pi-subagents 0.24.3 → 0.25.0

package/src/runs/shared/nested-path.ts

@@ -0,0 +1,52 @@
+import * as path from "node:path";
+
+const MAX_NESTED_ID_LENGTH = 128;
+export const MAX_NESTED_PATH_ENTRIES = 4;
+
+export type NestedPathEntry = { runId: string; stepIndex?: number; agent?: string };
+
+export function isSafeNestedPathId(value: unknown): value is string {
+	return typeof value === "string"
+		&& value.length > 0
+		&& value.length <= MAX_NESTED_ID_LENGTH
+		&& !path.isAbsolute(value)
+		&& !value.includes("/")
+		&& !value.includes("\\")
+		&& !value.includes("..");
+}
+
+function finiteNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function nonEmptyString(value: unknown, max: number): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value.slice(0, max) : undefined;
+}
+
+export function sanitizeNestedPath(value: unknown): NestedPathEntry[] {
+	if (!Array.isArray(value)) return [];
+	return value.map((part) => {
+		if (!part || typeof part !== "object") return undefined;
+		const record = part as Record<string, unknown>;
+		if (!isSafeNestedPathId(record.runId)) return undefined;
+		return {
+			runId: record.runId,
+			...(finiteNumber(record.stepIndex) !== undefined ? { stepIndex: finiteNumber(record.stepIndex) } : {}),
+			...(nonEmptyString(record.agent, 128) ? { agent: nonEmptyString(record.agent, 128) } : {}),
+		};
+	}).filter((part): part is NestedPathEntry => Boolean(part)).slice(0, MAX_NESTED_PATH_ENTRIES);
+}
+
+export function parseNestedPathEnv(value: string | undefined): NestedPathEntry[] {
+	if (!value) return [];
+	try {
+		return sanitizeNestedPath(JSON.parse(value) as unknown);
+	} catch {
+		return [];
+	}
+}
+
+export function encodeNestedPathEnv(value: NestedPathEntry[]): string {
+	const sanitized = sanitizeNestedPath(value);
+	return sanitized.length ? JSON.stringify(sanitized) : "";
+}

package/src/runs/shared/nested-render.ts

