token-pilot 0.31.0 → 0.33.0

package/dist/handlers/call-tree.d.ts

@@ -0,0 +1,35 @@
+/**
+ * v0.32.0 — call_tree MCP tool.
+ *
+ * Thin wrapper over `AstIndexClient.callTree`. Produces a text tree of
+ * callers (depth-N) for one function. Complements `find_usages` which
+ * is flat (one level of refs): call_tree is recursive, so you see the
+ * full chain from leaves → entry points.
+ *
+ * Typical use cases:
+ *   - debugging: "who eventually calls this helper"
+ *   - refactor planning: "what breaks if I change this function's
+ *     signature"
+ *   - dead-code verification: "does anything actually reach this
+ *     branch"
+ *
+ * Output shape is indented tree text, not JSON — the MCP-consuming
+ * model needs to read it, not diff it.
+ */
+import type { AstIndexClient } from "../ast-index/client.js";
+export interface CallTreeArgs {
+    /** Function / method name (unqualified, e.g. `fetchUser`). */
+    symbol: string;
+    /** Walk-up depth. Default 3, max 6 (anything deeper is overwhelming). */
+    depth?: number;
+}
+export declare function handleCallTree(args: CallTreeArgs, astIndex: AstIndexClient): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    meta: {
+        files: string[];
+    };
+}>;
+//# sourceMappingURL=call-tree.d.ts.map

package/dist/handlers/call-tree.js

@@ -0,0 +1,70 @@
+const MAX_DEPTH = 6;
+function renderNode(node, indent, out) {
+    const loc = node.file && node.line != null
+        ? ` — ${node.file}:${node.line}`
+        : node.file
+            ? ` — ${node.file}`
+            : "";
+    out.push(`${indent}${node.name}${loc}`);
+    if (node.callers && node.callers.length > 0) {
+        for (const child of node.callers) {
+            renderNode(child, indent + "  ", out);
+        }
+    }
+}
+export async function handleCallTree(args, astIndex) {
+    if (astIndex.isDisabled() || astIndex.isOversized()) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "call_tree is disabled: " +
+                        (astIndex.isDisabled()
+                            ? "project root not detected. Call smart_read() on any project file first."
+                            : "ast-index indexed >50k files (likely includes node_modules). Ensure node_modules is in .gitignore.") +
+                        "\nAlternative: use find_usages(symbol) iteratively.",
+                },
+            ],
+            meta: { files: [] },
+        };
+    }
+    const symbol = args.symbol?.trim();
+    if (!symbol) {
+        return {
+            content: [{ type: "text", text: "call_tree: `symbol` is required." }],
+            meta: { files: [] },
+        };
+    }
+    const depth = Math.min(Math.max(1, Math.floor(args.depth ?? 3)), MAX_DEPTH);
+    const tree = await astIndex.callTree(symbol, depth);
+    if (!tree) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `No call-tree found for \`${symbol}\`. The symbol may be uncalled, unindexed, or ambiguous. Try find_usages("${symbol}") for a flat cross-reference list.`,
+                },
+            ],
+            meta: { files: [] },
+        };
+    }
+    const lines = [];
+    lines.push(`CALL TREE for \`${symbol}\` (depth ${depth}, callers of callers…):`);
+    lines.push("");
+    renderNode(tree, "  ", lines);
+    lines.push("");
+    lines.push("Read bottom-up: indented entries call the parent. Root is the symbol you asked for.");
+    // Collect files for meta so downstream consumers can open them.
+    const files = new Set();
+    const collect = (n) => {
+        if (n.file)
+            files.add(n.file);
+        n.callers?.forEach(collect);
+    };
+    collect(tree);
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        meta: { files: [...files] },
+    };
+}
+//# sourceMappingURL=call-tree.js.map

package/dist/handlers/smart-log.js

