@sema-agent/sdk 17.0.0 → 17.2.0

package/openapi.yaml

@@ -5804,7 +5804,7 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/CcImportPrepareResult' }
-        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape — not {layers:[{layer,path,root,content}]}, or an empty `root` (an empty prefix would silently promote a project rule to global)
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape — not {layers:[{layer,path,root,content}]}, or a layer `root` the server does not accept (server >= 7.120.0: not a complete absolute path — see RuleScope; sentence "scope must be 'global' or 'project:<root>' with an absolute root", no ticket minted; <= 7.119.x: an empty `root`, answered with the body-shape sentence)
         '401': { $ref: '#/components/responses/Unauthorized' }
         '413': { $ref: '#/components/responses/PayloadTooLarge' }   # request.payload_too_large — more than 200 candidates across all submitted layers; SHORTEN and resend (retrying the same payload cannot help)
         '429': { $ref: '#/components/responses/RateLimited' }
@@ -5931,8 +5931,8 @@ paths:
           required: false
           schema: { type: string, minLength: 1 }
           description: >
-            Filter to one scope, spelled `global` or `project:<root>` with a NON-EMPTY root. Unreadable ⇒ 400
-            `request.query_invalid` (never silently unfiltered). Matching is done on the CANONICAL form, so an
+            Filter to one scope, spelled `global` or `project:<root>` (which roots are accepted: see RuleScope). Unreadable
+            or a root the server does not accept ⇒ 400 `request.query_invalid` (never silently unfiltered). Matching is done on the CANONICAL form, so an
             equivalent-but-differently-spelled root filters to an empty page.
         - name: limit
           in: query
@@ -6015,7 +6015,7 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/RuleWriteResult' }
-        '400': { $ref: '#/components/responses/BadRequest' }        # request.field_invalid — `behavior: "allow"` (whole-sentence refusal, NO `reason` key), or a content test refused it (closed `reason` + human `detail`: rule_rejected / scope_bidi_controls / scope_control_chars / row_inconsistent / …, the SAME table the local-import preview answers with). request.body_shape — body is not {behavior, rule, scope, principal?}, or `scope` is not `global`/`project:<non-empty root>` (same sentence as DELETE)
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.field_invalid — `behavior: "allow"` (whole-sentence refusal, NO `reason` key), or a content test refused it (closed `reason` + human `detail`: rule_rejected / scope_bidi_controls / scope_control_chars / row_inconsistent / …, the SAME table the local-import preview answers with). request.body_shape — body is not {behavior, rule, scope, principal?}, or `scope` is not `global`/`project:<root>` with a root the server accepts (see RuleScope; same sentence as DELETE)
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403': { $ref: '#/components/responses/Forbidden' }         # auth.operator_only — writing another principal's rules without explicit OPERATOR_PRINCIPALS membership
         '429': { $ref: '#/components/responses/RateLimited' }
@@ -6085,7 +6085,7 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/RuleRevokeResult' }
-        '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>`
+        '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:<root>` with a root the server accepts (see RuleScope)
         '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' }
@@ -6339,7 +6339,7 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/DeviceEnrollResult' }
-        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape (unknown key / missing required); request.field_invalid (platformOs outside the v1 closed set `darwin|linux` — a third value is never silently accepted; a field over its byte column — a silently truncated value is a DIFFERENT value)
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape (unknown key / missing required); request.field_invalid (platformOs outside the v1 closed set `darwin|linux` — a third value is never silently accepted; a field over its byte column — a silently truncated value is a DIFFERENT value; server >= 7.120.0: `workspaceRoot` not an absolute POSIX path — the token is not consumed)
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403':
           description: >
@@ -6598,6 +6598,13 @@ components:
         declared exceeds the roster bound (name 128, contract id / revision 64, `modelGate` 64); the caller cannot route
         around it and a verbatim retry never changes it (DETERMINISTIC — the SDK does not auto-retry these codes; they land
         on ServiceStateError via the 503 tail, with no wait hint); only the deployment fixing its declaration helps.
