token-pilot 0.16.2 → 0.17.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to Token Pilot will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.17.0] - 2026-04-02
+
+### Added
+- **`smart_read` scope parameter** — `scope="nav"` returns names + line ranges only (2-3x smaller), `scope="exports"` shows only public API. Default `scope="full"` unchanged.
+- **`smart_read` auto-delta** — when a file changed since last load (within 120s), shows ADDED/REMOVED/UNCHANGED symbols instead of full re-read. Config: `smartRead.autoDelta.enabled`.
+- **`read_symbol` include_edit_context** — optional `include_edit_context=true` appends raw code block (max 60 lines) to save a separate `read_for_edit` call. Large symbols fall back to `read_for_edit`.
+- **`find_usages` mode=list** — compact `file:line` output for initial discovery, 5-10x smaller than full mode.
+- **`smart_read_many` per-file dedup** — skips files already in context and unchanged, returns compact reminder instead.
+- **Actionable hints** — `read_for_edit` suggests `read_diff` after editing. Config: `display.actionableHints`.
+- **`symbol-display-constants.ts`** — shared display constants for symbol rendering.
+
+### Changed
+- **441 tests** (was 427) — new tests for scope, list mode, include_edit_context, dedup.
+- **MCP instructions** updated with scope/mode/include_edit_context guidance.
+- **find_usages context rendering** — sequential instead of concurrent to prevent shared cache race condition.
+
 ## [0.16.1] - 2026-03-21
 
 ### Added

package/dist/config/defaults.js

@@ -12,6 +12,10 @@ export const DEFAULT_CONFIG = {
         smallFileThreshold: 200,
         showDependencyHints: true,
         advisoryReminders: true,
+        autoDelta: {
+            enabled: true,
+            maxAgeSec: 120,
+        },
     },
     git: {
         watchHead: true,
@@ -33,6 +37,7 @@ export const DEFAULT_CONFIG = {
         showReferences: false,
         maxDepth: 2,
         showTokenSavings: true,
+        actionableHints: true,
     },
     contextMode: {
         enabled: 'auto',

package/dist/core/context-registry.d.ts

@@ -40,6 +40,10 @@ export declare class ContextRegistry {
         entries: ContextEntry[];
     };
     estimateTokens(): number;
+    trackStructureSymbols(path: string, symbolNames: string[]): void;
+    getSymbolNames(path: string): string[] | undefined;
+    /** Get the timestamp when a file was last loaded into context. */
+    getLoadedAt(path: string): number | undefined;
     invalidateByGitDiff(changedFiles: string[]): void;
 }
 //# sourceMappingURL=context-registry.d.ts.map

package/dist/core/context-registry.js

@@ -182,6 +182,19 @@ export class ContextRegistry {
         }
         return total;
     }
