token-pilot 0.19.1 → 0.22.2

package/dist/hooks/installer.d.ts

@@ -8,11 +8,17 @@ export interface HookUninstallResult {
     fatal: boolean;
     message: string;
 }
+export interface HookInstallOptions {
+    /** Absolute path to the entry script (dist/index.js). When provided, hooks use absolute paths instead of bare "token-pilot". */
+    scriptPath?: string;
+    /** Absolute path to the node binary. Defaults to process.execPath. */
+    nodeExecPath?: string;
+}
 /**
  * Install Token Pilot hook into Claude Code settings.
  * Creates or updates .claude/settings.json with PreToolUse hook.
  */
-export declare function installHook(projectRoot: string): Promise<HookInstallResult>;
+export declare function installHook(projectRoot: string, options?: HookInstallOptions): Promise<HookInstallResult>;
 /**
  * Remove Token Pilot hook from Claude Code settings.
  */

package/dist/hooks/installer.js

@@ -1,42 +1,87 @@
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { resolve, dirname } from 'node:path';
-const HOOK_CONFIG = {
-    hooks: {
-        PreToolUse: [
-            {
-                matcher: "Read",
-                hooks: [
-                    {
-                        type: "command",
-                        command: "token-pilot hook-read",
-                    },
-                ],
-            },
-            {
-                matcher: "Edit",
-                hooks: [
-                    {
-                        type: "command",
-                        command: "token-pilot hook-edit",
-                    },
-                ],
-            },
-        ],
-    },
-};
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+/**
+ * Build hook command that works in any shell (/bin/sh, bash, etc.)
+ * Uses absolute paths to node + script to avoid PATH/nvm issues.
+ * Falls back to bare "token-pilot" only for manual CLI installs.
+ */
+function buildHookCommand(action, options) {
+    if (options?.scriptPath) {
+        const node = options.nodeExecPath || process.execPath;
+        return `${node} ${options.scriptPath} ${action}`;
+    }
+    return `token-pilot ${action}`;
+}
+function createHookConfig(options) {
+    return {
+        hooks: {
+            PreToolUse: [
+                {
+                    matcher: "Read",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: buildHookCommand("hook-read", options),
+                        },
+                    ],
+                },
+                {
+                    matcher: "Edit",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: buildHookCommand("hook-edit", options),
+                        },
+                    ],
+                },
+            ],
+            SessionStart: [
+                {
+                    hooks: [
+                        {
+                            type: "command",
+                            command: buildHookCommand("hook-session-start", options),
+                        },
+                    ],
+                },
+            ],
+            PostToolUse: [
+                {
+                    matcher: "Bash",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: buildHookCommand("hook-post-bash", options),
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+}
 /**
  * Install Token Pilot hook into Claude Code settings.
  * Creates or updates .claude/settings.json with PreToolUse hook.
  */
-export async function installHook(projectRoot) {
-    const settingsPath = resolve(projectRoot, '.claude', 'settings.json');
+export async function installHook(projectRoot, options) {
+    // Skip auto-install when running as a Claude Code plugin —
+    // the plugin system already registers hooks via .claude-plugin/hooks/hooks.json
+    if (process.env.CLAUDE_PLUGIN_ROOT) {
+        return {
+            installed: false,
+            fatal: false,
+            message: "Running as plugin — hooks registered via plugin system.",
+        };
+    }
+    const settingsPath = resolve(projectRoot, ".claude", "settings.json");
+    const hookConfig = createHookConfig(options);
     try {
         // Ensure .claude dir exists
         await mkdir(dirname(settingsPath), { recursive: true });
         let settings = {};
         // Try to read existing settings
         try {
-            const raw = await readFile(settingsPath, 'utf-8');
+            const raw = await readFile(settingsPath, "utf-8");
             try {
                 settings = JSON.parse(raw);
             }
@@ -50,7 +95,7 @@ export async function installHook(projectRoot) {
             }
         }
         catch (err) {
-            if (err?.code !== 'ENOENT') {
+            if (err?.code !== "ENOENT") {
                 return {
                     installed: false,
                     fatal: true,
@@ -61,18 +106,36 @@ export async function installHook(projectRoot) {
         }
         // Check which Token Pilot hooks already exist
         const existingHooks = settings.hooks?.PreToolUse;
-        const isTokenPilotHook = (h) => h.hooks?.some((hook) => hook.command?.includes('token-pilot'));
+        const isTokenPilotHook = (h) => h.hooks?.some((hook) => hook.command?.includes("token-pilot"));
         if (Array.isArray(existingHooks)) {
-            const hasRead = existingHooks.some((h) => h.matcher === 'Read' && isTokenPilotHook(h));
-            const hasEdit = existingHooks.some((h) => h.matcher === 'Edit' && isTokenPilotHook(h));
-            if (hasRead && hasEdit) {
-                return { installed: false, fatal: false, message: 'Token Pilot hooks already installed.' };
+            // Remove old broken hooks (bare "token-pilot" without absolute path)
+            // 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/)));
+            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));
             }
-            // Add missing hooks
-            for (const hookDef of HOOK_CONFIG.hooks.PreToolUse) {
-                const exists = existingHooks.some((h) => h.matcher === hookDef.matcher && isTokenPilotHook(h));
+            else {
+                const hasRead = existingHooks.some((h) => h.matcher === "Read" && isTokenPilotHook(h));
+                const hasEdit = existingHooks.some((h) => h.matcher === "Edit" && isTokenPilotHook(h));
+                const hasSessionStart = Array.isArray(settings.hooks?.SessionStart) &&
+                    settings.hooks.SessionStart.some(isTokenPilotHook);
+                const hasPostBashHook = Array.isArray(settings.hooks?.PostToolUse) &&
+                    settings.hooks.PostToolUse.some(isTokenPilotHook);
+                if (hasRead && hasEdit && hasSessionStart && hasPostBashHook) {
+                    return {
+                        installed: false,
+                        fatal: false,
+                        message: "Token Pilot hooks already installed.",
+                    };
+                }
+            }
+            // Add missing PreToolUse hooks
+            for (const hookDef of hookConfig.hooks.PreToolUse) {
+                const exists = settings.hooks.PreToolUse.some((h) => h.matcher === hookDef.matcher && isTokenPilotHook(h));
                 if (!exists) {
-                    existingHooks.push(hookDef);
+                    settings.hooks.PreToolUse.push(hookDef);
                 }
             }
         }
@@ -80,9 +143,32 @@ export async function installHook(projectRoot) {
             // Create hooks section
             if (!settings.hooks)
                 settings.hooks = {};
-            settings.hooks.PreToolUse = HOOK_CONFIG.hooks.PreToolUse;
+            settings.hooks.PreToolUse = hookConfig.hooks.PreToolUse;
+        }
+        // Install SessionStart hook idempotently
+        const existingSessionStart = settings.hooks?.SessionStart;
+        const hasSessionStart = Array.isArray(existingSessionStart) &&
+            existingSessionStart.some(isTokenPilotHook);
+        if (!hasSessionStart) {
+            if (!settings.hooks)
+                settings.hooks = {};
+            if (!Array.isArray(settings.hooks.SessionStart)) {
+                settings.hooks.SessionStart = [];
+            }
+            settings.hooks.SessionStart.push(...hookConfig.hooks.SessionStart);
+        }
+        // Install PostToolUse (Bash advisor) hook idempotently
+        const existingPost = settings.hooks?.PostToolUse;
+        const hasPostBash = Array.isArray(existingPost) && existingPost.some(isTokenPilotHook);
+        if (!hasPostBash) {
+            if (!settings.hooks)
+                settings.hooks = {};
+            if (!Array.isArray(settings.hooks.PostToolUse)) {
+                settings.hooks.PostToolUse = [];
+            }
+            settings.hooks.PostToolUse.push(...hookConfig.hooks.PostToolUse);
         }
-        await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+        await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n");
         return {
             installed: true,
             fatal: false,
@@ -91,33 +177,63 @@ export async function installHook(projectRoot) {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        return { installed: false, fatal: true, message: `Failed to install hook: ${msg}` };
+        return {
+            installed: false,
+            fatal: true,
+            message: `Failed to install hook: ${msg}`,
+        };
     }
 }
 /**
  * Remove Token Pilot hook from Claude Code settings.
  */
 export async function uninstallHook(projectRoot) {
-    const settingsPath = resolve(projectRoot, '.claude', 'settings.json');
+    const settingsPath = resolve(projectRoot, ".claude", "settings.json");
     try {
-        const raw = await readFile(settingsPath, 'utf-8');
+        const raw = await readFile(settingsPath, "utf-8");
         const settings = JSON.parse(raw);
-        if (!settings.hooks?.PreToolUse) {
-            return { removed: false, fatal: false, message: 'No hooks to remove.' };
+        const hasPreToolUse = !!settings.hooks?.PreToolUse;
+        const hasSessionStart = !!settings.hooks?.SessionStart;
+        const hasPostToolUse = !!settings.hooks?.PostToolUse;
+        if (!hasPreToolUse && !hasSessionStart && !hasPostToolUse) {
+            return { removed: false, fatal: false, message: "No hooks to remove." };
         }
-        settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter((h) => !h.hooks?.some((hook) => hook.command?.includes('token-pilot')));
-        if (settings.hooks.PreToolUse.length === 0) {
-            delete settings.hooks.PreToolUse;
+        const isTokenPilotHook = (h) => h.hooks?.some((hook) => hook.command?.includes("token-pilot"));
+        if (Array.isArray(settings.hooks?.PreToolUse)) {
+            settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter((h) => !isTokenPilotHook(h));
+            if (settings.hooks.PreToolUse.length === 0) {
+                delete settings.hooks.PreToolUse;
+            }
+        }
+        if (Array.isArray(settings.hooks?.SessionStart)) {
+            settings.hooks.SessionStart = settings.hooks.SessionStart.filter((h) => !isTokenPilotHook(h));
+            if (settings.hooks.SessionStart.length === 0) {
+                delete settings.hooks.SessionStart;
+            }
+        }
+        if (Array.isArray(settings.hooks?.PostToolUse)) {
+            settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter((h) => !isTokenPilotHook(h));
+            if (settings.hooks.PostToolUse.length === 0) {
+                delete settings.hooks.PostToolUse;
+            }
         }
-        if (Object.keys(settings.hooks).length === 0) {
+        if (settings.hooks && Object.keys(settings.hooks).length === 0) {
             delete settings.hooks;
         }
-        await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-        return { removed: true, fatal: false, message: 'Token Pilot hook removed.' };
+        await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+        return {
+            removed: true,
+            fatal: false,
+            message: "Token Pilot hook removed.",
+        };
     }
     catch (err) {
-        if (err?.code === 'ENOENT') {
-            return { removed: false, fatal: false, message: 'Settings file not found.' };
+        if (err?.code === "ENOENT") {
+            return {
+                removed: false,
+                fatal: false,
+                message: "Settings file not found.",
+            };
         }
         if (err instanceof SyntaxError) {
             return {
@@ -126,7 +242,11 @@ export async function uninstallHook(projectRoot) {
                 message: `Settings file contains invalid JSON: ${settingsPath}. Fix it manually before uninstalling hooks.`,
             };
         }
-        return { removed: false, fatal: true, message: `Failed to process settings: ${err?.message ?? err}` };
+        return {
+            removed: false,
+            fatal: true,
+            message: `Failed to process settings: ${err?.message ?? err}`,
+        };
     }
 }
 //# sourceMappingURL=installer.js.map

package/dist/hooks/path-safety.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Path-safety check used by the PreToolUse hook before reading any file.
+ *
+ * Resolves both the target file and the project root through realpath
+ * (so symlinks cannot escape the sandbox), then requires the resolved
+ * file path to fall inside the resolved project directory. On any error
+ * (missing file, permission denied, realpath loop) we refuse — the hook
+ * will then pass-through rather than risk reading an attacker-crafted
+ * path.
+ *
+ * Sibling directories that share a common prefix (e.g. `/tmp/proj`
+ * vs `/tmp/proj-evil`) are rejected by forcing a path-separator on the
+ * normalised root.
+ */
+export declare function isPathWithinProject(filePath: string, projectRoot: string): boolean;
+//# sourceMappingURL=path-safety.d.ts.map

package/dist/hooks/path-safety.js

@@ -0,0 +1,34 @@
+/**
+ * Path-safety check used by the PreToolUse hook before reading any file.
+ *
+ * Resolves both the target file and the project root through realpath
+ * (so symlinks cannot escape the sandbox), then requires the resolved
+ * file path to fall inside the resolved project directory. On any error
+ * (missing file, permission denied, realpath loop) we refuse — the hook
+ * will then pass-through rather than risk reading an attacker-crafted
+ * path.
+ *
+ * Sibling directories that share a common prefix (e.g. `/tmp/proj`
+ * vs `/tmp/proj-evil`) are rejected by forcing a path-separator on the
+ * normalised root.
+ */
+import { realpathSync } from "node:fs";
+import { resolve, sep } from "node:path";
+export function isPathWithinProject(filePath, projectRoot) {
+    if (!filePath || !projectRoot)
+        return false;
+    let resolvedFile;
+    let resolvedRoot;
+    try {
+        resolvedFile = realpathSync(resolve(filePath));
+        resolvedRoot = realpathSync(resolve(projectRoot));
+    }
+    catch {
+        return false;
+    }
+    if (resolvedFile === resolvedRoot)
+        return true;
+    const prefix = resolvedRoot.endsWith(sep) ? resolvedRoot : resolvedRoot + sep;
+    return resolvedFile.startsWith(prefix);
+}
+//# sourceMappingURL=path-safety.js.map

package/dist/hooks/post-bash.d.ts

@@ -0,0 +1,46 @@
+/**
+ * TP-jzh — Bash output advisor.
+ *
+ * Claude Code's PostToolUse hook cannot modify or truncate `tool_response`
+ * (verified via Claude Code docs 2026-04-18 — the `updatedMCPToolOutput`
+ * field is MCP-only). The agent has already seen the full stdout by the
+ * time our hook fires.
+ *
+ * So the feature becomes an *advisory*: when Bash stdout is large, we
+ * append one line via `additionalContext` pointing the agent at cheaper
+ * alternatives (`mcp__token-pilot__test_summary` for tests, bounded
+ * commands, head/tail piping). The agent notices before it repeats the
+ * mistake on the next turn.
+ */
+export interface PostBashHookInput {
+    tool_name?: string;
+    tool_response?: unknown;
+}
+export interface PostBashAdvice {
+    /** Null when no advice is needed. */
+    additionalContext: string | null;
+    /** For telemetry: approximate output size the advisor saw. */
+    outputChars: number;
+}
+declare const LARGE_OUTPUT_THRESHOLD_CHARS = 8000;
+/**
+ * Pure decision function. Given a PostToolUse hook input for the Bash
+ * tool, return advice text (or null to stay silent).
+ */
+export interface PostBashAdviceOptions {
+    thresholdChars?: number;
+    /**
+     * When true, the advice also mentions context-mode — runs the command
+     * in a sandbox so only stdout enters context. Caller detects whether
+     * context-mode is installed and passes the flag.
+     */
+    contextModeAvailable?: boolean;
+}
+export declare function decidePostBashAdvice(input: PostBashHookInput, thresholdCharsOrOpts?: number | PostBashAdviceOptions): PostBashAdvice;
+/**
+ * Render the JSON payload Claude Code expects. Returns null for silent
+ * pass-through so the caller can simply `exit(0)` with no stdout.
+ */
+export declare function renderPostBashHookOutput(advice: PostBashAdvice): string | null;
+export { LARGE_OUTPUT_THRESHOLD_CHARS };
+//# sourceMappingURL=post-bash.d.ts.map

package/dist/hooks/post-bash.js

@@ -0,0 +1,77 @@
+/**
+ * TP-jzh — Bash output advisor.
+ *
+ * Claude Code's PostToolUse hook cannot modify or truncate `tool_response`
+ * (verified via Claude Code docs 2026-04-18 — the `updatedMCPToolOutput`
+ * field is MCP-only). The agent has already seen the full stdout by the
+ * time our hook fires.
+ *
+ * So the feature becomes an *advisory*: when Bash stdout is large, we
+ * append one line via `additionalContext` pointing the agent at cheaper
+ * alternatives (`mcp__token-pilot__test_summary` for tests, bounded
+ * commands, head/tail piping). The agent notices before it repeats the
+ * mistake on the next turn.
+ */
+const LARGE_OUTPUT_THRESHOLD_CHARS = 8000;
+function extractStdout(tool_response) {
+    if (!tool_response)
+        return "";
+    if (typeof tool_response === "string")
+        return tool_response;
+    if (typeof tool_response === "object") {
+        const r = tool_response;
+        const parts = [];
+        for (const key of ["stdout", "output", "content"]) {
+            const v = r[key];
+            if (typeof v === "string")
+                parts.push(v);
+        }
+        return parts.join("\n");
+    }
+    return "";
+}
+function countLines(s) {
+    if (s === "")
+        return 0;
+    return s.split(/\r?\n/).length;
+}
+export function decidePostBashAdvice(input, thresholdCharsOrOpts = LARGE_OUTPUT_THRESHOLD_CHARS) {
+    const opts = typeof thresholdCharsOrOpts === "number"
+        ? { thresholdChars: thresholdCharsOrOpts }
+        : thresholdCharsOrOpts;
+    const threshold = opts.thresholdChars ?? LARGE_OUTPUT_THRESHOLD_CHARS;
+    if (input.tool_name !== "Bash") {
+        return { additionalContext: null, outputChars: 0 };
+    }
+    const stdout = extractStdout(input.tool_response);
+    const chars = stdout.length;
+    if (chars < threshold) {
+        return { additionalContext: null, outputChars: chars };
+    }
+    const lines = countLines(stdout);
+    const roughTokens = Math.ceil(chars / 4);
+    const contextModeLine = opts.contextModeAvailable
+        ? " Or run via mcp__context-mode__execute — sandbox keeps stdout out of your window."
+        : "";
+    const msg = `⚠ Bash output was large (~${lines} lines, ~${roughTokens} tokens). ` +
+        `Consider mcp__token-pilot__test_summary for test runs, or bounded commands ` +
+        `(head/tail, --oneline, git log -n <N>, grep -m <N>) to keep context lean.` +
+        contextModeLine;
+    return { additionalContext: msg, outputChars: chars };
+}
+/**
+ * Render the JSON payload Claude Code expects. Returns null for silent
+ * pass-through so the caller can simply `exit(0)` with no stdout.
+ */
+export function renderPostBashHookOutput(advice) {
+    if (!advice.additionalContext)
+        return null;
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PostToolUse",
+            additionalContext: advice.additionalContext,
+        },
+    });
+}
+export { LARGE_OUTPUT_THRESHOLD_CHARS };
+//# sourceMappingURL=post-bash.js.map

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

@@ -0,0 +1,45 @@
+/**
+ * SessionStart reminder hook — Component 2 of the enforcement layer.
+ *
+ * On every session start / /clear / /compact, emits a compact additionalContext
+ * block containing the mandatory-tool rules and a list of tp-* subagents found
+ * in the project and user agent directories.
+ *
+ * Output contract: one JSON line on stdout, or exit 0 silent.
+ */
+export interface AgentEntry {
+    name: string;
+    description: string;
+}
+export interface SessionStartConfig {
+    enabled: boolean;
+    showStats: boolean;
+    maxReminderTokens: number;
+}
+export interface HandleSessionStartOptions {
+    projectRoot: string;
+    homeDir: string;
+    sessionStartConfig: SessionStartConfig;
+}
+/**
+ * Scan ~/.claude/agents/ and ./.claude/agents/ for tp-*.md agent definitions.
+ * Project directory takes precedence; duplicates (by name) are dropped.
+ *
+ * @param projectRoot - absolute path to the project root
+ * @param homeDir - home directory (injected for testability; defaults to os.homedir())
+ */
+export declare function scanAgents(projectRoot: string, homeDir: string): Promise<AgentEntry[]>;
+/**
+ * Build the reminder message combining the mandatory-tool rules and the
+ * tp-* agent list.  Enforces the maxReminderTokens budget by trimming the
+ * delegating list with "… and N more" if needed.
+ */
+export declare function buildReminderMessage(agents: AgentEntry[], maxReminderTokens: number): string;
+/**
+ * Main handler for the hook-session-start CLI command.
+ *
+ * Returns the JSON string to write to stdout, or null for silent exit.
+ * Never throws — any error → null (fail-safe pass-through).
+ */
+export declare function handleSessionStart(opts: HandleSessionStartOptions): Promise<string | null>;
+//# sourceMappingURL=session-start.d.ts.map