pi-subagents 0.29.0 → 0.30.0

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

@@ -31,7 +31,9 @@ import {
 	type StepOverrides,
 } from "../../shared/settings.ts";
 import { discoverAvailableSkills, normalizeSkillInput } from "../../agents/skills.ts";
-import { executeAsyncChain, executeAsyncSingle, formatAsyncStartedMessage, isAsyncAvailable } from "../background/async-execution.ts";
+import { buildAsyncRunnerSteps, executeAsyncChain, executeAsyncSingle, formatAsyncStartedMessage, isAsyncAvailable } from "../background/async-execution.ts";
+import { enqueueChainAppendRequest, readPendingChainAppendRequests, runnerStepOutputNames } from "../background/chain-append.ts";
+import { ChainOutputValidationError, validateChainOutputBindingsWithContext } from "../shared/chain-outputs.ts";
 import { createForkContextResolver } from "../../shared/fork-context.ts";
 import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
 import { applyIntercomBridgeToAgent, INTERCOM_BRIDGE_MARKER, resolveIntercomBridge, resolveIntercomSessionTarget, resolveSubagentIntercomTarget, type IntercomBridgeState } from "../../intercom/intercom-bridge.ts";
@@ -47,7 +49,8 @@ import {
 	resolveSubagentResultStatus,
 	stripDetailsOutputsForIntercomReceipt,
 } from "../../intercom/result-intercom.ts";
-import { buildRevivedAsyncTask, resolveAsyncResumeTarget } from "../background/async-resume.ts";
+import { buildRevivedAsyncTask, interruptLiveAsyncResumeTarget, resolveAsyncResumeTarget } from "../background/async-resume.ts";
+import { resolveAsyncRootResultPath } from "../background/chain-root-attachment.ts";
 import { createNestedRoute, readNestedControlResults, resolveInheritedNestedRouteFromEnv, resolveNestedAsyncDir, resolveNestedParentAddressFromEnv, updateForegroundNestedProjection, writeNestedControlRequest, writeNestedEvent, type NestedRunResolutionScope } from "../shared/nested-events.ts";
 import { resolveSubagentRunId, type ResolvedSubagentRunId } from "../background/run-id-resolver.ts";
 import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
