|
|
| 名称 |
claude-code-hooks |
| 描述 |
“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
官方文档
附加资源
./references/hook-events.md - 所有事件的输入/输出模式./references/configuration.md - 高级配置模式./references/security-patterns.md - 生产环境安全模式
另请参阅： claude-code-debug 用于故障排除，claude-code-headless 用于 CLI 自动化