pi-subagents 0.58.0 → 0.60.0

package/src/runs/shared/mcp-config-sources.ts

@@ -39,6 +39,44 @@ export interface McpServerDefinition {
 	literalEnv?: boolean;
 }
 
+export function isMcpServerDefinition(value: unknown): value is McpServerDefinition {
+	if (!isRecord(value)) return false;
+	for (const field of ["command", "socket", "cwd", "url", "bearerToken", "bearerTokenEnv", "protocolVersion", "httpTransport", "pluginDataDir"] as const) {
+		if (value[field] !== undefined && typeof value[field] !== "string") return false;
+	}
+	for (const field of ["args", "includeTools", "excludeTools"] as const) {
+		if (value[field] !== undefined && !isStringArray(value[field])) return false;
+	}
+	for (const field of ["env", "headers"] as const) {
+		if (value[field] !== undefined && !isStringRecord(value[field])) return false;
+	}
+	for (const field of ["exposeResources", "literalEnv"] as const) {
+		if (value[field] !== undefined && typeof value[field] !== "boolean") return false;
+	}
+	if (value.requestHeadersCommand !== undefined && !isRequestHeadersCommand(value.requestHeadersCommand)) return false;
+	if (value.auth !== undefined && value.auth !== "oauth" && value.auth !== "bearer" && value.auth !== false) return false;
+	return value.directTools === undefined || typeof value.directTools === "boolean" || isStringArray(value.directTools);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+	return isRecord(value) && Object.values(value).every((entry) => typeof entry === "string");
+}
+
+function isRequestHeadersCommand(value: unknown): value is NonNullable<McpServerDefinition["requestHeadersCommand"]> {
+	if (!isRecord(value) || typeof value.command !== "string") return false;
+	if (value.args !== undefined && !isStringArray(value.args)) return false;
+	if (value.env !== undefined && !isStringRecord(value.env)) return false;
+	return value.timeoutMs === undefined || (typeof value.timeoutMs === "number" && Number.isFinite(value.timeoutMs));
+}
+
 export function loadPackageMcpServers(cwd: string): Record<string, McpServerDefinition> {
 	const servers: Record<string, McpServerDefinition> = {};
 	const seen = new Set<string>();
@@ -64,11 +102,11 @@ export function loadPackageMcpServers(cwd: string): Record<string, McpServerDefi
 			const rawServers = (config as { mcpServers?: unknown }).mcpServers;
 			if (!rawServers || typeof rawServers !== "object" || Array.isArray(rawServers)) continue;
 			for (const [serverName, definition] of Object.entries(rawServers)) {
-				if (!definition || typeof definition !== "object" || Array.isArray(definition)) continue;
+				if (!isMcpServerDefinition(definition)) continue;
 				const normalizedName = `${packagePrefix}__${formatName(serverName, "server")}`;
 				if (seen.has(normalizedName)) continue;
 				seen.add(normalizedName);
-				servers[normalizedName] = definition as McpServerDefinition;
+				servers[normalizedName] = definition;
 			}
 		}
 	}
