@sema-agent/core 5.37.0 → 5.38.0

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

package/dist/core/types.d.ts

@@ -381,6 +381,25 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      * Exclusion still wins ({@link TaskSpec.excludeTools} unmounts — nothing left to keep inline).
      */
     alwaysLoad?: boolean;
+    /**
+     * design/277 — model-gate CLASS tag (open vocabulary; the built-in table is
+     * {@link import("./tool-model-gate.js").TOOL_MODEL_GATE_CLASSES}, v1 vocabulary =
+     * `"task-scaffold"`). A tagged entry declares "I am a default-mounted scaffold of this class":
+     * at prepare, when the task's RESOLVED model id matches the class's rule, THIS entry is dropped
+     * from the roster (true unmount, entry-level — a same-name untagged entry is untouched; the
+     * removed entry stops occupying its name on every downstream surface). Untagged = never gated.
+     * The default-bundle assemblers stamp their default arms only; an EXPLICITLY composed tool is
+     * not tagged (user asked ⇒ user gets) — so don't stamp hand-mounted factories. FAIL-OPEN: an id
+     * the merged table knows nothing about is never gated (BYOM open set — the table encodes
+     * positive knowledge only), and a tag naming an unknown class is inert + announced
+     * (`config.tool_model_gate_unknown_class`). Restore channels: explicit composition (no tag),
+     * {@link TaskSpec.restoreGatedTools}, env `SEMA_TOOL_MODEL_GATE=off`,
+     * `RunnerDeps.toolModelGate: false`; {@link TaskSpec.excludeTools} always wins regardless.
+     * The materialized `AgentTool` face does NOT carry this field (`defineTool` is a whitelist
+     * constructor) — the decision completes on the ToolSpec face inside `prepareConfigDoors`,
+     * before any conversion.
+     */
+    modelGate?: string;
     /**
      * Tool contract identity (campaign S2, prompt-assembly protocol §7): declares the EXECUTION
      * CONTRACT this tool implements, independent of its presentation text. `defineTool` attaches it
@@ -751,6 +770,13 @@ export interface ToolExecuteContext {
      *  X arrives deferred, the exemption having been dropped in transit — which is the one outcome the
      *  parent explicitly ruled out. Children merge this with their own spec value. */
     alwaysLoadTools?: readonly string[];
+    /** design/277 — the model-gate restore selector ({@link TaskSpec.restoreGatedTools}), inherited
+     *  down the delegation tree on the same trusted seat as the three tool-face controls above
+     *  (Runner-filled, read-only, frozen snapshot). Restoration is a TASK-TREE intent ("this work
+     *  wants the scaffold back") and each child re-judges the gate under its OWN resolved model —
+     *  dropping the selector in transit would trim a same-model child's roster in a way nobody
+     *  chose (the gate is a default, not a policy; there is no tighten-only axis to protect). */
+    restoreGatedTools?: readonly string[] | true;
     /** R2 双形轴 — the parent's resolved prompt profile, inherited down the delegation tree like the
      *  tool-face controls (Runner-filled): a classic-profile parent's children speak classic too
      *  unless the child spec says otherwise (child spec wins — profile is presentation, not policy). */
@@ -1867,6 +1893,24 @@ export interface TaskSpec {
      * wins — an unmounted tool has no schema to keep inline).
      */
     alwaysLoadTools?: string[];
