---
url: 'https://aisee.wiki/learn/hooks/index.md'
---
# Hook：在关键节点加上自动检查和约束

Hook 是 Agent 工作流中的自动化检查点，用来在关键时刻注入上下文、拦截风险、运行验证或记录结果。

## 为什么需要 Hook

Agent 执行速度快，但也容易越界、漏验证或忘记项目规则。Hook 的价值不在于“让 Agent 更聪明”，而在于把那些明确、重复、高风险、容易遗忘的检查挂到生命周期节点上。

如果没有 Hook，很多检查只能靠人反复提醒：

* 记得读项目规则
* 记得看危险命令
* 记得跑验证
* 记得在提交前检查工作区

Hook 解决的是“这些动作每次都该发生，但人很容易忘”的问题。

## 以 Codex Hooks 为例

这篇不再泛讲“所有 Agent 都有一套类似生命周期”，而是明确以 Codex Hooks 系统为例。原因很简单：不同平台的事件模型不完全一样，如果不先收敛到一个具体系统，读者很容易把概念和实现混在一起。

Codex 官方事件名包括：

* `SessionStart`
* `UserPromptSubmit`
* `PreToolUse`
* `PermissionRequest`
* `PostToolUse`
* `SubagentStart`
* `SubagentStop`
* `PreCompact`
* `PostCompact`
* `Stop`

## 最值得先用的事件

第一次理解或配置 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`，而不是事后补救。

::: warning Hook 的边界
Hook 不应该把所有流程都变成硬阻断，也不能替代人的判断。它适合处理明确、重复、高风险或容易遗忘的检查。
:::

## 与规则、Tool 和权限的关系

规则负责定义“应该怎么做”，Tool 负责真正执行动作，Hook 负责在关键节点检查、注入、拦截，权限系统则决定哪些动作需要额外批准。

`AGENTS.md`、OpenSpec 状态机和 Hook 共同形成约束层。规则告诉 Agent 应该怎么做，Hook 在关键节点帮助它不忘记、不越界、不漏验。

所以它们的职责边界可以这样理解：

* `规则`
  负责定义标准和边界。
* `Tool`
  负责执行动作并产生副作用。
* `Hook`
  负责把标准挂到动作前后，变成真正会被执行的检查点。
* `PermissionRequest`
  负责把高风险动作显式抬升到审批层，而不是静默继续。