@kkvcrobatz107/codegraph 0.9.6-pkm.1

package/dist/mcp/tools.js

@@ -0,0 +1,2545 @@
+"use strict";
+/**
+ * MCP Tool Definitions
+ *
+ * Defines the tools exposed by the CodeGraph MCP server.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolHandler = exports.tools = void 0;
+exports.getExploreBudget = getExploreBudget;
+exports.getExploreOutputBudget = getExploreOutputBudget;
+exports.formatStaleBanner = formatStaleBanner;
+exports.formatStaleFooter = formatStaleFooter;
+const index_1 = __importStar(require("../index"));
+const worktree_1 = require("../sync/worktree");
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const utils_1 = require("../utils");
+const os_1 = require("os");
+const path_1 = require("path");
+/** Maximum output length to prevent context bloat (characters) */
+const MAX_OUTPUT_LENGTH = 15000;
+/**
+ * Maximum length for free-form string inputs (query, task, symbol).
+ * Bounds memory and CPU when a buggy or hostile MCP client sends a
+ * huge payload — without this an attacker could ship a 100MB string
+ * and force a full FTS5 scan / OOM the server. 10 000 characters is
+ * far beyond any realistic legitimate query.
+ */
+const MAX_INPUT_LENGTH = 10_000;
+/**
+ * Maximum length for path-like string inputs (projectPath, path
+ * filter, glob pattern). Paths beyond a few thousand chars are
+ * never legitimate and signal abuse or a bug upstream.
+ */
+const MAX_PATH_LENGTH = 4_096;
+/**
+ * Rust path roots that have no file-system equivalent — `crate` is the
+ * current crate, `super` is the parent module, `self` is the current
+ * module. Used by `matchesSymbol` to strip these before file-path
+ * matching so `crate::configurator::stage_apply::run` resolves the
+ * same as `configurator::stage_apply::run`.
+ */
+const RUST_PATH_PREFIXES = new Set(['crate', 'super', 'self']);
+/**
+ * Node kinds that contain other symbols. For these, `codegraph_node` with
+ * `includeCode=true` returns a structural outline (member names + signatures
+ * + line numbers) instead of the full body, which for a large class is a
+ * multi-thousand-character wall of source that bloats the agent's context.
+ */
+const CONTAINER_NODE_KINDS = new Set([
+    'class', 'struct', 'interface', 'trait', 'protocol', 'enum', 'namespace', 'module',
+]);
+/** Last `::` / `.` / `/`-separated segment of a qualified symbol. */
+function lastQualifierPart(symbol) {
+    const parts = symbol.split(/::|[./]/).filter((p) => p.length > 0);
+    return parts[parts.length - 1] ?? symbol;
+}
+/**
+ * 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;
+}
+function getExploreOutputBudget(fileCount) {
+    if (fileCount < 500) {
+        return {
+            maxOutputChars: 18000,
+            defaultMaxFiles: 5,
+            maxCharsPerFile: 3800,
+            gapThreshold: 8,
+            maxSymbolsInFileHeader: 6,
+            maxEdgesPerRelationshipKind: 6,
+            includeRelationships: true,
+            includeAdditionalFiles: false,
+            includeCompletenessSignal: false,
+            includeBudgetNote: false,
+        };
+    }
+    if (fileCount < 5000) {
+        return {
+            // Sized so ONE explore can cover a flow that centers on a god-file (e.g.
+            // excalidraw's 415 KB App.tsx): the previous 2500/file returned <1% of such
+            // a file, forcing the agent to Read it anyway. Per-file must also stay ≥ the
+            // smaller <500 tier (3800) — the old 2500 was non-monotonic. Tokens are
+            // cheap relative to a 5–10 Read round-trip spiral; favor sufficiency.
+            maxOutputChars: 28000,
+            defaultMaxFiles: 10,
+            maxCharsPerFile: 6500,
+            gapThreshold: 12,
+            maxSymbolsInFileHeader: 10,
+            maxEdgesPerRelationshipKind: 10,
+            includeRelationships: true,
+            includeAdditionalFiles: true,
+            includeCompletenessSignal: true,
+            includeBudgetNote: true,
+        };
+    }
+    if (fileCount < 15000) {
+        return {
+            maxOutputChars: 35000,
+            defaultMaxFiles: 12,
+            maxCharsPerFile: 7000,
+            gapThreshold: 15,
+            maxSymbolsInFileHeader: 15,
+            maxEdgesPerRelationshipKind: 15,
+            includeRelationships: true,
+            includeAdditionalFiles: true,
+            includeCompletenessSignal: true,
+            includeBudgetNote: true,
+        };
+    }
+    return {
+        maxOutputChars: 38000,
+        defaultMaxFiles: 14,
+        maxCharsPerFile: 7000,
+        gapThreshold: 15,
+        maxSymbolsInFileHeader: 15,
+        maxEdgesPerRelationshipKind: 15,
+        includeRelationships: true,
+        includeAdditionalFiles: true,
+        includeCompletenessSignal: true,
+        includeBudgetNote: true,
+    };
+}
+/**
+ * Whether `codegraph_explore` should prefix source lines with their line
+ * numbers (cat -n style: `<num>\t<code>`).
+ *
+ * Line numbers let the agent cite `file:line` straight from the explore
+ * payload instead of re-Reading the file just to find a line number — the
+ * dominant residual cost on precise-tracing questions (#185 follow-up).
+ *
+ * Defaults ON. Set `CODEGRAPH_EXPLORE_LINENUMS=0` to disable (used by the
+ * A/B harness to measure the payload-cost vs. read-savings tradeoff).
+ */
+function exploreLineNumbersEnabled() {
+    return process.env.CODEGRAPH_EXPLORE_LINENUMS !== '0';
+}
+/**
+ * Prefix each line of a source slice with its 1-based line number, matching
+ * the Read tool's `cat -n` convention (number + tab) so the agent treats it
+ * the same way it treats Read output.
+ *
+ * @param slice  contiguous source text (already extracted from the file)
+ * @param firstLineNumber  the 1-based line number of the slice's first line
+ */
+function numberSourceLines(slice, firstLineNumber) {
+    const out = [];
+    const split = slice.split('\n');
+    for (let i = 0; i < split.length; i++) {
+        out.push(`${firstLineNumber + i}\t${split[i]}`);
+    }
+    return out.join('\n');
+}
+/**
+ * Mark a Claude session as having consulted MCP tools.
+ * This enables Grep/Glob/Bash commands that would otherwise be blocked.
+ *
+ * Why the explicit openSync + O_NOFOLLOW dance instead of plain writeFileSync:
+ * tmpdir() is world-writable on Linux (mode 1777), so on a shared multi-user
+ * machine any other local user can pre-create `codegraph-consulted-<hash>` as
+ * a symlink pointing at a file the victim owns. The old `writeFileSync` would
+ * happily follow that link and overwrite the target's contents with the ISO
+ * timestamp string (CWE-59). The session-id hash provides the predictability
+ * gate, but it's defense-in-depth: if a session id ever surfaces in logs,
+ * argv, or telemetry the attack becomes trivial, and the right fix is to not
+ * follow links from /tmp paths in the first place.
+ */
+function markSessionConsulted(sessionId) {
+    try {
+        const hash = (0, crypto_1.createHash)('md5').update(sessionId).digest('hex').slice(0, 16);
+        const markerPath = (0, path_1.join)((0, os_1.tmpdir)(), `codegraph-consulted-${hash}`);
+        // Refuse to follow a pre-planted symlink at the marker path (CWE-59).
+        // O_NOFOLLOW (below) is the atomic, TOCTOU-free guard on POSIX, but it is
+        // `undefined` on Windows (libuv ignores it), so the bitwise-OR silently
+        // drops it and openSync would follow the link. This lstat check closes that
+        // gap cross-platform; ENOENT (path is free) falls through to create it.
+        try {
+            if ((0, fs_1.lstatSync)(markerPath).isSymbolicLink())
+                return;
+        }
+        catch {
+            // No existing entry (or stat failed) — nothing to refuse; proceed.
+        }
+        // O_NOFOLLOW makes openSync throw ELOOP if markerPath is already a symlink.
+        // O_CREAT + O_TRUNC keep the original "create-or-overwrite" semantics, and
+        // mode 0o600 prevents readback by other local users (the marker payload is
+        // benign, but narrowing the exposure costs nothing).
+        const flags = fs_1.constants.O_WRONLY | fs_1.constants.O_CREAT | fs_1.constants.O_TRUNC | fs_1.constants.O_NOFOLLOW;
+        const fd = (0, fs_1.openSync)(markerPath, flags, 0o600);
+        try {
+            (0, fs_1.writeSync)(fd, new Date().toISOString());
+        }
+        finally {
+            (0, fs_1.closeSync)(fd);
+        }
+    }
+    catch {
+        // Silently fail - don't break MCP on marker write failure. ELOOP from a
+        // planted symlink lands here too, which is the intended behavior: refuse
+        // to write rather than overwrite an attacker-chosen target.
+    }
+}
+/**
+ * Per-file staleness banner emitted at the top of a tool response when the
+ * file watcher has pending events for files referenced by the response.
+ * The agent uses this to fall back to Read for those specific files
+ * without waiting for the debounced sync (issue #403).
+ */
+function formatStaleBanner(stale) {
+    const now = Date.now();
+    const lines = stale.map((p) => {
+        const ageMs = Math.max(0, now - p.lastSeenMs);
+        const label = p.indexing ? 'indexing in progress' : 'pending sync';
+        return `  - ${p.path} (edited ${ageMs}ms ago, ${label})`;
+    });
+    return ('⚠️ Some files referenced below were edited since the last index sync — ' +
+        'their codegraph entries may be stale:\n' +
+        lines.join('\n') +
+        '\nFor accurate content of those specific files, Read them directly. ' +
+        'The rest of this response is fresh.');
+}
+/**
+ * Compact footer listing pending files that are NOT referenced in this
+ * response. Gives the agent a complete project-wide freshness picture
+ * without bloating the main banner.
+ */
+function formatStaleFooter(stale) {
+    const MAX = 5;
+    const now = Date.now();
+    const shown = stale.slice(0, MAX);
+    const lines = shown.map((p) => {
+        const ageMs = Math.max(0, now - p.lastSeenMs);
+        return `  - ${p.path} (edited ${ageMs}ms ago)`;
+    });
+    const more = stale.length > MAX ? `\n  - …and ${stale.length - MAX} more` : '';
+    return (`(Note: ${stale.length} file(s) elsewhere in this project are pending index ` +
+        `sync but were not referenced above:\n${lines.join('\n')}${more})`);
+}
+/**
+ * Common projectPath property for cross-project queries
+ */
+const projectPathProperty = {
+    type: 'string',
+    description: 'Path to a different project with .codegraph/ initialized. If omitted, uses current project. Use this to query other codebases.',
+};
+/**
+ * All CodeGraph MCP tools
+ *
+ * Designed for minimal context usage - use codegraph_context as the primary tool,
+ * and only use other tools for targeted follow-up queries.
+ *
+ * All tools support cross-project queries via the optional `projectPath` parameter.
+ */
+exports.tools = [
+    {
+        name: 'codegraph_search',
+        description: 'Quick symbol search by name. Returns locations only (no code). Use codegraph_context instead for comprehensive task context.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Symbol name or partial name (e.g., "auth", "signIn", "UserService")',
+                },
+                kind: {
+                    type: 'string',
+                    description: 'Filter by node kind',
+                    enum: ['function', 'method', 'class', 'interface', 'type', 'variable', 'route', 'component'],
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum results (default: 10)',
+                    default: 10,
+                },
+                projectPath: projectPathProperty,
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'codegraph_context',
+        description: 'PRIMARY TOOL — call this FIRST for any "how does X work", architecture, feature, or bug-context question. Composes search + node + callers + callees and returns entry points, related symbols, and key code in ONE call — usually enough to answer with no further search/Read/Grep. Prefer this over chaining codegraph_search + codegraph_node, and over codegraph_explore. NOTE: provides CODE context, not product requirements; for new features still clarify UX/edge cases with the user.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task: {
+                    type: 'string',
+                    description: 'Description of the task, bug, or feature to build context for',
+                },
+                maxNodes: {
+                    type: 'number',
+                    description: 'Maximum symbols to include (default: 20)',
+                    default: 20,
+                },
+                includeCode: {
+                    type: 'boolean',
+                    description: 'Include code snippets for key symbols (default: true)',
+                    default: true,
+                },
+                projectPath: projectPathProperty,
+            },
+            required: ['task'],
+        },
+    },
+    {
+        name: 'codegraph_callers',
+        description: 'Find all functions/methods that call a specific symbol. Useful for understanding usage patterns and impact of changes.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                symbol: {
+                    type: 'string',
+                    description: 'Name of the function, method, or class to find callers for',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of callers to return (default: 20)',
+                    default: 20,
+                },
+                projectPath: projectPathProperty,
+            },
+            required: ['symbol'],
+        },
+    },
+    {
+        name: 'codegraph_callees',
+        description: 'Find all functions/methods that a specific symbol calls. Useful for understanding dependencies and code flow.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                symbol: {
+                    type: 'string',
+                    description: 'Name of the function, method, or class to find callees for',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of callees to return (default: 20)',
+                    default: 20,
+                },
+                projectPath: projectPathProperty,
+            },
+            required: ['symbol'],
+        },
+    },
+    {
+        name: 'codegraph_impact',
+        description: 'Analyze the impact radius of changing a symbol. Shows what code could be affected by modifications.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                symbol: {
+                    type: 'string',
+                    description: 'Name of the symbol to analyze impact for',
+                },
+                depth: {
+                    type: 'number',
+                    description: 'How many levels of dependencies to traverse (default: 2)',
+                    default: 2,
+                },
+                projectPath: projectPathProperty,
+            },
+            required: ['symbol'],
+        },
+    },
+    {
+        name: 'codegraph_node',
+        description: 'Get ONE symbol\'s details (location, signature, docstring) PLUS its TRAIL — what it calls and what calls it, each with file:line. Pass includeCode=true for source (functions return their body; containers return a member outline). Use this to WALK the call graph hop-by-hop — node a symbol, then node one of its trail entries — the structural, no-Read way to follow "what calls/triggers/handles X" across files. For a broad first overview of many symbols at once use codegraph_explore; use node to drill along a specific path from there. (If a trail is empty on a non-leaf, that hop is likely dynamic dispatch — read just that line.) Source returned with includeCode is the verbatim live file content — identical to Read.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                symbol: {
+                    type: 'string',
+                    description: 'Name of the symbol to get details for',
+                },
+                includeCode: {
+                    type: 'boolean',
+                    description: 'Include full source code (default: false to minimize context)',
+                    default: false,
+                },
+                projectPath: projectPathProperty,
+            },
+            required: ['symbol'],
+        },
+    },
+    {
+        name: 'codegraph_explore',
+        description: 'Returns source for SEVERAL related symbols grouped by file, plus a relationship map, in ONE capped call. This is the efficient way to inspect many related symbols at once — strongly prefer it over a series of codegraph_node or Read calls (each separate call re-reads the whole context, so 8 node calls cost far more than 1 explore). Use it after codegraph_context when you need to see the actual source of several symbols. Query with specific symbol/file/code terms, NOT natural-language sentences — run codegraph_search first to find names. Bad: "how are agent prompts loaded and passed to the CLI". Good: "renderStaticScene drawElementOnCanvas ShapeCache renderElement.ts". The code it returns is the VERBATIM live file source (byte-for-byte identical to Read), line-numbered — not a summary; treat files it shows as already Read, no need to re-open them.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Symbol names, file names, or short code terms to explore (e.g., "AuthService loginUser session-manager", "GraphTraverser BFS impact traversal.ts"). Use codegraph_search first to find relevant names.',
+                },
+                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.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectPath: projectPathProperty,
+            },
+        },
+    },
+    {
+        name: 'codegraph_files',
+        description: 'REQUIRED for file/folder exploration. Get the project file structure from the CodeGraph index. Returns a tree view of all indexed files with metadata (language, symbol count). Much faster than Glob/filesystem scanning. Use this FIRST when exploring project structure, finding files, or understanding codebase organization.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Filter to files under this directory path (e.g., "src/components"). Returns all files if not specified.',
+                },
+                pattern: {
+                    type: 'string',
+                    description: 'Filter files matching this glob pattern (e.g., "*.tsx", "**/*.test.ts")',
+                },
+                format: {
+                    type: 'string',
+                    description: 'Output format: "tree" (hierarchical, default), "flat" (simple list), "grouped" (by language)',
+                    enum: ['tree', 'flat', 'grouped'],
+                    default: 'tree',
+                },
+                includeMetadata: {
+                    type: 'boolean',
+                    description: 'Include file metadata like language and symbol count (default: true)',
+                    default: true,
+                },
+                maxDepth: {
+                    type: 'number',
+                    description: 'Maximum directory depth to show (default: unlimited)',
+                },
+                projectPath: projectPathProperty,
+            },
+        },
+    },
+    {
+        name: 'codegraph_trace',
+        description: 'Trace the CALL PATH between two symbols — "how does <from> reach/become <to>?" Returns the chain of functions from one to the other (each hop with file:line and its body inlined, plus the outgoing calls of the destination itself) in ONE call. This is something grep/Read structurally cannot do: there is no text pattern for "the path from A to B". Ideal for flow questions — how an update triggers a render, how a request reaches a handler, how a QuerySet becomes SQL. If no static path exists the chain likely breaks at dynamic dispatch (callbacks/descriptors/metaclasses); the tool says where and points you to codegraph_node to bridge it.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                from: {
+                    type: 'string',
+                    description: 'Symbol the flow starts at (e.g., "QuerySet", "handleRequest", "mutateElement")',
+                },
+                to: {
+                    type: 'string',
+                    description: 'Symbol the flow should reach (e.g., "execute_sql", "render", "setState")',
+                },
+                projectPath: projectPathProperty,
+            },
+            required: ['from', 'to'],
+        },
+    },
+];
+/**
+ * Tool handler that executes tools against a CodeGraph instance
+ *
+ * Supports cross-project queries via the projectPath parameter.
+ * Other projects are opened on-demand and cached for performance.
+ */
+class ToolHandler {
+    cg;
+    // Cache of opened CodeGraph instances for cross-project queries
+    projectCache = new Map();
+    // The directory the server last searched for a default project. Surfaced in
+    // the "not initialized" error so users can see why detection missed.
+    defaultProjectHint = null;
+    // Per-start-path cache of the git worktree/index mismatch (issue #155). The
+    // mismatch is a fixed property of (where the request came from → which
+    // .codegraph/ it resolves to), so the up-to-two `git rev-parse` spawns run
+    // once and every later tool call reuses the result — never shelling out to
+    // git on the hot path. `undefined` = not computed yet; `null` = no mismatch.
+    worktreeMismatchCache = new Map();
+    constructor(cg) {
+        this.cg = cg;
+    }
+    /**
+     * Update the default CodeGraph instance (e.g. after lazy initialization)
+     */
+    setDefaultCodeGraph(cg) {
+        this.cg = cg;
+    }
+    /**
+     * Record the directory the server tried to resolve the default project from.
+     * Used only to make the "no default project" error actionable.
+     */
+    setDefaultProjectHint(searchedPath) {
+        this.defaultProjectHint = searchedPath;
+    }
+    /**
+     * Whether a default CodeGraph instance is available
+     */
+    hasDefaultCodeGraph() {
+        return this.cg !== null;
+    }
+    /**
+     * Optional allowlist of exposed tools, parsed from the CODEGRAPH_MCP_TOOLS
+     * env var (comma-separated short names, e.g. "trace,search,node,context").
+     * Unset/empty → every tool is exposed. Lets an operator (or an A/B harness)
+     * trim the tool surface without rebuilding the client config; the ablated
+     * tool is then truly absent from ListTools rather than merely denied on call.
+     * Matching is on the short form, so "trace" and "codegraph_trace" both work.
+     */
+    toolAllowlist() {
+        const raw = process.env.CODEGRAPH_MCP_TOOLS;
+        if (!raw || !raw.trim())
+            return null;
+        const short = (s) => s.trim().replace(/^codegraph_/, '');
+        const set = new Set(raw.split(',').map(short).filter(Boolean));
+        return set.size ? set : null;
+    }
+    /** Whether a tool name passes the CODEGRAPH_MCP_TOOLS allowlist (if any). */
+    isToolAllowed(name) {
+        const allow = this.toolAllowlist();
+        return !allow || allow.has(name.replace(/^codegraph_/, ''));
+    }
+    /**
+     * 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. Honors the CODEGRAPH_MCP_TOOLS
+     * allowlist so a trimmed surface is reflected in ListTools.
+     */
+    getTools() {
+        const allow = this.toolAllowlist();
+        const visible = allow
+            ? exports.tools.filter(t => allow.has(t.name.replace(/^codegraph_/, '')))
+            : exports.tools;
+        if (!this.cg)
+            return visible;
+        try {
+            const stats = this.cg.getStats();
+            const budget = getExploreBudget(stats.fileCount);
+            return visible.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 visible;
+        }
+    }
+    /**
+     * Get CodeGraph instance for a project
+     *
+     * If projectPath is provided, opens that project's CodeGraph (cached).
+     * Otherwise returns the default CodeGraph instance.
+     *
+     * Walks up parent directories to find the nearest .codegraph/ folder,
+     * similar to how git finds .git/ directories.
+     */
+    getCodeGraph(projectPath) {
+        if (!projectPath) {
+            if (!this.cg) {
+                const searched = this.defaultProjectHint ?? process.cwd();
+                throw new Error('No CodeGraph project is loaded for this session.\n' +
+                    `Searched for a .codegraph/ directory starting from: ${searched}\n` +
+                    'The index is likely fine — this is a working-directory detection issue: ' +
+                    "the MCP client launched the server outside your project and didn't report the " +
+                    'workspace root. Fix it either way:\n' +
+                    '  • Pass projectPath to the tool call, e.g. projectPath: "/absolute/path/to/your/project"\n' +
+                    '  • Or add --path to the server\'s MCP config args: ["serve", "--mcp", "--path", "/absolute/path/to/your/project"]');
+            }
+            return this.cg;
+        }
+        // Check cache first (using original path as key)
+        if (this.projectCache.has(projectPath)) {
+            return this.projectCache.get(projectPath);
+        }
+        // Reject sensitive system directories before opening. Only validate a
+        // path that actually exists — a nested or not-yet-created sub-path of a
+        // real project must still be allowed to resolve UP to its .codegraph/
+        // root below (issue #238), so we don't run the existence-checking
+        // validator on paths that are meant to walk up.
+        if ((0, fs_1.existsSync)(projectPath)) {
+            const pathError = (0, utils_1.validateProjectPath)(projectPath);
+            if (pathError) {
+                throw new Error(pathError);
+            }
+        }
+        // Walk up parent directories to find nearest .codegraph/
+        const resolvedRoot = (0, index_1.findNearestCodeGraphRoot)(projectPath);
+        if (!resolvedRoot) {
+            throw new Error(`CodeGraph not initialized in ${projectPath}. Run 'codegraph init' in that project first.`);
+        }
+        // If the path resolves to the default project, reuse the already-open
+        // default instance rather than opening a SECOND connection to the same DB.
+        // A duplicate connection serializes reads against the watcher's auto-sync
+        // writes; on the wasm backend (no WAL) that surfaces as intermittent
+        // "database is locked" on concurrent tool calls. See issue #238. Deliberately
+        // not cached under projectPath — the server owns and closes the default
+        // instance, so routing it through projectCache.closeAll() would double-close it.
+        if (this.cg && this.cg.getProjectRoot() === resolvedRoot) {
+            return this.cg;
+        }
+        // Check if we already have this resolved root cached (different path, same project)
+        if (this.projectCache.has(resolvedRoot)) {
+            const cg = this.projectCache.get(resolvedRoot);
+            // Cache under original path too for faster future lookups
+            this.projectCache.set(projectPath, cg);
+            return cg;
+        }
+        // Open and cache under both paths
+        const cg = index_1.default.openSync(resolvedRoot);
+        this.projectCache.set(resolvedRoot, cg);
+        if (projectPath !== resolvedRoot) {
+            this.projectCache.set(projectPath, cg);
+        }
+        return cg;
+    }
+    /**
+     * Close all cached project connections
+     */
+    closeAll() {
+        for (const cg of this.projectCache.values()) {
+            cg.close();
+        }
+        this.projectCache.clear();
+        this.worktreeMismatchCache.clear();
+    }
+    /**
+     * Validate that a value is a non-empty string within length bounds.
+     *
+     * The `maxLength` cap protects against MCP clients that ship huge
+     * payloads (10MB+ query strings either by accident or maliciously).
+     * Without this, a single oversized input can pin the FTS5 index or
+     * exhaust memory before any real work runs.
+     */
+    validateString(value, name, maxLength = MAX_INPUT_LENGTH) {
+        if (typeof value !== 'string' || value.length === 0) {
+            return this.errorResult(`${name} must be a non-empty string`);
+        }
+        if (value.length > maxLength) {
+            return this.errorResult(`${name} exceeds maximum length of ${maxLength} characters (got ${value.length})`);
+        }
+        return value;
+    }
+    /**
+     * Validate an optional path-like string input. Returns the value if
+     * valid (or undefined), or a ToolResult with the error.
+     */
+    validateOptionalPath(value, name) {
+        if (value === undefined || value === null)
+            return undefined;
+        if (typeof value !== 'string') {
+            return this.errorResult(`${name} must be a string`);
+        }
+        if (value.length > MAX_PATH_LENGTH) {
+            return this.errorResult(`${name} exceeds maximum length of ${MAX_PATH_LENGTH} characters (got ${value.length})`);
+        }
+        return value;
+    }
+    /**
+     * Cached git worktree/index mismatch for a tool call's effective project.
+     *
+     * The "effective project" is what the request targets: an explicit
+     * `projectPath` arg, else the directory the server resolved its default
+     * project from (`defaultProjectHint`), else cwd. Memoized per start path —
+     * see `worktreeMismatchCache`. Best-effort: if the project can't be resolved
+     * (e.g. nothing initialized yet), it reports "no mismatch" so a tool is never
+     * broken by this check.
+     */
+    worktreeMismatchFor(projectPath) {
+        const startPath = projectPath ?? this.defaultProjectHint ?? process.cwd();
+        const cached = this.worktreeMismatchCache.get(startPath);
+        if (cached !== undefined)
+            return cached;
+        let mismatch = null;
+        try {
+            mismatch = (0, worktree_1.detectWorktreeIndexMismatch)(startPath, this.getCodeGraph(projectPath).getProjectRoot());
+        }
+        catch {
+            // No resolvable project (or any other resolution error) → nothing to warn.
+            mismatch = null;
+        }
+        this.worktreeMismatchCache.set(startPath, mismatch);
+        return mismatch;
+    }
+    /**
+     * Prefix a successful read-tool result with a compact worktree-mismatch
+     * notice when the resolved index belongs to a different git working tree than
+     * the caller's (issue #155). Without this, an agent in a nested worktree
+     * silently trusts main-branch results. No-op on error results and when there
+     * is no mismatch. `codegraph_status` is excluded — it embeds its own verbose
+     * warning — so it stays out of this path.
+     */
+    withWorktreeNotice(result, projectPath) {
+        if (result.isError)
+            return result;
+        const mismatch = this.worktreeMismatchFor(projectPath);
+        if (!mismatch)
+            return result;
+        const notice = (0, worktree_1.worktreeMismatchNotice)(mismatch);
+        const [first, ...rest] = result.content;
+        if (first && first.type === 'text') {
+            return { ...result, content: [{ type: 'text', text: `${notice}\n\n${first.text}` }, ...rest] };
+        }
+        return result;
+    }
+    /**
+     * Annotate a successful read-tool result with per-file staleness — the
+     * non-blocking answer to issue #403. The file watcher tracks every event
+     * it sees per path; here we intersect "files referenced in this response"
+     * against that pending set and prepend a compact banner so the agent can
+     * fall back to Read for those *specific* files without waiting for the
+     * debounced sync to fire. Other pending files in the project (not
+     * referenced by this response) get a small footer so the agent has a
+     * complete picture without bloating the banner.
+     *
+     * Cost when nothing is pending — the common case — is one boolean check.
+     * No I/O, no parsing of markdown beyond a per-pending-file substring scan.
+     */
+    withStalenessNotice(result, projectPath) {
+        if (result.isError)
+            return result;
+        let cg;
+        try {
+            cg = this.getCodeGraph(projectPath);
+        }
+        catch {
+            return result; // no default project — leave as is
+        }
+        // Cross-project `projectPath` calls open a cached CodeGraph WITHOUT a
+        // watcher (watchers are only attached to the default session project).
+        // When the cross-project path happens to be the same project as the
+        // default cg, the cached instance is the wrong one — its pendingFiles is
+        // permanently empty. Detect the equal-path case and prefer the default
+        // cg so the staleness signal still fires when an agent passes the
+        // explicit projectPath form of its own project.
+        if (this.cg && cg !== this.cg) {
+            try {
+                const sameProject = (0, path_1.resolve)(this.cg.getProjectRoot()) === (0, path_1.resolve)(cg.getProjectRoot());
+                if (sameProject)
+                    cg = this.cg;
+            }
+            catch {
+                /* getProjectRoot may throw on a closed instance — leave cg as is */
+            }
+        }
+        // Defensive: some test fakes inject a partial CodeGraph stub without the
+        // newer pending-files API. Treat missing/throwing as "no pending files."
+        let pending = [];
+        try {
+            pending = cg.getPendingFiles?.() ?? [];
+        }
+        catch {
+            return result;
+        }
+        if (pending.length === 0)
+            return result;
+        const [first, ...rest] = result.content;
+        if (!first || first.type !== 'text')
+            return result;
+        const text = first.text;
+        const inResponse = [];
+        const elsewhere = [];
+        for (const p of pending) {
+            // Substring match against the project-relative POSIX path — that's
+            // exactly the format both the watcher and every codegraph response
+            // emit, so a plain includes() is sufficient and avoids regex pitfalls.
+            if (text.includes(p.path))
+                inResponse.push(p);
+            else
+                elsewhere.push(p);
+        }
+        let banner = '';
+        if (inResponse.length > 0) {
+            banner = formatStaleBanner(inResponse);
+        }
+        let footer = '';
+        if (elsewhere.length > 0) {
+            footer = formatStaleFooter(elsewhere);
+        }
+        if (!banner && !footer)
+            return result;
+        const composed = [banner, text, footer].filter(Boolean).join('\n\n');
+        return { ...result, content: [{ type: 'text', text: composed }, ...rest] };
+    }
+    /**
+     * Execute a tool by name
+     */
+    async execute(toolName, args) {
+        try {
+            // Honor the optional tool allowlist (CODEGRAPH_MCP_TOOLS): a trimmed
+            // surface rejects ablated tools defensively even if a client cached them.
+            if (!this.isToolAllowed(toolName)) {
+                return this.errorResult(`Tool ${toolName} is disabled via CODEGRAPH_MCP_TOOLS`);
+            }
+            // Cross-cutting input validation. All tools accept an optional
+            // `projectPath` and most accept either `query`, `task`, or
+            // `symbol` — bound their lengths centrally so individual handlers
+            // can stay focused on tool-specific logic.
+            const pathCheck = this.validateOptionalPath(args.projectPath, 'projectPath');
+            if (typeof pathCheck === 'object' && pathCheck !== undefined) {
+                return pathCheck;
+            }
+            // The `path` and `pattern` properties used by codegraph_files are
+            // also path-shaped — apply the same cap.
+            if (args.path !== undefined) {
+                const check = this.validateOptionalPath(args.path, 'path');
+                if (typeof check === 'object' && check !== undefined)
+                    return check;
+            }
+            if (args.pattern !== undefined) {
+                const check = this.validateOptionalPath(args.pattern, 'pattern');
+                if (typeof check === 'object' && check !== undefined)
+                    return check;
+            }
+            // Read tools resolve through a single result variable so cross-cutting
+            // notices — worktree-index mismatch (issue #155) and per-file
+            // staleness (issue #403) — can be applied in one place. status embeds
+            // its own verbose worktree warning but still flows through the
+            // staleness wrapper so its pending-files section stays consistent
+            // with what the read tools surface.
+            let result;
+            switch (toolName) {
+                case 'codegraph_search':
+                    result = await this.handleSearch(args);
+                    break;
+                case 'codegraph_context':
+                    result = await this.handleContext(args);
+                    break;
+                case 'codegraph_callers':
+                    result = await this.handleCallers(args);
+                    break;
+                case 'codegraph_callees':
+                    result = await this.handleCallees(args);
+                    break;
+                case 'codegraph_impact':
+                    result = await this.handleImpact(args);
+                    break;
+                case 'codegraph_explore':
+                    result = await this.handleExplore(args);
+                    break;
+                case 'codegraph_node':
+                    result = await this.handleNode(args);
+                    break;
+                case 'codegraph_status':
+                    // status embeds the pending-files list as a first-class section
+                    // (see handleStatus), so we skip the auto-banner wrapper here to
+                    // avoid duplicating the same info at the top of the response.
+                    return await this.handleStatus(args);
+                case 'codegraph_files':
+                    result = await this.handleFiles(args);
+                    break;
+                case 'codegraph_trace':
+                    result = await this.handleTrace(args);
+                    break;
+                default:
+                    return this.errorResult(`Unknown tool: ${toolName}`);
+            }
+            const withWorktree = this.withWorktreeNotice(result, args.projectPath);
+            return this.withStalenessNotice(withWorktree, args.projectPath);
+        }
+        catch (err) {
+            return this.errorResult(`Tool execution failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Handle codegraph_search
+     */
+    async handleSearch(args) {
+        const query = this.validateString(args.query, 'query');
+        if (typeof query !== 'string')
+            return query;
+        const cg = this.getCodeGraph(args.projectPath);
+        const kind = args.kind;
+        const rawLimit = Number(args.limit) || 10;
+        const limit = (0, utils_1.clamp)(rawLimit, 1, 100);
+        const results = cg.searchNodes(query, {
+            limit,
+            kinds: kind ? [kind] : undefined,
+        });
+        if (results.length === 0) {
+            return this.textResult(`No results found for "${query}"`);
+        }
+        const formatted = this.formatSearchResults(results);
+        return this.textResult(this.truncateOutput(formatted));
+    }
+    /**
+     * Handle codegraph_context
+     */
+    async handleContext(args) {
+        const task = this.validateString(args.task, 'task');
+        if (typeof task !== 'string')
+            return task;
+        // Mark session as consulted (enables Grep/Glob/Bash)
+        const sessionId = process.env.CLAUDE_SESSION_ID;
+        if (sessionId) {
+            markSessionConsulted(sessionId);
+        }
+        const cg = this.getCodeGraph(args.projectPath);
+        const maxNodes = args.maxNodes || 20;
+        const includeCode = args.includeCode !== false;
+        const context = await cg.buildContext(task, {
+            maxNodes,
+            includeCode,
+            format: 'markdown',
+        });
+        // Detect if this looks like a feature request (vs bug fix or exploration)
+        const isFeatureQuery = this.looksLikeFeatureRequest(task);
+        const reminder = isFeatureQuery
+            ? '\n\n⚠️ **Ask user:** UX preferences, edge cases, acceptance criteria'
+            : '';
+        // buildContext returns string when format is 'markdown'
+        if (typeof context === 'string') {
+            return this.textResult(this.truncateOutput(context + reminder));
+        }
+        // If it returns TaskContext, format it
+        return this.textResult(this.truncateOutput(this.formatTaskContext(context) + reminder));
+    }
+    /**
+     * Heuristic to detect if a query looks like a feature request
+     */
+    looksLikeFeatureRequest(task) {
+        const featureKeywords = [
+            'add', 'create', 'implement', 'build', 'enable', 'allow',
+            'new feature', 'support for', 'ability to', 'want to',
+            'should be able', 'need to add', 'swap', 'edit', 'modify'
+        ];
+        const bugKeywords = [
+            'fix', 'bug', 'error', 'broken', 'crash', 'issue', 'problem',
+            'not working', 'fails', 'undefined', 'null'
+        ];
+        const explorationKeywords = [
+            'how does', 'where is', 'what is', 'find', 'show me',
+            'explain', 'understand', 'explore'
+        ];
+        const lowerTask = task.toLowerCase();
+        // If it's clearly a bug or exploration, not a feature
+        if (bugKeywords.some(k => lowerTask.includes(k)))
+            return false;
+        if (explorationKeywords.some(k => lowerTask.includes(k)))
+            return false;
+        // If it matches feature keywords, it's likely a feature request
+        return featureKeywords.some(k => lowerTask.includes(k));
+    }
+    /**
+     * Handle codegraph_callers
+     */
+    async handleCallers(args) {
+        const symbol = this.validateString(args.symbol, 'symbol');
+        if (typeof symbol !== 'string')
+            return symbol;
+        const cg = this.getCodeGraph(args.projectPath);
+        const limit = (0, utils_1.clamp)(args.limit || 20, 1, 100);
+        const allMatches = this.findAllSymbols(cg, symbol);
+        if (allMatches.nodes.length === 0) {
+            return this.textResult(`Symbol "${symbol}" not found in the codebase`);
+        }
+        // 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 formatted = this.formatNodeList(allCallers.slice(0, limit), `Callers of ${symbol}`) + allMatches.note;
+        return this.textResult(this.truncateOutput(formatted));
+    }
+    /**
+     * Handle codegraph_callees
+     */
+    async handleCallees(args) {
+        const symbol = this.validateString(args.symbol, 'symbol');
+        if (typeof symbol !== 'string')
+            return symbol;
+        const cg = this.getCodeGraph(args.projectPath);
+        const limit = (0, utils_1.clamp)(args.limit || 20, 1, 100);
+        const allMatches = this.findAllSymbols(cg, symbol);
+        if (allMatches.nodes.length === 0) {
+            return this.textResult(`Symbol "${symbol}" not found in the codebase`);
+        }
+        // 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 formatted = this.formatNodeList(allCallees.slice(0, limit), `Callees of ${symbol}`) + allMatches.note;
+        return this.textResult(this.truncateOutput(formatted));
+    }
+    /**
+     * Handle codegraph_impact
+     */
+    async handleImpact(args) {
+        const symbol = this.validateString(args.symbol, 'symbol');
+        if (typeof symbol !== 'string')
+            return symbol;
+        const cg = this.getCodeGraph(args.projectPath);
+        const depth = (0, utils_1.clamp)(args.depth || 2, 1, 10);
+        const allMatches = this.findAllSymbols(cg, symbol);
+        if (allMatches.nodes.length === 0) {
+            return this.textResult(`Symbol "${symbol}" not found in the codebase`);
+        }
+        // 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));
+    }
+    /**
+     * Handle codegraph_trace — shortest CALL PATH between two symbols.
+     *
+     * Exposes GraphTraverser.findPath: the chain of functions from `from` to `to`,
+     * each hop annotated with file:line and the call-site line. This is the
+     * capability grep/Read structurally cannot provide. When no static path
+     * exists, the chain has almost certainly broken at dynamic dispatch
+     * (callbacks, descriptors, metaclasses) — we say so and surface the start
+     * symbol's outgoing calls so the agent bridges the one missing hop with
+     * codegraph_node rather than blindly reading.
+     */
+    async handleTrace(args) {
+        const from = this.validateString(args.from, 'from');
+        if (typeof from !== 'string')
+            return from;
+        const to = this.validateString(args.to, 'to');
+        if (typeof to !== 'string')
+            return to;
+        const cg = this.getCodeGraph(args.projectPath);
+        const fromMatches = this.findAllSymbols(cg, from);
+        if (fromMatches.nodes.length === 0)
+            return this.textResult(`Symbol "${from}" not found in the codebase`);
+        const toMatches = this.findAllSymbols(cg, to);
+        if (toMatches.nodes.length === 0)
+            return this.textResult(`Symbol "${to}" not found in the codebase`);
+        // Trace along call edges only — a true call path. Names can map to several
+        // nodes, so try a few from×to candidate pairs until a usable path turns up.
+        //
+        // MAX_HOPS guard: a BFS shortest path longer than this on a dense call graph
+        // is almost always a spurious wander through unrelated code (django's
+        // `_fetch_all → … → execute_sql` BFS detours through prefetch/filter), not
+        // the real execution flow — and a confident-but-wrong 15-hop trace is worse
+        // than none. Over-cap paths are rejected and reported as "no direct path"
+        // (which, on real code, means the flow breaks at dynamic dispatch).
+        const edgeKinds = ['calls'];
+        const MAX_HOPS = 7;
+        const fromTry = fromMatches.nodes.slice(0, 3);
+        const toTry = toMatches.nodes.slice(0, 3);
+        let path = null;
+        let overCap = null;
+        for (const f of fromTry) {
+            for (const t of toTry) {
+                const p = cg.findPath(f.id, t.id, edgeKinds);
+                if (!p || p.length <= 1)
+                    continue;
+                if (p.length <= MAX_HOPS) {
+                    path = p;
+                    break;
+                }
+                if (!overCap || p.length < overCap.length)
+                    overCap = p;
+            }
+            if (path)
+                break;
+        }
+        if (!path) {
+            // No static path — almost always a dynamic-dispatch break. Surface the
+            // start symbol's outgoing calls so the agent can bridge the gap.
+            const start = fromTry[0];
+            const callees = cg.getCallees(start.id).slice(0, 10)
+                .map(c => `${c.node.name} (${c.node.filePath}:${c.node.startLine})`);
+            const lines = [
+                `No direct call path from "${from}" to "${to}".`,
+                '',
+                (overCap
+                    ? `(Only a ${overCap.length}-hop indirect chain connects them — almost certainly a BFS wander through unrelated code, not the real flow.) `
+                    : '') +
+                    'The direct chain most likely breaks at **dynamic dispatch** (a callback, descriptor, ' +
+                    'metaclass, or attribute-as-callable) that static parsing cannot resolve into an edge. ' +
+                    `Inspect \`${start.name}\` (${start.filePath}:${start.startLine}) with codegraph_node ` +
+                    '(includeCode=true) — its body usually shows the dynamic call to follow next.',
+            ];
+            if (callees.length > 0) {
+                lines.push('', `**${start.name} statically calls:** ${callees.join(', ')}`);
+            }
+            return this.textResult(lines.join('\n') + fromMatches.note + toMatches.note);
+        }
+        const lines = [
+            `## Trace: ${from} → ${to}`,
+            '',
+            `Full execution path below — ${path.length} hops, each with its body, plus what the destination calls. This is the complete flow; answer from it.`,
+            '',
+            `${path.length} hops:`,
+            '',
+        ];
+        // Inline what each hop needs so the agent doesn't Read/Grep to get it: the
+        // call-site source line, the registration site for dynamic-dispatch hops, AND
+        // the hop's own body (capped per hop so the trace stays path-scoped). Earlier
+        // versions inlined only the call-site line, which left agents calling explore
+        // or Read for the bodies — the exact follow-up the ablation experiment measured.
+        const fileCache = new Map();
+        for (let i = 0; i < path.length; i++) {
+            const step = path[i];
+            if (step.edge) {
+                const synth = this.synthEdgeNote(step.edge);
+                if (synth) {
+                    lines.push(`   ↓ ${synth.label}`);
+                    if (synth.registeredAt) {
+                        const regSrc = this.sourceLineAt(cg, synth.registeredAt, fileCache);
+                        lines.push(`     ↳ registered at ${synth.registeredAt}${regSrc ? `   ${regSrc}` : ''}`);
+                    }
+                }
+                else {
+                    // The call happens in the PREVIOUS hop's file at edge.line.
+                    const prev = path[i - 1];
+                    const ref = prev && step.edge.line ? `${prev.node.filePath}:${step.edge.line}` : undefined;
+                    const callSrc = this.sourceLineAt(cg, ref, fileCache);
+                    lines.push(`   ↓ ${step.edge.kind}${step.edge.line ? `@${step.edge.line}` : ''}${callSrc ? `   ${callSrc}` : ''}`);
+                }
+            }
+            lines.push(`${i + 1}. ${step.node.name} (${step.node.filePath}:${step.node.startLine}-${step.node.endLine})`);
+            const body = this.sourceRangeAt(cg, step.node.filePath, step.node.startLine, step.node.endLine, fileCache, 60, 1800);
+            if (body)
+                lines.push(body);
+        }
+        // The "last mile": what the destination does next. Agents otherwise explore/Read
+        // for exactly this (e.g. renderStaticScene → _renderStaticScene → the canvas draw),
+        // so inlining the destination's callees is what actually stops the investigation —
+        // sufficiency, not a "don't explore" instruction.
+        const dest = path[path.length - 1].node;
+        const destCallees = cg.getCallees(dest.id)
+            .filter(c => !path.some(p => p.node.id === c.node.id))
+            .slice(0, 6);
+        if (destCallees.length > 0) {
+            lines.push('', `### \`${dest.name}\` then calls (the destination's immediate work):`);
+            for (const c of destCallees) {
+                lines.push('', `- ${c.node.name} (${c.node.filePath}:${c.node.startLine}-${c.node.endLine})`);
+                const body = this.sourceRangeAt(cg, c.node.filePath, c.node.startLine, c.node.endLine, fileCache, 16, 600);
+                if (body)
+                    lines.push(body);
+            }
+        }
+        lines.push('', '> Full path + every hop body + the destination\'s calls are inlined above — the complete flow. Answer from it; a Read is only needed to chase a specific local variable\'s data-flow.');
+        return this.textResult(this.truncateOutput(lines.join('\n')));
+    }
+    /**
+     * Describe a synthesized (dynamic-dispatch) edge for human output: how the
+     * callback was wired up — the bridge static parsing can't see. Returns null
+     * for ordinary static edges. Used by trace + the node trail so a synthesized
+     * hop reads as "registered via onUpdate at App.tsx:3148", not a bare arrow.
+     */
+    synthEdgeNote(edge) {
+        if (!edge || edge.provenance !== 'heuristic')
+            return null;
+        const m = edge.metadata;
+        const registeredAt = typeof m?.registeredAt === 'string' ? m.registeredAt : undefined;
+        const at = registeredAt ? ` @${registeredAt}` : '';
+        if (m?.synthesizedBy === 'callback') {
+            const via = m.via ? `\`${String(m.via)}\`` : 'a registrar';
+            const field = m.field ? ` on .${String(m.field)}` : '';
+            return {
+                label: `callback — registered via ${via}${field} (dynamic dispatch)`,
+                compact: `dynamic: callback via ${via}${at}`,
+                registeredAt,
+            };
+        }
+        if (m?.synthesizedBy === 'event-emitter') {
+            const ev = m.event ? `\`${String(m.event)}\`` : 'an event';
+            return {
+                label: `event ${ev} — emit → handler (dynamic dispatch)`,
+                compact: `dynamic: event ${ev}${at}`,
+                registeredAt,
+            };
+        }
+        if (m?.synthesizedBy === 'react-render') {
+            return {
+                label: `React re-render — \`setState\` re-runs render() (dynamic dispatch)`,
+                compact: `dynamic: React re-render via setState${at}`,
+                registeredAt,
+            };
+        }
+        if (m?.synthesizedBy === 'jsx-render') {
+            const child = m.via ? `<${String(m.via)}>` : 'a child component';
+            return {
+                label: `renders ${child} (JSX child — dynamic dispatch)`,
+                compact: `dynamic: renders ${child}`,
+                registeredAt,
+            };
+        }
+        if (m?.synthesizedBy === 'vue-handler') {
+            const ev = m.event ? `@${String(m.event)}` : 'a template event';
+            return {
+                label: `Vue template handler — bound to ${ev} (dynamic dispatch)`,
+                compact: `dynamic: Vue ${ev} handler`,
+                registeredAt,
+            };
+        }
+        if (m?.synthesizedBy === 'interface-impl') {
+            return {
+                label: `interface/abstract dispatch — runs the implementation override (dynamic dispatch)`,
+                compact: `dynamic: interface → impl${at}`,
+                registeredAt,
+            };
+        }
+        return null;
+    }
+    /**
+     * Read one trimmed source line at "relpath:line" (relative to the project
+     * root). `cache` holds split file contents so a multi-hop trace reads each
+     * file at most once. Returns null if the file/line can't be resolved.
+     */
+    sourceLineAt(cg, ref, cache) {
+        if (!ref)
+            return null;
+        const i = ref.lastIndexOf(':');
+        if (i < 0)
+            return null;
+        const filePath = ref.slice(0, i);
+        const line = parseInt(ref.slice(i + 1), 10);
+        if (!Number.isFinite(line) || line < 1)
+            return null;
+        let fileLines = cache.get(filePath);
+        if (!fileLines) {
+            const abs = (0, utils_1.validatePathWithinRoot)(cg.getProjectRoot(), filePath);
+            if (!abs || !(0, fs_1.existsSync)(abs))
+                return null;
+            try {
+                fileLines = (0, fs_1.readFileSync)(abs, 'utf-8').split('\n');
+            }
+            catch {
+                return null;
+            }
+            cache.set(filePath, fileLines);
+        }
+        const raw = fileLines[line - 1];
+        if (raw == null)
+            return null;
+        const t = raw.trim();
+        return t.length > 160 ? t.slice(0, 157) + '…' : t;
+    }
+    /**
+     * Read a hop's body — filePath lines [startLine..endLine] — for inlining into
+     * a trace, capped (lines + chars) so the whole path stays path-scoped even on
+     * a 7-hop chain. Dedents to the body's own indentation and marks truncation.
+     * Shares `cache` with sourceLineAt so each file is read at most once per trace.
+     */
+    sourceRangeAt(cg, filePath, startLine, endLine, cache, maxLines = 28, maxChars = 1200) {
+        if (!Number.isFinite(startLine) || startLine < 1)
+            return null;
+        let fileLines = cache.get(filePath);
+        if (!fileLines) {
+            const abs = (0, utils_1.validatePathWithinRoot)(cg.getProjectRoot(), filePath);
+            if (!abs || !(0, fs_1.existsSync)(abs))
+                return null;
+            try {
+                fileLines = (0, fs_1.readFileSync)(abs, 'utf-8').split('\n');
+            }
+            catch {
+                return null;
+            }
+            cache.set(filePath, fileLines);
+        }
+        const end = Number.isFinite(endLine) && endLine >= startLine ? endLine : startLine;
+        let slice = fileLines.slice(startLine - 1, end);
+        if (slice.length === 0)
+            return null;
+        let omitted = 0;
+        if (slice.length > maxLines) {
+            omitted = slice.length - maxLines;
+            slice = slice.slice(0, maxLines);
+        }
+        const nonBlank = slice.filter(l => l.trim().length > 0);
+        const dedent = nonBlank.length ? Math.min(...nonBlank.map(l => l.length - l.trimStart().length)) : 0;
+        let text = slice.map((l, i) => `      ${startLine + i}\t${l.slice(dedent)}`).join('\n');
+        if (text.length > maxChars) {
+            text = text.slice(0, maxChars).replace(/\n[^\n]*$/, '');
+            omitted = Math.max(omitted, 1);
+        }
+        if (omitted > 0)
+            text += `\n      … (+${omitted} more line${omitted === 1 ? '' : 's'})`;
+        return text;
+    }
+    /**
+     * Flow-from-named-symbols: an agent's codegraph_explore query is a bag of
+     * symbol names that usually spans the flow it's investigating (e.g.
+     * "PmsProductController getList PmsProductService list PmsProductServiceImpl").
+     * Surface the longest call chain AMONG those named symbols — scoped to what the
+     * agent explicitly named, so (unlike a fuzzy relevance set) there's no
+     * wrong-feature wandering. Rides synthesized edges, so controller→service-
+     * interface→impl shows up. Returns '' if no chain of >=3 nodes exists.
+     *
+     * Ambiguous tokens (Java `list` → dozens of nodes) are disambiguated by
+     * CO-NAMING: the agent names the class too, so we keep only `list` candidates
+     * whose qualifiedName contains another named token (`PmsProductServiceImpl::list`),
+     * dropping unrelated `OmsOrderService::list`.
+     */
+    buildFlowFromNamedSymbols(cg, query) {
+        try {
+            const CALLABLE = new Set(['method', 'function', 'component', 'constructor']);
+            // Strip only a REAL file extension (Create.cs → Create); KEEP qualified
+            // names (Class.method / Class::method) — the agent's most precise input,
+            // resolved exactly by findAllSymbols. (The old strip mangled Class.method
+            // into Class, throwing the method away.)
+            const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte)$/i;
+            const tokens = [...new Set(query.split(/[\s,()[\]]+/)
+                    .map((t) => t.replace(FILE_EXT, '').trim())
+                    .filter((t) => t.length >= 3 && /^[A-Za-z_$][\w$]*(?:(?:::|\.)[\w$]+)*$/.test(t)))].slice(0, 16);
+            if (tokens.length < 2)
+                return '';
+            // Pool of name SEGMENTS (Class + method from every token) used to
+            // disambiguate an ambiguous SIMPLE name: keep a candidate only if its
+            // CONTAINER class is itself named in the query.
+            const segPool = new Set();
+            for (const t of tokens)
+                for (const s of t.toLowerCase().split(/::|\./))
+                    if (s)
+                        segPool.add(s);
+            const named = new Map();
+            for (const t of tokens) {
+                const cands = this.findAllSymbols(cg, t).nodes.filter((n) => CALLABLE.has(n.kind));
+                // A qualified or otherwise-specific name (<=3 hits) keeps all; an
+                // ambiguous simple name keeps only candidates whose container is named.
+                const pick = cands.length <= 3
+                    ? cands
+                    : cands.filter((n) => {
+                        const segs = (n.qualifiedName || '').toLowerCase().split(/::|\./).filter(Boolean);
+                        const container = segs.length >= 2 ? segs[segs.length - 2] : '';
+                        return !!container && segPool.has(container);
+                    });
+                for (const n of pick.slice(0, 6))
+                    named.set(n.id, n);
+                if (named.size > 40)
+                    break;
+            }
+            if (named.size < 2)
+                return '';
+            const MAX_HOPS = 7;
+            let best = null;
+            // BFS the full call graph (incl. synth edges) from each named seed, but
+            // only ACCEPT a sink that is also named — both ends anchored to symbols the
+            // agent named, so the chain stays on-topic while bridging intermediates
+            // (e.g. the exact interface overload) that the token resolution missed.
+            for (const seed of [...named.values()].slice(0, 8)) {
+                const parent = new Map();
+                parent.set(seed.id, { prev: null, edge: null, node: seed });
+                const q = [{ id: seed.id, depth: 0, streak: 0 }];
+                let deep = null, deepDepth = 0;
+                const MAX_BRIDGE = 1; // ≤1 consecutive UNNAMED hop: bridge one missing intermediate, never wander a god-function's fan-out
+                for (let h = 0; h < q.length && parent.size < 1500; h++) {
+                    const { id, depth, streak } = q[h];
+                    if (id !== seed.id && named.has(id) && depth > deepDepth) {
+                        deep = id;
+                        deepDepth = depth;
+                    }
+                    if (depth >= MAX_HOPS - 1)
+                        continue;
+                    for (const c of cg.getCallees(id)) {
+                        if (c.edge.kind !== 'calls' || parent.has(c.node.id))
+                            continue;
+                        const newStreak = named.has(c.node.id) ? 0 : streak + 1;
+                        if (newStreak > MAX_BRIDGE)
+                            continue;
+                        parent.set(c.node.id, { prev: id, edge: c.edge, node: c.node });
+                        q.push({ id: c.node.id, depth: depth + 1, streak: newStreak });
+                    }
+                }
+                if (!deep)
+                    continue;
+                const chain = [];
+                let cur = deep;
+                while (cur) {
+                    const p = parent.get(cur);
+                    if (!p)
+                        break;
+                    chain.push({ node: p.node, edge: p.edge });
+                    cur = p.prev;
+                }
+                chain.reverse();
+                if (!best || chain.length > best.length)
+                    best = chain;
+            }
+            if (!best || best.length < 3)
+                return '';
+            const out = ['## Flow (call path among the symbols you queried)', ''];
+            for (let i = 0; i < best.length; i++) {
+                const step = best[i];
+                if (step.edge) {
+                    const sy = this.synthEdgeNote(step.edge);
+                    out.push(`   ↓ ${sy ? sy.compact : step.edge.kind}`);
+                }
+                out.push(`${i + 1}. ${step.node.name} (${step.node.filePath}:${step.node.startLine})`);
+            }
+            out.push('', '> Full source for these symbols is below; codegraph_trace(from,to) for the exact path between two endpoints.', '');
+            return out.join('\n');
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * 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.
+     *
+     * Output size is adaptive to project file count via
+     * `getExploreOutputBudget` — see #185 for why a fixed 35k cap was a
+     * tax on small projects while earning its keep on large ones.
+     */
+    async handleExplore(args) {
+        const query = this.validateString(args.query, 'query');
+        if (typeof query !== 'string')
+            return query;
+        const cg = this.getCodeGraph(args.projectPath);
+        const projectRoot = cg.getProjectRoot();
+        // Resolve adaptive output budget from project size. Falls back to the
+        // largest-tier defaults if stats aren't available, which preserves
+        // pre-#185 behavior for callers that hit the rare stats failure.
+        let budget;
+        try {
+            budget = getExploreOutputBudget(cg.getStats().fileCount);
+        }
+        catch {
+            budget = getExploreOutputBudget(Infinity);
+        }
+        const maxFiles = (0, utils_1.clamp)(args.maxFiles || budget.defaultMaxFiles, 1, 20);
+        // Step 1: Find relevant context with generous parameters.
+        // Use a large maxNodes budget — explore has its own 35k char output limit
+        // that prevents context bloat, so more nodes just means better coverage
+        // across entry points (especially for large files like Svelte components).
+        const subgraph = await cg.findRelevantContext(query, {
+            searchLimit: 8,
+            traversalDepth: 3,
+            maxNodes: 200,
+            minScore: 0.2,
+        });
+        if (subgraph.nodes.size === 0) {
+            return this.textResult(`No relevant code found for "${query}"`);
+        }
+        // Graph-aware glue: findRelevantContext builds the subgraph from name/text
+        // search, so a method that BRIDGES named symbols — e.g. App.tsx's
+        // triggerRender, which calls the named triggerUpdate — is never a search hit
+        // and gets missed, forcing the agent to Read the file to trace it. Pull in
+        // the callers/callees of the entry (root) nodes, but ONLY those that live in
+        // files the subgraph already surfaces (where the agent reads to fill gaps),
+        // so we add wiring without dragging in unrelated files. These get an
+        // importance boost below so they survive the per-file cluster budget.
+        const glueNodeIds = new Set();
+        const subgraphFiles = new Set();
+        for (const n of subgraph.nodes.values())
+            subgraphFiles.add(n.filePath);
+        const GLUE_NODE_CAP = 60;
+        for (const rootId of subgraph.roots) {
+            if (glueNodeIds.size >= GLUE_NODE_CAP)
+                break;
+            let neighbors = [];
+            try {
+                neighbors = [
+                    ...cg.getCallers(rootId).map(c => c.node),
+                    ...cg.getCallees(rootId).map(c => c.node),
+                ];
+            }
+            catch {
+                continue;
+            }
+            for (const nb of neighbors) {
+                if (glueNodeIds.size >= GLUE_NODE_CAP)
+                    break;
+                if (subgraph.nodes.has(nb.id))
+                    continue;
+                if (!subgraphFiles.has(nb.filePath))
+                    continue;
+                subgraph.nodes.set(nb.id, nb);
+                glueNodeIds.add(nb.id);
+            }
+        }
+        // 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 (budget.includeRelationships && 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) {
+                const cap = budget.maxEdgesPerRelationshipKind;
+                const shown = edges.slice(0, cap);
+                lines.push(`**${kind}:**`);
+                for (const e of shown) {
+                    lines.push(`- ${e.source} → ${e.target}`);
+                }
+                if (edges.length > cap) {
+                    lines.push(`- ... and ${edges.length - cap} more`);
+                }
+                lines.push('');
+            }
+        }
+        // Step 4: Read contiguous file sections
+        lines.push('### Source Code');
+        lines.push('');
+        lines.push('> The code below is the **verbatim, current on-disk source** of these files — re-read from disk on this call and line-numbered, byte-for-byte identical to what the Read tool returns. It is NOT a summary, outline, or stale cache. Treat each block as a Read you have already performed: do not Read a file shown here.');
+        lines.push('');
+        let totalChars = lines.join('\n').length;
+        let filesIncluded = 0;
+        let anyFileTrimmed = false;
+        for (const [filePath, group] of sortedFiles) {
+            if (filesIncluded >= maxFiles)
+                break;
+            if (totalChars > budget.maxOutputChars * 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 || '';
+            // Whole-small-file rule: if a relevant file is small enough to afford,
+            // return it ENTIRELY instead of clustering. Clustering exists to tame
+            // god-files (App.tsx ~13k lines); on a ~134-line component a cluster is a
+            // lossy subset of a file the agent will just Read in full anyway — costing
+            // a round-trip and a re-read every later turn. Reserve clustering for files
+            // too big to ship whole. Still bounded by the total maxOutputChars check.
+            const WHOLE_FILE_MAX_LINES = 220;
+            const WHOLE_FILE_MAX_CHARS = budget.maxCharsPerFile * 3;
+            if (fileLines.length <= WHOLE_FILE_MAX_LINES && fileContent.length <= WHOLE_FILE_MAX_CHARS) {
+                const body = fileContent.replace(/\n+$/, '');
+                let wholeSection = exploreLineNumbersEnabled() ? numberSourceLines(body, 1) : body;
+                const uniqSymbols = [...new Set(group.nodes
+                        .filter(n => n.kind !== 'import' && n.kind !== 'export')
+                        .map(n => `${n.name}(${n.kind})`))];
+                const headerNames = uniqSymbols.slice(0, budget.maxSymbolsInFileHeader);
+                const omitted = uniqSymbols.length - headerNames.length;
+                const wholeHeader = `#### ${filePath} — ${omitted > 0 ? `${headerNames.join(', ')}, +${omitted} more` : headerNames.join(', ')}`;
+                if (totalChars + wholeSection.length + 200 > budget.maxOutputChars) {
+                    const remaining = budget.maxOutputChars - totalChars - 200;
+                    if (remaining < 500)
+                        break;
+                    wholeSection = wholeSection.slice(0, remaining) + '\n... (trimmed) ...';
+                    anyFileTrimmed = true;
+                }
+                lines.push(wholeHeader, '', '```' + lang, wholeSection, '```', '');
+                totalChars += wholeSection.length + 200;
+                filesIncluded++;
+                continue;
+            }
+            // Cluster nearby symbols to avoid reading huge gaps between distant symbols.
+            // Sort by start line, then merge overlapping/adjacent ranges (within the
+            // adaptive gap threshold). Include both node ranges AND edge source
+            // locations so template sections with component usages/calls are
+            // covered (not just script block symbols).
+            //
+            // Each range carries an `importance` score so we can rank clusters
+            // when the per-file budget forces us to drop some: entry-point nodes
+            // are worth 10, directly-connected nodes 3, peripheral nodes 1, and
+            // bare edge-source lines 2 (less than a connected node but more than
+            // a peripheral one — they hint at a reference but aren't a definition).
+            // Container kinds whose body can span most/all of a file. When such a
+            // node covers most of the file we drop it from the ranges: keeping it
+            // would merge every method inside it into one giant cluster spanning
+            // the whole file, which then tail-trims down to just the container's
+            // opening lines (its header/declarations) and buries the methods the
+            // query actually asked about (#185 follow-up — Session.swift in
+            // Alamofire is the canonical case: the `Session` class spans ~1,400
+            // lines). We want the granular symbols inside, not the envelope.
+            const ENVELOPE_KINDS = new Set(['file', 'module', 'class', 'struct', 'interface', 'enum', 'namespace', 'protocol', 'trait', 'component']);
+            const ranges = group.nodes
+                .filter(n => n.startLine > 0 && n.endLine > 0)
+                // Drop whole-file envelope nodes (containers covering >50% of the file).
+                .filter(n => !(ENVELOPE_KINDS.has(n.kind) && (n.endLine - n.startLine + 1) > fileLines.length * 0.5))
+                .map(n => {
+                let importance = 1;
+                if (entryNodeIds.has(n.id))
+                    importance = 10;
+                else if (glueNodeIds.has(n.id))
+                    importance = 6; // bridging caller/callee of an entry
+                else if (connectedToEntry.has(n.id))
+                    importance = 3;
+                return { start: n.startLine, end: n.endLine, name: n.name, kind: n.kind, importance };
+            });
+            // Add edge source locations in this file — captures template references
+            // (component usages, event handlers) that aren't nodes themselves.
+            // Query edges directly from the DB (not just the subgraph) because BFS
+            // traversal may have pruned template reference targets due to node budget.
+            const edgeLines = new Set(); // dedup by "line:name"
+            for (const node of group.nodes) {
+                const outgoing = cg.getOutgoingEdges(node.id);
+                for (const edge of outgoing) {
+                    if (!edge.line || edge.line <= 0 || edge.kind === 'contains')
+                        continue;
+                    const key = `${edge.line}:${edge.target}`;
+                    if (edgeLines.has(key))
+                        continue;
+                    edgeLines.add(key);
+                    // Look up target name from subgraph first, fall back to edge kind
+                    const targetNode = subgraph.nodes.get(edge.target);
+                    const targetName = targetNode?.name ?? edge.kind;
+                    ranges.push({ start: edge.line, end: edge.line, name: targetName, kind: edge.kind, importance: 2 });
+                }
+            }
+            ranges.sort((a, b) => a.start - b.start);
+            if (ranges.length === 0)
+                continue;
+            const gapThreshold = budget.gapThreshold;
+            const clusters = [];
+            let current = {
+                start: ranges[0].start,
+                end: ranges[0].end,
+                symbols: [`${ranges[0].name}(${ranges[0].kind})`],
+                score: ranges[0].importance,
+                maxImportance: ranges[0].importance,
+            };
+            for (let i = 1; i < ranges.length; i++) {
+                const r = ranges[i];
+                if (r.start <= current.end + gapThreshold) {
+                    current.end = Math.max(current.end, r.end);
+                    current.symbols.push(`${r.name}(${r.kind})`);
+                    current.score += r.importance;
+                    current.maxImportance = Math.max(current.maxImportance, r.importance);
+                }
+                else {
+                    clusters.push(current);
+                    current = {
+                        start: r.start,
+                        end: r.end,
+                        symbols: [`${r.name}(${r.kind})`],
+                        score: r.importance,
+                        maxImportance: r.importance,
+                    };
+                }
+            }
+            clusters.push(current);
+            // Build file section output from clusters, capped by per-file budget.
+            // The pathological case (#185): a file like Session.swift where every
+            // method is adjacent collapses into one cluster spanning the whole
+            // file, and dumping that into the agent's context is most of the
+            // token cost on small projects. We pick clusters in priority order
+            // until the per-file char cap is hit. Truly enormous single clusters
+            // get tail-trimmed with a marker.
+            const contextPadding = 3;
+            const withLineNumbers = exploreLineNumbersEnabled();
+            const buildSection = (c) => {
+                const startIdx = Math.max(0, c.start - 1 - contextPadding);
+                const endIdx = Math.min(fileLines.length, c.end + contextPadding);
+                const slice = fileLines.slice(startIdx, endIdx).join('\n');
+                // startIdx is 0-based, so the slice's first line is line startIdx + 1.
+                return withLineNumbers ? numberSourceLines(slice, startIdx + 1) : slice;
+            };
+            // Language-neutral separator (no `//` — not a comment in Python, Ruby,
+            // etc.). With line numbers on, the line-number jump also signals the gap.
+            const GAP_MARKER = '\n\n... (gap) ...\n\n';
+            // Rank clusters for inclusion under the per-file cap. Entry-point
+            // clusters come first: a cluster containing a query entry point
+            // (importance 10) must outrank a dense block of mere declarations,
+            // otherwise on a large file like Session.swift the top-of-file class
+            // header + property list (many adjacent low-importance nodes, high
+            // density) wins the budget and buries the actual methods the query
+            // asked about (perform/didCreateURLRequest/task live deep in the
+            // file). Within the same importance tier, prefer density (score per
+            // line) so we still favor focused clusters over sprawling ones, then
+            // smaller span as a cheap-to-include tiebreak.
+            const rankedClusters = clusters
+                .map((c, i) => ({ idx: i, span: c.end - c.start + 1, c }))
+                .sort((a, b) => {
+                if (b.c.maxImportance !== a.c.maxImportance)
+                    return b.c.maxImportance - a.c.maxImportance;
+                const densityA = a.c.score / a.span;
+                const densityB = b.c.score / b.span;
+                if (densityB !== densityA)
+                    return densityB - densityA;
+                if (b.c.score !== a.c.score)
+                    return b.c.score - a.c.score;
+                return a.span - b.span;
+            });
+            const chosenIndices = new Set();
+            let projectedChars = 0;
+            for (const rc of rankedClusters) {
+                const sectionLen = buildSection(rc.c).length + (chosenIndices.size > 0 ? GAP_MARKER.length : 0);
+                // Always take the top-ranked cluster, even if oversize, so we don't
+                // return an empty file section (agent would then re-Read the file,
+                // negating the savings).
+                if (chosenIndices.size === 0) {
+                    chosenIndices.add(rc.idx);
+                    projectedChars += sectionLen;
+                    continue;
+                }
+                if (projectedChars + sectionLen > budget.maxCharsPerFile)
+                    continue;
+                chosenIndices.add(rc.idx);
+                projectedChars += sectionLen;
+            }
+            // Emit chosen clusters in source order so the file reads top-to-bottom.
+            let fileSection = '';
+            const allSymbols = [];
+            let fileTrimmed = false;
+            for (let i = 0; i < clusters.length; i++) {
+                if (!chosenIndices.has(i))
+                    continue;
+                const cluster = clusters[i];
+                const section = buildSection(cluster);
+                if (fileSection.length > 0)
+                    fileSection += GAP_MARKER;
+                fileSection += section;
+                allSymbols.push(...cluster.symbols);
+            }
+            // If a single chosen cluster is still oversize (long monolithic
+            // function), tail-trim it. Better one trimmed view than nothing.
+            if (fileSection.length > budget.maxCharsPerFile) {
+                fileSection = fileSection.slice(0, budget.maxCharsPerFile) + '\n... (trimmed) ...';
+                fileTrimmed = true;
+            }
+            if (chosenIndices.size < clusters.length || fileTrimmed) {
+                anyFileTrimmed = true;
+            }
+            // Dedupe + cap the symbols list shown in the per-file header. Some
+            // files (Session.swift in Alamofire) produced 3.4KB symbol lists
+            // from cluster scoring + edge-source lines, dwarfing the per-file
+            // body cap. Show top names by frequency, with a "+N more" tail.
+            const symbolCounts = new Map();
+            for (const s of allSymbols) {
+                symbolCounts.set(s, (symbolCounts.get(s) ?? 0) + 1);
+            }
+            const sortedSymbols = [...symbolCounts.entries()]
+                .sort((a, b) => b[1] - a[1])
+                .map(([name]) => name);
+            const headerCap = budget.maxSymbolsInFileHeader;
+            const headerSymbols = sortedSymbols.slice(0, headerCap);
+            const omittedCount = sortedSymbols.length - headerSymbols.length;
+            const headerSuffix = omittedCount > 0
+                ? `${headerSymbols.join(', ')}, +${omittedCount} more`
+                : headerSymbols.join(', ');
+            const fileHeader = `#### ${filePath} — ${headerSuffix}`;
+            // Respect the total output cap on a file-by-file basis.
+            if (totalChars + fileSection.length + 200 > budget.maxOutputChars) {
+                const remaining = budget.maxOutputChars - totalChars - 200;
+                if (remaining < 500)
+                    break;
+                const trimmed = fileSection.slice(0, remaining) + '\n... (trimmed) ...';
+                lines.push(fileHeader);
+                lines.push('');
+                lines.push('```' + lang);
+                lines.push(trimmed);
+                lines.push('```');
+                lines.push('');
+                totalChars += trimmed.length + 200;
+                filesIncluded++;
+                anyFileTrimmed = true;
+                break;
+            }
+            lines.push(fileHeader);
+            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).
+        // Small projects (per budget) skip this — the relevant story already fits
+        // in the source section, and a trailing pointer list is pure overhead.
+        if (budget.includeAdditionalFiles) {
+            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('### Not shown above — explore these names for their source');
+                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.
+        // On small projects the budget gates this off — but if we actually had to
+        // trim or drop clusters, surface a brief note so the agent knows it can
+        // still Read for more detail.
+        if (budget.includeCompletenessSignal) {
+            lines.push('');
+            lines.push('---');
+            lines.push(`> **Complete source for ${filesIncluded} files is included above — do NOT re-read them.** If your question also needs files/symbols listed under "Not shown above" (or any area this call didn't cover), make ANOTHER codegraph_explore targeting those names — it returns the same source with line numbers and is cheaper and more complete than reading. Reserve Read for a single specific line range explore can't surface.`);
+        }
+        else if (anyFileTrimmed) {
+            lines.push('');
+            lines.push(`> Some file sections were trimmed for size. For a specific symbol you still need, run another \`codegraph_explore\` (or \`codegraph_node\`) with its exact name — line-numbered source, cheaper and more complete than Read.`);
+        }
+        // Add explore budget note based on project size
+        if (budget.includeBudgetNote) {
+            try {
+                const stats = cg.getStats();
+                const callBudget = getExploreBudget(stats.fileCount);
+                lines.push('');
+                lines.push(`> **Explore budget: ${callBudget} calls for this project (${stats.fileCount.toLocaleString()} files indexed).** Each call covers ~6 files; if your question spans more, spend your remaining calls on the uncovered area BEFORE falling back to Read — another explore is cheaper and more complete than reading those files. Synthesize once you've used ${callBudget}.`);
+            }
+            catch {
+                // Stats unavailable — skip budget note
+            }
+        }
+        // Hard-cap to the adaptive budget. The per-file loop bounds the source
+        // sections, but the relationship map, additional-files list, and
+        // completeness/budget notes can still push the assembled output past
+        // maxOutputChars (observed 30k against a 28k tier cap). A fat explore
+        // payload persists in the agent's context and is re-read as cache-input
+        // on every subsequent turn, so the overrun is paid many times over.
+        const output = this.buildFlowFromNamedSymbols(cg, query) + lines.join('\n');
+        if (output.length > budget.maxOutputChars) {
+            const cut = output.slice(0, budget.maxOutputChars);
+            const lastNewline = cut.lastIndexOf('\n');
+            const safe = lastNewline > budget.maxOutputChars * 0.8 ? cut.slice(0, lastNewline) : cut;
+            return this.textResult(safe + '\n\n... (output truncated to budget; the source above is complete and verbatim — treat it as already Read. For any area not covered, run another codegraph_explore with the specific names — do NOT Read these files.)');
+        }
+        return this.textResult(output);
+    }
+    /**
+     * Handle codegraph_node
+     */
+    async handleNode(args) {
+        const symbol = this.validateString(args.symbol, 'symbol');
+        if (typeof symbol !== 'string')
+            return symbol;
+        const cg = this.getCodeGraph(args.projectPath);
+        // Default to false to minimize context usage
+        const includeCode = args.includeCode === true;
+        const match = this.findSymbol(cg, symbol);
+        if (!match) {
+            return this.textResult(`Symbol "${symbol}" not found in the codebase`);
+        }
+        let code = null;
+        let outline = null;
+        if (includeCode) {
+            // For container symbols (class/interface/struct/…), the full body is the
+            // sum of every method body — a wall of source (e.g. a 10k-char class)
+            // that bloats context and is rarely needed in full. Return a structural
+            // outline (members + signatures + line numbers) instead; the agent can
+            // Read or codegraph_node a specific method for its body. Leaf symbols
+            // (function/method/etc.) return their full body as before.
+            if (CONTAINER_NODE_KINDS.has(match.node.kind)) {
+                outline = this.buildContainerOutline(cg, match.node);
+            }
+            if (!outline) {
+                code = await cg.getCode(match.node.id);
+            }
+        }
+        const trail = this.formatTrail(cg, match.node);
+        const formatted = this.formatNodeDetails(match.node, code, outline) + trail + match.note;
+        return this.textResult(this.truncateOutput(formatted));
+    }
+    /**
+     * Build the "trail" for a symbol: its direct callees (what it calls) and
+     * callers (what calls it), each with file:line — so codegraph_node doubles as
+     * the structural Grep→Read→expand primitive: a spot PLUS where to go next.
+     * Capped to stay cheap. Walk the graph by calling codegraph_node on a trail
+     * entry; no Read needed for covered hops. Empty edges on a non-leaf often mean
+     * dynamic dispatch the static graph couldn't resolve — that absence is itself
+     * a signal (read that one hop) rather than a dead end.
+     */
+    formatTrail(cg, node) {
+        const TRAIL_CAP = 12;
+        const fmt = (e) => {
+            const base = `${e.node.name} (${e.node.filePath}:${e.node.startLine})`;
+            const synth = this.synthEdgeNote(e.edge);
+            return synth ? `${base} [${synth.compact}]` : base;
+        };
+        const collect = (edges) => {
+            const seen = new Set([node.id]);
+            const out = [];
+            for (const e of edges) {
+                if (seen.has(e.node.id))
+                    continue;
+                seen.add(e.node.id);
+                out.push(e);
+            }
+            return out;
+        };
+        const callees = collect(cg.getCallees(node.id));
+        const callers = collect(cg.getCallers(node.id));
+        if (callees.length === 0 && callers.length === 0)
+            return '';
+        const lines = ['', '### Trail — codegraph_node any of these to follow it (no Read needed)'];
+        if (callees.length > 0) {
+            lines.push(`**Calls →** ${callees.slice(0, TRAIL_CAP).map(fmt).join(', ')}${callees.length > TRAIL_CAP ? `, +${callees.length - TRAIL_CAP} more` : ''}`);
+        }
+        if (callers.length > 0) {
+            lines.push(`**Called by ←** ${callers.slice(0, TRAIL_CAP).map(fmt).join(', ')}${callers.length > TRAIL_CAP ? `, +${callers.length - TRAIL_CAP} more` : ''}`);
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Handle codegraph_status
+     */
+    async handleStatus(args) {
+        let cg = this.getCodeGraph(args.projectPath);
+        // Same trick as withStalenessNotice — when an explicit projectPath
+        // resolves to the same project as the default session cg, prefer the
+        // default so getPendingFiles() (only populated by the default's watcher)
+        // is non-empty when there are pending edits.
+        if (this.cg && cg !== this.cg) {
+            try {
+                if ((0, path_1.resolve)(this.cg.getProjectRoot()) === (0, path_1.resolve)(cg.getProjectRoot())) {
+                    cg = this.cg;
+                }
+            }
+            catch { /* closed instance — leave as is */ }
+        }
+        const stats = cg.getStats();
+        // Warn when this index actually belongs to a different git working tree
+        // (e.g. the server resolved up from a nested worktree to the main checkout).
+        // Queries then reflect that tree's branch, not the worktree being edited.
+        // status shows the verbose, multi-line form; the read tools get the compact
+        // one-liner via withWorktreeNotice. Both share the cached detection.
+        const mismatch = this.worktreeMismatchFor(args.projectPath);
+        const lines = [
+            '## CodeGraph Status',
+            '',
+        ];
+        if (mismatch) {
+            lines.push(`> ⚠ ${(0, worktree_1.worktreeMismatchWarning)(mismatch).replace(/\n/g, '\n> ')}`, '');
+        }
+        lines.push(`**Files indexed:** ${stats.fileCount}`, `**Total nodes:** ${stats.nodeCount}`, `**Total edges:** ${stats.edgeCount}`, `**Database size:** ${(stats.dbSizeBytes / 1024 / 1024).toFixed(2)} MB`);
+        // Surface the active SQLite backend (node:sqlite, Node's built-in real
+        // SQLite — full WAL + FTS5, no native build).
+        lines.push(`**Backend:** node:sqlite (Node built-in) — full WAL + FTS5`);
+        // Effective journal mode. 'wal' ⇒ concurrent reads never block on a writer;
+        // anything else ⇒ they can ("database is locked"). node:sqlite supports WAL
+        // everywhere, so a non-wal mode means the filesystem can't (network/
+        // virtualized mounts, WSL2 /mnt). See issue #238.
+        const journalMode = cg.getJournalMode();
+        if (journalMode === 'wal') {
+            lines.push(`**Journal mode:** wal (concurrent reads safe)`);
+        }
+        else {
+            lines.push(`**Journal mode:** ⚠ ${journalMode || 'unknown'} — WAL not active, so reads ` +
+                `can block on a concurrent write (WAL appears unsupported on this filesystem)`);
+        }
+        lines.push('', '### Nodes by Kind:');
+        for (const [kind, count] of Object.entries(stats.nodesByKind)) {
+            if (count > 0) {
+                lines.push(`- ${kind}: ${count}`);
+            }
+        }
+        lines.push('', '### Languages:');
+        for (const [lang, count] of Object.entries(stats.filesByLanguage)) {
+            if (count > 0) {
+                lines.push(`- ${lang}: ${count}`);
+            }
+        }
+        // Per-file freshness — the inverse of the auto-prepended staleness banner
+        // (issue #403). Surfacing it inside `status` gives the agent a single
+        // place to ask "is the index caught up?" rather than inferring from
+        // banners on other tool calls.
+        const pending = cg.getPendingFiles();
+        if (pending.length > 0) {
+            lines.push('', '### Pending sync:');
+            const now = Date.now();
+            for (const p of pending) {
+                const ageMs = Math.max(0, now - p.lastSeenMs);
+                const label = p.indexing ? 'indexing in progress' : 'pending sync';
+                lines.push(`- ${p.path} (edited ${ageMs}ms ago, ${label})`);
+            }
+        }
+        return this.textResult(lines.join('\n'));
+    }
+    /**
+     * Handle codegraph_files - get project file structure from the index
+     */
+    async handleFiles(args) {
+        const cg = this.getCodeGraph(args.projectPath);
+        const pathFilter = args.path;
+        const pattern = args.pattern;
+        const format = args.format || 'tree';
+        const includeMetadata = args.includeMetadata !== false;
+        const maxDepth = args.maxDepth != null ? (0, utils_1.clamp)(args.maxDepth, 1, 20) : undefined;
+        // Get all files from the index
+        const allFiles = cg.getFiles();
+        if (allFiles.length === 0) {
+            return this.textResult('No files indexed. Run `codegraph index` first.');
+        }
+        // Filter by path prefix. Stored paths are project-relative POSIX (e.g.
+        // "src/foo.ts"), but agents commonly pass project-root variants like "/",
+        // ".", "./", "" or Windows-style "src\foo" — and prefixes with leading
+        // "/", "./" or "\". Normalize all of those before matching so the agent
+        // gets results instead of falling back to Read/Glob (see #426).
+        const normalizedFilter = pathFilter
+            ? pathFilter
+                .replace(/\\/g, '/')
+                .replace(/^(?:\.?\/+)+/, '')
+                .replace(/^\.$/, '')
+                .replace(/\/+$/, '')
+            : '';
+        let files = normalizedFilter
+            ? allFiles.filter(f => f.path === normalizedFilter || f.path.startsWith(normalizedFilter + '/'))
+            : allFiles;
+        // Filter by glob pattern
+        if (pattern) {
+            const regex = this.globToRegex(pattern);
+            files = files.filter(f => regex.test(f.path));
+        }
+        if (files.length === 0) {
+            return this.textResult(`No files found matching the criteria.`);
+        }
+        // Format output
+        let output;
+        switch (format) {
+            case 'flat':
+                output = this.formatFilesFlat(files, includeMetadata);
+                break;
+            case 'grouped':
+                output = this.formatFilesGrouped(files, includeMetadata);
+                break;
+            case 'tree':
+            default:
+                output = this.formatFilesTree(files, includeMetadata, maxDepth);
+                break;
+        }
+        return this.textResult(this.truncateOutput(output));
+    }
+    /**
+     * Convert glob pattern to regex
+     */
+    globToRegex(pattern) {
+        const escaped = pattern
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&') // Escape special regex chars except * and ?
+            .replace(/\*\*/g, '{{GLOBSTAR}}') // Temp placeholder for **
+            .replace(/\*/g, '[^/]*') // * matches anything except /
+            .replace(/\?/g, '[^/]') // ? matches single char except /
+            .replace(/\{\{GLOBSTAR\}\}/g, '.*'); // ** matches anything including /
+        return new RegExp(escaped);
+    }
+    /**
+     * Format files as a flat list
+     */
+    formatFilesFlat(files, includeMetadata) {
+        const lines = [`## Files (${files.length})`, ''];
+        for (const file of files.sort((a, b) => a.path.localeCompare(b.path))) {
+            if (includeMetadata) {
+                lines.push(`- ${file.path} (${file.language}, ${file.nodeCount} symbols)`);
+            }
+            else {
+                lines.push(`- ${file.path}`);
+            }
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Format files grouped by language
+     */
+    formatFilesGrouped(files, includeMetadata) {
+        const byLang = new Map();
+        for (const file of files) {
+            const existing = byLang.get(file.language) || [];
+            existing.push(file);
+            byLang.set(file.language, existing);
+        }
+        const lines = [`## Files by Language (${files.length} total)`, ''];
+        // Sort languages by file count (descending)
+        const sortedLangs = [...byLang.entries()].sort((a, b) => b[1].length - a[1].length);
+        for (const [lang, langFiles] of sortedLangs) {
+            lines.push(`### ${lang} (${langFiles.length})`);
+            for (const file of langFiles.sort((a, b) => a.path.localeCompare(b.path))) {
+                if (includeMetadata) {
+                    lines.push(`- ${file.path} (${file.nodeCount} symbols)`);
+                }
+                else {
+                    lines.push(`- ${file.path}`);
+                }
+            }
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Format files as a tree structure
+     */
+    formatFilesTree(files, includeMetadata, maxDepth) {
+        const root = { name: '', children: new Map() };
+        for (const file of files) {
+            const parts = file.path.split('/');
+            let current = root;
+            for (let i = 0; i < parts.length; i++) {
+                const part = parts[i];
+                if (!part)
+                    continue;
+                if (!current.children.has(part)) {
+                    current.children.set(part, { name: part, children: new Map() });
+                }
+                current = current.children.get(part);
+                // If this is the last part, it's a file
+                if (i === parts.length - 1) {
+                    current.file = { language: file.language, nodeCount: file.nodeCount };
+                }
+            }
+        }
+        // Render tree
+        const lines = [`## Project Structure (${files.length} files)`, ''];
+        const renderNode = (node, prefix, isLast, depth) => {
+            if (maxDepth !== undefined && depth > maxDepth)
+                return;
+            const connector = isLast ? '└── ' : '├── ';
+            const childPrefix = isLast ? '    ' : '│   ';
+            if (node.name) {
+                let line = prefix + connector + node.name;
+                if (node.file && includeMetadata) {
+                    line += ` (${node.file.language}, ${node.file.nodeCount} symbols)`;
+                }
+                lines.push(line);
+            }
+            const children = [...node.children.values()];
+            // Sort: directories first, then files, both alphabetically
+            children.sort((a, b) => {
+                const aIsDir = a.children.size > 0 && !a.file;
+                const bIsDir = b.children.size > 0 && !b.file;
+                if (aIsDir !== bIsDir)
+                    return aIsDir ? -1 : 1;
+                return a.name.localeCompare(b.name);
+            });
+            for (let i = 0; i < children.length; i++) {
+                const child = children[i];
+                const nextPrefix = node.name ? prefix + childPrefix : prefix;
+                renderNode(child, nextPrefix, i === children.length - 1, depth + 1);
+            }
+        };
+        renderNode(root, '', true, 0);
+        return lines.join('\n');
+    }
+    // =========================================================================
+    // Symbol resolution helpers
+    // =========================================================================
+    /**
+     * 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.
+     *
+     * Accepts simple names (`run`) and three flavors of qualifier:
+     *   - dotted     `Session.request`         (TS/JS/Python)
+     *   - colon-pair `stage_apply::run`        (Rust, C++, Ruby)
+     *   - slash      `configurator/stage_apply` (path-ish)
+     *
+     * Multi-level qualifiers compose: `crate::configurator::stage_apply::run`
+     * works. Rust path prefixes (`crate`, `super`, `self`) are stripped so
+     * the canonical `crate::module::symbol` form resolves.
+     *
+     * Resolution order, last part must always equal `node.name`:
+     *   1. Suffix-match against `qualifiedName` (handles class-scoped methods
+     *      where the extractor builds the qualified name from the AST stack)
+     *   2. File-path containment (handles file-derived modules in Rust/
+     *      Python — `stage_apply::run` matches a `run` in `stage_apply.rs`)
+     */
+    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 lookups: split on any supported separator. `\w` keeps
+        // identifier chars (incl. `_`) intact; everything else is treated as
+        // a separator we tolerate.
+        if (!/[.\/]|::/.test(symbol))
+            return false;
+        const parts = symbol.split(/::|[./]/).filter((p) => p.length > 0);
+        if (parts.length < 2)
+            return false;
+        const lastPart = parts[parts.length - 1];
+        if (node.name !== lastPart)
+            return false;
+        // Stage 1: qualified-name suffix match. The extractor joins the
+        // semantic hierarchy with `::`, so `Session.request` and
+        // `Session::request` both become `Session::request` here.
+        const colonSuffix = parts.join('::');
+        if (node.qualifiedName.includes(colonSuffix))
+            return true;
+        // Stage 2: file-path containment. Rust modules and Python packages
+        // are not in `qualifiedName` — they're encoded in the file path. So
+        // `stage_apply::run` matches a `run` in any file whose path
+        // contains a `stage_apply` segment (with or without an extension).
+        //
+        // Filter out Rust path prefixes that have no file-system equivalent.
+        const containerHints = parts.slice(0, -1).filter((p) => !RUST_PATH_PREFIXES.has(p));
+        if (containerHints.length === 0)
+            return false;
+        const segments = node.filePath.split('/').filter((s) => s.length > 0);
+        return containerHints.every((hint) => segments.some((seg) => seg === hint || seg.replace(/\.[^.]+$/, '') === hint));
+    }
+    findSymbol(cg, symbol) {
+        // Use higher limit for qualified lookups (e.g., "Session.request",
+        // "stage_apply::run") since the target may rank lower in FTS when
+        // there are many partial matches across the qualifier parts.
+        const isQualified = /[.\/]|::/.test(symbol);
+        const limit = isQualified ? 50 : 10;
+        let results = cg.searchNodes(symbol, { limit });
+        // FTS strips colons as a special char, so `stage_apply::run` searches
+        // for the literal `stage_applyrun` and finds nothing. Re-search by
+        // the bare last part and let `matchesSymbol` filter by qualifier.
+        if (isQualified && results.length === 0) {
+            const tail = lastQualifierPart(symbol);
+            if (tail && tail !== symbol)
+                results = cg.searchNodes(tail, { limit });
+        }
+        if (results.length === 0 || !results[0]) {
+            return null;
+        }
+        const exactMatches = results.filter(r => this.matchesSymbol(r.node, symbol));
+        if (exactMatches.length === 1) {
+            return { node: exactMatches[0].node, note: '' };
+        }
+        if (exactMatches.length > 1) {
+            // Multiple exact matches - pick first, note the others
+            const picked = exactMatches[0].node;
+            const others = exactMatches.slice(1).map(r => `${r.node.name} (${r.node.kind}) at ${r.node.filePath}:${r.node.startLine}`);
+            const note = `\n\n> **Note:** ${exactMatches.length} symbols named "${symbol}". Showing results for \`${picked.filePath}:${picked.startLine}\`. Others: ${others.join(', ')}`;
+            return { node: picked, note };
+        }
+        // No exact match. For qualified lookups, don't silently fall back
+        // to a fuzzy result — the user typed a specific qualifier, and
+        // resolving `stage_apply::nonexistent_fn` to the unrelated
+        // `stage_apply.rs` file would be actively misleading (#173).
+        if (isQualified)
+            return null;
+        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) {
+        let results = cg.searchNodes(symbol, { limit: 50 });
+        // Mirror the fallback in `findSymbol` for qualified queries — FTS
+        // strips colons, so a module-qualified lookup needs a second pass
+        // by the bare last part.
+        if (results.length === 0 && /[.\/]|::/.test(symbol)) {
+            const tail = lastQualifierPart(symbol);
+            if (tail && tail !== symbol)
+                results = cg.searchNodes(tail, { 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
+     */
+    truncateOutput(text) {
+        if (text.length <= MAX_OUTPUT_LENGTH)
+            return text;
+        const truncated = text.slice(0, MAX_OUTPUT_LENGTH);
+        const lastNewline = truncated.lastIndexOf('\n');
+        const cutPoint = lastNewline > MAX_OUTPUT_LENGTH * 0.8 ? lastNewline : MAX_OUTPUT_LENGTH;
+        return truncated.slice(0, cutPoint) + '\n\n... (output truncated)';
+    }
+    // =========================================================================
+    // Formatting helpers (compact by default to reduce context usage)
+    // =========================================================================
+    formatSearchResults(results) {
+        const lines = [`## Search Results (${results.length} found)`, ''];
+        for (const result of results) {
+            const { node } = result;
+            const location = node.startLine ? `:${node.startLine}` : '';
+            // Compact format: one line per result with key info
+            lines.push(`### ${node.name} (${node.kind})`);
+            lines.push(`${node.filePath}${location}`);
+            if (node.signature)
+                lines.push(`\`${node.signature}\``);
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    formatNodeList(nodes, title) {
+        const lines = [`## ${title} (${nodes.length} found)`, ''];
+        for (const node of nodes) {
+            const location = node.startLine ? `:${node.startLine}` : '';
+            // Compact: just name, kind, location
+            lines.push(`- ${node.name} (${node.kind}) - ${node.filePath}${location}`);
+        }
+        return lines.join('\n');
+    }
+    formatImpact(symbol, impact) {
+        const nodeCount = impact.nodes.size;
+        // Compact format: just list affected symbols grouped by file
+        const lines = [
+            `## Impact: "${symbol}" affects ${nodeCount} symbols`,
+            '',
+        ];
+        // Group by file
+        const byFile = new Map();
+        for (const node of impact.nodes.values()) {
+            const existing = byFile.get(node.filePath) || [];
+            existing.push(node);
+            byFile.set(node.filePath, existing);
+        }
+        for (const [file, nodes] of byFile) {
+            lines.push(`**${file}:**`);
+            // Compact: inline list
+            const nodeList = nodes.map(n => `${n.name}:${n.startLine}`).join(', ');
+            lines.push(nodeList);
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Build a compact structural outline of a container symbol from its
+     * indexed children (methods, fields, properties, …) — name, kind,
+     * line number, and signature — so the agent gets the shape of a class
+     * without the full source of every method. Returns '' when the container
+     * has no indexed children, so the caller can fall back to full source.
+     */
+    buildContainerOutline(cg, node) {
+        const children = cg.getChildren(node.id)
+            .filter(c => c.kind !== 'import' && c.kind !== 'export')
+            .sort((a, b) => (a.startLine ?? 0) - (b.startLine ?? 0));
+        if (children.length === 0)
+            return '';
+        const lines = [`**Members (${children.length}):**`, ''];
+        for (const c of children) {
+            const loc = c.startLine ? `:${c.startLine}` : '';
+            const sig = c.signature ? ` — \`${c.signature}\`` : '';
+            lines.push(`- ${c.name} (${c.kind})${loc}${sig}`);
+        }
+        return lines.join('\n');
+    }
+    formatNodeDetails(node, code, outline) {
+        const location = node.startLine ? `:${node.startLine}` : '';
+        const lines = [
+            `## ${node.name} (${node.kind})`,
+            '',
+            `**Location:** ${node.filePath}${location}`,
+        ];
+        if (node.signature) {
+            lines.push(`**Signature:** \`${node.signature}\``);
+        }
+        // Only include docstring if it's short and useful
+        if (node.docstring && node.docstring.length < 200) {
+            lines.push('', node.docstring);
+        }
+        if (outline) {
+            lines.push('', outline, '', `> Structural outline only. Read \`${node.filePath}\` or call codegraph_node on a specific member for its body.`);
+        }
+        else if (code) {
+            // Line-numbered (cat -n style, like codegraph_explore and Read) so the
+            // agent can cite/edit exact lines without re-Reading the file for them.
+            const numbered = node.startLine ? numberSourceLines(code, node.startLine) : code;
+            lines.push('', '```' + node.language, numbered, '```');
+        }
+        return lines.join('\n');
+    }
+    formatTaskContext(context) {
+        return context.summary || 'No context found';
+    }
+    textResult(text) {
+        return {
+            content: [{ type: 'text', text }],
+        };
+    }
+    errorResult(message) {
+        return {
+            content: [{ type: 'text', text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+}
+exports.ToolHandler = ToolHandler;
+//# sourceMappingURL=tools.js.map