@sema-agent/settings-schema 1.9.0 → 2.0.0

package/dist/hooks.js

@@ -2,10 +2,15 @@
  * `hooks` — the CC-parity hooks contract (incl. stop attribution).
  *
  * ONE definition of the FULL hook-event set — 27 CC 2.1.198 events (REF: the `jP` array in
- * claude-cli-2.1.198.pretty.js) + 4 post-198 events the shell already ships (CwdChanged / FileChanged /
- * MessageDisplay, and DirectoryAdded from CC 2.1.219). Per the product ruling: the CONTRACT is the full set
- * from day one; the engine hook-runner (service) and the shell light events up in PHASES — adding an event
- * later is pure implementation, never a schema change.
+ * claude-cli-2.1.198.pretty.js) + 6 post-198 events (CwdChanged / FileChanged / MessageDisplay, DirectoryAdded
+ * from CC 2.1.219, and the model-switch pair PreModelSwitch / PostModelSwitch from CC 2.1.259). Per the product
+ * ruling: the CONTRACT is the full set from day one; the engine hook-runner (service) and the shell light events
+ * up in PHASES — adding an event later is pure implementation, never a schema change.
+ *
+ * DRIFT: this package OWNS the hooks contract, so it owns noticing that CC moved. `test/upstream-drift.test.ts`
+ * compares {@link HOOK_EVENTS} against a CC anchor snapshot that `scripts/extract-cc-hook-events.mjs` extracts
+ * from the CLI bundle — a word CC has and this set does not is a RED test naming it, instead of a consumer
+ * discovering it the hard way (the 1.3.0 / 1.6.0 / 1.8.0 / 1.11.0 pattern).
  *
  * CONSUMERS
  * - service (the worker server): `TaskRequest.settings.hooks` wire face = `HooksConfig` below; the worker-side
@@ -56,12 +61,18 @@ export const CC_198_HOOK_EVENTS = [
     "InstructionsLoaded",
 ];
 /**
- * Post-CC-2.1.198 additions the shell already ships (sema superset; CC added them after 198).
+ * Post-CC-2.1.198 additions (sema superset; CC added them after 198).
  * APPEND-ONLY: new members go at the tail (1.3.0 `DirectoryAdded`, CC 2.1.219 — CC's own tuple places it
  * between FileChanged and MessageDisplay; the declaration order here is not normative, the enum is a set).
+ * 1.11.0 appends the model-switch pair (`PreModelSwitch` / `PostModelSwitch`, CC 2.1.259 — absent from the
+ * 2.1.250 corpus, so 250→259 is when they landed upstream).
+ *
+ * 🔴 This list is no longer maintained by hand-reading a CLI bundle: `test/upstream-drift.test.ts` fails
+ * (naming the missing words) whenever the CC anchor snapshot in `test/fixtures/cc-hook-events.json` holds an
+ * event this set does not, and that snapshot is produced by `scripts/extract-cc-hook-events.mjs`, never typed.
  */
-export const POST_198_HOOK_EVENTS = ["CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded"];
-/** The full 31-event contract set = CC 198's 27 + the 4 post-198 shell events. */
+export const POST_198_HOOK_EVENTS = ["CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded", "PreModelSwitch", "PostModelSwitch"];
+/** The full 33-event contract set = CC 198's 27 + the 6 post-198 events. */
 export const HOOK_EVENTS = [...CC_198_HOOK_EVENTS, ...POST_198_HOOK_EVENTS];
 export const HookEventName = z.enum(HOOK_EVENTS);
 // ── ownership (owner-single) ─────────────────────────────────────────────────────────────────────
@@ -124,6 +135,10 @@ export const HOOK_EVENT_MATCHER_FIELD = {
     FileChanged: "file_path", // matched against basename(file_path)
     MessageDisplay: null,
     DirectoryAdded: null, // the shell's getMatchingHooks switch has no arm for it → every entry matches (CwdChanged family)
+    // CC 2.1.259 matches both model-switch events against the RESOLVED target model id (`to_model`), so a
+    // matcher can scope a hook to "only when switching TO this model".
+    PreModelSwitch: "to_model",
+    PostModelSwitch: "to_model",
 };
 // ── shared enums (CC-verbatim) ─────────────────────────────────────────────────────────────────────────
 export const PermissionBehavior = z.enum(["allow", "deny", "ask"]);
