token-pilot 0.9.0 → 0.10.0

package/.claude-plugin/marketplace.json

@@ -1,8 +1,8 @@
 {
   "name": "token-pilot",
   "displayName": "Token Pilot",
-  "description": "Reduces token consumption by 80-95% via AST-aware lazy file reading. 14 MCP tools for structural code reading, symbol navigation, and cross-file search.",
-  "version": "0.9.0",
+  "description": "Reduces token consumption by 80-95% via AST-aware lazy file reading. 16 MCP tools for structural code reading, symbol navigation, and cross-file search.",
+  "version": "0.10.0",
   "author": "Digital-Threads",
   "repository": "https://github.com/Digital-Threads/token-pilot",
   "license": "MIT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Reduces token consumption by 80-95% via AST-aware lazy file reading. Returns structural overviews instead of full files.",
   "author": "token-pilot",
   "license": "MIT",

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.10.0] - 2026-03-14
+
+### Added
+- **`smart_diff` tool** — structural git diff with AST symbol mapping. Shows which functions/classes were modified/added/removed instead of raw patch output. Supports scopes: `unstaged`, `staged`, `commit` (ref required), `branch` (ref required). Small diffs (<=30 lines) include actual hunks, large diffs show summary. Returns `rawTokens` for precise savings analytics.
+- **`explore_area` tool** — one-call directory exploration combining outline + imports + tests + git changes. Replaces 3-5 separate tool calls when starting work on an area. Sections: `outline` (recursive depth 2), `imports` (external deps + who imports this area), `tests` (matching test/spec files), `changes` (recent git log). All sections run in parallel via `Promise.allSettled`.
+- **26 new tests** — smart_diff parser (10), symbol mapping (5), validation (11). Total: 170 tests (was 144).
+
+### Changed
+- **16 tools** (was 14) — added `smart_diff`, `explore_area`
+- **MCP instructions** — updated workflow: `project_overview → explore_area → smart_read → read_symbol → read_for_edit → edit → smart_diff`
+- **`outlineDir` and `CODE_EXTENSIONS` exported** from outline.ts for reuse by explore_area
+
 ## [0.9.0] - 2026-03-08
 
 ### Added

package/README.md

@@ -173,6 +173,8 @@ For more control, you can add rules to your project:
 | `find_unused` | manual | Detect dead code — unused functions, classes, variables. |
 | `code_audit` | multiple `Grep` | Code quality issues in one call: TODO/FIXME comments, deprecated symbols, structural code patterns (via ast-grep), decorator search. |
 | `module_info` | manual analysis | Module dependency analysis: dependencies, dependents, public API, unused deps. Use for architecture understanding and dependency cleanup. |
+| `smart_diff` | raw `git diff` | Structural diff with AST symbol mapping — shows which functions/classes changed instead of raw patch. Scopes: unstaged, staged, commit, branch. |
+| `explore_area` | outline + related_files + git log | One-call directory exploration: structure, imports, tests, recent changes. Replaces 3-5 separate calls. |
 
 ### Analytics
 
@@ -351,6 +353,8 @@ src/
     code-audit.ts       — code_audit handler (TODOs, deprecated, patterns)
     project-overview.ts — project_overview (dual-detection + confidence)
     module-info.ts      — module_info handler (deps, dependents, API, unused)
+    smart-diff.ts       — smart_diff handler (structural git diff + symbol mapping)
+    explore-area.ts     — explore_area handler (outline + imports + tests + changes)
     non-code.ts         — JSON/YAML/MD/TOML structural summaries
     export-ast-index.ts — AST export for context-mode BM25
   git/

package/dist/core/validation.d.ts

@@ -110,6 +110,23 @@ export interface ModuleInfoArgs {
     check?: 'deps' | 'dependents' | 'api' | 'unused-deps' | 'all';
 }
 export declare function validateModuleInfoArgs(args: unknown): ModuleInfoArgs;
+/**
+ * Validate smart_diff arguments.
+ */
+export interface SmartDiffArgs {
+    scope?: 'unstaged' | 'staged' | 'commit' | 'branch';
+    path?: string;
+    ref?: string;
+}
+export declare function validateSmartDiffArgs(args: unknown): SmartDiffArgs;
+/**
+ * Validate explore_area arguments.
+ */
+export interface ExploreAreaArgs {
+    path: string;
+    include?: Array<'outline' | 'imports' | 'tests' | 'changes'>;
+}
+export declare function validateExploreAreaArgs(args: unknown): ExploreAreaArgs;
 /** Detect roots that would cause ast-index to scan the entire filesystem */
 export declare function isDangerousRoot(root: string): boolean;
 //# sourceMappingURL=validation.d.ts.map

package/dist/core/validation.js

