Claude Code Hooks 完整参考指南

Hooks 是在 Claude Code 生命周期特定时机自动执行的用户定义处理器，提供对 Claude Code 行为的确定性控制（deterministic control），而不是依赖 LLM 去决定是否运行某些操作。可用于执行项目规则、自动化重复任务、与外部工具集成。

文档来源：

• Hooks reference: https://code.claude.com/docs/en/hooks.md
• Hooks guide: https://code.claude.com/docs/en/hooks-guide.md

1. Hook 处理器类型

2. Hook 生命周期节奏

3. 完整事件列表

4. 配置格式（settings.json）

Hooks 使用 3 层 JSON 嵌套结构：

{
  "hooks": {
    "EVENT_NAME": [
      {
        "matcher": "ToolName|OtherTool",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "/path/to/script.sh",
            "timeout": 600,
            "statusMessage": "Validating...",
            "async": false
          }
        ]
      }
    ]
  }
}

4.1 通用字段

4.2 Command hook

{
  "type": "command",
  "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/script.sh",
  "async": false,
  "asyncRewake": false,
  "shell": "bash"
}

• async: 后台运行，不阻塞
• asyncRewake: 后台运行，exit code 2 时唤醒 Claude
• shell: "bash"（默认）或 "powershell"

环境变量：

• $CLAUDE_PROJECT_DIR — 项目根目录
• ${CLAUDE_PLUGIN_ROOT} — 插件安装目录
• ${CLAUDE_PLUGIN_DATA} — 插件持久化数据目录
• CLAUDE_ENV_FILE — 写入 export VAR=value 行以持久化环境变量

4.3 HTTP hook

{
  "type": "http",
  "url": "http://localhost:8080/hooks/pre-tool-use",
  "timeout": 30,
  "headers": { "Authorization": "Bearer $MY_TOKEN" },
  "allowedEnvVars": ["MY_TOKEN"]
}

• POST 发送 JSON body（与 command hook 的 stdin 格式相同）
• 仅 allowedEnvVars 中列出的环境变量会被插值

4.4 Prompt hook

{
  "type": "prompt",
  "prompt": "Review this and decide if it's safe: $ARGUMENTS",
  "model": "fast-model",
  "timeout": 30
}

响应格式：{"ok": true} 允许，或 {"ok": false, "reason": "..."} 阻止。

4.5 Agent hook

{
  "type": "agent",
  "prompt": "Verify these changes don't break tests: $ARGUMENTS",
  "model": "sonnet",
  "timeout": 120
}

生成可用工具（Read/Grep/Glob）的 subagent，默认最多 50 次 tool-use turns。

4.6 Matcher 模式

事件的 matcher 含义：

MCP 工具匹配： 命名约定为 mcp__<server>__<tool>，例如 mcp__memory__.*。

5. 输入输出约定

5.1 通用输入字段

所有 hook 收到（command hook 通过 stdin）：

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "permission_mode": "default|plan|acceptEdits|auto|dontAsk|bypassPermissions",
  "hook_event_name": "PreToolUse",
  "agent_id": "agent-abc123",
  "agent_type": "Explore"
}

5.2 Exit Codes

Exit code 2 在各事件的效果：

5.3 JSON Output 结构化控制

exit 0 且 stdout 为 JSON 时支持细粒度控制：

{
  "continue": true,
  "stopReason": "Message shown to user",
  "suppressOutput": false,
  "systemMessage": "Warning to user",
  "decision": "block",
  "reason": "Why blocked",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow|deny|ask|defer",
    "permissionDecisionReason": "Reason",
    "updatedInput": {},
    "additionalContext": "Context for Claude"
  }
}

重要： 不要混用 exit 2 和 JSON 输出 — exit 2 时 JSON 会被忽略。

6. 关键事件详细说明

6.1 PreToolUse

Input:

{
  "tool_name": "Bash",
  "tool_input": { "command": "npm test" },
  "tool_use_id": "toolu_01ABC123..."
}

控制：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow|deny|ask|defer",
    "permissionDecisionReason": "Reason",
    "updatedInput": { "modified_field": "new_value" },
    "additionalContext": "Context for Claude"
  }
}

多 hook 决策优先级：deny > defer > ask > allow。

6.2 PostToolUse

Input: {tool_name, tool_input, tool_response, tool_use_id}

可通过 hookSpecificOutput.additionalContext 给模型反馈，或 updatedMCPToolOutput 替换 MCP 工具输出。

6.3 PermissionRequest

提供 permission_suggestions 数组，hook 可返回：

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow|deny",
      "updatedInput": {},
      "updatedPermissions": []
    }
  }
}

