pi-subagents 0.36.0 → 0.37.1

package/src/runs/shared/acceptance.ts

@@ -29,10 +29,9 @@ const LEVEL_RANK: Record<Exclude<AcceptanceLevel, "auto">, number> = {
 	attested: 1,
 	checked: 2,
 	verified: 3,
-	reviewed: 4,
 };
 
-const VALID_LEVELS = new Set<AcceptanceLevel>(["auto", "none", "attested", "checked", "verified", "reviewed"]);
+const VALID_LEVELS = new Set<AcceptanceLevel>(["auto", "none", "attested", "checked", "verified"]);
 const VALID_EVIDENCE = new Set<AcceptanceEvidenceKind>([
 	"changed-files",
 	"tests-added",
@@ -48,7 +47,7 @@ const ACCEPTANCE_CONFIG_KEYS = new Set(["level", "criteria", "evidence", "verify
 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"]);
-const EXPLICIT_REVIEWED_UNAVAILABLE = "cannot be requested explicitly because this run cannot supply an independent reviewer result; use checked/verified and orchestrate the reviewer separately, or omit acceptance for read-only review tasks.";
+const EXPLICIT_REVIEWED_UNAVAILABLE = "is an achieved status, not a requestable acceptance level. For a read-only reviewer call, omit acceptance. To require independent review of a writer result, use acceptance.review.required and orchestrate the reviewer separately.";
 
 function normalizeLevel(level: AcceptanceLevel | undefined): Exclude<AcceptanceLevel, "auto"> | "auto" {
 	return level ?? "auto";
@@ -67,7 +66,6 @@ function requiredEvidenceForLevel(level: Exclude<AcceptanceLevel, "auto">): Acce
 		case "checked":
 			return ["changed-files", "tests-added", "commands-run", "residual-risks", "no-staged-files"];
 		case "verified":
-		case "reviewed":
 			return ["changed-files", "tests-added", "commands-run", "validation-output", "residual-risks", "no-staged-files"];
 	}
 }
@@ -110,10 +108,10 @@ function inferLevel(input: {
 		reasons.push(input.async ? "async write-capable or risky run" : "risky write-capable run");
 		if (input.dynamic || input.dynamicGroup) reasons.push("dynamic fanout context");
 		return {
-			level: "reviewed",
+			level: "checked",
 			reasons,
 			criteria: ["Implement the requested change without widening scope", "Return evidence sufficient for an independent acceptance review"],
-			evidence: requiredEvidenceForLevel("reviewed"),
+			evidence: requiredEvidenceForLevel("checked"),
 			review: { agent: "reviewer", required: true },
 		};
 	}
@@ -160,9 +158,9 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
 	if (input === undefined) return errors;
 	if (input === false) return errors;
 	if (typeof input === "string") {
-		if (!VALID_LEVELS.has(input as AcceptanceLevel)) errors.push(`${pathLabel} has invalid level '${input}'.`);
+		if (input === "reviewed") errors.push(`${pathLabel} ${EXPLICIT_REVIEWED_UNAVAILABLE}`);
+		else if (!VALID_LEVELS.has(input as AcceptanceLevel)) errors.push(`${pathLabel} has invalid level '${input}'.`);
 		else if (input === "none") errors.push(`${pathLabel} level "none" requires a reason; use { level: "none", reason: "..." }.`);
-		else if (input === "reviewed") errors.push(`${pathLabel} ${EXPLICIT_REVIEWED_UNAVAILABLE}`);
 		return errors;
 	}
 	if (!input || typeof input !== "object" || Array.isArray(input)) {
@@ -173,13 +171,14 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
 	for (const key of Object.keys(value)) {
 		if (!ACCEPTANCE_CONFIG_KEYS.has(key)) errors.push(`${pathLabel}.${key} is not supported.`);
 	}
-	if (value.level !== undefined && (typeof value.level !== "string" || !VALID_LEVELS.has(value.level as AcceptanceLevel))) {
-		errors.push(`${pathLabel}.level must be one of auto, none, attested, checked, verified, reviewed.`);
+	if (value.level === "reviewed") {
+		errors.push(`${pathLabel}.level ${EXPLICIT_REVIEWED_UNAVAILABLE}`);
+	} 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.level === "none" && (typeof value.reason !== "string" || !value.reason.trim())) {
 		errors.push(`${pathLabel}.reason is required when level is none.`);
 	}
-	if (value.level === "reviewed") errors.push(`${pathLabel}.level ${EXPLICIT_REVIEWED_UNAVAILABLE}`);
 	if (value.reason !== undefined && typeof value.reason !== "string") errors.push(`${pathLabel}.reason must be a string.`);
 	if (value.criteria !== undefined && !Array.isArray(value.criteria)) errors.push(`${pathLabel}.criteria must be an array.`);
 	if (Array.isArray(value.criteria)) {
@@ -362,10 +361,7 @@ export function resolveEffectiveAcceptance(input: {
 		(explicit.criteria?.length ? explicit.criteria : inferred.criteria) as Array<string | { id?: string; must?: string; evidence?: AcceptanceEvidenceKind[]; severity?: "required" | "recommended" }>,
 		evidence,
 	);
-	let review = explicit.review !== undefined ? explicit.review : inferred.review;
-	if (level === "reviewed" && input.explicit !== undefined && explicitLevel !== "reviewed" && explicit.review === undefined && review && review !== false) {
-		review = { ...review, required: false };
-	}
+	const review = explicit.review !== undefined ? explicit.review : inferred.review;
 	return {
 		level,
 		explicit: input.explicit !== undefined,
@@ -1061,8 +1057,10 @@ export async function evaluateAcceptance(input: {
 	reportOptional?: boolean;
 }): Promise<AcceptanceLedger> {
 	const acceptance = input.acceptance;
+	const initialStatus = acceptance.level === "none" ? "not-required" : "claimed";
 	const ledger: AcceptanceLedger = {
-		status: acceptance.level === "none" ? "not-required" : "claimed",
+		status: initialStatus,
+		evidenceStatus: initialStatus,
 		explicit: acceptance.explicit,
 		effectiveAcceptance: acceptance,
 		inferredReason: acceptance.inferredReason,
@@ -1084,11 +1082,13 @@ export async function evaluateAcceptance(input: {
 	if (parsed.report) {
 		ledger.childReport = parsed.report;
 		ledger.status = "attested";
+		ledger.evidenceStatus = "attested";
 	} else if (!input.reportOptional || needsReport || parsed.error !== ACCEPTANCE_REPORT_NOT_FOUND) {
 		ledger.childReportParseError = parsed.error;
 		ledger.runtimeChecks.push({ id: "attestation", status: "failed", message: parsed.error ?? "Structured acceptance report missing." });
 		if (!input.reportOptional) {
 			ledger.status = "rejected";
+			ledger.evidenceStatus = "rejected";
 			return ledger;
 		}
 	} else {
@@ -1103,6 +1103,7 @@ export async function evaluateAcceptance(input: {
 		];
 		if (!ledger.runtimeChecks.some((check) => check.status === "failed")) {
 			ledger.status = "checked";
+			ledger.evidenceStatus = "checked";
 		}
 	}
 
@@ -1110,6 +1111,7 @@ export async function evaluateAcceptance(input: {
 		if (acceptance.level === "verified" && acceptance.verify.length === 0) {
 			ledger.runtimeChecks.push({ id: "verification-config", status: "failed", message: "verified acceptance requires runtime verify commands." });
 			ledger.status = "rejected";
+			ledger.evidenceStatus = "rejected";
 			return ledger;
 		}
 		ledger.verifyRuns = [];
@@ -1119,34 +1121,42 @@ export async function evaluateAcceptance(input: {
 		}
 		if (ledger.verifyRuns.some((run) => run.status === "failed" || run.status === "timed-out")) {
 			ledger.status = "rejected";
+			ledger.evidenceStatus = "rejected";
 			return ledger;
 		}
-		if (!ledger.runtimeChecks.some((check) => check.status === "failed")) ledger.status = "verified";
+		if (!ledger.runtimeChecks.some((check) => check.status === "failed")) {
+			ledger.status = "verified";
+			ledger.evidenceStatus = "verified";
+		}
 	}
 
 	if (ledger.runtimeChecks.some((check) => check.status === "failed")) {
 		ledger.status = "rejected";
+		ledger.evidenceStatus = "rejected";
 		return ledger;
 	}
-	if (ledger.status === "claimed" && acceptance.level !== "reviewed") {
+	if (ledger.status === "claimed") {
 		ledger.status = acceptance.level === "verified" ? "verified" : acceptance.level;
+		ledger.evidenceStatus = ledger.status;
 	}
 
-	if (acceptance.level === "reviewed") {
-		if (input.reviewResult) {
+	if (acceptance.review && acceptance.review !== false) {
+		if (input.reviewResult?.status === "reviewed") {
 			ledger.reviewResult = input.reviewResult;
-			ledger.status = input.reviewResult.status === "no-blockers" ? "reviewed" : "rejected";
-		} else {
-			const optionalReview = acceptance.review && acceptance.review !== false && acceptance.review.required === false;
-			ledger.reviewResult = {
-				status: "needs-parent-decision",
+			ledger.status = "reviewed";
+		} else if (input.reviewResult?.status === "blockers") {
+			ledger.reviewResult = input.reviewResult;
+			ledger.status = "rejected";
+		} else if (acceptance.review.required !== false) {
+			ledger.reviewResult = input.reviewResult ?? {
+				status: "review-required",
 				findings: [{
-					severity: acceptance.explicit && !optionalReview ? "blocker" : "non-blocking",
-					issue: "Reviewed acceptance requires an independent reviewer result.",
+					severity: "non-blocking",
+					issue: "Independent review has not been supplied.",
 					rationale: "The run cannot be marked reviewed from child evidence alone.",
 				}],
 			};
-			if (acceptance.review === false || (acceptance.explicit && !optionalReview)) ledger.status = "rejected";
+			ledger.status = "review-required";
 		}
 	}
 
@@ -1154,8 +1164,10 @@ export async function evaluateAcceptance(input: {
 }
 
 export function buildSkippedAcceptanceLedger(acceptance: ResolvedAcceptanceConfig, input: { id: string; message: string }): AcceptanceLedger {
+	const status = acceptance.level === "none" ? "not-required" : "rejected";
 	return {
-		status: acceptance.level === "none" ? "not-required" : "rejected",
+		status,
+		evidenceStatus: status,
 		explicit: acceptance.explicit,
 		effectiveAcceptance: acceptance,
 		inferredReason: acceptance.inferredReason,
@@ -1173,7 +1185,6 @@ export function acceptanceFailureMessage(ledger: AcceptanceLedger): string | und
 	if (failedCheck) return `Acceptance rejected: ${failedCheck.message}`;
 	const failedVerify = ledger.verifyRuns.find((run) => run.status === "failed" || run.status === "timed-out");
 	if (failedVerify) return `Acceptance verification '${failedVerify.id}' ${failedVerify.status}.`;
-	if (ledger.reviewResult?.status === "needs-parent-decision") return "Acceptance review required but no automatic reviewer result is available.";
 	if (ledger.reviewResult?.status === "blockers") return "Acceptance review found blockers.";
 	return "Acceptance rejected.";
 }

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

@@ -27,6 +27,7 @@ type ImportKind = keyof typeof IMPORT_PATHS;
 interface ServerEntry {
 	command?: string;
 	args?: string[];
+	socket?: string;
 	env?: Record<string, string>;
 	cwd?: string;
 	url?: string;
@@ -35,6 +36,7 @@ interface ServerEntry {
 	bearerToken?: string;
 	bearerTokenEnv?: string;
 	exposeResources?: boolean;
+	includeTools?: string[];
 	excludeTools?: string[];
 	directTools?: boolean | string[];
 }
@@ -69,14 +71,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 +199,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 +220,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 +232,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>>();
@@ -265,14 +273,16 @@ export function computeMcpServerHash(definition: ServerEntry): string {
 	const identity: Record<string, unknown> = {
 		command: definition.command,
 		args: definition.args,
+		socket: resolveConfigPath(definition.socket),
 		env: interpolateEnvRecord(definition.env),
 		cwd: resolveConfigPath(definition.cwd),
-		url: definition.url,
+		url: resolveServerUrl(definition),
 		headers: interpolateEnvRecord(definition.headers),
 		auth: definition.auth,
 		bearerToken: resolveBearerToken(definition),
 		bearerTokenEnv: definition.bearerTokenEnv,
 		exposeResources: definition.exposeResources,
+		includeTools: definition.includeTools,
 		excludeTools: definition.excludeTools,
 	};
 	return createHash("sha256").update(stableStringify(identity)).digest("hex");
@@ -327,22 +337,51 @@ function resourceNameToToolName(name: string): string {
 }
 
 function interpolateEnvRecord(values: Record<string, string> | undefined): Record<string, string> | undefined {
-	if (!values || typeof values !== "object" || Array.isArray(values)) return undefined;
-	const resolved: Record<string, string> = {};
-	for (const [key, value] of Object.entries(values)) {
-		if (typeof value === "string") resolved[key] = interpolateEnvVars(value);
-	}
-	return resolved;
+	if (!values) return undefined;
+	return Object.fromEntries(Object.entries(values).map(([key, value]) => [key, interpolateSecretExpression(value)]));
 }
 
 function interpolateEnvVars(value: string): string {
 	return value
 		.replace(/\$\{(\w+)\}/g, (_, name: string) => process.env[name] ?? "")
-		.replace(/\$env:(\w+)/g, (_, name: string) => process.env[name] ?? "");
+		.replace(/\$env:(\w+)/g, (_, name: string) => process.env[name] ?? "")
+		.replace(/\{env:(\w+)\}/g, (_, name: string) => process.env[name] ?? "");
+}
+
+function interpolateSecretExpression(value: string): string {
+	if (value.startsWith("!!")) return interpolateEnvVars(value.slice(1));
+	return value.startsWith("!") ? value : interpolateEnvVars(value);
+}
+
+function getMissingEnvVars(value: string): string[] {
+	const missing = new Set<string>();
+	for (const match of value.matchAll(/\$\{(\w+)\}|\$env:(\w+)|\{env:(\w+)\}/g)) {
+		const name = match[1] ?? match[2] ?? match[3];
+		if (name && process.env[name] === undefined) missing.add(name);
+	}
+	return [...missing];
+}
+
+function resolveServerUrl(definition: Pick<ServerEntry, "url">): string | undefined {
+	if (definition.url == null) return undefined;
+	if (typeof definition.url !== "string") throw new Error("MCP server URL must be a string");
+
+	const missing = getMissingEnvVars(definition.url);
+	if (missing.length > 0) {
+		throw new Error(`Missing environment variable${missing.length === 1 ? "" : "s"} in MCP server URL: ${missing.join(", ")}`);
+	}
+
+	const resolved = interpolateEnvVars(definition.url);
+	try {
+		new URL(resolved);
+	} catch (error) {
+		throw new Error(`Invalid MCP server URL after environment interpolation: ${resolved}`, { cause: error });
+	}
+	return resolved;
 }
 
 function resolveConfigPath(value: string | undefined): string | undefined {
-	if (typeof value !== "string") return undefined;
+	if (value === undefined) return undefined;
 	const resolved = interpolateEnvVars(value);
 	if (resolved === "~") return os.homedir();
 	if (resolved.startsWith("~/") || resolved.startsWith("~\\")) return path.join(os.homedir(), resolved.slice(2));
@@ -350,8 +389,8 @@ function resolveConfigPath(value: string | undefined): string | undefined {
 }
 
 function resolveBearerToken(definition: Pick<ServerEntry, "bearerToken" | "bearerTokenEnv">): string | undefined {
-	if (typeof definition.bearerToken === "string") return interpolateEnvVars(definition.bearerToken);
-	return typeof definition.bearerTokenEnv === "string" ? process.env[definition.bearerTokenEnv] : undefined;
+	if (definition.bearerToken !== undefined) return interpolateSecretExpression(definition.bearerToken);
+	return definition.bearerTokenEnv ? process.env[definition.bearerTokenEnv] : undefined;
 }
 
 function stableStringify(value: unknown): string {

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

@@ -30,6 +30,14 @@ export interface ParentModel {
 	id: string;
 }
 
+export function normalizeParentModel(model: unknown): ParentModel | undefined {
+	if (!model || typeof model !== "object") return undefined;
+	const candidate = model as { provider?: unknown; id?: unknown };
+	if (typeof candidate.provider !== "string" || typeof candidate.id !== "string") return undefined;
+	if (!candidate.provider || !candidate.id) return undefined;
+	return { provider: candidate.provider, id: candidate.id };
+}
+
 /**
  * Normalize a model id or provider segment for fuzzy comparison: case-fold,
  * treat dots/underscores as dashes (so `4.5` matches `4-5`), and collapse

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 {