@@ -398,7 +413,49 @@ export const DirectoryAddedHookInput = BaseHookInput.extend({
     directory: z.string(),
     source: z.enum(DIRECTORY_ADDED_SOURCES),
 });
-/** Any hook input — discriminated on `hook_event_name` (all 31 events). */
+/**
+ * What triggered a model switch (CC 2.1.259). The two events carry DIFFERENT vocabularies and that is
+ * deliberate upstream: `PreModelSwitch` only fires for a REQUESTED switch (slash command / picker / headless
+ * set_model), while `PostModelSwitch` also reports changes nobody requested (`auto` = automatic fallback,
+ * `resume` = model restored while resuming a session) — those have no "before" to gate.
+ */
+export const MODEL_SWITCH_SOURCES = {
+    pre: ["command", "picker", "sdk"],
+    post: ["command", "picker", "sdk", "auto", "resume"],
+};
+/** The fields both model-switch events carry (CC-verbatim): the models, what was asked for, and the
+ *  cache-forfeit estimate a hook needs to decide whether the switch is worth it. */
+const ModelSwitchFields = {
+    /** Resolved model id the session was running before the switch. */
+    from_model: z.string(),
+    /** Resolved model id the session runs after the switch (also the `matcher` field for both events). */
+    to_model: z.string(),
+    /** What was asked for — an alias such as `"opus"`, a full id, or `null` for "default". NULLABLE, not optional. */
+    requested_model: z.string().nullable(),
+    /** Prompt tokens the next request re-sends (0 before the first response). */
+    context_tokens: z.number(),
+    /** Whether the current model's prompt cache is likely still warm (a switch then forfeits it). */
+    prompt_cache_warm: z.boolean(),
+    cache_ttl: z.enum(["5m", "1h"]),
+    /** Estimated cost of re-caching `context_tokens` on `to_model` at its cache-write rate (excludes the response). */
+    estimated_cache_write_usd: z.number(),
+    /** `configured` = managed modelPricing; `catalog` = list price; `default` = `to_model` unknown, default tier assumed. */
+    pricing: z.enum(["configured", "catalog", "default"]),
+};
+/** Fires BEFORE a requested model switch; its `hookSpecificOutput.permissionDecision` can deny/ask (same
+ *  contract as PreToolUse — DESIGN POINT ① applies: the engine clamps `allow` to the policy floor). */
+export const PreModelSwitchHookInput = BaseHookInput.extend({
+    hook_event_name: z.literal("PreModelSwitch"),
+    ...ModelSwitchFields,
+    source: z.enum(MODEL_SWITCH_SOURCES.pre),
+});
+/** Fires AFTER the session model changed, whatever the cause (informational; may add context). */
+export const PostModelSwitchHookInput = BaseHookInput.extend({
+    hook_event_name: z.literal("PostModelSwitch"),
+    ...ModelSwitchFields,
+    source: z.enum(MODEL_SWITCH_SOURCES.post),
+});
+/** Any hook input — discriminated on `hook_event_name` (all 33 events). */
 export const HookInput = z.discriminatedUnion("hook_event_name", [
     PreToolUseHookInput,
     PostToolUseHookInput,
@@ -431,6 +488,8 @@ export const HookInput = z.discriminatedUnion("hook_event_name", [
     FileChangedHookInput,
     MessageDisplayHookInput,
     DirectoryAddedHookInput,
+    PreModelSwitchHookInput,
+    PostModelSwitchHookInput,
 ]);
 // ── hook output / decision semantics (CC-verbatim, with the service-receipt design points pinned) ────────
 //
@@ -502,6 +561,15 @@ export const HookSpecificOutput = z.union([
     z.object({ hookEventName: z.literal("CwdChanged"), watchPaths: z.array(z.string()).optional() }),
     z.object({ hookEventName: z.literal("FileChanged"), watchPaths: z.array(z.string()).optional() }),
     z.object({ hookEventName: z.literal("WorktreeCreate"), worktreePath: z.string() }),
+    z.object({
+        hookEventName: z.literal("PreModelSwitch"),
+        /** CC: `allow` proceeds (skipping the interactive cache-miss confirm), `deny` cancels the switch, `ask`
+         *  asks the user to confirm (a headless session refuses instead). Same wording as PreToolUse — DESIGN
+         *  POINT ① applies: a hook `allow` never overrides a policy floor. */
+        permissionDecision: PermissionBehavior.optional(),
+        permissionDecisionReason: z.string().optional(),
+    }),
+    z.object({ hookEventName: z.literal("PostModelSwitch"), additionalContext: z.string().optional() }),
 ]);
 /**
  * Synchronous hook JSON output (stdout of a command hook, CC-verbatim). Exit-code semantics ride

package/dist/remote-exec.d.ts

@@ -61,7 +61,7 @@ export declare const RemoteExecSpec: z.ZodDiscriminatedUnion<"provider", [z.ZodO
     memory?: string | undefined;
     workdir?: string | undefined;
     cpus?: number | undefined;
-    network?: "host" | "none" | "bridge" | undefined;
+    network?: "none" | "host" | "bridge" | undefined;
     mountPath?: string | undefined;
 }, {
     provider: "local-docker";
@@ -69,7 +69,7 @@ export declare const RemoteExecSpec: z.ZodDiscriminatedUnion<"provider", [z.ZodO
     memory?: string | undefined;
     workdir?: string | undefined;
     cpus?: number | undefined;
-    network?: "host" | "none" | "bridge" | undefined;
+    network?: "none" | "host" | "bridge" | undefined;
     mountPath?: string | undefined;
 }>, z.ZodObject<{
     /** The remote docker endpoint — a DOCKER_HOST url: `ssh://user@host` or `tcp://host:2376`. A `user@` is OK
@@ -96,7 +96,7 @@ export declare const RemoteExecSpec: z.ZodDiscriminatedUnion<"provider", [z.ZodO
     memory?: string | undefined;
     workdir?: string | undefined;
     cpus?: number | undefined;
-    network?: "host" | "none" | "bridge" | undefined;
+    network?: "none" | "host" | "bridge" | undefined;
     mountPath?: string | undefined;
     tlsCertEnv?: string | undefined;
     tlsKeyEnv?: string | undefined;
@@ -109,7 +109,7 @@ export declare const RemoteExecSpec: z.ZodDiscriminatedUnion<"provider", [z.ZodO
     memory?: string | undefined;
     workdir?: string | undefined;
     cpus?: number | undefined;
-    network?: "host" | "none" | "bridge" | undefined;
+    network?: "none" | "host" | "bridge" | undefined;
     mountPath?: string | undefined;
     tlsCertEnv?: string | undefined;
     tlsKeyEnv?: string | undefined;

package/dist/remote-exec.js

@@ -28,7 +28,7 @@ import { ENV_NAME, K8S_QUANTITY, NON_SECRET_URL, TCP_PORT, containsSecretToken,
  *  byte uniformly — a NUL validates here but makes Node throw at spawn/boot (fail-OPEN → runtime crash). R20. */
 const execStr = z.string().min(1).refine((s) => !hasNul(s), "must not contain a NUL byte");
 /** Container knobs shared by the two docker lanes (local-docker / remote-docker). `network` defaults to
- *  `none` at the adapter (the safe posture for untrusted code — see DUAL-MODE-DESIGN.md). */
+ *  `none` at the adapter (the safe posture for untrusted code — see the dual-mode design note). */
 const DOCKER_FIELDS = {
     /** Sandbox image (required — a run must be reproducible). */
     image: execStr,

package/dist/resolve-roster.d.ts

@@ -1,5 +1,5 @@
 /**
- * Per-worker roster resolution (docs/MULTI-ROSTER.md). Turns the GLOBAL effective config + a worker name
+ * Per-worker roster resolution (the multi-roster design note). Turns the GLOBAL effective config + a worker name
  * into THAT worker's effective config: its `models` domain is the roster's view (model subset + role-map +
  * @-allowlist override), everything else stays global. The `rosters` domain is control-plane-only and is
  * always stripped from the wire payload (no /effective consumer reads it).

package/dist/scheduler-store.d.ts

@@ -54,13 +54,23 @@ export interface SchedulerStore {
 }
 /** Structural validation of one record (required fields + a well-formed `when`). Unknown fields are allowed. */
 export declare function isSchedulerRecord(v: unknown): v is SchedulerRecord;
-/** One record dropped by {@link parseSchedulerStore} for failing {@link isSchedulerRecord} (malformed shape).
- *  `index` = its position in the parsed array (for correlating with the source file); `record` = the raw
- *  (unvalidated) value, for diagnostics. Additive — passing `onWarning` is optional. */
+/** Something {@link parseSchedulerStore} DID to the data it read, rather than reading it verbatim. `index` =
+ *  the record's position in the parsed array (for correlating with the source file). Additive — passing
+ *  `onWarning` is optional, and a new `kind` is an additive union member (a consumer with an exhaustive
+ *  `switch` gains an arm to write).
+ *   - `malformed-record`      — the record failed {@link isSchedulerRecord} and was dropped; `record` = the
+ *                               raw (unvalidated) value, for diagnostics.
+ *   - `durable-scope-rekeyed` — the durable-scope compat arm rewrote this row's `scope` (1.11.0; before that
+ *                               the rewrite happened silently every parse). */
 export type SchedulerParseWarning = {
     index: number;
     kind: 'malformed-record';
     record: unknown;
+} | {
+    index: number;
+    kind: 'durable-scope-rekeyed';
+    from: string;
+    to: string;
 };
 export declare function parseSchedulerStore(text: string, onWarning?: (w: SchedulerParseWarning) => void): SchedulerRecord[];
 /** Serialize the store to its canonical on-disk form (stable, pretty JSON). The WRITE half of the format contract. */

package/dist/scheduler-store.js

@@ -55,6 +55,11 @@ export function isSchedulerRecord(v) {
  *
  * 窄读判据:`lifetime` 不在本契约的显式键上(server 写侧作为 forward-compat 字段随行),按未知
  * 字段窄读——`"session"` 行是会话链键,零触碰;其余(缺席=durable 默认)按 durable 归一。
+ *
+ * 落日(1.11.0):删除它 = **持久数据**面的破坏(仍按旧键存着的 durable 行会就此找不回),所以不能在
+ * minor 上一删了事 —— 归下一个 MAJOR,按持久数据的规矩办(响亮拒收 + 一次性迁移)。在那之前,本版把
+ * 这次重写从**静默**改成**出声**(`durable-scope-rekeyed`,带改写前后):关窗的前提是有人能证明它
+ * 已经不再触发,而不是有人记得它还在。
  */
 function normalizeDurableScope(r) {
     if (r.lifetime === 'session')
@@ -76,10 +81,15 @@ export function parseSchedulerStore(text, onWarning) {
         return parsed.filter(isSchedulerRecord).map(normalizeDurableScope);
     const out = [];
     parsed.forEach((record, index) => {
-        if (isSchedulerRecord(record))
-            out.push(normalizeDurableScope(record));
-        else
+        if (!isSchedulerRecord(record)) {
             onWarning({ index, kind: 'malformed-record', record });
+            return;
+        }
+        const normalized = normalizeDurableScope(record);
+        // 兼容臂真改写了这一行才出声(未改写时 normalizeDurableScope 返回同一个引用)。
+        if (normalized !== record)
+            onWarning({ index, kind: 'durable-scope-rekeyed', from: record.scope, to: normalized.scope });
+        out.push(normalized);
     });
     return out;
 }

package/dist/skills-manifest.js

@@ -1,5 +1,5 @@
 /**
- * Skills content-addressing (docs/MCP-SKILLS.md §3.1, slice 2). The /effective payload ships skills as a
+ * Skills content-addressing (the mcp/skills design note §3.1, slice 2). The /effective payload ships skills as a
  * MANIFEST — each skill's markdown `content` replaced by a `contentHash` — so the frequent 60s refresh stays
  * small; the service pulls each body ONCE (at boot) via GET /api/config/skills/content/<hash>, caches it by
  * hash, and re-pulls only when the hash changes (skills rarely change → big win). Bodies are immutable +