@sema-agent/sdk 6.6.1 → 6.7.0

package/openapi.yaml

@@ -515,6 +515,15 @@ paths:
             errorCode "steering.not_running" — the run is terminal, is running on ANOTHER replica
             (cross-replica live-steer is not wired), or the durable park lost its CAS (the checkpoint
             resolved/expired in between). NOT the ordinary suspended case — that one parks and 202s.
+            errorCode "steering.queue_full" (server >=7.3.0 / core 5.14.0) — the run IS parked, but the
+            steering queue on its checkpoint is full. The queue is bounded and FAIL-LOUD: the engine never
+            evicts an already-accepted instruction to make room. Opposite handling from not_running: the
+            text is still valid — let the run resume (which drains the queue) or reduce concurrent steers,
+            then resend.
+            errorCode "steering.duplicate_input_id" (server >=7.3.0 / core 5.14.0) — the Idempotency-Key you
+            sent is already parked with DIFFERENT steering content (same key + same content is an idempotent
+            no-op and 202s). The engine refuses rather than silently picking a side. Reissue with a fresh
+            key — this is a new instruction, not a retry.
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -2800,6 +2809,97 @@ paths:
         '404': { description: Unknown/settled/expired/foreign approval (no existence oracle). }
         '501': { description: Live tool-approval HITL not enabled (TOOL_APPROVAL_ENABLED). }
 
+  /v1/tasks/{taskId}/asks/{askId}/decision:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+      - { name: askId, in: path, required: true, schema: { type: string }, description: 'From ApprovalRequestFrame.askId (the durable identity, NOT approvalId).' }
+    post:
+      tags: [questions]
+      operationId: askDecision
+      x-status: planned          # design/172 §3.2 (#151 车4) — UNRELEASED; ships with server 7.3.0, gated OFF by STREAM_APPROVAL_ENABLED. SDK toolApprovals.decideAsk() 消费。
+      summary: Settle an IN-STREAM approval card (design/172 streaming approval protocol).
+      description: >
+        The in-stream sibling of POST /v1/tool-approvals/{id}/respond: the approver is live on the SSE stream, so
+        the ask does a stream round-trip and the run never parks. Keyed on `askId` (the DURABLE identity derived
+        from a five-tuple), so the decision is accepted by ANY replica (the CAS lands in the persistent store).
+
+        Decision is a TWO-word set (`approve`/`deny`) — `allow_session` is a live-bridge-only semantic and is NOT
+        on this endpoint. `actor` accepts ONLY `label`: `id`/`verified` are always server-minted and an actor
+        NEVER participates in the permission decision (design/171 §5.1).
+
+        Response doctrine (design/172 §3.2, four rules): ① same `idempotencyKey` retried → the ORIGINAL 200
+        replayed (no second CAS); ② already DECIDED with a DIFFERENT decision → 409 `conflict.ask_decided`
+        carrying the first decision echo (`decision`/`decidedAtMs`/`actor`; `note` is NEVER echoed across
+        permission boundaries); ③ PARKED/DENIED/VOID → 410 `gone.ask_parked` (with the gate reconciliation
+        coordinates `{sessionId, gateBoundCallId, gateBoundInputHash}` — NEVER the checkpoint token) or
+        `gone.ask`; ④ PARKING → 425 `parking.ask_retry` — retrying fetches the FINAL ROUTING INFO, it does NOT
+        retry acceptance of the decision (the window is already closed).
+
+        Attribution split: DENIED is produced ONLY by routing failure (`routing_failure_fail_closed`); an
+        operator refusal is DECIDED(decision=deny). A timeout NEVER produces a deny.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/AskDecisionBody' }
+      responses:
+        '200':
+          description: The decision was accepted (or replayed for the same idempotencyKey).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/AskDecisionAck' }
+        '400':
+          description: 'Malformed body — `request.invalid_json` (unparseable) or `request.body_shape` (schema reject, e.g. an `actor` carrying anything but `label`).'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404':
+          description: >
+            Unknown askId / taskId mismatch / non-owner — ONE shape, NO existence oracle (`not_found.ask`).
+            NOT the cross-leg case: a park+resume mints a NEW askId, and the OLD row survives in its terminal
+            state, so deciding against the old askId gets that row's terminal answer (200 idempotent replay /
+            409 first-decision echo / 410) — the "no consent is ever reused across legs" guarantee comes from
+            the new leg having its own independent row, not from the old one 404-ing.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '409':
+          description: >
+            Already settled with a DIFFERENT decision (`conflict.ask_decided`, first-decision echo in the body),
+            or the idempotencyKey belongs to another ask (`conflict.ask_idempotency`).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/AskDecidedConflictBody' }
+        '410':
+          description: >
+            The window is closed and the outcome is already cast: `gone.ask_parked` (gate coordinates in the
+            body — route to the durable gate flow) or `gone.ask` (`{state, deniedReason?}`). The two legs carry
+            DISJOINT bodies.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/AskGoneBody' }
+        '425':
+          description: >
+            PARKING — transferring to the delivery plane. `parking.ask_retry`; the retry fetches FINAL ROUTING
+            INFO, never acceptance. The body carries `retryAfterSec` and NO gate coordinates (they are not
+            written until bind).
+          headers:
+            Retry-After:
+              schema: { type: integer }
+              description: 'Seconds to wait before polling again for the final routing info. Paired with the body''s `retryAfterSec`.'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/AskParkingBody' }
+        '501':
+          description: >
+            In-stream approval protocol not on this worker (`feature.approval_ask_disabled`) — no ask store, or
+            STREAM_APPROVAL_ENABLED is off. Probe the capability, do not trial-by-501.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
   /v1/side-query:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -4173,14 +4273,30 @@ components:
           type: string
           enum: [default, plan, acceptEdits, bypassPermissions, auto]
           description: >
