@bastani/atomic 0.9.12 → 0.9.13-alpha.2

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

@@ -1,23 +1,40 @@
 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,
+	getCurrentSubagentDepth,
+	isWorkflowStageOrchestrationContext,
+	resolveChildMaxSubagentDepth,
+	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.js";
+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,9 +42,96 @@ 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),
+		// The child's own effective limit, recorded when the run was retained. An
+		// older record without one falls back to narrowing the current limit by the
+		// agent definition, so a resume never widens a child's delegation budget.
+		maxSubagentDepth:
+			child.maxSubagentDepth ??
+			resolveChildMaxSubagentDepth(
+				resolveWorkflowStageMaxSubagentDepth(ctx, deps.config.maxSubagentDepth),
+				agentConfig.maxSubagentDepth,
+			),
+		parentDepth: getCurrentSubagentDepth(ctx),
+		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"]);
+/**
+ * Management actions that only observe. Every other action either mutates agent
+ * definitions or starts/continues agent execution, so a child without fanout
+ * authorization is refused all of them.
+ */
+const READ_ONLY_MANAGEMENT_ACTIONS = new Set(["list", "get", "status", "doctor"]);
+const FANOUT_REFUSAL_MESSAGE = "Subagent fanout is not authorized for this child.";
 
 export type { SubagentExecutorRuntimeDeps, SubagentParamsLike } from "./subagent-executor-types.ts";
 
@@ -47,6 +151,30 @@ async function handleManagementRequest(input: {
 			details: { mode: "management", results: [] },
 		};
 	}
+	if (!(SUBAGENT_ACTIONS as readonly string[]).includes(action)) {
+		return {
+			content: [{ type: "text", text: `Unknown action: ${action}. Valid: ${SUBAGENT_ACTIONS.join(", ")}` }],
+			isError: true,
+			details: { mode: "management" as const, results: [] },
+		};
+	}
+	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,
+			details: { mode: "management" as const, results: [] },
+		};
+	}
+	// `resume` revives a child and `interrupt` is privileged control over a
+	// running one; both continue agent execution, so only the observing actions
+	// reach their handlers for a child without fanout authorization.
+	if (deps.childPolicy && !deps.childPolicy.fanoutAuthorized && !READ_ONLY_MANAGEMENT_ACTIONS.has(action)) {
+		return {
+			content: [{ type: "text", text: FANOUT_REFUSAL_MESSAGE }],
+			isError: true,
+			details: { mode: "management" as const, results: [] },
+		};
+	}
 	if (action === "doctor") {
 		let currentSessionFile: string | null = null;
 		let currentSessionId = deps.state.currentSessionId;
@@ -84,112 +212,68 @@ 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) },
-		);
-	}
-	if (action === "resume") {
-		return resumeAsyncRun({ params: paramsWithResolvedCwd, requestCwd, ctx, deps });
-	}
-	if (action === "interrupt") {
-		return handleInterruptRequest({ paramsWithResolvedCwd, deps });
-	}
-	if (!(SUBAGENT_ACTIONS as readonly string[]).includes(action)) {
 		return {
-			content: [{ type: "text", text: `Unknown action: ${action}. Valid: ${SUBAGENT_ACTIONS.join(", ")}` }],
-			isError: true,
-			details: { mode: "management" as const, results: [] },
-		};
-	}
-	if (deps.allowMutatingManagementActions === false && MUTATING_MANAGEMENT_ACTIONS.has(action)) {
-		return {
-			content: [{ type: "text", text: `Action '${action}' is not available from child-safe subagent fanout mode.` }],
+			content: [
+				{
+					type: "text",
+					text: targetRunId ? `No in-process child found for '${targetRunId}'.` : "No in-process subagent found.",
+				},
+			],
 			isError: true,
-			details: { mode: "management" as const, results: [] },
+			details: { mode: "management", results: [] },
 		};
 	}
