@herbertgao/pi-extensions 2026.9.3 → 2026.9.5

package/node_modules/pi-mcp-adapter/index.ts

@@ -1,27 +1,24 @@
-import type { AgentToolUpdateCallback, ExtensionAPI, ExtensionContext, ToolInfo } from "@earendil-works/pi-coding-agent";
+import { withFileMutationQueue, type AgentToolUpdateCallback, type ExtensionAPI, type ExtensionContext, type ToolInfo } from "@earendil-works/pi-coding-agent";
+import { resolve } from "node:path";
 import type { McpExtensionState } from "./state.ts";
-import type { DirectToolSpec, McpAdapterOptions, McpConfig, PromptMetadata, ServerEntry } from "./types.ts";
+import { isServerDisabled, type DirectToolSpec, type McpAdapterOptions, type McpConfig, type PromptMetadata, type ServerEntry } from "./types.ts";
 import type { McpOAuthRuntime } from "./mcp-auth-flow.ts";
 import { Type } from "typebox";
 import type { TSchema } from "typebox";
-import { showStatus, showTools, showPrompts, reconnectServer, reconnectServers, authenticateServer, logoutServer, manageBearerToken, openMcpAuthPanel, openMcpPanel, openMcpSetup } from "./commands.ts";
-import { cloneMcpConfig, loadMcpConfig, writeProjectServerDisabledOverride } from "./config.ts";
-import { buildProxyDescription, createDirectToolExecutor, getMissingConfiguredDirectToolServers, prepareDirectToolArguments, resolveDirectTools } from "./direct-tools.ts";
-import { flushMetadataCache, initializeMcp, updateStatusBar } from "./init.ts";
+import { cloneMcpConfig, discoverConfiguredClaudePluginSkills, getPiGlobalConfigPath, getProjectConfigPath, loadMcpConfig, resolveConfiguredClaudePluginMcp, writeProjectServerDisabledOverride, writeSharedServerEntry } from "./config.ts";
+import { buildProxyDescription, getMissingConfiguredDirectToolServers, prepareDirectToolArguments, resolveDirectTools } from "./direct-tool-surface.ts";
 import { isServerInActiveFailureBackoff } from "./failure-backoff.ts";
-import { loadMetadataCache, parseDirectToolSelectors, type MetadataCache } from "./metadata-cache.ts";
+import { computeServerHash, isServerCacheValid, loadMetadataCache, parseDirectToolSelectors, type MetadataCache } from "./metadata-cache.ts";
 import { createPromptCommand, resolveCachedPrompts } from "./prompts.ts";
 import { logger } from "./logger.ts";
-import { executeAuthComplete, executeAuthStart, executeCall, executeConnect, executeDescribe, executeInstructions, executeList, executeSearch, executeStatus, executeUiMessages } from "./proxy-modes.ts";
 import { formatTerminalError, getConfigPathFromArgv, normalizeDirectToolInputSchema, truncateAtWord } from "./utils.ts";
-import { createOAuthRuntime, shutdownOAuth } from "./mcp-auth-flow.ts";
 import { createMcpDirectToolCallRenderer, createMcpProxyToolCallRenderer, createMcpScriptToolCallRenderer, createMcpToolResultRenderer, resolveMcpToolRenderOptions } from "./tool-result-renderer.ts";
 import { toolErrorOverride } from "./error-signal.ts";
 import { createMcpRuntimeOwner, createOwnedUi, isAbortError, type McpRuntimeOwner } from "./runtime-owner.ts";
 import { publishMcpStatusShutdown } from "./mcp-status.ts";
-import { runMcpScript } from "./mcp-code.ts";
-import { cleanupMaterializedBinaryResources } from "./tool-registrar.ts";
 import { syncNamespaceProxyTools } from "./namespace-tools.ts";
+import { restoreSessionApprovalState } from "./session-approvals.ts";
+import { createRetryableLoader } from "./lazy-loader.ts";
 
 export type { McpAdapterOptions } from "./types.ts";
 export type { ServerEntry } from "./types.ts";
@@ -45,6 +42,14 @@ export {
   type McpToolApprovalRequest,
 } from "./types.ts";
 
+const loadCoreRuntime = createRetryableLoader(() => import("./init.ts"));
+const loadOAuthRuntime = createRetryableLoader(() => import("./mcp-auth-flow.ts"));
+const loadProxyModes = createRetryableLoader(() => import("./proxy-modes.ts"));
+const loadDirectExecution = createRetryableLoader(() => import("./direct-tools.ts"));
+const loadCommands = createRetryableLoader(() => import("./commands.ts"));
+const loadCodeMode = createRetryableLoader(() => import("./mcp-code.ts"));
+const loadInstallParsing = createRetryableLoader(() => import("./mcp-install.ts"));
+
 const INIT_WAIT_TIMEOUT_MS = 30_000;
 const INIT_FAILURE_MESSAGE_MAX_CHARS = 1_000;
 const INIT_WAIT_TIMED_OUT: unique symbol = Symbol("init-wait-timed-out");
