整理自 Claude Code 官方 Hooks 参考。原文是逐字段罗列的字典式文档，这里压缩成”什么时候用什么、怎么决定”的速查笔记。第一次配置 hook 前推荐先看 使用 hooks 自动化工作流 指南。

Claude Code Hooks 笔记

Hooks 是挂在 Claude Code 生命周期事件上的回调：可以跑 shell 命令、HTTP 请求、调用 MCP 工具、或让 LLM 帮判断。本质是”事件 → 过滤 → 副作用/决定”的三段式管道。

按触发频率分三档：

• 每个会话一次：SessionStart、SessionEnd、Setup、InstructionsLoaded
• 每轮对话一次：UserPromptSubmit、UserPromptExpansion、Stop、StopFailure、PreCompact、PostCompact
• 代理循环内每个工具调用：PreToolUse、PostToolUse、PostToolUseFailure、PostToolBatch、PermissionRequest、PermissionDenied、SubagentStart、SubagentStop、TaskCreated、TaskCompleted、Notification、CwdChanged、FileChanged、ConfigChange、WorktreeCreate、WorktreeRemove、MessageDisplay、Elicitation、ElicitationResult

另外有些事件是异步独立触发：TeammateIdle（agent team 队友闲置）、ConfigChange、CwdChanged、FileChanged、WorktreeCreate/Remove、Notification。

生命周期全景

上图里几个要点：

• Setup（可选）→ SessionStart → 每轮循环（UserPromptSubmit → Agentic Loop → Stop / StopFailure）→ SessionEnd
• Agentic Loop 里嵌套 PreToolUse → PermissionRequest → 工具执行 → PostToolUse / PostToolUseFailure → PostToolBatch
• Subagent 循环是平行的：SubagentStart / SubagentStop、TaskCreated / TaskCompleted
• 灰色虚线的事件（Notification、ConfigChange、WorktreeCreate 等）是异步副作用，不在主路径上
• Elicitation / ElicitationResult 嵌在 MCP 工具执行里
• MessageDisplay 是只读显示事件，不影响 Claude 行为

解析流程

一个 hook 要真正跑起来，三层过滤缺一不可：

1. 事件触发：Claude Code 决定发事件（如要执行 Bash）
2. 匹配器检查：matcher 字段过滤事件（如只对 Bash 工具）
3. if 条件检查：if 用权限规则语法再过滤一次（如 Bash(rm *)）
4. 执行 handler：从 stdin 收 JSON，决定如何回应

下面这个例子同时演示了三层结构 + 通过 JSON permissionDecision: "deny" 阻止调用：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

handler 通过退出码和 stdout 表达决定（详见 决定控制）。

配置位置

临时禁用所有 hook：在任意 settings 文件里设 "disableAllHooks": true。托管策略里的 hook 不受用户/项目设置里的 disableAllHooks 影响——只有托管级才能禁托管 hook。/hooks 菜单可读不能改。

Handler 类型

配置里 hooks 数组每个对象是一个 handler，有五种类型：

并非所有事件都支持所有类型。SessionStart / Setup 只支持 command 和 mcp_tool。prompt 和 agent 只能在能”做决定”的事件上用（PreToolUse、PostToolUse、Stop、UserPromptSubmit 等），不能在纯副作用事件上用。

通用字段

命令 hook 的 exec vs shell 形式

设了 args 走 exec 形式：command 解析为可执行文件，args 是参数向量，无 shell 介入。引号、空格、$ 都原样传递。路径占位符必须用 exec 形式（${CLAUDE_PROJECT_DIR} 等不会被 shell 破坏）。

{ "type": "command", "command": "node",
  "args": ["${CLAUDE_PROJECT_DIR}/scripts/format.js", "--fix"] }

没设 args 走 shell 形式：command 整体交给 sh -c 解释，能用管道、&&、变量展开。

{ "type": "command",
  "command": "node \"${CLAUDE_PROJECT_DIR}\"/scripts/format.js --fix" }

Windows 上：exec 形式需要真实 .exe，npm 垫片（.cmd/.bat）必须走 shell 形式或 node 直调。设 "shell": "powershell" 可在 PowerShell 里跑单条 hook。

路径占位符

• ${CLAUDE_PROJECT_DIR}：项目根
• ${CLAUDE_PLUGIN_ROOT}：插件安装目录（每次更新会变）
• ${CLAUDE_PLUGIN_DATA}：插件持久数据目录（更新后保留）

