pi-subagents 0.76.0 → 0.77.0

package/src/runs/foreground/subagent-executor.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { discoverAgents, findBlockingAgentDiagnostic, formatUnknownAgentError, resolveAgentName, unknownAgentDiagnosticContext } from "../../agents/agents.js";
+import { discoverAgents, findBlockingAgentDiagnostic, formatAvailableAgentLines, formatUnknownAgentError, resolveAgentName, suggestAgentName, unknownAgentDiagnosticContext } from "../../agents/agents.js";
 import { getArtifactsDir, getProjectArtifactPackagingWarning, getProjectSubagentsDir } from "../../shared/artifacts.js";
 import { writeAtomicJson } from "../../shared/atomic-json.js";
 import { createCapacityResilientJsonWriter } from "../../shared/capacity-resilient-json.js";
@@ -10,7 +10,7 @@ import { resolveEffectiveThinking, toModelInfo } from "../../shared/model-info.j
 import { beginForegroundChild, finishForegroundChild, foregroundSchedulingSettled, settleForegroundSchedulingOwner, updateForegroundChild, } from "./foreground-control.js";
 import { getLivePromptAudit, rewritePromptWithGuidance, updateLiveEffectivePrompt } from "./prompt-audit.js";
 import { persistForegroundRunHistory, MAX_REMEMBERED_FOREGROUND_RUNS } from "./foreground-history.js";
-import { resolveExecutionAgentScope } from "../../agents/agent-scope.js";
+import { projectScopeRequiresTrustMessage, resolveExecutionAgentScope } from "../../agents/agent-scope.js";
 import { handleManagementAction } from "../../agents/agent-management.js";
 import { handleRefinementAction } from "../../agents/agent-refinements.js";
 import { buildDoctorReport } from "../../extension/doctor.js";
