token-pilot 0.23.4 → 0.23.7

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.23.4",
+  "version": "0.23.7",
   "description": "Enforcement layer for token-efficient AI coding: MCP-first hook with structural denial summaries, SessionStart reminder, bless-agents CLI, and six tp-* subagents — works for every agent including those without MCP access.",
   "author": "token-pilot",
   "license": "MIT",

package/CHANGELOG.md

@@ -5,6 +5,65 @@ 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.23.7] - 2026-04-18
+
+### Changed — per-agent `model:` selection for cheap, format-bound work
+
+Claude Code allows each subagent to declare its own model in frontmatter (or `inherit` from the main agent). We've been relying on the user's global `CLAUDE_CODE_SUBAGENT_MODEL` env var as a blunt switch — that doesn't fit because some `tp-*` agents need real reasoning (debugger, impact analyzer, refactor planner) while others are pure format work. Moved three agents to **haiku-4.5** explicitly:
+
+- **`tp-commit-writer`** — classifies diff → Conventional type, drafts short message. Context-bound, no architectural decisions.
+- **`tp-session-restorer`** — parses `latest.md` + git status, emits a fixed-shape briefing. Pure transformation.
+- **`tp-onboard`** — pulls project_overview and retells it in an orientation map. Format-bound.
+
+The other 11 agents keep `inherit` — they do enough reasoning (intent, risk classification, call-tree traversal) that haiku would regress them. `tp-dead-code-finder` and `tp-audit-scanner` stay inherit for now; we'll revisit after real-world usage shows whether cross-check accuracy holds on haiku.
+
+**User is NOT asked to set `CLAUDE_CODE_SUBAGENT_MODEL`.** The selection is per-agent and shipped with the template — predictable, rollback-friendly (one line per agent).
+
+### Planned
+
+- **TP-z64** (v0.28 backlog) — expanded tp-* roster with combo-agents that pair novel MCP-tool combinations for niche workflows (review-impact, test-coverage-gapper, api-surface-tracker, dep-health, incident-timeline). Must be brainstormed with names + triggers before implementation; deferred until v0.24 onboarding wizard ships and baseline stabilises.
+- **v0.24.0** — onboarding wizard (doctor-warnings → one-step applied): writes `MAX_THINKING_TOKENS=10000` + `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50` to `~/.claude/settings.json`, generates `.claudeignore` if missing. Does NOT set `CLAUDE_CODE_SUBAGENT_MODEL` — per-agent model now handles that.
+
+### Numbers
+- 910 tests green, `tsc --noEmit` clean, 14 agents built.
+
+## [0.23.6] - 2026-04-18
+
+### Fixed — five findings from a live user audit
+
+A real-world QA pass on a large Nuxt repo surfaced five issues. All addressed.
+
+**1. `read_symbols` regression (−16% tokens saved).** When the caller requested nearly every symbol of a file, the sum of bodies + N × per-symbol metadata exceeded a raw Read of the whole file — batch tool was worse than no batch. Two fixes:
+- Handler now includes an anti-pattern guard: if ≥ 70 % of the file's line coverage is requested AND ≥ 3 symbols, it refuses with a short advisory pointing at `smart_read` / `read_for_edit` / bounded `Read`.
+- Server-side `tokensWouldBe` for `read_symbols` corrected to reflect reality: baseline is "N individual `read_symbol` calls", not "one raw Read of the whole file". Saved now shows the real win — deduped headers + shared file open — instead of a misleading figure that flipped negative in the edge case.
+
+**2. Tool description updated.** `read_symbols` now says *"BEST FIT: 3–8 symbols in one file … if you'd request ≥ 70 % of the file's symbols, the handler refuses and points you to smart_read"*. Prior docstring didn't give agents a decision rule, so they used it reflexively.
+
+**3. `tp-commit-writer` trivial-diff guard.** The agent's `description:` was unconditional — reviewers triggered it on a whitespace-only docs diff (239 s subagent spawn for a one-line message). Now it explicitly says *"Do NOT use for docs-only, whitespace-only, or < 20-line diffs — the user can write those manually faster than a subagent spawn"*.
+
+**4. `docs/token-pilot-dir.md` — side-files layout reference.** Users saw `hook-events.jsonl` and `hook-denied.jsonl` appear but no snapshots/context-registries/docs directories, wondered if features were broken. They're lazy-created: each sub-path only appears when the triggering feature fires. New doc lists every path, who writes it, when, and whether to commit. Recommended `.gitignore` stanza included.
+
+**5. `tp-migration-scout` context-mode "fallback" — false alarm.** Audit reported the agent announced a fallback from an unavailable `context-mode` tool. Verified: `tp-migration-scout.md` does not advertise `context-mode` anywhere. The agent self-reported a fallback it invented. No code change needed; noted for future behavioural-harness work (TP-q33b).
+
+### Numbers
+- 910 tests green (+3 regression tests for `read_symbols` guard), `tsc --noEmit` clean.
+
+## [0.23.5] - 2026-04-18
+
+### Changed — ast-index is now a hard npm dependency
+
+Until now `ast-index` was auto-downloaded from GitHub on first MCP-server start. That worked but had weak spots: exotic architectures, corporate proxies, ZIP-only Windows path — any of them left the user with a token-pilot that couldn't do structural reads until they manually ran `install-ast-index`. Users also rightly expected *"I just `npm install`d the package — it should just work"*.
+
+- **`@ast-index/cli@^3.38.0` moved from implicit auto-install to `dependencies`.** Regular `npm install token-pilot` now pulls the main package + the correct platform-specific native binary (`@ast-index/cli-<platform>-<arch>`) as a transitive dep, same pattern Rollup / esbuild / swc use. Removed the old `peerDependencies: ast-index` stub — confusing and never served a purpose.
+- **New `findViaBundledDep()` is first in the binary resolution order** (after config override, before system PATH). Walks up from our own module to `node_modules/@ast-index/cli/bin/ast-index`; works whether npm created `.bin/ast-index` symlinks or not.
+- **`BinaryStatus.source` gains `"bundled"`** to distinguish the new path from `system` / `npm` / `managed` / `none`. `doctor` honours it.
+- **`scripts/postinstall.mjs` is a safety net** — runs after `npm install`, checks `findBinary()` result; if nothing found, fires the GitHub download fallback. **Never fails the install** — any error ends in a single stderr warning and exit 0. Respects `TOKEN_PILOT_SKIP_POSTINSTALL=1` and `CI=true` for sandboxed builds.
+
+Result: fresh `npm install token-pilot` gives a ready-to-work binary on macOS (arm64 + x64), Linux (arm64 + x64), Windows x64 — no first-run download step, no stderr noise about "ast-index not found, downloading…".
+
+### Numbers
+- 907 tests green, `tsc --noEmit` clean. `npm install @ast-index/cli` end-to-end verified against actual npm registry.
+
 ## [0.23.4] - 2026-04-18
 
 ### Fixed

