@bastani/atomic 0.9.12 → 0.9.13-alpha.1

package/dist/builtin/subagents/src/runs/foreground/subagent-executor-single.ts

@@ -19,9 +19,9 @@ import {
 	wrapForkTask,
 } from "../../shared/types.ts";
 import { compactForegroundDetails, getSingleResultOutput } from "../../shared/utils.ts";
+import { updateForegroundNestedProjection } from "../inprocess/runtime-support/nested-api.ts";
 import { inheritedIntercomGroup, resolveChildIntercomGroup } from "../shared/intercom-group.ts";
 import { currentModelFullId, resolveModelCandidate } from "../shared/model-fallback.ts";
-import { updateForegroundNestedProjection } from "../shared/nested-events.ts";
 import { recordRun } from "../shared/run-history.ts";
 import {
 	finalizeSingleOutput,
@@ -238,7 +238,7 @@ export async function runSinglePath(
 		foregroundControl.toolCount = r.progress?.toolCount;
 		foregroundControl.updatedAt = Date.now();
 	}
-	recordRun(params.agent!, cleanTask, r.exitCode, r.progressSummary?.durationMs ?? 0);
+	recordRun(params.agent!, cleanTask, r.status, r.progressSummary?.durationMs ?? 0);
 
 	if (r.progress) allProgress.push(r.progress);
 	if (r.artifactPaths) allArtifactPaths.push(r.artifactPaths);
@@ -249,7 +249,7 @@ export async function runSinglePath(
 		truncatedOutput: r.truncation?.text,
 		outputPath,
 		outputMode: r.outputMode,
-		exitCode: r.exitCode,
+		status: r.status,
 		savedPath: r.savedOutputPath,
 		outputReference: r.outputReference,
 		saveError: r.outputSaveError,
@@ -278,7 +278,7 @@ export async function runSinglePath(
 			return {
 				content: [{ type: "text", text: intercomReceipt.text }],
 				details: intercomReceipt.details,
-				...(r.exitCode !== 0 ? { isError: true } : {}),
+				...(r.status === "error" ? { isError: true } : {}),
 			};
 		}
 	}
@@ -304,7 +304,7 @@ export async function runSinglePath(
 		};
 	}
 
