你要给这台 agent 加一个小功能：每轮对话开头把当前 git 分支名写进模型上下文。打开仓库，第一反应是往 codex-core 里加。session、context、guardian、tools 都在那儿，新文件放进去最省事。依赖表不用改，调用链不用跨 crate。

过了一周，同样的理由又进来三条。一个截断工具输出的 helper，一个模型供应商适配，一个会话恢复的边角。core/src/lib.rs 顶部又多三个 mod。下游只要写 use codex_core，编译图跟着变宽。有人想单独复用上下文片段那个类型，发现它焊在 core 里。要复用就得把整个 core 拉进来，包括沙箱、MCP、Guardian。

仓库把这件事写成禁令。AGENTS.md 用加粗英文写 resist adding code to codex-core。新概念先问现有的非 core crate 能不能住。再问该不该新建一个 workspace crate，并且允许为此重构旧代码。core 是最后一档。评审遇到往 core 里堆功能的 PR，被要求主动挡回去。

出处：AGENTS.md 第 72 至 83 行

禁令写进文件的日期是 2026-03-26。当时 core 已经是最大 crate。立完之后 workspace 成员从 75 个长到 135 个，core 的生产代码却还是涨了。挡的是默认往核心扔，挡不住核心继续长。

清单是一份显式数组。codex-rs/Cargo.toml 的 members 数一遍是 135。目录名和 crate 名要分开看：目录叫 core，包名叫 codex-core，use 的时候写成 codex_core。

出处：codex-rs/Cargo.toml 第 1 至 20 行；AGENTS.md 第 1 至 5 行；codex-rs/core/Cargo.toml 第 1 至 9 行

按 .rs 行数，少数几个吃掉大半体积。core 33 万行，tui 27 万，app-server 14.8 万。大于等于 1 万行的 24 个，小于 2 千的 77 个。core 去掉测试后剩约 10.3 万行。25 个 workspace 成员直接依赖它。tui 的 Cargo.toml 没有这一行，它依赖 codex-app-server-client，再由 client 拉 core。往 core 加一行，直接下游 25 个要重编，tui 仍会被带上。

出处：codex-rs/cli/Cargo.toml 第 41 至 42 行；codex-rs/tui/Cargo.toml 第 30 至 31 行

上帝包的失败模式是这次很小、先放核心。把默认落点写成明文，让评审有权挡，不依赖某种语言。换个语言重写，最小形态仍是这三问：现有包能不能住，该不该新建包，进核心凭什么拆不出去。

依赖方向反了，编译图会从两边一起胀。core 自己已经依赖 61 个 codex-* crate，包括拆出去的 context-fragments 和 features。如果新的上下文类型再写回 core，想复用它的人必须把沙箱和 Guardian 一起拉进来。叶子依赖核心，核心再依赖叶子，边界就没了。

拆出去的 crate 只带自己需要的那一点。context-fragments 的包清单几乎没有业务依赖，只碰 protocol 和一段字符串工具，对外 re-export 两个片段类型和一个 trait。core 可以依赖它，它不依赖 core。git 分支名这种片段走这条路：类型落在 fragments，core 当调用方。模型供应商适配已经抽到 codex-model-provider。必须摸 session 内部状态的东西，才走到最后一档，评审仍要问为什么拆不出去。

出处：codex-rs/context-fragments/src/lib.rs 第 1 至 6 行；codex-rs/core/Cargo.toml 第 26 至 42 行

旁边还有两把尺子。文件目标 500 行，大约超过 800 行就开新模块。非机械改动一次不超过 800 行，复杂逻辑压到 500。三层一起看，针对的是同一件事：人和 AI 都倾向于把改动写大，写进已经很大的文件。

出处：AGENTS.md 第 49 至 61 行；AGENTS.md 第 125 至 131 行

这条禁令本身没有 lint，没有 CI job。仓库里检索 resist adding code to codex-core，只命中 AGENTS.md 这一处。挡得住的是旁边那几条：依赖没刷 Bazel lock，CI 红；include_str! 没改 BUILD.bazel，Bazel 红。core 禁令挡得住习惯，挡不住有理由的例外，也挡不住漏看。

出处：AGENTS.md 第 37 至 43 行

编译图的方向是物理约束。叶子可以独立编译，被多个中心复用。中心一旦吞下叶子类型，复用成本变成拉进整个中心。这个形状换语言也成立。

你让 coding agent 改一个函数。屏幕上这是一轮对话：你说了一句，它忙了一阵，最后回「改完了」。

忙的时候其实叠了几件事。模型调了工具。你中途补了一句「测试用 pytest」。它写完助手消息后，Stop hook 说还没跑 linter，于是又采了一次样。

这几件事如果塞进同一个 while，就只能靠几个布尔抢出口。谁先检查、谁能打断谁，会变成口头约定。少一层，就少一个干净插口：插话、续跑和流重试会搅在一起。

Codex 拆成三层。任务壳 RegularTask::run 决定这一趟还要不要再开一轮。轮次 run_turn 决定工具续跑、插话和 hook 要不要继续。采样层只把一次模型流收到 Completed。

对外入口 start_or_steer_turn 自己不看会话空不空闲。返回值只表示 Core 接没接住这条输入，不等 hooks，也不等采样。空闲就 spawn RegularTask，忙碌就 Steered 写入 pending。三层循环从任务壳才开始转。

出处：codex-rs/core/src/codex_thread.rs 第 333 至 344 行 · codex-rs/core/src/session/turn_input.rs 第 1 至 9 行

任务壳发一次 TurnStarted，然后只要队列里还有待处理输入，就再调一次 run_turn。第二次进去时 next_input 为空，新消息从 input_queue 取。turn_id 钉死，界面不会再闪一次「新的一轮开始了」。

出处：codex-rs/core/src/tasks/regular.rs 第 76 至 90 行

轮次层把采样回来的两件事合成一个布尔：model_needs_follow_up || has_pending_input。为真就自己 continue。为假才跑 stop hook。hook 带 prompt 拦收工，这一层自己再转，任务壳和采样层都还没退。

出处：codex-rs/core/src/session/turn.rs 第 423 行 · 第 500 至 525 行

采样层自己还有两圈。外圈处理可重试错误。内圈消费一条 SSE 流。工具调用不等 Completed：OutputItemDone 当时就会挂上 future。流收到 Completed，先 drain_in_flight，再把结果交回 run_turn。

出处：codex-rs/core/src/stream_events_utils.rs 第 326 至 327 行 · codex-rs/core/src/session/turn.rs 第 2539 至 2584 行 · 第 2749 行

三层按「谁有资格决定继续」切开。采样层只看见这一次流，能重试，不能收整轮。轮次层看见工具、pending、预算和 hook，能续采样，不能重发 TurnStarted。任务壳看见任务还在、队列里是否还有活。

这不随文件怎么拆而变。换个语言重写，该问的还是三个问题：这一条流结束了吗，这一轮还要再采吗，这一趟任务还活着吗。

RegularTask 和 run_turn 都看 pending。同一句用户话如果两处都取，会转两圈。如果只留一处，就会把 hook 和后到消息挤进同一个出口。

两处问的是两件不同的事。

轮次层在采样刚刚结束时问，问的是「这一轮还要不要再采一次」。任务壳在 run_turn 已经 break 之后问，问的是「这一趟任务还要不要再进一次 run_turn」。前者把插话和工具结果留在同一个 turn_id 里。后者是界面已经可以收工、队列里又来了必须处理的输入。

去掉轮次层那一问：模型写出最终答案后，run_turn 会去跑 stop hook 并 break，中途那句「测试用 pytest」只能等任务壳再进一次 run_turn。功能上还能补上，只是多一次函数返回，stop hook 会在插话进模型之前先跑一轮。

去掉任务壳那一问：run_turn 因 should_stop 返回后，任务直接结束。队列里后到的用户消息要么消失，要么等会话变空闲，由 maybe_start_turn_for_pending_work 换一个 turn_id 新开任务。TurnStarted 会再闪一次，回放里变成两个 turn 桶。

stop hook 返回 block 且带 prompt，控制权留在轮次层。采样层早已返回。任务壳还在等这次 run_turn。block 是轮次层内部续跑。stop 是轮次层把控制权交回任务壳。

出处：codex-rs/core/src/session/turn.rs 第 509 至 537 行 · codex-rs/hooks/src/events/stop.rs 第 67 至 74 行

源码没有单独写「为什么要问两次」，下面从实现反推。hook 续跑时控制权留在轮次层，任务壳看不见。hook 放行后，任务壳才有机会接手「收工瞬间又来的那一句」。两个问题发生在不同时刻，所以要问两次。这跟具体语言、具体 hook 协议无关。

你让模型读三个文件再写摘要。屏幕上还在打字，读文件的声音已经响了。然后你按 Esc。界面停了，历史里却留下那次请求，有时还留下结果。你以为取消等于什么都没发生。运行时并不这么记账。

另一头更常见：模型已经发出两个 function_call，第三个还在路上，SSE 在 response.completed 到来之前关掉。下一次重试该看见空历史，还是已经落盘的调用和结果？

若等 Completed 再写入，提前关流会把已经完整的调用一起扔掉。重试让模型再发一遍同样的调用。若取消时跳过写入，历史只剩半截请求，模型和界面都看见一个没闭合的调用。

OutputItemDone 是解析层把一帧 response.output_item.done 收成的业务事件。它一到，采样循环先把这一条写入会话历史和 rollout，再把工具执行包成 future 挂到有序队列上。取消令牌用子令牌，父令牌一亮，这个工具跟着停。取消来得再快，这一条 function_call 已经进历史。最多再多写一条 aborted by user。

出处：codex-rs/core/src/stream_events_utils.rs 第 190 至 192 行；第 316 至 327 行。类型别名上方的注释把合同写死：完成的模型输出要立刻记下来，后面 turn 被取消，历史和 rollout 也保持同步。

历史只能往上加，不能改写。工具已经读了磁盘，这条事实已经发生。取消树可以打断执行，打断不了已经写下的请求。先写请求、后写结果，transcript 始终闭合。这条合同不依赖 Rust，换 TypeScript 也是先 append 再 push 一个 promise。

出处：AGENTS.md 第 91 至 100 行，Model visible context 第一条：No history rewrite。

模型常常先发出读文件，再继续写一段说明。等收工哨再开工，等于把读文件的延迟和打字的延迟串起来。流内开工能让这两段时间重叠。代价是取消和断流必须认领已经开工的 future。没有认领人，就会出现孤儿任务：工具还在跑，历史对不上。

收流循环无论正常 Completed、提前关流还是 or_cancel，都只是离开 loop。函数还没返回。随后固定调用 drain_in_flight，按插入顺序等到每条 future 给出结果，再写入历史。然后才检查取消令牌。

断流走 Stream，可重试。重试从 clone_history 重建 prompt，已经写下的调用和结果都在。Esc 走 TurnAborted，不可重试。正在跑的工具写出中止文案，drain 把它当普通输出写入。

出处：codex-rs/core/src/session/turn.rs 第 2282 至 2284 行；第 2744 至 2762 行。codex-rs/protocol/src/error.rs 第 88 至 93 行、第 364 至 390 行。

中途开工就必须在每个出口等齐。所有权留在采样函数的局部变量里，没有另一条后台回收队列。成功、错误、取消共用这一段收尾。换语言也一样：离开异步循环之后先 allSettled，再决定重试还是中止。

三个工具可以同时跑。谁先跑完，历史仍按模型发出的顺序写结果。按完成顺序写，同一段会话重放两次可能对不上，prompt cache 也会更脆。有序队列把观测顺序和执行顺序拆开。并发闸门在别的一层，这里只记：挂起顺序就是日后 drain 的顺序。

出处：codex-rs/core/src/session/turn.rs 第 2130 至 2154 行；第 2391 至 2397 行。

三种日常结局都不好受。立刻打断，前面两个文件的改动可能半成品留在磁盘上。排到下一轮，你只能看着它把剩下的文件按旧方向改完。塞进当前上下文却不叫醒循环，模型要到下一次自己开口才看得到，你补的约束等于迟到。

Codex 把这件事收成一个入口、三种模式。调用方选 StartOrSteer、StartIfIdle 或 Steer，不直接喊 start。Core 按现场忙闲和任务种类判定，立刻回 Started、Steered 或 NotSubmitted。回完决定就结束，不等 user-prompt hook，不等历史落盘，不等模型开始采样。

出处：codex-rs/core/src/session/turn_input.rs 第 1 至 9 行；codex-rs/protocol/src/turn_input.rs 第 127 至 136 行

StartOrSteer 的顺序和函数名一致。先试插话。只有返回 NoActiveTurn，才 apply_started 再 spawn_task。其他拒绝原因原样包装成 NotSubmitted，不会偷偷开工。TUI 实时语音也走这条，和默认入口共用同一套判定。

出处：codex-rs/core/src/session/turn_input.rs 第 141 至 156 行、第 195 至 249 行

设置不能先改再判定。prepare 先预览线程设置，预览失败直接 InvalidRequest。真正写入发生在 apply_started 或 apply_steered。被拒绝的输入连设置都不改。插话成功后只落持久设置，当前轮的 TurnContext 不换。开工专用的选项，比如结构化输出 schema，只在 Started 上用。

出处：codex-rs/core/src/session/turn_input.rs 第 58 至 80 行

开工和插话必须在同一把锁里做完。先看有没有活动轮，再看 kind，再写入 pending，中间不能让另一次提交把轮次换掉。设置却要先预览后写入，因为拒绝路径必须保证线程不变。判定和入队拆成两次加锁，用户回车和子邮件同时到达时，可能出现判定时还空闲、入队时已经有人占坑的窗口。

审查任务自己再开一条 one-shot 子对话，压缩任务在换窗口。用户在这时候补一句「用 YAML」，没有当前轮的工具循环可以接住它。如果因此新开一轮普通对话，审查结果和压缩摘要会跟新对话抢同一个 active_turn。

steer_input 拿着 active_turn 锁做完全部检查。没有活动轮，或者有槽没有 task，都算 NoActiveTurn。TaskKind 只有 Regular、Review、Compact 三个变体。审查和压缩返回 ActiveTurnNotSteerable。StartOrSteer 也不会因此开工。

出处：codex-rs/core/src/session/turn_input.rs 第 507 至 519 行；codex-rs/core/src/state/turn.rs 第 67 至 72 行

检查过关之后，用户输入被推进 pending_input，同时把信箱相位打回 CurrentTurn。穷尽 match 在这里有业务后果：新加一种任务类型，编译器会逼你回答能不能插话。

出处：codex-rs/core/src/session/turn_input.rs 第 546 至 564 行

内部任务有自己的生命周期。把用户插话焊进审查轮，等于让两种工作抢同一条执行槽。调用方收到拒绝，这条输入不会被默默排进一条新对话。换个语言重写，该守的仍是：能接住插话的任务和不能接住的任务，必须在类型上分开。

主 agent 已经在屏幕上打出一段看起来像最终答案的话，子 agent 同时发回一条进度。并进去，用户已经看见的答案会被续写。一律等到下一轮，子 agent 的结果可能要隔一次采样才进模型。

用户插话进的是 turn 内的 pending_input。子 agent 的信走会话级 mailbox_pending_mails。两套存货能不能并进当前轮，由 MailboxDeliveryPhase 决定。相位从 CurrentTurn 起步。用户已经看见最终答案之后切到 NextTurn。用户再插一句，或者模型又发出工具调用，相位会重开。

出处：codex-rs/core/src/state/turn.rs 第 37 至 56 行

