token-pilot 0.19.0 → 0.19.2

package/README.md

@@ -215,7 +215,7 @@ For more control, you can add rules to your project:
 
 | Tool | Description |
 |------|-------------|
-| `session_snapshot` | Capture session state as a compact markdown block (<200 tokens): goal, confirmed facts, relevant files, blockers, next step. Call before compaction or when switching direction. |
+| `session_snapshot` | Capture session state as a compact markdown block (<200 tokens): goal, decisions (with reasoning), confirmed facts, relevant files, blockers, next step. Decisions field prevents revisiting rejected approaches after compaction. |
 | `session_analytics` | Token savings report: total saved, per-tool breakdown, top files, per-intent breakdown, decision insights, policy advisories. |
 
 ## CLI Commands

package/dist/ast-index/binary-manager.d.ts

@@ -2,14 +2,14 @@ export interface BinaryStatus {
     available: boolean;
     path: string;
     version: string | null;
-    source: 'system' | 'managed' | 'none';
+    source: 'system' | 'npm' | 'managed' | 'none';
 }
 /**
- * Find ast-index binary: check system PATH first, then managed install.
+ * Find ast-index binary: config → system PATH → npm global → managed install.
  */
 export declare function findBinary(configPath?: string | null): Promise<BinaryStatus>;
 /**
- * Download and install ast-index binary from GitHub releases.
+ * Install ast-index: tries npm global first (all platforms), falls back to GitHub download.
  */
 export declare function installBinary(onProgress?: (msg: string) => void): Promise<BinaryStatus>;
 /**

package/dist/ast-index/binary-manager.js

@@ -12,7 +12,7 @@ const REPO = 'defendend/Claude-ast-index-search';
 const BINARY_NAME = platform() === 'win32' ? 'ast-index.exe' : 'ast-index';
 const INSTALL_DIR = resolve(homedir(), '.token-pilot', 'bin');
 /**
- * Find ast-index binary: check system PATH first, then managed install.
+ * Find ast-index binary: config → system PATH → npm global → managed install.
  */
 export async function findBinary(configPath) {
     // 1. Config override
@@ -28,7 +28,15 @@ export async function findBinary(configPath) {
         const version = await getBinaryVersion(systemPath);
         return { available: true, path: systemPath, version, source: 'system' };
     }
-    // 3. Managed install
+    // 3. npm global install (@ast-index/cli)
+    const npmPath = await findViaNpmBin();
+    if (npmPath) {
+        const version = await getBinaryVersion(npmPath);
+        if (version) {
+            return { available: true, path: npmPath, version, source: 'npm' };
+        }
+    }
+    // 4. Managed install (GitHub download)
     const managedPath = resolve(INSTALL_DIR, BINARY_NAME);
     const version = await getBinaryVersion(managedPath);
     if (version) {
@@ -37,24 +45,53 @@ export async function findBinary(configPath) {
     return { available: false, path: '', version: null, source: 'none' };
 }
 /**
- * Download and install ast-index binary from GitHub releases.
+ * Install ast-index: tries npm global first (all platforms), falls back to GitHub download.
  */
 export async function installBinary(onProgress) {
     const log = onProgress ?? (() => { });
+    // Try npm first — simpler, handles all platforms including Windows
+    try {
+        return await installViaNpm(log);
+    }
+    catch (npmErr) {
+        log(`npm install failed (${npmErr instanceof Error ? npmErr.message : npmErr}), trying GitHub download...`);
+    }
+    // GitHub download fallback
+    return installViaNpmFallback(log);
+}
+async function installViaNpm(onProgress) {
+    onProgress('Installing @ast-index/cli via npm...');
+    await new Promise((resolve, reject) => {
+        execFile('npm', ['install', '-g', '@ast-index/cli'], { timeout: 120_000 }, (err, _stdout, stderr) => {
+            if (err)
+                reject(new Error(stderr.trim() || err.message));
+            else
+                resolve();
+        });
+    });
+    const binPath = await findViaNpmBin();
+    if (!binPath) {
+        throw new Error('@ast-index/cli installed but binary not found in npm prefix');
+    }
+    const version = await getBinaryVersion(binPath);
+    onProgress(`Installed ast-index ${version} via npm at ${binPath}`);
+    return { available: true, path: binPath, version, source: 'npm' };
+}
+async function installViaNpmFallback(onProgress) {
     // Determine platform/arch
     const plat = getPlatform();
     const ar = getArch();
     if (!plat || !ar) {
         throw new Error(`Unsupported platform: ${platform()} ${arch()}`);
     }
-    log('Fetching latest release info...');
+    onProgress('Fetching latest release info...');
     const release = await fetchLatestRelease();
     const assetName = buildAssetName(release.tag, plat, ar);
     const asset = release.assets.find(a => a.name === assetName);
     if (!asset) {
         throw new Error(`No binary found for ${plat}-${ar}. Available: ${release.assets.map(a => a.name).join(', ')}`);
     }
-    log(`Downloading ${asset.name} (${(asset.size / 1024 / 1024).toFixed(1)}MB)...`);
+    onProgress(`Downloading ${asset.name} (${(asset.size / 1024 / 1024).toFixed(1)}MB)...`);
     await mkdir(INSTALL_DIR, { recursive: true });
     const tmpPath = resolve(INSTALL_DIR, `${BINARY_NAME}.tmp`);
     const finalPath = resolve(INSTALL_DIR, BINARY_NAME);
@@ -62,19 +99,16 @@ export async function installBinary(onProgress) {
         if (assetName.endsWith('.tar.gz')) {
             await downloadAndExtractTarGz(asset.url, INSTALL_DIR, BINARY_NAME);
         }
-        else if (assetName.endsWith('.zip')) {
-            // For Windows, download zip and extract
+        else {
             await downloadFile(asset.url, tmpPath);
-            // Simple approach: use system unzip if available
-            throw new Error('ZIP extraction not yet supported. Please install ast-index manually on Windows.');
+            throw new Error('ZIP extraction not yet supported. Please use: npm install -g @ast-index/cli');
         }
         await chmod(finalPath, 0o755);
         const version = await getBinaryVersion(finalPath);
-        log(`Installed ast-index ${version} to ${finalPath}`);
+        onProgress(`Installed ast-index ${version} to ${finalPath}`);
         return { available: true, path: finalPath, version, source: 'managed' };
     }
     catch (err) {
-        // Cleanup on failure
         try {
             await rm(tmpPath, { force: true });
         }
@@ -130,6 +164,35 @@ export function isNewerVersion(current, latest) {
     return false;
 }
 // --- Internal helpers ---
+/**
+ * Find ast-index binary installed via `npm install -g @ast-index/cli`.
+ * Checks the npm global prefix bin directory.
+ */
+async function findViaNpmBin() {
+    try {
+        const prefix = await new Promise((resolve, reject) => {
+            execFile('npm', ['config', 'get', 'prefix'], { timeout: 3000 }, (err, stdout) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(stdout.trim());
+            });
+        });
+        // Unix: <prefix>/bin/ast-index  |  Windows: <prefix>\ast-index.exe or <prefix>\bin\ast-index.exe
+        const candidates = platform() === 'win32'
+            ? [resolve(prefix, BINARY_NAME), resolve(prefix, 'bin', BINARY_NAME)]
+            : [resolve(prefix, 'bin', BINARY_NAME)];
+        for (const candidate of candidates) {
+            try {
+                await access(candidate);
+                return candidate;
+            }
+            catch { }
+        }
+    }
+    catch { }
+    return null;
+}
 function getPlatform() {
     switch (platform()) {
         case 'darwin': return 'darwin';

package/dist/ast-index/client.d.ts

@@ -27,12 +27,16 @@ export declare class AstIndexClient {
     symbol(name: string): Promise<AstIndexSymbolDetail | null>;
     search(query: string, options?: {
         inFile?: string;
+        type?: string;
         maxResults?: number;
         fuzzy?: boolean;
     }): Promise<AstIndexSearchResult[]>;
     usages(symbolName: string): Promise<AstIndexUsageResult[]>;
     implementations(name: string): Promise<AstIndexImplementation[]>;
-    hierarchy(name: string): Promise<AstIndexHierarchyNode | null>;
+    hierarchy(name: string, options?: {
+        inFile?: string;
+        module?: string;
+    }): Promise<AstIndexHierarchyNode | null>;
     stats(): Promise<string | null>;
     listFiles(): Promise<string[]>;
     refs(symbolName: string, limit?: number): Promise<AstIndexRefsResponse>;

package/dist/ast-index/client.js

@@ -223,6 +223,8 @@ export class AstIndexClient {
         const args = ['search', query, '--format', 'json'];
         if (options?.inFile)
             args.push('--in-file', options.inFile);
+        if (options?.type)
+            args.push('--type', options.type);
         if (options?.maxResults)
             args.push('--limit', String(options.maxResults));
         if (options?.fuzzy)
@@ -295,10 +297,15 @@ export class AstIndexClient {
             return [];
         }
     }
-    async hierarchy(name) {
+    async hierarchy(name, options) {
         await this.ensureIndex();
         try {
-            const result = await this.exec(['hierarchy', name, '--format', 'json']);
+            const args = ['hierarchy', name, '--format', 'json'];
+            if (options?.inFile)
+                args.push('--in-file', options.inFile);
+            if (options?.module)
+                args.push('--module', options.module);
+            const result = await this.exec(args);
             try {
                 return JSON.parse(result);
             }

package/dist/handlers/session-snapshot.d.ts

@@ -1,5 +1,6 @@
 export interface SessionSnapshotArgs {
     goal: string;
+    decisions?: string[];
     confirmed?: string[];
     files?: string[];
     blocked?: string;

package/dist/handlers/session-snapshot.js

@@ -1,6 +1,12 @@
 export function handleSessionSnapshot(args) {
     const lines = ['## Session State'];
     lines.push(`**Goal:** ${args.goal}`);
+    if (args.decisions?.length) {
+        lines.push('**Decisions:**');
+        for (const item of args.decisions) {
+            lines.push(`- ${item}`);
+        }
+    }
     if (args.confirmed?.length) {
         lines.push('**Confirmed:**');
         for (const item of args.confirmed) {

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,35 +1,55 @@
 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",
-                    },
-                ],
-            },
-        ],
-    },
-};
+/**
+ * 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),
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+}
 /**
  * Install Token Pilot hook into Claude Code settings.
  * Creates or updates .claude/settings.json with PreToolUse hook.
  */
-export async function installHook(projectRoot) {
+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 });
@@ -63,16 +83,26 @@ export async function installHook(projectRoot) {
         const existingHooks = settings.hooks?.PreToolUse;
         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/) // bare command without path
+            ));
+            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.' };
+                }
             }
             // Add missing hooks
-            for (const hookDef of HOOK_CONFIG.hooks.PreToolUse) {
-                const exists = existingHooks.some((h) => h.matcher === hookDef.matcher && isTokenPilotHook(h));
+            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,7 +110,7 @@ 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;
         }
         await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
         return {

package/dist/index.js

@@ -122,7 +122,16 @@ export async function startServer(cliArgs = process.argv.slice(2)) {
     const binaryStatus = await findBinary(config.astIndex.binaryPath);
     checkAllUpdates(config, binaryStatus).catch(() => { });
     // 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}`);
         }
@@ -239,7 +248,15 @@ 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);
 }
@@ -443,25 +460,25 @@ export async function checkAllUpdates(config, binaryStatus) {
     }
 }
 export function printHelp() {
-    console.log(`token-pilot v${getVersion()} — MCP server for token-efficient code reading
-
-Usage:
-  token-pilot [project-root]        Start MCP server (default: cwd)
-  token-pilot init [dir]            Create .mcp.json with token-pilot + context-mode
-  token-pilot install-hook [root]   Install PreToolUse hook (Claude Code only)
-  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 --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
+    console.log(`token-pilot v${getVersion()} — MCP server for token-efficient code reading
+
+Usage:
+  token-pilot [project-root]        Start MCP server (default: cwd)
+  token-pilot init [dir]            Create .mcp.json with token-pilot + context-mode
+  token-pilot install-hook [root]   Install PreToolUse hook (Claude Code only)
+  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 --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
 `);
     process.exit(0);
 }

package/dist/server/tool-definitions.d.ts

@@ -70,6 +70,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -144,6 +145,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -218,6 +220,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -282,6 +285,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -343,6 +347,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -404,6 +409,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -489,6 +495,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -553,6 +560,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -632,6 +640,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -694,6 +703,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -752,6 +762,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -816,6 +827,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -874,6 +886,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -938,6 +951,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -1009,6 +1023,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -1071,6 +1086,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -1136,6 +1152,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -1201,6 +1218,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -1265,6 +1283,7 @@ export declare const TOOL_DEFINITIONS: ({
             runner?: undefined;
             timeout?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -1330,6 +1349,7 @@ export declare const TOOL_DEFINITIONS: ({
             ref?: undefined;
             count?: undefined;
             goal?: undefined;
+            decisions?: undefined;
             confirmed?: undefined;
             files?: undefined;
             blocked?: undefined;
@@ -1347,6 +1367,13 @@ export declare const TOOL_DEFINITIONS: ({
                 type: string;
                 description: string;
             };
+            decisions: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
             confirmed: {
                 type: string;
                 items: {

package/dist/server/tool-definitions.js

@@ -29,7 +29,7 @@ export const MCP_INSTRUCTIONS = [
     '17. Module architecture → module_info (deps, dependents, public API)',
     '18. Read markdown/yaml/json/csv section → read_section (loads one heading/key/row-range, NOT the whole file)',
     '   - For editing sections: read_for_edit(path, section="Section Name")',
-    '19. Long session / before compaction → session_snapshot (capture goal, confirmed facts, files, next step as <200 token block)',
+    '19. Long session / before compaction → session_snapshot (capture goal, decisions, confirmed facts, files, next step as <200 token block)',
     '   - Budget-constrained? Use smart_read(max_tokens=N) to auto-downgrade output size',
     '',
     'USE DEFAULT TOOLS ONLY FOR: regex text search → Grep | exact raw content → Read | non-code configs → Read',
@@ -362,6 +362,7 @@ export const TOOL_DEFINITIONS = [
             type: 'object',
             properties: {
                 goal: { type: 'string', description: 'Session goal — what and why' },
+                decisions: { type: 'array', items: { type: 'string' }, description: 'Key decisions made and why (e.g., "removed sysfee step — caused double counting"). Prevents revisiting rejected approaches.' },
                 confirmed: { type: 'array', items: { type: 'string' }, description: 'Established facts (what has been verified)' },
                 files: { type: 'array', items: { type: 'string' }, description: 'Relevant file paths' },
                 blocked: { type: 'string', description: 'Current blocker or obstacle' },