@within-7/minto 0.1.6 → 0.2.0

package/dist/services/compressionService.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/services/compressionService.ts"],
-  "sourcesContent": ["/**\n * Compression Service - Stateless Context Compression Core\n *\n * This service provides stateless compression functionality that can be used by\n * both the main agent and subagents without side effects. It is the foundation\n * of the layered compression architecture.\n *\n * **Architecture Design:**\n *\n * ```\n * \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n * \u2502              Compression System Architecture             \u2502\n * \u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n * \u2502  Layer 1: MainAgentCompressor                            \u2502\n * \u2502  - Handles /compact command and main agent compression   \u2502\n * \u2502  - Manages global state (messages, cache)                \u2502\n * \u2502  - Recovers recently accessed files                      \u2502\n * \u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n * \u2502  Layer 2: SubagentCompressor                             \u2502\n * \u2502  - Handles subagent automatic compression                \u2502\n * \u2502  - Operates only on local message arrays                 \u2502\n * \u2502  - Zero side effects, no global state modification       \u2502\n * \u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n * \u2502  Layer 3: CompressionService (THIS FILE)                 \u2502\n * \u2502  - Stateless compression algorithm                       \u2502\n * \u2502  - LLM-based summarization                               \u2502\n * \u2502  - Shared by both layers above                           \u2502\n * \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n * ```\n *\n * **Key Principles:**\n * - \u2705 Completely stateless - no global variable access\n * - \u2705 Pure functions - same input always produces same output\n * - \u2705 No side effects - does not modify messages parameter\n * - \u2705 Reusable - shared by main agent and subagent compressors\n *\n * @module CompressionService\n * @see src/services/mainAgentCompressor.ts - Main agent compression layer\n * @see src/services/subagentCompressor.ts - Subagent compression layer\n * @see CONTEXT_COMPRESSION_REFACTORING_GUIDE.md - Architecture documentation\n */\n\nimport { Message } from '@query'\nimport { queryLLM } from '@services/claude'\nimport { createUserMessage, normalizeMessagesForAPI } from '@utils/messages'\nimport { countTokens } from '@utils/tokens'\nimport {\n  getCompressionPrompt,\n  CompressionMode,\n} from '@constants/compressionPrompts'\nimport { getCompressionMode } from '@utils/compressionMode'\n\n/**\n * Configuration options for compression behavior\n */\nexport interface CompressionOptions {\n  /**\n   * Compression mode: determines the structure of the summary\n   * - 'business': Optimized for strategic consulting, research, and management\n   * - 'code': Optimized for software development, debugging, and coding\n   *\n   * If not specified, uses the global compression mode setting\n   */\n  mode?: CompressionMode\n\n  /**\n   * Threshold ratio for triggering compression (0-1)\n   *\n   * Compression triggers when: tokenCount >= contextLength * threshold\n   * Default: 0.92 (92% of context length)\n   *\n   * @example\n   * threshold: 0.92  // Compress at 92% capacity\n   * threshold: 0.80  // Compress earlier at 80% capacity\n   */\n  threshold?: number\n\n  /**\n   * Target model's maximum context length in tokens\n   *\n   * This should match the context length of the model being used\n   * by the agent (main agent or subagent).\n   *\n   * @example\n   * contextLength: 200_000  // Claude Sonnet 3.5\n   * contextLength: 128_000  // GPT-4\n   */\n  contextLength: number\n\n  /**\n   * Whether to recover recently accessed files (main agent only)\n   *\n   * File recovery adds recently accessed files back into the compressed\n   * context to maintain development workflow continuity. This should\n   * only be enabled for the main agent.\n   *\n   * - Main agent: true (preserve coding context)\n   * - Subagent: false (keep lightweight)\n   *\n   * Default: false\n   */\n  recoverFiles?: boolean\n\n  /**\n   * Maximum number of files to recover (if recoverFiles is true)\n   *\n   * Limits the number of files added to prevent context bloat.\n   * Default: 5\n   */\n  maxRecoveredFiles?: number\n}\n\n/**\n * Result of a compression operation\n */\nexport interface CompressionResult {\n  /**\n   * Compressed message array\n   *\n   * If compression was performed:\n   * - Index 0: User message explaining compression occurred\n   * - Index 1: Assistant message containing the summary\n   * - Index 2+: Recovered file messages (if recoverFiles was true)\n   *\n   * If compression was not needed:\n   * - Returns the original messages array unchanged\n   */\n  compressedMessages: Message[]\n\n  /**\n   * Whether compression was actually performed\n   *\n   * false if:\n   * - Token count below threshold\n   * - Message count < 3\n   * - Compression failed (error caught)\n   */\n  wasCompacted: boolean\n\n  /**\n   * The generated summary text (only if wasCompacted is true)\n   *\n   * Contains the LLM-generated conversation summary structured\n   * according to the compression mode (business or code).\n   */\n  summary?: string\n\n  /**\n   * Recovered files data (only if recoverFiles was true and wasCompacted is true)\n   *\n   * Each entry contains:\n   * - path: Absolute file path\n   * - content: File content (possibly truncated)\n   * - tokens: Estimated token count\n   * - truncated: Whether content was truncated due to token limits\n   */\n  recoveredFiles?: Array<{\n    path: string\n    content: string\n    tokens: number\n    truncated: boolean\n  }>\n}\n\n/**\n * Stateless Compression Service\n *\n * Provides pure compression functionality without touching any global state.\n * Used as the foundation for both main agent and subagent compression.\n */\nexport class CompressionService {\n  /**\n   * Determine if compression should be triggered\n   *\n   * Compression is triggered when:\n   * 1. Message count >= 3 (need enough context to summarize)\n   * 2. Token count >= contextLength * threshold\n   *\n   * @param messages - Messages to evaluate for compression\n   * @param options - Compression configuration\n   * @returns true if compression should be triggered\n   *\n   * @example\n   * ```typescript\n   * const shouldCompress = CompressionService.shouldCompress(messages, {\n   *   contextLength: 200_000,\n   *   threshold: 0.92,\n   * })\n   * if (shouldCompress) {\n   *   // Proceed with compression\n   * }\n   * ```\n   */\n  static shouldCompress(\n    messages: Message[],\n    options: CompressionOptions,\n  ): boolean {\n    // Need at least 3 messages to create meaningful summary\n    if (messages.length < 3) {\n      return false\n    }\n\n    const tokenCount = countTokens(messages)\n    const threshold = options.contextLength * (options.threshold ?? 0.92)\n\n    return tokenCount >= threshold\n  }\n\n  /**\n   * Execute context compression\n   *\n   * This method performs the actual compression by:\n   * 1. Checking if compression is needed (via shouldCompress)\n   * 2. Generating a comprehensive summary using LLM\n   * 3. Optionally recovering recently accessed files\n   * 4. Building the compressed message array\n   *\n   * **Important:** This method is completely stateless and has no side effects.\n   * It does NOT:\n   * - Modify the input messages array\n   * - Update any global state (messages, cache, etc.)\n   * - Call any state setters\n   *\n   * State management is the responsibility of the calling layer\n   * (MainAgentCompressor or SubagentCompressor).\n   *\n   * @param messages - Messages to compress\n   * @param tools - Available tools for LLM\n   * @param abortSignal - Abort signal for cancellation\n   * @param options - Compression configuration\n   * @returns Compression result with compressed messages and metadata\n   *\n   * @throws Never throws - errors are caught and returned as wasCompacted: false\n   *\n   * @example\n   * ```typescript\n   * // Subagent compression (no file recovery)\n   * const result = await CompressionService.compress(\n   *   subagentMessages,\n   *   tools,\n   *   abortSignal,\n   *   {\n   *     contextLength: 128_000,\n   *     recoverFiles: false,\n   *   }\n   * )\n   *\n   * if (result.wasCompacted) {\n   *   // Use result.compressedMessages\n   *   subagentMessages = result.compressedMessages\n   * }\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Main agent compression (with file recovery)\n   * const result = await CompressionService.compress(\n   *   mainMessages,\n   *   tools,\n   *   abortSignal,\n   *   {\n   *     contextLength: 200_000,\n   *     recoverFiles: true,\n   *     maxRecoveredFiles: 5,\n   *   }\n   * )\n   *\n   * if (result.wasCompacted) {\n   *   // Main agent layer will handle global state updates\n   *   // (messages, cache clearing, etc.)\n   * }\n   * ```\n   */\n  static async compress(\n    messages: Message[],\n    tools: any[],\n    abortSignal: AbortSignal,\n    options: CompressionOptions,\n  ): Promise<CompressionResult> {\n    // Early return if compression not needed\n    if (!this.shouldCompress(messages, options)) {\n      return {\n        compressedMessages: messages,\n        wasCompacted: false,\n      }\n    }\n\n    try {\n      // Step 1: Generate comprehensive conversation summary using LLM\n      const mode = options.mode ?? getCompressionMode()\n      const compressionPrompt = getCompressionPrompt(mode)\n      const summaryRequest = createUserMessage(compressionPrompt)\n\n      const summaryResponse = await queryLLM(\n        normalizeMessagesForAPI([...messages, summaryRequest]),\n        [\n          'You are a helpful AI assistant tasked with creating comprehensive conversation summaries that preserve all essential context for continuing work.',\n        ],\n        0,\n        tools,\n        abortSignal,\n        {\n          safeMode: false,\n          model: 'main', // Use main model for high-quality summarization\n          prependCLISysprompt: true,\n        },\n      )\n\n      // Step 2: Extract summary text from response\n      const content = summaryResponse.message.content\n      const summary =\n        typeof content === 'string'\n          ? content\n          : content.length > 0 && content[0]?.type === 'text'\n            ? content[0].text\n            : null\n\n      if (!summary) {\n        throw new Error(\n          'Failed to generate conversation summary - response did not contain valid text content',\n        )\n      }\n\n      // Step 3: Reset token usage for summary response\n      // The summary generation itself shouldn't count against the budget\n      // since it's an internal operation, not user-requested work\n      summaryResponse.message.usage = {\n        input_tokens: 0,\n        output_tokens: summaryResponse.message.usage.output_tokens,\n        cache_creation_input_tokens: 0,\n        cache_read_input_tokens: 0,\n      }\n\n      // Step 4: Build compressed messages array\n      const compressedMessages: Message[] = [\n        createUserMessage(\n          'Context automatically compressed due to token limit. Essential information preserved.',\n        ),\n        summaryResponse,\n      ]\n\n      // Step 5: File recovery (optional, main agent only)\n      let recoveredFiles: CompressionResult['recoveredFiles']\n\n      if (options.recoverFiles) {\n        // TODO: Implement file recovery\n        // This should be migrated from src/utils/fileRecoveryCore.ts\n        // and integrated here to maintain recently accessed files\n        // in the compressed context.\n        //\n        // Requirements:\n        // - Use fileFreshnessService to get important files\n        // - Respect maxRecoveredFiles limit\n        // - Apply per-file and total token budgets\n        // - Add recovered files as user messages to compressedMessages\n        //\n        // See: src/utils/fileRecoveryCore.ts:selectAndReadFiles()\n        recoveredFiles = await this.recoverRecentFiles(\n          options.maxRecoveredFiles ?? 5,\n        )\n\n        // Note: File recovery is intentionally left as empty for now\n        // When implemented, recovered files should be appended to\n        // compressedMessages as formatted user messages\n      }\n\n      return {\n        compressedMessages,\n        wasCompacted: true,\n        summary,\n        recoveredFiles,\n      }\n    } catch (error) {\n      // Graceful degradation: if compression fails, continue with original messages\n      // This ensures the system remains functional even if compression encounters issues\n      console.error('Compression failed:', error)\n      return {\n        compressedMessages: messages,\n        wasCompacted: false,\n      }\n    }\n  }\n\n  /**\n   * Recover recently accessed files for context preservation\n   *\n   * **Status: Not Implemented (TODO)**\n   *\n   * This method should be migrated from src/utils/fileRecoveryCore.ts\n   * to maintain development context after compression. The implementation\n   * should:\n   *\n   * 1. Query fileFreshnessService for important files\n   * 2. Read file contents with proper error handling\n   * 3. Apply token budgets (per-file and total)\n   * 4. Truncate large files while preserving essential content\n   * 5. Return structured file data\n   *\n   * **Why this is private:**\n   * File recovery is an internal implementation detail of the compression\n   * process. External code should only interact with the public compress()\n   * method.\n   *\n   * **Why this is only for main agent:**\n   * - Main agent needs file context for coding workflows\n   * - Subagents should remain lightweight and stateless\n   * - File recovery adds significant token overhead\n   *\n   * @param maxFiles - Maximum number of files to recover\n   * @returns Array of recovered file data\n   *\n   * @private\n   * @internal\n   *\n   * @see src/utils/fileRecoveryCore.ts - Current implementation to migrate\n   * @see src/services/fileFreshness.ts - File tracking service\n   */\n  private static async recoverRecentFiles(\n    maxFiles: number,\n  ): Promise<NonNullable<CompressionResult['recoveredFiles']>> {\n    // TODO: Implement file recovery logic\n    //\n    // Migration checklist:\n    // - [ ] Import fileFreshnessService from @services/fileFreshness\n    // - [ ] Call getImportantFiles(maxFiles)\n    // - [ ] Read each file using readTextContent from @utils/file\n    // - [ ] Estimate tokens (content.length * 0.25)\n    // - [ ] Apply MAX_TOKENS_PER_FILE limit (10,000)\n    // - [ ] Apply MAX_TOTAL_FILE_TOKENS limit (50,000)\n    // - [ ] Handle read errors gracefully (skip failed files)\n    // - [ ] Return structured array matching CompressionResult['recoveredFiles']\n    //\n    // Reference implementation: src/utils/fileRecoveryCore.ts:selectAndReadFiles()\n\n    return []\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * Compression Service - Stateless Context Compression Core\n *\n * This service provides stateless compression functionality that can be used by\n * both the main agent and subagents without side effects. It is the foundation\n * of the layered compression architecture.\n *\n * **Architecture Design:**\n *\n * ```\n * \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n * \u2502              Compression System Architecture             \u2502\n * \u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n * \u2502  Layer 1: MainAgentCompressor                            \u2502\n * \u2502  - Handles /compact command and main agent compression   \u2502\n * \u2502  - Manages global state (messages, cache)                \u2502\n * \u2502  - Recovers recently accessed files                      \u2502\n * \u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n * \u2502  Layer 2: SubagentCompressor                             \u2502\n * \u2502  - Handles subagent automatic compression                \u2502\n * \u2502  - Operates only on local message arrays                 \u2502\n * \u2502  - Zero side effects, no global state modification       \u2502\n * \u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n * \u2502  Layer 3: CompressionService (THIS FILE)                 \u2502\n * \u2502  - Stateless compression algorithm                       \u2502\n * \u2502  - LLM-based summarization                               \u2502\n * \u2502  - Shared by both layers above                           \u2502\n * \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n * ```\n *\n * **Key Principles:**\n * - \u2705 Completely stateless - no global variable access\n * - \u2705 Pure functions - same input always produces same output\n * - \u2705 No side effects - does not modify messages parameter\n * - \u2705 Reusable - shared by main agent and subagent compressors\n *\n * @module CompressionService\n * @see src/services/mainAgentCompressor.ts - Main agent compression layer\n * @see src/services/subagentCompressor.ts - Subagent compression layer\n * @see CONTEXT_COMPRESSION_REFACTORING_GUIDE.md - Architecture documentation\n */\n\nimport { Message } from '@query'\nimport { queryLLM } from '@services/claude'\nimport { createUserMessage, normalizeMessagesForAPI } from '@utils/messages'\nimport { countTokens } from '@utils/tokens'\nimport {\n  getCompressionPrompt,\n  CompressionMode,\n} from '@constants/compressionPrompts'\nimport { getCompressionMode } from '@utils/compressionMode'\nimport { fileFreshnessService } from '@services/fileFreshness'\nimport { readTextContent } from '@utils/file'\n\n// File recovery configuration constants\nconst MAX_TOKENS_PER_FILE = 10_000\nconst MAX_TOTAL_FILE_TOKENS = 50_000\n\n/**\n * Configuration options for compression behavior\n */\nexport interface CompressionOptions {\n  /**\n   * Compression mode: determines the structure of the summary\n   * - 'business': Optimized for strategic consulting, research, and management\n   * - 'code': Optimized for software development, debugging, and coding\n   *\n   * If not specified, uses the global compression mode setting\n   */\n  mode?: CompressionMode\n\n  /**\n   * Threshold ratio for triggering compression (0-1)\n   *\n   * Compression triggers when: tokenCount >= contextLength * threshold\n   * Default: 0.92 (92% of context length)\n   *\n   * @example\n   * threshold: 0.92  // Compress at 92% capacity\n   * threshold: 0.80  // Compress earlier at 80% capacity\n   */\n  threshold?: number\n\n  /**\n   * Target model's maximum context length in tokens\n   *\n   * This should match the context length of the model being used\n   * by the agent (main agent or subagent).\n   *\n   * @example\n   * contextLength: 200_000  // Claude Sonnet 3.5\n   * contextLength: 128_000  // GPT-4\n   */\n  contextLength: number\n\n  /**\n   * Whether to recover recently accessed files (main agent only)\n   *\n   * File recovery adds recently accessed files back into the compressed\n   * context to maintain development workflow continuity. This should\n   * only be enabled for the main agent.\n   *\n   * - Main agent: true (preserve coding context)\n   * - Subagent: false (keep lightweight)\n   *\n   * Default: false\n   */\n  recoverFiles?: boolean\n\n  /**\n   * Maximum number of files to recover (if recoverFiles is true)\n   *\n   * Limits the number of files added to prevent context bloat.\n   * Default: 5\n   */\n  maxRecoveredFiles?: number\n}\n\n/**\n * Result of a compression operation\n */\nexport interface CompressionResult {\n  /**\n   * Compressed message array\n   *\n   * If compression was performed:\n   * - Index 0: User message explaining compression occurred\n   * - Index 1: Assistant message containing the summary\n   * - Index 2+: Recovered file messages (if recoverFiles was true)\n   *\n   * If compression was not needed:\n   * - Returns the original messages array unchanged\n   */\n  compressedMessages: Message[]\n\n  /**\n   * Whether compression was actually performed\n   *\n   * false if:\n   * - Token count below threshold\n   * - Message count < 3\n   * - Compression failed (error caught)\n   */\n  wasCompacted: boolean\n\n  /**\n   * The generated summary text (only if wasCompacted is true)\n   *\n   * Contains the LLM-generated conversation summary structured\n   * according to the compression mode (business or code).\n   */\n  summary?: string\n\n  /**\n   * Recovered files data (only if recoverFiles was true and wasCompacted is true)\n   *\n   * Each entry contains:\n   * - path: Absolute file path\n   * - content: File content (possibly truncated)\n   * - tokens: Estimated token count\n   * - truncated: Whether content was truncated due to token limits\n   */\n  recoveredFiles?: Array<{\n    path: string\n    content: string\n    tokens: number\n    truncated: boolean\n  }>\n}\n\n/**\n * Stateless Compression Service\n *\n * Provides pure compression functionality without touching any global state.\n * Used as the foundation for both main agent and subagent compression.\n */\nexport class CompressionService {\n  /**\n   * Determine if compression should be triggered\n   *\n   * Compression is triggered when:\n   * 1. Message count >= 3 (need enough context to summarize)\n   * 2. Token count >= contextLength * threshold\n   *\n   * @param messages - Messages to evaluate for compression\n   * @param options - Compression configuration\n   * @returns true if compression should be triggered\n   *\n   * @example\n   * ```typescript\n   * const shouldCompress = CompressionService.shouldCompress(messages, {\n   *   contextLength: 200_000,\n   *   threshold: 0.92,\n   * })\n   * if (shouldCompress) {\n   *   // Proceed with compression\n   * }\n   * ```\n   */\n  static shouldCompress(\n    messages: Message[],\n    options: CompressionOptions,\n  ): boolean {\n    // Need at least 3 messages to create meaningful summary\n    if (messages.length < 3) {\n      return false\n    }\n\n    const tokenCount = countTokens(messages)\n    const threshold = options.contextLength * (options.threshold ?? 0.92)\n\n    return tokenCount >= threshold\n  }\n\n  /**\n   * Execute context compression\n   *\n   * This method performs the actual compression by:\n   * 1. Checking if compression is needed (via shouldCompress)\n   * 2. Generating a comprehensive summary using LLM\n   * 3. Optionally recovering recently accessed files\n   * 4. Building the compressed message array\n   *\n   * **Important:** This method is completely stateless and has no side effects.\n   * It does NOT:\n   * - Modify the input messages array\n   * - Update any global state (messages, cache, etc.)\n   * - Call any state setters\n   *\n   * State management is the responsibility of the calling layer\n   * (MainAgentCompressor or SubagentCompressor).\n   *\n   * @param messages - Messages to compress\n   * @param tools - Available tools for LLM\n   * @param abortSignal - Abort signal for cancellation\n   * @param options - Compression configuration\n   * @returns Compression result with compressed messages and metadata\n   *\n   * @throws Never throws - errors are caught and returned as wasCompacted: false\n   *\n   * @example\n   * ```typescript\n   * // Subagent compression (no file recovery)\n   * const result = await CompressionService.compress(\n   *   subagentMessages,\n   *   tools,\n   *   abortSignal,\n   *   {\n   *     contextLength: 128_000,\n   *     recoverFiles: false,\n   *   }\n   * )\n   *\n   * if (result.wasCompacted) {\n   *   // Use result.compressedMessages\n   *   subagentMessages = result.compressedMessages\n   * }\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Main agent compression (with file recovery)\n   * const result = await CompressionService.compress(\n   *   mainMessages,\n   *   tools,\n   *   abortSignal,\n   *   {\n   *     contextLength: 200_000,\n   *     recoverFiles: true,\n   *     maxRecoveredFiles: 5,\n   *   }\n   * )\n   *\n   * if (result.wasCompacted) {\n   *   // Main agent layer will handle global state updates\n   *   // (messages, cache clearing, etc.)\n   * }\n   * ```\n   */\n  static async compress(\n    messages: Message[],\n    tools: any[],\n    abortSignal: AbortSignal,\n    options: CompressionOptions,\n  ): Promise<CompressionResult> {\n    // Early return if compression not needed\n    if (!this.shouldCompress(messages, options)) {\n      return {\n        compressedMessages: messages,\n        wasCompacted: false,\n      }\n    }\n\n    try {\n      // Step 1: Generate comprehensive conversation summary using LLM\n      const mode = options.mode ?? getCompressionMode()\n      const compressionPrompt = getCompressionPrompt(mode)\n      const summaryRequest = createUserMessage(compressionPrompt)\n\n      const summaryResponse = await queryLLM(\n        normalizeMessagesForAPI([...messages, summaryRequest]),\n        [\n          'You are a helpful AI assistant tasked with creating comprehensive conversation summaries that preserve all essential context for continuing work.',\n        ],\n        0,\n        tools,\n        abortSignal,\n        {\n          safeMode: false,\n          model: 'main', // Use main model for high-quality summarization\n          prependCLISysprompt: true,\n        },\n      )\n\n      // Step 2: Extract summary text from response\n      const content = summaryResponse.message.content\n      const summary =\n        typeof content === 'string'\n          ? content\n          : content.length > 0 && content[0]?.type === 'text'\n            ? content[0].text\n            : null\n\n      if (!summary) {\n        throw new Error(\n          'Failed to generate conversation summary - response did not contain valid text content',\n        )\n      }\n\n      // Step 3: Reset token usage for summary response\n      // The summary generation itself shouldn't count against the budget\n      // since it's an internal operation, not user-requested work\n      summaryResponse.message.usage = {\n        input_tokens: 0,\n        output_tokens: summaryResponse.message.usage.output_tokens,\n        cache_creation_input_tokens: 0,\n        cache_read_input_tokens: 0,\n      }\n\n      // Step 4: Build compressed messages array\n      const compressedMessages: Message[] = [\n        createUserMessage(\n          'Context automatically compressed due to token limit. Essential information preserved.',\n        ),\n        summaryResponse,\n      ]\n\n      // Step 5: File recovery (optional, main agent only)\n      let recoveredFiles: CompressionResult['recoveredFiles']\n\n      if (options.recoverFiles) {\n        recoveredFiles = await this.recoverRecentFiles(\n          options.maxRecoveredFiles ?? 5,\n        )\n\n        // Add recovered files as user messages to preserve context\n        if (recoveredFiles && recoveredFiles.length > 0) {\n          for (const file of recoveredFiles) {\n            const truncatedNote = file.truncated ? ' (truncated)' : ''\n            const fileMessage = createUserMessage(\n              `[Recovered File${truncatedNote}] ${file.path}\\n\\n\\`\\`\\`\\n${file.content}\\n\\`\\`\\``,\n            )\n            compressedMessages.push(fileMessage)\n          }\n        }\n      }\n\n      return {\n        compressedMessages,\n        wasCompacted: true,\n        summary,\n        recoveredFiles,\n      }\n    } catch (error) {\n      // Graceful degradation: if compression fails, continue with original messages\n      // This ensures the system remains functional even if compression encounters issues\n      console.error('Compression failed:', error)\n      return {\n        compressedMessages: messages,\n        wasCompacted: false,\n      }\n    }\n  }\n\n  /**\n   * Recover recently accessed files for context preservation\n   *\n   * **Status: Not Implemented (TODO)**\n   *\n   * This method should be migrated from src/utils/fileRecoveryCore.ts\n   * to maintain development context after compression. The implementation\n   * should:\n   *\n   * 1. Query fileFreshnessService for important files\n   * 2. Read file contents with proper error handling\n   * 3. Apply token budgets (per-file and total)\n   * 4. Truncate large files while preserving essential content\n   * 5. Return structured file data\n   *\n   * **Why this is private:**\n   * File recovery is an internal implementation detail of the compression\n   * process. External code should only interact with the public compress()\n   * method.\n   *\n   * **Why this is only for main agent:**\n   * - Main agent needs file context for coding workflows\n   * - Subagents should remain lightweight and stateless\n   * - File recovery adds significant token overhead\n   *\n   * @param maxFiles - Maximum number of files to recover\n   * @returns Array of recovered file data\n   *\n   * @private\n   * @internal\n   *\n   * @see src/utils/fileRecoveryCore.ts - Current implementation to migrate\n   * @see src/services/fileFreshness.ts - File tracking service\n   */\n  private static async recoverRecentFiles(\n    maxFiles: number,\n  ): Promise<NonNullable<CompressionResult['recoveredFiles']>> {\n    const importantFiles = fileFreshnessService.getImportantFiles(maxFiles)\n    const results: NonNullable<CompressionResult['recoveredFiles']> = []\n    let totalTokens = 0\n\n    for (const fileInfo of importantFiles) {\n      try {\n        const { content } = readTextContent(fileInfo.path)\n        const estimatedTokens = Math.ceil(content.length * 0.25)\n\n        // Apply per-file token limit to prevent any single file from dominating context\n        let finalContent = content\n        let truncated = false\n\n        if (estimatedTokens > MAX_TOKENS_PER_FILE) {\n          const maxChars = Math.floor(MAX_TOKENS_PER_FILE / 0.25)\n          finalContent = content.substring(0, maxChars)\n          truncated = true\n        }\n\n        const finalTokens = Math.min(estimatedTokens, MAX_TOKENS_PER_FILE)\n\n        // Enforce total token budget to maintain compression effectiveness\n        if (totalTokens + finalTokens > MAX_TOTAL_FILE_TOKENS) {\n          break\n        }\n\n        totalTokens += finalTokens\n        results.push({\n          path: fileInfo.path,\n          content: finalContent,\n          tokens: finalTokens,\n          truncated,\n        })\n      } catch (error) {\n        // Skip files that cannot be read - don't let one failure stop the process\n        console.error(\n          `Failed to read file for recovery: ${fileInfo.path}`,\n          error,\n        )\n      }\n    }\n\n    return results\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/services/contextMonitor.js

@@ -0,0 +1,162 @@
+import { countTokens } from "../utils/tokens.js";
+import { getModelManager } from "../utils/model.js";
+import { debug } from "../utils/debugLogger.js";
+const DEFAULT_CONFIG = {
+  warningThreshold: 0.7,
+  autoCompactThreshold: 0.95,
+  avgTokensPerTurn: 2e3,
+  minTurnsBeforeWarning: 3
+};
+class ContextMonitor {
+  config;
+  lastSuggestTime = 0;
+  suggestCooldownMs = 6e4;
+  // 1 minute cooldown
+  turnsSinceSuggest = 0;
+  constructor(config) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+  /**
+   * Update configuration
+   */
+  updateConfig(config) {
+    this.config = { ...this.config, ...config };
+  }
+  /**
+   * Get current configuration
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+  /**
+   * Check context usage and return a comprehensive report
+   */
+  checkUsage(messages, modelPointer = "main") {
+    const tokenCount = countTokens(messages);
+    const maxTokens = this.getContextLength(modelPointer);
+    const usagePercent = maxTokens > 0 ? tokenCount / maxTokens : 0;
+    let status = "normal";
+    let action = "none";
+    let message = "";
+    if (usagePercent >= this.config.autoCompactThreshold) {
+      status = "critical";
+      action = "auto-compact";
+      message = `Context critical (${this.formatPercent(usagePercent)}). Auto-compacting to preserve quality.`;
+    } else if (usagePercent >= this.config.warningThreshold) {
+      status = "warning";
+      const now = Date.now();
+      const cooldownPassed = now - this.lastSuggestTime >= this.suggestCooldownMs;
+      const enoughTurnsPassed = this.turnsSinceSuggest >= this.config.minTurnsBeforeWarning;
+      if (cooldownPassed && enoughTurnsPassed) {
+        action = "suggest-compact";
+        message = `Context at ${this.formatPercent(usagePercent)}. Consider running /compact to preserve response quality.`;
+        this.lastSuggestTime = now;
+        this.turnsSinceSuggest = 0;
+      } else {
+        message = `Context at ${this.formatPercent(usagePercent)}. Running low on context space.`;
+      }
+    } else {
+      message = `Context usage normal (${this.formatPercent(usagePercent)}).`;
+    }
+    const remainingTokens = maxTokens - tokenCount;
+    const estimatedTurnsRemaining = Math.max(
+      0,
+      Math.floor(remainingTokens / this.config.avgTokensPerTurn)
+    );
+    const report = {
+      tokenCount,
+      maxTokens,
+      usagePercent,
+      status,
+      action,
+      estimatedTurnsRemaining,
+      compactSuggested: action === "suggest-compact",
+      message
+    };
+    debug.state("CONTEXT_MONITOR_CHECK", {
+      tokenCount: String(tokenCount),
+      maxTokens: String(maxTokens),
+      usagePercent: this.formatPercent(usagePercent),
+      status,
+      action,
+      estimatedTurns: String(estimatedTurnsRemaining)
+    });
+    return report;
+  }
+  /**
+   * Record that a turn was completed (for cooldown tracking)
+   */
+  recordTurn() {
+    this.turnsSinceSuggest++;
+  }
+  /**
+   * Reset suggest cooldown (e.g., after user manually compacts)
+   */
+  resetCooldown() {
+    this.lastSuggestTime = 0;
+    this.turnsSinceSuggest = 0;
+  }
+  /**
+   * Get context length for a model
+   */
+  getContextLength(modelPointer) {
+    try {
+      const modelManager = getModelManager();
+      const profile = modelManager.resolveModel(modelPointer);
+      if (profile) {
+        return profile.contextLength;
+      }
+      return 2e5;
+    } catch {
+      return 2e5;
+    }
+  }
+  /**
+   * Format percentage for display
+   */
+  formatPercent(value) {
+    return `${Math.round(value * 100)}%`;
+  }
+}
+function getContextVisualization(report) {
+  const progressPercent = Math.round(report.usagePercent * 100);
+  let color = "green";
+  if (report.status === "critical") {
+    color = "red";
+  } else if (report.status === "warning") {
+    color = "yellow";
+  }
+  const formatTokens = (n) => {
+    if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+    if (n >= 1e3) return `${(n / 1e3).toFixed(1)}K`;
+    return String(n);
+  };
+  return {
+    progressPercent,
+    color,
+    label: `Context: ${progressPercent}%`,
+    stats: {
+      used: formatTokens(report.tokenCount),
+      total: formatTokens(report.maxTokens),
+      remaining: formatTokens(report.maxTokens - report.tokenCount),
+      turns: report.estimatedTurnsRemaining
+    }
+  };
+}
+let globalMonitor = null;
+function getContextMonitor() {
+  if (!globalMonitor) {
+    globalMonitor = new ContextMonitor();
+  }
+  return globalMonitor;
+}
+function resetContextMonitor() {
+  globalMonitor = null;
+}
+export {
+  ContextMonitor,
+  getContextMonitor,
+  getContextVisualization,
+  resetContextMonitor
+};
+//# sourceMappingURL=contextMonitor.js.map

package/dist/services/contextMonitor.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/services/contextMonitor.ts"],
+  "sourcesContent": ["/**\n * Context Monitor Service\n *\n * Monitors token usage and provides intelligent compression recommendations.\n * Implements the 70%/95% threshold system from the optimization roadmap.\n *\n * Features:\n * - Real-time token usage tracking\n * - 70% threshold warning (suggest manual /compact)\n * - 95% threshold auto-compact trigger\n * - Estimated turns remaining calculation\n * - Context health status reporting\n */\n\nimport { Message } from '@query'\nimport { countTokens } from '@utils/tokens'\nimport { getModelManager } from '@utils/model'\nimport { debug } from '@utils/debugLogger'\n\n/**\n * Context status levels\n */\nexport type ContextStatus = 'normal' | 'warning' | 'critical'\n\n/**\n * Recommended action based on context status\n */\nexport type ContextAction = 'none' | 'suggest-compact' | 'auto-compact'\n\n/**\n * Context usage report\n */\nexport interface ContextUsageReport {\n  /** Current token count */\n  tokenCount: number\n  /** Maximum context length for current model */\n  maxTokens: number\n  /** Usage percentage (0-1) */\n  usagePercent: number\n  /** Context health status */\n  status: ContextStatus\n  /** Recommended action */\n  action: ContextAction\n  /** Estimated turns remaining at current pace */\n  estimatedTurnsRemaining: number\n  /** Whether compact was recently suggested */\n  compactSuggested: boolean\n  /** Human-readable status message */\n  message: string\n}\n\n/**\n * Context Monitor Configuration\n */\nexport interface ContextMonitorConfig {\n  /** Warning threshold (0-1), default 0.70 */\n  warningThreshold: number\n  /** Auto-compact threshold (0-1), default 0.95 */\n  autoCompactThreshold: number\n  /** Average tokens per turn estimate, default 2000 */\n  avgTokensPerTurn: number\n  /** Minimum turns before suggesting compact, default 3 */\n  minTurnsBeforeWarning: number\n}\n\n/**\n * Default configuration\n */\nconst DEFAULT_CONFIG: ContextMonitorConfig = {\n  warningThreshold: 0.7,\n  autoCompactThreshold: 0.95,\n  avgTokensPerTurn: 2000,\n  minTurnsBeforeWarning: 3,\n}\n\n/**\n * Context Monitor\n *\n * Tracks context usage and provides compression recommendations.\n */\nexport class ContextMonitor {\n  private config: ContextMonitorConfig\n  private lastSuggestTime: number = 0\n  private suggestCooldownMs: number = 60000 // 1 minute cooldown\n  private turnsSinceSuggest: number = 0\n\n  constructor(config?: Partial<ContextMonitorConfig>) {\n    this.config = { ...DEFAULT_CONFIG, ...config }\n  }\n\n  /**\n   * Update configuration\n   */\n  updateConfig(config: Partial<ContextMonitorConfig>): void {\n    this.config = { ...this.config, ...config }\n  }\n\n  /**\n   * Get current configuration\n   */\n  getConfig(): ContextMonitorConfig {\n    return { ...this.config }\n  }\n\n  /**\n   * Check context usage and return a comprehensive report\n   */\n  checkUsage(\n    messages: Message[],\n    modelPointer: string = 'main',\n  ): ContextUsageReport {\n    const tokenCount = countTokens(messages)\n    const maxTokens = this.getContextLength(modelPointer)\n    const usagePercent = maxTokens > 0 ? tokenCount / maxTokens : 0\n\n    // Determine status\n    let status: ContextStatus = 'normal'\n    let action: ContextAction = 'none'\n    let message = ''\n\n    if (usagePercent >= this.config.autoCompactThreshold) {\n      status = 'critical'\n      action = 'auto-compact'\n      message = `Context critical (${this.formatPercent(usagePercent)}). Auto-compacting to preserve quality.`\n    } else if (usagePercent >= this.config.warningThreshold) {\n      status = 'warning'\n\n      // Only suggest compact if cooldown has passed\n      const now = Date.now()\n      const cooldownPassed =\n        now - this.lastSuggestTime >= this.suggestCooldownMs\n      const enoughTurnsPassed =\n        this.turnsSinceSuggest >= this.config.minTurnsBeforeWarning\n\n      if (cooldownPassed && enoughTurnsPassed) {\n        action = 'suggest-compact'\n        message = `Context at ${this.formatPercent(usagePercent)}. Consider running /compact to preserve response quality.`\n        this.lastSuggestTime = now\n        this.turnsSinceSuggest = 0\n      } else {\n        message = `Context at ${this.formatPercent(usagePercent)}. Running low on context space.`\n      }\n    } else {\n      message = `Context usage normal (${this.formatPercent(usagePercent)}).`\n    }\n\n    // Calculate estimated turns remaining\n    const remainingTokens = maxTokens - tokenCount\n    const estimatedTurnsRemaining = Math.max(\n      0,\n      Math.floor(remainingTokens / this.config.avgTokensPerTurn),\n    )\n\n    const report: ContextUsageReport = {\n      tokenCount,\n      maxTokens,\n      usagePercent,\n      status,\n      action,\n      estimatedTurnsRemaining,\n      compactSuggested: action === 'suggest-compact',\n      message,\n    }\n\n    debug.state('CONTEXT_MONITOR_CHECK', {\n      tokenCount: String(tokenCount),\n      maxTokens: String(maxTokens),\n      usagePercent: this.formatPercent(usagePercent),\n      status,\n      action,\n      estimatedTurns: String(estimatedTurnsRemaining),\n    })\n\n    return report\n  }\n\n  /**\n   * Record that a turn was completed (for cooldown tracking)\n   */\n  recordTurn(): void {\n    this.turnsSinceSuggest++\n  }\n\n  /**\n   * Reset suggest cooldown (e.g., after user manually compacts)\n   */\n  resetCooldown(): void {\n    this.lastSuggestTime = 0\n    this.turnsSinceSuggest = 0\n  }\n\n  /**\n   * Get context length for a model\n   */\n  private getContextLength(modelPointer: string): number {\n    try {\n      const modelManager = getModelManager()\n      // Use resolveModel which handles both pointer types and model names\n      const profile = modelManager.resolveModel(modelPointer)\n      if (profile) {\n        return profile.contextLength\n      }\n      // Default fallback for Claude\n      return 200_000\n    } catch {\n      return 200_000\n    }\n  }\n\n  /**\n   * Format percentage for display\n   */\n  private formatPercent(value: number): string {\n    return `${Math.round(value * 100)}%`\n  }\n}\n\n/**\n * Context usage visualization data for UI\n */\nexport interface ContextVisualization {\n  /** Progress bar segments (0-100) */\n  progressPercent: number\n  /** Color for progress bar */\n  color: 'green' | 'yellow' | 'red'\n  /** Label text */\n  label: string\n  /** Detailed stats */\n  stats: {\n    used: string\n    total: string\n    remaining: string\n    turns: number\n  }\n}\n\n/**\n * Generate visualization data for context usage\n */\nexport function getContextVisualization(\n  report: ContextUsageReport,\n): ContextVisualization {\n  const progressPercent = Math.round(report.usagePercent * 100)\n\n  let color: ContextVisualization['color'] = 'green'\n  if (report.status === 'critical') {\n    color = 'red'\n  } else if (report.status === 'warning') {\n    color = 'yellow'\n  }\n\n  const formatTokens = (n: number): string => {\n    if (n >= 1000000) return `${(n / 1000000).toFixed(1)}M`\n    if (n >= 1000) return `${(n / 1000).toFixed(1)}K`\n    return String(n)\n  }\n\n  return {\n    progressPercent,\n    color,\n    label: `Context: ${progressPercent}%`,\n    stats: {\n      used: formatTokens(report.tokenCount),\n      total: formatTokens(report.maxTokens),\n      remaining: formatTokens(report.maxTokens - report.tokenCount),\n      turns: report.estimatedTurnsRemaining,\n    },\n  }\n}\n\n// Global singleton instance\nlet globalMonitor: ContextMonitor | null = null\n\n/**\n * Get the global context monitor instance\n */\nexport function getContextMonitor(): ContextMonitor {\n  if (!globalMonitor) {\n    globalMonitor = new ContextMonitor()\n  }\n  return globalMonitor\n}\n\n/**\n * Reset the global context monitor (for testing)\n */\nexport function resetContextMonitor(): void {\n  globalMonitor = null\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/services/customCommands.js

@@ -6,7 +6,49 @@ import { getCwd } from "../utils/state.js";
 import { execFile } from "child_process";
 import { promisify } from "util";
 import { loadAllPlugins } from "../utils/pluginLoader.js";
+import {
+  getCurrentProjectConfig
+} from "../utils/config.js";
 const execFileAsync = promisify(execFile);
+function isBashCommandAllowed(command) {
+  const projectConfig = getCurrentProjectConfig();
+  const allowedTools = projectConfig?.allowedTools || [];
+  const parts = command.split(/\s+/);
+  const baseCommand = parts[0];
+  if (allowedTools.includes(`Bash(${command})`)) {
+    return true;
+  }
+  if (allowedTools.includes(`Bash(${baseCommand}:*)`)) {
+    return true;
+  }
+  const safeCommands = /* @__PURE__ */ new Set([
+    "git",
+    "ls",
+    "pwd",
+    "date",
+    "which",
+    "echo",
+    "cat",
+    "head",
+    "tail",
+    "wc",
+    "sort",
+    "uniq",
+    "grep",
+    "find",
+    "dirname",
+    "basename"
+  ]);
+  if (safeCommands.has(baseCommand)) {
+    return true;
+  }
+  return false;
+}
+function isFileReadAllowed(filePath) {
+  const projectConfig = getCurrentProjectConfig();
+  const allowedTools = projectConfig?.allowedTools || [];
+  return true;
+}
 async function executeBashCommands(content) {
   const bashCommandRegex = /!\`([^`]+)\`/g;
   const matches = [...content.matchAll(bashCommandRegex)];
@@ -17,6 +59,13 @@ async function executeBashCommands(content) {
   for (const match of matches) {
     const fullMatch = match[0];
     const command = match[1].trim();
+    if (!isBashCommandAllowed(command)) {
+      console.warn(
+        `Custom command bash execution denied: "${command}" - not in allowed list`
+      );
+      result = result.replace(fullMatch, `(permission denied: ${command})`);
+      continue;
+    }
     try {
       const parts = command.split(/\s+/);
       const cmd = parts[0];
@@ -72,8 +121,6 @@ ${fileContent}
   return result;
 }
 function validateAllowedTools(allowedTools) {
-  if (allowedTools && allowedTools.length > 0) {
-  }
   return true;
 }
 function parseFrontmatter(content) {
@@ -147,9 +194,8 @@ function createCustomCommand(frontmatter, content, filePath, baseDir) {
   const relativePath = filePath.replace(baseDir + "/", "");
   const pathParts = relativePath.split("/");
   const fileName = pathParts[pathParts.length - 1].replace(".md", "");
-  const userClaudeDir = join(homedir(), ".claude", "commands");
   const userMintoDir = join(homedir(), ".minto", "commands");
-  const scope = baseDir === userClaudeDir || baseDir === userMintoDir ? "user" : "project";
+  const scope = baseDir === userMintoDir ? "user" : "project";
   const prefix = scope === "user" ? "user" : "project";
   let finalName;
   if (frontmatter.name) {
@@ -221,47 +267,26 @@ IMPORTANT: You are restricted to using only these tools: ${allowedToolsStr}. Do
 }
 const loadCustomCommands = memoize(
   async () => {
-    const userClaudeDir = join(homedir(), ".claude", "commands");
-    const projectClaudeDir = join(getCwd(), ".claude", "commands");
     const userMintoDir = join(homedir(), ".minto", "commands");
     const projectMintoDir = join(getCwd(), ".minto", "commands");
     const abortController = new AbortController();
     const timeout = setTimeout(() => abortController.abort(), 3e3);
     try {
       const startTime = Date.now();
-      const [
-        projectClaudeFiles,
-        userClaudeFiles,
-        projectMintoFiles,
-        userMintoFiles
-      ] = await Promise.all([
-        existsSync(projectClaudeDir) ? scanMarkdownFiles(
-          ["--files", "--hidden", "--glob", "*.md"],
-          // Legacy args for ripgrep compatibility
-          projectClaudeDir,
-          abortController.signal
-        ) : Promise.resolve([]),
-        existsSync(userClaudeDir) ? scanMarkdownFiles(
-          ["--files", "--glob", "*.md"],
-          // Legacy args for ripgrep compatibility
-          userClaudeDir,
-          abortController.signal
-        ) : Promise.resolve([]),
+      const [projectMintoFiles, userMintoFiles] = await Promise.all([
         existsSync(projectMintoDir) ? scanMarkdownFiles(
           ["--files", "--hidden", "--glob", "*.md"],
-          // Legacy args for ripgrep compatibility
           projectMintoDir,
           abortController.signal
         ) : Promise.resolve([]),
         existsSync(userMintoDir) ? scanMarkdownFiles(
           ["--files", "--glob", "*.md"],
-          // Legacy args for ripgrep compatibility
           userMintoDir,
           abortController.signal
         ) : Promise.resolve([])
       ]);
-      const projectFiles = [...projectMintoFiles, ...projectClaudeFiles];
-      const userFiles = [...userMintoFiles, ...userClaudeFiles];
+      const projectFiles = [...projectMintoFiles];
+      const userFiles = [...userMintoFiles];
       const allFiles = [...projectFiles, ...userFiles];
       const duration = Date.now() - startTime;
       const commands = [];
@@ -269,12 +294,11 @@ const loadCustomCommands = memoize(
         try {
           const content = readFileSync(filePath, { encoding: "utf-8" });
           const { frontmatter, content: commandContent } = parseFrontmatter(content);
-          const baseDir = filePath.includes(".minto/commands") ? projectMintoDir : projectClaudeDir;
           const command = createCustomCommand(
             frontmatter,
             commandContent,
             filePath,
-            baseDir
+            projectMintoDir
           );
           if (command) {
             commands.push(command);
@@ -287,12 +311,11 @@ const loadCustomCommands = memoize(
         try {
           const content = readFileSync(filePath, { encoding: "utf-8" });
           const { frontmatter, content: commandContent } = parseFrontmatter(content);
-          const baseDir = filePath.includes(".minto/commands") ? userMintoDir : userClaudeDir;
           const command = createCustomCommand(
             frontmatter,
             commandContent,
             filePath,
-            baseDir
+            userMintoDir
           );
           if (command) {
             commands.push(command);
@@ -314,11 +337,9 @@ const loadCustomCommands = memoize(
   // This ensures cache invalidation when directories change
   () => {
     const cwd = getCwd();
-    const userClaudeDir = join(homedir(), ".claude", "commands");
-    const projectClaudeDir = join(cwd, ".claude", "commands");
     const userMintoDir = join(homedir(), ".minto", "commands");
     const projectMintoDir = join(cwd, ".minto", "commands");
-    return `${cwd}:${existsSync(userClaudeDir)}:${existsSync(projectClaudeDir)}:${existsSync(userMintoDir)}:${existsSync(projectMintoDir)}:${Math.floor(Date.now() / 6e4)}`;
+    return `${cwd}:${existsSync(userMintoDir)}:${existsSync(projectMintoDir)}:${Math.floor(Date.now() / 6e4)}`;
   }
 );
 const reloadCustomCommands = () => {
@@ -326,15 +347,13 @@ const reloadCustomCommands = () => {
 };
 function getCustomCommandDirectories() {
   return {
-    userClaude: join(homedir(), ".claude", "commands"),
-    projectClaude: join(getCwd(), ".claude", "commands"),
-    userMinto: join(homedir(), ".minto", "commands"),
-    projectMinto: join(getCwd(), ".minto", "commands")
+    user: join(homedir(), ".minto", "commands"),
+    project: join(getCwd(), ".minto", "commands")
   };
 }
 function hasCustomCommands() {
-  const { userClaude, projectClaude, userMinto, projectMinto } = getCustomCommandDirectories();
-  return existsSync(userClaude) || existsSync(projectClaude) || existsSync(userMinto) || existsSync(projectMinto);
+  const { user, project } = getCustomCommandDirectories();
+  return existsSync(user) || existsSync(project);
 }
 const loadPluginCommands = memoize(
   async () => {