@sema-agent/core 6.0.0 → 7.0.1

package/dist/agents/subagent.js

@@ -37,10 +37,27 @@ function delegatedCostField(stats) {
     const total = rollupDelegatedCost(stats, stats.nested);
     return total !== undefined ? { costMicroUsd: total } : {};
 }
+export function delegatedGranularityFields(stats, elapsedMs) {
+    return { ...(stats.toolCalls !== undefined ? { toolUses: stats.toolCalls } : {}), durationMs: elapsedMs };
+}
+function providerFaultField(child) {
+    if (child.apiFailure === undefined)
+        return {};
+    return {
+        apiFailure: {
+            ...(typeof child.apiFailure.status === "number" ? { status: child.apiFailure.status } : {}),
+            ...(typeof child.apiFailure.requestId === "string" ? { requestId: child.apiFailure.requestId } : {}),
+        },
+    };
+}
+export function delegatedGranularityFieldsWire(stats, elapsedMs) {
+    return { ...(stats.toolCalls !== undefined ? { tool_uses: stats.toolCalls } : {}), duration_ms: elapsedMs };
+}
 export { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX };
 import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getOrCreateSessionRetainLedger, ensureSessionReapHook, createResumePrompt, } from "./retain-ledger.js";
 import { createPeerInboundChainRef, createPeerSelfRef } from "./peer-admission.js";
 import { recordRosterSpawn } from "./roster-store.js";
+import { LAUNCH_RECEIPT_OWN_WORDS_CLAUSE, launchReceiptNoQuoteClause } from "./launch-receipt-contract.js";
 import { ObserverDigestTap, ObserverPairing, createObserverReportToolSpec, markObserverTaskId, unmarkObserverTaskId, isObserverTaskId, ObserverResumeStateError, ObserverStoppedByUserError, observerFramingPrompt, observerSlug, resolveObserverDeclaration, } from "./observer.js";
 import { SubagentStepRecorder } from "./subagent-steps.js";
 const BG_AGENT_RESULT_MAX = 4_000;
@@ -326,6 +343,7 @@ function resumabilityClaim(f) {
 const BG_AGENT_COLLATERAL_REAP_REASON = "its parent run ended";
 const RESERVED_AGENT_NAMES = new Set([OUTPUT_TOOL_NAME, TOOL_SEARCH_NAME, OFFLOAD_TOOL_NAME, REPORT_BLOCKED_TOOL_NAME, DEFAULT_SUBAGENT_TOOL_NAME]);
 export const REPORT_FIELD_MAX = 300;
+const ROSTER_ECHO_MAX = 400;
 function configError(message, code) {
     const e = new Error(message);
     e.code = code;
@@ -364,6 +382,7 @@ export function completedAgentCard(child, extras) {
         ...(child.blockedReason !== undefined ? { blockedReason: child.blockedReason } : {}),
         ...(child.errorMessage !== undefined ? { errorMessage: child.errorMessage } : {}),
         ...(child.errorCode !== undefined ? { errorCode: child.errorCode } : {}),
+        ...providerFaultField(child),
         ...(child.retryAfterMs !== undefined ? { retryAfterMs: child.retryAfterMs } : {}),
         ...(child.degraded !== undefined ? { degraded: child.degraded } : {}),
         ...(extras.handbackWarning !== undefined ? { handbackWarning: extras.handbackWarning } : {}),
@@ -711,9 +730,10 @@ export function createSubagentResume(deps) {
                 const completionIdRevive = deps.registry?.getCompletionId(deps.taskId ?? "");
                 const reviveName = deps.rowDescription ?? `sub-agent ${marker}`;
                 const failReasonRevive = status === "failed" ? child.errorMessage : undefined;
+                const reviveElapsedMs = Date.now() - reviveStartedAt;
                 const reviveTerminalSummary = failReasonRevive !== undefined
-                    ? `Agent "${reviveName}" (resumed) failed: ${failReasonRevive}${ccElapsedTag(Date.now() - reviveStartedAt)}`.slice(0, 300) + errorKindClause(errClassRevive)
-                    : `Agent "${reviveName}" (resumed) ${status === "killed" ? "stopped" : child.status === "completed" ? "finished" : String(child.status)}${ccElapsedTag(Date.now() - reviveStartedAt)}`;
+                    ? `Agent "${reviveName}" (resumed) failed: ${failReasonRevive}${ccElapsedTag(reviveElapsedMs)}`.slice(0, 300) + errorKindClause(errClassRevive)
+                    : `Agent "${reviveName}" (resumed) ${status === "killed" ? "stopped" : child.status === "completed" ? "finished" : String(child.status)}${ccElapsedTag(reviveElapsedMs)}`;
                 const reviveDurableProbe = deps.registry !== undefined && deps.taskId !== undefined ? deps.registry.durableAgentRowProbe(deps.taskId) : undefined;
                 const reviveDurableRow = reviveDurableProbe !== undefined ? await reviveDurableProbe().catch(() => false) : false;
                 const resumableRevive = resumabilityClaim({
@@ -739,7 +759,7 @@ export function createSubagentResume(deps) {
                         summary: reviveTerminalSummary,
                         ...resumeResidual(),
                         resumable: resumableRevive,
-                        usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats) },
+                        usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats), ...delegatedGranularityFields(child.stats, reviveElapsedMs) },
                         ...(completionIdRevive !== undefined ? { completionId: completionIdRevive } : {}),
                     });
                 const resumeFrame = {
@@ -753,11 +773,12 @@ export function createSubagentResume(deps) {
                     summary: reviveTerminalSummary,
                     ...(failReasonRevive !== undefined ? { error: failReasonRevive.slice(0, REPORT_FIELD_MAX) } : {}),
                     ...(status === "failed" && errCodeRevive !== undefined ? { errorCode: errCodeRevive } : {}),
+                    ...providerFaultField(child),
                     ...(resumeHandbackResult ? { result: notifyResultField(resumeHandbackResult) } : {}),
                     ...(status === "killed" && child.result ? { partial: true } : {}),
                     ...resumeResidual(),
                     resumable: resumableRevive,
-                    usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats) },
+                    usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats), ...delegatedGranularityFieldsWire(child.stats, reviveElapsedMs) },
                     ...(completionIdRevive !== undefined ? { completionId: completionIdRevive } : {}),
                 };
                 const gateOwner = ownsTerminalFacesRevive && status === "completed" && deps.notify !== undefined && deps.registry !== undefined && ledger.get(deps.parentToolCallId) === entry
