pi-subagents 0.36.0 → 0.37.1

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

@@ -3,16 +3,17 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { encodeNestedPathEnv, parseNestedPathEnv, type NestedPathEntry } from "./nested-path.ts";
-import { resolveMcpDirectToolNames } from "./mcp-direct-tool-allowlist.ts";
+import { resolveMcpDirectToolSelections, type ResolvedMcpDirectToolSelection } from "./mcp-direct-tool-allowlist.ts";
 import { resolvePiPackageRoot } from "./pi-spawn.ts";
 import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV } from "./structured-output.ts";
 import { TEMP_ROOT_DIR, type JsonSchemaObject, type ResolvedToolBudget } from "../../shared/types.ts";
 import { THINKING_LEVELS } from "../../shared/model-info.ts";
 import { TOOL_BUDGET_ENV, TOOL_BUDGET_ZERO_AUTH_ENV, encodeToolBudgetEnv } from "./tool-budget.ts";
-import { CHILD_TOOL_DIAGNOSTIC_PATH_ENV, REQUIRED_CHILD_TOOLS_ENV } from "./tool-availability.ts";
+import { CHILD_TOOL_DIAGNOSTIC_PATH_ENV, MCP_DIRECT_CHILD_TOOLS_ENV, REQUIRED_CHILD_TOOLS_ENV } from "./tool-availability.ts";
 import { CHILD_WATCHDOG_CONFIG_ENV, encodeChildWatchdogConfig, type ChildWatchdogConfig } from "../../watchdog/child-status.ts";
 import { WAIT_TOOL_ENABLED_ENV } from "../background/wait-config.ts";
 import { PI_CODING_AGENT_PACKAGE_ROOT_ENV } from "../../shared/utils.ts";
+import { SUBAGENT_CAPABILITY_CEILING_ENV, decodeSubagentCapabilityCeiling, encodeSubagentCapabilityCeiling, intersectSubagentCapabilityCeilings, type ResolvedSubagentCapabilityCeiling, type SubagentCapabilityAudit } from "./capability-ceiling.ts";
 
 const TASK_ARG_LIMIT = 8000;
 const PROMPT_RUNTIME_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "subagent-prompt-runtime.ts");
@@ -38,7 +39,7 @@ export const SUBAGENT_STEER_INBOX_ENV = "PI_SUBAGENT_STEER_INBOX";
 export const SUBAGENT_STEER_CAPABILITY_ENV = "PI_SUBAGENT_STEER_CAPABILITY";
 export const SUBAGENT_STEER_ACK_DIR_ENV = "PI_SUBAGENT_STEER_ACK_DIR";
 
