读懂 Codex（7.34）：Session、Prompt、Tool、Compact 与 Subagent Hook 事件负载

Hook 不是一个通用 JSON blob：每个事件有独立输入 schema，公共字段只负责 session/turn/cwd/transcript，Tool 事件增加 tool_name/input/response，Compact 增加 trigger，Subagent 增加 agent 身份。

本节只研究“Hook event 的类型化 payload 组装”。输入是 Session/Turn/Tool/Compact/Subagent 运行状态，状态由 hooks/events 与 Core hook_runtime 持有，成功输出为与 event schema 匹配的 JSON stdin。相邻章节中看起来相似的对象如果由不同组件拥有，就不能用一个布尔状态替代。

先确定边界和状态所有者

问题	本节答案
谁发起	Session/Turn/Tool/Compact/Subagent 运行状态
谁拥有可变状态	hooks/events 与 Core hook_runtime
成功产物	与 event schema 匹配的 JSON stdin
不在本节内	Hook event 的类型化 payload 组装之外的上游产品策略和下游业务实现

这张表的用途不是复述名词，而是约束实现顺序：校验必须发生在副作用之前；已经提交的状态只能由原所有者撤销；只读投影不能反过来成为控制权威。

端到端调用链

选择 HookEventName
组装 common context
附加事件特有字段
序列化对应 input schema
交 Dispatcher 匹配/执行

Session、Prompt、Tool、Compact 与 Subagent Hook 事件负载的端到端机制流程，展示选择 HookEventName、组装 common context、附加事件特有字段、序列化对应 input schema、交 Dispatcher 匹配/执行 — 图 7.34-1：选择 HookEventName → 组装 common context → 附加事件特有字段 → 序列化对应 input schema → 交 Dispatcher 匹配/执行。图中每条箭头都表示下一层只接收上一层已经确认的状态。

这条链里至少有三种时间尺度：配置或身份在 Thread 创建时冻结，Turn 内状态由 Session 串行协调，Step 级目录与能力在每次模型采样前重新捕获。若把后一个时点的新状态拿去解释前一个时点已经发出的调用，就会产生跨代错误。

源码机制拆解

Session Start/End 描述线程边界

Start payload 带 source 等启动信息，End 带结束原因；SessionEnd 有独立默认/最大 timeout，避免退出被任意脚本无限拖住。

这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 hooks/events 与 Core hook_runtime 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。

Tool 前后使用不同事实

PreToolUse 在执行前提供 tool_name、matcher aliases 与 tool_input，可影响是否允许/更新输入；PostToolUse 才能携 tool_response。PermissionRequest 是审批阶段的另一事件。

Compact 区分 manual/auto trigger

PreCompact/PostCompact matcher 可以用触发类型过滤；它们不伪装成普通工具调用，因为压缩会改变历史基线。

Subagent 与普通 Session 分开

SubagentStart/Stop payload 使用 agent_id、agent_type 和 Turn 信息标识派生 Agent，而不是伪造 Root SessionStart/End。SubagentStart 的 continue:false 不负责阻止启动，只用于追加 context；Root SessionStart 才解释 stop。

Python 风格伪代码

下面的伪代码提炼状态机与错误顺序，不逐行翻译 Rust，也不假装 Python 对象具有 Rust 的所有权保证：

def build_hook_payload(event, runtime):
    common = CommonHookInput(
        session_id=runtime.session_id,
        turn_id=runtime.turn_id_if_any,
        cwd=runtime.cwd,
        transcript_path=runtime.transcript_path,
    )
    match event:
        case PreToolUse(tool): return PreToolInput(common, tool.name, tool.input)
        case PostToolUse(tool, result): return PostToolInput(common, tool.name, tool.input, result)
        case PreCompact(trigger): return CompactInput(common, trigger)
        case SubagentStart(agent): return SubagentInput(common, agent.id, agent.agent_type)
        case SessionEnd(reason): return SessionEndInput(common, reason)
        case _: return event_specific_payload(common, event)

阅读这段伪代码时要检查三件事：第一，输入是否在副作用前完成规范化；第二，异步等待是否仍携带原 Thread/Turn/Step 身份；第三，失败后究竟释放了什么、又保留了什么。只写快乐路径会把本节最重要的一致性条件删掉。

失败、取消与恢复

Session、Prompt、Tool、Compact 与 Subagent Hook 事件负载的三类失败分支、可观察结果和恢复责任 — 图 7.34-2：失败不会抹掉已经提交的状态；每条分支都由拥有该状态的组件执行恢复或补偿。

