@duckmind/dm-linux-x64 0.65.4 → 0.65.6

package/extensions/dm-mcp-adapter/index.js

@@ -1,22 +1,23 @@
+import { withFileMutationQueue } from "@duckmind/dm-coding-agent";
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { isServerDisabled } from "./types.js";
 import { Type } from "typebox";
-import { showStatus, showTools, showPrompts, reconnectServer, reconnectServers, authenticateServer, logoutServer, manageBearerToken, openMcpAuthPanel, openMcpPanel, openMcpSetup } from "./commands.js";
-import { cloneMcpConfig, loadMcpConfig, writeProjectServerDisabledOverride } from "./config.js";
-import { buildProxyDescription, createDirectToolExecutor, getMissingConfiguredDirectToolServers, prepareDirectToolArguments, resolveDirectTools } from "./direct-tools.js";
-import { flushMetadataCache, initializeMcp, updateStatusBar } from "./init.js";
+import { cloneMcpConfig, discoverConfiguredClaudePluginSkills, getPiGlobalConfigPath, getProjectConfigPath, loadMcpConfig, resolveConfiguredClaudePluginMcp, writeProjectServerDisabledOverride, writeSharedServerEntry } from "./config.js";
+import { buildProxyDescription, getLargeDirectToolsAdvisory, getMissingConfiguredDirectToolServers, prepareDirectToolArguments, resolveDirectTools } from "./direct-tool-surface.js";
 import { isServerInActiveFailureBackoff } from "./failure-backoff.js";
-import { loadMetadataCache, parseDirectToolSelectors } from "./metadata-cache.js";
+import { computeServerHash, isServerCacheValid, loadMetadataCache, parseDirectToolSelectors } from "./metadata-cache.js";
 import { createPromptCommand, resolveCachedPrompts } from "./prompts.js";
 import { logger } from "./logger.js";
-import { executeAuthComplete, executeAuthStart, executeCall, executeConnect, executeDescribe, executeInstructions, executeList, executeSearch, executeStatus, executeUiMessages } from "./proxy-modes.js";
-import { formatTerminalError, getConfigPathFromArgv, normalizeDirectToolInputSchema, truncateAtWord } from "./utils.js";
-import { createOAuthRuntime, shutdownOAuth } from "./mcp-auth-flow.js";
+import { formatMcpFooterStatus, formatTerminalError, getConfigPathFromArgv, normalizeDirectToolInputSchema, truncateAtWord } from "./utils.js";
 import { createMcpDirectToolCallRenderer, createMcpProxyToolCallRenderer, createMcpScriptToolCallRenderer, createMcpToolResultRenderer, resolveMcpToolRenderOptions } from "./tool-result-renderer.js";
 import { toolErrorOverride } from "./error-signal.js";
 import { createMcpRuntimeOwner, createOwnedUi, isAbortError } from "./runtime-owner.js";
 import { publishMcpStatusShutdown } from "./mcp-status.js";
-import { runMcpScript } from "./mcp-code.js";
-import { cleanupMaterializedBinaryResources } from "./tool-registrar.js";
 import { syncNamespaceProxyTools } from "./namespace-tools.js";