+        Server >= 7.119.0 adds `state.scenario_assignment_unknown` to this slot — the center's scenario assignment for the principal names a
+        scenario this deployment does not have; refused before any side effect or billing, zero run, body `detail: { scenario, source }`, NO
+        `Retry-After` (resending before the assignment is re-pointed — or the scenario added back to the deployment — is pointless; then retry
+        verbatim, the serving replica reads the new assignment after its own cache window, one minute by default). The caller did nothing wrong:
+        an explicit unknown `scenario` in the body is still 400 `scenario_unknown`. DETERMINISTIC for the SDK's retry arm (see
+        `ErrorResponse.errorCode`); lands on ServiceStateError. On a resume leg the same refusal folds into 409 `resume_blocked_by_policy`
+        (`blockedBy: state.scenario_assignment_unknown`).
         Which of them carry a wait hint is stated ONCE, under `headers.Retry-After` below (kept in one place so
         the two statements cannot drift apart).
       headers:
@@ -7118,7 +7125,7 @@ components:
             key on every submit of that session). ⚠️ A server < 7.104.0 answers 400 `request.body_shape` (unknown key).
         permissionMode:
           type: string
-          enum: [default, plan, acceptEdits, bypassPermissions, auto]
+          enum: [default, plan, acceptEdits, bypassPermissions, auto, dontAsk]
           description: >
             🔴 K-32 — server >= 7.106.0 (S-877 / core 7.34.0 design/1111 "one permission mode"), READ THIS FIRST; the long text
             below describes <= 7.105.0. The effective mode passes through VERBATIM to the engine (`TaskSpec.permissionMode`); the
@@ -7131,13 +7138,16 @@ components:
             `config.permission_mode_unavailable`. `bypassPermissions` RELEASES the ten releasable ask classes (server >= 7.115.0: the tenth is `unstated`, a server-tool call nobody stated)
             and DISCLOSES each (`tool_end.gate.disposition.released` + one `engine_notice` `permission.ask_released_by_mode` per (mode, class) per run);
             immune classes (deployment-authored, ask / org rules, hooks, ancestors, questions …) still ask; a write whose protection
-            cannot be judged is refused (`deniedBy: mode`). Request vocabulary: FIVE words — `dontAsk` on a fresh submit is 400
-            `request.field_invalid` (S-902). The three sentences below — "omitting both carriers means no mode-derived gate", "`auto`
+            cannot be judged is refused (`deniedBy: mode`). Request vocabulary: SIX words (server >= 7.119.0) — `dontAsk`, the engine's
+            "auto-refuse" mode, is accepted and passes through verbatim: the ENGINE refuses the calls that would ask (no card, no parked row,
+            `tool_end.gate.disposition = { kind: denied, deniedBy: mode, mode: dontAsk, … }`), the run ends normally, and it is never looser
+            than `default`. One exception: a PreToolUse hook's OWN ask, when no other class in that ask's set backs it, is still handed to a person
+            (the engine's `arbitrateByMode`: the `hook` class on a row without `hookAskFloor`). Send it only when `capabilities.permissionModes` carries it: that bit absent = server <= 7.118.x, whose request
+            vocabulary is FIVE words — `dontAsk` on a fresh submit is 400 `request.field_invalid` there. The three sentences below — "omitting both carriers means no mode-derived gate", "`auto`
             is armed by the principal's entitlement independent of the mode word", "`bypassPermissions` adds no mode-derived gate" —
             hold for <= 7.105.0 only.
-            CC-parity permission-mode INTENT — the five values THIS wire's closed submit-gate accepts (post-[816]/
-            [820]/[822]; not a claim these are CC's/sema-cli's complete mode vocabulary, which is wider, e.g.
-            `dontAsk`). The frontend (TUI shell / web portal) carries the RAW mode; the SERVICE interprets it TIGHTEN-ONLY vs the deployment baseline:
+            CC-parity permission-mode INTENT — the values THIS wire's closed submit-gate accepts (the first five on server <= 7.118.x,
+            plus `dontAsk` from 7.119.0 = the engine's whole mode vocabulary, `capabilities.permissionModes`). The frontend (TUI shell / web portal) carries the RAW mode; the SERVICE interprets it TIGHTEN-ONLY vs the deployment baseline:
             `plan` ⇒ mount present_plan (core enablePlanMode) + read-only hands (CC EnterPlanMode research);
             `default` adds the manual ask gate on non-exempt writes (scratchpad dirs / remembered session
             exemptions still auto-allow — not literally every Write/Edit); the server emits the SAME gate-policy
