@bastani/atomic 0.8.31-alpha.5 → 0.9.0-alpha.2

package/dist/builtin/subagents/src/runs/foreground/execution-attempt.ts

@@ -0,0 +1,454 @@
+import { spawn } from "node:child_process";
+import { existsSync, unlinkSync } from "node:fs";
+import type { Message } from "@earendil-works/pi-ai";
+import type { AgentConfig } from "../../agents/agents.ts";
+import {
+	type AgentProgress,
+	type RunSyncOptions,
+	type SingleResult,
+	INTERCOM_DETACH_REQUEST_EVENT,
+	INTERCOM_DETACH_RESPONSE_EVENT,
+	getSubagentDepthEnv,
+} from "../../shared/types.ts";
+import { extractTextFromContent, extractToolArgsPreview, getFinalOutput } from "../../shared/utils.ts";
+import { createJsonlWriter } from "../../shared/jsonl-writer.ts";
+import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
+import { applyThinkingSuffix, buildPiArgs, cleanupTempDir } from "../shared/pi-args.ts";
+import { getPiSpawnCommand } from "../shared/pi-spawn.ts";
+import { assistantStopReason, isAssistantFailureStopReason, shouldStartSubagentFinalDrain } from "../shared/final-drain.ts";
+import { modelFailureMessage } from "../shared/model-fallback.ts";
+import {
+	createMutatingFailureState,
+	didMutatingToolFail,
+	isMutatingTool,
+	recordMutatingFailure,
+	resetMutatingFailureState,
+	resolveCurrentPath,
+	shouldEscalateMutatingFailures,
+	summarizeRecentMutatingFailures,
+} from "../shared/long-running-guard.ts";
+import { resolveSubagentModelFastMode } from "../../shared/fast-mode.ts";
+import { appendRecentOutput, emptyUsage, modelFailureSignalByResult, snapshotProgress, snapshotResult } from "./execution-utils.ts";
+import { createAttemptControlRuntime } from "./execution-attempt-control.ts";
+import { finalizeSingleAttempt } from "./execution-attempt-finalize.ts";
+import type { RunSingleAttemptShared } from "./execution-attempt-types.ts";
+
+export async function runSingleAttempt(
+	runtimeCwd: string,
+	agent: AgentConfig,
+	task: string,
+	model: string | undefined,
+	options: RunSyncOptions,
+	shared: RunSingleAttemptShared,
+): Promise<SingleResult> {
+	const modelArg = applyThinkingSuffix(model, agent.thinking);
+	const runCwd = options.cwd ?? runtimeCwd;
+	const fastMode = resolveSubagentModelFastMode({
+		model: modelArg,
+		cwd: runCwd,
+		settings: shared.fastModeSettings,
+		scope: shared.fastModeScope,
+	});
+	const { args, env: sharedEnv, tempDir } = buildPiArgs({
+		baseArgs: ["--mode", "json", "-p"],
+		task,
+		sessionEnabled: shared.sessionEnabled,
+		sessionDir: options.sessionDir,
+		sessionFile: options.sessionFile,
+		model,
+		thinking: agent.thinking,
+		systemPromptMode: agent.systemPromptMode,
+		inheritProjectContext: agent.inheritProjectContext,
+		inheritSkills: agent.inheritSkills,
+		tools: agent.tools,
+		extensions: agent.extensions,
+		systemPrompt: shared.systemPrompt,
+		mcpDirectTools: agent.mcpDirectTools,
+		cwd: runCwd,
+		promptFileStem: agent.name,
+		intercomSessionName: options.intercomSessionName,
+		orchestratorIntercomTarget: options.orchestratorIntercomTarget,
+		runId: options.runId,
+		childAgentName: agent.name,
+		childIndex: options.index ?? 0,
+		parentEventSink: options.nestedRoute?.eventSink,
+		parentControlInbox: options.nestedRoute?.controlInbox,
+		parentRootRunId: options.nestedRoute?.rootRunId,
+		parentCapabilityToken: options.nestedRoute?.capabilityToken,
+		codexFastModeSettings: shared.fastModeSettings,
+		codexFastModeScope: shared.fastModeScope,
+		structuredOutput: options.structuredOutput,
+	});
+
+	const result: SingleResult = {
+		agent: agent.name,
+		task: shared.originalTask ?? task,
+		exitCode: 0,
+		messages: [],
+		usage: emptyUsage(),
+		model: modelArg,
+		...(fastMode ? { fastMode } : {}),
+		artifactPaths: shared.artifactPaths,
+		skills: shared.resolvedSkillNames,
+		skillsWarning: shared.skillsWarning,
+	};
+	const startTime = Date.now();
+	if (options.structuredOutput) {
+		try {
+			if (existsSync(options.structuredOutput.outputPath)) unlinkSync(options.structuredOutput.outputPath);
+		} catch {
+			// Missing/stale structured-output files are handled after the child exits.
+		}
+	}
+	let interruptedByControl = false;
+	const progress: AgentProgress = {
+		index: options.index ?? 0,
+		agent: agent.name,
+		status: "running",
+		task,
+		skills: shared.resolvedSkillNames,
+		recentTools: [],
+		recentOutput: [...shared.attemptNotes],
+		toolCount: 0,
+		tokens: 0,
+		durationMs: 0,
+		lastActivityAt: startTime,
+	};
+	result.progress = progress;
+	const controlRuntime = createAttemptControlRuntime({ options, agent, result, progress, startTime });
+	const spawnEnv = {
+		...process.env,
+		...sharedEnv,
+		...getSubagentDepthEnv(options.maxSubagentDepth, {
+			workflowStageSubagentGuard: options.workflowStageSubagentGuard,
+		}),
+	};
+	const exitCode = await new Promise<number>((resolve) => {
+		const spawnSpec = getPiSpawnCommand(args);
+		const proc = spawn(spawnSpec.command, spawnSpec.args, {
+			cwd: runCwd,
+			env: spawnEnv,
+			stdio: ["ignore", "pipe", "pipe"],
+			windowsHide: true,
+		});
+		const jsonlWriter = createJsonlWriter(shared.jsonlPath, proc.stdout);
+		let buf = "";
+		let processClosed = false;
+		let settled = false;
+		let detached = false;
+		let intercomStarted = false;
+		let assistantError: string | undefined;
+		let assistantFailureSignal: unknown;
+		let removeAbortListener: (() => void) | undefined;
+		let removeInterruptListener: (() => void) | undefined;
+		let activityTimer: NodeJS.Timeout | undefined;
+
+		const detachForIntercom = () => {
+			detached = true;
+			processClosed = true;
+			result.detached = true;
+			result.detachedReason = "intercom coordination";
+			progress.status = "detached";
+			progress.durationMs = Date.now() - startTime;
+			result.progressSummary = { toolCount: progress.toolCount, tokens: progress.tokens, durationMs: progress.durationMs };
+			finish(-2);
+		};
+
+		const FINAL_STOP_GRACE_MS = 1000;
+		const HARD_KILL_MS = 3000;
+		let childExited = false;
+		let forcedTerminationSignal = false;
+		let cleanTerminalAssistantStopReceived = false;
+		let finalDrainTimer: NodeJS.Timeout | undefined;
+		let finalHardKillTimer: NodeJS.Timeout | undefined;
+		const clearFinalDrainTimers = () => {
+			if (finalDrainTimer) {
+				clearTimeout(finalDrainTimer);
+				finalDrainTimer = undefined;
+			}
+			if (finalHardKillTimer) {
+				clearTimeout(finalHardKillTimer);
+				finalHardKillTimer = undefined;
+			}
+		};
+		const startFinalDrain = () => {
+			if (childExited || finalDrainTimer || settled || processClosed || detached) return;
+			finalDrainTimer = setTimeout(() => {
+				if (settled || processClosed || detached) return;
+				const termSent = trySignalChild(proc, "SIGTERM");
+				if (!termSent) return;
+				forcedTerminationSignal = true;
+				if (!cleanTerminalAssistantStopReceived && !assistantError) {
+					result.error = result.error ?? `Subagent process did not exit within ${FINAL_STOP_GRACE_MS}ms after its final message. Forcing termination.`;
+				}
+				finalHardKillTimer = setTimeout(() => {
+					if (settled || processClosed || detached) return;
+					forcedTerminationSignal = trySignalChild(proc, "SIGKILL") || forcedTerminationSignal;
+				}, HARD_KILL_MS);
+				finalHardKillTimer.unref?.();
+			}, FINAL_STOP_GRACE_MS);
+			finalDrainTimer.unref?.();
+		};
+
+		const unsubscribeIntercomDetach = options.intercomEvents?.on?.(INTERCOM_DETACH_REQUEST_EVENT, (payload) => {
+			if (!options.allowIntercomDetach || detached || processClosed || !intercomStarted) return;
+			if (!payload || typeof payload !== "object") return;
+			const requestId = (payload as { requestId?: unknown }).requestId;
+			if (typeof requestId !== "string" || requestId.length === 0) return;
+			options.intercomEvents?.emit(INTERCOM_DETACH_RESPONSE_EVENT, { requestId, accepted: true });
+			detachForIntercom();
+		});
+
+		const finish = (code: number) => {
+			if (settled) return;
+			settled = true;
+			clearFinalDrainTimers();
+			clearStdioGuard();
+			if (activityTimer) {
+				clearInterval(activityTimer);
+				activityTimer = undefined;
+			}
+			unsubscribeIntercomDetach?.();
+			removeAbortListener?.();
+			removeInterruptListener?.();
+			resolve(code);
+		};
+
+		let pendingToolResult: { tool: string; path?: string; mutates: boolean; startedAt?: number } | undefined;
+		const mutatingFailures = createMutatingFailureState();
+		const mutatingFailureWindowMs = 5 * 60_000;
+		const emitUpdateSnapshot = (text: string) => {
+			if (!options.onUpdate || processClosed) return;
+			const progressSnapshot = snapshotProgress(progress);
+			const resultSnapshot = snapshotResult(result, progressSnapshot);
+			options.onUpdate({
+				content: [{ type: "text", text }],
+				details: {
+					mode: "single",
+					results: [resultSnapshot],
+					progress: [progressSnapshot],
+					controlEvents: controlRuntime.drainPendingControlEvents(),
+				},
+			});
+		};
+		const fireUpdate = () => {
+			if (!options.onUpdate || processClosed) return;
+			progress.durationMs = Date.now() - startTime;
+			emitUpdateSnapshot(getFinalOutput(result.messages ?? []) || "(running...)");
+		};
+
+		const processLine = (line: string) => {
+			if (!line.trim()) return;
+			jsonlWriter.writeLine(line);
+			let evt: { type?: string; message?: Message; toolName?: string; args?: unknown };
+			try {
+				evt = JSON.parse(line) as { type?: string; message?: Message; toolName?: string; args?: unknown };
+			} catch {
+				return;
+			}
+
+			const now = Date.now();
+			progress.durationMs = now - startTime;
+			progress.lastActivityAt = now;
+			controlRuntime.updateActivityState(now);
+
+			if (evt.type === "tool_execution_start") {
+				const toolArgs = evt.args && typeof evt.args === "object" && !Array.isArray(evt.args) ? evt.args as Record<string, unknown> : {};
+				if (options.allowIntercomDetach && (evt.toolName === "intercom" || evt.toolName === "contact_supervisor")) intercomStarted = true;
+				progress.toolCount++;
+				progress.currentTool = evt.toolName;
+				progress.currentToolArgs = extractToolArgsPreview(toolArgs);
+				progress.currentToolStartedAt = now;
+				progress.currentPath = resolveCurrentPath(evt.toolName, toolArgs);
+				pendingToolResult = { tool: evt.toolName ?? "tool", path: progress.currentPath, mutates: isMutatingTool(evt.toolName, toolArgs), startedAt: now };
+				fireUpdate();
+			}
+
+			if (evt.type === "tool_execution_end") {
+				if (progress.currentTool) {
+					progress.recentTools.push({ tool: progress.currentTool, args: progress.currentToolArgs || "", endMs: now });
+				}
+				progress.currentTool = undefined;
+				progress.currentToolArgs = undefined;
+				progress.currentToolStartedAt = undefined;
+				progress.currentPath = undefined;
+				fireUpdate();
+			}
+
+			if (evt.type === "message_end" && evt.message) {
+				result.messages?.push(evt.message);
+				if (evt.message.role === "assistant") {
+					result.usage.turns++;
+					progress.turnCount = result.usage.turns;
+					const u = evt.message.usage;
+					if (u) {
+						result.usage.input += u.input || 0;
+						result.usage.output += u.output || 0;
+						result.usage.cacheRead += u.cacheRead || 0;
+						result.usage.cacheWrite += u.cacheWrite || 0;
+						result.usage.cost += u.cost?.total || 0;
+						progress.tokens = result.usage.input + result.usage.output;
+					}
+					if (!result.model && evt.message.model) result.model = evt.message.model;
+					const assistantText = extractTextFromContent(evt.message.content);
+					appendRecentOutput(progress, assistantText.split("\n").slice(-10));
+					const stopReason = assistantStopReason(evt.message);
+					if (evt.message.errorMessage) {
+						assistantError = evt.message.errorMessage;
+						assistantFailureSignal = evt.message;
+					}
+					if (isAssistantFailureStopReason(stopReason)) {
+						assistantError = modelFailureMessage(evt.message);
+						assistantFailureSignal = evt.message;
+					}
+					if (shouldStartSubagentFinalDrain(evt.message)) {
+						if (assistantText.trim()) {
+							assistantError = undefined;
+							assistantFailureSignal = undefined;
+						}
+						cleanTerminalAssistantStopReceived = true;
+						startFinalDrain();
+					}
+				}
+				controlRuntime.updateActivityState(now);
+				fireUpdate();
+			}
+
+			if (evt.type === "tool_result_end" && evt.message) {
+				result.messages?.push(evt.message);
+				const resultText = extractTextFromContent(evt.message.content);
+				appendRecentOutput(progress, resultText.split("\n").slice(-10));
+				const toolSnapshot = pendingToolResult;
+				pendingToolResult = undefined;
+				if (toolSnapshot?.mutates && didMutatingToolFail(resultText)) {
+					recordMutatingFailure(mutatingFailures, {
+						tool: toolSnapshot.tool,
+						path: toolSnapshot.path,
+						error: resultText.split("\n").find((row) => row.trim())?.trim().slice(0, 180) ?? "mutating tool failed",
+						ts: now,
+					}, mutatingFailureWindowMs);
+					if (shouldEscalateMutatingFailures(mutatingFailures, controlRuntime.config.failedToolAttemptsBeforeAttention)) {
+						controlRuntime.emitNeedsAttention(now, {
+							message: `${agent.name} needs attention after repeated mutating tool failures`,
+							reason: "tool_failures",
+							currentTool: toolSnapshot.tool,
+							currentPath: toolSnapshot.path,
+							currentToolDurationMs: toolSnapshot.startedAt ? Math.max(0, now - toolSnapshot.startedAt) : undefined,
+							recentFailureSummary: summarizeRecentMutatingFailures(mutatingFailures),
+						});
+					}
+				} else if (toolSnapshot?.mutates) {
+					resetMutatingFailureState(mutatingFailures);
+				}
+				fireUpdate();
+			}
+		};
+
+		if (controlRuntime.config.enabled) {
+			activityTimer = setInterval(() => {
+				if (processClosed || settled || detached) return;
+				const now = Date.now();
+				if (controlRuntime.updateActivityState(now)) {
+					progress.durationMs = now - startTime;
+					fireUpdate();
+				}
+			}, 1000);
+			activityTimer.unref?.();
+		}
+
+		let stderrBuf = "";
+		const clearStdioGuard = attachPostExitStdioGuard(proc, { idleMs: 2000, hardMs: 8000 });
+		proc.stdout.on("data", (d) => {
+			buf += d.toString();
+			const lines = buf.split("\n");
+			buf = lines.pop() || "";
+			lines.forEach(processLine);
+		});
+		proc.stderr.on("data", (d) => {
+			stderrBuf += d.toString();
+		});
+		proc.on("exit", () => {
+			childExited = true;
+			clearFinalDrainTimers();
+		});
+		proc.on("close", (code, signal) => {
+			clearFinalDrainTimers();
+			clearStdioGuard();
+			void jsonlWriter.close().catch(() => undefined);
+			cleanupTempDir(tempDir);
+			if (detached) {
+				finish(-2);
+				return;
+			}
+			processClosed = true;
+			if (buf.trim()) processLine(buf);
+			if (!result.error && assistantError) result.error = assistantError;
+			if (assistantFailureSignal !== undefined && result.error === assistantError) {
+				modelFailureSignalByResult.set(result, assistantFailureSignal);
+			}
+			const forcedDrainAfterFinalSuccess = forcedTerminationSignal && cleanTerminalAssistantStopReceived && !result.error;
+			if (code !== 0 && stderrBuf.trim() && !result.error && !forcedDrainAfterFinalSuccess) result.error = stderrBuf.trim();
+			const finalCode = forcedDrainAfterFinalSuccess ? 0 : forcedTerminationSignal || signal ? (code ?? 1) : (code ?? 0);
+			finish(finalCode);
+		});
+		proc.on("error", (error) => {
+			clearFinalDrainTimers();
+			clearStdioGuard();
+			void jsonlWriter.close().catch(() => undefined);
+			cleanupTempDir(tempDir);
+			if (!result.error) result.error = error instanceof Error ? error.message : String(error);
+			finish(1);
+		});
+
+		if (options.signal) {
+			const kill = () => {
+				if (processClosed || detached) return;
+				if (options.allowIntercomDetach && intercomStarted) {
+					detachForIntercom();
+					return;
+				}
+				proc.kill("SIGTERM");
+				setTimeout(() => !proc.killed && proc.kill("SIGKILL"), 3000);
+			};
+			if (options.signal.aborted) kill();
+			else {
+				options.signal.addEventListener("abort", kill, { once: true });
+				removeAbortListener = () => options.signal?.removeEventListener("abort", kill);
+			}
+		}
+
+		if (options.interruptSignal) {
+			const interrupt = () => {
+				if (processClosed || detached || settled) return;
+				interruptedByControl = true;
+				progress.status = "running";
+				progress.durationMs = Date.now() - startTime;
+				result.interrupted = true;
+				result.finalOutput = "Interrupted. Waiting for explicit next action.";
+				progress.activityState = undefined;
+				fireUpdate();
+				trySignalChild(proc, "SIGINT");
+				setTimeout(() => {
+					if (settled || processClosed || detached) return;
+					trySignalChild(proc, "SIGTERM");
+				}, 1000).unref?.();
+			};
+			if (options.interruptSignal.aborted) interrupt();
+			else {
+				options.interruptSignal.addEventListener("abort", interrupt, { once: true });
+				removeInterruptListener = () => options.interruptSignal?.removeEventListener("abort", interrupt);
+			}
+		}
+	});
+
+	return finalizeSingleAttempt({
+		result,
+		progress,
+		exitCode,
+		interruptedByControl,
+		allControlEvents: controlRuntime.allControlEvents,
+		options,
+		shared,
+		startTime,
+	});
+}

