pi-subagents 0.25.0 → 0.28.0

package/src/agents/agent-management.ts

@@ -17,7 +17,7 @@ import {
 	parsePackageName,
 } from "./agents.ts";
 import { serializeAgent } from "./agent-serializer.ts";
-import { serializeChain } from "./chain-serializer.ts";
+import { serializeChain, serializeJsonChain } from "./chain-serializer.ts";
 import { discoverAvailableSkills } from "./skills.ts";
 import type { Details } from "../shared/types.ts";
 
@@ -169,6 +169,22 @@ function parseStepList(raw: unknown): { steps?: ChainStepConfig[]; error?: strin
 		const s = item as Record<string, unknown>;
 		if (typeof s.agent !== "string" || !s.agent.trim()) return { error: `config.steps[${i}].agent must be a non-empty string.` };
 		const step: ChainStepConfig = { agent: s.agent.trim(), task: typeof s.task === "string" ? s.task : "" };
+		if (hasKey(s, "phase")) {
+			if (typeof s.phase === "string") step.phase = s.phase;
+			else return { error: `config.steps[${i}].phase must be a string.` };
+		}
+		if (hasKey(s, "label")) {
+			if (typeof s.label === "string") step.label = s.label;
+			else return { error: `config.steps[${i}].label must be a string.` };
+		}
+		if (hasKey(s, "as")) {
+			if (typeof s.as === "string") step.as = s.as;
+			else return { error: `config.steps[${i}].as must be a string.` };
+		}
+		if (hasKey(s, "outputSchema")) {
+			if (typeof s.outputSchema === "string") step.outputSchema = s.outputSchema;
+			else return { error: `config.steps[${i}].outputSchema must be a schema file path string for saved chains.` };
+		}
 		if (hasKey(s, "output")) {
 			if (s.output === false) step.output = false;
 			else if (typeof s.output === "string") step.output = s.output;
@@ -297,6 +313,18 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 			target.maxSubagentDepth = cfg.maxSubagentDepth;
 		} else return "config.maxSubagentDepth must be an integer >= 0 or false when provided.";
 	}
