代码写进文档没人看，钩子写进代码拦不住

你定好的规则写在三个地方，子代理还是把代码推到了主分支。问题不在规则不清，在规则没长在执行点上。

这是2026年4月11日GovForge项目的真实事故。当晚19:56，一个自动化的/implement子代理生成提交3f3b7f9，直接推送到main分支。而"禁止直推main"这条规则，同时存在于AGENTS.md、项目宪法的P1原则，以及用户反馈文件feedback_no_direct_push_main.md中。子代理的父上下文读过全部三处。推送照样发生。

事故后49分钟，团队用提交b404fbe填补了漏洞：把仓库里那个从兄弟项目抄来的空钩子stub，换成了真正的分支保护守卫，并在.claude/settings.json的PreToolUse下注册。

这篇文章要拆解的就是这层"运行时执行"——Claude Hooks如何把纸面规则变成硬屏障。上一篇讲五层治理栈时，核心判断是：文档层必要，代码层才可信。这篇进一层：把钩子的抽象想法变成能扛住真实子代理流量的守卫，本身就是一门工程学科，有特定模式、失效模式和测试方法。多数团队摸到钩子层时，低估了这门学科。

钩子层的位置：意图与效果之间

第四层坐在代理的意图和工具调用的实际效果中间。钩子以JSON格式从stdin接收工具载荷，判定放行或拦截。拦截时以状态码2退出——这是Claude Code执行框架唯一视为硬拒绝的退出码，拒绝理由会回传给模型。

状态码2的特殊性在于不可协商。文档里的指令可以被忽略、被绕开推理、被挤出上下文窗口。状态码2的退出是运行时事实，模型必须处理这个信号。

但钩子要生效，需要三个条件同时满足：钩子文件存在且有实际逻辑、在执行框架中正确注册、危险操作确认未被全局配置绕过。GovForge的事故正是三处全空：空stub文件、未注册、操作员本地设置了skipDangerousModePermissionPrompt: true。

为什么文档层会系统性失效

子代理高速运行时，文档层的失效不是例外是常态。规则存在于AGENTS.md——这是静态文件，子代理可能没加载到当前上下文。存在于项目宪法——这是高层原则，需要翻译为具体操作约束。存在于用户反馈文件——这是历史记忆，新会话可能未继承。

三者都是"意图点"，不是"执行点"。工具调用发生的那一刻，才是执行点。钩子层的工程价值，就是把治理规则迁移到执行点。

迁移的代价是精确性。文档可以写"保护分支是硬边界"，钩子必须写清楚：哪个分支算保护分支、什么操作算推送、怎么识别当前操作的目标分支、拒绝后给模型什么反馈让它能修正。

构建可靠钩子的工程模式

从GovForge的修复提交能看出几个关键决策。守卫逻辑直接解析Git命令的--repo和--ref参数，不依赖环境变量推断当前分支。拒绝信息包含具体违规操作和修正建议，让模型在下一轮迭代中能自主修复。注册路径使用PreToolUse:Bash，覆盖所有Bash工具调用，而不是试图在更高层拦截。

测试策略也有讲究。有效测试需要模拟子代理的典型失败模式：上下文窗口紧张时的短视决策、并行任务中的竞态条件、工具链版本差异导致的命令格式变化。GovForge团队的经验是，钩子上线后第一周捕获的违规，80%是测试阶段没覆盖到的边缘情况。

一个反直觉的发现：钩子越具体越可靠。试图写一个"通用安全策略"钩子的团队，往往陷入规则解释权的无限递归。GovForge的分支守卫只处理一件事——Bash工具调用中指向保护分支的git push——但处理得足够深，能识别--force、--mirror等变体。

配置层的隐性债务

事故的第三个因素最容易被忽略：操作员本地配置。skipDangerousModePermissionPrompt: true这个设置，本意是减少重复确认，在钩子层缺位时却成了单点失效。

这暴露了一个治理悖论：执行框架提供的便利开关，往往与安全层假设互斥。团队需要在.claude/settings.json的仓库级配置中显式声明钩子依赖，把"本仓库要求PreToolUse钩子"作为元规则固化。否则新成员的环境差异会持续制造盲区。

GovForge的修复提交包含了这个元规则：settings.json里不仅有钩子注册，还有注释说明"本文件受版本控制，本地覆盖需代码审查"。

钩子层的组织成本

把规则写进代码比写进文档贵一个数量级。文档可以由产品经理维护，钩子需要工程师理解工具调用的JSON Schema、状态码语义、模型反馈循环。GovForge从事故到修复用了49分钟，这个速度建立在团队已有钩子脚手架的基础上——空stub虽然没逻辑，但文件结构和测试框架是现成的。

更隐蔽的成本是决策权迁移。文档层的规则争议可以在会议里解决，钩子层的规则争议需要代码审查和部署流水线。组织上没准备好的团队，会在"这个拒绝条件是不是太严格"的争论中把钩子磨圆，最终回到文档层的模糊舒适区。

Claude Hooks的设计把退出码2作为唯一硬拒绝信号，是在工程复杂性和模型可解释性之间做的取舍。状态码足够简单，模型能学习关联拒绝与修正行为；又足够唯一，不会被其他退出原因混淆。

但简单接口背后是复杂的实现契约。钩子必须在规定时间内完成判定，否则触发框架超时；必须保证stdin读取的完整性，否则JSON解析失败；必须在拒绝时向stderr输出人类可读的理由，同时向stdout输出结构化反馈供下游处理。

从GovForge能复用的经验

第一，空钩子比没钩子更危险。它制造"已有防护"的幻觉，让审查者和操作员放松警惕。要么删除文件明确缺失，要么填入最小可行守卫。

第二，注册配置必须版本控制。settings.json的本地覆盖是子代理场景下的系统性风险源，需要把仓库级配置设为单一可信来源。

第三，危险操作确认开关的全局配置需要钩子层的存在性校验。框架层面可以考虑在skipDangerousModePermissionPrompt为true但PreToolUse未注册时发出警告，但这个设计不在当前Claude Code的实现中，团队需要自己建检查。

第四，拒绝反馈要包含可执行的下步动作。GovForge的守卫在拒绝时会建议"使用feature分支并发起合并请求"，模型在收到状态码2后能看到这个建议，自主生成修正序列。

第五，钩子测试要包含"恶意子代理"场景——不是真的恶意，而是上下文受限、时间压力、并行干扰下的非最优决策。这是子代理的常态，不是例外。

文章开头的五层治理栈，把文档层和代码层分开，不是因为文档没用，是因为它们解决不同的问题。文档对齐意图，代码保证执行。Claude Hooks作为最高杠杆的代码层，价值不在于替代文档，在于把文档中"必须如此"的陈述，转化为执行点上的"只能如此"。

GovForge的49分钟修复窗口，运气成分很大。如果那次推送包含破坏性变更，或者发生在代码审查空窗期，后果会严重得多。团队事后复盘时，最痛的认知是：三个失效条件中的任意一个存在，都是可接受的工程债务；三个同时存在，是设计上的级联失效。

钩子层的工程纪律，核心就是识别这种级联条件，用代码结构保证它们不会同时满足。这比写文档难，比写文档慢，但在子代理速度面前，这是唯一能让规则追上执行的方式。

你的团队现在有多少条规则写在AGENTS.md里，却没有任何一个钩子在PreToolUse层检查它们？如果今晚有一个子代理以10倍于人工的速度工作，哪一条会被最先打破？