@@ -7148,7 +7158,7 @@ components:
             as plain `default`; `acceptEdits` adds the SAME gate narrowed to auto-allow inside the working
             directory — but only when the service has a trusted working directory to scope it to; on a sandbox
             execution lane with none wired, `acceptEdits` degrades to asking on every non-exempt write, same
-            as `default`; `bypassPermissions` adds no mode-derived gate at all. None of the five can ever subtract
+            as `default`; `bypassPermissions` adds no mode-derived gate at all. None of them can ever subtract
             from the deployment/operator policy (deny-wins). Omitting this field is NOT itself "no mode-derived
             gate" — this field wins over a `settings.permissions.defaultMode` bundle when both are sent, but when
             THIS field is omitted the bundled mode (if any) still supplies one; only when neither carrier supplies
@@ -8114,18 +8124,21 @@ components:
           enum: [mysql, pg, local, memory]
           description: >
             The ASSEMBLED backend (same word table; nothing assembled = `memory`). `declared != backend` is legal:
-            `DB_BACKEND=pg` + `SESSION_BACKEND=memory` (deliberately non-durable, no `degradedReason`) / an `auto` degrade
-            (`db_unreachable`) / a default-derived local store that could not be built (`declared: local`, `backend: memory`,
-            `local_unwritable`).
+            `DB_BACKEND=pg` + `SESSION_BACKEND=memory` (deliberately non-durable, no `degradedReason`) / a default-derived local
+            store that could not be built (`declared: local`, `backend: memory`, `local_unwritable`). Server >= 7.119.0: a configured
+            SQL store that cannot open is retried inside the wait window and then the boot is REFUSED — it never degrades to memory
+            (server <= 7.118.x degraded it silently under `SESSION_BACKEND=auto`, with the RETIRED word `degradedReason: db_unreachable`).
         durable: { type: boolean, description: '`backend !== "memory"`.' }
         degradedReason:
           type: string
           enum: [db_unreachable, local_unwritable]
           description: >
-            PRESENT-IFF the degrade arm ran; closed two words by backend family (server `STORE_DEGRADED_REASONS`):
-            `db_unreachable` = the SQL family could not open under `SESSION_BACKEND=auto` (connect or DDL, not told apart);
+            PRESENT-IFF the degrade arm ran; the server's own closed set (`STORE_DEGRADED_REASONS`) is ONE word since server >= 7.119.0:
             `local_unwritable` = the default-derived local file store could not be built (mkdir / lock / permission / read-only
-            mount / disk full). Absent = not degraded.
+            mount / disk full). ⚰️ RETIRED word `db_unreachable`: the SQL family could not open under `SESSION_BACKEND=auto` (connect or DDL, not told
+            apart) — a server <= 7.118.x (inside the support floor) still sends it; a server >= 7.119.0 NEVER does (a configured SQL store that
+            cannot open is retried, then the boot is refused — the SQL family has no degraded state). Kept in this enum so a valid response from an
+            older server still validates; it is deleted once the support floor rises past 7.118.x. Absent = not degraded.
         sql:
           allOf: [{ $ref: '#/components/schemas/SqlEngineCapability' }]
           description: >
@@ -9349,11 +9362,32 @@ components:
             server >= 7.118.0, hardcoded true (a version bit): the three approval decision doors read `decidedBy` (ApprovalDecidedBy).
             Send it only when this is present; absent = an older server (the durable doors and `plan_review` 400 it, the live
             `respond` drops it silently and answers 200).
