@bastani/atomic 0.9.5-alpha.8 → 0.9.5-alpha.9

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [0.9.5-alpha.9] - 2026-07-09
+
+### Changed
+
+- Improved interactive startup responsiveness by keeping footer git watcher setup out of first paint and deferring it until the first input handler is ready, while preserving lazy footer branch reads and post-frame branch-change re-rendering. Deferred extension/resource loading no longer starts on a blind post-paint timer that can freeze live typing; instead, Atomic starts it in the background once input is ready and uses a readiness gate before the first normal prompt/model turn if the background load has not settled. This keeps first-paint/typeahead responsive while ensuring the first interactive prompt sees extension tools, skills, prompt templates, resources, and extension-registered provider/model updates. Built-in slash commands stay available immediately, and bundled extension slash commands expose lightweight metadata for autocomplete before their heavy implementations load; explicitly submitted extension slash commands load the implementation on demand and then route the same command. Explicit provider/model selections stay on the synchronous startup path because they must resolve against extension-registered providers before the session is created. Changelog and first-run notice materialization now happen after the first frame, and startup/input timing probes cover raw-mode enablement, first captured raw key, first frame, input-handler callback installation, and first submit for benchmark/probe runs.
+- Documented the built-in extension lazy-startup model: lightweight tools/commands register immediately while MCP connection warmup, workflow discovery, subagent maintenance, and web-access heavy provider loading run in the background or on explicit use.
+
+### Fixed
+
+- Fixed Windows native filesystem watchers to canonicalize watched paths before calling `fs.watch`, reject unresolved 8.3 short-name paths, and fall back to polling for unsafe watcher paths. This prevents libuv fs-event assertion crashes when temp, session, footer, or theme paths contain short-name components such as `USERNA~1`.
+- Fixed responses truncated at the output-token cap (`stopReason: "length"`) dead-ending the model's work with a "maximum output token limit" error when the context was still below the auto-compaction threshold. Previously auto-continuation only happened as a side effect of threshold compaction, so a length truncation with input room to spare left the task half-finished. Length-truncated turns now continue directly without compacting: the incomplete assistant is removed from retry context and the generation resumes automatically so the model finishes where it left off, bounded by a small consecutive-continuation cap so a turn that keeps exceeding the per-turn output cap still terminates. Compaction-driven `willRetry: true` continuations are now consistently tracked through the normal prompt lifecycle, so `AgentSession.prompt()` waits for threshold length-stop continuation before resolving instead of treating it as fire-and-forget.
+- Fixed auto-compaction after OpenAI Responses output-budget underflow errors such as `Invalid 'max_output_tokens': integer below minimum value. Expected a value >= 16, but got 1 instead.` Atomic now classifies that specific context-pressure failure as retry-worthy when the live context crosses the compaction threshold, removes the empty error assistant from retry context after compaction, and automatically continues from the preceding work anchor instead of waiting for the user to type `Continue`. Generic `invalid_request_body` errors such as malformed tool schemas are still not auto-retried, OpenAI Responses payload sanitization now prevents `max_output_tokens` values below the provider minimum of 16 from being sent, and repeated output-budget underflow continuation is capped at one compact-and-retry attempt so an unrecoverable context terminates visibly instead of looping or stalling.
+- Fixed bundled workflow durable resume for reusable `git_worktree_dir` worktrees so resumed runs reuse the original invocation repository/cwd and report slow Git subprocess timeouts as Git timeouts instead of repository-detection failures.
+- Removed the queued-message restore success status from the interactive UI so restoring queued messages silently returns them to the editor without showing transient restore copy.
+- Fixed bundled MCP proxy metadata paths so explicit cold-cache `search`, `describe`, and server-list requests hydrate lazy server metadata on demand without reconnecting all lazy servers during startup.
+
 ## [0.9.5-alpha.8] - 2026-07-08
 
 ### Added

