token-pilot 0.24.1 → 0.26.5

package/dist/core/tool-call-log.js

@@ -0,0 +1,171 @@
+/**
+ * v0.26.2 — persistent MCP tool-call log.
+ *
+ * Separate from `hook-events.jsonl` (which records Read-hook outcomes),
+ * this file accumulates every MCP tool invocation with its token
+ * accounting across ALL sessions. Used by `npx token-pilot tool-audit`
+ * to produce a per-tool savings distribution that survives `/clear`,
+ * session restarts, and even reboots — i.e. the data-driven base we
+ * need before pruning or modifying tools based on "savings".
+ *
+ * Why not piggy-back on hook-events.jsonl? Different data model: hook
+ * events are a denied/allowed bitstream keyed by filepath+lineCount,
+ * tool calls are rich records with tokensReturned, wouldBe, category,
+ * delegation status. Forcing both into one schema would hurt both
+ * readers.
+ *
+ * File path: `<projectRoot>/.token-pilot/tool-calls.jsonl`. Rotation,
+ * retention, and best-effort error handling follow the same contract
+ * as event-log.ts — identical 10 MB / 30-day / 100 MB caps so overall
+ * .token-pilot/ disk usage stays predictable.
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+export const TOOL_LOG_ROTATION_BYTES = 10_000_000;
+export const TOOL_LOG_RETENTION_MAX_AGE_DAYS = 30;
+export const TOOL_LOG_RETENTION_MAX_TOTAL_BYTES = 100_000_000;
+const CURRENT_FILE = "tool-calls.jsonl";
+const ARCHIVE_RE = /^tool-calls\.\d+\.jsonl$/;
+function toolLogDir(projectRoot) {
+    return join(projectRoot, ".token-pilot");
+}
+export function currentToolLogPath(projectRoot) {
+    return join(toolLogDir(projectRoot), CURRENT_FILE);
+}
+async function ensureDir(projectRoot) {
+    await fs.mkdir(toolLogDir(projectRoot), { recursive: true });
+}
+async function rotateIfNeeded(projectRoot, thresholdBytes = TOOL_LOG_ROTATION_BYTES) {
+    const current = currentToolLogPath(projectRoot);
+    try {
+        const s = await fs.stat(current);
+        if (s.size < thresholdBytes)
+            return;
+    }
+    catch {
+        return; // no file → nothing to rotate
+    }
+    const archive = join(toolLogDir(projectRoot), `tool-calls.${Date.now()}.jsonl`);
+    try {
+        await fs.rename(current, archive);
+    }
+    catch {
+        /* raced — next writer will append onto whichever file exists */
+    }
+}
+/**
+ * Append one tool call. Never throws — telemetry must not break the
+ * tool-response path (the caller awaits this but treats errors as
+ * silent via `.catch(() => undefined)` at the call site).
+ */
+export async function appendToolCall(projectRoot, event) {
+    try {
+        await ensureDir(projectRoot);
+        await rotateIfNeeded(projectRoot);
+        await fs.appendFile(currentToolLogPath(projectRoot), JSON.stringify(event) + "\n");
+    }
+    catch {
+        /* silent */
+    }
+}
+/**
+ * Read every tool-call event from the current file + all archives.
+ * Malformed JSONL lines are skipped silently — one bad line should not
+ * poison the dataset. Returns events in *insertion order within each
+ * file*, which happens to be chronological because append-only.
+ */
+export async function loadAllToolCalls(projectRoot) {
+    const dir = toolLogDir(projectRoot);
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    if (entries.includes(CURRENT_FILE))
+        files.push(CURRENT_FILE);
+    for (const n of entries)
+        if (ARCHIVE_RE.test(n))
+            files.push(n);
+    const out = [];
+    for (const name of files) {
+        let raw;
+        try {
+            raw = await fs.readFile(join(dir, name), "utf-8");
+        }
+        catch {
+            continue;
+        }
+        for (const line of raw.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                /* skip malformed */
+            }
+        }
+    }
+    return out;
+}
+// ─── retention (mirrors event-log) ──────────────────────────────────────────
+export function retentionDeletions(files, now, maxAgeDays = TOOL_LOG_RETENTION_MAX_AGE_DAYS, maxTotalBytes = TOOL_LOG_RETENTION_MAX_TOTAL_BYTES) {
+    const toDelete = new Set();
+    const maxAgeMs = maxAgeDays * 86_400_000;
+    const survivors = [];
+    for (const f of files) {
+        if (now.getTime() - f.mtime.getTime() > maxAgeMs) {
+            toDelete.add(f.path);
+        }
+        else {
+            survivors.push(f);
+        }
+    }
+    const totalSize = survivors.reduce((sum, f) => sum + f.size, 0);
+    if (totalSize > maxTotalBytes) {
+        const byOldest = [...survivors].sort((a, b) => a.mtime.getTime() - b.mtime.getTime());
+        let trimmed = totalSize;
+        for (const f of byOldest) {
+            if (trimmed <= maxTotalBytes)
+                break;
+            toDelete.add(f.path);
+            trimmed -= f.size;
+        }
+    }
+    return [...toDelete];
+}
+export async function applyRetention(projectRoot, now = new Date()) {
+    const dir = toolLogDir(projectRoot);
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch {
+        return;
+    }
+    const archives = [];
+    for (const name of entries) {
+        if (!ARCHIVE_RE.test(name))
+            continue;
+        const full = join(dir, name);
+        try {
+            const s = await fs.stat(full);
+            archives.push({ path: full, mtime: s.mtime, size: s.size });
+        }
+        catch {
+            /* unreadable → skip */
+        }
+    }
+    for (const p of retentionDeletions(archives, now)) {
+        try {
+            await fs.unlink(p);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+//# sourceMappingURL=tool-call-log.js.map

package/dist/handlers/read-symbols.js

@@ -67,6 +67,15 @@ export async function handleReadSymbols(args, projectRoot, symbolResolver, fileC
     let anyTruncated = false;
     let anyResolved = false;
     let totalTokens = 0;
+    // v0.26.1 — overlap dedupe. The ast-index parser occasionally resolves
+    // two requested symbols to the exact same line range (arrow-function
+    // exports, Vue SFCs, type-vs-function ambiguity). Before this fix the
+    // handler emitted the same body N× — a 4× blow-up on Opus 4.7's field
+    // report, directly negating batch savings. We key by "startLine:endLine"
+    // and emit a short dedupe note instead of repeating the source. Caller
+    // still sees *which* names they asked for; token budget stays sane.
+    const seenRanges = new Map(); // "start:end" -> first name
+    let dedupedCount = 0;
     for (let i = 0; i < N; i++) {
         const symbolName = args.symbols[i];
         const idx = i + 1;
@@ -78,6 +87,16 @@ export async function handleReadSymbols(args, projectRoot, symbolResolver, fileC
             continue;
         }
         anyResolved = true;
+        const rangeKey = `${resolved.startLine}:${resolved.endLine}`;
+        const firstName = seenRanges.get(rangeKey);
+        if (firstName) {
+            dedupedCount++;
+            sections.push(`SYMBOL ${idx}/${N}: ${symbolName} — DEDUPED\n` +
+                `Same [L${resolved.startLine}-${resolved.endLine}] range as "${firstName}" ` +
+                `(ast-index parser overlap). See that section above for the source.`);
+            continue;
+        }
+        seenRanges.set(rangeKey, symbolName);
         const source = symbolResolver.extractSource(resolved, lines, {
             contextBefore: args.context_before ?? 2,
             contextAfter: args.context_after ?? 0,
@@ -164,7 +183,10 @@ export async function handleReadSymbols(args, projectRoot, symbolResolver, fileC
     if (cached?.hash) {
         contextRegistry.setContentHash(absPath, cached.hash);
     }
-    const header = `FILE: ${args.path} | SYMBOLS: ${N} requested`;
+    const header = `FILE: ${args.path} | SYMBOLS: ${N} requested` +
+        (dedupedCount > 0
+            ? ` | DEDUPED: ${dedupedCount} (parser overlap — saved ~${dedupedCount}× body tokens)`
+            : "");
     const body = sections.join("\n\n---\n\n");
     const footer = "CONTEXT TRACKED: These symbols are now in your context.";
     const output = [header, "", body, "", footer].join("\n");

package/dist/hooks/installer.js

@@ -130,9 +130,18 @@ export async function installHook(projectRoot, options) {
                 const hasEdit = existingHooks.some((h) => h.matcher === "Edit" && isTokenPilotHook(h));
                 const hasSessionStart = Array.isArray(settings.hooks?.SessionStart) &&
                     settings.hooks.SessionStart.some(isTokenPilotHook);
-                const hasPostBashHook = Array.isArray(settings.hooks?.PostToolUse) &&
-                    settings.hooks.PostToolUse.some(isTokenPilotHook);
-                if (hasRead && hasEdit && hasSessionStart && hasPostBashHook) {
+                // v0.25.0: check each PostToolUse matcher separately. Previously
+                // "any token-pilot hook in PostToolUse" counted the whole section
+                // as installed, so v0.21 users (Bash matcher only) missed the
+                // Task matcher added in v0.23 and their budget watchdog stayed
+                // silent. The required matchers are exactly what createHookConfig
+                // ships — derive from there so this stays in sync automatically.
+                const requiredPostMatchers = hookConfig.hooks.PostToolUse.map((h) => h.matcher);
+                const postMatchers = Array.isArray(settings.hooks?.PostToolUse)
+                    ? settings.hooks.PostToolUse.filter(isTokenPilotHook).map((h) => h.matcher)
+                    : [];
+                const hasAllPostMatchers = requiredPostMatchers.every((m) => postMatchers.includes(m));
+                if (hasRead && hasEdit && hasSessionStart && hasAllPostMatchers) {
                     return {
                         installed: false,
                         fatal: false,
@@ -166,16 +175,22 @@ export async function installHook(projectRoot, options) {
             }
             settings.hooks.SessionStart.push(...hookConfig.hooks.SessionStart);
         }
-        // Install PostToolUse (Bash advisor) hook idempotently
-        const existingPost = settings.hooks?.PostToolUse;
-        const hasPostBash = Array.isArray(existingPost) && existingPost.some(isTokenPilotHook);
-        if (!hasPostBash) {
-            if (!settings.hooks)
-                settings.hooks = {};
-            if (!Array.isArray(settings.hooks.PostToolUse)) {
-                settings.hooks.PostToolUse = [];
+        // Install PostToolUse hooks idempotently — per-matcher check.
+        // v0.25.0: earlier code treated the whole section as one unit, which
+        // meant users installed in v0.21 (only Bash matcher) never received
+        // the Task matcher added in v0.23. That silently broke the budget
+        // watchdog for anyone upgrading from an older version. Now we check
+        // each matcher individually, same as PreToolUse.
+        if (!settings.hooks)
+            settings.hooks = {};
+        if (!Array.isArray(settings.hooks.PostToolUse)) {
+            settings.hooks.PostToolUse = [];
+        }
+        for (const hookDef of hookConfig.hooks.PostToolUse) {
+            const exists = settings.hooks.PostToolUse.some((h) => h.matcher === hookDef.matcher && isTokenPilotHook(h));
+            if (!exists) {
+                settings.hooks.PostToolUse.push(hookDef);
             }
-            settings.hooks.PostToolUse.push(...hookConfig.hooks.PostToolUse);
         }
         await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n");
         return {

package/dist/index.js

@@ -28,6 +28,7 @@ import { handleInstallAgents, maybeEmitStartupReminder, } from "./cli/install-ag
 import { handleUninstallAgents } from "./cli/uninstall-agents.js";
 import { appendEvent, applyRetention, } from "./core/event-log.js";
 import { handleStats } from "./cli/stats.js";
+import { handleToolAudit } from "./cli/tool-audit.js";
 import { promptYesNo } from "./cli/install-agents.js";
 import { runClaudeCodeEnvCheck } from "./cli/doctor-env-check.js";
 import { claudeIgnoreStatus, writeDefaultClaudeIgnore, } from "./cli/claudeignore.js";
@@ -205,6 +206,11 @@ export async function main(cliArgs = process.argv.slice(2)) {
             process.exit(code);
             return;
         }
+        case "tool-audit": {
+            const code = await handleToolAudit(cliArgs.slice(1));
+            process.exit(code);
+            return;
+        }
         case "save-doc": {
             const code = await handleSaveDocCli(cliArgs.slice(1));
             process.exit(code);
@@ -527,6 +533,19 @@ export function handleHookEdit() {
     process.exit(0);
 }
 export async function handleInstallHook(projectRoot) {
+    // v0.26.5 — plugin-aware early-return. If we're running as a Claude
+    // Code plugin (CLAUDE_PLUGIN_ROOT set) the hooks are already declared
+    // in .claude-plugin/hooks/hooks.json and Claude Code wires them up
+    // on install. Calling install-hook in that context would write a
+    // duplicate entry to the user's settings.json and emit two hooks for
+    // every event. Bail early.
+    if (process.env.CLAUDE_PLUGIN_ROOT) {
+        console.log("token-pilot is running as a Claude Code plugin — hooks are already\n" +
+            "declared in .claude-plugin/hooks/hooks.json and registered by the\n" +
+            "plugin installer. `install-hook` is only needed for npm/npx setups.\n" +
+            "Skipping to avoid duplicate hook entries.");
+        process.exit(0);
+    }
     let hookOptions;
     try {
         const rawPath = fileURLToPath(new URL("./index.js", import.meta.url));
@@ -576,6 +595,22 @@ export async function handleDoctor() {
     const { join } = await import("node:path");
     const cwd = process.cwd();
     console.log(`token-pilot doctor v${version}\n`);
+    // ── Installation mode ──
+    // v0.26.5 — tell the user HOW token-pilot is installed. Matters
+    // because plugin users don't need `install-hook` (hooks come from
+    // .claude-plugin/hooks/hooks.json); npm users do. dev/worktree users
+    // are usually contributors running from a local checkout.
+    let installMode;
+    if (process.env.CLAUDE_PLUGIN_ROOT) {
+        installMode = `plugin (${process.env.CLAUDE_PLUGIN_ROOT})`;
+    }
+    else if (process.argv[1]?.includes("/.claude/worktrees/")) {
+        installMode = "dev / worktree (contributor)";
+    }
+    else {
+        installMode = "npm / npx";
+    }
+    console.log(`Install mode:   ${installMode}`);
     // ── Environment ──
     const nodeVersion = process.version;
     const nodeMajor = parseInt(nodeVersion.slice(1), 10);
@@ -677,6 +712,26 @@ export async function handleDoctor() {
     catch {
         /* ignore */
     }
+    // ── profile recommendation ──
+    // v0.26.4 — data-driven. Reads cumulative tool-calls.jsonl and suggests
+    // the narrowest TOKEN_PILOT_PROFILE that wouldn't hide any tool the
+    // user actually invokes. Never auto-applies; doctor just prints the
+    // env snippet and why.
+    try {
+        const { loadAllToolCalls } = await import("./core/tool-call-log.js");
+        const { recommendProfile, formatRecommendation } = await import("./server/profile-recommender.js");
+        const events = await loadAllToolCalls(cwd);
+        const rec = recommendProfile(events);
+        // Only print when there's actionable signal OR a clear "stay on full"
+        // with enough data — skip the noise when the log is empty.
+        if (rec.totalCalls > 0) {
+            console.log(formatRecommendation(rec));
+            console.log("");
+        }
+    }
+    catch {
+        /* doctor must never crash over an optional check */
+    }
     // ── CLAUDE.md hygiene ──
     try {
         const r = await assessClaudeMd(cwd);

package/dist/server/profile-recommender.d.ts

@@ -0,0 +1,48 @@
+/**
+ * v0.26.4 — data-driven profile recommendation.
+ *
+ * The user mandate: existing users who don't read CHANGELOG shouldn't
+ * be left carrying the full 22-tool tools/list payload forever just
+ * because we were afraid of a breaking default change.
+ *
+ * Approach: the doctor command reads cumulative .token-pilot/tool-calls.jsonl
+ * (introduced in v0.26.2) and classifies the user's actual usage:
+ *
+ *   - Every tool they used fits in NAV_TOOLS    → recommend `nav`
+ *   - Uses NAV + a subset of EDIT_EXTRAS        → recommend `edit`
+ *   - Uses full-only tools (test_summary,
+ *     code_audit, find_unused, session_*)      → recommend `full`
+ *
+ * The recommendation is *advisory*. We never auto-flip anyone's default;
+ * a user running through a rare but real tool like code_audit would
+ * lose it silently. Doctor prints the recommendation + the exact env
+ * snippet to paste into .mcp.json, and the copy nudges the user to act.
+ */
+import type { ToolCallEvent } from "../core/tool-call-log.js";
+import { type ToolProfile } from "./tool-profiles.js";
+export interface ProfileRecommendation {
+    /** The profile we'd pick if the user asked "what fits me?". */
+    recommended: ToolProfile;
+    /** One-sentence explanation printable by doctor. */
+    reason: string;
+    /** Number of distinct tools the user has ever called. */
+    uniqueToolsSeen: number;
+    /** Total calls in the log (across all sessions/projects). */
+    totalCalls: number;
+    /** Tools that would be filtered out under `recommended`. Empty when
+     *  recommended=full. */
+    wouldHide: string[];
+    /** True when we don't have enough data to claim more than "full". */
+    lowConfidence: boolean;
+}
+/**
+ * Pure analysis — takes raw tool-call events, returns a recommendation.
+ * Safe to unit-test without filesystem, network, or config.
+ */
+export declare function recommendProfile(events: readonly ToolCallEvent[]): ProfileRecommendation;
+/**
+ * Render a doctor-style multi-line block the caller can print verbatim.
+ * Pure.
+ */
+export declare function formatRecommendation(rec: ProfileRecommendation): string;
+//# sourceMappingURL=profile-recommender.d.ts.map

package/dist/server/profile-recommender.js

@@ -0,0 +1,102 @@
+/**
+ * v0.26.4 — data-driven profile recommendation.
+ *
+ * The user mandate: existing users who don't read CHANGELOG shouldn't
+ * be left carrying the full 22-tool tools/list payload forever just
+ * because we were afraid of a breaking default change.
+ *
+ * Approach: the doctor command reads cumulative .token-pilot/tool-calls.jsonl
+ * (introduced in v0.26.2) and classifies the user's actual usage:
+ *
+ *   - Every tool they used fits in NAV_TOOLS    → recommend `nav`
+ *   - Uses NAV + a subset of EDIT_EXTRAS        → recommend `edit`
+ *   - Uses full-only tools (test_summary,
+ *     code_audit, find_unused, session_*)      → recommend `full`
+ *
+ * The recommendation is *advisory*. We never auto-flip anyone's default;
+ * a user running through a rare but real tool like code_audit would
+ * lose it silently. Doctor prints the recommendation + the exact env
+ * snippet to paste into .mcp.json, and the copy nudges the user to act.
+ */
+import { NAV_TOOLS, EDIT_EXTRAS } from "./tool-profiles.js";
+/** Below this the sample is too small to make a confident recommendation. */
+const MIN_SAMPLE_CALLS = 20;
+/**
+ * Pure analysis — takes raw tool-call events, returns a recommendation.
+ * Safe to unit-test without filesystem, network, or config.
+ */
+export function recommendProfile(events) {
+    const used = new Set();
+    for (const e of events)
+        used.add(e.tool);
+    const totalCalls = events.length;
+    const uniqueToolsSeen = used.size;
+    if (totalCalls < MIN_SAMPLE_CALLS) {
+        return {
+            recommended: "full",
+            reason: `Only ${totalCalls} call(s) logged — need ≥${MIN_SAMPLE_CALLS} to recommend a narrower profile.`,
+            uniqueToolsSeen,
+            totalCalls,
+            wouldHide: [],
+            lowConfidence: true,
+        };
+    }
+    const allInNav = [...used].every((t) => NAV_TOOLS.has(t));
+    if (allInNav) {
+        return {
+            recommended: "nav",
+            reason: `Every tool you've used (${uniqueToolsSeen} distinct) is part of the nav subset. You're a read-only explorer.`,
+            uniqueToolsSeen,
+            totalCalls,
+            wouldHide: [
+                ...[...EDIT_EXTRAS].filter((t) => !used.has(t)),
+                /* full-only — we don't enumerate here, keep the list short */
+            ],
+            lowConfidence: false,
+        };
+    }
+    const allInEditOrBelow = [...used].every((t) => NAV_TOOLS.has(t) || EDIT_EXTRAS.has(t));
+    if (allInEditOrBelow) {
+        return {
+            recommended: "edit",
+            reason: `You use edit-preparation tools (read_for_edit, batch reads) but never reach for full-only tools like code_audit/test_summary/find_unused.`,
+            uniqueToolsSeen,
+            totalCalls,
+            wouldHide: [],
+            lowConfidence: false,
+        };
+    }
+    // Uses at least one full-only tool — stay on full.
+    const fullOnlyUsed = [...used].filter((t) => !NAV_TOOLS.has(t) && !EDIT_EXTRAS.has(t));
+    return {
+        recommended: "full",
+        reason: `You actually use full-only tools (${fullOnlyUsed.slice(0, 3).join(", ")}${fullOnlyUsed.length > 3 ? ", …" : ""}). Don't trim.`,
+        uniqueToolsSeen,
+        totalCalls,
+        wouldHide: [],
+        lowConfidence: false,
+    };
+}
+/**
+ * Render a doctor-style multi-line block the caller can print verbatim.
+ * Pure.
+ */
+export function formatRecommendation(rec) {
+    const lines = [];
+    lines.push(`── profile recommendation ──`);
+    lines.push(`  data:         ${rec.totalCalls} calls, ${rec.uniqueToolsSeen} distinct tools`);
+    lines.push(`  recommend:    TOKEN_PILOT_PROFILE=${rec.recommended}`);
+    lines.push(`  why:          ${rec.reason}`);
+    if (rec.recommended !== "full") {
+        lines.push(`  savings:      ~${rec.recommended === "nav" ? "2200 tokens (−54%)" : "1000 tokens (−25%)"} on every tools/list response`);
+        lines.push(`  apply:        add "env": { "TOKEN_PILOT_PROFILE": "${rec.recommended}" } to your token-pilot entry in .mcp.json`);
+    }
+    else if (rec.lowConfidence) {
+        lines.push(`  action:       keep default (full). Re-run \`token-pilot doctor\` after a few real sessions for a data-backed suggestion.`);
+    }
+    else {
+        lines.push(`  action:       keep default (full). You're using what you have.`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=profile-recommender.js.map

package/dist/server/token-estimates.d.ts

@@ -2,8 +2,22 @@
  * Token estimation functions for analytics.
  * Used to calculate "tokens would be" for honest savings reporting.
  */
-import type { FileCache } from '../core/file-cache.js';
-import type { SavingsCategory } from '../core/session-analytics.js';
+import type { FileCache } from "../core/file-cache.js";
+import type { SavingsCategory } from "../core/session-analytics.js";
+/**
+ * Honest savings classification for a tool's text output.
+ *
+ * Standalone (pure) so it can be unit-tested without spinning up the
+ * full token-estimates closure. Kept here because it's semantically
+ * tied to how this module reports wouldBe/returned pairs.
+ *
+ * v0.26.1 adds the 'none' branch: smart_read's small-file pass-through
+ * returns the file verbatim with a tiny header. Claiming wouldBe =
+ * fullFile for those calls was the root cause of the -2% "negative
+ * savings" line Opus 4.7 reported. With 'none', the recorder sets
+ * wouldBe = returned → 0% savings, no ghost overhead.
+ */
+export declare function detectSavingsCategoryPure(text: string): SavingsCategory;
 /**
  * Creates token estimation functions bound to a project context.
  * Uses getter for projectRoot since it may change on auto-detect.
@@ -26,6 +40,6 @@ export declare function createTokenEstimates(getProjectRoot: () => string, fileC
         externalDeps?: string[];
         changeCount?: number;
     }) => Promise<number>;
-    detectSavingsCategory: (text: string) => SavingsCategory;
+    detectSavingsCategory: typeof detectSavingsCategoryPure;
 };
 //# sourceMappingURL=token-estimates.d.ts.map