pi-subagents 0.25.0 → 0.27.0

package/src/runs/shared/acceptance-reports.ts

@@ -0,0 +1,127 @@
+import type {
+	AcceptanceReport,
+} from "../../shared/types.ts";
+
+function extractBalancedJson(text: string, start: number): string | undefined {
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	for (let i = start; i < text.length; i++) {
+		const char = text[i]!;
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === "\"") inString = false;
+			continue;
+		}
+		if (char === "\"") {
+			inString = true;
+			continue;
+		}
+		if (char === "{") depth++;
+		if (char === "}") {
+			depth--;
+			if (depth === 0) return text.slice(start, i + 1);
+		}
+	}
+	return undefined;
+}
+
+export function parseAcceptanceReport(output: string): { report?: AcceptanceReport; error?: string } {
+	const fenced = [...output.matchAll(/```acceptance-report\s*\n([\s\S]*?)```/gi)]
+		.map((match) => match[1]?.trim())
+		.filter((value): value is string => Boolean(value));
+	const parseErrors: string[] = [];
+	for (const body of fenced) {
+		try {
+			const parsed = JSON.parse(body) as unknown;
+			const report = (parsed && typeof parsed === "object" && "acceptance" in parsed)
+				? (parsed as { acceptance?: unknown }).acceptance
+				: parsed;
+			if (isAcceptanceReport(report)) return { report };
+			parseErrors.push("acceptance-report block does not contain a valid acceptance report");
+		} catch (error) {
+			parseErrors.push(error instanceof Error ? error.message : String(error));
+		}
+	}
+	if (parseErrors.length > 0) return { error: `Failed to parse acceptance-report: ${parseErrors.join("; ")}` };
+	const markerIndex = output.search(/ACCEPTANCE_REPORT\s*:/i);
+	if (markerIndex !== -1) {
+		const jsonStart = output.indexOf("{", markerIndex);
+		if (jsonStart !== -1) {
+			const json = extractBalancedJson(output, jsonStart);
+			if (json) {
+				try {
+					const parsed = JSON.parse(json) as unknown;
+					if (isAcceptanceReport(parsed)) return { report: parsed };
+				} catch (error) {
+					return { error: error instanceof Error ? error.message : String(error) };
+				}
+			}
+		}
+	}
+	return { error: "Structured acceptance report not found." };
+}
+
+export function stripAcceptanceReport(output: string): string {
+	return output
+		.replace(/\n?```acceptance-report\s*\n[\s\S]*?```\s*$/i, "")
+		.replace(/\n?ACCEPTANCE_REPORT\s*:\s*\{[\s\S]*\}\s*$/i, "")
+		.trimEnd();
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function isCriterionReport(value: unknown): value is NonNullable<AcceptanceReport["criteriaSatisfied"]>[number] {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const criterion = value as { id?: unknown; status?: unknown; evidence?: unknown };
+	if (criterion.id !== undefined && typeof criterion.id !== "string") return false;
+	if (criterion.status !== "satisfied" && criterion.status !== "not-satisfied" && criterion.status !== "not-applicable") return false;
+	return typeof criterion.evidence === "string" && criterion.evidence.trim().length > 0;
+}
+
+function isCommandReport(value: unknown): value is NonNullable<AcceptanceReport["commandsRun"]>[number] {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const command = value as { command?: unknown; result?: unknown; summary?: unknown };
+	return typeof command.command === "string"
+		&& (command.result === "passed" || command.result === "failed" || command.result === "not-run")
+		&& typeof command.summary === "string";
+}
+
+function isAcceptanceReport(value: unknown): value is AcceptanceReport {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const report = value as {
+		criteriaSatisfied?: unknown;
+		changedFiles?: unknown;
+		testsAddedOrUpdated?: unknown;
+		commandsRun?: unknown;
+		validationOutput?: unknown;
+		residualRisks?: unknown;
+		noStagedFiles?: unknown;
+		diffSummary?: unknown;
+		reviewFindings?: unknown;
+		manualNotes?: unknown;
+		notes?: unknown;
+	};
+	if (report.criteriaSatisfied !== undefined && (!Array.isArray(report.criteriaSatisfied) || !report.criteriaSatisfied.every(isCriterionReport))) return false;
+	if (report.changedFiles !== undefined && !isStringArray(report.changedFiles)) return false;
+	if (report.testsAddedOrUpdated !== undefined && !isStringArray(report.testsAddedOrUpdated)) return false;
+	if (report.commandsRun !== undefined && (!Array.isArray(report.commandsRun) || !report.commandsRun.every(isCommandReport))) return false;
+	if (report.validationOutput !== undefined && !isStringArray(report.validationOutput)) return false;
+	if (report.residualRisks !== undefined && !isStringArray(report.residualRisks)) return false;
+	if (report.noStagedFiles !== undefined && typeof report.noStagedFiles !== "boolean") return false;
+	if (report.diffSummary !== undefined && typeof report.diffSummary !== "string") return false;
+	if (report.reviewFindings !== undefined && !isStringArray(report.reviewFindings)) return false;
+	if (report.manualNotes !== undefined && typeof report.manualNotes !== "string") return false;
+	if (report.notes !== undefined && typeof report.notes !== "string") return false;
+	return report.criteriaSatisfied !== undefined
+		|| report.changedFiles !== undefined
+		|| report.testsAddedOrUpdated !== undefined
+		|| report.commandsRun !== undefined
+		|| report.residualRisks !== undefined
+		|| report.manualNotes !== undefined
+		|| report.reviewFindings !== undefined;
+}
+

package/src/runs/shared/acceptance.ts

@@ -0,0 +1,22 @@
+export {
+	acceptanceSelfReviewConfig,
+	formatAcceptancePrompt,
+	resolveEffectiveAcceptance,
+	shouldRunAcceptanceFinalization,
+	validateAcceptanceInput,
+} from "./acceptance-contract.ts";
+export {
+	parseAcceptanceReport,
+	stripAcceptanceReport,
+} from "./acceptance-reports.ts";
+export {
+	acceptanceFailureMessage,
+	evaluateAcceptance,
+} from "./acceptance-evaluation.ts";
+export {
+	attachFinalizationToLedger,
+	buildFinalizationProcessFailureLedger,
+	createFinalizationProcessFailureTurn,
+	createFinalizationTurn,
+	formatAcceptanceFinalizationPrompt,
+} from "./acceptance-finalization.ts";

package/src/runs/shared/chain-outputs.ts

@@ -0,0 +1,101 @@
+import { isDynamicParallelStep, isParallelStep, type ChainStep, type SequentialStep } from "../../shared/settings.ts";
+import type { ChainOutputMap, ChainOutputMapEntry, SingleResult } from "../../shared/types.ts";
+import { getSingleResultOutput } from "../../shared/utils.ts";
+import { DynamicFanoutError, hasDynamicFanoutFields, type DynamicFanoutConfig, validateDynamicStepShape } from "./dynamic-fanout.ts";
+
+const OUTPUT_REF_PATTERN = /\{outputs\.([^}]*)\}/g;
+const SAFE_OUTPUT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export class ChainOutputValidationError extends Error {}
+
+function outputNamesForStep(step: ChainStep): string[] {
+	if (isParallelStep(step)) return step.parallel.map((task) => task.as).filter((name): name is string => Boolean(name));
+	if (isDynamicParallelStep(step)) return [step.collect.as];
+	const name = (step as SequentialStep).as;
+	return name ? [name] : [];
+}
+
+function taskTemplatesForStep(step: ChainStep): string[] {
+	if (isParallelStep(step)) return step.parallel.map((task) => task.task ?? "{previous}");
+	if (isDynamicParallelStep(step)) return [step.parallel.task ?? "{previous}", step.parallel.label ?? ""].filter(Boolean);
+	return [(step as SequentialStep).task ?? "{previous}"];
+}
+
+export function validateChainOutputBindings(steps: ChainStep[], dynamicFanoutConfig: DynamicFanoutConfig = {}): void {
+	const available = new Set<string>();
+	const seen = new Set<string>();
+	for (let stepIndex = 0; stepIndex < steps.length; stepIndex++) {
+		const step = steps[stepIndex]!;
+		if (hasDynamicFanoutFields(step)) {
+			if (!isDynamicParallelStep(step)) {
+				throw new ChainOutputValidationError(`Dynamic chain step ${stepIndex + 1} requires expand, a single parallel template object, and collect; dynamic expand/collect cannot be mixed with static parallel arrays.`);
+			}
+			try {
+				validateDynamicStepShape(step, stepIndex, dynamicFanoutConfig);
+			} catch (error) {
+				if (error instanceof DynamicFanoutError) throw new ChainOutputValidationError(error.message);
+				throw error;
+			}
+			if (!available.has(step.expand.from.output)) {
+				throw new ChainOutputValidationError(`Dynamic chain step ${stepIndex + 1} references unknown output '${step.expand.from.output}'. Named outputs are only available after producing step/group completes.`);
+			}
+		}
+		for (const name of outputNamesForStep(step)) {
+			if (!SAFE_OUTPUT_NAME_PATTERN.test(name)) {
+				throw new ChainOutputValidationError(`Invalid chain output name '${name}' at step ${stepIndex + 1}. Use /^[A-Za-z_][A-Za-z0-9_]*$/.`);
+			}
+			if (seen.has(name)) {
+				throw new ChainOutputValidationError(`Duplicate chain output name '${name}'. Each as name must be unique.`);
+			}
+			seen.add(name);
+		}
+		for (const template of taskTemplatesForStep(step)) {
+			for (const match of template.matchAll(OUTPUT_REF_PATTERN)) {
+				const rawReference = match[0];
+				const name = match[1]!;
+				if (!SAFE_OUTPUT_NAME_PATTERN.test(name)) {
+					throw new ChainOutputValidationError(`Invalid chain output reference '${rawReference}' at step ${stepIndex + 1}. Use {outputs.name} with /^[A-Za-z_][A-Za-z0-9_]*$/ names.`);
+				}
+				if (!available.has(name)) {
+					throw new ChainOutputValidationError(`Unknown chain output reference '${rawReference}' at step ${stepIndex + 1}. Named outputs are only available after producing step/group completes.`);
+				}
+			}
+		}
+		for (const name of outputNamesForStep(step)) {
+			available.add(name);
+		}
+	}
+}
+
+export function resolveOutputReferences(template: string, outputs: ChainOutputMap): string {
+	return template.replace(OUTPUT_REF_PATTERN, (rawReference, name: string) => {
+		if (!SAFE_OUTPUT_NAME_PATTERN.test(name)) {
+			throw new ChainOutputValidationError(`Invalid chain output reference '${rawReference}'. Use {outputs.name} with /^[A-Za-z_][A-Za-z0-9_]*$/ names.`);
+		}
+		const entry = outputs[name];
+		if (!entry) throw new ChainOutputValidationError(`Unknown chain output reference '${rawReference}'.`);
+		return entry.text;
+	});
+}
+
+function compactStructuredText(value: unknown): string {
+	return JSON.stringify(value);
+}
+
+export function outputEntryFromResult(result: SingleResult, stepIndex: number): ChainOutputMapEntry {
+	return {
+		text: result.structuredOutput !== undefined ? compactStructuredText(result.structuredOutput) : getSingleResultOutput(result),
+		...(result.structuredOutput !== undefined ? { structured: result.structuredOutput } : {}),
+		agent: result.agent,
+		stepIndex,
+	};
+}
+
+export function outputEntryFromAsyncResult(result: { agent: string; output: string; structuredOutput?: unknown }, stepIndex: number): ChainOutputMapEntry {
+	return {
+		text: result.structuredOutput !== undefined ? compactStructuredText(result.structuredOutput) : result.output,
+		...(result.structuredOutput !== undefined ? { structured: result.structuredOutput } : {}),
+		agent: result.agent,
+		stepIndex,
+	};
+}