-            CC permission-mode INTENT (the five CC modes verbatim, post-[816]/[820]/[822]). The frontend (TUI shell /
-            web portal) carries the RAW mode; the SERVICE interprets it TIGHTEN-ONLY vs the deployment baseline:
+            CC-parity permission-mode INTENT — the five values THIS wire's closed submit-gate accepts (post-[816]/
+            [820]/[822]; not a claim these are CC's/sema-cli's complete mode vocabulary, which is wider, e.g.
+            `dontAsk`). The frontend (TUI shell / web portal) carries the RAW mode; the SERVICE interprets it TIGHTEN-ONLY vs the deployment baseline:
             `plan` ⇒ mount present_plan (core enablePlanMode) + read-only hands (CC EnterPlanMode research);
-            `default` adds the manual ask gate; `auto` = same ask gate with core's auto-mode classifier screening
-            asks upstream (entitlement-gated in core); `acceptEdits`/`bypassPermissions` are honored as
-            "add less/no mode-derived gating" — they can never subtract from the deployment/operator policy
-            (deny-wins). An unknown string coerces to `default` (the most-asking mode). Carrying the intent
-            (not pre-interpreted core fields) = one interpretation across frontends + service-owned governance.
+            `default` adds the manual ask gate on non-exempt writes (scratchpad dirs / remembered session
+            exemptions still auto-allow — not literally every Write/Edit); the server emits the SAME gate-policy
+            for `auto` as for `default` — sending `auto` is NOT itself what arms core's auto-mode classifier; that
+            classifier is armed purely by the principal's entitlement (`runtimeCaps.autoMode===true` plus a
+            deployment `deps.autoMode` wiring), independent of which mode word the request sends: an entitled
+            principal's `default` request is screened too, and a non-entitled principal's `auto` request behaves
+            as plain `default`; `acceptEdits` adds the SAME gate narrowed to auto-allow inside the working
+            directory — but only when the service has a trusted working directory to scope it to; on a sandbox
+            execution lane with none wired, `acceptEdits` degrades to asking on every non-exempt write, same
+            as `default`; `bypassPermissions` adds no mode-derived gate at all. None of the five can ever subtract
+            from the deployment/operator policy (deny-wins). Omitting this field is NOT itself "no mode-derived
+            gate" — this field wins over a `settings.permissions.defaultMode` bundle when both are sent, but when
+            THIS field is omitted the bundled mode (if any) still supplies one; only when neither carrier supplies
+            a mode is there no mode-derived gate (the same posture as `bypassPermissions`). Sending this field is
+            also NOT the same as leaving it unset — an explicit `default` actively installs the ask gate. A fresh
+            submit with an unknown string is rejected fail-loud with 400 (sibling of `promptProfile`); the old
+            silent most-asking-mode fallback no longer applies to fresh submits — a lenient version of that
+            fallback survives only internally, for RESUME replay of a pre-gate persisted
+            body. Carrying the intent (not pre-interpreted core fields) = one interpretation across frontends +
+            service-owned governance.
         attachmentIds:
           type: array
           maxItems: 16
@@ -4259,6 +4375,17 @@ components:
           type: string
           enum: [simple, classic]
           description: Which prompt-assembly profile to use.