+    trackStructureSymbols(path, symbolNames) {
+        const entry = this.entries.get(path);
+        if (entry) {
+            entry.symbolNames = symbolNames;
+        }
+    }
+    getSymbolNames(path) {
+        return this.entries.get(path)?.symbolNames;
+    }
+    /** Get the timestamp when a file was last loaded into context. */
+    getLoadedAt(path) {
+        return this.entries.get(path)?.loadedAt;
+    }
     invalidateByGitDiff(changedFiles) {
         for (const file of changedFiles) {
             this.entries.delete(file);

package/dist/core/validation.d.ts

@@ -59,6 +59,7 @@ export interface FindUsagesArgs {
     limit?: number;
     lang?: string;
     context_lines?: number;
+    mode?: 'full' | 'list';
 }
 export declare function validateFindUsagesArgs(args: unknown): FindUsagesArgs;
 /**

package/dist/core/validation.js

@@ -160,6 +160,14 @@ export function validateFindUsagesArgs(args) {
     if (context_lines !== undefined && (context_lines < 0 || context_lines > 10)) {
         throw new Error('"context_lines" must be between 0 and 10.');
     }
+    let mode;
+    if (a.mode !== undefined && a.mode !== null) {
+        const validModes = ['full', 'list'];
+        if (typeof a.mode !== 'string' || !validModes.includes(a.mode)) {
+            throw new Error(`"mode" must be one of: ${validModes.join(', ')}`);
+        }
+        mode = a.mode;
+    }
     return {
         symbol: a.symbol,
         scope: optionalString(a.scope, 'scope'),
@@ -167,6 +175,7 @@ export function validateFindUsagesArgs(args) {
         limit,
         lang: optionalString(a.lang, 'lang'),
         context_lines,
+        mode,
     };
 }
 /**

package/dist/formatters/structure.d.ts

@@ -5,6 +5,7 @@ export interface FormatOptions {
     showDependencyHints?: boolean;
     maxDepth?: number;
     showTokenSavings?: boolean;
+    scope?: 'full' | 'nav' | 'exports';
 }
 /**
  * Format a FileStructure as token-optimized text for LLMs.

package/dist/formatters/structure.js

@@ -2,13 +2,48 @@
  * Format a FileStructure as token-optimized text for LLMs.
  */
 export function formatOutline(structure, options = {}) {
-    const { showImports = true, showDocs = true, showDependencyHints = true, maxDepth = 2, } = options;
+    const { showImports = true, showDocs = true, showDependencyHints = true, maxDepth = 2, scope = 'full', } = options;
     const lines = [];
     // Header
     const sizeKB = (structure.meta.bytes / 1024).toFixed(1);
-    lines.push(`FILE: ${structure.path} (${structure.meta.lines} lines, ${sizeKB}KB)`);
+    const scopeLabel = scope !== 'full' ? `, ${scope} mode` : '';
+    lines.push(`FILE: ${structure.path} (${structure.meta.lines} lines, ${sizeKB}KB${scopeLabel})`);
     lines.push(`LANGUAGE: ${structure.language}`);
     lines.push('');
+    // NAV scope: compact names + line ranges only
+    if (scope === 'nav') {
+        lines.push('SYMBOLS:');
+        for (const sym of structure.symbols) {
+            formatSymbolNav(sym, lines, 1, maxDepth);
+        }
+        lines.push('');
+        lines.push('HINT: Use scope="full" for type signatures and imports. Use read_symbol(path, symbol) to load code.');
+        return lines.join('\n');
+    }
+    // EXPORTS scope: only exported symbols
+    if (scope === 'exports') {
+        const exportNames = new Set(structure.exports.map(e => e.name));
+        const exportedSymbols = structure.symbols.filter(s => exportNames.has(s.name));
+        const hiddenCount = structure.symbols.length - exportedSymbols.length;
+        lines.push('EXPORTS:');
+        for (const exp of structure.exports) {
+            const defaultLabel = exp.isDefault ? ' (default)' : '';
+            lines.push(`  ${exp.kind} ${exp.name}${defaultLabel}`);
+        }
+        lines.push('');
+        lines.push('STRUCTURE:');
+        for (const sym of exportedSymbols) {
+            formatSymbolTree(sym, lines, 1, maxDepth, showDocs, showDependencyHints);
+        }
+        lines.push('');
+        if (hiddenCount > 0) {
+            lines.push(`HINT: ${hiddenCount} non-exported symbol(s) hidden. Use scope="full" to see all symbols.`);
+        }
+        else {
+            lines.push('HINT: Use read_symbol(path, symbol) to load a specific symbol\'s code.');
+        }
+        return lines.join('\n');
+    }
     // Imports
     if (showImports && structure.imports.length > 0) {
         lines.push('IMPORTS:');
@@ -111,6 +146,17 @@ function formatSymbolTree(sym, lines, depth, maxDepth, showDocs, showDeps, paren
         lines.push(`${indent}  (${sym.children.length} members — increase depth to see)`);
     }
 }
+function formatSymbolNav(sym, lines, depth, maxDepth) {
+    const indent = '  '.repeat(depth);
+    const loc = `[L${sym.location.startLine}-${sym.location.endLine}]`;
+    const callable = sym.kind === 'function' || sym.kind === 'method' ? '()' : '';
+    lines.push(`${indent}${sym.name}${callable} ${loc}`);
+    if (depth < maxDepth && sym.children.length > 0) {
+        for (const child of sym.children) {
+            formatSymbolNav(child, lines, depth + 1, maxDepth);
+        }
+    }
+}
 /**
  * Detect HTTP route decorators and format as "METHOD /path".
  * Uses standard HTTP verbs — not framework-specific.

package/dist/handlers/find-usages.js

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { assessConfidence, formatConfidence } from '../core/confidence.js';
 /**
@@ -53,10 +53,15 @@ function renderSection(title, items) {
     lines.push('');
     return lines;
 }
+/** Max unique files to read for context (prevents unbounded I/O). */
+const MAX_CONTEXT_FILES = 30;
+/** Max file size (bytes) to read for context lines. */
+const MAX_CONTEXT_FILE_SIZE = 500_000;
 /**
  * Render a section with surrounding source context lines.
+ * Uses shared fileCache to avoid re-reading the same file across sections.
  */
-async function renderSectionWithContext(title, items, contextLines, projectRoot) {
+async function renderSectionWithContext(title, items, contextLines, projectRoot, fileCache) {
     if (items.length === 0)
         return [];
     const lines = [`${title}:`];
@@ -66,17 +71,30 @@ async function renderSectionWithContext(title, items, contextLines, projectRoot)
         arr.push({ line: item.line, text: item.text });
         byFile.set(item.file, arr);
     }
+    let filesRead = 0;
     for (const [file, matches] of byFile) {
         matches.sort((a, b) => a.line - b.line);
         lines.push(`  ${file}:`);
-        // Read file for context
+        // Read file for context (with shared cache and limits)
         let fileLines = null;
-        try {
-            const content = await readFile(resolve(projectRoot, file), 'utf-8');
-            fileLines = content.split('\n');
+        if (fileCache.has(file)) {
+            fileLines = fileCache.get(file);
         }
-        catch {
-            // File unreadable — fall back to text-only
+        else if (filesRead < MAX_CONTEXT_FILES) {
+            try {
+                const fileStat = await stat(resolve(projectRoot, file));
+                if (fileStat.size <= MAX_CONTEXT_FILE_SIZE) {
+                    const content = await readFile(resolve(projectRoot, file), 'utf-8');
+                    fileLines = content.split('\n');
+                }
+            }
+            catch {
+                // File unreadable
+            }
+            fileCache.set(file, fileLines);
+            filesRead++;
+        }
+        if (!fileLines) {
             for (const m of matches) {
                 lines.push(`    :${m.line}  ${m.text}`);
             }
@@ -218,6 +236,36 @@ export async function handleFindUsages(args, astIndex, projectRoot) {
             meta: { files: [], definitions: 0, imports: 0, usages: 0, total: 0 },
         };
     }
+    // ─── List mode — compact file:line output ───
+    if (args.mode === 'list') {
+        const allItems = [...definitions, ...allImports, ...allUsages];
+        const byFile = new Map();
+        for (const item of allItems) {
+            const arr = byFile.get(item.file) ?? [];
+            arr.push(item.line);
+            byFile.set(item.file, arr);
+        }
+        const listLines = [
+            `USAGES OF "${args.symbol}" (${allItems.length} matches in ${byFile.size} files):`,
+            '',
+        ];
+        for (const [file, fileLines] of byFile) {
+            const sorted = [...new Set(fileLines)].sort((a, b) => a - b);
+            listLines.push(`  ${file}: L${sorted.join(', L')}`);
+        }
+        listLines.push('');
+        listLines.push(`HINT: Use find_usages("${args.symbol}", path="specific_dir/") to narrow, or read_symbol() on specific matches.`);
+        return {
+            content: [{ type: 'text', text: listLines.join('\n') }],
+            meta: {
+                files: Array.from(byFile.keys()),
+                definitions: definitions.length,
+                imports: allImports.length,
+                usages: allUsages.length,
+                total: allItems.length,
+            },
+        };
+    }
     // Build header with active filters
     const filterHints = [];
     if (args.scope)
@@ -232,11 +280,11 @@ export async function handleFindUsages(args, astIndex, projectRoot) {
         '',
     ];
     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),
-        ]);
+        // Shared file cache across sections — sequential to avoid concurrent Map writes
+        const contextFileCache = new Map();
+        const defSection = await renderSectionWithContext('DEFINITIONS', definitions, args.context_lines, projectRoot, contextFileCache);
+        const impSection = await renderSectionWithContext('IMPORTS', allImports, args.context_lines, projectRoot, contextFileCache);
+        const useSection = await renderSectionWithContext('USAGES', allUsages, args.context_lines, projectRoot, contextFileCache);
         lines.push(...defSection);
         lines.push(...impSection);
         lines.push(...useSection);
@@ -247,6 +295,10 @@ export async function handleFindUsages(args, astIndex, projectRoot) {
         lines.push(...renderSection('USAGES', allUsages));
     }
     lines.push('HINT: Use read_symbol() or read_range() to load specific results.');
+    if (totalCount > 20) {
+        lines.push('');
+        lines.push(`NARROW: ${totalCount} matches found. Use find_usages("${args.symbol}", path="specific_dir/") to filter by location.`);
+    }
     // Confidence metadata
     const confidenceMeta = assessConfidence({
         refsFound: totalCount > 0,

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

@@ -12,7 +12,9 @@ export interface ReadForEditArgs {
     include_tests?: boolean;
     include_changes?: boolean;
 }
-export declare function handleReadForEdit(args: ReadForEditArgs, projectRoot: string, symbolResolver: SymbolResolver, fileCache: FileCache, contextRegistry: ContextRegistry, astIndex: AstIndexClient): Promise<{
+export declare function handleReadForEdit(args: ReadForEditArgs, projectRoot: string, symbolResolver: SymbolResolver, fileCache: FileCache, contextRegistry: ContextRegistry, astIndex: AstIndexClient, options?: {
+    actionableHints?: boolean;
+}): Promise<{
     content: Array<{
         type: 'text';
         text: string;

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

@@ -8,7 +8,7 @@ import { resolveSafePath } from '../core/validation.js';
 import { assessConfidence, formatConfidence } from '../core/confidence.js';
 const execFileAsync = promisify(execFile);
 const DEFAULT_CONTEXT = 5;
-export async function handleReadForEdit(args, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex) {
+export async function handleReadForEdit(args, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex, options) {
     const absPath = resolveSafePath(projectRoot, args.path);
     const ctx = args.context ?? DEFAULT_CONTEXT;
     // Get file content — also cache for read_diff baseline
@@ -220,6 +220,11 @@ export async function handleReadForEdit(args, projectRoot, symbolResolver, fileC
         astAvailable: true,
     });
     outputLines.push(formatConfidence(confidenceMeta));
+    // Add post-edit hint (config-gated)
+    if (options?.actionableHints !== false) {
+        outputLines.push('');
+        outputLines.push(`AFTER EDIT: Use read_diff("${args.path}") to verify changes (90% cheaper than re-reading the file).`);
+    }
     const output = outputLines.join('\n');
     const tokens = estimateTokens(output);
     // Track in context

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

@@ -8,6 +8,7 @@ export interface ReadSymbolArgs {
     context_before?: number;
     context_after?: number;
     show?: 'full' | 'head' | 'tail' | 'outline';
+    include_edit_context?: boolean;
 }
 export declare function handleReadSymbol(args: ReadSymbolArgs, projectRoot: string, symbolResolver: SymbolResolver, fileCache: FileCache, contextRegistry: ContextRegistry, astIndex?: AstIndexClient, advisoryReminders?: boolean): Promise<{
     content: Array<{

package/dist/handlers/read-symbol.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { estimateTokens } from '../core/token-estimator.js';
 import { resolveSafePath } from '../core/validation.js';
 import { assessConfidence, formatConfidence } from '../core/confidence.js';
+import { MAX_SYMBOL_LINES, MAX_FULL_LINES, SYMBOL_HEAD_LINES, SYMBOL_TAIL_LINES } from './symbol-display-constants.js';
 export async function handleReadSymbol(args, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex, advisoryReminders = true) {
     const absPath = resolveSafePath(projectRoot, args.path);
     // Get file content
@@ -48,10 +49,9 @@ export async function handleReadSymbol(args, projectRoot, symbolResolver, fileCa
     const loc = `[L${resolved.startLine}-${resolved.endLine}]`;
     const lineCount = resolved.endLine - resolved.startLine + 1;
     // Show mode: control how large symbols are displayed
-    const MAX_SYMBOL_LINES = 300;
-    const MAX_FULL_LINES = 500;
-    const HEAD = 50;
-    const TAIL = 30;
+    // Display constants from shared module (imported at top level)
+    const HEAD = SYMBOL_HEAD_LINES;
+    const TAIL = SYMBOL_TAIL_LINES;
     let displaySource = source;
     let truncated = false;
     // Determine effective show mode
@@ -119,6 +119,22 @@ export async function handleReadSymbol(args, projectRoot, symbolResolver, fileCa
     // Build full output including tracking message, THEN estimate tokens
     outputLines.push('');
     outputLines.push('CONTEXT TRACKED: This symbol is now in your context.');
+    // Optional: append raw edit context to save a separate read_for_edit call (small symbols only)
+    if (args.include_edit_context) {
+        const rawLines = lines.slice(resolved.startLine - 1, resolved.endLine);
+        const maxEditLines = 60;
+        if (rawLines.length <= maxEditLines) {
+            outputLines.push('');
+            outputLines.push('EDIT_CONTEXT (raw — copy directly as old_string):');
+            outputLines.push('```');
+            outputLines.push(rawLines.join('\n'));
+            outputLines.push('```');
+        }
+        else {
+            outputLines.push('');
+            outputLines.push(`EDIT_CONTEXT: Symbol too large (${rawLines.length} lines). Use read_for_edit("${args.path}", symbol="${args.symbol}") instead.`);
+        }
+    }
     const output = outputLines.join('\n');
     const tokens = estimateTokens(output);
     // Track

package/dist/handlers/smart-read-many.js

@@ -23,6 +23,15 @@ export async function handleSmartReadMany(args, projectRoot, astIndex, fileCache
     for (let i = 0; i < uniquePaths.length; i += BATCH_CONCURRENCY) {
         const batch = uniquePaths.slice(i, i + BATCH_CONCURRENCY);
         const settled = await Promise.allSettled(batch.map(async (path) => {
+            // Per-file dedup: if file is in context and unchanged, return compact reminder
+            const absPath = resolveSafePath(projectRoot, path);
+            const cachedFile = fileCache.get(absPath);
+            if (cachedFile && contextRegistry.hasAnyLoaded(absPath) && !contextRegistry.isStale(absPath, cachedFile.hash)) {
+                const reminder = contextRegistry.compactReminder(absPath, cachedFile.structure?.symbols ?? []);
+                const reminderText = reminder || `FILE: ${path} (already in context, unchanged)`;
+                const fullTokens = await estimateFullFileTokens(projectRoot, path);
+                return { path, text: reminderText + `\nFor full re-read: smart_read("${path}")`, fullTokens };
+            }
             const result = await handleSmartRead({ path }, projectRoot, astIndex, fileCache, contextRegistry, config);
             const text = result.content[0]?.text ?? '';
             const fullTokens = await estimateFullFileTokens(projectRoot, path);

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

@@ -8,6 +8,7 @@ export interface SmartReadArgs {
     show_docs?: boolean;
     show_references?: boolean;
     depth?: number;
+    scope?: 'full' | 'nav' | 'exports';
 }
 export declare function handleSmartRead(args: SmartReadArgs, projectRoot: string, astIndex: AstIndexClient, fileCache: FileCache, contextRegistry: ContextRegistry, config: TokenPilotConfig): Promise<{
     content: Array<{

package/dist/handlers/smart-read.js

@@ -6,6 +6,7 @@ import { resolveSafePath } from '../core/validation.js';
 import { isNonCodeStructured, handleNonCodeRead } from './non-code.js';
 import { parseTypeScriptRegex } from '../ast-index/regex-parser.js';
 import { buildFileStructure } from '../ast-index/enricher.js';
+import { formatDuration } from '../core/format-duration.js';
 const TS_JS_EXTENSIONS = new Set(['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs']);
 import { assessConfidence, formatConfidence } from '../core/confidence.js';
 export async function handleSmartRead(args, projectRoot, astIndex, fileCache, contextRegistry, config) {
@@ -111,12 +112,64 @@ export async function handleSmartRead(args, projectRoot, astIndex, fileCache, co
             return { content: [{ type: 'text', text: reminder }] };
         }
     }
+    // 5b. Auto-delta: file changed since last load, recently loaded
+    if (config.smartRead.autoDelta?.enabled &&
+        previouslyLoaded &&
+        contextRegistry.isStale(absPath, cached.hash)) {
+        const loadedAt = contextRegistry.getLoadedAt(absPath);
+        if (loadedAt !== undefined && (Date.now() - loadedAt) < (config.smartRead.autoDelta.maxAgeSec ?? 120) * 1000) {
+            const prevNames = contextRegistry.getSymbolNames(absPath) ?? [];
+            const prevSet = new Set(prevNames);
+            const currentNames = cached.structure.symbols.map(s => s.name);
+            const currentSet = new Set(currentNames);
+            const added = currentNames.filter(n => !prevSet.has(n));
+            const removed = prevNames.filter(n => !currentSet.has(n));
+            const unchanged = currentNames.filter(n => prevSet.has(n));
+            const elapsed = formatDuration(Date.now() - loadedAt);
+            const deltaLines = [
+                `FILE: ${args.path} (DELTA — changed since last read ${elapsed} ago)`,
+                '',
+            ];
+            if (added.length > 0) {
+                deltaLines.push('ADDED:');
+                for (const name of added) {
+                    const sym = cached.structure.symbols.find(s => s.name === name);
+                    if (sym)
+                        deltaLines.push(`  ${sym.kind} ${sym.signature} [L${sym.location.startLine}-${sym.location.endLine}]`);
+                }
+                deltaLines.push('');
+            }
+            if (removed.length > 0) {
+                deltaLines.push(`REMOVED: ${removed.join(', ')}`);
+                deltaLines.push('');
+            }
+            if (unchanged.length > 0) {
+                deltaLines.push(`UNCHANGED (${unchanged.length} symbols):`);
+                for (const name of unchanged.slice(0, 15)) {
+                    const sym = cached.structure.symbols.find(s => s.name === name);
+                    if (sym)
+                        deltaLines.push(`  ${sym.name} [L${sym.location.startLine}-${sym.location.endLine}]`);
+                }
+                if (unchanged.length > 15)
+                    deltaLines.push(`  ... and ${unchanged.length - 15} more`);
+                deltaLines.push('');
+            }
+            deltaLines.push(`HINT: For full re-read: smart_read("${args.path}", scope="full")`);
+            const deltaText = deltaLines.join('\n');
+            const deltaTokens = estimateTokens(deltaText);
+            contextRegistry.trackLoad(absPath, { type: 'structure', startLine: 1, endLine: cached.structure.meta.lines, tokens: deltaTokens });
+            contextRegistry.setContentHash(absPath, cached.hash);
+            contextRegistry.trackStructureSymbols(absPath, currentNames);
+            return { content: [{ type: 'text', text: deltaText }] };
+        }
+    }
     // 6. Format output
     const output = formatOutline(cached.structure, {
         showImports: args.show_imports ?? config.display.showImports,
         showDocs: args.show_docs ?? config.display.showDocs,
         showDependencyHints: config.smartRead.showDependencyHints,
         maxDepth: args.depth ?? config.display.maxDepth,
+        scope: args.scope ?? 'full',
     });
     // 6b. Adaptive fallback: if outline is not significantly smaller than raw, return raw
     const structureTokens = estimateTokens(output);
@@ -129,6 +182,9 @@ export async function handleSmartRead(args, projectRoot, astIndex, fileCache, co
             tokens: fullTokens,
         });
         contextRegistry.setContentHash(absPath, cached.hash);
+        if (cached.structure.symbols.length > 0) {
+            contextRegistry.trackStructureSymbols(absPath, cached.structure.symbols.map(s => s.name));
+        }
         return {
             content: [{
                     type: 'text',
@@ -148,6 +204,7 @@ export async function handleSmartRead(args, projectRoot, astIndex, fileCache, co
         tokens: structureTokens,
     });
     contextRegistry.setContentHash(absPath, cached.hash);
+    contextRegistry.trackStructureSymbols(absPath, cached.structure.symbols.map(s => s.name));
     // 9. Confidence metadata
     const confidenceMeta = assessConfidence({
         symbolResolved: (cached.structure.symbols?.length ?? 0) > 0,

package/dist/handlers/symbol-display-constants.d.ts

@@ -0,0 +1,10 @@
+/** Shared display constants for symbol rendering (read_symbol, read_symbols). */
+/** Symbols larger than this get auto-truncated to outline mode. */
+export declare const MAX_SYMBOL_LINES = 300;
+/** Symbols larger than this are never shown in full, even with show="full". */
+export declare const MAX_FULL_LINES = 500;
+/** Lines shown from the start in head/outline mode. */
+export declare const SYMBOL_HEAD_LINES = 50;
+/** Lines shown from the end in tail/outline mode. */
+export declare const SYMBOL_TAIL_LINES = 30;
+//# sourceMappingURL=symbol-display-constants.d.ts.map

package/dist/handlers/symbol-display-constants.js

@@ -0,0 +1,10 @@
+/** Shared display constants for symbol rendering (read_symbol, read_symbols). */
+/** Symbols larger than this get auto-truncated to outline mode. */
+export const MAX_SYMBOL_LINES = 300;
+/** Symbols larger than this are never shown in full, even with show="full". */
+export const MAX_FULL_LINES = 500;
+/** Lines shown from the start in head/outline mode. */
+export const SYMBOL_HEAD_LINES = 50;
+/** Lines shown from the end in tail/outline mode. */
+export const SYMBOL_TAIL_LINES = 30;
+//# sourceMappingURL=symbol-display-constants.js.map

package/dist/server/tool-definitions.d.ts

@@ -25,10 +25,16 @@ export declare const TOOL_DEFINITIONS: ({
                 type: string;
                 description: string;
             };
+            scope: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
             symbol?: undefined;
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
@@ -39,10 +45,10 @@ export declare const TOOL_DEFINITIONS: ({
             include_tests?: undefined;
             include_changes?: undefined;
             paths?: undefined;
-            scope?: undefined;
             kind?: undefined;
             limit?: undefined;
             lang?: undefined;
+            mode?: undefined;
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
@@ -87,9 +93,14 @@ export declare const TOOL_DEFINITIONS: ({
                 enum: string[];
                 description: string;
             };
+            include_edit_context: {
+                type: string;
+                description: string;
+            };
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            scope?: undefined;
             symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
@@ -100,10 +111,10 @@ export declare const TOOL_DEFINITIONS: ({
             include_tests?: undefined;
             include_changes?: undefined;
             paths?: undefined;
-            scope?: undefined;
             kind?: undefined;
             limit?: undefined;
             lang?: undefined;
+            mode?: undefined;
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
@@ -154,7 +165,9 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            scope?: undefined;
             symbol?: undefined;
+            include_edit_context?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -164,10 +177,10 @@ export declare const TOOL_DEFINITIONS: ({
             include_tests?: undefined;
             include_changes?: undefined;
             paths?: undefined;
-            scope?: undefined;
             kind?: undefined;
             limit?: undefined;
             lang?: undefined;
+            mode?: undefined;
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
@@ -206,10 +219,12 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            scope?: undefined;
             symbol?: undefined;
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             symbols?: undefined;
             context_lines?: undefined;
             line?: undefined;
@@ -218,10 +233,10 @@ export declare const TOOL_DEFINITIONS: ({
             include_tests?: undefined;
             include_changes?: undefined;
             paths?: undefined;
-            scope?: undefined;
             kind?: undefined;
             limit?: undefined;
             lang?: undefined;
+            mode?: undefined;
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
@@ -256,10 +271,12 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            scope?: undefined;
             symbol?: undefined;
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
@@ -269,10 +286,10 @@ export declare const TOOL_DEFINITIONS: ({
             include_tests?: undefined;
             include_changes?: undefined;
             paths?: undefined;
-            scope?: undefined;
             kind?: undefined;
             limit?: undefined;
             lang?: undefined;
+            mode?: undefined;
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
@@ -334,17 +351,19 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            scope?: undefined;
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
             paths?: undefined;
-            scope?: undefined;
             kind?: undefined;
             limit?: undefined;
             lang?: undefined;
+            mode?: undefined;
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
@@ -379,10 +398,12 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            scope?: undefined;
             symbol?: undefined;
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
@@ -392,10 +413,10 @@ export declare const TOOL_DEFINITIONS: ({
             include_callers?: undefined;
             include_tests?: undefined;
             include_changes?: undefined;
-            scope?: undefined;
             kind?: undefined;
             limit?: undefined;
             lang?: undefined;
+            mode?: undefined;
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
@@ -445,6 +466,11 @@ export declare const TOOL_DEFINITIONS: ({
                 type: string;
                 description: string;
             };
+            mode: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
             path?: undefined;
             show_imports?: undefined;
             show_docs?: undefined;
@@ -452,6 +478,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
@@ -496,10 +523,12 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            scope?: undefined;
             symbol?: undefined;
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
@@ -510,10 +539,10 @@ export declare const TOOL_DEFINITIONS: ({
             include_tests?: undefined;
             include_changes?: undefined;
             paths?: undefined;
-            scope?: undefined;
             kind?: undefined;
             limit?: undefined;
             lang?: undefined;
+            mode?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
             verbose?: undefined;
@@ -543,10 +572,12 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            scope?: undefined;
             symbol?: undefined;
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
@@ -557,10 +588,10 @@ export declare const TOOL_DEFINITIONS: ({
             include_tests?: undefined;
             include_changes?: undefined;
             paths?: undefined;
-            scope?: undefined;
             kind?: undefined;
             limit?: undefined;
             lang?: undefined;
+            mode?: undefined;
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
@@ -599,10 +630,12 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            scope?: undefined;
             symbol?: undefined;
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
@@ -613,10 +646,10 @@ export declare const TOOL_DEFINITIONS: ({
             include_tests?: undefined;
             include_changes?: undefined;
             paths?: undefined;
-            scope?: undefined;
             kind?: undefined;
             limit?: undefined;
             lang?: undefined;
+            mode?: undefined;
             include?: undefined;
             verbose?: undefined;
             module?: undefined;
@@ -646,10 +679,12 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            scope?: undefined;
             symbol?: undefined;
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
@@ -660,10 +695,10 @@ export declare const TOOL_DEFINITIONS: ({
             include_tests?: undefined;
             include_changes?: undefined;
             paths?: undefined;
-            scope?: undefined;
             kind?: undefined;
             limit?: undefined;
             lang?: undefined;
+            mode?: undefined;
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
@@ -702,10 +737,12 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            scope?: undefined;
             symbol?: undefined;
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
@@ -716,9 +753,9 @@ export declare const TOOL_DEFINITIONS: ({
             include_tests?: undefined;
             include_changes?: undefined;
             paths?: undefined;
-            scope?: undefined;
             kind?: undefined;
             lang?: undefined;
+            mode?: undefined;
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
@@ -765,10 +802,12 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            scope?: undefined;
             symbol?: undefined;
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
@@ -779,8 +818,8 @@ export declare const TOOL_DEFINITIONS: ({
             include_tests?: undefined;
             include_changes?: undefined;
             paths?: undefined;
-            scope?: undefined;
             kind?: undefined;
+            mode?: undefined;
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
@@ -814,10 +853,12 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            scope?: undefined;
             symbol?: undefined;
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
@@ -828,10 +869,10 @@ export declare const TOOL_DEFINITIONS: ({
             include_tests?: undefined;
             include_changes?: undefined;
             paths?: undefined;
-            scope?: undefined;
             kind?: undefined;
             limit?: undefined;
             lang?: undefined;
+            mode?: undefined;
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
@@ -873,6 +914,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
@@ -886,6 +928,7 @@ export declare const TOOL_DEFINITIONS: ({
             kind?: undefined;
             limit?: undefined;
             lang?: undefined;
+            mode?: undefined;
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
@@ -923,10 +966,12 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            scope?: undefined;
             symbol?: undefined;
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
@@ -937,10 +982,10 @@ export declare const TOOL_DEFINITIONS: ({
             include_tests?: undefined;
             include_changes?: undefined;
             paths?: undefined;
-            scope?: undefined;
             kind?: undefined;
             limit?: undefined;
             lang?: undefined;
+            mode?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
             verbose?: undefined;
@@ -978,10 +1023,12 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            scope?: undefined;
             symbol?: undefined;
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
@@ -992,10 +1039,10 @@ export declare const TOOL_DEFINITIONS: ({
             include_tests?: undefined;
             include_changes?: undefined;
             paths?: undefined;
-            scope?: undefined;
             kind?: undefined;
             limit?: undefined;
             lang?: undefined;
+            mode?: undefined;
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
@@ -1034,10 +1081,12 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            scope?: undefined;
             symbol?: undefined;
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            include_edit_context?: undefined;
             symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
@@ -1048,10 +1097,10 @@ export declare const TOOL_DEFINITIONS: ({
             include_tests?: undefined;
             include_changes?: undefined;
             paths?: undefined;
-            scope?: undefined;
             kind?: undefined;
             limit?: undefined;
             lang?: undefined;
+            mode?: undefined;
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;

package/dist/server/tool-definitions.js

@@ -9,26 +9,30 @@ export const MCP_INSTRUCTIONS = [
     '1. New codebase / unfamiliar project → project_overview',
     '2. Starting work on a directory → explore_area (outline + imports + tests + git log in one call)',
     '3. Need to read a code file → smart_read (NOT Read/cat — returns structure, 60-80% fewer tokens)',
+    '   - For navigation/browsing: smart_read(scope="nav") — names + lines only, 2-3x smaller',
+    '   - For public API overview: smart_read(scope="exports")',
     '4. Need one function/class body → read_symbol (loads only that symbol, NOT the whole file)',
-    '4b. Need MULTIPLE function/class bodies from same file → read_symbols (batch — one call instead of N)',
-    '5. Preparing an edit → read_for_edit (returns exact text for Edit old_string)',
-    '6. Verify edits after editing → read_diff (only changed hunks — REQUIRES smart_read BEFORE editing)',
-    '7. Multiple files at once → smart_read_many (batch up to 20 files)',
-    '8. Find where a symbol is used → find_usages (semantic: definitions + imports + usages)',
-    '9. Understand file dependencies → related_files (imports, importers, tests — ranked by relevance)',
-    '10. List all symbols in a directory → outline (classes, functions, methods in one call)',
-    '11. Review git changes → smart_diff (NOT git diff — maps changes to functions/classes)',
-    '12. Commit history → smart_log (NOT git log — structured with categories)',
-    '13. Run tests → test_summary (NOT raw test output — structured pass/fail)',
-    '14. Code quality → code_audit (TODOs, deprecated, structural patterns)',
-    '15. Dead code → find_unused (unreferenced symbols across project)',
-    '16. Module architecture → module_info (deps, dependents, public API)',
+    '   - Preparing edit? Add include_edit_context=true to skip separate read_for_edit call',
+    '5. Need MULTIPLE function/class bodies from same file → read_symbols (batch — one call instead of N)',
+    '6. Preparing an edit → read_for_edit (returns exact text for Edit old_string)',
+    '7. Verify edits after editing → read_diff (only changed hunks — REQUIRES smart_read BEFORE editing)',
+    '8. Multiple files at once → smart_read_many (batch up to 20 files)',
+    '9. Find where a symbol is used → find_usages (semantic: definitions + imports + usages)',
+    '   - For initial discovery: find_usages(mode="list") — file:line only, 5-10x smaller',
+    '10. Understand file dependencies → related_files (imports, importers, tests — ranked by relevance)',
+    '11. List all symbols in a directory → outline (classes, functions, methods in one call)',
+    '12. Review git changes → smart_diff (NOT git diff — maps changes to functions/classes)',
+    '13. Commit history → smart_log (NOT git log — structured with categories)',
+    '14. Run tests → test_summary (NOT raw test output — structured pass/fail)',
+    '15. Code quality → code_audit (TODOs, deprecated, structural patterns)',
+    '16. Dead code → find_unused (unreferenced symbols across project)',
+    '17. Module architecture → module_info (deps, dependents, public API)',
     '',
     'USE DEFAULT TOOLS ONLY FOR: regex text search → Grep | exact raw content → Read | non-code configs → Read',
     '',
     'WORKFLOWS:',
     '• Explore: project_overview → explore_area → smart_read → read_symbol',
-    '• Edit: smart_read → read_for_edit → Edit → read_diff',
+    '• Edit: smart_read → read_symbol(include_edit_context=true) → Edit → read_diff',
     '• Refactor: find_usages → read_symbols → read_for_edit → Edit → test_summary',
     '• Audit: code_audit + find_unused + Grep (for regex patterns)',
 ].join('\n');
@@ -44,6 +48,11 @@ export const TOOL_DEFINITIONS = [
                 show_imports: { type: 'boolean', description: 'Include import details (default: true)' },
                 show_docs: { type: 'boolean', description: 'Include doc comments (default: true)' },
                 depth: { type: 'number', description: 'Max depth for nested symbols (default: 2)' },
+                scope: {
+                    type: 'string',
+                    enum: ['full', 'nav', 'exports'],
+                    description: 'Output scope: full (default, all details), nav (names + lines only, 2-3x smaller), exports (public API only)',
+                },
             },
             required: ['path'],
         },
@@ -59,13 +68,17 @@ export const TOOL_DEFINITIONS = [
                 context_before: { type: 'number', description: 'Lines of context before (default: 2)' },
                 context_after: { type: 'number', description: 'Lines of context after (default: 0)' },
                 show: { type: 'string', enum: ['full', 'head', 'tail', 'outline'], description: 'Display mode: full (all lines), head (first 50), tail (last 30), outline (head + methods + tail). Default: auto (full ≤300 lines, outline >300)' },
+                include_edit_context: {
+                    type: 'boolean',
+                    description: 'Append raw code block for Edit old_string (saves a read_for_edit call)',
+                },
             },
             required: ['path', 'symbol'],
         },
     },
     {
         name: 'read_symbols',
-        description: 'Batch read MULTIPLE symbols from ONE file in a single call — saves N-1 round-trips vs calling read_symbol N times. Returns all requested symbol bodies.',
+        description: 'Batch read MULTIPLE symbols from ONE file for UNDERSTANDING code — saves N-1 round-trips vs calling read_symbol N times. Returns formatted symbol bodies with show modes (full/head/tail/outline). Use this when READING code, not editing. For edit preparation use read_for_edit instead.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -109,7 +122,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: 'read_for_edit',
-        description: 'Use INSTEAD OF Read when preparing an edit. Returns exact raw code around a symbol or line — copy directly as old_string for Edit tool. Supports batch: pass "symbols" array to get multiple edit contexts in one call. Optional: include_callers, include_tests, include_changes for enriched context.',
+        description: 'Use INSTEAD OF Read when preparing an EDIT. Returns exact RAW code around a symbol or line — copy directly as old_string for Edit tool. Supports batch: pass "symbols" array to get multiple edit contexts in one call. Unlike read_symbols (for reading/understanding), this returns unformatted code optimized for copy-paste into Edit. Optional: include_callers, include_tests, include_changes for enriched context.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -157,6 +170,11 @@ export const TOOL_DEFINITIONS = [
                 limit: { type: 'number', description: 'Max results per category (default: 50, max: 500)' },
                 lang: { type: 'string', description: 'Filter by language/extension (e.g., "php", "typescript")' },
                 context_lines: { type: 'number', description: 'Lines of source context around each match (0-10). When set, shows surrounding code — saves follow-up read_symbol calls.' },
+                mode: {
+                    type: 'string',
+                    enum: ['full', 'list'],
+                    description: 'Output mode: full (with context, default), list (file:line only, 5-10x smaller for initial discovery)',
+                },
             },
             required: ['symbol'],
         },

package/dist/server.js

@@ -273,6 +273,7 @@ export async function createServer(projectRoot, options) {
                             return nonCodeResult;
                         }
                     }
+                    // Dedup is handled inside handleSmartRead (step 5)
                     const result = await handleSmartRead(validArgs, projectRoot, astIndex, fileCache, contextRegistry, config);
                     const text = result.content[0]?.text ?? '';
                     const fullTokensSR = await fullFileTokens(validArgs.path);
@@ -283,6 +284,7 @@ export async function createServer(projectRoot, options) {
                 }
                 case 'read_symbol': {
                     const symArgs = validateReadSymbolArgs(args);
+                    // Dedup is handled inside handleReadSymbol
                     const symResult = await handleReadSymbol(symArgs, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex, config.smartRead.advisoryReminders);
                     const symText = symResult.content[0]?.text ?? '';
                     const symTokens = estimateTokens(symText);
@@ -319,7 +321,7 @@ export async function createServer(projectRoot, options) {
                 }
                 case 'read_for_edit': {
                     const editArgs = validateReadForEditArgs(args);
-                    const editResult = await handleReadForEdit(editArgs, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex);
+                    const editResult = await handleReadForEdit(editArgs, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex, { actionableHints: config.display.actionableHints });
                     const editText = editResult.content[0]?.text ?? '';
                     const editTokens = estimateTokens(editText);
                     const fullTokensEdit = await fullFileTokens(editArgs.path);

package/dist/types.d.ts

@@ -59,6 +59,7 @@ export interface ContextEntry {
     contentHash: string;
     tokenEstimate: number;
     loadedAt: number;
+    symbolNames?: string[];
 }
 export interface LoadedRegion {
     type: 'structure' | 'symbol' | 'range' | 'full';
@@ -89,6 +90,10 @@ export interface TokenPilotConfig {
         smallFileThreshold: number;
         showDependencyHints: boolean;
         advisoryReminders: boolean;
+        autoDelta: {
+            enabled: boolean;
+            maxAgeSec: number;
+        };
     };
     git: {
         watchHead: boolean;
@@ -110,6 +115,7 @@ export interface TokenPilotConfig {
         showReferences: boolean;
         maxDepth: number;
         showTokenSavings: boolean;
+        actionableHints: boolean;
     };
     contextMode: {
         enabled: boolean | 'auto';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "description": "Save up to 80% tokens when AI reads code — MCP server for token-efficient code navigation, AST-aware structural reading instead of dumping full files into context window",
   "type": "module",
   "main": "dist/index.js",