@@ -90,7 +128,7 @@ export function loadAgentPluginMcpServers(paths: unknown, cwd: string): Record<s
 		const rawServers = (config as { mcpServers: Record<string, unknown> }).mcpServers;
 
 		for (const [serverName, rawDefinition] of Object.entries(rawServers)) {
-			const definition = translatePluginServer(manifest.name, pluginRoot, serverName, rawDefinition);
+			const definition = translatePluginServer(manifest.name, pluginRoot, rawDefinition);
 			if (!definition) continue;
 			const normalizedName = `${formatName(manifest.name, "plugin")}__${formatName(serverName, "server")}`;
 			if (Object.hasOwn(servers, normalizedName)) continue;
@@ -254,12 +292,11 @@ function isValidPluginConfig(value: unknown): value is { mcpServers: Record<stri
 function translatePluginServer(
 	pluginName: string,
 	pluginRoot: string,
-	serverName: string,
 	value: unknown,
 ): McpServerDefinition | undefined {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
 	const raw = value as Record<string, unknown>;
-	if (raw.type === "stdio") return translatePluginStdioServer(pluginName, pluginRoot, serverName, raw);
+	if (raw.type === "stdio") return translatePluginStdioServer(pluginName, pluginRoot, raw);
 	if (raw.type === "streamable-http" || raw.type === "sse") return translatePluginHttpServer(raw);
 	return undefined;
 }
@@ -267,7 +304,6 @@ function translatePluginServer(
 function translatePluginStdioServer(
 	pluginName: string,
 	pluginRoot: string,
-	serverName: string,
 	raw: Record<string, unknown>,
 ): McpServerDefinition | undefined {
 	if ([...Object.keys(raw)].some((key) => !PLUGIN_STDIO_FIELDS.has(key))) return undefined;

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

@@ -4,11 +4,19 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { findConfiguredProjectRoot } from "../../agents/agents.ts";
 import { getAgentDir, getProjectConfigDir } from "../../shared/utils.ts";
-import { loadAgentPluginMcpServers, loadPackageMcpServers, type McpServerDefinition } from "./mcp-config-sources.ts";
+import { isMcpServerDefinition, loadAgentPluginMcpServers, loadPackageMcpServers, type McpServerDefinition } from "./mcp-config-sources.ts";
+import {
+	normalizeMcpDirectToolSelectors,
+	parseMcpDirectToolSelectors,
+	planMcpDirectToolGrant,
+} from "./mcp-direct-tool-grant.ts";
+import type { McpToolPrefix, ResolvedMcpDirectToolSelection } from "./mcp-direct-tool-grant.ts";
+
+export { formatUnresolvedMcpDirectToolSelectors } from "./mcp-direct-tool-grant.ts";
+export type { ResolvedMcpDirectToolSelection } from "./mcp-direct-tool-grant.ts";
 
 const CACHE_VERSION = 1;
 const CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
-const BUILTIN_TOOL_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls", "mcp"]);
 const GENERIC_GLOBAL_CONFIG_PATH = path.join(os.homedir(), ".config", "mcp", "mcp.json");
 const IMPORT_PATHS = {
 	cursor: [path.join(os.homedir(), ".cursor", "mcp.json")],
@@ -23,7 +31,6 @@ const IMPORT_PATHS = {
 	vscode: [".vscode/mcp.json"],
 } as const;
 
-type ToolPrefix = "server" | "none" | "short";
 type ImportKind = keyof typeof IMPORT_PATHS;
 
 type ServerEntry = McpServerDefinition;
@@ -32,7 +39,7 @@ export interface McpConfig {
 	mcpServers: Record<string, ServerEntry>;
 	imports?: ImportKind[];
 	settings?: {
-		toolPrefix?: ToolPrefix;
+		toolPrefix?: McpToolPrefix;
 		directTools?: boolean;
 		agentPluginPaths?: unknown;
 	};
@@ -83,8 +90,6 @@ interface MetadataCache {
 	servers: Record<string, ServerCacheEntry>;
 }
 
-export interface ResolvedMcpDirectToolSelection { name: string; selector: string }
-
 export interface McpDirectToolResolution {
 	selections: ResolvedMcpDirectToolSelection[];
 	unresolvedSelectors: string[];
@@ -93,21 +98,17 @@ export interface McpDirectToolResolution {
 	runtimeServerNames?: string[];
 }
 
-function normalizeSelectors(selectors: string[] | undefined): string[] {
-	return [...new Set((selectors ?? []).map((selector) => selector.replace(/\/+$/, "")).filter(Boolean))];
-}
-
 export function resolveMcpDirectToolResolution(
 	mcpDirectTools: string[] | undefined,
 	cwd = process.cwd(),
 	runtimeSnapshotHost?: McpRuntimeSnapshotHost,
 	configOverride?: McpConfig,
 ): McpDirectToolResolution {
-	const selectors = normalizeSelectors(mcpDirectTools);
+	const selectors = normalizeMcpDirectToolSelectors(mcpDirectTools);
 	if (selectors.length === 0) return { selections: [], unresolvedSelectors: [] };
 
 	const config = configOverride ?? loadMcpConfig(cwd);
-	const { servers: selectedServers, tools: selectedTools } = parseSelections(selectors);
+	const { servers: selectedServers, tools: selectedTools } = parseMcpDirectToolSelectors(selectors);
 	const runtimeSelectionServers = new Set([...selectedServers, ...selectedTools.keys()]);
 	const runtimeServers = resolveRuntimeMcpServers(config, runtimeSelectionServers, runtimeSnapshotHost);
 	const resolvedConfig = Object.keys(runtimeServers).length > 0
@@ -116,15 +117,20 @@ export function resolveMcpDirectToolResolution(
 	validateSelectedServerDefinitions(resolvedConfig, selectors);
 	const cache = loadMetadataCache();
 	if (!cache) return { selections: [], unresolvedSelectors: selectors };
-	const selections = resolveDirectToolSelections(resolvedConfig, cache, getToolPrefix(resolvedConfig.settings?.toolPrefix), selectors);
-	const unresolvedSelectors = selectors.filter((selector) =>
-		selector.includes("/")
-			? !selections.some((selection) => selection.selector === selector)
-			: !selections.some((selection) => selection.selector.startsWith(`${selector}/`)),
-	);
+	const validMetadata: Record<string, ServerCacheEntry> = {};
+	for (const [serverName, definition] of Object.entries(resolvedConfig.mcpServers)) {
+		const serverCache = cache.servers[serverName];
+		if (isServerCacheValid(serverCache, definition)) validMetadata[serverName] = serverCache;
+	}
+	const grant = planMcpDirectToolGrant({
+		selectors,
+		servers: resolvedConfig.mcpServers,
+		metadata: validMetadata,
+		toolPrefix: resolvedConfig.settings?.toolPrefix,
+	});
 	return {
-		selections,
-		unresolvedSelectors,
+		selections: grant.selections,
+		unresolvedSelectors: grant.unresolvedSelectors,
 		...(Object.keys(runtimeServers).length > 0
 			? { mcpConfig: resolvedConfig, runtimeServerNames: Object.keys(runtimeServers) }
 			: {}),
@@ -139,10 +145,6 @@ export function resolveMcpDirectToolSelections(
 	return resolveMcpDirectToolResolution(mcpDirectTools, cwd, runtimeSnapshotHost).selections;
 }
 
-export function formatUnresolvedMcpDirectToolSelectors(selectors: readonly string[]): string {
-	return `Unresolved MCP direct-tool selectors: ${selectors.join(", ")}. Direct MCP tools require a matching configured server and fresh metadata cache; runtime-registered servers require a host/pi-mcp-adapter handoff before child launch.`;
-}
-
 function loadMetadataCache(): MetadataCache | null {
 	const cachePath = path.join(getAgentDir(), "mcp-cache.json");
 	let parsed: unknown;
@@ -152,12 +154,46 @@ function loadMetadataCache(): MetadataCache | null {
 		return null;
 	}
 
-	if (!parsed || typeof parsed !== "object") return null;
-	const raw = parsed as Record<string, unknown>;
-	if (raw.version !== CACHE_VERSION || !raw.servers || typeof raw.servers !== "object" || Array.isArray(raw.servers)) {
-		return null;
+	if (!isRecord(parsed) || parsed.version !== CACHE_VERSION || !isRecord(parsed.servers)) return null;
+	const servers: Record<string, ServerCacheEntry> = {};
+	for (const [name, value] of Object.entries(parsed.servers)) {
+		const entry = parseServerCacheEntry(value);
+		if (entry) servers[name] = entry;
 	}
-	return raw as unknown as MetadataCache;
+	return { version: CACHE_VERSION, servers };
+}
+
+function parseServerCacheEntry(value: unknown): ServerCacheEntry | undefined {
+	if (!isRecord(value)) return undefined;
+	if (value.configHash !== undefined && typeof value.configHash !== "string") return undefined;
+	if (value.cachedAt !== undefined && (typeof value.cachedAt !== "number" || !Number.isFinite(value.cachedAt))) return undefined;
+	if (value.tools !== undefined && !Array.isArray(value.tools)) return undefined;
+	if (value.resources !== undefined && !Array.isArray(value.resources)) return undefined;
+	const tools = value.tools?.map(parseCachedTool);
+	const resources = value.resources?.map(parseCachedResource);
+	if (tools && !tools.every((entry): entry is CachedTool => entry !== undefined)) return undefined;
+	if (resources && !resources.every((entry): entry is CachedResource => entry !== undefined)) return undefined;
+	return {
+		...(value.configHash !== undefined ? { configHash: value.configHash } : {}),
+		...(value.cachedAt !== undefined ? { cachedAt: value.cachedAt } : {}),
+		...(tools ? { tools } : {}),
+		...(resources ? { resources } : {}),
+	};
+}
+
+function parseCachedTool(value: unknown): CachedTool | undefined {
+	if (!isRecord(value) || (value.name !== undefined && typeof value.name !== "string")) return undefined;
+	return value.name === undefined ? {} : { name: value.name };
+}
+
+function parseCachedResource(value: unknown): CachedResource | undefined {
+	if (!isRecord(value)) return undefined;
+	if (value.uri !== undefined && typeof value.uri !== "string") return undefined;
+	if (value.name !== undefined && typeof value.name !== "string") return undefined;
+	return {
+		...(value.uri !== undefined ? { uri: value.uri } : {}),
+		...(value.name !== undefined ? { name: value.name } : {}),
+	};
 }
 
 function resolveRuntimeMcpServers(
@@ -196,9 +232,7 @@ function getRuntimeMcpServerSnapshot(
 		snapshot.name !== name ||
 		snapshot.runtime !== true ||
 		snapshot.persisted !== false ||
-		!snapshot.definition ||
-		typeof snapshot.definition !== "object" ||
-		Array.isArray(snapshot.definition)
+		!isMcpServerDefinition(snapshot.definition)
 	) {
 		throw new Error(`Invalid MCP runtime snapshot for server "${name}"`);
 	}
@@ -249,18 +283,33 @@ function readConfig(configPath: string): McpConfig | null {
 }
 
 function validateConfig(raw: unknown): McpConfig {
-	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { mcpServers: {} };
-	const obj = raw as Record<string, unknown>;
+	if (!isRecord(raw)) return { mcpServers: {} };
+	const obj = raw;
 	const servers = obj.mcpServers ?? obj["mcp-servers"] ?? {};
 	return {
-		mcpServers: servers && typeof servers === "object" && !Array.isArray(servers) ? servers as Record<string, ServerEntry> : {},
+		mcpServers: parseServerEntries(servers),
 		imports: Array.isArray(obj.imports) ? obj.imports.filter((value): value is ImportKind => isImportKind(value)) : undefined,
-		settings: obj.settings && typeof obj.settings === "object" && !Array.isArray(obj.settings)
-			? obj.settings as McpConfig["settings"]
-			: undefined,
+		settings: parseSettings(obj.settings),
 	};
 }
 
+function parseServerEntries(value: unknown): Record<string, ServerEntry> {
+	if (!isRecord(value)) return {};
+	return Object.fromEntries(Object.entries(value).filter((entry): entry is [string, ServerEntry] => isMcpServerDefinition(entry[1])));
+}
+
+function parseSettings(value: unknown): McpConfig["settings"] | undefined {
+	if (!isRecord(value)) return undefined;
+	const toolPrefix = value.toolPrefix === "server" || value.toolPrefix === "short" || value.toolPrefix === "none" ? value.toolPrefix : undefined;
+	const directTools = typeof value.directTools === "boolean" ? value.directTools : undefined;
+	const settings: NonNullable<McpConfig["settings"]> = {
+		...(toolPrefix ? { toolPrefix } : {}),
+		...(directTools !== undefined ? { directTools } : {}),
+		...(value.agentPluginPaths !== undefined ? { agentPluginPaths: value.agentPluginPaths } : {}),
+	};
+	return Object.keys(settings).length ? settings : undefined;
+}
+
 function mergeConfigs(base: McpConfig, next: McpConfig): McpConfig {
 	const imports = [...(base.imports ?? []), ...(next.imports ?? [])];
 	return {
@@ -304,79 +353,20 @@ function resolveImportPath(importKind: ImportKind, cwd: string): string | null {
 }
 
 function extractServers(config: unknown, kind: ImportKind): Record<string, ServerEntry> {
-	if (!config || typeof config !== "object" || Array.isArray(config)) return {};
-	const obj = config as Record<string, unknown>;
+	if (!isRecord(config)) return {};
+	const obj = config;
 	const servers = kind === "cursor" || kind === "windsurf" || kind === "vscode"
 		? obj.mcpServers ?? obj["mcp-servers"]
 		: obj.mcpServers;
-	return servers && typeof servers === "object" && !Array.isArray(servers) ? servers as Record<string, ServerEntry> : {};
-}
-
-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);
-
-	for (const [serverName, definition] of Object.entries(config.mcpServers)) {
-		const serverCache = cache.servers[serverName];
-		if (!isServerCacheValid(serverCache, definition)) continue;
-
-		const toolFilter = selectedServers.has(serverName)
-			? true
-			: selectedTools.get(serverName);
-		if (!toolFilter) continue;
-
-		for (const tool of Array.isArray(serverCache.tools) ? serverCache.tools : []) {
-			if (typeof tool?.name !== "string" || !tool.name) continue;
-			if (toolFilter !== true && !toolFilter.has(tool.name)) continue;
-			if (isToolExcluded(tool.name, serverName, prefix, definition.excludeTools)) continue;
-			const prefixedName = formatToolName(tool.name, serverName, prefix);
-			if (BUILTIN_TOOL_NAMES.has(prefixedName) || seenNames.has(prefixedName)) continue;
-			seenNames.add(prefixedName);
-			names.push({ name: prefixedName, selector: `${serverName}/${tool.name}` });
-		}
-
-		if (definition.exposeResources === false) continue;
-		for (const resource of Array.isArray(serverCache.resources) ? serverCache.resources : []) {
-			if (typeof resource?.name !== "string" || !resource.name || typeof resource.uri !== "string" || !resource.uri) continue;
-			const baseName = `get_${resourceNameToToolName(resource.name)}`;
-			if (toolFilter !== true && !toolFilter.has(baseName)) continue;
-			if (isToolExcluded(baseName, serverName, prefix, definition.excludeTools)) continue;
-			const prefixedName = formatToolName(baseName, serverName, prefix);
-			if (BUILTIN_TOOL_NAMES.has(prefixedName) || seenNames.has(prefixedName)) continue;
-			seenNames.add(prefixedName);
-			names.push({ name: prefixedName, selector: `${serverName}/${baseName}` });
-		}
-	}
-
-	return names;
+	return parseServerEntries(servers);
 }
 
 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>>();
-	for (const item of selections) {
-		if (item.includes("/")) {
-			const [server, tool] = item.split("/", 2);
-			if (server && tool) {
-				if (!tools.has(server)) tools.set(server, new Set());
-				tools.get(server)!.add(tool);
-			} else if (server) {
-				servers.add(server);
-			}
-		} else if (item) {
-			servers.add(item);
-		}
-	}
-	return { servers, tools };
-}
-
 function validateSelectedServerDefinitions(config: McpConfig, selectors: string[]): void {
-	const { servers, tools } = parseSelections(selectors);
+	const { servers, tools } = parseMcpDirectToolSelectors(selectors);
 	for (const serverName of new Set([...servers, ...tools.keys()])) {
 		const definition = config.mcpServers[serverName];
 		if (definition) computeMcpServerHash(definition);
@@ -417,52 +407,12 @@ export function computeMcpServerHash(definition: ServerEntry): string {
 	return createHash("sha256").update(stableStringify(identity)).digest("hex");
 }
 
-function getToolPrefix(value: unknown): ToolPrefix {
-	return value === "none" || value === "short" || value === "server" ? value : "server";
-}
-
 function isImportKind(value: unknown): value is ImportKind {
 	return typeof value === "string" && Object.hasOwn(IMPORT_PATHS, value);
 }
 
-function getServerPrefix(serverName: string, mode: ToolPrefix): string {
-	if (mode === "none") return "";
-	if (mode === "short") {
-		const short = serverName.replace(/-?mcp$/i, "").replace(/-/g, "_");
-		return short || "mcp";
-	}
-	return serverName.replace(/-/g, "_");
-}
-
-function formatToolName(toolName: string, serverName: string, prefix: ToolPrefix): string {
-	const serverPrefix = getServerPrefix(serverName, prefix);
-	return serverPrefix ? `${serverPrefix}_${toolName}` : toolName;
-}
-
-function isToolExcluded(toolName: string, serverName: string, prefix: ToolPrefix, excludeTools: unknown): boolean {
-	if (!Array.isArray(excludeTools) || excludeTools.length === 0) return false;
-	const candidates = new Set([
-		normalizeToolName(toolName),
-		normalizeToolName(formatToolName(toolName, serverName, prefix)),
-		normalizeToolName(formatToolName(toolName, serverName, "server")),
-		normalizeToolName(formatToolName(toolName, serverName, "short")),
-	]);
-	return excludeTools.some((excluded) => typeof excluded === "string" && candidates.has(normalizeToolName(excluded)));
-}
-
-function normalizeToolName(value: string): string {
-	return value.replace(/-/g, "_");
-}
-
-function resourceNameToToolName(name: string): string {
-	let result = name
-		.replace(/[^a-zA-Z0-9]/g, "_")
-		.replace(/_+/g, "_")
-		.replace(/^_+/, "")
-		.replace(/_+$/, "")
-		.toLowerCase();
-	if (!result || /^\d/.test(result)) result = `resource${result ? `_${result}` : ""}`;
-	return result;
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
 function interpolateEnvRecord(values: Record<string, string> | undefined): Record<string, string> | undefined {

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

@@ -0,0 +1,194 @@
+const BUILTIN_TOOL_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls", "mcp"]);
+
+export type McpToolPrefix = "server" | "none" | "short";
+
+export interface McpGrantServerFacts {
+	readonly exposeResources?: boolean;
+	readonly includeTools?: readonly unknown[];
+	readonly excludeTools?: readonly unknown[];
+}
+
+export interface McpGrantToolMetadata {
+	readonly name?: string;
+}
+
+export interface McpGrantResourceMetadata {
+	readonly name?: string;
+	readonly uri?: string;
+}
+
+export interface McpGrantServerMetadata {
+	readonly tools?: readonly McpGrantToolMetadata[];
+	readonly resources?: readonly McpGrantResourceMetadata[];
+}
+
+export interface McpDirectToolGrantInput {
+	readonly selectors?: readonly string[];
+	readonly servers: Readonly<Record<string, McpGrantServerFacts>>;
+	/** Cache entries already validated by the source-loading adapter. */
+	readonly metadata: Readonly<Record<string, McpGrantServerMetadata>>;
+	readonly toolPrefix?: unknown;
+}
+
+export interface ResolvedMcpDirectToolSelection {
+	name: string;
+	selector: string;
+}
+
+export interface McpDirectToolGrant {
+	selections: ResolvedMcpDirectToolSelection[];
+	unresolvedSelectors: string[];
+}
+
+export function normalizeMcpDirectToolSelectors(selectors: readonly string[] | undefined): string[] {
+	return [...new Set((selectors ?? []).map((selector) => selector.replace(/\/+$/, "")).filter(Boolean))];
+}
+
+export function parseMcpDirectToolSelectors(selectors: readonly string[]): {
+	servers: Set<string>;
+	tools: Map<string, Set<string>>;
+} {
+	const servers = new Set<string>();
+	const tools = new Map<string, Set<string>>();
+	for (const item of selectors) {
+		if (item.includes("/")) {
+			const [server, tool] = item.split("/", 2);
+			if (server && tool) {
+				if (!tools.has(server)) tools.set(server, new Set());
+				tools.get(server)!.add(tool);
+			} else if (server) {
+				servers.add(server);
+			}
+		} else if (item) {
+			servers.add(item);
+		}
+	}
+	return { servers, tools };
+}
+
+export function planMcpDirectToolGrant(input: McpDirectToolGrantInput): McpDirectToolGrant {
+	const selectors = normalizeMcpDirectToolSelectors(input.selectors);
+	if (selectors.length === 0) return { selections: [], unresolvedSelectors: [] };
+
+	const { servers: selectedServers, tools: selectedTools } = parseMcpDirectToolSelectors(selectors);
+	const selections: ResolvedMcpDirectToolSelection[] = [];
+	const seenNames = new Set<string>();
+	const prefix = normalizeMcpToolPrefix(input.toolPrefix);
+
+	for (const [serverName, server] of Object.entries(input.servers)) {
+		const metadata = input.metadata[serverName];
+		if (!metadata) continue;
+
+		const toolFilter: true | ReadonlySet<string> | undefined = selectedServers.has(serverName)
+			? true
+			: selectedTools.get(serverName);
+		if (!toolFilter) continue;
+
+		for (const tool of Array.isArray(metadata.tools) ? metadata.tools : []) {
+			if (typeof tool?.name !== "string" || !tool.name) continue;
+			if (toolFilter !== true && !toolFilter.has(tool.name)) continue;
+			if (!isToolAllowed(tool.name, serverName, prefix, server.includeTools, server.excludeTools)) continue;
+			const name = formatToolName(tool.name, serverName, prefix);
+			if (BUILTIN_TOOL_NAMES.has(name) || seenNames.has(name)) continue;
+			seenNames.add(name);
+			selections.push({ name, selector: `${serverName}/${tool.name}` });
+		}
+
+		if (server.exposeResources === false) continue;
+		for (const resource of Array.isArray(metadata.resources) ? metadata.resources : []) {
+			if (typeof resource?.name !== "string" || !resource.name || typeof resource.uri !== "string" || !resource.uri) continue;
+			const baseName = `get_${resourceNameToToolName(resource.name)}`;
+			if (toolFilter !== true && !toolFilter.has(baseName)) continue;
+			if (!isToolAllowed(baseName, serverName, prefix, server.includeTools, server.excludeTools)) continue;
+			const name = formatToolName(baseName, serverName, prefix);
+			if (BUILTIN_TOOL_NAMES.has(name) || seenNames.has(name)) continue;
+			seenNames.add(name);
+			selections.push({ name, selector: `${serverName}/${baseName}` });
+		}
+	}
+
+	const unresolvedSelectors = selectors.filter((selector) =>
+		selector.includes("/")
+			? !selections.some((selection) => selection.selector === selector)
+			: !selections.some((selection) => selection.selector.startsWith(`${selector}/`)),
+	);
+	return { selections, unresolvedSelectors };
+}
+
+export function normalizeMcpToolPrefix(value: unknown): McpToolPrefix {
+	return value === "none" || value === "short" || value === "server" ? value : "server";
+}
+
+export function formatUnresolvedMcpDirectToolSelectors(selectors: readonly string[]): string {
+	return `Unresolved MCP direct-tool selectors: ${selectors.join(", ")}. Direct MCP tools require a matching configured server and fresh metadata cache; runtime-registered servers require a host/pi-mcp-adapter handoff before child launch.`;
+}
+
+function getServerPrefix(serverName: string, mode: McpToolPrefix): string {
+	if (mode === "none") return "";
+	if (mode === "short") return serverName.replace(/-?mcp$/i, "") || "mcp";
+	return serverName;
+}
+
+function formatToolName(toolName: string, serverName: string, prefix: McpToolPrefix): string {
+	const serverPrefix = getServerPrefix(serverName, prefix);
+	return serverPrefix ? `${serverPrefix}_${toolName}` : toolName;
+}
+
+function isToolAllowed(
+	toolName: string,
+	serverName: string,
+	prefix: McpToolPrefix,
+	includeTools: readonly unknown[] | undefined,
+	excludeTools: readonly unknown[] | undefined,
+): boolean {
+	const candidates = toolNameCandidates(toolName, serverName, prefix);
+	return (!Array.isArray(includeTools) || includeTools.length === 0 || matchesToolPatterns(candidates, includeTools))
+		&& !matchesToolPatterns(candidates, excludeTools);
+}
+
+function toolNameCandidates(toolName: string, serverName: string, prefix: McpToolPrefix): Set<string> {
+	return new Set([
+		toolName,
+		`mcp_${toolName}`,
+		formatToolName(toolName, serverName, prefix),
+		formatToolName(toolName, serverName, "server"),
+		formatToolName(toolName, serverName, "short"),
+		formatToolName(toolName, serverName, "none"),
+	]);
+}
+
+function matchesToolPatterns(candidates: ReadonlySet<string>, patterns: readonly unknown[] | undefined): boolean {
+	if (!Array.isArray(patterns) || patterns.length === 0) return false;
+	for (const pattern of patterns) {
+		if (typeof pattern !== "string") continue;
+		const normalizedPattern = normalizeToolName(pattern);
+		const matcher = normalizedPattern.includes("*") || normalizedPattern.includes("?")
+			? globToRegExp(normalizedPattern)
+			: undefined;
+		for (const candidate of candidates) {
+			const normalizedCandidate = normalizeToolName(candidate);
+			if (matcher ? matcher.test(normalizedCandidate) : normalizedCandidate === normalizedPattern) return true;
+		}
+	}
+	return false;
+}
+
+function globToRegExp(pattern: string): RegExp {
+	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+	return new RegExp(`^${escaped}$`);
+}
+
+function normalizeToolName(value: string): string {
+	return value.replace(/-/g, "_");
+}
+
+function resourceNameToToolName(name: string): string {
+	let result = name
+		.replace(/[^a-zA-Z0-9]/g, "_")
+		.replace(/_+/g, "_")
+		.replace(/^_+/, "")
+		.replace(/_+$/, "")
+		.toLowerCase();
+	if (!result || /^\d/.test(result)) result = `resource${result ? `_${result}` : ""}`;
+	return result;
+}

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

@@ -24,7 +24,12 @@ export function formatSubagentModelVerificationError(expectedModel: string, obse
 	const observedBase = splitThinkingSuffix(observedModel).baseModel;
 	if (expectedBase === observedBase) return undefined;
 	const expectedEntry = availableModels.find((entry) => entry.fullId === expectedBase);
-	if (expectedEntry && expectedEntry.id === observedBase) return undefined;
+	if (expectedEntry) {
+		if (expectedEntry.id === observedBase) return undefined;
+		const expectedIdLeaf = expectedEntry.id.slice(expectedEntry.id.lastIndexOf("/") + 1);
+		const expectedFullIdLeaf = expectedEntry.fullId.slice(expectedEntry.fullId.lastIndexOf("/") + 1);
+		if (expectedIdLeaf === observedBase || expectedFullIdLeaf === observedBase) return undefined;
+	}
 	return `model_verification_failed: child reported a different model than the launch candidate. Expected '${expectedModel}' but observed '${observedModel}'.`;
 }
 
@@ -446,9 +451,11 @@ const RETRYABLE_MODEL_FAILURE_PATTERNS = [
 	/upstream/i,
 	/timed? out/i,
 	/timeout/i,
+	/\b500\b/,
 	/\b502\b/,
 	/\b503\b/,
 	/\b504\b/,
+	/internal server error/i,
 	/cold.?start/i,
 	/empty response/i,
 	/no output/i,
@@ -479,7 +486,7 @@ function messageError(message: unknown): string | undefined {
 export function isRetryableModelFailureAttempt(input: { error: string | undefined; messages?: readonly unknown[]; toolCount?: number }): boolean {
 	if (!isRetryableModelFailure(input.error)) return false;
 	if ((input.toolCount ?? 0) > 0) return false;
-	if (input.error === "Subagent produced no output (possible model cold-start or empty response).") return true;
+	if (input.error === "Subagent produced no output (possible model cold-start or empty response)." || /^Subagent produced no output after terminal assistant stopReason "[^"]+"\.$/.test(input.error ?? "")) return true;
 	if ((input.toolCount ?? 0) === 0 && (input.messages?.length ?? 0) === 0) return true;
 	const error = input.error?.trim();
 	return Boolean(error && input.messages?.some((message) => messageError(message)?.trim() === error));