token-pilot 0.24.1 → 0.26.5

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.24.1"
+token_pilot_version: "0.26.5"
 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.24.1"
+token_pilot_version: "0.26.5"
 token_pilot_body_hash: a058518619fd6e2def0c9226f6c70438a5e0a80efe680c935414ecd7e1b14a4f
 ---
 

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

@@ -8,7 +8,7 @@ tools:
   - mcp__token-pilot__outline
   - mcp__token-pilot__module_info
   - Bash
-token_pilot_version: "0.24.1"
+token_pilot_version: "0.26.5"
 token_pilot_body_hash: 72b635f511492188587d6cb6fd70f936ae34cf5df1f9cd9eff7849cf1231e185
 ---
 

package/dist/agents/tp-run.md

@@ -15,7 +15,7 @@ tools:
   - Grep
   - Glob
   - Bash
-token_pilot_version: "0.24.1"
+token_pilot_version: "0.26.5"
 token_pilot_body_hash: d665d57085db38077d0eeab74bda8bdb84c9ad59688495486059af5d3fac67cf
 ---
 

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

@@ -9,7 +9,7 @@ tools:
   - mcp__token-pilot__session_budget
   - Bash
   - Read
-token_pilot_version: "0.24.1"
+token_pilot_version: "0.26.5"
 token_pilot_body_hash: 35b7f333a28c94e7dc89fcc3171703c4b466225f55cd5c701b7592f4f6486440
 ---
 

package/dist/agents/tp-test-coverage-gapper.md

@@ -10,7 +10,7 @@ tools:
   - mcp__token-pilot__test_summary
   - Glob
   - Grep
-token_pilot_version: "0.24.1"
+token_pilot_version: "0.26.5"
 token_pilot_body_hash: cc3d1f46fdb95ac3caf9344f69f1ddcd5ce5a175ee70aa150b7f9fda93edb152
 ---
 

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.24.1"
+token_pilot_version: "0.26.5"
 token_pilot_body_hash: 255912c47661d203c8f9a735237bc419f97e937f788a01811bbe126ee3dd5878
 ---
 

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

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

package/dist/cli/detect-client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * v0.26.0 — AI-client detection for install-agents.
+ *
+ * `tp-*` subagents are a Claude Code concept: `.md` files in
+ * `~/.claude/agents/` with `tools:` frontmatter, invoked via the `Task`
+ * tool. Other clients (Cursor, Codex CLI, Gemini CLI, Cline) read MCP
+ * tool descriptions directly and have no subagent surface — they still
+ * get our MCP tools + Read hook, but the 19 tp-* delegates sit idle.
+ *
+ * This detector tries to recognise the active client from env vars and
+ * on-disk config directories, so `install-agents` can warn non-Claude
+ * users before silently creating a dir nothing will read.
+ *
+ * Note: detection is best-effort. It returns the *most likely* client or
+ * "unknown" — never throws, never asks the user. A false "claude-code"
+ * result only costs one unused directory; a false "cursor" would print a
+ * misleading warning. We err on the side of "claude-code" when in doubt.
+ */
+export type DetectedClient = "claude-code" | "cursor" | "codex" | "gemini" | "cline" | "unknown";
+export interface DetectionResult {
+    client: DetectedClient;
+    source: string;
+    subagentsSupported: boolean;
+}
+/**
+ * Identify which AI client is likely running token-pilot, by inspecting
+ * env vars first (cheapest) then filesystem markers.
+ *
+ * @param homeDir       user's home directory (injected for tests)
+ * @param projectRoot   current project root (injected for tests)
+ * @param env           process.env (injected for tests)
+ */
+export declare function detectClient(homeDir: string, projectRoot: string, env?: NodeJS.ProcessEnv): Promise<DetectionResult>;
+/**
+ * Compose a human-readable warning for `install-agents` to print when
+ * the detected client doesn't support subagents. Null when it does.
+ */
+export declare function nonClaudeClientWarning(detection: DetectionResult): string | null;
+//# sourceMappingURL=detect-client.d.ts.map

package/dist/cli/detect-client.js