-	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);
+	if (action === "resume") {
+		const targetRunId = paramsWithResolvedCwd.runId ?? paramsWithResolvedCwd.id;
+		const message = paramsWithResolvedCwd.message ?? paramsWithResolvedCwd.task;
+		if (!targetRunId || !message) {
 			return {
-				content: [{ type: "text", text: message }],
+				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 (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: [] },
-			};
+	if (action === "interrupt") {
+		const targetRunId = paramsWithResolvedCwd.runId ?? paramsWithResolvedCwd.id;
+		if (targetRunId) {
+			const inProcess = await interruptInProcessChild(targetRunId);
+			if (inProcess) return inProcess;
 		}
 		return {
-			content: [{ type: "text", text: `Foreground run ${foreground.runId} has no active child step to interrupt.` }],
+			content: [
+				{
+					type: "text",
+					text: targetRunId
+						? `No running in-process child found for '${targetRunId}'.`
+						: "No interrupt-capable child found.",
+				},
+			],
 			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: [] },
-	};
+	return handleManagementAction(action, paramsWithResolvedCwd, { ...ctx, cwd: requestCwd });
 }
 
-function inferExecutionMode(params: SubagentParamsLike): "single" | "parallel" | "chain" {
-	if ((params.chain?.length ?? 0) > 0) return "chain";
+function inferExecutionMode(params: SubagentParamsLike): "single" | "parallel" {
 	if ((params.tasks?.length ?? 0) > 0) return "parallel";
 	return "single";
 }
@@ -233,6 +317,17 @@ export function createSubagentExecutor(rawDeps: ExecutorDeps): {
 		if (params.action) {
 			return handleManagementRequest({ params, paramsWithResolvedCwd, requestCwd, ctx, deps });
 		}
+		// Fanout authorization gates delegation and every management action that can
+		// start or continue agent execution. Only `list`, `get`, `status`, and
+		// `doctor` stay available to an unauthorized child; `resume`, `interrupt`,
+		// and mutating management are refused inside handleManagementRequest.
+		if (deps.childPolicy && !deps.childPolicy.fanoutAuthorized) {
+			return {
+				content: [{ type: "text", text: FANOUT_REFUSAL_MESSAGE }],
+				isError: true,
+				details: { mode: inferExecutionMode(params), results: [] },
+			};
+		}
 
 		const depthError = checkDepthForExecution(ctx, deps);
 		if (depthError) return depthError;
@@ -248,11 +343,6 @@ export function createSubagentExecutor(rawDeps: ExecutorDeps): {
 				prepared.writeNestedForegroundEvent("subagent.nested.started");
 				nestedForegroundStarted = true;
 			}
-			if (prepared.hasChain && prepared.effectiveParams.chain) {
-				const result = await runChainPath(prepared.execData, deps);
-				prepared.writeNestedForegroundEvent("subagent.nested.completed", result);
-				return withForkContext(result, prepared.effectiveParams.context);
-			}
 			if (prepared.hasTasks && prepared.effectiveParams.tasks) {
 				const result = await runParallelPath(prepared.execData, deps);
 				prepared.writeNestedForegroundEvent("subagent.nested.completed", result);

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

@@ -0,0 +1,195 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isStaleExtensionContextError } from "@bastani/atomic";
+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.js";
+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,
+		parentDepth,
+		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),
+		parentDepth,
+		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)";
+			try {
+				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,
+				});
+			} catch (error) {
+				if (!isStaleExtensionContextError(error)) throw error;
+				// A detached child may finish after its parent extension runtime reloads.
+			}
+		},
+	});
+
+	try {
+		ctx.pi.events.emit(SUBAGENT_ASYNC_STARTED_EVENT, {
+			id,
+			asyncDir,
+			sessionId: result.path,
+			mode: "single",
+			agent,
+			agents: [agent],
+			...(result.model !== undefined ? { model: result.model } : {}),
+			...(result.thinking !== undefined ? { thinking: result.thinking } : {}),
+			...(result.fastMode ? { fastMode: true } : {}),
+		});
+	} catch (error) {
+		if (!isStaleExtensionContextError(error)) throw error;
+		// The launch result remains useful when the captured runtime is stale.
+	}
+	return {
+		content: [{ type: "text", text: formatAsyncStartedMessage(`Async: ${agent} [${id}]`) }],
+		details: { mode: "single", runId: id, results: [result], asyncId: id, asyncDir },
+		...(result.status === "error" ? { isError: true } : {}),
+	};
+}

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

