适合：任务会话初始化时注入规则、上下文、change 状态或项目级提示。
不适合：不要在这里直接改业务文件或执行高风险命令。Hook：在关键节点加上自动检查和约束
约 1150 字大约 4 分钟
2026-05-25
Hook 是 Agent 工作流中的自动化检查点，用来在关键时刻注入上下文、拦截风险、运行验证或记录结果。
CODEX HOOK EVENTS
本文以 Codex Hooks 系统为例，Hook 的价值取决于挂在哪个事件上。
适合：用户提交输入时做预检查或附加轻量提示。
不适合：不适合挂需要 matcher 的复杂逻辑，官方也不支持 matcher。适合：在 Bash、apply_patch、MCP tool 调用前拦危险动作、查路径和参数。
不适合：不要把每一次普通调用都变成繁琐阻断。适合：在即将弹审批时补充风险说明、权限解释或策略提醒。
不适合：不要假设所有高风险动作都会先进入这个事件。适合：工具执行后检查输出、diff、失败结果和下一步建议。
不适合：已经发生的副作用不能靠这个事件回滚。适合：一次 turn 结束时做收尾检查、结果记录或最终提醒。
不适合：不要把它当成“归档前”专用节点。SECONDARY EVENTS
这些事件存在，但通常不是第一批要先用好的节点。
- SubagentStart子代理启动时触发，适合补充上下文和边界提醒。
- SubagentStop子代理结束时触发，适合检查输出和结果汇总。
- PreCompact会话压缩前触发，适合保存重要上下文。
- PostCompact会话压缩后触发，适合确认关键信息没有丢失。
为什么需要 Hook
Agent 执行速度快，但也容易越界、漏验证或忘记项目规则。Hook 的价值不在于“让 Agent 更聪明”，而在于把那些明确、重复、高风险、容易遗忘的检查挂到生命周期节点上。
如果没有 Hook，很多检查只能靠人反复提醒：
- 记得读项目规则
- 记得看危险命令
- 记得跑验证
- 记得在提交前检查工作区
Hook 解决的是“这些动作每次都该发生，但人很容易忘”的问题。
以 Codex Hooks 为例
这篇不再泛讲“所有 Agent 都有一套类似生命周期”，而是明确以 Codex Hooks 系统为例。原因很简单：不同平台的事件模型不完全一样，如果不先收敛到一个具体系统，读者很容易把概念和实现混在一起。
Codex 官方事件名包括：
SessionStartUserPromptSubmitPreToolUsePermissionRequestPostToolUseSubagentStartSubagentStopPreCompactPostCompactStop
最值得先用的事件
第一次理解或配置 Hook，不需要把所有事件平均铺开。更值得先掌握的是这几个：
| 事件 | 适合挂什么 |
|---|---|
SessionStart | 注入项目规则、加载上下文、检查任务起始状态 |
PreToolUse | 拦危险命令、看路径、查参数、提醒高风险动作 |
PermissionRequest | 在即将弹审批时补充风险说明和权限解释 |
PostToolUse | 检查输出、diff、失败结果和下一步建议 |
Stop | 做一轮收尾检查、结果记录或最终提醒 |
它们之所以优先，是因为最贴近初学者能感知到的协作节奏：开始、调用工具、权限审批、看结果、结束。
Hook 能做什么
- 注入规则：提醒 Agent 读取
AGENTS.md、OpenSpec 工件和 memory 索引。 - 拦截风险：阻止删除、重置、上传密钥、生产操作。
- 运行验证：格式化、构建、测试、链接检查。
- 记录结果：把复盘、失败原因、可复用经验写到合适位置。
如果把 Tool 比作“手”，Hook 更像“手伸出去之前和收回来之后的检查闸机”。
子代理与压缩事件
除了前面那几类最常用事件，Codex Hooks 里还有一些更偏系统层的节点：
SubagentStart / SubagentStop适合在子代理启动或结束时补上下文和结果检查。PreCompact / PostCompact适合在会话压缩前后保存和恢复关键信息。UserPromptSubmit发生在用户提交输入时，适合做轻量预检查；官方文档里也明确说明它不支持 matcher。
这些事件不是不重要，而是通常不适合作为第一次理解 Hook 的入口。
Hook 的边界
Hook 并不适合处理所有问题。更准确地说，它最适合：
- 明确、可判断的规则
- 重复出现的检查
- 高风险动作前后的守卫
- 容易被忽略、但必须执行的验证
它不适合：
- 替代人工审查
- 承载复杂业务逻辑
- 把整个工作流都做成硬阻断
- 在没有明确标准时强行决定“对还是错”
另外还要明确一点：PostToolUse 只能在动作发生之后检查结果，它不能撤销已经发生的副作用。所以高风险动作最应该优先考虑的是 PreToolUse 和 PermissionRequest，而不是事后补救。
Hook 的边界
Hook 不应该把所有流程都变成硬阻断，也不能替代人的判断。它适合处理明确、重复、高风险或容易遗忘的检查。
与规则、Tool 和权限的关系
规则负责定义“应该怎么做”，Tool 负责真正执行动作，Hook 负责在关键节点检查、注入、拦截，权限系统则决定哪些动作需要额外批准。
AGENTS.md、OpenSpec 状态机和 Hook 共同形成约束层。规则告诉 Agent 应该怎么做，Hook 在关键节点帮助它不忘记、不越界、不漏验。
所以它们的职责边界可以这样理解：
规则负责定义标准和边界。Tool负责执行动作并产生副作用。Hook负责把标准挂到动作前后，变成真正会被执行的检查点。PermissionRequest负责把高风险动作显式抬升到审批层，而不是静默继续。
