@sema-agent/sdk 8.1.0 → 8.2.0

package/openapi.yaml

@@ -3358,31 +3358,21 @@ paths:
                 decision: { type: string, enum: [allow, allow_session, deny] }
                 updatedInput: { description: 'ctrl+g edited tool args (replaces the asked args on allow).' }
                 persistRule:
-                  type: object
-                  # 刻意**不**封闭:server 的 `parseToolApprovalResponse` 只读 `rule`,对象里多给的键它**忽略**
-                  # (与 `updatedInput` 同一条宽收姿势)。写 `additionalProperties:false` 会让照 spec 生成的
-                  # 客户端拒发一个 server 其实会受理的请求 —— 那是我们自己造的漂移,不是上游的约束。
-                  required: [rule]
-                  properties:
-                    rule: { type: string, minLength: 1, maxLength: 512, description: 'Non-empty (the server parser rejects an empty string); at most MAX_RULE_TEXT_CHARS = 512.' }
+                  allOf: [{ $ref: '#/components/schemas/PersistRuleSelection' }]
                   description: >
-                    server #154 车二, ADDITIVE — the person ticked "don't ask again": echo back, VERBATIM, the
-                    `rule` of the chosen entry of the frame's `ruleSuggestions`. Allow-family only (on `deny`
-                    the server tolerantly ignores it, same posture as `updatedInput`).
-
-                    🔴 A CANDIDATE, NOT FREE TEXT: the server locates this string in the candidate table the
-                    engine minted and refuses if it does not match (`ruleRefusal: "rule_not_offered"`). Do not
-                    hand-build it, re-case it or append `:*` — take it from the frame.
-                    🔴 Together with `updatedInput` the persistence is refused (`rule_input_edited`): the call
-                    that takes effect is the edited one while the candidates came from the ORIGINAL command.
-                    The decision itself still stands.
-                    ⚠️ If the frame carried no `ruleSuggestions`, do not send this key — there is nothing
-                    redeemable for THIS card and the answer is necessarily `rulePersisted:false` +
-                    `rule_lane_unavailable` (the missing material short-circuits BEFORE any candidate
-                    comparison, so it is never `rule_not_offered`). Absence has THREE possible causes — no rule
-                    store wired, the engine minted no candidate for this command (compound / redirect /
-                    substitution), or the command bytes were unreadable — so do NOT diagnose the deployment's
-                    rule lane from one frame or from that refusal.
+                    The person ticked "don't ask again". TWO MUTUALLY EXCLUSIVE ARMS — the candidate/edited arm
+                    `{ rule, edited? }` and the batch arm `{ batchOfferIndex }`; the shapes, the server's four
+                    verbatim 400 texts, the two capability bits to probe first and the `deny` posture are on
+                    the PersistRuleSelection schema. Allow-family only (on `deny` the whole field is ignored).
+
+                    ⚠️ If the frame carried neither `ruleOffers` nor `ruleSuggestions`, do not send this key —
+                    there is nothing redeemable for THIS card and the answer is necessarily
+                    `rulePersisted:false` + `rule_lane_unavailable` (the missing material short-circuits BEFORE
+                    any candidate comparison, so it is never `rule_not_offered`). Absence has several causes —
+                    no rule store wired, the engine minted no offer for this command (compound / redirect /
+                    substitution), the command bytes were unreadable, or this ask belongs to one of the seven
+                    families that never get offers — so do NOT diagnose the deployment's rule lane from one
+                    frame or from that one refusal.
                 note:
                   type: string
                   maxLength: 2048
@@ -6603,6 +6593,39 @@ components:
             `noteRecorded` (a live-card-only deployment has no row to write, and a flapping store cannot write
             one; both answer `false` while the decision itself still stands). This bit only says "this build
             knows the key" — same family as `permissionRulesRevoke`, deliberately gated on no facility.
