# Hook 生命周期模式

## 问题

如果没有中心化的 hook 生命周期，扩展性会退化为混乱：hook 作者在 Agent 执行的任意点附加副作用，没有一致的信任执行，并发 hook 之间没有确定性排序，也没有结构化的方式将阻止决策传回调用者。外部 hook 可能在工作区信任建立之前执行，导致从不受信的配置文件进行远程代码执行。长时间运行的 hook 如果在没有正确注册表交接的情况下自行转为后台运行，会留下孤儿进程，在意想不到的时间传递过时或矛盾的信号。

这些问题出现在任何支持可扩展 hook 点的 Agent 运行时中——并非特定于某个具体实现。

## 黄金法则

### 所有 hook 流经单一分发点

永远不要让 hook 执行分散在多个调用处。单一分发函数是信任检查、来源合并、类型路由和结果聚合的咽喉。如果添加新的 hook 类型，分发点是唯一需要更改的地方。分散的执行处在信任执行或结果处理上不可避免地会偏离。

### 信任是全有或全无的

在任何 hook 触发之前，恰好检查一次工作区信任。如果信任尚未建立，跳过所有 hook——不仅仅是外部的。包括进程内 hook。这防止了一种半信任状态，其中某些 hook 执行而另一些不执行，这种状态比干净地全部跳过更难调试，产生不可预测的行为。

### 多个来源以显式优先级合并

Hook 来自多个来源：持久化配置、编程 SDK 注册和临时的会话作用域注册。将它们合并为具有定义优先级分层的单一有序列表。当企业策略限制 hook 时，整个来源层被干净地排除，而非逐个过滤 hook。

### 退出码承载语义权重

对于外部进程 hook，为特定退出码保留特定含义。一个码表示成功。一个特定码表示"阻止此操作并将我的错误消息注入 Agent 的上下文"。所有其他非零码表示"警告用户但不阻止"。这种三级约定让外部脚本无需结构化 JSON 输出即可控制 Agent 行为。

### 拒绝优于询问优于允许

当同一批次中的多个 hook 返回冲突的权限决策时，应用严格的优先级：拒绝覆盖询问，询问覆盖允许，穿透永远不设置聚合决策。这种确定性解析在 hook 不一致时消除了歧义。

### 会话 hook 在设计上是临时的

在运行时为特定 Agent 会话注册的 hook 必须作用域限定于该会话的 ID，并在会话结束时自动清理。它们永远不应写入持久化配置。如果子 Agent 注册了一个 hook，该 hook 不能在父 Agent 的会话或兄弟子 Agent 的会话中触发。这种隔离防止并行扇出期间的跨会话副作用。

## 适用场景

- 你的 Agent 运行时暴露了外部代码可以 hook 的生命周期事件。
- 你需要任何 hook 类型都无法绕过的信任执行。
- Hook 来自多个必须确定性合并的配置来源。
- 你支持同步阻塞 hook 和长时间运行的后台 hook。
- 多个 hook 可能对同一操作返回冲突的权限决策。
- 你需要会话结束时自动清理的会话作用域 hook。

## 权衡

| 决策 | 收益 | 代价 |
|---|---|---|
| 单一分发点 | 信任、路由和聚合集中一处 | 每种 hook 类型都必须符合相同的分发接口 |
| 全有或全无的信任门控 | 无半信任状态，简单的心智模型 | 不构成安全风险的进程内 hook 也被阻止 |
| 多来源合并与优先级 | 干净的策略执行，可预测的排序 | hook 作者必须理解自己属于哪个来源层 |
| 多种 hook 类型 | 每项工作有合适的工具（进程、LLM、HTTP、进程内） | 更多类型面需要文档和维护 |
| 异步生成器组合 | 流式部分结果，阻塞错误可早期退出 | 调用者必须处理增量累积 |
| 通过注册表交接的后台化 | 长时间运行的 hook 不阻塞主循环 | 如果跳过注册表交接有孤儿风险 |
| 会话作用域 hook | 临时 hook 在会话结束时自动清理 | 作用域限定于一个会话的 hook 不在子 Agent 会话中触发 |
| 跨来源去重 | 同一 hook 出现在多个配置中时不会重复触发 | 去重键设计必须考虑来源特定前缀 |

## 实现模式

