Hooks 系统（Hooks System）

概述

Hooks 是用户定义的自动化动作，在 Claude Code 的特定生命周期节点自动执行。它们是确定性的（不是建议性的），一旦配置就会严格执行，不会被 Claude 跳过。

四种处理器类型

1. Command（Shell 命令）

运行本地 Shell 命令，通过 stdin 接收 JSON 输入：

{
  "hooks": {
    "PreToolUse": [{
      "type": "command",
      "command": "python3 ~/.claude/hooks/lint-check.py"
    }]
  }
}

2. HTTP（网络请求）

发送 POST 请求到 URL，支持环境变量插值：

{
  "hooks": {
    "Stop": [{
      "type": "http",
      "url": "https://hooks.example.com/notify",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }]
  }
}

3. Prompt（LLM 评估）

使用 Claude 模型评估条件，返回 {ok, reason}：

{
  "hooks": {
    "PreToolUse": [{
      "type": "prompt",
      "prompt": "这个 Bash 命令是否安全？不允许删除操作和 rm -rf。"
    }]
  }
}

4. Agent（子代理验证）

生成具有工具访问权限的子代理进行复杂验证：

{
  "hooks": {
    "PostToolUse": [{
      "type": "agent",
      "prompt": "验证刚刚编辑的文件是否通过类型检查和 lint。",
      "tools": ["Bash", "Read"]
    }]
  }
}

生命周期事件

会话级事件

工具级事件

子代理事件

上下文事件

其他事件

退出码行为

PreToolUse 的 JSON 输出

PreToolUse 是最强大的 Hook 事件，可以返回权限决策和修改参数：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "已通过安全检查",
    "updatedInput": { "command": "npm test -- --coverage" },
    "additionalContext": "已添加覆盖率标志"
  }
}

权限决策选项：

• allow：允许执行（跳过用户确认）
• deny：拒绝执行
• ask：交给用户决定

Hook 配置位置

环境变量

Hook 脚本可使用的环境变量：

通用输入字段

每个 Hook 都会收到包含以下字段的 JSON：

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/当前/工作/目录",
  "permission_mode": "default",
  "hook_event_name": "EventName",
  "agent_id": "agent-xyz",
  "agent_type": "AgentName"
}

实用配方

自动格式化保存的文件

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

桌面通知（Claude 完成时）

{
  "hooks": {
    "Stop": [{
      "type": "command",
      "command": "osascript -e 'display notification \"Claude 已完成\" with title \"Claude Code\"'"
    }]
  }
}

阻止危险的 Shell 命令

{
  "hooks": {
    "PreToolUse": [{
      "type": "prompt",
      "prompt": "检查这个 Bash 命令是否包含危险操作（rm -rf、git push --force、DROP TABLE 等）。如果危险则拒绝。",
      "matcher": { "tool_name": "Bash" }
    }]
  }
}

MCP 工具命名模式

MCP 工具在 Hook 中的名称格式为 mcp__<服务器名>__<工具名>，例如 mcp__memory__create_entities。