@@ -293,6 +293,50 @@ export function validateModuleInfoArgs(args) {
         check: check ?? 'all',
     };
 }
+export function validateSmartDiffArgs(args) {
+    if (!args || typeof args !== 'object')
+        return { scope: 'unstaged' };
+    const a = args;
+    let scope;
+    if (a.scope !== undefined && a.scope !== null) {
+        const validScopes = ['unstaged', 'staged', 'commit', 'branch'];
+        if (typeof a.scope !== 'string' || !validScopes.includes(a.scope)) {
+            throw new Error(`"scope" must be one of: ${validScopes.join(', ')}`);
+        }
+        scope = a.scope;
+    }
+    const ref = optionalString(a.ref, 'ref');
+    if ((scope === 'commit' || scope === 'branch') && !ref) {
+        throw new Error(`"ref" is required when scope="${scope}".`);
+    }
+    return {
+        scope: scope ?? 'unstaged',
+        path: optionalString(a.path, 'path'),
+        ref,
+    };
+}
+const VALID_EXPLORE_SECTIONS = ['outline', 'imports', 'tests', 'changes'];
+export function validateExploreAreaArgs(args) {
+    if (!args || typeof args !== 'object') {
+        throw new Error('Arguments must be an object with a "path" parameter.');
+    }
+    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 (a.include !== undefined && a.include !== null) {
+        if (!Array.isArray(a.include)) {
+            throw new Error('"include" must be an array of section names.');
+        }
+        for (const item of a.include) {
+            if (typeof item !== 'string' || !VALID_EXPLORE_SECTIONS.includes(item)) {
+                throw new Error(`Each element of "include" must be one of: ${VALID_EXPLORE_SECTIONS.join(', ')}. Got: "${item}"`);
+            }
+        }
+        return { path: a.path, include: a.include };
+    }
+    return { path: a.path };
+}
 /** Detect roots that would cause ast-index to scan the entire filesystem */
 export function isDangerousRoot(root) {
     const normalized = root.replace(/\/+$/, '') || '/';

package/dist/handlers/explore-area.d.ts

@@ -0,0 +1,9 @@
+import type { AstIndexClient } from '../ast-index/client.js';
+import type { ExploreAreaArgs } from '../core/validation.js';
+export declare function handleExploreArea(args: ExploreAreaArgs, projectRoot: string, astIndex: AstIndexClient): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=explore-area.d.ts.map

package/dist/handlers/explore-area.js

@@ -0,0 +1,280 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readdir, stat } from 'node:fs/promises';
+import { resolve, relative, basename, dirname } from 'node:path';
+import { resolveSafePath } from '../core/validation.js';
+import { outlineDir, CODE_EXTENSIONS } from './outline.js';
+const execFileAsync = promisify(execFile);
+// ──────────────────────────────────────────────
+// Constants
+// ──────────────────────────────────────────────
+const MAX_IMPORT_FILES = 20;
+const MAX_OUTPUT_LINES = 500;
+// ──────────────────────────────────────────────
+// Handler
+// ──────────────────────────────────────────────
+export async function handleExploreArea(args, projectRoot, astIndex) {
+    // Resolve path — if it points to a file, use its parent directory
+    let absPath = resolveSafePath(projectRoot, args.path);
+    const pathStat = await stat(absPath).catch(() => null);
+    if (!pathStat) {
+        return {
+            content: [{ type: 'text', text: `Path "${args.path}" not found.` }],
+        };
+    }
+    if (!pathStat.isDirectory()) {
+        absPath = dirname(absPath);
+    }
+    const relDir = relative(projectRoot, absPath) || '.';
+    const include = args.include ?? ['outline', 'imports', 'tests', 'changes'];
+    // Collect code files for import/test analysis
+    const codeFiles = await listCodeFiles(absPath);
+    // Run all sections in parallel
+    const [outlineSection, importsSection, testsSection, changesSection] = await Promise.allSettled([
+        include.includes('outline') ? buildOutlineSection(absPath, projectRoot, astIndex) : Promise.resolve(null),
+        include.includes('imports') ? buildImportsSection(codeFiles, absPath, projectRoot, astIndex) : Promise.resolve(null),
+        include.includes('tests') ? buildTestsSection(codeFiles, absPath, projectRoot) : Promise.resolve(null),
+        include.includes('changes') ? buildChangesSection(relDir, projectRoot) : Promise.resolve(null),
+    ]);
+    // Assemble output
+    const lines = [];
+    const subdirCount = await countSubdirs(absPath);
+    lines.push(`AREA: ${relDir}/ (${codeFiles.length} code files${subdirCount > 0 ? `, ${subdirCount} subdirs` : ''})`);
+    lines.push('');
+    // Outline
+    const outlineLines = extractResult(outlineSection);
+    if (outlineLines) {
+        lines.push('STRUCTURE:');
+        lines.push(...outlineLines);
+        lines.push('');
+    }
+    // Imports
+    const importLines = extractResult(importsSection);
+    if (importLines) {
+        lines.push(...importLines);
+    }
+    // Tests
+    const testLines = extractResult(testsSection);
+    if (testLines) {
+        lines.push(...testLines);
+    }
+    // Changes
+    const changeLines = extractResult(changesSection);
+    if (changeLines) {
+        lines.push(...changeLines);
+    }
+    // Truncate if needed
+    if (lines.length > MAX_OUTPUT_LINES) {
+        lines.length = MAX_OUTPUT_LINES;
+        lines.push('... truncated. Use outline() on specific subdirectories for details.');
+    }
+    lines.push('HINT: Use smart_read(file) for details, read_symbol(path, symbol) for source code, find_usages(symbol) for references.');
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+}
+// ──────────────────────────────────────────────
+// Outline section — reuses outlineDir from outline.ts
+// ──────────────────────────────────────────────
+async function buildOutlineSection(absPath, projectRoot, astIndex) {
+    const sections = [];
+    await outlineDir(absPath, sections, 0, 2, projectRoot, astIndex);
+    return sections;
+}
+// ──────────────────────────────────────────────
+// Imports section — aggregate external deps + who imports this area
+// ──────────────────────────────────────────────
+async function buildImportsSection(codeFiles, absPath, projectRoot, astIndex) {
+    if (!astIndex.isAvailable() || astIndex.isDisabled() || astIndex.isOversized()) {
+        return [];
+    }
+    const filesToAnalyze = codeFiles.slice(0, MAX_IMPORT_FILES);
+    const externalDeps = new Set();
+    const internalDeps = new Set();
+    const relDir = relative(projectRoot, absPath) || '.';
+    // Get imports for each file
+    const importResults = await Promise.allSettled(filesToAnalyze.map(f => astIndex.fileImports(f)));
+    for (const result of importResults) {
+        if (result.status !== 'fulfilled' || !result.value)
+            continue;
+        for (const imp of result.value) {
+            const source = imp.source;
+            if (!source)
+                continue;
+            if (source.startsWith('.') || source.startsWith('/')) {
+                // Internal import — track if it's outside this area
+                const resolved = resolve(absPath, source);
+                if (!resolved.startsWith(absPath)) {
+                    const relImport = relative(projectRoot, resolved).replace(/\.[^.]+$/, '');
+                    internalDeps.add(relImport);
+                }
+            }
+            else {
+                // External package
+                const pkg = source.startsWith('@') ? source.split('/').slice(0, 2).join('/') : source.split('/')[0];
+                externalDeps.add(pkg);
+            }
+        }
+    }
+    // Find who imports files from this area (reverse dependencies)
+    const importedBy = new Set();
+    const fileBasenames = filesToAnalyze.map(f => basename(f).replace(/\.[^.]+$/, ''));
+    const refResults = await Promise.allSettled(fileBasenames.slice(0, 10).map(name => astIndex.refs(name, 10)));
+    for (const result of refResults) {
+        if (result.status !== 'fulfilled' || !result.value)
+            continue;
+        const refs = result.value;
+        if (refs.imports) {
+            for (const imp of refs.imports) {
+                const impFile = imp.path;
+                if (!impFile)
+                    continue;
+                const relFile = relative(projectRoot, impFile);
+                // Only include files outside this area
+                if (!relFile.startsWith(relDir)) {
+                    importedBy.add(relFile.replace(/\.[^.]+$/, ''));
+                }
+            }
+        }
+    }
+    const lines = [];
+    if (externalDeps.size > 0) {
+        const deps = Array.from(externalDeps).sort().slice(0, 20);
+        lines.push(`IMPORTS: ${deps.join(', ')}${externalDeps.size > 20 ? ` ... (${externalDeps.size} total)` : ''}`);
+    }
+    if (internalDeps.size > 0) {
+        const deps = Array.from(internalDeps).sort().slice(0, 10);
+        lines.push(`INTERNAL DEPS: ${deps.join(', ')}${internalDeps.size > 10 ? ` ... (${internalDeps.size} total)` : ''}`);
+    }
+    if (importedBy.size > 0) {
+        const importers = Array.from(importedBy).sort().slice(0, 10);
+        lines.push(`IMPORTED BY: ${importers.join(', ')}${importedBy.size > 10 ? ` ... (${importedBy.size} total)` : ''}`);
+    }
+    if (lines.length > 0)
+        lines.push('');
+    return lines;
+}
+// ──────────────────────────────────────────────
+// Tests section — find test/spec files matching area files
+// ──────────────────────────────────────────────
+async function buildTestsSection(codeFiles, absPath, projectRoot) {
+    const testFiles = [];
+    const areaFileNames = new Set(codeFiles.map(f => basename(f).replace(/\.[^.]+$/, '')));
+    // Scan for test files: check area dir + common test dirs
+    const dirsToScan = [absPath];
+    // Check for sibling __tests__ or tests directory
+    const parent = dirname(absPath);
+    const areaName = basename(absPath);
+    const testDirCandidates = [
+        resolve(absPath, '__tests__'),
+        resolve(absPath, 'tests'),
+        resolve(absPath, 'test'),
+        resolve(parent, '__tests__', areaName),
+        resolve(parent, 'tests', areaName),
+    ];
+    for (const testDir of testDirCandidates) {
+        const testDirStat = await stat(testDir).catch(() => null);
+        if (testDirStat?.isDirectory()) {
+            dirsToScan.push(testDir);
+        }
+    }
+    // Also check project-level test directories
+    const projectTestDirs = [
+        resolve(projectRoot, 'tests'),
+        resolve(projectRoot, 'test'),
+        resolve(projectRoot, '__tests__'),
+    ];
+    for (const testDir of projectTestDirs) {
+        if (dirsToScan.includes(testDir))
+            continue;
+        const testDirStat = await stat(testDir).catch(() => null);
+        if (testDirStat?.isDirectory()) {
+            dirsToScan.push(testDir);
+        }
+    }
+    for (const dir of dirsToScan) {
+        try {
+            const entries = await readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile())
+                    continue;
+                const name = entry.name;
+                if (name.includes('.test.') || name.includes('.spec.') || name.includes('_test.') || name.includes('_spec.')) {
+                    // Check if this test corresponds to an area file
+                    const testBase = name
+                        .replace(/\.(test|spec)\./, '.')
+                        .replace(/_(test|spec)\./, '.')
+                        .replace(/\.[^.]+$/, '');
+                    if (areaFileNames.has(testBase) || dir !== absPath) {
+                        const relPath = relative(projectRoot, resolve(dir, name));
+                        if (!testFiles.includes(relPath)) {
+                            testFiles.push(relPath);
+                        }
+                    }
+                }
+            }
+        }
+        catch { /* skip unreadable dirs */ }
+    }
+    if (testFiles.length === 0)
+        return [];
+    const lines = [];
+    lines.push(`TESTS: ${testFiles.join(', ')}`);
+    lines.push('');
+    return lines;
+}
+// ──────────────────────────────────────────────
+// Changes section — recent git log for this area
+// ──────────────────────────────────────────────
+async function buildChangesSection(relDir, projectRoot) {
+    try {
+        const { stdout } = await execFileAsync('git', ['log', '--oneline', '-5', '--', relDir], { cwd: projectRoot, timeout: 5000 });
+        if (!stdout.trim())
+            return [];
+        const lines = [];
+        lines.push('RECENT CHANGES:');
+        for (const line of stdout.trim().split('\n')) {
+            lines.push(`  ${line}`);
+        }
+        lines.push('');
+        return lines;
+    }
+    catch {
+        return [];
+    }
+}
+// ──────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────
+function extractResult(settled) {
+    if (settled.status === 'fulfilled' && settled.value && settled.value.length > 0) {
+        return settled.value;
+    }
+    return null;
+}
+async function listCodeFiles(dirPath) {
+    try {
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        const files = [];
+        for (const entry of entries) {
+            if (entry.isFile()) {
+                const ext = entry.name.split('.').pop()?.toLowerCase() ?? '';
+                if (CODE_EXTENSIONS.has(ext)) {
+                    files.push(resolve(dirPath, entry.name));
+                }
+            }
+        }
+        return files.sort();
+    }
+    catch {
+        return [];
+    }
+}
+async function countSubdirs(dirPath) {
+    try {
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        return entries.filter(e => e.isDirectory()).length;
+    }
+    catch {
+        return 0;
+    }
+}
+//# sourceMappingURL=explore-area.js.map

