@sema-agent/core 7.0.0 → 7.0.2

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,75 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     };
                 }
             }
+            const modelObjectForm = typeof a.model === "object" &&
+                a.model !== null &&
+                !Array.isArray(a.model) &&
+                typeof a.model.id === "string" &&
+                typeof a.model.api === "string";
+            if (a.model !== undefined && typeof a.model !== "string" && !modelObjectForm) {
+                const typeDesc = Array.isArray(a.model) ? "an array" : a.model === null ? "null" : typeof a.model === "object" ? "an object" : `a ${typeof a.model}`;
+                return {
+                    isError: true,
+                    content: `Sub-agent not started: \`model\` must be a model name (string) from this deployment's catalog — got ${typeDesc}. Omit the parameter to run the agent type's own model.`,
+                    details: { error: "model.invalid" },
+                };
+            }
+            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 (modelObjectForm) {
                 if (wantsFork) {
-                    modelNote = `note: model "${requestedModel}" was ignored — a fork always runs on the caller's model.`;
+                    modelNote = `note: model "${inlineUntrusted(a.model.id, 80)}" was ignored — a fork always runs on the caller's model.`;
                 }
-                else if (!opts.models) {
-                    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 {
+                    perCallModel = a.model;
+                }
+            }
+            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 "${inlineUntrusted(requestedModel, 80)}" was ignored — a fork always runs on the caller's model.`;
+                }
+                else if (rosterKeys.length === 0) {
+                    modelNote = `note: model "${inlineUntrusted(requestedModel, 80)}" 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 +1772,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 ?? perCallModel.id : 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;
@@ -1936,6 +2048,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             const provenanceRequest = ctx.delegationProvenanceForChildren?.();
             const childProvenanceRef = provenanceRequest !== undefined ? { current: newDelegationProvenanceAggregate() } : undefined;
             const childAttestation = (status) => childProvenanceRef !== undefined ? reduceDelegationAttestation(childProvenanceRef.current, { completed: status === "completed" }) : undefined;
+            const liveCaptureFloor = reviveClaim === undefined
+                ? { optedOut: (await ctx.memoryCaptureOptedOut) === true, indeterminate: (await ctx.memoryCaptureIndeterminate) === true }
+                : undefined;
             const childInternals = {
                 ...(inheritedManifestScope ? { inheritedManifestScope } : {}),
                 ...(childProvenanceRef !== undefined && provenanceRequest !== undefined ? { delegationProvenance: { ref: childProvenanceRef, contentSafety: provenanceRequest } } : {}),
@@ -1954,8 +2069,8 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ...(ctx.interactionPosture !== undefined ? { parentInteractionPosture: ctx.interactionPosture } : {}),
                 ...(reviveClaim === undefined
                     ? {
-                        ...(ctx.memoryCaptureOptedOut === true ? { memoryCaptureFloor: true } : {}),
-                        ...(ctx.memoryCaptureOptedOut !== true && ctx.memoryCaptureIndeterminate === true ? { memoryCaptureFloorIndeterminate: true } : {}),
+                        ...(liveCaptureFloor?.optedOut === true ? { memoryCaptureFloor: true } : {}),
+                        ...(liveCaptureFloor?.optedOut !== true && liveCaptureFloor?.indeterminate === true ? { memoryCaptureFloorIndeterminate: true } : {}),
                         ...(ctx.memoryCaptureControlDir !== undefined ? { memoryCaptureQueryDir: ctx.memoryCaptureControlDir } : {}),
                         ...(ctx.memoryCaptureAncestors !== undefined ? { memoryCaptureAncestors: ctx.memoryCaptureAncestors } : {}),
                     }
@@ -2342,7 +2457,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 +2518,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 +2537,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 +2567,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 +2602,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 +2680,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 +2699,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 +2713,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 +3032,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 +3056,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 +3112,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 +3186,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 +3233,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 +3522,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 +3540,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 +3553,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/memory-engine/engine.d.ts

@@ -796,6 +796,27 @@ export declare function memoryConsolidationRefusedNotice(input: {
     reason?: string;
     occurrenceId?: string;
 }): EngineNotice;
+/**
+ * design/383 §S-7 (#511 件1) — {@link MemoryEngine.sessionMemoryStatus}'s answer. Every key is
+ * optional; ABSENCE means the fact's source could not be read (a fault never coins a `false`/`0`
+ * stand-in) — see the method doc for each key's exact absence law.
+ */
+export interface SessionMemoryStatus {
+    /** TRUE = a standing capture opt-out record; FALSE = store readable, no record (capture on).
+     *  ABSENT = the record store faulted — indeterminate (`optOutSource: "fault"` accompanies). */
+    captureOptedOut?: boolean;
+    /** Committed entries carrying this session's lineage contribution. Absent = ledger unreadable. */
+    committedCount?: number;
+    /** Of those, entries already folded into consolidation products (lineage × `distilled.inputs`).
+     *  Absent = ledger / scope enumeration / product read unreadable. */
+    foldedCount?: number;
+    /** WHY `captureOptedOut` reads as it does: `"record"` = a standing one-way record;
+     *  `"fault"` = the store faulted and the capture state is INDETERMINATE (no boolean is coined). */
+    optOutSource?: "record" | "fault";
+    /** Newest lineage `lastAt` for this session (ms epoch) — rides the same single ledger read as
+     *  `committedCount`. Absent = ledger unreadable, or no committed contribution exists at all. */
+    lastCaptureAt?: number;
+}
 export declare class MemoryEngine {
     private readonly backend;
     private readonly memoryDir;
@@ -910,13 +931,17 @@ export declare class MemoryEngine {
      * first cross-process resume, and "私密 only until the next resume" is a promise this engine
      * refuses to imply — the deliberate divergence from the pollution marker's best-effort arm.
      */
-    markSessionCaptureOptOut(sessionId: string, reason: string): SessionCaptureOptOutMarkOutcome;
+    markSessionCaptureOptOut(sessionId: string, reason: string): SessionCaptureOptOutMarkOutcome | Promise<SessionCaptureOptOutMarkOutcome>;
     /** The session's capture opt-out record (in-process first, then the durable store) — undefined =
      *  capture is on. Side-effect-free OBSERVER face; a THROWING store read degrades to the
      *  in-process answer here. Every consumer whose answer decides whether bytes COMMIT must use
      *  {@link sessionCaptureOptOutOrFault} instead — this face cannot distinguish "no record" from
-     *  "store outage", and on that distinction the fail direction flips. */
-    sessionCaptureOptOut(sessionId: string): SessionCaptureOptOutRecord | undefined;
+     *  "store outage", and on that distinction the fail direction flips.
+     *  DUAL FORM (#511 件2, the whole capture-face family — this one, `sessionCaptureOptOutOrFault`,
+     *  `markSessionCaptureOptOut`, `listCaptureOptOutSessions`): over a sync store the answer is the
+     *  same synchronous value as always; over a Promise-form {@link SessionCaptureRecordStore} the
+     *  face answers a Promise of the identical shape. `await` is always correct on either arm. */
+    sessionCaptureOptOut(sessionId: string): SessionCaptureOptOutRecord | undefined | Promise<SessionCaptureOptOutRecord | undefined>;
     /** {@link sessionCaptureOptOut} with the FAULT axis preserved (codex review, 亲核 adopted):
      *  `fault: true` ⇔ the durable store THREW — the record state is INDETERMINATE, which the
      *  commit-deciding consumers (harvest opening read, pre-commit re-read, the runner's read
@@ -926,11 +951,14 @@ export declare class MemoryEngine {
     sessionCaptureOptOutOrFault(sessionId: string): {
         record?: SessionCaptureOptOutRecord;
         fault: boolean;
-    };
+    } | Promise<{
+        record?: SessionCaptureOptOutRecord;
+        fault: boolean;
+    }>;
     /** Every capture-opted-out session id (durable roster ∪ in-process marks). THROWS on an
      *  enumeration failure — the one consumer (the consolidation eligibility arm, §2.4) is
      *  fail-closed by design: "roster unknown" must refuse the run, never read as "no one opted out". */
-    listCaptureOptOutSessions(): Set<string>;
+    listCaptureOptOutSessions(): Set<string> | Promise<Set<string>>;
     /**
      * design/383 §2.3 — the mid-session flip's BOUNDARY-ISOLATION SWEEP over the write plane: files
      * under the writable root that this session window added or changed (vs the materialize baseline)
@@ -1445,6 +1473,35 @@ export declare class MemoryEngine {
      * registry THROWS fail-closed — the same reason an unsupported one never reads as empty.
      */
     listMemoryScopes(): Promise<MemoryScopeEnumeration>;
+    /**
+     * design/383 §S-7 (#511 件1) — the HOST's per-session memory-status read face: the data supply
+     * for the "memory capture is off / N committed, M folded" disclosure family and the
+     * resume-visibility answer (state face, not event face — notice dedup semantics are untouched).
+     * A server projects it onto a wire endpoint as a PURE derivation of these keys.
+     *
+     * EVERY key is optional and its ABSENCE means "that fact's source could not be read" — a fault
+     * never coins a `false`/`0` stand-in (the §3.1 fault-transit law):
+     *  - `captureOptedOut` — the capture opt-out state. Present `true` (a standing record — with
+     *    `optOutSource: "record"`) or present `false` (the store answered and no one-way record
+     *    exists — genuine "capture on"). ABSENT ⇔ the record store faulted: the capture state is
+     *    INDETERMINATE and `optOutSource: "fault"` says so (the 383 片2/3 `captureIndeterminate`
+     *    axis, projected — never a boolean).
+     *  - `committedCount` — how many committed entries carry this session's lineage contribution
+     *    (the lineage ledger's committed set). Absent ⇔ the ledger is unreadable.
+     *  - `foldedCount` — of those, how many appear among the `distilled.inputs` of committed
+     *    consolidation products (the lineage × distilled.inputs intersection — "already folded into
+     *    long-term memory"). Absent ⇔ the ledger, the scope enumeration (a backend without
+     *    `listScopes` cannot name the header universe), or the product read is unreadable.
+     *  - `lastCaptureAt` — the newest `lastAt` over this session's lineage contributions (ms epoch).
+     *    CHEAP by construction — it rides the SAME single ledger read as `committedCount`, so it is
+     *    carried rather than dropped; absent ⇔ the ledger is unreadable OR the session has no
+     *    committed contribution at all (there is no such moment to name — the one key whose absence
+     *    also covers "no fact exists", stated here so consumers need not guess).
+     *
+     * Side-effect-free committed reads throughout (capture face + lineage sidecar + audit-face
+     * headers/getByIds); never throws — an unreadable source is an absent key, which IS the answer.
+     */
+    sessionMemoryStatus(sessionId: string): Promise<SessionMemoryStatus>;
     /** The committed, side-effect-free audit read: the adoption-restricted committed view when the
      *  backend offers one (zero-copy File — ledger+shadow, no disk adoption), else the non-adopting
      *  retrieval view (copy-out File), else the backend itself (Pg/TiDB shapes — naturally committed