@@ -1206,7 +1227,7 @@ export function forkWorktreeTranslationNote(parentCwd, worktreeDir) {
 export function asyncLaunchedReceipt(p) {
     const noteLines = (p.notes ?? []).filter((n) => n !== undefined && n !== "");
     const oneShotBlocked = p.notify && p.oneShot === true;
-    return (`Async agent launched successfully. (This tool result is internal metadata — never quote or paste any part of it, including the task_id below, into a user-facing reply.)\n` +
+    return (`Async agent launched successfully. (${launchReceiptNoQuoteClause(", including the task_id below,")})\n` +
         `task_id: ${p.taskId} (internal ID - do not mention to user. Use SendMessage with to: '${p.taskId}', summary: '<5-10 word recap>' to continue this agent.)\n` +
         (oneShotBlocked
             ? `${p.workingLine} This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput(task_id: "${p.taskId}", block: true). If it is still running after the wait, wait again (bounded) rather than ending the turn, or write out your best available answer now if you are near your own time budget.\n`
@@ -1215,10 +1236,18 @@ export function asyncLaunchedReceipt(p) {
                 : `${p.workingLine} Its result is NOT pushed automatically — retrieve progress and results with TaskOutput(task_id) where mounted.\n`) +
         noteLines.map((n) => `${n}\n`).join("") +
         (oneShotBlocked
-            ? `In your own words, briefly tell the user what you launched — do not echo this tool result. Do not assume a later message will deliver the result: this submission ends after this turn, so retrieve it now with the blocking TaskOutput wait above before writing your final answer.`
+            ? `${LAUNCH_RECEIPT_OWN_WORDS_CLAUSE} Do not assume a later message will deliver the result: this submission ends after this turn, so retrieve it now with the blocking TaskOutput wait above before writing your final answer.`
             : p.notify
-                ? `In your own words, briefly tell the user what you launched — do not echo this tool result. Agent results will arrive in a subsequent message. If the user asks for progress, say the agent is still running.`
-                : `In your own words, briefly tell the user what you launched — do not echo this tool result. The result will NOT arrive on its own — retrieve it with TaskOutput(task_id) where mounted before relying on it.`));
+                ? `${LAUNCH_RECEIPT_OWN_WORDS_CLAUSE} Agent results will arrive in a subsequent message. If the user asks for progress, say the agent is still running.`
+                : `${LAUNCH_RECEIPT_OWN_WORDS_CLAUSE} The result will NOT arrive on its own — retrieve it with TaskOutput(task_id) where mounted before relying on it.`));
+}
+function runnerModelCatalog(runner) {
+    try {
+        return runner?.agentCatalog?.models;
+    }
+    catch {
+        return undefined;
+    }
 }
 export function createSubagentTool(opts) {
     const catalog = opts.runner.agentCatalog;
@@ -1227,8 +1256,7 @@ export function createSubagentTool(opts) {
     if (opts.builtinAgents === undefined && catalog?.builtinAgents !== undefined) {
         opts = { ...opts, builtinAgents: catalog.builtinAgents };
     }
-    if (opts.models === undefined && catalog?.models)
-        opts = { ...opts, models: catalog.models };
+    const assemblyModels = opts.models ?? catalog?.models;
     if (opts.agents?.length) {
         opts = {
             ...opts,
@@ -1252,7 +1280,7 @@ export function createSubagentTool(opts) {
             }
             if (typeof a.model === "string") {
                 try {
-                    resolveModel(a.model, opts.models);
+                    resolveModel(a.model, assemblyModels);
                 }
                 catch {
                     throw configError(`createSubagentTool: agent "${a.name}" references unknown model "${a.model}" (pass \`models\` to resolve string refs).`, "config.agent.unknown_model");
@@ -1308,7 +1336,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
         ...(forkOffered ? [FORK_SUBAGENT_TYPE] : []),
         ...(generalPurposeShadowed ? [] : [GENERAL_PURPOSE_SUBAGENT_TYPE]),
     ];
-    const rosterNames = opts.models ? Object.keys(opts.models) : undefined;
+    const activeModels = () => opts.models ?? runnerModelCatalog(opts.runner);
+    const mountModels = activeModels();
+    const rosterNames = mountModels ? Object.keys(mountModels) : undefined;
     const agentListing = [
         ...(generalPurposeShadowed
             ? []
@@ -1424,7 +1454,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             })),
             model: Type.Optional(Type.String({
                 description: rosterNames !== undefined && rosterNames.length > 0
-                    ? `Optional model override for this agent. Takes precedence over the agent definition's model. If omitted, uses the agent definition's model, or inherits from the parent. Ignored for subagent_type: "${FORK_SUBAGENT_TYPE}" — forks always inherit the parent model.`
+                    ? `Optional model override for this agent. Takes precedence over the agent definition's model. If omitted, uses the agent definition's model, or inherits from the parent. A value outside this deployment's model catalog is REFUSED — the call does not fall back silently. Ignored for subagent_type: "${FORK_SUBAGENT_TYPE}" — forks always inherit the parent model.`
                     : `Optional model override request. No model catalog is configured here, so a requested name cannot be resolved — the agent runs its definition's model (or inherits from the parent) and the result notes the override was not applied. Ignored for subagent_type: "${FORK_SUBAGENT_TYPE}".`,
             })),
             isolation: Type.Optional(Type.Literal("worktree", {
@@ -1560,23 +1590,54 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     };
                 }
             }
+            if (typeof a.model === "string" && a.model.trim() === "" && !wantsFork && reviveClaim === undefined) {
+                return {
+                    isError: true,
+                    content: "Sub-agent not started: `model` was empty. Name a model from this deployment's catalog, or omit the parameter to run the agent type's own model.",
+                    details: { error: "model.empty" },
+                };
+            }
             const requestedModel = typeof a.model === "string" && a.model.trim() !== "" ? a.model.trim() : undefined;
             let perCallModel;
             let modelNote;
-            if (requestedModel !== undefined) {
+            const judgedModels = activeModels();
+            const rosterKeys = judgedModels !== undefined ? Object.keys(judgedModels) : [];
+            if (typeof a.model === "string" && requestedModel === undefined) {
+                modelNote = wantsFork
+                    ? `note: model "" was ignored — a fork always runs on the caller's model.`
+                    : `note: the durable record's model was blank and was NOT applied — the revived agent ran on its default (inherited) model.`;
+            }
+            else if (requestedModel !== undefined) {
                 if (wantsFork) {
                     modelNote = `note: model "${requestedModel}" was ignored — a fork always runs on the caller's model.`;
                 }
-                else if (!opts.models) {
+                else if (rosterKeys.length === 0) {
                     modelNote = `note: model "${requestedModel}" was NOT applied — this delegation tool has no model roster configured; the sub-agent ran on its default (inherited) model.`;
                 }
                 else {
                     try {
-                        resolveModel(requestedModel, opts.models);
-                        perCallModel = requestedModel;
+                        perCallModel = resolveModel(requestedModel, judgedModels);
                     }
                     catch {
-                        modelNote = `note: model "${requestedModel}" was NOT applied — unknown model (roster: ${Object.keys(opts.models).join(", ")}); the sub-agent ran on its default (inherited) model.`;
+                        if (reviveClaim !== undefined) {
+                            modelNote = `note: recorded model "${inlineUntrusted(requestedModel, 80)}" is not on the current model roster and was NOT applied — the revived agent ran on its default (inherited) model.`;
+                        }
+                        else {
+                            const shown = [];
+                            let budget = ROSTER_ECHO_MAX;
+                            for (const k of rosterKeys) {
+                                if (budget - k.length < 0)
+                                    break;
+                                shown.push(k);
+                                budget -= k.length + 2;
+                            }
+                            const rosterEcho = shown.length === rosterKeys.length ? shown.join(", ") : `${shown.join(", ")}, … (${rosterKeys.length - shown.length} more)`;
+                            return {
+                                isError: true,
+                                content: `Sub-agent not started: unknown model "${inlineUntrusted(requestedModel, 80)}". Available model values: ${inlineUntrusted(rosterEcho, ROSTER_ECHO_MAX + 32)}. Omit \`model\` to run the agent type's own model, or inherit the caller's.`,
+                                details: { error: "model.unknown" },
+                            };
+                        }
                     }
                 }
             }
@@ -1690,9 +1751,39 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             const childTools = def
                 ? resolveToolSubset(childPool, def.allowTools, def.denyTools)
                 : resolveToolSubset(childPool, opts.allowTools, opts.denyTools);
-            const childModel = wantsFork
+            let childModel = wantsFork
                 ? ctx.model ?? opts.model
                 : perCallModel ?? (def ? (def.model ?? ctx.model ?? opts.model) : opts.model);
+            if (reviveClaim !== undefined && typeof childModel === "string") {
+                const resolvable = (ref) => {
+                    try {
+                        resolveModel(ref, runnerModelCatalog(opts.runner));
+                        return true;
+                    }
+                    catch {
+                        return false;
+                    }
+                };
+                if (!resolvable(childModel)) {
+                    const dead = childModel;
+                    const rest = def !== undefined ? [ctx.model, opts.model] : [opts.model];
+                    childModel = rest.find((c) => c !== undefined && (typeof c !== "string" || resolvable(c)));
+                    if (modelNote === undefined) {
+                        modelNote = `note: model "${inlineUntrusted(dead, 80)}" from this agent type's configuration is not on the current model roster and was NOT applied — the revived agent ran on its default (inherited) model.`;
+                    }
+                }
+            }
+            const spawnModel = typeof childModel === "string"
+                ? (() => {
+                    try {
+                        return resolveModel(childModel, judgedModels).id;
+                    }
+                    catch {
+                        return resolveModelDisplayLabel(childModel);
+                    }
+                })()
+                : childModel?.id;
+            const rowModelKey = perCallModel !== undefined ? requestedModel : typeof childModel === "string" ? childModel : childModel?.id;
             const childSystemPrompt = def?.systemPrompt ?? opts.systemPrompt;
             const childDefaultPersona = childSystemPrompt === undefined && !wantsFork ? SUBAGENT_PROMPT : undefined;
             const defMaxTurns = typeof def?.maxTurns === "number" && Number.isFinite(def.maxTurns) && def.maxTurns > 0 ? def.maxTurns : undefined;
@@ -2342,7 +2433,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ...(ctx.taskId !== undefined && ctx.taskId !== ctx.sessionId ? { parentTaskId: ctx.taskId } : {}),
                             ...(ctx.sessionId !== undefined ? { parentSessionId: ctx.sessionId } : {}),
                             ...((ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}),
-                            ...((typeof childModel === "string" ? resolveModelDisplayLabel(childModel) : childModel?.id) !== undefined ? { model: typeof childModel === "string" ? childModel : childModel?.id } : {}),
+                            ...(rowModelKey !== undefined ? { model: rowModelKey } : {}),
                             deliveryChannel: "attaching",
                             toolUseId: ctx.toolCallId,
                             ...(bg.agentStore !== undefined ? { store: bg.agentStore } : {}),
@@ -2403,7 +2494,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         }, { priority: "next" }), "subagent.reapTerminalNotify");
                     });
                     if (agentName !== undefined) {
-                        recordRosterSpawn(ctx.roster, { name: agentName, agentId: taskId, sessionId: forkedId, toolUseId: ctx.toolCallId, owner: bgOwner, scope: bgScope, ...((typeof childModel === "string" ? resolveModelDisplayLabel(childModel) : childModel?.id) !== undefined ? { model: typeof childModel === "string" ? childModel : childModel?.id } : {}), ...(modelFallback !== undefined ? { modelFallback } : {}), ...((ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}), ...(sessionScopedBg ? { sessionScoped: true } : {}), createdAt: Date.now() }, (err) => opts.onObserverError?.(err, { site: "roster.recordSpawn" }));
+                        recordRosterSpawn(ctx.roster, { name: agentName, agentId: taskId, sessionId: forkedId, toolUseId: ctx.toolCallId, owner: bgOwner, scope: bgScope, ...(rowModelKey !== undefined ? { model: rowModelKey } : {}), ...(modelFallback !== undefined ? { modelFallback } : {}), ...((ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}), ...(sessionScopedBg ? { sessionScoped: true } : {}), createdAt: Date.now() }, (err) => opts.onObserverError?.(err, { site: "roster.recordSpawn" }));
                     }
                     const bgSink = ctx.onBackgroundChildEvent;
                     const sinkEmit = (event) => {
@@ -2422,6 +2513,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         ...(bgScope !== undefined ? { scope: bgScope } : {}),
                         description: shortDesc,
                         agentType: spawnAgentType,
+                        ...(spawnModel !== undefined ? { model: spawnModel } : {}),
                         ...(bgForkCycleSeq !== undefined ? { seq: bgForkCycleSeq } : {}),
                         ...(agentName !== undefined ? { name: agentName } : {}),
                         sessionId: forkedId,
@@ -2451,6 +2543,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             parentToolCallId: ctx.toolCallId,
                             progressTaskId: forkedId,
                             agentType: spawnAgentType,
+                            ...(spawnModel !== undefined ? { model: spawnModel } : {}),
                             ...(bgForkCycleSeq !== undefined ? { seq: bgForkCycleSeq } : {}),
                             ...(currentAction !== undefined ? { currentAction } : {}),
                             ...(currentTool !== undefined ? { currentTool } : {}),
@@ -2485,6 +2578,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                         progressTaskId: e.taskId,
                                         ...(e.parentTaskId !== undefined ? { progressParentTaskId: e.parentTaskId } : {}),
                                         agentType: spawnAgentType,
+                                        ...(spawnModel !== undefined ? { model: spawnModel } : {}),
                                         ...(e.name !== undefined ? { name: e.name } : {}),
                                         ...(currentAction !== undefined ? { currentAction } : {}),
                                         ...(currentTool !== undefined ? { currentTool } : {}),
@@ -2562,9 +2656,10 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         const resumableFork = false;
                         const forkTranscriptId = child.sessionId ?? forkedId;
                         const failReasonFork = settledBg === "failed" ? child.errorMessage : undefined;
+                        const forkElapsedMs = Date.now() - forkBgStartedAt;
                         const forkTerminalSummary = failReasonFork !== undefined
-                            ? `Agent "${shortDesc}" failed: ${failReasonFork}${ccElapsedTag(Date.now() - forkBgStartedAt)}`.slice(0, 300) + errorKindClause(errClassFork)
-                            : `${ccCompletionText(shortDesc, settledBg, String(child.status), Date.now() - forkBgStartedAt)}`;
+                            ? `Agent "${shortDesc}" failed: ${failReasonFork}${ccElapsedTag(forkElapsedMs)}`.slice(0, 300) + errorKindClause(errClassFork)
+                            : `${ccCompletionText(shortDesc, settledBg, String(child.status), forkElapsedMs)}`;
                         const ownsTerminalFacesFork = bg.registry.claimAgentTerminalNotify(taskId);
                         if (ownsTerminalFacesFork)
                             sinkEmit({
@@ -2580,7 +2675,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                 summary: forkTerminalSummary,
                                 ...residualFork,
                                 resumable: resumableFork,
-                                usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats) },
+                                usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats), ...delegatedGranularityFields(child.stats, forkElapsedMs) },
                                 ...(completionIdFork !== undefined ? { completionId: completionIdFork } : {}),
                             });
                         try {
@@ -2594,12 +2689,13 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                     summary: forkTerminalSummary,
                                     ...(failReasonFork !== undefined ? { error: failReasonFork.slice(0, REPORT_FIELD_MAX) } : {}),
                                     ...(settledBg === "failed" && errCodeFork !== undefined ? { errorCode: errCodeFork } : {}),
+                                    ...providerFaultField(child),
                                     ...(child.sessionId ? { sessionId: child.sessionId } : {}),
                                     ...(forkBgResult ? { result: notifyResultField(forkBgResult) } : {}),
                                     ...(settledBg === "killed" && child.result ? { partial: true } : {}),
                                     ...residualFork,
                                     resumable: resumableFork,
-                                    usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats) },
+                                    usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats), ...delegatedGranularityFieldsWire(child.stats, forkElapsedMs) },
                                     ...(completionIdFork !== undefined ? { completionId: completionIdFork } : {}),
                                 }, { priority: "next" });
                         }