+        toolMaterializeStrategy:
+          type: string
+          enum: [static, swap]
+          description: >
+            server >=7.3.0 (core 5.14.0, board [2856]2) — how a DEFERRED tool (see `deferTools`) supplies its
+            schema AFTER ToolSearch activates it. `static` keeps the placeholder (activation only flips
+            callability; the advertised schema stays the empty object); `swap` advertises the REAL schema on the
+            next request. A provider whose decoding is CONSTRAINED by the advertised schema loops UNBOUNDED under
+            `static` (every round emits `{}` and the next round still advertises an empty schema), which is why
+            this is a per-task knob. OMIT to inherit the engine chain (`spec ?? env ?? static`) — sending an
+            explicit value takes that decision away from the deployment env lane. Unknown value => 400 fail-loud.
         clientContext:
           type: object
           description: Non-authoritative client hints (never trusted for authz).
@@ -4276,8 +4403,11 @@ components:
           description: >
             TOC `settings.json` contract carried to the worker (CC-parity v1: permissions/hooks/env/model/
             outputStyle). The SDK owns the schema in `src/settings.ts` (`SemaSettings`) — it is deliberately NOT
-            duplicated here as a component: the service passes it through to core rather than interpreting it, so
-            the TS type is the single authority. OPEN object.
+            duplicated here as a component to keep ONE schema authority instead of two drifting copies. The
+            service ACTIVELY interprets this bundle (task-settings.ts: permissions + permissions.defaultMode +
+            model + outputStyle + env shipped in the 1.26.0 v1 scope; hooks was deferred at that point and wired
+            in a later batch — both are live and interpreted today, not a raw uninterpreted passthrough);
+            `permissions.defaultMode`'s specific fold is documented on `TaskRequest.permissionMode`. OPEN object.
           additionalProperties: true
         cwd: { type: string, description: Working directory for the execution env. }
         selfOrchestration: { type: boolean, description: Permit S8 self-orchestration (run_workflow) inside this task. }
@@ -7010,6 +7140,9 @@ components:
         - $ref: '#/components/schemas/Event_elicitation'
         - $ref: '#/components/schemas/Event_elicitation_complete'
         - $ref: '#/components/schemas/Event_workflow_complete'
+        # [2854] core 5.14.0 TaskEvent 16->18 (server 7.3.0 pickup): both new arms, projected.
+        - $ref: '#/components/schemas/Event_human_input'
+        - $ref: '#/components/schemas/Event_wiring_manifest'
       discriminator:
         propertyName: type
         mapping:
@@ -7046,6 +7179,8 @@ components:
           elicitation: '#/components/schemas/Event_elicitation'
           elicitation_complete: '#/components/schemas/Event_elicitation_complete'
           workflow_complete: '#/components/schemas/Event_workflow_complete'
+          human_input: '#/components/schemas/Event_human_input'
+          wiring_manifest: '#/components/schemas/Event_wiring_manifest'
 
     # design/99 §E2 (SHIPPED, core TaskEventIdentity) — additive per-event identity on every CONTENT event (NOT on
     # the lifecycle arms turn_end/compacted/suspended/done/failed). eventId = uuidv7 dedup/resume handle (the durable
@@ -7321,6 +7456,13 @@ components:
       properties:
         type: { const: task_progress }
         taskId: { type: string, description: 'The subagent task id (the delegated sub-run).' }
+        taskType:
+          type: string
+          description: >
+            server >=7.3.0 (core 5.14.0, board [2854] six-car batch item 2) — the DELEGATION KIND discriminator
+            (`background_agent` | `workflow`), so a consumer routes a progress frame without inferring the kind
+            from the id shape. ABSENT on a synchronous child's frames (absence means "no fleet row" — tolerate
+            it). Open on read.
         usage:
           type: object
           description: 'Cumulative usage as of this turn boundary (closed 3-field set, byte-aligned to core).'
@@ -7339,6 +7481,121 @@ components:
         parentToolCallId: { type: string }
         sourceTaskId: { type: string }
         bgAgentId: { type: string }
