排查 Windows 下 Claude Code 钩子漏拦截
文章指出,仅匹配 Bash 的 PreToolUse 钩子可能漏掉独立的 PowerShell 工具调用,导致保护规则未覆盖实际命令。提供 PowerShell 检查命令,并提醒检查匹配器及脚本执行环境。
AI 深度解读
Windows 上的 Claude Code hook 配好了,危险命令却可能根本没经过它。作者排查自己发布的防护包后发现:规则和脚本测试都通过,真正漏掉的是工具调用到脚本之间的配置。
这篇文章最有用的结论是:防护是否有效,取决于整条调用链。工具名有没有匹配、脚本怎样启动、异常怎样退出,都要验证。对在 Windows 上用 AI 操作代码仓库的程序员,这比再添几条拦截正则更值得先检查。
十秒钟先查:你的规则能收到 PowerShell 调用吗
作者建议先在 PowerShell 执行这条检查命令:Get-Content .\.claude\settings.json -Raw | ConvertFrom-Json | ForEach-Object { $_.hooks.PreToolUse } | Select-Object matcher。
看输出中的 matcher。按原文描述,Windows 上的 Claude Code 除了 Bash 工具,还可能通过独立的 PowerShell 工具执行命令。PreToolUse 按工具名称匹配,配置成 "matcher": "Bash",就收不到 PowerShell 工具的调用。
脚本里即使写了针对 Remove-Item -Recurse、rd /s、del、format C: 的规则,也没有机会执行。作者给出的修复是 "matcher": "Bash|PowerShell"。
脚本通过测试,只能证明它处理过测试输入,不能证明真实调用会到达它。
这是作者亲自踩过的坑。他的防护包 v1.0.0 已经包含上述四类命令的匹配规则,测试也全部通过,但测试直接调用脚本,绕开了 settings.json。配置没有接通,规则再完善也无用。
这里应当区分作者的实测与适用范围:他确认了自己防护包中的缺陷;原文没有交代所用 Claude Code 版本,也没有列出不同安装方式下的工具差异。检查时要以当前会话实际加载的工具和 hook 为准。
启动方式和退出码,决定防护怎样失效
第二个问题发生在脚本启动阶段。
常见的 shell form 把整条命令塞进一个字符串。原文举例使用 powershell -NoProfile -ExecutionPolicy Bypass -File 启动脚本。作者指出,这种形式还要经过一层 shell:Windows 上可能是 Git Bash,未安装时则可能是 PowerShell。项目路径带空格时,引号也必须正确穿过这一层。
作者推荐用 exec form,把可执行文件和参数分开,减少 shell 与引号处理带来的变量:
{
"type": "command",
"command": "powershell.exe",
"args": [
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
"${CLAUDE_PROJECT_DIR}/.claude/hooks/block.ps1"
],
"timeout": 15
}
重点看 args:按作者描述,每个元素作为一个完整参数传入,${CLAUDE_PROJECT_DIR} 在启动前替换。因此,C:\My Projects\thing 不会因为空格拆成多个参数。原文还提醒,设置 args 后,shell 字段会被忽略。这里的 timeout 是 15,但文章没有展开说明其单位及超时后的处理。
第三个问题更容易被忽略:hook 用退出码表达处理结果。
文章以 exit 2 表示阻断,以 exit 0 表示放行,并指出其他非零退出码可能让危险命令继续执行。PowerShell 脚本抛出未处理异常时,不能想当然地认为「脚本报错,所以操作被拦住了」。
下面这段示例把读取输入、解析 JSON 和规则判断一起放入异常处理,拦截普通强推:
$ErrorActionPreference = 'Stop'
try {
$raw = [Console]::In.ReadToEnd()
$data = $raw | ConvertFrom-Json
$command = [string]$data.tool_input.command
if (-not [string]::IsNullOrWhiteSpace($command)) {
# 刻意放行 --force-with-lease,避免误拦后用户禁用整个 hook。
if ($command -match '(?i)\bgit\s+push\b.*\s(--force|-f)(\s|$)') {
[Console]::Error.WriteLine("BLOCKED by hook: force push. Command: $command")
exit 2
}
}
} catch {
# 输入无法解析或发生其他异常时主动放行。
# 这是故障放行策略,需要明确接受其后果。
exit 0
}
exit 0
最需要看的是 catch 中的 exit 0。作者选择故障放行(fail-open),让损坏的 hook 不至于卡住工作;代价是异常时防护失效。故障阻断(fail-closed)则可能因一条异常输入阻塞会话。文章没有证明哪一种普遍更好,强调的是必须主动选择。
只把 ConvertFrom-Json 包进 try/catch 还不够,后面的规则处理同样可能抛异常。
测试要覆盖放行,也要验证配置接通
hook 从标准输入接收 JSON,所以测试不需要先启动 agent。作者把包含 tool_name、tool_input.command 的输入送给脚本,再读取 $LASTEXITCODE:对于 git push --force origin main,预期是 2。
但这只是第一层。
第二层要验证正常操作返回 0。原文特别点名 git push --force-with-lease 和 rm -rf ./dist。作者认为,误拦常用操作会推动用户禁用整套防护。前端读者很容易理解后一种情况:清理构建目录是日常工作,规则需要理解允许范围。
第三层要读取真实的 settings.json,验证覆盖 Bash 的命令组也覆盖 PowerShell,并检查引用脚本存在、每个处理器配置超时、启动方式符合预期。这才是能抓住作者 v1.0.0 缺陷的测试。
最后还要进入实际会话,通过 /hooks 查看预期 matcher 是否加载,再触发一次应被阻断的调用,观察自己脚本输出的 BLOCKED 消息。
防护测试需要同时证明三件事:该拦的拦住,该放的放行,真实调用能到达规则。
我的判断
作者最有价值的经验,是把测试边界从脚本扩展到了配置和真实会话。单测直接调用函数很方便,却可能绕过工具名匹配、进程启动和输入传递;这类测试盲区在日常开发里也很常见。
但文章开头把 hooks 称为 agent 与破坏性命令之间唯一可编程的阻挡,表述偏绝对。它没有比较仓库权限、受限执行环境、Git 分支保护等做法,也没有给出实际事故率或误拦率的对照数据。其可靠性收益属于经验判断,不能据此承诺完整防护。
正则示例也有明确边界:它展示的是字符串匹配,没有证明能识别脚本间接调用、命令别名或所有等价写法。放行 --force-with-lease 是作者的规则选择,也不代表每一次相关操作都安全。
文章附带 MIT 开源精简版,以及售价 $29 的完整包,后者包含三个 hooks、两个 subagents、两个 skills、安装器和 74 个测试案例。这些是产品信息;案例数量本身不能证明覆盖完整,文章也没有提供购买前后的效果对照。
能拿来做什么
- 如果你在 Windows 上用 Claude Code 操作仓库,先检查
PreToolUse.matcher,再用/hooks核对实际加载情况。把 PowerShell 调用纳入验证范围。 - 给现有规则补一组允许案例,例如正常清理
./dist和团队允许的 Git 操作,同时检查退出码,避免规则干扰日常前端构建。 - 把
settings.json纳入测试,检查 matcher、脚本路径和超时配置。涉及带空格的项目路径时,验证参数是否完整传入。 - 明确异常时选择放行还是阻断,并在项目说明里写清楚。最终验证优先在临时仓库或无害测试规则上完成,确认能看到预期的
BLOCKED消息。