@@ -2912,7 +3008,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ...(ctx.taskId !== undefined && ctx.taskId !== ctx.sessionId ? { parentTaskId: ctx.taskId } : {}),
                             ...(ctx.sessionId !== undefined ? { parentSessionId: ctx.sessionId } : {}),
                             ...((ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}),
-                            ...((typeof childModel === "string" ? resolveModelDisplayLabel(childModel) : childModel?.id) !== undefined ? { model: typeof childModel === "string" ? childModel : childModel?.id } : {}),
+                            ...(rowModelKey !== undefined ? { model: rowModelKey } : {}),
                             deliveryChannel: "attaching",
                             toolUseId: ctx.toolCallId,
                             ...(bg.agentStore !== undefined ? { store: bg.agentStore } : {}),
@@ -2936,7 +3032,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     chargeDelegationEntryHandle(bg.registry, capLedgerKey, bg.agentStore, reviveRow === undefined ? taskId : undefined);
                 childInternals.peerSelfRef?.addAxis("h", taskId);
                 if (agentName !== undefined) {
-                    recordRosterSpawn(ctx.roster, { name: agentName, agentId: taskId, toolUseId: ctx.toolCallId, owner: bgOwner, scope: bgScope, ...((typeof childModel === "string" ? resolveModelDisplayLabel(childModel) : childModel?.id) !== undefined ? { model: typeof childModel === "string" ? childModel : childModel?.id } : {}), ...(reviveRow !== undefined ? ((reviveRow.rootSessionId ?? reviveRow.parentSessionId) !== undefined ? { rootSessionId: reviveRow.rootSessionId ?? reviveRow.parentSessionId } : {}) : (ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}), ...(sessionScopedBg ? { sessionScoped: true } : {}), createdAt: reviveRow?.spawnedAt ?? Date.now() }, (err) => opts.onObserverError?.(err, { site: "roster.recordSpawn" }));
+                    recordRosterSpawn(ctx.roster, { name: agentName, agentId: taskId, toolUseId: ctx.toolCallId, owner: bgOwner, scope: bgScope, ...(reviveRow !== undefined ? (reviveRow.model !== undefined ? { model: reviveRow.model } : {}) : rowModelKey !== undefined ? { model: rowModelKey } : {}), ...(modelFallback !== undefined ? { modelFallback } : {}), ...(reviveRow !== undefined ? ((reviveRow.rootSessionId ?? reviveRow.parentSessionId) !== undefined ? { rootSessionId: reviveRow.rootSessionId ?? reviveRow.parentSessionId } : {}) : (ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}), ...(sessionScopedBg ? { sessionScoped: true } : {}), createdAt: reviveRow?.spawnedAt ?? Date.now() }, (err) => opts.onObserverError?.(err, { site: "roster.recordSpawn" }));
                 }
                 const bgSink = ctx.onBackgroundChildEvent;
                 const sinkEmit = (event) => {
@@ -2992,6 +3088,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     ...(bgScope !== undefined ? { scope: bgScope } : {}),
                     description: reviveRow !== undefined ? `${shortDesc} (revived)` : shortDesc,
                     agentType: spawnAgentType,
+                    ...(spawnModel !== undefined ? { model: spawnModel } : {}),
                     ...(bgCycleSeq !== undefined ? { seq: bgCycleSeq } : {}),
                     ...(agentName !== undefined ? { name: agentName } : {}),
                     sessionId: bgChildSessionId,
@@ -3065,6 +3162,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         parentToolCallId: ctx.toolCallId,
                         progressTaskId: bgChildSessionId,
                         agentType: spawnAgentType,
+                        ...(spawnModel !== undefined ? { model: spawnModel } : {}),
                         ...(bgCycleSeq !== undefined ? { seq: bgCycleSeq } : {}),
                         ...(currentAction !== undefined ? { currentAction } : {}),
                         ...(currentTool !== undefined ? { currentTool } : {}),
@@ -3111,6 +3209,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                     progressTaskId: e.taskId,
                                     ...(e.parentTaskId !== undefined ? { progressParentTaskId: e.parentTaskId } : {}),
                                     agentType: spawnAgentType,
+                                    ...(spawnModel !== undefined ? { model: spawnModel } : {}),
                                     ...(e.name !== undefined ? { name: e.name } : {}),
                                     ...(currentAction !== undefined ? { currentAction } : {}),
                                     ...(currentTool !== undefined ? { currentTool } : {}),
@@ -3399,9 +3498,10 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         named: agentName !== undefined,
                     });
                     const failReasonBg = settled === "failed" ? unparkedPauseReason ?? child.errorMessage : undefined;