@@ -91,6 +96,24 @@ export interface McpRuntimeSnapshotRequest {
 const runtimeRegistrars = new WeakMap<ExtensionAPI, (name: string, definition: ServerEntry) => McpServerRegistration>();
 const runtimeSnapshotters = new WeakMap<ExtensionAPI, (name: string) => McpRuntimeServerSnapshot>();
 
+function resolveProgrammaticClaudePluginPath(path: string, cwd: string): string {
+  if (path === "~") return resolve(process.env.HOME ?? "", ".");
+  if (path.startsWith("~/")) return resolve(process.env.HOME ?? "", path.slice(2));
+  return resolve(cwd, path);
+}
+
+function normalizeProgrammaticConfig(config: McpConfig): McpConfig {
+  if (!config.claudePlugins) return config;
+  const cwd = process.cwd();
+  return {
+    ...config,
+    claudePlugins: config.claudePlugins.map(plugin => ({
+      ...plugin,
+      path: resolveProgrammaticClaudePluginPath(plugin.path, cwd),
+    })),
+  };
+}
+
 async function awaitWithTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | typeof INIT_WAIT_TIMED_OUT> {
   let timer: ReturnType<typeof setTimeout> | undefined;
   try {
@@ -135,10 +158,20 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
   const programmaticConfig = sessionConfig !== undefined;
   let state: McpExtensionState | null = null;
   let initPromise: Promise<McpExtensionState> | null = null;
+  let initStartedPromise: Promise<void> | null = null;
   let currentOwner: McpRuntimeOwner | null = null;
   let currentOAuthRuntime: McpOAuthRuntime | null = null;
   let lifecycleGeneration = 0;
   let retainedInitFailure: string | null = null;
+  let finalizationGuard: (() => void) | null = null;
+  let finalizationRegistrations: Set<string> | null = null;
+
+  function callReentrant<T>(callback: () => T): T {
+    finalizationGuard?.();
+    const result = callback();
+    finalizationGuard?.();
+    return result;
+  }
 
   function retainInitFailure(error: unknown): string {
     const message = truncateAtWord(formatTerminalError(error), INIT_FAILURE_MESSAGE_MAX_CHARS);
@@ -164,23 +197,70 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     return true;
   }
 
+  interface RuntimeGuard {
+    generation: number;
+    owner: McpRuntimeOwner | null;
+    state: McpExtensionState | null;
+  }
+
+  function captureRuntimeGuard(expectedState: McpExtensionState | null = state): RuntimeGuard {
+    return { generation: lifecycleGeneration, owner: currentOwner, state: expectedState };
+  }
+
+  function assertRuntimeGuard(guard: RuntimeGuard): void {
+    guard.owner?.throwIfInactive();
+    if (
+      lifecycleGeneration !== guard.generation
+      || currentOwner !== guard.owner
+      || state !== guard.state
+    ) {
+      throw guard.owner?.signal.reason ?? new Error("MCP operation belongs to a stale session");
+    }
+  }
+
+  function isRuntimeGuardStale(guard: RuntimeGuard): boolean {
+    return guard.owner?.isActive() === false
+      || lifecycleGeneration !== guard.generation
+      || currentOwner !== guard.owner
+      || state !== guard.state;
+  }
+
+  async function loadForRuntime<T>(loader: () => Promise<T>, guard: RuntimeGuard): Promise<T> {
+    const loaded = await loader();
+    assertRuntimeGuard(guard);
+    return loaded;
+  }
+
+  function createCommandContext(ctx: ExtensionContext, owner: McpRuntimeOwner | null): ExtensionContext {
+    const commandCtx = Object.create(ctx) as ExtensionContext;
+    const hasUI = ctx.hasUI;
+    Object.defineProperties(commandCtx, {
+      hasUI: { value: hasUI, enumerable: true },
+      ui: {
+        value: hasUI ? owner ? createOwnedUi(ctx.ui, owner) : ctx.ui : undefined,
+        enumerable: true,
+      },
+      signal: { value: owner?.signal ?? ctx.signal, enumerable: true },
+    });
+    return commandCtx;
+  }
+
   function startGatewayRetryInitialization(ctx: ExtensionContext): void {
     const generation = ++lifecycleGeneration;
     const owner = createMcpRuntimeOwner();
-    const oauthRuntime = createOAuthRuntime(owner.signal);
     currentOwner = owner;
-    currentOAuthRuntime = oauthRuntime;
+    currentOAuthRuntime = null;
     state = null;
-    startInitialization(ctx, owner, oauthRuntime, generation, "stale_gateway_retry_initialization");
+    startInitialization(ctx, owner, generation, "stale_gateway_retry_initialization");
   }
 
-  async function shutdownState(currentState: McpExtensionState | null, reason: string): Promise<void> {
+  async function shutdownState(currentState: McpExtensionState | null, reason: string, publishStatus = true): Promise<void> {
     if (!currentState) {
-      publishMcpStatusShutdown(pi.events);
+      if (publishStatus) publishMcpStatusShutdown(pi.events);
       return;
     }
 
-    publishMcpStatusShutdown(currentState.statusEvents);
+    if (publishStatus) publishMcpStatusShutdown(currentState.statusEvents);
 
     if (currentState.uiServer) {
       currentState.uiServer.close(reason);
@@ -189,6 +269,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
 
     let flushError: unknown;
     try {
+      const { flushMetadataCache } = await loadCoreRuntime();
       flushMetadataCache(currentState);
     } catch (error) {
       flushError = error;
@@ -213,19 +294,54 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     }
   }
 
+  function restoreCurrentSessionApprovals(targetState: McpExtensionState): void {
+    const sessionManager = targetState.sessionManager;
+    if (!sessionManager) return;
+
+    let branch: readonly unknown[] = [];
+    try {
+      branch = sessionManager.getBranch();
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      logger.debug(`MCP: could not read the active session branch for approval restore: ${detail}`);
+    }
+    restoreSessionApprovalState(targetState, branch);
+  }
+
   const earlyConfigPath = programmaticConfig
     ? undefined
     : options.configPath ?? getConfigPathFromArgv();
   const earlyConfig = programmaticConfig
-    ? cloneMcpConfig(sessionConfig)
+    ? resolveConfiguredClaudePluginMcp(cloneMcpConfig(sessionConfig), process.cwd())
     : loadMcpConfig(earlyConfigPath);
   const earlyCache = loadMetadataCache();
   const envRaw = process.env.MCP_DIRECT_TOOLS;
   const envDirectToolOverride = parseEnvDirectToolOverride(envRaw);
   const namespaceEnvOverride = resolveNamespaceEnvOverride(envRaw, envDirectToolOverride);
+  const enabledEarlyServers = Object.entries(earlyConfig.mcpServers)
+    .filter(([, definition]) => !isServerDisabled(definition));
+  const hasStartupServer = enabledEarlyServers.some(([, definition]) =>
+    definition.lifecycle === "eager" || definition.lifecycle === "keep-alive");
+  const hasUsableCachedMetadata = earlyCache !== null && enabledEarlyServers.every(([serverName, definition]) => {
+    const entry = earlyCache.servers[serverName];
+    return entry !== undefined && isServerCacheValid(entry, definition);
+  });
+  const hasColdEnvironmentDirectTools = envRaw !== undefined && envRaw !== "__none__"
+    && getMissingConfiguredDirectToolServers(earlyConfig, earlyCache, envDirectToolOverride).length > 0;
+  const deferSessionRuntime = !hasStartupServer && hasUsableCachedMetadata && !hasColdEnvironmentDirectTools;
   const registeredDirectTools = new Map<string, string>();
+  const registeredDirectToolServers = new Map<string, string>();
+  const registeredDirectToolVersions = new Map<string, number>();
+  // Overlapping connect results consume each server's discovery names once.
+  // Removal clears the record so stale/fallback reactivation is reportable.
+  const reportedDirectToolNamesByServer = new Map<string, Set<string>>();
   const registeredNamespaceProxyTools = new Set<string>();
   const fallbackDeactivatedTools = new Set<string>();
+  // directTools: "search" — registered inactive, activated by mcp({ search }).
+  const lazyDirectTools = new Set<string>();
+  // The lazy tools a search has activated; every other lazy tool is held out
+  // of the active set. Per process: nothing here survives a restart.
+  const searchActivatedTools = new Set<string>();
   const toolRenderOptions = resolveMcpToolRenderOptions(earlyConfig.settings);
   const toolRenderShell = toolRenderOptions.resultRendering === "compact" ? "self" : "default";
   const renderMcpToolResult = createMcpToolResultRenderer(toolRenderOptions);
@@ -265,11 +381,23 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       resourceUri: spec.resourceUri,
       uiResourceUri: spec.uiResourceUri,
       uiStreamMode: spec.uiStreamMode,
+      // A mode-only change (search ↔ eager) must re-register, or the tool
+      // keeps the activation behavior of the mode it was registered under.
+      lazy: spec.lazy === true,
     });
   }
 
+  function forgetReportedDirectToolName(serverName: string | undefined, toolName: string): void {
+    if (!serverName) return;
+    const reportedNames = reportedDirectToolNamesByServer.get(serverName);
+    if (!reportedNames) return;
+    reportedNames.delete(toolName);
+    if (reportedNames.size === 0) reportedDirectToolNamesByServer.delete(serverName);
+  }
+
   function registerDirectTool(spec: DirectToolSpec, config: McpConfig): void {
-    (pi.registerTool as (tool: unknown) => unknown)({
+    finalizationRegistrations?.add(spec.prefixedName);
+    callReentrant(() => (pi.registerTool as (tool: unknown) => unknown)({
       name: spec.prefixedName,
       label: `MCP: ${spec.originalName}`,
       description: spec.description || "(no description)",
@@ -278,11 +406,69 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       ...(config.settings?.strictDirectToolArguments === true
         ? { prepareArguments: (args: unknown) => prepareDirectToolArguments(spec.inputSchema, args) }
         : {}),
-      execute: createDirectToolExecutor(() => state, () => initPromise, spec),
+      async execute(toolCallId: string, params: Record<string, unknown>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined, ctx: ExtensionContext) {
+        let executor: ReturnType<(typeof import("./direct-tools.ts"))["createDirectToolExecutor"]>;
+        let guard: RuntimeGuard | undefined;
+        try {
+          const targetState = await ensureSessionRuntime(ctx);
+          if (!targetState) throw new Error("MCP not initialized");
+          guard = captureRuntimeGuard(targetState);
+          const executionGuard = guard;
+          const { createDirectToolExecutor } = await loadForRuntime(loadDirectExecution, executionGuard);
+          executor = createDirectToolExecutor(() => executionGuard.state, () => initPromise, spec);
+        } catch (error) {
+          if (guard && (isRuntimeGuardStale(guard) || (guard.owner && isOwnerAbortError(error, guard.owner)))) throw error;
+          const message = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{ type: "text" as const, text: `MCP initialization failed for ${spec.serverName}: ${message}` }],
+            details: { error: "init_failed", server: spec.serverName, message },
+          };
+        }
+        if (!guard) throw new Error("MCP runtime guard unavailable");
+        assertRuntimeGuard(guard);
+        return executor(toolCallId, params, signal, onUpdate, ctx);
+      },
       renderShell: toolRenderShell,
       renderCall: createMcpDirectToolCallRenderer(spec.prefixedName, toolRenderOptions),
       renderResult: renderMcpToolResult,
-    });
+    }));
+  }
+
+  // Pi registers a tool active. A lazy tool must not stay that way: hold every
+  // lazy tool that search has not activated out of the active set. Safe to call
+  // repeatedly; a no-op until Pi's action methods are available.
+  function holdLazyToolsInactive(): void {
+    if (lazyDirectTools.size === 0) return;
+    const activeTools = getActiveToolsIfReady();
+    if (!activeTools) return;
+    const next = activeTools.filter((name) => !lazyDirectTools.has(name) || searchActivatedTools.has(name));
+    if (next.length !== activeTools.length) pi.setActiveTools(next);
+  }
+
+  /**
+   * Activate the lazy direct tools a search matched, additively. This is the
+   * one place a search-mode tool becomes active; nothing is ever deactivated
+   * here. Returns the names that actually changed state so the result can
+   * report only real additions.
+   */
+  function activateSearchMatches(matches: ReadonlyArray<{ server: string; tool: string }>): string[] {
+    const activeTools = getActiveToolsIfReady();
+    if (!activeTools) return [];
+    const activeSet = new Set(activeTools);
+    // executeSearch reports ToolMetadata.name, which is the prefixed name a
+    // direct tool is registered under — the same key the lazy set holds.
+    const added: string[] = [];
+    for (const match of matches) {
+      const name = match.tool;
+      if (!lazyDirectTools.has(name) || registeredDirectToolServers.get(name) !== match.server) continue;
+      if (activeSet.has(name) || added.includes(name)) continue;
+      added.push(name);
+    }
+    if (added.length > 0) {
+      pi.setActiveTools([...activeTools, ...added]);
+      for (const name of added) searchActivatedTools.add(name);
+    }
+    return added;
   }
 
   function activeFailureServers(): Set<string> {
@@ -299,7 +485,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
 
   function getActiveToolsIfReady(): string[] | undefined {
     try {
-      return pi.getActiveTools?.();
+      return callReentrant(() => pi.getActiveTools?.());
     } catch (error) {
       if (error instanceof Error
         && error.message.includes("Action methods cannot be called during extension loading")) return undefined;
@@ -310,7 +496,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
   function deactivateTools(toolNames: string[]): string[] {
     if (toolNames.length === 0) return [];
     const unregisterTool = (pi as ExtensionAPI & { unregisterTool?: (name: string) => boolean }).unregisterTool;
-    const unregistered = toolNames.filter((toolName) => unregisterTool?.(toolName) === true);
+    const unregistered = toolNames.filter((toolName) => callReentrant(() => unregisterTool?.(toolName)) === true);
     const fallbackNames = toolNames.filter((toolName) => !unregistered.includes(toolName));
     const remove = new Set(toolNames);
     const activeTools = getActiveToolsIfReady();
@@ -321,7 +507,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     const nextActiveTools = activeTools.filter((name) => !remove.has(name));
     if (nextActiveTools.length !== activeTools.length) {
       for (const toolName of fallbackNames) fallbackDeactivatedTools.add(toolName);
-      pi.setActiveTools(nextActiveTools);
+      callReentrant(() => pi.setActiveTools(nextActiveTools));
     }
     return unregistered;
   }
@@ -345,29 +531,53 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       const fingerprint = directToolFingerprint(spec);
       const previous = registeredDirectTools.get(spec.prefixedName);
       if (previous !== fingerprint) {
+        const previousServer = registeredDirectToolServers.get(spec.prefixedName);
         registerDirectTool(spec, config);
+        finalizationGuard?.();
         registeredDirectTools.set(spec.prefixedName, fingerprint);
-        if (fallbackDeactivatedTools.delete(spec.prefixedName)) {
+        registeredDirectToolServers.set(spec.prefixedName, spec.serverName);
+        registeredDirectToolVersions.set(spec.prefixedName, (registeredDirectToolVersions.get(spec.prefixedName) ?? 0) + 1);
+        if (previousServer !== spec.serverName) {
+          forgetReportedDirectToolName(previousServer, spec.prefixedName);
+        }
+        if (fallbackDeactivatedTools.delete(spec.prefixedName) && !spec.lazy) {
           const activeTools = getActiveToolsIfReady();
           if (activeTools && !activeTools.includes(spec.prefixedName)) {
-            pi.setActiveTools([...activeTools, spec.prefixedName]);
+            callReentrant(() => pi.setActiveTools([...activeTools, spec.prefixedName]));
           }
         }
         (previous ? updated : added).push(spec.prefixedName);
       }
+      if (spec.lazy) {
+        // Search mode, whether first registered or flipped from eager (e.g. in
+        // the panel): held inactive below unless a search already activated it.
+        lazyDirectTools.add(spec.prefixedName);
+      } else if (lazyDirectTools.delete(spec.prefixedName)) {
+        // Search → eager: an eager direct tool is active by definition, so a
+        // tool that search never activated must be activated now. Pi does not
+        // re-activate a tool it already knows on re-registration.
+        searchActivatedTools.delete(spec.prefixedName);
+        const activeTools = getActiveToolsIfReady();
+        if (activeTools && !activeTools.includes(spec.prefixedName)) callReentrant(() => pi.setActiveTools([...activeTools, spec.prefixedName]));
+      }
     }
 
     for (const toolName of [...registeredDirectTools.keys()]) {
       if (nextNames.has(toolName)) continue;
+      const serverName = registeredDirectToolServers.get(toolName);
       registeredDirectTools.delete(toolName);
+      registeredDirectToolServers.delete(toolName);
+      forgetReportedDirectToolName(serverName, toolName);
+      if (lazyDirectTools.delete(toolName)) searchActivatedTools.delete(toolName);
       deactivated.push(toolName);
     }
 
     deactivateTools(deactivated);
+    holdLazyToolsInactive();
     return { specs, reservedDirectNames, activeDirectNames: nextNames, added, updated, deactivated };
   }
 
-  function applyDirectToolConfigChanges(changes: Map<string, true | string[] | false>): void {
+  function applyDirectToolConfigChanges(changes: Map<string, true | string[] | false | "search">): void {
     if (!state) return;
     for (const [serverName, value] of changes) {
       const definition = state.config.mcpServers[serverName];
@@ -376,18 +586,44 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     }
   }
 
+  function loadToolSurfaceCache(config: McpConfig): MetadataCache | null {
+    const cache = loadMetadataCache();
+    const currentState = state;
+    if (!currentState || !cache) return cache;
+    const servers = { ...cache.servers };
+    const connections = callReentrant(() => [...currentState.manager.getAllConnections()]);
+    for (const [serverName, connection] of connections) {
+      const definition = config.mcpServers[serverName];
+      const entry = servers[serverName];
+      if (connection.status !== "connected" || !entry || !definition || isServerDisabled(definition)) continue;
+      const configHash = computeServerHash(definition);
+      if (computeServerHash(connection.definition) !== configHash || entry.configHash !== configHash) continue;
+      const { ttlMs: _liveTtl, ...liveEntry } = entry;
+      servers[serverName] = liveEntry;
+    }
+    return { ...cache, servers };
+  }
+
   function syncToolSurface(ctx?: ExtensionContext): void {
     const config = state?.config ?? earlyConfig;
-    const cache = loadMetadataCache();
+    const cache = loadToolSurfaceCache(config);
     const result = syncDirectTools(config, cache);
+    if (state) {
+      const directToolCounts = state.directToolCounts ?? new Map<string, number>();
+      directToolCounts.clear();
+      for (const spec of result.specs) {
+        directToolCounts.set(spec.serverName, (directToolCounts.get(spec.serverName) ?? 0) + 1);
+      }
+      state.directToolCounts = directToolCounts;
+    }
     syncProxyTool(config, cache, result.specs);
     syncNamespaceTools(config, cache, result.reservedDirectNames, result.activeDirectNames);
     const changed = result.added.length + result.updated.length + result.deactivated.length;
     if (changed > 0 && ctx?.hasUI) {
-      ctx.ui.notify(
+      callReentrant(() => ctx.ui.notify(
         `MCP: direct tools refreshed (+${result.added.length}, ~${result.updated.length}, -${result.deactivated.length})`,
         "info",
-      );
+      ));
     }
   }
 
@@ -408,11 +644,19 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       pi,
       getState: () => state,
       getInitPromise: () => initPromise,
+      ensureRuntime: (ctx) => ensureSessionRuntime(ctx as ExtensionContext),
+      executeCall: async (...args) => {
+        const guard = captureRuntimeGuard(args[0]);
+        return (await loadForRuntime(loadProxyModes, guard)).executeCall(...args);
+      },
       getPiTools: () => pi.getAllTools(),
       renderOptions: toolRenderOptions,
       renderShell: toolRenderShell,
       renderResult: renderMcpToolResult,
+      guardReentrant: () => finalizationGuard?.(),
+      onToolRegistered: (name) => finalizationRegistrations?.add(name),
     });
+    finalizationGuard?.();
     for (const name of result.added) registeredNamespaceProxyTools.add(name);
     for (const name of result.deactivated) registeredNamespaceProxyTools.delete(name);
   }
