@sema-agent/sdk 9.4.0 → 9.6.0

package/openapi.yaml

@@ -83,6 +83,25 @@ info:
       • New contract fields are OPTIONAL with no default (CORE-PRINCIPLES §6).
       • Async results are delivered by POLL (`GET /v1/runs/:id`) or SSE (`/v1/runs/:id/events`).
         There is NO generic webhook/callback and NO signing (SERVICE-CORE-CONTEXT §2.4).
+      • 🔴 STRING-LENGTH UNIT (applies to EVERY `maxLength`/`minLength` in this file). The producer's own
+        gates are JavaScript `.length`, i.e. **UTF-16 code units**; JSON Schema counts **code points**.
+        The two agree across the entire BMP and differ only on supplementary characters (emoji, rare CJK,
+        musical symbols), each of which costs 2 units but 1 code point. => near a bound, a value made of
+        supplementary characters can pass this schema and still be refused by the producer. THAT DIRECTION
+        IS DELIBERATE: a schema looser than the producer yields a loud, readable 4xx naming the field, while
+        a schema tighter than the producer makes a client refuse a request the producer would have accepted —
+        an invisible false refusal whose symptom is indistinguishable from a server rejection (this contract
+        shipped exactly that defect on `SkillSpec.content` for several releases). Halving every bound to be
+        safe for all-supplementary input would refuse roughly half of the legal range on ordinary text, so the
+        bounds here state the producer's number verbatim and this convention states the unit. A client that
+        must pre-check exactly counts UTF-16 units itself.
+        (`maxLength` is the only keyword involved: it counts code points and that is not configurable. A
+        `pattern` could count code units — but only on validators whose regex engine is UTF-16-based and
+        non-unicode-mode, which is implementation-specific rather than contract-portable, and it would cost a
+        full regex scan of a megabyte-scale payload. The unit is therefore stated, not encoded.)
+      • The same unit applies to every BYTE-sounding phrase in this file unless it says UTF-8 explicitly: the
+        producer's guards are character/unit counts, so a non-ASCII value is NOT twice as expensive against
+        them. Do not pre-check these bounds with a byte length.
   x-sources:
     - ../docs/SERVICE-CORE-CONTEXT.md   # §2 wire answers, §4 verb surface (authoritative producer input)
     - ../docs/CORE-PRINCIPLES.md        # §2 secret discipline, §3 principal-first, §5 contract-as-anchor, §6 optional-no-default
@@ -2670,15 +2689,19 @@ paths:
             — the workflow run's record carries no readable `parks[]` list (the ENGINE's own park-ownership
             ledger, and the single source this lane joins the caller's checkpoint against). A record written by
             an engine older than 7.17.0 does not carry the key at all, or one entry is damaged and the whole list
-            cannot be read; a RESUME of that run is refused by the engine for the identical reason
-            (`workflow.park_truth_unreadable` / `parks_unreadable`, or `workflow.park_binding_broken`), so the
+            cannot be read; the redemption keys this lane would need are therefore not on the record, so the
             decision is STRUCTURALLY UNDELIVERABLE and this lane refuses loudly rather than answer a 200 nothing
             could redeem. Body carries `runId` (the WORKFLOW run) and NO `taskId` (same two-field shape as the
             SEVENTH group). SDK → `DecideWorkflowParksUnreadableError` (a `DecideError` subclass, NOT a
             `DecideWorkflowHostError` — see its class doc for why). 🔴 RECOVERY IS THE OPPOSITE of the SEVENTH