+                    const bgElapsedMs = Date.now() - bgStartedAt;
                     const bgTerminalSummary = failReasonBg !== undefined
-                        ? `Agent "${shortDesc}" failed: ${failReasonBg}${ccElapsedTag(Date.now() - bgStartedAt)}${observerNote}`.slice(0, 300) + errorKindClause(errClassBg)
-                        : `${ccCompletionText(shortDesc, settled, String(child.status), Date.now() - bgStartedAt)}${observerNote}`;
+                        ? `Agent "${shortDesc}" failed: ${failReasonBg}${ccElapsedTag(bgElapsedMs)}${observerNote}`.slice(0, 300) + errorKindClause(errClassBg)
+                        : `${ccCompletionText(shortDesc, settled, String(child.status), bgElapsedMs)}${observerNote}`;
                     const ownsTerminalFaces = bg.registry.claimAgentTerminalNotify(taskId);
                     if (ownsTerminalFaces)
                         sinkEmit({
@@ -3416,7 +3516,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             summary: bgTerminalSummary,
                             ...residual,
                             resumable: resumableBg,
-                            usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats) },
+                            usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats), ...delegatedGranularityFields(child.stats, bgElapsedMs) },
                             ...(completionIdBg !== undefined ? { completionId: completionIdBg } : {}),
                         });
                     const completionFrame = {
@@ -3429,12 +3529,13 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         summary: bgTerminalSummary,
                         ...(failReasonBg !== undefined ? { error: failReasonBg.slice(0, REPORT_FIELD_MAX) } : {}),
                         ...(settled === "failed" && errCodeBg !== undefined ? { errorCode: errCodeBg } : {}),
+                        ...providerFaultField(child),
                         ...(child.sessionId ? { sessionId: child.sessionId } : {}),
                         ...(bgHandbackResult ? { result: notifyResultField(bgHandbackResult) } : {}),
                         ...(settled === "killed" && child.result ? { partial: true } : {}),
                         ...residual,
                         resumable: resumableBg,
-                        usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats) },
+                        usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats), ...delegatedGranularityFieldsWire(child.stats, bgElapsedMs) },
                         ...(completionIdBg !== undefined ? { completionId: completionIdBg } : {}),
                     };
                     const gateOwner = ownsTerminalFaces && settled === "completed" && notify !== undefined ? bgRetain?.childSessionId : undefined;

