token-pilot 0.13.0 → 0.14.2

package/dist/server.js

@@ -5,9 +5,12 @@ import { FileCache } from './core/file-cache.js';
 import { ContextRegistry } from './core/context-registry.js';
 import { SymbolResolver } from './core/symbol-resolver.js';
 import { SessionAnalytics } from './core/session-analytics.js';
+import { classifyIntent } from './core/intent-classifier.js';
+import { buildDecisionTrace } from './core/decision-trace.js';
+import { SessionCache } from './core/session-cache.js';
 import { loadConfig } from './config/loader.js';
 import { readFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { execFile } from 'node:child_process';
 import { isDangerousRoot } from './core/validation.js';
 import { promisify } from 'node:util';
@@ -25,7 +28,7 @@ import { handleNonCodeRead, isNonCodeStructured } from './handlers/non-code.js';
 import { handleFindUnused } from './handlers/find-unused.js';
 import { handleReadForEdit } from './handlers/read-for-edit.js';
 import { handleRelatedFiles } from './handlers/related-files.js';
-import { handleOutline } from './handlers/outline.js';
+import { handleOutline, CODE_EXTENSIONS } 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';
@@ -34,6 +37,7 @@ import { handleSmartLog } from './handlers/smart-log.js';
 import { handleTestSummary } from './handlers/test-summary.js';
 import { detectContextMode } from './integration/context-mode-detector.js';
 import { estimateTokens } from './core/token-estimator.js';
+import { checkPolicy, isFullReadTool } from './core/policy-engine.js';
 import { resolveSafePath, validateSmartReadArgs, validateReadSymbolArgs, validateReadRangeArgs, validateReadDiffArgs, validateFindUsagesArgs, validateSmartReadManyArgs, validateReadForEditArgs, validateRelatedFilesArgs, validateOutlineArgs, validateFindUnusedArgs, validateCodeAuditArgs, validateProjectOverviewArgs, validateModuleInfoArgs, validateSmartDiffArgs, validateExploreAreaArgs, validateSmartLogArgs, validateTestSummaryArgs, } from './core/validation.js';
 export async function createServer(projectRoot, options) {
     const config = await loadConfig(projectRoot);
@@ -139,6 +143,13 @@ export async function createServer(projectRoot, options) {
     }
     // Session analytics
     const analytics = new SessionAnalytics();
+    // Session cache (tool-result-level caching, invalidated by file/AST/git changes)
+    const sessionCache = config.sessionCache.enabled
+        ? new SessionCache(config.sessionCache.maxEntries)
+        : null;
+    // Policy engine state
+    let fullFileReadsCount = 0;
+    const readForEditCalled = new Set();
     // Detect context-mode companion
     const cmEnabled = config.contextMode.enabled;
     const contextModeStatus = await detectContextMode(projectRoot, cmEnabled === 'auto' ? undefined : cmEnabled);
@@ -161,6 +172,17 @@ export async function createServer(projectRoot, options) {
         fileWatcher = new FileWatcher(projectRoot, fileCache, contextRegistry, config.ignore, astIndex);
         fileWatcher.start();
         fileCache.onSet((filePath) => fileWatcher?.watchFile(filePath));
+        if (sessionCache) {
+            fileWatcher.onFileChange((absPath) => sessionCache.invalidateByFiles([absPath]));
+            fileWatcher.onAstUpdate(() => sessionCache.invalidateByAst());
+        }
+    }
+    // Wire session cache to git watcher
+    if (sessionCache) {
+        gitWatcher.onBranchSwitchEvent((changedFiles) => {
+            sessionCache.invalidateByFiles(changedFiles);
+            sessionCache.invalidateByGit();
+        });
     }
     // Read version from package.json
     let pkgVersion = '0.1.1';
@@ -271,7 +293,7 @@ export async function createServer(projectRoot, options) {
             },
             {
                 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.',
+                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. Optional: include_callers, include_tests, include_changes for enriched context.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -279,6 +301,9 @@ export async function createServer(projectRoot, options) {
                         symbol: { type: 'string', description: 'Symbol name to edit (e.g. "UserService.updateUser")' },
                         line: { type: 'number', description: 'Line number to edit (alternative to symbol)' },
                         context: { type: 'number', description: 'Lines of context around target (default: 5)' },
+                        include_callers: { type: 'boolean', description: 'Show top callers of this symbol (saves a separate find_usages call)' },
+                        include_tests: { type: 'boolean', description: 'Show related test file and test names' },
+                        include_changes: { type: 'boolean', description: 'Show recent git changes in the target region' },
                     },
                     required: ['path'],
                 },
@@ -330,7 +355,7 @@ export async function createServer(projectRoot, options) {
             },
             {
                 name: 'related_files',
-                description: 'Show import graph for a file: what it imports, what imports it, and test files. Understand dependencies before refactoring.',
+                description: 'Show ranked import graph for a file: imports, importers, and tests scored by relevance (test adjacency, import closeness, recent changes, path proximity). Files ranked into HIGH VALUE / MEDIUM / LOW to prioritize reading.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -480,6 +505,205 @@ export async function createServer(projectRoot, options) {
             return 0;
         }
     }
+    async function estimateProjectOverviewWorkflowTokens(includeSections) {
+        const sectionFiles = {
+            stack: ['package.json', 'composer.json', 'Cargo.toml', 'pyproject.toml', 'go.mod'],
+            ci: ['.gitlab-ci.yml', 'Jenkinsfile', '.circleci/config.yml', 'bitbucket-pipelines.yml', '.travis.yml'],
+            quality: [
+                'tsconfig.json',
+                'vitest.config.ts',
+                'vitest.config.js',
+                'vitest.config.mts',
+                'jest.config.js',
+                'jest.config.ts',
+                'jest.config.mjs',
+                'eslint.config.js',
+                'eslint.config.mjs',
+                '.eslintrc',
+                '.eslintrc.js',
+                '.eslintrc.json',
+                '.eslintrc.yml',
+                'biome.json',
+                'biome.jsonc',
+                '.prettierrc',
+                '.prettierrc.js',
+                '.prettierrc.json',
+                'prettier.config.js',
+                'phpunit.xml',
+                'phpunit.xml.dist',
+                'phpstan.neon',
+                'phpstan.neon.dist',
+            ],
+            architecture: ['README.md'],
+        };
+        let total = 0;
+        const seen = new Set();
+        for (const section of includeSections) {
+            for (const file of sectionFiles[section]) {
+                if (seen.has(file))
+                    continue;
+                seen.add(file);
+                total += await fullFileTokens(file);
+            }
+        }
+        if (includeSections.includes('ci')) {
+            try {
+                const { readdir: readDirAsync } = await import('node:fs/promises');
+                const workflowDir = resolveSafePath(projectRoot, '.github/workflows');
+                const workflowFiles = await readDirAsync(workflowDir, { withFileTypes: true });
+                for (const file of workflowFiles) {
+                    if (!file.isFile())
+                        continue;
+                    if (!file.name.endsWith('.yml') && !file.name.endsWith('.yaml'))
+                        continue;
+                    total += await fullFileTokens(`.github/workflows/${file.name}`);
+                }
+            }
+            catch {
+                // ignore missing workflows dir
+            }
+        }
+        if (includeSections.includes('architecture')) {
+            total += 200;
+        }
+        return total;
+    }
+    async function estimateOutlineWorkflowTokens(relativePath, recursive, maxDepth) {
+        const SAMPLE_LIMIT = 30;
+        try {
+            const { readdir: readDirAsync } = await import('node:fs/promises');
+            const { resolve: resolvePath } = await import('node:path');
+            const absDir = resolveSafePath(projectRoot, relativePath);
+            const sampledFiles = [];
+            let totalFiles = 0;
+            async function walk(dirPath, depth) {
+                const entries = await readDirAsync(dirPath, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.isFile()) {
+                        const ext = entry.name.split('.').pop()?.toLowerCase() ?? '';
+                        if (!CODE_EXTENSIONS.has(ext))
+                            continue;
+                        totalFiles++;
+                        if (sampledFiles.length < SAMPLE_LIMIT) {
+                            sampledFiles.push(resolvePath(dirPath, entry.name));
+                        }
+                        continue;
+                    }
+                    if (entry.isDirectory() && recursive && depth < maxDepth) {
+                        await walk(resolvePath(dirPath, entry.name), depth + 1);
+                    }
+                }
+            }
+            await walk(absDir, 0);
+            if (totalFiles === 0)
+                return 0;
+            let sampledTokens = 0;
+            for (const filePath of sampledFiles) {
+                const relPath = filePath.startsWith(projectRoot)
+                    ? filePath.slice(projectRoot.length + 1)
+                    : filePath;
+                sampledTokens += await fullFileTokens(relPath);
+            }
+            if (sampledFiles.length === 0 || sampledTokens === 0)
+                return 0;
+            if (sampledFiles.length === totalFiles)
+                return sampledTokens;
+            const averageTokens = sampledTokens / sampledFiles.length;
+            return Math.round(averageTokens * totalFiles);
+        }
+        catch {
+            return 0;
+        }
+    }
+    async function estimateRelatedFilesWorkflowTokens(targetPath, meta) {
+        const related = new Set([targetPath]);
+        for (const path of meta?.imports ?? [])
+            related.add(path);
+        for (const path of meta?.importedBy ?? [])
+            related.add(path);
+        for (const path of meta?.tests ?? [])
+            related.add(path);
+        let total = 0;
+        let counted = 0;
+        for (const path of related) {
+            total += await fullFileTokens(path);
+            counted++;
+            if (counted >= 12)
+                break;
+        }
+        return total;
+    }
+    async function estimateFindUsagesWorkflowTokens(files) {
+        let total = 0;
+        let counted = 0;
+        for (const file of files) {
+            total += await fullFileTokens(file);
+            counted++;
+            if (counted >= 20)
+                break;
+        }
+        return total;
+    }
+    /** Detect savings category from response text prefix. */
+    function detectSavingsCategory(text) {
+        if (text.startsWith('REMINDER:') || text.startsWith('DEDUP:'))
+            return 'dedup';
+        return 'compression';
+    }
+    /** Record analytics with intent classification and decision trace. Returns policy advisory if any. */
+    function recordWithTrace(call) {
+        const { absPath, args, recentlyEdited, ...rest } = call;
+        analytics.record({
+            ...rest,
+            intent: classifyIntent(rest.tool),
+            decisionTrace: buildDecisionTrace({
+                absPath,
+                tool: rest.tool,
+                args: (args ?? {}),
+                contextRegistry,
+                fileCache,
+                tokensReturned: rest.tokensReturned,
+                tokensWouldBe: rest.tokensWouldBe,
+                recentlyEdited,
+            }),
+        });
+        // Policy tracking
+        if (isFullReadTool(rest.tool)) {
+            fullFileReadsCount++;
+        }
+        if (rest.tool === 'read_for_edit' && call.path) {
+            readForEditCalled.add(call.path);
+        }
+        // Policy check
+        const advisory = checkPolicy(config.policies, rest.tool, {
+            fullFileReadsCount,
+            tokensReturned: rest.tokensReturned,
+            readForEditCalled,
+        });
+        return advisory ? `\n${advisory.message}` : null;
+    }
+    async function estimateExploreAreaWorkflowTokens(meta) {
+        const localFiles = new Set();
+        for (const file of meta.codeFiles ?? [])
+            localFiles.add(file);
+        for (const file of meta.testFiles ?? [])
+            localFiles.add(file);
+        for (const file of meta.internalDeps ?? [])
+            localFiles.add(file);
+        for (const file of meta.importedBy ?? [])
+            localFiles.add(file);
+        let total = 0;
+        let counted = 0;
+        for (const file of localFiles) {
+            total += await fullFileTokens(file);
+            counted++;
+            if (counted >= 24)
+                break;
+        }
+        total += (meta.externalDeps?.length ?? 0) * 30;
+        total += (meta.changeCount ?? 0) * 40;
+        return total;
+    }
     // Handle tool calls with validated arguments
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
@@ -502,32 +726,44 @@ export async function createServer(projectRoot, options) {
                         });
                         if (nonCodeResult) {
                             const text = nonCodeResult.content[0]?.text ?? '';
-                            analytics.record({ tool: 'smart_read', path: validArgs.path, tokensReturned: estimateTokens(text), tokensWouldBe: estimateTokens(text), timestamp: Date.now() });
+                            recordWithTrace({
+                                tool: 'smart_read',
+                                path: validArgs.path,
+                                tokensReturned: estimateTokens(text),
+                                tokensWouldBe: await fullFileTokens(validArgs.path) || estimateTokens(text),
+                                timestamp: Date.now(),
+                                delegatedToContextMode: text.includes('ADVISORY:') && text.includes('context-mode'),
+                                savingsCategory: 'compression',
+                                absPath: resolve(projectRoot, validArgs.path),
+                                args: validArgs,
+                            });
                             return nonCodeResult;
                         }
                     }
                     const result = await handleSmartRead(validArgs, projectRoot, astIndex, fileCache, contextRegistry, config);
                     const text = result.content[0]?.text ?? '';
                     const fullTokensSR = await fullFileTokens(validArgs.path);