@@ -14,14 +14,19 @@ const MAX_COUNT = 50;
 export async function handleSmartLog(args, projectRoot) {
     const count = Math.min(args.count ?? 10, MAX_COUNT);
     const ref = args.ref ?? 'HEAD';
-    // Build git log command with --numstat for file stats
+    // Build git log command with --numstat for file stats.
+    // v0.33.0 (B6) — `ref` MUST be a revision argument, not a pathspec.
+    // The previous version pushed `'--', ref` which made git interpret
+    // `HEAD` as a path (`git log -- HEAD`) and silently returned empty.
+    // Adding a path then produced `git log -- HEAD -- foo.ts` — invalid.
+    // Correct order: `git log <flags> <ref> [-- <path>]`.
     const gitArgs = [
         'log',
         `--format=${RECORD_SEPARATOR}%h${FIELD_SEPARATOR}%ad${FIELD_SEPARATOR}%an${FIELD_SEPARATOR}%s`,
         '--date=short',
         '--numstat',
         `-n`, `${count}`,
-        '--', ref,
+        ref,
     ];
     if (args.path) {
         gitArgs.push('--', args.path);

package/dist/hooks/installer.d.ts

@@ -14,6 +14,20 @@ export interface HookInstallOptions {
     /** Absolute path to the node binary. Defaults to process.execPath. */
     nodeExecPath?: string;
 }
+/**
+ * Detect a stale token-pilot hook command — one that points at a
+ * pinned npx-cache snapshot (`npx/_npx/<hash>/...`) or any other
+ * version-pinned path that won't follow plugin upgrades.
+ *
+ * v0.33.0 fix: users who ran `npx token-pilot init` early on got
+ * settings.json entries with literal `~/.npm/_npx/<hash>/...` paths.
+ * When the npx cache rotates or token-pilot publishes a new minor,
+ * those entries silently call the old binary, missing every hook
+ * shipped after install (e.g. v0.31.0 Task hooks). Removing the
+ * stale entry lets the next install or the bundled plugin's
+ * `hooks/hooks.json` (CLAUDE_PLUGIN_ROOT) take over.
+ */
+export declare function isStaleTokenPilotHookCommand(cmd: unknown): boolean;
 /**
  * Install Token Pilot hook into Claude Code settings.
  * Creates or updates .claude/settings.json with PreToolUse hook.
@@ -23,4 +37,30 @@ export declare function installHook(projectRoot: string, options?: HookInstallOp
  * Remove Token Pilot hook from Claude Code settings.
  */
 export declare function uninstallHook(projectRoot: string): Promise<HookUninstallResult>;
+export interface CleanStaleResult {
+    scanned: string[];
+    cleaned: string[];
+    staleEntriesRemoved: number;
+    message: string;
+}
+/**
+ * Scan a settings.json (user-level or project-level) and remove every
+ * token-pilot hook entry whose command points at a pinned npx-cache
+ * snapshot or a literal plugin-cache version path. The plugin's bundled
+ * `hooks/hooks.json` (resolved through `${CLAUDE_PLUGIN_ROOT}` at
+ * runtime) supersedes them.
+ *
+ * Pure-ish: writes only when something changed. Never throws — bad JSON
+ * or missing file are reported in the result so callers (CLI, init)
+ * can surface them without aborting.
+ */
+export declare function cleanStaleHookEntries(settingsPath: string): Promise<CleanStaleResult>;
+/**
+ * Inspect `~/.claude/settings.json` to determine whether the user has
+ * enabled the bundled `token-pilot` plugin in Claude Code. When true,
+ * the plugin's own `hooks/hooks.json` is the source of truth and any
+ * additional hook entries written by the npm CLI are duplicates that
+ * also lock the user to whichever binary path the CLI captured.
+ */
+export declare function isTokenPilotPluginEnabled(homeDir: string): Promise<boolean>;
 //# sourceMappingURL=installer.d.ts.map

package/dist/hooks/installer.js

@@ -12,6 +12,40 @@ function buildHookCommand(action, options) {
     }
     return `token-pilot ${action}`;
 }
+/**
+ * Detect a stale token-pilot hook command — one that points at a
+ * pinned npx-cache snapshot (`npx/_npx/<hash>/...`) or any other
+ * version-pinned path that won't follow plugin upgrades.
+ *
+ * v0.33.0 fix: users who ran `npx token-pilot init` early on got
+ * settings.json entries with literal `~/.npm/_npx/<hash>/...` paths.
+ * When the npx cache rotates or token-pilot publishes a new minor,
+ * those entries silently call the old binary, missing every hook
+ * shipped after install (e.g. v0.31.0 Task hooks). Removing the
+ * stale entry lets the next install or the bundled plugin's
+ * `hooks/hooks.json` (CLAUDE_PLUGIN_ROOT) take over.
+ */
+export function isStaleTokenPilotHookCommand(cmd) {
+    if (typeof cmd !== "string")
+        return false;
+    if (!cmd.includes("token-pilot"))
+        return false;
+    // npm/npx cache hash — always stale (will rotate)
+    if (/\/_npx\/[0-9a-f]+\//.test(cmd))
+        return true;
+    // Pinned plugin-cache version path — old version that may not
+    // contain a hook handler the new settings entry references.
+    // Match `/plugins/cache/token-pilot/token-pilot/<version>/`.
+    const pinned = cmd.match(/\/plugins\/cache\/token-pilot\/token-pilot\/([^/]+)\//);
+    if (pinned) {
+        // The plugin runtime always uses ${CLAUDE_PLUGIN_ROOT} which
+        // resolves to the *current* version dir. A literal version in
+        // the path means someone wrote it from a CLI that captured the
+        // dir at install time — stale by definition.
+        return true;
+    }
+    return false;
+}
 function createHookConfig(options) {
     return {
         hooks: {
@@ -154,9 +188,11 @@ export async function installHook(projectRoot, options) {
         const isTokenPilotHook = (h) => h.hooks?.some((hook) => hook.command?.includes("token-pilot"));
         if (Array.isArray(existingHooks)) {
             // Remove old broken hooks (bare "token-pilot" without absolute path)
-            // and replace with working ones using absolute paths
+            // OR stale npx-cache / pinned-version paths (v0.33.0)
+            // and replace with working ones using absolute paths.
             const oldBrokenHooks = existingHooks.filter((h) => isTokenPilotHook(h) &&
-                h.hooks?.some((hook) => hook.command?.match(/^token-pilot\s/)));
+                h.hooks?.some((hook) => hook.command?.match(/^token-pilot\s/) ||
+                    isStaleTokenPilotHookCommand(hook.command)));
             if (oldBrokenHooks.length > 0 && options?.scriptPath) {
                 // Remove old broken hooks, will re-add with absolute paths below
                 settings.hooks.PreToolUse = existingHooks.filter((h) => !isTokenPilotHook(h));
@@ -309,4 +345,111 @@ export async function uninstallHook(projectRoot) {
         };
     }
 }
+/**
+ * Scan a settings.json (user-level or project-level) and remove every
+ * token-pilot hook entry whose command points at a pinned npx-cache
+ * snapshot or a literal plugin-cache version path. The plugin's bundled
+ * `hooks/hooks.json` (resolved through `${CLAUDE_PLUGIN_ROOT}` at
+ * runtime) supersedes them.
+ *
+ * Pure-ish: writes only when something changed. Never throws — bad JSON
+ * or missing file are reported in the result so callers (CLI, init)
+ * can surface them without aborting.
+ */
+export async function cleanStaleHookEntries(settingsPath) {
+    const result = {
+        scanned: [settingsPath],
+        cleaned: [],
+        staleEntriesRemoved: 0,
+        message: "",
+    };
+    let raw;
+    try {
+        raw = await readFile(settingsPath, "utf-8");
+    }
+    catch (err) {
+        if (err?.code === "ENOENT") {
+            result.message = `No settings at ${settingsPath} — nothing to migrate.`;
+            return result;
+        }
+        result.message = `Cannot read ${settingsPath}: ${err?.message ?? err}`;
+        return result;
+    }
+    let settings;
+    try {
+        settings = JSON.parse(raw);
+    }
+    catch {
+        result.message = `Invalid JSON in ${settingsPath} — skipped (fix manually).`;
+        return result;
+    }
+    const sections = ["PreToolUse", "PostToolUse", "SessionStart"];
+    let removed = 0;
+    for (const section of sections) {
+        const arr = settings.hooks?.[section];
+        if (!Array.isArray(arr))
+            continue;
+        const filtered = arr.filter((entry) => {
+            const inner = Array.isArray(entry?.hooks) ? entry.hooks : [];
+            const hasStale = inner.some((h) => isStaleTokenPilotHookCommand(h?.command));
+            if (hasStale) {
+                removed++;
+                return false;
+            }
+            return true;
+        });
+        if (filtered.length !== arr.length) {
+            if (filtered.length === 0) {
+                delete settings.hooks[section];
+            }
+            else {
+                settings.hooks[section] = filtered;
+            }
+        }
+    }
+    if (removed === 0) {
+        result.message = `No stale token-pilot hook entries in ${settingsPath}.`;
+        return result;
+    }
+    // Drop empty hooks container so JSON stays clean.
+    if (settings.hooks &&
+        typeof settings.hooks === "object" &&
+        Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks;
+    }
+    await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    result.cleaned.push(settingsPath);
+    result.staleEntriesRemoved = removed;
+    result.message = `Removed ${removed} stale token-pilot hook entr${removed === 1 ? "y" : "ies"} from ${settingsPath}.`;
+    return result;
+}
+/**
+ * Inspect `~/.claude/settings.json` to determine whether the user has
+ * enabled the bundled `token-pilot` plugin in Claude Code. When true,
+ * the plugin's own `hooks/hooks.json` is the source of truth and any
+ * additional hook entries written by the npm CLI are duplicates that
+ * also lock the user to whichever binary path the CLI captured.
+ */
+export async function isTokenPilotPluginEnabled(homeDir) {
+    const settingsPath = resolve(homeDir, ".claude", "settings.json");
+    let raw;
+    try {
+        raw = await readFile(settingsPath, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    let settings;
+    try {
+        settings = JSON.parse(raw);
+    }
+    catch {
+        return false;
+    }
+    const enabled = settings?.enabledPlugins;
+    if (!enabled || typeof enabled !== "object")
+        return false;
+    // keys look like `token-pilot@token-pilot` — match prefix.
+    return Object.entries(enabled).some(([key, val]) => val === true && typeof key === "string" && key.startsWith("token-pilot@"));
+}
 //# sourceMappingURL=installer.js.map

package/dist/hooks/pre-task.js

@@ -54,6 +54,19 @@ function containsEscape(description) {
     const n = description.toLowerCase();
     return ESCAPE_PHRASES.some((p) => n.includes(p));
 }
+/**
+ * v0.33.0 (B14) — generic context appended to every advice payload
+ * for non-tp-* dispatches. Subagents like `general-purpose` and
+ * `code-analyzer` don't know about the token-pilot MCP tools and
+ * loop on raw `Read` even after `hook-pre-read` denies them. This
+ * paragraph lands in their context window before they take their
+ * first action and tells them what to use instead.
+ */
+const SUBAGENT_TOOL_GUIDE = "When working in this task: prefer `mcp__token-pilot__smart_read` " +
+    "(file structure), `read_symbol` (one function/class), and " +
+    "`find_usages` (semantic search) over raw Read/Grep. The token-pilot " +
+    "PreToolUse hooks block large-file Read and unbounded Grep — use " +
+    "the MCP tools or pass `offset`/`limit` to Read.";
 /**
  * Pure decision function. Caller resolves all context (env, mode,
  * agent index) up front so this stays a plain input → output mapping.
@@ -67,23 +80,44 @@ export function decidePreTask(input, ctx) {
     if (typeof subagentType === "string" && subagentType.startsWith("tp-")) {
         return { kind: "allow" };
     }
-    // No description → nothing to match against. Allow (Claude Code
-    // sometimes dispatches Task with only a subagent_type + session id).
-    if (!description || description.length === 0)
-        return { kind: "allow" };
+    // v0.33.0 (B4) — TOKEN_PILOT_FORCE_SUBAGENTS=1 with an empty agent
+    // catalog used to silently allow every Task call (no matches → no
+    // suggestion). That defeats the env's only purpose. Fail loud
+    // instead: tell the user to install the templates.
+    const indexEmpty = !ctx.agentIndex.agents || ctx.agentIndex.agents.length === 0;
+    if (ctx.force && indexEmpty) {
+        return {
+            kind: "deny",
+            reason: "TOKEN_PILOT_FORCE_SUBAGENTS=1 is set but no tp-* agents are " +
+                "installed in this project (or `~/.claude/agents/`). " +
+                "Run `npx token-pilot install-agents --scope=project` first, " +
+                "or unset TOKEN_PILOT_FORCE_SUBAGENTS.",
+        };
+    }
+    // No description → nothing to match against. Inject the generic
+    // tool-guide so the subagent still picks tp-tools (B14).
+    if (!description || description.length === 0) {
+        return { kind: "advise", message: SUBAGENT_TOOL_GUIDE };
+    }
     // Author-blessed escape clauses — user is explicitly saying
-    // "this is broad". Respect that.
-    if (containsEscape(description))
-        return { kind: "allow" };
+    // "this is broad". Inject the tool-guide but no agent suggestion.
+    if (containsEscape(description)) {
+        return { kind: "advise", message: SUBAGENT_TOOL_GUIDE };
+    }
     const hit = matchTpAgent(description, ctx.agentIndex);
-    if (!hit)
-        return { kind: "allow" };
+    if (!hit) {
+        // No specific tp-* match. Still send the generic tool-guide so
+        // the subagent learns about smart_read / read_symbol — covers the
+        // common code-analyzer / general-purpose loop on raw Read (B14).
+        return { kind: "advise", message: SUBAGENT_TOOL_GUIDE };
+    }
     const suggestion = `Consider dispatching \`${hit.agent}\` instead of \`${subagentType || "general-purpose"}\` — ` +
         `the description matches its trigger phrases (confidence: ${hit.confidence}). ` +
         `tp-* agents run under a tighter budget and output in terse style, typically ` +
         `~50-70 % fewer tokens than general-purpose. ` +
         `Escape: add "ad-hoc" or "open-ended" to the description to bypass, or set ` +
-        `TOKEN_PILOT_MODE=advisory for warn-only behaviour.`;
+        `TOKEN_PILOT_MODE=advisory for warn-only behaviour.\n\n` +
+        SUBAGENT_TOOL_GUIDE;
     const hardBlock = ctx.force ||
         ctx.mode === "strict" ||
         (ctx.mode === "deny" && hit.confidence === "high" && ctx.force);

package/dist/hooks/safe-runner.d.ts

@@ -0,0 +1,48 @@
+/**
+ * v0.34.0 — `runHookSafely` / `runHookEntryPoint`.
+ *
+ * Every token-pilot hook used to wrap its own try/catch. When the
+ * branch broke (B2 stale binary, B8 bad cwd, B10 ast-index init
+ * race), throws were swallowed silently and the user saw "nothing
+ * happens". This wrapper centralises the discipline:
+ *
+ *   - Run the hook body
+ *   - On throw → record one structured `HookErrorRecord` to the
+ *     user-level error log
+ *   - Optionally measure duration and emit a `diagnostic` event
+ *     (Pack 3 — timing)
+ *   - ALWAYS exit 0 — Claude Code must never see a hook error
+ *     because that aborts the user's tool call.
+ *
+ * Hooks themselves keep responsibility for emitting domain-level
+ * diagnostics (matcher empty, WSL reject, etc.) — this wrapper is
+ * the safety net for unexpected throws.
+ */
+export interface RunHookOptions {
+    /** Hook name (matcher in hooks.json — e.g. "hook-pre-task"). */
+    hook: string;
+    /** Optional safe summary of the hook input — sanitised by caller. */
+    inputSummary?: Record<string, unknown>;
+    /** Plugin version, captured by caller and forwarded to the log. */
+    pluginVersion?: string;
+}
+/**
+ * Run a hook body and swallow any throw into the structured error log.
+ * Returns true on success, false on caught error — useful when the
+ * caller still wants to take a fallback action (e.g. emit a generic
+ * permissionDecision to Claude before exiting).
+ */
+export declare function runHookSafely(options: RunHookOptions, fn: () => Promise<void> | void): Promise<boolean>;
+/**
+ * The full entry-point wrapper used by `index.ts` cases. Wraps
+ * `runHookSafely` and additionally guarantees `process.exit(0)` at
+ * the end so a stray throw cannot leak a non-zero status to Claude.
+ *
+ * Pack 3: optionally measures duration and forwards it to the
+ * caller via `onTiming` so the timing diagnostic can be emitted
+ * after the hook body decided what to log to hook-events.jsonl.
+ */
+export declare function runHookEntryPoint(options: RunHookOptions & {
+    onTiming?: (durationMs: number) => Promise<void> | void;
+}, fn: () => Promise<void> | void): Promise<never>;
+//# sourceMappingURL=safe-runner.d.ts.map

package/dist/hooks/safe-runner.js

@@ -0,0 +1,73 @@
+/**
+ * v0.34.0 — `runHookSafely` / `runHookEntryPoint`.
+ *
+ * Every token-pilot hook used to wrap its own try/catch. When the
+ * branch broke (B2 stale binary, B8 bad cwd, B10 ast-index init
+ * race), throws were swallowed silently and the user saw "nothing
+ * happens". This wrapper centralises the discipline:
+ *
+ *   - Run the hook body
+ *   - On throw → record one structured `HookErrorRecord` to the
+ *     user-level error log
+ *   - Optionally measure duration and emit a `diagnostic` event
+ *     (Pack 3 — timing)
+ *   - ALWAYS exit 0 — Claude Code must never see a hook error
+ *     because that aborts the user's tool call.
+ *
+ * Hooks themselves keep responsibility for emitting domain-level
+ * diagnostics (matcher empty, WSL reject, etc.) — this wrapper is
+ * the safety net for unexpected throws.
+ */
+import { appendError, classifyError } from "../core/error-log.js";
+/**
+ * Run a hook body and swallow any throw into the structured error log.
+ * Returns true on success, false on caught error — useful when the
+ * caller still wants to take a fallback action (e.g. emit a generic
+ * permissionDecision to Claude before exiting).
+ */
+export async function runHookSafely(options, fn) {
+    try {
+        await fn();
+        return true;
+    }
+    catch (err) {
+        const e = err;
+        await appendError({
+            ts: Date.now(),
+            hook: options.hook,
+            level: "error",
+            code: classifyError(err),
+            msg: e?.message ?? String(err),
+            stack: e?.stack,
+            input: options.inputSummary,
+            pluginVersion: options.pluginVersion,
+            nodeVersion: process.version,
+            platform: process.platform,
+        });
+        return false;
+    }
+}
+/**
+ * The full entry-point wrapper used by `index.ts` cases. Wraps
+ * `runHookSafely` and additionally guarantees `process.exit(0)` at
+ * the end so a stray throw cannot leak a non-zero status to Claude.
+ *
+ * Pack 3: optionally measures duration and forwards it to the
+ * caller via `onTiming` so the timing diagnostic can be emitted
+ * after the hook body decided what to log to hook-events.jsonl.
+ */
+export async function runHookEntryPoint(options, fn) {
+    const started = Date.now();
+    await runHookSafely(options, fn);
+    const durationMs = Date.now() - started;
+    if (options.onTiming) {
+        try {
+            await options.onTiming(durationMs);
+        }
+        catch {
+            /* timing emit must never affect exit */
+        }
+    }
+    process.exit(0);
+}
+//# sourceMappingURL=safe-runner.js.map

package/dist/hooks/session-start.d.ts

@@ -7,6 +7,8 @@
  *
  * Output contract: one JSON line on stdout, or exit 0 silent.
  */
+import { type HookEvent } from "../core/event-log.js";
+export declare function buildSubagentAdoptionNudge(events: HookEvent[], now: number, windowDays?: number, minSample?: number, threshold?: number): string | null;
 export interface AgentEntry {
     name: string;
     description: string;

package/dist/hooks/session-start.js

@@ -10,7 +10,43 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join, basename } from "node:path";
 import { loadLatestSnapshot } from "./../handlers/session-snapshot-persist.js";
+import { loadEvents } from "../core/event-log.js";
 const SNAPSHOT_FRESH_MS = 2 * 3600 * 1000; // 2h — enough to cover compaction/restart, tight enough that a new day's unrelated work doesn't inherit yesterday's thread
+// ─── subagent adoption nudge (v0.32.0) ──────────────────────────────
+// Pure function: takes the event log + current time, returns either a
+// one-liner nudge string or null when there's nothing useful to say.
+// Thresholds are module-level constants so tests can reference them.
+const NUDGE_WINDOW_DAYS = 7;
+/** Minimum Task events in window before we consider the sample big enough. */
+const NUDGE_MIN_SAMPLE = 5;
+/** Miss-rate (routable general-purpose dispatches / total) above which we nudge. */
+const NUDGE_THRESHOLD = 0.5;
+export function buildSubagentAdoptionNudge(events, now, windowDays = NUDGE_WINDOW_DAYS, minSample = NUDGE_MIN_SAMPLE, threshold = NUDGE_THRESHOLD) {
+    const cutoff = now - windowDays * 86_400_000;
+    const tasks = events.filter((e) => e.event === "task" && e.ts >= cutoff);
+    if (tasks.length < minSample)
+        return null;
+    const misses = tasks.filter((e) => typeof e.matched_tp_agent === "string" &&
+        e.matched_tp_agent.length > 0 &&
+        e.subagent_type !== e.matched_tp_agent);
+    if (misses.length === 0)
+        return null;
+    const rate = misses.length / tasks.length;
+    if (rate < threshold)
+        return null;
+    const pct = Math.round(rate * 100);
+    // Surface the top routing miss pair so the nudge is concrete, not abstract.
+    const pairCounts = new Map();
+    for (const m of misses) {
+        const key = `${m.subagent_type} → ${m.matched_tp_agent}`;
+        pairCounts.set(key, (pairCounts.get(key) ?? 0) + 1);
+    }
+    const topPair = [...pairCounts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
+    const pairClause = topPair ? ` Top miss: ${topPair}.` : "";
+    return (`[token-pilot] subagent miss-rate ${pct}% over last ${windowDays}d ` +
+        `(${misses.length}/${tasks.length} Task calls could have used a tp-* specialist).${pairClause} ` +
+        `Run \`token-pilot stats --tasks\` for details, or set TOKEN_PILOT_FORCE_SUBAGENTS=1 to hard-block.`);
+}
 function extractSnapshotGoal(body) {
     const m = body.match(/\*\*Goal:\*\*\s*(.+?)(?:\n|$)/);
     return m ? m[1].trim().slice(0, 100) : null;
@@ -215,6 +251,19 @@ export async function handleSessionStart(opts) {
             const goalClause = goal ? ` (goal: "${goal}")` : "";
             message += `\n\n[token-pilot] session_snapshot from ${age}${goalClause}. Read .token-pilot/snapshots/latest.md to resume — or ignore if unrelated.`;
         }
+        // v0.32.0 — subagent adoption nudge. Reads recent Task telemetry
+        // from hook-events.jsonl; when the main thread is picking
+        // general-purpose on routable work, surface a one-liner so the
+        // user / agent sees the miss rate without needing `stats --tasks`.
+        try {
+            const events = await loadEvents(opts.projectRoot);
+            const nudge = buildSubagentAdoptionNudge(events, Date.now());
+            if (nudge)
+                message += `\n\n${nudge}`;
+        }
+        catch {
+            /* silent — telemetry nudge is strictly opt-in */
+        }
         const output = {
             hookSpecificOutput: {
                 hookEventName: "SessionStart",

package/dist/index.d.ts

@@ -15,6 +15,17 @@ export declare function main(cliArgs?: string[]): Promise<void>;
  * dev installs (cloning the repo and running against itself stays legal).
  */
 export declare function looksLikePluginCacheDir(candidate: string): boolean;
+/**
+ * v0.33.0 (B8) — reject candidates that are obviously not a project
+ * directory. Triggered by WSL launches where the shell starts in
+ * `C:\Windows\System32`, `/mnt/c/Windows/...`, or a UNC path. Without
+ * this guard, `git rev-parse --show-toplevel` either fails noisily or
+ * returns the Windows tree, leaving every subsequent git/MCP call
+ * looking at the wrong filesystem.
+ *
+ * Conservative — only matches paths we are certain are not user code.
+ */
+export declare function isWindowsSystemPath(candidate: string): boolean;
 export declare function startServer(cliArgs?: string[]): Promise<void>;
 export interface HookReadAdaptiveOptions {
     adaptiveThreshold?: boolean;