Claude Code Hooks 是 Claude Code 的钩子系统，允许在 Claude Code 工具调用前后执行自定义脚本，用于校验、记录和扩展工具行为。
用途 钩子用于在工具执行的关键节点插入自定义逻辑，例如在工具运行前校验输入、在工具完成后记录审计日志、在权限弹窗出现时触发自定义审批流程，或在会话开始时加载项目上下文。
主要能力 系统提供多个事件：PreToolUse（工具执行前）、PostToolUse（工具完成后）、PermissionRequest（显示权限对话框时）、Notification（发送通知时）、UserPromptSubmit（用户提交提示词时）、Stop（Agent 结束）、SubagentStop（子代理结束）、PreCompact（上下文压缩前）、SessionStart（会话开始或恢复）、SessionEnd（会话结束）。其中 PreToolUse、PostToolUse、PermissionRequest、Notification 支持 matcher，其余事件不支持。
Matcher 模式 matcher 用于限定钩子触发的工具范围："Write" 仅匹配 Write 工具；"" 或空字符串匹配所有工具；"mcp__" 匹配所有 MCP 工具；"Bash" 匹配 Bash 命令。
使用方式 在 ~/.claude/settings.json 或 .claude/settings.local.json 中添加 hooks 配置。示例配置为 PreToolUse 事件、matcher 为 Bash、执行 $CLAUDE_PROJECT_DIR/hooks/validate.sh、超时 5000 毫秒。钩子脚本通过 stdin 接收 JSON，格式如 { "tool_name": "...", "tool_input": {...} }，可用 jq 解析。退出码语义：0 表示成功并继续；2 表示阻止并报错，stderr 会展示给 Claude；其他退出码为非阻塞错误。
适用场景 常见用例包括：用 PreToolUse 校验输入并阻止危险命令；用 PostToolUse 记录所有工具使用情况；用 PermissionRequest 发送 Slack 通知实现自定义审批；用 SessionStart 加载项目上下文。
安全与限制 安全清单建议：变量加引号（"$VAR" 而非 $VAR）；校验路径，防止 .. 目录穿越；使用 $CLAUDE_PROJECT_DIR 构建路径；设置合理超时；处理 jq 解析错误。
排查方式 可用 claude --debug 调试钩子加载；用 /hooks 列出已注册钩子；用 echo '{"tool_name":"Bash"}' | ./hooks/validate.sh 手动测试脚本。
官方文档 Hooks 参考：https://code.claude.com/docs/en/hooks；设置配置：https://code.claude.com/docs/en/settings。
附加资源 ./references/hook-events.md 提供所有事件及输入输出 schema；./references/configuration.md 提供高级配置模式；./references/security-ops.md 提供生产环境安全实践。另可参考 claude-code-debug 进行故障排查，claude-code-headless 进行 CLI 自动化。