package/dist/builtin/cursor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/cursor",
-  "version": "0.9.5-alpha.8",
+  "version": "0.9.5-alpha.9",
   "private": true,
   "description": "Experimental first-party Atomic extension for Cursor OAuth, model discovery, and streaming provider registration.",
   "contributors": [
@@ -40,7 +40,7 @@
     }
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.9.5-alpha.8",
+    "@bastani/atomic-natives": "0.9.5-alpha.9",
     "@bufbuild/protobuf": "^2.12.1",
     "@earendil-works/pi-ai": "^0.80.3"
   }

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.9.5-alpha.8",
+  "version": "0.9.5-alpha.9",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [

package/dist/builtin/mcp/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.5-alpha.9] - 2026-07-09
+
+### Changed
+
+- Improved startup responsiveness by keeping first-run/default lazy MCP metadata bootstrap out of `initializeMcp()`'s synchronous path. Cached direct tools and the MCP proxy still register immediately, explicit `eager`/`keep-alive` servers still connect during initialization, missing configured or `MCP_DIRECT_TOOLS`-selected direct-tool metadata is warmed in the background, and explicit proxy `search`, `describe`, and server-list requests hydrate cold-cache lazy server metadata on demand instead of broadening startup warmup. Warmed direct tools are registered live in the current session after metadata refresh rather than requiring restart. Cold-cache `describe` first narrows hydration to prefix-matched or explicitly requested servers, treats hyphen/underscore prefixes as aliases, and does not fan out to unrelated lazy servers after a prefix-directed miss; cold-cache proxy `search` intentionally hydrates all matching lazy servers so unscoped searches can see every configured tool.
+
+### Fixed
+
+- Aligned MCP tool result expansion hints with the CLI-wide `Ctrl+o` keybinding copy.
+- Fixed MCP background direct-tool warmup cancellation so stale in-flight connects are discarded before metadata/cache mutation, direct-tool refresh callbacks are guarded to the active session, completed warmups clear their active handle safely, and env-selected direct tool servers hydrate without forcing every lazy server eager.
+
 ## [0.9.4] - 2026-07-03
 
 ### Changed

package/dist/builtin/mcp/README.md

@@ -65,7 +65,7 @@ Precedence is:
 3. `.mcp.json`
 4. `.pi/mcp.json`
 
-Servers are **lazy by default** — they won't connect until you actually call one of their tools. The adapter caches tool metadata so search and describe work without live connections.
+Servers are **lazy by default** — they won't connect until you actually call one of their tools. The adapter caches tool metadata so search and describe work without live connections when a valid cache exists; on a cold cache, explicit proxy search/describe/server-list requests may connect lazy server(s) once to hydrate metadata on demand. `describe` narrows cold-cache hydration to an explicitly requested server or the server identified by the configured tool-name prefix before falling back to broader discovery. Unscoped `search` intentionally hydrates every configured lazy server that lacks cached metadata so the search can see all available tools.
 
 ```
 mcp({ search: "screenshot" })
@@ -136,7 +136,7 @@ Pi-specific files are the write targets for imported or shared global servers wh
 
 ### Lifecycle Modes
 
-- **`lazy`** (default) — Don't connect at startup. Connect on first tool call. Disconnect after idle timeout. Cached metadata keeps search/list working without connections.
+- **`lazy`** (default) — Don't connect at startup. Connect on first tool call or explicit cold-cache proxy metadata request (`search`, `describe`, or `server` list). Disconnect after idle timeout. Cached metadata keeps search/list working without connections.
 - **`eager`** — Connect at startup but don't auto-reconnect if the connection drops. No idle timeout by default (set `idleTimeout` explicitly to enable).
 - **`keep-alive`** — Connect at startup. Auto-reconnect via health checks. No idle timeout. Use for servers you always need available.
 
@@ -232,7 +232,7 @@ To exclude specific tools while still using `directTools: true`, add `excludeToo
 
 Each direct tool costs ~150-300 tokens in the system prompt (name + description + schema). Good for targeted sets of 5-20 tools. For servers with 75+ tools, stick with the proxy or pick specific tools with a `string[]`.
 
