@sema-agent/sdk 22.0.3 → 23.0.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: `) 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
+        `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: `allowTools: ["mcp__*"]`, `excludeTools: ["*"]` (and, on server 7.126.0–7.128.x only, a name in `allowTools` / `excludeTools` that no tool of this run answers to — server >= 7.129.0 runs those as written and announces each once with the operator row `runner_config_advisory`), 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
@@ -2511,7 +2511,8 @@ paths:
       description: >
         E6 — write the per-session rules. 🔴 TIGHTEN-ONLY for a normal principal: a loosen (remove a deny / widen
         an allowlist or allowDirs) → 403 `loosen_forbidden` (operator-only). `expectedRev` = optimistic-concurrency
-        CAS; a stale rev → 409 `conflict`. Each rule field must be `string[]` → malformed body 400. ownerless
+        CAS; a stale rev → 409 `conflict`. Each rule field must be `string[]` and the body carries only the three buckets (`toolAllow` / `toolDeny` / `allowDirs`; any other
+        key, including the retired `commandAllow` / `commandDeny`, → 400 `rules.invalid_shape` on server >= 7.129.0) → malformed body 400. ownerless
         session → 409; non-owner → 404. 501 without a session-policy store.
       requestBody:
         required: true
@@ -2521,7 +2522,22 @@ paths:
               type: object
               required: [rules]
               properties:
-                rules: { $ref: '#/components/schemas/SessionPermissionRules' }
+                # 🔴 请求体里的 `rules` 收闭(server >= 7.129.0:写口的判官拒一切不是桶的键,含退役命令桶 ⇒ 400 `rules.invalid_shape`)。
+                #   `SessionPermissionRules` 本体保持开放(响应 / 同步面的 `StoredSessionRules` 经 allOf 引它并再加 `rev` / `gen`,本体收闭会把合法的 `rev` 判成违约);
+                #   所以收闭落在**这一个引用点**:allOf + 本地镜像三桶 + `additionalProperties:false`(spec.test 的通用「封闭 allOf 必须镜像分支键」门看守镜像完整)。
+                rules:
+                  allOf: [{ $ref: '#/components/schemas/SessionPermissionRules' }]
+                  additionalProperties: false
+                  properties:
+                    toolAllow: { type: array, items: { type: string } }
+                    toolDeny: { type: array, items: { type: string } }
+                    allowDirs: { type: array, items: { type: string } }
+                    # server >= 7.129.0 (engine 7.51.2): a stored body echoed back (GET → edit → PUT) may carry its `rev` and `grammar`;
+                    # the engine reads the entries in THAT grammar (`rev` without `grammar` = grammar 0 ⇒ a rule-spelled allow entry
+                    # answers `400 rules.inert_entry` reason `earlier_grammar`; the way out is to send the three buckets alone — the
+                    # write judge stamps the current grammar). `grammar` newer than the engine's ⇒ `400 rules.invalid_shape`.
+                    rev: { type: integer, minimum: 0 }
+                    grammar: { type: integer, minimum: 0 }
                 expectedRev: { type: integer, minimum: 0, description: CAS — reject if the stored rev differs. }
       responses:
         '200':
@@ -2537,18 +2553,22 @@ paths:
                   rules: { $ref: '#/components/schemas/StoredSessionRules' }
         '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.
+            400 — the rules body is refused BEFORE anything is written (not one byte reaches the store; the store's own refusal uses the same code and body). Branch on `errorCode`, never on the sentence.
+            The `rules.*` family (the SDK lands both codes on `BadRequestError`); the judge is the ENGINE's write-door judge, one reader for the whole body (server >= 7.129.0, engine 7.51.0):
+            `rules.inert_entry`: a rule entry in a bucket (`toolAllow` / `toolDeny`) that the engine reads as NOTHING — written down it would deny / allow nothing. Body keys (top level; the SDK reads them from `err.extra`):
+            `field` (which bucket), `entry` (which entry, the original value), `reason` (the engine's `ALLOW_ENTRY_INERT_REASONS`, six words: `tool_name` no tool answers to the name · `wildcard_all` the bare `*` ·
+            `namespace_wildcard` `mcp__*`-style wildcard naming no server · `content_unsupported` the tool has no rule form like that, e.g. `Monitor(touch:*)` · `grammar` the grammar fails, e.g. an empty string or `Bash(` ·
+            `near_miss` a near-miss of a valid form), `verdict` (optional; only on `tool_name`: `retired` an engine-retired name / `unprefixed_namespace` a `__` name without a protocol prefix / `unmintable_segment` a protocol
+            name whose peer segment or tool segment the engine cannot mint, or whose tool segment is EMPTY — `mcp__<server>__`, `a2a__<peer>__`), `currentName` (optional; present when there is a 1:1 successor, e.g. `bash` => `Bash`), `guidance` (optional; the engine judge's wording
+            of the fix, byte for byte — carried by `retired` and `unmintable_segment`). The sentence is the engine's own: match on the code. Rewrite that entry and write again.
+            `rules.invalid_shape`: the rules body itself has the wrong shape — not an object (`rules` absent, `null`, an array, a scalar), a key that is not a bucket (including the RETIRED `commandAllow` / `commandDeny`:
+            never silently dropped, a dropped deny is enforced by nobody), a bucket that is not a list of strings, an `allowDirs` member that is empty / blank. Body keys: `field` (which key; the empty string when the
+            body as a whole is not an object), `got` (the TYPE of that value, e.g. `a string` / `not a rule bucket` — the value is never echoed); `error` is the engine's sentence.
+            The command rule's new spelling is an entry: `commandDeny: ["rm"]` => `toolDeny: ["Bash(rm:*)"]` (denies the command name `rm`; it does not deny a path-spelled `/bin/rm ...` nor a command line that does not read as one command
+            name — the old bucket denied both; to deny those too deny the whole shell, `toolDeny: ["Bash"]`); `commandAllow` has no counterpart.
+            🔴 BREAKING (server 7.129.0): server 7.105.0–7.128.x answered this family with `rules.legacy_tool_name` (entry in `name`, no `reason`) — that code is retired with no alias; a caller that branched on it branches on the two codes
+            above (the `rules.` prefix test still holds). On server <= 7.128.x the shape problems answered `400 request.field_invalid` (`rules` not an object: `request.body_shape`) and a body with a command bucket was accepted.
+            Also `request.id_invalid` (malformed session id).
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -3261,15 +3281,12 @@ paths:
               schema: { $ref: '#/components/schemas/ImportStaged' }
         '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).
