@agent-compose/sdk 0.8.5 → 0.8.7

package/dist/request-context/request-context.d.ts

@@ -1,7 +1,7 @@
 /**
  * RequestContext — one typed bag carrying tenant identity + freeform
  * per-run state across the boundary between server, dispatch, runner,
- * workflow body, agent loop, and (future) processors.
+ * workflow body, agent loop, and processors.
  *
  * Two halves:
  *

package/dist/runtimes/_cli-agent.d.ts

@@ -4,7 +4,7 @@
  * contract.
  *
  * This is a different *mechanism* from the other runtimes: `claudeRuntime`
- * drives the Anthropic Agent SDK and `vercelRuntime` drives the Vercel AI SDK,
+ * drives the Anthropic Agent SDK and `createVercelRuntime` drives the Vercel AI SDK,
  * but a CLI-agent runtime spawns the provider's own CLI (`codex exec --json`,
  * `amp -x --stream-json`) — the CLI brings its own agent loop + tools, and we
  * only stream-parse the events it prints. Codex and Amp are the first two; this
@@ -125,12 +125,15 @@ export interface ProbeDeathState {
 }
 /** The death-door decision, pure for tests. Null = keep polling. */
 export declare function probeDeathVerdict(s: ProbeDeathState, nowMs: number): "dead-gone" | "dead-silent" | null;