+        sessionReadRedaction:
+          type: boolean
+          description: >-
+            server >= 7.120.0, hardcoded true (a predicate-class bit, same family as `approvalDecidedBy`): the session HISTORY read
+            (`GET /v1/sessions/:id`, the `messages` string leaves, every fetch form) passes the same redaction as the live and ledger
+            frames (see SessionRecord). Branch on the bit, not on the server version. Bit absent is NOT `false` and NOT "unredacted":
+            a server <= 7.118.x returns the archive as written; a 7.119.x server already redacts but does not report the bit. A true
+            bit does not mean the read face exists (that is `sessions`; without a session audit face that door answers 501 and this
+            bit is still true), nor that the archive holds no credential (the redaction is read-side only).
         approvalReach:
           type: boolean
           description: >-
             server >= 7.118.0, hardcoded true (same word as the request key): TaskRequest.approvalReach is understood. Absent = an
             older server — do not send the key.
+        permissionModes:
+          type: array
+          items: { type: string }
+          description: >-
+            server >= 7.119.0 — the permission-mode words this worker's REQUEST face accepts: the engine's `PERMISSION_MODES` whole set, engine order
+            (today six: `default`, `acceptEdits`, `plan`, `auto`, `bypassPermissions`, `dontAsk`). The top-level `TaskRequest.permissionMode`,
+            `settings.permissions.defaultMode` and `GET /v1/capabilities?permissionMode=` read ONE closed set: every word in the bit is accepted by
+            all three, a word outside it is 400 `request.field_invalid` whose sentence lists the same words. Send `dontAsk` only when this bit
+            carries it; ABSENT = server <= 7.118.x (five words, `dontAsk` is a 400). OPEN set: the bit forwards the engine's vocabulary
+            verbatim, so a future engine word shows up here before this document knows it — decide by the bit, do not filter it through the
+            `PermissionMode` schema. It says "this server accepts the word", not "the word takes effect on this submit" (`auto` still needs a
+            classifier seat and an entitlement — see `permissionModeAuto`).
         respondFreeFormRules:
           type: boolean
           description: >
@@ -9618,8 +9652,9 @@ components:
             the same false, and a shell must do different things for those. `reason` is present ONLY when
             `armed` is false; read its vocabulary as an OPEN set (server already grew it from four words to
             six). `model` is omitted when the classifier route cannot be resolved (the server logs the
-            engine's refusal rather than 500-ing the read face). `?permissionMode=<five words>` folds the
-            caller's INTENT into the verdict; anything outside the five words is a 400
+            engine's refusal rather than 500-ing the read face). `?permissionMode=<mode word>` folds the
+            caller's INTENT into the verdict (server >= 7.119.0 takes the six words of `capabilities.permissionModes` — `dontAsk` answers
+            `armed: false` / `reason: mode_not_auto`; server <= 7.118.x takes five); anything outside the server's words is a 400
             `request.field_invalid`.
           # 🔴 required 只有**三位**:武装两键(armed / reason)是 server >= 7.57.0 (S-80)
           # 才有的,而本包的支持地板是 3.0.0 => every 7.x <= 7.56.0 server is inside the promised face and
@@ -12756,6 +12791,12 @@ components:
       description: >
         Session audit (`GET /v1/sessions/:id`) — true shape. `messages` = current model context
         (older history folded into a summary message); can be large.
