token-pilot 0.19.2 → 0.22.2

package/dist/hooks/installer.js

@@ -1,5 +1,5 @@
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { resolve, dirname } from 'node:path';
+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.
@@ -21,7 +21,7 @@ function createHookConfig(options) {
                     hooks: [
                         {
                             type: "command",
-                            command: buildHookCommand('hook-read', options),
+                            command: buildHookCommand("hook-read", options),
                         },
                     ],
                 },
@@ -30,7 +30,28 @@ function createHookConfig(options) {
                     hooks: [
                         {
                             type: "command",
-                            command: buildHookCommand('hook-edit', options),
+                            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),
                         },
                     ],
                 },
@@ -46,9 +67,13 @@ 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.' };
+        return {
+            installed: false,
+            fatal: false,
+            message: "Running as plugin — hooks registered via plugin system.",
+        };
     }
-    const settingsPath = resolve(projectRoot, '.claude', 'settings.json');
+    const settingsPath = resolve(projectRoot, ".claude", "settings.json");
     const hookConfig = createHookConfig(options);
     try {
         // Ensure .claude dir exists
@@ -56,7 +81,7 @@ export async function installHook(projectRoot, options) {
         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);
             }
@@ -70,7 +95,7 @@ export async function installHook(projectRoot, options) {
             }
         }
         catch (err) {
-            if (err?.code !== 'ENOENT') {
+            if (err?.code !== "ENOENT") {
                 return {
                     installed: false,
                     fatal: true,
@@ -81,24 +106,32 @@ export async function installHook(projectRoot, options) {
         }
         // 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)) {
             // 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/) // bare command without path
-            ));
+            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));
             }
             else {
-                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.' };
+                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 hooks
+            // 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) {
@@ -112,7 +145,30 @@ export async function installHook(projectRoot, options) {
                 settings.hooks = {};
             settings.hooks.PreToolUse = hookConfig.hooks.PreToolUse;
         }
-        await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+        // 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");
         return {
             installed: true,
             fatal: false,
@@ -121,33 +177,63 @@ export async function installHook(projectRoot, options) {
     }
     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 (Object.keys(settings.hooks).length === 0) {
+        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 (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 {
@@ -156,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

package/dist/hooks/session-start.js

@@ -0,0 +1,179 @@
+/**
+ * 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.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { join, basename } from "node:path";
+import { loadLatestSnapshot } from "./../handlers/session-snapshot-persist.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
+function extractSnapshotGoal(body) {
+    const m = body.match(/\*\*Goal:\*\*\s*(.+?)(?:\n|$)/);
+    return m ? m[1].trim().slice(0, 100) : null;
+}
+// ─── Agent scanner (subtask 2.2) ─────────────────────────────────────────────
+/**
+ * Parse YAML-style frontmatter from a markdown file.
+ * Only handles simple key: value pairs (no nested, no arrays).
+ * Returns an object with extracted string fields.
+ */
+function parseFrontmatter(content) {
+    const result = {};
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return result;
+    for (const line of match[1].split(/\r?\n/)) {
+        const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
+        if (kv) {
+            result[kv[1]] = kv[2].trim();
+        }
+    }
+    return result;
+}
+/**
+ * Scan one agents directory for tp-*.md files and return parsed entries.
+ */
+async function scanDir(dir) {
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const agents = [];
+    for (const filename of names) {
+        if (!filename.startsWith("tp-") || !filename.endsWith(".md"))
+            continue;
+        try {
+            const content = await readFile(join(dir, filename), "utf-8");
+            const fm = parseFrontmatter(content);
+            const stem = basename(filename, ".md");
+            agents.push({
+                name: fm.name ?? stem,
+                description: fm.description ?? "",
+            });
+        }
+        catch {
+            // Skip unreadable files
+        }
+    }
+    return agents;
+}
+/**
+ * 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 async function scanAgents(projectRoot, homeDir) {
+    const projectAgentsDir = join(projectRoot, ".claude", "agents");
+    const homeAgentsDir = join(homeDir, ".claude", "agents");
+    const [projectAgents, homeAgents] = await Promise.all([
+        scanDir(projectAgentsDir),
+        scanDir(homeAgentsDir),
+    ]);
+    // Merge: project agents first; home agents fill in names not already present
+    const seen = new Set();
+    const merged = [];
+    for (const agent of [...projectAgents, ...homeAgents]) {
+        if (!seen.has(agent.name)) {
+            seen.add(agent.name);
+            merged.push(agent);
+        }
+    }
+    return merged;
+}
+// ─── Message builder (subtask 2.3) ───────────────────────────────────────────
+const MANDATORY_BLOCK = `[token-pilot active]
+
+MANDATORY — for code files, use these before raw Read:
+  mcp__token-pilot__smart_read(path)        — structural overview
+  mcp__token-pilot__read_symbol(path, sym)  — one function / class
+  mcp__token-pilot__read_for_edit(path, sym)— exact text for editing
+  mcp__token-pilot__outline(path)           — symbol list
+Raw Read allowed only with offset/limit or TOKEN_PILOT_BYPASS=1.`;
+function estimateTokens(text) {
+    // Fast approximation: chars / 4, adjusted for whitespace
+    if (text.length === 0)
+        return 0;
+    return Math.ceil(text.length / 4);
+}
+/**
+ * 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 function buildReminderMessage(agents, maxReminderTokens) {
+    const agentLines = agents.length === 0
+        ? "  none installed — run: npx token-pilot install-agents"
+        : agents.map((a) => `  ${a.name}  — ${a.description}`).join("\n");
+    const delegatingSection = `WHEN DELEGATING — use the right token-pilot-native subagent:\n${agentLines}`;
+    const full = `${MANDATORY_BLOCK}\n\n${delegatingSection}`;
+    if (estimateTokens(full) <= maxReminderTokens) {
+        return full;
+    }
+    // Trim agent list until we fit. Distinguish "all agents trimmed due to
+    // budget" (count remained >0 in the original list) from "no agents at
+    // all" — they look the same to `trimmedAgents.length === 0` but mean
+    // very different things to the caller (one requires install-agents; the
+    // other just reports "N more hidden").
+    let trimmedAgents = [...agents];
+    while (trimmedAgents.length > 0) {
+        trimmedAgents = trimmedAgents.slice(0, trimmedAgents.length - 1);
+        const dropped = agents.length - trimmedAgents.length;
+        const trimmedLines = trimmedAgents.length === 0
+            ? `  … and ${dropped} more (reminder budget exhausted)`
+            : trimmedAgents
+                .map((a) => `  ${a.name}  — ${a.description}`)
+                .join("\n") + `\n  … and ${dropped} more`;
+        const candidate = `${MANDATORY_BLOCK}\n\nWHEN DELEGATING — use the right token-pilot-native subagent:\n${trimmedLines}`;
+        if (estimateTokens(candidate) <= maxReminderTokens) {
+            return candidate;
+        }
+    }
+    // Last resort: just the mandatory block
+    return MANDATORY_BLOCK;
+}
+// ─── Handler (subtask 2.4) ───────────────────────────────────────────────────
+/**
+ * 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 async function handleSessionStart(opts) {
+    try {
+        if (!opts.sessionStartConfig.enabled) {
+            return null;
+        }
+        const agents = await scanAgents(opts.projectRoot, opts.homeDir);
+        let message = buildReminderMessage(agents, opts.sessionStartConfig.maxReminderTokens);
+        // TP-340: surface a fresh snapshot so the new session can resume.
+        const snap = await loadLatestSnapshot(opts.projectRoot);
+        if (snap && snap.ageMs < SNAPSHOT_FRESH_MS) {
+            const minutes = Math.round(snap.ageMs / 60000);
+            const age = minutes < 60 ? `${minutes}m ago` : `${Math.round(minutes / 60)}h ago`;
+            const goal = extractSnapshotGoal(snap.body);
+            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.`;
+        }
+        const output = {
+            hookSpecificOutput: {
+                hookEventName: "SessionStart",
+                additionalContext: message,
+            },
+        };
+        return JSON.stringify(output);
+    }
+    catch {
+        // Fail-safe: never block the session
+        return null;
+    }
+}
+//# sourceMappingURL=session-start.js.map

package/dist/hooks/summary-ast-index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Primary hook-summary parser: spawns the bundled `ast-index` binary with
+ * `ast-index outline <path>` and maps the returned outline entries to
+ * SignalLine[]. Returns null when the binary is unavailable or the
+ * subprocess fails — the pipeline then falls back to regex / head+tail.
+ *
+ * Short-lived: the hook process spawns the binary once per invocation.
+ * The long-running AstIndexClient used by the MCP server is intentionally
+ * NOT reused here to keep the hook's startup cost minimal.
+ */
+import type { HookSummary } from "./summary-types.js";
+type ExecFn = (binary: string, args: string[], opts: {
+    timeout: number;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export interface AstIndexSummaryOptions {
+    /** Explicit binary path. `null` means "no binary available" → returns null. Omit to resolve via findBinary. */
+    binaryPath?: string | null;
+    /** Subprocess timeout (ms). Default 4000. */
+    timeoutMs?: number;
+    /** Injectable spawner for tests. */
+    exec?: ExecFn;
+}
+export declare function parseAstIndexSummary(content: string, filePath: string, options?: AstIndexSummaryOptions): Promise<HookSummary | null>;
+export {};
+//# sourceMappingURL=summary-ast-index.d.ts.map