读懂 Codex（7.40）：Hooks 与进程内 Extension 的信任、能力和失败边界

Hooks 是配置/插件提供的外部命令：要经过 discovery trust、matcher、timeout、JSON schema 和输出限制；Extension 是编译进宿主进程的 Rust 代码：拥有 typed capabilities、可直接贡献工具/上下文，因此信任更高且故障半径更大。

本节只研究“两类扩展机制的架构选型和安全边界”。输入是外部 hook declaration 或进程内 contributor，状态由 Hook Engine、Extension Registry 与 Host policy 持有，成功输出为受控 decision/context 或原生能力贡献。相邻章节中看起来相似的对象如果由不同组件拥有，就不能用一个布尔状态替代。

先确定边界和状态所有者

问题	本节答案
谁发起	外部 hook declaration 或进程内 contributor
谁拥有可变状态	Hook Engine、Extension Registry 与 Host policy
成功产物	受控 decision/context 或原生能力贡献
不在本节内	两类扩展机制的架构选型和安全边界之外的上游产品策略和下游业务实现

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

端到端调用链

按所需能力选 Hook/Extension
Hook 做 trust/进程隔离或 Extension 编译注册
在专用 lifecycle gate 调用
限制/记录输出
失败按各自策略收敛

Hooks 与进程内 Extension 的信任、能力和失败边界的端到端机制流程，展示按所需能力选 Hook/Extension、Hook 做 trust/进程隔离或 Extension 编译注册、在专用 lifecycle gate 调用、限制/记录输出、失败按各自策略收敛 — 图 7.40-1：按所需能力选 Hook/Extension → Hook 做 trust/进程隔离或 Extension 编译注册 → 在专用 lifecycle gate 调用 → 限制/记录输出 → 失败按各自策略收敛。图中每条箭头都表示下一层只接收上一层已经确认的状态。

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

源码机制拆解

Hook 能看 payload 并做阻断

PreToolUse/PermissionRequest/UserPromptSubmit 等可接收 JSON 载荷并返回 deny/block/updated_input；ToolLifecycleContributor 刻意只观察 accepted call 的名称、来源和结果状态，不检查或改写工具 payload。

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

Extension 能直接提供能力

Tool/MCP/Context/WorldState contributors 返回进程内对象或结构化贡献，没有外部进程的 JSON 隔离；因此只适合宿主编译并信任的功能。

Hook 有显式资源护栏

外部命令使用 timeout、kill_on_drop、stdout/stderr 捕获、additional_context token limit、managed-only 与 trust state；坏 JSON 通常降级为失败/警告而非获得权限。

Extension 故障隔离不一致

TurnItemContributor 用 Result 软失败；大多数 lifecycle/context/tool trait 本身不返回 Result，Host 直接 await。扩展 panic、死锁或长等待可影响整个 Session，不能把它宣传成沙箱。

Python 风格伪代码

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

def choose_extension_boundary(requirement):
    if requirement.must_register_native_tool_or_world_state:
        require(requirement.code_is_host_trusted)
        return InProcessExtension(
            typed_capabilities=True,
            failure_budget='host process',
        )
    return ExternalHook(
        trust_policy='managed/user/plugin state',
        timeout=True,
        json_schema=True,
        output_limit=True,
    )

async def safe_hook_decision(handler, payload):
    run = await run_with_timeout_and_kill(handler, json.dumps(payload))
    parsed = parse_event_specific_output(run.stdout)
    return parsed if parsed and parsed.is_valid else NoDecisionWithWarning()

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

失败、取消与恢复

Hooks 与进程内 Extension 的信任、能力和失败边界的三类失败分支、可观察结果和恢复责任 — 图 7.40-2：失败不会抹掉已经提交的状态；每条分支都由拥有该状态的组件执行恢复或补偿。

故障点	已发生的状态	可观察结果	恢复责任
不可信逻辑做成 Extension	运行在宿主进程	可崩溃/访问广泛能力	改为 Hook/MCP 外部边界
需要原生工具却用 Hook	只能围绕已有事件运行	无法注册强类型执行器	用受信 ToolContributor
把 PostToolUse block 当回滚	工具副作用已发生	只能阻止/影响后续流程	需要执行前策略放 PreToolUse

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

并发与一致性不变量

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

设计思路与代价

本节设计保护的核心不变量是：Hooks 是配置/插件提供的外部命令：要经过 discovery trust、matcher、timeout、JSON schema 和输出限制；Extension 是编译进宿主进程的 Rust 代码：拥有 typed capabilities、可直接贡献工具/上下文，因此信任更高且故障半径更大。代价是同一个功能会跨越地址、配置、Session、队列、存储或扩展适配层，测试也必须覆盖正常、并发和中途失败。更短的单体实现虽然容易演示，却无法区分“存在、已加载、正在运行、可恢复、已关闭、模型可见”这些彼此独立的事实。

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

源码与测试证据

位置	能证明什么
`codex-rs/hooks/src/engine/discovery.rs`	Hook trust/managed policy
`codex-rs/hooks/src/engine/command_runner.rs`	进程/timeout/kill 边界
`codex-rs/hooks/src/engine/output_parser.rs`	输出 schema/decision 校验
`codex-rs/ext/extension-api/src/contributors.rs`	进程内 typed contributor 能力
`codex-rs/core/src/stream_events_utils.rs`	TurnItem contributor 软失败特例

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

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

Mini Codex 复刻建议

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

本节结论

Hooks 是配置/插件提供的外部命令：要经过 discovery trust、matcher、timeout、JSON schema 和输出限制；Extension 是编译进宿主进程的 Rust 代码：拥有 typed capabilities、可直接贡献工具/上下文，因此信任更高且故障半径更大。掌握这一点后，再看相邻模块时就能判断它是在改变身份、运行状态、模型可见上下文、外部能力，还是仅提供观察快照。

阅读导航

上一节：Thread 与 Turn Lifecycle Contributor 的调用时机和状态清理 · 下一章：工作怎样被记住

源码依据

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

codex-rs/hooks/src/engine/discovery.rs：Hook trust/managed policy
codex-rs/hooks/src/engine/command_runner.rs：进程/timeout/kill 边界
codex-rs/hooks/src/engine/output_parser.rs：输出 schema/decision 校验
codex-rs/ext/extension-api/src/contributors.rs：进程内 typed contributor 能力
codex-rs/core/src/stream_events_utils.rs：TurnItem contributor 软失败特例