@sema-agent/core 7.35.1 → 7.36.0

package/CHANGELOG.md

@@ -1,3 +1,88 @@
+## 7.36.0 — 2026-09-30
+
+**Hard-breaking changes — the whole release in three sentences.**
+
+① *Who is affected.* (design/1209) A host whose PostToolUse / PostToolUseFailure hook (or hook matcher) keys on an alias spelling (PostToolBatch is untouched: its entries keep the spelling, as the reference's do); a deployment that declares one tool under the names of two engine tools (any two engine tool names count, seat-bearing or not: `Custom{aliases:["NotebookEdit","Write"]}`, `NotebookEdit{aliases:["Write"]}`, `Read{aliases:["Bash"]}` — a tool's own `pathTarget` does not exempt it); a caller tool that declares a low irreversibility tier while wearing `Bash` / `Monitor` as an alias; a caller tool that claims an engine hand tool's name as an alias (`Charge{effect:"write", aliases:["Read"]}`); a reader of a park row's `names` order or of a resumed call's `tool_start` / `tool_end` name. (#1207) A host, tool or store that keys on a tool-call id and is served by a gateway whose ids fall outside visible ASCII 1–128 or contain `~` (it now receives the engine's fold, not the provider's bytes, on every frame, card, park row and transcript line); a tool that reads the transcript's `ToolCall.id` as the provider's own id; a host replaying a side query's returned calls to a provider; a consumer with a closed table of notice codes (server / cli / client-core: +1 `route.tool_call_id_folded`).
+
+② *How to change.* (design/1209) Match PostToolUse / PostToolUseFailure on the tool's wire name (during a mixed-version rollout, list both the wire name and the alias); leave a PostToolBatch matcher on the spelling (its entries do not move); keep ONE engine tool's names on a tool (drop the second alias); drop the `Bash` / `Monitor` alias from a tool that must not sit behind the engine's shell seat, or accept the seat; do not claim an engine hand tool's name as an alias; read a park row's `names` as "the spelling first", and pair a resumed call's frames by `toolCallId`. (#1207) Key everything on the engine id (`ToolCall.id`, `toolCallId` on every frame, card and row); read the provider's spelling from `ToolCall.wireId` / `SideQueryResult.toolCalls[].wireId` (present only when the two differ) and hand the provider `wireId ?? id` (replaying through another side query: carry both on the `toolCall` block, key the result by `id`); add the notice row (`operator`).
+
+③ *If you do not.* (design/1209) An alias matcher on PostToolUse / PostToolUseFailure no longer fires (post-execution face only — no decision is widened); a declaration answering to two engine tools refuses the run at prepare with `config.tool_face_invalid` (no turn runs; a call parked under such a tool stays parked until the declaration changes); the shell seat's question now reaches a low-tier tool that wears `Bash` (`default` 0 → 1 card, `dontAsk` ran 1 → 0); an interrupted call spelled a claimed hand tool's name reads the conservative "confirm with the user before repeating it" wording, and the faces that admit a call by its declared effect under that name treat it as the less repeat-safe effect. (#1207) Nothing breaks for an id in shape: every `toolu_…` / `call_…` / uuid id is admitted verbatim (no fold, no `wireId`, no notice), so every face and every request is byte-identical to v7.35.1's; for a folded id the provider is still handed its own spelling for the call, its result, an image carrier's label and a dropped-call note (only engine handles minted from the call id — an offloaded result's `ref` — are minted from the fold); a host that replays a side query's folded call to a provider under `id` alone hands it the fold, not its own id; a notice table missing the row reads the code as an unknown one.
+
+**Closed sets, one by one.**
+- `ENGINE_NOTICE_CODES` / `EngineNoticeCode` (#1207): +`route.tool_call_id_folded` (audience `operator` in `NOTICE_AUDIENCE`).
+- design/1209: no closed set moves — its prepare refusal is `config.tool_face_invalid`, already in `TOOL_DECLARATION_CODES`.
+
+**Package exports** (`npm run handoff:diff v7.35.1 HEAD`): +0 / −0. Four public types gain one optional member each: `ToolCall.wireId?: string`, `SideQueryResult.toolCalls[].wireId?: string` (#1207, one meaning: the provider's spelling, present only on a fold); `AggregateBudgetOptions.toolNameOf?`, `ContextEditOptions.toolNameOf?` (design/1209; absent ⇒ the recorded name, as before). The wire list carries three of the four (`ToolCall` +`wireId`, `AggregateBudgetOptions` / `ContextEditOptions` +`toolNameOf`, each optional); the fourth sits on an inline array element the list does not read — stated here by hand. design/1209's read ports and table (`src/core/tool-name-readings.ts`) are not exported; `ruleNamesOf` stays exported (now declared beside the ports); the retired call-site helpers (`callAnswersTo`, `toolNameSetHas`, `anyNamed`, `firstNamed`) were never package exports. #1207's `admitToolCallId` and the fold are internal (`src/brain/tool-call-id.ts`).
+
+**The wire list's BREAKING items** (`node scripts/wire-changes.mjs v7.35.1 HEAD --version 7.36.0`), one per line:
+- none — 0 BREAKING items. The non-breaking moves it carries: closed set gained a member `ENGINE_NOTICE_CODES` +`route.tool_call_id_folded` (#1207); a new module-level closed set `ToolCallIdFoldReason` (`charset` / `length` — the notice detail's `reason`, #1207; not a package export); type gained optional keys `ToolCall` +`wireId` (#1207), `AggregateBudgetOptions` +`toolNameOf`, `ContextEditOptions` +`toolNameOf` (design/1209).
+- not on the wire list (an inline array element): `SideQueryResult.toolCalls[]` +`wireId?` (#1207) — stated here by hand.
+- value moves on existing faces the list cannot read, from the criteria: F1 (the tier seat), F2 (the post hooks' name), F3 (the declaration refusal), F4 (a park row's `names` order, a resumed call's frame name), F5 / F6 (the effect and result-name readings), F7 (the declaration-time effect table), F8 (a folded tool-call id on every engine face).
+
+### Every per-call site that resolves a call's names reads them one declared way — one table, four readings, typed ports (display and hint sites that only echo the spelling stay outside it: KL-1209-h) (design/1209; behavior (tighten, and the post-execution hooks' name); +0 exports, +2 optional option members (`AggregateBudgetOptions.toolNameOf`, `ContextEditOptions.toolNameOf`), +0 codes, +0 wire keys) (@server @cli @test)
+
+- **Before (v7.35.0).** The gate resolved a call's name to the wire name, and each of 41 sites keyed on an engine tool name decided on its own whether to read that name or every name the call answers to — in a comment, and in which of five helpers it called; five sites compared the call's name with an engine name literally. The same review round found three defects of that family.
+- **Now.** `src/core/tool-name-readings.ts` holds ONE table (`NAME_READINGS`, 56 rows: the design's 41, 12 its program scan found, 1 the release review found (the batch hook entry, a spelling row), 2 the review round found) giving each site one of four readings — `any` (a tighten held under every name the call answers to; a set-valued table read as the union), `seat` (a multi-key seat read under ONE name: `tier` = the name whose irreversibility tier is strictest, `member` = the first name the table holds), `wire` (a grant or a routing: the wire name only), `spelling` (a record of what the model said; no port) — and the ports `heldBy` / `heldValues` / `seatOf` / `wireOf`, which take a site id typed by the table's kind: a site read through another kind's port does not compile. `gate:name-readings` (in `gate:all`) reads the program for the ways around the ports: a name-keyed table read outside them, a call's name compared with an engine name without `wireOf`, a site id spelled twice.
+- **The tier seat is the strictest name, with the source band.** *Before:* the gate, the rule-offer door, the park row's risk descriptor and an ask's `riskAxes` read the seat under the FIRST of the call's names holding a tier — `MyShell{irreversibility:"never", aliases:["Bash"]}` called as `MyShell` read `never` and never met the engine's `Bash` seat. *Now:* the seat is the name whose tier is strictest (`never < maybe < always`, absent lowest; ties to the earlier name); its probe and its shell-seat provenance are read under that name; the four sites choose the same name. `shellGated` holds only when no name the call answers to carries a deployment mark (the gate's mark sources are now the union over the call's names). *Who is hurt:* a caller tool that declares a low tier and wears `Bash` / `Monitor`: `rm -rf <root>/y` under `default` asks (0 → 1), under `dontAsk` is refused (ran 1 → 0).
+- **PostToolUse / PostToolUseFailure receive the wire name** (the reference: the post hook is passed the resolved tool's name). *Before:* they received the model's spelling while PreToolUse received the wire name. *Now:* both receive the wire name. **PostToolBatch keeps the spelling** — deliberately, as the reference does (its PostToolBatch payload maps each tool_use block's own name, while its PostToolUse is passed the resolved tool): the batch entry is now a table row (`hook.postToolBatch`, spelling), so the gate sees it — the release review found the projection outside the table; `tool_start` / `tool_end`, the transcript and the activity stream keep the spelling. *Who is hurt:* a post hook or matcher written against an alias spelling (see ①–③).
+- **One order of a call's names; the park row carries the gate's.** *Before:* the gate's face listed the spelling first, the park row's `names` the wire name first. *Now:* the park row copies the names of the face the gate judged the call under (the spelling first); a resume re-mints its face under that recorded spelling only while it still resolves to the row's own tool — a spelling that disappeared, or that another tool now owns, gives the row's wire name (never another tool's face). A resumed call's `tool_start` / `tool_end` carry the recorded spelling (`names[0]`, else the row's name). A row parked by 7.34.0 or earlier (no `names`) reads as before (KL-1194-a); a row parked by 7.35.0 carries the wire name first, which re-mints as it did.
+- **The write verification reads the tool's effect under the wire name** (live and on the resume seed); the orphan reconcile keeps reading the recorded name.
+- **A result's budget exemption and its clearability are judged on the tool the call ran.** *Before:* the per-turn result budget exempted a result whose RECORDED name was in the catalog's exempt set (`Read`), and the micro-compaction pass cleared a result whose recorded name was compactable — so a caller tool wearing `Read` called as `Read` escaped the budget (a 300 000-character result stayed whole) while the same tool called under its own name was capped. *Now:* the Runner hands both passes the roster's resolution (`toolNameOf`), and the set is read under the wire name — the engine's own `Read` stays exempt, a tool wearing its name is capped under either spelling; clearing likewise reaches only the engine's compactable tools. A host calling `capAggregateToolResults` / `clearStaleToolResults` without `toolNameOf` reads the recorded name as before.
+- Pins: `test/name-readings-oracle.test.ts` (the table deep-equals the frozen oracle `test/fixtures/name-readings.oracle.json`; every row has a cell judged by the ORACLE's kind — site / real-lane / port cells; the four compile-time bind pins); `test/name-readings-behavior.test.ts` (the four seat sites agree, the tier counterexample on a real lane, the source band, the three fates of a parked alias, the post hooks' name); `test/name-readings-gate.test.ts` (the gate on the tree, and every way around the ports planted in memory — red at its line). Mutations D-a…D-j (D-g is the declaration refusal of the BREAKING section below; D-k is the effect table's): `.gate-logs/criteria-7.36.0-mutations.md`, its design/1209 part.
+
+### An interrupted call is never reconciled as safe to repeat on a hand tool's word when a caller tool claims that name (pre-existing, fixed in this release; design/1209 review round 2; behavior (tighten); +0 exports) (@test)
+
+- **Before (≤ v7.35.0).** The declaration-time effect table first recorded a caller tool's effect under each alias it claims, then registered the hand band's effects unconditionally over them: `Charge{effect:"write", aliases:["Read"]}` with the engine's `Read` excluded filed `Read` as `read`, so a `Read`-spelled call to `Charge` interrupted mid-run was reconciled as "read-only/idempotent … simply call it again" — a write the model was told to repeat.
+- **Now.** A name a caller tool claims as an alias AND a hand tool owns records the LESS repeat-safe of the two effects (`write` over `idempotent` over `read`; a claimer that declares none is a write), whichever tool the roster later dispatches it to: the interrupted call reads the UNKNOWN wording ("confirm with the user before repeating it"). A name no caller claims keeps the hand's own effect. *Who is hurt:* where a caller tool also claims an engine hand tool's name as an alias — an interrupted call spelled that name reads the conservative wording, and the faces that admit a call by its declared effect under that name (a session's `allowDirs`, a skill's `allowPaths`, the final-verification seat) treat it as the less repeat-safe effect (the same over-conservative direction the effect default already takes) — only where the name's mount does not re-register its effect: with the engine's own hand tool mounted under that name, its mount re-registers the hand's effect and those three faces read it (the conservative wording then reaches only the interrupted-call note). Compensation: do not claim an engine hand tool's name as an alias.
+- Pin: `test/name-readings-behavior.test.ts` (the declaration-time effect table block); mutation D-k.
+
+### BREAKING (declaration) — a tool whose names belong to two engine tools is refused at prepare (design/1209 §3, #1208; `config.tool_face_invalid`, an existing code; +0 exports) (@server @test)
+
+- **Before (v7.35.0).** `Custom{aliases:["NotebookEdit","Write"]}` declaring no path target was judged on the slot of the name it was called by — called as `NotebookEdit` with the denied path in `file_path`, it ran (KL-1194-d); `Read{aliases:["Bash"]}` joined only the first read station its names met.
+- **Now.** The roster counts, per row, the engine tools its RESOLVED names belong to (its wire name and the aliases that resolve to it: an alias another row owns is not counted; several names of one engine tool — `ListAgents` / `ListPeers` — count once). Two or more ⇒ prepare fails with `config.tool_face_invalid`, before any turn and before a resume's identity comparison. A tool that declares its own `pathTarget` under two engine names is refused too (the literal form). `Custom{aliases:["Read","Bash"]}` beside the engine's mounted `Read` is not refused: `Read` resolves to the engine's row.
+- *Who is hurt / compensation:* see ①–③ above — keep one engine tool's names.
+
+### A provider's tool-call id is admitted once, where the brain builds the call: in shape it is the key, out of shape it is folded — the provider always gets its own id back (#1207; behavior (a folded id on every engine face) + closed set +1 notice code; +0 exports, +2 optional type members, one meaning (`ToolCall.wireId`, `SideQueryResult.toolCalls[].wireId`)) (@server @cli @client-core @test)
+
+- **Before (v7.35.1).** The three built-in brains copied the provider's id into `ToolCall.id` as sent. An id outside the provider echo shape — a control sequence (`call_\u001b]0;…\u0007`), a non-ASCII unit, a space, 129+ characters — became the key of every engine face (tool frames, approval cards and askIds, the tool-result join, the park row, the transcript) and reached the wire as upstream bytes. Only a missing id had a rule (the lane's fallback).
+- **Now.** One admission, `admitToolCallId(raw, prefix)` (`src/brain/tool-call-id.ts`), at the one place each brain builds a call (anthropic `closeToolUseBlock`, openai `closeToolCallAccum`, open-responses `closeFunctionCall`), returning two ids:
+  - absent (a non-string or `""`) ⇒ the lane's fallback (`toolu_…` / `call_…`), both ids — unchanged;
+  - admitted — visible ASCII 0x21–0x7E, 1–128 (`isProviderEchoShape`), and no `~` ⇒ both ids are the raw string — unchanged;
+  - otherwise FOLDED ⇒ the engine id is a readable base (the raw's first 32 code units, each one outside the admitted alphabet written `-`) + `~` + 32 hex of sha256 over the raw's UTF-16 code units — always in shape, always carrying one `~`, which the admitted arm refuses, so a fold never equals an admitted id; two different raws fold apart (lone surrogates included); one raw folds to one id in every lane and every run. The raw rides beside it as `ToolCall.wireId`.
+- **The provider always gets its own id.** Each brain hands a call back under `wireId ?? id` and a result under the `wireId` of the call it answers, read off the same request's messages (no side table): anthropic `tool_use.id` / `tool_result.tool_use_id`, openai `tool_calls[].id` / `tool_call_id`, open-responses `function_call.call_id` / `function_call_output.call_id`. `wireId` is persisted with the assistant message, so a resumed run — in another process, after a compaction — hands back the same spelling and never folds again; a row parked by v7.35.x (the raw id as the key, no `wireId`) resumes under that raw id.
+- **A side query's tool calls carry the provider's spelling too.** `SideQueryResult.toolCalls[]` gains an optional `wireId` — present only when it differs from `id`, read from the same `ToolCall.wireId`. The replay rule: hand the provider `wireId ?? id`; replaying through another side query, carry both on the `toolCall` block and key the result by `id` (the brain then hands the provider `wireId`). Absent ⇒ `id` is the provider's own. (@server: the S-889 side-query consumer.)
+- **One notice per run**, `route.tool_call_id_folded` (operator), on the first folded call: `detail: { toolCallId, rawLength, reason: "charset" | "length", sessionId, runId }` — the engine id, never the raw bytes. Read off `ToolCall.wireId` by a runner seat, so it is the same reading for every brain.
+- **Model-facing text names the provider's spelling too.** The label of an image carried beside a tool result (openai / open-responses: `[Image from tool result <id>]`) names the result's provider id; the note a brain adds for a dropped call (a call with no name: `id="…"`, replayed to the provider as assistant text) keeps naming the id as the provider sent it (unchanged).
+- `PROVIDER_ECHO_SHAPE` / `isProviderEchoShape` move to a leaf module (`src/brain/provider-echo-shape.ts`, re-exported from `errors.ts` as before) so the admission stays a leaf; the constant, the predicate and the package exports are unchanged.
+- **Who is hurt.** A consumer that relied on seeing a gateway's out-of-shape bytes as the tool-call id on a frame, card, row or transcript line now sees the fold; the bytes are on `ToolCall.wireId` in the transcript (upstream bytes, never sanitized — render `id`). A host `Brain` is not admitted: its ids enter as it wrote them (KL-1207-a). Compensation: the notice, the deterministic fold (one raw, one id — joinable across runs), and the provider face: every provider-minted id the request carries is the provider's own spelling.
+- Pins: `test/backlog1207-tool-call-id-admission.test.ts` — a real Runner over each of the three brains, the provider a fetch stub, reading frames, notices, the persisted transcript and the request bodies: G1 admitted ids (four shapes) identical on every face, no notice; G2 five out-of-shape shapes folded in shape on every engine face, handed back as sent, one notice per run (two folds, one notice), deterministic across runs; G3 the fallback unchanged; G4 two 129-character ids differing in their last two characters fold apart and both join; G5 a folded and an admitted call side by side — the request never names the fold; a folded call beside a nameless one — the replayed drop note names the provider's spelling; a result carrying an image — the carrier's label names the provider's id; G6 a folded call parked, the process gone, a fresh Runner over the same files resumes it: the call executes under the parked engine id and the provider gets its own id back for the call and its result, no notice again; G6b a row parked with the raw id as its key resumes under it; G6c a compaction between the resumed call and the next request keeps the parked call verbatim (a tool result is never a cut point, so a call and its result are kept or summarized together) and the next request still hands the provider its own id. `test/backlog1207-tool-call-id-unit.test.ts` — U1 the three arms and both fold reasons; U2 injectivity (past the readable base; lone surrogates vs U+FFFD), disjoint arms, determinism, lane independence; U3 the outbound reading; U4 the notice seat (once per run; a host brain's in-shape `wireId` is not a fold); U5 the drop note on all three lanes names the provider's spelling; U6 a side query over the openai brain returns `{ id: <fold>, wireId: <raw> }`, and replaying it through a second side query hands the provider the raw for the call and its result (an admitted id: no `wireId` key). v7.35.1 (2c39696fe) on the first file: G2, G4, G6 red (24), G1, G3, G5 green (21).
+- Mutations (`.gate-logs/criteria-7.36.0-mutations.md`, its #1207 part, per fixture): D970 no fold; D971 / D972 a call / a result handed back under the engine id; D973 the fold without its digest; D974 a fold salted per call; D975 `wireId` kept only in memory; D976 a notice per call; D977 no notice; D978 `~` admitted verbatim; D979 the drop note names the fold; D980 the image carrier's label names the engine id; D981 the admitted arm removed; D982 the empty string folds; D983 the side-query projection drops `wireId`.
+- Known limits: KL-1207-a (a host brain's ids are not admitted). KL-1207-b (a side query returned only the fold) closed in this entry by `SideQueryResult.toolCalls[].wireId`.
+
+## 7.35.2 — 2026-09-29
+
+### A wait the watchdog cuts at the 30 s disclosure threshold is disclosed before the cut (#746; behavior (status frames: +1 `waiting_first_token` frame per attempt when a first-token or first-byte window is exactly the 30 s threshold); +0 exports, +0 wire keys, +0 codes, closed sets unchanged) (@cli @client-core @server @test)
+
+- **Before (v7.35.1).** Measured by cli against a running engine (L-778, five scenarios: a gateway that sends headers at once and its first token 45 s later, or holds its headers 45 s). With the first-token watchdog at 30 s (`firstTokenTimeoutMs`; server env `MODEL_FIRST_TOKEN_TIMEOUT_MS`), a request waited 30 s with no `status` frame at all and was then cut. The wait disclosure was armed only for a ceiling strictly above its 30 s threshold, so the one tick that fell on the deadline was never sent. At 40 s, or at the 600 s default, the 30 s frame was there. A first-byte window of exactly 30 s (knob plus upload allowance) had the same gap.
+- **Now.** The wait disclosure is armed whenever its ceiling reaches the threshold (`>=`, the watchdog's own comparison). When the watchdog fires, a wait not yet disclosed is disclosed at that instant — `waiting_first_token` with `elapsedMs` equal to `timeoutMs` — and the retry (or terminal) frame follows. The deadline owns that frame, so which timer runs first no longer decides whether it is sent. This holds for the first-token wait and the header wait alike. Re-announcements are unchanged: they stay strictly before the ceiling, so a 120 s watchdog still shows 30 / 60 / 90 s and no frame at 120 s.
+- **Not changed.** The retry after a watchdog cut keeps `phase: "reconnecting"` with `errClass: "stall"`. The shells already tell the two apart by `errClass`: cli L-264 renders it as "No output before the stream timeout · slow model or gateway", through client-core's `stalled` arm. The engine does not rename the phase. The header wait and the first-token wait still share `waiting_first_token`; a separate phase word would be a wire change.
+- **Readings (engine fixtures of cli's scenarios, fake clock).**
+  - A (token 45 s, watchdog 30 s, every request slow): 0 → 11 wait frames, one per attempt, each 30000 of 30000, each before its attempt's `reconnecting` / `stall` frame. The call still ends `gave_up` / `first-token timeout after 30000ms`.
+  - A2 (only the first request slow): `reconnecting, recovered` → `waiting_first_token, reconnecting, recovered`.
+  - B′ (header window exactly 30 s): the same.
+  - B (headers 45 s, first-byte 30 s + 3 s upload allowance), C (the 600 s default) and D (40 s): unchanged.
+- **Who is hurt.** A deployment whose first-token (or first-byte) window is exactly 30 s sees one more frame per attempt, at the deadline. The frame is closed by `recovered` / `gave_up` as before. client-core maps it to `kind: 'waiting'` and cli renders its waiting byline. A probe that counted zero wait frames under a 30 s watchdog goes red. The engine defaults are unchanged.
+- Pins: `test/backlog746-first-token-watchdog-phase.test.ts`:
+  - A ① every attempt's wait is disclosed at its deadline; A ② control: the retries and the end; A ③ an event loop stalled across the deadline still gets exactly one wait frame before the retry.
+  - A2, B′ (the full trails), B, C, D (controls).
+  - Baseline v7.35.1: A ①, A ③, A2 and B′ red; A ②, B, C and D green.
+  - Unchanged and green: `backlog530-waiting-first-token`, including the 120 s cell and the stalled-event-loop cell.
+- Mutations:
+  - D960, the disclosure arms only above the threshold (v7.35.1's `>`): A ①, A ③, A2 and B′ go red.
+  - D960b, the deadline does not disclose (`expire` does what `stop` does): the same four go red. Per site: the first-token watchdog calling `stop` turns A ①, A ③ and A2 red; the header `finally` always stopping turns B′ red.
+  - D960c, the deadline discloses a wait that was already disclosed: the controls go red (D, B, and `backlog530` ④ / ⑥ / ④c).
+  - Per-fixture table: `.gate-logs/criteria-7.35.2-mutations.md`.
+
 ## 7.35.1 — 2026-09-29
 
 ### A run that named no session holds the session its store minted — a second run on that id waits for it (#1206; behavior (tighten: a second run of a new session queues); +0 exports, +0 wire keys; +1 engine-invariant code `internal.session_lock_second_id` that no engine path reaches) (@server @test)

package/dist/brain/anthropic.js

@@ -3,7 +3,7 @@ import { BrainError } from "./errors.js";
 import { startsWithInputTooLongAnchor } from "./input-too-long.js";
 import { DEGENERATE_MESSAGE, trimDegenerateTail } from "./repetition.js";
 import { STREAM_TORN_WARNING, createRepetitionPoll, noteResponseModel, parseStreamedToolArgs } from "./stream-shared.js";
-import { mintFallbackToolCallId } from "./tool-call-id.js";
+import { admitToolCallId, providerResultIds, providerToolCallId } from "./tool-call-id.js";
 import { emitBrainTelemetry, reportReasoningWireFacts } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, takeHeaderCasefold } from "./request-params.js";
@@ -58,6 +58,7 @@ function toAnthropicMessages(ctx, model) {
         raw.push({ role: "user", content: pendingDocs });
         pendingDocs = [];
     };
+    const resultWireId = providerResultIds(ctx.messages);
     for (const m of ctx.messages) {
         if (m.role !== "toolResult")
             flushDocs();
@@ -84,7 +85,7 @@ function toAnthropicMessages(ctx, model) {
                     blocks.push({ type: "text", text: c.text });
                 }
                 else if (c.type === "toolCall") {
-                    blocks.push({ type: "tool_use", id: c.id, name: c.name, input: c.arguments ?? {} });
+                    blocks.push({ type: "tool_use", id: providerToolCallId(c), name: c.name, input: c.arguments ?? {} });
                 }
             }
             raw.push({ role: "assistant", content: blocks.length ? blocks : [{ type: "text", text: NO_CONTENT }] });
@@ -132,7 +133,7 @@ function toAnthropicMessages(ctx, model) {
                 content: [
                     {
                         type: "tool_result",
-                        tool_use_id: m.toolCallId,
+                        tool_use_id: resultWireId(m.toolCallId),
                         content: inner,
                         ...(m.isError ? { is_error: true } : {}),
                     },
@@ -220,9 +221,8 @@ function closeToolUseBlock(acc) {
     const args = parseStreamedToolArgs(acc.toolJson);
     if (args === undefined)
         return undefined;
-    if (!acc.toolId)
-        acc.toolId = mintFallbackToolCallId("toolu_");
-    acc.closedTc = { type: "toolCall", id: acc.toolId, name: acc.toolName, arguments: args };
+    const { engineId, wireId } = admitToolCallId(acc.toolId, "toolu_");
+    acc.closedTc = { type: "toolCall", id: engineId, ...(wireId !== engineId ? { wireId } : {}), name: acc.toolName, arguments: args };
     return acc.closedTc;
 }
 export function createAnthropicBrain(config = {}) {

package/dist/brain/errors.d.ts

@@ -70,19 +70,7 @@ export declare class BrainError extends Error {
         apiError?: boolean;
     });
 }
-/**
- * The shape a provider ECHO field must have to be carried: the request id a provider states on a response
- * header (`AssistantMessage.requestId`, projected as `TaskResult.apiFailure.requestId`) and the model name it
- * reports answering (`AssistantMessage.responseModel`). Both are UPSTREAM BYTES that end up persisted in a
- * transcript and rendered by a UI, so one alphabet governs both: visible ASCII (0x21–0x7E — no space, no
- * control byte, no non-ASCII), 1–128 characters. A value outside it is dropped (the field is absent), never
- * truncated or rewritten; the empty string is outside it. No flags, so `test` is stateless. This object is the
- * consumer's copy: the engine judges with its own instance built from the same source, so recompiling or
- * otherwise mutating this one cannot change what the engine admits.
- */
-export declare const PROVIDER_ECHO_SHAPE: RegExp;
-/** Does `value` fit {@link PROVIDER_ECHO_SHAPE}? A non-string answers `false` (a JS caller's number is not an echo). */
-export declare function isProviderEchoShape(value: string): boolean;
+export { isProviderEchoShape, PROVIDER_ECHO_SHAPE } from "./provider-echo-shape.js";
 /** How the brains read one provider echo value: a non-string or the empty string states nothing (`absent` — no field,
  *  nothing counted); a string in {@link isProviderEchoShape} is `carried`; any other string is `refused` (dropped and
  *  counted as `echo_dropped`). */
@@ -180,4 +168,3 @@ export declare function brainErrorCodeOf(e: unknown): BrainErrorCode | undefined
  *  each layer's `code:`-prefixed message and skipping layers the parent's message already contains;
  *  a causeless error renders as its plain message. */
 export declare function describeNetworkError(e: unknown): string;
-export {};

package/dist/brain/errors.js

@@ -1,5 +1,6 @@
 import { isErrorLike, readMember, thrownText } from "../core/thrown-value.js";
 import { emitBrainTelemetry } from "./status-sink.js";
+import { isProviderEchoShape } from "./provider-echo-shape.js";
 export const ZERO_USAGE = {
     input: 0,
     output: 0,
@@ -31,12 +32,7 @@ export class BrainError extends Error {
     }
 }
 const REQUEST_ID_HEADERS = ["request-id", "x-request-id"];
-const PROVIDER_ECHO_SOURCE = "^[\\x21-\\x7E]{1,128}$";
-const providerEchoShape = new RegExp(PROVIDER_ECHO_SOURCE);
-export const PROVIDER_ECHO_SHAPE = new RegExp(PROVIDER_ECHO_SOURCE);
-export function isProviderEchoShape(value) {
-    return typeof value === "string" && providerEchoShape.test(value);
-}
+export { isProviderEchoShape, PROVIDER_ECHO_SHAPE } from "./provider-echo-shape.js";
 export function providerEchoReading(value) {
     if (typeof value !== "string" || value.length === 0)
         return "absent";

package/dist/brain/open-responses.js

@@ -2,7 +2,7 @@ import {} from "../internal/llm.js";
 import { BrainError } from "./errors.js";
 import { DEGENERATE_MESSAGE, trimDegenerateTail } from "./repetition.js";
 import { STREAM_TORN_WARNING, createRepetitionPoll, noteResponseModel, parseStreamedToolArgs } from "./stream-shared.js";
-import { mintFallbackToolCallId } from "./tool-call-id.js";
+import { admitToolCallId, providerResultIds, providerToolCallId } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders } from "./request-params.js";
@@ -80,6 +80,7 @@ function toResponsesInput(ctx, model, replayReasoning) {
         });
         pendingImages = [];
     };
+    const resultWireId = providerResultIds(ctx.messages);
     for (const m of ctx.messages) {
         if (m.role !== "toolResult")
             flushImages();
@@ -113,7 +114,7 @@ function toResponsesInput(ctx, model, replayReasoning) {
             if (text !== "")
                 out.push({ type: "message", role: "assistant", content: [{ type: "output_text", text }] });
             for (const tc of toolCalls) {
-                out.push({ type: "function_call", call_id: tc.id, name: tc.name, arguments: JSON.stringify(tc.arguments ?? {}) });
+                out.push({ type: "function_call", call_id: providerToolCallId(tc), name: tc.name, arguments: JSON.stringify(tc.arguments ?? {}) });
             }
         }
         else if (m.role === "toolResult") {
@@ -132,11 +133,11 @@ function toResponsesInput(ctx, model, replayReasoning) {
             const finalText = errorNote === undefined ? withVisionNote : withVisionNote ? `${withVisionNote}\n${errorNote}` : errorNote;
             out.push({
                 type: "function_call_output",
-                call_id: m.toolCallId,
+                call_id: resultWireId(m.toolCallId),
                 output: functionCallOutputText(finalText, images.length > 0, m.content),
             });
             for (const img of images)
-                pendingImages.push({ toolCallId: m.toolCallId, data: img.data, mimeType: img.mimeType });
+                pendingImages.push({ toolCallId: resultWireId(m.toolCallId), data: img.data, mimeType: img.mimeType });
         }
     }
     flushImages();
@@ -206,9 +207,8 @@ function closeFunctionCall(acc) {
     const args = parseStreamedToolArgs(acc.args);
     if (args === undefined)
         return undefined;
-    if (!acc.callId)
-        acc.callId = mintFallbackToolCallId("call_");
-    acc.closedTc = { type: "toolCall", id: acc.callId, name: acc.name, arguments: args };
+    const { engineId, wireId } = admitToolCallId(acc.callId, "call_");
+    acc.closedTc = { type: "toolCall", id: engineId, ...(wireId !== engineId ? { wireId } : {}), name: acc.name, arguments: args };
     return acc.closedTc;
 }
 function mapTerminalStopReason(incompleteReason, hadToolCalls) {

package/dist/brain/openai.js

@@ -2,7 +2,7 @@ import {} from "../internal/llm.js";
 import { repairTextToolCalls } from "./tool-call-repair.js";
 import { DEGENERATE_MESSAGE, trimDegenerateTail } from "./repetition.js";
 import { STREAM_TORN_WARNING, createRepetitionPoll, noteResponseModel, parseStreamedToolArgs } from "./stream-shared.js";
-import { mintFallbackToolCallId } from "./tool-call-id.js";
+import { admitToolCallId, providerResultIds, providerToolCallId } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders } from "./request-params.js";
@@ -20,9 +20,8 @@ function closeToolCallAccum(acc) {
     const args = parseStreamedToolArgs(acc.args);
     if (args === undefined)
         return undefined;
-    if (!acc.id)
-        acc.id = mintFallbackToolCallId("call_");
-    acc.closedTc = { type: "toolCall", id: acc.id, name: acc.name, arguments: args };
+    const { engineId, wireId } = admitToolCallId(acc.id, "call_");
+    acc.closedTc = { type: "toolCall", id: engineId, ...(wireId !== engineId ? { wireId } : {}), name: acc.name, arguments: args };
     return acc.closedTc;
 }
 function textOf(content) {
@@ -174,6 +173,7 @@ function toOpenAIMessages(ctx, replayThinking = true, model) {
         });
         pendingImages = [];
     };
+    const resultWireId = providerResultIds(ctx.messages);
     for (const m of ctx.messages) {
         if (m.role !== "toolResult")
             flushImages();
@@ -201,7 +201,7 @@ function toOpenAIMessages(ctx, replayThinking = true, model) {
             }
             if (toolCalls.length > 0) {
                 msg.tool_calls = toolCalls.map((tc) => ({
-                    id: tc.id,
+                    id: providerToolCallId(tc),
                     type: "function",
                     function: { name: tc.name, arguments: JSON.stringify(tc.arguments ?? {}) },
                 }));
@@ -224,11 +224,11 @@ function toOpenAIMessages(ctx, replayThinking = true, model) {
             const finalText = errorNote === undefined ? text : text ? `${text}\n${errorNote}` : errorNote;
             out.push({
                 role: "tool",
-                tool_call_id: m.toolCallId,
+                tool_call_id: resultWireId(m.toolCallId),
                 content: toolResultText(finalText, images.length > 0, m.content),
             });
             for (const img of images)
-                pendingImages.push({ toolCallId: m.toolCallId, data: img.data, mimeType: img.mimeType });
+                pendingImages.push({ toolCallId: resultWireId(m.toolCallId), data: img.data, mimeType: img.mimeType });
         }
     }
     flushImages();

package/dist/brain/provider-echo-shape.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The provider echo shape — the ONE alphabet for upstream bytes the engine carries verbatim (#1204): visible ASCII
+ * (0x21–0x7E — no space, no control byte, no non-ASCII), 1–128 characters. The echo fields (`requestId`,
+ * `responseModel`) are carried or dropped by it, and a provider-minted tool-call id is admitted verbatim or folded
+ * by it (`tool-call-id.ts`).
+ *
+ * Zero-dependency leaf: `tool-call-id.ts` (itself a leaf, see its header) reads the shape from here. `errors.ts`
+ * re-exports the two public names, which is where the package root takes them from.
+ */
+/** The longest value the shape admits. */
+export declare const PROVIDER_ECHO_MAX_CHARS = 128;
+/**
+ * The shape a provider ECHO field must have to be carried: the request id a provider states on a response
+ * header (`AssistantMessage.requestId`, projected as `TaskResult.apiFailure.requestId`) and the model name it
+ * reports answering (`AssistantMessage.responseModel`). Both are UPSTREAM BYTES that end up persisted in a
+ * transcript and rendered by a UI, so one alphabet governs both: visible ASCII (0x21–0x7E — no space, no
+ * control byte, no non-ASCII), 1–128 characters. A value outside it is dropped (the field is absent), never
+ * truncated or rewritten; the empty string is outside it. No flags, so `test` is stateless. This object is the
+ * consumer's copy: the engine judges with its own instance built from the same source, so recompiling or
+ * otherwise mutating this one cannot change what the engine admits.
+ */
+export declare const PROVIDER_ECHO_SHAPE: RegExp;
+/** Does `value` fit {@link PROVIDER_ECHO_SHAPE}? A non-string answers `false` (a JS caller's number is not an echo). */
+export declare function isProviderEchoShape(value: string): boolean;
+/** Is every character of `value` in the shape's alphabet, whatever its length? (`""` answers `true`.) */
+export declare function fitsProviderEchoCharset(value: string): boolean;

package/dist/brain/provider-echo-shape.js

@@ -0,0 +1,12 @@
+const PROVIDER_ECHO_CHARSET = "\\x21-\\x7E";
+export const PROVIDER_ECHO_MAX_CHARS = 128;
+const PROVIDER_ECHO_SOURCE = `^[${PROVIDER_ECHO_CHARSET}]{1,${PROVIDER_ECHO_MAX_CHARS}}$`;
+const providerEchoShape = new RegExp(PROVIDER_ECHO_SOURCE);
+const providerEchoChars = new RegExp(`^[${PROVIDER_ECHO_CHARSET}]*$`);
+export const PROVIDER_ECHO_SHAPE = new RegExp(PROVIDER_ECHO_SOURCE);
+export function isProviderEchoShape(value) {
+    return typeof value === "string" && providerEchoShape.test(value);
+}
+export function fitsProviderEchoCharset(value) {
+    return providerEchoChars.test(value);
+}

package/dist/brain/stream-engine.d.ts

@@ -96,7 +96,8 @@ export declare function shouldRetryHeaderVerdict(res: Response | undefined): boo
  * {@link WAITING_FIRST_TOKEN_AFTER_MS}, and one more every {@link WAITING_FIRST_TOKEN_EVERY_MS} after
  * that, until the first token lands, the watchdog fires, or the attempt ends. A short wait (under the
  * threshold) announces nothing — the frame exists for the unattended "no answer for a minute" case,
- * not for every request. The same 30s slice the retry countdown re-announces on.
+ * not for every request. A wait whose watchdog fires AT the threshold is disclosed once, at that
+ * instant, before the cut is announced. The same 30s slice the retry countdown re-announces on.
  */
 export declare const WAITING_FIRST_TOKEN_AFTER_MS = 30000;
 export declare const WAITING_FIRST_TOKEN_EVERY_MS = 30000;

package/dist/brain/stream-engine.js

@@ -337,29 +337,40 @@ export function runStreamingBrain(args) {
         const idleTimeoutMs = resolveWatchdogMs(config.idleTimeoutMs, stallTimeouts?.idleMs, STALL_IDLE_MS, "idleTimeoutMs");
         const firstByteRetryBudget = resolveFirstByteRetries(config.firstByteRetries);
         const armWaitDisclosure = (ceilingMs) => {
-            if (!(ceilingMs > WAITING_FIRST_TOKEN_AFTER_MS))
-                return { stop: () => undefined };
+            if (!(ceilingMs >= WAITING_FIRST_TOKEN_AFTER_MS))
+                return { stop: () => undefined, expire: () => undefined };
             const startedAt = Date.now();
             const emitWaitFrame = bindBrainStatusEmitter();
             let timer;
             let stopped = false;
+            let disclosed = false;
+            const disclose = () => {
+                disclosed = true;
+                announcedWait = true;
+                emitWaitFrame({ phase: "waiting_first_token", detail: "waiting for the first token", elapsedMs: Date.now() - startedAt, timeoutMs: ceilingMs });
+            };
             const schedule = (delayMs) => {
                 timer = setTimeout(() => {
                     timer = undefined;
                     if (stopped || Date.now() - startedAt >= ceilingMs)
                         return;
-                    announcedWait = true;
-                    emitWaitFrame({ phase: "waiting_first_token", detail: "waiting for the first token", elapsedMs: Date.now() - startedAt, timeoutMs: ceilingMs });
+                    disclose();
                     schedule(WAITING_FIRST_TOKEN_EVERY_MS);
                 }, delayMs);
             };
             schedule(WAITING_FIRST_TOKEN_AFTER_MS);
+            const stop = () => {
+                stopped = true;
+                if (timer)
+                    clearTimeout(timer);
+                timer = undefined;
+            };
             return {
-                stop: () => {
-                    stopped = true;
-                    if (timer)
-                        clearTimeout(timer);
-                    timer = undefined;
+                stop,
+                expire: () => {
+                    if (!stopped && !disclosed)
+                        disclose();
+                    stop();
                 },
             };
         };
@@ -378,13 +389,13 @@ export function runStreamingBrain(args) {
                     throw e;
                 }
                 const window = firstByteWindow(firstByteTimeoutMs, Buffer.byteLength(req.body), firstByteStalls);
+                const headerWait = armWaitDisclosure(window.windowMs);
                 const cc = createAttemptController(window.windowMs, signal);
                 let r;
                 let netErr;
                 let firstByteStall;
                 requestIdSeen = undefined;
                 attemptPartial = undefined;
-                const headerWait = armWaitDisclosure(window.windowMs);
                 const stalledAtFirstByte = () => {
                     firstByteWindowsWaited.push(window.windowMs);
                     return {
@@ -423,7 +434,10 @@ export function runStreamingBrain(args) {
                     }
                 }
                 finally {
-                    headerWait.stop();
+                    if (firstByteStall !== undefined)
+                        headerWait.expire();
+                    else
+                        headerWait.stop();
                 }
                 if (r && r.ok && r.body) {
                     cc.clearTimer();
@@ -587,14 +601,14 @@ export function runStreamingBrain(args) {
             let firstTokenSeen = false;
             let firedFirstTokenDeadlineMs;
             let ftTimer;
-            let firstTokenWait = { stop: () => undefined };
+            let firstTokenWait = { stop: () => undefined, expire: () => undefined };
             if (firstTokenTimeoutMs && firstTokenTimeoutMs > 0) {
+                firstTokenWait = armWaitDisclosure(firstTokenTimeoutMs);
                 ftTimer = setTimeout(() => {
                     firedFirstTokenDeadlineMs = firstTokenTimeoutMs;
-                    firstTokenWait.stop();
+                    firstTokenWait.expire();
                     void reader.cancel().catch(() => undefined);
                 }, firstTokenTimeoutMs);
-                firstTokenWait = armWaitDisclosure(firstTokenTimeoutMs);
             }
             let firedIdleDeadlineMs;
             let idleTimer;

package/dist/brain/tool-call-id.d.ts

@@ -1,21 +1,33 @@
-/**
- * REF-C5 — the ONE place a **fallback tool-call id** is minted.
- *
- * When a provider's wire frame carries no `id` for a tool call, the adapter must still hand downstream a
- * non-`undefined`, process-unique handle: the whole execution/pairing chain keys on it (a tool_use must pair
- * with its tool_result, and an in-stream executor's result must pair with the final content). Three adapters
- * used to hand-roll the same `Math.random().toString(36)` short id with only their protocol prefix differing.
- *
- * The prefix is the caller's protocol identity (`toolu_` / `call_` / `repair_<name>_`) and is the ONLY
- * parameter — the id BODY is deliberately opaque and uniform: no length/charset options, so there is exactly
- * one collision profile to reason about for every lane.
- *
- * Zero-dependency leaf on purpose: `tool-call-repair.ts` is a pure parser with no runtime imports, so this
- * must not drag a stream/telemetry dependency in. Internal module: not re-exported from `src/index.ts`.
- */
+import type { Message } from "../internal/llm.js";
+/** The character every folded id carries and no admitted id may: what keeps the two arms' outputs apart. */
+export declare const TOOL_CALL_ID_FOLD_SEPARATOR = "~";
 /**
  * Mint a placeholder tool-call id under `prefix`. Uniqueness is per-process and probabilistic
  * (`Math.random`), which is what every call site already relied on — the id never crosses a trust boundary
  * and is never a capability; it only has to not collide inside one response.
  */
 export declare function mintFallbackToolCallId(prefix: string): string;
+/** The two ids of one admitted tool call (see the module header). Equal unless the admission folded. */
+export interface AdmittedToolCallId {
+    readonly engineId: string;
+    readonly wireId: string;
+}
+/** Why a raw id is folded: `"charset"` — it holds a character outside the admitted alphabet (a control byte, a space,
+ *  a non-ASCII unit, or the fold separator); `"length"` — every character is admitted and it is longer than 128. */
+export type ToolCallIdFoldReason = "charset" | "length";
+/** The fold reading of a non-empty raw id: `undefined` ⇒ admitted verbatim; otherwise why it is folded. */
+export declare function toolCallIdFoldReason(raw: string): ToolCallIdFoldReason | undefined;
+/** Admit a provider-minted tool-call id (see the module header for the three arms). Pure: announcing a fold is the
+ *  run's job, read off `ToolCall.wireId`. */
+export declare function admitToolCallId(raw: unknown, prefix: string): AdmittedToolCallId;
+/** The id a provider is handed for this call: its `wireId` when it carries one (a non-empty string), else its `id`. */
+export declare function providerToolCallId(call: {
+    readonly id: string;
+    readonly wireId?: unknown;
+}): string;
+/**
+ * The id a provider is handed for the tool RESULT of `engineId`, read off the calls in the same request's messages:
+ * a result carries only the engine id, and the call it answers carries the provider's. A result whose call is not
+ * in the messages is handed on under its engine id.
+ */
+export declare function providerResultIds(messages: readonly Message[]): (engineId: string) => string;

package/dist/brain/tool-call-id.js

@@ -1,3 +1,46 @@
+import { createHash } from "node:crypto";
+import { fitsProviderEchoCharset, isProviderEchoShape } from "./provider-echo-shape.js";
+export const TOOL_CALL_ID_FOLD_SEPARATOR = "~";
+const FOLD_BASE_CHARS = 32;
+const FOLD_DIGEST_HEX = 32;
 export function mintFallbackToolCallId(prefix) {
     return `${prefix}${Math.random().toString(36).slice(2)}`;
 }
+export function toolCallIdFoldReason(raw) {
+    const separated = raw.includes(TOOL_CALL_ID_FOLD_SEPARATOR);
+    if (!separated && isProviderEchoShape(raw))
+        return undefined;
+    return !separated && fitsProviderEchoCharset(raw) ? "length" : "charset";
+}
+export function admitToolCallId(raw, prefix) {
+    if (typeof raw !== "string" || raw === "") {
+        const id = mintFallbackToolCallId(prefix);
+        return { engineId: id, wireId: id };
+    }
+    return { engineId: engineIdOf(raw), wireId: raw };
+}
+function engineIdOf(raw) {
+    if (toolCallIdFoldReason(raw) === undefined)
+        return raw;
+    const base = raw.slice(0, FOLD_BASE_CHARS).replace(/[^\x21-\x7D]/g, "-");
+    const digest = createHash("sha256").update(Buffer.from(raw, "utf16le")).digest("hex").slice(0, FOLD_DIGEST_HEX);
+    return `${base}${TOOL_CALL_ID_FOLD_SEPARATOR}${digest}`;
+}
+export function providerToolCallId(call) {
+    return typeof call.wireId === "string" && call.wireId !== "" ? call.wireId : call.id;
+}
+export function providerResultIds(messages) {
+    const byEngineId = new Map();
+    for (const m of messages) {
+        if (m.role !== "assistant" || !Array.isArray(m.content))
+            continue;
+        for (const c of m.content) {
+            if (c?.type !== "toolCall" || typeof c.id !== "string")
+                continue;
+            const wire = providerToolCallId(c);
+            if (wire !== c.id)
+                byEngineId.set(c.id, wire);
+        }
+    }
+    return (engineId) => byEngineId.get(engineId) ?? engineId;
+}

package/dist/core/ask-question.d.ts

@@ -279,36 +279,6 @@ export interface AskUserQuestionToolOptions {
      *  would let a LATER question inherit the claim that an operator approved it. */
     redeemedApprovalQuestionsHash?: string;
 }
-/**
- * Durable ask (design/64 TC-5.4 — ABOVE CC, the disconnected-human case): instead of the headless
- * "proceed with your best judgment" default, an AskUserQuestion **suspends the task durably** and the
- * answer resumes it — built ENTIRELY from existing primitives, no new gate kind.
- *
- * **The park is the fallback, not the mandate.** An adjudicated question parks durably UNLESS this run
- * has a live question face (see {@link isLiveQuestionFace}), in which case the engine routes the question
- * to that face and the answer arrives in-stream — same turn, no checkpoint, no rebuild. The park is what
- * happens when nobody is there: no live face, the face affirming nobody is reachable, or a control-plane
- * `forceDurableGate` that mandates the durable breakpoint regardless. A deployment that wired a live face
- * AND wants every question parked anyway states that with `forceDurableGate` (or by not wiring the face).
- *
- *  1. Run the task with `durableApproval` + a durable `CheckpointStore` (+ durable session/offload
- *     stores) and `combinePolicies(createDurableQuestionPolicy(), yourPolicy)`. The policy adjudicates
- *     the AskUserQuestion call `ask`; in durable mode that suspends BEFORE the tool executes —
- *     `onQuestion` is never called on the suspend side, so mount the tool with
- *     {@link QUESTION_AWAITS_RESUME} when no live human is connected.
- *  2. The HITL surface reads the questions from `checkpoint.pendingAction.args.questions` and collects
- *     the human's {@link QuestionAnswer} out-of-band (hours/days later, any replica).
- *  3. `runner.resume(token, { gate: "policy_ask", decision: "allow", boundCallId:
- *     checkpoint.pendingAction.toolCallId }, { ...taskConfig, onQuestion: async () => answer })` — the resume
- *     re-mounts the tool with the answer closure; the pending call executes against it and the model
- *     continues with "The user answered: …". `boundCallId` (design/80 D-1) must name the pending call the
- *     human answered, or the resume is rejected (`checkpoint.invalid_outcome`).
- *
- * A deployment that wants the CC-style threshold form ("wait N minutes for a live human, then go
- * durable") implements it inside its own policy: return `allow` while a human is connected (the live
- * `onQuestion` answers synchronously) and `ask` when none is — the sync-vs-durable choice is exactly
- * one policy decision.
- */
 export declare function createDurableQuestionPolicy(): ToolPolicy;
 /**
  * Placeholder {@link OnQuestion} that mounts the AskUserQuestion tool on a worker with NO live human