package/dist/agents/tp-audit-scanner.md

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__read_section
   - Grep
   - Read
-token_pilot_version: "0.23.4"
+token_pilot_version: "0.23.7"
 token_pilot_body_hash: a740dc6c928d11d7c2c5fbaa953c50b0e35f2abc2dd6e5ef5117bf469a2d0207
 ---
 

package/dist/agents/tp-commit-writer.md

@@ -1,13 +1,14 @@
 ---
 name: tp-commit-writer
-description: PROACTIVELY use this when the user is about to commit, asks "write a commit message", or says "commit this". Reads staged diff, verifies tests pass, drafts Conventional Commit. Refuses mixed diffs (asks to split), failing tests, or empty stage. Do NOT use to explain already-made commits.
+model: claude-haiku-4-5-20251001
+description: PROACTIVELY use this when the user is about to commit a NON-TRIVIAL change (new feature, fix, refactor) and asks "write a commit message". Reads staged diff, verifies tests pass, drafts Conventional Commit. Refuses mixed diffs (asks to split), failing tests, or empty stage. Do NOT use for docs-only, whitespace-only, or < 20-line diffs — the user can write those manually faster than a subagent spawn. Do NOT use to explain already-made commits.
 tools:
   - mcp__token-pilot__smart_diff
   - mcp__token-pilot__smart_log
   - mcp__token-pilot__test_summary
   - mcp__token-pilot__outline
   - Bash
-token_pilot_version: "0.23.4"
+token_pilot_version: "0.23.7"
 token_pilot_body_hash: 559a0b61d20974bf33e35bc4c80dcf1b41d10d4df46cf9d05d3d5620713cd46f
 ---
 

package/dist/agents/tp-dead-code-finder.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__related_files
   - Grep
   - Read
-token_pilot_version: "0.23.4"
+token_pilot_version: "0.23.7"
 token_pilot_body_hash: 482e33ba566dc75d87753d980267fb2e01763e5924612efd54ec89993b5e12fd
 ---
 

package/dist/agents/tp-debugger.md

@@ -11,7 +11,7 @@ tools:
   - mcp__token-pilot__read_for_edit
   - Read
   - Bash
-token_pilot_version: "0.23.4"
+token_pilot_version: "0.23.7"
 token_pilot_body_hash: 04864ae0bf0689863d7de9f4c0b44b293087b34098ad2771837e491d37dab953
 ---
 

package/dist/agents/tp-history-explorer.md

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__outline
   - Bash
   - Read
-token_pilot_version: "0.23.4"
+token_pilot_version: "0.23.7"
 token_pilot_body_hash: b2daca007e959eaf26bf9a4d92ba36c3aa277a51de4ca4db674833d36acbe11b
 ---
 

package/dist/agents/tp-impact-analyzer.md

@@ -11,7 +11,7 @@ tools:
   - mcp__token-pilot__smart_read_many
   - mcp__token-pilot__read_symbols
   - Read
-token_pilot_version: "0.23.4"
+token_pilot_version: "0.23.7"
 token_pilot_body_hash: 0be2620ce0303f912f6b3334f261d169f064970c0d16602fa1e76db4cb2ea441
 ---
 

package/dist/agents/tp-migration-scout.md

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__smart_read_many
   - Grep
   - Glob
-token_pilot_version: "0.23.4"
+token_pilot_version: "0.23.7"
 token_pilot_body_hash: cf32cdee777430ecc6732db32b3f883a685c8a02b6dc93379d71b15555e79b3e
 ---
 

package/dist/agents/tp-onboard.md

@@ -1,5 +1,6 @@
 ---
 name: tp-onboard
+model: claude-haiku-4-5-20251001
 description: PROACTIVELY use this when the user is exploring an unfamiliar codebase — asks "how is this organised", "what does this project do", "where do I start reading", or starts any conversation in a repo the main agent doesn't know. Orientation map only (layout, entry points, modules); does NOT drill into implementation.
 tools:
   - mcp__token-pilot__project_overview
@@ -9,7 +10,7 @@ tools:
   - mcp__token-pilot__smart_read
   - mcp__token-pilot__smart_read_many
   - mcp__token-pilot__read_section
-token_pilot_version: "0.23.4"
+token_pilot_version: "0.23.7"
 token_pilot_body_hash: ae0b86eaffaf34bf283b94b5572481fa8c2d6a2a25193f1173b70bef0fbe1919
 ---
 

package/dist/agents/tp-pr-reviewer.md

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__smart_read_many
   - mcp__token-pilot__read_for_edit
   - Read
-token_pilot_version: "0.23.4"
+token_pilot_version: "0.23.7"
 token_pilot_body_hash: eb9fb7f87d9ab61c5b18248a40b283008b5d73414ddb2e3094ff0826e7e463d0
 ---
 

package/dist/agents/tp-refactor-planner.md

