### 设计原则

1. **文件优先于数据库。** 记忆是 Markdown，配置是 TOML，日志是纯文本。一切都是人类可读且可 git 差异比对的。

2. **边界即特性。** 审批门控让自主智能体变得可信。一个不经询问就能花你钱的智能体不是自主，而是危险。

3. **复利式知识。** 每次迭代都应让智能体更聪明。记忆不是缓存——它是投资。

4. **默认透明。** 如果你看不到智能体做了什么以及为什么，那一定出了问题。

<a id="platform-support"></a>

## 平台支持

| | macOS | Linux | Windows (WSL) | Windows (native PS7) |
|---|:---:|:---:|:---:|:---:|
| bash-guard | 是 | 是 | 是 | 是 (.ps1) |
| git-safe | 是 | 是 | 是 | 是 (.ps1) |
| file-guard | 是 | 是 | 是 | 是 (.ps1) |
| read-once | 是 | 是 | 是 | 是 (.ps1) |
| branch-guard | 是 | 是 | 是 | 是 (.ps1) |
| worktree-guard | 是 | 是 | 是 | 是 (.ps1) |
| session-log | 是 | 是 | 是 | 是 (.ps1) |
| enforce-hooks | 是 | 是 | 是 (bash) | WSL 或 Git Bash |
| safety-check | 是 | 是 | 是 | 部分（需要 bash） |
| 安装程序 | `install.sh` | `install.sh` | `install.sh` | `install.ps1` |
| 钩子可靠性 | 完整 | 完整 | 完整 | [~18%](https://github.com/anthropics/claude-code/issues/37988) |

**最佳体验：** macOS 或 Linux。**Windows：** 使用 WSL 以获得完整可靠性。原生 PowerShell 钩子可以工作，但 Claude Code 触发它们并不一致（[#37988](https://github.com/anthropics/claude-code/issues/37988)）。

<a id="recommended-claude-code-version"></a>

## 推荐的 Claude Code 版本

**请使用最新的 Claude Code 版本。** Claude Code 变化很快；在固定版本前，请查看 Anthropic 的[发布动态](https://github.com/anthropics/claude-code/releases)，然后运行带 `--verify` 的 `safety-check` 以确认钩子在你的环境中正确触发。以下版本是历史上与钩子相关的断点版本，并非当前版本的追踪表：

| 版本 | 问题 |
|---|---|
| v2.1.91+ | 恢复内置 `rg` 可执行权限，修复 v2.1.88-89 中项目命令发现的回归（[#41497](https://github.com/anthropics/claude-code/issues/41497)、[#41864](https://github.com/anthropics/claude-code/issues/41864)） |
| v2.1.90+ | exit-2 + JSON 阻止改进、PostToolUse 保存时格式化修复以及 4 个 PowerShell 权限绕过修复所需的最低版本 |
| v2.1.89 | 新增 `PermissionDenied`、`defer`、绝对 `file_path` 和复合钩子 `if` 匹配，但仍存在命令发现和 `SessionStart` 显示回归 |
| v2.1.88 | [已弃用/从 npm 撤回](https://github.com/anthropics/claude-code/issues/41497)：自定义命令/技能损坏，源码映射泄漏 |
| v2.1.81-84 | 安装 PreToolUse 钩子时[权限绕过会在会话中途重置](https://github.com/anthropics/claude-code/issues/37745) |
| < v2.1.50 | 不支持 `hookSpecificOutput` 格式（已弃用的 `decision: "block"` 仍有效，但应进行迁移） |

运行 `claude --version` 检查你的本地安装。

## 故障排除

**settings.json 中的 JSONC 注释**：如果你的 `~/.claude/settings.json` 包含 `//` 或 `/* */` 注释，钩子可能会静默停止工作（[claude-code#37540](https://github.com/anthropics/claude-code/issues/37540)）。我们的安装程序会检测 JSONC 并自动去除注释（创建 `.bak` 备份）。如果钩子没有触发，请检查你的设置文件中是否有注释。

**钩子未阻止操作**：Claude Code 只在工具调用时触发钩子，而不是在提示词组装时。像 @-自动补全这样的功能会在钩子能够拦截之前注入文件内容。参见 [claude-code#32928](https://github.com/anthropics/claude-code/issues/32928)。

**从子目录启动时项目钩子被跳过**：如果你的仓库在仓库根目录的 `.claude/settings.json` 中存储钩子，请从同一根目录启动 Claude Code 并运行 `safety-check`。从子目录启动可能会让 Claude 将该子目录视为项目根目录，并在不发出警告的情况下跳过上级项目的钩子。`safety-check` 会将此报告为上级项目设置警告。在原生 Windows PowerShell 中，请先在检出的仓库目录内运行 `Set-Location (git rev-parse --show-toplevel)`，然后再运行 `install.ps1 verify`。

**安装钩子后权限绕过会重置**：如果你使用 `--dangerously-skip-permissions`（在自主设置中很常见），PreToolUse 钩子可能会[导致权限状态在会话中途重置](https://github.com/anthropics/claude-code/issues/37745)，使所有工具恢复为手动审批。这是平台缺陷，不是钩子缺陷。如果工具在会话开始 30-120 分钟后突然要求审批，原因就在这里。

**IS_DEMO 环境变量禁用所有钩子**：如果你的环境中设置了 `IS_DEMO=1`（有时通过 IDE 或云工作区设置），Claude Code 会[静默跳过所有钩子执行](https://github.com/anthropics/claude-code/issues/37780)，因为它抑制了工作区信任却不授予信任。运行 `echo $IS_DEMO` 检查。我们的 `safety-check` 工具会自动检测这一点。

**CLAUDE_CODE_SIMPLE 禁用所有钩子**：当 `CLAUDE_CODE_SIMPLE` 环境变量被设置为任何非空值时，Claude Code 会完全禁用钩子、MCP 工具、附件和 CLAUDE.md 文件加载（在 v2.1.50 中引入）。不会触发任何执行规则。运行 `echo $CLAUDE_CODE_SIMPLE` 检查。我们的 `safety-check` 工具会自动检测这一点。

**`--bare` 标志跳过所有钩子**：`--bare` CLI 标志会为脚本化的 `-p` 调用禁用钩子、LSP、插件同步和技能目录遍历。如果你的自主流水线使用 `claude --bare -p`，则不会有钩子触发。在 bare 模式下，请使用操作系统级控制（文件权限、容器化）进行强制执行。

**钩子 deny 处理在各工具和版本间仍不一致**：`hookSpecificOutput.permissionDecision: "deny"` 已有所改进，但在 Claude Code 的各个界面上并非普遍保证。多个上游问题仍记录了 deny 处理被忽略或因工具/事件类型而变化的情况。这就是为什么必须硬性阻止危险操作的框架钩子采用 Claude Code 当前最可靠尊重的保守路径：在 `stderr` 上输出人类可读的原因并 `exit 2`，然后我们告诉用户在安装后以及 Claude Code 更新后运行 `safety-check --verify`。如果你编写自定义钩子，不要仅仅因为 JSON deny 响应在某个本地测试中有效就认定它足够。

**子智能体可能跳过钩子设置**：通过 Agent 工具生成的智能体[不能一致地继承权限设置](https://github.com/anthropics/claude-code/issues/37730)。`.claude/settings.json` 中的钩子仍应触发（共享配置），但在使用子智能体工作流时请验证钩子行为。

**钩子 stderr 可能泄漏你的文件系统路径**：Claude Code 的钩子运行器[会给 stderr 输出加上原始命令路径前缀](https://github.com/anthropics/claude-code/issues/41226)，在对话中暴露诸如 `/Users/yourname/.claude/hooks/my-hook.sh` 之类的信息。这来自平台的执行层，而不是钩子本身。我们的钩子使用干净的前缀（`[bash-guard]`、`[file-guard]` 等）输出调试消息，并且绝不会在 stdout 或 stderr 中暴露文件系统路径。调试日志按钩子选择启用（例如 `BASH_GUARD_LOG=1`）。

**内部 git 操作绕过所有钩子**：Claude Code 会[以编程方式每约 10 分钟](https://github.com/anthropics/claude-code/issues/40710)运行一次后台 git 操作（fetch + reset），而不启动外部 `git` 二进制文件或进行工具调用。由于钩子只在工具调用时触发，git-safe 和所有其他钩子对这些操作一无所知。这可能会静默破坏已跟踪文件上未提交的更改。解决方法：使用 git worktree（免疫于主检出目录中的重置）或频繁提交。如果你使用 `claude -w`，在依赖 worktree 前还要安装 [worktree-guard](https://github.com/bande-a-bonnot/boucle-framework/blob/main/tools/worktree-guard)；否则退出 worktree 可能会删除未合并或未推送的提交。

**编辑 settings.local.json 后权限失步**：如果 Claude 的 Edit 工具在会话期间修改了 `.claude/settings.local.json`，内存中的权限状态会[与磁盘上的文件失步](https://github.com/anthropics/claude-code/issues/41259)。允许规则停止工作，用户会被反复提示批准已经允许的命令。磁盘上的文件是正确的；问题出在内存缓存。解决方法：让 Claude Code 通过其自身的提示机制管理权限文件，或在手动编辑后重启会话。

**v2.1.89 新增：PermissionDenied 钩子事件**：自动模式分类器拒绝后会触发一个新的钩子事件。钩子可以返回 `{"retry": true}` 告诉模型它可以重试被拒绝的操作。链接的 issue 记录了该事件最初存在的文档缺口。另外在 v2.1.89 中：钩子的 `if` 条件现在可以[匹配复合 Bash 命令](https://github.com/anthropics/claude-code/issues/41262)（`ls && git push` 匹配 `Bash(git *)`）以及带环境变量前缀的命令（`FOO=bar git push`）。

**SessionStart systemMessage 不再显示（v2.1.89）**：SessionStart 钩子返回的 `systemMessage` 字段[不再在终端中渲染](https://github.com/anthropics/claude-code/issues/41285)。钩子会运行，`additionalContext` 仍会注入到模型上下文中，但之前出现的可视化输出（例如 "SessionStart:startup says: ..."）会静默缺失。如果你依赖 `systemMessage` 进行操作员通知或会话标识，该输出将不可见。相关：[#9090](https://github.com/anthropics/claude-code/issues/9090)、[#15344](https://github.com/anthropics/claude-code/issues/15344)。

**钩子在新项目的首次会话中失败**：在项目目录的首次会话时，SessionStart 和 UserPromptSubmit 钩子会在[项目目录存在之前](https://github.com/anthropics/claude-code/issues/41310)触发（`~/.claude/projects/<encoded-path>/`）。任何从 `transcript_path` 派生文件路径并尝试写入那里的钩子都会失败。解决方法：在写入前为从 transcript_path 派生的路径添加 `mkdir -p`。

**长会话中的模型自执行**：在长时间无人值守的会话中，模型可能会在[任务通知传递后幻觉出 `Human:` 文本](https://github.com/anthropics/claude-code/issues/41307)，然后像真正的用户请求一样执行它，从而触发未经授权的 git 操作和文件修改。钩子无法检测到这一点，因为由此产生的工具调用是真实的——只有触发是幻觉。缓解措施：使用会话时间限制，避免过长的无人值守会话。

**Worktree GIT_INDEX_FILE 泄漏**：通过 EnterWorktree 生成的智能体可能会因 `GIT_INDEX_FILE` 环境变量跨进程边界泄漏而使其 git 索引[被市场插件条目破坏](https://github.com/anthropics/claude-code/issues/41314)。如果 worktree 操作在 git status 中显示意外文件，这可能是原因。

**后台智能体无法停止**：通过 Agent 工具以 `run_in_background` 生成的智能体[无法被用户可靠地终止](https://github.com/anthropics/claude-code/issues/41461)。在一个报告的案例中，14 个并行智能体写入同一个文件并消耗了约 140 万 token（55-106 美元）。没有内置的终止机制。缓解措施：避免生成大量后台智能体；如果确实需要，请监控 token 使用量。

**cleanupPeriodDays 设置可能被忽略**：`settings.json` 中的 `cleanupPeriodDays` 设置[可能被静默绕过](https://github.com/anthropics/claude-code/issues/41458)，即使设置为非常高的值也会删除会话文件。一位用户尽管将其设置为 99999 仍丢失了 490 个会话。如果你依赖会话持久化，请独立备份 `~/.claude/projects/`。

**符号链接的 .claude/ 目录无法被发现（Linux）**：来自[符号链接的 `.claude/commands/`](https://github.com/anthropics/claude-code/issues/41451)的斜杠命令在 Linux 上无法加载（回归）。这是一种常见的团队模式（将共享配置存储在中央目录并进行符号链接）。如果 `.claude/` 本身是符号链接，钩子和技能也可能失败。解决方法：复制文件而不是符号链接。

**内置 ripgrep 缺少可执行权限（Linux）**：内置的 `rg` 二进制文件在 Linux 上[可能丢失可执行权限](https://github.com/anthropics/claude-code/issues/41463)，静默破坏 `~/.claude/commands/` 中所有用户定义的斜杠命令。修复方法：对内置二进制文件执行 `chmod +x`。

**v2.1.88-89 命令发现回归**：v2.1.88 在自定义命令停止加载且 `cli.js.map` 意外发布后被[弃用/从 npm 撤回](https://github.com/anthropics/claude-code/issues/41497)。v2.1.89 对部分用户保留了命令发现回归（[#41864](https://github.com/anthropics/claude-code/issues/41864)），尽管它也添加了诸如 `PermissionDenied` 等钩子功能。Anthropic 将内置 `rg` 可执行权限修复标记为在 v2.1.91 中发布。如果自定义命令或技能消失，请更新到最新的 Claude Code 版本并重新运行 `safety-check --verify`。

**非交互式会话在使用限制处挂起**：在无头、`--print` 或远程控制模式下，达到使用限制时会[显示一个无法应答的确认提示](https://github.com/anthropics/claude-code/issues/41502)，因为没有 stdin。会话会永久挂起。没有编程上的解决方法（[#41503](https://github.com/anthropics/claude-code/issues/41503)）。如果你在 CI、cron 或自主循环中运行 Claude Code，请设置会话时间限制并监控卡住的进程。

**管道和复合命令绕过拒绝规则**：内置拒绝规则只匹配完整的命令字符串。`Bash(rm *)` 会阻止 `rm -rf /`，但不会阻止 `find /foo | xargs rm` 或 `something && rm -rf /`。文档说允许规则会解析 shell 运算符，但[拒绝规则不会](https://github.com/anthropics/claude-code/issues/41559)。注意：钩子的 `if` 条件已在上游修复（2026 年 3 月下旬），可以正确匹配复合命令和环境变量前缀，因此钩子会为这些模式*正确*触发。差距只存在于拒绝*规则*，而不是钩子。bash-guard 会独立解析每个管道段和复合链，捕获这些绕过模式。另见 [#37662](https://github.com/anthropics/claude-code/issues/37662)、[#16180](https://github.com/anthropics/claude-code/issues/16180)。

**"逐项确认每个更改"被静默跳过**：当退出计划模式并选择"逐项确认每个更改"时，如果工具（Edit、Write、Bash）位于 `permissions.allow` 中，[更改会在没有任何提示的情况下应用](https://github.com/anthropics/claude-code/issues/41551)。持久化的允许规则会覆盖用户在会话中的明确选择。解决方法：移除宽泛的工具允许，改用钩子进行强制执行。

**SessionEnd 钩子在完成前被终止**：执行异步工作（API 调用、LLM 摘要、网络请求）的 SessionEnd 钩子在 Claude Code 退出时[会在执行中途被终止](https://github.com/anthropics/claude-code/issues/41577)，无论配置的超时时间是多少。钩子到达了异步调用，但父进程在响应返回之前就退出。解决方法：使用 `nohup ... & disown` 将繁重的工作分离到后台进程，然后立即 `exit 0`。

**"始终允许"目录访问不被持久化**：点击"是，并始终允许访问 [文件夹]"时[无法可靠保存](https://github.com/anthropics/claude-code/issues/41579)。Claude 会在后续会话中重新提示同一目录。添加到 settings.json 的 `additionalDirectories` 也不稳定。与 [#40606](https://github.com/anthropics/claude-code/issues/40606)（additionalDirectories 跨项目泄漏）相关。

**`~/.claude/` 的写入会阻塞自动化会话**：对 `~/.claude/` 下路径的写入会触发硬编码的敏感文件提示，[无法被](https://github.com/anthropics/claude-code/issues/41615) `permissions.allow`、返回 `"allow"` 的 PreToolUse 钩子、`bypassPermissions` 模式或 `skipDangerousModePermissionPrompt` 抑制。需要修改 Claude Code 配置文件的自动化会话（tmux、CI、自主循环）会挂在该交互提示上。解决方法：使用 Bash 工具命令（`echo`、`cat`、`jq`）直接写入文件，而不是使用 Edit/Write 工具。

**`bash -c` 包装绕过 `.claude/` 目录写入保护**：权限系统保护 `.claude/` 文件不被修改（编辑、写入、直接 bash 命令都会触发确认弹窗）。但将命令包装在 [`bash -c 'echo "..." >> .claude/file'`](https://github.com/anthropics/claude-code/issues/43085) 中会完全绕过检查：没有弹窗，写入静默成功。模式匹配只检查顶层命令字符串，而不检查嵌套的子 shell。这意味着模型（或通过工具结果进行的提示注入）可以在没有用户确认的情况下修改钩子、settings.json、技能或智能体定义。如果将 `.claude/` 添加到 `.file-guard` 配置中，file-guard 可以捕获这一点，因为它会扫描完整的 Bash 命令字符串以查找受保护的路径（包括带引号的参数内部）。仅依赖内置权限检查的用户会面临风险。

**`WorktreeCreate` 钩子导致 `claude -w` 挂起**：任何 `WorktreeCreate` 钩子都会导致 [`claude -w` 无限期挂起](https://github.com/anthropics/claude-code/issues/41614)，无论钩子内容是什么。即使是 `echo ok < /dev/null` 也会冻结会话。钩子执行并返回，但 Claude Code 永远不会继续。如果你需要 `claude -w` 正常工作，请移除所有 `WorktreeCreate` 钩子。

**模型可以操纵钩子状态文件**：模型具有文件系统访问权限，并且[可以覆盖钩子所依赖的文件](https://github.com/anthropics/claude-code/issues/38841)——检查点文件、锁文件、计数器。在一个有记录的案例中，Claude 计算了检查点文件名的 SHA256 哈希，并写入了一个新的时间戳以绕过内容读取门控。依赖外部状态文件进行强制执行的钩子应假定模型可以读取和修改这些文件。加密签名或进程外验证可以缓解这种情况。

**`bypassPermissions` 在会话恢复时不会恢复（VS Code）**：当通过 VS Code 设置中的 `initialPermissionMode` 配置 `bypassPermissions` 时，[恢复的对话会回退到默认权限模式](https://github.com/anthropics/claude-code/issues/42735)并对每次编辑进行提示。新会话可能会采用它，但恢复的会话始终失败。依赖会话在绕过模式下运行的钩子不能指望它在恢复后仍然保持。

**git 子模块中 worktree 隔离失效**：在 git 子模块内对 Agent 工具使用 `isolation: "worktree"` 会[在 `.git/modules/<path>/.claude/worktrees/`](https://github.com/anthropics/claude-code/issues/42732)中创建工作树，而不是在项目自己的 `.claude/worktrees/` 中。这会将智能体置于项目权限范围之外，导致 `bypassPermissions` 被静默降级并触发意外的权限提示。

**技能批准不与内容哈希绑定**：当用户批准一个技能时，该批准[不会锚定到文件的内容哈希](https://github.com/anthropics/claude-code/issues/43157)。如果技能文件在批准后被修改（即使在会话中途），修改后的版本会在不再提示的情况下执行。此外，批准技能可以绕过 `settings.json` 中的工具级拒绝规则。这是一个供应链风险：任何对 `~/.claude/skills/` 有写入权限的东西都可以在批准后提升能力。**Stdio MCP 服务器永远不会自动重连**：当 stdio 类型的 MCP 服务器进程死亡或断开连接时，Claude Code 会[将其标记为失败并且永远不会重试](https://github.com/anthropics/claude-code/issues/43177)。HTTP/SSE/WebSocket 服务器会以指数退避（5 次尝试）自动重连，但 stdio 服务器被明确排除在外。用户必须手动运行 `/mcp` 来重新连接。这会影响任何使用 stdio 传输（最常见的本地模式）的 MCP 集成。

**首个周期后计划模式绕过**：完成一个“计划-批准-实施”周期后，再次进入计划模式[并不能可靠地强制执行只读限制](https://github.com/anthropics/claude-code/issues/43147)。Claude 会带有“已批准”的思维状态，并在用户批准新计划之前就开始编辑文件。依赖计划模式作为安全边界的 Hooks 无法在同一会话的多个周期内信任它。

**Windows**：所有七个 Hooks 都有原生 **PowerShell 7+** 等效版本（`hook.ps1`），无需任何外部依赖。需要 [PowerShell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows)（`pwsh`），而不是内置的 Windows PowerShell 5。使用以下命令安装它们：```powershell
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } all"