+            400 — malformed input (the `policy` face is judged by the same engine write-door judge 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.inert_entry` / `rules.invalid_shape` (server >= 7.129.0, engine 7.51.0; the `rules.*` family, same code and same body as the policy door — read the bucket list, the `reason` words
+            (`tool_name` / `wildcard_all` / `namespace_wildcard` / `content_unsupported` / `grammar` / `near_miss`) and the body keys `field` / `entry` / `reason` / `verdict` / `currentName` / `guidance` / `got` there):
+            a record's rule entry the engine reads as nothing (e.g. a protocol name with an EMPTY TOOL SEGMENT — `mcp__<server>__`, `a2a__<peer>__` — has `reason` `tool_name` and `verdict` `unmintable_segment`), or a rules body of the wrong shape (including the retired `commandAllow` / `commandDeny` buckets). The sentence carries the record position prefix `policy: [i].rules: ` and then the
+            engine's own sentence; match on the code. `rules.legacy_tool_name` is retired with no alias (server 7.105.0–7.128.x sent it) — it is replaced by `rules.inert_entry` (its `name` key is now `entry`).
+            On server <= 7.128.x the shape problems answered `400 request.field_invalid` and a record with a command bucket was staged.
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -3646,12 +3663,13 @@ paths:
             render it as "this card can only be denied / wait for a server upgrade". Not a regression: 7.31.x children
             never had those tools.
             🔴 THE TWO CAUSES ARE TOLD APART BY `cause` (server S-818, riding core #1161; ADDITIVE, optional): the body may
-            carry `cause` — core's CAUSE WORD for this startup failure, relayed VERBATIM from the engine receipt's `details`
-            (no rewrite, no default; absent when the engine did not say, i.e. every server before S-818 and every core before
-            #1161). The closed set is core's (#1161 exports it as a constant, named in core 7.34.1's release notes); this
-            spec copies no word list, so treat it as an OPEN string with a default arm. Absent ⇒ "cannot tell": offer both
-            ways out. SDK → `ParkedResumeStartupError.startupCause` (`undefined` when absent or not a string; the wire key stays
-            `cause` — the SDK does not put it on the standard `Error.cause`, which means a chained error).
+            carry `cause` — core's CAUSE WORD for this startup failure, relayed from the engine receipt's `details`
+            (no default; absent when the engine did not say, i.e. every server before S-818 and every core before
+            #1161). The closed set is core's (#1161; core 7.51.0 exports it as `RESUME_STARTUP_CAUSES`); since server >= 7.129.0
+            the key is one of those five words (`ResumeStartupCause`: `environment` / `session_gone` / `tool_unavailable` / `configuration` / `decision_rejected`)
+            — the server screens it, a word outside the set is dropped; servers <= 7.128.x relay the word unscreened. Absent ⇒ "cannot tell": offer both
+            ways out. SDK → `ParkedResumeStartupError.startupCause` (23.0.0: `ResumeStartupCause`; `undefined` when absent, not a string, or outside the five words — the raw value stays at `err.extra.cause`;
+            the wire key stays `cause` — the SDK does not put it on the standard `Error.cause`, which means a chained error).
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -7144,7 +7162,7 @@ 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. 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).' }
+        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) on server 7.126.0–7.128.x, and RUNS AS WRITTEN on server >= 7.129.0 (the entry is kept, an operator row `runner_config_advisory` announces it once; `denyTools: ["bash"]` does not deny `Bash`).' }
         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
@@ -7667,7 +7685,7 @@ components:
             🔴 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`).
+            allow side accepts + notice, deny / ask side refuses, session-rule write doors answer `400 rules.inert_entry` (server >= 7.129.0; `reason: tool_name`, `verdict: unmintable_segment`; 7.123.0–7.128.x answered a retired code, named in the 400 of `PUT /v1/sessions/{sessionId}/policy`).
             🔴 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`.
@@ -7805,8 +7823,9 @@ components:
           items: { type: string }
           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`).
+            NO tool answers to rejects the run before it starts with `config.tool_face_control` on server 7.126.0–7.128.x (sync leg 400, no token burned; streamed / background legs: a `failed` terminal with
+            the same code); server >= 7.129.0 RUNS it as written (the entry is kept and takes effect if a tool of that name is mounted later; an operator row `runner_config_advisory` announces it once, with the spelling to write —
+            names are read verbatim, so `excludeTools: ["bash"]` does not withhold `Bash`). `"*"` is rejected on this list too (unmount-everything is only `excludeAllTools`).
         allowTools:
           type: array
           items: { type: string }
@@ -9586,6 +9605,13 @@ components:
       additionalProperties: true
       properties:
         sideQuery: { type: boolean, description: 'POST /v1/side-query one-shot brain-routed Q&A face is wired (probe before use, no trial-by-501).' }
