结论先行:Hook 是围绕概率模型的确定性护栏——在工具调用前后的固定生命周期点执行你的脚本,能拦截、能改写、能旁路处理。凡是"必须 100% 发生"的规则(密钥不进上下文、代码提交前必须 format、mapper XML 不许改)都该用 hook 实现,而不是写进 prompt 祈祷模型遵守。Hook 和 prompt 的分工一句话:概率的事交给模型,确定的事交给 hook。

Hook 点在哪

以 Claude Code 为代表的主流 harness 都提供类似的钩子体系,常见事件点:

事件点触发时机能否阻断典型用途
PreToolUse工具调用执行前能(拦截或改写入参)危险路径拦截、参数规范化
PostToolUse工具调用执行后不能(结果已产生)格式化、lint、结果校验、追加提醒
UserPromptSubmit用户输入提交时能输入预处理、敏感词过滤
Stop / SessionEnd回合或会话结束不能通知、归档、成本汇总

每个 hook 本质是一个收到 JSON stdin 的本地命令:harness 把事件上下文(工具名、入参、会话信息)写进来,你的脚本处理后决定放行还是拦截。约定优于集成——hook 不需要 harness 提供任何插件 API,任何能读 stdin、写退出码的可执行程序都能当钩子,bash、python、编译好的二进制都行。

hook 和权限系统是什么关系?两者都是确定性机制,但管的事不同:权限规则(allow/deny)管"这类操作允许吗",是策略;hook 是策略之外你自己脚本的执行位,管"允许的操作在执行前后还要发生什么",也可以充当策略的自定义实现。分工上建议简单规则走 allow/deny(引擎原生匹配,零维护),带业务逻辑的判断(路径组合规则、多条件联动)才写 hook——hook 脚本每多一行正则,就多一分未来要人维护的负债。AGENTS.md 里的软约定和 hook 的硬约束也常常成对出现:说明书告诉模型"为什么不能这么做、该走什么路",hook 保证"就算模型忘了也过不去"。一个规则先写进 AGENTS.md 观察违反频率,违反多了就升级成 hook,这是软约束硬化的常见路径。

实战一:拦截危险写入

mapper XML 由 DBA 统一管理的团队,用 prompt 说一百遍不如 hook 挡一次:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "python3 /srv/hooks/guard_paths.py"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "sh -c 'FILE=$(echo \"$HOOK_INPUT\" | jq -r .tool_input.file_path); case \"$FILE\" in *.java) google-java-format -i \"$FILE\";; *.ts) prettier --write \"$FILE\";; esac'"
      }
    ]
  }
}
# /srv/hooks/guard_paths.py(示意)
import sys, json

event = json.load(sys.stdin)
path = event["tool_input"].get("file_path", "")

BLOCKED = ("src/main/resources/mapper/", ".env", "pom.xml")
if any(p in path for p in BLOCKED):
    # 非零退出 + stderr 会作为拦截原因反馈给模型
    print(f"禁止修改 {path}:清单外文件改动需走人工流程", file=sys.stderr)
    sys.exit(2)
sys.exit(0)

模型撞上拦截会把原因读进上下文,下一轮自然调整方向——这比 prompt 里的软约束可靠,因为它根本没有"忘记"的可能。

实战二:提交前强制 format

PostToolUse 挂在 Edit 之后,对改动文件自动跑 formatter(配置见上一节的合并示例)。这类"格式化、lint、生成文件后追加提醒"的动作放在 PostToolUse,模型不需要知道它发生了,风格一致性却始终成立。PreToolUse 与 PostToolUse 的选位逻辑很简单:要在事情发生前挡住的放前面,要在事情发生后补救的放后面;拿不准放哪边时问一句"这个动作如果晚了一步,后果还能挽回吗"。

设计守则

Hook 脚本要快:PreToolUse 在每次工具调用的关键路径上,脚本本身超过一两秒就会明显拖慢整个循环,重活(比如全量安全扫描)放到 PostToolUse 或异步队列。拦截信息要给模型可执行的指导:“不许改"要配上"那该怎么办”(走什么流程、找谁),否则模型会在原地反复尝试。

对比一组错误写法与正确写法:

# 错误写法:解析失败直接抛异常,hook 卡死整个工具调用链
import sys, json
event = json.load(sys.stdin)          # stdin 为空或非 JSON 时这里崩
if event["tool_input"]["file_path"].startswith("pom.xml"):
    sys.exit(2)                       # 只说"不许",不给出路

# 正确写法:解析失败保守放行并记日志,拦截信息带替代路径
import sys, json, os
try:
    event = json.load(sys.stdin)
    path = event["tool_input"].get("file_path", "")
except Exception:
    log_line("parse_error")           # 放行但留痕,事后可查
    sys.exit(0)
