结论先行:给 agent 加安全护栏(hook)后,护栏本身会成为新的故障源。这次教训:只读命令被误判为写操作拦截,绕了弯路才发现是规则匹配方式的问题。

现象

一条无害的只读组合命令(grep 管道拼 sed)被 PreToolUse hook 拦截,报"禁止修改源码"。命令本身没有任何写动作:

# 被 PreToolUse hook 拦截的组合命令(纯读取,无写动作)
grep -n "status" mapper/OrderMapper.xml | sed -n '1,20p'

诡异之处在于这条命令昨天还能跑。中间没改过命令本身,改的是 hook 的拦截规则——所以第一反应完全不会朝 hook 想。这也是护栏类故障的第一个特征:它伪装成被保护对象的故障。用户感知是"命令没跑成"“agent 卡住了”,而不是"护栏误伤了"。

先交代背景:PreToolUse hook 挂在工具调用链上,agent 每次要执行命令前先过一遍规则,命中拦截特征就拒绝执行并给出提示。我配它的初衷只有一个——拦住针对源码目录的动态写操作。机制本身很简单,而简单机制出问题时排查方向反而容易跑偏:没人会怀疑一个"只是做字符串匹配"的东西,这个盲区是本次事故的第一环。

排查过程:二分定位

  1. 单独跑 grep——通过
  2. 单独跑 sed(固定行号版)——通过
  3. grep 管道接 sed——被拦

三个数据点把问题钉死了:两个组件单独都无罪,组合才有罪,问题出在拦截规则对"组合"的判定上。回头看这个二分能在很短时间收敛,是因为坚持了一次只变一个变量:没有同时换命令写法加换参数,每一轮只分离出一个组件。

把这次的方法论抽出来是三步:先复现最小化——把组合命令拆到能触发拦截的最小形态;再变量分离——每轮只变一个部分;最后对配置 diff——回到最近改过的规则上找线索。顺序别乱,尤其最后一步:先定位到行为再回看配置,比拿着配置猜行为快得多。

结论浮出水面:hook 的规则是模式匹配,“grep + sed 同时出现"命中了"动态拼接修改命令"的特征。规则没有错,错在特征提取太粗。

根因:特征提取太粗

写规则时的假设是"sed 出现在管道里 = 动态拼接 = 有写风险”。这个假设在写它的那天看是合理的——绝大多数 sed 进管道确实是为了改写。但推理链有一环是概率性的:sed 出现不等于写操作,带 -i 的 sed 才是。把高概率特征当成充分条件,误伤只是时间问题。安全规则里每一个"通常如此"的假设,都会在足够大的命令空间里找到反例。

为什么规则会写粗?因为写规则时的心智模型是"我要防的那个场景",而规则上线后面对的是整个命令空间。要防的场景里 sed 都在改写,整个空间里 sed 大部分在打印。规则无法枚举善意,只能枚举恶意——所以特征必须选"恶意的确证信号",而不是"善意的缺席信号"。

修复:收紧匹配面

改法很简单:动态组合的判断只针对写类命令(Edit/Write/带 -i 的 sed),纯读取组合放行。规则示意:

{
  "matcher": "Bash",
  "rule": "仅当命令同时满足 (写类动词 edit|write|rm|mv|sed -i) 且 (含管道或 &&) 时拦截",
  "on_block": "原始命令全文落 hook-block.log,含时间与命中特征"
}

顺手把旁路记录也补上了。改动的原则不是"放宽",而是把判断依据从"可疑特征"挪到"确证特征":带 -i 的 sed 是确证,grep 管道接 sed -n 只是可疑。护栏宁可放过可疑,不能错杀确证无罪的。

修复后的验证要双向做:拿误拦的那条原始命令回归,确认放行;再拿几条真该拦的——带 -i 的 sed、往源码目录重定向的写——确认仍然拦住。只测第一个方向的规则修复,经常制造反向事故:误拦没了,护栏也没了。两条回归命令我都存进了 hook 配置旁边的注释里,改规则时顺手跑一遍。

三条沉淀

  • hook 的误报代价是隐蔽的:它不报错,只是"命令没跑成",用户感知为 agent 卡住或命令失效
  • 护栏要有旁路记录:每次拦截落一条日志,误拦才有排查入口
  • 给安全机制做减法和给功能做加法同样重要:每加一条拦截规则,问一遍误伤面在哪

安全机制的可信度 = 拦截率 − 误拦率。误拦多了,用户会直接关掉护栏,那才是真正的危险。

这个等式还有个时间维度:误拦的信任损耗比拦截的收益积累快得多——一次误拦就足以让用户记住"它会坏事",十次正确拦截未必被感知,因为正确拦截是无感的。所以护栏的调优要永远偏向保守:宁可少拦一件,不可错拦一件。

误报的隐蔽性还有个放大器:agent 遇到拦截提示时的反应通常是绕路重试——换个写法再试一次。绕路重试本身是好行为,但它把误拦的痕迹抹掉了:你看到的不是"被拦",而是"agent 绕了几圈最后换了种方式完成"。事后审计时,只有旁路日志能还原中间发生了什么。

后来我给新 hook 上线加了灰度:先跑"只记录不拦截"模式,把命中的命令全量落日志,人工过一遍误伤面,确认特征干净了再切成真拦截。这是功能发布的老办法,但用在安全机制上格外值——拦截规则没法自动化回归全覆盖,只能拿真实流量代替。

真拦截误拦截
命令内容含写动作纯读,特征巧合命中
用户感知正确阻止危险操作agent 卡住、命令失效
排查入口有日志即可定位必须有旁路记录才有入口
处理方式放行改写后的命令修规则、缩匹配面

真实场景

那天下午我在让 agent 排查一个 mapper 问题,连续两条命令"没跑成",模型开始换着法子重试同一件事。我的第一反应是模型抽风,甚至重开了一次会话——浪费的那几轮里,答案其实就躺在 hook 的拦截日志里,只是我当时不知道有这份日志。当时的权衡:可以先临时关掉 hook 恢复工作、日后再查,我选择了当场查,怕的是"关了忘开",护栏裸奔比误拦更危险。事后看,更优的路径是第一步就看拦截日志——这份日志能把排查从"猜"变成"读",前面那几轮浪费本可以省掉;“临时关闭"那个选项其实也能执行得更安全:关之前给自己留一条必须恢复的显式记录。这次之后我给所有 hook 加了两样东西:旁路日志,和一条写在配置注释里的"误拦时的第一排查入口”。补一个当时的体感:真正花在定位到 hook 上的时间占比很小,大头花在怀疑错对象上——先怀疑模型,再怀疑工具链。方向对了之后很快收敛。排查的瓶颈几乎总在假设列表,不在执行速度。

检查清单

  • 每条拦截规则写明判定特征,区分可疑特征与确证特征
  • 判断写风险依据确证特征(如 sed -i),不用高概率特征
  • 每次拦截落旁路日志:原始命令全文 + 时间 + 命中原因
  • 新规则上线前,用纯读组合命令回归一遍误伤面
  • agent 行为异常时,先查 hook 日志再怀疑模型
  • 临时关闭护栏要留显式记录,防止裸奔过夜