+    /**
+     * design/277 — per-task restore valve for the tool-registration MODEL GATE. The gate trims
+     * default-mounted scaffold entries (tagged via {@link ToolSpec.modelGate}) from the roster when
+     * the task's resolved model id matches the gate table — this valve opts the task (and its whole
+     * delegation tree — the selector inherits down like `excludeTools`) back in:
+     *  · an ARRAY of wire names — naming ANY tagged tool restores that tool's WHOLE class for this
+     *    task (CC parity: opting into any member of the family restores the family). Judged against
+     *    the full stamp set, so a name that `excludeTools` also lists still works as a class
+     *    SELECTOR — while the exclusion itself still wins for that name (exclusion is the final
+     *    valve; no restore channel resurrects an excluded name). Unknown names are inert (a
+     *    center-distributed list may be a superset), same posture as `excludeTools`.
+     *  · literal `true` — every gate class restored for this task (the shortest "this task wants
+     *    all its scaffolding" spelling for center-distributed specs).
+     * A malformed value refuses at prepare (`config.tool_model_gate_invalid`, #123) — garbage must
+     * not silently read as "restore nothing" in the trimming direction. Absent = the gate's verdict
+     * stands. Explicit composition needs no valve: a hand-mounted (untagged) tool is never gated.
+     */
+    restoreGatedTools?: string[] | true;
     /**
      * RB-403 — whether a schema-VALID call on a still-deferred tool runs the real tool directly
      * (activating it as a side effect). Default `true`, matching the upstream posture where the
@@ -4440,6 +4484,93 @@ export interface BackgroundChildEvent {
         costMicroUsd?: number;
     };
 }
+/**
+ * #281 件B — one lifecycle phase of a DELEGATED child leg, delivered to the process-level
+ * {@link RunnerDeps.onDelegationLifecycle} observer: the public, deps-level home of the delegation
+ * lifecycle that previously lived only on the trusted RunInternals third parameter
+ * (`onSubagentSpawn` — sync lane, a steer handle whose `settled` is a void promise) and on the
+ * background-lane-only {@link BackgroundChildEvent}. A deployment wired ONLY through `RunnerDeps`
+ * now sees every delegation lane through one seat.
+ *
+ * EMISSION CHOKEPOINT (the reason this seat covers every lane at once): frames are minted by the
+ * RUNNER at the child LEG itself — spawn right after the leg's `wiring_manifest` (prepared, nothing
+ * run yet), terminal when the leg's `TaskResult` assembles — not by the individual spawn lanes. Every
+ * delegation lane (sync/steer/background/fork/revive, workflow-spawned agents) runs its child through
+ * this chokepoint, so none of them needs its own emission and none can drift.
+ *
+ * PER-LEG semantics, deliberately: a durable park + resume, or a retained child's revive, is a NEW
+ * leg — each emits its own spawn/terminal pair, and `identity.legKind` (`"resume"`) says which cycle
+ * a frame belongs to. Consumers correlate legs of one delegation by `identity.taskId` /
+ * `identity.parentToolCallId` (stable across cycles).
+ *
+ * HONEST ABSENCES (recorded, not gaps to fix silently):
+ *  · a child whose PREPARE throws emits neither frame (there is no leg identity to report);
+ *  · the ROOT leg emits nothing here — the deployment called `runTask` itself and holds the result;
+ *    this seat is the delegation observer, not a run observer;
+ *  · a deps-only resume (`resume(token, outcome, config)` — no trusted internals re-supplied) of a
+ *    checkpoint minted BEFORE the delegation axis was persisted
+ *    ({@link import("./checkpoint-store.js").CheckpointState.isDelegatedChild}) emits neither frame:
+ *    the row carries no evidence the parked leg was a delegated child, and fabricating the axis
+ *    would stamp delegation frames onto host-resumed root tasks. Rows minted WITH the axis resume
+ *    with their spawn/terminal pair even deps-only; a resume that re-supplies trusted internals
+ *    (every in-engine lane does) was never affected.
+ * PAIRING (codex r2-D2 closed the one hole): a spawn frame is always closed by a terminal frame —
+ * the ordinary path emits it where the `TaskResult` assembles, and a POST-SPAWN throw that the
+ * stream layer converts into a synthesized failed result (e.g. `resume.tool_unavailable` re-thrown
+ * past the run tail) emits the failed terminal from that backstop, gated on a carrier that is set
+ * only after the spawn emission and cleared by the ordinary terminal (so the two sites can never
+ * both fire for one leg). A leg whose PROCESS dies mid-flight is the only unpaired spawn.
+ *
+ * OBSERVATION ONLY (matrix §5.2 Q3: frame-rate lifecycle facts ride an observer seat, never
+ * onNotice): no return capability, and delivery can never alter the child run —
+ * {@link deliverDelegationLifecycle} contains a throwing sink and an async sink's rejection alike.
+ *
+ * FRAME OBJECT SHAPE (consumer contract, not an implementation detail): every delivered frame is
+ * FROZEN and carries a NULL PROTOTYPE — re-minted at the one delivery point so a forged member
+ * cannot ride a frame through a writable `Object.prototype`, the same rule (and the same trade) as
+ * the {@link import("./hooks.js").HookInvocationIdentity} envelope inside it. `Object.keys`, spread,
+ * JSON serialization and direct member reads (`frame.status`) all behave normally, but
+ * `frame instanceof Object` is `false` and inherited methods are ABSENT — probe optional members
+ * with `Object.hasOwn(frame, "errorCode")` or `"errorCode" in frame`, never
+ * `frame.hasOwnProperty(...)` (throws) or implicit string coercion (`` `${frame}` `` throws).
+ */
+export type DelegationLifecycleEvent = {
+    phase: "spawn";
+    /** The child LEG's identity envelope (#281 件A — the same frozen object that leg's own hook
+     *  invocations carry). `isDelegatedChild` is `true` by construction on every frame here. */
+    identity: import("./hooks.js").HookInvocationIdentity;
+} | {
+    phase: "terminal";
+    /** Same envelope as the leg's spawn frame (one mint per leg). */
+    identity: import("./hooks.js").HookInvocationIdentity;
+    /** The leg's settled status — the `TaskResult.status` the spawning lane receives, verbatim
+     *  (the sync lane's previously-void `settled` payload, made public). `"suspended"` means a
+     *  durable park: expect a later `"resume"`-leg spawn/terminal pair if it is redeemed. */
+    status: TaskResult["status"];
+    /** Turns the leg completed. */
+    turns: number;
+    /** The leg's `TaskResult.errorCode`, when one was stamped. */
+    errorCode?: string;
+};
+/** Test seam (mirrors `__resetMalformedNoticeSeatAnnouncement`): never called by production code. */
+export declare function __resetMalformedDelegationSeatAnnouncement(): void;
+/**
+ * The ONE delivery form behind every {@link RunnerDeps.onDelegationLifecycle} emission point (both
+ * runner stations — spawn and terminal — call this; a second spelling of the swallow/announce rules
+ * would be the #170 triplication reborn). Contract:
+ *  · a FUNCTION seat is invoked with the frame FROZEN (a mutating observer must not rewrite what a
+ *    later frame consumer — or the shared identity envelope's other readers — see), contained in the
+ *    caller's {@link SafeNotifier} against BOTH failure shapes the void-typed seat admits: a
+ *    synchronous throw ({@link SafeNotifier.notify}) and an async sink's rejected promise
+ *    ({@link observeThenableRejection} routes it back through the same notifier/site — the #253
+ *    three-station form). A broken observer never faults the child run.
+ *  · a PRESENT NON-function seat is a bad deployment value; #123 forbids folding it to silence. There
+ *    is no per-frame console fallback (this is a frame-rate observer stream, not an announcement
+ *    channel — an unwired seat means UNOBSERVED, and echoing every spawn to stderr would flood), so
+ *    the loud exit is the seat DEFECT itself: announced via `console.warn` once per process.
+ *  · an ABSENT seat is a plain no-op (the deployment chose not to observe).
+ */
+export declare function deliverDelegationLifecycle(seat: RunnerDeps["onDelegationLifecycle"], event: DelegationLifecycleEvent, notifier: import("./safe-notify.js").SafeNotifier, site: string): void;
 /**
  * parity-204 — structured `RunnerDeps.loadProjectMemory` return (backward-compatible: a bare
  * `string | null` keeps its exact historical meaning). Adds the CC 2.1.204 `seededFromContext`
@@ -4519,6 +4650,24 @@ export interface EngineNotice {
      *    a library-direct `createHandsToolkit` mount announces at toolkit creation (one per mount,
      *    through the band-local `HandsToolkitOptions.onNotice` seat, absent ⇒ `console.warn`);
      *    `detail: { seat, declared, inForce, cause }`.
+     *  - `"config.tool_model_gate_removed"` (design/277) — the model gate trimmed default-mounted
+     *    scaffold entries from a task's roster. One notice per (model, class), de-duplicated once per
+     *    `onNotice` SINK on the (modelId, class, canonical sorted removed-name set) line (same unit
+     *    as `config.read_face_deployment_clamped`: two deployments hosted in one process each hear
+     *    their own trim; unwired console arm once per process) — same class with a different removal
+     *    shape is a distinct fact and announces again;
+     *    `detail: { modelId, gateClass, removed, restore }` (`restore` names the three valves).
+     *  - `"config.tool_model_gate_unknown_class"` (design/277) — a `ToolSpec.modelGate` tag names a
+     *    class the merged gate table has no row for: the tag is inert (fail-open — the tool stays
+     *    mounted) and this is its loud half (a tag typo must not silently become "never gated" with
+     *    nobody told). Once per `onNotice` sink per class (console arm once per process);
+     *    `detail: { gateClass }`.
+     *  - `"config.tool_model_gate_env_invalid"` (design/277, the NOTICE dialect of the same fact the
+     *    refusal code carries) — `SEMA_TOOL_MODEL_GATE` holds a value outside `on|1|true|off|0|false`
+     *    in a seat where it is NOT in force (nothing this prepare would gate): announced once per
+     *    `onNotice` sink per value (console arm once per process) instead of lying in wait; where the
+     *    value IS in force the prepare refuses with the same code as `TaskResult.errorCode` (one
+     *    fact, one code, two loudness dialects); `detail: { raw }`.
      *
      *  Deliberately NOT a notice family: brain retry/reconnect liveness (a rate limit, a 5xx, a
      *  transient network failure being retried). Those are per-attempt liveness frames with their own
@@ -4874,6 +5023,23 @@ export interface RunnerDeps {
      * completion pushes from it. Observability only — a throwing observer is swallowed, never faults a run.
      */
     onBackgroundChildEvent?: (event: BackgroundChildEvent) => void;