package/dist/core/file-history-store.js

@@ -166,6 +166,14 @@ export function validateFileHistoryExport(data) {
                 return bad(`tracked row ${t.relOrAbsPath} carries a non-integer version number`);
             if (v.blobHash !== null && (typeof v.blobHash !== "string" || !/^[0-9a-f]{64}$/.test(v.blobHash)))
                 return bad(`tracked row ${t.relOrAbsPath} carries a blob reference that is not a sha256 digest`);
+            if (v.mode !== undefined) {
+                if (typeof v.mode !== "number" || !Number.isInteger(v.mode) || v.mode < 0 || v.mode > 0o7777) {
+                    return bad(`tracked row ${t.relOrAbsPath} carries a mode outside the permission-bit domain [0, 0o7777] — refused, never coerced`);
+                }
+                if ((v.mode & 0o6000) !== 0) {
+                    return bad(`tracked row ${t.relOrAbsPath} carries a set-ID mode (0o${v.mode.toString(8)}) — a restore replaying setuid/setgid bits would mint a privilege-escalation primitive; refused`);
+                }
+            }
         }
         if (new Set(t.versions.map((v) => v.version)).size !== t.versions.length)
             return bad(`tracked row ${t.relOrAbsPath} carries the same version number twice — a chain whose versions are ambiguous cannot be published`);
