pi-subagents 0.36.0 → 0.37.0

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

@@ -0,0 +1,177 @@
+import { Buffer } from "node:buffer";
+
+export const SUBAGENT_CAPABILITY_CEILING_VERSION = 1 as const;
+export const SUBAGENT_CAPABILITY_CEILING_REGISTRY_KEY = "pi-subagents.capability-ceiling.v1";
+export const SUBAGENT_CAPABILITY_CEILING_ENV = "PI_SUBAGENT_CAPABILITY_CEILING_V1";
+
+export type SubagentCapabilityCeiling =
+	| { allowedTools: readonly string[]; denyExtensions?: boolean }
+	| { allowedTools?: readonly string[]; denyExtensions: boolean };
+
+export interface ResolvedSubagentCapabilityCeiling {
+	version: typeof SUBAGENT_CAPABILITY_CEILING_VERSION;
+	allowedTools?: string[];
+	denyExtensions: boolean;
+	sources: string[];
+}
+
+export interface SubagentCapabilityAudit {
+	ceiling: ResolvedSubagentCapabilityCeiling;
+	requestedTools?: string[];
+	effectiveTools: string[];
+	removedTools: string[];
+	internalTools: string[];
+	extensionsDenied: boolean;
+	removedExtensionCount: number;
+	requestedMcpToolCount: number;
+	effectiveMcpTools: string[];
+}
+
+export interface RegisterSubagentCapabilityCeilingOptions {
+	sessionId: string;
+	source: string;
+	ceiling: SubagentCapabilityCeiling;
+}
+
+export interface SubagentCapabilityCeilingHandle {
+	update(ceiling: SubagentCapabilityCeiling): void;
+	dispose(): void;
+}
+
+type Registration = { source: string; ceiling: ResolvedSubagentCapabilityCeiling };
+type Registry = Map<string, Map<symbol, Registration>>;
+
+function registry(): Registry {
+	const key = Symbol.for(SUBAGENT_CAPABILITY_CEILING_REGISTRY_KEY);
+	const store = globalThis as typeof globalThis & { [key: symbol]: unknown };
+	const existing = store[key];
+	if (existing instanceof Map) return existing as Registry;
+	const created: Registry = new Map();
+	store[key] = created;
+	return created;
+}
+
+function validateText(value: unknown, field: string): string {
+	if (typeof value !== "string" || !value.trim() || /[\u0000-\u001f\u007f]/u.test(value) || Buffer.byteLength(value.trim(), "utf8") > 256) {
+		throw new Error(`Invalid capability ceiling ${field}; expected a non-empty string without control characters (max 256 UTF-8 bytes).`);
+	}
+	return value.trim();
+}
+
+function normalizeCeiling(ceiling: SubagentCapabilityCeiling): ResolvedSubagentCapabilityCeiling {
+	if (!ceiling || typeof ceiling !== "object" || Array.isArray(ceiling)) throw new Error("Invalid capability ceiling; expected an object.");
+	const hasAllowedTools = Object.hasOwn(ceiling, "allowedTools");
+	const hasDenyExtensions = Object.hasOwn(ceiling, "denyExtensions");
+	if (!hasAllowedTools && !hasDenyExtensions) throw new Error("Invalid capability ceiling; expected allowedTools or denyExtensions.");
+	if (hasDenyExtensions && typeof ceiling.denyExtensions !== "boolean") throw new Error("Invalid capability ceiling denyExtensions; expected a boolean.");
+	let allowedTools: string[] | undefined;
+	if (hasAllowedTools) {
+		if (!Array.isArray(ceiling.allowedTools)) throw new Error("Invalid capability ceiling allowedTools; expected an array.");
+		if (ceiling.allowedTools.length > 256) throw new Error("Invalid capability ceiling allowedTools; expected at most 256 names.");
+		allowedTools = [...new Set(ceiling.allowedTools.map((tool) => {
+			const name = validateText(tool, "allowedTools entry");
+			if (!/^[A-Za-z0-9_.:-]+$/u.test(name)) throw new Error(`Invalid capability ceiling allowedTools entry '${name}'.`);
+			if (Buffer.byteLength(name, "utf8") > 128) throw new Error(`Invalid capability ceiling allowedTools entry '${name}'; max 128 UTF-8 bytes.`);
+			return name;
+		}))].sort();
+	}
+	return {
+		version: SUBAGENT_CAPABILITY_CEILING_VERSION,
+		...(allowedTools ? { allowedTools } : {}),
+		denyExtensions: ceiling.denyExtensions === true,
+		sources: [],
+	};
+}
+
+export function parseSubagentCapabilityCeiling(value: unknown, field = "capability ceiling"): ResolvedSubagentCapabilityCeiling {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Invalid ${field}; expected an object.`);
+	const record = value as Record<string, unknown>;
+	if (record.version !== SUBAGENT_CAPABILITY_CEILING_VERSION) throw new Error(`Invalid ${field} version.`);
+	const normalized = normalizeCeiling(record as SubagentCapabilityCeiling);
+	const sources = record.sources;
+	if (!Array.isArray(sources) || sources.some((source) => typeof source !== "string")) throw new Error(`Invalid ${field} sources; expected an array of strings.`);
+	normalized.sources = [...new Set(sources.map((source) => validateText(source, `${field} source`)))].sort();
+	return normalized;
+}
+
+export function registerSubagentCapabilityCeiling(options: RegisterSubagentCapabilityCeilingOptions): SubagentCapabilityCeilingHandle {
+	const sessionId = validateText(options.sessionId, "sessionId");
+	const source = validateText(options.source, "source");
+	let normalized = normalizeCeiling(options.ceiling);
+	const token = Symbol(source);
+	const store = registry();
+	let session = store.get(sessionId);
+	if (!session) {
+		session = new Map();
+		store.set(sessionId, session);
+	}
+	const setRegistration = () => {
+		normalized = normalizeCeiling(normalized);
+		normalized.sources = [source];
+		session!.set(token, { source, ceiling: normalized });
+	};
+	setRegistration();
+	let disposed = false;
+	return {
+		update(ceiling) {
+			if (disposed) throw new Error("Cannot update a disposed capability ceiling handle.");
+			normalized = normalizeCeiling(ceiling);
+			normalized.sources = [source];
+			session!.set(token, { source, ceiling: normalized });
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			session!.delete(token);
+			if (session!.size === 0) store.delete(sessionId);
+		},
+	};
+}
+
+export function intersectSubagentCapabilityCeilings(...ceilings: Array<ResolvedSubagentCapabilityCeiling | undefined>): ResolvedSubagentCapabilityCeiling | undefined {
+	const active = ceilings.filter((ceiling): ceiling is ResolvedSubagentCapabilityCeiling => ceiling !== undefined);
+	if (active.length === 0) return undefined;
+	const definedLists = active.filter((ceiling) => ceiling.allowedTools !== undefined).map((ceiling) => new Set(ceiling.allowedTools));
+	let allowedTools: string[] | undefined;
+	if (definedLists.length > 0) {
+		allowedTools = [...definedLists[0]!].filter((tool) => definedLists.every((list) => list.has(tool))).sort();
+	}
+	return {
+		version: SUBAGENT_CAPABILITY_CEILING_VERSION,
+		...(allowedTools ? { allowedTools } : {}),
+		denyExtensions: active.some((ceiling) => ceiling.denyExtensions),
+		sources: [...new Set(active.flatMap((ceiling) => ceiling.sources))].sort(),
+	};
+}
+
+export function resolveSubagentCapabilityCeiling(sessionId: string | undefined, inherited?: ResolvedSubagentCapabilityCeiling): ResolvedSubagentCapabilityCeiling | undefined {
+	const active: ResolvedSubagentCapabilityCeiling[] = [];
+	if (sessionId) {
+		const registrations = registry().get(sessionId);
+		if (registrations) active.push(...Array.from(registrations.values(), ({ ceiling }) => ceiling));
+	}
+	return intersectSubagentCapabilityCeilings(inherited, ...active);
+}
+
+export function resolveCurrentSubagentCapabilityCeiling(sessionId: string | undefined): ResolvedSubagentCapabilityCeiling | undefined {
+	return resolveSubagentCapabilityCeiling(sessionId, decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV]));
+}
+
+export function encodeSubagentCapabilityCeiling(ceiling: ResolvedSubagentCapabilityCeiling | undefined): string | undefined {
+	if (!ceiling) return undefined;
+	return Buffer.from(JSON.stringify(ceiling), "utf8").toString("base64url");
+}
+
+export function decodeSubagentCapabilityCeiling(value: string | undefined): ResolvedSubagentCapabilityCeiling | undefined {
+	if (value === undefined || value === "") return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+	} catch (error) {
+		throw new Error(`Invalid inherited capability ceiling: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || (parsed as { version?: unknown }).version !== SUBAGENT_CAPABILITY_CEILING_VERSION) {
+		throw new Error("Invalid inherited capability ceiling version.");
+	}
+	return parseSubagentCapabilityCeiling(parsed, "inherited capability ceiling");
+}

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", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "waitToolEnabled",
-	"structuredOutput", "structuredOutputSchema", "tools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "completionGuard", "systemPrompt",
+	"structuredOutput", "structuredOutputSchema", "tools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "capabilityCeiling", "completionGuard", "systemPrompt",
 	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId",
 ]);
 const DYNAMIC_COLLECT_KEYS = new Set(["as", "outputSchema"]);

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