+        respondFreeFormRules:
+          type: boolean
+          description: >
+            server >= 7.44.0 (#340), hard-coded true in the capability object — the VERSION PROBE for the
+            free-text arm of POST /v1/tool-approvals/{id}/respond (`persistRule.edited: true`): the rule to
+            persist is text the person HAND-EDITED on the card, not one of the engine's candidates.
+
+            PROBE IT BEFORE RENDERING THE EDITABLE INPUT. The live respond body validator is a NON-STRICT
+            hand-written parser, so an older worker DROPS the unknown `edited` key and judges the text AS A
+            CANDIDATE, answering `rule_not_offered` — honest, but a person reads it as "I typed it wrong".
+            Absent means an older worker: do not render the affordance.
+
+            IT DOES NOT PROMISE THIS ONE WILL LAND (deliberately no facility predicate, same family as
+            `approvalDecisionNote`): that is per-call and answered by `rulePersisted` / `ruleRefusal` —
+            `edit-unsupported` (this card has no binding anchor, STOP rendering the box) versus
+            `edit-rejected` (fix it and try again). Whether the LANE exists at all is `permissionRules`,
+            computed per caller; read the two bits together.
+        respondBatchRuleOffers:
+          type: boolean
+          description: >
+            server >= 7.46.0 (design/377), hard-coded true — the VERSION PROBE for the batch arm of the same
+            endpoint (`persistRule.batchOfferIndex`): the person ticked a `kind: "batch"` offer, and the
+            selection key is that offer's index in the frame's `ruleOffers`.
+
+            PROBE IT BEFORE RENDERING A REDEEMABLE BATCH AFFORDANCE: an older worker drops the unknown key and
+            then fails the `rule` shape check with a 400 — honest, but it cannot tell a batch was ticked. With
+            the bit absent, render batch offers read-only.
+
+            Same posture as above: it only says "this binary knows this key". Whether THIS redemption lands is
+            answered per call by `rulePersisted` / `ruleRefusal`, with `persistedRules` on success and (server
+            >= 7.48.0) the per-entry anchors `persistedRuleAnchors` — that additive key deliberately gets NO
+            second capability bit, since it rides the same batch redemption channel and a consumer just reads
+            whether it is there.
         promptSuggestions: { type: boolean, description: "Follow-up prompt suggestions are generated." }
         modelUsage:
           type: boolean
@@ -8023,6 +8046,27 @@ components:
             display order; an EXACT entry, when present, is always first. core contract caps candidates at 2;
             the server enforces a tolerance cap of 4 on read-back — lay out for 4. Absent = pre-column row
             (parked before the column existed) OR no candidates; render both as "no candidates", never an error.
+        ruleOffers:
+          type: array
+          minItems: 1
+          items: { $ref: '#/components/schemas/RuleOffer' }
+          description: >
+            server >= 7.46.0 (core 5.58.0, design/375) — the discriminated-union successor of the retired
+            `ruleSuggestions` above on the DURABLE queue row (core `PendingAction.ruleOffers`, the same
+            contract as the sync leg's `AskRequest.ruleOffers`). A >= 7.46.0 row carries only the new key;
+            pre-5.58 rows fail the new narrow read entry by entry and land as "no supply" (no compatibility
+            read — a stale schema means re-ask).
+
+            🔴 THE INDEX ON THIS LEG IS NOT A SELECTION KEY. This projection drops malformed offers one by one
+            and COMPACTS, so an excision shifts every later index forward. That is only sound because this leg
+            has NO redemption mouth (POST /v1/approvals/{sessionId}/decide takes no rule field). Using it as
+            `persistRule.batchOfferIndex` would redeem a different rule than the one the person clicked. The
+            live card leg is the opposite (pure prefix truncation, no per-entry drops) and is where redemption
+            actually happens.
+
+            🔴 DISPLAY / TRIAGE ONLY, and ABSENT MEANS THERE REALLY IS NO SUPPLY (rule lane unarmed, the
+            command yields no rule, no rule could silence this ask, or an old row) — never "the projection
+            dropped it", which is precisely the bug this key exists to close. Never `null`, never `[]`.
         governanceForced:
           type: boolean
           enum: [true]
@@ -9889,6 +9933,38 @@ components:
             replica ⇒ redeemable; after a restart / on another replica that `approvalId` 404s and the person
             must use the durable decide leg, which carries NO rule field in v1 (its body is strict — an extra
             `persistRule` is a loud 400, not a silent drop).
+        ruleOffers:
+          type: array
+          minItems: 1
+          items: { $ref: '#/components/schemas/RuleOffer' }
+          description: >
+            server >= 7.46.0 (core 5.58.0, design/375), "tool_approval" only — the ENGINE-minted "don't ask
+            again" OPTIONS for this ask, as a DISCRIMINATED UNION (`single` | `batch`). It is the BREAKING
+            REPLACEMENT of `ruleSuggestions` above: a >= 7.46.0 engine mints the old key nowhere, there is no
+            alias, and the two keys are declared side by side only so one type surface covers both generations.
+
+            🔴 READ `kind` TO TELL THE ARMS APART, never a positional assumption. ORDER IS CONTRACT: a
+            whole-string exact `single` is index 0 when present and a `batch` is always last; core's own
+            cardinality is <= 2 while the server enforces a tolerance cap of 4.
+
+            🔴 INDEX SEMANTICS DIFFER PER LEG, and only one leg can redeem. On THIS leg (and on the
+            `approval_request` card and the durable replay of both) the server prefix-truncates and never drops
+            an entry, so the index equals core's offer index and IS a legal selection key for
+            `persistRule.batchOfferIndex`. On the durable queue row (PendingCheckpoint.ruleOffers) the server
+            drops malformed entries and COMPACTS, so indexes shift there and that leg has no redemption mouth
+            at all. A consumer that drops entries itself must keep every survivor's ORIGINAL wire index, or
+            suppress its persistence actions entirely (core's normative clause) — a compacted index means the
+            k-th option the person clicked is not the k-th rule the server redeems.
+
+            🔴 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 /
+            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`).
+
+            ⚠️ 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
           description: >
@@ -10123,6 +10199,15 @@ components:
             the PRESENCE-IS-THE-PROMISE clause (present only where a rule store is wired) and the redemption
             scope are stated verbatim on ToolApprovalFrame.ruleSuggestions — the live frame, the stored
             `card_json` and the replayed frame carry the SAME material.
+        ruleOffers:
+          type: array
+          minItems: 1
+          items: { $ref: '#/components/schemas/RuleOffer' }
+          description: >
+            server >= 7.46.0 (core 5.58.0, design/375) — the discriminated-union replacement of
+            `ruleSuggestions` above. Same material as the live frame and the stored `card_json` (the server
+            projects all three through one `copyRuleOffer`), so semantics, order-is-contract, presence-is-the-
+            promise and the per-leg index rules are stated verbatim on ToolApprovalFrame.ruleOffers.
         persistedRuleShadowed:
           type: string
           description: >
@@ -10163,13 +10248,269 @@ components:
           description: '`exact` = this one command only (`Bash(git status)`); `prefix` = word-boundary prefix (`Bash(git status:*)`). Closed vocabulary — an unknown value is not a candidate this contract describes; do not render it as redeemable.'
         command: { type: string, maxLength: 512, description: 'The command pattern inside the rule, for a shell that would rather not re-parse `rule`.' }
 
+    RuleOfferMatch:
+      type: string
+      description: >
+        The MATCH FORM of a persisted rule — the server's `PERSISTED_RULE_MATCHES`, verbatim (the vocabulary
+        is OWNED BY CORE; the server only transcribes it and pins set equality, so core adding a member turns
+        the server red at compile time).
+
+        `exact` = this one command only (`Bash(git status)`). `prefix` = the historical colon-star
+        word-boundary prefix (`Bash(git status:*)`) and the ONLY spelling for a compound prefix form; it stays
+        a permanent compatibility read. `wildcard` = the trailing space-star form (`Bash(npm run *)`), the
+        same predicate as `prefix` on a single command body, minted by core's suggestion face since
+        design/382 / #510. `subpath` = the `Read(//abs-dir/**)` directory form, which never holds a command.
+
+        🔴 FOUR MEMBERS, not "the three today's miner emits": this type describes what a consumer may RECEIVE,
+        and the server's wire validator accepts all four. A consumer type narrower than the mint point is a
+        lie — it lets a `switch` claim exhaustiveness the wire does not honour. (The retired `RuleSuggestion`
+        declared only two, which is exactly why a legal `wildcard` candidate used to be dropped as malformed.)
+      enum: [exact, prefix, wildcard, subpath]
+
+    RuleOfferUncoveredReason:
+      type: string
+      description: >
+        Why one segment of a compound command is STILL not covered after redeeming the batch (design/382
+        §3.5; the server's `UNCOVERED_SEGMENT_REASONS`, core-owned). `redirection` = a redirection is asked
+        every time, permanently. `no_rule_form` = there is no rule form that could cover this segment.
+        `cap_overflow` = deduplication plus the batch cap pushed it out.
+      enum: [redirection, no_rule_form, cap_overflow]
+
+    RuleOfferUncoveredDetail:
+      type: object
+      description: >
+        design/382 §3.5, ADDITIVE — one "why is this segment still uncovered" row. `segment` is the folded
+        segment's ORIGINAL BYTES (command family: UNTRUSTED for display, and subject to the same redaction /
+        truncation discipline as a member's `segment`).
+      additionalProperties: false
+      required: [segment, reason]
+      properties:
+        segment: { type: string, maxLength: 512 }
+        reason: { $ref: '#/components/schemas/RuleOfferUncoveredReason' }
+
+    RuleOfferBatchMember:
+      description: >
+        ONE MEMBER of a `batch` offer — the rule folded out of one segment of a compound command
+        (design/382 §2.3 B3; discriminated on `kind`, core-owned closed vocabulary).
+
+        `segment` records WHICH folded segment this member came from. Core states it explicitly as a RENDERING
+        SEAT that never participates in adjudication, and it is UNTRUSTED for display exactly like
+        `rule` / `command` / `directory`. ⚠️ Only `segment` may be TRUNCATED by the server (an honest
+        elision); `rule` / `command` / `directory` sit on the left-hand side of the redemption equality and
+        are NEVER truncated.
+
+        🔴 AN UNRECOGNISED MEMBER `kind` DROPS THE WHOLE BATCH, never the single member (core's normative
+        degradation clause): a batch missing one member renders "yes to N" as "yes to N-1", which is worse
+        than not rendering it. Any `single` offers beside it are complete and honest, so they stay.
+      oneOf:
+        - type: object
+          additionalProperties: false
+          required: [kind, rule, match, command, segment]
+          properties:
+            kind: { type: string, enum: [command] }
+            rule: { type: string, maxLength: 512 }
+            match: { $ref: '#/components/schemas/RuleOfferMatch' }
+            command: { type: string, maxLength: 512 }
+            segment: { type: string, maxLength: 512 }
+        - type: object
+          additionalProperties: false
+          required: [kind, rule, directory, segment]
+          properties:
+            kind: { type: string, enum: [directoryRead] }
+            rule: { type: string, maxLength: 512, description: 'The `Read(//abs-dir/**)` directory-read grant minted from a `cd` segment.' }
+            directory: { type: string, maxLength: 512, description: 'Lexically normalised absolute directory — a rendering seat, so the shell need not re-parse `rule`. This arm carries NO `match` / `command`.' }
+            segment: { type: string, maxLength: 512 }
+      discriminator:
+        propertyName: kind
+
+    RuleOffer:
+      description: >
+        ONE "don't ask again" OPTION on an approval card (core 5.58.0 design/375 §3.1; server >= 7.46.0 emits
+        the same shape on THREE legs — the live `tool_approval` frame, the stored `card_json`, and the durable
+        park row). It is the BREAKING replacement of `RuleSuggestion`, with no alias.
+
+        🔴 READ `kind`. ORDER IS CONTRACT: a whole-string exact `single` is index 0 when present, a `batch` is
+        always last, core's cardinality is <= 2 and the server's enforcement cap is 4.
+
+        🔴 TWO ARMS, TWO SELECTION KEYS (see PersistRuleSelection). The `single` arm is redeemed by echoing its
+        `rule` text VERBATIM — the server locates it BY TEXT, so a hand-built string is refused
+        (`rule_not_offered`) by construction. The `batch` arm has no single text to copy (it is ONE yes for
+        every member, with no per-member ticking), so it is redeemed BY INDEX, and the server additionally
+        checks an anti-drift equality before honouring it: the batch re-minted from the adjudicated command
+        must have the SAME member text set as the one the person saw, or the redemption is refused and the way
+        forward is to re-trigger the command for a fresh card.
+
+        🔴 INDEX SEMANTICS DIFFER PER LEG — the live card leg's index is a legal selection key, the durable
+        queue row's is not (that projection compacts). Both statements are on the two `ruleOffers` properties.
+      oneOf:
+        - type: object
+          additionalProperties: false
+          required: [kind, rule, match, command]
+          properties:
+            kind: { type: string, enum: [single] }
+            rule: { type: string, maxLength: 512, description: 'The canonical rule text to echo back verbatim on redemption (server MAX_RULE_TEXT_CHARS = 512).' }
+            match: { $ref: '#/components/schemas/RuleOfferMatch' }
+            command: { type: string, maxLength: 512, description: 'The command pattern inside the rule, for a shell that would rather not re-parse `rule`.' }
+        - type: object
+          additionalProperties: false
+          required: [kind, rules, uncoveredSegments]
+          properties:
+            kind: { type: string, enum: [batch] }
+            rules:
+              type: array
+              minItems: 1
+              items: { $ref: '#/components/schemas/RuleOfferBatchMember' }
+              description: 'The per-segment members (segment order, deduplicated by rule text). Core contract 1..5; the server tolerates up to 8.'
+            uncoveredSegments:
+              type: integer
+              minimum: 0
+              description: >
+                The HONEST SURPLUS at mint time: how many segments of this compound command would still not be
+                allowed by any rule after redeeming this batch, under the coverage snapshot taken then. `0`
+                means "redeem this and the whole command is covered, as of that snapshot" — a statement about
+                the snapshot, not a lasting guarantee (a concurrent rule revocation makes it stale).
+            uncoveredDetail:
+              type: array
+              items: { $ref: '#/components/schemas/RuleOfferUncoveredDetail' }
+              description: >
+                design/382 §3.5, ADDITIVE — the per-segment reason behind `uncoveredSegments`. When present the
+                row count equals `uncoveredSegments`, but THE COUNT IS THE SOURCE OF TRUTH: the server drops a
+                malformed detail seat without dropping the batch, so an absent `uncoveredDetail` is NOT an
+                assertion that nothing is uncovered.
+      discriminator:
+        propertyName: kind
+
+    PersistedRuleAnchor:
+      type: object
+      description: >
+        server >= 7.48.0 (P-39), ADDITIVE — one self-describing attribution anchor for
+        `ToolApprovalRespondAck.persistedRules`, index-aligned with it.
+
+        The disease it closes: per-entry attribution of `persistedRules` used to be inferable only from
+        POSITION, and position was not provable on the wire (the ack order came from the server's RE-MINTED
+        batch walk, matching the documented display order only by coincidence — the anti-drift check is a SET
+        equality, order is not in it).
+
+        🔴 BOTH INDEXES LIVE IN THE OFFER SPACE, so a consumer needs no mapping: `offerIndex` echoes the
+        request's `persistRule.batchOfferIndex` VERBATIM (correlation: "this ack really is for the redemption
+        I sent"), and `memberIndex` is the position inside that batch's `rules[]` on the frame. Core's
+        candidate space is deliberately kept off the wire.
+      additionalProperties: false
+      required: [offerIndex, memberIndex, rule]
+      properties:
+        offerIndex: { type: integer, minimum: 0 }
+        memberIndex: { type: integer, minimum: 0 }
+        rule: { type: string, maxLength: 512, description: 'The canonical text this member actually landed as (equal to the same-index entry of `persistedRules`).' }
+
+    PersistRuleSelection:
+      description: >
+        The body field `persistRule` of POST /v1/tool-approvals/{id}/respond — TWO MUTUALLY EXCLUSIVE ARMS,
+        matching the server's `ParsedPersistRule` one for one.
+
+        🔴 THERE IS NO `kind` ON THE WIRE: that is the server's own post-parse discriminator. The arms are told
+        apart by WHICH FIELD IS PRESENT.
+
+        🔴 MUTUAL EXCLUSION IS A LOUD 400, not "pick one silently" (server constant
+        PERSIST_RULE_BATCH_EXCLUSIVE_ERROR, verbatim): "persistRule.batchOfferIndex is mutually exclusive with
+        persistRule.rule / persistRule.edited — send exactly one arm". Two arms are two DIFFERENT
+        authorisations; guessing between them is deciding for the person.
+
+        🔴 MALFORMED IS ALSO A 400, never folded (PERSIST_RULE_BATCH_INDEX_ERROR, verbatim):
+        "persistRule.batchOfferIndex must be a non-negative integer when present" — a negative, fractional or
+        non-numeric index that got coerced points at ANOTHER offer. Likewise
+        PERSIST_RULE_EDITED_FLAG_ERROR: "persistRule.edited must be a boolean when present" — a non-boolean is
+        NEVER silently treated as false, because that would quietly fold a "I want to store free text" back
+        into the candidate arm and answer `rule_not_offered`, leaving the person to think their own rule was
+        rejected. And `rule` must be a non-empty string of at most 512 characters.
+
+        🔴 NO SCOPE IN THE BODY: a top-level `scope` and a `persistRule.scope` are both loud 400s
+        ("this endpoint does not accept a rule scope — the server mints it from where the approval happened").
+        Letting the caller name a scope is letting a consent given inside project A be written as a standing
+        allow over project B (or globally) — the most expensive widening available on this axis.
+
+        ⚠️ ON `decision: "deny"` THE WHOLE FIELD IS NOT PARSED AT ALL (tolerated, ignored, no 400 — same
+        posture as `updatedInput`): having refused the operation, consenting to it persistently is meaningless.
+        So the refusals above apply to the allow family; only the TOP-LEVEL `scope` 400 is decision-independent.
+      oneOf:
+        - type: object
+          title: candidate-or-edited-arm
+          required: [rule]
+          # 🔴 互斥必须 EXPLICIT(codex R2-F1,验真后修):两臂都是开集,所以每一臂都能把对面臂的键
+          #    当「多余键」收下 —— `oneOf` 数的是「几臂命中」,于是 `{rule, batchOfferIndex:-1}` 会因为
+          #    批臂被 `minimum:0` 判假而**恰好命中一臂**,schema 放行、server 报互斥 400。靠「另一臂恰好
+          #    判假」表达互斥是间接后果,不是约束。
+          not: { required: [batchOfferIndex] }
+          properties:
+            rule:
+              type: string
+              minLength: 1
+              maxLength: 512
+              description: >
+                With `edited` absent or false this is the CANDIDATE ARM: echo back, VERBATIM, the `rule` of the
+                chosen `kind: "single"` entry of the frame's `ruleOffers` (or, against a <= 7.45 server, of
+                `ruleSuggestions`). Do not hand-build it, re-case it or append `:*` — the server locates it by
+                text and refuses otherwise (`rule_not_offered`). With `edited: true` this is the FREE-TEXT ARM
+                and the string is whatever the person typed.
+            edited:
+              type: boolean
+              description: >
+                server >= 7.44.0 (#340), ADDITIVE — capability bit `respondFreeFormRules`, PROBE IT FIRST.
+                `true` says the text above was hand-edited on the card, so the candidate-table equality is not
+                applied; the engine judges it instead through three gates (the shared validator, a COVERAGE
+                gate requiring the edited rule to still hold the command being adjudicated, and scope
+                inherited from this card). On success the ack carries `persistedRule` = the canonical spelling
+                that really landed. An older worker drops the unknown key and judges the text AS A CANDIDATE,
+                answering `rule_not_offered` — honest, but easily misread as "I wrote it wrong".
+
+                ⚠️ Together with `updatedInput` the persistence is refused (`rule_input_edited`): the call that
+                takes effect is the edited one while the candidates came from the ORIGINAL command. The
+                decision itself still stands.
+          # 🔴 刻意**不封闭**(codex R1-F2,验真后修;main 的同一格早有同款注释,换形时别把它丢了):
+          #    server 的 `parseToolApprovalResponse` 是手写 parser,只读它认识的键,对象里多给的键**忽略**
+          #    (与 `updatedInput` 同一条宽收姿势)。写 `additionalProperties:false` 会让照 spec 生成的客户端
+          #    拒发一个 server 其实会受理的请求 —— 例如一个把整只候选对象 `{rule, match, command}` 原样转发的
+          #    存量壳,重新 codegen 之后就发不出去了。那是我们自己造的漂移,不是上游的约束。
+          #    互斥**不靠封闭表达**:`oneOf` 的语义是「恰好命中一臂」,两臂各自 `required` 不同 ⇒
+          #    `{rule, batchOfferIndex}` 同时命中两臂 ⇒ 判假。开集与互斥两件事各自成立。
+        - type: object
+          title: batch-arm
+          required: [batchOfferIndex]
+          # 同上一臂:`{batchOfferIndex:0, edited:false}` 曾因为文本臂缺 `rule` 判假而恰好命中本臂。
+          not: { anyOf: [{ required: [rule] }, { required: [edited] }] }
+          properties:
+            batchOfferIndex:
+              type: integer
+              minimum: 0
+              description: >
+                server >= 7.46.0 (design/377), ADDITIVE — capability bit `respondBatchRuleOffers`, PROBE IT
+                FIRST. The person ticked a `kind: "batch"` offer; the value is that offer's INDEX in the
+                frame's `ruleOffers`. A conjunctive batch has no single text to copy, so the index is the only
+                possible selection key.
+
+                🔴 NARROWLY OPENED TO BATCH ONLY: an index that points nowhere, or points at a `single`, yields
+                `rulePersisted:false` + `rule_not_offered` — what was never rendered can never be redeemed, and
+                the `single` arm's anti-forgery anchor is its TEXT equality, which an index may not bypass.
+                🔴 An older worker drops the unknown key and then fails the `rule` shape check with a 400
+                — honest, but it cannot tell that a batch was ticked. If the capability bit is absent, do not
+                render a redeemable batch affordance.
+          # 同上一臂:刻意不封闭(理由逐字见那一段)。
+
     RuleRefusalReason:
       type: string
       description: >
         Why a "don't ask again" did NOT get persisted (#154 车二; the server's `RuleRefusalReason`, verbatim).
         A CLOSED set so a shell can branch instead of matching prose. The two naming styles are NOT a typo:
-        the four hyphenated members are derived from the consent lane's own refusal reasons, the four
-        underscored ones are minted by the server's gates.
+        the SEVEN hyphenated members are derived from the consent lane's own refusal reasons
+        (server `CardRulePersisted`), the SIX underscored ones are minted by the server's gates.
+
+        `edit-unsupported` and `edit-rejected` (server >=7.44.0, #340) belong to the FREE-TEXT arm and ask the
+        shell for OPPOSITE things: the first means the edit affordance does not work on this card (no binding
+        anchor, or the deployment has it off) so STOP RENDERING THE INPUT BOX; the second means the engine's
+        gates refused this particular text, so "fix it and try again" — and since #345 (server >=7.51.0) the
+        independently decidable half of that judgement happens BEFORE the decision settles (a 400 with the card
+        still alive), so trying again really works. `scope-unresolved` (core 7.0.0 #490②) is the death of the
+        silent global: with neither an explicit scope nor a cwd the lane refuses loudly instead of defaulting to
+        global, which makes it a ROUTINE answer on a deployment that has not wired `ruleScopeRootFor`.
 
         🔴 A refusal NEVER flips the decision. The person's "allow this once" has already taken effect and
         reached the engine; turning the whole respond into a 4xx would make a real allow vanish. The honest
@@ -10200,16 +10541,30 @@ components:
         note on `rule_lane_unavailable` above already says never to disable the feature globally on it, and
         the same holds here. The one correct source for "does this worker serve rules at all" is
         `capabilities.permissionRules`. Keep offering "don't ask again" on the next ask; just not on this one.
+        `rule_material_absent` (server >=7.48.0, #363) — DURABLE (PARKED) LATE-DECISION LEG ONLY: THIS ROW
+        carries no material to mint a rule from. Three causes, one handling: the ask never entered the rule
+        lane (governance-forced / no owner / the engine minted no candidate / the command bytes are not
+        readable out of the args), the row predates those columns, or the card on the row will not parse.
+        🔴 ALSO SPLIT FROM `rule_lane_unavailable` ON PURPOSE, for the same reason as the previous member:
+        that word says "this deployment serves no rules at all" and a shell may stop rendering the affordance
+        on it, whereas the truth here is "the lane is fine, only THIS ROW has no material". Folding them lets
+        one late park answer condemn a healthy deployment's whole lane. Silently ignoring it is worse still
+        (no silent fail-open on the approval axis): a person who ticked "don't ask again" and saw nothing
+        happen will not tick it twice.
       enum:
         - no-candidates
         - unknown-candidate
         - confirm-refused
         - redeem-refused
+        - edit-unsupported
+        - edit-rejected
+        - scope-unresolved
         - rule_lane_unavailable
         - rule_input_edited
         - rule_not_offered
         - rule_store_error
         - rule_governance_forced
+        - rule_material_absent
 
     ApprovalRiskAxes:
       type: object
@@ -11864,6 +12219,44 @@ components:
             next ask" (`rule_input_edited`) from "there was nothing redeemable on this card"
             (`rule_lane_unavailable`). 🔴 `rule_lane_unavailable` covers four causes, two of them per-card — do
             NOT read it as "this deployment has no rule lane" (see the RuleRefusalReason schema).
+        persistedRule:
+          type: string
+          maxLength: 512
+          description: >
+            server >= 7.44.0 (#340), ADDITIVE — FREE-TEXT ARM ONLY: the CANONICAL SPELLING of the rule that
+            actually landed (core may normalise `Bash(adb *)` into `Bash(adb:*)`). Echo THIS back to the
+            person, not the bytes they typed into the box.
+
+            🔴 ABSENCE HAS THREE MEANINGS, none of them "the rule is gone": (1) this respond used the
+            CANDIDATE arm — the server's `editedArmEcho` is the single mint point for this key, so a candidate
+            respond's ack is byte-for-byte unchanged; (2) nothing landed (read `rulePersisted` / `ruleRefusal`);
+            (3) the respond carried no `persistRule` at all.
+        persistedRules:
+          type: array
+          items: { type: string, maxLength: 512 }
+          description: >
+            server >= 7.46.0 (design/377), ADDITIVE — BATCH ARM ONLY: the canonical text of EVERY member that
+            landed in this one redemption. A conjunctive batch is one yes for the whole set; if any member is
+            refused the ack is `rulePersisted:false` + `ruleRefusal:"redeem-refused"` and the members that DID
+            land are not rolled back (their dots are on record and a re-triggered card dedupes idempotently).
+
+            🔴 ORDER: from server 7.48.0 on, the DISPLAY order of the requested offer
+            (`ruleOffers[batchOfferIndex].rules`) is a PROMISE, not a coincidence; on 7.46-7.47 it inherited the
+            server's re-minted walk order instead. For per-entry attribution read `persistedRuleAnchors`
+            rather than inferring it from position.
+            🔴 Not the same thing as `persistedRule`: the singular key belongs to the single/edited arm, the
+            plural one to the batch arm, and the two never appear together.
+        persistedRuleAnchors:
+          type: array
+          items: { $ref: '#/components/schemas/PersistedRuleAnchor' }
+          description: >
+            server >= 7.48.0 (P-39), ADDITIVE and with NO capability bit — the per-entry, self-describing
+            attribution anchors for `persistedRules`, INDEX-ALIGNED with it.
+
+            Minted ONLY on the batch arm (the single/edited arm has no member coordinates to speak of), and
+            omitted WHOLESALE whenever the server cannot prove attribution — an honest absence, never a
+            fabricated index. A consumer that sees it absent knows this ack can only be read positionally, and
+            `persistedRules` itself is unchanged to the byte (older consumers ignore the unknown key).
         noteRecorded:
           type: boolean
           description: >

package/package.json

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