+    Event_human_input:
+      type: object
+      description: >
+        server >=7.3.0 (core 5.14.0 design/171) — HUMAN INPUT LIFECYCLE: who fed this run what, and whether it
+        landed. One frame per carrier (objective / live steer / nextTurn / parked-steer resume / wake). It carries
+        NO body text: this is the attribution + delivery ledger, not the message (join content through
+        `message_committed` + stream order). Live emissions PRECEDE the commit and omit `entryId`.
+        SERVICE PROJECTION: core's `principal` is deliberately NOT forwarded (the stream is already owner-scoped —
+        the frame does not restate the tenant). `issuer` / `actor.id` / `actor.issuer` are host-derived identity
+        strings and arrive SECRET-REDACTED.
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      additionalProperties: false   # 封闭 + identity 本地镜像:见 Event_reasoning 处的长注
+      required: [type, inputId]
+      properties:
+        type: { const: human_input }
+        inputId: { type: string, description: 'Stable per-input id (also the durable steering queue idempotency key).' }
+        sessionSeq: { type: integer, description: 'Leg-scoped monotone sequence of human inputs.' }
+        carrier: { type: string, description: 'Which carrier delivered it (steer / objective / a source word). Open on read.' }
+        source: { type: string, description: 'objective | steer | next_turn | wake | external | system. Open on read.' }
+        delivery: { type: string, description: 'applied | queued | parked_for_wake. Open on read.' }
+        issuer: { type: string, description: 'Who asserted the identity (host-derived; REDACTED).' }
+        actor:
+          type: object
+          description: >
+            Speaker attribution — NEVER authority. `hostAsserted:false` means the host did NOT derive the identity
+            from ingress credentials; render it as unverified (core's own `[from ...]` renderer appends
+            " (unverified)" on exactly this bit). `id`/`issuer` arrive REDACTED.
+          additionalProperties: false
+          properties:
+            id: { type: string }
+            hostAsserted: { type: boolean }
+            issuer: { type: string }
+        entryId: { type: string, description: 'The committed session entry this input became (absent on the live pre-commit emission).' }
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
+    Event_wiring_manifest:
+      type: object
+      description: >
+        server >=7.3.0 (core 5.14.0 design/173) — ASSEMBLY SELF-EVIDENCE: what this leg actually wired, emitted at
+        prepare. Root / child / resume legs each emit their OWN manifest (a delegated child's rides the CHILD's
+        stream by design). SERVICE PROJECTION: the `governance` section core stamps `audience:"operator"` is
+        STRIPPED by the server before this frame reaches a tenant stream (core contract: "no projection => do not
+        disclose") — it is deliberately absent from this schema. `configFingerprint` is ALSO stripped for the same
+        reason: core hashes the whole manifest (governance included) unsalted, and governance is four booleans —
+        sixteen combinations a tenant could brute-force against everything else it already receives, recovering the
+        section that was removed. Both come back on the operator-scoped projection, not here.
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      additionalProperties: false   # 封闭 + identity 本地镜像:见 Event_reasoning 处的长注
+      required: [type, manifest]
+      properties:
+        type: { const: wiring_manifest }
+        manifest:
+          type: object
+          additionalProperties: false
+          properties:
+            schemaVersion: { type: integer }
+            leg:
+              type: object
+              additionalProperties: false
+              properties: { kind: { type: string, description: 'root | child | resume. Open on read.' } }
+            ask:
+              type: object
+              additionalProperties: false
+              description: 'Approval seam: how it is wired, where it came from, and what it effectively resolves to.'
+              properties:
+                form: { type: string }
+                provenance: { type: string, description: 'spec | deps. Open on read.' }
+                effective: { type: string }
+            question:
+              type: object
+              additionalProperties: false
+              description: >
+                Question channel — three-valued (wired / absent / stripped_bg_lane, the last meaning the engine
+                stripped a bg child per-request face). `interactiveToolsWithoutDeliveryFace` is the composition-lie flag.
+              properties:
+                wired: { type: string }
+                provenance: { type: string }
+                interactiveToolsWithoutDeliveryFace: { type: boolean }
+            interaction:
+              type: object
+              additionalProperties: false
+              properties: { posture: { type: string, description: 'interactive | headless | absent. Open on read.' } }
+            elicit:
+              type: object
+              additionalProperties: false
+              properties:
+                seamWired: { type: boolean }
+                serversOptedIn: { type: integer }
+            parkLane:
+              type: object
+              additionalProperties: false
+              description: >
+                Durable park lane: capability vs EFFECTIVE policy. `effective` is THREE-VALUED — `"unresolved"`
+                means the engine has not decided yet; never fold it to false.
+              properties:
+                capable: { type: boolean }
+                effective: { oneOf: [{ type: boolean }, { type: string }] }
+                reasons: { type: array, items: { type: string } }
+                checkpointDurability: { type: string }
+            session:
+              type: object
+              additionalProperties: false
+              properties: { store: { type: string } }
+            fleet:
+              type: object
+              additionalProperties: false
+              properties:
+                backgroundAgentStore: { type: boolean }
+                hostChildEventSink: { type: boolean }
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
     Event_workspace_changed:
       type: object
       description: >
@@ -7705,6 +7962,313 @@ components:
           enum: [allowed, denied, expired]
           description: '"tool_approval_complete" only. `expired` = TTL/abort/disconnect — a fail-closed DENY the shell should render as such, not as "still pending".'
 
+    # ── design/172 流内审批协议(#151;UNRELEASED,候 server 7.3.0 + STREAM_APPROVAL_ENABLED,默认 OFF)──
+    # 与上面的 ToolApprovalFrame 是**并行加帧,不替换**:开关打开时同一只 ask 出两帧(先 tool_approval,
+    # 后 approval_request),两帧同带 `approvalId` ⇒ 消费端按它去重、优先渲染新帧。
+    ApprovalRequestFrame:
+      type: object
+      description: >
+        IN-STREAM approval card (SSE, `type` IS the event name; design/172 §3.1). NOT an AgentEvent arm — it
+        interleaves on the live token stream like tool_approval/question/elicitation. Settle it via
+        POST /v1/tasks/{taskId}/asks/{askId}/decision.
+
+        WINDOW: `expiresAtMs` is cast ONCE and never recomputed; `expiresInMs` = max(0, expiresAtMs - serverNowMs)
+        and is therefore MONOTONICALLY DECREASING across replays — a reconnect NEVER renews the window.
+
+        REPLAY: on a new connection the server replays every STREAM_PENDING card as a PREAMBLE, and that preamble
+        is the shell's FULL RECONCILIATION BASELINE — any local card not in it must be dropped (revoke frames can
+        be lost across a process boundary; the preamble is the structural compensation). Historical approval
+        frames replayed from the durable events tail are for TIMELINE RENDERING ONLY, not a card-set baseline
+        (their `expiresInMs` is the value frozen when the frame was minted). Preamble frames carry no SSE `id:`
+        and take no part in the Last-Event-ID cursor.
+
+        UNKNOWN SHAPES ARE NEVER AUTO-DENIED: an unknown schemaVersion/kind or an unrenderable card gets a
+        GENERIC card (safety metadata + manual approve/deny); if it cannot be shown, keep the frame and tell the
+        operator, letting the window fall through to park. Folding "I don't understand it" into a refusal is the
+        deadlock this protocol exists to remove.
+
+        NOT EVERY ASK HAS A CARD: the non-streaming POST /v1/tasks (no delivery plane) and council/team subtask
+        legs produce none; an adhoc (non-durable) sync stream's taskId is one-shot and has no replay handle; a
+        background child's ask arriving after the host run ended is NOT thrown at the dead stream — it parks onto
+        the durable gate (the existing inbox surface).
+      required: [type, schemaVersion, askId, taskId, kind, card, expiresInMs, expiresAtMs, serverNowMs, approvalId]
+      additionalProperties: true
+      properties:
+        type: { type: string, enum: [approval_request] }
+        schemaVersion:
+          type: integer
+          enum: [1]
+          description: >
+            Frame shape version. THIS SCHEMA DESCRIBES v1 ONLY — a frame carrying any other version is not this
+            shape; read it as ApprovalFrameEnvelope and render the generic card. NEVER auto-deny.
+        askId:
+          type: string
+          description: >
+            The DURABLE identity (derived from the five-tuple sourceTaskId/runId/toolCallId/legKey/
+            parentToolCallId). Dismissal, decision and reconciliation all key on THIS. Deduplicate by it (the
+            same frame may be delivered repeatedly). VOID AFTER A PARK and never reused across legs — a resume
+            re-asks with a NEW askId, so "the thing you just approved may be asked again" is normal and the
+            shell must explain it.
+        taskId: { type: string, description: 'wire run id — the {taskId} segment of the decision path.' }
+        kind:
+          type: string
+          enum: [permission]
+          description: >
+            v1 closed set. `content` is a reserved slot, not implemented (design/172 §8③). A frame with any
+            other kind is not this shape — read it as ApprovalFrameEnvelope and render the generic card.
+        card: { $ref: '#/components/schemas/ApprovalCard' }
+        expiresInMs: { type: integer, description: 'Remaining budget = max(0, expiresAtMs - serverNowMs). Monotonically decreasing across replays; the window is never renewed.' }
+        expiresAtMs: { type: integer, description: 'Absolute server-clock deadline. Cast ONCE, never recomputed.' }
+        serverNowMs: { type: integer, description: 'Server clock at mint time — the shell corrects its local clock skew with it.' }
+        approvalId:
+          type: string
+          description: >
+            Bridge to the legacy frame / dedupe key — same value as the parallel tool_approval frame. During the
+            transition window POST /v1/tool-approvals/{approvalId}/respond still works.
+
+    ApprovalCard:
+      type: object
+      description: >
+        The card payload — a NEUTRAL PROJECTION (design/172 §6.7: the server neither restates nor rewrites; the
+        shell owns rendering). UNTRUSTED FOR DISPLAY: `message`/`args`/`sourceAgentName`/`delegation.agentName`
+        are server-redacted and length-bounded but remain model/tool-authored bytes — render only, never re-feed
+        to a model. `args` has a 16 KiB BYTE cap (UTF-8 bytes, not characters); over the cap it is omitted with
+        `argsOmitted: true` and the shell must render an elision stub, NOT conclude "no arguments".
+      required: [toolName, message, risk]
+      additionalProperties: true
+      properties:
+        toolName: { type: string, description: 'Canonical core tool name.' }
+        message: { type: string, description: 'The engine ask text, secret-redacted. UNTRUSTED for display.' }
+        args: { description: 'The pending call''s args, redacted + byte-bounded. Absent (with argsOmitted) when over the cap or unserializable. UNTRUSTED for display.' }
+        argsOmitted: { type: boolean, enum: [true], description: 'Present (true) only when args exceeded the byte cap. Never false.' }
+        toolCallId: { type: string, description: 'The engine''s tool-call id (the `call_…` on the assistant message''s tool_use block) — same domain as ToolApprovalFrame.toolCallId.' }
+        risk: { $ref: '#/components/schemas/ApprovalRiskAxes' }
+        fromSubagent: { type: boolean, enum: [true], description: 'Present ⇔ the ask comes from a DELEGATED child — the explicit discriminator (a worker cannot forge it).' }
+        sourceTaskId: { type: string, description: 'The child''s core session id — row-join value + fallback discriminator.' }
+        sourceAgentName: { type: string, description: 'The child agent''s display name, redacted. UNTRUSTED.' }
+        delegation: { $ref: '#/components/schemas/ApprovalCardDelegation' }
+
+    ApprovalRiskAxes:
+      type: object
+      description: >
+        The two risk axes plus the coarse safety marker (design/172 §3.1; SDK ApprovalRiskAxes).
+
+        🔴 THREE-STATE, NOT TWO: true / false / ABSENT = the engine did not annotate it. The shell must render
+        absence as "not annotated" and MUST NOT fold it to false — rendering "unknown" as "safe" is exactly the
+        failure this contract forbids. The axes are optional because core exposes them additively on AskRequest,
+        so an older engine/server omits them entirely.
+
+        `requiresRealApproval` is the ONE marker core always carries ("this is a safety-class ask" — the gate
+        that refuses blanket-allow). It is NOT a substitute for, nor the conjunction of, the two axes: folding
+        "deletes data" and "sends data out" into a single boolean erases the basis for the human decision.
+      required: [requiresRealApproval]
+      additionalProperties: true
+      properties:
+        irreversible: { type: boolean, description: 'The call is irreversible. ABSENT = not annotated — do not read as false.' }
+        egress: { type: boolean, description: 'The call sends data across a boundary. ABSENT = not annotated — do not read as false.' }
+        requiresRealApproval: { type: boolean, description: 'Coarse safety-class marker (core AskRequest.requiresRealApproval). Always present.' }
+
+    ApprovalCardDelegation:
+      type: object
+      description: 'Delegation provenance for a child ask (present only alongside fromSubagent).'
+      required: [parentToolCallId, depth]
+      additionalProperties: true
+      properties:
+        parentToolCallId: { type: string, description: 'The host-side delegating tool-call id — the card''s attribution anchor.' }
+        depth: { type: integer, description: 'Delegation depth (a direct child of the host = 1).' }
+        agentName: { type: string, description: 'Child agent name. UNTRUSTED — spawning-model free text (server-redacted and length-bounded).' }
+
+    ApprovalRevokeFrame:
+      type: object
+      description: >
+        BATCH-LEVEL card revocation (SSE; design/172 §3.3). A batch = the blast radius of ONE run-level abort
+        (every in-flight tool call of that run plus its synchronous delegation subtree). On receipt the shell
+        clears that batch's local cards (whitelist-pick by `askIds`) and waits for the new askIds a resume mints.
+
+        Siblings already DECIDED are NOT in `askIds` (an accepted decision is not affected by revocation).
+        Revoke frames CAN BE LOST (frames produced by the reconciler / orphan legs have no seq to allocate and
+        ride the live plane only) — the structural compensation is the open-stream preamble baseline (see
+        ApprovalRequestFrame), not a redelivery of this frame.
+      required: [type, schemaVersion, batchId, askIds, reason, serverNowMs]
+      additionalProperties: true
+      properties:
+        type: { type: string, enum: [approval_revoke] }
+        schemaVersion: { type: integer, enum: [1], description: 'This schema describes v1 only (see ApprovalFrameEnvelope for the unknown-version read).' }
+        batchId: { type: string }
+        askIds: { type: array, items: { type: string }, description: 'The asks revoked (moved to VOID) by this frame.' }
+        reason:
+          type: string
+          description: >
+            `superseded_by_park` = a sibling''s window expired and the whole batch degraded to the durable park;
+            `aborted` = the run was cancelled. Read as OPEN: an unknown reason is handled as a generic revoke
+            (clear the cards), never specially.
+        serverNowMs: { type: integer }
+
+    AskDecidedConflictBody:
+      allOf:
+        - $ref: '#/components/schemas/ErrorResponse'
+        - type: object
+          properties:
+            decision:
+              allOf: [{ $ref: '#/components/schemas/ApprovalAskDecision' }]
+              description: 'FIRST-DECISION ECHO (`conflict.ask_decided` only): the decision that was accepted.'
+            decidedAtMs: { type: integer, description: 'When the first decision was durably accepted.' }
+            actor:
+              allOf: [{ $ref: '#/components/schemas/ActorAssertion' }]
+              description: 'Who decided. Omitted when the persisted actor fails its schema check (car4 §12-D).'
+      description: >
+        409 body. `conflict.ask_decided` carries the FIRST-DECISION ECHO; `conflict.ask_idempotency` carries the
+        bare `errorCode` (the key belongs to a different ask — change the key, not the ask).
+        🔴 `note` is NEVER echoed: the echo is bounded by the requester's visible permissions (design/172 §3.2).
+        Retrying the same decision can never succeed — single-winner CAS means the outcome is already cast.
+
+    AskGoneBody:
+      allOf:
+        - $ref: '#/components/schemas/ErrorResponse'
+        - type: object
+          properties:
+            sessionId: { type: string, description: 'gone.ask_parked ONLY — gate reconciliation coordinate 1; drive the existing durable-gate flow with it.' }
+            gateBoundCallId: { type: string, description: 'gone.ask_parked ONLY — gate reconciliation coordinate 2.' }
+            gateBoundInputHash: { type: string, description: 'gone.ask_parked ONLY — gate reconciliation coordinate 3.' }
+            state: { type: string, enum: [DENIED, VOID], description: 'gone.ask ONLY — the terminal state.' }
+            deniedReason:
+              type: string
+              description: >
+                gone.ask ONLY — attribution, GROUPED BY `state`. `DENIED` carries the single-member deny
+                vocabulary `routing_failure_fail_closed`; `VOID` carries the separate (and growing) void
+                vocabulary, e.g. `adhoc_leg_no_durable_domain`. The two vocabularies never mix.
+      description: >
+        410 body. THE TWO LEGS ARE DISJOINT: `gone.ask_parked` carries exactly the three gate coordinates,
+        `gone.ask` carries exactly `{state, deniedReason?}`. Routing off field presence across the legs is how a
+        consumer ends up driving the wrong durable gate.
+        🔴 The checkpoint token is NEVER here: the resume credential is not externally disclosed. Use
+        `sessionId`.
+        🔴 ATTRIBUTION SPLIT: `DENIED` is produced ONLY by routing failure. An operator refusal is
+        `DECIDED(decision="deny")` and reaches the caller as a 200 or as the 409 first-decision echo — never as
+        `DENIED`. A timeout never produces a deny.
+
+    AskParkingBody:
+      allOf:
+        - $ref: '#/components/schemas/ErrorResponse'
+        - type: object
+          properties:
+            retryAfterSec: { type: integer, description: 'Suggested lower bound before polling again; paired with the Retry-After header.' }
+      description: >
+        425 body (`parking.ask_retry`). 🔴 NOT "retry may succeed": the window is already closed and the decision
+        can never be accepted. The retry fetches the FINAL ROUTING INFO (poll until the 410 hands over the gate
+        coordinates). Carries NO gate coordinates — they are not written until the batch binds.
+
+    ApprovalFrameEnvelope:
+      type: object
+      description: >
+        The UNKNOWN-SHAPE read of either approval frame — the minimal common shape on the wire, and the typed
+        counterpart of design/172's "unknown shapes are never auto-denied" clause.
+
+        ApprovalRequestFrame and ApprovalRevokeFrame describe **v1 only** (`schemaVersion: 1`, plus
+        `kind: permission` on the request frame). Leaving those discriminants open would let a schema
+        simultaneously say "any version may arrive" and keep promising the complete v1 `card` — which is exactly
+        how a consumer ends up dereferencing `card.risk.requiresRealApproval` on a frame that never promised it.
+        Read the frame as this envelope, narrow on the discriminants, and fall back to the generic card when it
+        does not narrow.
+      required: [type, schemaVersion]
+      additionalProperties: true
+      properties:
+        type: { type: string, description: 'Echo of the SSE event name. Open: a third frame family may appear.' }
+        schemaVersion: { type: integer, description: 'Frame shape version. Anything but 1 means this package does not describe the payload.' }
+
+    ApprovalAskDecision:
+      type: string
+      enum: [approve, deny]
+      description: >
+        The decision on an IN-STREAM approval card (design/172 §3.2). A TWO-word set — deliberately NOT the
+        three-word ToolApprovalDecision: `allow_session` ("remember for this session") is a live-bridge-only
+        semantic and does not exist on POST /v1/tasks/{taskId}/asks/{askId}/decision.
+
+    ActorAssertion:
+      type: object
+      description: >
+        Decision-maker identity assertion (design/171 §5.1; the cross-repo source of truth is
+        `@sema-agent/registry-core` ActorAssertionWire — the SDK holds a value copy).
+
+        NORMATIVE, not a style note: an ACTOR NEVER PARTICIPATES IN THE PERMISSION DECISION — authority always
+        belongs to the principal; this shape exists only for audit/echo/presentation. `id` is ALWAYS server-minted
+        (= the verified principal; an auth-off deployment mints the `"_"` sentinel), and a wire requester may
+        submit ONLY `label`.
+      required: [id]
+      additionalProperties: false   # registry-core's ActorAssertionWire is .strict()
+      properties:
+        id: { type: string, minLength: 1, maxLength: 256, description: 'Server-minted principal ("_" sentinel when auth is off). Never submittable by the requester.' }
+        label: { type: string, maxLength: 256, description: 'Unverified display text — the ONLY field a requester may submit (server redacts + bounds it). UNTRUSTED.' }
+        verified: { type: boolean, description: 'Whether the server minted this id under an authenticated context (auth-off ⇒ false, honestly). Never submittable.' }
+        via:
+          type: string
+          enum: [owner, operator]
+          description: >
+            Audit axis for which authorization path accepted the decision: `owner` (row owner) or `operator`
+            (explicit operator seat). CLOSED — verbatim-equal to the owning schema
+            (registry-core ActorAssertionWire). Widening it here without widening the owner is copy drift.
+
+    AskDecisionBody:
+      type: object
+      description: 'Request body of POST /v1/tasks/{taskId}/asks/{askId}/decision (design/172 §3.2).'
+      required: [decision]
+      additionalProperties: false
+      properties:
+        decision: { $ref: '#/components/schemas/ApprovalAskDecision' }
+        updatedInput:
+          description: >
+            Operator-edited args (WHOLE REPLACEMENT, not a patch). Valid on the approve arm only (leniently
+            ignored on deny). Passed through verbatim: core re-runs PreToolUse + the full policy chain on the
+            edit; the server interprets nothing. Whether it was forwarded shows up as AskDecisionAck
+            .updatedInputForwarded.
+        note:
+          type: string
+          maxLength: 2048
+          description: >
+            Audit note. NEVER echoed back on the 409 first-decision echo (the echo is bounded by the requester's
+            visible permissions).
+        idempotencyKey:
+          type: string
+          minLength: 1
+          maxLength: 255
+          description: >
+            Decision idempotency key (<= 255). The same key retried replays the ORIGINAL 200 (no second CAS);
+            the same key against a DIFFERENT askId is a 409 `conflict.ask_idempotency` — deliberately fail-loud,
+            because replaying across asks would both mask a caller key-management bug and violate design/172''s
+            "never reuse an old consent" clause.
+        actor:
+          type: object
+          description: 'Display name of the decision-maker. ONLY `label` is accepted — id/verified are always server-minted; any extra key is a 400 request.body_shape.'
+          required: [label]
+          additionalProperties: false
+          properties:
+            label: { type: string, maxLength: 256 }
+
+    AskDecisionAck:
+      type: object
+      description: 'The 200 ack of POST /v1/tasks/{taskId}/asks/{askId}/decision (design/172 §3.2 rule ①; also the replay body for an idempotent retry).'
+      required: [askId, taskId, decision, decidedAtMs]
+      additionalProperties: false   # server-composed envelope (car4 §6), not an engine passthrough — closed on purpose
+      properties:
+        askId: { type: string }
+        taskId: { type: string }
+        decision: { $ref: '#/components/schemas/ApprovalAskDecision' }
+        decidedAtMs: { type: integer, description: 'Server instant at which the decision was durably accepted.' }
+        actor:
+          allOf: [{ $ref: '#/components/schemas/ActorAssertion' }]
+          description: >
+            OPTIONAL: when the persisted decision_actor fails its schema check the server OMITS this field
+            rather than answering 500 (car4 §12-D). Never dereference `actor.id` without a presence check.
+        updatedInputForwarded:
+          type: boolean
+          enum: [true]
+          description: >
+            Present (true) when the approve carried `updatedInput` AND a live in-process entry was actually
+            settled with it (the server forwarded the edited args to the engine). 🔴 TRUE OR ABSENT, NEVER FALSE
+            — so "no live entry (pure durable / another replica)" and "no edit sent" are indistinguishable on the
+            wire. An idempotent replay does NOT promise byte-identity on this field: it is a function of THIS
+            replica's live state and is not persisted.
+
     QuestionFrame:
       type: object
       description: >