@sema-agent/core 5.37.0 → 5.39.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) } : {}),
@@ -1679,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();
         });
@@ -2037,6 +2045,20 @@ export class Runner {
         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() });
         };
@@ -2729,6 +2751,7 @@ export class Runner {
                         stopHookActive: consecutiveBlocks > 0,
                         consecutiveBlocks,
                         getBranch: () => prepared.session.getBranch(),
+                        identity: prepared.hookIdentity,
                     });
                 }
                 catch (err) {
@@ -2804,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;
@@ -2869,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),
             },
         });
@@ -3099,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;
@@ -3503,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,
@@ -3516,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)
@@ -4503,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 });
@@ -4535,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 {
@@ -4581,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/sensitive-path-policy.js

@@ -39,8 +39,8 @@ function compilePatterns(patterns) {
     }
     return out;
 }
-function matchSensitive(canonicalKey, compiled) {
-    return matchSegmentPatterns(canonicalKey, compiled);
+function matchSensitive(canonicalKey, compiled, aliasResolved) {
+    return matchSegmentPatterns(canonicalKey, compiled, { aliasResolved });
 }
 export function createSensitivePathPolicy(opts) {
     const compiled = compilePatterns(opts.patterns);
@@ -64,7 +64,7 @@ export function createSensitivePathPolicy(opts) {
                 }
                 return { action: "allow" };
             }
-            const hit = matchSensitive(canon.key, compiled);
+            const hit = matchSensitive(canon.key, compiled, canon.aliasResolved === true);
             if (hit) {
                 return {
                     action: "deny",

package/dist/core/store-contracts/mailbox-store-contract.d.ts

@@ -1,4 +1,4 @@
-import type { MailboxStore } from "../mailbox-store.js";
+import { type MailboxStore } from "../mailbox-store.js";
 import { type ContractAssertionRunner } from "./contract-harness.js";
 /**
  * design/159 S1 — the cross-backend {@link MailboxStore} contract, extracted VERBATIM from
@@ -46,3 +46,31 @@ export declare function mailboxAckOwnershipContract(mk: () => MailboxStore, runA
  * 放宽」:核心层没有一条为了任何后端而弱化。第三方后端若有租户轴,应当也挂这一层。
  */
 export declare function mailboxBundledOnlyContract(mk: () => MailboxStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+export interface MailboxTombstonedRecipientContractHooks {
+    /** Put `(scope, handle)` into the deployment's PRE-DELETE state — whatever that is for this
+     *  backend (a cascade marking the session row, a `deleting` column, a tombstone table). Core does
+     *  not name the mechanism, only what `append` must then do. */
+    tombstone: (store: MailboxStore, scope: string, handle: string) => Promise<void>;
+    runAssertion?: ContractAssertionRunner;
+}
+/**
+ * T2 可选能力层(pre-delete 分册)—— 只挂**看得见收件人生命周期**的后端:它的 mailbox 行与某个
+ * 删除级联要清掉的 session 行同生共死(server 的留存删除级联是首个此形消费方)。三个捆绑后端都
+ * 没有这个视角,因此都不挂——**这不是「做不到所以放宽」**:没有预删除态的后端根本没有可拒的对象,
+ * 而有这个态却静默接受的后端,拿到的 seq 是一张级联马上就要撕掉的回执(`append` 是 durable-first,
+ * 回执即承诺),且没有任何其它面会说出这件事。
+ *
+ * 契约不规定态怎么置(那是部署自己的删除协议),只钉「拒」这件事的三条轴 —— **三条一起列在这里,
+ * 是因为逐条补的过程本身证明了单看一条会假绿**(每加一条,都有一个能过掉前面全部用例的错误实现被
+ * 抓出来):
+ *  1. **拒因轴**:必须拒,且每条路径上都带同一个码(空箱与非空箱都算路径);
+ *  2. **副作用轴**:被拒的 append 对箱零改动 —— 不入箱(幽灵投递)、不清箱(删除窗口内静默丢)、
+ *     也不动活租约(动了就撬开 X-1 的单消费者围栏,同一批消息会被二次投递);
+ *  3. **收件人边界轴**:态属于一个 `(scope, handle)` 整体,且这个整体是**单射**的 —— 兄弟 handle
+ *     不受牵连、跨租户同名不受牵连、拼键歧义不得把两个收件人折成一个。
+ * 新增用例请按这三条轴归位;要加第四条轴,先说清它是哪一类假绿。
+ *
+ * 受众前提与 {@link mailboxBundledOnlyContract} 同线:后端有自己的租户轴(生命周期可见的后端就是
+ * 服务端形态的 store),边界轴的两条用例要用两个 scope 构造。
+ */
+export declare function mailboxTombstonedRecipientContract(mk: () => MailboxStore, hooks: MailboxTombstonedRecipientContractHooks): Promise<void>;

package/dist/core/store-contracts/mailbox-store-contract.js

@@ -1,4 +1,5 @@
 import { strict as assert } from "node:assert";
+import { MAILBOX_TOMBSTONED_RECIPIENT_CODE } from "../mailbox-store.js";
 import { beginContract } from "./contract-harness.js";
 export const MAILBOX_CONTRACT_SCOPE = "default";
 const msg = (content, sentAt = 1000) => ({ content, sentAt });
@@ -191,3 +192,80 @@ export async function mailboxBundledOnlyContract(mk, runAssertion) {
     });
     await settle();
 }
+export async function mailboxTombstonedRecipientContract(mk, hooks) {
+    const { run: runRaw, settle } = beginContract(hooks.runAssertion);
+    const run = (name, fn) => runRaw(name, () => withStores(mk, fn));
+    const S = MAILBOX_CONTRACT_SCOPE;
+    const codeOf = (e) => e?.code;
+    run("预删除态的收件人:append 响亮拒且带码(既不静默收下级联即将删掉的消息,也不裸抛)", async (make) => {
+        const s = make();
+        await hooks.tombstone(s, S, "a1");
+        let thrown;
+        try {
+            await s.append(S, "a1", msg("m1"));
+        }
+        catch (e) {
+            thrown = e;
+        }
+        assert.notEqual(thrown, undefined, "静默收下 = 给发件人一张级联马上撕掉的回执");
+        assert.equal(codeOf(thrown), MAILBOX_TOMBSTONED_RECIPIENT_CODE, "裸抛与拒同形:消费方要能按码分诊");
+        let again;
+        try {
+            await s.append(S, "a1", msg("m2"));
+        }
+        catch (e) {
+            again = e;
+        }
+        assert.equal(codeOf(again), MAILBOX_TOMBSTONED_RECIPIENT_CODE);
+    });
+    run("拒的粒度是收件人,不是开关:同 scope 下另一个活收件人照常收信", async (make) => {
+        const s = make();
+        await hooks.tombstone(s, S, "a1");
+        assert.equal(await s.append(S, "a2", msg("still-live")), 1, "活收件人不受邻居的删除级联牵连");
+        assert.equal(await s.peekCount(S, "a2"), 1);
+    });
+    run("收件人身份是 (scope, handle) 整体:A 租户的删除级联不得拒掉 B 租户的同名收件人", async (make) => {
+        const s = make();
+        await hooks.tombstone(s, "tenant-a", "a1");
+        assert.equal(await s.append("tenant-b", "a1", msg("other-tenant")), 1, "同名 handle 在另一个租户下是另一个收件人");
+        assert.equal(await s.peekCount("tenant-b", "a1"), 1);
+    });
+    run("两件套还得是单射的:把 (scope, handle) 拼成一个字符串记态,不得让两个不同收件人撞成一个", async (make) => {
+        const s = make();
+        await hooks.tombstone(s, "tenant a", "b");
+        assert.equal(await s.append("tenant", "a b", msg("distinct-recipient")), 1, "拼键歧义不得把另一个收件人一起拒掉");
+        assert.equal(await s.peekCount("tenant", "a b"), 1);
+    });
+    run("副作用轴 · 活租约:被拒的 append 不得动别人手上的租约(单消费者围栏不因删除窗口松开)", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("in-flight"));
+        const held = await s.claimLease(S, "a1", "consumer-A", 60_000, 10_000);
+        assert.equal(held?.messages.length, 1);
+        await hooks.tombstone(s, S, "a1");
+        await assert.rejects(s.append(S, "a1", msg("after-tombstone", 2_000)), "预删除态下的 append 必须拒");
+        assert.equal(await s.claimLease(S, "a1", "rival", 60_000, 11_000), null, "A 的活租约必须仍然 fence 住别人");
+        await s.ack(S, "a1", "consumer-A", held.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+    });
+    run("拒的是入口,不是清仓:被拒的 append 零副作用,已入箱的消息按原 seq/内容原封不动", async (make) => {
+        const s = make();
+        const seq = await s.append(S, "a1", msg("parked-before"));
+        await hooks.tombstone(s, S, "a1");
+        let thrown;
+        let refused = false;
+        try {
+            await s.append(S, "a1", msg("after-tombstone", 2_000));
+        }
+        catch (e) {
+            refused = true;
+            thrown = e;
+        }
+        assert.equal(refused, true, "预删除态下的 append 必须拒");
+        assert.equal(codeOf(thrown), MAILBOX_TOMBSTONED_RECIPIENT_CODE, "箱非空时的拒同样要带码");
+        assert.equal(await s.peekCount(S, "a1"), 1, "被拒的 append 不得入箱(幽灵投递),也不得清箱");
+        const lease = await s.claimLease(S, "a1", "w1", 60_000, 10_000);
+        assert.deepEqual(lease?.messages.map((m) => m.seq), [seq]);
+        assert.deepEqual(lease?.messages.map((m) => m.content), ["parked-before"], "取到的仍是拒之前那一条");
+    });
+    await settle();
+}

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;