pi-subagents 0.24.4 → 0.27.0

package/src/agents/chain-serializer.ts

@@ -1,6 +1,9 @@
 import type { ChainConfig, ChainStepConfig } from "./agents.ts";
 import { buildRuntimeName, frontmatterNameForConfig, parsePackageName } from "./identity.ts";
 import { parseFrontmatter } from "./frontmatter.ts";
+import { ChainOutputValidationError, validateChainOutputBindings } from "../runs/shared/chain-outputs.ts";
+import { validateAcceptanceInput } from "../runs/shared/acceptance.ts";
+import type { ChainStep } from "../shared/settings.ts";
 
 function parseStepBody(agent: string, sectionBody: string): ChainStepConfig {
 	const lines = sectionBody.split("\n");
@@ -20,6 +23,25 @@ function parseStepBody(agent: string, sectionBody: string): ChainStepConfig {
 			else if (rawValue) step.output = rawValue;
 			continue;
 		}
+		if (key === "phase") {
+			if (rawValue) step.phase = rawValue;
+			continue;
+		}
+		if (key === "label") {
+			if (rawValue) step.label = rawValue;
+			continue;
+		}
+		if (key === "as") {
+			if (rawValue) step.as = rawValue;
+			continue;
+		}
+		if (key === "outputschema") {
+			if (rawValue.startsWith("{") || rawValue.startsWith("[")) {
+				throw new Error("Inline outputSchema values are not supported in .chain.md files; use a schema file path.");
+			}
+			if (rawValue) step.outputSchema = rawValue;
+			continue;
+		}
 		if (key === "outputmode") {
 			if (rawValue === "inline" || rawValue === "file-only") step.outputMode = rawValue;
 			continue;
@@ -102,6 +124,100 @@ export function parseChain(content: string, source: "user" | "project", filePath
 	};
 }
 
+export function parseJsonChain(content: string, source: "user" | "project", filePath: string): ChainConfig {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(content);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Invalid JSON chain '${filePath}': ${message}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`JSON chain '${filePath}' must contain an object root.`);
+	}
+	const input = parsed as Record<string, unknown>;
+	if (typeof input.name !== "string" || !input.name.trim()) {
+		throw new Error(`JSON chain '${filePath}' must include string name.`);
+	}
+	if (typeof input.description !== "string" || !input.description.trim()) {
+		throw new Error(`JSON chain '${filePath}' must include string description.`);
+	}
+	if (!Array.isArray(input.chain)) {
+		throw new Error(`JSON chain '${filePath}' must include array chain.`);
+	}
+	for (let i = 0; i < input.chain.length; i++) {
+		const step = input.chain[i];
+		if (!step || typeof step !== "object" || Array.isArray(step)) {
+			throw new Error(`JSON chain '${filePath}' step ${i + 1} must be an object.`);
+		}
+		const stepRecord = step as Record<string, unknown>;
+		const parallel = stepRecord.parallel;
+		if (Array.isArray(parallel) && Object.hasOwn(stepRecord, "acceptance")) {
+			throw new Error(`Invalid JSON chain '${filePath}': step ${i + 1} acceptance is not supported on static parallel groups; set acceptance on each parallel task.`);
+		}
+		if (parallel && typeof parallel === "object" && !Array.isArray(parallel) && Object.hasOwn(stepRecord, "acceptance")) {
+			throw new Error(`Invalid JSON chain '${filePath}': step ${i + 1} acceptance is not supported on dynamic fanout groups; set acceptance on the dynamic template.`);
+		}
+		const acceptanceErrors = validateAcceptanceInput(stepRecord.acceptance, `step ${i + 1} acceptance`);
+		if (acceptanceErrors.length > 0) {
+			throw new Error(`Invalid JSON chain '${filePath}': ${acceptanceErrors.join(" ")}`);
+		}
+		if (Array.isArray(parallel)) {
+			for (let taskIndex = 0; taskIndex < parallel.length; taskIndex++) {
+				const task = parallel[taskIndex];
+				if (!task || typeof task !== "object" || Array.isArray(task)) continue;
+				const taskErrors = validateAcceptanceInput((task as Record<string, unknown>).acceptance, `step ${i + 1} parallel task ${taskIndex + 1} acceptance`);
+				if (taskErrors.length > 0) {
+					throw new Error(`Invalid JSON chain '${filePath}': ${taskErrors.join(" ")}`);
+				}
+			}
+		} else if (parallel && typeof parallel === "object") {
+			const templateErrors = validateAcceptanceInput((parallel as Record<string, unknown>).acceptance, `step ${i + 1} dynamic template acceptance`);
+			if (templateErrors.length > 0) {
+				throw new Error(`Invalid JSON chain '${filePath}': ${templateErrors.join(" ")}`);
+			}
+		}
+	}
+	try {
+		validateChainOutputBindings(input.chain as ChainStep[], { maxItems: Number.MAX_SAFE_INTEGER });
+	} catch (error) {
+		if (error instanceof ChainOutputValidationError) throw new Error(`Invalid JSON chain '${filePath}': ${error.message}`);
+		throw error;
+	}
+	const parsedPackage = parsePackageName(typeof input.package === "string" ? input.package : undefined, `Chain '${input.name}' package`);
+	if (parsedPackage.error) throw new Error(parsedPackage.error);
+	const extraFields: Record<string, string> = {};
+	for (const [key, value] of Object.entries(input)) {
+		if (key === "name" || key === "package" || key === "description" || key === "chain") continue;
+		if (typeof value === "string") extraFields[key] = value;
+	}
+	return {
+		name: buildRuntimeName(input.name.trim(), parsedPackage.packageName),
+		localName: input.name.trim(),
+		packageName: parsedPackage.packageName,
+		description: input.description.trim(),
+		source,
+		filePath,
+		steps: input.chain as ChainStepConfig[],
+		extraFields: Object.keys(extraFields).length > 0 ? extraFields : undefined,
+	};
+}
+
+export function serializeJsonChain(config: ChainConfig): string {
+	const root: Record<string, unknown> = {
+		name: frontmatterNameForConfig(config),
+		description: config.description,
+		chain: config.steps,
+	};
+	if (config.packageName) root.package = config.packageName;
+	if (config.extraFields) {
+		for (const [key, value] of Object.entries(config.extraFields)) {
+			if (key !== "name" && key !== "description" && key !== "package" && key !== "chain") root[key] = value;
+		}
+	}
+	return `${JSON.stringify(root, null, 2)}\n`;
+}
+
 export function serializeChain(config: ChainConfig): string {
 	const lines: string[] = [];
 	lines.push("---");
@@ -121,6 +237,10 @@ export function serializeChain(config: ChainConfig): string {
 		lines.push(`## ${step.agent}`);
 		if (step.output === false) lines.push("output: false");
 		else if (step.output) lines.push(`output: ${step.output}`);
+		if (step.phase) lines.push(`phase: ${step.phase}`);
+		if (step.label) lines.push(`label: ${step.label}`);
+		if (step.as) lines.push(`as: ${step.as}`);
+		if (step.outputSchema) lines.push(`outputSchema: ${step.outputSchema}`);
 		if (step.outputMode) lines.push(`outputMode: ${step.outputMode}`);
 		if (step.reads === false) lines.push("reads: false");
 		else if (Array.isArray(step.reads) && step.reads.length > 0) lines.push(`reads: ${step.reads.join(", ")}`);

package/src/extension/fanout-child.ts

@@ -0,0 +1,171 @@
+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.",
+			"For goal-style requests such as /goal, goal, active goal, or work until evidence says done, use explicit acceptance on the delegated run: criteria for the target, evidence/verify for proof, stopRules for constraints, and maxFinalizationTurns for the bounded loop.",
+			"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

@@ -33,7 +33,8 @@ 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 {
@@ -207,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];
@@ -391,6 +395,7 @@ EXECUTION (use exactly ONE mode):
 • CHAIN: { chain: [{agent:"agent-a"}, {parallel:[{agent:"agent-b",count:3}]}] } - sequential pipeline with optional parallel fan-out
 • PARALLEL: { tasks: [{agent,task,count?,output?,reads?,progress?}, ...], concurrency?: number, worktree?: true } - concurrent execution (worktree: isolate each task in a git worktree)
 • Optional context: { context: "fresh" | "fork" } (default: if any requested agent has defaultContext: "fork", the whole invocation uses fork; otherwise "fresh"; inspect agent defaults via { action: "list" })
+• Goal-style requests: when the user says “/goal”, “goal”, “active goal”, “work until evidence says done”, or “verify against a goal”, model that as explicit acceptance. Use acceptance.criteria for the target, acceptance.evidence/verify for proof, acceptance.stopRules for constraints, and acceptance.maxFinalizationTurns for the bounded loop.
 
 CHAIN TEMPLATE VARIABLES (use in task strings):
 • {task} - The original task/request from the user

package/src/extension/schemas.ts

@@ -35,9 +35,82 @@ const ReadsOverride = Type.Unsafe({
 	description: "Files to read before running (array of filenames), or false to disable",
 });
 
+const JsonSchemaObject = Type.Unsafe({
+	type: "object",
+	additionalProperties: true,
+	description: "JSON Schema object for strict structured output. Non-object roots are rejected.",
+});
+
+const AcceptanceEvidenceKind = Type.String({
+	enum: [
+		"changed-files",
+		"tests-added",
+		"commands-run",
+		"validation-output",
+		"residual-risks",
+		"no-staged-files",
+		"diff-summary",
+		"review-findings",
+		"manual-notes",
+	],
+});
+
+const AcceptanceGateSchema = Type.Object({
+	id: Type.String(),
+	must: Type.String(),
+	evidence: Type.Optional(Type.Array(AcceptanceEvidenceKind)),
+	severity: Type.Optional(Type.String({ enum: ["required", "recommended"] })),
+}, { additionalProperties: false });
+
+const AcceptanceVerifyCommandSchema = Type.Object({
+	id: Type.String(),
+	command: Type.String(),
+	timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
+	cwd: Type.Optional(Type.String()),
+	env: Type.Optional(Type.Unsafe({ type: "object", additionalProperties: { type: "string" } })),
+	allowFailure: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+
+const AcceptanceReviewGateSchema = Type.Object({
+	agent: Type.Optional(Type.String()),
+	focus: Type.Optional(Type.String()),
+	required: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+
+const AcceptanceOverride = Type.Unsafe({
+	type: "object",
+	properties: {
+		criteria: {
+			type: "array",
+			items: {
+				anyOf: [
+					{ type: "string" },
+					AcceptanceGateSchema,
+				],
+			},
+		},
+		evidence: { type: "array", items: AcceptanceEvidenceKind },
+		verify: { type: "array", items: AcceptanceVerifyCommandSchema },
+		review: AcceptanceReviewGateSchema,
+		stopRules: { type: "array", items: { type: "string" } },
+		maxFinalizationTurns: { type: "integer", minimum: 1, maximum: 10 },
+	},
+	additionalProperties: false,
+	allOf: [{
+		anyOf: [
+			{ required: ["criteria"] },
+			{ required: ["evidence"] },
+			{ required: ["verify"] },
+			{ required: ["review"] },
+			{ required: ["stopRules"] },
+		],
+	}],
+	description: "Optional acceptance contract. Use this for goal-style requests such as /goal, goal, active goal, or work until evidence says done: criteria define the target, evidence/verify define proof, stopRules define constraints, and maxFinalizationTurns defines the bounded loop. When present, the child must complete a same-session self-review/repair loop before acceptance is evaluated.",
+});
+
 const TaskItem = Type.Object({
-	agent: Type.String(), 
-	task: Type.String(), 
+	agent: Type.String(),
+	task: Type.String(),
 	cwd: Type.Optional(Type.String()),
 	count: Type.Optional(Type.Integer({ minimum: 1, description: "Repeat this parallel task N times with the same settings." })),
 	output: Type.Optional(OutputOverride),
@@ -46,12 +119,17 @@ const TaskItem = Type.Object({
 	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking for this task" })),
 	model: Type.Optional(Type.String({ description: "Override model for this task (e.g. 'google/gemini-3-pro')" })),
 	skill: Type.Optional(SkillOverride),
+	acceptance: Type.Optional(AcceptanceOverride),
 });
 
 // Parallel task item (within a parallel step)
 const ParallelTaskSchema = Type.Object({
 	agent: Type.String(),
 	task: Type.Optional(Type.String({ description: "Task template with {task}, {previous}, {chain_dir} variables. Defaults to {previous}." })),
+	phase: Type.Optional(Type.String({ description: "Optional phase/group label for status and graph rendering." })),
+	label: Type.Optional(Type.String({ description: "Optional user-facing label for this parallel task." })),
+	as: Type.Optional(Type.String({ description: "Optional safe identifier used as {outputs.name} in later chain steps." })),
+	outputSchema: Type.Optional(JsonSchemaObject),
 	cwd: Type.Optional(Type.String()),
 	count: Type.Optional(Type.Integer({ minimum: 1, description: "Repeat this parallel task N times with the same settings." })),
 	output: Type.Optional(OutputOverride),
@@ -60,14 +138,51 @@ const ParallelTaskSchema = Type.Object({
 	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
 	skill: Type.Optional(SkillOverride),
 	model: Type.Optional(Type.String({ description: "Override model for this task" })),
+	acceptance: Type.Optional(AcceptanceOverride),
 });
 
+const DynamicExpandSchema = Type.Object({
+	from: Type.Object({
+		output: Type.String({ description: "Prior named structured output to expand from." }),
+		path: Type.String({ description: "JSON Pointer into the structured output, e.g. /items." }),
+	}, { additionalProperties: false }),
+	item: Type.Optional(Type.String({ description: "Template variable name for each item. Defaults to item." })),
+	key: Type.Optional(Type.String({ description: "JSON Pointer relative to each item for stable child ids." })),
+	maxItems: Type.Optional(Type.Integer({ minimum: 0, description: "Required fanout bound unless configured globally." })),
+	onEmpty: Type.Optional(Type.String({ enum: ["skip", "fail"], description: "Empty input behavior. Defaults to skip." })),
+}, { additionalProperties: false });
+
+const DynamicParallelTemplateSchema = Type.Object({
+	agent: Type.String(),
+	task: Type.Optional(Type.String({ description: "Task template with {item}, {item.path}, {task}, {previous}, {chain_dir}, and {outputs.name} variables." })),
+	phase: Type.Optional(Type.String({ description: "Optional phase/group label for status and graph rendering." })),
+	label: Type.Optional(Type.String({ description: "Optional user-facing label; item templates are supported." })),
+	outputSchema: Type.Optional(JsonSchemaObject),
+	cwd: Type.Optional(Type.String()),
+	output: Type.Optional(OutputOverride),
+	outputMode: Type.Optional(OutputModeOverride),
+	reads: Type.Optional(ReadsOverride),
+	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
+	skill: Type.Optional(SkillOverride),
+	model: Type.Optional(Type.String({ description: "Override model for this task" })),
+	acceptance: Type.Optional(AcceptanceOverride),
+}, { additionalProperties: false });
+
+const DynamicCollectSchema = Type.Object({
+	as: Type.String({ description: "Safe output name for the ordered collected result array." }),
+	outputSchema: Type.Optional(JsonSchemaObject),
+}, { additionalProperties: false });
+
 // Flattened so chain steps do not need an object-shape anyOf/oneOf union.
 const ChainItem = Type.Object({
 	agent: Type.Optional(Type.String({ description: "Sequential step agent name" })),
 	task: Type.Optional(Type.String({
-		description: "Task template with variables: {task}=original request, {previous}=prior step's text response, {chain_dir}=shared folder. Required for first step, defaults to '{previous}' for subsequent steps."
+		description: "Task template with variables: {task}=original request, {previous}=prior step's text response, {chain_dir}=shared folder, {outputs.name}=prior named output. Required for first step, defaults to '{previous}' for subsequent steps."
 	})),
+	phase: Type.Optional(Type.String({ description: "Optional phase/group label for status and graph rendering." })),
+	label: Type.Optional(Type.String({ description: "Optional user-facing label for this chain step." })),
+	as: Type.Optional(Type.String({ description: "Optional safe identifier used as {outputs.name} in later chain steps." })),
+	outputSchema: Type.Optional(JsonSchemaObject),
 	cwd: Type.Optional(Type.String()),
 	output: Type.Optional(OutputOverride),
 	outputMode: Type.Optional(OutputModeOverride),
@@ -75,13 +190,30 @@ const ChainItem = Type.Object({
 	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
 	skill: Type.Optional(SkillOverride),
 	model: Type.Optional(Type.String({ description: "Override model for this step" })),
-	parallel: Type.Optional(Type.Array(ParallelTaskSchema, { minItems: 1, description: "Tasks to run in parallel" })),
+	acceptance: Type.Optional(AcceptanceOverride),
+	parallel: Type.Optional(Type.Unsafe({
+		anyOf: [
+			Type.Array(ParallelTaskSchema, { minItems: 1, description: "Tasks to run in parallel" }),
+			DynamicParallelTemplateSchema,
+		],
+		description: "Static parallel tasks array, or a single dynamic fanout child template when expand/collect are present.",
+	})),
+	expand: Type.Optional(DynamicExpandSchema),
+	collect: Type.Optional(DynamicCollectSchema),
 	concurrency: Type.Optional(Type.Number({ description: "Max concurrent tasks (default: 4)" })),
 	failFast: Type.Optional(Type.Boolean({ description: "Stop on first failure (default: false)" })),
 	worktree: Type.Optional(Type.Boolean({
 		description: "Create isolated git worktrees for each parallel task."
 	})),
-}, { description: "Chain step: use {agent, task?, ...} for sequential or {parallel: [...]} for concurrent execution" });
+}, {
+	description: "Chain step: use {agent, task?, ...} for sequential, {parallel: [...]} for static concurrent execution, or {expand, parallel: {...}, collect} for dynamic fanout.",
+	additionalProperties: false,
+	allOf: [
+		{ if: { required: ["expand"] }, then: { required: ["parallel", "collect"], properties: { parallel: { type: "object" } } } },
+		{ if: { required: ["collect"] }, then: { required: ["expand", "parallel"], properties: { parallel: { type: "object" } } } },
+		{ not: { required: ["expand"], properties: { parallel: { type: "array", items: {} } } } },
+	],
+});
 
 const ControlOverrides = Type.Object({
 	enabled: Type.Optional(Type.Boolean({ description: "Enable/disable subagent control attention tracking for this run" })),
@@ -165,4 +297,5 @@ export const SubagentParams = Type.Object({
 	outputMode: Type.Optional(OutputModeOverride),
 	skill: Type.Optional(SkillOverride),
 	model: Type.Optional(Type.String({ description: "Override model for single agent (e.g. 'anthropic/claude-sonnet-4')" })),
+	acceptance: Type.Optional(AcceptanceOverride),
 });

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));