@bastani/atomic 0.8.19 → 0.8.20

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

@@ -1,7 +1,6 @@
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { APP_NAME, getEnvValue, type ExtensionAPI, type ExtensionContext } from "@bastani/atomic";
 import { type AgentConfig, type AgentScope } from "../../agents/agents.ts";
 import { getArtifactsDir } from "../../shared/artifacts.ts";
@@ -78,15 +77,19 @@ import {
 	type SingleResult,
 	type SubagentRunMode,
 	type SubagentState,
+	type SubagentToolResult,
 	DEFAULT_ARTIFACT_CONFIG,
 	SUBAGENT_ACTIONS,
 	SUBAGENT_CONTROL_EVENT,
 	SUBAGENT_CONTROL_INTERCOM_EVENT,
 	checkSubagentDepth,
+	isWorkflowStageOrchestrationContext,
 	resolveTopLevelParallelConcurrency,
 	resolveTopLevelParallelMaxTasks,
 	resolveChildMaxSubagentDepth,
-	resolveCurrentMaxSubagentDepth,
+	resolveSubagentDepthPolicy,
+	resolveWorkflowStageMaxSubagentDepth,
+	subagentDepthBlockedMessage,
 	wrapForkTask,
 } from "../../shared/types.ts";
 
@@ -107,7 +110,7 @@ interface TaskParam {
 }
 
 export interface SubagentParamsLike {
-	action?: string;
+	action?: (typeof SUBAGENT_ACTIONS)[number];
 	id?: string;
 	runId?: string;
 	dir?: string;
@@ -115,6 +118,8 @@ export interface SubagentParamsLike {
 	agent?: string;
 	task?: string;
 	message?: string;
+	chainName?: string;
+	config?: unknown;
 	chain?: ChainStep[];
 	tasks?: TaskParam[];
 	concurrency?: number;
@@ -133,10 +138,32 @@ export interface SubagentParamsLike {
 	skill?: string | string[] | boolean;
 	output?: string | boolean;
 	outputMode?: "inline" | "file-only";
-	agentScope?: unknown;
+	agentScope?: string;
 	chainDir?: string;
 }
 
+export interface SubagentExecutorRuntimeDeps {
+	runSync: typeof runSync;
+	executeAsyncChain: typeof executeAsyncChain;
+	executeAsyncSingle: typeof executeAsyncSingle;
+	isAsyncAvailable: typeof isAsyncAvailable;
+	formatAsyncStartedMessage: typeof formatAsyncStartedMessage;
+}
+
+const defaultSubagentExecutorRuntimeDeps: SubagentExecutorRuntimeDeps = {
+	runSync,
+	executeAsyncChain,
+	executeAsyncSingle,
+	isAsyncAvailable,
+	formatAsyncStartedMessage,
+};
+
+function resolveSubagentExecutorRuntimeDeps(
+	overrides?: Partial<SubagentExecutorRuntimeDeps>,
+): SubagentExecutorRuntimeDeps {
+	return { ...defaultSubagentExecutorRuntimeDeps, ...overrides };
+}
+
 interface ExecutorDeps {
 	pi: ExtensionAPI;
 	state: SubagentState;
@@ -147,6 +174,11 @@ interface ExecutorDeps {
 	expandTilde: (p: string) => string;
 	discoverAgents: (cwd: string, scope: AgentScope) => { agents: AgentConfig[] };
 	allowMutatingManagementActions?: boolean;
+	runtime?: Partial<SubagentExecutorRuntimeDeps>;
+}
+
+interface ResolvedExecutorDeps extends Omit<ExecutorDeps, "runtime"> {
+	runtime: SubagentExecutorRuntimeDeps;
 }
 
 interface ExecutionContextData {
@@ -154,7 +186,7 @@ interface ExecutionContextData {
 	effectiveCwd: string;
 	ctx: ExtensionContext;
 	signal: AbortSignal;
-	onUpdate?: (r: AgentToolResult<Details>) => void;
+	onUpdate?: (r: SubagentToolResult) => void;
 	agents: AgentConfig[];
 	runId: string;
 	shareEnabled: boolean;
@@ -206,7 +238,7 @@ function formatForegroundActivity(control: SubagentState["foregroundControls"] e
 	return [`active ${seconds}s ago`, ...facts].join(" | ");
 }
 
-function nestedResolutionScopeForExecutor(deps: ExecutorDeps): NestedRunResolutionScope | undefined {
+function nestedResolutionScopeForExecutor(deps: ResolvedExecutorDeps): NestedRunResolutionScope | undefined {
 	if (deps.allowMutatingManagementActions !== false) return undefined;
 	const route = resolveInheritedNestedRouteFromEnv();
 	const address = route ? resolveNestedParentAddressFromEnv() : undefined;
@@ -216,7 +248,7 @@ function nestedResolutionScopeForExecutor(deps: ExecutorDeps): NestedRunResoluti
 	};
 }
 
-function foregroundStatusResult(control: SubagentState["foregroundControls"] extends Map<string, infer T> ? T : never): AgentToolResult<Details> {
+function foregroundStatusResult(control: SubagentState["foregroundControls"] extends Map<string, infer T> ? T : never): SubagentToolResult {
 	let nestedWarning: string | undefined;
 	try {
 		updateForegroundNestedProjection(control);
@@ -399,7 +431,7 @@ function emitControlNotification(input: {
 	}
 }
 
-function interruptAsyncRun(state: SubagentState, runId: string | undefined): AgentToolResult<Details> | null {
+function interruptAsyncRun(state: SubagentState, runId: string | undefined): SubagentToolResult | null {
 	const target = getAsyncInterruptTarget(state, runId);
 	if (!target) return null;
 	const status = readStatus(target.asyncDir);
@@ -509,7 +541,7 @@ async function sendNestedControlRequest(target: ResolvedSubagentRunId & { kind:
 	return waitForNestedControlResult(target, requestId);
 }
 
-function directNestedAsyncInterrupt(target: ResolvedSubagentRunId & { kind: "nested" }): AgentToolResult<Details> | undefined {
+function directNestedAsyncInterrupt(target: ResolvedSubagentRunId & { kind: "nested" }): SubagentToolResult | undefined {
 	const run = target.match.run;
 	const asyncDir = resolveNestedAsyncDir(target.match.rootRunId, run);
 	if (!asyncDir) return undefined;
@@ -525,7 +557,7 @@ function directNestedAsyncInterrupt(target: ResolvedSubagentRunId & { kind: "nes
 	}
 }
 
-async function interruptNestedRun(target: ResolvedSubagentRunId & { kind: "nested" }): Promise<AgentToolResult<Details>> {
+async function interruptNestedRun(target: ResolvedSubagentRunId & { kind: "nested" }): Promise<SubagentToolResult> {
 	const run = target.match.run;
 	if (run.state === "complete") return { content: [{ type: "text", text: `Nested run ${run.id} is already complete and cannot be interrupted.` }], isError: true, details: { mode: "management", results: [] } };
 	if (run.state === "failed") return { content: [{ type: "text", text: `Nested run ${run.id} has failed and cannot be interrupted.` }], isError: true, details: { mode: "management", results: [] } };
@@ -537,7 +569,7 @@ async function interruptNestedRun(target: ResolvedSubagentRunId & { kind: "neste
 	return { content: [{ type: "text", text: `Nested run ${run.id} owner is not reachable and no safe direct async interrupt fallback is available.` }], isError: true, details: { mode: "management", results: [] } };
 }
 
-async function resumeLiveNestedRun(input: { target: ResolvedSubagentRunId & { kind: "nested" }; message: string }): Promise<AgentToolResult<Details>> {
+async function resumeLiveNestedRun(input: { target: ResolvedSubagentRunId & { kind: "nested" }; message: string }): Promise<SubagentToolResult> {
 	const run = input.target.match.run;
 	const result = await sendNestedControlRequest(input.target, "resume", input.message);
 	if (result) return { content: [{ type: "text", text: result.message }], isError: result.ok ? undefined : true, details: { mode: "management", results: [] } };
@@ -548,8 +580,8 @@ async function resumeAsyncRun(input: {
 	params: SubagentParamsLike;
 	requestCwd: string;
 	ctx: ExtensionContext;
-	deps: ExecutorDeps;
-}): Promise<AgentToolResult<Details>> {
+	deps: ResolvedExecutorDeps;
+}): Promise<SubagentToolResult> {
 	const followUp = (input.params.message ?? input.params.task ?? "").trim();
 	if (!followUp) {
 		return {
@@ -602,10 +634,17 @@ async function resumeAsyncRun(input: {
 		};
 	}
 
-	const { blocked, depth, maxDepth } = checkSubagentDepth(input.deps.config.maxSubagentDepth);
+	const resumeDepthPolicy = resolveSubagentDepthPolicy(input.ctx, input.deps.config.maxSubagentDepth);
+	const { blocked, depth, maxDepth, workflowStageGuard } = checkSubagentDepth(resumeDepthPolicy.maxSubagentDepth);
 	if (blocked) {
 		return {
-			content: [{ type: "text", text: `Nested subagent resume blocked (depth=${depth}, max=${maxDepth}). Complete the follow-up directly instead.` }],
+			content: [{
+				type: "text",
+				text: subagentDepthBlockedMessage(depth, maxDepth, {
+					action: "resume",
+					workflowStageGuard: workflowStageGuard || resumeDepthPolicy.workflowStageSubagentGuard,
+				}),
+			}],
 			isError: true,
 			details: { mode: "management", results: [] },
 		};
@@ -637,7 +676,7 @@ async function resumeAsyncRun(input: {
 	const runId = randomUUID().slice(0, 8);
 	const artifactConfig: ArtifactConfig = { ...DEFAULT_ARTIFACT_CONFIG, enabled: input.params.artifacts !== false };
 	const availableModels = input.ctx.modelRegistry.getAvailable().map(toModelInfo);
-	const result = executeAsyncSingle(runId, {
+	const result = input.deps.runtime.executeAsyncSingle(runId, {
 		agent: target.agent,
 		task: buildRevivedAsyncTask(target, followUp),
 		agentConfig,
@@ -655,7 +694,8 @@ async function resumeAsyncRun(input: {
 		shareEnabled: input.params.share === true,
 		sessionRoot: input.deps.getSubagentSessionRoot(parentSessionFile),
 		sessionFile: target.sessionFile,
-		maxSubagentDepth: resolveCurrentMaxSubagentDepth(input.deps.config.maxSubagentDepth),
+		maxSubagentDepth: resolveWorkflowStageMaxSubagentDepth(input.ctx, input.deps.config.maxSubagentDepth),
+		workflowStageSubagentGuard: isWorkflowStageOrchestrationContext(input.ctx),
 		worktreeSetupHook: input.deps.config.worktreeSetupHook,
 		worktreeSetupHookTimeoutMs: input.deps.config.worktreeSetupHookTimeoutMs,
 		controlConfig: resolveControlConfig(input.deps.config.control, input.params.control),
@@ -677,7 +717,7 @@ async function resumeAsyncRun(input: {
 		revivedTarget ? `Intercom target: ${revivedTarget} (if registered)` : undefined,
 		`Status if needed: subagent({ action: "status", id: "${revivedId}" })`,
 	].filter((line): line is string => Boolean(line));
-	return { content: [{ type: "text", text: formatAsyncStartedMessage(lines.join("\n")) }], details: result.details };
+	return { content: [{ type: "text", text: input.deps.runtime.formatAsyncStartedMessage(lines.join("\n")) }], details: result.details };
 }
 
 function resultSummaryForIntercom(result: SingleResult): string {
@@ -765,7 +805,7 @@ function validateExecutionInput(
 	hasTasks: boolean,
 	hasSingle: boolean,
 	allowClarifyTaskPrompt: boolean,
-): AgentToolResult<Details> | null {
+): SubagentToolResult | null {
 	if (Number(hasChain) + Number(hasTasks) + Number(hasSingle) !== 1) {
 		return {
 			content: [
@@ -869,7 +909,7 @@ function applyAgentDefaultContext(params: SubagentParamsLike, agents: AgentConfi
 		: params;
 }
 
-function buildRequestedModeError(params: SubagentParamsLike, message: string): AgentToolResult<Details> {
+function buildRequestedModeError(params: SubagentParamsLike, message: string): SubagentToolResult {
 	return withForkContext(
 		{
 			content: [{ type: "text", text: message }],
@@ -921,7 +961,7 @@ function expandChainParallelCounts(chain: ChainStep[]): { chain?: ChainStep[]; e
 	return { chain: expandedChain };
 }
 
-function normalizeRepeatedParallelCounts(params: SubagentParamsLike): { params?: SubagentParamsLike; error?: AgentToolResult<Details> } {
+function normalizeRepeatedParallelCounts(params: SubagentParamsLike): { params?: SubagentParamsLike; error?: SubagentToolResult } {
 	if (params.tasks) {
 		const expandedTasks = expandTopLevelTaskCounts(params.tasks);
 		if (expandedTasks.error) {
@@ -940,9 +980,9 @@ function normalizeRepeatedParallelCounts(params: SubagentParamsLike): { params?:
 }
 
 function withForkContext(
-	result: AgentToolResult<Details>,
+	result: SubagentToolResult,
 	context: SubagentParamsLike["context"],
-): AgentToolResult<Details> {
+): SubagentToolResult {
 	if (context !== "fork" || !result.details) return result;
 	return {
 		...result,
@@ -953,7 +993,7 @@ function withForkContext(
 	};
 }
 
-function toExecutionErrorResult(params: SubagentParamsLike, error: unknown): AgentToolResult<Details> {
+function toExecutionErrorResult(params: SubagentParamsLike, error: unknown): SubagentToolResult {
 	const message = error instanceof Error ? error.message : String(error);
 	return withForkContext(
 		{
@@ -1005,7 +1045,7 @@ function wrapChainTasksForFork(chain: ChainStep[], context: SubagentParamsLike["
 	});
 }
 
-function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentToolResult<Details> | null {
+function runAsyncPath(data: ExecutionContextData, deps: ResolvedExecutorDeps): SubagentToolResult | null {
 	const {
 		params,
 		effectiveCwd,
@@ -1048,7 +1088,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 		}
 	}
 
-	if (!isAsyncAvailable()) {
+	if (!deps.runtime.isAsyncAvailable()) {
 		return {
 			content: [{ type: "text", text: `Async mode requires upstream jiti for TypeScript execution but it could not be found. Ensure the ${APP_NAME}-subagents package dependencies are installed.` }],
 			isError: true,
@@ -1064,7 +1104,9 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 		currentModel: currentModelFullId(ctx.model),
 	};
 	const availableModels: ModelInfo[] = ctx.modelRegistry.getAvailable().map(toModelInfo);
-	const currentMaxSubagentDepth = resolveCurrentMaxSubagentDepth(deps.config.maxSubagentDepth);
+	const depthPolicy = resolveSubagentDepthPolicy(ctx, deps.config.maxSubagentDepth);
+	const currentMaxSubagentDepth = depthPolicy.maxSubagentDepth;
+	const workflowStageSubagentGuard = depthPolicy.workflowStageSubagentGuard;
 	const currentProvider = ctx.model?.provider;
 	const controlIntercomTarget = intercomBridge.active ? intercomBridge.orchestratorTarget : undefined;
 	const childIntercomTarget = intercomBridge.active ? (agent: string, index: number) => resolveSubagentIntercomTarget(id, agent, index) : undefined;
@@ -1086,7 +1128,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			...(task.reads !== undefined && task.reads !== true ? { reads: task.reads } : {}),
 			...(task.progress !== undefined ? { progress: task.progress } : {}),
 		}));
-		return executeAsyncChain(id, {
+		return deps.runtime.executeAsyncChain(id, {
 			chain: [{
 				parallel: parallelTasks,
 				concurrency: resolveTopLevelParallelConcurrency(params.concurrency, deps.config.parallel?.concurrency),
@@ -1105,6 +1147,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			chainSkills: [],
 			sessionFilesByFlatIndex: params.tasks.map((_, index) => sessionFileForIndex(index)),
 			maxSubagentDepth: currentMaxSubagentDepth,
+			workflowStageSubagentGuard,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
 			controlConfig,
@@ -1118,7 +1161,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 		const normalized = normalizeSkillInput(params.skill);
 		const chainSkills = normalized === false ? [] : (normalized ?? []);
 		const chain = wrapChainTasksForFork(params.chain as ChainStep[], params.context);
-		return executeAsyncChain(id, {
+		return deps.runtime.executeAsyncChain(id, {
 			chain,
 			task: params.task,
 			agents,
@@ -1133,6 +1176,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			chainSkills,
 			sessionFilesByFlatIndex: collectChainSessionFiles(chain, sessionFileForIndex),
 			maxSubagentDepth: currentMaxSubagentDepth,
+			workflowStageSubagentGuard,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
 			controlConfig,
@@ -1158,7 +1202,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 		const skills = normalizedSkills === false ? [] : normalizedSkills;
 		const maxSubagentDepth = resolveChildMaxSubagentDepth(currentMaxSubagentDepth, a.maxSubagentDepth);
 		const modelOverride = resolveModelCandidate((params.model as string | undefined) ?? a.model, availableModels, currentProvider);
-		return executeAsyncSingle(id, {
+		return deps.runtime.executeAsyncSingle(id, {
 			agent: params.agent!,
 			task: params.context === "fork" ? wrapForkTask(params.task ?? "") : (params.task ?? ""),
 			agentConfig: a,
@@ -1176,6 +1220,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			outputMode: effectiveOutputMode,
 			modelOverride,
 			maxSubagentDepth,
+			workflowStageSubagentGuard,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
 			controlConfig,
@@ -1188,7 +1233,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 	return null;
 }
 
-async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Promise<AgentToolResult<Details>> {
+async function runChainPath(data: ExecutionContextData, deps: ResolvedExecutorDeps): Promise<SubagentToolResult> {
 	const {
 		params,
 		effectiveCwd,
@@ -1211,7 +1256,9 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 	const normalized = normalizeSkillInput(params.skill);
 	const chainSkills = normalized === false ? [] : (normalized ?? []);
 	const chain = wrapChainTasksForFork(params.chain as ChainStep[], params.context);
-	const currentMaxSubagentDepth = resolveCurrentMaxSubagentDepth(deps.config.maxSubagentDepth);
+	const depthPolicy = resolveSubagentDepthPolicy(ctx, deps.config.maxSubagentDepth);
+	const currentMaxSubagentDepth = depthPolicy.maxSubagentDepth;
+	const workflowStageSubagentGuard = depthPolicy.workflowStageSubagentGuard;
 	const chainResult = await executeChain({
 		chain,
 		task: params.task,
@@ -1238,12 +1285,14 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 		chainSkills,
 		chainDir: params.chainDir,
 		maxSubagentDepth: currentMaxSubagentDepth,
+		workflowStageSubagentGuard,
 		worktreeSetupHook: deps.config.worktreeSetupHook,
 		worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+		runSync: deps.runtime.runSync,
 	});
 
 	if (chainResult.requestedAsync) {
-		if (!isAsyncAvailable()) {
+		if (!deps.runtime.isAsyncAvailable()) {
 			return {
 				content: [{ type: "text", text: `Background mode requires upstream jiti for TypeScript execution but it could not be found. Ensure the ${APP_NAME}-subagents package dependencies are installed.` }],
 				isError: true,
@@ -1259,7 +1308,7 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 			currentModel: currentModelFullId(ctx.model),
 		};
 		const asyncChain = wrapChainTasksForFork(chainResult.requestedAsync.chain, params.context);
-		return executeAsyncChain(id, {
+		return deps.runtime.executeAsyncChain(id, {
 			chain: asyncChain,
 			task: params.task,
 			agents,
@@ -1274,6 +1323,7 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 			chainSkills: chainResult.requestedAsync.chainSkills,
 			sessionFilesByFlatIndex: collectChainSessionFiles(asyncChain, sessionFileForIndex),
 			maxSubagentDepth: currentMaxSubagentDepth,
+			workflowStageSubagentGuard,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
 			controlConfig,
@@ -1323,6 +1373,7 @@ interface ForegroundParallelRunInput {
 	maxOutput?: MaxOutputConfig;
 	paramsCwd: string;
 	maxSubagentDepths: number[];
+	workflowStageSubagentGuard?: boolean;
 	availableModels: ModelInfo[];
 	modelOverrides: (string | undefined)[];
 	behaviors: Array<ReturnType<typeof resolveStepBehavior>>;
@@ -1335,11 +1386,12 @@ interface ForegroundParallelRunInput {
 	concurrencyLimit: number;
 	liveResults: (SingleResult | undefined)[];
 	liveProgress: (AgentProgress | undefined)[];
-	onUpdate?: (r: AgentToolResult<Details>) => void;
+	onUpdate?: (r: SubagentToolResult) => void;
 	worktreeSetup?: WorktreeSetup;
+	runtime: Pick<SubagentExecutorRuntimeDeps, "runSync">;
 }
 
-function buildParallelModeError(message: string): AgentToolResult<Details> {
+function buildParallelModeError(message: string): SubagentToolResult {
 	return {
 		content: [{ type: "text", text: message }],
 		isError: true,
@@ -1354,7 +1406,7 @@ function createParallelWorktreeSetup(
 	tasks: TaskParam[],
 	setupHook: ExtensionConfig["worktreeSetupHook"],
 	setupHookTimeoutMs: ExtensionConfig["worktreeSetupHookTimeoutMs"],
-): { setup?: WorktreeSetup; errorResult?: AgentToolResult<Details> } {
+): { setup?: WorktreeSetup; errorResult?: SubagentToolResult } {
 	if (!enabled) return {};
 	try {
 		return {
@@ -1469,7 +1521,7 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 			};
 		}
 		const agentConfig = input.agents.find((agent) => agent.name === task.agent);
-		return runSync(input.ctx.cwd, input.agents, task.agent, taskText, {
+		return input.runtime.runSync(input.ctx.cwd, input.agents, task.agent, taskText, {
 			cwd: taskCwd,
 			signal: input.signal,
 			interruptSignal: interruptController.signal,
@@ -1486,6 +1538,7 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 			outputPath,
 			outputMode: behavior?.outputMode,
 			maxSubagentDepth: input.maxSubagentDepths[index],
+			workflowStageSubagentGuard: input.workflowStageSubagentGuard,
 			controlConfig: input.controlConfig,
 			onControlEvent: input.onControlEvent,
 			intercomSessionName: input.childIntercomTarget?.(task.agent, index),
@@ -1496,39 +1549,39 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 			preferredModelProvider: input.ctx.model?.provider,
 			currentModel: currentModelFullId(input.ctx.model),
 			skills: effectiveSkills === false ? [] : effectiveSkills,
-				onUpdate: input.onUpdate
-					? (progressUpdate) => {
-						const stepResults = progressUpdate.details?.results || [];
-						const stepProgress = progressUpdate.details?.progress || [];
-						if (input.foregroundControl && stepProgress.length > 0) {
-							const current = stepProgress[0];
-							input.foregroundControl.currentAgent = task.agent;
-							input.foregroundControl.currentIndex = index;
-							input.foregroundControl.currentActivityState = current?.activityState;
-							input.foregroundControl.lastActivityAt = current?.lastActivityAt;
-							input.foregroundControl.currentTool = current?.currentTool;
-							input.foregroundControl.currentToolStartedAt = current?.currentToolStartedAt;
-							input.foregroundControl.currentPath = current?.currentPath;
-							input.foregroundControl.turnCount = current?.turnCount;
-							input.foregroundControl.tokens = current?.tokens;
-							input.foregroundControl.toolCount = current?.toolCount;
-							input.foregroundControl.updatedAt = Date.now();
-						}
-						if (stepResults.length > 0) input.liveResults[index] = stepResults[0];
-						if (stepProgress.length > 0) input.liveProgress[index] = stepProgress[0];
-						const mergedResults = input.liveResults.filter((result): result is SingleResult => result !== undefined);
-						const mergedProgress = input.liveProgress.filter((progress): progress is AgentProgress => progress !== undefined);
-						input.onUpdate?.({
-							content: progressUpdate.content,
-							details: {
-								mode: "parallel",
-								results: mergedResults,
-								progress: mergedProgress,
-								controlEvents: progressUpdate.details?.controlEvents,
-								totalSteps: input.tasks.length,
-							},
-						});
+			onUpdate: input.onUpdate
+				? (progressUpdate) => {
+					const stepResults = progressUpdate.details?.results || [];
+					const stepProgress = progressUpdate.details?.progress || [];
+					if (input.foregroundControl && stepProgress.length > 0) {
+						const current = stepProgress[0];
+						input.foregroundControl.currentAgent = task.agent;
+						input.foregroundControl.currentIndex = index;
+						input.foregroundControl.currentActivityState = current?.activityState;
+						input.foregroundControl.lastActivityAt = current?.lastActivityAt;
+						input.foregroundControl.currentTool = current?.currentTool;
+						input.foregroundControl.currentToolStartedAt = current?.currentToolStartedAt;
+						input.foregroundControl.currentPath = current?.currentPath;
+						input.foregroundControl.turnCount = current?.turnCount;
+						input.foregroundControl.tokens = current?.tokens;
+						input.foregroundControl.toolCount = current?.toolCount;
+						input.foregroundControl.updatedAt = Date.now();
 					}
+					if (stepResults.length > 0) input.liveResults[index] = stepResults[0];
+					if (stepProgress.length > 0) input.liveProgress[index] = stepProgress[0];
+					const mergedResults = input.liveResults.filter((result): result is SingleResult => result !== undefined);
+					const mergedProgress = input.liveProgress.filter((progress): progress is AgentProgress => progress !== undefined);
+					input.onUpdate?.({
+						content: progressUpdate.content,
+						details: {
+							mode: "parallel",
+							results: mergedResults,
+							progress: mergedProgress,
+							controlEvents: progressUpdate.details?.controlEvents,
+							totalSteps: input.tasks.length,
+						},
+					});
+				}
 				: undefined,
 		}).finally(() => {
 			if (input.foregroundControl?.currentIndex === index) {
@@ -1539,7 +1592,7 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 	});
 }
 
-async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps): Promise<AgentToolResult<Details>> {
+async function runParallelPath(data: ExecutionContextData, deps: ResolvedExecutorDeps): Promise<SubagentToolResult> {
 	const {
 		params,
 		effectiveCwd,
@@ -1585,7 +1638,9 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 		agentConfigs.push(config);
 	}
 
-	const currentMaxSubagentDepth = resolveCurrentMaxSubagentDepth(deps.config.maxSubagentDepth);
+	const depthPolicy = resolveSubagentDepthPolicy(ctx, deps.config.maxSubagentDepth);
+	const currentMaxSubagentDepth = depthPolicy.maxSubagentDepth;
+	const workflowStageSubagentGuard = depthPolicy.workflowStageSubagentGuard;
 	const maxSubagentDepths = agentConfigs.map((config) =>
 		resolveChildMaxSubagentDepth(currentMaxSubagentDepth, config.maxSubagentDepth),
 	);
@@ -1658,7 +1713,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 		}
 
 		if (result.runInBackground) {
-			if (!isAsyncAvailable()) {
+			if (!deps.runtime.isAsyncAvailable()) {
 				return {
 					content: [{ type: "text", text: `Background mode requires upstream jiti for TypeScript execution but it could not be found. Ensure the ${APP_NAME}-subagents package dependencies are installed.` }],
 					isError: true,
@@ -1688,7 +1743,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 					...(progress !== undefined ? { progress } : {}),
 				};
 			});
-			return executeAsyncChain(id, {
+			return deps.runtime.executeAsyncChain(id, {
 				chain: [{ parallel: parallelTasks, concurrency: parallelConcurrency, worktree: params.worktree }],
 				resultMode: "parallel",
 				agents,
@@ -1703,6 +1758,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 				chainSkills: [],
 				sessionFilesByFlatIndex: tasks.map((_, index) => sessionFileForIndex(index)),
 				maxSubagentDepth: currentMaxSubagentDepth,
+				workflowStageSubagentGuard,
 				worktreeSetupHook: deps.config.worktreeSetupHook,
 				worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
 				controlConfig,
@@ -1767,6 +1823,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			artifactsDir,
 			maxOutput: params.maxOutput,
 			paramsCwd: effectiveCwd,
+			workflowStageSubagentGuard,
 			availableModels,
 			modelOverrides,
 			behaviors,
@@ -1782,6 +1839,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			liveProgress,
 			onUpdate,
 			worktreeSetup,
+			runtime: deps.runtime,
 		});
 		for (let i = 0; i < results.length; i++) {
 			const run = results[i]!;
@@ -1860,7 +1918,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 	}
 }
 
-async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Promise<AgentToolResult<Details>> {
+async function runSinglePath(data: ExecutionContextData, deps: ResolvedExecutorDeps): Promise<SubagentToolResult> {
 	const {
 		params,
 		effectiveCwd,
@@ -1902,7 +1960,9 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	const rawOutput = params.output !== undefined ? params.output : agentConfig.output;
 	let effectiveOutput = normalizeSingleOutputOverride(rawOutput, agentConfig.output);
 	const effectiveOutputMode = params.outputMode ?? "inline";
-	const currentMaxSubagentDepth = resolveCurrentMaxSubagentDepth(deps.config.maxSubagentDepth);
+	const depthPolicy = resolveSubagentDepthPolicy(ctx, deps.config.maxSubagentDepth);
+	const currentMaxSubagentDepth = depthPolicy.maxSubagentDepth;
+	const workflowStageSubagentGuard = depthPolicy.workflowStageSubagentGuard;
 	const maxSubagentDepth = resolveChildMaxSubagentDepth(currentMaxSubagentDepth, agentConfig.maxSubagentDepth);
 
 	if (params.clarify === true && ctx.hasUI) {
@@ -1938,7 +1998,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		if (override?.skills !== undefined) skillOverride = override.skills;
 
 		if (result.runInBackground) {
-			if (!isAsyncAvailable()) {
+			if (!deps.runtime.isAsyncAvailable()) {
 				return {
 					content: [{ type: "text", text: `Background mode requires upstream jiti for TypeScript execution but it could not be found. Ensure the ${APP_NAME}-subagents package dependencies are installed.` }],
 					isError: true,
@@ -1953,7 +2013,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 				currentModelProvider: ctx.model?.provider,
 				currentModel: currentModelFullId(ctx.model),
 			};
-			return executeAsyncSingle(id, {
+			return deps.runtime.executeAsyncSingle(id, {
 				agent: params.agent!,
 				task: params.context === "fork" ? wrapForkTask(task) : task,
 				agentConfig,
@@ -1971,6 +2031,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 				outputMode: effectiveOutputMode,
 				modelOverride,
 				maxSubagentDepth,
+				workflowStageSubagentGuard,
 				worktreeSetupHook: deps.config.worktreeSetupHook,
 				worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
 				controlConfig,
@@ -2014,7 +2075,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	}
 
 	const forwardSingleUpdate = onUpdate
-		? (update: AgentToolResult<Details>) => {
+		? (update: SubagentToolResult) => {
 			if (foregroundControl) {
 				const firstProgress = update.details?.progress?.[0];
 				foregroundControl.currentAgent = params.agent;
@@ -2033,7 +2094,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		}
 		: undefined;
 
-	const r = await runSync(ctx.cwd, agents, params.agent!, task, {
+	const r = await deps.runtime.runSync(ctx.cwd, agents, params.agent!, task, {
 		cwd: effectiveCwd,
 		signal,
 		interruptSignal: interruptController.signal,
@@ -2049,6 +2110,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		outputPath,
 		outputMode: effectiveOutputMode,
 		maxSubagentDepth,
+		workflowStageSubagentGuard,
 		onUpdate: forwardSingleUpdate,
 		controlConfig,
 		onControlEvent,
@@ -2145,22 +2207,23 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	};
 }
 
-export function createSubagentExecutor(deps: ExecutorDeps): {
+export function createSubagentExecutor(rawDeps: ExecutorDeps): {
 	execute: (
 		id: string,
 		params: SubagentParamsLike,
 		signal: AbortSignal,
-		onUpdate: ((r: AgentToolResult<Details>) => void) | undefined,
+		onUpdate: ((r: SubagentToolResult) => void) | undefined,
 		ctx: ExtensionContext,
-	) => Promise<AgentToolResult<Details>>;
+	) => Promise<SubagentToolResult>;
 } {
+	const deps: ResolvedExecutorDeps = { ...rawDeps, runtime: resolveSubagentExecutorRuntimeDeps(rawDeps.runtime) };
 	const execute = async (
 		_id: string,
 		params: SubagentParamsLike,
 		signal: AbortSignal,
-		onUpdate: ((r: AgentToolResult<Details>) => void) | undefined,
+		onUpdate: ((r: SubagentToolResult) => void) | undefined,
 		ctx: ExtensionContext,
-	): Promise<AgentToolResult<Details>> => {
+	): Promise<SubagentToolResult> => {
 		deps.state.baseCwd = ctx.cwd;
 		deps.state.foregroundRuns ??= new Map();
 		deps.state.foregroundControls ??= new Map();
@@ -2219,7 +2282,12 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 					const foreground = getForegroundControl(deps.state, undefined);
 					if (foreground) return foregroundStatusResult(foreground);
 				}
-				return inspectSubagentStatus(paramsWithResolvedCwd, { state: deps.state, nested: nestedResolutionScopeForExecutor(deps) });
+				return inspectSubagentStatus({
+					action: "status",
+					id: paramsWithResolvedCwd.id,
+					runId: paramsWithResolvedCwd.runId,
+					dir: paramsWithResolvedCwd.dir,
+				}, { state: deps.state, nested: nestedResolutionScopeForExecutor(deps) });
 			}
 			if (params.action === "resume") {
 				return resumeAsyncRun({ params: paramsWithResolvedCwd, requestCwd, ctx, deps });
@@ -2278,16 +2346,15 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 			return handleManagementAction(params.action, paramsWithResolvedCwd, { ...ctx, cwd: requestCwd });
 		}
 
-		const { blocked, depth, maxDepth } = checkSubagentDepth(deps.config.maxSubagentDepth);
+		const depthPolicy = resolveSubagentDepthPolicy(ctx, deps.config.maxSubagentDepth);
+		const { blocked, depth, maxDepth, workflowStageGuard } = checkSubagentDepth(depthPolicy.maxSubagentDepth);
+		const workflowStageSubagentGuard = workflowStageGuard || depthPolicy.workflowStageSubagentGuard;
 		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.",
+						text: subagentDepthBlockedMessage(depth, maxDepth, { workflowStageGuard: workflowStageSubagentGuard }),
 					},
 				],
 				isError: true,
@@ -2385,7 +2452,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 			sessionFileForIndex(idx) ?? path.join(sessionDirForIndex(idx), "session.jsonl");
 
 		const onUpdateWithContext = onUpdate
-			? (r: AgentToolResult<Details>) => onUpdate(withForkContext(r, effectiveParams.context))
+			? (r: SubagentToolResult) => onUpdate(withForkContext(r, effectiveParams.context))
 			: undefined;
 
 		const execData: ExecutionContextData = {
@@ -2428,7 +2495,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 			deps.state.lastForegroundControlId = runId;
 		}
 
-		const writeNestedForegroundEvent = (type: "subagent.nested.started" | "subagent.nested.completed", result?: AgentToolResult<Details>): void => {
+		const writeNestedForegroundEvent = (type: "subagent.nested.started" | "subagent.nested.completed", result?: SubagentToolResult): void => {
 			if (!inheritedNestedRoute || !nestedParentAddress) return;
 			const now = Date.now();
 			const details = result?.details;