package/dist/builtin/subagents/src/runs/foreground/execution-run-sync.ts

@@ -0,0 +1,219 @@
+import { existsSync } from "node:fs";
+import type { AgentConfig } from "../../agents/agents.ts";
+import { buildSkillInjection, resolveSkillsWithFallback } from "../../agents/skills.ts";
+import { ensureArtifactsDir, getArtifactPaths, writeArtifact, writeMetadata } from "../../shared/artifacts.ts";
+import { getSubagentCodexFastModeSettings, resolveSubagentCodexFastModeScope } from "../../shared/fast-mode.ts";
+import { resolveEffectiveThinking } from "../../shared/model-info.ts";
+import {
+	DEFAULT_MAX_OUTPUT,
+	type ArtifactPaths,
+	type ModelAttempt,
+	type RunSyncOptions,
+	type SingleResult,
+	truncateOutput,
+} from "../../shared/types.ts";
+import { findLatestSessionFile } from "../../shared/utils.ts";
+import { applyThinkingSuffix } from "../shared/pi-args.ts";
+import { captureSingleOutputSnapshot, validateFileOnlyOutputMode } from "../shared/single-output.ts";
+import {
+	buildModelCandidates,
+	formatModelAttemptNote,
+	isRetryableModelFailure,
+} from "../shared/model-fallback.ts";
+import { artifactOutputByResult, emptyUsage, modelFailureSignalByResult, sumUsage } from "./execution-utils.ts";
+import { runSingleAttemptWithStructuredOutputRetries } from "./execution-structured-retries.ts";
+import { shouldSuppressIntermediateRetryableFailureUpdate } from "./execution-updates.ts";
+
+/**
+ * Run a subagent synchronously (blocking until complete)
+ */
+export async function runSync(
+	runtimeCwd: string,
+	agents: AgentConfig[],
+	agentName: string,
+	task: string,
+	options: RunSyncOptions,
+): Promise<SingleResult> {
+	const agent = agents.find((a) => a.name === agentName);
+	if (!agent) {
+		return { agent: agentName, task, exitCode: 1, messages: [], usage: emptyUsage(), error: `Unknown agent: ${agentName}` };
+	}
+	const outputModeValidationError = validateFileOnlyOutputMode(options.outputMode, options.outputPath, `Single run (${agentName})`);
+	if (outputModeValidationError) {
+		return {
+			agent: agentName,
+			task,
+			exitCode: 1,
+			messages: [],
+			usage: emptyUsage(),
+			outputMode: options.outputMode,
+			error: outputModeValidationError,
+		};
+	}
+
+	const shareEnabled = options.share === true;
+	const sessionEnabled = Boolean(options.sessionFile || options.sessionDir) || shareEnabled;
+	const skillNames = options.skills ?? agent.skills ?? [];
+	const skillCwd = options.cwd ?? runtimeCwd;
+	const { resolved: resolvedSkills, missing: missingSkills } = resolveSkillsWithFallback(skillNames, skillCwd, runtimeCwd);
+	if (skillNames.some((skill) => skill.trim() === "subagent") && missingSkills.includes("subagent")) {
+		return { agent: agentName, task, exitCode: 1, messages: [], usage: emptyUsage(), error: "Skills not found: subagent" };
+	}
+	let systemPrompt = agent.systemPrompt?.trim() || "";
+	if (resolvedSkills.length > 0) {
+		const skillInjection = buildSkillInjection(resolvedSkills);
+		systemPrompt = systemPrompt ? `${systemPrompt}\n\n${skillInjection}` : skillInjection;
+	}
+
+	const candidates = buildModelCandidates(
+		options.modelOverride ?? agent.model,
+		agent.fallbackModels,
+		options.availableModels,
+		options.preferredModelProvider,
+		options.currentModel,
+		agent.fallbackThinkingLevels,
+	);
+	const fastModeCwd = options.cwd ?? runtimeCwd;
+	const fastModeSettings = getSubagentCodexFastModeSettings(fastModeCwd);
+	const fastModeScope = resolveSubagentCodexFastModeScope(options.workflowStageSubagentGuard);
+	const attemptedModels: string[] = [];
+	const modelAttempts: ModelAttempt[] = [];
+	const aggregateUsage = emptyUsage();
+	const attemptNotes: string[] = [];
+	const pendingAttemptNotes: string[] = [];
+	let totalToolCount = 0;
+	let totalDurationMs = 0;
+
+	let artifactPathsResult: ArtifactPaths | undefined;
+	let jsonlPath: string | undefined;
+	if (options.artifactsDir && options.artifactConfig?.enabled !== false) {
+		artifactPathsResult = getArtifactPaths(options.artifactsDir, options.runId, agentName, options.index);
+		ensureArtifactsDir(options.artifactsDir);
+		if (options.artifactConfig?.includeInput !== false) {
+			writeArtifact(artifactPathsResult.inputPath, `# Task for ${agentName}\n\n${task}`);
+		}
+		if (options.artifactConfig?.includeJsonl !== false) jsonlPath = artifactPathsResult.jsonlPath;
+	}
+
+	let lastResult: SingleResult | undefined;
+	const modelsToTry = candidates.length > 0 ? candidates : [undefined];
+	for (let i = 0; i < modelsToTry.length; i++) {
+		const candidate = modelsToTry[i];
+		if (candidate) attemptedModels.push(candidate);
+		const outputSnapshot = captureSingleOutputSnapshot(options.outputPath);
+		let attemptOptions = options;
+		if (i < modelsToTry.length - 1 && options.onUpdate) {
+			const forwardUpdate = options.onUpdate;
+			attemptOptions = {
+				...options,
+				onUpdate: (update) => {
+					if (shouldSuppressIntermediateRetryableFailureUpdate(update)) return;
+					forwardUpdate(update);
+				},
+			};
+		}
+		const result = await runSingleAttemptWithStructuredOutputRetries(runtimeCwd, agent, task, candidate, attemptOptions, {
+			sessionEnabled,
+			systemPrompt,
+			resolvedSkillNames: resolvedSkills.length > 0 ? resolvedSkills.map((skill) => skill.name) : undefined,
+			skillsWarning: missingSkills.length > 0 ? `Skills not found: ${missingSkills.join(", ")}` : undefined,
+			jsonlPath,
+			artifactPaths: artifactPathsResult,
+			attemptNotes,
+			outputSnapshot,
+			fastModeSettings,
+			fastModeScope,
+			originalTask: task,
+		});
+		lastResult = result;
+		sumUsage(aggregateUsage, result.usage);
+		totalToolCount += result.progressSummary?.toolCount ?? 0;
+		totalDurationMs += result.progressSummary?.durationMs ?? 0;
+		const attemptSucceeded = result.exitCode === 0 && !result.error;
+		const attemptModel = applyThinkingSuffix(candidate, agent.thinking) ?? result.model ?? agent.model ?? "default";
+		const attempt: ModelAttempt = {
+			model: attemptModel,
+			reasoningLevel: resolveEffectiveThinking(attemptModel, agent.thinking),
+			success: attemptSucceeded,
+			exitCode: result.exitCode,
+			error: result.error,
+			usage: { ...result.usage },
+		};
+		modelAttempts.push(attempt);
+		if (attemptSucceeded) break;
+		const retrySignal = modelFailureSignalByResult.get(result) ?? result.error;
+		if (isRetryableModelFailure(retrySignal) && i < modelsToTry.length - 1) {
+			pendingAttemptNotes.push(formatModelAttemptNote(attempt, modelsToTry[i + 1]));
+			continue;
+		}
+		attemptNotes.push(...pendingAttemptNotes);
+		break;
+	}
+
+	const result = lastResult ?? {
+		agent: agentName,
+		task,
+		exitCode: 1,
+		messages: [],
+		usage: emptyUsage(),
+		error: "Subagent did not produce a result.",
+	} satisfies SingleResult;
+
+	result.usage = aggregateUsage;
+	result.attemptedModels = attemptedModels.length > 0 ? attemptedModels : undefined;
+	result.modelAttempts = modelAttempts.length > 0 ? modelAttempts : undefined;
+	result.progressSummary = {
+		toolCount: totalToolCount,
+		tokens: aggregateUsage.input + aggregateUsage.output,
+		durationMs: totalDurationMs,
+	};
+	if (attemptNotes.length > 0 && result.progress) {
+		result.progress.recentOutput = [...attemptNotes, ...result.progress.recentOutput];
+		if (result.progress.recentOutput.length > 50) result.progress.recentOutput.splice(50);
+	}
+
+	if (artifactPathsResult && options.artifactConfig?.enabled !== false) {
+		result.artifactPaths = artifactPathsResult;
+		if (options.artifactConfig?.includeOutput !== false) {
+			writeArtifact(artifactPathsResult.outputPath, artifactOutputByResult.get(result) ?? result.finalOutput ?? "");
+		}
+		if (options.artifactConfig?.includeMetadata !== false) {
+			writeMetadata(artifactPathsResult.metadataPath, {
+				runId: options.runId,
+				agent: agentName,
+				task,
+				exitCode: result.exitCode,
+				usage: result.usage,
+				model: result.model,
+				fastMode: result.fastMode,
+				attemptedModels: result.attemptedModels,
+				modelAttempts: result.modelAttempts,
+				durationMs: result.progressSummary?.durationMs,
+				toolCount: result.progressSummary?.toolCount,
+				error: result.error,
+				skills: result.skills,
+				skillsWarning: result.skillsWarning,
+				timestamp: Date.now(),
+			});
+		}
+
+		if (options.maxOutput) {
+			const config = { ...DEFAULT_MAX_OUTPUT, ...options.maxOutput };
+			const truncationResult = truncateOutput(result.finalOutput ?? "", config, artifactPathsResult.outputPath);
+			if (truncationResult.truncated) result.truncation = truncationResult;
+		}
+	} else if (options.maxOutput) {
+		const config = { ...DEFAULT_MAX_OUTPUT, ...options.maxOutput };
+		const truncationResult = truncateOutput(result.finalOutput ?? "", config);
+		if (truncationResult.truncated) result.truncation = truncationResult;
+	}
+
+	if (options.sessionFile && (existsSync(options.sessionFile) || result.messages?.length)) {
+		result.sessionFile = options.sessionFile;
+	} else if (shareEnabled && options.sessionDir) {
+		const sessionFile = findLatestSessionFile(options.sessionDir);
+		if (sessionFile) result.sessionFile = sessionFile;
+	}
+
+	return result;
+}