+        Server >= 7.119.0 (wire VALUE change, shape unchanged): string leaves inside `messages` (assistant text / reasoning, tool arguments,
+        tool results, shell output, compaction summaries) pass the SAME redaction as the live and ledger frames — a credential-shaped span reads
+        `«redacted:…»`. Key set, count and segment order are verbatim; a history with no credential-shaped span is byte-identical; the archive itself is
+        untouched (the redaction is read-side only), and `?blobCap=` truncation runs AFTER redaction. A caller that rebuilds a model context from this
+        read gets the placeholder, not the original string. Server >= 7.120.0 reports this with the capability bit `sessionReadRedaction`
+        (a 7.119.x server redacts but does not report it).
       # 🔴 **暂不封闭**(census 轴一裁定,2026-07-30):本体是 core `StoredSession.buildContext()` 的投影
       # (server `audit.ts` auditFromStorage),再叠 server 自己的两条 additive 后处理(windowMessages /
       # truncateMessageBlobs)与路由层追加的 owner —— 键集由「core 投影 × 查询参数」共同决定,不是一个
@@ -13574,8 +13615,10 @@ components:
             7.104.0 / S-271 — a deployment-declared tool exceeds the roster bound), `config.tool_schema_bound` (503, server >=
             7.106.0 / core 7.35.0 #765 — a tool's `parameters` schema exceeds the roster row's key bound; "same family, same tier";
             <= 7.105.0 answered the synchronous leg 200 + a failed body), `corrupt` (500 — the session rule store
-            cannot read its own bytes) and `internal.memory_control_plane_corrupt` (500 — the memory control plane refuses
-            fail-closed). Every other 5xx code keeps the status-based retry.
+            cannot read its own bytes), `internal.memory_control_plane_corrupt` (500 — the memory control plane refuses
+            fail-closed) and `state.scenario_assignment_unknown` (503, server >= 7.119.0 — the center's scenario assignment for the
+            principal is dangling; only re-pointing the assignment, or adding the scenario back to the deployment, helps). Every other 5xx
+            code keeps the status-based retry.
             🔴 `request.host_posture_refused` (422) has TWO triggers (same code, same status — "you wrote it right, this
             deployment will not grant that host posture"): (1) the write-containment face (`permissionMode: bypassPermissions` ⇒
             `writeFace: open`; read `capabilities.taskWriteFaceOpen` first); (2) server >= 7.106.0 / S-895: `inheritEnv: "all"` on a
@@ -13657,10 +13700,19 @@ components:
             row's configuration was refused — `taskConfig` (change the configuration, then decide the SAME card again) or
             `inheritedGate` (the row's recorded mode seed is bad — the run can only be cancelled). Also on 400 `request.field_invalid` for a
             `settings.hooks` tool-event matcher that selects an engine alias but not its canonical name (server >= 7.115.0 / S-1025):
-            `field` is always the literal `settings.hooks` (see `detail`). SDK: `err.extra.field`.
+            `field` is always the literal `settings.hooks` (see `detail`). Also on 400 `request.body_shape` (server >= 7.119.0), on the THREE
+            tool-approval decision doors (`POST /v1/tool-approvals/{id}/respond`, `POST /v1/tasks/{taskId}/asks/{askId}/decision`,
+            `POST /v1/approvals/{sessionId}/decide`) and ONLY there: the body carried the retired key `settledBy` (any value but `undefined` —
+            `null` and `""` count), the refusal landed before any decision, and `field` is the literal `settledBy`; the three doors now answer
+            the SAME sentence. Every such 400 carries it, even when another defect in the same body was hit first (the sentence then names that
+            defect). Branch on the code plus `field`, never on the sentence; a bad body WITHOUT that key carries no `field`. SDK: `err.extra.field`.
         detail:
           description: >
-            🔴 TWO SHAPES under one code — branch on `field` (or the `errorCode`), never guess from the type of `detail`. On 400
+            🔴 SHAPES differ by code — branch on `field` (or the `errorCode`), never guess from the type of `detail`. On 503
+            `state.scenario_assignment_unknown` (server >= 7.119.0): an OBJECT `{ scenario, source }` — `scenario` = the dangling scenario name,
+            `source` ∈ `ruling` (the center's assignment for this principal names a scenario this deployment does not have) / `deployment`
+            (the deployment default `DEFAULT_SCENARIO` is dangling — the server refuses to BOOT on that, so a request reaches it only on an
+            embedder that assembles `resolveSpec` itself). On 400
             `request.field_invalid` for a `settings.hooks` tool-event matcher (server >= 7.115.0 / S-1025; additive, the sentence and the code
             are unchanged): an OBJECT `{ event, alias, canonical }` — `event` = the tool event of the refused group (the first refused one when
             several are), `alias` / `canonical` = the engine catalog's alias and canonical name (closed strings, never the caller's raw bytes),
@@ -13675,6 +13727,12 @@ components:
                 event: { type: string }
                 alias: { type: string }
                 canonical: { type: string }
+            - type: object
+              required: [scenario, source]
+              additionalProperties: false
+              properties:
+                scenario: { type: string }
+                source: { type: string, enum: [ruling, deployment] }
             - type: string
         count:
           type: integer
@@ -14266,16 +14324,24 @@ components:
       enum: [default, acceptEdits, plan, auto, bypassPermissions, dontAsk]
       description: >
         core 7.34.0 `PERMISSION_MODES` (six words). CLOSED on the gate record (the server screens it with core `isPermissionMode`;
-        an out-of-set word withholds the whole `gate`). ⚠️ The REQUEST face (`TaskRequest.permissionMode`) takes FIVE on server
-        7.106.0 — `dontAsk` on a fresh submit is 400 `request.field_invalid` (S-902) — yet `dontAsk` can still appear here (e.g. an
-        unattended leg run under `UNATTENDED_PERMISSION_MODE=dontAsk`).
+        an out-of-set word withholds the whole `gate`). The REQUEST face (`TaskRequest.permissionMode`) takes the same six words from
+        server 7.119.0 (`capabilities.permissionModes`); on server <= 7.118.x it takes FIVE — `dontAsk` on a fresh submit is 400
+        `request.field_invalid` there — yet `dontAsk` can still appear here on those versions (e.g. an unattended leg run under
+        `UNATTENDED_PERMISSION_MODE=dontAsk`).
     AskClass:
       type: string
