@agent-compose/sdk 0.8.5 → 0.8.6

package/src/runtimes/claude-code.ts

@@ -35,11 +35,13 @@
  */
 
 import type {
-  AgentMessage, AgentMessageCompaction, AgentMessageTaskNotification, AgentMessageTaskProgress,
+  AgentMessage, AgentMessageCompaction, AgentMessageModelUsage, AgentMessagePlanLimits,
+  AgentMessageTaskNotification, AgentMessageTaskProgress, AgentMessageUsage,
   WorkflowProgressEntry,
 } from "../index.js";
 import { createCliAgentRuntime, shellQuote, type CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
 import { formatError } from "../utils/errors.js";
+import { CLAUDE_CODE_VERSION } from "../sandbox/baked-clis.js";
 
 function now(): string { return new Date().toISOString(); }
 
@@ -409,6 +411,106 @@ export function parseSystemCompaction(
   };
 }
 
+// ── Plan limits (the account meter, off the stream) ─────────────────────────
+//
+// A subscription-funded `claude -p` reads the `anthropic-ratelimit-unified-*`
+// headers off every response and re-emits them as `rate_limit_event` lines
+// whenever its reading changes (the public Agent SDK's SDKRateLimitEvent;
+// anthropics/claude-code#50518 shows the plainly-allowed shape:
+// `{status: "allowed", resetsAt: 1729281600, rateLimitType: "five_hour"}`,
+// with `utilization` carried only once a window crosses a warning
+// threshold). `resetsAt` is epoch SECONDS. A `rejected` event is the plan's
+// wall for the request just made, with the authoritative reset. The platform
+// folds these into the funding account's meter (one reading per window) and
+// learns a cooldown from a rejected one — never from the notice text.
+
+const PLAN_LIMIT_STATUSES: ReadonlySet<string> = new Set(["allowed", "allowed_warning", "rejected"]);
+
+/** Epoch seconds (the CLI's `resetsAt`) as ISO; undefined for anything else. */
+function epochSecondsIso(v: unknown): string | undefined {
+  if (typeof v !== "number" || !Number.isFinite(v) || v <= 0) return undefined;
+  return new Date(v * 1000).toISOString();
+}
+
+/** One `rate_limit_event` mapped onto the structured plan-limits message,
+ *  or null when the event names no recognisable status. Pure and tolerant
+ *  over untrusted harness JSON: every field is forwarded only when present
+ *  and well-typed; nothing is defaulted or invented. Exported for tests. */
+export function parsePlanLimits(
+  p: Record<string, unknown>, timestamp: string,
+): AgentMessagePlanLimits | null {
+  const info = (typeof p.rate_limit_info === "object" && p.rate_limit_info !== null
+    ? p.rate_limit_info : null) as Record<string, unknown> | null;
+  if (!info || typeof info.status !== "string" || !PLAN_LIMIT_STATUSES.has(info.status)) return null;
+  const num = (v: unknown): number | undefined =>
+    typeof v === "number" && Number.isFinite(v) ? v : undefined;
+  const str = (v: unknown): string | undefined =>
+    typeof v === "string" && v.length > 0 ? clip(v, 100) : undefined;
+  const window = str(info.rateLimitType);
+  const resetsAt = epochSecondsIso(info.resetsAt);
+  const utilization = num(info.utilization);
+  const surpassedThreshold = num(info.surpassedThreshold);
+  const overageStatus = typeof info.overageStatus === "string" && PLAN_LIMIT_STATUSES.has(info.overageStatus)
+    ? info.overageStatus as AgentMessagePlanLimits["status"] : undefined;
+  const overageResetsAt = epochSecondsIso(info.overageResetsAt);
+  const overageDisabledReason = str(info.overageDisabledReason);
+  const overageInUse = typeof info.isUsingOverage === "boolean" ? info.isUsingOverage
+    : typeof info.overageInUse === "boolean" ? info.overageInUse : undefined;
+  const overage = overageStatus !== undefined || overageResetsAt !== undefined
+    || overageDisabledReason !== undefined || overageInUse !== undefined
+    ? {
+        ...(overageStatus !== undefined ? { status: overageStatus } : {}),
+        ...(overageResetsAt !== undefined ? { resetsAt: overageResetsAt } : {}),
+        ...(overageDisabledReason !== undefined ? { disabledReason: overageDisabledReason } : {}),
+        ...(overageInUse !== undefined ? { inUse: overageInUse } : {}),
+      }
+    : undefined;
+  const limitScope = str(info.limitScope);
+  const errorCode = str(info.errorCode);
+  return {
+    type: "plan_limits",
+    status: info.status as AgentMessagePlanLimits["status"],
+    ...(window !== undefined ? { window } : {}),
+    ...(resetsAt !== undefined ? { resetsAt } : {}),
+    ...(utilization !== undefined ? { utilization } : {}),
+    ...(surpassedThreshold !== undefined ? { surpassedThreshold } : {}),
+    ...(overage !== undefined ? { overage } : {}),
+    ...(limitScope !== undefined ? { limitScope } : {}),
+    ...(errorCode !== undefined ? { errorCode } : {}),
+    timestamp,
+  };
+}
+
+/** The terminal result's per-model report (`result.modelUsage`, keyed by
+ *  the raw model string) mapped onto the protocol's per-model shape, or
+ *  undefined when the result carries none. Counts the harness did not
+ *  report stay absent (the four classes default to 0 only when the entry
+ *  exists at all — an entry IS a report of that model). Pure; exported for
+ *  tests. */
+export function parseModelUsage(raw: unknown): Record<string, AgentMessageModelUsage> | undefined {
+  if (typeof raw !== "object" || raw === null) return undefined;
+  const num = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+  const opt = (v: unknown): number | undefined => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+  const out: Record<string, AgentMessageModelUsage> = {};
+  for (const [model, entry] of Object.entries(raw as Record<string, unknown>)) {
+    if (typeof entry !== "object" || entry === null || model.length === 0) continue;
+    const e = entry as Record<string, unknown>;
+    const thinkingTokens = opt(e.thinkingTokens);
+    const webSearchRequests = opt(e.webSearchRequests);
+    const costUsd = opt(e.costUSD);
+    out[clip(model, 200)] = {
+      inputTokens: num(e.inputTokens),
+      outputTokens: num(e.outputTokens),
+      cacheReadTokens: num(e.cacheReadInputTokens),
+      cacheCreationTokens: num(e.cacheCreationInputTokens),
+      ...(thinkingTokens !== undefined ? { thinkingTokens } : {}),
+      ...(webSearchRequests !== undefined ? { webSearchRequests } : {}),
+      ...(costUsd !== undefined ? { costUsd } : {}),
+    };
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
 /** Claude Code's real reasoning knob is its own `--effort <level>` flag
  *  (low|medium|high|xhigh|max — verified against `claude -p --help`). The
  *  CliReasoningEffort union IS the CLI's vocabulary, so the level rides the
@@ -419,6 +521,50 @@ export function parseSystemCompaction(
 export const CLAUDE_CODE_EFFORT_LEVELS: readonly CliReasoningEffort[] =
   ["low", "medium", "high", "xhigh", "max"];
 
+/** The Bash PreToolUse hook rtk installs for Claude Code (`rtk init -g
+ *  --hook-only` writes exactly this entry — matcher `Bash`, command
+ *  `rtk hook claude` — into ~/.claude/settings.json; the image bakes
+ *  RTK_VERSION, sandbox/baked-clis.ts, which this payload was run against).
+ *  `rtk hook claude` reads the PreToolUse JSON on stdin and, when it has a
+ *  filter for the command, answers with `updatedInput` rewriting `git
+ *  status` to `rtk git status` (ls, find, grep, test runners, bun, curl,
+ *  docker, …), so the model reads rtk's compact output. A command it
+ *  cannot compress — an unknown tool, a pipe into one, command or process
+ *  substitution, a heredoc, a file redirect, anything already prefixed
+ *  `rtk`, or a `RTK_DISABLED=1` prefix — gets no output and exit 0, which
+ *  Claude Code treats as "no decision": the original command runs
+ *  unchanged (all verified against the binary).
+ *
+ *  The wrapper fails OPEN both ways. `command -v` covers images without
+ *  rtk (the devbox, a bare Vercel VM): there a bare `rtk hook claude` would
+ *  fail every Bash call's hook with exit 127 — non-blocking, but a stderr
+ *  warning per call; rtk's own legacy shell hook degraded the same way
+ *  ("binary not found: exit 0"). The trailing `exit 0` covers an rtk that
+ *  cannot answer: Claude Code treats a PreToolUse hook's exit 2 as a BLOCK
+ *  of the tool call with stderr fed to the model, and clap exits 2 with
+ *  its usage for a subcommand it does not know — which is how the codex
+ *  hook (RTK_CODEX_HOOK_COMMAND, codex.ts) blocked every codex shell
+ *  command on 2026-10-03, when the image's rtk was a cache-served 0.45.0.
+ *  rtk's hooks never exit non-zero on purpose, so a non-zero exit is a
+ *  broken rtk, and the compressor must never cost the worker its shell:
+ *  the exit code is dropped, and the smoke gate's rtk-hook-rewrite check
+ *  is what proves the rewrite itself. */
+export const RTK_BASH_HOOK_COMMAND =
+  "command -v rtk >/dev/null 2>&1 && rtk hook claude; exit 0";
+
+/** Settings every platform `claude` launch passes as `--settings` (inline
+ *  JSON). Claude Code MERGES hook entries across its settings sources
+ *  instead of replacing them (user → project → local → flag → managed), so
+ *  this rides beside whatever the machine's own ~/.claude/settings.json
+ *  carries, and nothing is written to that file — the right outcome, since
+ *  the server never owns it: home carry tar-restores it whole across
+ *  machines and the image capture strips it as personal state. */
+export const CLAUDE_CODE_PLATFORM_SETTINGS = {
+  hooks: {
+    PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: RTK_BASH_HOOK_COMMAND }] }],
+  },
+} as const;
+
 export const claudeCodeSpec: CliAgentSpec = {
   kind: "claude-code",
   authEnv: "ANTHROPIC_API_KEY",
@@ -428,11 +574,14 @@ export const claudeCodeSpec: CliAgentSpec = {
   acp: { command: "npx", args: ["--yes", CLAUDE_CODE_ACP_ADAPTER] },
   // Bare-sandbox fallback only: the agent-env image bakes /usr/local/bin/claude
   // (same recipe — infra/e2b-template/build.ts), so the probe short-circuits
-  // on the platform path. Anthropic's installer drops a versioned binary under
-  // $HOME with a ~/.local/bin/claude launcher; resolve the symlink and copy
-  // the self-contained binary to a world-executable system path.
+  // on the platform path. The SAME pinned version as the image
+  // (CLAUDE_CODE_VERSION), never latest, so a machine the image predates runs
+  // what the image's machines run. Anthropic's installer drops a versioned
+  // binary under $HOME with a ~/.local/bin/claude launcher; resolve the
+  // symlink and copy the self-contained binary to a world-executable system
+  // path.
   install:
-    'curl -fsSL https://claude.ai/install.sh | bash && ' +
+    `curl -fsSL https://claude.ai/install.sh | bash -s ${CLAUDE_CODE_VERSION} && ` +
     'REAL=$(readlink -f "$HOME/.local/bin/claude") && test -f "$REAL" && ' +
     'sudo cp "$REAL" /usr/local/bin/claude && sudo chmod 0755 /usr/local/bin/claude',
   // Claude reads the prompt from stdin in -p mode.
@@ -447,7 +596,8 @@ export const claudeCodeSpec: CliAgentSpec = {
   // the same build). A message that lands after the result would start a
   // NEW turn in-process, which is why the transport's feeder stops at the
   // result line instead of forwarding past it.
-  streamInput: {
+  midTurnInput: {
+    transport: "stdin-stream",
     promptLine: (prompt) => JSON.stringify({ type: "user", message: { role: "user", content: prompt } }),
     messageLine: (text) => JSON.stringify({ type: "user", message: { role: "user", content: text } }),
     // The ESC equivalent (verified live against claude 2.1.236): the CLI's
@@ -479,6 +629,10 @@ export const claudeCodeSpec: CliAgentSpec = {
       // claude's own attestation env for exactly this: it lifts the flag's
       // root-user refusal (the E2B agent-env user is root).
       "--dangerously-skip-permissions",
+      // rtk's Bash PreToolUse hook (RTK_BASH_HOOK_COMMAND): shell output is
+      // compressed before it reaches the model. Flag settings merge with the
+      // machine's own settings; they never replace them.
+      `--settings ${shellQuote(JSON.stringify(CLAUDE_CODE_PLATFORM_SETTINGS))}`,
       ...(model ? [`--model ${shellQuote(model)}`] : []),
       // Reasoning effort is the CLI's own flag; the value comes from the
       // closed CliReasoningEffort set, so it is shell-safe unquoted.
@@ -614,14 +768,21 @@ export const claudeCodeSpec: CliAgentSpec = {
         return [];
       }
       // Terminal result: usage on success (the text already streamed via the
-      // assistant events); an honest string error on failure.
+      // assistant events); an honest string error on failure. The turn
+      // totals are the main loop's `usage`; `modelUsage` (every model the
+      // query pipeline called, with the CLI's own cost estimate) and
+      // `total_cost_usd` ride beside them as the harness reported them —
+      // cumulative for the guest session (AgentMessageUsage.byModel).
       case "result": {
         if (p.is_error === true) {
           return [{ type: "error", text: formatError(p.result ?? p.subtype ?? p), timestamp: ts }];
         }
         const u = p.usage as Record<string, number> | undefined;
         if (!u) return [];
-        return [{
+        const byModel = parseModelUsage(p.modelUsage);
+        const costUsd = typeof p.total_cost_usd === "number" && Number.isFinite(p.total_cost_usd)
+          ? p.total_cost_usd : undefined;
+        const usage: AgentMessageUsage = {
           type: "usage",
           inputTokens: u.input_tokens ?? 0,
           outputTokens: u.output_tokens ?? 0,
@@ -629,8 +790,17 @@ export const claudeCodeSpec: CliAgentSpec = {
           cacheCreationTokens: u.cache_creation_input_tokens ?? 0,
           durationMs: typeof p.duration_ms === "number" ? p.duration_ms : 0,
           numTurns: typeof p.num_turns === "number" ? p.num_turns : 1,
+          ...(byModel !== undefined ? { byModel } : {}),
+          ...(costUsd !== undefined ? { costUsd } : {}),
           timestamp: ts,
-        }];
+        };
+        return [usage];
+      }
+      // The account's plan limits as the CLI read them off the response
+      // headers (subscription-funded sessions; parsePlanLimits above).
+      case "rate_limit_event": {
+        const limits = parsePlanLimits(p, ts);
+        return limits ? [limits] : [];
       }
       // System events: init carries the session id (extractSessionId), and
       // the background-task lane rides here too — `task_notification` is

package/src/runtimes/claude.ts

@@ -1,4 +1,4 @@
-/** Claude Agent SDK runtime — replaces the old Claude CLI subprocess runtime. */
+/** Claude Agent SDK runtime. */
 
 import { query, type HookCallback, type PreToolUseHookInput, type SDKUserMessage, type ThinkingConfig } from "@anthropic-ai/claude-agent-sdk";
 import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvider, ToolCallGateResult } from "../index.js";

package/src/runtimes/codex.ts

@@ -5,17 +5,28 @@
  * only stream-parse what it prints.
  *
  * Auth: set `OPENAI_API_KEY` (or `CODEX_API_KEY`) in the sandbox env via a
- * workflow secret. The runtime installs the `codex` CLI (`@openai/codex`) on
- * demand — no image baking needed; pair with `snapshots: { bootFrom: "reuse" }`
- * to install once and boot from the captured snapshot on every run after.
+ * workflow secret. The E2B session image bakes the pinned `codex` CLI
+ * (`@openai/codex@CODEX_CLI_VERSION`); on any other machine the runtime
+ * installs that same version on demand (pair with
+ * `snapshots: { bootFrom: "reuse" }` to install once and boot from the
+ * captured snapshot on every run after).
  *
  * Verified against codex-cli 0.124.0: `codex exec --json` + resume-by-thread,
- * with the command_execution / reasoning / agent_message item shapes below.
+ * with the command_execution / reasoning / agent_message item shapes below;
+ * the plan's `todo_list` item against codex-rs rust-v0.153.4 and
+ * rust-v0.159.2 (see codexPlanMessages); the command_execution /
+ * agent_message / turn.completed shapes re-verified live against 0.160.0
+ * (the pin), whose plan-tool sources are byte-identical to rust-v0.159.2.
  */
 
 import type { AgentMessage } from "../index.js";
-import { createCliAgentRuntime, shellQuote, type CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
+import type { AgentMessagePlan } from "../types/protocol.js";
+import {
+  MID_TURN_DELIVERED_ENV, MID_TURN_INBOX_ENV, createCliAgentRuntime, shellQuote,
+  type CliAgentSpec, type CliReasoningEffort,
+} from "./_cli-agent.js";
 import { formatError } from "../utils/errors.js";
+import { CODEX_CLI_VERSION } from "../sandbox/baked-clis.js";
 
 function now(): string { return new Date().toISOString(); }
 
@@ -24,6 +35,97 @@ function now(): string { return new Date().toISOString(); }
  *  overrides the bundled `@openai/codex` the adapter drives underneath. */
 const CODEX_ACP_ADAPTER = "@agentclientprotocol/codex-acp@0.1.0";
 
+/** The Bash PreToolUse hook rtk installs for Codex (`rtk init -g --codex`
+ *  writes exactly this entry — matcher `Bash`, command `rtk hook codex` —
+ *  into $CODEX_HOME/hooks.json). `rtk hook codex` exists since rtk 0.50.0;
+ *  the image bakes RTK_VERSION (sandbox/baked-clis.ts), which this payload
+ *  was run against. Codex's shell tool matches the `Bash` matcher (codex-rs
+ *  rust-v0.160.0, the pinned CODEX_CLI_VERSION; identical at
+ *  rust-v0.159.2), and the hook runs under `$SHELL -lc` with the PreToolUse
+ *  JSON on stdin. `rtk hook codex` answers `permissionDecision: "allow"` +
+ *  `updatedInput` rewriting `git status` to `rtk git status` when it has a
+ *  filter for the command; Codex applies the replacement before its own
+ *  approval and sandbox checks. For a command it cannot compress (an
+ *  unknown tool, a pipe into one, substitutions, heredocs, redirects, a
+ *  `RTK_DISABLED=1` prefix, an unknown permission mode) it prints nothing
+ *  and exits 0, and Codex runs the original unchanged.
+ *
+ *  The wrapper fails OPEN both ways, like RTK_BASH_HOOK_COMMAND
+ *  (claude-code.ts). `command -v` covers an image without rtk (the devbox,
+ *  a bare Vercel VM): silent, exit 0, so Codex runs the command instead of
+ *  failing every shell call's hook with 127. The trailing `exit 0` covers
+ *  an rtk that cannot answer: Codex treats a PreToolUse hook's exit 2 with
+ *  stderr as a BLOCK of the tool call (codex-rs hooks/src/events/
+ *  pre_tool_use.rs at rust-v0.160.0 — the model reads "Command blocked by
+ *  PreToolUse hook: <stderr>"), and clap exits 2 with its usage on stderr
+ *  for a subcommand it does not know. That was 2026-10-03: the image's rtk
+ *  was a cache-served 0.45.0 with no `hook codex`, and this hook — `exec`
+ *  handing rtk's exit code to Codex — blocked every shell command of every
+ *  codex session. rtk's hooks never exit non-zero on purpose (they fail
+ *  open with no stdout), so a non-zero exit is always a broken rtk, and the
+ *  compressor must never cost the worker its shell: the exit code is
+ *  dropped, and the smoke gate's codex-rtk-hook-rewrite check is what
+ *  proves the rewrite itself. */
+export const RTK_CODEX_HOOK_COMMAND =
+  "command -v rtk >/dev/null 2>&1 && rtk hook codex; exit 0";
+
+/** The awk program of the mid-turn hook below: the inbox lines not yet fed
+ *  (JSON string literals, one per line — `codexSpec.midTurnInput.messageLine`)
+ *  become ONE PostToolUse hook output. Each literal's quotes are stripped and
+ *  the bodies are joined with an escaped blank line; the bodies are already
+ *  JSON-escaped, so the result is one valid JSON string. Nothing is printed
+ *  when no line is due, and codex ignores an empty stdout. */
+const CODEX_MID_TURN_HOOK_AWK = String.raw`NR > fed && NR <= upto { s = substr($0, 2, length($0) - 2); out = (out == "" ? s : out "\\n\\n" s) } END { if (out != "") printf "{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUse\",\"additionalContext\":\"%s\"}}\n", out }`;
+
+/** The PostToolUse command hook that carries a mid-turn message into a
+ *  RUNNING codex turn (the 2026-10-02 relayed-steer incident: three of the
+ *  owner's instructions waited 48-51 minutes for a codex build to end).
+ *  Codex runs it, under `$SHELL -lc` with the event JSON on stdin and the
+ *  codex process's own environment, after every tool call it completes
+ *  (codex-rs core/src/tools/registry.rs → hook_runtime.rs at rust-v0.160.0,
+ *  the pin). The launch wrapper exported the turn's inbox and delivered-
+ *  counter paths into that environment (sdk _cli-agent.ts
+ *  toolHookInboxFragment); the hook forwards the inbox lines past the
+ *  counter as the hook's `additionalContext`, which codex records as
+ *  developer context in the live turn's history before the model's next
+ *  request (hook_runtime.rs record_additional_contexts), then advances the
+ *  counter — the same ack the server's inject lane trusts for the stdin
+ *  lane. Not a platform turn (no inbox in the environment): silent, exit 0.
+ *  Codex's default spill threshold for a hook's additional context is 2,500
+ *  tokens (hooks/src/output_spill.rs); a longer message reaches the model
+ *  as a preview plus a file pointer, which a steer never is. */
+export const CODEX_MID_TURN_HOOK_COMMAND =
+  // Drain the event JSON first, so codex's stdin write never meets a closed pipe.
+  "cat >/dev/null; "
+  + `[ -n "\${${MID_TURN_INBOX_ENV}:-}" ] && [ -f "$${MID_TURN_INBOX_ENV}" ] || exit 0; `
+  + `ac_fed=$(cat "$${MID_TURN_DELIVERED_ENV}" 2>/dev/null); ac_fed=\${ac_fed:-0}; `
+  + `ac_lines=$(wc -l < "$${MID_TURN_INBOX_ENV}" 2>/dev/null); ac_lines=\${ac_lines:-0}; `
+  + `[ "$ac_lines" -gt "$ac_fed" ] || exit 0; `
+  + `awk -v fed="$ac_fed" -v upto="$ac_lines" '${CODEX_MID_TURN_HOOK_AWK}' "$${MID_TURN_INBOX_ENV}" `
+  + `&& echo "$ac_lines" > "$${MID_TURN_DELIVERED_ENV}"; exit 0`;
+
+/** $CODEX_HOME/hooks.json for every platform Codex session (the server
+ *  writes it at boot, session-runtime-config.ts). Codex only RUNS a
+ *  user-level hook it has persisted trust for — the TUI's review prompt
+ *  has no headless counterpart, and `--dangerously-bypass-hook-trust` would
+ *  run a cloned repository's `.codex/hooks.json` unreviewed too — so the
+ *  server also writes the trust record for each of these exact hooks into
+ *  the config.toml it generates (sandbox/codex-hooks.ts). Verified live
+ *  against codex 0.159.2 and 0.160.0 for the rtk hook: with the record,
+ *  `codex exec` rewrote `git status` through rtk with no bypass flag;
+ *  without it, the hook was skipped.
+ *
+ *  The PostToolUse group carries NO matcher: codex runs a matcher-less hook
+ *  after every tool it completes (hooks/src/events/common.rs
+ *  matches_matcher: an absent matcher is a match), so a mid-turn message
+ *  lands at the next tool step whatever the tool was. */
+export const CODEX_PLATFORM_HOOKS = {
+  hooks: {
+    PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: RTK_CODEX_HOOK_COMMAND }] }],
+    PostToolUse: [{ hooks: [{ type: "command", command: CODEX_MID_TURN_HOOK_COMMAND }] }],
+  },
+} as const;
+
 /** Known-noise codex ADVISORY lines. codex emits these as `item.completed`
  *  error items on the `--json` stream (exec maps every `Warning` notification
  *  to an error item — verified against codex-cli 0.147.0), so without a filter
@@ -101,6 +203,41 @@ export function codexWriterLockPreflight(
     + `flock -n "$ac_lk" rm -f -- "$ac_lk" 2>/dev/null || true; fi; `;
 }
 
+/**
+ * codex's PLAN (its update_plan tool) on the `--json` stream: one
+ * `todo_list` item per turn, `item.started` on the plan's first update,
+ * `item.updated` (same id, the whole list) on every later one, and
+ * `item.completed` at the turn's end. That is codex-rs exec's
+ * event_processor_with_jsonl_output.rs, identical in rust-v0.153.4 and
+ * rust-v0.159.2, where it is the only `item.updated` codex emits; the item
+ * `{ id, type: "todo_list", items: [{ text, completed }] }` is the shape every
+ * todo_list item our machines have persisted carries. Each event maps to ONE
+ * whole-plan `plan` message, so the transcript's checklist, and the worker's
+ * status line, follow the plan while the turn runs (before this, the list
+ * surfaced once, at the turn's end, as a raw `todo_list` tool card).
+ *
+ * A step carries only `completed`: codex's `pending` and `in_progress` both
+ * serialize as false. Its plan tool allows at most one step in progress and
+ * a plan runs in order, so the first step not completed is the one under
+ * way; the rest are pending. The stream names no priority, so none is set.
+ */
+function codexPlanMessages(item: Record<string, unknown>, timestamp: string): AgentMessage[] {
+  const steps = Array.isArray(item.items) ? item.items : [];
+  let underWay = false;
+  const entries: AgentMessagePlan["entries"] = [];
+  for (const step of steps) {
+    if (typeof step !== "object" || step === null) continue;
+    const text = (step as { text?: unknown }).text;
+    if (typeof text !== "string" || text.trim().length === 0) continue;
+    let status: AgentMessagePlan["entries"][number]["status"];
+    if ((step as { completed?: unknown }).completed === true) status = "completed";
+    else if (!underWay) { status = "in_progress"; underWay = true; }
+    else status = "pending";
+    entries.push({ content: text.trim(), status });
+  }
+  return entries.length > 0 ? [{ type: "plan", entries, timestamp }] : [];
+}
+
 /** Exported for the fixture-based parity tests (ADR-0020): the legacy JSONL
  *  `mapEvent` is the golden the ACP normaliser is asserted equal to. Not part
  *  of the public runtime surface — `createCodexRuntime` stays the entry point. */
@@ -113,6 +250,22 @@ export const codexSpec: CliAgentSpec = {
   // every resume of the same thread, so supersede teardown must KILL it —
   // never detach it alive (server runner-kill.ts consumes this flag).
   exclusiveSessionWriter: true,
+  // Mid-turn input (the 2026-10-02 relayed-steer incident). codex reads
+  // stdin ONCE, as the prompt: `codex exec -` submits one UserTurn and never
+  // reads stdin again (codex-rs exec/src/lib.rs read_prompt_from_stdin and
+  // its single InitialOperation::UserTurn at rust-v0.160.0; the app-server's
+  // `turn/steer` is a different transport, not `codex exec`). So a running
+  // turn takes a message through the PostToolUse hook above: codex runs it
+  // after every tool call it completes, with the codex process's own
+  // environment; the hook prints the unfed inbox lines as `additionalContext`
+  // and codex records them as developer context in the live turn's history
+  // before the model's next request. One JSON string literal per inbox line,
+  // so the hook splices bodies without decoding. Codex builds the PostToolUse
+  // payload only for a tool call it counts as successful (tools/registry.rs),
+  // so a message lands at the next successful tool step. Source-verified at
+  // rust-v0.160.0 (the pinned CODEX_CLI_VERSION); the end-to-end run against
+  // a live codex is the acceptance check still owed.
+  midTurnInput: { transport: "tool-hook", messageLine: (text) => JSON.stringify(text) },
   // ACP-mode invocation (ADR-0020 increment 1). `codex` has no native `--acp`
   // flag; the adapter (a Rust binary shipped via npm) speaks ACP and drives a
   // compatible bundled `@openai/codex`. The runner attempts this first and
@@ -125,9 +278,11 @@ export const codexSpec: CliAgentSpec = {
     // (e.g. a sandbox-baked one) instead of the adapter's bundled copy.
     ...(process.env.CODEX_PATH ? { env: { CODEX_PATH: process.env.CODEX_PATH } } : {}),
   },
-  // Global npm install; symlink onto PATH only if the global bin dir isn't
-  // already there (so a non-login `sh -c` can find it).
-  install: 'sudo npm install -g @openai/codex && (command -v codex >/dev/null 2>&1 || sudo ln -sf "$(npm prefix -g)/bin/codex" /usr/local/bin/codex)',
+  // The E2B session image bakes this exact version (sandbox/baked-clis.ts),
+  // so this runs only on a machine whose image predates the bake: a global
+  // npm install of the SAME pin, symlinked onto PATH only if the global bin
+  // dir isn't already there (so a non-login `sh -c` can find it).
+  install: `sudo npm install -g @openai/codex@${CODEX_CLI_VERSION} && (command -v codex >/dev/null 2>&1 || sudo ln -sf "$(npm prefix -g)/bin/codex" /usr/local/bin/codex)`,
   // Codex reads the prompt from stdin when invoked as `codex exec ... -`.
   promptPayload: (prompt) => prompt,
   buildCommand: ({ promptPath, sessionId, model, cwd, effort }) => {
@@ -140,13 +295,13 @@ export const codexSpec: CliAgentSpec = {
       // for running in environments that are externally sandboxed".
       "--dangerously-bypass-approvals-and-sandbox",
       ...(model ? ["-m", shellQuote(model)] : []),
-      // codex's own reasoning knob — a config override, valid values
-      // none|minimal|low|medium|high|xhigh (codex docs; xhigh is the
-      // codex-max-tier deep-reasoning level). There is NO "max" in codex's
-      // vocabulary: the server rejects it for codex sessions
-      // (sessionEffortLockError), and this clamp to xhigh is the type-level
-      // backstop for a caller that bypasses that gate. The value comes from
-      // the closed CliReasoningEffort set, so it is shell-safe unquoted.
+      // codex's own reasoning knob — a config override. Every codex model
+      // takes low|medium|high|xhigh; only the GPT-6 and GPT-5.6 presets add
+      // max (codex 0.153+), so the platform offers codex up to xhigh: the
+      // server rejects "max" for codex sessions (sessionEffortLockError), and
+      // this clamp to xhigh is the type-level backstop for a caller that
+      // bypasses that gate. The value comes from the closed
+      // CliReasoningEffort set, so it is shell-safe unquoted.
       ...(effort ? ["-c", `model_reasoning_effort=${effort === "max" ? "xhigh" : effort}`] : []),
     ].join(" ");
     // Working directory via a shell `cd` — the idiom EVERY other runtime uses
@@ -172,11 +327,19 @@ export const codexSpec: CliAgentSpec = {
   mapEvent: (p): AgentMessage[] => {
     const ts = now();
     switch (p.type) {
+      case "item.updated": {
+        // Only the plan updates in place (codexPlanMessages); any other
+        // item surfaces on its started / completed events below.
+        const item = p.item as Record<string, unknown> | undefined;
+        return item?.type === "todo_list" ? codexPlanMessages(item, ts) : [];
+      }
       case "item.started":
       case "item.completed": {
         const item = p.item as Record<string, unknown> | undefined;
         if (!item) return [];
         const itype = String(item.type ?? "");
+        // The plan, whole, on its first update and at the turn's end.
+        if (itype === "todo_list") return codexPlanMessages(item, ts);
         // Text + reasoning land on completion (started carries no final text).
         if (itype === "agent_message") {
           return p.type === "item.completed" ? [{ type: "text", text: String(item.text ?? ""), timestamp: ts }] : [];
@@ -209,12 +372,17 @@ export const codexSpec: CliAgentSpec = {
           }
           return [{ type: "error", text, timestamp: ts }];
         }
-        // file_change / mcp_tool_call / web_search / todo: surface once, on completion.
+        // file_change / mcp_tool_call / web_search: surface once, on completion.
         if (p.type === "item.completed") {
           return [{ type: "tool_use", toolName: itype || "item", toolInput: item, toolUseId: String(item.id ?? ""), timestamp: ts }];
         }
         return [];
       }
+      // The turn's token classes as codex reports them (codex-rs
+      // exec_events.rs `Usage`): input, cached input, cache-write input,
+      // output and reasoning output. Every class is kept — cache writes land
+      // in the creation class, reasoning rides beside output (it is counted
+      // inside output_tokens, so the four totals stay additive).
       case "turn.completed": {
         const u = p.usage as Record<string, number> | undefined;
         if (!u) return [];
@@ -223,9 +391,10 @@ export const codexSpec: CliAgentSpec = {
           inputTokens: u.input_tokens ?? 0,
           outputTokens: u.output_tokens ?? 0,
           cacheReadTokens: u.cached_input_tokens ?? 0,
-          cacheCreationTokens: 0,
+          cacheCreationTokens: u.cache_write_input_tokens ?? 0,
           durationMs: 0,
           numTurns: 1,
+          ...(typeof u.reasoning_output_tokens === "number" ? { reasoningOutputTokens: u.reasoning_output_tokens } : {}),
           timestamp: ts,
         }];
       }
@@ -238,8 +407,8 @@ export const codexSpec: CliAgentSpec = {
   },
 };
 
-/** The effort levels codex actually has (`model_reasoning_effort`):
- *  low|medium|high|xhigh — no "max" (that level is Claude Code's alone). */
+/** The effort levels this runtime passes to codex (`model_reasoning_effort`):
+ *  low|medium|high|xhigh, the levels every codex model takes. */
 export type CodexReasoningEffort = Exclude<CliReasoningEffort, "max">;
 
 export interface CodexRuntimeConfig {