@herbertgao/pi-extensions 2026.9.11 → 2026.9.13

package/node_modules/pi-mcp-adapter/proxy-modes.ts

@@ -1,32 +1,52 @@
 import type { AgentToolResult, ToolInfo } from "@earendil-works/pi-coding-agent";
-import { UrlElicitationRequiredError, type Client, type Progress, type RequestOptions } from "@modelcontextprotocol/client";
+import { UrlElicitationRequiredError, type Client, type JsonSchemaType, type JsonSchemaValidator, type Progress, type RequestOptions } from "@modelcontextprotocol/client";
 import { createRequire } from "node:module";
 import type { McpExtensionState } from "./state.ts";
 import type { ToolMetadata, McpContent } from "./types.ts";
-import { getServerPrefix, isServerDisabled, parseUiPromptHandoff, type ServerEntry } from "./types.ts";
+import { getServerPrefix, getToolNameCandidates, isServerDisabled, parseUiPromptHandoff, resolveToolPrefix, type ServerEntry } from "./types.ts";
 import { lazyConnect, markKeepAliveAfterConnect, notifyToolMetadataUpdated, updateServerMetadata, updateMetadataCache, getFailureAgeSeconds, updateStatusBar, clearFailure, recordFailure } from "./init.ts";
 import { abortable, throwIfAborted } from "./abort.ts";
 import { combineAbortSignals, isAbortError } from "./runtime-owner.ts";
-import { buildToolMetadata, getToolNames, findToolByName, formatSchema } from "./tool-metadata.ts";
+import { buildToolMetadata, getToolNames, formatSchema } from "./tool-metadata.ts";
 import { renderTsShape } from "./ts-shape.ts";
 import { reconstructPromptMetadata } from "./metadata-cache.ts";
-import { resolveMcpResultContent, transformMcpContent, transformMcpResourceContents } from "./tool-registrar.ts";
+import { resolveMcpResultContent, transformMcpResourceContents } from "./tool-registrar.ts";
 import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from "./mcp-output-guard.ts";
 import { maybeStartUiSession, summarizeUiSessionResult, type UiSessionRuntime } from "./ui-session.ts";
 import { formatAuthRequiredMessage, formatMcpStatus, normalizeToolArguments, resolveServerUrl, truncateAtWord } from "./utils.ts";
 import { authenticate, completeAuthFromInput, getAuthStatus, startAuth, supportsOAuth } from "./mcp-auth-flow.ts";
 import { SessionRecoveryAuthRequiredError, withSessionRecovery } from "./session-recovery.ts";
+import { callToolViaTaskSession } from "./mcp-tasks.ts";
 import { paginate, rankSuggestions, rankToolMatches, resolveSearchKeywords } from "./search-ranking.ts";
 import { ensureToolCallApproved, isToolCallApprovalRequired } from "./tool-approval.ts";
 import { isServerInActiveFailureBackoff } from "./failure-backoff.ts";
+import { semanticSearch, type SemanticSearchBackend, type SemanticSearchEvaluator } from "./semantic-search.ts";
 import { getInputRequiredNeedsUiDetails } from "./errors.ts";
+import { createJsonSchemaValidator } from "./json-schema-validator.ts";
 
 type ProxyToolResult = AgentToolResult<Record<string, unknown>>;
 type ClientCallToolResult = Awaited<ReturnType<Client["callTool"]>>;
 type ClientReadResourceResult = Awaited<ReturnType<Client["readResource"]>>;
 
 const require = createRequire(import.meta.url);
+const proxyArgumentValidators = new WeakMap<object, JsonSchemaValidator<unknown>>();
 const MAX_REGEX_SEARCH_QUERY_LENGTH = 256;
