Hooks：把规矩写成必然发生的动作

你在 CLAUDE.md 里写了「每次改完代码都要跑 Prettier」，Claude 大多数时候会照做，但总有那么一两次忘了，提交时才发现格式全乱。你又写了「绝对不要 force push」，可它到底会不会遵守，你心里没底。

问题在于：CLAUDE.md 是建议，模型会尽量遵守，但不保证。Hooks 是规则：在 Claude Code 生命周期的固定时刻，由程序（而不是模型）去执行你写好的命令，每次必然发生。这一课就把「希望它记得」变成「一定会发生」。

Hook 由三层组成

一个 Hook 配置有三层嵌套：

1. 事件（hook event）：什么时刻触发，比如「工具调用之前」PreToolUse、「Claude 回复完毕」Stop；
2. 匹配器（matcher）：在这个事件里再筛一道，比如「只针对 Bash 工具」；
3. 处理器（hook handler）：真正执行的东西。最常用的是 command（跑一条 shell 命令），另外还有 http（把事件 POST 到一个地址）、mcp_tool（调用某个 MCP 工具）、prompt（让模型做一次判断）和仍属实验性质的 agent。

事件触发时，Claude Code 会把这次事件的上下文以 JSON 形式通过 stdin 交给你的命令，比如 PreToolUse 会收到 tool_name、tool_input、cwd、session_id 等字段。你的脚本读它、做判断、用退出码或输出告诉 Claude Code 结果。

生命周期事件一览

官方当前列出了三十多个事件，下面按用途分组。能阻止动作的事件意味着你的 Hook 可以说「不行」：

日常最常用的是 PreToolUse（拦截）、PostToolUse（善后）、Stop 和 Notification（提醒），先把这四个用熟。事件清单还在持续增加，用到冷门事件时以官方参考为准。

配置写在哪、怎么写

Hooks 写在 settings 文件的 hooks 字段里。放在哪个文件，决定了它的作用范围：

此外，插件、Skill 和子智能体的 frontmatter 里也能定义 Hooks，组织管理员还能下发托管策略。多个层级的 Hooks 是叠加的，不会互相覆盖。

matcher 的规则：只含字母、数字、下划线、| 这类字符时按精确名称匹配，所以 Bash 只匹配 Bash 工具，Edit|Write 匹配两者之一；含有其他字符时按正则匹配，比如 mcp__github__.* 匹配 GitHub 服务器的所有工具。matcher 区分大小写，写成 bash 不会触发。"*"、空字符串或不写，都表示全部匹配。

想更精细，可以在处理器上加 if 字段，它用和权限规则一样的语法同时匹配工具名和参数，比如 "Bash(git push *)" 只在执行 git push 时才运行脚本，省得每条命令都启动一次。

配完后在会话里输入 /hooks，可以看到一份只读清单，标明每个 Hook 来自哪个文件。

退出码与输出控制

你的脚本怎么「回话」，决定了 Hook 的效果：

最大的坑就在第三行：Unix 习惯用 exit 1 表示失败，但在 Hooks 里 exit 1 拦不住任何东西。要拦截，必须 exit 2。

需要更细的控制时，退出 0 并在 stdout 打印一个 JSON 对象。常用字段：

• continue: false 加 stopReason：让 Claude 整个停下来；
• systemMessage：给你（用户）看的提示；
• 顶层 decision: "block" 加 reason：用于 Stop、PostToolUse 等事件，比如让 Stop 不许结束、继续去跑测试；
• hookSpecificOutput：事件专属字段，必须带 hookEventName。PreToolUse 用其中的 permissionDecision（allow / deny / ask / defer）决定放行、拒绝还是交给你确认，用 additionalContext 给 Claude 补充信息。

JSON 前面混进任何别的文字（比如你的 .zshrc 里无条件 echo 了一句欢迎语），整段就会被当成普通文本而失效。

三个实用 Hook

下面三个例子都假设你装了 jq（macOS 用 brew install jq），脚本放在 .claude/hooks/ 下，并且执行过 chmod +x。

1. 编辑后自动格式化（项目级）

