用 Claude Code 钩子拦截危险命令
文章展示通过 PreToolUse 钩子读取工具调用 JSON,并以退出码 2 阻止执行的方法。示例针对项目外递归删除、强制推送和删除远端主分支等高风险命令设置限制。
AI 深度解读
Claude Code 连续几次只跑 ls,确认弹窗很容易变成机械点击。可一旦开启自动接受,下一条命令就可能是 git reset --hard。作者的做法是把几类高风险操作交给 PreToolUse 钩子,在 Bash 执行前拦下,并告诉 Agent 接下来怎么处理。
原文最有用的两处细节,一处是作者在真实会话里保住了一行未提交改动,另一处是同一篇文章展示了最小版规则为什么会漏判。想给日常 AI 编程加一道保护,可以从这两个结果入手。
哪些命令应该留给人来执行?
作者划了五条线。第一条是删除范围,rm -rf 一旦指向项目外、~、/、项目根目录或 .git,就该停下来。第二条是远端 Git 操作,git push --force 和删除远端 main 会影响依赖这些分支的同事。第三条是本地 Git 操作,git reset --hard、git clean -f 和 git checkout . 都可能丢掉尚未提交的工作。剩下两条是把下载内容直接交给 Shell 执行,例如 curl ... | sh,以及用 sudo 提权。
Claude Code 的 PreToolUse 在工具调用之前运行。它从标准输入读入 JSON,退出码 0 放行,退出码 2 取消调用,并把拦截消息交给 Agent。下面这段 .claude/settings.json 把检查接到 Bash 工具上。
{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [
{ "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard.py\"" } ] } ] } }
注意 matcher 这一项,它把这段配置的检查范围限定在 Bash 调用。
下面的 .claude/hooks/guard.py 展示了如何从工具调用里取出命令,命中规则时把原因写入标准错误。
import json, re, sys
event = json.load(sys.stdin)
command = event.get("tool_input", {}).get("command", "")
RULES = [
(r"\bgit\s+push\b.*(--force|-f\b|--mirror)", "force push rewrites shared history"),
(r"\bgit\s+reset\s+--hard\b", "git reset --hard throws away uncommitted work"),
(r"\b(curl|wget)\b[^|]*\|\s*(sh|bash|zsh)\b", "piping a download into a shell runs unread code"),
(r"(^|[;&|]\s*)sudo\b", "sudo is not needed to edit a project"),
]
for pattern, reason in RULES:
if re.search(pattern, command):
print(f"BLOCKED - {reason}. Ask the human to run it.", file=sys.stderr)
sys.exit(2)
sys.exit(0)
注意末尾的 sys.exit(0),任何未匹配的命令都会放行。示例只实现了 RULES 中的四条检查,删除路径、删除远端 main 和另外两条本地 Git 命令还需要补规则。作者把包含 git reset --hard HEAD~3 的 JSON 直接喂给脚本,再用 echo "exit=$?" 检查,得到 exit=2。这一步可以脱离 Claude Code 单独跑。
为什么同一个动作换种写法就会漏掉?
作者实测,git -C x push --force 和 env sudo ls 在最小版里都得到 exit=0。前者在 git 和 push 之间插入了全局参数,后者在 sudo 前加了命令前缀。把匹配条件放宽也有代价,文件名、引号里的普通文本和 heredoc 正文都可能被误判成命令。
更完整的实现先按 Shell 的语法拆出命令,再做判断。一行里有 &&、; 或 |,就得分别检查各段。遇到 bash -c,还要识别引号里实际交给 Shell 的命令。判断删除范围时,./build 和 ./build/../../ 看起来都从项目内起步,实际指向却可能不同,所以还要展开 ~ 和通配符、解析符号链接,再判断目标在不在项目里。
作者提到 Python 的 shlex 能帮忙做词法切分。实际会话用的是更完整的插件版本,约 680 行 Python,分在两个文件里,另有一个含 21 个用例的测试文件。每个用例覆盖一种具体写法,能说明这些输入的处理结果。
真实会话里,钩子保住了什么?
作者用 claude -p --plugin-dir ... 加载插件,环境是 Claude Code 2.1.330 和 Haiku 模型。他让 Agent 在有一行未提交改动的仓库里运行 git reset --hard HEAD。钩子取消了调用,并提示可以先提交、先暂存到 stash,或者交给人执行。Agent 转述了提示,没有换一种方式丢弃改动,那一行也确实留在文件里。
这次实测验证了整条链路,从钩子取消调用,到 Agent 收到提示,再到文件状态保持原样。它只覆盖一次会话。原文没有给出其他模型面对同一条提示的对照结果。
我的判断
最值得借鉴的是拦截消息。普通权限弹窗让人临场判断是否放行,钩子适合把团队已经定下的规则重复执行。遇到 git reset --hard 时,告诉 Agent 先检查改动、再考虑提交或 stash,比只回一句「禁止执行」更容易让任务继续。至于哪种提示最有效,原文没有对照数据,这部分是经验之谈。
这套做法还有个前提,判断依据是命令文本。看到 python3 script.py 时,钩子读到的是启动脚本的命令,脚本里的文件操作得靠执行环境约束。Agent 如果还能改 .claude/hooks/ 或 .claude/settings.json,规则本身也可能被改掉。把 .claude/ 纳入 Git,可以在 git status 里看见配置变化。若团队需要限制脚本能访问哪些文件,就该把控制放到沙箱或文件权限层。
能拿来做什么
- 给 Claude Code 接入钩子时,先选团队明确要人工处理的命令,例如
git reset --hard和git push --force,并在拦截消息里写清 Agent 可以怎么继续。 - 改规则后,直接用 JSON 喂给脚本,检查退出码和提示。既测必须拦住的命令,也测项目内正常清理
build这类应该放行的操作。 - 把
.claude/提交进仓库,把钩子配置和脚本一起纳入代码审查,尤其留意有哪些命令会因为一次规则变更被放行。