if "pom.xml" in path:
    print("禁止直接改 pom.xml:依赖变更请在最终回复中列出并在 PR 说明,由人工合入",
          file=sys.stderr)
    sys.exit(2)
sys.exit(0)

日志必须全量落盘:hook 拦截记录是权限规则演进的最好素材,被拦次数多的路径说明规则该精细化或该补进 AGENTS.md。

性能预算上还有一个隐性约束容易被忽略:PreToolUse 是串行关键路径,模型每发起一次工具调用,所有匹配该工具的 hook 都要跑完才能执行。挂五个各三百毫秒的脚本,每次工具调用就凭空多出一秒半,长任务里会被放大成分钟级的体感劣化。所以 hook 的预算要按"单次调用总耗时"算而不是按单个脚本算;能合并的判断合并进一个脚本,能缓存的查找结果(比如禁改清单)启动时读一次内存里放着。hook 脚本本身也要有超时保护——harness 侧通常有超时配置,脚本内部对网络调用这类不可控操作同样要设上限,宁可本次跳过校验并记日志,也不要把关键路径挂死。

调试与灰度

Hook 脚本自身的 bug 比没有 hook 更糟——它会把整个工具调用链卡死。所以上 hook 前先在本地把 stdin 用假的 JSON 跑一遍,确认退出码和 stderr 符合预期:

# 上线前的离线自测:模拟 harness 喂进来的事件
echo '{"tool_name":"Edit","tool_input":{"file_path":"src/main/resources/mapper/OrderMapper.xml"}}' \
  | python3 /srv/hooks/guard_paths.py
echo "exit=$?"    # 期望输出 exit=2,且 stderr 含拦截原因

echo '{"tool_name":"Edit","tool_input":{"file_path":"src/main/java/Foo.java"}}' \
  | python3 /srv/hooks/guard_paths.py
echo "exit=$?"    # 期望输出 exit=0

脚本里对解析失败要保守处理,拿不到预期字段时宁可放行并记日志,也不要误拦截。离线自测的用例至少覆盖四类:正常放行、正常拦截、空 stdin、字段缺失。常见故障清单值得贴在团队文档里:stdin 为空(harness 版本升级改了事件结构)、脚本依赖的 jq/python 不在执行环境里、文件路径含空格没加引号、脚本没写 shebang 导致被当 shell 脚本解析、脚本里用了相对路径但 harness 的工作目录和开发时不一样。这五类占 hook 线上故障的绝大多数,且每一类都能在离线自测阶段暴露。灰度顺序也有讲究:先只挂 PostToolUse 这类"拦不住什么"的位置观察一周,日志确认无误后再上 PreToolUse 的硬拦截,全程保留一键摘除的能力(配置文件里注释掉即摘除)。

还有一条边界要守住:hook 只做确定性校验和机械动作,不做业务判断。发现"该不该改这个文件"需要理解业务上下文时,那是 reviewer 的工作,硬塞进 hook 脚本只会得到一堆脆弱的正则。

实战场景

一个 Java 团队的 hook 落地过程:团队规范要求 mapper XML 由 DBA 专属流程管理,此前靠 AGENTS.md 写了三个版本的"不要动 mapper",仍然每周有一两次模型顺手改了 XML 导致发布回退。改用 PreToolUse 拦截后,模型第一次撞墙就读到了拦截原因里"由 DBA 统一管理、需要时在 PR 中说明"的指引,自动转成在回复里列出建议的 SQL 变更,此后误改归零(定性观察)。第二步他们把 PostToolUse 的自动 format 挂上,一个月后 code review 里"格式不一致"类评论几乎消失,reviewer 的注意力转移到了真正的业务逻辑上。中间也踩过一个坑:早期版本的 hook 脚本对 stdin 做了无保护的 json.load,某次 harness 升级改了事件字段导致脚本整批崩溃,所有工具调用被卡死半小时——这正是"解析失败保守放行 + 离线自测 + PostToolUse 先行灰度"三条守则的来历。

检查清单

  • “必须 100% 发生"的规则全部用 hook 实现,prompt 里不再重复祈祷
  • PreToolUse 脚本执行时间控制在亚秒级,重活移到 PostToolUse 或异步
  • 拦截信息带可执行的替代路径,不让模型在原地反复撞墙
  • 解析失败保守放行并记日志,脚本崩溃不卡死工具调用链
  • 上线前用假 JSON 离线自测退出码与 stderr
  • 灰度顺序:先 PostToolUse 观察一周,再上 PreToolUse 硬拦截
  • 拦截记录全量落盘,高频拦截路径反哺 AGENTS.md 或权限规则
  • hook 只做确定性校验与机械动作,业务判断留给 reviewer