+
+function proxyArgumentValidationError(inputSchema: unknown, args: unknown): string | null {
+  if (!inputSchema || typeof inputSchema !== "object" || Array.isArray(inputSchema)) return null;
+  try {
+    let validate = proxyArgumentValidators.get(inputSchema);
+    if (!validate) {
+      validate = createJsonSchemaValidator().getValidator(inputSchema as JsonSchemaType);
+      proxyArgumentValidators.set(inputSchema, validate);
+    }
+    const result = validate(args);
+    return result.valid ? null : result.errorMessage ?? "arguments do not match the advertised input schema";
+  } catch {
+    // Preserve server-side validation for schema dialects the adapter cannot evaluate.
+    return null;
+  }
+}
 const INSTRUCTIONS_PREVIEW_LENGTH = 300;
 const REGEX_SAFETY_CHECK_PARAMS = {
   attackTimeout: 50,
@@ -81,6 +101,17 @@ function getEnabledToolMatches(state: McpExtensionState, toolName: string, exact
   return matches;
 }
 
+function getEnabledOriginalToolMatches(state: McpExtensionState, toolName: string): { server: string; tool: ToolMetadata }[] {
+  const matches: { server: string; tool: ToolMetadata }[] = [];
+  for (const [server, metadata] of state.toolMetadata) {
+    if (isServerDisabled(state.config.mcpServers[server])) continue;
+    for (const tool of metadata) {
+      if (tool.originalName === toolName) matches.push({ server, tool });
+    }
+  }
+  return matches;
+}
+
 function serverBackoffResult(state: McpExtensionState, mode: string, serverName: string): ProxyToolResult {
   const failedAgo = getFailureAgeSeconds(state, serverName) ?? 0;
   const message = `Server "${serverName}" not available (last failed ${failedAgo}s ago)`;
@@ -90,28 +121,72 @@ function serverBackoffResult(state: McpExtensionState, mode: string, serverName:
   };
 }
 
-function getSingleToolMatch(metadata: ToolMetadata[] | undefined, toolName: string): ToolMetadata | "ambiguous" | undefined {
-  const exactMatches = getToolMatches(metadata, toolName, true);
-  const matches = exactMatches.length > 0 ? exactMatches : getToolMatches(metadata, toolName, false);
-  return matches.length > 1 ? "ambiguous" : matches[0];
+function getCandidateToolMatches(
+  metadata: ToolMetadata[] | undefined,
+  toolName: string,
+  serverName: string,
+  state: McpExtensionState,
+): ToolMetadata[] {
+  if (!metadata) return [];
+  const prefix = resolveToolPrefix(state.config.mcpServers[serverName], state.config.settings?.toolPrefix);
+  return metadata.filter((tool) => getToolNameCandidates(tool.originalName, serverName, prefix).has(toolName));
+}
+
+function getCandidateToolMatch(
+  metadata: ToolMetadata[] | undefined,
+  toolName: string,
+  serverName: string,
+  state: McpExtensionState,
+): ToolMetadata | "ambiguous" | undefined {
+  const exact = metadata?.filter((tool) => tool.name === toolName) ?? [];
+  if (exact.length > 0) return exact.length === 1 ? exact[0] : "ambiguous";
+  const candidates = getCandidateToolMatches(metadata, toolName, serverName, state);
+  return candidates.length > 1 ? "ambiguous" : candidates[0];
+}
+
+function getPrefixedServerScope(state: McpExtensionState, toolName: string): string | undefined {
+  const candidates = Object.entries(state.config.mcpServers)
+    .filter(([, definition]) => !isServerDisabled(definition))
+    .map(([name, definition]) => ({
+      name,
+      prefix: getServerPrefix(name, resolveToolPrefix(definition, state.config.settings?.toolPrefix)),
+    }))
+    .filter(({ prefix }) => prefix.length > 0 && toolName.startsWith(`${prefix}_`))
+    .sort((a, b) => b.prefix.length - a.prefix.length);
+  if (candidates.length === 0) return undefined;
+  const longest = candidates[0]!.prefix.length;
+  const best = candidates.filter(({ prefix }) => prefix.length === longest);
+  return best.length === 1 ? best[0]!.name : undefined;
 }
 
 type ServerScopedToolMatch = { tool: ToolMetadata; precedence: number } | "ambiguous";
 
-function getServerScopedToolMatch(metadata: ToolMetadata[] | undefined, toolName: string): ServerScopedToolMatch | undefined {
+function getServerScopedToolCandidates(
+  metadata: ToolMetadata[] | undefined,
+  toolName: string,
+): { tools: ToolMetadata[]; precedence: number } | undefined {
   if (!metadata) return undefined;
   const normalizedName = toolName.replace(/-/g, "_");
-  const matchesByPrecedence = [
-    metadata.filter((tool) => tool.name === toolName),
-    metadata.filter((tool) => tool.originalName === toolName),
-    metadata.filter((tool) => tool.name.replace(/-/g, "_") === normalizedName),
-    metadata.filter((tool) => tool.originalName.replace(/-/g, "_") === normalizedName),
-  ];
-  for (const [precedence, matches] of matchesByPrecedence.entries()) {
-    if (matches.length > 1) return "ambiguous";
-    if (matches.length === 1) return { tool: matches[0]!, precedence };
-  }
-  return undefined;
+  const exactDisplayedMatches = metadata.filter((tool) => tool.name === toolName);
+  if (exactDisplayedMatches.length > 0) return { tools: exactDisplayedMatches, precedence: 0 };
+  const exactOriginalMatches = metadata.filter((tool) => tool.originalName === toolName);
+  if (exactOriginalMatches.length > 0) return { tools: exactOriginalMatches, precedence: 1 };
+  const normalizedDisplayedMatches = metadata.filter((tool) => tool.name.replace(/-/g, "_") === normalizedName);
+  const normalizedOriginalMatches = metadata.filter((tool) => tool.originalName.replace(/-/g, "_") === normalizedName);
+  const normalizedMatches = new Set([...normalizedDisplayedMatches, ...normalizedOriginalMatches]);
+  if (normalizedMatches.size === 0) return undefined;
+  return {
+    tools: [...normalizedMatches],
+    precedence: normalizedDisplayedMatches.length > 0 ? 2 : 3,
+  };
+}
+
+function getServerScopedToolMatch(metadata: ToolMetadata[] | undefined, toolName: string): ServerScopedToolMatch | undefined {
+  const candidates = getServerScopedToolCandidates(metadata, toolName);
+  if (!candidates) return undefined;
+  return candidates.tools.length === 1
+    ? { tool: candidates.tools[0]!, precedence: candidates.precedence }
+    : "ambiguous";
 }
 
 function ambiguousToolResult(mode: "call" | "describe", toolName: string): ProxyToolResult {
@@ -122,6 +197,18 @@ function ambiguousToolResult(mode: "call" | "describe", toolName: string): Proxy
   };
 }
 
+function ambiguousServerToolResult(
+  mode: "call" | "describe",
+  toolName: string,
+  serverName: string,
+): ProxyToolResult {
+  const message = `Tool "${toolName}" matches multiple tools on server "${serverName}". Use an exact displayed or upstream tool name; run mcp({ server: "${serverName}" }) to list available tools.`;
+  return {
+    content: [{ type: "text" as const, text: message }],
+    details: { mode, error: "ambiguous_tool", server: serverName, requestedTool: toolName, message },
+  };
+}
+
 function disabledResult(mode: string, serverName: string): ProxyToolResult {
   const message = `Server "${serverName}" is disabled. Run /mcp enable ${serverName} and /reload to enable it.`;
   return {
@@ -606,23 +693,30 @@ export async function executeAuthComplete(state: McpExtensionState, serverName:
   }
 }
 
-export function executeDescribe(state: McpExtensionState, toolName: string): ProxyToolResult {
-  const exactMatches = getEnabledToolMatches(state, toolName, true)
-    .filter((match) => !isServerInActiveFailureBackoff(state, match.server));
-  if (exactMatches.length > 1) return ambiguousToolResult("describe", toolName);
-  if (exactMatches.length === 0 && getEnabledToolMatches(state, toolName, false).filter((match) => !isServerInActiveFailureBackoff(state, match.server)).length > 1) {
-    return ambiguousToolResult("describe", toolName);
-  }
-
-  let serverName = exactMatches[0]?.server;
-  let toolMeta = exactMatches[0]?.tool;
+export function executeDescribe(state: McpExtensionState, toolName: string, serverOverride?: string): ProxyToolResult {
+  let serverName: string | undefined;
+  let toolMeta: ToolMetadata | undefined;
   let disabledMatch: string | undefined;
   let failedMatch: string | undefined;
 
-  if (!toolMeta) {
+  if (serverOverride) {
+    if (!state.config.mcpServers[serverOverride]) {
+      return {
+        content: [{ type: "text" as const, text: `Server "${serverOverride}" not found. Use mcp({}) to see available servers.` }],
+        details: { mode: "describe", error: "server_not_found", server: serverOverride, requestedTool: toolName },
+      };
+    }
+    const match = getServerScopedToolMatch(state.toolMetadata.get(serverOverride), toolName);
+    if (match === "ambiguous") return ambiguousServerToolResult("describe", toolName, serverOverride);
+    if (isServerDisabled(state.config.mcpServers[serverOverride])) return disabledResult("describe", serverOverride);
+    if (isServerInActiveFailureBackoff(state, serverOverride)) return serverBackoffResult(state, "describe", serverOverride);
+    serverName = serverOverride;
+    toolMeta = match?.tool;
+  } else {
+    const matches: Array<{ server: string; tool: ToolMetadata; precedence: number }> = [];
     for (const [server, metadata] of state.toolMetadata.entries()) {
-      const found = findToolByName(metadata, toolName);
-      if (!found) continue;
+      const candidates = getServerScopedToolCandidates(metadata, toolName);
+      if (!candidates) continue;
       if (isServerDisabled(state.config.mcpServers[server])) {
         disabledMatch ??= server;
         continue;
@@ -631,20 +725,29 @@ export function executeDescribe(state: McpExtensionState, toolName: string): Pro
         failedMatch ??= server;
         continue;
       }
-      serverName = server;
-      toolMeta = found;
-      break;
+      for (const tool of candidates.tools) matches.push({ server, tool, precedence: candidates.precedence });
+    }
+    if (matches.length > 0) {
+      const precedence = Math.min(...matches.map(match => match.precedence));
+      const bestMatches = matches.filter(match => match.precedence === precedence);
+      if (bestMatches.length > 1) return ambiguousToolResult("describe", toolName);
+      serverName = bestMatches[0]!.server;
+      toolMeta = bestMatches[0]!.tool;
     }
   }
 
   if (!serverName || !toolMeta) {
     if (disabledMatch) return disabledResult("describe", disabledMatch);
     if (failedMatch) return serverBackoffResult(state, "describe", failedMatch);
-    const suggestions = rankSuggestions(state, toolName, 5);
+    const suggestions = rankSuggestions(state, toolName, 5, serverOverride);
     const suggestionText = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}` : "";
+    const scopeText = serverOverride ? ` on server "${serverOverride}"` : "";
+    const searchHint = serverOverride
+      ? `mcp({ search: "...", server: "${serverOverride}" })`
+      : `mcp({ search: "..." })`;
     return {
-      content: [{ type: "text" as const, text: `Tool "${toolName}" not found. Use mcp({ search: "..." }) to search.${suggestionText}` }],
-      details: { mode: "describe", error: "tool_not_found", requestedTool: toolName, suggestions },
+      content: [{ type: "text" as const, text: `Tool "${toolName}" not found${scopeText}. Use ${searchHint} to search.${suggestionText}` }],
+      details: { mode: "describe", error: "tool_not_found", server: serverOverride, requestedTool: toolName, suggestions },
     };
   }
 
@@ -673,6 +776,78 @@ export function executeDescribe(state: McpExtensionState, toolName: string): Pro
   };
 }
 
+function renderSearchResults(
+  state: McpExtensionState,
+  query: string,
+  server: string | undefined,
+  showSchemas: boolean,
+  limit: number,
+  offset: number,
+  matches: Array<{ server: string; tool: ToolMetadata; score: number }>,
+  backend?: SemanticSearchBackend,
+): ProxyToolResult {
+  const page = paginate(matches, offset, limit);
+  if (page.total === 0) {
+    const connectingServers = server
+      ? state.config.mcpServers[server] && state.manager.isConnecting(server) ? [server] : []
+      : Object.keys(state.config.mcpServers)
+        .filter(name => !isServerDisabled(state.config.mcpServers[name]) && state.manager.isConnecting(name))
+        .sort((a, b) => a.localeCompare(b));
+    const scope = server ? ` in "${server}"` : "";
+    const msg = backend?.requested === "semantic" && backend.used === "semantic" && backend.abstained
+      ? `Jev found no suitable tool for "${query}"${scope}`
+      : `No tools matching "${query}"${scope}`;
+    const connectingMessage = connectingServers.length === 1
+      ? ` Server "${connectingServers[0]}" is still connecting; retry in a moment.`
+      : connectingServers.length > 1
+        ? ` Servers ${connectingServers.map(name => `"${name}"`).join(", ")} are still connecting; retry in a moment.`
+        : "";
+    return {
+      content: [{ type: "text" as const, text: `${msg}${connectingMessage}` }],
+      details: {
+        mode: "search", matches: [], count: 0, hasMore: false, nextOffset: null, query,
+        ...(backend ? { backend } : {}),
+        ...(connectingServers.length > 0 ? { connectingServers } : {}),
+      },
+    };
+  }
+
+  let text = `Found ${page.total} tool${page.total === 1 ? "" : "s"} matching "${query}":\n\n`;
+  for (const match of page.items) {
+    const approvalMarker = isToolCallApprovalRequired(state.config, match.server, match.tool, state.toolMetadata)
+      ? " (requires approval)"
+      : "";
+    if (showSchemas) {
+      text += `${match.tool.name}${approvalMarker}\n`;
+      text += `  ${match.tool.description || "(no description)"}\n`;
+      if (match.tool.inputSchema && !match.tool.resourceUri) {
+        const shape = renderTsShape(match.tool.inputSchema);
+        text += shape === null
+          ? `\n  Parameters:\n${formatSchema(match.tool.inputSchema, "    ")}\n`
+          : `\n  Shape:\n${shape.split("\n").map(line => `    ${line}`).join("\n")}\n`;
+      } else if (match.tool.resourceUri) {
+        text += "  No parameters (resource tool).\n";
+      }
+      text += "\n";
+    } else {
+      text += `- ${match.tool.name}${approvalMarker}`;
+      if (match.tool.description) text += ` - ${truncateAtWord(match.tool.description, 50)}`;
+      text += "\n";
+    }
+  }
+  if (page.hasMore) text += `\n${page.items.length} of ${page.total} — offset: ${page.nextOffset} for more\n`;
+
+  return {
+    content: [{ type: "text" as const, text: text.trim() }],
+    details: {
+      mode: "search",
+      matches: page.items.map(match => ({ server: match.server, tool: match.tool.name, score: match.score })),
+      count: page.total, hasMore: page.hasMore, nextOffset: page.nextOffset, query,
+      ...(backend ? { backend } : {}),
+    },
+  };
+}
+
 export function executeSearch(
   state: McpExtensionState,
   query: string,
@@ -681,10 +856,36 @@ export function executeSearch(
   includeSchemas?: boolean,
   limit = 12,
   offset = 0,
-): ProxyToolResult {
+  searchMode: "lexical" | "semantic" = "lexical",
+  signal?: AbortSignal,
+  semanticEvaluator?: SemanticSearchEvaluator,
+): ProxyToolResult | Promise<ProxyToolResult> {
   const showSchemas = includeSchemas !== false;
+  if ((searchMode as string) !== "lexical" && (searchMode as string) !== "semantic") {
+    return {
+      content: [{ type: "text" as const, text: "Search mode must be lexical or semantic." }],
+      details: { mode: "search", error: "invalid_search_mode", query },
+    };
+  }
   if (server && isServerDisabled(state.config.mcpServers[server])) return disabledResult("search", server);
   if (server && isServerInActiveFailureBackoff(state, server)) return serverBackoffResult(state, "search", server);
+  if (searchMode === "semantic" && regex) {
+    return {
+      content: [{ type: "text" as const, text: "Semantic search cannot be combined with regex search." }],
+      details: { mode: "search", error: "invalid_search_mode", query },
+    };
+  }
+  if (searchMode === "semantic") {
+    return semanticSearch(state, query, server, signal, semanticEvaluator).then(result => {
+      if (!result.ok) {
+        return {
+          content: [{ type: "text" as const, text: `Semantic search failed: ${result.error.message}` }],
+          details: { mode: "search", error: result.error.code, message: result.error.message, query },
+        };
+      }
+      return renderSearchResults(state, query, server, showSchemas, limit, offset, result.matches, result.backend);
+    });
+  }
 
   let matches: Array<{ server: string; tool: ToolMetadata; score: number }>;
   if (regex) {
@@ -748,69 +949,7 @@ export function executeSearch(
     matches = rankToolMatches(state, query, server);
   }
 
-  const page = paginate(matches, offset, limit);
-  if (page.total === 0) {
-    const connectingServers = server
-      ? state.config.mcpServers[server] && state.manager.isConnecting(server) ? [server] : []
-      : Object.keys(state.config.mcpServers)
-        .filter(name => !isServerDisabled(state.config.mcpServers[name]) && state.manager.isConnecting(name))
-        .sort((a, b) => a.localeCompare(b));
-    const msg = server ? `No tools matching "${query}" in "${server}"` : `No tools matching "${query}"`;
-    const connectingMessage = connectingServers.length === 1
-      ? ` Server "${connectingServers[0]}" is still connecting; retry in a moment.`
-      : connectingServers.length > 1
-        ? ` Servers ${connectingServers.map(name => `"${name}"`).join(", ")} are still connecting; retry in a moment.`
-        : "";
-    return {
-      content: [{ type: "text" as const, text: `${msg}${connectingMessage}` }],
-      details: {
-        mode: "search",
-        matches: [],
-        count: 0,
-        hasMore: false,
-        nextOffset: null,
-        query,
-        ...(connectingServers.length > 0 ? { connectingServers } : {}),
-      },
-    };
-  }
-
-  let text = `Found ${page.total} tool${page.total === 1 ? "" : "s"} matching "${query}":\n\n`;
-  for (const match of page.items) {
-    const approvalMarker = isToolCallApprovalRequired(state.config, match.server, match.tool, state.toolMetadata)
-      ? " (requires approval)"
-      : "";
-    if (showSchemas) {
-      text += `${match.tool.name}${approvalMarker}\n`;
-      text += `  ${match.tool.description || "(no description)"}\n`;
-      if (match.tool.inputSchema && !match.tool.resourceUri) {
-        const shape = renderTsShape(match.tool.inputSchema);
-        text += shape === null
-          ? `\n  Parameters:\n${formatSchema(match.tool.inputSchema, "    ")}\n`
-          : `\n  Shape:\n${shape.split("\n").map(line => `    ${line}`).join("\n")}\n`;
-      } else if (match.tool.resourceUri) {
-        text += "  No parameters (resource tool).\n";
-      }
-      text += "\n";
-    } else {
-      text += `- ${match.tool.name}${approvalMarker}`;
-      if (match.tool.description) text += ` - ${truncateAtWord(match.tool.description, 50)}`;
-      text += "\n";
-    }
-  }
-  if (page.hasMore) text += `\n${page.items.length} of ${page.total} — offset: ${page.nextOffset} for more\n`;
-
-  return {
-    content: [{ type: "text" as const, text: text.trim() }],
-    details: {
-      mode: "search",
-      matches: page.items.map(match => ({ server: match.server, tool: match.tool.name, score: match.score })),
-      count: page.total,
-      hasMore: page.hasMore,
-      nextOffset: page.nextOffset,
-      query,
-    },
-  };
+  return renderSearchResults(state, query, server, showSchemas, limit, offset, matches);
 }
 
 export function executeList(state: McpExtensionState, server: string): ProxyToolResult {
@@ -1044,59 +1183,62 @@ export async function executeCall(
     };
   }
   if (serverName) {
-    const match = getServerScopedToolMatch(state.toolMetadata.get(serverName), toolName);
-    if (match === "ambiguous") return ambiguousToolResult("call", toolName);
-    toolMeta = match?.tool;
+    const match = getCandidateToolMatch(state.toolMetadata.get(serverName), toolName, serverName, state);
+    if (match === "ambiguous") return ambiguousServerToolResult("call", toolName, serverName);
+    toolMeta = match;
     if (isServerDisabled(state.config.mcpServers[serverName])) {
       return disabledCallResult(serverName, toolMeta);
     }
   } else {
     const exactMatches = getEnabledToolMatches(state, toolName, true);
     if (exactMatches.length > 1) return ambiguousToolResult("call", toolName);
-    if (exactMatches.length === 0 && getEnabledToolMatches(state, toolName, false).length > 1) {
-      return ambiguousToolResult("call", toolName);
-    }
-
-    let disabledMatch: { serverName: string; toolMeta: ToolMetadata } | undefined;
-    for (const [server, metadata] of state.toolMetadata.entries()) {
-      const found = metadata.find(tool => tool.name === toolName);
-      if (!found) continue;
-      if (isServerDisabled(state.config.mcpServers[server])) {
-        disabledMatch ??= { serverName: server, toolMeta: found };
-        continue;
+    if (exactMatches.length === 1) {
+      serverName = exactMatches[0]!.server;
+      toolMeta = exactMatches[0]!.tool;
+    } else {
+      const originalMatches = getEnabledOriginalToolMatches(state, toolName);
+      if (originalMatches.length > 1) return ambiguousToolResult("call", toolName);
+      if (originalMatches.length === 1) {
+        serverName = originalMatches[0]!.server;
+        toolMeta = originalMatches[0]!.tool;
+      } else {
+        const prefixedScope = getPrefixedServerScope(state, toolName);
+        if (prefixedScope) {
+          serverName = prefixedScope;
+          const match = getCandidateToolMatch(state.toolMetadata.get(prefixedScope), toolName, prefixedScope, state);
+          if (match === "ambiguous") return ambiguousServerToolResult("call", toolName, prefixedScope);
+          toolMeta = match;
+        } else {
+          const matches: Array<{ server: string; tool: ToolMetadata }> = [];
+          for (const [server, metadata] of state.toolMetadata) {
+            if (isServerDisabled(state.config.mcpServers[server])) continue;
+            for (const tool of getCandidateToolMatches(metadata, toolName, server, state)) matches.push({ server, tool });
+          }
+          if (matches.length > 1) return ambiguousToolResult("call", toolName);
+          if (matches.length === 1) {
+            serverName = matches[0]!.server;
+            toolMeta = matches[0]!.tool;
+          }
+        }
       }
-      serverName = server;
-      toolMeta = found;
-      break;
     }
-    if (!toolMeta && !disabledMatch) {
-      for (const [server, metadata] of state.toolMetadata.entries()) {
-        const found = findToolByName(metadata, toolName);
-        if (!found) continue;
-        if (isServerDisabled(state.config.mcpServers[server])) {
-          disabledMatch ??= { serverName: server, toolMeta: found };
-          continue;
-        }
-        serverName = server;
-        toolMeta = found;
-        break;
+
+    if (!toolMeta) {
+      const disabledMatches: Array<{ server: string; tool: ToolMetadata }> = [];
+      for (const [server, metadata] of state.toolMetadata) {
+        if (!isServerDisabled(state.config.mcpServers[server])) continue;
+        for (const tool of getCandidateToolMatches(metadata, toolName, server, state)) disabledMatches.push({ server, tool });
       }
+      if (disabledMatches.length === 1) return disabledCallResult(disabledMatches[0]!.server, disabledMatches[0]!.tool);
     }
-    if (!toolMeta && disabledMatch) return disabledCallResult(disabledMatch.serverName, disabledMatch.toolMeta);
   }
 
   if (serverName && !toolMeta) {
     const connected = await lazyConnect(state, serverName, ownedSignal);
     if (connected) {
-      if (serverOverride) {
-        const match = getServerScopedToolMatch(state.toolMetadata.get(serverName), toolName);
-        if (match === "ambiguous") return ambiguousToolResult("call", toolName);
-        toolMeta = match?.tool;
-      } else {
-        const match = getSingleToolMatch(state.toolMetadata.get(serverName), toolName);
-        if (match === "ambiguous") return ambiguousToolResult("call", toolName);
-        toolMeta = match;
-      }
+      const match = getCandidateToolMatch(state.toolMetadata.get(serverName), toolName, serverName, state);
+      if (match === "ambiguous") return ambiguousServerToolResult("call", toolName, serverName);
+      toolMeta = match;
     } else {
       const needsAuthConnection = state.manager.getConnection(serverName);
       if (needsAuthConnection?.status === "needs-auth") {
@@ -1114,11 +1256,11 @@ export async function executeCall(
             clearFailure(state, serverName);
             const connectedAfterAuth = await lazyConnect(state, serverName, ownedSignal);
             if (connectedAfterAuth) {
-              const match = getServerScopedToolMatch(state.toolMetadata.get(serverName), toolName);
-              if (match === "ambiguous") return ambiguousToolResult("call", toolName);
-              toolMeta = match?.tool;
+              const match = getCandidateToolMatch(state.toolMetadata.get(serverName), toolName, serverName, state);
+              if (match === "ambiguous") return ambiguousServerToolResult("call", toolName, serverName);
+              toolMeta = match;
               if (!toolMeta) {
-                const suggestions = rankSuggestions(state, toolName, 5);
+                const suggestions = rankSuggestions(state, toolName, 5, serverName);
                 const suggestionText = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}` : "";
                 return {
                   content: [{ type: "text" as const, text: `Tool "${toolName}" not found on "${serverName}" after reconnect.${suggestionText}` }],
@@ -1192,7 +1334,7 @@ export async function executeCall(
         lazyExactMatches.push({ serverName: configuredServer, toolMeta: exactMatches[0]! });
         continue;
       }
-      const fallbackMatches = getToolMatches(metadata, toolName, false);
+      const fallbackMatches = getCandidateToolMatches(metadata, toolName, configuredServer, state);
       if (fallbackMatches.length > 1) return ambiguousToolResult("call", toolName);
       if (fallbackMatches.length === 1) lazyFallbackMatches.push({ serverName: configuredServer, toolMeta: fallbackMatches[0]! });
     }
@@ -1223,7 +1365,7 @@ export async function executeCall(
     } else {
       msg += ` Use mcp({ search: "..." }) to search.`;
     }
-    const suggestions = rankSuggestions(state, toolName, 5);
+    const suggestions = rankSuggestions(state, toolName, 5, serverOverride);
     if (suggestions.length > 0) msg += ` Did you mean: ${suggestions.join(", ")}`;
     return {
       content: [{ type: "text" as const, text: msg }],
@@ -1233,7 +1375,7 @@ export async function executeCall(
 
   const callIdentity = toolMeta.resourceUri
     ? { server: serverName, resourceUri: toolMeta.resourceUri }
-    : { server: serverName, tool: toolMeta.originalName };
+    : { server: serverName, tool: toolMeta.originalName, canonicalTool: toolMeta.name };
 
   let connection = state.manager.getConnection(serverName);
   if (connection?.status === "needs-auth") {
@@ -1313,21 +1455,15 @@ export async function executeCall(
       if (!restored) notifyToolMetadataUpdated(state, serverName, "proxy-call-reconnect");
       markKeepAliveAfterConnect(state, serverName);
       updateStatusBar(state);
-      if (serverOverride) {
-        const match = getServerScopedToolMatch(state.toolMetadata.get(serverName), toolName);
-        if (match === "ambiguous") return ambiguousToolResult("call", toolName);
-        toolMeta = match?.tool;
-      } else {
-        const match = getSingleToolMatch(state.toolMetadata.get(serverName), toolName);
-        if (match === "ambiguous") return ambiguousToolResult("call", toolName);
-        toolMeta = match;
-      }
+      const match = getCandidateToolMatch(state.toolMetadata.get(serverName), toolName, serverName, state);
+      if (match === "ambiguous") return ambiguousServerToolResult("call", toolName, serverName);
+      toolMeta = match;
       if (!toolMeta) {
         const available = getToolNames(state, serverName);
         const hint = available.length > 0
           ? `Available tools on "${serverName}": ${available.join(", ")}`
           : `Server "${serverName}" has no tools.`;
-        const suggestions = rankSuggestions(state, toolName, 5);
+        const suggestions = rankSuggestions(state, toolName, 5, serverName);
         const suggestionText = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}` : "";
         return {
           content: [{ type: "text" as const, text: `Tool "${toolName}" not found on "${serverName}" after reconnect. ${hint}${suggestionText}` }],
@@ -1350,6 +1486,18 @@ export async function executeCall(
   }
 
   const normalizedArgs = toolMeta.resourceUri ? args ?? {} : normalizeToolArguments(args);
+  const validationError = toolMeta.resourceUri ? null : proxyArgumentValidationError(toolMeta.inputSchema, normalizedArgs);
+  if (validationError) {
+    const schemaText = `\n\nExpected parameters:\n${formatSchema(toolMeta.inputSchema)}`;
+    const guarded = await guardMcpOutput(
+      [{ type: "text" as const, text: validationError }],
+      { ...resolveMcpOutputGuardOptions(state.config.settings), prefix: "Failed to call tool: ", suffix: schemaText },
+    );
+    return {
+      content: guarded.content,
+      details: { mode: "call", error: "call_failed", ...callIdentity, message: validationError, ...guardedMcpDetails(guarded) },
+    };
+  }
   const approval = await ensureToolCallApproved(
     state,
     serverName,
@@ -1467,6 +1615,15 @@ export async function executeCall(
       serverName,
       async (conn) => {
         await state.manager.ensureListen?.(serverName, conn);
+        if (conn.taskSession) {
+          return await callToolViaTaskSession(conn.taskSession, {
+            name: toolMeta.originalName,
+            args: normalizedArgs ?? {},
+            meta: uiSession?.requestMeta,
+            signal: ownedSignal,
+            requestTimeoutMs: requestOptions?.timeout,
+          }) as unknown as ClientCallToolResult;
+        }
         return abortable(conn.client.callTool({
           name: toolMeta.originalName,
           arguments: normalizedArgs,
@@ -1487,11 +1644,9 @@ export async function executeCall(
 
     if (toolMeta.uiResourceUri) {
       if (result.isError) {
-        const mcpContent = (result.content ?? []) as McpContent[];
-        const content = transformMcpContent(mcpContent, state.owner?.signal);
+        const content = resolveMcpResultContent(result as Record<string, unknown>, state.owner?.signal);
         const outputContent = content.length > 0 ? content : [{ type: "text" as const, text: "(empty result)" }];
-        const schemaText = toolMeta.inputSchema ? `\n\nExpected parameters:\n${formatSchema(toolMeta.inputSchema)}` : "";
-        const guarded = await guardMcpOutput(outputContent, { ...outputGuardOptions, prefix: "Error: ", suffix: schemaText, emptyTextFallback: "Tool execution failed", rawMcpResult: result });
+        const guarded = await guardMcpOutput(outputContent, { ...outputGuardOptions, prefix: "Error: ", emptyTextFallback: "Tool execution failed", rawMcpResult: result });
         return {
           content: guarded.content,
           details: { mode: "call", error: "tool_error", ...callIdentity, ...guardedMcpDetails(guarded) },
@@ -1516,11 +1671,9 @@ export async function executeCall(
     }
 
     if (result.isError) {
-      const mcpContent = (result.content ?? []) as McpContent[];
-      const content = transformMcpContent(mcpContent, state.owner?.signal);
+      const content = resolveMcpResultContent(result as Record<string, unknown>, state.owner?.signal);
       const outputContent = content.length > 0 ? content : [{ type: "text" as const, text: "(empty result)" }];
-      const schemaText = toolMeta.inputSchema ? `\n\nExpected parameters:\n${formatSchema(toolMeta.inputSchema)}` : "";
-      const guarded = await guardMcpOutput(outputContent, { ...outputGuardOptions, prefix: "Error: ", suffix: schemaText, emptyTextFallback: "Tool execution failed", rawMcpResult: result });
+      const guarded = await guardMcpOutput(outputContent, { ...outputGuardOptions, prefix: "Error: ", emptyTextFallback: "Tool execution failed", rawMcpResult: result });
       return {
         content: guarded.content,
         details: { mode: "call", error: "tool_error", ...callIdentity, ...guardedMcpDetails(guarded) },