-      enum: [content_question, hook, ancestor, unverifiable_delete, transcript_write, org_rule, governance_unavailable, rule_unreadable, ask_rule, denial_limit_fallback, classifier_no_ruling, requires_user_interaction, operator_forced, shell_floor, write_protection_unresolved, probe, write_protection, tool_marks_mcp, tool_marks_a2a, policy_rra, artifact_shared_read, mode, unstated, ordinary]
+      enum: [content_question, hook, ancestor, dangerous_delete, unverifiable_delete, transcript_write, org_rule, governance_unavailable, rule_unreadable, ask_rule, denial_limit_fallback, classifier_no_ruling, requires_user_interaction, operator_forced, shell_floor, write_protection_unresolved, probe, write_protection, tool_marks_mcp, tool_marks_a2a, policy_rra, artifact_shared_read, mode, unstated, ordinary]
       description: >
-        core `ASK_CLASSES` (twenty-two words as of core 7.40.0, twenty-three as of core 7.41.0, twenty-four as of core 7.43.0 — 7.34.0 minted twenty; `shell_floor` joined in 7.39.0 #1260 and rides
+        core `ASK_CLASSES` (twenty-two words as of core 7.40.0, twenty-three as of core 7.41.0, twenty-four as of core 7.43.0, twenty-five as of core 7.45.0 — 7.34.0 minted twenty; `shell_floor` joined in 7.39.0 #1260 and rides
         server >= 7.113.0; `unstated` joined in 7.40.0 and rides server >= 7.115.0; `requires_user_interaction` joined in 7.41.0 and rides
-        server >= 7.116.0; `classifier_no_ruling` joined in 7.43.0 #1353 and rides server >= 7.118.0) — which CLASS an ask falls in (the columns of the mode × class arbitration table).
+        server >= 7.116.0; `classifier_no_ruling` joined in 7.43.0 #1353 and rides server >= 7.118.0; `dangerous_delete` joined in 7.45.0 and rides
+        server >= 7.119.0) — which CLASS an ask falls in (the columns of the mode × class arbitration table).
+        `dangerous_delete` = a DELETE OF A PROTECTED PLACE: an `rm` / `rmdir` whose target is the filesystem root, a top-level directory, the home
+        directory, the task root / working directory / an added working directory or an ancestor of one (including `rm -rf *` at the task root and
+        `rm -rf ~/*`), or a shell handed a script that is only assembled at run time (`bash -c "$CMD"`, `eval "$(…)"`). ONLY A PERSON'S ANSWER clears
+        it: no mode (`bypassPermissions` included), no allow (request `settings.permissions.allow`, operator `APPROVAL_GRANT`, a stored allow row, a
+        skill's tool list, a hook's allow) and no `auto` classifier does; the frame carries `requiresRealApproval: true`, nobody answering means the
+        call does not run (the unattended leg refuses), and it is bypass-IMMUNE (not one of the ten releasable classes).
         `classifier_no_ruling` = the auto-mode classifier did not rule (it could not run — `error` / `timeout` — or replied with no verdict —
         `parse_error`), so a person decides: the denial-limit fallback's row (bypass-immune, no allow rule clears it, the classifier is not asked
         again); the live frame and the inbox row also carry the cause as `classifierNoRuling`.
