pi-subagents 0.30.0 → 0.31.0

package/src/runs/shared/acceptance.ts

@@ -39,6 +39,10 @@ const VALID_EVIDENCE = new Set<AcceptanceEvidenceKind>([
 	"review-findings",
 	"manual-notes",
 ]);
+const ACCEPTANCE_CONFIG_KEYS = new Set(["level", "criteria", "evidence", "verify", "review", "stopRules", "reason"]);
+const ACCEPTANCE_GATE_KEYS = new Set(["id", "must", "evidence", "severity"]);
+const ACCEPTANCE_VERIFY_KEYS = new Set(["id", "command", "timeoutMs", "cwd", "env", "allowFailure"]);
+const ACCEPTANCE_REVIEW_KEYS = new Set(["agent", "focus", "required"]);
 
 function normalizeLevel(level: AcceptanceLevel | undefined): Exclude<AcceptanceLevel, "auto"> | "auto" {
 	return level ?? "auto";
@@ -144,13 +148,44 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
 		return errors;
 	}
 	const value = input as Record<string, unknown>;
+	for (const key of Object.keys(value)) {
+		if (!ACCEPTANCE_CONFIG_KEYS.has(key)) errors.push(`${pathLabel}.${key} is not supported.`);
+	}
 	if (value.level !== undefined && (typeof value.level !== "string" || !VALID_LEVELS.has(value.level as AcceptanceLevel))) {
 		errors.push(`${pathLabel}.level must be one of auto, none, attested, checked, verified, reviewed.`);
 	}
 	if (value.level === "none" && (typeof value.reason !== "string" || !value.reason.trim())) {
 		errors.push(`${pathLabel}.reason is required when level is none.`);
 	}
+	if (value.reason !== undefined && typeof value.reason !== "string") errors.push(`${pathLabel}.reason must be a string.`);
 	if (value.criteria !== undefined && !Array.isArray(value.criteria)) errors.push(`${pathLabel}.criteria must be an array.`);
