用途:Claude Code 在工具调用边界触发钩子。钩子是接收 stdin JSON 事件的 shell 命令,对可阻断的钩子而言,退出码决定工具调用是否继续。资料强调这是唯一能从结构上阻止某行为的机制:CLAUDE.md 里的文字规则只是建议,钩子才是墙。
何时该用:当某条规则已写明却仍反复被违反时,把规则从文字(建议)升级为钩子(强制)。资料给出的经验法则:Tier-0 不可逆操作(会话内无法撤销,如销毁未提交工作、推送密钥、删除文件、对外发布)若只有文字规则而无钩子,就应做成钩子。不该用时:规则从未真正复发,或规则属于无机械特征的判断(钩子只能匹配 token/模式)。
钩子类型与退出码:PreToolUse 在工具运行前触发,退出 0 走正常权限流程(除非 JSON 给出 allow/deny/ask),退出 2 即使 JSON 说 allow 也阻断,stderr 作为模型看到的理由;PostToolUse 在工具运行后触发,退出 0 时若在 stdout 打印 hookSpecificOutput JSON 可注入上下文,无法撤销已运行的工具;SessionStart 在会话开始时触发,不能阻断,建议始终退出 0,否则每次会话开始都会在用户记录里留下 hook 错误;Stop(含 SubagentStop)在模型即将结束回复时触发,退出 2 可阻止停止并强制继续,需检查 stop_hook_active 并自带循环上限。
匹配与用法:matcher 选择工具(Bash、Agent、WebFetch 等),仅含字母数字等字符时按精确字符串匹配,否则按未锚定 JS 正则;匹配区分大小写。PreToolUse 是阻断工具调用的主力。资料给出 PreToolUse Bash 守卫骨架,使用 set -euo pipefail、IFS= read -rd '' INPUT、内置 case 快速路径,再用 python3 解析 tool_name 与 command,最后 grep -qw 精确判断并以 exit 2 阻断。
限制与注意:粗过滤必须是所阻断内容的超集,原始子串测试不是超集,引号拼接可造成绕过;应基于 JSON 键或工具名过滤,或先去引号再匹配。应使用 shlex 类按 token 匹配,不要用 awk 切分原始字符串,否则会误杀健康命令。注册中的 if 字段(如 "Bash(git *)")可省去进程开销,但属尽力而为,不能当作门禁。资料未提供安装命令、价格或平台信息。