+        inherit_env.own_credentials_withheld:
+          type: boolean
+          description: >-
+            ENGINE CAPABILITY WORD (core `ENGINE_CAPABILITIES`, core 7.51.1; the key IS the word, dotted, value always `true` when present; sdk 23.0.0 `ENGINE_CAPABILITY_WORDS` derives the typed key from the engine's list):
+            a child process spawned on this host NEVER inherits a name the deployment declared as its own credential — every `inheritEnv` policy (`"all"` and `"scrub"` alike) subtracts that list first, and an allow list naming one is
+            refused. It speaks of INHERITANCE only (the engine process's own environment stays readable to same-user processes on the host; a credential that never enters it remains the root fix).
+            ABSENT = an old server (<= 7.128.x) or a word this deployment does not wire: read it as "not promised", not as "absent capability". A shell gates on the word, never on a version number.
         asyncRuns: { type: boolean }
         artifacts: { type: boolean }
         approvals: { type: boolean }
@@ -10089,7 +10115,7 @@ components:
             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`.
+            allow side accepts + notice, deny / ask side refuses, session-rule write doors answer `400 rules.inert_entry` (server >= 7.129.0; 7.123.0–7.128.x answered a retired code, named in the 400 of `PUT /v1/sessions/{sessionId}/policy`).
             🔴 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
@@ -10749,7 +10775,7 @@ components:
             `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).
+            One name, three outcomes: allow side accepts + notice, deny / ask side refuses, session-rule write doors answer `400 rules.inert_entry` (server >= 7.129.0; 7.123.0–7.128.x answered a retired code, named in the 400 of `PUT /v1/sessions/{sessionId}/policy`; `disallowedTools` below is a deny side).
         disallowedTools:
           type: array
           items: { type: string }
@@ -10765,7 +10791,7 @@ components:
             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`.
+            one name, three outcomes: allow side accepts + notice, deny / ask side refuses, session-rule write doors answer `400 rules.inert_entry` (server >= 7.129.0; 7.123.0–7.128.x answered a retired code, named in the 400 of `PUT /v1/sessions/{sessionId}/policy`).
 
     McpServerSpec:
       type: object
@@ -11735,22 +11761,35 @@ components:
       # 把 `AskOrigin` 改真开集的同一条判据)。core 的 `routePairingStatus` 把 `verdict.posture` **直接内插**
       # 进 `ok:${…}`,server 的铸点与 core 的这只函数**全路径没有一处运行期成员判定** —— 一只自带
       # `adjudicateRoute` 的 brain 供什么词就上什么词。写一条会执法的 enum = 假闭集,会把一台合法 worker
-      # 的真响应判违约。已知七词写在 description 里(消费端 switch 认已知词 + 一条 default 臂)。
+      # 的真响应判违约。已知六词写在 description 里(消费端 switch 认已知词 + 一条 default 臂)。
       type: string
       x-open-enum: true
       description: >-
         A model row's key<->URL pairing posture (core `RoutePairingStatus`; server >= 7.45). OPEN on read —
-        the seven words below are today's set, branch on the known ones and keep a `default` arm. NON-SECRET — no
+        the six words below are today's set, branch on the known ones and keep a `default` arm. NON-SECRET — no
         URL, no credential.
         `ok:per-model` this model has its own credential · `ok:paired` deployment credential, and the model's URL
-        is on the deployment's declared root · `ok:unpinned` deployment credential but the deployment declared no
-        root, so the pairing is UNVERIFIABLE · `ok:keyless` no credential anywhere (a local unauthenticated
+        is on the deployment's declared root · `ok:keyless` no credential anywhere (a local unauthenticated
         gateway) · `broken:credential_mismatch` / `broken:credential_missing` a real request WILL be refused by
         the engine (flag it red) · `unknown` could not be adjudicated — render "unknown", NEVER "good" or "bad".
+        🔴 sdk 23.0.0 BREAKING (server >= 7.129.0 / engine 7.51.0): `ok:unpinned` (a deployment credential on a deployment that declared no root, so the pairing was unverifiable) is RETIRED with no alias —
+        on such a deployment the engine now judges the deployment credential `broken:credential_mismatch`. A server <= 7.128.x still sends `ok:unpinned`: it falls in the open tail, render it as
+        "pairing not verified", never as good.
         The verdict's frame of reference is the gateway root as of BRAIN CONSTRUCTION, so a live re-pointing of
         the deployment root only shows up after a restart (both this reading and the real request judge from the
         same snapshot).
 
+    ResumeStartupCause:
+      type: string
+      enum: [environment, session_gone, tool_unavailable, configuration, decision_rejected]
+      description: >-
+        WHY a parked resume could not start its approved action — the engine's closed `RESUME_STARTUP_CAUSES` (core 7.51.0), word for word and in order. The body key of the 422 `parked_resume.startup_failed`
+        (`ErrorResponse.cause`; SDK `ParkedResumeStartupError.startupCause`). Server >= 7.129.0 screens the engine's word against this set before it goes out (a word the engine did not say, or one outside the set => the key is absent).
+        `environment` the leg's infrastructure failed (workspace restore, an abort) — the decision is untouched, retrying replays it · `session_gone` the resumed agent's transcript session is missing ·
+        `tool_unavailable` the approved tool is not available to the resumed leg (gone, or replaced by a different contract) — this approval cannot run, decide afresh · `configuration` the deployment's
+        configuration refuses the resumed leg; a retry under the same configuration fails the same way · `decision_rejected` the decision does not fit the checkpoint (another gate's answer, an input the constraints
+        refuse) — correct it and resubmit. The shared `ErrorResponse.cause` stays an open string in this document because the key is shared by other codes and by servers <= 7.128.x (which relay the engine's word unscreened).
+
     ElicitResponse:
       type: object
       description: >
@@ -12716,6 +12755,7 @@ components:
         seq: { type: integer, description: 'Stop-cycle counter (revive second cycle = higher seq); absent on older engines.' }
         status: { type: string, enum: [completed, failed, killed] }
         summary: { type: string }
+        result: { type: string, description: "server >= 7.129.0 (K-86), the notification frame ONLY (row frames never carry it): the background child's report, the same string the parent model reads in the completion frame (the engine redacts it and truncates it once at the frame's cap; the server redacts again at its own wire boundary, like `summary`). ABSENT = no report. Additive / tolerate-absent." }
         scope: { type: string, enum: [task, session], description: 'Background LIFETIME scope (design/129), NOT the tenant scope.' }
         parentTaskId: { type: string }
         stoppedBy: { type: string, description: 'Verbatim open enum (who/what stopped a killed child).' }
@@ -13264,7 +13304,10 @@ components:
           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`.'
+          description: 'server >= 7.100.0 (S-700): WHY the park row offers no rule — the same narrow read and closed set (four words from server >= 7.129.0) as the live card frame and `card_json`.'
+        boundGrantAbsence:
+          allOf: [{ $ref: '#/components/schemas/BoundGrantAbsence' }]
+          description: 'server >= 7.129.0 (core 7.51.0 #1688; park-row fact eight): why this parked card has no grant-binding digest — the park-row twin seat `PendingAction.tool_approval.boundGrantAbsence`, the same narrow read and the same name / value as the live frame and the inbox row. ABSENT on this face = a skill card (it carries the digest; the digest itself is not on this face) / a row parked before engine 7.51.0 (says neither — the inbox face projects `unreadable` for the same row) / a word outside the set / an old server — NOT `not_bindable`.'
         askClass:
           allOf: [{ $ref: '#/components/schemas/AskClass' }]
           description: 'server >= 7.109.0 (S-934 ② / core 7.37.0 #1214): the park-row twin seat `PendingAction.tool_approval.askClass`, read through `readAskClassPair` — the SAME narrow read as the live frame and the card. Present together with `classes` (`classes[0] === askClass`); the basis a durable approver answers by. Absent = an old row (parked before core 7.37.0; resume does not backfill) or an unreadable pair — NOT "no class". The inbox row (InboxRow) does not carry it.'
@@ -13411,6 +13454,9 @@ components:
         boundGrants:
           allOf: [{ $ref: '#/components/schemas/BoundSkillGrants' }]
           description: 'server >= 7.118.0 — the value `boundGrantDigest` hashes, published ONLY when it hashes to it (the engine judges; a pair that disagrees reads as absent). DEPLOYMENT TEXT: render with contextual escaping.'
+        boundGrantAbsence:
+          allOf: [{ $ref: '#/components/schemas/BoundGrantAbsence' }]
+          description: 'server >= 7.129.0 (core 7.51.0 #1688) — why this card has no `boundGrantDigest` (exactly one of the two; the engine''s summary is total over tool-approval rows — a row parked before engine 7.51.0, which says neither, reads `unreadable` here). Same name and value on the live frame and the operator queue row.'
         classifierNoRuling:
           allOf: [{ $ref: '#/components/schemas/AutoModeFallbackCause' }]
           description: 'server >= 7.118.0 — only on a parked `classifier_no_ruling` card: why the auto-mode classifier did not rule.'
@@ -13893,14 +13939,18 @@ components:
       type: object
       description: >
         E6 (shell-host permissionMode; core SessionPermissionRules session-policy-store.ts) — operator-tightened
-        per-session tool-permission rules (core reads them at prepare-time, SUBTRACT-only). 5 optional `string[]`
-        fields. tighten-only invariant is core-enforced (a loosen needs an operator).
-      properties:
-        toolAllow: { type: array, items: { type: string }, description: Narrowing allowlist (only these tools allowed). }
-        toolDeny: { type: array, items: { type: string }, description: Always-denied tool names (deny wins). }
+        per-session tool-permission rules (core reads them at prepare-time, SUBTRACT-only). THREE optional `string[]`
+        buckets. tighten-only invariant is core-enforced (a loosen needs an operator).
+        🔴 server >= 7.129.0 (engine 7.51.0): ONE grammar. `toolAllow` / `toolDeny` hold rule ENTRIES — a tool name, `mcp__<server>`,
+        or a rule in the tool's own grammar such as `Bash(git push:*)` / `Edit(src/**)`; `toolDeny: ["Bash(rm:*)"]` denies the command name `rm` in any segment of a connected command line.
+        The command buckets `commandAllow` / `commandDeny` are RETIRED (sdk 23.0.0 deletes them, no alias): writing one answers `400 rules.invalid_shape` (never silently ignored — an ignored
+        deny is a deny nobody enforces); `commandDeny: ["rm"]` becomes `toolDeny: ["Bash(rm:*)"]` (which does not deny a path-spelled `/bin/rm ...` nor a command line that does not read as one command name — deny the whole
+        shell with `toolDeny: ["Bash"]` for those); `commandAllow` has no counterpart. A stored SQL row (written by server <= 7.128.x) that still holds a command bucket reads back as `500 corrupt`
+        on this deployment (the operator rewrites that row to the new grammar or deletes the session). An entry the engine reads as nothing answers `400 rules.inert_entry`.
+      properties:
+        toolAllow: { type: array, items: { type: string }, description: 'Narrowing allowlist (only these entries allowed) — rule entries, see the schema description.' }
+        toolDeny: { type: array, items: { type: string }, description: 'Always-denied entries (deny wins) — a tool name, `mcp__<server>`, or a rule such as `Bash(rm:*)`.' }
         allowDirs: { type: array, items: { type: string }, description: Write tools confined to these dirs; bash denied while set. }
-        commandAllow: { type: array, items: { type: string }, description: "Only these bash command names (argv[0]) allowed." }
-        commandDeny: { type: array, items: { type: string }, description: "Always-denied bash command names (argv[0])." }
 
     StoredSessionRules:
       description: '{@link SessionPermissionRules} + the monotonic `rev` the store stamps (the OCC key).'
@@ -13917,22 +13967,32 @@ components:
                 server >= 7.92.0 (engine 7.25.0): the session's rule LINEAGE generation. An erase
                 (`deleteBySession`) ends the lineage — the next write carries gen+1 — so a reader treats a
                 different gen as a new lineage, never a continuation, regardless of rev. Absent on older servers.
+            grammar:
+              type: integer
+              minimum: 0
+              description: >
+                server >= 7.129.0 (engine 7.51.2): the rule GRAMMAR the row's entries are read in, stamped by the
+                engine's write judge on every row written through it (every row this server writes carries `1`).
+                Absent = a row stored before the stamp (grammar 0: an allow entry spelled as a rule, `Bash(rm:*)`,
+                named no tool and admitted nothing — the engine keeps reading such a row that way and announces it
+                once; the one-time migration rewrites stored rows and stamps them). Echoing a stored body back into
+                PUT with its `rev` but no `grammar` is read as grammar 0 (`400 rules.inert_entry`, reason
+                `earlier_grammar`); a `grammar` newer than the engine's answers `400 rules.invalid_shape` (field `grammar`).
       # 🔴 封闭 + 本地镜像(census 批2 第二段,2026-07-30)。同 Event_reasoning 处那条长注的病:
       # `additionalProperties` 只结算**同一个 subschema** 的 `properties`,`allOf` 分支($ref
       # SessionPermissionRules + 内联的 `rev`)声明的键不在它作用域内 ⇒ 只写 `false` 会把合法的
       # `toolAllow`/`rev` 判成违约。镜像的一致性由 spec.test.ts 的通用「封闭 allOf 臂必须镜像被引
       # schema 全部键」门看守(以后往 SessionPermissionRules 加键,忘了同步镜像就当场红)。
-      # 为什么值得封闭:PUT 腿 `routes/sessions.ts` 只挑这 5 个已知字段落店,GET 腿回的是 store
-      # 原样 —— 「store 多回一个键」正是本门要抓的那类漂(消费方按 spec 生成的类型会漏掉它)。
+      # 为什么值得封闭:GET 腿回的是 store 原样 —— 「store 多回一个键」正是本门要抓的那类漂(消费方按 spec 生成的类型会漏掉它)。
+      # server >= 7.129.0 规则体只剩三只桶(命令桶退役,带命令桶的 SQL 存量行读回 500,不会出现在 200 体上)。
       additionalProperties: false
       properties:
         toolAllow: { type: array, items: { type: string } }
         toolDeny: { type: array, items: { type: string } }
         allowDirs: { type: array, items: { type: string } }
-        commandAllow: { type: array, items: { type: string } }
-        commandDeny: { type: array, items: { type: string } }
         rev: { type: integer }
         gen: { type: integer }
+        grammar: { type: integer }
 
     McpServerStatus:
       type: object
@@ -14616,10 +14676,10 @@ components:
           type: string
           description: >-
             server S-818 (riding core #1161), on `parked_resume.startup_failed` (422) ONLY: core's CAUSE WORD for the parked
-            resume's startup failure, relayed verbatim (never rewritten, never defaulted; absent when the engine did not say).
-            An OPEN string here — the closed set is core's (#1161 exports it; the constant's name is in core 7.34.1's release
-            notes). Absent ⇒ cannot tell which of the two causes (see the `/v1/approvals/{sessionId}/decide` 422 text).
-            SDK reads it as `ParkedResumeStartupError.startupCause`.
+            resume's startup failure, relayed (never defaulted; absent when the engine did not say). From server >= 7.129.0 it is
+            one of the engine's closed `RESUME_STARTUP_CAUSES` (core 7.51.0; schema `ResumeStartupCause` — the server screens it, a word outside the set is dropped);
+            server <= 7.128.x relays the engine's word unscreened (an OPEN string — hence the plain `string` here). Absent ⇒ cannot tell which cause (see the
+            `/v1/approvals/{sessionId}/decide` 422 text). SDK reads it as `ParkedResumeStartupError.startupCause` (23.0.0: the five-word `ResumeStartupCause`; a word outside it reads as `undefined`, the raw value stays at `err.extra.cause`).
         remaining:
           type: array
           items: { type: string }