切到 NextTurn 有一条例外：pending_input 里只要还有一条不是排队不叫醒的子邮件，就保持当前相位。取信时也看这面牌。NextTurn 时 turn 内 pending 也不拿，会话信箱更不掏。CurrentTurn 时先拿走 turn 内 pending，再掏会话信箱，拼在后面。所以最终答案落地之后，子邮件可以躺在信箱里，循环却认为没有待处理输入，本轮会收束。

出处：codex-rs/core/src/session/input_queue.rs 第 206 至 227 行、第 284 至 336 行

什么算出用户可见的最终答案？助手正文，phase 是 Commentary 的不算，trim 之后为空的也不算。未打标的助手消息按最终答案处理。未打标的提供方默认走更安全的那条：先把信箱关到下一轮。审批、权限、提问、elicitation、动态工具是五张独立的 oneshot 表，不进这套信箱，各等各的回执。

出处：codex-rs/core/src/stream_events_utils.rs 第 486 至 501 行；codex-rs/core/src/state/turn.rs 第 87 至 103 行

「答案已经给用户看过」是一条产品边界，不依赖 Rust 或某个信箱实现。换语言重写，仍然需要一面翻牌：迟到的附属消息默认不续写已经上屏的答案；明确的同轮工作，比如用户再插一句或模型再调工具，再把门打开。

你让 Codex 改一个测试文件。模型先跑 cargo test，编译器吐了两屏 rustc 报错，退出码是 1。下一秒对话停了，界面弹出 turn aborted。很多人第一次写 agent 会这么干：工具返回 Err，整轮跟着死。模型还没看见 stderr，会话已经结束。

分诊发生在工具回到对话的那道门上，一共三层门槛。

最浅一层：进程已经跑过。退出码非零、命令超时、沙箱拒绝，都收成工具回执。success 写成 true，意思是 handler 跑完了，回执可以喂给模型。命令成不成功写在正文里。

出处：codex-rs/core/src/tools/context.rs 第 344 至 353 行

中间一层：调用没做成。参数坏了、进程没拉起来、apply_patch 上下文对不上，走 RespondToModel。回执 success 才是 false。模型读到文案，自己改再试。

最深一层：payload 对不上、任务 join 失败，才写 Fatal，升成 CodexErr，停 turn。

工具层自己的枚举只有两档。RespondToModel 把字符串喂回模型。Fatal 才升成引擎错误。默认把非 Fatal 折成 Ok。想停对话，得写出 Fatal 或 CodexErr。

use thiserror::Error;

/// Error returned while executing a model-visible tool invocation.
#[derive(Debug, Error, PartialEq)]
pub enum FunctionCallError {
    #[error("{0}")]
    RespondToModel(String),
    #[error("Fatal error: {0}")]
    Fatal(String),
}

cargo test 退出码 1 停在最浅一层，连错误枚举的门槛都没迈过。沙箱拒绝同样走 Ok。代理拦请求时给命令进程回 HTTP 403，也停在最浅一层。模型 API 的 403 才是引擎错误。两处 403 不要并成一档。

出处：codex-rs/core/src/tools/handlers/unified_exec/exec_command.rs 第 384 至 411 行；codex-rs/network-proxy/src/responses.rs 第 76 至 83 行

handler 里一个 IO 错误如果直接冒到 turn 循环，整轮对话跟着死。默认回灌，想停必须显式写出。这条线换语言重写也用得上。自己做内部 agent，先抄这一档：工具失败回灌，引擎失败停循环。

用户按 Esc，要停的不只是当前那次采样。采样可能还在读流，工具可能正在写文件，后台 terminal 可能已经拉起来了。只杀采样，工具会继续改磁盘。一刀切杀掉所有进程，unified exec 的后台任务也会被误杀。

任务启动时现造一张取消令牌。采样请求用 child_token()，工具派发再 child 一次。父令牌一取消，子令牌一起取消。子令牌自己取消，不影响父令牌。这就是取消树。

出处：codex-rs/core/src/session/turn.rs 第 1399 行；codex-rs/core/src/stream_events_utils.rs 第 319 至 324 行

or_cancel 把谁先到写成固定形状。任意 future 配一张令牌。取消先到，返回 CancelErr，一律变成 TurnAborted。

出处：codex-rs/async-utils/src/lib.rs 第 4 至 31 行；codex-rs/protocol/src/error.rs 第 269 至 273 行

用户按 Esc，协议入口是 Op::Interrupt。合同写死：中止当前任务，不杀后台 terminal。handle_task_abort 先 cancel()，再等 100 毫秒。超时就 task.handle.abort()。令牌先发信号，任务有机会自己收尾。收不完，再硬拆。硬拆这一步不可逆。

出处：codex-rs/protocol/src/protocol.rs 第 546 至 548 行；codex-rs/core/src/tasks/mod.rs 第 66 行、第 880 至 913 行

一份用户意图，多层各自收尾。合作式取消加硬期限，是并发系统的通用形状。Python 里用 asyncio.Event 就能做最小版。不必抄 37 个变体的 CodexErr。

取消发生在工具已经改了文件之后，历史里怎么记。如果把已经完成的输出改写成 aborted by user，模型下一轮会以为写入没做成，可能再打一遍补丁。

工具 future 同时等派发结果和令牌。令牌先到，还要看 handler 是否已经走到终态。已经走完，就保留真实结果。没走完，才 abort，再造一条 AbortedToolOutput，正文是 aborted by user after Xs。

出处：codex-rs/core/src/tools/parallel.rs 第 177 至 206 行、第 243 至 260 行

然后追加一段模型可见标记，包在 <turn_aborted> 里。文案承认两件事：unified exec 可能还在后台跑，被中止的工具可能已经执行了一部分。标记写进历史之后立刻 flush_rollout()。有的客户端收到 TurnAborted 会同步重读 rollout，标记必须先落盘。

出处：codex-rs/core/src/context/turn_aborted.rs 第 1 至 35 行；codex-rs/core/src/tasks/mod.rs 第 920 至 962 行

历史只追加、不改写。中止只往后面加片段，已落盘的工具输出不动。下一轮模型能同时看见完成的输出、被中止工具的回执、以及中止标记。上下文治理的第一条就是这个形状。

出处：AGENTS.md 第 91 至 100 行

你给 agent 加过这类功能：用户刚批准了 npm *，下一轮模型还在问要不要跑 npm test。或者压缩刚结束，模型突然忘了工作区在哪、沙箱是只读还是可写。再或者 fork 一条会话，旧的 AGENTS.md 还在，新的目录提示叠上去，模型同时看见两套互相打架的规则。

这三件事的共同来源是同一类操作：运行时往模型上下文里塞了一段文字。批准前缀、工作区、权限档案、被中断的 turn、当前 UTC 时间，全是告诉模型一件它自己看不到的事实。一段 format! 就能写出来。

问题出在事后。这段文字进了历史之后，压缩要不要留它、会话恢复要不要认它、UI 要不要把它藏起来、world state 要不要拿它当模型已经知道了的证据，全都依赖一件事：你还能从纯文本里把它认回来。各处再写一遍 startsWith，过几周四处会漂。未知标签还会漏进用户消息解析。

Codex 把每一种注入收成一个实现 ContextualUserFragment 的类型。trait 不在 codex-core 里，而在独立 crate codex-context-fragments。每个实现必须同时回答：这段以 user 还是 developer 进 Responses API，头尾 marker 是什么，中间 body 怎么写，要不要单独成一条消息。

render() 把头尾 marker 和 body 直接首尾相接，中间不加分隔符。空白和换行算 body 的。空 marker 只输出 body。into() 把渲染结果收成一条 ResponseItem::Message，content 只有一个 InputText。注入的终点是协议对象。

    fn render(&self) -> String {
        let (start_marker, end_marker) = self.markers();
        let body = self.body();
        if start_marker.is_empty() && end_marker.is_empty() {
            return body;
        }

        format!("{start_marker}{body}{end_marker}")
    }

markers() 带 self，渲染走实例。type_markers() 不带 self，识别走类型。手里只有历史文本、没有原对象时，仍然能问这段像不像某某 fragment。dyn ContextualUserFragment 调不了 matches_text，反向识别必须点到具体类型。

加一种注入要新建文件、实现 trait、挂进 core/src/context/mod.rs。目录里 39 个模块。这个摩擦力本身就是治理：临时 format! 走不通，因为组装函数收的是 Box<dyn ContextualUserFragment>。出处：codex-rs/core/src/context/mod.rs 第 3 至 41 行；codex-rs/core/src/session/mod.rs 第 3677 至 3707 行

渲染和识别共用一份定义。换个语言重写，最小形态仍是一份接口、一份注册表、同一对 marker。组装函数的参数写成 fragment 类型，业务侧就失去了随手拼 XML 的调用点。识别函数只从注册表做匹配，不许再写一套 text.startsWith。

所有注入都带标，一次性通知也会在压缩后被重认、再喂一遍。所有注入都不带标，压缩后的历史里分不清用户原话和运行时塞进去的说明。fork 会把过期的 <environment_context> 当成用户输入重新提交。

窗口身份、环境、中断、图片缩放、管理侧开发者指令，事后要认、要 diff、要在压缩后决定是否重注，所以带 begin 和 end。一次性通知，比如批准前缀、网络规则入册、剩余 token 一句提醒，type_markers() 返回两个空串。默认 matches_text 恒为 false。

匹配规则只看整段文本的首尾。先 trim 开头比前缀，再 trim 结尾比后缀，ASCII 大小写不敏感，两个都中才算命中。中间夹什么不管。无标 fragment 主动放弃可逆性。出处：codex-rs/context-fragments/src/fragment.rs 第 89 至 103 行

developer 侧另有一张前缀表，在 event_mapping.rs，用来补一部分无标识别。覆盖面比 user 侧 matcher 列表窄。前缀表里至今留着 <token_budget> 旧标签，注释写明是为了认旧版本持久化下来的包装。marker 一旦写进 rollout，就变成恢复合同的一部分。改标签等于改协议。

UserInstructions 有一处容易看走眼。它的 begin marker 是 Markdown 标题 # AGENTS.md instructions，end marker 是 </INSTRUCTIONS>。协议里另有 <user_instructions> 那对标签，这个 struct 没用。按协议常量去写 matches_text，会认漏仓库里真实渲染出来的文本。出处：codex-rs/core/src/context/user_instructions.rs 第 18 至 19 行；codex-rs/protocol/src/protocol.rs 第 112 至 113 行

需要事后认的做成协议，一次性的主动放弃，并且在类型上写清楚。压缩后要重认的强制 begin 和 end，一次性通知可以无标，但要在注释里写放弃可逆。

各处随手 push 字符串，顺序靠约定，单独成条靠注释。TokenBudgetContext 会和权限说明挤在同一条 developer 消息里。压缩滤网没法按条处理。混装之后回滚也拆不开。event_mapping.rs 的注释承认：build_initial_context 可能把 contextual fragment 和持久 developer 文本捆在一起。出处：codex-rs/core/src/event_mapping.rs 第 69 至 71 行

第一次组装发生在 Session::build_initial_context_with_world_state。它把 fragment 按 role()、markers() 的开头、requires_separate_message() 分进几组：可合并的 developer 段、必须单独成条的 developer 段、user 段，以及要置顶或置底的特殊段。

窗口身份这一条有点特别。Feature::TokenBudget 打开且模型有 context window 时，它在 world_state 循环之前就被推进单独组。输出顺序是：先一条合并好的 developer 消息，再一条条单独的 developer 消息，再一条 contextual user 消息。分拣依据是类型字段。出处：codex-rs/core/src/session/mod.rs 第 3630 至 3728 行

requires_separate_message() 把能不能和别人挤在同一条 developer 消息里也收进类型。TokenBudgetContext、ImageResizeNotice、ManagedDeveloperInstructions 选择单独成条。单独成条的代价是多占一条消息、多一次 role 切换。好处是压缩滤网可以按条处理。

组装入口只收已登记类型。这是把没登记的注入挡在门外的通用形状。类型挡得住没登记，挡不住登记了但每轮塞 40KB。那一层是评审规则，下一章展开。

想象四份看起来很负责的 PR。甲给 environment 上下文加一个 git_status 字段，每轮写入完整工作区状态。乙在 turn.rs 里 format 一句 hint，提醒模型跑测试。丙新建一个 fragment，把整个源文件塞进模型可见文本，不写截断。丁在 AGENTS.md 一改时，就地改写历史里那一条说明。

四份都能写出干净的 struct、干净的测试。类型系统会放行。下一轮推理的 cache 前缀会被打掉，token 账单会按轮翻倍，从旧 rollout 恢复时会读到被改过的历史。

ContextualUserFragment 是往模型上下文里塞一段带标记文字的登记口。上一章用它把注入收成类型。编译器从此只接受实现了这个 trait 的 struct。形状对了，成本还可以不合法：又长、又勤、又无界。

Codex 把成本写成六条禁令，放在仓库根 AGENTS.md，标题就叫 Model visible context。同一段原文被抄进 .codex/skills/code-review-context/SKILL.md。评审机器人读到的就是这六条，没有第二套解释。

### Model visible context

Codex maintains a context (history of messages) that is sent to the model in inference requests.

1. No history rewrite - the context must be built up incrementally.
2. Avoid frequent changes to context that cause cache misses.
3. No unbounded items - everything injected in the model context must have a bounded size and a hard cap.
4. No items larger than 10K tokens.
5. Highlight new individual items that can cross >1k tokens as P0. These need an additional manual review.
6. All injected fragments must be defined as structs in `core/context` and implement ContextualUserFragment trait

第 6 条和第 3、4 条先问入口和上界。没走 trait，handler 里直接 format! 一段 Message，编译能过，评审打回。走了 trait 但没写硬 cap，同样打回。工具输出侧默认按字节 10_000 截断，超了从中间砍，前面加一行警告，告诉模型原 token 数和总行数。出处：codex-rs/protocol/src/protocol.rs 第 3112 行；codex-rs/models-manager/src/model_info.rs 第 167 行；codex-rs/utils/output-truncation/src/lib.rs 第 12 至 24 行

通用附加上下文另卡在 1_000 token。1K 正好是第 5 条的门槛：已有种类被代码截到 1K，新的可能超过 1K 的种类才需要人看。源码里没有 P0 枚举，也没有 lint 去估一个新 struct 的 body() 会不会超过 1K。出处：codex-rs/context-fragments/src/additional_context.rs 第 5 行

第 2 条盯的是时机。能追加就追加。每轮重写环境 XML、每轮换工具清单，前缀对不上，cache 从第一层作废。会话级客户端把跨 turn 稳定和 turn 内粘滞拆开，sticky token 不准跨 turn 重放。Guardian 审查会话故意复用同一条 trunk，好保住 prompt_cache_key。集成测试 prompt_caching.rs 盯的就是连续两轮 instructions 和 tools 必须一致。出处：codex-rs/core/src/client.rs 第 262 至 274 行；codex-rs/core/src/guardian/review.rs 第 932 至 934 行

类型系统证明的是形状。它证明不了这条文字会不会每轮变、有没有上界、会不会改已经发出去的前缀。这些是过程属性，换语言重写也得另开一扇门。

日常命令也补不上这扇门。just fmt 和 just test 挡住格式、锁文件漂移和一部分 API 破坏。它们读不懂你是不是每轮注入了 git status。六条里零条有专用 lint。第 1、2 条有集成测试影子，第 3、4 条靠局部 cap，第 5 条纯靠人。第 6 条拦得住没实现 trait 就走 render_full 的路，拦不住在 handler 里直接拼一段 Message。skill 存在，说明执行主体是评审。