@@ -79,7 +82,9 @@ import {
 	type SingleResult,
 	type SubagentRunMode,
 	type SubagentState,
+	ASYNC_DIR,
 	DEFAULT_ARTIFACT_CONFIG,
+	RESULTS_DIR,
 	SUBAGENT_ACTIONS,
 	SUBAGENT_CONTROL_EVENT,
 	SUBAGENT_CONTROL_INTERCOM_EVENT,
@@ -150,6 +155,7 @@ interface ExecutorDeps {
 	expandTilde: (p: string) => string;
 	discoverAgents: (cwd: string, scope: AgentScope) => { agents: AgentConfig[] };
 	allowMutatingManagementActions?: boolean;
+	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 }
 
 interface ExecutionContextData {
@@ -317,7 +323,7 @@ function isExactResumeError(error: unknown, source: "async" | "foreground", requ
 	return new RegExp(`\\b${source} run '${escapeRegExp(requested)}'`, "i").test(error.message);
 }
 
-function resolveResumeTarget(params: SubagentParamsLike, state: SubagentState): ResumeSourceTarget {
+function resolveResumeTarget(params: SubagentParamsLike, state: SubagentState, options: { asyncRequireSessionFile?: boolean } = {}): ResumeSourceTarget {
 	const requested = (params.id ?? params.runId)?.trim() ?? "";
 	let foregroundTarget: ForegroundResumeSourceTarget | undefined;
 	let foregroundError: unknown;
@@ -331,7 +337,7 @@ function resolveResumeTarget(params: SubagentParamsLike, state: SubagentState):
 		foregroundError = error;
 	}
 	try {
-		asyncTarget = { source: "async", ...resolveAsyncResumeTarget(params) };
+		asyncTarget = { source: "async", ...resolveAsyncResumeTarget(params, {}, { requireSessionFile: options.asyncRequireSessionFile }) };
 	} catch (error) {
 		asyncError = error;
 	}
@@ -402,7 +408,7 @@ function emitControlNotification(input: {
 	}
 }
 
-function interruptAsyncRun(state: SubagentState, runId: string | undefined): AgentToolResult<Details> | null {
+function interruptAsyncRun(state: SubagentState, runId: string | undefined, kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean): AgentToolResult<Details> | null {
 	const target = getAsyncInterruptTarget(state, runId);
 	if (!target) return null;
 	const status = readStatus(target.asyncDir);
@@ -414,7 +420,7 @@ function interruptAsyncRun(state: SubagentState, runId: string | undefined): Age
 		};
 	}
 	try {
-		process.kill(status.pid, ASYNC_INTERRUPT_SIGNAL);
+		(kill ?? process.kill)(status.pid, ASYNC_INTERRUPT_SIGNAL);
 		const tracked = state.asyncJobs.get(target.asyncId);
 		if (tracked) {
 			tracked.activityState = undefined;
@@ -434,6 +440,186 @@ function interruptAsyncRun(state: SubagentState, runId: string | undefined): Age
 	}
 }
 
+function duplicateNames(names: string[]): string[] {
+	const seen = new Set<string>();
+	const duplicates = new Set<string>();
+	for (const name of names) {
+		if (seen.has(name)) duplicates.add(name);
+		else seen.add(name);
+	}
+	return [...duplicates];
+}
+
+function appendStepToAsyncChain(input: {
+	params: SubagentParamsLike;
+	requestCwd: string;
+	ctx: ExtensionContext;
+	deps: ExecutorDeps;
+}): AgentToolResult<Details> {
+	const targetRunId = input.params.id ?? input.params.runId;
+	if (!targetRunId) {
+		return {
+			content: [{ type: "text", text: "action='append-step' requires id." }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+	if (!input.params.chain || input.params.chain.length !== 1) {
+		return {
+			content: [{ type: "text", text: "action='append-step' requires chain with exactly one step." }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+
+	let resolved: ResolvedSubagentRunId | undefined;
+	try {
+		resolved = resolveSubagentRunId(targetRunId, { state: input.deps.state, nested: nestedResolutionScopeForExecutor(input.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) {
+		return {
+			content: [{ type: "text", text: `No async chain run found for '${targetRunId}'.` }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+	if (resolved.kind !== "async" || !resolved.location.asyncDir) {
+		return {
+			content: [{ type: "text", text: `Run '${resolved.id}' is not an append-capable async chain run.` }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+
+	const status = readStatus(resolved.location.asyncDir);
+	if (!status) {
+		return {
+			content: [{ type: "text", text: `No async run status found for '${resolved.id}'.` }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+	if (status.mode !== "chain") {
+		return {
+			content: [{ type: "text", text: `Run '${resolved.id}' is ${status.mode}; only active chain runs accept appended steps.` }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+	if (status.state !== "running") {
+		return {
+			content: [{ type: "text", text: `Run '${resolved.id}' is ${status.state}; only running chain runs accept appended steps.` }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+	const stillInProgress = (status.steps ?? []).some((step) => step.status === "running" || step.status === "pending") || (status.pendingAppends ?? 0) > 0;
+	if (!stillInProgress) {
+		return {
+			content: [{ type: "text", text: `Run '${resolved.id}' has no running or pending chain steps left; append-step must target an in-progress chain.` }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+
+	const pendingAppendRequests = readPendingChainAppendRequests(resolved.location.asyncDir);
+	const reservedOutputNames = new Set<string>([
+		...Object.keys(status.outputs ?? {}),
+		...(status.steps ?? []).map((step) => step.outputName).filter((name): name is string => Boolean(name)),
+		...pendingAppendRequests.flatMap((request) => runnerStepOutputNames(request.steps)),
+	]);
+	try {
+		validateChainOutputBindingsWithContext(input.params.chain, { maxItems: input.deps.config.chain?.dynamicFanout?.maxItems }, {
+			priorOutputNames: reservedOutputNames,
+			startStepIndex: status.chainStepCount ?? status.steps?.length ?? 0,
+		});
+	} catch (error) {
+		if (!(error instanceof ChainOutputValidationError)) throw error;
+		return {
+			content: [{ type: "text", text: `Cannot append step to run '${resolved.id}': ${error.message}` }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+
+	const scope: AgentScope = resolveExecutionAgentScope(input.params.agentScope);
+	const agents = input.deps.discoverAgents(input.requestCwd, scope).agents;
+	const chainSkillInput = normalizeSkillInput(input.params.skill);
+	const chainSkills = chainSkillInput === false ? [] : (chainSkillInput ?? []);
+	const asyncCtx = {
+		pi: input.deps.pi,
+		cwd: input.ctx.cwd,
+		currentSessionId: resolveCurrentSessionId(input.ctx.sessionManager),
+		currentModelProvider: input.ctx.model?.provider,
+		currentModel: input.ctx.model,
+	};
+	const built = buildAsyncRunnerSteps(resolved.id, {
+		chain: wrapChainTasksForFork(input.params.chain, input.params.context),
+		task: input.params.task,
+		resultMode: "chain",
+		agents,
+		ctx: asyncCtx,
+		availableModels: input.ctx.modelRegistry.getAvailable().map(toModelInfo),
+		cwd: status.cwd ?? input.requestCwd,
+		chainSkills,
+		dynamicFanoutMaxItems: input.deps.config.chain?.dynamicFanout?.maxItems,
+		maxSubagentDepth: resolveCurrentMaxSubagentDepth(input.deps.config.maxSubagentDepth),
+		asyncDir: resolved.location.asyncDir,
+		validateOutputBindings: false,
+	});
+	if ("error" in built) {
+		return {
+			content: [{ type: "text", text: built.error }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+	const appendedOutputNames = runnerStepOutputNames(built.steps);
+	const duplicateAppendedOutputs = duplicateNames(appendedOutputNames);
+	if (duplicateAppendedOutputs.length > 0) {
+		return {
+			content: [{ type: "text", text: `Cannot append step to run '${resolved.id}': duplicate output name in appended step: ${duplicateAppendedOutputs.join(", ")}.` }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+	const pendingOutputNames = new Set(pendingAppendRequests.flatMap((request) => runnerStepOutputNames(request.steps)));
+	const pendingDuplicateOutputs = appendedOutputNames.filter((name) => pendingOutputNames.has(name));
+	if (pendingDuplicateOutputs.length > 0) {
+		return {
+			content: [{ type: "text", text: `Cannot append step to run '${resolved.id}': output name already belongs to a pending append: ${pendingDuplicateOutputs.join(", ")}.` }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+
+	try {
+		const result = enqueueChainAppendRequest({
+			asyncDir: resolved.location.asyncDir,
+			runId: resolved.id,
+			steps: built.steps,
+		});
+		const stepText = built.steps.length === 1 ? "step" : "steps";
+		return {
+			content: [{
+				type: "text",
+				text: `Append queued for chain run ${resolved.id}: ${built.steps.length} ${stepText}. It becomes eligible after the chain's already-queued steps finish. Pending appends: ${result.pendingCount}.`,
+			}],
+			details: { mode: "management", results: [], asyncId: resolved.id, asyncDir: resolved.location.asyncDir },
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return {
+			content: [{ type: "text", text: `Failed to append step to chain run ${resolved.id}: ${message}` }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+}
+
 function nestedRunSessionFile(run: NestedRunSummary): string | undefined {
 	return run.sessionFile ?? (run.steps?.length === 1 ? run.steps[0]?.sessionFile : undefined);
 }
@@ -554,7 +740,8 @@ async function resumeAsyncRun(input: {
 	deps: ExecutorDeps;
 }): Promise<AgentToolResult<Details>> {
 	const followUp = (input.params.message ?? input.params.task ?? "").trim();
-	if (!followUp) {
+	const attachChain = (input.params.chain?.length ?? 0) > 0 ? input.params.chain as ChainStep[] : undefined;
+	if (!followUp && !attachChain) {
 		return {
 			content: [{ type: "text", text: "action='resume' requires message." }],
 			isError: true,
@@ -568,6 +755,13 @@ async function resumeAsyncRun(input: {
 		const requestedId = input.params.id ?? input.params.runId;
 		const resolved = requestedId ? resolveSubagentRunId(requestedId, { state: input.deps.state, nested: nestedResolutionScopeForExecutor(input.deps) }) : undefined;
 		if (resolved?.kind === "nested") {
+			if (attachChain) {
+				return {
+					content: [{ type: "text", text: "Attaching a running subagent as a chain root is currently available for top-level async runs only." }],
+					isError: true,
+					details: { mode: "management", results: [] },
+				};
+			}
 			if (resolved.match.run.state === "running" || resolved.match.run.state === "queued") {
 				return resumeLiveNestedRun({ target: resolved, message: followUp });
 			}
@@ -577,14 +771,26 @@ async function resumeAsyncRun(input: {
 			];
 			target = resolveNestedResumeTarget(resolved, trustedSessionRoots);
 		} else {
-			target = resolveResumeTarget(input.params, input.deps.state);
+			target = resolveResumeTarget(input.params, input.deps.state, { asyncRequireSessionFile: !attachChain });
 		}
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		return { content: [{ type: "text", text: message }], isError: true, details: { mode: "management", results: [] } };
 	}
 
-	if (target.kind === "live") {
+	if (target.kind === "live" && !attachChain) {
+		const interrupt = interruptLiveAsyncResumeTarget({
+			target,
+			state: input.deps.state,
+			kill: input.deps.kill,
+		});
+		if (!interrupt.ok) {
+			return {
+				content: [{ type: "text", text: interrupt.message }],
+				isError: true,
+				details: { mode: "management", results: [] },
+			};
+		}
 		const delivered = await deliverSubagentIntercomMessageEvent(
 			input.deps.pi.events,
 			target.intercomTarget,
@@ -594,7 +800,7 @@ async function resumeAsyncRun(input: {
 		);
 		if (delivered) {
 			return {
-				content: [{ type: "text", text: [`Delivered follow-up to live async child.`, `Run: ${target.runId}`, `Intercom target: ${target.intercomTarget}`].join("\n") }],
+				content: [{ type: "text", text: [`Interrupted live async child, then delivered follow-up.`, `Run: ${target.runId}`, `Intercom target: ${target.intercomTarget}`].join("\n") }],
 				details: { mode: "management", results: [] },
 			};
 		}
@@ -637,6 +843,73 @@ async function resumeAsyncRun(input: {
 		};
 	}
 
+	if (attachChain) {
+		if (target.source !== "async") {
+			return {
+				content: [{ type: "text", text: "Attaching a running subagent as a chain root is currently available for async runs only." }],
+				isError: true,
+				details: { mode: "management", results: [] },
+			};
+		}
+		if (!isAsyncAvailable()) {
+			return {
+				content: [{ type: "text", text: "Async mode requires upstream jiti for TypeScript execution but it could not be found. Ensure the pi-subagents package dependencies are installed." }],
+				isError: true,
+				details: { mode: "chain", results: [] },
+			};
+		}
+		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 chain = wrapChainTasksForFork(attachChain, input.params.context);
+		const normalized = normalizeSkillInput(input.params.skill);
+		const result = executeAsyncChain(runId, {
+			chain,
+			task: (input.params.task ?? followUp) || undefined,
+			attachRoot: {
+				runId: target.runId,
+				asyncDir: target.asyncDir ?? path.join(ASYNC_DIR, target.runId),
+				resultPath: resolveAsyncRootResultPath(RESULTS_DIR, target.runId),
+				index: target.index,
+				agent: target.agent,
+				label: `Attached ${target.runId}`,
+			},
+			agents,
+			ctx: {
+				pi: input.deps.pi,
+				cwd: input.requestCwd,
+				currentSessionId: input.deps.state.currentSessionId,
+				currentModelProvider: input.ctx.model?.provider,
+				currentModel: input.ctx.model,
+			},
+			availableModels,
+			cwd: effectiveCwd,
+			maxOutput: input.params.maxOutput,
+			artifactsDir: input.deps.tempArtifactsDir,
+			artifactConfig,
+			shareEnabled: input.params.share === true,
+			sessionRoot: input.deps.getSubagentSessionRoot(parentSessionFile),
+			chainSkills: normalized === false ? [] : (normalized ?? []),
+			dynamicFanoutMaxItems: input.deps.config.chain?.dynamicFanout?.maxItems,
+			maxSubagentDepth: resolveCurrentMaxSubagentDepth(input.deps.config.maxSubagentDepth),
+			worktreeSetupHook: input.deps.config.worktreeSetupHook,
+			worktreeSetupHookTimeoutMs: input.deps.config.worktreeSetupHookTimeoutMs,
+			controlConfig: resolveControlConfig(input.deps.config.control, input.params.control),
+			controlIntercomTarget: intercomBridge.active ? intercomBridge.orchestratorTarget : undefined,
+			childIntercomTarget: intercomBridge.active ? (agent, index) => resolveSubagentIntercomTarget(runId, agent, index) : undefined,
+		});
+		if (result.isError) return result;
+		const attachedId = result.details.asyncId ?? runId;
+		const lines = [
+			`Attached async subagent ${target.runId} as the first step of a new chain.`,
+			`Chain run: ${attachedId}`,
+			`Root: ${target.agent} (step ${target.index + 1})`,
+			result.details.asyncDir ? `Async dir: ${result.details.asyncDir}` : undefined,
+			`Status if needed: subagent({ action: "status", id: "${attachedId}" })`,
+		].filter((line): line is string => Boolean(line));
+		return { content: [{ type: "text", text: formatAsyncStartedMessage(lines.join("\n")) }], details: result.details };
+	}
+
 	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);
@@ -2268,6 +2541,9 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 			if (params.action === "resume") {
 				return resumeAsyncRun({ params: paramsWithResolvedCwd, requestCwd, ctx, deps });
 			}
+			if (params.action === "append-step") {
+				return appendStepToAsyncChain({ params: paramsWithResolvedCwd, requestCwd, ctx, deps });
+			}
 			if (params.action === "interrupt") {
 				const targetRunId = paramsWithResolvedCwd.runId ?? paramsWithResolvedCwd.id;
 				let resolved: ResolvedSubagentRunId | undefined;
@@ -2297,7 +2573,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 						details: { mode: "management", results: [] },
 					};
 				}
-				const asyncInterruptResult = interruptAsyncRun(deps.state, resolved?.kind === "async" ? resolved.id : targetRunId);
+				const asyncInterruptResult = interruptAsyncRun(deps.state, resolved?.kind === "async" ? resolved.id : targetRunId, deps.kill);
 				if (asyncInterruptResult) return asyncInterruptResult;
 				return {
 					content: [{ type: "text", text: "No interrupt-capable run found in this session." }],
@@ -2319,7 +2595,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 					details: { mode: "management" as const, results: [] },
 				};
 			}
-			return handleManagementAction(params.action, paramsWithResolvedCwd, { ...ctx, cwd: requestCwd });
+			return handleManagementAction(params.action, paramsWithResolvedCwd, { ...ctx, cwd: requestCwd, config: deps.config });
 		}
 
 		const { blocked, depth, maxDepth } = checkSubagentDepth(deps.config.maxSubagentDepth);

package/src/runs/shared/chain-outputs.ts

@@ -8,6 +8,11 @@ const SAFE_OUTPUT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
 export class ChainOutputValidationError extends Error {}
 
+export interface ChainOutputValidationContext {
+	priorOutputNames?: Iterable<string>;
+	startStepIndex?: number;
+}
+
 function outputNamesForStep(step: ChainStep): string[] {
 	if (isParallelStep(step)) return step.parallel.map((task) => task.as).filter((name): name is string => Boolean(name));
 	if (isDynamicParallelStep(step)) return [step.collect.as];
@@ -22,27 +27,37 @@ function taskTemplatesForStep(step: ChainStep): string[] {
 }
 
 export function validateChainOutputBindings(steps: ChainStep[], dynamicFanoutConfig: DynamicFanoutConfig = {}): void {
-	const available = new Set<string>();
-	const seen = new Set<string>();
+	validateChainOutputBindingsWithContext(steps, dynamicFanoutConfig);
+}
+
+export function validateChainOutputBindingsWithContext(
+	steps: ChainStep[],
+	dynamicFanoutConfig: DynamicFanoutConfig = {},
+	context: ChainOutputValidationContext = {},
+): void {
+	const priorOutputNames = [...(context.priorOutputNames ?? [])];
+	const available = new Set<string>(priorOutputNames);
+	const seen = new Set<string>(priorOutputNames);
 	for (let stepIndex = 0; stepIndex < steps.length; stepIndex++) {
+		const displayStepIndex = (context.startStepIndex ?? 0) + stepIndex + 1;
 		const step = steps[stepIndex]!;
 		if (hasDynamicFanoutFields(step)) {
 			if (!isDynamicParallelStep(step)) {
-				throw new ChainOutputValidationError(`Dynamic chain step ${stepIndex + 1} requires expand, a single parallel template object, and collect; dynamic expand/collect cannot be mixed with static parallel arrays.`);
+				throw new ChainOutputValidationError(`Dynamic chain step ${displayStepIndex} requires expand, a single parallel template object, and collect; dynamic expand/collect cannot be mixed with static parallel arrays.`);
 			}
 			try {
-				validateDynamicStepShape(step, stepIndex, dynamicFanoutConfig);
+				validateDynamicStepShape(step, displayStepIndex - 1, dynamicFanoutConfig);
 			} catch (error) {
 				if (error instanceof DynamicFanoutError) throw new ChainOutputValidationError(error.message);
 				throw error;
 			}
 			if (!available.has(step.expand.from.output)) {
-				throw new ChainOutputValidationError(`Dynamic chain step ${stepIndex + 1} references unknown output '${step.expand.from.output}'. Named outputs are only available after producing step/group completes.`);
+				throw new ChainOutputValidationError(`Dynamic chain step ${displayStepIndex} references unknown output '${step.expand.from.output}'. Named outputs are only available after producing step/group completes.`);
 			}
 		}
 		for (const name of outputNamesForStep(step)) {
 			if (!SAFE_OUTPUT_NAME_PATTERN.test(name)) {
-				throw new ChainOutputValidationError(`Invalid chain output name '${name}' at step ${stepIndex + 1}. Use /^[A-Za-z_][A-Za-z0-9_]*$/.`);
+				throw new ChainOutputValidationError(`Invalid chain output name '${name}' at step ${displayStepIndex}. Use /^[A-Za-z_][A-Za-z0-9_]*$/.`);
 			}
 			if (seen.has(name)) {
 				throw new ChainOutputValidationError(`Duplicate chain output name '${name}'. Each as name must be unique.`);
@@ -54,10 +69,10 @@ export function validateChainOutputBindings(steps: ChainStep[], dynamicFanoutCon
 				const rawReference = match[0];
 				const name = match[1]!;
 				if (!SAFE_OUTPUT_NAME_PATTERN.test(name)) {
-					throw new ChainOutputValidationError(`Invalid chain output reference '${rawReference}' at step ${stepIndex + 1}. Use {outputs.name} with /^[A-Za-z_][A-Za-z0-9_]*$/ names.`);
+					throw new ChainOutputValidationError(`Invalid chain output reference '${rawReference}' at step ${displayStepIndex}. Use {outputs.name} with /^[A-Za-z_][A-Za-z0-9_]*$/ names.`);
 				}
 				if (!available.has(name)) {
-					throw new ChainOutputValidationError(`Unknown chain output reference '${rawReference}' at step ${stepIndex + 1}. Named outputs are only available after producing step/group completes.`);
+					throw new ChainOutputValidationError(`Unknown chain output reference '${rawReference}' at step ${displayStepIndex}. Named outputs are only available after producing step/group completes.`);
 				}
 			}
 		}

package/src/runs/shared/dynamic-fanout.ts

@@ -48,7 +48,7 @@ const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outpu
 const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
 	...DYNAMIC_PARALLEL_KEYS,
 	"outputName", "structured", "inheritProjectContext", "inheritSkills", "skills", "outputPath", "maxSubagentDepth",
-	"structuredOutput", "structuredOutputSchema", "tools", "extensions", "mcpDirectTools", "completionGuard", "systemPrompt",
+	"structuredOutput", "structuredOutputSchema", "tools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "completionGuard", "systemPrompt",
 	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance",
 ]);
 const DYNAMIC_COLLECT_KEYS = new Set(["as", "outputSchema"]);

package/src/runs/shared/parallel-utils.ts

@@ -1,6 +1,12 @@
 export interface RunnerSubagentStep {
 	agent: string;
 	task: string;
+	importAsyncRoot?: {
+		runId: string;
+		asyncDir: string;
+		resultPath: string;
+		index: number;
+	};
 	phase?: string;
 	label?: string;
 	outputName?: string;
@@ -11,6 +17,7 @@ export interface RunnerSubagentStep {
 	modelCandidates?: string[];
 	tools?: string[];
 	extensions?: string[];
+	subagentOnlyExtensions?: string[];
 	mcpDirectTools?: string[];
 	completionGuard?: boolean;
 	systemPrompt?: string | null;

package/src/runs/shared/pi-args.ts

@@ -39,6 +39,7 @@ interface BuildPiArgsInput {
 	inheritSkills: boolean;
 	tools?: string[];
 	extensions?: string[];
+	subagentOnlyExtensions?: string[];
 	systemPrompt?: string | null;
 	mcpDirectTools?: string[];
 	cwd?: string;
@@ -120,11 +121,11 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 		: [PROMPT_RUNTIME_EXTENSION_PATH];
 	if (input.extensions !== undefined) {
 		args.push("--no-extensions");
-		for (const extPath of [...new Set([...runtimeExtensions, ...toolExtensionPaths, ...input.extensions])]) {
+		for (const extPath of [...new Set([...runtimeExtensions, ...toolExtensionPaths, ...input.extensions, ...(input.subagentOnlyExtensions ?? [])])]) {
 			args.push("--extension", extPath);
 		}
 	} else {
-		for (const extPath of [...new Set([...runtimeExtensions, ...toolExtensionPaths])]) {
+		for (const extPath of [...new Set([...runtimeExtensions, ...toolExtensionPaths, ...(input.subagentOnlyExtensions ?? [])])]) {
 			args.push("--extension", extPath);
 		}
 	}

package/src/runs/shared/subagent-control.ts

@@ -173,9 +173,8 @@ export function formatControlNoticeMessage(event: ControlEvent, childIntercomTar
 		].filter((line): line is string => Boolean(line)).join("\n");
 	}
 
-	const nudgeCommand = childIntercomTarget
-		? `intercom({ action: "send", to: "${childIntercomTarget}", message: "What are you blocked on? Reply with the smallest next step or ask for a decision." })`
-		: undefined;
+	const nudgeMessage = "What are you blocked on? Reply with the smallest next step or ask for a decision.";
+	const nudgeCommand = `subagent({ action: "resume", id: "${runTarget}", ${event.index !== undefined ? `index: ${event.index}, ` : ""}message: "${nudgeMessage}" })`;
 	if (event.type === "active_long_running") {
 		const facts = formatLongRunningFacts(event);
 		return [
@@ -183,10 +182,9 @@ export function formatControlNoticeMessage(event: ControlEvent, childIntercomTar
 			`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
 			`Signal: ${event.message}`,
 			facts ? `Facts: ${facts}` : undefined,
-			"Hint: Inspect status, then nudge if the work seems stuck.",
-			childIntercomTarget
-				? `Nudge: ${nudgeCommand}`
-				: "Nudge: no child message route registered",
+			"Hint: Inspect status, then nudge if the work seems stuck. Live async nudges interrupt the child before sending the follow-up.",
+			`Nudge: ${nudgeCommand}`,
+			childIntercomTarget ? `Direct intercom target: ${childIntercomTarget}` : undefined,
 			`Status: subagent({ action: "status", id: "${runTarget}" })`,
 			`Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
 		].filter((line): line is string => Boolean(line)).join("\n");
@@ -197,10 +195,9 @@ export function formatControlNoticeMessage(event: ControlEvent, childIntercomTar
 		`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
 		`Signal: ${event.message}`,
 		event.recentFailureSummary ? `Recent failures: ${event.recentFailureSummary}` : undefined,
-		"Hint: Inspect status first unless the run is clearly blocked.",
-		childIntercomTarget
-			? `Nudge: ${nudgeCommand}`
-			: "Nudge: no child message route registered",
+		"Hint: Inspect status first unless the run is clearly blocked. Live async nudges interrupt the child before sending the follow-up.",
+		`Nudge: ${nudgeCommand}`,
+		childIntercomTarget ? `Direct intercom target: ${childIntercomTarget}` : undefined,
 		`Status: subagent({ action: "status", id: "${runTarget}" })`,
 		`Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
 	].filter((line): line is string => Boolean(line)).join("\n");

package/src/shared/types.ts

@@ -579,6 +579,7 @@ export interface AsyncStatus {
 	cwd?: string;
 	currentStep?: number;
 	chainStepCount?: number;
+	pendingAppends?: number;
 	parallelGroups?: AsyncParallelGroupStatus[];
 	workflowGraph?: WorkflowGraphSnapshot;
 	steps?: Array<{
@@ -815,6 +816,13 @@ interface ExtensionChainConfig {
 	};
 }
 
+export interface ProactiveSkillSubagentsConfig {
+	enabled?: boolean;
+	minReferences?: number;
+	maxRecommendations?: number;
+	preferredAgent?: string;
+}
+
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
 	forceTopLevelAsync?: boolean;
@@ -826,6 +834,7 @@ export interface ExtensionConfig {
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
 	intercomBridge?: IntercomBridgeConfig;
+	proactiveSkillSubagents?: ProactiveSkillSubagentsConfig | false;
 }
 
 // ============================================================================
@@ -916,7 +925,7 @@ export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
 export const POLL_INTERVAL_MS = 250;
 export const MAX_WIDGET_JOBS = 4;
 export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
-export const SUBAGENT_ACTIONS = ["list", "get", "create", "update", "delete", "status", "interrupt", "resume", "doctor"] as const;
+export const SUBAGENT_ACTIONS = ["list", "get", "create", "update", "delete", "status", "interrupt", "resume", "append-step", "doctor"] as const;
 
 export const DEFAULT_FORK_PREAMBLE =
 	"You are a delegated subagent running from a fork of the parent session. " +

package/src/slash/slash-bridge.ts

@@ -13,6 +13,8 @@ import {
 interface SlashSubagentRequest {
 	requestId: string;
 	params: SubagentParamsLike;
+	/** Optional requester context for in-process extension bridge calls. */
+	ctx?: ExtensionContext;
 }
 
 export interface SlashSubagentResponse {
@@ -77,7 +79,7 @@ export function registerSlashSubagentBridge(options: SlashBridgeOptions): {
 		if (typeof request.requestId !== "string" || !request.params) return;
 		const { requestId, params } = request as SlashSubagentRequest;
 
-		const ctx = options.getContext();
+		const ctx = request.ctx ?? options.getContext();
 		if (!ctx) {
 			const response: SlashSubagentResponse = {
 				requestId,

package/src/slash/slash-commands.ts

@@ -245,7 +245,7 @@ async function requestSlashRun(
 			next();
 		};
 
-		pi.events.emit(SLASH_SUBAGENT_REQUEST_EVENT, { requestId, params });
+		pi.events.emit(SLASH_SUBAGENT_REQUEST_EVENT, { requestId, params, ctx });
 
 		// Bridge emits STARTED synchronously during REQUEST emit.
 		// If not started, no bridge received the request.