pi-subagents 0.24.3 → 0.24.4

package/src/runs/background/async-job-tracker.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { renderWidget } from "../../tui/render.ts";
+import { renderWidget, widgetRenderKey } from "../../tui/render.ts";
 import { formatControlNoticeMessage } from "../shared/subagent-control.ts";
 import {
 	type AsyncJobState,
@@ -118,7 +118,9 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 				return;
 			}
 
+			let widgetChanged = false;
 			for (const job of state.asyncJobs.values()) {
+				const widgetStateBefore = widgetRenderKey(job);
 				try {
 					emitNewControlEvents(job);
 					const reconciliation = reconcileAsyncRun(job.asyncDir, {
@@ -153,7 +155,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 						job.currentStep = status.currentStep ?? job.currentStep;
 						job.chainStepCount = status.chainStepCount ?? job.chainStepCount;
 						job.startedAt = status.startedAt ?? job.startedAt;
-						job.updatedAt = status.lastUpdate ?? Date.now();
+						if (status.lastUpdate !== undefined) job.updatedAt = status.lastUpdate;
 						if (status.steps?.length) {
 							const groups = normalizeParallelGroups(status.parallelGroups, status.steps.length, status.chainStepCount ?? status.steps.length);
 							job.parallelGroups = groups.length ? groups : job.parallelGroups;
@@ -179,21 +181,27 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 						if ((job.status === "complete" || job.status === "failed" || job.status === "paused") && (previousStatus !== job.status || !state.cleanupTimers.has(job.asyncId))) {
 							scheduleCleanup(job.asyncId);
 						}
+						if (widgetRenderKey(job) !== widgetStateBefore) widgetChanged = true;
 						continue;
 					}
-					job.status = job.status === "queued" ? "running" : job.status;
-					job.updatedAt = Date.now();
+					if (job.status === "queued") {
+						job.status = "running";
+						job.updatedAt = Date.now();
+					}
 				} catch (error) {
-					console.error(`Failed to read async status for '${job.asyncDir}':`, error);
-					job.status = "failed";
-					job.updatedAt = Date.now();
+					if (job.status !== "failed") {
+						console.error(`Failed to read async status for '${job.asyncDir}':`, error);
+						job.status = "failed";
+						job.updatedAt = Date.now();
+					}
 					if (!state.cleanupTimers.has(job.asyncId)) {
 						scheduleCleanup(job.asyncId);
 					}
 				}
+				if (widgetRenderKey(job) !== widgetStateBefore) widgetChanged = true;
 			}
 
-			if (state.lastUiContext?.hasUI) rerenderWidget(state.lastUiContext);
+			if (widgetChanged && state.lastUiContext?.hasUI) rerenderWidget(state.lastUiContext);
 		}, pollIntervalMs);
 		state.poller.unref?.();
 	};

package/src/runs/background/subagent-runner.ts

@@ -222,7 +222,12 @@ function runPiStreaming(
 			...(piPackageRoot ? { piPackageRoot } : {}),
 			...(piArgv1 ? { argv1: piArgv1 } : {}),
 		});
-		const child = spawn(spawnSpec.command, spawnSpec.args, { cwd, stdio: ["ignore", "pipe", "pipe"], env: spawnEnv });
+		const child = spawn(spawnSpec.command, spawnSpec.args, {
+			cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+			env: spawnEnv,
+			windowsHide: true,
+		});
 		let stderr = "";
 		let stdoutBuf = "";
 		let stderrBuf = "";