@@ -0,0 +1,90 @@
+import type { ExtensionAPI, SessionWorkflowMetadata } from "@bastani/atomic";
+import type { AgentConfig } from "../../agents/agents.ts";
+import type { SupervisorAuthorization } from "../../intercom/supervisor-authorization.ts";
+import type { ModelInfo } from "../../shared/model-info.ts";
+import type { RunSyncOptions } from "../../shared/types.ts";
+
+export interface AsyncExecutionContext {
+	pi: ExtensionAPI;
+	cwd: string;
+	currentSessionId: string;
+	currentModelProvider?: string;
+	currentModel?: string;
+	intercomGroup?: string;
+	workflowSessionMetadata?: SessionWorkflowMetadata;
+}
+
+export interface AsyncSingleParams {
+	agent: string;
+	task?: string;
+	group?: string | true;
+	agentConfig: AgentConfig;
+	ctx: AsyncExecutionContext;
+	cwd?: string;
+	maxOutput?: { bytes?: number; lines?: number };
+	artifactsDir?: string;
+	artifactConfig: {
+		enabled: boolean;
+		includeInput: boolean;
+		includeOutput: boolean;
+		includeJsonl: boolean;
+		includeMetadata: boolean;
+		cleanupDays: number;
+	};
+	shareEnabled: boolean;
+	sessionRoot?: string;
+	sessionFile?: string;
+	skills?: string[];
+	output?: string | boolean;
+	outputMode?: "inline" | "file-only";
+	progress?: boolean;
+	modelOverride?: string;
+	availableModels?: ModelInfo[];
+	knownModelProviders?: string[];
+	maxSubagentDepth: number;
+	parentDepth?: number;
+	workflowStageSubagentGuard?: boolean;
+	worktreeSetupHook?: string;
+	worktreeSetupHookTimeoutMs?: number;
+	controlConfig?: import("../../shared/types.ts").ResolvedControlConfig;
+	controlIntercomTarget?: string;
+	childIntercomTarget?: (agent: string, index: number) => string | undefined;
+	supervisorAuthorization?: SupervisorAuthorization;
+	nestedRoute?: import("../../shared/types.ts").NestedRouteInfo;
+	/** Internal seam used by focused runtime tests. */
+	testSession?: RunSyncOptions["testSession"];
+}
+
+export interface AsyncExecutionResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: import("../../shared/types.ts").Details;
+	isError?: boolean;
+}
+
+export function formatAsyncStartedMessage(headline: string): string {
+	return [
+		`Launched: ${headline}`,
+		"Completion pending; Atomic will deliver the result when the in-process child finishes.",
+		"",
+		"The async child is tied to the current parent process and does not survive parent exit.",
+		'Use subagent({ action: "status", id: "..." }) when you need the current status/result.',
+	].join("\n");
+}
+
+/** Async execution is always available because it no longer depends on a jiti child process. */
+export function isAsyncAvailable(): boolean {
+	return true;
+}
+
+export function formatAsyncStartError(mode: "single" | "parallel", message: string): AsyncExecutionResult {
+	return {
+		content: [{ type: "text", text: message }],
+		isError: true,
+		details: { mode, results: [] },
+	};
+}
+
+export const UNAVAILABLE_SUBAGENT_SKILL_ERROR = "Skills not found: subagent";
+
+export class UnavailableSubagentSkillError extends Error {}
+export class AsyncStartValidationError extends Error {}

package/dist/builtin/subagents/src/runs/inprocess/child-policy.ts

@@ -0,0 +1,27 @@
+import type { SubagentChildPolicy } from "@bastani/atomic";
+
+export type ChildModePolicy = SubagentChildPolicy;
+
+/**
+ * Resolve the child-mode capabilities at the in-process admission door.
+ *
+ * Every admitted child is management-restricted. Fanout is granted only when
+ * the admitted tool allowlist explicitly includes the subagent tool; an
+ * omitted allowlist cannot widen a descendant's capabilities.
+ */
+export function resolveChildModePolicy(spec: {
+	readonly tools?: readonly string[];
+	readonly agent: {
+		readonly tools?: readonly string[];
+		readonly inheritProjectContext: boolean;
+		readonly inheritSkills: boolean;
+	};
+}): ChildModePolicy {
+	const tools = spec.tools ?? spec.agent.tools;
+	return {
+		managementActions: "restricted",
+		fanoutAuthorized: tools?.includes("subagent") === true,
+		inheritProjectContext: spec.agent.inheritProjectContext,
+		inheritSkills: spec.agent.inheritSkills,
+	};
+}