token-pilot 0.16.2 → 0.18.0

package/dist/handlers/markdown-sections.js

@@ -0,0 +1,49 @@
+/**
+ * Markdown section parser — shared helper for section-aware tools.
+ * Parses heading structure with line ranges for targeted reading.
+ */
+export function parseMarkdownSections(content) {
+    if (!content.trim())
+        return [];
+    const lines = content.split('\n');
+    const headings = [];
+    for (let i = 0; i < lines.length; i++) {
+        const match = lines[i].match(/^(#{1,6})\s+(.+)/);
+        if (match) {
+            headings.push({
+                heading: match[2].trim(),
+                level: match[1].length,
+                line: i + 1,
+            });
+        }
+    }
+    if (headings.length === 0)
+        return [];
+    const sections = [];
+    for (let i = 0; i < headings.length; i++) {
+        const current = headings[i];
+        let endLine = lines.length;
+        for (let j = i + 1; j < headings.length; j++) {
+            if (headings[j].level <= current.level) {
+                endLine = headings[j].line - 1;
+                break;
+            }
+        }
+        sections.push({
+            heading: current.heading,
+            level: current.level,
+            startLine: current.line,
+            endLine,
+            lineCount: endLine - current.line + 1,
+        });
+    }
+    return sections;
+}
+export function findSection(sections, heading) {
+    const normalized = heading.replace(/^#+\s*/, '').trim().toLowerCase();
+    return sections.find(s => s.heading.toLowerCase() === normalized);
+}
+export function extractSectionContent(lines, section) {
+    return lines.slice(section.startLine - 1, section.endLine).join('\n');
+}
+//# sourceMappingURL=markdown-sections.js.map

package/dist/handlers/non-code.js

@@ -2,12 +2,16 @@ import { readFile } from 'node:fs/promises';
 import { extname } from 'node:path';
 import { estimateTokens } from '../core/token-estimator.js';
 import { resolveSafePath } from '../core/validation.js';
+import { parseMarkdownSections } from './markdown-sections.js';
+import { parseYamlSections } from './yaml-sections.js';
+import { parseJsonSections } from './json-sections.js';
+import { parseCsvOutline, formatCsvOutline } from './csv-sections.js';
 /**
  * Detect if a file is a non-code structured file (JSON, YAML, Markdown, etc.)
  */
 export function isNonCodeStructured(filePath) {
     const ext = extname(filePath).toLowerCase();
-    return ['.json', '.yaml', '.yml', '.md', '.markdown', '.toml'].includes(ext);
+    return ['.json', '.yaml', '.yml', '.md', '.markdown', '.toml', '.csv'].includes(ext);
 }
 /**
  * Generate a structural summary for non-code files.
@@ -37,6 +41,9 @@ export async function handleNonCodeRead(filePath, projectRoot, contextRegistry,
         case '.toml':
             summary = summarizeToml(filePath, content, lines.length);
             break;
+        case '.csv':
+            summary = summarizeCsv(filePath, content, lines.length);
+            break;
         default:
             return null;
     }
@@ -87,14 +94,34 @@ function summarizeJson(filePath, content, lineCount) {
     catch {
         lines.push('(Invalid JSON — parse error)');
     }
+    // Add section line ranges for navigation
+    const jsonSections = parseJsonSections(content);
+    if (jsonSections.length > 0) {
+        lines.push('');
+        lines.push('SECTION RANGES:');
+        for (const sec of jsonSections) {
+            lines.push(`  "${sec.heading}" [L${sec.startLine}-${sec.endLine}] (${sec.lineCount} lines)`);
+        }
+    }
+    lines.push('');
+    lines.push(`HINT: Use read_section("${filePath}", heading="<key>") to load a specific section.`);
     return lines.join('\n');
 }
 function summarizeYaml(filePath, content, lineCount) {
     const lines = [
         `FILE: ${filePath} (${lineCount} lines, YAML)`,
         '',
-        'STRUCTURE:',
     ];
+    // Add top-level section overview with line ranges
+    const yamlSections = parseYamlSections(content);
+    if (yamlSections.length > 0) {
+        lines.push('SECTIONS:');
+        for (const sec of yamlSections) {
+            lines.push(`  ${sec.heading}: [L${sec.startLine}-${sec.endLine}] (${sec.lineCount} lines)`);
+        }
+        lines.push('');
+    }
+    lines.push('STRUCTURE:');
     const rawLines = content.split('\n');
     const roots = [];
     // Stack tracks parent nodes at each indent level
@@ -159,6 +186,8 @@ function summarizeYaml(filePath, content, lineCount) {
             formatYamlNode(root, lines, 1, 3); // max 3 levels deep
         }
     }
+    lines.push('');
+    lines.push(`HINT: Use read_section("${filePath}", heading="<key>") to load a specific section.`);
     return lines.join('\n');
 }
 function formatYamlNode(node, lines, depth, maxDepth) {
@@ -194,16 +223,17 @@ function summarizeMarkdown(filePath, content, lineCount) {
     const lines = [
         `FILE: ${filePath} (${lineCount} lines, Markdown)`,
         '',
-        'TABLE OF CONTENTS:',
     ];
-    // Extract headings
-    for (const line of content.split('\n')) {
-        const match = line.match(/^(#{1,6})\s+(.+)/);
-        if (match) {
-            const level = match[1].length;
-            const indent = '  '.repeat(level - 1);
-            lines.push(`${indent}${match[2]}`);
-        }
+    const sections = parseMarkdownSections(content);
+    if (sections.length === 0) {
+        lines.push('(No headings found)');
+        return lines.join('\n');
+    }
+    lines.push('SECTIONS:');
+    for (const sec of sections) {
+        const indent = '  '.repeat(sec.level);
+        const hashes = '#'.repeat(sec.level);
+        lines.push(`${indent}${hashes} ${sec.heading} [L${sec.startLine}-${sec.endLine}] (${sec.lineCount} lines)`);
     }
     // Count code blocks
     const codeBlocks = (content.match(/```/g) || []).length / 2;
@@ -211,6 +241,9 @@ function summarizeMarkdown(filePath, content, lineCount) {
         lines.push('');
         lines.push(`Code blocks: ${Math.floor(codeBlocks)}`);
     }
+    lines.push('');
+    lines.push(`HINT: Use read_section("${filePath}", heading="<name>") to load a specific section.`);
+    lines.push(`      Use read_for_edit("${filePath}", section="<name>") for edit context.`);
     return lines.join('\n');
 }
 function summarizeToml(filePath, content, lineCount) {
@@ -228,4 +261,8 @@ function summarizeToml(filePath, content, lineCount) {
     }
     return lines.join('\n');
 }
+function summarizeCsv(filePath, content, lineCount) {
+    const outline = parseCsvOutline(content);
+    return formatCsvOutline(filePath, outline, lineCount);
+}
 //# sourceMappingURL=non-code.js.map

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

@@ -11,8 +11,11 @@ export interface ReadForEditArgs {
     include_callers?: boolean;
     include_tests?: boolean;
     include_changes?: boolean;
+    section?: string;
 }
-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

@@ -2,15 +2,121 @@ import { readFile, stat, access } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { createHash } from 'node:crypto';
-import { relative, join } from 'node:path';
+import { relative, join, extname } from 'node:path';
+import { parseMarkdownSections, findSection, extractSectionContent } from './markdown-sections.js';
+import { parseYamlSections, findYamlSection, extractYamlSectionContent } from './yaml-sections.js';
+import { parseJsonSections, findJsonSection, extractJsonSectionContent } from './json-sections.js';
+import { parseCsvOutline, parseCsvSectionSpec, extractCsvSectionContent } from './csv-sections.js';
 import { estimateTokens } from '../core/token-estimator.js';
 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;
+    // Section mode: markdown/YAML section extraction for edit
+    if (args.section) {
+        const ext = extname(absPath).toLowerCase();
+        const supportedExts = new Set(['.md', '.markdown', '.yaml', '.yml', '.json', '.csv']);
+        if (!supportedExts.has(ext)) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `"section" parameter only works with Markdown, YAML, or JSON files. Got: ${ext}. Use "symbol" for code files.`,
+                    }],
+            };
+        }
+        const fileContent = await readFile(absPath, 'utf-8');
+        const fileLines = fileContent.split('\n');
+        // Cache file in fileCache for read_diff baseline
+        if (!fileCache.get(absPath)) {
+            const fileStat = await stat(absPath);
+            const hash = createHash('sha256').update(fileContent).digest('hex');
+            const language = ext === '.csv' ? 'csv' : ext === '.json' ? 'json' : (ext === '.md' || ext === '.markdown') ? 'markdown' : 'yaml';
+            fileCache.set(absPath, {
+                structure: { path: absPath, language, meta: { lines: fileLines.length, bytes: fileContent.length, lastModified: fileStat.mtimeMs, contentHash: hash }, imports: [], exports: [], symbols: [] },
+                content: fileContent, lines: fileLines, mtime: fileStat.mtimeMs, hash, lastAccess: Date.now(),
+            });
+        }
+        let sectionResult = null;
+        if (ext === '.md' || ext === '.markdown') {
+            const sections = parseMarkdownSections(fileContent);
+            const section = findSection(sections, args.section);
+            if (!section) {
+                const available = sections.map(s => s.heading).join(', ');
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Section "${args.section}" not found in ${args.path}.\nAvailable: ${available}`,
+                        }],
+                };
+            }
+            const hashes = '#'.repeat(section.level);
+            sectionResult = { ...section, rawContent: extractSectionContent(fileLines, section), label: `${hashes} ${section.heading}` };
+        }
+        else if (ext === '.yaml' || ext === '.yml') {
+            const sections = parseYamlSections(fileContent);
+            const section = findYamlSection(sections, args.section);
+            if (!section) {
+                const available = sections.map(s => s.heading).join(', ');
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Section "${args.section}" not found in ${args.path}.\nAvailable: ${available}`,
+                        }],
+                };
+            }
+            sectionResult = { ...section, rawContent: extractYamlSectionContent(fileLines, section), label: section.heading };
+        }
+        else if (ext === '.json') {
+            const sections = parseJsonSections(fileContent);
+            const section = findJsonSection(sections, args.section);
+            if (!section) {
+                const available = sections.map(s => s.heading).join(', ');
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Section "${args.section}" not found in ${args.path}.\nAvailable: ${available}`,
+                        }],
+                };
+            }
+            sectionResult = { ...section, rawContent: extractJsonSectionContent(fileLines, section), label: section.heading };
+        }
+        else if (ext === '.csv') {
+            const outline = parseCsvOutline(fileContent);
+            const section = parseCsvSectionSpec(args.section, outline.rowCount);
+            if (!section) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Invalid section "${args.section}" for CSV. Use: rows:1-50 or row:5\nTotal rows: ${outline.rowCount}`,
+                        }],
+                };
+            }
+            sectionResult = { ...section, rawContent: extractCsvSectionContent(fileLines, section), label: section.heading };
+        }
+        if (!sectionResult) {
+            return { content: [{ type: 'text', text: `Unsupported file type: ${ext}` }] };
+        }
+        const outputLines = [
+            `FILE: ${args.path}`,
+            `EDIT SECTION: ${sectionResult.label} [L${sectionResult.startLine}-${sectionResult.endLine}] (${sectionResult.lineCount} lines)`,
+            '',
+            sectionResult.rawContent,
+            '',
+            `AFTER EDIT: Use read_diff("${args.path}") to verify changes (90% cheaper than re-reading).`,
+        ];
+        const output = outputLines.join('\n');
+        const tokens = estimateTokens(output);
+        contextRegistry.trackLoad(absPath, {
+            type: 'range',
+            startLine: sectionResult.startLine,
+            endLine: sectionResult.endLine,
+            tokens,
+        });
+        return { content: [{ type: 'text', text: output }] };
+    }
     // Get file content — also cache for read_diff baseline
     const cached = fileCache.get(absPath);
     let lines;
@@ -220,6 +326,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-section.d.ts

@@ -0,0 +1,12 @@
+import type { ContextRegistry } from '../core/context-registry.js';
+export interface ReadSectionArgs {
+    path: string;
+    heading: string;
+}
+export declare function handleReadSection(args: ReadSectionArgs, projectRoot: string, contextRegistry: ContextRegistry): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=read-section.d.ts.map

package/dist/handlers/read-section.js

@@ -0,0 +1,96 @@
+import { readFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { estimateTokens } from '../core/token-estimator.js';
+import { resolveSafePath } from '../core/validation.js';
+import { parseMarkdownSections, findSection, extractSectionContent } from './markdown-sections.js';
+import { parseYamlSections, findYamlSection, extractYamlSectionContent } from './yaml-sections.js';
+import { parseJsonSections, findJsonSection, extractJsonSectionContent } from './json-sections.js';
+import { parseCsvOutline, parseCsvSectionSpec, extractCsvSectionContent } from './csv-sections.js';
+export async function handleReadSection(args, projectRoot, contextRegistry) {
+    const absPath = resolveSafePath(projectRoot, args.path);
+    const ext = extname(absPath).toLowerCase();
+    const content = await readFile(absPath, 'utf-8');
+    const lines = content.split('\n');
+    // Dispatch to format-specific parser
+    let sectionData = null;
+    if (ext === '.md' || ext === '.markdown') {
+        const sections = parseMarkdownSections(content);
+        const section = findSection(sections, args.heading);
+        if (!section) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Section "${args.heading}" not found in ${args.path}.\nAvailable sections: ${sections.map(s => s.heading).join(', ')}`,
+                    }],
+            };
+        }
+        const hashes = '#'.repeat(section.level);
+        sectionData = { ...section, content: extractSectionContent(lines, section), label: `${hashes} ${section.heading}` };
+    }
+    else if (ext === '.yaml' || ext === '.yml') {
+        const sections = parseYamlSections(content);
+        const section = findYamlSection(sections, args.heading);
+        if (!section) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Section "${args.heading}" not found in ${args.path}.\nAvailable sections: ${sections.map(s => s.heading).join(', ')}`,
+                    }],
+            };
+        }
+        sectionData = { ...section, content: extractYamlSectionContent(lines, section), label: section.heading };
+    }
+    else if (ext === '.json') {
+        const sections = parseJsonSections(content);
+        const section = findJsonSection(sections, args.heading);
+        if (!section) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Section "${args.heading}" not found in ${args.path}.\nAvailable sections: ${sections.map(s => s.heading).join(', ')}`,
+                    }],
+            };
+        }
+        sectionData = { ...section, content: extractJsonSectionContent(lines, section), label: section.heading };
+    }
+    else if (ext === '.csv') {
+        const outline = parseCsvOutline(content);
+        const section = parseCsvSectionSpec(args.heading, outline.rowCount);
+        if (!section) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Invalid section spec "${args.heading}" for CSV. Use format: rows:1-50 or row:5\nTotal rows: ${outline.rowCount}`,
+                    }],
+            };
+        }
+        sectionData = { ...section, content: extractCsvSectionContent(lines, section), label: section.heading };
+    }
+    else {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `read_section supports: .md, .yaml, .yml, .json, .csv. Got: ${ext}`,
+                }],
+        };
+    }
+    const outputLines = [
+        `FILE: ${args.path}`,
+        `SECTION: ${sectionData.label} [L${sectionData.startLine}-${sectionData.endLine}] (${sectionData.lineCount} lines)`,
+        '',
+        sectionData.content,
+        '',
+        `HINT: Use read_for_edit("${args.path}", section="${sectionData.heading}") for edit context.`,
+        'CONTEXT TRACKED.',
+    ];
+    const output = outputLines.join('\n');
+    const tokens = estimateTokens(output);
+    contextRegistry.trackLoad(absPath, {
+        type: 'range',
+        startLine: sectionData.startLine,
+        endLine: sectionData.endLine,
+        tokens,
+    });
+    return { content: [{ type: 'text', text: output }] };
+}
+//# sourceMappingURL=read-section.js.map

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/handlers/yaml-sections.d.ts

@@ -0,0 +1,17 @@
+/**
+ * YAML section parser — parses top-level keys with line ranges.
+ */
+export interface YamlSection {
+    heading: string;
+    startLine: number;
+    endLine: number;
+    lineCount: number;
+}
+/**
+ * Parse YAML into sections based on top-level keys.
+ * A top-level key is a key at indent level 0.
+ */
+export declare function parseYamlSections(content: string): YamlSection[];
+export declare function findYamlSection(sections: YamlSection[], heading: string): YamlSection | undefined;
+export declare function extractYamlSectionContent(lines: string[], section: YamlSection): string;
+//# sourceMappingURL=yaml-sections.d.ts.map