+import { restoreSessionApprovalState } from "./session-approvals.js";
+import { createRetryableLoader } from "./lazy-loader.js";
 export {
   namespaceProxyName,
   parseMcpReference,
@@ -27,15 +28,49 @@ export {
   MCP_STATUS_SNAPSHOT_VERSION,
   MCP_TOOL_APPROVAL_REQUEST_EVENT
 } from "./types.js";
+const loadCoreRuntime = createRetryableLoader(() => import("./init.js"));
+const loadOAuthRuntime = createRetryableLoader(() => import("./mcp-auth-flow.js"));
+const loadProxyModes = createRetryableLoader(() => import("./proxy-modes.js"));
+const loadDirectExecution = createRetryableLoader(() => import("./direct-tools.js"));
+const loadCommands = createRetryableLoader(() => import("./commands.js"));
+const loadCodeMode = createRetryableLoader(() => import("./mcp-code.js"));
+const loadInstallParsing = createRetryableLoader(() => import("./mcp-install.js"));
 const INIT_WAIT_TIMEOUT_MS = 30000;
 const INIT_FAILURE_MESSAGE_MAX_CHARS = 1000;
 const INIT_WAIT_TIMED_OUT = Symbol("init-wait-timed-out");
+function hasEnabledServerWithoutValidMetadata(config, cache, directSpecs = []) {
+  return Object.entries(config.mcpServers).some(([serverName, definition]) => {
+    if (isServerDisabled(definition) || directSpecs.some((spec) => spec.serverName === serverName))
+      return false;
+    const entry = cache?.servers[serverName];
+    return entry === undefined || !isServerCacheValid(entry, definition);
+  });
+}
 export const MCP_RUNTIME_REGISTER_EVENT = "dm-mcp-adapter:runtime-register:v1";
 export const MCP_RUNTIME_REGISTER_VERSION = 1;
 export const MCP_RUNTIME_SNAPSHOT_EVENT = "dm-mcp-adapter:runtime-snapshot:v1";
 export const MCP_RUNTIME_SNAPSHOT_VERSION = 1;
 const runtimeRegistrars = new WeakMap;
 const runtimeSnapshotters = new WeakMap;
+function resolveProgrammaticClaudePluginPath(path, cwd) {
+  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) {
+  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(promise, timeoutMs) {
   let timer;
   try {
@@ -67,10 +102,19 @@ function installMcpAdapter(pi, options) {
   const programmaticConfig = sessionConfig !== undefined;
   let state = null;
   let initPromise = null;
+  let initStartedPromise = null;
   let currentOwner = null;
   let currentOAuthRuntime = null;
   let lifecycleGeneration = 0;
   let retainedInitFailure = null;
+  let finalizationGuard = null;
+  let finalizationRegistrations = null;
+  function callReentrant(callback) {
+    finalizationGuard?.();
+    const result = callback();
+    finalizationGuard?.();
+    return result;
+  }
   function retainInitFailure(error) {
     const message = truncateAtWord(formatTerminalError(error), INIT_FAILURE_MESSAGE_MAX_CHARS);
     retainedInitFailure = message;
@@ -92,27 +136,59 @@ function installMcpAdapter(pi, options) {
     }
     return true;
   }
+  function captureRuntimeGuard(expectedState = state) {
+    return { generation: lifecycleGeneration, owner: currentOwner, state: expectedState };
+  }
+  function assertRuntimeGuard(guard) {
+    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) {
+    return guard.owner?.isActive() === false || lifecycleGeneration !== guard.generation || currentOwner !== guard.owner || state !== guard.state;
+  }
+  async function loadForRuntime(loader, guard) {
+    const loaded = await loader();
+    assertRuntimeGuard(guard);
+    return loaded;
+  }
+  function createCommandContext(ctx, owner) {
+    const commandCtx = Object.create(ctx);
+    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) {
     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, reason) {
+  async function shutdownState(currentState, reason, publishStatus = true) {
     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);
       currentState.uiServer = null;
     }
     let flushError;
     try {
+      const { flushMetadataCache } = await loadCoreRuntime();
       flushMetadataCache(currentState);
     } catch (error) {
       flushError = error;
@@ -134,21 +210,41 @@ function installMcpAdapter(pi, options) {
       throw flushError;
     }
   }
+  function restoreCurrentSessionApprovals(targetState) {
+    const sessionManager = targetState.sessionManager;
+    if (!sessionManager)
+      return;
+    let branch = [];
+    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) : loadMcpConfig(earlyConfigPath);
+  const earlyConfig = programmaticConfig ? 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 hasStartupServer = Object.values(earlyConfig.mcpServers).some((definition) => !isServerDisabled(definition) && (definition.lifecycle === "eager" || definition.lifecycle === "keep-alive"));
   const registeredDirectTools = new Map;
+  const registeredDirectToolServers = new Map;
+  const registeredDirectToolVersions = new Map;
+  const reportedDirectToolNamesByServer = new Map;
   const registeredNamespaceProxyTools = new Set;
   const fallbackDeactivatedTools = new Set;
+  const lazyDirectTools = new Set;
+  const searchActivatedTools = new Set;
   const toolRenderOptions = resolveMcpToolRenderOptions(earlyConfig.settings);
   const toolRenderShell = toolRenderOptions.resultRendering === "compact" ? "self" : "default";
   const renderMcpToolResult = createMcpToolResultRenderer(toolRenderOptions);
   let proxyToolRegistered = false;
   let proxyToolDescription = null;
   let directToolsFrozen = false;
+  let largeDirectToolsAdvisoryDelivered = false;
   const runtimeServers = new Map;
   function attachRuntimeServerLifecycle(targetState, name, definition) {
     const lifecycleMode = definition.lifecycle ?? "lazy";
@@ -168,22 +264,89 @@ function installMcpAdapter(pi, options) {
       inputSchema: spec.inputSchema,
       resourceUri: spec.resourceUri,
       uiResourceUri: spec.uiResourceUri,
-      uiStreamMode: spec.uiStreamMode
+      uiStreamMode: spec.uiStreamMode,
+      lazy: spec.lazy === true
     });
   }
+  function forgetReportedDirectToolName(serverName, toolName) {
+    if (!serverName)
+      return;
+    const reportedNames = reportedDirectToolNamesByServer.get(serverName);
+    if (!reportedNames)
+      return;
+    reportedNames.delete(toolName);
+    if (reportedNames.size === 0)
+      reportedDirectToolNamesByServer.delete(serverName);
+  }
   function registerDirectTool(spec, config) {
-    pi.registerTool({
+    finalizationRegistrations?.add(spec.prefixedName);
+    callReentrant(() => pi.registerTool({
       name: spec.prefixedName,
       label: `MCP: ${spec.originalName}`,
       description: spec.description || "(no description)",
       promptSnippet: truncateAtWord(spec.description, 100) || `MCP tool from ${spec.serverName}`,
       parameters: toToolParameters(normalizeDirectToolInputSchema(spec.inputSchema)),
       ...config.settings?.strictDirectToolArguments === true ? { prepareArguments: (args) => prepareDirectToolArguments(spec.inputSchema, args) } : {},
-      execute: createDirectToolExecutor(() => state, () => initPromise, spec),
+      async execute(toolCallId, params, signal, onUpdate, ctx) {
+        let executor;
+        let guard;
+        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", 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
-    });
+    }));
+  }
+  function holdLazyToolsInactive() {
+    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);
+  }
+  function activateSearchMatches(matches) {
+    const activeTools = getActiveToolsIfReady();
+    if (!activeTools)
+      return [];
+    const activeSet = new Set(activeTools);
+    const added = [];
+    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() {
     const currentState = state;
@@ -199,7 +362,7 @@ function installMcpAdapter(pi, options) {
   }
   function getActiveToolsIfReady() {
     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;
@@ -210,21 +373,19 @@ function installMcpAdapter(pi, options) {
     if (toolNames.length === 0)
       return [];
     const unregisterTool = pi.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();
-    if (!activeTools || activeTools.length === 0) {
-      for (const toolName of fallbackNames)
-        fallbackDeactivatedTools.add(toolName);
+    if (!activeTools)
       return unregistered;
-    }
+    const removedFallbackNames = fallbackNames.filter((name) => activeTools.includes(name));
+    if (removedFallbackNames.length === 0)
+      return unregistered;
+    const remove = new Set(removedFallbackNames);
     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));
+    for (const toolName of removedFallbackNames)
+      fallbackDeactivatedTools.add(toolName);
     return unregistered;
   }
   function syncDirectTools(config, cache) {
@@ -238,24 +399,45 @@ function installMcpAdapter(pi, options) {
       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) {
+        lazyDirectTools.add(spec.prefixedName);
+      } else if (lazyDirectTools.delete(spec.prefixedName)) {
+        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) {
@@ -268,17 +450,77 @@ function installMcpAdapter(pi, options) {
       state.config.mcpServers[serverName] = { ...definition, directTools: value };
     }
   }
+  function loadToolSurfaceCache(config) {
+    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) {
+    const notificationGeneration = lifecycleGeneration;
+    const notificationOwner = currentOwner;
     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;
+      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);
+    deliverLargeDirectToolsAdvisory(ctx, config, result.specs);
+    if (ctx && (notificationGeneration !== lifecycleGeneration || notificationOwner !== currentOwner || notificationOwner && !notificationOwner.isActive())) {
+      throw notificationOwner?.signal.reason ?? new Error("Stale MCP session after direct-tools advisory");
+    }
+    finalizationGuard?.();
     const changed = result.added.length + result.updated.length + result.deactivated.length;
     if (changed > 0 && ctx?.hasUI) {
-      ctx.ui.notify(`MCP: direct tools refreshed (+${result.added.length}, ~${result.updated.length}, -${result.deactivated.length})`, "info");
+      callReentrant(() => ctx.ui.notify(`MCP: direct tools refreshed (+${result.added.length}, ~${result.updated.length}, -${result.deactivated.length})`, "info"));
+    }
+  }
+  function deliverLargeDirectToolsAdvisory(ctx, config, specs) {
+    if (!ctx || largeDirectToolsAdvisoryDelivered)
+      return;
+    const message = getLargeDirectToolsAdvisory(config, specs);
+    if (!message)
+      return;
+    largeDirectToolsAdvisoryDelivered = true;
+    if (ctx.hasUI) {
+      callReentrant(() => ctx.ui.notify(message, "warning"));
+    } else {
+      console.warn(message);
     }
   }
+  function getDeferredSessionSnapshot(cwd) {
+    const config = programmaticConfig ? resolveConfiguredClaudePluginMcp(cloneMcpConfig(sessionConfig), cwd ?? process.cwd()) : loadMcpConfig(earlyConfigPath, cwd);
+    const cache = loadMetadataCache();
+    const enabledServers = Object.values(config.mcpServers).filter((definition) => !isServerDisabled(definition));
+    if (enabledServers.some((definition) => definition.lifecycle === "eager" || definition.lifecycle === "keep-alive"))
+      return;
+    if (envRaw !== undefined && envRaw !== "__none__" && getMissingConfiguredDirectToolServers(config, cache, envDirectToolOverride).length > 0)
+      return;
+    if (config.settings?.deferWithMissingMetadata !== true && (cache === null || hasEnabledServerWithoutValidMetadata(config, cache)))
+      return;
+    return { config, cache, enabledServerCount: enabledServers.length };
+  }
   function syncNamespaceTools(config, cache, reservedDirectNames = new Set(registeredDirectTools.keys()), activeDirectNames = new Set(registeredDirectTools.keys())) {
     const result = syncNamespaceProxyTools({
       config,
@@ -291,11 +533,19 @@ function installMcpAdapter(pi, options) {
       pi,
       getState: () => state,
       getInitPromise: () => initPromise,
+      ensureRuntime: (ctx) => ensureSessionRuntime(ctx),
+      executeCall: async (...args) => {
+        const guard = captureRuntimeGuard(args[0]);
+        return (await loadForRuntime(loadProxyModes, guard)).executeCall(...args);
+      },
       getPiTools: () => pi.getAllTools(),
       renderOptions: toolRenderOptions,
       renderShell: toolRenderShell,
-      renderResult: renderMcpToolResult
+      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)
@@ -308,14 +558,20 @@ function installMcpAdapter(pi, options) {
         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),
+        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() {
-    registerPromptCommands([...state?.promptMetadata?.values() ?? []].flat());
+    registerPromptCommands([...state?.promptMetadata?.entries() ?? []].filter(([name]) => !state?.provisionalInstalls?.has(name)).flatMap(([, prompts]) => prompts));
   }
-  registerPromptCommands(resolveCachedPrompts(earlyConfig));
   const registerRuntimeServer = (name, definition) => {
     if (typeof name !== "string" || name.trim() === "") {
       throw new Error("MCP server name must be a non-empty string");
@@ -335,7 +591,12 @@ function installMcpAdapter(pi, options) {
       registeredState.config.mcpServers[name] = entry;
       attachRuntimeServerLifecycle(registeredState, name, entry);
       syncToolSurface();
-      updateStatusBar(registeredState);
+      const guard = captureRuntimeGuard(registeredState);
+      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 {
@@ -349,9 +610,11 @@ function installMcpAdapter(pi, options) {
           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);
       }
     };
   };
@@ -420,82 +683,195 @@ function installMcpAdapter(pi, options) {
     description: "Path to MCP config file",
     type: "string"
   });
-  function startInitialization(ctx, owner, oauthRuntime, generation, staleReason) {
-    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, owner, generation, staleReason) {
+    let oauthRuntime = null;
+    let markStarted;
+    initStartedPromise = new Promise((resolve) => {
+      markStarted = resolve;
     });
-    initPromise = promise;
-    return promise.then(async (nextState) => {
+    let coreRuntime = 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.js");
+        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 = 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;
+      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();
+        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);
-      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();
+        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);
+        }
+        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;
       }
+    });
+    initPromise = promise;
+    return promise.then(() => {
+      return;
     }).catch(async (err) => {
       if (!owner.isActive() || generation !== lifecycleGeneration) {
         return;
       }
-      if (initPromise !== promise && initPromise !== null) {
+      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)}`);
       }
     });
   }
+  function ensureSessionRuntime(ctx) {
+    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() {
-    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(() => {
@@ -503,9 +879,8 @@ function installMcpAdapter(pi, options) {
         return;
       const generation = ++lifecycleGeneration;
       const owner = createMcpRuntimeOwner();
-      const oauthRuntime = createOAuthRuntime(owner.signal);
       currentOwner = owner;
-      currentOAuthRuntime = oauthRuntime;
+      currentOAuthRuntime = null;
       startInitialization({
         mode: "print",
         hasUI: false,
@@ -513,40 +888,101 @@ function installMcpAdapter(pi, options) {
         model: undefined,
         modelRegistry: undefined,
         signal: undefined
-      }, owner, oauthRuntime, generation, "stale_load_time_initialization");
+      }, 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);
+    if (earlyConfig.settings?.scriptMode !== false) {
+      const scriptingSkillPath = fileURLToPath(new URL("./skills/mcp-scripting/SKILL.md", import.meta.url));
+      if (existsSync(scriptingSkillPath) && !skillPaths.includes(scriptingSkillPath)) {
+        skillPaths.push(scriptingSkillPath);
+      }
+    }
+    return skillPaths.length > 0 ? { skillPaths } : undefined;
+  });
   pi.on("session_start", async (_event, ctx) => {
+    searchActivatedTools.clear();
+    holdLazyToolsInactive();
     const generation = ++lifecycleGeneration;
+    largeDirectToolsAdvisoryDelivered = false;
     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();
     const stopPrevious = previousOwner?.stop("MCP extension session restarted") ?? Promise.resolve();
     try {
       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;
-    const initialization = startInitialization(ctx, owner, oauthRuntime, generation, "stale_session_start");
+    if (state)
+      return;
+    if (!initPromise) {
+      const deferredSnapshot = getDeferredSessionSnapshot(ctx.cwd);
+      if (deferredSnapshot) {
+        const { config, cache, enabledServerCount } = deferredSnapshot;
+        const directResult = syncDirectTools(config, cache);
+        syncProxyTool(config, cache, directResult.specs);
+        syncNamespaceTools(config, cache, directResult.reservedDirectNames, directResult.activeDirectNames);
+        if (config.settings?.deferWithMissingMetadata !== true) {
+          registerPromptCommands(resolveCachedPrompts(config));
+        }
+        deliverLargeDirectToolsAdvisory(ctx, config, directResult.specs);
+        if (generation !== lifecycleGeneration || !owner.isActive() || currentOwner !== owner)
+          return;
+        const serverCount = Object.keys(config.mcpServers).length;
+        const formattedStatus = formatMcpFooterStatus(config, enabledServerCount, serverCount - enabledServerCount, 0);
+        const theme = ctx.ui?.theme;
+        const styledStatus = formattedStatus !== undefined && typeof theme?.fg === "function" ? theme.fg("accent", formattedStatus) : formattedStatus;
+        ctx.ui?.setStatus("mcp", styledStatus);
+        return;
+      }
+      startInitialization(ctx, owner, generation, "stale_session_start");
+    }
+    const initialization = initPromise;
+    const initializationStarted = initStartedPromise;
     if (envRaw !== undefined && envRaw !== "__none__") {
       const missingEnvDirectTools = getMissingConfiguredDirectToolServers(earlyConfig, loadMetadataCache(), envDirectToolOverride);
       if (missingEnvDirectTools.length > 0) {
-        await initialization;
+        await initialization?.then(() => {
+          return;
+        }, () => {
+          return;
+        });
+        return;
       }
     }
+    await initializationStarted;
+  });
+  pi.on("before_agent_start", holdLazyToolsInactive);
+  pi.on("session_tree", (_event, ctx) => {
+    const currentState = state;
+    const owner = currentOwner;
+    if (!currentState || !owner?.isActive() || !currentState.sessionManager)
+      return;
+    let sessionManager;
+    try {
+      sessionManager = ctx.sessionManager;
+    } catch {
+      return;
+    }
+    if (sessionManager !== currentState.sessionManager)
+      return;
+    restoreCurrentSessionApprovals(currentState);
   });
   pi.on("input", async () => {
     const inputOwner = currentOwner;
@@ -579,13 +1015,14 @@ function installMcpAdapter(pi, options) {
     currentOAuthRuntime = null;
     state = null;
     initPromise = null;
+    initStartedPromise = null;
     clearRetainedInitFailure();
     const stopOwner = owner?.stop("MCP extension session shutdown") ?? Promise.resolve();
     try {
       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)}`);
@@ -603,6 +1040,8 @@ function installMcpAdapter(pi, options) {
           { value: "tools", label: "tools — List all tools" },
           { value: "prompts", label: "prompts — List all MCP prompts" },
           { value: "setup", label: "setup — Configure MCP servers" },
+          { value: "jev", label: "jev setup — Configure Jev semantic search" },
+          { value: "edit", label: "edit — Edit .mcp.json or the global config" },
           { value: "logout", label: "logout — Clear server credentials" },
           { value: "token", label: "token — Manage stored bearer tokens" },
           { value: "disable", label: "disable — Disable a server" },
@@ -612,8 +1051,12 @@ function installMcpAdapter(pi, options) {
         return subcommands.length > 0 ? subcommands : null;
       }
       const [, subcommand, argumentPrefix] = argumentMatch;
-      if (subcommand !== "reconnect" && subcommand !== "logout" && subcommand !== "disable" && subcommand !== "enable" && subcommand !== "token" || argumentPrefix === undefined || !state)
+      if (subcommand === "jev") {
+        return "setup".startsWith((argumentPrefix ?? "").trimStart()) ? [{ value: "jev setup", label: "setup — Configure Jev semantic search" }] : null;
+      }
+      if (subcommand !== "reconnect" && subcommand !== "logout" && subcommand !== "disable" && subcommand !== "enable" && subcommand !== "token" || argumentPrefix === undefined)
         return null;
+      const completionConfig = state?.config ?? earlyConfig;
       if (subcommand === "token") {
         const tokenMatch = argumentPrefix.trimStart().match(/^(set|remove|status)\s+(.*)$/);
         if (!tokenMatch) {
@@ -622,28 +1065,22 @@ function installMcpAdapter(pi, options) {
         }
         const action = tokenMatch[1] ?? "";
         const serverPrefix = tokenMatch[2] ?? "";
-        const servers = Object.keys(state.config.mcpServers).filter((serverName) => serverName.startsWith(serverPrefix.trimStart())).map((serverName) => ({ value: `token ${action} ${serverName}`, label: serverName }));
+        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).filter((serverName) => serverName.startsWith(argumentPrefix.trimStart())).map((serverName) => ({ value: `${subcommand} ${serverName}`, label: serverName }));
+      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
-      };
-      if (!state && initPromise) {
+      let commandCtx = createCommandContext(ctx, commandOwner);
+      if (!state) {
         try {
-          const initialized = await initPromise;
+          state = await ensureSessionRuntime(ctx);
+          commandOwner = currentOwner;
+          commandCtx = createCommandContext(ctx, commandOwner);
           commandOwner?.throwIfInactive();
-          state = initialized;
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
           if (commandCtx.hasUI)
@@ -656,6 +1093,18 @@ function installMcpAdapter(pi, options) {
           commandCtx.ui?.notify("MCP not initialized", "error");
         return;
       }
+      const commandGuard = captureRuntimeGuard(state);
+      let commands;
+      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];
@@ -663,13 +1112,13 @@ function installMcpAdapter(pi, options) {
       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();
@@ -677,7 +1126,7 @@ function installMcpAdapter(pi, options) {
             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();
@@ -685,6 +1134,41 @@ function installMcpAdapter(pi, options) {
           }
           break;
         }
+        case "jev": {
+          if (parts[1] !== "setup" || parts.length !== 2) {
+            commandCtx.ui?.notify("Usage: /mcp jev setup", "error");
+            break;
+          }
+          if (programmaticConfig) {
+            commandCtx.ui?.notify("Jev setup is unavailable when config is supplied by createMcpAdapter().", "info");
+            break;
+          }
+          commandOwner?.throwIfInactive();
+          if (await commands.setupJevSemanticSearch(state, commandCtx, earlyConfigPath)) {
+            commandOwner?.throwIfInactive();
+            await commandReload();
+            return;
+          }
+          break;
+        }
+        case "edit": {
+          if (programmaticConfig) {
+            commandCtx.ui?.notify("MCP edit is unavailable when config is supplied by createMcpAdapter().", "info");
+            break;
+          }
+          const target = parts[1] ?? "project";
+          if (target !== "project" && target !== "global") {
+            commandCtx.ui?.notify("Usage: /mcp edit [project|global]", "error");
+            return;
+          }
+          commandOwner?.throwIfInactive();
+          if (await commands.editSharedConfig(commandCtx, target)) {
+            commandOwner?.throwIfInactive();
+            await commandReload();
+            return;
+          }
+          break;
+        }
         case "logout": {
           const serverName = rest;
           if (!serverName) {
@@ -693,7 +1177,7 @@ function installMcpAdapter(pi, options) {
             return;
           }
           commandOwner?.throwIfInactive();
-          await logoutServer(serverName, state, commandCtx);
+          await commands.logoutServer(serverName, state, commandCtx);
           break;
         }
         case "token": {
@@ -710,7 +1194,7 @@ function installMcpAdapter(pi, options) {
             return;
           }
           commandOwner?.throwIfInactive();
-          await manageBearerToken(action, serverName, state, commandCtx);
+          await commands.manageBearerToken(action, serverName, state, commandCtx);
           break;
         }
         case "disable":
@@ -744,10 +1228,10 @@ function installMcpAdapter(pi, options) {
             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);
             });
@@ -757,7 +1241,7 @@ function installMcpAdapter(pi, options) {
               return;
             }
           } else {
-            await showStatus(state, commandCtx);
+            await commands.showStatus(state, commandCtx);
           }
           break;
       }
@@ -769,24 +1253,18 @@ function installMcpAdapter(pi, options) {
   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
-      };
+      let commandOwner = currentOwner;
+      let commandCtx = createCommandContext(ctx, commandOwner);
       const serverName = args?.trim();
       if (!serverName && !commandCtx.hasUI) {
         return;
       }
-      if (!state && initPromise) {
+      if (!state) {
         try {
-          const initialized = await initPromise;
+          state = await ensureSessionRuntime(ctx);
+          commandOwner = currentOwner;
+          commandCtx = createCommandContext(ctx, commandOwner);
           commandOwner?.throwIfInactive();
-          state = initialized;
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
           if (commandCtx.hasUI)
@@ -799,18 +1277,30 @@ function installMcpAdapter(pi, options) {
           commandCtx.ui?.notify("MCP not initialized", "error");
         return;
       }
+      const commandGuard = captureRuntimeGuard(state);
+      let commands;
+      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);
       }
     }
   });
@@ -818,7 +1308,7 @@ function installMcpAdapter(pi, options) {
     pi.registerTool({
       name: "mcpScript",
       label: "MCP Script",
-      description: "Run trusted JavaScript that makes multiple MCP tool calls in one request — loop, filter, chain, or fan out between calls. For a single MCP call, search, describe, status check, or auth action, use the mcp tool instead. Discover with await tools.search({ query }) — resolves to { items: [{ path, name, server, description? }], total, hasMore, nextOffset }, not an { ok, data } envelope. Inspect with await tools.describe({ path }) — resolves to the tool descriptor with inputTypeScript, or { path, error: { code, message, suggestions } }. Then call tools.call(path, args) — resolves to { ok: true, data } or { ok: false, error: { code, message } } — or use direct flat calls when the name is already known; use emit(value) for user-visible output. Load the mcp-scripting skill for the full workflow guide.",
+      description: "Run trusted JavaScript that makes multiple MCP tool calls in one request — loop, filter, chain, or fan out between calls. For a single MCP call, search, describe, status check, or auth action, use the mcp tool instead. Discover with await tools.search({ query }) — resolves to { items: [{ path, name, server, description? }], total, hasMore, nextOffset }, not an { ok, data } envelope. Inspect with await tools.describe({ path }) — resolves to the tool descriptor with inputTypeScript, or { path, error: { code, message, suggestions } }. Then call tools.call(path, args) — resolves to { ok: true, data } or { ok: false, error: { code, message } } — or use direct flat calls when the name is already known; use emit(value) for user-visible output.",
       promptSnippet: "Batch multiple MCP tool calls in one JavaScript request (loop, filter, chain)",
       parameters: Type.Object({
         code: Type.String({ description: "Trusted JavaScript MCP script. Use tools.<prefixedToolName>(args) and emit(value)." }),
@@ -826,17 +1316,18 @@ function installMcpAdapter(pi, options) {
       }),
       renderCall: createMcpScriptToolCallRenderer(toolRenderOptions),
       renderResult: renderMcpToolResult,
-      async execute(_toolCallId, params, signal) {
-        const executeOwner = currentOwner;
-        if (!state && initPromise) {
+      async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+        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", 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) {
@@ -856,16 +1347,231 @@ function installMcpAdapter(pi, options) {
           };
         }
         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, serverName, signal, ctx) {
+    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;
+    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, rawUrl, requestedName, target, cwd, signal) {
+    const installOwner = currentOwner;
+    signal?.throwIfAborted();
+    installOwner?.throwIfInactive();
+    if (programmaticConfig) {
+      return {
+        content: [{ type: "text", text: "MCP install is unavailable when the adapter uses programmatic configuration." }],
+        details: { mode: "install", error: "programmatic_config" }
+      };
+    }
+    if (targetState.config.settings?.allowInstall === false) {
+      return {
+        content: [{ type: "text", text: "MCP install is disabled by configuration." }],
+        details: { mode: "install", error: "install_disabled" }
+      };
+    }
+    if (target !== undefined && target !== "global" && target !== "project") {
+      return {
+        content: [{ type: "text", 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", 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;
+    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", 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", 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", 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", 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 = { url: normalized.url };
+    const runtimeEntry = 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.set(serverName, previous);
+      };
+    });
+    const hadLivePrompts = targetState.promptMetadataLive.has(serverName);
+    const rollback = async () => {
+      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;
+    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", 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", 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",
+          text: `${provisional ? "Installed" : "Found"} MCP server "${serverName}" at ${normalized.url}.
+
+${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",
+        text: `${provisional ? "Installed and connected" : "Already installed; connected"} MCP server "${serverName}" at ${normalized.url}.
+
+${connectText ?? ""}`.trim()
+      }],
+      details: {
+        mode: "install",
+        status: "connected",
+        server: serverName,
+        url: normalized.url,
+        ...provisional ? { path: destination } : {}
+      }
+    };
+  }
   function registerProxyTool(description) {
-    pi.registerTool({
+    callReentrant(() => pi.registerTool({
       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({
@@ -881,12 +1587,15 @@ function installMcpAdapter(pi, options) {
         describe: Type.Optional(Type.String({ description: "Tool name to describe (shows parameters)" })),
         instructions: Type.Optional(Type.String({ description: "Server name to show that server's usage instructions" })),
         search: Type.Optional(Type.String({ description: "Search tools by name/description" })),
+        searchMode: Type.Optional(Type.String({ enum: ["lexical", "semantic"], description: "Search backend (default: lexical; semantic is available when a System One key is configured)" })),
         regex: Type.Optional(Type.Boolean({ description: "Treat search as regex (default: substring match)" })),
         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 searches, disambiguates calls and describe operations, 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, params, signal, _onUpdate, _ctx) {
@@ -914,12 +1623,15 @@ function installMcpAdapter(pi, options) {
           return args;
         };
         const parsedArgs = parseArgs(params.args);
-        const hasGatewayMode = (value) => value.tool !== undefined || value.connect !== undefined || value.describe !== undefined || value.instructions !== undefined || value.search !== undefined || value.server !== undefined || value.action !== undefined;
+        const hasGatewayMode = (value) => value.tool !== undefined || value.connect !== undefined || value.describe !== undefined || value.instructions !== undefined || value.search !== undefined || value.server !== 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
+            ensureSessionRuntime(_ctx);
           executeOwner = currentOwner;
         }
         if (!state && initPromise) {
@@ -950,8 +1662,14 @@ function installMcpAdapter(pi, options) {
           };
         }
         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) {
@@ -960,7 +1678,7 @@ function installMcpAdapter(pi, options) {
               details: { mode: "auth-start", error: "missing_server" }
             };
           }
-          return signal ? executeAuthStart(state, params.server, signal) : executeAuthStart(state, params.server);
+          return signal ? proxyModes.executeAuthStart(proxyState, params.server, signal) : proxyModes.executeAuthStart(proxyState, params.server);
         }
         if (params.action === "auth-complete") {
           if (!params.server) {
@@ -976,47 +1694,66 @@ function installMcpAdapter(pi, options) {
               details: { mode: "auth-complete", error: "missing_input" }
             };
           }
-          return signal ? executeAuthComplete(state, params.server, input, signal) : executeAuthComplete(state, params.server, input);
+          return signal ? 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);
-          return result;
+          return connectAndReport(proxyState, params.connect, signal, _ctx);
         }
         if (params.describe) {
-          return executeDescribe(state, params.describe);
+          return proxyModes.executeDescribe(proxyState, params.describe, params.server);
         }
         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 = await proxyModes.executeSearch(proxyState, params.search, params.regex, params.server, params.includeSchemas, params.limit, params.offset, params.searchMode, signal);
+          assertRuntimeGuard(proxyGuard);
+          if (lazyDirectTools.size === 0)
+            return result;
+          holdLazyToolsInactive();
+          const matches = result.details?.matches ?? [];
+          const added = activateSearchMatches(matches);
+          if (added.length === 0)
+            return result;
+          const text = result.content.map((block) => ("text" in block) ? block.text : "").join(`
+`);
+          return {
+            ...result,
+            content: [{ type: "text", text: `Activated as direct tools: ${added.join(", ")}.
+
+${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;
   }
   function syncProxyTool(config, cache, directSpecs) {
     const missingConfiguredDirectToolServers = getMissingConfiguredDirectToolServers(config, cache, envRaw === undefined || envRaw === "__none__" ? undefined : envDirectToolOverride);
-    const shouldRegisterProxyTool = config.settings?.disableProxyTool !== true || directSpecs.length === 0 || missingConfiguredDirectToolServers.length > 0;
+    const hasSearchModeSpecs = directSpecs.some((spec) => spec.lazy === true);
+    const shouldRegisterProxyTool = config.settings?.disableProxyTool !== true || directSpecs.length === 0 || hasSearchModeSpecs || missingConfiguredDirectToolServers.length > 0 || hasEnabledServerWithoutValidMetadata(config, cache, directSpecs);
     if (shouldRegisterProxyTool) {
       const description = buildProxyDescription(config);
       if (!proxyToolRegistered || proxyToolDescription !== description) {
+        finalizationRegistrations?.add("mcp");
         registerProxyTool(description);
-        return;
+        finalizationGuard?.();
       }
       const activeTools = getActiveToolsIfReady();
-      if (activeTools && !activeTools.includes("mcp")) {
-        pi.setActiveTools([...activeTools, "mcp"]);
+      if (activeTools?.includes("mcp")) {
+        fallbackDeactivatedTools.delete("mcp");
+      } else if (activeTools && fallbackDeactivatedTools.delete("mcp")) {
+        callReentrant(() => pi.setActiveTools([...activeTools, "mcp"]));
       }
       return;
     }
@@ -1034,7 +1771,7 @@ function installMcpAdapter(pi, options) {
   startLoadTimeInitialization();
 }
 export function createMcpAdapter(options = {}) {
-  const factoryConfig = options.config !== undefined ? cloneMcpConfig(options.config) : undefined;
+  const factoryConfig = options.config !== undefined ? normalizeProgrammaticConfig(cloneMcpConfig(options.config)) : undefined;
   return function mcpAdapter(pi) {
     installMcpAdapter(pi, {
       ...options.configPath !== undefined ? { configPath: options.configPath } : {},