token-pilot 0.32.0 → 0.33.0

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/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;