AGENTS.md 改了，最省事的做法是找到历史里那一条 UserInstructions，把正文换掉。当前轮少占一条消息，token 看起来还降了。从旧 rollout 恢复时，读到的是被改过的文本，会话对不上。

压缩看起来也像在改历史：旧窗口从 live history 里消失。若有人把压缩做成打开历史文件改一行，第 1 条和 breaking changes 第五项会一起被踩中。第五项点名的就是从已有 rollout 恢复会话。

replace_compacted_history 把新表整表装进 live history，旧内容以带 replacement_history 的 CompactedItem 追加到 rollout，不回改旧行。注释写明 「Compaction starts a new history window」。第 1 条和压缩能共存，因为压缩被定义成开新窗口。生产路径里那条就地换表的函数叫 replace_history，上面标了 #[cfg(test)]。出处：codex-rs/core/src/session/mod.rs 第 3373 至 3418 行；AGENTS.md 第 95 行、第 110 行

远端压缩还有一层滤网。服务端送回来的 transcript 不可信，developer 消息直接丢掉，再由本地按当前 world state 把带 marker 的 fragment 重新渲染进去。历史继续增量构建，压缩继续换窗口。出处：codex-rs/core/src/compact_remote.rs 第 354 至 372 行

追加写、用快照换窗口，是日志系统的通用形状。事件溯源换的是投影，LSM 树换的是 SSTable，都不回改已经写下的旧行。禁止就地更新，恢复才有得对。

总量谁来管，六条没写数字。代码用两层补上：模型窗口的 full_context_window_limit 是硬顶，会话树的 RolloutBudget 按加权 token 记账，用尽对整棵 thread 停写。40 条都合法且每条 9K，总量仍会被满窗或会话预算拦住。出处：codex-rs/core/src/session/context_window.rs 第 53 至 54 行、第 74 至 79 行；codex-rs/core/src/rollout_budget.rs 第 45 至 65 行

你让 coding agent 在同一个线程里改了三十轮。前二十轮还记得工作区在哪、哪几个文件不能动。到第三十轮，它突然问你「当前目录是什么」。再过几轮，已经批准过的 npm test 又被问了一遍。

用量顶到窗口边上之后，系统必须压历史。如果把什么时候压、怎么压写进同一段判断，换提供方或加一种不叫模型的空窗，判定入口都要跟着改。中途压完还要继续采样，发消息前压完则下一轮才会重注，这两件事对摘要位置的要求也不一样。

Codex 把时机写成 CompactionPhase：发消息前的 PreTurn、工具跑完还要续跑的 MidTurn、用户手动的 StandaloneTurn。实现写成 CompactionImplementation：本地再采一次样、旧的 /responses/compact、新的 compaction_trigger。分析事件另有 Trigger 和 Reason 两套标签。自动路径共用 run_auto_compact，手动路径共用 CompactTask。九宫格是乘法表，源码里没有九套并列函数。

三个自动时机都先问同一个函数。token_limit_reached 在缓冲后的 compact 限额或满窗任一触发时为真。中途还要多一道闸：后面还要继续，并且模型刚请求了新窗口或 token 已经到顶。只满不续，这一轮自然结束，下一轮用户消息到来时走预采样。

出处：codex-rs/core/src/session/context_window.rs 第 74 至 91 行；codex-rs/core/src/session/turn.rs 第 458 至 483 行

分发器第一句看 TokenBudget。开了就换空窗，远端和本地都被跳过。关了再按提供方能力选：认 compaction_trigger 且特性开，走远端 v2；认 V2 但特性关，走旧远端接口；Unsupported 走本地。TokenBudget 默认关，RemoteCompactionV2 默认开。默认 OpenAI 会话走远端 v2。

出处：codex-rs/core/src/session/turn.rs 第 1178 至 1201 行；codex-rs/features/src/lib.rs 第 1428 至 1433 行、第 1542 至 1547 行

什么时候该换窗，和窗里装什么，是两件独立的事。换语言重写，仍要先选相位再选管道。提供方只有一个时，也可以先把判定和安装拆开。

服务端带回的 transcript 可能夹着过期 developer 指令。不滤就和本地按当前 world state 新渲染的环境叠在一起，效果等价于有人改了旧行。中途压完还要在同一轮继续采样，模型被训练成摘要是历史上最后一项。上下文如果插到摘要后面，训练约束就破了。

滤网是完整的穷尽 match。丢掉 developer、非用户内容的 user 包装、工具调用和压缩触发项。留下真实用户消息、持久化 hook prompt、assistant、压缩项。v2 复用同一函数。

出处：codex-rs/core/src/compact_remote.rs 第 370 至 397 行

然后按 InitialContextInjection 决定插不插。预采样和手动用 DoNotInject：替换历史里没有初始上下文，并清掉 reference_context_item，下一轮普通 turn 会走完整重注。中途用 BeforeLastUserMessage：当前环境和权限插到最后一条真实用户消息之上，摘要仍在队尾。插入函数还有兜底：没有真实用户就插在摘要前，再没有就插在最后一条 compaction 项前。

出处：codex-rs/core/src/compact.rs 第 59 至 74 行

三种实现最后都进 replace_compacted_history。live history 整表替换。history_version 只在这时加一，追加不碰版本号。Guardian 复用 transcript 时会核对 parent_history_version，版本变了就不能复用旧的审查前缀。

出处：codex-rs/core/src/context_manager/history.rs 第 298 至 302 行

远端结果只要不是本地函数吐出来的，进门先丢掉指令包装。插入点挡的是训练约束和重注时机，这两件事本来就分开。版本号只在重写时前进，因为追加每轮都发生。

有时用户只想换一扇干净的窗，不要摘要。空窗如果走另一套生命周期，hook 和 ContextCompaction 条目会看不见这件事。这个开关默认关，避免用户在没意识到时丢掉整段对话。

TokenBudget 跳过模型和服务端摘要，安装一扇新窗口，摘要字段是空字符串。模型在新窗口里看不到旧对话，只看到此刻的环境和权限。这和 new_context 工具那句合同一致：换窗，不摘要。它仍然走压缩生命周期，pre-compact hook 若停下，窗口还没换。

出处：codex-rs/core/src/compact_token_budget.rs 第 21 至 25 行

本地路径自己碰上满窗，不递归调用自动压缩。它删最老的一条再打一次。只剩一条还超，就标满窗并返回错误。远端失败也不会改走本地：普通满窗触发的预压缩和中途压缩都把 fallback 传成 None，第一次远端失败直接返回。超时不在可重试名单里。

出处：codex-rs/core/src/compact_model_fallback.rs 第 8 至 20 行

压缩是一次换窗的生命周期，产物可以是摘要，也可以是空房间。递归要自己挡住：手动任务不进 turn 循环，本地超窗靠修剪，中途路径靠压成功就会低于限额。假设不成立时，循环可以再次进入。

列表要快，恢复要对。一份文件很难同时满足。JSONL 追加便宜，用 jq 就能读。按工作区、置顶、归档去筛，它就不合适。SQLite 擅长这些过滤，却不该成为恢复时拼模型输入的地方。

两件看起来相反的事故，其实指向同一条规则。state_5.sqlite 被删掉，列表空一阵又长回来，对话还在。你用手改库里的标题和 cwd，刷新后有时跟着变，有时又变回去。镜像可以重建，也可以被原文覆盖。原文丢了，镜像救不回来。

Codex 拆成两轨。Session 不直接碰文件，它把已经构造好的 item 交给当前的 LiveThread。没有 live handle，或者 append 失败，turn 本身不因此中断，错误只进日志。

出处：codex-rs/core/src/session/mod.rs 第 3753 至 3759 行

LiveThread 先按策略过滤一份观察用的副本，交给 store 的仍是原始切片。store 自己再跑一遍白名单。流式增量、审批、警告这些瞬时 EventMsg 进不了 JSONL。Compacted、TurnContext、WorldState、SessionMeta 一律留下。

写的顺序固定。先让 JSONL 落盘，再投影到 SQLite。投影失败可以下次重做。JSONL 失败，SQLite 不能顶上去。

追加写和随机查要的物理形状不一样。绑在同一份格式上，要么列表变慢，要么每次追加都改整份文档。拆开之后，写路径可以先保证原文，再修镜像。换语言重写，合同还是这句。

如果先写 SQLite 再补 JSONL，进程死在两步中间，列表里会出现点不开的会话。用户看见标题，点进去没有对应行。这种不一致比列表暂时为空更难查。

Paginated 模式下，注释把 SQLite 写成可重建视图。flush 屏障必须先赢，投影可以落后，不能超前。durable_write 返回 Ok 之后，materialize_to_sqlite 才许开始。投影出错只打 warn。

出处：codex-rs/thread-store/src/local/live_writer.rs 第 335 至 347 行

落到字节的那一步，一行 JSON 加一个换行，write_all 后再 flush。这里的 flush 是 tokio 文件缓冲，源码没有再调 sync_all。进程被立刻杀掉时，最后几行可能停在内核页缓存里。下次打开会补换行，坏掉的半行计进 parse_errors。

出处：codex-rs/rollout/src/recorder.rs 第 1968 至 1974 行

恢复、fork、压缩回放只读 JSONL。列表优先走 SQLite。库不存在、打开失败、回填未完成，一律退回扫 ~/.codex/sessions/ 目录，并打稳定指标 codex.sqlite.fallback.count。

出处：codex-rs/rollout/src/recorder.rs 第 547 至 559 行

可重建的东西允许丢，不允许抢跑。两边绑进同一个事务，镜像一慢，原文也写不进去。允许落后、禁止超前，是日志加派生表的通用合同。

压缩会换掉一段历史。如果 Compacted、WorldState、TurnContext 只活在内存或只活在 SQLite，删库之后窗口号和基线一起丢。用户以为模型忘了，加载器其实只是没读到那三行。

压缩先改内存历史，再按 Compacted、WorldState、TurnContext 的顺序落盘。WorldState 必须跟在 replacement history 后面，因为它是这份新历史的基线。

出处：codex-rs/core/src/session/mod.rs 第 3417 至 3427 行

恢复时反过来读。从后往前扫，碰到带 replacement_history 的 Compacted 就切断更早的后缀，并清掉更早的 TurnContext 基线。再正序重放 WorldState，full 快照重置基线，patch 往上合并。

出处：codex-rs/core/src/session/rollout_reconstruction.rs 第 155 至 188 行

这三类对列表几乎无用。apply_rollout_item 碰到 Compacted 和 WorldState 是空操作。镜像不是全文索引，是列表和筛选要用的字段。标题来自 UserMessage，不从模型的 ResponseItem 猜。

出处：codex-rs/state/src/extract.rs 第 14 至 34 行

恢复合同写在文件里。改持久化形状等于改恢复合同。仓库根的 AGENTS.md 把从已有 rollout 恢复会话列进破坏性变更检查清单。文件还在，会话就能按合同重放。

你刚接上 MCP filesystem，模型这一轮还在跑。要是按整轮用户对话冻工具表，新连上的服务器得等下一条用户消息才进菜单。要是每调一次工具冻一次，同一次采样里并行的两次调用可能看见两份不同的表。

广告一份、执行另一份，或者执行到一半表变了，是工具表最常见的翻车。

Codex 把这一次采样的模型、审批、环境、MCP 绑定和已经算完的 tool_router 一起放进 StepContext。注释写明它是 request-scoped：采样请求之间可以变，同一次采样里不变。tool_router 是 this exact sampling request 的计划。

采样进行期间，模型看见的名字和能 dispatch 的 runtime 都读这份快照。MCP 服务器在这次采样中途掉线，改不了已经算完的表。下一次采样会再走 mcp_runtime_for_step，绑定可能复用，也可能换成空绑定。出处：codex-rs/core/src/session/step_context.rs 第 17 至 47 行；codex-rs/core/src/session/mcp.rs 第 348 至 357 行

所以冻结单位是 step，不是 turn。一个 turn 里可以有多次采样，每次重建一份 StepContext。出处：codex-rs/core/src/session/turn.rs 第 1318 至 1320 行

可见和可执行共用一份快照，下一轮再吸收新连接。换个语言重写，最小形态仍是一个函数：输入开关、MCP 目录、身份，输出可见表和可执行表，请求开始时算一次，算完就冻。

审批模型如果看见工作模型那整张 MCP 和协作工具表，它就能去 spawn_agent、读外部资源，审批本身被绕开。先注册全表再过滤，漏一条分支就会把不该给的名字送出去。

规划函数按身份决定走哪些来源。Guardian 评审员的标签必须恰好是 guardian。权限档案不是 Managed，函数直接返回，注册表是空的。Managed 且有环境时，最多三件：exec_command、write_stdin、可选 view_image。普通会话才走 shell、MCP 资源、实用工具、协作这四组，再追加 MCP、扩展和动态工具。出处：codex-rs/core/src/guardian/review.rs 第 212 至 220 行；codex-rs/core/src/tools/spec_plan.rs 第 144 至 164 行、第 889 至 934 行

读盘也没有一等入口。handlers 目录里没有 ReadFileHandler。模型要读文件，走 exec_command、MCP filesystem，或 view_image 内部的 exec-server API。

身份一变，整组来源都不走。默认关上门发生在评审员、环境缺失、特性关闭这几处，换语言也用得上。

MCP 工具的 schema 很贵。全挂上，初始请求的 token 会被描述文本吃掉。两个 server 都提供 read_file，不消歧就会撞名。

暴露态把注册表拆成几条可见面。Direct 进初始表。Deferred 只留给 tool_search。Hidden 只留给 dispatch。搜索开着时，MCP 工具默认 Deferred，不进初始可见表。出处：codex-rs/tools/src/tool_executor.rs 第 51 至 80 行；codex-rs/core/src/mcp_tool_exposure.rs 第 90 至 94 行

finalize_tool_router 只在两件事同时成立时才挂 tool_search：模型支持 search tool，并且注册表里还有至少一个 deferred 且带 search_info 的工具。没有 deferred，它不会进表。出处：codex-rs/core/src/tools/spec_plan.rs 第 335 至 370 行、第 578 至 580 行

两个 MCP server 的同名工具，在规范化阶段消歧：默认加 mcp__ 前缀，sanitize 后仍撞车再加 12 位哈希后缀。外部工具撞到已占用的核心名，直接跳过。仓库根 AGENTS.md 仍写着 mcp_connection_manager.rs，当前树里没有这个文件，消歧在 tools.rs。出处：codex-rs/codex-mcp/src/tools.rs 第 1 至 5 行、第 113 至 151 行；AGENTS.md 第 35 行

可见、可检索、可执行是三份集合。token 预算紧就推迟发现，核心名保留、外部让路。这些不依赖 Rust。

你让模型同时读 src/main.rs、读 src/lib.rs，再打一处补丁。屏幕上两份读文件几乎同时出进度，打补丁那一下却停了一拍。

如果运行时把可以并行理解成这些调用叠着跑，两个 apply_patch 会一起改共享的 diff 记账，账会乱。如果这些调用首尾相接，两个读文件也要排队，多耗一轮墙钟。请求侧那面旗只回答模型愿不愿意一次发多个盒子，回答不了盒子落地时谁能重叠。

发给模型的旗写在 Prompt 上。字段默认是 false，采样主路径走 build_prompt，把旗写成 true。编成 Responses 请求体时，再和模型是不是 Responses Lite 做一次与。Lite 上这面旗关掉。压缩那两条组包路径也写死 true，为的是和主采样请求的形状对齐，websocket 复用会逐字段对比，其中就包括这面旗。

出处：codex-rs/core/src/session/turn.rs 第 1312 至 1328 行 · codex-rs/core/src/client.rs 第 946 至 953 行

