@sema-agent/sdk 16.2.0 → 16.3.0

package/openapi.yaml

@@ -417,7 +417,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), `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: `), `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
@@ -886,6 +886,13 @@ paths:
             ⚠️ Against a server 7.19.0–7.22.0 the OLD caveat applies verbatim: only the parked legs dedupe —
             a lost 200 retried with the same key injects TWICE with byte-identical receipts; treat a lost 200
             there as "outcome unknown", never "safe to retry".
+            🔴 server >= 7.117.0 — TWO MORE 409 answers on a TERMINAL run (the `parked_for_wake` leg), refused BEFORE the wake card is minted
+            (no card is minted; the row is untouched; on 7.116.x this was a 202 `parked_for_wake` followed by a refusal at `/wake`, i.e. a card that could
+            never be redeemed): when the stored submit body of this session is one this version no longer replays — errorCode
+            `checkpoint.unsupported_version` (`retriable: true` = the card is still pending / cancellable, NOT "a retry will succeed"; the stored body carries
+            `settings.permissions.allow` under an earlier reading — list or statement era) or errorCode `resume_blocked_by_policy` (`blockedBy: "request.field_invalid"`;
+            the stored skill `disallowedTools` carries an entry the engine now reads as nothing). Both answers are word-for-word the ones `POST /v1/sessions/{sessionId}/wake`
+            gives for the same body. Way out: cancel the task and resubmit as a new one (with the entry fixed). The SDK does not retry them (409 is not in the retry set).
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -7187,6 +7194,13 @@ components:
           description: 'core 5.11.0: extra READ-ONLY absolute host paths — read fence only (classify read-boundary auto-allow + read_file/grep containment); writes to the same dirs are still refused. Same shape/400 rules as additionalDirectories; servers <6.6.0 silently ignore (harmless additive).'
         images:
           type: array
+          description: >
+            Image input: `{ data, mimeType }` (inline base64) or `{ url }`. 🔴 INLINE-ARM ADMISSION (server >= 7.117.0 / core 7.42.0): `mimeType` must be one of `image/png` /
+            `image/jpeg` / `image/gif` / `image/webp` (the API's type word, not a file extension), the decoded bytes must carry the DECLARED type's file signature, and the decoded size must
+            not exceed 5 MiB — otherwise the engine refuses BEFORE the first model call (after the UserPromptSubmit hook; not one model token spent) with 400 `config.image_invalid`, whose
+            `error` starts with `TaskSpec.images: `. Before 7.117.0 such an image was sent as-is to the model provider and the whole first request failed there (no code to branch on).
+            A base64 string longer than 5 242 880 characters (the model API's 5 MB image cap; the server reads the engine's exported constant) is NOT this code: the submit gate refuses it first
+            with 413 `request.payload_too_large` (zero model calls, no submit hook, no run row). The `{ url }` arm is unchanged. The model must accept image input (`ModelInfo.vision`; absent = unknown, send anyway).
           items:
             oneOf:
               - type: object
@@ -7330,9 +7344,20 @@ components:
             the delivery lane, so raising it only helps a model whose declared window is below 200 000 tokens.
             The engine's own twin code `config.skill_listing_budget_invalid` (400) is NOT reachable through this
             submit leg today — it belongs to callers that build a `TaskSpec` directly.
-            🔴 `permissions.allow` IS A STATEMENT, NOT A WHITELIST (server >= 7.115.0 / S-654; probe
-            `capabilities.settings.permissions.allowGrant === true` — an absent key is an older server that reads the bucket as a
-            list, so put nothing in it there). The bucket is compiled by the SAME rule compiler as `deny` / `ask`: a hit is a
+            🔴 `permissions.allow` — THE READING DEPENDS ON THE SERVER GENERATION (probe `capabilities.settings.permissions`; an absent bit = the older generation).
+            server >= 7.117.0 (`allowLayer === true`, core 7.42.0): the WHOLE list goes to the engine's allow layer and a listed call is NOT ASKED — the engine's ordinary and
+            "nobody stated it" questions are cleared, built-in write gates and shell checks included (like the reference implementation's `permissions.allow`); content forms
+            (`Bash(git:*)`, `Read(//dir/**)`) are accepted; entries the engine reads as nothing (`*`, write-path forms such as `Edit(src/**)`, domain forms, names with whitespace) are NOT
+            refused — the run opens with an `engine_notice` `permission.allowed_tool_not_granted`. Any layer's deny / ask rule, operator `APPROVAL_REQUIRE` / `APPROVAL_NEVER_AUTO` /
+            `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.
+            🔴 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`.
+            The skill lists (`skills[].allowedTools`) read exactly like this bucket from 7.117.0 on.
+            Server 7.115.0–7.116.x (`allowGrant` without `allowLayer`): `permissions.allow` IS A STATEMENT, NOT A WHITELIST — an absent `allowGrant` is a server <= 7.114.x that reads the bucket
+            as a list, so put nothing in it there. The bucket is compiled by the SAME rule compiler as `deny` / `ask`: a hit is a
             reasoned allow = "somebody stated it" (it answers an MCP / A2A server-tool call nobody stated; without it an
             ask-class mode raises a card, and with no approval surface the call is refused); a miss states nothing and the call is
             judged as usual — a tool off the list is NOT refused any more (<= 7.114.x refused it). It does NOT skip the question
@@ -9414,22 +9439,28 @@ components:
         settings:
           type: object
           description: >
-            🔴 server >= 7.115.0 (S-654), ALWAYS present: `{ permissions: { allowGrant: true } }` — the VERSION bit for "which reading does this
-            server give `settings.permissions.allow` on a task submit". `permissions.allowGrant === true` = the `allow` bucket is compiled into
-            ALLOW RULES: a hit gives "somebody stated it" (so an MCP / A2A server-tool call nobody stated no longer raises a card) — it is NOT
-            "skip the question" and NOT a whitelist (a tool off the list is no longer refused; the engine's own write gate / shell checks still ask
-            on built-in tools, deny / ask still win; a bad-shape or content-form name is a whole-request 422).
-            🔴 ABSENT KEY = 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"). A version bit: constant `true`, never varies with the deployment; the deployment-level "who stated what"
-            (operator env `APPROVAL_GRANT`) is on the operator diagnostics face (`serverGates.approvalGrant`), not here.
+            🔴 server >= 7.115.0, ALWAYS present: `{ permissions: { allowGrant: true } }`; server >= 7.117.0 adds `allowLayer: true` to `permissions` — the VERSION bits for
+            "which reading does this server give `settings.permissions.allow` on a task submit" (both constant `true`, never vary with the deployment: the single-user
+            and `REQUIRE_PRINCIPAL=true` forms carry the same value). Read three levels: `settings` -> `permissions` -> <bit>; an absent / non-boolean bit = a server without it.
+            `permissions.allowGrant === true` (>= 7.115.0) = the `allow` bucket is read as allow RULES, not as a list (a tool off the list is no longer refused).
+            `permissions.allowLayer === true` (>= 7.117.0, core 7.42.0) = the server hands the WHOLE `allow` list to the engine's allow layer: a listed call is NOT ASKED (the engine's
+            ordinary and "nobody stated it" questions are cleared — built-in write gates / shell checks included, like the reference implementation's `permissions.allow`); content forms
+            (`Bash(git:*)`, `Read(//dir/**)`) are accepted; entries the engine reads as nothing (`*`, write-path / domain forms, names with whitespace) are NOT refused — the run opens with an
+            `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.
+            🔴 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
+            deployment-level "who stated what" (operator env `APPROVAL_GRANT`) is on the operator diagnostics face (`serverGates.approvalGrant`), not here.
           additionalProperties: true
           properties:
             permissions:
               type: object
               additionalProperties: true
               properties:
-                allowGrant: { type: boolean, description: 'Constant `true` on server >= 7.115.0: `settings.permissions.allow` is read as allow RULES (a statement), not as a list. The whole `settings` key being absent = an older server.' }
+                allowGrant: { type: boolean, description: 'Constant `true` on server >= 7.115.0: `settings.permissions.allow` is read as allow RULES, not as a list. The whole `settings` key being absent = an older server.' }
+                allowLayer: { type: boolean, description: 'Constant `true` on server >= 7.117.0 (core 7.42.0): the whole `settings.permissions.allow` list goes to the engine allow layer (listed calls are not asked; content forms accepted; entries read as nothing get an `engine_notice` `permission.allowed_tool_not_granted`). Absent = a server without it (7.115.0–7.116.x: allow is a statement; older: a list).' }
         memoryWrite:
           type: boolean
           description: >
@@ -10014,8 +10045,9 @@ components:
         🔴 server >= 7.116.0 (core 7.41.0): a skill carries two TOOL LISTS, `allowedTools` / `disallowedTools` — the
         run-scoped ALLOW-RULE and DENY-RULE source of the skill once it is activated. NOT a fence (<= 7.115.x the engine read
         the skill's tool list as "only these"): unlisted tools are judged as usual, listed ones are not asked about for the rest
-        of the run — which makes it WIDER than `settings.permissions.allow` (that one stays a statement and does not
-        release the engine's own write gate / shell ordinary asks on built-in tools). Probe `capabilities.skillToolLists`
+        of the run. On server 7.116.x that made it WIDER than `settings.permissions.allow` (then a statement that did not
+        release the engine's own write gate / shell ordinary asks on built-in tools); server >= 7.117.0 reads the two request-level
+        allow sources the SAME way (see `capabilities.settings.permissions.allowLayer`). Probe `capabilities.skillToolLists`
         (absent = an old server that accepts the keys on a top-level skill and silently ignores them). The skill's `manifest`
         key is RETIRED: any value on a top-level skill is a 400 `request.field_invalid` ("skill.manifest was retired in core
         7.41.0 — …"; rewrite `manifest.allowTools` to `allowedTools`; `allowPaths` has no replacement), and on a delegated
@@ -10032,21 +10064,28 @@ components:
             server >= 7.116.0. The skill's run-scoped ALLOW-RULE source (permission-rule spellings: a tool name,
             `mcp__<server>` / `mcp__<server>__*`; `*`, write paths and domain forms grant nothing). Once the skill is activated
             (named in top-level `userInvokedSkills` — no `Skill` card — or activated by the model and the card approved) the
-            listed tools are not asked about for the rest of the run: it clears the engine's ordinary and "nobody stated it" asks,
-            so it is WIDER than `settings.permissions.allow`; deny / ask rules, `APPROVAL_REQUIRE`, `APPROVAL_NEVER_AUTO`, the shell
-            floor, write protection and plan-mode asks are not cleared. NOT a fence: unlisted tools are judged as usual. A non-string-array
-            is a 400 `request.field_invalid`; a protocol name whose server segment cannot be minted / is missing / is a wildcard
-            (`mcp__*`) is a 400 too (top-level `skills[]` and `agents[].skills[]` judge identically). Probe `capabilities.skillToolLists`.
+            listed tools are not asked about for the rest of the run: it clears the engine's ordinary and "nobody stated it" asks;
+            deny / ask rules, `APPROVAL_REQUIRE`, `APPROVAL_NEVER_AUTO`, the shell floor, write protection and plan-mode asks are not cleared.
+            NOT a fence: unlisted tools are judged as usual. Versus `settings.permissions.allow`: on server 7.116.x this list was WIDER (that bucket
+            was then only a statement); server >= 7.117.0 reads the two the SAME way, entry for entry (entries the engine reads as nothing get an
+            `engine_notice` `permission.allowed_tool_not_granted`). A non-string-array is a 400 `request.field_invalid`; a protocol name whose server
+            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`.
         disallowedTools:
           type: array
           items: { type: string }
           description: >
             server >= 7.116.0. The skill's run-scoped DENY-RULE source (same grammar / gates / probe as `allowedTools`): once the skill
             is activated these tools are refused for the run (no execution, no card; `tool_end.gate.disposition` is
-            `{ kind: "denied", deniedBy: "policy" }`). `*` and domain forms (`WebFetch(domain:…)`) read as "none" on this side too —
-            accepted with 2xx and only an operator-audience notice `skills.allowed_tool_not_granted`; write-path forms and the rest compile
-            into deny rows (as the server contract states it for the engine's `compileSkillGrant`; the SDK did not re-run the engine on the deny side's write-path forms —
-            the engine's own notice text lists "a write-path or domain entry" among entries that "grant (or refuse) nothing").
+            `{ kind: "denied", deniedBy: "policy" }`); write-path forms and command rules compile into deny rows too.
+            🔴 server >= 7.117.0: an entry the engine reads as nothing (`*`, a domain form `WebFetch(domain:…)`, a protocol name with a wildcard, a name with
+            whitespace or malformed) is refused AT SUBMIT — 400 `request.field_invalid`, `error` = `skill.disallowedTools entry "<entry>" reads as nothing (<reason>): <how to write it>`
+            (delegated level: prefix `agents[<i>]: skills[<j>]: `), top-level `skills[]` and `agents[].skills[]` alike — because an entry that looks like a refusal but refuses nothing is
+            worse than none (<= 7.116.x accepted it with only an operator-audience notice that was not sent to the session stream; that code is now `permission.allowed_tool_not_granted`,
+            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.
 
     McpServerSpec:
       type: object
@@ -10788,16 +10827,17 @@ components:
         baseUrl/apiKey/headers (the service strips them).
       # 🔴 封闭 + required 补铸造点(census 批2 第三段,2026-07-30):铸造点 `routes/capabilities.ts`
       # 是逐键字面量投影(白名单,不是透传——「open set」旧注不成立,新键要先过这道 spec)。core Model 类型
-      # 里 id/provider/reasoning 都是必填、`vision` 由 `input` 恒算 ⇒ 五键无条件;contextWindow/maxOutputTokens
-      # 0/缺省即省略,supportedEffortLevels 仅 reasoning 模型。
-      required: [name, id, provider, reasoning, vision]
+      # 里 id/provider/reasoning 都是必填 ⇒ 四键无条件;contextWindow/maxOutputTokens 0/缺省即省略,
+      # supportedEffortLevels 仅 reasoning 模型。🔴 server 7.117.0 起 `vision` 是三态(收 / 不收 / 没声明 `input`),
+      # 没声明 ⇒ 键缺席 ⇒ 不再是必有键(此前由 `input` 恒算成布尔,对没声明的条目报 false)。
+      required: [name, id, provider, reasoning]
       additionalProperties: false
       properties:
         name: { type: string, description: 'the @mention handle (user-pickable model name).' }
         id: { type: string, description: 'underlying model id (display, e.g. deepseek-v4-pro).' }
         provider: { type: string }
         reasoning: { type: boolean, description: 'a reasoning-tier model (picker can badge it).' }
-        vision: { type: boolean, description: 'accepts image input.' }
+        vision: { type: boolean, description: 'Whether this catalog row accepts image input — THREE states (server >= 7.117.0; before it a row that declared no `input` reported `false`): `true` = the row declares `input` and it contains "image"; `false` = declares `input` without it; ABSENT = the row declared no `input` (a hand-written catalog entry; the env lane and the config-center lane always declare it). ABSENT means UNKNOWN, not false: treat it as "send the image anyway and tell the user", do not read it as `false` and block the image locally — the server hands the image to the model for that same row at run time. Only an explicit `false` justifies "this model does not take images".' }
         contextWindow: { type: integer, description: 'E4 (SHIPPED) — context-window token DENOMINATOR for the %-used gauge; omitted when unknown.' }
         maxOutputTokens: { type: integer, description: 'E4 (SHIPPED) — single-call max output tokens; omitted when unknown.' }
         supportedEffortLevels:
@@ -12260,6 +12300,16 @@ components:
             toolName: { type: string }
             summary: { type: string }
             touchedPaths: {}
+            allowRuleShadowed:
+              type: array
+              items: { $ref: '#/components/schemas/AllowRuleShadow' }
+              description: >
+                server >= 7.117.0 (core 7.42.0): the DURABLE dual of `ToolApprovalFrame.allowRuleShadowed` — the allow-layer members that matched this call
+                and could not clear its ask (same shape and semantics; entries are secret-redacted again at the server's read boundary). Passed through whole
+                on `GET /v1/approvals` and `/v1/approvals/stream`. Absent != "you have no rule". 🔴 The old key `shadowedRule` (a string, server <= 7.116.x)
+                is RETIRED: the SQL backend rewrote its parked rows once at the 7.117.0 boot to `[{ member: "persisted", entries: [<old value>] }]`, but the
+                file backend's pre-upgrade parked rows and run results already on disk (`checkpointGate.riskDescriptor`) keep the old key verbatim
+                (text still redacted, no structured disclosure) — a consumer reading those must still tolerate the old string.
         # server 7.16.0 [3684]② — durable 队列行归因两键(与活卡 tool_approval 帧的同名键语义同族、判据不同源;
         # 两条腿对同一只 ask 的在场性可以不一致,两侧都只认在场、都禁把缺席读成否定)。
         ruleSuggestions:
@@ -13628,6 +13678,8 @@ components:
             `not_found.resource` / `request.unprocessable` / `capability.unavailable` …). ALWAYS PRESENT on server >= 7.104.0
             (S-607); before that it was absent when the original refusal carried no code. SDK:
             `ResumeBlockedByPolicyError.blockedBy` (`undefined` when the key is absent or not a string — never defaulted).
+            server >= 7.117.0 adds a third fold source: a stored skill `disallowedTools` entry the engine now reads as nothing (the submit leg's 400 `request.field_invalid` sentence)
+            ⇒ `blockedBy: "request.field_invalid"`, refused before the claim; the terminal-run steer leg answers it before minting the wake card.
 
     ResumeLegConflictError:
       description: >
@@ -15905,29 +15957,45 @@ components:
             requiresRealApproval / shadowed / 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
-            `persistedRuleShadowed`).
+            `allowRuleShadowed`; `persistedRuleShadowed` on a server <= 7.116.x).
 
             ⚠️ REDEMPTION SCOPE is the live respond leg keyed by this frame's `approvalId` only; a replayed
             offer on another replica is not a promise that it is still redeemable.
         persistedRuleShadowed:
           type: string
+          deprecated: true
           description: >
-            server >= 7.13.0 (core 5.25.0 #144), ADDITIVE, "tool_approval" only: this ask MATCHED one of the
+            🔴 RETIRED by server 7.117.0 (core 7.42.0) — replaced by `allowRuleShadowed`, no alias. A server >= 7.117.0 never mints this key
+            (its strict card schema even refuses a stored card carrying it); only a server <= 7.116.x still does, and the SDK keeps the declaration
+            for those servers (the supported floor is far below 7.117.0). Slated for deletion in the next major.
+
+            For those older servers (server >= 7.13.0 / core 5.25.0 #144, ADDITIVE, "tool_approval" only): this ask MATCHED one of the
             caller's persisted allow rules and that rule COULD NOT silence it. The value is the shadowed rule's
             VERBATIM text (secret-redacted + length-bounded). UNTRUSTED for display, same treatment as `message`.
-
-            It documents a BEHAVIOUR NARROWING ("Allow rules silence the CLASSIFIER's questions, never a MANDATED
-            one"): under MANUAL_MODE_SHELL_GATE=always, for tools carrying an egress/irreversible mark, and under
-            the governance gates, asks a rule used to silence now REAPPEAR. Render an explanatory line ("your rule
-            is still there — this call must be confirmed each time"); without it the only conclusion a user can
-            draw is "my rule broke", while the rule sits fine in the store.
-
-            🔴 ABSENT != "you have no rule": present only when a rule matched AND could not clear the ask. Most
-            asks have no match at all, and matched-and-cleared ones never become asks (they were silenced — no
-            card exists). 🔴 Deliberately SEPARATE from `governanceForced` and not derivable from it: that key
-            answers "who imposed the gate", this one answers "what happened to YOUR rule"; governance is only one
-            of three un-silenceable sources (doctrine `always` and a tool's own mark carry no governance badge).
-            The durable dual is `gate.riskDescriptor.shadowedRule` on the parked row.
+            🔴 ABSENT != "you have no rule": present only when a rule matched AND could not clear the ask. 🔴 Deliberately SEPARATE
+            from `governanceForced` and not derivable from it: that key answers "who imposed the gate", this one answers "what
+            happened to YOUR rule". The durable dual on those servers is `gate.riskDescriptor.shadowedRule` on the parked row.
+        allowRuleShadowed:
+          type: array
+          items: { $ref: '#/components/schemas/AllowRuleShadow' }
+          description: >
+            server >= 7.117.0 (core 7.42.0), ADDITIVE, "tool_approval" only — BREAKING RENAME, replacing the retired string `persistedRuleShadowed`
+            (no alias): the allow-layer members that MATCHED this call and could NOT clear this ask, one `{ member, entries, omitted? }` record per
+            matching member (see AllowRuleShadow). `member` is one of `hook` / `deployment` / `persisted` / `skill` / `request`; `entries` are the
+            entries that member matched, as their source spells them (UNTRUSTED for display like `message`, secret-redacted, <= 512 chars each,
+            <= 32 listed; a `hook` record's `entries` is always the empty list); `omitted` counts the entries not listed.
+
+            The explaining sentence ("... matches this call but does not clear the ask — <reason>") is IN `message` (the engine writes it where it builds
+            the card); this key is the structured twin of the same fact. Render a line from it ("your rule matched, but this call must be confirmed each
+            time"): without it the only conclusion a user can draw is "my rule broke".
+
+            🔴 ABSENT != "you have no rule": present only when a member matched AND could not clear the ask; a match that cleared never becomes an ask.
+            🔴 `member: "hook"` does not say whose hook (a deployment PreToolUse hook and, on the single-user lane, the request's own `settings.hooks`
+            share one member). 🔴 Deliberately SEPARATE from `governanceForced` (that one: "who imposed the gate"; this one: "what happened to YOUR
+            rule"). What the allow layer can NOT clear: any layer's deny / ask rule, operator `APPROVAL_REQUIRE` / `APPROVAL_NEVER_AUTO` /
+            `MANUAL_MODE_SHELL_GATE=always`, write protection, sensitive-path writes, governance, a hook's ask, plan-mode asks. The durable dual is
+            `gate.riskDescriptor.allowRuleShadowed` on the parked row (PendingCheckpoint.riskDescriptor). Rolling-upgrade caveat: a card stored by a
+            <= 7.116.x replica (`card_json` carrying `persistedRuleShadowed`) cannot be read by a >= 7.117.0 replica — the replay skips it.
         probeCause:
           type: object
           description: >
@@ -16320,12 +16388,21 @@ components:
             promise and the per-leg index rules are stated verbatim on ToolApprovalFrame.ruleOffers.
         persistedRuleShadowed:
           type: string
+          deprecated: true
+          description: >
+            🔴 RETIRED by server 7.117.0 (core 7.42.0) — replaced by `allowRuleShadowed`, no alias (a server >= 7.117.0 never mints it; the strict card
+            schema refuses a stored card carrying it). Only a server <= 7.116.x still does; slated for deletion in the next major. For those servers
+            (ADDITIVE, server >= 7.13.0 / core 5.25.0 #144): the VERBATIM text of the persisted rule this ask matched but which could not silence it
+            (secret-redacted + length-bounded). UNTRUSTED for display. Semantics, the ABSENT != "you have no rule" clause and the deliberate separation
+            from `governanceForced` are stated verbatim on ToolApprovalFrame.persistedRuleShadowed.
+        allowRuleShadowed:
+          type: array
+          items: { $ref: '#/components/schemas/AllowRuleShadow' }
           description: >
-            ADDITIVE (server >= 7.13.0 / core 5.25.0 #144): the VERBATIM text of the persisted rule this ask
-            matched but which could not silence it (secret-redacted + length-bounded). UNTRUSTED for display.
-            Semantics, the ABSENT != "you have no rule" clause and the deliberate separation from
-            `governanceForced` are stated verbatim on ToolApprovalFrame.persistedRuleShadowed — the live frame,
-            the stored `card_json` and the replayed frame carry the SAME material.
+            ADDITIVE (server >= 7.117.0 / core 7.42.0, BREAKING RENAME of the retired `persistedRuleShadowed`): the allow-layer members that matched this
+            call and could not clear this ask. Semantics, the five members, the always-empty `hook` entries, the explaining sentence living in `message`,
+            the ABSENT != "you have no rule" clause and the separation from `governanceForced` are stated verbatim on ToolApprovalFrame.allowRuleShadowed
+            — the live frame, the stored `card_json`, the replayed frame and the `approval_request` card carry the SAME material.
         fromSubagent: { type: boolean, enum: [true], description: 'Present ⇔ the ask comes from a DELEGATED child — the explicit discriminator (a worker cannot forge it).' }
         sourceTaskId: { type: string, description: 'The child''s core session id — row-join value + fallback discriminator.' }
         sourceAgentName: { type: string, description: 'The child agent''s display name, redacted. UNTRUSTED.' }
@@ -16450,6 +16527,37 @@ components:
         `.strict()`). The eleven known words are exported at runtime as the SDK's `ASK_ORIGINS` (core 7.32.1
         `ASK_ORIGINS`, verbatim and in order) — known words, NOT an enforcement table.
 
+    AllowRuleMember:
+      type: string
+      enum: [hook, deployment, persisted, skill, request]
+      description: >
+        The closed five-word vocabulary of `AllowRuleShadow.member` (server >= 7.117.0 / core 7.42.0 `ALLOW_RULE_MEMBERS`, verbatim and in the order the engine reads the members). The SDK exports
+        it at runtime as `ALLOW_RULE_MEMBERS`. Owner = core; read it as an open string with a default arm (core may add a member and the server follows).
+
+    AllowRuleShadow:
+      type: object
+      additionalProperties: false
+      required: [member, entries]
+      description: >
+        One allow-layer DISCLOSURE record (`ToolApprovalFrame.allowRuleShadowed` / `ApprovalCard.allowRuleShadowed` / the durable
+        `PendingCheckpoint.riskDescriptor.allowRuleShadowed`; server >= 7.117.0 / core 7.42.0 `AllowRuleShadow`): one member of the allow layer that
+        MATCHED the call and could NOT clear its ask. At most one record per member, at most five per ask. The vocabulary owner is core; the server
+        drops the whole key on a member outside the five words, so a >= 7.117.0 server only ever sends these five — still read `member` as an open
+        string with a default arm (core may add members and the server follows).
+      properties:
+        member:
+          $ref: '#/components/schemas/AllowRuleMember'
+          description: >
+            Which allow-layer member matched, in the order the engine reads them: `hook` = a PreToolUse hook's explicit `allow` (a deployment hook or,
+            on the single-user lane, the request's own `settings.hooks` — the key cannot say which) · `deployment` = the operator's `APPROVAL_GRANT` ·
+            `persisted` = a person's stored allow rules · `skill` = an activated skill's `allowedTools` · `request` = the request's `settings.permissions.allow`.
+        entries:
+          type: array
+          maxItems: 32
+          items: { type: string, maxLength: 512 }
+          description: 'The entries that member matched, as their source spells them (UNTRUSTED for display, secret-redacted, <= 512 chars each, <= 32 listed). Always the empty list for `hook` — its word is about the call, not about an entry.'
+        omitted: { type: integer, minimum: 1, description: 'How many matched entries were not listed (beyond the cap). Absent = none omitted.' }
+
     RuleOffersAbsence:
       type: string
       enum: [mandated, shadowed, lane_cannot_speak]
@@ -16458,7 +16566,7 @@ components:
         `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
-        rule matched but could not clear it (the machine-readable twin of `persistedRuleShadowed`);
+        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.
 
         Engine-side MUTUALLY EXCLUSIVE with `ruleOffers`. 🔴 ABSENCE IS NOT AN ASSERTION — it covers both

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "16.2.0",
+  "version": "16.3.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",