token-pilot 0.24.2 → 0.26.6

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

@@ -1,4 +1,20 @@
 #!/usr/bin/env node
+// v0.26.6 — handle EPIPE silently. Piping `token-pilot doctor | head -5`
+// causes EPIPE once head closes stdin. Classic Node.js CLI wart. Default
+// behaviour is a red "throw er; // Unhandled 'error' event" stacktrace,
+// which scares users who just wanted a quick look. Standard fix: swallow
+// EPIPE on stdout/stderr and exit 0 — any CLI piped to head|less|grep
+// behaves this way.
+process.stdout.on("error", (err) => {
+    if (err.code === "EPIPE")
+        process.exit(0);
+    throw err;
+});
+process.stderr.on("error", (err) => {
+    if (err.code === "EPIPE")
+        process.exit(0);
+    throw err;
+});
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { readFileSync, realpathSync, appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
@@ -28,6 +44,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 +222,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 +549,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 +611,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 +728,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

package/dist/server/token-estimates.js

@@ -2,9 +2,31 @@
  * Token estimation functions for analytics.
  * Used to calculate "tokens would be" for honest savings reporting.
  */
-import { estimateTokens } from '../core/token-estimator.js';
-import { resolveSafePath } from '../core/validation.js';
-import { CODE_EXTENSIONS } from '../handlers/outline.js';
+import { estimateTokens } from "../core/token-estimator.js";
+import { resolveSafePath } from "../core/validation.js";
+import { CODE_EXTENSIONS } from "../handlers/outline.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 function detectSavingsCategoryPure(text) {
+    if (text.startsWith("REMINDER:") || text.startsWith("DEDUP:"))
+        return "dedup";
+    if (text.includes("returned in full, below threshold") ||
+        text.includes("returned in full, outline not smaller")) {
+        return "none";
+    }
+    return "compression";
+}
 /**
  * Creates token estimation functions bound to a project context.
  * Uses getter for projectRoot since it may change on auto-detect.
@@ -16,8 +38,8 @@ export function createTokenEstimates(getProjectRoot, fileCache) {
             const cached = fileCache.get(absPath);
             if (cached)
                 return estimateTokens(cached.content);
-            const { readFile: readFileAsync } = await import('node:fs/promises');
-            const content = await readFileAsync(absPath, 'utf-8');
+            const { readFile: readFileAsync } = await import("node:fs/promises");
+            const content = await readFileAsync(absPath, "utf-8");
             return estimateTokens(content);
         }
         catch {
@@ -26,34 +48,46 @@ export function createTokenEstimates(getProjectRoot, fileCache) {
     }
     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'],
+            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',
+                "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'],
+            architecture: ["README.md"],
         };
         let total = 0;
         const seen = new Set();
@@ -65,15 +99,17 @@ export function createTokenEstimates(getProjectRoot, fileCache) {
                 total += await fullFileTokens(file);
             }
         }
-        if (includeSections.includes('ci')) {
+        if (includeSections.includes("ci")) {
             try {
-                const { readdir: readDirAsync } = await import('node:fs/promises');
-                const workflowDir = resolveSafePath(getProjectRoot(), '.github/workflows');
-                const workflowFiles = await readDirAsync(workflowDir, { withFileTypes: true });
+                const { readdir: readDirAsync } = await import("node:fs/promises");
+                const workflowDir = resolveSafePath(getProjectRoot(), ".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'))
+                    if (!file.name.endsWith(".yml") && !file.name.endsWith(".yaml"))
                         continue;
                     total += await fullFileTokens(`.github/workflows/${file.name}`);
                 }
@@ -82,7 +118,7 @@ export function createTokenEstimates(getProjectRoot, fileCache) {
                 // ignore missing workflows dir
             }
         }
-        if (includeSections.includes('architecture')) {
+        if (includeSections.includes("architecture")) {
             total += 200;
         }
         return total;
@@ -90,8 +126,8 @@ export function createTokenEstimates(getProjectRoot, fileCache) {
     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 { readdir: readDirAsync } = await import("node:fs/promises");
+            const { resolve: resolvePath } = await import("node:path");
             const absDir = resolveSafePath(getProjectRoot(), relativePath);
             const sampledFiles = [];
             let totalFiles = 0;
@@ -99,7 +135,7 @@ export function createTokenEstimates(getProjectRoot, fileCache) {
                 const entries = await readDirAsync(dirPath, { withFileTypes: true });
                 for (const entry of entries) {
                     if (entry.isFile()) {
-                        const ext = entry.name.split('.').pop()?.toLowerCase() ?? '';
+                        const ext = entry.name.split(".").pop()?.toLowerCase() ?? "";
                         if (!CODE_EXTENSIONS.has(ext))
                             continue;
                         totalFiles++;
@@ -186,11 +222,7 @@ export function createTokenEstimates(getProjectRoot, fileCache) {
         total += (meta.changeCount ?? 0) * 40;
         return total;
     }
-    function detectSavingsCategory(text) {
-        if (text.startsWith('REMINDER:') || text.startsWith('DEDUP:'))
-            return 'dedup';
-        return 'compression';
-    }
+    const detectSavingsCategory = detectSavingsCategoryPure;
     return {
         fullFileTokens,
         estimateProjectOverviewWorkflowTokens,

package/dist/server/tool-definitions.js

@@ -287,7 +287,7 @@ export const TOOL_DEFINITIONS = [
     // --- Search & navigation ---
     {
         name: "find_usages",
-        description: "Use INSTEAD OF Grep for finding symbol references. Semantic search — groups by: definitions, imports, usages. Supports scope, kind, limit, lang filters. Use context_lines to include surrounding code.",
+        description: "Use INSTEAD OF Grep for finding symbol references. Semantic search — groups by: definitions, imports, usages. Supports scope, kind, limit, lang filters. Use context_lines to include surrounding code. HINT: for very short / generic symbols (≤4 chars like `id`, `err`, `Cmd`, `db`) Grep is usually cheaper than find_usages — the semantic grouping doesn't pay off when the symbol resolves ambiguously across thousands of files.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/server/tool-profiles.d.ts

@@ -0,0 +1,46 @@
+/**
+ * v0.26.3 — tool profiles.
+ *
+ * Idea lifted honestly from Token Savior's TOKEN_SAVIOR_PROFILE. When an
+ * MCP server advertises 22 tools, every tools/list response costs the
+ * agent ~3 k tokens before it does anything. Most sessions don't need
+ * every tool — a code-review agent uses smart_read + find_usages +
+ * outline and nothing else. A profile lets the user ship a narrower
+ * tools/list while keeping the handlers live (so a subagent or another
+ * user in the same server can still reach the full set if they know
+ * the name).
+ *
+ * Three profiles:
+ *   - full  (default): everything, same as pre-v0.26.3.
+ *   - nav  : read-only exploration. smart_read, outline, find_usages,
+ *            read_symbol, project_overview, module_info, related_files,
+ *            explore_area, smart_log, smart_diff.
+ *   - edit : nav + batch reads + everything Edit needs to hit a symbol
+ *            precisely. Adds read_symbols, read_range, read_section,
+ *            read_diff, read_for_edit, smart_read_many.
+ *
+ * Selection: TOKEN_PILOT_PROFILE=nav|edit|full env var. Unknown values
+ * fall back to full with a stderr warning. Silent on missing env.
+ */
+export type ToolProfile = "full" | "nav" | "edit";
+export declare const PROFILE_NAMES: readonly ToolProfile[];
+/** Minimum nav profile — exploration only, no editing support. */
+export declare const NAV_TOOLS: ReadonlySet<string>;
+/** Edit profile adds batch reads + edit-preparation tools. */
+export declare const EDIT_EXTRAS: ReadonlySet<string>;
+/**
+ * Decide which tools the LLM sees in tools/list given a profile.
+ * Pure — safe to unit-test without spinning up the server.
+ *
+ * Tool names NOT matched by any profile rule (e.g. future additions)
+ * fall into 'full' only, to stay conservative by default.
+ */
+export declare function filterToolsByProfile<T extends {
+    name: string;
+}>(tools: readonly T[], profile: ToolProfile): T[];
+/**
+ * Parse the TOKEN_PILOT_PROFILE env value. Unknown values get a warning
+ * and fall back to full — we never silently apply a guess.
+ */
+export declare function parseProfileEnv(envValue: string | undefined, warn?: (msg: string) => void): ToolProfile;
+//# sourceMappingURL=tool-profiles.d.ts.map