#!/bin/bash
# .claude/hooks/format.sh：Claude 写入或编辑文件后自动格式化
FILE=$(jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0
PRETTIER="$CLAUDE_PROJECT_DIR/node_modules/.bin/prettier"
case "$FILE" in
  *.ts|*.tsx|*.js|*.vue|*.css|*.json)
    [ -x "$PRETTIER" ] && "$PRETTIER" --write "$FILE" >/dev/null 2>&1 ;;
  *.py)
    command -v ruff >/dev/null && ruff format "$FILE" >/dev/null 2>&1 ;;
esac
exit 0

2. 拦截危险命令（项目级）

#!/bin/bash
# .claude/hooks/guard-bash.sh：在 Bash 命令执行前检查
CMD=$(jq -r '.tool_input.command // empty')
if echo "$CMD" | grep -Eiq 'rm -rf /|git push (-f|--force)|git reset --hard|drop (table|database)'; then
  echo "已拦截高危命令：$CMD。如确有需要，请让用户在终端里手动执行。" >&2
  exit 2
fi
if echo "$CMD" | grep -q '^git push'; then
  jq -n '{hookSpecificOutput: {hookEventName: "PreToolUse",
    permissionDecision: "ask", permissionDecisionReason: "推送代码前请人工确认"}}'
fi
exit 0

这个脚本演示了两种回话方式：高危命令直接 exit 2 拦死，普通 git push 则用 JSON 的 ask 交给你确认。

把两个脚本注册到 .claude/settings.json（这里用了 args: [] 的 exec 形式，直接启动脚本，不经过 shell，路径里有空格也不怕）：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format.sh", "args": [], "timeout": 30 }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-bash.sh", "args": [] }
        ]
      }
    ]
  }
}

3. 完成时桌面通知（个人级）

通知是个人偏好，放进 ~/.claude/settings.json。Stop 在 Claude 每次回复完时触发，Notification 在它等你批准权限（permission_prompt）或闲置等你输入（idle_prompt）时触发：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "osascript -e 'display notification \"这一轮干完了，回来看看\" with title \"Claude Code\"'" }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          { "type": "command", "command": "osascript -e 'display notification \"在等你拍板\" with title \"Claude Code\"'" }
        ]
      }
    ]
  }
}

Linux 把 osascript ... 换成 notify-send 'Claude Code' '这一轮干完了'。macOS 上如果通知不出现，多半是「脚本编辑器」没有通知权限：先在终端运行一次 osascript -e 'display notification "test"'，再到「系统设置 → 通知」里找到「脚本编辑器」打开允许。

> 帮我把本地分支强制推到远程，覆盖掉同事的提交
⏺ Bash git push --force origin main
  PreToolUse:Bash hook error: [...guard-bash.sh]: 已拦截高危命令：git push --force origin main。
  如确有需要，请让用户在终端里手动执行。
⏺ 这个操作被项目的安全规则拦下了。强制推送会覆盖同事的提交，
  建议先 git pull --rebase 合并远程改动，再正常推送。需要我这样做吗？
# 拦截理由会反馈给 Claude，它会据此换一种做法

常见坑

• Hook 没触发：先看 /hooks 里有没有它；再检查 matcher 大小写、事件选对没有（改文件前后分别是 Pre 和 Post）、脚本有没有执行权限。手动测试可以直接喂一段 JSON：echo '{"tool_input":{"command":"git push -f"}}' | .claude/hooks/guard-bash.sh; echo $?。
• Stop Hook 死循环：用 decision: "block" 让 Claude 继续干活时，要读输入里的 stop_hook_active，为 true 时直接 exit 0 放行。官方也设了上限，连续拦截 8 次后会强制结束这一轮。
• 把 Hook 当唯一防线：if 和字符串匹配都是尽力而为，rm -rf 换个写法就可能绕过。真正的硬性禁止交给权限规则的 deny（见第 3 课），Hook 作为第二道防线。好消息是：PreToolUse 返回的 deny 在任何权限模式下都有效，包括 bypassPermissions。
• Hook 以你的身份运行：它能做你在终端里能做的一切。克隆陌生仓库时，先看一眼 .claude/settings.json 里的 hooks 再信任这个目录。

让 Claude 帮你写 Hook

手写 JSON 容易漏逗号。你可以把需求描述清楚，让 Claude 来写，再自己审一遍：