-                    analytics.record({ tool: 'smart_read', path: validArgs.path, tokensReturned: estimateTokens(text), tokensWouldBe: fullTokensSR || estimateTokens(text), timestamp: Date.now() });
+                    const policyAdv = recordWithTrace({ tool: 'smart_read', path: validArgs.path, tokensReturned: estimateTokens(text), tokensWouldBe: fullTokensSR || estimateTokens(text), timestamp: Date.now(), savingsCategory: detectSavingsCategory(text), absPath: resolve(projectRoot, validArgs.path), args: validArgs });
+                    if (policyAdv)
+                        result.content[0] = { type: 'text', text: text + policyAdv };
                     return result;
                 }
                 case 'read_symbol': {
                     const symArgs = validateReadSymbolArgs(args);
-                    const symResult = await handleReadSymbol(symArgs, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex);
+                    const symResult = await handleReadSymbol(symArgs, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex, config.smartRead.advisoryReminders);
                     const symText = symResult.content[0]?.text ?? '';
                     const symTokens = estimateTokens(symText);
                     const fullTokensSym = await fullFileTokens(symArgs.path);
-                    analytics.record({ tool: 'read_symbol', path: symArgs.path, tokensReturned: symTokens, tokensWouldBe: fullTokensSym || symTokens, timestamp: Date.now() });
+                    recordWithTrace({ tool: 'read_symbol', path: symArgs.path, tokensReturned: symTokens, tokensWouldBe: fullTokensSym || symTokens, timestamp: Date.now(), savingsCategory: detectSavingsCategory(symText), absPath: resolve(projectRoot, symArgs.path), args: symArgs });
                     return symResult;
                 }
                 case 'read_range': {
                     const rangeArgs = validateReadRangeArgs(args);
-                    const rangeResult = await handleReadRange(rangeArgs, projectRoot, fileCache, contextRegistry);
+                    const rangeResult = await handleReadRange(rangeArgs, projectRoot, fileCache, contextRegistry, config.smartRead.advisoryReminders);
                     const rangeText = rangeResult.content[0]?.text ?? '';
                     const rangeTokens = estimateTokens(rangeText);
                     const fullTokensRange = await fullFileTokens(rangeArgs.path);
-                    analytics.record({ tool: 'read_range', path: rangeArgs.path, tokensReturned: rangeTokens, tokensWouldBe: fullTokensRange || rangeTokens, timestamp: Date.now() });
+                    recordWithTrace({ tool: 'read_range', path: rangeArgs.path, tokensReturned: rangeTokens, tokensWouldBe: fullTokensRange || rangeTokens, timestamp: Date.now(), savingsCategory: detectSavingsCategory(rangeText), absPath: resolve(projectRoot, rangeArgs.path), args: rangeArgs });
                     return rangeResult;
                 }
                 case 'read_diff': {
@@ -536,7 +772,7 @@ export async function createServer(projectRoot, options) {
                     const diffText = diffResult.content[0]?.text ?? '';
                     const diffTokens = estimateTokens(diffText);
                     const fullTokensDiff = await fullFileTokens(diffArgs.path);
-                    analytics.record({ tool: 'read_diff', path: diffArgs.path, tokensReturned: diffTokens, tokensWouldBe: fullTokensDiff || diffTokens, timestamp: Date.now() });
+                    recordWithTrace({ tool: 'read_diff', path: diffArgs.path, tokensReturned: diffTokens, tokensWouldBe: fullTokensDiff || diffTokens, timestamp: Date.now(), savingsCategory: 'compression', absPath: resolve(projectRoot, diffArgs.path), args: diffArgs });
                     return diffResult;
                 }
                 case 'read_for_edit': {
@@ -545,7 +781,7 @@ export async function createServer(projectRoot, options) {
                     const editText = editResult.content[0]?.text ?? '';
                     const editTokens = estimateTokens(editText);
                     const fullTokensEdit = await fullFileTokens(editArgs.path);
-                    analytics.record({ tool: 'read_for_edit', path: editArgs.path, tokensReturned: editTokens, tokensWouldBe: fullTokensEdit || editTokens, timestamp: Date.now() });
+                    recordWithTrace({ tool: 'read_for_edit', path: editArgs.path, tokensReturned: editTokens, tokensWouldBe: fullTokensEdit || editTokens, timestamp: Date.now(), savingsCategory: 'compression', absPath: resolve(projectRoot, editArgs.path), args: editArgs });
                     return editResult;
                 }
                 case 'smart_read_many': {
@@ -553,66 +789,178 @@ export async function createServer(projectRoot, options) {
                     const manyResult = await handleSmartReadMany(manyArgs, projectRoot, astIndex, fileCache, contextRegistry, config);
                     const manyText = manyResult.content[0]?.text ?? '';
                     const manyTokens = estimateTokens(manyText);
+                    const uniqueManyPaths = Array.from(new Set(manyArgs.paths));
                     let fullTokensMany = 0;
-                    for (const p of manyArgs.paths) {
+                    for (const p of uniqueManyPaths) {
                         fullTokensMany += await fullFileTokens(p);
                     }
-                    analytics.record({ tool: 'smart_read_many', path: manyArgs.paths.join(', '), tokensReturned: manyTokens, tokensWouldBe: fullTokensMany || manyTokens, timestamp: Date.now() });
+                    recordWithTrace({
+                        tool: 'smart_read_many',
+                        path: uniqueManyPaths.join(', '),
+                        tokensReturned: manyTokens,
+                        tokensWouldBe: fullTokensMany || manyTokens,
+                        timestamp: Date.now(),
+                        savingsCategory: 'compression',
+                        args: manyArgs,
+                    });
                     return manyResult;
                 }
                 case 'find_usages': {
                     const usagesArgs = validateFindUsagesArgs(args);
+                    const cachedUsages = sessionCache?.get('find_usages', usagesArgs);
+                    if (cachedUsages) {
+                        recordWithTrace({ tool: 'find_usages', path: usagesArgs.symbol, tokensReturned: cachedUsages.tokenEstimate, tokensWouldBe: cachedUsages.tokensWouldBe ?? cachedUsages.tokenEstimate, timestamp: Date.now(), sessionCacheHit: true, savingsCategory: 'cache', args: usagesArgs });
+                        return cachedUsages.result;
+                    }
                     const usagesResult = await handleFindUsages(usagesArgs, astIndex);
                     const usagesText = usagesResult.content[0]?.text ?? '';
-                    analytics.record({ tool: 'find_usages', path: usagesArgs.symbol, tokensReturned: estimateTokens(usagesText), tokensWouldBe: estimateTokens(usagesText), timestamp: Date.now() });
+                    const usagesTokens = estimateTokens(usagesText);
+                    const usagesWouldBe = await estimateFindUsagesWorkflowTokens(usagesResult.meta.files);
+                    sessionCache?.set('find_usages', usagesArgs, usagesResult, {
+                        files: usagesResult.meta.files.map(f => resolve(projectRoot, f)),
+                        dependsOnAst: true,
+                    }, usagesTokens, usagesWouldBe || usagesTokens);
+                    recordWithTrace({
+                        tool: 'find_usages',
+                        path: usagesArgs.symbol,
+                        tokensReturned: usagesTokens,
+                        tokensWouldBe: usagesWouldBe || usagesTokens,
+                        timestamp: Date.now(),
+                        savingsCategory: 'compression',
+                        args: usagesArgs,
+                    });
                     return usagesResult;
                 }
                 case 'project_overview': {
                     const overviewArgs = validateProjectOverviewArgs(args);
-                    const overviewResult = await handleProjectOverview(overviewArgs, projectRoot, astIndex);
+                    const cachedOverview = sessionCache?.get('project_overview', overviewArgs);
+                    if (cachedOverview) {
+                        recordWithTrace({ tool: 'project_overview', path: projectRoot, tokensReturned: cachedOverview.tokenEstimate, tokensWouldBe: cachedOverview.tokensWouldBe ?? cachedOverview.tokenEstimate, timestamp: Date.now(), sessionCacheHit: true, savingsCategory: 'cache', args: overviewArgs });
+                        return cachedOverview.result;
+                    }
+                    const overviewResult = await handleProjectOverview(overviewArgs, projectRoot, astIndex, pkgVersion);
                     const overviewText = overviewResult.content[0]?.text ?? '';
                     overviewResult.content[0] = { type: 'text', text: `TOKEN PILOT v${pkgVersion}\n\n${overviewText}` };
                     const ovTokens = estimateTokens(overviewResult.content[0].text);
-                    analytics.record({ tool: 'project_overview', path: projectRoot, tokensReturned: ovTokens, tokensWouldBe: ovTokens, timestamp: Date.now() });
+                    const overviewWouldBe = await estimateProjectOverviewWorkflowTokens(overviewArgs.include ?? ['stack', 'ci', 'quality', 'architecture']);
+                    sessionCache?.set('project_overview', overviewArgs, overviewResult, {
+                        dependsOnAst: true,
+                    }, ovTokens, overviewWouldBe || ovTokens);
+                    recordWithTrace({
+                        tool: 'project_overview',
+                        path: projectRoot,
+                        tokensReturned: ovTokens,
+                        tokensWouldBe: overviewWouldBe || ovTokens,
+                        timestamp: Date.now(),
+                        savingsCategory: 'compression',
+                        args: overviewArgs,
+                    });
                     return overviewResult;
                 }
                 case 'related_files': {
                     const relArgs = validateRelatedFilesArgs(args);
+                    const cachedRel = sessionCache?.get('related_files', relArgs);
+                    if (cachedRel) {
+                        recordWithTrace({ tool: 'related_files', path: relArgs.path, tokensReturned: cachedRel.tokenEstimate, tokensWouldBe: cachedRel.tokensWouldBe ?? cachedRel.tokenEstimate, timestamp: Date.now(), sessionCacheHit: true, savingsCategory: 'cache', absPath: resolve(projectRoot, relArgs.path), args: relArgs });
+                        return cachedRel.result;
+                    }
                     const relResult = await handleRelatedFiles(relArgs, projectRoot, astIndex);
                     const relText = relResult.content[0]?.text ?? '';
-                    analytics.record({ tool: 'related_files', path: relArgs.path, tokensReturned: estimateTokens(relText), tokensWouldBe: estimateTokens(relText), timestamp: Date.now() });
+                    const relTokens = estimateTokens(relText);
+                    const relWouldBe = await estimateRelatedFilesWorkflowTokens(relArgs.path, relResult.meta);
+                    const relDeps = [
+                        resolve(projectRoot, relArgs.path),
+                        ...relResult.meta.imports.map(f => resolve(projectRoot, f)),
+                        ...relResult.meta.importedBy.map(f => resolve(projectRoot, f)),
+                        ...relResult.meta.tests.map(f => resolve(projectRoot, f)),
+                    ];
+                    sessionCache?.set('related_files', relArgs, relResult, {
+                        files: relDeps,
+                        dependsOnAst: true,
+                    }, relTokens, relWouldBe || relTokens);
+                    recordWithTrace({
+                        tool: 'related_files',
+                        path: relArgs.path,
+                        tokensReturned: relTokens,
+                        tokensWouldBe: relWouldBe || relTokens,
+                        timestamp: Date.now(),
+                        savingsCategory: 'compression',
+                        absPath: resolve(projectRoot, relArgs.path),
+                        args: relArgs,
+                    });
                     return relResult;
                 }
                 case 'outline': {
                     const outlineArgs = validateOutlineArgs(args);
+                    const cachedOutline = sessionCache?.get('outline', outlineArgs);
+                    if (cachedOutline) {
+                        recordWithTrace({ tool: 'outline', path: outlineArgs.path, tokensReturned: cachedOutline.tokenEstimate, tokensWouldBe: cachedOutline.tokensWouldBe ?? cachedOutline.tokenEstimate, timestamp: Date.now(), sessionCacheHit: true, savingsCategory: 'cache', args: outlineArgs });
+                        return cachedOutline.result;
+                    }
                     const outlineResult = await handleOutline(outlineArgs, projectRoot, astIndex);
                     const outlineText = outlineResult.content[0]?.text ?? '';
-                    analytics.record({ tool: 'outline', path: outlineArgs.path, tokensReturned: estimateTokens(outlineText), tokensWouldBe: estimateTokens(outlineText), timestamp: Date.now() });
+                    const outlineTokens = estimateTokens(outlineText);
+                    const outlineWouldBe = await estimateOutlineWorkflowTokens(outlineArgs.path, outlineArgs.recursive ?? false, outlineArgs.max_depth ?? 2);
+                    sessionCache?.set('outline', outlineArgs, outlineResult, {
+                        files: [resolve(projectRoot, outlineArgs.path) + '/'],
+                        dependsOnAst: true,
+                    }, outlineTokens, outlineWouldBe || outlineTokens);
+                    recordWithTrace({
+                        tool: 'outline',
+                        path: outlineArgs.path,
+                        tokensReturned: outlineTokens,
+                        tokensWouldBe: outlineWouldBe || outlineTokens,
+                        timestamp: Date.now(),
+                        savingsCategory: 'compression',
+                        args: outlineArgs,
+                    });
                     return outlineResult;
                 }
                 case 'session_analytics':
                     return { content: [{ type: 'text', text: `TOKEN PILOT v${pkgVersion}\n\n${analytics.report()}` }] };
                 case 'find_unused': {
                     const unusedArgs = validateFindUnusedArgs(args);
+                    const cachedUnused = sessionCache?.get('find_unused', unusedArgs);
+                    if (cachedUnused) {
+                        recordWithTrace({ tool: 'find_unused', path: unusedArgs.module ?? 'all', tokensReturned: cachedUnused.tokenEstimate, tokensWouldBe: cachedUnused.tokensWouldBe ?? cachedUnused.tokenEstimate, timestamp: Date.now(), sessionCacheHit: true, savingsCategory: 'cache', args: unusedArgs });
+                        return cachedUnused.result;
+                    }
                     const unusedResult = await handleFindUnused(unusedArgs, astIndex);
                     const unusedText = unusedResult.content[0]?.text ?? '';
-                    analytics.record({ tool: 'find_unused', path: unusedArgs.module ?? 'all', tokensReturned: estimateTokens(unusedText), tokensWouldBe: estimateTokens(unusedText), timestamp: Date.now() });
+                    const unusedTokens = estimateTokens(unusedText);
+                    const unusedWouldBe = await estimateFindUsagesWorkflowTokens(unusedResult.meta.files);
+                    sessionCache?.set('find_unused', unusedArgs, unusedResult, { dependsOnAst: true }, unusedTokens, unusedWouldBe || unusedTokens);
+                    recordWithTrace({ tool: 'find_unused', path: unusedArgs.module ?? 'all', tokensReturned: unusedTokens, tokensWouldBe: unusedWouldBe || unusedTokens, timestamp: Date.now(), savingsCategory: 'compression', args: unusedArgs });
                     return unusedResult;
                 }
                 case 'code_audit': {
                     const auditArgs = validateCodeAuditArgs(args);
+                    const cachedAudit = sessionCache?.get('code_audit', auditArgs);
+                    if (cachedAudit) {
+                        recordWithTrace({ tool: 'code_audit', path: auditArgs.check, tokensReturned: cachedAudit.tokenEstimate, tokensWouldBe: cachedAudit.tokensWouldBe ?? cachedAudit.tokenEstimate, timestamp: Date.now(), sessionCacheHit: true, savingsCategory: 'cache', args: auditArgs });
+                        return cachedAudit.result;
+                    }
                     const auditResult = await handleCodeAudit(auditArgs, projectRoot, astIndex);
                     const auditText = auditResult.content[0]?.text ?? '';
-                    analytics.record({ tool: 'code_audit', path: auditArgs.check, tokensReturned: estimateTokens(auditText), tokensWouldBe: estimateTokens(auditText), timestamp: Date.now() });
+                    const auditTokens = estimateTokens(auditText);
+                    const auditWouldBe = await estimateFindUsagesWorkflowTokens(auditResult.meta.files);
+                    sessionCache?.set('code_audit', auditArgs, auditResult, { dependsOnAst: true }, auditTokens, auditWouldBe || auditTokens);
+                    recordWithTrace({ tool: 'code_audit', path: auditArgs.check, tokensReturned: auditTokens, tokensWouldBe: auditWouldBe || auditTokens, timestamp: Date.now(), savingsCategory: 'compression', args: auditArgs });
                     return auditResult;
                 }
                 case 'module_info': {
                     const moduleArgs = validateModuleInfoArgs(args);
+                    const cachedModule = sessionCache?.get('module_info', moduleArgs);
+                    if (cachedModule) {
+                        recordWithTrace({ tool: 'module_info', path: moduleArgs.module, tokensReturned: cachedModule.tokenEstimate, tokensWouldBe: cachedModule.tokensWouldBe ?? cachedModule.tokenEstimate, timestamp: Date.now(), sessionCacheHit: true, savingsCategory: 'cache', args: moduleArgs });
+                        return cachedModule.result;
+                    }
                     const moduleResult = await handleModuleInfo(moduleArgs, projectRoot, astIndex);
                     const moduleText = moduleResult.content[0]?.text ?? '';
-                    // Estimate: manual analysis would require reading all module files + grepping deps
-                    const moduleWouldBe = estimateTokens(moduleText) * 5;
-                    analytics.record({ tool: 'module_info', path: moduleArgs.module, tokensReturned: estimateTokens(moduleText), tokensWouldBe: moduleWouldBe, timestamp: Date.now() });
+                    const moduleTokens = estimateTokens(moduleText);
+                    const moduleWouldBe = await estimateFindUsagesWorkflowTokens(moduleResult.meta.files);
+                    sessionCache?.set('module_info', moduleArgs, moduleResult, { dependsOnAst: true }, moduleTokens, moduleWouldBe || moduleTokens);
+                    recordWithTrace({ tool: 'module_info', path: moduleArgs.module, tokensReturned: moduleTokens, tokensWouldBe: moduleWouldBe || moduleTokens, timestamp: Date.now(), savingsCategory: 'compression', args: moduleArgs });
                     return moduleResult;
                 }
                 case 'smart_diff': {
@@ -620,17 +968,34 @@ export async function createServer(projectRoot, options) {
                     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() });
+                    recordWithTrace({ tool: 'smart_diff', path: sdArgs.path ?? sdArgs.scope ?? 'unstaged', tokensReturned: sdTokens, tokensWouldBe: sdResult.rawTokens || sdTokens, timestamp: Date.now(), savingsCategory: 'compression', args: sdArgs });
                     return { content: sdResult.content };
                 }
                 case 'explore_area': {
                     const eaArgs = validateExploreAreaArgs(args);
+                    const cachedEa = sessionCache?.get('explore_area', eaArgs);
+                    if (cachedEa) {
+                        recordWithTrace({ tool: 'explore_area', path: eaArgs.path, tokensReturned: cachedEa.tokenEstimate, tokensWouldBe: cachedEa.tokensWouldBe ?? cachedEa.tokenEstimate, timestamp: Date.now(), sessionCacheHit: true, savingsCategory: 'cache', args: eaArgs });
+                        return cachedEa.result;
+                    }
                     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() });
+                    const eaWouldBe = await estimateExploreAreaWorkflowTokens(eaResult.meta);
+                    sessionCache?.set('explore_area', eaArgs, eaResult, {
+                        files: [resolve(projectRoot, eaArgs.path) + '/'],
+                        dependsOnAst: true,
+                        dependsOnGit: true,
+                    }, eaTokens, eaWouldBe || eaTokens);
+                    recordWithTrace({
+                        tool: 'explore_area',
+                        path: eaArgs.path,
+                        tokensReturned: eaTokens,
+                        tokensWouldBe: eaWouldBe || eaTokens,
+                        timestamp: Date.now(),
+                        savingsCategory: 'compression',
+                        args: eaArgs,
+                    });
                     return eaResult;
                 }
                 case 'smart_log': {
@@ -638,7 +1003,7 @@ export async function createServer(projectRoot, options) {
                     const slResult = await handleSmartLog(slArgs, projectRoot);
                     const slText = slResult.content[0]?.text ?? '';
                     const slTokens = estimateTokens(slText);
-                    analytics.record({ tool: 'smart_log', path: slArgs.path ?? 'all', tokensReturned: slTokens, tokensWouldBe: slResult.rawTokens || slTokens, timestamp: Date.now() });
+                    recordWithTrace({ tool: 'smart_log', path: slArgs.path ?? 'all', tokensReturned: slTokens, tokensWouldBe: slResult.rawTokens || slTokens, timestamp: Date.now(), savingsCategory: 'compression', args: slArgs });
                     return { content: slResult.content };
                 }
                 case 'test_summary': {
@@ -646,7 +1011,7 @@ export async function createServer(projectRoot, options) {
                     const tsResult = await handleTestSummary(tsArgs, projectRoot);
                     const tsText = tsResult.content[0]?.text ?? '';
                     const tsTokens = estimateTokens(tsText);
-                    analytics.record({ tool: 'test_summary', path: tsArgs.command, tokensReturned: tsTokens, tokensWouldBe: tsResult.rawTokens || tsTokens, timestamp: Date.now() });
+                    recordWithTrace({ tool: 'test_summary', path: tsArgs.command, tokensReturned: tsTokens, tokensWouldBe: tsResult.rawTokens || tsTokens, timestamp: Date.now(), savingsCategory: 'compression', args: tsArgs });
                     return { content: tsResult.content };
                 }
                 default:

package/dist/types.d.ts

@@ -119,6 +119,18 @@ export interface TokenPilotConfig {
         checkOnStartup: boolean;
         autoUpdate: boolean;
     };
+    sessionCache: {
+        enabled: boolean;
+        maxEntries: number;
+    };
+    policies: {
+        preferCheapReads: boolean;
+        requireReadForEditBeforeEdit: boolean;
+        cacheProjectOverview: boolean;
+        maxFullFileReads: number;
+        warnOnLargeReads: boolean;
+        largeReadThreshold: number;
+    };
     ignore: string[];
 }
 //# sourceMappingURL=types.d.ts.map