-            group: there is no retry, no waiting for the host to park again, and no resuming this run at all —
-            it cannot be resumed by this engine. The card stays PENDING (nothing is forged); the only recovery
-            action is to START A NEW RUN. ⚰️ This code REPLACES the 7.71.0 code `decide.workflow_park_identity_lost`
+            group: not a retry of this decide and not waiting for the host to park again — RESUME THE RUN
+            (`runId`). Whether that resume is ADMITTED is the engine's answer, not this lane's: admission weighs
+            the record, the journal and the record's own parked agent rows together and proves each candidate, so
+            a caller must neither pre-filter recovery candidates on this code nor promise the user it will work.
+            🔴 CORRECTED at server 7.78.0 / core 7.18.0: this text used to say the engine refuses to resume such a
+            record and the only recovery was to start a NEW run — core 7.18.0 falsified that, and the old advice
+            abandoned recoverable runs. Once admission completes the engine writes `parks` onto the record, and
+            the next decide takes the ordinary arm. The card stays PENDING throughout (nothing is forged). ⚰️ This code REPLACES the 7.71.0 code `decide.workflow_park_identity_lost`
             (retired at this same 7.75.0 — a store size-degrade step stopped keeping a SECOND copy of a parked
             row's recovery identity once `parks[]` became the engine's single source, so the state that old code
             named is now structurally unreachable). That retired code was NEVER modeled by this SDK (it went
@@ -5414,11 +5437,16 @@ components:
             Server cap 16384 chars → 400.
         skills:
           type: array
-          maxItems: 10
           description: >
             Per-request user skills (LIVE, service 170c384) — progressive disclosure, same
             mechanism as scenario skills. Merge: scenario WINS on name collision (user's dropped, warn-logged).
-            Caps server-enforced; violations 400 with the offending rule named.
+            🔴 server >= 7.78.1 (hard BREAKING, no alias): the ITEM-COUNT cap (was 10), the `description` 1024-char
+            cap and the `name` 64-char cap are GONE — and so are their three refusal messages, so a consumer branch
+            anchored on them can be deleted (a refusal turned into an acceptance: no harm in the other direction).
+            The only size gate left on this face is `SkillSpec.content` <= 1 MiB (the engine's own load gate);
+            bulk is otherwise bounded by the NON-skill-specific 8 MiB request-body cap. Per-turn cost belongs to the
+            LISTING RENDERER, not to this gate: turn it down with `settings.skillListingBudgetFraction` /
+            `settings.skillListingMaxDescChars`.
           items: { $ref: '#/components/schemas/SkillSpec' }
         reasoningEffort:
           type: string
@@ -5686,7 +5714,24 @@ components:
             service ACTIVELY interprets this bundle (task-settings.ts: permissions + permissions.defaultMode +
             model + outputStyle + env shipped in the 1.26.0 v1 scope; hooks was deferred at that point and wired
             in a later batch — both are live and interpreted today, not a raw uninterpreted passthrough);
-            `permissions.defaultMode`'s specific fold is documented on `TaskRequest.permissionMode`. OPEN object.
+            `permissions.defaultMode`'s specific fold is documented on `TaskRequest.permissionMode`.
+            🔴 ON THIS SUBMIT FACE THE KEY SET IS CLOSED (server >= 7.57.0 for the sub-tree): accepted top-level keys
+            are `env` / `hooks` / `model` / `outputStyle` / `permissions` / `skillListingBudgetFraction` /
+            `skillListingMaxDescChars` / `ultracode` / `webSearch`, and accepted `permissions.*` keys are
+            `allow` / `ask` / `defaultMode` / `deny` / `disableAutoMode`; anything else is 400 `request.body_shape`
+            with the names in the refusal's `unknownKeys` / `unsupportedKeys` arrays (REFUSED, not dropped — a dropped
+            key reads as "in effect" to the caller). The object stays OPEN here because the same `SemaSettings`
+            schema also serves the local `settings.json` wiring, where deferred CC keys are legal.
+            🔴 `skillListingBudgetFraction` (number in (0,1]) / `skillListingMaxDescChars` (positive integer),
+            server >= 7.78.1: the SKILL-LISTING RENDER BUDGET, passed to the engine with ZERO processing
+            (no clamping, no conversion, no folding) — ABSENT means the key is not written at all (the server does
+            NOT restate the engine defaults, CC-identical `0.01` / `1536`), and an out-of-domain value is
+            400 `request.field_invalid` on the fresh leg (the resume replay leg drops it instead of 4xx).
+            ⚠️ `skillListingBudgetFraction` is a ONE-WAY knob — turning it DOWN works, turning it UP does not:
+            the engine's listing budget is `min(window x fraction, 8000 bytes)` and 8000 is a STRUCTURAL ceiling of
+            the delivery lane, so raising it only helps a model whose declared window is below 200 000 tokens.
+            The engine's own twin code `config.skill_listing_budget_invalid` (400) is NOT reachable through this
+            submit leg today — it belongs to callers that build a `TaskSpec` directly.
           additionalProperties: true
         cwd: { type: string, description: Working directory for the execution env. }
         selfOrchestration: { type: boolean, description: Permit S8 self-orchestration (run_workflow) inside this task. }
@@ -7409,12 +7454,19 @@ components:
 
     SkillSpec:
       type: object
-      description: A per-request skill (passed as an object; core-native TaskSpec.skills shape).
+      description: >-
+        A per-request skill (passed as an object; core-native TaskSpec.skills shape).
+        🔴 server >= 7.78.1: `name` / `description` carry NO length cap any more (the engine's listing renderer
+        trims descriptions and falls back to name-only within its own byte budget — it never REFUSES a skill for
+        being long). `content` keeps the one real gate: 1 MiB, the twin of the engine's load gate (over it the
+        engine refuses the skill outright at load time, so the HTTP face answers first where the caller can read it).
+        The bound is 1 048 576 **UTF-16 code units** (`MAX_SKILL_CONTENT_CHARS`); see the STRING-LENGTH UNIT
+        convention in `info.description` for why this `maxLength` states that number verbatim.
       required: [name, description, content]
       properties:
-        name: { type: string, maxLength: 64 }
-        description: { type: string, maxLength: 1024 }
-        content: { type: string, maxLength: 32768 }
+        name: { type: string, minLength: 1 }
+        description: { type: string }
+        content: { type: string, minLength: 1, maxLength: 1048576 }
 
     McpServerSpec:
       type: object
@@ -8151,6 +8203,80 @@ components:
           type: array
           description: 'The nested ctx.workflow group tree (roots only — children nest recursively). Empty when the script used no nesting.'
           items: { $ref: '#/components/schemas/WorkflowGroupNode' }
+        parks:
+          type: array
+          description: >
+            core 7.17.0 (#652) / server >= 7.74.0 — the engine's own PARK RESPONSIBILITY table for this run
+            (detail face only; the list row has no such key).
+            🔴 `undefined` AND `[]` ARE TWO DIFFERENT THINGS: the WHOLE KEY ABSENT means an OLDER ENGINE wrote
+            this record (or the store's projection stripped it), so THIS FIELD ALONE cannot prove whether parks
+            exist; `parks: []` is a POSITIVE FACT — "this run has no park". Never fold one into the other; the
+            reading is `"parks" in run`.
+            🔴 THIS KEY DECIDES NOTHING ABOUT WHETHER THE RUN CAN BE RESUMED — in EITHER direction. Resume
+            admission is the ENGINE's: it weighs the record's `parks` (when present), the journal's `parked`
+            entries and the record's own `status:"parked"` agent rows together, proves each candidate against the
+            checkpoint store, and has refusal arms this read face cannot see. A consumer must not drop a run from
+            its recovery candidates because this key is absent (that abandons recoverable runs), and must not
+            promise recovery because it is present.
+            ⚠️ This description deliberately does NOT restate the admission algorithm: a mirror of someone else's
+            rule goes stale (this very text asserted "absent => the engine refuses to resume, start a new run"
+            between server 7.75.0 and 7.78.0, which core 7.18.0 falsified). The ONE bit that IS decisive on this
+            face is `resumeAdmissionIncomplete`.
+            ⚠️ The `/decide` lane does still refuse such a record (the keys it must join against are derived in
+            the admission pass and cannot be read off the record); its recovery verb is RESUME THIS RUN, not
+            "start a new one". Two lanes, two predicates — never infer one from the other.
+            🔴 KEYS ONLY — not a pending count and not a status (core's words): entries are replaced by
+            `callKey` and are NEVER removed when a decision lands, so a listed token may already be resolved /
+            expired / reaped. Never read `parks.length` as "how many approvals are waiting" (that is
+            `GET /v1/approvals`).
+            🔴 The redemption TOKEN is deliberately NOT projected: one GET would silently promote read access
+            to decide access. `/decide` takes the token from the checkpoint row itself.
+          items: { $ref: '#/components/schemas/WorkflowRunPark' }
+        resumeAdmissionIncomplete:
+          type: boolean
+          enum: [true]
+          description: >
+            core 7.18.0 (#755) / server >= 7.78.0 — this RESUME record's admission did not complete.
+            🔴 NEVER-FALSE: core DELETES the key the moment admission completes and never writes `false`, so the
+            only reading is presence. ABSENT = admission completed, OR this is not a resume at all (the normal
+            case) — absence asserts nothing.
+            🔴 PRESENT => IT IS NOT A RESUME BASE: the engine refuses it whole (`admission_incomplete`) and
+            derives no candidate from it. A face rendering resume candidates MUST carry this bit — dropping it
+            turns a REFUSED record back into an admissible one (core's words; the projection obligation is
+            word-for-word the same rank as `parks`). It does NOT fold into the absence of `parks`, which has
+            its own two meanings (above).
+
+    WorkflowRunPark:
+      # sdk 9.5.0:具名行形(同 `WiringManifestMcpEntry` 的裁定),并且**封闭** —— 服务端逐键挑出这四位,
+      # 多出来的键意味着有人在别处手拼了第二份形(凭据位就是这样漏出去的)。
+      type: object
+      additionalProperties: false
+      description: >
+        One row of `WorkflowRun.parks` — the engine's park responsibility table, EXACTLY four keys because the
+        server picks them key by key rather than spreading core's row.
+        🔴 THE REDEMPTION TOKEN IS STRUCTURALLY ABSENT from this shape: core's row carries one (its own note
+        says never log / never URL), and the read face leaves it in the store. So "I can read the park row"
+        never means "I can decide it".
+      required: [callKey, sessionId, originRunId]
+      properties:
+        callKey: { type: string, description: "Which call this park belongs to — joins `agents[].callKey`." }
+        sessionId: { type: string, description: 'The parked CHILD session the host routes by.' }
+        originRunId:
+          type: string
+          description: >
+            Which run this park was MADE on. On an inherited entry it is NOT this run's id; and while
+            `originUnconfirmed` is present it says which run the material BELONGS TO, not where it was seen.
+        originUnconfirmed:
+          type: boolean
+          enum: [true]
+          description: >
+            core 7.18.0 (#757) / server >= 7.78.0 — NO journal has yet read or written a `parked` entry for this
+            token.
+            🔴 It PAIRS with `originRunId`: while present, that coordinate is UNCONFIRMED — core's contract,
+            verbatim, "a consumer must not read it as confirmed". Projecting the coordinate and dropping this
+            bit renders an unconfirmed coordinate as a confirmed one.
+            🔴 NEVER-FALSE: upstream DELETES the key at confirmation and never writes `false`, so absence =
+            confirmed, and rows written before 7.78.0 read identically (a true additive).
 
     # ── B4 命名化(2026-07-31):以下 10 个 component 与 SDK resources/* 的同名导出类型 1:1;内容为
     #    原端点内联 schema 的字节级搬运(零语义变更),使用点换 $ref。census 封闭注随迁。
@@ -8849,13 +8975,16 @@ components:
         🔴 A SIXTH PROVENANCE (server >= 7.75.0 / S-252, same lane): a 409 `decide.workflow_parks_unreadable`
         instead of the 200 above means the run record's `parks[]` — the engine's OWN park-ownership ledger,
         and the only source this lane can join the caller's checkpoint against — cannot be read at all (an
-        engine older than 7.17.0 never wrote the key, or one entry is damaged). A resume of that run is refused
-        by the engine for the identical reason, so this lane refuses too rather than accept a decision it could
-        never actually deliver. This is NOT the same failure as `decide.workflow_host_not_parked`: recovery is
-        the OPPOSITE — there is no retry and no waiting for a park, because this run cannot be resumed at all.
-        The card stays pending; the only recovery action is to start a NEW run. SDK → a dedicated
-        `DecideWorkflowParksUnreadableError` (NOT `DecideWorkflowHostError` — folding the two together would
-        make "retry via `.runId`" look like valid advice for a run this engine can never touch again). This
+        engine older than 7.17.0 never wrote the key, or one entry is damaged). The redemption keys this lane
+        needs are not on such a record, so it refuses rather than accept a decision it could never deliver.
+        This is NOT the same failure as `decide.workflow_host_not_parked`: recovery is neither a retry nor
+        waiting for a park — it is RESUMING the run named by `runId`, and whether that resume is admitted is the
+        engine's answer, not this lane's. 🔴 CORRECTED at server 7.78.0 / core 7.18.0: this text used to say the
+        engine refuses to resume such a record and that the only recovery was a NEW run — core 7.18.0 falsified
+        that (admission does not decide on the record's `parks` key alone), and the old advice abandoned
+        recoverable runs. SDK → a dedicated `DecideWorkflowParksUnreadableError` (NOT
+        `DecideWorkflowHostError` — folding the two together would make "retry this decide" look like valid
+        advice, when the action is to resume the run instead). This
         code REPLACES the 7.71.0 code `decide.workflow_park_identity_lost`, retired at this same 7.75.0 and
         never modeled by any released version of this SDK.
         The durable approval-queue projection is UNCHANGED — no key marks the workflow origin on any read face.
@@ -9925,8 +10054,11 @@ components:
             `workflow_host_unknown`, `workflow_host_not_parked`, and — server >= 7.75.0 / S-252 —
             `workflow_parks_unreadable`): the WORKFLOW run's id. On the first three it is the RECOVERY HANDLE
             (wait for the host session to park and re-decide, or resume that run directly); on
-            `workflow_parks_unreadable` it names a run that CANNOT be resumed at all — the handle is for
-            identifying which run to abandon in favor of a new one, not for retrying it.
+            `workflow_parks_unreadable` it is ALSO a recovery handle but for a DIFFERENT verb — resume that run
+            (admission is where the engine settles its park set), do not re-issue this decide against it; whether
+            that resume is admitted is the engine's answer, not this code's.
+            🔴 CORRECTED at server 7.78.0 / core 7.18.0: this text used to call it a run that cannot be resumed
+            at all, to be abandoned in favour of a new one — that was true of core < 7.18.0 only.
             🔴 NOT interchangeable with `taskId`: the workflow-child park lane mints no taskId at all (this
             decision never landed on any run, so minting one would be a lie), and the other two decide lanes
             mint no runId. Branch by `errorCode`, never fall back from one handle to the other.
@@ -10013,6 +10145,11 @@ components:
         #   `allOf: [SegmentEndFields]`, one wire concept, one shape). SERVER-MINTED (server >= 7.77.0): the
         #   engine emits only `reasoning_delta`, so this frame's presence tracks the SERVER version, not core's.
         - $ref: '#/components/schemas/Event_reasoning_end'
+        # sdk 9.5.0: the two frames core 7.18.0 added and server 7.78.0 forwards — `tool_disclosure` (#786,
+        #   the leg's DEFERRAL CENSUS, all three legs) and `tool_progress` (#741, a still-running call's
+        #   liveness tick, LIVE ONLY — never on the durable replay).
+        - $ref: '#/components/schemas/Event_tool_disclosure'
+        - $ref: '#/components/schemas/Event_tool_progress'
       discriminator:
         propertyName: type
         mapping:
@@ -10059,6 +10196,8 @@ components:
           text_end: '#/components/schemas/Event_text_end'
           tool_roster_delta: '#/components/schemas/Event_tool_roster_delta'
           reasoning_end: '#/components/schemas/Event_reasoning_end'
+          tool_disclosure: '#/components/schemas/Event_tool_disclosure'
+          tool_progress: '#/components/schemas/Event_tool_progress'
 
     # design/99 §E2 (SHIPPED, core TaskEventIdentity) — additive per-event identity on every CONTENT event (NOT on
     # the lifecycle arms turn_end/compacted/suspended/done/failed). eventId = uuidv7 dedup/resume handle (the durable
@@ -10361,12 +10500,25 @@ components:
           required: [kind]
           properties:
             kind: { const: allowed }
+            classifier:
+              allOf: [{ $ref: '#/components/schemas/GateClassifierAttribution' }]
+              description: >
+                server >= 7.78.0 (core 7.18.0 #742) — the classification's model attribution. It rides BOTH arms
+                (a classification ends either way, allow or deny), which is why this key is mirrored on the deny
+                arm below. Full reading in `GateClassifierAttribution`.
         - type: object
           additionalProperties: false
           required: [kind, deniedBy]
           properties:
             kind: { const: denied }
             deniedBy: { $ref: '#/components/schemas/DeniedBy' }
+            classifier:
+              allOf: [{ $ref: '#/components/schemas/GateClassifierAttribution' }]
+              description: >
+                server >= 7.78.0 (core 7.18.0 #742) — the same member as on the allow arm, same shape, same
+                reading (see `GateClassifierAttribution`). Orthogonal to the sibling `cause`: `cause` says WHAT
+                SHAPE this deny was, this key says WHICH MODEL decided — an inherited chain carries a `cause`
+                with no attribution seat, so the two can appear apart.
             cause:
               type: string
               description: >-
@@ -10380,6 +10532,52 @@ components:
                 — branch the two known words and keep a default arm. Absent = this deny was not a classifier-fault
                 shape (policy / person / rule refused); never read absence as "classifier healthy".
 
+    GateClassifierAttribution:
+      # sdk 9.5.0:具名 —— 同一份形挂在 `GateDisposition` 的两只臂上,内联会立刻是两份会各自漂的镜像。
+      type: object
+      additionalProperties: false
+      description: >
+        WHICH MODEL decided one auto-mode classification (core 7.18.0 #742 `AutoModeClassifierRound`,
+        server >= 7.78.0): the rung it was FOR, the rung that ANSWERED, and — only when the ladder actually
+        MOVED — where it left, where it landed and why.
+        🔴 ABSENT READS **UNKNOWN**, NEVER "the seat answered" (core's words). "The seat answered" is this
+        member PRESENT with `fallback` ABSENT — the two are distinguishable on the wire. The three causes of
+        the member being absent are NOT distinguishable from the record: no classification happened; one ran on
+        a decider given no candidate ladder (it can name no model); or one ran on an ANCESTOR's inherited
+        chain, which carries the FORM but has no attribution seat yet.
+        🔴 NOT PERSISTED into the durable row (same as core): it is an observation of HOW this gate pass was
+        decided, not a terminal fact. It appears on `tool_end.gate` and on the two raw replay legs.
+        🔴 A record failing core's invariant I6 is withheld WHOLE by the server, so every attribution that
+        reaches a consumer has two non-empty model ids, `fallback.to === modelUsed`, and a cause inside the
+        closed set.
+      required: [modelRequested, modelUsed]
+      properties:
+        modelRequested: { type: string, description: "The ladder's FIRST rung — the seat this classification was for." }
+        modelUsed:
+          type: string
+          description: >
+            The rung whose answer the gate ACTED ON; where no candidate ruled, the last rung ATTEMPTED (stated,
+            never implied by absence).
+        fallback:
+          type: object
+          additionalProperties: false
+          required: [from, to, cause]
+          description: >
+            Present EXACTLY when the ladder MOVED to reach `modelUsed`; ABSENT = the first rung answered
+            ("the seat answered"). This is the one place on this shape where an absence IS an assertion.
+          properties:
+            from: { type: string, description: 'The rung it left.' }
+            to: { type: string, description: 'The rung it arrived at — ALWAYS equal to `modelUsed` (core invariant I6).' }
+            cause:
+              type: string
+              enum: [error, timeout, parse_error]
+              description: >
+                Why the ladder moved: `error` (that rung threw / rejected), `timeout` (the round-trip cap),
+                `parse_error` (it answered outside the verdict contract).
+                🔴 TRULY CLOSED here, unlike most engine words on this wire: core's I6 screen calls an
+                out-of-set cause a record DEFECT and the server withholds a defective record whole, so an
+                unknown word reaches a consumer as an ABSENT `gate`, never as a strange value.
+
     GateOutcome:
       type: object
       additionalProperties: false
@@ -10959,6 +11157,27 @@ components:
             already owns the single redaction mint point for it). The actionable cause is `errorCode`.
             A row missing `name` or `status` is dropped individually — the other servers'' rows still ship.
           items: { $ref: '#/components/schemas/WiringManifestMcpEntry' }
+        hooks:
+          type: array
+          description: >
+            core 7.18.0 (#789), server >= 7.78.0 — TENANT-visible: the hook seats THIS leg wired, one row per
+            family, in core's declaration order. EFFECTIVE half only.
+            🔴 PRESENT IFF at least one seat is wired — core NEVER emits an empty array, so "the key is here"
+            means non-empty. 🔴 ABSENCE READS "this leg wired no hook RECORD of its own", NOT "no hook runs":
+            a delegated child with no local record can still be screened (and refused) by an ANCESTOR's
+            `preToolUse` through the gate's constraint fold, which this face deliberately does not call a hook
+            of this leg. A row missing `family` or `owner` is dropped INDIVIDUALLY (same rule as `mcp[]`); all
+            rows dropped => the key is absent. 🔴 EXCLUDED from `configFingerprint` (the record is a per-task
+            seat), so two legs with the same fingerprint and different `hooks[]` are NOT in contradiction.
+          items: { $ref: '#/components/schemas/WiringManifestHookEntry' }
+        lsp:
+          allOf: [{ $ref: '#/components/schemas/WiringManifestLspSeam' }]
+          description: >
+            core 7.18.0 (#789), server >= 7.78.0 — TENANT-visible: the LSP code-intelligence seam. EFFECTIVE
+            half only. PRESENT IFF a manager seat resolved (`spec.lspManager ?? deps.lspManager`); a deployment
+            that wires none reports nothing at all. The server never invents `mounted: false` when it cannot
+            read the bit — the whole section goes absent instead (a minted false would read as "really not
+            mounted").
         governance:
           type: object
           additionalProperties: false
@@ -11008,6 +11227,104 @@ components:
         parentToolCallId: { type: string }
         sourceTaskId: { type: string }
         bgAgentId: { type: string }
+    Event_tool_disclosure:
+      type: object
+      description: >
+        This leg's DEFERRAL CENSUS (server >= 7.78.0, core 7.18.0 #786): which mounted tools ship today as
+        NAME-ONLY placeholders, which ones the model has activated, and which policy decided it.
+        🔴 A DIFFERENT QUESTION FROM THE ROSTER: `wiring_manifest.tools` says WHICH TOOLS CAN BE CALLED; this
+        frame says WHETHER ONE MUST BE FETCHED FIRST. A deferred name is ON the roster.
+        🔴 ALL THREE LEGS (live SSE + durable ledger + resume replay), same as `tool_roster_delta`. The leg-start
+        census is the FIRST frame after `wiring_manifest`; every later frame means the census CHANGED (an
+        activation landed).
+        🔴 WHOLE SNAPSHOT: `deferred` and `activated` are both complete — replace your copy, never merge.
+        🔴 ABSENCE READINGS, three of them: (a) the WHOLE FRAME absent = "this leg deferred NOTHING" (a leg with
+        an empty deferred set emits no frame at all) — NOT "this build has no such face" and NOT "unknown";
+        (b) `thresholdPercent` absent = under `always` / `never` NO THRESHOLD WAS EVER CONSULTED — never read it
+        as "the default percent"; (c) a RESUME leg's FIRST census may carry a non-empty `activated` (the engine
+        reseeded it) — never read that as "this leg activated them".
+        🔴 Half a census never reaches the wire: the server drops the WHOLE frame when any of the three required
+        members is unreadable (half a table would read as "these are the only deferred ones").
+      additionalProperties: false   # 封闭 + identity 本地镜像:见 Event_reasoning 处的长注
+      required: [type, policy, deferred, activated]
+      properties:
+        type: { const: tool_disclosure }
+        policy:
+          type: string
+          description: >
+            Which arm of `RunnerDeps.toolSearch` decided this (`always` / `never` / `auto` today). READ AS OPEN:
+            the server passes it through verbatim and does not enumerate, so a new word must pass through your
+            default arm.
+        thresholdPercent:
+          type: number
+          description: >
+            Under `auto`: the percent of the window the candidate set had to reach. ABSENT under `always` /
+            `never` because no threshold was consulted — NEVER substitute a default.
+            🔴 A FINITE NUMBER, NOT AN INTEGER: the engine's seat accepts any finite percent in [0, 100]
+            (`{mode:"auto", thresholdPercent: 12.5}` is a legal deployment) and the server forwards it through
+            a finite-number guard, verbatim. Typing it `integer` here would make a spec-validating consumer
+            REJECT a legal frame, and the symptom ("this build has no census") is indistinguishable from the
+            frame being absent. The range is NOT constrained here either: the seat enforces [0, 100] at parse
+            time, the server re-derives nothing, and a bound this face does not enforce would be a second
+            screen that can only disagree with the first.
+        deferred:
+          type: array
+          items: { type: string }
+          description: 'Every name-only placeholder on this leg (frozen at prepare, sorted). WHOLE snapshot.'
+        activated:
+          type: array
+          items: { type: string }
+          description: >
+            The deferred names ACTIVE right now (the engine's state, not a record of commits; sorted, always a
+            subset of `deferred`). WHOLE snapshot.
+        # identity:两键 —— server 的 `identityFields` 只在这条臂上铸 eventId/parentToolCallId(本帧不在
+        # live 腿那张四键白名单上),同 Event_compaction_outcome 的处置。
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+    Event_tool_progress:
+      type: object
+      description: >
+        A LIVENESS TICK for a tool call that is STILL RUNNING (server >= 7.78.0, core 7.18.0 #741), minted
+        between that call's `tool_start` and `tool_end` under the same ordering law as every other content
+        frame; a child's ticks reach a parent under the same opt-in as those two
+        (`TaskSpec.forwardSubagentEvents`).
+        🔴 LIVE ONLY — NOT PERSISTED, NOT REPLAYED (core's `tool_progress.ephemeral`, same family as
+        `task_progress` / `status`): `GET /v1/runs/{id}/events` has no such arm and a reconnect back-fills
+        nothing. The DURABLE fact about how long a call took is `tool_end` — core states explicitly that
+        `elapsedTimeSeconds` does NOT equal the `tool_end` duration (this clock starts when the call ENTERS
+        EXECUTION, earlier than a shell command's spawn).
+        🔴 THE FRAME'S ABSENCE IS NEVER EVIDENCE (core's `tool_progress.cadence`): at most one frame per second
+        per call, and a call that finishes INSIDE one interval emits NONE. Never expect one per `tool_start`,
+        and never use its presence to decide whether a call ran.
+        🔴 `output` / `totalLines` / `totalBytes` RIDE OR STAY AWAY TOGETHER: present = "output has been
+        observed", absent = "not one byte has been observed" (`sleep 3`; or an execution environment that does
+        not stream — a buffered remote `exec` never invokes the output callbacks) — NEVER "unchanged since the
+        last frame". The server projects the counters only when `output` itself is readable, so a counter never
+        arrives without the text it counts.
+      additionalProperties: false   # 封闭 + identity 本地镜像:见 Event_reasoning 处的长注
+      required: [type, toolCallId, toolName]
+      properties:
+        type: { const: tool_progress }
+        toolCallId: { type: string, description: "The still-running call's id — joins its own `tool_start`/`tool_end`. The server drops the whole frame without it." }
+        toolName: { type: string, description: 'The running tool name (the `tool_start` value verbatim).' }
+        elapsedTimeSeconds:
+          type: integer
+          description: >
+            Whole seconds this call has been running: floored, monotonic across its frames, ONE ORIGIN per call
+            stamped by the mint. It does NOT equal the `tool_end` duration. ABSENT (rather than 0) when the
+            server's finite-number guard could not read it — "the clock was unreadable" is not "zero seconds".
+        output:
+          type: string
+          description: >
+            The TAIL of what the command has written so far (stdout and stderr interleaved in arrival order),
+            capped by the mint to a few trailing lines — a live pane, never a log.
+            🔴 UNTRUSTED RAW, exactly like `tool_end.output`: the server has passed it through the SAME
+            redactor, a consumer MAY bound it further before display, and it must NEVER be re-fed to a model
+            (it is a moving, truncated window; the model already holds the full result).
+        totalLines: { type: integer, description: 'Newlines observed so far (>= the tail''s own line count — the tail is only a window). Rides iff `output` does.' }
+        totalBytes: { type: integer, description: 'Bytes observed BEFORE the tail cap, so it keeps growing after `output` stops being able to. Rides iff `output` does.' }
+        eventId: { type: string }
+        parentToolCallId: { type: string }
     ToolRosterDelta:
       type: object
       description: >
@@ -11871,6 +12188,41 @@ components:
             frame and the inbox row; the `card_json` card deliberately does NOT carry it (it travels with `origin`,
             which is not on the card). Absence = `origin` is not that word — NOT an assertion that the rule store
             is healthy.
+        readRootCandidate:
+          type: object
+          required: [dir, clearsThisAsk]
+          additionalProperties: false
+          properties:
+            dir:
+              type: string
+              minLength: 1
+              maxLength: 1024
+              description: >-
+                The ABSOLUTE, lexically-folded directory to add to this session's read roots, spelled by the read
+                boundary itself — THE STRING SHOWN IS THE STRING TO ADD. A shell may render a shortened / `~` form,
+                but must echo THIS string back verbatim. The server carries it whole or drops the whole key
+                (a malformed shape, or a `dir` over 1024 UTF-16 code units ⇒ the key is ABSENT — never truncated,
+                because a truncated directory is a DIFFERENT directory and adding it would not clear this ask;
+                see the STRING-LENGTH UNIT convention in `info.description` for this `maxLength`'s counting unit).
+            clearsThisAsk:
+              type: boolean
+              enum: [true]
+              description: >-
+                Shape, not value — the domain is the literal `true` only, so this seat cannot be quietly widened
+                into a "might help" hint.
+          description: >-
+            server >= 7.78.1 (core 7.19.0), ADDITIVE, LIVE `tool_approval` FRAME ONLY — the clearing directory for
+            an OUT-OF-ROOT READ ask: add `dir` to this session's read roots (the shell's existing `/add-dir`) and
+            the same call stops asking.
+            🔴 READ PRESENCE ONLY, NEVER ABSENCE. Absence is NOT "nothing can be done": it also covers sensitive-path
+            deny rows (pattern-judged — no root changes them), commands the read boundary cannot parse (heredoc /
+            newline / command substitution / an argument used as the program), unexpanded globs, recursive walks,
+            and every ask NOT raised by the read boundary — every ask on server <= 7.78.0 has this shape too.
+            ⚠️ THIS FACE ONLY: `card_json`, the §2 inbox row, the `/v1/approvals` rich row and the park face carry
+            NO twin of this seat in this version — a PARKED out-of-root read ask still renders that single card.
+            ⚠️ Known shapes (upstream-registered, so a shell must NOT render this option as a guarantee):
+            `cd X && cat Y` yields X's PARENT directory; and on a deployment that normalizes declared read roots
+            (e.g. `/tmp/x` stored as `/private/tmp/x`) the same call may ask once more after the root is added.
     ApprovalRequestFrame:
       type: object
       description: >
@@ -12946,12 +13298,40 @@ components:
         usedTokens: { type: integer }
         windowTokens: { type: integer, description: 'autocompact 窗,不是模型上下文大小。' }
         compactAtTokens: { type: integer }
+        sections:
+          type: array
+          description: >
+            core 7.18.0 (#790), server >= 7.78.0 — WHAT THIS LEG'S SYSTEM PROMPT IS MADE OF: one row per
+            rendered pack section.
+            🔴 NOT THE SAME COORDINATE SYSTEM AS `usedTokens` — NEVER SUBTRACT (core's contract, verbatim):
+            `sections[].tokens` is a PREPARE-time estimate of the SYSTEM PROMPT from rendered character counts,
+            while `usedTokens` is the engine's triggering input over the WHOLE conversation. So: never subtract
+            the section sum from `usedTokens`, never compare one section against `compactAtTokens`, and never
+            read a cross-frame change as "it grew" — the values FREEZE at prepare and every boundary on this leg
+            re-reports the same set verbatim. The sum MAY exceed `usedTokens` (two quantities, not one ledger).
+            🔴 THE WHOLE KEY ABSENT = this leg assembled NO section IR (some providers replace the prompt
+            wholesale and hand back an opaque block) — NOT "every section weighs zero". An element missing
+            `id`/`tokens` is dropped individually; all dropped => the key is absent.
+          items: { $ref: '#/components/schemas/ContextUsageSection' }
         # LIVE 腿(routes/tasks.ts)在这条臂上挂 identity;durable 腿不挂。同 turn_end 的处置:
         # 本地可选声明,不 allOf(不把 identity 承诺进契约面)。
         eventId: { type: string }
         parentToolCallId: { type: string }
         sourceTaskId: { type: string }
         bgAgentId: { type: string }
+    ContextUsageSection:
+      # sdk 9.5.0:具名而非内联 —— 与 `WiringManifestMcpEntry` 同一条裁定(一份行形,多处引用)。
+      type: object
+      description: >
+        One rendered section of this leg's SYSTEM PROMPT (core 7.18.0 #790). `id` shares ONE vocabulary with
+        `prompt.assembled`'s `sections[].id`, so the two faces join. See `Event_context_usage.sections` for the
+        do-not-subtract rule — it is the load-bearing half of this shape's contract.
+      additionalProperties: false
+      required: [id, tokens]
+      properties:
+        id: { type: string, description: "The section id — same vocabulary as `prompt.assembled`'s `sections[].id`." }
+        tokens: { type: integer, description: 'PREPARE-time estimate of this section, in ITS OWN coordinate system (see the parent key).' }
+        kind: { type: string, description: 'The semantic slot; ABSENT when the manifest entry declared none (not "no semantics").' }
     Event_compaction_outcome:
       type: object
       description: >
@@ -13854,6 +14234,66 @@ components:
           properties:
             armed: { type: boolean }
             reason: { type: string }
+        hooks:
+          type: array
+          description: >
+            core 7.18.0 (#789), server >= 7.78.0 — the hook seats THIS leg wired, one row per family.
+            EFFECTIVE half only (the diagnostics endpoint's static half never carries it). Present iff at least
+            one seat is wired; absence means "no hook RECORD of this leg", never "no hook runs".
+            Full per-key contract: see Event_wiring_manifest.hooks.
+          items: { $ref: '#/components/schemas/WiringManifestHookEntry' }
+        lsp:
+          allOf: [{ $ref: '#/components/schemas/WiringManifestLspSeam' }]
+          description: >
+            core 7.18.0 (#789), server >= 7.78.0 — the LSP seam. EFFECTIVE half only; present iff a manager
+            seat resolved. `mounted` and `lane` are INDEPENDENT facts — never fold them into one.
+            Full per-key contract: see Event_wiring_manifest.lsp.
+    WiringManifestHookEntry:
+      # sdk 9.5.0:与 `WiringManifestMcpEntry` 同一条裁定 —— 同一份行形被 live 帧与静态诊断面两处引用,
+      # 内联就是两份会各自漂的镜像,所以一开始就具名。
+      type: object
+      description: >
+        One row of a leg's HOOK seat manifest (core 7.18.0 #789): which family, where the seat came from, and
+        whether the `preToolUse` row was DECLARED observational.
+      additionalProperties: false
+      required: [family, owner]
+      properties:
+        family:
+          type: string
+          description: >
+            The hook family. core's closed vocabulary today (`preToolUse` / `postToolUse` / `userPromptSubmit` /
+            `stop` / `postToolUseFailure` / `postToolBatch` / `preCompact` / `postCompact` / `stopFailure` /
+            `permissionDenied`) but READ AS OPEN: the server passes it through verbatim and does not enumerate,
+            so a newly minted family must pass through your default arm.
+        owner:
+          type: string
+          description: "Where the seat came from — core's `SeamProvenance` (`spec` / `deps`). Closed today, read as open."
+        observational:
+          type: boolean
+          enum: [true]
+          description: >
+            Only on the `preToolUse` row, and only when the deployment DECLARED the face observational: it still
+            runs on every call but is not folded into a delegated child's inherited constraints.
+            🔴 NEVER-FALSE — core's words: "Absence means 'not declared', never 'declared false'".
+    WiringManifestLspSeam:
+      # sdk 9.5.0:同上 —— live 帧与静态面共用一份段形。
+      type: object
+      description: >
+        A leg's LSP code-intelligence seam (core 7.18.0 #789). 🔴 THE TWO BITS ARE INDEPENDENT AND MUST NOT BE
+        READ AS ONE: `mounted` is the ROSTER fact (a wired manager whose `LSP` tool was excluded reports
+        `false`), while `lane` arms on the manager / the hands / the opt-out and NOT on the mount — so
+        `{mounted: false, lane: "diagnostics"}` is a REAL, REACHABLE state, not bad data.
+      additionalProperties: false
+      required: [mounted]
+      properties:
+        mounted:
+          type: boolean
+          description: 'Is the LSP tool on this leg''s roster. Required — when the server cannot read it the WHOLE section is absent (it never mints a false).'
+        lane:
+          type: string
+          description: >
+            Which lanes are live — core's closed three (`tool` / `diagnostics` / `tool_and_diagnostics`), read as
+            open. ABSENT = neither lane is live (not "unknown").
     WiringManifestMcpEntry:
       # 8.9.0:从 `Event_wiring_manifest.mcp.items` 的内联形**提取**为具名 schema —— 同一份行形现在被
       # 两处引用(live 帧与 `WiringManifest` 的静态/两半形),内联会立刻变成两份会各自漂的镜像。

package/package.json

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