@sema-agent/core 5.36.0 → 5.38.0

package/dist/core/runner/runtask.js

@@ -1,5 +1,6 @@
 import { persistedReadDenyEntryProblem } from "../../tools/fs/read-deny.js";
 import { createSafeNotifier, observeThenableRejection } from "../safe-notify.js";
+import { deliverDelegationLifecycle } from "../types.js";
 import { AgentHarness, DEFAULT_COMPACTION_SETTINGS, uuidv7 } from "../../internal/harness.js";
 import { snapshotActorAssertion } from "../../internal/llm.js";
 import { CheckpointError, BINDING_CHECKPOINT_VERSION, checkpointVersionOf, F012_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, remainingBudgetMicroUsd, readPendingSteerQueue, remainingTokens, LEGACY_PENDING_STEER_INPUT_ID, MAX_STEER_INPUT_ID_CHARS, validatePendingSteer, winnerFromOutcome, } from "../checkpoint-store.js";
@@ -757,7 +758,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
             const injectedThisTurn = finalVerifyInjectedThisTurn ? "final_verification" : undefined;
             if (!boundarySteered && !prepared.abortController.signal.aborted) {
                 try {
-                    const r = await postToolBatchHook(batch, injectedThisTurn !== undefined ? { injectedThisTurn } : undefined);
+                    const r = await postToolBatchHook(batch, injectedThisTurn !== undefined ? { injectedThisTurn } : undefined, { identity: prepared.hookIdentity });
                     if (r?.additionalContext && injectedThisTurn === undefined) {
                         const body = sanitizeUntrustedText(r.additionalContext);
                         const budget = ATTACHMENT_BYTE_CAP - boundaryAttachmentBytes;
@@ -1484,12 +1485,12 @@ export class Runner {
                 ...(typeof h.preToolUse === "function" ? { preToolUse: (t, i, c) => h.preToolUse(t, i, c) } : {}),
                 ...(typeof h.preToolUse === "function" && h.preToolUseObservational === true ? { preToolUseObservational: true } : {}),
                 ...(typeof h.postToolUse === "function" ? { postToolUse: (t, i, o, c) => h.postToolUse(t, i, o, c) } : {}),
-                ...(typeof h.userPromptSubmit === "function" ? { userPromptSubmit: (p) => h.userPromptSubmit(p) } : {}),
+                ...(typeof h.userPromptSubmit === "function" ? { userPromptSubmit: (p, c) => h.userPromptSubmit(p, c) } : {}),
                 ...(typeof h.stop === "function" ? { stop: (c) => h.stop(c) } : {}),
                 ...(typeof h.postToolUseFailure === "function"
                     ? { postToolUseFailure: (t, i, f, c) => h.postToolUseFailure(t, i, f, c) }
                     : {}),
-                ...(typeof h.postToolBatch === "function" ? { postToolBatch: (b) => h.postToolBatch(b) } : {}),
+                ...(typeof h.postToolBatch === "function" ? { postToolBatch: (b, m, c) => h.postToolBatch(b, m, c) } : {}),
                 ...(typeof h.preCompact === "function" ? { preCompact: (c) => h.preCompact(c) } : {}),
                 ...(typeof h.postCompact === "function" ? { postCompact: (c) => h.postCompact(c) } : {}),
                 ...(typeof h.stopFailure === "function" ? { stopFailure: (c) => h.stopFailure(c) } : {}),
@@ -1659,6 +1660,7 @@ export class Runner {
                 errorMessage: err instanceof Error ? err.message : String(err),
                 errorCode: code,
                 ...(remoteEnvFailure !== undefined ? { remoteEnvFailures: remoteEnvFailure } : {}),
+                ...(taskIdRef.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: taskIdRef.effectiveMemoryScopes } : {}),
                 ...(() => {
                     const hinted = err.retryAfterMs;
                     return code === "memory.admission_required" && typeof hinted === "number" && Number.isFinite(hinted) && hinted > 0
@@ -1678,6 +1680,13 @@ export class Runner {
                 durationMs: Date.now() - runStartedAt,
                 ts: Date.now(),
             }));
+            const owedTerminal = taskIdRef.delegationTerminalOwed;
+            if (owedTerminal !== undefined) {
+                taskIdRef.delegationTerminalOwed = undefined;
+                deliverDelegationLifecycle(this.deps.onDelegationLifecycle, { phase: "terminal", identity: owedTerminal, status: "failed", turns: 0, ...(code !== undefined ? { errorCode: code } : {}) }, createSafeNotifier({
+                    onError: (f) => console.warn(`[sema-core] ${f.site}: delegation-lifecycle observer threw (contained; further failures counted, not re-disclosed): ${f.error.message}`),
+                }), "runtask.onDelegationLifecycle");
+            }
             queue.push({ type: "done", result: resultValue });
             queue.close();
         });
@@ -2029,11 +2038,27 @@ export class Runner {
         }, this);
         notificationHarness = prepared.harness;
         notificationSessionId = prepared.sessionId;
+        if (taskIdRef)
+            taskIdRef.effectiveMemoryScopes = prepared.effectiveMemoryScopes;
         const runSourceTaskId = spec.taskId ?? prepared.sessionId;
         const parentToolCallId = internals?.parentToolCallId;
         const ident = () => parentToolCallId !== undefined ? { eventId: uuidv7(), parentToolCallId, sourceTaskId: runSourceTaskId } : { eventId: uuidv7() };
         notificationIdent = ident;
         queue.push({ type: "wiring_manifest", manifest: prepared.wiringManifest, ...ident() });
+        const delegationLifecycleNotifier = createSafeNotifier({
+            onError: (f) => console.warn(`[sema-core] ${f.site}: delegation-lifecycle observer threw (contained; further failures counted, not re-disclosed): ${f.error.message}`),
+        });
+        const emitDelegationLifecycle = (event) => {
+            if (!prepared.hookIdentity.isDelegatedChild)
+                return;
+            if (this.deps.onDelegationLifecycle === undefined)
+                return;
+            deliverDelegationLifecycle(this.deps.onDelegationLifecycle, event, delegationLifecycleNotifier, "runtask.onDelegationLifecycle");
+        };
+        emitDelegationLifecycle({ phase: "spawn", identity: prepared.hookIdentity });
+        if (taskIdRef !== undefined && prepared.hookIdentity.isDelegatedChild && this.deps.onDelegationLifecycle !== undefined) {
+            taskIdRef.delegationTerminalOwed = prepared.hookIdentity;
+        }
         manualCompactRef.emitMooted = (reason) => {
             queue.push({ type: "compaction_outcome", outcome: "mooted", trigger: "manual", reason, ...ident() });
         };
@@ -2726,6 +2751,7 @@ export class Runner {
                         stopHookActive: consecutiveBlocks > 0,
                         consecutiveBlocks,
                         getBranch: () => prepared.session.getBranch(),
+                        identity: prepared.hookIdentity,
                     });
                 }
                 catch (err) {
@@ -2801,7 +2827,7 @@ export class Runner {
                             ...this.seamCCompactionOptions(prepared),
                             ...gitRestateOption(prepared),
                             ...windowSafetyOptions(prepared.harness.getModel()),
-                            ...this.compactionHookOptions(spec, prepared.sessionId, "forced"),
+                            ...this.compactionHookOptions(spec, prepared.sessionId, "forced", prepared.hookIdentity),
                         });
                         if (comp.compacted) {
                             compactionBreaker.failures = 0;
@@ -2866,7 +2892,7 @@ export class Runner {
             runnerHooks: {
                 onError: this.deps.onError,
                 seamCCompactionOptions: (p) => this.seamCCompactionOptions(p),
-                compactionHookOptions: (s, sid, trig) => this.compactionHookOptions(s, sid, trig),
+                compactionHookOptions: (s, sid, trig) => this.compactionHookOptions(s, sid, trig, prepared.hookIdentity),
                 recordCompactionReuse: (p, c) => this.recordCompactionReuse(p, c),
             },
         });