@@ -0,0 +1,106 @@
+/**
+ * v0.26.0 — AI-client detection for install-agents.
+ *
+ * `tp-*` subagents are a Claude Code concept: `.md` files in
+ * `~/.claude/agents/` with `tools:` frontmatter, invoked via the `Task`
+ * tool. Other clients (Cursor, Codex CLI, Gemini CLI, Cline) read MCP
+ * tool descriptions directly and have no subagent surface — they still
+ * get our MCP tools + Read hook, but the 19 tp-* delegates sit idle.
+ *
+ * This detector tries to recognise the active client from env vars and
+ * on-disk config directories, so `install-agents` can warn non-Claude
+ * users before silently creating a dir nothing will read.
+ *
+ * Note: detection is best-effort. It returns the *most likely* client or
+ * "unknown" — never throws, never asks the user. A false "claude-code"
+ * result only costs one unused directory; a false "cursor" would print a
+ * misleading warning. We err on the side of "claude-code" when in doubt.
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+/**
+ * Identify which AI client is likely running token-pilot, by inspecting
+ * env vars first (cheapest) then filesystem markers.
+ *
+ * @param homeDir       user's home directory (injected for tests)
+ * @param projectRoot   current project root (injected for tests)
+ * @param env           process.env (injected for tests)
+ */
+export async function detectClient(homeDir, projectRoot, env = process.env) {
+    // 1. Env-var signals — fastest, most reliable when set.
+    if (env.CLAUDE_PLUGIN_ROOT) {
+        return {
+            client: "claude-code",
+            source: "CLAUDE_PLUGIN_ROOT env",
+            subagentsSupported: true,
+        };
+    }
+    if (env.CURSOR_TRACE_ID || env.CURSOR_SESSION_ID) {
+        return {
+            client: "cursor",
+            source: "CURSOR_* env",
+            subagentsSupported: false,
+        };
+    }
+    if (env.GEMINI_CLI === "1" || env.GOOGLE_CLOUD_CODE === "1") {
+        return {
+            client: "gemini",
+            source: "GEMINI_* env",
+            subagentsSupported: false,
+        };
+    }
+    if (env.OPENAI_CODEX === "1" || env.CODEX_MODE) {
+        return {
+            client: "codex",
+            source: "CODEX_* env",
+            subagentsSupported: false,
+        };
+    }
+    // 2. Filesystem signals. Order matters — check the ones with the
+    //    strongest on-disk footprint first.
+    const markers = [
+        [
+            join(homeDir, ".claude", "agents"),
+            "~/.claude/agents/",
+            "claude-code",
+            true,
+        ],
+        [join(homeDir, ".claude"), "~/.claude/", "claude-code", true],
+        [join(projectRoot, ".cursor"), ".cursor/", "cursor", false],
+        [join(homeDir, ".cursor"), "~/.cursor/", "cursor", false],
+        [join(homeDir, ".codex"), "~/.codex/", "codex", false],
+        [join(homeDir, ".gemini"), "~/.gemini/", "gemini", false],
+        [join(projectRoot, ".gemini"), ".gemini/", "gemini", false],
+    ];
+    for (const [path, source, client, subagentsSupported] of markers) {
+        try {
+            await fs.access(path);
+            return { client, source, subagentsSupported };
+        }
+        catch {
+            /* try next */
+        }
+    }
+    // 3. Nothing recognised — assume Claude Code (safest default: the user
+    //    explicitly ran `install-agents`, so they likely have Claude Code
+    //    but haven't used it yet, or ran via CI where env vars are sparse).
+    return {
+        client: "unknown",
+        source: "no markers found",
+        subagentsSupported: true,
+    };
+}
+/**
+ * Compose a human-readable warning for `install-agents` to print when
+ * the detected client doesn't support subagents. Null when it does.
+ */
+export function nonClaudeClientWarning(detection) {
+    if (detection.subagentsSupported)
+        return null;
+    return (`[token-pilot] Detected ${detection.client} (${detection.source}).\n` +
+        `[token-pilot] tp-* subagents are a Claude Code concept and will NOT be\n` +
+        `[token-pilot] auto-invoked in ${detection.client}. Your MCP tools and Read hook\n` +
+        `[token-pilot] still work fully. If you meant to install for Claude Code (multiple\n` +
+        `[token-pilot] AI clients coexist), pass --scope=user explicitly and re-run.`);
+}
+//# sourceMappingURL=detect-client.js.map

package/dist/cli/install-agents.d.ts

