token-pilot 0.13.0 → 0.14.2

package/.claude-plugin/hooks/hooks.json

@@ -9,6 +9,15 @@
             "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/index.js hook-read"
           }
         ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/index.js hook-edit"
+          }
+        ]
       }
     ]
   }

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.14.1] - 2026-03-14
+
+### Fixed
+- **CI: Node.js 24 runtime** — opted into `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` for GitHub Actions, resolving deprecation warnings for `actions/checkout@v4` and `actions/setup-node@v4`.
+- **CI: test matrix** — updated from Node 18+22 to Node 20+22 (Node 18 is EOL).
+- **Test: git commit in CI** — `read-for-edit` tests now pass `-c user.name` / `-c user.email` to `git commit`, fixing failures in environments without global git config.
+
+## [0.14.0] - 2026-03-14
+
+### Added
+- **R&D Track 0: Instrumentation** — per-call decision trace capturing file size, context state, estimated vs actual cost, and cheaper alternative suggestions. Integrated into all 18 tool handlers via `recordWithTrace()`.
+- **R&D Track 1: Budget Planner** — advisory layer suggesting cheaper tool alternatives (e.g. `smart_read` → `read_diff` when file already in context, → `read_symbol` when symbol known). Analytics-only, no blocking.
+- **R&D Track 2: Intent Router** — classifies tool calls into 7 intents (edit/debug/explore/review/analyze/search/read). Per-intent breakdown in session analytics.
+- **R&D Track 3: Edit Prep Mode** — `read_for_edit` with `include_callers`, `include_tests`, `include_changes` enrichment options.
+- **R&D Track 4: Session Cache** — tool-result-level caching with file/AST/git invalidation.
+- **R&D Track 5: Confidence-Based Escalation** — confidence metadata (high/medium/low) appended to `smart_read`, `read_symbol`, `read_for_edit`, `find_usages` responses. Shows known unknowns and suggested next steps.
+- **R&D Track 6: Working Set / Dedup** — compact reminders for already-loaded files and symbols.
+- **R&D Track 7: Related Files Ranking** — scored ranking with 6 signals (test +5, import +4, importer +3, same-dir +2, recently-changed +2, multi-ref +1). HIGH VALUE / MEDIUM / LOW buckets.
+- **R&D Track 8: Architecture Fingerprint** — caches architecture in `.token-pilot-fingerprint.json` (24h TTL). Amortizes `project_overview` cost across sessions.
+- **R&D Track 9: Verified Savings Dashboard** — savings breakdown by category (compression/cache/dedup), session cache hit rate, dedup stats.
+- **R&D Track 10: Team Policy Mode** — configurable policies: `preferCheapReads`, `maxFullFileReads`, `warnOnLargeReads`, `requireReadForEditBeforeEdit`.
+- **7 new core modules** — `confidence.ts`, `intent-classifier.ts`, `budget-planner.ts`, `decision-trace.ts`, `session-cache.ts`, `architecture-fingerprint.ts`, `policy-engine.ts`.
+- **35 new tests** — confidence (11), architecture-fingerprint (11), policy-engine (13). Total: 393 tests.
+
+### Changed
+- **`session_analytics`** — per-intent breakdown, decision insights, savings by category.
+- **`project_overview`** — saves/loads architecture fingerprint for cross-session caching.
+- **Config** — added `policies` section to `TokenPilotConfig`.
+
 ## [0.13.0] - 2026-03-14
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # Token Pilot
 
-MCP server that reduces token consumption in AI coding assistants by **60-80%** via AST-aware lazy file reading.
+MCP server that reduces token consumption in AI coding assistants by **up to 80%** via AST-aware lazy file reading.
 
 Instead of dumping entire files into the LLM context, Token Pilot returns structural overviews (classes, functions, signatures, line ranges) and lets the AI load only the specific symbols it needs.
 