@@ -230,6 +235,7 @@ function runPiStreaming(
 		const usage = emptyUsage();
 		let model: string | undefined;
 		let error: string | undefined;
+		let assistantError: string | undefined;
 		let interrupted = false;
 		let observedMutationAttempt = false;
 		const rawStdoutLines: string[] = [];
@@ -290,7 +296,7 @@ function runPiStreaming(
 
 				if (event.type !== "message_end" || event.message.role !== "assistant") return;
 				if (event.message.model) model = event.message.model;
-				if (event.message.errorMessage) error = event.message.errorMessage;
+				if (event.message.errorMessage) assistantError = event.message.errorMessage;
 				const eventUsage = event.message.usage;
 				if (eventUsage) {
 					usage.turns++;
@@ -304,6 +310,7 @@ function runPiStreaming(
 				const hasToolCall = Array.isArray(event.message.content)
 					&& event.message.content.some((part) => (part as { type?: string }).type === "toolCall");
 				if (stopReason === "stop" && !hasToolCall) {
+					if (!event.message.errorMessage && extractTextFromContent(event.message.content).trim()) assistantError = undefined;
 					cleanTerminalAssistantStopReceived ||= !event.message.errorMessage;
 					startFinalDrain();
 				}
@@ -371,7 +378,7 @@ function runPiStreaming(
 				const termSent = trySignalChild(child, "SIGTERM");
 				if (!termSent) return;
 				forcedTerminationSignal = true;
-				if (!cleanTerminalAssistantStopReceived && !error) {
+				if (!cleanTerminalAssistantStopReceived && !error && !assistantError) {
 					error = `Subagent process did not exit within ${FINAL_STOP_GRACE_MS}ms after its final message. Forcing termination.`;
 				}
 				finalHardKillTimer = setTimeout(() => {
@@ -395,14 +402,15 @@ function runPiStreaming(
 			if (stderrBuf.trim()) appendChildLine("subagent.child.stderr", stderrBuf);
 			outputStream.end();
 			const finalOutput = getFinalOutput(messages) || rawStdoutLines.join("\n").trim();
-			const forcedDrainAfterFinalSuccess = forcedTerminationSignal && cleanTerminalAssistantStopReceived && !error;
+			const finalError = error ?? assistantError;
+			const forcedDrainAfterFinalSuccess = forcedTerminationSignal && cleanTerminalAssistantStopReceived && !finalError;
 			resolve({
 				stderr,
 				exitCode: interrupted || forcedDrainAfterFinalSuccess ? 0 : forcedTerminationSignal || signal ? (exitCode ?? 1) : exitCode,
 				messages,
 				usage,
 				model,
-				error: interrupted || forcedDrainAfterFinalSuccess ? undefined : error,
+				error: interrupted || forcedDrainAfterFinalSuccess ? undefined : finalError,
 				finalOutput,
 				interrupted,
 				observedMutationAttempt,
@@ -417,7 +425,7 @@ function runPiStreaming(
 			outputStream.end();
 			const finalOutput = getFinalOutput(messages) || rawStdoutLines.join("\n").trim();
 			const spawnErrorMessage = spawnError instanceof Error ? spawnError.message : String(spawnError);
-			resolve({ stderr, exitCode: 1, messages, usage, model, error: error ?? spawnErrorMessage, finalOutput, observedMutationAttempt });
+			resolve({ stderr, exitCode: 1, messages, usage, model, error: error ?? assistantError ?? spawnErrorMessage, finalOutput, observedMutationAttempt });
 		});
 	});
 }
@@ -614,6 +622,7 @@ async function runSingleStep(
 			systemPrompt: step.systemPrompt,
 			systemPromptMode: step.systemPromptMode,
 			mcpDirectTools: step.mcpDirectTools,
+			cwd: step.cwd ?? ctx.cwd,
 			promptFileStem: step.agent,
 			intercomSessionName: ctx.childIntercomTarget,
 			orchestratorIntercomTarget: ctx.orchestratorIntercomTarget,
@@ -636,11 +645,13 @@ async function runSingleStep(
 		cleanupTempDir(tempDir);
 
 		const hiddenError = run.exitCode === 0 && !run.error ? detectSubagentError(run.messages) : null;
-		const completionGuard = run.exitCode === 0 && !run.error && !hiddenError?.hasError
+		const completionGuard = run.exitCode === 0 && !run.error && !hiddenError?.hasError && step.completionGuard !== false
 			? evaluateCompletionMutationGuard({
 				agent: step.agent,
 				task,
 				messages: run.messages,
+				tools: step.tools,
+				mcpDirectTools: step.mcpDirectTools,
 			})
 			: undefined;
 		const completionGuardTriggered = completionGuard?.triggered === true && !run.observedMutationAttempt;

package/src/runs/foreground/execution.ts

@@ -151,6 +151,7 @@ async function runSingleAttempt(
 		extensions: agent.extensions,
 		systemPrompt: shared.systemPrompt,
 		mcpDirectTools: agent.mcpDirectTools,
+		cwd: options.cwd ?? runtimeCwd,
 		promptFileStem: agent.name,
 		intercomSessionName: options.intercomSessionName,
 		orchestratorIntercomTarget: options.orchestratorIntercomTarget,
@@ -207,6 +208,7 @@ async function runSingleAttempt(
 			cwd: options.cwd ?? runtimeCwd,
 			env: spawnEnv,
 			stdio: ["ignore", "pipe", "pipe"],
+			windowsHide: true,
 		});
 		const jsonlWriter = createJsonlWriter(shared.jsonlPath, proc.stdout);
 		let buf = "";
@@ -214,6 +216,7 @@ async function runSingleAttempt(
 		let settled = false;
 		let detached = false;
 		let intercomStarted = false;
+		let assistantError: string | undefined;
 		let removeAbortListener: (() => void) | undefined;
 		let removeInterruptListener: (() => void) | undefined;
 		let activityTimer: NodeJS.Timeout | undefined;
@@ -259,7 +262,7 @@ async function runSingleAttempt(
 				const termSent = trySignalChild(proc, "SIGTERM");
 				if (!termSent) return;
 				forcedTerminationSignal = true;
-				if (!cleanTerminalAssistantStopReceived) {
+				if (!cleanTerminalAssistantStopReceived && !assistantError) {
 					result.error = result.error ?? `Subagent process did not exit within ${FINAL_STOP_GRACE_MS}ms after its final message. Forcing termination.`;
 				}
 				finalHardKillTimer = setTimeout(() => {
@@ -465,13 +468,15 @@ async function runSingleAttempt(
 						progress.tokens = result.usage.input + result.usage.output;
 					}
 					if (!result.model && evt.message.model) result.model = evt.message.model;
-					if (evt.message.errorMessage) result.error = evt.message.errorMessage;
-					appendRecentOutput(progress, extractTextFromContent(evt.message.content).split("\n").slice(-10));
+					if (evt.message.errorMessage) assistantError = evt.message.errorMessage;
+					const assistantText = extractTextFromContent(evt.message.content);
+					appendRecentOutput(progress, assistantText.split("\n").slice(-10));
 					// Final assistant message: start the exit drain window.
 					const stopReason = (evt.message as { stopReason?: string }).stopReason;
 					const hasToolCall = Array.isArray(evt.message.content)
 						&& evt.message.content.some((part) => (part as { type?: string }).type === "toolCall");
 					if (stopReason === "stop" && !hasToolCall) {
+						if (!evt.message.errorMessage && assistantText.trim()) assistantError = undefined;
 						cleanTerminalAssistantStopReceived ||= !evt.message.errorMessage;
 						startFinalDrain();
 					}
@@ -551,6 +556,7 @@ async function runSingleAttempt(
 			}
 			processClosed = true;
 			if (buf.trim()) processLine(buf);
+			if (!result.error && assistantError) result.error = assistantError;
 			const forcedDrainAfterFinalSuccess = forcedTerminationSignal && cleanTerminalAssistantStopReceived && !result.error;
 			if (code !== 0 && stderrBuf.trim() && !result.error && !forcedDrainAfterFinalSuccess) {
 				result.error = stderrBuf.trim();
@@ -662,8 +668,14 @@ async function runSingleAttempt(
 	};
 
 	let fullOutput = getFinalOutput(result.messages);
-	const completionGuard = result.exitCode === 0 && !result.error
-		? evaluateCompletionMutationGuard({ agent: agent.name, task, messages: result.messages })
+	const completionGuard = result.exitCode === 0 && !result.error && agent.completionGuard !== false
+		? evaluateCompletionMutationGuard({
+			agent: agent.name,
+			task,
+			messages: result.messages,
+			tools: agent.tools,
+			mcpDirectTools: agent.mcpDirectTools,
+		})
 		: undefined;
 	if (completionGuard?.triggered && !observedMutationAttempt) {
 		result.exitCode = 1;

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

@@ -35,7 +35,7 @@ import { createForkContextResolver } from "../../shared/fork-context.ts";
 import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
 import { applyIntercomBridgeToAgent, INTERCOM_BRIDGE_MARKER, resolveIntercomBridge, resolveIntercomSessionTarget, resolveSubagentIntercomTarget, type IntercomBridgeState } from "../../intercom/intercom-bridge.ts";
 import { formatControlIntercomMessage, formatControlNoticeMessage, resolveControlConfig, shouldNotifyControlEvent } from "../shared/subagent-control.ts";
-import { finalizeSingleOutput, injectSingleOutputInstruction, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
+import { finalizeSingleOutput, injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { compactForegroundDetails, getSingleResultOutput, mapConcurrent, readStatus, resolveChildCwd } from "../../shared/utils.ts";
 import {
 	buildSubagentResultIntercomPayload,
@@ -979,7 +979,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			};
 		}
 		const rawOutput = params.output !== undefined ? params.output : a.output;
-		const effectiveOutput: string | false | undefined = rawOutput === true ? a.output : (rawOutput as string | false | undefined);
+		const effectiveOutput = normalizeSingleOutputOverride(rawOutput, a.output);
 		const effectiveOutputMode = params.outputMode ?? "inline";
 		const normalizedSkills = normalizeSkillInput(params.skill);
 		const skills = normalizedSkills === false ? [] : normalizedSkills;
@@ -1716,7 +1716,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	);
 	let skillOverride: string[] | false | undefined = normalizeSkillInput(params.skill);
 	const rawOutput = params.output !== undefined ? params.output : agentConfig.output;
-	let effectiveOutput: string | false | undefined = rawOutput === true ? agentConfig.output : (rawOutput as string | false | undefined);
+	let effectiveOutput = normalizeSingleOutputOverride(rawOutput, agentConfig.output);
 	const effectiveOutputMode = params.outputMode ?? "inline";
 	const currentMaxSubagentDepth = resolveCurrentMaxSubagentDepth(deps.config.maxSubagentDepth);
 	const maxSubagentDepth = resolveChildMaxSubagentDepth(currentMaxSubagentDepth, agentConfig.maxSubagentDepth);
@@ -1750,7 +1750,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		task = result.templates[0]!;
 		const override = result.behaviorOverrides[0];
 		if (override?.model) modelOverride = override.model;
-		if (override?.output !== undefined) effectiveOutput = override.output;
+		if (override?.output !== undefined) effectiveOutput = normalizeSingleOutputOverride(override.output, agentConfig.output);
 		if (override?.skills !== undefined) skillOverride = override.skills;
 
 		if (result.runInBackground) {

package/src/runs/shared/completion-guard.ts

@@ -54,11 +54,24 @@ const GENERAL_IMPLEMENTATION_PATTERNS = [
 	/\b(?:update|add|remove|replace|delete|create)\s+(?:the\s+)?(?:file|files|code|source|implementation|test|tests|component|function|module|class|method|logic|import|imports|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command)\b/i,
 ];
 
+const READ_ONLY_BUILTIN_TOOLS = new Set([
+	"read",
+	"grep",
+	"find",
+	"ls",
+	"web_search",
+	"fetch_content",
+	"get_search_content",
+	"intercom",
+	"contact_supervisor",
+]);
 
 interface CompletionMutationGuardInput {
 	agent: string;
 	task: string;
 	messages: Message[];
+	tools?: string[];
+	mcpDirectTools?: string[];
 }
 
 interface CompletionMutationGuardResult {
@@ -83,6 +96,13 @@ function stripScopedNoEditConstraints(task: string): string {
 	return stripped;
 }
 
+function declaresOnlyReadOnlyTools(tools: string[] | undefined, mcpDirectTools: string[] | undefined): boolean {
+	return tools !== undefined
+		&& tools.length > 0
+		&& (mcpDirectTools?.length ?? 0) === 0
+		&& tools.every((tool) => READ_ONLY_BUILTIN_TOOLS.has(tool));
+}
+
 export function expectsImplementationMutation(agent: string, task: string): boolean {
 	const taskText = stripFrameworkInstructions(task);
 	const taskTextWithoutScopedConstraints = stripScopedNoEditConstraints(taskText);
@@ -115,7 +135,9 @@ export function hasMutationToolCall(messages: Message[]): boolean {
 }
 
 export function evaluateCompletionMutationGuard(input: CompletionMutationGuardInput): CompletionMutationGuardResult {
-	const expectedMutation = expectsImplementationMutation(input.agent, input.task);
+	const expectedMutation = declaresOnlyReadOnlyTools(input.tools, input.mcpDirectTools)
+		? false
+		: expectsImplementationMutation(input.agent, input.task);
 	const attemptedMutation = hasMutationToolCall(input.messages);
 	return {
 		expectedMutation,

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

@@ -0,0 +1,365 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getAgentDir } from "../../shared/utils.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")],
+	"claude-code": [
+		path.join(os.homedir(), ".claude", "mcp.json"),
+		path.join(os.homedir(), ".claude.json"),
+		path.join(os.homedir(), ".claude", "claude_desktop_config.json"),
+	],
+	"claude-desktop": [path.join(os.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json")],
+	codex: [path.join(os.homedir(), ".codex", "config.json")],
+	windsurf: [path.join(os.homedir(), ".windsurf", "mcp.json")],
+	vscode: [".vscode/mcp.json"],
+} as const;
+
+type ToolPrefix = "server" | "none" | "short";
+type ImportKind = keyof typeof IMPORT_PATHS;
+
+interface ServerEntry {
+	command?: string;
+	args?: string[];
+	env?: Record<string, string>;
+	cwd?: string;
+	url?: string;
+	headers?: Record<string, string>;
+	auth?: "oauth" | "bearer" | false;
+	bearerToken?: string;
+	bearerTokenEnv?: string;
+	exposeResources?: boolean;
+	excludeTools?: string[];
+	directTools?: boolean | string[];
+}
+
+interface McpConfig {
+	mcpServers: Record<string, ServerEntry>;
+	imports?: ImportKind[];
+	settings?: {
+		toolPrefix?: ToolPrefix;
+		directTools?: boolean;
+	};
+}
+
+interface CachedTool {
+	name?: string;
+}
+
+interface CachedResource {
+	uri?: string;
+	name?: string;
+}
+
+interface ServerCacheEntry {
+	configHash?: string;
+	tools?: CachedTool[];
+	resources?: CachedResource[];
+	cachedAt?: number;
+}
+
+interface MetadataCache {
+	version: number;
+	servers: Record<string, ServerCacheEntry>;
+}
+
+export function resolveMcpDirectToolNames(mcpDirectTools: string[] | undefined, cwd = process.cwd()): string[] {
+	if (!mcpDirectTools?.length) return [];
+
+	try {
+		const config = loadMcpConfig(cwd);
+		const cache = loadMetadataCache();
+		if (!cache) return [];
+		return resolveDirectToolNames(config, cache, getToolPrefix(config.settings?.toolPrefix), mcpDirectTools);
+	} catch {
+		return [];
+	}
+}
+
+function loadMetadataCache(): MetadataCache | null {
+	const cachePath = path.join(getAgentDir(), "mcp-cache.json");
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(fs.readFileSync(cachePath, "utf-8"));
+	} catch {
+		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;
+	}
+	return raw as unknown as MetadataCache;
+}
+
+function loadMcpConfig(cwd: string): McpConfig {
+	let config: McpConfig = { mcpServers: {} };
+	for (const sourcePath of getConfigPaths(cwd)) {
+		const loaded = readConfig(sourcePath);
+		if (!loaded) continue;
+		config = mergeConfigs(config, expandImports(loaded, cwd));
+	}
+	return config;
+}
+
+function getConfigPaths(cwd: string): string[] {
+	const piGlobalPath = path.join(getAgentDir(), "mcp.json");
+	const projectPath = path.resolve(cwd, ".mcp.json");
+	const projectPiPath = path.resolve(cwd, ".pi", "mcp.json");
+	const sources: string[] = [];
+	if (GENERIC_GLOBAL_CONFIG_PATH !== piGlobalPath) sources.push(GENERIC_GLOBAL_CONFIG_PATH);
+	sources.push(piGlobalPath);
+	if (projectPath !== piGlobalPath) sources.push(projectPath);
+	if (projectPiPath !== piGlobalPath && projectPiPath !== projectPath) sources.push(projectPiPath);
+	return sources;
+}
+
+function readConfig(configPath: string): McpConfig | null {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+	} catch {
+		return null;
+	}
+	return validateConfig(parsed);
+}
+
+function validateConfig(raw: unknown): McpConfig {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { mcpServers: {} };
+	const obj = raw as Record<string, unknown>;
+	const servers = obj.mcpServers ?? obj["mcp-servers"] ?? {};
+	return {
+		mcpServers: servers && typeof servers === "object" && !Array.isArray(servers) ? servers as Record<string, ServerEntry> : {},
+		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,
+	};
+}
+
+function mergeConfigs(base: McpConfig, next: McpConfig): McpConfig {
+	const imports = [...(base.imports ?? []), ...(next.imports ?? [])];
+	return {
+		mcpServers: { ...base.mcpServers, ...next.mcpServers },
+		imports: imports.length ? [...new Set(imports)] : undefined,
+		settings: next.settings ? { ...base.settings, ...next.settings } : base.settings,
+	};
+}
+
+function expandImports(config: McpConfig, cwd: string): McpConfig {
+	if (!config.imports?.length) return config;
+
+	const importedServers: Record<string, ServerEntry> = {};
+	for (const importKind of config.imports) {
+		const importPath = resolveImportPath(importKind, cwd);
+		if (!importPath) continue;
+		let imported: unknown;
+		try {
+			imported = JSON.parse(fs.readFileSync(importPath, "utf-8"));
+		} catch {
+			continue;
+		}
+		for (const [name, definition] of Object.entries(extractServers(imported, importKind))) {
+			if (!importedServers[name]) importedServers[name] = definition;
+		}
+	}
+
+	return {
+		imports: config.imports,
+		settings: config.settings,
+		mcpServers: { ...importedServers, ...config.mcpServers },
+	};
+}
+
+function resolveImportPath(importKind: ImportKind, cwd: string): string | null {
+	for (const candidate of IMPORT_PATHS[importKind]) {
+		const fullPath = candidate.startsWith(".") ? path.resolve(cwd, candidate) : candidate;
+		if (fs.existsSync(fullPath)) return fullPath;
+	}
+	return 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>;
+	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 resolveDirectToolNames(config: McpConfig, cache: MetadataCache, prefix: ToolPrefix, envOverride: string[]): string[] {
+	const names: string[] = [];
+	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(prefixedName);
+		}
+
+		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(prefixedName);
+		}
+	}
+
+	return names;
+}
+
+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 (let item of selections) {
+		item = item.replace(/\/+$/, "");
+		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 isServerCacheValid(entry: ServerCacheEntry | undefined, definition: ServerEntry): entry is ServerCacheEntry {
+	if (!entry || entry.configHash !== computeMcpServerHash(definition)) return false;
+	if (!entry.cachedAt || typeof entry.cachedAt !== "number") return false;
+	return Date.now() - entry.cachedAt <= CACHE_MAX_AGE_MS;
+}
+
+export function computeMcpServerHash(definition: ServerEntry): string {
+	const identity: Record<string, unknown> = {
+		command: definition.command,
+		args: definition.args,
+		env: interpolateEnvRecord(definition.env),
+		cwd: resolveConfigPath(definition.cwd),
+		url: definition.url,
+		headers: interpolateEnvRecord(definition.headers),
+		auth: definition.auth,
+		bearerToken: resolveBearerToken(definition),
+		bearerTokenEnv: definition.bearerTokenEnv,
+		exposeResources: definition.exposeResources,
+		excludeTools: definition.excludeTools,
+	};
+	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 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;
+}
+
+function interpolateEnvVars(value: string): string {
+	return value
+		.replace(/\$\{(\w+)\}/g, (_, name: string) => process.env[name] ?? "")
+		.replace(/\$env:(\w+)/g, (_, name: string) => process.env[name] ?? "");
+}
+
+function resolveConfigPath(value: string | undefined): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const resolved = interpolateEnvVars(value);
+	if (resolved === "~") return os.homedir();
+	if (resolved.startsWith("~/") || resolved.startsWith("~\\")) return path.join(os.homedir(), resolved.slice(2));
+	return resolved;
+}
+
+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;
+}
+
+function stableStringify(value: unknown): string {
+	if (value === null || value === undefined || typeof value !== "object") {
+		const serialized = JSON.stringify(value);
+		return serialized === undefined ? "undefined" : serialized;
+	}
+	if (Array.isArray(value)) return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+	const obj = value as Record<string, unknown>;
+	return `{${Object.keys(obj).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`).join(",")}}`;
+}