是什么
Hooks 是在 Claude Code 生命周期特定节点自动执行的用户定义处理器，支持 Shell 命令、HTTP 端点或 LLM Prompt 三种形式。通过 Hooks 可以实现确定性控制：格式化代码、阻止危险命令、注入上下文、发送通知等，而不依赖 LLM 自主决策。
核心机制
事件分类：
- 会话级（每次会话一次）：
SessionStart、SessionEnd、Setup - 轮次级（每轮一次）：
UserPromptSubmit、Stop、StopFailure - 工具调用级（每次工具调用）：
PreToolUse、PostToolUse、PostToolUseFailure - 异步事件：
Notification、FileChanged、CwdChanged、ConfigChange - Agent 相关：
SubagentStart、SubagentStop、TeammateIdle、TaskCreated、TaskCompleted - 上下文相关：
PreCompact、PostCompact、WorktreeCreate、WorktreeRemove
Hook 解析流程：事件触发 → matcher 匹配工具名 → if 条件过滤 → 执行 handler → 返回决策。
决策控制：PreToolUse 可返回 permissionDecision: "deny" 阻止工具调用；Stop Hook 可返回 {retry: true} 让 Claude 继续工作；TaskCompleted 返回 exit code 2 可阻止任务完成。
三种 Handler 类型：
command：Shell 命令，通过 stdin 接收 JSON，stdout 返回决策http：HTTP POST 端点，请求体为 JSONprompt：LLM Prompt，用于需要判断的场景
关键细节
- 配置位置：
~/.claude/settings.json或.claude/settings.json - 查看已配置的 Hooks：
/hooks - 阻止工具调用：exit code 2 +
permissionDecision: "deny" - 允许工具调用：exit 0
- 向 Claude 发送反馈：stdout 输出
{hookSpecificOutput: {...}} matcher字段：匹配工具名（如"Bash"、"Edit|Write"）if字段：细粒度过滤（如"Bash(rm *)"），避免不必要的进程启动
关联
- hooks-guide — Hooks 实践指南与常见用例
- agent-teams — TeammateIdle/TaskCreated/TaskCompleted 等 Agent Teams 相关 Hook
- skills — 另一种扩展 Claude 能力的方式
实践要点
PreToolUse是最常用的 Hook，可实现命令审计、危险操作拦截if字段可以大幅减少不必要的进程启动开销- HTTP Hook 适合集成到现有监控或审计系统
- Prompt Hook 适合需要 LLM 判断的场景（如代码质量检查）
PostToolUse配合Edit|Writematcher 可实现自动格式化