执行侧另有一张表。ToolExecutor 默认 supports_parallel_tool_calls 返回 false。漏写覆盖就走写锁。exec_command、view_image、tool_search 覆盖成 true。apply_patch 不覆盖。路由先查注册表，查不到当 false。曝光是 Hidden 的，handler 自己返回 true 也没用。MCP 还要服务器开关或只读提示，缺省仍是串行。

出处：codex-rs/tools/src/tool_executor.rs 第 122 至 124 行 · codex-rs/core/src/tools/registry.rs 第 470 至 473 行

模型只看见 parallel_tool_calls 为 true 或 Lite 下的 false。它看不见谁能并行。工具清单也不会因为某个工具其实要拿写锁而少掉一项。

对模型的许可以和宿主调度拆开，换语言重写也用得上。请求侧只回答愿不愿意一次发多个调用。执行侧只回答这一次能不能和别人重叠。Lite 测试把旗关掉，说明作者接受某些模型路径上失去这层提示。闸门始终在。模型如果仍在一条响应里发出两个调用，两个任务照样 spawn，照样按本地表拿锁。

分类对了，还要有人看门。两个读可以共存，一个写必须独占。若先握住锁再等 MCP 服务器连上，一次冷启动会让旁边已经就绪的 exec_command 也卡住。

还有公平性。若后来的读者能从写者头顶上翻进去，补丁可能一直拿不到锁。换成标准库那把 RwLock，优先级依赖操作系统，写者有机会被饿死。

一次采样共用一把 tokio::sync::RwLock<()>。锁保护的值是单元类型，里面没有业务数据，只当闸门。任务先 spawn，可选地等就绪，再拿锁。能并行就 read，否则 write。就绪等在锁外面。一个还没连上的 MCP 服务器，不会占着写锁让旁边的 shell 也卡住。

出处：codex-rs/core/src/tools/parallel.rs 第 144 至 156 行

这把锁的优先级是 fair，也叫 write-preferring。已经排队的写请求没拿到、没释放之前，后面的读锁不会发下去。一个 view_image 还在跑，apply_patch 已经在门外，再来的 exec_command 明明可以和 view_image 重叠，却必须排在补丁后面。fair 换来的是写者不会饿死，代价是后来的读者被写者隔开。

分类粒度是工具实例，看不到这一次的参数。exec_command 无论跑 ls 还是 rm，都走读锁。apply_patch 无论补丁多大，都走写锁。两个无关的串行工具也会互相挡住。检索业务代码，没有容量上限。十个 shell 可以一起进。容量交给进程、沙箱和操作系统。

问的是这一刻有没有独占者。餐厅可以多人同时看菜单，只准一人进后厨。公平策略写在锁的实现里。业务代码只问并行还是独占。换一把会让新读者插队的锁，写者就有机会被饿死。把就绪等待放在锁外面，也是同一类判断：还没准备好的人，不要占着门口。

两个 exec_command 叠着跑，后发出的可能先跑完。若按完成顺序写历史，模型下一轮看到的结果顺序会和它发出的调用对不上。流内每到一条 OutputItemDone 就建 future，那一套管的是何时开工。这里管的是开工之后谁能重叠，以及结果按什么顺序入账。

采样循环把 tool_future 按到达顺序推进 FuturesOrdered。drain 按插入顺序出队，再写入会话。读锁让两个 shell 叠着跑，入账仍按发出顺序。先发出的先入账，哪怕它其实更晚跑完。

出处：codex-rs/core/src/session/turn.rs 第 2130 至 2140 行

观测顺序和执行重叠从结构上分开。并行只改墙钟，不改账本。自己做 Agent 时，至少把这两条队列分开写。对模型说可以并行，跑工具时再看本地表，结果仍按调用列表的原顺序收下。

模型要装依赖，发出 npm install。同一轮里又开 vim 改 README。若每种执行各写一套审批和沙箱，Guardian、网络代理和审批缓存会复制三遍，改一处漏两处。

对外只有 exec_command 和 write_stdin。前者开进程，后者往已有进程写，空写就是一次 poll。内部跟踪的是 process_id，模型侧参数名叫 session_id。管理器只准备请求，审批、选沙箱、重试交给编排器。

出处：codex-rs/core/src/unified_exec/mod.rs 第 12 至 17 行

本地拉起按两个开关三选一。tty 为真走 PTY。tty 为假且 stdin 开着，走带 stdin 的 pipe。否则走不带 stdin 的 pipe。远程环境或带 shell snapshot 的请求不走本地 spawn，它们走 exec-server。Windows 受限令牌是单独一条后端。

出处：codex-rs/sandboxing/src/spawn.rs 第 97 至 127 行

默认工具调用常常是 pipe。模块注释里的拉起 PTY，只覆盖 tty=true 那一支。要完整终端能力，模型必须显式打开 tty。环境变量还会钉死 TERM=dumb、PAGER=cat 一批值，交互程序先被削一层。

政策逻辑集中，进程形态可以换。换语言重写，仍是入口统一、拉起方式按特征分。PTY 怎么实现，可以留在自己的仓库里。

沙箱拒了写 /etc/hosts，stderr 里是 Operation not permitted。运行时若把这条当成命令写错，模型会改源码、换路径、加 sudo。认出来，它才有机会按策略再跑一次，或者把拒绝正文喂给模型去申请权限。

本地进程接住之后，退出通道里已经有码、通道关了、或者 150 毫秒内退出，才会做拒绝检查。超过这个窗口，只挂一个后台任务等退出，把还活着的进程交回去。编排器重试依赖这里返回 SandboxDenied。进程活过 150 毫秒，编排器已经拿到 Ok，后面再死就进不了第二次 spawn。

出处：codex-rs/core/src/unified_exec/process.rs 第 38 行 · 第 349 至 367 行

exec-server 路径有同一段超时。检查函数自己还先等 20 毫秒，让输出通知有机会到达。判定还有三道短路：进程还没退出，直接放过；已经是 SandboxType::None 且执行器没报拒绝，也放过。其余情况才跑共享启发式。

出处：codex-rs/core/src/unified_exec/process.rs 第 290 至 324 行

活过窗口的进程先入库，再开始 yield。打断 turn 时，不能因为最后一个 Arc 被丢掉而把后台进程杀掉。yield 等到进程已经退出，管理器会再跑一次拒绝检查。这时编排器早已返回 Ok。这个错误直接回 handler，收成带正文的工具回执，process_id 置空。

出处：codex-rs/core/src/unified_exec/process_manager.rs 第 535 至 556 行 · codex-rs/core/src/tools/handlers/unified_exec/exec_command.rs 第 384 至 407 行

一次性命令可以等到结束再判定。持久进程必须有截止时间。漏掉截止，跑了几秒才失败的命令会被当成拒绝再裸跑。副作用已经写到磁盘上，第二次是另一份进程，源码里没有回滚。

模块头写：被拒之后按策略用 SandboxType::None 再试，并且靠缓存不再问一遍。Never、OnRequest、Guardian strict、带 deny-read 的档案，都会把不再问或无沙箱重试关掉。用户按 Esc 若把 vim 一起带走，下一轮找不到这个 session。

出处：codex-rs/core/src/unified_exec/mod.rs 第 7 至 8 行

编排器只认一种错误：SandboxErr::Denied。认出来之后过五道门。unified_exec 声明自己会升级。Never 和 OnRequest 默认不要无沙箱重试，把带原文的拒绝表面给调用方。档案里有 deny-read 时，绕过沙箱会把这些拒绝读静默放行，所以 unsandboxed 关掉。Guardian 的 strict auto-review 把第一次批准只覆盖沙箱内尝试。第二次允许 unsandboxed 时落到 None。

出处：codex-rs/core/src/tools/runtimes/unified_exec.rs 第 159 至 161 行 · codex-rs/core/src/tools/sandboxing.rs 第 330 至 337 行 · 第 269 至 278 行 · codex-rs/core/src/tools/orchestrator.rs 第 411 至 415 行 · 第 444 至 460 行

用户在 TUI 里按 Esc，协议入口是 Interrupt：中止当前任务，不杀后台 terminal。要杀全部后台，另有 CleanBackgroundTerminals。先入库再 yield，turn 令牌被取消时，进程的 Arc 还在。pipe 会话收不到普通按键，只有 \u{3} 会走 interrupt。

出处：codex-rs/protocol/src/protocol.rs 第 546 至 552 行

用户选中的隔离级别不能被运行时悄悄改掉。停思考和停终端是两件事。取消只停等待，不杀已登记的进程。

出处：packages/terminal/tool-terminal/src/index.ts 第 156 至 160 行 · crates/codegen/xai-grok-shell/src/session/acp_session_impl/spawn.rs 第 2048 至 2070 行

同一份仓库，三台机器，模型发出同一条 git status。配置里写的是同一份权限档案：工作区可写，网络收紧。

排障的人会以为沙箱没生效。日志里档案还在，模型上下文里那份 environment_context 也还在。只是平台这一层没有把档案编译成包装命令。Windows 上开关关着，编译器交出原 argv，策略层还在。

SandboxManager 先问要不要，再问有没有。should_sandbox 只返回一个布尔。Forbid 恒假，Require 恒真，Auto 看档案形状。有托管网络要求，必须上。网络收紧时，除了调用方自己管文件系统，都要上。网络放开且文件系统不受限，才跳过。

出处：codex-rs/sandboxing/src/manager.rs 第 310 至 329 行 · codex-rs/sandboxing/src/policy_transforms.rs 第 541 至 561 行

然后 get_platform_sandbox 按操作系统给类型。macOS 给 Seatbelt，Linux 给 seccomp helper。Windows 多一个开关，关着就是空。空的意思是这台主机没有可派发的实现。

出处：codex-rs/sandboxing/src/manager.rs 第 62 至 76 行

select_initial 先问前者，再把后者的空收成 SandboxType::None。档案说需要，主机给不出，类型仍是 None。

出处：codex-rs/sandboxing/src/manager.rs 第 293 至 306 行

配置里的意图和主机上的后端，本来就会分手。产品文案、状态栏、模型说明如果都去读配置里希望启用的那一侧，排障会从这里开始歪。两个函数，一个返回布尔，一个返回可选的后端名。换语言重写也用得上。

权限如果写成两份，改了一边忘了另一边，模型就会按旧边界规划下一步。模型看见没有外层沙箱，和 Windows 关沙箱时落到 None，应该是同一份意图的两个出口。

PermissionProfile 三个变体写的是谁负责建外层沙箱。Managed 由 Codex 自己拼包装命令。Disabled 不要外层。External 文件系统由调用方负责，网络仍可能归 Codex 管。

出处：codex-rs/protocol/src/models.rs 第 411 至 425 行

transform 按类型分派。None 原样传出用户 argv，连本机 cwd 都不准备，因为未沙箱的请求可能带着外机路径。macOS 只信任 /usr/bin/sandbox-exec，策略走 -p，路径走 -D，用户命令放在 -- 后面。Linux 把整份档案序列化进 --permission-profile，helper 缺失直接报错，不会按无沙箱降级。Windows 第一拍只校验，argv 不动；包装器就是当前 exe，套壳推迟到 transform_for_direct_spawn。

出处：codex-rs/sandboxing/src/manager.rs 第 365 至 459 行 · codex-rs/sandboxing/src/seatbelt.rs 第 52 至 56 行 · codex-rs/sandboxing/src/landlock.rs 第 15 至 23 行 · codex-rs/sandboxing/src/manager.rs 第 484 至 518 行

同一份档案由 FileSystemContext 收成内部枚举，渲染进 environment_context。Disabled 写成 type="disabled" 加 unrestricted 文件系统。模型可见文本挡不住越权，只减少无效尝试。

出处：codex-rs/core/src/context/environment_context.rs 第 96 至 116 行

运行时事实只应有一份。隔离发生在子进程入口，编排层继续拿路径和档案，到执行边界才落地。平台方言会变，这份同时喂给包装命令和模型的档案形状用得上。

单条命令还可以再带一份 overlay。如果人批的时候用并集，一次误批就能把请求里没有的路径写进会话授权。

合并走并集：任一侧打开网络，结果就是开网；文件系统条目首尾相接去重。求交走另一套：网络必须两侧都开才留下；文件系统只保留落在请求范围内的已批条目。求交结果为空，会话不记账，基座档案继续生效。空集的含义是这次额外开口没留下任何加宽。命令还能不能跑，要看后面的策略和沙箱。

出处：codex-rs/sandboxing/src/policy_transforms.rs 第 90 至 142 行 · codex-rs/sandboxing/src/policy_transforms.rs 第 144 至 214 行 · codex-rs/core/src/session/mod.rs 第 2833 至 2846 行

加宽和批准是两件事。并集让这条命令多开一条路径这件事说得清。求交保证人批下来的不宽过请求。空集表示开口失败，不要解释成改成最严，也不要解释成整条命令禁止。

出处：packages/sandbox/sandbox-local/src/index.ts 第 316 至 333 行 · crates/codegen/xai-grok-sandbox/src/lib.rs 第 117 至 136 行

同事把仓库设成可写根，让模型在里面改代码。模型执行 mkdir .codex，想在仓库里落一份自己的配置。命令立刻失败，stderr 写着 Operation not permitted。可写根听起来像整棵树，实际不是。

再试一条更绕的路。模型先在仓库里写一个普通文件，再 mv 整个工作区，想把里面的 .codex 一起挪到沙箱外面。这条也失败。错误还是 Operation not permitted。

macOS 上 get_platform_sandbox 直接返回 MacosSeatbelt。那个布尔开关只对 Windows 有意义。包装器不是 Codex 自己的 exe，是系统里固定路径的 /usr/bin/sandbox-exec。PATH 上放一个同名二进制没用。

出处：codex-rs/sandboxing/src/manager.rs 第 62 至 76 行 · codex-rs/sandboxing/src/seatbelt.rs 第 52 至 56 行

策略文本分两层。四份 .sbpl 用 include_str! 编进二进制，当静态基线。动态段按这一次的可读可写根现拼。拼接顺序固定：基线、读、写、网络在前。全盘可读才加 preferences。受限读才加平台默认路径。祖先的 file-write-unlink 放最后，避免前面更宽的 allow 把 rename 用的 unlink 重新打开。

出处：codex-rs/sandboxing/src/seatbelt.rs 第 21 至 27 行 · codex-rs/sandboxing/src/seatbelt.rs 第 985 至 1012 行

基线第一句业务规则是 (deny default)。没写明的事一律拒绝。子进程继承这份底稿，sandbox-exec 拉起的 bash 再 fork 出来的子孙，仍在同一套规则里。

Seatbelt 的内核接口就是吃一份 SBPL 文本。能控的是文本怎么生成。默认拒绝，再按这一次的根往上开门，换语言重写也用得上。片段的顺序是合同：更窄的 deny 必须能压住前面更宽的 allow。

有人把工程放在 ~/work/app (copy) 这种带括号和空格的目录里，或者路径里出现引号。SBPL 里括号、引号、分号都是语法。路径一旦插进策略正文，用户目录名就能变成语法。sandbox-exec 解析失败，模型看到的是包装器错误，不是沙箱拒绝。

动态读写规则只往正文里写 (param "WRITABLE_ROOT_0") 这类键名。真实路径写成 -DKEY=value，成为独立 argv。排除子路径同样走参数表。策略正文和 -D 必须同时出现，测试把这件事锁成合同。

出处：codex-rs/sandboxing/src/seatbelt.rs 第 1022 至 1028 行