@@ -425,13 +669,22 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         logger.debug(`MCP: prompt "${spec.originalName}" on ${spec.serverName} skipped; /${spec.commandName} is already registered`);
         continue;
       }
+      callReentrant(() => pi.registerCommand(spec.commandName, createPromptCommand(pi, () => state, spec, {
+        ensureState: (ctx) => ensureSessionRuntime(ctx as unknown as ExtensionContext),
+        lazyConnect: async (...args) => {
+          const guard = captureRuntimeGuard(args[0]);
+          return (await loadForRuntime(loadCoreRuntime, guard)).lazyConnect(...args);
+        },
+        isStateCurrent: (targetState) => state === targetState && currentOwner?.isActive() === true,
+      })));
       registeredPromptCommands.add(spec.commandName);
-      pi.registerCommand(spec.commandName, createPromptCommand(pi, () => state, spec));
     }
   }
 
   function syncPromptCommands(): void {
-    registerPromptCommands([...(state?.promptMetadata?.values() ?? [])].flat());
+    registerPromptCommands([...(state?.promptMetadata?.entries() ?? [])]
+      .filter(([name]) => !state?.provisionalInstalls?.has(name))
+      .flatMap(([, prompts]) => prompts));
   }
 
   registerPromptCommands(resolveCachedPrompts(earlyConfig));