@@ -14636,7 +14696,7 @@ components:
             unreadable) / `unreachable` (unreachable / 5xx / timeout / bad body / any status other than 200 / 409 / 400 / 401 / 403 —
             center 404 / 429 / 3xx included). On 400 `request.field_invalid` for a `settings.permissions` bucket (server >= 7.106.0 /
             S-904): `over_cap` (more than `cap` entries; beside `count` + `cap`) / `bad_entry` (a non-string or empty item; beside
-            `index`). Out-of-vocabulary word ⇒ treat as unknown. (Other codes carry their own `reason` words, e.g. `rules.*`.)
+            `index`). On 400 `rules.inert_entry` (server >= 7.129.0): the engine's `ALLOW_ENTRY_INERT_REASONS` (`tool_name` / `wildcard_all` / `namespace_wildcard` / `content_unsupported` / `grammar` / `near_miss`). Out-of-vocabulary word ⇒ treat as unknown. (Other codes carry their own `reason` words.)
         retryAfterSec:
           type: number
           description: >-
@@ -14648,8 +14708,8 @@ components:
           type: string
           description: >-
             On 400 `request.field_invalid` for a `settings.permissions` bucket (server >= 7.106.0 / S-904): which bucket —
-            `settings.permissions.allow` | `settings.permissions.deny` | `settings.permissions.ask`. (`rules.*` content refusals
-            carry their own `field`.) Resume legs carry the same group on 409 `resume_blocked_by_policy`
+            `settings.permissions.allow` | `settings.permissions.deny` | `settings.permissions.ask`. (`rules.*` refusals
+            carry their own `field`: the bucket on `rules.inert_entry`, the offending key on `rules.invalid_shape`.) Resume legs carry the same group on 409 `resume_blocked_by_policy`
             (`blockedBy: "request.field_invalid"`). Also on 409 `checkpoint.config_refused` (server >= 7.113.0): which part of the
             row's configuration was refused — `taskConfig` (change the configuration, then decide the SAME card again) or
             `inheritedGate` (the row's recorded mode seed is bad — the run can only be cancelled). Also on 400 `request.field_invalid` for a
@@ -14671,7 +14731,7 @@ components:
             are unchanged): an OBJECT `{ event, alias, canonical }` — `event` = the tool event of the refused group (the first refused one when
             several are), `alias` / `canonical` = the engine catalog's alias and canonical name (closed strings, never the caller's raw bytes),
             beside `field: "settings.hooks"`. On 400 `request.field_invalid` for the two `POST /v1/adoption` principal sentences (adoption):
-            a human-readable STRING. Other codes (`rules.*` content refusals: `reason` + human `detail`; core `checkpoint.*` mirrors) carry their
+            a human-readable STRING. Other codes (core `checkpoint.*` mirrors; `rules.*` refusals carry no `detail` — their keys are `field` / `entry` / `reason` / `verdict` / `currentName` / `guidance` / `got` at the top level) carry their
             own `detail`; read it by `errorCode`. SDK: `err.extra.detail` (verbatim, unnamed).
           oneOf:
             - type: object
@@ -15053,9 +15113,8 @@ components:
         persisted rules). It is the personal-store sibling of `org`: same VETO family (it can overturn an approval
         a person already gave, and it re-judges an edited command), which is why it is neither `policy` nor
         `ask_resolution` · `classifier` = the auto-mode classifier denied directly ·
-        ⚰️ `plan_mode` = RETIRED WORD (server <= 7.105.0 / core <= 7.33.x): plan mode's read-only block on a write tool —
-        core 7.34.0 design/1111 folded it into `mode`, server 7.106.0 no longer emits it; kept because servers inside this SDK's
-        support floor still send it (delete when the floor passes 7.106.0) · `mode` (server >= 7.106.0 / core 7.34.0) = the
+        (⚰️ `plan_mode` — server <= 7.105.0 / core <= 7.33.x: plan mode's read-only block on a write tool, folded into `mode` by core 7.34.0 design/1111 — is NOT in this set since sdk 23.0.0: it is an
+        ARCHIVE word of the gate record, see `GateRecordDeniedBy`) · `mode` (server >= 7.106.0 / core 7.34.0) = the
         permission MODE refused a surviving ask on its own account — `dontAsk` turns an ask nobody can answer into a refusal,
         `bypassPermissions` refuses a write whose protection could not be judged; the deny arm then carries `mode` / `askClass` /
         `classes` (core invariant I8) · `compliance` = the compliance call-time