-Direct tools register from the metadata cache in the Pi agent dir (`~/.pi/agent/mcp-cache.json` by default, or `$PI_CODING_AGENT_DIR/mcp-cache.json` when set), so no server connections are needed at startup. On the first session after adding `directTools` to a new server, the cache won't exist yet — tools fall back to proxy-only and the cache populates in the background. To force it: `/mcp reconnect <server>`.
+Direct tools register from the metadata cache in the Pi agent dir (`~/.pi/agent/mcp-cache.json` by default, or `$PI_CODING_AGENT_DIR/mcp-cache.json` when set), so no server connections are needed at startup when the cache is warm. On the first session after adding `directTools` to a new server, or when a child/subagent selects tools through `MCP_DIRECT_TOOLS`, the cache may not exist yet — tools fall back to proxy-only while the selected/configured direct-tool servers populate in the background, then the extension refreshes tool registration so the warmed direct tools become available in the current session. To force it immediately: `/mcp reconnect <server>`.
 
 When you change direct-tool toggles in `/mcp` or write new config through `/mcp setup`, the extension triggers Pi's normal reload flow automatically. That refreshes extensions, prompts, skills, and MCP tool registration in one shot, so newly configured direct tools can appear without a manual restart.
 
@@ -332,7 +332,7 @@ Prefer `.mcp.json` for project-local shared MCP config. Use `.pi/mcp.json` only
 | Connect | `mcp({ connect: "server-name" })` |
 | UI messages | `mcp({ action: "ui-messages" })` |
 
-MCP proxy and direct-tool results render compactly by default: long text shows the first three lines plus a `CTRL+O Expand` hint, while the full result remains available when expanded and is still returned unchanged to the model.
+MCP proxy and direct-tool results render compactly by default: long text shows the first three lines plus a `Ctrl+o Expand` hint, while the full result remains available when expanded and is still returned unchanged to the model.
 
 Search includes both MCP tools and Pi tools (from extensions). Pi tools appear first with `[pi tool]` prefix. Space-separated words are OR'd.
 
@@ -358,8 +358,8 @@ In interactive sessions, you can also authenticate from `/mcp` with `CTRL+A` or
 ## How It Works
 
 - One `mcp` tool in context (~200 tokens) instead of hundreds
-- Servers are lazy by default — they connect on first tool call, not at startup
-- Tool metadata is cached to disk so search/list/describe work without live connections
+- Servers are lazy by default — they connect on first tool call or explicit cold-cache proxy metadata request, not at startup
+- Tool metadata is cached to disk so search/list/describe work without live connections when the cache is valid; cold-cache explicit search/describe/server-list requests hydrate metadata on demand
 - Idle servers disconnect after 10 minutes (configurable), reconnect automatically on next use
 - npx-based servers resolve to direct binary paths, skipping the ~143 MB npm parent process
 - MCP server validates arguments, not the adapter

package/dist/builtin/mcp/direct-tools.ts

@@ -72,6 +72,37 @@ async function attemptDirectAutoAuth(
   }
 }
 