updatedPermissions 条目类型： addRules, replaceRules, removeRules, setMode, addDirectories, removeDirectories

Destinations： session, localSettings, projectSettings, userSettings

⚠️ PermissionRequest hook 在非交互模式（-p）下不触发 — 使用 PreToolUse 替代。

6.4 Stop

Input: {stop_reason, message, stop_hook_active}

⚠️ Stop hook 必须检查 stop_hook_active 字段防止无限循环。

6.5 SessionStart

Matcher: startup, resume, clear, compact

可通过 stdout 注入额外 context，支持 JSON additionalContext、sessionTitle，以及 CLAUDE_ENV_FILE 持久化环境变量。

6.6 FileChanged / CwdChanged

支持 CLAUDE_ENV_FILE — 写入 export VAR=value 行即可持久化到后续 Bash 命令，常用于 direnv 集成。

7. Hook 作用域与位置

用户级 vs 项目级 关键区别

1. 多层合并： 多个 hook 匹配同一事件并行运行，决策合并采用最严格结果（deny > ask > allow）。所有 additionalContext 拼接传给 Claude。

2. 安全边界： Managed policy settings 来自管理员无法绕过；PreToolUse hook 在任何 permission mode 检查之前触发 — 即便 bypassPermissions 也能阻止工具。但 hook 的 "allow" 不能绕过 deny 规则 — hook 只能收紧，不能放宽。

3. 批量禁用： 在任意 settings 设置 "disableAllHooks": true 可一次性禁用该作用域内所有 hook。

4. 查看当前 hook： /hooks 命令（只读）显示所有已配置 hook，按事件分组。

8. 安全考虑

⚠️ 免责声明： Hooks 拥有用户权限，恶意 hook 可盗取凭据、外泄数据、入侵系统。只使用可信来源的 hook。

8.1 最佳实践

1. 验证所有输入。 tool_input 是用户（通过 Claude）控制的。使用 jq 安全提取 JSON，shell 变量必须加引号。

2. 避免 shell 注入：

   bashCopy

   # 错误
   COMMAND=$(jq -r '.tool_input.command')
   if echo $COMMAND | grep rm; then ...
   
   # 正确
   COMMAND=$(jq -r '.tool_input.command')
   if echo "$COMMAND" | grep -q rm; then ...
   

   不要用 eval。

3. 保护敏感文件。 transcript_path 含完整会话（可能含 API key、密码）。

4. 限制环境变量插值。 HTTP hook 的 headers 只解析 allowedEnvVars 白名单内的变量。

5. 不要硬编码密钥。 /hooks 菜单显示完整命令/URL — 用 allowedEnvVars 或 ~/.netrc 管理凭据。

6. 路径遍历防护：

   bashCopy

   FILE_PATH=$(jq -r '.tool_input.file_path')
   REAL_PATH=$(realpath "$FILE_PATH" 2>/dev/null)
   PROJECT_ROOT=$(realpath "$CLAUDE_PROJECT_DIR")
   if *"$REAL_PATH" != "$PROJECT_ROOT"**; then
     echo "Access denied: path outside project" >&2
     exit 2
   fi
   

9. 常见使用场景

10. 限制与故障排除

10.1 主要限制

• Command hook 仅通过 stdout/stderr/exit code 通信，不能触发 / 命令或工具调用
• Hook 超时默认 10 分钟（command）
• PostToolUse hook 无法撤销操作（tool 已执行）
• PermissionRequest hook 在 -p 非交互模式不触发
• Stop hook 在 Claude 每次完成回答时触发（不只任务完成），不会在用户打断时触发
• 多个 PreToolUse hook 并行修改同一工具参数时，最后完成的胜出（非确定性）

10.2 Stop hook 无限循环防护

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi

10.3 "JSON validation failed"

原因：shell profile (~/.zshrc / ~/.bashrc) 有无条件 echo 把文字拼接到 hook 的 JSON stdout 前。

修复：

# 只在交互 shell 中 echo
if *$- == *i**; then
  echo "Shell ready"
fi

10.4 Debug 技巧

• Ctrl+O — 打开 transcript view，查看每个 hook 的摘要
• claude --debug-file /tmp/claude.log — 写 debug log
• /debug — 运行中启用 logging
• /hooks — 只读菜单验证 hook 配置

参考链接

• Hooks reference: https://code.claude.com/docs/en/hooks.md
• Hooks guide with examples: https://code.claude.com/docs/en/hooks-guide.md
• Permission rules syntax: https://code.claude.com/docs/en/permissions
• Settings reference: https://code.claude.com/docs/en/settings
• Bash validator example: https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py