@@ -56,7 +56,7 @@ import { assertAgentAllowedByCapabilityCeiling, intersectSubagentCapabilityCeili
 import { isAgentContract } from "../shared/agent-contract.js";
 import { normalizeExtensionBindings } from "../shared/extension-bindings.js";
 import { assertRequiredChildExtensionsAdmitted, hasMandatoryRequiredChildExtensions, readRetainedRequiredChildExtensions, resolveRequiredChildExtensions } from "../../shared/required-child-extensions.js";
-import { finalizeSingleOutput, injectSingleOutputInstruction, normalizeSingleOutputOverride, outputPathMappingFromTask, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.js";
+import { capInlineOutput, finalizeSingleOutput, injectSingleOutputInstruction, normalizeSingleOutputOverride, outputPathMappingFromTask, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.js";
 import { assertJsonSchemaObject, cleanupStructuredOutputRuntime, createStructuredOutputRuntime } from "../shared/structured-output.js";
 import { compactForegroundDetails, getSingleResultOutput, PROMPT_REDACTED, readStatus, resolveChildCwd, sumResultsCost, sumResultsUsage, toAgentToolUsage } from "../../shared/utils.js";
 import { discardPreservedWorktrees, formatParallelHandoffError, formatParallelHandoffReference, protectRetainedWorktreeForResume, formatStoredParallelHandoffCleanup, parallelHandoffPath, readParallelHandoffManifest, recordParallelHandoffMerge, recordParallelHandoffSupersession, writeParallelHandoffGroup, writeWorktreeSetupHandoff } from "../shared/parallel-handoff.js";
@@ -73,8 +73,8 @@ import { promotePausedWorkflowIfSettled, reconcileDetachedWorkflowChildCompletio
 import { reconcileAsyncRun } from "../background/stale-run-reconciler.js";
 import { resolveAsyncRootResultPath, waitForImportedAsyncRoot } from "../background/chain-root-attachment.js";
 import { awaitExistingAsyncRun, claimWorkflowAwaitedResult } from "../background/await-async-run.js";
-import { fallbackResultPayloadPathForSessionRun, removeResultIndex, resultFilePath, writeAsyncResultFile } from "../background/result-files.js";
-import { attachRootChildrenToSteps, createNestedRoute, findNestedControlResult, inheritedNestedParentAddressOf, inheritedNestedRouteOf, nestedRunScope, resolveNestedAsyncDir, retainNestedLookupRoute, snapshotNestedEventFiles, updateForegroundNestedProjection, writeNestedControlRequest, writeNestedEvent } from "../shared/nested-events.js";
+import { fallbackResultPayloadPathForSessionRun, resultFilePath, retireResultSnapshot, writeAsyncResultFile } from "../background/result-files.js";
+import { attachRootChildrenToSteps, createNestedRoute, findNestedControlResult, inheritedNestedParentAddressOf, inheritedNestedRouteOf, nestedRunNotActiveMessage, nestedRunScope, resolveNestedAsyncDir, retainNestedLookupRoute, snapshotNestedEventFiles, updateForegroundNestedProjection, writeNestedControlRequest, writeNestedEvent } from "../shared/nested-events.js";
 import { resolveSubagentRunId } from "../background/run-id-resolver.js";
 import { formatNestedRunStatusLines } from "../shared/nested-render.js";
 import { isStoppableAsyncStatusStep, resolveAsyncStatusChild } from "../shared/child-identity.js";
@@ -83,6 +83,7 @@ import { getExternalJobProvider } from "../../api/external-job-provider.js";
 import { externalJobFollowUpRequestDigest, externalJobFollowUpRequestId, externalJobFollowUpRunId, externalJobPromptDigest, externalJobStableJson } from "../shared/external-job-runner.js";
 import { externalCliReceiptMetadata, normalizeExternalCliRunnerStatus } from "../shared/external-cli-contract.js";
 import { formatHerdrMachineRunnerUnsupported, resolveHerdrMachinePlacement } from "../shared/herdr-machine.js";
+import { lookupRunnerLauncher, resolveAgentRunnerLauncher } from "../shared/runner-launcher.js";
 import { applyForceTopLevelAsyncOverride } from "../background/top-level-async.js";
 import { handleMissionAction, MISSION_ACTIONS } from "../../missions/actions.js";
 import { attachMissionToLaunchResult, prepareMissionLaunch, writeMissionAsyncBinding } from "../../missions/lifecycle.js";
@@ -111,35 +112,12 @@ import { applyReviewedCleanupPlan, formatCleanupReceipt, loadReviewedCleanupPlan
 import { createWorktreeCleanupPlan, formatWorktreeCleanupPlan } from "../shared/worktree-cleanup-plan.js";
 import { DIRS, DEFAULT_ARTIFACT_CONFIG, DEFAULT_MAX_OUTPUT, DEFAULT_FORK_PREAMBLE, SUBAGENT_ACTIONS, SUBAGENT_ASYNC_STARTED_EVENT, SUBAGENT_CHILD_STATUS_EVENT, SUBAGENT_CONTROL_EVENT, SUBAGENT_CONTROL_INTERCOM_EVENT, SUBAGENT_FOREGROUND_COMPLETE_EVENT, SUBAGENT_LIFECYCLE_ARTIFACT_VERSION, checkSubagentDepth, resolveChildMaxSubagentDepth, resolveCurrentMaxSubagentDepth, resolveMaxSubagentSpawnsPerRun, truncateOutput, wrapForkTask, } from "../../shared/types.js";
 import { deriveChildSessionName } from "../../shared/child-session-name.js";
+import { editDistance, hasSingleAdjacentTransposition } from "../../shared/edit-distance.js";
 const MUTATING_MANAGEMENT_ACTIONS = new Set(["command.yield", "command.cancel", "create", "update", "delete", "eject", "disable", "enable", "reset", "grant-spawn-budget", "watchdog.configure", "mission.create", "mission.update", "mission.resolve-decision", "mission.attach-run", "mission.close", "inspector.open", "inspector.close", "project.open", "project.close", "worktree.discard", "worktree.cleanup", "lane.recordMerge", "lane.recordSupersession", "refine", "refine.rollback", "dismiss", "schedule.create", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"]);
 const DESTRUCTIVE_MANAGEMENT_ACTIONS = new Set(["command.cancel", "delete", "eject", "disable", "reset", "mission.close", "worktree.discard", "refine.rollback", "inspector.close", "project.close", "stop", "interrupt", "schedule.delete"]);
 function resolveSteerDeliveryMode(mode) {
     return mode === "steer" || mode === "follow_up" || mode === "auto" ? mode : undefined;
 }
-function editDistance(left, right) {
-    const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
-    for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
-        let diagonal = previous[0];
-        previous[0] = leftIndex;
-        for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
-            const above = previous[rightIndex];
-            previous[rightIndex] = left[leftIndex - 1] === right[rightIndex - 1]
-                ? diagonal
-                : Math.min(diagonal, above, previous[rightIndex - 1]) + 1;
-            diagonal = above;
-        }
-    }
-    return previous[right.length];
-}
-function hasSingleAdjacentTransposition(left, right) {
-    if (left.length !== right.length)
-        return false;
-    const mismatch = [...left].findIndex((character, index) => character !== right[index]);
-    return mismatch >= 0
-        && left[mismatch] === right[mismatch + 1]
-        && left[mismatch + 1] === right[mismatch]
-        && left.slice(mismatch + 2) === right.slice(mismatch + 2);
-}
 export function unknownSubagentActionMessage(action, disabled) {
     const requested = action.toLowerCase();
     const enabledActions = SUBAGENT_ACTIONS.filter((candidate) => !disabled?.actions.has(candidate));
@@ -304,6 +282,21 @@ function trustedSessionRootsForStatus(ctx, deps) {
 function sessionProjectTrust(ctx) {
     return typeof ctx.isProjectTrusted === "function" ? ctx.isProjectTrusted() : undefined;
 }
+/** Agent and settings discovery follows the launching session's trust, like the child itself. */
+function withSessionProjectTrust(deps, ctx) {
+    if (sessionProjectTrust(ctx) !== false)
+        return deps;
+    return { ...deps, discoverAgents: (cwd, scope, preferredModelProvider) => deps.discoverAgents(cwd, scope, preferredModelProvider, { projectTrusted: false }) };
+}
+function projectScopeTrustError(params, ctx) {
+    if (sessionProjectTrust(ctx) !== false || resolveExecutionAgentScope(params.agentScope) !== "project")
+        return undefined;
+    const action = typeof params.action === "string" ? params.action.trim() : undefined;
+    // These actions resolve agents in the requested scope; management actions are left to their own handlers.
+    if (action !== undefined && action !== "resume" && action !== "validate" && action !== "append-step")
+        return undefined;
+    return buildRequestedModeError(params, projectScopeRequiresTrustMessage(resolveRequestedCwd(ctx.cwd, params.cwd)));
+}
 function spawnBudgetErrorResult(message, mode) {
     return {
         content: [{ type: "text", text: message }],
@@ -824,7 +817,7 @@ function emitControlNotification(input) {
     }
 }
 function interruptAsyncRun(state, runId, kill, location) {
-    const target = getAsyncInterruptTarget(state, runId, location);
+    const target = getAsyncInterruptTarget(state, runId, location, { fallbackToNewest: runId === undefined });
     if (!target)
         return null;
     const status = reconcileAsyncRun(target.asyncDir, omitUndefinedProperties({ kill })).status;
@@ -1016,6 +1009,7 @@ function appendStepToAsyncChain(input) {
         cwd: input.ctx.cwd,
         currentSessionId: resolveCurrentSessionId(input.ctx.sessionManager),
         parentSessionId: input.ctx.sessionManager.getSessionId() ?? undefined,
+        parentSessionFile: input.ctx.sessionManager.getSessionFile() ?? undefined,
         currentModelProvider: parentModel?.provider,
         currentModel: parentModel,
         scopedModelIds: scopedModelIdsFromContext(input.ctx),
@@ -1025,6 +1019,17 @@ function appendStepToAsyncChain(input) {
         permissions: input.deps.config.permissions,
         childRuntime: input.deps.childRuntime,
     });
+    // Appended steps run inside the already-running runner, so they must use its launcher (or none).
+    // Checked before building, which can write progress files. A mix is refused by the builder.
+    const appendedLaunchers = new Set(chain.flatMap(getStepAgents).map((name) => agents.find((agent) => agent.name === name)?.launcher));
+    const appendedLauncher = [...appendedLaunchers][0];
+    if (appendedLaunchers.size === 1 && appendedLauncher !== status.launcher?.name) {
+        return {
+            content: [{ type: "text", text: `Cannot append step to run '${resolved.id}': its runner uses ${status.launcher ? `launcher '${status.launcher.name}'` : "no launcher"}, but the appended agents use ${appendedLauncher ? `launcher '${appendedLauncher}'` : "no launcher"}.` }],
+            isError: true,
+            details: { mode: "management", results: [] },
+        };
+    }
     const built = buildAsyncRunnerSteps(resolved.id, compactOptional({
         chain: wrapChainTasksForFork(chain, contextPolicy),
         task: input.params.task,
@@ -1332,11 +1337,18 @@ async function interruptNestedRun(target) {
     if (run.state === "paused")
         return { content: [{ type: "text", text: `Nested run ${run.id} is already paused.` }], isError: true, details: { mode: "management", results: [] } };
     const result = await sendNestedControlRequest(target, "interrupt");
-    if (result)
+    // The owner's foreground map cannot address a detached async child. Only
+    // that missing-route response may use the existing authorized async inbox;
+    // other owner refusals must remain authoritative.
+    const missingForegroundRoute = result?.ok === false && result.message === nestedRunNotActiveMessage(run.id);
+    if (result && !missingForegroundRoute)
         return { content: [{ type: "text", text: result.message }], ...(result.ok ? {} : { isError: true }), details: { mode: "management", results: [] } };
     const direct = directNestedAsyncInterrupt(target);
     if (direct)
         return direct;
+    // No async inbox either: the owner's own answer is the accurate one.
+    if (result)
+        return { content: [{ type: "text", text: result.message }], isError: true, details: { mode: "management", results: [] } };
     return { content: [{ type: "text", text: `Nested run ${run.id} owner is not reachable and no safe direct async interrupt fallback is available.` }], isError: true, details: { mode: "management", results: [] } };
 }
 async function resumeLiveNestedRun(input) {
@@ -1467,6 +1479,7 @@ async function resumeExternalJobFollowUp(input) {
             cwd: input.requestCwd,
             currentSessionId,
             parentSessionId: input.ctx.sessionManager.getSessionId() ?? undefined,
+            parentSessionFile: input.ctx.sessionManager.getSessionFile() ?? undefined,
             currentModelProvider: parentModel?.provider,
             currentModel: parentModel,
             scopedModelIds: scopedModelIdsFromContext(input.ctx),
@@ -1587,7 +1600,7 @@ async function resumeAsyncRun(input) {
                     type: "text",
                     text: [
                         `Async child '${target.runId}' index ${target.index} is still running. action='resume' only revives paused, completed, or failed children.`,
-                        `Send live input with subagent({ action: "steer", id: "${target.runId}", index: ${target.index}, message: "..." }).`,
+                        `Send live input with subagent({ action: "steer", id: "${target.runId}", message: "...", options: { index: ${target.index} } }).`,
                     ].join("\n"),
                 }],
             isError: true,
@@ -1727,7 +1740,7 @@ async function resumeAsyncRun(input) {
         const chain = wrapChainTasksForFork(attachChain, contextPolicy);
         const normalized = normalizeSkillInput(input.params.skill);
         const parentModel = input.parentModel;
-        const result = executeAsyncChain(runId, compactOptional({
+        const result = await executeAsyncChain(runId, compactOptional({
             chain,
             task: workflowTask,
             goal,
@@ -1746,11 +1759,13 @@ async function resumeAsyncRun(input) {
                 cwd: input.requestCwd,
                 currentSessionId: input.deps.state.currentSessionId,
                 parentSessionId: input.ctx.sessionManager.getSessionId() ?? undefined,
+                parentSessionFile: input.ctx.sessionManager.getSessionFile() ?? undefined,
                 currentModelProvider: parentModel?.provider,
                 currentModel: parentModel,
                 scopedModelIds: scopedModelIdsFromContext(input.ctx),
                 modelScope,
                 modelResponseAliases: input.deps.config.modelResponseAliases,
+                runnerLaunchers: input.deps.config.runnerLaunchers,
                 interactive: input.ctx.hasUI,
                 permissions: input.deps.config.permissions,
                 childRuntime: input.deps.childRuntime,
@@ -1814,7 +1829,8 @@ async function resumeAsyncRun(input) {
     if (target.source === "nested" && !target.recoveryDescriptor) {
         return { content: [{ type: "text", text: `Nested child '${target.runId}' is missing its required recovery identity. Start a new run instead.` }], isError: true, details: { mode: "management", results: [] } };
     }
-    const recoveryAgentConfig = recoveryDescriptor ? applySteeringRecoveryAgentConfig(baseAgentConfig, recoveryDescriptor) : baseAgentConfig;
+    // Runs without a recovery descriptor were never wrapped; a launcher added to the agent file later does not apply.
+    const recoveryAgentConfig = recoveryDescriptor ? applySteeringRecoveryAgentConfig(baseAgentConfig, recoveryDescriptor) : { ...baseAgentConfig, launcher: undefined };
     const agentConfig = intercomBridge.active ? applyIntercomBridgeToAgent(recoveryAgentConfig, intercomBridge) : recoveryAgentConfig;
     const foregroundContract = target.source === "foreground" ? target.resumeContract : undefined;
     const outputSchema = Object.hasOwn(input.params, "outputSchema")
@@ -1831,6 +1847,10 @@ async function resumeAsyncRun(input) {
     if (acceptanceErrors.length > 0) {
         return { content: [{ type: "text", text: `Cannot resume: ${acceptanceErrors.join(" ")}` }], isError: true, details: { mode: "management", results: [] } };
     }
+    // Refuse before capacity moves so the retained run stays resumable once the config is fixed.
+    if (agentConfig.launcher !== undefined && !lookupRunnerLauncher(input.deps.config.runnerLaunchers, agentConfig.launcher)) {
+        return { content: [{ type: "text", text: `Cannot resume: run '${target.runId}' was launched with launcher '${agentConfig.launcher}', which is no longer defined in runnerLaunchers in the user subagent config.` }], isError: true, details: { mode: "management", results: [] } };
+    }
     const runId = randomUUID();
     const topLevelResume = depth === 0 && !inheritedNestedRoute(input.deps) && !input.params.workflowParentRunId;
     let activeAsyncCapacity;
@@ -1873,12 +1893,14 @@ async function resumeAsyncRun(input) {
             cwd: input.requestCwd,
             currentSessionId: input.deps.state.currentSessionId,
             parentSessionId: input.ctx.sessionManager.getSessionId() ?? undefined,
+            parentSessionFile: input.ctx.sessionManager.getSessionFile() ?? undefined,
             currentModelProvider: parentModel?.provider,
             currentModel: parentModel,
             scopedModelIds: scopedModelIdsFromContext(input.ctx),
             modelScope,
             // Absence in the retained contract is meaningful; never acquire current aliases.
             modelResponseAliases: recoveryDescriptor ? recoveryDescriptor.modelResponseAliases : foregroundContract?.modelResponseAliases,
+            runnerLaunchers: input.deps.config.runnerLaunchers,
             interactive: input.ctx.hasUI,
             permissions: input.deps.config.permissions,
             childRuntime: input.deps.childRuntime,
@@ -2028,10 +2050,12 @@ function formatFailedSingleRunOutput(result, displayOutput) {
     const error = result.error || "Failed";
     const output = displayOutput.trim();
     const lines = [error];
+    let cappedOutput = output;
     if (output && output !== error.trim()) {
-        lines.push("", "Output:", output);
+        cappedOutput = capInlineOutput(output, { artifactPath: result.artifactPaths?.outputPath, savedPath: result.savedOutputPath });
+        lines.push("", "Output:", cappedOutput);
     }
-    if (result.artifactPaths?.outputPath && fs.existsSync(result.artifactPaths.outputPath)) {
+    if (cappedOutput === output && result.artifactPaths?.outputPath && fs.existsSync(result.artifactPaths.outputPath)) {
         lines.push("", `Output artifact: ${result.artifactPaths.outputPath}`);
     }
     return lines.join("\n");
@@ -2156,6 +2180,8 @@ function workflowValidationOptions(deps, params, runtimeCwd, parentModelProvider
     const cwd = resolveRequestedCwd(runtimeCwd, params.cwd);
     const scope = resolveExecutionAgentScope(params.agentScope);
     let discovered;
+    // Validation reports every bad agent name; only the first one carries the agent list.
+    let listedAgents = false;
     return {
         maxSubagentSpawnsPerRun: params.maxSubagentSpawnsPerRun ?? resolveMaxSubagentSpawnsPerRun(deps.config.maxSubagentSpawnsPerRun),
         agentNameError: (name) => {
@@ -2164,12 +2190,13 @@ function workflowValidationOptions(deps, params, runtimeCwd, parentModelProvider
             const resolved = resolveAgentName(name, agents);
             if (resolved.agent || resolved.error)
                 return canonicalizeAgentName(name, agents, discovered.agentDiagnostics, diagnosticContextFromDiscovery(discovered, cwd, scope)).error;
-            const requested = name.trim().toLowerCase();
-            const suggestion = [...new Set(agents.flatMap((agent) => [agent.name, ...(agent.localName ? [agent.localName] : []), ...(agent.aliases ?? [])]))]
-                .map((candidate) => ({ candidate, distance: editDistance(requested, candidate.toLowerCase()) }))
-                .filter(({ candidate, distance }) => distance <= Math.max(1, Math.floor(candidate.length / 4)) || hasSingleAdjacentTransposition(requested, candidate.toLowerCase()))
-                .sort((left, right) => left.distance - right.distance || left.candidate.localeCompare(right.candidate))[0]?.candidate;
-            return `Unknown agent '${name}'.${suggestion ? ` Did you mean '${suggestion}'?` : ""} Use subagent({ action: "list" }) to inspect agents.`;
+            const disabled = discovered.disabledAgents?.includes(name.trim()) === true;
+            const suggestion = disabled ? undefined : suggestAgentName(name, agents);
+            const problem = disabled ? `Agent '${name}' is disabled by a settings override.` : `Unknown agent '${name}'.${suggestion ? ` Did you mean '${suggestion}'?` : ""}`;
+            if (listedAgents)
+                return problem;
+            listedAgents = true;
+            return [`${problem} Available agents:`, ...formatAvailableAgentLines(agents)].join("\n");
         },
     };
 }
@@ -2904,12 +2931,12 @@ function importedAsyncRootUsage(completed) {
 }
 function removeWorkflowAwaitedResult(asyncDir, resultPath, runId, publication) {
     try {
-        fs.rmSync(resultPath, { force: true });
+        retireResultSnapshot(workflowAwaitedAsyncResultPath(asyncDir), { ...publication, runId }, resultPath);
     }
-    catch {
-        // Payload cleanup must not replace an already imported delivery.
+    catch (error) {
+        // Cleanup must not replace an already imported delivery.
+        console.error(`Failed to remove imported workflow child result '${resultPath}'; leaving it in place:`, error);
     }
-    removeResultIndex(asyncDir, publication.sessionId, runId, publication.toolCallId);
 }
 function emitWorkflowAwaitedChildComplete(pi, state, runId, asyncDir, parentWorkflowRunId, completed) {
     let status;
@@ -3037,11 +3064,13 @@ async function runAsyncPath(data, deps) {
         cwd: ctx.cwd,
         currentSessionId: data.parentSessionId,
         parentSessionId: data.parentPiSessionId,
+        parentSessionFile: ctx.sessionManager.getSessionFile() ?? undefined,
         currentModelProvider: parentModel?.provider,
         currentModel: parentModel,
         scopedModelIds: data.scopedModelIds,
         modelScope: data.modelScope,
         modelResponseAliases: deps.config.modelResponseAliases,
+        runnerLaunchers: deps.config.runnerLaunchers,
         interactive: ctx.hasUI,
         permissions: deps.config.permissions,
         childRuntime: deps.childRuntime,
@@ -3091,6 +3120,7 @@ async function runAsyncPath(data, deps) {
         if (launchRuleError)
             return toExecutionErrorResult(params, new Error(launchRuleError), data.contextPolicy.contextSummary);
         const asyncResult = await executeAsyncSingle(id, compactOptional({
+            toolCallId: data.toolCallId,
             agent: params.agent,
             task: shouldForkAgent(contextPolicy, params.agent) ? wrapForkTask(params.task ?? "") : (params.task ?? ""),
             goal: params.task ?? "",
@@ -3295,7 +3325,12 @@ function resolveWorkflowChildOutputPath(input) {
             id: input.params.resume.trim(),
             ...(typeof index === "number" && Number.isInteger(index) ? { index } : {}),
         }, input.state);
-        return { path: "recoveryDescriptor" in target ? target.recoveryDescriptor?.outputPath : undefined, inherited: false };
+        const recoveryOutput = "recoveryDescriptor" in target ? target.recoveryDescriptor?.outputPath : undefined;
+        if (hasExplicitOutput)
+            return { path: recoveryOutput, inherited: false };
+        // An output-less foreground resume reuses its recorded output; only an absolute path is known before the new run id exists.
+        const foregroundOutput = target.source === "foreground" ? target.resumeContract?.output : undefined;
+        return { path: recoveryOutput, inherited: false, resumedOutput: recoveryOutput ?? (typeof foregroundOutput === "string" && path.isAbsolute(foregroundOutput) ? foregroundOutput : undefined) };
     }
     const childCwd = resolveWorkflowChildLocalCwd(input);
     let agentOutput;
@@ -3335,7 +3370,9 @@ function workflowChildOutputClaims(input) {
     }
     const overrides = new Map();
     for (const entry of resolvedEntries) {
-        if (entry.inherited && entry.path && (paths.get(resolveWorkflowHostOutputClaimPath(entry.path)) ?? 0) > 1) {
+        // An output-less resume keeps its retained path unless an earlier child of this workflow already owns it.
+        const resumeCollides = entry.resumedOutput !== undefined && input.claimedOutputPaths.has(resolveWorkflowHostOutputClaimPath(entry.resumedOutput));
+        if (resumeCollides || (entry.inherited && entry.path && (paths.get(resolveWorkflowHostOutputClaimPath(entry.path)) ?? 0) > 1)) {
             const output = workflowChildDefaultOutput(input.aggregateOutputPath, input.artifactsDir, input.workflowRunId, entry.key);
             overrides.set(entry.key, output);
             entry.path = output;
@@ -3353,6 +3390,16 @@ function workflowChildOutputClaims(input) {
         claims.set(claimPath, key);
         childClaims.set(key, claimPath);
     }
+    // Record a discovered output-less resume path for later admissions without adding same-batch duplicate errors.
+    for (const { key, path: resolved, resumedOutput } of resolvedEntries) {
+        if (resolved || !resumedOutput)
+            continue;
+        const claimPath = resolveWorkflowHostOutputClaimPath(resumedOutput);
+        if (claims.has(claimPath))
+            continue;
+        claims.set(claimPath, key);
+        childClaims.set(key, claimPath);
+    }
     return { claims, childClaims, overrides };
 }
 function applyWorkflowChildOutputClaims(target, claims) {
@@ -3363,7 +3410,7 @@ function applyWorkflowChildOutputClaims(target, claims) {
 function prepareWorkflowChildLaunchParams(input) {
     let childParams = input.childParams;
     const usesDefaultOutput = input.childParams.output === undefined && input.childParams.resume === undefined;
-    if (usesDefaultOutput && input.outputOverride !== undefined) {
+    if (input.childParams.output === undefined && input.outputOverride !== undefined) {
         childParams = { ...input.childParams, output: input.outputOverride };
     }
     else if (usesDefaultOutput && input.aggregateOutputPath !== undefined) {
@@ -3380,7 +3427,7 @@ function prepareWorkflowChildLaunchParams(input) {
     const agent = typeof childParams.agent === "string"
         ? resolveAgentName(childParams.agent, discoveredAgents).agent ?? resolveAgentName(childParams.agent, input.agents).agent
         : undefined;
-    const externalAsyncRequired = agent?.runner?.type === "external-cli" || agent?.runner?.type === "external-job";
+    const externalAsyncRequired = agent?.runner?.type === "external-cli" || agent?.runner?.type === "external-job" || agent?.launcher !== undefined;
     return prepareWorkflowLaunchParams(input.workflowDefaults, childParams, input.parentWorkflowRunId, input.workflowKey, { ...input.options, externalAsyncRequired, outputClaimPath: input.outputClaimPath });
 }
 async function finalizeSingleWorktreeHandoff(input) {
@@ -3604,6 +3651,7 @@ async function runSinglePath(data, deps) {
     const interruptController = new AbortController();
     let detachForeground;
     let childSessionControls;
+    let pendingRuntimeStop;
     const foregroundControl = deps.state.foregroundControls.get(runId);
     const syncHerdrForegroundChild = () => {
         if (!foregroundControl?.parentWorkflowRunId)
@@ -3679,6 +3727,7 @@ async function runSinglePath(data, deps) {
         ? new Promise((resolve) => { resolveDetachedWorkflowChild = resolve; })
         : undefined;
     try {
+        const childSessionFile = sessionFileForTask(params.agent, 0, modelOverride, modelOverrideFromParent, modelOrigin);
         const launched = await runSync(ctx.cwd, agents, params.agent, task, compactOptional({
             machine: foregroundMachine,
             parentProviderRegistry: ctx.modelRegistry,
@@ -3687,9 +3736,14 @@ async function runSinglePath(data, deps) {
             permissions: deps.config.permissions,
             runtimeSnapshotHost: deps.pi,
             parentSessionId: ctx.sessionManager.getSessionId() ?? undefined,
+            parentSessionFile: ctx.sessionManager.getSessionFile() ?? undefined,
             requiredExtensions,
             childRuntime: deps.childRuntime,
-            onChildSession: (controls) => { childSessionControls = controls; },
+            onChildSession: (controls) => {
+                childSessionControls = controls;
+                if (pendingRuntimeStop)
+                    controls.stop(pendingRuntimeStop);
+            },
             context: data.contextPolicy.contextForAgent(params.agent),
             unknownAgentDiagnosticContext: data.unknownAgentDiagnosticContext,
             runFanoutBudget: params.runFanoutAdmitted ? data.runFanoutBudget : { ...data.runFanoutBudget, parentPath: `${data.runFanoutBudget.parentPath ? `${data.runFanoutBudget.parentPath}/` : ""}single` },
@@ -3702,7 +3756,7 @@ async function runSinglePath(data, deps) {
             intercomEvents: deps.pi.events,
             runId,
             sessionDir: sessionDirForIndex(0),
-            sessionFile: sessionFileForTask(params.agent, 0, modelOverride, modelOverrideFromParent, modelOrigin),
+            sessionFile: childSessionFile,
             share: shareEnabled,
             artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
             artifactConfig,
@@ -3743,6 +3797,8 @@ async function runSinglePath(data, deps) {
                 detachForeground = detach;
             },
             onDetachedExit: async (result) => {
+                if (foregroundControl)
+                    foregroundControl.stopForRuntimeReplacement = undefined;
                 if (resolveDetachedWorkflowChild) {
                     resolveDetachedWorkflowChild(result);
                     return;
@@ -3794,6 +3850,20 @@ async function runSinglePath(data, deps) {
             capabilityCeiling: data.capabilityCeiling,
             allowZeroToolBudget: data.allowZeroToolBudget && effectiveToolBudget.toolBudget === data.toolBudget,
         }));
+        if (launched.detached && foregroundControl) {
+            // Record the stop before aborting so the next runtime's history restore finds it.
+            foregroundControl.stopForRuntimeReplacement = () => {
+                // The detach receipt predates the session file that resume needs.
+                const sessionFile = childSessionFile && fs.existsSync(childSessionFile) ? childSessionFile : undefined;
+                const stopped = { ...launched, detached: undefined, stopped: true, exitCode: 1, error: RUNTIME_REPLACED_STOP_ERROR, finalOutput: RUNTIME_REPLACED_STOP_ERROR, sessionFile };
+                rememberForegroundRun(deps.state, { modelResponseAliases, runId, mode: "single", cwd: singleCwd, sessionId: data.parentSessionId, results: [stopped], params, effectiveOutput, effectiveOutputMode, extensionBindings: params.extensionBindings, requiredExtensions });
+                // A child detached during creation has no controls yet; stop it as soon as they arrive.
+                if (childSessionControls)
+                    childSessionControls.stop(RUNTIME_REPLACED_STOP_ERROR);
+                else
+                    pendingRuntimeStop = RUNTIME_REPLACED_STOP_ERROR;
+            };
+        }
         r = launched.detached && detachedWorkflowChild ? await detachedWorkflowChild : launched;
     }
     catch (error) {
@@ -3904,7 +3974,7 @@ async function runSinglePath(data, deps) {
             isError: true,
         };
     return {
-        content: [{ type: "text", text: `${finalizedOutput.displayOutput || "(no output)"}${worktreeSuffix}` }],
+        content: [{ type: "text", text: `${capInlineOutput(finalizedOutput.displayOutput, { artifactPath: r.artifactPaths?.outputPath, savedPath: finalizedOutput.savedPath }) || "(no output)"}${worktreeSuffix}` }],
         details,
     };
 }
@@ -4107,7 +4177,7 @@ function workflowRunningChildrenSummary(children) {
 function workflowResultChildren(children, status, includeFailureFields) {
     return withWorkflowRevivals(DIRS.async, status.runId, children).map((child) => {
         const sessionName = status.steps?.find((step) => step.workflowKey === child.key)?.sessionName;
-        return { workflowKey: child.key, ...(child.agent ? { agent: child.agent } : {}), ...(child.runId ? { runId: child.runId } : {}), ...(child.revival ? { revival: formatWorkflowKeyRevival(child.revival) } : {}), ...(sessionName ? { sessionName } : {}), ...workflowChildAccountingFields(child), output: child.output, outputState: child.output.trim() || child.structuredOutput !== undefined ? "present" : "absent", structuredOutput: child.structuredOutput, ...(child.state === "running" ? { state: "running" } : { success: child.ok }), ...(child.asyncDir ? { asyncDir: child.asyncDir } : {}), ...(child.outputReference ? { outputReference: child.outputReference } : {}), ...(includeFailureFields && child.terminalOutcome ? { terminalOutcome: child.terminalOutcome } : {}), ...(child.outputPathMapping ? { outputPathMapping: child.outputPathMapping } : {}), ...(child.stopped ? { stopped: true } : {}), ...(child.interrupted ? { interrupted: true } : {}), ...(includeFailureFields && child.detached && status.state !== "complete" ? { detached: true } : {}), ...(child.outputArtifactPath || child.outputReference ? { artifactPaths: { outputPath: child.outputArtifactPath ?? child.outputReference } } : {}) };
+        return { workflowKey: child.key, ...(child.agent ? { agent: child.agent } : {}), ...(child.runId ? { runId: child.runId } : {}), ...(child.revival ? { revival: formatWorkflowKeyRevival(child.revival) } : {}), ...(sessionName ? { sessionName } : {}), ...workflowChildAccountingFields(child), output: child.output, outputState: child.output.trim() || child.structuredOutput !== undefined ? "present" : "absent", structuredOutput: child.structuredOutput, ...(child.state === "running" ? { state: "running" } : { success: child.ok }), ...(!child.ok && child.error ? { error: child.error } : {}), ...(child.asyncDir ? { asyncDir: child.asyncDir } : {}), ...(child.outputReference ? { outputReference: child.outputReference } : {}), ...(includeFailureFields && child.terminalOutcome ? { terminalOutcome: child.terminalOutcome } : {}), ...(child.outputPathMapping ? { outputPathMapping: child.outputPathMapping } : {}), ...(child.stopped ? { stopped: true } : {}), ...(child.interrupted ? { interrupted: true } : {}), ...(includeFailureFields && child.detached && status.state !== "complete" ? { detached: true } : {}), ...(child.outputArtifactPath || child.outputReference ? { artifactPaths: { outputPath: child.outputArtifactPath ?? child.outputReference } } : {}) };
     });
 }
 function workflowOutputPathMappingSummary(children) {
@@ -4141,6 +4211,7 @@ function workflowSteerReceipt(key, result) {
     };
 }
 const CHILD_SESSION_NOT_RUNNING_YET = "Child session is not running yet.";
+const RUNTIME_REPLACED_STOP_ERROR = "Subagent stopped because the pi-subagents runtime that ran it was replaced (reload or session switch).";
 const MAX_WORKFLOW_RESUME_HINT_BYTES = 1024;
 const MAX_WORKFLOW_CHILD_RUN_ID_BYTES = 256;
 const WORKFLOW_RESUME_HINT_PARENT_STATES = new Set(["complete", "failed", "partial"]);
@@ -4634,6 +4705,7 @@ function createScheduledOwnerState(source, ownerSessionId, ctx) {
     };
 }
 export function createSubagentExecutor(deps) {
+    const executorDeps = deps;
     const delegatedThinkingOverrides = new WeakMap();
     const delegatedZeroToolBudgets = new WeakSet();
     const delegatedExecutions = new WeakSet();
@@ -4657,6 +4729,10 @@ export function createSubagentExecutor(deps) {
         }
     };
     const execute = async (_id, params, signal, onUpdate, ctx, preserveActiveSession = false, parentModelOverride) => {
+        const projectScopeError = projectScopeTrustError(params, ctx);
+        if (projectScopeError)
+            return projectScopeError;
+        const deps = withSessionProjectTrust(executorDeps, ctx);
         const workflowLaunchObserver = workflowLaunchObservers.get(params);
         const inheritedUsageBudget = workflowOwnedUsageBudgets.get(params);
         const retainedRequiredExtensions = workflowRetainedRequiredExtensions.get(params);
@@ -4985,7 +5061,7 @@ export function createSubagentExecutor(deps) {
                     if (deps.state.currentSessionId !== currentSessionId || deps.state.completionOwnerId !== completionOwnerId)
                         return false;
                     try {
-                        deps.pi.sendMessage({
+                        (deps.parentWake ?? deps.pi).sendMessage({
                             customType: "subagent-workflow-result-write-failed",
                             content: message,
                             display: true,
@@ -5529,6 +5605,16 @@ export function createSubagentExecutor(deps) {
                                 const journalFingerprint = workflowJournalFingerprints.get(notification.childKey);
                                 if (journalFingerprint)
                                     appendWorkflowChildJournal(asyncDir, { type: "settle", key: notification.childKey, fingerprint: journalFingerprint, result: notification.result });
+                                // Fresh, journal-reused and re-attached children all settle here, so their rows take usage from the same result.
+                                const settledResults = notification.result.results ?? [];
+                                const settledStep = settledResults.length ? status.steps?.find((candidate) => candidate.workflowKey === notification.childKey) : undefined;
+                                if (settledStep) {
+                                    const usage = sumResultsUsage(settledResults);
+                                    settledStep.tokens = { input: usage.input, output: usage.output, total: usage.input + usage.output };
+                                    if (usage.turns > 0)
+                                        settledStep.turnCount = usage.turns;
+                                    persist({ tolerateStatusWriteFailure: true });
+                                }
                                 appendWorkflowEvent({
                                     type: "subagent.workflow.child_settled",
                                     childKey: notification.childKey,
@@ -5537,10 +5623,12 @@ export function createSubagentExecutor(deps) {
                                     workflowRunning: notification.workflowRunning,
                                 });
                                 try {
-                                    deps.pi.sendMessage({
+                                    (deps.parentWake ?? deps.pi).sendMessage({
                                         customType: "subagent-incremental-child-notify",
                                         content: formatIncrementalChildCompletion(notification),
                                         display: notification.outcome !== "completed",
+                                        // Render-only: Pi does not send details to the model.
+                                        details: { childKey: notification.childKey, outcome: notification.outcome },
                                     }, { triggerTurn: incrementalChildCompletionTriggersTurn(notification, requestParams.scheduleOrigin) });
                                 }
                                 catch (sendError) {
@@ -5600,7 +5688,7 @@ export function createSubagentExecutor(deps) {
                                     appendWorkflowChildJournal(asyncDir, { type: "start", key, fingerprint: journalFingerprint, runId: priorRunId });
                                     const stopListener = stopAwaitedAsyncChildOnAbort(workflowSignal, deps.state, priorRunId, priorAsyncDir, deps.kill);
                                     const reattached = await awaitExistingAsyncRun(priorAsyncDir, priorRunId, workflowSignal).finally(stopListener.remove);
-                                    const claimedPath = reattached.status === "settled" ? claimWorkflowAwaitedResult(priorAsyncDir, workflowRunId) : undefined;
+                                    const claimedPath = reattached.status === "settled" ? claimWorkflowAwaitedResult(priorAsyncDir, workflowRunId, { ...reattached.result.importedPublication, runId: priorRunId }) : undefined;
                                     if (reattached.status === "settled" && claimedPath) {
                                         const imported = importWorkflowAwaitedChildResult(reattached.result, { runId: priorRunId, asyncDir: priorAsyncDir, resultPath: claimedPath, task: typeof childParams.task === "string" ? childParams.task : "", parentWorkflowRunId: workflowReuseSource?.runId, details: { mode: "single", asyncId: priorRunId, asyncDir: priorAsyncDir, results: [] }, state: deps.state, pi: deps.pi });
                                         const reattachedResult = workflowChildResult(key, imported, childParams, deps.state);
@@ -6408,7 +6496,10 @@ export function createSubagentExecutor(deps) {
             if (action === "guide") {
                 try {
                     const guide = readSubagentGuide(paramsWithResolvedCwd.topic);
-                    const notice = paramsWithResolvedCwd.topic === "tool-reference" ? disabledFeatureNotice(disabledFeatures) : undefined;
+                    const [topic, section] = paramsWithResolvedCwd.topic?.split("/") ?? [];
+                    const fullNotice = topic === "tool-reference" ? disabledFeatureNotice(disabledFeatures) : undefined;
+                    // Sections are capped at 8,000 chars, so they get a one-line pointer instead of the full list.
+                    const notice = fullNotice && section !== undefined ? "Some options and actions documented here are disabled by config in this session; guide topic tool-reference lists them." : fullNotice;
                     return {
                         content: [{ type: "text", text: notice ? `${notice}\n\n${guide}` : guide }],
                         details: { mode: "management", results: [] },
@@ -6433,10 +6524,13 @@ export function createSubagentExecutor(deps) {
             if (action === "doctor") {
                 let currentSessionFile = null;
                 let currentSessionId = deps.state.currentSessionId;
+                let budgetSessionId = deps.state.currentSessionId;
                 let sessionError;
                 try {
                     currentSessionFile = ctx.sessionManager.getSessionFile() ?? null;
                     currentSessionId = ctx.sessionManager.getSessionId();
+                    // Launch admission's key (resolveCurrentSessionId) without its throw for an unbound session.
+                    budgetSessionId = currentSessionFile ?? currentSessionId;
                 }
                 catch (error) {
                     sessionError = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
@@ -6449,9 +6543,9 @@ export function createSubagentExecutor(deps) {
                     if (!sessionError)
                         sessionError = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
                 }
-                const spawnBudget = getSpawnBudgetSnapshot(deps.state, deps.config, currentSessionId);
-                const activeAsyncCapacity = currentSessionId
-                    ? getActiveAsyncCapacitySnapshot(currentSessionId, resolveMaxActiveAsyncRunsPerSession(deps.config.maxActiveAsyncRunsPerSession), { liveWorkflowRunIds: new Set(deps.state.workflowControllers?.keys() ?? []), abandonedSlotReleaseAfterMs: resolveAbandonedSlotReleaseAfterMs(deps.config.capacity?.abandonedSlotReleaseAfterMs) })
+                const spawnBudget = getSpawnBudgetSnapshot(deps.state, deps.config, budgetSessionId);
+                const activeAsyncCapacity = budgetSessionId
+                    ? getActiveAsyncCapacitySnapshot(budgetSessionId, resolveMaxActiveAsyncRunsPerSession(deps.config.maxActiveAsyncRunsPerSession), { liveWorkflowRunIds: new Set(deps.state.workflowControllers?.keys() ?? []), abandonedSlotReleaseAfterMs: resolveAbandonedSlotReleaseAfterMs(deps.config.capacity?.abandonedSlotReleaseAfterMs) })
                     : { used: 0, limit: resolveMaxActiveAsyncRunsPerSession(deps.config.maxActiveAsyncRunsPerSession) ?? 0 };
                 deps.state.activeAsyncCapacity = activeAsyncCapacity;
                 return {
@@ -6465,6 +6559,8 @@ export function createSubagentExecutor(deps) {
                                 requestedSessionDir: paramsWithResolvedCwd.sessionDir,
                                 currentSessionFile,
                                 currentSessionId,
+                                spawnBudget,
+                                activeAsyncCapacity,
                                 orchestratorTarget,
                                 sessionError,
                                 expandTilde: deps.expandTilde,
@@ -6965,16 +7061,28 @@ export function createSubagentExecutor(deps) {
             : hasTasks
                 ? (effectiveParams.tasks ?? []).map((task) => task.agent)
                 : (effectiveParams.chain ?? []).flatMap((step) => getStepAgents(step));
-        const externalAgent = selectedAgentNames
-            .map((name) => agents.find((agent) => agent.name === name))
-            .find((agent) => agent?.runner?.type === "external-cli" || agent?.runner?.type === "external-job");
-        const externalAsyncRequired = Boolean(externalAgent) && effectiveParams.async === undefined && effectiveParams.clarify !== true && effectiveParams.foregroundOnly !== true;
+        const selectedAgents = selectedAgentNames.map((name) => agents.find((agent) => agent.name === name));
+        const externalAgent = selectedAgents.find((agent) => agent?.runner?.type === "external-cli" || agent?.runner?.type === "external-job");
+        const launcherAgent = selectedAgents.find((agent) => agent?.launcher !== undefined);
+        // A launcher agent goes to the background whenever the caller omitted async, even if the agent file defaults to foreground.
+        const externalAsyncRequired = effectiveParams.foregroundOnly !== true && ((Boolean(externalAgent) && effectiveParams.async === undefined && effectiveParams.clarify !== true)
+            || (Boolean(launcherAgent) && normalizedParams.async === undefined && normalizedParams.clarify !== true));
         const requestedAsync = externalAsyncRequired ? true : effectiveParams.async ?? deps.asyncByDefault;
         const backgroundRequestedWhileClarifying = (hasChain || hasTasks) && requestedAsync && effectiveParams.clarify === true;
         const effectiveAsync = requestedAsync && effectiveParams.clarify !== true;
         if (externalAgent && (!effectiveAsync || effectiveParams.foregroundOnly === true)) {
             return buildRequestedModeError(effectiveParams, `Agent '${externalAgent.name}' uses runner.type='${externalAgent.runner?.type}', which currently supports async/background execution only. Omit async or pass async:true; clarify and foregroundOnly are unsupported.`);
         }
+        // forceTopLevelAsync rewrites async:false and clarify, so check what the caller asked for.
+        if (launcherAgent && (!effectiveAsync || normalizedParams.async === false || normalizedParams.clarify === true || effectiveParams.foregroundOnly === true)) {
+            return buildRequestedModeError(effectiveParams, `Agent '${launcherAgent.name}' uses launcher '${launcherAgent.launcher}', which wraps the background runner only. Foreground children run inside the parent process, so a launcher cannot wrap them. Omit async or pass async:true; clarify and foregroundOnly are unsupported.`);
+        }
+        // Refuse a launcher launch that cannot start before fan-out admission or a session directory exists.
+        for (const agent of selectedAgents) {
+            const launcherError = agent ? resolveAgentRunnerLauncher(agent, deps.config.runnerLaunchers, effectiveParams.machine ?? agent.machine).error : undefined;
+            if (launcherError)
+                return buildRequestedModeError(effectiveParams, launcherError);
+        }
         if (effectiveAsync && hasSingle && effectiveParams.resume === undefined && effectiveParams.worktree === true) {
             try {
                 await preflightWorktreeSource(effectiveCwd, { signal });
@@ -7168,6 +7276,7 @@ export function createSubagentExecutor(deps) {
             backgroundRequestedWhileClarifying,
             effectiveAsync,
             asyncRunId,
+            toolCallId: _id,
             controlConfig,
             ...(delegatedExecution ? { suppressUnchangedDelegationUpdates: true } : {}),
             intercomBridge,