-/** The claude CLI's stderr complaint when `--resume <id>` names a thread
- *  that does not exist on this machine (the 2026-08-18 split-brain
- *  forensic). When a nonzero exit's stderr carries it, the transport
- *  surfaces the stderr as the turn's LAST error event even though a bare
- *  result error already streamed — the consumer's classifier needs the
- *  specific complaint, not the generic `error_during_execution` token. */
+/** The CLI's stderr complaint when the thread it was told to resume does
+ *  not exist on this machine: claude's `--resume <id>` "No conversation
+ *  found with session ID" (the 2026-08-18 split-brain forensic) and
+ *  opencode's `--session <id>` "Error: Session not found" (in the CLI's
+ *  red-bold ANSI dressing; 1.18.34). When a nonzero exit's stderr carries
+ *  it, the transport surfaces the stderr as the turn's LAST error event
+ *  even though a bare result error already streamed — the consumer's
+ *  classifier needs the specific complaint, not the generic
+ *  `error_during_execution` token. */
 export declare const RESUME_TARGET_MISSING_STDERR: RegExp;
 /** One durable-trio reading, parsed from the probe exec's single line. */
 export interface TurnProbeReading {
@@ -193,10 +196,31 @@ export declare const INJECT_FEEDER_RESULT_TAIL_BYTES = 262144;
 export declare const INJECT_ACK_POLL_ATTEMPTS = 30;
 export declare const INJECT_ACK_POLL_SECONDS = "0.5";
 export declare const INJECT_ACK_EXEC_TIMEOUT_MS = 25000;
+/** How the guest recognises the CLI's terminal `result` event in the durable
+ *  .out: a line that carries the `"type":"result"` pair and does not open
+ *  with another event's type, as an awk condition over `$0` (POSIX awk, so
+ *  dash, busybox and the macOS test hosts read it alike). The CLI does not
+ *  keep its key order: 2.1.212 wrote `{"type":"result",…` but 2.1.278 and
+ *  later write the pair near the END of the object
+ *  (`{"duration_api_ms":…,"result":"…","type":"result","duration_ms":…}`), so
+ *  the anchored prefix the resident contract used matched nothing on the
+ *  pinned 2.1.283. Every other event the CLI writes opens with its own type
+ *  (`{"type":"assistant",…`, `{"type":"stream_event",…`), which keeps a tool
+ *  call whose input holds the same pair from counting; tool output and model
+ *  text ride inside JSON strings, where the quotes are escaped. */
+export declare const CLI_RESULT_LINE_AWK: string;
 /** The in-guest feeder fragment, prepended to the detached wrapper script.
  *  Runs inside the setsid session (group-kill reaps it) and keys its loop to
  *  the wrapper's own pid (`$$`), like the heartbeat subshell. Exported for
- *  tests. */
+ *  tests.
+ *
+ *  The forward is GUARDED: the fed and delivered counters advance only
+ *  when `sed` wrote the lines. The loop keys on the wrapper, which outlives
+ *  a CLI that died without a result line by the sentinel write and the
+ *  exit push; in that window the FIFO has no reader, `sed` dies of SIGPIPE,
+ *  and an unguarded counter still advanced, so the ack exited 0 for a line
+ *  nobody could read and the settle sealed it (review C1). Guarded, the ack
+ *  sees no advance and exits 4 or 5, and the message stays owed. */
 export declare function streamInputFeederFragment(paths: {
     promptPath: string;
     fifoPath: string;
@@ -215,13 +239,28 @@ export declare function streamInputFeederFragment(paths: {
  *  activity) MUST wrap through here — the wrapper rides only the wire to
  *  the model; the stored conversation row keeps the user's raw text.
  *  The text is pinned by tests: change it deliberately or not at all. */
-export declare function wrapMidTurnUserMessage(text: string): string;
+export declare function wrapMidTurnUserMessage(text: string, opts?: MidTurnEnvelopeOptions): string;
+/** Who a mid-turn message speaks for, when it is not the session user.
+ *  `relayedFrom` = the display name of the person whose own words an agent
+ *  relayed verbatim; `fromOwnerAgent` = the thread agent that owns this
+ *  worker, in its own words; `platformNotice` = a system notice the
+ *  platform posted to wake the conversation (nobody's words); all absent =
+ *  the session user's own message. */
+export interface MidTurnEnvelopeOptions {
+    relayedFrom?: string | null;
+    fromOwnerAgent?: boolean;
+    platformNotice?: boolean;
+}
 /** The one delivery-ack exec `injectUserMessage` runs: append the message
  *  line to the durable inbox, then wait for the feeder's delivered counter
- *  to cover it. Exit 0 = delivered into the CLI's stdin pre-result; 4 = the
- *  runner died first; 5 = not delivered within the ack window (feeder
- *  stopped on the result, or the guest is crawling) — both non-zero exits
- *  mean "leave the message owed". Exported for tests. */
+ *  to cover it. Exit 0 = written into the CLI's stdin pipe pre-result,
+ *  which is NOT "the model saw it": the CLI surfaces the line at its next
+ *  tool boundary, so a kill before then loses it, and the settle's kill
+ *  terminals hold the anchor at the pre-inject dispatch head for that
+ *  reason (review D8). 4 = the runner died first; 5 = not forwarded within
+ *  the ack window (the feeder is not forwarding: it stopped on the result,
+ *  the resident turn gate is closed, or the guest is crawling). Both
+ *  non-zero exits mean "leave the message owed". Exported for tests. */
 export declare function injectAppendAndAckCommand(args: {
     line: string;
     target: number;
@@ -229,6 +268,60 @@ export declare function injectAppendAndAckCommand(args: {
     inboxPath: string;
     deliveredPath: string;
 }): string;
+/** stdin is a live message stream: the FIFO feeder above delivers the prompt
+ *  line first and inbox lines after (claude: `--input-format stream-json`). */
+export interface StdinStreamInputSpec {
+    transport: "stdin-stream";
+    /** Serialise the opening prompt into ONE stream-input stdin line
+     *  (claude: a stream-json user message). No trailing newline — the
+     *  transport owns line framing. */
+    promptLine(prompt: string): string;
+    /** Serialise one mid-turn user message into ONE stdin line. No
+     *  trailing newline. */
+    messageLine(text: string): string;
+    /** Serialise ONE in-band interrupt control line (claude: a stream-json
+     *  `control_request` with subtype "interrupt") — the ESC equivalent.
+     *  The CLI's control layer handles these immediately, MID-STEP
+     *  included: the running tool call aborts (its tool_result records the
+     *  harness's own rejection text), the run ends with an
+     *  `error_during_execution` result within ~100ms, and the session file
+     *  stays `--resume`-able with the whole turn context. Verified live
+     *  against claude 2.1.236. Absent → the runtime has no in-band
+     *  interrupt; callers fall back to kill semantics. */
+    interruptLine?(requestId: string): string;
+}
+/** The CLI hands the inbox to the model itself, through a hook it runs after
+ *  each tool call it completes (codex: the platform's PostToolUse command
+ *  hook, CODEX_MID_TURN_HOOK_COMMAND in codex.ts). The launch creates the
+ *  inbox and exports its paths into the CLI's environment
+ *  (toolHookInboxFragment); the hook reads them back, prints the unfed lines
+ *  as its additional context for the model and advances the delivered
+ *  counter. stdin stays the plain prompt file, so there is no in-band
+ *  interrupt on this transport. */
+export interface ToolHookInputSpec {
+    transport: "tool-hook";
+    /** Serialise one mid-turn user message into ONE inbox line the hook can
+     *  splice into its JSON output without decoding: a JSON string literal. */
+    messageLine(text: string): string;
+}
+export type MidTurnInputSpec = StdinStreamInputSpec | ToolHookInputSpec;
+/** The stdin-stream transport of a spec, or undefined. The FIFO feeder, the
+ *  resident harness, the prewarm lane and the in-band interrupt exist only
+ *  for this transport; the inject lane itself reads `midTurnInput`. */
+export declare function stdinStreamInputOf(spec: Pick<CliAgentSpec, "midTurnInput">): StdinStreamInputSpec | undefined;
+/** The environment the tool-hook lane hands the CLI, and so the hook: codex
+ *  runs a command hook with the CLI process's own environment (codex-rs
+ *  hooks/src/registry.rs Hooks::new, engine/command_runner.rs at
+ *  rust-v0.160.0). The turn's inbox and delivered-counter paths. */
+export declare const MID_TURN_INBOX_ENV = "AC_MID_TURN_INBOX";
+export declare const MID_TURN_DELIVERED_ENV = "AC_MID_TURN_DELIVERED";
+/** The tool-hook lane's launch fragment, prepended to the detached wrapper
+ *  script (the shell the CLI starts in): a fresh inbox, the counter at 0,
+ *  and both paths exported for the hook. Exported for tests. */
+export declare function toolHookInboxFragment(paths: {
+    inboxPath: string;
+    deliveredPath: string;
+}): string;
 /** SIGTERM grace before escalation: attempts × sleep = 5s. */
 export declare const REAP_TERM_WAIT_ATTEMPTS = 20;
 /** Post-SIGKILL confirm window: attempts × sleep = 2s (a KILLed process only
@@ -251,33 +344,63 @@ export declare function reapKillAndConfirmCommand(pid: number): string;
 export declare const RESIDENT_IDLE_TTL_S = 240;
 /** Watchdog poll cadence (seconds). */
 export declare const RESIDENT_WATCHDOG_POLL_S = 15;
-/** Anchored prefix of the CLI's terminal result event line. Anchoring keeps
- *  the guest-side counts honest against tool output that merely CONTAINS
- *  the substring; a serialization-order change fails SAFE (parity check
- *  refuses adoption → cold launch — a latency cost, never correctness). */
-export declare const RESIDENT_RESULT_LINE_PREFIX = "{\"type\":\"result\"";
+/** Shell command printing how many result lines the durable .out holds —
+ *  the guest's turn accounting (feeder gate, idle check, adoption parity).
+ *  Prints nothing when the file is missing: callers default an empty count
+ *  to 0. */
+export declare function cliResultCountCommand(outPath: string): string;
 /** One bounded exec printing the count of result lines at or past
  *  `fromByte` (0-based) in the durable .out. Always exits 0; stdout is the
  *  count (a missing file reads as 0). Hint-grade by design. */
 export declare function residentResultCountCommand(outPath: string, fromByte?: number): string;
+/** One bounded exec reporting the LAST result line in the durable .out
+ *  window [`fromByte`, `toByte`): prints `none` (no result line), `error`
+ *  (its `is_error` is true) or `ok`. Always exits 0 and never prints the
+ *  line itself. The harvest's confirm for a resident result the tailer never
+ *  parsed (review C2): a count alone cannot say whether the turn failed. The
+ *  whole line is searched for `"is_error":true`, wherever the CLI put it
+ *  (key order is not fixed). `toByte` bounds the window to bytes a drain
+ *  already walked past, so a result the drain never reached (or a line still
+ *  being written past its line-aligned offset) is not confirmed; omitted,
+ *  the window runs to the end of the file. A window with `toByte <= fromByte`
+ *  is empty. */
+export declare function residentLastResultCommand(outPath: string, fromByte?: number, toByte?: number): string;
 /** The resident feeder: `streamInputFeederFragment` with the result-break
- *  REPLACED by the end-file break — the ONLY guest-contract change the
- *  resident shape needs (verified live by the spec's probe: two messages,
- *  one process, one session file, graceful exit on `.end`). */
+ *  REPLACED by the end-file break (verified live by the spec's probe: two
+ *  messages, one process, one session file, graceful exit on `.end`), plus
+ *  the TURN GATE: inbox lines are forwarded only while a delivered turn is
+ *  still unanswered (the result count in .out is below `.served`),
+ *  the same two numbers the idle predicate reads. Without the gate, a line
+ *  appended after the turn's result line but before the server settled the
+ *  turn was fed into the idle CLI, started a turn nobody tails, and was
+ *  acked as delivered: the message was never answered, and the extra result
+ *  line broke the next adoption's parity. With the gate that line stays
+ *  unfed, the inject ack exits 5, and the message stays owed for the
+ *  follow-up turn. Adoption bumps `.served` BEFORE it appends, so the next
+ *  turn's prompt still flows. The count is a full-file grep, re-run
+ *  only on a poll that has unfed lines AND a changed (.out size, .served)
+ *  pair, so an idle resident holding a gated line never rescans. The
+ *  forward is guarded like the plain feeder's: the counters advance only
+ *  when `sed` wrote the lines into the FIFO. */
 export declare function residentFeederFragment(paths: {
     promptPath: string;
     fifoPath: string;
     inboxPath: string;
     deliveredPath: string;
     endPath: string;
+    outPath: string;
+    servedPath: string;
 }): string;
-/** Sets `ac_idle` (1 = between turns: every delivered turn has its result
- *  and the inbox is fully fed). Embedded by the watchdog and the resident
- *  heartbeat gate — one idle predicate, stated once. */
+/** Sets `ac_idle` (1 = between turns: every delivered turn has its result).
+ *  Embedded by the watchdog and the resident heartbeat gate: one idle
+ *  predicate, stated once. Unfed inbox lines do not make a resident busy:
+ *  the feeder's turn gate forwards a line only while results < served, so
+ *  a line still unfed once results >= served is held until the next
+ *  adoption bumps `.served` (a message that raced the result, owed on the
+ *  server). Reading it as work would keep the heartbeat fresh and the
+ *  watchdog quiet for as long as the line sat there. */
 export declare function residentIdleCheckFragment(paths: {
     outPath: string;
-    inboxPath: string;
-    deliveredPath: string;
     servedPath: string;
 }): string;
 /** Guest idle watchdog: reap the whole process group after
@@ -302,8 +425,6 @@ export declare function residentIdleCheckFragment(paths: {
  *  process existence). */
 export declare function residentIdleWatchdogFragment(paths: {
     outPath: string;
-    inboxPath: string;
-    deliveredPath: string;
     servedPath: string;
 }): string;
 /** Exit-event doorbell with the turnId read from a guest FILE at push time
@@ -341,6 +462,13 @@ export declare const INSTALL_PROBE_TIMEOUT_MS = 30000;
  *  detached launch — the session images bake only `claude`, so codex/
  *  opencode/cursor/droid MUST be installable at launch on a fresh machine. */
 export declare const CLI_INSTALL_TIMEOUT_MS = 300000;
+/** Recover the detached runner's pid from its durable pidfile after the
+ *  launch exec's STREAM died (deadline_exceeded, canceled context, any wire
+ *  fault). Reads over the file transport with a short retry so the race
+ *  where the launch shell is still writing the pidfile is absorbed.
+ *  Exported for the server's workflow-lane launch (turn-workflow/tailer.ts
+ *  launchDetachedRunner), which recovers the same way. */
+export declare function recoverLaunchPid(read: (path: string) => Promise<string>, pidPath: string): Promise<number>;
 /** Single-quote a value for safe interpolation into a `sh -c` command line. */
 export declare function shellQuote(value: string): string;
 /** $HOME-relative path of the platform-managed session env file. The server
@@ -354,6 +482,16 @@ export declare const SESSION_ENV_FILE_RELPATH = ".agent-compose/session-env.sh";
  *  when no env file is configured. Errors are swallowed — a missing or
  *  unreadable file must never fail a turn. */
 export declare function sessionEnvSourceFragment(relPath: string | undefined): string;
+/** Shell command printing a fingerprint of the session env file's current
+ *  bytes (POSIX `cksum`), or `absent` when there is no file. A resident
+ *  records it next to its prompt immediately BEFORE sourcing the file, and
+ *  an adoption compares the file's fingerprint at that moment with it: a
+ *  fresh launch would source the file as it is now, the resident only ever
+ *  saw the one it started with. Recording before the source keeps the
+ *  comparison conservative — a write that lands between the two reads as a
+ *  change. The guest file is the one truth every replica writes to, so the
+ *  verdict never depends on which server process wrote it. */
+export declare function sessionEnvFingerprintCommand(relPath: string): string;
 /** The per-turn model-credential source fragment (`RuntimeOptions.
  *  credEnvFile` — an ABSOLUTE guest path), or "" when none is configured.
  *  Sourced AFTER the session env file so the turn actor's credential wins.
@@ -458,9 +596,9 @@ export interface CliAgentSpec {
      *  `effort` is present only when the caller configured a reasoning effort
      *  AND the spec has a real knob for it (see `CliReasoningEffort`).
      *  `streamInput` is true when the durable transport is feeding stdin as a
-     *  live message stream (see `CliAgentSpec.streamInput`): `promptPath` is
-     *  then the FIFO the feeder writes, and the CLI must be invoked in its
-     *  stream-input mode (claude: `--input-format stream-json`). */
+     *  live message stream (the "stdin-stream" `midTurnInput` transport):
+     *  `promptPath` is then the FIFO the feeder writes, and the CLI must be
+     *  invoked in its stream-input mode (claude: `--input-format stream-json`). */
     buildCommand(args: {
         promptPath: string;
         sessionId?: string;
@@ -502,37 +640,15 @@ export interface CliAgentSpec {
         args: string[];
         env?: Record<string, string>;
     };
-    /** Mid-turn STREAM-INPUT support (the delivery half of
-     *  `injectUserMessage`). When present AND the durable detached transport
-     *  is in play, the CLI's stdin is fed from a FIFO by an in-guest feeder:
-     *  the prompt line first, then any lines appended to the turn's durable
-     *  inbox file — so a steering-capable CLI (claude: queued user input is
-     *  folded into the RUNNING turn at the next tool boundary; verified live
-     *  against claude 2.1.233) receives user messages while the turn runs.
-     *  The feeder stops at the CLI's terminal result line (a message that
-     *  races the result is NOT forwarded — it stays owed) and closes the
-     *  FIFO, which is what ends the CLI process (stream-input CLIs exit on
-     *  stdin EOF, not after a result). Absent → the prompt file is the whole
-     *  stdin, exactly as before. */
-    streamInput?: {
-        /** Serialise the opening prompt into ONE stream-input stdin line
-         *  (claude: a stream-json user message). No trailing newline — the
-         *  transport owns line framing. */
-        promptLine(prompt: string): string;
-        /** Serialise one mid-turn user message into ONE stdin line. No
-         *  trailing newline. */
-        messageLine(text: string): string;
-        /** Serialise ONE in-band interrupt control line (claude: a stream-json
-         *  `control_request` with subtype "interrupt") — the ESC equivalent.
-         *  The CLI's control layer handles these immediately, MID-STEP
-         *  included: the running tool call aborts (its tool_result records the
-         *  harness's own rejection text), the run ends with an
-         *  `error_during_execution` result within ~100ms, and the session file
-         *  stays `--resume`-able with the whole turn context. Verified live
-         *  against claude 2.1.236. Absent → the runtime has no in-band
-         *  interrupt; callers fall back to kill semantics. */
-        interruptLine?(requestId: string): string;
-    };
+    /** Mid-turn INPUT support (the delivery half of `injectUserMessage`): how
+     *  a line appended to the turn's durable inbox reaches the CLI while its
+     *  turn runs — see the transports above. Engages only on the durable
+     *  detached transport (the inbox, the delivered counter and the feeder or
+     *  hook live in the guest; single-exec transports keep the plain
+     *  prompt-file stdin). Absent → the runtime cannot take a message
+     *  mid-turn: every inject answers "unsupported" and the message waits for
+     *  the turn boundary. */
+    midTurnInput?: MidTurnInputSpec;
 }
 export declare class CliAgentRunner implements ModelExecutionContract {
     private readonly sandbox;
@@ -611,12 +727,13 @@ export declare class CliAgentRunner implements ModelExecutionContract {
     /** Deliver one user message INTO the live turn — see the contract doc
      *  (types/runtime.ts). Appends a stream-input line to the turn's durable
      *  inbox and waits for the in-guest feeder's delivered-counter ack; only
-     *  an acked forward (pre-result, into the CLI's stdin) reports
-     *  "delivered". Guest exit 5 (ack window exhausted with the runner still
-     *  alive — a CLI that is not draining stdin mid-step) reports "pending":
-     *  the appended line may still be read when the current step finishes,
-     *  but it was NOT seen yet. Never throws. */
-    injectUserMessage(text: string): Promise<"delivered" | "pending" | "closed" | "unsupported">;
+     *  an acked forward (pre-result, written into the CLI's stdin pipe)
+     *  reports "delivered", and even then the model reads the line only at
+     *  its next tool boundary (review D8). Guest exit 5 (ack window exhausted
+     *  with the runner still alive: the feeder is not forwarding) reports
+     *  "pending": the appended line may still be forwarded later, but it was
+     *  NOT seen yet. Never throws. */
+    injectUserMessage(text: string, opts?: MidTurnEnvelopeOptions): Promise<"delivered" | "pending" | "closed" | "unsupported">;
     /** Request an in-band step interrupt of the LIVE turn — the ESC
      *  equivalent; see the contract doc (types/runtime.ts). Appends the
      *  spec's interrupt control line to the turn's durable inbox; the guest

package/dist/runtimes/_reported-model.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A model id as a harness names it — the one derivation behind every
+ * `model_report` the Claude runtimes emit (AgentMessageModelReport): the
+ * `model` on claude-code's `system`/`init` event and the `message.model` on
+ * each `assistant` event, which the Agent SDK's messages mirror.
+ *
+ *   - claude-code's `[1m]`-style suffix (`claude-opus-4-8[1m]`) is the CLI's
+ *     context-window marker: a variant flag on the same model, not another
+ *     model, so the report drops it;
+ *   - `<synthetic>` is the harness's own voice (slash-command stdout,
+ *     advisories) and names no model;
+ *   - anything that is not a non-empty string names none.
+ *
+ * Machine-format rules only; nothing here reads words.
+ */
+export declare function reportedModelId(raw: unknown): string | undefined;

package/dist/runtimes/claude-code.d.ts

@@ -33,7 +33,7 @@
  *     sessions this is the gateway-minted session virtual key pointed at the
  *     token-metering gateway's Anthropic passthrough (ADR-0039).
  */
-import type { AgentMessage, AgentMessageCompaction, AgentMessageTaskNotification, AgentMessageTaskProgress } from "../index.js";
+import type { AgentMessage, AgentMessageCompaction, AgentMessageModelUsage, AgentMessagePlanLimits, AgentMessageTaskNotification, AgentMessageTaskProgress } from "../index.js";
 import { type CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
 /** Pinned Claude Code ACP adapter (Zed's npm shim — `claude` has no native
  *  ACP mode). Pinned EXACT, not a range: the adapter's README warns of
@@ -82,6 +82,18 @@ export declare function parseSystemTaskProgress(p: Record<string, unknown>, time
  *  compact_result stays unmapped). Pure and tolerant over untrusted harness
  *  JSON. Exported for tests. */
 export declare function parseSystemCompaction(p: Record<string, unknown>, timestamp: string): AgentMessageCompaction | null;
+/** 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 declare function parsePlanLimits(p: Record<string, unknown>, timestamp: string): AgentMessagePlanLimits | null;
+/** 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 declare function parseModelUsage(raw: unknown): Record<string, AgentMessageModelUsage> | 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
@@ -90,6 +102,53 @@ export declare function parseSystemCompaction(p: Record<string, unknown>, timest
  *  `MAX_THINKING_TOKENS` env mapping is gone: the CLI deprecated it (treated
  *  as on/off on current models) and it could never express xhigh/max. */
 export declare const CLAUDE_CODE_EFFORT_LEVELS: readonly CliReasoningEffort[];
+/** 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 declare 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 declare const CLAUDE_CODE_PLATFORM_SETTINGS: {
+    readonly hooks: {
+        readonly PreToolUse: readonly [{
+            readonly matcher: "Bash";
+            readonly hooks: readonly [{
+                readonly type: "command";
+                readonly command: "command -v rtk >/dev/null 2>&1 && rtk hook claude; exit 0";
+            }];
+        }];
+    };
+};
 export declare const claudeCodeSpec: CliAgentSpec;
 export interface ClaudeCodeRuntimeConfig {
     /** Claude model id (`--model`). Omit to use the CLI's configured default. */

package/dist/runtimes/claude.d.ts

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

package/dist/runtimes/codex.d.ts

@@ -5,14 +5,102 @@
  * 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 CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
+/** 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 declare const RTK_CODEX_HOOK_COMMAND = "command -v rtk >/dev/null 2>&1 && rtk hook codex; exit 0";
+/** 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 declare const CODEX_MID_TURN_HOOK_COMMAND: string;
+/** $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 declare const CODEX_PLATFORM_HOOKS: {
+    readonly hooks: {
+        readonly PreToolUse: readonly [{
+            readonly matcher: "Bash";
+            readonly hooks: readonly [{
+                readonly type: "command";
+                readonly command: "command -v rtk >/dev/null 2>&1 && rtk hook codex; exit 0";
+            }];
+        }];
+        readonly PostToolUse: readonly [{
+            readonly hooks: readonly [{
+                readonly type: "command";
+                readonly command: string;
+            }];
+        }];
+    };
+};
 /** True when an error-item message is a known codex advisory (log-level
  *  noise), not a real error. Exported for tests. */
 export declare function isCodexAdvisoryNoise(text: string): boolean;
@@ -28,8 +116,8 @@ export declare function codexWriterLockPreflight(threadId: string, waitAttempts?
  *  `mapEvent` is the golden the ACP normaliser is asserted equal to. Not part
  *  of the public runtime surface — `createCodexRuntime` stays the entry point. */
 export declare 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 {
     /** Codex model id (`-m`). Omit to use the codex CLI's configured default. */

package/dist/runtimes/codex.mid-turn-hook.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * codex's mid-turn hook, run for real: the PostToolUse command hook
+ * (CODEX_MID_TURN_HOOK_COMMAND) executed under `sh` the way codex runs a
+ * command hook — the event JSON on stdin, the codex process's environment —
+ * against a constructed inbox, and the launch fragment that gives the codex
+ * process that environment (toolHookInboxFragment). These pin what the
+ * guest DOES: the JSON codex parses, the delivered counter the server's ack
+ * trusts, and silence everywhere else.
+ */
+export {};

package/dist/runtimes/model-report.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The harness's own report of the model it runs (AgentMessageModelReport,
+ * owner 2026-10-06: "what model actually did the work"), one case per
+ * branch of the one derivation (_reported-model.ts) and of the specs that
+ * emit it:
+ *   - claude-code's `system`/`init` names the session's model, minus the
+ *     CLI's `[1m]` context-window marker; an init without one names none;
+ *   - a top-level `assistant` event names the model the API answered with,
+ *     before its content; the harness's own voice (`<synthetic>`) and a
+ *     subagent's event (`parent_tool_use_id`) name none;
+ *   - codex's and opencode's streams carry no model: their specs emit no
+ *     report for the events that would carry one.
+ */
+export {};