Claude Code Hooks 用于在 Claude Code 调用工具的前后执行自定义脚本,实现输入校验、审计日志、自定义审批与会话初始化等。
主要能力与事件:PreToolUse 在工具执行前触发,PostToolUse 在工具完成后触发,二者带 matcher;PermissionRequest、Notification 带 matcher;UserPromptSubmit、Stop、SubagentStop、PreCompact、SessionStart、SessionEnd 不带 matcher。
配置:在 ~/.claude/settings.json 或 .claude/settings.local.json 中加入 hooks 字段,按事件列出 matcher 与 hooks,命令支持 type、command、timeout,例如使用 $CLAUDE_PROJECT_DIR/hooks/validate.sh。matcher 可为具体工具名如 Write、Bash,也可用 "" 或 "" 匹配全部工具,"mcp__" 匹配所有 MCP 工具。
脚本要求:脚本通过 stdin 接收 JSON,如 {"tool_name":"...","tool_input":{...}};退出码 0 表示继续,2 表示阻止并把 stderr 展示给 Claude,其他为非阻断错误。
常见用途:PreToolUse 校验输入、拦截危险命令;PostToolUse 记录全部工具使用;PermissionRequest 做自定义审批(如 Slack 通知);SessionStart 加载项目上下文。
安全与排查:变量需加引号、校验路径避免 .. 穿越、使用 $CLAUDE_PROJECT_DIR、设置合理超时、处理 jq 解析错误。可用 claude --debug 调试加载,用 /hooks 查看已注册钩子。
官方文档见 code.claude.com/docs/en/hooks 与 /settings;仓库另含 hook 事件、配置与安全模式等参考文件。具体安装命令与价格资料暂未提供。