pi-subagents 0.24.3 → 0.25.0

package/src/agents/skills.ts

@@ -6,6 +6,7 @@ import { execSync } from "node:child_process";
 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 type SkillSource =
 	| "project"
@@ -46,11 +47,10 @@ interface SkillSearchPath {
 const skillCache = new Map<string, SkillCacheEntry>();
 const MAX_CACHE_SIZE = 50;
 
-let loadSkillsCache: { cwd: string; skills: CachedSkillEntry[]; timestamp: number } | null = null;
+let loadSkillsCache: { cwd: string; agentDir: string; skills: CachedSkillEntry[]; timestamp: number } | null = null;
 const LOAD_SKILLS_CACHE_TTL_MS = 5000;
 
 const CONFIG_DIR = ".pi";
-const AGENT_DIR = path.join(os.homedir(), ".pi", "agent");
 const SUBAGENT_ORCHESTRATION_SKILL = "pi-subagents";
 
 const SOURCE_PRIORITY: Record<SkillSource, number> = {
@@ -133,10 +133,10 @@ function getGlobalNpmRoot(): string | null {
 	}
 }
 
-function collectInstalledPackageSkillPaths(cwd: string): SkillSearchPath[] {
+function collectInstalledPackageSkillPaths(cwd: string, agentDir: string): SkillSearchPath[] {
 	const dirs: SkillSearchPath[] = [
 		{ path: path.join(cwd, CONFIG_DIR, "npm", "node_modules"), source: "project-package" },
-		{ path: path.join(AGENT_DIR, "npm", "node_modules"), source: "user-package" },
+		{ path: path.join(agentDir, "npm", "node_modules"), source: "user-package" },
 	];
 
 	const globalRoot = getGlobalNpmRoot();
@@ -184,11 +184,11 @@ function collectInstalledPackageSkillPaths(cwd: string): SkillSearchPath[] {
 	return results;
 }
 
-function collectSettingsSkillPaths(cwd: string): SkillSearchPath[] {
+function collectSettingsSkillPaths(cwd: string, agentDir: string): SkillSearchPath[] {
 	const results: SkillSearchPath[] = [];
 	const settingsFiles = [
 		{ file: path.join(cwd, CONFIG_DIR, "settings.json"), base: path.join(cwd, CONFIG_DIR), source: "project-settings" as const },
-		{ file: path.join(AGENT_DIR, "settings.json"), base: AGENT_DIR, source: "user-settings" as const },
+		{ file: path.join(agentDir, "settings.json"), base: agentDir, source: "user-settings" as const },
 	];
 
 	for (const { file, base, source } of settingsFiles) {
@@ -285,10 +285,10 @@ function resolveSettingsPackageRoot(source: string, baseDir: string): string | u
 	return undefined;
 }
 
-function collectSettingsPackageSkillPaths(cwd: string): SkillSearchPath[] {
+function collectSettingsPackageSkillPaths(cwd: string, agentDir: string): SkillSearchPath[] {
 	const settingsFiles = [
 		{ file: path.join(cwd, CONFIG_DIR, "settings.json"), base: path.join(cwd, CONFIG_DIR), source: "project-package" as const },
-		{ file: path.join(AGENT_DIR, "settings.json"), base: AGENT_DIR, source: "user-package" as const },
+		{ file: path.join(agentDir, "settings.json"), base: agentDir, source: "user-package" as const },
 	];
 	const results: SkillSearchPath[] = [];
 
@@ -315,16 +315,16 @@ function collectSettingsPackageSkillPaths(cwd: string): SkillSearchPath[] {
 	return results;
 }
 
-function buildSkillPaths(cwd: string): SkillSearchPath[] {
+function buildSkillPaths(cwd: string, agentDir: string): SkillSearchPath[] {
 	const skillPaths: SkillSearchPath[] = [
 		{ path: path.join(cwd, CONFIG_DIR, "skills"), source: "project" },
 		{ path: path.join(cwd, ".agents", "skills"), source: "project" },
-		{ path: path.join(AGENT_DIR, "skills"), source: "user" },
+		{ path: path.join(agentDir, "skills"), source: "user" },
 		{ path: path.join(os.homedir(), ".agents", "skills"), source: "user" },
-		...collectInstalledPackageSkillPaths(cwd),
-		...collectSettingsPackageSkillPaths(cwd),
+		...collectInstalledPackageSkillPaths(cwd, agentDir),
+		...collectSettingsPackageSkillPaths(cwd, agentDir),
 		...extractSkillPathsFromPackageRoot(cwd, "project-package"),
-		...collectSettingsSkillPaths(cwd),
+		...collectSettingsSkillPaths(cwd, agentDir),
 	];
 
 	const deduped = new Map<string, SkillSearchPath>();
@@ -337,15 +337,16 @@ function buildSkillPaths(cwd: string): SkillSearchPath[] {
 	return [...deduped.values()];
 }
 
-function inferSkillSource(filePath: string, cwd: string, sourceHint?: SkillSource): SkillSource {
+function inferSkillSource(filePath: string, cwd: string, agentDir: string, sourceHint?: SkillSource): SkillSource {
 	if (sourceHint) return sourceHint;
 
 	const projectConfigRoot = path.resolve(cwd, CONFIG_DIR);
 	const projectSkillsRoot = path.resolve(cwd, CONFIG_DIR, "skills");
 	const projectPackagesRoot = path.resolve(cwd, CONFIG_DIR, "npm", "node_modules");
 	const projectAgentsRoot = path.resolve(cwd, ".agents");
-	const userSkillsRoot = path.resolve(AGENT_DIR, "skills");
-	const userPackagesRoot = path.resolve(AGENT_DIR, "npm", "node_modules");
+	const userSkillsRoot = path.resolve(agentDir, "skills");
+	const userPackagesRoot = path.resolve(agentDir, "npm", "node_modules");
+	const userAgentRoot = path.resolve(agentDir);
 	const userAgentsRoot = path.resolve(os.homedir(), ".agents");
 
 	if (isWithinPath(filePath, projectPackagesRoot)) return "project-package";
@@ -354,7 +355,7 @@ function inferSkillSource(filePath: string, cwd: string, sourceHint?: SkillSourc
 
 	if (isWithinPath(filePath, userPackagesRoot)) return "user-package";
 	if (isWithinPath(filePath, userSkillsRoot) || isWithinPath(filePath, userAgentsRoot)) return "user";
-	if (isWithinPath(filePath, AGENT_DIR)) return "user-settings";
+	if (isWithinPath(filePath, userAgentRoot)) return "user-settings";
 
 	const globalRoot = getGlobalNpmRoot();
 	if (globalRoot && isWithinPath(filePath, globalRoot)) return "user-package";
@@ -390,7 +391,7 @@ function maybeReadSkillDescription(filePath: string): string | undefined {
 	}
 }
 
-function collectFilesystemSkills(cwd: string, skillPaths: SkillSearchPath[]): CachedSkillEntry[] {
+function collectFilesystemSkills(cwd: string, agentDir: string, skillPaths: SkillSearchPath[]): CachedSkillEntry[] {
 	const entries: CachedSkillEntry[] = [];
 	const seen = new Set<string>();
 	let order = 0;
@@ -403,7 +404,7 @@ function collectFilesystemSkills(cwd: string, skillPaths: SkillSearchPath[]): Ca
 		entries.push({
 			name,
 			filePath: resolvedFile,
-			source: inferSkillSource(resolvedFile, cwd, sourceHint),
+			source: inferSkillSource(resolvedFile, cwd, agentDir, sourceHint),
 			description: maybeReadSkillDescription(resolvedFile),
 			order: order++,
 		});
@@ -464,12 +465,13 @@ function collectFilesystemSkills(cwd: string, skillPaths: SkillSearchPath[]): Ca
 
 function getCachedSkills(cwd: string): CachedSkillEntry[] {
 	const now = Date.now();
-	if (loadSkillsCache && loadSkillsCache.cwd === cwd && now - loadSkillsCache.timestamp < LOAD_SKILLS_CACHE_TTL_MS) {
+	const agentDir = getAgentDir();
+	if (loadSkillsCache && loadSkillsCache.cwd === cwd && loadSkillsCache.agentDir === agentDir && now - loadSkillsCache.timestamp < LOAD_SKILLS_CACHE_TTL_MS) {
 		return loadSkillsCache.skills;
 	}
 
-	const skillPaths = buildSkillPaths(cwd);
-	const loaded = collectFilesystemSkills(cwd, skillPaths);
+	const skillPaths = buildSkillPaths(cwd, agentDir);
+	const loaded = collectFilesystemSkills(cwd, agentDir, skillPaths);
 	const dedupedByName = new Map<string, CachedSkillEntry>();
 
 	for (const entry of loaded) {
@@ -478,7 +480,7 @@ function getCachedSkills(cwd: string): CachedSkillEntry[] {
 	}
 
 	const skills = [...dedupedByName.values()].sort((a, b) => a.order - b.order);
-	loadSkillsCache = { cwd, skills, timestamp: now };
+	loadSkillsCache = { cwd, agentDir, skills, timestamp: now };
 	return skills;
 }
 

package/src/extension/config.ts

@@ -0,0 +1,16 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionConfig } from "../shared/types.ts";
+import { getAgentDir } from "../shared/utils.ts";
+
+export function loadConfig(): ExtensionConfig {
+	const configPath = path.join(getAgentDir(), "extensions", "subagent", "config.json");
+	try {
+		if (fs.existsSync(configPath)) {
+			return JSON.parse(fs.readFileSync(configPath, "utf-8")) as ExtensionConfig;
+		}
+	} catch (error) {
+		console.error(`Failed to load subagent config from '${configPath}':`, error);
+	}
+	return {};
+}

package/src/extension/fanout-child.ts

@@ -0,0 +1,170 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { discoverAgents } from "../agents/agents.ts";
+import { getArtifactsDir } from "../shared/artifacts.ts";
+import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
+import { SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV } from "../runs/shared/pi-args.ts";
+import { readNestedControlRequests, resolveNestedRouteFromEnv, writeNestedControlResult } from "../runs/shared/nested-events.ts";
+import { deliverSubagentIntercomMessageEvent } from "../intercom/result-intercom.ts";
+import { resolveSubagentIntercomTarget } from "../intercom/intercom-bridge.ts";
+import { SubagentParams } from "./schemas.ts";
+import { loadConfig } from "./config.ts";
+import { type Details, type SubagentState } from "../shared/types.ts";
+
+function getSubagentSessionRoot(parentSessionFile: string | null): string {
+	if (parentSessionFile) {
+		const baseName = path.basename(parentSessionFile, ".jsonl");
+		const sessionsDir = path.dirname(parentSessionFile);
+		return path.join(sessionsDir, baseName);
+	}
+	return fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-session-"));
+}
+
+function expandTilde(p: string): string {
+	return p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p;
+}
+
+function createChildSafeState(): SubagentState {
+	return {
+		baseCwd: "",
+		currentSessionId: null,
+		asyncJobs: new Map(),
+		foregroundRuns: new Map(),
+		foregroundControls: new Map(),
+		lastForegroundControlId: null,
+		pendingForegroundControlNotices: new Map(),
+		cleanupTimers: new Map(),
+		lastUiContext: null,
+		poller: null,
+		completionSeen: new Map(),
+		watcher: null,
+		watcherRestartTimer: null,
+		resultFileCoalescer: {
+			schedule: () => false,
+			clear: () => {},
+		},
+	};
+}
+
+function startNestedControlInboxListener(pi: ExtensionAPI, state: SubagentState): NodeJS.Timeout | undefined {
+	let route;
+	try {
+		route = resolveNestedRouteFromEnv();
+	} catch {
+		return undefined;
+	}
+	if (!route) return undefined;
+	const seen = new Set<string>();
+	const inFlight = new Set<string>();
+	const pendingResults = new Map<string, Parameters<typeof writeNestedControlResult>[1]>();
+	const timer = setInterval(() => {
+		try {
+			for (const request of readNestedControlRequests(route)) {
+				if (seen.has(request.requestId) || inFlight.has(request.requestId)) continue;
+				inFlight.add(request.requestId);
+				void (async () => {
+					try {
+						let result = pendingResults.get(request.requestId);
+						if (!result) {
+							let ok = false;
+							let message = "Control request failed.";
+							try {
+								const control = state.foregroundControls.get(request.targetRunId);
+								if (!control) {
+									message = `Nested run ${request.targetRunId} is not active in this fanout child.`;
+								} else if (request.action === "interrupt") {
+									ok = control.interrupt?.() === true;
+									message = ok
+										? `Interrupt requested for nested run ${request.targetRunId}.`
+										: `Nested run ${request.targetRunId} has no active child step to interrupt.`;
+								} else if (!request.message?.trim()) {
+									message = "Nested resume requires message.";
+								} else if (!control.currentAgent) {
+									message = `Nested run ${request.targetRunId} has no active child message route.`;
+								} else {
+									const index = control.currentIndex ?? 0;
+									const target = resolveSubagentIntercomTarget(request.targetRunId, control.currentAgent, index);
+									ok = await deliverSubagentIntercomMessageEvent(
+										pi.events,
+										target,
+										`Follow-up for nested run ${request.targetRunId} (${control.currentAgent}):\n\n${request.message.trim()}`,
+										500,
+										{ source: "nested-resume", runId: request.targetRunId, agent: control.currentAgent, index },
+									);
+									message = ok
+										? `Delivered follow-up to live nested run ${request.targetRunId}.`
+										: `Nested child intercom target is not registered: ${target}`;
+								}
+							} catch (error) {
+								message = error instanceof Error ? error.message : String(error);
+							}
+							result = { ts: Date.now(), requestId: request.requestId, targetRunId: request.targetRunId, ok, message };
+						}
+						try {
+							writeNestedControlResult(route, result);
+						} catch (error) {
+							pendingResults.set(request.requestId, result);
+							console.error(`Failed to write nested control result for request '${request.requestId}' targeting '${request.targetRunId}' via inbox '${route.controlInbox}'; keeping request for retry:`, error);
+							return;
+						}
+						pendingResults.delete(request.requestId);
+						seen.add(request.requestId);
+						try { fs.unlinkSync(request.filePath); } catch {}
+					} finally {
+						inFlight.delete(request.requestId);
+					}
+				})();
+			}
+		} catch (error) {
+			console.error(`Failed to poll nested control inbox '${route.controlInbox}' for root '${route.rootRunId}':`, error);
+		}
+	}, 200);
+	timer.unref?.();
+	return timer;
+}
+
+export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI): void {
+	if (process.env[SUBAGENT_CHILD_ENV] !== "1" || process.env[SUBAGENT_FANOUT_CHILD_ENV] !== "1") return;
+
+	const globalStore = globalThis as Record<string, unknown>;
+	const registeredKey = "__piSubagentFanoutChildRegisteredApis";
+	const registeredApis = globalStore[registeredKey] instanceof WeakSet
+		? globalStore[registeredKey] as WeakSet<ExtensionAPI>
+		: new WeakSet<ExtensionAPI>();
+	globalStore[registeredKey] = registeredApis;
+	if (registeredApis.has(pi)) return;
+	registeredApis.add(pi);
+
+	const config = loadConfig();
+	const state = createChildSafeState();
+	const executor = createSubagentExecutor({
+		pi,
+		state,
+		config,
+		asyncByDefault: config.asyncByDefault === true,
+		tempArtifactsDir: getArtifactsDir(null),
+		getSubagentSessionRoot,
+		expandTilde,
+		discoverAgents,
+		allowMutatingManagementActions: false,
+	});
+
+	const tool: ToolDefinition<typeof SubagentParams, Details> = {
+		name: "subagent",
+		label: "Subagent",
+		description: [
+			"Delegate to subagents from child-safe fanout mode.",
+			"Allowed management/control actions: list, get, status, interrupt, resume, doctor.",
+			"Agent config mutation actions create, update, and delete are blocked in this mode.",
+		].join("\n"),
+		parameters: SubagentParams,
+		execute(id, params, signal, onUpdate, ctx) {
+			return executor.execute(id, params as SubagentParamsLike, signal, onUpdate, ctx);
+		},
+	};
+
+	pi.registerTool(tool);
+	startNestedControlInboxListener(pi, state);
+}

package/src/extension/index.ts

@@ -22,7 +22,7 @@ import { discoverAgents } from "../agents/agents.ts";
 import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "../shared/artifacts.ts";
 import { resolveCurrentSessionId } from "../shared/session-identity.ts";
 import { cleanupOldChainDirs } from "../shared/settings.ts";
-import { renderWidget, renderSubagentResult, stopResultAnimations, stopWidgetAnimation, syncResultAnimation } from "../tui/render.ts";
+import { clearLegacyResultAnimationTimer, renderWidget, renderSubagentResult } from "../tui/render.ts";
 import { SubagentParams } from "./schemas.ts";
 import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
 import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
@@ -33,11 +33,12 @@ import { registerSlashSubagentBridge } from "../slash/slash-bridge.ts";
 import { clearSlashSnapshots, getSlashRenderableSnapshot, resolveSlashMessageDetails, restoreSlashFinalSnapshots, type SlashMessageDetails } from "../slash/slash-live-state.ts";
 import { inspectSubagentStatus } from "../runs/background/run-status.ts";
 import registerSubagentNotify, { type SubagentNotifyDetails } from "../runs/background/notify.ts";
-import { SUBAGENT_CHILD_ENV } from "../runs/shared/pi-args.ts";
+import { SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV } from "../runs/shared/pi-args.ts";
+import registerFanoutChildSubagentExtension from "./fanout-child.ts";
 import { formatDuration, shortenPath } from "../shared/formatters.ts";
+import { loadConfig } from "./config.ts";
 import {
 	type Details,
-	type ExtensionConfig,
 	type SubagentState,
 	ASYNC_DIR,
 	DEFAULT_ARTIFACT_CONFIG,
@@ -56,6 +57,8 @@ import {
 	type SubagentControlMessageDetails,
 } from "./control-notices.ts";
 
+export { loadConfig } from "./config.ts";
+
 /**
  * Derive subagent session base directory from parent session file.
  * If parent session is ~/.pi/agent/sessions/abc123.jsonl,
@@ -72,18 +75,6 @@ function getSubagentSessionRoot(parentSessionFile: string | null): string {
 	return fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-session-"));
 }
 
-function loadConfig(): ExtensionConfig {
-	const configPath = path.join(os.homedir(), ".pi", "agent", "extensions", "subagent", "config.json");
-	try {
-		if (fs.existsSync(configPath)) {
-			return JSON.parse(fs.readFileSync(configPath, "utf-8")) as ExtensionConfig;
-		}
-	} catch (error) {
-		console.error(`Failed to load subagent config from '${configPath}':`, error);
-	}
-	return {};
-}
-
 function expandTilde(p: string): string {
 	return p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p;
 }
@@ -142,14 +133,11 @@ function createSlashResultComponent(
 	details: SlashMessageDetails,
 	options: { expanded: boolean },
 	theme: ExtensionContext["ui"]["theme"],
-	requestRender: () => void,
 ): Container {
 	const container = new Container();
-	const animationState: { subagentResultAnimationTimer?: ReturnType<typeof setInterval> } = {};
 	let lastVersion = -1;
 	container.render = (width: number): string[] => {
 		const snapshot = getSlashRenderableSnapshot(details);
-		syncResultAnimation(snapshot.result, { state: animationState, invalidate: requestRender });
 		if (snapshot.version !== lastVersion || isSlashResultRunning(snapshot.result)) {
 			lastVersion = snapshot.version;
 			rebuildSlashResultContainer(container, snapshot.result, options, theme);
@@ -220,7 +208,10 @@ class SubagentControlNoticeComponent implements Component {
 }
 
 export default function registerSubagentExtension(pi: ExtensionAPI): void {
-	if (process.env[SUBAGENT_CHILD_ENV] === "1") return;
+	if (process.env[SUBAGENT_CHILD_ENV] === "1") {
+		if (process.env[SUBAGENT_FANOUT_CHILD_ENV] === "1") registerFanoutChildSubagentExtension(pi);
+		return;
+	}
 	const globalStore = globalThis as Record<string, unknown>;
 	const runtimeCleanupStoreKey = "__piSubagentRuntimeCleanup";
 	const previousRuntimeCleanup = globalStore[runtimeCleanupStoreKey];
@@ -271,8 +262,6 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	primeExistingResults();
 
 	const runtimeCleanup = () => {
-		stopWidgetAnimation();
-		stopResultAnimations();
 		stopResultWatcher();
 		clearPendingForegroundControlNotices(state);
 		if (state.poller) {
@@ -297,7 +286,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	pi.registerMessageRenderer<SlashMessageDetails>(SLASH_RESULT_TYPE, (message, options, theme) => {
 		const details = resolveSlashMessageDetails(message.details);
 		if (!details) return undefined;
-		return createSlashResultComponent(details, options, theme, () => state.lastUiContext?.ui.requestRender?.());
+		return createSlashResultComponent(details, options, theme);
 	});
 
 	pi.registerMessageRenderer<SubagentNotifyDetails>("subagent-notify", (message, options, theme) => {
@@ -466,7 +455,7 @@ DIAGNOSTICS:
 		},
 
 		renderResult(result, options, theme, context) {
-			syncResultAnimation(result, context);
+			clearLegacyResultAnimationTimer(context);
 			return renderSubagentResult(result, options, theme);
 		},
 
@@ -514,6 +503,7 @@ DIAGNOSTICS:
 		state.lastUiContext = ctx;
 		if (state.asyncJobs.size > 0) {
 			renderWidget(ctx, Array.from(state.asyncJobs.values()));
+			ctx.ui.requestRender?.();
 			ensurePoller();
 		}
 	});
@@ -569,8 +559,6 @@ DIAGNOSTICS:
 		slashBridge.dispose();
 		promptTemplateBridge.cancelAll();
 		promptTemplateBridge.dispose();
-		stopWidgetAnimation();
-		stopResultAnimations();
 		if (globalStore[runtimeCleanupStoreKey] === runtimeCleanup) {
 			delete globalStore[runtimeCleanupStoreKey];
 		}

package/src/intercom/intercom-bridge.ts

@@ -4,12 +4,13 @@ import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentConfig } from "../agents/agents.ts";
 import type { ExtensionConfig, IntercomBridgeConfig, IntercomBridgeMode } from "../shared/types.ts";
+import { getAgentDir } from "../shared/utils.ts";
 
 const PI_INTERCOM_PACKAGE_NAME = "pi-intercom";
 const CONFIG_DIR = ".pi";
 
 function defaultAgentDir(): string {
-	return path.join(os.homedir(), ".pi", "agent");
+	return getAgentDir();
 }
 
 function defaultIntercomExtensionDir(agentDir = defaultAgentDir()): string {

package/src/intercom/result-intercom.ts

@@ -3,6 +3,8 @@ import * as fs from "node:fs";
 import {
 	type Details,
 	type IntercomEventBus,
+	type NestedRunSummary,
+	type PublicNestedRunSummary,
 	type SingleResult,
 	type SubagentResultIntercomChild,
 	type SubagentResultIntercomPayload,
@@ -60,6 +62,110 @@ function resolveGroupedStatus(children: SubagentResultIntercomChild[]): Subagent
 	return "failed";
 }
 
+function compactNestedRun(run: NestedRunSummary | PublicNestedRunSummary, depth = 0): PublicNestedRunSummary {
+	return {
+		id: run.id,
+		parentRunId: run.parentRunId,
+		...(run.parentStepIndex !== undefined ? { parentStepIndex: run.parentStepIndex } : {}),
+		...(run.parentAgent ? { parentAgent: run.parentAgent } : {}),
+		depth: run.depth,
+		path: run.path.slice(0, 4).map((part) => ({
+			runId: part.runId,
+			...(part.stepIndex !== undefined ? { stepIndex: part.stepIndex } : {}),
+			...(part.agent ? { agent: part.agent } : {}),
+		})),
+		...(run.asyncDir ? { asyncDir: run.asyncDir } : {}),
+		...(run.sessionId ? { sessionId: run.sessionId } : {}),
+		...(run.sessionFile ? { sessionFile: run.sessionFile } : {}),
+		...(run.intercomTarget ? { intercomTarget: run.intercomTarget } : {}),
+		...(run.ownerIntercomTarget ? { ownerIntercomTarget: run.ownerIntercomTarget } : {}),
+		...(run.leafIntercomTarget ? { leafIntercomTarget: run.leafIntercomTarget } : {}),
+		...(run.ownerState ? { ownerState: run.ownerState } : {}),
+		...(run.mode ? { mode: run.mode } : {}),
+		state: run.state,
+		...(run.agent ? { agent: run.agent } : {}),
+		...(run.agents?.length ? { agents: run.agents.slice(0, 12) } : {}),
+		...(run.currentStep !== undefined ? { currentStep: run.currentStep } : {}),
+		...(run.chainStepCount !== undefined ? { chainStepCount: run.chainStepCount } : {}),
+		...(run.parallelGroups?.length ? { parallelGroups: run.parallelGroups.slice(0, 8) } : {}),
+		...(run.activityState ? { activityState: run.activityState } : {}),
+		...(run.lastActivityAt !== undefined ? { lastActivityAt: run.lastActivityAt } : {}),
+		...(run.currentTool ? { currentTool: run.currentTool } : {}),
+		...(run.currentToolStartedAt !== undefined ? { currentToolStartedAt: run.currentToolStartedAt } : {}),
+		...(run.currentPath ? { currentPath: run.currentPath } : {}),
+		...(run.turnCount !== undefined ? { turnCount: run.turnCount } : {}),
+		...(run.toolCount !== undefined ? { toolCount: run.toolCount } : {}),
+		...(run.totalTokens ? { totalTokens: run.totalTokens } : {}),
+		...(run.startedAt !== undefined ? { startedAt: run.startedAt } : {}),
+		...(run.endedAt !== undefined ? { endedAt: run.endedAt } : {}),
+		...(run.lastUpdate !== undefined ? { lastUpdate: run.lastUpdate } : {}),
+		...(run.error ? { error: run.error } : {}),
+		...(run.steps?.length ? { steps: run.steps.slice(0, 12).map((step) => ({
+			agent: step.agent,
+			status: step.status,
+			...(step.sessionFile ? { sessionFile: step.sessionFile } : {}),
+			...(step.activityState ? { activityState: step.activityState } : {}),
+			...(step.lastActivityAt !== undefined ? { lastActivityAt: step.lastActivityAt } : {}),
+			...(step.currentTool ? { currentTool: step.currentTool } : {}),
+			...(step.currentToolStartedAt !== undefined ? { currentToolStartedAt: step.currentToolStartedAt } : {}),
+			...(step.currentPath ? { currentPath: step.currentPath } : {}),
+			...(step.turnCount !== undefined ? { turnCount: step.turnCount } : {}),
+			...(step.toolCount !== undefined ? { toolCount: step.toolCount } : {}),
+			...(step.startedAt !== undefined ? { startedAt: step.startedAt } : {}),
+			...(step.endedAt !== undefined ? { endedAt: step.endedAt } : {}),
+			...(step.error ? { error: step.error } : {}),
+			...(depth < 2 && step.children?.length ? { children: step.children.slice(0, 8).map((child) => compactNestedRun(child, depth + 1)) } : {}),
+		})) } : {}),
+		...(depth < 2 && run.children?.length ? { children: run.children.slice(0, 8).map((child) => compactNestedRun(child, depth + 1)) } : {}),
+	};
+}
+
+export function compactNestedResultChildren(children: Array<NestedRunSummary | PublicNestedRunSummary> | undefined): PublicNestedRunSummary[] | undefined {
+	if (!children?.length) return undefined;
+	return children.slice(0, 16).map((child) => compactNestedRun(child));
+}
+
+export function attachNestedChildrenToResultChildren(
+	runId: string,
+	children: SubagentResultIntercomChild[],
+	nestedChildren: NestedRunSummary[] | undefined,
+): SubagentResultIntercomChild[] {
+	const compact = compactNestedResultChildren(nestedChildren);
+	if (!compact?.length) return children.map((child) => ({ ...child, children: compactNestedResultChildren(child.children) }));
+	return children.map((child, index) => {
+		const childIndex = child.index ?? index;
+		const alreadyAttachedIds = new Set(child.children?.map((nested) => nested.id) ?? []);
+		const attached = compact.filter((nested) => nested.parentRunId === runId && nested.parentStepIndex === childIndex && !alreadyAttachedIds.has(nested.id));
+		const fallbackAttached = children.length === 1
+			? compact.filter((nested) => nested.parentRunId === runId && nested.parentStepIndex === undefined && !alreadyAttachedIds.has(nested.id))
+			: [];
+		const merged = compactNestedResultChildren([...(child.children ?? []), ...attached, ...fallbackAttached]);
+		return merged?.length ? { ...child, children: merged } : { ...child, children: undefined };
+	});
+}
+
+function formatNestedResultLines(children: PublicNestedRunSummary[] | undefined): string[] {
+	if (!children?.length) return [];
+	const lines = ["Nested subagents:"];
+	let remaining = 10;
+	const append = (runs: PublicNestedRunSummary[] | undefined, indent: string): void => {
+		for (const run of runs ?? []) {
+			if (remaining <= 0) {
+				lines.push(`${indent}↳ +more nested runs; inspect status for full tree`);
+				return;
+			}
+			remaining--;
+			const label = run.agent ?? run.agents?.join("+") ?? run.id;
+			lines.push(`${indent}↳ ${label} — ${run.state} [${run.id}]`);
+			if (run.sessionFile) lines.push(`${indent}  Session: ${run.sessionFile}`);
+			append(run.children, `${indent}  `);
+			for (const step of run.steps ?? []) append(step.children, `${indent}    `);
+		}
+	};
+	append(children, "");
+	return lines;
+}
+
 interface GroupedResultIntercomMessageInput {
 	to: string;
 	runId: string;
@@ -128,6 +234,7 @@ function formatSubagentResultIntercomMessage(input: {
 		if (child.intercomTarget) lines.push(`${input.source === "async" ? "Previous intercom target" : "Run intercom target"}: ${child.intercomTarget}`);
 		if (child.artifactPath) lines.push(`Output artifact: ${child.artifactPath}`);
 		if (child.sessionPath) lines.push(`Session: ${child.sessionPath}`);
+		lines.push(...formatNestedResultLines(child.children));
 		lines.push("Summary:");
 		lines.push(child.summary);
 	}
@@ -139,6 +246,7 @@ export function buildSubagentResultIntercomPayload(input: GroupedResultIntercomM
 	const children = input.children.map((child) => ({
 		...child,
 		summary: child.summary.trim() || "(no output)",
+		children: compactNestedResultChildren(child.children),
 	}));
 	const status = resolveGroupedStatus(children);
 	const summary = formatStatusCounts(countStatuses(children));