- 将每次 hook 调用路由到单一分发函数。此函数是信任检查、来源合并、类型分发和结果聚合的唯一位置。
- 将信任检查实现为分发中的第一个操作。如果信任缺失，立即返回空结果——不评估哪些 hook 本应匹配。
- 按定义的优先级顺序合并 hook 来源（如持久化配置、SDK 注册、会话作用域）。当策略标志限制为仅管理的 hook 时，排除整个来源层而非过滤单个条目。
- 使用包含来源特定上下文的复合键跨来源去重。来自不同插件的两个相同命令的 hook 是不同的；来自用户配置和项目配置的相同命令折叠为后者优先的条目。
- 至少支持以下 hook 类型类别：外部进程（shell 命令）、LLM 子调用、子 Agent 委派、HTTP 端点、具有完整输出控制的进程内回调，以及用于简单允许/拒绝决策的轻量布尔门控。
- 使用异步生成器组合并行运行所有匹配的 hook。每个 hook 在可用时产出类型化的结果片段。分发函数合并所有生成器并向调用者产出聚合的片段。
- 对于外部进程 hook，将退出码映射到语义结果：一个码表示成功，一个保留码表示阻塞错误（错误消息在 stderr 上），所有其他非零码表示非阻塞警告。
- 支持两种后台化模式：静态（在 hook 配置中于执行前声明）和动态（hook 将后台化信号作为第一行输出发出）。后台化的 hook 被交接到待处理 hook 注册表，以便跨轮次跟踪。
- 将会话 hook 作用域限定于特定的 Agent 或会话 ID。主会话下注册的 hook 不在子 Agent 会话中触发。提供显式移除函数，但也在会话结束时自动清除所有会话 hook。
- 聚合多个 hook 的权限决策时，应用严格优先级：拒绝优于询问，询问优于允许，穿透被忽略。
- 根据所需能力选择 hook 类型。使用外部进程 hook 进行 shell 级副作用。使用 LLM 子调用 hook 当 hook 本身需要推理时。使用 HTTP hook 进行外部服务集成。使用进程内回调当 hook 需要对结构化输出字段（权限决策、注入上下文、输入重写）的完全控制时。使用轻量布尔门控当你只需要对对话历史进行是/否决策而无需 JSON 序列化开销时。
- 注册进程级清理处理器在关闭时终止所有运行中的 hook。没有这个，后台化的 hook 会在父进程之后存活成为孤儿。
- 防范事件类型限制：某些事件可能与某些 hook 类型不兼容。例如，在早期会话设置期间的 HTTP hook 可能在响应消费者准备好之前触发事件时死锁。在分发层而非依赖 hook 作者自行发现来记录这些限制。

## 踩坑指南

**信任门控阻止所有 hook 类型，不仅仅是外部的。** 每个 hook——包括进程内回调和布尔门控——在信任缺失时都被跳过。永远不要因为 hook 在进程内运行就假设它已触发。如果 hook 未触发，首先检查信任状态。

**缺失的外部脚本可能产生与故意阻止相同的退出码。** 如果 hook 脚本在注册和执行之间被删除，shell 本身可能以保留的阻塞码退出。在注册时而非仅在执行时验证 hook 脚本存在。

**策略限制模式静默丢弃会话 hook。** 当企业策略将 hook 限制为仅管理来源时，技能或子 Agent 注册的会话作用域 hook 收到零匹配且无错误。管理和非管理部署之间的测试行为可能不同。

**带"唤醒"语义的后台 hook 绕过待处理注册表。** 正常后台化的 hook 出现在注册表中，在下一轮之前被解决。唤醒式 hook 设计上跨轮次存活——它们在以阻塞退出码完成时注入任务通知来唤醒模型，而非出现在待处理 hook 注册表中。不要对必须在下一次工具调用前完成的 hook 使用唤醒。

**布尔门控 hook 不可序列化。** 仅返回 true/false 的轻量进程内门控本质上是临时的。它们被排除在配置快照、分析和遥测之外。如果需要持久性或可观测性，使用完整回调类型。

**去重使用后者优先，可能让多作用域作者意外。** 当相同的 hook 命令同时出现在用户级和项目级配置中时，项目级条目胜出。去重键中的来源特定前缀防止跨来源冲突，但同来源冲突被静默解决。