安全策略如果最终是一段文本，用户可控的字符串不要进这段文本。模板只含占位符，真实路径、域名、端口走另一份参数表。和 Seatbelt 语法无关。Python 里同样是模板加 argv。

只写 subpath，第一次创建这个目录会漏，mkdir .codex 会成功。元数据保护变成空壳。不加 file-write-unlink，rename 能把只读子树挪出挖空区。下一次若仍按原路径授权，实际写的是链接对面。

排除子路径时，require-not 要写两条。literal 管目录自己，subpath 管下面的内容。两条一起放进 require-all，是并且关系。顺序不敏感，少写 literal 才是。

出处：codex-rs/sandboxing/src/seatbelt.rs 第 548 至 555 行

可写根默认保护三个顶层名字：.git、.agents、.codex。可写根目录本身再钉一条 deny file-write-unlink。可写根中间若有用户可控的符号链接，拼装直接报错，不会跟着链接走。

出处：codex-rs/protocol/src/permissions.rs 第 24 至 33 行 · codex-rs/sandboxing/src/seatbelt.rs 第 504 至 509 行 · codex-rs/sandboxing/src/seatbelt.rs 第 441 至 450 行

网络是另一段动态文本。要走代理却没有可用端口，返回受限网络段加网络基线，不给 (allow network-outbound) 这种整网放行。网络基线还在，只是没有 blanket outbound。

出处：codex-rs/sandboxing/src/seatbelt.rs 第 309 至 335 行

挖空一条路径，同时挡住节点本身和它的子孙。再挡住对这个节点的 rename。三条一起生成，用测试锁住形状。跨平台错误文案不同：macOS 常见 Operation not permitted，能被现有关键词表接住。不要假设另外两个平台也是这句话。

出处：codex-rs/sandboxing/src/denial.rs 第 50 至 58 行

同事在 Mac 上跑 Codex，agent 去读 ~/.ssh/id_rsa，Seatbelt 立刻回 Operation not permitted。同一份仓库放到 Linux 笔记本上，常见文案变成 No such file or directory。路径常常根本不在挂载里。

如果先打开 PR_SET_NO_NEW_PRIVS，再去调系统自带的 bwrap，不少发行版上的 setuid 二进制会直接起不来。沙箱在装得最全的机器上反而失败。seccomp 是一套内核过滤器，用来规定进程还能调用哪些系统接口；no_new_privs 是它的前置条件，也会挡住 setuid 提权。

默认路径两次进入同一份 helper。外层只拼 bubblewrap，把文件系统换成默认只读，再叠可写根，.git、.agents、.codex 即使落在可写根里也保持只读。内层才打开 no_new_privs、装网络 seccomp，然后 fork、把进程镜像让给用户命令。

函数头把顺序写成三步：

/// Entry point for the Linux sandbox helper.
///
/// The sequence is:
/// 1. When needed, wrap the command with bubblewrap to construct the
///    filesystem view.
/// 2. Apply in-process restrictions (no_new_privs + seccomp).
/// 3. `execvp` into the final command.

字段注释把原因写在旗标上：bubblewrap 可能依赖 setuid，必须先建好视图，再收紧。出处：codex-rs/linux-sandbox/src/linux_run_main.rs 第 117 至 121 行；codex-rs/linux-sandbox/src/landlock.rs 第 57 至 65 行

能看见什么，和能调用哪些 syscall，是两道墙。先换世界，再收紧调用。换成别的语言重写，发行版上只要还有 setuid 包装器，这个顺序就还成立。

bubblewrap 和 seccomp 必须发生在即将变成用户命令的那个进程里。主 CLI 自己 unshare 再 exec，失败会把整次会话带走，也没法在 PID namespace 里留下一个收孤儿的 1 号进程。超时和取消会留下睡眠进程。

Linux 看 argv[0] 的 basename。文件名已经是 codex-linux-sandbox 就保留，否则改成这个别名，把同一份二进制拐进 helper。外层 exec 的不是 ls，是 helper 自己，带着 --apply-seccomp-then-exec。launcher 还会插进 --as-pid-1，让 bubblewrap 自己当命名空间里的 1 号进程。

内层先 capget。effective 或 permitted 任一非零，立刻 panic，命令不会跑。过了这道检查，才 fork。子进程 execvp，父进程 waitpid(-1) 把子孙都收掉，退出码原样传出。出处：codex-rs/linux-sandbox/src/linux_run_main.rs 第 216 至 221 行、第 242 至 243 行；codex-rs/linux-sandbox/src/launcher.rs 第 38 至 39 行

独立辅助进程加先包装、再收紧，是跨平台同一类自我调用。Windows 看隐藏参数，Linux 看 arg0。包装器失败时，固定退出码加固定 stderr 前缀更好自动归因。

类型名还叫 LandlockCommand，crate 目录也叫 linux-sandbox，网上不少资料会写成 Codex 在 Linux 上用 Landlock。当前默认文件系统沙箱已经是 bubblewrap。Landlock 是显式打开的 legacy 回退，特性开关标成 Deprecated，默认关。legacy 吃不下受限读，也吃不下拆分出来的嵌套只读。

如果 bwrap 失败后静默换 Landlock，模型会按「我被关在视图里」规划，实际却还看得见主机文件树。下一步就会分叉。

外层写明 never falls back。bubblewrap 失败就失败。WSL1 在需要 bubblewrap 时，transform 返回 Wsl1UnsupportedForBubblewrap，命令不会进 helper。全盘可写且不走代理时，根本不会进 bwrap，WSL1 可以过。user namespace 建不出来给启动警告，不会改走更弱的后端。出处：codex-rs/linux-sandbox/src/linux_run_main.rs 第 290 至 294 行；codex-rs/sandboxing/src/manager.rs 第 413 至 420 行、第 696 至 710 行；codex-rs/features/src/lib.rs 第 1064 至 1069 行

跨平台能力不对等时，最容易犯的错是用「我们有 Linux 沙箱」覆盖所有 Linux。本机有新 bwrap、CI 容器禁了 user namespace、同事还在 WSL1，三台机器不是同一道墙。产品文案和模型说明必须按实际启用的那一层来写。

同事在 Mac 上跑 Codex，agent 去碰用户目录里的 SSH 私钥路径，立刻被 Seatbelt 拦住，错误写着 Operation not permitted。同一条读取放到 Windows 上，报错变成 Access is denied。再换一台没开 Windows 沙箱的机器，这条命令可能根本走不到 ACL，execpolicy 先把它判成 Forbidden 或 Prompt。

三台机器、同一份意图、三种失败。模型看到的下一句话不一样，下一步也会跟着变。如果 Windows 上假装有和 Unix 一样的默认沙箱，模型会按自己被关着去规划，实际命令裸跑。

macOS 限制这个进程能对哪些路径做哪些操作。Linux 限制这个进程能看见什么、能调哪些系统调用。Windows 没有 namespace，也没有 seccomp。Codex 换成另一套问题：这个身份能碰哪些资源。

令牌决定你是谁。RestrictedToken 档从当前用户令牌裁，Elevated 档先用专用账户登录，再从那个令牌裁。两边最后都进同一组标志：DISABLE_MAX_PRIVILEGE、LUA_TOKEN、WRITE_RESTRICTED。特权被削薄，写必须同时通过普通 ACL 和 restricting SID 的交叉检查。

读在 RestrictedToken 这一档仍然跟当前用户走。源码自己写了：WRITE_RESTRICTED 令牌上的 capability SID deny-read ACE 不参与读检查，所以读限制必须走 Elevated，裸跑会被直接拒绝。出处：codex-rs/windows-sandbox-rs/src/token.rs 第 480 行；codex-rs/sandboxing/src/windows.rs 第 109 至 117 行

主体能做什么，和客体能被谁碰，是两套隔离原语。换语言重写，Windows 上仍然没有 bwrap 可以调用。该问的还是：你有没有一份身份，这份身份被允许碰什么。

包装方式也是同一类自我调用。Windows 用自己的 exe 加上隐藏参数 --run-as-windows-sandbox，跟 Linux 改 arg0 是同一思路。出处：codex-rs/windows-sandbox-rs/src/wrapper.rs 第 20 行

WFP 是 Windows Filtering Platform，一套内核里的包过滤框架。它和防火墙规则都按 SID 匹配。一个 SID 只能对应一套网络策略。同一身份没法同时表示完全没网，也没法同时表示可以走代理或出网。

所以用两个本地用户当两个网络身份：CodexSandboxOffline 和 CodexSandboxOnline。from_permissions 在强制走代理，或网络策略未启用时，选 Offline。离线身份装出站阻断、代理端口白名单，再加 12 条 WFP，覆盖 ICMP、DNS 53、DNS-over-TLS 853 和 SMB。在线身份不装这套阻断。

Unix 的网络隔离是给进程换一张网卡视图。WFP 是进程还在主机网络栈上，只是这个 SID 发出的特定流量被挡住。进程仍然能看见网卡、解析失败、连别的端口。

过滤器用稳定 GUID 标识，带着持久标志，重启后还在。卸载和崩溃都不会自动拆掉它们。仓库里检索不到删除用户或拆除 WFP 的函数。WFP 失败被写成非致命，防火墙失败会让 setup 整段失败。出处：codex-rs/windows-sandbox-rs/src/setup.rs 第 50 至 51 行、第 706 至 714 行；codex-rs/windows-sandbox-rs/src/wfp.rs 第 69 至 95 行

按身份做访问控制，身份数量必须覆盖策略组合数。网络策略有两档，就需要两个身份。这和用两张门禁卡进两栋楼是同一件事，跟 WFP 这个具体 API 无关。

有人会问为什么不上 AppContainer。它的可读范围默认很窄，任意路径读取要改宿主 DACL。Codex 需要 workspace 可读、平台根可读，再按 deny 列表挖空。受限令牌加 ACL 更贴这份权限模型。在 codex-rs/ 里检索 AppContainer，业务代码零命中。对照仓库 DeepSeek Harness 把同一判断写成了明文：AppContainer 做不了任意路径读取。

Elevated 要把读和网络也管住，就要建账户、弹 UAC、改防火墙和 WFP。企业策略可能禁止本地建用户。把默认设成 Disabled，等于把这道产品摩擦留给第一次启用。

枚举自己把默认值写成关。没写 windows.sandbox、两个 legacy flag 也没有时，就落回 Disabled。legacy flag 已经被标成 Removed。

pub enum WindowsSandboxLevel {
    #[default]
    Disabled,
    RestrictedToken,
    Elevated,
}

关掉之后，平台沙箱确实没了。get_platform_sandbox(false) 在 Windows 上返回空，select_initial 把它变成 SandboxType::None。命令仍可能被策略层拦住。Windows 测试锁住了这条：没有后端时，只读档案加 Never 审批，未匹配的 cmd.exe /c dir 必须是 Decision::Forbidden。出处：codex-rs/sandboxing/src/manager.rs 第 62 至 72 行、第 301 行；codex-rs/core/src/exec_policy_windows_tests.rs 第 113 至 130 行

隔离深度跟安装预算挂钩。只防模型误改仓库，当前用户受限令牌就够。要防读出密钥再从这台机器往外传，必须再做读限制和按身份的网络过滤。承诺了做不到的墙，模型和用户都会按那道墙做决策。

跨平台能力不对等时，对外说法必须按实际启用的那一层来写。macOS 默认就有 Seatbelt，Windows 默认可能是 Disabled。用户听到有沙箱，会以为三台机器同一道墙。

你给团队写一条禁令，pattern 写成 git 加 reset。本意是拦 --hard。过了一周有人报，--keep 也被拦了。前缀一短，后面跟什么都命中同一条。

再过一周，模型用 bash -lc 包了一层。禁令按字面 argv 去匹 bash，第一条对不上，命令进了启发式通道。

白名单每条都在赌两件事。一是 pattern 刚好覆盖你想拦的。二是它不会误伤你想放的。这两件事通常要等线上才知道。下一次改 pattern 的人，也看不到作者当初怕误伤哪条命令。

Codex 把正反例写进规则本身。match 里是这条规则必须命中的命令，not_match 里是它必须放过的命令。prefix_rule 并不当场跑例子，它先把规则和例子推进待校验队列。整份 Starlark 求值完，parse 再统一校验。

顺序固定。先跑反例，再跑正例。反例误命中，报 ExampleDidMatch。正例一个都没命中，报 ExampleDidNotMatch。两种错都让 parse 返回失败，Policy 不会被 build 出去。出处：codex-rs/execpolicy/src/parser.rs 第 57 至 78 行，以及第 133 至 151 行

crate README 把这件事写成一句话：它们是加载期校验的示例调用，可以当成单元测试。字符串和 token 数组两种写法进解析器后都会变成 token 列表，字符串走 shlex 拆词。校验时启发式回调传空，正例必须靠真实前缀规则命中，不能靠启发式凑数。

白名单的典型失败，是作者以为 pattern 是这个意思。把以为写成例子，机器可以反对。这条不依赖 Starlark，换成 JSON 或 YAML 也能抄。

规则和例子写在同一处，策略文件被拷进用户目录或被 overlay 下发时，例子跟着走。加载器没有只读规则、不跑例子的分支。漏写例子等于漏写测试，加载器不会替你编例子，写了就会强制执行。

正则能写 git reset 后面跟任意参数，也能写出作者自己都读不懂的例外。叠加规则时如果取最宽，用户层一条宽松的 allow 就能盖住系统层的 forbidden。

规则本体是一段前缀。匹配是精确字符串相等，没有 glob，没有正则。git reset --hard 能吃后面再跟 origin/main 的命令，因为多出来的 token 不参与比较。它吃不了中间插了 --config 的写法，因为第二个 token 对不上。出处：codex-rs/execpolicy/src/rule.rs 第 46 至 59 行

规则按第一个 token 放进桶。查找时先按 argv 第零项精确取。取不到，再考虑把绝对路径收成 basename。命中多条时，对 decision 做 max。Decision 派生了 Ord，变体书写顺序就是严重程度：Allow 小于 Prompt 小于 Forbidden。

组合命令先拆段再摊平，再取一次 max。一段 git status 是 Prompt，一段 git commit 是 Forbidden，整条管道仍是 Forbidden。出处：codex-rs/execpolicy/src/policy.rs 第 265 至 287 行，以及第 402 至 411 行

叠加只能加严，不能放宽。这个序写在枚举变体上，运行时没有另一张优先级表可以写错。换语言重写，三个字符串做成有序枚举，聚合用一次 max 就够。

前缀强迫你把意图落成 token 序列。代价是插在中间的参数会让规则失效，作者必须用更短的前缀或另写一条。正反例就是用来接住这条代价的：写短了，反例会在加载期先崩。

禁令写的是 git reset --hard。模型写成 bash -lc 包一层。按字面 argv 去匹，第一条是 bash，禁令不亮。

判定前先走 parse_shell_lc_plain_commands。它要求脚本只由纯词命令加 &&、||、分号、管道组成，拒绝重定向、替换、括号、控制流。过关后按命令节点切成多段 argv。bash -lc 包着 git reset --hard，会被拆成内层那三段，再拿去匹前缀。出处：codex-rs/core/src/exec_policy.rs 第 831 至 858 行

拆不出来时，整段 argv 当一条命令，交给启发式和后续沙箱。空引号插在参数里还能还原。空引号插在命令名里，word-only 解析失败，前缀规则看不见 git，这条命令掉进启发式。

解析器承认自己吃不下的东西，就不假装已经看懂脚本。这是 fail closed 的通用形状。它挡得住解析成功但漏掉危险段。拆失败之后，启发式和沙箱还在。

