token-pilot 0.15.0 → 0.16.1

package/dist/core/session-analytics.js

@@ -1,4 +1,6 @@
 import { formatDuration } from './format-duration.js';
+import { ALL_INTENTS } from './intent-classifier.js';
+import { loadDeniedReads, clearDeniedReads } from './hook-tracker.js';
 /**
  * Tracks token savings and tool usage across a session.
  * When context-mode is detected, includes unified reporting.
@@ -7,6 +9,10 @@ export class SessionAnalytics {
     calls = [];
     sessionStart = Date.now();
     contextModeStatus = { detected: false, source: 'none', toolPrefix: '' };
+    projectRoot;
+    setProjectRoot(root) {
+        this.projectRoot = root;
+    }
     setContextModeStatus(status) {
         this.contextModeStatus = status;
     }
@@ -14,53 +20,50 @@ export class SessionAnalytics {
         this.calls.push(call);
     }
     /**
-     * Generate a compact session report (~5 lines).
+     * Generate session report. Compact by default (~5 lines), verbose=true for full breakdown.
      */
-    report() {
+    report(verbose = false) {
         const duration = formatDuration(Date.now() - this.sessionStart);
         const totalReturned = this.calls.reduce((s, c) => s + c.tokensReturned, 0);
         const totalWouldBe = this.calls.reduce((s, c) => s + c.tokensWouldBe, 0);
         const saved = totalWouldBe > 0 ? Math.round((1 - totalReturned / totalWouldBe) * 100) : 0;
+        // --- Shared data ---
+        const byTool = new Map();
+        for (const c of this.calls) {
+            const e = byTool.get(c.tool) ?? { count: 0, tokens: 0, saved: 0, wouldBe: 0 };
+            e.count++;
+            e.tokens += c.tokensReturned;
+            e.saved += Math.max(0, c.tokensWouldBe - c.tokensReturned);
+            e.wouldBe += c.tokensWouldBe;
+            byTool.set(c.tool, e);
+        }
+        const sortedTools = Array.from(byTool.entries()).sort((a, b) => b[1].saved - a[1].saved);
+        const byFile = new Map();
+        for (const c of this.calls) {
+            if (c.path) {
+                byFile.set(c.path, (byFile.get(c.path) ?? 0) + Math.max(0, c.tokensWouldBe - c.tokensReturned));
+            }
+        }
+        const cacheHits = this.calls.filter(c => c.sessionCacheHit);
+        // --- Compact report ---
+        const tokensSaved = totalWouldBe - totalReturned;
         const lines = [
             `SESSION ANALYTICS (${duration})`,
-            `Calls: ${this.calls.length}  ·  Tokens returned: ~${totalReturned}  ·  Saved: ~${totalWouldBe - totalReturned} (${saved}%)`,
+            `Calls: ${this.calls.length}  ·  Tokens returned: ~${totalReturned}  ·  Saved: ~${tokensSaved} (${saved}%)`,
         ];
-        // By tool — top 5 by savings, all on one line
         if (this.calls.length > 0) {
-            const byTool = new Map();
-            for (const c of this.calls) {
-                const e = byTool.get(c.tool) ?? { count: 0, tokens: 0, wouldBe: 0 };
-                e.count++;
-                e.tokens += c.tokensReturned;
-                e.wouldBe += c.tokensWouldBe;
-                byTool.set(c.tool, e);
-            }
-            const sorted = Array.from(byTool.entries())
-                .sort((a, b) => (b[1].wouldBe - b[1].tokens) - (a[1].wouldBe - a[1].tokens))
-                .slice(0, 5);
-            const toolParts = sorted.map(([tool, s]) => {
+            const toolParts = sortedTools.slice(0, 5).map(([tool, s]) => {
                 const pct = s.wouldBe > 0 ? Math.round((1 - s.tokens / s.wouldBe) * 100) : 0;
                 return `${tool} ${s.count}× (${pct}%)`;
             });
             lines.push(`Tools: ${toolParts.join('  ·  ')}`);
         }
-        // Top files by savings (top 3)
-        const byFile = new Map();
-        for (const c of this.calls) {
-            if (c.path) {
-                byFile.set(c.path, (byFile.get(c.path) ?? 0) + Math.max(0, c.tokensWouldBe - c.tokensReturned));
-            }
-        }
-        const topFiles = Array.from(byFile.entries())
-            .sort((a, b) => b[1] - a[1])
-            .slice(0, 3);
+        const topFiles = Array.from(byFile.entries()).sort((a, b) => b[1] - a[1]).slice(0, 3);
         if (topFiles.length > 0) {
             const fileParts = topFiles.map(([f, s]) => `${f} ~${s}`);
             lines.push(`Top files: ${fileParts.join('  ·  ')}`);
         }
-        // Cache hits + context-mode on one line
         const extras = [];
-        const cacheHits = this.calls.filter(c => c.sessionCacheHit);
         if (cacheHits.length > 0) {
             const hitRate = Math.round(cacheHits.length / this.calls.length * 100);
             extras.push(`Cache: ${cacheHits.length}/${this.calls.length} hits (${hitRate}%)`);
@@ -71,11 +74,144 @@ export class SessionAnalytics {
         if (extras.length > 0) {
             lines.push(extras.join('  ·  '));
         }
+        // Hook interception savings
+        const deniedReads = loadDeniedReads(this.projectRoot);
+        const sessionDenied = deniedReads.filter(d => d.timestamp >= this.sessionStart);
+        if (sessionDenied.length > 0) {
+            const hookTokensSaved = sessionDenied.reduce((s, d) => s + d.estimatedTokens, 0);
+            lines.push(`Hook: intercepted ${sessionDenied.length} unbounded Read${sessionDenied.length === 1 ? '' : 's'}, saved ~${hookTokensSaved} tokens`);
+        }
+        if (!verbose)
+            return lines.join('\n');
+        // --- Verbose additions ---
+        lines.push('');
+        lines.push('--- DETAILED BREAKDOWN ---');
+        // Full per-tool table
+        if (sortedTools.length > 0) {
+            lines.push('');
+            lines.push('By tool:');
+            for (const [tool, stats] of sortedTools) {
+                const reduction = stats.wouldBe > 0 ? Math.round((1 - stats.tokens / stats.wouldBe) * 100) : 0;
+                lines.push(`  ${tool}: ${stats.count} calls, ~${stats.tokens} tokens returned, ~${stats.saved} saved (${reduction}%)`);
+            }
+        }
+        // Top 5 files
+        const allTopFiles = Array.from(byFile.entries()).sort((a, b) => b[1] - a[1]).slice(0, 5);
+        if (allTopFiles.length > 0) {
+            lines.push('');
+            lines.push('Top files by savings:');
+            for (const [file, fileSaved] of allTopFiles) {
+                lines.push(`  ${file}: ~${fileSaved} tokens saved`);
+            }
+        }
+        // Low-value tools
+        const lowValue = sortedTools
+            .map(([tool, stats]) => ({
+            tool,
+            reduction: stats.wouldBe > 0 ? Math.round((1 - stats.tokens / stats.wouldBe) * 100) : 0,
+            count: stats.count,
+        }))
+            .filter(t => t.reduction < 20);
+        if (lowValue.length > 0) {
+            lines.push('');
+            lines.push('Needs improvement:');
+            for (const t of lowValue.slice(0, 5)) {
+                lines.push(`  ${t.tool}: only ${t.reduction}% reduction across ${t.count} call${t.count === 1 ? '' : 's'}`);
+            }
+        }
+        // Savings by category
+        const byCategory = { compression: 0, cache: 0, dedup: 0, none: 0 };
+        for (const c of this.calls) {
+            byCategory[c.savingsCategory ?? 'none'] += Math.max(0, c.tokensWouldBe - c.tokensReturned);
+        }
+        if (totalWouldBe > totalReturned) {
+            lines.push('');
+            lines.push('Savings breakdown:');
+            if (byCategory.compression > 0)
+                lines.push(`  Compression (AST/structured): ~${byCategory.compression} tokens`);
+            if (byCategory.cache > 0)
+                lines.push(`  Cache hits (session cache): ~${byCategory.cache} tokens`);
+            if (byCategory.dedup > 0)
+                lines.push(`  Dedup (already in context): ~${byCategory.dedup} tokens`);
+        }
+        // Session cache detail
+        if (cacheHits.length > 0) {
+            const cacheTokensSaved = cacheHits.reduce((s, c) => s + Math.max(0, c.tokensWouldBe - c.tokensReturned), 0);
+            lines.push('');
+            lines.push(`Session cache: ${cacheHits.length} hits / ${this.calls.length} calls (${Math.round(cacheHits.length / this.calls.length * 100)}% hit rate, ~${cacheTokensSaved} tokens saved)`);
+        }
+        // Delegation
+        const delegated = this.calls.filter(c => c.delegatedToContextMode);
+        if (delegated.length > 0) {
+            lines.push(`Delegated to context-mode: ${delegated.length} calls`);
+        }
+        // Per-intent breakdown
+        const callsWithIntent = this.calls.filter(c => c.intent);
+        if (callsWithIntent.length > 0) {
+            const byIntent = new Map();
+            for (const c of callsWithIntent) {
+                const intent = c.intent;
+                const e = byIntent.get(intent) ?? { count: 0, saved: 0 };
+                e.count++;
+                e.saved += Math.max(0, c.tokensWouldBe - c.tokensReturned);
+                byIntent.set(intent, e);
+            }
+            lines.push('');
+            lines.push('Per-intent breakdown:');
+            for (const intent of ALL_INTENTS) {
+                const stats = byIntent.get(intent);
+                if (stats) {
+                    lines.push(`  ${intent}: ${stats.count} call${stats.count === 1 ? '' : 's'}, ~${stats.saved} tokens saved`);
+                }
+            }
+        }
+        // Decision insights
+        const tracedCalls = this.calls.filter(c => c.decisionTrace);
+        if (tracedCalls.length > 0) {
+            const alreadyInContext = tracedCalls.filter(c => c.decisionTrace.alreadyInContext).length;
+            const totalEstimated = tracedCalls.reduce((s, c) => s + c.decisionTrace.estimatedCost, 0);
+            const totalActual = tracedCalls.reduce((s, c) => s + c.decisionTrace.actualCost, 0);
+            const avgReduction = totalEstimated > 0 ? Math.round((1 - totalActual / totalEstimated) * 100) : 0;
+            const missedSavings = tracedCalls.filter(c => c.decisionTrace.cheaperAlternative).length;
+            lines.push('');
+            lines.push('Decision insights:');
+            lines.push(`  Files already in context: ${alreadyInContext} of ${tracedCalls.length} calls (${Math.round(alreadyInContext / tracedCalls.length * 100)}%)`);
+            lines.push(`  Avg cost reduction: ${avgReduction}% (estimated → actual)`);
+            if (missedSavings > 0) {
+                lines.push(`  Missed savings: ${missedSavings} call${missedSavings === 1 ? '' : 's'} could have used cheaper tools`);
+            }
+        }
+        // Hook interception details
+        if (sessionDenied.length > 0) {
+            const hookTokensSaved = sessionDenied.reduce((s, d) => s + d.estimatedTokens, 0);
+            lines.push('');
+            lines.push(`Hook interceptions: ${sessionDenied.length} unbounded Read calls denied → ~${hookTokensSaved} tokens saved`);
+            const byHookFile = new Map();
+            for (const d of sessionDenied) {
+                const e = byHookFile.get(d.filePath) ?? { count: 0, tokens: 0 };
+                e.count++;
+                e.tokens += d.estimatedTokens;
+                byHookFile.set(d.filePath, e);
+            }
+            const topHookFiles = Array.from(byHookFile.entries()).sort((a, b) => b[1].tokens - a[1].tokens).slice(0, 5);
+            for (const [file, stats] of topHookFiles) {
+                lines.push(`  ${file}: ${stats.count}× denied, ~${stats.tokens} tokens saved`);
+            }
+        }
+        // Context-mode
+        if (this.contextModeStatus.detected) {
+            lines.push('');
+            lines.push('--- Combined Architecture ---');
+            lines.push(`context-mode: active (detected via ${this.contextModeStatus.source})`);
+            lines.push('Token Pilot handles: code files (AST-level structural reading)');
+            lines.push('context-mode handles: shell output, logs, large data files (BM25-indexed)');
+        }
         return lines.join('\n');
     }
     reset() {
         this.calls = [];
         this.sessionStart = Date.now();
+        clearDeniedReads(this.projectRoot);
     }
 }
 //# sourceMappingURL=session-analytics.js.map

package/dist/core/validation.d.ts

@@ -23,6 +23,16 @@ export declare function validateReadSymbolArgs(args: unknown): {
     context_after?: number;
     show?: 'full' | 'head' | 'tail' | 'outline';
 };
+/**
+ * Validate read_symbols arguments (batch multi-symbol read).
+ */
+export declare function validateReadSymbolsArgs(args: unknown): {
+    path: string;
+    symbols: string[];
+    context_before?: number;
+    context_after?: number;
+    show?: 'full' | 'head' | 'tail' | 'outline';
+};
 /**
  * Validate read_range arguments.
  */
@@ -48,6 +58,7 @@ export interface FindUsagesArgs {
     kind?: 'definitions' | 'imports' | 'usages' | 'all';
     limit?: number;
     lang?: string;
+    context_lines?: number;
 }
 export declare function validateFindUsagesArgs(args: unknown): FindUsagesArgs;
 /**
@@ -62,6 +73,7 @@ export declare function validateSmartReadManyArgs(args: unknown): {
 export declare function validateReadForEditArgs(args: unknown): {
     path: string;
     symbol?: string;
+    symbols?: string[];
     line?: number;
     context?: number;
     include_callers?: boolean;

package/dist/core/validation.js

@@ -60,6 +60,44 @@ export function validateReadSymbolArgs(args) {
         show,
     };
 }
+/**
+ * Validate read_symbols arguments (batch multi-symbol read).
+ */
+export function validateReadSymbolsArgs(args) {
+    if (!args || typeof args !== 'object') {
+        throw new Error('Arguments must be an object.');
+    }
+    const a = args;
+    if (typeof a.path !== 'string' || a.path.length === 0) {
+        throw new Error('Required parameter "path" must be a non-empty string.');
+    }
+    if (!Array.isArray(a.symbols) || a.symbols.length === 0) {
+        throw new Error('Required parameter "symbols" must be a non-empty array of strings.');
+    }
+    if (a.symbols.length > 10) {
+        throw new Error('"symbols" can contain at most 10 symbols.');
+    }
+    for (const s of a.symbols) {
+        if (typeof s !== 'string' || s.length === 0) {
+            throw new Error('Each symbol in "symbols" must be a non-empty string.');
+        }
+    }
+    let show;
+    if (a.show !== undefined && a.show !== null) {
+        const valid = ['full', 'head', 'tail', 'outline'];
+        if (typeof a.show !== 'string' || !valid.includes(a.show)) {
+            throw new Error('"show" must be one of: full, head, tail, outline.');
+        }
+        show = a.show;
+    }
+    return {
+        path: a.path,
+        symbols: a.symbols,
+        context_before: optionalNumber(a.context_before, 'context_before'),
+        context_after: optionalNumber(a.context_after, 'context_after'),
+        show,
+    };
+}
 /**
  * Validate read_range arguments.
  */
@@ -118,12 +156,17 @@ export function validateFindUsagesArgs(args) {
     if (limit !== undefined && (limit < 1 || limit > 500)) {
         throw new Error('"limit" must be between 1 and 500.');
     }
+    const context_lines = optionalNumber(a.context_lines, 'context_lines');
+    if (context_lines !== undefined && (context_lines < 0 || context_lines > 10)) {
+        throw new Error('"context_lines" must be between 0 and 10.');
+    }
     return {
         symbol: a.symbol,
         scope: optionalString(a.scope, 'scope'),
         kind,
         limit,
         lang: optionalString(a.lang, 'lang'),
+        context_lines,
     };
 }
 /**
@@ -176,12 +219,29 @@ export function validateReadForEditArgs(args) {
     if (typeof a.path !== 'string' || a.path.length === 0) {
         throw new Error('Required parameter "path" must be a non-empty string.');
     }
-    if (!a.symbol && !a.line) {
-        throw new Error('Either "symbol" or "line" must be provided.');
+    if (!a.symbol && !a.line && (!Array.isArray(a.symbols) || a.symbols.length === 0)) {
+        throw new Error('Either "symbol", "symbols", or "line" must be provided.');
+    }
+    // Validate symbols array (batch mode)
+    let symbols;
+    if (a.symbols !== undefined && a.symbols !== null) {
+        if (!Array.isArray(a.symbols)) {
+            throw new Error('"symbols" must be an array of strings.');
+        }
+        if (a.symbols.length > 10) {
+            throw new Error('"symbols" can contain at most 10 symbols.');
+        }
+        for (const s of a.symbols) {
+            if (typeof s !== 'string' || s.length === 0) {
+                throw new Error('Each symbol in "symbols" must be a non-empty string.');
+            }
+        }
+        symbols = a.symbols;
     }
     return {
         path: a.path,
         symbol: optionalString(a.symbol, 'symbol'),
+        symbols,
         line: optionalNumber(a.line, 'line'),
         context: optionalNumber(a.context, 'context'),
         include_callers: optionalBool(a.include_callers, 'include_callers'),

package/dist/handlers/find-usages.d.ts

@@ -10,7 +10,7 @@ import type { FindUsagesArgs } from '../core/validation.js';
  *
  * v1.1: added scope, kind, limit, lang post-filters.
  */
-export declare function handleFindUsages(args: FindUsagesArgs, astIndex: AstIndexClient): Promise<{
+export declare function handleFindUsages(args: FindUsagesArgs, astIndex: AstIndexClient, projectRoot?: string): Promise<{
     content: Array<{
         type: 'text';
         text: string;

package/dist/handlers/find-usages.js

@@ -1,3 +1,5 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
 import { assessConfidence, formatConfidence } from '../core/confidence.js';
 /**
  * Escape special regex characters in a string.
@@ -51,6 +53,52 @@ function renderSection(title, items) {
     lines.push('');
     return lines;
 }
+/**
+ * Render a section with surrounding source context lines.
+ */
+async function renderSectionWithContext(title, items, contextLines, projectRoot) {
+    if (items.length === 0)
+        return [];
+    const lines = [`${title}:`];
+    const byFile = new Map();
+    for (const item of items) {
+        const arr = byFile.get(item.file) ?? [];
+        arr.push({ line: item.line, text: item.text });
+        byFile.set(item.file, arr);
+    }
+    for (const [file, matches] of byFile) {
+        matches.sort((a, b) => a.line - b.line);
+        lines.push(`  ${file}:`);
+        // Read file for context
+        let fileLines = null;
+        try {
+            const content = await readFile(resolve(projectRoot, file), 'utf-8');
+            fileLines = content.split('\n');
+        }
+        catch {
+            // File unreadable — fall back to text-only
+            for (const m of matches) {
+                lines.push(`    :${m.line}  ${m.text}`);
+            }
+            continue;
+        }
+        for (let mi = 0; mi < matches.length; mi++) {
+            const m = matches[mi];
+            const start = Math.max(0, m.line - 1 - contextLines);
+            const end = Math.min(fileLines.length, m.line + contextLines);
+            for (let i = start; i < end; i++) {
+                const lineNum = i + 1;
+                const marker = lineNum === m.line ? '>' : ' ';
+                lines.push(`    ${marker} ${lineNum} | ${fileLines[i]}`);
+            }
+            if (mi < matches.length - 1) {
+                lines.push('');
+            }
+        }
+    }
+    lines.push('');
+    return lines;
+}
 /**
  * Find all usages of a symbol across the project.
  *
@@ -61,7 +109,7 @@ function renderSection(title, items) {
  *
  * v1.1: added scope, kind, limit, lang post-filters.
  */
-export async function handleFindUsages(args, astIndex) {
+export async function handleFindUsages(args, astIndex, projectRoot) {
     if (astIndex.isDisabled() || astIndex.isOversized()) {
         return {
             content: [{
@@ -183,9 +231,21 @@ export async function handleFindUsages(args, astIndex) {
         `REFS: "${args.symbol}" (${totalCount} total: ${definitions.length} def · ${allImports.length} imports · ${allUsages.length} usages)${filterStr}`,
         '',
     ];
-    lines.push(...renderSection('DEFINITIONS', definitions));
-    lines.push(...renderSection('IMPORTS', allImports));
-    lines.push(...renderSection('USAGES', allUsages));
+    if (args.context_lines !== undefined && args.context_lines > 0 && projectRoot) {
+        const [defSection, impSection, useSection] = await Promise.all([
+            renderSectionWithContext('DEFINITIONS', definitions, args.context_lines, projectRoot),
+            renderSectionWithContext('IMPORTS', allImports, args.context_lines, projectRoot),
+            renderSectionWithContext('USAGES', allUsages, args.context_lines, projectRoot),
+        ]);
+        lines.push(...defSection);
+        lines.push(...impSection);
+        lines.push(...useSection);
+    }
+    else {
+        lines.push(...renderSection('DEFINITIONS', definitions));
+        lines.push(...renderSection('IMPORTS', allImports));
+        lines.push(...renderSection('USAGES', allUsages));
+    }
     lines.push('HINT: Use read_symbol() or read_range() to load specific results.');
     // Confidence metadata
     const confidenceMeta = assessConfidence({

package/dist/handlers/read-for-edit.d.ts

@@ -5,6 +5,7 @@ import type { ContextRegistry } from '../core/context-registry.js';
 export interface ReadForEditArgs {
     path: string;
     symbol?: string;
+    symbols?: string[];
     line?: number;
     context?: number;
     include_callers?: boolean;

package/dist/handlers/read-for-edit.js

@@ -39,6 +39,71 @@ export async function handleReadForEdit(args, projectRoot, symbolResolver, fileC
             lastAccess: Date.now(),
         });
     }
+    // --- Batch mode: multiple symbols ---
+    if (args.symbols && args.symbols.length > 0) {
+        let structure = cached?.structure;
+        if (!structure) {
+            structure = await astIndex.outline(absPath) ?? undefined;
+        }
+        const sections = [];
+        sections.push(`--- EDIT CONTEXT (BATCH: ${args.symbols.length} symbols) ---`);
+        sections.push(`FILE: ${args.path}`);
+        sections.push('');
+        let resolved_count = 0;
+        for (let i = 0; i < args.symbols.length; i++) {
+            const symName = args.symbols[i];
+            const resolved = await symbolResolver.resolve(symName, structure);
+            if (!resolved) {
+                sections.push(`=== SYMBOL ${i + 1}/${args.symbols.length}: ${symName} — NOT FOUND ===`);
+                sections.push('');
+                continue;
+            }
+            resolved_count++;
+            const symbolLines = resolved.endLine - resolved.startLine + 1;
+            const MAX_EDIT_LINES = 60;
+            let effStart = resolved.startLine;
+            let effEnd;
+            let label;
+            if (symbolLines <= MAX_EDIT_LINES) {
+                effEnd = resolved.endLine;
+                label = `${symName} [L${effStart}-${effEnd}] (${symbolLines} lines, full)`;
+            }
+            else {
+                effEnd = effStart + MAX_EDIT_LINES - 1;
+                label = `${symName} [L${effStart}-${resolved.endLine}] (showing first ${MAX_EDIT_LINES} of ${symbolLines} lines)`;
+            }
+            const rangeStart = Math.max(1, effStart - ctx);
+            const rangeEnd = Math.min(lines.length, effEnd + ctx);
+            const rawCode = lines.slice(rangeStart - 1, rangeEnd).join('\n');
+            sections.push(`=== SYMBOL ${i + 1}/${args.symbols.length}: ${label} ===`);
+            sections.push('');
+            sections.push(rawCode);
+            sections.push('');
+            // Track each symbol
+            contextRegistry.trackLoad(absPath, {
+                type: 'symbol',
+                symbolName: symName,
+                startLine: rangeStart,
+                endLine: rangeEnd,
+                tokens: estimateTokens(rawCode),
+            });
+        }
+        sections.push('--- END EDIT CONTEXT ---');
+        sections.push('');
+        sections.push(`To edit: use exact text from each section as old_string in Edit tool.`);
+        if (resolved_count < args.symbols.length) {
+            sections.push(`WARNING: ${args.symbols.length - resolved_count} symbol(s) not found. Use smart_read to see available symbols.`);
+        }
+        const confidenceMeta = assessConfidence({
+            symbolResolved: resolved_count > 0,
+            fullFile: false,
+            truncated: false,
+            astAvailable: true,
+        });
+        sections.push(formatConfidence(confidenceMeta));
+        const output = sections.join('\n');
+        return { content: [{ type: 'text', text: output }] };
+    }
     let startLine;
     let endLine;
     let targetLabel;

package/dist/handlers/read-symbols.d.ts

@@ -0,0 +1,18 @@
+import type { AstIndexClient } from '../ast-index/client.js';
+import type { SymbolResolver } from '../core/symbol-resolver.js';
+import type { FileCache } from '../core/file-cache.js';
+import type { ContextRegistry } from '../core/context-registry.js';
+export interface ReadSymbolsArgs {
+    path: string;
+    symbols: string[];
+    context_before?: number;
+    context_after?: number;
+    show?: 'full' | 'head' | 'tail' | 'outline';
+}
+export declare function handleReadSymbols(args: ReadSymbolsArgs, projectRoot: string, symbolResolver: SymbolResolver, fileCache: FileCache, contextRegistry: ContextRegistry, astIndex?: AstIndexClient, advisoryReminders?: boolean): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=read-symbols.d.ts.map