pi-subagents 0.24.4 → 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/pi-args.ts

@@ -2,16 +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[];
@@ -35,6 +46,14 @@ interface BuildPiArgsInput {
 	runId?: string;
 	childAgentName?: string;
 	childIndex?: number;
+	parentEventSink?: string;
+	parentControlInbox?: string;
+	parentRootRunId?: string;
+	parentRunId?: string;
+	parentChildIndex?: number;
+	parentDepth?: number;
+	parentPath?: NestedPathEntry[];
+	parentCapabilityToken?: string;
 }
 
 interface BuildPiArgsResult {
@@ -71,14 +90,14 @@ 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) {
@@ -89,7 +108,9 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 		}
 	}
 
-	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])]) {
@@ -127,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) {
@@ -153,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/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/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 */