你把审批留在 on-request，沙箱从 workspace-write 拧到 danger-full-access。十分钟前那条出沙箱命令还会弹窗。现在不弹了。你没改审批旋钮。

审批策略 AskForApproval 是当前 turn 用哪套问人规则，类型里有四个变体。文件系统沙箱种类是三个，默认 Restricted，意思是只读或只能写工作区。这两颗旋钮在同一个判定函数里。改其中一颗，另一颗的行为会跟着走。出处：codex-rs/protocol/src/protocol.rs 第 924 至 947 行，以及 codex-rs/protocol/src/permissions.rs 第 227 至 232 行

一条命令先读审批策略，再看文件系统是不是 Restricted，再让 execpolicy 把 Allow、Prompt、Forbidden 叠上去。execpolicy 是按命令文本给出三态的规则文件。

默认问不问写在 default_exec_approval_requirement。Never 这一层给 Skip。UnlessTrusted 这一层给 NeedsApproval。OnRequest 和 Granular 只在 Restricted 时要问。read-only 和 workspace-write 都是 Restricted，所以这两格的默认结局一样。danger-full-access 把 kind 变成 Unrestricted，默认函数走 Skip。出处：codex-rs/core/src/tools/sandboxing.rs 第 198 至 230 行

Granular 还多一个闸。需要审批、且 sandbox_approval 关掉时，直接 Forbidden。文件系统如果已经是 Unrestricted，needs_approval 先变成假，Forbidden 分支进不去。关掉沙箱审批，只挡住本来就要弹的窗。

Never 遇到 execpolicy 的 Prompt，提问会升级成拒绝。它并不表示什么都准跑。出处：codex-rs/core/src/exec_policy.rs 第 214 至 236 行

untrusted 写不进配置。类型还在，公开字符串已经退休。用户显式写出，整次加载失败。没写才看项目信任：已信任走 OnRequest，明确未信任走 UnlessTrusted。出处：codex-rs/core/src/config/mod.rs 第 3607 至 3625 行

还有一个加载期硬拒绝。requirements 不允许 danger-full-access，配置却写了 approval_policy = "never"，加载器会先把权限档案回落到只读。只读加上从不提问，等于模型在窄沙箱里还没人可问。这种组合直接判非法。出处：codex-rs/core/src/config/mod.rs 第 3969 至 3979 行

全盘可写时，再问一次出沙箱没有意义。两颗旋钮绑在一起，少弹窗。代价是改沙箱会静默带走审批行为。换个语言重写，仍要先回答：全权模式还要不要问人。

策略枚举靠穷尽分支表达规则。新加一个变体，编译器会逼所有判定函数表态。这是类型在替运行时守门。

弹窗上两条记住长得很像。一条是本会话记住这条命令。一条是把前缀写进 execpolicy，跨会话生效。点错了，后面的边界题就会答反。

常规 exec 弹窗默认菜单里，甚至没有 ApprovedForSession。有网络上下文时才带上它。普通命令给一次批准，有前缀修正提案时再加按前缀记住，最后是取消。用户最常碰到的记住，是前缀那一条。出处：codex-rs/protocol/src/approvals.rs 第 314 至 347 行

会话缓存活在 ApprovalStore 里，跟会话同寿命。key 是规范化后的完整命令，外加 cwd、环境和 execpolicy 指纹。所有 key 都已经是 ApprovedForSession 才命中。Approved 一次放行不会进 map。出处：codex-rs/core/src/tools/sandboxing.rs 第 64 至 116 行

npm run test 批准进会话，npm run lint 是另一把 key。/bin/bash -lc 和 bash -lc 在能拆出单一明文命令时，缓存成同一组 token。会话缓存认完整命令，不认 npm *。前缀扩张只走 execpolicy。

改审批策略不会清空这座 map。key 里没有 AskForApproval。中途从 OnRequest 改成 UnlessTrusted，已经缓存的批准仍算数。改 execpolicy 会改指纹，缓存才会失效。

两套记住对应两种威胁。精确 key 挡不住换参数。前缀挡得住换参数，也容易把包装命令的范围扩太大。两层分开，才能各自配禁建议名单。一天弹窗不多的时候，先只做一次放行也成立。

策略改了，只改运行时分支不够。模型看到的说明必须同步改，否则它会按旧规则去要 require_escalated。Never 下面如果说明书还在教它提权，运行时会把提问升级成拒绝，模型只会反复撞墙。

权限说明是一段 developer 消息。先选沙箱模板，再选审批模板。Never、UnlessTrusted、OnRequest 各有现成 markdown。Never 那份只有一句：不要再给 sandbox_permissions，命令会被拒。Granular 没有第五份文件，按五个开关现场拼允许列表和拒绝列表。两套说明拼在同一段里，模型一次看到当前组合。出处：codex-rs/prompts/src/permissions_instructions.rs 第 271 至 291 行

钩子在人前面。钩子给出 Allow 或 Deny，弹窗就不会出现。钩子的 Allow 是一次 Approved，不写会话缓存。

运行时和模型说明书是同一份合同的两面。判定函数改了，字典那一行必须一起改。把这两份放在同一个模块，用同一组测试喂两边，换语言也用得上。

你开着 Codex 改仓库。模型先跑 git status，再读两个文件，然后要 git push。下一分钟它要 curl，再下一分钟要往 /tmp 写备忘，再下一分钟要删掉那份备忘。弹窗叠弹窗。人开始只看命令头两个词，拇指已经形成肌肉记忆。

这就是审批疲劳。防线还在，判断已经不在。回路退化成一个总是亮绿灯的按钮。这时如果把自动放行交给刚写出这条命令的主模型，申请人兼审批人。如果失败时放行，超时和坏 JSON 就变成免费通行证。

Codex 把该不该自动放行抽成一次专职审查。它不替代沙箱，也不替代网络代理。它只接管一类本来会弹给用户的 on-request 审批。路由很窄：策略必须是 OnRequest 或 Granular，审查员必须是 AutoReview。默认审查员仍是用户。出处：codex-rs/core/src/guardian/review.rs 第 186 至 210 行

模块头把四步写死。

你让模型去 GitHub 提一个 issue。它写出 curl，环境里有真 token。下一秒域名换成 evil.example，或者打到 169.254.169.254。只拦「不在名单里的域名」，deny 条目和内网地址会漏。空名单若默认放行，忘写配置等于全开。

判定顺序写死。先 deny，再本地或私有，最后 allowlist。空名单和没命中，都拦。决策器只能翻 allowlist 漏掉的案，翻不了 denylist，也翻不了本地网段。

出处：codex-rs/network-proxy/src/runtime.rs 第 549 至 552 行；codex-rs/network-proxy/src/network_policy.rs 第 346 至 378 行；codex-rs/network-proxy/README.md 第 161 至 162 行

*.example.com 不含 apex，**.example.com 才含。解析到私有 IP 的域名，精确写进名单也拦。本地字面量要精确写上 localhost 或 127.0.0.1，通配 * 不算。

出处：codex-rs/network-proxy/src/policy.rs 第 321 至 331 行；codex-rs/network-proxy/src/runtime.rs 第 1028 至 1043 行

被拦时回给命令进程 403，头是 x-proxy-error，正文是一句人话。not_allowed 和 not_allowed_local 对外都叫 blocked-by-allowlist，正文才能分开「不在名单」和「沙箱拦了本地」。这条 403 变成 exec 输出喂回模型，采样循环不会停。

出处：codex-rs/network-proxy/src/responses.rs 第 52 至 83 行

同一 pattern 既 allow 又 deny，有效值取大的。枚举序是 None < Allow < Deny。

出处：codex-rs/network-proxy/src/config.rs 第 19 至 27 行

默认拒绝、deny 恒胜、内网要显式开门，这是 SSRF 防护的通用形状。换语言重写，该问的还是同一组问题：没写名单时怎么办，冲突时谁赢，解析到内网的名字算不算放行。

token 跟着命令进 rollout。下一轮模型还能看见它，再下一轮可能进日志。凭据一旦进入模型上下文，后面每一层脱敏都是补救。

拉起命令前，凭据经纪把 GH_TOKEN、OPENAI_API_KEY 换成同长度、同前缀的假值。模型若 printenv，看见的是假的。假值进上下文，对上游无用。

出处：codex-rs/network-proxy/src/credential_broker.rs 第 92 至 119 行

出站时 MITM 按 host 过滤。请求头里必须带着假值，才换成真值。hook 的剥头、注头发生在经纪之后，可以剥掉刚注入的 Authorization。用户改过的环境值不还原。标记当不可信输入。经纪只覆盖 GitHub 和 OpenAI。

出处：codex-rs/network-proxy/src/mitm.rs 第 297 至 302 行

出网策略写错，模型还能凭 403 改主意。凭据进上下文，撤销成本高。所以真值在 spawn 前拿走，回填发生在代理进程内存里。假值保持形状，是为了让校验格式的客户端还能启动。

Go 的 net/http 对 loopback 绕过 HTTP_PROXY。你以为流量进了代理，其实它直连 127.0.0.1。本地有管理口、docker socket。策略文件写了名单，请求根本没走到那一层。

沙箱只放行代理端口。macOS 受限 Seatbelt 只写 localhost:{port}。Linux 走 ProxyOnly。allow_local_binding 为假时，NO_PROXY 写成空串，loopback 字面量也必须走代理。打开本地绑定等于承认 loopback 不再经过 allowlist。

出处：codex-rs/sandboxing/src/seatbelt.rs 第 309 至 336 行；codex-rs/network-proxy/src/proxy.rs 第 450 至 460 行

应用层代理挡不住不肯走代理的客户端。下一层必须是操作系统或防火墙，只留一个口。三道门叠在一起才构成托管网络。单独一道都挡不住另一道漏掉的面。

你让模型改一个函数：把 greet 里的 pass 换成 return 123。它吐出标准 unified diff，头一行写成 @@ -47,3 +47,3 @@。

文件刚才被另一处编辑插了两行，greet 已经在第 49 行。模型是在带行号的摘录里数的，写补丁时还要自己加算起始行和跨度。这四个数字一起错，是常态。

patch(1) 会按行号去找，找不到就 fuzz。fuzz 再失败，整份补丁作废。更麻烦的是它可能把变更贴到邻近的另一个函数上。测试还是绿的，只是改错了函数。

Codex 把填写和阅读拆开。模型填的那份没有行号。更新一段时，头一行只写成 @@ def greet():。单独一个 @@ 表示从当前位置继续搜。定位交给运行时的 seek_sequence。

人看变更时，界面上再另外用 similar::TextDiff 生成一份标准 unified diff。工具参数里那份 Codex 格式到这里已经用完了。

这份文法把没有行号写进了产生式。两种 @@ 写法都只带文本锚点：

//! change_context: ("@@" | "@@ " /(.+)/) LF
//! change_line: ("+" | "-" | " ") /(.+)/ LF
//! eof_line: "*** End of File" LF

发给模型的说明书把这套语言写成「stripped-down, file-oriented diff format designed to be easy to parse and safe to apply」。Add、Delete、Move 在文法里是三种标记，解析器按标记分发。模型不用记 ---、+++、/dev/null 和 rename 头怎么拼。

坐标靠加算，内容靠识别。模型数行号这件事，换一个模型、换一种语言都好不到哪去。把找到哪一段从填写时的算术，改成应用时的字符串搜索，这个分工不依赖 Rust，也不依赖 unified diff 这个具体格式。

模型写补丁时，行尾多一个空格，或者文件里是 en-dash、它写成了减号，都是高频事故。每次都整份失败，模型只能重写。按行号附近再试几行，又会回到 fuzz 贴错函数的老路。

seek_sequence 按四档从紧到松搜。第一档整行精确相等。第二档去掉行尾空白再比。第三档两边都 trim()。第四档把常见 Unicode 短横和弯引号收成 ASCII。四级都失败就返回空，报「Failed to find context」或「Failed to find expected lines」。没有按附近几行再试这个循环。

早期有一次事故，专门为奇怪的 Unicode 字符加了第四级。它只放宽空白和标点，不放宽位置。中文全角引号不在归一化表里，模型写了全角左引号，文件里是半角引号，四级都会失败。

容错要分清两类差异。行尾空格、弯引号是无意义的字节差，可以归一。行号偏了两行，是贴错地方，应该报错让模型重写。这个分界换语言重写也成立。

一份补丁里有两个 chunk。第二个对不上，第一个已经改进去了，文件会变成半成品。排查的人看到的是一份应用成功了一半的文件，比整份失败更难修。

单文件内部，compute_replacements 把每个 chunk 先收成替换列表，某一个对不上就立刻返回错误，还没走到 write_file。这个文件保持原样。

跨文件是另一回事。apply_hunks_to_files 按 hunk 顺序写盘，失败时带着已经提交的 AppliedPatchDelta 返回，循环里没有回滚。测试 015 把这个钉死了：先成功新增 created.txt，再更新一个不存在的文件，磁盘上 created.txt 还在。

算完再提交的范围，要和你能原子处理的单位对齐。一个文件可以先在内存里算完全部替换再写一次。多个文件已经落到磁盘上，回滚就要再写一遍，还要处理 Move 这种源和目标都动过的半成功。要不要跨文件事务，是产品选择，不是格式本身的承诺。写给模型的说明里，别把单文件的保证说成全局保证。

读五个文件再汇总，用普通工具调用要走五次完整往返。每次往返把整个文件内容推进上下文，模型下一轮还得把滚大的历史重读一遍。真正贵的地方在往返的节奏上，工具本身不贵。

那让模型写程序不就行了。麻烦在于，这段程序没有任何人审过一行，模型现写现交。给它一个能读文件、能发网络请求的运行时，等于把宿主的全部能力直接交出去。

Codex 给模型两个工具，exec 和 wait。exec 收一段 JavaScript 源码，扔进一个全新的 V8 isolate 当 async module 求值。所有工具挂在全局 tools 对象上，名字被规范化成合法的 JS 标识符，写起来就是 await tools.exec_command(...)。程序里想循环就循环、想分支就分支，中间值留在变量里，只有主动交出去的那部分回到模型。

关键在于这个运行时被削得很薄。工具说明书里对模型直说了它没有什么：

- Runs raw JavaScript -- no Node, no file system, no network access, no console.
- Accepts raw JavaScript source text, not JSON, quoted strings, or markdown code fences.
- You may optionally start the tool input with a first-line pragma like `// @exec: {"yield_time_ms": 10000, "max_output_tokens": 1000}`.
- `yield_time_ms` asks `exec` to yield early if the script is still running. Defaults to 10000 ms.
- `max_output_tokens` sets the token budget for direct `exec` results. Defaults to 10000 tokens.
- When the JS code is fully evaluated, the isolate's lifetime ends and unawaited promises are silently discarded.

没有 Node，没有文件系统，没有网络，连 console 都没有。这些能力不是忘了加，是特意不给。程序想产生任何副作用，只剩一条路，走 tools。那条路上审批和沙箱一样不少，该弹的窗照弹，该拦的照拦。

附带好处是要审查的面积小了。isolate 里如果能直接读文件，这一层就得自己再做一套文件权限；现在它什么都做不了，权限判断留在下一层就够，代码不用写两遍。

往返贵、批处理便宜，这是几十年的老账。数据库有批量写入，RPC 框架都在攒 batch。模型采样一轮比一次网络往返贵得多，把 N 次合成一次，收益只会更夸张。

减法这一半更通用。给不受信任的代码一个尽量小的环境，让它想干坏事都没有接口可用，这是安全设计的通用形状，和 V8 这个具体技术没关系。换成别的语言、别的沙箱，该问的还是同一个问题：这段代码到底需要哪几样能力，其余的能不能一样都不给。

