本资料是 Claude Code Hooks 的创建与管理指南。Hooks 是在工具执行前、执行后或会话结束时自动运行的脚本。主要类型及用途:PreToolUse 在工具执行前运行,可用于校验与拦截危险操作;PostToolUse 在工具执行后运行,可用于给出建议或记录日志;Stop 在会话结束时运行,可用于清理。
创建流程:先编写脚本(例中放在 .claude/hooks/my-hook.sh),脚本可读取 TOOL_NAME 等环境变量及 JSON 格式的 TOOL_INPUT;退出码含义为 0 成功(允许)、1 警告(仍允许并显示消息)、2 阻止(停止执行)。随后执行 chmod +x .claude/hooks/my-hook.sh 赋予执行权限,再在 .claude/settings.local.json 的 hooks 配置中按事件类型注册,matcher 支持用正则匹配工具名(如 Write|Edit|Bash),command 指向脚本路径。
资料给出若干示例:PreToolUse 中拦截对 main/master 的 force push、对 .env 文件编辑给出警告;PostToolUse 中在 git commit 后检测 schema 变更并建议创建迁移文件;Stop 中提示存在已合并分支并建议删除。调试可手动设置 TOOL_NAME 与 TOOL_INPUT 直接运行脚本并用 echo $? 查看退出码。
最佳实践:避免阻塞耗时操作;输出到 stderr 而非 stdout;仅给出建议、不自动执行,由人判断;用 jq 解析 JSON;在 jq 不可用时保持放行(exit 0)作为失效保护。适用场景包括危险操作拦截、执行后提示、会话结束清理。限制方面,资料未提供更多平台或版本要求。