Hooks 与确定性自动化

它替你干掉什么：把「每次都要做」从模型的自由意志里拿走

第一条立刻能跑：改完自动 format

官方指南里逐字给了这段，放进项目根的 .claude/settings.json，Claude 每次用 Edit / Write 改完文件就自动跑 Prettier：

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

事件数据是一段 JSON 打到 stdin，所以官方所有 Bash 示例都用 jq 取字段（brew install jq / apt-get install jq）。什么时候别写这条：如果文件也可能被 Bash 命令改写，Edit|Write 这个 matcher 就漏了——官方让你改用 FileChanged 钩子盯具体文件名。

第二条：把不该动的文件挡住

写进 .claude/hooks/protect-files.sh（记得 chmod +x），在 PreToolUse 上注册成 "$CLAUDE_PROJECT_DIR"/.claude/hooks/protect-files.sh：

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
# 命中就 exit 2：动作被拦下，stderr 作为反馈回给模型
case "$FILE_PATH" in
  *.env|*/secrets/*) echo "该路径受保护，禁止写入" >&2; exit 2 ;;
esac
exit 0

第三条：不想自己写，装官方那个

/plugin install security-guidance@claude-plugins-official
# 提示 marketplace 找不到就先加：
/plugin marketplace add anthropics/claude-plugins-official

security-guidance 是官方唯一一个把自己整个建在 hooks 上的插件，装完什么都不用喊。它替你干掉的是：注入、不安全反序列化、dangerouslySetInnerHTML 这类问题从「等 PR review 抓」提前到「写下去的那一刻」。什么时候别装：它每个改了文件的 turn 会多一次模型调用、每次 commit 再多一次 agentic 审查（默认 Claude Opus 4.7），这是真金白银；不在 git 仓库里时后两层直接跳过；cloud session 不加载 plugin。嫌贵可以只留免费那层——ENABLE_CODE_SECURITY_REVIEW=0 关掉全部模型审查，保留纯字符串匹配的逐次编辑检查。

机制：33 个事件 × 5 种类型 × 3 档退出码

事件：不只是 Pre/Post ToolUse

官方 reference 的事件表现在列了 33 个。社区文章里常见的「13 个生命周期事件」是旧的。几个容易被忽略但很好用的：

类型：5 种，后两种是「反确定性」的

• command — 跑 shell 命令。默认超时 10 分钟。
• http — POST 到一个 endpoint，body 里返回同样的 JSON。header 里的 $VAR 只解析 allowedEnvVars 列出的那些。
• mcp_tool — 直接调某个 MCP server 的工具。
• prompt — 把事件数据丢给一个模型（默认 Haiku）判 {"ok": true/false, "reason": "..."}。超时 30 秒。
• agent — 起一个 subagent，能读文件、跑命令再判。超时 60 秒、最多 50 轮工具调用。官方标记为实验性，生产工作流建议用 command。

退出码：只有三档

0 = 成功，stdout 按 JSON 解析（解析不了就当纯文本，部分事件会注入 Claude 上下文）。2 = 拦截，stderr 是拦截理由；能被拦的事件是有限几个（PreToolUse、UserPromptSubmit、Stop、SubagentStop、PreModelSwitch 等），SessionStart 这类拦不住，exit 2 只是把 stderr 显示给你。其余 = 非阻塞错误，动作照常进行，transcript 里出现一条 hook error。

配置放哪，决定了谁受管

/hooks 命令可以按事件浏览全部已配置钩子，但它只读——增删改要直接编辑 JSON。全局关闭是 "disableAllHooks": true；管理员那边还有个 allowManagedHooksOnly，能把你自己的钩子全部禁掉只留托管的。

抄一份真实的注册表

security-guidance 把自己拆成五条注册，这张表值得当模板背下来（源码在 GitHub 上，目录里就是 .claude-plugin/ + hooks/ + tests/）：

三件事可以直接学：贵的放后面（免费的字符串匹配放逐次编辑，花钱的模型审查放 Stop 和 commit）；基线在前、判定在后（UserPromptSubmit 存快照，Stop 才 diff）；审查者不是写代码那个实例（另起一次调用、全新 context）。

真实用法与边界：六个可装可读的条目

① GowayLee/cchooks · Python SDK（132★）

pip install cchooks   # 或 uv add cchooks

from cchooks import create_context, PreToolUseContext
c = create_context()
assert isinstance(c, PreToolUseContext)
if c.tool_name == "Write" and ".env" in c.tool_input.get("file_path", ""):
    c.output.exit_deny("Nope! .env files are protected")
else:
    c.output.exit_success()

替你干掉：手写 json.load(sys.stdin) 和记退出码语义，事件类型是带类型的 context 对象。覆盖 9 种事件。什么时候别装：你的钩子就一行 jq | xargs——为它引一个包不划算；它那 9 种事件也远少于官方现在的 33 种，冷门事件得自己裸写。（据 GitHub 仓库页，2026-09）

② syou6162/cchook · 把 JSON 换成 YAML（34★）

go install github.com/syou6162/cchook@latest

PostToolUse:
  - matcher: "Write|Edit"
    conditions:
      - type: file_extension
        value: ".go"
    actions:
      - type: command
        command: "gofmt -w {.tool_input.file_path}"

替你干掉：settings.json 里那坨转义地狱，条件（按扩展名、按模式）用声明式写，带 dry-run。什么时候别装：团队要共享配置时，多一层非官方格式就多一层「新人看不懂」；星数也说明它还是个小众工具。（据 GitHub 仓库页，2026-09）

③ johnlindquist/claude-hooks · TypeScript（393★）

npx claude-hooks   # 生成 .claude/hooks/index.ts，执行需要 Bun

替你干掉：payload 的类型提示与自动补全，全部事件写在一个 index.ts 里分发。什么时候别装：它把运行时依赖绑到了 Bun——CI 或队友机器上没有 Bun，钩子就静默失败（而 hook 失败默认不阻塞，你不开 debug 根本不知道）。（据 GitHub 仓库页，2026-09）

④ disler/claude-code-hooks-mastery · 教学仓（3.9k★）

这个仓用 Astral uv 的单文件 Python 脚本把当时的每个事件都实现了一遍，含 PreCompact 前备份 transcript、拦截 subagent 完成这类花活。替你干掉：「这个事件的 JSON 长什么样」——照着读比翻文档快。什么时候别装：它是范本不是产品，README 自述覆盖 13 个事件，而官方 reference 现在是 33 个；整个 .claude 目录拷进你的项目会连它的 output styles、status line 一起带进来。（据 GitHub 仓库页，2026-09）

⑤ disler/claude-code-hooks-multi-agent-observability · 看板（1.5k★）

它把所有事件通过 HTTP POST 打到一个 Bun 服务器，再 WebSocket 推到 Vue 客户端，多个并发 agent 的流向实时可见。替你干掉：「五个 agent 同时在跑，谁卡住了」这种睁眼瞎。什么时候别装：要 uv + Bun + 一个常驻服务器，单人单会话纯属过度工程；官方 http 类型钩子现在原生支持 POST 到 endpoint，自己接个日志服务可能比搬这套轻。（据 GitHub 仓库页，2026-09）

⑥ pre-commit/pre-commit · 不在 Claude 里的那一半（15.6k★）

pre-commit（pip install pre-commit → pre-commit install，配置写在 .pre-commit-config.yaml）管的是 git 提交这一刻，和 Claude 的钩子不是替代关系是接力关系：Claude hook 只覆盖 Claude 干的事，你自己在终端敲的 commit 它一概看不见（官方明说 ! shell escape 里的 commit 也不算）。什么时候别装：只有你一个人、且所有改动都过 Claude——那多一层会重复跑同样的 linter。

三条判据，用来在上面这些之间取舍

1. 这件事需要判断吗？不需要 → command 钩子。需要但只看事件数据就能判 → prompt。要读代码才能判 → agent（且知道它是实验性的）。
2. 漏一次的代价是什么？代价只是难看（没格式化）→ PostToolUse 补。代价是出事（写了 secret）→ PreToolUse + exit 2 拦在前面，因为 PostToolUse 撤不回来。
3. 只管 Claude 还是管所有人？只管 Claude → Claude 钩子。要管住所有提交 → pre-commit 或 CI。两边都要 → 两边都写，且让 Claude 侧调用同一个脚本，别维护两份规则。

代价与替代品：钩子会把不确定性从前门赶出去，再从后门请回来

五笔账

• 没有沙箱。官方原话：A hook can read files, make network requests, modify your environment, and run arbitrary commands. 建议是「像对待 shell alias 和 dotfiles 一样对待它」——只启用你看懂的。危险的是钩子藏得住：plugin 的 hooks/hooks.json、skill frontmatter、subagent frontmatter 都能带钩子，装一个插件等于接受它注册的一切。
• 失败是静默的。非 0 非 2 的退出码只算非阻塞错误，动作照常做完。要看全貌得 claude --debug 或会话里 /debug。
• if 是尽力而为，不是安全边界。if: "Bash(rm *)" 这种过滤在 Claude Code 判不出命令结构时会照跑不误；官方直说：硬性的 allow/deny 要用权限系统，不是 hook。
• matcher 的覆盖面是假的。Edit|Write 抓不到 Bash 写的文件。要真全覆盖，官方给三条路：Stop 钩子每轮扫一次 git status --porcelain；或同时匹配 Bash|PowerShell；或用 FileChanged 盯文件本身。
• 时间预算。SessionEnd 的全部钩子共享 1.5 秒（显式写更长的 timeout 才会抬到最多 60 秒）——想在那儿做清理、上传日志的，先看这条。

不写 hook，你还能怎么办

1. 权限系统。要的是「绝对不许碰」而不是「碰了记一笔」——用 allow/deny 规则，那才是硬边界。
2. pre-commit / CI。要管的是所有人的提交而不是 Claude 的编辑，钩子挂错层了。
3. CLAUDE.md 或 skill。规则本身需要理解和变通（「新代码尽量写测试」），钉死反而变成噪音——每次都触发的告警等于没有告警。
4. 什么都不做。一件事一个月发生一次，写钩子的时间比手动做十年还长。