name: claude-code-hooks description: “Claude Code 钩子系统，用于工具执行前后的自定义脚本执行。触发时机包括：hooks、PreToolUse、PostToolUse、钩子脚本、工具验证、审计日志。” compatibility: “支持 settings.json 配置的 Claude Code CLI” allowed-tools: “Bash 读写工具” depends-on: [] related-skills: [claude-code-debug, claude-code-headless]

Claude Code 钩子

在 Claude Code 工具调用前后执行自定义脚本。

快速参考

事件	触发时机	支持匹配器
`PreToolUse`	工具执行前	是
`PostToolUse`	工具完成后	是
`PermissionRequest`	权限对话框显示时	是
`Notification`	发送通知时	是
`UserPromptSubmit`	用户提交提示词时	否
`Stop`	智能体结束时	否
`SubagentStop`	子智能体结束时	否
`PreCompact`	上下文压缩前	否
`SessionStart`	会话开始/恢复时	否
`SessionEnd`	会话结束时	否

基础配置

添加到 ~/.claude/settings.json 或 .claude/settings.local.json：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "$CLAUDE_PROJECT_DIR/hooks/validate.sh",
        "timeout": 5000
      }]
    }]
  }
}

匹配器模式

模式	匹配对象
`"Write"`	仅 Write 工具
`"*"` 或 `""`	所有工具
`"mcp__*"`	所有 MCP 工具
`"Bash"`	Bash 命令

钩子脚本要求

#!/bin/bash
# 通过 stdin 接收 JSON：{ "tool_name": "...", "tool_input": {...} }
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')

# 退出代码：
# 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

官方文档

https://code.claude.com/docs/en/hooks - 钩子参考文档
https://code.claude.com/docs/en/settings - 设置配置

附加资源

./references/hook-events.md - 所有事件的输入/输出模式
./references/configuration.md - 高级配置模式
./references/security-patterns.md - 生产环境安全模式

另请参阅： claude-code-debug 用于故障排除，claude-code-headless 用于 CLI 自动化