pi-subagents 0.61.0 → 0.62.0

package/src/runs/foreground/execution.ts

@@ -3,12 +3,12 @@
  */
 
 import { spawn } from "node:child_process";
-import { existsSync, unlinkSync } from "node:fs";
+import { existsSync } from "node:fs";
 import * as path from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
 import { discoverAgents, formatUnknownAgentError, unknownAgentDiagnosticContext, type AgentConfig } from "../../agents/agents.ts";
 import { appendAgentRefinementOverlay } from "../../agents/agent-refinements.ts";
-import { alignForkedSessionCwd } from "../../shared/fork-context.ts";
+import { alignForkedSessionCwd } from "../../shared/fork-session-cwd.ts";
 import {
 	ensureArtifactsDir,
 	formatOutputArtifactContent,
@@ -73,7 +73,7 @@ import { readRuntimeAcknowledgedExtensions } from "../shared/runtime-acknowledge
 import { assertAgentAllowedByCapabilityCeiling, decodeSubagentCapabilityCeiling, intersectSubagentCapabilityCeilings, resolveCurrentSubagentCapabilityCeiling, SUBAGENT_CAPABILITY_CEILING_ENV } from "../shared/capability-ceiling.ts";
 import { resolveEffectiveThinking } from "../../shared/model-info.ts";
 import { assertThinkingWithinCeiling, decodeThinkingCeiling, intersectThinkingCeilings, SUBAGENT_THINKING_CEILING_ENV } from "../../shared/thinking-ceiling.ts";
-import { MISSING_STRUCTURED_OUTPUT_CALL_ERROR, readStructuredOutput, readStructuredOutputAcceptanceReport } from "../shared/structured-output.ts";
+import { clearStructuredOutputCaptures, MISSING_STRUCTURED_OUTPUT_CALL_ERROR, readStructuredOutput, readStructuredOutputAcceptanceReport } from "../shared/structured-output.ts";
 import { formatMidToolExitError, formatProcessSignalError, isOrdinaryToolForMidToolExit, isUnexplainedProcessSignal } from "../shared/process-signal.ts";
 import { readChildToolDiagnosticError } from "../shared/tool-availability.ts";
 import { buildTimeoutRecoverySummary, collectTrackedMutationEvidence, snapshotTrackedMutations } from "../shared/mutation-evidence.ts";
@@ -411,6 +411,7 @@ async function runSingleAttempt(
 		inheritSkills: agent.inheritSkills,
 		requireReadTool: Boolean(shared.resolvedSkillNames?.length),
 		tools: agent.tools,
+		excludeTools: agent.excludeTools,
 		allowNestedSubagents: agent.allowNestedSubagents,
 		extensions: agent.extensions,
 		subagentOnlyExtensions: agent.subagentOnlyExtensions,
@@ -464,6 +465,7 @@ async function runSingleAttempt(
 		cwd: options.cwd ?? runtimeCwd,
 		requireReadTool: Boolean(shared.resolvedSkillNames?.length),
 		structuredOutput: Boolean(options.structuredOutput),
+		excludeTools: agent.excludeTools,
 		fast: options.fast ?? agent.fast,
 		model: modelArg,
 		modelCandidates: shared.modelCandidates,
@@ -520,6 +522,7 @@ async function runSingleAttempt(
 		inheritSkills: agent.inheritSkills,
 		skills: shared.resolvedSkillNames ?? [],
 		tools: toolPlan.effectiveToolAllowlist,
+		...(toolPlan.excludeTools.length > 0 ? { excludeTools: toolPlan.excludeTools } : {}),
 		extensions: toolPlan.extensionArgs,
 		mcpDirectTools: toolPlan.effectiveMcpTools,
 		...(options.outputPath ? { outputPath: options.outputPath } : {}),
@@ -551,10 +554,14 @@ async function runSingleAttempt(
 	}, options.context);
 	const startTime = Date.now();
 	if (options.structuredOutput) {
-		try {
-			if (existsSync(options.structuredOutput.outputPath)) unlinkSync(options.structuredOutput.outputPath);
-		} catch {
-			// Missing/stale structured-output files are handled after the child exits.
+		const cleanupError = clearStructuredOutputCaptures(options.structuredOutput);
+		if (cleanupError) {
+			cleanupTempDir(tempDir);
+			result.exitCode = 1;
+			result.error = cleanupError;
+			result.finalOutput = cleanupError;
+			result.progressSummary = { toolCount: 0, tokens: 0, durationMs: Date.now() - startTime };
+			return result;
 		}
 	}
 	const controlConfig = options.controlConfig ?? DEFAULT_CONTROL_CONFIG;

package/src/runs/foreground/subagent-executor.ts

@@ -50,7 +50,7 @@ import { acquireActiveAsyncCapacity, ActiveAsyncCapacityError, getActiveAsyncCap
 import { isScheduledRunAction } from "../background/scheduled-runs.ts";
 import { enqueueChainAppendRequest, readPendingChainAppendRequests, runnerStepOutputNames } from "../background/chain-append.ts";
 import { ChainOutputValidationError, validateChainOutputBindingsWithContext } from "../shared/chain-outputs.ts";
-import { normalizeGateAcceptance, validateExecutionAcceptance } from "../shared/acceptance.ts";
+import { normalizeGateAcceptance, resolveAcceptanceReportMode, validateExecutionAcceptance } from "../shared/acceptance.ts";
 import { canPreferFork, createForkContextResolver, forkedChildRequiresThinkingOff, resolveSubagentLaunchContext } from "../../shared/fork-context.ts";
 import { createPrunedForkSessionWriter } from "../../shared/pruned-fork.ts";
 import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
@@ -393,6 +393,7 @@ export interface SubagentParamsLike {
 	agentContract?: AgentContract;
 	at?: string;
 	every?: string;
+	sessionOnly?: boolean;
 	on?: string | number;
 	timezone?: string;
 	overlap?: "skip";
@@ -3690,7 +3691,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		return { content: [{ type: "text", text: validationError }], isError: true, details: { mode: "single", results: [] } };
 	}
 	const structuredRuntime = params.outputSchema
-		? createStructuredOutputRuntime(params.outputSchema, artifactConfig.enabled ? path.join(artifactsDir, "structured-output", runId) : undefined, { captureAcceptanceReport: params.acceptance !== false })
+		? createStructuredOutputRuntime(params.outputSchema, artifactConfig.enabled ? path.join(artifactsDir, "structured-output", runId) : undefined, { acceptanceReport: resolveAcceptanceReportMode(params.acceptance) })
 		: undefined;
 	// Reads: caller override > agent defaultReads > none. `~`/`~/` expand to home;
 	// absolute paths pass through; relative paths resolve against the child cwd.

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") {
@@ -851,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;
@@ -1310,7 +1371,7 @@ export async function evaluateAcceptance(input: {
 
 	const parsed: AcceptanceReportParseResult = input.reportError
 		? { error: input.reportError }
-		: input.report
+		: input.report !== undefined
 		? (() => {
 			const validation = validateAcceptanceReport(input.report);
 			return validation.report

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/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", "bg_wait", "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;

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

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import { PI_CODING_AGENT_PACKAGE_ROOT_ENV } from "../../shared/utils.ts";
 
 export const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
 export const PI_SUBAGENT_PI_BINARY_ENV = "PI_SUBAGENT_PI_BINARY";
@@ -23,9 +24,13 @@ export function findPiPackageRootFromEntry(
 }
 
 export function resolveInstalledPiPackageRoot(): string | undefined {
-	return findPiPackageRootFromEntry(
-		fileURLToPath(import.meta.resolve(PI_CODING_AGENT_PACKAGE)),
-	);
+	try {
+		return findPiPackageRootFromEntry(
+			fileURLToPath(import.meta.resolve(PI_CODING_AGENT_PACKAGE)),
+		);
+	} catch {
+		return undefined;
+	}
 }
 
 export function resolvePiPackageRoot(): string | undefined {
@@ -58,12 +63,21 @@ interface PiSpawnCommand {
 	args: string[];
 }
 
+interface PiPackageJson {
+	name?: unknown;
+	bin?: string | Record<string, string>;
+}
+
+function isNodeScriptPath(filePath: string): boolean {
+	return /\.(?:mjs|cjs|js)$/i.test(filePath);
+}
+
 function isRunnableNodeScript(
 	filePath: string,
 	existsSync: (filePath: string) => boolean,
 ): boolean {
 	if (!existsSync(filePath)) return false;
-	return /\.(?:mjs|cjs|js)$/i.test(filePath);
+	return isNodeScriptPath(filePath);
 }
 
 function normalizePath(filePath: string): string {
@@ -75,6 +89,23 @@ function isStandalonePiExecutable(execPath: string): boolean {
 	return /^pi(?:\.exe)?$/i.test(executableName ?? "");
 }
 
+function resolvePiCliScriptFromPackageJson(
+	packageJsonPath: string,
+	readFileSync: (filePath: string, encoding: "utf-8") => string,
+	existsSync: (filePath: string) => boolean,
+): string | undefined {
+	const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as PiPackageJson;
+	if (packageJson.name !== PI_CODING_AGENT_PACKAGE) return undefined;
+	const binField = packageJson.bin;
+	const binPath =
+		typeof binField === "string"
+			? binField
+			: (binField?.pi ?? Object.values(binField ?? {})[0]);
+	if (!binPath) return undefined;
+	const candidate = path.resolve(path.dirname(packageJsonPath), binPath);
+	return isRunnableNodeScript(candidate, existsSync) ? candidate : undefined;
+}
+
 export function resolvePiCliScript(
 	deps: PiSpawnDeps = {},
 ): string | undefined {
@@ -84,6 +115,7 @@ export function resolvePiCliScript(
 		deps.readFileSync ??
 		((filePath, encoding) => fs.readFileSync(filePath, encoding));
 	const argv1 = deps.argv1 ?? process.argv[1];
+	const env = deps.env ?? process.env;
 
 	if (argv1) {
 		const argvPath = normalizePath(argv1);
@@ -99,38 +131,28 @@ export function resolvePiCliScript(
 		}
 	}
 
-	try {
-		const resolvePackageJson =
-			deps.resolvePackageJson ??
-			(() => {
-				const root = deps.piPackageRoot ?? resolvePiPackageRoot();
-				if (root) return path.join(root, "package.json");
-				const packageRoot = deps.resolvePackageEntry
-					? findPiPackageRootFromEntry(deps.resolvePackageEntry())
-					: resolveInstalledPiPackageRoot();
-				if (!packageRoot)
-					throw new Error(
-						`Could not resolve ${PI_CODING_AGENT_PACKAGE} package root`,
-					);
-				return path.join(packageRoot, "package.json");
-			});
-		const packageJsonPath = resolvePackageJson();
-		const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as {
-			bin?: string | Record<string, string>;
-		};
-		const binField = packageJson.bin;
-		const binPath =
-			typeof binField === "string"
-				? binField
-				: (binField?.pi ?? Object.values(binField ?? {})[0]);
-		if (!binPath) return undefined;
-		const candidate = path.resolve(path.dirname(packageJsonPath), binPath);
-		if (isRunnableNodeScript(candidate, existsSync)) {
-			return candidate;
+	const packageJsonCandidates: Array<() => string | undefined> = [];
+	if (deps.resolvePackageJson) packageJsonCandidates.push(deps.resolvePackageJson);
+	for (const root of [deps.piPackageRoot, env[PI_CODING_AGENT_PACKAGE_ROOT_ENV], resolvePiPackageRoot()]) {
+		const trimmed = root?.trim();
+		if (trimmed) packageJsonCandidates.push(() => path.join(trimmed, "package.json"));
+	}
+	packageJsonCandidates.push(() => {
+		const packageRoot = deps.resolvePackageEntry
+			? findPiPackageRootFromEntry(deps.resolvePackageEntry())
+			: resolveInstalledPiPackageRoot();
+		return packageRoot ? path.join(packageRoot, "package.json") : undefined;
+	});
+
+	for (const candidatePackageJson of packageJsonCandidates) {
+		try {
+			const packageJsonPath = candidatePackageJson();
+			if (!packageJsonPath) continue;
+			const candidate = resolvePiCliScriptFromPackageJson(packageJsonPath, readFileSync, existsSync);
+			if (candidate) return candidate;
+		} catch {
+			// Keep resolving; callers decide whether a PATH fallback is safe.
 		}
-	} catch {
-		// Verified CLI resolution is optional; falling back to `pi` lets PATH handle execution.
-		return undefined;
 	}
 
 	return undefined;
@@ -140,9 +162,16 @@ export function getPiSpawnCommand(
 	args: string[],
 	deps: PiSpawnDeps = {},
 ): PiSpawnCommand {
+	const platform = deps.platform ?? process.platform;
 	const env = deps.env ?? process.env;
 	const piBinary = env[PI_SUBAGENT_PI_BINARY_ENV]?.trim();
 	if (piBinary) {
+		if (platform === "win32" && isNodeScriptPath(piBinary)) {
+			return {
+				command: deps.execPath ?? process.execPath,
+				args: [piBinary, ...args],
+			};
+		}
 		return { command: piBinary, args };
 	}
 
@@ -158,6 +187,11 @@ export function getPiSpawnCommand(
 			args: [piCliPath, ...args],
 		};
 	}
+	if (platform === "win32") {
+		throw new Error(
+			`Could not resolve the Pi CLI on Windows. Set ${PI_SUBAGENT_PI_BINARY_ENV} or ensure ${PI_CODING_AGENT_PACKAGE} is installed.`,
+		);
+	}
 
 	return { command: "pi", args };
 }