@sema-agent/sdk 18.0.0 → 18.2.0

package/openapi.yaml

@@ -2416,7 +2416,23 @@ paths:
                 required: [rules]
                 properties:
                   rules: { $ref: '#/components/schemas/StoredSessionRules' }
-        '400': { $ref: '#/components/responses/BadRequest' }
+        '400':
+          description: >-
+            400 — the rules body is refused BEFORE anything is written (not one byte reaches the store). Branch on `errorCode`, never on the sentence.
+            `rules.legacy_tool_name` (server >= 7.105.0; the `rules.*` family, the SDK lands it on `BadRequestError`): a tool-name bucket (`toolAllow` / `toolDeny`) entry
+            that would be written but could never run — an engine-retired name, a `__` name without a protocol prefix, or a protocol name whose peer segment the
+            engine cannot mint. Body keys (top level; the SDK reads them from `err.extra`): `field` (which bucket), `name` (which entry), `verdict`
+            (`retired` / `unprefixed_namespace`, server >= 7.116.0; `unmintable_segment`, server >= 7.118.0), `currentName` (server >= 7.116.0; present when
+            there is a 1:1 successor), `guidance` (server >= 7.119.0; the engine judge's wording of the fix, byte for byte — carried by `retired` and
+            `unmintable_segment`, absent for `unprefixed_namespace`). 🔴 server >= 7.123.0 also lands a protocol name with an EMPTY TOOL SEGMENT
+            (`mcp__<server>__`, `a2a__<peer>__`) here, as `verdict: "unmintable_segment"`; server 7.116.0–7.122.x answered `400 request.field_invalid`
+            for it — a caller that branched on that code for this shape now branches on `rules.legacy_tool_name` (the body's `verdict` tells the shapes apart).
+            `request.field_invalid`: a bucket that is not a list of non-empty strings (a bare string, `null`, a non-string member) and — behavior change
+            in server >= 7.123.0 — an EMPTY or BLANK (whitespace-only) member, which earlier servers took in (200); the sentence is the engine's own,
+            match on the code. Also `request.id_invalid` (malformed session id) and a malformed body.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403':
           description: 403 `loosen_forbidden` — a non-operator write tried to relax the rules (tighten-only).
@@ -3116,7 +3132,20 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ImportStaged' }
-        '400': { $ref: '#/components/responses/BadRequest' }
+        '400':
+          description: >-
+            400 — malformed input (the `policy` face is judged by the same write-door reader as `PUT /v1/sessions/{sessionId}/policy`, BEFORE any staging
+            is created, so a refused push leaves nothing behind). Branch on `errorCode`, never on the sentence. `rules.legacy_tool_name` (server >= 7.105.0):
+            a record's tool-name bucket (`toolAllow` / `toolDeny`) holds a name that could never run — an engine-retired name, a `__` name without a protocol prefix,
+            or a protocol name whose peer segment the engine cannot mint. Body keys (top level; the SDK reads them from `err.extra`): `field`, `name`, `verdict`
+            (`retired` / `unprefixed_namespace`, server >= 7.116.0; `unmintable_segment`, server >= 7.118.0), `currentName` (server >= 7.116.0, when there is a 1:1 successor),
+            `guidance` (server >= 7.119.0, the engine judge's wording; absent for `unprefixed_namespace`). 🔴 server >= 7.123.0 also lands a protocol name with an EMPTY TOOL
+            SEGMENT (`mcp__<server>__`, `a2a__<peer>__`) here (`verdict: "unmintable_segment"`); server 7.116.0–7.122.x answered `400 request.field_invalid` for it.
+            `request.field_invalid`: a bucket that is not a list of non-empty strings and — behavior change in server >= 7.123.0 — an EMPTY or BLANK member, which earlier
+            servers took in (the sentence carries the `policy: [i].rules: ` position prefix and then the engine's own sentence; match on the code).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409':
@@ -3234,7 +3263,9 @@ paths:
         Frames: `meta` ({type,version,mode:"approvals-delta",pollMs}), then `synced` ({type,count}) once the
         first full snapshot has been emitted, then `pending`/`resolved` deltas; plus `heartbeat` ({type}) on the
         keep-alive tick and a terminal `error` ({type,errorCode:"STREAM_MAX_DURATION",…}) when the 15-min cap
-        fires. (Corrected 2026-07-31: this list used to name only meta/pending/resolved — a consumer written to
+        fires — or, server >= 7.122.0, `error` with `errorCode:"draining"` at the moment the instance enters drain (same code and
+        sentence as the billable-submit 503 `draining`; the server closes the stream right after the frame, reconnect to the
+        replacement instance). (Corrected 2026-07-31: this list used to name only meta/pending/resolved — a consumer written to
         it silently drops three frame kinds it really receives.) Each data payload mirrors its SSE event name in
         `data.type` — proxy-safe dispatch. Cross-replica by
         construction (polls the SHARED checkpoint table). 15-min cap + heartbeats; a DB blip retries, never
@@ -3735,8 +3766,12 @@ paths:
             `ErrorResponse`-shaped. Codes: "request.body_shape" (bad/missing `decision`, OR an unrecognised
             top-level key — server >= 7.86.0 / S-438 key closure, the body carries `unknownKeys` /
             `unsupportedKeys`) · "request.field_conflict" (`edit` without a non-empty `editedPlan`;
-            `editedPlan` present on approve/reject; `permissionModeAfter` sent with `edit`/`reject`;
-            `permissionModeAfter` on a task that was not submitted with `permissionMode:"plan"`) ·
+            `editedPlan` present on approve/reject; `permissionModeAfter` sent with `reject`;
+            `permissionModeAfter` on a task whose stored permission mode is not `plan`) — match these two by CODE;
+            server >= 7.122.0: `approve` and `edit` both carry the plan out of plan mode and both take the key, and a
+            run's mode word has ONE source, the stored submit body (an operator `AUTONOMY=plan` task is stored as `plan`
+            and takes the key); <= 7.121.x only `approve` took it and the second conflict read "not submitted with
+            `permissionMode:"plan"`" ·
             "request.field_invalid" (non-string `reason`; `permissionModeAfter` outside the two-word closed
             set — zero widening arm) · "request.path_malformed" (a bad percent-encoded path segment —
             server >= 7.86.0 / S-430 turned that family from 500 `internal.error` into a 400 across 16 doors).
@@ -4117,8 +4152,9 @@ 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 }` (`default` = the deployment default model id, display-only — the
-        internal `default` alias is hidden; `defaultModel` = the same default as `{id, name?}` in one piece).
+        `{ models, default, defaultModel, droppedEntries? }` — 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`).
         🔴 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:
@@ -4126,26 +4162,7 @@ paths:
           description: Model catalog (possibly empty).
           content:
             application/json:
-              schema:
-                type: object
-                # 🔴 封闭 + `defaultModel` 补登记(census 批2 第三段,2026-07-30):铸造点
-                # `routes/capabilities.ts` 三键字面量。`defaultModel`([865]③ id/name 撕裂消解,server
-                # 已发多版)SDK `models.list()` 的返回类型早就带,**spec 是唯一没登记的一侧** —— 生成式
-                # 消费方对它全瞎。`name` 条件(目录无命中即省略),`id` 恒在。
-                additionalProperties: false
-                required: [models, default, defaultModel]
-                properties:
-                  models:
-                    type: array
-                    items: { $ref: '#/components/schemas/ModelInfo' }
-                  default: { type: string, description: "deployment default model id (display-only; legacy id-form, byte-stable)" }
-                  defaultModel:
-                    type: object
-                    additionalProperties: false
-                    required: [id]
-                    properties:
-                      id: { type: string }
-                      name: { type: string, description: 'the catalog @handle of the default model; omitted when the catalog has no match (env single-model lane).' }
+              schema: { $ref: '#/components/schemas/ModelsResponse' }
         '401': { $ref: '#/components/responses/Unauthorized' }
 
   /v1/elicitations/{id}/respond:
