@sema-agent/core 5.37.0 → 5.38.0

package/dist/core/runner/prepare-task.js

@@ -29,7 +29,7 @@ import { inlineUntrusted } from "../untrusted-text.js";
 import { policyAskClassOf } from "../ask-class.js";
 import { emitTrace } from "../trace.js";
 import { createSessionRulePolicy } from "./session-rule-policy.js";
-import { cloneObserverInput, createHookEnvCapabilities, createPreToolUseConstraintPolicy, formatHookFeedback, persistedRuleMandateOf, runToolGate } from "../hooks.js";
+import { cloneObserverInput, createHookEnvCapabilities, createPreToolUseConstraintPolicy, formatHookFeedback, mintHookInvocationIdentity, persistedRuleMandateOf, runToolGate } from "../hooks.js";
 import { orgRuleVerdictFor } from "../permission-rule-org.js";
 import { CacheBreakDetector, toolsToFingerprintInputs } from "../cache-break-detector.js";
 import { reservedCollisions, reservedFor } from "../../brain/request-params.js";
@@ -92,13 +92,104 @@ import { countElicitOptIns, deriveWiringManifest, resolveAskSeamForm, resolveDec
 import { durableParkGapFor } from "../park-selfcheck.js";
 import { GLOBAL_USAGE_KEY, usageRetryAfterMs } from "../usage-window-store.js";
 import { deliverEngineNotice } from "../types.js";
-const announcedMaterializeEnv = new Set();
+let announcedMaterializeEnvBySink = new WeakMap();
+const announcedMaterializeEnvConsole = new Set();
+function materializeEnvLedger(onNotice) {
+    if (typeof onNotice !== "function")
+        return announcedMaterializeEnvConsole;
+    let lines = announcedMaterializeEnvBySink.get(onNotice);
+    if (lines === undefined) {
+        lines = new Set();
+        announcedMaterializeEnvBySink.set(onNotice, lines);
+    }
+    return lines;
+}
 export function __resetMaterializeEnvAnnouncements() {
-    announcedMaterializeEnv.clear();
+    announcedMaterializeEnvBySink = new WeakMap();
+    announcedMaterializeEnvConsole.clear();
 }
 function emitMaterializeEnvNotice(onNotice, message, detail) {
+    const ledger = materializeEnvLedger(onNotice);
+    if (ledger.has(message))
+        return;
+    ledger.add(message);
     deliverEngineNotice(onNotice, { code: "config.materialize_env_discarded", message, detail });
 }
+function warnCompactionWindowHazard(tracer, spec, model, compModel, hostTaskId) {
+    if (compModel === undefined)
+        return;
+    const compWindow = compModel.contextTokens ?? compModel.contextWindow;
+    const mainWindow = model.autoCompactTokens ?? model.contextTokens ?? model.contextWindow;
+    if (compWindow > 0 && mainWindow > 0 && compWindow < mainWindow) {
+        const merged = { ...DEFAULT_COMPACTION_SETTINGS, ...spec.compaction };
+        const sanitized = sanitizeCompactionSettings(merged, mainWindow);
+        const tolerance = sanitized.clampTolerance ?? DEFAULT_CLAMP_TOLERANCE;
+        const headroom = Math.max(0, compWindow - Math.max(Math.floor(0.8 * summaryOutputBudgetTokens(compModel, sanitized)), 2048) - 512);
+        emitTrace(tracer, () => ({
+            kind: "compaction.window_config_warning",
+            version: 1,
+            taskId: hostTaskId,
+            compactionModelWindow: compWindow,
+            mainModelWindow: mainWindow,
+            ...(tolerance < 1 ? { fallbackAt: Math.floor(headroom / (1 - tolerance)) } : {}),
+            ts: Date.now(),
+        }));
+    }
+}
+let announcedToolModelGateBySink = new WeakMap();
+const announcedToolModelGateConsole = new Set();
+function toolModelGateLedger(onNotice) {
+    if (typeof onNotice !== "function")
+        return announcedToolModelGateConsole;
+    let lines = announcedToolModelGateBySink.get(onNotice);
+    if (lines === undefined) {
+        lines = new Set();
+        announcedToolModelGateBySink.set(onNotice, lines);
+    }
+    return lines;
+}
+export function __resetToolModelGateAnnouncements() {
+    announcedToolModelGateBySink = new WeakMap();
+    announcedToolModelGateConsole.clear();
+}
+function announceToolModelGate(onNotice, modelId, gate) {
+    const ledger = toolModelGateLedger(onNotice);
+    for (const [gateClass, removed] of gate.removedByClass) {
+        const line = `Model gate: default-mounted tool(s) ${removed.map((n) => JSON.stringify(n)).join(", ")} (class ${JSON.stringify(gateClass)}) ` +
+            `were not mounted for model ${JSON.stringify(modelId)} — the gate table marks this model as managing multi-step work without the scaffold. ` +
+            `Explicitly composed tools are exempt; restore via TaskSpec.restoreGatedTools, SEMA_TOOL_MODEL_GATE=off, or RunnerDeps.toolModelGate: false.`;
+        if (!ledger.has(line)) {
+            ledger.add(line);
+            deliverEngineNotice(onNotice, {
+                code: "config.tool_model_gate_removed",
+                message: line,
+                detail: {
+                    modelId,
+                    gateClass,
+                    removed: [...removed],
+                    restore: { spec: "TaskSpec.restoreGatedTools", env: "SEMA_TOOL_MODEL_GATE=off", deps: "RunnerDeps.toolModelGate: false" },
+                },
+            });
+        }
+    }
+    for (const gateClass of gate.unknownClasses) {
+        const line = `ToolSpec.modelGate names gate class ${JSON.stringify(gateClass)}, which no row of the merged gate table defines — the tag is inert ` +
+            `(fail-open: the tool stays mounted). Fix the tag, or define the class via RunnerDeps.toolModelGate.classes.`;
+        if (!ledger.has(line)) {
+            ledger.add(line);
+            deliverEngineNotice(onNotice, { code: "config.tool_model_gate_unknown_class", message: line, detail: { gateClass } });
+        }
+    }
+    if (gate.discardedEnvRaw !== undefined) {
+        const line = `SEMA_TOOL_MODEL_GATE=${JSON.stringify(gate.discardedEnvRaw)} is not in the closed set (on|1|true|off|0|false, case-insensitive) — ` +
+            `not in force on this task (nothing the model gate would remove), but a task where the gate WOULD trim a default-mounted tool ` +
+            `will refuse to prepare under it (config.tool_model_gate_env_invalid). Fix or unset the flag.`;
+        if (!ledger.has(line)) {
+            ledger.add(line);
+            deliverEngineNotice(onNotice, { code: "config.tool_model_gate_env_invalid", message: line, detail: { raw: gate.discardedEnvRaw } });
+        }
+    }
+}
 const readFaceClampAnnouncedSinks = new WeakSet();
 let readFaceClampConsoleAnnounced = false;
 export function __resetReadFaceClampAnnouncement() {
@@ -153,8 +244,9 @@ export { rebaseWorkspacePath, rebaseWorkspacePathAcross } from "./prepare-worksp
 function hasConversationContent(branch) {
     return branch.some((e) => e.type === "message" || e.type === "custom_message" || e.type === "compaction");
 }
-function isDelegatedNonForkChild(internals) {
-    return internals?.isDelegatedChild === true && internals?.insideFork !== true;
+function effectiveDelegationFacts(internals, seedIsDelegatedChild) {
+    const isDelegatedChild = internals?.isDelegatedChild !== undefined ? internals.isDelegatedChild === true : seedIsDelegatedChild === true;
+    return { isDelegatedChild, isNonForkChild: isDelegatedChild && internals?.insideFork !== true };
 }
 export function batchContextAt(messages, currentId) {
     let batch = [];
@@ -238,6 +330,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
     const doors = prepareConfigDoors({ spec, deps, sessions, resume, internals });
     spec = doors.spec;
     const { toolFaceSnapshot, promptProfile, lockedPreflight, resolvedInteractionPosture, resolvedRole, model, thinking, compModel, fableMitigations, usageWindows, brainCallGuardrailRef, brainCallGuardrailMs } = doors;
+    announceToolModelGate(deps.onNotice, model.id, doors.modelGate);
     const { toolEffects, egressTools, irreversibleTools, irreversibilityTier, axisExplicitNegatives, reversibilityProbes, ownToolNames } = prepareSafetyScan({ spec, deps });
     let shellGatedBash = false;
     let shellGatedMonitor = false;
@@ -249,25 +342,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
     const { acquired, session, conflictRef, wakeRecovered, resumeAtBeforeParentId } = await prepareAcquireReconcile({ sessions, spec, resume, toolEffects, ...(() => { const g = durableParkGapFor(deps, spec); return g !== undefined ? { durableParkGap: g } : {}; })() });
     const sessionId = acquired.sessionId;
     const hostTaskId = spec.taskId ?? sessionId;
-    if (compModel !== undefined) {
-        const compWindow = compModel.contextTokens ?? compModel.contextWindow;
-        const mainWindow = model.autoCompactTokens ?? model.contextTokens ?? model.contextWindow;
-        if (compWindow > 0 && mainWindow > 0 && compWindow < mainWindow) {
-            const merged = { ...DEFAULT_COMPACTION_SETTINGS, ...spec.compaction };
-            const sanitized = sanitizeCompactionSettings(merged, mainWindow);
-            const tolerance = sanitized.clampTolerance ?? DEFAULT_CLAMP_TOLERANCE;
-            const headroom = Math.max(0, compWindow - Math.max(Math.floor(0.8 * summaryOutputBudgetTokens(compModel, sanitized)), 2048) - 512);
-            emitTrace(deps.tracer, () => ({
-                kind: "compaction.window_config_warning",
-                version: 1,
-                taskId: hostTaskId,
-                compactionModelWindow: compWindow,
-                mainModelWindow: mainWindow,
-                ...(tolerance < 1 ? { fallbackAt: Math.floor(headroom / (1 - tolerance)) } : {}),
-                ts: Date.now(),
-            }));
-        }
-    }
+    const delegation = effectiveDelegationFacts(internals, resume?.seed.isDelegatedChild);
+    warnCompactionWindowHazard(deps.tracer, spec, model, compModel, hostTaskId);
     const taskScope = internals?.registryScope ?? spec.principal ?? "default";
     internals?.peerSelfRef?.addAxis("s", sessionId);
     internals?.peerSelfRef?.addAxis("t", hostTaskId);
@@ -705,6 +781,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             excludeTools: toolFaceSnapshot.exclude,
             deferTools: toolFaceSnapshot.defer,
             alwaysLoadTools: toolFaceSnapshot.alwaysLoad,
+            ...(toolFaceSnapshot.restoreGated !== undefined ? { restoreGatedTools: toolFaceSnapshot.restoreGated } : {}),
             promptProfile,
             ...(spec.additionalDirectories !== undefined ? { additionalDirectories: Object.freeze([...spec.additionalDirectories]) } : {}),
             ...(spec.additionalReadDirectories !== undefined ? { additionalReadDirectories: Object.freeze([...spec.additionalReadDirectories]) } : {}),
@@ -876,6 +953,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 parentExcludeTools: toolFaceSnapshot.exclude,
                 parentDeferTools: toolFaceSnapshot.defer,
                 parentAlwaysLoadTools: toolFaceSnapshot.alwaysLoad,
+                ...(toolFaceSnapshot.restoreGated !== undefined ? { parentRestoreGatedTools: toolFaceSnapshot.restoreGated } : {}),
                 parentPromptProfile: promptProfile,
                 models: deps.models,
                 agents: deps.agents,
@@ -1581,7 +1659,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 orgMemoryDenied: complianceDenies.has("org_memory_mount"),
                 complianceDegraded,
                 parentAdmittedOrgScopes: foldAdmissionFreeze({
-                    delegated: internals?.isDelegatedChild === true ||
+                    delegated: delegation.isDelegatedChild ||
                         internals?.inheritedGate !== undefined ||
                         (resume?.seed.inheritedGate !== undefined &&
                             (resume.seed.inheritedGate.ancestorRules !== undefined ||
@@ -1650,7 +1728,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 loaded = await Promise.resolve(deps.loadProjectMemory({
                     cwd: taskRootFinal,
                     handsEnabled,
-                    isSubagent: isDelegatedNonForkChild(internals),
+                    isSubagent: delegation.isNonForkChild,
                     ...(internals?.agentName ? { agentName: internals.agentName } : {}),
                     sessionId,
                     phase: projectMemoryPhase,
@@ -1775,7 +1853,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             awarenessEnabled: thinking !== undefined && ULTRA_REASONING_TIERS.has(thinking),
             worktreeIsolated: internals?.isolation === "worktree" && ownedEnv !== undefined,
             withinTaskCompactionEnabled: (spec.compaction?.enabled ?? true) && (spec.compaction?.withinTask ?? true),
-            isSubagent: isDelegatedNonForkChild(internals),
+            isSubagent: delegation.isNonForkChild,
         };
         const userSystemPrompt = spec.systemPrompt ?? resolvedRole.systemPrompt ?? internals?.defaultSystemPrompt;
         const userAppendSystemPrompt = spec.appendSystemPrompt;
@@ -2209,10 +2287,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             const raw = process.env.SEMA_TOOL_MATERIALIZE_STRATEGY;
             if (raw !== undefined && raw !== "swap" && raw !== "static" && deferred.size === 0) {
                 const line = `SEMA_TOOL_MATERIALIZE_STRATEGY=${JSON.stringify(raw)} is not "swap" or "static" — inert on this task (no deferred tools), but a deferring task WITHOUT an explicit spec strategy will refuse to prepare under it (an explicit legal spec outranks and discards it, loudly). Fix or unset the flag.`;
-                if (!announcedMaterializeEnv.has(line)) {
-                    announcedMaterializeEnv.add(line);
-                    emitMaterializeEnvNotice(deps.onNotice, line, { raw });
-                }
+                emitMaterializeEnvNotice(deps.onNotice, line, { raw });
             }
         }
         if (deferred.size > 0) {
@@ -2231,10 +2306,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             }
             if (envStrategyInvalid) {
                 const line = `SEMA_TOOL_MATERIALIZE_STRATEGY=${JSON.stringify(rawEnvStrategy)} was ignored — not "swap" or "static", and the task spec pins toolMaterializeStrategy=${JSON.stringify(spec.toolMaterializeStrategy)} which outranks it. Fix or unset the env flag.`;
-                if (!announcedMaterializeEnv.has(line)) {
-                    announcedMaterializeEnv.add(line);
-                    emitMaterializeEnvNotice(deps.onNotice, line, { raw: rawEnvStrategy, specStrategy: spec.toolMaterializeStrategy });
-                }
+                emitMaterializeEnvNotice(deps.onNotice, line, { raw: rawEnvStrategy, specStrategy: spec.toolMaterializeStrategy });
             }
             const envStrategy = envStrategyInvalid ? undefined : rawEnvStrategy;
             const requestedStrategy = spec.toolMaterializeStrategy ?? envStrategy ?? "swap";
@@ -2785,7 +2857,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             ...((internals?.explicitAgentName ?? internals?.agentName) !== undefined
                 ? { sourceAgentName: internals?.explicitAgentName ?? internals?.agentName }
                 : {}),
-            ...(internals?.isDelegatedChild === true ? { isDelegatedChild: true } : {}),
+            ...(delegation.isDelegatedChild ? { isDelegatedChild: true } : {}),
         });
         const riskAxesOf = (toolName) => {
             const tier = irreversibilityTier.get(toolName);
@@ -3347,6 +3419,15 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             retentionPolicyWired: deps.retentionPolicy !== undefined,
         });
         const parkLaneArmed = wiringManifest.parkLane.effective === true;
+        const hookIdentity = mintHookInvocationIdentity({
+            sessionId,
+            taskId: spec.taskId ?? sessionId,
+            legKind: wiringManifest.leg.kind,
+            isDelegatedChild: delegation.isDelegatedChild,
+            ...(internals?.insideFork === true ? { insideFork: true } : {}),
+            ...(internals?.agentName !== undefined ? { agentName: internals.agentName } : {}),
+            ...(internals?.parentToolCallId !== undefined ? { parentToolCallId: internals.parentToolCallId } : {}),
+        });
         const hookContextConsumerWired = hooks?.preToolUse !== undefined || hooks?.postToolUse !== undefined || hooks?.postToolUseFailure !== undefined;
         const hookEnvFace = hookContextConsumerWired && (ownedEnv ?? deps.executionEnv) != null ? createHookEnvCapabilities(executionEnv) : undefined;
         if (effectivePolicy || hooks?.preToolUse || egressTools.size > 0 || irreversibleTools.size > 0 || resourceSuspendEligible || platformSuspendArmed || spec.enablePlanMode === true) {
@@ -3556,6 +3637,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     : undefined,
                 gitAnnouncement: gitStatusRef.announced !== undefined ? { ...gitStatusRef.announced } : undefined,
                 delegationProvenance: internals?.delegationProvenance !== undefined ? { ...internals.delegationProvenance.ref.current } : undefined,
+                isDelegatedChild: hookIdentity.isDelegatedChild ? true : undefined,
             });
             const commitSuspendSaga = async (token, cp, remoteEnv, remoteHandle) => {
                 if (!checkpointStore)
@@ -4155,7 +4237,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             if (blockedTracked)
                                 blockedToolCalls.add(e.toolCallId);
                             if (notifyPermissionDenied) {
-                                await notifyPermissionDenied({ toolName: e.toolName, input: cloneObserverInput(e.input), toolCallId: e.toolCallId, reason: complianceDeny, source: "safety" });
+                                await notifyPermissionDenied({ toolName: e.toolName, input: cloneObserverInput(e.input), toolCallId: e.toolCallId, reason: complianceDeny, source: "safety", identity: hookIdentity });
                             }
                             return { block: true, reason: formatHookFeedback(complianceDeny), preToolContext: [] };
                         }
@@ -4166,7 +4248,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         const planDenyReason = `Plan mode is active — "${e.toolName}" is a write/mutating tool and is read-only-blocked. ` +
                             `Research with read-only tools, then call ${PRESENT_PLAN_TOOL_NAME} with your plan to get it approved before acting.`;
                         if (notifyPermissionDenied) {
-                            await notifyPermissionDenied({ toolName: e.toolName, input: cloneObserverInput(e.input), toolCallId: e.toolCallId, reason: planDenyReason, source: "planMode" });
+                            await notifyPermissionDenied({ toolName: e.toolName, input: cloneObserverInput(e.input), toolCallId: e.toolCallId, reason: planDenyReason, source: "planMode", identity: hookIdentity });
                         }
                         return {
                             block: true,
@@ -4179,6 +4261,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         result = await runToolGate({
                             onNotifyError: (f) => emitTrace(deps.tracer, () => ({ kind: "observer.notify_failed", version: 1, taskId: spec.taskId ?? sessionId, site: f.site, message: f.error.message, ts: Date.now() })),
                             event: e,
+                            identity: hookIdentity,
                             preToolUse: ownGatePreToolUse,
                             ...(hookEnvFace !== undefined ? { hookEnv: hookEnvFace } : {}),
                             adjudicate,
@@ -4291,7 +4374,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             isInterrupt: abortController.signal.aborted || spec.signal?.aborted === true,
                             content: e.content.map((c) => ({ ...c })),
                             details: clonedDetails,
-                        }, { toolCallId: e.toolCallId, toolName: e.toolName, ...(hookEnvFace !== undefined ? { env: hookEnvFace } : {}) });
+                        }, { toolCallId: e.toolCallId, toolName: e.toolName, ...(hookEnvFace !== undefined ? { env: hookEnvFace } : {}), identity: hookIdentity });
                         if (patch?.additionalContext) {
                             content = [...content, { type: "text", text: formatHookFeedback(patch.additionalContext) }];
                             changed = true;
@@ -4299,7 +4382,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     }
                 }
                 else if (hooks?.postToolUse) {
-                    const patch = await hooks.postToolUse(e.toolName, e.input, { content: e.content, details: e.details, isError: e.isError }, { toolCallId: e.toolCallId, toolName: e.toolName, ...(hookEnvFace !== undefined ? { env: hookEnvFace } : {}) });
+                    const patch = await hooks.postToolUse(e.toolName, e.input, { content: e.content, details: e.details, isError: e.isError }, { toolCallId: e.toolCallId, toolName: e.toolName, ...(hookEnvFace !== undefined ? { env: hookEnvFace } : {}), identity: hookIdentity });
                     if (patch?.updatedOutput) {
                         content = patch.updatedOutput;
                         changed = true;
@@ -4586,7 +4669,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const effectiveReadFaceObserved = carrierReadFace();
         const effectiveReadDenyObserved = readDenyAdditionsNormalized.length > 0 ? readDenyAdditionsNormalized.map((e) => ({ ...e })) : undefined;
         const preparedHolder = {};
-        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath: taskRootFinal, model, thinking, compModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, approvalSettlement, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), ...(effectiveReadFaceObserved !== undefined ? { effectiveReadFace: effectiveReadFaceObserved } : {}), ...(effectiveReadDenyObserved !== undefined ? { effectiveReadDenyPatterns: effectiveReadDenyObserved } : {}), effectiveMemoryScopes: memoryEffectiveScopes, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), ...(permissionRuleOrgLane !== undefined ? { permissionRuleOrg: permissionRuleOrgLane } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, suspendRef, suspendProgressRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, gitStatusRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath: taskRootFinal, model, thinking, compModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, approvalSettlement, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), ...(effectiveReadFaceObserved !== undefined ? { effectiveReadFace: effectiveReadFaceObserved } : {}), ...(effectiveReadDenyObserved !== undefined ? { effectiveReadDenyPatterns: effectiveReadDenyObserved } : {}), effectiveMemoryScopes: memoryEffectiveScopes, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), ...(permissionRuleOrgLane !== undefined ? { permissionRuleOrg: permissionRuleOrgLane } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, suspendRef, suspendProgressRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, gitStatusRef, listBackgroundTasks, hookIdentity, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         const prepared = buildPrepared();
         preparedHolder.current = prepared;
         return prepared;

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/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;