-interface BuildPiArgsInput {
+export interface BuildPiArgsInput {
 	parentSessionId?: string;
 	baseArgs: string[];
 	task: string;
@@ -83,13 +84,15 @@ interface BuildPiArgsInput {
 	allowZeroToolBudget?: boolean;
 	childWatchdog?: ChildWatchdogConfig;
 	waitToolEnabled?: boolean;
+	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 }
 
-interface BuildPiArgsResult {
+export interface BuildPiArgsResult {
 	args: string[];
 	env: Record<string, string | undefined>;
 	tempDir?: string;
 	toolDiagnosticPath?: string;
+	capabilityAudit?: SubagentCapabilityAudit;
 }
 
 function sanitizeSupervisorChannelSegment(value: string): string {
@@ -109,6 +112,106 @@ export function applyThinkingSuffix(model: string | undefined, thinking: string
 	return `${model}:${thinking}`;
 }
 
+export interface ResolvePiLaunchToolPlanInput {
+	tools?: string[];
+	extensions?: string[];
+	subagentOnlyExtensions?: string[];
+	mcpDirectTools?: string[];
+	cwd?: string;
+	requireReadTool?: boolean;
+	structuredOutput?: boolean;
+	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	inheritedCapabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+}
+
+export interface PiLaunchToolPlan {
+	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	requestedBuiltinTools: string[];
+	declaredBuiltinTools: string[];
+	toolExtensionPaths: string[];
+	resolvedMcpSelections: ResolvedMcpDirectToolSelection[];
+	effectiveMcpSelections: ResolvedMcpDirectToolSelection[];
+	effectiveMcpTools: string[];
+	explicitToolAllowlist: boolean;
+	internalTools: string[];
+	effectiveToolAllowlist: string[];
+	requiredChildTools: string[];
+	fanoutAuthorized: boolean;
+	runtimeExtensions: string[];
+	configuredExtensions: string[];
+	extensionArgs: string[];
+	disableAmbientExtensions: boolean;
+	capabilityAudit?: SubagentCapabilityAudit;
+}
+
+export function resolvePiLaunchToolPlan(input: ResolvePiLaunchToolPlanInput): PiLaunchToolPlan {
+	const capabilityCeiling = intersectSubagentCapabilityCeilings(input.capabilityCeiling, input.inheritedCapabilityCeiling);
+	const allowedToolSet = capabilityCeiling?.allowedTools === undefined ? undefined : new Set(capabilityCeiling.allowedTools);
+	const requestedBuiltinTools = input.tools?.filter((tool) => !(tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) ?? [];
+	if (input.requireReadTool && allowedToolSet && !allowedToolSet.has("read")) {
+		throw new Error(`Capability ceiling from ${capabilityCeiling?.sources.join(", ") || "unknown source"} excludes required tool 'read' for lazy skill loading.`);
+	}
+	const declaredBuiltinTools = input.tools === undefined
+		? (allowedToolSet ? [...allowedToolSet] : [])
+		: (input.requireReadTool && requestedBuiltinTools.length > 0 && !requestedBuiltinTools.includes("read") && !allowedToolSet
+			? ["read", ...requestedBuiltinTools]
+			: requestedBuiltinTools).filter((tool) => !allowedToolSet || allowedToolSet.has(tool));
+	const fanoutAuthorized = declaredBuiltinTools.includes("subagent");
+	const toolExtensionPaths: string[] = capabilityCeiling?.denyExtensions ? [] : (input.tools ?? []).filter((tool) => !requestedBuiltinTools.includes(tool) && (tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js")));
+	const resolvedMcpSelections = capabilityCeiling?.denyExtensions ? [] : resolveMcpDirectToolSelections(input.mcpDirectTools, input.cwd);
+	const effectiveMcpSelections = resolvedMcpSelections.filter((selection) => !allowedToolSet || allowedToolSet.has(selection.name));
+	const effectiveMcpTools = effectiveMcpSelections.map((selection) => selection.name);
+	const explicitToolAllowlist = input.tools !== undefined || (input.mcpDirectTools?.length ?? 0) > 0 || allowedToolSet !== undefined;
+	const internalTools = input.structuredOutput ? ["structured_output"] : [];
+	const effectiveToolAllowlist = [...new Set([...declaredBuiltinTools, ...effectiveMcpTools, ...internalTools])];
+	const requiredChildTools = explicitToolAllowlist ? [...new Set([
+		...(input.tools !== undefined ? declaredBuiltinTools : []),
+		...(input.mcpDirectTools?.length ? effectiveMcpTools : []),
+		...internalTools,
+	])] : [];
+	const runtimeExtensions = fanoutAuthorized
+		? [PROMPT_RUNTIME_EXTENSION_PATH, FANOUT_CHILD_EXTENSION_PATH]
+		: [PROMPT_RUNTIME_EXTENSION_PATH];
+	const disableAmbientExtensions = capabilityCeiling?.denyExtensions === true || input.extensions !== undefined;
+	const configuredExtensions = capabilityCeiling?.denyExtensions ? [] : [...toolExtensionPaths, ...(input.extensions ?? []), ...(input.subagentOnlyExtensions ?? [])];
+	const extensionArgs = disableAmbientExtensions
+		? [...new Set([...runtimeExtensions, ...configuredExtensions])]
+		: [...new Set([...runtimeExtensions, ...toolExtensionPaths, ...(input.subagentOnlyExtensions ?? [])])];
+	const requestedToolNames = input.tools !== undefined
+		? [...new Set([...requestedBuiltinTools, ...resolvedMcpSelections.map((selection) => selection.name)])]
+		: undefined;
+	const capabilityAudit = capabilityCeiling ? {
+		ceiling: capabilityCeiling,
+		...(requestedToolNames ? { requestedTools: requestedToolNames } : {}),
+		effectiveTools: effectiveToolAllowlist,
+		removedTools: requestedToolNames?.filter((tool) => !effectiveToolAllowlist.includes(tool)) ?? [],
+		internalTools,
+		extensionsDenied: capabilityCeiling.denyExtensions,
+		removedExtensionCount: capabilityCeiling.denyExtensions ? (input.extensions?.length ?? 0) + (input.subagentOnlyExtensions?.length ?? 0) + ((input.tools ?? []).filter((tool) => tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js")).length) : 0,
+		requestedMcpToolCount: input.mcpDirectTools?.length ?? 0,
+		effectiveMcpTools,
+	} satisfies SubagentCapabilityAudit : undefined;
+	return {
+		...(capabilityCeiling ? { capabilityCeiling } : {}),
+		requestedBuiltinTools,
+		declaredBuiltinTools,
+		toolExtensionPaths,
+		resolvedMcpSelections,
+		effectiveMcpSelections,
+		effectiveMcpTools,
+		explicitToolAllowlist,
+		internalTools,
+		effectiveToolAllowlist,
+		requiredChildTools,
+		fanoutAuthorized,
+		runtimeExtensions,
+		configuredExtensions,
+		extensionArgs,
+		disableAmbientExtensions,
+		...(capabilityAudit ? { capabilityAudit } : {}),
+	};
+}
+
 export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	const args = [...input.baseArgs];
 
@@ -130,46 +233,25 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 		args.push("--model", modelArg);
 	}
 
-	const explicitToolAllowlist = input.tools !== undefined || (input.mcpDirectTools?.length ?? 0) > 0;
-	const declaredBuiltinToolsBase = input.tools?.filter((tool) => !(tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) ?? [];
-	const declaredBuiltinTools = input.requireReadTool && declaredBuiltinToolsBase.length > 0 && !declaredBuiltinToolsBase.includes("read")
-		? ["read", ...declaredBuiltinToolsBase]
-		: declaredBuiltinToolsBase;
-	const fanoutAuthorized = declaredBuiltinTools.includes("subagent");
-	const toolExtensionPaths: string[] = [];
-	let requiredChildTools: string[] = [];
-	for (const tool of input.tools ?? []) {
-		if (!declaredBuiltinTools.includes(tool) && (tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) {
-			toolExtensionPaths.push(tool);
-		}
+	const toolPlan = resolvePiLaunchToolPlan({
+		tools: input.tools,
+		extensions: input.extensions,
+		subagentOnlyExtensions: input.subagentOnlyExtensions,
+		mcpDirectTools: input.mcpDirectTools,
+		cwd: input.cwd,
+		requireReadTool: input.requireReadTool,
+		structuredOutput: input.structuredOutput,
+		capabilityCeiling: input.capabilityCeiling,
+		inheritedCapabilityCeiling: decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV]),
+	});
+	if (toolPlan.explicitToolAllowlist) {
+		args.push(toolPlan.effectiveToolAllowlist.length > 0 ? "--tools" : "--no-tools");
+		if (toolPlan.effectiveToolAllowlist.length > 0) args.push(toolPlan.effectiveToolAllowlist.join(","));
 	}
-	if (explicitToolAllowlist) {
-		const allowedTools = [
-			...declaredBuiltinTools,
-			...resolveMcpDirectToolNames(input.mcpDirectTools, input.cwd),
-			...(input.structuredOutput ? ["structured_output"] : []),
-		];
-		requiredChildTools = [...new Set(allowedTools)];
-		if (requiredChildTools.length > 0) {
-			args.push("--tools", requiredChildTools.join(","));
-		} else {
-			args.push("--no-tools");
-		}
-	}
-
-	const runtimeExtensions = fanoutAuthorized
-		? [PROMPT_RUNTIME_EXTENSION_PATH, FANOUT_CHILD_EXTENSION_PATH]
-		: [PROMPT_RUNTIME_EXTENSION_PATH];
-	if (input.extensions !== undefined) {
+	if (toolPlan.disableAmbientExtensions) {
 		args.push("--no-extensions");
-		for (const extPath of [...new Set([...runtimeExtensions, ...toolExtensionPaths, ...input.extensions, ...(input.subagentOnlyExtensions ?? [])])]) {
-			args.push("--extension", extPath);
-		}
-	} else {
-		for (const extPath of [...new Set([...runtimeExtensions, ...toolExtensionPaths, ...(input.subagentOnlyExtensions ?? [])])]) {
-			args.push("--extension", extPath);
-		}
 	}
+	for (const extPath of toolPlan.extensionArgs) args.push("--extension", extPath);
 
 	if (!input.inheritSkills) {
 		args.push("--no-skills");
@@ -199,14 +281,15 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	const piPackageRoot = process.env[PI_CODING_AGENT_PACKAGE_ROOT_ENV] ?? resolvePiPackageRoot();
 	if (piPackageRoot) env[PI_CODING_AGENT_PACKAGE_ROOT_ENV] = piPackageRoot;
 	let toolDiagnosticPath: string | undefined;
-	if (requiredChildTools.length > 0) {
+	if (toolPlan.requiredChildTools.length > 0) {
 		if (!tempDir) tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
 		toolDiagnosticPath = path.join(tempDir, "tool-diagnostic.json");
-		env[REQUIRED_CHILD_TOOLS_ENV] = JSON.stringify(requiredChildTools);
+		env[REQUIRED_CHILD_TOOLS_ENV] = JSON.stringify(toolPlan.requiredChildTools);
 		env[CHILD_TOOL_DIAGNOSTIC_PATH_ENV] = toolDiagnosticPath;
 	}
+	env[MCP_DIRECT_CHILD_TOOLS_ENV] = toolPlan.effectiveMcpTools.length > 0 ? JSON.stringify(toolPlan.effectiveMcpTools) : undefined;
 	env[SUBAGENT_CHILD_ENV] = "1";
-	env[SUBAGENT_FANOUT_CHILD_ENV] = fanoutAuthorized ? "1" : "0";
+	env[SUBAGENT_FANOUT_CHILD_ENV] = toolPlan.fanoutAuthorized ? "1" : "0";
 	if (input.waitToolEnabled !== undefined) {
 		env[WAIT_TOOL_ENABLED_ENV] = input.waitToolEnabled ? "true" : "false";
 	}
@@ -227,20 +310,20 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 			...(input.childAgentName ? { agent: input.childAgentName } : {}),
 		}] : []),
 	];
-	env[SUBAGENT_PARENT_EVENT_SINK_ENV] = fanoutAuthorized
+	env[SUBAGENT_PARENT_EVENT_SINK_ENV] = toolPlan.fanoutAuthorized
 		? input.parentEventSink ?? process.env[SUBAGENT_PARENT_EVENT_SINK_ENV] ?? ""
 		: "";
-	env[SUBAGENT_PARENT_CONTROL_INBOX_ENV] = fanoutAuthorized
+	env[SUBAGENT_PARENT_CONTROL_INBOX_ENV] = toolPlan.fanoutAuthorized
 		? input.parentControlInbox ?? process.env[SUBAGENT_PARENT_CONTROL_INBOX_ENV] ?? ""
 		: "";
-	env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] = fanoutAuthorized
+	env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] = toolPlan.fanoutAuthorized
 		? input.parentRootRunId ?? process.env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] ?? input.runId ?? ""
 		: "";
-	env[SUBAGENT_PARENT_RUN_ID_ENV] = fanoutAuthorized ? parentRunId : "";
-	env[SUBAGENT_PARENT_CHILD_INDEX_ENV] = fanoutAuthorized ? parentChildIndex : "";
-	env[SUBAGENT_PARENT_DEPTH_ENV] = fanoutAuthorized ? String(parentDepth) : "";
-	env[SUBAGENT_PARENT_PATH_ENV] = fanoutAuthorized ? encodeNestedPathEnv(parentPath) : "";
-	env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV] = fanoutAuthorized
+	env[SUBAGENT_PARENT_RUN_ID_ENV] = toolPlan.fanoutAuthorized ? parentRunId : "";
+	env[SUBAGENT_PARENT_CHILD_INDEX_ENV] = toolPlan.fanoutAuthorized ? parentChildIndex : "";
+	env[SUBAGENT_PARENT_DEPTH_ENV] = toolPlan.fanoutAuthorized ? String(parentDepth) : "";
+	env[SUBAGENT_PARENT_PATH_ENV] = toolPlan.fanoutAuthorized ? encodeNestedPathEnv(parentPath) : "";
+	env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV] = toolPlan.fanoutAuthorized
 		? input.parentCapabilityToken ?? process.env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV] ?? ""
 		: "";
 	env.PI_SUBAGENT_INHERIT_PROJECT_CONTEXT = input.inheritProjectContext ? "1" : "0";
@@ -270,11 +353,11 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	if (input.childIndex !== undefined) {
 		env[SUBAGENT_CHILD_INDEX_ENV] = String(input.childIndex);
 	}
-	if (input.mcpDirectTools?.length) {
-		env.MCP_DIRECT_TOOLS = input.mcpDirectTools.join(",");
-	} else {
-		env.MCP_DIRECT_TOOLS = "__none__";
-	}
+	if (!toolPlan.capabilityCeiling && input.mcpDirectTools?.length) env.MCP_DIRECT_TOOLS = input.mcpDirectTools.join(",");
+	else if (toolPlan.capabilityCeiling && toolPlan.effectiveMcpSelections.length && !toolPlan.capabilityCeiling.denyExtensions) env.MCP_DIRECT_TOOLS = toolPlan.effectiveMcpSelections.map((selection) => selection.selector).join(",");
+	else env.MCP_DIRECT_TOOLS = "__none__";
+	const encodedCapabilityCeiling = encodeSubagentCapabilityCeiling(toolPlan.capabilityCeiling);
+	if (encodedCapabilityCeiling) env[SUBAGENT_CAPABILITY_CEILING_ENV] = encodedCapabilityCeiling;
 	if (input.structuredOutput) {
 		env[STRUCTURED_OUTPUT_CAPTURE_ENV] = input.structuredOutput.outputPath;
 		env[STRUCTURED_OUTPUT_SCHEMA_ENV] = input.structuredOutput.schemaPath;
@@ -292,7 +375,7 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 
 	env[SUBAGENT_PARENT_SESSION_ENV] = input.parentSessionId ?? process.env[SUBAGENT_PARENT_SESSION_ENV] ?? "";
 
-	return { args, env, tempDir, toolDiagnosticPath };
+	return { args, env, tempDir, toolDiagnosticPath, capabilityAudit: toolPlan.capabilityAudit };
 }
 
 export const parseParentPathEnv = parseNestedPathEnv;

package/src/runs/shared/session-lease.ts

@@ -37,9 +37,14 @@ export interface SessionLeaseHandle {
 	leaseDir: string;
 	owner: SessionLeaseOwner;
 	updateWriter(writer: { state: "none" | "spawning" } | { state: "running"; pid: number }): void;
-	release(): void;
+	release(): boolean;
 }
 
+export type SessionLeaseState =
+	| { state: "free"; canonicalSessionFile: string; canonicalSessionId: string }
+	| { state: "owned"; canonicalSessionFile: string; canonicalSessionId: string; owner: SessionLeaseOwner }
+	| { state: "unreadable"; canonicalSessionFile: string; canonicalSessionId: string };
+
 interface SessionLeaseOptions {
 	rootDir?: string;
 	now?: () => number;
@@ -98,11 +103,25 @@ export function canonicalSessionFilePath(sessionFile: string): string {
 	return fs.realpathSync.native(path.resolve(sessionFile));
 }
 
-export function sessionLeaseDir(sessionFile: string, rootDir = SESSION_LEASES_DIR): string {
+export function canonicalSessionId(sessionFile: string): string {
 	const canonical = canonicalSessionFilePath(sessionFile);
 	const key = process.platform === "win32" ? canonical.toLowerCase() : canonical;
-	const digest = createHash("sha256").update(key).digest("hex");
-	return path.join(rootDir, digest);
+	return createHash("sha256").update(key).digest("hex");
+}
+
+export function sessionLeaseDir(sessionFile: string, rootDir = SESSION_LEASES_DIR): string {
+	return path.join(rootDir, canonicalSessionId(sessionFile));
+}
+
+export function inspectSessionLease(sessionFile: string, rootDir = SESSION_LEASES_DIR): SessionLeaseState {
+	const canonicalSessionFile = canonicalSessionFilePath(sessionFile);
+	const canonicalSessionIdValue = canonicalSessionId(canonicalSessionFile);
+	const leaseDir = path.join(rootDir, canonicalSessionIdValue);
+	if (!fs.existsSync(leaseDir)) return { state: "free", canonicalSessionFile, canonicalSessionId: canonicalSessionIdValue };
+	const owner = readLeaseOwner(leaseDir);
+	return owner
+		? { state: "owned", canonicalSessionFile, canonicalSessionId: canonicalSessionIdValue, owner }
+		: { state: "unreadable", canonicalSessionFile, canonicalSessionId: canonicalSessionIdValue };
 }
 
 function parseOwner(value: unknown): SessionLeaseOwner | undefined {
@@ -251,8 +270,9 @@ export function acquireSessionLease(request: SessionLeaseRequest, options: Sessi
 				},
 				release() {
 					const currentOwner = readLeaseOwner(leaseDir);
-					if (!currentOwner || currentOwner.token !== owner.token) return;
+					if (!currentOwner || currentOwner.token !== owner.token) return false;
 					fs.rmSync(leaseDir, { recursive: true, force: true });
+					return !fs.existsSync(leaseDir);
 				},
 			};
 		}

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -7,6 +7,7 @@ import { SUBAGENT_CHILD_AGENT_ENV, SUBAGENT_CHILD_INDEX_ENV, SUBAGENT_FANOUT_CHI
 import { createStructuredOutputToolParameters, STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
 import {
 	CHILD_TOOL_DIAGNOSTIC_PATH_ENV,
+	MCP_DIRECT_CHILD_TOOLS_ENV,
 	REQUIRED_CHILD_TOOLS_ENV,
 	writeChildToolDiagnostic,
 	type ChildToolDiagnostic,
@@ -78,12 +79,24 @@ function readRequiredChildTools(): string[] | undefined {
 	return required;
 }
 
+function readMcpDirectChildTools(): string[] | undefined {
+	const encoded = process.env[MCP_DIRECT_CHILD_TOOLS_ENV]?.trim();
+	if (!encoded) return undefined;
+	try {
+		const tools = JSON.parse(encoded) as unknown;
+		if (!Array.isArray(tools) || tools.some((name) => typeof name !== "string" || !name)) return undefined;
+		return tools;
+	} catch {
+		return undefined;
+	}
+}
+
 function refreshChildToolDiagnostic(pi: ExtensionAPI): ChildToolDiagnostic | undefined {
 	const filePath = process.env[CHILD_TOOL_DIAGNOSTIC_PATH_ENV]?.trim();
 	const required = readRequiredChildTools();
 	if (!filePath || !required) return undefined;
 	const available = pi.getAllTools().map((tool) => tool.name);
-	return writeChildToolDiagnostic(filePath, required, available, process.env[SUBAGENT_CHILD_AGENT_ENV]?.trim());
+	return writeChildToolDiagnostic(filePath, required, available, process.env[SUBAGENT_CHILD_AGENT_ENV]?.trim(), readMcpDirectChildTools());
 }
 
 function findSectionEnd(prompt: string, startIndex: number, nextHeaders: string[]): number {

package/src/runs/shared/task-intent.ts

@@ -40,7 +40,7 @@ const REVIEWER_REQUIRED_EDIT_PATTERNS = [
 const NO_EDIT_PROHIBITION_PATTERN = /\b(?:do not|don't|must not)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b((?:(?!\b(?:but|and|then)\b)[^.;,:!?\n–—-])*)/gi;
 
 /** Objects of a no-edit prohibition that mean "the codebase in general" rather than a named scope. */
-const GENERIC_PROHIBITION_OBJECT = /^\s*(?:(?:any|all|the|these|those|your|our|existing|project|source|sources|repo|repository)[\s/,-]*)*(?:files?|code|codebase|sources?|anything|repo(?:sitory)?)?\s*$/i;
+const GENERIC_PROHIBITION_OBJECT = /^\s*(?:(?:any|all|the|these|those|your|our|existing|project|product|source|sources|config|configs|repo|repository)[\s/,-]*)*(?:files?|code|codebase|sources?|anything|repo(?:sitory)?)?\s*$/i;
 
 const SCOPED_NO_EDIT_CONSTRAINT_PATTERNS = [
 	/\bdo not edit files?\s+outside\b/i,

package/src/runs/shared/tool-availability.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 
 export const REQUIRED_CHILD_TOOLS_ENV = "PI_SUBAGENT_REQUIRED_TOOLS";
+export const MCP_DIRECT_CHILD_TOOLS_ENV = "PI_SUBAGENT_MCP_DIRECT_TOOLS";
 export const CHILD_TOOL_DIAGNOSTIC_PATH_ENV = "PI_SUBAGENT_TOOL_DIAGNOSTIC_PATH";
 
 export interface ChildToolDiagnostic {
@@ -9,6 +10,7 @@ export interface ChildToolDiagnostic {
 	required: string[];
 	available: string[];
 	missing: string[];
+	missingMcpDirectTools?: string[];
 }
 
 const PI_CORE_CHILD_TOOLS = new Set(["bash", "edit", "find", "grep", "ls", "read", "write"]);
@@ -18,6 +20,7 @@ export function writeChildToolDiagnostic(
 	required: string[],
 	available: string[],
 	agent?: string,
+	mcpDirectTools?: string[],
 ): ChildToolDiagnostic | undefined {
 	const availableNames = new Set([...available, ...PI_CORE_CHILD_TOOLS]);
 	const missing = required.filter((name) => !availableNames.has(name));
@@ -26,7 +29,16 @@ export function writeChildToolDiagnostic(
 		return undefined;
 	}
 
-	const diagnostic: ChildToolDiagnostic = { agent, required, available, missing };
+	const missingMcpDirectTools = mcpDirectTools?.length
+		? missing.filter((name) => mcpDirectTools.includes(name))
+		: [];
+	const diagnostic: ChildToolDiagnostic = {
+		agent,
+		required,
+		available,
+		missing,
+		...(missingMcpDirectTools.length > 0 ? { missingMcpDirectTools } : {}),
+	};
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
 	fs.writeFileSync(filePath, JSON.stringify(diagnostic), { mode: 0o600 });
 	return diagnostic;
@@ -36,7 +48,7 @@ export function readChildToolDiagnostic(filePath: string | undefined): ChildTool
 	if (!filePath || !fs.existsSync(filePath)) return undefined;
 	const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8")) as Partial<ChildToolDiagnostic>;
 	const stringArray = (value: unknown): value is string[] => Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.length > 0);
-	if (!stringArray(parsed.required) || !stringArray(parsed.available) || !stringArray(parsed.missing) || (parsed.agent !== undefined && typeof parsed.agent !== "string")) {
+	if (!stringArray(parsed.required) || !stringArray(parsed.available) || !stringArray(parsed.missing) || (parsed.agent !== undefined && typeof parsed.agent !== "string") || (parsed.missingMcpDirectTools !== undefined && !stringArray(parsed.missingMcpDirectTools))) {
 		throw new Error(`Malformed child tool diagnostic at '${filePath}'.`);
 	}
 	return {
@@ -44,6 +56,7 @@ export function readChildToolDiagnostic(filePath: string | undefined): ChildTool
 		required: parsed.required,
 		available: parsed.available,
 		missing: parsed.missing,
+		...(parsed.missingMcpDirectTools ? { missingMcpDirectTools: parsed.missingMcpDirectTools } : {}),
 	};
 }
 
@@ -52,6 +65,9 @@ export function formatChildToolDiagnostic(diagnostic: ChildToolDiagnostic): stri
 	return [
 		`${subject} requested unavailable child tools: ${diagnostic.missing.join(", ")}.`,
 		"The `tools` field is a strict allowlist; it does not load extension code.",
+		...(diagnostic.missingMcpDirectTools?.length
+			? [`Resolved MCP direct tools missing from the child registry: ${diagnostic.missingMcpDirectTools.join(", ")}. This indicates a host/pi-mcp-adapter registration problem, not a tool-call failure.`]
+			: []),
 		"For extension tools, add the provider path to `subagentOnlyExtensions` (child-only), `extensions`, or as a path-like entry in `tools`, while keeping each registered tool name in `tools`.",
 		"For MCP tools, verify the MCP adapter configuration and selected tool names. For builtin tools, verify the name against the installed Pi version.",
 	].join("\n");

package/src/shared/launch-contract.ts

@@ -0,0 +1,123 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import type { AgentConfig } from "../agents/agents.ts";
+
+export const AGENT_DEFINITION_PROJECTION_VERSION = 1 as const;
+export const LAUNCH_BINDING_PROJECTION_VERSION = 1 as const;
+
+function stableJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+	if (value && typeof value === "object") {
+		return `{${Object.entries(value as Record<string, unknown>)
+			.filter(([, entry]) => entry !== undefined)
+			.sort(([a], [b]) => a.localeCompare(b))
+			.map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
+			.join(",")}}`;
+	}
+	return JSON.stringify(value);
+}
+
+function sha256(value: unknown): string {
+	return createHash("sha256").update(stableJson(value)).digest("hex");
+}
+
+function fileDigest(filePath: string): string | undefined {
+	try {
+		return createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+	} catch {
+		return undefined;
+	}
+}
+
+/** Public-safe, deterministic evidence for the parsed launch-affecting agent definition. */
+export function projectAgentDefinition(agent: AgentConfig): Record<string, unknown> {
+	return {
+		version: AGENT_DEFINITION_PROJECTION_VERSION,
+		name: agent.name,
+		localName: agent.localName,
+		packageName: agent.packageName,
+		filePath: agent.filePath,
+		fileContentDigest: fileDigest(agent.filePath),
+		systemPrompt: agent.systemPrompt,
+		systemPromptMode: agent.systemPromptMode,
+		inheritProjectContext: agent.inheritProjectContext,
+		inheritSkills: agent.inheritSkills,
+		model: agent.model,
+		fallbackModels: agent.fallbackModels,
+		thinking: agent.thinking,
+		tools: agent.tools,
+		mcpDirectTools: agent.mcpDirectTools,
+		extensions: agent.extensions,
+		subagentOnlyExtensions: agent.subagentOnlyExtensions,
+		skills: agent.skills,
+		skillPath: agent.skillPath,
+		output: agent.output,
+		defaultReads: agent.defaultReads,
+		defaultProgress: agent.defaultProgress,
+		defaultContext: agent.defaultContext,
+		defaultAsync: agent.defaultAsync,
+		defaultTimeoutMs: agent.defaultTimeoutMs,
+		defaultTurnBudget: agent.defaultTurnBudget,
+		defaultAcceptance: agent.defaultAcceptance,
+		acceptanceRole: agent.acceptanceRole,
+		interactive: agent.interactive,
+		maxSubagentDepth: agent.maxSubagentDepth,
+		completionGuard: agent.completionGuard,
+		toolBudget: agent.toolBudget,
+		memory: agent.memory,
+	};
+}
+
+export function agentDefinitionDigest(agent: AgentConfig): string {
+	return sha256(projectAgentDefinition(agent));
+}
+
+export interface LaunchBindingInput {
+	definitionDigest: string;
+	/** Caller task; runtime acceptance/output task annotations are explicitly outside the preflight-known subset. */
+	task?: string;
+	model?: string;
+	modelCandidates?: string[];
+	thinking?: string;
+	systemPrompt?: string | null;
+	systemPromptMode?: AgentConfig["systemPromptMode"];
+	inheritProjectContext: boolean;
+	inheritSkills: boolean;
+	skills?: string[];
+	tools?: string[];
+	extensions?: string[];
+	subagentOnlyExtensions?: string[];
+	mcpDirectTools?: string[];
+	outputPath?: string;
+	outputMode?: string;
+	structuredOutputSchema?: unknown;
+}
+
+/** Canonical projection of the resolved inputs handed to the child. */
+export function projectLaunchBinding(input: LaunchBindingInput): Record<string, unknown> {
+	return {
+		version: LAUNCH_BINDING_PROJECTION_VERSION,
+		definitionDigest: input.definitionDigest,
+		taskDigest: input.task === undefined ? undefined : sha256(input.task),
+		// The ordered candidate set already contains each attempted model; keeping only
+		// this set makes retries correlate to the same preflight binding.
+		modelCandidates: input.modelCandidates,
+		thinking: input.thinking,
+		systemPromptDigest: input.systemPrompt === undefined || input.systemPrompt === null ? undefined : sha256(input.systemPrompt),
+		systemPromptMode: input.systemPromptMode,
+		inheritProjectContext: input.inheritProjectContext,
+		inheritSkills: input.inheritSkills,
+		skills: input.skills,
+		tools: input.tools,
+		extensions: input.extensions,
+		subagentOnlyExtensions: input.subagentOnlyExtensions,
+		mcpDirectTools: input.mcpDirectTools,
+		outputPath: input.outputPath,
+		outputMode: input.outputMode,
+		structuredOutputSchema: input.structuredOutputSchema,
+	};
+}
+
+export function launchBindingDigest(input: LaunchBindingInput): string {
+	return sha256(projectLaunchBinding(input));
+}