@compilr-dev/cli 0.4.0

package/dist/repl.js

@@ -0,0 +1,1878 @@
+/**
+ * REPL (Read-Eval-Print Loop)
+ *
+ * Main orchestration for the interactive agent session.
+ * Coordinates between input, agent execution, and output.
+ *
+ * Uses event-driven architecture with Footer component for:
+ * - Persistent todo list while agent runs
+ * - Persistent input prompt (always visible)
+ * - Input queueing during agent execution
+ * - Esc to cancel running agent
+ */
+import { builtinSkills } from '@compilr-dev/agents';
+import { exec } from 'child_process';
+import { getToolPermissionInfo } from './agent.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import pc from 'picocolors';
+import { debug, debugError } from './debug.js';
+import { getNextMode, MODE_INFO } from './ui/types.js';
+import { createInitialState, updateTodos, setAgentRunning } from './state.js';
+import { Footer } from './ui/footer.js';
+import * as conversation from './ui/conversation.js';
+import * as overlays from './ui/overlays.js';
+import * as terminal from './ui/terminal.js';
+import { resolveCommand } from './commands.js';
+import { showAgentsOverlay } from './ui/agents-overlay.js';
+import { showCommandsOverlay } from './ui/commands-overlay.js';
+import { showConfigOverlay } from './ui/config-overlay.js';
+import { showInitOverlay } from './ui/init-overlay.js';
+import { showBacklogOverlay } from './ui/backlog-overlay.js';
+import { showKeysOverlay } from './ui/keys-overlay.js';
+import { showTutorialOverlay } from './ui/tutorial-overlay.js';
+import { showToolsOverlay } from './ui/tools-overlay.js';
+import { showModelWarningOverlay } from './ui/model-warning-overlay.js';
+import { showArchTypeOverlay } from './ui/arch-type-overlay.js';
+import { registerFooterCallbacks } from './ui/overlay-controller.js';
+import { getCustomCommandRegistry } from './commands/index.js';
+import { getPermissionMode } from './settings/index.js';
+import { getModelTier, modelMeetsTier } from './utils/model-tiers.js';
+import { findBacklogPath, parseBacklogItems } from './tools/backlog.js';
+import { isOverlayActive } from './shared-handlers.js';
+import { loadCompilrConfig } from './utils/project-status.js';
+// =============================================================================
+// Tool Intent Detection
+// =============================================================================
+// Keyword patterns for tool selection
+const TOOL_KEYWORDS = {
+    read_file: ['read', 'show', 'display', 'look at', 'view', 'what is in', 'content of'],
+    write_file: ['write', 'create', 'save', 'make a file'],
+    edit: ['edit', 'modify', 'change', 'update', 'fix', 'replace'],
+    bash: ['run', 'execute', 'command', 'shell', 'npm', 'git', 'pip', 'ls', 'pwd', 'mkdir', 'build', 'install'],
+    grep: ['search', 'find', 'grep', 'look for', 'where is', 'occurrences'],
+    glob: ['list files', 'find files', 'what files', 'show files', 'directory', 'pattern'],
+    todo_write: ['todo', 'task', 'plan', 'steps'],
+    todo_read: ['todo', 'task', 'plan', 'steps'],
+    backlog_read: ['backlog', 'requirements', 'features', 'bugs', 'items'],
+    backlog_write: ['backlog', 'requirements', 'features', 'bugs', 'add item', 'add feature'],
+    git_status: ['git status', 'changes', 'modified', 'staged'],
+    git_diff: ['git diff', 'differences', 'what changed'],
+    git_log: ['git log', 'history', 'commits'],
+    git_commit: ['commit', 'save changes'],
+    git_branch: ['branch', 'branches'],
+    detect_project: ['project type', 'what kind of project', 'framework'],
+    find_project_root: ['project root', 'root directory'],
+    run_tests: ['test', 'tests', 'run tests', 'check tests'],
+    run_lint: ['lint', 'linting', 'check code', 'style'],
+};
+/**
+ * Select relevant tool names based on user input intent
+ */
+function selectToolNamesByIntent(input, allToolNames) {
+    const lower = input.toLowerCase();
+    // If input is very short or a question, use all tools
+    if (input.length < 10 || input.includes('?')) {
+        return allToolNames;
+    }
+    const selected = new Set();
+    // Add tools based on keyword matches
+    for (const [tool, keywords] of Object.entries(TOOL_KEYWORDS)) {
+        if (keywords.some((kw) => lower.includes(kw)) && allToolNames.includes(tool)) {
+            selected.add(tool);
+        }
+    }
+    // Always include todo tools (they're used implicitly)
+    if (allToolNames.includes('todo_write'))
+        selected.add('todo_write');
+    if (allToolNames.includes('todo_read'))
+        selected.add('todo_read');
+    // If nothing matched, use all tools
+    if (selected.size === 0) {
+        return allToolNames;
+    }
+    return Array.from(selected);
+}
+// =============================================================================
+// Build Command Types and Constants
+// =============================================================================
+const PRIORITY_ORDER = ['critical', 'high', 'medium', 'low'];
+// =============================================================================
+// Project Detection Helpers
+// =============================================================================
+/**
+ * Detect if we're in a compilr project (has .compilr folder or -docs sibling)
+ * Returns project path from config.json if available
+ */
+function detectCompilrProject() {
+    const cwd = process.cwd();
+    // First try to load config and get paths from there
+    const config = loadCompilrConfig(cwd);
+    if (config) {
+        return {
+            found: true,
+            backlogPath: findBacklogPath(cwd),
+            projectPath: config.paths.project || null,
+            docsPath: config.paths.docs,
+        };
+    }
+    // Check for .compilr folder in current directory
+    const compilrDir = path.join(cwd, '.compilr');
+    if (fs.existsSync(compilrDir)) {
+        const backlogPath = path.join(compilrDir, 'backlog.md');
+        return {
+            found: true,
+            backlogPath: fs.existsSync(backlogPath) ? backlogPath : null,
+            projectPath: cwd,
+            docsPath: null,
+        };
+    }
+    // Check for -docs sibling folder (two-repo pattern)
+    const parentDir = path.dirname(cwd);
+    const projectName = path.basename(cwd);
+    const docsDir = path.join(parentDir, `${projectName}-docs`);
+    const docsBacklogPath = path.join(docsDir, '01-planning', 'backlog.md');
+    if (fs.existsSync(docsBacklogPath)) {
+        return {
+            found: true,
+            backlogPath: docsBacklogPath,
+            projectPath: cwd,
+            docsPath: docsDir,
+        };
+    }
+    // Check if we're in the docs repo itself
+    const inDocsBacklog = path.join(cwd, '01-planning', 'backlog.md');
+    if (fs.existsSync(inDocsBacklog)) {
+        // We're in -docs folder, try to find sibling code folder
+        const baseName = projectName.replace(/-docs$/, '');
+        const codeDir = path.join(parentDir, baseName);
+        return {
+            found: true,
+            backlogPath: inDocsBacklog,
+            projectPath: fs.existsSync(codeDir) ? codeDir : null,
+            docsPath: cwd,
+        };
+    }
+    // Check for project subfolders (running from parent folder after /init)
+    try {
+        const entries = fs.readdirSync(cwd, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            // Check for .compilr in subfolder (single-repo pattern)
+            const subCompilrDir = path.join(cwd, entry.name, '.compilr');
+            if (fs.existsSync(subCompilrDir)) {
+                const backlogPath = path.join(subCompilrDir, 'backlog.md');
+                return {
+                    found: true,
+                    backlogPath: fs.existsSync(backlogPath) ? backlogPath : null,
+                    projectPath: path.join(cwd, entry.name),
+                    docsPath: null,
+                };
+            }
+            // Check for -docs subfolder (two-repo pattern)
+            if (entry.name.endsWith('-docs')) {
+                const docsBacklog = path.join(cwd, entry.name, '01-planning', 'backlog.md');
+                if (fs.existsSync(docsBacklog)) {
+                    const baseName = entry.name.replace(/-docs$/, '');
+                    const codeDir = path.join(cwd, baseName);
+                    return {
+                        found: true,
+                        backlogPath: docsBacklog,
+                        projectPath: fs.existsSync(codeDir) ? codeDir : null,
+                        docsPath: path.join(cwd, entry.name),
+                    };
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    return { found: false, backlogPath: null, projectPath: null, docsPath: null };
+}
+/**
+ * Check if backlog has any items using the shared parser
+ */
+function hasBacklogItems(backlogPath) {
+    if (!backlogPath || !fs.existsSync(backlogPath)) {
+        return false;
+    }
+    try {
+        const content = fs.readFileSync(backlogPath, 'utf-8');
+        const items = parseBacklogItems(content);
+        return items.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get skill prompt by name from builtinSkills
+ */
+function getSkillPrompt(name) {
+    const skill = builtinSkills.find((s) => s.name === name);
+    return skill?.prompt ?? null;
+}
+// =============================================================================
+// Build Command Helpers
+// =============================================================================
+/**
+ * Select the best backlog item to build.
+ * If requestedId is provided, finds that specific item.
+ * Otherwise, auto-picks the highest priority 📋 item.
+ */
+function selectBuildItem(items, requestedId) {
+    // If specific ID requested, find it
+    if (requestedId && requestedId.toLowerCase() !== 'scaffold') {
+        const searchId = requestedId.toUpperCase();
+        const item = items.find(i => i.id === searchId);
+        if (!item)
+            return null;
+        if (item.status !== '📋') {
+            // Item exists but not in planned status
+            return null; // Handler will show appropriate message
+        }
+        return item;
+    }
+    // Filter to only 📋 (planned) items
+    const planned = items.filter(i => i.status === '📋');
+    if (planned.length === 0)
+        return null;
+    // Sort by priority, then by ID
+    planned.sort((a, b) => {
+        const prioA = PRIORITY_ORDER.indexOf(a.priority.toLowerCase());
+        const prioB = PRIORITY_ORDER.indexOf(b.priority.toLowerCase());
+        if (prioA !== prioB)
+            return prioA - prioB;
+        return a.id.localeCompare(b.id); // REQ-001 before REQ-002
+    });
+    return planned[0];
+}
+/**
+ * Find dependency IDs mentioned in item title/description.
+ * Looks for patterns like "depends on REQ-001", "blocked by BUG-002", etc.
+ */
+function findDependencies(item) {
+    const text = `${item.title} ${item.description}`;
+    const patterns = [
+        /depends\s+on\s+([A-Z]+-\d+)/gi,
+        /blocked\s+by\s+([A-Z]+-\d+)/gi,
+        /requires\s+([A-Z]+-\d+)/gi,
+        /after\s+([A-Z]+-\d+)/gi,
+        /needs\s+([A-Z]+-\d+)/gi,
+    ];
+    const deps = [];
+    for (const pattern of patterns) {
+        const matches = text.matchAll(pattern);
+        for (const match of matches) {
+            deps.push(match[1].toUpperCase());
+        }
+    }
+    return [...new Set(deps)];
+}
+/**
+ * Get list of dependencies that are not yet completed.
+ */
+function getUnmetDependencies(item, allItems) {
+    const depIds = findDependencies(item);
+    return allItems.filter(i => depIds.includes(i.id) && i.status !== '✅');
+}
+/**
+ * Check if the project has a code foundation (src/, package.json, etc.)
+ */
+function hasProjectFoundation() {
+    const cwd = process.cwd();
+    const indicators = [
+        'src',
+        'lib',
+        'app',
+        'package.json',
+        'requirements.txt',
+        'Cargo.toml',
+        'go.mod',
+        'pom.xml',
+        'build.gradle',
+        'setup.py',
+        'pyproject.toml',
+    ];
+    for (const indicator of indicators) {
+        const fullPath = path.join(cwd, indicator);
+        if (fs.existsSync(fullPath)) {
+            return true;
+        }
+    }
+    // Also check in project subfolders (for two-repo pattern)
+    try {
+        const entries = fs.readdirSync(cwd, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            // Skip docs folder and hidden folders
+            if (entry.name.endsWith('-docs') || entry.name.startsWith('.'))
+                continue;
+            for (const indicator of indicators) {
+                const subPath = path.join(cwd, entry.name, indicator);
+                if (fs.existsSync(subPath)) {
+                    return true;
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    return false;
+}
+// =============================================================================
+// REPL Class
+// =============================================================================
+export class REPL {
+    agent;
+    model;
+    currentModel; // Can be hot-switched
+    provider;
+    version;
+    showFiltering;
+    onModeChange;
+    onAgentFinish;
+    startTime;
+    state;
+    footer;
+    // Session stats
+    sessionInputTokens = 0;
+    sessionOutputTokens = 0;
+    sessionRequests = 0;
+    // Running state
+    isRunning = false;
+    agentRunning = false;
+    abortController = null;
+    // Promise for waiting on REPL exit
+    exitResolve = null;
+    constructor(options) {
+        this.agent = options.agent;
+        this.model = options.model;
+        this.currentModel = options.model; // Start with same model, can be hot-switched
+        this.provider = options.provider ?? 'unknown';
+        this.version = options.version ?? '0.0.1';
+        this.showFiltering = options.showFiltering ?? false;
+        this.onModeChange = options.onModeChange;
+        this.onAgentFinish = options.onAgentFinish;
+        this.startTime = new Date();
+        this.state = createInitialState(this.model);
+        // Map permission mode setting to AgentMode
+        const permissionMode = getPermissionMode();
+        const initialMode = permissionMode === 'bypass' ? 'auto-accept' :
+            permissionMode === 'plan' ? 'plan' : 'normal';
+        this.footer = new Footer({
+            showSeparators: true,
+            initialMode,
+        });
+        // Notify external state handler of initial mode
+        if (this.onModeChange && initialMode !== 'normal') {
+            this.onModeChange(initialMode);
+        }
+        // Set up event handlers
+        this.setupEventHandlers();
+        // Notify that footer is ready with pause/resume/setSuggestion functions
+        if (options.onFooterReady) {
+            options.onFooterReady(() => { this.footer.pauseAnimation(); }, () => { this.footer.resumeAnimation(); }, (action) => { this.footer.setSuggestion(action); });
+        }
+        // Register footer callbacks for overlay controller (used by tools like ask_user)
+        registerFooterCallbacks(() => { this.footer.pauseAnimation(); }, () => { this.footer.resumeAnimation(); });
+    }
+    /**
+     * Set up Footer event handlers
+     */
+    setupEventHandlers() {
+        // Handle submit - process message or it gets queued by Footer
+        this.footer.on('submit', (input) => {
+            if (!this.agentRunning && input.trim()) {
+                void this.handleSubmit(input);
+            }
+            // If agent is running, Footer automatically queues the input
+        });
+        // Handle slash commands
+        this.footer.on('command', (command, args) => {
+            // Pause animation for overlays
+            this.footer.pauseAnimation();
+            void this.handleCommand(command, args).then((shouldContinue) => {
+                this.footer.resumeAnimation();
+                if (!shouldContinue) {
+                    this.isRunning = false;
+                    if (this.exitResolve) {
+                        this.exitResolve();
+                    }
+                }
+            });
+        });
+        // Handle Esc - abort running agent
+        this.footer.on('escape', () => {
+            if (this.agentRunning && this.abortController) {
+                this.abortController.abort();
+                conversation.printWarning('Agent execution cancelled');
+            }
+        });
+        // Handle Ctrl+C - exit REPL
+        this.footer.on('cancel', () => {
+            this.isRunning = false;
+            if (this.exitResolve) {
+                this.exitResolve();
+            }
+        });
+        // Handle Shift+Tab - cycle modes
+        this.footer.on('modeChange', () => {
+            this.cycleMode();
+        });
+    }
+    /**
+     * Cycle through agent modes (normal -> auto-accept -> plan -> normal)
+     */
+    cycleMode() {
+        const currentMode = this.footer.getMode();
+        const nextMode = getNextMode(currentMode);
+        this.footer.setMode(nextMode);
+        // Notify external state handler
+        if (this.onModeChange) {
+            this.onModeChange(nextMode);
+        }
+        // Show feedback
+        const modeInfo = MODE_INFO[nextMode];
+        this.footer.clearForOutput();
+        conversation.printInfo(`Mode: ${modeInfo.label} - ${modeInfo.description}`);
+        this.footer.forceRender();
+    }
+    // ===========================================================================
+    // Public API
+    // ===========================================================================
+    /**
+     * Start the REPL (event-driven)
+     */
+    async run() {
+        this.isRunning = true;
+        // Set terminal title and clear screen
+        terminal.setTitle('compilr');
+        terminal.clearScreen();
+        conversation.printWelcome(this.model, this.version);
+        // Start footer (begins render loop and input capture)
+        this.footer.start();
+        // Wait for exit signal
+        await this.waitForExit();
+        // Cleanup
+        this.footer.stop();
+        terminal.writeLine('');
+        conversation.printInfo('Goodbye!');
+    }
+    /**
+     * Wait for REPL exit
+     */
+    waitForExit() {
+        return new Promise((resolve) => {
+            this.exitResolve = resolve;
+        });
+    }
+    /**
+     * Get current model
+     */
+    getCurrentModel() {
+        return this.currentModel;
+    }
+    /**
+     * Get current provider
+     */
+    getProvider() {
+        return this.provider;
+    }
+    /**
+     * Set model for hot-switching (within same provider)
+     */
+    setModel(model) {
+        this.currentModel = model;
+        conversation.printInfo(`Model switched to: ${model}`);
+    }
+    /**
+     * Set the agent mode programmatically (e.g., from permission handler)
+     */
+    setMode(mode) {
+        this.footer.setMode(mode);
+        // Notify external state handler
+        if (this.onModeChange) {
+            this.onModeChange(mode);
+        }
+        // Show feedback
+        const modeInfo = MODE_INFO[mode];
+        this.footer.clearForOutput();
+        conversation.printInfo(`Mode: ${modeInfo.label} - ${modeInfo.description}`);
+        this.footer.forceRender();
+    }
+    /**
+     * Stop the REPL
+     */
+    stop() {
+        this.isRunning = false;
+        this.footer.stop();
+        if (this.exitResolve) {
+            this.exitResolve();
+        }
+    }
+    /**
+     * Handle submitted input (processes message and queued inputs)
+     */
+    async handleSubmit(input) {
+        // Clear any previous suggestion when new input is submitted
+        this.footer.setSuggestion(null);
+        await this.processMessage(input);
+        // Process queued inputs (FIFO)
+        while (this.footer.hasQueuedInput() && this.isRunning) {
+            const queued = this.footer.popQueuedInput();
+            if (queued) {
+                await this.processMessage(queued);
+            }
+        }
+    }
+    // ===========================================================================
+    // Command Handling
+    // ===========================================================================
+    /**
+     * Handle slash command
+     * Returns false if REPL should exit
+     */
+    async handleCommand(command, args) {
+        // Resolve aliases to canonical command name
+        const resolved = resolveCommand(command);
+        if (!resolved) {
+            // Check if it's a custom command
+            const customRegistry = getCustomCommandRegistry();
+            if (customRegistry.has(command)) {
+                // Expand custom command and send as message
+                const customArgs = args ? args.split(' ').filter(a => a.trim()) : [];
+                const expanded = customRegistry.expand(command, customArgs);
+                if (expanded) {
+                    // Resume animation before processing (it was paused for overlay commands)
+                    this.footer.resumeAnimation();
+                    // Process as a regular message
+                    await this.processMessage(expanded);
+                    return true;
+                }
+            }
+            conversation.printWarning(`Unknown command: /${command}`);
+            conversation.printInfo('Type /help to see available commands');
+            return true;
+        }
+        switch (resolved) {
+            case 'agents':
+                await showAgentsOverlay();
+                return true;
+            case 'backlog': {
+                const backlogResult = await showBacklogOverlay();
+                if (backlogResult.modified) {
+                    conversation.printSuccess('Backlog updated.');
+                }
+                return true;
+            }
+            case 'commands':
+                await showCommandsOverlay();
+                return true;
+            case 'exit':
+                return false;
+            case 'help':
+                await overlays.showHelp();
+                return true;
+            case 'init': {
+                const initResult = await showInitOverlay();
+                if (initResult.created) {
+                    // Show success message with created files info
+                    conversation.printSuccess(`Project created: ${initResult.projectPath ?? ''}`);
+                    if (initResult.docsPath) {
+                        conversation.printSuccess(`Docs repo created: ${initResult.docsPath}`);
+                    }
+                    conversation.printInfo('');
+                    conversation.printInfo('Next steps:');
+                    conversation.printInfo(`  cd ${initResult.projectPath?.split('/').pop() ?? 'project'}`);
+                    conversation.printInfo('  npm install');
+                    conversation.printInfo('  npm run dev');
+                    conversation.printInfo('');
+                    // Resume footer animation before processing message
+                    this.footer.resumeAnimation();
+                    // Ask agent to read the COMPILR.md and understand the project
+                    const compilrMdPath = initResult.docsPath
+                        ? `${initResult.docsPath}/COMPILR.md`
+                        : `${initResult.projectPath ?? '.'}/COMPILR.md`;
+                    await this.processMessage(`I just created a new project using /init. Please read ${compilrMdPath} to understand the project context and confirm you're ready to help me build it.
+
+(Note to user: When you want to define requirements and populate the backlog, type /design)`);
+                }
+                return true;
+            }
+            case 'keys': {
+                const keysResult = await showKeysOverlay();
+                if (keysResult.changed) {
+                    conversation.printSuccess('API keys updated.');
+                    conversation.printInfo('Restart the CLI to use the new keys.');
+                }
+                return true;
+            }
+            case 'clear':
+                terminal.clearScreen();
+                conversation.printWelcome(this.model, this.version);
+                return true;
+            case 'compact':
+                await this.handleCompact();
+                return true;
+            case 'config': {
+                // Get context stats for usage tab
+                const contextManager = this.agent.getContextManager();
+                const history = this.agent.getHistory();
+                let contextUsed = 0;
+                let contextMax = 200000;
+                if (contextManager) {
+                    const stats = contextManager.getStats(history.length);
+                    contextUsed = stats.currentTokens;
+                    contextMax = stats.maxTokens;
+                }
+                const configResult = await showConfigOverlay({
+                    version: this.version,
+                    cwd: process.cwd(),
+                    model: this.currentModel,
+                    provider: this.provider,
+                    toolCount: this.agent.getToolDefinitions().length,
+                    startTime: this.startTime,
+                    // Usage stats
+                    inputTokens: this.sessionInputTokens,
+                    outputTokens: this.sessionOutputTokens,
+                    requests: this.sessionRequests,
+                    contextUsed,
+                    contextMax,
+                    messageCount: history.length,
+                    // Model change callback for hot-switch
+                    onModelChange: (model) => {
+                        this.setModel(model);
+                    },
+                });
+                // Handle model change result (for hot-switch)
+                if (configResult.modelChanged) {
+                    this.currentModel = configResult.modelChanged;
+                }
+                // Refresh prompt in case theme changed
+                this.footer.refreshPrompt();
+                return true;
+            }
+            case 'tools':
+                await this.showTools();
+                return true;
+            case 'tokens':
+                this.showTokens();
+                return true;
+            case 'context':
+                this.showContext();
+                return true;
+            case 'export':
+                await this.handleExport(args);
+                return true;
+            case 'model': {
+                const modelResult = await showConfigOverlay({
+                    model: this.currentModel,
+                    provider: this.provider,
+                    initialMode: 'model-selector',
+                    // Don't print in callback - overlay cleanup would clear it
+                    // We'll print after overlay closes instead
+                });
+                // Handle model change result
+                if (modelResult.modelChanged) {
+                    this.currentModel = modelResult.modelChanged;
+                    // Clear footer, print message, re-render footer
+                    this.footer.clearForOutput();
+                    conversation.printSuccess(`Model switched to: ${modelResult.modelChanged}`);
+                    this.footer.forceRender();
+                }
+                return true;
+            }
+            case 'status':
+                this.showStatus();
+                return true;
+            case 'todos':
+                this.showTodos();
+                return true;
+            case 'plan':
+                // Switch to plan mode
+                this.footer.setMode('plan');
+                if (this.onModeChange) {
+                    this.onModeChange('plan');
+                }
+                conversation.printInfo('📋 Switched to Plan mode');
+                conversation.printInfo('The agent will create execution plans without performing actions.');
+                conversation.printInfo('Use Shift+Tab to switch back to Normal or Auto-accept mode.');
+                return true;
+            case 'design': {
+                // Check if project is initialized
+                const designProject = detectCompilrProject();
+                if (!designProject.found) {
+                    conversation.printError('No .compilr project found. Run /init first.');
+                    return true;
+                }
+                // Check model tier - /design works best with large models
+                if (!modelMeetsTier(this.currentModel, '/design')) {
+                    const modelTier = getModelTier(this.currentModel);
+                    // Show warning overlay
+                    const choice = await showModelWarningOverlay({
+                        command: '/design',
+                        currentModel: this.currentModel,
+                        currentTier: modelTier.tier,
+                        suggestedModel: modelTier.suggestedUpgrade,
+                        alternativeCommand: '/sketch',
+                    });
+                    switch (choice) {
+                        case 'cancel':
+                            return true;
+                        case 'alternative':
+                            // Run /sketch instead (command name without leading slash)
+                            return this.handleCommand('sketch', '');
+                        case 'switch':
+                            // Hot-switch to the suggested model
+                            if (modelTier.suggestedUpgrade) {
+                                this.currentModel = modelTier.suggestedUpgrade;
+                                conversation.printSuccess(`Switched to ${modelTier.suggestedUpgrade}`);
+                                conversation.printInfo('');
+                            }
+                            else {
+                                conversation.printWarning('No suggested upgrade available. Continuing with current model.');
+                                conversation.printInfo('');
+                            }
+                            break;
+                        case 'continue':
+                            // Proceed with current model
+                            break;
+                    }
+                }
+                // Get design skill prompt
+                const designPrompt = getSkillPrompt('design');
+                if (!designPrompt) {
+                    conversation.printError('Design skill not found.');
+                    return true;
+                }
+                // Note: Plan mode is not yet implemented, so we run in normal mode
+                // The skill prompt guides the agent's behavior
+                conversation.printInfo('📋 Starting project design...');
+                conversation.printInfo('');
+                // Resume footer animation before processing message
+                this.footer.resumeAnimation();
+                // Inject design skill and send initial message
+                // Show short message to user, but send full skill prompt to agent
+                await this.processMessage(`I want to design my project and create the backlog.
+
+${designPrompt}
+
+Please start by using todo_write to track the design phases, then begin with Phase 1: Vision. Use the ask_user tool to gather information efficiently.`, {
+                    displayMessage: 'Start the design process for my project.',
+                });
+                return true;
+            }
+            case 'sketch': {
+                // Check if project is initialized
+                const sketchProject = detectCompilrProject();
+                if (!sketchProject.found) {
+                    conversation.printError('No .compilr project found. Run /init first.');
+                    return true;
+                }
+                // Get sketch skill prompt
+                const sketchPrompt = getSkillPrompt('sketch');
+                if (!sketchPrompt) {
+                    conversation.printError('Sketch skill not found.');
+                    return true;
+                }
+                conversation.printInfo('✏️ Starting quick project sketch...');
+                conversation.printInfo('');
+                // Resume footer animation before processing message
+                this.footer.resumeAnimation();
+                // Inject sketch skill and send initial message
+                // Uses ask_user_simple for simpler questions (one at a time)
+                await this.processMessage(`I want to quickly outline my project.
+
+${sketchPrompt}
+
+Please start by asking me about the type of application I'm building using the ask_user_simple tool.`, {
+                    displayMessage: 'Quick project outline.',
+                });
+                return true;
+            }
+            case 'refine': {
+                // Check if project is initialized - use same path detection as /backlog
+                const refineBacklogPath = findBacklogPath();
+                if (!refineBacklogPath) {
+                    conversation.printError('No backlog found. Run /init first to create a project.');
+                    return true;
+                }
+                // Check if backlog has items
+                if (!hasBacklogItems(refineBacklogPath)) {
+                    conversation.printError('No backlog items found. Run /design first to create initial requirements.');
+                    return true;
+                }
+                // Check if a specific item ID was provided (e.g., /refine REQ-001)
+                const itemId = args.trim().toUpperCase();
+                const isFocusedRefine = itemId && /^[A-Z]+-\d{3}$/.test(itemId);
+                // For full refine mode (no item ID), check model tier and warn
+                if (!isFocusedRefine && !modelMeetsTier(this.currentModel, '/refine')) {
+                    const modelTier = getModelTier(this.currentModel);
+                    const choice = await showModelWarningOverlay({
+                        command: '/refine',
+                        currentModel: this.currentModel,
+                        currentTier: modelTier.tier,
+                        suggestedModel: modelTier.suggestedUpgrade,
+                        alternativeCommand: '/refine <ITEM-ID>',
+                    });
+                    switch (choice) {
+                        case 'cancel':
+                            return true;
+                        case 'alternative':
+                            // Show hint about using specific item ID
+                            conversation.printInfo('💡 Tip: Use /refine <ITEM-ID> for focused refinement with smaller models.');
+                            conversation.printInfo('   Example: /refine REQ-001');
+                            conversation.printInfo('');
+                            return true;
+                        case 'switch':
+                            if (modelTier.suggestedUpgrade) {
+                                this.currentModel = modelTier.suggestedUpgrade;
+                                conversation.printSuccess(`Switched to ${this.currentModel}`);
+                            }
+                            break;
+                        case 'continue':
+                            // Continue with current model
+                            break;
+                    }
+                }
+                // Get appropriate skill prompt
+                const skillName = isFocusedRefine ? 'refine-item' : 'refine';
+                const refinePrompt = getSkillPrompt(skillName);
+                if (!refinePrompt) {
+                    conversation.printError(`${skillName} skill not found.`);
+                    return true;
+                }
+                if (isFocusedRefine) {
+                    conversation.printInfo(`🔄 Refining item ${itemId}...`);
+                }
+                else {
+                    conversation.printInfo('🔄 Starting requirements refinement...');
+                }
+                conversation.printInfo('');
+                // Resume footer animation before processing message
+                this.footer.resumeAnimation();
+                // Build message based on mode
+                const userIntent = isFocusedRefine
+                    ? `I want to refine backlog item ${itemId}.`
+                    : 'I want to refine my project requirements.';
+                const agentInstructions = isFocusedRefine
+                    ? `Please use backlog_read with id:"${itemId}" to get the item details, then guide me through refining it.`
+                    : 'Please start by using backlog_read with limit:10 to get an overview, then ask me what I\'d like to focus on using ask_user_simple.';
+                await this.processMessage(`${userIntent}
+
+${refinePrompt}
+
+${agentInstructions}`, {
+                    displayMessage: userIntent,
+                });
+                return true;
+            }
+            case 'arch': {
+                // Check if project is initialized
+                const archProject = detectCompilrProject();
+                if (!archProject.found) {
+                    conversation.printError('No .compilr project found. Run /init first.');
+                    return true;
+                }
+                // Check model tier - /arch requires large models
+                if (!modelMeetsTier(this.currentModel, '/arch')) {
+                    const modelTier = getModelTier(this.currentModel);
+                    const choice = await showModelWarningOverlay({
+                        command: '/arch',
+                        currentModel: this.currentModel,
+                        currentTier: modelTier.tier,
+                        suggestedModel: modelTier.suggestedUpgrade,
+                        // No alternative command for /arch - it's inherently complex
+                    });
+                    switch (choice) {
+                        case 'cancel':
+                            return true;
+                        case 'switch':
+                            if (modelTier.suggestedUpgrade) {
+                                this.currentModel = modelTier.suggestedUpgrade;
+                                conversation.printSuccess(`Switched to ${modelTier.suggestedUpgrade}`);
+                                conversation.printInfo('');
+                            }
+                            else {
+                                conversation.printWarning('No suggested upgrade available. Continuing with current model.');
+                                conversation.printInfo('');
+                            }
+                            break;
+                        case 'continue':
+                            // Proceed with current model
+                            break;
+                    }
+                }
+                // Show type selection overlay
+                const archChoice = await showArchTypeOverlay();
+                if (!archChoice) {
+                    // User cancelled
+                    return true;
+                }
+                // Get architecture skill prompt
+                const archPrompt = getSkillPrompt('architecture');
+                if (!archPrompt) {
+                    conversation.printError('Architecture skill not found.');
+                    return true;
+                }
+                // Build the document type description for display
+                const docTypeLabels = {
+                    'adr': 'Architecture Decision Record',
+                    'diagram': 'System Diagram',
+                    'data-model': 'Data Model',
+                    'api': 'API Design',
+                    'custom': 'Custom Documentation',
+                };
+                const displayType = archChoice.customTopic
+                    ? `Custom: ${archChoice.customTopic}`
+                    : docTypeLabels[archChoice.type];
+                conversation.printInfo(`📐 Creating ${displayType}...`);
+                conversation.printInfo('');
+                // Resume footer animation before processing message
+                this.footer.resumeAnimation();
+                // Replace placeholders in skill prompt
+                const finalPrompt = archPrompt
+                    .replace('{{doc_type}}', archChoice.type)
+                    .replace('{{#if custom_topic}}Custom Topic: {{custom_topic}}{{/if}}', archChoice.customTopic ? `Custom Topic: ${archChoice.customTopic}` : '');
+                await this.processMessage(`I want to create architecture documentation.
+
+${finalPrompt}
+
+Please start by reading any existing PRD.md and using backlog_read to understand the project context. Then use ask_user to gather the information needed for this ${archChoice.type} document.`, {
+                    displayMessage: `Create ${displayType} documentation.`,
+                });
+                return true;
+            }
+            case 'note': {
+                // Check if project is initialized
+                const noteProject = detectCompilrProject();
+                if (!noteProject.found) {
+                    conversation.printError('No .compilr project found. Run /init first.');
+                    return true;
+                }
+                // Get session-notes skill prompt
+                const notePrompt = getSkillPrompt('session-notes');
+                if (!notePrompt) {
+                    conversation.printError('Session-notes skill not found.');
+                    return true;
+                }
+                // Check for optional title argument
+                const noteTitle = args.trim();
+                conversation.printInfo('📝 Creating session note...');
+                conversation.printInfo('');
+                // Resume footer animation before processing message
+                this.footer.resumeAnimation();
+                // Build message based on whether title was provided
+                const titleInstruction = noteTitle
+                    ? `The session title is: "${noteTitle}"`
+                    : 'Please ask me for a title using ask_user_simple, or generate one from the session summary.';
+                await this.processMessage(`I want to create a session note capturing what we've done.
+
+${notePrompt}
+
+${titleInstruction}
+
+Review the conversation context to understand what was accomplished, then create the session note file.`, {
+                    displayMessage: noteTitle
+                        ? `Create session note: "${noteTitle}"`
+                        : 'Create a session note for this session.',
+                });
+                return true;
+            }
+            case 'prd': {
+                // Check if project is initialized
+                const prdProject = detectCompilrProject();
+                if (!prdProject.found) {
+                    conversation.printError('No .compilr project found. Run /init first.');
+                    return true;
+                }
+                // Get prd skill prompt
+                const prdPrompt = getSkillPrompt('prd');
+                if (!prdPrompt) {
+                    conversation.printError('PRD skill not found.');
+                    return true;
+                }
+                // Check for optional section argument
+                const prdSection = args.trim().toLowerCase();
+                const validSections = ['vision', 'scope', 'technical', 'success'];
+                const sectionInstruction = validSections.includes(prdSection)
+                    ? `The user wants to update the "${prdSection}" section specifically.`
+                    : 'Ask the user which section they want to update using ask_user_simple.';
+                conversation.printInfo('📄 Opening PRD for updates...');
+                conversation.printInfo('');
+                // Resume footer animation before processing message
+                this.footer.resumeAnimation();
+                await this.processMessage(`I want to update the Product Requirements Document.
+
+${prdPrompt}
+
+${sectionInstruction}
+
+Start by reading the existing PRD.md file to understand current state.`, {
+                    displayMessage: prdSection
+                        ? `Update PRD: ${prdSection} section`
+                        : 'Update the Product Requirements Document',
+                });
+                return true;
+            }
+            case 'build': {
+                const itemId = args.trim() || undefined;
+                // Handle /build scaffold - redirect to scaffold handler
+                if (itemId?.toLowerCase() === 'scaffold') {
+                    return this.handleScaffoldCommand();
+                }
+                // Check if project is initialized
+                const buildProject = detectCompilrProject();
+                if (!buildProject.found) {
+                    conversation.printError('No .compilr project found. Run /init first.');
+                    return true;
+                }
+                // Read backlog using the shared path detection
+                const buildBacklogPath = findBacklogPath();
+                if (!buildBacklogPath) {
+                    conversation.printError('No backlog found. Run /design or /sketch first.');
+                    return true;
+                }
+                // Parse backlog items
+                let buildItems = [];
+                try {
+                    const backlogContent = fs.readFileSync(buildBacklogPath, 'utf-8');
+                    buildItems = parseBacklogItems(backlogContent);
+                }
+                catch {
+                    conversation.printError('Failed to read backlog file.');
+                    return true;
+                }
+                if (buildItems.length === 0) {
+                    conversation.printError('No backlog items found. Run /design or /sketch first.');
+                    return true;
+                }
+                // Get project path for context
+                const projectPathForBuild = buildProject.projectPath || process.cwd();
+                const projectPathContext = `**IMPORTANT: Project Directory**
+All code files MUST be created in: ${projectPathForBuild}
+Do NOT create files in the current working directory if it differs from the project path.
+`;
+                // Check foundation
+                const foundationExists = hasProjectFoundation();
+                if (!foundationExists) {
+                    // Let agent handle foundation check via skill
+                    conversation.printInfo('🔍 Checking project foundation...');
+                    conversation.printInfo('');
+                    this.footer.resumeAnimation();
+                    await this.processMessage(`I want to build a feature from the backlog, but first check if the project has a foundation.
+
+${projectPathContext}
+
+Use detect_project to check the current state. If there's no code foundation (no src/, no package.json or equivalent), use ask_user_simple to ask:
+"No project foundation detected. Would you like to:"
+- "Create scaffold first (recommended)"
+- "Proceed with feature anyway"
+- "Cancel"
+
+If user chooses scaffold, read COMPILR.md and PRD.md for tech stack info, then create the project scaffold following these guidelines:
+
+${getSkillPrompt('scaffold') ?? ''}
+
+After scaffold is done (or if user chose to proceed anyway), continue with building the feature.`, { displayMessage: 'Check project foundation before building.' });
+                    return true;
+                }
+                // Select item
+                const item = selectBuildItem(buildItems, itemId);
+                if (!item) {
+                    if (itemId) {
+                        const existingItem = buildItems.find(i => i.id.toUpperCase() === itemId.toUpperCase());
+                        if (existingItem) {
+                            conversation.printError(`Item ${itemId} is already ${existingItem.status === '✅' ? 'completed' : 'in progress'}.`);
+                        }
+                        else {
+                            conversation.printError(`Item ${itemId} not found in backlog.`);
+                        }
+                    }
+                    else {
+                        conversation.printInfo('No pending items in backlog. All done! 🎉');
+                    }
+                    return true;
+                }
+                // Check dependencies
+                const unmetDeps = getUnmetDependencies(item, buildItems);
+                const depsWarning = unmetDeps.length > 0
+                    ? `\n\n**⚠️ UNMET DEPENDENCIES:**\n${unmetDeps.map(d => `- ${d.id}: ${d.title} (${d.status})`).join('\n')}\n\nThese items are not yet completed. Ask user to confirm before proceeding.`
+                    : '';
+                // Get build skill prompt and replace placeholders
+                const buildPromptTemplate = getSkillPrompt('build');
+                if (!buildPromptTemplate) {
+                    conversation.printError('Build skill not found.');
+                    return true;
+                }
+                const buildPrompt = buildPromptTemplate
+                    .replace(/\{\{item_id\}\}/g, item.id)
+                    .replace(/\{\{item_title\}\}/g, item.title)
+                    .replace(/\{\{item_description\}\}/g, item.description)
+                    .replace(/\{\{item_type\}\}/g, item.type)
+                    .replace(/\{\{item_priority\}\}/g, item.priority);
+                conversation.printInfo(`🔨 Building ${item.id}: ${item.title}`);
+                conversation.printInfo('');
+                this.footer.resumeAnimation();
+                await this.processMessage(`I want to implement backlog item ${item.id}.
+
+${projectPathContext}
+
+${buildPrompt}${depsWarning}`, { displayMessage: `Build ${item.id}: ${item.title}` });
+                return true;
+            }
+            case 'scaffold': {
+                return this.handleScaffoldCommand();
+            }
+            case 'tutorial': {
+                await showTutorialOverlay();
+                return true;
+            }
+            default:
+                // This shouldn't happen if resolveCommand works correctly
+                conversation.printWarning(`Unknown command: /${command}`);
+                return true;
+        }
+    }
+    /**
+     * Handle /scaffold command (shared between /scaffold and /build scaffold)
+     */
+    async handleScaffoldCommand() {
+        // Check if project is initialized
+        const scaffoldProject = detectCompilrProject();
+        if (!scaffoldProject.found) {
+            conversation.printError('No .compilr project found. Run /init first.');
+            return true;
+        }
+        // Get project path for context
+        const projectPathForScaffold = scaffoldProject.projectPath || process.cwd();
+        const scaffoldPathContext = `**IMPORTANT: Project Directory**
+All code files MUST be created in: ${projectPathForScaffold}
+Do NOT create files in the current working directory if it differs from the project path.
+`;
+        // Check if foundation already exists
+        const foundationExists = hasProjectFoundation();
+        if (foundationExists) {
+            // Let agent confirm with user
+            conversation.printInfo('🔍 Project files detected...');
+            conversation.printInfo('');
+            this.footer.resumeAnimation();
+            await this.processMessage(`User wants to create a project scaffold, but a foundation may already exist.
+
+${scaffoldPathContext}
+
+Use detect_project to analyze the current state. Then use ask_user_simple:
+"Project files already exist. What would you like to do?"
+- "Continue anyway (may overwrite)"
+- "Cancel"
+
+If continuing, read COMPILR.md and PRD.md for tech stack info, then create the scaffold:
+
+${getSkillPrompt('scaffold') ?? ''}`, { displayMessage: 'Create project scaffold (foundation exists).' });
+            return true;
+        }
+        // Get scaffold skill prompt
+        const scaffoldPrompt = getSkillPrompt('scaffold');
+        if (!scaffoldPrompt) {
+            conversation.printError('Scaffold skill not found.');
+            return true;
+        }
+        conversation.printInfo('🏗️ Creating project scaffold...');
+        conversation.printInfo('');
+        this.footer.resumeAnimation();
+        await this.processMessage(`I want to create the project scaffold (foundation).
+
+${scaffoldPathContext}
+
+${scaffoldPrompt}
+
+Read COMPILR.md and PRD.md first to understand the tech stack, then create the appropriate scaffold.`, { displayMessage: 'Create project scaffold.' });
+        return true;
+    }
+    // ===========================================================================
+    // Message Processing
+    // ===========================================================================
+    /**
+     * Strip '@' prefix from @path mentions before sending to agent
+     * The '@' is UI syntax for path autocomplete, not part of the actual path
+     * Only strips @ when it's at start of a word (not in middle like email@domain.com)
+     */
+    stripAtMentions(input) {
+        // Match @ at start of string or after whitespace, followed by non-whitespace
+        return input.replace(/(^|\s)@(\S+)/g, '$1$2');
+    }
+    /**
+     * Process a message to the agent
+     * @param input - The full message to send to the agent
+     * @param options - Optional settings
+     * @param options.displayMessage - What to show the user (defaults to input)
+     * @param options.skipPlanModeCheck - Skip plan mode handling (for /design, /refine)
+     */
+    async processMessage(input, options) {
+        // Print user message to conversation (show displayMessage or original)
+        this.footer.clearForOutput();
+        conversation.printUserMessage(options?.displayMessage ?? input);
+        this.footer.forceRender();
+        // Strip @ prefix from path mentions before sending to agent
+        const cleanedInput = this.stripAtMentions(input);
+        // Check current mode (unless skipped for skill-based commands)
+        const mode = this.footer.getMode();
+        // Plan mode - placeholder for now (skip for /design, /refine which handle their own flow)
+        if (mode === 'plan' && !options?.skipPlanModeCheck) {
+            this.footer.clearForOutput();
+            conversation.printInfo('📋 Plan Mode (coming soon)');
+            conversation.printInfo('In plan mode, the agent will analyze your request and create');
+            conversation.printInfo('a detailed execution plan without performing any actions.');
+            conversation.printInfo('');
+            conversation.printInfo('For now, switch to Normal or Auto-accept mode with Shift+Tab.');
+            terminal.writeLine('');
+            this.footer.forceRender();
+            return;
+        }
+        // Get all tool names and filter based on intent (use cleaned input)
+        const allToolNames = this.agent.getToolDefinitions().map((t) => t.name);
+        const selectedNames = selectToolNamesByIntent(cleanedInput, allToolNames);
+        // Show filtering analysis if enabled
+        if (this.showFiltering) {
+            const saved = allToolNames.length - selectedNames.length;
+            const pct = Math.round((saved / allToolNames.length) * 100);
+            this.footer.clearForOutput();
+            conversation.printInfo(`[Tool Filtering] ${String(selectedNames.length)}/${String(allToolNames.length)} tools, ~${String(pct)}% reduction`);
+            this.footer.forceRender();
+        }
+        // Start agent running state
+        this.agentRunning = true;
+        setAgentRunning(this.state, true);
+        this.footer.setAgentRunning(true);
+        this.abortController = new AbortController();
+        let totalInputTokens = 0;
+        let totalOutputTokens = 0;
+        let llmCalls = 0;
+        let hasTextOutput = false;
+        let usedTools = false;
+        let lastToolInput = null;
+        // Event-based rendering: accumulate text, render complete blocks
+        let textAccumulator = '';
+        debug('processMessage', 'Starting agent stream', {
+            inputLength: cleanedInput.length,
+            toolCount: selectedNames.length,
+            model: this.currentModel,
+        });
+        try {
+            for await (const event of this.agent.stream(cleanedInput, {
+                toolFilter: selectedNames,
+                signal: this.abortController.signal,
+                chatOptions: { model: this.currentModel },
+            })) {
+                debug('processMessage', `Event received: ${event.type}`, event);
+                // Check if aborted
+                if (this.abortController.signal.aborted) {
+                    debug('processMessage', 'Aborted');
+                    break;
+                }
+                if (event.type === 'llm_chunk') {
+                    if (event.chunk.type === 'text' && event.chunk.text) {
+                        // Event-based rendering: accumulate text until tool_start or stream end
+                        // This allows complete code blocks to be rendered with syntax highlighting
+                        textAccumulator += event.chunk.text;
+                        hasTextOutput = true;
+                    }
+                    else if (event.chunk.type === 'done' && event.chunk.usage) {
+                        const tokens = event.chunk.usage.inputTokens + event.chunk.usage.outputTokens;
+                        this.footer.addTokens(tokens);
+                        totalInputTokens += event.chunk.usage.inputTokens;
+                        totalOutputTokens += event.chunk.usage.outputTokens;
+                        llmCalls++;
+                    }
+                }
+                else if (event.type === 'tool_start') {
+                    // Event-based rendering: flush accumulated text before tool output
+                    // Exception: For ask_user/ask_user_simple tools, we'll buffer the text and print after overlay closes
+                    // to avoid the text interfering with the overlay rendering
+                    // Also skip if an overlay is currently active (e.g., permission overlay)
+                    const isAskUserTool = event.name === 'ask_user' || event.name === 'ask_user_simple';
+                    const shouldBuffer = isAskUserTool || isOverlayActive();
+                    if (textAccumulator.trim() && !shouldBuffer) {
+                        this.footer.clearForOutput();
+                        conversation.printAssistantResponse(textAccumulator.trim());
+                        terminal.writeLine('');
+                        this.footer.forceRender();
+                        textAccumulator = '';
+                    }
+                    usedTools = true;
+                    lastToolInput = event.input;
+                    // Show tool in spinner (but not silent tools)
+                    if (event.name !== 'todo_read' && event.name !== 'todo_write' && event.name !== 'suggest') {
+                        // For task tool, show subagent type
+                        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                        if (event.name === 'task' && event.input) {
+                            const inputObj = event.input;
+                            const subagentType = typeof inputObj.subagent_type === 'string' ? inputObj.subagent_type : 'general';
+                            const description = typeof inputObj.description === 'string' ? inputObj.description : '';
+                            this.footer.setCurrentTool(`task(${subagentType}): ${description}`);
+                        }
+                        else {
+                            this.footer.setCurrentTool(event.name);
+                        }
+                    }
+                    // Note: Diff is shown in the permission handler (index.ts) BEFORE the prompt
+                }
+                else if (event.type === 'tool_end') {
+                    const toolName = event.name;
+                    const toolInput = lastToolInput;
+                    const result = event.result;
+                    lastToolInput = null;
+                    // Handle todo_write - update state and render
+                    if (toolName === 'todo_write' && toolInput && Array.isArray(toolInput.todos)) {
+                        const todos = toolInput.todos.map((t) => {
+                            const content = typeof t.content === 'string' ? t.content :
+                                typeof t.title === 'string' ? t.title :
+                                    typeof t.task === 'string' ? t.task :
+                                        typeof t.description === 'string' ? t.description :
+                                            typeof t.text === 'string' ? t.text : 'Untitled task';
+                            const status = (typeof t.status === 'string' && ['pending', 'in_progress', 'completed'].includes(t.status)
+                                ? t.status
+                                : 'pending');
+                            const activeForm = typeof t.activeForm === 'string' ? t.activeForm : undefined;
+                            return { content, status, activeForm };
+                        });
+                        updateTodos(this.state, todos);
+                        this.footer.setTodos(todos);
+                        this.footer.setCurrentTool(null);
+                        continue;
+                    }
+                    // Skip todo_read display
+                    if (toolName === 'todo_read') {
+                        this.footer.setCurrentTool(null);
+                        continue;
+                    }
+                    // Skip suggest tool display (suggestion is shown in input prompt)
+                    if (toolName === 'suggest') {
+                        this.footer.setCurrentTool(null);
+                        this.footer.forceRender();
+                        continue;
+                    }
+                    // Handle ask_user/ask_user_simple tools - print buffered text now that overlay is done
+                    if (toolName === 'ask_user' || toolName === 'ask_user_simple') {
+                        // Print any accumulated text that was buffered before the overlay
+                        if (textAccumulator.trim()) {
+                            this.footer.clearForOutput();
+                            conversation.printAssistantResponse(textAccumulator.trim());
+                            terminal.writeLine('');
+                            textAccumulator = '';
+                        }
+                        this.footer.setCurrentTool(null);
+                        this.footer.forceRender();
+                        continue;
+                    }
+                    // Clear footer for output
+                    this.footer.clearForOutput();
+                    // Handle edit tool - diff was already shown on tool_start
+                    if (toolName === 'edit') {
+                        // Just clear the tool indicator, diff was shown before permission prompt
+                        this.footer.setCurrentTool(null);
+                        this.footer.forceRender();
+                        continue;
+                    }
+                    // Handle task tool (subagent) - show subagent info
+                    if (toolName === 'task' && toolInput) {
+                        const subagentType = typeof toolInput.subagent_type === 'string' ? toolInput.subagent_type : 'general';
+                        const description = typeof toolInput.description === 'string' ? toolInput.description : '';
+                        // Format result summary for subagent
+                        let resultSummary = '';
+                        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                        if (result && typeof result === 'object') {
+                            const resultObj = result;
+                            if (resultObj.error) {
+                                const errorObj = resultObj.error;
+                                const errorMsg = typeof errorObj.message === 'string' ? errorObj.message : JSON.stringify(resultObj.error);
+                                resultSummary = pc.red(`Error: ${errorMsg.slice(0, 60)}`);
+                            }
+                            else if (resultObj.result && typeof resultObj.result === 'object') {
+                                const r = resultObj.result;
+                                const iterations = typeof r.iterations === 'number' ? r.iterations : 1;
+                                // Try to get a summary from the result
+                                if (typeof r.result === 'string') {
+                                    const preview = r.result.slice(0, 60);
+                                    resultSummary = pc.dim(`${String(iterations)} iteration(s) - ${preview}${r.result.length > 60 ? '...' : ''}`);
+                                }
+                                else {
+                                    resultSummary = pc.dim(`${String(iterations)} iteration(s)`);
+                                }
+                            }
+                        }
+                        // Print as "task(explore): Search for files" format
+                        conversation.printToolExecution(`task(${pc.cyan(subagentType)})`, description, resultSummary);
+                        this.footer.setCurrentTool(null);
+                        this.footer.forceRender();
+                        continue;
+                    }
+                    // Build argument summary for other tools
+                    let argSummary = '';
+                    if (toolInput) {
+                        const path = toolInput.path ?? toolInput.file_path ?? toolInput.filePath;
+                        const command = toolInput.command;
+                        const pattern = toolInput.pattern;
+                        if (typeof path === 'string') {
+                            argSummary = path.split('/').pop() ?? path;
+                        }
+                        else if (typeof command === 'string') {
+                            argSummary = command.length > 40 ? command.slice(0, 40) + '...' : command;
+                        }
+                        else if (typeof pattern === 'string') {
+                            argSummary = pattern;
+                        }
+                    }
+                    // Format result summary
+                    let resultSummary = '';
+                    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                    if (result && typeof result === 'object') {
+                        const resultObj = result;
+                        if (resultObj.error) {
+                            const errorObj = resultObj.error;
+                            const errorMsg = typeof errorObj.message === 'string' ? errorObj.message : JSON.stringify(resultObj.error);
+                            resultSummary = pc.red(`Error: ${errorMsg.slice(0, 60)}`);
+                        }
+                        else if (resultObj.result !== undefined) {
+                            resultSummary = conversation.formatToolResult(resultObj.result);
+                        }
+                    }
+                    // Print tool log
+                    conversation.printToolExecution(toolName, argSummary, resultSummary);
+                    // Re-render footer after output
+                    this.footer.setCurrentTool(null);
+                    this.footer.forceRender();
+                }
+            }
+            debug('processMessage', 'Stream completed', {
+                hasTextOutput,
+                usedTools,
+                totalInputTokens,
+                totalOutputTokens,
+                llmCalls,
+                textAccumulatorLength: textAccumulator.length,
+            });
+            // Skip stats if aborted
+            if (this.abortController.signal.aborted) {
+                this.agentRunning = false;
+                setAgentRunning(this.state, false);
+                this.footer.setAgentRunning(false);
+                this.abortController = null;
+                return;
+            }
+            // Event-based rendering: flush any remaining accumulated text
+            if (textAccumulator.trim()) {
+                this.footer.clearForOutput();
+                conversation.printAssistantResponse(textAccumulator.trim());
+                terminal.writeLine('');
+                textAccumulator = '';
+            }
+            // Warn if tools used but no text
+            if (usedTools && !hasTextOutput) {
+                this.footer.clearForOutput();
+                conversation.printWarning('No text response from model - try a more capable model');
+            }
+            // Update session stats
+            this.sessionInputTokens += totalInputTokens;
+            this.sessionOutputTokens += totalOutputTokens;
+            this.sessionRequests++;
+            // Show token usage
+            if (totalInputTokens > 0 || totalOutputTokens > 0) {
+                this.footer.clearForOutput();
+                const total = totalInputTokens + totalOutputTokens;
+                const sessionTotal = this.sessionInputTokens + this.sessionOutputTokens;
+                conversation.printInfo(`[Tokens: ${total.toLocaleString()} (${totalInputTokens.toLocaleString()} in / ${totalOutputTokens.toLocaleString()} out) - ${String(llmCalls)} LLM call(s)]`);
+                conversation.printInfo(`[Session: ${sessionTotal.toLocaleString()} total (${String(this.sessionRequests)} requests)]`);
+                terminal.writeLine('');
+            }
+            // Stop spinner and re-render footer (AFTER all output is printed)
+            this.agentRunning = false;
+            setAgentRunning(this.state, false);
+            this.footer.setAgentRunning(false);
+        }
+        catch (error) {
+            debugError('processMessage', error);
+            if (error.name !== 'AbortError') {
+                this.footer.clearForOutput();
+                conversation.printError(error.message);
+                this.footer.forceRender();
+            }
+        }
+        finally {
+            // Ensure agent is stopped even on error
+            this.agentRunning = false;
+            setAgentRunning(this.state, false);
+            this.footer.setAgentRunning(false);
+            this.abortController = null;
+            // Notify that agent has finished (for applying deferred suggestions)
+            this.onAgentFinish?.();
+        }
+    }
+    // ===========================================================================
+    // Helper Commands
+    // ===========================================================================
+    async handleCompact() {
+        const contextManager = this.agent.getContextManager();
+        if (!contextManager) {
+            conversation.printWarning('Context manager not available');
+            return;
+        }
+        const history = this.agent.getHistory();
+        if (history.length === 0) {
+            conversation.printInfo('No conversation history to compact');
+            return;
+        }
+        const stats = contextManager.getStats(history.length);
+        this.footer.clearForOutput();
+        conversation.printInfo(`Current: ${stats.currentTokens.toLocaleString()} tokens, ${String(history.length)} messages`);
+        const confirmed = await overlays.showConfirmation('Compact conversation history?');
+        if (!confirmed) {
+            this.footer.forceRender();
+            return;
+        }
+        // Show spinner during compaction
+        this.footer.setSpinnerText('Compacting context');
+        setAgentRunning(this.state, true);
+        this.footer.setAgentRunning(true);
+        this.footer.forceRender(); // Render immediately before blocking operation
+        try {
+            // Use the agent's compact() method - handles summarization, tool pairing, and hints
+            const result = (await this.agent.compact());
+            // Stop spinner and clear for output
+            setAgentRunning(this.state, false);
+            this.footer.setAgentRunning(false);
+            this.footer.setSpinnerText(null);
+            this.footer.clearForOutput();
+            if (!result.success) {
+                conversation.printWarning('Compaction not available (no context manager)');
+                this.footer.forceRender();
+                return;
+            }
+            // Build status message
+            const newHistory = this.agent.getHistory();
+            const statusParts = [
+                `Compacted: ${String(result.originalTokens ?? 0).replace(/\B(?=(\d{3})+(?!\d))/g, ',')} → ${String(result.summaryTokens ?? 0).replace(/\B(?=(\d{3})+(?!\d))/g, ',')} tokens`,
+                `(${String(history.length)} → ${String(newHistory.length)} messages, ${String(result.messagesPreserved ?? 0)} preserved)`,
+            ];
+            // Add smart compaction category info
+            if (result.categoryStats) {
+                const actions = [];
+                if (result.categoryStats.toolResults.action === 'compacted') {
+                    actions.push('tool results → files');
+                }
+                if (result.categoryStats.history.action === 'summarized') {
+                    actions.push('history → summary');
+                }
+                if (actions.length > 0) {
+                    statusParts.push(`[${actions.join(', ')}]`);
+                }
+            }
+            // Add files created info
+            if (result.filesCreated && result.filesCreated.length > 0) {
+                statusParts.push(`[${String(result.filesCreated.length)} file(s) created]`);
+            }
+            // Add file tracking info
+            if (result.restorationHintsInjected) {
+                const fileTracker = this.agent.getFileTracker();
+                const trackerStats = fileTracker?.getStats();
+                const filesTracked = trackerStats ? trackerStats.total : 0;
+                statusParts.push(`[${String(filesTracked)} files tracked]`);
+            }
+            // Add repair info if tool_results were fixed
+            if (result.toolResultsRepaired && result.toolResultsRepaired > 0) {
+                statusParts.push(`[${String(result.toolResultsRepaired)} orphaned tool results removed]`);
+            }
+            conversation.printSuccess(statusParts.join(' '));
+        }
+        catch (error) {
+            // Stop spinner on error too
+            setAgentRunning(this.state, false);
+            this.footer.setAgentRunning(false);
+            this.footer.setSpinnerText(null);
+            this.footer.clearForOutput();
+            conversation.printError(`Compaction failed: ${error.message}`);
+        }
+        this.footer.forceRender();
+    }
+    async showTools() {
+        const tools = this.agent.getToolDefinitions().map((t) => {
+            // Extract parameters from inputSchema
+            const parameters = [];
+            const props = t.inputSchema.properties;
+            const required = t.inputSchema.required ?? [];
+            for (const [name, schema] of Object.entries(props)) {
+                parameters.push({
+                    name,
+                    type: schema.type ?? 'unknown',
+                    description: schema.description,
+                    required: required.includes(name),
+                });
+            }
+            // Look up permission info
+            const permissionInfo = getToolPermissionInfo(t.name);
+            const permission = permissionInfo
+                ? { level: permissionInfo.level, description: permissionInfo.description }
+                : undefined;
+            // For task tool, extract just the intro (before verbose agent types list)
+            let description = t.description;
+            if (t.name === 'task' && description.includes('Available agent types:')) {
+                description = description.split('Available agent types:')[0].trim();
+            }
+            return {
+                name: t.name,
+                description,
+                parameters,
+                permission,
+            };
+        });
+        // Pause footer during overlay
+        this.footer.pauseAnimation();
+        try {
+            await showToolsOverlay(tools);
+        }
+        finally {
+            this.footer.resumeAnimation();
+            this.footer.forceRender();
+        }
+    }
+    showTokens() {
+        this.footer.clearForOutput();
+        overlays.showTokenUsage({
+            inputTokens: this.sessionInputTokens,
+            outputTokens: this.sessionOutputTokens,
+            totalTokens: this.sessionInputTokens + this.sessionOutputTokens,
+        });
+        this.footer.forceRender();
+    }
+    showContext() {
+        const contextManager = this.agent.getContextManager();
+        const history = this.agent.getHistory();
+        this.footer.clearForOutput();
+        if (contextManager) {
+            const stats = contextManager.getStats(history.length);
+            overlays.showContextStats({
+                tokens: stats.currentTokens,
+                maxTokens: stats.maxTokens,
+                messages: stats.messageCount,
+                turns: stats.turnCount,
+                utilization: stats.utilization,
+            });
+        }
+        else {
+            // Fallback to session tracking
+            overlays.showContextStats({
+                tokens: this.sessionInputTokens + this.sessionOutputTokens,
+                maxTokens: 200000,
+                messages: history.length,
+                turns: Math.floor(history.filter((m) => m.role === 'user').length),
+                utilization: (this.sessionInputTokens + this.sessionOutputTokens) / 200000,
+            });
+        }
+        this.footer.forceRender();
+    }
+    showStatus() {
+        const contextManager = this.agent.getContextManager();
+        const history = this.agent.getHistory();
+        const mode = this.footer.getMode();
+        const modeInfo = MODE_INFO[mode];
+        this.footer.clearForOutput();
+        terminal.writeLine('');
+        terminal.writeLine(pc.bold('Status'));
+        terminal.writeLine(pc.dim('─'.repeat(40)));
+        terminal.writeLine(`  Version:  ${pc.cyan(this.version)}`);
+        terminal.writeLine(`  Model:    ${pc.cyan(this.model)}`);
+        terminal.writeLine(`  Mode:     ${pc.cyan(modeInfo.label)}`);
+        if (contextManager) {
+            const stats = contextManager.getStats(history.length);
+            const pct = (stats.utilization * 100).toFixed(1);
+            const bar = this.renderProgressBar(stats.utilization, 20);
+            terminal.writeLine(`  Context:  ${bar} ${pct}%`);
+            terminal.writeLine(`  Messages: ${pc.cyan(String(stats.messageCount))}`);
+        }
+        else {
+            const total = this.sessionInputTokens + this.sessionOutputTokens;
+            terminal.writeLine(`  Tokens:   ${pc.cyan(total.toLocaleString())}`);
+            terminal.writeLine(`  Messages: ${pc.cyan(String(history.length))}`);
+        }
+        terminal.writeLine(`  Requests: ${pc.cyan(String(this.sessionRequests))}`);
+        terminal.writeLine('');
+        this.footer.forceRender();
+    }
+    renderProgressBar(ratio, width) {
+        const filled = Math.round(ratio * width);
+        const empty = width - filled;
+        const color = ratio > 0.9 ? pc.red : ratio > 0.7 ? pc.yellow : pc.green;
+        return color('█'.repeat(filled)) + pc.dim('░'.repeat(empty));
+    }
+    showTodos() {
+        const todos = this.state.todos;
+        this.footer.clearForOutput();
+        terminal.writeLine('');
+        if (todos.length === 0) {
+            terminal.writeLine(pc.dim('No todos. The agent will create todos when working on tasks.'));
+            terminal.writeLine('');
+            this.footer.forceRender();
+            return;
+        }
+        terminal.writeLine(pc.bold('Todos'));
+        terminal.writeLine(pc.dim('─'.repeat(40)));
+        for (const todo of todos) {
+            let icon;
+            let style;
+            switch (todo.status) {
+                case 'completed':
+                    icon = pc.green('✓');
+                    style = pc.strikethrough;
+                    break;
+                case 'in_progress':
+                    icon = pc.yellow('●');
+                    style = pc.bold;
+                    break;
+                default:
+                    icon = pc.dim('○');
+                    style = (s) => s;
+            }
+            terminal.writeLine(`  ${icon} ${style(todo.content)}`);
+        }
+        terminal.writeLine('');
+        this.footer.forceRender();
+    }
+    async handleExport(args) {
+        const history = this.agent.getHistory();
+        if (history.length === 0) {
+            this.footer.clearForOutput();
+            conversation.printWarning('No conversation to export');
+            this.footer.forceRender();
+            return;
+        }
+        // Format conversation as markdown
+        const markdown = this.formatConversationAsMarkdown(history);
+        if (args.trim()) {
+            // Export to file
+            const filename = args.trim();
+            const filepath = path.isAbsolute(filename) ? filename : path.join(process.cwd(), filename);
+            try {
+                fs.writeFileSync(filepath, markdown, 'utf-8');
+                this.footer.clearForOutput();
+                conversation.printSuccess(`Exported to ${filepath}`);
+                this.footer.forceRender();
+            }
+            catch (error) {
+                this.footer.clearForOutput();
+                conversation.printError(`Failed to export: ${error.message}`);
+                this.footer.forceRender();
+            }
+        }
+        else {
+            // Export to clipboard
+            try {
+                await this.copyToClipboard(markdown);
+                this.footer.clearForOutput();
+                conversation.printSuccess(`Copied ${String(history.length)} messages to clipboard`);
+                this.footer.forceRender();
+            }
+            catch (error) {
+                this.footer.clearForOutput();
+                conversation.printError(`Failed to copy to clipboard: ${error.message}`);
+                this.footer.forceRender();
+            }
+        }
+    }
+    formatConversationAsMarkdown(history) {
+        const lines = [];
+        const timestamp = new Date().toISOString().split('T')[0];
+        lines.push(`# Conversation Export`);
+        lines.push('');
+        lines.push(`**Model:** ${this.model}`);
+        lines.push(`**Date:** ${timestamp}`);
+        lines.push(`**Messages:** ${String(history.length)}`);
+        lines.push('');
+        lines.push('---');
+        lines.push('');
+        for (const msg of history) {
+            const role = msg.role === 'user' ? '👤 User' : '🤖 Assistant';
+            lines.push(`## ${role}`);
+            lines.push('');
+            if (typeof msg.content === 'string') {
+                lines.push(msg.content);
+            }
+            else if (Array.isArray(msg.content)) {
+                // Handle content blocks (tool calls, etc.)
+                for (const block of msg.content) {
+                    if (typeof block === 'object' && block !== null) {
+                        const b = block;
+                        if (b.type === 'text' && typeof b.text === 'string') {
+                            lines.push(b.text);
+                        }
+                        else if (b.type === 'tool_use') {
+                            const toolName = typeof b.name === 'string' ? b.name : String(b.name);
+                            lines.push(`**Tool:** \`${toolName}\``);
+                            lines.push('```json');
+                            lines.push(JSON.stringify(b.input, null, 2));
+                            lines.push('```');
+                        }
+                        else if (b.type === 'tool_result') {
+                            lines.push(`**Tool Result:**`);
+                            const content = typeof b.content === 'string' ? b.content : JSON.stringify(b.content);
+                            if (content.length > 500) {
+                                lines.push('```');
+                                lines.push(content.slice(0, 500) + '...[truncated]');
+                                lines.push('```');
+                            }
+                            else {
+                                lines.push('```');
+                                lines.push(content);
+                                lines.push('```');
+                            }
+                        }
+                    }
+                }
+            }
+            else {
+                lines.push(JSON.stringify(msg.content, null, 2));
+            }
+            lines.push('');
+            lines.push('---');
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    async copyToClipboard(text) {
+        const platform = process.platform;
+        let command;
+        if (platform === 'darwin') {
+            command = 'pbcopy';
+        }
+        else if (platform === 'linux') {
+            // Try xclip first, fall back to xsel
+            command = 'xclip -selection clipboard';
+        }
+        else if (platform === 'win32') {
+            command = 'clip';
+        }
+        else {
+            throw new Error(`Unsupported platform: ${platform}`);
+        }
+        const child = exec(command);
+        if (child.stdin) {
+            child.stdin.write(text);
+            child.stdin.end();
+        }
+        await new Promise((resolve, reject) => {
+            child.on('exit', (code) => {
+                if (code === 0) {
+                    resolve();
+                }
+                else {
+                    reject(new Error(`Clipboard command exited with code ${String(code ?? 'unknown')}`));
+                }
+            });
+            child.on('error', reject);
+        });
+    }
+}