pi-subagents 0.56.0 → 0.58.0

package/src/runs/background/subagent-runner.ts

@@ -14,6 +14,7 @@ import { createChildTranscriptWriter, type ChildTranscriptWriter } from "../../s
 import { closeSteerInbox, consumeInterruptRequest, consumeSteerRequests, deliverInterruptRequest, deliverStopRequest, deliverTimeoutRequest, enqueueStepSteer, steerAcksDir, steerCapabilityPath, stepSteerInboxDir, watchAsyncControlInbox, type SteerAck, type SteerCapability, type SteerRequest, type StopRequest } from "./control-channel.ts";
 import { appendJsonl as appendRawJsonl, formatOutputArtifactContent, getArtifactPaths, writeArtifact, writeMetadata } from "../../shared/artifacts.ts";
 import { PI_CODING_AGENT_PACKAGE, getPiSpawnCommand, resolveInstalledPiPackageRoot } from "../shared/pi-spawn.ts";
+import { preflightLaunchCwd } from "../shared/launch-cwd.ts";
 import { captureSingleOutputSnapshot, extractChildWrittenOutput, finalizeSingleOutput, formatSavedOutputReference, injectOutputPathSystemPrompt, injectSingleOutputInstruction, resolveSingleOutput, type SingleOutputSnapshot } from "../shared/single-output.ts";
 import {
 	type ActivityState,
@@ -49,6 +50,7 @@ import {
 	type SteeringTargetState,
 	type SteeringTargetStatus,
 	type SubagentChildStatusEvent,
+	type SettlementDiagnostic,
 	DEFAULT_MAX_OUTPUT,
 	type MaxOutputConfig,
 	SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
@@ -81,13 +83,13 @@ import { applyThinkingSuffix, buildPiArgs, cleanupTempDir, projectLaunchResolved
 import { readRuntimeAcknowledgedExtensions } from "../shared/runtime-acknowledged-extensions.ts";
 import { outputEntryFromAsyncResult, resolveOutputReferences } from "../shared/chain-outputs.ts";
 import { createStructuredOutputRuntime, MISSING_STRUCTURED_OUTPUT_CALL_ERROR, readStructuredOutput, readStructuredOutputAcceptanceReport } from "../shared/structured-output.ts";
-import { formatProcessSignalError, isUnexplainedProcessSignal } from "../shared/process-signal.ts";
+import { formatMidToolExitError, formatProcessSignalError, isOrdinaryToolForMidToolExit, isUnexplainedProcessSignal } from "../shared/process-signal.ts";
 import { readChildToolDiagnosticError } from "../shared/tool-availability.ts";
 import { buildTimeoutRecoverySummary, collectTrackedMutationEvidence, snapshotTrackedMutations } from "../shared/mutation-evidence.ts";
 import { collectDynamicResults, DynamicFanoutError, materializeDynamicParallelStep, validateDynamicCollection } from "../shared/dynamic-fanout.ts";
 import { claimRunFanoutBatch, getRunFanoutBudgetSnapshot } from "../shared/run-fanout-budget.ts";
 import { nestedSummaryFromAsyncStatus, projectNestedEvents, resolveNestedAsyncDir, writeNestedEvent } from "../shared/nested-events.ts";
-import { formatModelAttemptNote, formatSubagentModelVerificationError, isContextOverflow, isRetryableModelFailure, recordRetryableModelFailure } from "../shared/model-fallback.ts";
+import { formatModelAttemptNote, formatSubagentModelVerificationError, isContextOverflow, isRetryableModelFailureAttempt, recordRetryableModelFailure } from "../shared/model-fallback.ts";
 import {
 	SUBAGENT_STARTUP_RETRY_DELAYS_MS,
 	formatSubagentExtensionConflictError,
@@ -101,7 +103,7 @@ import { createOwnedProcessTreeController, type OwnedProcessTreeController } fro
 import { createSteeringStatus, recordSteeringRequest, steeringStatus, terminalSteeringNoticeState, updateSteeringTarget } from "./steering.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
 import { PROMPT_REDACTED, detectSubagentError, extractTextFromContent, extractToolArgsPreview, getFinalOutput, hasEmptyTerminalAssistantResponse, readStatus } from "../../shared/utils.ts";
-import { evaluateCompletionMutationGuard, validateImplementationToolContract } from "../shared/completion-guard.ts";
+import { evaluateCompletionMutationGuard, expectsImplementationMutation, hasMutationToolCapability, validateImplementationToolContract } from "../shared/completion-guard.ts";
 import {
 	createMutatingFailureState,
 	didMutatingToolFail,
@@ -124,7 +126,7 @@ import {
 	formatWorktreeTaskCwdConflict,
 	type WorktreeSetup,
 } from "../shared/worktree.ts";
-import { resolveEffectiveThinking } from "../../shared/model-info.ts";
+import { findModelInfo, resolveEffectiveThinking } from "../../shared/model-info.ts";
 import { assertThinkingWithinCeiling, decodeThinkingCeiling, SUBAGENT_THINKING_CEILING_ENV } from "../../shared/thinking-ceiling.ts";
 import { launchBindingDigest } from "../../shared/launch-contract.ts";
 import { writeInitialProgressFile } from "../../shared/settings.ts";
@@ -141,9 +143,13 @@ import { effectiveToolTimeoutMs, formatToolTimeoutMessage, toolTimeoutCallKey }
 import { usageBudgetExceededMessage, usageBudgetState } from "../shared/usage-budget.ts";
 import { formatParallelHandoffError, formatParallelHandoffReference, parallelHandoffPath, writeParallelHandoffGroup, writePendingParallelHandoff } from "../shared/parallel-handoff.ts";
 import { resolveWatchdogConfig } from "../../watchdog/settings.ts";
-import { createBoundedByteTail, createBoundedLineReader, formatProtocolOutputLimit, MAX_CHILD_STDERR_BYTES, PI_AGGREGATE_EVENT_PROJECTOR, projectChildLifecycle, type ChildLifecycleAction, type ProtocolOutputLimit } from "../shared/child-protocol.ts";
+import { createBoundedByteTail, createBoundedLineReader, formatProtocolOutputLimit, MAX_CHILD_STDERR_BYTES, PI_AGGREGATE_EVENT_PROJECTOR, projectChildLifecycle, type ChildLifecycleAction, type ChildLifecycleState, type ProtocolOutputLimit } from "../shared/child-protocol.ts";
 import { acquireSessionLease, type SessionLeaseRequest } from "../shared/session-lease.ts";
 import { buildExternalCliPrompt, runExternalCli } from "../shared/external-cli-runner.ts";
+import { resolveClaudeCodeLaunch } from "../shared/claude-code-adapter.ts";
+import { resolveCodexExecLaunch } from "../shared/codex-exec-adapter.ts";
+import { resolveCursorAgentLaunch } from "../shared/cursor-agent-adapter.ts";
+import { resolveExternalCliRunnerStatus } from "../shared/external-cli-contract.ts";
 import { runExternalJob } from "../shared/external-job-runner.ts";
 import { createOrcaProgressTab, type OrcaProgressTab } from "../shared/orca-progress-tabs.ts";
 import { decodeSubagentCapabilityCeiling, SUBAGENT_CAPABILITY_CEILING_ENV, type ResolvedSubagentCapabilityCeiling } from "../shared/capability-ceiling.ts";
@@ -206,6 +212,7 @@ interface SubagentRunConfig {
 	launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
 	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
 	runnerProcessInstanceId?: string;
+	launchBarrierToken?: string;
 	parentWorkflowRunId?: string;
 	workflowKey?: string;
 }
@@ -496,6 +503,7 @@ interface ChildUsage {
 	output?: number;
 	outputTokens?: number;
 	cacheRead?: number;
+	cacheReadTokens?: number;
 	cacheWrite?: number;
 	cost?: { total?: number };
 }
@@ -537,6 +545,7 @@ interface RunPiStreamingResult {
 	observedMutationAttempt?: boolean;
 	structuredOutputToolInvoked?: boolean;
 	structuredOutputMessageStartIndex?: number;
+	structuredOutput?: unknown;
 	watchdog?: ChildWatchdogStateSnapshot;
 	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
 	processInstanceId: string;
@@ -546,6 +555,28 @@ interface RunPiStreamingResult {
 	currentTool?: string;
 	currentToolArgs?: string;
 	currentPath?: string;
+	afterCompactionSettlement?: boolean;
+	effects?: import("../../shared/types.ts").EffectsProjection;
+}
+
+const MAX_CHILD_FAILURE_DIAGNOSTIC_CHARS = 8_192;
+
+function formatChildFailureDiagnostic(input: {
+	error: string | undefined;
+	afterCompactionSettlement?: boolean;
+	missingFileOnlyOutput?: string;
+	missingStructuredOutput?: string;
+}): string | undefined {
+	const notes = [
+		input.afterCompactionSettlement ? "Child failure followed session compaction and agent settlement." : undefined,
+		input.missingFileOnlyOutput ? `Required file-only output was not produced: ${input.missingFileOnlyOutput.slice(0, 2_048)}` : undefined,
+		input.missingStructuredOutput ? `Required structured output was not produced: ${input.missingStructuredOutput.slice(0, 2_048)}` : undefined,
+	].filter((note): note is string => Boolean(note));
+	if (notes.length === 0) return input.error;
+	const context = notes.join("\n");
+	const errorLimit = MAX_CHILD_FAILURE_DIAGNOSTIC_CHARS - (context ? context.length + 1 : 0);
+	const baseError = input.error || "Subagent failed.";
+	return `${baseError.slice(0, Math.max(0, errorLimit))}${context ? `\n${context}` : ""}`;
 }
 
 function runPiStreaming(
@@ -571,6 +602,7 @@ function runPiStreaming(
 	orcaProgressTab?: OrcaProgressTab,
 	expectedModelForVerification?: string,
 	modelVerificationRegistry?: Array<{ provider: string; id: string; fullId: string }>,
+	mutationTools?: readonly string[],
 ): Promise<RunPiStreamingResult> {
 	return new Promise((resolve) => {
 		const startedAt = Date.now();
@@ -620,8 +652,50 @@ function runPiStreaming(
 		let currentToolArgs: string | undefined;
 		let currentPath: string | undefined;
 		let toolCount = 0;
+		type ActiveToolCall = { key: string; tool: string; args?: string; path?: string };
+		let activeToolSequence = 0;
+		const activeToolCalls = new Map<string, ActiveToolCall>();
+		const activeToolKeysByName = new Map<string, string[]>();
+		const refreshCurrentTool = (): void => {
+			const active = [...activeToolCalls.values()].at(-1);
+			currentTool = active?.tool;
+			currentToolArgs = active?.args;
+			currentPath = active?.path;
+		};
+		const recordActiveToolCall = (event: { toolCallId?: unknown; toolName: string; args?: Record<string, unknown> }): void => {
+			const key = toolTimeoutCallKey(event, ++activeToolSequence);
+			const active = omitUndefinedProperties({
+				key,
+				tool: event.toolName,
+				args: extractToolArgsPreview(event.args ?? {}),
+				path: resolveCurrentPath(event.toolName, event.args),
+			});
+			activeToolCalls.set(key, active);
+			const keys = activeToolKeysByName.get(active.tool) ?? [];
+			keys.push(key);
+			activeToolKeysByName.set(active.tool, keys);
+			refreshCurrentTool();
+		};
+		const removeActiveToolCall = (event: { toolCallId?: unknown; toolName?: unknown }): void => {
+			const key = typeof event.toolCallId === "string" && event.toolCallId.length > 0
+				? `id:${event.toolCallId}`
+				: typeof event.toolName === "string"
+					? activeToolKeysByName.get(event.toolName)?.[0]
+					: activeToolCalls.size === 1
+						? [...activeToolCalls.keys()][0]
+						: undefined;
+			if (!key) return;
+			const active = activeToolCalls.get(key);
+			if (!active) return;
+			activeToolCalls.delete(key);
+			const keys = activeToolKeysByName.get(active.tool)?.filter((candidate) => candidate !== key) ?? [];
+			if (keys.length > 0) activeToolKeysByName.set(active.tool, keys);
+			else activeToolKeysByName.delete(active.tool);
+			refreshCurrentTool();
+		};
 		const childWatchdogConfig = decodeChildWatchdogConfig(env?.[CHILD_WATCHDOG_CONFIG_ENV]);
 		let childWatchdogState: ChildWatchdogStateSnapshot | undefined;
+		const childLifecycleState: ChildLifecycleState = { compactionRetryActive: false };
 		let applyChildLifecycle = (_action: ChildLifecycleAction): void => {};
 		const updateChildWatchdogState = (snapshot: ChildWatchdogStateSnapshot): void => {
 			childWatchdogState = snapshot;
@@ -672,8 +746,10 @@ function runPiStreaming(
 
 			appendChildEvent(event as unknown as Record<string, unknown>);
 			transcriptWriter?.writeChildEvent(event);
-			if (event.type === "agent_settled") agentSettledReceived = true;
-			applyChildLifecycle(projectChildLifecycle(event));
+			if (event.type === "compaction_start") compactionStartedReceived = true;
+			const lifecycleAction = projectChildLifecycle(event, false, childLifecycleState);
+			if (event.type === "agent_settled" && lifecycleAction === "start-drain") agentSettledReceived = true;
+			applyChildLifecycle(lifecycleAction);
 
 			if (isChildWatchdogStatusEvent(event)) {
 				if (!childWatchdogConfig) return;
@@ -710,29 +786,32 @@ function runPiStreaming(
 
 			if (event.type === "tool_execution_end") {
 				clearActiveToolTimeout(event);
-				currentTool = undefined;
-				currentToolArgs = undefined;
-				currentPath = undefined;
+				removeActiveToolCall(event);
 				return;
 			}
 
 			if (event.type === "tool_execution_start" && event.toolName) {
 				toolCount += 1;
 				armToolTimeout({ toolCallId: (event as { toolCallId?: unknown }).toolCallId, toolName: event.toolName });
-				currentTool = event.toolName;
-				currentToolArgs = extractToolArgsPreview(event.args ?? {});
-				currentPath = resolveCurrentPath(event.toolName, event.args);
+				recordActiveToolCall({ toolCallId: (event as { toolCallId?: unknown }).toolCallId, toolName: event.toolName, args: event.args });
 				if (event.toolName === "structured_output") {
 					structuredOutputToolInvoked = true;
 					structuredOutputMessageStartIndex = messages.length;
 				}
-				observedMutationAttempt = observedMutationAttempt || isMutatingTool(event.toolName, event.args);
+				observedMutationAttempt = observedMutationAttempt || isMutatingTool(event.toolName, event.args, mutationTools);
 				const toolArgs = extractToolArgsPreview(event.args ?? {});
 				writeOutputLine(toolArgs ? `${event.toolName}: ${toolArgs}` : event.toolName);
 				return;
 			}
 
 			if ((event.type === "message_end" || event.type === "tool_result_end") && event.message) {
+				if (event.type === "tool_result_end") {
+					clearActiveToolTimeout(event);
+					removeActiveToolCall({
+						toolCallId: (event.message as { toolCallId?: unknown }).toolCallId ?? (event as { toolCallId?: unknown }).toolCallId,
+						toolName: (event.message as { toolName?: unknown }).toolName ?? event.toolName,
+					});
+				}
 				messages.push(event.message);
 				const text = extractTextFromContent(event.message.content);
 				if (text) writeOutputText(text);
@@ -759,7 +838,11 @@ function runPiStreaming(
 				if (isTerminalAssistantStop(event.message)) {
 					if (!event.message.errorMessage && extractTextFromContent(event.message.content).trim()) assistantError = undefined;
 					cleanTerminalAssistantStopReceived ||= !event.message.errorMessage;
-					applyChildLifecycle(projectChildLifecycle(event, true));
+					clearAllToolTimeouts();
+					activeToolCalls.clear();
+					activeToolKeysByName.clear();
+					refreshCurrentTool();
+					applyChildLifecycle(projectChildLifecycle(event, true, childLifecycleState));
 				}
 			}
 		};
@@ -772,6 +855,7 @@ function runPiStreaming(
 		let forcedTerminationSignal = false;
 		let cleanTerminalAssistantStopReceived = false;
 		let agentSettledReceived = false;
+		let compactionStartedReceived = false;
 		let finalDrainTimer: NodeJS.Timeout | undefined;
 		let finalHardKillTimer: NodeJS.Timeout | undefined;
 		let watchdogTailTimer: NodeJS.Timeout | undefined;
@@ -1047,6 +1131,7 @@ function runPiStreaming(
 				currentTool,
 				currentToolArgs,
 				currentPath,
+				afterCompactionSettlement: (compactionStartedReceived && agentSettledReceived) || undefined,
 			}));
 		});
 
@@ -1219,7 +1304,7 @@ interface SingleStepContext {
 	nestedRoute?: NestedRouteInfo;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 	runFanoutBudget?: RunFanoutBudgetDescriptor;
-	onAttemptStart?: (attempt: { model?: string; thinking?: string }) => void;
+	onAttemptStart?: (attempt: { model?: string; thinking?: string; contextLimit?: number }) => void;
 	onChildEvent?: (event: ChildEvent) => void;
 	onWriterProcess?: (writer: { state: "none" | "spawning" } | { state: "running"; pid: number }) => void;
 	onExternalProcess?: (process: ExternalProcessStatus) => void;
@@ -1321,6 +1406,8 @@ async function runSingleStepInner(
 			model: step.model,
 			modelCandidates: step.modelCandidates,
 			mcpDirectTools: step.mcpDirectTools,
+			mcpConfig: step.mcpConfig,
+			runtimeServerNames: step.runtimeServerNames,
 			cwd: step.cwd ?? ctx.cwd,
 			requireReadTool: Boolean(step.skills?.length),
 			structuredOutput: Boolean(effectiveStructuredOutput),
@@ -1381,21 +1468,29 @@ async function runSingleStepInner(
 	transcriptWriter?.writeInitialUserMessage(`${PROMPT_REDACTED}; live Prompt Audit only.`);
 
 	if (step.runner?.type === "external-cli") {
-		const runner: ExternalCliRunnerStatus = {
-			type: "external-cli",
-			command: step.runner.command,
-			args: step.runner.args ?? [],
-			promptDelivery: step.runner.promptDelivery ?? "stdin",
-			capabilities: { stop: true, steer: false, resume: false, structuredOutput: false, toolEvents: false },
-		};
+		const externalCwd = step.cwd ?? ctx.cwd;
+		const adapterLaunch = step.runner.adapter === "codex-exec" || step.runner.adapter === "codex-exec-writer"
+			? resolveCodexExecLaunch({ adapter: step.runner.adapter, command: step.runner.command, asyncDir: path.dirname(ctx.outputFile), stepIndex: ctx.flatIndex })
+			: step.runner.adapter === "claude-code" || step.runner.adapter === "claude-code-writer"
+				? resolveClaudeCodeLaunch({ adapter: step.runner.adapter, command: step.runner.command })
+				: step.runner.adapter === "cursor-agent" || step.runner.adapter === "cursor-agent-writer"
+					? resolveCursorAgentLaunch({ adapter: step.runner.adapter, command: step.runner.command, cwd: externalCwd, asyncDir: path.dirname(ctx.outputFile), stepIndex: ctx.flatIndex })
+				: undefined;
+		const runner = resolveExternalCliRunnerStatus({ ...step.runner, ...(adapterLaunch ? { args: adapterLaunch.args } : {}) });
 		const outputSnapshot = captureSingleOutputSnapshot(step.outputPath);
 		const external = await runExternalCli(omitUndefinedProperties({
-			command: runner.command,
-			args: runner.args,
-			cwd: step.cwd ?? ctx.cwd,
+			command: adapterLaunch?.command ?? runner.command,
+			args: adapterLaunch?.args ?? runner.args,
+			cwd: externalCwd,
 			prompt: buildExternalCliPrompt(step.systemPrompt ?? "", task),
 			asyncDir: path.dirname(ctx.outputFile),
 			stepIndex: ctx.flatIndex,
+			environment: adapterLaunch?.environment,
+			preflight: adapterLaunch?.preflight,
+			parser: adapterLaunch?.parser,
+			finalOutputPath: adapterLaunch?.finalOutputPath,
+			promptFilePath: adapterLaunch?.promptFilePath,
+			temporaryDirectories: adapterLaunch?.temporaryDirectories,
 			registerTimeout: ctx.registerTimeout,
 			registerStop: ctx.registerStop,
 			timeoutMessage: ctx.timeoutMessage,
@@ -1508,6 +1603,10 @@ async function runSingleStepInner(
 		});
 	}
 
+	const effectiveCwd = step.cwd ?? ctx.cwd;
+	const cwdError = preflightLaunchCwd(step.requestedCwd ?? effectiveCwd, effectiveCwd);
+	if (cwdError) return { agent: step.agent, output: cwdError, error: cwdError, exitCode: 1, context: step.context };
+
 	const candidates = step.modelCandidates !== undefined
 		? step.modelCandidates.length > 0 ? step.modelCandidates : [undefined]
 		: step.model
@@ -1550,7 +1649,11 @@ async function runSingleStepInner(
 			const message = error instanceof Error ? error.message : String(error);
 			return omitUndefinedProperties({ agent: step.agent, output: message, error: message, exitCode: 1, context: step.context, thinkingCeiling: step.thinkingCeiling });
 		}
-		ctx.onAttemptStart?.(omitUndefinedProperties({ model: candidate, thinking: resolveEffectiveThinking(candidate, step.thinking) }));
+		ctx.onAttemptStart?.(omitUndefinedProperties({
+			model: candidate,
+			thinking: resolveEffectiveThinking(candidate, step.thinking),
+			contextLimit: findModelInfo(candidate, step.modelVerificationRegistry)?.contextWindow,
+		}));
 		const outputSnapshot = captureSingleOutputSnapshot(step.outputPath);
 		if (effectiveStructuredOutput) {
 			try {
@@ -1579,6 +1682,7 @@ async function runSingleStepInner(
 			sessionFile: step.sessionFile,
 			model: candidate,
 			inheritProjectContext: step.inheritProjectContext,
+			inheritGlobalContext: step.inheritGlobalContext,
 			inheritSkills: step.inheritSkills,
 			requireReadTool: Boolean(step.skills?.length),
 			tools: step.tools,
@@ -1589,6 +1693,8 @@ async function runSingleStepInner(
 			systemPrompt: appendTurnBudgetSystemPrompt(step.systemPrompt ?? "", ctx.turnBudget),
 			systemPromptMode: step.systemPromptMode,
 			mcpDirectTools: step.mcpDirectTools,
+			mcpConfig: step.mcpConfig,
+			runtimeServerNames: step.runtimeServerNames,
 			capabilityCeiling: step.capabilityCeiling ?? ctx.capabilityCeiling,
 			cwd: step.cwd ?? ctx.cwd,
 			promptFileStem: step.agent,
@@ -1632,6 +1738,8 @@ async function runSingleStepInner(
 				model: step.model,
 				modelCandidates: step.modelCandidates,
 				mcpDirectTools: step.mcpDirectTools,
+				mcpConfig: step.mcpConfig,
+				runtimeServerNames: step.runtimeServerNames,
 				cwd: step.cwd ?? ctx.cwd,
 				requireReadTool: Boolean(step.skills?.length),
 				structuredOutput: Boolean(effectiveStructuredOutput),
@@ -1651,6 +1759,7 @@ async function runSingleStepInner(
 				systemPrompt: appendTurnBudgetSystemPrompt(step.systemPrompt ?? "", ctx.turnBudget),
 				systemPromptMode: step.systemPromptMode,
 				inheritProjectContext: step.inheritProjectContext,
+				inheritGlobalContext: step.inheritGlobalContext,
 				inheritSkills: step.inheritSkills,
 				skills: step.skills,
 				tools: toolPlan.effectiveToolAllowlist,
@@ -1687,6 +1796,7 @@ async function runSingleStepInner(
 			ctx.orcaProgressTab,
 			expectedModelForVerification,
 			step.modelVerificationRegistry,
+			step.mutationTools,
 		);
 		if (run.processCloseObservedAt !== undefined) {
 			writerProcesses.push({
@@ -1723,11 +1833,25 @@ async function runSingleStepInner(
 			: undefined;
 		const runtimeAcknowledgedExtensions = readRuntimeAcknowledgedExtensions(runtimeAcknowledgedExtensionsPath);
 		cleanupTempDir(tempDir);
+		const midToolExitError = run.currentTool
+			&& isOrdinaryToolForMidToolExit(run.currentTool)
+			&& !run.interrupted
+			&& !run.timedOut
+			&& !run.stopped
+			&& !run.turnBudgetExceeded
+			&& !run.protocolError
+			&& !toolAvailabilityError
+			? formatMidToolExitError({
+				toolName: run.currentTool,
+				exitCode: run.exitCode,
+				processSignal: run.processSignal,
+			})
+			: undefined;
 
 		let structuredOutput: unknown;
 		let structuredError: string | undefined;
 		let validatedStructuredOutput = false;
-		if (effectiveStructuredOutput && run.exitCode === 0 && !run.error && !toolAvailabilityError) {
+		if (effectiveStructuredOutput && run.exitCode === 0 && !run.error && !toolAvailabilityError && !midToolExitError) {
 			if (!run.structuredOutputToolInvoked) {
 				structuredError = MISSING_STRUCTURED_OUTPUT_CALL_ERROR;
 			} else {
@@ -1749,7 +1873,7 @@ async function runSingleStepInner(
 		const errorMessages = validatedStructuredOutput
 			? run.messages.slice(run.structuredOutputMessageStartIndex ?? run.messages.length)
 			: run.messages;
-		const hiddenError = run.exitCode === 0 && !run.error && !toolAvailabilityError && !structuredError
+		const hiddenError = run.exitCode === 0 && !run.error && !toolAvailabilityError && !structuredError && !midToolExitError
 			? detectSubagentError(errorMessages)
 			: null;
 		const emptyOutputError = run.exitCode === 0
@@ -1763,16 +1887,18 @@ async function runSingleStepInner(
 			: undefined;
 		const completionGuardEnabled = isAgentContractV1(step.agentContract) ? step.completionGuard === true : step.completionGuard !== false;
 		const completionToolPlan = resolvedTaskToolPlan;
+		const completionTools = completionToolPlan ? (completionToolPlan.explicitToolAllowlist ? completionToolPlan.effectiveToolAllowlist : undefined) : step.tools;
 		const mutationEvidence = collectTrackedMutationEvidence(mutationSnapshot, step.cwd ?? ctx.cwd);
 		finalMutationEvidence = mutationEvidence;
 		const completionMutationEvidence = ctx.trackedMutationEvidenceForCompletionGuard === false ? undefined : mutationEvidence;
-		const completionGuard = run.exitCode === 0 && !run.error && !structuredError && !hiddenError?.hasError && !emptyOutputError && completionGuardEnabled
+		const completionGuard = run.exitCode === 0 && !run.error && !structuredError && !hiddenError?.hasError && !midToolExitError && !emptyOutputError && completionGuardEnabled
 			? evaluateCompletionMutationGuard(omitUndefinedProperties({
 				agent: step.agent,
 				task: taskForCompletionGuard,
 				messages: run.messages,
-				tools: completionToolPlan ? (completionToolPlan.explicitToolAllowlist ? completionToolPlan.effectiveToolAllowlist : undefined) : step.tools,
+				tools: completionTools,
 				mcpDirectTools: completionToolPlan?.effectiveMcpTools ?? step.mcpDirectTools,
+				mutationTools: step.mutationTools,
 				toolAvailabilityError,
 				mutationEvidence: completionMutationEvidence,
 			}))
@@ -1780,6 +1906,9 @@ async function runSingleStepInner(
 		const mutationAttemptObserved = run.observedMutationAttempt === true || completionMutationEvidence?.attemptedMutation === true;
 		const completionGuardTriggered = completionGuard?.triggered === true && !mutationAttemptObserved;
 		const completionGuardBlocked = completionGuard?.blocked === true;
+		const mutationExpected = completionGuard?.expectedMutation ?? (completionGuardEnabled
+			&& hasMutationToolCapability(completionTools, completionToolPlan?.effectiveMcpTools ?? step.mcpDirectTools)
+			&& expectsImplementationMutation(step.agent, taskForCompletionGuard));
 		const fileMutationEffect = completionGuard
 			? {
 				status: completionGuardBlocked ? "blocked" as const : completionGuard.expectedMutation ? completionGuardTriggered ? "missing" as const : "observed" as const : "not-applicable" as const,
@@ -1793,7 +1922,7 @@ async function runSingleStepInner(
 		const completionGuardError = completionGuardTriggered && !isAgentContractV1(step.agentContract)
 			? "Subagent completed without making edits for an implementation task.\nIt appears to have returned planning or scratchpad output instead of applying changes."
 			: undefined;
-		const effectiveExitCode = toolAvailabilityError || (completionGuardTriggered && !isAgentContractV1(step.agentContract)) || structuredError || emptyOutputError
+		const effectiveExitCode = toolAvailabilityError || (completionGuardTriggered && !isAgentContractV1(step.agentContract)) || midToolExitError || structuredError || emptyOutputError
 			? 1
 			: hiddenError?.hasError
 				? (hiddenError.exitCode ?? 1)
@@ -1810,6 +1939,7 @@ async function runSingleStepInner(
 		const error = formatSubagentExtensionConflictError(
 			toolAvailabilityError
 				?? completionGuardError
+				?? midToolExitError
 				?? structuredError
 				?? emptyOutputError
 				?? (hiddenError?.hasError
@@ -1839,7 +1969,24 @@ async function runSingleStepInner(
 			toolBudgetBlocked = Boolean(blockedMessage);
 			toolBudget = toolBudgetState(step.toolBudget, toolMessages.length, blockedMessage ? (blockedMessage as { toolName?: string }).toolName : undefined);
 		}
-		finalResult = { ...run, exitCode: effectiveExitCode, model: candidate ?? run.model, error, structuredOutput, runtimeAcknowledgedExtensions, ...(step.agentContract ? { agentContract: step.agentContract } : {}), ...(fileMutationEffect ? { effects: { fileMutation: fileMutationEffect } } : {}) } as RunPiStreamingResult & { structuredOutput?: unknown; agentContract?: import("../../shared/types.ts").AgentContract; effects?: import("../../shared/types.ts").EffectsProjection };
+		const requiredOutput = step.outputMode === "file-only" && step.outputPath
+			? { kind: "file-only" as const, path: step.outputPath, missing: !fs.existsSync(step.outputPath) }
+			: effectiveStructuredOutput
+				? { kind: "structured" as const, path: effectiveStructuredOutput.outputPath, missing: !fs.existsSync(effectiveStructuredOutput.outputPath) }
+			: undefined;
+		const settlementDiagnostic: SettlementDiagnostic | undefined = effectiveExitCode !== 0 || completionGuardTriggered || completionGuardBlocked
+			? {
+				finalTextPresent: Boolean(stripAcceptanceReport(run.finalOutput).trim()),
+				mutation: {
+					expected: mutationExpected,
+					attempted: completionGuard?.attemptedMutation === true || mutationAttemptObserved,
+					observed: mutationEvidence.attemptedMutation,
+				},
+				...(requiredOutput ? { requiredOutput } : {}),
+				afterCompactionSettlement: run.afterCompactionSettlement === true,
+			}
+			: undefined;
+		finalResult = { ...run, exitCode: effectiveExitCode, model: candidate ?? run.model, error, structuredOutput, runtimeAcknowledgedExtensions, ...(step.agentContract ? { agentContract: step.agentContract } : {}), ...(fileMutationEffect || settlementDiagnostic ? { effects: { ...(fileMutationEffect ? { fileMutation: fileMutationEffect } : {}), ...(settlementDiagnostic ? { settlementDiagnostic } : {}) } } : {}) } as RunPiStreamingResult;
 		if (run.turnBudgetExceeded) break modelAttemptsLoop;
 		if (run.stopped || run.timedOut || ctx.timeoutSignal?.aborted || ctx.stopSignal?.aborted || ctx.skipAcceptance?.()) break modelAttemptsLoop;
 		if (attempt.success || completionGuardTriggered) break modelAttemptsLoop;
@@ -1889,7 +2036,7 @@ async function runSingleStepInner(
 			finalResult.finalOutput = startupError;
 			break modelAttemptsLoop;
 		}
-		const retryableModelFailure = isRetryableModelFailure(error);
+		const retryableModelFailure = isRetryableModelFailureAttempt({ error, messages: run.messages, toolCount: run.toolCount });
 		if (retryableModelFailure) recordRetryableModelFailure(candidate ?? run.model ?? step.model, error);
 		if (isContextOverflow(error)) {
 			contextOverflow = true;
@@ -1993,7 +2140,7 @@ async function runSingleStepInner(
 	const acceptanceCanFailRun = acceptanceFailure && effectiveAcceptance?.explicit && (finalResult?.exitCode ?? 1) === 0 && !finalResult?.interrupted && !timedOutAfterAcceptance && !stoppedAfterAcceptance && !turnBudgetExceeded && !isAgentContractV1(step.agentContract);
 	const effectiveFinalExitCode = timedOutAfterAcceptance || stoppedAfterAcceptance || turnBudgetExceeded ? 1 : acceptanceCanFailRun ? 1 : finalResult?.exitCode ?? 1;
 	const intercomDetachReceipt = finalResult?.finalOutput === INTERCOM_DETACH_RECEIPT;
-	const effectiveFinalError = stoppedAfterAcceptance
+	const baseFinalError = stoppedAfterAcceptance
 		? ctx.stopMessage ?? "Subagent stopped by user."
 		: timedOutAfterAcceptance
 			? finalResult?.error ?? ctx.timeoutMessage ?? "Subagent timed out."
@@ -2002,6 +2149,16 @@ async function runSingleStepInner(
 				: acceptanceCanFailRun
 					? (finalResult?.error ? `${finalResult.error}\n${acceptanceFailure}` : acceptanceFailure)
 					: finalResult?.error ?? (intercomDetachReceipt ? INTERCOM_DETACH_RECEIPT : undefined);
+	const effectiveFinalError = formatChildFailureDiagnostic({
+		error: baseFinalError,
+		afterCompactionSettlement: effectiveFinalExitCode !== 0 ? finalResult?.afterCompactionSettlement : undefined,
+		missingFileOnlyOutput: effectiveFinalExitCode !== 0 && finalResult?.effects?.settlementDiagnostic?.requiredOutput?.kind === "file-only" && finalResult.effects.settlementDiagnostic.requiredOutput.missing
+			? finalResult.effects.settlementDiagnostic.requiredOutput.path
+			: undefined,
+		missingStructuredOutput: effectiveFinalExitCode !== 0 && finalResult?.effects?.settlementDiagnostic?.requiredOutput?.kind === "structured" && finalResult.effects.settlementDiagnostic.requiredOutput.missing
+			? finalResult.effects.settlementDiagnostic.requiredOutput.path
+			: undefined,
+	});
 
 	const artifactErrors = artifactPaths && ctx.artifactConfig?.enabled !== false
 		? persistStepArtifacts({
@@ -2098,13 +2255,7 @@ type RunnerStatusStep = NonNullable<AsyncStatus["steps"]>[number] & {
 
 function externalRunnerStatus(runner: SubagentStep["runner"]): ExternalCliRunnerStatus | ExternalJobRunnerStatus | undefined {
 	if (runner?.type === "external-cli") {
-		return {
-			type: "external-cli",
-			command: runner.command,
-			args: runner.args ?? [],
-			promptDelivery: runner.promptDelivery ?? "stdin",
-			capabilities: { stop: true, steer: false, resume: false, structuredOutput: false, toolEvents: false },
-		};
+		return resolveExternalCliRunnerStatus(runner);
 	}
 	if (runner?.type === "external-job") {
 		return {
@@ -2408,6 +2559,7 @@ async function runSubagent(
 					...(transcriptPath ? { transcriptPath } : {}),
 					skills: task.skills,
 					model: task.model,
+					...(task.contextLimit !== undefined ? { contextLimit: task.contextLimit } : {}),
 					thinking: task.thinking,
 					attemptedModels: task.modelCandidates && task.modelCandidates.length > 0 ? task.modelCandidates : task.model ? [task.model] : undefined,
 					recentTools: [],
@@ -2425,6 +2577,7 @@ async function runSubagent(
 				label: step.label ?? step.parallel.label ?? `Dynamic fanout (${step.collect.as})`,
 				outputName: step.collect.as,
 				structured: Boolean(step.collect.outputSchema),
+				...(step.parallel.contextLimit !== undefined ? { contextLimit: step.parallel.contextLimit } : {}),
 				...(step.agentContract ? { agentContract: step.agentContract } : {}),
 				...(step.capabilityCeiling ? { capabilityCeiling: step.capabilityCeiling } : {}),
 				...(step.thinkingCeiling ? { thinkingCeiling: step.thinkingCeiling } : {}),
@@ -2457,6 +2610,7 @@ async function runSubagent(
 				...(transcriptPath ? { transcriptPath } : {}),
 				skills: step.skills,
 				model: step.model,
+				...(step.contextLimit !== undefined ? { contextLimit: step.contextLimit } : {}),
 				thinking: step.thinking,
 				attemptedModels: step.modelCandidates && step.modelCandidates.length > 0 ? step.modelCandidates : step.model ? [step.model] : undefined,
 				recentTools: [],
@@ -3318,11 +3472,12 @@ async function runSubagent(
 		}
 		pendingStepSteers.push(...remaining);
 	};
-	const updateStepModel = (flatIndex: number, model: string | undefined, thinking: string | undefined, now = Date.now()): void => {
+	const updateStepModel = (flatIndex: number, model: string | undefined, thinking: string | undefined, contextLimit?: number, now = Date.now()): void => {
 		const step = statusPayload.steps[flatIndex];
 		if (!step) return;
 		setOptionalProperty(step, "model", model);
 		setOptionalProperty(step, "thinking", thinking);
+		setOptionalProperty(step, "contextLimit", contextLimit);
 		statusPayload.lastUpdate = now;
 		writeStatusPayload();
 	};
@@ -3408,7 +3563,7 @@ async function runSubagent(
 			return;
 		}
 		if (event.type === "tool_execution_start" && event.toolName) {
-			const mutates = isMutatingTool(event.toolName, event.args);
+			const mutates = isMutatingTool(event.toolName, event.args, flatSteps[flatIndex]?.mutationTools);
 			const currentPath = resolveCurrentPath(event.toolName, event.args);
 			const argsPreview = extractToolArgsPreview(event.args ?? {});
 			const blocksSupervisor = isBlockingSupervisorTool(event.toolName, event.args);
@@ -3516,12 +3671,13 @@ async function runSubagent(
 			if (usage) {
 				const input = usage.input ?? usage.inputTokens ?? 0;
 				const output = usage.output ?? usage.outputTokens ?? 0;
+				const window = input + (usage.cacheRead ?? usage.cacheReadTokens ?? 0);
 				const previousInput = step.tokens?.input ?? 0;
 				const previousOutput = step.tokens?.output ?? 0;
-				step.tokens = { input: previousInput + input, output: previousOutput + output, total: previousInput + previousOutput + input + output };
+				step.tokens = { input: previousInput + input, output: previousOutput + output, total: previousInput + previousOutput + input + output, window, windowPeak: Math.max(step.tokens?.windowPeak ?? 0, window) };
 				const totalInput = statusPayload.totalTokens?.input ?? 0;
 				const totalOutput = statusPayload.totalTokens?.output ?? 0;
-				statusPayload.totalTokens = { input: totalInput + input, output: totalOutput + output, total: totalInput + totalOutput + input + output };
+				statusPayload.totalTokens = { input: totalInput + input, output: totalOutput + output, total: totalInput + totalOutput + input + output, window, windowPeak: Math.max(statusPayload.totalTokens?.windowPeak ?? 0, window) };
 				refreshUsageBudget();
 			}
 			statusPayload.turnCount = Math.max(statusPayload.turnCount ?? 0, step.turnCount);
@@ -3952,6 +4108,7 @@ async function runSubagent(
 					...(transcriptPath ? { transcriptPath } : {}),
 					...(task.skills ? { skills: task.skills } : {}),
 					...(task.model ? { model: task.model } : {}),
+					...(task.contextLimit !== undefined ? { contextLimit: task.contextLimit } : {}),
 					...(task.thinking ? { thinking: task.thinking } : {}),
 					...(task.thinkingCeiling ? { thinkingCeiling: task.thinkingCeiling } : {}),
 					...(task.modelCandidates && task.modelCandidates.length > 0 ? { attemptedModels: task.modelCandidates } : task.model ? { attemptedModels: [task.model] } : {}),
@@ -4081,7 +4238,7 @@ async function runSubagent(
 					stopMessage,
 					turnBudget: config.turnBudget,
 					toolTimeoutMs: task.toolTimeoutMs ?? config.toolTimeoutMs,
-					onAttemptStart: (attempt) => updateStepModel(fi, attempt.model, attempt.thinking),
+					onAttemptStart: (attempt) => updateStepModel(fi, attempt.model, attempt.thinking, attempt.contextLimit),
 					onChildEvent: (event) => updateStepFromChildEvent(fi, event),
 					onWriterProcess,
 					onExternalProcess: (process) => updateExternalProcess(fi, process),
@@ -4477,7 +4634,7 @@ async function runSubagent(
 							stopMessage,
 							turnBudget: config.turnBudget,
 							toolTimeoutMs: taskForRun.toolTimeoutMs ?? config.toolTimeoutMs,
-							onAttemptStart: (attempt) => updateStepModel(fi, attempt.model, attempt.thinking),
+							onAttemptStart: (attempt) => updateStepModel(fi, attempt.model, attempt.thinking, attempt.contextLimit),
 							onChildEvent: (event) => updateStepFromChildEvent(fi, event),
 							onWriterProcess,
 							onExternalProcess: (process) => updateExternalProcess(fi, process),
@@ -4580,13 +4737,21 @@ async function runSubagent(
 					const sessionTokens = config.sessionDir
 						? parseSessionTokens(path.join(config.sessionDir, `parallel-${t}`))
 						: null;
-					const taskTokens = sessionTokens ?? tokenUsageFromAttempts(parallelResults[t]?.modelAttempts);
+					const fallbackTokens = tokenUsageFromAttempts(parallelResults[t]?.modelAttempts);
+					const observedTokens = requiredStatusStep(statusPayload, fi).tokens;
+					const taskTokens = sessionTokens ?? (fallbackTokens
+						? { ...fallbackTokens, ...(observedTokens?.window !== undefined ? { window: observedTokens.window } : {}), ...(observedTokens?.windowPeak !== undefined ? { windowPeak: observedTokens.windowPeak } : {}) }
+						: null);
 					if (!taskTokens) continue;
 					requiredStatusStep(statusPayload, fi).tokens = taskTokens;
 					previousCumulativeTokens = {
 						input: previousCumulativeTokens.input + taskTokens.input,
 						output: previousCumulativeTokens.output + taskTokens.output,
 						total: previousCumulativeTokens.total + taskTokens.total,
+						...(taskTokens.window !== undefined ? { window: taskTokens.window } : {}),
+						...(previousCumulativeTokens.windowPeak !== undefined || taskTokens.windowPeak !== undefined
+							? { windowPeak: Math.max(previousCumulativeTokens.windowPeak ?? 0, taskTokens.windowPeak ?? 0) }
+							: {}),
 					};
 				}
 				statusPayload.totalTokens = { ...previousCumulativeTokens };
@@ -4824,7 +4989,7 @@ async function runSubagent(
 				stopMessage,
 				turnBudget: config.turnBudget,
 				toolTimeoutMs: seqStep.toolTimeoutMs ?? config.toolTimeoutMs,
-				onAttemptStart: (attempt) => updateStepModel(flatIndex, attempt.model, attempt.thinking),
+				onAttemptStart: (attempt) => updateStepModel(flatIndex, attempt.model, attempt.thinking, attempt.contextLimit),
 				onChildEvent: (event) => updateStepFromChildEvent(flatIndex, event),
 				onWriterProcess,
 				onExternalProcess: (process) => updateExternalProcess(flatIndex, process),
@@ -4903,17 +5068,27 @@ async function runSubagent(
 						input: cumulativeTokens.input - previousCumulativeTokens.input,
 						output: cumulativeTokens.output - previousCumulativeTokens.output,
 						total: cumulativeTokens.total - previousCumulativeTokens.total,
+						...(cumulativeTokens.window !== undefined ? { window: cumulativeTokens.window } : {}),
+						...(cumulativeTokens.windowPeak !== undefined ? { windowPeak: cumulativeTokens.windowPeak } : {}),
 					}
 				: null;
 			if (cumulativeTokens) {
 				previousCumulativeTokens = cumulativeTokens;
 			} else {
-				stepTokens = tokenUsageFromAttempts(singleResult.modelAttempts);
+				const fallbackTokens = tokenUsageFromAttempts(singleResult.modelAttempts);
+				const observedTokens = requiredStatusStep(statusPayload, flatIndex).tokens;
+				stepTokens = fallbackTokens
+					? { ...fallbackTokens, ...(observedTokens?.window !== undefined ? { window: observedTokens.window } : {}), ...(observedTokens?.windowPeak !== undefined ? { windowPeak: observedTokens.windowPeak } : {}) }
+					: null;
 				if (stepTokens) {
 					previousCumulativeTokens = {
 						input: previousCumulativeTokens.input + stepTokens.input,
 						output: previousCumulativeTokens.output + stepTokens.output,
 						total: previousCumulativeTokens.total + stepTokens.total,
+						...(stepTokens.window !== undefined ? { window: stepTokens.window } : {}),
+						...(previousCumulativeTokens.windowPeak !== undefined || stepTokens.windowPeak !== undefined
+							? { windowPeak: Math.max(previousCumulativeTokens.windowPeak ?? 0, stepTokens.windowPeak ?? 0) }
+							: {}),
 					};
 				}
 			}
@@ -5048,7 +5223,7 @@ async function runSubagent(
 		}
 	}
 
-	let summary = results.map((r) => `${r.agent}:\n${r.output}`).join("\n\n");
+	let summary = results.map((r) => `${r.agent}:\n${r.output || (r.exitCode !== 0 ? r.error : undefined) || "(no output)"}`).join("\n\n");
 	let truncated = false;
 
 	if (maxOutput) {
@@ -5359,7 +5534,7 @@ async function waitForStartupControl(
 			} catch (error) {
 				throw new Error(`Failed to read runner startup control '${controlPath}': ${error instanceof Error ? error.message : String(error)}`);
 			}
-			if (payload.token !== token) throw new Error("Runner startup control token does not match the acquired session lease.");
+			if (payload.token !== token) throw new Error("Runner startup control token does not match.");
 			if (payload.action === action) return;
 			if (payload.action !== "ack" && payload.action !== "proceed") throw new Error("Runner startup control action is invalid.");
 		}
@@ -5370,7 +5545,7 @@ async function waitForStartupControl(
 
 async function runConfiguredSubagent(config: SubagentRunConfig): Promise<void> {
 	let lease: ReturnType<typeof acquireSessionLease> | undefined;
-	let startupCommitted = config.revivalLease === undefined;
+	let startupCommitted = config.revivalLease === undefined && config.launchBarrierToken === undefined;
 	const startupPath = path.join(config.asyncDir, "runner-startup.json");
 	const startupAckPath = path.join(config.asyncDir, "runner-startup-ack.json");
 	const startupProceedPath = path.join(config.asyncDir, "runner-startup-proceed.json");
@@ -5383,7 +5558,15 @@ async function runConfiguredSubagent(config: SubagentRunConfig): Promise<void> {
 	};
 	process.once("exit", releaseOnExit);
 	try {
-		if (config.revivalLease) {
+		if (config.launchBarrierToken) {
+			await waitForStartupControl(startupProceedPath, config.launchBarrierToken, "proceed");
+			startupCommitted = true;
+			try {
+				fs.rmSync(startupProceedPath, { force: true });
+			} catch {
+				// Startup control cleanup is best effort after the parent commits the run.
+			}
+		} else if (config.revivalLease) {
 			lease = acquireSessionLease(config.revivalLease);
 			config.revivalLeaseToken = lease.owner.token;
 			writeAtomicJson(startupPath, { state: "ready", token: lease.owner.token, pid: process.pid, owner: lease.owner });
@@ -5401,7 +5584,7 @@ async function runConfiguredSubagent(config: SubagentRunConfig): Promise<void> {
 		}
 		await runSubagent(config, lease ? (writer) => lease!.updateWriter(writer) : undefined);
 	} catch (error) {
-		if (config.revivalLease && !startupCommitted) {
+		if (!startupCommitted) {
 			try {
 				writeAtomicJson(startupPath, { state: "error", pid: process.pid, error: error instanceof Error ? error.message : String(error) });
 			} catch {