token-pilot 0.19.1 → 0.22.2

package/dist/index.js

@@ -1,65 +1,201 @@
 #!/usr/bin/env node
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { readFileSync, realpathSync, appendFileSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import { fileURLToPath } from 'node:url';
-import { createServer } from './server.js';
-import { installHook, uninstallHook } from './hooks/installer.js';
-import { findBinary, installBinary, checkBinaryUpdate, isNewerVersion } from './ast-index/binary-manager.js';
-import { loadConfig } from './config/loader.js';
-import { isDangerousRoot } from './core/validation.js';
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { readFileSync, realpathSync, appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import { createServer } from "./server.js";
+import { installHook, uninstallHook } from "./hooks/installer.js";
+import { findBinary, installBinary, checkBinaryUpdate, isNewerVersion, } from "./ast-index/binary-manager.js";
+import { loadConfig } from "./config/loader.js";
+import { isDangerousRoot } from "./core/validation.js";
+import { runSummaryPipeline } from "./hooks/summary-pipeline.js";
+import { formatDenyMessage } from "./hooks/format-deny-message.js";
+import { isPathWithinProject } from "./hooks/path-safety.js";
+import { handleSessionStart } from "./hooks/session-start.js";
+import { computeEffectiveThreshold } from "./hooks/adaptive-threshold.js";
+import { loadSessionSavedTokens } from "./core/session-savings.js";
+import { handleSaveDocCli, handleListDocsCli } from "./cli/save-doc.js";
+import { isContextModeInstalledSync } from "./integration/context-mode-detector.js";
+import { handleBlessAgents } from "./cli/bless-agents.js";
+import { unblessAgents } from "./cli/unbless-agents.js";
+import { detectDrift, formatDriftFinding } from "./cli/doctor-drift.js";
+import { handleInstallAgents, maybeEmitStartupReminder, } from "./cli/install-agents.js";
+import { handleUninstallAgents } from "./cli/uninstall-agents.js";
+import { appendEvent, applyRetention, } from "./core/event-log.js";
+import { handleStats } from "./cli/stats.js";
+import { promptYesNo } from "./cli/install-agents.js";
+import { runClaudeCodeEnvCheck } from "./cli/doctor-env-check.js";
+import { claudeIgnoreStatus, writeDefaultClaudeIgnore, } from "./cli/claudeignore.js";
+import { assessClaudeMd } from "./cli/claudemd-hygiene.js";
+import { decidePostBashAdvice, renderPostBashHookOutput, } from "./hooks/post-bash.js";
 const execFileAsync = promisify(execFile);
 export const CODE_EXTENSIONS = new Set([
-    'ts', 'tsx', 'js', 'jsx', 'mjs', 'py', 'go', 'rs', 'java', 'kt', 'kts',
-    'swift', 'cs', 'cpp', 'cc', 'cxx', 'hpp', 'c', 'h', 'php', 'rb', 'scala',
-    'dart', 'lua', 'sh', 'bash', 'sql', 'r', 'vue', 'svelte', 'pl', 'pm',
-    'ex', 'exs', 'groovy', 'm', 'proto', 'bsl',
-    'lisp', 'lsp', 'cl', 'asd',
+    "ts",
+    "tsx",
+    "js",
+    "jsx",
+    "mjs",
+    "py",
+    "go",
+    "rs",
+    "java",
+    "kt",
+    "kts",
+    "swift",
+    "cs",
+    "cpp",
+    "cc",
+    "cxx",
+    "hpp",
+    "c",
+    "h",
+    "php",
+    "rb",
+    "scala",
+    "dart",
+    "lua",
+    "sh",
+    "bash",
+    "sql",
+    "r",
+    "vue",
+    "svelte",
+    "pl",
+    "pm",
+    "ex",
+    "exs",
+    "groovy",
+    "m",
+    "proto",
+    "bsl",
+    "lisp",
+    "lsp",
+    "cl",
+    "asd",
 ]);
 export function getVersion() {
     try {
-        const pkgPath = new URL('../package.json', import.meta.url).pathname;
-        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        const pkgPath = new URL("../package.json", import.meta.url).pathname;
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
         return pkg.version;
     }
     catch {
-        return '0.0.0';
+        return "0.0.0";
     }
 }
 export async function main(cliArgs = process.argv.slice(2)) {
     switch (cliArgs[0]) {
-        case 'hook-read': {
+        case "hook-read": {
             const cfg = await loadConfig(process.cwd());
-            handleHookRead(cliArgs[1], cfg.hooks.denyThreshold);
+            await handleHookRead(cliArgs[1], cfg.hooks.mode, cfg.hooks.denyThreshold, process.cwd(), {
+                adaptiveThreshold: cfg.hooks.adaptiveThreshold,
+                adaptiveBudgetTokens: cfg.hooks.adaptiveBudgetTokens,
+            });
             return;
         }
-        case 'hook-edit':
+        case "hook-edit":
             handleHookEdit();
             return;
-        case 'install-hook':
+        case "hook-post-bash": {
+            try {
+                const stdin = readFileSync(0, "utf-8");
+                const input = JSON.parse(stdin);
+                const advice = decidePostBashAdvice(input, {
+                    contextModeAvailable: isContextModeInstalledSync(process.cwd()),
+                });
+                const rendered = renderPostBashHookOutput(advice);
+                if (rendered)
+                    process.stdout.write(rendered);
+            }
+            catch {
+                /* silent — hook must not break */
+            }
+            process.exit(0);
+            return;
+        }
+        case "hook-session-start": {
+            const cfg = await loadConfig(process.cwd());
+            // `sessionStart.enabled` is independent of `hooks.mode` by design —
+            // a user may want the Read-blocking hook off (mode:"off") while still
+            // getting the tool-rules reminder at session start, or vice versa.
+            if (!cfg.sessionStart.enabled) {
+                process.exit(0);
+            }
+            const result = await handleSessionStart({
+                projectRoot: process.cwd(),
+                homeDir: homedir(),
+                sessionStartConfig: cfg.sessionStart,
+            });
+            if (result) {
+                process.stdout.write(result);
+            }
+            process.exit(0);
+            return;
+        }
+        case "install-hook":
             await handleInstallHook(cliArgs[1] || process.cwd());
             return;
-        case 'uninstall-hook':
+        case "uninstall-hook":
             await handleUninstallHook(cliArgs[1] || process.cwd());
             return;
-        case 'install-ast-index':
+        case "install-ast-index":
             await handleInstallAstIndex();
             return;
-        case 'doctor':
+        case "doctor":
             await handleDoctor();
             return;
-        case 'init':
+        case "bless-agents":
+            await handleBlessAgents(cliArgs.slice(1));
+            return;
+        case "unbless-agents": {
+            const args = cliArgs.slice(1);
+            const all = args.includes("--all");
+            const names = args.filter((a) => !a.startsWith("--"));
+            if (!all && names.length === 0) {
+                process.stderr.write("Usage: token-pilot unbless-agents <name>... | --all\n");
+                process.exit(1);
+            }
+            await unblessAgents({ projectRoot: process.cwd(), names, all });
+            return;
+        }
+        case "install-agents": {
+            const code = await handleInstallAgents(cliArgs.slice(1));
+            process.exit(code);
+            return;
+        }
+        case "uninstall-agents": {
+            const code = await handleUninstallAgents(cliArgs.slice(1));
+            process.exit(code);
+            return;
+        }
+        case "stats": {
+            const code = await handleStats(cliArgs.slice(1));
+            process.exit(code);
+            return;
+        }
+        case "save-doc": {
+            const code = await handleSaveDocCli(cliArgs.slice(1));
+            process.exit(code);
+            return;
+        }
+        case "list-docs": {
+            const code = await handleListDocsCli();
+            process.exit(code);
+            return;
+        }
+        case "init":
             await handleInit(cliArgs[1] || process.cwd());
             return;
-        case '--version':
-        case '-v':
+        case "--version":
+        case "-v":
             console.log(getVersion());
             process.exit(0);
             return;
-        case '--help':
-        case '-h':
+        case "--help":
+        case "-h":
             printHelp();
             return;
         default:
@@ -76,20 +212,20 @@ export async function startServer(cliArgs = process.argv.slice(2)) {
             process.env.INIT_CWD, // npm/npx sets this to invoking directory
             process.env.PWD, // shell working directory (may differ from cwd)
             process.cwd(), // Node.js working directory
-        ].filter((c) => !!c && c !== '/');
+        ].filter((c) => !!c && c !== "/");
         let detected = false;
         for (const candidate of candidates) {
             if (isDangerousRoot(candidate))
                 continue;
             try {
-                const { stdout } = await execFileAsync('git', ['rev-parse', '--show-toplevel'], {
+                const { stdout } = await execFileAsync("git", ["rev-parse", "--show-toplevel"], {
                     cwd: candidate,
                     timeout: 3000,
                 });
                 const gitRoot = stdout.trim();
                 if (gitRoot && !isDangerousRoot(gitRoot)) {
                     projectRoot = gitRoot;
-                    console.error(`[token-pilot] project root: ${projectRoot} (git from ${candidate === process.env.INIT_CWD ? 'INIT_CWD' : candidate === process.env.PWD ? 'PWD' : 'cwd'})`);
+                    console.error(`[token-pilot] project root: ${projectRoot} (git from ${candidate === process.env.INIT_CWD ? "INIT_CWD" : candidate === process.env.PWD ? "PWD" : "cwd"})`);
                     detected = true;
                     break;
                 }
@@ -100,10 +236,10 @@ export async function startServer(cliArgs = process.argv.slice(2)) {
         }
         if (!detected) {
             // Use best non-dangerous candidate as fallback even without git
-            const fallback = candidates.find(c => !isDangerousRoot(c));
+            const fallback = candidates.find((c) => !isDangerousRoot(c));
             if (fallback) {
                 projectRoot = fallback;
-                console.error(`[token-pilot] project root: ${projectRoot} (${fallback === process.env.INIT_CWD ? 'INIT_CWD' : 'PWD'}, not a git repo)`);
+                console.error(`[token-pilot] project root: ${projectRoot} (${fallback === process.env.INIT_CWD ? "INIT_CWD" : "PWD"}, not a git repo)`);
             }
             else {
                 console.error(`[token-pilot] project root: ${projectRoot} (cwd, not a git repo)`);
@@ -120,99 +256,222 @@ export async function startServer(cliArgs = process.argv.slice(2)) {
     // Non-blocking update check for all components (logs to stderr, never blocks startup)
     const config = await loadConfig(projectRoot);
     const binaryStatus = await findBinary(config.astIndex.binaryPath);
-    checkAllUpdates(config, binaryStatus).catch(() => { });
+    checkAllUpdates(config, binaryStatus).catch(() => {
+        /* ignore */
+    });
+    // Phase 5 subtask 5.6 — one-time reminder when no tp-* agents installed.
+    // Non-blocking, silent on error, single-fire per process.
+    maybeEmitStartupReminder({
+        projectRoot,
+        homeDir: homedir(),
+        configSuppressed: config.agents?.reminder === false,
+    }).catch(() => {
+        /* ignore */
+    });
+    // Phase 6 subtask 6.2 — age + size retention on hook-events archives.
+    // Fire-and-forget: retention failures must never block startup.
+    applyRetention(projectRoot).catch(() => {
+        /* ignore */
+    });
     // Auto-install PreToolUse hook (non-blocking, Claude Code only)
-    installHook(projectRoot).then(result => {
+    // Uses absolute paths to node + script so hooks work in /bin/sh (nvm, npx, etc.)
+    let hookOptions;
+    try {
+        const rawPath = fileURLToPath(new URL("./index.js", import.meta.url));
+        hookOptions = {
+            scriptPath: realpathSync(rawPath),
+            nodeExecPath: process.execPath,
+        };
+    }
+    catch {
+        // Can't resolve script path (e.g. running from src/ in tests) — fall back to bare command
+    }
+    installHook(projectRoot, hookOptions)
+        .then((result) => {
         if (result.installed) {
             console.error(`[token-pilot] hook auto-installed: ${result.message}`);
         }
-    }).catch(() => { });
+    })
+        .catch(() => {
+        /* ignore — not Claude Code or no .claude dir */
+    });
     const server = await createServer(projectRoot, {
         skipAstIndex: isDangerousRoot(projectRoot),
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    process.on('SIGINT', async () => {
+    process.on("SIGINT", async () => {
         await server.close();
         process.exit(0);
     });
-    process.on('SIGTERM', async () => {
+    process.on("SIGTERM", async () => {
         await server.close();
         process.exit(0);
     });
 }
-export function handleHookRead(filePathArg, denyThreshold = 300) {
-    // Parse stdin (Claude Code hook format) to get tool_input
+export async function handleHookRead(filePathArg, mode = "deny-enhanced", denyThreshold = 300, projectRoot = process.cwd(), adaptive = {}) {
+    // Mode 'off' — hook is inert regardless of input.
+    if (mode === "off") {
+        process.exit(0);
+    }
+    const dispatchResult = await runHookReadDispatch(filePathArg, mode, denyThreshold, projectRoot, adaptive);
+    if (dispatchResult) {
+        process.stdout.write(dispatchResult);
+    }
+    process.exit(0);
+}
+/**
+ * Pure implementation of the hook-read dispatch — returns the JSON payload
+ * to write to stdout, or null when we should pass-through (no output).
+ * Extracted for testability; the outer handleHookRead adds the process.exit
+ * wrapping.
+ */
+export async function runHookReadDispatch(filePathArg, mode, denyThresholdArg, projectRootArg, adaptive = {}) {
+    const denyThreshold = denyThresholdArg ?? 300;
+    const projectRoot = projectRootArg ?? process.cwd();
+    return runHookReadDispatchImpl(filePathArg, mode, denyThreshold, projectRoot, adaptive);
+}
+async function runHookReadDispatchImpl(filePathArg, mode, denyThreshold, projectRoot, adaptive = {}) {
+    if (mode === "off")
+        return null;
+    // Parse stdin to get tool_input + session/agent metadata, unless a
+    // filePath was supplied directly (tests, --filePath invocation).
     let filePath = filePathArg;
     let hasOffset = false;
     let hasLimit = false;
+    let sessionId = "";
+    let agentType = null;
+    let agentId = null;
     if (!filePath) {
         try {
-            const stdin = readFileSync(0, 'utf-8');
+            const stdin = readFileSync(0, "utf-8");
             const input = JSON.parse(stdin);
             filePath = input?.tool_input?.file_path;
             hasOffset = input?.tool_input?.offset != null;
             hasLimit = input?.tool_input?.limit != null;
+            sessionId = typeof input?.session_id === "string" ? input.session_id : "";
+            agentType =
+                typeof input?.agent_type === "string" ? input.agent_type : null;
+            agentId = typeof input?.agent_id === "string" ? input.agent_id : null;
         }
         catch {
-            process.exit(0);
+            return null;
         }
     }
-    if (!filePath) {
-        process.exit(0);
-    }
-    const ext = filePath.split('.').pop()?.toLowerCase() ?? '';
-    // Non-code files — allow Read without interference
-    if (!CODE_EXTENSIONS.has(ext)) {
-        process.exit(0);
-    }
-    // Bounded Read (has offset or limit) — allow, AI is reading a specific section
-    if (hasOffset || hasLimit) {
-        process.exit(0);
+    if (!filePath)
+        return null;
+    const ext = filePath.split(".").pop()?.toLowerCase() ?? "";
+    if (!CODE_EXTENSIONS.has(ext))
+        return null;
+    // Bounded Reads are always passed through — the agent already narrowed scope.
+    if (hasOffset || hasLimit)
+        return null;
+    // Path safety: refuse to summarise any file outside the project root
+    // (traversal, symlinks pointing outside). Pass-through on failure so the
+    // agent is never blocked by a safety reject.
+    if (!isPathWithinProject(filePath, projectRoot)) {
+        try {
+            process.stderr.write(`[token-pilot] refusing to summarise "${filePath}" — outside project root. Hook passing through.\n`);
+        }
+        catch {
+            /* silent — hook must not break */
+        }
+        return null;
     }
-    // Check file size
+    // Resolve effective threshold once (cheap if adaptive is off).
+    const effectiveThreshold = adaptive.adaptiveThreshold
+        ? computeEffectiveThreshold({
+            baseThreshold: denyThreshold,
+            sessionSavedTokens: loadSessionSavedTokens(projectRoot, sessionId),
+            sessionBudgetTokens: adaptive.adaptiveBudgetTokens ?? 100_000,
+            enabled: true,
+        })
+        : denyThreshold;
+    // Read file content + line count.
+    let fileContent = "";
     let lineCount = 0;
-    let fileContent = '';
     try {
-        fileContent = readFileSync(filePath, 'utf-8');
-        lineCount = fileContent.split('\n').length;
-        if (lineCount <= denyThreshold) {
-            process.exit(0);
-        }
+        fileContent = readFileSync(filePath, "utf-8");
+        lineCount = fileContent.split("\n").length;
+        if (lineCount <= effectiveThreshold)
+            return null;
     }
     catch {
-        process.exit(0);
+        return null;
     }
-    // Track denied read for session analytics
+    const charEst = Math.ceil(fileContent.length / 4);
+    const wsRatio = (fileContent.match(/\s/g)?.length ?? 0) / fileContent.length;
+    const estTokens = Math.ceil(charEst * (1 - wsRatio * 0.3));
+    // Legacy telemetry (hook-denied.jsonl) — retained for backward compatibility
+    // with existing loadDeniedReads() readers in session-analytics. Never block
+    // hook dispatch on failure.
     try {
-        const charEst = Math.ceil(fileContent.length / 4);
-        const wsRatio = (fileContent.match(/\s/g)?.length ?? 0) / fileContent.length;
-        const estTokens = Math.ceil(charEst * (1 - wsRatio * 0.3));
-        const entry = JSON.stringify({ filePath, lineCount, estimatedTokens: estTokens, timestamp: Date.now() });
-        const dir = join(process.cwd(), '.token-pilot');
+        const entry = JSON.stringify({
+            filePath,
+            lineCount,
+            estimatedTokens: estTokens,
+            mode,
+            timestamp: Date.now(),
+        });
+        const dir = join(projectRoot, ".token-pilot");
         mkdirSync(dir, { recursive: true });
-        appendFileSync(join(dir, 'hook-denied.jsonl'), entry + '\n');
+        appendFileSync(join(dir, "hook-denied.jsonl"), entry + "\n");
     }
     catch {
-        // Silent fail — hook must not break
+        /* silent — hook must not break */
+    }
+    const writeEvent = async (eventKind, summaryTokens) => {
+        await appendEvent(projectRoot, {
+            ts: Date.now(),
+            session_id: sessionId,
+            agent_type: agentType,
+            agent_id: agentId,
+            event: eventKind,
+            file: filePath,
+            lines: lineCount,
+            estTokens,
+            summaryTokens,
+            savedTokens: Math.max(0, estTokens - summaryTokens),
+        });
+    };
+    if (mode === "advisory") {
+        const reason = `File "${filePath}" has ${lineCount} lines. Use mcp__token-pilot__smart_read("${filePath}") ` +
+            `for a structural overview, or mcp__token-pilot__read_for_edit("${filePath}", symbol="<name>") ` +
+            `for edit context. Bounded Read with offset/limit is still allowed.`;
+        await writeEvent("denied", Math.ceil(reason.length / 4));
+        return JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "deny",
+                permissionDecisionReason: reason,
+            },
+        });
+    }
+    // mode === 'deny-enhanced'
+    const pipelineResult = await runSummaryPipeline(fileContent, filePath);
+    if (pipelineResult.kind === "pass-through") {
+        await writeEvent("pass-through", 0);
+        return null;
     }
-    // Large code file, unbounded Read → DENY
-    // permissionDecisionReason is shown to Claude (not user) per official docs
-    const deny = JSON.stringify({
+    const message = formatDenyMessage({
+        filePath,
+        summary: pipelineResult.summary,
+        tier: pipelineResult.tier,
+    });
+    await writeEvent("denied", Math.ceil(message.length / 4));
+    return JSON.stringify({
         hookSpecificOutput: {
             hookEventName: "PreToolUse",
             permissionDecision: "deny",
-            permissionDecisionReason: `File "${filePath}" has ${lineCount} lines. Use smart_read("${filePath}") for structural overview, or read_for_edit("${filePath}", symbol="<name>") for edit context. Bounded Read with offset/limit is still allowed.`,
+            permissionDecisionReason: message,
         },
     });
-    process.stdout.write(deny);
-    process.exit(0);
 }
 export function handleHookEdit() {
     // Parse stdin for Edit tool_input
     let filePath;
     try {
-        const stdin = readFileSync(0, 'utf-8');
+        const stdin = readFileSync(0, "utf-8");
         const input = JSON.parse(stdin);
         filePath = input?.tool_input?.file_path;
     }
@@ -222,7 +481,7 @@ export function handleHookEdit() {
     if (!filePath) {
         process.exit(0);
     }
-    const ext = filePath.split('.').pop()?.toLowerCase() ?? '';
+    const ext = filePath.split(".").pop()?.toLowerCase() ?? "";
     // Only add context for code files
     if (!CODE_EXTENSIONS.has(ext)) {
         process.exit(0);
@@ -239,7 +498,18 @@ export function handleHookEdit() {
     process.exit(0);
 }
 export async function handleInstallHook(projectRoot) {
-    const result = await installHook(projectRoot);
+    let hookOptions;
+    try {
+        const rawPath = fileURLToPath(new URL("./index.js", import.meta.url));
+        hookOptions = {
+            scriptPath: realpathSync(rawPath),
+            nodeExecPath: process.execPath,
+        };
+    }
+    catch {
+        // Fall back to bare command
+    }
+    const result = await installHook(projectRoot, hookOptions);
     console.log(result.message);
     process.exit(result.fatal ? 1 : 0);
 }
@@ -273,23 +543,23 @@ export async function handleInstallAstIndex() {
 }
 export async function handleDoctor() {
     const version = getVersion();
-    const { existsSync } = await import('node:fs');
-    const { join } = await import('node:path');
+    const { existsSync } = await import("node:fs");
+    const { join } = await import("node:path");
     const cwd = process.cwd();
     console.log(`token-pilot doctor v${version}\n`);
     // ── Environment ──
     const nodeVersion = process.version;
     const nodeMajor = parseInt(nodeVersion.slice(1), 10);
-    console.log(`Node.js:        ${nodeVersion} ${nodeMajor >= 18 ? '✓' : '✗ (requires >=18)'}`);
-    const configPath = join(cwd, '.token-pilot.json');
-    console.log(`config:         ${existsSync(configPath) ? configPath + ' ✓' : 'default (no .token-pilot.json)'}`);
-    const gitDir = join(cwd, '.git');
-    console.log(`git repo:       ${existsSync(gitDir) ? 'yes ✓' : 'no (read_diff/git features unavailable)'}`);
-    console.log('');
+    console.log(`Node.js:        ${nodeVersion} ${nodeMajor >= 18 ? "✓" : "✗ (requires >=18)"}`);
+    const configPath = join(cwd, ".token-pilot.json");
+    console.log(`config:         ${existsSync(configPath) ? configPath + " ✓" : "default (no .token-pilot.json)"}`);
+    const gitDir = join(cwd, ".git");
+    console.log(`git repo:       ${existsSync(gitDir) ? "yes ✓" : "no (read_diff/git features unavailable)"}`);
+    console.log("");
     // ── token-pilot ──
-    console.log('── token-pilot ──');
+    console.log("── token-pilot ──");
     console.log(`  installed:    ${version}`);
-    const tpLatest = await checkNpmLatest('token-pilot');
+    const tpLatest = await checkNpmLatest("token-pilot");
     if (tpLatest) {
         if (isNewerVersion(version, tpLatest)) {
             console.log(`  latest:       ${tpLatest} (update available!)`);
@@ -302,9 +572,9 @@ export async function handleDoctor() {
     else {
         console.log(`  latest:       could not check (network error)`);
     }
-    console.log('');
+    console.log("");
     // ── ast-index ──
-    console.log('── ast-index ──');
+    console.log("── ast-index ──");
     const astStatus = await findBinary();
     if (astStatus.available) {
         console.log(`  installed:    ${astStatus.version} (${astStatus.source}: ${astStatus.path})`);
@@ -317,45 +587,99 @@ export async function handleDoctor() {
             console.log(`  latest:       ${astUpdate.latest} ✓ (up to date)`);
         }
         const config = await loadConfig(cwd);
-        console.log(`  auto-update:  ${config.updates.autoUpdate ? 'enabled ✓' : 'disabled (set updates.autoUpdate=true in .token-pilot.json)'}`);
+        console.log(`  auto-update:  ${config.updates.autoUpdate ? "enabled ✓" : "disabled (set updates.autoUpdate=true in .token-pilot.json)"}`);
     }
     else {
         console.log(`  installed:    not found ✗`);
         console.log(`  run:          npx token-pilot install-ast-index`);
     }
-    console.log('');
+    console.log("");
     // ── context-mode ──
-    console.log('── context-mode ──');
-    const { detectContextMode } = await import('./integration/context-mode-detector.js');
+    console.log("── context-mode ──");
+    const { detectContextMode } = await import("./integration/context-mode-detector.js");
     const cmStatus = await detectContextMode(cwd);
-    console.log(`  detected:     ${cmStatus.detected ? `yes (${cmStatus.source})` : 'no'}`);
-    const cmLatest = await checkNpmLatest('claude-context-mode');
+    console.log(`  detected:     ${cmStatus.detected ? `yes (${cmStatus.source})` : "no"}`);
+    const cmLatest = await checkNpmLatest("claude-context-mode");
     if (cmLatest) {
         console.log(`  latest npm:   ${cmLatest}`);
     }
     if (!cmStatus.detected) {
         console.log(`  setup:        npx token-pilot init`);
     }
-    console.log('');
+    console.log("");
+    // ── blessed agents drift check ──
+    const drift = await detectDrift({ projectRoot: cwd, homeDir: homedir() });
+    if (drift.length > 0) {
+        console.log("── blessed-agents drift ──");
+        for (const finding of drift) {
+            console.log(`  ${formatDriftFinding(finding)}`);
+        }
+        console.log("");
+    }
+    // ── Claude Code env-var savings tips ──
+    try {
+        const tips = await runClaudeCodeEnvCheck();
+        if (tips.length > 0) {
+            console.log("── Claude Code env knobs (savings tips) ──");
+            for (const t of tips) {
+                console.log(`  ⚠ ${t}`);
+            }
+            console.log("");
+        }
+    }
+    catch {
+        /* doctor must never crash over an optional check */
+    }
+    // ── .claudeignore ──
+    try {
+        const status = await claudeIgnoreStatus(cwd);
+        console.log("── .claudeignore ──");
+        if (status.kind === "absent") {
+            console.log(`  not present — run \`npx token-pilot init\` to add sensible defaults`);
+        }
+        else if (status.kind === "managed") {
+            console.log(`  present ✓ (managed by token-pilot; safe to edit)`);
+        }
+        else {
+            console.log(`  present ✓ (user-owned; token-pilot will not touch it)`);
+        }
+        console.log("");
+    }
+    catch {
+        /* ignore */
+    }
+    // ── CLAUDE.md hygiene ──
+    try {
+        const r = await assessClaudeMd(cwd);
+        if (r.kind === "bloated") {
+            console.log("── CLAUDE.md hygiene ──");
+            console.log(`  ⚠ ${r.path} has ${r.nonEmptyLines} non-empty lines (threshold: ${r.threshold}).`);
+            console.log(`  This file loads into every Claude Code message — splitting into docs/*.md and loading on-demand saves tokens per turn.`);
+            console.log("");
+        }
+    }
+    catch {
+        /* ignore */
+    }
     process.exit(0);
 }
 export async function handleInit(targetDir) {
-    const { existsSync, readFileSync: readFs, writeFileSync } = await import('node:fs');
-    const { join } = await import('node:path');
-    const mcpPath = join(targetDir, '.mcp.json');
+    const { existsSync, readFileSync: readFs, writeFileSync, } = await import("node:fs");
+    const { join } = await import("node:path");
+    const mcpPath = join(targetDir, ".mcp.json");
     const tokenPilotConfig = {
-        command: 'npx',
-        args: ['-y', 'token-pilot'],
+        command: "npx",
+        args: ["-y", "token-pilot"],
     };
     const contextModeConfig = {
-        command: 'npx',
-        args: ['-y', 'claude-context-mode'],
+        command: "npx",
+        args: ["-y", "claude-context-mode"],
     };
     let config = { mcpServers: {} };
     let existed = false;
     if (existsSync(mcpPath)) {
         try {
-            config = JSON.parse(readFs(mcpPath, 'utf-8'));
+            config = JSON.parse(readFs(mcpPath, "utf-8"));
             if (!config.mcpServers)
                 config.mcpServers = {};
             existed = true;
@@ -366,28 +690,71 @@ export async function handleInit(targetDir) {
         }
     }
     const added = [];
-    if (!config.mcpServers['token-pilot']) {
-        config.mcpServers['token-pilot'] = tokenPilotConfig;
-        added.push('token-pilot');
+    if (!config.mcpServers["token-pilot"]) {
+        config.mcpServers["token-pilot"] = tokenPilotConfig;
+        added.push("token-pilot");
     }
-    if (!config.mcpServers['context-mode']) {
-        config.mcpServers['context-mode'] = contextModeConfig;
-        added.push('context-mode');
+    if (!config.mcpServers["context-mode"]) {
+        config.mcpServers["context-mode"] = contextModeConfig;
+        added.push("context-mode");
     }
     if (added.length === 0) {
         console.log(`✓ ${mcpPath} already has both token-pilot and context-mode configured`);
         process.exit(0);
     }
-    writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n');
+    writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
     if (existed) {
-        console.log(`✓ Updated ${mcpPath} — added: ${added.join(', ')}`);
+        console.log(`✓ Updated ${mcpPath} — added: ${added.join(", ")}`);
     }
     else {
         console.log(`✓ Created ${mcpPath} with token-pilot + context-mode`);
     }
     console.log(`\nConfigured MCP servers:`);
-    console.log(`  • token-pilot   — AST-aware code reading (60-80% token savings)`);
+    console.log(`  • token-pilot   — enforcement layer for token-efficient reads (hook + MCP + tp-* subagents)`);
     console.log(`  • context-mode  — shell output & large data processing (BM25 sandbox)`);
+    // Claude Code users benefit from six token-pilot-native subagents (tp-run,
+    // tp-onboard, …). Offer installation now so they don't have to discover
+    // `install-agents` from a stderr reminder later.
+    const offeredAgents = added.includes("token-pilot") && process.stdin.isTTY === true;
+    if (offeredAgents) {
+        console.log("");
+        const yes = await promptYesNo("Install 6 tp-* subagents now (recommended for Claude Code)?", true);
+        if (yes) {
+            // Delegate to the full install-agents flow: it will prompt scope,
+            // handle idempotence, and persist the choice to .token-pilot.json.
+            const code = await handleInstallAgents([], { projectRoot: targetDir });
+            if (code !== 0) {
+                console.log("\n(install-agents returned non-zero; you can retry with: npx token-pilot install-agents)");
+            }
+        }
+        else {
+            console.log("\nSkipping agent install. Run later: npx token-pilot install-agents");
+        }
+    }
+    else if (added.includes("token-pilot")) {
+        // Non-TTY path — at minimum surface the next step in the log.
+        console.log(`\nNext step (Claude Code): npx token-pilot install-agents --scope=user|project`);
+    }
+    // Offer `.claudeignore` — small one-time win that compounds per message.
+    // Separate TTY check so a script that declined agents can still get ignore,
+    // and vice versa.
+    const ignoreStatus = await claudeIgnoreStatus(targetDir);
+    if (offeredAgents && ignoreStatus.kind !== "user-owned") {
+        console.log("");
+        const yesIgnore = await promptYesNo(ignoreStatus.kind === "absent"
+            ? "Create .claudeignore with sensible defaults (node_modules, dist, lockfiles, …)?"
+            : "Refresh .claudeignore defaults (managed by token-pilot)?", true);
+        if (yesIgnore) {
+            const wrote = await writeDefaultClaudeIgnore(targetDir);
+            if (wrote)
+                console.log("✓ .claudeignore written");
+            else
+                console.log("(Skipped — existing .claudeignore is user-owned; not touched.)");
+        }
+    }
+    else if (ignoreStatus.kind === "absent") {
+        console.log(`\nTip: \`npx token-pilot init\` offers to create .claudeignore — improves context by skipping node_modules, build artefacts, lockfiles.`);
+    }
     console.log(`\nRestart your AI assistant to activate.`);
     process.exit(0);
 }
@@ -404,7 +771,7 @@ export async function checkNpmLatest(packageName) {
         clearTimeout(timeout);
         if (!resp.ok)
             return null;
-        const data = await resp.json();
+        const data = (await resp.json());
         return data.version ?? null;
     }
     catch {
@@ -415,28 +782,32 @@ export async function checkAllUpdates(config, binaryStatus) {
     if (!config.updates.checkOnStartup)
         return;
     const [tpLatest, astUpdate, cmLatest] = await Promise.allSettled([
-        checkNpmLatest('token-pilot'),
-        binaryStatus.available ? checkBinaryUpdate(binaryStatus.path) : Promise.resolve(null),
-        checkNpmLatest('claude-context-mode'),
+        checkNpmLatest("token-pilot"),
+        binaryStatus.available
+            ? checkBinaryUpdate(binaryStatus.path)
+            : Promise.resolve(null),
+        checkNpmLatest("claude-context-mode"),
     ]);
     // token-pilot
     const tpVersion = getVersion();
-    if (tpLatest.status === 'fulfilled' && tpLatest.value && isNewerVersion(tpVersion, tpLatest.value)) {
+    if (tpLatest.status === "fulfilled" &&
+        tpLatest.value &&
+        isNewerVersion(tpVersion, tpLatest.value)) {
         console.error(`[token-pilot] Update available: ${tpVersion} → ${tpLatest.value}. Run: npx token-pilot@latest`);
     }
     // ast-index
-    if (astUpdate.status === 'fulfilled' && astUpdate.value?.updateAvailable) {
+    if (astUpdate.status === "fulfilled" && astUpdate.value?.updateAvailable) {
         const { current, latest } = astUpdate.value;
         if (config.updates.autoUpdate) {
             console.error(`[token-pilot] Auto-updating ast-index: ${current} → ${latest}...`);
-            installBinary(msg => console.error(`[token-pilot] ${msg}`)).catch(() => { });
+            installBinary((msg) => console.error(`[token-pilot] ${msg}`)).catch(() => { });
         }
         else {
             console.error(`[token-pilot] ast-index update: ${current} → ${latest}. Run: token-pilot install-ast-index`);
         }
     }
     // context-mode (notification only — runs as separate MCP server)
-    if (cmLatest.status === 'fulfilled' && cmLatest.value) {
+    if (cmLatest.status === "fulfilled" && cmLatest.value) {
         // We can't reliably detect the currently installed version of context-mode
         // (it runs as separate process via npx). Just log latest available for doctor.
         // On startup, we only notify if explicitly useful.
@@ -452,22 +823,28 @@ Usage:
   token-pilot uninstall-hook [root] Remove PreToolUse hook
   token-pilot install-ast-index     Download ast-index binary (auto on first run)
   token-pilot doctor                Run diagnostics (check ast-index, config, updates)
+  token-pilot save-doc <name>       Save stdin to .token-pilot/docs/<name>.md
+  token-pilot list-docs             List saved docs
   token-pilot --version             Show version
   token-pilot --help                Show this help
 
 Quick start:
   npx token-pilot init              Setup .mcp.json (token-pilot + context-mode)
 
-MCP Tools (18):
-  smart_read, read_symbol, read_range, read_diff, read_for_edit, smart_read_many,
-  find_usages, find_unused, related_files, outline, project_overview, session_analytics,
-  code_audit, module_info, smart_diff, explore_area, smart_log, test_summary
+MCP Tools (22):
+  smart_read, read_symbol, read_symbols, read_range, read_section, read_diff,
+  read_for_edit, smart_read_many, find_usages, find_unused, related_files,
+  outline, project_overview, session_analytics, code_audit, module_info,
+  smart_diff, explore_area, smart_log, test_summary, session_snapshot,
+  session_budget
 `);
     process.exit(0);
 }
-const isDirectRun = process.argv[1] !== undefined && realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+const isDirectRun = process.argv[1] !== undefined &&
+    realpathSync(fileURLToPath(import.meta.url)) ===
+        realpathSync(process.argv[1]);
 if (isDirectRun) {
-    main().catch(err => {
+    main().catch((err) => {
         console.error(`[token-pilot] Fatal: ${err instanceof Error ? err.message : err}`);
         process.exit(1);
     });