token-pilot 0.16.0 → 0.16.2

package/CHANGELOG.md

@@ -5,6 +5,12 @@ 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.16.1] - 2026-03-21
+
+### Added
+- **Hook interception tracking** — PreToolUse hook now records denied Read calls (file path, line count, estimated tokens) to `.token-pilot/hook-denied.jsonl`. Session analytics shows how many tokens the hook saved by intercepting unbounded reads on large code files.
+- **`session_analytics` hook savings** — compact report adds "Hook: intercepted N reads, saved ~X tokens" line. Verbose mode shows per-file breakdown of intercepted reads.
+
 ## [0.16.0] - 2026-03-21
 
 ### Added

package/dist/core/hook-tracker.d.ts

@@ -0,0 +1,20 @@
+export interface DeniedRead {
+    filePath: string;
+    lineCount: number;
+    estimatedTokens: number;
+    timestamp: number;
+}
+/**
+ * Called from hook-read process when a Read is denied.
+ * Appends to a shared JSONL file so the MCP server can read it.
+ */
+export declare function appendDeniedRead(filePath: string, lineCount: number, fileContent: string, projectRoot?: string): void;
+/**
+ * Called from MCP server to load denied reads for analytics.
+ */
+export declare function loadDeniedReads(projectRoot?: string): DeniedRead[];
+/**
+ * Clear denied reads (called on session reset or after reporting).
+ */
+export declare function clearDeniedReads(projectRoot?: string): void;
+//# sourceMappingURL=hook-tracker.d.ts.map

package/dist/core/hook-tracker.js