**HTTP hook 在早期生命周期事件中可能死锁。** 如果 HTTP hook 为会话启动或设置事件注册，出站请求可能在响应消费者准备好之前触发，造成死锁。分发层应显式过滤不兼容的 hook 类型/事件类型组合，而非留给 hook 作者处理。

**会话 hook 在会话清理后不可见。** 一旦会话结束且其 hook 被清除，不留下它们曾存在的记录。如果调试需要理解过去会话中哪些 hook 是活跃的，你需要单独的日志——会话存储本身是临时的。

## Claude Code 实证

Claude Code 的 hook 系统是这些原则的生产实现，支持六种 hook 类型，覆盖数十个生命周期事件。

**带信任门控的单一分发。** 所有 hook 执行流经一个异步生成器函数。它做的第一件事是检查工作区信任。在交互模式下，这要求用户已接受信任对话框。在 SDK（非交互）模式下，信任是隐含的。如果信任缺失，生成器立即返回——不触发任何类型的 hook。

**三层来源合并与策略执行。** Hook 按优先级顺序从三个来源提取：来自设置文件的快照 hook、SDK 注册的回调 hook，以及存储在基于 Map 的会话状态中的会话作用域 hook。当企业策略设置仅管理标志时，会话和插件 hook 在来源合并层被排除，而非逐个过滤。这意味着策略执行是一个单一条件，丢弃整个来源列表，而非需要为每种新 hook 类型维护的逐 hook 过滤。

**流式结果的异步生成器组合。** 每个 hook 作为独立的异步生成器运行，产出类型化的结果片段——阻塞错误、权限决策、额外上下文、修改后的输入。并行合并工具组合所有生成器，使调用者在片段到达时接收它们。这对阻塞错误至关重要：批次中的慢 hook 不会延迟快 hook 的阻塞信号。

**基于 Map 的会话状态用于并发。** 会话 hook 对会话存储使用 Map 而非普通对象。Map 修改返回相同的容器引用，因此应用存储的相等性检查看不到变化，存储的监听器都不触发。这避免了并行子 Agent 扇出期间的二次方监听器通知成本，此时许多 hook 可能快速连续注册。设计教训是通用的：当存储支持的数据结构在并发操作期间接收频繁写入时，选择一个其修改不触发变更检测级联的容器。

**两种模式的后台化。** Hook 可以静态后台化（在配置中声明）或动态后台化（hook 在做实际工作之前发出后台化信号作为第一行输出）。更进一步的变体，"唤醒"后台化，用于必须跨多个 Agent 轮次存活的 hook——在以阻塞退出码完成时，它们注入任务通知来唤醒模型，而非出现在待处理 hook 注册表中。这种三级后台化设计反映了现实世界中 hook 生命周期的范围：同轮次、下一轮次和跨多轮次。

**权限优先级。** 当多个 hook 对同一工具使用事件返回冲突的权限决策时，聚合遵循严格优先级：拒绝覆盖询问，询问覆盖允许，穿透被忽略。这确保单个注重安全的 hook 始终可以否决，无论有多少宽松的 hook 也回应。

**六种 hook 类型各有独特角色。** 系统支持命令 hook（shell 进程）、prompt hook（LLM 子调用）、Agent hook（完整子 Agent 委派）、HTTP hook（要求 JSON 响应的外部服务调用）、回调 hook（具有完整结构化输出控制的进程内函数），以及函数 hook（仅对对话历史的会话级布尔门控）。回调/函数的分离是刻意的：回调遵循与外部 hook 相同的协议，可以影响权限、注入上下文和重写输入。函数 hook 仅接收消息历史并返回布尔值——它们存在是为了无 JSON 序列化开销的轻量验证，且永远不被持久化或包含在遥测中。

**退出码纪律。** 外部命令 hook 遵循严格的三级约定：退出 0 是成功，退出 2 是阻塞错误（其 stderr 消息被注入模型的上下文），任何其他非零退出是非阻塞警告——向用户显示但不停止执行。这一约定让 shell 脚本作者仅使用进程退出码就能细粒度地控制 Agent 行为。

**来源感知键的去重。** 当相同的 hook 命令出现在多个设置作用域（用户、项目、工作区本地）时，合并层使用复合键去重。对于来自同一来源的 hook，后者优先。对于来自不同插件根的 hook，去重键中的来源特定前缀防止跨插件冲突被静默折叠。