@@ -0,0 +1,115 @@
+import { formatDuration, formatTokens, shortenPath } from "../../shared/formatters.ts";
+import { formatActivityLabel } from "../../shared/status-format.ts";
+import type { ActivityState, NestedRunSummary, NestedStepSummary } from "../../shared/types.ts";
+
+export interface NestedRunCounts {
+	total: number;
+	running: number;
+	paused: number;
+	complete: number;
+	failed: number;
+	queued: number;
+}
+
+export function countNestedRuns(children: NestedRunSummary[] | undefined): NestedRunCounts {
+	const counts: NestedRunCounts = { total: 0, running: 0, paused: 0, complete: 0, failed: 0, queued: 0 };
+	for (const child of children ?? []) {
+		counts.total++;
+		counts[child.state]++;
+		const nested = countNestedRuns([...(child.children ?? []), ...(child.steps?.flatMap((step) => step.children ?? []) ?? [])]);
+		counts.total += nested.total;
+		counts.running += nested.running;
+		counts.paused += nested.paused;
+		counts.complete += nested.complete;
+		counts.failed += nested.failed;
+		counts.queued += nested.queued;
+	}
+	return counts;
+}
+
+export function formatNestedAggregate(children: NestedRunSummary[] | undefined): string | undefined {
+	const counts = countNestedRuns(children);
+	if (counts.total === 0) return undefined;
+	const parts = [
+		counts.running > 0 ? `${counts.running} running` : "",
+		counts.paused > 0 ? `${counts.paused} paused` : "",
+		counts.failed > 0 ? `${counts.failed} failed` : "",
+		counts.complete > 0 ? `${counts.complete} complete` : "",
+		counts.queued > 0 ? `${counts.queued} queued` : "",
+	].filter(Boolean);
+	return `+${counts.total} nested run${counts.total === 1 ? "" : "s"}${parts.length ? ` (${parts.join(", ")})` : ""}`;
+}
+
+function nestedRunLabel(run: NestedRunSummary): string {
+	if (run.agent) return run.agent;
+	if (run.agents?.length) return run.agents.length === 1 ? run.agents[0]! : `${run.agents.slice(0, 2).join(", ")}${run.agents.length > 2 ? ` +${run.agents.length - 2}` : ""}`;
+	return run.id;
+}
+
+function formatNestedActivity(input: {
+	activityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	turnCount?: number;
+	toolCount?: number;
+	totalTokens?: NestedRunSummary["totalTokens"];
+}): string | undefined {
+	const facts: string[] = [];
+	if (input.currentTool && input.currentToolStartedAt !== undefined) facts.push(`tool ${input.currentTool} ${formatDuration(Math.max(0, Date.now() - input.currentToolStartedAt))}`);
+	else if (input.currentTool) facts.push(`tool ${input.currentTool}`);
+	if (input.currentPath) facts.push(shortenPath(input.currentPath));
+	if (input.turnCount !== undefined) facts.push(`${input.turnCount} turns`);
+	if (input.toolCount !== undefined) facts.push(`${input.toolCount} tools`);
+	if (input.totalTokens) facts.push(`${formatTokens(input.totalTokens.total)} tok`);
+	const activity = formatActivityLabel(input.lastActivityAt, input.activityState as ActivityState | undefined);
+	return activity || facts.length ? [activity, ...facts].filter(Boolean).join(" | ") : undefined;
+}
+
+function formatNestedRunLines(children: NestedRunSummary[] | undefined, options: { indent: string; maxDepth: number; maxLines: number; commandHints?: boolean }): string[] {
+	const lines: string[] = [];
+	const append = (items: NestedRunSummary[] | undefined, depth: number, indent: string): void => {
+		if (!items?.length || lines.length >= options.maxLines) return;
+		if (depth > options.maxDepth) {
+			const aggregate = formatNestedAggregate(items);
+			if (aggregate && lines.length < options.maxLines) lines.push(`${indent}↳ ${aggregate}`);
+			return;
+		}
+		for (let index = 0; index < items.length; index++) {
+			const child = items[index]!;
+			if (lines.length >= options.maxLines) {
+				const aggregate = formatNestedAggregate(items.slice(index));
+				if (aggregate) lines[lines.length - 1] = `${indent}↳ ${aggregate}`;
+				return;
+			}
+			const activity = child.state === "running" ? formatNestedActivity(child) : undefined;
+			const error = child.error ? ` | error: ${child.error}` : "";
+			lines.push(`${indent}↳ ${nestedRunLabel(child)} [${child.id}] ${child.state}${activity ? ` | ${activity}` : ""}${error}`);
+			if (options.commandHints && lines.length < options.maxLines) lines.push(`${indent}  Status: subagent({ action: "status", id: "${child.id}" })`);
+			if (depth === options.maxDepth) {
+				const aggregate = formatNestedAggregate([...(child.steps?.flatMap((step) => step.children ?? []) ?? []), ...(child.children ?? [])]);
+				if (aggregate && lines.length < options.maxLines) lines.push(`${indent}  ↳ ${aggregate}`);
+				continue;
+			}
+			for (const [stepIndex, step] of (child.steps ?? []).entries()) {
+				if (lines.length >= options.maxLines) return;
+				const stepActivity = step.status === "running" ? formatNestedActivity(step) : undefined;
+				lines.push(`${indent}  ${stepIndex + 1}. ${step.agent} ${step.status}${stepActivity ? ` | ${stepActivity}` : ""}${step.error ? ` | error: ${step.error}` : ""}`);
+				append(step.children, depth + 1, `${indent}    `);
+			}
+			append(child.children, depth + 1, `${indent}  `);
+		}
+	};
+	append(children, 0, options.indent);
+	return lines;
+}
+
+export function formatNestedRunStatusLines(children: NestedRunSummary[] | undefined, options: { indent?: string; maxDepth?: number; maxLines?: number; commandHints?: boolean } = {}): string[] {
+	return formatNestedRunLines(children, {
+		indent: options.indent ?? "  ",
+		maxDepth: options.maxDepth ?? 2,
+		maxLines: options.maxLines ?? 40,
+		commandHints: options.commandHints ?? false,
+	});
+}

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