@@ -284,13 +292,15 @@ export async function applyFileRestoreViaEnv(env, absPath, target, opts) {
             return { outcome: "identical" };
         if (modeOnly === "applied")
             return { outcome: "applied" };
+        if (modeOnly === "applied_unpreserved")
+            return { outcome: "applied", modeNotPreserved: true };
         return { outcome: "identical", modeNotPreserved: true };
     }
     const w = await writeRestoredBytes(env, absPath, target.bytes, signal);
     if (!w.ok)
         return { outcome: w.refused ? "refused" : "failed", reason: `write: ${w.code}` };
     const modeAfter = await applyRecordedMode(env, absPath, opts, undefined);
-    return { outcome: "applied", ...(modeAfter === "unpreserved" ? { modeNotPreserved: true } : {}) };
+    return { outcome: "applied", ...(modeAfter === "unpreserved" || modeAfter === "applied_unpreserved" ? { modeNotPreserved: true } : {}) };
 }
 async function restorePreflight(env, absPath, opts) {
     const info = await env.fileInfo(absPath, opts.signal);
@@ -337,7 +347,10 @@ export async function previewFileDelta(env, absPath, targetHash, targetBytes, ta
             return undefined;
         const info = await env.fileInfo(absPath);
         const currentMode = info.ok ? info.value.mode : undefined;
-        return modeProvenDifferent(targetMode, currentMode) ? { insertions: 0, deletions: 0 } : undefined;
+        const replayMode = (targetMode & 0o6000) !== 0 ? targetMode & 0o1777 : targetMode;
+        return modeProvenDifferent(targetMode, currentMode) && modeProvenDifferent(replayMode, currentMode)
+            ? { insertions: 0, deletions: 0 }
+            : undefined;
     }
     return countRestoreLineDiff(curBytes, targetBytes);
 }