@@ -3096,7 +3122,7 @@ export class Runner {
                 const userPromptSubmit = (spec.hooks ?? this.deps.hooks)?.userPromptSubmit;
                 if (userPromptSubmit) {
                     try {
-                        const decision = await userPromptSubmit(spec.objective);
+                        const decision = await userPromptSubmit(spec.objective, { identity: prepared.hookIdentity });
                         if (decision?.block) {
                             prepared.blockedRef.reason = formatHookFeedback(decision.block);
                             promptBlocked = true;
@@ -3426,6 +3452,7 @@ export class Runner {
                 remoteEnvFailures: prepared.remoteEnvFailures,
                 effectiveReadFace: prepared.effectiveReadFace,
                 effectiveReadDenyPatterns: prepared.effectiveReadDenyPatterns,
+                effectiveMemoryScopes: prepared.effectiveMemoryScopes,
                 retryAfterMs: rs.limits.platformTerminal?.retryAfterMs,
                 abortedForTimeout: timeout.fired,
                 abortedForTurns: rs.limits.turnsExceeded,
@@ -3499,6 +3526,7 @@ export class Runner {
                 result.errorCode !== "conflict") {
                 try {
                     await stopFailureHook({
+                        identity: prepared.hookIdentity,
                         error: result.errorMessage ?? "model error",
                         ...(result.errorCode !== undefined ? { errorKind: result.errorCode } : {}),
                         turns: stats.turns,
@@ -3512,6 +3540,15 @@ export class Runner {
                     }
                 }
             }
+            emitDelegationLifecycle({
+                phase: "terminal",
+                identity: prepared.hookIdentity,
+                status: result.status,
+                turns: stats.turns,
+                ...(result.errorCode !== undefined ? { errorCode: result.errorCode } : {}),
+            });
+            if (taskIdRef !== undefined)
+                taskIdRef.delegationTerminalOwed = undefined;
             if (rs.degrade.degraded)
                 result.degraded = rs.degrade.degraded;
             if (prepared.outputRef.set)
@@ -4499,15 +4536,17 @@ export class Runner {
             consecutiveProviderReuse: prepared.compactionReuseRef.consecutive,
         };
     }
-    compactionHookOptions(spec, sessionId, trigger) {
+    compactionHookOptions(spec, sessionId, trigger, identity) {
         const hooks = spec.hooks ?? this.deps.hooks;
         const pre = hooks?.preCompact;
         const post = hooks?.postCompact;
+        const withIdentity = (ctx) => identity !== undefined ? { ...ctx, identity } : ctx;
         return {
             trigger,
             ...(pre
                 ? {
-                    preCompact: async (ctx) => {
+                    preCompact: async (rawCtx) => {
+                        const ctx = withIdentity(rawCtx);
                         const report = (err) => {
                             try {
                                 this.deps.onError?.(err, { phase: "hook", sessionId });
@@ -4531,9 +4570,9 @@ export class Runner {
                 : {}),
             ...(post
                 ? {
-                    postCompact: async (ctx) => {
+                    postCompact: async (rawCtx) => {
                         try {
-                            await post.call(hooks, ctx);
+                            await post.call(hooks, withIdentity(rawCtx));
                         }
                         catch (err) {
                             try {
@@ -4577,7 +4616,7 @@ export class Runner {
                     ...(prepared.onCompactionApplied ? { onApplied: prepared.onCompactionApplied } : {}),
                     ...this.seamCCompactionOptions(prepared),
                     ...gitRestateOption(prepared),
-                    ...this.compactionHookOptions(spec, prepared.sessionId, "auto"),
+                    ...this.compactionHookOptions(spec, prepared.sessionId, "auto", prepared.hookIdentity),
                 });
                 this.recordCompactionReuse(prepared, finishComp);
                 if (finishComp.unevaluableWindow) {

package/dist/core/tool-model-gate.d.ts

@@ -0,0 +1,125 @@
+/**
+ * design/277 — the tool-registration MODEL GATE (CC 233 counterpart, first formalized there as a
+ * family+version-floor table over the todo/task-board tool family).
+ *
+ * WHAT THE GATE IS: a DEFAULT-MOUNT trim, never a capability ban. A {@link ToolSpec.modelGate}
+ * tag declares "this entry is a default-mounted scaffold of the named class"; when the task's
+ * RESOLVED model id matches the class's rule below, that entry is dropped from the roster at
+ * prepare (true unmount — the schema never reaches `tools[]`). An EXPLICITLY composed tool is
+ * never tagged (the bundle only stamps its default arms), so "the user asked for it" is the
+ * first restore channel by construction. Restore channels beyond that:
+ * `TaskSpec.restoreGatedTools` (per task-tree), env `SEMA_TOOL_MODEL_GATE=off` (process),
+ * `RunnerDeps.toolModelGate: false` (deployment).
+ *
+ * FAIL-OPEN, BY CONTRACT (not by accident): sema is BYOM — model ids are an OPEN set, and this
+ * table encodes POSITIVE knowledge ("this family at this version and above manages multi-step
+ * work without the scaffold"). An id the table knows nothing about (deepseek-* / gpt-* / qwen-* / any
+ * custom name) is NOT gated: no knowledge ⇒ no trim ⇒ tool stays. The matcher's three pass-through
+ * edges (family absent, id shape unmatched, version below floor) all point the same way, and it is
+ * the only polarity compatible with BYOM — the reverse would trim every non-claude deployment's
+ * default face. The engine does NOT guarantee a canonical id either: a deployment-authored
+ * `Model.id` (a raw Model object, or a catalog key shadowing the tier expansion) that is not in
+ * canonical `claude-<family>-<version>` shape simply falls off the regex and stays open — the
+ * explicit-id discipline's deployment-side duty. To gate a non-claude strong model, write the
+ * exact id into a {@link ToolModelGateRule.modelIds} row (the only non-claude channel; no prefix
+ * or wildcard syntax exists).
+ *
+ * DIVERGENCE (registered, deliberate): CC judges the MAIN-LOOP canonical model once per process;
+ * sema judges the PER-TASK resolved model on every prepare — BYOM per-task models are first-class,
+ * so a delegated child on a different model re-judges under its own (strong parent / weak child ⇒
+ * the child gets the scaffold back). And the env valve's polarity is reversed (CC: enable the
+ * tools; sema: disable the GATE) because sema's class vocabulary is open — a per-family enable
+ * env would have to grow with every class.
+ */
+import type { ToolSpec } from "./types.js";
+/** The shared tail extractor (BYOM ids may carry provider prefixes — "openrouter/anthropic/claude-fable-5"):
+ *  boundary-aware LAST path segment, case-folded. Single source for every model-family/model-id
+ *  comparison site (`isFableFamilyModelId` consumes it too — the prompt-shape axis, semantically
+ *  independent but sharing the one tail-extraction posture). */
+export declare function modelIdTail(id: string): string;
+/** One gate class's matching rule (both axes optional; a rule with BOTH axes empty gates nothing —
+ *  the per-class OFF shape a deployment reaches by explicitly clearing the axes). */
+export interface ToolModelGateRule {
+    /** claude-syntax family+floor rows — meaningful only for ids whose TAIL SEGMENT matches
+     *  `claude-<letters>-<digits(-digits)*>`. Version tuples compare positionally, missing positions
+     *  read 0, tuple ≥ floor ⇒ gated (CC 233 comparator, verbatim semantics). Any other id shape
+     *  falls through this axis entirely (fail-open). */
+    floors?: ReadonlyArray<readonly [family: string, floor: ReadonlyArray<number>]>;
+    /** Exact-id rows (explicit-id discipline): the resolved `Model.id`'s tail segment must equal the
+     *  row case-insensitively. The ONLY channel by which a BYOM deployment gates its own non-claude
+     *  strong model — deliberately no prefix/wildcard syntax (a substring guess against an open id
+     *  set is how the `deepseek-chat` alias downgrade class of accident happens). */
+    modelIds?: ReadonlyArray<string>;
+}
+/**
+ * The built-in gate table: gate-class → rule. CC 233 z_S floors, verbatim (evidence D2; the
+ * `mythos` row rides per the anchor). v1 vocabulary = ONE class, `"task-scaffold"` — the
+ * TodoWrite/TaskCreate/TaskGet/TaskUpdate/TaskList default bundle (`assembleCodeTools`). One class
+ * is evidence discipline, not mechanism limit: a family enters this table only with positive
+ * "strong models don't need it" evidence (a CC anchor or deployment measurement); classes are an
+ * open vocabulary and a deployment adds its own via `RunnerDeps.toolModelGate.classes`.
+ */
+export declare const TOOL_MODEL_GATE_CLASSES: Readonly<Record<string, ToolModelGateRule>>;
+/**
+ * Pure matcher: is `modelId` gated under `rule`? Every unmatched shape returns `false` (the
+ * fail-open contract in the module header). Exported for deployment pre-flight ("would my model
+ * lose the scaffold?") — the engine's own decision point calls this same function.
+ */
+export declare function isModelGatedForClass(modelId: string, rule: ToolModelGateRule): boolean;
+/**
+ * #123 value screen for `TaskSpec.restoreGatedTools` (same posture as `assertReadFaceValue`: the
+ * VALUE is screened at the door, unconditionally — a garbage restore list must refuse loudly on
+ * every leg, never be silently read as "no restore" in the narrowing direction). Legal: absent,
+ * literal `true` (restore every class), or an array of strings (wire names; unknown names are
+ * inert by contract, like `excludeTools`).
+ */
+export declare function assertRestoreGatedToolsValue(value: unknown): asserts value is true | readonly string[] | undefined;
+/** Doors-facing decision (built + applied inside `prepareConfigDoors`' synchronous stretch —
+ *  decision and application share one atomic window, no drift gap). */
+export interface ToolModelGateDecision {
+    /** Present ⇔ at least one entry was removed: the fresh, PRIVATE survivor array `spec.tools` is
+     *  rebound to (a caller mutating its original live array afterwards can neither re-add a removed
+     *  entry nor displace anything — there are no indices left to misalign). `undefined` = no
+     *  removal, the spec is left untouched. */
+    survivors: ToolSpec[] | undefined;
+    /** gate-class → removed wire names (sorted, unique) — the removal-notice payload. */
+    removedByClass: ReadonlyMap<string, readonly string[]>;
+    /** Stamped classes with no row in the merged table — announce-once material (the loud half of
+     *  fail-open: a tag typo must not silently become "never gated" with nobody told). */
+    unknownClasses: readonly string[];
+    /** An env value outside the closed set that was NOT in force (nothing this prepare would gate) —
+     *  discarded-value announce material. In-force garbage never lands here: it throws. */
+    discardedEnvRaw: string | undefined;
+}
+/**
+ * The single decision point, called from `prepareConfigDoors` with the model id read ONCE into the
+ * decision (the Model object is mutable; decision and later reads must not diverge) and the frozen
+ * restore snapshot (never the live spec).
+ *
+ * Channel semantics (a UNION of loosening channels — any hit ⇒ don't trim; the order below is
+ * evaluation order, not priority):
+ *  - `depsSeat === false` — deployment kill switch; nothing is scanned.
+ *  - env `SEMA_TOOL_MODEL_GATE` `off|0|false` (case-folded) — process kill switch; `on|1|true` is
+ *    the explicit default (no-op). A value outside the closed set follows the loud-bad-value
+ *    dialect split (#123, the SEMA_TOOL_MATERIALIZE_STRATEGY precedent): where the value is IN
+ *    FORCE — its reading would change this prepare's outcome, i.e. after folding the other
+ *    channels there remains a stamped entry the gate would remove — the prepare REFUSES
+ *    (`config.tool_model_gate_env_invalid`; a mistyped `off` must not silently select the
+ *    narrowing arm). Everywhere else it is a DISCARDED value: announced once per process, never a
+ *    veto of the configuration that outranks it.
+ *  - `restoreGated === true` — every class exempt for this task; an array exempts the WHOLE class
+ *    of any stamped tool it names (CC "opting into any tool of the family restores the family",
+ *    judged against the FULL stamp set — a name `excludeTools` will later remove still selects its
+ *    class here, while the exclusion itself stands downstream; unknown names inert).
+ *  - a stamped class with no merged row ⇒ kept + reported in `unknownClasses` (fail-open, loud).
+ *  - a merged rule with both axes empty ⇒ kept, silent (the documented per-class OFF).
+ *  - the exclusion valve (`excludeTools`, applied downstream at the roster splice) ALWAYS wins in
+ *    the result: no restore channel resurrects an excluded name.
+ */
+export declare function applyToolModelGate(input: {
+    tools: ReadonlyArray<ToolSpec> | undefined;
+    modelId: string;
+    depsSeat: unknown;
+    restoreGated: true | readonly string[] | undefined;
+    envRaw: string | undefined;
+}): ToolModelGateDecision;

package/dist/core/tool-model-gate.js

@@ -0,0 +1,303 @@
+export function modelIdTail(id) {
+    return id.toLowerCase().split("/").pop() ?? "";
+}
+export const TOOL_MODEL_GATE_CLASSES = Object.freeze({
+    "task-scaffold": Object.freeze({
+        floors: Object.freeze([
+            Object.freeze(["opus", Object.freeze([4, 8])]),
+            Object.freeze(["sonnet", Object.freeze([5])]),
+            Object.freeze(["fable", Object.freeze([5])]),
+            Object.freeze(["mythos", Object.freeze([5])]),
+        ]),
+    }),
+});
+const CLAUDE_ID_RE = /^claude-([a-z]+)-(\d+(?:-\d+)*)$/;
+function versionTupleGte(version, floor) {
+    const n = Math.max(version.length, floor.length);
+    for (let i = 0; i < n; i++) {
+        const v = version[i] ?? 0;
+        const f = floor[i] ?? 0;
+        if (v > f)
+            return true;
+        if (v < f)
+            return false;
+    }
+    return true;
+}
+export function isModelGatedForClass(modelId, rule) {
+    const tail = modelIdTail(modelId);
+    if (rule.modelIds !== undefined) {
+        for (const row of rule.modelIds) {
+            if (typeof row === "string" && tail === row.toLowerCase())
+                return true;
+        }
+    }
+    if (rule.floors !== undefined) {
+        const m = CLAUDE_ID_RE.exec(tail);
+        if (m !== null) {
+            const family = m[1] ?? "";
+            const version = (m[2] ?? "").split("-").map(Number);
+            for (const row of rule.floors) {
+                if (!Array.isArray(row) || row.length !== 2)
+                    continue;
+                const [fam, floor] = row;
+                if (typeof fam !== "string" || fam.toLowerCase() !== family)
+                    continue;
+                if (Array.isArray(floor) && versionTupleGte(version, floor))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+function gateConfigError(message) {
+    const e = new Error(message);
+    e.code = "config.tool_model_gate_invalid";
+    return e;
+}
+export function assertRestoreGatedToolsValue(value) {
+    if (value === undefined || value === true)
+        return;
+    if (Array.isArray(value)) {
+        const entries = value;
+        for (const entry of entries) {
+            if (typeof entry !== "string") {
+                throw gateConfigError(`TaskSpec.restoreGatedTools entries must be strings (got ${describeValue(entry)}) — an unevaluable selector must not silently restore nothing.`);
+            }
+        }
+        return;
+    }
+    throw gateConfigError(`TaskSpec.restoreGatedTools must be \`true\` or an array of tool names (got ${describeValue(value)}).`);
+}
+const isPlainObject = (v) => {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+};
+const describeValue = (v) => {
+    try {
+        const s = JSON.stringify(v);
+        return s === undefined ? String(v) : s;
+    }
+    catch {
+        return typeof v === "bigint" ? `${String(v)}n` : "[unserializable value]";
+    }
+};
+function mergeToolModelGateClasses(depsSeat) {
+    const merged = new Map();
+    for (const [cls, rule] of Object.entries(TOOL_MODEL_GATE_CLASSES))
+        merged.set(cls, rule);
+    if (depsSeat === undefined)
+        return merged;
+    if (!isPlainObject(depsSeat)) {
+        throw gateConfigError(`RunnerDeps.toolModelGate must be \`false\` or a plain object — prototype included (got ${Array.isArray(depsSeat) ? "an array" : describeValue(depsSeat)}).`);
+    }
+    for (const key of Object.keys(depsSeat)) {
+        if (key !== "classes") {
+            throw gateConfigError(`RunnerDeps.toolModelGate has unknown key ${JSON.stringify(key)} — the only legal key is "classes".`);
+        }
+    }
+    const classes = Object.hasOwn(depsSeat, "classes") ? depsSeat.classes : undefined;
+    if (classes === undefined)
+        return merged;
+    if (!isPlainObject(classes)) {
+        throw gateConfigError(`RunnerDeps.toolModelGate.classes must be a plain object (got ${Array.isArray(classes) ? "an array" : describeValue(classes)}).`);
+    }
+    for (const [cls, row] of Object.entries(classes)) {
+        if (cls === "")
+            throw gateConfigError("RunnerDeps.toolModelGate.classes has an empty-string class name.");
+        if (row === undefined)
+            continue;
+        if (!isPlainObject(row)) {
+            throw gateConfigError(`RunnerDeps.toolModelGate.classes[${JSON.stringify(cls)}] must be a plain object (got ${Array.isArray(row) ? "an array" : describeValue(row)}).`);
+        }
+        for (const key of Object.keys(row)) {
+            if (key !== "floors" && key !== "modelIds") {
+                throw gateConfigError(`RunnerDeps.toolModelGate.classes[${JSON.stringify(cls)}] has unknown key ${JSON.stringify(key)} — legal keys: "floors", "modelIds".`);
+            }
+        }
+        let floors;
+        if (row.floors !== undefined) {
+            if (!Array.isArray(row.floors)) {
+                throw gateConfigError(`RunnerDeps.toolModelGate.classes[${JSON.stringify(cls)}].floors must be an array (got ${describeValue(row.floors)}).`);
+            }
+            const seen = new Set();
+            const out = [];
+            const rows = row.floors;
+            for (const entry of rows) {
+                if (!Array.isArray(entry) || entry.length !== 2) {
+                    throw gateConfigError(`RunnerDeps.toolModelGate.classes[${JSON.stringify(cls)}].floors rows must be [family, floor] pairs (got ${describeValue(entry)}).`);
+                }
+                const famRaw = entry[0];
+                const floorRaw = entry[1];
+                if (typeof famRaw !== "string" || famRaw.length === 0) {
+                    throw gateConfigError(`RunnerDeps.toolModelGate.classes[${JSON.stringify(cls)}].floors family must be a non-empty string (got ${describeValue(famRaw)}).`);
+                }
+                const fam = famRaw.toLowerCase();
+                if (!/^[a-z]+$/.test(fam)) {
+                    throw gateConfigError(`RunnerDeps.toolModelGate.classes[${JSON.stringify(cls)}].floors family ${JSON.stringify(famRaw)} cannot ever match — the canonical id shape only admits letters. Refused rather than kept as a dead row.`);
+                }
+                if (seen.has(fam)) {
+                    throw gateConfigError(`RunnerDeps.toolModelGate.classes[${JSON.stringify(cls)}].floors lists family ${JSON.stringify(fam)} twice.`);
+                }
+                seen.add(fam);
+                const floorNums = [];
+                if (Array.isArray(floorRaw)) {
+                    const floorEntries = floorRaw;
+                    for (const n of floorEntries) {
+                        if (typeof n === "number" && Number.isSafeInteger(n) && n >= 0)
+                            floorNums.push(n);
+                    }
+                }
+                if (!Array.isArray(floorRaw) || floorRaw.length === 0 || floorNums.length !== floorRaw.length) {
+                    throw gateConfigError(`RunnerDeps.toolModelGate.classes[${JSON.stringify(cls)}].floors floor for ${JSON.stringify(fam)} must be a non-empty array of non-negative safe integers (got ${describeValue(floorRaw)}).`);
+                }
+                out.push([fam, floorNums]);
+            }
+            floors = out;
+        }
+        let modelIds;
+        if (row.modelIds !== undefined) {
+            if (!Array.isArray(row.modelIds)) {
+                throw gateConfigError(`RunnerDeps.toolModelGate.classes[${JSON.stringify(cls)}].modelIds must be an array (got ${describeValue(row.modelIds)}).`);
+            }
+            const seen = new Set();
+            const out = [];
+            const ids = row.modelIds;
+            for (const entry of ids) {
+                if (typeof entry !== "string" || entry.length === 0) {
+                    throw gateConfigError(`RunnerDeps.toolModelGate.classes[${JSON.stringify(cls)}].modelIds entries must be non-empty strings (got ${describeValue(entry)}).`);
+                }
+                const folded = entry.toLowerCase();
+                if (folded.includes("/")) {
+                    throw gateConfigError(`RunnerDeps.toolModelGate.classes[${JSON.stringify(cls)}].modelIds entry ${JSON.stringify(entry)} contains "/" — matching is against the id's TAIL segment, so a prefixed row can never fire. Write the bare id.`);
+                }
+                if (seen.has(folded)) {
+                    throw gateConfigError(`RunnerDeps.toolModelGate.classes[${JSON.stringify(cls)}].modelIds lists ${JSON.stringify(folded)} twice (case-folded).`);
+                }
+                seen.add(folded);
+                out.push(folded);
+            }
+            modelIds = out;
+        }
+        const base = merged.get(cls);
+        merged.set(cls, {
+            ...(floors !== undefined ? { floors } : base?.floors !== undefined ? { floors: base.floors } : {}),
+            ...(modelIds !== undefined ? { modelIds } : base?.modelIds !== undefined ? { modelIds: base.modelIds } : {}),
+        });
+    }
+    return merged;
+}
+const ENV_OFF = new Set(["off", "0", "false"]);
+const ENV_ON = new Set(["on", "1", "true"]);
+export function applyToolModelGate(input) {
+    const noop = (discardedEnvRaw) => ({
+        survivors: undefined,
+        removedByClass: new Map(),
+        unknownClasses: [],
+        discardedEnvRaw,
+    });
+    let merged;
+    try {
+        if (input.depsSeat !== false && input.depsSeat !== undefined && !isPlainObject(input.depsSeat)) {
+            throw gateConfigError(`RunnerDeps.toolModelGate must be \`false\` or a plain object — prototype included (got ${describeValue(input.depsSeat)}).`);
+        }
+        merged = input.depsSeat === false ? undefined : mergeToolModelGateClasses(input.depsSeat);
+    }
+    catch (e) {
+        let code;
+        try {
+            code = e?.code;
+        }
+        catch {
+            code = undefined;
+        }
+        if (code !== undefined)
+            throw e;
+        let msg;
+        try {
+            msg = e instanceof Error ? e.message : String(e);
+        }
+        catch {
+            msg = "[unreportable throw]";
+        }
+        throw gateConfigError(`RunnerDeps.toolModelGate could not be read (${msg}) — a config seat whose reads throw is a bad value, refused rather than passed.`);
+    }
+    const raw = input.envRaw;
+    let envVerdict;
+    if (raw === undefined)
+        envVerdict = "absent";
+    else {
+        const tok = raw.toLowerCase();
+        envVerdict = ENV_OFF.has(tok) ? "off" : ENV_ON.has(tok) ? "on" : "invalid";
+    }
+    const invalidRaw = envVerdict === "invalid" ? raw : undefined;
+    if (merged === undefined)
+        return noop(invalidRaw);
+    if (envVerdict === "off")
+        return noop();
+    const tools = input.tools ?? [];
+    const stamped = [];
+    for (const entry of tools) {
+        if (entry.modelGate !== undefined)
+            stamped.push({ entry, cls: entry.modelGate });
+    }
+    if (stamped.length === 0)
+        return noop(invalidRaw);
+    const restoredClasses = new Set();
+    if (input.restoreGated === true) {
+        for (const s of stamped)
+            restoredClasses.add(s.cls);
+    }
+    else if (input.restoreGated !== undefined) {
+        const names = new Set(input.restoreGated);
+        for (const s of stamped)
+            if (names.has(s.entry.name))
+                restoredClasses.add(s.cls);
+    }
+    const unknownClasses = [];
+    const unknownSeen = new Set();
+    const removed = new Set();
+    const removedByClass = new Map();
+    for (const { entry, cls } of stamped) {
+        const rule = merged.get(cls);
+        if (rule === undefined) {
+            if (!unknownSeen.has(cls)) {
+                unknownSeen.add(cls);
+                unknownClasses.push(cls);
+            }
+            continue;
+        }
+        if (rule.floors === undefined && rule.modelIds === undefined)
+            continue;
+        if (restoredClasses.has(cls))
+            continue;
+        if (!isModelGatedForClass(input.modelId, rule))
+            continue;
+        removed.add(entry);
+        const list = removedByClass.get(cls) ?? [];
+        if (!list.includes(entry.name))
+            list.push(entry.name);
+        removedByClass.set(cls, list);
+    }
+    if (invalidRaw !== undefined) {
+        if (removed.size > 0) {
+            const e = new Error(`SEMA_TOOL_MODEL_GATE=${JSON.stringify(invalidRaw)} is not in the closed set (on|1|true|off|0|false, case-insensitive) and IS in force on this task (the model gate would remove default-mounted tool(s)). Refused rather than guessed — "off" mistyped must not silently keep the trim armed.`);
+            e.code = "config.tool_model_gate_env_invalid";
+            throw e;
+        }
+        return { survivors: undefined, removedByClass: new Map(), unknownClasses, discardedEnvRaw: invalidRaw };
+    }
+    if (removed.size === 0) {
+        return { survivors: undefined, removedByClass: new Map(), unknownClasses, discardedEnvRaw: undefined };
+    }
+    for (const list of removedByClass.values())
+        list.sort();
+    return {
+        survivors: tools.filter((t) => !removed.has(t)),
+        removedByClass,
+        unknownClasses,
+        discardedEnvRaw: undefined,
+    };
+}

package/dist/core/tool-policy.d.ts

@@ -866,7 +866,7 @@ export interface AskRequest {
      *  run's model: a parent-thread run is told to stop and wait for the user (its transcript has a
      *  user turn coming), a delegated child is told to adapt or report the limitation. A fork is
      *  deliberately IN: it inherits the parent's authority (design/110 — which is why the RB-330
-     *  `isDelegatedNonForkChild` derivation, serving the authority/context faces, excludes it), but
+     *  non-fork facet of `effectiveDelegationFacts`, serving the authority/context faces, excludes it), but
      *  its interaction contract is one-shot — "report once and stop … no waiting for the user"
      *  (FORK_DIRECTIVE_FRAME) — so a stop-and-wait refusal would instruct it to do the impossible
      *  (codex adversarial round, confirmed). NOT the same fact as {@link fromSubagent} either: that is