@@ -15064,11 +15123,48 @@ components:
         `read_boundary` = the shell READ STATION refused (core 7.25.0 #945): a deny-listed read before any approval,
         or an approved rewrite re-judged onto a deny row (beside `settlement.kind: "human_allowed"`); may veto, carries no `cause`.
         🔴 CLOSED ON THIS WIRE, and deliberately not marked open: the engine's invariant screen
-        (`screenGateOutcome`) treats an out-of-set `deniedBy` as a DEFECT, and the service withholds a defective
-        record WHOLE (report + withhold). A word outside this set therefore cannot reach a consumer — it arrives
-        as the `gate` key being ABSENT, never as an unfamiliar word. Same rule for `Settlement.kind` and for
-        `GateOutcome.origin`.
-      enum: [policy, hook, org, persisted_rule, classifier, plan_mode, compliance, write_protection, ask_resolution, read_boundary, mode]
+        (`screenGateOutcome`) treats a word that NO engine generation ever minted as a DEFECT, and the service withholds a defective
+        record WHOLE (report + withhold). Since server >= 7.129.0 (engine 7.51.0) the screen reads the gate record as an ARCHIVE:
+        today's words PLUS the engine's retired words (`RETIRED_MEMBERS`) — `GateRecordDeniedBy` is that archive set; this schema is today's set
+        (the request / card faces). Same rule for `Settlement.kind` and for `GateOutcome.origin`.
+      enum: [policy, hook, org, persisted_rule, classifier, compliance, write_protection, ask_resolution, read_boundary, mode]
+
+
+    # ── sdk 23.0.0 · server >= 7.129.0 (engine 7.51.0 `RETIRED_MEMBERS`): the GATE RECORD's archive sets ──────────────────────────────────────────
+    # 门记录({@link GateOutcome}:`tool_end.gate`、turns / trace 回放、`GET /v1/runs/:id/events` 的账本裸回放)只过引擎的 `screenGateOutcome` 一次,缺省按**档案**读:
+    # 每只闭集 = 引擎今天的词 ∪ 引擎退役词表里那一集。这五张 enum 与引擎 `RETIRED_MEMBERS` 逐集逐词同(由 `server-7129-wire` 对拍);卡面 / 队列行 / 请求面的同名闭集只取今天的词。
+    GateRecordAskClass:
+      type: string
+      enum: [content_question, hook, ancestor, dangerous_delete, unverifiable_delete, unverifiable_shell_text, transcript_write, org_rule, rule_unreadable, ask_rule, denial_limit_fallback, classifier_no_ruling, requires_user_interaction, operator_forced, shell_floor, target_unresolved, probe, write_protection, tool_marks_mcp, tool_marks_a2a, policy_rra, artifact_shared_read, mode, unstated, ordinary, write_protection_unresolved, governance_unavailable]
+      description: >-
+        The class word on a GATE RECORD (`tool_end.gate.disposition.askClass` / `.classes` on the mode-refusal arm, `ModeRelease.askClass` / `.classes`) — server >= 7.129.0 reads the record as an ARCHIVE:
+        today's `AskClass` set (twenty-five words) PLUS the words the engine retired (`write_protection_unresolved`, retired in core 7.49.0 — renamed `target_unresolved`; `governance_unavailable`,
+        retired in core 7.51.0 — merged into `rule_unreadable`). A record the previous engine generation legally wrote is replayed byte for byte (a 7.50.x mode refusal can carry `governance_unavailable`);
+        a word NO engine generation ever minted (a case variant, the empty string, a future word) withholds the whole `gate` and counts `server.trace.gate-outcome-defective`.
+        Render a known archive word normally and an unknown one generically; never drop the record because the word is not in today's set.
+    GateRecordDeniedBy:
+      type: string
+      enum: [policy, hook, org, persisted_rule, classifier, compliance, write_protection, ask_resolution, read_boundary, mode, plan_mode]
+      description: >-
+        `deniedBy` on a GATE RECORD (archive read, server >= 7.129.0): today's `DeniedBy` set PLUS the retired `plan_mode` (core 7.34.0 folded it into `mode`). Same reading as `GateRecordAskClass`.
+    GateRecordModeReleaseReason:
+      type: string
+      enum: [target_unresolved, write_protection_unresolved, rule_unreadable]
+      description: >-
+        `released.reason` on a GATE RECORD (archive read, server >= 7.129.0): today's one word `target_unresolved` (core `MODE_RELEASE_REASONS`) PLUS the retired `write_protection_unresolved`
+        (server 7.122.0–7.125.x spelling, retired in core 7.49.0) and `rule_unreadable` (server <= 7.126.x: the release went over an unreadable rule; retired in core 7.50.0). Server 7.127.0–7.128.x
+        OMITTED `reason` for the two retired words (`released` was still sent); from 7.129.0 they arrive verbatim on the replay faces. Same reading as `GateRecordAskClass`.
+    GateRecordPersistedRuleMandate:
+      type: string
+      enum: [operator_always, tool_marks, probe_mandate, probe_unanswered, write_protection, target_unresolved, write_protection_unresolved]
+      description: >-
+        `released.mandate` on a GATE RECORD (archive read, server >= 7.129.0): today's six `PersistedRuleMandate` words PLUS the retired `write_protection_unresolved` (core 7.49.0 rename). Same reading as `GateRecordAskClass`.
+    GateRecordAskOrigin:
+      type: string
+      enum: [content_question, plan_review, ancestor_marked, org_unavailable, org_rule, rule_store_unavailable, hook, ask_rule, denial_limit_fallback, shell_gate_tighten, safety_tighten, policy, unresolvable]
+      description: >-
+        `origin` on a GATE RECORD (`GateOutcome.origin`, `ModeRelease.origin`; archive read, server >= 7.129.0): core's twelve `ASK_ORIGINS` PLUS the retired `unresolvable` (core 7.14.0 renamed it `ancestor_marked`).
+        🔴 CLOSED on this face — the engine judges membership here — unlike the OPEN `AskOrigin` of the approval-card faces (the server only checks a non-empty string there). Same reading as `GateRecordAskClass`.
 
     Settlement:
       description: >
@@ -15247,7 +15343,7 @@ components:
           required: [kind, deniedBy]
           properties:
             kind: { const: denied }
-            deniedBy: { $ref: '#/components/schemas/DeniedBy' }
+            deniedBy: { $ref: '#/components/schemas/GateRecordDeniedBy' }
             classifier:
               allOf: [{ $ref: '#/components/schemas/GateClassifierAttribution' }]
               description: >
@@ -15275,12 +15371,12 @@ components:
                 that refused. `dontAsk` turns an ask nobody can answer into a refusal; `bypassPermissions` refuses a write whose
                 protection could not be judged. `plan` refuses nothing here (its questions ask).
             askClass:
-              allOf: [{ $ref: '#/components/schemas/AskClass' }]
-              description: 'Beside `mode`: the refused ask''s disclosed class word.'
+              allOf: [{ $ref: '#/components/schemas/GateRecordAskClass' }]
+              description: 'Beside `mode`: the refused ask''s disclosed class word (gate-record archive read — a 7.50.x mode refusal can carry the retired `governance_unavailable`).'
             classes:
               type: array
-              items: { $ref: '#/components/schemas/AskClass' }
-              description: 'Beside `mode`: the whole folded class set.'
+              items: { $ref: '#/components/schemas/GateRecordAskClass' }
+              description: 'Beside `mode`: the whole folded class set (archive read, see `GateRecordAskClass`).'
 
     PermissionMode:
       type: string
@@ -15293,9 +15389,9 @@ components:
         `UNATTENDED_PERMISSION_MODE=dontAsk`).
     AskClass:
       type: string
-      enum: [content_question, hook, ancestor, dangerous_delete, unverifiable_delete, unverifiable_shell_text, transcript_write, org_rule, governance_unavailable, rule_unreadable, ask_rule, denial_limit_fallback, classifier_no_ruling, requires_user_interaction, operator_forced, shell_floor, target_unresolved, probe, write_protection, tool_marks_mcp, tool_marks_a2a, policy_rra, artifact_shared_read, mode, unstated, ordinary]
+      enum: [content_question, hook, ancestor, dangerous_delete, unverifiable_delete, unverifiable_shell_text, transcript_write, org_rule, rule_unreadable, ask_rule, denial_limit_fallback, classifier_no_ruling, requires_user_interaction, operator_forced, shell_floor, target_unresolved, probe, write_protection, tool_marks_mcp, tool_marks_a2a, policy_rra, artifact_shared_read, mode, unstated, ordinary]
       description: >
