Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

chore: merge origin/main into worktree-investgiage-gpt-file

Jack Rudenko20935f6c35ad
diff --cc CLAUDE.md
index ce661a49,7fcd4326..81898dad
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@@ -16,8 -15,12 +16,12 @@@ lives in `ROADMAP.md`
- `network-recovery.md` — the two-tier connection hold: the DERIVED deadline (`API_TIMEOUT_MS`, not a
watchdog), why tier 2 answers 503 and never 429, why the banner is magmux's `overlay` and never a
pane of ours (closing a pane wedged Claude Code), the five auth sites
- - `behavior-layer.md` — Layer 4, the harness-conformance supervisor
+ - `hooks.md` — the hook system (`hooks/`): closed actions and severity, the unsafe raw tier and its
+ transactional containment, the response seam and opt-in buffering, cross-process injection through
+ the owner-created inbox, the `SETTLING` hold and turn chains, the interactive driver, and the
+ harness-conformance supervisor with its plan-mode measurement. Read before editing `hooks/`, a stream
+ parser's raw tap, or the settle path. User guide: `docs/advanced/hooks.md`
-- `advisor.md` — `--advisor` for any main model: independent of `--monitor`, decorator on the routed handler, ids by tool name, retained session state, stub paths S1-S10, Claude Code's gates, metered panel billing; read before editing advisor, decorator, monitor-launch or native-auth code
+- `advisor.md` — `--advisor` for any main model: independent of `--monitor`, decorator on the routed handler, ids by tool name, retained session state, stub paths S1-S10 and the record fields, Claude Code's gates; panel routing through `planAdvisorModel` + `buildAdvisorChains` before the port (no lazy path), the advisor handler set, the never-served panel gateway, stickiness, and the Claude rule (login only where `childAuthControl` says claudish controls the child's auth, S0 request shape, the 429 "Error" shape refusal); read before editing advisor, decorator, panel gateway, `planAdvisorModel`/`buildAdvisorChains`, monitor-launch or native-auth code
- `providers/devin.md`, `providers/grok-subscription.md`, `providers/antigravity.md`, `providers/qwen-alibaba.md` — one per reverse-engineered provider
- `providers/meta-muse-code.md`: `muse@` on a Muse Code subscription and its metered sibling `meta@`: the mint
as entitlement evidence (per process, on 401, 30-min TTL), the Muse Keychain item read only by an
diff --cc ai-docs/architecture/README.md
index a26bbd67,a945ded7..3b5f445a
--- a/ai-docs/architecture/README.md
+++ b/ai-docs/architecture/README.md
@@@ -29,9 -29,8 +29,9 @@@ three earlier write-ups this material c
| [`keychain.md`](keychain.md) | The macOS Keychain backend: the 17ms-vs-28ms measurement that split presence from values, the two `security` behaviours that are traps (hex reads, a "secure" write that stores nothing and exits 0), and why no new `CredentialSource` member | touch `providers/keychain.ts`, `keychain-source.ts`, or the Providers tab's key write/delete |
| [`wire.md`](wire.md) | Every request from the connection's catalog `wire` and the route registry: the four-step pipeline, Jack's decisions where they diverge from the backend spec (clamp, borrow-and-drop, try in turn), the first-run refusal that stuck for a session, `+` doubling as the chain separator, name gates one layer down, custom endpoints' declared wire, the advisor and discovery on registry hosts | touch `connection-*.ts`, `wire-*.ts`, `declared-wire.ts`, `ComposedHandler` step 5w, an adapter's limit or reasoning fields, the advisor's request, or `+`/`#` model-spec markers |
| [`adapters.md`](adapters.md) | Layers 1–3 (FormatConverter / ModelTranslator / ProviderTransport), stream-parser selection, errors that ride an HTTP 200, and the `upstream_status` remap with its downstream readers | add a provider, model translator, or stream parser; or change error classification and retry |
+| [`code-mode.md`](code-mode.md) | `--code-mode` for `openai-codex`: one freeform `exec` tool running JavaScript in a QuickJS sandbox, nested calls relayed as `tool_use` blocks; the decision and why its gates run in that order, the lite and classic shapes and the lite → classic fallback, the request-scoped binding and the account/session keys, step 5r resume and its tombstones, the input builder (turn records, classic rounds transliterated), the store byte ceilings, and the sandbox measurements (handle ownership, wasm growing to 2 GiB under a 32 MiB heap limit, hence the 256 MiB ceiling per module, retire-and-replay past it) | touch `code-mode/`, step 5d or 5r, the Responses leg parser's exec handling, the turn driver's code-mode hooks, or the sandbox limits |
| [`network-recovery.md`](network-recovery.md) | The two-tier connection hold: why the deadline is DERIVED from `API_TIMEOUT_MS` (measured 359.607 s, a default and not a watchdog), why the tier-2 status is 503 and never 429, why the banner is magmux's `overlay` and never a pane of ours (closing a pane wedged Claude Code), why its lease is renewed on its own tick and not by ladder events, the five sites where a network failure wore an auth status code, and why a pane child gets no watchdog | touch the retry ladder, `recovery/`, the tier-2 status, the recovery banner, or any `x-claudish-recovery` reader |
- | [`behavior-layer.md`](behavior-layer.md) | Layer 4, the harness-convention SUPERVISOR: the rule engine, the four hooks, the 115-call plan-mode measurement it was built on, and opt-in telemetry | write a `behavior/` rule, or change harness-conformance handling |
+ | [`hooks.md`](hooks.md) | The hook system, which replaced the behavior layer and the `MiddlewareManager`: closed actions and severity, the process topology and the owner-created inbox, request stages A and B, the response seam's three stages and opt-in buffering, the raw tier's transactional containment, hook output kept off the MCP protocol stream (`dup2`), the settle hold (`SETTLING`, record then conclude, turn chains), the interactive driver; plus the harness-convention SUPERVISOR rationale, the 115-call plan-mode measurement and opt-in telemetry | write or change a hook or built-in hook, touch `hooks/`, the response seam, a stream parser's raw tap, the settle hold, or harness-conformance handling |
| [`advisor.md`](advisor.md) | `--advisor` for any main model: why it is independent of `--monitor` yet keeps four of its launch bits, the decorator around the ROUTED handler, id capture by tool name (the `toolu_` prefix that made it a no-op on every foreign provider), the tee and retained session-keyed state, the ten stub paths and advice origin, Claude Code's advisor gates, metered panel billing, and the inherited-placeholder 401 | touch `--advisor`, `advisor-decorator.ts`, `native-handler-advisor.ts`, `advisor-startup.ts`, monitor-gated launch code, or native auth in `claude-runner.ts` |
| [`headless-vs-interactive.md`](headless-vs-interactive.md) | Why `-p` is NOT interactive-without-a-TTY: an UNKNOWN `--agent` is SILENTLY unvalidated under `--input-format stream-json` (measured, exit 0, no stream frame, `result: success`), upstream closed it as not planned, why magmux is in the dependency tree, the one `-p` the MCP server starts (`run_prompt` on a Claude model) and why it is safe, and why a driver cannot rely on magmux's pane states | drive Claude Code headlessly, add a child-spawn flag, or assume a headless run behaves like an interactive one |
| [`pane-session.md`](pane-session.md) | MCP `team` slots, CLI `team` and `create_session` as interactive Claude Code in headless magmux panes: the transcript as turn oracle, boot from screen content and closed dialog lists ("never accept"), the four settle paths with the measured `secondaryQuietMs` (32 s), prompt delivery by file with read coverage and exact `require_pattern` semantics, the environment snapshot and shell shim, one level of nesting (`inMcpSession`/`isPaneChild`, the nested refusal), the pane watcher and the identity-checked reap, the socket traps, `seq` ownership, the D9/D10 bounds, the phase table, and the frozen mod contract v1 | edit `pane/`, team or MCP session spawn, the settle rule, prompt delivery, the reap or sweep, or any field the mod contract carries |
diff --cc ai-docs/architecture/advisor.md
index 66dd99af,1dc295ab..134e0693
--- a/ai-docs/architecture/advisor.md
+++ b/ai-docs/architecture/advisor.md
@@@ -315,239 -287,20 +315,240 @@@ settings, `/advisor`). The variable alo
## Panel routing and billing
-Panel and collector calls never go through `route()`. `advisorRouteFor(modelSpec, role)` is the
-only place the branching lives. Request building, key resolution (`advisorCredentialsFor`), the
-origin records and the startup checks all read it, so startup cannot drift from runtime.
+Through v12.1.2 every panel and collector call was one bare `fetch` with a metered key chosen by a
+hand-written `advisorRouteFor`: a Codex, SuperGrok or Antigravity subscriber paid per token, `cx@`
+and `gk@` went to OpenRouter, a Claude panel member went to OpenRouter, and no panel spend reached
+stats. That function is gone. Each member is now planned by the function main routing is derived
+from, and called through the same handler machinery as a main-model request. Session
+`dev-feature-advisor-subscription-20261020-233354-f7e4` holds the design (`architecture.md`, its
+amendments A1–A9) and the S0 measurement; the session directory is gitignored, so the load-bearing
+facts are copied here.
+
+### One routing function, planned and built before the port exists
+
+`planAdvisorModel(spec, role, deps)` (`handlers/advisor-route-plan.ts:149`) decides each member,
+in this order:
+
+1. `splitWireMarkers` — a marker error (`+pro`, `#fast` misuse) is a refused plan.
+2. `nativeRouteFor` FIRST, as the proxy does (CLAUDE.md invariant). A Claude name becomes a
+ `claude-native` plan (`planClaudeMember`, `:214`) and never reaches `explainRoute`; Claude Code
+ selectors are refused (`claudeAdvisorModelFor`, `handlers/advisor-claude-route.ts`):
+ `opusplan`, `best` and any `[1m]` form name no single model id the API accepts; `internal` and
+ `default` resolve to the opus tier; a tier alias resolves through the catalog alias, then the
+ newest `claude-<tier>-*` id; a concrete `claude-*` id is passed through.
+3. `ensureCatalogReady(5000)`, the proxy's wait.
+4. `explainRoute(model)` — the function `route()` is derived from. `no-route` is a refused plan
+ with routing's own cause, reason and hint; otherwise the plan's hops are the `kept` candidates
+ in chain order, each billed by `isSubscriptionProvider` at plan time.
+
+An explicit `anthropic@…` spec is NOT native (explicit specs never are, in the proxy either), so
+it is planned through `explainRoute`; only a bare Claude name takes the Claude arm.
+
+`evaluateAdvisorStartup` (`advisor-startup.ts:494`) plans every member strictly one after
+another, panel then collector, each in its own trace span (`startup:advisor-plan:<role>:<i>`),
+then builds every routed member's chain with `buildAdvisorChains`
+(`handlers/advisor-route-plan.ts:436`, span `startup:advisor-build`), also strictly sequential:
+a build may resolve a credential value (1Password, Keychain), and concurrent handshakes are what
+1Password refuses. The builder copies the proxy's dispatch (a `poe:` spec to the Poe getter, an
+`openrouter` hop to the OpenRouter getter, everything else to the remote getter, and the local
+getter only for an explicit single-hop plan) and classifies each hop: `built` (a
+`ComposedHandler`), `built-pending` (a `TryInTurnHandler` or `CatalogPendingHandler`, whose
+transport is chosen per request), `refused` (a `RefusingHandler`, asked once at build, no
+network; whether the chain continues past it is `FallbackHandler`'s own `isRetryableError` on its
+answer), `not-built` (getter returned null) or `failed` (getter threw; message redacted).
+
+The notice, the refusal and the runtime all read those plans and builds. `index.ts` hands them to
+`createProxyServer` as `advisorRuntime` (`index.ts:1119`); there is **no lazy path**: a spec the
+startup map lacks is S7 "advisor runtime not planned for this launch". A refusal shuts down every
+handler it built. Plans and chains are frozen per launch, like main's handler caches.
+
+### Credentials are resolved at launch, fallback hops included
+
+Startup planning reads the key of every candidate the routing chain keeps for a configured panel
+or collector model, once, at launch, through the same credential filter main routing runs on each
+request: `explainRoute` asks `credentials.describeReadiness` / `hasCredentialsForProvider` for
+every candidate (`providers/routing-rules.ts:1112-1120`), and `ApiKeyCredentialProvider`
+answers anything that is not in env, config or an OAuth file by resolving the value
+(`auth/credentials/api-key-credential.ts:336` → Keychain read, then op:// through
+`resolveOpKeyForEnvVars` at `:275`). The value is cached (`:234`), so the chain build's
+`getRequestAuth` (`handlers/handler-set.ts:368`) asks no vault a second time. With op:// keys
+this can mean a 1Password prompt at launch for a panel model's fallback hops, which a call may
+never reach.
+
+This is accepted (owner decision, 2026-10-21; requirement N4 is worded accordingly), because
+presence cannot be checked without reading the value: `op-source.ts` offers only `hasOpSources()`
+(`:458`, "is any 1Password source configured at all") and `resolveOpKeyForEnvVars` (`:831`), and
+glob entries and 1Password Environments name their variables only after the fetch, which needs
+the handshake. The Keychain can enumerate for presence (`keychain.md`); 1Password cannot.
+Changing this would mean changing main routing's credential filter for every request. The
+notice says it, on one line printed when any advisor member is routed:
-| Spec | Host | Key |
-|---|---|---|
-| `gemini-*`, `google@`, `gemini@` | generativelanguage.googleapis.com | `GEMINI_API_KEY` (`GOOGLE_API_KEY` as last-resort env fallback) |
-| `gpt-*`, `openai@`, `oai@` | api.openai.com | `OPENAI_API_KEY`, never the Codex login |
-| Claude model, as COLLECTOR only | api.anthropic.com | inbound `x-api-key` if real, else `ANTHROPIC_API_KEY` |
-| everything else, including `grok-*`, `cx@`, `gk@` | openrouter.ai | `OPENROUTER_API_KEY` |
+```
+ credentials: each routed advisor model's chain had its keys resolved at launch, including fallback hops (1Password or Keychain may have been asked once)
+```
-Every panel call is billed per token on a raw API key. A Codex or SuperGrok subscriber pays
-metered rates for panel calls, and a `cx@` or `gk@` panel spec goes to OpenRouter. The startup
-notice says so on every launch:
+### The advisor handler set, and why panel calls never touch the status line
+
+Chains are built in their own `createHandlerSet({requestRole: "advisor", port: 0, …})`
+(`advisor-startup.ts`). A handler owns a `TokenTracker` with cumulative counters, and one instance
+serving both main and panel traffic would mix them; the advisor set also has its own
+`FallbackHandler`s, so `lastSuccessIndex` never crosses between main and panel requests.
+`requestRole: "advisor"` on a `ComposedHandler`:
+
+- writes no token file (`composed-handler.ts:470` → `TokenTracker.writeFile` returns at once,
+ `shared/token-tracker.ts:504`), so the main status line is never repainted with the panel model.
+ A port cannot isolate it: `CLAUDISH_TOKEN_FILE` outranks the port;
- - skips the plan-usage scrape (`composed-handler.ts:3440`) and Layer 4 (`:1360`): a panel call is
- not a harness turn;
++- skips the plan-usage scrape (`capturePlanUsage`) and every hook (`requestHooksOf` is not read
++ for an advisor handler, and the panel gateway's never-served context carries no hooks anyway): a
++ panel call is not a harness turn;
+- tags every stats event `request_role: "advisor"` (`:593`).
+
+`requestRole` must stay in `sharedOpts`' `Pick` (`providers/provider-profiles.ts`); a
+profile-built handler without it writes the token file again, and nothing errors.
+
+### The panel gateway: a never-served Hono app
+
+`createAdvisorPanelGateway` (`handlers/advisor-panel-gateway.ts:83`) is two functions: `plan`
+(the startup map only) and `call`, which never rejects. `call` POSTs the payload to an internal
+Hono app that is never passed to `Bun.serve`, whose one route installs the call's abort signal,
+hop log and signing secrets on a real `Context` and hands it to the startup-built chain. It never
+goes through `resolveHandlerForRequest`, so the monitor branch, the `serve` slot map and the
+`--model` remap cannot touch a panel call, and no advisor wrapper is applied (no recursion). A
+loopback `fetch(proxy.url)` was rejected for exactly that reason: the `--model` remap would
+re-route the panel request to the main model.
+
+The synthetic request carries no auth header (and `ComposedHandler` forwards no inbound
+`authorization`), so Claude Code's bearer cannot reach a panel hop. Its payload is exactly
+`{model, system, messages, max_tokens: 2048, stream: false}` (`buildAdvisorPanelPayload`,
+`handlers/advisor-route-plan.ts:679`): no tools and no session id, so code mode stays off and
- Layer 4 has nothing to drain. The body is read inside the deadline (60 s panel, 30 s collector)
++no hook has pending notes to apply. The body is read inside the deadline (60 s panel, 30 s collector)
+and redacted by value against every credential the chain signed with, before the call's lease is
+released when its work settles (`:170`). A timeout aborts every piece of upstream work the chain
+started (`adapters.md`, "An internal call's deadline reaches every piece of upstream work").
+
+Deliberate deviations from main routing:
+
+- **Tier-1 network recovery is skipped** (`x-claudish-no-recovery: advisor`,
+ `composed-handler.ts:895`). Routing, classification and the connection verdict are identical;
+ only the hold ladder is skipped, because a 60 s budget cannot use a multi-minute hold and a
+ tier-2 503 means nothing to an internal caller.
+- **Explicit specs get the availability check at startup**, stricter than a main request. Where
+ the provider cannot answer (`openai-codex` has no discovery), the hop is kept, as on main; a
+ model the Codex account lacks is then an S7 carrying Codex's own (redacted) message.
+- **A cold catalog refuses a bare member at launch** (`catalog-unreadable`), which is the
+ runtime's answer too. The cold-catalog WARNING (`index.ts`) names only explicit-spec members,
+ whose provider was taken as written.
+
+### Stickiness is main routing's, and it is not silent
+
+`FallbackHandler` starts each call at the last hop that served (`lastSuccessIndex`). After one
+transient subscription failure that a metered hop answered, every later call of that member
+starts at the metered hop, exactly as on main (R3). A rejected subscription LOGIN is never routed
+onto a metered hop (only subscription hops are tried after a terminal credential verdict), which
+the notice says when a member's chain mixes the two. When a call is served by a hop whose billing
+differs from the hop the notice named, one line is written per change
+(`warnWhenServedUnlikePlan`, `handlers/native-handler-advisor.ts:2771`):
+
+```
+[advisor] gpt-x was served by OpenAI (metered, billed per token), not OpenAI Codex (subscription) as the notice said; later calls start there (routing keeps the last hop that served)
+```
+
+### Claude members and the Claude collector
+
+A Claude member is one request to the fixed `ANTHROPIC_MESSAGES_URL` (`https://api.anthropic.com/
+v1/messages`, `handlers/advisor-claude-route.ts`; `NativeHandler` imports the same origin), sent
+by `runClaudeAdvisorCall` (`handlers/native-handler-advisor.ts:2114`), which takes no URL
+parameter. The advisor applies the native passthrough's forwarding RULE here, not through a
+`NativeHandler` instance: that handler's fetch has no abort signal and records no stats, and its
+no-auth fallback hands out `ANTHROPIC_AUTH_TOKEN`.
+
+**These are claudish-composed requests signed with the Claude Code login, not Claude Code's own
+requests** (unlike `team` native slots, which are Claude Code's requests passed through). The
+owner can judge them against Anthropic's terms for subscription use with that stated plainly.
+
+**The login signs only on a launch where claudish controls the child's auth.** S0 (below) showed
+that a request cannot prove its bearer is the claude.ai login: the `oauth-2025-04-20` beta that
+login requests carry is client-declared (`ANTHROPIC_BETAS` adds it to any bearer) and the server
+does not require it. So the decision is made at launch by `childAuthControl(config, env)`
+(`claude-runner.ts:390`): controlled only when the launch is native-auth (no foreign `--model`
+handing the child claudish's placeholder), no user `ANTHROPIC_AUTH_TOKEN` and no real
+`ANTHROPIC_API_KEY` reaches the child, `ANTHROPIC_CUSTOM_HEADERS` carries no auth header, and no
+settings layer claudish can read (managed settings, `~/.claude/settings.json`,
+`$CLAUDE_CONFIG_DIR/settings.json`, the project and project-local files, `--settings`) names an
+`apiKeyHelper` or sets an Anthropic credential in its `env`. It cannot see settings delivered by a
+mechanism it does not read (an MDM profile). The decision travels in `AdvisorRuntime.childAuth`
+to the decorator (`proxy-server.ts:326`); a decorator given none treats the launch as not
+controlled.
+
+Per main request, the decorator reads the Claude facts once, before any member runs
+(`claudeRequestFacts`, `handlers/native-handler-advisor.ts:1854`), which also registers every real
+inbound bearer and `x-api-key` on that request's signing lease. The login arm needs ALL of: an
+inbound `Bearer` that is not a claudish placeholder; a value that is not this process's
+`ANTHROPIC_AUTH_TOKEN`; and `childAuth.controlled`. The value is held in `ClaudeLogin` (`:1762`),
+whose `String()`, `toJSON()` and inspect print `[redacted]`; only `runClaudeAdvisorCall` reads it.
+
+The credential for one advisor call is chosen by presence and provenance, never by failure
+(`resolveClaudeAdvisorAuth`, `:1937`), and resolved at most once per call and only when a Claude
+member runs (a routed-only panel never resolves an Anthropic key):
+
+1. the login, when every check passed — `arm: oauth`, `billing: subscription`;
+2. else the inbound `x-api-key` when it is real — metered;
+3. else `ANTHROPIC_API_KEY` through `resolveAdvisorCredential` (env, config, Keychain,
+ 1Password; never `ANTHROPIC_AUTH_TOKEN`, never a placeholder) — metered;
+4. else S7/S9 "no Claude credential".
+
+A real bearer that failed a check, or a request with no bearer, is never moved to a metered key
+silently: the call writes an `[advisor]` warning naming the reason. claudish's own placeholder (a
+proxy-auth launch, whose notice already says metered) is not a credential and only shows as
+`loginSkipped: "placeholder"`. A login the API rejects (401, 429) is reported with Anthropic's
+message and never retried on a metered key, as the native passthrough never does.
+
+**Request shape on the login arm** (S0 shape A): `authorization` (inbound, verbatim),
+`anthropic-version` (inbound, else `2023-06-01`), `anthropic-beta` (inbound, through
+`stripAdvisorBeta`), `content-type`; no `x-api-key`. `system` is `[identity block, advisor
+prompt]`, where the identity block is the first inbound system text block that is not Claude
+Code's billing-header block and spans one line, copied without its `cache_control`
+(`claudeIdentityBlock`). With no such block the prompt is sent alone and the record says
+`systemHead: "none"`. The API-key arms send the earlier metered request byte for byte: `x-api-key`,
+`anthropic-version: 2023-06-01`, a string `system`, shaped by the connection's wire when known
+(`claudeAdvisorRequestInit`, `:2050`).
+
+**HTTP 429 `rate_limit_error` "Error" with no `anthropic-ratelimit-unified-*` header is a shape
+refusal, not quota exhaustion** (`isClaudeShapeRefusal`, `:1988`). S0 got it for the prompt alone
+(shape A0) on every tier, deterministically, with `x-should-retry: true`. It is never retried and
+never cools anything down; the stub says so and the record carries `shapeRefusal: true`.
+
+Immediately before the fetch, one boundary line is logged from the `Request` being sent, never a
+value:
+
+```
+[advisor] Calling API: https://api.anthropic.com/v1/messages (role: panel, auth: bearer, source: claude-code-login, systemHead: identity)
+```
+
+### Billing and stats
+
+`billing` is decided by the arm that signed, never by the provider name: routed calls read it
+from the hop log after signing (`HopAttempt.billing`, set by `markHopSigned`: for
+`openai-codex`, the one credential-decided provider, it is that request's own
+`RequestAuth.arm`, `oauth` = subscription and anything else metered, never the name check, whose
+probe reads a process-wide last-signed arm; for every other provider it is its
+`SUBSCRIPTION_PROVIDERS` membership); Claude calls
+are `subscription` iff `arm === "oauth"` (`native-anthropic` is in neither billing set). That is
+the $0 evidence with stats on or off: `getModelPricing` returns zero exactly when
+`isSubscriptionProvider` is true, or, for a `ComposedHandler` request, when that request's own
+`RequestBilling` says subscription. The hop label and the token cost share one derivation
+(`ComposedHandler.signedBilling`), passed per call into every `TokenTracker` cost update,
+retry-leg input included, so a concurrent request's signing cannot reprice this one.
+
+Every advisor call records stats with `request_role: "advisor"`, with main's semantics:
+`estimated_cost` is the emitting handler's running total for the launch and `is_free_model` is
+"that total is 0". Routed calls get it from their advisor-set `TokenTracker`; Claude calls from a
+per-launch accumulator per model id (`claudeAdvisorSpend`, `:2182`), which adds 0 on the login arm
+and `calculateCost("native-anthropic", …)` on an API-key arm. A launch's advisor spend is the last
+`estimated_cost` per `(model_id, provider_name)` with `request_role = advisor`. Panel spend stays
+off the main status line by design.
+
+### The notice
```
[claudish] --advisor is on for this launch
diff --cc ai-docs/architecture/code-mode.md
index 29fbeb06,00000000..c82fc6d9
mode 100644,000000..100644
--- a/ai-docs/architecture/code-mode.md
+++ b/ai-docs/architecture/code-mode.md
@@@ -1,393 -1,0 +1,394 @@@
+# Code mode — Codex models driven the way their own client drives them
+
+`--code-mode <auto|on|off>` (> `CLAUDISH_CODE_MODE` > `codeMode` in the project `.claudish.json`
+> `codeMode` in the global config > the default `auto`) changes how the claudish provider
+`openai-codex` (the ChatGPT Codex backend, `cx@`) is asked to call tools. Instead of Claude
+Code's ~90 tools as classic function tools, the request carries ONE freeform tool, `exec`, whose
+input is a JavaScript script that calls `tools.<Name>(args)`; claudish runs the script in a QuickJS
+sandbox and relays every nested call to Claude Code as an ordinary `tool_use` block. The official
+Codex client has driven these models this way since `tool_mode: code_mode_only`; claudish was the
+only client still sending them classic parallel function calls.
+
+The default is `auto`: code mode is on only where the account's dynamic models catalog (the Codex
+`/models` endpoint) reports `tool_mode: "code_mode_only"` for the model, and only for `openai-codex`
+on the OAuth arm with tools declared; every other claudish provider is unaffected. It became the
+default after Phase 7 iteration 2 passed on Claude Code 2.1.303 and 2.1.304 (`[email protected]`):
+the real `auto` path 20/20 answers with 39/39 relayed exec ids resumed and 0 lost-state notes,
+edit + Bash 6/6, a claudish restart mid-script 2/2, and the compiled binary 1/1. `--code-mode off`,
+`CLAUDISH_CODE_MODE=off` or `codeMode: "off"` turns it off. With code mode off, everything code mode added is skipped (5r returns at once, 5d returns at the
+`setting-off` gate, apart from one `[CodeMode] off (setting-off)` log line per session). The
+request is NOT byte-for-byte what it was before this work, for one deliberate reason: commit
+`d6629064` sends `filterIdentity(system)` as the Responses `instructions` of EVERY `cx@` and
+`openai@` request, where the raw "You are Claude Code" system prompt went before. Each existing
+session loses its prompt-cache prefix once after that upgrade.
+
+Design and evidence: `ai-docs/sessions/dev-feature-codex-tool-calls-20261016-143706-dc2c/`
+(`architecture.md`, `research-codemode.md`, `research-sandbox.md`, `evidence/r1/`, `evidence/r2/`)
+— gitignored; the numbers that matter are copied here.
+
+## Why
+
+Three failures on `cx@`, one root cause:
+
+- **Zero-delta arguments.** Since 2026-07-29 the backend sends every multi-call turn with no
+ `function_call_arguments.delta`; claudish forwarded arguments only from deltas, so Claude Code
+ got `{}` (`InputValidationError: … The required parameter 'file_path' is missing`). Fixed in the
+ classic path ([`adapters.md`](adapters.md), "Zero-delta function calls").
+- **The degenerate `parallel` wrapper.** About 1% of turns end on a 41–96 KB `a.ts.tsaaa.ts…`
+ argument string after a 361–484 s keepalive-only stall. The B experiment found no request factor
+ that helps (Fisher p = 1.000 for effort, tool count and `strict:false`;
+ `ai-docs/reports/codex-parallel-wrapper-degeneration-2026-10.md`). Contained in the classic path
+ by the in-turn retry and the 150 s stall guard ([`adapters.md`](adapters.md)).
+- **Both are symptoms of a legacy protocol.** A live capture of codex-cli 0.161.0 shows the model's
+ native tool protocol is one `exec` call per response running `Promise.allSettled([...])`. Custom
+ tool input is ALWAYS streamed as deltas (9/9 captured calls), so the zero-delta failure cannot
+ occur, and there is no wrapper to degenerate.
+
+## The decision, and its order (`code-mode/policy.ts`, step 5d)
+
+Code mode is decided per request, after 5c, from THIS request's auth binding. The gates run in
+this order, and the order is deliberate — the static gates come first, so a request that can never
+be in code mode pays no discovery wait, creates no store and loads no sandbox:
+
+| # | Gate | Off reason | Why |
+|---|---|---|---|
+| 1 | claudish provider is `openai-codex` | `not-openai-codex` | the only backend measured |
+| 2 | setting is not `off` | `setting-off` | the user's opt-out |
+| 3 | the binding's arm is `oauth` | `metered-arm` | the api-key arm reaches api.openai.com, which publishes no `tool_mode` |
+| 4 | the login has a ChatGPT account id | `no-account-id` | every record is keyed by account (below); a login without one never gets code mode |
+| 5 | the wire API is Responses | `not-responses` | |
+| 6 | ≥ 1 tool declared | `no-tools` | Claude Code's first request is often tool-less |
+| 7 | `tool_choice` absent or `auto` | `forced-tool-choice` | a named tool, `any` and `none` are Claude Code's internal one-shot calls; the classic payload honours them exactly (`none` keeps the tools declared, it does not remove them) |
+| 8 | the request carries a Claude Code session id | `no-session-id` | the process-wide `conversationKey()` fallback is a cache hint and must never key stateful execution |
+| 9 | the sandbox loads | `sandbox-unavailable` | |
+| 10 | setting `on` | on, `forced` | |
+| 11 | discovery reports `tool_mode: code_mode_only` | on, `discovery` | `auto` |
+| 12 | the session is pinned | on, `pinned` | it already relayed an exec, so a later discovery failure cannot flip a code-mode conversation back to classic mid-script |
+| 13 | otherwise | `discovery-unknown` / `classic-by-discovery` | |
+
+The shape is `lite` iff discovery says `use_responses_lite: true` and no lite rejection is
+remembered for the model; otherwise `classic`. Logged once per session per change:
+`[CodeMode] on (lite, discovery: code_mode_only)` / `[CodeMode] off (<reason>)`; the two
+process-wide reasons (`no-account-id`, `no-session-id`) once per process.
+
+Discovery is the account's dynamic models catalog (`GET …/codex/models?client_version=`,
+`providers/codex-models-discovery.ts`): memoised per account for 1 h, single-flight,
+stale-while-error, `AbortSignal.timeout(10_000)` on every fetch, a 60 s back-off while no good
+answer exists, and a tool-bearing request with an empty memo waits at most 2 s before going
+classic. Never persisted. Discovery is not an auth site: every throw resolves to
+`discovery-unknown`, never to a status.
+
+## Two shapes, one tool (`code-mode/request.ts`)
+
+| | lite | classic |
+|---|---|---|
+| tools | none top-level; `input[0]` is `{type:"additional_tools", id:"at_<uuidv5>", role:"developer", tools:[exec]}` | `tools: [exec]` |
+| instructions | none; `input[1]` is a developer message with the system text | `instructions` = the system text |
+| reasoning | `context: "all_turns"` (effort: Claude Code's, else discovery's `default_reasoning_level`; neither → classic shape) | unchanged |
+| header | `x-openai-internal-codex-responses-lite: true` through `wireHeaders`, so every header fetch (primary, parameter retry, 401 retry, legs) carries it | none |
+| both | `parallel_tool_calls: false` (parallelism lives in the script), `tool_choice: "auto"`, `input` from the input builder | |
+
- The system text is Claude Code's system prompt (identity-filtered at step 4, after Layer 4) plus a
++The system text is Claude Code's system prompt (identity-filtered at step 4, after hook request stage A) plus a
+three-line claudish note — not the 21.7 KB Codex persona. Step 5a' re-applies `--model-params`
+only to a code-mode payload, so the user's explicit fields still win. A build that throws sends
+that request non-code-mode (logged); it never refuses.
+
+Live probes of what the backend accepts (R1 §1d):
+
+| Variant | Shape | Result |
+|---|---|---|
+| A | lite + header + `context: all_turns` | 200 |
+| C | classic `tools:[exec]`, no header | 200 |
+| D | classic + lite header, no `reasoning.context` | **400** `X-OpenAI-Internal-Codex-Responses-Lite requires \`reasoning.context\` to be \`all_turns\`.` |
+| G, H, I | round trips: `custom_tool_call` + `custom_tool_call_output` as parts, as a string, and a `Script failed` output | 200 |
+
+### Lite → classic fallback
+
+The lite header is internal to OpenAI. The first check of the 4xx block, on the RAW upstream status
+(before the terminal remap to 400): a lite request answered 400 whose body names the lite header or
+`reasoning.context` is rebuilt in the classic code-mode shape — the same exec tool and the same
+input, never the non-code-mode function tools — from the post-5c payload clone, `--model-params`
+re-applied, the lite header REMOVED from `wireHeaders` (variant D: a classic body with the header is
+itself a 400), and resent once through the parameter-retry fetch with fresh headers for this
+request's binding. The model stays classic for the discovery TTL (1 h). A retry that also fails
+falls through to the error path with the ORIGINAL response.
+
+## Identity: the binding, the account and the session
+
+Every value that depends on auth comes from ONE artifact the request holds in a local
+(`AuthBinding`, returned by `refreshAuth` at 5b), never from the transport's shared `cachedAuth`:
+another request's refresh can land during the 2 s discovery wait or between legs, and the login
+can change in-process (`reloadCredentials`).
+
+- `accountKey` = `sha256("openai-codex\0" + chatgpt-account-id)` from the binding's headers; defined
+ only for the `oauth` arm with the header present.
+- `sessionKey` = `sha256(session id + "\0" + accountKey)`.
+- Exec records are keyed `(accountKey, exec key)`: upstream call ids are unique, so a forked session
+ (`--fork-session`: new session id, same history, same account) still finds its execs and renders
+ their completed outputs byte-identically. Each record stores its OWNER session; only the owner may
+ resume it. Turn records and the pin are keyed by `sessionKey`.
+- Another account never finds, resumes or renders this account's records (their encrypted reasoning
+ would be rejected under another account anyway).
+
+## The exec tool (`code-mode/exec-tool.ts`)
+
+The definition is the official one (`type:"custom"`, `name:"exec"`, the lark grammar with the
+`// @exec:` pragma). The description lists only what claudish implements (`text()`, `exit()`,
- `tools`, `ALL_TOOLS`) and one section per tool rendered from `claudeRequest.tools` AFTER Layer 4,
++`tools`, `ALL_TOOLS`) and one section per tool rendered from `claudeRequest.tools` AFTER the hook request stages,
+so names are Claude Code's own, never the step-5 encoded wire names. Schemas become TypeScript
+declarations (property descriptions as `//` comments, depth ≤ 4, else `unknown`). Identifiers are
+normalised to `[A-Za-z0-9_$]` with the later of two colliding names skipped, as Codex does. Budget:
+≤ 6 KB per tool, ≤ 48 KB in all, in Claude Code's order; the rest are listed as "Deferred tools"
+and stay callable (`ALL_TOOLS` carries every tool). The rule is pinned, never a count.
+
+## A turn: relay, continue, resume
+
+### The leg and the driver
+
+The Responses parser is split into a leg parser (one upstream body) and a turn driver (one
+downstream Claude message) — the same mechanism that retries a degenerate leg
+([`adapters.md`](adapters.md)). With code mode on:
+
+- The leg HOLDS the `custom_tool_call` named `exec` (never a content block). Its input is
+ `custom_tool_call_input.done` ?? `output_item.done.item.input` ?? the accumulated deltas. The leg
+ keeps reading until `response.completed` / `.incomplete` / end of body, at most
+ `EXEC_DRAIN_MS = 10_000` (R1: the terminal event arrives milliseconds after the exec item), so the
+ outcome carries its usage. An exec cut by `response.incomplete` is never run: the model gets
+ `Script failed … exec input was truncated by max_output_tokens` and can send a shorter script.
+ An exec cut by a dropped socket (or a body that ends inside it) ends the message with an SSE
+ `error`, as a cut classic tool block does: the script never ran and nothing reached Claude Code,
+ so its retry is safe, where `end_turn` would stop the agent.
+- The hooks (`code-mode/relay.ts`) create the record, pin the session and run the script:
+ - **blocked** on N nested calls → N whole `tool_use` blocks `toolu_cx_<hex>_<seq>` (Claude Code's
- tool names; buffered tools repaired through Layer 4; `onToolCallObserved` once per nested
- block, never for `exec`), the message's Responses items stored as a turn record, `stop_reason:
++ tool names; `onToolCallObserved` once per nested block, never for `exec`; a `toolCall` hook
++ repairs them at the response seam above the parser, like any other tool block), the message's Responses items stored as a turn record, `stop_reason:
+ tool_use`. Claude Code runs the tools under its own permissions.
+ - **finished** without blocking → its output is stored and another leg is issued: the current
+ leg's body with this leg's items and the exec call + output appended to `input`.
+- `MAX_LEGS_PER_TURN = 6` (legs count continuations AND retries; each exec answered inside the
+ message adds a leg, so it bounds those too) ends the message with `[claudish: stopped after 6
+ upstream requests in one code-mode turn]`. A retry inside a code-mode
+ turn re-sends the CURRENT leg's body; retries count per leg position.
+- Usage stays honest: the context figure is the LAST leg's input, output is summed over legs, the
+ earlier legs' input is billed once (cost only) before the one `onTokenUpdate` that fires the
+ request's stats record.
+- A client gone before the `message_stop` of a relayed batch → the record is terminated: Claude
+ Code never saw the batch, and its retry starts a new upstream turn with a new exec id.
+
+`nestedId` decoding is strict (`^toolu_cx_([0-9a-f]{32})_(\d{1,4})$`): classic ids and the
+parallel wrapper's `toolu_<id>_p<k>` never decode, so history grouping never depends on the store.
+
+### Step 5r: resuming a script (`code-mode/resume.ts`)
+
- After 5b (the account is THIS request's) and after 3c (a synthetic reply gets the same Layer 4
- hooks), before 5c. Synchronous from record lookup to state transition, so two concurrent requests
++After 5b (the account is THIS request's) and after 3b (a synthetic reply gets the same raw
++hooks, and the response seam above the handler applies the closed tool hooks to it as to a driver
++batch), before 5c. Synchronous from record lookup to state transition, so two concurrent requests
+for one record serialise. Guard: `openai-codex`, `oauth` arm, an account key, a session id, ≥ 1
+declared tool (5d's `no-tools` gate: a tool-less compaction or summary request is never code mode,
+so it must not consume a batch, end other scripts, or get tool_use blocks), `tool_choice` absent or
+`auto`. A request with a named tool, `any` or `none` never resumes a
+script: consuming a batch there would run the script's next tools outside the turn that owns it;
+the next ordinary request resumes it. It reads the stores only if a code-mode request already
+created them, with one exception: when none exist (the first request after a restart) but the last
+message answers nested ids, 5r creates them (setting not `off`), so the lost script's tombstone is
+stored BEFORE 5d builds the input. Without it the builder rendered an unstored `Script failed` on
+that request and `Script completed` ("output unavailable after a claudish restart") on the next,
+for the same script.
+
+**"The last message" means the last user or assistant message** (`conversationMessages` in
+`code-mode/types.ts`), in 5r, in the input builder and in the turn-record anchor alike. Claude
+Code sends `role: "system"` messages inside `messages` (SessionStart hook output, MCP server
+instructions, the token reminder), and 2.1.303 ENDS requests with one: `user, system,
+assistant(tool_use×3), user(tool_result×3), system`. Reading the raw last message, 5r found no
+results on any request, so no script ever resumed and every answer took the lost path (Phase 7
+V2a/V2b/V4/V8: 0 resumes across 39 relays). The same system message arrives as blocks while it is
+last and as a string once a turn follows it, so it can never anchor a turn record either.
+
+| Situation (the last user message answers nested ids) | Behaviour |
+|---|---|
+| suspended, owned by this session, expected batch | results resolve or reject by seq (`is_error` rejects with a plain string, as Codex); missing → "no tool_result returned"; blocked again → **synthetic reply**; done → output stored, the upstream turn continues and the input builder renders it |
+| `[Request interrupted by user` beside the results | terminated: output so far, the results, "interrupted by the user"; continue. A LOST record is replayed only up to the answered round and terminated there (never fed its results), so Esc yields no further tool call |
+| consumed batch, same `batchHash` (a duplicate request) | the memoised step: the same synthetic reply, or the stored completion. The reply goes to the OWNER only: a fork asking while the owner's next batch is pending gets the forked-script `Script failed` below, never that batch (its tools would run twice) |
+| consumed batch, different `batchHash` (a rewind that re-ran tools) | lost path, tombstone under the new completion key |
+| suspended, owned by ANOTHER session (a fork) | untouched; the fork gets `Script failed` "this script belongs to the session this one was forked from; claudish cannot run it twice"; the owner's later run output wins every lookup |
- | record lost, source kept, owned by this session, the request answers its LAST round | **replay** (`replay.ts`): the source re-runs in a fresh runtime (when no module is loaded — the first answer after a retire, a poison or a recycle — 5r answers `needs-module` without touching anything, the handler awaits `loadQuickJSModule()`, about 3 ms, and runs 5r once more; 5r itself never awaits) and each batch is answered from history, provided batch k is exactly the k-th round (same ids, names and canonical inputs — or, for a call Layer 4 repaired when it was relayed, the script's input and history's input equal the hashes recorded then); then as the first row. The emitter writes a repaired input back onto the record's block (the script's own kept as `scriptInput`), so a duplicate reply re-sends exactly what was relayed, repaired once. `Math.random` is seeded by the call id; a script that branches on `Date` diverges |
++| record lost, source kept, owned by this session, the request answers its LAST round | **replay** (`replay.ts`): the source re-runs in a fresh runtime (when no module is loaded — the first answer after a retire, a poison or a recycle — 5r answers `needs-module` without touching anything, the handler awaits `loadQuickJSModule()`, about 3 ms, and runs 5r once more; 5r itself never awaits) and each batch is answered from history, provided batch k is exactly the k-th round (same ids, names and canonical inputs — or, for a call recorded as repaired when it was relayed, the script's input and history's input equal the hashes recorded then); then as the first row. The emitter writes a repaired input back onto the record's block (the script's own kept as `scriptInput`), so a duplicate reply re-sends exactly what was relayed, repaired once. Since hooks replaced the behavior layer, repair happens at the response seam, after the relay, and the relay passes the script's input unchanged: no repair is recorded, so a round whose call a `toolCall` hook repaired does not match on replay and the script is tombstoned instead of resumed. `Math.random` is seeded by the call id; a script that branches on `Date` diverges |
+| record lost (eviction, poisoned module, or a replay that diverged) or none (restart, another account) | `Script failed` "claudish lost this script's state (proxy restart or eviction); the nested tool results it was waiting for follow" + the results, stored as a TOMBSTONE (a minimal record when none) |
+| late results for a settled record | nothing; history renders its output |
+
+For every OTHER suspended record of the session: a pending batch the conversation moved past
+(a typed prompt instead of results) is terminated ("the conversation moved on without the tool
+results"); one on the LAST message (a prefill) or absent from the request (a Task subagent sharing
+the session id, compaction) is left alone — a subagent can legitimately run while the main thread's
+script waits on its `Task` call. TTL and LRU end those.
+
+The **synthetic reply** is written by the same sink and hooks as a driver batch, with
+`message_start`/`message_delta` usage = the previous request's input / 0, through the same exit as
+step 8 (`stream === true ? SSE : sseResponseToJson`). No upstream call, no auth beyond 5b's, no
+stats record: nothing was billed.
+
+Tombstones exist so the NEXT request renders the same bytes as this one: a function of history,
+stored under the completion key the history gives, rendered only for the session that stored it.
+A `run` output (a function of source + results) is rendered for any session; a tombstone never
+overwrites one.
+
+## History: the input builder (`code-mode/input-builder.ts`)
+
+Built from `claudeRequest.messages`, never from the step-3 conversion, which is lossy here: it lifts
+tool_result images into separate messages, synthesizes results for unanswered calls, joins
+assistant text blocks and knows nothing of scripts.
+
+- **Assistant message**: its turn record's items verbatim when one exists (how interstitial execs,
+ multi-leg text and reasoning come back in order), else its text blocks; thinking blocks are never
+ sent (reasoning travels as encrypted items).
+- **Exec group** (the nested tool_uses of one exec, across every round trip): its reasoning and
+ `custom_tool_call` ONCE at the first round; its `custom_tool_call_output` ONCE after the round
+ that completed it, looked up by completion key (`batchHash` of each batch's results, in order;
+ one function shared with 5r). Images are referenced, never stored, and resolved from the request
+ so each appears exactly once, inside the output.
+- **Record gone**: evicted → reconstructed source + `Script completed` "claudish evicted this
+ script's stored output under its memory limit"; gone for any other reason → the same with
+ "output unavailable after a claudish restart". Never `Script failed` for a script that resolved
+ in the past — and never `Script completed` for one that did not: that rendering requires every
+ call of the script's last round to carry a real result. A restart usually means the session
+ died with the script blocked, and `claude -c` then records each pending call as
+ `[Tool call interrupted: the session ended before this call's result was recorded…]`
+ (`is_error`), adds `No response requested.` and waits for the user (Phase 7 V7). Any such result
+ → `Script terminated` "the session ended before these calls' results were recorded, so this
+ script never received them and did not finish" (whether or not the record survived); a call
+ with no tool_result at all and no record → `Script terminated` "this script's outcome is
+ unknown". The review-round-1 premise that a resolved script always has a stored output holds
+ within one process only.
+- **Classic tool round** (a session that started classic, a `/model` switch, wrapper `_p<k>` ids,
+ a stray classic call) → ONE synthetic exec (`transliterate.ts`): `call_` + 32 hex of
+ sha256(first tool_use id), `Promise.allSettled([tools.Read({...}), …])` (`tools["name"]` for a
+ tool absent from today's list), `Script completed` with one part per result. A request therefore
+ never mixes classic `function_call` items with the exec tool — the one shape no probe proved.
+- **Orphan tool_result** (its call was compacted away) → user text `[Tool Result]: <text>`, as the
+ step-3 converter renders it; never dropped.
+- Text beside results (reminders, hook context) → a user message right after the output (or after
+ the call while the script is open).
+
+Output is byte-identical for byte-identical history and store state. The eviction renderings are
+pure functions of history plus the eviction sets, so the prompt-cache prefix changes ONCE, on the
+first request after an eviction.
+
+## Stores and their byte ceilings
+
+Process memory only (`code-mode/stores.ts`, created by the first code-mode request); a restart
+loses them, and the restart rendering covers that. Every store has a ceiling the model cannot
+raise:
+
+| Store | Ceiling | Eviction |
+|---|---|---|
+| suspended runtimes | 32 (one running + ≤ 31 suspended), all in the current module | LRU → record `lost`; a retired module's at once |
+| suspended idle | 6 h | `expire` → `lost` |
+| exec records (settled) | ≤ 2,000 AND ≤ 32 MiB (source + output text + reasoning JSON; images are references) | LRU; id kept in `evictedExecs` |
+| turn records | ≤ 2,000 AND ≤ 32 MiB; one record > 8 MiB is never stored | LRU by last render; anchor kept in `evictedTurns` |
+| eviction sets | ≤ 20,000 ids each (≈ 1.3 MiB) | FIFO |
+| relayed batch blocks | kept only while the record is live (inputs up to 8 MiB a batch, not in the byte cap) | dropped when it settles |
+
+A 60 s reaper applies the TTL and caps. Record states are a transition table
+(`patterns/state.md`); an illegal transition is logged and coerced to `lost`, never thrown —
+this runs on the request path, and a refused request is worse than a degraded script.
+
+## The sandbox (`code-mode/sandbox/`)
+
+QuickJS compiled to wasm, `quickjs-emscripten-core` + `@jitl/quickjs-singlefile-mjs-release-sync`
+0.32.0 (the singlefile variant inlines the wasm, so `dist/` and `bun build --compile` take one
+path). One module per process, loaded lazily on the first code-mode decision; one runtime + context
+per script; the script suspends across Claude Code round trips as deferred QuickJS promises, so a
+`Promise.all` of N calls is one batch of N tool_use blocks with no extra logic.
+
+**Packaging spike (measured).** Module load 27 ms cold, 12 ms warm. A `bun build --target bun`
+bundle (1.40 MB) ran from a directory with no `node_modules` in 12 ms; a `bun build --compile`
+binary, re-signed with `codesign --force -s -`, in 22.5 ms, Promise.all suspend/resume working.
+No wasm asset and no `files` change. `dist/` grew 3.37 → 4.69 MB (the variant sits behind a lazy
+`init_*()`); `dist/index.js --version` 0.09 s.
+
+**Handle ownership (measured).** A host function's RETURNED handle is consumed by the library
+(`scope.manage(result)` + `QTS_DupValuePointer`): `deferred.handle.alive === false` after return,
+so a runtime owns only each deferred's resolve/reject. `dispose()` is idempotent and runs on every
+terminal transition, in order: unsettled deferreds, the top-level promise handle, the helper
+handles, the context, the runtime. Leak test: 1,000 × (start a script suspended on 3 deferreds and
+a pending top promise → dispose → run a new script) in one module: 367 ms, no error, not poisoned,
+0 live after. A wasm trap or a library lifetime error anywhere poisons the module: every runtime in
+it is abandoned (handles dropped, never disposed), its records go `lost`, and the next script loads
+a fresh module.
+
+**The per-runtime memory limit does NOT bound wasm memory (measured).** Under a 32 MiB
+`setMemoryLimit`, `a.push("x".repeat(1024) + a.length)` grew the module's linear memory to the
+2048 MiB wasm maximum in 3.8 s before QuickJS reported out of memory; `a.push({i})` reached
+143 MiB. Linear memory never shrinks. So the interrupt handler also checks the module's
+`HEAPU8.byteLength` (private, guarded; a module where it reads 0 logs once that the ceilings are
+off) against `WASM_CEILING_BYTES = 256 MiB`, two ways:
+
+- a slice past the ceiling that grew the module by MORE than its own heap limit is stopped (`out of
+ memory: the script grew the sandbox's memory past claudish's limit`) — the runaway signature: the
+ string-push loop grew it 282 MiB in one slice;
+- after EVERY slice, a module over the ceiling is retired with no script blamed. Scripts that each
+ stay inside their heap limit still add up, and result delivery grows memory from the host,
+ outside any interrupt check (measured: 31 suspended scripts each holding 8 × 1 MiB results, the
+ per-script result cap, took the module to 298 MiB with no slice stopped). Blaming the slice that
+ happened to cross failed an innocent script (measured: a script allocating 56 MiB within a 64 MiB
+ heap, beside 26 holders at 248 MiB, failed "out of memory"; now it completes).
+
+Retiring admits no new script and evicts every SUSPENDED runtime in the module at once (its record
+goes `lost`; replay re-runs it in the next module, which 5r loads first: `needs-module`), because a
+suspended runtime holds the whole module and may wait on Claude Code for hours. Live cap × heap
+limit (32 × 32 MiB) is deliberately NOT sized under the ceiling: the heap limit does not bound
+linear memory (one runaway alone reached 298 MiB under it), so no product of the two is a bound,
+and lowering either would refuse legitimate scripts (the 8 MiB result budget needs the heap). The
+ceiling plus retire-and-replay is the bound; what it costs a holder is one replay. An idle module
+over 256 MiB is dropped for reload when its last runtime ends. The per-module ceiling is a
+per-process one with no separate gate: a retired module never outlives the slice that retired it
+(retire evicts every suspended runtime; the running one releases the module when its slice ends;
+measured: the old lease holds 0 live runtimes right after), so only the current module is ever
+alive when a new script is admitted. 256 MiB, not the 1 GiB first shipped: linear memory never
+shrinks, so whatever one runaway script reaches stays resident until the module is dropped.
+
+**Settlement after every slice.** The top-level promise is read FIRST: fulfilled, or rejected with
+the `exit()` sentinel → completed, and every outstanding call is DISCARDED (in claudish an unawaited
+call never runs; in Codex it may already have run); rejected otherwise → failed; pending with calls
+created in this slice → blocked; pending with none → failed (`deadlocked: the script awaits a
+promise that can never settle`). `blocked([])` is unrepresentable.
+
+| Limit (claudish policy, model-independent) | Value | When exceeded |
+|---|---|---|
+| QuickJS heap per runtime | 32 MiB | `failed` (out of memory) |
+| CPU per script, cumulative across slices | 2 s | `failed` (`interrupted: exceeded the 2 s CPU budget`) |
+| wasm linear memory per module (the only module alive at admission) | 256 MiB | a slice that grew it past by more than its heap limit: stopped; any slice ending over it: module retired, its suspended scripts lost and replayed |
+| source | 256 KB | `failed` before running |
+| calls per batch / per script | 32 / 256 | the excess call rejects with a string, so `Promise.allSettled` still finishes |
+| one call input / one batch | 2 MiB / 8 MiB | that call rejects |
+| tool result into the script | 1 MiB each (truncated, marked) / 8 MiB per script | rejects |
+| `text()` output | 1,048,576 characters (UTF-16 code units, not bytes) per exec, enforced by the HOST on what it receives (a tampered prelude can waste one bounded copy, never raise the total); `text("")` adds no part; ≤ 1,024 parts (the store counts 64 bytes per part) | dropped, with a warning line; past 1,024 parts, text joins the last part |
+| output tokens | `max_output_tokens` pragma clamped to [1, 50,000]; default discovery's `truncation_policy.limit` in tokens, else 10,000 | Codex's truncation header, at 4 B/token |
+
+Why 32 MiB and 2 s: the heap limit stops one runtime's ordinary allocations; it bounds nothing
+process-wide (above), which is the wasm ceilings' job. The interrupt handler can only TERMINATE a slice, never yield it (R2 §2:
+`InternalError: interrupted`, 202 ms against a 200 ms budget), so the cumulative CPU budget is also
+the longest one script can block the event loop, and 2 s keeps one script from pausing every
+stream of a `serve` process for longer. Orchestration scripts need milliseconds. Neither value was
+tuned against a measured script workload; a worker thread is the alternative if real logs show
+CPU-heavy scripts.
+
+**Isolation.** QuickJS built-ins plus four globals (`text`, `exit`, `tools`, `ALL_TOOLS`), the host
+bridge closure-only behind a prelude that captures every intrinsic it uses at load (a script that
+overwrites `String.prototype.slice`, `Reflect.apply` or `Function.prototype.call` cannot alter the
+bridge). `SharedArrayBuffer`, `Atomics`, `WeakRef`, `FinalizationRegistry` deleted; no `console`
+(as Codex); `Date` kept; `Math.random` seeded from the exec call id. Every effect goes through
+`tools.*` → a `tool_use` block → Claude Code's permissions. Script errors are data: `Script failed`
+with `Script error:` and the stack (line numbers mapped back to the model's input), returned to the
+model, never an HTTP error.
+
+## Not proven yet
+
+- Not run live in Phase 7: a mixed classic → code-mode history after `claude --resume`, and Esc
+ on a nested permission prompt. `openai@` was BLOCKED (V3: the account had no credits); gate 3
+ keeps the api-key arm out of code mode whatever the setting.
+- Reasoning replayed before a first nested call after a switch to non-code-mode (remembered under
+ `toolu_cx_<hex>_0`, the A3 `_p0` rule) was never observed live.
+- A login without a ChatGPT account id never gets code mode; if real logins lack it, a fallback
+ identity is a follow-up, not a guess.
+- `console is not defined` failures are counted in Phase 7; the model is trained on Codex's
+ `exec_command` object and gets Claude Code's `Bash` string.
diff --cc packages/cli/src/child-auth-types.ts
index 00000000,00000000..7e5bc290
new file mode 100644
--- /dev/null
+++ b/packages/cli/src/child-auth-types.ts
@@@ -1,0 -1,0 +1,58 @@@
++/**
++ * The types of `childAuthControl` (claude-runner.ts): whether claudish controls
++ * the child's Anthropic auth on this launch. Kept free of imports so a handler
++ * that takes the decision does not load the launcher. The decision itself is
++ * made in claude-runner.ts.
++ */
++
++/**
++ * A credential source, other than Claude Code's own claude.ai login, that this
++ * launch lets the child authenticate with. Names only; no value is ever kept.
++ *
++ * - `proxy-auth`: the child gets claudish's placeholder pair, so no login
++ * reaches the proxy at all.
++ * - `user-auth-token`: the user's own ANTHROPIC_AUTH_TOKEN stays in the child
++ * env (the native-mapping branch keeps it); Claude Code sends it as a bearer.
++ * - `user-api-key`: a real ANTHROPIC_API_KEY stays in the child env (sent as
++ * `x-api-key`).
++ * - `settings-auth-token` / `settings-api-key`: a Claude Code settings file
++ * sets that variable in its `env` block, which claudish's env builder never
++ * sees and cannot remove.
++ * - `api-key-helper`: a settings file names an `apiKeyHelper`; Claude Code
++ * sends its output as a bearer AND as `x-api-key`.
++ * - `custom-headers`: ANTHROPIC_CUSTOM_HEADERS (the environment or a settings
++ * `env` block) carries an `Authorization` or `x-api-key` header.
++ * - `settings-unreadable`: a `--settings` value the child receives verbatim
++ * could not be read or parsed by claudish, so what it sets is unknown.
++ * Unknown provenance is never treated as controlled.
++ */
++export type ChildAuthSource =
++ | "proxy-auth"
++ | "user-auth-token"
++ | "user-api-key"
++ | "settings-auth-token"
++ | "settings-api-key"
++ | "api-key-helper"
++ | "custom-headers"
++ | "settings-unreadable";
++
++/**
++ * Whether claudish controls the child's Anthropic auth, so that a bearer
++ * arriving at the proxy can only be Claude Code's own claude.ai login.
++ * `where` names the source (`environment`, or the settings file's path),
++ * never a value.
++ */
++export type ChildAuthControl =
++ | { controlled: true }
++ | {
++ controlled: false;
++ reason: ChildAuthSource;
++ where: string;
++ /**
++ * `custom-headers` only: whether the headers set `x-api-key`, so Claude
++ * Code itself sends a real key the advisor can sign with. False when they
++ * set only `Authorization`, whose bearer the advisor never uses on an
++ * uncontrolled launch.
++ */
++ sendsApiKey?: boolean;
++ };
diff --cc packages/cli/src/claude-runner-auth-control.test.ts
index 170e1e5c,00000000..2607c97e
mode 100644,000000..100644
--- a/packages/cli/src/claude-runner-auth-control.test.ts
+++ b/packages/cli/src/claude-runner-auth-control.test.ts
@@@ -1,218 -1,0 +1,223 @@@
+import { beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ChildAuthControlDeps } from "./claude-runner.js";
+import type { ClaudishConfig } from "./types.js";
+
+const FILE = import.meta.path;
+const TIMEOUT = 20_000;
+
+if (process.env.T4_ISOLATED_FILE !== FILE) {
+ test(
+ "T4 G1 runs with an isolated HOME and no inherited credentials",
+ async () => {
+ const home = mkdtempSync(join(tmpdir(), "t4-auth-control-"));
+ const env = { ...process.env };
+ for (const key of Object.keys(env)) {
+ if (/^(ANTHROPIC|CLAUDE|CLAUDISH|OPENAI|OP_)/.test(key)) delete env[key];
+ }
+ const child = Bun.spawn([process.execPath, "test", FILE], {
+ cwd: home,
+ env: {
+ ...env,
+ HOME: home,
+ CLAUDE_CONFIG_DIR: join(home, "claude"),
+ T4_ISOLATED_FILE: FILE,
+ },
+ stdin: "ignore",
+ stdout: "pipe",
+ stderr: "pipe",
+ });
+ try {
+ const [code, stdout, stderr] = await Promise.all([
+ child.exited,
+ new Response(child.stdout).text(),
+ new Response(child.stderr).text(),
+ ]);
+ console.info(stdout + stderr);
+ expect(code).toBe(0);
+ } finally {
+ child.kill();
+ rmSync(home, { recursive: true, force: true });
+ }
+ },
+ TIMEOUT
+ );
+} else {
+ let childAuthControl: typeof import("./claude-runner.js").childAuthControl;
+ let placeholder: string;
+ const cwd = join(process.env.HOME!, "project");
+ const settingsPath = join(cwd, "auth-settings.json");
+ const firstPath = join(cwd, "first-settings.json");
+ const token = "OPAQUE_TEST_TOKEN_abc";
+ const config = (overrides: Partial<ClaudishConfig> = {}): ClaudishConfig => ({
+ autoApprove: false,
+ dangerous: false,
+ interactive: false,
+ debug: false,
+ logLevel: "minimal",
+ quiet: true,
+ jsonOutput: false,
+ monitor: false,
+ stdin: false,
+ noLogs: true,
+ diagMode: "off",
+ claudeArgs: [],
+ advisor: true,
+ // A native role mapping forwards real auth rather than a foreign-model placeholder.
+ model: "cx@t4-structural-model",
+ modelHaiku: "haiku",
+ ...overrides,
+ });
+ const reads = (files: Record<string, unknown> = {}): ChildAuthControlDeps => ({
+ cwd,
+ home: process.env.HOME!,
+ readFile(path) {
+ if (!(path in files)) throw new Error("ENOENT");
+ return JSON.stringify(files[path]);
+ },
+ });
+
+ beforeAll(async () => {
- globalThis.fetch = (() => {
++ // A `data:` URL is not network: claude-runner's import graph reaches
++ // @opentui/core, whose yoga-layout loads its wasm with fetch(data:…).
++ const local = globalThis.fetch;
++ globalThis.fetch = ((input: string | URL | Request, init?: RequestInit) => {
++ const url = input instanceof Request ? input.url : String(input);
++ if (url.startsWith("data:")) return local(input, init);
+ throw new Error("T4 forbids network");
+ }) as unknown as typeof fetch;
+ ({ childAuthControl, CLAUDISH_PLACEHOLDER_AUTH_TOKEN: placeholder } = await import(
+ "./claude-runner.js"
+ ));
+ });
+
+ describe("G1 childAuthControl — A9 and every forwarded --settings", () => {
+ test(
+ "native role mapping without another auth source is controlled",
+ () => {
+ expect(childAuthControl(config(), {}, reads())).toEqual({ controlled: true });
+ },
+ TIMEOUT
+ );
+
+ test(
+ "foreign main model without a native mapping is not controlled",
+ () => {
+ expect(childAuthControl(config({ modelHaiku: undefined }), {}, reads())).toMatchObject({
+ controlled: false,
+ reason: "proxy-auth",
+ });
+ },
+ TIMEOUT
+ );
+
+ test(
+ "a forwarded user token is not controlled, even on a native mapping",
+ () => {
+ const result = childAuthControl(config(), { ANTHROPIC_AUTH_TOKEN: token }, reads());
+ expect(result).toMatchObject({ controlled: false, reason: "user-auth-token" });
+ expect(JSON.stringify(result)).not.toContain(token);
+ },
+ TIMEOUT
+ );
+
+ test(
+ "a claudish placeholder cannot prove the child uses a login",
+ () => {
+ expect(
+ childAuthControl(
+ config({ modelHaiku: undefined }),
+ {
+ ANTHROPIC_AUTH_TOKEN: placeholder,
+ },
+ reads()
+ )
+ ).toMatchObject({ controlled: false, reason: "proxy-auth" });
+ },
+ TIMEOUT
+ );
+
+ for (const [label, value, reason] of [
+ ["token", { env: { ANTHROPIC_AUTH_TOKEN: token } }, "settings-auth-token"],
+ ["apiKeyHelper", { apiKeyHelper: "T4-never-executed-helper" }, "api-key-helper"],
+ ] as const) {
+ for (const [form, args] of [
+ ["two-token path", ["--settings", settingsPath]],
+ ["equals path", [`--settings=${settingsPath}`]],
+ ["second two-token occurrence", ["--settings", firstPath, "--settings", settingsPath]],
+ ["second equals occurrence", ["--settings", firstPath, `--settings=${settingsPath}`]],
+ ["inline JSON", ["--settings", JSON.stringify(value)]],
+ ] as const) {
+ test(
+ `${label} through ${form} is not controlled`,
+ () => {
+ const result = childAuthControl(
+ config({ claudeArgs: [...args] }),
+ {},
+ reads({
+ [firstPath]: { permissions: {} },
+ [settingsPath]: value,
+ })
+ );
+ expect(result).toMatchObject({ controlled: false, reason });
+ expect(JSON.stringify(result)).not.toContain(token);
+ expect(JSON.stringify(result)).not.toContain("T4-never-executed-helper");
+ },
+ TIMEOUT
+ );
+ }
+ }
+
+ test(
+ "an unreadable forwarded equals settings file is not controlled",
+ () => {
+ expect(
+ childAuthControl(config({ claudeArgs: [`--settings=${settingsPath}`] }), {}, reads())
+ ).toMatchObject({ controlled: false, reason: "settings-unreadable" });
+ },
+ TIMEOUT
+ );
+
+ test(
+ "a second unreadable settings file cannot be ignored",
+ () => {
+ expect(
+ childAuthControl(
+ config({
+ claudeArgs: ["--settings", firstPath, "--settings", settingsPath],
+ }),
+ {},
+ reads({ [firstPath]: {} })
+ )
+ ).toMatchObject({ controlled: false, reason: "settings-unreadable" });
+ },
+ TIMEOUT
+ );
+
+ for (const path of [
+ join(process.env.HOME!, ".claude", "settings.json"),
+ join(cwd, ".claude", "settings.json"),
+ join(cwd, ".claude", "settings.local.json"),
+ ]) {
+ test(
+ `a settings-supplied token at ${path} prevents the login promise`,
+ () => {
+ expect(
+ childAuthControl(
+ config(),
+ {},
+ reads({
+ [path]: {
+ env: { ANTHROPIC_AUTH_TOKEN: token },
+ },
+ })
+ )
+ ).toMatchObject({ controlled: false, reason: "settings-auth-token" });
+ },
+ TIMEOUT
+ );
+ }
+ });
+}
diff --cc packages/cli/src/claude-runner-settings-collision.test.ts
index 286c9902,00000000..5d9d4a74
mode 100644,000000..100644
--- a/packages/cli/src/claude-runner-settings-collision.test.ts
+++ b/packages/cli/src/claude-runner-settings-collision.test.ts
@@@ -1,99 -1,0 +1,106 @@@
+import { afterAll, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const home = mkdtempSync(join(tmpdir(), "claudish-settings-collision-"));
+const pinnedNow = 1_720_000_000_000;
+
+interface ChildResult {
+ pid: number;
+ now: number;
+ settings: {
+ path: string;
+ tokenFilePath: string;
+ };
+}
+
+afterAll(() => {
+ rmSync(home, { recursive: true, force: true });
+});
+
+test("keeps settings paths and contents separate across processes in the same millisecond", async () => {
+ const preloadPath = join(home, "pin-time.ts");
+ const workerPath = join(home, "create-settings.ts");
+ const modulePath = join(import.meta.dir, "claude-runner.ts");
+ writeFileSync(
+ preloadPath,
++ // A data: URL is not network: claude-runner's import graph reaches
++ // @opentui/core, whose yoga-layout loads its wasm with fetch(data:…).
+ `Date.now = () => ${pinnedNow};
- globalThis.fetch = () => { throw new Error("Network is forbidden in the settings collision test"); };
++ const localFetch = globalThis.fetch;
++ globalThis.fetch = (input, init) => {
++ const url = input instanceof Request ? input.url : String(input);
++ if (url.startsWith("data:")) return localFetch(input, init);
++ throw new Error("Network is forbidden in the settings collision test");
++ };
+ `
+ );
+ writeFileSync(
+ workerPath,
+ `import { createTempSettingsFile } from ${JSON.stringify(modulePath)};
+ const settings = createTempSettingsFile("settings collision", process.argv[2], true);
+ console.log(JSON.stringify({ pid: process.pid, now: Date.now(), settings }));
+ `
+ );
+
+ const ports = ["41001", "41002"];
+ const children = ports.map((port) =>
+ Bun.spawn([process.execPath, "--preload", preloadPath, workerPath, port], {
+ env: {
+ HOME: home,
+ CLAUDE_CONFIG_DIR: join(home, ".claude"),
+ XDG_CONFIG_HOME: join(home, ".config"),
+ CLAUDISH_DISABLE_KEYCHAIN: "1",
+ CLAUDISH_DISABLE_OP: "1",
+ CLAUDISH_DISABLE_CATALOG_WARM: "1",
+ },
+ stdin: "ignore",
+ stdout: "pipe",
+ stderr: "pipe",
+ })
+ );
+ const timeout = setTimeout(() => {
+ for (const child of children) child.kill();
+ }, 15_000);
+
+ const outputs = await (async () => {
+ try {
+ return await Promise.all(
+ children.map(async (child) => {
+ const [stdout, stderr, exitCode] = await Promise.all([
+ new Response(child.stdout).text(),
+ new Response(child.stderr).text(),
+ child.exited,
+ ]);
+ return { stdout, stderr, exitCode };
+ })
+ );
+ } finally {
+ clearTimeout(timeout);
+ for (const child of children) {
+ if (child.exitCode === null) child.kill();
+ }
+ await Promise.all(children.map((child) => child.exited));
+ }
+ })();
+
+ const results = outputs.map(({ stdout, stderr, exitCode }) => {
+ expect(exitCode, stderr).toBe(0);
+ return JSON.parse(stdout) as ChildResult;
+ });
+ const [first, second] = results;
+ expect(first.pid).not.toBe(second.pid);
+ expect(first.now).toBe(pinnedNow);
+ expect(second.now).toBe(pinnedNow);
+ expect(first.settings.path).not.toBe(second.settings.path);
+
+ for (const [index, { settings }] of results.entries()) {
+ const otherIndex = 1 - index;
+ expect(existsSync(settings.path)).toBe(true);
+ const content = readFileSync(settings.path, "utf8");
+ expect(content.includes(ports[index]) || content.includes(settings.tokenFilePath)).toBe(true);
+ expect(content).not.toContain(ports[otherIndex]);
+ expect(content).not.toContain(results[otherIndex].settings.tokenFilePath);
+ }
+}, 20_000);
diff --cc packages/cli/src/claude-runner.ts
index e7775faa,0e880327..49103108
--- a/packages/cli/src/claude-runner.ts
+++ b/packages/cli/src/claude-runner.ts
@@@ -15,8 -19,18 +19,19 @@@ import { homedir, tmpdir } from "node:o
import { dirname, join } from "node:path";
import { isatty } from "node:tty";
import { lookupModelForProvider } from "./adapters/model-catalog.js";
++import type { ChildAuthControl, ChildAuthSource } from "./child-auth-types.js";
import { classifierPassthroughEnabled } from "./classifier-passthrough.js";
import { ENV } from "./config.js";
+ import { getHookEngine } from "./hooks/index.js";
+ import { InProcessSink, setProcessSink } from "./hooks/injection/sinks.js";
+ import { sessionHooksNeedBinding } from "./hooks/session/binding.js";
+ import { InteractiveDriver } from "./hooks/session/interactive-driver.js";
+ import {
+ driverLeadingArgs,
+ planInteractiveSurfaces,
+ sessionFlagsOf,
+ } from "./hooks/session/interactive-launch.js";
+ import { type NoSurfaceSession, startNoSurfaceSession } from "./hooks/session/no-surface.js";
import {
STRIPPED_CHILD_VARS,
magmuxPaneCapability,
@@@ -313,278 -349,6 +350,231 @@@ export function isProxyAuthMode(config
return !config.monitor && !isAdvisorNativeSession(config) && !shouldPreserveNativeAuth(config);
}
- /**
- * A credential source, other than Claude Code's own claude.ai login, that this
- * launch lets the child authenticate with. Names only; no value is ever kept.
- *
- * - `proxy-auth`: the child gets claudish's placeholder pair, so no login
- * reaches the proxy at all.
- * - `user-auth-token`: the user's own ANTHROPIC_AUTH_TOKEN stays in the child
- * env (the native-mapping branch keeps it); Claude Code sends it as a bearer.
- * - `user-api-key`: a real ANTHROPIC_API_KEY stays in the child env (sent as
- * `x-api-key`).
- * - `settings-auth-token` / `settings-api-key`: a Claude Code settings file
- * sets that variable in its `env` block, which claudish's env builder never
- * sees and cannot remove.
- * - `api-key-helper`: a settings file names an `apiKeyHelper`; Claude Code
- * sends its output as a bearer AND as `x-api-key`.
- * - `custom-headers`: ANTHROPIC_CUSTOM_HEADERS (the environment or a settings
- * `env` block) carries an `Authorization` or `x-api-key` header.
- * - `settings-unreadable`: a `--settings` value the child receives verbatim
- * could not be read or parsed by claudish, so what it sets is unknown.
- * Unknown provenance is never treated as controlled.
- */
- export type ChildAuthSource =
- | "proxy-auth"
- | "user-auth-token"
- | "user-api-key"
- | "settings-auth-token"
- | "settings-api-key"
- | "api-key-helper"
- | "custom-headers"
- | "settings-unreadable";
-
- /**
- * Whether claudish controls the child's Anthropic auth, so that a bearer
- * arriving at the proxy can only be Claude Code's own claude.ai login.
- * `where` names the source (`environment`, or the settings file's path),
- * never a value.
- */
- export type ChildAuthControl =
- | { controlled: true }
- | {
- controlled: false;
- reason: ChildAuthSource;
- where: string;
- /**
- * `custom-headers` only: whether the headers set `x-api-key`, so Claude
- * Code itself sends a real key the advisor can sign with. False when they
- * set only `Authorization`, whose bearer the advisor never uses on an
- * uncontrolled launch.
- */
- sendsApiKey?: boolean;
- };
++// The decision's types live in a module with no imports, so the advisor
++// handlers that take a decision do not pull this launcher (and through it the
++// pane launcher and cli.ts) into every program that imports a handler.
++export type { ChildAuthControl, ChildAuthSource } from "./child-auth-types.js";
+
+/** Injectable reads for {@link childAuthControl}; defaults read the real files. */
+export interface ChildAuthControlDeps {
+ readFile?: (path: string) => string;
+ cwd?: string;
+ home?: string;
+}
+
+/**
+ * Does claudish itself control the child's Anthropic auth on this launch?
+ *
+ * The advisor may sign its own Claude call with the bearer Claude Code sends
+ * only when that bearer can be nothing but Claude Code's claude.ai login. The
+ * request cannot prove it: the `oauth-2025-04-20` beta that login requests
+ * carry is client-declared (`ANTHROPIC_BETAS` adds it to any bearer) and the
+ * server does not require it (measured 2026-10-21, S0). So the decision is
+ * made HERE, at launch, from what this launch hands the child, and every other
+ * launch keeps the bearer off the advisor path.
+ *
+ * Controlled only when ALL hold, as far as claudish can see before spawning:
+ * 1. a native-auth launch (`isProxyAuthMode` false), so no placeholder pair;
+ * 2. no user ANTHROPIC_AUTH_TOKEN and no real ANTHROPIC_API_KEY reaches the
+ * child. The monitor / no-model `--advisor` branch deletes both
+ * (`runClaudeWithProxy`, "Handle API key and model based on mode"); the
+ * native-mapping branch scrubs only claudish's placeholders, keeps a
+ * user's token, and hides an API key only per
+ * `shouldHideIncidentalAnthropicKey`;
+ * 3. ANTHROPIC_CUSTOM_HEADERS carries no auth header;
+ * 4. no Claude Code settings layer claudish can read — managed settings, the
+ * user file (and `$CLAUDE_CONFIG_DIR/settings.json`), the project and
+ * project-local files, and every `--settings` value in either spelling —
+ * names an `apiKeyHelper` or sets an Anthropic credential in its `env`
+ * block, and no `--settings` value the child receives is unreadable.
+ *
+ * What it cannot see, and therefore does not claim: settings delivered by a
+ * mechanism claudish does not read (an MDM profile, a file Claude Code adds
+ * later). Mirrors the env builder without editing it: the two must change
+ * together.
+ */
+export function childAuthControl(
+ config: ClaudishConfig,
+ env: NodeJS.ProcessEnv = process.env,
+ deps: ChildAuthControlDeps = {}
+): ChildAuthControl {
+ if (isProxyAuthMode(config)) {
+ return { controlled: false, reason: "proxy-auth", where: "environment" };
+ }
+ // The shouldPreserveNativeAuth branch keeps what the monitor branch deletes.
+ if (!config.monitor && !isAdvisorNativeSession(config)) {
+ if (isRealAnthropicEnvCredential(env, "ANTHROPIC_AUTH_TOKEN")) {
+ return { controlled: false, reason: "user-auth-token", where: "environment" };
+ }
+ if (
+ isRealAnthropicEnvCredential(env, "ANTHROPIC_API_KEY") &&
+ !shouldHideIncidentalAnthropicKey(config, env)
+ ) {
+ return { controlled: false, reason: "user-api-key", where: "environment" };
+ }
+ }
+ if (customHeadersCarryAuth(env.ANTHROPIC_CUSTOM_HEADERS)) {
+ return {
+ controlled: false,
+ reason: "custom-headers",
+ where: "environment",
+ sendsApiKey: customHeaderAuthNames(env.ANTHROPIC_CUSTOM_HEADERS).has("x-api-key"),
+ };
+ }
+ for (const { where, settings } of readableClaudeSettingsLayers(config, env, deps)) {
+ const reason = settings === null ? "settings-unreadable" : settingsAuthSource(settings);
+ if (reason === "custom-headers" && settings) {
+ const sendsApiKey = customHeaderAuthNames(settingsCustomHeaders(settings)).has("x-api-key");
+ return { controlled: false, reason, where, sendsApiKey };
+ }
+ if (reason) return { controlled: false, reason, where };
+ }
+ return { controlled: true };
+}
+
+/** One `--settings` occurrence in the passthrough args, in either spelling. */
+interface SettingsArgOccurrence {
+ /** Index of the flag token in the args. */
+ index: number;
+ /** The value; undefined when the flag is the last token. */
+ value: string | undefined;
+ /** `separate` = `--settings <v>` (two tokens); `inline` = `--settings=<v>`. */
+ spelling: "separate" | "inline";
+}
+
+/**
+ * Every `--settings` occurrence in argv order, in both spellings Claude Code
+ * accepts. `--settings=<v>` is split on the first `=` only, so a value that
+ * itself contains `=` survives.
+ */
+function settingsArgOccurrences(args: readonly string[]): SettingsArgOccurrence[] {
+ const out: SettingsArgOccurrence[] = [];
+ for (let index = 0; index < args.length; index++) {
+ const token = args[index];
+ if (token === "--settings") {
+ out.push({ index, value: args[index + 1], spelling: "separate" });
+ index++; // the next token is this flag's value, never a flag of its own
+ } else if (token.startsWith("--settings=")) {
+ out.push({ index, value: token.slice("--settings=".length), spelling: "inline" });
+ }
+ }
+ return out;
+}
+
+/** The auth header names (lowercase) an ANTHROPIC_CUSTOM_HEADERS value (one `Name: value` per line) sets. */
+function customHeaderAuthNames(value: unknown): Set<"authorization" | "x-api-key"> {
+ const names = new Set<"authorization" | "x-api-key">();
+ if (typeof value !== "string" || !value) return names;
+ for (const line of value.split(/\r?\n/)) {
+ const colon = line.indexOf(":");
+ if (colon <= 0) continue;
+ const name = line.slice(0, colon).trim().toLowerCase();
+ if (name === "authorization" || name === "x-api-key") names.add(name);
+ }
+ return names;
+}
+
+/** True when an ANTHROPIC_CUSTOM_HEADERS value sets an auth header. */
+function customHeadersCarryAuth(value: unknown): boolean {
+ return customHeaderAuthNames(value).size > 0;
+}
+
+/** The `ANTHROPIC_CUSTOM_HEADERS` a settings object's `env` block sets, if any. */
+function settingsCustomHeaders(settings: Record<string, unknown>): unknown {
+ return settings.env && typeof settings.env === "object"
+ ? (settings.env as Record<string, unknown>).ANTHROPIC_CUSTOM_HEADERS
+ : undefined;
+}
+
+/** The non-login credential source one settings object declares, or null. */
+function settingsAuthSource(settings: Record<string, unknown>): ChildAuthSource | null {
+ const env =
+ settings.env && typeof settings.env === "object"
+ ? (settings.env as Record<string, unknown>)
+ : {};
+ const realValue = (name: "ANTHROPIC_AUTH_TOKEN" | "ANTHROPIC_API_KEY"): boolean => {
+ const value = env[name];
+ return (
+ typeof value === "string" &&
+ value.trim().length > 0 &&
+ !isClaudishPlaceholderCredential(name, value)
+ );
+ };
+ if (realValue("ANTHROPIC_AUTH_TOKEN")) return "settings-auth-token";
+ if (typeof settings.apiKeyHelper === "string" && settings.apiKeyHelper.trim()) {
+ return "api-key-helper";
+ }
+ if (realValue("ANTHROPIC_API_KEY")) return "settings-api-key";
+ if (customHeadersCarryAuth(env.ANTHROPIC_CUSTOM_HEADERS)) return "custom-headers";
+ return null;
+}
+
+/**
+ * Every Claude Code settings layer claudish can read for this launch, parsed.
+ * A missing, unreadable or malformed settings FILE is skipped (Claude Code does
+ * not apply a file it cannot parse either). `where` is the path, or `--settings`.
+ *
+ * `--settings` values follow the launcher exactly (`runClaudeWithProxy`):
+ * `mergeUserSettingsIfPresent` takes only the FIRST two-token `--settings <v>`
+ * (`indexOf`), merges it into claudish's temp file and splices it out — when it
+ * cannot be parsed it is dropped, so the child never sees it and it is skipped
+ * here too. Every other occurrence (a later `--settings <v>`, any
+ * `--settings=<v>`) is forwarded to the child verbatim with the passthrough
+ * args, so each one is inspected, and one claudish cannot read or parse is
+ * returned with `settings: null` — the child may still apply it, and unknown
+ * provenance never counts as controlled (A1).
+ */
+function readableClaudeSettingsLayers(
+ config: ClaudishConfig,
+ env: NodeJS.ProcessEnv,
+ deps: ChildAuthControlDeps
+): Array<{ where: string; settings: Record<string, unknown> | null }> {
+ const readFile = deps.readFile ?? ((path: string) => readFileSync(path, "utf-8"));
+ const home = deps.home ?? homedir();
+ const cwd = deps.cwd ?? process.cwd();
+ const files = [
+ managedSettingsPath(),
+ join(home, ".claude", "settings.json"),
+ ...(env.CLAUDE_CONFIG_DIR ? [join(env.CLAUDE_CONFIG_DIR, "settings.json")] : []),
+ join(cwd, ".claude", "settings.json"),
+ join(cwd, ".claude", "settings.local.json"),
+ ];
+ const layers: Array<{ where: string; settings: Record<string, unknown> | null }> = [];
+ for (const file of files) {
+ const settings = readSettingsSource(file, readFile);
+ if (settings) layers.push({ where: file, settings });
+ }
+ const occurrences = settingsArgOccurrences(config.claudeArgs ?? []);
+ const merged = occurrences.find((o) => o.spelling === "separate");
+ occurrences.forEach((occurrence, i) => {
+ // `where` never carries the value: an inline `--settings` may hold a secret.
+ const where = occurrences.length > 1 ? `--settings (occurrence ${i + 1})` : "--settings";
+ // Merge's own guard: a missing or empty value is neither merged nor read.
+ if (!occurrence.value) return;
+ const settings = readSettingsSource(occurrence.value, readFile);
+ if (occurrence === merged && !settings) return; // dropped by the merge
+ layers.push({ where, settings });
+ });
+ return layers;
+}
+
+/**
+ * One settings source, parsed: inline JSON (a `--settings` value starting with
+ * `{`) or a file path. Null when it cannot be read or is not a JSON object.
+ */
+function readSettingsSource(
+ source: string,
+ readFile: (path: string) => string
+): Record<string, unknown> | null {
+ try {
+ const raw = source.trimStart().startsWith("{") ? source : readFile(source);
+ const parsed = JSON.parse(raw) as unknown;
+ return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : null;
+ } catch {
+ return null;
+ }
+}
+
/**
* OS-specific path to Claude Code's *managed* settings file — the highest-precedence
* tier, which "cannot be overridden by anything" (not even our --settings overlay).
diff --cc packages/cli/src/cli.ts
index 28df7663,089f72b0..cb2f4f7d
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@@ -50,7 -44,8 +50,13 @@@ import type
ProbeStepState,
} from "./probe/probe-tui-app.js";
import { startProbeTui } from "./probe/probe-tui-runtime.js";
- import { getModelMapping, loadConfig, readCodeMode, readProOnUltracode } from "./profile-config.js";
-import { getRunModelMapping, loadConfig, readProOnUltracode } from "./profile-config.js";
++import {
++ getRunModelMapping,
++ loadConfig,
++ readCodeMode,
++ readProOnUltracode,
++} from "./profile-config.js";
+ import { usableProfileModels } from "./project-models.js";
import { API_KEY_MAP } from "./providers/api-key-map.js";
import { type KeyProvenance, resolveCredentialProvenance } from "./providers/api-key-provenance.js";
import { normalizeNativeModelSpec } from "./providers/claude-code-aliases.js";
diff --cc packages/cli/src/code-mode/exec-tool.ts
index d839b1a5,00000000..ef4436fc
mode 100644,000000..100644
--- a/packages/cli/src/code-mode/exec-tool.ts
+++ b/packages/cli/src/code-mode/exec-tool.ts
@@@ -1,292 -1,0 +1,292 @@@
+/**
+ * The exec tool: ONE freeform custom tool whose input is JavaScript that calls
+ * Claude Code's tools as `tools.<Name>(args)`.
+ *
+ * The definition follows the official Codex client's (R1 §1c,
+ * `evidence/r1/exec-tool.json`): `type: "custom"`, `name: "exec"`, the same
+ * lark grammar (with its optional `// @exec:` first-line pragma), and a
+ * description whose head explains the runtime, followed by one section per
+ * nested tool in Codex's form:
+ *
+ * ### `Name`
+ * <the tool's description>
+ *
+ * exec tool declaration:
+ * ```ts
+ * declare const tools: { Name(args: {…}): Promise<string>; };
+ * ```
+ *
+ * The head lists only what claudish's sandbox implements (`text()`, `exit()`,
+ * `tools`, `ALL_TOOLS`); Codex's `image()`, `store()`, `notify()`, timers and
+ * yield are absent, so the model is never told about a helper that would throw.
+ *
- * Sections are rendered from `claudeRequest.tools` AFTER Layer 4 (step 3c) has
++ * Sections are rendered from `claudeRequest.tools` AFTER the hook request stages (1a, 3a) have
+ * rewritten descriptions, so names are Claude Code's own, never the step-5
+ * encoded names. A size budget keeps the description bounded on sessions with
+ * many MCP tools: a section is at most `perToolBytes` (its description is cut to
+ * fit; the full text stays in `ALL_TOOLS`), sections are added in Claude Code's
+ * order up to `totalBytes`, and the rest are listed as deferred tools by name
+ * and first sentence. Every tool stays callable either way.
+ */
+
+import { log } from "../logger.js";
+import { schemaToTs } from "./schema-to-ts.js";
+import { ToolNameTable, normalizeToolIdent } from "./tool-names.js";
+
+/** The exec tool's grammar, verbatim from the Codex client's definition. */
+export const EXEC_TOOL_GRAMMAR =
+ "\nstart: pragma_source | plain_source\npragma_source: PRAGMA_LINE NEWLINE SOURCE\nplain_source: SOURCE\n\nPRAGMA_LINE: /[ \\t]*\\/\\/ @exec:[^\\r\\n]*/\nNEWLINE: /\\r?\\n/\nSOURCE: /[\\s\\S]+/\n";
+
+/** The exec tool's name on the wire. */
+export const EXEC_TOOL_NAME = "exec";
+
+/**
+ * The output budget the exec description states when discovery publishes no
+ * token truncation policy: the protocol default the Codex exec description
+ * itself states ("Defaults to 10000 tokens"). A rule, not model data.
+ */
+export const DEFAULT_EXEC_MAX_OUTPUT_TOKENS = 10_000;
+
+/** Description size limits (claudish policy; UTF-8 bytes). */
+export interface ExecToolBudget {
+ /** One nested tool's section, heading to closing fence. */
+ perToolBytes: number;
+ /** Every rendered section together. */
+ totalBytes: number;
+}
+
+export const DEFAULT_EXEC_TOOL_BUDGET: ExecToolBudget = {
+ perToolBytes: 6 * 1024,
+ totalBytes: 48 * 1024,
+};
+
+/** The Responses custom tool definition sent upstream. */
+export interface ExecToolDefinition {
+ type: "custom";
+ name: typeof EXEC_TOOL_NAME;
+ description: string;
+ format: { type: "grammar"; syntax: "lark"; definition: string };
+}
+
+/** One entry of the sandbox's `ALL_TOOLS` global. */
+export interface ExecToolMeta {
+ /** The identifier a script calls (`tools[name]`). */
+ name: string;
+ description: string;
+ inputSchema: unknown;
+}
+
+export interface RenderedExecTool {
+ tool: ExecToolDefinition;
+ /** Identifier ↔ Claude Code name for every callable tool. */
+ names: ToolNameTable;
+ /** `ALL_TOOLS`: every callable tool with its full description and schema. */
+ allTools: ExecToolMeta[];
+ /** Claude Code names listed only under "Deferred tools" (over the budget). */
+ deferred: string[];
+}
+
+/** A Claude Code tool as it arrives in `claudeRequest.tools`. */
+export interface ClaudeToolLike {
+ name?: unknown;
+ description?: unknown;
+ input_schema?: unknown;
+}
+
+export interface RenderExecToolOptions {
+ /** The `max_output_tokens` default the description states. Default 10,000. */
+ defaultMaxOutputTokens?: number;
+}
+
+function utf8Bytes(text: string): number {
+ return Buffer.byteLength(text, "utf8");
+}
+
+/** `text` cut to at most `maxBytes` UTF-8 bytes at a line (else character) boundary. */
+function cutToBytes(text: string, maxBytes: number): string {
+ if (maxBytes <= 0) return "";
+ if (utf8Bytes(text) <= maxBytes) return text;
+ let lo = 0;
+ let hi = text.length;
+ while (lo < hi) {
+ const mid = Math.ceil((lo + hi) / 2);
+ if (utf8Bytes(text.slice(0, mid)) <= maxBytes) lo = mid;
+ else hi = mid - 1;
+ }
+ const head = text.slice(0, lo);
+ const nl = head.lastIndexOf("\n");
+ return nl > head.length / 2 ? head.slice(0, nl) : head;
+}
+
+/** The first sentence (or first line) of a description, for the deferred list. */
+function firstSentence(description: string): string {
+ const line = description.trim().split(/\r?\n/)[0] ?? "";
+ const match = /^(.+?[.!?])(\s|$)/.exec(line);
+ const sentence = (match ? match[1] : line).trim();
+ return sentence.length > 200 ? `${sentence.slice(0, 199)}…` : sentence;
+}
+
+function execToolHead(defaultMaxOutputTokens: number): string {
+ return [
+ "Run JavaScript code to orchestrate/compose tool calls",
+ "- Evaluates the provided JavaScript code in a fresh sandbox as the body of an async function, so top-level `await` works.",
+ '- All nested tools are available on the global `tools` object, for example `await tools.Read({ file_path: "/abs/path" })`. Tool names are exposed as normalized JavaScript identifiers.',
+ "- Nested tool methods take an object as their input argument.",
+ "- Nested tools return a string: the tool's result text. A failed or denied call rejects with a string (the tool's error text), so use `Promise.allSettled` to inspect every result.",
+ "- Runs raw JavaScript -- no Node, no file system, no network access, no console, no timers.",
+ "- 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: {"max_output_tokens": 1000}`.',
+ `- \`max_output_tokens\` sets the token budget for direct \`exec\` results. Defaults to ${defaultMaxOutputTokens} tokens.`,
+ "- When the script finishes, nested tool calls it never awaited are discarded and never run.",
+ "",
+ "- Global helpers:",
+ "- `exit()`: Immediately ends the current script successfully (like an early return from the top level).",
+ "- `text(value: string | number | boolean | undefined | null)`: Appends a text item. Non-string values are stringified with `JSON.stringify(...)` when possible.",
+ "- `ALL_TOOLS`: metadata for the enabled nested tools as `{ name, description, inputSchema }` entries.",
+ "",
+ "Batch independent searches and reads in one exec using await Promise.allSettled([...]); inspect every result.",
+ "When calling `exec`, parallelize independent tool calls by awaiting Promises.",
+ ].join("\n");
+}
+
+function renderSection(ident: string, description: string, schema: unknown): string {
+ const declaration = `declare const tools: { ${ident}(args: ${schemaToTs(schema)}): Promise<string>; };`;
+ const body = description.trim();
+ return [
+ `### \`${ident}\``,
+ ...(body ? [body] : []),
+ "",
+ "exec tool declaration:",
+ "```ts",
+ declaration,
+ "```",
+ ].join("\n");
+}
+
+/**
+ * One section within `perToolBytes`: the full description when it fits, else
+ * the description cut to fit with a pointer to `ALL_TOOLS`; undefined when the
+ * declaration alone exceeds the budget (the tool is then deferred).
+ */
+function sectionWithinBudget(
+ ident: string,
+ description: string,
+ schema: unknown,
+ perToolBytes: number
+): string | undefined {
+ const full = renderSection(ident, description, schema);
+ if (utf8Bytes(full) <= perToolBytes) return full;
+ const bare = renderSection(ident, "", schema);
+ const marker = "\n[description shortened; the full text is in ALL_TOOLS]";
+ const room = perToolBytes - utf8Bytes(bare) - utf8Bytes(marker) - 1;
+ if (room < 0) return undefined;
+ const cut = cutToBytes(description.trim(), room);
+ return renderSection(ident, cut ? `${cut}${marker}` : marker.trim(), schema);
+}
+
+/** The "Deferred tools" list: identifier and first sentence of each. */
+function deferredSection(
+ deferred: readonly string[],
+ names: ToolNameTable,
+ allTools: readonly ExecToolMeta[]
+): string {
+ const lines = deferred.map((name) => {
+ const ident = names.identFor(name) ?? name;
+ const meta = allTools.find((m) => m.name === ident);
+ const sentence = firstSentence(meta?.description ?? "");
+ return sentence ? `- \`${ident}\` — ${sentence}` : `- \`${ident}\``;
+ });
+ return `### Deferred tools\n${lines.join("\n")}`;
+}
+
+/**
+ * Every callable tool's `ALL_TOOLS` entry, the sections that fit the budget,
+ * and the names deferred past it.
+ */
+function layOutSections(
+ named: ReadonlyArray<ClaudeToolLike & { name: string }>,
+ names: ToolNameTable,
+ limits: ExecToolBudget
+): { sections: string[]; deferred: string[]; allTools: ExecToolMeta[] } {
+ const sections: string[] = [];
+ const deferred: string[] = [];
+ // One entry per kept table name (a repeated name or a skipped collision is not callable).
+ const seen = new Set<string>();
+ const callable = named.filter((tool) => {
+ if (seen.has(tool.name) || names.identFor(tool.name) === undefined) return false;
+ seen.add(tool.name);
+ return true;
+ });
+ const allTools: ExecToolMeta[] = callable.map((tool) => ({
+ name: names.identFor(tool.name) ?? normalizeToolIdent(tool.name),
+ description: typeof tool.description === "string" ? tool.description : "",
+ inputSchema: tool.input_schema ?? {},
+ }));
+ let used = 0;
+ let overflowed = false;
+
+ for (const [i, tool] of callable.entries()) {
+ const { name: ident, description, inputSchema } = allTools[i];
+ const section = overflowed
+ ? undefined
+ : sectionWithinBudget(ident, description, inputSchema, limits.perToolBytes);
+ const size = section === undefined ? 0 : utf8Bytes(section) + 2;
+ if (section === undefined || used + size > limits.totalBytes) {
+ // Claude Code's order is kept: once one section does not fit the total,
+ // every later tool is deferred too. A tool whose declaration alone
+ // exceeds the per-tool budget is deferred on its own.
+ if (section !== undefined) overflowed = true;
+ deferred.push(tool.name);
+ continue;
+ }
+ sections.push(section);
+ used += size;
+ }
+ return { sections, deferred, allTools };
+}
+
+/**
+ * The exec tool for `tools` (Claude Code's tool list, in its order).
+ *
+ * Tools without a string name are ignored; a name whose identifier collides
+ * with an earlier one is skipped (logged by `ToolNameTable`) and not callable.
+ */
+export function renderExecTool(
+ tools: readonly ClaudeToolLike[],
+ budget: Partial<ExecToolBudget> = {},
+ options: RenderExecToolOptions = {}
+): RenderedExecTool {
+ const limits: ExecToolBudget = { ...DEFAULT_EXEC_TOOL_BUDGET, ...budget };
+ const defaultMaxOutputTokens = options.defaultMaxOutputTokens ?? DEFAULT_EXEC_MAX_OUTPUT_TOKENS;
+ const named = tools.filter(
+ (t): t is ClaudeToolLike & { name: string } => typeof t?.name === "string" && t.name !== ""
+ );
+ const names = new ToolNameTable(named.map((t) => t.name));
+ const { sections, deferred, allTools } = layOutSections(named, names, limits);
+
+ const parts = [execToolHead(defaultMaxOutputTokens)];
+ if (deferred.length > 0) {
+ parts.push(
+ "Some deferred nested tools are omitted from this description. They are still available on the global `tools` object and listed in `ALL_TOOLS`.\nTo find one, filter `ALL_TOOLS` by `name` and `description`."
+ );
+ }
+ parts.push(...sections);
+ if (deferred.length > 0) {
+ parts.push(deferredSection(deferred, names, allTools));
+ log(
+ `[CodeMode] exec tool: ${sections.length} tool(s) described, ${deferred.length} deferred over the ${limits.totalBytes}-byte budget`
+ );
+ }
+
+ return {
+ tool: {
+ type: "custom",
+ name: EXEC_TOOL_NAME,
+ description: parts.join("\n\n"),
+ format: { type: "grammar", syntax: "lark", definition: EXEC_TOOL_GRAMMAR },
+ },
+ names,
+ allTools,
+ deferred,
+ };
+}
diff --cc packages/cli/src/code-mode/input-builder.ts
index 2dd9d2c4,00000000..2e00649d
mode 100644,000000..100644
--- a/packages/cli/src/code-mode/input-builder.ts
+++ b/packages/cli/src/code-mode/input-builder.ts
@@@ -1,606 -1,0 +1,606 @@@
+/**
+ * The Responses `input` of a code-mode request, built straight from Claude
+ * Code's `claudeRequest.messages` — never from the step-3 conversion, which is
+ * lossy for this purpose: it lifts tool_result images into separate messages,
+ * synthesizes results for unanswered calls, joins assistant text blocks, and
+ * knows nothing of exec scripts.
+ *
+ * Walk, in order (architecture §5.10):
+ * - assistant message: its turn record's items verbatim when one exists (how
+ * interstitial execs and multi-leg text come back in order), else its text
+ * blocks as one `output_text` message each; then the exec groups it starts.
+ * Thinking blocks are not sent (reasoning travels as encrypted items).
+ * - exec group (the nested tool_uses whose ids decode to one exec, across every
+ * round trip of that script): the exec's reasoning items and its
+ * `custom_tool_call` ONCE, at its first round; its `custom_tool_call_output`
+ * ONCE, after the round that completed it, looked up by completion key. A
+ * script whose record is gone is reconstructed from history: an evicted one
+ * or one lost to a restart renders `Script completed` with a note saying
+ * which, never `Script failed` for a script that resolved in the past —
+ * but only when its last round's results all arrived. Results Claude Code
+ * marked `[Tool call interrupted` (the session ended) render `Script
+ * terminated`; a missing one renders `Script terminated`, outcome unknown.
+ * - user message: text and images as `input_text` / `input_image`; text beside
+ * tool results goes AFTER the outputs they sit beside, in arrival order.
+ * - orphan tool_result (its call is in no earlier assistant message, e.g.
+ * compaction removed it): rendered as user text `[Tool Result]: <text>` with
+ * its images after it, as the step-3 converter does; never dropped.
+ * - classic tool round (ids that do not decode: a session that started classic,
+ * a `/model` switch, parallel-wrapper `_p<k>` ids, a stray classic call):
+ * transliterated into ONE synthetic exec (`transliterate.ts`) — the call at
+ * the assistant message, its `Script completed` output after the message
+ * that answers it — so a request never mixes classic `function_call` items
+ * with the exec tool.
+ *
+ * Two sets keep the once-only rules mechanical for the whole walk: emitted
+ * `call_id`s and emitted reasoning (by item id, else the sha256 of its
+ * `encrypted_content`). Output is byte-identical for byte-identical history
+ * and store state, so the prompt-cache prefix is stable; the eviction
+ * renderings are pure functions of history plus the eviction sets, so the
+ * prefix changes once, on the first request after an eviction.
+ */
+
+import { createHash } from "node:crypto";
+import { log } from "../logger.js";
+import { DEFAULT_EXEC_MAX_OUTPUT_TOKENS, EXEC_TOOL_NAME } from "./exec-tool.js";
+import { type BatchResultEntry, batchHash, completionKey } from "./hashes.js";
+import { decodeNestedId } from "./ids.js";
+import {
+ type ExecOutput,
+ type ImageRef,
+ type OutputPart,
+ type ResponsesOutputPart,
+ formatExecOutput,
+} from "./output.js";
+import type { CodeModeStores } from "./stores.js";
+import { type ToolNameTable, normalizeToolIdent } from "./tool-names.js";
+import {
+ imageUrlOf,
+ isSessionEndedResult,
+ toolResultImages,
+ toolResultText,
+} from "./tool-results.js";
+import { transliterateRound } from "./transliterate.js";
+import { turnAnchorFor } from "./turn-records.js";
+import {
+ type ClaudeContentBlock,
+ type ClaudeMessage,
+ type ResponsesItem,
+ conversationMessages,
+} from "./types.js";
+
+/** Whose records a request may read. */
+export interface CodeModeKeys {
+ accountKey: string;
+ sessionKey: string;
+}
+
+export interface BuildCodeModeInputOptions {
+ /** Output budget for an exec whose record names none (discovery's truncation limit). */
+ defaultMaxOutputTokens?: number;
+ /** Today's exec-tool identifiers; a transliterated call to a tool absent from it uses `tools["name"]`. */
+ toolNames?: ToolNameTable;
+}
+
+/** A classic round awaiting its transliterated output. */
+interface PendingClassicRound {
+ assistantIndex: number;
+ uses: ClaudeContentBlock[];
+ done: boolean;
+}
+
+/** First line of a reconstructed script. */
+export const RECONSTRUCTED_SOURCE_HEADER =
+ "// reconstructed by claudish: original script unavailable";
+export const EVICTED_OUTPUT_NOTE =
+ "claudish evicted this script's stored output under its memory limit; the nested tool results follow";
+export const RESTART_OUTPUT_NOTE =
+ "output unavailable after a claudish restart; the nested tool results follow";
+export const LOST_SCRIPT_NOTE =
+ "claudish lost this script's state (proxy restart or eviction); the nested tool results it was waiting for follow";
+export const MOVED_ON_NOTE = "the conversation moved on without the tool results";
+export const SESSION_ENDED_NOTE =
+ "the session ended before these calls' results were recorded, so this script never received them and did not finish; the nested tool results follow";
+export const UNKNOWN_OUTCOME_NOTE =
+ "this script's outcome is unknown: claudish has no record of it and some of its nested calls have no tool_result; the nested tool results follow";
+
+interface Round {
+ assistantIndex: number;
+ blocks: ClaudeContentBlock[];
+}
+
+interface ExecGroup {
+ execKey: string;
+ rounds: Round[];
+}
+
+function blocksOf(message: ClaudeMessage | undefined): ClaudeContentBlock[] {
+ return message && Array.isArray(message.content) ? message.content : [];
+}
+
+function sha256Hex(text: string): string {
+ return createHash("sha256").update(text).digest("hex");
+}
+
+function reasoningKey(item: ResponsesItem): string | undefined {
+ if (typeof item.id === "string" && item.id) return `id:${item.id}`;
+ if (typeof item.encrypted_content === "string") return `enc:${sha256Hex(item.encrypted_content)}`;
+ return undefined;
+}
+
+const CALL_TYPES = new Set(["custom_tool_call", "function_call"]);
+const OUTPUT_TYPES = new Set(["custom_tool_call_output", "function_call_output"]);
+
+/** The key under which an item may be emitted only once; undefined for any other item. */
+function onceKey(item: ResponsesItem): string | undefined {
+ if (item.type === "reasoning") {
+ const key = reasoningKey(item);
+ return key ? `reasoning:${key}` : undefined;
+ }
+ const callId = typeof item.call_id === "string" && item.call_id ? item.call_id : undefined;
+ if (!callId) return undefined;
+ if (CALL_TYPES.has(item.type)) return `call:${callId}`;
+ if (OUTPUT_TYPES.has(item.type)) return `output:${callId}`;
+ return undefined;
+}
+
+/**
+ * The source shown for an exec whose record is gone: one
+ * `Promise.allSettled([...])` per batch the script emitted, from history.
+ */
+export function reconstructExecSource(
+ batches: ReadonlyArray<ReadonlyArray<{ name: string; input: unknown }>>
+): string {
+ const lines = [RECONSTRUCTED_SOURCE_HEADER];
+ for (const batch of batches) {
+ const calls = batch.map(
+ (call) => `tools.${normalizeToolIdent(call.name)}(${JSON.stringify(call.input ?? {})})`
+ );
+ lines.push(`await Promise.allSettled([${calls.join(", ")}]);`);
+ }
+ return lines.join("\n");
+}
+
+class InputBuilder {
+ private readonly out: ResponsesItem[] = [];
+ /** Once-only keys: `call:<call_id>`, `output:<call_id>`, `reasoning:<id|enc hash>`. */
+ private readonly emitted = new Set<string>();
+ /** tool_use id → index of the assistant message carrying it (first occurrence). */
+ private readonly toolUseAt = new Map<string, number>();
+ /** tool_use id → its tool_result block (first occurrence). */
+ private readonly results = new Map<string, ClaudeContentBlock>();
+ private readonly groups = new Map<string, ExecGroup>();
+ private readonly classicRounds: PendingClassicRound[] = [];
+ private loggedOrphan = false;
+
+ constructor(
+ private readonly messages: readonly ClaudeMessage[],
+ private readonly stores: CodeModeStores,
+ private readonly keys: CodeModeKeys,
+ private readonly defaultMaxOutputTokens: number,
+ private readonly toolNames?: ToolNameTable
+ ) {
+ this.index();
+ }
+
+ build(): ResponsesItem[] {
+ for (let i = 0; i < this.messages.length; i++) {
+ const message = this.messages[i];
+ if (message?.role === "assistant") this.assistant(i);
+ else if (message?.role === "user") this.user(i);
+ }
+ return this.out;
+ }
+
+ // ─── indexing ───────────────────────────────────────────────────────
+
+ private index(): void {
+ for (let i = 0; i < this.messages.length; i++) {
+ const message = this.messages[i];
+ for (const block of blocksOf(message)) {
+ if (message.role === "assistant") this.indexToolUse(i, block);
+ else if (message.role === "user") this.indexToolResult(block);
+ }
+ }
+ }
+
+ private indexToolUse(i: number, block: ClaudeContentBlock): void {
+ if (block.type !== "tool_use" || typeof block.id !== "string") return;
+ if (this.toolUseAt.has(block.id)) return;
+ this.toolUseAt.set(block.id, i);
+ const nested = decodeNestedId(block.id);
+ if (nested) this.addToGroup(nested.execKey, i, block);
+ }
+
+ private indexToolResult(block: ClaudeContentBlock): void {
+ if (block.type !== "tool_result" || typeof block.tool_use_id !== "string") return;
+ if (!this.results.has(block.tool_use_id)) this.results.set(block.tool_use_id, block);
+ }
+
+ private addToGroup(execKey: string, assistantIndex: number, block: ClaudeContentBlock): void {
+ let group = this.groups.get(execKey);
+ if (!group) {
+ group = { execKey, rounds: [] };
+ this.groups.set(execKey, group);
+ }
+ let round = group.rounds[group.rounds.length - 1];
+ if (!round || round.assistantIndex !== assistantIndex) {
+ round = { assistantIndex, blocks: [] };
+ group.rounds.push(round);
+ }
+ round.blocks.push(block);
+ }
+
+ // ─── emission helpers ───────────────────────────────────────────────
+
+ private push(item: ResponsesItem): void {
+ const key = onceKey(item);
+ if (key !== undefined) {
+ if (this.emitted.has(key)) return;
+ this.emitted.add(key);
+ }
+ this.out.push(item);
+ }
+
+ private outputEmitted(callId: string): boolean {
+ return this.emitted.has(`output:${callId}`);
+ }
+
+ private assistantText(text: string): void {
+ if (!text) return;
+ this.push({ type: "message", role: "assistant", content: [{ type: "output_text", text }] });
+ }
+
+ // ─── assistant messages ─────────────────────────────────────────────
+
+ private assistant(i: number): void {
+ const message = this.messages[i];
+ const anchor = turnAnchorFor(this.keys.sessionKey, message, this.messages[i - 1]);
+ const record = this.stores.turns.get(this.keys.sessionKey, anchor);
+ if (record) {
+ for (const item of record.items) this.push(item);
+ } else if (typeof message.content === "string") {
+ this.assistantText(message.content);
+ } else {
+ for (const block of message.content) {
+ if (block.type === "text" && typeof block.text === "string") this.assistantText(block.text);
+ }
+ }
+ const startedHere = new Set<string>();
+ const classicUses: ClaudeContentBlock[] = [];
+ for (const block of blocksOf(message)) {
+ if (block.type !== "tool_use" || typeof block.id !== "string") continue;
+ if (this.toolUseAt.get(block.id) !== i) continue;
+ const nested = decodeNestedId(block.id);
+ if (!nested) {
+ classicUses.push(block);
+ continue;
+ }
+ const group = this.groups.get(nested.execKey);
+ if (group && group.rounds[0]?.assistantIndex === i && !startedHere.has(nested.execKey)) {
+ startedHere.add(nested.execKey);
+ this.startGroup(group);
+ }
+ }
+ if (classicUses.length > 0) this.startClassicRound(i, classicUses);
+ }
+
+ // ─── classic rounds (transliterated) ────────────────────────────────
+
+ /** A classic round's synthetic exec call; its output follows the message that answers it. */
+ private startClassicRound(i: number, uses: ClaudeContentBlock[]): void {
+ const round = transliterateRound({ uses, results: new Map() }, { names: this.toolNames });
+ this.push(round.call);
+ this.classicRounds.push({ assistantIndex: i, uses, done: false });
+ }
+
+ /**
+ * The transliterated output of every classic round message `i` answers: the
+ * first user message after the round (a missing result reads as not
+ * returned, as the step-3 converter synthesizes one). A round on the last
+ * message (a prefill) has no answer yet and gets the call alone.
+ */
+ private completeClassicRounds(i: number): void {
+ for (const pending of this.classicRounds) {
+ if (pending.done || pending.assistantIndex >= i) continue;
+ let firstUser = true;
+ for (let j = pending.assistantIndex + 1; j < i; j++) {
+ if (this.messages[j]?.role === "user") firstUser = false;
+ }
+ if (!firstUser) continue;
+ pending.done = true;
+ const round = transliterateRound(
+ { uses: pending.uses, results: this.results },
+ { names: this.toolNames }
+ );
+ this.push({
+ type: "custom_tool_call_output",
+ call_id: round.callId,
+ output: formatExecOutput(round.output, {
+ maxOutputTokens: this.defaultMaxOutputTokens,
+ resolveImage: (ref) => this.resolveImage(ref),
+ }),
+ });
+ }
+ }
+
+ private callIdOf(group: ExecGroup): string {
+ const record = this.stores.scripts.peek(this.keys.accountKey, group.execKey);
+ return record?.originalCallId ?? `call_${group.execKey}`;
+ }
+
+ private startGroup(group: ExecGroup): void {
+ const record = this.stores.scripts.peek(this.keys.accountKey, group.execKey);
+ for (const item of record?.reasoningItems ?? []) this.push(item);
+ const source =
+ record?.source ??
+ reconstructExecSource(
+ group.rounds.map((round) =>
+ round.blocks.map((b) => ({
+ name: typeof b.name === "string" ? b.name : "",
+ input: b.input,
+ }))
+ )
+ );
+ this.push({
+ type: "custom_tool_call",
+ call_id: this.callIdOf(group),
+ name: EXEC_TOOL_NAME,
+ input: source,
+ });
+ }
+
+ // ─── user messages ──────────────────────────────────────────────────
+
+ private user(i: number): void {
+ const message = this.messages[i];
+ if (typeof message.content === "string") {
+ this.closeMovedOnGroups(i);
+ this.completeClassicRounds(i);
+ if (message.content) {
+ this.push({
+ type: "message",
+ role: "user",
+ content: [{ type: "input_text", text: message.content }],
+ });
+ }
+ return;
+ }
+ const parts: ResponsesOutputPart[] = [];
+ const seen = new Set<string>();
+ const touchedGroups: string[] = [];
+ for (const block of message.content) {
+ if (block.type === "text" && typeof block.text === "string") {
+ parts.push({ type: "input_text", text: block.text });
+ } else if (block.type === "image") {
+ const url = imageUrlOf(block);
+ if (url) parts.push({ type: "input_image", image_url: url });
+ } else if (block.type === "tool_result" && typeof block.tool_use_id === "string") {
+ if (seen.has(block.tool_use_id)) continue;
+ seen.add(block.tool_use_id);
+ this.toolResult(i, block, parts, touchedGroups);
+ }
+ }
+ for (const execKey of touchedGroups) this.maybeCompleteGroup(execKey, i);
+ this.closeMovedOnGroups(i);
+ this.completeClassicRounds(i);
+ if (parts.length > 0) this.push({ type: "message", role: "user", content: parts });
+ }
+
+ private toolResult(
+ i: number,
+ block: ClaudeContentBlock,
+ parts: ResponsesOutputPart[],
+ touchedGroups: string[]
+ ): void {
+ const id = block.tool_use_id as string;
+ const callAt = this.toolUseAt.get(id);
+ if (callAt === undefined || callAt >= i) {
+ this.orphan(block, parts);
+ return;
+ }
+ const nested = decodeNestedId(id);
+ if (nested && !touchedGroups.includes(nested.execKey)) touchedGroups.push(nested.execKey);
+ // A classic result is read from `results` when its round's transliterated
+ // output is emitted (completeClassicRounds); its images go inside that output.
+ }
+
+ private orphan(block: ClaudeContentBlock, parts: ResponsesOutputPart[]): void {
+ if (!this.loggedOrphan) {
+ this.loggedOrphan = true;
+ log(
+ `[CodeMode] tool result ${block.tool_use_id} answers no earlier call; rendered as user text`
+ );
+ }
+ parts.push({ type: "input_text", text: `[Tool Result]: ${toolResultText(block)}` });
+ for (const image of toolResultImages(block)) {
+ const url = imageUrlOf(image);
+ if (url) parts.push({ type: "input_image", image_url: url });
+ }
+ }
+
+ // ─── exec outputs ───────────────────────────────────────────────────
+
+ /**
+ * True when message `i` (which carries a result of this group) answers the
+ * group's LAST round. Usually the first user message after that round; a
+ * later one when a user message without its results came between —
+ * `closeMovedOnGroups` leaves the group open then (its results exist), so
+ * the output must land here or the `custom_tool_call` has none at all.
+ * `emitOutput` emits once, so a later duplicate result changes nothing.
+ */
+ private completesAt(group: ExecGroup, i: number): boolean {
+ const last = group.rounds[group.rounds.length - 1];
+ if (!last || last.assistantIndex >= i) return false;
+ return blocksOf(this.messages[i]).some(
+ (b) => b.type === "tool_result" && last.blocks.some((use) => use.id === b.tool_use_id)
+ );
+ }
+
+ private maybeCompleteGroup(execKey: string, i: number): void {
+ const group = this.groups.get(execKey);
+ if (!group || !this.completesAt(group, i)) return;
+ this.emitOutput(group, this.hasLaterAssistant(i));
+ }
+
+ /**
+ * A group whose last round was the previous assistant message and that this
+ * message does not answer at all: the conversation moved on without results.
+ */
+ private closeMovedOnGroups(i: number): void {
+ const previous = i - 1;
+ if (this.messages[previous]?.role !== "assistant") return;
+ for (const group of this.groups.values()) {
+ const last = group.rounds[group.rounds.length - 1];
+ if (!last || last.assistantIndex !== previous) continue;
+ const answered = last.blocks.some((b) => this.results.has(b.id as string));
+ if (answered) continue;
+ this.emitOutput(group, true, MOVED_ON_NOTE);
+ }
+ }
+
+ private hasLaterAssistant(i: number): boolean {
+ for (let j = i + 1; j < this.messages.length; j++) {
+ if (this.messages[j]?.role === "assistant") return true;
+ }
+ return false;
+ }
+
+ private batchEntries(round: Round): BatchResultEntry[] {
+ return round.blocks.map((b) => {
+ const id = b.id as string;
+ const result = this.results.get(id);
+ return result
+ ? {
+ toolUseId: id,
+ result: { isError: result.is_error === true, content: result.content ?? "" },
+ }
+ : { toolUseId: id };
+ });
+ }
+
+ private emitOutput(group: ExecGroup, followedByAssistant: boolean, movedOnNote?: string): void {
+ const callId = this.callIdOf(group);
+ if (this.outputEmitted(callId)) return;
+ const key = completionKey(group.rounds.map((round) => batchHash(this.batchEntries(round))));
+ const record = this.stores.scripts.peek(this.keys.accountKey, group.execKey);
+ const stored = this.stores.scripts.lookupOutput(
+ this.keys.accountKey,
+ group.execKey,
+ key,
+ this.keys.sessionKey
+ );
+ const maxOutputTokens = record?.maxOutputTokens ?? this.defaultMaxOutputTokens;
+ let output: ResponsesOutputPart[];
+ if (stored) {
+ output = formatExecOutput(stored.output, {
+ maxOutputTokens,
+ resolveImage: (ref) => this.resolveImage(ref),
+ });
+ } else if (movedOnNote) {
+ output = this.notedOutput(group, "terminated", movedOnNote, maxOutputTokens);
+ } else {
+ const [status, note] = this.unstoredOutcome(group, record !== undefined, followedByAssistant);
+ output = this.notedOutput(group, status, note, maxOutputTokens);
+ }
+ this.push({ type: "custom_tool_call_output", call_id: callId, output });
+ }
+
+ /**
+ * Status and note of a group with no stored output, decided from history.
+ * `Script completed` only when every call of its last round has a real
+ * result and the conversation went on (the script resolved before its record
+ * was evicted or claudish restarted). A script never fed its last results —
+ * Claude Code's session ended first (V7), or a result is missing — did not
+ * complete, and is never called completed.
+ */
+ private unstoredOutcome(
+ group: ExecGroup,
+ hasRecord: boolean,
+ followedByAssistant: boolean
+ ): [ExecOutput["status"], string] {
+ const answers = this.lastRoundAnswers(group);
+ if (answers === "session-ended") return ["terminated", SESSION_ENDED_NOTE];
+ if (hasRecord || !followedByAssistant) return ["failed", LOST_SCRIPT_NOTE];
+ if (answers === "incomplete") return ["terminated", UNKNOWN_OUTCOME_NOTE];
+ const evicted = this.stores.scripts.isEvicted(this.keys.accountKey, group.execKey);
+ return ["completed", evicted ? EVICTED_OUTPUT_NOTE : RESTART_OUTPUT_NOTE];
+ }
+
+ /**
+ * How the group's last round was answered: a session-ended marker for any
+ * call, else a call with no tool_result at all, else every call answered.
+ */
+ private lastRoundAnswers(group: ExecGroup): "all" | "session-ended" | "incomplete" {
+ const last = group.rounds[group.rounds.length - 1];
+ let incomplete = false;
+ for (const block of last?.blocks ?? []) {
+ const result = this.results.get(block.id as string);
+ if (!result) incomplete = true;
+ else if (isSessionEndedResult(result)) return "session-ended";
+ }
+ return incomplete ? "incomplete" : "all";
+ }
+
+ /** `status` + `note` + one item per nested result (with its images), for a script with no output to show. */
+ private notedOutput(
+ group: ExecGroup,
+ status: ExecOutput["status"],
+ note: string,
+ maxOutputTokens: number
+ ): ResponsesOutputPart[] {
+ const parts: OutputPart[] = [{ type: "text", text: note }];
+ for (const round of group.rounds) {
+ for (const block of round.blocks) {
+ const id = block.id as string;
+ const name = typeof block.name === "string" ? block.name : "";
+ const call = `tools.${normalizeToolIdent(name)}(${JSON.stringify(block.input ?? {})})`;
+ const result = this.results.get(id);
+ if (!result) {
+ parts.push({ type: "text", text: `${call}: no tool_result returned` });
+ continue;
+ }
+ const verb = result.is_error === true ? "rejected" : "returned";
+ parts.push({ type: "text", text: `${call} ${verb}:\n${toolResultText(result)}` });
+ toolResultImages(result).forEach((_, index) => {
+ parts.push({ type: "image", ref: { toolUseId: id, index } });
+ });
+ }
+ }
+ return formatExecOutput(
+ { status, wallMs: undefined, parts },
+ { maxOutputTokens, resolveImage: (ref) => this.resolveImage(ref) }
+ );
+ }
+
+ private resolveImage(ref: ImageRef): string | undefined {
+ const result = this.results.get(ref.toolUseId);
+ if (!result) return undefined;
+ const image = toolResultImages(result)[ref.index];
+ return image ? imageUrlOf(image) : undefined;
+ }
+}
+
+/**
- * The Responses `input` for `messages` (Claude Code's own, after Layer 4),
++ * The Responses `input` for `messages` (Claude Code's own, after hook stage A),
+ * reading this account's and session's records from `stores`. Pure for a given
+ * history and store state.
+ */
+export function buildCodeModeInput(
+ messages: readonly ClaudeMessage[],
+ stores: CodeModeStores,
+ keys: CodeModeKeys,
+ options: BuildCodeModeInputOptions = {}
+): ResponsesItem[] {
+ // The walk's neighbour rules (the message before an assistant message, the
+ // first user message after a round) read the conversation only: Claude
+ // Code's inline system messages were never rendered and sit between them.
+ const builder = new InputBuilder(
+ conversationMessages(messages),
+ stores,
+ keys,
+ options.defaultMaxOutputTokens ?? DEFAULT_EXEC_MAX_OUTPUT_TOKENS,
+ options.toolNames
+ );
+ return builder.build();
+}
diff --cc packages/cli/src/code-mode/relay.test.ts
index e9e22541,00000000..455d22f4
mode 100644,000000..100644
--- a/packages/cli/src/code-mode/relay.test.ts
+++ b/packages/cli/src/code-mode/relay.test.ts
@@@ -1,329 -1,0 +1,372 @@@
+import { afterEach, describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { Hono } from "hono";
+import { sseResponseToJson } from "../handlers/shared/collect-sse-message.js";
+import {
+ createResponsesStreamHandler,
+ createSyntheticToolUseReply,
+} from "../handlers/shared/stream-parsers/openai-responses-sse.js";
+import type { StallClock } from "../handlers/shared/stream-parsers/responses/stall-guard.js";
++import { HookEngine } from "../hooks/engine.js";
++import { UnavailableSink } from "../hooks/injection/sinks.js";
++import { type HookDefinition, act } from "../hooks/public.js";
++import { HookRegistry } from "../hooks/registry.js";
++import { RequestHooks } from "../hooks/request-stage.js";
++import { applyResponseSeam } from "../hooks/response-seam.js";
+import { accountKeyFromBinding, sessionKeyFor } from "./ids.js";
+import { createCodeModeTurnHooks } from "./relay.js";
+import { loadQuickJSModule, resetQuickJSLoaderForTests } from "./sandbox/quickjs-loader.js";
+import { ScriptStore } from "./script-store.js";
+import type { CodeModeStores } from "./stores.js";
+import { ToolNameTable } from "./tool-names.js";
+import { TurnRecords } from "./turn-records.js";
+import type { CodeModeTurnHooks, ResponsesItem } from "./types.js";
+
+const turn1 = readFileSync(
+ new URL("../test-fixtures/sse-responses/codex-exec-turn1.sse", import.meta.url),
+ "utf8"
+);
+const turn2 = readFileSync(
+ new URL("../test-fixtures/sse-responses/codex-exec-turn2.sse", import.meta.url),
+ "utf8"
+);
+const classic = readFileSync(
+ new URL(
+ "../test-fixtures/sse-responses/gpt-5.6-sol-responses-toolsonly-turn1.sse",
+ import.meta.url
+ ),
+ "utf8"
+);
+const roundtrip = JSON.parse(
+ readFileSync(
+ new URL("../test-fixtures/code-mode/roundtrip-parts.request.json", import.meta.url),
+ "utf8"
+ )
+);
+const storesToClear: CodeModeStores[] = [];
+const session = "55555555-5555-4555-8555-555555555555";
+const binding = { auth: { arm: "oauth" as const, headers: { "chatgpt-account-id": "t4-relay" } } };
+const accountKey = accountKeyFromBinding(binding)!;
+const keys = { accountKey, sessionKey: sessionKeyFor(session, accountKey)! };
+const modelName = "capture-model";
+
+type Event = {
+ type: string;
+ index?: number;
+ content_block?: { type: string; id?: string; name?: string; input?: Record<string, unknown> };
+ delta?: { type?: string; text?: string; partial_json?: string; stop_reason?: string };
+ message?: { usage?: { input_tokens: number; output_tokens: number } };
+ usage?: { input_tokens: number; output_tokens: number };
+ error?: { type: string; message: string };
+};
+function frames(wire: string): string[] {
+ return wire.split(/\r?\n\r?\n/).filter((block) => block.includes("data: "));
+}
+function data(frame: string): Record<string, unknown> {
+ const line = frame.split(/\r?\n/).find((l) => l.startsWith("data: "))!;
+ return JSON.parse(line.slice(6));
+}
+function wire(frames: string[]): string {
+ return frames.join("\n\n") + "\n\n";
+}
+const execFrames = frames(turn1);
+const execStart = execFrames.findIndex((f) => {
+ const e = data(f);
+ return (
+ e.type === "response.output_item.added" &&
+ (e.item as { type?: string })?.type === "custom_tool_call"
+ );
+});
+const midExec = wire(execFrames.slice(0, execStart + 4));
+function clock(): StallClock {
+ const pending = new Set<() => void>();
+ return {
+ now: () => 1000,
+ setTimeout: (fn) => {
+ pending.add(fn);
+ return fn;
+ },
+ clearTimeout: (handle) => {
+ pending.delete(handle as () => void);
+ },
+ };
+}
+function upstream(body: string | ReadableStream<Uint8Array>): Response {
+ return new Response(body, { headers: { "content-type": "text/event-stream" } });
+}
+async function stream(
+ response: Response,
+ codeMode: CodeModeTurnHooks,
+ extra: Partial<Parameters<typeof createResponsesStreamHandler>[2]> = {}
+) {
+ const app = new Hono();
+ app.get("/", (c) =>
+ createResponsesStreamHandler(c, response, {
+ modelName,
+ codeMode,
+ retry: {
+ stall: { thresholdMs: 0 },
+ stallClock: clock(),
+ issueLeg: async () => {
+ throw new Error("Unexpected upstream continuation in a blocking-exec test");
+ },
+ },
+ ...extra,
+ })
+ );
+ const result = await app.fetch(new Request("http://t4.invalid/"));
+ return frames(await result.text()).map((f) => data(f) as unknown as Event);
+}
+function toolUses(events: Event[]) {
+ const uses = new Map<number, { id: string; name: string; json: string }>();
+ for (const e of events) {
+ if (e.type === "content_block_start" && e.content_block?.type === "tool_use")
+ uses.set(e.index!, { id: e.content_block.id!, name: e.content_block.name!, json: "" });
+ if (e.type === "content_block_delta" && e.delta?.type === "input_json_delta") {
+ const use = uses.get(e.index!);
+ if (use) use.json += e.delta.partial_json ?? "";
+ }
+ }
+ return [...uses.values()].map(({ id, name, json }) => ({
+ id,
+ name,
+ input: JSON.parse(json || "{}"),
+ }));
+}
+async function hooks() {
+ const stores = { scripts: new ScriptStore({ now: () => 1000 }), turns: new TurnRecords() };
+ storesToClear.push(stores);
+ const module = await loadQuickJSModule();
+ expect(module).toBeDefined();
+ return createCodeModeTurnHooks({
+ stores,
+ ...keys,
+ shape: () => "classic",
+ names: new ToolNameTable(["exec_command"]),
+ allTools: [],
+ defaultMaxOutputTokens: 10000,
+ previousMessage: undefined,
+ loadModule: async () => module,
+ limits: { cpuMs: 100 },
+ });
+}
+afterEach(() => {
+ for (const s of storesToClear.splice(0)) {
+ s.scripts.clear();
+ s.turns.clear();
+ }
+ resetQuickJSLoaderForTests();
+});
+
+describe("T4 code-mode relay through the public Responses handler", () => {
+ test("REQ-21 TEST-25 relays the real exec as exactly two nested tool_use blocks, never exec", async () => {
+ const events = await stream(upstream(turn1), await hooks());
+ expect(toolUses(events)).toEqual([
+ {
+ id: "toolu_cx_c0d07fd9ccd84fe29372c0e72ed12869_0",
+ name: "exec_command",
+ input: { cmd: "cat README.md; wc -l README.md", max_output_tokens: 3000 },
+ },
+ {
+ id: "toolu_cx_c0d07fd9ccd84fe29372c0e72ed12869_1",
+ name: "exec_command",
+ input: { cmd: "cat notes.txt; wc -l notes.txt", max_output_tokens: 3000 },
+ },
+ ]);
+ expect(events.filter((e) => e.type === "message_start")).toHaveLength(1);
+ expect(events.filter((e) => e.type === "message_stop")).toHaveLength(1);
+ expect(events.some((e) => e.type === "error")).toBe(false);
+ expect(events.find((e) => e.type === "message_delta")?.delta?.stop_reason).toBe("tool_use");
+ expect(events.find((e) => e.type === "message_delta")?.usage).toMatchObject({
+ input_tokens: 30678,
+ output_tokens: 134,
+ });
+ }, 20000);
+
+ test("REQ-21 the captured answer turn keeps text and finishes without inventing tools", async () => {
+ const events = await stream(upstream(turn2), await hooks());
+ expect(toolUses(events)).toEqual([]);
+ expect(events.some((e) => e.type === "error")).toBe(false);
+ expect(events.find((e) => e.type === "message_delta")?.delta?.stop_reason).toBe("end_turn");
+ expect(
+ events.some(
+ (e) => e.type === "content_block_delta" && e.delta?.type === "text_delta" && e.delta.text
+ )
+ ).toBe(true);
+ }, 20000);
+
+ test.each(["body end", "socket error"])(
+ "REQ-22 TEST-26 emits SSE error when %s cuts the real exec input",
+ async (how) => {
+ // Derived solely by cutting codex-exec-turn1.sse after real input deltas.
+ const bytes = new TextEncoder().encode(midExec);
+ let sent = false;
+ const body =
+ how === "body end"
+ ? midExec
+ : new ReadableStream<Uint8Array>({
+ pull(controller) {
+ if (!sent) {
+ sent = true;
+ controller.enqueue(bytes);
+ } else controller.error(new Error("injected socket drop"));
+ },
+ });
+ const events = await stream(upstream(body), await hooks());
+ expect(events.some((e) => e.type === "error")).toBe(true);
+ expect(toolUses(events)).toEqual([]);
+ expect(
+ events.some((e) => e.type === "message_delta" && e.delta?.stop_reason === "tool_use")
+ ).toBe(false);
+ },
+ 20000
+ );
+
+ test("REQ-23 TEST-27 refuses a tool_use finish over a cut-off classic block beside a blocking exec", async () => {
+ // Derived event sequence: untouched added+delta frames for the first classic
+ // call in gpt-5.6-sol-responses-toolsonly-turn1.sse, followed by untouched
+ // exec and terminal frames of codex-exec-turn1.sse. Omit classic done frames
+ // to model a cut-off block; do not fabricate protocol events.
+ const ordinary = frames(classic);
+ const start = ordinary.findIndex((f) => {
+ const e = data(f);
+ return (
+ e.type === "response.output_item.added" &&
+ (e.item as { type?: string })?.type === "function_call"
+ );
+ });
+ const heldExec = execFrames.filter((f) => {
+ const e = data(f);
+ return (
+ e.type === "response.completed" ||
+ String(e.type).includes("custom_tool_call_input") ||
+ (e.item as { type?: string })?.type === "custom_tool_call"
+ );
+ });
+ const mixed = wire([...ordinary.slice(0, start + 2), ...heldExec]);
+ const events = await stream(upstream(mixed), await hooks());
+ expect(events.some((e) => e.type === "error")).toBe(true);
+ expect(
+ events.some((e) => e.type === "message_delta" && e.delta?.stop_reason === "tool_use")
+ ).toBe(false);
+ }, 20000);
+
+ test("REQ-24 TEST-28 records an exec output even when a complete classic call shares its leg", async () => {
+ // Derived from the first COMPLETE classic call's verbatim frames and real
+ // exec frames. The public runtime seam supplies the accepted G roundtrip's
+ // verbatim exec call/output pair to model an interstitial completed exec.
+ const ordinary = frames(classic);
+ const start = ordinary.findIndex((f) => {
+ const e = data(f);
+ return (
+ e.type === "response.output_item.added" &&
+ (e.item as { type?: string })?.type === "function_call"
+ );
+ });
+ const end = ordinary.findIndex(
+ (f, i) => i > start && data(f).type === "response.output_item.done"
+ );
+ const heldExec = execFrames.filter((f) => {
+ const e = data(f);
+ return (
+ e.type === "response.completed" ||
+ String(e.type).includes("custom_tool_call_input") ||
+ (e.item as { type?: string })?.type === "custom_tool_call"
+ );
+ });
+ const appendItems: ResponsesItem[] = roundtrip.body.input.slice(-2);
+ let recorded: ResponsesItem[] = [];
+ const codeMode: CodeModeTurnHooks = {
+ onExecCall: () => ({ kind: "continue", appendItems: structuredClone(appendItems) }),
+ onTurnEnd: (record) => {
+ recorded = record.items;
+ },
+ onTurnAbandoned: () => {},
+ };
+ const events = await stream(
+ upstream(wire([...ordinary.slice(0, end + 1), ...heldExec])),
+ codeMode
+ );
+ expect(toolUses(events)).toEqual([
+ { id: expect.any(String), name: "read_file", input: { path: "a.ts" } },
+ ]);
+ expect(events.find((e) => e.type === "message_delta")?.delta?.stop_reason).toBe("tool_use");
+ expect(events.some((e) => e.type === "error")).toBe(false);
+ expect(
+ recorded.filter((i) => i.type === "custom_tool_call" || i.type === "custom_tool_call_output")
+ ).toEqual(appendItems);
+ }, 20000);
+
+ test("REQ-26 TEST-32 synthetic replies share repair, prior usage and the JSON exit", async () => {
- const sse = createSyntheticToolUseReply(
- [
- {
- id: "toolu_cx_0123456789abcdef0123456789abcdef_1",
- name: "Read",
- input: { file_path: "f1" },
++ // Tool-argument repair runs at the hook response seam (`withHooks` wraps the
++ // handler's Response, a 5r synthetic reply included), so the reply goes
++ // through the seam exactly as a driver batch does.
++ const def = {
++ apiVersion: 1,
++ id: "repair-read",
++ on: {
++ toolCall: {
++ tools: ["Read"],
++ handle: (ctx) => [act.repairToolArgs({ ...ctx.tool.args, repaired: true }, "test")],
+ },
- ],
++ },
++ } satisfies HookDefinition;
++ const engine = new HookEngine({
++ registry: new HookRegistry(
++ [],
++ [{ id: "hook:t/repair", module: "/t.ts", moduleIndex: 0, exportIndex: 0, def }],
++ undefined
++ ),
++ config: {},
++ hostMode: "other",
++ journalSink: () => {},
++ warn: () => {},
++ drainTelemetryOutbox: false,
++ });
++ const vars = new Map<string, unknown>();
++ const context = {
++ get: (k: string) => vars.get(k),
++ set: (k: string, v: unknown) => vars.set(k, v),
++ };
++ const scope = await new RequestHooks(engine, null, new UnavailableSink(() => {})).beginAttempt(
++ context as never,
+ {
- modelName,
- priorInputTokens: 1234,
- shouldBufferTool: (name) => name === "Read",
- onToolCall: (_name, args) => JSON.stringify({ ...JSON.parse(args), repaired: true }),
++ claudeRequest: { messages: [{ role: "user", content: "read" }] },
++ route: { modelId: modelName, provider: "openai-codex", native: false },
++ model: modelName,
++ stream: true,
+ }
+ );
++ const sse = await applyResponseSeam(
++ createSyntheticToolUseReply(
++ [
++ {
++ id: "toolu_cx_0123456789abcdef0123456789abcdef_1",
++ name: "Read",
++ input: { file_path: "f1" },
++ },
++ ],
++ { modelName, priorInputTokens: 1234 }
++ ),
++ scope
++ );
+ const json = await sseResponseToJson(sse, modelName);
+ expect(json.status).toBe(200);
+ const body = await json.json();
+ expect(body).toMatchObject({
+ type: "message",
+ role: "assistant",
+ model: modelName,
+ stop_reason: "tool_use",
+ content: [
+ {
+ type: "tool_use",
+ id: "toolu_cx_0123456789abcdef0123456789abcdef_1",
+ name: "Read",
+ input: { file_path: "f1", repaired: true },
+ },
+ ],
+ usage: { input_tokens: 1234, output_tokens: 0 },
+ });
+ }, 20000);
+});
diff --cc packages/cli/src/code-mode/replay.ts
index 3c959331,00000000..644da10c
mode 100644,000000..100644
--- a/packages/cli/src/code-mode/replay.ts
+++ b/packages/cli/src/code-mode/replay.ts
@@@ -1,220 -1,0 +1,220 @@@
+/**
+ * Replay a lost exec script from history (architecture §5.12).
+ *
+ * A suspended script whose runtime was evicted (the 32-runtime live cap, the
+ * 6 h idle TTL, a retired or poisoned module) still has its record and its
+ * SOURCE. When Claude Code's answer to its pending batch arrives, the script is
+ * re-run from the start in a fresh runtime and each batch it blocks on is
+ * answered from history: batch k must be exactly the k-th round the request
+ * carries — the same nested ids, and for each the same tool name and the same
+ * canonical input. Only then are that round's tool_results fed in. A script is
+ * deterministic enough for this: `Math.random` is seeded by its exec call id;
+ * `Date` is not, and a script that branches on it mismatches. Any mismatch, or
+ * no loaded sandbox module (synchronous, never loads one; 5r asks its caller to load one first: `needs-module`),
+ * leaves the record lost and the caller takes the lost path.
+ *
+ * The record is only ever replayed by its OWNER session (the caller checks).
+ */
+
+import { log } from "../logger.js";
+import { type ClaudeToolLike, renderExecTool } from "./exec-tool.js";
+import {
+ type BatchResultEntry,
+ batchHash,
+ canonicalJson,
+ completionKey,
+ inputHash,
+} from "./hashes.js";
+import { decodeNestedId, encodeNestedId } from "./ids.js";
+import type { ExecOutput } from "./output.js";
+import { nestedBlocksFor, settleDone, suspendBlocked } from "./relay.js";
+import { type QuickJSModuleLease, currentQuickJSModule } from "./sandbox/quickjs-loader.js";
+import {
+ type NestedCall,
+ type NestedResult,
+ type ScriptRuntime,
+ type ScriptStep,
+ createScriptRuntime,
+} from "./sandbox/script-runtime.js";
+import type { ExecBatch, ExecRecord, ExecState, ScriptStore } from "./script-store.js";
+import { nestedResultFromToolResult } from "./tool-results.js";
+import type { ClaudeContentBlock, NestedToolUse } from "./types.js";
+
+/** One round of the exec in the request's history: its nested tool_use blocks, in order. */
+export interface HistoryRound {
+ ids: string[];
+ blocks: ClaudeContentBlock[];
+}
+
+export interface ReplayInput {
+ scripts: ScriptStore;
+ /** A `lost` record that still has its source and the batches it relayed. */
+ record: ExecRecord;
+ /** The exec's rounds in this request, ending with the round this request answers. */
+ rounds: HistoryRound[];
+ /** tool_use id → tool_result across the request. */
+ results: ReadonlyMap<string, ClaudeContentBlock>;
+ /** Claude Code's tools in this request (the identifiers the script calls). */
+ tools: readonly ClaudeToolLike[];
+ sessionKey: string;
+ /**
+ * The user interrupted (Esc) beside the last round's results: the script is
+ * re-run up to that round and ENDED there, never fed its results, so it can
+ * emit no further tool call — as the live path terminates on the same marker.
+ */
+ interrupted?: boolean;
+ /** Test seam; default the loaded module, if any. */
+ module?: QuickJSModuleLease;
+}
+
+export type ReplayResult =
+ | { kind: "reply"; blocks: [NestedToolUse, ...NestedToolUse[]] }
+ | { kind: "done" }
+ /**
+ * Interrupted at the last round: `output` is what the script produced before
+ * it (the runtime is disposed, the record still `lost`); `key` is the
+ * completion key through that round. The caller adds the results and stores it.
+ */
+ | { kind: "interrupted"; output: ExecOutput; key: string }
+ | undefined;
+
+function entriesOf(
+ ids: readonly string[],
+ results: ReadonlyMap<string, ClaudeContentBlock>
+): BatchResultEntry[] {
+ return ids.map((id) => {
+ const result = results.get(id);
+ return result
+ ? {
+ toolUseId: id,
+ result: { isError: result.is_error === true, content: result.content ?? "" },
+ }
+ : { toolUseId: id };
+ });
+}
+
+/**
+ * The batch the script blocked on is exactly this history round: the same
- * ids and names, and each input either equal to history's or the one Layer 4
- * repaired into history's (`repairs`, recorded when the batch was relayed).
++ * ids and names, and each input either equal to history's or the one a recorded repair turned
++ * into history's (`repairs`, recorded when the batch was relayed).
+ */
+function matchesRound(
+ execKey: string,
+ calls: readonly NestedCall[],
+ round: HistoryRound,
+ repairs: ExecBatch["repairs"]
+): boolean {
+ if (calls.length !== round.blocks.length) return false;
+ return calls.every((call) => {
+ const id = encodeNestedId(execKey, call.seq);
+ const block = round.blocks.find((b) => b.id === id);
+ if (block === undefined || block.name !== call.name) return false;
+ if (canonicalJson(block.input ?? {}) === canonicalJson(call.input)) return true;
+ const repair = repairs?.[id];
+ return (
+ repair !== undefined &&
+ repair.script === inputHash(call.input) &&
+ repair.relayed === inputHash(block.input)
+ );
+ });
+}
+
+function resultsFor(
+ round: HistoryRound,
+ results: ReadonlyMap<string, ClaudeContentBlock>
+): NestedResult[] {
+ const out: NestedResult[] = [];
+ for (const id of round.ids) {
+ const seq = decodeNestedId(id)?.seq;
+ const block = results.get(id);
+ if (seq !== undefined && block) out.push(nestedResultFromToolResult(seq, block));
+ }
+ return out;
+}
+
+/**
+ * Feed history's rounds to a freshly started script, checking each batch it
+ * blocks on against the round. `stopped` is a divergence (undefined) or an
+ * interrupt at the last round; otherwise the step after the last round.
+ */
+function runRounds(
+ runtime: ScriptRuntime,
+ input: ReplayInput
+): { kind: "ran"; step: ScriptStep; hashes: string[] } | { kind: "stopped"; result: ReplayResult } {
+ const { record, rounds, results } = input;
+ let step = runtime.start(record.source);
+ const hashes: string[] = [];
+ for (const [k, round] of rounds.entries()) {
+ const repairs = record.batches[k]?.repairs;
+ if (step.kind !== "blocked" || !matchesRound(record.execCallId, step.calls, round, repairs)) {
+ log(`[CodeMode] exec ${record.originalCallId}: replay diverged from history; script lost`);
+ runtime.dispose();
+ return { kind: "stopped", result: undefined };
+ }
+ hashes.push(batchHash(entriesOf(round.ids, results)));
+ if (input.interrupted && k === rounds.length - 1) {
+ const output = runtime.terminate("");
+ log(`[CodeMode] exec ${record.originalCallId}: replayed to the interrupt; terminated`);
+ return {
+ kind: "stopped",
+ result: { kind: "interrupted", output, key: completionKey(hashes) },
+ };
+ }
+ step = runtime.resume(resultsFor(round, results));
+ }
+ return { kind: "ran", step, hashes };
+}
+
+/**
+ * Re-run `record`'s script against history. A blocked step past the last
+ * round is the script's next batch (reply); a finished one is stored. Undefined
+ * when the script is not replayable or diverged: the record stays lost.
+ */
+export function replayLostScript(input: ReplayInput): ReplayResult {
+ const { record, rounds, scripts } = input;
+ if (record.state !== "lost" || record.batches.length === 0 || !record.source) return undefined;
+ if (rounds.length === 0) return undefined;
+ const lease = input.module ?? currentQuickJSModule();
+ if (!lease) return undefined;
+ let runtime: ScriptRuntime | undefined;
+ try {
+ const rendered = renderExecTool(input.tools);
+ runtime = createScriptRuntime({
+ tools: rendered.names,
+ allTools: rendered.allTools,
+ seed: record.originalCallId,
+ module: lease,
+ onEvicted: () => scripts.loseIfRuntimeGone(record),
+ });
+ const ran = runRounds(runtime, input);
+ if (ran.kind !== "ran") return ran.result;
+ const { step, hashes } = ran;
+ scripts.transition(record, "replay");
+ scripts.attachRuntime(record, runtime);
+ record.batches = rounds.map((round, k) => ({
+ ids: round.ids,
+ batchHash: hashes[k],
+ repairs: record.batches[k]?.repairs,
+ }));
+ if (step.kind === "blocked") {
+ const blocks = nestedBlocksFor(record.execCallId, step.calls);
+ suspendBlocked(scripts, record, blocks);
+ log(`[CodeMode] exec ${record.originalCallId}: replayed from history; blocked again`);
+ return { kind: "reply", blocks };
+ }
+ settleDone(scripts, record, step.output, completionKey(hashes), input.sessionKey);
+ log(`[CodeMode] exec ${record.originalCallId}: replayed from history; ${step.output.status}`);
+ return { kind: "done" };
+ } catch (err) {
+ log(`[CodeMode] exec ${record.originalCallId}: replay failed; script lost: ${err}`);
+ try {
+ runtime?.dispose();
+ // The replay transition may already have run before the throw.
+ const state: ExecState = (record as ExecRecord).state;
+ if (state === "running") scripts.transition(record, "fail");
+ } catch {
+ // The runtime is gone either way.
+ }
+ return undefined;
+ }
+}
diff --cc packages/cli/src/code-mode/request.ts
index b9cd17c3,00000000..02d21396
mode 100644,000000..100644
--- a/packages/cli/src/code-mode/request.ts
+++ b/packages/cli/src/code-mode/request.ts
@@@ -1,373 -1,0 +1,373 @@@
+/**
+ * Step 5d: the code-mode request shape for `openai-codex`.
+ *
+ * Runs after 5c, so `prompt_cache_key`, `store`, `include` and
+ * `reasoning.summary` are already on the payload and are kept. The decision
+ * (`decideCodeMode`) reads THIS request's auth binding, its Claude Code session
+ * id, the account's `/models` discovery and whether the sandbox loads; when it
+ * is on, the payload is rewritten into one of the two shapes the backend
+ * accepts (R1 §1d), each carrying exactly one tool, the exec tool:
+ *
+ * lite: no top-level `tools` or `instructions`; `input` starts with
+ * `{type:"additional_tools", id:"at_<uuidv5>", role:"developer",
+ * tools:[exec]}` and a developer message carrying the system text;
+ * `reasoning.context: "all_turns"` (the lite header without it is a
+ * 400, variant D); header `x-openai-internal-codex-responses-lite: true`.
+ * classic: `tools: [exec]`, `instructions` = the system text.
+ * both: `parallel_tool_calls: false` (parallelism lives in the script),
+ * `tool_choice: "auto"`, `input` from `buildCodeModeInput`.
+ *
+ * The system text is the step-4 `instructions` (Claude Code's system prompt,
- * identity-filtered, after Layer 4) plus a short claudish note — not the
++ * identity-filtered, after hook stage A) plus a short claudish note — not the
+ * 21.7 KB Codex persona. Everything here degrades: a build that throws sends
+ * the request non-code-mode (logged), never refuses it; discovery and the
+ * sandbox resolve to "off" on any failure.
+ */
+
+import { createHash } from "node:crypto";
- import { extractSessionId } from "../behavior/harness.js";
++import { extractSessionId } from "../hooks/harness.js";
+import { log } from "../logger.js";
+import {
+ type CodexModelInfo,
+ getCodexModelInfo,
+ prefetchCodexModels,
+} from "../providers/codex-models-discovery.js";
+import type { WireApi, WireHeader } from "../providers/connection-wire.js";
+import type { AuthBinding } from "../providers/transport/types.js";
+import {
+ DEFAULT_EXEC_MAX_OUTPUT_TOKENS,
+ type ExecToolDefinition,
+ type ExecToolMeta,
+ renderExecTool,
+} from "./exec-tool.js";
+import { accountKeyFromBinding, sessionKeyFor, uuidV5 } from "./ids.js";
+import { buildCodeModeInput } from "./input-builder.js";
+import { defaultExecOutputTokens } from "./output.js";
+import {
+ type CodeModeDecision,
+ type CodeModeSetting,
+ decideCodeMode,
+ describeCodeModeDecision,
+} from "./policy.js";
+import { isSandboxAvailable } from "./sandbox/quickjs-loader.js";
+import { getCodeModeStores } from "./stores.js";
+import type { ToolNameTable } from "./tool-names.js";
+import type { ResponsesItem } from "./types.js";
+
+/** The header that marks a lite request (sent over HTTP; Codex's WebSocket uses client_metadata). */
+export const LITE_HEADER_NAME = "x-openai-internal-codex-responses-lite";
+
+/**
+ * Appended to Claude Code's system prompt in code mode. Short on purpose: the
+ * exec tool's own description carries the runtime contract.
+ */
+export const CODE_MODE_NOTE = [
+ "# Tools in this session",
+ "Every tool is called from JavaScript through the `exec` tool: `await tools.<Name>(args)` with the tool's own argument object. A tool's result is its text; a failed or denied call rejects with a string.",
+ "Batch independent reads and searches in one exec with `await Promise.allSettled([...])` and inspect every result. Use `text()` to return what you need from the script.",
+].join("\n");
+
+/** How long a lite rejection keeps a model on the classic shape (the discovery TTL). */
+export const LITE_FALLBACK_TTL_MS = 60 * 60 * 1000;
+
+/** model slug (lowercase) → until when the classic shape is used instead of lite. */
+const liteFallbackUntil = new Map<string, number>();
+
+/** True while a lite rejection for `model` is remembered. */
+export function isLiteFallbackActive(model: string, now: number = Date.now()): boolean {
+ const until = liteFallbackUntil.get(model.toLowerCase());
+ if (until === undefined) return false;
+ if (now >= until) {
+ liteFallbackUntil.delete(model.toLowerCase());
+ return false;
+ }
+ return true;
+}
+
+/** Forget remembered lite rejections and logged decisions (tests only). */
+export function resetCodeModeRequestStateForTests(): void {
+ liteFallbackUntil.clear();
+ lastLogged.clear();
+}
+
+/** Remember that the backend rejected a lite request for `model`. */
+export function markLiteFallback(model: string, now: number = Date.now()): void {
+ liteFallbackUntil.set(model.toLowerCase(), now + LITE_FALLBACK_TTL_MS);
+ log(`[CodeMode] ${model}: lite request rejected; classic shape for the next hour`);
+}
+
+export interface CodeModePayloadContext {
+ shape: "lite" | "classic";
+ execTool: ExecToolDefinition;
+ /** `buildCodeModeInput`'s output. */
+ input: ResponsesItem[];
+ sessionKey: string;
+ modelInfo?: CodexModelInfo;
+}
+
+export interface CodeModeRequest {
+ payload: any;
+ /** The shape actually built (lite falls back to classic when no effort can be set). */
+ shape: "lite" | "classic";
+ /** Headers to merge into every header fetch of this request. */
+ headers: WireHeader[];
+}
+
+function systemText(instructions: unknown): string {
+ const base = typeof instructions === "string" ? instructions.trim() : "";
+ return base ? `${base}\n\n${CODE_MODE_NOTE}` : CODE_MODE_NOTE;
+}
+
+/**
+ * Lite needs `reasoning.context: "all_turns"`, which needs a reasoning object
+ * with an effort: Claude Code's when it set one, else discovery's default
+ * level (with `summary: "auto"`, as 5c adds). Undefined when neither exists:
+ * the request then goes in the classic shape and nothing is pinned.
+ */
+function liteReasoning(payload: any, modelInfo: CodexModelInfo | undefined): any | undefined {
+ const reasoning =
+ payload.reasoning && typeof payload.reasoning === "object" ? payload.reasoning : {};
+ if (typeof reasoning.effort === "string" && reasoning.effort) {
+ return { ...reasoning, context: "all_turns" };
+ }
+ const level = modelInfo?.defaultReasoningLevel;
+ if (!level) return undefined;
+ return {
+ ...reasoning,
+ effort: level,
+ summary: reasoning.summary ?? "auto",
+ context: "all_turns",
+ };
+}
+
+/**
+ * Rewrite `payload` (mutated and returned) into the code-mode shape `ctx.shape`.
+ * The caller passes a clone, so a throw leaves the original intact.
+ */
+export function applyCodeModeToPayload(payload: any, ctx: CodeModePayloadContext): CodeModeRequest {
+ const system = systemText(payload.instructions);
+ let shape = ctx.shape;
+ const headers: WireHeader[] = [];
+
+ if (shape === "lite") {
+ const reasoning = liteReasoning(payload, ctx.modelInfo);
+ if (reasoning) {
+ const toolsHash = createHash("sha256").update(JSON.stringify(ctx.execTool)).digest("hex");
+ payload.reasoning = reasoning;
+ delete payload.tools;
+ delete payload.instructions;
+ payload.input = [
+ {
+ type: "additional_tools",
+ id: `at_${uuidV5(ctx.sessionKey, toolsHash)}`,
+ role: "developer",
+ tools: [ctx.execTool],
+ },
+ { type: "message", role: "developer", content: [{ type: "input_text", text: system }] },
+ ...ctx.input,
+ ];
+ headers.push({ name: LITE_HEADER_NAME, value: "true", merge: "append-comma" });
+ } else {
+ log("[CodeMode] no reasoning effort and no discovery default; classic shape instead of lite");
+ shape = "classic";
+ }
+ }
+ if (shape === "classic") {
+ payload.tools = [ctx.execTool];
+ payload.instructions = system;
+ payload.input = ctx.input;
+ }
+ payload.parallel_tool_calls = false;
+ payload.tool_choice = "auto";
+ return { payload, shape, headers };
+}
+
+// ─── decision logging ─────────────────────────────────────────────────
+
+const MAX_LOG_KEYS = 10_000;
+/** session (or process-wide reason) → the last decision line logged for it. */
+const lastLogged = new Map<string, string>();
+
+/** Log the decision once per session per change; process-wide reasons once per process. */
+function logDecision(
+ line: string,
+ sessionKey: string | undefined,
+ decision: CodeModeDecision
+): void {
+ const processWide =
+ !decision.on && (decision.reason === "no-account-id" || decision.reason === "no-session-id");
+ const key = processWide ? `process:${decision.reason}` : (sessionKey ?? "process:no-session");
+ if (lastLogged.get(key) === line) return;
+ lastLogged.delete(key);
+ lastLogged.set(key, line);
+ while (lastLogged.size > MAX_LOG_KEYS) {
+ const oldest = lastLogged.keys().next().value;
+ if (oldest === undefined) break;
+ lastLogged.delete(oldest);
+ }
+ log(line);
+}
+
+// ─── step 5d ──────────────────────────────────────────────────────────
+
+export interface PrepareCodeModeInput {
+ providerName: string;
+ setting: CodeModeSetting;
+ /** THIS request's auth binding (step 5b). */
+ binding: AuthBinding | undefined;
+ api: WireApi | undefined;
- /** Claude Code's request after Layer 4 (`tools`, `messages`, `tool_choice`, `metadata`). */
++ /** Claude Code's request after the hook request stages (`tools`, `messages`, `tool_choice`, `metadata`). */
+ claudeRequest: any;
+ /** The upstream payload after 5c. */
+ payload: any;
+ /** Test seam: discovery wait. */
+ discoveryWaitMs?: number;
+}
+
+export interface PreparedCodeMode {
+ decision: CodeModeDecision;
+ /** Present only when the decision is on and the build succeeded. */
+ request?: CodeModeRequest;
+ /** A deep clone of the post-5c payload, for the lite → classic fallback. */
+ prePayload?: any;
+ /** What the payload was built from; the lite → classic fallback rebuilds from it. */
+ context?: CodeModePayloadContext;
+ /** What the turn's exec calls run with (`createCodeModeTurnHooks`). */
+ turn?: {
+ accountKey: string;
+ sessionKey: string;
+ names: ToolNameTable;
+ allTools: ExecToolMeta[];
+ defaultMaxOutputTokens: number;
+ };
+}
+
+/** Does a 400 body name the lite header or `reasoning.context` (the lite shape's own rejections)? */
+export function isLiteRejection(status: number, body: string): boolean {
+ if (status !== 400) return false;
+ const text = body.toLowerCase();
+ return text.includes(LITE_HEADER_NAME) || text.includes("reasoning.context");
+}
+
+/**
+ * The lite → classic fallback: the classic code-mode shape built from the
+ * post-5c payload clone and the same context (the same exec tool and the same
+ * `buildCodeModeInput` output — never the non-code-mode function tools).
+ * `model` is remembered for the discovery TTL, so the next requests go classic.
+ */
+export function rebuildAsClassic(
+ prePayload: any,
+ context: CodeModePayloadContext,
+ model: string
+): CodeModeRequest {
+ markLiteFallback(model);
+ return applyCodeModeToPayload(structuredClone(prePayload), { ...context, shape: "classic" });
+}
+
+/** `headers` without the lite header (a classic body with it is itself a 400, variant D). */
+export function withoutLiteHeader(headers: WireHeader[]): WireHeader[] {
+ return headers.filter((h) => h.name.toLowerCase() !== LITE_HEADER_NAME);
+}
+
+/**
+ * Decide and, when on, build the code-mode request for one `openai-codex`
+ * request. Never throws: every failure is "off" or a non-code-mode request.
+ */
+export async function prepareCodeModeRequest(
+ input: PrepareCodeModeInput
+): Promise<PreparedCodeMode> {
+ try {
+ return await prepare(input);
+ } catch (err) {
+ log(`[CodeMode] decision failed; sending this request non-code-mode: ${err}`);
+ return { decision: { on: false, reason: "discovery-unknown" } };
+ }
+}
+
+async function prepare(input: PrepareCodeModeInput): Promise<PreparedCodeMode> {
+ const { binding, claudeRequest, payload } = input;
+ const arm = binding?.auth?.arm;
+ const accountKey = accountKeyFromBinding(binding);
+ const sessionKey = sessionKeyFor(extractSessionId(claudeRequest), accountKey);
+ const tools = Array.isArray(claudeRequest?.tools) ? claudeRequest.tools : [];
+ const model = typeof payload?.model === "string" ? payload.model : "";
+
+ // Warm the account's dynamic models catalog as early as possible (Claude
+ // Code's first request is usually tool-less); never while the setting is off.
+ if (input.setting !== "off" && binding && accountKey && arm === "oauth") {
+ prefetchCodexModels(binding, accountKey);
+ }
+
+ const base = {
+ providerName: input.providerName,
+ arm,
+ accountKey,
+ api: input.api,
+ hasTools: tools.length > 0,
+ toolChoice: claudeRequest?.tool_choice,
+ hasSessionId: sessionKey !== undefined,
+ setting: input.setting,
+ pinned: false,
+ sandboxAvailable: true,
+ liteFallbackActive: isLiteFallbackActive(model),
+ };
+
+ // Static gates first: no discovery wait, no store, no sandbox load.
+ const gate = decideCodeMode({ ...base, modelInfo: undefined });
+ if (!gate.on && gate.reason !== "discovery-unknown") {
+ logDecision(describeCodeModeDecision(gate, undefined), sessionKey, gate);
+ return { decision: gate };
+ }
+
+ const stores = getCodeModeStores();
+ const pinned = sessionKey !== undefined && stores.scripts.isPinned(sessionKey);
+ const modelInfo =
+ binding && accountKey
+ ? await getCodexModelInfo(model, binding, accountKey, { waitMs: input.discoveryWaitMs })
+ : undefined;
+ let decision = decideCodeMode({ ...base, pinned, modelInfo });
+ if (decision.on && !(await isSandboxAvailable())) {
+ decision = decideCodeMode({ ...base, pinned, modelInfo, sandboxAvailable: false });
+ }
+ logDecision(describeCodeModeDecision(decision, modelInfo), sessionKey, decision);
+ if (!decision.on || !accountKey || !sessionKey) return { decision };
+
+ try {
+ const defaultMaxOutputTokens = defaultExecOutputTokens(
+ modelInfo?.truncationPolicy,
+ DEFAULT_EXEC_MAX_OUTPUT_TOKENS
+ );
+ const rendered = renderExecTool(tools, {}, { defaultMaxOutputTokens });
+ const codeModeInput = buildCodeModeInput(
+ Array.isArray(claudeRequest.messages) ? claudeRequest.messages : [],
+ stores,
+ { accountKey, sessionKey },
+ { defaultMaxOutputTokens, toolNames: rendered.names }
+ );
+ const prePayload = structuredClone(payload);
+ const context: CodeModePayloadContext = {
+ shape: decision.shape,
+ execTool: rendered.tool,
+ input: codeModeInput,
+ sessionKey,
+ modelInfo,
+ };
+ const request = applyCodeModeToPayload(structuredClone(payload), context);
+ return {
+ decision,
+ request,
+ prePayload,
+ context,
+ turn: {
+ accountKey,
+ sessionKey,
+ names: rendered.names,
+ allTools: rendered.allTools,
+ defaultMaxOutputTokens,
+ },
+ };
+ } catch (err) {
+ log(`[CodeMode] request build failed; sending this request non-code-mode: ${err}`);
+ return { decision };
+ }
+}
diff --cc packages/cli/src/code-mode/resume.ts
index 5a8fca61,00000000..65c364c8
mode 100644,000000..100644
--- a/packages/cli/src/code-mode/resume.ts
+++ b/packages/cli/src/code-mode/resume.ts
@@@ -1,692 -1,0 +1,692 @@@
+/**
+ * Step 5r: resume a suspended exec script from the tool_results Claude Code
+ * sends back (architecture §5.9).
+ *
- * Runs after 5b, so the account is THIS request's (its binding), and after 3c,
- * so a synthetic reply gets the same Layer 4 hooks as a driver batch. It is
++ * Runs after 5b, so the account is THIS request's (its binding), and after 3b,
++ * so a synthetic reply gets the same hooks as a driver batch. It is
+ * synchronous from the record lookup to the state transition (no `await` in
+ * between), so two concurrent requests for one record serialise: the second
+ * sees the batch already consumed.
+ *
+ * Guard (else nothing is touched and the request continues): `openai-codex`
+ * (the caller's check), the binding's arm is `oauth`, an account key, a Claude
+ * Code session id, ≥ 1 declared tool (5d's `no-tools` gate), and `tool_choice`
+ * absent or `auto`. A named tool, `any` or
+ * `none` never resumes a script: such requests are Claude Code's internal
+ * one-shot calls, and consuming a batch there would run the script's next tools
+ * outside the turn that owns it; the next ordinary request resumes it.
+ *
+ * Every rule below reads the conversation's messages only (`conversationMessages`):
+ * Claude Code's inline `role: "system"` messages, which 2.1.303 puts LAST, are
+ * skipped, so "the last message" is the last user or assistant message.
+ *
+ * Entry: the last user message carries tool_results whose ids decode as nested
+ * ids. Only a suspended record owned by this session is resumed:
+ *
+ * | situation | behaviour |
+ * |-------------------------------------------------|--------------------------------------------|
+ * | expected batch, no interrupt | resolve/reject by seq, resume: blocked → |
+ * | | synthetic reply; done → output stored, |
+ * | | the upstream turn continues |
+ * | a result missing for an emitted id | that call rejects "no tool_result returned"|
+ * | interrupt (`[Request interrupted by user…`) | terminated: output so far + the results + |
+ * | | "interrupted by the user"; continue |
+ * | consumed batch, same batchHash (duplicate) | the memoised step: the same synthetic |
+ * | | reply, or the stored completion |
+ * | late results for a settled record | nothing (history renders its output) |
+ * | consumed batch, different batchHash (rewind) | lost path: tombstone, new completion key |
+ * | suspended, owned by ANOTHER session (a fork) | untouched; the fork gets a tombstone |
+ * | record lost (eviction, poisoned module) or none | lost path: `Script failed` + the results, |
+ * | (restart, another account) | stored as a tombstone (a minimal record |
+ * | | when none), so later turns render it too |
+ *
+ * Then, for every OTHER suspended record this session owns: if a message
+ * follows the assistant message carrying its pending batch and nothing answers
+ * that batch, the conversation moved on → terminated. A pending batch on the
+ * LAST message (a prefill) or absent from this request (a subagent sharing the
+ * session id; compaction) is left alone: TTL and LRU end it.
+ */
+
- import { extractSessionId } from "../behavior/harness.js";
+import type { ClaudeToolChoice } from "../handlers/shared/format/openai-tools.js";
++import { extractSessionId } from "../hooks/harness.js";
+import { log } from "../logger.js";
+import type { AuthBinding } from "../providers/transport/types.js";
+import type { ClaudeToolLike } from "./exec-tool.js";
+import { type BatchResultEntry, batchHash, completionKey } from "./hashes.js";
+import { accountKeyFromBinding, decodeNestedId, sessionKeyFor } from "./ids.js";
+import { LOST_SCRIPT_NOTE, MOVED_ON_NOTE, reconstructExecSource } from "./input-builder.js";
+import type { ExecOutput, OutputPart } from "./output.js";
+import type { CodeModeSetting } from "./policy.js";
+import { nestedBlocksFor, settleDone, suspendBlocked } from "./relay.js";
+import { replayLostScript } from "./replay.js";
+import { currentQuickJSModule } from "./sandbox/quickjs-loader.js";
+import type { NestedResult } from "./sandbox/script-runtime.js";
+import type { ExecRecord, ScriptStore } from "./script-store.js";
+import type { CodeModeStores } from "./stores.js";
+import { normalizeToolIdent } from "./tool-names.js";
+import { nestedResultFromToolResult, toolResultImages, toolResultText } from "./tool-results.js";
+import {
+ type ClaudeContentBlock,
+ type ClaudeMessage,
+ type NestedToolUse,
+ conversationMessages,
+} from "./types.js";
+
+/** Claude Code's interrupt marker (2.1.290: a user text block beside the results). */
+export const INTERRUPT_MARKER = "[Request interrupted by user";
+export const INTERRUPTED_NOTE = "interrupted by the user";
+export const FORKED_SCRIPT_NOTE =
+ "this script belongs to the session this one was forked from; claudish cannot run it twice";
+
+/** What 5r decided for one request. */
+export type ResumeOutcome =
+ /** Nothing to resume (or the guard does not hold): the request continues unchanged. */
+ | { kind: "none" }
+ /** A script resolved or ended: the request continues to the upstream turn. */
+ | { kind: "continue" }
+ /** A script blocked again: answer with these tool_use blocks, no upstream call. */
+ | { kind: "reply"; blocks: [NestedToolUse, ...NestedToolUse[]] }
+ /**
+ * Only with `mayRequestModule`: a lost script this request could replay, and
+ * no sandbox module is loaded (a retired, poisoned or recycled one was
+ * dropped). Nothing was touched; the caller awaits `loadQuickJSModule()` and
+ * calls 5r again without `mayRequestModule`, so 5r itself never awaits.
+ */
+ | { kind: "needs-module" };
+
+export interface ResumeOptions {
+ /** The resolved code-mode setting; `off` turns matching suspended records lost. */
+ setting?: CodeModeSetting;
+ /**
+ * Creates the process's stores when none exist yet but the last message
+ * answers nested ids (the first request after a restart), so the lost-script
+ * tombstone is stored before 5d builds the input. Default: never create.
+ */
+ createStores?: () => CodeModeStores;
+ /** May answer `needs-module` (see ResumeOutcome). Default false: replay without a module tombstones. */
+ mayRequestModule?: boolean;
+}
+
+/** True when the last message is a user message carrying a tool_result for a nested id. */
+function lastMessageAnswersNestedIds(messages: ClaudeMessage[]): boolean {
+ const last = messages[messages.length - 1];
+ if (last?.role !== "user") return false;
+ return blocksOf(last).some(
+ (b) =>
+ b.type === "tool_result" &&
+ typeof b.tool_use_id === "string" &&
+ decodeNestedId(b.tool_use_id) !== undefined
+ );
+}
+
+interface RequestView {
+ messages: ClaudeMessage[];
+ accountKey: string;
+ sessionKey: string;
+ /** tool_use id → its block (first occurrence, assistant messages). */
+ toolUses: Map<string, ClaudeContentBlock>;
+ /** tool_use id → its tool_result (first occurrence, user messages), as the input builder reads them. */
+ results: Map<string, ClaudeContentBlock>;
+ /** Claude Code's tools in this request (a replayed script calls them). */
+ tools: ClaudeToolLike[];
+}
+
+function blocksOf(message: ClaudeMessage | undefined): ClaudeContentBlock[] {
+ return message && Array.isArray(message.content) ? message.content : [];
+}
+
+function isAutoToolChoice(choice: ClaudeToolChoice | null | undefined): boolean {
+ return !choice || choice.type === undefined || choice.type === "auto";
+}
+
+function indexToolResults(messages: ClaudeMessage[]): Map<string, ClaudeContentBlock> {
+ const out = new Map<string, ClaudeContentBlock>();
+ for (const message of messages) {
+ if (message?.role !== "user") continue;
+ for (const block of blocksOf(message)) {
+ const id = block.tool_use_id;
+ if (block.type === "tool_result" && typeof id === "string" && !out.has(id))
+ out.set(id, block);
+ }
+ }
+ return out;
+}
+
+function indexToolUses(messages: ClaudeMessage[]): Map<string, ClaudeContentBlock> {
+ const out = new Map<string, ClaudeContentBlock>();
+ for (const message of messages) {
+ if (message?.role !== "assistant") continue;
+ for (const block of blocksOf(message)) {
+ if (block.type === "tool_use" && typeof block.id === "string" && !out.has(block.id)) {
+ out.set(block.id, block);
+ }
+ }
+ }
+ return out;
+}
+
+/** The batch's entries for hashing: each id with its tool_result, or missing. */
+function batchEntries(
+ ids: readonly string[],
+ results: ReadonlyMap<string, ClaudeContentBlock>
+): BatchResultEntry[] {
+ return ids.map((id) => {
+ const result = results.get(id);
+ return result
+ ? {
+ toolUseId: id,
+ result: { isError: result.is_error === true, content: result.content ?? "" },
+ }
+ : { toolUseId: id };
+ });
+}
+
+/** One text part per nested result (`tools.X({...}) returned:` …), images by reference. */
+export function resultParts(
+ ids: readonly string[],
+ results: ReadonlyMap<string, ClaudeContentBlock>,
+ toolUses: ReadonlyMap<string, ClaudeContentBlock>
+): OutputPart[] {
+ const parts: OutputPart[] = [];
+ for (const id of ids) {
+ const use = toolUses.get(id);
+ const name = typeof use?.name === "string" ? use.name : "";
+ const call = `tools.${normalizeToolIdent(name)}(${JSON.stringify(use?.input ?? {})})`;
+ const result = results.get(id);
+ if (!result) {
+ parts.push({ type: "text", text: `${call}: no tool_result returned` });
+ continue;
+ }
+ const verb = result.is_error === true ? "rejected" : "returned";
+ parts.push({ type: "text", text: `${call} ${verb}:\n${toolResultText(result)}` });
+ toolResultImages(result).forEach((_, index) => {
+ parts.push({ type: "image", ref: { toolUseId: id, index } });
+ });
+ }
+ return parts;
+}
+
+/** File a tool_result under its exec key when its id decodes as a nested id. */
+function addNestedResult(
+ groups: Map<string, Map<string, ClaudeContentBlock>>,
+ id: string,
+ block: ClaudeContentBlock
+): void {
+ const nested = decodeNestedId(id);
+ if (!nested) return;
+ let group = groups.get(nested.execKey);
+ if (!group) {
+ group = new Map();
+ groups.set(nested.execKey, group);
+ }
+ if (!group.has(id)) group.set(id, block);
+}
+
+/** The completion key of a record's batches 0..k, the last hashed from `lastHash`. */
+function keyThrough(record: ExecRecord, k: number, lastHash: string): string {
+ const hashes = record.batches.slice(0, k).map((b) => b.batchHash ?? "");
+ return completionKey([...hashes, lastHash]);
+}
+
+class Resume {
+ private readonly scripts: ScriptStore;
+
+ constructor(
+ private readonly view: RequestView,
+ stores: CodeModeStores
+ ) {
+ this.scripts = stores.scripts;
+ }
+
+ /** The last message's nested tool_results grouped by exec key, and whether it carries an interrupt. */
+ private lastMessageResults(): {
+ groups: Map<string, Map<string, ClaudeContentBlock>>;
+ interrupted: boolean;
+ } {
+ const groups = new Map<string, Map<string, ClaudeContentBlock>>();
+ let interrupted = false;
+ const last = this.view.messages[this.view.messages.length - 1];
+ if (last?.role !== "user") return { groups, interrupted };
+ for (const block of blocksOf(last)) {
+ if (block.type === "text" && typeof block.text === "string") {
+ if (block.text.trimStart().startsWith(INTERRUPT_MARKER)) interrupted = true;
+ } else if (block.type === "tool_result" && typeof block.tool_use_id === "string") {
+ addNestedResult(groups, block.tool_use_id, block);
+ }
+ }
+ return { groups, interrupted };
+ }
+
+ run(): ResumeOutcome {
+ const { groups, interrupted } = this.lastMessageResults();
+ const replies: NestedToolUse[] = [];
+ let resolved = false;
+ for (const [execKey, results] of groups) {
+ const outcome = this.resumeOne(execKey, results, interrupted);
+ if (outcome.kind === "reply") replies.push(...outcome.blocks);
+ else if (outcome.kind === "continue") resolved = true;
+ }
+ this.terminateMovedOn(new Set(groups.keys()));
+ const [first, ...rest] = replies;
+ if (first) return { kind: "reply", blocks: [first, ...rest] };
+ return resolved ? { kind: "continue" } : { kind: "none" };
+ }
+
+ private resumeOne(
+ execKey: string,
+ results: Map<string, ClaudeContentBlock>,
+ interrupted: boolean
+ ): ResumeOutcome {
+ const record = this.scripts.get(this.view.accountKey, execKey);
+ // An evicted runtime whose source is kept: re-run it against history first
+ // (on an interrupt, only up to the answered round, then ended there).
+ if (record?.state === "lost" && record.sessionKey === this.view.sessionKey) {
+ const replayed = this.replay(execKey, record, results, interrupted);
+ if (replayed) return replayed;
+ }
+ // Restart, another account's record, eviction or a poisoned module: the
+ // script state is gone; the model gets Script failed and the results.
+ if (!record || record.state === "lost")
+ return this.tombstone(execKey, record, LOST_SCRIPT_NOTE, results);
+ const k = record.batches.findIndex((b) => b.ids.some((id) => results.has(id)));
+ if (k < 0) return { kind: "none" };
+ const batch = record.batches[k];
+ const hash = batchHash(batchEntries(batch.ids, results));
+ // The script's state is a function of EVERY batch it consumed: a history
+ // whose earlier results differ (a rewind) cannot resume it or reuse a step.
+ if (!this.prefixMatches(record, k)) {
+ log(`[CodeMode] exec ${record.originalCallId}: earlier results changed; not resumable`);
+ return this.tombstone(execKey, record, LOST_SCRIPT_NOTE, results);
+ }
+
+ if (batch.batchHash !== undefined) {
+ return this.answerConsumed(execKey, record, k, batch.batchHash === hash, results);
+ }
+ if (record.state !== "suspended") return { kind: "none" };
+ // A fork answering the original's pending batch: never resumed and never
+ // touched; the owner's later answer resumes it and its run output wins.
+ if (record.sessionKey !== this.view.sessionKey) {
+ return this.tombstone(execKey, record, FORKED_SCRIPT_NOTE, results);
+ }
+ if (k !== record.batches.length - 1 || !record.runtime) return { kind: "none" };
+ batch.batchHash = hash;
+ try {
+ return this.consume(record, k, results, interrupted);
+ } catch (err) {
+ // A store or sandbox failure: the script is lost, the request goes on.
+ log(`[CodeMode] exec ${record.originalCallId}: resume failed; script lost: ${err}`);
+ this.loseQuietly(record);
+ return { kind: "none" };
+ }
+ }
+
+ /**
+ * Batches 0..k-1 as consumed equal this request's results for them, so
+ * `keyThrough` (which copies their hashes from the record) names the key the
+ * input builder computes from this history.
+ */
+ private prefixMatches(record: ExecRecord, k: number): boolean {
+ for (let j = 0; j < k; j++) {
+ const consumed = record.batches[j];
+ if (consumed.batchHash !== batchHash(batchEntries(consumed.ids, this.view.results))) {
+ return false;
+ }
+ }
+ return true;
+ }
+
+ /** Results for batch `k`, which the script already consumed. */
+ private answerConsumed(
+ execKey: string,
+ record: ExecRecord,
+ k: number,
+ sameResults: boolean,
+ results: ReadonlyMap<string, ClaudeContentBlock>
+ ): ResumeOutcome {
+ // Different results (a rewind that re-ran the tools): not resumable; a
+ // tombstone under the new completion key.
+ if (!sameResults) return this.tombstone(execKey, record, LOST_SCRIPT_NOTE, results);
+ // Another session (a fork) may read a completed output, never be handed
+ // the owner's next batch: its tools would run twice, once per session.
+ if (record.sessionKey !== this.view.sessionKey && record.batches[k + 1]?.blocks) {
+ return this.tombstone(execKey, record, FORKED_SCRIPT_NOTE, results);
+ }
+ return this.replayDuplicate(record, k);
+ }
+
+ /**
+ * The round the LAST message answers: the last round carrying one of its
+ * tool_result ids. Never searched over the whole request's results, which
+ * hold every earlier round too and so always matched round 0.
+ */
+ private answeredRound(
+ rounds: ReadonlyArray<{ ids: string[] }>,
+ answered: ReadonlyMap<string, ClaudeContentBlock>
+ ): number {
+ for (let k = rounds.length - 1; k >= 0; k--) {
+ if (rounds[k].ids.some((id) => answered.has(id))) return k;
+ }
+ return -1;
+ }
+
+ /**
+ * The exec's rounds in THIS request's history: the assistant messages that
+ * carry its nested ids, in order (the input builder groups them the same way).
+ */
+ private historyRounds(execKey: string): Array<{ ids: string[]; blocks: ClaudeContentBlock[] }> {
+ const rounds: Array<{ ids: string[]; blocks: ClaudeContentBlock[] }> = [];
+ const seen = new Set<string>();
+ for (const message of this.view.messages) {
+ if (message?.role !== "assistant") continue;
+ const blocks = blocksOf(message).filter(
+ (b) =>
+ b.type === "tool_use" &&
+ typeof b.id === "string" &&
+ !seen.has(b.id) &&
+ decodeNestedId(b.id)?.execKey === execKey
+ );
+ for (const b of blocks) seen.add(b.id as string);
+ if (blocks.length > 0) rounds.push({ ids: blocks.map((b) => b.id as string), blocks });
+ }
+ return rounds;
+ }
+
+ /**
+ * The lost path: `Script failed` with `note` and the results it was waiting
+ * for, stored as a TOMBSTONE under the completion key this request's history
+ * gives, so the input builder renders it now and byte-identically on every
+ * later request. No record (restart, another account) → a minimal one is
+ * created under this account and session; a `lost` record is answered
+ * (→ failed); a live record owned by another session is not touched beyond
+ * the tombstone, which only this session renders.
+ */
+ private tombstone(
+ execKey: string,
+ record: ExecRecord | undefined,
+ note: string,
+ lastResults: ReadonlyMap<string, ClaudeContentBlock>
+ ): ResumeOutcome {
+ const rounds = this.historyRounds(execKey);
+ const answered = this.answeredRound(rounds, lastResults);
+ if (answered < 0) return { kind: "none" };
+ try {
+ const key = completionKey(
+ rounds.slice(0, answered + 1).map((r) => batchHash(batchEntries(r.ids, this.view.results)))
+ );
+ const target =
+ record ??
+ this.scripts.create({
+ accountKey: this.view.accountKey,
+ sessionKey: this.view.sessionKey,
+ execCallId: execKey,
+ originalCallId: `call_${execKey}`,
+ source: reconstructExecSource(
+ rounds.map((r) =>
+ r.blocks.map((b) => ({
+ name: typeof b.name === "string" ? b.name : "",
+ input: b.input,
+ }))
+ )
+ ),
+ shape: "classic",
+ state: "lost",
+ });
+ if (target.state === "lost") this.scripts.transition(target, "answer");
+ const output: ExecOutput = {
+ status: "failed",
+ wallMs: undefined,
+ parts: [
+ { type: "text", text: note },
+ ...resultParts(rounds[answered].ids, this.view.results, this.view.toolUses),
+ ],
+ };
+ this.scripts.storeOutput(target, key, output, "tombstone", this.view.sessionKey);
+ log(
+ `[CodeMode] exec ${target.originalCallId}: answered as Script failed (${note.split(";")[0]})`
+ );
+ return { kind: "continue" };
+ } catch (err) {
+ log(`[CodeMode] exec call_${execKey}: storing the Script failed answer failed: ${err}`);
+ return { kind: "none" };
+ }
+ }
+
+ /** C6: replay a lost script from history when this request answers its LAST round. */
+ private replay(
+ execKey: string,
+ record: ExecRecord,
+ lastResults: ReadonlyMap<string, ClaudeContentBlock>,
+ interrupted: boolean
+ ): ResumeOutcome | undefined {
+ const rounds = this.historyRounds(execKey);
+ const answered = this.answeredRound(rounds, lastResults);
+ if (answered < 0 || answered !== rounds.length - 1) return undefined;
+ const replayed = replayLostScript({
+ scripts: this.scripts,
+ record,
+ rounds,
+ results: this.view.results,
+ tools: this.view.tools,
+ sessionKey: this.view.sessionKey,
+ interrupted,
+ });
+ if (!replayed) return undefined;
+ if (replayed.kind === "interrupted") {
+ // The live path's terminated output: what ran before the interrupt, the
+ // results it was waiting for, the note. No further tool call is emitted.
+ try {
+ const { output } = replayed;
+ output.parts.push(...resultParts(rounds[answered].ids, lastResults, this.view.toolUses));
+ output.parts.push({ type: "text", text: INTERRUPTED_NOTE });
+ this.scripts.storeOutput(record, replayed.key, output, "run", this.view.sessionKey);
+ this.scripts.transition(record, "terminate");
+ return { kind: "continue" };
+ } catch (err) {
+ log(`[CodeMode] exec ${record.originalCallId}: storing the interrupt failed: ${err}`);
+ return undefined;
+ }
+ }
+ return replayed.kind === "reply" ? replayed : { kind: "continue" };
+ }
+
+ /** A duplicate of a request already answered: the memoised step. */
+ private replayDuplicate(record: ExecRecord, k: number): ResumeOutcome {
+ const [first, ...rest] = record.batches[k + 1]?.blocks ?? [];
+ if (first) {
+ log(`[CodeMode] exec ${record.originalCallId}: duplicate request; same reply replayed`);
+ return { kind: "reply", blocks: [first, ...rest] };
+ }
+ // The stored completion answers it; the upstream turn starts again (the
+ // first answer never reached Claude Code; the script is the idempotency
+ // boundary, not the upstream turn).
+ return { kind: "continue" };
+ }
+
+ /** Feed batch `k`'s results to the suspended script (or end it on an interrupt). */
+ private consume(
+ record: ExecRecord,
+ k: number,
+ results: ReadonlyMap<string, ClaudeContentBlock>,
+ interrupted: boolean
+ ): ResumeOutcome {
+ const runtime = record.runtime as NonNullable<ExecRecord["runtime"]>;
+ const batch = record.batches[k];
+ const key = keyThrough(record, k, batch.batchHash ?? "");
+ if (interrupted) {
+ const output = runtime.terminate("");
+ output.parts.push(...resultParts(batch.ids, results, this.view.toolUses));
+ output.parts.push({ type: "text", text: INTERRUPTED_NOTE });
+ this.scripts.storeOutput(record, key, output, "run", this.view.sessionKey);
+ this.scripts.transition(record, "terminate");
+ log(`[CodeMode] exec ${record.originalCallId}: interrupted by the user; terminated`);
+ return { kind: "continue" };
+ }
+ const nestedResults: NestedResult[] = [];
+ for (const id of batch.ids) {
+ const seq = decodeNestedId(id)?.seq;
+ const block = results.get(id);
+ // A missing result is left out: the runtime rejects that call "no tool_result returned".
+ if (seq !== undefined && block) nestedResults.push(nestedResultFromToolResult(seq, block));
+ }
+ this.scripts.transition(record, "resume");
+ const step = runtime.resume(nestedResults);
+ if (step.kind === "blocked") {
+ const blocks = nestedBlocksFor(record.execCallId, step.calls);
+ suspendBlocked(this.scripts, record, blocks);
+ log(`[CodeMode] exec ${record.originalCallId}: resumed; blocked on ${blocks.length} call(s)`);
+ return { kind: "reply", blocks };
+ }
+ settleDone(this.scripts, record, step.output, key, this.view.sessionKey);
+ log(`[CodeMode] exec ${record.originalCallId}: resumed; ${step.output.status}`);
+ return { kind: "continue" };
+ }
+
+ private loseQuietly(record: ExecRecord): void {
+ try {
+ if (record.state === "running") this.scripts.transition(record, "fail");
+ else if (record.state === "suspended") this.scripts.transition(record, "evict");
+ } catch {
+ // Lost either way.
+ }
+ }
+
+ /** The other-entry scan: a pending batch the conversation moved past is terminated. */
+ private terminateMovedOn(handled: ReadonlySet<string>): void {
+ const { messages } = this.view;
+ for (const record of this.scripts.suspendedOwnedBy(this.view.sessionKey)) {
+ if (handled.has(record.execCallId)) continue;
+ const pending = record.batches[record.batches.length - 1];
+ if (!pending || pending.batchHash !== undefined) continue;
+ const ids = new Set(pending.ids);
+ const at = messages.findIndex(
+ (m) =>
+ m?.role === "assistant" &&
+ blocksOf(m).some((b) => b.type === "tool_use" && ids.has(b.id as string))
+ );
+ // Absent (another thread, compaction) or the last message (a prefill): leave it.
+ if (at < 0 || at === messages.length - 1) continue;
+ const answered = messages
+ .slice(at + 1)
+ .some((m) =>
+ blocksOf(m).some((b) => b.type === "tool_result" && ids.has(b.tool_use_id as string))
+ );
+ if (answered) continue;
+ try {
+ const output: ExecOutput = record.runtime
+ ? record.runtime.terminate(MOVED_ON_NOTE)
+ : {
+ status: "terminated",
+ wallMs: undefined,
+ parts: [{ type: "text", text: MOVED_ON_NOTE }],
+ };
+ const key = keyThrough(
+ record,
+ record.batches.length - 1,
+ batchHash(pending.ids.map((id) => ({ toolUseId: id })))
+ );
+ this.scripts.storeOutput(record, key, output, "run", this.view.sessionKey);
+ this.scripts.transition(record, "terminate");
+ log(`[CodeMode] exec ${record.originalCallId}: the conversation moved on; terminated`);
+ } catch (err) {
+ log(`[CodeMode] exec ${record.originalCallId}: terminating failed; script lost: ${err}`);
+ this.loseQuietly(record);
+ }
+ }
+ }
+
+ /**
+ * True when the last message answers a script this session owns whose
+ * runtime is gone but whose source is kept — the case `run()` replays.
+ * Read-only (`peek`, no transition), so a `needs-module` answer touches
+ * nothing.
+ */
+ wouldReplay(): boolean {
+ const { groups } = this.lastMessageResults();
+ for (const execKey of groups.keys()) {
+ const record = this.scripts.peek(this.view.accountKey, execKey);
+ if (!record || record.sessionKey !== this.view.sessionKey) continue;
+ if (!record.source || record.batches.length === 0) continue;
+ const runtimeGone =
+ record.state === "lost" ||
+ (record.state === "suspended" && (!record.runtime || !record.runtime.alive));
+ if (runtimeGone) return true;
+ }
+ return false;
+ }
+
+ /** Setting `off`: every suspended record the last message answers is lost (runtime disposed). */
+ loseAnswered(): void {
+ const { groups } = this.lastMessageResults();
+ for (const execKey of groups.keys()) {
+ const record = this.scripts.peek(this.view.accountKey, execKey);
+ if (record?.state === "suspended") {
+ log(`[CodeMode] exec ${record.originalCallId}: code mode is off; script dropped`);
+ this.scripts.transition(record, "evict");
+ }
+ }
+ }
+}
+
+/**
+ * Step 5r for one `openai-codex` request. Never throws and never awaits: a
+ * failure loses the script, never the request.
+ */
+export function resumeFromToolResults(
+ req: { messages?: unknown; metadata?: unknown; tools?: unknown },
+ binding: AuthBinding | undefined,
+ stores: CodeModeStores | undefined,
+ toolChoice: ClaudeToolChoice | null | undefined,
+ opts: ResumeOptions = {}
+): ResumeOutcome {
+ try {
+ if (binding?.auth?.arm !== "oauth") return { kind: "none" };
+ const accountKey = accountKeyFromBinding(binding);
+ const sessionKey = sessionKeyFor(extractSessionId(req), accountKey);
+ if (!accountKey || !sessionKey) return { kind: "none" };
+ if (!isAutoToolChoice(toolChoice)) return { kind: "none" };
+ // 5d's `no-tools` gate: a tool-less request (compaction, an internal
+ // summary) is never code mode, so it must not consume a batch, end the
+ // session's other scripts, or be answered with tool_use blocks.
+ const tools = Array.isArray(req.tools) ? (req.tools as ClaudeToolLike[]) : [];
+ if (tools.length === 0) return { kind: "none" };
+ // Only user/assistant: a trailing system message (Claude Code 2.1.303)
+ // is never "the last message" that answers a batch.
+ const messages = conversationMessages(req.messages);
+ let active = stores;
+ if (
+ !active &&
+ opts.setting !== "off" &&
+ opts.createStores &&
+ lastMessageAnswersNestedIds(messages)
+ ) {
+ // After a restart: no store, but history answers a script claudish no
+ // longer has. Without its tombstone the builder rendered `Script failed`
+ // now and `Script completed` on the next request for the same script.
+ active = opts.createStores();
+ }
+ if (!active) return { kind: "none" };
+ const resume = new Resume(
+ {
+ messages,
+ accountKey,
+ sessionKey,
+ toolUses: indexToolUses(messages),
+ results: indexToolResults(messages),
+ tools,
+ },
+ active
+ );
+ if (opts.setting === "off") {
+ resume.loseAnswered();
+ return { kind: "none" };
+ }
+ if (opts.mayRequestModule && !currentQuickJSModule() && resume.wouldReplay()) {
+ log("[CodeMode] a lost script can replay but no sandbox module is loaded; loading one first");
+ return { kind: "needs-module" };
+ }
+ return resume.run();
+ } catch (err) {
+ log(`[CodeMode] resume step failed; continuing without it: ${err}`);
+ return { kind: "none" };
+ }
+}
diff --cc packages/cli/src/code-mode/script-store.ts
index a5a1f674,00000000..1e7a5827
mode 100644,000000..100644
--- a/packages/cli/src/code-mode/script-store.ts
+++ b/packages/cli/src/code-mode/script-store.ts
@@@ -1,524 -1,0 +1,524 @@@
+/**
+ * Exec records: one per exec call relayed with code mode on, keyed
+ * `(accountKey, execCallId)`, holding the script source, its suspended runtime
+ * while it waits on Claude Code, the batches it emitted and the outputs it
+ * produced.
+ *
+ * Why keyed by account and not by session: upstream call ids are unique, so a
+ * forked session (`--fork-session`: new session id, same history, same account)
+ * still finds its execs and renders their completed outputs byte-identically.
+ * Each record stores its OWNER `sessionKey`; only the owner may resume it. A
+ * request on another account computes another `accountKey` and never finds,
+ * resumes or renders this account's records.
+ *
+ * States — the State pattern's transition-table form (`patterns/state.md`),
+ * chosen because the states differ only in which transitions are legal:
+ *
+ * running: block → suspended, finish → completed, fail → failed
+ * suspended: resume → running, terminate → terminated, abandon → terminated,
+ * evict → lost, expire → lost
+ * lost: answer → failed (tombstone stored), replay → running,
+ * terminate → terminated (replayed up to a user interrupt)
+ * completed / failed / terminated: answer → same state
+ *
+ * The catalog's table throws on an illegal transition. Here it is logged and
+ * coerced to `lost`, never thrown: this runs on the request path, and a refused
+ * request is worse than a degraded script. Every transition that ends a runtime
+ * disposes it.
+ *
+ * Every store has a byte ceiling the model cannot raise (architecture §5.8):
+ * settled records (anything but running/suspended) are capped at 2,000 records
+ * AND 32 MiB, counting the UTF-8 length of the source, every stored output's
+ * text plus 64 bytes per output part, and the reasoning items' JSON (images
+ * are references, never bytes).
+ * Eviction is LRU by `lastTouched`; an evicted record's id goes to a bounded
+ * FIFO set, so the input builder can say "evicted" rather than "restart".
+ * Suspended records are bounded by the sandbox's live-runtime cap (32) and a
+ * 6 h idle TTL. A 60 s reaper applies the TTL and the caps.
+ */
+
+import { log } from "../logger.js";
+import { inputHash } from "./hashes.js";
+import type { ExecOutput } from "./output.js";
+import type { ScriptRuntime } from "./sandbox/script-runtime.js";
+import type { NestedToolUse, ResponsesItem } from "./types.js";
+
+export type ExecState = "running" | "suspended" | "completed" | "failed" | "terminated" | "lost";
+
+export type ExecEvent =
+ | "block"
+ | "finish"
+ | "fail"
+ | "resume"
+ | "terminate"
+ | "abandon"
+ | "evict"
+ | "expire"
+ | "answer"
+ | "replay";
+
+/** The legal transitions; anything absent is illegal (logged, coerced to `lost`). */
+const TRANSITIONS: Record<ExecState, Partial<Record<ExecEvent, ExecState>>> = {
+ running: { block: "suspended", finish: "completed", fail: "failed" },
+ suspended: {
+ resume: "running",
+ terminate: "terminated",
+ abandon: "terminated",
+ evict: "lost",
+ expire: "lost",
+ },
+ lost: { answer: "failed", replay: "running", terminate: "terminated" },
+ completed: { answer: "completed" },
+ failed: { answer: "failed" },
+ terminated: { answer: "terminated" },
+};
+
+/** Events after which the runtime is gone. */
+const ENDS_RUNTIME = new Set<ExecEvent>([
+ "finish",
+ "fail",
+ "terminate",
+ "abandon",
+ "evict",
+ "expire",
+ "answer",
+]);
+
+/** An output stored for one completion key. */
+export interface StoredOutput {
+ output: ExecOutput;
+ /** `run`: the script produced it; `tombstone`: claudish answered for a lost script. */
+ origin: "run" | "tombstone";
+ /** The session that stored it (a tombstone is rendered only for that session). */
+ sessionKey: string;
+}
+
+/** One emitted batch: the nested tool_use ids, and its hash once consumed. */
+export interface ExecBatch {
+ ids: string[];
+ batchHash?: string;
+ /**
+ * The tool_use blocks as relayed, kept only while the record is live, so a
+ * duplicate request can replay the same reply (dropped when it settles: the
+ * inputs are up to 8 MiB a batch and are not in the byte cap).
+ */
+ blocks?: NestedToolUse[];
+ /**
- * The Layer 4 repairs of this batch, by nested id: hashes of the script's
++ * The recorded repairs of this batch, by nested id: hashes of the script's
+ * own input and of the input relayed instead. Taken from `blocks` when they
+ * are dropped, so a replay can accept history's repaired input for a call.
+ */
+ repairs?: Record<string, { script: string; relayed: string }>;
+}
+
+/** Keep a batch's repairs as hashes, then drop its blocks. */
+function compactBatch(batch: ExecBatch): void {
+ for (const block of batch.blocks ?? []) {
+ if (block.scriptInput === undefined) continue;
+ batch.repairs ??= {};
+ batch.repairs[block.id] = {
+ script: inputHash(block.scriptInput),
+ relayed: inputHash(block.input),
+ };
+ }
+ batch.blocks = undefined;
+}
+
+export interface ExecRecord {
+ accountKey: string;
+ /** The owner: only this session may resume the script. */
+ sessionKey: string;
+ /** The 32-hex exec key (`execKeyFor`), the key nested ids carry. */
+ execCallId: string;
+ /** The upstream `call_id` as the model sent it. */
+ originalCallId: string;
+ source: string;
+ shape: "lite" | "classic";
+ state: ExecState;
+ runtime?: ScriptRuntime;
+ batches: ExecBatch[];
+ /** Outputs by completion key (`hashes.ts`). */
+ outputs: Map<string, StoredOutput>;
+ /** The reasoning items of the leg that produced the exec. */
+ reasoningItems?: ResponsesItem[];
+ /** The exec's output budget in tokens (pragma, else the default) when it was relayed. */
+ maxOutputTokens?: number;
+ startedAt: number;
+ lastTouched: number;
+ /** Counted bytes (source + output text + reasoning JSON). */
+ bytes: number;
+}
+
+export interface ScriptStoreLimits {
+ maxRecords: number;
+ maxBytes: number;
+ suspendedTtlMs: number;
+ maxEvictedIds: number;
+ reapIntervalMs: number;
+}
+
+export const DEFAULT_SCRIPT_STORE_LIMITS: ScriptStoreLimits = {
+ maxRecords: 2_000,
+ maxBytes: 32 * 1024 * 1024,
+ suspendedTtlMs: 6 * 60 * 60 * 1000,
+ maxEvictedIds: 20_000,
+ reapIntervalMs: 60_000,
+};
+
+export interface NewExecRecord {
+ accountKey: string;
+ sessionKey: string;
+ execCallId: string;
+ originalCallId: string;
+ source: string;
+ shape: "lite" | "classic";
+ state?: ExecState;
+ reasoningItems?: ResponsesItem[];
+ maxOutputTokens?: number;
+}
+
+function utf8Bytes(text: string): number {
+ return Buffer.byteLength(text, "utf8");
+}
+
+/**
+ * What one stored output part costs beyond its text: the host object and its
+ * Responses part. Without it, parts with little or no text were free.
+ */
+const PART_OVERHEAD_BYTES = 64;
+
+function outputBytes(output: ExecOutput): number {
+ let bytes = output.error ? utf8Bytes(output.error) : 0;
+ for (const part of output.parts) {
+ bytes += PART_OVERHEAD_BYTES;
+ if (part.type === "text") bytes += utf8Bytes(part.text);
+ }
+ return bytes;
+}
+
+function recordBytes(record: ExecRecord): number {
+ let bytes = utf8Bytes(record.source);
+ for (const stored of record.outputs.values()) bytes += outputBytes(stored.output);
+ if (record.reasoningItems) bytes += utf8Bytes(JSON.stringify(record.reasoningItems));
+ for (const batch of record.batches) {
+ // Two 64-hex sha256 strings per repaired call, plus its nested id.
+ for (const id of Object.keys(batch.repairs ?? {})) bytes += utf8Bytes(id) + 128;
+ }
+ return bytes;
+}
+
+function recordKey(accountKey: string, execCallId: string): string {
+ return `${accountKey}\0${execCallId}`;
+}
+
+function isLive(state: ExecState): boolean {
+ return state === "running" || state === "suspended";
+}
+
+/** A bounded FIFO set of ids. */
+class BoundedIdSet {
+ private readonly ids = new Set<string>();
+ constructor(private readonly max: number) {}
+ add(id: string): void {
+ this.ids.delete(id);
+ this.ids.add(id);
+ while (this.ids.size > this.max) {
+ const oldest = this.ids.values().next().value;
+ if (oldest === undefined) break;
+ this.ids.delete(oldest);
+ }
+ }
+ has(id: string): boolean {
+ return this.ids.has(id);
+ }
+ delete(id: string): void {
+ this.ids.delete(id);
+ }
+ get size(): number {
+ return this.ids.size;
+ }
+}
+
+export class ScriptStore {
+ private readonly records = new Map<string, ExecRecord>();
+ private readonly evicted: BoundedIdSet;
+ private readonly pins: BoundedIdSet;
+ private readonly limits: ScriptStoreLimits;
+ private readonly now: () => number;
+ private settledBytes = 0;
+ private reaper: ReturnType<typeof setInterval> | undefined;
+
+ constructor(opts: { limits?: Partial<ScriptStoreLimits>; now?: () => number } = {}) {
+ this.limits = { ...DEFAULT_SCRIPT_STORE_LIMITS, ...opts.limits };
+ this.now = opts.now ?? Date.now;
+ this.evicted = new BoundedIdSet(this.limits.maxEvictedIds);
+ this.pins = new BoundedIdSet(this.limits.maxEvictedIds);
+ }
+
+ // ─── records ────────────────────────────────────────────────────────
+
+ /** Create (or replace) the record for an exec. */
+ create(init: NewExecRecord): ExecRecord {
+ const key = recordKey(init.accountKey, init.execCallId);
+ const existing = this.records.get(key);
+ if (existing) this.remove(existing);
+ const now = this.now();
+ const record: ExecRecord = {
+ accountKey: init.accountKey,
+ sessionKey: init.sessionKey,
+ execCallId: init.execCallId,
+ originalCallId: init.originalCallId,
+ source: init.source,
+ shape: init.shape,
+ state: init.state ?? "running",
+ batches: [],
+ outputs: new Map(),
+ reasoningItems: init.reasoningItems,
+ maxOutputTokens: init.maxOutputTokens,
+ startedAt: now,
+ lastTouched: now,
+ bytes: 0,
+ };
+ record.bytes = recordBytes(record);
+ this.records.set(key, record);
+ this.evicted.delete(key);
+ if (!isLive(record.state)) {
+ this.settledBytes += record.bytes;
+ this.enforceCaps();
+ }
+ return record;
+ }
+
+ /**
+ * The record, touched. A suspended record whose runtime is gone (module
+ * poisoned, evicted by the live cap) is moved to `lost` first.
+ */
+ get(accountKey: string, execCallId: string): ExecRecord | undefined {
+ const record = this.records.get(recordKey(accountKey, execCallId));
+ if (!record) return undefined;
+ record.lastTouched = this.now();
+ this.loseIfRuntimeGone(record);
+ return record;
+ }
+
+ /**
+ * A suspended record whose runtime is gone (evicted for the live cap, a
+ * retired or poisoned module) moves to `lost` NOW, so it leaves the
+ * suspended set and enters the settled caps. The runtime's `onEvicted`
+ * calls this; `get()` and the reaper catch any it missed.
+ */
+ loseIfRuntimeGone(record: ExecRecord): void {
+ if (record.state === "suspended" && (!record.runtime || !record.runtime.alive)) {
+ this.transition(record, "evict");
+ }
+ }
+
+ /** The record without touching it or checking its runtime. */
+ peek(accountKey: string, execCallId: string): ExecRecord | undefined {
+ return this.records.get(recordKey(accountKey, execCallId));
+ }
+
+ /** True when the record was evicted under the caps (not merely never seen). */
+ isEvicted(accountKey: string, execCallId: string): boolean {
+ return this.evicted.has(recordKey(accountKey, execCallId));
+ }
+
+ /** Every suspended record owned by `sessionKey`. */
+ suspendedOwnedBy(sessionKey: string): ExecRecord[] {
+ const out: ExecRecord[] = [];
+ for (const record of this.records.values()) {
+ if (record.state === "suspended" && record.sessionKey === sessionKey) out.push(record);
+ }
+ return out;
+ }
+
+ /**
+ * Apply `event`. An illegal transition is logged and coerced to `lost`
+ * (never thrown). Returns the new state.
+ */
+ transition(record: ExecRecord, event: ExecEvent): ExecState {
+ const from = record.state;
+ const legal = TRANSITIONS[from][event];
+ const to: ExecState = legal ?? "lost";
+ if (!legal) {
+ log(
+ `[CodeMode] exec ${record.execCallId}: illegal transition ${event} from ${from}; record coerced to lost`
+ );
+ }
+ if (!legal || ENDS_RUNTIME.has(event)) this.disposeRuntime(record);
+ const wasLive = isLive(from);
+ record.state = to;
+ record.lastTouched = this.now();
+ const nowLive = isLive(to);
+ if (!nowLive) for (const batch of record.batches) compactBatch(batch);
+ // Re-counted here: compaction adds the repair hashes the settled cap must see.
+ const before = record.bytes;
+ record.bytes = recordBytes(record);
+ if (wasLive && !nowLive) this.settledBytes += record.bytes;
+ else if (!wasLive && nowLive) this.settledBytes -= before;
+ else if (!wasLive) this.settledBytes += record.bytes - before;
+ if (!nowLive) this.enforceCaps();
+ return to;
+ }
+
+ /** Attach a runtime to a running record (the store disposes it on the ending transitions). */
+ attachRuntime(record: ExecRecord, runtime: ScriptRuntime): void {
+ if (record.runtime && record.runtime !== runtime) record.runtime.dispose();
+ record.runtime = runtime;
+ }
+
+ /** Store the reasoning items of the leg that produced the exec. */
+ setReasoning(record: ExecRecord, items: ResponsesItem[] | undefined): void {
+ this.rebytes(record, () => {
+ record.reasoningItems = items && items.length > 0 ? items : undefined;
+ });
+ }
+
+ /**
+ * Store `output` under `completionKey`. A tombstone never overwrites a `run`
+ * output for the same key.
+ */
+ storeOutput(
+ record: ExecRecord,
+ completionKey: string,
+ output: ExecOutput,
+ origin: StoredOutput["origin"],
+ sessionKey: string
+ ): void {
+ const existing = record.outputs.get(completionKey);
+ if (existing?.origin === "run" && origin === "tombstone") return;
+ this.rebytes(record, () => {
+ record.outputs.set(completionKey, { output, origin, sessionKey });
+ });
+ record.lastTouched = this.now();
+ if (!isLive(record.state)) this.enforceCaps();
+ }
+
+ /**
+ * The output to render for `completionKey`: a `run` output from any session
+ * (a function of source + results, so a fork with the same history renders it
+ * identically), else a tombstone stored by THIS session.
+ */
+ lookupOutput(
+ accountKey: string,
+ execCallId: string,
+ completionKey: string,
+ sessionKey: string
+ ): StoredOutput | undefined {
+ const record = this.records.get(recordKey(accountKey, execCallId));
+ const stored = record?.outputs.get(completionKey);
+ if (!stored) return undefined;
+ if (stored.origin === "run" || stored.sessionKey === sessionKey) {
+ if (record) record.lastTouched = this.now();
+ return stored;
+ }
+ return undefined;
+ }
+
+ // ─── pins ───────────────────────────────────────────────────────────
+
+ /** This session relayed an exec: keep it in code mode while its arm stays OAuth. */
+ pin(sessionKey: string): void {
+ this.pins.add(sessionKey);
+ }
+
+ isPinned(sessionKey: string): boolean {
+ return this.pins.has(sessionKey);
+ }
+
+ // ─── caps and reaping ───────────────────────────────────────────────
+
+ /** Lose suspended records whose runtime is gone, expire idle ones, enforce the caps. */
+ reap(): void {
+ const now = this.now();
+ for (const record of [...this.records.values()]) {
+ this.loseIfRuntimeGone(record);
+ if (record.state === "suspended" && now - record.lastTouched > this.limits.suspendedTtlMs) {
+ this.transition(record, "expire");
+ }
+ }
+ this.enforceCaps();
+ }
+
+ /** Start the 60 s reaper (idempotent; unref'd so it never holds the process). */
+ startReaper(): void {
+ if (this.reaper) return;
+ this.reaper = setInterval(() => {
+ try {
+ this.reap();
+ } catch (err) {
+ log(`[CodeMode] script store reaper failed: ${err}`);
+ }
+ }, this.limits.reapIntervalMs);
+ this.reaper.unref?.();
+ }
+
+ stopReaper(): void {
+ if (this.reaper) clearInterval(this.reaper);
+ this.reaper = undefined;
+ }
+
+ /** Records currently held. */
+ get size(): number {
+ return this.records.size;
+ }
+
+ /** Counted bytes of settled records (the 32 MiB cap applies to this). */
+ get bytes(): number {
+ return this.settledBytes;
+ }
+
+ /** Drop everything, disposing every runtime (tests; a process reset). */
+ clear(): void {
+ for (const record of this.records.values()) this.disposeRuntime(record);
+ this.records.clear();
+ this.settledBytes = 0;
+ }
+
+ private settledCount(): number {
+ let n = 0;
+ for (const record of this.records.values()) if (!isLive(record.state)) n++;
+ return n;
+ }
+
+ private enforceCaps(): void {
+ let count = this.settledCount();
+ if (count <= this.limits.maxRecords && this.settledBytes <= this.limits.maxBytes) return;
+ const settled = [...this.records.values()]
+ .filter((r) => !isLive(r.state))
+ .sort((a, b) => a.lastTouched - b.lastTouched);
+ for (const record of settled) {
+ if (count <= this.limits.maxRecords && this.settledBytes <= this.limits.maxBytes) break;
+ this.remove(record);
+ this.evicted.add(recordKey(record.accountKey, record.execCallId));
+ count--;
+ }
+ log(
+ `[CodeMode] script store over its cap; evicted to ${count} record(s), ${this.settledBytes} bytes`
+ );
+ }
+
+ private remove(record: ExecRecord): void {
+ this.disposeRuntime(record);
+ this.records.delete(recordKey(record.accountKey, record.execCallId));
+ if (!isLive(record.state)) this.settledBytes -= record.bytes;
+ }
+
+ private rebytes(record: ExecRecord, mutate: () => void): void {
+ const before = record.bytes;
+ mutate();
+ record.bytes = recordBytes(record);
+ if (!isLive(record.state)) this.settledBytes += record.bytes - before;
+ }
+
+ private disposeRuntime(record: ExecRecord): void {
+ const runtime = record.runtime;
+ record.runtime = undefined;
+ if (!runtime) return;
+ try {
+ runtime.dispose();
+ } catch (err) {
+ log(`[CodeMode] exec ${record.execCallId}: disposing its runtime failed: ${err}`);
+ }
+ }
+}
diff --cc packages/cli/src/code-mode/types.ts
index 40a33c46,00000000..2f1b5c93
mode 100644,000000..100644
--- a/packages/cli/src/code-mode/types.ts
+++ b/packages/cli/src/code-mode/types.ts
@@@ -1,126 -1,0 +1,126 @@@
+/**
+ * Shapes shared by the code-mode modules: Responses `input` items and the
+ * parts of Claude Code's `/v1/messages` body the input builder and the stores
+ * read. Deliberately loose: both sides are external wire formats, and code mode
+ * only ever reads the fields named here.
+ */
+
+/** One Responses `input` item (message, reasoning, custom_tool_call, custom_tool_call_output, …). */
+export interface ResponsesItem {
+ type: string;
+ [field: string]: unknown;
+}
+
+/** A content block of a Claude Code message. */
+export interface ClaudeContentBlock {
+ type: string;
+ text?: string;
+ id?: string;
+ name?: string;
+ input?: unknown;
+ tool_use_id?: string;
+ content?: unknown;
+ is_error?: boolean;
+ source?: unknown;
+ [field: string]: unknown;
+}
+
+/** One message of `claudeRequest.messages`. */
+export interface ClaudeMessage {
+ role: string;
+ content: string | ClaudeContentBlock[];
+}
+
+/**
+ * The conversation's own messages: `user` and `assistant`, in order.
+ *
+ * Claude Code also sends `role: "system"` messages INSIDE `messages` (the
+ * SessionStart hook's output, MCP server instructions, the token reminder), and
+ * 2.1.303 ENDS a request with one: `user, system, assistant(tool_use×3),
+ * user(tool_result×3), system`. Code mode reasons about message ORDER — the
+ * last message, the message before an assistant message, a message after a
+ * batch — so it reads this view: a trailing system message hid every batch's
+ * answer and no script ever resumed. The input builder never rendered a system
+ * message, so dropping them changes no output.
+ */
+export function conversationMessages(messages: unknown): ClaudeMessage[] {
+ if (!Array.isArray(messages)) return [];
+ return messages.filter((m): m is ClaudeMessage => m?.role === "user" || m?.role === "assistant");
+}
+
+/** A nested tool call relayed to Claude Code as one tool_use block. */
+export interface NestedToolUse {
+ /** `toolu_cx_<hex>_<seq>` (`encodeNestedId`). */
+ id: string;
+ /** Claude Code's own tool name. */
+ name: string;
- /** The input as relayed to Claude Code (after a Layer 4 repair, when one applied). */
++ /** The input as relayed to Claude Code (after a recorded repair, when one applied). */
+ input: Record<string, unknown>;
- /** The script's own input, set only when Layer 4 repaired what was relayed. */
++ /** The script's own input, set only when a recorded repair changed what was relayed. */
+ scriptInput?: Record<string, unknown>;
+}
+
+/**
- * The input JSON Claude Code gets for `block`: `repair` (Layer 4) applied ONCE
++ * The input JSON Claude Code gets for `block`: `repair` applied ONCE
+ * to the script's input. A repaired input is written back onto the block — the
+ * exec record holds the same object — with the script's own kept as
+ * `scriptInput`, so a duplicate reply re-sends exactly what was relayed and a
+ * replay can tell a repair from a divergence. A pure function, safe for the
+ * turn driver to import (it loads no sandbox).
+ */
+export function relayNestedInput(
+ block: NestedToolUse,
+ repair: (name: string, argsJson: string) => string
+): string {
+ const args = JSON.stringify(block.input ?? {});
+ if (block.scriptInput !== undefined) return args;
+ const sent = repair(block.name, args);
+ if (sent === args) return args;
+ try {
+ const parsed: unknown = JSON.parse(sent);
+ if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+ block.scriptInput = block.input;
+ block.input = parsed as Record<string, unknown>;
+ }
+ } catch {
+ // An unparsable repair is sent as it is and not recorded.
+ }
+ return sent;
+}
+
+/**
+ * What the turn driver does after an exec call: relay the script's batch as
+ * tool_use blocks (the message ends `tool_use`), or continue the turn with
+ * another upstream leg whose input carries the exec items.
+ */
+export type ExecTurnStep =
+ | { kind: "emit-tool-uses"; blocks: [NestedToolUse, ...NestedToolUse[]] }
+ | { kind: "continue"; appendItems: ResponsesItem[] };
+
+/**
+ * How the Responses turn driver reaches code mode. The driver never imports
+ * code mode itself, so classic providers never load QuickJS.
+ */
+export interface CodeModeTurnHooks {
+ /**
+ * An exec call ended a leg. `precedingItems` are that leg's assistant text
+ * and reasoning items in order; `truncated` means `response.incomplete` cut
+ * the exec input, which is then never run. Never rejects: a store or sandbox
+ * failure becomes a `Script failed` continuation.
+ */
+ onExecCall(call: {
+ callId: string;
+ input: string;
+ precedingItems: ResponsesItem[];
+ truncated: boolean;
+ }): ExecTurnStep | Promise<ExecTurnStep>;
+ /**
+ * The message ended: store its Responses items (they end before the final
+ * exec call when it ended on nested calls). `anchor` is the message's first
+ * tool_use id; undefined when it has none, and `texts` (its text blocks, in
+ * order) then derive it.
+ */
+ onTurnEnd(record: { anchor?: string; items: ResponsesItem[]; texts: string[] }): void;
+ /** The client went away before the `message_stop` of a relayed batch. */
+ onTurnAbandoned(callId: string): void;
+}
diff --cc packages/cli/src/handlers/advisor-claude-arm.test.ts
index 2e6bb33f,00000000..a67e56d8
mode 100644,000000..100644
--- a/packages/cli/src/handlers/advisor-claude-arm.test.ts
+++ b/packages/cli/src/handlers/advisor-claude-arm.test.ts
@@@ -1,447 -1,0 +1,447 @@@
+import { afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
- import type { ChildAuthControl } from "../claude-runner.js";
++import type { ChildAuthControl } from "../child-auth-types.js";
+import type { ClaudeAdvisorAuth, ClaudeRequestFacts } from "./native-handler-advisor.js";
+import type { SigningSecrets } from "./shared/call-context.js";
+
+const FILE = import.meta.path;
+const TIMEOUT = 20_000;
+
+if (process.env.T4_ISOLATED_FILE !== FILE) {
+ test(
+ "T4 G2/G4 runs with an isolated HOME and no inherited credentials",
+ async () => {
+ const home = mkdtempSync(join(tmpdir(), "t4-claude-arm-"));
+ const env = { ...process.env };
+ for (const key of Object.keys(env)) {
+ if (/^(ANTHROPIC|CLAUDE|CLAUDISH|OPENAI|OP_)/.test(key)) delete env[key];
+ }
+ const child = Bun.spawn([process.execPath, "test", FILE], {
+ cwd: home,
+ env: {
+ ...env,
+ HOME: home,
+ CLAUDE_CONFIG_DIR: join(home, "claude"),
+ T4_ISOLATED_FILE: FILE,
+ },
+ stdin: "ignore",
+ stdout: "pipe",
+ stderr: "pipe",
+ });
+ try {
+ const [code, stdout, stderr] = await Promise.all([
+ child.exited,
+ new Response(child.stdout).text(),
+ new Response(child.stderr).text(),
+ ]);
+ console.info(stdout + stderr);
+ expect(code).toBe(0);
+ } finally {
+ child.kill();
+ rmSync(home, { recursive: true, force: true });
+ }
+ },
+ TIMEOUT
+ );
+} else {
+ let api: typeof import("./native-handler-advisor.js");
+ let callContext: typeof import("./shared/call-context.js");
+ let wrapAnthropicError: typeof import("./shared/anthropic-error.js").wrapAnthropicError;
+ let calculateCost: typeof import("./shared/remote-provider-types.js").calculateCost;
+ let Hono: typeof import("hono").Hono;
+ const dataRoot = join(import.meta.dir, "../test-fixtures");
+ const inbound = readFileSync(join(dataRoot, "advisor/inbound-login.jsonl"), "utf8")
+ .trim()
+ .split("\n")
+ .map((line) => JSON.parse(line))
+ .find((entry) => entry.body?.toolsCount > 0);
+ const requestBody = JSON.parse(
+ readFileSync(join(dataRoot, "code-mode/cc-2.1.304-inbound-system.jsonl"), "utf8")
+ .trim()
+ .split("\n")[0]!
+ ).body;
+ const matrix = JSON.parse(
+ readFileSync(join(dataRoot, "advisor/replay-results-1792535094326.json"), "utf8")
+ );
+ const accepted = matrix.results.find((entry: any) => entry.shape === "A");
+ const refused = matrix.results.find((entry: any) => entry.shape === "A0");
+ const token = "OPAQUE_TEST_TOKEN_abc";
+ const inboundKey = "OPAQUE_TEST_KEY_inbound";
+ const resolvedKey = "OPAQUE_TEST_KEY_resolved";
+ const leases: SigningSecrets[] = [];
+ const noNetwork = (() => {
+ throw new Error("T4 forbids network");
+ }) as unknown as typeof fetch;
+ let successBody: string;
+
+ beforeAll(async () => {
+ globalThis.fetch = noNetwork;
+ api = await import("./native-handler-advisor.js");
+ callContext = await import("./shared/call-context.js");
+ ({ wrapAnthropicError } = await import("./shared/anthropic-error.js"));
+ ({ calculateCost } = await import("./shared/remote-provider-types.js"));
+ ({ Hono } = await import("hono"));
+ const logger = await import("../logger.js");
+ logger.initLogger(false, "minimal", true);
+ logger.setStderrQuiet(true);
+ const { sseResponseToJson } = await import("./shared/collect-sse-message.js");
+ // Derive the JSON reply with the production collector from this real Anthropic SSE capture.
+ successBody = await (
+ await sseResponseToJson(
+ new Response(
+ readFileSync(
+ join(dataRoot, "sse-responses/minimax-m3-anthropic-implicit-signature-r10416.sse")
+ ),
+ { headers: { "content-type": "text/event-stream" } }
+ ),
+ accepted.tier
+ )
+ ).text();
+ });
+
+ afterEach(() => {
+ for (const secrets of leases.splice(0)) secrets.lease.release();
+ api._debug_resetClaudeAuthWarnings();
+ api._debug_resetClaudeAdvisorSpend();
+ globalThis.fetch = noNetwork;
+ });
+
+ async function facts(
+ options: {
+ childAuth?: ChildAuthControl;
+ bearer?: string | null;
+ key?: string;
+ userToken?: string;
+ omitBeta?: boolean;
+ } = {}
+ ): Promise<ClaudeRequestFacts> {
+ // Header map from the S0 main-turn capture; only the redacted credential is replaced.
+ const headers = new Headers(inbound.headers);
+ if (options.bearer === null) headers.delete("authorization");
+ else headers.set("authorization", `Bearer ${options.bearer ?? token}`);
+ if (options.key) headers.set("x-api-key", options.key);
+ if (options.omitBeta) headers.delete("anthropic-beta");
+ const app = new Hono();
+ let result!: ClaudeRequestFacts;
+ app.post("/", (c) => {
+ const secrets = callContext.createSigningSecrets();
+ leases.push(secrets);
+ c.set(callContext.SIGNING_SECRETS_KEY, secrets);
+ result = api.claudeRequestFacts(c, requestBody, {
+ childAuth: options.childAuth ?? { controlled: true },
+ env: options.userToken ? { ANTHROPIC_AUTH_TOKEN: options.userToken } : {},
+ });
+ return c.text("ok");
+ });
+ await app.request("/", { method: "POST", headers });
+ return result;
+ }
+
+ function callParams(auth: ClaudeAdvisorAuth, role: "panel" | "collector" = "panel") {
+ return {
+ role,
+ spec: accepted.tier,
+ model: accepted.tier,
+ auth,
+ system: accepted.sent.systemShape.blocks.at(-1).text,
+ // Turns derived from the real inbound Claude Code capture, not a synthetic request body.
+ turns: [
+ {
+ role: "user" as const,
+ content: api.extractBlocksAsText(requestBody.messages[0].content),
+ },
+ ],
+ timeoutMs: 1000,
+ };
+ }
+
+ function fetchReply(body = successBody, status = 200, headers: HeadersInit = {}) {
+ const requests: Request[] = [];
+ const fetchImpl = (async (input: RequestInfo | URL, init?: RequestInit) => {
+ requests.push(input instanceof Request ? input.clone() : new Request(input, init));
+ return new Response(body, { status, headers });
+ }) as unknown as typeof fetch;
+ return { requests, fetchImpl };
+ }
+
+ describe("G2 Claude login arm — A1/A9 and S0", () => {
+ for (const role of ["panel", "collector"] as const) {
+ test(
+ `${role}: controlled login signs only the fixed Anthropic endpoint with shape A`,
+ async () => {
+ const f = await facts({ omitBeta: true });
+ let resolutions = 0;
+ const auth = await api.resolveClaudeAdvisorAuth(f, async () => {
+ resolutions++;
+ return resolvedKey;
+ });
+ expect(auth.arm).toBe("oauth");
+ expect(resolutions).toBe(0);
+ const reply = fetchReply();
+ const warnings: string[] = [];
+ const result = await api.runClaudeAdvisorCall({
+ ...callParams(auth, role),
+ ...reply,
+ warn: (message) => warnings.push(message),
+ });
+ expect(reply.requests).toHaveLength(1);
+ const request = reply.requests[0]!;
+ expect(request.url).toBe("https://api.anthropic.com/v1/messages");
+ expect(request.headers.get("authorization")).toBe(`Bearer ${token}`);
+ expect(request.headers.has("x-api-key")).toBe(false);
+ const body = await request.json();
+ expect(body.system[0]).toEqual({ type: "text", text: f.identityBlock });
+ expect(body.system[0]).not.toHaveProperty("cache_control");
+ expect(body.system).toHaveLength(2);
+ expect(result).toMatchObject({
+ origin: "upstream",
+ servedArm: "oauth",
+ billing: "subscription",
+ systemHead: "identity",
+ });
+ expect(warnings).toEqual([]);
+ expect(JSON.stringify(result)).not.toContain(token);
+ },
+ TIMEOUT
+ );
+ }
+
+ test(
+ "the captured advisor beta is stripped without removing the login beta",
+ async () => {
+ const auth = await api.resolveClaudeAdvisorAuth(await facts(), async () => undefined);
+ const reply = fetchReply();
+ await api.runClaudeAdvisorCall({ ...callParams(auth), ...reply, warn() {} });
+ const beta = reply.requests[0]!.headers.get("anthropic-beta")!;
+ expect(beta).not.toContain("advisor-tool-2026-03-01");
+ expect(beta).toContain("oauth-2025-04-20");
+ },
+ TIMEOUT
+ );
+
+ for (const source of ["settings-auth-token", "api-key-helper", "proxy-auth"] as const) {
+ test(
+ `uncontrolled ${source} never signs with a bearer and warns before metered use`,
+ async () => {
+ const f = await facts({
+ childAuth: { controlled: false, reason: source, where: "T4 settings" },
+ key: inboundKey,
+ });
+ let resolutions = 0;
+ const auth = await api.resolveClaudeAdvisorAuth(f, async () => {
+ resolutions++;
+ return resolvedKey;
+ });
+ expect(f.login).toBeUndefined();
+ expect(f.loginSkipped).toBe("launch-auth-not-claudish-controlled");
+ expect(auth).toMatchObject({ arm: "api-key", source: "inbound-x-api-key" });
+ expect(resolutions).toBe(0);
+ const reply = fetchReply();
+ const warnings: string[] = [];
+ const result = await api.runClaudeAdvisorCall({
+ ...callParams(auth),
+ ...reply,
+ warn: (message) => warnings.push(message),
+ });
+ expect(reply.requests[0]!.url).toBe("https://api.anthropic.com/v1/messages");
+ expect(reply.requests[0]!.headers.has("authorization")).toBe(false);
+ expect(reply.requests[0]!.headers.get("x-api-key")).toBe(inboundKey);
+ expect(result).toMatchObject({
+ origin: "upstream",
+ servedArm: "api-key",
+ billing: "metered",
+ });
+ expect(warnings).toHaveLength(1);
+ expect(warnings[0]).toContain(source);
+ expect(warnings[0]).toMatch(/metered|billed per token/);
+ expect(warnings.join(" ")).not.toContain(token);
+ },
+ TIMEOUT
+ );
+ }
+
+ test(
+ "a user's ANTHROPIC_AUTH_TOKEN is excluded even when the beta and controlled flag are present",
+ async () => {
+ const f = await facts({ userToken: token });
+ const auth = await api.resolveClaudeAdvisorAuth(f, async () => resolvedKey);
+ expect(f.login).toBeUndefined();
+ expect(f.loginSkipped).toBe("user-auth-token");
+ expect(auth).toMatchObject({ arm: "api-key", source: "ANTHROPIC_API_KEY" });
+ const reply = fetchReply();
+ const warnings: string[] = [];
+ await api.runClaudeAdvisorCall({
+ ...callParams(auth),
+ ...reply,
+ warn: (message) => warnings.push(message),
+ });
+ expect(reply.requests[0]!.headers.has("authorization")).toBe(false);
+ expect(reply.requests[0]!.headers.get("x-api-key")).toBe(resolvedKey);
+ expect(warnings.join(" ")).toContain("ANTHROPIC_AUTH_TOKEN");
+ expect(warnings.join(" ")).not.toContain(token);
+ },
+ TIMEOUT
+ );
+
+ test(
+ "no bearer uses the resolved key, warns once per reason, and warns for a later different reason",
+ async () => {
+ const noBearer = await api.resolveClaudeAdvisorAuth(
+ await facts({ bearer: null }),
+ async () => resolvedKey
+ );
+ const skipped = await api.resolveClaudeAdvisorAuth(
+ await facts({ userToken: token }),
+ async () => resolvedKey
+ );
+ const reply = fetchReply();
+ const warnings: string[] = [];
+ for (const auth of [noBearer, noBearer, skipped, skipped]) {
+ const result = await api.runClaudeAdvisorCall({
+ ...callParams(auth),
+ ...reply,
+ warn: (message) => warnings.push(message),
+ });
+ expect(result.billing).toBe("metered");
+ }
+ expect(warnings).toHaveLength(2);
+ expect(new Set(warnings).size).toBe(2);
+ expect(reply.requests.every((request) => !request.headers.has("authorization"))).toBe(true);
+ },
+ TIMEOUT
+ );
+
+ test(
+ "no accepted login and no key produces a credential stub without fetching",
+ async () => {
+ const auth = await api.resolveClaudeAdvisorAuth(
+ await facts({ bearer: null }),
+ async () => undefined
+ );
+ const reply = fetchReply();
+ const warnings: string[] = [];
+ const result = await api.runClaudeAdvisorCall({
+ ...callParams(auth),
+ ...reply,
+ warn: (message) => warnings.push(message),
+ });
+ expect(reply.requests).toHaveLength(0);
+ expect(result.origin).toBe("stub");
+ expect(result.reason).toContain("no Claude credential");
+ expect(warnings).toHaveLength(1);
+ },
+ TIMEOUT
+ );
+
+ test(
+ "S0 429 Error without unified headers is a shape stub, never retried or cooled down",
+ async () => {
+ // Derived from S0 replay-results-1792535094326.json: captured error type/message/status
+ // and headers are passed through the production Anthropic error builder, not retyped.
+ const body = JSON.stringify(
+ wrapAnthropicError(refused.status, refused.errorMessage, refused.errorType)
+ );
+ expect(
+ api.isClaudeShapeRefusal(refused.status, body, new Headers(refused.responseHeaders))
+ ).toBe(true);
+ expect(
+ api.isClaudeShapeRefusal(refused.status, body, new Headers(accepted.responseHeaders))
+ ).toBe(false);
+ expect(api.isClaudeShapeRefusal(401, body, new Headers(refused.responseHeaders))).toBe(
+ false
+ );
+ const auth = await api.resolveClaudeAdvisorAuth(await facts(), async () => resolvedKey);
+ const reply = fetchReply(body, refused.status, refused.responseHeaders);
+ for (let i = 0; i < 2; i++) {
+ const result = await api.runClaudeAdvisorCall({
+ ...callParams(auth),
+ ...reply,
+ warn() {},
+ });
+ expect(result).toMatchObject({
+ origin: "stub",
+ upstreamStatus: refused.status,
+ shapeRefusal: true,
+ });
+ expect(result.reason).toContain("shape");
+ expect(result.reason).toContain("not a quota");
+ expect(reply.requests).toHaveLength(i + 1);
+ }
+ expect(reply.requests.every((request) => request.headers.has("authorization"))).toBe(true);
+ },
+ TIMEOUT
+ );
+ });
+
+ describe("G4 advisor stats and the main status line", () => {
+ test(
+ "Claude stats have request_role advisor and accumulate metered spend, never subscription spend",
+ () => {
+ const outcome = { upstreamStatus: 200, latencyMs: 1, usage: accepted.ok.usage };
+ const login = api.claudeAdvisorStatsEvent(accepted.tier, "oauth", outcome);
+ expect(login).toMatchObject({
+ request_role: "advisor",
+ estimated_cost: 0,
+ is_free_model: true,
+ provider_name: "native-anthropic",
+ });
+ const cost = calculateCost(
+ "native-anthropic",
+ accepted.tier,
+ outcome.usage.input_tokens,
+ outcome.usage.output_tokens
+ );
+ expect(cost).toBeGreaterThan(0);
+ const first = api.claudeAdvisorStatsEvent(accepted.tier, "api-key", outcome);
+ const second = api.claudeAdvisorStatsEvent(accepted.tier, "api-key", outcome);
+ expect(first.estimated_cost).toBeCloseTo(cost, 12);
+ expect(second).toMatchObject({ request_role: "advisor", is_free_model: false });
+ expect(second.estimated_cost).toBeCloseTo(cost * 2, 12);
+ const afterLogin = api.claudeAdvisorStatsEvent(accepted.tier, "oauth", outcome);
+ expect(afterLogin.estimated_cost).toBeCloseTo(cost * 2, 12);
+ const failed = api.claudeAdvisorStatsEvent(accepted.tier, "api-key", {
+ upstreamStatus: 429,
+ latencyMs: 1,
+ });
+ expect(failed).toMatchObject({ request_role: "advisor", success: false, http_status: 429 });
+ expect(failed.estimated_cost).toBeCloseTo(cost * 2, 12);
+ },
+ TIMEOUT
+ );
+
+ test(
+ "Claude panel and collector calls leave the main token file byte-identical",
+ async () => {
+ const path = join(process.env.HOME!, "main-token.json");
+ const sentinel = JSON.stringify({
+ model: "main-session",
+ input_tokens: 71,
+ output_tokens: 9,
+ });
+ writeFileSync(path, sentinel);
+ process.env.CLAUDISH_TOKEN_FILE = path;
+ try {
+ for (const role of ["panel", "collector"] as const) {
+ for (const bearer of [token, null]) {
+ const auth = await api.resolveClaudeAdvisorAuth(
+ await facts({ bearer }),
+ async () => resolvedKey
+ );
+ await api.runClaudeAdvisorCall({
+ ...callParams(auth, role),
+ ...fetchReply(),
+ warn() {},
+ });
+ expect(readFileSync(path, "utf8")).toBe(sentinel);
+ }
+ }
+ } finally {
+ delete process.env.CLAUDISH_TOKEN_FILE;
+ }
+ },
+ TIMEOUT
+ );
+ });
+}
diff --cc packages/cli/src/handlers/advisor-decorator.ts
index 2c7232d1,9568bb0b..6eb34320
--- a/packages/cli/src/handlers/advisor-decorator.ts
+++ b/packages/cli/src/handlers/advisor-decorator.ts
@@@ -45,18 -45,15 +45,18 @@@ import type { Context } from "hono"
// The HARNESS extractSessionId: takes the whole request and reads
// `metadata.user_id`'s JSON `session_id`. NOT the same-named function in
// session-events/index.ts, which takes the metadata object instead.
- import { extractSessionId } from "../behavior/harness.js";
- import type { ChildAuthControl } from "../claude-runner.js";
++import type { ChildAuthControl } from "../child-auth-types.js";
+ import { extractSessionId } from "../hooks/harness.js";
import { log, logStderr } from "../logger.js";
+import type { AdvisorPanelGateway } from "./advisor-route-plan.js";
import {
- type AdvisorApiKeys,
- type AdvisorRouteKind,
type AdvisorSwapConfig,
type AdvisorToolResult,
+ type ClaudeAdvisorAuth,
+ type ClaudeRequestFacts,
NO_SESSION_BUCKET,
- advisorCredentialsFor,
+ type RunAdvisorCallParams,
+ claudeRequestFacts,
createAdvisorStreamScanner,
findPendingAdvisorToolResults,
getAdvisorCall,
diff --cc packages/cli/src/handlers/advisor-panel-gateway.ts
index f7f27665,00000000..20ea1f78
mode 100644,000000..100644
--- a/packages/cli/src/handlers/advisor-panel-gateway.ts
+++ b/packages/cli/src/handlers/advisor-panel-gateway.ts
@@@ -1,220 -1,0 +1,220 @@@
+/**
+ * The advisor panel gateway: one in-process request per routed panel or
+ * collector call, through the chain startup built for it.
+ *
+ * A facade of two functions over Context building, chain lookup, the call's
+ * deadline, its signing lease, redaction and hop attribution:
+ *
+ * - `plan(spec, role)` reads the startup plan map only. There is no lazy
+ * planning: a spec the map lacks is a refused plan ("advisor runtime not
+ * planned for this launch").
+ * - `call(req)` never rejects. It POSTs the payload to a never-served Hono app
+ * whose one route installs the call's abort signal, hop log and signing
+ * secrets on a real `Context` and hands it to the startup-built chain. The
+ * app is never passed to `Bun.serve` and never goes through the session's
+ * `resolveHandlerForRequest`, so the monitor branch, the serve slot map and
+ * the `--model` remap cannot touch a panel call, and no advisor wrapper is
+ * ever applied (no recursion).
+ *
+ * The synthetic request carries NO auth header, and `ComposedHandler` forwards
+ * no inbound `authorization`, so Claude Code's bearer cannot reach a panel hop.
+ * `x-claudish-no-recovery: advisor` skips the tier-1 hold ladder: a 60 s budget
+ * cannot use a multi-minute hold.
+ */
+
+import { type Context, Hono } from "hono";
- import type { ChildAuthControl } from "../claude-runner.js";
++import type { ChildAuthControl } from "../child-auth-types.js";
+import { log } from "../logger.js";
+import { redactExactValues, redactForClient } from "../redact.js";
+import {
+ type AdvisorChainBuild,
+ type AdvisorModelPlan,
+ type AdvisorPanelCall,
+ type AdvisorPanelGateway,
+ type AdvisorPanelResult,
+ type AdvisorRole,
+ advisorChainKey,
+ planHopForTransport,
+} from "./advisor-route-plan.js";
+import { wrapAnthropicError } from "./shared/anthropic-error.js";
+import {
+ CALL_ABORT_SIGNAL_KEY,
+ HOP_LOG_KEY,
+ type HopAttempt,
+ SIGNING_SECRETS_KEY,
+ type SigningSecrets,
+ createSigningSecrets,
+} from "./shared/call-context.js";
+import { isStreamFailureResponse } from "./shared/recovery-marker.js";
+import type { ModelHandler } from "./types.js";
+
+/** What startup hands the proxy: every member's plan and every routed member's built chain. */
+export interface AdvisorRuntime {
+ /** Keyed `"<role>:<spec>"` (`advisorChainKey`). */
+ plans: ReadonlyMap<string, AdvisorModelPlan>;
+ chains: ReadonlyMap<string, AdvisorChainBuild>;
+ /**
+ * The launch's `childAuthControl` decision, the one the Claude plans were
+ * made with: the decorator lets Claude Code's bearer sign a Claude call only
+ * when it says claudish controls the child's auth.
+ */
+ childAuth: ChildAuthControl;
+}
+
+/** The URL of the synthetic request. Never resolved: the app is called in process. */
+const ADVISOR_INTERNAL_URL = "http://claudish.advisor.internal/v1/messages";
+
+interface PendingCall {
+ handler: ModelHandler;
+ signal: AbortSignal;
+ hops: HopAttempt[];
+ secrets: SigningSecrets;
+}
+
+function errorMessage(err: unknown): string {
+ return err instanceof Error ? err.message : String(err);
+}
+
+/** The answer the app gives for a call it cannot run or a handler that threw. */
+function proxyErrorResponse(c: Context, message: string): Response {
+ return c.json(wrapAnthropicError(500, redactForClient(`Proxy error: ${message}`)), 500);
+}
+
+export function createAdvisorPanelGateway(runtime: AdvisorRuntime): AdvisorPanelGateway {
+ const pendingCalls = new WeakMap<Request, PendingCall>();
+ const app = new Hono();
+
+ app.onError((err, c) => {
+ log(`[advisor] panel gateway error: ${errorMessage(err)}`);
+ return proxyErrorResponse(c, errorMessage(err));
+ });
+
+ app.post("/v1/messages", async (c) => {
+ // Hono keeps the Request's identity, so the entry `call()` registered is
+ // found by the very object it passed to `app.fetch`.
+ const entry = pendingCalls.get(c.req.raw);
+ if (!entry)
+ return proxyErrorResponse(c, "advisor gateway: no call registered for this request");
+ c.set(CALL_ABORT_SIGNAL_KEY, entry.signal);
+ c.set(HOP_LOG_KEY, entry.hops);
+ c.set(SIGNING_SECRETS_KEY, entry.secrets);
+ try {
+ return await entry.handler.handle(c, await c.req.json());
+ } catch (err) {
+ log(`[advisor] panel call threw: ${errorMessage(err)}`);
+ return proxyErrorResponse(c, errorMessage(err));
+ }
+ });
+
+ const plan = (spec: string, role: AdvisorRole): AdvisorModelPlan =>
+ runtime.plans.get(advisorChainKey(role, spec)) ?? {
+ kind: "refused",
+ spec,
+ role,
+ cause: "no-callable-hop",
+ reason: "advisor runtime not planned for this launch",
+ };
+
+ const call = async (req: AdvisorPanelCall): Promise<AdvisorPanelResult> => {
+ const started = performance.now();
+ const latencyMs = () => Math.round(performance.now() - started);
+ const build = runtime.chains.get(advisorChainKey(req.plan.role, req.plan.spec));
+ const hops: HopAttempt[] = [];
+ const snapshot = (): AdvisorPanelResult["hops"] =>
+ hops.slice().map((h) => {
+ const hop = build ? planHopForTransport(req.plan, build, h) : null;
+ return { ...h, uid: hop?.provider ?? null, displayName: hop?.displayName ?? h.provider };
+ });
+ if (!build?.handler) {
+ return {
+ status: null,
+ bodyText: "",
+ streamFailure: false,
+ hops: [],
+ failure: { kind: "internal", message: `no hop could be built for ${req.plan.spec}` },
+ latencyMs: latencyMs(),
+ };
+ }
+
+ const plannedIndex = build.firstCallableHop;
+ const plannedHop = plannedIndex === null ? undefined : req.plan.hops[plannedIndex];
+ const planned = plannedHop
+ ? {
+ plannedHop: {
+ provider: plannedHop.provider,
+ displayName: plannedHop.displayName,
+ billing: plannedHop.billing,
+ },
+ }
+ : {};
+
+ const secrets = createSigningSecrets();
+ const controller = new AbortController();
+ const request = new Request(ADVISOR_INTERNAL_URL, {
+ method: "POST",
+ body: JSON.stringify(req.payload),
+ signal: controller.signal,
+ headers: { "content-type": "application/json", "x-claudish-no-recovery": "advisor" },
+ });
+ pendingCalls.set(request, { handler: build.handler, signal: controller.signal, hops, secrets });
+
+ // The body is read INSIDE the work, so the deadline covers it, and redacted
+ // while the lease still holds every value the chain signed with.
+ const work = (async () => {
+ const res = await app.fetch(request);
+ const text = redactExactValues(redactForClient(await res.text()), secrets.values);
+ return { res, text };
+ })();
+ // The lease lives as long as the work: released when it settles, which for
+ // a timed-out call is after its aborted work has unwound (and could still log).
+ work.finally(() => secrets.lease.release()).catch(() => {});
+
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const deadline = new Promise<"timeout">((resolve) => {
+ timer = setTimeout(() => resolve("timeout"), req.timeoutMs);
+ });
+ try {
+ const outcome = await Promise.race([work, deadline]);
+ if (outcome === "timeout") {
+ controller.abort();
+ return {
+ status: null,
+ bodyText: "",
+ streamFailure: false,
+ hops: snapshot(),
+ ...planned,
+ failure: {
+ kind: "timeout",
+ message: `timed out after ${Math.round(req.timeoutMs / 1000)}s`,
+ },
+ latencyMs: latencyMs(),
+ };
+ }
+ return {
+ status: outcome.res.status,
+ bodyText: outcome.text,
+ streamFailure: isStreamFailureResponse(outcome.res),
+ hops: snapshot(),
+ ...planned,
+ latencyMs: latencyMs(),
+ };
+ } catch (err) {
+ return {
+ status: null,
+ bodyText: "",
+ streamFailure: false,
+ hops: snapshot(),
+ ...planned,
+ failure: {
+ kind: "internal",
+ message: redactExactValues(redactForClient(errorMessage(err)), secrets.values),
+ },
+ latencyMs: latencyMs(),
+ };
+ } finally {
+ clearTimeout(timer);
+ }
+ };
+
+ return { plan, call };
+}
diff --cc packages/cli/src/handlers/advisor-route-plan.ts
index 9a0ef368,00000000..d9fbe7d6
mode 100644,000000..100644
--- a/packages/cli/src/handlers/advisor-route-plan.ts
+++ b/packages/cli/src/handlers/advisor-route-plan.ts
@@@ -1,826 -1,0 +1,826 @@@
+/**
+ * The routing decision for one `--advisor` spec, made by the function main
+ * routing is derived from.
+ *
+ * `planAdvisorModel` wraps `explainRoute` (providers/routing-rules.ts), the
+ * function `route()` itself runs, so a panel member is planned exactly like a
+ * main-model request: the same route candidates, the same credential and
+ * availability filters, the same tier order. Startup plans every member before
+ * the port is bound; the notice, the refusal and the runtime all read that one
+ * result, so they cannot disagree.
+ *
+ * A Claude name is decided BEFORE routing, as the proxy does (`nativeRouteFor`
+ * first, CLAUDE.md invariant): `native-anthropic` has no credential store, so
+ * `route()` would drop it and degrade the chain to OpenRouter. A Claude member
+ * is a call to api.anthropic.com instead, signed with Claude Code's login only
+ * on a launch where claudish controls the child's auth (`childAuthControl`,
+ * claude-runner.ts), else with an API key, metered.
+ *
+ * Imports neither the advisor call path nor the proxy (no cycle): the
+ * Anthropic-key presence check is passed in by the caller, which owns the one
+ * lookup the runtime also uses.
+ */
+
+import type { Context } from "hono";
- import type { ChildAuthControl, ChildAuthSource } from "../claude-runner.js";
++import type { ChildAuthControl, ChildAuthSource } from "../child-auth-types.js";
+import { log } from "../logger.js";
+import { ensureCatalogReady } from "../providers/catalog-client.js";
+import { nativeRouteFor } from "../providers/native-route.js";
+import type { RouteTier } from "../providers/provider-definitions.js";
+import {
+ type CandidateOutcome,
+ type NoRouteCause,
+ type RouteExplanation,
+ explainRoute,
+} from "../providers/routing-rules.js";
+import { CatalogPendingHandler, RefusingHandler } from "../providers/wire-handler.js";
+import {
+ WireMarkerError,
+ WireMarkerHandler,
+ type WireMarkers,
+ splitWireMarkers,
+} from "../providers/wire-markers.js";
+import { TryInTurnHandler } from "../providers/wire-try-in-turn.js";
+import { redactSecrets } from "../redact.js";
+import { ANTHROPIC_API_HOST, claudeAdvisorModelFor } from "./advisor-claude-route.js";
+import { ComposedHandler } from "./composed-handler.js";
+import { type FallbackCandidate, FallbackHandler, isRetryableError } from "./fallback-handler.js";
+import type { HandlerSet } from "./handler-set.js";
+import { type HopAttempt, type HopBilling, withPlannedHop } from "./shared/call-context.js";
+import { isSubscriptionProvider } from "./shared/remote-provider-types.js";
+import type { ModelHandler } from "./types.js";
+
+export type AdvisorRole = "panel" | "collector";
+export type AdvisorBilling = HopBilling;
+
+/** One kept route candidate of a routed plan. */
+export interface AdvisorHop {
+ /** claudish provider uid (`ExplainedCandidate.provider`). */
+ provider: string;
+ /** THE display source for the notice and the records. */
+ displayName: string;
+ modelSpec: string;
+ wireId: string;
+ tier?: RouteTier;
+ /** `isSubscriptionProvider(provider)` at plan time; the record re-reads it after signing. */
+ billing: AdvisorBilling;
+}
+
+/** Where a Claude member's API key comes from on a launch without a usable login. */
+export type ClaudeApiKeySource = "inbound-x-api-key" | "ANTHROPIC_API_KEY";
+
+export type AdvisorModelPlan =
+ | {
+ kind: "routed";
+ spec: string;
+ role: AdvisorRole;
+ markers?: WireMarkers;
+ explanation: RouteExplanation;
+ /** ≥ 1: the kept candidates, in chain order. */
+ hops: AdvisorHop[];
+ invocationMode: "explicit-model" | "auto-route";
+ }
+ | {
+ kind: "claude-native";
+ spec: string;
+ role: AdvisorRole;
+ /** The resolved Anthropic API id. */
+ model: string;
+ expectedArm: "claude-login" | "api-key";
+ /** Set only for `api-key`: the source that keeps the login off this launch, and where. */
+ authSource?: { reason: ChildAuthSource; where: string };
+ /** Set only for `api-key`: what the call is expected to sign with. */
+ apiKeySource?: ClaudeApiKeySource;
+ }
+ | {
+ kind: "refused";
+ spec: string;
+ role: AdvisorRole;
+ cause:
+ | NoRouteCause
+ | "wire-marker"
+ | "unresolved-alias"
+ | "claude-selector"
+ | "claude-no-credential"
+ | "no-callable-hop";
+ reason: string;
+ hint?: string;
+ };
+
+export interface PlanAdvisorDeps {
+ /** This launch's `childAuthControl(config, env)`. */
+ childAuth: ChildAuthControl;
+ /**
+ * Presence of ANTHROPIC_API_KEY through the advisor's own credential lookup
+ * (never ANTHROPIC_AUTH_TOKEN, never a placeholder). Asked only for a Claude
+ * member that cannot use the login and gets no inbound `x-api-key`.
+ */
+ anthropicKeyPresent: () => Promise<boolean>;
+ /** Default `explainRoute`. */
+ explain?: (target: string) => Promise<RouteExplanation>;
+ /** Default `ensureCatalogReady`. */
+ ensureCatalog?: (timeoutMs: number) => Promise<void>;
+ /** Default `isSubscriptionProvider`. */
+ isSubscription?: (provider: string) => boolean;
+}
+
+/**
+ * Sources after which Claude Code itself sends a real `x-api-key`, so a Claude
+ * member signs with that and needs no ANTHROPIC_API_KEY of claudish's.
+ * `custom-headers` is not listed: it counts only when the headers set
+ * `x-api-key` (`sendsApiKey`, see `sendsInboundApiKey`).
+ */
+const INBOUND_KEY_SOURCES: ReadonlySet<ChildAuthSource> = new Set([
+ "user-api-key",
+ "settings-api-key",
+ "api-key-helper",
+]);
+
+/**
+ * Whether Claude Code sends a real `x-api-key` on this uncontrolled launch.
+ * ANTHROPIC_CUSTOM_HEADERS that set only `Authorization` send a bearer the
+ * advisor never signs with off a controlled launch, so such a launch needs
+ * ANTHROPIC_API_KEY or is refused at startup, not stubbed at every call.
+ */
+function sendsInboundApiKey(childAuth: Extract<ChildAuthControl, { controlled: false }>): boolean {
+ if (childAuth.reason === "custom-headers") return childAuth.sendsApiKey === true;
+ return INBOUND_KEY_SOURCES.has(childAuth.reason);
+}
+
+/** The catalog wait main routing applies before it routes (`proxy-server.ts` step 2c). */
+const CATALOG_WAIT_MS = 5000;
+
+/**
+ * Plan one advisor spec. Never writes to stderr; `explanation.warnings` are
+ * returned for the notice to print.
+ *
+ * Decision order: wire markers; a Claude name (native recognition first); the
+ * catalog wait; `explainRoute`. Each step exists in main routing; only the
+ * composition is new.
+ */
+export async function planAdvisorModel(
+ spec: string,
+ role: AdvisorRole,
+ deps: PlanAdvisorDeps
+): Promise<AdvisorModelPlan> {
+ let markers: WireMarkers;
+ try {
+ markers = splitWireMarkers(spec);
+ } catch (err) {
+ if (err instanceof WireMarkerError) {
+ return { kind: "refused", spec, role, cause: "wire-marker", reason: err.message };
+ }
+ throw err;
+ }
+ const model = markers.spec;
+
+ if (nativeRouteFor(model)) return planClaudeMember(spec, role, model, deps);
+
+ await (deps.ensureCatalog ?? ensureCatalogReady)(CATALOG_WAIT_MS);
+ const explanation = await (deps.explain ?? ((target: string) => explainRoute(target)))(model);
+ const { outcome } = explanation;
+ if (outcome.kind === "no-route") {
+ return {
+ kind: "refused",
+ spec,
+ role,
+ cause: outcome.cause,
+ reason: outcome.reason,
+ ...(outcome.hint !== undefined ? { hint: outcome.hint } : {}),
+ };
+ }
+
+ const isSubscription = deps.isSubscription ?? isSubscriptionProvider;
+ const hops: AdvisorHop[] = explanation.candidates
+ .filter((candidate) => candidate.outcome === "kept")
+ .map((candidate) => ({
+ provider: candidate.provider,
+ displayName: candidate.displayName,
+ modelSpec: candidate.modelSpec,
+ wireId: candidate.wireId,
+ ...(candidate.tier !== undefined ? { tier: candidate.tier } : {}),
+ billing: isSubscription(candidate.provider) ? "subscription" : "metered",
+ }));
+ if (hops.length === 0) {
+ // `toRoutePlan` throws for this; an "ok" outcome always keeps one today.
+ return {
+ kind: "refused",
+ spec,
+ role,
+ cause: "no-callable-hop",
+ reason: `routing kept no candidate for "${model}"`,
+ };
+ }
+
+ return {
+ kind: "routed",
+ spec,
+ role,
+ ...(markers.mode || markers.speed ? { markers } : {}),
+ explanation,
+ hops,
+ invocationMode: explanation.source === "explicit" ? "explicit-model" : "auto-route",
+ };
+}
+
+async function planClaudeMember(
+ spec: string,
+ role: AdvisorRole,
+ model: string,
+ deps: PlanAdvisorDeps
+): Promise<AdvisorModelPlan> {
+ const claude = claudeAdvisorModelFor(model);
+ if (claude.refused) {
+ return { kind: "refused", spec, role, cause: claude.cause, reason: claude.reason };
+ }
+ const { childAuth } = deps;
+ if (childAuth.controlled) {
+ return { kind: "claude-native", spec, role, model: claude.id, expectedArm: "claude-login" };
+ }
+ const authSource = { reason: childAuth.reason, where: childAuth.where };
+ if (sendsInboundApiKey(childAuth)) {
+ return {
+ kind: "claude-native",
+ spec,
+ role,
+ model: claude.id,
+ expectedArm: "api-key",
+ authSource,
+ apiKeySource: "inbound-x-api-key",
+ };
+ }
+ if (!(await deps.anthropicKeyPresent())) {
+ return {
+ kind: "refused",
+ spec,
+ role,
+ cause: "claude-no-credential",
+ reason:
+ `${spec} is a Claude model; this launch gives the advisor no Claude login ` +
+ `(${noLoginPhrase(authSource)}), and no ANTHROPIC_API_KEY was found in env, config, ` +
+ "keychain or 1Password. Set the key, run without --model, map a role to Claude " +
+ "(--model-haiku haiku), or name it through OpenRouter (or@anthropic/<id>).",
+ };
+ }
+ return {
+ kind: "claude-native",
+ spec,
+ role,
+ model: claude.id,
+ expectedArm: "api-key",
+ authSource,
+ apiKeySource: "ANTHROPIC_API_KEY",
+ };
+}
+
+/** Why a launch has no Claude login the advisor may use, as a clause. */
+export function noLoginPhrase(source: { reason: ChildAuthSource; where: string }): string {
+ switch (source.reason) {
+ case "proxy-auth":
+ return "a --model of another provider gives Claude Code claudish's placeholder, not your login";
+ case "user-auth-token":
+ return "your ANTHROPIC_AUTH_TOKEN is forwarded to Claude Code instead";
+ case "user-api-key":
+ return "your ANTHROPIC_API_KEY is forwarded to Claude Code instead";
+ case "settings-auth-token":
+ return `a Claude Code settings file (${source.where}) sets ANTHROPIC_AUTH_TOKEN`;
+ case "settings-api-key":
+ return `a Claude Code settings file (${source.where}) sets ANTHROPIC_API_KEY`;
+ case "api-key-helper":
+ return `a Claude Code settings file (${source.where}) names an apiKeyHelper`;
+ case "custom-headers":
+ return `ANTHROPIC_CUSTOM_HEADERS (${source.where}) sets an auth header`;
+ case "settings-unreadable":
+ return `a ${source.where} value Claude Code receives could not be read, so its auth cannot be ruled out`;
+ }
+}
+
+/** What a user does to put the login back, per source. */
+function restoreLoginHint(source: { reason: ChildAuthSource }): string {
+ switch (source.reason) {
+ case "proxy-auth":
+ return "Run without --model, or map a role to Claude (--model-haiku haiku), to use your subscription";
+ case "user-auth-token":
+ return "Unset ANTHROPIC_AUTH_TOKEN to use your subscription";
+ case "user-api-key":
+ return "Unset ANTHROPIC_API_KEY to use your subscription";
+ default:
+ return "Remove it to use your subscription";
+ }
+}
+
+/** The billing word a notice line uses. */
+export function billingWord(billing: AdvisorBilling): string {
+ return billing === "subscription" ? "subscription" : "metered, billed per token";
+}
+
+/** A `CandidateOutcome` as the notice's "skipped" phrase. */
+export const SKIPPED_PHRASE: Readonly<Record<Exclude<CandidateOutcome, "kept">, string>> = {
+ "no-credential": "no credential",
+ "credential-unreadable": "credential could not be read",
+ "not-served": "the account does not serve it",
+ "excluded-by-membership": "not in the plan's membership",
+ "excluded-by-content-use": "content-use opt-in id only",
+};
+
+/**
+ * The notice line for a Claude member: where it goes and what signs it. A
+ * routed member's line needs its built chain (`describeAdvisorPlan` with a
+ * build).
+ */
+export function describeClaudeAdvisorPlan(
+ plan: Extract<AdvisorModelPlan, { kind: "claude-native" }>
+): string {
+ if (plan.expectedArm === "claude-login") {
+ return (
+ `${plan.spec} -> ${ANTHROPIC_API_HOST} (subscription: your Claude Code login; if a request ` +
+ "carries none: its x-api-key or ANTHROPIC_API_KEY, metered, billed per token)"
+ );
+ }
+ const source = plan.authSource ?? { reason: "proxy-auth" as const, where: "environment" };
+ const key =
+ plan.apiKeySource === "inbound-x-api-key"
+ ? "the x-api-key Claude Code sends, else ANTHROPIC_API_KEY"
+ : "ANTHROPIC_API_KEY";
+ return (
+ `${plan.spec} -> ${ANTHROPIC_API_HOST} (metered, billed per token: ${key}; ` +
+ `${noLoginPhrase(source)}, so the advisor never signs with a bearer on this launch. ` +
+ `${restoreLoginHint(source)})`
+ );
+}
+
+type RoutedPlan = Extract<AdvisorModelPlan, { kind: "routed" }>;
+type RefusedPlan = Extract<AdvisorModelPlan, { kind: "refused" }>;
+
+/**
+ * The refusal sentence for a refused plan, or for a routed plan whose built
+ * chain has no callable hop (every hop's outcome is named).
+ */
+export function describeAdvisorRefusal(
+ refusal: RefusedPlan | { plan: RoutedPlan; build: AdvisorChainBuild }
+): string {
+ if ("build" in refusal) {
+ const { plan, build } = refusal;
+ const outcomes = plan.hops.map((hop, i) => {
+ const b = build.builds[i];
+ const what =
+ b?.kind === "refused"
+ ? b.message
+ : b?.kind === "failed"
+ ? `could not be built: ${b.message}`
+ : b?.kind === "not-built" || !b
+ ? "could not be built"
+ : "built, but a refusing hop before it stops the chain";
+ return `${hop.displayName}: ${what}`;
+ });
+ return `${plan.spec}: no hop could be built — ${outcomes.join("; ")}`;
+ }
+ switch (refusal.cause) {
+ case "claude-selector":
+ case "unresolved-alias":
+ case "claude-no-credential":
+ return refusal.reason;
+ default:
+ return `${refusal.spec}: ${refusal.reason}${refusal.hint ? ` ${refusal.hint}` : ""}`;
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Chains: built once, at startup, from the plan, with main routing's dispatch
+// ---------------------------------------------------------------------------
+
+/**
+ * What building one planned hop produced. Every handler a getter can return
+ * has a case (round-3 A3), and `provider.name` is read only off a
+ * `ComposedHandler`, the one type known to have a transport:
+ *
+ * - `built`: a `ComposedHandler`; `transportName` is its provider's name, the
+ * name its hop-log entries carry.
+ * - `built-pending`: a handler whose transport is chosen per request (a
+ * `TryInTurnHandler` for a wire the catalog does not publish, a
+ * `CatalogPendingHandler` while no route registry is readable). The serving
+ * transport is attributed from the hop log at call time.
+ * - `refused`: a `RefusingHandler`; asked once at build (no network), and
+ * `chainContinues` is `FallbackHandler`'s own `isRetryableError` on its answer.
+ * - `not-built`: the getter returned null.
+ * - `failed`: the getter or a profile factory threw; `message` is redacted.
+ */
+export type HopBuild =
+ | { kind: "built"; handler: ModelHandler; transportName: string }
+ | {
+ kind: "built-pending";
+ handler: ModelHandler;
+ handlerKind: "try-in-turn" | "catalog-pending" | "other";
+ }
+ | { kind: "refused"; handler: ModelHandler; message: string; chainContinues: boolean }
+ | { kind: "not-built" }
+ | { kind: "failed"; message: string };
+
+export interface AdvisorChainBuild {
+ /** `"<role>:<spec>"`. */
+ key: string;
+ /** Index-aligned with `plan.hops`. */
+ builds: HopBuild[];
+ /** The runtime handler (a `FallbackHandler` when more than one hop runs); null when nothing can run. */
+ handler: ModelHandler | null;
+ /** Index into `plan.hops` of the first hop a call can reach and that can serve; null ⇒ refusal. */
+ firstCallableHop: number | null;
+ /** Hop-log provider name → plan hop uid, for every `built` hop. */
+ uidByTransportName: ReadonlyMap<string, string>;
+}
+
+/** The key a plan's build is stored under. */
+export function advisorChainKey(role: AdvisorRole, spec: string): string {
+ return `${role}:${spec}`;
+}
+
+/**
+ * Build every routed plan's chain with the getters main routing uses,
+ * STRICTLY SEQUENTIALLY (plans in order, hops in order, each awaited): a
+ * getter may resolve a credential value (1Password, Keychain), and concurrent
+ * handshakes are what 1Password refuses.
+ *
+ * Dispatch copies the proxy's: a `poe:` spec → the Poe getter (step 3); an
+ * `openrouter` hop → the OpenRouter getter (2c); everything else → the remote
+ * getter (2c), and only for an explicit single-hop plan whose remote build
+ * returned null, the local getter (steps 4 → 5). A `poe@<wire>` hop therefore
+ * goes through the remote getter and the Poe profile, never through the
+ * legacy `poe:` strip. No advisor wrapper is ever applied.
+ */
+export async function buildAdvisorChains(
+ plans: readonly RoutedPlan[],
+ set: HandlerSet
+): Promise<Map<string, AdvisorChainBuild>> {
+ const out = new Map<string, AdvisorChainBuild>();
+ for (const plan of plans) {
+ const key = advisorChainKey(plan.role, plan.spec);
+ if (out.has(key)) continue;
+ const builds: HopBuild[] = [];
+ for (const hop of plan.hops) {
+ builds.push(await buildHop(plan, hop, set));
+ }
+ out.set(key, assembleChain(key, plan, builds));
+ }
+ return out;
+}
+
+async function buildHop(plan: RoutedPlan, hop: AdvisorHop, set: HandlerSet): Promise<HopBuild> {
+ const mode = plan.invocationMode;
+ let handler: ModelHandler | null;
+ try {
+ if (hop.modelSpec.startsWith("poe:")) {
+ handler = await set.poe(hop.modelSpec, mode);
+ } else if (hop.provider === "openrouter") {
+ handler = set.openRouter(hop.modelSpec, mode);
+ } else {
+ handler = await set.remote(hop.modelSpec, mode);
+ if (!handler && mode === "explicit-model" && plan.hops.length === 1) {
+ handler = set.local(hop.modelSpec, mode);
+ }
+ }
+ } catch (err) {
+ const message = redactSecrets(err instanceof Error ? err.message : String(err));
+ log(`[advisor] build failed: ${plan.spec} hop ${hop.displayName}: ${message}`);
+ return { kind: "failed", message };
+ }
+ return classifyHandler(handler, hop);
+}
+
+/** The refusal text inside a `RefusingHandler`'s answer, without its `claudish: ` prefix. */
+function refusalMessageOf(body: string): string {
+ try {
+ const message = (JSON.parse(body) as { error?: { message?: unknown } }).error?.message;
+ if (typeof message === "string") return message.replace(/^claudish: /, "");
+ } catch {
+ // not JSON: use the body as it is
+ }
+ return body;
+}
+
+async function classifyHandler(handler: ModelHandler | null, hop: AdvisorHop): Promise<HopBuild> {
+ if (!handler) return { kind: "not-built" };
+ if (handler instanceof RefusingHandler) {
+ // Asked once, here: it answers locally and sends nothing.
+ const response = await handler.handle();
+ const body = await response.text();
+ return {
+ kind: "refused",
+ handler,
+ message: refusalMessageOf(body),
+ chainContinues: isRetryableError(
+ response.status,
+ body,
+ hop.displayName,
+ response.headers,
+ hop.provider
+ ),
+ };
+ }
+ if (handler instanceof ComposedHandler) {
+ return { kind: "built", handler, transportName: handler.getProviderName() };
+ }
+ const handlerKind =
+ handler instanceof TryInTurnHandler
+ ? "try-in-turn"
+ : handler instanceof CatalogPendingHandler
+ ? "catalog-pending"
+ : "other";
+ return {
+ kind: "built-pending",
+ handler: new PlannedHopHandler(handler, hop.provider),
+ handlerKind,
+ };
+}
+
+/**
+ * A built-pending hop, carrying its planned identity to call time. The
+ * transport it serves through is chosen per request, and its name need not be
+ * the planned uid (`google` serves through `GeminiProviderTransport`, named
+ * `gemini`), so every hop-log entry recorded while this hop runs carries the
+ * planned uid (`withPlannedHop` → `recordHopEntry`) rather than being matched
+ * back by name. The uid is on the entry from the moment it is pushed, so a
+ * timed-out call's snapshot already has it.
+ *
+ * Wrapping is safe here and nowhere else: `FallbackHandler` reads fallback
+ * metadata only off a `ComposedHandler`, and a pending handler is never one.
+ */
+export class PlannedHopHandler implements ModelHandler {
+ constructor(
+ readonly inner: ModelHandler,
+ readonly plannedUid: string
+ ) {}
+
+ handle(c: Context, payload: unknown): Promise<Response> {
+ return withPlannedHop(c, this.plannedUid, () => this.inner.handle(c, payload));
+ }
+
+ shutdown(): Promise<void> {
+ return this.inner.shutdown();
+ }
+}
+
+function assembleChain(key: string, plan: RoutedPlan, builds: HopBuild[]): AdvisorChainBuild {
+ let firstCallableHop: number | null = null;
+ for (let i = 0; i < builds.length; i++) {
+ const b = builds[i];
+ if (b.kind === "refused" && !b.chainContinues) break;
+ if (b.kind === "built" || b.kind === "built-pending") {
+ firstCallableHop = i;
+ break;
+ }
+ }
+
+ const uidByTransportName = new Map<string, string>();
+ const candidates: FallbackCandidate[] = [];
+ builds.forEach((b, i) => {
+ if (b.kind === "not-built" || b.kind === "failed") return;
+ const hop = plan.hops[i];
+ // Every runtime hop, a refusing one included, exactly as main routing's
+ // step 2c pushes every non-null handler.
+ candidates.push({ name: hop.displayName, provider: hop.provider, handler: b.handler });
+ if (b.kind === "built" && !uidByTransportName.has(b.transportName)) {
+ uidByTransportName.set(b.transportName, hop.provider);
+ }
+ });
+
+ let handler: ModelHandler | null = null;
+ if (firstCallableHop !== null && candidates.length > 0) {
+ handler = candidates.length > 1 ? new FallbackHandler(candidates) : candidates[0].handler;
+ if (plan.markers) handler = new WireMarkerHandler(handler, plan.markers);
+ }
+ return { key, builds, handler, firstCallableHop, uidByTransportName };
+}
+
+/**
+ * The plan hop a hop-log entry belongs to: the planned uid a `built-pending`
+ * hop stamped on it (`PlannedHopHandler`), else the build's transport-name map
+ * for a `built` hop, else the transport name taken as a uid. Null when none
+ * matches.
+ */
+export function planHopForTransport(
+ plan: RoutedPlan,
+ build: AdvisorChainBuild,
+ entry: Pick<HopAttempt, "provider" | "plannedUid">
+): AdvisorHop | null {
+ const uid = entry.plannedUid ?? build.uidByTransportName.get(entry.provider) ?? entry.provider;
+ return plan.hops.find((hop) => hop.provider === uid) ?? null;
+}
+
+/**
+ * Shut down every handler a set of builds holds, each once. For a startup
+ * that refuses after building, and for the proxy's own shutdown.
+ */
+export async function shutdownAdvisorChains(builds: Iterable<AdvisorChainBuild>): Promise<void> {
+ const handlers = new Set<ModelHandler>();
+ for (const build of builds) {
+ for (const b of build.builds) {
+ if (b.kind === "built" || b.kind === "built-pending" || b.kind === "refused") {
+ handlers.add(b.handler);
+ }
+ }
+ }
+ for (const handler of handlers) {
+ try {
+ await handler.shutdown();
+ } catch (err) {
+ log(`[advisor] handler shutdown failed: ${err instanceof Error ? err.message : String(err)}`);
+ }
+ }
+}
+
+/**
+ * The `; then …` parts for the hops after the first callable one, up to a
+ * refusing hop the chain stops at, and whether any of them bills per token.
+ */
+function laterHopParts(
+ plan: RoutedPlan,
+ build: AdvisorChainBuild,
+ firstCallableHop: number
+): { parts: string[]; metered: boolean } {
+ const parts: string[] = [];
+ let metered = false;
+ for (let i = firstCallableHop + 1; i < plan.hops.length; i++) {
+ const b = build.builds[i];
+ const hop = plan.hops[i];
+ if (b.kind === "refused") {
+ const stops = b.chainContinues ? "" : "; the chain stops here";
+ parts.push(`; then ${hop.displayName} (refuses: ${b.message}${stops})`);
+ if (!b.chainContinues) break;
+ continue;
+ }
+ if (b.kind !== "built" && b.kind !== "built-pending") continue;
+ parts.push(`; then ${hop.displayName} (${billingWord(hop.billing)})`);
+ if (hop.billing === "metered") metered = true;
+ }
+ return { parts, metered };
+}
+
+/**
+ * The notice line for any plan. A routed plan is described from its BUILT
+ * chain: the first callable hop, every later hop a call can reach, the
+ * subscription candidates routing skipped and why, and the hops that could
+ * not be built. A refused plan reads as its refusal.
+ */
+export function describeAdvisorPlan(plan: AdvisorModelPlan, build?: AdvisorChainBuild): string {
+ if (plan.kind === "claude-native") return describeClaudeAdvisorPlan(plan);
+ if (plan.kind === "refused") return describeAdvisorRefusal(plan);
+ if (!build || build.firstCallableHop === null) {
+ return build ? describeAdvisorRefusal({ plan, build }) : `${plan.spec} -> (not built)`;
+ }
+
+ const first = plan.hops[build.firstCallableHop];
+ const later = laterHopParts(plan, build, build.firstCallableHop);
+ const parts = [
+ `${plan.spec} -> ${first.displayName} (${billingWord(first.billing)})`,
+ ...later.parts,
+ ];
+ const laterMetered = later.metered;
+
+ const skipped = plan.explanation.candidates
+ .filter(
+ (c) =>
+ c.outcome !== "kept" && (c.tier === "subscription" || c.tier === "dynamic-subscription")
+ )
+ .map(
+ (c) => `${c.displayName} — ${SKIPPED_PHRASE[c.outcome as Exclude<CandidateOutcome, "kept">]}`
+ );
+ if (skipped.length > 0) parts.push(` (skipped: ${skipped.join("; ")})`);
+
+ const notBuilt = plan.hops
+ .filter((_, i) => build.builds[i].kind === "not-built" || build.builds[i].kind === "failed")
+ .map((hop) => hop.displayName);
+ for (const name of notBuilt) parts.push(` (not built: ${name}; see the debug log)`);
+
+ if (first.billing === "subscription" && laterMetered) {
+ parts.push(" (a rejected subscription login is reported, never routed onto a metered hop)");
+ }
+ return parts.join("");
+}
+
+// ---------------------------------------------------------------------------
+// The panel gateway's contract (implemented in advisor-panel-gateway.ts)
+// ---------------------------------------------------------------------------
+
+/** One turn of the conversation a panel member is asked about, flattened to text. */
+export interface AdvisorTurn {
+ role: "user" | "assistant";
+ content: string;
+}
+
+/** The Anthropic-shaped body a routed panel call sends through its chain. */
+export interface AdvisorPanelPayload {
+ model: string;
+ system: string;
+ messages: AdvisorTurn[];
+ max_tokens: number;
+ stream: false;
+}
+
+/**
+ * The body of a routed advisor call. Deliberately nothing but these keys: no
+ * `tools`, `tool_choice`, `metadata`, `thinking` or `output_config`. Without
+ * tools and a session id, code mode stays off (`decideCodeMode`), Layer 4 has
+ * no session to drain, and the panel cannot call back into the advisor.
+ */
+export function buildAdvisorPanelPayload(
+ hop0ModelSpec: string,
+ system: string,
+ turns: AdvisorTurn[],
+ maxTokens: number
+): AdvisorPanelPayload {
+ return { model: hop0ModelSpec, system, messages: turns, max_tokens: maxTokens, stream: false };
+}
+
+export interface AdvisorPanelCall {
+ plan: RoutedPlan;
+ payload: AdvisorPanelPayload;
+ /** 60 000 for a panel member, 30 000 for the collector. */
+ timeoutMs: number;
+}
+
+export interface AdvisorPanelResult {
+ /** The answer's HTTP status; null on timeout or an internal error. */
+ status: number | null;
+ /** The WHOLE body, read inside the deadline and redacted by value. */
+ bodyText: string;
+ /** `isStreamFailureResponse(response)`: a 200 whose stream ended on an error. */
+ streamFailure: boolean;
+ /** Snapshot of the hop log: every hop whose `handle()` was entered, in order. */
+ hops: Array<HopAttempt & { uid: string | null; displayName: string }>;
+ /** The chain's first callable hop at startup: what the notice promised this member. */
+ plannedHop?: { provider: string; displayName: string; billing: AdvisorBilling };
+ failure?: { kind: "timeout" | "internal"; message: string };
+ latencyMs: number;
+}
+
+export interface AdvisorPanelGateway {
+ /** The startup plan for a spec; a spec the startup map lacks is a refused plan. */
+ plan(spec: string, role: AdvisorRole): AdvisorModelPlan;
+ /** Run one routed call through its startup-built chain. Never rejects. */
+ call(req: AdvisorPanelCall): Promise<AdvisorPanelResult>;
+}
+
+// ---------------------------------------------------------------------------
+// Advice extraction
+// ---------------------------------------------------------------------------
+
+/** Why a 2xx answer carried no advice text. */
+export type AdvisorEmptyReason =
+ | "no-content"
+ | "reasoning-only"
+ | "max-tokens-before-text"
+ | "max-tokens-during-reasoning";
+
+export interface ExtractedAdvice {
+ /** Every `text` block, joined with a blank line and trimmed; absent when empty. */
+ text?: string;
+ emptyReason?: AdvisorEmptyReason;
+ /** The message's `stop_reason`, verbatim. */
+ stopReason?: string;
+ usage?: { input_tokens: number; output_tokens: number };
+}
+
+/**
+ * The advice in one Anthropic-shaped message, or the named reason there is
+ * none. Every text block counts, not only the first. No text: `max_tokens`
+ * with a non-empty thinking block is "max-tokens-during-reasoning", without
+ * one "max-tokens-before-text"; otherwise a thinking block makes it
+ * "reasoning-only", and nothing at all "no-content".
+ */
+export function extractAdvice(message: unknown): ExtractedAdvice {
+ const m = (message && typeof message === "object" ? message : {}) as {
+ content?: unknown;
+ stop_reason?: unknown;
+ usage?: { input_tokens?: unknown; output_tokens?: unknown };
+ };
+ const blocks = Array.isArray(m.content) ? (m.content as Array<Record<string, unknown>>) : [];
+ const stopReason = typeof m.stop_reason === "string" ? m.stop_reason : undefined;
+ const inputTokens = m.usage?.input_tokens;
+ const outputTokens = m.usage?.output_tokens;
+ const usage =
+ typeof inputTokens === "number" && typeof outputTokens === "number"
+ ? { input_tokens: inputTokens, output_tokens: outputTokens }
+ : undefined;
+ const base = {
+ ...(stopReason !== undefined ? { stopReason } : {}),
+ ...(usage ? { usage } : {}),
+ };
+
+ const text = blocks
+ .filter((b) => b?.type === "text" && typeof b.text === "string")
+ .map((b) => b.text as string)
+ .join("\n\n")
+ .trim();
+ if (text) return { text, ...base };
+
+ const thought = blocks.some(
+ (b) => b?.type === "thinking" && typeof b.thinking === "string" && b.thinking.trim() !== ""
+ );
+ let emptyReason: AdvisorEmptyReason;
+ if (stopReason === "max_tokens") {
+ emptyReason = thought ? "max-tokens-during-reasoning" : "max-tokens-before-text";
+ } else {
+ emptyReason = thought ? "reasoning-only" : "no-content";
+ }
+ return { emptyReason, ...base };
+}
diff --cc packages/cli/src/handlers/composed-handler.ts
index 6788325d,bc4269fa..a9525c5f
--- a/packages/cli/src/handlers/composed-handler.ts
+++ b/packages/cli/src/handlers/composed-handler.ts
@@@ -35,23 -41,10 +41,25 @@@ import { lookupModelAcceptsImages, look
import type { QuotaAdapter } from "../auth/quota/adapter.js";
import { resolveQuotaAdapter } from "../auth/quota/registry.js";
import { PLAN_POLL_INTERVAL_MS } from "../auth/quota/types.js";
- import type { BehaviorEngine, BehaviorSession } from "../behavior/index.js";
- import { getBehaviorEngine } from "../behavior/index.js";
+import { accountKeyFromBinding } from "../code-mode/ids.js";
+import { type CodeModeSetting, DEFAULT_CODE_MODE_SETTING } from "../code-mode/policy.js";
+import { createCodeModeTurnHooks } from "../code-mode/relay.js";
+import {
+ type CodeModePayloadContext,
+ type PreparedCodeMode,
+ isLiteRejection,
+ prepareCodeModeRequest,
+ rebuildAsClassic,
+ withoutLiteHeader,
+} from "../code-mode/request.js";
+import { resumeFromToolResults } from "../code-mode/resume.js";
+import { loadQuickJSModule } from "../code-mode/sandbox/quickjs-loader.js";
+import { getCodeModeStores, peekCodeModeStores } from "../code-mode/stores.js";
+import { conversationMessages } from "../code-mode/types.js";
+ import { getHookEngine } from "../hooks/index.js";
+ import { type RawStreamTap, statsNames } from "../hooks/raw.js";
+ import type { UpstreamFacts } from "../hooks/registry.js";
+ import { type HookRequestScope, isNativeRoute, requestHooksOf } from "../hooks/request-stage.js";
import {
getLogLevel,
log,
@@@ -302,16 -245,6 +310,16 @@@ export interface ComposedHandlerOption
wireMode?: WireMode;
/** `#<speed>` on the model spec, refused where the wire does not publish it. */
wireSpeed?: WireSpeed;
+ /**
+ * Who issues requests through this handler. `"advisor"` marks a handler built
+ * for `--advisor` panel and collector calls, which claudish issues itself:
+ * it writes no status-line token file (the main session owns it), skips the
+ * plan-usage scrape and poll (that reading belongs on the main status line
- * too), starts no Layer 4 session (a panel call is not a harness turn), and
++ * too), runs no hooks (a panel call is not a harness turn), and
+ * tags every stats event `request_role: "advisor"`. Absent on every handler
+ * that serves Claude Code's own requests.
+ */
+ requestRole?: "advisor";
}
export class ComposedHandler implements ModelHandler {
@@@ -476,19 -378,42 +454,55 @@@
});
}
+ /**
+ * The endpoint a binding signs for, read only for its credential query
+ * parameters (Gemini's `?key=`). Never throws: a transport that cannot name
+ * its endpoint here simply contributes no query value.
+ */
+ private signedEndpoint(binding: AuthBinding | undefined): string | undefined {
+ try {
+ return this.provider.getEndpoint(this.targetModel, binding);
+ } catch {
+ return undefined;
+ }
+ }
+
+ /**
+ * The route hooks are scoped by. `native` is the exact rule the plan-mode
+ * supervisor has always used: `claude-*` names and the `anthropic` provider,
+ * unless the provider profile sets `forceForeignModel`.
+ */
+ private routeInfo(): { modelId: string; provider: string; native: boolean } {
+ return {
+ modelId: this.bareModelName,
+ provider: this.provider.name,
+ native: isNativeRoute(this.bareModelName, this.provider.name, this.options.forceForeignModel),
+ };
+ }
+
+ /**
+ * `middleware_names` for stats: the built-in raw hooks (the Gemini
+ * thought-signature hook, today) that apply to this route. User hooks never
+ * appear, so the OTLP `llm.middleware` attribute is unchanged for them.
+ */
+ private rawStatsNames(): string[] {
+ return statsNames(getHookEngine(), this.routeInfo(), this.upstreamFacts());
+ }
+
+ /**
+ * What the catalog says about this handler's upstream, for built-ins selected
+ * from data rather than by model name (`BuiltinHook.selectByUpstream`). Only
+ * with a catalog connection: without one the hooks' name globs decide.
+ */
+ private upstreamFacts(): UpstreamFacts | undefined {
+ const connection = this.options.connection;
+ if (!connection) return undefined;
+ return {
+ wireApi: connection.wire.status === "known" ? connection.wire.api : null,
+ vendor: connection.vendor ?? null,
+ };
+ }
+
/** Provider adapter — handles transport format (messages, tools, payload) */
private getAdapter(): BaseModelAdapter {
return this.explicitAdapter || this.resolvedDialect;
@@@ -587,89 -512,6 +601,89 @@@
};
}
+ /**
+ * The ONE writer of this handler's stats events. Every `recordStats` call in
+ * this class goes through here, so a field that must be on every event (the
+ * request role of an advisor handler) is added in one place and cannot be
+ * missed by a site added later.
+ */
+ private emitStats(event: Parameters<typeof recordStats>[0]): void {
+ recordStats(
+ this.options.requestRole ? { ...event, request_role: this.options.requestRole } : event
+ );
+ }
+
+ /**
+ * Fill a hop-log entry once the request is signed: the arm from the
+ * binding the credential half returned (`RequestAuth.arm`, never inferred
+ * from a resolved object's truthiness), and the billing.
+ *
+ * For a provider whose billing the signing credential decides
+ * (`CREDENTIAL_DECIDED_PROVIDERS`, i.e. `openai-codex`) the billing is THIS
+ * request's arm: `oauth` is the subscription, anything else (absent
+ * included) is metered. It is never `isSubscriptionProvider(name)`, whose
+ * probe reads a process-wide last-signed arm that a concurrent main request
+ * can overwrite between this request's refresh and this line. Every other
+ * provider's billing is its fixed category (`SUBSCRIPTION_PROVIDERS`
+ * membership), whatever arm signs: a flat-rate key is still flat-rate.
+ */
+ private markHopSigned(hop: HopAttempt, binding: AuthBinding | undefined): void {
+ hop.arm = binding?.auth?.arm ?? null;
+ hop.billing = this.signedBilling(binding).subscription ? "subscription" : "metered";
+ }
+
+ /**
+ * The billing of a request signed with `binding`, by the rule above: the
+ * signing arm for a credential-decided provider, the fixed category for
+ * every other one. The ONE derivation shared by the hop label
+ * (`markHopSigned`) and the request's cost updates (`handleStream`), so the
+ * two cannot disagree.
+ */
+ private signedBilling(binding: AuthBinding | undefined): RequestBilling {
+ const name = this.provider.name.toLowerCase();
+ return {
+ subscription: CREDENTIAL_DECIDED_PROVIDERS.has(name)
+ ? binding?.auth?.arm === "oauth"
+ : isSubscriptionProvider(name),
+ };
+ }
+
+ /**
+ * The answer when an internal call's deadline passed (`call-context.ts`).
+ * No classification, no recovery, nothing on stderr: the caller has already
+ * stopped waiting and reports the timeout itself. One failure stats event,
+ * so the attempt is still counted. Unreachable on a main request, which
+ * never carries a call signal.
+ */
+ private respondCallAborted(
+ startTime: number,
+ fallbackMeta?: { chain: string[]; attempts: number }
+ ): Response {
+ log(`[${this.provider.displayName}] call stopped: its deadline passed`);
+ try {
+ this.emitStats({
+ model_id: this.targetModel,
+ provider_name: this.provider.name,
+ stream_format: this.provider.streamFormat,
+ latency_ms: Math.round(performance.now() - startTime),
+ success: false,
+ http_status: 408,
+ error_class: "timeout",
+ error_code: "call_aborted",
+ token_strategy: this.options.tokenStrategy ?? "standard",
+ adapter_name: this.getActiveAdapterName(),
- middleware_names: this.middlewareManager.getActiveNames(this.bareModelName),
++ middleware_names: this.rawStatsNames(),
+ fallback_used: fallbackMeta !== undefined,
+ fallback_chain: fallbackMeta?.chain,
+ fallback_attempts: fallbackMeta?.attempts,
+ invocation_mode: this.options.invocationMode ?? "auto-route",
+ });
+ } catch {
+ // Stats must never crash claudish
+ }
+ return abortedResponse();
+ }
+
/**
* The ONE response shape for "claudish could not reach the host".
*
@@@ -1221,17 -1056,27 +1235,40 @@@
// several at once. It stays all-zero and contributes NOTHING to any stats
// record unless a classified connection failure actually occurs.
const recoveryTally = ComposedHandler.newRecoveryTally();
+ // An internal call's deadline (the advisor panel gateway installs it).
+ // Undefined on every request from Claude Code, and then every use below
+ // collapses to the expression that ran before it existed.
+ const callSignal = callAbortSignal(c);
+ // This hop's entry in an internal call's hop log (advisor gateway only):
+ // pushed on entry, so the log lists every hop whose handle() ran, and
+ // filled with the signing arm once 5b has signed.
+ const hop = recordHopEntry(c, this.provider.name, this.bareModelName);
+ if (callSignal?.aborted) return this.respondCallAborted(startTime, fallbackMeta);
// 1. Transform incoming Claude-format request
- const { claudeRequest, droppedParams } = transformOpenAIToClaude(payload);
+ const transformed = transformOpenAIToClaude(payload);
+ const { droppedParams } = transformed;
+ // `let`: a raw `providerRequest` hook's committed copies replace it (3b).
+ let claudeRequest = transformed.claudeRequest;
+
+ // 1a. Hook request stage A, on this attempt's own deep copy (each
+ // FallbackHandler candidate gets a fresh one, so nothing leaks between
+ // attempts). Before conversion, so a system note reaches every route:
+ // chat-completions adapters copy `system` into messages[0] at step 2 and
+ // build their payload from `messages` alone.
- const hooks = requestHooksOf(c);
++ // An advisor handler runs none: a panel call is not a harness turn, and its
++ // request carries no session id whose pending notes it could consume. The
++ // panel gateway's never-served context carries no hooks either; this check
++ // keeps that true if an advisor handler is ever reached another way.
++ const hooks = this.options.requestRole === "advisor" ? undefined : requestHooksOf(c);
+ const hookScope: HookRequestScope | undefined = hooks
+ ? await hooks.beginAttempt(c, {
+ claudeRequest,
+ route: this.routeInfo(),
+ upstream: this.upstreamFacts(),
+ model: typeof payload?.model === "string" ? payload.model : this.bareModelName,
+ stream: payload?.stream === true,
+ })
+ : undefined;
// 2. Get adapter and reset state
const adapter = this.getAdapter();
@@@ -1653,100 -1463,15 +1672,101 @@@
}
}
+ // 5r. Code-mode resume (`openai-codex`): tool_results answering a suspended
+ // exec script's batch feed the script. After 5b, so the account is THIS
- // request's; after 3c, so a synthetic reply gets the same Layer 4 hooks.
++ // request's; after 3b, so a synthetic reply gets the same raw hooks (the
++ // response seam above this handler applies the closed tool hooks to it).
+ // Synchronous from record lookup to state transition. A script that
+ // blocked again is answered here with its next batch — no upstream call,
+ // no further auth, no stats record (nothing was billed) — through the same
+ // exit as step 8. Anything else continues. A store that was never created
+ // (no code-mode request in this process) is created here only when the
+ // last message answers nested ids — the first request after a restart —
+ // so the lost script's tombstone exists before 5d builds the input.
+ if (this.provider.name === "openai-codex") {
+ const resume = (mayRequestModule: boolean) =>
+ resumeFromToolResults(
+ claudeRequest,
+ binding,
+ peekCodeModeStores(),
+ claudeRequest?.tool_choice,
+ {
+ setting: this.options.codeMode ?? DEFAULT_CODE_MODE_SETTING,
+ createStores: getCodeModeStores,
+ mayRequestModule,
+ }
+ );
+ let resumed = resume(true);
+ if (resumed.kind === "needs-module") {
+ // A lost script can replay, but its module was dropped (retired,
+ // poisoned, recycled). 5r never awaits: load here, then run 5r once
+ // more — never a third time, so a failed load ends in the tombstone.
+ await loadQuickJSModule();
+ resumed = resume(false);
+ }
+ if (resumed.kind === "reply") {
+ const sse = createSyntheticToolUseReply(resumed.blocks, {
+ modelName: this.bareModelName,
+ priorInputTokens: this.tokenTracker.getLastInputTokens(),
- middlewareManager: this.middlewareManager,
- ...this.responsesHooks(behaviorSession),
++ onToolCallObserved: (name: string) => this.tokenTracker.recordToolUse(name),
++ raw: hookScope?.raw.streamTap(),
+ });
+ return payload?.stream === true ? sse : sseResponseToJson(sse, this.bareModelName);
+ }
+ }
+
// 5c. Provider payload transformation (e.g., CodeAssist envelope wrapping)
if (this.provider.transformPayload) {
- requestPayload = this.provider.transformPayload(requestPayload, claudeRequest);
+ requestPayload = this.provider.transformPayload(requestPayload, claudeRequest, binding);
+ }
+
+ // 5d. Code mode (`openai-codex` only; by default `auto`, on where
+ // discovery reports `code_mode_only`; `--code-mode` / CLAUDISH_CODE_MODE /
+ // `codeMode` override it). After 5c, so the Codex fields 5c added are
+ // kept; decided from THIS request's binding. A lite
+ // request's header joins `wireHeaders`, so every header fetch below
+ // carries it. Never throws: a failed decision or build leaves the request
+ // exactly as 5c produced it.
+ //
+ // `codeModeShape` is the shape actually sent (`lite` falls back to
+ // `classic` in the 4xx block when the backend rejects it); the clone and
+ // context are what that fallback rebuilds from.
+ let codeModeShape: "lite" | "classic" | undefined;
+ let codeModePrePayload: any;
+ let codeModeContext: CodeModePayloadContext | undefined;
+ let codeModeTurn: PreparedCodeMode["turn"];
+ if (this.provider.name === "openai-codex") {
+ const prepared = await prepareCodeModeRequest({
+ providerName: this.provider.name,
+ setting: this.options.codeMode ?? DEFAULT_CODE_MODE_SETTING,
+ binding,
+ api:
+ wire?.status === "known"
+ ? wire.api
+ : this.resolveStreamFormat() === "openai-responses-sse"
+ ? "responses"
+ : undefined,
+ claudeRequest,
+ payload: requestPayload,
+ });
+ if (prepared.request) {
+ requestPayload = prepared.request.payload;
+ codeModeShape = prepared.request.shape;
+ codeModePrePayload = prepared.prePayload;
+ codeModeContext = prepared.context;
+ codeModeTurn = prepared.turn;
+ wireHeaders = [...wireHeaders, ...prepared.request.headers];
+ // 5a'. --model-params again, only for a code-mode payload: the user's
+ // explicit fields still win over what 5d wrote (idempotent deep merge).
+ if (this.options.modelParams) deepMergeParams(requestPayload, this.options.modelParams);
+ }
}
- // (Middleware beforeRequest ran at step 3b, before buildPayload — see the
- // note there for why it cannot run at this point.)
+ // (Raw providerRequest hooks ran at step 3b, before buildPayload — see the
+ // note there for why they cannot run at this point.)
- const endpoint = this.provider.getEndpoint(this.targetModel);
+ // `let`: the 401 branch replaces `binding` and recomputes the endpoint from it.
+ let endpoint = this.provider.getEndpoint(this.targetModel, binding);
// The ORIGINAL inbound body, not the normalized `claudeRequest` clone: a
// header carrying conversation identity must see what Claude Code sent.
//
@@@ -2712,10 -2286,10 +2732,10 @@@
success: false,
http_status: 503,
error_class: "server_error",
- error_code: settled.code,
+ error_code: upstreamCode,
token_strategy: this.options.tokenStrategy ?? "standard",
adapter_name: this.getActiveAdapterName(),
- middleware_names: this.middlewareManager.getActiveNames(this.bareModelName),
+ middleware_names: this.rawStatsNames(),
fallback_used: fallbackMeta !== undefined,
fallback_chain: fallbackMeta?.chain,
fallback_attempts: fallbackMeta?.attempts,
@@@ -2785,10 -2352,10 +2805,10 @@@
success: false,
http_status: httpStatus,
error_class: isTerminal ? "client_error" : "server_error",
- error_code: settled.code,
+ error_code: upstreamCode,
token_strategy: this.options.tokenStrategy ?? "standard",
adapter_name: this.getActiveAdapterName(),
- middleware_names: this.middlewareManager.getActiveNames(this.bareModelName),
+ middleware_names: this.rawStatsNames(),
fallback_used: fallbackMeta !== undefined,
fallback_chain: fallbackMeta?.chain,
fallback_attempts: fallbackMeta?.attempts,
@@@ -2987,27 -2447,17 +3008,27 @@@
}
};
- const streamed = this.handleStream(
- c,
- response,
- adapter,
- claudeRequest,
- toolNameMap,
- onStreamComplete,
- (code, message) => {
- streamApiError = { code, message };
- },
- hookScope?.raw.streamTap()
+ const streamed = notifyOnDownstreamCancel(
+ this.handleStream(
+ c,
+ response,
+ adapter,
+ claudeRequest,
+ // Decided from the binding this request was finally signed with (a 401
+ // re-sign replaced it above); every leg of a Responses turn signs on
+ // that same arm, or the leg issuer refuses it.
+ this.signedBilling(binding),
+ toolNameMap,
+ onStreamComplete,
+ (code, message) => {
+ streamApiError = { code, message };
+ },
- behaviorSession,
++ hookScope?.raw.streamTap(),
+ responsesTurn
+ ),
+ () => {
+ clientCancelled = true;
+ }
);
// A client that did not ask for a stream gets the single JSON message the
@@@ -3280,8 -2704,8 +3280,9 @@@
toolNameMap?: Map<string, string>,
onComplete?: () => void,
onApiError?: (code: string, message: string) => void,
- behaviorSession?: BehaviorSession,
+ /** The raw `providerChunk`/`providerStreamEnd` tap for this stream, when one applies. */
- raw?: RawStreamTap
++ raw?: RawStreamTap,
+ responsesTurn?: ResponsesTurnWiring
): Response {
// Local mutable copy so we can null it out after firing (prevents double-firing)
// without reassigning the function parameter.
@@@ -3394,17 -2796,8 +3384,15 @@@
contextWindow: lookupModelForProvider(this.bareModelName, this.provider.name),
onApiError,
priorInputTokens,
- middlewareManager: this.middlewareManager,
- // The same builder as a 5r synthetic reply, so a resumed batch gets
- // exactly the hooks a driver batch gets.
- ...this.responsesHooks(behaviorSession),
+ raw,
+ onToolCallObserved: observeToolCall,
+ retry: responsesTurn?.retry,
+ // Earlier legs of a retried turn: cost only, before the stats snapshot
+ // that onTokenUpdate fires.
+ onExtraBilledInput: (input, detail) =>
+ this.tokenTracker.addBilledInputTokens(input, detail, billing),
+ onTurnSummary: responsesTurn?.onTurnSummary,
+ codeMode: responsesTurn?.codeMode,
});
case "anthropic-sse":
diff --cc packages/cli/src/handlers/native-handler-advisor.ts
index c72e6a4e,5bad9527..f855b8e8
--- a/packages/cli/src/handlers/native-handler-advisor.ts
+++ b/packages/cli/src/handlers/native-handler-advisor.ts
@@@ -34,40 -35,16 +34,40 @@@
*/
import { appendFileSync } from "node:fs";
+import type { Context } from "hono";
import { credentials } from "../auth/credentials/authority.js";
- import type { ChildAuthControl, ChildAuthSource } from "../claude-runner.js";
++import type { ChildAuthControl, ChildAuthSource } from "../child-auth-types.js";
import { getAlwaysOnLogPath, getLogFilePath, log, logStderr } from "../logger.js";
-import { type SlimModelEntry, readAllModelsCache } from "../providers/all-models-cache.js";
-import { getCatalogEntries, latestAnthropicTierModelId } from "../providers/catalog-client.js";
-import { findEntryByAlias } from "../providers/catalog-query.js";
-import { resolveConnection, resolveRouteProfile } from "../providers/connection-resolver.js";
-import { type KnownWire, type WireApi, wireRequestUrl } from "../providers/connection-wire.js";
-import { parseModelSpec } from "../providers/model-parser.js";
+import { resolveConnection } from "../providers/connection-resolver.js";
+import type { KnownWire, WireApi } from "../providers/connection-wire.js";
+import { getProviderByName } from "../providers/provider-definitions.js";
import { mergeWireHeaders, shapeRequestFromWire } from "../providers/wire-request.js";
+import {
+ acquireSigningLease,
+ redactExactValues,
+ redactForClient,
+ redactSigningValues,
+} from "../redact.js";
+import type { StatsEvent } from "../stats-otlp.js";
+import { recordStats } from "../stats.js";
+import { isBillingHeaderText } from "../transform.js";
+import { ANTHROPIC_API_HOST, ANTHROPIC_MESSAGES_URL } from "./advisor-claude-route.js";
+import {
+ type AdvisorBilling,
+ type AdvisorEmptyReason,
+ type AdvisorModelPlan,
+ type AdvisorPanelGateway,
+ type AdvisorPanelResult,
+ type AdvisorTurn,
+ type ExtractedAdvice,
+ billingWord,
+ buildAdvisorPanelPayload,
+ describeAdvisorRefusal,
+ extractAdvice,
+} from "./advisor-route-plan.js";
import { extractProviderMessage, extractUpstreamStatus } from "./shared/anthropic-error.js";
+import { addSigningSecrets, credentialValuesFromRequest } from "./shared/call-context.js";
+import { calculateCost } from "./shared/remote-provider-types.js";
const ADVISOR_SERVER_TOOL_TYPE = "advisor_20260301";
const ADVISOR_BETA_FLAG = "advisor-tool-2026-03-01";
diff --cc packages/cli/src/handlers/native-handler.ts
index 406e2455,c96f1905..b05ba736
--- a/packages/cli/src/handlers/native-handler.ts
+++ b/packages/cli/src/handlers/native-handler.ts
@@@ -1,8 -1,7 +1,9 @@@
import type { Context } from "hono";
import { credentials } from "../auth/credentials/authority.js";
+ import { requestHooksOf } from "../hooks/request-stage.js";
import { log, maskCredential } from "../logger.js";
+import { redactForClient } from "../redact.js";
+import { ANTHROPIC_API_ORIGIN } from "./advisor-claude-route.js";
import { ADVISOR_SWAPPED_CONTEXT_KEY } from "./advisor-decorator.js";
import {
loadAdvisorSwapConfig,
diff --cc packages/cli/src/handlers/shared/stream-parsers/anthropic-sse.ts
index 8e536b32,84461ad6..7a420e96
--- a/packages/cli/src/handlers/shared/stream-parsers/anthropic-sse.ts
+++ b/packages/cli/src/handlers/shared/stream-parsers/anthropic-sse.ts
@@@ -508,213 -464,111 +409,204 @@@ export function createAnthropicPassthro
}
}
} else {
- // Non-data line — an `event:` header or the blank separator —
- // on EITHER path.
- //
- // The header is held for exactly one line because its `data:`
- // line may still be dropped, and a header already on the wire
- // cannot be recalled. Claude Code rejects a header with no
- // body outright: `Could not parse message into JSON: From
- // chunk: [ "event:content_block_start" ]` kills the whole turn.
- //
- // This used to be conditional on `filterThinking`, on the
- // reasoning that only the thinking filter ever dropped a
- // frame. That stopped being true when the index layer began
- // dropping orphans, which it does on BOTH paths — and the
- // unfiltered one is the common case for z.ai, Kimi and qwen,
- // i.e. exactly the providers whose jumped indices the layer
- // exists to repair. Measured before this change: an orphaned
- // delta+stop pair left two bare `event:` lines on the wire.
- if (line.startsWith("event:")) {
- pendingEventLine = line;
- } else if (line.trim() === "" && suppressedFrame) {
- suppressedFrame = false; // swallow the dropped frame's separator
- } else if (!isClosed) {
- controller.enqueue(encoder.encode(`${line}\n`));
+ // Non-data lines (event: lines, blank lines) or no filtering
+ if (!filterThinking && payload !== null) {
+ // Parse data lines BEFORE enqueuing to detect in-stream errors
+ try {
+ const data = JSON.parse(payload);
+
+ // ── In-stream error detection (GitHub #106) ──
+ if (data.error) {
+ const errMsg = data.error.message || JSON.stringify(data.error);
+ log(`[AnthropicSSE] In-stream error detected: ${errMsg}`);
+ if (!isClosed) {
+ controller.enqueue(
+ encoder.encode(
+ `event: error\ndata: ${JSON.stringify({
+ type: "error",
+ error: { type: "api_error", message: redactForClient(errMsg) },
+ })}\n\n`
+ )
+ );
+ isClosed = true;
+ if (pingInterval) {
+ clearInterval(pingInterval);
+ pingInterval = null;
+ }
+ controller.close();
+ }
+ return; // stop processing further lines
+ }
+
- // No error — check index bounds before passing through
- // (still via the tool interceptor, which is a no-op unless
- // a rule asked for this tool).
++ // No error — check index bounds before passing through.
+ emitIndexed(controller, data, line);
+
+ // Usage/debug tracking, in its OWN try. The outer catch
+ // re-enqueues the raw line, which is right for a data line
+ // that would not parse — but by this point the frame has
+ // already been emitted, rewritten, or deliberately dropped.
+ // Letting a tracking throw reach that catch emits it a
+ // second time: a double frame, or a resurrected orphan
+ // carrying the very index the layer just removed. The
+ // filtered path already isolates its tracking this way.
+ try {
+ if (data.message?.usage) {
+ inputTokens = data.message.usage.input_tokens || inputTokens;
+ outputTokens = data.message.usage.output_tokens || outputTokens;
+ }
+ if (data.usage) {
+ inputTokens = data.usage.input_tokens || inputTokens;
+ outputTokens = data.usage.output_tokens || outputTokens;
+ }
+ if (
+ data.type === "content_block_delta" &&
+ data.delta?.type === "text_delta"
+ ) {
+ const txt = data.delta.text || "";
- opts.onAssistantText?.(txt, "text");
+ textChunks++;
+ log(
+ `[AnthropicSSE] Text chunk: "${txt.substring(0, 30).replace(/\n/g, "\\n")}" (${txt.length} chars)`
+ );
+ }
+ if (
+ data.type === "content_block_start" &&
+ data.content_block?.type === "tool_use"
+ ) {
+ toolUseBlocks++;
+ opts.onToolCallObserved?.(data.content_block.name);
+ log(`[AnthropicSSE] Tool use: ${data.content_block.name}`);
+ }
+ if (data.type === "message_delta" && data.delta?.stop_reason) {
+ stopReason = data.delta.stop_reason;
+ }
+ } catch {
+ // Observation must never change the wire.
+ }
+ } catch {
+ // Unparseable data line — pass through
+ if (!isClosed) {
+ controller.enqueue(encoder.encode(`${line}\n`));
+ }
+ }
+ } else {
+ // Non-data line — an `event:` header or the blank separator —
+ // on EITHER path.
+ //
+ // The header is held for exactly one line because its `data:`
+ // line may still be dropped, and a header already on the wire
+ // cannot be recalled. Claude Code rejects a header with no
+ // body outright: `Could not parse message into JSON: From
+ // chunk: [ "event:content_block_start" ]` kills the whole turn.
+ //
+ // This used to be conditional on `filterThinking`, on the
+ // reasoning that only the thinking filter ever dropped a
+ // frame. That stopped being true when the index layer began
+ // dropping orphans, which it does on BOTH paths — and the
+ // unfiltered one is the common case for z.ai, Kimi and qwen,
+ // i.e. exactly the providers whose jumped indices the layer
+ // exists to repair. Measured before this change: an orphaned
+ // delta+stop pair left two bare `event:` lines on the wire.
+ if (line.startsWith("event:")) {
+ pendingEventLine = line;
+ } else if (line.trim() === "" && suppressedFrame) {
+ suppressedFrame = false; // swallow the dropped frame's separator
+ } else if (!isClosed) {
+ controller.enqueue(encoder.encode(`${line}\n`));
+ }
}
}
- }
- // ── Usage/debug tracking for filtered path ────────────────
- // We need this even when filtering, but the data was already parsed
- // above in the filterThinking branch. Re-parse for tracking only.
- if (filterThinking && payload !== null) {
- try {
- const data = JSON.parse(payload);
- if (data.message?.usage) {
- inputTokens = data.message.usage.input_tokens || inputTokens;
- outputTokens = data.message.usage.output_tokens || outputTokens;
- }
- if (data.usage) {
- inputTokens = data.usage.input_tokens || inputTokens;
- outputTokens = data.usage.output_tokens || outputTokens;
- }
- if (data.type === "content_block_delta" && data.delta?.type === "text_delta") {
- textChunks++;
- }
- if (
- data.type === "content_block_start" &&
- data.content_block?.type === "tool_use"
- ) {
- toolUseBlocks++;
- opts.onToolCallObserved?.(data.content_block.name);
- log(`[AnthropicSSE] Tool use: ${data.content_block.name}`);
- }
- if (data.type === "message_delta" && data.delta?.stop_reason) {
- stopReason = data.delta.stop_reason;
- }
- } catch {}
+ // ── Usage/debug tracking for filtered path ────────────────
+ // We need this even when filtering, but the data was already parsed
+ // above in the filterThinking branch. Re-parse for tracking only.
+ if (filterThinking && payload !== null) {
+ try {
+ const data = JSON.parse(payload);
+ if (data.message?.usage) {
+ inputTokens = data.message.usage.input_tokens || inputTokens;
+ outputTokens = data.message.usage.output_tokens || outputTokens;
+ }
+ if (data.usage) {
+ inputTokens = data.usage.input_tokens || inputTokens;
+ outputTokens = data.usage.output_tokens || outputTokens;
+ }
+ if (data.type === "content_block_delta" && data.delta?.type === "text_delta") {
- opts.onAssistantText?.(data.delta.text || "", "text");
+ textChunks++;
+ }
+ if (
+ data.type === "content_block_start" &&
+ data.content_block?.type === "tool_use"
+ ) {
+ toolUseBlocks++;
+ opts.onToolCallObserved?.(data.content_block.name);
+ log(`[AnthropicSSE] Tool use: ${data.content_block.name}`);
+ }
+ if (data.type === "message_delta" && data.delta?.stop_reason) {
+ stopReason = data.delta.stop_reason;
+ }
+ } catch {}
+ }
}
}
- }
- log(
- `[AnthropicSSE] Stream complete for ${opts.modelName}: ${totalLines} lines, ${textChunks} text chunks, ${toolUseBlocks} tool_use blocks, stop_reason=${stopReason}${filterThinking ? `, filtered ${thinkingBlocksSuppressed} thinking blocks` : ""}`
- );
+ if (cancelled) {
+ endCancelled();
+ return;
+ }
- if (opts.onTokenUpdate) {
- opts.onTokenUpdate(inputTokens, outputTokens);
- }
+ log(
+ `[AnthropicSSE] Stream complete for ${opts.modelName}: ${totalLines} lines, ${textChunks} text chunks, ${toolUseBlocks} tool_use blocks, stop_reason=${stopReason}${filterThinking ? `, filtered ${thinkingBlocksSuppressed} thinking blocks` : ""}`
+ );
- opts.onTurnEnd?.();
-
- if (!isClosed) {
- isClosed = true;
- if (pingInterval) {
- clearInterval(pingInterval);
- pingInterval = null;
+ if (opts.onTokenUpdate) {
+ opts.onTokenUpdate(inputTokens, outputTokens);
}
- controller.close();
- }
- } catch (e) {
- log(`[AnthropicSSE] Stream error: ${e}`);
- // The upstream socket dropped mid-answer (Z.AI, MiniMax and Kimi all do
- // this under load). Closing the controller here without a terminal event
- // handed Claude Code a stream that stopped but never ended, and the turn
- // hung. Emit the tail first, then close, and still report the tokens so
- // the token file sees a completed turn rather than nothing.
- finalizeAbandonedStream(controller);
- try {
- opts.onTokenUpdate?.(inputTokens, outputTokens);
- } catch {}
- if (!isClosed) {
- isClosed = true;
- if (pingInterval) {
- clearInterval(pingInterval);
- pingInterval = null;
+
+ if (!isClosed) {
+ isClosed = true;
+ if (pingInterval) {
+ clearInterval(pingInterval);
+ pingInterval = null;
+ }
+ controller.close();
+ }
+ } catch (e) {
+ if (cancelled) {
+ endCancelled();
+ return;
+ }
+ log(`[AnthropicSSE] Stream error: ${e}`);
+ // The upstream socket dropped mid-answer (Z.AI, MiniMax and Kimi all do
+ // this under load). Closing the controller here without a terminal event
+ // handed Claude Code a stream that stopped but never ended, and the turn
- // hung. Emit the tail first, then close, and still run the turn-end hooks
- // so Layer 4 and the token file see a completed turn rather than nothing.
++ // hung. Emit the tail first, then close, and still report the tokens so
++ // the token file sees a completed turn rather than nothing.
+ finalizeAbandonedStream(controller);
- try {
- opts.onTurnEnd?.();
- } catch {}
+ try {
+ opts.onTokenUpdate?.(inputTokens, outputTokens);
+ } catch {}
+ if (!isClosed) {
+ isClosed = true;
+ if (pingInterval) {
+ clearInterval(pingInterval);
+ pingInterval = null;
+ }
+ controller.close();
}
- controller.close();
}
- }
- },
- cancel() {
- isClosed = true;
- if (pingInterval) {
- clearInterval(pingInterval);
- pingInterval = null;
- }
- },
- }),
+ },
+ // Downstream went away: cancelEndsUpstreamWork cancels the upstream reader
+ // after this and resolves only once the read loop above has settled.
+ cancel() {
+ cancelled = true;
+ isClosed = true;
+ if (pingInterval) {
+ clearInterval(pingInterval);
+ pingInterval = null;
+ }
+ },
+ })
+ ),
{
headers: {
"Content-Type": "text/event-stream",
diff --cc packages/cli/src/handlers/shared/stream-parsers/client-cancel.test.ts
index 5d70493f,00000000..b543bad6
mode 100644,000000..100644
--- a/packages/cli/src/handlers/shared/stream-parsers/client-cancel.test.ts
+++ b/packages/cli/src/handlers/shared/stream-parsers/client-cancel.test.ts
@@@ -1,418 -1,0 +1,431 @@@
+import { afterEach, describe, expect, mock, spyOn, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Context } from "hono";
+import type { StatsEvent } from "../../../stats.js";
+
+if (process.env.CLAUDISH_T2_CANCEL_CHILD !== "1") {
+ test("G2–G4 client-cancel contracts in an isolated HOME", async () => {
+ const home = mkdtempSync(join(tmpdir(), "claudish-t2-cancel-"));
+ try {
+ const child = Bun.spawn([process.execPath, "test", import.meta.path], {
+ cwd: home,
+ env: {
+ PATH: process.env.PATH,
+ HOME: home,
+ TMPDIR: home,
+ XDG_CONFIG_HOME: home,
+ CLAUDISH_T2_CANCEL_CHILD: "1",
+ },
+ stdout: "inherit",
+ stderr: "inherit",
+ });
+ expect(await child.exited).toBe(0);
+ } finally {
+ rmSync(home, { recursive: true, force: true });
+ }
+ }, 20_000);
+} else {
+ const { Hono } = await import("hono");
+ const { DefaultAPIFormat } = await import("../../../adapters/base-api-format.js");
- const { MiddlewareManager } = await import("../../../middleware/manager.js");
+ const logger = await import("../../../logger.js");
+ const { acquireSigningLease, redactSigningValues } = await import("../../../redact.js");
+ const { releaseWhenBodyEnds } = await import("../call-context.js");
+ const { cancelEndsUpstreamWork, notifyOnDownstreamCancel } = await import("./upstream-cancel.js");
+ const { createStreamingResponseHandler } = await import("./openai-sse.js");
+ const { createGeminiSseStream } = await import("./gemini-sse.js");
+ const { createAnthropicPassthroughStream } = await import("./anthropic-sse.js");
+ const { createDevinConnectStream } = await import("./devin-connect.js");
+ const { createOllamaJsonlStream } = await import("./ollama-jsonl.js");
+ const { ComposedHandler } = await import("../../composed-handler.js");
+ const stats = await import("../../../stats.js");
+
+ function deferred<T>() {
+ let resolve!: (value: T) => void;
+ const promise = new Promise<T>((yes) => {
+ resolve = yes;
+ });
+ return { promise, resolve };
+ }
+
+ async function ticks() {
+ for (let i = 0; i < 80; i++) await Promise.resolve();
+ }
+
+ const encoder = new TextEncoder();
+ const dataUrl = (name: string) =>
+ new URL(`../../../test-fixtures/sse-responses/${name}`, import.meta.url);
+ const grok = await Bun.file(dataUrl("grok-4.6-openai-advisor-turn1.sse")).text();
+ const gemini = await Bun.file(dataUrl("gemini-3.6-flash-antigravity-ok-answer.sse")).text();
+ const anthropic = await Bun.file(
+ dataUrl("minimax-m3-anthropic-implicit-signature-r10324.sse")
+ ).text();
+ const frames = (s: string) => s.match(/[\s\S]*?(?:\r?\n){2}/g) ?? [];
+
+ // All delivered frames are byte-for-byte slices of the named captures. Drop
+ // later frames, not fields, to model a client leaving before provider usage.
+ const openaiPrefix = frames(grok).slice(0, 12).join("");
+ const anthropicPrefix = frames(anthropic)
+ .filter((frame) => /event: content_block_(?:start|delta)/.test(frame))
+ .slice(0, 4)
+ .join("");
+ const usageFrame = frames(grok).find((frame) => /"usage":\{/.test(frame))!;
+ const geminiFrame = frames(gemini)[0];
+ const anthropicUsage = frames(anthropic).find((frame) => /event: message_delta/.test(frame))!;
+
+ function upstream(prefix = "", teardown?: Promise<void>) {
+ const waiting = deferred<void>();
+ const events: string[] = [];
+ const response = new Response(
+ new ReadableStream<Uint8Array>({
+ start(c) {
+ if (prefix) c.enqueue(encoder.encode(prefix));
+ },
+ pull() {
+ waiting.resolve();
+ },
+ async cancel() {
+ events.push("upstream-cancel");
+ await teardown;
+ events.push("upstream-settled");
+ },
+ })
+ );
+ return { response, waiting, events };
+ }
+
+ interface Hooks {
+ tokens: (input: number, output: number) => void;
- turnEnd: () => void;
- text: (text: string) => void;
- middlewareComplete: () => void;
++ /**
++ * The raw tier's `providerStreamEnd`: the one end-of-turn hook left at the
++ * parser level. The closed `responseEnd` runs at the response seam above
++ * every parser, and only on a `message_stop` (hooks/seam-tap.ts).
++ */
++ streamEnd: () => void;
+ }
++ /** A raw-tier tap that commits every chunk unchanged and records its stream end. */
++ const rawTap = (h: Hooks) => ({
++ chunk: <T>(chunk: T): T => chunk,
++ streamEnd: async () => {
++ h.streamEnd();
++ },
++ });
+ type Factory = (c: Context, response: Response, hooks: Hooks) => Response;
+ const factories: Record<string, Factory> = {
- "openai-sse": (c, r, h) => {
- const middleware = new MiddlewareManager();
- spyOn(middleware, "afterStreamComplete").mockImplementation(async () => {
- h.middlewareComplete();
- });
- return createStreamingResponseHandler(
++ "openai-sse": (c, r, h) =>
++ createStreamingResponseHandler(
+ c,
+ r,
+ new DefaultAPIFormat("t2"),
+ "t2",
- middleware,
++ rawTap(h),
+ h.tokens,
+ undefined,
+ undefined,
+ undefined,
- { onTurnEnd: h.turnEnd, onAssistantText: h.text }
- );
- },
++ {}
++ ),
+ "gemini-sse": (c, r, h) =>
+ createGeminiSseStream(c, r, {
+ modelName: "t2",
+ unwrapResponse: true,
++ raw: rawTap(h),
+ onTokenUpdate: h.tokens,
- onTurnEnd: h.turnEnd,
- onAssistantText: h.text,
+ }),
++ // No raw tap on these wires: the parser has no end-of-turn hook at all.
+ "anthropic-sse": (c, r, h) =>
+ createAnthropicPassthroughStream(c, r, {
+ modelName: "t2",
+ onTokenUpdate: h.tokens,
- onTurnEnd: h.turnEnd,
- onAssistantText: h.text,
+ }),
+ "devin-connect": (c, r, h) =>
+ createDevinConnectStream(c, r, {
+ modelName: "t2",
+ onTokenUpdate: h.tokens,
- onTurnEnd: h.turnEnd,
- onAssistantText: h.text,
+ }),
- // The public Ollama factory exposes no behavior-layer hook.
+ "ollama-jsonl": (c, r, h) =>
+ createOllamaJsonlStream(c, r, { modelName: "t2", onTokenUpdate: h.tokens }),
+ };
+
+ function hooks(): Hooks {
+ return {
+ tokens: mock(() => {}),
- turnEnd: mock(() => {}),
- text: mock(() => {}),
- middlewareComplete: mock(() => {}),
++ streamEnd: mock(() => {}),
+ };
+ }
+
++ /** Read the downstream body until `pattern` appears in what was delivered. */
++ async function readUntil(
++ reader: ReadableStreamDefaultReader<Uint8Array>,
++ pattern: RegExp
++ ): Promise<string> {
++ const decoder = new TextDecoder();
++ let seen = "";
++ while (!pattern.test(seen)) {
++ const { done, value } = await reader.read();
++ if (done) break;
++ seen += decoder.decode(value, { stream: true });
++ }
++ return seen;
++ }
++
+ function captureLogs() {
+ const lines: string[] = [];
+ spyOn(logger, "log").mockImplementation((line) => {
+ lines.push(line);
+ });
+ return lines;
+ }
+
+ async function parse(factory: Factory, response: Response, h: Hooks) {
+ const app = new Hono();
+ app.get("/", (c) => factory(c, response, h));
+ return app.request("http://t2.invalid/");
+ }
+
+ afterEach(() => {
+ mock.restore();
+ });
+
+ describe("G2 — cancellation is not silent truncation", () => {
+ for (const name of Object.keys(factories)) {
+ test(`${name}: cancel before usage records no estimate or turn-end hook`, async () => {
+ const lines = captureLogs();
+ const h = hooks();
+ // Gemini's available capture includes usage in its FIRST frame; cancel
+ // before it. No Devin/Ollama streaming capture exists in test-fixtures,
+ // so those two cases deliberately exercise the pre-first-byte path.
+ const prefix =
+ name === "openai-sse" ? openaiPrefix : name === "anthropic-sse" ? anthropicPrefix : "";
+ const source = upstream(prefix);
+ const response = await parse(factories[name], source.response, h);
- await source.waiting.promise;
- await ticks();
++ const reader = response.body!.getReader();
+ try {
- if (prefix) expect(h.text).toHaveBeenCalled();
++ // The prefix's content reached the client before it left.
++ const seen = prefix ? await readUntil(reader, /content_block_delta/) : "";
++ await source.waiting.promise;
++ await ticks();
++ if (prefix) expect(seen).toMatch(/content_block_delta/);
+ } finally {
- await response.body!.cancel("client left");
++ await reader.cancel("client left");
+ }
+ expect(source.events).toEqual(["upstream-cancel", "upstream-settled"]);
+ expect(h.tokens).not.toHaveBeenCalled();
- expect(h.turnEnd).not.toHaveBeenCalled();
- expect(h.middlewareComplete).not.toHaveBeenCalled();
++ expect(h.streamEnd).not.toHaveBeenCalled();
+ expect(
+ lines.filter((line) =>
+ /Stream ending error|silent-truncation|ending.*failure/i.test(line)
+ )
+ ).toEqual([]);
+ expect(lines.filter((line) => line.includes("Client cancelled the stream"))).toHaveLength(
+ 1
+ );
+ }, 10_000);
+ }
+
+ for (const [name, frame] of [
+ ["openai-sse", usageFrame],
+ ["gemini-sse", geminiFrame],
+ ["anthropic-sse", anthropicUsage],
+ ] as const) {
+ test(`${name}: cancel preserves provider-sent usage without a turn-end hook`, async () => {
+ const lines = captureLogs();
+ const h = hooks();
+ const source = upstream(frame);
+ const response = await parse(factories[name], source.response, h);
+ await source.waiting.promise;
+ await ticks();
+ await response.body!.cancel("client left");
+ expect(h.tokens).toHaveBeenCalledTimes(1);
- expect(h.turnEnd).not.toHaveBeenCalled();
- expect(h.middlewareComplete).not.toHaveBeenCalled();
++ expect(h.streamEnd).not.toHaveBeenCalled();
+ expect(lines.filter((line) => line.includes("Stream ending error"))).toEqual([]);
+ expect(lines.filter((line) => line.includes("Client cancelled the stream"))).toHaveLength(
+ 1
+ );
+ }, 10_000);
+ }
+ });
+
+ describe("G3 — a cancel retains its signing lease until work settles", () => {
+ test("outstanding parser read cannot release during delayed upstream cancellation", async () => {
+ const teardown = deferred<void>();
+ const source = upstream(openaiPrefix, teardown.promise);
+ const lease = acquireSigningLease();
+ const token = "OPAQUE_TEST_TOKEN_T2_parser";
+ lease.add([token]);
+ const release = mock(() => {
+ source.events.push("released");
+ lease.release();
+ });
+ const parsed = await parse(factories["openai-sse"], source.response, hooks());
+ const response = releaseWhenBodyEnds(parsed, release);
+ const reader = response.body!.getReader();
+ const consuming = (async () => {
+ while (!(await reader.read()).done) {
+ /* drain to the pending read */
+ }
+ })();
+ await source.waiting.promise;
+ await ticks();
+ const cancelled = reader.cancel("client left");
+ await ticks();
+ try {
+ expect(source.events).toEqual(["upstream-cancel"]);
+ expect(release).not.toHaveBeenCalled();
+ expect(redactSigningValues(token)).toBe("[redacted]");
+ } finally {
+ teardown.resolve();
+ await cancelled;
+ await consuming;
+ lease.release();
+ }
+ expect(source.events).toEqual(["upstream-cancel", "upstream-settled", "released"]);
+ expect(release).toHaveBeenCalledTimes(1);
+ expect(redactSigningValues(token)).toBe(token);
+ }, 10_000);
+
+ test("cancel awaits the parser task's delayed teardown, not only reader.cancel", async () => {
+ const teardown = deferred<void>();
+ const source = upstream();
+ const reader = source.response.body!.getReader();
+ const lease = acquireSigningLease();
+ const token = "OPAQUE_TEST_TOKEN_T2_task";
+ lease.add([token]);
+ const events: string[] = [];
+ const parsed = new Response(
+ new ReadableStream<Uint8Array>(
+ cancelEndsUpstreamWork(
+ { reader },
+ {
+ async start() {
+ await reader.read();
+ await teardown.promise;
+ events.push(`teardown:${redactSigningValues(token)}`);
+ },
+ }
+ )
+ )
+ );
+ const release = mock(() => {
+ events.push("released");
+ lease.release();
+ });
+ const wrapped = releaseWhenBodyEnds(parsed, release);
+ const downstream = wrapped.body!.getReader();
+ const pendingRead = downstream.read();
+ await source.waiting.promise;
+ const cancel = downstream.cancel();
+ await ticks();
+ try {
+ expect(source.events).toEqual(["upstream-cancel", "upstream-settled"]);
+ expect(release).not.toHaveBeenCalled();
+ expect(redactSigningValues(token)).toBe("[redacted]");
+ } finally {
+ teardown.resolve();
+ await cancel;
+ await pendingRead;
+ lease.release();
+ }
+ expect(events).toEqual(["teardown:[redacted]", "released"]);
+ expect(release).toHaveBeenCalledTimes(1);
+ expect(redactSigningValues(token)).toBe(token);
+ }, 10_000);
+ });
+
+ describe("G4 — cancellation stats", () => {
+ test("downstream cancel callback precedes the source's cancel", async () => {
+ const events: string[] = [];
+ const response = notifyOnDownstreamCancel(
+ new Response(
+ new ReadableStream({
+ cancel() {
+ events.push("source");
+ },
+ })
+ ),
+ () => {
+ events.push("callback");
+ }
+ );
+ await response.body!.cancel();
+ expect(events).toEqual(["callback", "source"]);
+ }, 10_000);
+
+ for (const withUsage of [false, true]) {
+ test(`ComposedHandler cancel ${withUsage ? "with" : "without"} provider usage`, async () => {
+ const events: Partial<StatsEvent>[] = [];
+ spyOn(stats, "recordStats").mockImplementation((event) => {
+ events.push(event);
+ });
+ const source = upstream(withUsage ? usageFrame : openaiPrefix);
+ const fetchSpy = spyOn(globalThis, "fetch").mockImplementation(
+ (async () => source.response) as unknown as typeof fetch
+ );
+ const handler = new ComposedHandler(
+ {
+ name: "t2-metered",
+ displayName: "T2",
+ streamFormat: "openai-sse",
+ getEndpoint: () => "http://t2.invalid/chat/completions",
+ getHeaders: async () => ({}),
+ },
+ "t2-model",
+ "t2-model",
+ 0,
+ {
+ adapter: new DefaultAPIFormat("t2-model", "openai-sse"),
+ requestRole: "advisor",
+ codeMode: "off",
+ catalogCachePath: join(process.env.HOME!, "absent-catalog.json"),
+ }
+ );
+ // Derived from the recorded Claude Code request: retain actual messages
+ // and limit, omit tool/system/metadata fields unrelated to cancellation.
+ const inbound = JSON.parse(
+ (
+ await Bun.file(
+ new URL(
+ "../../../test-fixtures/code-mode/cc-2.1.304-inbound-system.jsonl",
+ import.meta.url
+ )
+ ).text()
+ )
+ .trim()
+ .split("\n")[0]
+ ).body;
+ const payload = {
+ model: inbound.model,
+ messages: inbound.messages,
+ max_tokens: inbound.max_tokens,
+ stream: inbound.stream,
+ };
+ const app = new Hono();
+ app.post("/", (c) => handler.handle(c, payload));
+ try {
+ const response = await app.request("http://t2.invalid/", { method: "POST" });
+ expect(fetchSpy).toHaveBeenCalledTimes(1);
+ await source.waiting.promise;
+ await ticks();
+ await response.body!.cancel("client left");
+ if (withUsage) {
+ expect(events).toHaveLength(1);
+ expect(events[0]).toMatchObject({
+ success: false,
+ error_class: "cancelled",
+ error_code: "client_cancelled",
+ request_role: "advisor",
+ });
+ const captured = JSON.parse(usageFrame.split("data: ")[1]);
+ expect(events[0].input_tokens).toBe(captured.usage.prompt_tokens);
+ } else {
+ expect(events).toEqual([]);
+ expect(handler.getTokenTracker().getTotalCost()).toBe(0);
+ }
+ } finally {
+ await handler.shutdown();
+ }
+ }, 10_000);
+ }
+ });
+}
diff --cc packages/cli/src/handlers/shared/stream-parsers/gemini-sse.ts
index 768dfbaa,6a1dbd41..9e16109a
--- a/packages/cli/src/handlers/shared/stream-parsers/gemini-sse.ts
+++ b/packages/cli/src/handlers/shared/stream-parsers/gemini-sse.ts
@@@ -8,16 -8,10 +8,16 @@@
import type { Context } from "hono";
import type { BaseAPIFormat } from "../../../adapters/base-api-format.js";
+ import type { RawStreamTap } from "../../../hooks/raw.js";
import { log } from "../../../logger.js";
- import type { MiddlewareManager } from "../../../middleware/manager.js";
+import { redactForClient } from "../../../redact.js";
import { messageStartUsage } from "./message-start-usage.js";
import { sseDataPayload } from "./sse-line.js";
+import {
+ type ParserSource,
+ type UpstreamReaderSlot,
+ cancelEndsUpstreamWork,
+} from "./upstream-cancel.js";
export interface GeminiSseOptions {
modelName: string;
diff --cc packages/cli/src/handlers/shared/stream-parsers/openai-responses-sse.ts
index c2c6af15,7cf595d3..17b56276
--- a/packages/cli/src/handlers/shared/stream-parsers/openai-responses-sse.ts
+++ b/packages/cli/src/handlers/shared/stream-parsers/openai-responses-sse.ts
@@@ -12,83 -13,15 +12,73 @@@
import type { Context } from "hono";
import {
- type CachedReasoningItem,
- rememberReasoningForCall,
-} from "../../../adapters/reasoning-cache.js";
+ type CodeModeTurnHooks,
+ type NestedToolUse,
+ relayNestedInput,
+} from "../../../code-mode/types.js";
+ import type { RawStreamTap } from "../../../hooks/raw.js";
-import { getLogLevel, log } from "../../../logger.js";
import { wrapAnthropicError } from "../anthropic-error.js";
-import { messageStartUsage } from "./message-start-usage.js";
-import { formatRawSseLogPayload } from "./openai-sse.js";
-import { sseDataPayload } from "./sse-line.js";
+import type { UsageCacheDetail } from "../token-tracker.js";
+import { ClaudeSseSink } from "./responses/claude-sse-sink.js";
+import { type ResponsesRetryOptions, runResponsesTurn } from "./responses/responses-turn.js";
+import { type ParserSource, cancelEndsUpstreamWork } from "./upstream-cancel.js";
+
+export type { ResponsesRetryOptions } from "./responses/responses-turn.js";
+export type { CodeModeTurnHooks, ExecTurnStep } from "../../../code-mode/types.js";
+export { resolveStallPolicy, type StallPolicy } from "./responses/stall-guard.js";
+
+/**
+ * A code-mode script blocked again at step 5r: answer with its next batch as
- * tool_use blocks, with NO upstream call. Written by the same sink and the
- * same hooks as a driver batch (repair for buffered tools, one
- * `onToolCallObserved` per block, middleware `afterStreamComplete`,
- * `onTurnEnd`). `message_start` and `message_delta` carry the previous
- * request's input and 0 output; nothing was billed, so no usage callback fires.
++ * tool_use blocks, with NO upstream call. Written by the same sink as a driver
++ * batch (one `onToolCallObserved` per block, the raw `providerStreamEnd`
++ * hooks). Tool-argument repair is the hook response seam's job, above every
++ * parser, so a synthetic reply gets it exactly as a driver batch does.
++ * `message_start` and `message_delta` carry the previous request's input and 0
++ * output; nothing was billed, so no usage callback fires.
+ */
+export function createSyntheticToolUseReply(
+ blocks: ReadonlyArray<NestedToolUse>,
+ opts: {
+ modelName: string;
+ priorInputTokens?: number;
- shouldBufferTool?: (name: string) => boolean;
- onToolCall?: (name: string, argsJson: string) => string | null | undefined;
+ onToolCallObserved?: (name: string) => void;
- onTurnEnd?: () => void;
- // biome-ignore lint/suspicious/noExplicitAny: MiddlewareManager is untyped on every parser
- middlewareManager?: any;
++ raw?: RawStreamTap | null;
+ }
+): Response {
- const repair = (name: string, args: string): string => {
- if (opts.shouldBufferTool?.(name) !== true) return args;
- try {
- const repaired = opts.onToolCall?.(name, args);
- return typeof repaired === "string" ? repaired : args;
- } catch {
- return args;
- }
- };
+ const stream = new ReadableStream<Uint8Array>({
+ start: async (controller) => {
+ const sink = new ClaudeSseSink(controller, {
+ modelName: opts.modelName,
+ priorInputTokens: opts.priorInputTokens,
+ onToolCallObserved: opts.onToolCallObserved,
+ });
+ try {
+ sink.start();
+ for (const block of blocks) {
- sink.emitToolUse(block.id, block.name, relayNestedInput(block, repair));
++ sink.emitToolUse(
++ block.id,
++ block.name,
++ relayNestedInput(block, (_name, args) => args)
++ );
+ }
+ sink.endMessage("tool_use", { input_tokens: opts.priorInputTokens ?? 0, output_tokens: 0 });
- if (opts.middlewareManager) {
- await opts.middlewareManager.afterStreamComplete(opts.modelName, new Map());
- }
- opts.onTurnEnd?.();
++ if (opts.raw) await opts.raw.streamEnd();
+ } catch (err) {
+ // A throwing hook must not leave the downstream open.
+ sink.endWithError(`claudish: the synthetic reply failed: ${err}`);
+ } finally {
+ sink.close();
+ }
+ },
+ });
+ return new Response(stream, {
+ headers: {
+ "Content-Type": "text/event-stream",
+ "Cache-Control": "no-cache",
+ Connection: "keep-alive",
+ },
+ });
+}
export function createResponsesStreamHandler(
c: Context,
@@@ -130,84 -50,492 +120,60 @@@
*/
priorInputTokens?: number;
/**
- * Middleware chain, so the Responses path gets the same response-side hooks
- * the Chat Completions path has had. Previously absent, which left the Codex
- * models with no observation point at all.
- */
- // biome-ignore lint/suspicious/noExplicitAny: MiddlewareManager is untyped on every parser
- middlewareManager?: any;
- /**
- * Behavior-layer tool-call interception. Called once per completed tool call
- * with the fully accumulated argument JSON; return replacement JSON to repair
- * the call, or null/undefined to leave it untouched.
- *
- * Only consulted for tools that `shouldBufferTool` opted in — see below.
- */
- onToolCall?: (name: string, argsJson: string) => string | null | undefined;
- /**
- * Whether a tool's arguments must be withheld until the call completes.
- *
- * Repair is only possible for buffered calls: this parser streams
- * `input_json_delta` the instant each fragment arrives, so by the time a call
- * is complete its arguments are already on the wire to the client. Buffering
- * is therefore opt-in PER TOOL — a tool no rule cares about keeps streaming
- * incrementally, so the default path keeps its current latency profile.
+ * The raw-tier tap (`providerChunk` / `providerStreamEnd`), so the Responses
+ * path has the same raw hook points as the Chat Completions path. The
+ * Responses API has no `delta` object of its own, so the event stands in for
+ * both.
*/
- shouldBufferTool?: (name: string) => boolean;
+ raw?: RawStreamTap | null;
/**
- * Behavior-layer observation (Layer 4). Called with normalized text so rules
- * never have to understand this parser's event shape.
+ * Called once per `tool_use` block start, for the token tracker's tool
+ * count. Tool-argument interception is not this parser's job: it happens at
+ * the hook response seam, above every parser.
*/
- onAssistantText?: (text: string, kind?: "text" | "reasoning") => void;
onToolCallObserved?: (name: string) => void;
- onTurnEnd?: () => void;
+ /**
+ * The request's tool names as Claude Code sent them (decoded, not the
+ * encoded wire names). A function_call named `parallel` is treated as the
+ * parallel wrapper only when no declared tool has that name. Absent → the
+ * values of `toolNameMap`.
+ */
+ declaredToolNames?: string[];
+ /**
+ * Code mode for this turn (`openai-codex`): exec calls are run through these
+ * hooks (responses/responses-turn.ts). Absent ⇒ exec calls are ignored.
+ */
+ codeMode?: CodeModeTurnHooks;
}
): Response {
- const reader = response.body?.getReader();
- if (!reader) {
+ if (!response.body) {
+ // biome-ignore lint/suspicious/noExplicitAny: Hono's typed json response is not a plain Response
return c.json(wrapAnthropicError(500, "No response body"), 500) as any;
}
- const encoder = new TextEncoder();
- const decoder = new TextDecoder();
-
- let buffer = "";
- // Monotonic content-block index. Every block (thinking, text, tool_use) takes
- // the next index — Claude's SSE contract requires contiguous indices, and a
- // block index must never be reused once its block is closed.
- let curIdx = 0;
- let textIdx = -1;
- let reasoningIdx = -1;
- // OpenAI splits a reasoning summary into parts (summary_index 0, 1, 2, …),
- // each a bolded section. The paragraph break between parts is structural —
- // it is NOT in the text deltas — so tracking the index lets us re-insert it,
- // otherwise "**A**" + "**B**" render as one smashed "**A****B**".
- let lastSummaryIndex = -1;
- // Set when OpenAI reports the response was cut short (response.incomplete).
- // Must reach the client as a truthful stop_reason: when the model runs out of
- // output budget mid-tool-call, OpenAI still emits the partial arguments, and
- // claiming stop_reason "tool_use" tells the client to execute a tool whose
- // JSON is truncated.
- let incompleteReason: string | null = null;
- // Reasoning items seen since the last function call. OpenAI emits them just
- // before the call they informed; we hand them to the cache keyed by that call
- // so the next request can replay them (see reasoning-cache.ts).
- let pendingReasoning: CachedReasoningItem[] = [];
- let inputTokens = 0;
- let outputTokens = 0;
- let hasToolUse = false;
- let lastActivity = Date.now();
- let pingInterval: ReturnType<typeof setInterval> | null = null;
- let isClosed = false;
-
- type FnCall = {
- name: string;
- arguments: string;
- index: number;
- claudeId?: string;
- };
-
- // Track function calls being streamed. Keyed by BOTH call_id and item_id, so
- // the same FnCall object appears under two keys — never derive a count from
- // this map's size; use openToolBlocks / hasToolUse instead.
- const functionCalls: Map<string, FnCall> = new Map();
-
- // Tool blocks that have been started but not yet stopped, in emission order.
- const openToolBlocks = new Set<FnCall>();
-
- const stream = new ReadableStream({
- /*
- * The SSE event dispatch below has been far over the complexity limit since
- * this parser was written. The rule only started REPORTING a score once this
- * fix removed enough nesting for biome to compute one — before that it bailed
- * with "too complex to score", which downgrades to a warning. Splitting the
- * dispatch means threading ~20 closure variables through a new function: a
- * refactor in its own right, not a rider on a stream-truncation fix.
- */
- // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: pre-existing, see above
+ let sink: ClaudeSseSink | undefined;
+ const source: ParserSource<Uint8Array> = {
start: async (controller) => {
- const send = (event: string, data: any) => {
- if (!isClosed) {
- controller.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
- }
- };
-
- // cancel() (downstream disconnect) closes the controller without running any
- // of the normal completion paths, so those paths can still reach a close()
- // on an already-closed controller — `ERR_INVALID_STATE`. Harmless in itself,
- // but it surfaces as a bogus "[ResponsesSSE] Stream error" in the debug log
- // that reads like a translation failure. Every close goes through here.
- const safeClose = () => {
- try {
- controller.close();
- } catch {
- // Already closed by cancel(); nothing left to do.
- }
- };
-
- const closeReasoning = () => {
- if (reasoningIdx >= 0) {
- send("content_block_stop", { type: "content_block_stop", index: reasoningIdx });
- reasoningIdx = -1;
- }
- };
- const closeText = () => {
- if (textIdx >= 0) {
- send("content_block_stop", { type: "content_block_stop", index: textIdx });
- textIdx = -1;
- }
- };
- const closeTools = () => {
- for (const fnCall of openToolBlocks) {
- // A call that never reached output_item.done (truncated or failed
- // stream) has already streamed its fragments. What the client then
- // DOES with malformed JSON is decided by how the turn ends, not here:
- // only an `error` event reliably stops Claude Code executing the
- // fragment (see the catch block below).
- send("content_block_stop", { type: "content_block_stop", index: fnCall.index });
- }
- openToolBlocks.clear();
- };
-
- /**
- * The five-event tail both in-band error paths emit: a text block carrying
- * the message, then a normal `end_turn`. Shared so the two callers cannot
- * drift, and so `start` keeps a computable complexity score.
- */
- const endTurnWithText = (text: string) => {
- const idx = curIdx++;
- send("content_block_start", {
- type: "content_block_start",
- index: idx,
- content_block: { type: "text", text: "" },
- });
- send("content_block_delta", {
- type: "content_block_delta",
- index: idx,
- delta: { type: "text_delta", text },
- });
- send("content_block_stop", { type: "content_block_stop", index: idx });
- send("message_delta", {
- type: "message_delta",
- delta: { stop_reason: "end_turn", stop_sequence: null },
- usage: { input_tokens: inputTokens, output_tokens: outputTokens },
- });
- send("message_stop", { type: "message_stop" });
- };
-
- send("message_start", {
- type: "message_start",
- message: {
- id: `msg_${Date.now()}`,
- type: "message",
- role: "assistant",
- content: [],
- model: opts.modelName,
- stop_reason: null,
- stop_sequence: null,
- usage: messageStartUsage(opts.priorInputTokens),
- },
+ sink = new ClaudeSseSink(controller, {
+ modelName: opts.modelName,
+ priorInputTokens: opts.priorInputTokens,
+ onToolCallObserved: opts.onToolCallObserved,
+ });
+ sink.start();
+ // runResponsesTurn never rejects and closes the sink when it resolves.
+ await runResponsesTurn(sink, response, {
+ modelName: opts.modelName,
+ toolNameMap: opts.toolNameMap,
+ declaredToolNames: opts.declaredToolNames ?? [...(opts.toolNameMap?.values() ?? [])],
- middlewareManager: opts.middlewareManager,
- streamMetadata: new Map(),
- onToolCall: opts.onToolCall,
- shouldBufferTool: opts.shouldBufferTool,
- onAssistantText: opts.onAssistantText,
++ raw: opts.raw,
+ contextWindow: opts.contextWindow,
+ onApiError: opts.onApiError,
+ onTokenUpdate: opts.onTokenUpdate,
- onTurnEnd: opts.onTurnEnd,
+ retry: opts.retry,
+ onExtraBilledInput: opts.onExtraBilledInput,
+ onTurnSummary: opts.onTurnSummary,
+ codeMode: opts.codeMode,
});
- send("ping", { type: "ping" });
-
- pingInterval = setInterval(() => {
- if (!isClosed && Date.now() - lastActivity > 1000) {
- send("ping", { type: "ping" });
- }
- }, 1000);
-
- try {
- while (true) {
- const { done, value } = await reader.read();
- if (done) break;
- lastActivity = Date.now();
-
- buffer += decoder.decode(value, { stream: true });
- const lines = buffer.split("\n");
- buffer = lines.pop() || "";
-
- for (const line of lines) {
- const data = sseDataPayload(line);
- if (data === null) continue;
- if (data === "[DONE]") continue;
-
- // Raw capture, greppable into test fixtures — same contract as
- // [SSE:openai] / [SSE:anthropic] in the sibling parsers.
- if (getLogLevel() === "debug") {
- log(`[SSE:responses] ${formatRawSseLogPayload(data)}`);
- }
-
- try {
- let event = JSON.parse(data);
-
- // Raw-tier tap, before anything reads the event: what it returns
- // is the committed object, and every read below is of it. The
- // Responses API has no `delta` object of its own, so the event
- // stands in for both.
- if (opts.raw) event = opts.raw.chunk(event, (e: any) => e);
-
- if (getLogLevel() === "debug" && event.type) {
- log(`[ResponsesSSE] Event: ${event.type}`);
- }
-
- if (event.type === "response.output_text.delta") {
- closeReasoning();
- if (textIdx < 0) {
- textIdx = curIdx++;
- send("content_block_start", {
- type: "content_block_start",
- index: textIdx,
- content_block: { type: "text", text: "" },
- });
- }
- send("content_block_delta", {
- type: "content_block_delta",
- index: textIdx,
- delta: { type: "text_delta", text: event.delta || "" },
- });
- } else if (event.type === "response.output_item.added") {
- if (event.item?.type === "function_call") {
- const itemId = event.item.id;
- const openaiCallId = event.item.call_id || itemId;
- const callId = openaiCallId.startsWith("toolu_")
- ? openaiCallId
- : `toolu_${openaiCallId.replace(/^fc_/, "")}`;
- const rawFnName = event.item.name || "";
- const fnName = opts.toolNameMap?.get(rawFnName) || rawFnName;
-
- closeReasoning();
- closeText();
-
- const fnCallData: FnCall = {
- name: fnName,
- arguments: "",
- index: curIdx++,
- claudeId: callId,
- };
-
- functionCalls.set(openaiCallId, fnCallData);
- if (itemId && itemId !== openaiCallId) {
- functionCalls.set(itemId, fnCallData);
- }
- openToolBlocks.add(fnCallData);
- opts.onToolCallObserved?.(fnName);
-
- // Bind the reasoning that led to this call, keyed by the id the
- // client will echo back, so the next request can replay it.
- if (pendingReasoning.length > 0) {
- rememberReasoningForCall(callId, pendingReasoning);
- pendingReasoning = [];
- }
-
- send("content_block_start", {
- type: "content_block_start",
- index: fnCallData.index,
- content_block: { type: "tool_use", id: callId, name: fnName, input: {} },
- });
- hasToolUse = true;
- }
- } else if (
- event.type === "response.reasoning_summary_text.delta" ||
- // The RAW reasoning text (DashScope, open-weight models) rather
- // than a summary of it; a thinking block all the same.
- event.type === "response.reasoning_text.delta"
- ) {
- // Reasoning is the model's chain of thought, not its answer — it
- // belongs in a thinking block, or Claude Code renders it as the reply.
- const summaryIndex =
- typeof event.summary_index === "number"
- ? event.summary_index
- : typeof event.content_index === "number"
- ? event.content_index
- : 0;
- if (reasoningIdx < 0) {
- closeText();
- reasoningIdx = curIdx++;
- lastSummaryIndex = summaryIndex;
- send("content_block_start", {
- type: "content_block_start",
- index: reasoningIdx,
- content_block: { type: "thinking", thinking: "" },
- });
- } else if (summaryIndex !== lastSummaryIndex) {
- // New summary section — restore the paragraph break OpenAI
- // represents structurally rather than in the text stream.
- lastSummaryIndex = summaryIndex;
- send("content_block_delta", {
- type: "content_block_delta",
- index: reasoningIdx,
- delta: { type: "thinking_delta", thinking: "\n\n" },
- });
- }
- send("content_block_delta", {
- type: "content_block_delta",
- index: reasoningIdx,
- delta: { type: "thinking_delta", thinking: event.delta || "" },
- });
- } else if (event.type === "response.function_call_arguments.delta") {
- const callId = event.call_id || event.item_id;
- const fnCall = functionCalls.get(callId);
- if (fnCall) {
- fnCall.arguments += event.delta || "";
- send("content_block_delta", {
- type: "content_block_delta",
- index: fnCall.index,
- delta: { type: "input_json_delta", partial_json: event.delta || "" },
- });
- }
- } else if (event.type === "response.output_item.done") {
- if (event.item?.type === "reasoning" && event.item.encrypted_content) {
- // Keep the item verbatim (minus the id, which the Responses API
- // does not require on replay and which buildPayload strips).
- pendingReasoning.push({
- type: "reasoning",
- content: event.item.content ?? [],
- encrypted_content: event.item.encrypted_content,
- summary: event.item.summary ?? [],
- });
- }
- if (event.item?.type === "function_call") {
- const callId = event.item.call_id || event.item.id;
- const fnCall = functionCalls.get(callId) || functionCalls.get(event.item.id);
- if (fnCall && openToolBlocks.has(fnCall)) {
- send("content_block_stop", { type: "content_block_stop", index: fnCall.index });
- openToolBlocks.delete(fnCall);
- }
- }
- } else if (event.type === "response.incomplete") {
- // The reason lives at response.incomplete_details.reason — reading
- // event.reason always yielded "unknown".
- incompleteReason =
- event.response?.incomplete_details?.reason ?? event.reason ?? "unknown";
- log(`[ResponsesSSE] Response incomplete: ${incompleteReason}`);
- if (event.response?.usage) {
- inputTokens = event.response.usage.input_tokens || inputTokens;
- outputTokens = event.response.usage.output_tokens || outputTokens;
- }
- } else if (event.type === "response.completed" || event.type === "response.done") {
- if (event.response?.usage) {
- inputTokens = event.response.usage.input_tokens || 0;
- outputTokens = event.response.usage.output_tokens || 0;
- } else if (event.usage) {
- inputTokens = event.usage.input_tokens || 0;
- outputTokens = event.usage.output_tokens || 0;
- }
- } else if (event.type === "error" || event.type === "response.failed") {
- const err = event.error || event.response?.error || {};
- const errMsg = err.message || event.message || "Unknown API error";
- const errCode = err.code || event.code || "";
- log(`[ResponsesSSE] API error: ${errCode} - ${errMsg}`);
-
- // Signal the terminal error so the caller records this turn as a
- // failure (the error rides an HTTP 200 stream, invisible to status).
- opts.onApiError?.(errCode, errMsg);
-
- closeReasoning();
- closeText();
- closeTools();
-
- // Context-overflow gets an actionable message (with the real
- // per-backend cap when known) instead of the bare error code —
- // otherwise the user just sees a cryptic `context_length_exceeded`
- // and a stuck session (/compact re-sends the same oversized input).
- const isCtxOverflow =
- errCode === "context_length_exceeded" ||
- /context (length|window)|exceeds? the context|too long|maximum context/i.test(
- errMsg
- );
- let errorText = `\n\n[API Error: ${errCode} ${errMsg}]`;
- if (isCtxOverflow) {
- const cap =
- opts.contextWindow && opts.contextWindow > 0
- ? ` ~${Math.round(opts.contextWindow / 1000)}K tokens`
- : "";
- errorText =
- `\n\n[Context limit reached] This model's backend enforces a smaller context window${cap} than its API spec. ` +
- "Run /clear to start fresh (/compact will also fail — it re-sends the full conversation), " +
- `or route the model via \`oai@${opts.modelName}\` to use the full-size window.`;
- }
-
- endTurnWithText(errorText);
- isClosed = true;
- if (pingInterval) {
- clearInterval(pingInterval);
- pingInterval = null;
- }
- if (opts.onTokenUpdate) opts.onTokenUpdate(inputTokens, outputTokens);
- safeClose();
- return;
- }
- } catch (parseError) {
- log(`[ResponsesSSE] Parse error: ${parseError}`);
- }
- }
- }
-
- if (pingInterval) {
- clearInterval(pingInterval);
- pingInterval = null;
- }
-
- closeReasoning();
- closeText();
- closeTools();
-
- // A truncated turn must NOT be reported as a finished tool call. OpenAI
- // emits the partial function_call arguments it managed to produce, so
- // "tool_use" makes the client execute a tool with malformed JSON
- // (InputValidationError). Anthropic's contract for a cut-off turn is
- // stop_reason "max_tokens", which is the honest label here.
- //
- // KNOWN GAP: "max_tokens" does not actually stop Claude Code executing
- // the partial block. Verified against 2.1.217 (passflow session,
- // 2026-07-22, six days after v7.12.7 shipped this): the client ran the
- // truncated Write and reported InputValidationError anyway. The catch
- // block below uses an `error` event, which does stop it — but that is
- // only safe there because a dead socket is transient. max_output_tokens
- // is deterministic, so an error event would make the client retry a
- // request that truncates again. Capping the budget is the real fix and
- // the codex backend rejects max_output_tokens ("Unsupported parameter"),
- // so the label stays honest and the execution stays unprevented.
- const stopReason = incompleteReason
- ? incompleteReason === "content_filter"
- ? "refusal"
- : "max_tokens"
- : hasToolUse
- ? "tool_use"
- : "end_turn";
- if (incompleteReason) {
- log(
- `[ResponsesSSE] Truncated response (${incompleteReason}) → stop_reason=${stopReason}`
- );
- }
- send("message_delta", {
- type: "message_delta",
- delta: { stop_reason: stopReason, stop_sequence: null },
- usage: { input_tokens: inputTokens, output_tokens: outputTokens },
- });
- send("message_stop", { type: "message_stop" });
-
- isClosed = true;
- if (opts.onTokenUpdate) opts.onTokenUpdate(inputTokens, outputTokens);
- if (opts.raw) await opts.raw.streamEnd();
- safeClose();
- } catch (error) {
- if (pingInterval) {
- clearInterval(pingInterval);
- pingInterval = null;
- }
- log(`[ResponsesSSE] Stream error: ${error}`);
-
- if (!isClosed) {
- try {
- closeReasoning();
- closeText();
- // A tool block still open here had its argument JSON cut mid-object:
- // the socket died between `output_item.added` and `output_item.done`.
- // closeTools() still has to emit it, because its content_block_start
- // is already on the wire — so how the turn ENDS decides what the
- // client does with the fragment, and `end_turn` makes Claude Code run
- // the tool on truncated JSON:
- // InputValidationError: Write was called with input that could not
- // be parsed as JSON. You sent (first 200 of 9437 bytes): {"file_pa…
- // `max_tokens` does not rescue it either: Claude Code 2.1.217 ran a
- // max_tokens-terminated tool call anyway (passflow session,
- // 2026-07-22, six days after v7.12.7 shipped that mitigation). Only
- // an `error` event ends the message with no completed tool_use, and
- // it is the honest report — the turn did fail. devin-connect ends a
- // mid-stream fault the same way, for the same reason.
- const toolCallCutOff = openToolBlocks.size > 0;
- closeTools();
-
- if (toolCallCutOff) {
- log("[ResponsesSSE] tool arguments cut off mid-stream → error event");
- send("error", {
- type: "error",
- error: { type: "api_error", message: `Stream error: ${error}` },
- });
- } else {
- endTurnWithText(`\n\n[Stream error: ${error}]`);
- }
- } catch {}
-
- isClosed = true;
- if (opts.onTokenUpdate) opts.onTokenUpdate(inputTokens, outputTokens);
- safeClose();
- }
- }
},
// Downstream went away (client disconnect, abort, or timeout). The
// controller is already closed here, but none of the normal close paths
diff --cc packages/cli/src/handlers/shared/stream-parsers/openai-sse.ts
index 4a33a703,88c5cde5..d6bd4c6e
--- a/packages/cli/src/handlers/shared/stream-parsers/openai-sse.ts
+++ b/packages/cli/src/handlers/shared/stream-parsers/openai-sse.ts
@@@ -8,8 -8,8 +8,9 @@@
*/
import type { Context } from "hono";
+ import type { RawStreamTap } from "../../../hooks/raw.js";
import { log } from "../../../logger.js";
+import { redactForClient } from "../../../redact.js";
import {
type ToolSchema,
extractToolCallsFromText,
@@@ -257,963 -260,815 +262,907 @@@ export function createStreamingResponse
toolNameMap?: Map<string, string>, // Truncated → original tool name mapping
priorInputTokens?: number, // Last request's context size — seeds message_start.usage
/**
- * Behavior layer (Layer 4) tool-call interception. Grouped into one object
- * rather than two more positional parameters — this signature already carries
- * nine.
- *
- * Unlike the Responses parser, this path already buffers tool arguments
- * whenever the request carries tools (see `buffered` below), so hooking repair
- * in costs nothing extra: the complete argument object is assembled here
- * regardless. `shouldBufferTool` only matters for the rare case of a rule
- * wanting a tool the schema-validation path would not have buffered.
+ * Observation callbacks, grouped into one object rather than another
+ * positional parameter — this signature already carries nine.
+ * `onToolCallObserved` feeds the token tracker's tool count. Tool-argument
+ * interception is not this parser's job: it happens at the hook response
+ * seam, above every parser.
*/
- behavior?: {
- shouldBufferTool?: (name: string) => boolean;
- onToolCall?: (name: string, argsJson: string) => string | null | undefined;
- /**
- * Layer 4 observation. Normalized text, so rules never parse this parser's
- * event shape.
- */
- onAssistantText?: (text: string, kind?: "text" | "reasoning") => void;
+ observers?: {
onToolCallObserved?: (name: string) => void;
- onTurnEnd?: () => void;
}
): Response {
- /**
- * Offer a COMPLETE argument object to the behavior layer.
- *
- * Only ever called where the full object is in hand. The incremental
- * `partial_json` fragment path must never route through here — repairing a
- * fragment would emit malformed JSON.
- */
- const repairArgs = (toolName: string, argsJson: string): string => {
- if (!behavior?.onToolCall) return argsJson;
- try {
- const repaired = behavior.onToolCall(toolName, argsJson);
- if (typeof repaired === "string" && repaired !== argsJson) {
- log(`[Streaming] tool call repaired by behavior layer: ${toolName}`);
- return repaired;
- }
- } catch (err) {
- // A failing rule must never corrupt the stream.
- log(`[Streaming] behavior onToolCall threw for ${toolName}: ${err}`);
- }
- return argsJson;
- };
log(`[Streaming] ===== HANDLER STARTED for ${target} =====`);
let isClosed = false;
+ // Set by `cancel()` only: the client went away. `isClosed` alone cannot say
+ // that, because teardown sets it on every normal end too.
+ let cancelled = false;
let ping: NodeJS.Timeout | null = null;
const encoder = new TextEncoder();
const decoder = new TextDecoder();
- const streamMetadata = new Map<string, any>();
+ const upstream: UpstreamReaderSlot = {};
return c.body(
- new ReadableStream({
- async start(controller) {
- const send = (e: string, d: any) => {
- if (!isClosed) {
- // Observe every tool call HERE, at the single frame writer, rather than at
- // the `content_block_start` sites. (Those now all run through
- // `block-writer.ts`, which is itself a single site — but this hook stays
- // here, one layer lower, because it must also see anything a future path
- // emits without going through the writer.)
- //
- // This parser declared `onToolCallObserved` and never called it — so on the
- // busiest wire in claudish (GLM, Kimi, Grok, DeepSeek, Qwen, OpenRouter,
- // LiteLLM) the session summary would have reported zero tools. Hooking the writer instead
- // of the emission sites makes that class of omission impossible: a new
- // tool_use path cannot forget to opt in, and because exactly one
- // `content_block_start` is emitted per tool call, it cannot double count
- // either. The `input_json_delta` frames deliberately do not match.
- if (e === "content_block_start" && d?.content_block?.type === "tool_use") {
- try {
- observers?.onToolCallObserved?.(String(d.content_block.name ?? ""));
- } catch (err) {
- log(`[Streaming] onToolCallObserved threw: ${err}`);
+ new ReadableStream(
+ cancelEndsUpstreamWork<Uint8Array>(upstream, {
+ async start(controller) {
+ const send = (e: string, d: any) => {
+ if (!isClosed) {
+ // Observe every tool call HERE, at the single frame writer, rather than at
+ // the `content_block_start` sites. (Those now all run through
+ // `block-writer.ts`, which is itself a single site — but this hook stays
+ // here, one layer lower, because it must also see anything a future path
+ // emits without going through the writer.)
+ //
+ // This parser declared `onToolCallObserved` and never called it — so on the
+ // busiest wire in claudish (GLM, Kimi, Grok, DeepSeek, Qwen, OpenRouter,
- // LiteLLM) the behaviour layer's tool-name list was always empty and the
- // session summary would have reported zero tools. Hooking the writer instead
++ // LiteLLM) the session summary would have reported zero tools. Hooking the writer instead
+ // of the emission sites makes that class of omission impossible: a new
+ // tool_use path cannot forget to opt in, and because exactly one
+ // `content_block_start` is emitted per tool call, it cannot double count
+ // either. The `input_json_delta` frames deliberately do not match.
+ if (e === "content_block_start" && d?.content_block?.type === "tool_use") {
+ try {
- behavior?.onToolCallObserved?.(String(d.content_block.name ?? ""));
++ observers?.onToolCallObserved?.(String(d.content_block.name ?? ""));
+ } catch (err) {
+ log(`[Streaming] onToolCallObserved threw: ${err}`);
+ }
}
+ controller.enqueue(encoder.encode(`event: ${e}\ndata: ${JSON.stringify(d)}\n\n`));
}
- controller.enqueue(encoder.encode(`event: ${e}\ndata: ${JSON.stringify(d)}\n\n`));
- }
- };
-
- const msgId = `msg_${Date.now()}_${Math.random().toString(36).slice(2)}`;
- const state = createStreamingState();
- // Every content block for this turn is opened, appended to and closed
- // through here. It owns the block-index counter, so nothing else
- // allocates an index.
- const writer = createBlockWriter(send);
- const thinkSplitter = createThinkTagSplitter();
-
- /**
- * Route one splitter result to its blocks.
- *
- * Shared by the streaming path and by `finalize()`'s flush, so a fragment
- * released at the end of the turn takes exactly the same hold-back
- * decision as one released mid-stream — rather than bypassing it and
- * emitting a lone fragment of text that the hold-back is withholding the
- * rest of.
- */
- const emitSplitContent = ({ thinking, text }: ThinkSplit): void => {
- if (thinking) {
- writer.append(writer.openThinking(), thinking);
- }
- if (!text) return;
-
- // Accumulate text for potential tool call extraction
- state.accumulatedText += text;
-
- // Check if text contains STRUCTURED tool call patterns that we should hold back
- // Only hold back for patterns we can actually parse (XML, JSON), not natural language
- // Natural language patterns are extracted at finalization, not held back
- const hasStructuredToolPattern =
- // Qwen XML-style: <function=ToolName>. Same shape the
- // extractor accepts, so text held back here is always text
- // the extractor can act on. A looser test here withheld
- // text that nothing later emitted.
- hasExtractableFunctionTag(state.accumulatedText) ||
- // JSON tool call in text: {"name": "Task", "arguments":
- /\{\s*"(?:name|tool)"\s*:\s*"(?:Task|Read|Write|Edit|Bash|Grep|Glob)"/i.test(
- state.accumulatedText
- ) ||
- // XML tool_call tags: <tool_call>
- /<tool_call>/.test(state.accumulatedText);
-
- // Only hold back if we have a structured pattern AND haven't accumulated too much
- // (if we've accumulated > 1000 chars without a complete pattern, release the text)
- const shouldHoldBack = hasStructuredToolPattern && state.accumulatedText.length < 1000;
-
- if (shouldHoldBack) {
- log(
- `[Streaming] Text held back (structured tool pattern): ${state.accumulatedText.length} chars accumulated`
- );
- return;
- }
+ };
+
+ const msgId = `msg_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+ const state = createStreamingState();
+ // Every content block for this turn is opened, appended to and closed
+ // through here. It owns the block-index counter, so nothing else
+ // allocates an index.
+ const writer = createBlockWriter(send);
+ const thinkSplitter = createThinkTagSplitter();
+
+ /**
+ * Route one splitter result to its blocks.
+ *
+ * Shared by the streaming path and by `finalize()`'s flush, so a fragment
+ * released at the end of the turn takes exactly the same hold-back
+ * decision as one released mid-stream — rather than bypassing it and
+ * emitting a lone fragment of text that the hold-back is withholding the
+ * rest of.
+ */
+ const emitSplitContent = ({ thinking, text }: ThinkSplit): void => {
+ if (thinking) {
- behavior?.onAssistantText?.(thinking, "reasoning");
+ writer.append(writer.openThinking(), thinking);
+ }
+ if (!text) return;
+
+ // Accumulate text for potential tool call extraction
+ state.accumulatedText += text;
+
+ // Check if text contains STRUCTURED tool call patterns that we should hold back
+ // Only hold back for patterns we can actually parse (XML, JSON), not natural language
+ // Natural language patterns are extracted at finalization, not held back
+ const hasStructuredToolPattern =
+ // Qwen XML-style: <function=ToolName>. Same shape the
+ // extractor accepts, so text held back here is always text
+ // the extractor can act on. A looser test here withheld
+ // text that nothing later emitted.
+ hasExtractableFunctionTag(state.accumulatedText) ||
+ // JSON tool call in text: {"name": "Task", "arguments":
+ /\{\s*"(?:name|tool)"\s*:\s*"(?:Task|Read|Write|Edit|Bash|Grep|Glob)"/i.test(
+ state.accumulatedText
+ ) ||
+ // XML tool_call tags: <tool_call>
+ /<tool_call>/.test(state.accumulatedText);
- writer.append(writer.openText(), text);
- };
-
- send("message_start", {
- type: "message_start",
- message: {
- id: msgId,
- type: "message",
- role: "assistant",
- content: [],
- model: target,
- stop_reason: null,
- stop_sequence: null,
- usage: messageStartUsage(priorInputTokens),
- },
- });
- send("ping", { type: "ping" });
-
- ping = setInterval(() => {
- if (!isClosed && Date.now() - state.lastActivity > 1000) {
- send("ping", { type: "ping" });
- }
- }, 1000);
-
- // Teardown is separated from finalize() on purpose. finalize() guards
- // re-entry on state.finalized, so once it has started, a throw part-way
- // through used to mean the stream was never closed and the ping interval
- // was never cleared: the outer catch re-called finalize(), which returned
- // immediately at the guard. The client then sat on an open HTTP 200
- // forever. Teardown therefore runs from a `finally`, and stays safe to
- // call twice.
- const teardown = () => {
- if (!isClosed) {
- try {
- controller.enqueue(encoder.encode("data: [DONE]\n\n\n"));
- } catch {}
- try {
- controller.close();
- } catch {}
- isClosed = true;
- }
- if (ping) {
- clearInterval(ping);
- ping = null;
- }
- };
-
- const finalize = async (reason: string, err?: string) => {
- // A second call still has to tear down: the first may have thrown
- // before reaching its own `finally`.
- if (state.finalized) {
- teardown();
- return;
- }
- state.finalized = true;
+ // Only hold back if we have a structured pattern AND haven't accumulated too much
+ // (if we've accumulated > 1000 chars without a complete pattern, release the text)
+ const shouldHoldBack = hasStructuredToolPattern && state.accumulatedText.length < 1000;
- try {
- // Release anything the think-tag splitter is still holding — at most
- // seven characters of a tag that never completed. Runs FIRST, before
- // text-based tool-call recovery reads `accumulatedText`, so a held
- // fragment is part of the text recovery scans rather than arriving
- // after it.
- emitSplitContent(thinkSplitter.flush());
-
- // Argument fragments whose `function.name` never arrived. A call with
- // no name is not a call — there is nothing to dispatch and no schema to
- // validate against — so they are discarded. Named in the log because
- // silently dropping them is precisely the defect this buffer fixes, and
- // a buffer that survives to here means the provider is doing something
- // the accumulator did not anticipate. "error" puts it in the always-on
- // structural log.
- for (const [idx, pending] of state.pendingToolArgs) {
+ if (shouldHoldBack) {
log(
- `[Streaming] Tool argument error: discarding ${pending.length} buffered chars for tool_calls index ${idx} — function.name never arrived`
+ `[Streaming] Text held back (structured tool pattern): ${state.accumulatedText.length} chars accumulated`
);
+ return;
}
- state.pendingToolArgs.clear();
- // Debug: Log accumulated text for analysis
- if (state.accumulatedText.length > 0) {
- const preview = state.accumulatedText.slice(0, 500).replace(/\n/g, "\\n");
- log(
- `[Streaming] Accumulated text (${state.accumulatedText.length} chars): ${preview}...`
- );
+ writer.append(writer.openText(), text);
+ };
+
+ send("message_start", {
+ type: "message_start",
+ message: {
+ id: msgId,
+ type: "message",
+ role: "assistant",
+ content: [],
+ model: target,
+ stop_reason: null,
+ stop_sequence: null,
+ usage: messageStartUsage(priorInputTokens),
+ },
+ });
+ send("ping", { type: "ping" });
+
+ ping = setInterval(() => {
+ if (!isClosed && Date.now() - state.lastActivity > 1000) {
+ send("ping", { type: "ping" });
}
-
- // Check for text-based tool calls before finalizing
- // Some models (like Qwen) output tool calls as text instead of structured tool_calls
- //
- // Only when the model produced NO structured call. Recovery exists for
- // models that cannot emit `tool_calls` at all; against a model that
- // just did, it can only ADD calls, never repair one. Ungated, a turn
- // holding one real call plus prose mentioning a function tag dispatched
- // two tool_use blocks, and both were recorded.
- const textToolCalls =
- state.tools.size > 0
- ? []
- : extractToolCallsFromText(
- state.accumulatedText,
- toolSchemas?.map((t: any) => t?.name).filter((n: any): n is string => !!n),
- // The `<function=NAME><parameter=P>` envelope carries no
- // types, so every value arrives as a string. The schemas are
- // what turn `"5"` back into 5 and `"true"` into true.
- toolSchemas as ToolSchema[] | undefined,
- // Recovery reads the name the MODEL wrote, which is the
- // encoded one. The allowlist is built from the client's
- // originals, so an undecoded name is dropped in silence.
- toolNameMap ? (name: string) => toolNameMap.get(name) ?? name : undefined
- );
- if (state.tools.size > 0 && state.accumulatedText.length > 0) {
- log(
- `[Streaming] Skipping text-based tool extraction: ${state.tools.size} structured tool call(s) already present`
- );
+ }, 1000);
+
+ // Teardown is separated from finalize() on purpose. finalize() guards
+ // re-entry on state.finalized, so once it has started, a throw part-way
+ // through used to mean the stream was never closed and the ping interval
+ // was never cleared: the outer catch re-called finalize(), which returned
+ // immediately at the guard. The client then sat on an open HTTP 200
+ // forever. Teardown therefore runs from a `finally`, and stays safe to
+ // call twice.
+ const teardown = () => {
+ if (!isClosed) {
+ try {
+ controller.enqueue(encoder.encode("data: [DONE]\n\n\n"));
+ } catch {}
+ try {
+ controller.close();
+ } catch {}
+ isClosed = true;
}
- log(`[Streaming] Text-based tool calls found: ${textToolCalls.length}`);
-
- // ── How this turn ENDED ────────────────────────────────────────────
- //
- // Classified HERE — after recovery has run but BEFORE anything it
- // found is emitted — because recovery adds both content and tools, and
- // a classification taken before it runs would read a pre-recovery
- // state. Local models, the population text recovery exists for, are
- // exactly the ones most likely to end with no finish_reason.
- //
- // `finish_reason` is the ONLY completion signal. Neither the `[DONE]`
- // sentinel nor a final usage object counts: both are transport
- // punctuation that a proxy, a load balancer or a truncated body can
- // produce without the model ever having finished.
- const producedContent =
- state.accumulatedText.length > 0 ||
- writer.anyBlockEmitted ||
- state.tools.size > 0 ||
- textToolCalls.length > 0;
- const toolInFlight =
- // Already on the wire, including text-recovered calls from earlier
- // turns of this same finalize — `state.tools` does not cover those.
- writer.emittedToolRefs.length > 0 ||
- // `&& !t.closed` is load-bearing: `buffered && !started` is TRUE for
- // a tool that already failed validation and was closed.
- Array.from(state.tools.values()).some(
- (t) => !t.closed && (t.started || t.buffered)
- ) ||
- textToolCalls.length > 0;
-
- /**
- * `success` — the provider said how it finished, or produced nothing.
- * `silent-truncation` — no finish_reason, content, but no tool: the
- * partial prose is harmless and VISIBLE, and `max_tokens` is
- * Anthropic's own "the turn was cut off" label. An `error` here would
- * discard text the user can read.
- * `failure` — the turn cannot be presented as complete. Ends with an
- * SSE `error` event, which Claude Code honours by discarding a
- * partial `tool_use` and retrying (verified against a real client,
- * reports/truncated-toolcall-live-verification.md).
- */
- const ending: "success" | "silent-truncation" | "failure" =
- reason === "error"
- ? "failure"
- : state.finishReason !== null || !producedContent
- ? "success"
- : toolInFlight
- ? "failure"
- : "silent-truncation";
-
- if (ending !== "success") {
- log(
- `[Streaming] Stream ending error: reason=${reason} finish_reason=${state.finishReason ?? "null"} content=${producedContent} tool_in_flight=${toolInFlight} → ${ending}`
- );
+ if (ping) {
+ clearInterval(ping);
+ ping = null;
}
+ };
- // On a failure ending claudish emits NO NEW tool block and NO completed
- // tool call: the buffered flush below is skipped and recovered calls are
- // suppressed. It cannot recall a non-buffered tool block already on the
- // wire — `content_block_start` went out before a single argument byte
- // existed — but that partial is exactly the case the client-side
- // measurement covers.
- const emitToolCalls = ending !== "failure";
-
- if (textToolCalls.length > 0 && !emitToolCalls) {
- log(
- `[Streaming] Suppressing ${textToolCalls.length} text-recovered tool call(s): the turn ended in failure`
- );
- } else if (textToolCalls.length > 0) {
- log(
- `[Streaming] Found ${textToolCalls.length} text-based tool call(s), converting to structured format`
- );
-
- // Send each extracted tool call as a proper tool_use block.
- // `openTool` closes whatever is open first, which is where the
- // hand-written "close any open text block" used to live.
- for (const tc of textToolCalls) {
- const toolIdx = writer.reserve();
- const toolId = `tool_${Date.now()}_${toolIdx}`;
- const ref = writer.openTool({ id: toolId, name: tc.name, index: toolIdx });
- writer.append(ref, JSON.stringify(tc.arguments));
- writer.close(ref);
- }
+ /** Report the usage the provider sent. Only called when `state.usage` is set. */
+ const reportProviderUsage = () => {
+ if (!onTokenUpdate || !state.usage) return;
+ log(
+ `[Streaming] Final usage: prompt=${state.usage.prompt_tokens || 0}, completion=${state.usage.completion_tokens || 0}`
+ );
+ // FIRST ARGUMENT STAYS `prompt_tokens`: the tracker's input number
+ // is the context-occupancy figure the status line renders and the
+ // billing baseline the delta strategy compares against. The split
+ // goes in the third argument, where only the cost arithmetic sees
+ // it.
+ const costSplit = splitPromptTokens(state.usage);
+ onTokenUpdate(state.usage.prompt_tokens || 0, state.usage.completion_tokens || 0, {
+ cacheReadTokens: costSplit.cacheReadTokens,
+ cacheCreationTokens: costSplit.cacheCreationTokens,
+ });
+ };
+
+ const finalize = async (reason: string, err?: string) => {
+ // A second call still has to tear down: the first may have thrown
+ // before reaching its own `finally`.
+ if (state.finalized) {
+ teardown();
+ return;
}
-
- // Whatever is still open — thinking, text, or a tool — closes here.
- // This replaces the hand-written reasoning-then-text pair, which could
- // only ever close the two kinds it named.
- writer.closeCurrent();
-
- // Handle buffered-but-unsent structured tool calls.
- // Some models (e.g., Gemini via LiteLLM) send tool calls with finish_reason="stop"
- // instead of "tool_calls", so the normal validation path (line ~695) is never reached.
- // We must send these buffered tools here so Claude Code can execute them.
- //
- // SKIPPED ENTIRELY on a failure ending. Before this gate a failed turn
- // shipped a COMPLETE, parseable tool call and then an `error` event, so
- // the protection rested wholly on the client discarding it. Now only an
- // incomplete partial can reach the client on a failure ending, which is
- // precisely the case the client-side measurement covers.
- for (const t of emitToolCalls ? Array.from(state.tools.values()) : []) {
- if (!t.closed && t.buffered && !t.started) {
- if (toolSchemas && toolSchemas.length > 0) {
- const validation = validateToolArguments(
- t.name,
- t.arguments,
- toolSchemas,
- state.accumulatedText
- );
-
- if (validation.valid || (validation.repaired && validation.repairedArgs)) {
- const argsJson = JSON.stringify(
- validation.repaired ? validation.repairedArgs : validation.parsedArgs
- );
- log(
- `[Streaming] Sending buffered tool call (finish_reason!=tool_calls): ${t.name} with args: ${argsJson}`
- );
- t.ref = writer.openTool({ id: t.id, name: t.name, index: t.blockIndex });
- writer.append(t.ref, argsJson);
- writer.close(t.ref);
- t.started = true;
- t.closed = true;
- } else {
- log(
- `[Streaming] Buffered tool call ${t.name} failed validation, skipping: ${validation.missingParams.join(", ")}`
- );
- t.closed = true;
- }
- } else {
- // No schemas to validate against — send as-is
- const argsJson = t.arguments || "{}";
- log(
- `[Streaming] Sending buffered tool call (no validation): ${t.name} with args: ${argsJson}`
- );
- t.ref = writer.openTool({ id: t.id, name: t.name, index: t.blockIndex });
- writer.append(t.ref, argsJson);
- writer.close(t.ref);
- t.started = true;
- t.closed = true;
- }
+ state.finalized = true;
+
+ // The client cancelled: the upstream reader was cancelled under the
+ // loop, so its read resolved `done` (or threw) without the provider
+ // having ended anything. Not a truncation and not a failure, and the
+ // user abandoned the turn, so no ending classification, no estimate,
+ // no turn-end hook. Usage is recorded only when the provider sent it.
+ if (cancelled) {
+ try {
+ log(
+ `[Streaming] Client cancelled the stream for ${target} (loop ended: ${reason}); usage ${state.usage ? "reported" : "not received, not recorded"}`
+ );
+ reportProviderUsage();
+ } finally {
+ teardown();
}
+ return;
}
- // Close any remaining started-but-unclosed tool calls. Under the
- // one-open-block invariant at most one of these is still open; the
- // rest were closed when the block that superseded them opened, and
- // `writer.close` is a no-op for those.
- for (const t of Array.from(state.tools.values())) {
- if (t.started && !t.closed) {
- if (t.ref) writer.close(t.ref);
- t.closed = true;
+ try {
+ // Release anything the think-tag splitter is still holding — at most
+ // seven characters of a tag that never completed. Runs FIRST, before
+ // text-based tool-call recovery reads `accumulatedText`, so a held
+ // fragment is part of the text recovery scans rather than arriving
+ // after it.
+ emitSplitContent(thinkSplitter.flush());
+
+ // Argument fragments whose `function.name` never arrived. A call with
+ // no name is not a call — there is nothing to dispatch and no schema to
+ // validate against — so they are discarded. Named in the log because
+ // silently dropping them is precisely the defect this buffer fixes, and
+ // a buffer that survives to here means the provider is doing something
+ // the accumulator did not anticipate. "error" puts it in the always-on
+ // structural log.
+ for (const [idx, pending] of state.pendingToolArgs) {
+ log(
+ `[Streaming] Tool argument error: discarding ${pending.length} buffered chars for tool_calls index ${idx} — function.name never arrived`
+ );
}
- }
+ state.pendingToolArgs.clear();
- if (raw) await raw.streamEnd();
-
- if (ending === "failure") {
- // An SSE `error` event is the ONE ending Claude Code honours by
- // discarding a partial `tool_use` and retrying the turn. `end_turn`
- // means "the turn finished, run the tool" and made the client execute
- // truncated JSON; `max_tokens` was assumed to rescue it and measurably
- // does not (adapters.md, and the 2026-09-10 live verification).
- const message =
- err ??
- "Upstream stream ended with no finish_reason while a tool call was in flight. " +
- "The tool call is incomplete and was not dispatched.";
- send("error", { type: "error", error: { type: "api_error", message } });
- } else {
- // Set stop_reason based on whether we sent ANY tool calls (text-based or structured)
- const hasStructuredTools = Array.from(state.tools.values()).some((t) => t.started);
- // A turn the PROVIDER cut off must not be reported as a turn the model
- // chose to end. Anthropic's contract for a cut-off turn is "max_tokens";
- // reporting "end_turn" presents a truncated (or, when reasoning consumed
- // the whole budget, an EMPTY) answer as the model's complete final word.
- // Mirrors openai-responses-sse.ts, which already does this.
- // `content_filter` is the same class: the provider refused, which is
- // Anthropic's "refusal", not a turn the model chose to end.
- // openai-responses-sse.ts already maps both this way.
- // `length` still OUTRANKS `tool_use` — a truncated turn is reported as
- // truncated even when it carries a tool call. A silent truncation (no
- // finish_reason, content produced, no tool in flight) takes the same
- // label: it IS a cut-off turn, and `max_tokens` is Anthropic's word
- // for one. Neither can collide with the other: `finishReason` is
- // non-null in the first case and null in the second.
- const truncated = state.finishReason === "length" || ending === "silent-truncation";
- const refused = state.finishReason === "content_filter";
- const stopReason = refused
- ? "refusal"
- : truncated
- ? "max_tokens"
- : textToolCalls.length > 0 || hasStructuredTools
- ? "tool_use"
- : "end_turn";
- if (truncated || refused) {
+ // Debug: Log accumulated text for analysis
+ if (state.accumulatedText.length > 0) {
+ const preview = state.accumulatedText.slice(0, 500).replace(/\n/g, "\\n");
log(
- `[Streaming] Upstream finish_reason=${state.finishReason} → stop_reason=${stopReason} (${state.accumulatedText.length} chars produced)`
+ `[Streaming] Accumulated text (${state.accumulatedText.length} chars): ${preview}...`
);
}
- // A turn that ended NORMALLY must carry at least one content block.
- // `stop_reason: "end_turn"` with an empty `content` array is not a
- // shape Anthropic's API produces, and a client that indexes the last
- // block, or renders the turn, has nothing to work with — the turn
- // reads as a success that delivered nothing, with no diagnostic.
- //
- // The test is `stop_reason === "end_turn"` rather than "the ending was
- // a success", because that single value already excludes every case
- // where emptiness is MEANINGFUL and must be preserved:
- // • "max_tokens" — reasoning consumed the whole budget and the turn
- // was cut off. `gemini-3.1-pro-or-maxtokens-empty.sse` is a real
- // capture of exactly this; it must not be papered over.
- // • "max_tokens" from a silent truncation (item 4) — same reasoning.
- // • "refusal" — the provider refused. Emptiness IS the answer.
- // • "tool_use" — a tool block was emitted, so it is not contentless.
+ // Check for text-based tool calls before finalizing
+ // Some models (like Qwen) output tool calls as text instead of structured tool_calls
//
- // An EMPTY text block, not placeholder prose and not an error. Prose
- // would enter the conversation history as the assistant's words and be
- // replayed forever; an `error` would trigger the client's retry loop on
- // a deterministic outcome, which is adapters.md's stated reason for
- // keeping `max_tokens` over an error on the sibling case.
- if (stopReason === "end_turn" && !writer.anyBlockEmitted) {
+ // Only when the model produced NO structured call. Recovery exists for
+ // models that cannot emit `tool_calls` at all; against a model that
+ // just did, it can only ADD calls, never repair one. Ungated, a turn
+ // holding one real call plus prose mentioning a function tag dispatched
+ // two tool_use blocks, and both were recorded.
+ const textToolCalls =
+ state.tools.size > 0
+ ? []
+ : extractToolCallsFromText(
+ state.accumulatedText,
+ toolSchemas?.map((t: any) => t?.name).filter((n: any): n is string => !!n),
+ // The `<function=NAME><parameter=P>` envelope carries no
+ // types, so every value arrives as a string. The schemas are
+ // what turn `"5"` back into 5 and `"true"` into true.
+ toolSchemas as ToolSchema[] | undefined,
+ // Recovery reads the name the MODEL wrote, which is the
+ // encoded one. The allowlist is built from the client's
+ // originals, so an undecoded name is dropped in silence.
+ toolNameMap ? (name: string) => toolNameMap.get(name) ?? name : undefined
+ );
+ if (state.tools.size > 0 && state.accumulatedText.length > 0) {
log(
- `[Streaming] Contentless turn error: end_turn with no content block emitted (finish_reason=${state.finishReason ?? "null"}) — emitting an empty text block`
+ `[Streaming] Skipping text-based tool extraction: ${state.tools.size} structured tool call(s) already present`
);
- writer.close(writer.openText());
}
+ log(`[Streaming] Text-based tool calls found: ${textToolCalls.length}`);
- // The three input counters are derived ONCE and used for both the
- // wire and the cost update below, so the two cannot disagree.
- const split = splitPromptTokens(state.usage);
- // One degenerate turn is sent UNSPLIT, and this is not a special
- // case so much as the merge rule read honestly.
+ // ── How this turn ENDED ────────────────────────────────────────────
//
- // Claude Code only lets a delta value override its running total
- // when that value is GREATER THAN ZERO (2.1.273:
- // `n.input_tokens !== null && n.input_tokens > 0 ? n.input_tokens : e.input_tokens`).
- // So on a turn whose input is entirely cache — possible only when
- // the request repeats one already cached, i.e. a retry — an
- // `input_tokens: 0` is DISCARDED and the message_start seed (the
- // PREVIOUS turn's full context) survives beside a full-size
- // `cache_read_input_tokens`. The client would then sum the two and
- // believe the conversation is roughly twice its real size.
+ // Classified HERE — after recovery has run but BEFORE anything it
+ // found is emitted — because recovery adds both content and tools, and
+ // a classification taken before it runs would read a pre-recovery
+ // state. Local models, the population text recovery exists for, are
+ // exactly the ones most likely to end with no finish_reason.
//
- // Reporting that turn as ordinary input keeps the client's sum
- // exactly equal to `prompt_tokens`, which is the invariant that
- // matters. It costs nothing on the money side: the cost split is
- // taken from `splitPromptTokens` independently, below.
- const fullyCached = split.promptTokens > 0 && split.inputTokens === 0;
- const wireInput = fullyCached ? split.promptTokens : split.inputTokens;
- const wireCacheRead = fullyCached ? 0 : split.cacheReadTokens;
- const wireCacheCreation = fullyCached ? 0 : split.cacheCreationTokens;
- send("message_delta", {
- type: "message_delta",
- delta: { stop_reason: stopReason, stop_sequence: null },
- // input_tokens must ride the delta too: Claude Code takes the
- // context size from the last assistant message, and message_start
- // could only carry an estimate. Omitting it left the client
- // believing every conversation was 100 tokens, which silently
- // disabled auto-compaction on every openai-sse provider.
- //
- // All THREE keys ship TOGETHER, unconditionally, and that is not
- // stylistic. Claude Code reconstructs the conversation size by
- // summing them (verified in the 2.1.273 binary:
- // `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`,
- // read by both the context meter and the auto-compaction
- // threshold), so a reduced `input_tokens` sent WITHOUT its two
- // siblings understates the context by exactly the cached portion
- // — on the measured xAI turn, 20352 of 20379 tokens. That is the
- // one shape that reproduces the failure the paragraph above
- // records. `splitPromptTokens` guarantees the three sum back to
- // `prompt_tokens`.
- //
- // `input_tokens` is emitted even when it is 0 (a fully-cached
- // turn), because omitting it is the same silent-omission bug in a
- // different disguise.
- usage: {
- input_tokens: wireInput,
- cache_read_input_tokens: wireCacheRead,
- cache_creation_input_tokens: wireCacheCreation,
- output_tokens: state.usage?.completion_tokens || 0,
- },
- });
- send("message_stop", { type: "message_stop" });
- }
+ // `finish_reason` is the ONLY completion signal. Neither the `[DONE]`
+ // sentinel nor a final usage object counts: both are transport
+ // punctuation that a proxy, a load balancer or a truncated body can
+ // produce without the model ever having finished.
+ const producedContent =
+ state.accumulatedText.length > 0 ||
+ writer.anyBlockEmitted ||
+ state.tools.size > 0 ||
+ textToolCalls.length > 0;
+ const toolInFlight =
+ // Already on the wire, including text-recovered calls from earlier
+ // turns of this same finalize — `state.tools` does not cover those.
+ writer.emittedToolRefs.length > 0 ||
+ // `&& !t.closed` is load-bearing: `buffered && !started` is TRUE for
+ // a tool that already failed validation and was closed.
+ Array.from(state.tools.values()).some(
+ (t) => !t.closed && (t.started || t.buffered)
+ ) ||
+ textToolCalls.length > 0;
+
+ /**
+ * `success` — the provider said how it finished, or produced nothing.
+ * `silent-truncation` — no finish_reason, content, but no tool: the
+ * partial prose is harmless and VISIBLE, and `max_tokens` is
+ * Anthropic's own "the turn was cut off" label. An `error` here would
+ * discard text the user can read.
+ * `failure` — the turn cannot be presented as complete. Ends with an
+ * SSE `error` event, which Claude Code honours by discarding a
+ * partial `tool_use` and retrying (verified against a real client,
+ * reports/truncated-toolcall-live-verification.md).
+ */
+ const ending: "success" | "silent-truncation" | "failure" =
+ reason === "error"
+ ? "failure"
+ : state.finishReason !== null || !producedContent
+ ? "success"
+ : toolInFlight
+ ? "failure"
+ : "silent-truncation";
+
+ if (ending !== "success") {
+ log(
+ `[Streaming] Stream ending error: reason=${reason} finish_reason=${state.finishReason ?? "null"} content=${producedContent} tool_in_flight=${toolInFlight} → ${ending}`
+ );
+ }
+
+ // On a failure ending claudish emits NO NEW tool block and NO completed
+ // tool call: the buffered flush below is skipped and recovered calls are
+ // suppressed. It cannot recall a non-buffered tool block already on the
+ // wire — `content_block_start` went out before a single argument byte
+ // existed — but that partial is exactly the case the client-side
+ // measurement covers.
+ const emitToolCalls = ending !== "failure";
- // Update token counts - use actual usage if available, otherwise estimate
- if (onTokenUpdate) {
- if (state.usage) {
+ if (textToolCalls.length > 0 && !emitToolCalls) {
log(
- `[Streaming] Final usage: prompt=${state.usage.prompt_tokens || 0}, completion=${state.usage.completion_tokens || 0}`
+ `[Streaming] Suppressing ${textToolCalls.length} text-recovered tool call(s): the turn ended in failure`
);
- // FIRST ARGUMENT STAYS `prompt_tokens`: the tracker's input number
- // is the context-occupancy figure the status line renders and the
- // billing baseline the delta strategy compares against. The split
- // goes in the third argument, where only the cost arithmetic sees
- // it.
- const costSplit = splitPromptTokens(state.usage);
- onTokenUpdate(state.usage.prompt_tokens || 0, state.usage.completion_tokens || 0, {
- cacheReadTokens: costSplit.cacheReadTokens,
- cacheCreationTokens: costSplit.cacheCreationTokens,
- });
- } else {
- // Estimate tokens for local models that don't return usage data
- // Rough estimate: ~4 characters per token
- const estimatedOutputTokens = Math.ceil(state.accumulatedText.length / 4);
+ } else if (textToolCalls.length > 0) {
log(
- `[Streaming] No usage data from provider, estimating: ~${estimatedOutputTokens} output tokens`
+ `[Streaming] Found ${textToolCalls.length} text-based tool call(s), converting to structured format`
);
- // Carry the previous context size forward rather than a literal
- // 100 — the status line reads this value, and 100 would make the
- // bar collapse to "empty" on any turn the provider skips usage.
- onTokenUpdate(priorInputTokens || 100, estimatedOutputTokens);
+
+ // Send each extracted tool call as a proper tool_use block.
+ // `openTool` closes whatever is open first, which is where the
+ // hand-written "close any open text block" used to live.
+ for (const tc of textToolCalls) {
+ const toolIdx = writer.reserve();
+ const toolId = `tool_${Date.now()}_${toolIdx}`;
+ const ref = writer.openTool({ id: toolId, name: tc.name, index: toolIdx });
- writer.append(ref, repairArgs(tc.name, JSON.stringify(tc.arguments)));
++ writer.append(ref, JSON.stringify(tc.arguments));
+ writer.close(ref);
+ }
}
- }
- } finally {
- teardown();
- }
- };
-
- try {
- const reader = response.body!.getReader();
- let buffer = "";
-
- while (true) {
- const { done, value } = await reader.read();
- if (done) break;
- buffer += decoder.decode(value, { stream: true });
- const lines = buffer.split("\n");
- buffer = lines.pop() || "";
-
- for (const line of lines) {
- const dataStr = line.trim() ? sseDataPayload(line) : null;
- if (dataStr === null) continue;
- // Verbatim: this line IS the fixture source (see SSE_LOG_MAX_CHARS).
- log(`[SSE:openai] ${formatRawSseLogPayload(dataStr)}`);
- if (dataStr === "[DONE]") {
- await finalize("done");
- return;
+
+ // Whatever is still open — thinking, text, or a tool — closes here.
+ // This replaces the hand-written reasoning-then-text pair, which could
+ // only ever close the two kinds it named.
+ writer.closeCurrent();
+
+ // Handle buffered-but-unsent structured tool calls.
+ // Some models (e.g., Gemini via LiteLLM) send tool calls with finish_reason="stop"
+ // instead of "tool_calls", so the normal validation path (line ~695) is never reached.
+ // We must send these buffered tools here so Claude Code can execute them.
+ //
+ // SKIPPED ENTIRELY on a failure ending. Before this gate a failed turn
+ // shipped a COMPLETE, parseable tool call and then an `error` event, so
+ // the protection rested wholly on the client discarding it. Now only an
+ // incomplete partial can reach the client on a failure ending, which is
+ // precisely the case the client-side measurement covers.
+ for (const t of emitToolCalls ? Array.from(state.tools.values()) : []) {
+ if (!t.closed && t.buffered && !t.started) {
+ if (toolSchemas && toolSchemas.length > 0) {
+ const validation = validateToolArguments(
+ t.name,
+ t.arguments,
+ toolSchemas,
+ state.accumulatedText
+ );
+
+ if (validation.valid || (validation.repaired && validation.repairedArgs)) {
- const argsJson = repairArgs(
- t.name,
- JSON.stringify(
- validation.repaired ? validation.repairedArgs : validation.parsedArgs
- )
++ const argsJson = JSON.stringify(
++ validation.repaired ? validation.repairedArgs : validation.parsedArgs
+ );
+ log(
+ `[Streaming] Sending buffered tool call (finish_reason!=tool_calls): ${t.name} with args: ${argsJson}`
+ );
+ t.ref = writer.openTool({ id: t.id, name: t.name, index: t.blockIndex });
+ writer.append(t.ref, argsJson);
+ writer.close(t.ref);
+ t.started = true;
+ t.closed = true;
+ } else {
+ log(
+ `[Streaming] Buffered tool call ${t.name} failed validation, skipping: ${validation.missingParams.join(", ")}`
+ );
+ t.closed = true;
+ }
+ } else {
+ // No schemas to validate against — send as-is
- const argsJson = repairArgs(t.name, t.arguments || "{}");
++ const argsJson = t.arguments || "{}";
+ log(
+ `[Streaming] Sending buffered tool call (no validation): ${t.name} with args: ${argsJson}`
+ );
+ t.ref = writer.openTool({ id: t.id, name: t.name, index: t.blockIndex });
+ writer.append(t.ref, argsJson);
+ writer.close(t.ref);
+ t.started = true;
+ t.closed = true;
+ }
+ }
}
- try {
- let chunk = JSON.parse(dataStr);
- if (chunk.usage) {
- state.usage = chunk.usage;
+ // Close any remaining started-but-unclosed tool calls. Under the
+ // one-open-block invariant at most one of these is still open; the
+ // rest were closed when the block that superseded them opened, and
+ // `writer.close` is a no-op for those.
+ for (const t of Array.from(state.tools.values())) {
+ if (t.started && !t.closed) {
+ if (t.ref) writer.close(t.ref);
+ t.closed = true;
+ }
+ }
+
- if (middlewareManager) {
- await middlewareManager.afterStreamComplete(target, streamMetadata);
- }
++ if (raw) await raw.streamEnd();
+
+ if (ending === "failure") {
+ // An SSE `error` event is the ONE ending Claude Code honours by
+ // discarding a partial `tool_use` and retrying the turn. `end_turn`
+ // means "the turn finished, run the tool" and made the client execute
+ // truncated JSON; `max_tokens` was assumed to rescue it and measurably
+ // does not (adapters.md, and the 2026-09-10 live verification).
+ const message =
+ err ??
+ "Upstream stream ended with no finish_reason while a tool call was in flight. " +
+ "The tool call is incomplete and was not dispatched.";
+ send("error", {
+ type: "error",
+ error: { type: "api_error", message: redactForClient(message) },
+ });
+ } else {
+ // Set stop_reason based on whether we sent ANY tool calls (text-based or structured)
+ const hasStructuredTools = Array.from(state.tools.values()).some((t) => t.started);
+ // A turn the PROVIDER cut off must not be reported as a turn the model
+ // chose to end. Anthropic's contract for a cut-off turn is "max_tokens";
+ // reporting "end_turn" presents a truncated (or, when reasoning consumed
+ // the whole budget, an EMPTY) answer as the model's complete final word.
+ // Mirrors openai-responses-sse.ts, which already does this.
+ // `content_filter` is the same class: the provider refused, which is
+ // Anthropic's "refusal", not a turn the model chose to end.
+ // openai-responses-sse.ts already maps both this way.
+ // `length` still OUTRANKS `tool_use` — a truncated turn is reported as
+ // truncated even when it carries a tool call. A silent truncation (no
+ // finish_reason, content produced, no tool in flight) takes the same
+ // label: it IS a cut-off turn, and `max_tokens` is Anthropic's word
+ // for one. Neither can collide with the other: `finishReason` is
+ // non-null in the first case and null in the second.
+ const truncated = state.finishReason === "length" || ending === "silent-truncation";
+ const refused = state.finishReason === "content_filter";
+ const stopReason = refused
+ ? "refusal"
+ : truncated
+ ? "max_tokens"
+ : textToolCalls.length > 0 || hasStructuredTools
+ ? "tool_use"
+ : "end_turn";
+ if (truncated || refused) {
log(
- `[Streaming] Usage data received: prompt=${chunk.usage.prompt_tokens}, completion=${chunk.usage.completion_tokens}, total=${chunk.usage.total_tokens}`
+ `[Streaming] Upstream finish_reason=${state.finishReason} → stop_reason=${stopReason} (${state.accumulatedText.length} chars produced)`
);
}
- // An error carried inside the 200 body. Checked AFTER `usage`
- // so the tokens the turn already spent are still reported, and
- // BEFORE the `choices[0]` reads below, which an error frame's
- // empty `choices` array silently fails to match.
+ // A turn that ended NORMALLY must carry at least one content block.
+ // `stop_reason: "end_turn"` with an empty `content` array is not a
+ // shape Anthropic's API produces, and a client that indexes the last
+ // block, or renders the turn, has nothing to work with — the turn
+ // reads as a success that delivered nothing, with no diagnostic.
//
- // `finalize("error", …)` emits an SSE `error` event, which is
- // the only thing that makes Claude Code surface the failure. The
- // alternative — turning it into an assistant text block — is the
- // mistake `stream-head-sniffer.ts` documents: it freezes a
- // provider failure into the transcript as a successful answer.
- const inStreamError = describeInStreamError(chunk);
- if (inStreamError) {
- log(`[Streaming] Upstream error inside a 200 stream: ${inStreamError}`);
- await finalize("error", inStreamError);
- return;
- }
-
- // The raw tap runs BEFORE anything is derived from the chunk:
- // what it returns is the committed object (a hook's clone, or
- // the chunk itself), and every read below is of it, deletions
- // and a changed finish_reason included.
- if (raw && chunk.choices?.[0]?.delta) {
- chunk = raw.chunk(chunk, (c: any) => c.choices?.[0]?.delta);
+ // The test is `stop_reason === "end_turn"` rather than "the ending was
+ // a success", because that single value already excludes every case
+ // where emptiness is MEANINGFUL and must be preserved:
+ // • "max_tokens" — reasoning consumed the whole budget and the turn
+ // was cut off. `gemini-3.1-pro-or-maxtokens-empty.sse` is a real
+ // capture of exactly this; it must not be papered over.
+ // • "max_tokens" from a silent truncation (item 4) — same reasoning.
+ // • "refusal" — the provider refused. Emptiness IS the answer.
+ // • "tool_use" — a tool block was emitted, so it is not contentless.
+ //
+ // An EMPTY text block, not placeholder prose and not an error. Prose
+ // would enter the conversation history as the assistant's words and be
+ // replayed forever; an `error` would trigger the client's retry loop on
+ // a deterministic outcome, which is adapters.md's stated reason for
+ // keeping `max_tokens` over an error on the sibling case.
+ if (stopReason === "end_turn" && !writer.anyBlockEmitted) {
+ log(
+ `[Streaming] Contentless turn error: end_turn with no content block emitted (finish_reason=${state.finishReason ?? "null"}) — emitting an empty text block`
+ );
+ writer.close(writer.openText());
}
- const delta = chunk.choices?.[0]?.delta;
- const finishReason = chunk.choices?.[0]?.finish_reason;
- if (finishReason) state.finishReason = finishReason;
+ // The three input counters are derived ONCE and used for both the
+ // wire and the cost update below, so the two cannot disagree.
+ const split = splitPromptTokens(state.usage);
+ // One degenerate turn is sent UNSPLIT, and this is not a special
+ // case so much as the merge rule read honestly.
+ //
+ // Claude Code only lets a delta value override its running total
+ // when that value is GREATER THAN ZERO (2.1.273:
+ // `n.input_tokens !== null && n.input_tokens > 0 ? n.input_tokens : e.input_tokens`).
+ // So on a turn whose input is entirely cache — possible only when
+ // the request repeats one already cached, i.e. a retry — an
+ // `input_tokens: 0` is DISCARDED and the message_start seed (the
+ // PREVIOUS turn's full context) survives beside a full-size
+ // `cache_read_input_tokens`. The client would then sum the two and
+ // believe the conversation is roughly twice its real size.
+ //
+ // Reporting that turn as ordinary input keeps the client's sum
+ // exactly equal to `prompt_tokens`, which is the invariant that
+ // matters. It costs nothing on the money side: the cost split is
+ // taken from `splitPromptTokens` independently, below.
+ const fullyCached = split.promptTokens > 0 && split.inputTokens === 0;
+ const wireInput = fullyCached ? split.promptTokens : split.inputTokens;
+ const wireCacheRead = fullyCached ? 0 : split.cacheReadTokens;
+ const wireCacheCreation = fullyCached ? 0 : split.cacheCreationTokens;
+ send("message_delta", {
+ type: "message_delta",
+ delta: { stop_reason: stopReason, stop_sequence: null },
+ // input_tokens must ride the delta too: Claude Code takes the
+ // context size from the last assistant message, and message_start
+ // could only carry an estimate. Omitting it left the client
+ // believing every conversation was 100 tokens, which silently
+ // disabled auto-compaction on every openai-sse provider.
+ //
+ // All THREE keys ship TOGETHER, unconditionally, and that is not
+ // stylistic. Claude Code reconstructs the conversation size by
+ // summing them (verified in the 2.1.273 binary:
+ // `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`,
+ // read by both the context meter and the auto-compaction
+ // threshold), so a reduced `input_tokens` sent WITHOUT its two
+ // siblings understates the context by exactly the cached portion
+ // — on the measured xAI turn, 20352 of 20379 tokens. That is the
+ // one shape that reproduces the failure the paragraph above
+ // records. `splitPromptTokens` guarantees the three sum back to
+ // `prompt_tokens`.
+ //
+ // `input_tokens` is emitted even when it is 0 (a fully-cached
+ // turn), because omitting it is the same silent-omission bug in a
+ // different disguise.
+ usage: {
+ input_tokens: wireInput,
+ cache_read_input_tokens: wireCacheRead,
+ cache_creation_input_tokens: wireCacheCreation,
+ output_tokens: state.usage?.completion_tokens || 0,
+ },
+ });
- behavior?.onTurnEnd?.();
+ send("message_stop", { type: "message_stop" });
+ }
- // Debug: Log chunk details for troubleshooting early termination
- if (delta?.content || finishReason) {
+ // Update token counts - use actual usage if available, otherwise estimate
+ if (onTokenUpdate) {
+ if (state.usage) {
+ reportProviderUsage();
+ } else {
+ // Estimate tokens for local models that don't return usage data
+ // Rough estimate: ~4 characters per token
+ const estimatedOutputTokens = Math.ceil(state.accumulatedText.length / 4);
log(
- `[Streaming] Chunk: content=${delta?.content?.length || 0} chars, finish_reason=${finishReason || "null"}`
+ `[Streaming] No usage data from provider, estimating: ~${estimatedOutputTokens} output tokens`
);
+ // Carry the previous context size forward rather than a literal
+ // 100 — the status line reads this value, and 100 would make the
+ // bar collapse to "empty" on any turn the provider skips usage.
+ onTokenUpdate(priorInputTokens || 100, estimatedOutputTokens);
}
+ }
+ } finally {
+ teardown();
+ }
+ };
- if (delta) {
- // Reasoning arrives under two different field names on this one
- // wire format: `reasoning_content` (Kimi, DeepSeek via LiteLLM)
- // and `reasoning` (OpenRouter). Reading only the former silently
- // dropped every OpenRouter thinking model's reasoning.
- const reasoningText = delta.reasoning_content || delta.reasoning;
- if (reasoningText) {
- // This provider has a reasoning FIELD, so a `<think>` in its
- // content is a model writing about tags, not speaking in them.
- // Close-tag handling stays armed: these are exactly the
- // providers whose chat template opens `<think>` server-side and
- // leaks the bare close into the content.
- thinkSplitter.disarmOpen();
- state.lastActivity = Date.now();
- // Reasoning arriving AFTER text used to open a thinking block
- // while the text block was still open — two open blocks, which
- // Anthropic's wire does not allow. `openThinking` closes the
- // text block first. That difference is the point of this change.
- writer.append(writer.openThinking(), reasoningText);
- }
+ try {
+ const reader = response.body!.getReader();
+ upstream.reader = reader;
+ let buffer = "";
+
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ buffer += decoder.decode(value, { stream: true });
+ const lines = buffer.split("\n");
+ buffer = lines.pop() || "";
+
+ for (const line of lines) {
+ const dataStr = line.trim() ? sseDataPayload(line) : null;
+ if (dataStr === null) continue;
+ // Verbatim: this line IS the fixture source (see SSE_LOG_MAX_CHARS).
+ log(`[SSE:openai] ${formatRawSseLogPayload(dataStr)}`);
+ if (dataStr === "[DONE]") {
+ await finalize("done");
+ return;
+ }
- // Handle text content
- const txt = delta.content || "";
- log(
- `[Streaming] Text chunk: "${txt.substring(0, 30).replace(/\n/g, "\\n")}" (${txt.length} chars)`
- );
- if (txt) {
- state.lastActivity = Date.now();
- // The thinking block is NOT closed here any more: it closes
- // when `writer.openText()` actually runs below. A chunk that
- // the adapter empties, or that is held back pending a tool
- // pattern, no longer ends the thinking block on the strength
- // of text that never reaches the client.
- const res = adapter.processTextContent(txt, "");
+ try {
- const chunk = JSON.parse(dataStr);
++ let chunk = JSON.parse(dataStr);
+ if (chunk.usage) {
+ state.usage = chunk.usage;
log(
- `[Streaming] After adapter: "${res.cleanedText.substring(0, 30).replace(/\n/g, "\\n")}" (${res.cleanedText.length} chars, transformed=${res.wasTransformed})`
+ `[Streaming] Usage data received: prompt=${chunk.usage.prompt_tokens}, completion=${chunk.usage.completion_tokens}, total=${chunk.usage.total_tokens}`
);
+ }
- // An adapter emptying a chunk is LEGITIMATE on this path, so
- // there is deliberately no "non-empty in, non-empty out" guard
- // here — unlike gemini-sse.ts, which has one. Two adapters
- // return "" by design:
- // • QwenModelDialect — the chunk was entirely chat-template
- // special tokens (`<|im_start|>` &c.); passing the original
- // through would leak them to the user.
- // • GrokModelDialect — it is buffering a `<xai:function_call>`
- // XML block split across chunks; passing the original
- // through would emit half a tool call as visible text.
- // Per-chunk emptiness is therefore not evidence of loss here.
- // What WOULD be a bug is a whole turn arriving empty; that is
- // caught at the turn level by the probe and by stop_reason.
- if (txt.length > 0 && res.cleanedText.length === 0) {
- log(`[Streaming] Text filtered out by adapter: "${txt.substring(0, 50)}"`);
- }
+ // An error carried inside the 200 body. Checked AFTER `usage`
+ // so the tokens the turn already spent are still reported, and
+ // BEFORE the `choices[0]` reads below, which an error frame's
+ // empty `choices` array silently fails to match.
+ //
+ // `finalize("error", …)` emits an SSE `error` event, which is
+ // the only thing that makes Claude Code surface the failure. The
+ // alternative — turning it into an assistant text block — is the
+ // mistake `stream-head-sniffer.ts` documents: it freezes a
+ // provider failure into the transcript as a successful answer.
+ const inStreamError = describeInStreamError(chunk);
+ if (inStreamError) {
+ log(`[Streaming] Upstream error inside a 200 stream: ${inStreamError}`);
+ await finalize("error", inStreamError);
+ return;
+ }
- if (res.cleanedText) {
- // `<think>…</think>` carried in the ORDINARY content field is
- // reasoning, not the answer. Split it out here, after the
- // adapter, so the thinking half never enters
- // `accumulatedText` (tool-call recovery scans that) and never
- // renders as the assistant's words.
- emitSplitContent(thinkSplitter.push(res.cleanedText));
- }
++ // The raw tap runs BEFORE anything is derived from the chunk:
++ // what it returns is the committed object (a hook's clone, or
++ // the chunk itself), and every read below is of it, deletions
++ // and a changed finish_reason included.
++ if (raw && chunk.choices?.[0]?.delta) {
++ chunk = raw.chunk(chunk, (c: any) => c.choices?.[0]?.delta);
+ }
+
- // Handle tool calls
- if (delta.tool_calls) {
+ const delta = chunk.choices?.[0]?.delta;
+ const finishReason = chunk.choices?.[0]?.finish_reason;
+ if (finishReason) state.finishReason = finishReason;
+
+ // Debug: Log chunk details for troubleshooting early termination
+ if (delta?.content || finishReason) {
log(
- `[Streaming] Received ${delta.tool_calls.length} structured tool call(s) from model`
+ `[Streaming] Chunk: content=${delta?.content?.length || 0} chars, finish_reason=${finishReason || "null"}`
);
- for (const tc of delta.tool_calls) {
- const idx = tc.index;
- let t = state.tools.get(idx);
- if (tc.function?.name) {
- // Accumulate the name BEFORE anything reads it: a provider
- // may split `function.name` across chunks, and this is the
- // one place a complete name exists.
- const accumulatedName =
- (state.pendingToolName.get(idx) ?? "") + tc.function.name;
- state.pendingToolName.set(idx, accumulatedName);
- // THIS IS THE DECODE POINT: it reads the accumulated name,
- // never a single chunk's fragment. Decoding a fragment
- // misses the map, and the allowlist then drops the call
- // in silence.
- const restoredName = toolNameMap?.get(accumulatedName) || accumulatedName;
- if (!t) {
- // The hand-written "close thinking, then close text"
- // pair that used to stand here is `openTool`'s job now.
- t = {
- id: tc.id || `tool_${Date.now()}_${idx}`,
- name: restoredName,
- // Reserved, not opened: a buffered tool keeps its place
- // in the index order and emits at finish_reason time.
- blockIndex: writer.reserve(),
- started: false,
- closed: false,
- // Seeded, not empty: fragments that arrived for this
- // index before the name did are drained in here.
- arguments: state.pendingToolArgs.get(idx) ?? "",
- ref: null,
- // Buffer if we have schemas to validate the
- // completed arguments against.
- buffered: !!toolSchemas && toolSchemas.length > 0,
- };
- if (t.arguments) {
- log(
- `[Streaming] tool ${t.name} (index ${idx}): seeded ${t.arguments.length} argument chars that arrived before function.name`
- );
- }
- state.pendingToolArgs.delete(idx);
- state.tools.set(idx, t);
- if (isWebSearchToolCall(restoredName)) {
- warnWebSearchUnsupported(restoredName, target);
- }
- } else if (t.name !== restoredName) {
- // A LATER fragment completed the name. The tool was
- // created from the first fragment, so its name is a
- // prefix — and a prefix of an encoded name decodes to
- // nothing, which is how a call gets dropped without a
- // word anywhere.
- if (t.started) {
- // The block is already on the wire under the short
- // name; it cannot be recalled. "error" is deliberate
- // — it is what carries this to the structural log.
- log(
- `[Streaming] error: tool block ${t.blockIndex} was started as "${t.name}" but the full name is "${restoredName}" — the client sees the wrong name`
- );
- } else {
- t.name = restoredName;
- t.buffered = !!toolSchemas && toolSchemas.length > 0;
+ }
+
+ if (delta) {
- if (middlewareManager) {
- await middlewareManager.afterStreamChunk({
- modelId: target,
- chunk,
- delta,
- metadata: streamMetadata,
- });
- }
-
+ // Reasoning arrives under two different field names on this one
+ // wire format: `reasoning_content` (Kimi, DeepSeek via LiteLLM)
+ // and `reasoning` (OpenRouter). Reading only the former silently
+ // dropped every OpenRouter thinking model's reasoning.
+ const reasoningText = delta.reasoning_content || delta.reasoning;
+ if (reasoningText) {
+ // This provider has a reasoning FIELD, so a `<think>` in its
+ // content is a model writing about tags, not speaking in them.
+ // Close-tag handling stays armed: these are exactly the
+ // providers whose chat template opens `<think>` server-side and
+ // leaks the bare close into the content.
+ thinkSplitter.disarmOpen();
- behavior?.onAssistantText?.(reasoningText, "reasoning");
+ state.lastActivity = Date.now();
+ // Reasoning arriving AFTER text used to open a thinking block
+ // while the text block was still open — two open blocks, which
+ // Anthropic's wire does not allow. `openThinking` closes the
+ // text block first. That difference is the point of this change.
+ writer.append(writer.openThinking(), reasoningText);
+ }
+
+ // Handle text content
+ const txt = delta.content || "";
- if (txt) behavior?.onAssistantText?.(txt, "text");
+ log(
+ `[Streaming] Text chunk: "${txt.substring(0, 30).replace(/\n/g, "\\n")}" (${txt.length} chars)`
+ );
+ if (txt) {
+ state.lastActivity = Date.now();
+ // The thinking block is NOT closed here any more: it closes
+ // when `writer.openText()` actually runs below. A chunk that
+ // the adapter empties, or that is held back pending a tool
+ // pattern, no longer ends the thinking block on the strength
+ // of text that never reaches the client.
+ const res = adapter.processTextContent(txt, "");
+ log(
+ `[Streaming] After adapter: "${res.cleanedText.substring(0, 30).replace(/\n/g, "\\n")}" (${res.cleanedText.length} chars, transformed=${res.wasTransformed})`
+ );
+
+ // An adapter emptying a chunk is LEGITIMATE on this path, so
+ // there is deliberately no "non-empty in, non-empty out" guard
+ // here — unlike gemini-sse.ts, which has one. Two adapters
+ // return "" by design:
+ // • QwenModelDialect — the chunk was entirely chat-template
+ // special tokens (`<|im_start|>` &c.); passing the original
+ // through would leak them to the user.
+ // • GrokModelDialect — it is buffering a `<xai:function_call>`
+ // XML block split across chunks; passing the original
+ // through would emit half a tool call as visible text.
+ // Per-chunk emptiness is therefore not evidence of loss here.
+ // What WOULD be a bug is a whole turn arriving empty; that is
+ // caught at the turn level by the probe and by stop_reason.
+ if (txt.length > 0 && res.cleanedText.length === 0) {
+ log(`[Streaming] Text filtered out by adapter: "${txt.substring(0, 50)}"`);
+ }
+
+ if (res.cleanedText) {
+ // `<think>…</think>` carried in the ORDINARY content field is
+ // reasoning, not the answer. Split it out here, after the
+ // adapter, so the thinking half never enters
+ // `accumulatedText` (tool-call recovery scans that) and never
+ // renders as the assistant's words.
+ emitSplitContent(thinkSplitter.push(res.cleanedText));
+ }
+ }
+
+ // Handle tool calls
+ if (delta.tool_calls) {
+ log(
+ `[Streaming] Received ${delta.tool_calls.length} structured tool call(s) from model`
+ );
+ for (const tc of delta.tool_calls) {
+ const idx = tc.index;
+ let t = state.tools.get(idx);
+ if (tc.function?.name) {
+ // Accumulate the name BEFORE anything reads it: a provider
+ // may split `function.name` across chunks, and this is the
+ // one place a complete name exists.
+ const accumulatedName =
+ (state.pendingToolName.get(idx) ?? "") + tc.function.name;
+ state.pendingToolName.set(idx, accumulatedName);
+ // THIS IS THE DECODE POINT: it reads the accumulated name,
+ // never a single chunk's fragment. Decoding a fragment
+ // misses the map, and the allowlist then drops the call
+ // in silence.
+ const restoredName = toolNameMap?.get(accumulatedName) || accumulatedName;
+ if (!t) {
+ // The hand-written "close thinking, then close text"
+ // pair that used to stand here is `openTool`'s job now.
+ t = {
+ id: tc.id || `tool_${Date.now()}_${idx}`,
+ name: restoredName,
+ // Reserved, not opened: a buffered tool keeps its place
+ // in the index order and emits at finish_reason time.
+ blockIndex: writer.reserve(),
+ started: false,
+ closed: false,
+ // Seeded, not empty: fragments that arrived for this
+ // index before the name did are drained in here.
+ arguments: state.pendingToolArgs.get(idx) ?? "",
+ ref: null,
- // Buffer if we have schemas to validate, OR if a behavior
- // rule wants to rewrite this call — repair is only
- // possible while the arguments are still withheld.
- buffered:
- (!!toolSchemas && toolSchemas.length > 0) ||
- behavior?.shouldBufferTool?.(restoredName) === true,
++ // Buffer if we have schemas to validate the
++ // completed arguments against.
++ buffered: !!toolSchemas && toolSchemas.length > 0,
+ };
+ if (t.arguments) {
+ log(
+ `[Streaming] tool ${t.name} (index ${idx}): seeded ${t.arguments.length} argument chars that arrived before function.name`
+ );
+ }
+ state.pendingToolArgs.delete(idx);
+ state.tools.set(idx, t);
if (isWebSearchToolCall(restoredName)) {
warnWebSearchUnsupported(restoredName, target);
}
+ } else if (t.name !== restoredName) {
+ // A LATER fragment completed the name. The tool was
+ // created from the first fragment, so its name is a
+ // prefix — and a prefix of an encoded name decodes to
+ // nothing, which is how a call gets dropped without a
+ // word anywhere.
+ if (t.started) {
+ // The block is already on the wire under the short
+ // name; it cannot be recalled. "error" is deliberate
+ // — it is what carries this to the structural log.
+ log(
+ `[Streaming] error: tool block ${t.blockIndex} was started as "${t.name}" but the full name is "${restoredName}" — the client sees the wrong name`
+ );
+ } else {
+ t.name = restoredName;
- t.buffered =
- (!!toolSchemas && toolSchemas.length > 0) ||
- behavior?.shouldBufferTool?.(restoredName) === true;
++ t.buffered = !!toolSchemas && toolSchemas.length > 0;
+ if (isWebSearchToolCall(restoredName)) {
+ warnWebSearchUnsupported(restoredName, target);
+ }
+ }
+ }
+ // Only send content_block_start immediately if NOT buffering
+ if (!t.started && !t.buffered) {
+ t.ref = writer.openTool({
+ id: t.id,
+ name: t.name,
+ index: t.blockIndex,
+ });
+ t.started = true;
+ // Flush the seed as ONE delta, right after the start.
+ // Skipped when the seed is empty, which is every capture
+ // in the tree — so the common case stays byte-identical.
+ if (t.arguments) writer.append(t.ref, t.arguments);
}
}
- // Only send content_block_start immediately if NOT buffering
- if (!t.started && !t.buffered) {
- t.ref = writer.openTool({
- id: t.id,
- name: t.name,
- index: t.blockIndex,
- });
- t.started = true;
- // Flush the seed as ONE delta, right after the start.
- // Skipped when the seed is empty, which is every capture
- // in the tree — so the common case stays byte-identical.
- if (t.arguments) writer.append(t.ref, t.arguments);
+ if (tc.function?.arguments && !t) {
+ // Arguments before the name. This used to be dropped by an
+ // `&& t` guard, so the head of the JSON object vanished and
+ // what survived began mid-object and could not parse —
+ // indistinguishable downstream from a model emitting bad
+ // JSON. Hold it until the name creates the tool.
+ state.pendingToolArgs.set(
+ idx,
+ (state.pendingToolArgs.get(idx) ?? "") + tc.function.arguments
+ );
}
- }
- if (tc.function?.arguments && !t) {
- // Arguments before the name. This used to be dropped by an
- // `&& t` guard, so the head of the JSON object vanished and
- // what survived began mid-object and could not parse —
- // indistinguishable downstream from a model emitting bad
- // JSON. Hold it until the name creates the tool.
- state.pendingToolArgs.set(
- idx,
- (state.pendingToolArgs.get(idx) ?? "") + tc.function.arguments
- );
- }
- if (tc.function?.arguments && t) {
- // Always accumulate arguments
- t.arguments += tc.function.arguments;
- // Only stream immediately if NOT buffering
- if (!t.buffered) {
- if (!t.ref || !writer.append(t.ref, tc.function.arguments)) {
- // OpenAI's wire lets `tool_calls[0]` and `tool_calls[1]`
- // fragments interleave; Anthropic's allows one open
- // block. So this tool's block is no longer the open one
- // — something else (another tool, or text) took over and
- // closed it. Degrade THIS tool to the buffered path: the
- // complete arguments go out as one block when the call
- // closes. Same recovery shape the repair path already
- // uses when it supersedes a partially-streamed block.
- log(
- `[Streaming] tool ${t.name} (index ${idx}) lost its open block mid-arguments — buffering the rest`
- );
- t.buffered = true;
- t.started = false;
- t.ref = null;
+ if (tc.function?.arguments && t) {
+ // Always accumulate arguments
+ t.arguments += tc.function.arguments;
+ // Only stream immediately if NOT buffering
+ if (!t.buffered) {
+ if (!t.ref || !writer.append(t.ref, tc.function.arguments)) {
+ // OpenAI's wire lets `tool_calls[0]` and `tool_calls[1]`
+ // fragments interleave; Anthropic's allows one open
+ // block. So this tool's block is no longer the open one
+ // — something else (another tool, or text) took over and
+ // closed it. Degrade THIS tool to the buffered path: the
+ // complete arguments go out as one block when the call
+ // closes. Same recovery shape the repair path already
+ // uses when it supersedes a partially-streamed block.
+ log(
+ `[Streaming] tool ${t.name} (index ${idx}) lost its open block mid-arguments — buffering the rest`
+ );
+ t.buffered = true;
+ t.started = false;
+ t.ref = null;
+ }
}
}
}
}
}
- }
- if (chunk.choices?.[0]?.finish_reason === "tool_calls") {
- for (const t of Array.from(state.tools.values())) {
- if (!t.closed) {
- // Validate and potentially repair tool arguments
- if (toolSchemas && toolSchemas.length > 0) {
- const validation = validateToolArguments(
- t.name,
- t.arguments,
- toolSchemas,
- state.accumulatedText
- );
-
- if (validation.repaired && validation.repairedArgs) {
- // Tool call was repaired - send the complete repaired arguments
- log(
- `[Streaming] Tool call ${t.name} was repaired with inferred parameters`
- );
- const repairedJson = JSON.stringify(validation.repairedArgs);
- log(
- `[Streaming] Sending repaired tool call: ${t.name} with args: ${repairedJson}`
+ if (chunk.choices?.[0]?.finish_reason === "tool_calls") {
+ for (const t of Array.from(state.tools.values())) {
+ if (!t.closed) {
+ // Validate and potentially repair tool arguments
+ if (toolSchemas && toolSchemas.length > 0) {
+ const validation = validateToolArguments(
+ t.name,
+ t.arguments,
+ toolSchemas,
+ state.accumulatedText
);
- // If buffered, this is the first time we're sending this tool call
- // Send the complete repaired tool call as a single block
+ if (validation.repaired && validation.repairedArgs) {
+ // Tool call was repaired - send the complete repaired arguments
+ log(
+ `[Streaming] Tool call ${t.name} was repaired with inferred parameters`
+ );
- const repairedJson = repairArgs(
- t.name,
- JSON.stringify(validation.repairedArgs)
- );
++ const repairedJson = JSON.stringify(validation.repairedArgs);
+ log(
+ `[Streaming] Sending repaired tool call: ${t.name} with args: ${repairedJson}`
+ );
+
+ // If buffered, this is the first time we're sending this tool call
+ // Send the complete repaired tool call as a single block
+ if (t.buffered && !t.started) {
+ t.ref = writer.openTool({
+ id: t.id,
+ name: t.name,
+ index: t.blockIndex,
+ });
+ writer.append(t.ref, repairedJson);
+ writer.close(t.ref);
+ t.started = true;
+ t.closed = true;
+ continue;
+ }
+
+ // If already started (non-buffered), close old and send new.
+ // This is the one path that mints a SECOND block for a tool
+ // that already has one — the partially-streamed original is
+ // closed and superseded, under a new id.
+ if (t.started) {
+ if (t.ref) writer.close(t.ref);
+ const repairedIdx = writer.reserve();
+ const repairedId = `tool_repaired_${Date.now()}_${repairedIdx}`;
+ const repairedRef = writer.openTool({
+ id: repairedId,
+ name: t.name,
+ index: repairedIdx,
+ });
+ writer.append(repairedRef, repairedJson);
+ writer.close(repairedRef);
+ t.ref = repairedRef;
+ t.closed = true;
+ continue;
+ }
+ }
+
+ if (!validation.valid) {
+ // Repair failed - send error message instead of invalid tool call
+ log(
+ `[Streaming] Tool call ${t.name} validation failed: ${validation.missingParams.join(", ")}`
+ );
+ // A buffered tool never emitted its block, so its reserved
+ // index is free and the warning text takes it. A
+ // non-buffered one already spent its index on the tool
+ // block, so the warning needs a fresh one.
+ const errorIdx = t.buffered ? t.blockIndex : undefined;
+ const errorMsg = `\n\n⚠️ Tool call "${t.name}" failed: missing required parameters: ${validation.missingParams.join(", ")}. Local models sometimes generate incomplete tool calls. Please try again or use a model with better tool support.`;
+ const errorRef = writer.openText({ index: errorIdx });
+ writer.append(errorRef, errorMsg);
+ writer.close(errorRef);
+ // Close the invalid tool if it was already started.
+ // `openText` above will already have closed it when it was
+ // the open block; this covers the case where it was not.
+ if (t.started && !t.buffered && t.ref) {
+ writer.close(t.ref);
+ }
+ t.closed = true;
+ continue;
+ }
+
+ // Valid tool call - send if buffered, close if not
if (t.buffered && !t.started) {
- const argsJson = repairArgs(
- t.name,
- JSON.stringify(validation.parsedArgs)
- );
++ const argsJson = JSON.stringify(validation.parsedArgs);
t.ref = writer.openTool({
id: t.id,
name: t.name,
diff --cc packages/cli/src/handlers/shared/stream-parsers/responses/parallel-wrapper.test.ts
index 5170ecb7,00000000..beda41d2
mode 100644,000000..100644
--- a/packages/cli/src/handlers/shared/stream-parsers/responses/parallel-wrapper.test.ts
+++ b/packages/cli/src/handlers/shared/stream-parsers/responses/parallel-wrapper.test.ts
@@@ -1,208 -1,0 +1,206 @@@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import type { Context } from "hono";
+import { createResponsesStreamHandler } from "../openai-responses-sse.js";
+import { ClaudeSseSink } from "./claude-sse-sink.js";
+import { isParallelWrapperName, parseParallelWrapper } from "./parallel-wrapper.js";
+import { parseResponsesLeg } from "./responses-leg.js";
+
+const base = new URL("../../../../test-fixtures/sse-responses/", import.meta.url);
+const text = (name: string) => readFileSync(new URL(name, base), "utf8");
+function events(wire: string): any[] {
+ return wire
+ .split("\n")
+ .filter((l) => l.startsWith("data: ") && l !== "data: [DONE]")
+ .map((l) => JSON.parse(l.slice(6)));
+}
+const valid = () => text("codex-parallel-valid-DERIVED.sse");
+const expected = () =>
+ events(text("codex-zero-delta-multicall.sse"))
+ .filter((e) => e.type === "response.output_item.done")
+ .map((e) => JSON.parse(e.item.arguments));
+
+describe("REQ-3 parallel wrapper expansion", () => {
+ test("REQ-3 TEST-6 expands the labelled derived wrapper into three mapped Read calls with _pN ids", async () => {
+ const response = createResponsesStreamHandler({} as Context, new Response(valid()), {
+ modelName: "capture-model",
+ toolNameMap: new Map([["Read", "ReadDecoded"]]),
+ });
+ const output = events(await response.text());
+ const starts = output.filter(
+ (e) => e.type === "content_block_start" && e.content_block.type === "tool_use"
+ );
+ expect(starts).toHaveLength(3);
+ expect(starts.map((e) => e.content_block.name)).toEqual([
+ "ReadDecoded",
+ "ReadDecoded",
+ "ReadDecoded",
+ ]);
+ const callId = events(valid()).find((e) => e.type === "response.output_item.done").item.call_id;
+ expect(starts.map((e) => e.content_block.id)).toEqual(
+ [0, 1, 2].map((k) => `toolu_${callId.replace(/^fc_/, "")}_p${k}`)
+ );
+ expect(new Set(starts.map((e) => e.content_block.id)).size).toBe(3);
+ expect(
+ starts.map((s) => {
+ const deltas = output.filter(
+ (e) => e.type === "content_block_delta" && e.index === s.index
+ );
+ expect(deltas).toHaveLength(1);
+ return JSON.parse(deltas[0].delta.partial_json);
+ })
+ ).toEqual(expected());
+ });
+
+ test.each([
+ "parallel",
+ "multi_tool_use.parallel",
+ "functions.parallel",
+ "functions.multi_tool_use.parallel",
+ ])("REQ-3 TEST-7 recognizes %s only when not declared", (name) => {
+ expect(isParallelWrapperName(name, [])).toBe(true);
+ expect(isParallelWrapperName(name, [name.replace(/^functions\./, "")])).toBe(false);
+ expect(isParallelWrapperName("Read", [])).toBe(false);
+ });
+
+ test("REQ-3 TEST-7 a declared tool literally named parallel is emitted without expansion", async () => {
+ const response = createResponsesStreamHandler({} as Context, new Response(valid()), {
+ modelName: "capture-model",
+ declaredToolNames: ["parallel"],
+ });
+ const output = events(await response.text());
+ const starts = output.filter(
+ (e) => e.type === "content_block_start" && e.content_block.type === "tool_use"
+ );
+ expect(starts.map((e) => e.content_block.name)).toEqual(["parallel"]);
+ expect(starts[0].content_block.id).not.toContain("_p0");
+ const args = JSON.parse(
+ output
+ .filter((e) => e.type === "content_block_delta" && e.delta.type === "input_json_delta")
+ .map((e) => e.delta.partial_json)
+ .join("")
+ );
+ expect(args.tool_uses.map((u: any) => u.parameters)).toEqual(expected());
+ });
+});
+
+test("REQ-20 TEST-25 degenerate usage drain is bounded to 10000 ms on the injected clock", async () => {
+ // Derived from V0-21: retain the real wrapper but withhold its metadata/terminal usage.
+ const source = events(text("codex-parallel-degenerate-stall.sse"));
+ const end = source.findIndex((e) => e.type === "response.output_item.done");
+ const bytes = new TextEncoder().encode(
+ source
+ .slice(0, end + 1)
+ .map((e) => `data: ${JSON.stringify(e)}\n\n`)
+ .join("")
+ );
+ let cancelled = false;
+ let now = 0;
+ let timer: { at: number; fn: () => void } | undefined;
+ const clock = {
+ now: () => now,
+ setTimeout(fn: () => void, ms: number) {
+ timer = { at: now + ms, fn };
+ return 1;
+ },
+ clearTimeout() {
+ timer = undefined;
+ },
+ };
+ let sink!: ClaudeSseSink;
+ const downstream = new ReadableStream<Uint8Array>({
+ start(c) {
+ sink = new ClaudeSseSink(c, { modelName: "capture-model" });
+ },
+ });
+ const response = new Response(
+ new ReadableStream<Uint8Array>({
+ start(c) {
+ c.enqueue(bytes);
+ },
+ cancel() {
+ cancelled = true;
+ },
+ })
+ );
+ let settled = false;
+ const result = parseResponsesLeg(response, {
+ sink,
+ modelName: "capture-model",
+ declaredToolNames: [],
- streamMetadata: new Map(),
+ drainClock: clock,
+ }).then((outcome) => {
+ settled = true;
+ return outcome;
+ });
+ for (let i = 0; i < 100; i++) await Promise.resolve();
+ expect(timer?.at).toBe(10000);
+ now = 9999;
+ for (let i = 0; i < 100; i++) await Promise.resolve();
+ expect(settled).toBe(false);
+ now = 10000;
+ if (!timer) throw new Error("Expected usage drain timer");
+ timer.fn();
+ const outcome = await result;
+ expect(outcome.kind).toBe("degenerate-wrapper");
+ if (outcome.kind !== "degenerate-wrapper") throw new Error("Expected bounded degenerate outcome");
+ expect(outcome.usage).toBeUndefined();
+ expect(cancelled).toBe(true);
+ sink.close();
+ expect(await new Response(downstream).text()).toBe("");
+}, 1000);
+
+describe("REQ-4 malformed wrappers remain invisible", () => {
+ for (const name of [
+ "codex-parallel-degenerate-stall.sse",
+ "codex-parallel-degenerate-stall-2.sse",
+ "codex-parallel-degenerate-loop.sse",
+ ]) {
+ test(`REQ-4 REQ-15 TEST-8 ${name} yields a degenerate outcome with reason and terminal usage`, async () => {
+ const chunks: Uint8Array[] = [];
+ const stream = new ReadableStream<Uint8Array>({
+ start(controller) {
+ const sink = new ClaudeSseSink(controller, { modelName: "capture-model" });
+ void (async () => {
+ try {
+ const outcome = await parseResponsesLeg(new Response(text(name)), {
+ sink,
+ modelName: "capture-model",
+ declaredToolNames: [],
- streamMetadata: new Map(),
+ drainClock: { now: () => 0, setTimeout: () => 1, clearTimeout: () => {} },
+ });
+ expect(outcome.kind).toBe("degenerate-wrapper");
+ if (outcome.kind !== "degenerate-wrapper")
+ throw new Error("Expected degenerate outcome");
+ expect(outcome.reason).toBe("unparseable");
+ expect(outcome.bytes).toBeGreaterThan(0);
+ expect(outcome.usage?.outputTokens).toBeGreaterThan(0);
+ if (name === "codex-parallel-degenerate-stall.sse") {
+ expect(outcome.usage).toMatchObject({ inputTokens: 39429, outputTokens: 32000 });
+ }
+ sink.close();
+ } catch (error) {
+ controller.error(error);
+ }
+ })();
+ },
+ });
+ const reader = stream.getReader();
+ while (true) {
+ const next = await reader.read();
+ if (next.done) break;
+ chunks.push(next.value);
+ }
+ const output = events(chunks.map((c) => new TextDecoder().decode(c)).join(""));
+ expect(
+ output.filter(
+ (e) => e.type === "content_block_start" && e.content_block.type === "tool_use"
+ )
+ ).toEqual([]);
+ const rawArgs = events(text(name)).find(
+ (e) => e.type === "response.function_call_arguments.done"
+ ).arguments;
+ expect(parseParallelWrapper(rawArgs, (s) => s)).toEqual({ ok: false, reason: "unparseable" });
+ });
+ }
+});
diff --cc packages/cli/src/handlers/shared/stream-parsers/responses/responses-leg.test.ts
index b999714d,00000000..3fbc1be6
mode 100644,000000..100644
--- a/packages/cli/src/handlers/shared/stream-parsers/responses/responses-leg.test.ts
+++ b/packages/cli/src/handlers/shared/stream-parsers/responses/responses-leg.test.ts
@@@ -1,181 -1,0 +1,223 @@@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import type { Context } from "hono";
++import { HookEngine } from "../../../../hooks/engine.js";
++import { UnavailableSink } from "../../../../hooks/injection/sinks.js";
++import type { HookDefinition } from "../../../../hooks/public.js";
++import { HookRegistry } from "../../../../hooks/registry.js";
++import { RequestHooks } from "../../../../hooks/request-stage.js";
++import { applyResponseSeam } from "../../../../hooks/response-seam.js";
+import { collectSseMessage } from "../../collect-sse-message.js";
+import { createResponsesStreamHandler } from "../openai-responses-sse.js";
+
+const base = new URL("../../../../test-fixtures/sse-responses/", import.meta.url);
+// All derived streams below use real events/arguments from the named captures, not invented protocol.
+function capture(name: string): any[] {
+ return readFileSync(new URL(name, base), "utf8")
+ .split("\n")
+ .filter((l) => l.startsWith("data: ") && l !== "data: [DONE]")
+ .map((l) => JSON.parse(l.slice(6)));
+}
+function upstream(events: any[]): Response {
+ return new Response(events.map((e) => `data: ${JSON.stringify(e)}\n\n`).join(""));
+}
+function translated(
+ events: any[],
+ opts: Partial<Parameters<typeof createResponsesStreamHandler>[2]> = {}
+) {
+ return createResponsesStreamHandler({} as Context, upstream(events), {
+ modelName: "capture-model",
+ ...opts,
+ });
+}
+async function folded(response: Response): Promise<any[]> {
+ return (await response.text())
+ .split("\n")
+ .filter((l) => l.startsWith("data: ") && l !== "data: [DONE]")
+ .map((l) => JSON.parse(l.slice(6)));
+}
+function toolArguments(events: any[]) {
+ return events
+ .filter((e) => e.type === "content_block_start" && e.content_block.type === "tool_use")
+ .map((start) => {
+ const deltas = events.filter(
+ (e) =>
+ e.type === "content_block_delta" &&
+ e.index === start.index &&
+ e.delta.type === "input_json_delta"
+ );
+ const stop = events.findIndex(
+ (e) => e.type === "content_block_stop" && e.index === start.index
+ );
+ expect(stop).toBeGreaterThan(events.indexOf(start));
+ for (const delta of deltas) expect(events.indexOf(delta)).toBeLessThan(stop);
+ return {
+ name: start.content_block.name,
+ deltas,
+ args: JSON.parse(deltas.map((d) => d.delta.partial_json).join("")),
+ };
+ });
+}
+const zero = () => capture("codex-zero-delta-multicall.sse");
+const realCalls = () =>
+ zero().filter((e) => e.type === "response.output_item.done" && e.item.type === "function_call");
+
+describe("REQ-1/REQ-2 Responses final arguments", () => {
+ test("REQ-1 TEST-1 emits one full argument delta per real zero-delta Read before stop", async () => {
+ const calls = toolArguments(await folded(translated(zero())));
+ expect(calls).toHaveLength(3);
+ expect(calls.map((c) => c.name)).toEqual(["Read", "Read", "Read"]);
+ expect(calls.map((c) => c.deltas.length)).toEqual([1, 1, 1]);
+ expect(calls.map((c) => c.args)).toEqual(realCalls().map((e) => JSON.parse(e.item.arguments)));
+ expect(calls.map((c) => c.args.file_path.split("/").at(-1))).toEqual(["a.ts", "b.ts", "c.ts"]);
+ });
+
+ test("REQ-1 TEST-2 uses item.arguments when argument-done events are absent", async () => {
+ const calls = toolArguments(
+ await folded(
+ translated(zero().filter((e) => e.type !== "response.function_call_arguments.done"))
+ )
+ );
+ expect(calls.map((c) => c.args)).toEqual(realCalls().map((e) => JSON.parse(e.item.arguments)));
+ expect(calls.map((c) => c.deltas.length)).toEqual([1, 1, 1]);
+ });
+
+ test("REQ-1 TEST-2 prefers argument-done over a different item final", async () => {
+ // Derived from V0-1: first item final uses the second real Read arguments; argument-done stays unchanged.
+ const source = zero();
+ const finals = source.filter((e) => e.type === "response.output_item.done");
+ finals[0].item.arguments = finals[1].item.arguments;
+ const calls = toolArguments(await folded(translated(source)));
+ expect(calls.map((c) => c.args)).toEqual(realCalls().map((e) => JSON.parse(e.item.arguments)));
+ expect(calls.map((c) => c.deltas.length)).toEqual([1, 1, 1]);
+ });
+
+ test("REQ-2 TEST-3 buffers final real arguments before repair and JSON collection", async () => {
++ // Tool-argument repair runs at the hook response seam, above every parser:
++ // a fix-severity toolCall hook there must see each call's final real
++ // arguments, not the empty string a zero-delta call streams.
+ const observed: string[] = [];
- const result = await collectSseMessage(
- translated(zero(), {
- shouldBufferTool: () => true,
- onToolCall: (_name, args) => {
- observed.push(args);
- return null;
++ const def = {
++ apiVersion: 1,
++ id: "observe-repair-input",
++ on: {
++ toolCall: {
++ tools: ["*"],
++ handle: (ctx) => {
++ observed.push(ctx.tool.rawArgs);
++ return [];
++ },
+ },
- }),
++ },
++ } satisfies HookDefinition;
++ const engine = new HookEngine({
++ registry: new HookRegistry(
++ [],
++ [{ id: "hook:t/observe", module: "/t.ts", moduleIndex: 0, exportIndex: 0, def }],
++ undefined
++ ),
++ config: {},
++ hostMode: "other",
++ journalSink: () => {},
++ warn: () => {},
++ drainTelemetryOutbox: false,
++ });
++ const vars = new Map<string, unknown>();
++ const context = {
++ get: (k: string) => vars.get(k),
++ set: (k: string, v: unknown) => vars.set(k, v),
++ };
++ const scope = await new RequestHooks(engine, null, new UnavailableSink(() => {})).beginAttempt(
++ context as never,
++ {
++ claudeRequest: { messages: [{ role: "user", content: "read" }] },
++ route: { modelId: "capture-model", provider: "openai-codex", native: false },
++ model: "capture-model",
++ stream: true,
++ }
++ );
++ const result = await collectSseMessage(
++ await applyResponseSeam(translated(zero()), scope),
+ "capture-model"
+ );
+ expect(observed.map((s) => JSON.parse(s))).toEqual(
+ realCalls().map((e) => JSON.parse(e.item.arguments))
+ );
+ expect(result.content.filter((c) => c.type === "tool_use").map((c) => c.input)).toEqual(
+ realCalls().map((e) => JSON.parse(e.item.arguments))
+ );
+ expect(result.stop_reason).toBe("tool_use");
+ });
+});
+
+describe("REQ-6 Responses incremental argument compatibility", () => {
+ test("REQ-6 TEST-4 preserves many deltas per Codex call without resending final arguments", async () => {
+ // Derived from V0-1 final arguments and native toolsonly-turn1's real delta event envelope.
+ const template = capture("gpt-5.6-sol-responses-toolsonly-turn1.sse").find(
+ (e) => e.type === "response.function_call_arguments.delta"
+ );
+ const source = zero();
+ const derived = source.flatMap((e) => {
+ if (e.type !== "response.function_call_arguments.done") return [e];
+ const split = Math.floor(e.arguments.length / 2);
+ return [
+ {
+ ...template,
+ item_id: e.item_id,
+ output_index: e.output_index,
+ delta: e.arguments.slice(0, split),
+ },
+ {
+ ...template,
+ item_id: e.item_id,
+ output_index: e.output_index,
+ delta: e.arguments.slice(split),
+ },
+ e,
+ ];
+ });
+ const calls = toolArguments(await folded(translated(derived)));
+ expect(calls.map((c) => c.deltas.length)).toEqual([2, 2, 2]);
+ expect(calls.map((c) => c.args)).toEqual(realCalls().map((e) => JSON.parse(e.item.arguments)));
+ });
+
+ test("REQ-6 TEST-4 native one-delta plus done never duplicates arguments", async () => {
+ const source = capture("gpt-5.6-sol-responses-toolsonly-turn1.sse");
+ const calls = toolArguments(await folded(translated(source)));
+ expect(calls.map((c) => c.deltas.length)).toEqual([1, 1, 1]);
+ expect(calls.map((c) => c.args)).toEqual([
+ { path: "a.ts" },
+ { path: "b.ts" },
+ { path: "c.ts" },
+ ]);
+ });
+
+ test("REQ-6 TEST-5 emits only the missing suffix when final arguments extend a real delta", async () => {
+ // Derived from native one-delta capture: shorten each actual delta, retain original final arguments.
+ const source = capture("gpt-5.6-sol-responses-toolsonly-turn1.sse");
+ for (const e of source)
+ if (e.type === "response.function_call_arguments.delta") e.delta = e.delta.slice(0, 6);
+ const calls = toolArguments(await folded(translated(source)));
+ expect(calls.map((c) => c.args)).toEqual([
+ { path: "a.ts" },
+ { path: "b.ts" },
+ { path: "c.ts" },
+ ]);
+ expect(calls.map((c) => c.deltas.length)).toEqual([2, 2, 2]);
+ });
+
+ test("REQ-6 TEST-5 does not append divergent final bytes to streamed arguments", async () => {
+ // Derived from native capture: real first-call finals are replaced with real second-call finals.
+ const source = capture("gpt-5.6-sol-responses-toolsonly-turn1.sse");
+ const dones = source.filter((e) => e.type === "response.function_call_arguments.done");
+ dones[0].arguments = dones[1].arguments;
+ source.find((e) => e.type === "response.output_item.done").item.arguments = dones[1].arguments;
+ const calls = toolArguments(await folded(translated(source)));
+ expect(calls.map((c) => c.args)).toEqual([
+ { path: "a.ts" },
+ { path: "b.ts" },
+ { path: "c.ts" },
+ ]);
+ expect(calls.map((c) => c.deltas.length)).toEqual([1, 1, 1]);
+ });
+});
diff --cc packages/cli/src/handlers/shared/stream-parsers/responses/responses-leg.ts
index a2054bc7,00000000..be50e779
mode 100644,000000..100644
--- a/packages/cli/src/handlers/shared/stream-parsers/responses/responses-leg.ts
+++ b/packages/cli/src/handlers/shared/stream-parsers/responses/responses-leg.ts
@@@ -1,895 -1,0 +1,848 @@@
+/**
+ * One upstream Responses body → Claude SSE events (through the sink) → one
+ * LegOutcome.
+ *
+ * A LEG is one upstream HTTP response. A turn (one downstream Claude message,
+ * `responses-turn.ts`) has one leg, or more when the driver retries a stalled or
+ * degenerate leg. Everything here is per leg and discarded when the leg ends:
+ * function-call accumulators, this leg's open blocks, pending reasoning, the
+ * incomplete reason, held `parallel` wrappers and usage. Block indices,
+ * message lifecycle and tool block states belong to the turn and live on the
+ * sink.
+ *
+ * Every leg closes the blocks it opened before it returns, so the driver
+ * always starts the next leg, or writes the ending, from a clean slate. How
+ * the MESSAGE ends is the driver's decision, never the leg's.
+ *
+ * The Responses API events handled:
+ * response.output_text.delta → content text
+ * response.output_item.added → new item (function_call, reasoning)
+ * response.function_call_arguments.delta / .done → tool arguments
+ * response.reasoning_summary_text.delta / reasoning_text.delta → thinking output
+ * response.output_item.done → close tool_use block
+ * response.completed / response.done / response.incomplete → final usage
+ * error / response.failed → in-stream API error
+ */
+
+import {
+ type CachedReasoningItem,
+ rememberReasoningForCall,
+} from "../../../../adapters/reasoning-cache.js";
+import type { ResponsesItem } from "../../../../code-mode/types.js";
++import type { RawStreamTap } from "../../../../hooks/raw.js";
+import { getLogLevel, log } from "../../../../logger.js";
+import type { UsageCacheDetail } from "../../token-tracker.js";
+import { formatRawSseLogPayload } from "../openai-sse.js";
+import { sseDataPayload } from "../sse-line.js";
+import type { ClaudeSseSink } from "./claude-sse-sink.js";
+import {
+ type ParallelWrapperCall,
+ isParallelWrapperName,
+ parseParallelWrapper,
+} from "./parallel-wrapper.js";
+import {
+ type StallClock,
+ StallGuard,
+ isOutputBearingEvent,
+ systemStallClock,
+} from "./stall-guard.js";
+
+/** One leg's usage, read from `response.completed` / `.incomplete`. */
+export interface Usage {
+ inputTokens: number;
+ outputTokens: number;
+ /** From `input_tokens_details.cached_tokens` when the backend reports it. */
+ cacheDetail?: UsageCacheDetail;
+}
+
+/**
+ * How long a leg keeps reading after its exec call completed, for the
+ * terminal event's usage (R1: it arrives milliseconds after the exec item).
+ */
+export const EXEC_DRAIN_MS = 10_000;
+
+/** Why a `parallel` wrapper was judged degenerate. */
+export type DegenerateReason = "unparseable" | "shape" | "empty" | "incomplete";
+
+export type LegOutcome =
+ | {
+ kind: "done";
+ usage?: Usage;
+ incomplete?: string;
+ /** Code mode only: this leg's assistant text and reasoning items, in order. */
+ items?: ResponsesItem[];
+ }
+ | {
+ /** Code mode: the leg ended on an exec call (never emitted as a block). */
+ kind: "exec";
+ callId: string;
+ input: string;
+ precedingItems: ResponsesItem[];
+ usage?: Usage;
+ /** `response.incomplete` cut the exec input: it is never run. */
+ truncated: boolean;
+ }
+ | { kind: "stall"; afterMs: number }
+ | {
+ kind: "degenerate-wrapper";
+ bytes: number;
+ reason: DegenerateReason;
+ usage?: Usage;
+ }
+ | { kind: "api-error"; code: string; message: string; usage?: Usage }
+ | {
+ kind: "stream-error";
+ error: unknown;
+ openToolBlock: boolean;
+ /** Code mode: the socket died while the exec input streamed (never a block, never run). */
+ openExec?: boolean;
+ usage?: Usage;
+ }
+ | { kind: "cancelled"; usage?: Usage };
+
+export interface ResponsesLegContext {
+ sink: ClaudeSseSink;
+ modelName: string;
+ toolNameMap?: Map<string, string>;
+ /** Claude Code's own tool names; see isParallelWrapperName. */
+ declaredToolNames: string[];
- // biome-ignore lint/suspicious/noExplicitAny: MiddlewareManager is untyped on every parser
- middlewareManager?: any;
- /** Shared across every chunk hook of the turn; handed to afterStreamComplete. */
- // biome-ignore lint/suspicious/noExplicitAny: middleware metadata is free-form
- streamMetadata: Map<string, any>;
- onToolCall?: (name: string, argsJson: string) => string | null | undefined;
- shouldBufferTool?: (name: string) => boolean;
- onAssistantText?: (text: string, kind?: "text" | "reasoning") => void;
++ /**
++ * The raw-tier tap (`providerChunk`), shared by every leg of the turn. The
++ * Responses API has no `delta` object of its own, so the event stands in for
++ * both. Tool-argument interception is not this parser's job: it happens at
++ * the hook response seam, above every parser.
++ */
++ raw?: RawStreamTap | null;
+ /**
+ * This leg's stall guard (stall-guard.ts): fires `thresholdMs` after
+ * `headersAt` (this leg's response headers, on `clock`) unless an
+ * output-bearing event arrived first. Absent or 0 ⇒ unarmed.
+ */
+ stall?: { thresholdMs: number; headersAt: number; clock?: StallClock };
+ /**
+ * Code mode is on for this turn: a `custom_tool_call` named `exec` is held
+ * (never a block) and ends the leg as an `exec` outcome. Off ⇒ such items are
+ * ignored, exactly as before code mode existed.
+ */
+ codeMode?: boolean;
+ /** The clock of the EXEC_DRAIN_MS drain; tests inject a fake one. Default wall clock. */
+ drainClock?: StallClock;
+}
+
+/** A held exec call (code mode). */
+type HeldExec = {
+ callId: string;
+ itemId?: string;
+ acc: string;
+ doneInput?: string;
+ /** Set at `output_item.done`: the input is whole. */
+ final?: string;
+};
+
+type FnCall = {
+ name: string;
+ arguments: string;
+ index: number;
+ claudeId?: string;
- /** Withhold input_json_delta until the call completes so it can be repaired. */
- buffered?: boolean;
+ /**
+ * Bytes of `arguments` already sent downstream as `input_json_delta`. Zero
- * for a buffered call until it completes, and zero for every call of a Codex
- * multi-call turn, which streams no argument deltas at all.
++ * for every call of a Codex multi-call turn, which streams no argument
++ * deltas at all.
+ */
+ forwardedBytes: number;
+ /** `response.function_call_arguments.done`'s complete argument string. */
+ doneArgs?: string;
+};
+
+/**
+ * A `parallel` wrapper call being accumulated without a content_block_start
+ * (see parallel-wrapper.ts).
+ */
+type HeldWrapper = {
+ claudeBaseId: string;
+ arguments: string;
+ doneArgs?: string;
+ /** The reasoning that led to the wrapper, bound to its first expanded call only. */
+ reasoning: CachedReasoningItem[];
+};
+
+/** Internal: a leg-ending decision reached inside the event dispatch. */
+type Stop = { stop: LegOutcome };
+
+// biome-ignore lint/suspicious/noExplicitAny: Responses events are untyped JSON
+type ResponsesEvent = any;
+
+/** Read `usage` from a Responses usage object; undefined when it carries none. */
+function readUsage(raw: ResponsesEvent, prior?: Usage, keepPrior = false): Usage | undefined {
+ if (!raw || typeof raw !== "object") return undefined;
+ const input = raw.input_tokens || (keepPrior ? (prior?.inputTokens ?? 0) : 0);
+ const output = raw.output_tokens || (keepPrior ? (prior?.outputTokens ?? 0) : 0);
+ const cached = raw.input_tokens_details?.cached_tokens;
+ const usage: Usage = { inputTokens: input, outputTokens: output };
+ if (typeof cached === "number" && cached > 0) {
+ usage.cacheDetail = { cacheReadTokens: cached, cacheCreationTokens: 0 };
+ }
+ return usage;
+}
+
+class ResponsesLeg {
+ private textIdx = -1;
+ private reasoningIdx = -1;
+ // OpenAI splits a reasoning summary into parts (summary_index 0, 1, 2, …),
+ // each a bolded section. The paragraph break between parts is structural —
+ // it is NOT in the text deltas — so tracking the index lets us re-insert it,
+ // otherwise "**A**" + "**B**" render as one smashed "**A****B**".
+ private lastSummaryIndex = -1;
+ // Set when OpenAI reports the response was cut short (response.incomplete).
+ private incompleteReason: string | null = null;
+ // Reasoning items seen since the last function call. OpenAI emits them just
+ // before the call they informed; we hand them to the cache keyed by that call
+ // so the next request can replay them (see reasoning-cache.ts).
+ private pendingReasoning: CachedReasoningItem[] = [];
+ private usage: Usage | undefined;
+ // Keyed by BOTH call_id and item_id, so the same FnCall object appears under
+ // two keys — never derive a count from this map's size.
+ private readonly functionCalls = new Map<string, FnCall>();
+ // Tool blocks that have been started but not yet stopped, in emission order.
+ private readonly openToolBlocks = new Set<FnCall>();
+ private readonly heldWrappers = new Map<string, HeldWrapper>();
+ // Code mode only: the held exec call, and this leg's assistant text and
+ // reasoning items in order (an exec's precedingItems; a turn record's items).
+ private heldExec: HeldExec | undefined;
+ private readonly items: ResponsesItem[] = [];
+ private drainTimer: unknown;
+ /** A degenerate wrapper held until the terminal event (`holdDegenerate`). */
+ private heldDegenerate: { reason: DegenerateReason; bytes: number } | undefined;
+ private cancelReader: (() => void) | undefined;
+
+ constructor(private readonly ctx: ResponsesLegContext) {}
+
+ /** The exec outcome for a held exec whose input is whole. */
+ private execOutcome(truncated: boolean): LegOutcome {
+ const held = this.heldExec as HeldExec;
+ return {
+ kind: "exec",
+ callId: held.callId,
+ input: held.final ?? held.doneInput ?? held.acc,
+ precedingItems: [...this.items],
+ usage: this.usage,
+ truncated,
+ };
+ }
+
+ /**
+ * The leg's outcome is decided (a whole exec call, a degenerate wrapper):
+ * keep reading only for the terminal event's usage, at most EXEC_DRAIN_MS.
+ */
+ private startDrain(what: string): void {
+ if (this.drainTimer !== undefined) return;
+ this.drainTimer = this.drainClock.setTimeout(() => {
+ log(`[ResponsesSSE] no terminal event ${EXEC_DRAIN_MS} ms after the ${what}; using it`);
+ this.cancelReader?.();
+ }, EXEC_DRAIN_MS);
+ }
+
+ /**
+ * A wrapper judged degenerate at its `output_item.done`: never emitted, and
+ * the leg ends degenerate — but only after the terminal event, which carries
+ * the usage the provider billed (V0-21.sse: `response.incomplete` six lines
+ * after the wrapper, 39,429 input tokens that an immediate stop discarded).
+ */
+ private holdDegenerate(reason: DegenerateReason, bytes: number): undefined {
+ log(
+ `[ResponsesSSE] degenerate parallel wrapper (${reason}, ${bytes} bytes); draining for usage`
+ );
+ this.heldDegenerate = { reason, bytes };
+ this.startDrain("degenerate wrapper");
+ return undefined;
+ }
+
+ /** The held degenerate wrapper is the leg's outcome (the body ended, or the drain gave up). */
+ private endHeldDegenerate(): LegOutcome {
+ const held = this.heldDegenerate as { reason: DegenerateReason; bytes: number };
+ this.closeAll();
+ return this.degenerate(held.reason, held.bytes);
+ }
+
+ /** While a degenerate wrapper is held: only the terminal event (and its usage) matters. */
+ private drainDegenerate(event: ResponsesEvent): Stop | undefined {
+ const held = this.heldDegenerate as { reason: DegenerateReason; bytes: number };
+ switch (event.type) {
+ case "response.completed":
+ case "response.done":
+ this.usage = readUsage(event.response?.usage ?? event.usage) ?? this.usage;
+ break;
+ case "response.incomplete":
+ if (event.response?.usage) this.usage = readUsage(event.response.usage, this.usage, true);
+ break;
+ case "error":
+ case "response.failed":
+ break;
+ default:
+ return undefined;
+ }
+ return { stop: this.degenerate(held.reason, held.bytes) };
+ }
+
+ private get drainClock(): StallClock {
+ return this.ctx.drainClock ?? systemStallClock;
+ }
+
+ private get sink(): ClaudeSseSink {
+ return this.ctx.sink;
+ }
+
+ private decodeToolName(name: string): string {
+ return this.ctx.toolNameMap?.get(name) || name;
+ }
+
+ async run(response: Response): Promise<LegOutcome> {
+ const reader = response.body?.getReader();
+ if (!reader) {
+ return { kind: "stream-error", error: new Error("No response body"), openToolBlock: false };
+ }
+ const signal = this.sink.signal;
+ const onAbort = () => {
+ reader.cancel().catch(() => {});
+ };
+ this.cancelReader = () => {
+ reader.cancel().catch(() => {});
+ };
+ if (signal.aborted) onAbort();
+ else signal.addEventListener("abort", onAbort, { once: true });
+
+ // A fired guard cancels the reader; the pending read then settles and the
+ // leg reports `stall` instead of how the cut-short stream looked.
+ let stalledAfterMs: number | undefined;
+ const stall = this.ctx.stall;
+ const guard =
+ stall && stall.thresholdMs > 0
+ ? new StallGuard(
+ stall.thresholdMs,
+ stall.headersAt,
+ (afterMs) => {
+ stalledAfterMs = afterMs;
+ log(`[ResponsesTurn] no output item ${Math.round(afterMs / 1000)}s after headers`);
+ reader.cancel().catch(() => {});
+ },
+ stall.clock
+ )
+ : undefined;
+ const stalled = (): LegOutcome | undefined => {
+ if (stalledAfterMs === undefined || signal.aborted) return undefined;
+ this.closeAll();
+ return { kind: "stall", afterMs: stalledAfterMs };
+ };
+
+ const decoder = new TextDecoder();
+ let buffer = "";
+ try {
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ this.sink.touch();
+
+ buffer += decoder.decode(value, { stream: true });
+ const lines = buffer.split("\n");
+ buffer = lines.pop() || "";
+
+ for (const line of lines) {
+ const data = sseDataPayload(line);
+ if (data === null || data === "[DONE]") continue;
+ // Raw capture, greppable into test data — same contract as
+ // [SSE:openai] / [SSE:anthropic] in the sibling parsers.
+ if (getLogLevel() === "debug") {
+ log(`[SSE:responses] ${formatRawSseLogPayload(data)}`);
+ }
- // A malformed frame, or a handler or middleware that throws on one
++ // A malformed frame, or a handler or raw hook that throws on one
+ // event, costs that event only, never the turn.
+ let stop: Stop | undefined;
+ try {
+ const event = JSON.parse(data);
+ if (guard?.armed && isOutputBearingEvent(event?.type)) guard.disarm();
+ stop = await this.dispatch(event);
+ } catch (parseError) {
+ log(`[ResponsesSSE] Parse error: ${parseError}`);
+ continue;
+ }
+ if (stop) {
+ this.closeAll();
+ // Awaited: the next leg is never issued while this stream is open.
+ await reader.cancel().catch(() => {});
+ return stop.stop;
+ }
+ }
+ }
+ } catch (error) {
+ if (signal.aborted) return { kind: "cancelled", usage: this.usage };
+ const stalledOutcome = stalled();
+ if (stalledOutcome) return stalledOutcome;
+ if (this.heldExec?.final !== undefined) {
+ // The exec call was whole before the socket died: run it.
+ this.closeAll();
+ return this.execOutcome(false);
+ }
+ // The wrapper was already judged; the drain only waited for usage.
+ if (this.heldDegenerate) return this.endHeldDegenerate();
+ log(`[ResponsesSSE] Stream error: ${error}`);
+ this.closeReasoning();
+ this.closeText();
+ // A tool block still open here had its argument JSON cut mid-object: the
+ // socket died between `output_item.added` and `output_item.done`. Its
+ // content_block_start is already on the wire, so how the turn ENDS decides
+ // what the client does with the fragment (see the driver).
+ const openToolBlock = this.openToolBlocks.size > 0;
+ this.closeTools();
+ return {
+ kind: "stream-error",
+ error,
+ openToolBlock,
+ ...(this.heldExec ? { openExec: true } : {}),
+ usage: this.usage,
+ };
+ } finally {
+ guard?.disarm();
+ signal.removeEventListener("abort", onAbort);
+ if (this.drainTimer !== undefined) this.drainClock.clearTimeout(this.drainTimer);
+ }
+
+ if (signal.aborted) return { kind: "cancelled", usage: this.usage };
+ return stalled() ?? this.endOfBody();
+ }
+
+ /** The body ended without a stop: how the leg ended. */
+ private endOfBody(): LegOutcome {
+ if (this.heldDegenerate) return this.endHeldDegenerate();
+ if (this.heldExec) {
+ this.closeAll();
+ if (this.heldExec.final !== undefined) return this.execOutcome(false);
+ // The body ended inside the exec call: nothing whole to run.
+ log("[ResponsesSSE] stream ended inside the exec call");
+ return {
+ kind: "stream-error",
+ error: new Error("the stream ended inside the exec call"),
+ openToolBlock: false,
+ openExec: true,
+ usage: this.usage,
+ };
+ }
+
+ // The stream ended while a wrapper was still held: its arguments were never
+ // completed, so there is nothing valid to expand.
+ const unfinished = this.heldWrappers.values().next().value;
+ if (unfinished) {
+ this.closeAll();
+ return this.degenerate("incomplete", (unfinished.doneArgs ?? unfinished.arguments).length);
+ }
+
+ this.closeAll();
+ return {
+ kind: "done",
+ usage: this.usage,
+ ...(this.incompleteReason ? { incomplete: this.incompleteReason } : {}),
+ ...(this.ctx.codeMode ? { items: [...this.items] } : {}),
+ };
+ }
+
+ private degenerate(reason: DegenerateReason, bytes: number): LegOutcome {
+ log(`[ResponsesSSE] degenerate parallel wrapper (${reason}, ${bytes} bytes)`);
+ return { kind: "degenerate-wrapper", reason, bytes, usage: this.usage };
+ }
+
- private async dispatch(event: ResponsesEvent): Promise<Stop | undefined> {
- // Response-side observation point. The Responses API has no `delta`
- // object of its own, so the event stands in for both — observers here key
- // off `event.type`.
- if (this.ctx.middlewareManager) {
- await this.ctx.middlewareManager.afterStreamChunk({
- modelId: this.ctx.modelName,
- chunk: event,
- delta: event,
- metadata: this.ctx.streamMetadata,
- });
- }
++ private async dispatch(parsed: ResponsesEvent): Promise<Stop | undefined> {
++ // Raw-tier tap, before anything reads the event: what it returns is the
++ // committed object, and every read below is of it. The Responses API has
++ // no `delta` object of its own, so the event stands in for both.
++ const event = this.ctx.raw ? this.ctx.raw.chunk(parsed, (e: ResponsesEvent) => e) : parsed;
+ if (getLogLevel() === "debug" && event.type) {
+ log(`[ResponsesSSE] Event: ${event.type}`);
+ }
+ if (this.heldDegenerate) return this.drainDegenerate(event);
+
+ switch (event.type) {
+ case "response.output_text.delta":
+ this.onTextDelta(event);
+ return undefined;
+ case "response.output_item.added":
+ this.onItemAdded(event);
+ return undefined;
+ case "response.reasoning_summary_text.delta":
+ // The RAW reasoning text (DashScope, open-weight models) rather than a
+ // summary of it; a thinking block all the same.
+ case "response.reasoning_text.delta":
+ this.onReasoningDelta(event);
+ return undefined;
+ case "response.function_call_arguments.delta":
+ this.onArgumentsDelta(event);
+ return undefined;
+ case "response.function_call_arguments.done":
+ this.onArgumentsDone(event);
+ return undefined;
+ case "response.custom_tool_call_input.delta":
+ case "response.custom_tool_call_input.done":
+ this.onExecInput(event);
+ return undefined;
+ case "response.output_item.done":
+ return this.onItemDone(event);
+ case "response.incomplete":
+ return this.onIncomplete(event);
+ case "response.completed":
+ case "response.done":
+ this.usage = readUsage(event.response?.usage ?? event.usage) ?? this.usage;
+ // A whole exec call needs nothing after the terminal event's usage.
+ if (this.heldExec?.final !== undefined) return { stop: this.execOutcome(false) };
+ return undefined;
+ case "error":
+ case "response.failed": {
+ const err = event.error || event.response?.error || {};
+ const message = err.message || event.message || "Unknown API error";
+ const code = err.code || event.code || "";
+ log(`[ResponsesSSE] API error: ${code} - ${message}`);
+ return { stop: { kind: "api-error", code, message, usage: this.usage } };
+ }
+ default:
+ return undefined;
+ }
+ }
+
+ private onTextDelta(event: ResponsesEvent): void {
- this.ctx.onAssistantText?.(event.delta ?? "", "text");
+ this.closeReasoning();
+ if (this.textIdx < 0) {
+ this.textIdx = this.sink.nextIndex();
+ this.sink.startBlock(this.textIdx, { type: "text", text: "" });
+ }
+ this.sink.delta(this.textIdx, { type: "text_delta", text: event.delta || "" });
+ }
+
+ /** Code mode: the held exec's streamed input (`.delta`) or its whole input (`.done`). */
+ private onExecInput(event: ResponsesEvent): void {
+ const held = this.heldExec;
+ if (!held) return;
+ const id = event.item_id ?? event.call_id;
+ if (id !== undefined && id !== held.itemId && id !== held.callId) return;
+ if (event.type === "response.custom_tool_call_input.delta") held.acc += event.delta || "";
+ else if (typeof event.input === "string") held.doneInput = event.input;
+ }
+
+ /** Code mode: the held exec's `output_item.done` makes its input whole; other items are recorded. */
+ private onCodeModeItemDone(item: ResponsesEvent): boolean {
+ if (item?.type !== "custom_tool_call") {
+ this.recordItem(item);
+ return false;
+ }
+ const held = this.heldExec;
+ if (held && (item.call_id === held.callId || item.id === held.itemId)) {
+ const itemInput = typeof item.input === "string" ? item.input : undefined;
+ held.final = held.doneInput ?? itemInput ?? held.acc;
+ this.startDrain("exec call");
+ }
+ return true;
+ }
+
+ /** Code mode: hold the exec call. The text and reasoning before it are closed, never reopened. */
+ private onCustomToolCallAdded(item: ResponsesEvent): void {
+ if (item.name !== "exec" || this.heldExec) {
+ log(`[ResponsesSSE] ignoring custom_tool_call ${item.name ?? ""} (not the exec call)`);
+ return;
+ }
+ this.closeReasoning();
+ this.closeText();
+ this.heldExec = {
+ callId: item.call_id || item.id,
+ itemId: item.id,
+ acc: typeof item.input === "string" ? item.input : "",
+ };
+ log(`[ResponsesSSE] holding exec call ${this.heldExec.callId}`);
+ }
+
+ /** Code mode: an assistant message or reasoning item, kept verbatim for the turn's items. */
+ private recordItem(item: ResponsesEvent): void {
+ if (item?.type === "message" && item.role === "assistant" && Array.isArray(item.content)) {
+ const content = item.content
+ .filter((p: ResponsesEvent) => p?.type === "output_text" && typeof p.text === "string")
+ .map((p: ResponsesEvent) => ({ type: "output_text", text: p.text }));
+ if (content.length === 0) return;
+ const message: ResponsesItem = { type: "message", role: "assistant", content };
+ if (typeof item.phase === "string") message.phase = item.phase;
+ this.items.push(message);
+ } else if (item?.type === "reasoning" && item.encrypted_content) {
+ this.items.push({
+ type: "reasoning",
+ content: item.content ?? [],
+ encrypted_content: item.encrypted_content,
+ summary: item.summary ?? [],
+ });
+ }
+ }
+
+ private onItemAdded(event: ResponsesEvent): void {
+ if (this.ctx.codeMode && event.item?.type === "custom_tool_call") {
+ this.onCustomToolCallAdded(event.item);
+ return;
+ }
+ if (event.item?.type !== "function_call") return;
+ const itemId = event.item.id;
+ const openaiCallId = event.item.call_id || itemId;
+ const callId = openaiCallId.startsWith("toolu_")
+ ? openaiCallId
+ : `toolu_${openaiCallId.replace(/^fc_/, "")}`;
+ const rawFnName = event.item.name || "";
+ const fnName = this.decodeToolName(rawFnName);
+
+ if (isParallelWrapperName(fnName, this.ctx.declaredToolNames)) {
+ // HOLD: no content_block_start until the arguments are judged. The
+ // reasoning so far belongs to the wrapper, not to a later call.
+ const held: HeldWrapper = {
+ claudeBaseId: callId,
+ arguments: "",
+ reasoning: this.pendingReasoning,
+ };
+ this.pendingReasoning = [];
+ this.heldWrappers.set(openaiCallId, held);
+ if (itemId && itemId !== openaiCallId) this.heldWrappers.set(itemId, held);
+ log(`[ResponsesSSE] holding parallel wrapper ${rawFnName}`);
+ return;
+ }
+
+ this.closeReasoning();
+ this.closeText();
+
+ const fnCall: FnCall = {
+ name: fnName,
+ arguments: "",
+ index: this.sink.nextIndex(),
+ claudeId: callId,
- buffered: this.ctx.shouldBufferTool?.(fnName) === true,
+ forwardedBytes: 0,
+ };
+ this.functionCalls.set(openaiCallId, fnCall);
+ if (itemId && itemId !== openaiCallId) this.functionCalls.set(itemId, fnCall);
+ this.openToolBlocks.add(fnCall);
+
+ // Bind the reasoning that led to this call, keyed by the id the client
+ // will echo back, so the next request can replay it.
+ if (this.pendingReasoning.length > 0) {
+ rememberReasoningForCall(callId, this.pendingReasoning);
+ this.pendingReasoning = [];
+ }
+
+ this.sink.startToolBlock(fnCall.index, callId, fnName);
+ }
+
+ private onReasoningDelta(event: ResponsesEvent): void {
- this.ctx.onAssistantText?.(event.delta ?? "", "reasoning");
+ // Reasoning is the model's chain of thought, not its answer — it belongs
+ // in a thinking block, or Claude Code renders it as the reply.
+ const summaryIndex =
+ typeof event.summary_index === "number"
+ ? event.summary_index
+ : typeof event.content_index === "number"
+ ? event.content_index
+ : 0;
+ if (this.reasoningIdx < 0) {
+ this.closeText();
+ this.reasoningIdx = this.sink.nextIndex();
+ this.lastSummaryIndex = summaryIndex;
+ this.sink.startBlock(this.reasoningIdx, { type: "thinking", thinking: "" });
+ } else if (summaryIndex !== this.lastSummaryIndex) {
+ // New summary section — restore the paragraph break OpenAI represents
+ // structurally rather than in the text stream.
+ this.lastSummaryIndex = summaryIndex;
+ this.sink.delta(this.reasoningIdx, { type: "thinking_delta", thinking: "\n\n" });
+ }
+ this.sink.delta(this.reasoningIdx, { type: "thinking_delta", thinking: event.delta || "" });
+ }
+
+ private onArgumentsDelta(event: ResponsesEvent): void {
+ const callId = event.call_id || event.item_id;
+ const fnCall = this.functionCalls.get(callId);
+ if (!fnCall) {
+ const held = this.heldWrappers.get(callId);
+ if (held) held.arguments += event.delta || "";
+ return;
+ }
+ fnCall.arguments += event.delta || "";
- // Buffered calls emit nothing here — the whole argument object goes out in
- // one delta at output_item.done, after any repair.
- if (!fnCall.buffered) {
- this.sink.delta(fnCall.index, { type: "input_json_delta", partial_json: event.delta || "" });
- fnCall.forwardedBytes += (event.delta || "").length;
- }
++ this.sink.delta(fnCall.index, { type: "input_json_delta", partial_json: event.delta || "" });
++ fnCall.forwardedBytes += (event.delta || "").length;
+ }
+
+ private onArgumentsDone(event: ResponsesEvent): void {
+ // The complete argument string. The Codex backend sends a multi-call turn
+ // with NO argument deltas, so for those calls this (or the item at
+ // output_item.done) is the only copy of the arguments.
+ if (typeof event.arguments !== "string") return;
+ const fnCall = this.functionCalls.get(event.call_id) || this.functionCalls.get(event.item_id);
+ if (fnCall) {
+ fnCall.doneArgs = event.arguments;
+ return;
+ }
+ const held = this.heldWrappers.get(event.call_id) || this.heldWrappers.get(event.item_id);
+ if (held) held.doneArgs = event.arguments;
+ }
+
+ private onItemDone(event: ResponsesEvent): Stop | undefined {
+ const item = event.item;
+ if (item?.type === "reasoning" && item.encrypted_content) {
+ // Keep the item verbatim (minus the id, which the Responses API does not
+ // require on replay and which buildPayload strips).
+ this.pendingReasoning.push({
+ type: "reasoning",
+ content: item.content ?? [],
+ encrypted_content: item.encrypted_content,
+ summary: item.summary ?? [],
+ });
+ }
+ if (this.ctx.codeMode && this.onCodeModeItemDone(item)) return undefined;
+ if (item?.type !== "function_call") return undefined;
+
+ const callId = item.call_id || item.id;
+ const itemArgs = typeof item.arguments === "string" ? item.arguments : undefined;
+
+ const held = this.heldWrappers.get(callId) || this.heldWrappers.get(item.id);
+ if (held) {
+ this.heldWrappers.delete(callId);
+ this.heldWrappers.delete(item.id);
+ const final = held.doneArgs ?? itemArgs ?? held.arguments;
+ const parsed = parseParallelWrapper(final, (n) => this.decodeToolName(n));
+ if (!parsed.ok) return this.holdDegenerate(parsed.reason, final.length);
+ this.emitExpandedWrapper(held, parsed.calls);
+ return undefined;
+ }
+
+ const fnCall = this.functionCalls.get(callId) || this.functionCalls.get(item.id);
+ if (!fnCall || !this.openToolBlocks.has(fnCall)) return undefined;
+ const final = fnCall.doneArgs ?? itemArgs ?? fnCall.arguments;
- if (fnCall.buffered) {
- // Give the behavior layer its one chance to rewrite the call, then emit
- // the complete argument object as a single delta.
- const finalArgs = this.repairBufferedCall(fnCall.name, final);
- this.sink.delta(fnCall.index, { type: "input_json_delta", partial_json: finalArgs });
- fnCall.forwardedBytes = finalArgs.length;
- } else {
- this.emitUnforwardedArguments(fnCall, final, fnCall.doneArgs !== undefined ? "done" : "item");
- }
++ this.emitUnforwardedArguments(fnCall, final, fnCall.doneArgs !== undefined ? "done" : "item");
+ this.sink.markToolArgsComplete(fnCall.index);
+ this.sink.stopToolBlock(fnCall.index);
+ this.openToolBlocks.delete(fnCall);
+ return undefined;
+ }
+
+ private onIncomplete(event: ResponsesEvent): Stop | undefined {
+ // The reason lives at response.incomplete_details.reason — reading
+ // event.reason always yielded "unknown".
+ this.incompleteReason = event.response?.incomplete_details?.reason ?? event.reason ?? "unknown";
+ log(`[ResponsesSSE] Response incomplete: ${this.incompleteReason}`);
+ if (event.response?.usage) {
+ this.usage = readUsage(event.response.usage, this.usage, true);
+ }
+ // Code mode: an exec whose input was still streaming is cut, and never run.
+ if (this.heldExec) {
+ const truncated = this.heldExec.final === undefined;
+ if (truncated) log("[ResponsesSSE] exec input cut by response.incomplete; not run");
+ return { stop: this.execOutcome(truncated) };
+ }
+ // A wrapper still held when the response is cut short never got its
+ // arguments judged: degenerate by definition.
+ const pending = this.heldWrappers.values().next().value;
+ if (pending) {
+ return {
+ stop: this.degenerate("incomplete", (pending.doneArgs ?? pending.arguments).length),
+ };
+ }
+ return undefined;
+ }
+
- /** The behavior layer's one chance to rewrite a buffered call. A throwing rule changes nothing. */
- private repairBufferedCall(name: string, args: string): string {
- if (this.ctx.shouldBufferTool?.(name) !== true) return args;
- try {
- const repaired = this.ctx.onToolCall?.(name, args);
- if (typeof repaired === "string" && repaired !== args) {
- log(`[ResponsesSSE] tool call repaired: ${name}`);
- return repaired;
- }
- } catch (err) {
- // A failing rule must never corrupt the stream — emit the model's
- // original arguments and carry on.
- log(`[ResponsesSSE] onToolCall threw for ${name}: ${err}`);
- }
- return args;
- }
-
+ /**
+ * Emit a valid wrapper's entries as ordinary tool_use blocks, one complete
- * argument delta each (a buffered tool goes through onToolCall first). The
++ * argument delta each. The
+ * wrapper's reasoning is remembered under the FIRST expanded id only, so the
+ * next request replays it exactly once, before that call.
+ */
+ private emitExpandedWrapper(held: HeldWrapper, calls: ParallelWrapperCall[]): void {
+ this.closeReasoning();
+ this.closeText();
+ calls.forEach((call, k) => {
+ const id = `${held.claudeBaseId}_p${k}`;
- const args = this.repairBufferedCall(call.name, call.arguments);
++ const args = call.arguments;
+ const index = this.sink.nextIndex();
+ this.sink.startToolBlock(index, id, call.name);
+ this.sink.delta(index, { type: "input_json_delta", partial_json: args });
+ this.sink.markToolArgsComplete(index);
+ this.sink.stopToolBlock(index);
+ if (k === 0 && held.reasoning.length > 0) {
+ rememberReasoningForCall(id, held.reasoning);
+ }
+ });
+ log(`[ResponsesSSE] parallel wrapper expanded into ${calls.length} tool_use block(s)`);
+ }
+
+ /**
- * At `output_item.done` of a non-buffered call, send whatever part of the
++ * At `output_item.done` of a call, send whatever part of the
+ * final arguments the deltas did not carry. The Codex backend sends every
+ * call of a multi-call turn with ZERO argument deltas: the arguments exist
+ * only in `function_call_arguments.done` and the done item, so forwarding
+ * from deltas alone handed Claude Code `{}` and it answered
+ * `InputValidationError: ... The required parameter 'file_path' is missing`.
+ * A native `openai@` call streams every byte as deltas, and its final string
+ * equals what was forwarded, so nothing more goes out for it.
+ */
+ private emitUnforwardedArguments(fnCall: FnCall, final: string, source: "done" | "item"): void {
+ const emit = (partial: string) => {
+ this.sink.delta(fnCall.index, { type: "input_json_delta", partial_json: partial });
+ fnCall.forwardedBytes += partial.length;
+ };
+ if (fnCall.forwardedBytes === 0) {
+ if (final) {
+ emit(final);
+ log(
+ `[ResponsesSSE] zero-delta function_call ${fnCall.name}: emitted ${final.length} bytes from ${source}`
+ );
+ }
+ return;
+ }
+ const forwarded = fnCall.arguments;
+ if (final === forwarded) return;
+ if (final.startsWith(forwarded)) {
+ const suffix = final.slice(forwarded.length);
+ emit(suffix);
+ log(
+ `[ResponsesSSE] function_call ${fnCall.name}: emitted ${suffix.length}-byte suffix the deltas did not carry`
+ );
+ return;
+ }
+ log(`[ResponsesSSE] done arguments diverge from streamed deltas for ${fnCall.name}`);
+ }
+
+ private closeReasoning(): void {
+ if (this.reasoningIdx >= 0) {
+ this.sink.stopBlock(this.reasoningIdx);
+ this.reasoningIdx = -1;
+ }
+ }
+
+ private closeText(): void {
+ if (this.textIdx >= 0) {
+ this.sink.stopBlock(this.textIdx);
+ this.textIdx = -1;
+ }
+ }
+
+ private closeTools(): void {
+ for (const fnCall of this.openToolBlocks) {
- // A buffered call that never reached output_item.done (truncated or
- // failed stream) still has to emit what it accumulated. Withholding it
- // would turn "partial arguments" into "no arguments", which is strictly
- // worse — the non-buffered path would already have streamed the same
- // fragments. What the client then DOES with malformed JSON is decided by
- // how the turn ends: only an `error` event reliably stops Claude Code
- // executing the fragment. The block stays not-ARGS-COMPLETE on the sink.
- const accumulated = fnCall.doneArgs ?? fnCall.arguments;
- if (fnCall.buffered && accumulated) {
- this.sink.delta(fnCall.index, { type: "input_json_delta", partial_json: accumulated });
- }
++ // A call that never reached output_item.done (truncated or failed
++ // stream) has already streamed its fragments. What the client then DOES
++ // with malformed JSON is decided by how the turn ends: only an `error`
++ // event reliably stops Claude Code executing the fragment. The block
++ // stays not-ARGS-COMPLETE on the sink.
+ this.sink.stopToolBlock(fnCall.index);
+ }
+ this.openToolBlocks.clear();
+ }
+
+ private closeAll(): void {
+ this.closeReasoning();
+ this.closeText();
+ this.closeTools();
+ }
+}
+
+/**
+ * Parse one upstream Responses body into Claude SSE on `ctx.sink` and report
+ * how the leg ended. Never throws; never writes a message ending.
+ */
+export function parseResponsesLeg(
+ response: Response,
+ ctx: ResponsesLegContext
+): Promise<LegOutcome> {
+ return new ResponsesLeg(ctx).run(response);
+}
diff --cc packages/cli/src/handlers/shared/stream-parsers/responses/responses-turn.ts
index ad410b55,00000000..aff6740b
mode 100644,000000..100644
--- a/packages/cli/src/handlers/shared/stream-parsers/responses/responses-turn.ts
+++ b/packages/cli/src/handlers/shared/stream-parsers/responses/responses-turn.ts
@@@ -1,676 -1,0 +1,654 @@@
+/**
+ * The turn driver: one downstream Claude message, built from one or more
+ * upstream Responses legs.
+ *
+ * The leg parser (`responses-leg.ts`) turns one upstream body into Claude SSE
+ * and reports how it ended; this decides how the MESSAGE ends: the stop_reason,
+ * the in-band error text tail, or an SSE `error`, and fires the usage callback
+ * that records the request's stats exactly once.
+ *
+ * ── RETRY WITHIN THE TURN ────────────────────────────────────────────────────
+ *
+ * About 1% of ChatGPT Codex turns end with a degenerate `parallel` wrapper
+ * (parallel-wrapper.ts), usually after a 361-484 s keepalive-only stall. With
+ * `retry.stall` armed (stall-guard.ts), a leg with no output item 150 s after
+ * its headers is cut off too. When the caller passes `retry`, such a leg is retried
+ * by issuing the same body again while the downstream message stays open; the
+ * next leg continues at the next block index. A leg is issued only while no
+ * tool_use has been emitted in this message:
+ *
+ * | state of the message when the trigger fires | action |
+ * |----------------------------------------------------|---------------------------|
+ * | message_start + pings, or closed text/thinking only | retry |
+ * | ≥ 1 tool_use stopped with its arguments, none cut | no retry: end `tool_use` |
+ * | off (re-emitting could run a side-effecting Bash | for the stopped calls |
+ * | twice) | |
+ * | any tool_use started but cut off | no retry: SSE `error` |
+ * | retries exhausted | SSE `error` |
+ *
+ * NOT done in 7b (the status is already flushed), NOT in FallbackHandler (a
+ * model fault must never move a subscription user onto a metered hop), NOT in
+ * the transport. After the flush every failure ends with an SSE `error`.
+ *
+ * ── CODE MODE (`openai-codex`, `codeMode` hooks present) ─────────────────────
+ *
+ * A leg can end on an exec call (never emitted as a block). The hooks run the
+ * script and answer with one of two steps:
+ * - emit-tool-uses: the script blocked on nested tool calls → each becomes a
+ * whole tool_use block, the turn's Responses items are stored, and the
+ * message ends `tool_use` (Claude Code runs them; the next request resumes
+ * the script);
+ * - continue: the script finished without blocking → another leg whose body
+ * is the previous leg's body with this leg's items and the exec call +
+ * output appended to `input`.
+ * Bounded by MAX_LEGS_PER_TURN. A retry inside a code-mode turn re-sends the
+ * CURRENT leg's body, not the first one.
+ */
+
+import {
+ type CodeModeTurnHooks,
+ type ExecTurnStep,
+ type ResponsesItem,
+ relayNestedInput,
+} from "../../../../code-mode/types.js";
+import { log } from "../../../../logger.js";
+import type { LegResponse } from "../../responses-leg-issuer.js";
+import type { UsageCacheDetail } from "../../token-tracker.js";
+import type { ClaudeSseSink } from "./claude-sse-sink.js";
+import {
+ type LegOutcome,
+ type ResponsesLegContext,
+ type Usage,
+ parseResponsesLeg,
+} from "./responses-leg.js";
+import { type StallClock, type StallPolicy, systemStallClock } from "./stall-guard.js";
+
+/** Retries per leg position: 3 attempts in all. */
+export const MAX_LEG_RETRIES = 2;
+
+/**
+ * Code mode: upstream legs one downstream message may use — continuations
+ * after an exec that did not block AND retries. It also bounds the execs
+ * answered inside one message, since each of those adds a leg. Reaching it
+ * ends the message with {@link CODE_MODE_STOP_TEXT}.
+ */
+export const MAX_LEGS_PER_TURN = 6;
+export const CODE_MODE_STOP_TEXT = `\n\n[claudish: stopped after ${MAX_LEGS_PER_TURN} upstream requests in one code-mode turn]`;
+
+type RetryDecision =
+ | { action: "finish" }
+ | { action: "retry" }
+ | { action: "end-tool-use" }
+ | { action: "stop-attempts" }
+ | { action: "error"; message: string };
+
+/** The next leg's response, or undefined when the turn has ended instead. */
+type NextLeg = { response: Response; headersAt: number } | undefined;
+
+/** The trigger in words, for the log line and the exhaustion error. */
+function triggerLabel(outcome: LegOutcome): string {
+ if (outcome.kind === "stall") return `stall ${Math.round(outcome.afterMs / 1000)}s`;
+ if (outcome.kind === "degenerate-wrapper") return `degenerate ${outcome.bytes}B`;
+ return outcome.kind;
+}
+
+function exhaustedMessage(outcome: LegOutcome, attempts: number): string {
+ if (outcome.kind === "stall") {
+ return `no output for ${Math.round(outcome.afterMs / 1000)} s after ${attempts} attempts`;
+ }
+ return `degenerate parallel tool wrapper after ${attempts} attempts`;
+}
+
+function sum(values: number[]): number {
+ return values.reduce((a, b) => a + b, 0);
+}
+
+export interface ResponsesTurnOptions
+ extends Omit<ResponsesLegContext, "sink" | "codeMode" | "drainClock"> {
+ /** Code mode for this turn (architecture §5.11). Absent ⇒ exec calls are ignored, as before. */
+ codeMode?: CodeModeTurnHooks;
+ /**
+ * Real per-provider context window (tokens) for the model on THIS backend.
+ * Used only to make the overflow message specific; omit/0 → left out.
+ */
+ contextWindow?: number;
+ /** An in-stream API error (it rides an HTTP 200, invisible to status). */
+ onApiError?: (code: string, message: string) => void;
+ /**
+ * Fires the request's stats record; called at most once per turn, LAST, with
+ * the final leg's input (the context figure) and the output of every leg.
+ */
+ onTokenUpdate?: (input: number, output: number) => void;
- onTurnEnd?: () => void;
+ /** Absent ⇒ one leg per turn, exactly as before retries existed. */
+ retry?: ResponsesRetryOptions;
+ /**
+ * Fires FIRST at turn end, only when earlier legs of a retried turn reported
+ * usage: their summed input (and cache detail). Each was a separate upstream
+ * request the provider billed in full; nothing else will ever charge it.
+ */
+ onExtraBilledInput?: (inputTokens: number, detail?: UsageCacheDetail) => void;
+ /** Fires after onExtraBilledInput and before onTokenUpdate. */
+ onTurnSummary?: (s: { legs: number; legRetries: number }) => void;
+}
+
+export interface ResponsesRetryOptions {
+ /** Issue leg 2..n of this turn: `undefined` body ⇒ the primary request's body. */
+ issueLeg: (body: unknown | undefined, signal: AbortSignal) => Promise<LegResponse>;
+ /** Retries per leg position. Default {@link MAX_LEG_RETRIES}. */
+ maxLegRetries?: number;
+ /**
+ * Abort a leg with no output item for too long (stall-guard.ts): attempts
+ * 1..n-1 use `thresholdMs`, the final attempt `finalThresholdMs`. Absent or
+ * `thresholdMs: 0` ⇒ unarmed.
+ */
+ stall?: StallPolicy;
+ /** When the FIRST leg's response headers arrived (the stall clock's zero). */
+ firstHeadersAt?: number;
+ /** The stall guard's clock; tests inject a fake one. Default wall clock. */
+ stallClock?: StallClock;
+ /**
+ * The primary request's upstream body (an object with an `input` array). A
+ * code-mode continuation leg appends to it; absent ⇒ no continuation leg can
+ * be built and an exec that did not block ends the message with an error.
+ */
+ primaryBody?: () => unknown;
+}
+
+/** The in-band text for an in-stream API error; context overflow gets an actionable message. */
+function apiErrorText(code: string, message: string, opts: ResponsesTurnOptions): string {
+ // Context-overflow gets an actionable message (with the real per-backend cap
+ // when known) instead of the bare error code — otherwise the user just sees a
+ // cryptic `context_length_exceeded` and a stuck session (/compact re-sends the
+ // same oversized input).
+ const isCtxOverflow =
+ code === "context_length_exceeded" ||
+ /context (length|window)|exceeds? the context|too long|maximum context/i.test(message);
+ if (!isCtxOverflow) return `\n\n[API Error: ${code} ${message}]`;
+ const cap =
+ opts.contextWindow && opts.contextWindow > 0
+ ? ` ~${Math.round(opts.contextWindow / 1000)}K tokens`
+ : "";
+ return (
+ `\n\n[Context limit reached] This model's backend enforces a smaller context window${cap} than its API spec. ` +
+ "Run /clear to start fresh (/compact will also fail — it re-sends the full conversation), " +
+ `or route the model via \`oai@${opts.modelName}\` to use the full-size window.`
+ );
+}
+
+/**
+ * The stop_reason for a turn whose last leg completed.
+ *
+ * A truncated turn must NOT be reported as a finished tool call. OpenAI emits
+ * the partial function_call arguments it managed to produce, so "tool_use"
+ * makes the client execute a tool with malformed JSON (InputValidationError).
+ * Anthropic's contract for a cut-off turn is stop_reason "max_tokens", which is
+ * the honest label here.
+ *
+ * KNOWN GAP: "max_tokens" does not actually stop Claude Code executing the
+ * partial block. Verified against 2.1.217 (passflow session, 2026-07-22, six
+ * days after v7.12.7 shipped this): the client ran the truncated Write and
+ * reported InputValidationError anyway. A mid-stream socket failure uses an
+ * `error` event, which does stop it — but that is only safe there because a
+ * dead socket is transient. max_output_tokens is deterministic, so an error
+ * event would make the client retry a request that truncates again. Capping
+ * the budget is the real fix and the codex backend rejects max_output_tokens
+ * ("Unsupported parameter"), so the label stays honest and the execution stays
+ * unprevented.
+ */
+function stopReasonFor(incomplete: string | undefined, hasToolUse: boolean): string {
+ if (incomplete) return incomplete === "content_filter" ? "refusal" : "max_tokens";
+ return hasToolUse ? "tool_use" : "end_turn";
+}
+
+class ResponsesTurn {
+ /** One entry per leg, in order; undefined for a leg that reported no usage. */
+ private readonly legUsages: Array<Usage | undefined> = [];
+ /** Retries in the whole turn (telemetry). */
+ private legRetries = 0;
+ /** Retries at the current leg position (a code-mode continuation starts a new one). */
+ private positionRetries = 0;
+ private usageReported = false;
+ /** The current leg's body; undefined ⇒ the primary request's (`issueLeg(undefined)`). */
+ private currentBody: unknown = undefined;
+ /** Code mode: the Responses items of earlier legs of this message, interstitial execs included. */
+ private readonly turnItems: ResponsesItem[] = [];
+
+ constructor(
+ private readonly sink: ClaudeSseSink,
+ private readonly opts: ResponsesTurnOptions
+ ) {}
+
+ private get lastUsage(): Usage | undefined {
+ return this.legUsages[this.legUsages.length - 1];
+ }
+
+ private get totalOutputTokens(): number {
+ return sum(this.legUsages.map((u) => u?.outputTokens ?? 0));
+ }
+
+ /** Context figure = the final leg's input; output = every leg's output. */
+ private get wireUsage(): { input_tokens: number; output_tokens: number } {
+ return {
+ input_tokens: this.lastUsage?.inputTokens ?? 0,
+ output_tokens: this.totalOutputTokens,
+ };
+ }
+
+ /**
+ * Report the turn's usage, once, in this order:
+ * 1. `onExtraBilledInput` with the input of EARLIER legs that reported usage;
+ * 2. `onTurnSummary`;
+ * 3. `onTokenUpdate(final leg's input, every leg's output)`, which fires the
+ * request's one stats record — so that record already holds 1 and 2.
+ * After a client disconnect nothing fires unless a leg had reported usage:
+ * what was billed is billed, but a turn cut off before any usage arrived has
+ * no figure worth recording.
+ */
+ private reportUsage(): void {
+ if (this.usageReported) return;
+ this.usageReported = true;
+ const reported = this.legUsages.filter((u): u is Usage => u !== undefined);
+ if (this.sink.isCancelled && reported.length === 0) {
+ log("[ResponsesSSE] client disconnected before usage arrived; no token update");
+ return;
+ }
+ const earlier = this.legUsages.slice(0, -1).filter((u): u is Usage => u !== undefined);
+ const extraInput = sum(earlier.map((u) => u.inputTokens));
+ if (extraInput > 0) {
+ const cacheRead = sum(earlier.map((u) => u.cacheDetail?.cacheReadTokens ?? 0));
+ const cacheCreation = sum(earlier.map((u) => u.cacheDetail?.cacheCreationTokens ?? 0));
+ this.opts.onExtraBilledInput?.(
+ extraInput,
+ cacheRead > 0 || cacheCreation > 0
+ ? { cacheReadTokens: cacheRead, cacheCreationTokens: cacheCreation }
+ : undefined
+ );
+ }
+ this.opts.onTurnSummary?.({ legs: this.legUsages.length, legRetries: this.legRetries });
+ this.opts.onTokenUpdate?.(this.lastUsage?.inputTokens ?? 0, this.totalOutputTokens);
+ }
+
+ async run(firstResponse: Response): Promise<void> {
+ try {
+ let response = firstResponse;
+ let headersAt =
+ this.opts.retry?.firstHeadersAt ?? (this.opts.retry?.stallClock ?? systemStallClock).now();
+ while (true) {
+ const outcome = await parseResponsesLeg(response, {
+ ...this.opts,
+ sink: this.sink,
+ stall: this.stallFor(headersAt),
+ codeMode: this.opts.codeMode !== undefined,
+ // The drain runs on the stall guard's clock, so one fake clock drives both.
+ drainClock: this.opts.retry?.stallClock,
+ });
+ this.legUsages.push("usage" in outcome ? outcome.usage : undefined);
+ const next =
+ outcome.kind === "exec" ? await this.onExec(outcome) : await this.afterLeg(outcome);
+ if (!next) return;
+ response = next.response;
+ headersAt = next.headersAt;
+ }
+ } catch (error) {
+ this.failTurn(error);
+ } finally {
+ this.sink.close();
+ }
+ }
+
+ /**
- * A callback threw (`primaryBody`, `onApiError`, a usage or middleware
++ * A callback threw (`primaryBody`, `onApiError`, a usage or raw
+ * hook); the leg itself never throws. A message with no ending yet still
+ * gets one: closed without `message_stop` or `error`, the non-streamed path
+ * folded it into a silent 200 partial.
+ */
+ private failTurn(error: unknown): void {
+ log(`[ResponsesSSE] Stream error: ${error}`);
+ if (!this.sink.hasEnded && !this.sink.isCancelled) {
+ this.sink.endWithError(`claudish: the turn failed: ${error}`);
+ }
+ try {
+ this.reportUsage();
+ } catch (err) {
+ log(`[ResponsesSSE] reporting usage failed: ${err}`);
+ }
+ }
+
+ /** A leg that did not end on an exec call: finish, retry, or end the message otherwise. */
+ private async afterLeg(outcome: LegOutcome): Promise<NextLeg> {
+ const decision = this.retryDecision(outcome);
+ if (decision.action === "finish") {
+ await this.finish(outcome);
+ return undefined;
+ }
+ if (decision.action === "end-tool-use") {
+ // The calls already stopped stand; the trigger's leg is dropped.
+ log(`[ResponsesTurn] ${triggerLabel(outcome)} after tool_use blocks — ending tool_use`);
+ this.recordTurn([]);
+ await this.finishCompleted("tool_use");
+ return undefined;
+ }
+ if (decision.action === "stop-attempts") {
+ await this.stopAttempts();
+ return undefined;
+ }
+ if (decision.action === "error") {
+ log(`[ResponsesTurn] ${decision.message} → error event`);
+ this.sink.endWithError(decision.message);
+ this.reportUsage();
+ return undefined;
+ }
+ return this.issueRetry(outcome);
+ }
+
+ private retryDecision(outcome: LegOutcome): RetryDecision {
+ if (outcome.kind !== "degenerate-wrapper" && outcome.kind !== "stall") {
+ return { action: "finish" };
+ }
+ const retry = this.opts.retry;
+ if (!retry) return { action: "finish" };
+ if (this.sink.hasIncompleteToolBlock) {
+ // Never a tool_use finish over an incomplete block: the cut-off rule.
+ return {
+ action: "error",
+ message: `${triggerLabel(outcome)} with a tool call cut off`,
+ };
+ }
+ if (this.sink.hasCompletedToolBlock) return { action: "end-tool-use" };
+ const max = retry.maxLegRetries ?? MAX_LEG_RETRIES;
+ if (this.positionRetries >= max) {
+ return { action: "error", message: exhaustedMessage(outcome, this.positionRetries + 1) };
+ }
+ if (this.opts.codeMode && this.legUsages.length >= MAX_LEGS_PER_TURN) {
+ return { action: "stop-attempts" };
+ }
+ return { action: "retry" };
+ }
+
+ // ─── code mode ──────────────────────────────────────────────────────
+
+ /** Store this message's Responses items (code mode); a throwing hook changes nothing. */
+ private recordTurn(finalItems: ResponsesItem[]): void {
+ const hooks = this.opts.codeMode;
+ if (!hooks) return;
+ const items = [...this.turnItems, ...finalItems];
+ if (items.length === 0) return;
+ try {
+ hooks.onTurnEnd({
+ anchor: this.sink.firstToolUseId,
+ items,
+ texts: this.sink.textBlocks(),
+ });
+ } catch (err) {
+ log(`[ResponsesTurn] storing the turn record failed: ${err}`);
+ }
+ }
+
+ /** The legs bound was reached: a visible note, then `end_turn`. */
+ private async stopAttempts(): Promise<void> {
+ log(`[ResponsesTurn] code-mode bound reached after ${this.legUsages.length} leg(s)`);
+ const idx = this.sink.nextIndex();
+ this.sink.startBlock(idx, { type: "text", text: "" });
+ this.sink.delta(idx, { type: "text_delta", text: CODE_MODE_STOP_TEXT });
+ this.sink.stopBlock(idx);
+ this.recordTurn([]);
+ await this.finishCompleted("end_turn");
+ }
+
- /** The behavior layer's one chance to rewrite a buffered nested call. */
- private repairNested(name: string, args: string): string {
- if (this.opts.shouldBufferTool?.(name) !== true) return args;
- try {
- const repaired = this.opts.onToolCall?.(name, args);
- if (typeof repaired === "string" && repaired !== args) {
- log(`[ResponsesSSE] tool call repaired: ${name}`);
- return repaired;
- }
- } catch (err) {
- log(`[ResponsesSSE] onToolCall threw for ${name}: ${err}`);
- }
- return args;
- }
-
+ private abandon(callId: string): void {
+ try {
+ this.opts.codeMode?.onTurnAbandoned(callId);
+ } catch (err) {
+ log(`[ResponsesTurn] abandoning exec ${callId} failed: ${err}`);
+ }
+ }
+
+ /** A leg ended on an exec call: run it through the hooks. */
+ private async onExec(outcome: Extract<LegOutcome, { kind: "exec" }>): Promise<NextLeg> {
+ const hooks = this.opts.codeMode;
+ if (!hooks || this.sink.signal.aborted) {
+ this.reportUsage();
+ return undefined;
+ }
+ let step: ExecTurnStep;
+ try {
+ step = await hooks.onExecCall({
+ callId: outcome.callId,
+ input: outcome.input,
+ precedingItems: outcome.precedingItems,
+ truncated: outcome.truncated,
+ });
+ } catch (err) {
+ log(`[ResponsesTurn] exec ${outcome.callId} failed in claudish: ${err}`);
+ this.sink.endWithError(`claudish could not run the exec call: ${err}`);
+ this.reportUsage();
+ return undefined;
+ }
+ if (step.kind === "emit-tool-uses") {
+ await this.emitNested(outcome, step.blocks);
+ return undefined;
+ }
+ return this.continueAfterExec(outcome, step.appendItems);
+ }
+
+ /** The script blocked: its calls become tool_use blocks and the message ends `tool_use`. */
+ private async emitNested(
+ outcome: Extract<LegOutcome, { kind: "exec" }>,
+ blocks: Extract<ExecTurnStep, { kind: "emit-tool-uses" }>["blocks"]
+ ): Promise<void> {
+ if (this.sink.signal.aborted) {
+ this.abandon(outcome.callId);
+ this.reportUsage();
+ return;
+ }
+ if (this.sink.hasIncompleteToolBlock) {
+ // A classic block of this leg was cut off: the message ends with an SSE
+ // `error` (finishCompleted's rule), so Claude Code never sees this batch
+ // and its retry starts a new upstream turn — end the script now.
+ log(`[ResponsesTurn] exec ${outcome.callId} blocked beside a cut-off tool_use → error event`);
+ this.abandon(outcome.callId);
+ this.sink.endWithError("a tool call was cut off before the exec call");
+ this.reportUsage();
+ return;
+ }
+ for (const block of blocks) {
+ this.sink.emitToolUse(
+ block.id,
+ block.name,
- relayNestedInput(block, (name, args) => this.repairNested(name, args))
++ relayNestedInput(block, (_name, args) => args)
+ );
+ }
+ log(`[ResponsesTurn] exec ${outcome.callId} relayed as ${blocks.length} tool_use block(s)`);
+ this.recordTurn(outcome.precedingItems);
+ if (this.sink.isCancelled) {
+ // Claude Code never saw the batch: its retry starts a new upstream turn.
+ this.abandon(outcome.callId);
+ this.reportUsage();
+ return;
+ }
+ await this.finishCompleted("tool_use");
+ }
+
+ /** The script finished without blocking: another leg carries its output to the model. */
+ private async continueAfterExec(
+ outcome: Extract<LegOutcome, { kind: "exec" }>,
+ appendItems: ResponsesItem[]
+ ): Promise<NextLeg> {
+ if (this.sink.hasToolUse) {
+ // A stray classic call already went out in this message: no further leg.
+ if (this.sink.hasIncompleteToolBlock) {
+ // Never a tool_use finish over a cut-off block (the cut-off rule).
+ log(`[ResponsesTurn] exec ${outcome.callId} after a cut-off tool_use → error event`);
+ this.sink.endWithError("a tool call was cut off before the exec call");
+ this.reportUsage();
+ return undefined;
+ }
+ log(`[ResponsesTurn] exec ${outcome.callId} after a tool_use block — ending tool_use`);
+ // The exec ran: its call and output belong to this message's history,
+ // or the model's next input lacks its own script and that script's result.
+ this.recordTurn([...outcome.precedingItems, ...appendItems]);
+ await this.finishCompleted("tool_use");
+ return undefined;
+ }
+ this.turnItems.push(...outcome.precedingItems, ...appendItems);
+ if (this.legUsages.length >= MAX_LEGS_PER_TURN) {
+ await this.stopAttempts();
+ return undefined;
+ }
+ const retry = this.opts.retry;
+ const base = (this.currentBody ?? retry?.primaryBody?.()) as
+ | { input?: unknown; [field: string]: unknown }
+ | undefined;
+ if (!retry || !base || typeof base !== "object" || !Array.isArray(base.input)) {
+ log("[ResponsesTurn] code-mode continuation has no request body → error event");
+ this.sink.endWithError("claudish: the code-mode continuation has no request body");
+ this.reportUsage();
+ return undefined;
+ }
+ const body = { ...base, input: [...base.input, ...outcome.precedingItems, ...appendItems] };
+ this.currentBody = body;
+ this.positionRetries = 0;
+ log(
+ `[ResponsesTurn] exec ${outcome.callId} finished without tool calls — leg ${this.legUsages.length + 1}`
+ );
+ return this.issue(body);
+ }
+
+ /** Issue a leg with `body` (undefined ⇒ the primary body); undefined when the turn ended instead. */
+ private async issue(body: unknown): Promise<NextLeg> {
+ const retry = this.opts.retry;
+ if (!retry || this.sink.signal.aborted) {
+ this.reportUsage();
+ return undefined;
+ }
+ const leg = await retry.issueLeg(body, this.sink.signal);
+ if (leg.kind === "ok") return { response: leg.response, headersAt: leg.headersAt };
+ if (leg.kind === "error") this.sink.endWithError(leg.message);
+ this.reportUsage();
+ return undefined;
+ }
+
+ /**
+ * This leg's stall guard settings: the final attempt (no retry left) gets the
+ * longer threshold, so no attempt is unbounded and the last one still has
+ * room for a long reasoning phase.
+ */
+ private stallFor(headersAt: number): ResponsesLegContext["stall"] {
+ const retry = this.opts.retry;
+ const policy = retry?.stall;
+ if (!retry || !policy || !("finalThresholdMs" in policy) || policy.thresholdMs <= 0) {
+ return undefined;
+ }
+ const isFinal = this.positionRetries >= (retry.maxLegRetries ?? MAX_LEG_RETRIES);
+ return {
+ thresholdMs: isFinal ? policy.finalThresholdMs : policy.thresholdMs,
+ headersAt,
+ clock: retry.stallClock,
+ };
+ }
+
+ /** Re-send the current leg's body (the primary one until a code-mode continuation). */
+ private async issueRetry(outcome: LegOutcome): Promise<NextLeg> {
+ const retry = this.opts.retry;
+ if (!retry) return undefined;
+ this.legRetries++;
+ this.positionRetries++;
+ const max = retry.maxLegRetries ?? MAX_LEG_RETRIES;
+ log(`[ResponsesTurn] ${triggerLabel(outcome)} — retry ${this.positionRetries}/${max}`);
+ return this.issue(this.currentBody);
+ }
+
+ /**
- * A completed turn: `message_delta` + `message_stop`, usage, then the turn
- * hooks. Never a `tool_use` finish over a cut-off block (the cut-off rule),
++ * A completed turn: `message_delta` + `message_stop`, usage, then the raw
++ * `providerStreamEnd` hooks. Never a `tool_use` finish over a cut-off block (the cut-off rule),
+ * whichever path got here: an SSE `error` instead, so Claude Code runs none
+ * of the message's tools and retries.
+ */
+ private async finishCompleted(stopReason: string): Promise<void> {
+ if (stopReason === "tool_use" && this.sink.hasIncompleteToolBlock) {
+ log("[ResponsesTurn] tool_use finish over a cut-off tool block → error event");
+ this.sink.endWithError("a tool call was cut off mid-arguments");
+ this.reportUsage();
+ return;
+ }
+ this.sink.endMessage(stopReason, this.wireUsage);
+ this.reportUsage();
- if (this.opts.middlewareManager) {
- await this.opts.middlewareManager.afterStreamComplete(
- this.opts.modelName,
- this.opts.streamMetadata
- );
- }
- this.opts.onTurnEnd?.();
++ if (this.opts.raw) await this.opts.raw.streamEnd();
+ }
+
+ private async finish(outcome: LegOutcome): Promise<void> {
+ switch (outcome.kind) {
+ case "done": {
+ const stopReason = stopReasonFor(outcome.incomplete, this.sink.hasToolUse);
+ if (outcome.incomplete) {
+ log(
+ `[ResponsesSSE] Truncated response (${outcome.incomplete}) → stop_reason=${stopReason}`
+ );
+ }
+ this.recordTurn(outcome.items ?? []);
+ await this.finishCompleted(stopReason);
+ return;
+ }
+ case "api-error":
+ // Signal the terminal error so the caller records this turn as a
+ // failure (the error rides an HTTP 200 stream, invisible to status).
+ this.opts.onApiError?.(outcome.code, outcome.message);
+ this.sink.endWithText(
+ apiErrorText(outcome.code, outcome.message, this.opts),
+ this.wireUsage
+ );
+ this.reportUsage();
+ return;
+ case "stream-error":
+ // A tool block that was open when the socket died had its argument JSON
+ // cut mid-object, and `end_turn` makes Claude Code run the tool on it:
+ // InputValidationError: Write was called with input that could not
+ // be parsed as JSON. You sent (first 200 of 9437 bytes): {"file_pa…
+ // `max_tokens` does not rescue it either (Claude Code 2.1.217 ran a
+ // max_tokens-terminated call anyway). Only an `error` event ends the
+ // message with no completed tool_use, and it is the honest report — the
+ // turn did fail. devin-connect ends a mid-stream fault the same way.
+ // With no tool call in flight the inline text keeps partial prose visible.
+ // Code mode: an exec cut mid-input is a tool call in flight too. It was
+ // never a block and never ran, so Claude Code's retry is safe — and
+ // `end_turn` would stop the agent where classic mode retries.
+ if (outcome.openToolBlock || outcome.openExec) {
+ log("[ResponsesSSE] tool arguments cut off mid-stream → error event");
+ this.sink.endWithError(`Stream error: ${outcome.error}`);
+ } else {
+ this.sink.endWithText(`\n\n[Stream error: ${outcome.error}]`, this.wireUsage);
+ }
+ this.reportUsage();
+ return;
+ case "degenerate-wrapper":
+ // Only reached without `retry`. Never shown to Claude Code: the error
+ // event makes it discard the message and retry the turn, and no tool_use
+ // of it runs.
+ log("[ResponsesSSE] degenerate parallel wrapper → error event");
+ this.sink.endWithError(
+ `degenerate parallel tool wrapper (${outcome.reason}, ${outcome.bytes} bytes)`
+ );
+ this.reportUsage();
+ return;
+ case "stall":
+ this.sink.endWithError(`no output for ${Math.round(outcome.afterMs / 1000)} s`);
+ this.reportUsage();
+ return;
+ case "cancelled":
+ this.reportUsage();
+ return;
+ }
+ }
+}
+
+/**
+ * Drive one downstream Claude message from `firstResponse`. Never throws; the
+ * sink is closed when this resolves.
+ */
+export function runResponsesTurn(
+ sink: ClaudeSseSink,
+ firstResponse: Response,
+ opts: ResponsesTurnOptions
+): Promise<void> {
+ return new ResponsesTurn(sink, opts).run(firstResponse);
+}
diff --cc packages/cli/src/index.ts
index ed08c82d,68b08ef7..1af93910
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@@ -1243,7 -1300,9 +1313,10 @@@ async function runCli()
effortOverride: cliConfig.effortOverride,
modelParams: cliConfig.modelParams,
proOnUltracode: cliConfig.proOnUltracode,
+ codeMode: cliConfig.codeMode,
+ // Proxy events run in the process that hosts the proxy: a pane child
+ // for MCP/team slots, the interactive launcher otherwise.
+ hostMode: isPaneChild() ? "pane-child" : cliConfig.interactive ? "interactive" : "other",
}
)
);
diff --cc packages/cli/src/proxy-server.ts
index 1930addf,3def0e2b..f8e284d0
--- a/packages/cli/src/proxy-server.ts
+++ b/packages/cli/src/proxy-server.ts
@@@ -3,8 -3,9 +3,6 @@@ import { join } from "node:path"
import { type Context, Hono } from "hono";
import { cors } from "hono/cors";
import { isEffortLevel } from "./adapters/base-api-format.js";
- import { loadHookRules } from "./behavior/hooks.js";
- import { parseBehaviorConfig, registerHookRules } from "./behavior/index.js";
-import { LocalModelAdapter } from "./adapters/local-adapter.js";
-import { OpenRouterAPIFormat } from "./adapters/openrouter-api-format.js";
-import { credentials } from "./auth/credentials/authority.js";
import {
isAutoModeClassifierRequest,
rewriteClassifierForNative,
@@@ -27,12 -21,11 +25,16 @@@ import { createHandlerSet } from "./han
import { loadAdvisorSwapConfig } from "./handlers/native-handler-advisor.js";
import { NativeHandler } from "./handlers/native-handler.js";
import { wrapAnthropicError } from "./handlers/shared/anthropic-error.js";
+import {
+ SIGNING_SECRETS_KEY,
+ createSigningSecrets,
+ releaseWhenBodyEnds,
+} from "./handlers/shared/call-context.js";
import type { ModelHandler } from "./handlers/types.js";
+ import type { HookEngine } from "./hooks/engine.js";
+ import { loadHooksOnce } from "./hooks/index.js";
+ import type { HostMode } from "./hooks/public.js";
+ import { withHooks } from "./hooks/response-seam.js";
import { log, logStderr } from "./logger.js";
import { warmRecommendedModels } from "./model-loader.js";
import { loadConfig } from "./profile-config.js";
@@@ -160,18 -165,18 +162,30 @@@ export interface ProxyServerOptions
* no filesystem work at all.
*/
proOnUltracode?: boolean;
+ /**
+ * `--code-mode`: code mode for `openai-codex` (`auto` | `on` | `off`).
+ * Absent ⇒ `DEFAULT_CODE_MODE_SETTING` (`auto`).
+ */
+ codeMode?: CodeModeSetting;
+ /**
+ * Every `--advisor` member's startup plan and every routed member's chain,
+ * built before the port was bound (advisor-route-plan.ts). Present ⇒ the
+ * proxy exposes `advisorPanel` and owns the chains: `shutdown` shuts them
+ * down. Absent ⇒ no gateway; nothing is planned lazily.
+ */
+ advisorRuntime?: AdvisorRuntime;
+ /**
+ * Run hooks on this proxy's `/v1/messages` traffic. Default true. `--probe`
+ * passes false: hooks never see probe traffic. Monitor mode and the
+ * classifier passthrough never run hooks whatever this says.
+ */
+ hooks?: boolean;
+ /**
+ * Which host this process is, for hook loading and `ctx.host.mode`: the
+ * interactive launcher, a pane child, `serve`, the MCP server, or other.
+ * Default `"other"`. The first proxy of a process decides it.
+ */
+ hostMode?: HostMode;
}
/**