@@ -347,6 +360,15 @@ async function applyRecordedMode(env, absPath, opts, currentMode) {
         return "unchanged";
     if (currentMode === (want & 0o7777))
         return "unchanged";
+    if ((want & 0o6000) !== 0) {
+        const stripped = want & 0o1777;
+        if (currentMode === stripped)
+            return "unpreserved";
+        if (env.setFileMode === undefined)
+            return "unpreserved";
+        const r = await env.setFileMode(absPath, stripped, opts.signal);
+        return r.ok ? "applied_unpreserved" : "unpreserved";
+    }
     if (env.setFileMode === undefined)
         return "unpreserved";
     const r = await env.setFileMode(absPath, want & 0o7777, opts.signal);

package/dist/core/governance-codes.d.ts

@@ -62,12 +62,21 @@ export declare const RULE_SYNC_DROP_CODES: {
     /** The server refused this local row (its response `dropped` names it); it leaves the live view so
      *  it does not ride — and get refused on — every future round. */
     readonly server_rejected: "local-quarantined";
+    /** design/382 §4.3 — the row carries a SESSION scope, which the durable face (store, sync wire,
+     *  at-rest bytes) structurally never holds: a session authorization lives in its session's overlay
+     *  and dies with it. The row is dropped and disclosed, never landed and never quarantined (the
+     *  quarantine area is itself durable — parking a session row there would persist it). Inbound-
+     *  refused in every reachable case: the direct write arms refuse session scopes LOUDLY
+     *  (`unsupported.session_scope_store`) before one can become local. */
+    readonly session_scope_not_durable: "inbound-refused";
 };
 /** Every reason a sync round may drop or quarantine a record. Closed set; free text is not a member. */
 export type RuleSyncDropReason = keyof typeof RULE_SYNC_DROP_CODES;
 /** The subset that may appear on a LOCAL quarantined row (design/182 §8.1 `quarantine` instruction /
- *  fence arm / local screening). `own_actor_forged` is inbound-only by construction. */
-export type RuleQuarantineReason = Exclude<RuleSyncDropReason, "own_actor_forged">;
+ *  fence arm / local screening). `own_actor_forged` is inbound-only by construction;
+ *  `session_scope_not_durable` never quarantines — the quarantine area is durable, and a session row
+ *  parked there would be a session row persisted (design/382 §4.3). */
+export type RuleQuarantineReason = Exclude<RuleSyncDropReason, "own_actor_forged" | "session_scope_not_durable">;
 /**
  * WHO a notice code is for. `"user"` = a session-scoped disclosure the end user of that session is
  * entitled to see (safe to project onto that session's event stream); `"operator"` = a

package/dist/core/governance-codes.js

@@ -90,6 +90,7 @@ export const RULE_SYNC_DROP_CODES = {
     dot_identity_conflict: "inbound-refused",
     below_gc_frontier: "local-quarantined",
     server_rejected: "local-quarantined",
+    session_scope_not_durable: "inbound-refused",
 };
 export const ENGINE_NOTICE_CODES = [
     "config.autocompact_window_clamped",

package/dist/core/permission-rule-consent.d.ts

@@ -29,6 +29,7 @@
  */
 import { type RuleOffer, type RuleRejectCode, type RuleScope, type RuleDot } from "./permission-rule-model.js";
 import type { PermissionRuleStoreProvider, RuleOwner } from "./permission-rule-store.js";
