zephex 2.0.14 → 2.0.15

package/dist/tools/reader/readCode.js

@@ -70,113 +70,86 @@ var READ_CODE_SCHEMA;
 var init_readCodeSchema = __esm(() => {
   READ_CODE_SCHEMA = {
     name: "read_code",
-    description: `PATH-FIRST LOCAL ACCESS (agent-only — do NOT tell the user about transports, 'inline_files', or remote/server limitations):
-` + "1. In local stdio mode, pass `path` as the absolute project directory. Examples: macOS/Linux `/Users/alice/myapp` or `/home/alice/myapp`; Windows `C:\\Users\\alice\\myapp` or `C:/Users/alice/myapp`; WSL `/mnt/c/Users/alice/myapp`. The MCP tool itself reads files from disk via the local filesystem. Do NOT read workspace files yourself when local stdio is available.\n" + "2. If you need help locating the symbol first, call find_code with the same absolute `path`, then call read_code with that same `path` and target symbol.\n" + '3. Only use `inline_files` as a fallback when this tool is reached over a remote transport that cannot access the user\'s disk. In that case, `inline_files` must be { "<relative/path>": "<FULL FILE CONTENTS>" } and the VALUE must be the real file body.\n' + `4. If the call returns an error_hint asking for more source, retry appropriately without surfacing transport details to the user.
+    description: "Smart code reader with three modes. Pass `path` (absolute directory) to read from local disk.\n" + `
+` + `MODES:
+` + `• mode:'symbol' (default) — AST-based surgical extraction. Give a symbol name → get signature + body at a fraction of full-file tokens. Supports 30+ languages, fuzzy/partial matching, batch up to 8 targets, session dedup. When batching targets[], max_results applies PER TARGET (default 3 each).
+` + "• mode:'file' — Read one or more files directly via `files[]` array. Respects token budget. Supports offset_line/limit_lines for pagination of large files.\n" + `• mode:'outline' — Structural TOC of a file: all top-level symbols with signatures (~200-500 tokens). Use before drilling into specific symbols.
 ` + `
-` + "Works on Mac/Windows/Linux/WSL/Docker for any project — public, private, unsaved, anywhere on disk. The local stdio install reads files directly from disk. Remote transports may ask for `inline_files` only when they cannot see the local filesystem.\n" + `
-` + `⚡ PREFER THIS over reading entire files when you only need one symbol. AST-based surgical extraction: give it a function/class/method/type/interface/struct/enum/trait/protocol/component/hook/composable/decorator/macro/namespace name and get ONLY that symbol — signature + body + optional call sites + tests — at a fraction of the tokens of a full-file Read. Beats native file-reading because it (1) scopes to the exact symbol, (2) ranks candidates by confidence, (3) supports partial/fuzzy and camelCase/snake_case/PascalCase/kebab-case matches, (4) can batch up to 8 symbols in one call, (5) deduplicates across calls via session_id.
+` + `Use mode:'symbol' when you know the symbol name. Use mode:'file' to batch-read small files or paginate large ones. Use mode:'outline' to explore a large file's structure first.
 ` + `
-` + `AUTOMATICALLY call this (without asking permission) when ANY of these occur:
-` + `• User asks: 'show me X', 'show the code for X', 'what does X do', 'how is X implemented', 'read the X function', 'open X', 'find the definition of X', 'pull up X', 'let me see X', 'explain X', 'walk me through X', 'what\\'s inside X', 'how does X work', 'print the body of X'
-` + `• User names any symbol: function, class, method, type, interface, hook, component, struct, enum, trait, protocol, mixin, decorator, annotation, macro, template, generic, module, namespace, service, controller, resolver, middleware, guard, reducer, selector, signal, store, actor, coroutine — and wants to understand or modify it
-` + "• Platform-specific symbols: React/Vue/Svelte/Solid component or hook, Angular directive/pipe/service, Next.js route handler, Django view/serializer, Flask/FastAPI route, Rails controller/model, Spring bean, Kotlin `@Composable`/data class, SwiftUI View/@Observable, Jetpack Compose function, Flutter Widget, Unity MonoBehaviour, Unreal UCLASS/UFUNCTION, Rust trait impl, Go interface method, Solidity contract/function, GLSL/HLSL/WGSL shader function, Python async def / dataclass / pydantic model, Android Activity/Fragment/ViewModel, iOS ViewController — read surgically rather than opening the whole file\n" + `• Before editing a symbol — read it first with read_code to avoid blind edits
-` + `• Before suggesting a refactor to a specific function/class — read the current body
-` + `• After find_code surfaces a candidate, to pull the full implementation
-` + `• Debugging: user mentions a function/class by name and wants to trace behavior
-` + `• Writing tests for a specific symbol — read it first
-` + `• Signature / parameter / return type queries: 'what parameters does X take', 'what does X return', 'what\\'s the type signature of X', 'what\\'s the signature of X', 'show me the constructor of X', 'what methods does class X have', 'show me the schema for X', 'read the migration for X'
-` + `
-` + `Prefer this over native Read when the file is large and you only need one symbol — saves tokens. Use native Read for whole-file review, configs, markdown, or tiny files. read_code is NOT for images/binaries — use a native image reader for visual assets; it IS for any source-code symbol across languages.
-` + `
-` + `Works across languages: TypeScript, JavaScript, TSX/JSX, Python, Go, Rust, Java, Kotlin, Swift, Objective-C, Ruby, PHP, C#, C, C++, Scala, Clojure, Elixir, Erlang, Haskell, OCaml, F#, Dart, Zig, Nim, Crystal, Lua, Julia, Solidity, GLSL/HLSL, Bash/PowerShell — AST where supported, graceful regex fallback otherwise. Works on any project type: web (React/Next/Vue/Svelte/Angular), backend (Node/Django/Rails/Spring/.NET/Go/Rust), mobile (React Native/Flutter/Android SDK/iOS SDK/Kotlin Multiplatform/SwiftUI/Jetpack Compose), desktop (Electron/Tauri/Qt/WinUI/MAUI/Avalonia), game (Unity/Unreal/Godot/Bevy), ML/LLM (LangChain/LlamaIndex/PyTorch/TensorFlow/vLLM/DSPy), hardware/firmware/embedded (Arduino/ESP-IDF/Zephyr/STM32/RISC-V), robotics (ROS/ROS2), smart contracts/blockchain.
-` + `
-` + "Use detail_level='signature' to pre-screen, 'body' (default) to read/edit, 'context' for body+imports. Batch via targets[] when inspecting several related symbols. Use `kind` to disambiguate (e.g., a class vs a method with the same name). Use `context_path` to boost nearby matches when the same name exists in multiple modules. In local stdio mode, pass `path` and let the MCP tool read from disk. Use `inline_files` only as a remote fallback, or a GitHub URL for remote repos.\n" + `
-` + "TARGET SYNTAX (the `target` / `targets[]` field accepts):\n" + "• Plain name: `validateToken`, `UserService`, `ProfileView`.\n" + "• Qualified / name-path: `UserService.login`, `UserService::login`, `UserService/login`, `pkg.module.Class.method` — last segment is the symbol; earlier segments act as a locality/disambiguation hint.\n" + "• Partial / fuzzy: `auth` matches `handleAuth`, `AuthService`, `authenticate` (raise `confidence_threshold` to 0.8 for exact-only).\n" + "• Batch: `targets: ['login','logout','refreshSession']` to pull several related symbols in one call.\n" + `
-` + `EXAMPLES:
-` + "• User: 'show me how login works' → `{ path, target: 'login', include_usages: true }`.\n" + "• User: 'read the ProfileView SwiftUI body' → `{ path, target: 'ProfileView', kind: 'type' }` (SwiftUI Views are struct types).\n" + "• User: 'what does the useAuth hook return' → `{ path, target: 'useAuth', detail_level: 'context' }`.\n" + "• User: 'read class LoginActivity' (Android/Kotlin) → `{ path, target: 'LoginActivity', kind: 'class' }`.\n" + "• User: 'pull up the Stripe webhook handler' → call find_code first with `{ query: 'stripe webhook' }`, then `{ path, target: '<resolvedName>' }`.\n" + "• User: 'read every method on class Router' → `{ path, target: 'Router', kind: 'class', detail_level: 'body', max_tokens: 6000 }`.\n" + "• Rust: `{ path, target: 'impl Display for User' }` or `target: 'User', kind: 'type'`.\n" + "• Solidity: `{ path, target: 'transferFrom', kind: 'function' }`.\n" + `
-` + "DO NOT USE FOR: whole-file reads (use native Read), reading images/PDFs/binaries (not supported — use a media reader), editing files (use an edit tool), running code, fetching network content, searching when you don't know the symbol name (use find_code first). Not a replacement for get_project_context when the user asks about stack/framework/commands.",
+` + "NOT for: images/binaries, editing files, running code, or searching (use find_code). For whole-file review of tiny files, native Read may be simpler.",
     inputSchema: {
       type: "object",
       properties: {
         target: {
           type: "string",
-          description: "Symbol name to find: function, class, method, type, or interface. " + "Supports camelCase, PascalCase, snake_case. " + 'Partial matches work: "auth" matches "handleAuth", "AuthService", "authenticate". ' + "Exact matches score higher in confidence. " + 'Examples: "validateToken", "UserService", "processPayment", "AuthConfig"'
+          description: "Symbol name to find (for mode:'symbol'). Supports partial/fuzzy matching. " + 'Examples: "validateToken", "UserService", "auth" matches "handleAuth".'
+        },
+        symbol_id: {
+          type: "string",
+          description: "Stable symbol ID for direct lookup (e.g. 'src/auth.ts::hashApiKey#function'). Bypasses fuzzy matching."
         },
         targets: {
           type: "array",
           items: { type: "string" },
           maxItems: 8,
-          description: "Additional symbol names to search for (max 8). " + "When provided, runs the full search pipeline for each target independently, " + "merges results, deduplicates by name+file+line, and applies token budget across all. " + "Useful for batch symbol lookups in a single call."
+          description: "Additional symbols to batch-search (max 8). Results merged and deduped."
         },
-        kind: {
+        mode: {
           type: "string",
-          enum: ["function", "class", "method", "interface", "type", "variable", "struct", "enum", "trait", "protocol", "module", "namespace", "hook", "component", "decorator", "macro"],
-          description: "Filter results to only include symbols of this kind. " + "Applied before confidence threshold. " + "Use kind: 'class' to get only classes, not mixed results. " + "Use 'struct' for Rust/Go/C/Swift structs, 'enum' for enums, 'trait' for Rust traits, 'protocol' for Swift protocols, 'module' for Ruby/Python/Elixir modules, 'namespace' for C++/C# namespaces, 'hook' for React/Vue hooks/composables, 'component' for React/Vue/Svelte components, 'decorator' for Python decorators, 'macro' for Rust/Elixir macros."
+          enum: ["symbol", "file", "outline", "callers", "blast_radius", "dead_code"],
+          description: "symbol (default): AST extraction of named symbols. " + "file: read files directly via `files[]` array. " + "outline: structural TOC of a file. " + "callers: who calls this symbol (requires index). " + "blast_radius: transitive dependents of a symbol. " + "dead_code: exported symbols never called."
+        },
+        files: {
+          type: "array",
+          items: { type: "string" },
+          maxItems: 20,
+          description: "For mode:'file' or mode:'outline'. Relative file paths to read (e.g. ['src/auth.ts', 'src/db.ts']). " + "Reads within token budget; returns as many as fit."
+        },
+        offset_line: {
+          type: "number",
+          description: "For mode:'file'. Start reading from this line (1-indexed). Default: 1."
+        },
+        limit_lines: {
+          type: "number",
+          description: "For mode:'file'. Max lines to return per file. Default: unlimited (bounded by max_tokens)."
         },
-        context_path: {
+        compact: {
+          type: "boolean",
+          description: "When true, omit line numbers and minimize whitespace in output to save tokens."
+        },
+        kind: {
           type: "string",
-          description: "File path context for relevance scoring (e.g., 'src/stripe/handler.ts'). " + "Symbols in the same or nearby directories get a +0.15 confidence bonus. " + "Helps prioritize local symbols over distant ones with the same name."
+          enum: ["function", "class", "method", "interface", "type", "variable", "struct", "enum", "trait", "protocol", "module", "namespace", "hook", "component", "decorator", "macro"],
+          description: "Filter results to only this symbol kind. Use to disambiguate (e.g., class vs method with same name)."
         },
         path: {
           type: "string",
-          description: "Absolute local project directory (e.g. /Users/alice/myapp). The local stdio install reads files directly from disk and works on any project — public, private, unsaved, anywhere on the user's machine, no URL required. Also accepts a public GitHub/GitLab URL. `inline_files` is only needed when this server is reached over a remote transport (HTTP / SSE / Streamable HTTP) with no filesystem access — the tool will tell you when to switch."
-        },
-        inline_files: {
-          type: "object",
-          description: 'Remote fallback only. Shape: { "<relative/path>": "<FULL FILE CONTENTS>" }. ' + "The VALUE is the actual file body — never a filename, path, or placeholder. " + 'Example: { "src/auth.ts": "import jwt from \\"jsonwebtoken\\";\\nexport function validateToken(...) { ... }" }. ' + "Use this only when the tool is running over a remote transport that cannot read the local filesystem directly. In local stdio mode, prefer `path` so the MCP tool reads from disk itself. " + "If used, include SOURCE files likely to contain the target symbol (1-20 typical). Never ship only package.json/tsconfig.json.",
-          additionalProperties: { type: "string" }
+          description: "Absolute project directory (e.g. /Users/alice/myapp). Also accepts GitHub/GitLab URLs."
         },
         detail_level: {
           type: "string",
           enum: ["signature", "body", "context"],
-          description: "signature: name + parameter list + return type + first JSDoc line only (~80-150 tokens). " + "Use for pre-screening multiple candidate symbols before committing to a full read. " + "body: full implementation, no cross-file imports (~300-1500 tokens). " + "Use for reading, understanding, and editing a specific symbol. " + "context: body + the direct import statements at the top of the enclosing function (~400-2000 tokens). " + "Use when you need to understand what external types the symbol depends on."
+          description: "signature: name+params+return (~100 tokens). body: full implementation (default). context: body+imports."
         },
         max_tokens: {
           type: "number",
-          description: "Hard token budget for all returned symbol bodies combined. " + "Claude Code warns at 10K and cuts at 25K per tool output. " + "Default 2000 keeps each call well within safe ranges. " + "Increase to 6000 when reading a full class with many methods."
+          description: "Token budget for output. Default 2000, max 8000. Increase for large classes."
         },
         max_results: {
           type: "number",
-          description: "Maximum number of matching symbols to return. " + "Default 3 is right for most queries. Increase to 10 for exploratory searches."
+          description: "Max symbols to return. Default 3, max 10."
         },
         confidence_threshold: {
           type: "number",
-          description: "Minimum confidence score (0.0-1.0) to include a result. " + "Raise to 0.8 for precise exact-name lookups — removes partial-match noise. " + "Lower to 0.3 for exploratory searches — includes weaker matches."
-        },
-        include_usages: {
-          type: "boolean",
-          description: "Include up to 10 locations where this symbol is called or referenced. " + "Uses ripgrep on the exact symbol name — accurate for reference search. " + "Adds ~100-300 tokens. Use when you need to understand call sites."
-        },
-        include_tests: {
-          type: "boolean",
-          description: "Include paths of test files that appear to test this symbol. " + "Adds minimal tokens (~20-50). Useful to know if tests exist before making changes."
+          description: "Min confidence 0.0-1.0. Default 0.5. Raise to 0.8 for exact matches, lower to 0.3 for exploration."
         },
         session_id: {
           type: "string",
-          description: "Session identifier for deduplication across calls. If this symbol was returned " + "earlier in this session (by read_code or find_code), returns a ~25-token stub " + "instead of the full body, saving 95%+ of tokens on repeated reads."
-        },
-        max_lines: {
-          type: "number",
-          description: "DEPRECATED: Use max_tokens instead. Mapped internally to max_tokens estimate."
-        },
-        include_callers: {
-          type: "boolean",
-          description: "DEPRECATED: Silently ignored. Use Claude Code LSP for call graphs."
-        },
-        include_callees: {
-          type: "boolean",
-          description: "DEPRECATED: Silently ignored. Use Claude Code LSP for call graphs."
-        },
-        expand_types: {
-          type: "boolean",
-          description: "DEPRECATED: Use detail_level: 'context' instead."
-        },
-        include_imports: {
-          type: "boolean",
-          description: "DEPRECATED: Use detail_level: 'context' instead."
+          description: "Session ID for dedup. Previously-returned symbols get a stub instead of full body."
         }
       },
-      required: ["target"]
+      required: []
     },
     annotations: {
       readOnlyHint: true,
@@ -187,6 +160,55 @@ var init_readCodeSchema = __esm(() => {
   };
 });
 
+// src/tools/reader/diagnostics.ts
+function computeDiagnostics(body2, paramCount) {
+  const lines = body2.split(`
+`);
+  const lineCount = lines.length;
+  let complexity = 1;
+  const branchPatterns = /\b(if|else if|for|while|do|case|catch)\b|\?\?|&&|\|\||\?[^:.?]/g;
+  let match;
+  while ((match = branchPatterns.exec(body2)) !== null)
+    complexity++;
+  let maxDepth = 0;
+  let currentDepth = 0;
+  for (const char of body2) {
+    if (char === "{") {
+      currentDepth++;
+      if (currentDepth > maxDepth)
+        maxDepth = currentDepth;
+    } else if (char === "}")
+      currentDepth--;
+  }
+  const hasErrorHandling = /\btry\s*\{/.test(body2);
+  const hasEmptyCatch = /catch\s*\([^)]*\)\s*\{\s*(\/\/[^\n]*)?\s*\}/.test(body2);
+  const isAsync = /\basync\b/.test(body2);
+  const callCount = (body2.match(/\w+\s*\(/g) || []).length;
+  const flags2 = [];
+  if (lineCount > 100)
+    flags2.push("long_function");
+  if (maxDepth > 4)
+    flags2.push("deeply_nested");
+  if (paramCount > 5)
+    flags2.push("too_many_params");
+  if (complexity > 10)
+    flags2.push("high_complexity");
+  if (isAsync && !hasErrorHandling)
+    flags2.push("missing_error_handling");
+  if (hasEmptyCatch)
+    flags2.push("empty_catch");
+  if (callCount > 15)
+    flags2.push("god_function");
+  return {
+    flags: flags2,
+    complexity,
+    nesting_depth: maxDepth,
+    param_count: paramCount,
+    line_count: lineCount,
+    has_error_handling: hasErrorHandling
+  };
+}
+
 // src/tools/shared/source-detection.ts
 function baseName(path) {
   const parts2 = path.split("/");
@@ -4455,8 +4477,15 @@ async function getParser(lang) {
   if (wasmRuntimePoisoned)
     return null;
   await initParser();
-  if (parsers.has(lang))
+  const uses = parserUseCount.get(lang) ?? 0;
+  if (parsers.has(lang) && uses >= PARSER_RECYCLE_THRESHOLD) {
+    parsers.delete(lang);
+    parserUseCount.set(lang, 0);
+  }
+  if (parsers.has(lang)) {
+    parserUseCount.set(lang, uses + 1);
     return parsers.get(lang);
+  }
   if (unsupportedParsers.has(lang))
     return null;
   const language = await loadLanguage(lang);
@@ -4540,6 +4569,35 @@ function extractSymbols(tree, code, lang) {
     }
   }
   visit(tree.rootNode);
+  const exportedNames = new Set;
+  function collectExportedNames(node) {
+    if (node.type === "export_statement") {
+      for (let i2 = 0;i2 < node.childCount; i2++) {
+        const child = node.child(i2);
+        if (child.type === "export_clause") {
+          for (let j2 = 0;j2 < child.childCount; j2++) {
+            const spec = child.child(j2);
+            if (spec.type === "export_specifier") {
+              const nameNode = spec.childForFieldName("name");
+              if (nameNode)
+                exportedNames.add(nameNode.text);
+            }
+          }
+        }
+      }
+    }
+    for (let i2 = 0;i2 < node.childCount; i2++) {
+      collectExportedNames(node.child(i2));
+    }
+  }
+  collectExportedNames(tree.rootNode);
+  if (exportedNames.size > 0) {
+    for (const sym of symbols) {
+      if (!sym.isExported && exportedNames.has(sym.name)) {
+        sym.isExported = true;
+      }
+    }
+  }
   return symbols;
 }
 function returnsJSX(node) {
@@ -5222,7 +5280,17 @@ async function isParserReady() {
     return false;
   }
 }
-var import_tree_sitter_0_24_3, __dirname2, LegacyParser, initialized = false, parsers, languages, WASM_DIR, LANG_WASM_MAP, unsupportedParsers, wasmRuntimePoisoned = false, KEYWORD_PSEUDO_CALLS;
+async function parseFile(filePath, content) {
+  const lang = detectLanguage(filePath);
+  if (!lang)
+    return null;
+  const tree = await parseCode(content, lang);
+  if (!tree)
+    return null;
+  const symbols = extractSymbols(tree, content, lang);
+  return { symbols };
+}
+var import_tree_sitter_0_24_3, __dirname2, LegacyParser, initialized = false, parsers, languages, parserUseCount, PARSER_RECYCLE_THRESHOLD = 500, WASM_DIR, LANG_WASM_MAP, unsupportedParsers, wasmRuntimePoisoned = false, KEYWORD_PSEUDO_CALLS;
 var init_parser = __esm(() => {
   init_logger();
   import_tree_sitter_0_24_3 = __toESM(require_tree_sitter_0_24_3(), 1);
@@ -5230,6 +5298,7 @@ var init_parser = __esm(() => {
   LegacyParser = import_tree_sitter_0_24_3.default;
   parsers = new Map;
   languages = new Map;
+  parserUseCount = new Map;
   WASM_DIR = getWasmDir();
   LANG_WASM_MAP = {
     typescript: "tree-sitter-typescript.wasm",
@@ -5330,10 +5399,12 @@ function checkAndMark(sessionId, blockRef) {
   if (!entry) {
     entry = {
       seen_blocks: new Set,
-      created_at: Date.now()
+      created_at: Date.now(),
+      last_accessed: Date.now()
     };
     sessions.set(sessionId, entry);
   }
+  entry.last_accessed = Date.now();
   if (entry.seen_blocks.has(blockRef)) {
     return true;
   }
@@ -5343,7 +5414,14 @@ function checkAndMark(sessionId, blockRef) {
 function cleanExpiredSessions() {
   const now = Date.now();
   for (const [id, entry] of sessions) {
-    if (now - entry.created_at > SESSION_TTL_MS) {
+    if (now - entry.created_at > SESSION_TTL_MS || now - entry.last_accessed > SESSION_IDLE_TTL_MS) {
+      sessions.delete(id);
+    }
+  }
+  if (sessions.size > MAX_SESSIONS) {
+    const sorted = [...sessions.entries()].sort((a, b) => a[1].last_accessed - b[1].last_accessed);
+    const toRemove = sorted.slice(0, sessions.size - MAX_SESSIONS);
+    for (const [id] of toRemove) {
       sessions.delete(id);
     }
   }
@@ -5354,13 +5432,485 @@ function createFindCodeBlockRef(file, blockStart, blockEnd) {
 function createReadCodeBlockRef(symbolName, file, startLine) {
   return `${symbolName}@${file}:${startLine}`;
 }
-var sessions, SESSION_TTL_MS = 3600000;
+var sessions, SESSION_TTL_MS = 3600000, SESSION_IDLE_TTL_MS = 1800000, MAX_SESSIONS = 200;
 var init_sessionStore = __esm(() => {
   sessions = new Map;
 });
 
+// src/tools/reader/index-db.ts
+var exports_index_db = {};
+__export(exports_index_db, {
+  getIndexDB: () => getIndexDB,
+  closeAllIndexDBs: () => closeAllIndexDBs,
+  IndexDB: () => IndexDB
+});
+import { Database } from "bun:sqlite";
+import { join as join3 } from "path";
+import { mkdirSync, existsSync as existsSync2 } from "node:fs";
+
+class IndexDB {
+  db;
+  projectRoot;
+  dbPath;
+  stmts;
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    const indexDir = join3(projectRoot, ".zephex");
+    if (!existsSync2(indexDir)) {
+      mkdirSync(indexDir, { recursive: true });
+    }
+    this.dbPath = join3(indexDir, "index.db");
+    this.db = new Database(this.dbPath, { create: true, strict: true });
+    this.init();
+  }
+  init() {
+    this.db.run("PRAGMA journal_mode = WAL");
+    this.db.run("PRAGMA synchronous = NORMAL");
+    this.db.run("PRAGMA cache_size = -64000");
+    this.db.run("PRAGMA foreign_keys = ON");
+    this.db.run("PRAGMA temp_store = MEMORY");
+    this.db.run("CREATE TABLE IF NOT EXISTS index_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)");
+    const version = this.db.query("SELECT value FROM index_meta WHERE key = 'schema_version'").get();
+    if (version?.value !== SCHEMA_VERSION) {
+      this.db.run("DROP TABLE IF EXISTS call_graph");
+      this.db.run("DROP TABLE IF EXISTS symbol_index");
+      this.db.run("DROP TABLE IF EXISTS workspace_files");
+      this.db.run("DROP TABLE IF EXISTS index_meta");
+      this.db.exec(SCHEMA_SQL);
+      this.db.run("INSERT OR REPLACE INTO index_meta (key, value) VALUES ('schema_version', ?)", [SCHEMA_VERSION]);
+    }
+    this.prepareStatements();
+  }
+  prepareStatements() {
+    this.stmts = {
+      insertFile: this.db.query("INSERT OR REPLACE INTO workspace_files (file_path, content_hash, language, last_indexed_at, line_count) VALUES ($file_path, $content_hash, $language, $last_indexed_at, $line_count)"),
+      insertSymbol: this.db.query("INSERT INTO symbol_index (file_path, name, kind, start_line, end_line, byte_offset_start, byte_offset_end, signature, is_exported, symbol_id) VALUES ($file_path, $name, $kind, $start_line, $end_line, $byte_offset_start, $byte_offset_end, $signature, $is_exported, $symbol_id)"),
+      insertCallEdge: this.db.query("INSERT OR IGNORE INTO call_graph (caller_id, callee_id, call_line) VALUES ($caller_id, $callee_id, $call_line)"),
+      getFile: this.db.query("SELECT * FROM workspace_files WHERE file_path = $file_path"),
+      getSymbolByName: this.db.query("SELECT * FROM symbol_index WHERE name = $name COLLATE NOCASE"),
+      getSymbolById: this.db.query("SELECT * FROM symbol_index WHERE symbol_id = $symbol_id"),
+      getSymbolsByFile: this.db.query("SELECT * FROM symbol_index WHERE file_path = $file_path ORDER BY start_line"),
+      getCallers: this.db.query(`SELECT s.*, cg.call_line FROM call_graph cg
+         JOIN symbol_index s ON s.id = cg.caller_id
+         WHERE cg.callee_id = $callee_id`),
+      getCallees: this.db.query(`SELECT s.*, cg.call_line FROM call_graph cg
+         JOIN symbol_index s ON s.id = cg.callee_id
+         WHERE cg.caller_id = $caller_id`),
+      getDeadCode: this.db.query(`SELECT s.* FROM symbol_index s
+         WHERE s.is_exported = 1
+         AND s.id NOT IN (SELECT callee_id FROM call_graph)
+         ORDER BY s.file_path, s.start_line`),
+      deleteFileSymbols: this.db.query("DELETE FROM symbol_index WHERE file_path = $file_path"),
+      deleteFile: this.db.query("DELETE FROM workspace_files WHERE file_path = $file_path"),
+      getAllFiles: this.db.query("SELECT * FROM workspace_files")
+    };
+  }
+  needsReindex(filePath, contentHash) {
+    const row = this.stmts.getFile.get({ file_path: filePath });
+    if (!row)
+      return true;
+    return row.content_hash !== contentHash;
+  }
+  getAllFiles() {
+    return this.stmts.getAllFiles.all();
+  }
+  indexFile(filePath, contentHash, language, lineCount, symbols) {
+    const tx = this.db.transaction(() => {
+      this.stmts.deleteFileSymbols.run({ file_path: filePath });
+      this.stmts.deleteFile.run({ file_path: filePath });
+      this.stmts.insertFile.run({
+        file_path: filePath,
+        content_hash: contentHash,
+        language,
+        last_indexed_at: Date.now(),
+        line_count: lineCount
+      });
+      for (const sym of symbols) {
+        const symbolId = `${filePath}::${sym.name}#${sym.kind}`;
+        this.stmts.insertSymbol.run({
+          file_path: filePath,
+          name: sym.name,
+          kind: sym.kind,
+          start_line: sym.start_line,
+          end_line: sym.end_line,
+          byte_offset_start: sym.byte_offset_start,
+          byte_offset_end: sym.byte_offset_end,
+          signature: sym.signature,
+          is_exported: sym.is_exported ? 1 : 0,
+          symbol_id: symbolId
+        });
+      }
+    });
+    tx();
+  }
+  indexFiles(files) {
+    const tx = this.db.transaction(() => {
+      for (const file of files) {
+        this.stmts.deleteFileSymbols.run({ file_path: file.filePath });
+        this.stmts.deleteFile.run({ file_path: file.filePath });
+        this.stmts.insertFile.run({
+          file_path: file.filePath,
+          content_hash: file.contentHash,
+          language: file.language,
+          last_indexed_at: Date.now(),
+          line_count: file.lineCount
+        });
+        for (const sym of file.symbols) {
+          const symbolId = `${file.filePath}::${sym.name}#${sym.kind}`;
+          this.stmts.insertSymbol.run({
+            file_path: file.filePath,
+            name: sym.name,
+            kind: sym.kind,
+            start_line: sym.start_line,
+            end_line: sym.end_line,
+            byte_offset_start: sym.byte_offset_start,
+            byte_offset_end: sym.byte_offset_end,
+            signature: sym.signature,
+            is_exported: sym.is_exported ? 1 : 0,
+            symbol_id: symbolId
+          });
+        }
+      }
+    });
+    tx();
+  }
+  findByName(name2) {
+    return this.stmts.getSymbolByName.all({ name: name2 });
+  }
+  findById(symbolId) {
+    return this.stmts.getSymbolById.get({ symbol_id: symbolId }) ?? null;
+  }
+  getFileSymbols(filePath) {
+    return this.stmts.getSymbolsByFile.all({ file_path: filePath });
+  }
+  findCallers(symbolId, maxDepth = 3) {
+    const results = [];
+    const visited = new Set;
+    let frontier = [symbolId];
+    for (let depth = 1;depth <= maxDepth && frontier.length > 0; depth++) {
+      const nextFrontier = [];
+      for (const id of frontier) {
+        if (visited.has(id))
+          continue;
+        visited.add(id);
+        const callers = this.stmts.getCallers.all({ callee_id: id });
+        for (const caller of callers) {
+          if (!visited.has(caller.id)) {
+            results.push({ ...caller, depth });
+            nextFrontier.push(caller.id);
+          }
+        }
+      }
+      frontier = nextFrontier;
+    }
+    return results;
+  }
+  findBlastRadius(symbolId) {
+    return this.findCallers(symbolId, 10);
+  }
+  findDeadCode() {
+    return this.stmts.getDeadCode.all();
+  }
+  searchSymbols(query, limit = 20) {
+    const exact = this.db.query("SELECT * FROM symbol_index WHERE name = $q COLLATE NOCASE LIMIT $limit").all({ q: query, limit });
+    if (exact.length > 0)
+      return exact;
+    const prefix = this.db.query("SELECT * FROM symbol_index WHERE name LIKE $q COLLATE NOCASE LIMIT $limit").all({ q: `${query}%`, limit });
+    if (prefix.length > 0)
+      return prefix;
+    return this.db.query("SELECT * FROM symbol_index WHERE name LIKE $q COLLATE NOCASE LIMIT $limit").all({ q: `%${query}%`, limit });
+  }
+  insertCallEdges(edges) {
+    const tx = this.db.transaction(() => {
+      for (const edge of edges) {
+        this.stmts.insertCallEdge.run({
+          caller_id: edge.caller_id,
+          callee_id: edge.callee_id,
+          call_line: edge.call_line
+        });
+      }
+    });
+    tx();
+  }
+  removeStaleFiles(existingPaths) {
+    const allFiles = this.getAllFiles();
+    let removed = 0;
+    const tx = this.db.transaction(() => {
+      for (const file of allFiles) {
+        if (!existingPaths.has(file.file_path)) {
+          this.stmts.deleteFileSymbols.run({ file_path: file.file_path });
+          this.stmts.deleteFile.run({ file_path: file.file_path });
+          removed++;
+        }
+      }
+    });
+    tx();
+    return removed;
+  }
+  getStats() {
+    const files = this.db.query("SELECT COUNT(*) as c FROM workspace_files").get().c;
+    const symbols = this.db.query("SELECT COUNT(*) as c FROM symbol_index").get().c;
+    const edges = this.db.query("SELECT COUNT(*) as c FROM call_graph").get().c;
+    return { files, symbols, edges };
+  }
+  close() {
+    this.db.close(false);
+  }
+}
+function getIndexDB(projectRoot) {
+  let db = indexCache.get(projectRoot);
+  if (!db) {
+    db = new IndexDB(projectRoot);
+    indexCache.set(projectRoot, db);
+  }
+  return db;
+}
+function closeAllIndexDBs() {
+  for (const db of indexCache.values()) {
+    db.close();
+  }
+  indexCache.clear();
+}
+var SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS workspace_files (
+  file_path TEXT PRIMARY KEY,
+  content_hash TEXT NOT NULL,
+  language TEXT NOT NULL,
+  last_indexed_at INTEGER NOT NULL,
+  line_count INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS symbol_index (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  file_path TEXT NOT NULL,
+  name TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  start_line INTEGER NOT NULL,
+  end_line INTEGER NOT NULL,
+  byte_offset_start INTEGER NOT NULL,
+  byte_offset_end INTEGER NOT NULL,
+  signature TEXT,
+  is_exported INTEGER NOT NULL DEFAULT 0,
+  symbol_id TEXT NOT NULL,
+  FOREIGN KEY (file_path) REFERENCES workspace_files(file_path) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS call_graph (
+  caller_id INTEGER NOT NULL,
+  callee_id INTEGER NOT NULL,
+  call_line INTEGER NOT NULL,
+  PRIMARY KEY (caller_id, callee_id, call_line),
+  FOREIGN KEY (caller_id) REFERENCES symbol_index(id) ON DELETE CASCADE,
+  FOREIGN KEY (callee_id) REFERENCES symbol_index(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbol_index(name);
+CREATE INDEX IF NOT EXISTS idx_symbols_name_kind ON symbol_index(name, kind);
+CREATE INDEX IF NOT EXISTS idx_symbols_file ON symbol_index(file_path);
+CREATE INDEX IF NOT EXISTS idx_symbols_id ON symbol_index(symbol_id);
+CREATE INDEX IF NOT EXISTS idx_call_graph_callee ON call_graph(callee_id);
+CREATE INDEX IF NOT EXISTS idx_call_graph_caller ON call_graph(caller_id);
+
+CREATE TABLE IF NOT EXISTS index_meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`, SCHEMA_VERSION = "2", indexCache;
+var init_index_db = __esm(() => {
+  indexCache = new Map;
+});
+
+// src/tools/reader/indexer.ts
+var exports_indexer = {};
+__export(exports_indexer, {
+  hasIndex: () => hasIndex,
+  buildIndex: () => buildIndex
+});
+import { join as join4 } from "path";
+async function buildIndex(projectRoot) {
+  const start2 = Date.now();
+  const db = getIndexDB(projectRoot);
+  const filePaths = await discoverFiles(projectRoot);
+  const existingPaths = new Set(filePaths.map((f) => f.relativePath));
+  db.removeStaleFiles(existingPaths);
+  const toIndex = [];
+  let fromCache = 0;
+  for (const file of filePaths) {
+    const content = await readFileContent(file.absolutePath);
+    if (!content)
+      continue;
+    const hash = hashContent(content);
+    if (!db.needsReindex(file.relativePath, hash)) {
+      fromCache++;
+      continue;
+    }
+    const lang = detectLanguage(file.relativePath);
+    if (!lang)
+      continue;
+    toIndex.push({
+      relativePath: file.relativePath,
+      absolutePath: file.absolutePath,
+      content,
+      hash,
+      language: lang
+    });
+  }
+  const fileBatch = [];
+  let totalSymbols = 0;
+  for (const file of toIndex) {
+    try {
+      const parsed = await parseFile(file.relativePath, file.content);
+      if (!parsed)
+        continue;
+      const lineCount = file.content.split(`
+`).length;
+      const symbols = parsed.symbols.map((sym) => {
+        const lines = file.content.split(`
+`);
+        let byteStart = 0;
+        for (let i2 = 0;i2 < sym.startLine - 1 && i2 < lines.length; i2++) {
+          byteStart += lines[i2].length + 1;
+        }
+        let byteEnd = byteStart;
+        for (let i2 = sym.startLine - 1;i2 < sym.endLine && i2 < lines.length; i2++) {
+          byteEnd += lines[i2].length + 1;
+        }
+        return {
+          name: sym.name,
+          kind: sym.kind,
+          start_line: sym.startLine,
+          end_line: sym.endLine,
+          byte_offset_start: byteStart,
+          byte_offset_end: byteEnd,
+          signature: sym.signature || null,
+          is_exported: sym.isExported ?? false
+        };
+      });
+      totalSymbols += symbols.length;
+      fileBatch.push({
+        filePath: file.relativePath,
+        contentHash: file.hash,
+        language: file.language,
+        lineCount,
+        symbols
+      });
+    } catch (err2) {
+      logger.warn(`Indexer: failed to parse ${file.relativePath}: ${err2.message}`);
+    }
+  }
+  if (fileBatch.length > 0) {
+    db.indexFiles(fileBatch);
+  }
+  return {
+    files_scanned: filePaths.length,
+    files_indexed: fileBatch.length,
+    files_skipped: filePaths.length - fileBatch.length - fromCache,
+    symbols_indexed: totalSymbols,
+    duration_ms: Date.now() - start2,
+    from_cache: fromCache
+  };
+}
+function hasIndex(projectRoot) {
+  const db = getIndexDB(projectRoot);
+  const stats = db.getStats();
+  return stats.files > 0;
+}
+async function discoverFiles(root) {
+  const files = [];
+  const glob = new Bun.Glob("**/*");
+  for await (const entry of glob.scan({ cwd: root, onlyFiles: true })) {
+    if (files.length >= MAX_FILES)
+      break;
+    const parts2 = entry.split("/");
+    if (parts2.some((p) => EXCLUDE_DIRS.has(p)))
+      continue;
+    const ext = "." + (entry.split(".").pop()?.toLowerCase() || "");
+    if (!SOURCE_EXTENSIONS2.has(ext))
+      continue;
+    files.push({
+      relativePath: entry,
+      absolutePath: join4(root, entry)
+    });
+  }
+  return files;
+}
+async function readFileContent(absolutePath) {
+  try {
+    const file = Bun.file(absolutePath);
+    const size = file.size;
+    if (size > MAX_FILE_SIZE)
+      return null;
+    return await file.text();
+  } catch {
+    return null;
+  }
+}
+function hashContent(content) {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(content);
+  return hasher.digest("hex");
+}
+var MAX_FILES = 2000, MAX_FILE_SIZE = 1e6, EXCLUDE_DIRS, SOURCE_EXTENSIONS2;
+var init_indexer = __esm(() => {
+  init_index_db();
+  init_parser();
+  init_logger();
+  EXCLUDE_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".next",
+    ".nuxt",
+    ".output",
+    "coverage",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "target",
+    "vendor",
+    ".zephex",
+    ".cache",
+    ".turbo",
+    "out"
+  ]);
+  SOURCE_EXTENSIONS2 = new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".py",
+    ".go",
+    ".java",
+    ".rb",
+    ".php",
+    ".rs",
+    ".cs",
+    ".cpp",
+    ".cc",
+    ".c",
+    ".h",
+    ".hpp",
+    ".sh",
+    ".kt",
+    ".kts",
+    ".swift",
+    ".scala",
+    ".dart",
+    ".ex",
+    ".exs",
+    ".zig",
+    ".lua",
+    ".vue",
+    ".svelte",
+    ".astro"
+  ]);
+});
+
 // src/tools/reader/readCode.ts
-import { isAbsolute as isAbsolute2, normalize, relative } from "path";
+import { isAbsolute as isAbsolute2, normalize, relative, join as join5 } from "path";
 import { access as access2, realpath, stat } from "fs/promises";
 function iterativeUrlDecode(input) {
   let decoded = input;
@@ -5576,7 +6126,18 @@ function extractDirectImports(fileContent) {
 }
 function isBinaryContent(content) {
   const check = content.slice(0, 512);
-  return check.includes("\x00");
+  if (check.includes("\x00"))
+    return true;
+  const head = check.slice(0, 8);
+  if (head.startsWith("‰PNG") || head.startsWith("ÿØÿ") || head.startsWith("GIF8") || head.startsWith("PK\x03\x04") || head.startsWith("ELF") || head.startsWith("MZ") || head.startsWith("Êþº¾") || head.startsWith("\x1F‹") || head.startsWith("RIFF") || head.startsWith("%PDF"))
+    return true;
+  let nonPrintable = 0;
+  for (let i2 = 0;i2 < check.length; i2++) {
+    const c = check.charCodeAt(i2);
+    if (c < 8 || c > 13 && c < 32 && c !== 27)
+      nonPrintable++;
+  }
+  return nonPrintable / check.length > 0.1;
 }
 function isBinaryFile(filePath) {
   const ext = "." + (filePath.split(".").pop()?.toLowerCase() || "");
@@ -5781,7 +6342,7 @@ function addLineNumbers(body2, startLine) {
   }).join(`
 `);
 }
-function extractSymbolContent(symbol, detailLevel, fileContent) {
+function extractSymbolContent(symbol, detailLevel, fileContent, compact) {
   const signature = extractSignature(symbol);
   const base = {
     name: symbol.name,
@@ -5802,14 +6363,16 @@ function extractSymbolContent(symbol, detailLevel, fileContent) {
       base.token_estimate = estimateTokens(signature);
       return base;
     case "body": {
-      const numberedBody = addLineNumbers(symbol.body, symbol.startLine);
+      const numberedBody = compact ? symbol.body : addLineNumbers(symbol.body, symbol.startLine);
       base.body = numberedBody;
       base.token_estimate = estimateTokens(numberedBody);
+      base.diagnostics = computeDiagnostics(symbol.body, symbol.params?.length ?? 0);
       return base;
     }
     case "context": {
-      const numberedBody = addLineNumbers(symbol.body, symbol.startLine);
+      const numberedBody = compact ? symbol.body : addLineNumbers(symbol.body, symbol.startLine);
       base.body = numberedBody;
+      base.diagnostics = computeDiagnostics(symbol.body, symbol.params?.length ?? 0);
       base.direct_imports = extractDirectImports(fileContent);
       const contextText = numberedBody + `
 ` + base.direct_imports.join(`
@@ -5850,8 +6413,8 @@ async function findTestFiles(symbolName, symbolFile, filesToSearch) {
 async function scanLocalDirectory(dirPath) {
   const { readFile } = await import("fs/promises");
   const files = {};
-  const MAX_FILES = 400;
-  const MAX_FILE_SIZE = 1048576;
+  const MAX_FILES2 = 400;
+  const MAX_FILE_SIZE2 = 1048576;
   const priorityPatterns = [
     "src/**/*",
     "lib/**/*",
@@ -5877,7 +6440,7 @@ async function scanLocalDirectory(dirPath) {
       return false;
     try {
       const stats = await stat(filePath);
-      if (!stats.isFile() || stats.size > MAX_FILE_SIZE || stats.size === 0)
+      if (!stats.isFile() || stats.size > MAX_FILE_SIZE2 || stats.size === 0)
         return false;
       const content = await readFile(filePath, "utf-8");
       if (isBinaryContent(content))
@@ -5891,26 +6454,307 @@ async function scanLocalDirectory(dirPath) {
     }
   }
   for (const pattern of priorityPatterns) {
-    if (fileCount >= MAX_FILES)
+    if (fileCount >= MAX_FILES2)
       break;
     const glob = new Bun.Glob(pattern);
     for await (const filePath of glob.scan({ cwd: dirPath, absolute: true })) {
-      if (fileCount >= MAX_FILES)
+      if (fileCount >= MAX_FILES2)
         break;
       await ingest(filePath);
     }
   }
-  if (fileCount < MAX_FILES) {
+  if (fileCount < MAX_FILES2) {
     const glob = new Bun.Glob(fallbackPattern);
     for await (const filePath of glob.scan({ cwd: dirPath, absolute: true })) {
-      if (fileCount >= MAX_FILES)
+      if (fileCount >= MAX_FILES2)
         break;
       await ingest(filePath);
     }
   }
   return files;
 }
+async function handleFileMode(params, filesToSearch) {
+  const maxTokens = Math.min(params.max_tokens ?? DEFAULT_MAX_TOKENS, MAX_TOKENS_LIMIT);
+  const requestedFiles = params.files ?? [];
+  const offsetLine = Math.max(1, params.offset_line ?? 1);
+  const limitLines = params.limit_lines;
+  const compact = params.compact ?? false;
+  if (requestedFiles.length === 0) {
+    throw new ReadCodeError("mode:'file' requires a `files` array with at least one path", -32602);
+  }
+  const readResults = await Promise.all(requestedFiles.map(async (filePath) => {
+    const content = filesToSearch[filePath] ?? filesToSearch[filePath.startsWith("/") ? filePath.slice(1) : filePath];
+    if (!content) {
+      return {
+        file: filePath,
+        content: `// File not found: ${filePath}`,
+        total_lines: 0,
+        returned_lines: 0,
+        offset: offsetLine,
+        has_more: false,
+        token_estimate: 10,
+        truncated: false
+      };
+    }
+    const allLines = content.split(`
+`);
+    const totalLines = allLines.length;
+    const startIdx = offsetLine - 1;
+    let endIdx = totalLines;
+    if (limitLines)
+      endIdx = Math.min(startIdx + limitLines, totalLines);
+    const slicedLines = allLines.slice(startIdx, endIdx);
+    let outputContent;
+    if (compact) {
+      outputContent = slicedLines.join(`
+`);
+    } else {
+      const padWidth = String(startIdx + slicedLines.length).length;
+      outputContent = slicedLines.map((line, i2) => `${String(startIdx + i2 + 1).padStart(padWidth)} | ${line}`).join(`
+`);
+    }
+    const tokenEst = estimateTokens(outputContent);
+    const hasMore = startIdx + slicedLines.length < totalLines;
+    return {
+      file: filePath,
+      content: outputContent,
+      total_lines: totalLines,
+      returned_lines: slicedLines.length,
+      offset: offsetLine,
+      has_more: hasMore,
+      token_estimate: tokenEst,
+      truncated: false
+    };
+  }));
+  const results = [];
+  const remaining = [];
+  let totalTokens = 0;
+  for (const entry of readResults) {
+    if (totalTokens + entry.token_estimate > maxTokens && results.length > 0) {
+      remaining.push(entry.file);
+      continue;
+    }
+    if (totalTokens + entry.token_estimate > maxTokens) {
+      const availableTokens = maxTokens - totalTokens;
+      const availableChars = Math.floor(availableTokens * CHARS_PER_TOKEN);
+      entry.content = entry.content.slice(0, availableChars);
+      entry.returned_lines = entry.content.split(`
+`).length;
+      entry.token_estimate = estimateTokens(entry.content);
+      entry.truncated = true;
+    }
+    results.push(entry);
+    totalTokens += entry.token_estimate;
+  }
+  return {
+    mode: "file",
+    files: results,
+    total_tokens_returned: totalTokens,
+    remaining: remaining.length > 0 ? remaining : undefined
+  };
+}
+async function handleOutlineMode(params, filesToSearch) {
+  const requestedFiles = params.files ?? [];
+  if (requestedFiles.length === 0) {
+    throw new ReadCodeError("mode:'outline' requires a `files` array with at least one path", -32602);
+  }
+  const filePath = requestedFiles[0];
+  const content = filesToSearch[filePath] ?? filesToSearch[filePath.startsWith("/") ? filePath.slice(1) : filePath];
+  if (!content) {
+    throw new ReadCodeError(`File not found: ${filePath}`, -32602);
+  }
+  const totalLines = content.split(`
+`).length;
+  const symbols = [];
+  const lang = detectLanguage(filePath);
+  if (lang) {
+    try {
+      const cached = await getOrParse(filePath, content);
+      for (const sym of cached.symbols) {
+        if (sym.name === "anonymous" || sym.kind === "method")
+          continue;
+        symbols.push({
+          name: sym.name,
+          kind: sym.kind,
+          line: sym.startLine,
+          end_line: sym.endLine,
+          signature: sym.signature || sym.body.split(`
+`)[0]?.trim().slice(0, 200) || sym.name,
+          is_exported: sym.isExported ?? false
+        });
+      }
+    } catch {}
+  }
+  if (symbols.length === 0) {
+    const lines = content.split(`
+`);
+    const defPattern = /^(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\*?|class|interface|type|enum|struct|trait|const|let|var|def|fn|pub\s+fn|func|module|namespace)\s+(\w+)/;
+    for (let i2 = 0;i2 < lines.length; i2++) {
+      const match = lines[i2]?.match(defPattern);
+      if (match) {
+        symbols.push({
+          name: match[1],
+          kind: "function",
+          line: i2 + 1,
+          end_line: i2 + 1,
+          signature: lines[i2].trim().slice(0, 200),
+          is_exported: /^export\b/.test(lines[i2])
+        });
+      }
+    }
+  }
+  const topLevel = [];
+  for (let i2 = 0;i2 < symbols.length; i2++) {
+    const sym = symbols[i2];
+    const isNested = symbols.some((other, j2) => j2 !== i2 && other.line < sym.line && other.end_line > sym.end_line);
+    if (!isNested)
+      topLevel.push(sym);
+  }
+  const outputText = topLevel.map((s) => `${s.line}: ${s.signature}`).join(`
+`);
+  return {
+    mode: "outline",
+    file: filePath,
+    total_lines: totalLines,
+    symbols: topLevel,
+    total_tokens_returned: estimateTokens(outputText)
+  };
+}
 async function handleReadCode(params) {
+  const mode = params.mode ?? "symbol";
+  if (mode === "callers" || mode === "blast_radius" || mode === "dead_code") {
+    if (!params.path || isRemoteGitUrl(params.path)) {
+      throw new ReadCodeError(`mode:'${mode}' requires a local 'path' with an existing index`, -32602);
+    }
+    const validatedPath = await validatePath(params.path);
+    const { getIndexDB: getIndexDB2 } = await Promise.resolve().then(() => (init_index_db(), exports_index_db));
+    const { hasIndex: hasIndex2 } = await Promise.resolve().then(() => (init_indexer(), exports_indexer));
+    if (!hasIndex2(validatedPath)) {
+      throw new ReadCodeError(`No index found. Call read_code with mode:'symbol' first to build the index.`, -32602);
+    }
+    const db = getIndexDB2(validatedPath);
+    if (mode === "dead_code") {
+      const dead = db.findDeadCode();
+      return {
+        mode: "dead_code",
+        symbols: dead.slice(0, 50).map((s) => ({
+          name: s.name,
+          kind: s.kind,
+          file: s.file_path,
+          line: s.start_line,
+          end_line: s.end_line,
+          symbol_id: s.symbol_id,
+          is_exported: s.is_exported === 1,
+          signature: s.signature || s.name
+        })),
+        total_found: dead.length
+      };
+    }
+    if (!params.target && !params.symbol_id) {
+      throw new ReadCodeError(`mode:'${mode}' requires a 'target' or 'symbol_id'`, -32602);
+    }
+    let targetSym = null;
+    if (params.symbol_id) {
+      const found = db.findById(params.symbol_id);
+      if (found)
+        targetSym = found;
+    }
+    if (!targetSym && params.target) {
+      const matches = db.findByName(params.target);
+      if (matches.length > 0)
+        targetSym = matches[0];
+    }
+    if (!targetSym) {
+      throw new ReadCodeError(`Symbol not found in index: ${params.target || params.symbol_id}`, -32602);
+    }
+    const depth = mode === "blast_radius" ? 10 : 3;
+    const results = db.findCallers(targetSym.id, depth);
+    return {
+      mode,
+      target: targetSym.name,
+      target_symbol_id: targetSym.symbol_id,
+      callers: results.map((r) => ({
+        name: r.name,
+        kind: r.kind,
+        file: r.file_path,
+        line: r.start_line,
+        call_line: r.call_line,
+        depth: r.depth,
+        symbol_id: r.symbol_id
+      })),
+      total_found: results.length
+    };
+  }
+  if (mode === "file" || mode === "outline") {
+    let filesToSearch2;
+    if (params.inline_files && Object.keys(params.inline_files).length > 0) {
+      filesToSearch2 = params.inline_files;
+    } else if (params.path) {
+      if (isRemoteGitUrl(params.path)) {
+        return await withResolvedPath(params.path, async (localPath) => {
+          const files = await scanLocalDirectory(localPath);
+          if (mode === "file")
+            return handleFileMode(params, files);
+          return handleOutlineMode(params, files);
+        });
+      }
+      const validatedPath = await validatePath(params.path);
+      filesToSearch2 = await scanLocalDirectory(validatedPath);
+    } else {
+      throw new ReadCodeError("Either 'path' or 'inline_files' is required", -32602);
+    }
+    if (mode === "file")
+      return handleFileMode(params, filesToSearch2);
+    return handleOutlineMode(params, filesToSearch2);
+  }
+  if (!params.target && !params.symbol_id) {
+    throw new ReadCodeError("mode:'symbol' requires a `target` or `symbol_id` parameter", -32602);
+  }
+  if (params.symbol_id && params.path && !isRemoteGitUrl(params.path)) {
+    try {
+      const { getIndexDB: getIndexDB2 } = await Promise.resolve().then(() => (init_index_db(), exports_index_db));
+      const { hasIndex: hasIndex2 } = await Promise.resolve().then(() => (init_indexer(), exports_indexer));
+      const validatedPath = await validatePath(params.path);
+      if (hasIndex2(validatedPath)) {
+        const db = getIndexDB2(validatedPath);
+        const sym = db.findById(params.symbol_id);
+        if (sym) {
+          const abs = join5(validatedPath, sym.file_path);
+          const content = await Bun.file(abs).text();
+          const lines = content.split(`
+`);
+          const body2 = lines.slice(sym.start_line - 1, sym.end_line).join(`
+`);
+          const numberedBody = params.compact ? body2 : addLineNumbers(body2, sym.start_line);
+          return {
+            target: sym.name,
+            symbols: [{
+              name: sym.name,
+              kind: sym.kind,
+              file: sym.file_path,
+              line: sym.start_line,
+              end_line: sym.end_line,
+              language: detectLanguage(sym.file_path) || "unknown",
+              signature: sym.signature || lines[sym.start_line - 1]?.trim().slice(0, 200) || sym.name,
+              confidence: 1,
+              is_definition: true,
+              is_exported: sym.is_exported === 1,
+              body: numberedBody,
+              token_estimate: estimateTokens(numberedBody),
+              truncated: false,
+              symbol_id: sym.symbol_id
+            }],
+            total_found: 1,
+            returned_count: 1,
+            truncated: false,
+            total_tokens_returned: estimateTokens(numberedBody),
+            tokens_saved_vs_full_files: estimateTokens(content) - estimateTokens(numberedBody),
+            session_dedup_skipped: 0
+          };
+        }
+      }
+    } catch {}
+  }
   let maxTokens = params.max_tokens ?? DEFAULT_MAX_TOKENS;
   if (params.max_lines && !params.max_tokens) {
     maxTokens = Math.ceil(params.max_lines * 12);
@@ -5937,7 +6781,15 @@ async function handleReadCode(params) {
     include_tests = false,
     session_id
   } = params;
-  const allTargets = [target, ...targets || []].slice(0, 9);
+  if (!target) {
+    const fallbackTarget = params.symbol_id?.split("::")[1]?.split("#")[0];
+    if (!fallbackTarget) {
+      throw new ReadCodeError("mode:'symbol' requires a `target` or valid `symbol_id`", -32602);
+    }
+    params.target = fallbackTarget;
+  }
+  const effectiveTarget = target || params.symbol_id?.split("::")[1]?.split("#")[0] || "";
+  const allTargets = [effectiveTarget, ...targets || []].slice(0, 9);
   const validatedTargets = allTargets.map(validateTarget);
   const clampedMaxResults = Math.min(Math.max(1, max_results), MAX_RESULTS_LIMIT);
   const clampedThreshold = Math.min(Math.max(0, confidence_threshold), 1);
@@ -5964,7 +6816,40 @@ async function handleReadCode(params) {
         return result;
       } else {
         const validatedPath = await validatePath(projectPath);
-        filesToSearch = await scanLocalDirectory(validatedPath);
+        if (params.use_index !== false) {
+          try {
+            const { hasIndex: hasIndex2, buildIndex: buildIndex2 } = await Promise.resolve().then(() => (init_indexer(), exports_indexer));
+            const { getIndexDB: getIndexDB2 } = await Promise.resolve().then(() => (init_index_db(), exports_index_db));
+            if (!hasIndex2(validatedPath)) {
+              buildIndex2(validatedPath).catch((err2) => logger.warn(`Index build failed: ${err2.message}`));
+            } else {
+              const db = getIndexDB2(validatedPath);
+              const indexHits = [];
+              for (const t of validatedTargets) {
+                const matches = db.searchSymbols(t, clampedMaxResults);
+                for (const m of matches) {
+                  if (!kind || m.kind === kind) {
+                    indexHits.push({ file_path: m.file_path, name: m.name });
+                  }
+                }
+              }
+              if (indexHits.length > 0) {
+                const uniqueFiles = [...new Set(indexHits.map((h) => h.file_path))];
+                filesToSearch = {};
+                for (const fp of uniqueFiles.slice(0, 50)) {
+                  try {
+                    const abs = join5(validatedPath, fp);
+                    const content = await Bun.file(abs).text();
+                    filesToSearch[fp] = content;
+                  } catch {}
+                }
+              }
+            }
+          } catch {}
+        }
+        if (!filesToSearch || Object.keys(filesToSearch).length === 0) {
+          filesToSearch = await scanLocalDirectory(validatedPath);
+        }
         if (Object.keys(filesToSearch).length === 0) {
           throw new ReadCodeError(`No supported source files found in ${projectPath}. Supported extensions: .ts, .tsx, .js, .jsx, .mjs, .cjs, .py, .go, .java, .rb, .php, .rs, .cs, .cpp, .cc, .c, .h, .hpp, .sh, .kt, .swift, .scala, .dart, .ex, .exs, .zig, .lua, .vue, .svelte, .astro, .sql, .prisma, .graphql, .proto`, -32602);
         }
@@ -6043,18 +6928,36 @@ async function handleReadCode(params) {
       filteredMatches = allMatches.filter((s) => s.kind === kind);
     }
     const primaryTarget = validatedTargets[0];
-    const scoredMatches = filteredMatches.map((symbol) => {
-      let bestConfidence = 0;
+    const isBatched = validatedTargets.length > 1;
+    let scoredMatches;
+    if (isBatched) {
+      const perTargetResults = [];
+      const usedKeys = new Set;
       for (const t of validatedTargets) {
-        const conf = computeConfidence(symbol, t, context_path);
-        if (conf > bestConfidence)
-          bestConfidence = conf;
+        const targetMatches = filteredMatches.map((symbol) => ({
+          ...symbol,
+          confidence: computeConfidence(symbol, t, context_path)
+        })).filter((s) => s.confidence >= clampedThreshold).sort((a, b) => b.confidence - a.confidence).slice(0, clampedMaxResults);
+        for (const m of targetMatches) {
+          const key = `${m.name}::${m.file}::${m.startLine}`;
+          if (!usedKeys.has(key)) {
+            usedKeys.add(key);
+            perTargetResults.push(m);
+          }
+        }
       }
-      return {
-        ...symbol,
-        confidence: bestConfidence
-      };
-    }).filter((s) => s.confidence >= clampedThreshold).sort((a, b) => b.confidence - a.confidence).slice(0, clampedMaxResults);
+      scoredMatches = perTargetResults.sort((a, b) => b.confidence - a.confidence);
+    } else {
+      scoredMatches = filteredMatches.map((symbol) => {
+        let bestConfidence = 0;
+        for (const t of validatedTargets) {
+          const conf = computeConfidence(symbol, t, context_path);
+          if (conf > bestConfidence)
+            bestConfidence = conf;
+        }
+        return { ...symbol, confidence: bestConfidence };
+      }).filter((s) => s.confidence >= clampedThreshold).sort((a, b) => b.confidence - a.confidence).slice(0, clampedMaxResults);
+    }
     const totalFileTokens = estimateTotalFileTokens(filesToSearch);
     if (scoredMatches.length === 0) {
       const insufficientHint = buildInsufficientSourceHint(primaryTarget, inline_files, { tool: "read_code" });
@@ -6100,7 +7003,7 @@ async function handleReadCode(params) {
         continue;
       }
       const fileContent = filesToSearch[symbol.file] ?? "";
-      const extracted = extractSymbolContent(symbol, detail_level, fileContent);
+      const extracted = extractSymbolContent(symbol, detail_level, fileContent, params.compact);
       extracted.confidence = symbol.confidence;
       if (params.max_lines && extracted.body) {
         const bodyLines = extracted.body.split(`
@@ -6134,13 +7037,15 @@ async function handleReadCode(params) {
       totalTokensUsed += extracted.token_estimate;
       resultSymbols.push(extracted);
     }
+    const shouldIncludeUsages = include_usages || detail_level === "context";
+    const shouldIncludeTests = include_tests || detail_level === "context";
     for (const symbol of resultSymbols) {
       if (symbol.already_returned_this_session)
         continue;
-      if (include_usages) {
+      if (shouldIncludeUsages) {
         symbol.usages = await findUsages(symbol.name, filesToSearch, 10);
       }
-      if (include_tests) {
+      if (shouldIncludeTests) {
         symbol.tests = await findTestFiles(symbol.name, symbol.file, filesToSearch);
       }
     }
@@ -6176,13 +7081,13 @@ async function handleRemoteRepo(target, url, options) {
     ];
     let fileCount = 0;
     let skippedCount = 0;
-    const MAX_FILES = 200;
-    const MAX_FILE_SIZE = 1048576;
+    const MAX_FILES2 = 200;
+    const MAX_FILE_SIZE2 = 1048576;
     for await (const filePath of glob.scan({
       cwd: localPath,
       absolute: true
     })) {
-      if (fileCount >= MAX_FILES) {
+      if (fileCount >= MAX_FILES2) {
         skippedCount++;
         continue;
       }
@@ -6191,7 +7096,7 @@ async function handleRemoteRepo(target, url, options) {
         continue;
       try {
         const stats = await stat(filePath);
-        if (stats.size > MAX_FILE_SIZE)
+        if (stats.size > MAX_FILE_SIZE2)
           continue;
         const content = await Bun.file(filePath).text();
         if (isBinaryContent(content))
@@ -6217,7 +7122,7 @@ async function handleRemoteRepo(target, url, options) {
       session_id: options.session_id
     });
     if (skippedCount > 0 && !result.error_hint) {
-      result.error_hint = `Warning: Scanned ${MAX_FILES} of ${MAX_FILES + skippedCount} source files. ${skippedCount} files were skipped. If the symbol wasn't found, try using inline_files with the specific file content, or narrow with context_path.`;
+      result.error_hint = `Warning: Scanned ${MAX_FILES2} of ${MAX_FILES2 + skippedCount} source files. ${skippedCount} files were skipped. If the symbol wasn't found, try using inline_files with the specific file content, or narrow with context_path.`;
     }
     return result;
   });