@sema-agent/sdk 8.6.0 → 8.8.0

package/openapi.yaml

@@ -4620,10 +4620,18 @@ paths:
       x-status: gated            # server routes/rules.ts handleRuleList;同 cc-import 的部署谓词。SDK rules.list() 消费。
       summary: List the rules that are LIVE under a principal (keyset-paged, cursor bound to the revision).
       description: >
-        List the persisted allow rules currently live under one principal (tombstones already folded).
-        Ordering is deterministic — `(scope, rule)` lexicographic — because keyset paging's whole premise is
-        that the same data comes back in the same order every time. The order is decided by the server, NOT
-        by the store (core's `list()` promises none).
+        List the persisted rules currently live under one principal (tombstones already folded) — all THREE
+        behaviors from server >= 7.67.0, not the allow bucket alone.
+        Ordering is deterministic — `(scope, rule, behavior)` lexicographic from server >= 7.67.0, `(scope, rule)`
+        before it — because keyset paging's whole premise is that the same data comes back in the same order every
+        time. The order is decided by the server, NOT by the store (core's `list()` promises none).
+
+        🔴 THE CURSOR CARRIES A FORMAT GENERATION, BUMPED TO v2 IN 7.67.0 (the sort key gained `behavior`, since a
+        same-text deny/allow pair collided under the old two-part key and the strict `>` silently dropped the
+        sibling row at a page boundary). During a rolling upgrade or rollback the two generations REFUSE each
+        other's cursors with a 400 rather than each walking its own key shape — a governance listing going wrong
+        under an all-200 conversation is far more expensive than one re-listing. The cursor stays OPAQUE and the
+        handling is unchanged: echo it back verbatim, and on a 400 drop it and re-list from the top.
 
         🔴 THE CURSOR IS BOUND TO `(rev, principal, scope)` AND A MISMATCH IS REFUSED, NOT RESET. A rule set
         is read WHOLE, so there is no tearing WITHIN a page — tearing happens BETWEEN pages, when somebody
@@ -4688,12 +4696,16 @@ paths:
       tags: [rules]
       operationId: rulesRevoke
       x-status: gated            # server routes/rules.ts handleRuleRevoke;同 cc-import 的部署谓词。SDK rules.revoke() 消费。
-      summary: Revoke a persisted rule BY CONTENT — `(rule, scope)`, with no id in the path.
+      summary: Revoke a persisted rule BY CONTENT — `(behavior, rule, scope)`, with no id in the path.
       description: >
-        Revoke one persisted allow rule identified by its CONTENT pair `(rule, scope)`. There is no `:id`
-        path segment on purpose: a rule's identity IS that pair, the server mints no row id, and the engine's
-        `removePersistedRule` primitive (which this endpoint always goes through) works in observed-remove
-        form over the add dots.
+        Revoke one persisted rule identified by its CONTENT triple `(behavior, rule, scope)` — a pair before
+        server 7.67.0. There is no `:id` path segment on purpose: a rule's identity IS that triple, the server
+        mints no row id, and the engine's `removePersistedRule` primitive (which this endpoint always goes
+        through) works in observed-remove form over the add dots.
+
+        🔴 `behavior` IS REQUIRED AND HAS NO DEFAULT (server >= 7.67.0; omitting it is a 400
+        `request.body_shape`). Defaulting it would let a revoke aimed at an `allow` delete the same-text `deny` —
+        a refusal the operator meant to keep — while answering 200.
 
         🔴 IDEMPOTENT, AND DELIBERATELY NOT A 404. Revoking twice, or revoking something that was never
         there, is `200 {status:"no-op"}` — a "did this rule ever exist?" 404 would be an existence oracle
@@ -4725,7 +4737,7 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/RuleRevokeResult' }
-        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape — body is not {rule, scope, principal?}, or `scope` is not `global`/`project:<non-empty root>`
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape — body is not {behavior, rule, scope, principal?} (server >= 7.67.0: `behavior` is REQUIRED and has no default), or `scope` is not `global`/`project:<non-empty root>`
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403': { $ref: '#/components/responses/Forbidden' }         # auth.operator_only — revoking another principal's rule without explicit OPERATOR_PRINCIPALS membership
         '429': { $ref: '#/components/responses/RateLimited' }
@@ -7169,6 +7181,39 @@ components:
         note:
           type: string
 
+    PostureKnobReading:
+      type: object
+      additionalProperties: false
+      description: >
+        server >= 7.67.0 (S-178) — ONE deployment knob's reading: its value, WHO SET IT, and one operator-facing
+        pointer. Same shape as `ReadFacePosture`, whose value key is called `face` instead of `value`; both exist,
+        neither replaces the other.
+
+        🔴 WHY NOT A BARE VALUE: a bare boolean or number cannot answer "why is THIS machine on this setting, and
+        how do I pin it back". From 7.67.0 a single-user turnkey worker (REQUIRE_PRINCIPAL unset) derives
+        `DURABLE_APPROVAL` ON and a 24h approval window when neither is set, so a default FLIP has to be visible
+        on an operator surface or nobody sees it.
+
+        `source` is the CLOSED four-word set (exhaustive switch on the server — adding a word is a compile error
+        there), in PRECEDENCE order: `env` = pinned by this machine's env var (deployment sovereignty; beats any
+        published value) · `center` = applied from the config-center (restart-to-apply) · `posture` = derived from
+        the deployment shape (single-user turnkey) · `engine-default` = nothing pinned, the built-in default is in
+        force. Only `env`/`center` count as "an operator asked for this"; a posture-derived `true` does not.
+        `note` is PROSE for a human (per-knob, and on the `posture` arm it is that knob's own fact sentence) —
+        classify on `source`, never by matching `note`.
+
+        🔴 `value` IS NARROWED AT THE REFERENCE POINT, not here: the reading is one shape over many knobs, and a
+        second copy of the record per value type is how the three keys drift apart. Each `serverGates` row pins
+        its own `value` type beside the `$ref`.
+      required: [value, source, note]
+      properties:
+        value:
+          description: 'The knob''s effective value. Typed by the referencing site (boolean / integer / …).'
+        source:
+          type: string
+          enum: [env, center, posture, engine-default]
+        note: { type: string }
+
     SkillSpec:
       type: object
       description: A per-request skill (passed as an object; core-native TaskSpec.skills shape).
@@ -9568,12 +9613,16 @@ components:
     DeniedBy:
       type: string
       description: >
-        WHO REFUSED a call — the LAYER whose verdict is the deny (core 7.6.0 `DENIED_BY_VALUES`, 8 words,
-        CLOSED). The other question a deny raises — who ASKED — is answered by `AskOrigin`; the two used to
-        share one seven-word list in which `classifier` meant both.
+        WHO REFUSED a call — the LAYER whose verdict is the deny (core `DENIED_BY_VALUES`; 8 words in 7.6.0,
+        NINE from core 7.9.0 / server >= 7.67.0, CLOSED). The other question a deny raises — who ASKED — is
+        answered by `AskOrigin`; the two used to share one seven-word list in which `classifier` meant both.
         `policy` = the deployment `ToolPolicy` denied (directly, or re-checking an approved edit), or the
         approval-edit chain hit its round cap · `hook` = a PreToolUse hook denied, threw, or never answered ·
-        `org` = an organization policy rule denied · `classifier` = the auto-mode classifier denied directly ·
+        `org` = an organization policy rule denied · `persisted_rule` = the person's OWN standing `deny` row
+        denied (the deny list of their settings, imported — reachable from core 7.9.0 #625's three-behavior
+        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` = plan mode's read-only block on a write tool · `compliance` = the compliance call-time
         lock · `write_protection` = an approved edit was rewritten onto a write-protected path no approval
         covers · `ask_resolution` = the ask's own settlement IS the refusal (detail on `GateOutcome.settlement`).
@@ -9582,7 +9631,7 @@ components:
         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, classifier, plan_mode, compliance, write_protection, ask_resolution]
+      enum: [policy, hook, org, persisted_rule, classifier, plan_mode, compliance, write_protection, ask_resolution]
 
     Settlement:
       description: >
@@ -9751,7 +9800,7 @@ components:
             #   服务对缺陷记录是整条不上帧 ⇒ 词表外的值在这条 wire 上到不了消费端。审批帧那一面不判成员,
             #   所以 `AskOrigin` 本体保持真开(见该 schema 的长注)。这张 enum 是本 spec 里该词表的**唯一**
             #   执法点;core 加词时改这一处。
-            - enum: [content_question, unresolvable, org_unavailable, org_rule, hook, ask_rule, denial_limit_fallback, shell_gate_tighten, safety_tighten, policy]
+            - enum: [content_question, unresolvable, org_unavailable, org_rule, rule_store_unavailable, hook, ask_rule, denial_limit_fallback, shell_gate_tighten, safety_tighten, policy]
           description: >
             WHO ASKED. Same-present/same-absent as `settlement` (I1). CLOSED here (and only here) — see the
             enum note above.
@@ -10397,6 +10446,23 @@ components:
         access: { type: string, enum: [read, create, edit] }
         aliases: { type: array, items: { type: string } }
         skillScopeEligible: { type: boolean, enum: [true] }
+        base:
+          type: string
+          enum: [cwd, root]
+          description: >
+            core >= 7.9.1 (#635) — which base a RELATIVE path resolves against: the live cwd or the task root.
+            Only present when declared; `base:"root"` is legal on read faces only (the engine refuses it elsewhere).
+        absent:
+          type: string
+          enum: [none, base]
+          description: >
+            core >= 7.9.1 (#635) — what the tool targets when the param is ABSENT: nothing (`none`) or the base
+            directory (`base`, read faces only — e.g. `Grep` with no path searches the cwd).
+        patternParam:
+          type: string
+          description: >
+            core >= 7.9.1 (#635) — the input key that carries a glob PATTERN (e.g. `Glob.pattern`); an absolute
+            pattern there is the effective target. Must name a top-level input property.
     McpToolRenderHints:
       type: object
       additionalProperties: false
@@ -11276,7 +11342,7 @@ components:
       #   当天,一个**合法**的审批卡就会被严格消费端拒收。`x-open-enum` 只是意图标记,不解除 enum 的执法 ——
       #   这正是本车刚从 `CheckpointGate` 拆掉的那个假开集,不在这里换个地方重犯。
       #   闭集**执法**只属于**筛过的**那一面(`GateOutcome.origin`:引擎的 `screenGateOutcome` 判成员,
-      #   出集即整条不上帧),所以那张 enum 落在**那个引用点**,恰一处。已知十词见下面的描述。
+      #   出集即整条不上帧),所以那张 enum 落在**那个引用点**,恰一处。已知十一词见下面的描述。
       description: >
         WHO raised an ask (`ToolApprovalFrame.origin`; server >= 7.57.0 / core 7.5.0, S-125③/#564) — core's
         `ASK_ORIGINS`, ENGINE-STAMPED at the gate (core's words: "engine-stamped at the gate, never a policy's
@@ -11298,6 +11364,11 @@ components:
         word could not. Both are classifier-eligible (arming auto mode is the deployment's explicit choice to
         let the classifier resolve those classes).
 
+        🔴 core 7.9.0 ADDS AN ELEVENTH WORD (server >= 7.67.0): `rule_store_unavailable` = the gate's own
+        PERSISTED-RULE lane could not be READ for this call, so its deny/ask rows are unenforceable and the gate
+        fails closed to a person. It is the personal-store sibling of `org_unavailable` (a governance source that
+        cannot be read means ASK, never a silent allow).
+
         The SAME type is the `origin` member of `GateOutcome` on `tool_end` — one vocabulary, two faces.
 
     RuleOffersAbsence:
@@ -13005,8 +13076,18 @@ components:
     ServerWiringGates:
       type: object
       description: >
-        The server's OWN assembly predicates (the half core's manifest does not cover).
-      required: [streamApproval, durableApproval, checkpointStore]
+        The server's OWN assembly predicates (the half core's manifest does not cover) — server
+        `routes/diagnostics.ts` `buildServerWiringGates`.
+
+        🔴 BREAKING (server >= 7.67.0 / S-178): the three POSTURE-FAMILY knobs are now `{value, source, note}`
+        readings instead of bare values, and two of those rows are NEW. `streamApproval` is a GATE reading (a
+        different axis: is this leg live) and `checkpointStore` is a presence bit — neither is a knob, so neither
+        changed by one byte. Migration: `serverGates.durableApproval` -> `serverGates.durableApproval.value`.
+
+        ⚠️ THIS SCHEMA DESCRIBES ONE GENERATION (same treatment as `TaskResult.terminal` in SDK 8.4.0): against a
+        worker < 7.67.0 `durableApproval` is still a bare boolean on the wire and the other two keys are absent.
+        The discriminator is the PEER'S VERSION, not the presence of these keys.
+      required: [streamApproval, durableApproval, streamAskWindowMs, sessionAutoTitle, checkpointStore]
       additionalProperties: false
       properties:
         streamApproval:
@@ -13016,7 +13097,39 @@ components:
             same five-way predicate that gates `capabilities.streamApproval` and the decision endpoint's
             501 — so the diagnostics page and the consumer-facing behavior cannot disagree.
           enum: [active, no_tool_approval, protocol_disabled, no_backend, volatile_ask_ledger, no_park_facility]
-        durableApproval: { type: boolean, description: 'DURABLE_APPROVAL is on.' }
+        durableApproval:
+          allOf:
+            - { $ref: '#/components/schemas/PostureKnobReading' }
+            - properties: { value: { type: boolean } }
+          description: >
+            `DURABLE_APPROVAL` (the durable-checkpoint gate's master switch) AND who set it. 🔴 On a single-user
+            turnkey worker (REQUIRE_PRINCIPAL unset) the ABSENT default is now ON — conjoined with a durable store
+            actually being present, so a `DB_BACKEND=memory` worker still mints nothing. A multi-tenant worker's
+            absent default is unchanged (off). Pin it back with `DURABLE_APPROVAL=false` on the machine
+            (`source: "env"` always wins).
+        streamAskWindowMs:
+          allOf:
+            - { $ref: '#/components/schemas/PostureKnobReading' }
+            # 🔴 `number`,不是 `integer`:server 的 `parseNumOrFail`(config.ts)只判 `Number.isFinite`,
+            #   于是 `STREAM_ASK_WINDOW_MS=300000.5` 是一个**能启动**的部署,而这个值原样上诊断面 ——
+            #   写 `integer` 会把一台合法 worker 的真实响应判违约。下界 0 是**真有**的拒启门(负窗拒启)。
+            - properties: { value: { type: number, minimum: 0 } }
+          description: >
+            The approval window in milliseconds AND who set it. 🔴 On a single-user turnkey worker the absent
+            default moved from 5 minutes to 24 HOURS (a person stepping away for ten minutes should not come back
+            to a run that settled itself unattended); multi-tenant is unchanged at 300000. Pin it back with
+            `STREAM_ASK_WINDOW_MS=300000`.
+            ⚠️ POSTURE ONLY FILLS AN EMPTY SEAT: where the derived 24h would collide with the existing
+            cross-knob refuse-to-start inequality (`WINDOW + ADHOC_GRACE < ORPHAN_TTL`), posture YIELDS back to the
+            engine default 300000 and reports `source: "engine-default"` rather than refusing to boot a deployment
+            that changed nothing.
+        sessionAutoTitle:
+          allOf:
+            - { $ref: '#/components/schemas/PostureKnobReading' }
+            - properties: { value: { type: boolean } }
+          description: >
+            `SESSION_AUTO_TITLE` AND who set it. Its default is the SAME on every deployment shape (true), so this
+            knob has NO posture arm — an unset one reads `source: "engine-default"` and says so in `note`.
         checkpointStore: { type: boolean, description: 'A checkpoint store is wired (= the park facility exists).' }
 
     WiringDiagnostics:
@@ -13689,12 +13802,32 @@ components:
             kind: { type: string, enum: [project] }
             root: { type: string, minLength: 1, description: 'The canonical directory this rule is scoped to. NEVER empty — an empty prefix contains EVERY cwd, which would silently promote a project rule to a global one.' }
 
+    RuleBehavior:
+      type: string
+      description: >
+        WHICH OF THE THREE a persisted rule is (core `RULE_BEHAVIORS`, closed; listed in PRECEDENCE order, so
+        when rules of more than one behavior speak for one call the earliest member decides).
+
+        🔴 A RULE'S IDENTITY IS THE TRIPLE (behavior, text, scope) — core `sameRuleIdentity`; server >= 7.67.0 /
+        core 7.9.0 #625. The same text under two behaviors is TWO DIFFERENT ROWS, which is why the revoke body
+        requires this field and deliberately gives it NO default: a delete aimed at an `allow` that got defaulted
+        onto the same-text `deny` removes a refusal the operator meant to keep, and answers 200.
+        `allow` = the standing form of one recorded human approval ("don't ask again" on a card); `deny` / `ask` =
+        the standing forms of "never run this" and "ask me every time", the same content-form rules the engine
+        reads out of a settings file's deny/ask lists. ONE grammar, ONE canonical spelling and ONE matcher family
+        serve all three — the behavior is a FIELD BESIDE the text, never part of it.
+      enum: [deny, ask, allow]
+
     RuleCandidate:
       type: object
-      description: 'One candidate rule: the canonical text plus the scope it would land in (core `RuleCandidate`).'
+      description: >
+        One candidate rule: WHICH BEHAVIOR it is, the canonical text, and the scope it would land in (core
+        `RuleCandidate`). `behavior` is new in server >= 7.67.0 / core 7.9.0 #625 — a card mints `allow`
+        candidates only (a card is one person's yes), while the settings import now carries all three lists.
       additionalProperties: false
-      required: [rule, scope]
+      required: [behavior, rule, scope]
       properties:
+        behavior: { $ref: '#/components/schemas/RuleBehavior' }
         rule: { type: string, maxLength: 512 }
         scope: { $ref: '#/components/schemas/RuleScope' }
 
@@ -13764,8 +13897,14 @@ components:
         `uncovered` is a TWO-KEY RECORD, not a list: the two layers this version does not read are named in the
         TYPE, so an empty list, a missing member or a duplicate is not expressible. A preview that reported only
         the layers it read would be claiming a completeness it does not have.
+
+        🔴 server >= 7.67.0 / core 7.9.0 #625 — THE DENY AND ASK LISTS ARE IMPORTED TOO. Until then only the allow
+        bucket was read and deny/ask entries were counted into an `uncovered.denyAskBuckets` seat that said "left
+        in place"; now every candidate carries its own `behavior` and that seat is GONE — an entry that did not
+        become a candidate is in `skipped` with its reason. A consumer rendering `uncovered.denyAskBuckets` reads
+        `candidates[].behavior` instead.
       additionalProperties: false
-      required: [candidates, skipped, layers, uncovered]
+      required: [candidates, skipped, translated, layers, uncovered]
       properties:
         candidates:
           type: array
@@ -13775,6 +13914,25 @@ components:
           type: array
           items: { $ref: '#/components/schemas/CcImportSkippedRule' }
           description: 'Entries that did not become candidates. `reason` is PROSE, not a code — see the schema.'
+        translated:
+          type: array
+          description: >
+            ALWAYS EMPTY in this version — a compatibility seat core keeps on the wire shape (core
+            `ImportPreview.translated`, verbatim). It once carried entries whose MATCH FORM was rewritten on the
+            way in (the other product's space-star suggestion form translated to this lane's colon-star). That
+            translation is retired: space-star is now a first-class match form of this lane's own grammar, so an
+            entry's match form imports as the file states it and nothing is ever pushed here. A reader rendering a
+            "rewritten spellings" column from this seat renders an empty column, correctly.
+            ⚠️ Declared here from SDK 8.8.0 on: core has always emitted the key, so a closed schema without it
+            judged every real 200 body a violation (a staleness fix, not a behavior change).
+          items:
+            type: object
+            additionalProperties: false
+            required: [from, to, scope]
+            properties:
+              from: { type: string }
+              to: { type: string }
+              scope: { $ref: '#/components/schemas/RuleScope' }
         layers:
           type: array
           items: { $ref: '#/components/schemas/CcImportLayerReport' }
@@ -13814,9 +13972,12 @@ components:
         indeterminate, release the claim and answer 503 `state.rule_import_retry` (server rules-consent.ts) —
         so this schema honestly describes the two-value `status` only.
       additionalProperties: false
-      required: [candidateIndex, rule, scope, status, alreadyRedeemed, dot]
+      required: [candidateIndex, behavior, rule, scope, status, alreadyRedeemed, dot]
       properties:
         candidateIndex: { type: integer, description: 'Index into the prepare preview''s candidate set (candidate space).' }
+        behavior:
+          allOf: [{ $ref: '#/components/schemas/RuleBehavior' }]
+          description: 'server >= 7.67.0 / core 7.9.0 #625 — which of the three the landed row is (same value as the same-index candidate in the preview; one leg of the identity triple).'
         rule: { type: string, description: 'Canonical rule text.' }
         scope: { $ref: '#/components/schemas/RuleScope' }
         status:
@@ -13898,27 +14059,71 @@ components:
     PersistedRule:
       type: object
       description: >
-        One LIVE persisted allow rule as `GET /v1/rules` puts it on the wire (server `PersistedRuleWireRow`).
+        One LIVE persisted rule as `GET /v1/rules` puts it on the wire (server `PersistedRuleWireRow`).
         Tombstones are already folded — every row here is live at `RuleListResult.rev`.
         🔴 `scope` is the DISCRIMINANT STRING (`global` / `project:<root>`), NOT the `RuleScope` object the
         import lane speaks: this is the exact byte sequence the revoke body wants back, so echo it VERBATIM
         rather than re-serializing a parsed form (an equivalent-but-differently-spelled root matches nothing).
-        The rule lane is ALLOW-only; deny/ask rules are the tightening direction and never appear here.
+
+        🔴 THREE BEHAVIORS, NOT ALLOW-ONLY (server >= 7.67.0 / core 7.9.0 #625). Until 7.66.0 this schema said
+        "the rule lane is ALLOW-only; deny/ask rules are the tightening direction and never appear here" — that
+        sentence is now false, and `behavior` is the leg of the identity triple a revoke has to echo back.
       additionalProperties: false
-      required: [rule, scope, tool, match, command, adds]
+      required: [behavior, rule, scope, tool, match, command, adds, source, status]
       properties:
+        behavior:
+          allOf: [{ $ref: '#/components/schemas/RuleBehavior' }]
+          description: 'Which of the three this row is. Part of the row''s IDENTITY — pass it back VERBATIM to revoke, or the delete aims at another behavior''s same-text row.'
         rule: { type: string, description: 'Canonical rule text — `Bash(git status)` (exact) or `Bash(git status:*)` (prefix). Pass back VERBATIM to revoke.' }
         scope: { type: string, description: 'Scope discriminant string: `global`, or `project:<root>` with a NON-EMPTY root. Pass back VERBATIM to revoke.' }
-        tool: { type: string, enum: [Bash], description: 'The one tool the v1 rule lane speaks for. The field exists so a later version can widen without a shape change — read it, do not assume it.' }
+        tool:
+          type: string
+          # 🔴 只钉非空,**不借**输入面那条 `maxLength: 190`(server 的 `LocalImportRowSchema` 帽的是**收进来的**
+          #   行;列举面出去的行不过那道尺)。借一条别的面的约束来判这一面,迟早把一条合法行判成违约。
+          minLength: 1
+          description: >
+            Which tool this row speaks for. 🔴 NOT A CLOSED SET from server >= 7.67.0 / core 7.9.0 #625 (the
+            `enum: [Bash]` written here through SDK 8.7.0 is gone): the tool set is DERIVED from the engine
+            catalogue's path-target declarations — `Bash` is the command grammar, any tool declaring a
+            `pathTarget` (`Read` / `Write` / `Edit` / `Glob` / `Grep` / `NotebookEdit`, …) is the path grammar.
+            The test is "does the engine's rule grammar speak for this name", and that roster lives in the
+            engine's catalogue, not on this wire. READ IT; do not switch over a closed list. A name the grammar
+            does not know is still a 400 on the input faces.
         match:
           type: string
-          enum: [exact, prefix]
-          description: '`exact` = this one command only; `prefix` = word-boundary prefix. (core reserves a `wildcard` form for v2 that no current version produces.)'
+          enum: [exact, prefix, wildcard, subpath, path]
+          description: >
+            The match form (core `PersistedRuleMatch`, five members). `exact` = this one command only ·
+            `prefix` = word-boundary prefix (the historical colon-star spelling, and the only spelling for a
+            compound prefix) · `wildcard` = the space-star form, the SAME predicate as `prefix` on a single
+            command body · `subpath` = the directory (read-containment) form, which never admits a command ·
+            `path` = NEW in server >= 7.67.0, the path-family pattern grammar for deny/ask/allow rules (`//abs`,
+            `~/`, root-relative, cwd-relative; `*` within a segment, `**` across segments).
+            SDK 8.7.0 and earlier declared only the first two — a consumer rendering this cell off a closed list
+            must add the other three.
         command: { type: string, description: 'What the matcher actually compares against, parsed out of `rule` at mint time and stored so no consumer re-parses. Trust this + `match`, not your own parse of `rule`.' }
         adds:
           type: array
           description: 'Every LIVE add of this rule (see RuleAdd — a real set, deliberately not folded).'
           items: { $ref: '#/components/schemas/RuleAdd' }
+        source:
+          type: string
+          enum: [user, project, session]
+          description: >
+            Which source this row came from (server >= 7.57.0 / core 7.5.0 design/389). DERIVED FROM `scope`
+            (`global`<->`user`, `project`<->`project`, `session`<->`session`) — the row never carries a second
+            source byte that could drift from its scope. With only the durable partition wired today the reachable
+            values are `user | project`.
+            ⚠️ The IMPORT faces do NOT accept this key (nor `status`): POSTing a listing row straight back to
+            local-import is a 400. Declared here from SDK 8.8.0 on — the server has emitted it since 7.57.0, so a
+            closed schema without it judged every real listing row a violation.
+        status:
+          type: string
+          enum: [live, shadowed-by-org]
+          description: >
+            The row's STANDING (server >= 7.57.0 / design/389): `live`, or `shadowed-by-org` when an org deny
+            covers its command pattern. With no org partition wired today it is always `live` — branch on BOTH
+            values now rather than optimising the constant away. Same staleness note as `source`.
 
     RuleListResult:
       type: object
@@ -13946,8 +14151,15 @@ components:
       # 封闭:server 侧 zod 是 `.strict()` —— 把 `scope` 拼成 `scopes` 的客户端应当场知道,而不是
       # 拿到一个「删掉了 global 那条」的意外结果。
       additionalProperties: false
-      required: [rule, scope]
+      required: [behavior, rule, scope]
       properties:
+        behavior:
+          allOf: [{ $ref: '#/components/schemas/RuleBehavior' }]
+          description: >
+            🔴 REQUIRED from server >= 7.67.0 (omit it and the body is a 400 `request.body_shape`) — WHICH
+            BEHAVIOR's row to revoke, VERBATIM as the listing gave it. 🔴 DELIBERATELY NO DEFAULT: a revoke aimed
+            at an `allow` that got defaulted onto the same-text `deny` deletes a refusal that was meant to stay,
+            and hands the caller a 200. core's `sameRuleIdentity` names this exact failure.
         rule: { type: string, minLength: 1, maxLength: 1024, description: 'The canonical rule text, VERBATIM as `RuleListResult.rules[].rule` gave it.' }
         scope: { type: string, minLength: 1, maxLength: 4104, description: 'The scope discriminant string — `global` or `project:<root>` with a NON-EMPTY root (an empty root would match every cwd). VERBATIM as the listing gave it. Cap = "project:".length + server MAX_CWD_CHARS (8+4096) — the 1088 previously written here was the same stale independent copy the server itself fixed (rules.ts MAX_RULE_SCOPE_CHARS 顶注), found by the A-335 anchor sweep.' }
         principal: { type: string, minLength: 1, maxLength: 190, description: 'OPERATOR-ONLY cross-tenant revoke. Absent (or your own principal) = revoke your own rule.' }

package/package.json

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