+	if (hasKey(cfg, "maxExecutionTimeMs")) {
+		if (cfg.maxExecutionTimeMs === false || cfg.maxExecutionTimeMs === "") target.maxExecutionTimeMs = undefined;
+		else if (typeof cfg.maxExecutionTimeMs === "number" && Number.isInteger(cfg.maxExecutionTimeMs) && cfg.maxExecutionTimeMs >= 1) {
+			target.maxExecutionTimeMs = cfg.maxExecutionTimeMs;
+		} else return "config.maxExecutionTimeMs must be an integer >= 1 or false when provided.";
+	}
+	if (hasKey(cfg, "maxTokens")) {
+		if (cfg.maxTokens === false || cfg.maxTokens === "") target.maxTokens = undefined;
+		else if (typeof cfg.maxTokens === "number" && Number.isInteger(cfg.maxTokens) && cfg.maxTokens >= 1) {
+			target.maxTokens = cfg.maxTokens;
+		} else return "config.maxTokens must be an integer >= 1 or false when provided.";
+	}
 	if (hasKey(cfg, "completionGuard")) {
 		if (typeof cfg.completionGuard !== "boolean") return "config.completionGuard must be a boolean when provided.";
 		target.completionGuard = cfg.completionGuard;
@@ -339,7 +367,7 @@ function renamePath(
 	cwd: string,
 ): { filePath?: string; error?: string } {
 	if (nameExistsInScope(cwd, scope, newName, currentPath)) return { error: `Name '${newName}' already exists in ${scope} scope.` };
-	const ext = kind === "agent" ? ".md" : ".chain.md";
+	const ext = kind === "agent" ? ".md" : currentPath.endsWith(".chain.json") ? ".chain.json" : ".chain.md";
 	const filePath = path.join(path.dirname(currentPath), `${newName}${ext}`);
 	if (fs.existsSync(filePath) && filePath !== currentPath) {
 		return { error: `File already exists at ${filePath} but is not a valid ${kind} definition. Remove or rename it first.` };
@@ -370,11 +398,48 @@ function formatAgentDetail(agent: AgentConfig): string {
 	if (agent.defaultReads?.length) lines.push(`Reads: ${agent.defaultReads.join(", ")}`);
 	if (agent.defaultProgress) lines.push("Progress: true");
 	if (agent.maxSubagentDepth !== undefined) lines.push(`Max subagent depth: ${agent.maxSubagentDepth}`);
+	if (agent.maxExecutionTimeMs !== undefined) lines.push(`Max execution time: ${agent.maxExecutionTimeMs}ms`);
+	if (agent.maxTokens !== undefined) lines.push(`Max tokens: ${agent.maxTokens}`);
 	if (agent.completionGuard === false) lines.push("Completion guard: false");
 	if (agent.systemPrompt.trim()) lines.push("", "System Prompt:", agent.systemPrompt);
 	return lines.join("\n");
 }
 
+function formatChainStepDetail(step: ChainStepConfig, index: number): string[] {
+	const lines: string[] = [];
+	if (step.expand || step.collect) {
+		const parallel = step.parallel && !Array.isArray(step.parallel) && typeof step.parallel === "object" ? step.parallel as { agent?: unknown; task?: unknown; label?: unknown; outputSchema?: unknown } : undefined;
+		const expand = step.expand && typeof step.expand === "object" ? step.expand as { from?: { output?: unknown; path?: unknown }; item?: unknown; key?: unknown; maxItems?: unknown; onEmpty?: unknown } : undefined;
+		const collect = step.collect && typeof step.collect === "object" ? step.collect as { as?: unknown; outputSchema?: unknown } : undefined;
+		lines.push(`${index + 1}. Dynamic fanout${typeof collect?.as === "string" ? ` -> ${collect.as}` : ""}`);
+		if (expand?.from) lines.push(`   Expand: ${String(expand.from.output ?? "?")}${String(expand.from.path ?? "")}`);
+		if (typeof expand?.item === "string") lines.push(`   Item variable: ${expand.item}`);
+		if (typeof expand?.key === "string") lines.push(`   Key: ${expand.key}`);
+		if (typeof expand?.maxItems === "number") lines.push(`   Max items: ${expand.maxItems}`);
+		if (typeof expand?.onEmpty === "string") lines.push(`   On empty: ${expand.onEmpty}`);
+		if (parallel?.agent) lines.push(`   Agent: ${String(parallel.agent)}`);
+		if (typeof parallel?.label === "string") lines.push(`   Label: ${parallel.label}`);
+		if (typeof parallel?.task === "string" && parallel.task.trim()) lines.push(`   Task: ${parallel.task}`);
+		if (parallel?.outputSchema) lines.push("   Structured output: true");
+		if (collect?.outputSchema) lines.push("   Collect schema: true");
+		if (step.concurrency !== undefined) lines.push(`   Concurrency: ${step.concurrency}`);
+		if (step.failFast !== undefined) lines.push(`   Fail fast: ${step.failFast ? "true" : "false"}`);
+		return lines;
+	}
+	lines.push(`${index + 1}. ${step.agent}`);
+	if (step.task?.trim()) lines.push(`   Task: ${step.task}`);
+	if (step.output === false) lines.push("   Output: false");
+	else if (step.output) lines.push(`   Output: ${step.output}`);
+	if (step.outputMode) lines.push(`   Output mode: ${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(", ")}`);
+	if (step.model) lines.push(`   Model: ${step.model}`);
+	if (step.skills === false) lines.push("   Skills: false");
+	else if (Array.isArray(step.skills) && step.skills.length > 0) lines.push(`   Skills: ${step.skills.join(", ")}`);
+	if (step.progress !== undefined) lines.push(`   Progress: ${step.progress ? "true" : "false"}`);
+	return lines;
+}
+
 function formatChainDetail(chain: ChainConfig): string {
 	const lines: string[] = [`Chain: ${chain.name} (${chain.source})`, `Path: ${chain.filePath}`, `Description: ${chain.description}`];
 	if (chain.packageName) {
@@ -383,18 +448,7 @@ function formatChainDetail(chain: ChainConfig): string {
 	}
 	lines.push("", "Steps:");
 	for (let i = 0; i < chain.steps.length; i++) {
-		const s = chain.steps[i]!;
-		lines.push(`${i + 1}. ${s.agent}`);
-		if (s.task.trim()) lines.push(`   Task: ${s.task}`);
-		if (s.output === false) lines.push("   Output: false");
-		else if (s.output) lines.push(`   Output: ${s.output}`);
-		if (s.outputMode) lines.push(`   Output mode: ${s.outputMode}`);
-		if (s.reads === false) lines.push("   Reads: false");
-		else if (Array.isArray(s.reads) && s.reads.length > 0) lines.push(`   Reads: ${s.reads.join(", ")}`);
-		if (s.model) lines.push(`   Model: ${s.model}`);
-		if (s.skills === false) lines.push("   Skills: false");
-		else if (Array.isArray(s.skills) && s.skills.length > 0) lines.push(`   Skills: ${s.skills.join(", ")}`);
-		if (s.progress !== undefined) lines.push(`   Progress: ${s.progress ? "true" : "false"}`);
+		lines.push(...formatChainStepDetail(chain.steps[i]!, i));
 	}
 	return lines.join("\n");
 }
@@ -405,6 +459,7 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 	const scopedAgents = allAgents(d).filter((a) => scope === "both" || a.source === "builtin" || a.source === scope).sort((a, b) => a.name.localeCompare(b.name));
 	const agents = scopedAgents.filter((a) => !a.disabled);
 	const chains = d.chains.filter((c) => scope === "both" || c.source === scope).sort((a, b) => a.name.localeCompare(b.name));
+	const diagnostics = d.chainDiagnostics.filter((entry) => scope === "both" || entry.source === scope);
 	const lines = [
 		"Executable agents:",
 		...(agents.length
@@ -413,6 +468,7 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 		"",
 		"Chains:",
 		...(chains.length ? chains.map((c) => `- ${c.name} (${c.source}): ${c.description}`) : ["- (none)"]),
+		...(diagnostics.length ? ["", "Chain diagnostics:", ...diagnostics.map((entry) => `- ${entry.filePath}: ${entry.error}`)] : []),
 	];
 	return result(lines.join("\n"));
 }
@@ -608,7 +664,7 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 		if (renamed.error) return result(renamed.error, true);
 		updated.filePath = renamed.filePath!;
 	}
-	fs.writeFileSync(updated.filePath, serializeChain(updated), "utf-8");
+	fs.writeFileSync(updated.filePath, updated.filePath.endsWith(".chain.json") ? serializeJsonChain(updated) : serializeChain(updated), "utf-8");
 	const headline = updated.name === oldName
 		? `Updated chain '${updated.name}' at ${updated.filePath}.`
 		: `Updated chain '${oldName}' to '${updated.name}' at ${updated.filePath}.`;

package/src/agents/agent-serializer.ts

@@ -21,6 +21,8 @@ export const KNOWN_FIELDS = new Set([
 	"defaultProgress",
 	"interactive",
 	"maxSubagentDepth",
+	"maxExecutionTimeMs",
+	"maxTokens",
 	"completionGuard",
 ]);
 
@@ -67,8 +69,17 @@ export function serializeAgent(config: AgentConfig): string {
 
 	if (config.defaultProgress) lines.push("defaultProgress: true");
 	if (config.interactive) lines.push("interactive: true");
-	if (Number.isInteger(config.maxSubagentDepth) && config.maxSubagentDepth >= 0) {
-		lines.push(`maxSubagentDepth: ${config.maxSubagentDepth}`);
+	const maxSubagentDepth = config.maxSubagentDepth;
+	if (typeof maxSubagentDepth === "number" && Number.isInteger(maxSubagentDepth) && maxSubagentDepth >= 0) {
+		lines.push(`maxSubagentDepth: ${maxSubagentDepth}`);
+	}
+	const maxExecutionTimeMs = config.maxExecutionTimeMs;
+	if (typeof maxExecutionTimeMs === "number" && Number.isInteger(maxExecutionTimeMs) && maxExecutionTimeMs >= 1) {
+		lines.push(`maxExecutionTimeMs: ${maxExecutionTimeMs}`);
+	}
+	const maxTokens = config.maxTokens;
+	if (typeof maxTokens === "number" && Number.isInteger(maxTokens) && maxTokens >= 1) {
+		lines.push(`maxTokens: ${maxTokens}`);
 	}
 	if (config.completionGuard === false) lines.push("completionGuard: false");
 

package/src/agents/agents.ts

@@ -6,10 +6,10 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import type { OutputMode } from "../shared/types.ts";
+import type { AcceptanceInput, OutputMode } from "../shared/types.ts";
 import { getAgentDir } from "../shared/utils.ts";
 import { KNOWN_FIELDS } from "./agent-serializer.ts";
-import { parseChain } from "./chain-serializer.ts";
+import { parseChain, parseJsonChain } from "./chain-serializer.ts";
 import { mergeAgentsForScope } from "./agent-selection.ts";
 import { parseFrontmatter } from "./frontmatter.ts";
 import { buildRuntimeName, parsePackageName } from "./identity.ts";
@@ -46,6 +46,8 @@ export interface BuiltinAgentOverrideBase {
 	skills?: string[];
 	tools?: string[];
 	mcpDirectTools?: string[];
+	maxExecutionTimeMs?: number;
+	maxTokens?: number;
 	completionGuard?: boolean;
 }
 
@@ -61,6 +63,8 @@ interface BuiltinAgentOverrideConfig {
 	systemPrompt?: string;
 	skills?: string[] | false;
 	tools?: string[] | false;
+	maxExecutionTimeMs?: number | false;
+	maxTokens?: number | false;
 	completionGuard?: boolean;
 }
 
@@ -94,6 +98,8 @@ export interface AgentConfig {
 	defaultProgress?: boolean;
 	interactive?: boolean;
 	maxSubagentDepth?: number;
+	maxExecutionTimeMs?: number;
+	maxTokens?: number;
 	completionGuard?: boolean;
 	disabled?: boolean;
 	extraFields?: Record<string, string>;
@@ -108,14 +114,25 @@ interface SubagentSettings {
 const EMPTY_SUBAGENT_SETTINGS: SubagentSettings = { overrides: {} };
 
 export interface ChainStepConfig {
-	agent: string;
-	task: string;
+	agent?: string;
+	task?: string;
+	phase?: string;
+	label?: string;
+	as?: string;
+	outputSchema?: string | Record<string, unknown>;
 	output?: string | false;
 	outputMode?: OutputMode;
 	reads?: string[] | false;
 	model?: string;
 	skills?: string[] | false;
 	progress?: boolean;
+	parallel?: unknown;
+	expand?: unknown;
+	collect?: unknown;
+	concurrency?: number;
+	failFast?: boolean;
+	worktree?: boolean;
+	acceptance?: AcceptanceInput;
 }
 
 export interface ChainConfig {
@@ -129,6 +146,12 @@ export interface ChainConfig {
 	extraFields?: Record<string, string>;
 }
 
+export interface ChainDiscoveryDiagnostic {
+	source: "user" | "project";
+	filePath: string;
+	error: string;
+}
+
 interface AgentDiscoveryResult {
 	agents: AgentConfig[];
 	projectAgentsDir: string | null;
@@ -186,6 +209,8 @@ function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
 		skills: agent.skills ? [...agent.skills] : undefined,
 		tools: agent.tools ? [...agent.tools] : undefined,
 		mcpDirectTools: agent.mcpDirectTools ? [...agent.mcpDirectTools] : undefined,
+		maxExecutionTimeMs: agent.maxExecutionTimeMs,
+		maxTokens: agent.maxTokens,
 		completionGuard: agent.completionGuard,
 	};
 }
@@ -205,6 +230,8 @@ function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentO
 		...(override.systemPrompt !== undefined ? { systemPrompt: override.systemPrompt } : {}),
 		...(override.skills !== undefined ? { skills: override.skills === false ? false : [...override.skills] } : {}),
 		...(override.tools !== undefined ? { tools: override.tools === false ? false : [...override.tools] } : {}),
+		...(override.maxExecutionTimeMs !== undefined ? { maxExecutionTimeMs: override.maxExecutionTimeMs } : {}),
+		...(override.maxTokens !== undefined ? { maxTokens: override.maxTokens } : {}),
 		...(override.completionGuard !== undefined ? { completionGuard: override.completionGuard } : {}),
 	};
 }
@@ -342,6 +369,22 @@ function parseBuiltinOverrideEntry(
 		}
 	}
 
+	if ("maxExecutionTimeMs" in input) {
+		if (input.maxExecutionTimeMs === false || (typeof input.maxExecutionTimeMs === "number" && Number.isInteger(input.maxExecutionTimeMs) && input.maxExecutionTimeMs >= 1)) {
+			override.maxExecutionTimeMs = input.maxExecutionTimeMs;
+		} else {
+			throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'maxExecutionTimeMs'; expected an integer >= 1 or false.`);
+		}
+	}
+
+	if ("maxTokens" in input) {
+		if (input.maxTokens === false || (typeof input.maxTokens === "number" && Number.isInteger(input.maxTokens) && input.maxTokens >= 1)) {
+			override.maxTokens = input.maxTokens;
+		} else {
+			throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'maxTokens'; expected an integer >= 1 or false.`);
+		}
+	}
+
 	if ("completionGuard" in input) {
 		if (typeof input.completionGuard === "boolean") {
 			override.completionGuard = input.completionGuard;
@@ -422,6 +465,8 @@ function applyBuiltinOverride(
 		next.tools = tools;
 		next.mcpDirectTools = mcpDirectTools;
 	}
+	if (override.maxExecutionTimeMs !== undefined) next.maxExecutionTimeMs = override.maxExecutionTimeMs === false ? undefined : override.maxExecutionTimeMs;
+	if (override.maxTokens !== undefined) next.maxTokens = override.maxTokens === false ? undefined : override.maxTokens;
 	if (override.completionGuard !== undefined) next.completionGuard = override.completionGuard;
 
 	return next;
@@ -462,7 +507,7 @@ function applyBuiltinOverrides(
 
 export function buildBuiltinOverrideConfig(
 	base: BuiltinAgentOverrideBase,
-	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "completionGuard">,
+	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "maxExecutionTimeMs" | "maxTokens" | "completionGuard">,
 ): BuiltinAgentOverrideConfig | undefined {
 	const override: BuiltinAgentOverrideConfig = {};
 
@@ -480,6 +525,8 @@ export function buildBuiltinOverrideConfig(
 	const baseTools = joinToolList(base);
 	const draftTools = joinToolList(draft);
 	if (!arraysEqual(draftTools, baseTools)) override.tools = draftTools ? [...draftTools] : false;
+	if (draft.maxExecutionTimeMs !== base.maxExecutionTimeMs) override.maxExecutionTimeMs = draft.maxExecutionTimeMs ?? false;
+	if (draft.maxTokens !== base.maxTokens) override.maxTokens = draft.maxTokens ?? false;
 	if ((draft.completionGuard !== false) !== (base.completionGuard !== false)) {
 		override.completionGuard = draft.completionGuard !== false;
 	}
@@ -535,7 +582,7 @@ export function removeBuiltinAgentOverride(cwd: string, name: string, scope: "us
 	return filePath;
 }
 
-function listMarkdownFilesRecursive(dir: string, predicate: (fileName: string) => boolean): string[] {
+function listFilesRecursive(dir: string, predicate: (fileName: string) => boolean): string[] {
 	const files: string[] = [];
 	if (!fs.existsSync(dir)) return files;
 
@@ -549,7 +596,7 @@ function listMarkdownFilesRecursive(dir: string, predicate: (fileName: string) =
 	for (const entry of entries) {
 		const filePath = path.join(dir, entry.name);
 		if (entry.isDirectory()) {
-			files.push(...listMarkdownFilesRecursive(filePath, predicate));
+			files.push(...listFilesRecursive(filePath, predicate));
 			continue;
 		}
 		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
@@ -562,7 +609,7 @@ function listMarkdownFilesRecursive(dir: string, predicate: (fileName: string) =
 function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 	const agents: AgentConfig[] = [];
 
-	for (const filePath of listMarkdownFilesRecursive(dir, (fileName) => fileName.endsWith(".md") && !fileName.endsWith(".chain.md"))) {
+	for (const filePath of listFilesRecursive(dir, (fileName) => fileName.endsWith(".md") && !fileName.endsWith(".chain.md"))) {
 		let content: string;
 		try {
 			content = fs.readFileSync(filePath, "utf-8");
@@ -648,6 +695,8 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 		}
 
 		const parsedMaxSubagentDepth = Number(frontmatter.maxSubagentDepth);
+		const parsedMaxExecutionTimeMs = Number(frontmatter.maxExecutionTimeMs);
+		const parsedMaxTokens = Number(frontmatter.maxTokens);
 		const completionGuard = frontmatter.completionGuard === "false"
 			? false
 			: frontmatter.completionGuard === "true"
@@ -681,6 +730,14 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 				Number.isInteger(parsedMaxSubagentDepth) && parsedMaxSubagentDepth >= 0
 					? parsedMaxSubagentDepth
 					: undefined,
+			maxExecutionTimeMs:
+				Number.isInteger(parsedMaxExecutionTimeMs) && parsedMaxExecutionTimeMs >= 1
+					? parsedMaxExecutionTimeMs
+					: undefined,
+			maxTokens:
+				Number.isInteger(parsedMaxTokens) && parsedMaxTokens >= 1
+					? parsedMaxTokens
+					: undefined,
 			completionGuard,
 			extraFields: Object.keys(extraFields).length > 0 ? extraFields : undefined,
 		});
@@ -689,10 +746,11 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 	return agents;
 }
 
-function loadChainsFromDir(dir: string, source: AgentSource): ChainConfig[] {
-	const chains: ChainConfig[] = [];
+function loadChainsFromDir(dir: string, source: "user" | "project"): { chains: ChainConfig[]; diagnostics: ChainDiscoveryDiagnostic[] } {
+	const chains = new Map<string, ChainConfig>();
+	const diagnostics: ChainDiscoveryDiagnostic[] = [];
 
-	for (const filePath of listMarkdownFilesRecursive(dir, (fileName) => fileName.endsWith(".chain.md"))) {
+	for (const filePath of listFilesRecursive(dir, (fileName) => fileName.endsWith(".chain.md") || fileName.endsWith(".chain.json"))) {
 		let content: string;
 		try {
 			content = fs.readFileSync(filePath, "utf-8");
@@ -701,13 +759,17 @@ function loadChainsFromDir(dir: string, source: AgentSource): ChainConfig[] {
 		}
 
 		try {
-			chains.push(parseChain(content, source, filePath));
-		} catch {
+			const chain = filePath.endsWith(".chain.json") ? parseJsonChain(content, source, filePath) : parseChain(content, source, filePath);
+			const existing = chains.get(chain.name);
+			if (existing && existing.filePath.endsWith(".chain.json") && filePath.endsWith(".chain.md")) continue;
+			chains.set(chain.name, chain);
+		} catch (error) {
+			diagnostics.push({ source, filePath, error: error instanceof Error ? error.message : String(error) });
 			continue;
 		}
 	}
 
-	return chains;
+	return { chains: Array.from(chains.values()), diagnostics };
 }
 
 function isDirectory(p: string): boolean {
@@ -779,6 +841,7 @@ export function discoverAgentsAll(cwd: string): {
 	user: AgentConfig[];
 	project: AgentConfig[];
 	chains: ChainConfig[];
+	chainDiagnostics: ChainDiscoveryDiagnostic[];
 	userDir: string;
 	projectDir: string | null;
 	userChainDir: string;
@@ -816,17 +879,25 @@ export function discoverAgentsAll(cwd: string): {
 	const project = Array.from(projectMap.values());
 
 	const chainMap = new Map<string, ChainConfig>();
+	const projectChainDiagnostics: ChainDiscoveryDiagnostic[] = [];
 	for (const dir of projectChainDirs) {
-		for (const chain of loadChainsFromDir(dir, "project")) {
+		const loaded = loadChainsFromDir(dir, "project");
+		projectChainDiagnostics.push(...loaded.diagnostics);
+		for (const chain of loaded.chains) {
 			chainMap.set(chain.name, chain);
 		}
 	}
+	const userChains = loadChainsFromDir(userChainDir, "user");
 	const chains = [
-		...loadChainsFromDir(userChainDir, "user"),
+		...userChains.chains,
 		...Array.from(chainMap.values()),
 	];
+	const chainDiagnostics = [
+		...userChains.diagnostics,
+		...projectChainDiagnostics,
+	];
 
 	const userDir = process.env.PI_CODING_AGENT_DIR ? userDirOld : fs.existsSync(userDirNew) ? userDirNew : userDirOld;
 
-	return { builtin, user, project, chains, userDir, projectDir, userChainDir, projectChainDir, userSettingsPath, projectSettingsPath };
+	return { builtin, user, project, chains, chainDiagnostics, userDir, projectDir, userChainDir, projectChainDir, userSettingsPath, projectSettingsPath };
 }

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

@@ -156,6 +156,8 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
 		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.",
+			"For implementation handoffs from a plan, PRD, spec, issue, or broad fix, put implementation instructions and plan paths in task, and put the definition of done, evidence, verification commands, constraints, and loop cap in acceptance.",
 			"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"),

package/src/extension/index.ts

@@ -394,7 +394,10 @@ EXECUTION (use exactly ONE mode):
 • SINGLE: { agent, task? } - one task; omit task for self-contained agents
 • 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)
+• Foreground timeout: { timeoutMs } or { maxRuntimeMs } - wall-clock limit for foreground single, parallel, and chain runs. Timed-out children return timedOut:true with completed sibling/prior results preserved. Not for async/background runs.
 • 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.
+• Plan/spec implementation handoffs: when delegating a plan, PRD, spec, issue, or broad fix to an editing-capable child, prefer structured acceptance instead of burying validation requirements in task prose. Put the implementation instructions and plan paths in task; put the definition of done, evidence, verification commands, constraints, and loop cap in acceptance.
 
 CHAIN TEMPLATE VARIABLES (use in task strings):
 • {task} - The original task/request from the user
@@ -406,8 +409,8 @@ Example: { chain: [{agent:"agent-a", task:"Analyze {task}"}, {agent:"agent-b", t
 MANAGEMENT (use action field, omit agent/task/chain/tasks):
 • { action: "list" } - discover executable agents/chains
 • { action: "get", agent: "name" } - full detail; packaged agents use dotted runtime names like "package.agent"
-• { action: "create", config: { name: "custom-agent", package: "code-analysis", systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext, ... } }
-• { action: "update", agent: "code-analysis.custom-agent", config: { package: "analysis", ... } } - merge
+• { action: "create", config: { name: "custom-agent", package: "code-analysis", systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext, maxExecutionTimeMs, maxTokens, ... } }
+• { action: "update", agent: "code-analysis.custom-agent", config: { package: "analysis", maxExecutionTimeMs, maxTokens, ... } } - merge
 • { action: "delete", agent: "code-analysis.custom-agent" }
 • Use chainName for chain operations; packaged chains also use dotted runtime names