package/dist/handlers/outline.d.ts

@@ -1,9 +1,15 @@
 import type { AstIndexClient } from '../ast-index/client.js';
 import type { OutlineArgs } from '../core/validation.js';
+export declare const CODE_EXTENSIONS: Set<string>;
 export declare function handleOutline(args: OutlineArgs, projectRoot: string, astIndex: AstIndexClient): Promise<{
     content: Array<{
         type: 'text';
         text: string;
     }>;
 }>;
+/**
+ * Outline a single directory. When depth < maxDepth and recursive,
+ * recurse into subdirectories. Otherwise show file counts only.
+ */
+export declare function outlineDir(absPath: string, sections: string[], depth: number, maxDepth: number, projectRoot: string, astIndex: AstIndexClient): Promise<void>;
 //# sourceMappingURL=outline.d.ts.map

package/dist/handlers/outline.js

@@ -1,7 +1,7 @@
 import { readdir, stat } from 'node:fs/promises';
 import { resolve, basename, relative } from 'node:path';
 import { resolveSafePath } from '../core/validation.js';
-const CODE_EXTENSIONS = new Set([
+export const CODE_EXTENSIONS = new Set([
     'ts', 'tsx', 'js', 'jsx', 'mjs', 'py', 'go', 'rs', 'java', 'kt', 'kts',
     'swift', 'cs', 'cpp', 'cc', 'cxx', 'hpp', 'c', 'h', 'php', 'rb', 'scala',
     'dart', 'lua', 'sh', 'bash', 'sql', 'r', 'vue', 'svelte', 'pl', 'pm',
@@ -35,7 +35,7 @@ const MAX_OUTLINE_LINES = 500;
  * Outline a single directory. When depth < maxDepth and recursive,
  * recurse into subdirectories. Otherwise show file counts only.
  */
-async function outlineDir(absPath, sections, depth, maxDepth, projectRoot, astIndex) {
+export async function outlineDir(absPath, sections, depth, maxDepth, projectRoot, astIndex) {
     // Guard: stop if output is already too large
     if (sections.length >= MAX_OUTLINE_LINES) {
         if (!sections[sections.length - 1]?.startsWith('⚠')) {

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

@@ -0,0 +1,35 @@
+import type { AstIndexClient } from '../ast-index/client.js';
+import type { SmartDiffArgs } from '../core/validation.js';
+import type { FileStructure } from '../types.js';
+interface FileDiff {
+    path: string;
+    oldPath?: string;
+    addedLines: number;
+    removedLines: number;
+    hunks: DiffHunk[];
+    isBinary: boolean;
+    isNew: boolean;
+    isDeleted: boolean;
+}
+interface DiffHunk {
+    newStart: number;
+    newCount: number;
+    lines: string[];
+}
+interface SymbolChange {
+    name: string;
+    kind: string;
+    changeType: 'MODIFIED' | 'ADDED' | 'REMOVED';
+    lineRange: string;
+}
+export declare function handleSmartDiff(args: SmartDiffArgs, projectRoot: string, astIndex: AstIndexClient): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    rawTokens: number;
+}>;
+export declare function parseUnifiedDiff(raw: string): FileDiff[];
+export declare function mapHunksToSymbols(hunks: DiffHunk[], structure: FileStructure): SymbolChange[];
+export {};
+//# sourceMappingURL=smart-diff.d.ts.map

package/dist/handlers/smart-diff.js

@@ -0,0 +1,257 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { resolve } from 'node:path';
+import { estimateTokens } from '../core/token-estimator.js';
+const execFileAsync = promisify(execFile);
+// ──────────────────────────────────────────────
+// Handler
+// ──────────────────────────────────────────────
+const SMALL_DIFF_THRESHOLD = 30;
+const MAX_FILES = 50;
+const MAX_OUTPUT_LINES = 500;
+export async function handleSmartDiff(args, projectRoot, astIndex) {
+    // 1. Build git command
+    const gitArgs = buildGitArgs(args, projectRoot);
+    // 2. Execute git diff
+    let rawDiff;
+    try {
+        const { stdout } = await execFileAsync('git', gitArgs, {
+            cwd: projectRoot,
+            timeout: 10000,
+            maxBuffer: 5 * 1024 * 1024,
+        });
+        rawDiff = stdout;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('not a git repository') || msg.includes('fatal:')) {
+            return { content: [{ type: 'text', text: 'Not a git repository. smart_diff requires git.' }], rawTokens: 0 };
+        }
+        return { content: [{ type: 'text', text: `git diff failed: ${msg}` }], rawTokens: 0 };
+    }
+    const rawTokens = estimateTokens(rawDiff);
+    if (!rawDiff.trim()) {
+        const scopeLabel = args.scope ?? 'unstaged';
+        return {
+            content: [{ type: 'text', text: `NO CHANGES (${scopeLabel}): working tree is clean.` }],
+            rawTokens: 0,
+        };
+    }
+    // 3. Parse unified diff
+    const fileDiffs = parseUnifiedDiff(rawDiff);
+    if (fileDiffs.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'NO CHANGES: diff parsed but no file changes found.' }],
+            rawTokens,
+        };
+    }
+    // 4. Map hunks to symbols (parallel, capped)
+    const filesToProcess = fileDiffs.slice(0, MAX_FILES);
+    const symbolChanges = new Map();
+    const outlineResults = await Promise.allSettled(filesToProcess
+        .filter(f => !f.isBinary && !f.isDeleted)
+        .map(async (f) => {
+        const absPath = resolve(projectRoot, f.path);
+        const structure = await astIndex.outline(absPath);
+        return { path: f.path, structure };
+    }));
+    for (const result of outlineResults) {
+        if (result.status === 'fulfilled' && result.value.structure) {
+            const { path, structure } = result.value;
+            const fd = filesToProcess.find(f => f.path === path);
+            if (fd) {
+                symbolChanges.set(path, mapHunksToSymbols(fd.hunks, structure));
+            }
+        }
+    }
+    // 5. Format output
+    const output = formatSmartDiff(fileDiffs, filesToProcess, symbolChanges, args, rawTokens);
+    return { content: [{ type: 'text', text: output }], rawTokens };
+}
+// ──────────────────────────────────────────────
+// Git command builder
+// ──────────────────────────────────────────────
+function buildGitArgs(args, projectRoot) {
+    const base = [];
+    switch (args.scope) {
+        case 'staged':
+            base.push('diff', '--cached');
+            break;
+        case 'commit':
+            base.push('show', '--format=', args.ref);
+            break;
+        case 'branch':
+            base.push('diff', `${args.ref}...HEAD`);
+            break;
+        case 'unstaged':
+        default:
+            base.push('diff');
+            break;
+    }
+    if (args.path) {
+        base.push('--', args.path);
+    }
+    return base;
+}
+// ──────────────────────────────────────────────
+// Unified diff parser
+// ──────────────────────────────────────────────
+export function parseUnifiedDiff(raw) {
+    const files = [];
+    let current = null;
+    let currentHunk = null;
+    for (const line of raw.split('\n')) {
+        // New file
+        if (line.startsWith('diff --git ')) {
+            if (current)
+                files.push(current);
+            const match = line.match(/diff --git a\/(.+?) b\/(.+)/);
+            current = {
+                path: match?.[2] ?? '',
+                oldPath: match?.[1] !== match?.[2] ? match?.[1] : undefined,
+                addedLines: 0,
+                removedLines: 0,
+                hunks: [],
+                isBinary: false,
+                isNew: false,
+                isDeleted: false,
+            };
+            currentHunk = null;
+            continue;
+        }
+        if (!current)
+            continue;
+        if (line.startsWith('new file mode')) {
+            current.isNew = true;
+        }
+        else if (line.startsWith('deleted file mode')) {
+            current.isDeleted = true;
+        }
+        else if (line.startsWith('Binary files')) {
+            current.isBinary = true;
+        }
+        else if (line.startsWith('rename from ')) {
+            current.oldPath = line.slice(12);
+        }
+        else if (line.startsWith('@@ ')) {
+            const match = line.match(/@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+            currentHunk = {
+                newStart: match ? parseInt(match[1], 10) : 0,
+                newCount: match?.[2] ? parseInt(match[2], 10) : 1,
+                lines: [],
+            };
+            current.hunks.push(currentHunk);
+        }
+        else if (currentHunk) {
+            if (line.startsWith('+') && !line.startsWith('+++')) {
+                current.addedLines++;
+                currentHunk.lines.push(line);
+            }
+            else if (line.startsWith('-') && !line.startsWith('---')) {
+                current.removedLines++;
+                currentHunk.lines.push(line);
+            }
+            else if (line.startsWith(' ')) {
+                currentHunk.lines.push(line);
+            }
+        }
+    }
+    if (current)
+        files.push(current);
+    return files;
+}
+// ──────────────────────────────────────────────
+// Symbol mapping
+// ──────────────────────────────────────────────
+function flattenSymbols(symbols, prefix = '') {
+    const result = [];
+    for (const sym of symbols) {
+        const name = prefix ? `${prefix}.${sym.name}` : sym.name;
+        result.push({
+            name,
+            kind: sym.kind,
+            start: sym.location.startLine,
+            end: sym.location.endLine,
+        });
+        if (sym.children.length > 0) {
+            result.push(...flattenSymbols(sym.children, sym.kind === 'class' || sym.kind === 'interface' ? sym.name : ''));
+        }
+    }
+    return result;
+}
+export function mapHunksToSymbols(hunks, structure) {
+    const allSymbols = flattenSymbols(structure.symbols);
+    const changedSymbols = new Map();
+    for (const hunk of hunks) {
+        const hunkStart = hunk.newStart;
+        const hunkEnd = hunk.newStart + hunk.newCount - 1;
+        for (const sym of allSymbols) {
+            if (hunkStart <= sym.end && hunkEnd >= sym.start) {
+                if (!changedSymbols.has(sym.name)) {
+                    changedSymbols.set(sym.name, {
+                        name: sym.name,
+                        kind: sym.kind,
+                        changeType: 'MODIFIED',
+                        lineRange: `[L${sym.start}-${sym.end}]`,
+                    });
+                }
+            }
+        }
+    }
+    return Array.from(changedSymbols.values());
+}
+// ──────────────────────────────────────────────
+// Output formatter
+// ──────────────────────────────────────────────
+function formatSmartDiff(allFiles, processedFiles, symbolChanges, args, rawTokens) {
+    const totalAdded = allFiles.reduce((s, f) => s + f.addedLines, 0);
+    const totalRemoved = allFiles.reduce((s, f) => s + f.removedLines, 0);
+    const scopeLabel = args.scope ?? 'unstaged';
+    const lines = [];
+    lines.push(`CHANGES: ${allFiles.length} file${allFiles.length !== 1 ? 's' : ''}, +${totalAdded} -${totalRemoved} (${scopeLabel})`);
+    lines.push('');
+    for (const fd of processedFiles) {
+        if (lines.length >= MAX_OUTPUT_LINES) {
+            lines.push(`... truncated (${allFiles.length - processedFiles.indexOf(fd)} more files)`);
+            break;
+        }
+        // File header
+        const changeLabel = fd.isNew ? ' [NEW]' : fd.isDeleted ? ' [DELETED]' : '';
+        const renameLabel = fd.oldPath ? ` (renamed from ${fd.oldPath})` : '';
+        const binaryLabel = fd.isBinary ? ' [BINARY]' : '';
+        lines.push(`${fd.path} (+${fd.addedLines} -${fd.removedLines})${changeLabel}${renameLabel}${binaryLabel}`);
+        if (fd.isBinary) {
+            lines.push('');
+            continue;
+        }
+        // Symbol changes
+        const symbols = symbolChanges.get(fd.path);
+        if (symbols && symbols.length > 0) {
+            for (const sc of symbols) {
+                lines.push(`  ${sc.changeType}: ${sc.name}() ${sc.lineRange}`);
+            }
+        }
+        // Small diff: include actual hunks
+        const totalHunkLines = fd.hunks.reduce((s, h) => s + h.lines.length, 0);
+        if (totalHunkLines <= SMALL_DIFF_THRESHOLD && totalHunkLines > 0) {
+            for (const hunk of fd.hunks) {
+                lines.push(`    @@ L${hunk.newStart}`);
+                for (const hl of hunk.lines) {
+                    lines.push(`    ${hl}`);
+                }
+            }
+        }
+        else if (totalHunkLines > SMALL_DIFF_THRESHOLD) {
+            lines.push(`  (${totalHunkLines} lines changed — use read_symbol for details)`);
+        }
+        lines.push('');
+    }
+    if (allFiles.length > MAX_FILES) {
+        lines.push(`Showing ${MAX_FILES} of ${allFiles.length} changed files. Use path filter to narrow.`);
+        lines.push('');
+    }
+    lines.push(`HINT: Use read_symbol(path, symbol) to see full changed code, read_diff(path) for line-level diff.`);
+    lines.push(`RAW DIFF: ~${rawTokens} tokens → smart_diff: ~${estimateTokens(lines.join('\n'))} tokens`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=smart-diff.js.map

package/dist/server.js

@@ -28,9 +28,11 @@ import { handleRelatedFiles } from './handlers/related-files.js';
 import { handleOutline } from './handlers/outline.js';
 import { handleCodeAudit } from './handlers/code-audit.js';
 import { handleModuleInfo } from './handlers/module-info.js';
+import { handleSmartDiff } from './handlers/smart-diff.js';
+import { handleExploreArea } from './handlers/explore-area.js';
 import { detectContextMode } from './integration/context-mode-detector.js';
 import { estimateTokens } from './core/token-estimator.js';
-import { resolveSafePath, validateSmartReadArgs, validateReadSymbolArgs, validateReadRangeArgs, validateReadDiffArgs, validateFindUsagesArgs, validateSmartReadManyArgs, validateReadForEditArgs, validateRelatedFilesArgs, validateOutlineArgs, validateFindUnusedArgs, validateCodeAuditArgs, validateProjectOverviewArgs, validateModuleInfoArgs, } from './core/validation.js';
+import { resolveSafePath, validateSmartReadArgs, validateReadSymbolArgs, validateReadRangeArgs, validateReadDiffArgs, validateFindUsagesArgs, validateSmartReadManyArgs, validateReadForEditArgs, validateRelatedFilesArgs, validateOutlineArgs, validateFindUnusedArgs, validateCodeAuditArgs, validateProjectOverviewArgs, validateModuleInfoArgs, validateSmartDiffArgs, validateExploreAreaArgs, } from './core/validation.js';
 export async function createServer(projectRoot, options) {
     const config = await loadConfig(projectRoot);
     const astIndex = new AstIndexClient(projectRoot, config.astIndex.timeout, {
@@ -183,6 +185,8 @@ export async function createServer(projectRoot, options) {
             '• Reading file again → smart_read (returns compact reminder, not full content)',
             '• Multiple files → smart_read_many (batch, max 20)',
             '• Code quality audit → code_audit (TODOs, deprecated, structural code patterns)',
+            '• Reviewing git changes → smart_diff (structural diff with symbol mapping, not raw patch)',
+            '• Starting work on an area → explore_area (outline + imports + tests + git log in one call)',
             '',
             'WHEN TO USE DEFAULT TOOLS (Token Pilot adds no value):',
             '• Small files (≤200 lines) → smart_read returns full content anyway, same as Read',
@@ -201,7 +205,7 @@ export async function createServer(projectRoot, options) {
             '• Deep dive into specific code → read_symbol (after finding issues)',
             '• Module architecture → module_info (deps, dependents, public API, unused deps)',
             '',
-            'WORKFLOW: project_overview → smart_read → read_symbol → read_for_edit → edit → read_diff',
+            'WORKFLOW: project_overview → explore_area → smart_read → read_symbol → read_for_edit → edit → smart_diff',
         ].join('\n'),
     });
     server.setRequestHandler(ListToolsRequestSchema, () => ({
@@ -401,6 +405,35 @@ export async function createServer(projectRoot, options) {
                     required: ['module'],
                 },
             },
+            // --- Diff & exploration ---
+            {
+                name: 'smart_diff',
+                description: 'Use INSTEAD OF raw git diff. Shows changed files with AST symbol mapping — which functions/classes were modified/added/removed. Small diffs include hunks, large diffs show summary.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        scope: { type: 'string', enum: ['unstaged', 'staged', 'commit', 'branch'], description: 'Diff scope (default: "unstaged")' },
+                        path: { type: 'string', description: 'Filter to specific file or directory' },
+                        ref: { type: 'string', description: 'Git ref — required for scope="commit" (commit hash) or scope="branch" (branch name)' },
+                    },
+                },
+            },
+            {
+                name: 'explore_area',
+                description: 'One-call exploration of a directory: outline (all symbols), imports (external deps + who imports this area), tests (matching test files), recent git changes. Use INSTEAD OF separate outline + related_files + git log calls.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        path: { type: 'string', description: 'Directory path (or file path — will use its parent directory)' },
+                        include: {
+                            type: 'array',
+                            items: { type: 'string', enum: ['outline', 'imports', 'tests', 'changes'] },
+                            description: 'Sections to include (default: all)',
+                        },
+                    },
+                    required: ['path'],
+                },
+            },
         ],
     }));
     // Helper: get real full-file token count for honest analytics
@@ -553,6 +586,24 @@ export async function createServer(projectRoot, options) {
                     analytics.record({ tool: 'module_info', path: moduleArgs.module, tokensReturned: estimateTokens(moduleText), tokensWouldBe: moduleWouldBe, timestamp: Date.now() });
                     return moduleResult;
                 }
+                case 'smart_diff': {
+                    const sdArgs = validateSmartDiffArgs(args);
+                    const sdResult = await handleSmartDiff(sdArgs, projectRoot, astIndex);
+                    const sdText = sdResult.content[0]?.text ?? '';
+                    const sdTokens = estimateTokens(sdText);
+                    analytics.record({ tool: 'smart_diff', path: sdArgs.path ?? sdArgs.scope ?? 'unstaged', tokensReturned: sdTokens, tokensWouldBe: sdResult.rawTokens || sdTokens, timestamp: Date.now() });
+                    return { content: sdResult.content };
+                }
+                case 'explore_area': {
+                    const eaArgs = validateExploreAreaArgs(args);
+                    const eaResult = await handleExploreArea(eaArgs, projectRoot, astIndex);
+                    const eaText = eaResult.content[0]?.text ?? '';
+                    const eaTokens = estimateTokens(eaText);
+                    // Without explore_area, agent would call: outline + related_files + git log = ~3-5x tokens
+                    const eaWouldBe = eaTokens * 4;
+                    analytics.record({ tool: 'explore_area', path: eaArgs.path, tokensReturned: eaTokens, tokensWouldBe: eaWouldBe, timestamp: Date.now() });
+                    return eaResult;
+                }
                 default:
                     return {
                         content: [{ type: 'text', text: `Unknown tool: ${name}` }],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Save 60-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",