@@ -7,7 +7,7 @@ tools:
   - mcp__token-pilot__read_diff
   - mcp__token-pilot__outline
   - mcp__token-pilot__read_symbol
-token_pilot_version: "0.23.4"
+token_pilot_version: "0.23.7"
 token_pilot_body_hash: a058518619fd6e2def0c9226f6c70438a5e0a80efe680c935414ecd7e1b14a4f
 ---
 

package/dist/agents/tp-run.md

@@ -15,7 +15,7 @@ tools:
   - Grep
   - Glob
   - Bash
-token_pilot_version: "0.23.4"
+token_pilot_version: "0.23.7"
 token_pilot_body_hash: d665d57085db38077d0eeab74bda8bdb84c9ad59688495486059af5d3fac67cf
 ---
 

package/dist/agents/tp-session-restorer.md

@@ -1,5 +1,6 @@
 ---
 name: tp-session-restorer
+model: claude-haiku-4-5-20251001
 description: PROACTIVELY use this as the FIRST step after /clear, compaction, or a fresh window when a recent session_snapshot exists on disk. Reads snapshot + git status + saved docs, returns a ≤200-token briefing. Do NOT use mid-task.
 tools:
   - mcp__token-pilot__smart_read
@@ -8,7 +9,7 @@ tools:
   - mcp__token-pilot__session_budget
   - Bash
   - Read
-token_pilot_version: "0.23.4"
+token_pilot_version: "0.23.7"
 token_pilot_body_hash: 35b7f333a28c94e7dc89fcc3171703c4b466225f55cd5c701b7592f4f6486440
 ---
 

package/dist/agents/tp-test-triage.md

@@ -7,7 +7,7 @@ tools:
   - mcp__token-pilot__read_range
   - mcp__token-pilot__find_usages
   - mcp__token-pilot__read_symbol
-token_pilot_version: "0.23.4"
+token_pilot_version: "0.23.7"
 token_pilot_body_hash: 255912c47661d203c8f9a735237bc419f97e937f788a01811bbe126ee3dd5878
 ---
 

package/dist/agents/tp-test-writer.md

@@ -12,7 +12,7 @@ tools:
   - Write
   - Edit
   - Bash
-token_pilot_version: "0.23.4"
+token_pilot_version: "0.23.7"
 token_pilot_body_hash: 533b3d2387e631a24291314b2b8ad8c3e01c19e0b9ec1d3fe08ae0011f0c73f9
 ---
 

package/dist/ast-index/binary-manager.d.ts

@@ -2,7 +2,7 @@ export interface BinaryStatus {
     available: boolean;
     path: string;
     version: string | null;
-    source: 'system' | 'npm' | 'managed' | 'none';
+    source: "system" | "npm" | "managed" | "bundled" | "none";
 }
 /**
  * Find ast-index binary: config → system PATH → npm global → managed install.

package/dist/ast-index/binary-manager.js

@@ -1,16 +1,17 @@
-import { execFile } from 'node:child_process';
-import { createWriteStream } from 'node:fs';
-import { chmod, mkdir, access, rm } from 'node:fs/promises';
-import { resolve } from 'node:path';
-import { pipeline } from 'node:stream/promises';
-import { createGunzip } from 'node:zlib';
-import { homedir, platform, arch } from 'node:os';
-import { get as httpsGet } from 'node:https';
-import { get as httpGet } from 'node:http';
-import { tarExtract } from './tar-extract.js';
-const REPO = 'defendend/Claude-ast-index-search';
-const BINARY_NAME = platform() === 'win32' ? 'ast-index.exe' : 'ast-index';
-const INSTALL_DIR = resolve(homedir(), '.token-pilot', 'bin');
+import { execFile } from "node:child_process";
+import { createWriteStream } from "node:fs";
+import { chmod, mkdir, access, rm } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+import { homedir, platform, arch } from "node:os";
+import { get as httpsGet } from "node:https";
+import { get as httpGet } from "node:http";
+import { tarExtract } from "./tar-extract.js";
+const REPO = "defendend/Claude-ast-index-search";
+const BINARY_NAME = platform() === "win32" ? "ast-index.exe" : "ast-index";
+const INSTALL_DIR = resolve(homedir(), ".token-pilot", "bin");
 /**
  * Find ast-index binary: config → system PATH → npm global → managed install.
  */
