@colbymchenry/codegraph 0.6.8 → 0.7.2

package/dist/mcp/tools.d.ts

@@ -4,6 +4,12 @@
  * Defines the tools exposed by the CodeGraph MCP server.
  */
 import CodeGraph from '../index';
+/**
+ * Calculate the recommended number of codegraph_explore calls based on project size.
+ * Larger codebases need more exploration calls to cover their surface area,
+ * but smaller ones should use fewer to avoid unnecessary overhead.
+ */
+export declare function getExploreBudget(fileCount: number): number;
 /**
  * MCP Tool definition
  */
@@ -59,6 +65,12 @@ export declare class ToolHandler {
      * Whether a default CodeGraph instance is available
      */
     hasDefaultCodeGraph(): boolean;
+    /**
+     * Get tool definitions with dynamic descriptions based on project size.
+     * The codegraph_explore tool description includes a budget recommendation
+     * scaled to the number of indexed files.
+     */
+    getTools(): ToolDefinition[];
     /**
      * Get CodeGraph instance for a project
      *
@@ -105,6 +117,16 @@ export declare class ToolHandler {
      * Handle codegraph_impact
      */
     private handleImpact;
+    /** Maximum output for explore tool — sized to stay under MCP client token limits (~10k tokens) */
+    private static readonly EXPLORE_MAX_OUTPUT;
+    /**
+     * Handle codegraph_explore — deep exploration in a single call
+     *
+     * Strategy: find relevant symbols via graph traversal, group by file,
+     * then read contiguous file sections covering all symbols per file.
+     * This replaces multiple codegraph_node + Read calls.
+     */
+    private handleExplore;
     /**
      * Handle codegraph_node
      */
@@ -137,7 +159,18 @@ export declare class ToolHandler {
      * Find a symbol by name, handling disambiguation when multiple matches exist.
      * Returns the best match and a note about alternatives if any.
      */
+    /**
+     * Check if a node matches a symbol query, supporting both simple names and
+     * qualified "Parent.child" notation (e.g., "Session.request" matches a method
+     * named "request" inside a class named "Session").
+     */
+    private matchesSymbol;
     private findSymbol;
+    /**
+     * Find ALL symbols matching a name. Used by callers/callees/impact to aggregate
+     * results across all matching symbols (e.g., multiple classes with an `execute` method).
+     */
+    private findAllSymbols;
     /**
      * Truncate output if it exceeds the maximum length
      */

package/dist/mcp/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,SAAuC,MAAM,UAAU,CAAC;AAyB/D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;QAC3C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAUD;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,EAAE,cAAc,EA8KjC,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,WAAW;IAIV,OAAO,CAAC,EAAE;IAFtB,OAAO,CAAC,YAAY,CAAqC;gBAErC,EAAE,EAAE,SAAS,GAAG,IAAI;IAExC;;OAEG;IACH,mBAAmB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IAIxC;;OAEG;IACH,mBAAmB,IAAI,OAAO;IAI9B;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IAqCpB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAOhB;;OAEG;IACH,OAAO,CAAC,cAAc;IAOtB;;OAEG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IA2BnF;;OAEG;YACW,YAAY;IAsB1B;;OAEG;YACW,aAAa;IAmC3B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAyB/B;;OAEG;YACW,aAAa;IAuB3B;;OAEG;YACW,aAAa;IAuB3B;;OAEG;YACW,YAAY;IAkB1B;;OAEG;YACW,UAAU;IAuBxB;;OAEG;YACW,YAAY;IA+B1B;;OAEG;YACW,WAAW;IAgDzB;;OAEG;IACH,OAAO,CAAC,WAAW;IAUnB;;OAEG;IACH,OAAO,CAAC,eAAe;IAcvB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA6B1B;;OAEG;IACH,OAAO,CAAC,eAAe;IA4EvB;;;OAGG;IACH,OAAO,CAAC,UAAU;IA4BlB;;OAEG;IACH,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,mBAAmB;IAgB3B,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,YAAY;IA4BpB,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,WAAW;CAMpB"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,SAAuC,MAAM,UAAU,CAAC;AAW/D;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAM1D;AAgBD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;QAC3C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAUD;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,EAAE,cAAc,EAkMjC,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,WAAW;IAIV,OAAO,CAAC,EAAE;IAFtB,OAAO,CAAC,YAAY,CAAqC;gBAErC,EAAE,EAAE,SAAS,GAAG,IAAI;IAExC;;OAEG;IACH,mBAAmB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IAIxC;;OAEG;IACH,mBAAmB,IAAI,OAAO;IAI9B;;;;OAIG;IACH,QAAQ,IAAI,cAAc,EAAE;IAqB5B;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IAqCpB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAOhB;;OAEG;IACH,OAAO,CAAC,cAAc;IAOtB;;OAEG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IA6BnF;;OAEG;YACW,YAAY;IAsB1B;;OAEG;YACW,aAAa;IAmC3B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAyB/B;;OAEG;YACW,aAAa;IAgC3B;;OAEG;YACW,aAAa;IAgC3B;;OAEG;YACW,YAAY;IAyC1B,kGAAkG;IAClG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAEnD;;;;;;OAMG;YACW,aAAa;IAgQ3B;;OAEG;YACW,UAAU;IAuBxB;;OAEG;YACW,YAAY;IA+B1B;;OAEG;YACW,WAAW;IAgDzB;;OAEG;IACH,OAAO,CAAC,WAAW;IAUnB;;OAEG;IACH,OAAO,CAAC,eAAe;IAcvB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA6B1B;;OAEG;IACH,OAAO,CAAC,eAAe;IA4EvB;;;OAGG;IACH;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,UAAU;IA8BlB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAqBtB;;OAEG;IACH,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,mBAAmB;IAgB3B,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,YAAY;IA4BpB,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,WAAW;CAMpB"}

package/dist/mcp/tools.js

@@ -39,6 +39,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolHandler = exports.tools = void 0;
+exports.getExploreBudget = getExploreBudget;
 const index_1 = __importStar(require("../index"));
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
@@ -47,6 +48,22 @@ const os_1 = require("os");
 const path_1 = require("path");
 /** Maximum output length to prevent context bloat (characters) */
 const MAX_OUTPUT_LENGTH = 15000;
+/**
+ * Calculate the recommended number of codegraph_explore calls based on project size.
+ * Larger codebases need more exploration calls to cover their surface area,
+ * but smaller ones should use fewer to avoid unnecessary overhead.
+ */
+function getExploreBudget(fileCount) {
+    if (fileCount < 500)
+        return 1;
+    if (fileCount < 5000)
+        return 2;
+    if (fileCount < 15000)
+        return 3;
+    if (fileCount < 25000)
+        return 4;
+    return 5;
+}
 /**
  * Mark a Claude session as having consulted MCP tools.
  * This enables Grep/Glob/Bash commands that would otherwise be blocked.
@@ -207,6 +224,26 @@ exports.tools = [
             required: ['symbol'],
         },
     },
+    {
+        name: 'codegraph_explore',
+        description: 'Deep exploration tool — returns comprehensive context for a topic in a SINGLE call. Groups all relevant source code by file (contiguous sections, not snippets), includes a relationship map, and uses deeper graph traversal. Designed to replace multiple codegraph_node + file Read calls. Use this instead of codegraph_context when you need thorough understanding.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'What you want to understand (e.g., "undo redo system", "authentication flow", "how routing works")',
+                },
+                maxFiles: {
+                    type: 'number',
+                    description: 'Maximum number of files to include source code from (default: 12)',
+                    default: 12,
+                },
+                projectPath: projectPathProperty,
+            },
+            required: ['query'],
+        },
+    },
     {
         name: 'codegraph_status',
         description: 'Get the status of the CodeGraph index, including statistics about indexed files, nodes, and edges.',
@@ -276,6 +313,31 @@ class ToolHandler {
     hasDefaultCodeGraph() {
         return this.cg !== null;
     }
+    /**
+     * Get tool definitions with dynamic descriptions based on project size.
+     * The codegraph_explore tool description includes a budget recommendation
+     * scaled to the number of indexed files.
+     */
+    getTools() {
+        if (!this.cg)
+            return exports.tools;
+        try {
+            const stats = this.cg.getStats();
+            const budget = getExploreBudget(stats.fileCount);
+            return exports.tools.map(tool => {
+                if (tool.name === 'codegraph_explore') {
+                    return {
+                        ...tool,
+                        description: `${tool.description} Budget: make at most ${budget} calls for this project (${stats.fileCount.toLocaleString()} files indexed).`,
+                    };
+                }
+                return tool;
+            });
+        }
+        catch {
+            return exports.tools;
+        }
+    }
     /**
      * Get CodeGraph instance for a project
      *
@@ -350,6 +412,8 @@ class ToolHandler {
                     return await this.handleCallees(args);
                 case 'codegraph_impact':
                     return await this.handleImpact(args);
+                case 'codegraph_explore':
+                    return await this.handleExplore(args);
                 case 'codegraph_node':
                     return await this.handleNode(args);
                 case 'codegraph_status':
@@ -452,16 +516,25 @@ class ToolHandler {
             return symbol;
         const cg = this.getCodeGraph(args.projectPath);
         const limit = (0, utils_1.clamp)(args.limit || 20, 1, 100);
-        const match = this.findSymbol(cg, symbol);
-        if (!match) {
+        const allMatches = this.findAllSymbols(cg, symbol);
+        if (allMatches.nodes.length === 0) {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
         }
-        const callers = cg.getCallers(match.node.id);
-        if (callers.length === 0) {
-            return this.textResult(`No callers found for "${symbol}"${match.note}`);
+        // Aggregate callers across all matching symbols
+        const seen = new Set();
+        const allCallers = [];
+        for (const node of allMatches.nodes) {
+            for (const c of cg.getCallers(node.id)) {
+                if (!seen.has(c.node.id)) {
+                    seen.add(c.node.id);
+                    allCallers.push(c.node);
+                }
+            }
+        }
+        if (allCallers.length === 0) {
+            return this.textResult(`No callers found for "${symbol}"${allMatches.note}`);
         }
-        const callerNodes = callers.slice(0, limit).map(c => c.node);
-        const formatted = this.formatNodeList(callerNodes, `Callers of ${symbol}`) + match.note;
+        const formatted = this.formatNodeList(allCallers.slice(0, limit), `Callers of ${symbol}`) + allMatches.note;
         return this.textResult(this.truncateOutput(formatted));
     }
     /**
@@ -473,16 +546,25 @@ class ToolHandler {
             return symbol;
         const cg = this.getCodeGraph(args.projectPath);
         const limit = (0, utils_1.clamp)(args.limit || 20, 1, 100);
-        const match = this.findSymbol(cg, symbol);
-        if (!match) {
+        const allMatches = this.findAllSymbols(cg, symbol);
+        if (allMatches.nodes.length === 0) {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
         }
-        const callees = cg.getCallees(match.node.id);
-        if (callees.length === 0) {
-            return this.textResult(`No callees found for "${symbol}"${match.note}`);
+        // Aggregate callees across all matching symbols
+        const seen = new Set();
+        const allCallees = [];
+        for (const node of allMatches.nodes) {
+            for (const c of cg.getCallees(node.id)) {
+                if (!seen.has(c.node.id)) {
+                    seen.add(c.node.id);
+                    allCallees.push(c.node);
+                }
+            }
+        }
+        if (allCallees.length === 0) {
+            return this.textResult(`No callees found for "${symbol}"${allMatches.note}`);
         }
-        const calleeNodes = callees.slice(0, limit).map(c => c.node);
-        const formatted = this.formatNodeList(calleeNodes, `Callees of ${symbol}`) + match.note;
+        const formatted = this.formatNodeList(allCallees.slice(0, limit), `Callees of ${symbol}`) + allMatches.note;
         return this.textResult(this.truncateOutput(formatted));
     }
     /**
@@ -494,14 +576,275 @@ class ToolHandler {
             return symbol;
         const cg = this.getCodeGraph(args.projectPath);
         const depth = (0, utils_1.clamp)(args.depth || 2, 1, 10);
-        const match = this.findSymbol(cg, symbol);
-        if (!match) {
+        const allMatches = this.findAllSymbols(cg, symbol);
+        if (allMatches.nodes.length === 0) {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
         }
-        const impact = cg.getImpactRadius(match.node.id, depth);
-        const formatted = this.formatImpact(symbol, impact) + match.note;
+        // Aggregate impact across all matching symbols
+        const mergedNodes = new Map();
+        const mergedEdges = [];
+        const seenEdges = new Set();
+        for (const node of allMatches.nodes) {
+            const impact = cg.getImpactRadius(node.id, depth);
+            for (const [id, n] of impact.nodes) {
+                mergedNodes.set(id, n);
+            }
+            for (const e of impact.edges) {
+                const key = `${e.source}->${e.target}:${e.kind}`;
+                if (!seenEdges.has(key)) {
+                    seenEdges.add(key);
+                    mergedEdges.push(e);
+                }
+            }
+        }
+        const mergedImpact = {
+            nodes: mergedNodes,
+            edges: mergedEdges,
+            roots: allMatches.nodes.map(n => n.id),
+        };
+        const formatted = this.formatImpact(symbol, mergedImpact) + allMatches.note;
         return this.textResult(this.truncateOutput(formatted));
     }
+    /** Maximum output for explore tool — sized to stay under MCP client token limits (~10k tokens) */
+    static EXPLORE_MAX_OUTPUT = 35000;
+    /**
+     * Handle codegraph_explore — deep exploration in a single call
+     *
+     * Strategy: find relevant symbols via graph traversal, group by file,
+     * then read contiguous file sections covering all symbols per file.
+     * This replaces multiple codegraph_node + Read calls.
+     */
+    async handleExplore(args) {
+        const query = this.validateString(args.query, 'query');
+        if (typeof query !== 'string')
+            return query;
+        const cg = this.getCodeGraph(args.projectPath);
+        const maxFiles = (0, utils_1.clamp)(args.maxFiles || 12, 1, 20);
+        const projectRoot = cg.getProjectRoot();
+        // Step 1: Find relevant context with generous parameters
+        const subgraph = await cg.findRelevantContext(query, {
+            searchLimit: 8,
+            traversalDepth: 3,
+            maxNodes: 80,
+            minScore: 0.2,
+        });
+        if (subgraph.nodes.size === 0) {
+            return this.textResult(`No relevant code found for "${query}"`);
+        }
+        // Step 2: Group nodes by file, score by relevance
+        const fileGroups = new Map();
+        const entryNodeIds = new Set(subgraph.roots);
+        // Build a set of nodes directly connected to entry points (depth 1)
+        const connectedToEntry = new Set();
+        for (const edge of subgraph.edges) {
+            if (entryNodeIds.has(edge.source))
+                connectedToEntry.add(edge.target);
+            if (entryNodeIds.has(edge.target))
+                connectedToEntry.add(edge.source);
+        }
+        for (const node of subgraph.nodes.values()) {
+            // Skip import/export nodes — they add noise without information
+            if (node.kind === 'import' || node.kind === 'export')
+                continue;
+            const group = fileGroups.get(node.filePath) || { nodes: [], score: 0 };
+            group.nodes.push(node);
+            // Score: entry point nodes worth 10, directly connected worth 3, others worth 1
+            if (entryNodeIds.has(node.id)) {
+                group.score += 10;
+            }
+            else if (connectedToEntry.has(node.id)) {
+                group.score += 3;
+            }
+            else {
+                group.score += 1;
+            }
+            fileGroups.set(node.filePath, group);
+        }
+        // Only include files that have entry points or nodes directly connected to entry points
+        const relevantFiles = [...fileGroups.entries()].filter(([, group]) => group.score >= 3);
+        // Extract query terms for relevance checking
+        const queryTerms = query.toLowerCase().split(/\s+/).filter(t => t.length >= 3);
+        // Sort files: highest relevance first, deprioritize low-value files
+        const sortedFiles = relevantFiles.sort((a, b) => {
+            const aPath = a[0].toLowerCase();
+            const bPath = b[0].toLowerCase();
+            // Check if any node name or file path relates to query terms
+            const hasQueryRelevance = (filePath, nodes) => {
+                const fp = filePath.toLowerCase();
+                if (queryTerms.some(t => fp.includes(t)))
+                    return true;
+                return nodes.some(n => queryTerms.some(t => n.name.toLowerCase().includes(t)));
+            };
+            const aRelevant = hasQueryRelevance(aPath, a[1].nodes);
+            const bRelevant = hasQueryRelevance(bPath, b[1].nodes);
+            if (aRelevant !== bRelevant)
+                return aRelevant ? -1 : 1;
+            // Deprioritize test files, icon files, and i18n files
+            const isLowValue = (p) => /\/(tests?|__tests?__|spec)\//i.test(p) ||
+                /\bicons?\b/i.test(p) ||
+                /\bi18n\b/i.test(p);
+            const aLow = isLowValue(aPath);
+            const bLow = isLowValue(bPath);
+            if (aLow !== bLow)
+                return aLow ? 1 : -1;
+            if (a[1].score !== b[1].score)
+                return b[1].score - a[1].score;
+            return b[1].nodes.length - a[1].nodes.length;
+        });
+        // Step 3: Build relationship map
+        const lines = [
+            `## Exploration: ${query}`,
+            '',
+            `Found ${subgraph.nodes.size} symbols across ${fileGroups.size} files.`,
+            '',
+        ];
+        // Relationship map — show how symbols connect
+        const significantEdges = subgraph.edges.filter(e => e.kind !== 'contains' // skip contains — it's implied by file grouping
+        );
+        if (significantEdges.length > 0) {
+            lines.push('### Relationships');
+            lines.push('');
+            // Group edges by kind for readability
+            const byKind = new Map();
+            for (const edge of significantEdges) {
+                const sourceNode = subgraph.nodes.get(edge.source);
+                const targetNode = subgraph.nodes.get(edge.target);
+                if (!sourceNode || !targetNode)
+                    continue;
+                const group = byKind.get(edge.kind) || [];
+                group.push({ source: sourceNode.name, target: targetNode.name });
+                byKind.set(edge.kind, group);
+            }
+            for (const [kind, edges] of byKind) {
+                // Show up to 15 relationships per kind
+                const shown = edges.slice(0, 15);
+                lines.push(`**${kind}:**`);
+                for (const e of shown) {
+                    lines.push(`- ${e.source} → ${e.target}`);
+                }
+                if (edges.length > 15) {
+                    lines.push(`- ... and ${edges.length - 15} more`);
+                }
+                lines.push('');
+            }
+        }
+        // Step 4: Read contiguous file sections
+        lines.push('### Source Code');
+        lines.push('');
+        let totalChars = lines.join('\n').length;
+        let filesIncluded = 0;
+        for (const [filePath, group] of sortedFiles) {
+            if (filesIncluded >= maxFiles)
+                break;
+            if (totalChars > ToolHandler.EXPLORE_MAX_OUTPUT * 0.9)
+                break;
+            const absPath = (0, utils_1.validatePathWithinRoot)(projectRoot, filePath);
+            if (!absPath || !(0, fs_1.existsSync)(absPath))
+                continue;
+            let fileContent;
+            try {
+                fileContent = (0, fs_1.readFileSync)(absPath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const fileLines = fileContent.split('\n');
+            const lang = group.nodes[0]?.language || '';
+            // Cluster nearby symbols to avoid reading huge gaps between distant symbols.
+            // Sort by start line, then merge overlapping/adjacent ranges (within 15 lines).
+            const ranges = group.nodes
+                .filter(n => n.startLine > 0 && n.endLine > 0)
+                .map(n => ({ start: n.startLine, end: n.endLine, name: n.name, kind: n.kind }))
+                .sort((a, b) => a.start - b.start);
+            if (ranges.length === 0)
+                continue;
+            const GAP_THRESHOLD = 15; // merge sections within 15 lines of each other
+            const clusters = [];
+            let current = { start: ranges[0].start, end: ranges[0].end, symbols: [`${ranges[0].name}(${ranges[0].kind})`] };
+            for (let i = 1; i < ranges.length; i++) {
+                const r = ranges[i];
+                if (r.start <= current.end + GAP_THRESHOLD) {
+                    current.end = Math.max(current.end, r.end);
+                    current.symbols.push(`${r.name}(${r.kind})`);
+                }
+                else {
+                    clusters.push(current);
+                    current = { start: r.start, end: r.end, symbols: [`${r.name}(${r.kind})`] };
+                }
+            }
+            clusters.push(current);
+            // Build file section output from clusters
+            const contextPadding = 3;
+            let fileSection = '';
+            const allSymbols = [];
+            for (const cluster of clusters) {
+                const startIdx = Math.max(0, cluster.start - 1 - contextPadding);
+                const endIdx = Math.min(fileLines.length, cluster.end + contextPadding);
+                const section = fileLines.slice(startIdx, endIdx).join('\n');
+                if (fileSection.length > 0) {
+                    fileSection += '\n\n// ... (gap) ...\n\n';
+                }
+                fileSection += section;
+                allSymbols.push(...cluster.symbols);
+            }
+            // Skip if this section would blow the output limit
+            if (totalChars + fileSection.length + 200 > ToolHandler.EXPLORE_MAX_OUTPUT) {
+                const budget = ToolHandler.EXPLORE_MAX_OUTPUT - totalChars - 200;
+                if (budget < 500)
+                    break;
+                const trimmed = fileSection.slice(0, budget) + '\n// ... trimmed ...';
+                lines.push(`#### ${filePath} — ${allSymbols.join(', ')}`);
+                lines.push('');
+                lines.push('```' + lang);
+                lines.push(trimmed);
+                lines.push('```');
+                lines.push('');
+                totalChars += trimmed.length + 200;
+                filesIncluded++;
+                break;
+            }
+            lines.push(`#### ${filePath} — ${allSymbols.join(', ')}`);
+            lines.push('');
+            lines.push('```' + lang);
+            lines.push(fileSection);
+            lines.push('```');
+            lines.push('');
+            totalChars += fileSection.length + 200;
+            filesIncluded++;
+        }
+        // Add remaining files as references (from both relevant and peripheral files)
+        const remainingRelevant = sortedFiles.slice(filesIncluded);
+        const peripheralFiles = [...fileGroups.entries()]
+            .filter(([, group]) => group.score < 3)
+            .sort((a, b) => b[1].score - a[1].score);
+        const remainingFiles = [...remainingRelevant, ...peripheralFiles];
+        if (remainingFiles.length > 0) {
+            lines.push('### Additional relevant files (not shown)');
+            lines.push('');
+            for (const [filePath, group] of remainingFiles.slice(0, 10)) {
+                const symbols = group.nodes.map(n => `${n.name}:${n.startLine}`).join(', ');
+                lines.push(`- ${filePath}: ${symbols}`);
+            }
+            if (remainingFiles.length > 10) {
+                lines.push(`- ... and ${remainingFiles.length - 10} more files`);
+            }
+        }
+        // Add completeness signal so agents know they don't need to re-read these files
+        lines.push('');
+        lines.push('---');
+        lines.push(`> **Complete source code is included above for ${filesIncluded} files.** You do NOT need to re-read these files — the relevant sections are already shown in full. Only use Read/Grep for files listed under "Additional relevant files" if you need more detail.`);
+        // Add explore budget note based on project size
+        try {
+            const stats = cg.getStats();
+            const budget = getExploreBudget(stats.fileCount);
+            lines.push('');
+            lines.push(`> **Explore budget: ${budget} calls max for this project (${stats.fileCount.toLocaleString()} files indexed).** Stop exploring and synthesize your answer once you've used ${budget} calls — do NOT make additional explore calls beyond this budget.`);
+        }
+        catch {
+            // Stats unavailable — skip budget note
+        }
+        return this.textResult(lines.join('\n'));
+    }
     /**
      * Handle codegraph_node
      */
@@ -710,13 +1053,36 @@ class ToolHandler {
      * Find a symbol by name, handling disambiguation when multiple matches exist.
      * Returns the best match and a note about alternatives if any.
      */
+    /**
+     * Check if a node matches a symbol query, supporting both simple names and
+     * qualified "Parent.child" notation (e.g., "Session.request" matches a method
+     * named "request" inside a class named "Session").
+     */
+    matchesSymbol(node, symbol) {
+        // Simple name match
+        if (node.name === symbol)
+            return true;
+        // File basename match (e.g., "product-card" matches "product-card.liquid")
+        if (node.kind === 'file' && node.name.replace(/\.[^.]+$/, '') === symbol)
+            return true;
+        // Qualified name match: "Parent.child" → look for "::Parent::child" in qualified_name
+        if (symbol.includes('.')) {
+            const parts = symbol.split('.');
+            const qualifiedSuffix = parts.join('::');
+            if (node.qualifiedName.includes(qualifiedSuffix))
+                return true;
+        }
+        return false;
+    }
     findSymbol(cg, symbol) {
-        const results = cg.searchNodes(symbol, { limit: 10 });
+        // Use higher limit for qualified lookups (e.g., "Session.request") since the
+        // target may rank lower in FTS when there are many partial matches
+        const limit = symbol.includes('.') ? 50 : 10;
+        const results = cg.searchNodes(symbol, { limit });
         if (results.length === 0 || !results[0]) {
             return null;
         }
-        // If only one result, or first is an exact name match, use it directly
-        const exactMatches = results.filter(r => r.node.name === symbol);
+        const exactMatches = results.filter(r => this.matchesSymbol(r.node, symbol));
         if (exactMatches.length === 1) {
             return { node: exactMatches[0].node, note: '' };
         }
@@ -730,6 +1096,24 @@ class ToolHandler {
         // No exact match, use best fuzzy match
         return { node: results[0].node, note: '' };
     }
+    /**
+     * Find ALL symbols matching a name. Used by callers/callees/impact to aggregate
+     * results across all matching symbols (e.g., multiple classes with an `execute` method).
+     */
+    findAllSymbols(cg, symbol) {
+        const results = cg.searchNodes(symbol, { limit: 50 });
+        if (results.length === 0) {
+            return { nodes: [], note: '' };
+        }
+        const exactMatches = results.filter(r => this.matchesSymbol(r.node, symbol));
+        if (exactMatches.length <= 1) {
+            const node = exactMatches[0]?.node ?? results[0].node;
+            return { nodes: [node], note: '' };
+        }
+        const locations = exactMatches.map(r => `${r.node.kind} at ${r.node.filePath}:${r.node.startLine}`);
+        const note = `\n\n> **Note:** Aggregated results across ${exactMatches.length} symbols named "${symbol}": ${locations.join(', ')}`;
+        return { nodes: exactMatches.map(r => r.node), note };
+    }
     /**
      * Truncate output if it exceeds the maximum length
      */