匹配器（matcher）

不同事件匹配不同字段：

• 工具事件（PreToolUse/PostToolUse/PostToolUseFailure/PermissionRequest/PermissionDenied）：匹配 tool_name
• SessionStart：匹配 source（startup/resume/clear/compact）
• SessionEnd：匹配退出原因（clear/resume/logout/prompt_input_exit/bypass_permissions_disabled/other）
• Notification：匹配通知类型（permission_prompt/idle_prompt/auth_success/elicitation_*）
• SubagentStart/SubagentStop：匹配代理类型（general-purpose/Explore/Plan/自定义名）
• PreCompact/PostCompact：匹配 manual/auto
• ConfigChange：匹配 user_settings/project_settings/local_settings/policy_settings/skills
• FileChanged：字面文件名（用 | 分隔，如 .envrc|.env），不遵循下面的通用规则
• StopFailure：匹配错误类型（rate_limit/authentication_failed/billing_error 等）
• InstructionsLoaded：匹配加载原因（session_start/nested_traversal/compact 等）
• UserPromptExpansion：匹配命令名
• Elicitation/ElicitationResult：匹配 MCP 服务器名

不支持 matcher、永远全触发：UserPromptSubmit、PostToolBatch、Stop、TeammateIdle、TaskCreated、TaskCompleted、WorktreeCreate、WorktreeRemove、MessageDisplay、CwdChanged。给这些事件加 matcher 字段会被静默忽略。

匹配器语法：

• "*"、"" 或省略：匹配所有
• 只有字母/数字/_/|：精确字符串或 | 列表（Bash、Edit|Write）
• 含其他字符：JS 正则（^Notebook、mcp__memory__.*）

MCP 工具命名是 mcp__<server>__<tool>，匹配整个 server 用 mcp__<server>__.*（末尾的 .* 必须有，否则按字面精确匹配）。

if 字段在同一 handler 上做更窄的二次过滤，权限规则语法：Bash(rm *)、Edit(*.ts)。注意只支持单条规则，不支持 &&/||，要多个条件就写多个 handler。

事件清单（按生命周期）

输入输出

通用输入字段

每条 hook 通过 stdin（命令）/ POST body（HTTP）/ 工具参数（MCP）收到 JSON：

{
  "session_id": "abc123",
  "transcript_path": "/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/project",
  "permission_mode": "default",
  "effort": { "level": "high" },
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "npm test" }
}

--agent 启动或 subagent 内触发还会多 agent_id、agent_type。SessionStart 还会多 model 字段（不是环境变量）。

tool_name / tool_input 是事件特定字段，每个事件能拿到什么见 原文事件章节。

退出码语义

• 0：成功。stdout 被解析为 JSON（可选），除 UserPromptSubmit / UserPromptExpansion / SessionStart 外，stdout 不进对话
• 2：阻止错误。stderr 进 Claude 上下文作为错误信息，stdout 被忽略
• 其他：非阻止错误。WorktreeCreate 例外——任何非零都会中止

退出 2 能阻止什么

已发生的事件不能阻止：PostToolUse / PostToolUseFailure / Notification / SessionStart / Setup / SessionEnd / CwdChanged / FileChanged / PostCompact / InstructionsLoaded / MessageDisplay / WorktreeRemove / StopFailure —— 退出 2 只会让 stderr 展示给用户。PermissionDenied 不能用退出码阻止，但能用 JSON retry: true 告诉模型”可以再试一次”。

JSON 输出（精细控制）

退出 0 时往 stdout 打 JSON，得到比退出码更细的语义。只支持一种模式：要么只用退出码，要么用 JSON——不能混。stdout 必须只含 JSON，否则 shell 启动输出会破坏解析。

通用字段：

为 Claude 注入上下文（在 hookSpecificOutput 里）：

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "这个文件是生成的，请改 src/schema.ts 然后跑 bun generate"
  }
}

additionalContext 出现在 SessionStart/UserPromptSubmit/PreToolUse 等不同位置——本质是”Claude 看到的下一个模型请求时多了一条系统提醒”。多个 hook 都返回时 Claude 收到全部。超 10000 字符会被截断到文件并附带预览。

