Claude Code 钩子，真正执行你的规则。7 个独立钩子，外加用于 CLAUDE.md 策略的 enforce-hooks、审计工具、1,900+ 项测试，以及一个带严重性评级和解决方法的可搜索 Claude Code 差距语料库。
快速链接： 检查你的设置 · 安装钩子 · 已知限制 · JSON 导出 · 快速入门 · 分类 · 更新检查清单 · 安全支持证据 · 支持示例 · 只读审计 · 独立钩子 · 平台支持 · 推荐的 Claude Code 版本 · 故障排除 · Boucle Framework (可选，适用于自主代理)
Claude Code 的 CLAUDE.md 规则是可读但未强制执行 — 它们在会话开始时生效，并随着上下文增长而退化。其权限系统存在已知缺陷 — 通配符不匹配复合命令，拒绝规则不检查管道段且可能被多行注释绕过。这些钩子强制执行文本规则和权限无法实现的边界。
当钩子阻止危险命令时会发生什么：``` Claude tries: rm -rf ~/projects bash-guard: bash-guard: rm -rf targeting a critical system path. This would cause irreversible data loss. Claude sees: ⚠ Hook blocked this action. Suggesting safer alternative...
无提示，没有“你确定吗”对话框。该命令永远不会运行。
<a id="check-your-setup"></a>
**检查你当前的设置：**```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash
从启动 Claude Code 的同一项目根目录运行此命令。项目钩子
从当前目录解析，因此在子目录中启动可能会错过仓库根目录下的
.claude/settings.json。如果你已经在某个 git checkout 目录内：```sh
cd "$(git rev-parse --show-toplevel)"
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash
为你的 Claude Code 安全配置打分（A 到 F），并针对每个缺口显示一行修复方案。添加 `--verify` 可向每个钩子发送测试载荷，并确认它们确实能阻止：```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify
对于 CI 或脚本化工作站检查，当验证发现
FAIL-OPEN 钩子、损坏的钩子文件、跳过的 PreToolUse 检查、没有钩子，或
没有负载检查时失败：```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify --strict
使用[脚本化检查指南](https://github.com/bande-a-bonnot/boucle-framework/blob/main/tools/safety-check/CI.md)了解GitHub Actions、
开发者工作站检查、退出代码以及CI能证明的局限性。
检查挂钩安装、挂钩健康状态（缺失/不可执行脚本）、实时验证（向bash-guard发送`rm -rf /`、向git-safe发送`git push --force`等并确认它们被阻止）、enforce-hooks和CLAUDE.md `@enforced`规则、环境问题（IS_DEMO、JSONC设置、jq/python3依赖、Windows挂钩可靠性）以及已知的CLI版本回归。扫描用户级（`~/.claude/settings.json`）和项目级（`.claude/settings.json`）设置，并提供挂钩清单，显示自定义/第三方挂钩以及框架挂钩。摘要统计了8个框架挂钩槽位，因为它包含`enforce-hooks`策略挂钩；`install.sh all`安装下面列出的7个独立挂钩。当配置了没有bash-guard的拒绝规则时也会发出警告，因为拒绝模式可能[被复合命令和多行脚本绕过](https://github.com/anthropics/claude-code/issues/38119)。审计无需安装挂钩。由数百个测试覆盖。
如需从审计到已验证挂钩的10分钟路径，请参阅[安全检查快速入门](https://github.com/bande-a-bonnot/boucle-framework/blob/main/tools/safety-check/QUICKSTART.md)。
如果需要寻求帮助，请使用[安全支持证据指南](https://github.com/bande-a-bonnot/boucle-framework/blob/main/tools/safety-check/SUPPORT_EVIDENCE.md)
分享摘要块，而不会暴露私有设置或机密。要
仅打印该有界公共块，请运行：```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify --summary-only
有关安全公开报告和应避免的不安全片段的示例，请参阅 安全支持示例。
如需了解上游 Claude Code 钩子与权限缺口，请使用 可搜索的限制页面， 机器可读的 JSON 导出 或 Atom 订阅源。
macOS / Linux 要求： 需要 bash、python3 和 jq。安装程序使用
python3 管理 Claude Code 的 settings.json，safety-check 使用 python3 进行
审计，大多数独立的 shell 钩子使用 jq 解析 Claude Code 钩子
载荷。
从基本组件开始 (bash-guard + git-safe + file-guard)：```sh curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- recommended
这三个钩子构成了每个 Claude Code 用户都应具备的安全网：阻止危险命令，防止破坏性 git 操作，以及保护敏感文件。安装后，使用上面的 `--verify` 运行安全检查，以确认每个钩子都能阻止其应阻止的内容。
**如果安装成功但钩子未阻止任何操作：**
- 首先在 macOS/Linux 上运行 `install.sh check --verify --strict`（在原生 Windows 上运行 `install.ps1 verify`）。安装干净并不能证明钩子已生效。
- 接下来运行 `install.sh doctor`（Windows 上运行 `install.ps1 doctor`）。它会捕获缺失文件、错误权限、`settings.json` 中的 JSONC 以及其他静默放行（fail-open）状态。
- 在 Windows 上，请使用 PowerShell 7（`pwsh`），而不是 Windows PowerShell 5。
- 如果你编写自定义拒绝钩子，对于硬阻止请优先使用 `stderr` + `exit 2`。JSON 的 `permissionDecision: "deny"` 在 Claude Code 各界面中仍不一致。
**一次性安装所有钩子：**```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- all
Windows（PowerShell 7+） — 原生 PS1 钩子，无需 bash 或 jq。需要 PowerShell 7（pwsh），而非内置的 Windows PowerShell 5。从相同的推荐安全设置开始：```powershell
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } recommended"
或者一次性安装所有独立钩子：```powershell
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } all"
管理钩子：```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- list
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- verify
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- upgrade
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- uninstall read-once
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- uninstall all
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- backup
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- restore
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- check
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- check --verify --summary-only
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- check --verify --strict
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- doctor