+import type { SessionRuleOverlay } from "./permission-rule-session.js";
 /** One candidate rule inside an approval record: the exact text and where it would apply. */
 export interface RuleCandidate {
     rule: string;
@@ -199,6 +200,15 @@ export interface RuleConsentDeps {
      * happened, and withholding the receipt helps no one.
      */
     cardEdits?: boolean;
+    /**
+     * design/382 §4.3 — the SESSION-RULE OVERLAY: where a `{kind:"session"}` scoped candidate lands at
+     * redemption (the store write leg is never taken for one), and where the prepare-time coverage read
+     * merges a session's standing rows from. Host-provided, session-lifetime, never synced — see
+     * `permission-rule-session.ts` for the contract and the reference implementation. Absent ⇒ a
+     * session-scope candidate's redemption refuses loudly (there is nowhere for it to land), and
+     * coverage reads see no session rows — both fail toward asking.
+     */
+    sessionRules?: SessionRuleOverlay;
 }
 /** In-memory approval records — the test backend and the reference CAS semantics, the stale-row
  *  envelope read included. */
@@ -257,8 +267,27 @@ export declare function prepareCardApproval(opts: {
     /** The ask's call id and argument digest, recorded for reconciliation. */
     toolCallId?: string;
     boundInputHash?: string;
-    /** Where a redeemed rule would apply. Defaults to global. */
+    /**
+     * Where a redeemed rule would apply — any of the three consent dimensions (design/382 §4.1).
+     *
+     * design/382 §4.4 (#490②, BREAKING B2) — the DEFAULT is no longer global:
+     *  · present ⇒ used as given (the explicit channel; all three members legal, garbage refused loudly);
+     *  · absent with `cwd` present ⇒ `{ kind: "project", root: cwd }`. Root = the adjudicated call's
+     *    cwd is a deliberately NARROW default — the engine is a library and repository semantics are
+     *    host business; a host wanting the true project root passes an explicit scope. The narrow cost
+     *    is more asks (a nested-directory rule does not cover siblings), the safe direction;
+     *  · both absent ⇒ a LOUD refusal (`config.missing_scope`): silent-global was the #490② defect,
+     *    silent-project has no root to anchor, and "where does this consent land" is not guessable.
+     */
     scope?: RuleScope;
+    /**
+     * design/382 §4.3 — the SESSION IDENTITY of the adjudicated call, threaded by the caller from the
+     * original call context exactly like `cwd` (never inferred from the process). It is the coverage
+     * read's third eligibility axis: with it, a standing session rule of that session counts as
+     * coverage; without it, no session rule covers anything (fail-closed). Independent of `scope` on
+     * purpose — `scope` names where a NEW consent would land, this names where the CALL is running.
+     */
+    sessionId?: string;
     /**
      * The working directory of the ADJUDICATED CALL — the same task root the gate's lane judged
      * with — threaded by the caller from the original call context. Never inferred from `scope`
@@ -400,7 +429,12 @@ export type EditedRuleTextPrecheck = {
  * so the surface's move is to not offer the edit box at all.
  */
 export declare function precheckEditedRuleText(text: string, command: string): EditedRuleTextPrecheck;
-/** What a redemption produced. `alreadyRedeemed` marks the replay path — the same dot, no second rule. */
+/** What a redemption produced. `alreadyRedeemed` marks the replay path — the same dot, no second rule.
+ *
+ *  `rev` is the DURABLE store's revision. A session-scope redemption (design/382 §4.3) lands in the
+ *  session overlay and does not move it: its `rev` is a best-effort read of the store's current
+ *  revision (0 when the store could not be read — the landing is in the overlay either way, and the
+ *  durable revision is reporting, not the landing's identity). */
 export type RedeemResult = {
     status: "redeemed";
     rule: string;
@@ -508,6 +542,12 @@ export interface ImportPreview {
  * `false` AND `deduped` — the two axes answer different questions and neither implies the other).
  * A refused row always carries its `reason`. `deduped` counts as LANDED: an equivalent rule
  * already standing means the consent is already in effect.
+ *
+ * design/382 §4.3 — on a SESSION-scope member the two landed words mean the same thing about a
+ * different home: landed in / already in the session's OVERLAY (a session rule's home store), never
+ * the persisted store. The words state that the landing happened; DURABILITY is what the member's own
+ * `scope` says, so a consumer never has to guess it off the status (deliberately no fourth status
+ * value — the closed set names landing outcomes, not storage classes).
  */
 export type RedeemedBatchMember = {
     readonly candidateIndex: number;