pi-subagents 0.60.0 → 0.62.0

package/src/runs/shared/acceptance.ts

@@ -47,7 +47,7 @@ const VALID_EVIDENCE_KINDS: AcceptanceEvidenceKind[] = [
 const VALID_EVIDENCE = new Set<AcceptanceEvidenceKind>(VALID_EVIDENCE_KINDS);
 const ACCEPTANCE_EVIDENCE_HELP = `Supported evidence kinds: ${VALID_EVIDENCE_KINDS.join(", ")}. Example: { level: "checked", evidence: ["commands-run", "changed-files"] }.`;
 const ACCEPTANCE_OBJECT_EXAMPLE = "Example: { level: \"checked\", evidence: [\"commands-run\", \"changed-files\"] }.";
-const ACCEPTANCE_CONFIG_KEYS = new Set(["level", "criteria", "evidence", "verify", "review", "stopRules", "reason"]);
+const ACCEPTANCE_CONFIG_KEYS = new Set(["level", "report", "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"]);
@@ -146,11 +146,46 @@ function inferLevel(input: {
 	};
 }
 
-export function normalizeAcceptanceInput(input: AcceptanceInput | undefined): AcceptanceConfig {
+type AcceptanceInputNormalizationResult = { value: unknown; error?: string };
+
+function normalizeAcceptanceValue(input: unknown, pathLabel = "acceptance"): AcceptanceInputNormalizationResult {
+	if (typeof input !== "string") return { value: input };
+	const trimmed = input.trim();
+	if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return { value: input };
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(trimmed);
+	} catch (error) {
+		return {
+			value: input,
+			error: `${pathLabel} JSON string must encode a valid acceptance object: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		const kind = parsed === null ? "null" : Array.isArray(parsed) ? "an array" : typeof parsed;
+		return { value: input, error: `${pathLabel} JSON string must encode an object; got ${kind}.` };
+	}
+	return { value: parsed };
+}
+
+export function normalizeAcceptanceInput(input: unknown): AcceptanceConfig {
+	const normalized = normalizeAcceptanceValue(input);
+	if (normalized.error) throw new Error(normalized.error);
+	input = normalized.value;
 	if (input === undefined || input === "auto") return { level: "auto" };
 	if (input === false) return { level: "none", reason: "disabled by deprecated false shorthand" };
-	if (typeof input === "string") return { level: input };
-	return { ...input };
+	if (typeof input === "string") return { level: input as AcceptanceConfig["level"] };
+	return { ...(input as AcceptanceConfig) };
+}
+
+export type ResolvedAcceptanceReportMode = "off" | "optional" | "required";
+
+export function resolveAcceptanceReportMode(input: unknown): ResolvedAcceptanceReportMode {
+	const normalized = normalizeAcceptanceValue(input);
+	if (normalized.error) throw new Error(normalized.error);
+	const value = normalized.value;
+	const report = value && typeof value === "object" && !Array.isArray(value) ? (value as AcceptanceConfig).report : undefined;
+	return value === false || report === "off" ? "off" : report === "on" ? "required" : "optional";
 }
 
 type GateAcceptanceNormalizationResult =
@@ -158,7 +193,11 @@ type GateAcceptanceNormalizationResult =
 	| { ok: false; error: string };
 
 export function normalizeGateAcceptance(gate: unknown, acceptance: AcceptanceInput | undefined): GateAcceptanceNormalizationResult {
-	if (gate === undefined) return acceptance === undefined ? { ok: true } : { ok: true, acceptance };
+	if (gate === undefined) {
+		if (acceptance === undefined) return { ok: true };
+		const normalized = normalizeAcceptanceValue(acceptance);
+		return normalized.error ? { ok: false, error: normalized.error } : { ok: true, acceptance: normalized.value as AcceptanceInput };
+	}
 	if (typeof gate !== "string" || !gate.trim()) return { ok: false, error: "gate must be a non-empty command string." };
 	if (acceptance !== undefined) return { ok: false, error: "gate cannot be combined with acceptance; use one gate command or acceptance.verify." };
 	return { ok: true, acceptance: { level: "verified", verify: [{ id: "gate", command: gate.trim() }] } };
@@ -177,6 +216,9 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
 	const errors: string[] = [];
 	if (input === undefined) return errors;
 	if (input === false) return errors;
+	const normalized = normalizeAcceptanceValue(input, pathLabel);
+	if (normalized.error) return [normalized.error];
+	input = normalized.value;
 	if (typeof input === "string") {
 		if (input === "reviewed") errors.push(`${pathLabel} ${EXPLICIT_REVIEWED_UNAVAILABLE}`);
 		else if (!VALID_LEVELS.has(input as AcceptanceLevel)) errors.push(`${pathLabel} has invalid level '${input}'.`);
@@ -197,6 +239,9 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
 	} else 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.`);
 	}
+	if (value.report !== undefined && value.report !== "on" && value.report !== "off") {
+		errors.push(`${pathLabel}.report must be on or off.`);
+	}
 	if (value.level === "none" && (typeof value.reason !== "string" || !value.reason.trim())) {
 		errors.push(`${pathLabel}.reason is required when level is none.`);
 	}
@@ -304,29 +349,45 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
 
 export function validateExecutionAcceptance(input: {
 	acceptance?: unknown;
-	tasks?: Array<{ acceptance?: unknown }>;
+	outputSchema?: unknown;
+	tasks?: Array<{ acceptance?: unknown; outputSchema?: unknown }>;
 	chain?: Array<{
 		acceptance?: unknown;
-		parallel?: Array<{ acceptance?: unknown }> | { acceptance?: unknown };
+		outputSchema?: unknown;
+		parallel?: Array<{ acceptance?: unknown; outputSchema?: unknown }> | { acceptance?: unknown; outputSchema?: unknown };
 	}>;
 }): string[] {
 	const errors = validateAcceptanceInput(input.acceptance, "acceptance");
+	errors.push(...validateAcceptanceReportMode(input.acceptance, input.outputSchema, "acceptance"));
 	for (const [index, task] of (input.tasks ?? []).entries()) {
 		errors.push(...validateAcceptanceInput(task.acceptance, `tasks[${index}].acceptance`));
+		errors.push(...validateAcceptanceReportMode(task.acceptance, task.outputSchema, `tasks[${index}].acceptance`));
 	}
 	for (const [stepIndex, step] of (input.chain ?? []).entries()) {
 		errors.push(...validateAcceptanceInput(step.acceptance, `chain[${stepIndex}].acceptance`));
+		errors.push(...validateAcceptanceReportMode(step.acceptance, step.outputSchema, `chain[${stepIndex}].acceptance`));
 		if (Array.isArray(step.parallel)) {
 			for (const [taskIndex, task] of step.parallel.entries()) {
 				errors.push(...validateAcceptanceInput(task.acceptance, `chain[${stepIndex}].parallel[${taskIndex}].acceptance`));
+				errors.push(...validateAcceptanceReportMode(task.acceptance, task.outputSchema, `chain[${stepIndex}].parallel[${taskIndex}].acceptance`));
 			}
 		} else if (step.parallel) {
 			errors.push(...validateAcceptanceInput(step.parallel.acceptance, `chain[${stepIndex}].parallel.acceptance`));
+			errors.push(...validateAcceptanceReportMode(step.parallel.acceptance, step.parallel.outputSchema, `chain[${stepIndex}].parallel.acceptance`));
 		}
 	}
 	return errors;
 }
 
+function validateAcceptanceReportMode(acceptance: unknown, outputSchema: unknown, pathLabel: string): string[] {
+	const normalized = normalizeAcceptanceValue(acceptance, pathLabel);
+	if (normalized.error) return [];
+	acceptance = normalized.value;
+	if (!acceptance || typeof acceptance !== "object" || Array.isArray(acceptance)) return [];
+	if (!("report" in acceptance)) return [];
+	return outputSchema === undefined ? [`${pathLabel}.report requires outputSchema.`] : [];
+}
+
 function normalizeCriteria(criteria: Array<string | { id?: string; must?: string; evidence?: AcceptanceEvidenceKind[]; severity?: "required" | "recommended" }> | undefined, evidence: AcceptanceEvidenceKind[]): ResolvedAcceptanceGate[] {
 	return (criteria ?? []).map((criterion, index): ResolvedAcceptanceGate => {
 		if (typeof criterion === "string") {
@@ -678,7 +739,15 @@ function parseAcceptanceReportBody(body: string): { report?: AcceptanceReport; e
 	return validateAcceptanceReport(parseReportJson(body));
 }
 
-function parseUnterminatedAcceptanceReportFence(output: string): { report?: AcceptanceReport; error?: string } {
+interface AcceptanceReportParseResult {
+	report?: AcceptanceReport;
+	error?: string;
+	/** True when an acceptance-report signal was found but its envelope was invalid. */
+	malformed?: boolean;
+	sourcePath?: string;
+}
+
+function parseUnterminatedAcceptanceReportFence(output: string): AcceptanceReportParseResult {
 	const opener = /```acceptance[-_]report\b[^\n]*\n/gi.exec(output);
 	if (!opener) return {};
 	const bodyStart = opener.index + opener[0].length;
@@ -687,13 +756,13 @@ function parseUnterminatedAcceptanceReportFence(output: string): { report?: Acce
 		const validation = validateAcceptanceReport(JSON.parse(output.slice(bodyStart).trim()) as unknown);
 		return validation.report
 			? { report: validation.report }
-			: { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}` };
+			: { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}`, malformed: true };
 	} catch (error) {
-		return { error: `Failed to parse acceptance-report: ${error instanceof Error ? error.message : String(error)}` };
+		return { error: `Failed to parse acceptance-report: ${error instanceof Error ? error.message : String(error)}`, malformed: true };
 	}
 }
 
-function parseGenericJsonAcceptanceReportBody(body: string): { report?: AcceptanceReport; error?: string } {
+function parseGenericJsonAcceptanceReportBody(body: string): AcceptanceReportParseResult {
 	const parsed = parseReportJson(body);
 	const normalized = normalizeAcceptanceReportValue(parsed);
 	const hasCriteriaMarker = normalized.value !== null
@@ -704,12 +773,12 @@ function parseGenericJsonAcceptanceReportBody(body: string): { report?: Acceptan
 	const validation = validateAcceptanceReport(parsed);
 	return validation.report
 		? { report: validation.report }
-		: { error: `Invalid acceptance-report: ${validation.errors.join("; ")}` };
+		: { error: `Invalid acceptance-report: ${validation.errors.join("; ")}`, malformed: true };
 }
 
 export const ACCEPTANCE_REPORT_NOT_FOUND = "Structured acceptance report not found.";
 
-export function parseAcceptanceReport(output: string): { report?: AcceptanceReport; error?: string } {
+export function parseAcceptanceReport(output: string): AcceptanceReportParseResult {
 	const explicitFencePresent = /```acceptance[-_]report\b/i.test(output);
 	const fenced = fencedBlocks(output, "acceptance[-_]report");
 	const parseErrors: string[] = [];
@@ -722,17 +791,17 @@ export function parseAcceptanceReport(output: string): { report?: AcceptanceRepo
 			parseErrors.push(error instanceof Error ? error.message : String(error));
 		}
 	}
-	if (parseErrors.length > 0) return { error: `Failed to parse acceptance-report: ${parseErrors.join("; ")}` };
+	if (parseErrors.length > 0) return { error: `Failed to parse acceptance-report: ${parseErrors.join("; ")}`, malformed: true };
 	if (explicitFencePresent) {
 		const recovered = parseUnterminatedAcceptanceReportFence(output);
 		if (recovered.report || recovered.error) return recovered;
-		return { error: "Failed to parse acceptance-report: Empty or unterminated acceptance-report fence." };
+		return { error: "Failed to parse acceptance-report: Empty or unterminated acceptance-report fence.", malformed: true };
 	}
 	for (const body of fencedBlocks(output, "(?:json|jsonc|json5)")) {
 		try {
 			const parsed = parseGenericJsonAcceptanceReportBody(body);
 			if (parsed.report) return { report: parsed.report };
-			if (parsed.error) return { error: `Failed to parse acceptance-report: ${parsed.error}` };
+			if (parsed.error) return { error: `Failed to parse acceptance-report: ${parsed.error}`, malformed: parsed.malformed };
 		} catch {
 			// Ignore unrelated malformed generic JSON. A recognizable report shape
 			// returns exact validation errors above instead of being mistaken for prose.
@@ -742,20 +811,20 @@ export function parseAcceptanceReport(output: string): { report?: AcceptanceRepo
 	if (markerIndex !== -1) {
 		const jsonStart = output.indexOf("{", markerIndex);
 		if (jsonStart === -1) {
-			return { error: "Failed to parse acceptance-report: Expected a JSON object after ACCEPTANCE_REPORT:." };
+			return { error: "Failed to parse acceptance-report: Expected a JSON object after ACCEPTANCE_REPORT:.", malformed: true };
 		}
 		const json = extractBalancedJson(output, jsonStart);
 		if (!json) {
-			return { error: "Failed to parse acceptance-report: Unterminated JSON object after ACCEPTANCE_REPORT:." };
+			return { error: "Failed to parse acceptance-report: Unterminated JSON object after ACCEPTANCE_REPORT:.", malformed: true };
 		}
 		try {
 			const parsed = JSON.parse(json) as unknown;
 			const validation = validateAcceptanceReport(parsed);
 			if (validation.report) return { report: validation.report };
-			return { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}` };
+			return { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}`, malformed: true };
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
-			return { error: `Failed to parse acceptance-report: ${message}` };
+			return { error: `Failed to parse acceptance-report: ${message}`, malformed: true };
 		}
 	}
 	return { error: ACCEPTANCE_REPORT_NOT_FOUND };
@@ -764,14 +833,18 @@ export function parseAcceptanceReport(output: string): { report?: AcceptanceRepo
 function parseAcceptanceReportSources(
 	output: string,
 	fileOutput: { content: string; path: string; authoritative?: boolean } | undefined,
-): { report?: AcceptanceReport; error?: string } {
+): AcceptanceReportParseResult {
 	const fromText = () => parseAcceptanceReport(output);
 	const fromFile = () => {
 		if (!fileOutput) return { error: ACCEPTANCE_REPORT_NOT_FOUND };
 		const parsed = parseAcceptanceReport(fileOutput.content);
 		return parsed.report || parsed.error === ACCEPTANCE_REPORT_NOT_FOUND
 			? parsed
-			: { error: `${parsed.error} (in configured output ${fileOutput.path})` };
+			: {
+				...parsed,
+				error: `${parsed.error} (in configured output ${fileOutput.path})`,
+				sourcePath: fileOutput.path,
+			};
 	};
 	const [primary, secondary] = fileOutput?.authoritative ? [fromFile, fromText] : [fromText, fromFile];
 	const first = primary();
@@ -839,7 +912,7 @@ function validateStringArrayField(errors: string[], value: unknown, pathLabel: s
 	}
 }
 
-function validateAcceptanceReport(value: unknown, pathLabel = ""): { report?: AcceptanceReport; errors: string[] } {
+export function validateAcceptanceReport(value: unknown, pathLabel = ""): { report?: AcceptanceReport; errors: string[] } {
 	const normalized = normalizeAcceptanceReportValue(value, pathLabel);
 	value = normalized.value;
 	pathLabel = normalized.pathLabel;
@@ -1272,7 +1345,7 @@ export async function evaluateAcceptance(input: {
 	 * be misattributed). Searched for the acceptance report; searched before
 	 * the assistant output when `authoritative` (outputMode "file-only").
 	 */
-	fileOutput?: { content: string; path: string; authoritative?: boolean };
+	fileOutput?: { content: string; path: string; authoritative?: boolean; durable?: boolean };
 	report?: AcceptanceReport;
 	reportError?: string;
 	reviewResult?: AcceptanceReviewResult;
@@ -1296,16 +1369,25 @@ export async function evaluateAcceptance(input: {
 	};
 	if (acceptance.level === "none") return ledger;
 
-	const parsed = input.reportError
+	const parsed: AcceptanceReportParseResult = input.reportError
 		? { error: input.reportError }
-		: input.report
+		: input.report !== undefined
 		? (() => {
 			const validation = validateAcceptanceReport(input.report);
 			return validation.report
 				? { report: validation.report }
-				: { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}` };
+				: { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}`, malformed: true };
 		})()
 		: parseAcceptanceReportSources(input.output, input.fileOutput);
+	const durableFileOutput = input.fileOutput?.authoritative && input.fileOutput.durable ? input.fileOutput : undefined;
+	if (parsed.malformed && parsed.sourcePath && durableFileOutput) {
+		ledger.recovery = {
+			status: "available-for-review",
+			reason: "acceptance-metadata-rejected",
+			reportPath: parsed.sourcePath,
+			reportHash: hash(durableFileOutput.content),
+		};
+	}
 	const needsReport = acceptanceRequiresChildReport(acceptance);
 	if (parsed.report) {
 		ledger.childReport = parsed.report;
@@ -1314,6 +1396,10 @@ export async function evaluateAcceptance(input: {
 	} else if (!input.reportOptional || needsReport || parsed.error !== ACCEPTANCE_REPORT_NOT_FOUND) {
 		ledger.childReportParseError = parsed.error;
 		ledger.runtimeChecks.push({ id: "attestation", status: "failed", message: parsed.error ?? "Structured acceptance report missing." });
+		if (ledger.recovery) {
+			ledger.status = "rejected";
+			ledger.evidenceStatus = "rejected";
+		}
 		if (!input.reportOptional) {
 			ledger.status = "rejected";
 			ledger.evidenceStatus = "rejected";

package/src/runs/shared/capability-ceiling.ts

@@ -22,6 +22,7 @@ export interface SubagentCapabilityAudit {
 	requestedTools?: string[];
 	effectiveTools: string[];
 	removedTools: string[];
+	excludeTools?: string[];
 	internalTools: string[];
 	extensionsDenied: boolean;
 	removedExtensionCount: number;

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

@@ -50,7 +50,7 @@ const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outpu
 const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
 	...DYNAMIC_PARALLEL_KEYS,
 	"outputName", "structured", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled", "waitToolDefaultTimeoutMs",
-	"structuredOutput", "structuredOutputSchema", "tools", "allowNestedSubagents", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "capabilityCeiling", "completionGuard", "systemPrompt",
+	"structuredOutput", "structuredOutputSchema", "tools", "excludeTools", "allowNestedSubagents", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "capabilityCeiling", "completionGuard", "systemPrompt",
 	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "launchResolvedExtensions", "requestedCwd",
 ]);
 const DYNAMIC_COLLECT_KEYS = new Set(["as", "outputSchema"]);

package/src/runs/shared/host-step-status.ts

@@ -144,6 +144,7 @@ export function validHostStepNodes(graph: WorkflowGraphSnapshot | undefined): Ho
 export function assertWorkflowGraphHostSteps(graph: WorkflowGraphSnapshot | undefined, source = "status", expectedRunId?: string): void {
 	if (!graph) return;
 	if (expectedRunId !== undefined && graph.runId !== expectedRunId) throw new Error(`Invalid host step '${source}': workflowGraph.runId does not match the status run id.`);
+	if (!Array.isArray(graph.nodes)) throw new Error(`Invalid host step '${source}.workflowGraph': nodes must be an array.`);
 	const hostStepCount = graph.nodes.filter((node) => node.kind === "host-step").length;
 	if (hostStepCount > HOST_STEP_MAX_COUNT) throw new Error(`Invalid host step '${source}': workflowGraph contains more than ${HOST_STEP_MAX_COUNT} host steps.`);
 	const hostSteps: HostStepNodeV1[] = [];

package/src/runs/shared/model-fallback.ts

@@ -321,15 +321,23 @@ export function resolveSubagentModelOverride(
 	const explicit = trimmed && trimmed !== INHERIT_MODEL ? trimmed : undefined;
 	if (!parentModel) throwForUnresolvedEnforcedInheritScope(options?.scope, explicit === undefined || options?.source === "inherited");
 	let resolved: string | undefined;
+	let resolvedFromRegistry = explicit === undefined;
 	if (explicit === undefined) {
 		resolved = parentModel ? `${parentModel.provider}/${parentModel.id}` : undefined;
 	} else {
-		resolved = resolveRequiredSubagentModelCandidate(explicit, availableModels, preferredProvider);
-	}
-	if (resolved && explicit !== undefined && options?.source === "explicit") {
-		throwForExplicitModelExclusion(resolved);
+		const candidate = resolveSubagentModelCandidate(explicit, availableModels, preferredProvider);
+		if (options?.source === "explicit") {
+			resolved = candidate ?? resolveRequiredSubagentModelCandidate(explicit, availableModels, preferredProvider);
+			throwForExplicitModelExclusion(resolved);
+			resolvedFromRegistry = true;
+		} else if (candidate) {
+			resolved = candidate;
+			resolvedFromRegistry = true;
+		} else {
+			resolved = explicit;
+		}
 	}
-	if (resolved && options?.scope) {
+	if (resolved && options?.scope && resolvedFromRegistry) {
 		const source: ModelSource = explicit === undefined ? "inherited" : (options.source ?? "inherited");
 		enforceModelScopes(resolved, options.scope, source, options.onWarn);
 	}
@@ -362,12 +370,33 @@ export function resolveEffectiveSubagentModel(
 	);
 }
 
+export type ModelOrigin = ModelSource | "configured";
+
 export interface BuildModelCandidatesOptions {
 	/** Fallback models warn by default and throw when strict scope enforcement is enabled. */
 	scope?: ModelScopeCheckRule | ModelScopeCheckRule[];
 	onWarn?: (violation: ModelScopeViolation) => void;
 	/** The primary model came from the running parent session, not configuration. */
 	primaryModelFromParent?: boolean;
+	/** How the primary model was selected. Explicit stays strict and does not rotate to fallbacks. */
+	origin?: ModelOrigin;
+}
+
+const ZERO_USABLE_MODEL_CANDIDATES_ERROR =
+	"No usable subagent models remain after registry, scope, and cached-exclusion filtering.";
+
+export function resolveModelOrigin(input: {
+	explicitModel?: string | boolean;
+	agentModel?: string | boolean;
+	parentModel?: ParentModel;
+	fromParent?: boolean;
+	storedOrigin?: ModelOrigin;
+}): ModelOrigin {
+	if (input.storedOrigin) return input.storedOrigin;
+	if (input.fromParent) return "inherited";
+	if (inheritsParentModel(input.explicitModel, input.agentModel, input.parentModel)) return "inherited";
+	const trimmed = typeof input.explicitModel === "string" ? input.explicitModel.trim() : "";
+	return trimmed && trimmed !== INHERIT_MODEL ? "explicit" : "configured";
 }
 
 export function inheritsParentModel(
@@ -388,36 +417,51 @@ export function buildModelCandidates(
 	options?: BuildModelCandidatesOptions,
 ): string[] {
 	if (!primaryModel) throwForUnresolvedEnforcedInheritScope(options?.scope, true);
+	const origin = options?.origin ?? (options?.primaryModelFromParent ? "inherited" : "configured");
+	const scopes = configuredScopes(options?.scope);
+	const warnCachedExclusion = (candidate: string, exclusion: NonNullable<ReturnType<typeof findModelExclusion>>) => {
+		const reason = redactSecretValues((exclusion.reason ?? "runtime-failure").replace(/[\u0000-\u001f\u007f]+/g, " ")).slice(0, 240);
+		console.warn(`[pi-subagents] Skipping model '${candidate}' due to a cached exclusion (reason: ${reason}; expires: ${new Date(exclusion.expiresAt).toISOString()}).`);
+	};
+	if (origin === "explicit" && primaryModel) {
+		const normalized = resolveRequiredSubagentModelCandidate(primaryModel.trim(), availableModels, preferredProvider);
+		throwForExplicitModelExclusion(normalized);
+		enforceModelScopes(normalized, scopes, "explicit", options?.onWarn);
+		primaryModel = normalized;
+	}
 	const seen = new Set<string>();
 	const candidates: string[] = [];
 	const rawCandidates = [primaryModel, ...(fallbackModels ?? [])];
+	let skippedPrimary: string | undefined;
 	for (let index = 0; index < rawCandidates.length; index++) {
 		const raw = rawCandidates[index];
 		if (!raw) continue;
 		const model = raw.trim();
-		const normalized = index === 0
-			? options?.primaryModelFromParent
-				? model
-				: resolveRequiredSubagentModelCandidate(model, availableModels, preferredProvider)
+		const normalized = index === 0 && (origin === "inherited" || origin === "explicit" || options?.primaryModelFromParent)
+			? model
 			: resolveSubagentModelCandidate(model, availableModels, preferredProvider);
 		if (!normalized) {
-			console.warn(`[pi-subagents] Skipping fallback model '${model}' because it is unavailable in this environment.`);
+			if (index === 0) skippedPrimary = model;
+			else console.warn(`[pi-subagents] Skipping fallback model '${model}' because it is unavailable in this environment.`);
 			continue;
 		}
 		if (seen.has(normalized)) continue;
-		const scopes = configuredScopes(options?.scope);
 		if (index > 0 || scopes.some((scope) => scope.enforce === true && scope.strict === true)) {
 			enforceModelScopes(normalized, scopes, "inherited", options?.onWarn);
 		}
 		seen.add(normalized);
 		candidates.push(normalized);
 	}
-	return filterFallbackCandidates(candidates, {
-		onExcluded(candidate, exclusion) {
-			const reason = redactSecretValues((exclusion.reason ?? "runtime-failure").replace(/[\u0000-\u001f\u007f]+/g, " ")).slice(0, 240);
-			console.warn(`[pi-subagents] Skipping model '${candidate}' due to a cached exclusion (reason: ${reason}; expires: ${new Date(exclusion.expiresAt).toISOString()}).`);
-		},
-	});
+	const resolved = filterFallbackCandidates(candidates, { onExcluded: warnCachedExclusion });
+	if (resolved.length === 0) {
+		if (skippedPrimary) resolveRequiredSubagentModelCandidate(skippedPrimary, availableModels, preferredProvider);
+		if (candidates.length > 0) throw new Error(ZERO_USABLE_MODEL_CANDIDATES_ERROR);
+		return resolved;
+	}
+	if (skippedPrimary) {
+		console.warn(`[pi-subagents] Skipping primary model '${skippedPrimary}' because it is unavailable in this environment.`);
+	}
+	return resolved;
 }
 
 const RETRYABLE_MODEL_FAILURE_PATTERNS = [

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

@@ -42,6 +42,7 @@ export interface RunnerSubagentStep {
 	skipPrimaryModelVerification?: boolean;
 	modelVerificationRegistry?: Array<{ provider: string; id: string; fullId: string; contextWindow?: number }>;
 	tools?: string[];
+	excludeTools?: string[];
 	allowNestedSubagents?: boolean;
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
@@ -68,12 +69,7 @@ export interface RunnerSubagentStep {
 	toolTimeoutMs?: number;
 	waitToolEnabled?: boolean;
 	waitToolDefaultTimeoutMs?: number;
-	structuredOutput?: {
-		schema: import("../../shared/types.ts").JsonSchemaObject;
-		schemaPath: string;
-		outputPath: string;
-		acceptanceReportPath?: string;
-	};
+	structuredOutput?: import("./structured-output.ts").StructuredOutputRuntime;
 	structuredOutputSchema?: import("../../shared/types.ts").JsonSchemaObject;
 	agentContract?: import("../../shared/types.ts").AgentContract;
 	definitionDigest?: string;

package/src/runs/shared/permissions.ts

@@ -7,7 +7,7 @@ export interface PermissionConfig { rules?: PermissionRules }
 
 export const PERMISSION_POLICY_ENV = "PI_SUBAGENT_PERMISSION_POLICY";
 export const PERMISSION_AUDIT_PATH_ENV = "PI_SUBAGENT_PERMISSION_AUDIT_PATH";
-const INTERNAL_TOOLS = new Set(["contact_supervisor", "intercom", "subagent_wait", "structured_output"]);
+const INTERNAL_TOOLS = new Set(["contact_supervisor", "intercom", "bg_wait", "structured_output"]);
 const DECISIONS = new Set<PermissionDecision>(["allow", "ask", "deny"]);
 const MAX_POLICY_BYTES = 16 * 1024;
 const MAX_PREVIEW_BYTES = 2048;

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

@@ -20,8 +20,10 @@ import { encodeExtensionBindings, PI_SUBAGENT_EXTENSION_BINDINGS_ENV, type Exten
 import { RUNTIME_EXTENSION_ACK_PATH_ENV } from "./runtime-acknowledged-extensions.ts";
 import {
 	STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV,
+	STRUCTURED_OUTPUT_ACCEPTANCE_REQUIRED_ENV,
 	STRUCTURED_OUTPUT_CAPTURE_ENV,
 	STRUCTURED_OUTPUT_SCHEMA_ENV,
+	type StructuredOutputRuntime,
 } from "./structured-output.ts";
 import {
 	TEMP_ROOT_DIR,
@@ -171,6 +173,7 @@ export interface BuildPiArgsInput {
 	inheritSkills: boolean;
 	requireReadTool?: boolean;
 	tools?: string[];
+	excludeTools?: string[];
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
 	systemPrompt?: string | null;
@@ -201,12 +204,7 @@ export interface BuildPiArgsInput {
 	steerInboxDir?: string;
 	steerCapabilityPath?: string;
 	steerAckDir?: string;
-	structuredOutput?: {
-		schema: JsonSchemaObject;
-		schemaPath: string;
-		outputPath: string;
-		acceptanceReportPath?: string;
-	};
+	structuredOutput?: StructuredOutputRuntime;
 	fast?: boolean;
 	modelCandidates?: readonly string[];
 	toolBudget?: ResolvedToolBudget;
@@ -300,6 +298,7 @@ function resolveFastModeExtension(input: Pick<ResolvePiLaunchToolPlanInput, "fas
 
 export interface ResolvePiLaunchToolPlanInput {
 	tools?: string[];
+	excludeTools?: string[];
 	allowNestedSubagents?: boolean;
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
@@ -329,6 +328,7 @@ export interface PiLaunchToolPlan {
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 	requestedBuiltinTools: string[];
 	declaredBuiltinTools: string[];
+	excludeTools: string[];
 	toolExtensionPaths: string[];
 	resolvedMcpSelections: ResolvedMcpDirectToolSelection[];
 	effectiveMcpSelections: ResolvedMcpDirectToolSelection[];
@@ -499,8 +499,12 @@ export function resolvePiLaunchToolPlan(
 					? ["read", ...requestedBuiltinTools]
 					: requestedBuiltinTools
 				).filter((tool) => !allowedToolSet || allowedToolSet.has(tool));
-	const fanoutAuthorized = declaredBuiltinTools.includes("subagent") || (
+	const excludeTools = [...new Set((input.excludeTools ?? []).map((tool) => tool.trim()).filter(Boolean))];
+	const excludedToolSet = new Set(excludeTools);
+	const effectiveDeclaredBuiltinTools = declaredBuiltinTools.filter((tool) => !excludedToolSet.has(tool));
+	const fanoutAuthorized = effectiveDeclaredBuiltinTools.includes("subagent") || (
 		input.allowNestedSubagents === true &&
+		!excludedToolSet.has("subagent") &&
 		(!allowedToolSet || allowedToolSet.has("subagent"))
 	);
 	const toolExtensionPaths: string[] = capabilityCeiling?.denyExtensions
@@ -524,7 +528,7 @@ export function resolvePiLaunchToolPlan(
 			!allowedToolSet ||
 			allowedToolSet.has(selection.name) ||
 			isLegacyUnderscoreMcpToolAllowed(selection, allowedToolSet, resolvedMcpNames, legacyMcpNameCounts),
-	);
+	).filter((selection) => !excludedToolSet.has(selection.name));
 	const effectiveMcpTools = effectiveMcpSelections.map(
 		(selection) => selection.name,
 	);
@@ -540,10 +544,10 @@ export function resolvePiLaunchToolPlan(
 		input.tools !== undefined ||
 		(input.mcpDirectTools?.length ?? 0) > 0 ||
 		allowedToolSet !== undefined;
-	const internalTools = input.structuredOutput ? ["structured_output"] : [];
+	const internalTools = (input.structuredOutput ? ["structured_output"] : []).filter((tool) => !excludedToolSet.has(tool));
 	const effectiveToolAllowlist = [
 		...new Set([
-			...declaredBuiltinTools,
+			...effectiveDeclaredBuiltinTools,
 			...effectiveMcpTools,
 			...internalTools,
 		]),
@@ -554,11 +558,11 @@ export function resolvePiLaunchToolPlan(
 	// appended intercom alongside contact_supervisor, so that exact pairing is
 	// legacy plumbing, not a user demand for an external intercom provider;
 	// a lone intercom entry stays strictly required (#1207).
-	const legacySupervisorPairing = declaredBuiltinTools.includes("contact_supervisor");
+	const legacySupervisorPairing = effectiveDeclaredBuiltinTools.includes("contact_supervisor");
 	const requiredChildTools = explicitToolAllowlist
 		? [
 				...new Set([
-					...(input.tools !== undefined ? declaredBuiltinTools : []),
+					...(input.tools !== undefined ? effectiveDeclaredBuiltinTools : []),
 					...(input.mcpDirectTools?.length ? effectiveMcpTools : []),
 					...internalTools,
 				].filter((tool) => tool !== "contact_supervisor" && (!legacySupervisorPairing || tool !== "intercom"))),
@@ -620,6 +624,7 @@ export function resolvePiLaunchToolPlan(
 				ceiling: capabilityCeiling,
 				...(requestedToolNames ? { requestedTools: requestedToolNames } : {}),
 				effectiveTools: effectiveToolAllowlist,
+				...(excludeTools.length > 0 ? { excludeTools } : {}),
 				removedTools:
 					requestedToolNames?.filter(
 						(tool) => !effectiveToolAllowlist.includes(tool),
@@ -657,6 +662,7 @@ export function resolvePiLaunchToolPlan(
 		...(capabilityCeiling ? { capabilityCeiling } : {}),
 		requestedBuiltinTools,
 		declaredBuiltinTools,
+		excludeTools,
 		toolExtensionPaths,
 		resolvedMcpSelections,
 		effectiveMcpSelections,
@@ -740,6 +746,7 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 
 	const toolPlan = resolvePiLaunchToolPlan({
 		tools: input.tools,
+		excludeTools: input.excludeTools,
 		allowNestedSubagents: input.allowNestedSubagents,
 		extensions: input.extensions,
 		subagentOnlyExtensions: input.subagentOnlyExtensions,
@@ -766,6 +773,8 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 		);
 		if (toolPlan.effectiveToolAllowlist.length > 0)
 			args.push(toolPlan.effectiveToolAllowlist.join(","));
+	} else if (toolPlan.excludeTools.length > 0) {
+		args.push("--exclude-tools", toolPlan.excludeTools.join(","));
 	}
 	if (toolPlan.disableAmbientExtensions) {
 		args.push("--no-extensions");
@@ -999,10 +1008,13 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 		env[SUBAGENT_CAPABILITY_CEILING_ENV] = encodedCapabilityCeiling;
 	if (encodedPermissionRules)
 		env[PERMISSION_POLICY_ENV] = encodedPermissionRules;
+	env[STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV] = undefined;
+	env[STRUCTURED_OUTPUT_ACCEPTANCE_REQUIRED_ENV] = undefined;
 	if (input.structuredOutput) {
 		env[STRUCTURED_OUTPUT_CAPTURE_ENV] = input.structuredOutput.outputPath;
 		env[STRUCTURED_OUTPUT_SCHEMA_ENV] = input.structuredOutput.schemaPath;
 		if (input.structuredOutput.acceptanceReportPath) env[STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV] = input.structuredOutput.acceptanceReportPath;
+		if (input.structuredOutput.acceptanceReportRequired) env[STRUCTURED_OUTPUT_ACCEPTANCE_REQUIRED_ENV] = "1";
 	}
 	if (input.steerInboxDir) {
 		env[SUBAGENT_STEER_INBOX_ENV] = input.steerInboxDir;