Claude Code hooks：事件、示例与工作原理

Claude Code hook 事件

官方参考文档列出了 30 多个事件，下面是大多数 hook 会用到的几个；matcher 可以把 hook 限定在特定的工具、文件或来源上。

hook 配置在哪里

Claude Code hook 示例，一步一步来

把每段配置放到设置文件的 hooks 键下；如果文件里已经有 hooks 对象，就把事件作为同级的键加进去，不要整个替换。运行 /hooks 确认 Claude Code 已经加载。你也可以直接让 Claude 帮你写 hook。

1. Claude 需要你时收到桌面通知

   在 ~/.claude/settings.json 里加一个 Notification hook。这里在 macOS 上用的是 osascript；Linux 上用 notify-send，Windows 上用 PowerShell。

   {
     "hooks": {
       "Notification": [
         {
           "matcher": "",
           "hooks": [
             {
               "type": "command",
               "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
             }
           ]
         }
       ]
     }
   }

2. 自动格式化 Claude 编辑的每个文件

   一个匹配 Edit|Write 的 PostToolUse hook，用 jq 从 stdin 的 JSON 中读出被编辑文件的路径，再对它运行 Prettier。把它放进 .claude/settings.json，整个团队就都能用上。

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

3. 拦截危险命令

   一个针对 Bash 的 PreToolUse hook 运行这个脚本。退出码 2 会拦截这次调用，写到 stderr 的内容会作为反馈交给 Claude，让它调整方向。退出码 0 表示不做决定，照常走权限检查。

   #!/bin/bash
   # .claude/hooks/block-drop-table.sh，作为 Bash 的 PreToolUse hook 运行
   INPUT=$(cat)
   COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
   
   if echo "$COMMAND" | grep -q "drop table"; then
     echo "Blocked: dropping tables is not allowed" >&2  # 会成为给 Claude 的反馈
     exit 2                                               # 2 = 阻止该操作
   fi
   
   exit 0  # 不做决定：照常走权限流程

4. 让 Claude 一直干到任务完成

   一个 prompt 类型的 Stop hook 会问模型是否全部完成。如果回答是 ok: false，Claude 会以 reason 作为下一条指令继续工作。这就是经典的 Stop hook 示例。

   {
     "hooks": {
       "Stop": [
         {
           "hooks": [
             {
               "type": "prompt",
               "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
             }
           ]
         }
       ]
     }
   }

来源：Claude Code 文档，Automate actions with hooks

hook 如何决定接下来发生什么

• 输入：每个 hook 都会从 stdin 收到 JSON 格式的事件，比如工具名和 tool_input、会话 ID 以及 cwd。
• 退出码 0：没有异议。对少数事件（如 SessionStart 和 UserPromptSubmit），普通的 stdout 会被加入 Claude 的上下文。
• 退出码 2：在事件允许的情况下拦截。stderr 会根据事件的不同，返回给 Claude 或显示给你。
• stdout 输出 JSON：更精细的控制，比如带权限决定的 hookSpecificOutput、用来改写工具输入的 updatedInput，或 additionalContext。
• 其他退出码：通常视为不拦截的错误，除非 hook 设置了 onFailure: "block"。
• 同一事件下匹配到的多个 hook 会并行运行。

command、prompt、agent 和 HTTP 类型的 hook

hook、skill 与 CLAUDE.md 的区别，以及其他注意事项

• CLAUDE.md 和 skill 是 Claude 通常会遵守的指令；hook 则每次都会运行。任何绝不能跳过的事情都应该放进 hook。
• PostToolUse 无法撤销已经执行的操作；要阻止它，用 PreToolUse。
• Stop 在 Claude 每次结束回复时都会触发，不只是在任务结束时，而且用户中断时不会触发。
• hook 本身不能运行斜杠命令，也不能调用工具；它们只能通过退出码、stdout、stderr 或 JSON 回传信息。
• "disableAllHooks": true 会关闭 hook；但托管 hook 仍会运行，除非托管设置也把它们关掉。
• hook 只作用于你本地的 Claude Code 环境。覆盖所有 Claude 产品的组织级检查是另一项功能：Claude inference hooks。
• 用 PreToolUse hook 过滤测试输出，也是减少 token 用量最有效的方法之一。

hook 让 Claude Code 守规矩，Crewmark 让它一直干活。

hook 是让无人值守的 agent 变得安全的关键：格式化、测试和防护规则每次都会运行。Crewmark 把 Claude Code、Codex、DeepSeek Harness 或 OpenCode 会话变成有岗位、目标和工作时间的 AI 员工，并按心跳唤醒它，从看板上接手下一个 issue，同时加载你项目里的 hook。

1. 把 hook 提交到仓库

   .claude/settings.json 里的 hook 会像在你的会话中一样，在员工的会话中加载，所以它的编辑会被格式化，有风险的命令会被拦截。

2. 让心跳启动工作

   在工作时间内，员工每 15、30 或 60 分钟在同一个对话里醒来一次；参见如何让 Claude Code 主动工作。

3. 只回答需要你的问题

   它会在自己的 issue 下评论，需要你拍板时给你发消息。阅读什么是 AI 员工。

Claude Code hooks 常见问题