@@ -13,7 +13,7 @@ Token Pilot:  smart_read("user-service.ts")  →  15-line outline  →  ~200 tok
               After edit: read_diff("user-service.ts")  →  ~20 tokens
 ```
 
-**~80% reduction** in this example. Files under 200 lines are returned in full automatically (no overhead for small files). Real savings start at ~200+ lines.
+**Up to 80% reduction** on large files. Files under 200 lines are returned in full automatically (zero overhead for small files). Typical sessions with a mix of file sizes see **30-50% savings**, scaling higher with repeated reads (session cache, compact reminders) and targeted symbol loading.
 
 ## Installation
 
@@ -113,7 +113,10 @@ npx token-pilot install-ast-index
 
 ### PreToolUse Hook (Claude Code only)
 
-Optional hook that intercepts `Read` calls for large code files (>500 lines) and suggests `smart_read`. Claude Code only.
+Optional Claude Code hook support:
+
+- blocks unbounded `Read` on large code files (>500 lines) and points the agent to `smart_read`
+- adds `read_for_edit` guidance before `Edit`
 
 ```bash
 npx token-pilot install-hook            # Install
@@ -129,7 +132,7 @@ npx token-pilot uninstall-hook          # Remove
 When connected, every MCP client receives rules like:
 
 ```
-WHEN TO USE TOKEN PILOT (saves 60-80% tokens):
+WHEN TO USE TOKEN PILOT (saves up to 80% tokens):
 • Reading code files → smart_read (returns structure, not raw content)
 • Need one function/class → read_symbol (loads only that symbol)
 • Exploring a directory → outline (all symbols in one call)
@@ -149,13 +152,13 @@ For more control, you can add rules to your project:
 - **Cursor** → `.cursorrules` in project root
 - **Codex** → `AGENTS.md` in project root
 
-## MCP Tools (14)
+## MCP Tools (18)
 
 ### Core Reading
 
 | Tool | Instead of | Description |
 |------|-----------|-------------|
-| `smart_read` | `Read` | AST structural overview: classes, functions, methods with signatures. 60-80% savings. Framework-aware: shows HTTP routes, column types, validation rules. |
+| `smart_read` | `Read` | AST structural overview: classes, functions, methods with signatures. Up to 80% savings on large files. Framework-aware: shows HTTP routes, column types, validation rules. |
 | `read_symbol` | `Read` + scroll | Load source of a specific symbol. Supports `Class.method`. `show` param: full/head/tail/outline. |
 | `read_for_edit` | `Read` before `Edit` | Minimal RAW code around a symbol — copy directly as `old_string` for Edit tool. |
 | `read_range` | `Read` offset | Read a specific line range from a file. |
@@ -182,7 +185,7 @@ For more control, you can add rules to your project:
 
 | Tool | Description |
 |------|-------------|
-| `session_analytics` | Token savings report: total saved, per-tool breakdown, top files. |
+| `session_analytics` | Token savings report: total saved, per-tool breakdown, top files, per-intent breakdown, decision insights, policy advisories. |
 
 ## CLI Commands
 
@@ -194,6 +197,7 @@ token-pilot install-ast-index    # Download ast-index binary (auto on first run)
 token-pilot install-hook [root]  # Install PreToolUse hook
 token-pilot uninstall-hook       # Remove hook
 token-pilot hook-read <file>     # Hook handler (called by Claude Code)
+token-pilot hook-edit            # Edit hook handler (called by Claude Code)
 token-pilot doctor               # Run diagnostics (ast-index, config, updates)
 token-pilot --version            # Show version
 token-pilot --help               # Show help
@@ -222,6 +226,13 @@ Create `.token-pilot.json` in your project root to customize behavior:
     "adviseDelegation": true,
     "largeNonCodeThreshold": 200
   },
+  "policies": {
+    "preferCheapReads": true,
+    "maxFullFileReads": 10,
+    "warnOnLargeReads": true,
+    "largeReadThreshold": 2000,
+    "requireReadForEditBeforeEdit": true
+  },
   "display": {
     "showImports": true,
     "showDocs": true,
@@ -248,6 +259,10 @@ All fields are optional — sensible defaults are used for anything not specifie
 | `git.watchHead` | `true` | Watch `.git/HEAD` for branch switches, invalidate changed files. |
 | `contextMode.enabled` | `"auto"` | Detect context-mode plugin. `true`/`false` to force. |
 | `contextMode.adviseDelegation` | `true` | Suggest context-mode for large non-code files. |
+| `policies.preferCheapReads` | `true` | Advisory hints when expensive tool used where cheaper exists. |
+| `policies.maxFullFileReads` | `10` | Warn after N full-file reads in session. |
+| `policies.warnOnLargeReads` | `true` | Warn when single response exceeds threshold. |
+| `policies.largeReadThreshold` | `2000` | Token threshold for large read warning. |
 
 ## Integration with context-mode
 
@@ -265,13 +280,13 @@ When both are configured, Token Pilot automatically:
 - Suggests context-mode for large non-code files
 - Shows combined architecture info in `session_analytics`
 
-**Combined savings: 60-80%** in a typical coding session.
+**Combined savings: up to 80%** in a typical coding session.
 
 ## Supported Languages
 
-Token Pilot supports all 23 languages that [ast-index](https://github.com/defendend/Claude-ast-index-search) supports:
+Token Pilot supports all 29 languages that [ast-index](https://github.com/defendend/Claude-ast-index-search) supports:
 
-TypeScript, JavaScript, Python, Rust, Go, Java, Kotlin, Swift, C#, C++, C, PHP, Ruby, Scala, Dart, Lua, Shell/Bash, SQL, R, Vue, Svelte, Perl, Groovy
+TypeScript, JavaScript, Python, Rust, Go, Java, Kotlin, Swift, Objective-C, C#, C++, C, PHP, Ruby, Scala, Dart, Lua, Shell/Bash, SQL, R, Vue, Svelte, Perl, Groovy, Elixir, Common Lisp, Matlab, Protocol Buffers, BSL (1C:Enterprise)
 
 Plus structural summaries for non-code files: JSON, YAML, Markdown, TOML, XML, CSV.
 
@@ -319,8 +334,8 @@ npm run dev          # TypeScript watch mode
 
 ```
 src/
