claude-code-hooks

Claude Code Hooks

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

快速参考

事件	时机	是否支持匹配器
PreToolUse	工具执行前	是
PostToolUse	工具完成后	是
PermissionRequest	显示权限对话框时	是
Notification	发送通知时	是
UserPromptSubmit	用户提交提示词时	否
Stop	Agent 完成时	否
SubagentStop	子 Agent 完成时	否
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 命令

Hook 脚本要求

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

# Exit codes:
# 0 = Success (continue)
# 2 = Block with error (stderr shown to Claude)
# Other = Non-blocking error

常见用例

用例	事件	示例
验证输入	PreToolUse	阻止危险命令
审计日志	PostToolUse	记录所有工具使用情况
自定义审批	PermissionRequest	Slack 通知
会话初始化	SessionStart	加载项目上下文

安全检查清单

• 为所有变量添加引号：使用 "$VAR"，而不是 $VAR
• 验证路径（禁止使用 .. 遍历）
• 使用 $CLAUDE_PROJECT_DIR 表示路径
• 设置合理的超时时间
• 处理 jq 解析错误

故障排除

# Debug hook loading
claude --debug

# List registered hooks
/hooks

# Test script manually
echo '{"tool_name":"Bash"}' | ./hooks/validate.sh

官方文档

• https://code.claude.com/docs/en/hooks - Hooks 参考
• https://code.claude.com/docs/en/settings - 设置配置

更多资源

• ./references/hook-events.md - 包含输入／输出架构的所有事件
• ./references/configuration.md - 高级配置模式
• ./references/security-ops.md - 生产环境安全

---

另请参阅： claude-code-debug 以进行故障排除，claude-code-headless 以实现 CLI 自动化