@fitchmultz/pi-subagents 0.44.7 → 0.46.0

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

@@ -1,501 +1,203 @@
-import { randomUUID } from "node:crypto";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { resolveExecutionAgentScope } from "../../agents/agent-scope.ts";
-import { handleManagementAction } from "../../agents/agent-management.ts";
-import { buildDoctorReport } from "../../extension/doctor.ts";
-import { providerQualifiedModelId, toModelInfo, type ModelInfo } from "../../shared/model-info.ts";
-import { resolveModelCandidate } from "../shared/model-fallback.ts";
-import { getArtifactsDir } from "../../shared/artifacts.ts";
-import {
-	collectInvocationAgentNames,
-	isParallelStep,
-	isDynamicParallelStep,
-} from "../../shared/settings.ts";
-import {
-	buildFlatAgentNameResolver,
-	createPerAgentForkContextResolver,
-	invocationUsesForkContext,
-	resolveAgentContext,
-	validateForkContextModelPolicy,
-} from "../../shared/agent-context-policy.ts";
-import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
 import { resolveExecutionCwd } from "../../shared/execution-cwd.ts";
-import { resolveIntercomBridge, resolveIntercomSessionTarget, resolveOrchestratorIntercomTarget } from "../../intercom/intercom-bridge.ts";
-import { resolveControlConfig } from "../shared/subagent-control.ts";
-import { createNestedRoute, resolveInheritedNestedRouteFromEnv } from "../shared/nested-events.ts";
-import { resolveSubagentRunId, type ResolvedSubagentRunId } from "../background/run-id-resolver.ts";
-import { inspectSubagentStatus } from "../background/run-status.ts";
-import { applyForceTopLevelAsyncOverride } from "../background/top-level-async.ts";
-import { queryLiveIntercomHealth, queryLiveIntercomStatus } from "../../intercom/live-intercom.ts";
-import { saveQuestionOwner } from "../shared/supervisor-questions.ts";
-import { buildWorkflowGraphSnapshot, workflowAgentNodes } from "../shared/workflow-graph.ts";
-import { ownedRunList, ownedRunStatusResult, ownedRunView, rememberOwnedRun, resolveOwnedRun, workflowChildren } from "../shared/run-records.ts";
-import { ownedHistoryQuery } from "../shared/run-history-queries.ts";
-import { cancelSupervisorInput, controlSupervisorQuestion, projectSupervisorQuestions } from "./question-control.ts";
-import {
-	type AgentScope,
-} from "../../agents/agents.ts";
-import {
-	type SubagentExecutionResult,
-	SUBAGENT_ACTIONS,
-	checkSubagentDepth,
-} from "../../shared/types.ts";
-import {
-	type ExecutionContextData,
-	type ExecutorDeps,
-	type SubagentParamsLike,
-	resolveAsyncExecutionMode,
-} from "./subagent-params.ts";
-import {
-	MUTATING_MANAGEMENT_ACTIONS,
-	extendAsyncTimeoutResult,
-	interruptAsyncRun,
-	interruptNestedRun,
-	nestedResolutionScopeForExecutor,
-	nudgeSubagentRun,
-	rememberedForegroundStatusResult,
-	resolveRememberedForegroundRun,
-	resolveRequestedCwd,
-	resumeAsyncRun,
-} from "./foreground-control.ts";
-import {
-	buildRequestedModeError,
-	normalizeRepeatedParallelCounts,
-	normalizeRoleForegroundTimeout,
-	resolveForegroundTimeoutMs,
-	toExecutionErrorResult,
-	validateExecutionInput,
-	withForkContext,
-} from "./execution-input.ts";
-import { runAsyncPath } from "./run-async-path.ts";
-import { clarifyInvocation } from "./clarify-invocation.ts";
+import { errorMessage } from "../../shared/unknown.ts";
+import { ownedRunStatusResult, resolveOwnedRun } from "../shared/run-records.ts";
+import type { SubagentExecutionResult } from "../../shared/types.ts";
+import type { ExecutorDeps, SubagentParamsLike } from "./subagent-params.ts";
+import { nestedResolutionScopeForExecutor, resolveRequestedCwd } from "./execution-routing.ts";
+import { cancelSupervisorInput, projectSupervisorQuestions } from "./question-control.ts";
 import { waitForOwnedRun } from "./wait-run.ts";