-  index.ts              — CLI entry point (6 commands)
-  server.ts             — MCP server setup, 14 tool definitions, instructions
+  index.ts              — CLI entry point and server bootstrap
+  server.ts             — MCP server setup, tool definitions, instructions
   types.ts              — Core domain types
   ast-index/
     client.ts           — ast-index CLI wrapper (22+ methods)
@@ -332,10 +347,17 @@ src/
     context-registry.ts — Advisory context tracking + compact reminders
     symbol-resolver.ts  — Qualified symbol resolution
     token-estimator.ts  — Token count estimation
-    session-analytics.ts — Token savings tracking
+    session-analytics.ts — Token savings tracking with intent + decision trace
     validation.ts       — Input validators for all tools
     format-duration.ts  — Shared duration formatter
     project-detector.ts — Config-based project detection (frameworks, CI, quality tools)
+    confidence.ts       — Confidence metadata for response completeness
+    intent-classifier.ts — Tool → intent mapping (edit/debug/explore/review/analyze/search/read)
+    budget-planner.ts   — Advisory: suggests cheaper tool alternatives
+    decision-trace.ts   — Per-call instrumentation (cost, context state, alternatives)
+    session-cache.ts    — Tool-result-level caching with invalidation
+    architecture-fingerprint.ts — Cross-session architecture caching
+    policy-engine.ts    — Configurable team policies for consistent savings
   config/
     loader.ts           — Config loading + deep merge
     defaults.ts         — Default config values
@@ -360,7 +382,6 @@ src/
     smart-log.ts        — smart_log handler (structured git log + category detection)
     test-summary.ts     — test_summary handler (run tests + parse output)
     non-code.ts         — JSON/YAML/MD/TOML structural summaries
-    export-ast-index.ts — AST export for context-mode BM25
   git/
     watcher.ts          — Git HEAD watcher (branch switch detection)
     file-watcher.ts     — File system watcher (cache invalidation)
@@ -374,7 +395,7 @@ src/
 
 Token Pilot is built on top of these excellent open-source projects:
 
