Claude Code Hook真正解决的不是“少提醒AI”：而是把关键规则移出模型自由发挥

AH-0115最值得保留的核心不是“五个即配即用Hook”，而是一条工程原则：

> 关键约束不要只写进提示词；能交给环境强制执行的，就交给环境。

源文举的场景很真实：Agent说“完成了”，但漏了格式化、测试或提交。Hooks把某些动作绑定到生命周期事件，减少“模型记没记住”的不确定性。

这个方向到2026年仍然成立。

但Hook也不能被神化成“只要配置了，质量就一定保证”。

Prompt、Hook、CI不是三选一，而是三层控制

Prompt / Instructions

适合表达：

• 目标；
• 设计偏好；
• 非机械判断；
• 任务上下文。

它的优点是灵活。

缺点也是灵活：模型可能理解偏差、漏掉、在冲突约束下做取舍。

Hook

适合生命周期中的自动反应：

• 工具使用前拦截；
• 文件修改后格式化；
• 事件日志；
• 通知；
• 任务停止前检查；
• 上下文注入。

Hook比Prompt更接近控制平面。

CI / Deterministic Validator

适合真正必须满足的验收：

• 单元测试；
• 类型检查；
• lint；
• build；
• schema validation；
• security scan；
• policy checks。

如果一个条件关系到“代码到底能不能合并”，最终真相最好来自测试/CI，而不是模型自己说“我检查过了”。

Hook会执行，不等于Hook的判断一定正确

这是源文最需要补的一层。

比如你挂了PostToolUse格式化Hook：

如果：

• matcher写错；
• 脚本失败；
• formatter没有覆盖该文件类型；
• Hook输出被忽略；
• 工具本身没有安装；

那“已经配置”不等于“已经成功格式化”。

所以每个Hook至少要有：

Trigger 什么事件触发。

Matcher 触发范围。

Action 执行什么。

Failure Mode 脚本失败怎么办。

Visibility 用户/Agent能不能看到失败。

Blocking 失败会阻止后续动作，还是只记录。

Evidence 如何证明这次真的执行成功。

当前Claude Agent SDK依然把Hook作为正式控制机制

Anthropic当前Agent SDK文档仍提供Hook配置，包含PreToolUse、PostToolUse、UserPromptSubmit、Stop、SubagentStop、PreCompact等事件；文件系统设置源也继续区分user、project和local三种作用域。

这验证了源文的核心架构思想：

生命周期事件 + 匹配器 + 执行动作 + 配置作用域。

但事件集合、支持范围和SDK/CLI差异是动态事实，因此不应该永久背“20多个事件”。

正确教程应该先看当前官方reference。

PreToolUse最适合做什么？

不是写一个“万能危险命令正则”。

而是保护高后果边界。

例如：

• 不允许写生产环境密钥文件；
• 不允许未经确认操作某目录；
• 删除/迁移前要求额外确认；
• 特定工具必须满足前置状态。

但安全Hook同样不能取代权限系统。

如果Agent已经拿到过大的系统权限，靠一个自写Shell脚本兜底并不够。

安全层最好是：

Least Privilege → Permission → Hook → Audit

而不是只靠Hook。

PostToolUse最适合做机械、幂等的动作

例如：

• formatter；
• linter；

-生成变更记录； -局部静态检查。

机械动作最适合从模型判断中抽走。

但如果每改一个文件就跑全量测试，会导致成本/延迟失控。

所以要区分：

Fast Local Check 每次修改运行。

Task-level Check 一个任务完成时运行。

Merge Gate CI最终运行。

这就是Control Placement。

Stop Hook不能把“完成”定义权交回AI

一个很常见的反模式：

Stop时再问另一个模型： “任务真的做完了吗？”

这比没有检查强，但仍然是模型判断模型。

更稳的是：

• acceptance checklist；
• tests；
• expected files；
• clean git diff；
• build result；
• migration validation；

这些确定性证据。

模型只负责解释失败，不负责凭语气宣布通过。

HTTP Hook要注意数据外发

源文提到HTTP Hook适合审计和团队通知。

这类能力很有用。

但事件Payload可能包含：

• 文件路径；
• 命令；
• 项目名；
• 提示内容；

-工具参数； 甚至敏感数据。

所以发往第三方URL前需要：

• redaction；
• allowlist；
• authentication；
• retention；
• TLS；
• data processing policy。

“自动审计”不能反过来制造数据泄露。

网站资产：Agent Hook Control Plane Lab

本批实际生成 agent_hook_control_plane_lab.html。

你可以录入一个规则，例如：

“任何代码修改后必须格式化”。

然后选择：

• Prompt；
• PreToolUse；
• PostToolUse；
• Stop；
• CI；

以及是否需要Blocking、Evidence、Audit。

工具会提示：

这个规则应该放在哪一层，以及你有没有把关键质量交给模型自我声明。

这才是Hook真正值得学习的地方。

不是背五个JSON模板。

而是学会：

> 哪些事情应该让Agent决定，哪些事情应该由系统无条件执行，哪些事情必须有外部证据才能算通过。