CLAUDE.md 比 additionalContext 更适合放不变的项目说明——它加载时不需要跑脚本。

决定控制

每个事件表达”决定”的方式不同，下面是速查表：

PreToolUse 的 deferred 模式：返回 permissionDecision: "defer" 配合 toolUseID，可以把工具调用延迟到下一轮——典型场景是用户审批 UI 弹窗没准备好时。

PreToolUse 改写参数：

{ "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": { "command": "npm run lint" } } }

PostToolUse 改写输出：

{ "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "updatedToolOutput": { "stdout": "[redacted]", "stderr": "",
                            "interrupted": false, "isImage": false } } }

注意：updatedToolOutput 只能改 Claude 看到的内容，工具已执行的副作用（写文件、跑命令、HTTP 请求）都已经发生。遥测也在 hook 前抓完。

异步 Hook

命令 hook 默认阻塞。加 "async": true 后台跑，Claude 不等结果。适合”测试、部署、外部 API 回调”这类长操作。

{ "type": "command", "command": "/path/to/run-tests.sh",
  "async": true, "timeout": 120 }

异步 hook 不能阻止、不能返回决定（操作已经走完了）。它能做的：返回 additionalContext 在下一轮传给 Claude。systemMessage 给用户看。asyncRewake: true 让它在退出 2 时即使会话闲置也立刻唤醒 Claude。

限制：

• 只 type: "command" 支持
• 不支持 prompt / agent 异步
• 每次执行独立后台进程，不去重
• 输出默认被抑制（Ctrl+O 开详细模式）

基于提示的 Hook

type: "prompt"，不跑命令，送一个 LLM 单轮评估决定：

{ "type": "prompt",
  "prompt": "评估 Claude 是否应停止: $ARGUMENTS。检查任务是否完成。" }

LLM 返回 { "ok": true } 或 { "ok": false, "reason": "..." }。$ARGUMENTS 会被 hook 输入 JSON 替换。

• ok: true 允许
• ok: false：
  • Stop / SubagentStop / PreToolUse 等：原因作为下一条指令或工具错误回给 Claude
  • PostToolUse：默认结束轮次；设 continueOnBlock: true 把原因作为上下文
  • PostToolBatch / UserPromptSubmit / UserPromptExpansion：结束轮次

PermissionRequest 和 PermissionDenied 上 ok: false 无效，要用命令 hook 返回 decision.behavior: "deny" 或 retry: true。

基于代理的 Hook

type: "agent"（实验性，行为可能变）。和 prompt hook 类似，但代理可以调 Read/Grep/Glob 工具来验证条件，50 轮内返回。配置字段和 prompt 一样，只是默认 timeout=60。生产环境建议用命令 hook。

安全

命令 hook 以你的系统用户完整权限跑——能改/删任何文件。

最佳实践：

• 永远不信任 hook 输入数据
• shell 变量要引号 ("$VAR" 不是 $VAR)
• 检查 .. 路径遍历
• 用绝对路径（${CLAUDE_PROJECT_DIR} + exec 形式最稳）
• 跳过 .env、.git/、密钥目录

企业管理员可以设 allowManagedHooksOnly 禁止用户/项目/插件 hook——只允许托管设置里的 hook 跑。托管 enabledPlugins 强制启用的插件里的 hook 是豁免的。

调试

• /hooks 菜单：只读浏览所有配置的 hook
• claude --debug：把 hook 匹配、退出码、stdout/stderr 写到 ~/.claude/debug/<session-id>.txt，不打印终端
• claude --debug-file <path>：日志写到指定位置
• CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose：额外显示匹配器计数和查询细节

典型调试场景：

• hook 不触发 → 检查 matcher 字段拼写和事件支持列表
• Stop hook 持续阻止 → 确认退出 0 / JSON 模式二选一
• JSON 解析失败 → 检查 shell rc 文件（.bashrc 等）是否在 hook stdout 里打印东西

速查

事件 → matcher → [if] → handler
                 ↓
         stdin/POST 收 JSON
                 ↓
         退出 0 (stdout JSON) | 退出 2 (阻止) | 其他 (非阻止)
                 ↓
         stdout JSON 含 decision / permissionDecision / additionalContext / continue

参考资料：

• Hooks 官方参考
• 使用 hooks 自动化工作流（指南）
• 设置文件
• 权限规则
• Bash 命令验证器示例