-- **[ast-index](https://github.com/defendend/Claude-ast-index-search)** by [@defendend](https://github.com/defendend) — Rust-based AST indexing engine with tree-sitter, SQLite FTS5, and support for 23 programming languages. Token Pilot uses it as the backend for all code analysis.
+- **[ast-index](https://github.com/defendend/Claude-ast-index-search)** by [@defendend](https://github.com/defendend) — Rust-based AST indexing engine with tree-sitter, SQLite FTS5, and support for 29 programming languages. Token Pilot uses it as the backend for all code analysis.
 - **[claude-context-mode](https://github.com/mksglu/claude-context-mode)** by [@mksglu](https://github.com/mksglu) — Complementary MCP plugin for shell output and data file processing via sandbox + BM25. Token Pilot integrates with it for maximum combined savings.
 - **[Model Context Protocol](https://modelcontextprotocol.io/)** by Anthropic — The protocol that makes all of this possible.
 

package/dist/config/defaults.js

@@ -42,6 +42,18 @@ export const DEFAULT_CONFIG = {
         checkOnStartup: true,
         autoUpdate: false,
     },
+    sessionCache: {
+        enabled: true,
+        maxEntries: 200,
+    },
+    policies: {
+        preferCheapReads: true,
+        requireReadForEditBeforeEdit: true,
+        cacheProjectOverview: true,
+        maxFullFileReads: 10,
+        warnOnLargeReads: true,
+        largeReadThreshold: 2000,
+    },
     ignore: [
         'node_modules/**',
         'dist/**',

package/dist/core/architecture-fingerprint.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Architecture fingerprint — caches project architecture data to a file
+ * to amortize overview cost across sessions.
+ * Track 8: Architecture Fingerprint
+ */
+export interface ArchitectureFingerprint {
+    version: string;
+    generatedAt: number;
+    projectType?: string;
+    frameworks: string[];
+    testLayout?: string;
+    entrypoints: string[];
+    moduleCount: number;
+    sourceFileCount: number;
+    namingConventions: string[];
+}
+/**
+ * Load fingerprint from disk. Returns null if missing or expired.
+ */
+export declare function loadFingerprint(projectRoot: string): Promise<ArchitectureFingerprint | null>;
+/**
+ * Save fingerprint to disk.
+ */
+export declare function saveFingerprint(projectRoot: string, fp: ArchitectureFingerprint): Promise<void>;
+/**
+ * Build fingerprint from project_overview text output.
+ * Parses the structured overview text to extract key architecture data.
+ */
+export declare function buildFingerprint(overviewText: string, version: string): ArchitectureFingerprint;
+/**
+ * Format a cached fingerprint as a summary section.
+ */
+export declare function formatCachedFingerprint(fp: ArchitectureFingerprint): string;
+//# sourceMappingURL=architecture-fingerprint.d.ts.map

package/dist/core/architecture-fingerprint.js

@@ -0,0 +1,127 @@
+/**
+ * Architecture fingerprint — caches project architecture data to a file
+ * to amortize overview cost across sessions.
+ * Track 8: Architecture Fingerprint
+ */
+import { readFile, writeFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+const FINGERPRINT_FILE = '.token-pilot-fingerprint.json';
+const FINGERPRINT_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+/**
+ * Load fingerprint from disk. Returns null if missing or expired.
+ */
+export async function loadFingerprint(projectRoot) {
+    const filePath = join(projectRoot, FINGERPRINT_FILE);
+    try {
+        const fileStat = await stat(filePath);
+        const age = Date.now() - fileStat.mtimeMs;
+        if (age > FINGERPRINT_TTL_MS) {
+            return null; // expired
+        }
+        const raw = await readFile(filePath, 'utf-8');
+        const data = JSON.parse(raw);
+        // Validate minimal structure
+        if (!data.version || !data.generatedAt) {
+            return null;
+        }
+        return data;
+    }
+    catch {
+        return null; // file doesn't exist or is invalid
+    }
+}
+/**
+ * Save fingerprint to disk.
+ */
+export async function saveFingerprint(projectRoot, fp) {
+    const filePath = join(projectRoot, FINGERPRINT_FILE);
+    await writeFile(filePath, JSON.stringify(fp, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Build fingerprint from project_overview text output.
+ * Parses the structured overview text to extract key architecture data.
+ */
+export function buildFingerprint(overviewText, version) {
+    const fp = {
+        version,
+        generatedAt: Date.now(),
+        frameworks: [],
+        entrypoints: [],
+        moduleCount: 0,
+        sourceFileCount: 0,
+        namingConventions: [],
+    };
+    // Extract project type
+    const typeMatch = overviewText.match(/TYPE\s*(?:\([^)]*\))?:\s*(.+)/);
+    if (typeMatch) {
+        fp.projectType = typeMatch[1].trim().split('\n')[0];
+    }
+    // Extract frameworks
+    const fwMatch = overviewText.match(/FRAMEWORKS:\s*(.+)/);
+    if (fwMatch) {
+        fp.frameworks = fwMatch[1].split(',').map(s => s.trim()).filter(Boolean);
+    }
+    // Extract file count from MAP or ast-index data
+    const fileCountMatch = overviewText.match(/(\d+)\s*files/);
+    if (fileCountMatch) {
+        fp.sourceFileCount = parseInt(fileCountMatch[1], 10);
+    }
+    // Extract naming patterns
+    const patternsMatch = overviewText.match(/PATTERNS:\s*(.+)/);
+    if (patternsMatch) {
+        fp.namingConventions = patternsMatch[1].split(',').map(s => s.trim()).filter(Boolean);
+    }
+    // Extract architecture
+    const archMatch = overviewText.match(/ARCHITECTURE:\s*(.+)/);
+    if (archMatch) {
+        fp.testLayout = archMatch[1].trim();
+    }
+    // Extract MAP entries as module indicators
+    const mapEntries = overviewText.match(/^\s{2}\S+.*\(\d+ files/gm);
+    if (mapEntries) {
+        fp.moduleCount = mapEntries.length;
+        // Detect entrypoints from common patterns
+        for (const entry of mapEntries) {
+            const dirMatch = entry.match(/^\s*(\S+)/);
+            if (dirMatch) {
+                const dir = dirMatch[1];
+                if (/^(src|lib|app|main|index)/.test(dir)) {
+                    fp.entrypoints.push(dir);
+                }
+            }
+        }
+    }
+    return fp;
+}
+/**
+ * Format a cached fingerprint as a summary section.
+ */
+export function formatCachedFingerprint(fp) {
+    const lines = [
+        '--- Cached Architecture (from previous session) ---',
+    ];
+    if (fp.projectType) {
+        lines.push(`TYPE: ${fp.projectType}`);
+    }
+    if (fp.frameworks.length > 0) {
+        lines.push(`FRAMEWORKS: ${fp.frameworks.join(', ')}`);
+    }
+    if (fp.sourceFileCount > 0) {
+        lines.push(`FILES: ${fp.sourceFileCount}`);
+    }
+    if (fp.moduleCount > 0) {
+        lines.push(`MODULES: ${fp.moduleCount}`);
+    }
+    if (fp.namingConventions.length > 0) {
+        lines.push(`PATTERNS: ${fp.namingConventions.join(', ')}`);
+    }
+    if (fp.entrypoints.length > 0) {
+        lines.push(`ENTRYPOINTS: ${fp.entrypoints.join(', ')}`);
+    }
+    const age = Date.now() - fp.generatedAt;
+    const hoursAgo = Math.round(age / (60 * 60 * 1000));
+    lines.push(`CACHED: ${hoursAgo}h ago (v${fp.version})`);
+    lines.push('---');
+    return lines.join('\n');
+}
+//# sourceMappingURL=architecture-fingerprint.js.map

package/dist/core/budget-planner.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Budget planner — advisory layer that suggests cheaper tool alternatives.
+ * Phase 1: analytics-only, no active blocking.
+ */
+export interface CheaperAlternative {
+    tool: string;
+    estimatedTokens: number;
+    reason: string;
+}
+export interface BudgetContext {
+    fileLines?: number;
+    alreadyInContext: boolean;
+    symbolKnown: boolean;
+    recentlyEdited: boolean;
+}
+/**
+ * Given the tool that was used and the context, suggest a cheaper alternative.
+ * Returns null if the chosen tool was already optimal.
+ */
+export declare function suggestCheaperAlternative(usedTool: string, args: Record<string, unknown>, context: BudgetContext): CheaperAlternative | null;
+//# sourceMappingURL=budget-planner.d.ts.map

package/dist/core/budget-planner.js

@@ -0,0 +1,68 @@
+/**
+ * Budget planner — advisory layer that suggests cheaper tool alternatives.
+ * Phase 1: analytics-only, no active blocking.
+ */
+/**
+ * Given the tool that was used and the context, suggest a cheaper alternative.
+ * Returns null if the chosen tool was already optimal.
+ */
+export function suggestCheaperAlternative(usedTool, args, context) {
+    const fileLines = context.fileLines ?? 0;
+    switch (usedTool) {
+        case 'smart_read': {
+            // If file is already in context and was recently edited, read_diff is much cheaper
+            if (context.alreadyInContext && context.recentlyEdited) {
+                return {
+                    tool: 'read_diff',
+                    estimatedTokens: Math.max(20, Math.round(fileLines * 0.1)),
+                    reason: 'file already in context and recently edited — read_diff shows only changes',
+                };
+            }
+            // If a specific symbol is known, read_symbol is cheaper
+            if (context.symbolKnown && fileLines > 50) {
+                return {
+                    tool: 'read_symbol',
+                    estimatedTokens: Math.round(fileLines * 0.15),
+                    reason: 'specific symbol known — read_symbol returns only the target',
+                };
+            }
+            break;
+        }
+        case 'smart_read_many': {
+            // If all files are already in context, this is wasteful
+            if (context.alreadyInContext) {
+                return {
+                    tool: 'read_diff',
+                    estimatedTokens: Math.max(20, Math.round(fileLines * 0.1)),
+                    reason: 'files already in context — use read_diff for changed files only',
+                };
+            }
+            break;
+        }
+        case 'read_range': {
+            // Large ranges (>60 lines) could use read_symbol if symbol is known
+            const limit = typeof args.limit === 'number' ? args.limit : 0;
+            if (limit > 60 && context.symbolKnown) {
+                return {
+                    tool: 'read_symbol',
+                    estimatedTokens: Math.round(limit * 0.4),
+                    reason: 'large range with known symbol — read_symbol is more targeted',
+                };
+            }
+            break;
+        }
+        case 'read_symbol': {
+            // If file was recently edited and symbol already loaded, read_diff is better
+            if (context.alreadyInContext && context.recentlyEdited) {
+                return {
+                    tool: 'read_diff',
+                    estimatedTokens: Math.max(20, Math.round(fileLines * 0.1)),
+                    reason: 'symbol already loaded and file edited — read_diff shows changes only',
+                };
+            }
+            break;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=budget-planner.js.map

package/dist/core/confidence.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Confidence metadata — tells the LLM how complete the response is
+ * and what follow-up actions might be needed.
+ * Track 5: Confidence-Based Escalation
+ */
+export type ConfidenceLevel = 'high' | 'medium' | 'low';
+export interface ConfidenceMetadata {
+    confidence: ConfidenceLevel;
+    knownUnknowns: string[];
+    suggestedNextStep?: string;
+}
+export interface ConfidenceInput {
+    symbolResolved?: boolean;
+    fullFile?: boolean;
+    truncated?: boolean;
+    hasTests?: boolean;
+    hasCallers?: boolean;
+    crossFileDeps?: number;
+    refsFound?: boolean;
+    astAvailable?: boolean;
+    dedupHit?: boolean;
+}
+/**
+ * Assess confidence level based on response completeness signals.
+ */
+export declare function assessConfidence(input: ConfidenceInput): ConfidenceMetadata;
+/**
+ * Format confidence metadata as a text section for tool output.
+ */
+export declare function formatConfidence(meta: ConfidenceMetadata): string;
+//# sourceMappingURL=confidence.d.ts.map

package/dist/core/confidence.js

@@ -0,0 +1,99 @@
+/**
+ * Confidence metadata — tells the LLM how complete the response is
+ * and what follow-up actions might be needed.
+ * Track 5: Confidence-Based Escalation
+ */
+/**
+ * Assess confidence level based on response completeness signals.
+ */
+export function assessConfidence(input) {
+    const unknowns = [];
+    let score = 0;
+    // Positive signals
+    if (input.symbolResolved)
+        score += 3;
+    if (input.fullFile)
+        score += 2;
+    if (input.hasTests)
+        score += 1;
+    if (input.hasCallers)
+        score += 1;
+    if (input.refsFound)
+        score += 2;
+    if (input.astAvailable)
+        score += 1;
+    // Negative signals
+    if (input.truncated) {
+        score -= 2;
+        unknowns.push('output was truncated — some content not shown');
+    }
+    if (input.crossFileDeps !== undefined && input.crossFileDeps > 3) {
+        score -= 1;
+        unknowns.push(`${input.crossFileDeps} cross-file dependencies not explored`);
+    }
+    if (input.symbolResolved === false) {
+        score -= 2;
+        unknowns.push('target symbol not resolved');
+    }
+    if (input.astAvailable === false) {
+        score -= 1;
+        unknowns.push('AST index unavailable — structural analysis limited');
+    }
+    if (input.hasTests === false) {
+        unknowns.push('no test file found for this module');
+    }
+    // Dedup hit is informational, not a quality issue
+    if (input.dedupHit) {
+        score += 1; // already known = high confidence in context
+    }
+    // Determine level
+    let confidence;
+    if (score >= 5) {
+        confidence = 'high';
+    }
+    else if (score >= 2) {
+        confidence = 'medium';
+    }
+    else {
+        confidence = 'low';
+    }
+    // Generate suggested next step based on unknowns
+    let suggestedNextStep;
+    if (input.truncated) {
+        suggestedNextStep = 'use read_range() or read_symbol() with show="full" for remaining content';
+    }
+    else if (input.symbolResolved === false) {
+        suggestedNextStep = 'use smart_read() to see available symbols, then read_symbol() for the target';
+    }
+    else if (input.astAvailable === false) {
+        suggestedNextStep = 'structural reading unavailable — use read_range() for raw content';
+    }
+    else if (input.crossFileDeps !== undefined && input.crossFileDeps > 3) {
+        suggestedNextStep = 'use find_usages() or related_files() to explore cross-file dependencies';
+    }
+    const result = { confidence, knownUnknowns: unknowns };
+    if (suggestedNextStep) {
+        result.suggestedNextStep = suggestedNextStep;
+    }
+    return result;
+}
+/**
+ * Format confidence metadata as a text section for tool output.
+ */
+export function formatConfidence(meta) {
+    const lines = [
+        '',
+        `CONFIDENCE: ${meta.confidence}`,
+    ];
+    if (meta.knownUnknowns.length > 0) {
+        lines.push(`KNOWN UNKNOWNS: ${meta.knownUnknowns.join('; ')}`);
+    }
+    else {
+        lines.push('KNOWN UNKNOWNS: none');
+    }
+    if (meta.suggestedNextStep) {
+        lines.push(`SUGGESTED: ${meta.suggestedNextStep}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=confidence.js.map

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

@@ -11,12 +11,26 @@ export declare class ContextRegistry {
     setContentHash(path: string, hash: string): void;
     getLoaded(path: string): LoadedRegion[] | null;
     isSymbolLoaded(path: string, symbolName: string): boolean;
+    /** Check if any region of a file has been loaded into context. */
+    hasAnyLoaded(path: string): boolean;
     isStale(path: string, currentHash: string): boolean;
     /**
      * Generate a compact reminder for previously loaded content.
      * Returns a brief summary instead of full re-read.
      */
     compactReminder(path: string, symbols: SymbolInfo[]): string;
+    /** Check if file was loaded in full (type='full' region exists). */
+    isFullyLoaded(path: string): boolean;
+    /**
+     * Generate a compact dedup reminder for read_symbol.
+     * Fires when same symbol was already loaded OR full file is in context.
+     */
+    symbolReminder(path: string, symbolName: string): string;
+    /**
+     * Generate a compact dedup reminder for read_range.
+     * Only fires when full file is in context.
+     */
+    rangeReminder(path: string, startLine: number, endLine: number): string;
     forget(path: string, symbolName?: string): void;
     forgetAll(): void;
     summary(): {