@@ -8,6 +8,7 @@ export interface RunnerSubagentStep {
 	tools?: string[];
 	extensions?: string[];
 	mcpDirectTools?: string[];
+	completionGuard?: boolean;
 	systemPrompt?: string | null;
 	systemPromptMode?: "append" | "replace";
 	inheritProjectContext: boolean;

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

@@ -2,15 +2,27 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import { encodeNestedPathEnv, parseNestedPathEnv, type NestedPathEntry } from "./nested-path.ts";
+import { resolveMcpDirectToolNames } from "./mcp-direct-tool-allowlist.ts";
 
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
 const TASK_ARG_LIMIT = 8000;
 const PROMPT_RUNTIME_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "subagent-prompt-runtime.ts");
+const FANOUT_CHILD_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "extension", "fanout-child.ts");
 export const SUBAGENT_CHILD_ENV = "PI_SUBAGENT_CHILD";
 export const SUBAGENT_ORCHESTRATOR_TARGET_ENV = "PI_SUBAGENT_ORCHESTRATOR_TARGET";
 export const SUBAGENT_RUN_ID_ENV = "PI_SUBAGENT_RUN_ID";
 export const SUBAGENT_CHILD_AGENT_ENV = "PI_SUBAGENT_CHILD_AGENT";
 export const SUBAGENT_CHILD_INDEX_ENV = "PI_SUBAGENT_CHILD_INDEX";