程序要跑三分钟，超时该设多少。

设成三分钟，用户三分钟看不到动静，也没地方喊停。设成十秒，长任务永远做不完，更难受的是前面九秒的成果跟着一起丢，模型只收到一条超时消息，只能从头再来。两个方向都不对，问题出在把「还没跑完」当成了失败。

Codex 把正在跑的脚本做成一个有身份的东西，叫 cell。yield_time_ms 到点，cell 不死，它把这段时间攒下的输出整包交出去，然后清空缓冲继续跑。exec 这时返回一句话，告诉模型脚本还在跑，编号是多少。

模型拿到编号，手上就有三个选择：调 wait 再买一段时间；带 terminate: true 把它停掉；或者干脆先去干别的。wait 只返回上次让出之后的新输出，因为交出去的时候缓冲就被清空了，同一段内容不会重复占两次上下文。

有个小细节很能说明设计者在想什么。让出时间超过十秒时，Codex 会额外再送一秒宽限，然后才真的观察。出处：codex-rs/code-mode-runtime/src/service.rs 第 198 至 210 行刚好卡在边界上完成的脚本，不会因为差几毫秒白白多走一次往返。

还有一处不对称值得记一笔。发给模型的说明书里，wait 有四个参数：cell 编号、让出时间、返回长度上限、要不要终止。可协议层的请求结构体只带前两个，后两个停在处理器那一层，终止走的是另一条路径，长度上限是拿到结果之后才截断的。读源码的时候这两层很容易混成一层。

把「还没结束」做成一等状态，是长任务接口的通用形状。HTTP 有 202 加轮询，任务队列有 job id 加 poll，导出大文件的后台任务也是先给你一个编号。共同点是不让调用方在「一直等」和「当作失败」之间二选一，而是给一个可以再问一次的把手。

放到 agent 上，这个把手还多一层价值。模型拿到中间输出之后可以改主意，发现前四步的结果不对，直接 terminate，不用陪着跑完剩下八分钟。控制权回到了会思考的那一方手里。

模型写一段 while (true) {}，上一课见过，要靠 isolate 的 terminate 才能打断。这段程序如果和 Codex 事件循环抢同一个进程，卡死会从单个 cell 扩大到整条会话。

V8 的堆、JIT、没有条目上限的 store 表，任意一项在主进程里爆炸，都会带走 TUI 或 app-server。早期资料常把默认路径写成「主进程里直接跑 isolate」。当前特性注释已经把这句话改掉了。

出处：codex-rs/features/src/lib.rs 第 104 至 111 行

Codex 给「跑模型写的代码」留了一个提供方接口。业务层只依赖 CodeModeSession 和 CodeModeSessionProvider，自己不去 new 运行时。协议把会话收成四件事：execute、wait、terminate、shutdown。实现可以进程内，也可以远端。同会话共享 store，异会话隔离。

出处：codex-rs/code-mode-protocol/src/session.rs 第 146 至 167 行

主进程选提供方时，已经没有直接 new InProcessCodeModeSession 这条生产路径。CodeModeHost 打开，或者 disable_in_process_fallback 为真，都走向 ProcessOwnedCodeModeSessionProvider。两条都不成立，走向 DisabledCodeModeSessionProvider。

出处：codex-rs/core/src/thread_manager.rs 第 455 至 462 行

CodeModeHost 已经是 Stable，默认打开。用户看见的默认已经是本地子进程。进程内求值还在，只是沉到宿主进程内部：宿主打开会话时 new 的就是 InProcessCodeModeSession。isolate 活在小屋里，房东换成了独立二进制 codex-code-mode-host。

出处：codex-rs/features/src/lib.rs 第 921 至 925 行 · codex-rs/code-mode-host/src/lib.rs 第 599 至 608 行

拉起进程时，stdin / stdout / stderr 全管道化，Unix 上单独一个进程组，环境变量先 scrub 一遍。找不到可执行文件，availability() 直接失败，不会改去主进程里 new isolate。真正的回退发生在工具模式这一层：宿主不可用、请求的是普通 CodeMode、并且没有关掉回退时，有效工具模式变成 Direct。模型重新看见普通工具。

出处：codex-rs/code-mode/src/remote_session.rs 第 69 至 83 行 · codex-rs/core/src/tools/mod.rs 第 79 至 89 行

disable_in_process_fallback 这个名字容易让人以为还存在「回退到进程内 V8」。配置注释写的是另一件事：宿主不可用时，让 Code Mode 闭门失败。今天它控制的是「宿主没了以后，要不要从 Code Mode 退回普通工具」。

出处：codex-rs/core/src/config/mod.rs 第 1089 至 1096 行

不要让不受信任的语言运行时和 agent 主进程同命运。换成 Python 的 subprocess，换成别的 isolate，该问的还是同一句：这段代码崩了，谁还活着。

你把 app-server 指到一台远端机器的 --code-mode-host，容易以为整段 agent 都搬家了，连 exec_command 的审批弹窗都该出现在远端。当前源码对不上。远端宿主只搬走了求值。嵌套工具的审批、execpolicy、Guardian 仍在本机会话上。

宿主把 CodeModeSessionDelegate 做成 RemoteDelegate，经 IPC 打回 Codex 主进程。主进程上的 dispatch broker 才去走嵌套工具。isolate 搬家了，策略没有搬家。JS 在别处跑，副作用要绕回来问你。

出处：codex-rs/code-mode-host/src/delegate.rs 第 26 至 50 行

WebSocket 和 gRPC 是同一套求值、两套线。WebSocket 监听器拒绝带 Origin 头的请求，挡住浏览器页面跨源连到本机宿主。gRPC 把工具订阅、完成、执行流拆开，丢掉 OpenSession 那条租约流，会话关闭，正在跑的 cell 一并终止。app-server 的 --code-mode-host 认 http / https 为 gRPC，认 ws / wss 为 WebSocket。多个 thread 共享同一条远端连接，store 仍按会话切开。

出处：codex-rs/code-mode-host/src/transport.rs 第 288 至 302 行 · codex-rs/app-server/src/code_mode_host.rs 第 32 至 40 行

不可信的是 JS 世界，可信的是审批和策略。把前者搬走，后者留在有 UI 的那边。没有这条回路，远端宿主就必须复制你的整套权限系统。

一种常见预期是：你按了中断，V8 一起掐掉，下一轮 wait 立刻看到终止。当前默认对不上。另一种预期是：重连之后，刚才那段脚本还在原来的 cell 里接着跑。两种预期，源码都不认。

turn 被标成 Interrupted 时，任务取消令牌一定会取消。会不会再去 terminate 还在跑的 cell，要看 CodeModeInterrupt。这个开关还在开发，默认关。关掉时，中断只取消本轮工具调用和审批。宿主上的 isolate 可以继续跑，直到自己结束、被 wait(terminate: true) 停掉，或会话 shutdown。用户按 Ctrl-C，并不自动等于那条 terminate。

出处：codex-rs/core/src/tasks/mod.rs 第 888 至 899 行

掉线也一样。gRPC 丢掉 lease 就关会话。客户端可以再开一条租约，generation 从 1 往上加。第一代对外仍用原始 cell ID，第二代变成 g{generation}:{cell_id}。模型拿着第一代的编号去 wait，会收到 stale generation。本地子进程路径没有这套前缀，只是把状态机打回 New，再分配一个新的 session-N。对外 cell ID 仍从 1 数。两种重连都丢运行中的 cell 和那份 store。

出处：codex-rs/code-mode/src/grpc_session/generation.rs 第 49 至 67 行

store 表跟着宿主侧的 SessionRuntime。没有落盘，没有跨进程共享，没有 TTL。远端机器重启，表就没了。会话 ID 复用会被拒绝，不会把旧表偷偷接回来。重连恢复的是「还能再 exec」，不是「刚才那段脚本」。

cell 的寿命按会话算，不按 turn 算。中断轮次和杀掉程序是两件事。重连开的是新世界，旧身份证作废。自己做 Agent 时，如果用户按停止就期望程序立刻死，默认应该 terminate。Codex 默认不杀，是因为它还把 cell 当成可跨轮续跑的对象。

你让主会话派一个探索者去查 auth 模块。模型调用 spawn_agent，工具回了一句任务名 /root/explore_auth，外号 Hypatia。过几分钟点 wait_agent，信箱里躺着一份 FINAL_ANSWER。

第二天打开同一条 thread。子会话的运行时已经卸掉了。系统如果只记得昨天发生过一次调用，这条路径就找不到。你再发 send_message，控制面会报 live agent path not found。

Codex 把父子做成有向边。边只有两个值。Open 表示还能当打开的 spawned agent 恢复。Closed 表示从图的视角已经关掉。序列化是 open 和 closed。

出处：codex-rs/agent-graph-store/src/types.rs 第 4 至 12 行

图存在 SQLite 的 thread_spawn_edges 表。child_thread_id 是主键，一个孩子不能挂两个父。同一孩子再 spawn 一次，父和状态都会被新值盖住。会话正文不进这张表。子 agent 的模型上下文仍走自己的 rollout。图只回答谁生了谁，这条边现在开还是关。

出处：codex-rs/state/migrations/0021_thread_spawn_edges.sql 第 1 至 8 行

非临时会话在线程建出来之后立刻 upsert 一条 Open 边。写入失败只打 warn。子 thread 已经在跑，图可以稍后补。补写用 ON CONFLICT DO NOTHING，不会把已经 Closed 的边改回去。

出处：codex-rs/core/src/agent/control.rs 第 767 至 780 行

列后代时，过滤条件作用在走过的每一条边上。Some(Open) 只沿着 Open 走。父边已经 Closed 的子树，就算孙边仍是 Open，也不会被列出来。

出处：codex-rs/agent-graph-store/src/store.rs 第 49 至 54 行

路径才是寻址键，外号是给人认的。根是 /root。相对名接到当前路径后面。.. 和 . 被拒绝，所以不能靠相对路径爬到兄弟。角色可以收能力，不能替换父会话的权威。内置活角色是 default、explorer、worker。explorer.toml 是空文件。

出处：codex-rs/core/src/agent/role.rs 第 1 至 4 行

重启之后必须能问：这个孩子还算活着吗。只记一次 spawn 事件回答不了。Open 才能进恢复列表。Closed 从子树遍历里消失。child_id 做主键，图保持树，遍历可以按深度 BFS。换个语言重写，最小形态仍是一张三列表：parent、child、status。

子 agent 转完了，要回一封 FINAL_ANSWER。如果这封信自带叫醒，父正在写用户看得见的最终答案时，会被子结果强行开一轮。用户看到半截话，再加一份突然插进来的完成通知。

通信种类有四个标签：Spawn、Message、Followup、Result。它们是 OTEL 用的标签。协议侧只有一份 InterAgentCommunication，靠 trigger_turn 区分要不要叫醒。

send_message 是 QueueOnly，只入队。followup_task 是 TriggerTurn，才叫醒。空消息直接拒。followup_task 不能打根节点。

出处：codex-rs/core/src/tools/handlers/multi_agents_v2/message_tool.rs 第 11 至 24 行

处理函数先入队，再决定要不要开工。trigger_turn 为假时，信继续躺着。只有它为真，或会话还有未完成的 durable sleep，才去开工。V2 的完成通知是 Result，trigger_turn 为假。父如果正在说话，这封信按信箱相位排队。

出处：codex-rs/core/src/session/handlers.rs 第 89 至 99 行

信箱是会话级队列。用户插话进 pending_input，子邮件进 mailbox_pending_mails，两条槽。兄弟之间只要用绝对路径，例如 /root/worker_b，就可以互发。相对名 worker_b 会接到自己后面，变成自己的孩子。

出处：codex-rs/core/src/session/input_queue.rs 第 76 至 80 行

叫醒权是稀缺的。谁能开一轮，谁就不能随便开。把投递和开工拆开，完成通知默认不叫醒，叫醒权留给 followup_task 和用户。换一套消息总线也用得上这根布尔：wake 还是只入队。

V2 驻留名额满了，会按 LRU 卸掉一个孩子。如果卸运行时顺便把边标成 Closed，这个孩子从 Open 子树消失。下次恢复找不到它。用户没关过它，系统自己把它除名了。

shutdown_live_agent 关掉活着的 agent，刷 rollout，发 Shutdown，从管理器摘掉 thread。边还是 Open。下次恢复仍会把它当活子树成员。

出处：codex-rs/core/src/agent/control/legacy.rs 第 6 至 8 行

close_agent 先把目标自己的入边标 Closed，再关机。后代的边不会在这里被标 Closed。父 turn 正常结束走 TurnComplete，不调用 close_agent。孩子继续跑，边保持 Open。

出处：codex-rs/core/src/agent/control/legacy.rs 第 48 至 58 行

V2 恢复分两步。先把 Open 后代的身份装回注册表，不重开运行时。真正有人 send_message 或 followup_task 时，才按 rollout 把 thread 挂回来。

出处：codex-rs/core/src/agent/control/spawn.rs 第 144 至 162 行

运行时活着和从图上除名是两件独立的事。驻留 LRU、进程重启、用户关窗口，都可能卸运行时。只有编排者明确 close，才写成 Closed。恢复时沿着 Open 边走。这条分账不依赖 Rust。

你刚从 Claude Code 把一份 hooks.json 搬过来。文件里有三条处理器：命令拦危险 shell，提示词让小模型审用户提交，agent 在 Stop 时再起一个子会话跑 linter。Claude 那边三条都能跑。

贴进 Codex，启动会话。命令那条亮了。后两条日志各写一句 not supported yet。协议枚举明明列着 Prompt 和 Agent，配置解析也认这两个 tag。装进运行表的只有命令和 MCP 工具。

内核对外有三张表，宽度不一样。

协议面列出十一个事件名，serde 走 snake_case。旁边四个处理器类型也在：Command、McpTool、Prompt、Agent。

出处：codex-rs/protocol/src/protocol.rs 第 1508 至 1531 行

配置面用 type 标签把这四个名字都接住。后两个是空结构体。解析能过，字段里没有可执行内容。

出处：codex-rs/config/src/hook_config.rs 第 183 至 187 行

发现阶段看见后两个就 continue，文案是 prompt hooks are not supported yet 和 agent hooks are not supported yet。引擎里真正可执行的种类只有命令和 MCP 工具。普通用户配置里，这两条只进 warning，会话继续。托管必选 hook 配了它们，启动会失败。

出处：codex-rs/hooks/src/engine/discovery.rs 第 626 至 645 行

JSON hook 的运行时类型名直接写成 ClaudeHooksEngine。兼容不是注释里的愿望，是类型名。stdin 喂 JSON，stdout 按 schema 解析。旁边还留着一条旧 notify 路，只在 turn 收工时 fire-and-forget 一条命令。两条路不要混。

出处：codex-rs/hooks/src/engine/mod.rs 第 107 至 119 行

配置面可以比执行器宽。先把生态里已有的四个 type 接住，未知 tag 才不会把整份 hooks.json 打爆。代价是搬家的人会按枚举名理解能力。所以发现阶段必须留下稳定文案，必选策略碰到未实现 type 必须拒绝启动。换个语言重写，最小形态仍是两张表加一个 skip。

有人写了一条 PreToolUse 脚本，超时设成 1 秒，脚本里 sleep 5 秒。他们以为 hook 崩溃等于拦截。工具照样执行。日志里这条 hook 的状态是 failed，文案带 timed out after 1s。

run_command 超时把 error 写成 hook timed out after {n}s，exit_code 是空的。解析看见 error 只标 Failed，should_block 保持默认 false。工具注册表于是继续 handle_any_tool。