故障点	已发生的状态	可观察结果	恢复责任
给 PreToolUse 填 tool_response	字段不属于 schema	序列化/校验不接收	只在 PostToolUse 使用
缺少 turn id 的 session 事件	该事件本就不属于 Turn	使用可选/公共 scope 字段	不要伪造 id
event 名与 schema 选错	命令收到错误形状	Hook 可能 parse/logic 失败	按 HookEventName 映射专用 builder

取消不自动等于回滚，列表不自动等于权威存储，模型看见的描述也不自动等于已经获准执行。对于已经建立的 Thread、写入的 Edge、入队的 Mailbox、安装的插件或外部工具副作用，必须由相应所有者执行显式关闭、补偿或保留。

并发与一致性不变量

同一身份不能在并发路径中被重复预留或重复注册；若允许幂等重试，幂等键必须是稳定路径、ThreadId、request id 或 catalog revision，而不是展示名称。
一次模型采样看见的 Prompt、工具目录和执行入口必须来自同一个 Step 快照；刷新只影响后续 Step。
Watch/Activity/事件是通知机制，不是状态本身。被唤醒后必须重新读取 Registry、Session、Mailbox、Store 或 Binding 的权威值。
失败路径不得“为了干净”删除仍可恢复的历史；同样也不得把只剩历史的对象伪报成当前仍驻留运行。

设计思路与代价

本节设计保护的核心不变量是：Hook 不是一个通用 JSON blob：每个事件有独立输入 schema，公共字段只负责 session/turn/cwd/transcript，Tool 事件增加 tool_name/input/response，Compact 增加 trigger，Subagent 增加 agent 身份。代价是同一个功能会跨越地址、配置、Session、队列、存储或扩展适配层，测试也必须覆盖正常、并发和中途失败。更短的单体实现虽然容易演示，却无法区分“存在、已加载、正在运行、可恢复、已关闭、模型可见”这些彼此独立的事实。

设计动机部分是根据生产类型、调用顺序和测试行为归纳；源码可直接证明的是字段、分支、状态所有者和失败结果。文章不会把推断写成服务端或产品层的未公开事实。

源码与测试证据

位置	能证明什么
`codex-rs/hooks/src/events/mod.rs`	事件模块和公共导出
`codex-rs/hooks/src/events/common.rs`	公共字段/matcher 输入
`codex-rs/hooks/src/events/pre_tool_use.rs`	PreToolUse payload
`codex-rs/hooks/src/events/post_tool_use.rs`	PostToolUse payload
`codex-rs/hooks/src/events/compact.rs`	Compact trigger
`codex-rs/core/src/hook_runtime.rs`	Core 状态到 event payload

测试/可执行检查	覆盖重点	预期
`codex-rs/hooks/src/engine/mod_tests.rs`	正常、边界与状态转换	应与本节不变量一致
`codex-rs/hooks/src/events/session_end_tests.rs`	失败、并发或兼容行为	应与本节不变量一致

当前环境没有 Cargo，本轮不伪报 Rust 测试执行；验证由锁定提交下的源码—测试静态对读、源文件存在性检查、Mermaid 渲染、Astro 生产构建和公开页面检查组成。

Mini Codex 复刻建议

Mini Codex 应先复刻本节的协议不变量：明确状态所有者、稳定身份、可回滚预留、同 Step 快照、超时/取消和单一终态。平台沙箱、远程 Executor、OAuth、Backend App Route 或第三方 MCP Server 的安全性质不能由一个本地 Python mock 证明，适配器只能验证调用顺序和故障处理。

本节结论

Hook 不是一个通用 JSON blob：每个事件有独立输入 schema，公共字段只负责 session/turn/cwd/transcript，Tool 事件增加 tool_name/input/response，Compact 增加 trigger，Subagent 增加 agent 身份。掌握这一点后，再看相邻模块时就能判断它是在改变身份、运行状态、模型可见上下文、外部能力，还是仅提供观察快照。

阅读导航

上一节：Hooks 配置发现、Trust、Matcher 与 Command Runner · 下一节：Hook 输出解析、Additional Context、输入改写与阻断结果

源码依据

本文基于锁定提交 fe01054a28fa4bd04716d9ceadb410f2443a50ce 的生产代码和相邻测试静态核对。关键入口如下：

codex-rs/hooks/src/events/mod.rs：事件模块和公共导出
codex-rs/hooks/src/events/common.rs：公共字段/matcher 输入
codex-rs/hooks/src/events/pre_tool_use.rs：PreToolUse payload
codex-rs/hooks/src/events/post_tool_use.rs：PostToolUse payload
codex-rs/hooks/src/events/compact.rs：Compact trigger
codex-rs/core/src/hook_runtime.rs：Core 状态到 event payload