@sema-agent/sdk 20.0.3 → 21.1.0

package/openapi.yaml

@@ -423,7 +423,7 @@ paths:
         prepare-time refusal code that HAS a status in the server's per-code triage table (`resume_at.*` — `resume_at.not_found` is 404, the rest 422 —, governance codes,
         `rewind.store_unconfigured` / `rewind.capture_disabled` / `rewind.child_scope_unsupported` / `rewind_snapshot.unresolvable`, the
         registered `config.*` codes incl. the three roster-bound ones and — server >= 7.116.0 — `config.invalid_checkpoint_store` (400) and
-        `config.user_invoked_skill_unknown` (400: top-level `userInvokedSkills` named a skill this run does not carry) and — server >= 7.117.0 — `config.image_invalid` (400: an inline image failed the engine's byte admission; `error` starts with `TaskSpec.images: `), `corrupt_session`; codes outside the table, e.g. `rewind.invalid_spec`, stay
+        `config.user_invoked_skill_unknown` (400: top-level `userInvokedSkills` named a skill this run does not carry) and — server >= 7.117.0 — `config.image_invalid` (400: an inline image failed the engine's byte admission; `error` starts with `TaskSpec.images: `) and — server >= 7.126.0 — `config.tool_face_control` (400: a name in `allowTools` / `excludeTools` that no tool of this run answers to, `allowTools: ["mcp__*"]`, `excludeTools: ["*"]`, or an `excludeTools` entry that reaches a protocol tool this leg depends on; the engine rejects before the run starts, never silently ignoring the name; `error` is the engine's sentence naming the entry, its list and why), `corrupt_session`; codes outside the table, e.g. `rewind.invalid_spec`, stay
         200 with a failed body) answers its 4xx / 5xx ERROR BODY only when the whole submission did ZERO WORK (cumulative
         `stats.turns === 0` AND `stats.tokens === 0` — the common case: nothing billed, not idempotency-cached). When a
         `verify` / `cascade` run's earlier tier already ran turns and only the last tier is refused, the SAME code arrives
@@ -435,6 +435,8 @@ paths:
         in `result` (a nested `TaskResult`), and `wiringManifest` / `notice` are absent. A same-key duplicate that is still IN FLIGHT in the same process is merged
         instead and gets the first answer's bytes (no `replay` key). Only a submit that builds a row can be replayed this way (a run store AND a `sessionId`);
         otherwise a settled key re-runs. A key whose row the caller cannot read answers 409 `conflict.run_exists`.
+        🔴 SAME KEY = SAME BODY (server >= 7.126.0, contract §0.7): resubmitting the same `Idempotency-Key` with a DIFFERENT request body is 409
+        `conflict.idempotency_payload_mismatch` — not replayed, not created, the row untouched. To retry, resend the SAME body; for a different request use a NEW key.
       parameters:
         - $ref: '#/components/parameters/IdempotencyKey'
       requestBody:
@@ -483,6 +485,12 @@ paths:
             or at a row that is not the one this submit's `taskId` names. The sentence is `a run already exists for this submission's taskId or Idempotency-Key`
             (the code is unchanged; only the sentence moved); nothing about the row is echoed (no cross-tenant oracle). Submit under a NEW key. On
             `POST /v1/tasks/stream`, once the stream is open the same refusal arrives as the `done` frame's `{status:"failed", errorCode, errorMessage}`.
+            `conflict.idempotency_payload_mismatch` (server >= 7.126.0, contract §0.7 "same request = same body"): the submit's `Idempotency-Key` is already bound to a run row you CAN read,
+            and the body of the request that bound it differs from this one (normalization: JSON keys recursively sorted, `taskId` removed, headers never count; a value, a nested value, an
+            extra key or a reordered array is a different request). Not replayed, not created, the row untouched; the body is `{ error, errorCode }` and echoes neither the key nor the row.
+            Resend the SAME body to retry, or use a NEW key for a different request. Only the key's own binding is compared (a hit by `taskId` alone, or a row created without a key, is not
+            body-compared). A2A `message/send` never meets it. On `POST /v1/tasks/stream` it is a clean JSON 409 when found at the door; once the stream is open it arrives as the `done` frame's
+            `{status:"failed", errorCode:"conflict.idempotency_payload_mismatch", errorMessage}`.
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -1917,7 +1925,7 @@ paths:
           # (declared 2026-07-31) errorCode "request.id_invalid" — the path sessionId must decode to a
           # canonical uuid of ANY version (`routes/sessions.ts`; server >= 7.125.0 — the ONE shape gate shared with sync / fork / policy;
           # <= 7.124.x accepted only uuidv7 here); a malformed id never reaches the store. Branch on the code, never the sentence
-          # (the sentence changed with the gate: "invalid session id (must be a canonical uuid)").
+          # (the sentence changed with the gate, and again when the submit door joined it).
           $ref: '#/components/responses/BadRequest'
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
@@ -4278,9 +4286,10 @@ paths:
       description: >
         READ-ONLY catalog of `@mention`-pickable models. The user selects a model PER-TASK by typing `@<name>` in
         the objective body (the service allowlist-parses it; the client never re-decides). Envelope
-        `{ models, default, defaultModel, droppedEntries? }` — see `ModelsResponse` (`default` = the deployment default model id,
+        `{ models, default, defaultModel, droppedEntries?, candidateRejected? }` — see `ModelsResponse` (`default` = the deployment default model id,
         display-only — the internal `default` alias is hidden; `defaultModel` = the same default as `{id, name?}` in one piece;
-        `droppedEntries` = server >= 7.123.0, the catalog entries the read leg dropped, in the same generation as `models`).
+        `droppedEntries` = server >= 7.123.0, the catalog entries the read leg dropped, in the same generation as `models`;
+        `candidateRejected` = server >= 7.126.0, present-iff the configuration in force is the fallback one because the candidate judge rejected the latest candidate).
         🔴 NON-SECRET: only name/id/provider/reasoning/vision + the E4/E7 capability fields — NEVER baseUrl/apiKey/
         headers (the service strips them). Fail-safe: on error, render an empty picker (never block).
       responses:
@@ -6933,6 +6942,8 @@ components:
         server >= 7.125.0 also: `conflict.run_exists` — on a submit (`POST /v1/runs`, `/v1/tasks`, `/v1/tasks/stream`), the `Idempotency-Key` /
         `body.taskId` points at a run the caller cannot read, or the two keys of one submit point at different rows. The sentence is
         `a run already exists for this submission's taskId or Idempotency-Key` (code unchanged, sentence new; nothing echoed). Submit again under a new key.