@@ -19531,6 +19597,20 @@ components:
       description: >
         Where a persisted rule applies (core `RuleScope`). `project.root` is the directory prefix that decides
         which cwds the rule is live under.
+
+        🔴 WHICH ROOTS ARE ACCEPTED — the one statement every other mention in this file points to (the cc-import
+        layer `root`, and the `project:<root>` discriminant string on write / revoke / the list filter):
+        server >= 7.120.0 accepts only a COMPLETE ABSOLUTE PATH — POSIX `/…`, a Windows drive root `X:\…` / `X:/…`,
+        or a UNC root `\\host\…` (the engine's durable-scope predicate; every server entry calls it rather than
+        keeping a copy). A relative root (`proj`, `./x`, `~/x`) or a drive without a root (`C:`, `C:x`) is a 400 whose
+        `error` is exactly "scope must be 'global' or 'project:<root>' with an absolute root" — code
+        `request.body_shape` on write / revoke / cc-import prepare, `request.query_invalid` on the list filter.
+        Server <= 7.119.x checks only that the root is non-empty and keeps relative roots as written; such rows take
+        no part in any check on 7.120.0 — SQL backends delete them with a one-time migration at boot, while on the
+        file (`local`) backend they stay in the store, are absent from the listing, cannot be revoked, and each run
+        gets an `engine_notice` `permission.rule_row_dropped` naming them. Rewrite them with the project's full path.
+        An EMPTY root is refused on every version (an empty prefix contains every cwd). The root's truthfulness is
+        never validated — only its spelling.
       oneOf:
         - type: object
           additionalProperties: false
@@ -19542,7 +19622,7 @@ components:
           required: [kind, root]
           properties:
             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.' }
+            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. Server >= 7.120.0: a complete absolute path (see the RuleScope description).' }
 
     RuleBehavior:
       type: string
@@ -19618,9 +19698,12 @@ components:
         cloud deployment has no access to the user's filesystem — that is the deployment shape, not a bypass:
         what is read is still only the allow bucket.
 
-        🔴 `root` MUST be non-empty (an empty prefix contains every cwd — see RuleScope). Its TRUTHFULNESS is
-        deliberately NOT validated: the server has no such tree to check against, and pretending to validate
-        would be a lie. It is the user's own label for "which cwds should this rule be live under".
+        🔴 `root` follows the RuleScope rule (server >= 7.120.0: a complete absolute path; otherwise 400
+        `request.body_shape` with "scope must be 'global' or 'project:<root>' with an absolute root" and no ticket
+        minted). It applies to ALL layers alike — a `userSettings` layer's root never becomes a scope, but it is the
+        same field under the same check. On <= 7.119.x only an empty root is refused (with the body-shape sentence).
+        Its TRUTHFULNESS is deliberately NOT validated: the server has no such tree to check against, and pretending
+        to validate would be a lie. It is the user's own label for "which cwds should this rule be live under".
       # 封闭:server 侧 zod 是 `.strict()`(把 `content` 拼成 `contents` 的客户端应当场 400,而不是拿到
       # 一份「零候选」的预览去纳闷)。
       additionalProperties: false