@@ -69,14 +69,16 @@ interface MetadataCache {
 	servers: Record<string, ServerCacheEntry>;
 }
 
-export function resolveMcpDirectToolNames(mcpDirectTools: string[] | undefined, cwd = process.cwd()): string[] {
+export interface ResolvedMcpDirectToolSelection { name: string; selector: string }
+
+export function resolveMcpDirectToolSelections(mcpDirectTools: string[] | undefined, cwd = process.cwd()): ResolvedMcpDirectToolSelection[] {
 	if (!mcpDirectTools?.length) return [];
 
 	try {
 		const config = loadMcpConfig(cwd);
 		const cache = loadMetadataCache();
 		if (!cache) return [];
-		return resolveDirectToolNames(config, cache, getToolPrefix(config.settings?.toolPrefix), mcpDirectTools);
+		return resolveDirectToolSelections(config, cache, getToolPrefix(config.settings?.toolPrefix), mcpDirectTools);
 	} catch {
 		return [];
 	}
@@ -195,8 +197,8 @@ function extractServers(config: unknown, kind: ImportKind): Record<string, Serve
 	return servers && typeof servers === "object" && !Array.isArray(servers) ? servers as Record<string, ServerEntry> : {};
 }
 
-function resolveDirectToolNames(config: McpConfig, cache: MetadataCache, prefix: ToolPrefix, envOverride: string[]): string[] {
-	const names: string[] = [];
+function resolveDirectToolSelections(config: McpConfig, cache: MetadataCache, prefix: ToolPrefix, envOverride: string[]): ResolvedMcpDirectToolSelection[] {
+	const names: ResolvedMcpDirectToolSelection[] = [];
 	const seenNames = new Set<string>();
 	const { servers: selectedServers, tools: selectedTools } = parseSelections(envOverride);
 
@@ -216,7 +218,7 @@ function resolveDirectToolNames(config: McpConfig, cache: MetadataCache, prefix:
 			const prefixedName = formatToolName(tool.name, serverName, prefix);
 			if (BUILTIN_TOOL_NAMES.has(prefixedName) || seenNames.has(prefixedName)) continue;
 			seenNames.add(prefixedName);
-			names.push(prefixedName);
+			names.push({ name: prefixedName, selector: `${serverName}/${tool.name}` });
 		}
 
 		if (definition.exposeResources === false) continue;
@@ -228,13 +230,17 @@ function resolveDirectToolNames(config: McpConfig, cache: MetadataCache, prefix:
 			const prefixedName = formatToolName(baseName, serverName, prefix);
 			if (BUILTIN_TOOL_NAMES.has(prefixedName) || seenNames.has(prefixedName)) continue;
 			seenNames.add(prefixedName);
-			names.push(prefixedName);
+			names.push({ name: prefixedName, selector: `${serverName}/${baseName}` });
 		}
 	}
 
 	return names;
 }
 
+export function resolveMcpDirectToolNames(mcpDirectTools: string[] | undefined, cwd = process.cwd()): string[] {
+	return resolveMcpDirectToolSelections(mcpDirectTools, cwd).map((selection) => selection.name);
+}
+
 function parseSelections(selections: string[]): { servers: Set<string>; tools: Map<string, Set<string>> } {
 	const servers = new Set<string>();
 	const tools = new Map<string, Set<string>>();

package/src/runs/shared/nested-events.ts

@@ -27,6 +27,7 @@ import {
 	SUBAGENT_PARENT_RUN_ID_ENV,
 } from "./pi-args.ts";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { sanitizeProcessTerminal } from "../background/process-terminal.ts";
 
 export const NESTED_EVENTS_DIR = path.join(TEMP_ROOT_DIR, "nested-subagent-events");
 const ROUTE_FILE = "route.json";
@@ -873,6 +874,9 @@ export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: stri
 		...(status.pid ? { pid: status.pid } : {}),
 		...(status.sessionId ? { sessionId: status.sessionId } : {}),
 		mode: status.mode ?? fallback.mode,
+		...(status.processTerminal ? { processTerminal: sanitizeProcessTerminal(status.processTerminal, { runId: status.runId || fallback.id, runnerProcessInstanceId: status.processTerminal.runnerProcessInstanceId }, `${asyncDir}/status.json`) } : {}),
+		...(status.capabilityCeiling ? { capabilityCeiling: status.capabilityCeiling } : {}),
+		...(status.capabilityAudit ? { capabilityAudit: status.capabilityAudit } : {}),
 		state: status.state,
 		...(status.currentStep !== undefined ? { currentStep: status.currentStep } : {}),
 		...(status.chainStepCount !== undefined ? { chainStepCount: status.chainStepCount } : {}),
@@ -896,7 +900,7 @@ export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: stri
 		...(status.endedAt !== undefined ? { endedAt: status.endedAt } : {}),
 		lastUpdate: status.lastUpdate ?? fallback.ts,
 		...(status.sessionFile ? { sessionFile: status.sessionFile } : {}),
-		...(status.steps?.length ? { steps: status.steps.map((step) => ({
+		...(status.steps?.length ? { steps: status.steps.map((step, index) => ({
 			agent: step.agent,
 			status: step.status,
 			...(step.sessionFile ? { sessionFile: step.sessionFile } : {}),
@@ -915,6 +919,9 @@ export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: stri
 			...(step.turnBudget ? { turnBudget: step.turnBudget } : {}),
 			...(step.turnBudgetExceeded !== undefined ? { turnBudgetExceeded: step.turnBudgetExceeded } : {}),
 			...(step.wrapUpRequested !== undefined ? { wrapUpRequested: step.wrapUpRequested } : {}),
+			...(step.processTerminal ? { processTerminal: sanitizeProcessTerminal(step.processTerminal, { runId: status.runId || fallback.id, runnerProcessInstanceId: step.processTerminal.runnerProcessInstanceId }, `${asyncDir}/status.json step ${index}`) } : {}),
+			...(step.capabilityCeiling ? { capabilityCeiling: step.capabilityCeiling } : {}),
+			...(step.capabilityAudit ? { capabilityAudit: step.capabilityAudit } : {}),
 		})).slice(0, MAX_STEPS) } : {}),
 	};
 }

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

@@ -43,11 +43,16 @@ export interface RunnerSubagentStep {
 	};
 	structuredOutputSchema?: import("../../shared/types.ts").JsonSchemaObject;
 	agentContract?: import("../../shared/types.ts").AgentContract;
+	definitionDigest?: string;
+	launchBindingTask?: string;
+	launchContractDigest?: string;
 	effectiveAcceptance?: import("../../shared/types.ts").ResolvedAcceptanceConfig;
 	acceptanceInput?: import("../../shared/types.ts").AcceptanceInput;
 	acceptanceRole?: import("../../shared/types.ts").AcceptanceRole;
 	gateOn?: import("../../shared/types.ts").ChainGateLayer;
 	toolBudget?: import("../../shared/types.ts").ResolvedToolBudget;
+	capabilityCeiling?: import("./capability-ceiling.ts").ResolvedSubagentCapabilityCeiling;
+	capabilityAudit?: import("./capability-ceiling.ts").SubagentCapabilityAudit;
 }
 
 export interface ParallelStepGroup {

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);
 				},
 			};
 		}