+interface DirectToolSelection {
+  readonly servers: ReadonlySet<string>;
+  readonly toolsByServer: ReadonlyMap<string, ReadonlySet<string>>;
+}
+
+function parseDirectToolSelection(items: readonly string[] | undefined): DirectToolSelection {
+  const servers = new Set<string>();
+  const toolsByServer = new Map<string, Set<string>>();
+  for (const rawItem of items ?? []) {
+    const item = rawItem.replace(/\/+$/, "");
+    if (!item) continue;
+    if (!item.includes("/")) {
+      servers.add(item);
+      continue;
+    }
+    const [server, tool] = item.split("/", 2);
+    if (!server) continue;
+    if (!tool) {
+      servers.add(server);
+      continue;
+    }
+    if (!toolsByServer.has(server)) toolsByServer.set(server, new Set());
+    toolsByServer.get(server)!.add(tool);
+  }
+  return { servers, toolsByServer };
+}
+
+function directToolSelectionIncludes(selection: DirectToolSelection, serverName: string): boolean {
+  return selection.servers.has(serverName) || selection.toolsByServer.has(serverName);
+}
+
 export function resolveDirectTools(
   config: McpConfig,
   cache: MetadataCache | null,
@@ -83,24 +114,7 @@ export function resolveDirectTools(
 
   const seenNames = new Set<string>();
 
-  const envServers = new Set<string>();
-  const envTools = new Map<string, Set<string>>();
-  if (envOverride) {
-    for (let item of envOverride) {
-      item = item.replace(/\/+$/, "");
-      if (item.includes("/")) {
-        const [server, tool] = item.split("/", 2);
-        if (server && tool) {
-          if (!envTools.has(server)) envTools.set(server, new Set());
-          envTools.get(server)!.add(tool);
-        } else if (server) {
-          envServers.add(server);
-        }
-      } else if (item) {
-        envServers.add(item);
-      }
-    }
-  }
+  const envSelection = parseDirectToolSelection(envOverride);
 
   const globalDirect = config.settings?.directTools;
 
@@ -111,10 +125,10 @@ export function resolveDirectTools(
     let toolFilter: true | string[] | false = false;
 
     if (envOverride) {
-      if (envServers.has(serverName)) {
+      if (envSelection.servers.has(serverName)) {
         toolFilter = true;
-      } else if (envTools.has(serverName)) {
-        toolFilter = [...envTools.get(serverName)!];
+      } else if (envSelection.toolsByServer.has(serverName)) {
+        toolFilter = [...envSelection.toolsByServer.get(serverName)!];
       }
     } else {
       if (definition.directTools !== undefined) {
@@ -182,14 +196,18 @@ export function resolveDirectTools(
 export function getMissingConfiguredDirectToolServers(
   config: McpConfig,
   cache: MetadataCache | null,
+  envOverride?: readonly string[],
 ): string[] {
   const missing: string[] = [];
   const globalDirect = config.settings?.directTools;
-
+  const envSelection = parseDirectToolSelection(envOverride);
   for (const [serverName, definition] of Object.entries(config.mcpServers)) {
-    const hasDirectTools = definition.directTools !== undefined
+    const hasConfiguredDirectTools = definition.directTools !== undefined
       ? !!definition.directTools
       : !!globalDirect;
+    const hasDirectTools = envOverride
+      ? directToolSelectionIncludes(envSelection, serverName)
+      : hasConfiguredDirectTools;
 
     if (!hasDirectTools) continue;
 

package/dist/builtin/mcp/index.ts

@@ -39,6 +39,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
   let lifecycleGeneration = 0;
   let registeredDirectToolNames = new Set<string>();
   let registeredProxyTool = false;
+  let startupWarmupCancel: (() => void) | null = null;
 
   async function registerDirectToolsFromConfig(
     config: McpConfig,
@@ -50,13 +51,14 @@ export default function mcpAdapter(pi: ExtensionAPI) {
     ]);
     const prefix = config.settings?.toolPrefix ?? "server";
     const envRaw = process.env.MCP_DIRECT_TOOLS;
+    const envDirectTools = envRaw?.split(",").map(s => s.trim()).filter(Boolean);
     const directSpecs = envRaw === "__none__"
       ? []
       : resolveDirectTools(
           config,
           cache,
           prefix,
-          envRaw?.split(",").map(s => s.trim()).filter(Boolean),
+          envDirectTools,
         );
     for (const spec of directSpecs) {
       if (registeredDirectToolNames.has(spec.prefixedName)) continue;
@@ -75,7 +77,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
     refreshTools?.();
     return {
       directToolCount: directSpecs.length,
-      missingConfiguredDirectToolServers: getMissingConfiguredDirectToolServers(config, cache),
+      missingConfiguredDirectToolServers: getMissingConfiguredDirectToolServers(config, cache, envDirectTools),
     };
   }
 
@@ -129,12 +131,18 @@ export default function mcpAdapter(pi: ExtensionAPI) {
     type: "string",
   });
 
+  function cancelStartupWarmup(): void {
+    startupWarmupCancel?.();
+    startupWarmupCancel = null;
+  }
+
   pi.on("session_start", async (_event, ctx) => {
     const generation = ++lifecycleGeneration;
     const previousState = state;
     state = null;
     initPromise = null;
     registeredDirectToolNames = new Set<string>();
+    cancelStartupWarmup();
 
     try {
       const config = loadMcpConfig(earlyConfigPath, ctx.cwd);
@@ -168,7 +176,10 @@ export default function mcpAdapter(pi: ExtensionAPI) {
         throw new Error("Stale MCP session initialization cancelled before startup");
       }
 
-      const { initializeMcp, updateStatusBar } = await import("./init.ts");
+      const [{ initializeMcp, updateStatusBar }, { scheduleMcpStartupWarmup }] = await Promise.all([
+        import("./init.ts"),
+        import("./startup-warmup.ts"),
+      ]);
       if (generation !== lifecycleGeneration || !isContextActive(ctx)) {
         throw new Error("Stale MCP session initialization cancelled before startup");
       }
@@ -193,6 +204,21 @@ export default function mcpAdapter(pi: ExtensionAPI) {
       ) {
         registerProxyTool();
       }
+      let cancelWarmup: (() => void) | null = null;
+      const warmup = scheduleMcpStartupWarmup(nextState, {
+        shouldContinue: () => generation === lifecycleGeneration && state === nextState,
+        onDirectToolsChanged: async () => {
+          if (generation !== lifecycleGeneration || state !== nextState) return;
+          await registerDirectTools(nextState);
+        },
+        onSettled: () => {
+          if (generation === lifecycleGeneration && state === nextState && startupWarmupCancel === cancelWarmup) {
+            startupWarmupCancel = null;
+          }
+        },
+      });
+      cancelWarmup = () => warmup.cancel();
+      startupWarmupCancel = cancelWarmup;
       if (initPromise === promiseRef.current) {
         initPromise = null;
       }
@@ -226,6 +252,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
     state = null;
     initPromise = null;
     registeredDirectToolNames = new Set<string>();
+    cancelStartupWarmup();
 
     try {
       await Promise.all([
@@ -409,7 +436,7 @@ export default function mcpAdapter(pi: ExtensionAPI) {
           return executeConnect(state, params.connect);
         }
         if (params.describe) {
-          return executeDescribe(state, params.describe);
+          return executeDescribe(state, params.describe, params.server);
         }
         if (params.search) {
           return executeSearch(state, params.search, params.regex, params.server, params.includeSchemas);

package/dist/builtin/mcp/init.ts

@@ -21,7 +21,6 @@ import { buildToolMetadata, totalToolCount } from "./tool-metadata.ts";
 import { UiResourceHandler } from "./ui-resource-handler.ts";
 import { openUrl, parallelLimit } from "./utils.ts";
 import { logger } from "./logger.ts";
-import { getMissingConfiguredDirectToolServers } from "./direct-tools.ts";
 
 const FAILURE_BACKOFF_MS = 60 * 1000;
 
@@ -75,10 +74,7 @@ export async function initializeMcp(
   const cachePath = getMetadataCachePath();
   const cacheFileExists = existsSync(cachePath);
   let cache = loadMetadataCache();
-  let bootstrapAll = false;
-
   if (!cacheFileExists) {
-    bootstrapAll = true;
     saveMetadataCache({ version: 1, servers: {} });
   } else if (!cache) {
     cache = { version: 1, servers: {} };
@@ -105,12 +101,10 @@ export async function initializeMcp(
     }
   }
 
-  const startupServers = bootstrapAll
-    ? serverEntries
-    : serverEntries.filter(([, definition]) => {
-        const mode = definition.lifecycle ?? "lazy";
-        return mode === "keep-alive" || mode === "eager";
-      });
+  const startupServers = serverEntries.filter(([, definition]) => {
+    const mode = definition.lifecycle ?? "lazy";
+    return mode === "keep-alive" || mode === "eager";
+  });
 
   if (ctx.hasUI && startupServers.length > 0) {
     ctx.ui.setStatus("mcp", `MCP: connecting to ${startupServers.length} servers...`);
@@ -160,39 +154,6 @@ export async function initializeMcp(
     ctx.ui.notify(msg, "info");
   }
 
-  const envDirect = process.env.MCP_DIRECT_TOOLS;
-  if (envDirect !== "__none__") {
-    const currentCache = loadMetadataCache();
-    const missingCacheServers = getMissingConfiguredDirectToolServers(config, currentCache);
-
-    if (missingCacheServers.length > 0) {
-      const bootstrapResults = await parallelLimit(
-        missingCacheServers.filter(name => !results.some(r => r.name === name && r.connection)),
-        10,
-        async (name) => {
-          const definition = config.mcpServers[name];
-          try {
-            const connection = await manager.connect(name, definition);
-            if (connection.status === "needs-auth") {
-              return { name, ok: false };
-            }
-            const { metadata } = buildToolMetadata(connection.tools, connection.resources, definition, name, prefix);
-            toolMetadata.set(name, metadata);
-            updateMetadataCache(state, name);
-            return { name, ok: true };
-          } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            logger.debug(`MCP: direct-tools bootstrap failed for ${name}: ${message}`);
-            return { name, ok: false };
-          }
-        },
-      );
-      const bootstrapped = bootstrapResults.filter(r => r.ok).map(r => r.name);
-      if (bootstrapped.length > 0 && ctx.hasUI) {
-        ctx.ui.notify(`MCP: direct tools for ${bootstrapped.join(", ")} will be available after restart`, "info");
-      }
-    }
-  }
 
   lifecycle.setReconnectCallback((serverName) => {
     updateServerMetadata(state, serverName);

package/dist/builtin/mcp/metadata-hydration.ts

@@ -0,0 +1,37 @@
+import type { McpExtensionState } from "./state.ts";
+import { lazyConnect, updateMetadataCache, updateServerMetadata } from "./init.ts";
+import { parallelLimit } from "./utils.ts";
+
+export async function hydrateServerMetadata(
+  state: McpExtensionState,
+  serverName: string,
+): Promise<boolean> {
+  if (state.toolMetadata.has(serverName)) return true;
+  if (!state.config.mcpServers[serverName]) return false;
+
+  const connection = state.manager.getConnection(serverName);
+  if (connection?.status === "connected") {
+    updateServerMetadata(state, serverName);
+    updateMetadataCache(state, serverName);
+    return state.toolMetadata.has(serverName);
+  }
+
+  return lazyConnect(state, serverName);
+}
+
+export async function hydrateMissingMetadata(
+  state: McpExtensionState,
+  options?: { server?: string },
+): Promise<void> {
+  if (options?.server) {
+    await hydrateServerMetadata(state, options.server);
+    return;
+  }
+
+  const missingServers = Object.keys(state.config.mcpServers).filter(
+    (serverName) => !state.toolMetadata.has(serverName),
+  );
+  await parallelLimit(missingServers, 10, async (serverName) => {
+    await hydrateServerMetadata(state, serverName);
+  });
+}

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.9.5-alpha.8",
+  "version": "0.9.5-alpha.9",
   "private": true,
   "description": "Atomic extension that adapts MCP (Model Context Protocol) servers into the coding agent. Fork of: https://github.com/nicobailon/pi-mcp-adapter",
   "contributors": [

package/dist/builtin/mcp/proxy-info-modes.ts

@@ -1,9 +1,10 @@
 import type { McpExtensionState } from "./state.ts";
 import type { ToolMetadata } from "./types.ts";
-import { parseUiPromptHandoff } from "./types.ts";
+import { getServerPrefix, parseUiPromptHandoff } from "./types.ts";
 import { getFailureAgeSeconds } from "./init.ts";
 import { findToolByName, formatSchema } from "./tool-metadata.ts";
 import { truncateAtWord } from "./utils.ts";
+import { hydrateMissingMetadata } from "./metadata-hydration.ts";
 import type { ProxyToolResult } from "./proxy-types.ts";
 
 export function executeUiMessages(state: McpExtensionState): ProxyToolResult {
@@ -140,26 +141,73 @@ export function executeStatus(state: McpExtensionState): ProxyToolResult {
   };
 }
 
-export function executeDescribe(state: McpExtensionState, toolName: string): ProxyToolResult {
-  let serverName: string | undefined;
-  let toolMeta: ToolMetadata | undefined;
+function findToolMetadata(
+  state: McpExtensionState,
+  toolName: string,
+  server?: string,
+): { serverName: string; toolMeta: ToolMetadata } | null {
+  for (const [serverName, metadata] of state.toolMetadata.entries()) {
+    if (server && serverName !== server) continue;
+    const toolMeta = findToolByName(metadata, toolName);
+    if (toolMeta) return { serverName, toolMeta };
+  }
+  return null;
+}
 
-  for (const [server, metadata] of state.toolMetadata.entries()) {
-    const found = findToolByName(metadata, toolName);
-    if (found) {
-      serverName = server;
-      toolMeta = found;
-      break;
+function normalizeToolAlias(value: string): string {
+  return value.replace(/-/g, "_");
+}
+
+function prefixHydrationCandidates(state: McpExtensionState, toolName: string): string[] {
+  const prefixMode = state.config.settings?.toolPrefix ?? "server";
+  if (prefixMode === "none") return [];
+  const normalizedToolName = normalizeToolAlias(toolName);
+  return Object.keys(state.config.mcpServers)
+    .map((serverName) => ({ serverName, prefix: normalizeToolAlias(getServerPrefix(serverName, prefixMode)) }))
+    .filter(({ prefix }) => prefix.length > 0 && normalizedToolName.startsWith(`${prefix}_`))
+    .sort((a, b) => b.prefix.length - a.prefix.length)
+    .map(({ serverName }) => serverName);
+}
+
+async function hydrateDescribeMetadata(state: McpExtensionState, toolName: string, server?: string): Promise<void> {
+  if (server) {
+    await hydrateMissingMetadata(state, { server });
+    return;
+  }
+
+  const candidates = prefixHydrationCandidates(state, toolName);
+  if (candidates.length > 0) {
+    for (const candidate of candidates) {
+      await hydrateMissingMetadata(state, { server: candidate });
+      if (findToolMetadata(state, toolName, candidate)) return;
     }
+    return;
+  }
+
+  if (findToolMetadata(state, toolName)) return;
+  await hydrateMissingMetadata(state);
+}
+
+export async function executeDescribe(
+  state: McpExtensionState,
+  toolName: string,
+  server?: string,
+): Promise<ProxyToolResult> {
+  let found = findToolMetadata(state, toolName, server);
+  if (!found) {
+    await hydrateDescribeMetadata(state, toolName, server);
+    found = findToolMetadata(state, toolName, server);
   }
 
-  if (!serverName || !toolMeta) {
+  if (!found) {
     return {
       content: [{ type: "text" as const, text: `Tool "${toolName}" not found. Use mcp({ search: "..." }) to search.` }],
       details: { mode: "describe", error: "tool_not_found", requestedTool: toolName },
     };
   }
 
+  const { serverName, toolMeta } = found;
+
   let text = `${toolMeta.name}\n`;
   text += `Server: ${serverName}\n`;
   if (toolMeta.resourceUri) {
@@ -181,13 +229,13 @@ export function executeDescribe(state: McpExtensionState, toolName: string): Pro
   };
 }
 
-export function executeSearch(
+export async function executeSearch(
   state: McpExtensionState,
   query: string,
   regex?: boolean,
   server?: string,
   includeSchemas?: boolean,
-): ProxyToolResult {
+): Promise<ProxyToolResult> {
   const showSchemas = includeSchemas !== false;
 
   const matches: Array<{ server: string; tool: ToolMetadata }> = [];
@@ -213,6 +261,7 @@ export function executeSearch(
       details: { mode: "search", error: "invalid_pattern", query },
     };
   }
+  await hydrateMissingMetadata(state, { server });
 
   for (const [serverName, metadata] of state.toolMetadata.entries()) {
     if (server && serverName !== server) continue;
@@ -270,7 +319,7 @@ export function executeSearch(
   };
 }
 
-export function executeList(state: McpExtensionState, server: string): ProxyToolResult {
+export async function executeList(state: McpExtensionState, server: string): Promise<ProxyToolResult> {
   if (!state.config.mcpServers[server]) {
     return {
       content: [{ type: "text" as const, text: `Server "${server}" not found. Use mcp({}) to see available servers.` }],
@@ -278,6 +327,10 @@ export function executeList(state: McpExtensionState, server: string): ProxyTool
     };
   }
 
+  if (!state.toolMetadata.has(server)) {
+    await hydrateMissingMetadata(state, { server });
+  }
+
   const metadata = state.toolMetadata.get(server);
   const toolNames = metadata?.map(m => m.name) ?? [];
   const connection = state.manager.getConnection(server);