跳到文章正文
Claude 实用教程

Claude Code怎么在执行前拦截工具?PreToolUse Hook与样本验证

从PreToolUse事件读取工具输入,返回明确deny决策;先用人工JSON测试,再在隔离项目…

项目需要在工具运行前执行确定性检查,可以使用PreToolUse Hook。它不同于聊天里一句“请小心”,也不同于操作系统沙箱。本文用永不执行真实删除的练习输入,说明事件、匹配和拒绝输出怎样衔接。

Claude Code怎么在执行前拦截工具?PreToolUse Hook与样本验证
Claude Code怎么在执行前拦截工具?PreToolUse Hook与样本验证

第一步:确认事件和匹配器

PreToolUse在对应工具调用前运行,matcher决定匹配哪些工具,command处理器从标准输入读取JSON。先检查现有Hooks配置并备份,避免覆盖其他有效条目;项目规则、权限与Hooks各自作用不同。

官方支持多种Hook类型,本文只讲同步command流程。不是所有事件都能用同样字段阻断,不能把另一个事件的输出照抄。配置与脚本本身也要审阅,因为它们会在本机执行。

第二步:写一个可静态测试的拒绝结果

练习脚本读取输入后,仅当tool_name为Bash且命令完全等于人工标记字符串时返回deny,其余不输出决策。标记不是危险命令,避免为验证拦截而实际执行破坏动作。

import json, sys
data = json.load(sys.stdin)
if data.get("tool_name") == "Bash" and data.get("tool_input", {}).get("command") == "DEMO_BLOCK_MARKER":
    print(json.dumps({"hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "deny",
        "permissionDecisionReason": "练习标记被Hook拒绝"
    }}))

第三步:先输入人工JSON测试

将脚本放入练习项目,使用人工JSON运行它,检查结果可解析且字段正确;再用另一个标记验证没有误拒绝。不要输出多余调试文字到标准输出破坏JSON,必要日志写入受控位置并脱敏。

{"tool_name":"Bash","tool_input":{"command":"DEMO_BLOCK_MARKER"}}

第四步:接入配置并核对触发

在PreToolUse下设置matcher为Bash,command指向已审阅脚本或明确Python调用路径。实际解释器与相对路径要在本机验证,不从其他机器复制绝对路径。先只在隔离项目测试,不全局部署。

接入后核对Hook是否被加载、输入是否到达、拒绝原因是否显示,以及工具没有执行。测试触发时使用无副作用标记;如果调用不存在而只是文本展示,不能算Hook已触发。

第五步:理解能力边界

这个练习只验证协议,不是阻止危险Shell的完整策略。真实命令可能包含包装器、子命令或不同工具路径,简单字符串搜索无法覆盖所有情况。访问控制应结合现有权限、沙箱与服务端授权,不靠一个正则宣布安全。

修改Hook后要重新测试命中和不命中两类,检查是否误阻止正常任务。失败时先查路径、解释器、输出格式和事件,而不是关闭所有检查继续操作。保留回滚副本和加载记录,清理练习配置时只移除本次新增条目。

Hook的输入应被视为外部数据,读取字段前检查类型与缺失值。脚本失败时也要记录明确状态,不把崩溃等同于允许或拒绝。正式使用前按当前官方退出码规则测试失败路径,避免只验证一条正常JSON。

官方资料

资料核对日期:2026年11月17日。

本文地址:https://www.163264.com/21507