+export const SUBAGENT_FANOUT_CHILD_ENV = "PI_SUBAGENT_FANOUT_CHILD";
+export const SUBAGENT_PARENT_EVENT_SINK_ENV = "PI_SUBAGENT_PARENT_EVENT_SINK";
+export const SUBAGENT_PARENT_CONTROL_INBOX_ENV = "PI_SUBAGENT_PARENT_CONTROL_INBOX";
+export const SUBAGENT_PARENT_ROOT_RUN_ID_ENV = "PI_SUBAGENT_PARENT_ROOT_RUN_ID";
+export const SUBAGENT_PARENT_RUN_ID_ENV = "PI_SUBAGENT_PARENT_RUN_ID";
+export const SUBAGENT_PARENT_CHILD_INDEX_ENV = "PI_SUBAGENT_PARENT_CHILD_INDEX";
+export const SUBAGENT_PARENT_DEPTH_ENV = "PI_SUBAGENT_PARENT_DEPTH";
+export const SUBAGENT_PARENT_PATH_ENV = "PI_SUBAGENT_PARENT_PATH";
+export const SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV = "PI_SUBAGENT_PARENT_CAPABILITY_TOKEN";
 
 interface BuildPiArgsInput {
 	baseArgs: string[];
@@ -27,12 +39,21 @@ interface BuildPiArgsInput {
 	extensions?: string[];
 	systemPrompt?: string | null;
 	mcpDirectTools?: string[];
+	cwd?: string;
 	promptFileStem?: string;
 	intercomSessionName?: string;
 	orchestratorIntercomTarget?: string;
 	runId?: string;
 	childAgentName?: string;
 	childIndex?: number;
+	parentEventSink?: string;
+	parentControlInbox?: string;
+	parentRootRunId?: string;
+	parentRunId?: string;
+	parentChildIndex?: number;
+	parentDepth?: number;
+	parentPath?: NestedPathEntry[];
+	parentCapabilityToken?: string;
 }
 
 interface BuildPiArgsResult {
@@ -69,22 +90,27 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 		args.push("--model", modelArg);
 	}
 
+	const declaredBuiltinTools = input.tools?.filter((tool) => !(tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) ?? [];
+	const fanoutAuthorized = declaredBuiltinTools.includes("subagent");
 	const toolExtensionPaths: string[] = [];
 	if (input.tools?.length) {
-		const builtinTools: string[] = [];
+		const builtinTools = [...declaredBuiltinTools];
 		for (const tool of input.tools) {
-			if (tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js")) {
+			if (!declaredBuiltinTools.includes(tool) && (tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) {
 				toolExtensionPaths.push(tool);
-			} else {
-				builtinTools.push(tool);
 			}
 		}
 		if (builtinTools.length > 0) {
+			if (input.mcpDirectTools?.length) {
+				builtinTools.push(...resolveMcpDirectToolNames(input.mcpDirectTools, input.cwd));
+			}
 			args.push("--tools", builtinTools.join(","));
 		}
 	}
 
-	const runtimeExtensions = [PROMPT_RUNTIME_EXTENSION_PATH];
+	const runtimeExtensions = fanoutAuthorized
+		? [PROMPT_RUNTIME_EXTENSION_PATH, FANOUT_CHILD_EXTENSION_PATH]
+		: [PROMPT_RUNTIME_EXTENSION_PATH];
 	if (input.extensions !== undefined) {
 		args.push("--no-extensions");
 		for (const extPath of [...new Set([...runtimeExtensions, ...toolExtensionPaths, ...input.extensions])]) {
@@ -122,6 +148,40 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 
 	const env: Record<string, string | undefined> = {};
 	env[SUBAGENT_CHILD_ENV] = "1";
+	env[SUBAGENT_FANOUT_CHILD_ENV] = fanoutAuthorized ? "1" : "0";
+	const inheritedNestedRoute = Boolean(process.env[SUBAGENT_PARENT_EVENT_SINK_ENV] && process.env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] && process.env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV]);
+	const parentRunId = input.parentRunId ?? input.runId ?? (inheritedNestedRoute ? process.env[SUBAGENT_RUN_ID_ENV] : undefined) ?? process.env[SUBAGENT_PARENT_RUN_ID_ENV] ?? "";
+	const parentChildIndex = input.parentChildIndex !== undefined
+		? String(input.parentChildIndex)
+		: input.childIndex !== undefined
+			? String(input.childIndex)
+			: process.env[SUBAGENT_PARENT_CHILD_INDEX_ENV] ?? "";
+	const inheritedDepth = Number(process.env[SUBAGENT_PARENT_DEPTH_ENV]);
+	const parentDepth = input.parentDepth ?? (inheritedNestedRoute && Number.isFinite(inheritedDepth) ? inheritedDepth + 1 : 1);
+	const parentPath = input.parentPath ?? [
+		...parseNestedPathEnv(process.env[SUBAGENT_PARENT_PATH_ENV]),
+		...(parentRunId ? [{
+			runId: parentRunId,
+			...(parentChildIndex && /^\d+$/.test(parentChildIndex) ? { stepIndex: Number(parentChildIndex) } : {}),
+			...(input.childAgentName ? { agent: input.childAgentName } : {}),
+		}] : []),
+	];
+	env[SUBAGENT_PARENT_EVENT_SINK_ENV] = fanoutAuthorized
+		? input.parentEventSink ?? process.env[SUBAGENT_PARENT_EVENT_SINK_ENV] ?? ""
+		: "";
+	env[SUBAGENT_PARENT_CONTROL_INBOX_ENV] = fanoutAuthorized
+		? input.parentControlInbox ?? process.env[SUBAGENT_PARENT_CONTROL_INBOX_ENV] ?? ""
+		: "";
+	env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] = fanoutAuthorized
+		? input.parentRootRunId ?? process.env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] ?? input.runId ?? ""
+		: "";
+	env[SUBAGENT_PARENT_RUN_ID_ENV] = fanoutAuthorized ? parentRunId : "";
+	env[SUBAGENT_PARENT_CHILD_INDEX_ENV] = fanoutAuthorized ? parentChildIndex : "";
+	env[SUBAGENT_PARENT_DEPTH_ENV] = fanoutAuthorized ? String(parentDepth) : "";
+	env[SUBAGENT_PARENT_PATH_ENV] = fanoutAuthorized ? encodeNestedPathEnv(parentPath) : "";
+	env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV] = fanoutAuthorized
+		? input.parentCapabilityToken ?? process.env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV] ?? ""
+		: "";
 	env.PI_SUBAGENT_INHERIT_PROJECT_CONTEXT = input.inheritProjectContext ? "1" : "0";
 	env.PI_SUBAGENT_INHERIT_SKILLS = input.inheritSkills ? "1" : "0";
 	if (input.intercomSessionName) {
@@ -148,6 +208,8 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	return { args, env, tempDir };
 }
 