@@ -457,7 +710,14 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       registeredState.config.mcpServers[name] = entry;
       attachRuntimeServerLifecycle(registeredState, name, entry);
       syncToolSurface();
-      updateStatusBar(registeredState);
+      const guard = captureRuntimeGuard(registeredState);
+      void loadForRuntime(loadCoreRuntime, guard)
+        .then(({ updateStatusBar }) => updateStatusBar(registeredState))
+        .catch((error) => {
+          if (!isAbortError(error, guard.owner?.signal)) {
+            logger.debug(`MCP: could not update status after runtime registration: ${formatTerminalError(error)}`);
+          }
+        });
     }
     let disposed = false;
     return {
@@ -469,9 +729,11 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         if (!currentState || currentState.config.mcpServers[name] !== entry) return;
         delete currentState.config.mcpServers[name];
         currentState.lifecycle.unregisterServer(name);
+        const guard = captureRuntimeGuard(currentState);
         await currentState.manager.close(name);
+        assertRuntimeGuard(guard);
         syncToolSurface();
-        updateStatusBar(currentState);
+        (await loadForRuntime(loadCoreRuntime, guard)).updateStatusBar(currentState);
       },
     };
   };
@@ -539,75 +801,178 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     type: "string",
   });
 
-  function startInitialization(ctx: ExtensionContext, owner: McpRuntimeOwner, oauthRuntime: McpOAuthRuntime, generation: number, staleReason: string): Promise<void> {
-    owner.addCleanup(() => cleanupMaterializedBinaryResources(owner.signal));
-    const promise = initializeMcp(pi, ctx, owner, {
-      ...(programmaticConfig || options.configPath !== undefined
-        ? {
-            ...(earlyConfigPath !== undefined ? { configPath: earlyConfigPath } : {}),
-            ...(sessionConfig !== undefined ? { config: sessionConfig } : {}),
-          }
-        : {}),
-      oauthRuntime,
+  function startInitialization(ctx: ExtensionContext, owner: McpRuntimeOwner, generation: number, staleReason: string): Promise<void> {
+    let oauthRuntime: McpOAuthRuntime | null = null;
+    let markStarted!: () => void;
+    initStartedPromise = new Promise<void>((resolve) => {
+      markStarted = resolve;
     });
-    initPromise = promise;
-
-    return promise.then(async (nextState) => {
+    let coreRuntime: Awaited<ReturnType<typeof loadCoreRuntime>> | null = null;
+    const initializationPromise = (async () => {
+      const guard = captureRuntimeGuard(null);
+      const [core, oauth] = await Promise.all([
+        loadCoreRuntime(),
+        loadOAuthRuntime(),
+      ]);
+      assertRuntimeGuard(guard);
+      if (generation !== guard.generation || guard.owner !== owner) {
+        throw owner.signal.reason ?? new Error("Stale MCP initialization");
+      }
+      coreRuntime = core;
+      assertRuntimeGuard(guard);
+      oauthRuntime = oauth.createOAuthRuntime(owner.signal);
+      try {
+        assertRuntimeGuard(guard);
+      } catch (error) {
+        await oauth.shutdownOAuth(oauthRuntime);
+        throw error;
+      }
+      currentOAuthRuntime = oauthRuntime;
+      assertRuntimeGuard(guard);
+      owner.addCleanup(async () => {
+        const { cleanupMaterializedBinaryResources } = await import("./tool-registrar.ts");
+        cleanupMaterializedBinaryResources(owner.signal);
+      });
+      assertRuntimeGuard(guard);
+      const initialization = core.initializeMcp(pi, ctx, owner, {
+        ...(programmaticConfig || options.configPath !== undefined
+          ? {
+              ...(earlyConfigPath !== undefined ? { configPath: earlyConfigPath } : {}),
+              ...(sessionConfig !== undefined ? { config: sessionConfig } : {}),
+            }
+          : {}),
+        oauthRuntime,
+      });
+      assertRuntimeGuard(guard);
+      markStarted();
+      return initialization;
+    })().catch((error) => {
+      markStarted();
+      throw error;
+    }).then((value) => value);
+    let promise: Promise<McpExtensionState>;
+    promise = initializationPromise.then(async (nextState) => {
       if (!owner.isActive() || generation !== lifecycleGeneration || initPromise !== promise) {
         try {
-          await shutdownState(nextState, staleReason);
+          await shutdownState(nextState, staleReason, false);
         } catch (error) {
           console.error(`MCP: failed to clean stale initialization state: ${formatTerminalError(error)}`);
         }
-        return;
+        throw owner.signal.reason ?? new Error("Stale MCP initialization completed");
       }
 
+      const guard = () => {
+        owner.throwIfInactive();
+        if (generation !== lifecycleGeneration || currentOwner !== owner || state !== nextState || initPromise !== promise) {
+          throw owner.signal.reason ?? new Error("Stale MCP initialization finalized");
+        }
+      };
+      const registeredDuringFinalization = new Set<string>();
+      let statusPublicationAttempted = false;
       state = nextState;
-      clearRetainedInitFailure();
-      for (const [name, { entry }] of runtimeServers) {
-        if (Object.hasOwn(nextState.config.mcpServers, name)) {
-          console.error(`MCP: runtime-registered server "${name}" now collides with a configured server; keeping the configured server`);
-          continue;
+      finalizationGuard = guard;
+      finalizationRegistrations = registeredDuringFinalization;
+      try {
+        guard();
+        // Re-read after asynchronous startup so navigation during initialization
+        // cannot restore a stale branch.
+        callReentrant(() => restoreCurrentSessionApprovals(nextState));
+        for (const [name, { entry }] of runtimeServers) {
+          guard();
+          if (Object.hasOwn(nextState.config.mcpServers, name)) {
+            console.error(`MCP: runtime-registered server "${name}" now collides with a configured server; keeping the configured server`);
+            continue;
+          }
+          nextState.config.mcpServers[name] = entry;
+          guard();
+          callReentrant(() => attachRuntimeServerLifecycle(nextState, name, entry));
         }
-        nextState.config.mcpServers[name] = entry;
-        attachRuntimeServerLifecycle(nextState, name, entry);
-      }
-      nextState.onToolMetadataUpdated = (_serverName, _reason) => {
-        if (state !== nextState || !owner.isActive()) return;
+        guard();
+        nextState.onToolMetadataUpdated = (_serverName, _reason) => {
+          if (state !== nextState || !owner.isActive()) return;
+          syncPromptCommands();
+          if (directToolsFrozen) {
+            logger.debug(`MCP: metadata update for ${_serverName} (${_reason}) skipped — directTools frozen`);
+            return;
+          }
+          syncToolSurface(ctx);
+        };
+        guard();
         syncPromptCommands();
-        if (directToolsFrozen) {
-          logger.debug(`MCP: metadata update for ${_serverName} (${_reason}) skipped — directTools frozen`);
-          return;
-        }
+        guard();
         syncToolSurface(ctx);
-      };
-      syncPromptCommands();
-      syncToolSurface(ctx);
-      // A connected snapshot is readiness-like external state. Publish it only
-      // after Pi's model-facing direct-tool surface reflects live metadata.
-      nextState.statusEvents = pi.events;
-      updateStatusBar(nextState);
-      initPromise = null;
-      if (earlyConfig.settings?.freezeDirectTools === true) {
-        directToolsFrozen = true;
-        logger.info("MCP: direct tools frozen after initial sync — metadata can refresh without rebuilding the active tool surface");
+        guard();
+        // A connected snapshot is readiness-like external state. Publish it only
+        // after Pi's model-facing direct-tool surface reflects live metadata.
+        nextState.statusEvents = pi.events;
+        guard();
+        if (!coreRuntime) throw new Error("MCP core runtime was not loaded");
+        const loadedCoreRuntime = coreRuntime;
+        statusPublicationAttempted = true;
+        callReentrant(() => loadedCoreRuntime.updateStatusBar(nextState));
+        guard();
+        clearRetainedInitFailure();
+        guard();
+        if (earlyConfig.settings?.freezeDirectTools === true) {
+          directToolsFrozen = true;
+          logger.info("MCP: direct tools frozen after initial sync — metadata can refresh without rebuilding the active tool surface");
+        }
+        guard();
+        initPromise = null;
+        initStartedPromise = null;
+        return nextState;
+      } catch (error) {
+        if (state === nextState) state = null;
+        finalizationGuard = null;
+        finalizationRegistrations = null;
+        if (registeredDuringFinalization.size > 0) {
+          deactivateTools([...registeredDuringFinalization]);
+          for (const name of registeredDuringFinalization) {
+            registeredDirectTools.delete(name);
+            registeredDirectToolServers.delete(name);
+            registeredDirectToolVersions.delete(name);
+            registeredNamespaceProxyTools.delete(name);
+          }
+          if (registeredDuringFinalization.has("mcp")) {
+            proxyToolRegistered = false;
+            proxyToolDescription = null;
+          }
+        }
+        if (statusPublicationAttempted && generation === lifecycleGeneration && currentOwner === owner) {
+          publishMcpStatusShutdown(nextState.statusEvents);
+        }
+        // A synchronous lifecycle replacement captures published state and owns
+        // its cleanup. Only clean here when no replacement took ownership.
+        if (generation === lifecycleGeneration && currentOwner === owner) {
+          try {
+            await shutdownState(nextState, staleReason, false);
+          } catch (cleanupError) {
+            console.error(`MCP: failed to clean interrupted initialization state: ${formatTerminalError(cleanupError)}`);
+          }
+        }
+        throw error;
+      } finally {
+        if (finalizationGuard === guard) finalizationGuard = null;
+        if (finalizationRegistrations === registeredDuringFinalization) finalizationRegistrations = null;
       }
-    }).catch(async err => {
+    });
+    initPromise = promise;
+
+    return promise.then(() => undefined).catch(async err => {
       if (!owner.isActive() || generation !== lifecycleGeneration) {
         return;
       }
-      if (initPromise !== promise && initPromise !== null) {
-        return;
-      }
+      if (initPromise !== promise) return;
       const message = retainInitFailure(err);
       console.error(`MCP initialization failed: ${message}`);
       initPromise = null;
+      initStartedPromise = null;
       if (state) return;
 
       try {
         await Promise.all([
           owner.stop("MCP initialization failed"),
-          shutdownOAuth(oauthRuntime),
+          oauthRuntime ? loadOAuthRuntime().then(({ shutdownOAuth }) => shutdownOAuth(oauthRuntime!)) : Promise.resolve(),
         ]);
       } catch (error) {
         console.error(`MCP: failed to clean rejected initialization: ${formatTerminalError(error)}`);
@@ -615,19 +980,26 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     });
   }
 
+  function ensureSessionRuntime(ctx: ExtensionContext): Promise<McpExtensionState | null> {
+    if (state) return Promise.resolve(state);
+    if (initPromise) return initPromise;
+    const owner = currentOwner?.isActive() ? currentOwner : createMcpRuntimeOwner();
+    if (owner !== currentOwner) currentOwner = owner;
+    const generation = currentOwner === owner && lifecycleGeneration > 0
+      ? lifecycleGeneration
+      : ++lifecycleGeneration;
+    startInitialization(ctx, owner, generation, "stale_first_operation_initialization");
+    return initPromise!;
+  }
+
   function startLoadTimeInitialization(): void {
-    const hasStartupServer = Object.values(earlyConfig.mcpServers).some((definition) => {
-      if (definition.disabled === true) return false;
-      return definition.lifecycle === "eager" || definition.lifecycle === "keep-alive";
-    });
     if (!hasStartupServer) return;
     setImmediate(() => {
       if (lifecycleGeneration !== 0 || state || initPromise) return;
       const generation = ++lifecycleGeneration;
       const owner = createMcpRuntimeOwner();
-      const oauthRuntime = createOAuthRuntime(owner.signal);
       currentOwner = owner;
-      currentOAuthRuntime = oauthRuntime;
+      currentOAuthRuntime = null;
       startInitialization({
         mode: "print",
         hasUI: false,
@@ -635,21 +1007,29 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         model: undefined,
         modelRegistry: undefined,
         signal: undefined,
-      } as unknown as ExtensionContext, owner, oauthRuntime, generation, "stale_load_time_initialization");
+      } as unknown as ExtensionContext, owner, generation, "stale_load_time_initialization");
     });
   }
 
+  pi.on("resources_discover", (event) => {
+    const resourceConfig = programmaticConfig
+      ? cloneMcpConfig(sessionConfig)
+      : loadMcpConfig(earlyConfigPath, event.cwd);
+    const skillPaths = discoverConfiguredClaudePluginSkills(resourceConfig, event.cwd);
+    return skillPaths.length > 0 ? { skillPaths } : undefined;
+  });
+
   pi.on("session_start", async (_event, ctx) => {
     const generation = ++lifecycleGeneration;
     const previousState = state;
     const previousOwner = currentOwner;
     const previousOAuthRuntime = currentOAuthRuntime;
     const owner = createMcpRuntimeOwner();
-    const oauthRuntime = createOAuthRuntime(owner.signal);
     currentOwner = owner;
-    currentOAuthRuntime = oauthRuntime;
+    currentOAuthRuntime = null;
     state = null;
     initPromise = null;
+    initStartedPromise = null;
     clearRetainedInitFailure();
 
     // Abort synchronously before awaiting cleanup so old callbacks and startup
@@ -659,15 +1039,22 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       await Promise.all([
         stopPrevious,
         shutdownState(previousState, "session_restart"),
-        previousOAuthRuntime ? shutdownOAuth(previousOAuthRuntime) : Promise.resolve(),
+        previousOAuthRuntime ? loadOAuthRuntime().then(({ shutdownOAuth }) => shutdownOAuth(previousOAuthRuntime)) : Promise.resolve(),
       ]);
     } catch (error) {
       console.error(`MCP: failed to shut down previous session state: ${formatTerminalError(error)}`);
     }
 
     if (generation !== lifecycleGeneration || !owner.isActive()) return;
+    if (state) return;
+
+    if (!initPromise) {
+      if (deferSessionRuntime) return;
+      startInitialization(ctx, owner, generation, "stale_session_start");
+    }
 
-    const initialization = startInitialization(ctx, owner, oauthRuntime, generation, "stale_session_start");
+    const initialization = initPromise as Promise<McpExtensionState> | null;
+    const initializationStarted = initStartedPromise as Promise<void> | null;
     if (envRaw !== undefined && envRaw !== "__none__") {
       const missingEnvDirectTools = getMissingConfiguredDirectToolServers(
         earlyConfig,
@@ -675,9 +1062,27 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         envDirectToolOverride,
       );
       if (missingEnvDirectTools.length > 0) {
-        await initialization;
+        await initialization?.then(() => undefined, () => undefined);
+        return;
       }
     }
+    await initializationStarted;
+  });
+
+  pi.on("session_tree", (_event, ctx) => {
+    const currentState = state;
+    const owner = currentOwner;
+    if (!currentState || !owner?.isActive() || !currentState.sessionManager) return;
+
+    let sessionManager: ExtensionContext["sessionManager"] | undefined;
+    try {
+      sessionManager = ctx.sessionManager;
+    } catch {
+      return;
+    }
+    if (sessionManager !== currentState.sessionManager) return;
+
+    restoreCurrentSessionApprovals(currentState);
   });
 
   pi.on("input", async () => {
@@ -712,6 +1117,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     currentOAuthRuntime = null;
     state = null;
     initPromise = null;
+    initStartedPromise = null;
     clearRetainedInitFailure();
 
     // Abort before awaiting cleanup so delayed initialization cannot touch stale
@@ -721,7 +1127,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       await Promise.all([
         stopOwner,
         shutdownState(currentState, "session_shutdown"),
-        oauthRuntime ? shutdownOAuth(oauthRuntime) : Promise.resolve(),
+        oauthRuntime ? loadOAuthRuntime().then(({ shutdownOAuth }) => shutdownOAuth(oauthRuntime)) : Promise.resolve(),
       ]);
     } catch (error) {
       console.error(`MCP: session shutdown cleanup failed: ${formatTerminalError(error)}`);
@@ -755,9 +1161,9 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       if (
         (subcommand !== "reconnect" && subcommand !== "logout" && subcommand !== "disable" && subcommand !== "enable" && subcommand !== "token")
         || argumentPrefix === undefined
-        || !state
       ) return null;
 
+      const completionConfig = state?.config ?? earlyConfig;
       if (subcommand === "token") {
         const tokenMatch = argumentPrefix.trimStart().match(/^(set|remove|status)\s+(.*)$/);
         if (!tokenMatch) {
@@ -768,35 +1174,27 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         }
         const action = tokenMatch[1] ?? "";
         const serverPrefix = tokenMatch[2] ?? "";
-        const servers = Object.keys(state.config.mcpServers)
+        const servers = Object.keys(completionConfig.mcpServers)
           .filter(serverName => serverName.startsWith(serverPrefix.trimStart()))
           .map(serverName => ({ value: `token ${action} ${serverName}`, label: serverName }));
         return servers.length > 0 ? servers : null;
       }
 
-      const servers = Object.keys(state.config.mcpServers)
+      const servers = Object.keys(completionConfig.mcpServers)
         .filter((serverName) => serverName.startsWith(argumentPrefix.trimStart()))
         .map((serverName) => ({ value: `${subcommand} ${serverName}`, label: serverName }));
       return servers.length > 0 ? servers : null;
     },
     handler: async (args, ctx) => {
-      const commandOwner = currentOwner;
+      let commandOwner = currentOwner;
       const commandReload = typeof ctx.reload === "function" ? ctx.reload.bind(ctx) : async () => {};
-      const commandHasUI = ctx.hasUI;
-      const commandCtx = {
-        hasUI: commandHasUI,
-        ui: commandHasUI
-          ? commandOwner ? createOwnedUi(ctx.ui, commandOwner) : ctx.ui
-          : undefined,
-        cwd: ctx.cwd,
-        mode: ctx.mode,
-        signal: commandOwner?.signal ?? ctx.signal,
-      } as unknown as ExtensionContext;
-      if (!state && initPromise) {
+      let commandCtx = createCommandContext(ctx as unknown as ExtensionContext, commandOwner);
+      if (!state) {
         try {
-          const initialized = await initPromise;
+          state = await ensureSessionRuntime(ctx as unknown as ExtensionContext);
+          commandOwner = currentOwner;
+          commandCtx = createCommandContext(ctx as unknown as ExtensionContext, commandOwner);
           commandOwner?.throwIfInactive();
-          state = initialized;
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
           if (commandCtx.hasUI) commandCtx.ui?.notify(`MCP initialization failed: ${message}`, "error");
@@ -808,6 +1206,16 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         return;
       }
 
+      const commandGuard = captureRuntimeGuard(state);
+      let commands: Awaited<ReturnType<typeof loadCommands>>;
+      try {
+        commands = await loadForRuntime(loadCommands, commandGuard);
+      } catch (error) {
+        if (commandGuard.owner && isOwnerAbortError(error, commandGuard.owner)) return;
+        const message = error instanceof Error ? error.message : String(error);
+        if (commandCtx.hasUI) commandCtx.ui?.notify(`MCP initialization failed: ${message}`, "error");
+        return;
+      }
       const parts = args?.trim()?.split(/\s+/) ?? [];
       const subcommand = parts[0] ?? "";
       const targetServer = parts[1];
@@ -816,13 +1224,13 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       switch (subcommand) {
         case "reconnect":
           commandOwner?.throwIfInactive();
-          await reconnectServers(state, commandCtx, targetServer);
+          await commands.reconnectServers(state, commandCtx, targetServer);
           break;
         case "tools":
-          await showTools(state, commandCtx);
+          await commands.showTools(state, commandCtx);
           break;
         case "prompts":
-          await showPrompts(state, commandCtx);
+          await commands.showPrompts(state, commandCtx);
           break;
         case "setup": {
           commandOwner?.throwIfInactive();
@@ -830,7 +1238,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
             commandCtx.ui?.notify("MCP setup is unavailable when config is supplied by createMcpAdapter().", "info");
             break;
           }
-          const result = await openMcpSetup(state, pi, commandCtx, earlyConfigPath, "setup");
+          const result = await commands.openMcpSetup(state, pi, commandCtx, earlyConfigPath, "setup");
           if (result?.configChanged) {
             commandOwner?.throwIfInactive();
             await commandReload();
@@ -845,7 +1253,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
             return;
           }
           commandOwner?.throwIfInactive();
-          await logoutServer(serverName, state, commandCtx);
+          await commands.logoutServer(serverName, state, commandCtx);
           break;
         }
         case "token": {
@@ -860,7 +1268,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
             return;
           }
           commandOwner?.throwIfInactive();
-          await manageBearerToken(action, serverName, state, commandCtx);
+          await commands.manageBearerToken(action, serverName, state, commandCtx);
           break;
         }
         case "disable":
@@ -894,10 +1302,10 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
             commandOwner?.throwIfInactive();
             if (programmaticConfig) {
               commandCtx.ui?.notify("MCP status is shown from the in-memory SDK config; configuration discovery is unavailable.", "info");
-              await showStatus(state, commandCtx);
+              await commands.showStatus(state, commandCtx);
               break;
             }
-            const result = await openMcpPanel(state, pi, commandCtx, earlyConfigPath, (changes) => {
+            const result = await commands.openMcpPanel(state, pi, commandCtx, earlyConfigPath, (changes) => {
               applyDirectToolConfigChanges(changes);
               syncToolSurface(commandCtx);
             });
@@ -907,7 +1315,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
               return;
             }
           } else {
-            await showStatus(state, commandCtx);
+            await commands.showStatus(state, commandCtx);
           }
           break;
       }
@@ -919,27 +1327,19 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
   pi.registerCommand("mcp-auth", {
     description: "Authenticate with an MCP server (OAuth)",
     handler: async (args, ctx) => {
-      const commandOwner = currentOwner;
-      const commandHasUI = ctx.hasUI;
-      const commandCtx = {
-        hasUI: commandHasUI,
-        ui: commandHasUI
-          ? commandOwner ? createOwnedUi(ctx.ui, commandOwner) : ctx.ui
-          : undefined,
-        cwd: ctx.cwd,
-        mode: ctx.mode,
-        signal: commandOwner?.signal ?? ctx.signal,
-      } as unknown as ExtensionContext;
+      let commandOwner = currentOwner;
+      let commandCtx = createCommandContext(ctx as unknown as ExtensionContext, commandOwner);
       const serverName = args?.trim();
       if (!serverName && !commandCtx.hasUI) {
         return;
       }
 
-      if (!state && initPromise) {
+      if (!state) {
         try {
-          const initialized = await initPromise;
+          state = await ensureSessionRuntime(ctx as unknown as ExtensionContext);
+          commandOwner = currentOwner;
+          commandCtx = createCommandContext(ctx as unknown as ExtensionContext, commandOwner);
           commandOwner?.throwIfInactive();
-          state = initialized;
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
           if (commandCtx.hasUI) commandCtx.ui?.notify(`MCP initialization failed: ${message}`, "error");
@@ -951,19 +1351,29 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         return;
       }
 
+      const commandGuard = captureRuntimeGuard(state);
+      let commands: Awaited<ReturnType<typeof loadCommands>>;
+      try {
+        commands = await loadForRuntime(loadCommands, commandGuard);
+      } catch (error) {
+        if (commandGuard.owner && isOwnerAbortError(error, commandGuard.owner)) return;
+        const message = error instanceof Error ? error.message : String(error);
+        if (commandCtx.hasUI) commandCtx.ui?.notify(`MCP initialization failed: ${message}`, "error");
+        return;
+      }
       if (!serverName) {
         if (programmaticConfig) {
           commandCtx.ui?.notify("Use /mcp-auth <server> to authenticate a server from the in-memory SDK config.", "info");
           return;
         }
-        await openMcpAuthPanel(state, pi, commandCtx, earlyConfigPath);
+        await commands.openMcpAuthPanel(state, pi, commandCtx, earlyConfigPath);
         return;
       }
 
-      const result = await authenticateServer(serverName, state.config, commandCtx, commandCtx.signal, state.oauthRuntime);
+      const result = await commands.authenticateServer(serverName, state.config, commandCtx, commandCtx.signal, state.oauthRuntime);
       if (result.ok) {
         commandOwner?.throwIfInactive();
-        await reconnectServer(state, commandCtx, serverName);
+        await commands.reconnectServer(state, commandCtx, serverName);
       }
     },
   });
@@ -980,17 +1390,18 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       }),
       renderCall: createMcpScriptToolCallRenderer(toolRenderOptions),
       renderResult: renderMcpToolResult,
-      async execute(_toolCallId: string, params: { code: string; timeoutMs?: number }, signal: AbortSignal | undefined) {
-        const executeOwner = currentOwner;
-        if (!state && initPromise) {
+      async execute(_toolCallId: string, params: { code: string; timeoutMs?: number }, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: ExtensionContext) {
+        let executeOwner = currentOwner;
+        if (!state) {
           try {
-            const initialized = await awaitWithTimeout(initPromise, INIT_WAIT_TIMEOUT_MS);
+            const initialized = await awaitWithTimeout(ensureSessionRuntime(ctx), INIT_WAIT_TIMEOUT_MS);
             if (initialized === INIT_WAIT_TIMED_OUT) {
               return {
                 content: [{ type: "text" as const, text: "MCP initialization is still in progress. Try again shortly." }],
                 details: { mode: "script", error: "init_timeout", timeoutMs: INIT_WAIT_TIMEOUT_MS },
               };
             }
+            executeOwner = currentOwner;
             executeOwner?.throwIfInactive();
             state = initialized;
           } catch (error) {
@@ -1011,17 +1422,235 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
           };
         }
         executeOwner?.throwIfInactive();
-        return runMcpScript(state, params.code, params.timeoutMs, getPiTools, signal);
+        const scriptState = state;
+        const scriptGuard = captureRuntimeGuard(scriptState);
+        const codeMode = await loadForRuntime(loadCodeMode, scriptGuard);
+        return codeMode.runMcpScript(scriptState, params.code, params.timeoutMs, getPiTools, signal);
       },
     });
   }
 
+  async function connectAndReport(targetState: McpExtensionState, serverName: string, signal?: AbortSignal, ctx?: ExtensionContext) {
+    const guard = captureRuntimeGuard(targetState);
+    const directToolsBefore = new Map([...registeredDirectTools.keys()].map((name) => [name, registeredDirectToolVersions.get(name) ?? 0]));
+    const proxyModes = await loadForRuntime(loadProxyModes, guard);
+    const result = await proxyModes.executeConnect(targetState, serverName, signal);
+    assertRuntimeGuard(guard);
+    if (!directToolsFrozen) syncToolSurface(ctx);
+    const reportedNames = reportedDirectToolNamesByServer.get(serverName) ?? new Set<string>();
+    // Attribute only this server's new definitions; search-mode tools load on search, not connect.
+    const addedToolNames = [...registeredDirectTools.keys()].filter(
+      (name) => (!directToolsBefore.has(name) || (registeredDirectToolVersions.get(name) ?? 0) !== directToolsBefore.get(name))
+        && registeredDirectToolServers.get(name) === serverName
+        && !reportedNames.has(name)
+        && !lazyDirectTools.has(name),
+    );
+    if (addedToolNames.length === 0) return result;
+    for (const name of addedToolNames) reportedNames.add(name);
+    reportedDirectToolNamesByServer.set(serverName, reportedNames);
+    return { ...result, addedToolNames };
+  }
+
+  async function executeInstall(
+    targetState: McpExtensionState,
+    rawUrl: string | undefined,
+    requestedName: string | undefined,
+    target: string | undefined,
+    cwd: string,
+    signal?: AbortSignal,
+  ) {
+    const installOwner = currentOwner;
+    signal?.throwIfAborted();
+    installOwner?.throwIfInactive();
+    if (programmaticConfig) {
+      return {
+        content: [{ type: "text" as const, text: "MCP install is unavailable when the adapter uses programmatic configuration." }],
+        details: { mode: "install", error: "programmatic_config" },
+      };
+    }
+    if (target !== undefined && target !== "global" && target !== "project") {
+      return {
+        content: [{ type: "text" as const, text: "MCP install target must be 'global' or 'project'." }],
+        details: { mode: "install", error: "invalid_target" },
+      };
+    }
+
+    const destination = target === "project" ? getProjectConfigPath(cwd) : getPiGlobalConfigPath(earlyConfigPath);
+    if (target === "project" && process.env.PI_MCP_CONFIG_MODE?.trim().toLowerCase() === "exclusive"
+      && resolve(destination) !== resolve(getPiGlobalConfigPath(earlyConfigPath))) {
+      return {
+        content: [{ type: "text" as const, text: "Project installation is unavailable in exclusive config mode; use the global target." }],
+        details: { mode: "install", error: "inactive_target" },
+      };
+    }
+
+    const installGuard = captureRuntimeGuard(targetState);
+    const installParsing = await loadForRuntime(loadInstallParsing, installGuard);
+    let normalized: ReturnType<typeof installParsing.normalizeMcpInstallRequest>;
+    try {
+      normalized = installParsing.normalizeMcpInstallRequest({
+        url: rawUrl ?? "",
+        ...(requestedName !== undefined ? { serverName: requestedName } : {}),
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        content: [{ type: "text" as const, text: `Failed to install MCP server: ${message}` }],
+        details: { mode: "install", error: "invalid_request", message },
+      };
+    }
+
+    const matchingUrl = Object.entries(targetState.config.mcpServers).find(([, definition]) =>
+      definition.url !== undefined && installParsing.canonicalMcpServerUrl(definition.url) === normalized.url,
+    );
+    const serverName = requestedName?.trim() || matchingUrl?.[0] || normalized.serverName;
+    const existing = targetState.config.mcpServers[serverName];
+    if (existing && installParsing.canonicalMcpServerUrl(existing.url ?? "") !== normalized.url) {
+      return {
+        content: [{ type: "text" as const, text: `MCP server name "${serverName}" is already configured with a different endpoint.` }],
+        details: { mode: "install", error: "name_conflict", server: serverName, url: normalized.url },
+      };
+    }
+
+    if (targetState.provisionalInstalls?.has(serverName)) {
+      return {
+        content: [{ type: "text" as const, text: `MCP server "${serverName}" is still being installed. Retry after that installation finishes.` }],
+        details: { mode: "install", error: "install_in_progress", server: serverName },
+      };
+    }
+    if (runtimeServers.has(serverName)) {
+      return {
+        content: [{ type: "text" as const, text: `Runtime MCP server "${serverName}" cannot be promoted by URL install. Save its full definition manually.` }],
+        details: { mode: "install", error: "runtime_promotion_unsupported", server: serverName },
+      };
+    }
+
+    const persistedEntry: ServerEntry = { url: normalized.url };
+    const runtimeEntry: ServerEntry = existing ?? { ...persistedEntry, directTools: false };
+    const provisional = existing === undefined;
+    const restoreMetadata = [targetState.toolMetadata, targetState.promptMetadata, targetState.serverInstructions,
+      targetState.resourceCounts, targetState.directToolCounts].map((map) => {
+      const previous = map.get(serverName);
+      return () => {
+        if (previous === undefined) map.delete(serverName);
+        else (map as Map<string, unknown>).set(serverName, previous);
+      };
+    });
+    const hadLivePrompts = targetState.promptMetadataLive.has(serverName);
+    const rollback = async (): Promise<void> => {
+      if (!provisional || targetState.config.mcpServers[serverName] !== runtimeEntry) return;
+      delete targetState.config.mcpServers[serverName];
+      targetState.lifecycle.unregisterServer(serverName);
+      try {
+        await targetState.manager.close(serverName);
+      } finally {
+        targetState.provisionalInstalls?.delete(serverName);
+        for (const restore of restoreMetadata) restore();
+        if (!hadLivePrompts) targetState.promptMetadataLive.delete(serverName);
+        const core = await loadForRuntime(loadCoreRuntime, installGuard);
+        core.clearFailure(targetState, serverName, "install-rollback");
+        syncToolSurface();
+        core.updateStatusBar(targetState);
+      }
+    };
+
+    let connectResult: Awaited<ReturnType<typeof connectAndReport>>;
+    try {
+      if (provisional) {
+        (targetState.provisionalInstalls ??= new Set()).add(serverName);
+        targetState.config.mcpServers[serverName] = runtimeEntry;
+        attachRuntimeServerLifecycle(targetState, serverName, runtimeEntry);
+        syncToolSurface();
+        (await loadForRuntime(loadCoreRuntime, installGuard)).updateStatusBar(targetState);
+      }
+      connectResult = await connectAndReport(targetState, serverName, signal);
+      signal?.throwIfAborted();
+      installOwner?.throwIfInactive();
+    } catch (error) {
+      await rollback();
+      throw error;
+    }
+    const connectError = connectResult.details?.error;
+    const connectText = connectResult.content.find((content) => content.type === "text")?.text;
+    if (connectError && connectError !== "auth_required") {
+      await rollback();
+      return {
+        ...connectResult,
+        content: [{ type: "text" as const, text: `MCP installation validation failed for "${serverName}". ${connectText ?? "Connection failed."}` }],
+        details: { mode: "install", error: "validation_failed", server: serverName, url: normalized.url },
+      };
+    }
+
+    if (provisional) {
+      try {
+        await withFileMutationQueue(destination, async () => {
+          signal?.throwIfAborted();
+          installOwner?.throwIfInactive();
+          writeSharedServerEntry(destination, serverName, persistedEntry);
+        });
+      } catch (error) {
+        await rollback();
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text" as const, text: `MCP server validation succeeded, but configuration could not be saved: ${message}` }],
+          details: { mode: "install", error: "persistence_failed", server: serverName, url: normalized.url, message },
+        };
+      }
+      targetState.provisionalInstalls?.delete(serverName);
+      try {
+        (await loadForRuntime(loadCoreRuntime, installGuard)).updateMetadataCache(targetState, serverName);
+        assertRuntimeGuard(installGuard);
+      } catch (error) {
+        if (isRuntimeGuardStale(installGuard) || isAbortError(error, installGuard.owner?.signal)) throw error;
+        logger.warn(`MCP: installed "${serverName}" but could not cache metadata: ${error}`);
+      }
+      syncPromptCommands();
+    }
+
+    if (connectError === "auth_required") {
+      const proxyModes = await loadForRuntime(loadProxyModes, installGuard);
+      const authResult = await proxyModes.executeAuthStart(targetState, serverName, signal);
+      const authError = authResult.details?.error;
+      const authText = authResult.content.find((content) => content.type === "text")?.text;
+      return {
+        ...connectResult,
+        content: [{
+          type: "text" as const,
+          text: `${provisional ? "Installed" : "Found"} MCP server "${serverName}" at ${normalized.url}.\n\n${authText ?? "OAuth authorization is required."}`,
+        }],
+        details: {
+          mode: "install",
+          status: authError ? "auth_start_failed" : "awaiting_auth",
+          server: serverName,
+          url: normalized.url,
+          ...(provisional ? { path: destination } : {}),
+          ...(authError ? { error: authError } : {}),
+        },
+      };
+    }
+
+    return {
+      ...connectResult,
+      content: [{
+        type: "text" as const,
+        text: `${provisional ? "Installed and connected" : "Already installed; connected"} MCP server "${serverName}" at ${normalized.url}.\n\n${connectText ?? ""}`.trim(),
+      }],
+      details: {
+        mode: "install",
+        status: "connected",
+        server: serverName,
+        url: normalized.url,
+        ...(provisional ? { path: destination } : {}),
+      },
+    };
+  }
+
   function registerProxyTool(description: string): void {
-    (pi.registerTool as (tool: unknown) => unknown)({
+    callReentrant(() => (pi.registerTool as (tool: unknown) => unknown)({
       name: "mcp",
       label: "MCP",
       description,
-      promptSnippet: "MCP gateway — status, search, describe, auth, and single MCP tool calls",
+      promptSnippet: "MCP gateway — install by URL, status, search, describe, auth, and single MCP tool calls",
       renderShell: toolRenderShell,
       renderCall: createMcpProxyToolCallRenderer(toolRenderOptions),
       parameters: Type.Object({
@@ -1041,8 +1670,10 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         includeSchemas: Type.Optional(Type.Boolean({ description: "Include parameter schemas in search results (default: true)" })),
         limit: optionalNumber({ minimum: 1, description: "Maximum search results to return (default: 12)" }),
         offset: optionalNumber({ minimum: 0, description: "Search result offset (default: 0)" }),
-        server: Type.Optional(Type.String({ description: "Filter to specific server (also disambiguates tool calls)" })),
-        action: Type.Optional(Type.String({ description: "Action: 'ui-messages', 'auth-start', or 'auth-complete'" })),
+        server: Type.Optional(Type.String({ description: "Server name (filters/disambiguates calls and optionally names an install)" })),
+        action: Type.Optional(Type.String({ description: "Action: 'install', 'ui-messages', 'auth-start', or 'auth-complete'" })),
+        url: Type.Optional(Type.String({ description: "MCP endpoint URL for action: 'install'" })),
+        target: Type.Optional(Type.String({ description: "Install target: 'global' (default) or 'project'" })),
       }),
       renderResult: renderMcpToolResult,
       async execute(_toolCallId: string, params: {
@@ -1058,6 +1689,8 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         offset?: number;
         server?: string;
         action?: string;
+        url?: string;
+        target?: string;
       }, signal: AbortSignal | undefined, _onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined, _ctx: ExtensionContext) {
         let executeOwner = currentOwner;
         const parseArgs = (value: string | Record<string, unknown> | undefined): Record<string, unknown> | undefined => {
@@ -1090,13 +1723,16 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
           || value.instructions !== undefined
           || value.search !== undefined
           || value.server !== undefined
-          || value.action !== undefined;
+          || value.action !== undefined
+          || value.url !== undefined
+          || value.target !== undefined;
         if (!hasGatewayMode(params) && params.args !== undefined) {
           throw new Error("Gateway params were nested inside `args`; pass them top-level (for example, mcp({ search: \"...\" }) or mcp({ tool: \"...\", args: {} })).");
         }
 
-        if (!state && !initPromise && retainedInitFailure) {
-          startGatewayRetryInitialization(_ctx);
+        if (!state && !initPromise) {
+          if (retainedInitFailure) startGatewayRetryInitialization(_ctx);
+          else void ensureSessionRuntime(_ctx);
           executeOwner = currentOwner;
         }
 
@@ -1129,9 +1765,15 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
           };
         }
         executeOwner?.throwIfInactive();
+        const proxyState = state;
+        const proxyGuard = captureRuntimeGuard(proxyState);
+        const proxyModes = await loadForRuntime(loadProxyModes, proxyGuard);
 
+        if (params.action === "install") {
+          return executeInstall(proxyState, params.url, params.server, params.target, _ctx.cwd, signal);
+        }
         if (params.action === "ui-messages") {
-          return executeUiMessages(state);
+          return proxyModes.executeUiMessages(proxyState);
         }
         if (params.action === "auth-start") {
           if (!params.server) {
@@ -1141,8 +1783,8 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
             };
           }
           return signal
-            ? executeAuthStart(state, params.server, signal)
-            : executeAuthStart(state, params.server);
+            ? proxyModes.executeAuthStart(proxyState, params.server, signal)
+            : proxyModes.executeAuthStart(proxyState, params.server);
         }
         if (params.action === "auth-complete") {
           if (!params.server) {
@@ -1159,32 +1801,42 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
             };
           }
           return signal
-            ? executeAuthComplete(state, params.server, input, signal)
-            : executeAuthComplete(state, params.server, input);
+            ? proxyModes.executeAuthComplete(proxyState, params.server, input, signal)
+            : proxyModes.executeAuthComplete(proxyState, params.server, input);
         }
         if (params.tool) {
-          return executeCall(state, params.tool, parsedArgs, params.server, getPiTools, signal);
+          return proxyModes.executeCall(proxyState, params.tool, parsedArgs, params.server, getPiTools, signal);
         }
         if (params.connect) {
-          const result = await executeConnect(state, params.connect, signal);
-          if (!directToolsFrozen) syncToolSurface(_ctx as ExtensionContext);
-          return result;
+          return connectAndReport(proxyState, params.connect, signal, _ctx as ExtensionContext);
         }
         if (params.describe) {
-          return executeDescribe(state, params.describe);
+          return proxyModes.executeDescribe(proxyState, params.describe);
         }
         if (params.instructions) {
-          return executeInstructions(state, params.instructions);
+          return proxyModes.executeInstructions(proxyState, params.instructions);
         }
         if (params.search !== undefined) {
-          return executeSearch(state, params.search, params.regex, params.server, params.includeSchemas, params.limit, params.offset);
+          const result = proxyModes.executeSearch(proxyState, params.search, params.regex, params.server, params.includeSchemas, params.limit, params.offset);
+          if (lazyDirectTools.size === 0) return result;
+          holdLazyToolsInactive();
+          const matches = (result.details as { matches?: Array<{ server: string; tool: string }> } | undefined)?.matches ?? [];
+          const added = activateSearchMatches(matches);
+          if (added.length === 0) return result;
+          const text = result.content.map((block) => ("text" in block ? block.text : "")).join("\n");
+          return {
+            ...result,
+            content: [{ type: "text" as const, text: `Activated as direct tools: ${added.join(", ")}.\n\n${text}` }],
+            details: { ...(result.details ?? {}), activated: added },
+            addedToolNames: added,
+          };
         }
         if (params.server) {
-          return executeList(state, params.server);
+          return proxyModes.executeList(proxyState, params.server);
         }
-        return executeStatus(state);
+        return proxyModes.executeStatus(proxyState);
       },
-    });
+    }));
     proxyToolRegistered = true;
     proxyToolDescription = description;
   }
@@ -1195,20 +1847,27 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       cache,
       envRaw === undefined || envRaw === "__none__" ? undefined : envDirectToolOverride,
     );
+    // Search-mode tools are registered INACTIVE and `mcp({ search })` is their only
+    // activation entry point, so dropping the gateway strands them: every tool held, nothing
+    // able to activate one. Keep it whenever any spec depends on it.
+    const hasSearchModeSpecs = directSpecs.some((spec) => spec.lazy === true);
     const shouldRegisterProxyTool =
       config.settings?.disableProxyTool !== true
       || directSpecs.length === 0
+      || hasSearchModeSpecs
       || missingConfiguredDirectToolServers.length > 0;
 
     if (shouldRegisterProxyTool) {
       const description = buildProxyDescription(config);
       if (!proxyToolRegistered || proxyToolDescription !== description) {
+        finalizationRegistrations?.add("mcp");
         registerProxyTool(description);
+        finalizationGuard?.();
         return;
       }
       const activeTools = getActiveToolsIfReady();
       if (activeTools && !activeTools.includes("mcp")) {
-        pi.setActiveTools([...activeTools, "mcp"]);
+        callReentrant(() => pi.setActiveTools([...activeTools, "mcp"]));
       }
       return;
     }
@@ -1233,7 +1892,11 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
 }
 
 export function createMcpAdapter(options: McpAdapterOptions = {}) {
-  const factoryConfig = options.config !== undefined ? cloneMcpConfig(options.config) : undefined;
+  // Snapshot programmatic plugin roots at the API boundary so early and
+  // session-scoped loading cannot resolve the same relative path differently.
+  const factoryConfig = options.config !== undefined
+    ? normalizeProgrammaticConfig(cloneMcpConfig(options.config))
+    : undefined;
   return function mcpAdapter(pi: ExtensionAPI) {
     installMcpAdapter(pi, {
       ...(options.configPath !== undefined ? { configPath: options.configPath } : {}),