+    /**
+     * #281 件B — PROCESS-level observer for EVERY delegated child leg's lifecycle (`spawn`/`terminal`),
+     * all delegation lanes at once: synchronous and steer-handle delegations (whose spawn/settle
+     * previously reached only the trusted `RunInternals.onSubagentSpawn` third parameter — and whose
+     * `settled` is a void promise), background/fork/revive children (whose {@link BackgroundChildEvent}
+     * family this seat complements, not replaces — BCE stays the fleet-row lane with registry `a*`
+     * handles and ticks; this seat is the leg-identity lane), and workflow-spawned agents. Frames are
+     * minted at the child leg's own runner chokepoint and carry the #281 件A identity envelope plus a
+     * terminal status summary — see {@link DelegationLifecycleEvent} for the emission points, the
+     * per-leg semantics and the recorded honest absences. Wire it once at Runner construction; a
+     * deployment needs NO RunInternals access to observe delegation any more. Observation only — a
+     * throwing or rejecting observer is contained ({@link deliverDelegationLifecycle}) and never
+     * faults the child run; a PRESENT non-function value here is announced once per process and the
+     * frames are simply not delivered (#123 — a bad seat must be loud, and this stream's loud exit is
+     * the seat defect, not a per-frame console flood).
+     */
+    onDelegationLifecycle?: (event: DelegationLifecycleEvent) => void;
     /**
      * design/98 (S8) — the HARD sandbox seam for LLM-AUTHORED workflow scripts (`TaskSpec.selfOrchestration`).
      * A deployment supplies an isolated-vm / separate-process runner whose `safeForUntrustedScripts === true`;
@@ -4961,7 +5127,7 @@ export interface RunnerDeps {
      *  resolves a saved workflow, and a registration's `defaultArgs` merge under the call-time args. Opt-in
      *  (absent ⇒ inline `script` + built-in names only). */
     workflowScriptStore?: import("../orchestration/workflow-script-store.js").WorkflowScriptStore;