出处：codex-rs/hooks/src/engine/command_runner.rs 第 317 至 326 行

会拦的路只有两条。JSON 里给出 deny 或 block。或者退出码 2 且 stderr 非空。退出码 2 却没有理由，算失败，不拦。异步 hook 即使返回 deny，也加不上控制效果。只有同步、可信、未超时的处理器能改下一步。

出处：codex-rs/hooks/src/events/pre_tool_use.rs 第 261 至 277 行

审批路径上的规则反过来。PermissionRequest 跑在 Guardian 和用户审批 UI 之前。它不改工具输入。折叠规则是：任一 deny 立刻赢，否则保留最后一次 allow。Allow 映射成一次性 Approved，不进会话缓存。下次同样的命令还要再问。

出处：codex-rs/core/src/tools/approvals.rs 第 454 至 474 行

Claude 的 PermissionRequest 输出里有 updatedInput。Codex 把这个字段标成 reserved，看见就 fail closed。从 Claude 原样搬一条带改写的审批 hook，在这里会失败，不会改写。

一条挂掉的 linter hook 不该让所有工具停摆。可用性放在拦截可靠性前面。想改流程，必须同步、必须有明确决策。想发通知，可以异步、最多 8 个并行。审批路径对歧义输出 fail closed，因为那一层不能把看不懂的字段当成允许。

PostToolUse 想拦一次危险写入，文件已经落盘。SessionEnd 想往上下文里塞收尾说明，stdout 被丢掉。wire 枚举里也没有这个事件名。两处翻车的共同点是：挂钩点已经走过它能改的那一段。

十一个挂钩点按生命周期排开。主轴是 SessionStart → UserPromptSubmit → PreToolUse → PermissionRequest → 工具 → PostToolUse → PreCompact → PostCompact → Stop → SessionEnd。子 agent 另走一条细轴，SubagentStart 和 SubagentStop 只在 ThreadSpawn 上响。

每个点的合同不一样。

PreToolUse 能拦工具、能改输入。失败默认放行。PostToolUse 只在工具成功之后跑，block 拒绝的是结果，副作用已经发生。Stop 的 block 带着 continuation prompt，才在轮次层 continue，不重发 TurnStarted。没有 prompt 的 block 被忽略。should_stop 才把控制权交回任务壳。stop 优先于 block。

出处：codex-rs/core/src/session/turn.rs 第 509 至 538 行

UserPromptSubmit 的 block 写成 should_stop，停的是当前这条用户消息，不会拿 stderr 当下一轮 prompt。matcher 在这里被忽略。SessionStart 尊重 continue: false。SubagentStart 只做上下文注入，同样的字段被丢掉。

SessionEnd 是拆卸期通知。超时默认 1 秒，上限 3 秒，给 app-server 的五秒 shutdown 留余量。退出码 0 就是完成，stdout 整段丢掉。MCP 形态直接 skip。reason 目前写死 other。

出处：codex-rs/hooks/src/events/session_end.rs 第 20 至 24 行

hook 文本进模型之前先变成 developer 角色的片段。默认预算 2500 个近似 token。超限时全文写到临时目录，模型看见头尾预览加一行路径。写盘失败就只截断。

出处：codex-rs/hooks/src/output_spill.rs 第 53 至 91 行

挂钩点的能力跟它在生命周期的位置绑定。工具还没跑，才能改输入或跳过。工具跑完，只能改模型看见的那一截。拆卸期只有几秒，读 JSON、回灌上下文、再等 MCP，都会把关机拖过上限。于是它变成纯通知。换一套运行时，该问的仍是：这个点还来不来得及改已经发生的事。

你把 codex mcp-server 写进 Cursor 的 MCP 配置。Cursor 当 client，Codex 当 server。若这一次 tools/list 把内部 GitHub 工具一并交出去，IDE 调一次就摸到内部能力。权限边界从「调一次 Codex」扩成「直接调内部工具」。

crate 拆成两套。mcp-server 从 stdin 读行，一行一条 JSON。initialize 只打开 tools。tools/list 写死两个名字：codex 和 codex-reply。codex 会 start_thread，nested thread 再起自己的 McpRuntime。codex-mcp 管连接集，外部 server 的工具另做一份目录。

出处：codex-rs/mcp-server/src/lib.rs 第 131 至 152 行；codex-rs/mcp-server/src/codex_tool_runner.rs 第 66 至 90 行；codex-rs/codex-mcp/src/runtime.rs 第 88 至 98 行

同一份 JSON-RPC 线协议，处理器不是同一个。早期资料常把它们画成同一个 runtime 的两张脸。当前源码里它们甚至不共享 MessageProcessor。

出处：codex-rs/mcp-server/src/message_processor.rs 第 274 至 277 行；codex-rs/mcp-server/src/message_processor.rs 第 336 至 348 行

对外承诺和对内能力分开，是网关的通用形状。换语言也是两个函数：hosted 返回 run / continue，external 返回 mcp__*。IDE 只看见入口，会话里才看见外部店。

两家店都报 search，前缀还能分开。一家叫 basic-server，一家叫 basic_server，连字符洗成下划线之后，命名空间会撞。模型看见两个同名工具，下一次调用就不知道进哪家店。API 还有字节上限。

server 接进来，先把各家 tools/list 汇成一张表，再走 normalize_tools_for_model_with_prefix。顺序是固定的四步。

1. 给命名空间加上 mcp__ 前缀。

2. 非法字符洗成下划线，只留字母、数字和 _。

3. 完全相同的原始身份丢掉一份。清洗后命名空间或工具名还撞，就在末尾加 12 位 SHA-1。

4. 合起来超过 128 字节，截断再哈希。原始 server_name 和 tool.name 留在 ToolInfo 上，协议调用走原名。

出处：codex-rs/codex-mcp/src/tools.rs 第 105 至 117 行；codex-rs/codex-mcp/src/tools.rs 第 134 至 137 行；codex-rs/codex-mcp/src/tools.rs 第 166 至 194 行；codex-rs/codex-mcp/src/tools.rs 第 226 至 227 行；codex-rs/codex-mcp/src/mcp/mod.rs 第 477 至 485 行

给模型看的名字和协议上的名字本来就是两层。一层给人读、给 API 用，一层用来寻址。哈希消歧是撞名问题的通用答法。上限数字会变，这层翻译不会变。

若按 MCP 存活过滤目录，冷启动那几秒模型会以为 skill 不存在，下一轮又突然出现。说明书整份灌进每一轮，上下文也会被吃光。

点名记号是 $。目录只看 enabled 和 prompt_visible。用户点了名，或者任务和描述对得上，这一轮才读 SKILL.md 正文。Guardian 评审会话直接返回空注入，父 transcript 里的 $skill 不能再触发新说明书。

出处：codex-rs/skills/src/mentions.rs 第 41 行；codex-rs/ext/skills/src/catalog.rs 第 261 至 263 行；codex-rs/core/src/session/turn.rs 第 766 至 770 行；codex-rs/core/src/session/turn.rs 第 808 至 817 行

缺 MCP 时另问人。first-party 且功能开关开，才弹出 Install MCP servers。审批是 Never 就静默跳过。用户选 Continue anyway，目录还在，对应工具可能仍不可用。

出处：codex-rs/core/src/mcp_skill_dependencies.rs 第 47 至 60 行；codex-rs/core/src/mcp_skill_dependencies.rs 第 268 至 270 行

发现和就绪是两件事。索引先给，全文按需再给，缺依赖问人，不要把条目从目录里抹掉。装不装是配置变更，列不列是发现。

有人告诉你会自动从 Claude Code 搬家。你以为是把整个配置目录拷过来。第二天 hook 少了一条，MCP 少了一台，memory 没出现在清单里。少掉的 hook 用了 type: prompt。少掉的 MCP 命令里写了 ${API_KEY}。

再换一个同事。他用的是 Cursor。Codex 能看见他的 skill 和 hook，看不见他的 memory。仓库里的 Cursor 插件配置会被直接丢掉。

搬家 crate 只负责把外部配置读进来。插件怎么跑，在旁边的 core-plugins。源在类型上只有两个变体：Cla 是 Claude Code，Cur 是 Cursor。字符串对不上 cursor，就落到 Claude Code。调用方漏传源，检测会去翻 ~/.claude。

出处：codex-rs/external-agent-migration/src/migration_source.rs 第 51 至 67 行

一次检测最多产出十种条目。每种后面的导入必须给一个去处。字段先过白名单。Codex 认 11 个 hook 事件，Claude Code 发出 27 个。名字对不上的组，整组消失。单条 hook 的 type 默认当 command，对不上就跳过。MCP 的 command 或 url 里出现 ${，整台不要。市场来源只收 github、git、本地目录。file、url、npm、settings 直接丢掉。

出处：codex-rs/external-agent-migration/src/model.rs 第 53 至 64 行 · codex-rs/hooks/src/lib.rs 第 23 至 35 行 · restored-src/src/entrypoints/sdk/coreSchemas.ts 第 355 至 383 行 · codex-rs/external-agent-migration/src/hooks_cla.rs 第 131 至 137 行 · codex-rs/external-agent-migration/src/mcp.rs 第 204 至 210 行 · codex-rs/external-agent-migration/src/source_cla.rs 第 270 至 274 行

然后说明文件要改名。CLAUDE.md 变成 AGENTS.md。产品名按词边界改成 Codex。Cursor 只用大小写敏感的 Cursor，避免把普通英文 cursor 一起改掉。

出处：codex-rs/external-agent-migration/src/rewrite.rs 第 38 至 49 行

导入器的通用形状是白名单加三条出口。对不上的字段丢掉，不要改写成近似物。prompt hook 不会被塞进 command。带占位符的 MCP 不会被瞎展开。换个语言重写，这份表还用得上。

Claude Code 允许仓库 settings 带着启用插件名单，同事克隆之后自动有同一批插件。对 Codex 来说，仓库里的启用名单不能当安装权威。装上去会进用户配置。不可信仓库想在你机器上装可执行内容，这条路要先切断。

检测只在 home 扫插件。注释写死了：仓库控制的 settings 不能当安装权威。Cursor 只要看见仓库根，插件检测直接返回空。导入看见非空工作目录，报 repository-scoped plugin migration is not allowed。

出处：codex-rs/external-agent-migration/src/detect/mod.rs 第 330 至 332 行 · codex-rs/external-agent-migration/src/migration_source.rs 第 116 至 125 行 · codex-rs/external-agent-migration/src/plugins.rs 第 26 至 36 行

本地插件当场装。远程市场推进待装队列。会话也是两截：检测清单里可以有，同步 import() 对 Sessions 直接返回成功，什么都不写。真正写成 Codex thread 的，是 app-server 里的后台任务。调用方先拿到 import_id。

出处：codex-rs/external-agent-migration/src/service.rs 第 437 行 · codex-rs/app-server/src/external_agent_migration/session_importer.rs 第 100 至 111 行

Codex 认市场清单时，按固定相对路径找第一个存在的文件。四条路径里两条是自己的，两条是竞品的。同一套查找同时服务「用户主动加市场」和「从竞品搬市场」。

出处：codex-rs/core-plugins/src/marketplace.rs 第 20 至 25 行

可执行内容的安装权威必须落在用户级。面向任意 git clone 的产品，home-only 更稳。同步先回执、慢活进后台，是长任务接口的通用形状。

换产品最怕把已经改过的新配置盖掉。目标 hooks.json 里已经有内容，整文件替换会把用户手写的 hook 冲掉。

目标 hook 文件非空，整项取消。已有 config.toml 只补缺失键。MCP 同名 server 保留旧的。第一次搬家像填空。第二次再点迁移，多数条目会因为已经有了而不出现。

出处：codex-rs/external-agent-migration/src/hooks_common.rs 第 13 至 19 行

memory 另有一道门。特性开关默认关，阶段是 UnderDevelopment。检测函数不看这个开关，导入前处理器会查。关着就回 external agent memory import is disabled。导入按字节拷贝，不脱敏。

出处：codex-rs/features/src/lib.rs 第 998 至 1003 行 · codex-rs/app-server/src/external_agent_migration/processor.rs 第 180 至 185 行

导入是填空。用户已经写过的文件，搬家碰不得。memory 默认关，是因为另一家 agent 的项目记忆会按明文进盘。

你给侧栏等 type 等于 turn_started。联调那天字段对得上，type 却写成 task_started。你改成新名，旧夹具里的旧名还能解出来。

然后你加了一个自己的事件。本地和内核一起编，过了。隔壁旧版 MCP 客户端解不出来。再过一周，新版写下的 rollout（会话落盘文件）拿到旧版里 resume。那一行被跳过，parse_errors 加一，会话还能开，少了一段生命周期。

命令里带着 oneshot 回调、审批决定，甚至 realtime 音频帧。事件要进 rollout，要被 MCP 写成 JSON，要被旧客户端按 type 分发。方向、寿命、能不能过网，叠在同一种「消息」上会互相拖累。

模块头只用四行，把说话方式写死：一次会话里，客户端和 agent 用 SQ / EQ 异步通信。

//! Defines the protocol for a Codex session between a client and an agent.
//!
//! Uses a SQ (Submission Queue) / EQ (Event Queue) pattern to asynchronously communicate
//! between user and agent.

下行条目是 Submission。它有关联用的 id，有要执行的 Op（内核动词，当前 28 个），只派生 Debug，没有 serde。上行条目是 Event。它有 serde。id 对上当初那条提交，msg 才是事件本体。

出处：codex-rs/protocol/src/protocol.rs 第 185 至 200 行；codex-rs/protocol/src/protocol.rs 第 1276 至 1283 行

会话启动时同时建两条通道。下行 bounded，容量 512。上行 unbounded。客户端连打 512 条还没被 loop 收走，下一次 send 会等。事件可以堆积，占内存，不反压这一轮。

出处：codex-rs/core/src/session/mod.rs 第 460 至 461 行；codex-rs/core/src/session/mod.rs 第 533 至 534 行

TurnInput 的路由结果走 oneshot，不走 Event Queue。EventMsg 描述这一轮发生了什么。oneshot 只回答「这条提交有没有被接住」。

出处：codex-rs/core/src/session/handlers.rs 第 515 至 526 行

命令是人发的，频率低，堵住可以反压。事件是模型和工具喷出来的，堵住会把这一轮卡住。换语言重写，只要命令带回调、事件要落盘，这两条队列还是得分开。

Rust 变体已经改名叫 TurnStarted。若 JSON 上的字符串跟着改，旧 rollout 和旧客户端会在反序列化边界上断。按标识符名猜 wire 名，会猜错。

serde 写出 task_started，读入时也认 turn_started。Display 和指标走 turn_started。同一变体两套字符串：磁盘保住旧名，代码用新名。

出处：codex-rs/protocol/src/protocol.rs 第 1337 至 1340 行

item 生命周期还会再喷一份旧名字。新前端看 ItemStarted，旧前端看 ExecCommandBegin 或 AgentMessage。队列上会出现重复语义。这是迁移动线，给还没迁到 TurnItem 的消费者留的。

出处：codex-rs/core/src/session/mod.rs 第 1965 至 1973 行；codex-rs/protocol/src/legacy_events.rs 第 65 至 69 行

标识符可以改，已经落盘的字符串改不起。rename 加 alias 是给磁盘留后门的通用做法。指标用哪一套，要单独测，不要假设和 serde 相同。

EventMsg 是内部事件词表，81 个变体，没有 #[serde(other)]，也没标 non_exhaustive。加一个新 type，旧读取器怎么办，不能靠「看情况」。

三条路径，答案都写在代码里。