+	if (Array.isArray(value.criteria)) {
+		for (const [index, criterion] of value.criteria.entries()) {
+			if (typeof criterion === "string") continue;
+			const criterionPath = `${pathLabel}.criteria[${index}]`;
+			if (!criterion || typeof criterion !== "object" || Array.isArray(criterion)) {
+				errors.push(`${criterionPath} must be a string or an object.`);
+				continue;
+			}
+			const gate = criterion as Record<string, unknown>;
+			for (const key of Object.keys(gate)) {
+				if (!ACCEPTANCE_GATE_KEYS.has(key)) errors.push(`${criterionPath}.${key} is not supported.`);
+			}
+			if (typeof gate.id !== "string" || !gate.id.trim()) errors.push(`${criterionPath}.id is required.`);
+			if (typeof gate.must !== "string" || !gate.must.trim()) errors.push(`${criterionPath}.must is required.`);
+			if (gate.evidence !== undefined && !Array.isArray(gate.evidence)) errors.push(`${criterionPath}.evidence must be an array.`);
+			if (Array.isArray(gate.evidence)) {
+				for (const [evidenceIndex, item] of gate.evidence.entries()) {
+					if (typeof item !== "string" || !VALID_EVIDENCE.has(item as AcceptanceEvidenceKind)) {
+						errors.push(`${criterionPath}.evidence[${evidenceIndex}] is not a supported evidence kind.`);
+					}
+				}
+			}
+			if (gate.severity !== undefined && gate.severity !== "required" && gate.severity !== "recommended") {
+				errors.push(`${criterionPath}.severity must be required or recommended.`);
+			}
+		}
+	}
 	if (Array.isArray(value.evidence)) {
 		for (const [index, item] of value.evidence.entries()) {
 			if (typeof item !== "string" || !VALID_EVIDENCE.has(item as AcceptanceEvidenceKind)) {
@@ -168,11 +203,46 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
 				continue;
 			}
 			const cmd = command as Record<string, unknown>;
+			for (const key of Object.keys(cmd)) {
+				if (!ACCEPTANCE_VERIFY_KEYS.has(key)) errors.push(`${pathLabel}.verify[${index}].${key} is not supported.`);
+			}
 			if (typeof cmd.id !== "string" || !cmd.id.trim()) errors.push(`${pathLabel}.verify[${index}].id is required.`);
 			if (typeof cmd.command !== "string" || !cmd.command.trim()) errors.push(`${pathLabel}.verify[${index}].command is required.`);
-			if (cmd.timeoutMs !== undefined && (typeof cmd.timeoutMs !== "number" || cmd.timeoutMs <= 0)) {
-				errors.push(`${pathLabel}.verify[${index}].timeoutMs must be a positive number.`);
+			if (cmd.timeoutMs !== undefined && (typeof cmd.timeoutMs !== "number" || !Number.isInteger(cmd.timeoutMs) || cmd.timeoutMs < 1)) {
+				errors.push(`${pathLabel}.verify[${index}].timeoutMs must be an integer >= 1.`);
 			}
+			if (cmd.cwd !== undefined && typeof cmd.cwd !== "string") errors.push(`${pathLabel}.verify[${index}].cwd must be a string.`);
+			if (cmd.env !== undefined) {
+				if (!cmd.env || typeof cmd.env !== "object" || Array.isArray(cmd.env)) {
+					errors.push(`${pathLabel}.verify[${index}].env must be an object.`);
+				} else {
+					for (const [envKey, envValue] of Object.entries(cmd.env as Record<string, unknown>)) {
+						if (typeof envValue !== "string") errors.push(`${pathLabel}.verify[${index}].env.${envKey} must be a string.`);
+					}
+				}
+			}
+			if (cmd.allowFailure !== undefined && typeof cmd.allowFailure !== "boolean") {
+				errors.push(`${pathLabel}.verify[${index}].allowFailure must be a boolean.`);
+			}
+		}
+	}
+	if (value.review !== undefined && value.review !== false) {
+		if (!value.review || typeof value.review !== "object" || Array.isArray(value.review)) {
+			errors.push(`${pathLabel}.review must be false or an object.`);
+		} else {
+			const review = value.review as Record<string, unknown>;
+			for (const key of Object.keys(review)) {
+				if (!ACCEPTANCE_REVIEW_KEYS.has(key)) errors.push(`${pathLabel}.review.${key} is not supported.`);
+			}
+			if (review.agent !== undefined && typeof review.agent !== "string") errors.push(`${pathLabel}.review.agent must be a string.`);
+			if (review.focus !== undefined && typeof review.focus !== "string") errors.push(`${pathLabel}.review.focus must be a string.`);
+			if (review.required !== undefined && typeof review.required !== "boolean") errors.push(`${pathLabel}.review.required must be a boolean.`);
+		}
+	}
+	if (value.stopRules !== undefined && !Array.isArray(value.stopRules)) errors.push(`${pathLabel}.stopRules must be an array.`);
+	if (Array.isArray(value.stopRules)) {
+		for (const [index, item] of value.stopRules.entries()) {
+			if (typeof item !== "string") errors.push(`${pathLabel}.stopRules[${index}] must be a string.`);
 		}
 	}
 	return errors;
@@ -258,16 +328,19 @@ export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig): st
 	lines.push(
 		"",
 		"Finish with a fenced JSON block tagged `acceptance-report` in this shape:",
+		"Use empty arrays when no items apply; array fields contain strings unless object entries are shown.",
 		"```acceptance-report",
 		JSON.stringify({
 			criteriaSatisfied: [{ id: "criterion-1", status: "satisfied", evidence: "specific proof" }],
-			changedFiles: [],
-			testsAddedOrUpdated: [],
+			changedFiles: ["src/file.ts"],
+			testsAddedOrUpdated: ["test/file.test.ts"],
 			commandsRun: [{ command: "command", result: "passed", summary: "short result" }],
-			validationOutput: [],
-			residualRisks: [],
+			validationOutput: ["validation output or concise summary"],
+			residualRisks: ["none"],
 			noStagedFiles: true,
-			notes: "anything else the parent should know",
+			diffSummary: "short description of the diff",
+			reviewFindings: ["blocker: file.ts:12 - issue found, or no blockers"],
+			manualNotes: "anything else the parent should know",
 		}, null, 2),
 		"```",
 	);
@@ -299,43 +372,142 @@ function extractBalancedJson(text: string, start: number): string | undefined {
 	return undefined;
 }
 