+import { ManagementActions } from "./management-actions.ts";
+import { InvocationExecution, type ExecutionInvocation } from "./invocation-execution.ts";
 
 export type { SubagentParamsLike } from "./subagent-params.ts";
 export { normalizeSubagentParamsLike, resolveAsyncExecutionMode } from "./subagent-params.ts";
 export { writeAsyncInterruptRequest } from "./foreground-control.ts";
 
-type ExecuteSubagent = (id: string, params: SubagentParamsLike, signal: AbortSignal | undefined,
-	onUpdate: ((r: SubagentExecutionResult) => void) | undefined, ctx: ExtensionContext, executionCwd?: string) => Promise<SubagentExecutionResult>;
-
-export function createSubagentExecutor(deps: ExecutorDeps): {
-	execute: ExecuteSubagent;
-} {
-	const execute = async (
-		_id: string,
-		params: SubagentParamsLike,
-		signal: AbortSignal | undefined,
-		onUpdate: ((r: SubagentExecutionResult) => void) | undefined,
-		ctx: ExtensionContext,
-		executionCwd?: string,
-	): Promise<SubagentExecutionResult> => {
-		const needsExecutionCwd = !params.action || params.cwd !== undefined || ["list", "get", "create", "update", "delete", "doctor"].includes(params.action);
-		const invocationCwd = needsExecutionCwd ? executionCwd ?? resolveExecutionCwd(deps.pi, ctx) : ctx.cwd;
-		await deps.ensureSessionState?.(ctx);
-		if (needsExecutionCwd) deps.state.baseCwd = invocationCwd;
-		deps.state.foregroundRuns ??= new Map();
-		const requestCwd = resolveRequestedCwd(invocationCwd, params.cwd);
-		const paramsWithResolvedCwd = params.cwd === undefined ? params : { ...params, cwd: requestCwd };
-		if (params.action) {
-			if (params.action === "review") {
-				try {
-					if (!(params.id ?? params.runId) || (params.decision !== "accepted" && params.decision !== "needs_changes")) throw new Error("action='review' requires id and decision ('accepted' or 'needs_changes').");
-					const run = resolveOwnedRun(deps.state, (params.id ?? params.runId)!);
-					if (!run) throw new Error("Run not found in this parent session.");
-					if (ownedRunView(run, deps.state).state === "live") throw new Error("The run is still live. Use nudge for guidance, or stop it before reviewing its result.");
-					const reviewed = { ...run, review: { decision: params.decision, ...(params.message ? { message: params.message } : {}), reviewedAt: Date.now() } };
-					rememberOwnedRun(deps.state, reviewed);
-					const result = ownedRunStatusResult(reviewed, deps.state, undefined, { childSafe: Boolean(nestedResolutionScopeForExecutor(deps)) });
-					return { ...result, content: [{ type: "text", text: `Saved parent review for ${run.runId}: ${params.decision}.\nThe review note is parent-only and was not sent to the child. Put actionable instructions in ${deps.allowMutatingManagementActions === false && deps.config.compactChildTools === false ? "subagent resume/nudge" : "agent_runs continue/nudge"}. No work started.` }] };
-				} catch (error) {
-					return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true, details: { mode: "management", results: [] } };
-				}
-			}
-			if (params.action === "history" || params.action === "search") {
-				try { return await ownedHistoryQuery(deps.state, params, signal); }
-				catch (error) {
-					return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true, details: { mode: "management", results: [] } };
-				}
-			}
-			if (params.action === "questions" || params.action === "answer") {
-				return controlSupervisorQuestion({ params: paramsWithResolvedCwd, requestCwd, ctx, deps });
-			}
-			if (params.action === "doctor") {
-				let currentSessionFile: string | null = null;
-				let currentSessionId = deps.state.currentSessionId;
-				let sessionError: string | undefined;
-				try {
-					currentSessionFile = ctx.sessionManager.getSessionFile() ?? null;
-					currentSessionId = ctx.sessionManager.getSessionId();
-				} catch (error) {
-					sessionError = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
-				}
-				let orchestratorTarget: string | undefined;
-				try {
-					const fallbackTarget = resolveIntercomSessionTarget(deps.pi.getSessionName(), ctx.sessionManager.getSessionId());
-					orchestratorTarget = resolveOrchestratorIntercomTarget(deps.pi.events, fallbackTarget);
-				} catch {}
-				const { connection } = await queryLiveIntercomStatus(deps.pi.events);
-				return {
-					content: [{
-						type: "text",
-						text: buildDoctorReport({
-							cwd: requestCwd,
-							nativeSessionCwd: ctx.cwd,
-							config: deps.config,
-							state: deps.state,
-							requestedSessionDir: paramsWithResolvedCwd.sessionDir,
-							currentSessionFile,
-							currentSessionId,
-							orchestratorTarget,
-							connection,
-							sessionError,
-							projectTrusted: ctx.isProjectTrusted(),
-							expandTilde: deps.expandTilde,
-						}),
-					}],
-					details: { mode: "management", results: [] },
-				};
-			}
-			if (params.action === "status") {
-				const targetRunId = paramsWithResolvedCwd.id ?? paramsWithResolvedCwd.runId;
-				if (!targetRunId && !params.dir && deps.state.ownedRuns && deps.allowMutatingManagementActions !== false) {
-					try { return await ownedRunList(deps.state, { ...params, signal }); } catch (error) {
-						return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true, details: { mode: "management", results: [] } };
-					}
-				}
-				let includeRunHeader = true;
-				if (targetRunId) {
-					try {
-						includeRunHeader = Boolean(params.dir) || !resolveOwnedRun(deps.state, targetRunId);
-					} catch (error) {
-						const message = error instanceof Error ? error.message : String(error);
-						return { content: [{ type: "text", text: message }], isError: true, details: { mode: "management", results: [] } };
-					}
-				}
-				let inspected = inspectSubagentStatus({ ...paramsWithResolvedCwd, action: "status" }, { state: deps.state, nested: nestedResolutionScopeForExecutor(deps), includeRunHeader });
-				const targets = inspected.details.intercomTargets ?? [];
-				if (!inspected.isError && targets.length) {
-					const intercomHealth = await queryLiveIntercomHealth(deps.pi.events, targets);
-					if (intercomHealth.size) inspected = inspectSubagentStatus({ ...paramsWithResolvedCwd, action: "status" }, { state: deps.state, nested: nestedResolutionScopeForExecutor(deps), intercomHealth, includeRunHeader });
-				}
-				if (targetRunId && inspected.isError && inspected.content[0]?.type === "text" && inspected.content[0].text.startsWith("Async run not found.")) {
-					try {
-						const remembered = resolveRememberedForegroundRun(targetRunId, deps.state);
-						if (remembered) return rememberedForegroundStatusResult(remembered, Boolean(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 (!targetRunId && !params.dir && deps.allowMutatingManagementActions !== false) {
-					const foreground = [...(deps.state.foregroundRuns?.values() ?? [])]
-						.sort((a, b) => b.updatedAt - a.updatedAt)
-						.map((run) => rememberedForegroundStatusResult(run));
-					if (foreground.length) {
-						inspected = {
-							...inspected,
-							content: [...foreground.flatMap((result) => result.content), ...inspected.content],
-							details: {
-								...inspected.details,
-								managementControls: [...foreground.flatMap((result) => result.details.managementControl ? [result.details.managementControl] : []), ...(inspected.details.managementControls ?? [])],
-							},
-						};
-					}
-				}
-				return inspected;
-			}
-			if (params.action === "nudge") {
-				return nudgeSubagentRun({ params: paramsWithResolvedCwd, deps, ctx });
-			}
-			if (params.action === "resume") {
-				return resumeAsyncRun({ params: paramsWithResolvedCwd, requestCwd, ctx, deps });
-			}
-			if (params.action === "extend") {
-				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: [] } };
-					}
-				}
-				return extendAsyncTimeoutResult(deps.state, resolved?.id ?? targetRunId, paramsWithResolvedCwd.extendMs ?? paramsWithResolvedCwd.timeoutMs ?? paramsWithResolvedCwd.maxRuntimeMs ?? 0);
-			}
-			if (params.action === "interrupt") {
-				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, paramsWithResolvedCwd.index);
-				const asyncInterruptResult = interruptAsyncRun(deps.state, resolved?.kind === "async" ? resolved.id : targetRunId, paramsWithResolvedCwd.index);
-				if (asyncInterruptResult) return asyncInterruptResult;
-				return {
-					content: [{ type: "text", text: "No interrupt-capable run found in this session." }],
-					isError: true,
-					details: { mode: "management", results: [] },
-				};
-			}
-			if (!(SUBAGENT_ACTIONS as readonly string[]).includes(params.action)) {
-				return {
-					content: [{ type: "text", text: `Unknown action: ${params.action}. Valid: ${SUBAGENT_ACTIONS.join(", ")}` }],
-					isError: true,
-					details: { mode: "management" as const, results: [] },
-				};
-			}
-			if (deps.allowMutatingManagementActions === false && MUTATING_MANAGEMENT_ACTIONS.has(params.action)) {
-				return {
-					content: [{ type: "text", text: `Action '${params.action}' is not available from child-safe subagent fanout mode.` }],
-					isError: true,
-					details: { mode: "management" as const, results: [] },
-				};
-			}
-			return handleManagementAction(params.action, paramsWithResolvedCwd, { ...ctx, cwd: requestCwd });
-		}
-
-		const { blocked, depth, maxDepth } = checkSubagentDepth(deps.config.maxSubagentDepth);
-		if (blocked) {
-			return {
-				content: [
-					{
-						type: "text",
-						text:
-							`Nested subagent call blocked (depth=${depth}, max=${maxDepth}). ` +
-							"You are running at the maximum subagent nesting depth. " +
-							"Complete your current task directly without delegating to further subagents.",
-					},
-				],
-				isError: true,
-				details: { mode: "single" as const, results: [] },
-			};
-		}
-
-		const normalized = normalizeRepeatedParallelCounts(paramsWithResolvedCwd);
-		if (normalized.error) return normalized.error;
-		const normalizedParams = normalized.params!;
-
-		let effectiveParams = applyForceTopLevelAsyncOverride(
-			normalizedParams,
-			depth,
-			deps.config.forceTopLevelAsync === true,
-		);
-
-		const scope: AgentScope = resolveExecutionAgentScope(effectiveParams.agentScope);
-		const effectiveCwd = effectiveParams.cwd ?? invocationCwd;
-		const parentSessionFile = ctx.sessionManager.getSessionFile() ?? null;
-		deps.state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
-		const inheritedModel = providerQualifiedModelId(ctx.model?.provider, ctx.model?.id);
-		const discoveredAgents = deps.discoverAgents(effectiveCwd, scope, { projectTrusted: ctx.isProjectTrusted() }).agents
-			.map((agent) => agent.model || !inheritedModel ? agent : { ...agent, model: inheritedModel });
-		const invocationAgentNames = collectInvocationAgentNames(effectiveParams);
-		const invocationContext: SubagentParamsLike["context"] = invocationUsesForkContext(
-			effectiveParams.context,
-			invocationAgentNames,
-			discoveredAgents,
-		)
-			? "fork"
-			: undefined;
-		const fallbackTarget = resolveIntercomSessionTarget(deps.pi.getSessionName(), ctx.sessionManager.getSessionId());
-		const orchestratorTarget = resolveOrchestratorIntercomTarget(deps.pi.events, fallbackTarget);
-		const intercomBridge = resolveIntercomBridge(orchestratorTarget);
-		const runId = randomUUID();
-		const agentNameAtIndex = buildFlatAgentNameResolver(effectiveParams);
-		const resolveContextForAgent = (agentName: string | undefined) =>
-			resolveAgentContext(effectiveParams.context, agentName, discoveredAgents);
-		const resolveContextForIndex = (index?: number) =>
-			resolveContextForAgent(agentNameAtIndex(index ?? 0));
-		const agents = discoveredAgents.map((agent) => ({ ...agent, defaultContext: resolveContextForAgent(agent.name) }));
-		const inheritedNestedRoute = resolveInheritedNestedRouteFromEnv();
-		const nestedRoute = inheritedNestedRoute ?? createNestedRoute(runId);
-		const shareEnabled = effectiveParams.share === true;
-		const hasChain = (effectiveParams.chain?.length ?? 0) > 0;
-		const hasTasks = (effectiveParams.tasks?.length ?? 0) > 0;
-		const hasSingle = !hasChain && !hasTasks && Boolean(effectiveParams.agent);
-		const allowClarifyTaskPrompt = hasChain
-			&& effectiveParams.clarify === true
-			&& ctx.hasUI
-			&& !(effectiveParams.chain?.some(isParallelStep) ?? false);
-
-		const validationError = validateExecutionInput(
-			effectiveParams,
-			agents,
-			hasChain,
-			hasTasks,
-			hasSingle,
-			allowClarifyTaskPrompt,
-		);
-		if (validationError) return validationError;
-		if (invocationContext === "fork") {
-			let availableModels: ModelInfo[];
-			try {
-				availableModels = ctx.modelRegistry.getAvailable().map(toModelInfo);
-			} catch (error) {
-				return toExecutionErrorResult(effectiveParams, error, invocationContext);
-			}
-			const forkModelPolicyError = validateForkContextModelPolicy(
-				effectiveParams,
-				discoveredAgents,
-				(model) => resolveModelCandidate(model, availableModels, ctx.model?.provider),
-			);
-			if (forkModelPolicyError) {
-				return toExecutionErrorResult(effectiveParams, new Error(forkModelPolicyError), invocationContext);
-			}
-		}
-
-		try {
-			const clarified = await clarifyInvocation({ params: effectiveParams, agents, ctx, cwd: effectiveCwd, runId });
-			if (!clarified) return { content: [{ type: "text", text: "Cancelled" }], details: { mode: hasChain ? "chain" : hasTasks ? "parallel" : "single", results: [] } };
-			effectiveParams = clarified;
-		} catch (error) {
-			return toExecutionErrorResult(effectiveParams, error, invocationContext);
-		}
-		if (signal?.aborted) return toExecutionErrorResult(effectiveParams, new Error("Subagent cancelled before launch."), invocationContext);
-
-		let sessionFileForIndex: (idx?: number) => string | undefined = () => undefined;
-		let forkSessionFileForAgentIndex: (agentName: string | undefined, idx?: number) => string | undefined = () => undefined;
-		try {
-			const forkContextResolver = createPerAgentForkContextResolver(ctx.sessionManager, resolveContextForIndex, {
-				resolveContextForAgentIndex: (agentName) => resolveContextForAgent(agentName),
-			});
-			sessionFileForIndex = forkContextResolver.sessionFileForIndex;
-			forkSessionFileForAgentIndex = forkContextResolver.sessionFileForAgentIndex;
-		} catch (error) {
-			return toExecutionErrorResult(effectiveParams, error, invocationContext);
-		}
-		const asyncMode = resolveAsyncExecutionMode(effectiveParams, deps.asyncByDefault);
-		const backgroundRequestedWhileClarifying = (hasChain || hasTasks) && asyncMode.backgroundRequestedWhileClarifying;
-		const effectiveAsync = asyncMode.effectiveAsync;
-		const foregroundTimeout = resolveForegroundTimeoutMs(effectiveParams);
-		if (foregroundTimeout.error) return buildRequestedModeError(effectiveParams, foregroundTimeout.error);
-		if (effectiveAsync && foregroundTimeout.timeoutMs !== undefined) {
-			return buildRequestedModeError(effectiveParams, "timeoutMs/maxRuntimeMs only applies to foreground subagent runs. Set async:false or use action:'interrupt' for background runs.");
-		}
-		if (!effectiveAsync) foregroundTimeout.timeoutMs = normalizeRoleForegroundTimeout(effectiveParams, foregroundTimeout.timeoutMs);
-		const controlConfig = resolveControlConfig(deps.config.control, effectiveParams.control);
-
-		const artifactsEnabled = effectiveParams.artifacts !== false;
-		const artifactsDir = effectiveAsync ? deps.tempArtifactsDir : getArtifactsDir(parentSessionFile);
-
-		let sessionRoot: string;
-		if (effectiveParams.sessionDir) {
-			sessionRoot = path.resolve(deps.expandTilde(effectiveParams.sessionDir));
-		} else {
-			const baseSessionRoot = deps.config.defaultSessionDir
-				? path.resolve(deps.expandTilde(deps.config.defaultSessionDir))
-				: deps.getSubagentSessionRoot(parentSessionFile);
-			sessionRoot = path.join(baseSessionRoot, runId);
-		}
-		try {
-			fs.mkdirSync(sessionRoot, { recursive: true });
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			return toExecutionErrorResult(
-				effectiveParams,
-				new Error(`Failed to create session directory '${sessionRoot}': ${message}`),
-				invocationContext,
-			);
-		}
-		const sessionDirForIndex = (idx?: number) =>
-			path.join(sessionRoot, `run-${idx ?? 0}`);
-		const childSessionFileForIndex = (idx?: number) =>
-			sessionFileForIndex(idx) ?? path.join(sessionDirForIndex(idx), "session.jsonl");
-		const childSessionFileForAgentIndex = (agentName: string | undefined, idx?: number) =>
-			forkSessionFileForAgentIndex(agentName, idx) ?? path.join(sessionDirForIndex(idx), "session.jsonl");
-
-		const workflowGraph = effectiveParams.chain ? buildWorkflowGraphSnapshot({ runId, steps: effectiveParams.chain }) : undefined;
-		const assignmentNodes = workflowGraph && workflowAgentNodes(workflowGraph);
-		const onUpdateWithContext = (r: SubagentExecutionResult) => {
-			const owned = deps.state.ownedRuns?.get(runId);
-			if (owned && r.details.workflowGraph) rememberOwnedRun(deps.state, { ...owned, children: workflowChildren(owned.children, r.details.workflowGraph) });
-
-			onUpdate?.(withForkContext(r, invocationContext));
-		};
-		const assignments = effectiveParams.tasks ?? effectiveParams.chain?.flatMap((step) =>
-			isParallelStep(step) ? step.parallel : isDynamicParallelStep(step) ? [step.parallel] : [step])
-			?? [{ agent: effectiveParams.agent!, task: effectiveParams.task, label: effectiveParams.label }];
-
-		saveQuestionOwner(runId, ctx.sessionManager.getSessionId());
-		const execData: ExecutionContextData = {
-			params: effectiveParams,
-			effectiveCwd,
-			ctx,
-			signal,
-			onUpdate: onUpdateWithContext,
-			agents,
-			runId,
-			shareEnabled,
-			sessionRoot,
-			sessionDirForIndex,
-			sessionFileForIndex: childSessionFileForIndex,
-			sessionFileForAgentIndex: childSessionFileForAgentIndex,
-			artifactsEnabled,
-			artifactsDir,
-			backgroundRequestedWhileClarifying,
-			effectiveAsync,
-			...(foregroundTimeout.timeoutMs !== undefined ? { foregroundTimeoutMs: foregroundTimeout.timeoutMs } : {}),
-			controlConfig,
-			intercomBridge,
-			nestedRoute,
-		};
-
-		try {
-			const result = runAsyncPath(execData, deps);
-			if (!result) throw new Error("Invalid subagent execution mode.");
-			if (result.isError) return withForkContext(result, invocationContext);
-			rememberOwnedRun(deps.state, {
-				runId, ownerSessionId: ctx.sessionManager.getSessionId(), rootRunId: runId,
-				source: "async", mode: hasChain ? "chain" : hasTasks ? "parallel" : "single",
-				cwd: effectiveCwd, task: effectiveParams.task ?? effectiveParams.tasks?.map((task) => task.task).join("\n") ?? "Delegated workflow",
-				asyncDir: result.details.asyncDir, pid: result.details.asyncPid ?? deps.state.asyncJobs.get(runId)?.pid,
-				startedAt: Date.now(), children: assignments.map(({ agent, task, label }, index) => ({ agent, index, task, label, ...(assignmentNodes?.[index] ? { workflowNodeId: assignmentNodes[index]!.id } : {}) })),
-			});
-			if (!effectiveAsync && result.details.asyncId) {
-				return withForkContext(await waitForOwnedRun({ id: runId, deps, ctx, signal, onUpdate: onUpdateWithContext,
-					cancelNewRun: !effectiveAsync, executionResult: true, includeProgress: effectiveParams.includeProgress }), invocationContext);
-			}
-			return withForkContext(result, invocationContext);
-		} catch (error) {
-			const result = toExecutionErrorResult(effectiveParams, error, invocationContext);
-			const owned = deps.state.ownedRuns?.get(runId);
-			if (owned) rememberOwnedRun(deps.state, { ...owned, error: result.content.filter((part) => part.type === "text").map((part) => part.text).join("\n") });
-			return result;
-		}
-	};
-
-	return { execute: async (...args) => {
-		const [id, params, signal, onUpdate, ctx, executionCwd] = args;
-		const waiting = params.async === false && (params.action === "resume" || params.action === "answer");
-		const before = waiting ? new Set(deps.state.ownedRuns?.keys()) : undefined;
-		let result = await execute(id, params, signal, onUpdate, ctx, executionCwd);
-		// Launch/answer receipts and claims are saved before waiting; execution failure must not undo a successful launch.
-		if (waiting && !result.isError) {
-			const question = result.details.questions?.find((question) => question.delivery || question.state === "answer_pending");
-			const id = result.details.asyncId ?? result.details.managementControl?.runId ?? question?.delivery?.runId ?? question?.runId ?? params.id ?? params.runId;
-			const index = result.details.asyncId || question?.delivery?.kind === "revive" ? 0
-				: result.details.managementControl?.nextActions.find((action) => action.index !== undefined)?.index ?? question?.index ?? params.index;
-			if (id) return waitForOwnedRun({ id, index, deps, ctx, signal, onUpdate, cancelNewRun: params.async === false && !before?.has(id) && deps.state.ownedRuns?.has(id), executionResult: true, includeProgress: params.includeProgress });
-		}
-		if (args[1].action === "interrupt") return cancelSupervisorInput(result, args[1], args[4].sessionManager.getSessionId(), deps.pi.events);
-		if (args[1].action !== "status" || result.details.runList) return result;
-		const requested = args[1].id ?? args[1].runId;
-		if (requested && !args[1].dir) {
-			try {
-				const owned = resolveOwnedRun(deps.state, requested);
-				if (owned) result = ownedRunStatusResult(owned, deps.state, result, { full: args[1].full, childSafe: Boolean(nestedResolutionScopeForExecutor(deps)) });
-			} catch (error) {
-				return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true, details: { mode: "management", results: [] } };
-			}
-		}
-		return projectSupervisorQuestions(result, args[1], args[4].sessionManager.getSessionId(), Boolean(nestedResolutionScopeForExecutor(deps)));
-	} };
+export interface SubagentExecutionRequest extends Omit<ExecutionInvocation, "invocationCwd"> {
+  readonly toolCallId: string;
+  readonly executionCwd?: string;
+}
+interface WaitTarget {
+  readonly id: string;
+  readonly index?: number;
+}
+function present(value: string | undefined): boolean {
+  return value !== undefined && value.length > 0;
+}
+function needsExecutionCwd(params: SubagentParamsLike): boolean {
+  return (
+    !present(params.action) ||
+    params.cwd !== undefined ||
+    ["list", "get", "create", "update", "delete", "doctor"].some(
+      (action) => action === params.action,
+    )
+  );
+}
+function waitsForReceipt(params: SubagentParamsLike): boolean {
+  return params.async === false && (params.action === "resume" || params.action === "answer");
+}
+type ReceiptQuestion = NonNullable<SubagentExecutionResult["details"]["questions"]>[number];
+function receiptQuestion(result: SubagentExecutionResult): ReceiptQuestion | undefined {
+  return result.details.questions?.find(
+    (entry) => entry.delivery !== undefined || entry.state === "answer_pending",
+  );
+}
+function launchReceiptId(result: SubagentExecutionResult): string | undefined {
+  return result.details.asyncId ?? result.details.managementControl?.runId;
+}
+function questionReceiptId(question: ReceiptQuestion | undefined): string | undefined {
+  return question?.delivery?.runId ?? question?.runId;
+}
+function pendingReceiptIndex(result: SubagentExecutionResult): number | undefined {
+  return result.details.managementControl?.nextActions.find((action) => action.index !== undefined)
+    ?.index;
+}
+function receiptIndex(
+  result: SubagentExecutionResult,
+  question: ReceiptQuestion | undefined,
+  params: SubagentParamsLike,
+): number | undefined {
+  if (present(result.details.asyncId) || question?.delivery?.kind === "revive") {
+    return 0;
+  }
+  return pendingReceiptIndex(result) ?? question?.index ?? params.index;
+}
+function receiptTarget(
+  result: SubagentExecutionResult,
+  params: SubagentParamsLike,
+): WaitTarget | undefined {
+  const question = receiptQuestion(result);
+  const id = launchReceiptId(result) ?? questionReceiptId(question) ?? params.id ?? params.runId;
+  if (id === undefined || id.length === 0) {
+    return;
+  }
+  return { id, index: receiptIndex(result, question, params) };
+}
+/** Owns invocation/session preparation and foreground waiting; domain owners handle management and launch. */
+class ForegroundExecutor {
+  private readonly deps: ExecutorDeps;
+  private readonly management: ManagementActions;
+  private readonly launch: InvocationExecution;
+  constructor(
+    // Native tool invocation owns session state preparation and run/wait lifecycle through these dependencies.
+    deps: ExecutorDeps,
+  ) {
+    this.deps = deps;
+    this.management = new ManagementActions(deps);
+    this.launch = new InvocationExecution(deps);
+  }
+  async execute(call: SubagentExecutionRequest): Promise<SubagentExecutionResult> {
+    const waiting = waitsForReceipt(call.params);
+    const before = waiting ? new Set(this.deps.state.ownedRuns?.keys()) : undefined;
+    const result = await this.invoke(call);
+    // Launch/answer receipts are durable before waiting; wait failure cannot undo an accepted launch.
+    if (waiting && result.isError !== true) {
+      const target = receiptTarget(result, call.params);
+      if (target) {
+        return this.waitForReceipt(call, target, before);
+      }
+    }
+    return this.projectAction(result, call);
+  }
+  private async invoke(call: SubagentExecutionRequest): Promise<SubagentExecutionResult> {
+    const needsCwd = needsExecutionCwd(call.params);
+    const cwd = needsCwd
+      ? (call.executionCwd ?? resolveExecutionCwd(this.deps.pi, call.ctx))
+      : call.ctx.cwd;
+    await this.deps.ensureSessionState?.(call.ctx);
+    const state = this.deps.state;
+    if (needsCwd) {
+      state.baseCwd = cwd;
+    }
+    state.foregroundRuns ??= new Map();
+    const requestCwd = resolveRequestedCwd(cwd, call.params.cwd);
+    const params =
+      call.params.cwd === undefined ? call.params : { ...call.params, cwd: requestCwd };
+    if (present(params.action)) {
+      return this.management.execute({ params, requestCwd, ctx: call.ctx, signal: call.signal });
+    }
+    return this.launch.execute({
+      params,
+      invocationCwd: cwd,
+      ctx: call.ctx,
+      signal: call.signal,
+      onUpdate: call.onUpdate,
+    });
+  }
+  private waitForReceipt(
+    call: SubagentExecutionRequest,
+    target: WaitTarget,
+    before: Readonly<ReadonlySet<string>> | undefined,
+  ): Promise<SubagentExecutionResult> {
+    const newlyLaunched =
+      before?.has(target.id) !== true && this.deps.state.ownedRuns?.has(target.id) === true;
+    return waitForOwnedRun({
+      ...target,
+      deps: this.deps,
+      ctx: call.ctx,
+      signal: call.signal,
+      onUpdate: call.onUpdate,
+      cancelNewRun: call.params.async === false && newlyLaunched,
+      executionResult: true,
+      includeProgress: call.params.includeProgress,
+    });
+  }
+  private projectAction(
+    result: SubagentExecutionResult,
+    call: SubagentExecutionRequest,
+  ): SubagentExecutionResult {
+    const { params, ctx } = call;
+    if (params.action === "interrupt") {
+      return cancelSupervisorInput(
+        result,
+        params,
+        ctx.sessionManager.getSessionId(),
+        this.deps.pi.events,
+      );
+    }
+    if (params.action !== "status" || result.details.runList) {
+      return result;
+    }
+    let projected: SubagentExecutionResult;
+    try {
+      projected = this.projectOwnedStatus(result, params);
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: errorMessage(error) }],
+        isError: true,
+        details: { mode: "management", results: [] },
+      };
+    }
+    return projectSupervisorQuestions(
+      projected,
+      params,
+      ctx.sessionManager.getSessionId(),
+      nestedResolutionScopeForExecutor(this.deps) !== undefined,
+    );
+  }
+  private projectOwnedStatus(
+    result: SubagentExecutionResult,
+    params: SubagentParamsLike,
+  ): SubagentExecutionResult {
+    const requested = params.id ?? params.runId;
+    if (requested === undefined || requested.length === 0 || present(params.dir)) {
+      return result;
+    }
+    const owned = resolveOwnedRun(this.deps.state, requested);
+    return owned
+      ? ownedRunStatusResult(owned, this.deps.state, result, {
+          full: params.full,
+          childSafe: nestedResolutionScopeForExecutor(this.deps) !== undefined,
+        })
+      : result;
+  }
+}
+export function createSubagentExecutor(
+  // This factory transfers the actual session mutation owner to the native executor and its domain owners.
+  deps: ExecutorDeps,
+): { execute: (request: SubagentExecutionRequest) => Promise<SubagentExecutionResult> } {
+  const owner = new ForegroundExecutor(deps);
+  return {
+    execute: async (request) => owner.execute(request),
+  };
 }