@@ -19,30 +20,42 @@ export async function findBinary(configPath) {
     if (configPath) {
         const version = await getBinaryVersion(configPath);
         if (version) {
-            return { available: true, path: configPath, version, source: 'system' };
+            return { available: true, path: configPath, version, source: "system" };
         }
     }
-    // 2. System PATH
+    // 2. Bundled npm dep — @ast-index/cli alongside our own install. This is
+    //    the default path when the user ran `npm install token-pilot`: npm
+    //    resolves per-platform binary (@ast-index/cli-linux-x64 etc.) as an
+    //    optional dep of @ast-index/cli, symlinks ast-index into
+    //    node_modules/.bin alongside our own bin/, and everything "just works".
+    const bundledPath = await findViaBundledDep();
+    if (bundledPath) {
+        const version = await getBinaryVersion(bundledPath);
+        if (version) {
+            return { available: true, path: bundledPath, version, source: "bundled" };
+        }
+    }
+    // 3. System PATH
     const systemPath = await findInPath();
     if (systemPath) {
         const version = await getBinaryVersion(systemPath);
-        return { available: true, path: systemPath, version, source: 'system' };
+        return { available: true, path: systemPath, version, source: "system" };
     }
     // 3. npm global install (@ast-index/cli)
     const npmPath = await findViaNpmBin();
     if (npmPath) {
         const version = await getBinaryVersion(npmPath);
         if (version) {
-            return { available: true, path: npmPath, version, source: 'npm' };
+            return { available: true, path: npmPath, version, source: "npm" };
         }
     }
     // 4. Managed install (GitHub download)
     const managedPath = resolve(INSTALL_DIR, BINARY_NAME);
     const version = await getBinaryVersion(managedPath);
     if (version) {
-        return { available: true, path: managedPath, version, source: 'managed' };
+        return { available: true, path: managedPath, version, source: "managed" };
     }
-    return { available: false, path: '', version: null, source: 'none' };
+    return { available: false, path: "", version: null, source: "none" };
 }
 /**
  * Install ast-index: tries npm global first (all platforms), falls back to GitHub download.
@@ -60,9 +73,9 @@ export async function installBinary(onProgress) {
     return installViaNpmFallback(log);
 }
 async function installViaNpm(onProgress) {
-    onProgress('Installing @ast-index/cli via npm...');
+    onProgress("Installing @ast-index/cli via npm...");
     await new Promise((resolve, reject) => {
-        execFile('npm', ['install', '-g', '@ast-index/cli'], { timeout: 120_000 }, (err, _stdout, stderr) => {
+        execFile("npm", ["install", "-g", "@ast-index/cli"], { timeout: 120_000 }, (err, _stdout, stderr) => {
             if (err)
                 reject(new Error(stderr.trim() || err.message));
             else
@@ -71,11 +84,11 @@ async function installViaNpm(onProgress) {
     });
     const binPath = await findViaNpmBin();
     if (!binPath) {
-        throw new Error('@ast-index/cli installed but binary not found in npm prefix');
+        throw new Error("@ast-index/cli installed but binary not found in npm prefix");
     }
     const version = await getBinaryVersion(binPath);
     onProgress(`Installed ast-index ${version} via npm at ${binPath}`);
-    return { available: true, path: binPath, version, source: 'npm' };
+    return { available: true, path: binPath, version, source: "npm" };
 }
 async function installViaNpmFallback(onProgress) {
     // Determine platform/arch
@@ -84,29 +97,29 @@ async function installViaNpmFallback(onProgress) {
     if (!plat || !ar) {
         throw new Error(`Unsupported platform: ${platform()} ${arch()}`);
     }
-    onProgress('Fetching latest release info...');
+    onProgress("Fetching latest release info...");
     const release = await fetchLatestRelease();
     const assetName = buildAssetName(release.tag, plat, ar);
-    const asset = release.assets.find(a => a.name === assetName);
+    const asset = release.assets.find((a) => a.name === assetName);
     if (!asset) {
-        throw new Error(`No binary found for ${plat}-${ar}. Available: ${release.assets.map(a => a.name).join(', ')}`);
+        throw new Error(`No binary found for ${plat}-${ar}. Available: ${release.assets.map((a) => a.name).join(", ")}`);
     }
     onProgress(`Downloading ${asset.name} (${(asset.size / 1024 / 1024).toFixed(1)}MB)...`);
     await mkdir(INSTALL_DIR, { recursive: true });
     const tmpPath = resolve(INSTALL_DIR, `${BINARY_NAME}.tmp`);
     const finalPath = resolve(INSTALL_DIR, BINARY_NAME);
     try {
-        if (assetName.endsWith('.tar.gz')) {
+        if (assetName.endsWith(".tar.gz")) {
             await downloadAndExtractTarGz(asset.url, INSTALL_DIR, BINARY_NAME);
         }
         else {
             await downloadFile(asset.url, tmpPath);
-            throw new Error('ZIP extraction not yet supported. Please use: npm install -g @ast-index/cli');
+            throw new Error("ZIP extraction not yet supported. Please use: npm install -g @ast-index/cli");
         }
         await chmod(finalPath, 0o755);
         const version = await getBinaryVersion(finalPath);
         onProgress(`Installed ast-index ${version} to ${finalPath}`);
-        return { available: true, path: finalPath, version, source: 'managed' };
+        return { available: true, path: finalPath, version, source: "managed" };
     }
     catch (err) {
         try {
@@ -133,7 +146,7 @@ export async function checkBinaryUpdate(currentPath) {
             getBinaryVersion(currentPath),
             fetchLatestRelease(),
         ]);
-        const latest = release.tag.replace(/^v/, '');
+        const latest = release.tag.replace(/^v/, "");
         if (!current) {
             return { current: null, latest, updateAvailable: false };
         }
@@ -151,8 +164,8 @@ export async function checkBinaryUpdate(currentPath) {
  * Compare two semver strings. Returns true if `latest` is newer than `current`.
  */
 export function isNewerVersion(current, latest) {
-    const c = current.replace(/^v/, '').split('.').map(Number);
-    const l = latest.replace(/^v/, '').split('.').map(Number);
+    const c = current.replace(/^v/, "").split(".").map(Number);
+    const l = latest.replace(/^v/, "").split(".").map(Number);
     for (let i = 0; i < Math.max(c.length, l.length); i++) {
         const cv = c[i] ?? 0;
         const lv = l[i] ?? 0;
@@ -164,6 +177,48 @@ export function isNewerVersion(current, latest) {
     return false;
 }
 // --- Internal helpers ---
+/**
+ * Find ast-index bundled as a direct dependency of token-pilot. Walks up
+ * from this module (dist/ast-index/binary-manager.js → node_modules/…/
+ * @ast-index/cli/bin/ast-index) looking for the standard npm layout.
+ *
+ * Three locations are tried, in order of how npm installs usually resolve:
+ *   - peer dir    : node_modules/.bin/ast-index  (our own node_modules)
+ *   - parent dir  : ../../.bin/ast-index        (hoisted install)
+ *   - bin script  : ../@ast-index/cli/bin/ast-index (platform-specific
+ *     sub-package delegates to this JS shim)
+ *
+ * Returns null on any filesystem error — auto-install downstream still
+ * works; we only lose the "prefer local" optimisation.
+ */
+async function findViaBundledDep() {
+    let here;
+    try {
+        here = dirname(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return null;
+    }
+    const candidates = [
+        // .../node_modules/token-pilot/dist/ast-index → up to .../node_modules/.bin
+        resolve(here, "..", "..", "..", ".bin", BINARY_NAME),
+        // Hoisted npm layout (same but one level deeper)
+        resolve(here, "..", "..", "..", "..", ".bin", BINARY_NAME),
+        // Direct module bin script (platform-agnostic JS shim in @ast-index/cli)
+        resolve(here, "..", "..", "..", "@ast-index", "cli", "bin", BINARY_NAME),
+        resolve(here, "..", "..", "..", "..", "@ast-index", "cli", "bin", BINARY_NAME),
+    ];
+    for (const candidate of candidates) {
+        try {
+            await access(candidate);
+            return candidate;
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return null;
+}
 /**
  * Find ast-index binary installed via `npm install -g @ast-index/cli`.
  * Checks the npm global prefix bin directory.
@@ -171,7 +226,7 @@ export function isNewerVersion(current, latest) {
 async function findViaNpmBin() {
     try {
         const prefix = await new Promise((resolve, reject) => {
-            execFile('npm', ['config', 'get', 'prefix'], { timeout: 3000 }, (err, stdout) => {
+            execFile("npm", ["config", "get", "prefix"], { timeout: 3000 }, (err, stdout) => {
                 if (err)
                     reject(err);
                 else
@@ -179,9 +234,9 @@ async function findViaNpmBin() {
             });
         });
         // Unix: <prefix>/bin/ast-index  |  Windows: <prefix>\ast-index.exe or <prefix>\bin\ast-index.exe
-        const candidates = platform() === 'win32'
-            ? [resolve(prefix, BINARY_NAME), resolve(prefix, 'bin', BINARY_NAME)]
-            : [resolve(prefix, 'bin', BINARY_NAME)];
+        const candidates = platform() === "win32"
+            ? [resolve(prefix, BINARY_NAME), resolve(prefix, "bin", BINARY_NAME)]
+            : [resolve(prefix, "bin", BINARY_NAME)];
         for (const candidate of candidates) {
             try {
                 await access(candidate);
@@ -195,30 +250,37 @@ async function findViaNpmBin() {
 }
 function getPlatform() {
     switch (platform()) {
-        case 'darwin': return 'darwin';
-        case 'linux': return 'linux';
-        case 'win32': return 'windows';
-        default: return null;
+        case "darwin":
+            return "darwin";
+        case "linux":
+            return "linux";
+        case "win32":
+            return "windows";
+        default:
+            return null;
     }
 }
 function getArch() {
     switch (arch()) {
-        case 'arm64': return 'arm64';
-        case 'x64': return 'x86_64';
-        default: return null;
+        case "arm64":
+            return "arm64";
+        case "x64":
+            return "x86_64";
+        default:
+            return null;
     }
 }
 function buildAssetName(tag, plat, ar) {
-    const ext = plat === 'windows' ? '.zip' : '.tar.gz';
+    const ext = plat === "windows" ? ".zip" : ".tar.gz";
     return `ast-index-${tag}-${plat}-${ar}${ext}`;
 }
 async function findInPath() {
-    return new Promise(resolve => {
-        const cmd = platform() === 'win32' ? 'where' : 'which';
-        execFile(cmd, ['ast-index'], (err, stdout) => {
+    return new Promise((resolve) => {
+        const cmd = platform() === "win32" ? "where" : "which";
+        execFile(cmd, ["ast-index"], (err, stdout) => {
             if (err)
                 return resolve(null);
-            const path = stdout.trim().split('\n')[0];
+            const path = stdout.trim().split("\n")[0];
             resolve(path || null);
         });
     });
@@ -230,8 +292,8 @@ async function getBinaryVersion(binaryPath) {
     catch {
         return null;
     }
-    return new Promise(resolve => {
-        execFile(binaryPath, ['--version'], { timeout: 5000 }, (err, stdout) => {
+    return new Promise((resolve) => {
+        execFile(binaryPath, ["--version"], { timeout: 5000 }, (err, stdout) => {
             if (err)
                 return resolve(null);
             // Parse "ast-index v3.24.0" or "ast-index 3.24.0"
@@ -254,14 +316,14 @@ async function fetchLatestRelease() {
 function fetchJson(url) {
     return new Promise((resolve, reject) => {
         const options = {
-            headers: { 'User-Agent': 'token-pilot' },
+            headers: { "User-Agent": "token-pilot" },
         };
         httpsGet(url, options, (res) => {
             // Handle redirects
             if (res.statusCode === 301 || res.statusCode === 302) {
                 const location = res.headers.location;
                 if (!location)
-                    return reject(new Error('Redirect without location'));
+                    return reject(new Error("Redirect without location"));
                 fetchJson(location).then(resolve).catch(reject);
                 res.resume();
                 return;
@@ -270,10 +332,10 @@ function fetchJson(url) {
                 res.resume();
                 return reject(new Error(`HTTP ${res.statusCode} from ${url}`));
             }
-            let body = '';
-            res.setEncoding('utf-8');
-            res.on('data', chunk => body += chunk);
-            res.on('end', () => {
+            let body = "";
+            res.setEncoding("utf-8");
+            res.on("data", (chunk) => (body += chunk));
+            res.on("end", () => {
                 try {
                     resolve(JSON.parse(body));
                 }
@@ -281,18 +343,18 @@ function fetchJson(url) {
                     reject(new Error(`Invalid JSON from ${url}`));
                 }
             });
-            res.on('error', reject);
-        }).on('error', reject);
+            res.on("error", reject);
+        }).on("error", reject);
     });
 }
 function followRedirects(url) {
     return new Promise((resolve, reject) => {
-        const getter = url.startsWith('https') ? httpsGet : httpGet;
-        getter(url, { headers: { 'User-Agent': 'token-pilot' } }, (res) => {
+        const getter = url.startsWith("https") ? httpsGet : httpGet;
+        getter(url, { headers: { "User-Agent": "token-pilot" } }, (res) => {
             if (res.statusCode === 301 || res.statusCode === 302) {
                 const location = res.headers.location;
                 if (!location)
-                    return reject(new Error('Redirect without location'));
+                    return reject(new Error("Redirect without location"));
                 res.resume();
                 followRedirects(location).then(resolve).catch(reject);
                 return;
@@ -302,7 +364,7 @@ function followRedirects(url) {
                 return reject(new Error(`HTTP ${res.statusCode} downloading from ${url}`));
             }
             resolve(res);
-        }).on('error', reject);
+        }).on("error", reject);
     });
 }
 async function downloadAndExtractTarGz(url, destDir, binaryName) {
@@ -312,10 +374,10 @@ async function downloadAndExtractTarGz(url, destDir, binaryName) {
     const chunks = [];
     res.pipe(gunzip);
     await new Promise((resolve, reject) => {
-        gunzip.on('data', (chunk) => chunks.push(chunk));
-        gunzip.on('end', resolve);
-        gunzip.on('error', reject);
-        res.on('error', reject);
+        gunzip.on("data", (chunk) => chunks.push(chunk));
+        gunzip.on("end", resolve);
+        gunzip.on("error", reject);
+        res.on("error", reject);
     });
     const tarData = Buffer.concat(chunks);
     await tarExtract(tarData, destDir, binaryName);

package/dist/handlers/read-symbols.d.ts

@@ -1,17 +1,17 @@
-import type { AstIndexClient } from '../ast-index/client.js';
-import type { SymbolResolver } from '../core/symbol-resolver.js';
-import type { FileCache } from '../core/file-cache.js';
-import type { ContextRegistry } from '../core/context-registry.js';
+import type { AstIndexClient } from "../ast-index/client.js";
+import type { SymbolResolver } from "../core/symbol-resolver.js";
+import type { FileCache } from "../core/file-cache.js";
+import type { ContextRegistry } from "../core/context-registry.js";
 export interface ReadSymbolsArgs {
     path: string;
     symbols: string[];
     context_before?: number;
     context_after?: number;
-    show?: 'full' | 'head' | 'tail' | 'outline';
+    show?: "full" | "head" | "tail" | "outline";
 }
 export declare function handleReadSymbols(args: ReadSymbolsArgs, projectRoot: string, symbolResolver: SymbolResolver, fileCache: FileCache, contextRegistry: ContextRegistry, astIndex?: AstIndexClient, advisoryReminders?: boolean): Promise<{
     content: Array<{
-        type: 'text';
+        type: "text";
         text: string;
     }>;
 }>;

package/dist/handlers/read-symbols.js

@@ -1,7 +1,7 @@
-import { readFile } from 'node:fs/promises';
-import { estimateTokens } from '../core/token-estimator.js';
-import { resolveSafePath } from '../core/validation.js';
-import { assessConfidence, formatConfidence } from '../core/confidence.js';
+import { readFile } from "node:fs/promises";
+import { estimateTokens } from "../core/token-estimator.js";
+import { resolveSafePath } from "../core/validation.js";
+import { assessConfidence, formatConfidence } from "../core/confidence.js";
 export async function handleReadSymbols(args, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex, advisoryReminders = true) {
     const absPath = resolveSafePath(projectRoot, args.path);
     // Get file content ONCE
@@ -11,16 +11,41 @@ export async function handleReadSymbols(args, projectRoot, symbolResolver, fileC
         lines = cached.lines;
     }
     else {
-        const content = await readFile(absPath, 'utf-8');
-        lines = content.split('\n');
+        const content = await readFile(absPath, "utf-8");
+        lines = content.split("\n");
     }
     // Get AST structure ONCE
     let structure = cached?.structure;
     if (!structure && astIndex) {
-        structure = await astIndex.outline(absPath) ?? undefined;
+        structure = (await astIndex.outline(absPath)) ?? undefined;
     }
     const N = args.symbols.length;
     const sections = [];
+    // v0.23.6 — anti-pattern guard. When the caller requests nearly every
+    // symbol in the file, the sum of bodies + N × per-symbol metadata
+    // exceeds a single raw Read. That's worse than what smart_read +
+    // read_for_edit would do. Refuse the request and tell the caller.
+    if (structure && structure.symbols && structure.symbols.length > 0) {
+        const uniqueRequested = new Set(args.symbols.map((s) => s.split(".")[0]));
+        const matchedTopLevel = structure.symbols.filter((s) => uniqueRequested.has(s.name));
+        const totalTopLevelLines = structure.symbols.reduce((sum, s) => sum + (s.location.lineCount ?? 0), 0);
+        const requestedLines = matchedTopLevel.reduce((sum, s) => sum + (s.location.lineCount ?? 0), 0);
+        if (totalTopLevelLines > 0 &&
+            requestedLines / totalTopLevelLines >= 0.7 &&
+            matchedTopLevel.length >= 3) {
+            const text = `FILE: ${args.path} | SYMBOLS: ${N} requested\n\n` +
+                `ADVISORY: You requested ${matchedTopLevel.length} symbols covering ` +
+                `≥70% of this file (${requestedLines}/${totalTopLevelLines} lines). ` +
+                `A batch read here costs more than reading the whole file once.\n\n` +
+                `Cheaper alternatives:\n` +
+                `  - smart_read("${args.path}") for a structural overview\n` +
+                `  - read_for_edit("${args.path}", "<symbol>") when you need exact edit context\n` +
+                `  - Raw Read with offset/limit for a specific range\n\n` +
+                `If you truly need every body, call read_symbols with a narrower list ` +
+                `or use raw Read (bounded).`;
+            return { content: [{ type: "text", text }] };
+        }
+    }
     // Show mode constants (same as read_symbol.ts)
     const MAX_SYMBOL_LINES = 300;
     const MAX_FULL_LINES = 500;
@@ -47,75 +72,76 @@ export async function handleReadSymbols(args, projectRoot, symbolResolver, fileC
         const loc = `[L${resolved.startLine}-${resolved.endLine}]`;
         const lineCount = resolved.endLine - resolved.startLine + 1;
         // Determine effective show mode
-        const showMode = args.show ?? (lineCount > MAX_SYMBOL_LINES ? 'outline' : 'full');
+        const showMode = args.show ?? (lineCount > MAX_SYMBOL_LINES ? "outline" : "full");
         let displaySource = source;
         let truncated = false;
-        if (showMode === 'full') {
+        if (showMode === "full") {
             if (lineCount > MAX_FULL_LINES) {
-                const sourceLines = source.split('\n');
-                displaySource = sourceLines.slice(0, MAX_FULL_LINES).join('\n');
+                const sourceLines = source.split("\n");
+                displaySource = sourceLines.slice(0, MAX_FULL_LINES).join("\n");
                 displaySource += `\n\n    ... truncated at ${MAX_FULL_LINES} lines (${lineCount - MAX_FULL_LINES} more). Use show="head"/"tail" for targeted view.`;
                 truncated = true;
             }
         }
-        else if (showMode === 'head') {
-            const sourceLines = source.split('\n');
-            displaySource = sourceLines.slice(0, HEAD).join('\n');
+        else if (showMode === "head") {
+            const sourceLines = source.split("\n");
+            displaySource = sourceLines.slice(0, HEAD).join("\n");
             if (lineCount > HEAD) {
                 displaySource += `\n\n    ... ${lineCount - HEAD} more lines. Use show="tail" or read_symbol("${args.path}", "MethodName") for specific parts.`;
                 truncated = true;
             }
         }
-        else if (showMode === 'tail') {
-            const sourceLines = source.split('\n');
-            displaySource = sourceLines.slice(-TAIL).join('\n');
+        else if (showMode === "tail") {
+            const sourceLines = source.split("\n");
+            displaySource = sourceLines.slice(-TAIL).join("\n");
             if (lineCount > TAIL) {
-                displaySource = `    ... ${lineCount - TAIL} lines above ...\n\n` + displaySource;
+                displaySource =
+                    `    ... ${lineCount - TAIL} lines above ...\n\n` + displaySource;
                 truncated = true;
             }
         }
         else {
             // 'outline' mode: head + method list + tail
             if (lineCount > HEAD + TAIL) {
-                const sourceLines = source.split('\n');
-                const head = sourceLines.slice(0, HEAD).join('\n');
-                const tail = sourceLines.slice(-TAIL).join('\n');
+                const sourceLines = source.split("\n");
+                const head = sourceLines.slice(0, HEAD).join("\n");
+                const tail = sourceLines.slice(-TAIL).join("\n");
                 const omitted = sourceLines.length - HEAD - TAIL;
-                let methodOutline = '';
+                let methodOutline = "";
                 if (resolved.symbol.children && resolved.symbol.children.length > 0) {
-                    const methodLines = resolved.symbol.children.map(c => {
+                    const methodLines = resolved.symbol.children.map((c) => {
                         const mLoc = `[L${c.location.startLine}-${c.location.endLine}]`;
-                        return `  ${c.visibility === 'private' ? '🔒 ' : ''}${c.name}${c.kind === 'method' || c.kind === 'function' ? '()' : ''} ${mLoc} (${c.location.lineCount} lines)`;
+                        return `  ${c.visibility === "private" ? "🔒 " : ""}${c.name}${c.kind === "method" || c.kind === "function" ? "()" : ""} ${mLoc} (${c.location.lineCount} lines)`;
                     });
-                    methodOutline = `\nMETHODS (${resolved.symbol.children.length}):\n${methodLines.join('\n')}\n`;
+                    methodOutline = `\nMETHODS (${resolved.symbol.children.length}):\n${methodLines.join("\n")}\n`;
                 }
                 displaySource = [
                     head,
-                    '',
+                    "",
                     `    ... ${omitted} lines omitted — use read_symbol("${args.path}", "MethodName") to read specific methods ...`,
                     methodOutline,
                     tail,
-                ].join('\n');
+                ].join("\n");
                 truncated = true;
             }
         }
         if (truncated)
             anyTruncated = true;
         const symbolLines = [
-            `SYMBOL ${idx}/${N}: ${symbolName} (${resolved.symbol.kind}) ${loc} (${lineCount} lines${truncated ? `, show=${showMode}` : ''})`,
-            '',
+            `SYMBOL ${idx}/${N}: ${symbolName} (${resolved.symbol.kind}) ${loc} (${lineCount} lines${truncated ? `, show=${showMode}` : ""})`,
+            "",
             displaySource,
         ];
         if (resolved.symbol.references.length > 0) {
-            symbolLines.push('');
-            symbolLines.push(`REFERENCES: ${resolved.symbol.references.join(', ')}`);
+            symbolLines.push("");
+            symbolLines.push(`REFERENCES: ${resolved.symbol.references.join(", ")}`);
         }
-        sections.push(symbolLines.join('\n'));
+        sections.push(symbolLines.join("\n"));
         // Track each symbol
-        const sectionTokens = estimateTokens(symbolLines.join('\n'));
+        const sectionTokens = estimateTokens(symbolLines.join("\n"));
         totalTokens += sectionTokens;
         contextRegistry.trackLoad(absPath, {
-            type: 'symbol',
+            type: "symbol",
             symbolName,
             startLine: resolved.startLine,
             endLine: resolved.endLine,
@@ -126,9 +152,9 @@ export async function handleReadSymbols(args, projectRoot, symbolResolver, fileC
         contextRegistry.setContentHash(absPath, cached.hash);
     }
     const header = `FILE: ${args.path} | SYMBOLS: ${N} requested`;
-    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');
+    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");
     // Confidence metadata (aggregate)
     const confidenceMeta = assessConfidence({
         symbolResolved: anyResolved,
@@ -137,6 +163,10 @@ export async function handleReadSymbols(args, projectRoot, symbolResolver, fileC
         hasCallers: false,
         astAvailable: !!structure,
     });
-    return { content: [{ type: 'text', text: output + formatConfidence(confidenceMeta) }] };
+    return {
+        content: [
+            { type: "text", text: output + formatConfidence(confidenceMeta) },
+        ],
+    };
 }
 //# sourceMappingURL=read-symbols.js.map

package/dist/server/tool-definitions.js

@@ -129,7 +129,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "read_symbols",
-        description: "Batch read MULTIPLE symbols from ONE file for UNDERSTANDING code — saves N-1 round-trips vs calling read_symbol N times. Returns formatted symbol bodies with show modes (full/head/tail/outline). Use this when READING code, not editing. For edit preparation use read_for_edit instead.",
+        description: "Batch read MULTIPLE symbols from ONE file — saves N-1 round-trips vs calling read_symbol N times. BEST FIT: 3–8 symbols in one file when you need their bodies. For 1–2 symbols use read_symbol (simpler). If you'd request ≥70% of the file's symbols, the handler refuses and points you to smart_read — that's cheaper than a large batch. For edit preparation use read_for_edit.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/server.js

@@ -368,12 +368,18 @@ export async function createServer(projectRoot, options) {
                     const rsResult = await handleReadSymbols(rsArgs, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex, config.smartRead.advisoryReminders);
                     const rsText = rsResult.content[0]?.text ?? "";
                     const rsTokens = estimateTokens(rsText);
-                    const fullTokensRs = await fullFileTokens(rsArgs.path);
+                    // v0.23.6 — baseline is "N individual read_symbol calls", not
+                    // "one raw Read of the whole file". read_symbols replaces the
+                    // former, not the latter. Each read_symbol call carries its own
+                    // header/confidence overhead (~60 tokens); we dedupe that into
+                    // one shared file header, so batch saves roughly N-1 headers.
+                    const perSymbolOverhead = 60;
+                    const baselineRs = rsTokens + (rsArgs.symbols.length - 1) * perSymbolOverhead;
                     recordWithTrace({
                         tool: "read_symbols",
                         path: rsArgs.path,
                         tokensReturned: rsTokens,
-                        tokensWouldBe: fullTokensRs || rsTokens,
+                        tokensWouldBe: baselineRs,
                         timestamp: Date.now(),
                         savingsCategory: "compression",
                         absPath: resolve(projectRoot, rsArgs.path),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.23.4",
+  "version": "0.23.7",
   "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",
@@ -11,6 +11,7 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "dist/agents/*.md",
+    "scripts/postinstall.mjs",
     "start.sh",
     ".claude-plugin/",
     ".mcp.json",
@@ -27,6 +28,7 @@
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "bench:hook": "node scripts/bench-hook.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
     "lint": "tsc --noEmit",
     "prepublishOnly": "npm run build && node --input-type=module -e \"import { chmod } from 'node:fs/promises'; await chmod('dist/index.js', 0o755);\""
   },
@@ -64,6 +66,7 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
+    "@ast-index/cli": "^3.38.0",
     "chokidar": "^4.0.3"
   },
   "devDependencies": {
@@ -75,14 +78,6 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "peerDependencies": {
-    "ast-index": ">=0.1.0"
-  },
-  "peerDependenciesMeta": {
-    "ast-index": {
-      "optional": true
-    }
-  },
   "optionalDependencies": {
     "@ast-grep/cli": "^0.41.0"
   }

package/scripts/postinstall.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * postinstall — verify ast-index is usable, fall back to GitHub download.
+ *
+ * Runs after `npm install token-pilot` completes. npm has already pulled
+ * @ast-index/cli + the platform-specific sub-package as a transitive dep;
+ * this script only fires the GitHub fallback when that standard path
+ * didn't land a usable binary (exotic arch, corporate proxy, etc.).
+ *
+ * NEVER fails npm install. On any error we print a single warning and
+ * exit 0 — the `doctor` CLI still tells the user how to recover.
+ */
+
+import { access, constants } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(here, "..");
+
+// Opt-out hatch for CI, sandbox builds, etc.
+if (
+  process.env.TOKEN_PILOT_SKIP_POSTINSTALL === "1" ||
+  process.env.CI === "true"
+) {
+  process.exit(0);
+}
+
+// dist/ must exist or auto-install falls through — for fresh source
+// installs (cloned repo, pre-build), this is a no-op.
+const binaryManagerPath = resolve(
+  pkgRoot,
+  "dist",
+  "ast-index",
+  "binary-manager.js",
+);
+
+try {
+  await access(binaryManagerPath, constants.R_OK);
+} catch {
+  // Source checkout without dist/ — nothing for us to do.
+  process.exit(0);
+}
+
+let BM;
+try {
+  BM = await import(binaryManagerPath);
+} catch {
+  process.exit(0);
+}
+
+try {
+  const status = await BM.findBinary(null);
+  if (status && status.available) {
+    // Already good — the npm resolver handled everything.
+    process.exit(0);
+  }
+} catch {
+  /* fall through to install attempt */
+}
+
+// Try the explicit install path — logs to stderr, exit 0 regardless.
+try {
+  await BM.installBinary((msg) => {
+    process.stderr.write(`[token-pilot postinstall] ${msg}\n`);
+  });
+  process.stderr.write("[token-pilot postinstall] ast-index ready.\n");
+} catch (err) {
+  const msg = err && err.message ? err.message : String(err);
+  process.stderr.write(
+    `[token-pilot postinstall] Could not auto-install ast-index (${msg}). ` +
+      "Run \`npx token-pilot install-ast-index\` manually when ready; " +
+      "token-pilot will still start but some tools degrade until the " +
+      "binary is available.\n",
+  );
+}
+
+process.exit(0);