-export function parseAcceptanceReport(output: string): { report?: AcceptanceReport; error?: string } {
-	const fenced = [...output.matchAll(/```acceptance-report\s*\n([\s\S]*?)```/gi)]
+function unwrapAcceptanceReport(value: unknown): unknown {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+	const record = value as { acceptance?: unknown; "acceptance-report"?: unknown };
+	if ("acceptance" in record) return record.acceptance;
+	if ("acceptance-report" in record) return record["acceptance-report"];
+	return value;
+}
+
+function isCommandsRunArray(value: unknown): value is NonNullable<AcceptanceReport["commandsRun"]> {
+	return Array.isArray(value) && value.every((item) => {
+		if (!item || typeof item !== "object" || Array.isArray(item)) return false;
+		const command = item 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 hasGenericAcceptanceReportSignal(value: unknown): boolean {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const record = value as Record<string, unknown>;
+	return "criteriaSatisfied" in record && (
+		isStringArray(record.changedFiles)
+		|| isStringArray(record.testsAddedOrUpdated)
+		|| isCommandsRunArray(record.commandsRun)
+		|| isStringArray(record.validationOutput)
+		|| isStringArray(record.residualRisks)
+		|| typeof record.noStagedFiles === "boolean"
+		|| typeof record.diffSummary === "string"
+		|| isStringArray(record.reviewFindings)
+		|| typeof record.manualNotes === "string"
+	);
+}
+
+function parseReportJson(body: string): unknown {
+	const trimmed = body.trim();
+	try {
+		return JSON.parse(trimmed) as unknown;
+	} catch (error) {
+		const jsonStart = trimmed.indexOf("{");
+		if (jsonStart > 0) {
+			const json = extractBalancedJson(trimmed, jsonStart);
+			if (json) return JSON.parse(json) as unknown;
+		}
+		throw error;
+	}
+}
+
+function fencedBlocks(output: string, tag: string): string[] {
+	return [...output.matchAll(new RegExp(`\`\`\`${tag}\\s*\\n([\\s\\S]*?)\`\`\``, "gi"))]
 		.map((match) => match[1]?.trim())
 		.filter((value): value is string => Boolean(value));
+}
+
+function validationPathLabelForWrapper(value: unknown): string {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return "";
+	const record = value as Record<string, unknown>;
+	if ("acceptance" in record) return "acceptance";
+	if ("acceptance-report" in record) return "acceptance-report";
+	return "";
+}
+
+function parseAcceptanceReportBody(body: string): { report?: AcceptanceReport; errors: string[] } {
+	const parsed = parseReportJson(body);
+	const report = unwrapAcceptanceReport(parsed);
+	return validateAcceptanceReport(report, validationPathLabelForWrapper(parsed));
+}
+
+function parseGenericJsonAcceptanceReportBody(body: string): AcceptanceReport | undefined {
+	const parsed = parseReportJson(body);
+	const report = unwrapAcceptanceReport(parsed);
+	const validation = validateAcceptanceReport(report);
+	if (!validation.report) return undefined;
+	return hasGenericAcceptanceReportSignal(validation.report) ? validation.report : undefined;
+}
+
+export function parseAcceptanceReport(output: string): { report?: AcceptanceReport; error?: string } {
+	const fenced = fencedBlocks(output, "acceptance-report");
 	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");
+			const validation = parseAcceptanceReportBody(body);
+			if (validation.report) return { report: validation.report };
+			parseErrors.push(`Invalid acceptance-report: ${validation.errors.join("; ")}`);
 		} catch (error) {
 			parseErrors.push(error instanceof Error ? error.message : String(error));
 		}
 	}
 	if (parseErrors.length > 0) return { error: `Failed to parse acceptance-report: ${parseErrors.join("; ")}` };
+	for (const body of fencedBlocks(output, "(?:json|jsonc|json5)")) {
+		try {
+			const report = parseGenericJsonAcceptanceReportBody(body);
+			if (report) return { report };
+		} catch {
+			// Ignore unrelated or malformed generic JSON fences; only explicit
+			// acceptance-report fences should turn parse failures into blockers.
+		}
+	}
 	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) };
+			if (jsonStart !== -1) {
+				const json = extractBalancedJson(output, jsonStart);
+				if (json) {
+					try {
+						const parsed = JSON.parse(json) as unknown;
+						const report = unwrapAcceptanceReport(parsed);
+						const validation = validateAcceptanceReport(report, validationPathLabelForWrapper(parsed));
+						if (validation.report) return { report: validation.report };
+						return { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}` };
+					} catch (error) {
+						return { error: error instanceof Error ? error.message : String(error) };
+					}
 				}
 			}
 		}
-	}
 	return { error: "Structured acceptance report not found." };
 }
 
 export function stripAcceptanceReport(output: string): string {
+	const trailingFencePattern = /\n?```(acceptance-report|json|jsonc|json5)\s*\n([\s\S]*?)```\s*/gi;
+	let trailingFence: { index: number; tag: string; body: string } | undefined;
+	for (const match of output.matchAll(trailingFencePattern)) {
+		const end = (match.index ?? 0) + match[0].length;
+		if (output.slice(end).trim().length === 0 && match[1] && match[2]) {
+			trailingFence = { index: match.index ?? 0, tag: match[1].toLowerCase(), body: match[2] };
+		}
+	}
+	if (trailingFence) {
+		if (trailingFence.tag === "acceptance-report") return output.slice(0, trailingFence.index).trimEnd();
+		try {
+			if (parseGenericJsonAcceptanceReportBody(trailingFence.body)) return output.slice(0, trailingFence.index).trimEnd();
+		} catch {
+			// Leave unrelated or malformed generic JSON fences visible.
+		}
+	}
 	return output
 		.replace(/\n?```acceptance-report\s*\n[\s\S]*?```\s*$/i, "")
 		.replace(/\n?ACCEPTANCE_REPORT\s*:\s*\{[\s\S]*\}\s*$/i, "")
@@ -346,26 +518,105 @@ function isStringArray(value: unknown): value is string[] {
 	return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
 
-function isAcceptanceReport(value: unknown): value is AcceptanceReport {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+function pathFor(base: string, segment: string): string {
+	return base ? `${base}.${segment}` : segment;
+}
+
+function describeValidationValue(value: unknown): string {
+	if (value === undefined) return "missing";
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	if (typeof value === "object") return "object";
+	if (typeof value === "string") {
+		const short = value.length > 80 ? `${value.slice(0, 77)}...` : value;
+		return JSON.stringify(short);
+	}
+	return `${typeof value} ${String(value)}`;
+}
+
+function pushTypeError(errors: string[], pathLabel: string, expected: string, value: unknown): void {
+	errors.push(`${pathLabel}: expected ${expected}; got ${describeValidationValue(value)}`);
+}
+
+function validateStringArrayField(errors: string[], value: unknown, pathLabel: string): void {
+	if (!Array.isArray(value)) {
+		pushTypeError(errors, pathLabel, "string[]", value);
+		return;
+	}
+	for (const [index, item] of value.entries()) {
+		if (typeof item !== "string") pushTypeError(errors, `${pathLabel}[${index}]`, "string", item);
+	}
+}
+
+function validateAcceptanceReport(value: unknown, pathLabel = ""): { report?: AcceptanceReport; errors: string[] } {
+	const errors: string[] = [];
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		pushTypeError(errors, pathLabel || "acceptance-report", "object", value);
+		return { errors };
+	}
 	const report = value as AcceptanceReport;
 	if (report.criteriaSatisfied !== undefined) {
-		if (!Array.isArray(report.criteriaSatisfied)) return false;
-		for (const item of report.criteriaSatisfied) {
-			if (!item || typeof item !== "object" || Array.isArray(item)) return false;
-			const criterion = item 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;
-			if (typeof criterion.evidence !== "string" || !criterion.evidence.trim()) return false;
+		if (!Array.isArray(report.criteriaSatisfied)) {
+			pushTypeError(errors, pathFor(pathLabel, "criteriaSatisfied"), "array", report.criteriaSatisfied);
+		} else {
+			for (const [index, item] of report.criteriaSatisfied.entries()) {
+				const itemPath = `${pathFor(pathLabel, "criteriaSatisfied")}[${index}]`;
+				if (!item || typeof item !== "object" || Array.isArray(item)) {
+					pushTypeError(errors, itemPath, "object", item);
+					continue;
+				}
+				const criterion = item as { id?: unknown; status?: unknown; evidence?: unknown };
+				if (criterion.id !== undefined && typeof criterion.id !== "string") pushTypeError(errors, `${itemPath}.id`, "string", criterion.id);
+				if (criterion.status !== "satisfied" && criterion.status !== "not-satisfied" && criterion.status !== "not-applicable") {
+					pushTypeError(errors, `${itemPath}.status`, "one of \"satisfied\", \"not-satisfied\", \"not-applicable\"", criterion.status);
+				}
+				if (typeof criterion.evidence !== "string" || !criterion.evidence.trim()) pushTypeError(errors, `${itemPath}.evidence`, "non-empty string", criterion.evidence);
+			}
+		}
+	}
+	if (report.changedFiles !== undefined) validateStringArrayField(errors, report.changedFiles, pathFor(pathLabel, "changedFiles"));
+	if (report.testsAddedOrUpdated !== undefined) validateStringArrayField(errors, report.testsAddedOrUpdated, pathFor(pathLabel, "testsAddedOrUpdated"));
+	if (report.commandsRun !== undefined) {
+		if (!Array.isArray(report.commandsRun)) {
+			pushTypeError(errors, pathFor(pathLabel, "commandsRun"), "array", report.commandsRun);
+		} else {
+			for (const [index, item] of report.commandsRun.entries()) {
+				const itemPath = `${pathFor(pathLabel, "commandsRun")}[${index}]`;
+				if (!item || typeof item !== "object" || Array.isArray(item)) {
+					pushTypeError(errors, itemPath, "object", item);
+					continue;
+				}
+				const command = item as { command?: unknown; result?: unknown; summary?: unknown };
+				if (typeof command.command !== "string" || !command.command.trim()) pushTypeError(errors, `${itemPath}.command`, "non-empty string", command.command);
+				if (command.result !== "passed" && command.result !== "failed" && command.result !== "not-run") {
+					pushTypeError(errors, `${itemPath}.result`, "one of \"passed\", \"failed\", \"not-run\"", command.result);
+				}
+				if (typeof command.summary !== "string") pushTypeError(errors, `${itemPath}.summary`, "string", command.summary);
+			}
 		}
 	}
-	return report.criteriaSatisfied !== undefined
+	if (report.validationOutput !== undefined) validateStringArrayField(errors, report.validationOutput, pathFor(pathLabel, "validationOutput"));
+	if (report.residualRisks !== undefined) validateStringArrayField(errors, report.residualRisks, pathFor(pathLabel, "residualRisks"));
+	if (report.noStagedFiles !== undefined && typeof report.noStagedFiles !== "boolean") pushTypeError(errors, pathFor(pathLabel, "noStagedFiles"), "boolean", report.noStagedFiles);
+	if (report.diffSummary !== undefined && typeof report.diffSummary !== "string") pushTypeError(errors, pathFor(pathLabel, "diffSummary"), "string", report.diffSummary);
+	if (report.reviewFindings !== undefined) validateStringArrayField(errors, report.reviewFindings, pathFor(pathLabel, "reviewFindings"));
+	if (report.manualNotes !== undefined && typeof report.manualNotes !== "string") pushTypeError(errors, pathFor(pathLabel, "manualNotes"), "string", report.manualNotes);
+	if (report.notes !== undefined && typeof report.notes !== "string") pushTypeError(errors, pathFor(pathLabel, "notes"), "string", report.notes);
+	if (errors.length > 0) return { errors };
+	const hasReportField = report.criteriaSatisfied !== undefined
 		|| report.changedFiles !== undefined
 		|| report.testsAddedOrUpdated !== undefined
 		|| report.commandsRun !== undefined
+		|| report.validationOutput !== undefined
 		|| report.residualRisks !== undefined
+		|| report.noStagedFiles !== undefined
+		|| report.diffSummary !== undefined
 		|| report.manualNotes !== undefined
+		|| report.notes !== undefined
 		|| report.reviewFindings !== undefined;
+	return hasReportField
+		? { report, errors }
+		: { errors: [`${pathLabel || "acceptance-report"}: expected at least one acceptance report field`] };
 }
 
 function checkCriteriaSatisfied(criteria: ResolvedAcceptanceGate[], report: AcceptanceReport): AcceptanceRuntimeCheck[] {

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

@@ -84,7 +84,7 @@ function stripFrameworkInstructions(task: string): string {
 	return task
 		.split("\n")
 		.filter((line) => !/^\s*\[(?:Write to|Read from):/i.test(line))
-		.filter((line) => !/^\s*(?:Create and maintain progress at:|Update progress at:|Write your findings to:)/i.test(line))
+		.filter((line) => !/^\s*(?:Create and maintain progress at:|Update progress at:|\*\*Output:\*\*|Write your findings to(?: exactly this path)?:|This path is authoritative for this run\.|Ignore any other output filename or output path mentioned elsewhere)/i.test(line))
 		.join("\n");
 }
 

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

@@ -26,6 +26,7 @@ export interface DynamicCollectedResult {
 	text: string;
 	structured?: unknown;
 	error?: string;
+	timedOut?: boolean;
 	outputPath?: string;
 	artifactPaths?: ArtifactPaths;
 }
@@ -49,7 +50,7 @@ const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
 	...DYNAMIC_PARALLEL_KEYS,
 	"outputName", "structured", "inheritProjectContext", "inheritSkills", "skills", "outputPath", "maxSubagentDepth",
 	"structuredOutput", "structuredOutputSchema", "tools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "completionGuard", "systemPrompt",
-	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance",
+	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance", "parentSessionId",
 ]);
 const DYNAMIC_COLLECT_KEYS = new Set(["as", "outputSchema"]);
 
@@ -262,7 +263,7 @@ export function materializeDynamicParallelStep(step: DynamicParallelStep, output
 export function collectDynamicResults(
 	step: DynamicParallelStep,
 	items: DynamicMaterializedItem[],
-	results: Array<Pick<SingleResult, "agent" | "exitCode" | "error" | "structuredOutput" | "artifactPaths" | "savedOutputPath"> & { output?: string; finalOutput?: string }>,
+	results: Array<Pick<SingleResult, "agent" | "exitCode" | "error" | "timedOut" | "structuredOutput" | "artifactPaths" | "savedOutputPath"> & { output?: string; finalOutput?: string }>,
 ): DynamicCollectedResult[] {
 	return items.map((entry, index) => {
 		const result = results[index];
@@ -278,6 +279,7 @@ export function collectDynamicResults(
 			text,
 			...(result?.structuredOutput !== undefined ? { structured: result.structuredOutput } : {}),
 			...(result?.error ? { error: result.error } : {}),
+			...(result?.timedOut ? { timedOut: true } : {}),
 			...(result?.savedOutputPath ? { outputPath: result.savedOutputPath } : {}),
 			...(result?.artifactPaths ? { artifactPaths: result.artifactPaths } : {}),
 		};

package/src/runs/shared/mcp-direct-tool-allowlist.ts

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { getAgentDir } from "../../shared/utils.ts";
+import { getAgentDir, getProjectConfigDir } from "../../shared/utils.ts";
 
 const CACHE_VERSION = 1;
 const CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
@@ -112,7 +112,7 @@ function loadMcpConfig(cwd: string): McpConfig {
 function getConfigPaths(cwd: string): string[] {
 	const piGlobalPath = path.join(getAgentDir(), "mcp.json");
 	const projectPath = path.resolve(cwd, ".mcp.json");
-	const projectPiPath = path.resolve(cwd, ".pi", "mcp.json");
+	const projectPiPath = path.resolve(getProjectConfigDir(cwd), "mcp.json");
 	const sources: string[] = [];
 	if (GENERIC_GLOBAL_CONFIG_PATH !== piGlobalPath) sources.push(GENERIC_GLOBAL_CONFIG_PATH);
 	sources.push(piGlobalPath);

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

@@ -1,4 +1,6 @@
 export interface RunnerSubagentStep {
+	/** Session id of the direct parent session for permission-system ask forwarding. */
+	parentSessionId?: string;
 	agent: string;
 	task: string;
 	importAsyncRoot?: {
@@ -108,6 +110,7 @@ export interface ParallelTaskResult {
 	output: string;
 	exitCode: number | null;
 	error?: string;
+	timedOut?: boolean;
 	model?: string;
 	attemptedModels?: string[];
 	outputTargetPath?: string;
@@ -124,7 +127,9 @@ export function aggregateParallelOutputs(
 			const header = headerFormat(r.taskIndex ?? i, r.agent);
 			const hasOutput = Boolean(r.output?.trim());
 			const status =
-				r.exitCode === -1
+				r.timedOut
+					? `TIMED OUT${r.error ? `: ${r.error}` : ""}`
+					: r.exitCode === -1
 					? "SKIPPED"
 					: r.exitCode !== 0 && r.exitCode !== null
 						? `FAILED (exit code ${r.exitCode})${r.error ? `: ${r.error}` : ""}`

package/src/runs/shared/pi-args.ts

@@ -25,8 +25,10 @@ export const SUBAGENT_PARENT_CHILD_INDEX_ENV = "PI_SUBAGENT_PARENT_CHILD_INDEX";
 export const SUBAGENT_PARENT_DEPTH_ENV = "PI_SUBAGENT_PARENT_DEPTH";
 export const SUBAGENT_PARENT_PATH_ENV = "PI_SUBAGENT_PARENT_PATH";
 export const SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV = "PI_SUBAGENT_PARENT_CAPABILITY_TOKEN";
+export const SUBAGENT_PARENT_SESSION_ENV = "PI_SUBAGENT_PARENT_SESSION";
 
 interface BuildPiArgsInput {
+	parentSessionId?: string;
 	baseArgs: string[];
 	task: string;
 	sessionEnabled: boolean;
@@ -37,6 +39,7 @@ interface BuildPiArgsInput {
 	systemPromptMode?: "append" | "replace";
 	inheritProjectContext: boolean;
 	inheritSkills: boolean;
+	requireReadTool?: boolean;
 	tools?: string[];
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
@@ -98,7 +101,10 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 		args.push("--model", modelArg);
 	}
 
-	const declaredBuiltinTools = input.tools?.filter((tool) => !(tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) ?? [];
+	const declaredBuiltinToolsBase = input.tools?.filter((tool) => !(tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) ?? [];
+	const declaredBuiltinTools = input.requireReadTool && input.tools?.length && !declaredBuiltinToolsBase.includes("read")
+		? ["read", ...declaredBuiltinToolsBase]
+		: declaredBuiltinToolsBase;
 	const fanoutAuthorized = declaredBuiltinTools.includes("subagent");
 	const toolExtensionPaths: string[] = [];
 	if (input.tools?.length) {
@@ -217,6 +223,8 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 		env[STRUCTURED_OUTPUT_SCHEMA_ENV] = input.structuredOutput.schemaPath;
 	}
 
+	env[SUBAGENT_PARENT_SESSION_ENV] = input.parentSessionId ?? process.env[SUBAGENT_PARENT_SESSION_ENV] ?? "";
+
 	return { args, env, tempDir };
 }
 

package/src/runs/shared/single-output.ts

@@ -31,9 +31,23 @@ export function resolveSingleOutputPath(
 	return path.resolve(baseCwd, output);
 }
 
+function formatOutputPathInstruction(outputPath: string): string {
+	return [
+		`Write your findings to exactly this path: ${outputPath}`,
+		"This path is authoritative for this run.",
+		"Ignore any other output filename or output path mentioned elsewhere, including output destinations in the base agent prompt, system prompt, or task instructions.",
+	].join("\n");
+}
+
 export function injectSingleOutputInstruction(task: string, outputPath: string | undefined): string {
 	if (!outputPath) return task;
-	return `${task}\n\n---\n**Output:** Write your findings to: ${outputPath}`;
+	return `${task}\n\n---\n**Output:**\n${formatOutputPathInstruction(outputPath)}`;
+}
+
+export function injectOutputPathSystemPrompt(systemPrompt: string, outputPath: string | undefined): string {
+	if (!outputPath) return systemPrompt;
+	const instruction = `Runtime output path override:\n${formatOutputPathInstruction(outputPath)}`;
+	return systemPrompt ? `${systemPrompt}\n\n${instruction}` : instruction;
 }
 
 function countLines(text: string): number {

package/src/shared/settings.ts

@@ -305,6 +305,7 @@ function resolveChainPath(filePath: string, chainDir: string): string {
  * These are appended to the task to tell the agent what to read/write.
  */
 export function writeInitialProgressFile(progressDir: string): void {
+	fs.mkdirSync(progressDir, { recursive: true });
 	fs.writeFileSync(path.join(progressDir, "progress.md"), INITIAL_PROGRESS_CONTENT);
 }
 

package/src/shared/types.ts

@@ -391,6 +391,7 @@ export interface SingleResult {
 	detached?: boolean;
 	detachedReason?: string;
 	interrupted?: boolean;
+	timedOut?: boolean;
 	messages?: Message[];
 	usage: Usage;
 	model?: string;
@@ -681,6 +682,7 @@ export interface ForegroundResumeRun {
 export interface SubagentState {
 	baseCwd: string;
 	currentSessionId: string | null;
+	subagentInProgress?: boolean;
 	asyncJobs: Map<string, AsyncJobState>;
 	foregroundRuns?: Map<string, ForegroundResumeRun>;
 	foregroundControls: Map<string, {
@@ -754,9 +756,13 @@ export const SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT = "subagent:result-intercom
 // ============================================================================
 
 export interface RunSyncOptions {
+	/** Session id of the direct parent session for permission-system ask forwarding. */
+	parentSessionId?: string;
 	cwd?: string;
 	signal?: AbortSignal;
 	interruptSignal?: AbortSignal;
+	timeoutMs?: number;
+	deadlineAt?: number;
 	allowIntercomDetach?: boolean;
 	intercomEvents?: IntercomEventBus;
 	onUpdate?: (r: import("@earendil-works/pi-agent-core").AgentToolResult<Details>) => void;
@@ -782,7 +788,7 @@ export interface RunSyncOptions {
 	availableModels?: Array<{ provider: string; id: string; fullId: string }>;
 	/** Current parent-session provider to prefer for ambiguous bare model ids */
 	preferredModelProvider?: string;
-	/** Skills to inject (overrides agent default if provided) */
+	/** Skills to make available (overrides agent default if provided) */
 	skills?: string[];
 	structuredOutput?: {
 		schema: JsonSchemaObject;
@@ -925,7 +931,7 @@ export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
 export const POLL_INTERVAL_MS = 250;
 export const MAX_WIDGET_JOBS = 4;
 export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
-export const SUBAGENT_ACTIONS = ["list", "get", "create", "update", "delete", "status", "interrupt", "resume", "append-step", "doctor"] as const;
+export const SUBAGENT_ACTIONS = ["list", "get", "models", "create", "update", "delete", "status", "interrupt", "resume", "append-step", "doctor"] as const;
 
 export const DEFAULT_FORK_PREAMBLE =
 	"You are a delegated subagent running from a fork of the parent session. " +

package/src/shared/utils.ts

@@ -5,6 +5,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import * as piCodingAgent from "@earendil-works/pi-coding-agent";
 import type { Message } from "@earendil-works/pi-ai";
 import { formatToolCall } from "./formatters.ts";
 import type { AgentProgress, AsyncStatus, Details, DisplayItem, ErrorInfo, SingleResult, ToolCallSummary } from "./types.ts";
@@ -13,11 +14,28 @@ import type { AgentProgress, AsyncStatus, Details, DisplayItem, ErrorInfo, Singl
 // File System Utilities
 // ============================================================================
 
+const DEFAULT_CONFIG_DIR_NAME = ".pi";
+
+export function resolveConfigDirName(codingAgentModule: unknown = piCodingAgent): string {
+	const value = codingAgentModule && typeof codingAgentModule === "object"
+		? (codingAgentModule as { CONFIG_DIR_NAME?: unknown }).CONFIG_DIR_NAME
+		: undefined;
+	return typeof value === "string" && value.trim() ? value : DEFAULT_CONFIG_DIR_NAME;
+}
+
+export function getConfigDirName(): string {
+	return resolveConfigDirName();
+}
+
+export function getProjectConfigDir(projectRoot: string): string {
+	return path.join(projectRoot, getConfigDirName());
+}
+
 export function getAgentDir(): string {
 	const configured = process.env.PI_CODING_AGENT_DIR;
 	if (configured === "~") return os.homedir();
 	if (configured?.startsWith("~/")) return path.join(os.homedir(), configured.slice(2));
-	return configured || path.join(os.homedir(), ".pi", "agent");
+	return configured || path.join(os.homedir(), getConfigDirName(), "agent");
 }
 
 const statusCache = new Map<string, { mtime: number; status: AsyncStatus }>();