package/src/runs/shared/completion-guard.ts

@@ -66,6 +66,17 @@ const READ_ONLY_BUILTIN_TOOLS = new Set([
 	"contact_supervisor",
 ]);
 
+export type CompletionPolicy = "none" | "mutation-guard" | "acceptance-contract";
+
+interface CompletionPolicyInput {
+	agent: string;
+	task: string;
+	completionGuardEnabled: boolean;
+	usesAcceptanceContract: boolean;
+	tools?: string[];
+	mcpDirectTools?: string[];
+}
+
 interface CompletionMutationGuardInput {
 	agent: string;
 	task: string;
@@ -134,10 +145,22 @@ export function hasMutationToolCall(messages: Message[]): boolean {
 	return false;
 }
 
+export function resolveCompletionPolicy(input: CompletionPolicyInput): CompletionPolicy {
+	if (input.usesAcceptanceContract) return "acceptance-contract";
+	if (!input.completionGuardEnabled) return "none";
+	if (declaresOnlyReadOnlyTools(input.tools, input.mcpDirectTools)) return "none";
+	return expectsImplementationMutation(input.agent, input.task) ? "mutation-guard" : "none";
+}
+
 export function evaluateCompletionMutationGuard(input: CompletionMutationGuardInput): CompletionMutationGuardResult {
-	const expectedMutation = declaresOnlyReadOnlyTools(input.tools, input.mcpDirectTools)
-		? false
-		: expectsImplementationMutation(input.agent, input.task);
+	const expectedMutation = resolveCompletionPolicy({
+		agent: input.agent,
+		task: input.task,
+		completionGuardEnabled: true,
+		usesAcceptanceContract: false,
+		tools: input.tools,
+		mcpDirectTools: input.mcpDirectTools,
+	}) === "mutation-guard";
 	const attemptedMutation = hasMutationToolCall(input.messages);
 	return {
 		expectedMutation,

package/src/runs/shared/dynamic-fanout.ts

@@ -0,0 +1,293 @@
+import type { DynamicParallelStep, ParallelTaskItem } from "../../shared/settings.ts";
+import type { ArtifactPaths, ChainOutputMap, JsonSchemaObject, SingleResult } from "../../shared/types.ts";
+import { getSingleResultOutput } from "../../shared/utils.ts";
+import { validateStructuredOutputValue } from "./structured-output.ts";
+
+export class DynamicFanoutError extends Error {}
+
+export interface DynamicFanoutConfig {
+	maxItems?: number;
+	allowRunnerFields?: boolean;
+}
+
+export interface DynamicMaterializedItem {
+	index: number;
+	key: string;
+	idKey: string;
+	item: unknown;
+}
+
+export interface DynamicCollectedResult {
+	key: string;
+	index: number;
+	item: unknown;
+	agent: string;
+	exitCode: number | null;
+	text: string;
+	structured?: unknown;
+	error?: string;
+	outputPath?: string;
+	artifactPaths?: ArtifactPaths;
+}
+
+export interface DynamicMaterializedGroup {
+	items: DynamicMaterializedItem[];
+	parallel: ParallelTaskItem[];
+	collectedOnEmpty?: DynamicCollectedResult[];
+}
+
+const SAFE_OUTPUT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ITEM_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ITEM_REF_PATTERN = /\{([A-Za-z_][A-Za-z0-9_]*)(?:\.([^{}]+))?\}/g;
+const RESERVED_TEMPLATE_NAMES = new Set(["task", "previous", "chain_dir", "outputs"]);
+const DYNAMIC_STEP_KEYS = new Set(["expand", "parallel", "collect", "concurrency", "failFast", "phase", "label", "acceptance"]);
+const RUNNER_DYNAMIC_STEP_KEYS = new Set([...DYNAMIC_STEP_KEYS, "effectiveAcceptance"]);
+const DYNAMIC_EXPAND_KEYS = new Set(["from", "item", "key", "maxItems", "onEmpty"]);
+const DYNAMIC_EXPAND_FROM_KEYS = new Set(["output", "path"]);
+const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "acceptance"]);
+const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
+	...DYNAMIC_PARALLEL_KEYS,
+	"outputName", "structured", "inheritProjectContext", "inheritSkills", "skills", "outputPath", "maxSubagentDepth",
+	"structuredOutput", "structuredOutputSchema", "tools", "extensions", "mcpDirectTools", "completionGuard", "systemPrompt",
+	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance",
+]);
+const DYNAMIC_COLLECT_KEYS = new Set(["as", "outputSchema"]);
+
+export function isSafeOutputName(name: string): boolean {
+	return SAFE_OUTPUT_NAME_PATTERN.test(name);
+}
+
+export function assertJsonPointer(pointer: string, label: string): void {
+	if (pointer === "") return;
+	if (!pointer.startsWith("/")) {
+		throw new DynamicFanoutError(`${label} must be a JSON Pointer starting with '/'.`);
+	}
+	for (const segment of pointer.slice(1).split("/")) {
+		if (/~(?![01])/.test(segment)) {
+			throw new DynamicFanoutError(`${label} contains invalid JSON Pointer escape.`);
+		}
+	}
+}
+
+function decodePointerSegment(segment: string): string {
+	return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+export function resolveJsonPointer(value: unknown, pointer: string, label: string): unknown {
+	assertJsonPointer(pointer, label);
+	if (pointer === "") return value;
+	let current = value;
+	for (const rawSegment of pointer.slice(1).split("/")) {
+		const segment = decodePointerSegment(rawSegment);
+		if (Array.isArray(current)) {
+			if (!/^(0|[1-9][0-9]*)$/.test(segment)) {
+				throw new DynamicFanoutError(`${label} segment '${segment}' does not address an array index.`);
+			}
+			const index = Number(segment);
+			if (index >= current.length) throw new DynamicFanoutError(`${label} does not exist.`);
+			current = current[index];
+			continue;
+		}
+		if (!current || typeof current !== "object") {
+			throw new DynamicFanoutError(`${label} does not exist.`);
+		}
+		const record = current as Record<string, unknown>;
+		if (!Object.prototype.hasOwnProperty.call(record, segment)) {
+			throw new DynamicFanoutError(`${label} does not exist.`);
+		}
+		current = record[segment];
+	}
+	return current;
+}
+
+function scalarToKey(value: unknown, label: string): string {
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+		const key = String(value);
+		if (!key.trim()) throw new DynamicFanoutError(`${label} resolved to an empty key.`);
+		if (/[\u0000-\u001F\u007F]/.test(key)) throw new DynamicFanoutError(`${label} resolved to an unsafe key.`);
+		if (key.length > 200) throw new DynamicFanoutError(`${label} resolved to a key longer than 200 characters.`);
+		return key;
+	}
+	throw new DynamicFanoutError(`${label} must resolve to a string, number, or boolean.`);
+}
+
+export function normalizeItemKeyForId(key: string): string {
+	const normalized = key
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, 80);
+	return normalized || "item";
+}
+
+function valueToTemplateText(value: unknown, reference: string): string {
+	if (value === undefined) throw new DynamicFanoutError(`Unresolved item reference '${reference}'.`);
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || value === null) return String(value);
+	return JSON.stringify(value);
+}
+
+function resolveItemPath(item: unknown, pathText: string | undefined, reference: string): unknown {
+	if (!pathText) return item;
+	const pointer = `/${pathText.split(".").map((segment) => segment.replace(/~/g, "~0").replace(/\//g, "~1")).join("/")}`;
+	return resolveJsonPointer(item, pointer, reference);
+}
+
+export function resolveItemTemplate(template: string, itemName: string, item: unknown): string {
+	return template.replace(ITEM_REF_PATTERN, (raw, name: string, pathText: string | undefined) => {
+		if (name !== itemName) return raw;
+		if (pathText !== undefined && (!pathText.trim() || pathText.includes(".."))) {
+			throw new DynamicFanoutError(`Invalid item reference '${raw}'.`);
+		}
+		return valueToTemplateText(resolveItemPath(item, pathText, raw), raw);
+	});
+}
+
+function assertOnlyKeys(value: unknown, allowed: Set<string>, label: string): void {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new DynamicFanoutError(`${label} must be an object.`);
+	for (const key of Object.keys(value)) {
+		if (!allowed.has(key)) throw new DynamicFanoutError(`${label} does not support field '${key}'.`);
+	}
+}
+
+export function assertNoUnresolvedItemReferences(template: string, itemName: string, label: string): void {
+	for (const match of template.matchAll(/\{([^{}]*)\}/g)) {
+		const raw = match[0]!;
+		const reference = match[1]!;
+		if (reference === itemName || reference.startsWith(`${itemName}.`)) {
+			if (!ITEM_REF_PATTERN.test(raw) || reference === `${itemName}.` || reference.includes("..")) {
+				throw new DynamicFanoutError(`Invalid item reference '${raw}' in ${label}.`);
+			}
+			ITEM_REF_PATTERN.lastIndex = 0;
+			continue;
+		}
+		ITEM_REF_PATTERN.lastIndex = 0;
+		const name = reference.match(/^[A-Za-z_][A-Za-z0-9_]*/)?.[0];
+		if (name === itemName) throw new DynamicFanoutError(`Invalid item reference '${raw}' in ${label}.`);
+		if (name && RESERVED_TEMPLATE_NAMES.has(name)) continue;
+		if (name) throw new DynamicFanoutError(`Unsupported template reference '${raw}' in ${label}.`);
+	}
+	ITEM_REF_PATTERN.lastIndex = 0;
+	if (template.includes(`{${itemName}.}`) || new RegExp(`\\{${itemName}(?:\\.|$)[^}]*$`).test(template)) {
+		throw new DynamicFanoutError(`Invalid item reference in ${label}.`);
+	}
+}
+
+export function hasDynamicFanoutFields(step: unknown): boolean {
+	return !!step && typeof step === "object" && !Array.isArray(step)
+		&& (Object.prototype.hasOwnProperty.call(step, "expand") || Object.prototype.hasOwnProperty.call(step, "collect"));
+}
+
+export function validateDynamicStepShape(step: DynamicParallelStep, stepIndex: number, config: DynamicFanoutConfig = {}): void {
+	const prefix = `Dynamic chain step ${stepIndex + 1}`;
+	assertOnlyKeys(step, config.allowRunnerFields ? RUNNER_DYNAMIC_STEP_KEYS : DYNAMIC_STEP_KEYS, prefix);
+	if (!step.expand || !step.expand.from) throw new DynamicFanoutError(`${prefix} requires expand.from.`);
+	assertOnlyKeys(step.expand, DYNAMIC_EXPAND_KEYS, `${prefix} expand`);
+	assertOnlyKeys(step.expand.from, DYNAMIC_EXPAND_FROM_KEYS, `${prefix} expand.from`);
+	if (!isSafeOutputName(step.expand.from.output)) throw new DynamicFanoutError(`${prefix} has invalid expand.from.output '${step.expand.from.output}'.`);
+	assertJsonPointer(step.expand.from.path, `${prefix} expand.from.path`);
+	if (step.expand.key !== undefined) assertJsonPointer(step.expand.key, `${prefix} expand.key`);
+	const itemName = step.expand.item ?? "item";
+	if (!ITEM_NAME_PATTERN.test(itemName)) throw new DynamicFanoutError(`${prefix} has invalid expand.item '${itemName}'.`);
+	if (step.expand.maxItems === undefined && config.maxItems === undefined) {
+		throw new DynamicFanoutError(`${prefix} requires expand.maxItems or config.chain.dynamicFanout.maxItems.`);
+	}
+	if (step.expand.maxItems !== undefined && (!Number.isInteger(step.expand.maxItems) || step.expand.maxItems < 0)) {
+		throw new DynamicFanoutError(`${prefix} expand.maxItems must be an integer >= 0.`);
+	}
+	if (config.maxItems !== undefined && (!Number.isInteger(config.maxItems) || config.maxItems < 0)) {
+		throw new DynamicFanoutError("config.chain.dynamicFanout.maxItems must be an integer >= 0.");
+	}
+	if (!step.parallel || Array.isArray(step.parallel)) throw new DynamicFanoutError(`${prefix} requires a single parallel template object and cannot mix dynamic expand/collect with static parallel arrays.`);
+	assertOnlyKeys(step.parallel, config.allowRunnerFields ? RUNNER_DYNAMIC_PARALLEL_KEYS : DYNAMIC_PARALLEL_KEYS, `${prefix} parallel`);
+	if ("expand" in (step.parallel as object)) throw new DynamicFanoutError(`${prefix} does not support nested dynamic fanout.`);
+	if (!step.parallel.agent) throw new DynamicFanoutError(`${prefix} parallel.agent is required.`);
+	if (!step.collect?.as || !isSafeOutputName(step.collect.as)) throw new DynamicFanoutError(`${prefix} requires collect.as with a safe output name.`);
+	assertOnlyKeys(step.collect, DYNAMIC_COLLECT_KEYS, `${prefix} collect`);
+	for (const [label, template] of [
+		["parallel.task", step.parallel.task],
+		["parallel.label", step.parallel.label],
+	] as const) {
+		if (template) assertNoUnresolvedItemReferences(template, itemName, `${prefix} ${label}`);
+	}
+}
+
+export function resolveDynamicFanoutItems(step: DynamicParallelStep, outputs: ChainOutputMap, stepIndex: number, config: DynamicFanoutConfig = {}): DynamicMaterializedItem[] {
+	validateDynamicStepShape(step, stepIndex, config);
+	const sourceName = step.expand.from.output;
+	const source = outputs[sourceName];
+	if (!source) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} references unknown output '${sourceName}'.`);
+	if (source.structured === undefined) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} requires structured output '${sourceName}'.`);
+	const value = resolveJsonPointer(source.structured, step.expand.from.path, `Dynamic chain step ${stepIndex + 1} expand.from.path`);
+	if (!Array.isArray(value)) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} expand.from.path must resolve to an array.`);
+	const maxItems = step.expand.maxItems ?? config.maxItems;
+	if (maxItems === undefined) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} requires an effective maxItems.`);
+	if (value.length > maxItems) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} resolved ${value.length} items, exceeding maxItems ${maxItems}.`);
+	const seen = new Set<string>();
+	const seenIds = new Set<string>();
+	return value.map((item, index) => {
+		const key = step.expand.key === undefined
+			? String(index)
+			: scalarToKey(resolveJsonPointer(item, step.expand.key, `Dynamic chain step ${stepIndex + 1} expand.key`), `Dynamic chain step ${stepIndex + 1} expand.key`);
+		if (seen.has(key)) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} produced duplicate item key '${key}'.`);
+		seen.add(key);
+		const idKey = normalizeItemKeyForId(key);
+		if (seenIds.has(idKey)) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} produced colliding item id '${idKey}'.`);
+		seenIds.add(idKey);
+		return { index, key, idKey, item };
+	});
+}
+
+export function materializeDynamicParallelStep(step: DynamicParallelStep, outputs: ChainOutputMap, stepIndex: number, config: DynamicFanoutConfig = {}): DynamicMaterializedGroup {
+	const items = resolveDynamicFanoutItems(step, outputs, stepIndex, config);
+	if (items.length === 0) {
+		if ((step.expand.onEmpty ?? "skip") === "fail") {
+			throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} source array is empty.`);
+		}
+		return { items, parallel: [], collectedOnEmpty: [] };
+	}
+	const itemName = step.expand.item ?? "item";
+	const parallel = items.map((entry) => {
+		const task = resolveItemTemplate(step.parallel.task ?? "{previous}", itemName, entry.item);
+		const label = step.parallel.label ? resolveItemTemplate(step.parallel.label, itemName, entry.item) : undefined;
+		return {
+			...step.parallel,
+			task,
+			...(label !== undefined ? { label } : {}),
+		};
+	});
+	return { items, parallel };
+}
+
+export function collectDynamicResults(
+	step: DynamicParallelStep,
+	items: DynamicMaterializedItem[],
+	results: Array<Pick<SingleResult, "agent" | "exitCode" | "error" | "structuredOutput" | "artifactPaths" | "savedOutputPath"> & { output?: string; finalOutput?: string }>,
+): DynamicCollectedResult[] {
+	return items.map((entry, index) => {
+		const result = results[index];
+		const text = result
+			? ("output" in result && typeof result.output === "string" ? result.output : getSingleResultOutput(result as SingleResult))
+			: "";
+		return {
+			key: entry.key,
+			index: entry.index,
+			item: entry.item,
+			agent: result?.agent ?? step.parallel.agent,
+			exitCode: result?.exitCode ?? null,
+			text,
+			...(result?.structuredOutput !== undefined ? { structured: result.structuredOutput } : {}),
+			...(result?.error ? { error: result.error } : {}),
+			...(result?.savedOutputPath ? { outputPath: result.savedOutputPath } : {}),
+			...(result?.artifactPaths ? { artifactPaths: result.artifactPaths } : {}),
+		};
+	});
+}
+
+export function validateDynamicCollection(schema: JsonSchemaObject | undefined, value: DynamicCollectedResult[]): void {
+	if (!schema) return;
+	const validation = validateStructuredOutputValue(schema, value);
+	if (validation.status === "invalid") {
+		throw new DynamicFanoutError(`Collected output validation failed: ${validation.message}`);
+	}
+}

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

