@sean.holung/minicode 0.3.4 → 0.3.5

package/dist/src/serve/mcp-server.js

@@ -10,6 +10,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { z } from "zod";
 import { getSymbolDisplayName } from "../indexer/symbol-names.js";
+import { formatAmbiguousSymbolMatches, resolveSymbolInput, } from "../shared/symbol-resolution.js";
 /** Active transports keyed by session ID. */
 const transports = new Map();
 /**
@@ -44,12 +45,19 @@ function createMcpServer(bridge, emit) {
     // ── Tools ──
     server.tool("read_symbol", "Read a specific function, class, interface, or type by name from the AST index. Returns source code, signature, dependencies, references, and annotations in one call — much more targeted than reading an entire file. PREFERRED over read_file for .ts/.tsx/.js/.jsx when you know the symbol name.", { name: z.string().describe("The symbol name or qualified name (e.g. 'Session' or 'Session.trim')") }, async ({ name }) => {
         return wrapToolCall("read_symbol", { name }, async () => {
-            const sym = bridge.getSymbol(name);
-            if (!sym) {
+            const resolution = resolveSymbolInput(bridge, name);
+            if (resolution.status === "missing") {
                 return { content: [{ type: "text", text: `Symbol "${name}" not found in the project index.` }], isError: true };
             }
-            const deps = bridge.getDependencies(name, 1);
-            const refs = bridge.getReferences(name);
+            if (resolution.status === "ambiguous") {
+                return {
+                    content: [{ type: "text", text: formatAmbiguousSymbolMatches("read_symbol", name, resolution.matches) }],
+                    isError: true,
+                };
+            }
+            const sym = resolution.symbol;
+            const deps = bridge.getDependencies(sym.qualifiedName, 1);
+            const refs = bridge.getReferences(sym.qualifiedName);
             const lines = [
                 `## ${sym.kind}: ${getSymbolDisplayName(sym)}`,
                 `File: ${sym.filePath}:${sym.startLine}`,
@@ -85,14 +93,28 @@ function createMcpServer(bridge, emit) {
             return { content: [{ type: "text", text: lines.join("\n") }] };
         });
     });
-    server.tool("find_references", "Find all symbols that call, import, or reference a given symbol. Essential for understanding impact before making changes.", { name: z.string().describe("The symbol name to find references for") }, async ({ name }) => {
+    server.tool("find_references", "Find all symbols that call, import, or reference a given symbol. Essential for understanding impact before making changes.", { name: z.string().describe("The symbol name or qualified name to find references for") }, async ({ name }) => {
         return wrapToolCall("find_references", { name }, async () => {
-            const refs = bridge.getReferences(name);
+            const resolution = resolveSymbolInput(bridge, name);
+            if (resolution.status === "missing") {
+                return { content: [{ type: "text", text: `Symbol "${name}" not found.` }], isError: true };
+            }
+            if (resolution.status === "ambiguous") {
+                return {
+                    content: [{ type: "text", text: formatAmbiguousSymbolMatches("find_references", name, resolution.matches) }],
+                    isError: true,
+                };
+            }
+            const symbol = resolution.symbol;
+            const refs = bridge.getReferences(symbol.qualifiedName);
             if (!refs || refs.length === 0) {
                 return { content: [{ type: "text", text: `No references found for "${name}".` }] };
             }
-            const lines = [`References to "${name}":`, ...refs.map((r) => `  - ${r.name ?? r.from} (${r.kind})`)];
-            const annotations = bridge.getAnnotationsForSymbol(name);
+            const lines = [
+                `References to ${getSymbolDisplayName(symbol)}:`,
+                ...refs.map((r) => `  - ${r.name ?? r.from} (${r.kind})`),
+            ];
+            const annotations = bridge.getAnnotationsForSymbol(symbol.qualifiedName);
             if (annotations.length > 0) {
                 lines.push("", `[User annotation: ${annotations.join("; ")}]`);
             }
@@ -100,19 +122,30 @@ function createMcpServer(bridge, emit) {
         });
     });
     server.tool("get_dependencies", "Get the dependency cone of a symbol — everything it calls, imports, extends, or references. Essential for understanding implementation and data flow.", {
-        name: z.string().describe("The symbol name to get dependencies for"),
+        name: z.string().describe("The symbol name or qualified name to get dependencies for"),
         depth: z.number().optional().default(2).describe("How many levels deep to traverse (default: 2)"),
     }, async ({ name, depth }) => {
         return wrapToolCall("get_dependencies", { name, depth }, async () => {
-            const deps = bridge.getDependencies(name, depth);
+            const resolution = resolveSymbolInput(bridge, name);
+            if (resolution.status === "missing") {
+                return { content: [{ type: "text", text: `Symbol "${name}" not found.` }], isError: true };
+            }
+            if (resolution.status === "ambiguous") {
+                return {
+                    content: [{ type: "text", text: formatAmbiguousSymbolMatches("get_dependencies", name, resolution.matches) }],
+                    isError: true,
+                };
+            }
+            const symbol = resolution.symbol;
+            const deps = bridge.getDependencies(symbol.qualifiedName, depth);
             if (!deps || deps.length === 0) {
                 return { content: [{ type: "text", text: `No dependencies found for "${name}".` }] };
             }
             const lines = [
-                `Dependencies of "${name}" (depth=${depth}):`,
+                `Dependencies of ${getSymbolDisplayName(symbol)} (depth=${depth}):`,
                 ...deps.map((d) => `  - ${d.qualifiedName} (${d.kind}) — ${d.filePath}`),
             ];
-            const annotations = bridge.getAnnotationsForSymbol(name);
+            const annotations = bridge.getAnnotationsForSymbol(symbol.qualifiedName);
             if (annotations.length > 0) {
                 lines.push("", `[User annotation: ${annotations.join("; ")}]`);
             }
@@ -140,29 +173,41 @@ function createMcpServer(bridge, emit) {
             }
             const lines = [
                 `Found ${matches.length} symbol(s) matching "${query}":`,
-                ...matches.map((s) => `  - ${s.name} (${s.kind}) — ${s.filePath}:${s.startLine}${s.signature ? `\n    ${s.signature}` : ""}`),
+                ...matches.map((s) => `  - ${s.name} (${s.kind}) — ${s.filePath}:${s.startLine} — qualified: ${s.qualifiedName}${s.signature ? `\n    ${s.signature}` : ""}`),
             ];
             return { content: [{ type: "text", text: lines.join("\n") }] };
         });
     });
     server.tool("find_path", "Find the shortest dependency path between two symbols, or trace a symbol back to an entry point. Useful for understanding how code connects.", {
-        from: z.string().describe("Source symbol name"),
-        to: z.string().optional().describe("Target symbol name. If omitted, traces back to the nearest entry point."),
+        from: z.string().describe("Source symbol name or qualified name"),
+        to: z.string().optional().describe("Target symbol name or qualified name. If omitted, traces back to the nearest entry point."),
     }, async ({ from, to }) => {
         return wrapToolCall("find_path", { from, to }, async () => {
             if (!bridge.hasIndex()) {
                 return { content: [{ type: "text", text: "No project index available." }], isError: true };
             }
-            // Use the bridge's project index via getSymbol to verify symbols exist
-            const fromSym = bridge.getSymbol(from);
-            if (!fromSym) {
+            const fromResolution = resolveSymbolInput(bridge, from);
+            if (fromResolution.status === "missing") {
                 return { content: [{ type: "text", text: `Symbol "${from}" not found.` }], isError: true };
             }
+            if (fromResolution.status === "ambiguous") {
+                return {
+                    content: [{ type: "text", text: formatAmbiguousSymbolMatches("find_path", from, fromResolution.matches) }],
+                    isError: true,
+                };
+            }
+            const fromSym = fromResolution.symbol;
             if (to) {
-                const toSym = bridge.getSymbol(to);
-                if (!toSym) {
+                const toResolution = resolveSymbolInput(bridge, to);
+                if (toResolution.status === "missing") {
                     return { content: [{ type: "text", text: `Symbol "${to}" not found.` }], isError: true };
                 }
+                if (toResolution.status === "ambiguous") {
+                    return {
+                        content: [{ type: "text", text: formatAmbiguousSymbolMatches("find_path", to, toResolution.matches) }],
+                        isError: true,
+                    };
+                }
             }
             // Delegate to the find_path tool via the tool registry
             // We need the actual ProjectIndex for this, so access it through the bridge's getGraph
@@ -189,7 +234,11 @@ function createMcpServer(bridge, emit) {
             }
             const startId = fromSym.qualifiedName;
             if (to) {
-                const toSym = bridge.getSymbol(to);
+                const toResolution = resolveSymbolInput(bridge, to);
+                if (toResolution.status !== "resolved") {
+                    return { content: [{ type: "text", text: `Symbol "${to}" could not be resolved.` }], isError: true };
+                }
+                const toSym = toResolution.symbol;
                 const endId = toSym.qualifiedName;
                 // BFS shortest path
                 const visited = new Set([startId]);

package/dist/src/serve/server.js

@@ -9,6 +9,7 @@ import { handleChatCompletions, handleModels } from "./openai-compat.js";
 import { formatConfigForDisplay, getConfigMissing } from "../agent/config.js";
 import { applyPersistedConfigUpdates, buildStructuredConfigPayload } from "../agent/editable-config.js";
 import { sortModelsAlphabetically } from "../model-utils.js";
+import { serializeSymbolMatch } from "../shared/symbol-resolution.js";
 import { handleMcpRequest } from "./mcp-server.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Resolve web dir: always serve from dist/src/web (built by scripts/build-web.mjs)
@@ -195,7 +196,19 @@ export function createRequestHandler(bridge, emit, options = {}) {
                 const name = decodeURIComponent(pathname.slice("/api/symbols/".length, -"/dependencies".length));
                 const depthParam = url.searchParams.get("depth");
                 const depth = depthParam ? Number(depthParam) : undefined;
-                const result = bridge.getDependencies(name, depth);
+                const matches = bridge.getSymbolMatches(name);
+                if (matches.length === 0) {
+                    sendJson(res, 404, { error: `Symbol "${name}" not found` });
+                    return;
+                }
+                if (matches.length > 1) {
+                    sendJson(res, 409, {
+                        error: `Symbol "${name}" is ambiguous`,
+                        candidates: matches.map(serializeSymbolMatch),
+                    });
+                    return;
+                }
+                const result = bridge.getDependencies(matches[0].qualifiedName, depth);
                 if (!result) {
                     sendJson(res, 404, { error: `Symbol "${name}" not found` });
                     return;
@@ -205,7 +218,19 @@ export function createRequestHandler(bridge, emit, options = {}) {
             }
             if (pathname.startsWith("/api/symbols/") && pathname.endsWith("/references") && method === "GET") {
                 const name = decodeURIComponent(pathname.slice("/api/symbols/".length, -"/references".length));
-                const result = bridge.getReferences(name);
+                const matches = bridge.getSymbolMatches(name);
+                if (matches.length === 0) {
+                    sendJson(res, 404, { error: `Symbol "${name}" not found` });
+                    return;
+                }
+                if (matches.length > 1) {
+                    sendJson(res, 409, {
+                        error: `Symbol "${name}" is ambiguous`,
+                        candidates: matches.map(serializeSymbolMatch),
+                    });
+                    return;
+                }
+                const result = bridge.getReferences(matches[0].qualifiedName);
                 if (!result) {
                     sendJson(res, 404, { error: `Symbol "${name}" not found` });
                     return;
@@ -215,11 +240,19 @@ export function createRequestHandler(bridge, emit, options = {}) {
             }
             if (pathname.startsWith("/api/symbols/") && pathname.endsWith("/source") && method === "GET") {
                 const name = decodeURIComponent(pathname.slice("/api/symbols/".length, -"/source".length));
-                const sym = bridge.getSymbol(name);
-                if (!sym) {
+                const matches = bridge.getSymbolMatches(name);
+                if (matches.length === 0) {
                     sendJson(res, 404, { error: `Symbol "${name}" not found` });
                     return;
                 }
+                if (matches.length > 1) {
+                    sendJson(res, 409, {
+                        error: `Symbol "${name}" is ambiguous`,
+                        candidates: matches.map(serializeSymbolMatch),
+                    });
+                    return;
+                }
+                const sym = matches[0];
                 try {
                     const fileContent = await readFile(path.resolve(config.workspaceRoot, sym.filePath), "utf8");
                     const lines = fileContent.split(/\r?\n/);

package/dist/src/shared/graph-symbols.js

@@ -0,0 +1,82 @@
+function dedupe(values) {
+    return [...new Set(values.filter((value) => value.length > 0))];
+}
+function stripCollisionSuffix(value) {
+    const hashIndex = value.indexOf("#");
+    return hashIndex >= 0 ? value.slice(0, hashIndex) : value;
+}
+function stripDisplayKindSuffix(value) {
+    return value.replace(/\s+\([^()]+\)$/, "");
+}
+export function getGraphNodeId(node, fallbackId = "") {
+    return node.qualifiedName || node.id || fallbackId || node.name || "";
+}
+export function getGraphNodeLabel(node, fallbackId = "") {
+    const label = node.name?.trim();
+    if (label && label.length > 0) {
+        return label;
+    }
+    const id = getGraphNodeId(node, fallbackId);
+    return id.split(".").pop() || id;
+}
+export function getGraphNodeAliases(node, fallbackId = "") {
+    const id = getGraphNodeId(node, fallbackId);
+    const label = getGraphNodeLabel(node, fallbackId);
+    const shortId = id.split(".").pop() || id;
+    return dedupe([
+        id,
+        node.id ?? "",
+        node.qualifiedName ?? "",
+        label,
+        stripDisplayKindSuffix(label),
+        shortId,
+        stripCollisionSuffix(shortId),
+        stripCollisionSuffix(id),
+    ]);
+}
+function compareLabels(a, b) {
+    return a.localeCompare(b, undefined, { sensitivity: "base" });
+}
+export function compareGraphNodeIds(a, b, nodes) {
+    const nodeA = nodes.get(a);
+    const nodeB = nodes.get(b);
+    const exportedA = nodeA ? Number(!!nodeA.exported) : 0;
+    const exportedB = nodeB ? Number(!!nodeB.exported) : 0;
+    if (exportedA !== exportedB) {
+        return exportedB - exportedA;
+    }
+    const labelA = getGraphNodeLabel(nodeA ?? {}, a);
+    const labelB = getGraphNodeLabel(nodeB ?? {}, b);
+    const labelComparison = compareLabels(labelA, labelB);
+    if (labelComparison !== 0) {
+        return labelComparison;
+    }
+    return compareLabels(a, b);
+}
+export function matchesGraphNodeQuery(query, node, fallbackId = "") {
+    const normalizedQuery = query.trim().toLowerCase();
+    if (normalizedQuery.length === 0) {
+        return false;
+    }
+    return getGraphNodeAliases(node, fallbackId).some((alias) => alias.toLowerCase().includes(normalizedQuery));
+}
+export function resolveGraphNodeIds(nodes, symbolName) {
+    const query = symbolName.trim();
+    if (query.length === 0) {
+        return [];
+    }
+    if (nodes.has(query)) {
+        return [query];
+    }
+    const exactMatches = [...nodes.entries()]
+        .filter(([id, node]) => getGraphNodeAliases(node, id).includes(query))
+        .map(([id]) => id)
+        .sort((a, b) => compareGraphNodeIds(a, b, nodes));
+    if (exactMatches.length > 0) {
+        return exactMatches;
+    }
+    return [...nodes.entries()]
+        .filter(([id, node]) => matchesGraphNodeQuery(query, node, id))
+        .map(([id]) => id)
+        .sort((a, b) => compareGraphNodeIds(a, b, nodes));
+}

package/dist/src/shared/symbol-resolution.js

@@ -0,0 +1,33 @@
+import { getSymbolDisplayName } from "../indexer/symbol-names.js";
+export function resolveSymbolInput(projectIndex, name) {
+    const matches = projectIndex.getSymbolMatches(name);
+    if (matches.length === 0) {
+        return { status: "missing" };
+    }
+    if (matches.length > 1) {
+        return { status: "ambiguous", matches };
+    }
+    return { status: "resolved", symbol: matches[0] };
+}
+export function formatSymbolMatch(match) {
+    return `${getSymbolDisplayName(match)} (${match.kind}) — ${match.filePath}:${match.startLine} — qualified: ${match.qualifiedName}`;
+}
+export function formatAmbiguousSymbolMatches(toolName, name, matches) {
+    return [
+        `Symbol "${name}" is ambiguous; ${matches.length} matches were found.`,
+        `Re-run ${toolName} with one of these qualified or disambiguated names:`,
+        "",
+        ...matches.map((match) => `- ${formatSymbolMatch(match)}`),
+    ].join("\n");
+}
+export function serializeSymbolMatch(match) {
+    return {
+        name: getSymbolDisplayName(match),
+        qualifiedName: match.qualifiedName,
+        kind: match.kind,
+        filePath: match.filePath,
+        startLine: match.startLine,
+        endLine: match.endLine,
+        signature: match.signature,
+    };
+}

package/dist/src/tools/find-path.js

@@ -1,5 +1,6 @@
 import { expectNonEmptyString, expectOptionalNumber } from "@minicode/agent-sdk";
 import { getSymbolDisplayName } from "../indexer/symbol-names.js";
+import { formatAmbiguousSymbolMatches, resolveSymbolInput, } from "../shared/symbol-resolution.js";
 export function createFindPathTool(projectIndex) {
     return {
         name: "find_path",
@@ -27,17 +28,25 @@ export function createFindPathTool(projectIndex) {
             const from = expectNonEmptyString(input, "from");
             const to = typeof input.to === "string" && input.to.length > 0 ? input.to : undefined;
             const maxDepth = expectOptionalNumber(input, "max_depth");
-            const fromSymbol = projectIndex.getSymbol(from);
-            if (!fromSymbol) {
+            const fromResolution = resolveSymbolInput(projectIndex, from);
+            if (fromResolution.status === "missing") {
                 return `Symbol "${from}" not found in the project index.`;
             }
+            if (fromResolution.status === "ambiguous") {
+                return formatAmbiguousSymbolMatches("find_path", from, fromResolution.matches);
+            }
+            const fromSymbol = fromResolution.symbol;
             if (to) {
                 // Path between two symbols
-                const toSymbol = projectIndex.getSymbol(to);
-                if (!toSymbol) {
+                const toResolution = resolveSymbolInput(projectIndex, to);
+                if (toResolution.status === "missing") {
                     return `Symbol "${to}" not found in the project index.`;
                 }
-                const path = projectIndex.findPath(from, to, maxDepth ?? 10);
+                if (toResolution.status === "ambiguous") {
+                    return formatAmbiguousSymbolMatches("find_path", to, toResolution.matches);
+                }
+                const toSymbol = toResolution.symbol;
+                const path = projectIndex.findPath(fromSymbol.qualifiedName, toSymbol.qualifiedName, maxDepth ?? 10);
                 if (path.length === 0) {
                     return `No path found between "${from}" and "${to}".`;
                 }
@@ -53,7 +62,7 @@ export function createFindPathTool(projectIndex) {
             }
             else {
                 // Trace to entry point(s)
-                const paths = projectIndex.findPathToEntryPoint(from, maxDepth ?? 20);
+                const paths = projectIndex.findPathToEntryPoint(fromSymbol.qualifiedName, maxDepth ?? 20);
                 if (paths.length === 0) {
                     return `No entry point paths found for "${from}". It may itself be an entry point.`;
                 }

package/dist/src/tools/find-references.js

@@ -1,5 +1,6 @@
 import { expectNonEmptyString, expectOptionalNumber } from "@minicode/agent-sdk";
 import { getSymbolDisplayName } from "../indexer/symbol-names.js";
+import { formatAmbiguousSymbolMatches, resolveSymbolInput, } from "../shared/symbol-resolution.js";
 const DEFAULT_LIMIT = 50;
 export function createFindReferencesTool(projectIndex) {
     return {
@@ -28,10 +29,14 @@ export function createFindReferencesTool(projectIndex) {
             const name = expectNonEmptyString(input, "name");
             const skip = Math.max(0, expectOptionalNumber(input, "skip") ?? 0);
             const limit = Math.max(1, Math.min(100, expectOptionalNumber(input, "limit") ?? DEFAULT_LIMIT));
-            const symbol = projectIndex.getSymbol(name);
-            if (!symbol) {
+            const resolution = resolveSymbolInput(projectIndex, name);
+            if (resolution.status === "missing") {
                 return `Symbol "${name}" not found in the project index.`;
             }
+            if (resolution.status === "ambiguous") {
+                return formatAmbiguousSymbolMatches("find_references", name, resolution.matches);
+            }
+            const symbol = resolution.symbol;
             const refs = projectIndex.dependencyEdges.filter((e) => e.to === symbol.qualifiedName || e.to === symbol.name);
             if (refs.length === 0) {
                 return `No references found for "${name}".`;

package/dist/src/tools/get-dependencies.js

@@ -1,5 +1,6 @@
 import { expectNonEmptyString, expectOptionalNumber } from "@minicode/agent-sdk";
 import { getSymbolDisplayName } from "../indexer/symbol-names.js";
+import { formatAmbiguousSymbolMatches, resolveSymbolInput, } from "../shared/symbol-resolution.js";
 export function createGetDependenciesTool(projectIndex) {
     return {
         name: "get_dependencies",
@@ -32,11 +33,15 @@ export function createGetDependenciesTool(projectIndex) {
             const depth = expectOptionalNumber(input, "depth") ?? 1;
             const skip = Math.max(0, expectOptionalNumber(input, "skip") ?? 0);
             const limit = Math.max(1, Math.min(100, expectOptionalNumber(input, "limit") ?? 50));
-            const symbol = projectIndex.getSymbol(name);
-            if (!symbol) {
+            const resolution = resolveSymbolInput(projectIndex, name);
+            if (resolution.status === "missing") {
                 return `Symbol "${name}" not found in the project index.`;
             }
-            const cone = projectIndex.getDependencyCone(name, depth);
+            if (resolution.status === "ambiguous") {
+                return formatAmbiguousSymbolMatches("get_dependencies", name, resolution.matches);
+            }
+            const symbol = resolution.symbol;
+            const cone = projectIndex.getDependencyCone(symbol.qualifiedName, depth);
             const shown = cone.slice(skip, skip + limit);
             const lines = shown.map((s) => {
                 const header = `${s.kind} ${getSymbolDisplayName(s)}`;

package/dist/src/tools/read-symbol.js

@@ -1,12 +1,14 @@
 import { readFile, stat } from "node:fs/promises";
 import { resolveWorkspacePath, validateFileReadSize, expectNonEmptyString, expectOptionalBoolean, } from "@minicode/agent-sdk";
 import { getSymbolDisplayName } from "../indexer/symbol-names.js";
+import { formatAmbiguousSymbolMatches, resolveSymbolInput, } from "../shared/symbol-resolution.js";
 const LEADING_CONTEXT_LINES = 3;
 export function createReadSymbolTool(config, projectIndex) {
     return {
         name: "read_symbol",
         description: "Read a specific function, class, or type definition by name. " +
             "Returns the symbol's source code, referenced types, callers, and callees. " +
+            "If a bare name matches multiple symbols, returns disambiguation candidates. " +
             "PREFER this over read_file for .ts/.tsx/.js/.jsx — use the code map to find symbol names.",
         inputSchema: {
             type: "object",
@@ -26,10 +28,14 @@ export function createReadSymbolTool(config, projectIndex) {
         execute: async (input) => {
             const name = expectNonEmptyString(input, "name");
             const includeBody = expectOptionalBoolean(input, "includeBody") ?? true;
-            const symbol = projectIndex.getSymbol(name);
-            if (!symbol) {
+            const resolution = resolveSymbolInput(projectIndex, name);
+            if (resolution.status === "missing") {
                 return `Symbol "${name}" not found in the project index. Try using search to find it, or use read_file to read the full file.`;
             }
+            if (resolution.status === "ambiguous") {
+                return formatAmbiguousSymbolMatches("read_symbol", name, resolution.matches);
+            }
+            const symbol = resolution.symbol;
             const filePath = resolveWorkspacePath(symbol.filePath, config.workspaceRoot);
             const fileStat = await stat(filePath);
             if (!fileStat.isFile()) {
@@ -75,7 +81,7 @@ export function createReadSymbolTool(config, projectIndex) {
                 if (calls.length > 0) {
                     parts.push("", "## Calls", "", calls.map((s) => `- ${s}`).join("\n"));
                 }
-                const cone = projectIndex.getDependencyCone(name, 1);
+                const cone = projectIndex.getDependencyCone(symbol.qualifiedName, 1);
                 const typeRefs = cone.filter((s) => s.qualifiedName !== symbol.qualifiedName &&
                     (s.kind === "interface" || s.kind === "type"));
                 if (typeRefs.length > 0) {

package/dist/src/tools/registry.js

@@ -14,6 +14,9 @@ export function createToolRegistry(config, projectIndex) {
         ? {
             afterWrite: (relPath, content) => projectIndex.reindexFile(relPath, content),
             afterEdit: (relPath, content) => projectIndex.reindexFile(relPath, content),
+            afterCommand: async () => {
+                await projectIndex.refreshFromWorkspace();
+            },
         }
         : undefined;
     const tools = [
@@ -22,7 +25,7 @@ export function createToolRegistry(config, projectIndex) {
         createEditFileTool(config, hooks ? { afterEdit: hooks.afterEdit } : undefined),
         createSearchTool(config),
         createListFilesTool(config),
-        createRunCommandTool(config),
+        createRunCommandTool(config, hooks ? { afterCommand: hooks.afterCommand } : undefined),
     ];
     if (projectIndex) {
         tools.splice(1, 0, createReadSymbolTool(config, projectIndex));

package/dist/src/tools/search-code-map.js

@@ -1,6 +1,21 @@
 import { expectNonEmptyString, expectOptionalNumber } from "@minicode/agent-sdk";
 import { getSymbolDisplayName, getSymbolLookupNames } from "../indexer/symbol-names.js";
 const DEFAULT_LIMIT = 30;
+function compareMatchedSymbols(pattern, a, b) {
+    const lowerPattern = pattern.toLowerCase();
+    const aDisplay = getSymbolDisplayName(a).toLowerCase();
+    const bDisplay = getSymbolDisplayName(b).toLowerCase();
+    const aExact = Number(aDisplay === lowerPattern || a.qualifiedName.toLowerCase() === lowerPattern || a.name.toLowerCase() === lowerPattern);
+    const bExact = Number(bDisplay === lowerPattern || b.qualifiedName.toLowerCase() === lowerPattern || b.name.toLowerCase() === lowerPattern);
+    if (aExact !== bExact) {
+        return bExact - aExact;
+    }
+    return Number(b.exported) - Number(a.exported) ||
+        aDisplay.localeCompare(bDisplay) ||
+        a.filePath.localeCompare(b.filePath) ||
+        a.startLine - b.startLine ||
+        a.qualifiedName.localeCompare(b.qualifiedName);
+}
 function matchesPattern(text, pattern) {
     const lowerText = text.toLowerCase();
     const lowerPattern = pattern.toLowerCase();
@@ -11,7 +26,7 @@ export function createSearchCodeMapTool(projectIndex) {
         name: "search_code_map",
         description: "Search the full project index for symbols by name or substring. " +
             "Use when the code map is truncated and you need to find a symbol not listed. " +
-            "Returns qualified names and file paths; use read_symbol with the result.",
+            "Returns disambiguated display names, qualified names, and file paths; use read_symbol with the result.",
         inputSchema: {
             type: "object",
             properties: {
@@ -53,9 +68,9 @@ export function createSearchCodeMapTool(projectIndex) {
                     return false;
                 }
                 return true;
-            });
+            }).sort((a, b) => compareMatchedSymbols(pattern, a, b));
             const shown = matches.slice(skip, skip + limit);
-            const lines = shown.map((s) => `- ${getSymbolDisplayName(s)} (${s.kind}) — ${s.filePath}`);
+            const lines = shown.map((s) => `- ${getSymbolDisplayName(s)} (${s.kind}) — ${s.filePath}:${s.startLine} — qualified: ${s.qualifiedName}`);
             const remaining = matches.length - skip - shown.length;
             const footer = remaining > 0
                 ? `\n... and ${remaining} more (use skip: ${skip + limit}, limit: ${limit} for next page)`