-        core `ASK_CLASSES` (twenty-two words as of core 7.40.0, twenty-three as of core 7.41.0, twenty-four as of core 7.43.0, twenty-five as of core 7.45.0, twenty-six as of core 7.49.0 — 7.34.0 minted twenty; `unverifiable_shell_text` joined in 7.49.0 #1505 and rides server >= 7.126.0, where the
+        core `ASK_CLASSES` (TWENTY-FIVE words as of core 7.51.0 / server >= 7.129.0: `governance_unavailable` was merged into `rule_unreadable`, no alias — sdk 23.0.0; a stored card / parked row written by server <= 7.128.x is rewritten once by the server at boot. The gate record reads the ARCHIVE form, see `GateRecordAskClass`. History: twenty-two words as of core 7.40.0, twenty-three as of core 7.41.0, twenty-four as of core 7.43.0, twenty-five as of core 7.45.0, twenty-six as of core 7.49.0 — 7.34.0 minted twenty; `unverifiable_shell_text` joined in 7.49.0 #1505 and rides server >= 7.126.0, where the
         unresolved-write-target class was also RENAMED to `target_unresolved` (#955; zero alias — the previous spelling is in the SDK README's 22.0.0 migration table); `shell_floor` joined in 7.39.0 #1260 and rides
         server >= 7.113.0; `unstated` joined in 7.40.0 and rides server >= 7.115.0; `requires_user_interaction` joined in 7.41.0 and rides
         server >= 7.116.0; `classifier_no_ruling` joined in 7.43.0 #1353 and rides server >= 7.118.0; `dangerous_delete` joined in 7.45.0 and rides
@@ -15307,6 +15403,7 @@ components:
         it: no mode (`bypassPermissions` included), no allow (request `settings.permissions.allow`, operator `APPROVAL_GRANT`, a stored allow row, a
         skill's tool list, a hook's allow) and no `auto` classifier does; the frame carries `requiresRealApproval: true`, nobody answering means the
         call does not run (the unattended leg refuses), and it is bypass-IMMUNE (not a releasable class).
+        `rule_unreadable` (core 7.51.0 / server >= 7.129.0 also covers the organization snapshot that could not be read — the former `governance_unavailable`) = a rule that may govern this call could not be READ (the organization's snapshot, a partition of the person's own rule store, or the rule this call was read against); bypass-immune.
         `unverifiable_shell_text` (core 7.49.0 #1505, server >= 7.126.0) = the engine CANNOT READ the text this shell will execute — the shell is fed
         text the command does not spell (a program's output, a substitution, a file's content, an argv a stream fills in: `bash -c "$CMD"`,
         `eval "$(…)"`, `xargs sh -c …`; shell text that does not parse or is nested too deep lands here too). Its arbitration row is
@@ -15334,7 +15431,7 @@ components:
         `shell_floor` = the operator's `shellGate: "always"` floor on a shell-running seat (the question the `operator_always` mandate
         word discloses), a class of its own so a set that holds another forced question still holds it; like `operator_forced` it is
         bypass-IMMUNE (not releasable).
-        CLOSED on the gate record (screened with core `isAskClass`). `bypassPermissions` releases only the RELEASABLE classes (core
+        CLOSED: the card / queue-row / request faces carry exactly today's twenty-five words; the GATE RECORD (`tool_end.gate` and the replay faces) carries today's words PLUS the engine's retired words (`GateRecordAskClass`). `bypassPermissions` releases only the RELEASABLE classes (core
         `releasableAskClassesFor(face)`). Server >= 7.127.0 (core 7.50.0): nine on every face (`transcript_write` / `probe` / `write_protection` /
         `tool_marks_mcp` / `tool_marks_a2a` / `artifact_shared_read` / `mode` / `unstated` / `ordinary`) plus a tenth on the SHELL face only,
         `target_unresolved` (shell 10, other faces 9; on the file tools that class is refused, `deniedBy: mode`); `rule_unreadable` is no longer released
@@ -15353,30 +15450,29 @@ components:
         `permission.ask_released_by_mode` per run.
       properties:
         mode: { $ref: '#/components/schemas/PermissionMode' }
-        askClass: { $ref: '#/components/schemas/AskClass' }
-        classes: { type: array, items: { $ref: '#/components/schemas/AskClass' } }
+        askClass: { $ref: '#/components/schemas/GateRecordAskClass' }
+        classes: { type: array, items: { $ref: '#/components/schemas/GateRecordAskClass' } }
         origin:
-          type: string
-          enum: [content_question, plan_review, ancestor_marked, org_unavailable, org_rule, rule_store_unavailable, hook, ask_rule, denial_limit_fallback, shell_gate_tighten, safety_tighten, policy]
-          description: 'The origin word the card would have shown (core `ASK_ORIGINS`; screened closed on this face, same list as `GateOutcome.origin`).'
-        mandate: { $ref: '#/components/schemas/PersistedRuleMandate' }
+          allOf: [{ $ref: '#/components/schemas/GateRecordAskOrigin' }]
+          description: 'The origin word the card would have shown (core `ASK_ORIGINS`, archive read — screened closed on this face, same set as `GateOutcome.origin`).'
+        mandate:
+          allOf: [{ $ref: '#/components/schemas/GateRecordPersistedRuleMandate' }]
+          description: 'The mandate word the card would have shown (today''s six `PersistedRuleMandate` words plus the retired spelling, archive read).'
         reason:
-          type: string
-          enum: [target_unresolved]
+          allOf: [{ $ref: '#/components/schemas/GateRecordModeReleaseReason' }]
           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 of ONE word — the server screens it with core `isModeReleaseReason`, so a word
-            outside it withholds the whole `gate` from the frame.
+            set holds; ABSENT when the set holds none. Today's set has ONE word, `target_unresolved` (core `MODE_RELEASE_REASONS`); the GATE RECORD reads the ARCHIVE form
+            (server >= 7.129.0, `GateRecordModeReleaseReason`), so the engine's two retired words can also arrive verbatim on the replay faces.
             `target_unresolved` = the release went over a write whose landing place could not be determined (a link on the way could not be examined,
             or the environment could not resolve the target), so whether it lands on a guarded path 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.
-            History (this SDK's type and this enum hold the one word from 22.0.0; a word an older server sends reads as OUT OF SET and is not rewritten):
-            server 7.122.0–7.125.x (core 7.47.0–7.48.x) spelled this member differently (the SDK README's 22.0.0 migration table); server <= 7.126.x also
-            had `rule_unreadable` (the release went over a rule this call could not be read against) — core 7.50.0 / server >= 7.127.0 releases an
-            unreadable rule under no mode, so that member left (`rule_unreadable` stays an `AskClass`). Before server 7.122.0 the set was `rule_unreadable` alone.
+            History (sdk 22.0.0 narrowed this to one word; sdk 23.0.0 reads the archive form because server >= 7.129.0 replays the engine's retired words verbatim):
+            the two retired words are the server 7.122.0–7.125.x spelling of today's word and, on server <= 7.126.x, `rule_unreadable` (the release went over a rule this call
+            could not be read against) — core 7.50.0 / server >= 7.127.0 releases an unreadable rule under no mode (`rule_unreadable` stays an `AskClass`). Before server 7.122.0 the set was `rule_unreadable` alone.
 
     GateClassifierAttribution:
       # sdk 9.5.0:具名 —— 同一份形挂在 `GateDisposition` 的两只臂上,内联会立刻是两份会各自漂的镜像。
@@ -15455,16 +15551,13 @@ components:
           allOf: [{ $ref: '#/components/schemas/Settlement' }]
           description: 'Present only when THIS pass settled an ask. Same-present/same-absent as `origin` (I1).'
         origin:
-          allOf:
-            - { $ref: '#/components/schemas/AskOrigin' }
-            # 🔴 闭集执法**只在这一面**:引擎的 `screenGateOutcome` 对 `origin` 判成员,出集即记录缺陷,而
-            #   服务对缺陷记录是整条不上帧 ⇒ 词表外的值在这条 wire 上到不了消费端。审批帧那一面不判成员,
-            #   所以 `AskOrigin` 本体保持真开(见该 schema 的长注)。这张 enum 是本 spec 里该词表的**唯一**
-            #   执法点;core 加词时改这一处。
-            - enum: [content_question, plan_review, ancestor_marked, org_unavailable, org_rule, rule_store_unavailable, hook, ask_rule, denial_limit_fallback, shell_gate_tighten, safety_tighten, policy]
+          allOf: [{ $ref: '#/components/schemas/GateRecordAskOrigin' }]
+          # 🔴 闭集**执法**只在门记录这一面:引擎的 `screenGateOutcome` 对 `origin` 判成员(server >= 7.129.0 按**档案**读:今天的十二词 ∪ 退役词 `unresolvable`),
+          #   任何一代引擎都没铸过的词即记录缺陷,服务对缺陷记录是整条不上帧。审批帧那一面不判成员,所以 `AskOrigin` 本体保持真开(见该 schema 的长注)。
+          #   闭集执法点 = `GateRecordAskOrigin` 这一张 enum(门记录的两个引用点 `GateOutcome.origin` / `ModeRelease.origin` 共用);core 加词时改这一处。
           description: >
-            WHO ASKED. Same-present/same-absent as `settlement` (I1). CLOSED here (and only here) — see the
-            enum note above.
+            WHO ASKED. Same-present/same-absent as `settlement` (I1). CLOSED here (archive read, `GateRecordAskOrigin`) — see the
+            note above.
 
     McpProbeFace:
       type: object
@@ -16593,8 +16686,9 @@ components:
         `toolCallId` joins the `tool_approval` card / `tool_end`; `sessionId` is conditional. Not a block; not counted by
         `classifier.denial_limit`. · `config.permission_mode_unavailable` — the requested mode is NOT the mode this leg runs,
         `{ requested, effective, by, sessionId, runId, childSessionId? }`, `requested` / `effective` = core's six mode words, `by` = core
-        `PERMISSION_MODE_FOLD_REASONS` (`operator_deny` / `face_absent` / `inherited_ceiling` — the last is ALSO minted onto the PARENT
-        session's stream with `childSessionId`); the first two arms always have `effective: default`; the server-side
+        `PERMISSION_MODE_FOLD_REASONS` (`operator_deny` / `face_absent` / `inherited_ceiling`); from core 7.51.0 / server >= 7.129.0 a child leg's fold on ANY of the three arms is ALSO minted onto the PARENT
+        session's stream (`detail.sessionId` = the parent, `childSessionId` = the child; dedupe by `childSessionId`) and `requested` reads as "the word that was folded" (a child that requested nothing: the word it inherited);
+        the first two arms always have `effective: default`; the server-side
         `settings.permissions.disableAutoMode` fold happens before the engine and mints no frame. · `permission.ask_released_by_mode`
         — `bypassPermissions` released an ask nobody answered, `{ mode, askClass, origin?, mandate?, count, firstToolCallId, sessionId, runId }`,
         first time per (mode, askClass) per run (`count` is 1); the per-call record is `tool_end.gate.disposition.released`. ·
@@ -16619,6 +16713,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.129.0 (the user-visible whitelist grows 37 -> 38 codes; contract appendix D.3): `permission.entry_mode_clamped` (SERVER-minted, audience `user`, at most one frame per submission) — the operator's
+        entry floor `AUTONOMY=plan` folded the requested permission mode (top-level `permissionMode` or `settings.permissions.defaultMode`, whichever took effect) back to `plan`, so this run starts in a different mode
+        (before, the fold was undisclosed). `detail` = `{ requested, effective, ceiling, sessionId }` — `requested` the folded word, `effective` the word the run starts in, `ceiling` the floor that folded it, all
+        three from core's six `PERMISSION_MODES`, passed through verbatim; there is no `runId` (the fold happens at the admission door, before the engine mints a run identity — attribute the frame by the stream / ledger it lands on).
+        Sent on the two fresh legs (`POST /v1/tasks/stream` / `POST /v1/runs`) at the open beat, before any model output; NOT sent when there is no entry floor, no word was declared, the requested word is not looser than the floor,
+        on the resume family, or on the synchronous non-streaming `POST /v1/tasks` (that leg has no notice port). It is a different fact from `config.permission_mode_unavailable` (the engine's own fold), which cannot see this one.
         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
@@ -16746,7 +16846,13 @@ components:
           type: ['string', 'null']
           description: >
             server.ts —— 一条 resume 腿把 run 重新挂回 suspended 时,带上「为什么重开」的 errorCode
-            (无则显式 null)。只出现在这条重开臂上;普通挂起帧不带此键。
+            (无则显式 null)。只出现在这条重开臂上;普通挂起帧不带此键。server >= 7.129.0:重开与否只按店里那一行判(不再按失败码的三码名单),所以名单外的失败码也会出现在这里;
+            `plan_review` 的重开落 `needs_review`(同形)。
+        toolCallId:
+          type: string
+          description: >
+            The tool call the run is parked on (a tool-approval gate; ABSENT for a tool-less park / when it could not be read — never `null`). Same value as the `tool_approval` card's `toolCallId`. The server's park ledger row has
+            always carried it (sdk 23.0.0 declares it; this arm is closed, so a strict validator rejected a real replay row before).
     ModelUsageDelta:
       # 新增(2026-07-25 回填批)。SDK 的 facade 审计把这个形状命名了一次(此前是在两个使用点各写一遍的匿名内联形:
       # `AgentEvent` 的 `model_usage` 臂 与 `done.result.stats.modelUsage` 的值类型,同源同形)。
@@ -17105,7 +17211,7 @@ components:
 
             🔴 PRESENCE IS THE PROMISE (same as `ruleSuggestions`): present only where a permission-rule store
             is really wired. The converse does not hold — a wired deployment still omits it for mandated /
-            requiresRealApproval / shadowed / hook-produced / inherited-unresolved / ancestor-resolved /
+            requiresRealApproval / allow_outranked / ask_rule_matched / hook-produced / inherited-unresolved / ancestor-resolved /
             anonymous asks. Absence reads as "THIS CARD has no such option", never as "this deployment has no
             rule lane" (that is `capabilities.permissionRules`) and never as "your rule broke" (that is
             `allowRuleShadowed`; `persistedRuleShadowed` on a server <= 7.116.x).
@@ -17358,6 +17464,9 @@ components:
         boundGrants:
           allOf: [{ $ref: '#/components/schemas/BoundSkillGrants' }]
           description: 'server >= 7.118.0, "tool_approval" only — the value `boundGrantDigest` hashes; present iff it is. DEPLOYMENT TEXT: render with contextual escaping.'
+        boundGrantAbsence:
+          allOf: [{ $ref: '#/components/schemas/BoundGrantAbsence' }]
+          description: 'server >= 7.129.0 (core 7.51.0 #1688), "tool_approval" only — why this card has no `boundGrantDigest` (exactly one of the two). Same name and value on the inbox row, the operator queue row and the `pending` stream frame; passed through verbatim.'
         classifierNoRuling:
           allOf: [{ $ref: '#/components/schemas/AutoModeFallbackCause' }]
           description: >-
@@ -17743,21 +17852,38 @@ components:
 
     RuleOffersAbsence:
       type: string
-      enum: [mandated, shadowed, lane_cannot_speak]
+      enum: [mandated, allow_outranked, ask_rule_matched, lane_cannot_speak]
       description: >
         WHY `ruleOffers` is absent while the rule lane IS present (`ToolApprovalFrame.ruleOffersAbsence` and
         `ApprovalCard.ruleOffersAbsence`; server >= 7.55.0 / core #490 fix ②, S-15). The engine names which
         door is shut: `mandated` = this ask must be confirmed every time (🔴 this arm must NOT point the user
-        at writing a rule — a rule would not silence it, and saying so sends them into a loop); `shadowed` = a
-        an allow-layer member matched but could not clear it (the machine-readable twin of `allowRuleShadowed`; `persistedRuleShadowed` on a server <= 7.116.x);
-        `lane_cannot_speak` = the engine could mint no coverable form for this command.
+        at writing a rule — a rule would not silence it, and saying so sends them into a loop); `allow_outranked` = an
+        allow-layer member matched this call but the ask sits at a higher tier, so another allow rule cannot clear it (the machine-readable twin of `allowRuleShadowed`; `persistedRuleShadowed` on a server <= 7.116.x);
+        `ask_rule_matched` = an explicit `ask` rule matched this call (same frame `origin: ask_rule`): it keeps asking, an allow rule would not silence it either; a card from the deployment name-list gate
+        `APPROVAL_REQUIRE` / the supervisor route that reports an explicit ask-rule hit lands here too; `lane_cannot_speak` = a rule COULD clear this ask but the lane cannot speak this time (the engine could mint no coverable form for this command).
+        🔴 sdk 23.0.0 BREAKING (server >= 7.129.0 / engine 7.51.0, `RULE_OFFERS_ABSENCES`): the former `shadowed` meant two things and is split into the middle two words, no alias; a card / parked row that a server <= 7.128.x
+        stored with `shadowed` is rewritten once by the server at boot (the key is dropped — an absent reason is legal).
 
         Engine-side MUTUALLY EXCLUSIVE with `ruleOffers`. 🔴 ABSENCE IS NOT AN ASSERTION — it covers both
-        "there are offers" and the three structural doors, and one frame cannot tell them apart. ADVISORY
+        "there are offers" and the structural doors, and one frame cannot tell them apart. ADVISORY
         display metadata, NEVER adjudication input. The frame and the stored `card_json` go through the SAME
-        server-side narrow read, so both faces carry identical values; a word outside the set is treated as
+        server-side narrow read, so both faces carry identical values; a word outside the four is treated as
         malformed and the key is not minted at all (the server never passes an unknown word through).
 
+    BoundGrantAbsence:
+      type: string
+      enum: [not_bindable, unreadable]
+      description: >
+        WHY a tool-approval card has NO grant-binding digest (`ToolApprovalFrame.boundGrantDigest`) — the engine's closed `BOUND_GRANT_ABSENCES` (core 7.51.0 #1688; server >= 7.129.0). The engine mints
+        EXACTLY ONE of the digest and this word on every card. `not_bindable` = this ask is not an activation of the engine's `Skill` tool, so it binds no grant: approving it grants nothing else, and "allow for this
+        session" can be remembered per tool. `unreadable` = the card binds a grant but what it binds could not be read (a stored row whose digest is not a string, or says neither — a row parked before engine 7.51.0
+        reads as this on the inbox face); on a live card the engine always supplies the digest, so this word shows up only where STORED rows are read.
+        Four carriers, same name and same value: the live `tool_approval` frame (and `livePending[].frame`), the inbox row, the operator queue row and the `/v1/approvals/stream` `pending` frame; `card_json` and the
+        presented-card frame do not carry it.
+        🔴 ABSENCE IS NOT `not_bindable`: a skill card carries the digest (exactly one of the two), and an old server (<= 7.128.x projects it on none of the faces), a row parked before engine 7.51.0 on the queue face (it says neither),
+        and a word outside the set all read as ABSENT — a card without this word must not be treated as "approving it grants nothing else"; whether to render "allow for this session" is `rememberRefused`.
+        Display metadata, never an adjudication input. CLOSED: the server narrows with the engine's members, anything else reads as absent.
+
     PersistedRuleMandate:
       type: string
       enum: [operator_always, tool_marks, probe_mandate, probe_unanswered, write_protection, target_unresolved]
@@ -18892,7 +19018,7 @@ components:
       type: object
       description: >
         DURABLE only (design/80 D-B, server http/server.ts) — a RESUMED plan_review leg got re-gated into
-        another review pause. Same payload shape as `suspended`: the gate verbatim, or an explicit `null`.
+        another review pause. Same payload shape as `suspended`: the gate verbatim, or an explicit `null`; plus `toolCallId?` / `reopened?` (sdk 23.0.0 declares both; the arm is closed).
         NOTE `needs_review` is BOTH a `RunStatus` terminal and a `CheckpointGate.kind`; this arm is the third
         use of the name — the stream frame announcing that pause.
       additionalProperties: false
@@ -18904,6 +19030,14 @@ components:
           oneOf:
             - $ref: '#/components/schemas/CheckpointGate'
             - type: 'null'
+        reopened:
+          type: ['string', 'null']
+          description: >
+            server >= 7.129.0 — same reading as `suspended.reopened`: a resume leg failed BEFORE the approved step started and the `plan_review` gate went back to `needs_review`; the errorCode of that failure (explicit null when it had none).
+            (Before 7.129.0 a `plan_review` reopen of the three listed codes was recorded as `suspended`.) Ordinary frames do not carry the key.
+        toolCallId:
+          type: string
+          description: 'Same as `suspended.toolCallId` (ABSENT when the park has no tool call; never `null`).'
     Event_message_committed:
       type: object
       description: >
@@ -19199,6 +19333,9 @@ components:
         ruleOffersAbsence:
           allOf: [{ $ref: '#/components/schemas/RuleOffersAbsence' }]
           description: '`pending` frames only (server >= 7.100.0 / S-700) — see PendingCheckpoint.ruleOffersAbsence.'
+        boundGrantAbsence:
+          allOf: [{ $ref: '#/components/schemas/BoundGrantAbsence' }]
+          description: '`pending` frames only (server >= 7.129.0 / core 7.51.0 #1688) — see PendingCheckpoint.boundGrantAbsence. A `live_pending` frame carries it only inside its `frame`.'
         askClass:
           allOf: [{ $ref: '#/components/schemas/AskClass' }]
           description: '`pending` frames only (server >= 7.109.0 / S-934 ②) — see PendingCheckpoint.askClass. A `live_pending` frame carries the pair only inside its `frame`.'
@@ -20437,12 +20574,12 @@ components:
         remember for this session's category (fs-write tools share ONE category: approving Write covers
         Edit/NotebookEdit; other tools are per-tool) — the CC "don't ask again this session" semantic.
 
-    ToolApprovalRespondAck:
+    ToolApprovalRespondApplied:
       type: object
       description: >
-        The 200 ack of POST /v1/tool-approvals/{approvalId}/respond (server tool-approval.ts — exact
-        shape, `decision` echoed). Owner-gated with a 404 and NO existence oracle: non-owner and
-        unknown/settled/expired/wrong-replica ids are indistinguishable.
+        The APPLIED arm of the 200 ack of POST /v1/tool-approvals/{approvalId}/respond (server tool-approval.ts — exact
+        shape, `decision` echoed): the decision settled a live gate. Owner-gated with a 404 and NO existence oracle: non-owner and
+        unknown/settled/expired/wrong-replica ids are indistinguishable. See ToolApprovalRespondAck for the replayed arm.
       # 封闭(census 批2 第三段,2026-07-30):铸造点 `tool-approval.ts` 三恒在键 + 两条件键
       # (rememberApplied/updatedInputForwarded 的条件展开就在同一行字面量里)。
       # #154 车二(2026-08-10):`persistRuleAfterDecision` 的 `withFlag()` 在同一个体上再盖两个条件键
@@ -20544,6 +20681,33 @@ components:
             server ignores the unknown key and still answers 200, so "this build does not know `note`" is only
             distinguishable via `capabilities.approvalDecisionNote` — probe that bit before sending `note`.
 
+    ToolApprovalRespondReplayed:
+      type: object
+      description: >
+        The REPLAYED arm of the 200 ack of POST /v1/tool-approvals/{approvalId}/respond: the ask was already DECIDED
+        (by anyone) when this answer arrived, so the server replays the FIRST decision — `decision` is the row's two-word
+        value (`allow_session` was folded to `allow` when it landed), `decidedAtMs` the first decision's clock,
+        `decisionNote` only when the row has one, `rememberApplied: false` only when THIS request asked `allow_session`.
+        No `delivery` key: nothing was delivered. A reversed late answer is the same replay — not a 409, nothing re-judged.
+        (server src/tool-approval.ts `replayDecidedAsk`; sdk 23.0.0 declares it, the shape predates it.)
+      required: [approvalId, askId, idempotent, decision, decidedAtMs]
+      additionalProperties: false
+      properties:
+        approvalId: { type: string }
+        askId: { type: string }
+        idempotent: { type: boolean, enum: [true] }
+        decision: { type: string, enum: [allow, deny] }
+        decidedAtMs: { type: integer }
+        decisionNote: { type: string }
+        rememberApplied: { type: boolean, enum: [false] }
+    ToolApprovalRespondAck:
+      description: >
+        The 200 ack of POST /v1/tool-approvals/{approvalId}/respond — a discriminated union: the decision was APPLIED to a live
+        gate (ToolApprovalRespondApplied, `delivery: "applied"`) or the ask was already decided and the first decision is
+        REPLAYED (ToolApprovalRespondReplayed, `idempotent: true`). The discriminant is `idempotent`.
+      oneOf:
+        - $ref: '#/components/schemas/ToolApprovalRespondApplied'
+        - $ref: '#/components/schemas/ToolApprovalRespondReplayed'
     UsageMetric:
       type: string
       enum: [tasks, tokensIn, tokensOut, costUsd]