Hook Engine 从受管要求、分层 config.toml/hooks.json 与插件清单发现 handlers，先应用 managed-only/trust/state 策略，再按事件 matcher 选中；命令以 JSON stdin、受限环境、cwd、timeout 和 kill-on-drop 并发执行。
本节只研究“Hook 从配置到外部命令完成”。输入是 ConfigLayerStack、PluginHookSource、event/matcher input、payload JSON，状态由 hooks Discovery/Dispatcher/CommandRunner 持有，成功输出为 按配置序排列的 CommandRunResult。相邻章节中看起来相似的对象如果由不同组件拥有，就不能用一个布尔状态替代。
先确定边界和状态所有者
| 问题 | 本节答案 |
|---|---|
| 谁发起 | ConfigLayerStack、PluginHookSource、event/matcher input、payload JSON |
| 谁拥有可变状态 | hooks Discovery/Dispatcher/CommandRunner |
| 成功产物 | 按配置序排列的 CommandRunResult |
| 不在本节内 | Hook 从配置到外部命令完成之外的上游产品策略和下游业务实现 |
这张表的用途不是复述名词，而是约束实现顺序：校验必须发生在副作用之前；已经提交的状态只能由原所有者撤销；只读投影不能反过来成为控制权威。
端到端调用链
- 低到高层发现 JSON/TOML/plugin hooks
- 生成稳定 hook key/应用 state/trust
- 按 event+regex matcher 选择
- 并发运行命令/JSON stdin
- 按 configured order 整理结果
这条链里至少有三种时间尺度：配置或身份在 Thread 创建时冻结，Turn 内状态由 Session 串行协调，Step 级目录与能力在每次模型采样前重新捕获。若把后一个时点的新状态拿去解释前一个时点已经发出的调用，就会产生跨代错误。
源码机制拆解
配置来源有明确顺序和 policy
先加入 managed requirements，再按配置层低优先级到高优先级读取 hooks.json 与 TOML，最后插件 HookSource；allow_managed_hooks_only 可排除非受管来源。
这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 hooks Discovery/Dispatcher/CommandRunner 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。
Trust 绑定规范化配置哈希
非受管 Command Hook 只有 trusted_hash 与当前规范化 handler hash 相同才进入运行列表；命令、matcher 或 timeout 改变后状态变为 Modified，需要重新信任。受管来源直接标为 Managed。
这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 hooks Discovery/Dispatcher/CommandRunner 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。
JSON 与 TOML 同层共存会警告
Engine 可以加载两者，但提示优先使用单一表示，避免同一 handler 被用户误配置两遍；访问过的 JSON folder 也会去重。
这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 hooks Discovery/Dispatcher/CommandRunner 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。
Matcher 不会因 alias 重复执行
PreToolUse 可同时拿 canonical tool name 和兼容 aliases；任一 regex 命中就选 handler，但每个 configured handler 只加入一次。UserPromptSubmit/Stop 不按 matcher 过滤。
这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 hooks Discovery/Dispatcher/CommandRunner 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。
当前只执行 Command Handler
Prompt/Agent handler 在 discovery 阶段给 warning 并跳过；标记 async 的 Hook 目前也不真正异步，只有 SessionEnd 接受该字段并仍同步执行。
这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 hooks Discovery/Dispatcher/CommandRunner 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。
并发完成、配置顺序消费
Handlers 用 FuturesUnordered 并行执行，记录 completion_order；最终按 configured_order 排列，让多个输出的合并语义稳定，不受某个脚本速度影响。
这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 hooks Discovery/Dispatcher/CommandRunner 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。
Python 风格伪代码
下面的伪代码提炼状态机与错误顺序，不逐行翻译 Rust，也不假装 Python 对象具有 Rust 的所有权保证：
async def dispatch_hooks(registry, event, matcher_names, payload, cwd):
handlers = [h for h in registry.handlers
if h.event == event and matches_any_once(h.matcher, matcher_names)]
pending = [run_hook_command(h, json.dumps(payload), cwd,
timeout=h.timeout_sec, kill_on_drop=True)
for h in handlers]
completed = await gather_as_completed_with_indexes(pending)
completed.sort(key=lambda item: item.configured_index)
return completed阅读这段伪代码时要检查三件事：第一，输入是否在副作用前完成规范化；第二，异步等待是否仍携带原 Thread/Turn/Step 身份；第三，失败后究竟释放了什么、又保留了什么。只写快乐路径会把本节最重要的一致性条件删掉。
失败、取消与恢复
| 故障点 | 已发生的状态 | 可观察结果 | 恢复责任 |
|---|---|---|---|
| hooks.json 解析失败 | 其他层仍可加载 | warning+跳过该文件 | 修正 schema |
| 命令 spawn/stdin/wait 失败 | CommandRunResult 有 error | 输出解析按失败处理 | 不崩溃 Session |
| 命令超时 | child kill_on_drop | timeout error/无有效 decision | 缩短脚本或调合法 timeout |
取消不自动等于回滚，列表不自动等于权威存储，模型看见的描述也不自动等于已经获准执行。对于已经建立的 Thread、写入的 Edge、入队的 Mailbox、安装的插件或外部工具副作用，必须由相应所有者执行显式关闭、补偿或保留。
并发与一致性不变量
- 同一身份不能在并发路径中被重复预留或重复注册；若允许幂等重试，幂等键必须是稳定路径、ThreadId、request id 或 catalog revision，而不是展示名称。
- 一次模型采样看见的 Prompt、工具目录和执行入口必须来自同一个 Step 快照；刷新只影响后续 Step。
- Watch/Activity/事件是通知机制，不是状态本身。被唤醒后必须重新读取 Registry、Session、Mailbox、Store 或 Binding 的权威值。
- 失败路径不得“为了干净”删除仍可恢复的历史；同样也不得把只剩历史的对象伪报成当前仍驻留运行。
设计思路与代价
本节设计保护的核心不变量是：Hook Engine 从受管要求、分层 config.toml/hooks.json 与插件清单发现 handlers，先应用 managed-only/trust/state 策略，再按事件 matcher 选中；命令以 JSON stdin、受限环境、cwd、timeout 和 kill-on-drop 并发执行。代价是同一个功能会跨越地址、配置、Session、队列、存储或扩展适配层，测试也必须覆盖正常、并发和中途失败。更短的单体实现虽然容易演示，却无法区分“存在、已加载、正在运行、可恢复、已关闭、模型可见”这些彼此独立的事实。
设计动机部分是根据生产类型、调用顺序和测试行为归纳；源码可直接证明的是字段、分支、状态所有者和失败结果。文章不会把推断写成服务端或产品层的未公开事实。
源码与测试证据
| 位置 | 能证明什么 |
|---|---|
codex-rs/hooks/src/engine/discovery.rs | 配置层/plugin 发现、policy 和稳定 key |
codex-rs/hooks/src/engine/dispatcher.rs | matcher、并发和顺序恢复 |
codex-rs/hooks/src/engine/command_runner.rs | shell、stdin、timeout 与输出捕获 |
codex-rs/hooks/src/events/common.rs | matcher 验证 |
| 测试/可执行检查 | 覆盖重点 | 预期 |
|---|---|---|
codex-rs/hooks/src/engine/mod_tests.rs | 正常、边界与状态转换 | 应与本节不变量一致 |
codex-rs/hooks/src/engine/command_runner_tests.rs | 失败、并发或兼容行为 | 应与本节不变量一致 |
当前环境没有 Cargo，本轮不伪报 Rust 测试执行；验证由锁定提交下的源码—测试静态对读、源文件存在性检查、Mermaid 渲染、Astro 生产构建和公开页面检查组成。
Mini Codex 复刻建议
Mini Codex 应先复刻本节的协议不变量：明确状态所有者、稳定身份、可回滚预留、同 Step 快照、超时/取消和单一终态。平台沙箱、远程 Executor、OAuth、Backend App Route 或第三方 MCP Server 的安全性质不能由一个本地 Python mock 证明，适配器只能验证调用顺序和故障处理。
本节结论
Hook Engine 从受管要求、分层 config.toml/hooks.json 与插件清单发现 handlers，先应用 managed-only/trust/state 策略，再按事件 matcher 选中；命令以 JSON stdin、受限环境、cwd、timeout 和 kill-on-drop 并发执行。 掌握这一点后，再看相邻模块时就能判断它是在改变身份、运行状态、模型可见上下文、外部能力，还是仅提供观察快照。
阅读导航
上一节：App MCP Routing、Backend Auth 门控与同名 Server 去重 · 下一节：Session、Prompt、Tool、Compact 与 Subagent Hook 事件负载
源码依据
本文基于锁定提交 fe01054a28fa4bd04716d9ceadb410f2443a50ce 的生产代码和相邻测试静态核对。关键入口如下：
- codex-rs/hooks/src/engine/discovery.rs：配置层/plugin 发现、policy 和稳定 key
- codex-rs/hooks/src/engine/dispatcher.rs：matcher、并发和顺序恢复
- codex-rs/hooks/src/engine/command_runner.rs：shell、stdin、timeout 与输出捕获
- codex-rs/hooks/src/events/common.rs：matcher 验证
评论
登录后即可评论