@@ -0,0 +1,57 @@
+import { appendFileSync, readFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+function getDeniedReadsPath(projectRoot) {
+    const root = projectRoot || process.cwd();
+    return join(root, '.token-pilot', 'hook-denied.jsonl');
+}
+/**
+ * Called from hook-read process when a Read is denied.
+ * Appends to a shared JSONL file so the MCP server can read it.
+ */
+export function appendDeniedRead(filePath, lineCount, fileContent, projectRoot) {
+    try {
+        const charEstimate = Math.ceil(fileContent.length / 4);
+        const whitespaceRatio = (fileContent.match(/\s/g)?.length ?? 0) / fileContent.length;
+        const estimatedTokens = Math.ceil(charEstimate * (1 - whitespaceRatio * 0.3));
+        const entry = {
+            filePath,
+            lineCount,
+            estimatedTokens,
+            timestamp: Date.now(),
+        };
+        const outPath = getDeniedReadsPath(projectRoot);
+        mkdirSync(join(outPath, '..'), { recursive: true });
+        appendFileSync(outPath, JSON.stringify(entry) + '\n');
+    }
+    catch {
+        // Silent fail — hook must not break
+    }
+}
+/**
+ * Called from MCP server to load denied reads for analytics.
+ */
+export function loadDeniedReads(projectRoot) {
+    try {
+        const raw = readFileSync(getDeniedReadsPath(projectRoot), 'utf-8');
+        return raw
+            .trim()
+            .split('\n')
+            .filter(Boolean)
+            .map(line => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Clear denied reads (called on session reset or after reporting).
+ */
+export function clearDeniedReads(projectRoot) {
+    try {
+        unlinkSync(getDeniedReadsPath(projectRoot));
+    }
+    catch {
+        // File may not exist
+    }
+}
+//# sourceMappingURL=hook-tracker.js.map

package/dist/core/session-analytics.d.ts

@@ -23,6 +23,8 @@ export declare class SessionAnalytics {
     private calls;
     private sessionStart;
     private contextModeStatus;
+    private projectRoot?;
+    setProjectRoot(root: string): void;
     setContextModeStatus(status: ContextModeStatus): void;
     record(call: ToolCall): void;
     /**

package/dist/core/session-analytics.js

@@ -1,5 +1,6 @@
 import { formatDuration } from './format-duration.js';
 import { ALL_INTENTS } from './intent-classifier.js';
+import { loadDeniedReads, clearDeniedReads } from './hook-tracker.js';
 /**
  * Tracks token savings and tool usage across a session.
  * When context-mode is detected, includes unified reporting.
@@ -8,6 +9,10 @@ export class SessionAnalytics {
     calls = [];
     sessionStart = Date.now();
     contextModeStatus = { detected: false, source: 'none', toolPrefix: '' };
+    projectRoot;
+    setProjectRoot(root) {
+        this.projectRoot = root;
+    }
     setContextModeStatus(status) {
         this.contextModeStatus = status;
     }
@@ -69,6 +74,13 @@ export class SessionAnalytics {
         if (extras.length > 0) {
             lines.push(extras.join('  ·  '));
         }
+        // Hook interception savings
+        const deniedReads = loadDeniedReads(this.projectRoot);
+        const sessionDenied = deniedReads.filter(d => d.timestamp >= this.sessionStart);
+        if (sessionDenied.length > 0) {
+            const hookTokensSaved = sessionDenied.reduce((s, d) => s + d.estimatedTokens, 0);
+            lines.push(`Hook: intercepted ${sessionDenied.length} unbounded Read${sessionDenied.length === 1 ? '' : 's'}, saved ~${hookTokensSaved} tokens`);
+        }
         if (!verbose)
             return lines.join('\n');
         // --- Verbose additions ---
@@ -169,6 +181,23 @@ export class SessionAnalytics {
                 lines.push(`  Missed savings: ${missedSavings} call${missedSavings === 1 ? '' : 's'} could have used cheaper tools`);
             }
         }
+        // Hook interception details
+        if (sessionDenied.length > 0) {
+            const hookTokensSaved = sessionDenied.reduce((s, d) => s + d.estimatedTokens, 0);
+            lines.push('');
+            lines.push(`Hook interceptions: ${sessionDenied.length} unbounded Read calls denied → ~${hookTokensSaved} tokens saved`);
+            const byHookFile = new Map();
+            for (const d of sessionDenied) {
+                const e = byHookFile.get(d.filePath) ?? { count: 0, tokens: 0 };
+                e.count++;
+                e.tokens += d.estimatedTokens;
+                byHookFile.set(d.filePath, e);
+            }
+            const topHookFiles = Array.from(byHookFile.entries()).sort((a, b) => b[1].tokens - a[1].tokens).slice(0, 5);
+            for (const [file, stats] of topHookFiles) {
+                lines.push(`  ${file}: ${stats.count}× denied, ~${stats.tokens} tokens saved`);
+            }
+        }
         // Context-mode
         if (this.contextModeStatus.detected) {
             lines.push('');
@@ -182,6 +211,7 @@ export class SessionAnalytics {
     reset() {
         this.calls = [];
         this.sessionStart = Date.now();
+        clearDeniedReads(this.projectRoot);
     }
 }
 //# sourceMappingURL=session-analytics.js.map

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { readFileSync, realpathSync } from 'node:fs';
+import { readFileSync, realpathSync, appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
@@ -171,9 +172,10 @@ export function handleHookRead(filePathArg, denyThreshold = 300) {
     }
     // Check file size
     let lineCount = 0;
+    let fileContent = '';
     try {
-        const content = readFileSync(filePath, 'utf-8');
-        lineCount = content.split('\n').length;
+        fileContent = readFileSync(filePath, 'utf-8');
+        lineCount = fileContent.split('\n').length;
         if (lineCount <= denyThreshold) {
             process.exit(0);
         }
@@ -181,6 +183,19 @@ export function handleHookRead(filePathArg, denyThreshold = 300) {
     catch {
         process.exit(0);
     }
+    // Track denied read for session analytics
+    try {
+        const charEst = Math.ceil(fileContent.length / 4);
+        const wsRatio = (fileContent.match(/\s/g)?.length ?? 0) / fileContent.length;
+        const estTokens = Math.ceil(charEst * (1 - wsRatio * 0.3));
+        const entry = JSON.stringify({ filePath, lineCount, estimatedTokens: estTokens, timestamp: Date.now() });
+        const dir = join(process.cwd(), '.token-pilot');
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(join(dir, 'hook-denied.jsonl'), entry + '\n');
+    }
+    catch {
+        // Silent fail — hook must not break
+    }
     // Large code file, unbounded Read → DENY
     // permissionDecisionReason is shown to Claude (not user) per official docs
     const deny = JSON.stringify({

package/dist/server.js

@@ -146,6 +146,7 @@ export async function createServer(projectRoot, options) {
     }
     // Session analytics
     const analytics = new SessionAnalytics();
+    analytics.setProjectRoot(projectRoot);
     // Session cache (tool-result-level caching, invalidated by file/AST/git changes)
     const sessionCache = config.sessionCache.enabled
         ? new SessionCache(config.sessionCache.maxEntries)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "Save up to 80% tokens when AI reads code — MCP server for token-efficient code navigation, AST-aware structural reading instead of dumping full files into context window",
   "type": "module",
   "main": "dist/index.js",
@@ -58,6 +58,7 @@
   "bugs": {
     "url": "https://github.com/Digital-Threads/token-pilot/issues"
   },
+  "mcpName": "io.github.Digital-Threads/token-pilot",
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",