@@ -4668,7 +4685,8 @@ paths:
         (`LEADER_ENABLED` off) the answer depends on the server: server >= 7.116.0 mounts the route unconditionally and answers
         **501 `capability.leader_endpoint_required`** (new code; under multi-tenant the identity gate's 401 still comes first);
         <= 7.115.x did not register the route at all → the generic **404** `not_found.route`. Detect "leader unavailable" by
-        `errorCode` (or the `capabilities.leader` bit, which reads the same fact as the gate), not by the status alone.
+        `errorCode` (or the `capabilities.leader` bit — server >= 7.122.0 also reads false on a deployment whose operator runs `AUTONOMY=plan`, where a submit answers
+        422 `request.autonomy_lane_refused` instead; see `Capabilities.leader`), not by the status alone.
 
 
         🔴 IDEMPOTENCY (server >= 7.24.0): this POST now consumes the `Idempotency-Key` header — the header is
@@ -4717,6 +4735,20 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '422':
+          description: >-
+            errorCode "request.autonomy_lane_refused" (server >= 7.122.0) — the deployment runs the operator `AUTONOMY=plan`: every task starts
+            in plan mode and leaves it only when a person approves its plan through plan review, and a leader task's workers have no plan
+            review channel, so they could neither write nor hand their plan to anyone who can approve it. REFUSED at the door, NO run created;
+            a replay with the same `Idempotency-Key` gets the same 422 (the idempotency key is not consumed). The `capabilities.leader` bit
+            reads false on such a deployment (the same judgement as this refusal) — read it, or `GET /v1/policy` `autonomy`, beforehand. Exits: submit the work as a run (`POST /v1/runs`, plan reviewed through
+            `POST /v1/assistant/tasks/{taskId}/plan_review`), or ask the operator to set `AUTONOMY=read-only` or `ask` (leader tasks run
+            there). Not the hosted-posture refusal (`request.host_posture_refused`): that one is the tenant axis, this one is the AUTONOMY
+            axis. A change to `plan` after acceptance is caught where the run is born: the 202'd run ends with the same sentence in
+            `GET /v1/leader/{leaderRunId}` `error` and no worker is started.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '409':
           description: >-
             errorCode "conflict.leader_run_exists" (server >= 7.24.0) — your `Idempotency-Key` hit a leader run
@@ -7206,7 +7238,12 @@ components:
             `config.permission_mode_unavailable`. `bypassPermissions` RELEASES the ten releasable ask classes (server >= 7.115.0: the tenth is `unstated`, a server-tool call nobody stated)
             and DISCLOSES each (`tool_end.gate.disposition.released` + one `engine_notice` `permission.ask_released_by_mode` per (mode, class) per run);
             immune classes (deployment-authored, ask / org rules, hooks, ancestors, questions …) still ask; a write whose protection
-            cannot be judged is refused (`deniedBy: mode`). Request vocabulary: SIX words (server >= 7.119.0) — `dontAsk`, the engine's
+            cannot be judged is refused (`deniedBy: mode`) on the file tools — and, from server >= 7.122.0 / core 7.47.0, RELEASED on the SHELL face
+            (an eleventh class, `write_protection_unresolved`, for a caller-supplied tool whose wire name is exactly `Bash` or `Monitor` and which
+            declares a write-path target; see `ModeRelease.reason`). `plan` (server >= 7.122.0): the engine's plan mode and nothing the service adds —
+            the tool table equals `default`'s, the engine mounts the plan-presenting tool, and a write or any non-read-only call is asked AT CALL TIME by the
+            engine's plan gate (a card where somebody can answer, a refusal where nobody can; a delegated sub-agent inherits plan as its ceiling); up to
+            7.121.x the service also mapped `plan` to read-only hands, withheld the delegation tool and refused `Workflow`. Request vocabulary: SIX words (server >= 7.119.0) — `dontAsk`, the engine's
             "auto-refuse" mode, is accepted and passes through verbatim: the ENGINE refuses the calls that would ask (no card, no parked row,
             `tool_end.gate.disposition = { kind: denied, deniedBy: mode, mode: dontAsk, … }`), the run ends normally, and it is never looser
             than `default`. One exception: a PreToolUse hook's OWN ask, when no other class in that ask's set backs it, is still handed to a person
@@ -7216,7 +7253,7 @@ components:
             hold for <= 7.105.0 only.
             CC-parity permission-mode INTENT — the values THIS wire's closed submit-gate accepts (the first five on server <= 7.118.x,
             plus `dontAsk` from 7.119.0 = the engine's whole mode vocabulary, `capabilities.permissionModes`). 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);
+            `plan` ⇒ mount present_plan (core enablePlanMode) + read-only hands (CC EnterPlanMode research) — that is the <= 7.121.x reading; server >= 7.122.0: see the `plan` sentence in the first block;
             `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
@@ -7443,6 +7480,10 @@ components:
             `MANUAL_MODE_SHELL_GATE=always`, write protection, governance, a hook's ask and plan-mode asks still ask (a matching `request` member then shows as `allowRuleShadowed` on the
             card). The submit gate judges only the shape (array of strings, at most 1000 entries => 400) and the NAMES (the same judge and the same sentence as `deny` / `ask`: a retired name,
             an unprefixed short name, or a protocol name whose server segment cannot be minted / is missing / is a wildcard (`mcp__*`) is a whole-request 422) — never the content.
+            🔴 server >= 7.118.0: the NAME layer of the allow side moved to the engine — a retired name, an unprefixed short name or an unmintable protocol name is ACCEPTED here (no 422) and the run opens with an
+            `engine_notice` `permission.allowed_tool_not_granted` (`entries[].reason: tool_name`); the `deny` / `ask` buckets still refuse that family with a whole-request 422. 🔴 server >= 7.123.0 (core 7.48.0) also accepts a
+            protocol name with an EMPTY TOOL SEGMENT (`mcp__<server>__`, `a2a__<peer>__`) in this bucket (server 7.118.0–7.122.x refused it on every table). One name, three outcomes:
+            allow side accepts + notice, deny / ask side refuses, session-rule write doors answer `400 rules.legacy_tool_name` (`verdict: unmintable_segment`).
             🔴 THE 422 SENTENCE (server >= 7.117.0): `error` starts with `request settings cannot be applied as written: ` (<= 7.116.x: a different sentence that said tighten-only — all three
             buckets share this exit, and the old head misled a caller writing a tightening rule and lied about the allow bucket). Do NOT dispatch on the sentence: it carries no code of its own, so
             `errorCode` is the status-derived coarse code `request.unprocessable`.
@@ -9077,7 +9118,16 @@ components:
         asyncRuns: { type: boolean }
         artifacts: { type: boolean }
         approvals: { type: boolean }
-        leader: { type: boolean }
+        leader:
+          type: boolean
+          description: >-
+            The `POST /v1/leader` lane. server >= 7.122.0 reads the conjunction of two facts: the leader face is mounted (`LEADER_ENABLED` etc.) AND the
+            operator entry floor takes leader submissions — the same judgement as the 422 `request.autonomy_lane_refused` at the door (a leader task's
+            workers have no plan review channel). So on a deployment whose operator runs `AUTONOMY=plan` the bit reads false and a direct submit still
+            answers 422 `request.autonomy_lane_refused`; with `AUTONOMY=read-only` / `ask` / unset the bit follows the face. A false bit from an absent face
+            answers 501 `capability.leader_endpoint_required` on submit (404 `not_found.route` on <= 7.115.x) — tell the two falses apart by the submit's
+            `errorCode`, or read `GET /v1/policy` `autonomy` beforehand. <= 7.121.x (historical reading): the bit read the face only — true on a `plan`
+            deployment, no prediction of the refusal.
         version: { type: string }
         scenarios:
           type: array
@@ -9566,6 +9616,9 @@ components:
             `engine_notice` `permission.allowed_tool_not_granted`; any layer's deny / ask rule, operator `APPROVAL_REQUIRE` / `APPROVAL_NEVER_AUTO` / shell floor / write protection /
             governance, a hook's ask and plan-mode asks still ask (a matching member then shows as `allowRuleShadowed` on the card). The submit gate judges only the shape and the NAMES (retired
             name / unprefixed short name / unmintable protocol server segment => 422, at most 1000 entries => 400) — never the content.
+            🔴 server >= 7.118.0: the allow side's NAME layer moved to the engine (retired / short / unmintable names are accepted there and announced with `engine_notice` `permission.allowed_tool_not_granted`; `deny` / `ask` still 422);
+            server >= 7.123.0 also accepts a protocol name with an EMPTY TOOL SEGMENT (`mcp__<server>__`) on the allow side (server 7.118.0–7.122.x refused it on every table):
+            allow side accepts + notice, deny / ask side refuses, session-rule write doors answer `400 rules.legacy_tool_name`.
             🔴 ABSENT `allowLayer` with `allowGrant` present = a 7.115.0–7.116.x server: allow is a STATEMENT (it does not clear the engine's own write gate / shell checks; a content form
             is a whole-request 422). ABSENT KEY altogether (no `settings`) = an older server (<= 7.114.x), which read `allow` as a WHITELIST (everything off the list refused) — do not put
             anything in the allow bucket there. NOT the same bit as `taskSettings.permissions` (unchanged, still a boolean: "this server accepts the `settings.permissions` face"). The
@@ -9744,10 +9797,11 @@ components:
             does not know auto" and "it knows auto but this box has no entitlement source" would collapse to
             the same false, and a shell must do different things for those. `reason` is present ONLY when
             `armed` is false; read its vocabulary as an OPEN set (server already grew it from four words to
-            six). `model` is omitted when the classifier route cannot be resolved (the server logs the
+            six, and to seven with `operator_floor` in server >= 7.123.0). `model` is omitted when the classifier route cannot be resolved (the server logs the
             engine's refusal rather than 500-ing the read face). `?permissionMode=<mode word>` folds the
             caller's INTENT into the verdict (server >= 7.119.0 takes the six words of `capabilities.permissionModes` — `dontAsk` answers
-            `armed: false` / `reason: mode_not_auto`; server <= 7.118.x takes five); anything outside the server's words is a 400
+            `armed: false` / `reason: mode_not_auto`, except on a deployment whose operator entry floor rewrites the word — `AUTONOMY=plan`, where
+            server >= 7.123.0 answers `operator_floor`, see `reason`; server <= 7.118.x takes five); anything outside the server's words is a 400
             `request.field_invalid`.
           # 🔴 required 只有**三位**:武装两键(armed / reason)是 server >= 7.57.0 (S-80)
           # 才有的,而本包的支持地板是 3.0.0 => every 7.x <= 7.56.0 server is inside the promised face and
@@ -9768,7 +9822,17 @@ components:
                 fold that absence into false (it would render a 7.50 box that IS arming as "auto == default").
             reason:
               type: string
-              enum: [mode_not_auto, deployment_incapable, org_denied, local_denied, settings_denied, resolver_fault]
+              enum: [mode_not_auto, operator_floor, deployment_incapable, org_denied, local_denied, settings_denied, resolver_fault]
+              description: >
+                Why `armed` is false — the server's closed SEVEN words, in judgement order (read as an open set; keep a default arm).
+                `mode_not_auto` = this request's intent (the `?permissionMode=` query word) is not `auto` and that word reaches the engine as it is.
+                `operator_floor` (server >= 7.123.0) = this deployment's operator entry floor (`AUTONOMY=plan`) rewrote the intent into another word, and that
+                word is not `auto`: the word that reaches the engine is the operator's, so the way out is the operator changing the level, NOT the word the
+                request sends. On an `AUTONOMY=plan` deployment an absent intent (answered as the `auto` intent), `auto` and any word looser than `plan` read
+                `operator_floor`; an intent that IS `plan` stays `mode_not_auto` (the word arrives as sent, not rewritten by the floor).
+                Server <= 7.122.x answers `mode_not_auto` for both cases. The rest: `deployment_incapable` = no classifier seat mounted;
+                `org_denied` = this principal's caps say auto is off and no local deny is set (the center's explicit deny, or its fail-closed refusal); `local_denied` = the local `PERMISSIONS_DISABLE_AUTO_MODE`;
+                `settings_denied` = the settings layer folds auto (run-level, not produced by this read face); `resolver_fault` = the resolver threw.
             model: { type: string }
         readFace:
           type: ["string", "null"]
@@ -9928,13 +9992,16 @@ components:
         taskWriteFaceOpen:
           type: boolean
           description: >
-            server >= 7.95.0 (S-591; value meaning refined at 7.96.0 / S-613; mint `routes/capabilities.ts:653` =
-            `taskWriteFaceRefusal(deps.config) === undefined && autonomyOverrides(deps.config.autonomy).writeFace !== "roots"`)
+            server >= 7.95.0 (S-591; value meaning refined at 7.96.0 / S-613; mint `routes/capabilities.ts` =
+            `taskWriteFaceRefusal(deps.config) === undefined && autonomyKeepsOpenWriteFace(deps.config.autonomy)` from server >= 7.122.0;
+            up to 7.121.x the right half was `autonomyOverrides(deps.config.autonomy).writeFace !== "roots"`)
             — DISCLOSURE BIT OF THE WRITE-CONTAINMENT FACE: does this deployment honour the task-level "open the write
             fence" declaration (`permissionMode:"bypassPermissions"` ⇒ `TaskSpec.writeFace:"open"`, writes outside the
             workspace roots)? `false` has two forms: (1) the hosted-posture gate refuses ⇒ sending that mode gets
-            `422 request.host_posture_refused`; (2) the deployment runs `AUTONOMY=read-only|plan` ⇒ the request is
-            accepted but the write face is clamped back to roots — the declaration silently does nothing. Three states
+            `422 request.host_posture_refused`; (2) the deployment runs `AUTONOMY=read-only` ⇒ the request is
+            accepted but the write face is clamped back to roots — the declaration silently does nothing; server >= 7.122.0: `AUTONOMY=plan`
+            reads `false` too, but because the entry mode word is clamped to `plan` at admission (the engine's plan mode runs instead of
+            `bypassPermissions`; up to 7.121.x it was the same read-only-hands + roots clamp as `AUTONOMY=read-only`, and a hosted deployment answered 422 `request.host_posture_refused` where it now accepts the request into plan). Three states
             are folded into one bit on purpose: the caller has exactly one decision (send that key or not); tier and
             evidence live in the refusal body and the operator's `GET /v1/diagnostics/wiring`. It speaks ONLY for the
             write-containment cell — the other two columns of `bypassPermissions` are unaffected.
@@ -10190,6 +10257,9 @@ components:
             segment cannot be minted / is missing / is a wildcard (`mcp__*`) is a 400 too, and from 7.117.0 so is a retired name / unprefixed short
             name (the name layer is judged by the same judge as the allow bucket) and a list of more than 1000 entries (top-level `skills[]` and
             `agents[].skills[]` judge identically). Probe `capabilities.skillToolLists`.
+            🔴 The name-layer 400s above hold for server 7.116.x–7.117.x only. server >= 7.118.0: the allow side's name layer moved to the engine — a retired name / unprefixed short name / unmintable protocol name is ACCEPTED here and the run opens with an
+            `engine_notice` `permission.allowed_tool_not_granted` (`entries[].reason: tool_name`); server >= 7.123.0 also accepts a protocol name with an EMPTY TOOL SEGMENT (`mcp__<server>__`, `a2a__<peer>__`) here (server 7.118.0–7.122.x refused it).
+            One name, three outcomes: allow side accepts + notice, deny / ask side refuses, session-rule write doors answer `400 rules.legacy_tool_name` (`disallowedTools` below is a deny side).
         disallowedTools:
           type: array
           items: { type: string }
@@ -10204,6 +10274,8 @@ components:
             user audience, on the session stream). 🔴 The resume legs judge the stored body the same way: a parked task whose stored skill `disallowedTools` carries such an entry answers
             409 `resume_blocked_by_policy` (`blockedBy: "request.field_invalid"`, same sentence) BEFORE the claim — row and card untouched; a terminal run's `POST /v1/runs/{taskId}/steer`
             answers it before minting the wake card. Why: engine 7.41 trimmed whitespace (`"Bash "` was a working deny), engine 7.42 reads verbatim (reads as nothing). The allow side does not refuse.
+            🔴 A protocol name with an EMPTY TOOL SEGMENT (`mcp__<server>__`, `a2a__<peer>__`) is refused here (server >= 7.123.0: `error` is the engine's entry-reading sentence, `... reads as nothing (tool_name) ...`), while `allowedTools` accepts it from 7.123.0 —
+            one name, three outcomes: allow side accepts + notice, deny / ask side refuses, session-rule write doors answer `400 rules.legacy_tool_name`.
 
     McpServerSpec:
       type: object
@@ -10937,6 +11009,92 @@ components:
             `"other"`). This is the "where did those 180 404s actually land" cell. Empty object = zero failures;
             key absent = an older server.
 
+    ModelsResponse:
+      type: object
+      description: >
+        The `GET /v1/models` 200 body (the envelope; service `src/http/routes/capabilities.ts` mints the keys as literals).
+        `models` = the `@mention`-pickable catalog (`ModelInfo`); `default` = the deployment default model id (display-only, legacy id
+        form, byte-stable); `defaultModel` = the same default as `{id, name?}`; `droppedEntries` = server >= 7.123.0, ALWAYS present
+        there: the catalog entries THIS generation's read leg dropped one by one (an entry that does not pass the settings-schema
+        `ModelEntry` shape; the rest of the catalog is served as usual). ABSENT = an earlier server (<= 7.122.x) — so the key is
+        optional here (the SDK's supported server floor is 3.0.0); `[]` = the engine says nothing was dropped (also the env lane,
+        where no catalog is read), which is NOT the same as absent (the engine cannot say).
+      # 🔴 封闭 + `defaultModel` 补登记(census 批2 第三段,2026-07-30):铸造点
+      # `routes/capabilities.ts` 三键字面量。`defaultModel`([865]③ id/name 撕裂消解,server
+      # 已发多版)SDK `models.list()` 的返回类型早就带,**spec 是唯一没登记的一侧** —— 生成式
+      # 消费方对它全瞎。`name` 条件(目录无命中即省略),`id` 恒在。
+      # 18.2.0:信封升为具名 schema(此前内联在 `GET /v1/models` 的 200 上),新键 `droppedEntries`(server >= 7.123.0)挂在上面,**不进 required**。
+      additionalProperties: false
+      required: [models, default, defaultModel]
+      properties:
+        models:
+          type: array
+          items: { $ref: '#/components/schemas/ModelInfo' }
+        default: { type: string, description: "deployment default model id (display-only; legacy id-form, byte-stable)" }
+        defaultModel:
+          type: object
+          additionalProperties: false
+          required: [id]
+          properties:
+            id: { type: string }
+            name: { type: string, description: 'the catalog @handle of the default model; omitted when the catalog has no match (env single-model lane).' }
+        droppedEntries:
+          type: array
+          items: { $ref: '#/components/schemas/DroppedEntry' }
+          description: >
+            server >= 7.123.0 (settings-schema >= 10.1.0), always present there; ABSENT = an earlier server. The catalog entries the read leg
+            dropped from THIS generation (an entry that does not pass the `ModelEntry` shape) so a shell / admin panel can tell "which entry
+            I wrote did the engine not take, and why" without re-judging the schema. Rows carry an index, a closed reason word and (when
+            disclosable) a name / id — NEVER free text (the schema diagnostics, the entry value and any Record key stay in the server log).
+            🔴 SAME GENERATION as `models`: both are the two faces of one catalog generation and commit together. When a center candidate's
+            model plane is refused as a group (for example the default model is not in the catalog), or the candidate has no enabled entry at all
+            (survivors and dropped rows both count by the `enabled` each row wrote; a dropped row whose `enabled` cannot be read counts as enabled),
+            `models` and `droppedEntries` both stay on the previous generation — the key does NOT report the entries of the candidate that did not
+            land (why it did not land: `/health.modelRefusals`). So a disabled dropped entry shows up only in a catalog that has an enabled entry and whose model
+            plane landed. Different question from `/health.modelRefusals` (which names the models this box does NOT serve, with the engine's refusal code):
+            this key lists what the read leg dropped, including nameless and disabled rows.
+            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".
+
+    DroppedEntry:
+      type: object
+      description: >
+        One row of `ModelsResponse.droppedEntries` (server >= 7.123.0): a catalog entry the read leg dropped. `index` = the entry's original
+        position in the `models` array of the catalog document read this time (the local lane = its place in `config.d/models.json`; the
+        center lane = the catalog the center sent this worker) — the same coordinate as the server's `models.<index>` log line.
+        `identity` is optional: absent when none of the three keys is disclosable.
+      additionalProperties: false
+      required: [index, reasonCode]
+      properties:
+        index: { type: integer, minimum: 0 }
+        reasonCode: { $ref: '#/components/schemas/DroppedEntryReasonCode' }
+        identity: { $ref: '#/components/schemas/DroppedEntryIdentity' }
+
+    DroppedEntryReasonCode:
+      type: string
+      enum: [entry-schema-invalid, entry-key-invalid, entry-unreadable]
+      description: >
+        Why the read leg dropped a catalog entry (server >= 7.123.0). The words are settings-schema's closed `DROPPED_ENTRY_REASON_CODES`, passed through
+        verbatim (the server neither hand-copies nor rewrites them; a new word in the package is a compile error there, forcing an explicit decision).
+        `entry-schema-invalid` = the entry did not pass its own schema; `entry-key-invalid` = a Record-shaped collection's key did not pass the key schema
+        (the catalog is an array, so this word does not appear on `droppedEntries` today — keep it in the switch anyway); `entry-unreadable` = the judging
+        threw (a pathological accessor; the engine never carries what it threw). Read an unknown word as "dropped, reason unknown".
+
+    DroppedEntryIdentity:
+      type: object
+      description: >
+        The disclosable identity of a dropped entry (settings-schema's entry-identity shape). `name` / `id` appear only when they are DISCLOSABLE identifiers
+        (allow-listed characters, no secret shape, no URL userinfo — the server asks again at the exit); a non-disclosable one is simply absent, NOT masked (a masked
+        string is no longer an identity). `enabled` is the boolean the entry wrote itself (a disabled dropped entry is listed with `enabled: false`). With none of the
+        three keys the whole `identity` is absent — an empty object never reaches the wire, hence minProperties: 1.
+      additionalProperties: false
+      minProperties: 1
+      properties:
+        name: { type: string }
+        id: { type: string }
+        enabled: { type: boolean }
+
     ModelInfo:
       type: object
       description: >
@@ -12848,8 +13006,9 @@ components:
         REQUIRED iff `decision==="edit"` (FORBIDDEN otherwise → 400).
         🔴 THE BODY KEY SET IS CLOSED (server >= 7.86.0 / S-438): an unrecognised top-level key is refused with
         400 `request.body_shape` plus the `unknownKeys` / `unsupportedKeys` machine tables — refused rather
-        than dropped, because a misspelled `permissionModeAfter` would otherwise silently leave the task
-        read-only after its plan was approved.
+        than dropped, because a misspelled `permissionModeAfter` would otherwise silently fold to `default`
+        (the task keeps asking before each write after its plan was approved) while the caller believes the
+        mode was settled.
       required: [decision]
       additionalProperties: false
       properties:
@@ -12860,18 +13019,35 @@ components:
           type: string
           enum: [default, acceptEdits]
           description: >
-            server >= 7.86.0 (S-433, P1; mints `routes/approvals-assistant.ts:1021/1024/1148`) — WHICH
-            PERMISSION MODE THIS TASK CONTINUES IN once the plan is approved. Before this key, approving a plan
-            was a BLANK CHEQUE: the plan was approved while the read-only clamp stayed on and every write kept
-            asking. `acceptEdits` = writes stop asking; `default` = keep asking (AND is the folded value when
-            the key is absent, so an older shell executes plans unchanged).
-            🔴 THREE 400s, each with its own code: a value outside the two-word closed set ⇒
+            server >= 7.86.0 (S-433, P1) — WHICH PERMISSION MODE THIS TASK CONTINUES IN once the plan is approved.
+            `acceptEdits` = writes stop asking; `default` = keep asking (AND is the folded value when the key is
+            absent, so an older shell executes plans unchanged). The decision writes the mode back into the task's
+            stored submit body, so every later park -> resume continues in it and never falls back to plan.
+            🔴 server >= 7.122.0 — ONE JUDGE, ONE SOURCE: plan is only the engine's `permissionMode:"plan"`. Since 7.122.0
+            the service adds no read-only clamp of its own, so there is none to lift: the tool table equals `default`'s,
+            and a write or any non-read-only call is asked (somebody can answer) or refused (nobody can) AT CALL TIME by
+            the engine's plan gate. A run's mode word has ONE source, the stored submit body; its two writers are the submit door
+            and this write-back. A decision that carries the plan out of plan mode — `approve` (the original plan) or
+            `edit` (the person's revised plan; the engine proceeds with it) — writes this key back (absent => `default`);
+            only `reject` (the review goes back to redo the plan, plan mode stays) does not. Before 7.122.0 the service
+            also mapped plan to read-only hands; this key was added in 7.86.0 because, before it, approving a plan was a
+            BLANK CHEQUE (the plan was approved while the read-only clamp stayed on and every write kept asking); and on
+            7.86.0-7.121.x `edit` + this key was a 400 while `edit` itself wrote back `plan`, the continuation still held
+            by the read-only hands. All of that is gone since 7.122.0.
+            (A deployment's `AUTONOMY=read-only` static fence is a separate thing: since 7.122.0 it is all the service's governance
+            layer re-folds on each resume, it has nothing to do with approving a plan, and approval does not lift it.)
+            🔴 THREE 400s, each with its own code (match by CODE, not by sentence — the two `request.field_conflict`
+            sentences were reworded in 7.122.0, codes unchanged): a value outside the two-word closed set =>
             `request.field_invalid` (ZERO widening arm — this bit decides whether the model has hands after
             approval, so folding a misspelling into either mode is a silent downgrade on the security axis);
-            sending it with `edit`/`reject` ⇒ `request.field_conflict` (core: those two send the plan back to be
-            redone and the read-only clamp stays — dropping it there would let the caller believe the mode was
-            settled); sending it for a task that was NOT submitted with `permissionMode:"plan"` ⇒
-            `request.field_conflict` (approving the plan lifts no read-only restriction there).
+            sending it with `reject` => `request.field_conflict`, server sentence `permissionModeAfter is only valid with a
+            decision that carries the plan out ('approve' or 'edit'; got 'reject')` (a silent drop there would let the caller
+            believe the mode was settled); sending it for a task whose STORED permission mode is not `plan` (the model
+            entered plan mode itself, so approving returns it to the mode it was in before planning) =>
+            `request.field_conflict`, server sentence `permissionModeAfter does not apply to this task: it was not
+            started in plan mode (its stored permission mode is not "plan"), so approving the plan returns it to the mode
+            it was in before planning`. A task STARTED in plan mode is one the request put there, or one an operator
+            `AUTONOMY=plan` stamped at the submit door (its stored word is `plan`): the key is accepted for both.
             ⚠️ DIRECT-DOOR deployments: this key rides the HMAC envelope's TRAILING EXTENSION OBJECT (server
             7.87.0: `{answer?, permissionModeAfter?}`, present keys in lexicographic order; 7.86.0's bare
             trailing slot is DELETED with zero double-read) ⇒ a signer must sign the new shape, and mixed
@@ -13717,6 +13893,14 @@ components:
             `writeFace: open`; read `capabilities.taskWriteFaceOpen` first); (2) server >= 7.106.0 / S-895: `inheritEnv: "all"` on a
             hosted deployment (`REQUIRE_PRINCIPAL=true`; reach = the hosted posture only; read `capabilities.projectContext` first).
             Remove the key (or send `inheritEnv: "scrub"`) and resend. Resume legs fold it into 409 `resume_blocked_by_policy`.
+            🔴 `request.autonomy_lane_refused` (422, server >= 7.122.0): the deployment's operator `AUTONOMY` does not take tasks on this LANE.
+            Today's only trigger is `AUTONOMY=plan` × `POST /v1/leader` — plan leaves plan mode only through a person approving the plan (plan
+            review), a leader task's workers have no plan review channel, so the refusal is at the door and NO run is created (a replay with the
+            same `Idempotency-Key` gets the same 422 and does not consume the key). Same family as `host_posture_refused` but a different axis:
+            that one is the hosted / tenant posture axis (remove the key and resend); this one is the AUTONOMY axis (nothing to remove — submit
+            as a run via `POST /v1/runs`, or ask the operator for `AUTONOMY=read-only` / `ask`, under which leader tasks run). Read the live
+            config: a hot change takes effect on the next request; read `GET /v1/policy` `autonomy` beforehand (the `capabilities.leader` bit
+            reads false on such a deployment).
         error: { type: string }
         errorMessage: { type: string }
         activeTaskId:
@@ -14455,7 +14639,9 @@ components:
         bypass-IMMUNE (not releasable).
         CLOSED on the gate record (screened with core `isAskClass`). `bypassPermissions` releases only the ten RELEASABLE classes
         (`transcript_write` / `rule_unreadable` / `probe` / `write_protection` / `tool_marks_mcp` / `tool_marks_a2a` /
-        `artifact_shared_read` / `mode` / `unstated` / `ordinary`); every other class (deployment-authored `operator_forced`, ask / org rules, hook,
+        `artifact_shared_read` / `mode` / `unstated` / `ordinary`) — on every face — plus, from server >= 7.122.0 / core 7.47.0, an eleventh on the SHELL
+        face only: `write_protection_unresolved` (core `releasableAskClassesFor(face)`: shell 11, other faces 10; on the file tools that class is
+        refused, `deniedBy: mode`); every other class (deployment-authored `operator_forced`, ask / org rules, hook,
         ancestor, content question, …) asks under every mode.
     ModeRelease:
       type: object
@@ -14477,8 +14663,19 @@ components:
         mandate: { $ref: '#/components/schemas/PersistedRuleMandate' }
         reason:
           type: string
-          enum: [rule_unreadable]
-          description: '`rule_unreadable` = the release went over a rule this call could not be read against (the rule store was unreadable — a security-axis fail-open direction the server discloses on its own).'
+          enum: [rule_unreadable, write_protection_unresolved]
+          description: >
+            WHAT the release went over — one word: the FIRST member (in core `MODE_RELEASE_REASONS` array order) that the ask's class
+            set holds; ABSENT when the set holds none. CLOSED set — the server screens it with core `isModeReleaseReason`, so a word
+            outside it withholds the whole `gate` from the frame (and a consumer that dispatches on the word must learn each new one).
+            `rule_unreadable` = the release went over a rule this call could not be read against (the rule store was unreadable — a
+            security-axis fail-open direction the server discloses on its own).
+            `write_protection_unresolved` (server >= 7.122.0 / core 7.47.0) = the release went over a write whose target the
+            write-protection judge could not RESOLVE (whether it lands on the protected table is unknown). It is released on the SHELL
+            face only: a caller-supplied tool whose wire name is exactly `Bash` or `Monitor` and which declares a write-path target,
+            under `bypassPermissions`; on the file tools the same unresolved write is still refused (`deniedBy: mode`). The engine's
+            own `Bash` / `Monitor` cannot mint this class and the server mounts no such tool — it comes from a caller-embedded tool of
+            those names. Before server 7.122.0 / core 7.47.0 the set was `rule_unreadable` alone.
 
     GateClassifierAttribution:
       # sdk 9.5.0:具名 —— 同一份形挂在 `GateDisposition` 的两只臂上,内联会立刻是两份会各自漂的镜像。
@@ -17871,13 +18068,16 @@ components:
         🔴 Its arrival means the RUN IS STILL ALIVE — the 15-minute stream cap fired. The correct handling is to
         RECONNECT with `Last-Event-ID` and keep reading (the durable leg stamps `id:` on every frame); rendering
         it as a terminal would declare a live task dead. `done` / `failed` are the terminal arms; this one is not.
-        Known `errorCode`: `STREAM_MAX_DURATION` (open set — branch on the code, degrade unknown codes to the
-        generic "reconnectable stream-control signal").
+        Known `errorCode`: `STREAM_MAX_DURATION` (the 15-minute cap) · `draining` (server >= 7.122.0: the instance entered drain / is being
+        replaced — each of the eight read-only subscription streams gets this frame at the moment drain begins and is then closed by the server;
+        same code and sentence as the billable-submit 503 `draining`, same reconnect protocol: reconnect with `Last-Event-ID`, the replacement
+        instance serves it; NOT a run failure; the same reason family as the cap — the server closes a stream for flow control)
+        (open set — branch on the code, degrade unknown codes to the generic "reconnectable stream-control signal").
       additionalProperties: false
       required: [type, errorCode]
       properties:
         type: { const: error }
-        errorCode: { type: string, description: 'STREAM_MAX_DURATION (open set).' }
+        errorCode: { type: string, description: 'STREAM_MAX_DURATION | draining (server >= 7.122.0) (open set).' }
         message: { type: string }
     Event_question:
       type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "18.0.0",
+  "version": "18.2.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",
@@ -52,6 +52,6 @@
     "prepublishOnly": "rm -f tsconfig.tsbuildinfo && npm run build && npm run typecheck --workspaces=false --prefix ../.. && npm test --workspaces=false --prefix ../.. && npm run prepack"
   },
   "devDependencies": {
-    "@sema-agent/settings-schema": "^9.0.0"
+    "@sema-agent/settings-schema": "^10.1.1"
   }
 }