-	if (r.exitCode !== 0)
+	if (r.status === "error")
 		return {
 			content: [{ type: "text", text: formatFailedSingleRunOutput(r, finalizedOutput.displayOutput) }],
 			details,

package/dist/builtin/subagents/src/runs/foreground/subagent-executor-status.ts

@@ -21,8 +21,8 @@ import {
 } from "../../shared/types.ts";
 import { compactForegroundDetails, compactForegroundResult, getSingleResultOutput } from "../../shared/utils.ts";
 import { deliverLocalCompletionNotification } from "../background/completion-notification.ts";
-import { updateForegroundNestedProjection } from "../shared/nested-events.ts";
-import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
+import { updateForegroundNestedProjection } from "../inprocess/runtime-support/nested-api.ts";
+import { formatNestedRunStatusLines } from "../inprocess/runtime-support/nested-rendering.ts";
 import {
 	formatControlIntercomMessage,
 	formatControlNoticeMessage,
@@ -141,7 +141,7 @@ export function rememberForegroundRun(
 				agent: result.agent,
 				index,
 				status: resolveSubagentResultStatus({
-					exitCode: result.exitCode,
+					status: result.status,
 					interrupted: result.interrupted,
 					detached: result.detached,
 				}),
@@ -192,7 +192,7 @@ export function replaceForegroundRunChild(
 	const child = run.children.find((entry) => entry.index === index);
 	if (child?.status !== "detached") return;
 	child.status = resolveSubagentResultStatus({
-		exitCode: retainedResult.exitCode,
+		status: retainedResult.status,
 		interrupted: retainedResult.interrupted,
 		detached: retainedResult.detached,
 	});
@@ -249,7 +249,7 @@ export function createForegroundControlNotifier(
 
 function resultSummaryForIntercom(result: SingleResult): string {
 	const output = getSingleResultOutput(result);
-	if (result.exitCode !== 0 && result.error) {
+	if (result.status === "error" && result.error) {
 		return output ? `${result.error}\n\nOutput:\n${output}` : result.error;
 	}
 	return output || result.error || "(no output)";
@@ -278,9 +278,8 @@ export function notifyDetachedForegroundChildExit(input: {
 			id: runId,
 			runId,
 			agent: result.agent,
-			success: result.exitCode === 0 && !result.interrupted && !result.error,
+			status: result.status,
 			summary: resultSummaryForIntercom(result),
-			exitCode: result.exitCode,
 			...(result.interrupted ? { state: "paused" } : {}),
 			timestamp: Date.now(),
 			...(result.progressSummary?.durationMs !== undefined ? { durationMs: result.progressSummary.durationMs } : {}),
@@ -311,7 +310,7 @@ async function emitForegroundResultIntercom(input: {
 					{
 						agent: result.agent,
 						status: resolveSubagentResultStatus({
-							exitCode: result.exitCode,
+							status: result.status,
 							interrupted: result.interrupted,
 							detached: result.detached,
 						}),

package/dist/builtin/subagents/src/runs/foreground/subagent-executor-types.ts

@@ -14,11 +14,12 @@ import type {
 	SubagentToolResult,
 } from "../../shared/types.ts";
 import type {
-	executeAsyncChain,
-	executeAsyncSingle,
+	AsyncExecutionResult,
+	AsyncSingleParams,
 	formatAsyncStartedMessage,
 	isAsyncAvailable,
-} from "../background/async-execution.ts";
+} from "../inprocess/background.ts";
+import type { ChildModePolicy } from "../inprocess/child-policy.ts";
 import type { runSync } from "./execution.ts";
 
 export interface TaskParam {
@@ -72,8 +73,7 @@ export interface SubagentParamsLike {
 
 export interface SubagentExecutorRuntimeDeps {
 	runSync: typeof runSync;
-	executeAsyncChain: typeof executeAsyncChain;
-	executeAsyncSingle: typeof executeAsyncSingle;
+	executeAsyncSingle: (id: string, params: AsyncSingleParams) => AsyncExecutionResult | Promise<AsyncExecutionResult>;
 	isAsyncAvailable: typeof isAsyncAvailable;
 	formatAsyncStartedMessage: typeof formatAsyncStartedMessage;
 }
@@ -88,9 +88,18 @@ export interface ExecutorDeps {
 	expandTilde: (p: string) => string;
 	discoverAgents: (cwd: string, scope: AgentScope) => { agents: AgentConfig[] };
 	allowMutatingManagementActions?: boolean;
+	/** Typed admission policy; when present it is authoritative over the legacy boolean. */
+	childPolicy?: ChildModePolicy;
 	runtime?: Partial<SubagentExecutorRuntimeDeps>;
 }
 
+export function isManagementActionsRestricted(
+	deps: Pick<ExecutorDeps, "childPolicy" | "allowMutatingManagementActions">,
+): boolean {
+	return deps.childPolicy
+		? deps.childPolicy.managementActions === "restricted"
+		: deps.allowMutatingManagementActions === false;
+}
 export interface ResolvedExecutorDeps extends Omit<ExecutorDeps, "runtime"> {
 	runtime: SubagentExecutorRuntimeDeps;
 }

package/dist/builtin/subagents/src/runs/foreground/subagent-executor.ts

@@ -1,23 +1,39 @@
 import type { ExtensionContext } from "@bastani/atomic";
 import { handleManagementAction } from "../../agents/agent-management.ts";
+import { resolveExecutionAgentScope } from "../../agents/agent-scope.ts";
 import { clearPendingForegroundControlNotices } from "../../extension/control-notices.ts";
 import { buildDoctorReport } from "../../extension/doctor.ts";
-import { resolveIntercomSessionTarget } from "../../intercom/intercom-bridge.ts";
-import { SUBAGENT_ACTIONS, type SubagentToolResult } from "../../shared/types.ts";
-import { type ResolvedSubagentRunId, resolveSubagentRunId } from "../background/run-id-resolver.ts";
-import { inspectSubagentStatus } from "../background/run-status.ts";
+import {
+	resolveIntercomBridge,
+	resolveIntercomSessionTarget,
+	resolveSubagentIntercomTarget,
+} from "../../intercom/intercom-bridge.ts";
+import { requestSupervisorAuthorization } from "../../intercom/supervisor-authorization.ts";
+import { getArtifactsDir } from "../../shared/artifacts.ts";
+import { toModelInfo } from "../../shared/model-info.ts";
+import { resolveSingleProgress } from "../../shared/settings.ts";
+import {
+	DEFAULT_ARTIFACT_CONFIG,
+	isWorkflowStageOrchestrationContext,
+	resolveWorkflowStageMaxSubagentDepth,
+	SUBAGENT_ACTIONS,
+	type SubagentToolResult,
+	workflowSessionMetadataFromContext,
+} from "../../shared/types.ts";
+import {
+	inspectInProcessChildStatus,
+	interruptInProcessChild,
+	resumeInProcessChild,
+} from "../inprocess/control-status.ts";
+import { inheritedIntercomGroup } from "../shared/intercom-group.ts";
+import { currentModelFullId } from "../shared/model-fallback.ts";
+import { resolveControlConfig } from "../shared/subagent-control.ts";
 import { runAsyncPath } from "./subagent-executor-async.ts";
 import { runChainPath } from "./subagent-executor-chain.ts";
 import { checkDepthForExecution, prepareExecutionContext } from "./subagent-executor-context.ts";
 import { toExecutionErrorResult, withForkContext } from "./subagent-executor-input.ts";
 import { runParallelPath } from "./subagent-executor-parallel.ts";
-import {
-	interruptAsyncRun,
-	interruptNestedRun,
-	nestedResolutionScopeForExecutor,
-	resolveRequestedCwd,
-	resumeAsyncRun,
-} from "./subagent-executor-resume.ts";
+import { resolveRequestedCwd } from "./subagent-executor-resume.ts";
 import { resolveSubagentExecutorRuntimeDeps } from "./subagent-executor-runtime.ts";
 import { runSinglePath } from "./subagent-executor-single.ts";
 import {
@@ -25,8 +41,79 @@ import {
 	getForegroundControl,
 	retainedForegroundStatusResult,
 } from "./subagent-executor-status.ts";
-import type { ExecutorDeps, ResolvedExecutorDeps, SubagentParamsLike } from "./subagent-executor-types.ts";
+import {
+	type ExecutorDeps,
+	isManagementActionsRestricted,
+	type ResolvedExecutorDeps,
+	type SubagentParamsLike,
+} from "./subagent-executor-types.ts";
 
+async function resumeRetainedForegroundChild(
+	params: SubagentParamsLike,
+	message: string,
+	ctx: ExtensionContext,
+	deps: ResolvedExecutorDeps,
+): Promise<SubagentToolResult | undefined> {
+	const requested = params.id ?? params.runId;
+	if (!requested) return undefined;
+	const run = deps.state.foregroundRuns?.get(requested);
+	if (!run) return undefined;
+	const child = run.children[params.index ?? 0];
+	if (!child) return undefined;
+	const agents = deps.discoverAgents(run.cwd, resolveExecutionAgentScope(params.agentScope)).agents;
+	const agentConfig = agents.find((agent) => agent.name === child.agent);
+	if (!agentConfig) {
+		return {
+			content: [{ type: "text", text: `Unknown agent for resume: ${child.agent}` }],
+			isError: true,
+			details: { mode: "single", results: [] },
+		};
+	}
+	const parentSessionFile = ctx.sessionManager.getSessionFile() ?? null;
+	const sessionName = resolveIntercomSessionTarget(deps.pi.getSessionName(), ctx.sessionManager.getSessionId());
+	const intercomBridge = resolveIntercomBridge({
+		config: deps.config.intercomBridge,
+		context: params.context,
+		orchestratorTarget: sessionName,
+		cwd: run.cwd,
+	});
+	const supervisedTarget = intercomBridge.active
+		? resolveSubagentIntercomTarget(run.runId, child.agent, child.index)
+		: undefined;
+	const supervisorAuthorization = await requestSupervisorAuthorization(deps.pi.events, supervisedTarget);
+	return deps.runtime.executeAsyncSingle(run.runId, {
+		agent: child.agent,
+		agentConfig,
+		task: message,
+		ctx: {
+			pi: deps.pi,
+			cwd: run.cwd,
+			currentSessionId: ctx.sessionManager.getSessionId(),
+			currentModelProvider: ctx.model?.provider,
+			currentModel: currentModelFullId(ctx.model),
+			intercomGroup: inheritedIntercomGroup(ctx),
+			workflowSessionMetadata: workflowSessionMetadataFromContext(ctx),
+		},
+		cwd: run.cwd,
+		maxOutput: params.maxOutput,
+		artifactsDir: getArtifactsDir(parentSessionFile),
+		artifactConfig: { ...DEFAULT_ARTIFACT_CONFIG, enabled: params.artifacts !== false },
+		shareEnabled: params.share === true,
+		sessionRoot: deps.getSubagentSessionRoot(parentSessionFile),
+		sessionFile: child.sessionFile,
+		progress: resolveSingleProgress(agentConfig, params.progress, message),
+		modelOverride: params.model,
+		availableModels: ctx.modelRegistry.getAvailable().map(toModelInfo),
+		maxSubagentDepth: resolveWorkflowStageMaxSubagentDepth(ctx, deps.config.maxSubagentDepth),
+		workflowStageSubagentGuard: isWorkflowStageOrchestrationContext(ctx),
+		controlConfig: resolveControlConfig(deps.config.control, params.control),
+		controlIntercomTarget: intercomBridge.active ? intercomBridge.orchestratorTarget : undefined,
+		childIntercomTarget: intercomBridge.active
+			? (agent, index) => resolveSubagentIntercomTarget(run.runId, agent, index)
+			: undefined,
+		supervisorAuthorization,
+	});
+}
 const MUTATING_MANAGEMENT_ACTIONS = new Set(["create", "update", "delete"]);
 
 export type { SubagentExecutorRuntimeDeps, SubagentParamsLike } from "./subagent-executor-types.ts";
@@ -84,43 +171,63 @@ async function handleManagementRequest(input: {
 	}
 	if (action === "status") {
 		const targetRunId = paramsWithResolvedCwd.id ?? paramsWithResolvedCwd.runId;
+		const inProcess = inspectInProcessChildStatus(targetRunId);
+		if (inProcess) return inProcess;
+		const foreground = getForegroundControl(deps.state, targetRunId);
+		if (foreground) return foregroundStatusResult(foreground);
 		if (targetRunId) {
-			try {
-				const nestedScope = nestedResolutionScopeForExecutor(deps);
-				const resolved = resolveSubagentRunId(targetRunId, { state: deps.state, nested: nestedScope });
-				if (resolved?.kind === "foreground") {
-					const foreground = getForegroundControl(deps.state, resolved.id);
-					if (foreground) return foregroundStatusResult(foreground);
-					const retained = retainedForegroundStatusResult(deps.state, resolved.id);
-					if (retained) return retained;
-				}
-			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
-				return {
-					content: [{ type: "text", text: message }],
-					isError: true,
-					details: { mode: "management", results: [] },
-				};
-			}
-		} else {
-			const foreground = getForegroundControl(deps.state, undefined);
-			if (foreground) return foregroundStatusResult(foreground);
+			const retained = retainedForegroundStatusResult(deps.state, targetRunId);
+			if (retained) return retained;
 		}
-		return inspectSubagentStatus(
-			{
-				action: "status",
-				id: paramsWithResolvedCwd.id,
-				runId: paramsWithResolvedCwd.runId,
-				dir: paramsWithResolvedCwd.dir,
-			},
-			{ state: deps.state, nested: nestedResolutionScopeForExecutor(deps) },
-		);
+		return {
+			content: [
+				{
+					type: "text",
+					text: targetRunId ? `No in-process child found for '${targetRunId}'.` : "No in-process subagent found.",
+				},
+			],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
 	}
 	if (action === "resume") {
-		return resumeAsyncRun({ params: paramsWithResolvedCwd, requestCwd, ctx, deps });
+		const targetRunId = paramsWithResolvedCwd.runId ?? paramsWithResolvedCwd.id;
+		const message = paramsWithResolvedCwd.message ?? paramsWithResolvedCwd.task;
+		if (!targetRunId || !message) {
+			return {
+				content: [{ type: "text", text: "action='resume' requires id/runId and message." }],
+				isError: true,
+				details: { mode: "management", results: [] },
+			};
+		}
+		const inProcess = await resumeInProcessChild(targetRunId, message, { model: ctx.model });
+		if (inProcess) return inProcess;
+		const retained = await resumeRetainedForegroundChild(paramsWithResolvedCwd, message, ctx, deps);
+		if (retained) return retained;
+		return {
+			content: [{ type: "text", text: `No in-process child found for '${targetRunId}'.` }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
 	}
 	if (action === "interrupt") {
-		return handleInterruptRequest({ paramsWithResolvedCwd, deps });
+		const targetRunId = paramsWithResolvedCwd.runId ?? paramsWithResolvedCwd.id;
+		if (targetRunId) {
+			const inProcess = await interruptInProcessChild(targetRunId);
+			if (inProcess) return inProcess;
+		}
+		return {
+			content: [
+				{
+					type: "text",
+					text: targetRunId
+						? `No running in-process child found for '${targetRunId}'.`
+						: "No interrupt-capable child found.",
+				},
+			],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
 	}
 	if (!(SUBAGENT_ACTIONS as readonly string[]).includes(action)) {
 		return {
@@ -129,7 +236,7 @@ async function handleManagementRequest(input: {
 			details: { mode: "management" as const, results: [] },
 		};
 	}
-	if (deps.allowMutatingManagementActions === false && MUTATING_MANAGEMENT_ACTIONS.has(action)) {
+	if (isManagementActionsRestricted(deps) && MUTATING_MANAGEMENT_ACTIONS.has(action)) {
 		return {
 			content: [{ type: "text", text: `Action '${action}' is not available from child-safe subagent fanout mode.` }],
 			isError: true,
@@ -139,55 +246,6 @@ async function handleManagementRequest(input: {
 	return handleManagementAction(action, paramsWithResolvedCwd, { ...ctx, cwd: requestCwd });
 }
 
-async function handleInterruptRequest(input: {
-	paramsWithResolvedCwd: SubagentParamsLike;
-	deps: ResolvedExecutorDeps;
-}): Promise<SubagentToolResult> {
-	const { paramsWithResolvedCwd, deps } = input;
-	const targetRunId = paramsWithResolvedCwd.runId ?? paramsWithResolvedCwd.id;
-	let resolved: ResolvedSubagentRunId | undefined;
-	if (targetRunId) {
-		try {
-			resolved = resolveSubagentRunId(targetRunId, {
-				state: deps.state,
-				nested: nestedResolutionScopeForExecutor(deps),
-			});
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			return {
-				content: [{ type: "text", text: message }],
-				isError: true,
-				details: { mode: "management", results: [] },
-			};
-		}
-	}
-	if (resolved?.kind === "nested") return interruptNestedRun(resolved);
-	const foreground = getForegroundControl(deps.state, resolved?.kind === "foreground" ? resolved.id : targetRunId);
-	if (foreground?.interrupt) {
-		const interrupted = foreground.interrupt();
-		if (interrupted) {
-			foreground.updatedAt = Date.now();
-			foreground.currentActivityState = undefined;
-			return {
-				content: [{ type: "text", text: `Interrupt requested for foreground run ${foreground.runId}.` }],
-				details: { mode: "management", results: [] },
-			};
-		}
-		return {
-			content: [{ type: "text", text: `Foreground run ${foreground.runId} has no active child step to interrupt.` }],
-			isError: true,
-			details: { mode: "management", results: [] },
-		};
-	}
-	const asyncInterruptResult = interruptAsyncRun(deps.state, resolved?.kind === "async" ? resolved.id : targetRunId);
-	if (asyncInterruptResult) return asyncInterruptResult;
-	return {
-		content: [{ type: "text", text: "No interrupt-capable run found in this session." }],
-		isError: true,
-		details: { mode: "management", results: [] },
-	};
-}
-
 function inferExecutionMode(params: SubagentParamsLike): "single" | "parallel" | "chain" {
 	if ((params.chain?.length ?? 0) > 0) return "chain";
 	if ((params.tasks?.length ?? 0) > 0) return "parallel";
@@ -224,6 +282,13 @@ export function createSubagentExecutor(rawDeps: ExecutorDeps): {
 		onUpdate: ((r: SubagentToolResult) => void) | undefined,
 		ctx: ExtensionContext,
 	): Promise<SubagentToolResult> => {
+		if (deps.childPolicy && !deps.childPolicy.fanoutAuthorized) {
+			return {
+				content: [{ type: "text", text: "Subagent fanout is not authorized for this child." }],
+				isError: true,
+				details: { mode: "single", results: [] },
+			};
+		}
 		deps.state.baseCwd = ctx.cwd;
 		deps.state.foregroundRuns ??= new Map();
 		deps.state.foregroundControls ??= new Map();

package/dist/builtin/subagents/src/runs/inprocess/background-single.ts

@@ -0,0 +1,179 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { buildSkillInjection, resolveSkillsWithFallback } from "../../agents/skills.ts";
+import { injectSingleProgressInstruction, writeInitialProgressFile } from "../../shared/settings.ts";
+import {
+	ASYNC_DIR,
+	resolveChildMaxSubagentDepth,
+	SUBAGENT_ASYNC_COMPLETE_EVENT,
+	SUBAGENT_ASYNC_STARTED_EVENT,
+} from "../../shared/types.ts";
+import { resolveChildCwd } from "../../shared/utils.ts";
+import { runSingleInProcess } from "../foreground/inprocess-run-sync.ts";
+import { resolveChildIntercomGroup } from "../shared/intercom-group.ts";
+import { filterSpawnableModelCandidates } from "../shared/model-candidate-filter.ts";
+import { buildModelCandidates } from "../shared/model-fallback.ts";
+import {
+	injectSingleOutputInstruction,
+	normalizeSingleOutputOverride,
+	resolveSingleOutputPath,
+	validateFileOnlyOutputMode,
+} from "../shared/single-output.ts";
+import {
+	type AsyncExecutionResult,
+	type AsyncSingleParams,
+	formatAsyncStartError,
+	formatAsyncStartedMessage,
+	UNAVAILABLE_SUBAGENT_SKILL_ERROR,
+} from "./background.ts";
+
+/**
+ * Execute a single agent asynchronously using the in-process runner.
+ *
+ * The returned promise resolves after admission and continuation, not after the
+ * model attempt. Terminal delivery happens through the existing detached-exit
+ * callback and in-memory result path.
+ */
+export async function executeAsyncSingle(id: string, params: AsyncSingleParams): Promise<AsyncExecutionResult> {
+	const {
+		agent,
+		agentConfig,
+		ctx,
+		cwd,
+		maxOutput,
+		artifactsDir,
+		artifactConfig,
+		sessionRoot,
+		sessionFile,
+		maxSubagentDepth,
+		workflowStageSubagentGuard,
+		controlConfig,
+		controlIntercomTarget,
+		childIntercomTarget,
+	} = params;
+	const task = params.task ?? "";
+	const runnerCwd = resolveChildCwd(ctx.cwd, cwd);
+	const skillNames = params.skills ?? agentConfig.skills ?? [];
+	const { resolved: resolvedSkills, missing: missingSkills } = resolveSkillsWithFallback(
+		skillNames,
+		runnerCwd,
+		ctx.cwd,
+	);
+	if (missingSkills.includes("subagent")) return formatAsyncStartError("single", UNAVAILABLE_SUBAGENT_SKILL_ERROR);
+
+	let systemPrompt = agentConfig.systemPrompt?.trim() ?? "";
+	if (resolvedSkills.length > 0) {
+		const injection = buildSkillInjection(resolvedSkills);
+		systemPrompt = systemPrompt ? `${systemPrompt}\n\n${injection}` : injection;
+	}
+
+	const asyncDir = path.join(ASYNC_DIR, id);
+	try {
+		fs.mkdirSync(asyncDir, { recursive: true });
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return formatAsyncStartError("single", `Failed to create async run directory '${asyncDir}': ${message}`);
+	}
+
+	const effectiveOutput = normalizeSingleOutputOverride(params.output, agentConfig.output);
+	const outputPath = resolveSingleOutputPath(effectiveOutput, ctx.cwd, runnerCwd);
+	const outputMode = params.outputMode ?? "inline";
+	const validationError = validateFileOnlyOutputMode(outputMode, outputPath, `Async single run (${agent})`);
+	if (validationError) return formatAsyncStartError("single", validationError);
+	let taskWithOutputInstruction = injectSingleOutputInstruction(task, outputPath);
+	if (params.progress) {
+		const progressDir =
+			artifactConfig.enabled && artifactsDir
+				? path.join(artifactsDir, "progress", id)
+				: path.join(asyncDir, "progress");
+		writeInitialProgressFile(progressDir);
+		taskWithOutputInstruction = injectSingleProgressInstruction(taskWithOutputInstruction, progressDir);
+	}
+
+	const availableModels = params.availableModels;
+	const knownModelProviders = params.knownModelProviders;
+	const rawModelCandidates = buildModelCandidates(
+		params.modelOverride ?? agentConfig.model,
+		agentConfig.fallbackModels,
+		availableModels,
+		ctx.currentModelProvider,
+		ctx.currentModel,
+		agentConfig.fallbackThinkingLevels,
+	);
+	const filteredCandidates = filterSpawnableModelCandidates({
+		candidates: rawModelCandidates,
+		availableModels,
+		knownModelProviders,
+		currentModel: ctx.currentModel,
+	});
+	if (rawModelCandidates.length > 0 && filteredCandidates.candidates.length === 0) {
+		return formatAsyncStartError("single", "No spawnable subagent model candidates after pre-spawn filtering.");
+	}
+
+	const childAgent = { ...agentConfig, systemPrompt };
+	const result = await runSingleInProcess(runnerCwd, childAgent, taskWithOutputInstruction, {
+		cwd: runnerCwd,
+		runId: id,
+		sessionDir: path.join(sessionRoot ?? asyncDir, "session"),
+		sessionFile,
+		artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
+		artifactConfig,
+		maxOutput,
+		outputPath,
+		outputMode,
+		backgroundContinuation: true,
+		maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, agentConfig.maxSubagentDepth),
+		workflowStageSubagentGuard,
+		workflowSessionMetadata: ctx.workflowSessionMetadata,
+		controlConfig,
+		supervisorAuthorization: params.supervisorAuthorization,
+		intercomSessionName: childIntercomTarget?.(agent, 0),
+		orchestratorIntercomTarget: controlIntercomTarget,
+		intercomGroup: resolveChildIntercomGroup(params.group, ctx.intercomGroup, undefined),
+		modelOverride: filteredCandidates.candidates[0] ?? params.modelOverride ?? agentConfig.model,
+		availableModels,
+		knownModelProviders,
+		preferredModelProvider: ctx.currentModelProvider,
+		currentModel: ctx.currentModel,
+		skills: resolvedSkills.map((skill) => skill.name),
+		testSession: params.testSession,
+		onDetachedExit: (completed) => {
+			const envelope = completed.envelope?.trim() ? completed.envelope : "(no output)";
+			ctx.pi.events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, {
+				id,
+				runId: id,
+				asyncDir,
+				agent,
+				status: completed.status,
+				summary: envelope,
+				envelope,
+				timestamp: Date.now(),
+				sessionFile: completed.sessionFile,
+				results: [
+					{
+						agent,
+						output: envelope,
+						status: completed.status,
+						index: 0,
+						intercomTarget: childIntercomTarget?.(agent, 0),
+					},
+				],
+				result: completed,
+			});
+		},
+	});
+
+	ctx.pi.events.emit(SUBAGENT_ASYNC_STARTED_EVENT, {
+		id,
+		asyncDir,
+		sessionId: result.path,
+		mode: "single",
+		agent,
+		agents: [agent],
+	});
+	return {
+		content: [{ type: "text", text: formatAsyncStartedMessage(`Async: ${agent} [${id}]`) }],
+		details: { mode: "single", runId: id, results: [result], asyncId: id, asyncDir },
+		...(result.status === "error" ? { isError: true } : {}),
+	};
+}