@@ -19817,7 +19900,7 @@ components:
           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.' }
+        scope: { type: string, description: 'Scope discriminant string: `global`, or `project:<root>` (which roots: see RuleScope — on server >= 7.120.0 every listed project row has a complete absolute root; an older server may list relative ones). Pass back VERBATIM to revoke.' }
         tool:
           type: string
           # 🔴 只钉非空,**不借**输入面那条 `maxLength: 190`(server 的 `LocalImportRowSchema` 帽的是**收进来的**
@@ -19918,7 +20001,7 @@ components:
           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). Unreadable ⇒ 400 `request.body_shape`, never guessed into `global`. Cap = "project:".length + server MAX_CWD_CHARS (8+4096), same source as RuleRevokeRequest.'
+          description: 'The scope discriminant string — `global` or `project:<root>` (which roots are accepted: see RuleScope; an empty root would match every cwd). Unreadable, or a root the server does not accept ⇒ 400 `request.body_shape`, never guessed into `global`. Cap = "project:".length + server MAX_CWD_CHARS (8+4096), same source as RuleRevokeRequest.'
         principal: { type: string, minLength: 1, maxLength: 190, description: 'OPERATOR-ONLY cross-tenant write. Absent (or your own principal) = write your own rule. Gated exactly like the revoke half.' }
 
     RuleWriteResult:
@@ -20082,7 +20165,7 @@ components:
             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.' }
+        scope: { type: string, minLength: 1, maxLength: 4104, description: 'The scope discriminant string — `global` or `project:<root>` (which roots are accepted: see RuleScope; an empty root would match every cwd; a root the server does not accept ⇒ 400 `request.body_shape`). 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.' }
 
     RemovalLiveness:
@@ -20427,7 +20510,7 @@ components:
           description: 'The v1 CLOSED SET. A third value (e.g. `win32`) ⇒ 400 request.field_invalid — never silently accepted.'
         platformArch: { type: string, maxLength: 32, description: 'At most 32 **UTF-8 bytes** (producer gates byte length; `maxLength` is the looser character bound, see the unit convention).' }
         displayName: { type: string, maxLength: 255, description: 'Echoed back by `GET /v1/devices` as `name`, and HONESTLY ABSENT there when empty. At most 255 **UTF-8 bytes** (producer gates byte length; `maxLength` is the looser character bound).' }
-        workspaceRoot: { type: string, minLength: 1, maxLength: 1024, description: 'The device-side root every instruction resolves against. Required and non-empty. At most 1024 **UTF-8 bytes** (producer gates byte length; `maxLength` is the looser character bound) ⇒ over it 400 request.field_invalid (a silently truncated value is a DIFFERENT value).' }
+        workspaceRoot: { type: string, minLength: 1, maxLength: 1024, description: 'The device-side root every instruction resolves against (and the `cwd` of `exec` / `execStream` when neither the session nor its delegation parents registered a working directory). Server >= 7.120.0: an ABSOLUTE POSIX path — empty, relative (`work`, `./w`) or `~/…` ⇒ 400 request.field_invalid, `error` starting "workspaceRoot must be an absolute POSIX path", the token NOT consumed (resolve the root on the device first). Server <= 7.119.x: only non-empty is checked, and a device registered with a relative root has its sessions refused when 7.120.0 builds their execution environment — re-enroll with an absolute root (new `deviceId`; revoke the old one). At most 1024 **UTF-8 bytes** (producer gates byte length; `maxLength` is the looser character bound) ⇒ over it 400 request.field_invalid (a silently truncated value is a DIFFERENT value).' }
 
     DeviceEnrollResult:
       type: object

package/package.json

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