-    /** design/140 §6 1c — `false` removes the BUILT-IN named workflows (`team-discussion`, …) from the
+    /** design/140 §6 1c — `false` removes the BUILT-IN named workflows (`discussion`, …) from the
      *  auto-mounted run_workflow tool (the `builtinAgents:false` analog; default ON). A deployment
      *  `workflowScriptStore` registration of the same name shadows a built-in regardless. */
     builtinWorkflows?: boolean;
@@ -5142,6 +5308,28 @@ export interface RunnerDeps {
     mcpImageResizer?: import("./mcp.js").McpImageResizer;
     /** Default tool-call gate for all tasks (a task's own `toolPolicy` overrides this). */
     toolPolicy?: import("./tool-policy.js").ToolPolicy;
+    /**
+     * design/277 — the deployment seat of the tool-registration MODEL GATE (default ON; the gate
+     * itself only ever touches entries tagged via {@link ToolSpec.modelGate}, so an untagged roster
+     * is byte-identical under any value here):
+     *  · `false` — deployment kill switch: the gate never trims anything.
+     *  · `{ classes }` — per-class rule rows merged into the built-in table
+     *    ({@link import("./tool-model-gate.js").TOOL_MODEL_GATE_CLASSES}) PER AXIS: a present
+     *    `floors`/`modelIds` axis REPLACES that axis, an absent axis INHERITS the built-in one — so
+     *    a row adding only `modelIds` (the BYOM channel for gating a deployment's own strong model)
+     *    keeps the built-in claude floors armed. `floors: []` / `modelIds: []` are the EXPLICIT
+     *    per-axis clears; a class whose merged rule has both axes empty gates nothing (legal
+     *    per-class off). New class names extend the open vocabulary for deployment-authored tags.
+     * The legality set is CLOSED (#123): any other shape — array/null/true seat, unknown keys at
+     * either level, malformed floors/modelIds rows, families that can never match the canonical id
+     * grammar, duplicate families/ids, `/`-prefixed ids — refuses the prepare loudly
+     * (`config.tool_model_gate_invalid`), never folds to a guess. Process-level counterpart: env
+     * `SEMA_TOOL_MODEL_GATE=off`. Removals are announced per (model, class) through `onNotice`
+     * (`config.tool_model_gate_removed`) — a silent default-face trim is forbidden (#237).
+     */
+    toolModelGate?: false | {
+        classes?: Record<string, import("./tool-model-gate.js").ToolModelGateRule>;
+    };
     /** Deployment default for {@link TaskSpec.basePolicyForResumeEdit} (#93 / F-012 L3): the resume-edit
      *  re-adjudication override. Resolution: `spec.basePolicyForResumeEdit ?? THIS ?? (spec.toolPolicy ??
      *  deps.toolPolicy)` — absence falls back to the caller policy, never to a silent skip. */

package/dist/core/types.js

@@ -1,3 +1,24 @@
+import { observeThenableRejection } from "./safe-notify.js";
+let malformedDelegationSeatAnnounced = false;
+export function __resetMalformedDelegationSeatAnnouncement() {
+    malformedDelegationSeatAnnounced = false;
+}
+export function deliverDelegationLifecycle(seat, event, notifier, site) {
+    if (typeof seat === "function") {
+        const frame = Object.freeze(Object.assign(Object.create(null), event));
+        notifier.notify(() => observeThenableRejection(seat(frame), notifier, site), site);
+        return;
+    }
+    if (seat !== undefined && !malformedDelegationSeatAnnounced) {
+        malformedDelegationSeatAnnounced = true;
+        try {
+            console.warn(`The delegation-lifecycle sink (RunnerDeps.onDelegationLifecycle) holds ${seat === null ? "null" : typeof seat} — not a ` +
+                `function. Delegation spawn/terminal frames are NOT delivered until the wiring is fixed (omit the key, or wire a function).`);
+        }
+        catch {
+        }
+    }
+}
 let malformedNoticeSeatAnnounced = false;
 export function __resetMalformedNoticeSeatAnnouncement() {
     malformedNoticeSeatAnnounced = false;

package/dist/core/untrusted-text.d.ts

@@ -21,7 +21,7 @@
  * model-facing instructions. Always neutralizes `<system-reminder>` / `</system-reminder>` (the codebase's
  * elevated-authority wrapper) by inserting a zero-width space after the leading `<`. Pass `extraTags` to also
  * neutralize a CALLER's own data-framing tags — e.g. `team.ts` embeds member output inside `<statement>` /
- * `<team-discussion>`, so an untrusted member could emit `</statement>` to break out (search [46] BUG2);
+ * `<discussion>`, so an untrusted member could emit `</statement>` to break out (search [46] BUG2);
  * the caller passes those tag names. Tag names must be literal (alphanumeric/hyphen) — they are code-supplied
  * wrapper names, never untrusted input. Idempotent for prompt assembly (a defused tag no longer matches).
  */

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export { createWebFetchTool, webFetchToolSpec, htmlToText, type WebFetchConfig,
 export { createTodoWriteTool } from "./tools/todo.js";
 export { createTaskListTools, createMemoryTaskListStore, assertJsonMetadata, type TaskListItem, type TaskListStore } from "./tools/task-list.js";
 export { assembleCodeTools, type CodeToolsConfig, CODE_ROLE } from "./scenarios/full-body.js";
+export { TOOL_MODEL_GATE_CLASSES, isModelGatedForClass, type ToolModelGateRule } from "./core/tool-model-gate.js";
 export { capAggregateToolResults, AGGREGATE_TOOL_RESULT_BUDGET_CHARS, DEFAULT_BUDGET_EXEMPT_TOOLS, type AggregateBudgetOptions, } from "./core/tool-result-budget.js";
 export { capAggregateMediaBytes, AGGREGATE_MEDIA_BUDGET_BYTES, type MediaStripInfo } from "./core/media-byte-cap.js";
 export { createAskUserQuestionTool, createDurableQuestionPolicy, QUESTION_AWAITS_RESUME, isQuestionUnavailable, type OnQuestionOutcome, type QuestionUnavailable, type OnQuestion, type AskQuestion, type AskQuestionOption, type AskQuestionRequest, type QuestionAnswer, type QuestionAnswerItem, type AskQuestionCardDetails, type AskUserQuestionToolOptions, type AskAnswerContinuationSource, type SyntheticContinuationReason, } from "./core/ask-question.js";
@@ -162,7 +163,7 @@ export { FilePermissionRuleStoreProvider } from "./stores/file/permission-rule-s
 export { adoptFilePermissionRuleStore, type AdoptFileRuleStoreResult } from "./stores/file/permission-rule-adopt.js";
 export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, type AdoptionErrorCode, type AdoptionSource, type AdoptionReport, type AdoptionReceipt, type AdoptionLegReport, type AffectedDeploymentConfig, type RootAdoptionFile, } from "./stores/file/adoption/marker.js";
 export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, type AdoptionStatus, type AdoptLocalDataRootOptions, type AdoptLocalDataRootResult, type AdoptionCarriageLeg, type AdoptionCarriageLegContext, type AdoptionConfigWitnessReceipt, } from "./stores/file/adoption/adopt.js";
-export { formatHookFeedback, runToolGate, createHookEnvCapabilities, createPreToolUseConstraintPolicy, type PersistedRuleHit, type PersistedRuleUnreadable, type PersistedRuleAnswer, normalizePersistedRuleHit, type Hooks, type HookToolContext, type HookEnvCapabilities, type HookToolOutput, type PreToolUseResult, type PostToolUseResult, type UserPromptSubmitResult, type HookToolFailure, type PostToolUseFailureResult, type PostToolBatchCall, type PostToolBatchResult, type PreCompactContext, type PreCompactResult, type PostCompactContext, type StopFailureContext, type PermissionDeniedPayload, type PermissionDeniedSource, } from "./core/hooks.js";
+export { formatHookFeedback, runToolGate, createHookEnvCapabilities, createPreToolUseConstraintPolicy, type PersistedRuleHit, type PersistedRuleUnreadable, type PersistedRuleAnswer, normalizePersistedRuleHit, type Hooks, type HookToolContext, type HookInvocationIdentity, type UserPromptSubmitContext, type PostToolBatchContext, type HookEnvCapabilities, type HookToolOutput, type PreToolUseResult, type PostToolUseResult, type UserPromptSubmitResult, type HookToolFailure, type PostToolUseFailureResult, type PostToolBatchCall, type PostToolBatchResult, type PreCompactContext, type PreCompactResult, type PostCompactContext, type StopFailureContext, type PermissionDeniedPayload, type PermissionDeniedSource, } from "./core/hooks.js";
 export { InMemoryMemoryStore, composeMemoryBlock, composeLayeredMemoryBlock, normalizeMemorySpec, type NormalizedMemorySpec, type MemorySpecInput, supportsConsolidation, supportsPeriodicConsolidation, firstSentence, expandLexicalTerms, lexicalSearchMatch, type Embedder, classifyPromotable, enforcePromotableWriteGate, guardedMemoryStore, MemoryGateError, detectSecret, enforceSecretWriteGate, enforceStructuredNoteSecretGate, type UtilityGate, type MemoryStore, type MemoryVectorMode, type ScoredMemory, type MemoryNoteHeader, type MemoryNoteRecord, type MemoryNoteType, type StructuredNoteInput, } from "./core/memory.js";
 export { MemoryEngine, FileMemoryEngineBackend, memoryBackendContract, assertMemoryBackendSearchEquivalence, type MemoryBackendContractHooks, buildMemoryInstruction, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, readV2HeaderHints, type V2HeaderHints, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type MemoryGetDetails, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, type MemoryAnnouncement, type ScanFinding, type MemoryEngineOptions, type MemoryInjection, type EntryProvenanceAccount, type TransferEvidence, type CommittedBinding, type CommittedEntrySnapshot, type CommittedScopeSnapshots, type EntryCustodyReport, erasureSelectHash, type EraseMemoryEntriesInput, type ErasureSelect, type ErasedBinding, type MemoryErasureAttestation, type MemoryBackend, type MemoryEntry, type MemoryEntryFrontmatter, type MemoryEntryHeader, type ScoredMemoryEntry, type NotePatch, type PatchReport, type MaterializedFile, type MemorySessionHandle, type HarvestReport, type HarvestRejection, type HarvestRejectionCode, type ParsedEntryFile, type ScannedEntryFile, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, type ParsedScopeKey, migrateScope, type MigrateScopeReport, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, type RemoteMemoryFile, type RemoteMemoryBaseline, type RemoteMaterialization, type RemoteHarvestResult, type InboundEntryFinding, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, type MemorySyncCursor, type MemorySyncConflict, type MemorySyncPlan, type RecallSource, syncMemoryScope, type MemorySyncTransport, type MemorySyncRequestBody, type MemorySyncResponseBody, type MemorySyncClientConflict, type SyncMemoryScopeOptions, type MemorySyncClientResult, } from "./core/memory-engine/index.js";
 export { SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_LIST_PAGE_SIZE, SharedMemoryStoreError, type SharedMemoryStoreProvider, type SharedMemoryStoreReader, type SharedMemoryPagedList, type SharedMemoryStoreInfo, type SharedMemoryDocumentEntry, type SharedMemorySnapshot, type SharedMemoryRequestContext, type MemoryListDetails, type MemoryReadDetails, } from "./core/shared-memory/types.js";
@@ -201,7 +202,7 @@ export { assertWorkflowSandboxConformance, assertWorkflowPrimitivesWiring, asser
 export { WorkflowModelNotAllowedError, type WorkflowAgentSpec } from "./orchestration/workflow-governance.js";
 export { WorkflowMaxAgentsError, WorkflowResultTooLargeError } from "./orchestration/workflow.js";
 export { createFileWorkflowScriptStore, mergeWorkflowArgs, type WorkflowScriptStore, type NamedWorkflowResolution, type NamedWorkflowListing, } from "./orchestration/workflow-script-store.js";
-export { TEAM_DISCUSSION_WORKFLOW_NAME, TEAM_DISCUSSION_SCRIPT, builtinWorkflowDefinitions, builtinWorkflowListings, resolveBuiltinWorkflow, type BuiltinWorkflowDefinition, } from "./orchestration/builtin-workflows.js";
+export { DISCUSSION_WORKFLOW_NAME, DISCUSSION_SCRIPT, TEAM_DISCUSSION_WORKFLOW_NAME, TEAM_DISCUSSION_SCRIPT, canonicalWorkflowName, retiredWorkflowNameAliases, builtinWorkflowDefinitions, builtinWorkflowListings, resolveBuiltinWorkflow, type BuiltinWorkflowDefinition, } from "./orchestration/builtin-workflows.js";
 export { WORKFLOW_AGENT_STALL_MS, WORKFLOW_AGENT_MAX_RETRIES, WORKFLOW_AGENT_THROTTLE_BACKOFF_MS } from "./orchestration/workflow.js";
 export { createRunWorkflowTool, RUN_WORKFLOW_TOOL_NAME, workflowWhenToUseText, renderNamedWorkflowListing, type WorkflowCompletionNotifier, type WorkflowLimits, type RunWorkflowToolDeps, } from "./orchestration/run-workflow-tool.js";
 export { runSideQuery, type SideQuerySpec, type SideQueryResult, type SideQueryToolDef, type SideQueryDeps, type SideQueryMessage } from "./core/side-query.js";
@@ -254,7 +255,7 @@ export { retryBackoffMs, parseRetryAfter } from "./brain/retry.js";
 export { type BrainTimeoutConfig } from "./brain/timeout.js";
 export { createAssistantMessageEventStream } from "./internal/llm.js";
 export type { AssistantMessage, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, StopReason, StreamFn, TextContent, ThinkingContent, ToolCall, ToolResultMessage, Usage, UserMessage, } from "./internal/llm.js";
-export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, EngineNotice, RuntimeCaps, BackgroundChildEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ReversibilityVerdict, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
+export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, EngineNotice, RuntimeCaps, BackgroundChildEvent, DelegationLifecycleEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ReversibilityVerdict, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
 export { Type } from "typebox";
 export type { TSchema, Static } from "typebox";
 export { explainPromptAssembly, describeDefaultPack, type DefaultPackDescription, type ExplainInput } from "./prompt-assembly/explain.js";