pi-subagents 0.64.0 → 0.65.1

package/src/runs/foreground/workflow-foreground-steering.ts

@@ -1,20 +1,10 @@
 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 type { Details, ForegroundRunControl, SubagentState } from "../../shared/types.ts";
 import { readStatus } from "../../shared/utils.ts";
 import { steeringReceipt } from "../background/steering.ts";
-import {
-	consumeSteerAckFromDir,
-	readSteerCapability,
-	steerAcksDir,
-	steerCapabilityPath,
-	stepSteerInboxDir,
-	writeSteerRequestToExistingDir,
-	type SteerDeliveryMode,
-	type SteerRequest,
-} from "../background/control-channel.ts";
+import type { SteerDeliveryMode } from "../background/control-channel.ts";
 
 export interface WorkflowForegroundSteeringTarget {
 	control: ForegroundRunControl;
@@ -40,7 +30,6 @@ function activeWorkflowError(state: SubagentState, workflowRunId: string, asyncD
 function controlIsLiveInWorkflow(control: ForegroundRunControl, workflowRunId: string, sessionId: string): boolean {
 	return control.parentWorkflowRunId === workflowRunId
 		&& control.sessionId === sessionId
-		&& Boolean(control.workflowSteeringDir)
 		&& (control.activeChildren?.size ?? 0) > 0;
 }
 
@@ -77,17 +66,18 @@ function managementError(message: string): AgentToolResult<Details> {
 	return { content: [{ type: "text", text: message }], isError: true, details: { mode: "management", results: [] } };
 }
 
+/**
+ * Steer a live workflow-owned foreground child through its in-process session.
+ * `steer` (and `auto`) interrupt the child at its next safe point; `follow_up`
+ * queues the message until the current run settles.
+ */
 export async function steerWorkflowForegroundTarget(input: {
 	target: WorkflowForegroundSteeringTarget;
 	message: string;
 	mode?: SteerDeliveryMode;
 	index?: number;
-	signal?: AbortSignal;
-	ackTimeoutMs?: number;
 }): Promise<AgentToolResult<Details>> {
 	const { control, sourceRunId } = input.target;
-	const routeDir = control.workflowSteeringDir;
-	if (!routeDir || !fs.existsSync(routeDir)) return managementError(`Foreground run '${control.runId}' has no live workflow steering route.`);
 	const activeIndexes = [...(control.activeChildren?.keys() ?? [])].sort((left, right) => left - right);
 	const index = input.index ?? (activeIndexes.length === 1 ? activeIndexes[0] : undefined);
 	if (index === undefined) {
@@ -95,94 +85,30 @@ export async function steerWorkflowForegroundTarget(input: {
 			? `Foreground run '${control.runId}' has no live child session.`
 			: `Foreground run '${control.runId}' has ${activeIndexes.length} live child sessions; provide index.`);
 	}
-	if (!activeIndexes.includes(index)) return managementError(`Foreground run '${control.runId}' child ${index} is not live.`);
-	const capability = readSteerCapability(routeDir, index);
-	if (capability?.supported === false) return managementError(`Foreground run '${control.runId}' child ${index} does not support steering.`);
+	const child = control.activeChildren?.get(index);
+	if (!child) return managementError(`Foreground run '${control.runId}' child ${index} is not live.`);
+	if (!child.steer) return managementError(`Foreground run '${control.runId}' child ${index} does not support steering.`);
 
-	const request: SteerRequest = {
-		type: "steer",
-		id: randomUUID(),
-		ts: Date.now(),
-		message: input.message.trim(),
-		...(input.mode && input.mode !== "steer" ? { mode: input.mode } : {}),
-		targetIndex: index,
-		source: "steer-action",
-	};
-	try {
-		writeSteerRequestToExistingDir(stepSteerInboxDir(routeDir, index), request);
-	} catch (error) {
-		if (typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") {
-			return managementError(`Foreground run '${control.runId}' has no live workflow steering route.`);
-		}
-		return managementError(`Failed to queue steering for foreground run ${control.runId}: ${error instanceof Error ? error.message : String(error)}`);
-	}
-
-	const deadline = Date.now() + (input.ackTimeoutMs ?? 3_000);
-	let ack;
-	let routeRemoved = false;
-	while (Date.now() <= deadline) {
-		ack = consumeSteerAckFromDir(steerAcksDir(routeDir, index), request.id);
-		if (ack || input.signal?.aborted) break;
-		if (!fs.existsSync(routeDir)) {
-			routeRemoved = true;
-			break;
-		}
-		await new Promise<void>((resolve) => setTimeout(resolve, Math.min(50, Math.max(1, deadline - Date.now()))));
-	}
-	if (routeRemoved || (!ack && !input.signal?.aborted && !fs.existsSync(routeDir))) {
-		return managementError(`Foreground run '${control.runId}' has no live child session.`);
-	}
-	const target = ack?.state === "delivered"
-		? { index, state: "delivered" as const, deliveredAt: ack.ts }
-		: ack?.state === "queued"
+	const message = input.message.trim();
+	const requestId = randomUUID();
+	const outcome = await child.steer({ message, ...(input.mode && input.mode !== "steer" ? { mode: input.mode } : {}) });
+	const target = outcome.state === "delivered"
+		? { index, state: "delivered" as const, deliveredAt: Date.now() }
+		: outcome.state === "queued"
 			? { index, state: "queued" as const }
-			: ack?.state === "failed"
-				? { index, state: "failed" as const, reason: ack.message }
-				: { index, state: "pending" as const };
+			: { index, state: "failed" as const, reason: outcome.reason };
 	const steering = {
-		requestId: request.id,
-		state: ack?.state === "delivered" ? "delivered" as const : ack?.state === "failed" ? "failed" as const : "pending" as const,
-		deliveryStatus: ack?.state === "delivered" ? "delivered" as const : "queued" as const,
+		requestId,
+		state: outcome.state === "delivered" ? "delivered" as const : outcome.state === "failed" ? "failed" as const : "pending" as const,
+		deliveryStatus: outcome.state === "delivered" ? "delivered" as const : "queued" as const,
 		sourceRunId,
 		targets: [target],
 	};
-	if (input.signal?.aborted) {
-		return { content: [{ type: "text", text: steeringReceipt(request.message, `Steering pending for foreground run ${control.runId} (request ${request.id}); caller aborted before acknowledgment.`) }], details: { mode: "management", results: [], steering } };
-	}
-	if (ack?.state === "delivered") {
-		return { content: [{ type: "text", text: steeringReceipt(request.message, `Steering delivered for foreground run ${control.runId} (request ${request.id}).`) }], details: { mode: "management", results: [], steering } };
-	}
-	if (ack?.state === "queued") {
-		return { content: [{ type: "text", text: steeringReceipt(request.message, `Steering queued for foreground run ${control.runId} (request ${request.id}).`) }], details: { mode: "management", results: [], steering } };
+	if (outcome.state === "delivered") {
+		return { content: [{ type: "text", text: steeringReceipt(message, `Steering delivered for foreground run ${control.runId} (request ${requestId}).`) }], details: { mode: "management", results: [], steering } };
 	}
-	if (ack?.state === "failed") {
-		return { content: [{ type: "text", text: steeringReceipt(request.message, `Steering failed for foreground run ${control.runId} (request ${request.id}): ${ack.message}`) }], isError: true, details: { mode: "management", results: [], steering } };
+	if (outcome.state === "queued") {
+		return { content: [{ type: "text", text: steeringReceipt(message, `Steering queued for foreground run ${control.runId} (request ${requestId}).`) }], details: { mode: "management", results: [], steering } };
 	}
-	return { content: [{ type: "text", text: steeringReceipt(request.message, `Steering pending for foreground run ${control.runId} (request ${request.id}); no acknowledgment was received.`) }], details: { mode: "management", results: [], steering } };
-}
-
-export function workflowForegroundSteeringDir(asyncDirRoot: string, workflowRunId: string, childRunId: string): string {
-	return path.join(asyncDirRoot, workflowRunId, "control", "workflow-foreground", childRunId);
-}
-
-export function removeWorkflowForegroundSteeringRoute(control: ForegroundRunControl): void {
-	if (!control.workflowSteeringDir) return;
-	try {
-		fs.rmSync(control.workflowSteeringDir, { recursive: true, force: true });
-	} catch (error) {
-		console.warn(`[pi-subagents] Failed to remove workflow foreground steering route '${control.workflowSteeringDir}': ${error instanceof Error ? error.message : String(error)}`);
-	}
-}
-
-export function workflowForegroundSteeringLaunchOptions(control: ForegroundRunControl | undefined, index: number): Pick<import("../../shared/types.ts").RunSyncOptions, "steerInboxDir" | "steerCapabilityPath" | "steerAckDir"> {
-	if (!control?.workflowSteeringDir) return {};
-	const steerInboxDir = stepSteerInboxDir(control.workflowSteeringDir, index);
-	const steerAckDir = steerAcksDir(control.workflowSteeringDir, index);
-	fs.mkdirSync(steerInboxDir, { recursive: true });
-	fs.mkdirSync(steerAckDir, { recursive: true });
-	return {
-		steerInboxDir,
-		steerCapabilityPath: steerCapabilityPath(control.workflowSteeringDir, index),
-		steerAckDir,
-	};
+	return { content: [{ type: "text", text: steeringReceipt(message, `Steering failed for foreground run ${control.runId} (request ${requestId}): ${outcome.reason ?? "unknown error"}`) }], isError: true, details: { mode: "management", results: [], steering } };
 }

package/src/runs/shared/abort-recovery.ts

@@ -101,9 +101,9 @@ export function planAbortRecovery(input: {
 	if (input.alreadyResumed) return settle("resume already attempted");
 	if (!input.sessionAvailable) return settle("retained session unavailable");
 	if (input.stopped || input.interrupted) return settle("explicit stop or interrupt");
-	// A compaction abort can leave the child process open until the runner's
-	// terminal drain sends SIGTERM. The compaction + settlement markers make
-	// that cleanup signal non-authoritative; explicit stop/interrupt still wins.
+	// An external-job runner reports a process signal when its terminal drain
+	// ends a child left open by a compaction abort. The compaction + settlement
+	// markers make that cleanup signal non-authoritative; explicit stop/interrupt still wins.
 	if (input.processSignal && !compactionAbortCandidate) return settle("process terminated by signal");
 	if (input.timedOut) return settle("elapsed timeout");
 	if (input.toolBudgetExhausted || input.usageBudgetExhausted) return settle("budget exhausted");

package/src/runs/shared/acceptance.ts

@@ -202,10 +202,23 @@ export function normalizeGateAcceptance(gate: unknown, acceptance: AcceptanceInp
 		return normalized.error ? { ok: false, error: normalized.error } : { ok: true, acceptance: normalized.value as AcceptanceInput };
 	}
 	if (typeof gate !== "string" || !gate.trim()) return { ok: false, error: "gate must be a non-empty command string." };
-	if (acceptance !== undefined) return { ok: false, error: "gate cannot be combined with acceptance; use one gate command or acceptance.verify." };
+	if (acceptance !== undefined && acceptance !== false) return { ok: false, error: "gate cannot be combined with acceptance; use one gate command or acceptance.verify." + describeGateAcceptanceConflict(gate, acceptance) };
 	return { ok: true, acceptance: { level: "verified", verify: [{ id: "gate", command: gate.trim() }] } };
 }
 
+export function describeGateAcceptanceConflict(gate: unknown, acceptance: unknown): string {
+	const render = (value: unknown): string => {
+		let encoded: string;
+		try {
+			encoded = JSON.stringify(value) ?? String(value);
+		} catch {
+			encoded = String(value);
+		}
+		return encoded.length > 120 ? `${encoded.slice(0, 120)}...` : encoded;
+	};
+	return ` Both fields were present: gate=${render(gate)} acceptance=${render(acceptance)}.`;
+}
+
 function explicitAcceptanceCanDisable(explicit: AcceptanceConfig): boolean {
 	return explicit.level === "none" && typeof explicit.reason === "string" && explicit.reason.trim().length > 0;
 }

package/src/runs/shared/capability-ceiling.ts

@@ -2,7 +2,6 @@ import { Buffer } from "node:buffer";
 
 export const SUBAGENT_CAPABILITY_CEILING_VERSION = 1 as const;
 export const SUBAGENT_CAPABILITY_CEILING_REGISTRY_KEY = "pi-subagents.capability-ceiling.v1";
-export const SUBAGENT_CAPABILITY_CEILING_ENV = "PI_SUBAGENT_CAPABILITY_CEILING_V1";
 
 export type SubagentCapabilityCeiling =
 	| { allowedTools: readonly string[]; allowedAgents?: readonly string[]; denyExtensions?: boolean }
@@ -167,7 +166,7 @@ export function resolveSubagentCapabilityCeiling(sessionId: string | undefined,
 }
 
 export function resolveCurrentSubagentCapabilityCeiling(sessionId: string | undefined): ResolvedSubagentCapabilityCeiling | undefined {
-	return resolveSubagentCapabilityCeiling(sessionId, decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV]));
+	return resolveSubagentCapabilityCeiling(sessionId, undefined);
 }
 
 export function isAgentAllowedByCapabilityCeiling(agentName: string, ceiling: ResolvedSubagentCapabilityCeiling | undefined): boolean {

package/src/runs/shared/child-hooks.ts

@@ -0,0 +1,25 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import registerFanoutChildSubagentExtension from "../../extension/fanout-child.ts";
+import registerSubagentFastModeExtension from "./fast-mode-extension.ts";
+import registerSubagentPromptRuntime from "./subagent-prompt-runtime.ts";
+import type { ChildRuntimeConfig } from "./child-runtime-config.ts";
+
+/** Inline extension shape accepted by pi's resource loader (`extensionFactories`). */
+export interface ChildHookExtension {
+	name: string;
+	factory: (pi: ExtensionAPI) => void;
+}
+
+/**
+ * The child-side hooks pi-subagents installs in every child, keyed off the
+ * launch config. The registrations live in `subagent-prompt-runtime.ts`,
+ * `fast-mode-extension.ts`, and `fanout-child.ts`.
+ */
+export function createChildHooks(config: ChildRuntimeConfig): ChildHookExtension[] {
+	const hooks: ChildHookExtension[] = [
+		{ name: "pi-subagents:prompt-runtime", factory: (pi) => registerSubagentPromptRuntime(pi, config) },
+	];
+	if (config.fast) hooks.push({ name: "pi-subagents:fast-mode", factory: (pi) => registerSubagentFastModeExtension(pi) });
+	if (config.fanoutChild) hooks.push({ name: "pi-subagents:fanout-child", factory: (pi) => registerFanoutChildSubagentExtension(pi, config) });
+	return hooks;
+}

package/src/runs/shared/child-identity.ts

@@ -14,11 +14,11 @@ export type AsyncStatusChildResolution =
 	| { ok: false; code: "not_found" | "ambiguous"; message: string };
 
 export function asyncStatusChildIdentity(step: AsyncStatusStep, index: number): string {
-	return step.workflowKey ?? step.runId ?? `step:${index}`;
+	return asyncStatusChildIdentityCandidates(step, index)[0]!;
 }
 
 export function asyncStatusChildIdentityCandidates(step: AsyncStatusStep, index: number): string[] {
-	return [...new Set([step.workflowKey, step.runId, `step:${index}`].filter((value): value is string => typeof value === "string" && value.length > 0))];
+	return [...new Set([step.childId, step.workflowKey, step.runId, `step:${index}`].filter((value): value is string => typeof value === "string" && value.length > 0))];
 }
 
 export function resolveAsyncStatusChild(
@@ -49,3 +49,14 @@ export function resolveAsyncStatusChild(
 export function isStoppableAsyncStatusStep(step: AsyncStatusStep): boolean {
 	return step.status === "pending" || step.status === "running";
 }
+
+export function stopStoppableAsyncStatusChildren(
+	status: Pick<AsyncStatus, "steps">,
+	stopChild: ((childId: string, message?: string) => boolean) | undefined,
+	message: string,
+): void {
+	if (!stopChild) return;
+	for (const [index, step] of (status.steps ?? []).entries()) {
+		if (isStoppableAsyncStatusStep(step)) stopChild(asyncStatusChildIdentity(step, index), message);
+	}
+}

package/src/runs/shared/child-launch.ts

@@ -0,0 +1,314 @@
+/**
+ * Builds the in-process launch for one child: the tool plan, the typed child
+ * runtime config the hooks read, and the session launch input. Foreground
+ * children are built in the parent process; background children are built in
+ * the detached runner from the step it received in its config.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ChildWatchdogConfig, ChildWatchdogStatusEvent } from "../../watchdog/child-status.ts";
+import type { ThinkingLevel } from "../../shared/model-info.ts";
+import { intersectThinkingCeilings } from "../../shared/thinking-ceiling.ts";
+import {
+	resolveChildDepth,
+	type LaunchResolvedChildExtensionsV1,
+	type ResolvedToolBudget,
+	type RunFanoutBudgetDescriptor,
+} from "../../shared/types.ts";
+import type { NestedPathEntry } from "./nested-path.ts";
+import type { McpRuntimeSnapshotHost } from "./mcp-direct-tool-allowlist.ts";
+import type { PermissionRules } from "./permissions.ts";
+import type { StructuredOutputRuntime } from "./structured-output.ts";
+import type { ChildToolDiagnostic } from "./tool-availability.ts";
+import type { RuntimeAcknowledgedChildExtensionsV1 } from "../../shared/types.ts";
+import { projectRuntimeAcknowledgedExtensions } from "./runtime-acknowledged-extensions.ts";
+import { encodeExtensionBindings, PI_SUBAGENT_EXTENSION_BINDINGS_ENV, type ExtensionBindings } from "./extension-bindings.ts";
+import type { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from "./capability-ceiling.ts";
+import {
+	isSubagentRuntimeExtensionPath,
+	projectLaunchResolvedChildExtensions,
+	resolvePiLaunchToolPlan,
+	supervisorChannelDir,
+	type PiLaunchToolPlan,
+} from "./child-tool-plan.ts";
+import type { ChildRuntimeConfig } from "./child-runtime-config.ts";
+import { createChildHooks } from "./child-hooks.ts";
+import type { ChildSessionLaunch, ChildSessionStorage } from "./child-session.ts";
+
+/** Environment variable pi-mcp-adapter reads for the tools a child may expose. */
+export const MCP_DIRECT_TOOLS_ENV = "MCP_DIRECT_TOOLS";
+
+/**
+ * The parts of the launching executor's own child runtime that a child it
+ * launches inherits. Serialized into the background runner config; the
+ * foreground path passes the executor's full `ChildRuntimeConfig`.
+ */
+export type InheritedChildRuntime = Pick<ChildRuntimeConfig, "depth" | "maxDepth" | "nestedRoute" | "nestedParent" | "capabilityCeiling" | "thinkingCeiling" | "runFanoutBudget">;
+
+export function inheritedChildRuntime(config: ChildRuntimeConfig | undefined): InheritedChildRuntime | undefined {
+	if (!config) return undefined;
+	return {
+		depth: config.depth,
+		...(config.maxDepth !== undefined ? { maxDepth: config.maxDepth } : {}),
+		...(config.nestedRoute ? { nestedRoute: config.nestedRoute } : {}),
+		...(config.nestedParent ? { nestedParent: config.nestedParent } : {}),
+		...(config.capabilityCeiling ? { capabilityCeiling: config.capabilityCeiling } : {}),
+		...(config.thinkingCeiling ? { thinkingCeiling: config.thinkingCeiling } : {}),
+		...(config.runFanoutBudget ? { runFanoutBudget: config.runFanoutBudget } : {}),
+	};
+}
+
+export interface BuildInProcessChildLaunchInput {
+	parentSessionId?: string;
+	forkCacheKey?: string;
+	sessionEnabled: boolean;
+	sessionDir?: string;
+	sessionFile?: string;
+	/** Model reference with the thinking suffix already applied. */
+	model?: string;
+	systemPromptMode?: "append" | "replace";
+	inheritProjectContext: boolean;
+	inheritGlobalContext: boolean;
+	inheritSkills: boolean;
+	requireReadTool?: boolean;
+	tools?: string[];
+	excludeTools?: string[];
+	extensions?: string[];
+	subagentOnlyExtensions?: string[];
+	systemPrompt?: string | null;
+	mcpDirectTools?: string[];
+	extensionBindings?: ExtensionBindings;
+	cwd: string;
+	intercomSessionName?: string;
+	sessionName?: string;
+	orchestratorIntercomTarget?: string;
+	runId?: string;
+	childAgentName: string;
+	childIndex: number;
+	nestedRoute?: { rootRunId: string; eventSink: string; controlInbox: string; capabilityToken: string };
+	runFanoutBudget?: RunFanoutBudgetDescriptor;
+	structuredOutput?: StructuredOutputRuntime;
+	fast?: boolean;
+	modelCandidates?: readonly string[];
+	toolBudget?: ResolvedToolBudget;
+	permissionRules?: PermissionRules;
+	permissionAuditPath?: string;
+	childWatchdog?: ChildWatchdogConfig;
+	watchdogStatus?: (event: ChildWatchdogStatusEvent) => void;
+	waitToolEnabled?: boolean;
+	waitToolDefaultTimeoutMs?: number;
+	allowNestedSubagents?: boolean;
+	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	thinkingCeiling?: ThinkingLevel;
+	maxSubagentDepth?: number;
+	runtimeSnapshotHost?: McpRuntimeSnapshotHost;
+	/** The launching executor's own child runtime when it is itself an in-process child. */
+	inherited?: InheritedChildRuntime;
+	/**
+	 * Which process hosts the session. The parent never loads ambient extensions
+	 * or writes child environment values (it shares its process with the parent
+	 * session); the runner loads ambient extensions when the tool plan allows
+	 * them and exposes the child environment external extensions read.
+	 */
+	host: "parent" | "runner";
+}
+
+export interface InProcessChildCapture {
+	structuredOutput(): { called: boolean; value?: unknown; acceptanceReport?: unknown; acceptanceReportProvided: boolean };
+	toolDiagnostic(): ChildToolDiagnostic | undefined;
+	runtimeAcknowledgedExtensions(): RuntimeAcknowledgedChildExtensionsV1 | undefined;
+}
+
+export interface InProcessChildLaunch {
+	toolPlan: PiLaunchToolPlan;
+	config: ChildRuntimeConfig;
+	session: Omit<ChildSessionLaunch, "onExtensionError">;
+	capture: InProcessChildCapture;
+	launchResolvedExtensions: LaunchResolvedChildExtensionsV1;
+	warnings: string[];
+	capabilityAudit?: SubagentCapabilityAudit;
+}
+
+/** Escape XML-significant characters in a string for safe attribute interpolation. */
+function escapeXmlAttr(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/"/g, "&quot;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
+}
+
+function inheritedCapabilityCeiling(inherited: InheritedChildRuntime | undefined): ResolvedSubagentCapabilityCeiling | undefined {
+	return inherited?.capabilityCeiling;
+}
+
+/** Environment values external child extensions read; only the runner applies them. */
+function childProcessEnv(input: BuildInProcessChildLaunchInput, toolPlan: PiLaunchToolPlan): Record<string, string | undefined> {
+	const env: Record<string, string | undefined> = {};
+	env[PI_SUBAGENT_EXTENSION_BINDINGS_ENV] = encodeExtensionBindings(input.extensionBindings);
+	if (!toolPlan.capabilityCeiling && input.mcpDirectTools?.length) env[MCP_DIRECT_TOOLS_ENV] = input.mcpDirectTools.join(",");
+	else if (toolPlan.capabilityCeiling && toolPlan.effectiveMcpSelections.length && !toolPlan.capabilityCeiling.denyExtensions) {
+		env[MCP_DIRECT_TOOLS_ENV] = toolPlan.effectiveMcpSelections.map((selection) => selection.selector).join(",");
+	} else env[MCP_DIRECT_TOOLS_ENV] = "__none__";
+	return env;
+}
+
+function childStorage(input: BuildInProcessChildLaunchInput): ChildSessionStorage {
+	if (input.sessionFile) {
+		fs.mkdirSync(path.dirname(input.sessionFile), { recursive: true });
+		return { kind: "file", sessionFile: input.sessionFile };
+	}
+	if (!input.sessionEnabled) return { kind: "memory" };
+	if (input.sessionDir) {
+		fs.mkdirSync(input.sessionDir, { recursive: true });
+		return { kind: "dir", sessionDir: input.sessionDir };
+	}
+	return { kind: "default" };
+}
+
+export function buildInProcessChildLaunch(input: BuildInProcessChildLaunchInput): InProcessChildLaunch {
+	const toolPlan = resolvePiLaunchToolPlan({
+		tools: input.tools,
+		excludeTools: input.excludeTools,
+		allowNestedSubagents: input.allowNestedSubagents,
+		extensions: input.extensions,
+		subagentOnlyExtensions: input.subagentOnlyExtensions,
+		mcpDirectTools: input.mcpDirectTools,
+		cwd: input.cwd,
+		requireReadTool: input.requireReadTool,
+		structuredOutput: Boolean(input.structuredOutput),
+		fast: input.fast,
+		model: input.model,
+		modelCandidates: input.modelCandidates,
+		capabilityCeiling: input.capabilityCeiling,
+		inheritedCapabilityCeiling: inheritedCapabilityCeiling(input.inherited),
+		agentName: input.childAgentName,
+		permissionRules: input.permissionRules,
+		runtimeSnapshotHost: input.runtimeSnapshotHost,
+	});
+
+	const inherited = input.inherited;
+	const fanout = toolPlan.fanoutAuthorized;
+	const inheritedRoute = inherited?.nestedRoute;
+	const parentRunId = input.runId ?? inherited?.nestedParent?.parentRunId ?? "";
+	const parentChildIndex = input.childIndex;
+	const parentDepth = inheritedRoute && inherited?.nestedParent ? inherited.nestedParent.depth + 1 : 1;
+	const parentPath: NestedPathEntry[] = [
+		...(inherited?.nestedParent?.path ?? []),
+		...(parentRunId ? [{ runId: parentRunId, stepIndex: parentChildIndex, agent: input.childAgentName }] : []),
+	];
+	const nestedRoute = fanout ? (input.nestedRoute ?? inheritedRoute) : undefined;
+	const childDepth = resolveChildDepth(input.maxSubagentDepth, inherited);
+	const permissions = input.permissionRules && Object.keys(input.permissionRules).length > 0
+		? { rules: input.permissionRules, ...(input.permissionAuditPath ? { auditPath: input.permissionAuditPath } : {}) }
+		: undefined;
+	let supervisorDir: string | undefined;
+	if (input.orchestratorIntercomTarget && input.parentSessionId && input.runId) {
+		supervisorDir = supervisorChannelDir(input.runId, input.childAgentName, input.childIndex);
+		fs.mkdirSync(path.join(supervisorDir, "requests"), { recursive: true });
+		fs.mkdirSync(path.join(supervisorDir, "replies"), { recursive: true });
+	}
+	const thinkingCeiling = intersectThinkingCeilings(input.thinkingCeiling, inherited?.thinkingCeiling);
+
+	let structuredValue: unknown;
+	let structuredAcceptanceReport: unknown;
+	let structuredCalled = false;
+	let structuredAcceptanceProvided = false;
+	let toolDiagnostic: ChildToolDiagnostic | undefined;
+	let acknowledgedIds: string[] | undefined;
+
+	const config: ChildRuntimeConfig = {
+		...(input.runId ? { runId: input.runId } : {}),
+		agent: input.childAgentName,
+		childIndex: input.childIndex,
+		fanoutChild: fanout,
+		...(input.sessionName?.trim() ? { sessionName: input.sessionName.trim() } : {}),
+		...(input.intercomSessionName ? { intercomSessionName: input.intercomSessionName } : {}),
+		...(input.orchestratorIntercomTarget ? { orchestratorTarget: input.orchestratorIntercomTarget } : {}),
+		...(input.parentSessionId ? { orchestratorSessionId: input.parentSessionId, parentSessionId: input.parentSessionId } : {}),
+		...(supervisorDir ? { supervisorChannelDir: supervisorDir } : {}),
+		...(nestedRoute ? { nestedRoute } : {}),
+		...(fanout && parentRunId ? { nestedParent: { parentRunId, parentChildIndex, depth: parentDepth, path: parentPath } } : {}),
+		...(fanout && (input.runFanoutBudget ?? inherited?.runFanoutBudget) ? { runFanoutBudget: input.runFanoutBudget ?? inherited?.runFanoutBudget } : {}),
+		depth: childDepth.depth,
+		maxDepth: childDepth.maxDepth,
+		...(toolPlan.capabilityCeiling ? { capabilityCeiling: toolPlan.capabilityCeiling } : {}),
+		...(thinkingCeiling ? { thinkingCeiling } : {}),
+		inheritProjectContext: input.inheritProjectContext,
+		inheritGlobalContext: input.inheritGlobalContext,
+		inheritSkills: input.inheritSkills,
+		...(input.forkCacheKey?.trim() ? { forkCacheKey: input.forkCacheKey.trim() } : {}),
+		...(permissions ? { permissions } : {}),
+		...(input.toolBudget ? { toolBudget: input.toolBudget } : {}),
+		...(input.childWatchdog ? { childWatchdog: input.childWatchdog } : {}),
+		...(input.watchdogStatus ? { watchdogStatus: input.watchdogStatus } : {}),
+		waitTool: {
+			enabled: input.waitToolEnabled ?? true,
+			...(input.waitToolDefaultTimeoutMs !== undefined ? { defaultTimeoutMs: input.waitToolDefaultTimeoutMs } : {}),
+		},
+		...(input.structuredOutput
+			? {
+				structuredOutput: {
+					schema: input.structuredOutput.schema,
+					...(input.structuredOutput.acceptanceReportPath
+						? { acceptanceReport: input.structuredOutput.acceptanceReportRequired ? "required" as const : "optional" as const }
+						: {}),
+					capture: (value: unknown, acceptanceReport: unknown) => {
+						structuredCalled = true;
+						structuredValue = value;
+						structuredAcceptanceProvided = acceptanceReport !== undefined;
+						structuredAcceptanceReport = acceptanceReport;
+					},
+				},
+			}
+			: {}),
+		...(toolPlan.requiredChildTools.length > 0 ? { requiredTools: toolPlan.requiredChildTools } : {}),
+		...(toolPlan.effectiveMcpTools.length > 0 ? { mcpDirectTools: toolPlan.effectiveMcpTools } : {}),
+		toolDiagnostic: (diagnostic) => { toolDiagnostic = diagnostic; },
+		runtimeAcknowledgements: (ids) => { acknowledgedIds = ids; },
+		fast: input.fast === true,
+	};
+
+	const extensionPaths = toolPlan.extensionArgs.filter((extensionPath) => !isSubagentRuntimeExtensionPath(extensionPath));
+	const ambientExtensions = input.host === "runner" && !toolPlan.disableAmbientExtensions;
+	const launchResolvedExtensions = projectLaunchResolvedChildExtensions({
+		runtimeExtensions: toolPlan.runtimeExtensions,
+		configuredExtensions: toolPlan.configuredExtensions,
+		extensionArgs: toolPlan.extensionArgs,
+		disableAmbientExtensions: !ambientExtensions,
+	});
+	const taggedPrompt = input.systemPrompt !== undefined && input.systemPrompt !== null
+		? `<active_agent name="${escapeXmlAttr(input.childAgentName)}"/>\n\n${input.systemPrompt}`
+		: undefined;
+	const session: Omit<ChildSessionLaunch, "onExtensionError"> = {
+		cwd: input.cwd,
+		storage: childStorage(input),
+		...(input.model ? { model: input.model } : {}),
+		...(toolPlan.explicitToolAllowlist ? { tools: toolPlan.effectiveToolAllowlist } : {}),
+		...(!toolPlan.explicitToolAllowlist && toolPlan.excludeTools.length > 0 ? { excludeTools: toolPlan.excludeTools } : {}),
+		extensionPaths,
+		ambientExtensions,
+		hooks: createChildHooks(config),
+		...(input.host === "runner" ? { processEnv: childProcessEnv(input, toolPlan) } : {}),
+		runtime: config,
+		noSkills: !input.inheritSkills,
+		noContextFiles: !input.inheritProjectContext,
+		...(taggedPrompt !== undefined
+			? input.systemPromptMode === "replace" ? { systemPrompt: taggedPrompt } : { appendSystemPrompt: taggedPrompt }
+			: {}),
+	};
+
+	return {
+		toolPlan,
+		config,
+		session,
+		capture: {
+			structuredOutput: () => ({ called: structuredCalled, value: structuredValue, acceptanceReport: structuredAcceptanceReport, acceptanceReportProvided: structuredAcceptanceProvided }),
+			toolDiagnostic: () => toolDiagnostic,
+			runtimeAcknowledgedExtensions: () => (acknowledgedIds ? projectRuntimeAcknowledgedExtensions(acknowledgedIds) : undefined),
+		},
+		launchResolvedExtensions,
+		warnings: toolPlan.warnings,
+		...(toolPlan.capabilityAudit ? { capabilityAudit: toolPlan.capabilityAudit } : {}),
+	};
+}

package/src/runs/shared/child-lifecycle.ts

@@ -0,0 +1,25 @@
+/**
+ * Child lifecycle projection: when the observed child session events mean
+ * the run is settling and the observer may start (or must cancel) its final
+ * drain window.
+ */
+export type ChildLifecycleAction = "start-drain" | "cancel-drain" | "none";
+
+export interface ChildLifecycleState {
+	compactionRetryActive: boolean;
+}
+
+export function projectChildLifecycle(event: { type?: string; willRetry?: unknown }, terminalAssistantStop = false, state?: ChildLifecycleState): ChildLifecycleAction {
+	if (event.type === "compaction_end") {
+		if (state) state.compactionRetryActive = event.willRetry === true;
+		return event.willRetry === true ? "cancel-drain" : "none";
+	}
+	if (event.type === "agent_start" || event.type === "auto_retry_start") {
+		if (state) state.compactionRetryActive = false;
+	}
+	if (event.type === "agent_end" && event.willRetry === true) return "cancel-drain";
+	if (event.type === "agent_end" && state) state.compactionRetryActive = false;
+	if (event.type === "agent_settled") return state?.compactionRetryActive ? "none" : "start-drain";
+	if (terminalAssistantStop) return "start-drain";
+	return "none";
+}