+export const parseParentPathEnv = parseNestedPathEnv;
+
 export function cleanupTempDir(tempDir: string | null | undefined): void {
 	if (!tempDir) return;
 	try {

package/src/runs/shared/run-history.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
+import { getAgentDir } from "../../shared/utils.ts";
 
 export interface RunEntry {
 	agent: string;
@@ -11,10 +11,13 @@ export interface RunEntry {
 	exit?: number;
 }
 
-const HISTORY_PATH = path.join(os.homedir(), ".pi", "agent", "run-history.jsonl");
 const ROTATE_READ_THRESHOLD = 1200;
 const ROTATE_KEEP = 1000;
 
+function getHistoryPath(): string {
+	return path.join(getAgentDir(), "run-history.jsonl");
+}
+
 export function recordRun(agent: string, task: string, exitCode: number, durationMs: number): void {
 	try {
 		const entry: RunEntry = {
@@ -25,18 +28,20 @@ export function recordRun(agent: string, task: string, exitCode: number, duratio
 			duration: durationMs,
 			...(exitCode !== 0 ? { exit: exitCode } : {}),
 		};
-		fs.mkdirSync(path.dirname(HISTORY_PATH), { recursive: true });
-		fs.appendFileSync(HISTORY_PATH, `${JSON.stringify(entry)}\n`);
+		const historyPath = getHistoryPath();
+		fs.mkdirSync(path.dirname(historyPath), { recursive: true });
+		fs.appendFileSync(historyPath, `${JSON.stringify(entry)}\n`);
 	} catch {
 		// Best-effort — never crash the execution flow for history recording
 	}
 }
 
 export function loadRunsForAgent(agent: string): RunEntry[] {
-	if (!fs.existsSync(HISTORY_PATH)) return [];
+	const historyPath = getHistoryPath();
+	if (!fs.existsSync(historyPath)) return [];
 	let raw: string;
 	try {
-		raw = fs.readFileSync(HISTORY_PATH, "utf-8");
+		raw = fs.readFileSync(historyPath, "utf-8");
 	} catch {
 		return [];
 	}
@@ -45,7 +50,7 @@ export function loadRunsForAgent(agent: string): RunEntry[] {
 
 	if (lines.length > ROTATE_READ_THRESHOLD) {
 		lines = lines.slice(-ROTATE_KEEP);
-		try { fs.writeFileSync(HISTORY_PATH, `${lines.join("\n")}\n`, "utf-8"); } catch {}
+		try { fs.writeFileSync(historyPath, `${lines.join("\n")}\n`, "utf-8"); } catch {}
 	}
 
 	return lines

package/src/runs/shared/single-output.ts

@@ -8,12 +8,22 @@ export interface SingleOutputSnapshot {
 	size?: number;
 }
 
+export function normalizeSingleOutputOverride(
+	output: string | boolean | undefined,
+	defaultOutput: string | undefined,
+): string | false | undefined {
+	if (output === false || output === "false") return false;
+	if (output === true || output === "true") return defaultOutput;
+	if (typeof output === "string" && output.length > 0) return output;
+	return undefined;
+}
+
 export function resolveSingleOutputPath(
-	output: string | false | undefined,
+	output: string | boolean | undefined,
 	runtimeCwd: string,
 	requestedCwd?: string,
 ): string | undefined {
-	if (typeof output !== "string" || !output) return undefined;
+	if (typeof output !== "string" || !output || output === "false" || output === "true") return undefined;
 	if (path.isAbsolute(output)) return output;
 	const baseCwd = requestedCwd
 		? (path.isAbsolute(requestedCwd) ? requestedCwd : path.resolve(runtimeCwd, requestedCwd))

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { SUBAGENT_FANOUT_CHILD_ENV } from "./pi-args.ts";
 
 const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "PI_SUBAGENT_INHERIT_PROJECT_CONTEXT";
 const SUBAGENT_INHERIT_SKILLS_ENV = "PI_SUBAGENT_INHERIT_SKILLS";
@@ -12,6 +13,15 @@ export const CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS = [
 	"If you need to edit files, call the actual edit/write tools. Do not print tool-call syntax, patches, or pseudo-tool calls as text.",
 ].join("\n");
 
+export const CHILD_FANOUT_BOUNDARY_INSTRUCTIONS = [
+	"You are a child subagent with explicit fanout responsibility for this assigned task.",
+	"The parent session owns final orchestration, acceptance, and follow-up implementation launches.",
+	"You may use the `subagent` tool only for the fanout work explicitly requested in this task.",
+	"Do not broaden yourself into general parent orchestration. Do not launch follow-up workers unless the task explicitly asks for that.",
+	"The maxSubagentDepth cap still applies and may block further fanout.",
+	"If you need to edit files, call the actual edit/write tools. Do not print tool-call syntax, patches, or pseudo-tool calls as text.",
+].join("\n");
+
 const PARENT_ONLY_CUSTOM_MESSAGE_TYPES = new Set([
 	"subagent-orchestration-instructions",
 	"subagent-slash-result",
@@ -62,9 +72,17 @@ export function stripSubagentOrchestrationSkill(prompt: string): string {
 		.replace(/[ \t]*<skill>\s*[\s\S]*?<\/skill>\s*/g, (block) => SUBAGENT_ORCHESTRATION_SKILL_NAME_PATTERN.test(block) ? "" : block);
 }
 
+function stripChildBoundaryInstructions(prompt: string): string {
+	let rewritten = prompt;
+	for (const boundary of [CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS, CHILD_FANOUT_BOUNDARY_INSTRUCTIONS]) {
+		rewritten = rewritten.split(boundary).join("");
+	}
+	return rewritten.replace(/^(?:[ \t]*\r?\n)+/, "");
+}
+
 export function rewriteSubagentPrompt(
 	prompt: string,
-	options: { inheritProjectContext: boolean; inheritSkills: boolean },
+	options: { inheritProjectContext: boolean; inheritSkills: boolean; fanoutChild?: boolean },
 ): string {
 	let rewritten = prompt;
 	if (!options.inheritProjectContext) {
@@ -74,9 +92,9 @@ export function rewriteSubagentPrompt(
 		rewritten = stripInheritedSkills(rewritten);
 	}
 	rewritten = stripSubagentOrchestrationSkill(rewritten);
-	return rewritten.includes(CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS)
-		? rewritten
-		: `${CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS}\n\n${rewritten}`;
+	rewritten = stripChildBoundaryInstructions(rewritten);
+	const boundary = options.fanoutChild ? CHILD_FANOUT_BOUNDARY_INSTRUCTIONS : CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS;
+	return `${boundary}\n\n${rewritten}`;
 }
 
 function isParentOnlySubagentMessage(message: unknown): boolean {
@@ -139,10 +157,12 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 
 		const inheritProjectContext = readBooleanEnv(SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV);
 		const inheritSkills = readBooleanEnv(SUBAGENT_INHERIT_SKILLS_ENV);
-		if (inheritProjectContext === undefined && inheritSkills === undefined) return;
+		const fanoutChild = readBooleanEnv(SUBAGENT_FANOUT_CHILD_ENV);
+		if (inheritProjectContext === undefined && inheritSkills === undefined && fanoutChild === undefined) return;
 		const rewritten = rewriteSubagentPrompt(event.systemPrompt, {
 			inheritProjectContext: inheritProjectContext ?? true,
 			inheritSkills: inheritSkills ?? true,
+			fanoutChild: fanoutChild === true,
 		});
 		if (rewritten === event.systemPrompt) return;
 		return { systemPrompt: rewritten };

package/src/shared/artifacts.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 import { TEMP_ARTIFACTS_DIR, type ArtifactPaths } from "./types.ts";
+import { getAgentDir } from "./utils.ts";
 const CLEANUP_MARKER_FILE = ".last-cleanup";
 
 export function getArtifactsDir(sessionFile: string | null): string {
@@ -74,7 +74,7 @@ export function cleanupOldArtifacts(dir: string, maxAgeDays: number): void {
 export function cleanupAllArtifactDirs(maxAgeDays: number): void {
 	cleanupOldArtifacts(TEMP_ARTIFACTS_DIR, maxAgeDays);
 
-	const sessionsBase = path.join(os.homedir(), ".pi", "agent", "sessions");
+	const sessionsBase = path.join(getAgentDir(), "sessions");
 	if (!fs.existsSync(sessionsBase)) return;
 
 	let dirs: string[];

package/src/shared/types.ts

@@ -83,6 +83,8 @@ export interface ControlEvent {
 	agent: string;
 	index?: number;
 	runId: string;
+	nestedRunId?: string;
+	nestingPath?: NestedRunAddress["path"];
 	message: string;
 	reason?: "idle" | "completion_guard" | "active_long_running" | "tool_failures" | "time_threshold" | "turn_threshold" | "token_threshold";
 	turns?: number;
@@ -98,6 +100,21 @@ export interface ControlEvent {
 export type SubagentResultStatus = "completed" | "failed" | "paused" | "detached";
 export type SubagentRunMode = "single" | "parallel" | "chain";
 
+export type PublicNestedStepSummary = Pick<
+	NestedStepSummary,
+	"agent" | "status" | "sessionFile" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "startedAt" | "endedAt" | "error"
+> & {
+	children?: PublicNestedRunSummary[];
+};
+
+export type PublicNestedRunSummary = Pick<
+	NestedRunSummary,
+	"id" | "parentRunId" | "parentStepIndex" | "parentAgent" | "depth" | "path" | "asyncDir" | "sessionId" | "sessionFile" | "intercomTarget" | "ownerIntercomTarget" | "leafIntercomTarget" | "ownerState" | "mode" | "state" | "agent" | "agents" | "currentStep" | "chainStepCount" | "parallelGroups" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "totalTokens" | "startedAt" | "endedAt" | "lastUpdate" | "error"
+> & {
+	steps?: PublicNestedStepSummary[];
+	children?: PublicNestedRunSummary[];
+};
+
 export interface SubagentResultIntercomChild {
 	agent: string;
 	status: SubagentResultStatus;
@@ -106,6 +123,7 @@ export interface SubagentResultIntercomChild {
 	artifactPath?: string;
 	sessionPath?: string;
 	intercomTarget?: string;
+	children?: PublicNestedRunSummary[];
 }
 
 export interface SubagentResultIntercomPayload {
@@ -261,6 +279,76 @@ export interface AsyncParallelGroupStatus {
 	stepIndex: number;
 }
 
+export type NestedRunState = "queued" | "running" | "complete" | "failed" | "paused";
+export type NestedOwnerState = "live" | "gone" | "unknown";
+
+export interface NestedRunAddress {
+	id: string;
+	parentRunId: string;
+	parentStepIndex?: number;
+	parentAgent?: string;
+	depth: number;
+	path: Array<{ runId: string; stepIndex?: number; agent?: string }>;
+}
+
+export interface NestedStepSummary {
+	agent: string;
+	status: "pending" | "running" | "complete" | "completed" | "failed" | "paused";
+	sessionFile?: string;
+	activityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	turnCount?: number;
+	toolCount?: number;
+	startedAt?: number;
+	endedAt?: number;
+	error?: string;
+	children?: NestedRunSummary[];
+}
+
+export interface NestedRunSummary extends NestedRunAddress {
+	asyncDir?: string;
+	pid?: number;
+	sessionId?: string;
+	sessionFile?: string;
+	intercomTarget?: string;
+	ownerIntercomTarget?: string;
+	leafIntercomTarget?: string;
+	ownerState?: NestedOwnerState;
+	controlInbox?: string;
+	capabilityToken?: string;
+	mode?: SubagentRunMode;
+	state: NestedRunState;
+	agent?: string;
+	agents?: string[];
+	currentStep?: number;
+	chainStepCount?: number;
+	parallelGroups?: AsyncParallelGroupStatus[];
+	steps?: NestedStepSummary[];
+	children?: NestedRunSummary[];
+	activityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	turnCount?: number;
+	toolCount?: number;
+	totalTokens?: TokenUsage;
+	startedAt?: number;
+	endedAt?: number;
+	lastUpdate?: number;
+	error?: string;
+}
+
+export interface NestedRouteInfo {
+	rootRunId: string;
+	eventSink: string;
+	controlInbox: string;
+	capabilityToken: string;
+}
+
 export interface AsyncStartedEvent {
 	id?: string;
 	asyncDir?: string;
@@ -272,6 +360,7 @@ export interface AsyncStartedEvent {
 	chain?: string[];
 	chainStepCount?: number;
 	parallelGroups?: AsyncParallelGroupStatus[];
+	nestedRoute?: NestedRouteInfo;
 }
 
 export interface AsyncStatus {
@@ -297,6 +386,7 @@ export interface AsyncStatus {
 	steps?: Array<{
 		agent: string;
 		status: "pending" | "running" | "complete" | "completed" | "failed" | "paused";
+		children?: NestedRunSummary[];
 		sessionFile?: string;
 		activityState?: ActivityState;
 		lastActivityAt?: number;
@@ -361,6 +451,8 @@ export interface AsyncJobState {
 	totalTokens?: TokenUsage;
 	sessionFile?: string;
 	controlEventCursor?: number;
+	nestedRoute?: NestedRouteInfo;
+	nestedChildren?: NestedRunSummary[];
 }
 
 export interface ForegroundResumeChild {
@@ -398,6 +490,8 @@ export interface SubagentState {
 		turnCount?: number;
 		tokens?: number;
 		toolCount?: number;
+		nestedRoute?: NestedRouteInfo;
+		nestedChildren?: NestedRunSummary[];
 		interrupt?: () => boolean;
 	}>;
 	lastForegroundControlId: string | null;
@@ -473,6 +567,7 @@ export interface RunSyncOptions {
 	outputPath?: string;
 	outputMode?: OutputMode;
 	maxSubagentDepth?: number;
+	nestedRoute?: NestedRouteInfo;
 	/** Override the agent's default model (format: "provider/id" or just "id") */
 	modelOverride?: string;
 	/** Registry models available for heuristic bare-model resolution */

package/src/shared/utils.ts

@@ -13,6 +13,13 @@ import type { AgentProgress, AsyncStatus, Details, DisplayItem, ErrorInfo, Singl
 // File System Utilities
 // ============================================================================
 
+export function getAgentDir(): string {
+	const configured = process.env.PI_CODING_AGENT_DIR;
+	if (configured === "~") return os.homedir();
+	if (configured?.startsWith("~/")) return path.join(os.homedir(), configured.slice(2));
+	return configured || path.join(os.homedir(), ".pi", "agent");
+}
+
 const statusCache = new Map<string, { mtime: number; status: AsyncStatus }>();
 
 function getErrorMessage(error: unknown): string {
@@ -182,8 +189,11 @@ export function getFinalOutput(messages: Message[]): string {
 	for (let i = messages.length - 1; i >= 0; i--) {
 		const msg = messages[i];
 		if (msg.role === "assistant") {
+			const hasAssistantError = ("errorMessage" in msg && typeof msg.errorMessage === "string" && msg.errorMessage.length > 0)
+				|| ("stopReason" in msg && msg.stopReason === "error");
+			if (hasAssistantError) continue;
 			for (const part of msg.content) {
-				if (part.type === "text") return part.text;
+				if (part.type === "text" && part.text.trim().length > 0) return part.text;
 			}
 		}
 	}