@sema-agent/settings-schema 1.10.0 → 2.0.0

package/dist/cross-domain.js

@@ -1,7 +1,11 @@
 /** A resolver over the reader, optionally shadowed by pending (same-operation) writes keyed by domain.
  *  Widened from the fat ConfigStore to the narrow {@link ConfigReader} (it only calls `getDomain`) so a TOC
- *  file source can use it without the full store. */
-export function siblingResolver(store, pending) {
+ *  file source can use it without the full store.
+ *
+ *  1.11.0 renamed this from `siblingResolver` (BREAKING, zero aliases): the naming law is `build*` returns
+ *  plain DATA and `create*` returns a LIVE object — this returns a closure, so it was on the wrong side of
+ *  the line and carried neither prefix. A consumer's compile error IS the notice; the fix is the new name. */
+export function createSiblingResolver(store, pending) {
     return async (domain) => {
         if (pending && Object.prototype.hasOwnProperty.call(pending, domain))
             return pending[domain];

package/dist/fleet.d.ts

@@ -1,6 +1,6 @@
 /**
  * @sema-agent/settings-schema/fleet — the PURE scheduling/fleet contract for the sema-center control plane
- * (design: cc-parity CONTROL-PLANE-SCHEDULING-DESIGN.md, 产品拍板 2026-07-04 — "one contract, three orchestrators").
+ * (design: the cc-parity control-plane scheduling design note, 产品拍板 2026-07-04 — "one contract, three orchestrators").
  *
  * Seven domains (rolling update / discovery / traffic / failover / LB / quota / token governance) are ONE
  * data-plane lifecycle contract reused by three deployment forms — whoever HOLDS the engine handle orchestrates,

package/dist/fleet.js

@@ -1,6 +1,6 @@
 /**
  * @sema-agent/settings-schema/fleet — the PURE scheduling/fleet contract for the sema-center control plane
- * (design: cc-parity CONTROL-PLANE-SCHEDULING-DESIGN.md, 产品拍板 2026-07-04 — "one contract, three orchestrators").
+ * (design: the cc-parity control-plane scheduling design note, 产品拍板 2026-07-04 — "one contract, three orchestrators").
  *
  * Seven domains (rolling update / discovery / traffic / failover / LB / quota / token governance) are ONE
  * data-plane lifecycle contract reused by three deployment forms — whoever HOLDS the engine handle orchestrates,

package/dist/hooks.d.ts

@@ -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
@@ -27,14 +32,20 @@ import { z } from "zod";
 /** CC 2.1.198 full hook-event set (jP array) — 27 events. Order matches the shell's HOOK_EVENTS. */
 export declare const CC_198_HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "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 declare const POST_198_HOOK_EVENTS: readonly ["CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded"];
-/** The full 31-event contract set = CC 198's 27 + the 4 post-198 shell events. */
-export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded"];
-export declare const HookEventName: z.ZodEnum<["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded"]>;
+export declare const POST_198_HOOK_EVENTS: readonly ["CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded", "PreModelSwitch", "PostModelSwitch"];
+/** The full 33-event contract set = CC 198's 27 + the 6 post-198 events. */
+export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded", "PreModelSwitch", "PostModelSwitch"];
+export declare const HookEventName: z.ZodEnum<["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded", "PreModelSwitch", "PostModelSwitch"]>;
 export type HookEventName = z.infer<typeof HookEventName>;
 export declare const HookOwner: z.ZodEnum<["engine", "shell"]>;
 export type HookOwner = z.infer<typeof HookOwner>;
@@ -1263,8 +1274,8 @@ export declare const ElicitationHookInput: z.ZodObject<{
     transcript_path: string;
     cwd: string;
     hook_event_name: "Elicitation";
-    mode?: "url" | "form" | undefined;
     url?: string | undefined;
+    mode?: "url" | "form" | undefined;
     agent_type?: string | undefined;
     permission_mode?: string | undefined;
     agent_id?: string | undefined;
@@ -1277,8 +1288,8 @@ export declare const ElicitationHookInput: z.ZodObject<{
     transcript_path: string;
     cwd: string;
     hook_event_name: "Elicitation";
-    mode?: "url" | "form" | undefined;
     url?: string | undefined;
+    mode?: "url" | "form" | undefined;
     agent_type?: string | undefined;
     permission_mode?: string | undefined;
     agent_id?: string | undefined;
@@ -1309,8 +1320,8 @@ export declare const ElicitationResultHookInput: z.ZodObject<{
     cwd: string;
     hook_event_name: "ElicitationResult";
     action: "accept" | "decline" | "cancel";
-    mode?: "url" | "form" | undefined;
     content?: Record<string, unknown> | undefined;
+    mode?: "url" | "form" | undefined;
     agent_type?: string | undefined;
     permission_mode?: string | undefined;
     agent_id?: string | undefined;
@@ -1322,8 +1333,8 @@ export declare const ElicitationResultHookInput: z.ZodObject<{
     cwd: string;
     hook_event_name: "ElicitationResult";
     action: "accept" | "decline" | "cancel";
-    mode?: "url" | "form" | undefined;
     content?: Record<string, unknown> | undefined;
+    mode?: "url" | "form" | undefined;
     agent_type?: string | undefined;
     permission_mode?: string | undefined;
     agent_id?: string | undefined;
@@ -1631,7 +1642,132 @@ export declare const DirectoryAddedHookInput: z.ZodObject<{
     agent_id?: string | undefined;
 }>;
 export type DirectoryAddedHookInput = z.infer<typeof DirectoryAddedHookInput>;
-/** 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 declare const MODEL_SWITCH_SOURCES: {
+    readonly pre: readonly ["command", "picker", "sdk"];
+    readonly post: readonly ["command", "picker", "sdk", "auto", "resume"];
+};
+/** 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 declare const PreModelSwitchHookInput: z.ZodObject<{
+    session_id: z.ZodString;
+    transcript_path: z.ZodString;
+    cwd: z.ZodString;
+    permission_mode: z.ZodOptional<z.ZodString>;
+    /** Subagent id — present only when the hook fires from within a subagent. */
+    agent_id: z.ZodOptional<z.ZodString>;
+    /** Agent type name (e.g. "general-purpose") — present alongside agent_id, or on --agent main threads. */
+    agent_type: z.ZodOptional<z.ZodString>;
+} & {
+    source: z.ZodEnum<["command", "picker", "sdk"]>;
+    from_model: z.ZodString;
+    to_model: z.ZodString;
+    requested_model: z.ZodNullable<z.ZodString>;
+    context_tokens: z.ZodNumber;
+    prompt_cache_warm: z.ZodBoolean;
+    cache_ttl: z.ZodEnum<["5m", "1h"]>;
+    estimated_cache_write_usd: z.ZodNumber;
+    pricing: z.ZodEnum<["configured", "catalog", "default"]>;
+    hook_event_name: z.ZodLiteral<"PreModelSwitch">;
+}, "strip", z.ZodTypeAny, {
+    source: "command" | "picker" | "sdk";
+    to_model: string;
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: "PreModelSwitch";
+    from_model: string;
+    requested_model: string | null;
+    context_tokens: number;
+    prompt_cache_warm: boolean;
+    cache_ttl: "5m" | "1h";
+    estimated_cache_write_usd: number;
+    pricing: "default" | "catalog" | "configured";
+    agent_type?: string | undefined;
+    permission_mode?: string | undefined;
+    agent_id?: string | undefined;
+}, {
+    source: "command" | "picker" | "sdk";
+    to_model: string;
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: "PreModelSwitch";
+    from_model: string;
+    requested_model: string | null;
+    context_tokens: number;
+    prompt_cache_warm: boolean;
+    cache_ttl: "5m" | "1h";
+    estimated_cache_write_usd: number;
+    pricing: "default" | "catalog" | "configured";
+    agent_type?: string | undefined;
+    permission_mode?: string | undefined;
+    agent_id?: string | undefined;
+}>;
+export type PreModelSwitchHookInput = z.infer<typeof PreModelSwitchHookInput>;
+/** Fires AFTER the session model changed, whatever the cause (informational; may add context). */
+export declare const PostModelSwitchHookInput: z.ZodObject<{
+    session_id: z.ZodString;
+    transcript_path: z.ZodString;
+    cwd: z.ZodString;
+    permission_mode: z.ZodOptional<z.ZodString>;
+    /** Subagent id — present only when the hook fires from within a subagent. */
+    agent_id: z.ZodOptional<z.ZodString>;
+    /** Agent type name (e.g. "general-purpose") — present alongside agent_id, or on --agent main threads. */
+    agent_type: z.ZodOptional<z.ZodString>;
+} & {
+    source: z.ZodEnum<["command", "picker", "sdk", "auto", "resume"]>;
+    from_model: z.ZodString;
+    to_model: z.ZodString;
+    requested_model: z.ZodNullable<z.ZodString>;
+    context_tokens: z.ZodNumber;
+    prompt_cache_warm: z.ZodBoolean;
+    cache_ttl: z.ZodEnum<["5m", "1h"]>;
+    estimated_cache_write_usd: z.ZodNumber;
+    pricing: z.ZodEnum<["configured", "catalog", "default"]>;
+    hook_event_name: z.ZodLiteral<"PostModelSwitch">;
+}, "strip", z.ZodTypeAny, {
+    source: "command" | "auto" | "resume" | "picker" | "sdk";
+    to_model: string;
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: "PostModelSwitch";
+    from_model: string;
+    requested_model: string | null;
+    context_tokens: number;
+    prompt_cache_warm: boolean;
+    cache_ttl: "5m" | "1h";
+    estimated_cache_write_usd: number;
+    pricing: "default" | "catalog" | "configured";
+    agent_type?: string | undefined;
+    permission_mode?: string | undefined;
+    agent_id?: string | undefined;
+}, {
+    source: "command" | "auto" | "resume" | "picker" | "sdk";
+    to_model: string;
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: "PostModelSwitch";
+    from_model: string;
+    requested_model: string | null;
+    context_tokens: number;
+    prompt_cache_warm: boolean;
+    cache_ttl: "5m" | "1h";
+    estimated_cache_write_usd: number;
+    pricing: "default" | "catalog" | "configured";
+    agent_type?: string | undefined;
+    permission_mode?: string | undefined;
+    agent_id?: string | undefined;
+}>;
+export type PostModelSwitchHookInput = z.infer<typeof PostModelSwitchHookInput>;
+/** Any hook input — discriminated on `hook_event_name` (all 33 events). */
 export declare const HookInput: z.ZodDiscriminatedUnion<"hook_event_name", [z.ZodObject<{
     session_id: z.ZodString;
     transcript_path: z.ZodString;
@@ -2616,8 +2752,8 @@ export declare const HookInput: z.ZodDiscriminatedUnion<"hook_event_name", [z.Zo
     transcript_path: string;
     cwd: string;
     hook_event_name: "Elicitation";
-    mode?: "url" | "form" | undefined;
     url?: string | undefined;
+    mode?: "url" | "form" | undefined;
     agent_type?: string | undefined;
     permission_mode?: string | undefined;
     agent_id?: string | undefined;
@@ -2630,8 +2766,8 @@ export declare const HookInput: z.ZodDiscriminatedUnion<"hook_event_name", [z.Zo
     transcript_path: string;
     cwd: string;
     hook_event_name: "Elicitation";
-    mode?: "url" | "form" | undefined;
     url?: string | undefined;
+    mode?: "url" | "form" | undefined;
     agent_type?: string | undefined;
     permission_mode?: string | undefined;
     agent_id?: string | undefined;
@@ -2660,8 +2796,8 @@ export declare const HookInput: z.ZodDiscriminatedUnion<"hook_event_name", [z.Zo
     cwd: string;
     hook_event_name: "ElicitationResult";
     action: "accept" | "decline" | "cancel";
-    mode?: "url" | "form" | undefined;
     content?: Record<string, unknown> | undefined;
+    mode?: "url" | "form" | undefined;
     agent_type?: string | undefined;
     permission_mode?: string | undefined;
     agent_id?: string | undefined;
@@ -2673,8 +2809,8 @@ export declare const HookInput: z.ZodDiscriminatedUnion<"hook_event_name", [z.Zo
     cwd: string;
     hook_event_name: "ElicitationResult";
     action: "accept" | "decline" | "cancel";
-    mode?: "url" | "form" | undefined;
     content?: Record<string, unknown> | undefined;
+    mode?: "url" | "form" | undefined;
     agent_type?: string | undefined;
     permission_mode?: string | undefined;
     agent_id?: string | undefined;
@@ -2962,6 +3098,114 @@ export declare const HookInput: z.ZodDiscriminatedUnion<"hook_event_name", [z.Zo
     agent_type?: string | undefined;
     permission_mode?: string | undefined;
     agent_id?: string | undefined;
+}>, z.ZodObject<{
+    session_id: z.ZodString;
+    transcript_path: z.ZodString;
+    cwd: z.ZodString;
+    permission_mode: z.ZodOptional<z.ZodString>;
+    /** Subagent id — present only when the hook fires from within a subagent. */
+    agent_id: z.ZodOptional<z.ZodString>;
+    /** Agent type name (e.g. "general-purpose") — present alongside agent_id, or on --agent main threads. */
+    agent_type: z.ZodOptional<z.ZodString>;
+} & {
+    source: z.ZodEnum<["command", "picker", "sdk"]>;
+    from_model: z.ZodString;
+    to_model: z.ZodString;
+    requested_model: z.ZodNullable<z.ZodString>;
+    context_tokens: z.ZodNumber;
+    prompt_cache_warm: z.ZodBoolean;
+    cache_ttl: z.ZodEnum<["5m", "1h"]>;
+    estimated_cache_write_usd: z.ZodNumber;
+    pricing: z.ZodEnum<["configured", "catalog", "default"]>;
+    hook_event_name: z.ZodLiteral<"PreModelSwitch">;
+}, "strip", z.ZodTypeAny, {
+    source: "command" | "picker" | "sdk";
+    to_model: string;
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: "PreModelSwitch";
+    from_model: string;
+    requested_model: string | null;
+    context_tokens: number;
+    prompt_cache_warm: boolean;
+    cache_ttl: "5m" | "1h";
+    estimated_cache_write_usd: number;
+    pricing: "default" | "catalog" | "configured";
+    agent_type?: string | undefined;
+    permission_mode?: string | undefined;
+    agent_id?: string | undefined;
+}, {
+    source: "command" | "picker" | "sdk";
+    to_model: string;
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: "PreModelSwitch";
+    from_model: string;
+    requested_model: string | null;
+    context_tokens: number;
+    prompt_cache_warm: boolean;
+    cache_ttl: "5m" | "1h";
+    estimated_cache_write_usd: number;
+    pricing: "default" | "catalog" | "configured";
+    agent_type?: string | undefined;
+    permission_mode?: string | undefined;
+    agent_id?: string | undefined;
+}>, z.ZodObject<{
+    session_id: z.ZodString;
+    transcript_path: z.ZodString;
+    cwd: z.ZodString;
+    permission_mode: z.ZodOptional<z.ZodString>;
+    /** Subagent id — present only when the hook fires from within a subagent. */
+    agent_id: z.ZodOptional<z.ZodString>;
+    /** Agent type name (e.g. "general-purpose") — present alongside agent_id, or on --agent main threads. */
+    agent_type: z.ZodOptional<z.ZodString>;
+} & {
+    source: z.ZodEnum<["command", "picker", "sdk", "auto", "resume"]>;
+    from_model: z.ZodString;
+    to_model: z.ZodString;
+    requested_model: z.ZodNullable<z.ZodString>;
+    context_tokens: z.ZodNumber;
+    prompt_cache_warm: z.ZodBoolean;
+    cache_ttl: z.ZodEnum<["5m", "1h"]>;
+    estimated_cache_write_usd: z.ZodNumber;
+    pricing: z.ZodEnum<["configured", "catalog", "default"]>;
+    hook_event_name: z.ZodLiteral<"PostModelSwitch">;
+}, "strip", z.ZodTypeAny, {
+    source: "command" | "auto" | "resume" | "picker" | "sdk";
+    to_model: string;
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: "PostModelSwitch";
+    from_model: string;
+    requested_model: string | null;
+    context_tokens: number;
+    prompt_cache_warm: boolean;
+    cache_ttl: "5m" | "1h";
+    estimated_cache_write_usd: number;
+    pricing: "default" | "catalog" | "configured";
+    agent_type?: string | undefined;
+    permission_mode?: string | undefined;
+    agent_id?: string | undefined;
+}, {
+    source: "command" | "auto" | "resume" | "picker" | "sdk";
+    to_model: string;
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: "PostModelSwitch";
+    from_model: string;
+    requested_model: string | null;
+    context_tokens: number;
+    prompt_cache_warm: boolean;
+    cache_ttl: "5m" | "1h";
+    estimated_cache_write_usd: number;
+    pricing: "default" | "catalog" | "configured";
+    agent_type?: string | undefined;
+    permission_mode?: string | undefined;
+    agent_id?: string | undefined;
 }>]>;
 export type HookInput = z.infer<typeof HookInput>;
 /** Legacy top-level decision (CC): "approve" ≈ allow, "block" feeds `reason` back to the model. */
@@ -3666,6 +3910,30 @@ export declare const HookSpecificOutput: z.ZodUnion<[z.ZodObject<{
 }, {
     hookEventName: "WorktreeCreate";
     worktreePath: string;
+}>, z.ZodObject<{
+    hookEventName: z.ZodLiteral<"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: z.ZodOptional<z.ZodEnum<["allow", "deny", "ask"]>>;
+    permissionDecisionReason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    hookEventName: "PreModelSwitch";
+    permissionDecision?: "ask" | "allow" | "deny" | undefined;
+    permissionDecisionReason?: string | undefined;
+}, {
+    hookEventName: "PreModelSwitch";
+    permissionDecision?: "ask" | "allow" | "deny" | undefined;
+    permissionDecisionReason?: string | undefined;
+}>, z.ZodObject<{
+    hookEventName: z.ZodLiteral<"PostModelSwitch">;
+    additionalContext: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    hookEventName: "PostModelSwitch";
+    additionalContext?: string | undefined;
+}, {
+    hookEventName: "PostModelSwitch";
+    additionalContext?: string | undefined;
 }>]>;
 export type HookSpecificOutput = z.infer<typeof HookSpecificOutput>;
 /**
@@ -4163,6 +4431,30 @@ export declare const SyncHookOutput: z.ZodObject<{
     }, {
         hookEventName: "WorktreeCreate";
         worktreePath: string;
+    }>, z.ZodObject<{
+        hookEventName: z.ZodLiteral<"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: z.ZodOptional<z.ZodEnum<["allow", "deny", "ask"]>>;
+        permissionDecisionReason: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        hookEventName: "PreModelSwitch";
+        permissionDecision?: "ask" | "allow" | "deny" | undefined;
+        permissionDecisionReason?: string | undefined;
+    }, {
+        hookEventName: "PreModelSwitch";
+        permissionDecision?: "ask" | "allow" | "deny" | undefined;
+        permissionDecisionReason?: string | undefined;
+    }>, z.ZodObject<{
+        hookEventName: z.ZodLiteral<"PostModelSwitch">;
+        additionalContext: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        hookEventName: "PostModelSwitch";
+        additionalContext?: string | undefined;
+    }, {
+        hookEventName: "PostModelSwitch";
+        additionalContext?: string | undefined;
     }>]>>;
 }, "strip", z.ZodTypeAny, {
     reason?: string | undefined;
@@ -4268,6 +4560,13 @@ export declare const SyncHookOutput: z.ZodObject<{
     } | {
         hookEventName: "WorktreeCreate";
         worktreePath: string;
+    } | {
+        hookEventName: "PreModelSwitch";
+        permissionDecision?: "ask" | "allow" | "deny" | undefined;
+        permissionDecisionReason?: string | undefined;
+    } | {
+        hookEventName: "PostModelSwitch";
+        additionalContext?: string | undefined;
     } | undefined;
 }, {
     reason?: string | undefined;
@@ -4373,6 +4672,13 @@ export declare const SyncHookOutput: z.ZodObject<{
     } | {
         hookEventName: "WorktreeCreate";
         worktreePath: string;
+    } | {
+        hookEventName: "PreModelSwitch";
+        permissionDecision?: "ask" | "allow" | "deny" | undefined;
+        permissionDecisionReason?: string | undefined;
+    } | {
+        hookEventName: "PostModelSwitch";
+        additionalContext?: string | undefined;
     } | undefined;
 }>;
 export type SyncHookOutput = z.infer<typeof SyncHookOutput>;
@@ -4882,6 +5188,30 @@ export declare const HookOutput: z.ZodUnion<[z.ZodObject<{
     }, {
         hookEventName: "WorktreeCreate";
         worktreePath: string;
+    }>, z.ZodObject<{
+        hookEventName: z.ZodLiteral<"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: z.ZodOptional<z.ZodEnum<["allow", "deny", "ask"]>>;
+        permissionDecisionReason: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        hookEventName: "PreModelSwitch";
+        permissionDecision?: "ask" | "allow" | "deny" | undefined;
+        permissionDecisionReason?: string | undefined;
+    }, {
+        hookEventName: "PreModelSwitch";
+        permissionDecision?: "ask" | "allow" | "deny" | undefined;
+        permissionDecisionReason?: string | undefined;
+    }>, z.ZodObject<{
+        hookEventName: z.ZodLiteral<"PostModelSwitch">;
+        additionalContext: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        hookEventName: "PostModelSwitch";
+        additionalContext?: string | undefined;
+    }, {
+        hookEventName: "PostModelSwitch";
+        additionalContext?: string | undefined;
     }>]>>;
 }, "strip", z.ZodTypeAny, {
     reason?: string | undefined;
@@ -4987,6 +5317,13 @@ export declare const HookOutput: z.ZodUnion<[z.ZodObject<{
     } | {
         hookEventName: "WorktreeCreate";
         worktreePath: string;
+    } | {
+        hookEventName: "PreModelSwitch";
+        permissionDecision?: "ask" | "allow" | "deny" | undefined;
+        permissionDecisionReason?: string | undefined;
+    } | {
+        hookEventName: "PostModelSwitch";
+        additionalContext?: string | undefined;
     } | undefined;
 }, {
     reason?: string | undefined;
@@ -5092,6 +5429,13 @@ export declare const HookOutput: z.ZodUnion<[z.ZodObject<{
     } | {
         hookEventName: "WorktreeCreate";
         worktreePath: string;
+    } | {
+        hookEventName: "PreModelSwitch";
+        permissionDecision?: "ask" | "allow" | "deny" | undefined;
+        permissionDecisionReason?: string | undefined;
+    } | {
+        hookEventName: "PostModelSwitch";
+        additionalContext?: string | undefined;
     } | undefined;
 }>]>;
 export type HookOutput = z.infer<typeof HookOutput>;
@@ -5525,8 +5869,12 @@ export declare const HookMatcherEntry: z.ZodObject<{
 export type HookMatcherEntry = z.infer<typeof HookMatcherEntry>;
 /**
  * The hooks config record — the shape `TaskRequest.settings.hooks` carries on the wire and the shell
- * reads from settings JSON: `{ [eventName]: [{ matcher?, hooks: [...] }] }`. Keys limited to the 31
+ * reads from settings JSON: `{ [eventName]: [{ matcher?, hooks: [...] }] }`. Keys limited to the 33
  * contract events (an unknown event name fails parse — catch typos at the wire); all keys optional.
+ *
+ * 🔴 The closed set is what makes a typo loud, and it is ALSO what makes falling behind CC expensive: an
+ * event this package has not adopted yet takes the WHOLE settings file down with it, not just its own key.
+ * That blast radius is why {@link HOOK_EVENTS} now has an upstream drift gate rather than a human promise.
  */
 export type HooksConfig = Partial<Record<HookEventName, HookMatcherEntry[]>>;
 export declare const HooksConfig: z.ZodType<HooksConfig>;