@@ -1,6 +1,13 @@
+import type { DynamicCollectSpec, DynamicExpandSpec } from "../../shared/settings.ts";
+import type { JsonSchemaObject, ResolvedAcceptanceConfig } from "../../shared/types.ts";
+
 export interface RunnerSubagentStep {
 	agent: string;
 	task: string;
+	phase?: string;
+	label?: string;
+	outputName?: string;
+	structured?: boolean;
 	cwd?: string;
 	model?: string;
 	thinking?: string;
@@ -18,6 +25,13 @@ export interface RunnerSubagentStep {
 	outputMode?: "inline" | "file-only";
 	sessionFile?: string;
 	maxSubagentDepth?: number;
+	structuredOutput?: {
+		schema: JsonSchemaObject;
+		schemaPath: string;
+		outputPath: string;
+	};
+	structuredOutputSchema?: JsonSchemaObject;
+	effectiveAcceptance?: ResolvedAcceptanceConfig;
 }
 
 export interface ParallelStepGroup {
@@ -27,17 +41,33 @@ export interface ParallelStepGroup {
 	worktree?: boolean;
 }
 
-export type RunnerStep = RunnerSubagentStep | ParallelStepGroup;
+export interface DynamicRunnerGroup {
+	expand: DynamicExpandSpec;
+	parallel: RunnerSubagentStep;
+	collect: DynamicCollectSpec;
+	concurrency?: number;
+	failFast?: boolean;
+	phase?: string;
+	label?: string;
+}
+
+export type RunnerStep = RunnerSubagentStep | ParallelStepGroup | DynamicRunnerGroup;
 
 export function isParallelGroup(step: RunnerStep): step is ParallelStepGroup {
 	return "parallel" in step && Array.isArray(step.parallel);
 }
 
+export function isDynamicRunnerGroup(step: RunnerStep): step is DynamicRunnerGroup {
+	return "expand" in step && "collect" in step && "parallel" in step && !Array.isArray((step as { parallel?: unknown }).parallel);
+}
+
 export function flattenSteps(steps: RunnerStep[]): RunnerSubagentStep[] {
 	const flat: RunnerSubagentStep[] = [];
 	for (const step of steps) {
 		if (isParallelGroup(step)) {
 			for (const task of step.parallel) flat.push(task);
+		} else if (isDynamicRunnerGroup(step)) {
+			continue;
 		} else {
 			flat.push(step);
 		}