+        server >= 7.126.0 also: `conflict.idempotency_payload_mismatch` — the same `Idempotency-Key` carried with a DIFFERENT request body than the one that bound it (contract §0.7:
+        not replayed, not created, the row untouched; resend the SAME body to retry, a NEW key for a different request).
       content:
         application/json:
           schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -6996,13 +7007,12 @@ components:
       description: >
         Primary routing axis (one image serves many). Selects model/tools/skills/prompt. OPEN: a stock server's builtin
         table is `code` (factory default) / `default` / `code-review` / `scan` (SDK `KNOWN_SCENARIOS`, checked against the
-        published server's `buildScenarios()` table) plus `discuss` — still accepted today, deliberately not in
-        `KNOWN_SCENARIOS` because it sits inside core #1056's (7.35.0) retirement sweep (server S-630 ②) — and a deployment may
-        register more through the registry. A name
+        published server's `buildScenarios()` table; servers <= 7.125.x also listed `discuss`, retired with the whole team-orchestration surface at
+        7.126.0, no alias) — and a deployment may register more through the registry. A name
         the caller SENDS that the deployment does not serve is a loud 400 `scenario_unknown` (server >= 5.1.0, the body
         carries the live vocabulary) — the silent fold to `default` exists only on the server-side ASSIGNMENT chain.
         Retired, no alias: `oa` (5.0.0), `autonomous` ([2400] CAPS-OPS-11), `team` (renamed `discuss`, server #273 / C-R14;
-        alias withdrawn at #342 — the discuss scenario's body key `team`, which picks the roster template, kept its name).
+        alias withdrawn at #342).
       examples: ['code', 'default', 'code-review', 'scan']
 
     ScenarioDetail:
@@ -7130,8 +7140,8 @@ components:
         name: { type: string, description: 'the `subagent_type` the model passes to Task. Non-empty, ≤64 chars, UNIQUE per request.' }
         whenToUse: { type: string, description: 'when the model should delegate to this agent (shown in the Task tool''s agent list). ≤4096 chars.' }
         whenToUseLean: { type: string, description: 'compact variant of `whenToUse` for lean tool listings. ≤4096 chars.' }
-        allowTools: { type: array, items: { type: string }, description: 'allowlist of tool names. Omit ⇒ inherit ALL tools.' }
-        denyTools: { type: array, items: { type: string }, description: 'denylist (SUBTRACTIVE — applied after `allowTools`).' }
+        allowTools: { type: array, items: { type: string }, description: 'allowlist of tool names. Omit ⇒ inherit ALL tools. server >= 7.126.0: the names are judged by the ENGINE, one selector shared with the root run''s `allowTools` / `excludeTools`; a name no tool answers to => the run is rejected with the terminal code `config.agent.unknown_tool` (not an HTTP code).' }
+        denyTools: { type: array, items: { type: string }, description: 'denylist (SUBTRACTIVE — applied after `allowTools`). server >= 7.126.0: same engine-judged selector as `allowTools`; `Tool(content)` => the whole tool.' }
         skills:
           type: array
           description: 'skills preloaded into the agent.'
@@ -7174,10 +7184,9 @@ components:
     TaskRequest:
       type: object
       description: >
-        Common request body. `[additionalProperties]` mirrors the service passthrough — scenario-specific fields
-        (code-review's `repo`/`lenses`/`rounds`, etc.) ride here. NOTE (sdk 9.1.0): `council`/`debate` used to be
-        named here as passthrough examples, but the service declares them as TOP-LEVEL typed keys and reads them
-        on two seams outside the scenario builder, so they are declared properties below.
+        Common request body. `[additionalProperties]` mirrors the service passthrough — scenario-specific fields (today only `repo`) ride here.
+        server 7.126.0 (hard BREAKING, no alias) took the declared keys `council` / `debate` and the scenario passthrough keys `businessContext` / `lenses` / `rounds` / `team` out of the accepted set with the team-orchestration
+        surface: sending one is 400 `request.body_shape` listing it in `unknownKeys`. The open `additionalProperties` here does NOT catch them — the server's 400 is the notice.
       required: [objective]
       additionalProperties: true
       properties:
@@ -7200,7 +7209,12 @@ components:
         scenario: { $ref: '#/components/schemas/Scenario' }
         sessionId:
           type: string
-          description: Continue a conversation (same sessionId across turns). Omit on first turn → service mints one.
+          description: >
+            Continue a conversation (same sessionId across turns). Omit on first turn → service mints one.
+            server >= 7.126.0 (contract section 0.8): a caller-supplied session id has ONE shape law on every door — a canonical uuid of ANY version (lowercase 8-4-4-4-12 hex, version nibble 1-8; a client-preset v4 and the
+            server-minted v7 both pass), the same judge `fork` / `delete` / `policy` / 2c sync use. Anything else is 400 `request.id_invalid` (branch on the CODE, never the sentence). A self-chosen name is not a
+            session id any more (keep your own name-to-uuid mapping); the old "at most 64 characters" cap and its `request.field_invalid` refusal are gone; the empty string is NO LONGER "absent" (it is a non-uuid => 400;
+            omit the key for a new session). Shape-only: it does not check that the session exists. A2A `contextId` rides this key and is judged by the same rule.
         requireExistingSession:
           type: boolean
           description: >
@@ -7306,23 +7320,6 @@ components:
             the 32-entry cap the surplus entries are DROPPED and named too — same disposition as a malformed
             entry, not a 400.
           items: { $ref: '#/components/schemas/A2aServerSpec' }
-        council:
-          type: boolean
-          description: >
-            The `code-review` scenario's EXPENSIVE tier — fan the review out to N parallel lenses plus an
-            arbiter (`run_council`) instead of the lead reviewing in-line. Read on TWO seams and both matter:
-            the scenario builder mounts the council tool, and spec resolution treats it as an EXPLICIT team
-            declaration (widening the task's wall-clock tenancy budget and suppressing the value router's
-            auto-escalation). Only a literal `true` counts on both seams. On other scenarios the first seam is
-            inert while the second still applies.
-        debate:
-          type: boolean
-          description: >
-            Run the L2 peer-debate rounds on top of `council`. 🔴 The two seams are ASYMMETRIC — this is not a
-            standalone switch: the scenario builder reads it only INSIDE the `council === true` branch (sending
-            `debate:true` alone produces no debate rounds), while the explicit-team predicate is
-            `council || debate` (sending it alone still widens the budget and suppresses auto-escalation).
-            Literal `true` only, same as `council`.
         resumeAt:
           type: string
           description: >
@@ -7801,7 +7798,23 @@ components:
         excludeTools:
           type: array
           items: { type: string }
-          description: Tool names to withhold from this task's roster.
+          description: >
+            Tool names to withhold from this task's roster. server >= 7.126.0 (engine 7.49.0, contract G.9e): read with the SAME grammar as `allowTools`; a name that
+            NO tool answers to rejects the run before it starts with `config.tool_face_control` (sync leg 400, no token burned; streamed / background legs: a `failed` terminal with
+            the same code) instead of being silently ignored, and `"*"` is rejected on this list too (unmount-everything is only `excludeAllTools`).
+        allowTools:
+          type: array
+          items: { type: string }
+          description: >
+            (server >= 7.126.0, engine 7.49.0 #1623, contract G.9e) The run's AVAILABILITY SELECTOR, passed to the engine's `TaskSpec.allowTools` verbatim (the server reads nothing:
+            no complement, no entry filtering, `[]` is not folded to absent, not mixed with `settings.permissions.allow`). Available tools = everything this run mounts (caller tools,
+            hands, the engine's own tools, MCP / A2A, scenario and leg tools) ∩ `allowTools` − `excludeTools` (deny wins), computed by the engine once before the run starts.
+            `["*"]` = no list at this layer (same as absent); `[]` = give nothing; an entry is a wire name or alias, `Tool(content)` (the whole tool), `mcp__srv` / `mcp__srv__*` /
+            a tool-segment wildcard (`mcp__*` is rejected on this list). A leg's protocol tools (a delegated child's `ReportBlocked`, …) need no mention. A name that NO tool answers to
+            => `config.tool_face_control` (sync leg 400, no token burned; streamed / background legs: a `failed` terminal with the same code). Wrong shape (not a string array) =>
+            400 `request.field_invalid`, the same gate as `excludeTools` / `deferTools`. An engine older than 7.49.0 rejects loudly (400 `request.field_invalid` naming `allowTools`) —
+            never silently dropped (dropping a narrowing key widens). No capability bit: probe by key closure (<= 7.125.x answers `400 request.body_shape` with the name in
+            `unknownKeys`). The A2A inbound face (`message/send`) does not carry this key.
         excludeAllTools:
           type: boolean
           enum: [true]
@@ -8040,6 +8053,85 @@ components:
             🔴 On the wire it carries NO `token` — the same withholding rule as the top-level `paused` arm
             (see `PausedCause`); `gate` / `checkpointId` are present as usual.
             Absent on every failure the engine itself assembles.
+        detail:
+          allOf: [{ $ref: '#/components/schemas/TerminalFailureDetail' }]
+          description: >
+            The machine-readable account of the failure beside `code` (server >= 7.110.0 carried the `provider_rejected` arm; server >= 7.126.0 / core 7.49.0 it is a CLOSED union branching on `kind`,
+            three arms — see `TerminalFailureDetail`). Branch on `detail.kind`, never on `message`; new members join with a core minor, so a branch MUST keep a default arm. Present only when the arm that
+            named this result has such a fact to project; absent otherwise (absence is not an "older version" signal). The same object crosses three faces: the synchronous 200 body, the stream's `done.result`,
+            `GET /v1/runs/{taskId}` -> `result`.
+
+    TerminalFailureDetail:
+      description: >
+        `TerminalCause_failed.detail` (contract section 5.0a; core `TerminalFailureDetail`) — a CLOSED union branching on `kind`, three arms as of server 7.126.0. An UNKNOWN `kind` (a newer engine) is passed through
+        by the server with every string leaf redacted, never dropped or reshaped: a consumer treats it as the default arm.
+      oneOf:
+        - { $ref: '#/components/schemas/TerminalProviderRejectedDetail' }
+        - { $ref: '#/components/schemas/TerminalCodedDetail' }
+        - { $ref: '#/components/schemas/TerminalModelOutputInvalidDetail' }
+
+    TerminalProviderRejectedDetail:
+      type: object
+      additionalProperties: false
+      required: [kind, status]
+      description: >
+        The model provider REFUSED the request with a 4xx and that refusal is what named this result. 5xx, connect / stream failures, an in-band error inside a 200, a lock conflict, a request-build guard and every non-provider
+        failure carry no detail. 401 / 403 / 429 carry it too: to tell "the user can edit and resend", read `status` (or `code`), not whether `detail` is present.
+      properties:
+        kind: { const: provider_rejected }
+        status: { type: integer, minimum: 400, maximum: 499, description: 'The refusal''s HTTP status (same value as `apiFailure.status`).' }
+        code: { type: string, description: 'The provider''s own error word (`error.code`, else `error.type`); absent when the provider gave none or it is out of shape (1–128 visible ASCII).' }
+        providerCondition:
+          type: string
+          description: 'server >= 7.126.0 (core 7.49.0 #1454): what the refusal says about the account — the engine''s closed word (`quota_exhausted | throttled | overloaded | unknown | stop_other`), passed through verbatim; read as an OPEN set. The terminal reading of the verdict the call''s retry frames carried (`status.providerCondition`).'
+        providerConditionSource: { type: string, description: 'server >= 7.126.0: the evidence `providerCondition` rests on (`unified_header | provider_code | status`); present exactly when it is; read as an OPEN set.' }
+        providerResetAtMs: { type: number, description: 'server >= 7.126.0: epoch milliseconds when the window resets, carried beside a `quota_exhausted` condition.' }
+        route:
+          allOf: [{ $ref: '#/components/schemas/TerminalRequestRoute' }]
+          description: 'server >= 7.126.0: the route the refused request took, in KNOB words only (never a key value or a URL).'
+
+    TerminalRequestRoute:
+      type: object
+      additionalProperties: false
+      required: [credentialSource, root]
+      description: 'server >= 7.126.0 — `TerminalProviderRejectedDetail.route` (core `RequestRoute`): the route a refused request took, in KNOB words only (never a key value or a URL). All four words are read as OPEN sets.'
+      properties:
+        credentialSource: { type: string, description: 'Where the credential came from: `per-model | deployment-config | absent`.' }
+        carrier: { type: string, description: 'How it rode: `apiKey | header`; absent exactly when `credentialSource` is `absent`.' }
+        carrierBag: { type: string, description: 'Which header bag the auth header came from: `options | model | config`.' }
+        root: { type: string, description: 'Which knob named the request''s root: `model | deployment | lane-default`.' }
+
+    TerminalCodedDetail:
+      type: object
+      additionalProperties: false
+      required: [kind, detail]
+      description: >
+        server >= 7.126.0 — the run threw a coded error (this result''s `terminal.code`) whose throw site also stated a structured `detail` (for example a checkpoint error''s `{ reason }`). Present only when that error carried a
+        plain-object `detail` with at least one projectable member.
+      properties:
+        kind: { const: coded }
+        detail:
+          type: object
+          description: 'The thrown error''s `detail`: a JSON-plain snapshot (strings, finite numbers, booleans, null, arrays / plain objects of those; bounded). A member under a credential name stands as `"[redacted]"`; every string leaf passes the error-sentence redaction (credential shapes masked, paths kept).'
+          additionalProperties: true
+
+    TerminalModelOutputInvalidDetail:
+      type: object
+      additionalProperties: false
+      required: [kind, cause]
+      description: 'server >= 7.126.0 — the model''s final turn failed because its tool calls could not be executed. Same words as the `task.tool_turn_incomplete` notice.'
+      properties:
+        kind: { const: model_output_invalid }
+        cause: { type: string, enum: [truncated, unnamed], description: 'Why the calls were dropped: `truncated` = the arguments were cut before they parsed; `unnamed` = a call with no tool name.' }
+        outputLimit:
+          type: object
+          additionalProperties: false
+          required: [capStop]
+          description: 'Only beside `truncated`: the output-cap facts the stream reported.'
+          properties:
+            capStop: { type: boolean }
+            outputTokens: { type: number }
+            capTokens: { type: number }
 
     TerminalCause_blocked:
       type: object
@@ -8405,14 +8497,15 @@ components:
         The `done.result` of a submit REFUSED after the SSE stream was already open (`POST /v1/tasks/stream`): the status line is gone, so the refusal travels as the
         stream's terminal frame in the triple `{status:"failed", errorCode, errorMessage}` — the same code and sentence the JSON refusal body would have carried
         (server `src/http/routes/tasks.ts`). Two producers: (1) server >= 7.125.0 — the submit's key (or `body.taskId`) turned out, only at row-creation time, to point at a run row
-        the caller cannot read or that is not the one this submit names: `errorCode: "conflict.run_exists"` (contract §0.7; the frame carries `replay: true`); (2) a device-placement
+        the caller cannot read or that is not the one this submit names: `errorCode: "conflict.run_exists"` (contract §0.7; the frame carries `replay: true`); server >= 7.126.0 adds
+        `errorCode: "conflict.idempotency_payload_mismatch"` (the same key, found at row-creation time bound by a request with a different body; same projection); (2) a device-placement
         refusal (the placement error body's code and sentence). It is NOT an engine result and NOT `ActiveRunConflictDoneResult` (that one is `conflict.session_active_run` and requires
         `activeTaskId`). Branch on `errorCode`; the sentence is for people.
       additionalProperties: false
       required: [status, errorCode, errorMessage]
       properties:
         status: { const: failed }
-        errorCode: { type: string, description: 'Open string: `conflict.run_exists` (server >= 7.125.0) or the device-placement refusal code.' }
+        errorCode: { type: string, description: 'Open string: `conflict.run_exists` (server >= 7.125.0), `conflict.idempotency_payload_mismatch` (server >= 7.126.0) or the device-placement refusal code.' }
         errorMessage: { type: string, description: 'The refusal sentence (display only — never match on it).' }
 
     RunReceipt:
@@ -8446,22 +8539,48 @@ components:
     WorkspaceSyncCapability:
       type: object
       description: >
-        server >= 7.125.0 (contract appendix B.1 / B.1a) — the `GET /v1/capabilities` `workspaceSync` segment: EXACTLY two keys, key-for-key the server's `src/workspace-space.ts`
-        `WorkspaceSyncCapability`. Both are ALWAYS-PRESENT members of the object (B.1a); the object itself is present-iff (see `Capabilities.workspaceSync`).
+        server >= 7.125.0 (contract appendix B.1 / B.1a) — the `GET /v1/capabilities` `workspaceSync` segment, key-for-key the server's composite member table
+        `workspaceSync: [persist, keep, timeoutMs, cache]`. server >= 7.126.0: the members are PRESENT INDEPENDENTLY, each by its own facility — `persist` / `keep` / `timeoutMs` are
+        present-iff the SNAPSHOT STORE (the k8s lane AND the three `MINIO_*` keys; in 7.125.0 `persist` / `keep` were always-present members of the object and `timeoutMs` did not exist, so a 7.125.x body is `{ persist, keep }` — which this schema still accepts: only `persist` <-> `keep` are bound to each other, and `timeoutMs`, when present, needs both); `cache` is present-iff the BUILD-CACHE VOLUME is on
+        (the k8s lane AND `WORKSPACE_CACHE=volume`; independent of the snapshot store). The object itself is present-iff ANY member is present (see `Capabilities.workspaceSync`), so a deployment with the cache
+        volume on but no snapshot store answers an object with only `cache`: "the object is present" no longer implies `persist` is present. Read cross-run retention as `persist === "space"`.
       additionalProperties: false
-      required: [persist, keep]
+      minProperties: 1
+      dependentRequired:
+        persist: [keep]
+        keep: [persist]
+        timeoutMs: [persist, keep]
       properties:
         persist:
           type: string
           enum: [space, off]
           description: >
-            The operator knob `WORKSPACE_PERSIST` (default `off` — persistence is opt-in), a TWO-WORD closed set. `space` = the operator switched it on: the k8s `/workspace` persists across runs per session occupant. `off` = the snapshot
-            store IS wired but persistence is not switched on (the default, or the operator switched it off): a fresh workspace every run — NOT the same as the whole object being absent (absent = no such facility on this deployment).
+            The operator knob `WORKSPACE_PERSIST`, a TWO-WORD closed set, DEFAULT `space` (server >= 7.126.0; the 7.125.0 default was `off`). `space` = the k8s `/workspace` persists across runs per session occupant. `off` = the snapshot
+            store IS wired but the operator switched persistence off: a fresh workspace every run — NOT the same as the member being absent (absent = no snapshot store on this deployment). Present-iff the snapshot store; moves with `keep`.
         keep:
           type: integer
           minimum: 1
           maximum: 50
-          description: 'Snapshots kept per space (the session occupant) (`WORKSPACE_SNAPSHOT_KEEP`, an integer in [1, 50], default 3); older ones are deleted after each successful save.'
+          description: 'Snapshots kept per space (the session occupant) (`WORKSPACE_SNAPSHOT_KEEP`, an integer in [1, 50], default 3); older ones are deleted after each successful save. Present-iff the snapshot store; moves with `persist`.'
+        timeoutMs:
+          type: integer
+          minimum: 30000
+          maximum: 3600000
+          description: 'server >= 7.126.0 — the snapshot time bound (`WORKSPACE_SNAPSHOT_TIMEOUT_MS`, milliseconds, an integer in [30000, 3600000], default 300000): the wall-clock bound of the end-of-run upload and of the restore when the sandbox connects, and the longest the next run waits for the previous run to finish saving. A shell tells the user the "snapshot bound" from it. Present-iff the snapshot store (and, when present, `persist` / `keep` are present too); absent on server 7.125.x.'
+        cache:
+          allOf: [{ $ref: '#/components/schemas/WorkspaceCacheCapability' }]
+          description: >
+            server >= 7.126.0 — the per-space BUILD-CACHE VOLUME (`WORKSPACE_CACHE=volume`): one cache volume per space (session occupant) mounted at `mount` OUTSIDE the workspace (never in the snapshot, disposable), the tool caches
+            (Gradle / Maven / npm / pip / uv / Go; Rust is not covered) are pointed there through pod env. A run that cannot get the volume still starts without it (slower builds, no failure); delegated children / background agents
+            do not mount it. Present-iff the cache volume is on, independent of the snapshot store.
+    WorkspaceCacheCapability:
+      type: object
+      additionalProperties: false
+      required: [mount, size]
+      description: 'server >= 7.126.0 — `Capabilities.workspaceSync.cache`: the per-space build-cache volume (`WORKSPACE_CACHE=volume`), key-for-key the server''s `WorkspaceCacheCapability`.'
+      properties:
+        mount: { type: string, description: 'The absolute path of the cache volume inside the pod (default `/cache`, outside the workspace mount).' }
+        size: { type: string, description: 'The capacity requested per volume, a k8s quantity string (default `20Gi`).' }
     StoreCapability:
       type: object
       description: >
@@ -10312,13 +10431,14 @@ components:
             server >= 7.125.0 (contract appendix B.1 / B.1a) — WORKSPACE KEPT ACROSS RUNS: the k8s lane's `/workspace` is stored in object storage per session OCCUPANT (the session incarnation: delete the session and re-register the same id = a NEW space, starting from an empty directory). Each run's end
             snapshots the workspace into `<prefix>/<incarnation>/space/` (a sub-prefix this lane owns; the park-suspend snapshots live outside it and are never pruned), moves the `space/latest` pointer and keeps only
             the newest `keep`; the next run's start (when it connects the sandbox) restores from `latest`. A replica that cannot read the session occupant neither restores nor saves for that run (an operator line) and does NOT fall back to the session id.
-            A shell / center renders "work files kept across turns" only when `persist` is `"space"` (the default is `off`; persistence is opt-in).
+            A shell / center renders "work files kept across turns" only when `persist` is `"space"` (the default is `space` since server 7.126.0; it was `off` in 7.125.0) — read `persist`, not "the object is present".
             🔴 PRESENT-IFF — one of the three per-key exceptions on this surface (with `sealedKey` and `centerWiring`, contract appendix B.1): the facility = the k8s lane AND a snapshot store (the three
-            `MINIO_*` keys). ABSENT is a missing key, never `false` / `null` / `{}`, and means one of TWO things with the SAME action: an older server (< 7.125.0, does not know this bit), or a deployment that
-            is not the k8s lane / has no snapshot store (the same body's `version` tells them apart) — either way do NOT promise "last run's files are still there"; treat each run's workspace as an empty directory.
-            `persist: "off"` means the store is present and the capability is present but nothing is retained today (the default, or the operator switched it off) — different from absent. Covers `/workspace` only (process / memory state does not cross runs).
-            FAILURE IS LOUD: failing to read `latest` or the commit marker, a `latest` that points at a missing snapshot object, or a restore that fails midway fails THAT run's sandbox connect (never a silent empty
-            directory; a partial directory is not handed to tools and is not snapshotted back); a failed end-of-run snapshot puts the residual key `workspaceSnapshot: "failed"` on the fleet terminal `task` frame
+            `MINIO_*` keys), OR (server >= 7.126.0) the k8s lane AND the build-cache volume on. ABSENT is a missing key, never `false` / `null` / `{}`, and means one of TWO things with the SAME action: an older server (< 7.125.0, does not know this bit), or a deployment that
+            is not the k8s lane / has neither a snapshot store nor the cache volume (the same body's `version` tells them apart) — either way do NOT promise "last run's files are still there"; treat each run's workspace as an empty directory.
+            `persist: "off"` means the store is present and the capability is present but the operator switched persistence off, so nothing is retained today — different from the member being absent. Covers `/workspace` only (process / memory state does not cross runs).
+            FAILURE IS LOUD: failing to read `latest` or the commit marker, or a restore that fails midway (the snapshot is there but the download / unpack / time bound failed — the refusal names two exits: raise `WORKSPACE_SNAPSHOT_TIMEOUT_MS`, or run one turn with
+            `WORKSPACE_PERSIST=off`) fails THAT run's sandbox connect (never a silent empty directory; a partial directory is not handed to tools and is not snapshotted back); a `latest` that points at a missing snapshot object (cleared by a bucket lifecycle rule)
+            is, since server 7.126.0, an operator line plus deleting the dangling pointer, and that run starts from an empty directory (in 7.125.0 it failed the sandbox connect). A failed end-of-run snapshot puts the residual key `workspaceSnapshot: "failed"` on the fleet terminal `task` frame
             (`FleetTaskRow.workspaceSnapshot`), and the next run restores the PREVIOUS `latest`.
         background:
           type: object
@@ -11220,7 +11340,7 @@ components:
         [model, runsActive, tasks, tokensTotal, costUsd, costUsdByModel, costUnknown, unpricedCalls,
          taskDurationAvgSec, brainFirstTokenAvgMs, brainCallAvgMs, cacheHitRateAvg, promptCacheLowHit,
          rateLimited, costQuotaRejected, budgetExceeded, degraded, degenerate, memoryConsolidationOps,
-         planCacheRecurrence, cascade, verifications, councilRuns, toolErrors]
+         planCacheRecurrence, cascade, verifications, toolErrors]
       additionalProperties: true
       properties:
         model: { type: string }
@@ -11254,7 +11374,6 @@ components:
             hitRate: { type: [number, 'null'] }
         cascade: { type: object, additionalProperties: { type: integer } }
         verifications: { type: object, additionalProperties: { type: integer } }
-        councilRuns: { type: object, additionalProperties: { type: integer } }
         toolErrors: { type: object, additionalProperties: { type: integer } }
         limitCeilingAfterAnswer:
           type: object
@@ -11331,6 +11450,38 @@ components:
             Upgrade window (as it is): an on-disk LKG written by server <= 7.122.x only recorded the dropped entries that had a name AND were
             enabled; while serving from it with the center still unreachable this key lists only those rows (possibly `[]`) and the first pull after the
             center is reachable fills it in. An unknown `reasonCode` word reads as "dropped, reason unknown".
+        candidateRejected:
+          allOf: [{ $ref: '#/components/schemas/CandidateRejected' }]
+          description: >
+            server >= 7.126.0, PRESENT-IFF: the conclusion of the most recent configuration candidate the candidate judge rejected as a whole.
+            Present exactly when the configuration now in force is the fallback one (the on-disk LKG / the previously adopted candidate / env) BECAUSE the judge
+            rejected the latest candidate; a later candidate judged clean, a deployment that never judged a rejection / has no configuration pipeline (pure env), and
+            a dry-run posture all leave it ABSENT. Never minted as `null` / `[]` (unlike the always-present `droppedEntries`). So ABSENT does NOT mean "the
+            configuration is clean" (it is also an earlier server): render the real cause only when the key is present; keep the old behaviour when absent.
+            Same read as `models`: key present => this `models` is the fallback generation (none of the candidate's models are in it). No capability bit
+            (the endpoint is always there; the presence of the key is the presence rule).
+
+    CandidateRejected:
+      type: object
+      additionalProperties: false
+      required: [domains, at, source]
+      description: >
+        `ModelsResponse.candidateRejected` (server >= 7.126.0): the conclusion of the most recent configuration candidate the candidate judge
+        rejected as a whole (one failing domain, or a malformed prompts plane, rejects the WHOLE candidate: no domain of it is applied).
+        ZERO free text: no rejection sentence, no file path, no version number (those stay in the server log).
+      properties:
+        domains:
+          type: array
+          items: { type: string }
+          description: 'The configuration domain names (the contract package''s domain keys, e.g. `mcp` / `models` / `prompts`) that failed the shape judgement; sorted, de-duplicated. An unknown word is rendered as-is.'
+        at:
+          type: string
+          format: date-time
+          description: 'ISO 8601: when THIS process''s judge judged this candidate (re-judging the same candidate with the same failing domains does not refresh it).'
+        source:
+          type: string
+          enum: [local, remote]
+          description: 'Which configuration source the candidate was read from: `local` = the local config directory, `remote` = the center. A shell says "edit your config file" vs "ask the administrator" from it.'
 
     DroppedEntry:
       type: object
@@ -12615,7 +12766,9 @@ components:
           description: 'server >= 7.102.0 (S-755 / cli L-695): WHO raised this ask, read once together with `frame.origin` when the entry is minted. The durable `pending[]` rows of the same response carry it top-level too — one reading for both row families. OPEN set (see AskOrigin).'
         fromSubagent: { type: boolean, enum: [true], description: 'The ask originates from a delegated subagent.' }
         originTaskId: { type: string, description: 'S-52 C2 (server ≥7.52, A-075.87): the delegated child taskId (= the child''s core runSourceTaskId, uuid) — correlates this live ask to the child run row. Minted by the SAME conditional spread as `fromSubagent`: the two keys are always both present or both absent (三键恒等亲证在案).' }
-        contentKind: { type: string, description: 'S-62 (server >= 7.6x): content-question kind — `content_ask` when the gated tool is AskUserQuestion (the SAME word as the two durable read faces and core''s summarize face). Absent = an ordinary tool ask. Display/triage only; it NEVER takes part in decision routing.' }
+        approvalCard:
+          allOf: [{ $ref: '#/components/schemas/ToolApprovalCardWord' }]
+          description: 'server >= 7.126.0 (core 7.49.0 #1414): which card this ask renders on — the engine-minted card word, the SAME value as `frame.approvalCard` (the row reads the frame''s own seat, no second read), same layer and shape as the operator queue row''s `approvalCard`. It REPLACES `contentKind` (server <= 7.125.x derived it from the tool name; deleted at 7.126.0, no alias). ABSENT = the engine minted none. Display / triage only; it NEVER takes part in decision routing.'
         frame:
           allOf: [{ $ref: '#/components/schemas/ToolApprovalFrame' }]
           description: >-
@@ -12958,6 +13111,9 @@ components:
         origin:
           allOf: [{ $ref: '#/components/schemas/AskOrigin' }]
           description: 'server >= 7.102.0 (S-755 / cli L-695 / C-R111): WHO raised this ask — the park-row twin seat `PendingAction.tool_approval.origin` read through `readClosedWordSeat(…, "origin")` (core `isAskOrigin`). Same word as the live card frame and the inbox row. Absent = an old row (parked before core 7.5.0) or an out-of-set word — NOT "policy".'
+        approvalCard:
+          allOf: [{ $ref: '#/components/schemas/ToolApprovalCardWord' }]
+          description: 'server >= 7.126.0 (core 7.49.0 #1414): which card this row renders on — the engine-minted `gate.approvalCard` (closed eight-word set; the park-row twin seat reads the same word core''s `summarizeCheckpoint` projects onto `CheckpointSummary.approvalCard`; an out-of-set word reads as absent and is counted), the same word as the live frame / `livePending` row. It REPLACES `contentKind` (deleted at 7.126.0, no alias). ABSENT = the engine minted none: a row parked before engine 7.49.0 (core never derives a card from the tool name: no card = not a question, so an old question row carries no card word and is swept by the SLA at its deadline), a non-approval gate, or an older engine. Display / triage only; NEVER part of resume / gate / CAS; the inbox row does not carry it.'
         ruleOffersAbsence:
           allOf: [{ $ref: '#/components/schemas/RuleOffersAbsence' }]
           description: 'server >= 7.100.0 (S-700): WHY the park row offers no rule — the same narrow read and closed three-word set as the live card frame and `card_json`.'
@@ -13012,11 +13168,6 @@ components:
             (they carry a RiskDescriptor); ABSENT for resource_limit/needs_review/plan_review — UI tolerates undefined.
         spentMicroUsd: { type: number, description: 'cumulative spend on the suspend chain (when a resource ledger is attached).' }
         deadline: { type: integer, description: 'awaiting-human SLA deadline (epoch ms).' }
-        contentKind:
-          type: string
-          description: >
-            Open enum (known value `content_ask`) distinguishing WHAT is being asked about, for gates whose payload
-            is content rather than a tool call. Treat unknown values as opaque.
         sourceTaskId: { type: string, description: 'The task that produced this checkpoint (when distinct from sessionId).' }
         principal: { type: string, description: 'The submitting principal, when the deployment records one.' }
         createdAt: { type: integer, description: 'Creation time, epoch ms (NOTE — SessionRecord.createdAt is an ISO string).' }
@@ -13030,7 +13181,7 @@ components:
         ASSISTANT-WIRE-CONTRACT §2 — an inbox row (server >=3.4.0 EXPLICIT-projection form): the §1 mirror keys
         of a CheckpointSummary (token stripped; no rich per-tool fields) + two nullable enrichments.
         NARROWING RECORD (2026-07-30, board [2027]->[2029]): rows used to also carry
-        toolName/toolCallId/preview/principal/sourceTaskId/contentKind (handler spread the whole projection) and
+        toolName/toolCallId/preview/principal/sourceTaskId (handler spread the whole projection) and
         this spec over-declared decide bindings that never appeared on inbox wire at all. Four client repos were
         structurally zero-consumers, so server 3.4.0 narrowed the wire and this schema follows. For the tool face
         and decide bindings use /v1/approvals (PendingCheckpoint); for task attribution use /v1/assistant/tasks.
@@ -13318,6 +13469,13 @@ components:
         decision: { type: string, enum: [approve, edit, reject] }
         editedPlan: { type: string, description: 'the operator''s revised plan — required iff decision==="edit".' }
         reason: { type: string }
+        decidedBy:
+          allOf: [{ $ref: '#/components/schemas/ApprovalDecidedBy' }]
+          description: >
+            server >= 7.126.0 (engine 7.49.0 gave the plan-review outcome a required decision-fact seat, the same seat as tool approvals) — WHO MADE THIS DECISION, the same closed set and the same single
+            reading as the three tool-approval decision doors: absent => `person`; `policy` is accepted; a word outside the closed set (including `sla_timeout`, which only the server's own deadline sweep can say)
+            => `400 request.field_invalid`; on a direct-door (D-G) deployment ANY value => `400 decided_by_not_in_proof` (the key is not in the decision proof's signed payload). Not echoed in the response. NO capability bit
+            covers this door (`approvalDecidedBy` is >= 7.118.0 and does not cover plan_review): send it by server version; <= 7.125.x answers `400 request.body_shape` and lists it in `unsupportedKeys`.
         permissionModeAfter:
           type: string
           enum: [default, acceptEdits]
@@ -14721,6 +14879,13 @@ components:
         # 真发 `label`(core 展示名,与 tool_end 同待遇),spec 此前漏声明 —— 封闭前必须先补,否则真帧变假红。
         label: { type: string, description: 'core 展示名(缺席 ⇒ 用 toolName 渲染)。' }
         args: {}
+        recovered:
+          type: boolean
+          enum: [true]
+          description: >
+            server >= 7.126.0 (core 7.49.0 `tool_start.recovered`, contract table B `recovered` row, passed through verbatim): present, always the literal `true`, when the engine CLOSED a call whose start
+            frame was never emitted by minting this start frame after the fact (an interrupted run's reconciliation / a resumed process closing a call the dead process had announced), keeping "every
+            `tool_end` is preceded by a `tool_start` of the same id". Absent on the loop's own announced start frames (the vast majority). Does NOT assert whether the tool executed — read the paired `tool_end.notExecuted`.
         eventId: { type: string }
         parentToolCallId: { type: string }
         sourceTaskId: { type: string }
@@ -15250,6 +15415,18 @@ components:
         # 🔴 census 轴一(2026-07-30)回填:`toolEndEventData`(trace/project.ts)真发 `label` 与
         # `structured`,spec 此前两者都漏 —— SDK 的 events.ts 早已声明,漂移只在 spec 这一侧。
         label: { type: string, description: 'core 展示名(同 tool_start.label)。' }
+        notExecuted:
+          type: boolean
+          enum: [true]
+          description: >
+            server >= 7.126.0 (core 7.49.0, contract table B `notExecuted` row, passed through verbatim) — ABSENT IS NEVER "it ran": present, always the literal `true` (never `false`), when the engine has
+            POSITIVE evidence the call was never executed; absent only means the engine has no such evidence (a call interrupted mid-execution, or one closed by the reconciliation on the next process start, does not carry it —
+            telling the model "it did not run" there could invite a replay of a write that already took effect). Read it together with the paired `tool_start.recovered`.
+        wireName:
+          type: string
+          description: >
+            server >= 7.126.0 (core 7.49.0, contract table B `wireName` row, passed through verbatim) — the tool name this call resolved to on the LIVE roster (the name the gate judged). `toolName` stays the model's spelling (an alias /
+            a retired name the roster still answers to). Present ONLY on a refused call (`gate.disposition.kind === "denied"`), and absent when the station that refused it did not know the roster name; per-tool refusal accounting reads this, not `toolName`.
         structured: {}   # core 1.203 CC 卡片明细;与 output 同一 UNTRUSTED RAW 待遇(已 redactDeep),形状开放
         isError: { type: boolean }
         output: {}   # NON-UNIFORM: string | (TextContent|ImageContent)[] | (truncated) string. Absent ⇒ no body.
@@ -15471,6 +15648,8 @@ components:
         maxRetries: { type: number, description: "retry budget of the lane in force (refused-connect short lane = 2)" }
         retryInMs: { type: number, description: "same number as retryInSec at ms precision (countdown rendering)" }
         errClass: { type: string, description: "connect_refused | transport | rate_limit | server | http | output_cap — retry-wait frames ONLY; never inferred from phase" }
+        providerCondition: { type: string, description: "server >= 7.126.0 (core 7.49.0 #1454, passed through verbatim): what the provider said about the account / capacity — core's closed `PROVIDER_CONDITIONS`; a retry frame carries only the three retryable words `throttled | overloaded | unknown` (`quota_exhausted` / `stop_other` do not retry and ride the terminal `detail.providerCondition`). Presence law as `errorStatus`; read as an OPEN set (keep a default arm). ABSENT = not judged, read the same as `unknown` (back off, do not assert quota). Moves with `providerConditionSource`." }
+        providerConditionSource: { type: string, description: "server >= 7.126.0 (core 7.49.0 #1454): the evidence the `providerCondition` verdict rests on — `unified_header | provider_code | status`; present exactly when `providerCondition` is; read as an OPEN set." }
         eventId: { type: string }
         parentToolCallId: { type: string }
         sourceTaskId: { type: string }
@@ -16230,6 +16409,12 @@ components:
         switch itself became the WORD `"disabled"` instead of `null` (a string is not nullish, so the ordinary
         coalesce is the whole resolution rule and no reader has to remember a null test). A consumer still
         matching `task_store_null` matches nothing.
+        server 7.126.0 (the user-visible whitelist grows 35 -> 37 codes; contract appendix D.3): `task.tool_turn_incomplete` gains an optional `detail.outcome` (core 7.49.1) —
+        `{cause, count, toolCallIds?, outcome?, sessionId, runId}`, `outcome` in {`terminal` (the dropped calls ended the run with `model_output_invalid`), `reissued` (the model was asked to reissue)}, present only when
+        the turn's own message can say it, ABSENT = not said; two NEW codes (core 7.49.0, audience `user`, zero body text): `route.finish_reason_unknown` `{finishReason, sessionId, runId}` — the provider ended the turn
+        with a finish reason the engine does not understand, so the text above may be cut short (`finishReason` = the provider's own word, an OPEN string, passed through verbatim; once per run per word); and
+        `route.stream_end_ignored` `{statement, word, frames, sessionId, runId}` — the provider had already ended the turn and its stream sent more (`statement` in {`ending`, `error`, `content`}, `word` = the late first
+        frame's ending reason / error word / content kind, `frames` = how many frames came after the end; the first ending counts, anything later never entered the turn; once per run per (statement, word)).
         A notice whose `detail.sessionId` is absent is HONESTLY NOT DELIVERED (the server never guesses a session),
         so the frame's absence does NOT mean "did not happen" — the operator-facing structured log always has the
         full family. `detail` is already redacted + size-bounded by the server; still treat it as external text.
@@ -16877,6 +17062,15 @@ components:
             deployment read the bit at all. Present ⇒ every automatic allowance (remembered rules,
             bypassPermissions posture) stands down.
         origin: { $ref: '#/components/schemas/AskOrigin' }
+        approvalCard:
+          allOf: [{ $ref: '#/components/schemas/ToolApprovalCardWord' }]
+          description: >
+            "tool_approval" only, ADDITIVE (server >= 7.126.0 / core 7.49.0 #1414, contract table B `approvalCard` row) — WHICH CARD THIS ASK RENDERS ON: the one word the engine minted at the gate
+            (closed set `ToolApprovalCardWord`, eight words), passed through verbatim after a closed-set narrow read (an out-of-set word reads as absent). The ONLY card-word source — it REPLACES the
+            second card word `contentKind` that server <= 7.125.x derived from the tool name (deleted at 7.126.0, no alias: a consumer reading `contentKind === "content_ask"` reads
+            `approvalCard === "question"`). ABSENT = the engine minted none (a host-built ask / an older engine / a non-approval gate) — never `generic` by default. Display / triage only; it NEVER
+            takes part in resume / gate / CAS. The same word rides the `livePending` row top level (= this frame's own value), the operator queue row and the `/v1/approvals/stream` `pending` /
+            `live_pending` frames; the `card_json` card face and the `approval_request` frame's `card` do NOT carry it (`ApprovalCard` is `.strict()`).
         inputHasBidi:
           type: boolean
           enum: [true]
@@ -18048,6 +18242,22 @@ components:
             400 `request.field_invalid`; any value on a direct-door worker ⇒ 400 `decided_by_not_in_proof`. An older server
             (no `approvalDecidedBy` bit) has a strict body here ⇒ 400 `request.body_shape`, nothing decided.
 
+    ApprovalDecideGateKind:
+      type: string
+      enum: [human, irreversible_ask]
+      description: >
+        server >= 7.126.0 (sdk 21.1.0 `APPROVAL_DECIDE_GATE_KINDS`, verbatim and in order; single owner = server
+        `APPROVAL_GATE_KINDS`) — the parked gate kinds the DURABLE decision door `POST /v1/approvals/{sessionId}/decide`
+        accepts (the live `POST /v1/tool-approvals/{approvalId}/respond` answers the same card family). A parked row of
+        kind `plan_review` goes to the plan-review door instead (`PlanReviewGateKind`); `resource_limit` / `needs_review` /
+        `task_done` have no human decision door (resume / terminal). Clients route a pending row by reading this set,
+        never by a hand-written copy of it.
+    PlanReviewGateKind:
+      type: string
+      enum: [plan_review]
+      description: >
+        server >= 7.126.0 (sdk 21.1.0 `PLAN_REVIEW_GATE_KINDS`) — the parked gate kind the plan-review door
+        `POST /v1/assistant/tasks/{taskId}/plan_review` accepts (3-state approve | edit | reject).
     ApprovalDecidedBy:
       type: string
       enum: [person, policy]
@@ -18062,7 +18272,17 @@ components:
         "the wait ran out with nobody answering" is said only by the server's own deadline sweep — and the old `human` / `timeout`
         words) ⇒ 400 before the decision. It REPLACES the 7.93.3–7.117.x key `settledBy` (deny-only, the same fact), deleted
         by server 7.118.0 with no alias: sending `settledBy` ⇒ 400 `request.body_shape` on all three doors.
-        `plan_review` does not take it (400 `request.body_shape`).
+        `plan_review` (`POST /v1/assistant/tasks/{taskId}/plan_review`): server >= 7.126.0 takes it too, with the same reading and the same refusals; server <= 7.125.x answers 400 `request.body_shape`
+        (listed in `unsupportedKeys`), and `approvalDecidedBy` does not cover that door — send it by server version.
+
+    ToolApprovalCardWord:
+      type: string
+      enum: [file-edit, file-write, notebook-edit, shell, fetch, plan, question, generic]
+      description: >
+        server >= 7.126.0 (core 7.49.0 `TOOL_APPROVAL_CARDS`, verbatim and in order; contract table B `approvalCard` row) — WHICH CARD an approval ask renders on: the one word the engine mints at the gate, the
+        ONLY card-word source (it replaces the tool-name-derived `contentKind`). `question` = a question put to the user (the engine's reserved question tool — not a side-effecting tool; a consumer that read
+        `contentKind === "content_ask"` reads `approvalCard === "question"`); `generic` = a card with no dedicated renderer. CLOSED set; new words join with a core minor, so a switch on it keeps a default arm.
+        At expiry a parked `question` gate is voided and every other approval gate goes to the SLA refusal sweep (the judge is the engine's `facetOf(gate)`).
 
     ApprovalReach:
       type: string
@@ -18741,6 +18961,9 @@ components:
         origin:
           allOf: [{ $ref: '#/components/schemas/AskOrigin' }]
           description: '`pending` / `live_pending` frames (server >= 7.102.0 / S-755) — see PendingCheckpoint.origin / LivePendingRow.origin. OPEN set.'
+        approvalCard:
+          allOf: [{ $ref: '#/components/schemas/ToolApprovalCardWord' }]
+          description: '`pending` / `live_pending` frames (server >= 7.126.0 / core 7.49.0 #1414) — see PendingCheckpoint.approvalCard / LivePendingRow.approvalCard. Replaces `contentKind`.'
         ruleOffersAbsence:
           allOf: [{ $ref: '#/components/schemas/RuleOffersAbsence' }]
           description: '`pending` frames only (server >= 7.100.0 / S-700) — see PendingCheckpoint.ruleOffersAbsence.'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "20.0.3",
+  "version": "21.1.0",
   "description": "Typed, zero-runtime-dependency SDK for the Sema agent fleet usage plane. The shared substrate for all doors (CC/Codex MCP façade + web). Server-side only — tokens never enter the browser.",
   "type": "module",
   "license": "BUSL-1.1",