@@ -84,6 +84,7 @@ export declare function handleInstallAgents(argv: string[], opts?: {
     homeDir?: string;
     projectRoot?: string;
     isTTY?: boolean;
+    env?: NodeJS.ProcessEnv;
 }): Promise<number>;
 export interface StartupReminderOptions {
     projectRoot: string;

package/dist/cli/install-agents.js

@@ -29,6 +29,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseFrontmatter } from "./agent-frontmatter.js";
+import { detectClient, nonClaudeClientWarning } from "./detect-client.js";
 function targetDirFor(opts) {
     const root = opts.scope === "user" ? opts.homeDir : opts.projectRoot;
     return join(root, ".claude", "agents");
@@ -301,6 +302,35 @@ export async function handleInstallAgents(argv, opts) {
     const scopeArg = parseFlag(argv, "scope");
     const force = parseFlag(argv, "force") !== undefined;
     const projectRoot = opts?.projectRoot ?? process.cwd();
+    const homeDir = opts?.homeDir ?? homedir();
+    const env = opts?.env ?? process.env;
+    // v0.26.5 — plugin-aware note. If we're running as a Claude Code
+    // plugin (CLAUDE_PLUGIN_ROOT set), `install-agents` is still useful —
+    // tp-* subagents are separate from plugin hooks. But the directory
+    // the plugin installer created is the authoritative one; we print a
+    // short note so the user doesn't think they need to reinstall on
+    // every plugin update.
+    if (env.CLAUDE_PLUGIN_ROOT) {
+        process.stderr.write("[token-pilot] Note: you're running as a Claude Code plugin. " +
+            "install-agents still works for tp-* subagents (those are separate " +
+            "from plugin hooks). Continuing.\n");
+    }
+    // v0.26.0 — detect non-Claude clients where tp-* subagents have no
+    // runtime. We still let users force-install via --scope (they may run
+    // multiple clients side-by-side), but we warn loudly so nobody ends
+    // up with a ghost ~/.claude/agents/ directory nothing invokes.
+    const detection = await detectClient(homeDir, projectRoot, env);
+    const warning = nonClaudeClientWarning(detection);
+    if (warning) {
+        process.stderr.write(warning + "\n");
+        if (scopeArg === undefined) {
+            // Silent bail is worse than a warning — return 0 so CI/postinstall
+            // don't treat this as a failure, but skip creating the directory.
+            process.stderr.write("[token-pilot] Skipping agent install (pass --scope to override).\n");
+            return 0;
+        }
+        process.stderr.write(`[token-pilot] --scope=${scopeArg} supplied — proceeding anyway.\n`);
+    }
     let scope;
     if (scopeArg === "user" || scopeArg === "project") {
         scope = scopeArg;
@@ -330,7 +360,7 @@ export async function handleInstallAgents(argv, opts) {
         const result = await installAgents({
             scope,
             projectRoot,
-            homeDir: opts?.homeDir ?? homedir(),
+            homeDir,
             distAgentsDir,
             force,
         });

package/dist/cli/tool-audit.d.ts

@@ -0,0 +1,58 @@
+/**
+ * v0.26.2 — `npx token-pilot tool-audit`.
+ *
+ * Reads `.token-pilot/tool-calls.jsonl` + archives and emits a per-tool
+ * savings distribution across every session the user has ever run. The
+ * whole point is to answer "which tools actually save tokens" with
+ * data, not with a single field-report session.
+ *
+ * Output is human-readable by default; `--json` for scripts/CI.
+ * Exit code is always 0 — this is a diagnostic, not a gate. A future
+ * `tool-audit --fail-below=20` could turn it into a CI signal once we
+ * trust the baseline.
+ */
+import { type ToolCallEvent } from "../core/tool-call-log.js";
+export interface ToolAuditRow {
+    tool: string;
+    count: number;
+    tokensReturned: number;
+    tokensWouldBe: number;
+    saved: number;
+    reductionPct: number;
+    /** Calls where the recorder claimed NO savings (pass-through) — separate so
+     *  they don't poison the reduction average. */
+    noneCalls: number;
+    /** True when reduction is below the low-value threshold AND we have enough
+     *  samples (≥5) to make a claim — avoids flagging tools after 1 bad run. */
+    lowValue: boolean;
+}
+/**
+ * Aggregate raw events into one row per tool. Pure — tested in
+ * isolation from the filesystem.
+ */
+export declare function aggregateToolCalls(events: ToolCallEvent[], lowValueThreshold?: number, minSamples?: number): ToolAuditRow[];
+/**
+ * Format rows as a fixed-width table for the terminal. Pure.
+ */
+export declare function formatTable(rows: ToolAuditRow[], opts: {
+    totalEvents: number;
+}): string;
+export interface ToolAuditOptions {
+    projectRoot: string;
+    json?: boolean;
+    /** For tests. */
+    now?: Date;
+}
+export declare function runToolAudit(opts: ToolAuditOptions): Promise<{
+    stdout: string;
+    exitCode: number;
+    rows: ToolAuditRow[];
+}>;
+/**
+ * CLI entry. `argv` is the raw `process.argv.slice(2)` after
+ * dispatching to this subcommand.
+ */
+export declare function handleToolAudit(argv: string[], opts?: {
+    projectRoot?: string;
+}): Promise<number>;
+//# sourceMappingURL=tool-audit.d.ts.map

package/dist/cli/tool-audit.js

@@ -0,0 +1,123 @@
+/**
+ * v0.26.2 — `npx token-pilot tool-audit`.
+ *
+ * Reads `.token-pilot/tool-calls.jsonl` + archives and emits a per-tool
+ * savings distribution across every session the user has ever run. The
+ * whole point is to answer "which tools actually save tokens" with
+ * data, not with a single field-report session.
+ *
+ * Output is human-readable by default; `--json` for scripts/CI.
+ * Exit code is always 0 — this is a diagnostic, not a gate. A future
+ * `tool-audit --fail-below=20` could turn it into a CI signal once we
+ * trust the baseline.
+ */
+import { loadAllToolCalls } from "../core/tool-call-log.js";
+/**
+ * Aggregate raw events into one row per tool. Pure — tested in
+ * isolation from the filesystem.
+ */
+export function aggregateToolCalls(events, lowValueThreshold = 20, minSamples = 5) {
+    const byTool = new Map();
+    for (const e of events) {
+        const row = byTool.get(e.tool) ?? {
+            count: 0,
+            tokensReturned: 0,
+            tokensWouldBe: 0,
+            noneCalls: 0,
+        };
+        row.count++;
+        row.tokensReturned += e.tokensReturned;
+        row.tokensWouldBe += e.tokensWouldBe;
+        if (e.savingsCategory === "none")
+            row.noneCalls++;
+        byTool.set(e.tool, row);
+    }
+    const rows = [];
+    for (const [tool, r] of byTool) {
+        const saved = Math.max(0, r.tokensWouldBe - r.tokensReturned);
+        const reductionPct = r.tokensWouldBe > 0
+            ? Math.round((1 - r.tokensReturned / r.tokensWouldBe) * 100)
+            : 0;
+        const lowValue = r.count >= minSamples && reductionPct < lowValueThreshold;
+        rows.push({
+            tool,
+            count: r.count,
+            tokensReturned: r.tokensReturned,
+            tokensWouldBe: r.tokensWouldBe,
+            saved,
+            reductionPct,
+            noneCalls: r.noneCalls,
+            lowValue,
+        });
+    }
+    // Sort by tokens saved desc — the first row is your biggest
+    // contributor to overall savings, low-value tools sink to the bottom.
+    rows.sort((a, b) => b.saved - a.saved);
+    return rows;
+}
+function fmtTokens(n) {
+    if (n >= 1_000_000)
+        return (n / 1_000_000).toFixed(1) + "M";
+    if (n >= 1_000)
+        return (n / 1_000).toFixed(1) + "k";
+    return String(n);
+}
+/**
+ * Format rows as a fixed-width table for the terminal. Pure.
+ */
+export function formatTable(rows, opts) {
+    if (rows.length === 0) {
+        return `No tool calls recorded yet.
+Run a few MCP tool calls from your AI client, then re-run \`npx token-pilot tool-audit\`.`;
+    }
+    const lines = [];
+    lines.push(`Token Pilot — tool audit`);
+    lines.push(`  ${opts.totalEvents} calls across ${rows.length} tools (cumulative across sessions)`);
+    lines.push("");
+    lines.push("  Tool                     Calls      Saved   Returned  Reduction");
+    lines.push("  ─────────────────────────────────────────────────────────────────");
+    for (const r of rows) {
+        const tool = r.tool.padEnd(24);
+        const count = String(r.count).padStart(6);
+        const saved = fmtTokens(r.saved).padStart(9);
+        const returned = fmtTokens(r.tokensReturned).padStart(9);
+        const pct = `${r.reductionPct}%`.padStart(6);
+        const flag = r.lowValue ? "  ⚠ low-value" : "";
+        lines.push(`  ${tool} ${count} ${saved} ${returned} ${pct}${flag}`);
+    }
+    const lowValueRows = rows.filter((r) => r.lowValue);
+    if (lowValueRows.length > 0) {
+        lines.push("");
+        lines.push("Low-value tools flagged above have <20% token reduction across ≥5 calls.");
+        lines.push("Consider: check their `none` passthrough count, or whether a cheaper alternative (Grep, Read) would do the job.");
+    }
+    return lines.join("\n");
+}
+export async function runToolAudit(opts) {
+    const events = await loadAllToolCalls(opts.projectRoot);
+    const rows = aggregateToolCalls(events);
+    if (opts.json) {
+        return {
+            stdout: JSON.stringify({ totalEvents: events.length, tools: rows }, null, 2),
+            exitCode: 0,
+            rows,
+        };
+    }
+    return {
+        stdout: formatTable(rows, { totalEvents: events.length }),
+        exitCode: 0,
+        rows,
+    };
+}
+/**
+ * CLI entry. `argv` is the raw `process.argv.slice(2)` after
+ * dispatching to this subcommand.
+ */
+export async function handleToolAudit(argv, opts) {
+    const json = argv.includes("--json");
+    const projectRoot = opts?.projectRoot ?? process.cwd();
+    const { stdout, exitCode } = await runToolAudit({ projectRoot, json });
+    process.stdout.write(stdout + "\n");
+    return exitCode;
+}
+//# sourceMappingURL=tool-audit.js.map

package/dist/cli/typo-guard.d.ts

@@ -17,7 +17,7 @@
  * Everything else passes through untouched — a real project root like
  * `/home/user/my-project` or `./subdir` goes to startServer as before.
  */
-export declare const KNOWN_COMMANDS: readonly ["hook-read", "hook-edit", "hook-post-bash", "hook-post-task", "hook-session-start", "install-hook", "uninstall-hook", "install-ast-index", "doctor", "bless-agents", "unbless-agents", "install-agents", "uninstall-agents", "stats", "save-doc", "list-docs", "init", "--version", "-v", "--help", "-h"];
+export declare const KNOWN_COMMANDS: readonly ["hook-read", "hook-edit", "hook-post-bash", "hook-post-task", "hook-session-start", "install-hook", "uninstall-hook", "install-ast-index", "doctor", "bless-agents", "unbless-agents", "install-agents", "uninstall-agents", "stats", "tool-audit", "save-doc", "list-docs", "init", "--version", "-v", "--help", "-h"];
 export interface TypoGuardResult {
     kind: "pass-through" | "typo";
     suggestion?: string;

package/dist/cli/typo-guard.js

@@ -33,6 +33,7 @@ export const KNOWN_COMMANDS = [
     "install-agents",
     "uninstall-agents",
     "stats",
+    "tool-audit",
     "save-doc",
     "list-docs",
     "init",

package/dist/core/tool-call-log.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 type { SavingsCategory } from "./session-analytics.js";
+export declare const TOOL_LOG_ROTATION_BYTES = 10000000;
+export declare const TOOL_LOG_RETENTION_MAX_AGE_DAYS = 30;
+export declare const TOOL_LOG_RETENTION_MAX_TOTAL_BYTES = 100000000;
+/**
+ * Persisted shape of one MCP tool call. Mirrors the in-memory
+ * `ToolCall` in session-analytics.ts but trims runtime-only fields
+ * (intent, decisionTrace — those are re-derivable from args/tool if
+ * ever needed, not worth the disk cost).
+ */
+export interface ToolCallEvent {
+    ts: number;
+    session_id: string;
+    tool: string;
+    path?: string;
+    tokensReturned: number;
+    tokensWouldBe: number;
+    savingsCategory: SavingsCategory;
+    sessionCacheHit?: boolean;
+    delegatedToContextMode?: boolean;
+}
+export declare function currentToolLogPath(projectRoot: string): string;
+/**
+ * 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 declare function appendToolCall(projectRoot: string, event: ToolCallEvent): Promise<void>;
+/**
+ * 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 declare function loadAllToolCalls(projectRoot: string): Promise<ToolCallEvent[]>;
+export declare function retentionDeletions(files: Array<{
+    path: string;
+    mtime: Date;
+    size: number;
+}>, now: Date, maxAgeDays?: number, maxTotalBytes?: number): string[];
+export declare function applyRetention(projectRoot: string, now?: Date): Promise<void>;
+//# sourceMappingURL=tool-call-log.d.ts.map