@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/repl.js

@@ -10,320 +10,34 @@
  * - 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 { debugLog } from './utils/debug-log.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 { TerminalRenderer, RenderMode } from './ui/terminal-renderer.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';
+// Note: All overlay imports (showConfigOverlay, showModelOverlay, showThemeOverlay, showMascotOverlay, etc.)
+// are now handled by command handlers in ./commands/handlers/
 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 { getCustomCommandRegistry, commandRegistry, registerAllHandlers } 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';
+// Note: findBacklogPath, parseBacklogItems moved to command handlers
 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;
-}
+import { getActiveProject } from './tools/project-db.js';
+import { getAnchorManager } from './anchors/index.js';
+import { isMemoryInput, handleMemoryInput } from './input-handlers/index.js';
+// Helper functions extracted to reduce file size
+import { selectToolNamesByIntent } from './repl-helpers.js';
 // =============================================================================
 // REPL Class
 // =============================================================================
@@ -336,19 +50,25 @@ export class REPL {
     showFiltering;
     onModeChange;
     onAgentFinish;
+    clearSubagentTracking;
     startTime;
+    initialCommand;
     state;
     footer;
+    renderer;
     // Session stats
     sessionInputTokens = 0;
     sessionOutputTokens = 0;
     sessionRequests = 0;
     // Running state
     isRunning = false;
+    shouldReturnToMenu = false;
     agentRunning = false;
     abortController = null;
     // Promise for waiting on REPL exit
     exitResolve = null;
+    // Text buffer flush function (set during processMessage, allows permission handler to flush)
+    textBufferFlusher = null;
     constructor(options) {
         this.agent = options.agent;
         this.model = options.model;
@@ -358,7 +78,9 @@ export class REPL {
         this.showFiltering = options.showFiltering ?? false;
         this.onModeChange = options.onModeChange;
         this.onAgentFinish = options.onAgentFinish;
+        this.clearSubagentTracking = options.clearSubagentTracking;
         this.startTime = new Date();
+        this.initialCommand = options.initialCommand;
         this.state = createInitialState(this.model);
         // Map permission mode setting to AgentMode
         const permissionMode = getPermissionMode();
@@ -368,6 +90,19 @@ export class REPL {
             showSeparators: true,
             initialMode,
         });
+        // Initialize TerminalRenderer in REPL mode
+        // TODO: Scroll regions disabled until incremental rebuild is complete
+        this.renderer = new TerminalRenderer({
+            initialMode: RenderMode.REPL,
+            useScrollRegions: false, // DISABLED: Use legacy mode for now
+            debug: false,
+        });
+        // Connect footer to renderer (enables external renderer mode on footer)
+        this.renderer.setFooter(this.footer);
+        // Connect conversation output to renderer
+        conversation.setRenderer(this.renderer);
+        // Note: renderer.start() is called in run(), not here
+        // This ensures proper startup sequence: footer.start() → renderer.start() → printWelcome()
         // Notify external state handler of initial mode
         if (this.onModeChange && initialMode !== 'normal') {
             this.onModeChange(initialMode);
@@ -378,8 +113,60 @@ export class REPL {
         if (options.onFooterReady) {
             options.onFooterReady(() => { this.footer.pauseAnimation(); }, () => { this.footer.resumeAnimation(); }, (action) => { this.footer.setSuggestion(action); });
         }
+        // Provide text buffer flush function (for permission handler to flush before overlay)
+        if (options.onTextBufferReady) {
+            options.onTextBufferReady(() => {
+                if (this.textBufferFlusher) {
+                    this.textBufferFlusher();
+                }
+            });
+        }
+        // Provide subagent tracking callbacks (for agent to report subagent activity)
+        if (options.onSubagentReady) {
+            options.onSubagentReady({
+                onStart: (agentId, agentType, description) => {
+                    this.footer.onSubagentStart(agentId, agentType, description);
+                },
+                onToolUse: (agentId, toolName, summary) => {
+                    this.footer.onSubagentToolUse(agentId, toolName, summary);
+                },
+                onEnd: (agentId, success, tokenCount, error) => {
+                    this.footer.onSubagentEnd(agentId, success, tokenCount, error);
+                },
+            });
+        }
         // Register footer callbacks for overlay controller (used by tools like ask_user)
         registerFooterCallbacks(() => { this.footer.pauseAnimation(); }, () => { this.footer.resumeAnimation(); });
+        // Register all command handlers (idempotent - safe to call multiple times)
+        registerAllHandlers();
+    }
+    /**
+     * Reload project-specific anchors when switching projects
+     * Clears old project anchors and loads new project anchors
+     */
+    reloadProjectAnchors(oldProjectId, newProjectId) {
+        // Clear old project anchors (if any)
+        if (oldProjectId) {
+            const clearedCount = this.agent.clearAnchors({ projectId: oldProjectId });
+            debug('anchors', `Cleared ${String(clearedCount)} anchors for project ${oldProjectId}`);
+        }
+        // Load new project anchors from disk
+        const newProjectAnchors = getAnchorManager(newProjectId).getAll({ scope: 'persistent' });
+        debug('anchors', `Loading ${String(newProjectAnchors.length)} anchors for project ${newProjectId}`);
+        // Add new project anchors to the agent
+        for (const anchor of newProjectAnchors) {
+            this.agent.addAnchor({
+                id: anchor.id,
+                content: anchor.content,
+                priority: anchor.priority,
+                scope: anchor.scope,
+                tags: anchor.tags,
+                projectId: newProjectId,
+            });
+        }
+        if (newProjectAnchors.length > 0) {
+            conversation.printInfo(`  Anchors: ${String(newProjectAnchors.length)} loaded for project`);
+        }
     }
     /**
      * Set up Footer event handlers
@@ -394,16 +181,24 @@ export class REPL {
         });
         // Handle slash commands
         this.footer.on('command', (command, args) => {
-            // Pause animation for overlays
-            this.footer.pauseAnimation();
+            debugLog('REPL:command', `received /${command}`);
+            // NOTE: Don't pause footer here - let overlays pause when ready to render
+            // This prevents blank screen flash when overlays have slow constructors
             void this.handleCommand(command, args).then((shouldContinue) => {
-                this.footer.resumeAnimation();
+                debugLog('REPL:command', 'handler complete');
                 if (!shouldContinue) {
+                    // Exiting - don't restart input, just resolve
                     this.isRunning = false;
                     if (this.exitResolve) {
                         this.exitResolve();
                     }
                 }
+                else {
+                    // Overlays handle their own pause/resume via lifecycle
+                    // For non-overlay commands, we need to restart the input prompt
+                    // (finishInput() stopped it when user pressed Enter)
+                    this.footer.restartInput();
+                }
             });
         });
         // Handle Esc - abort running agent
@@ -450,18 +245,37 @@ export class REPL {
      */
     async run() {
         this.isRunning = true;
-        // Set terminal title and clear screen
+        // Set terminal title, clear screen, and show welcome
         terminal.setTitle('compilr');
         terminal.clearScreen();
-        conversation.printWelcome(this.model, this.version);
+        conversation.printWelcome(this.model, this.version, getActiveProject()?.displayName ?? null);
         // Start footer (begins render loop and input capture)
         this.footer.start();
+        // Start renderer (in legacy mode, this is mostly a no-op)
+        this.renderer.start();
+        // Set project name in footer
+        const activeProject = getActiveProject();
+        if (activeProject) {
+            this.footer.setProjectName(activeProject.displayName);
+        }
+        // Execute initial command if provided (e.g., /design from project menu)
+        if (this.initialCommand) {
+            const cmd = this.initialCommand;
+            // Give footer a moment to render before running command
+            setTimeout(() => {
+                void this.handleCommand(cmd, '');
+            }, 100);
+        }
         // Wait for exit signal
         await this.waitForExit();
         // Cleanup
         this.footer.stop();
-        terminal.writeLine('');
-        conversation.printInfo('Goodbye!');
+        this.renderer.stop();
+        // Only print goodbye when actually exiting (not when returning to menu)
+        if (!this.shouldReturnToMenu) {
+            terminal.writeLine('');
+            conversation.printInfo('Goodbye!');
+        }
     }
     /**
      * Wait for REPL exit
@@ -511,16 +325,28 @@ export class REPL {
     stop() {
         this.isRunning = false;
         this.footer.stop();
+        this.renderer.stop();
         if (this.exitResolve) {
             this.exitResolve();
         }
     }
+    /**
+     * Check if the user requested to return to the startup menu
+     */
+    wantsReturnToMenu() {
+        return this.shouldReturnToMenu;
+    }
     /**
      * Handle submitted input (processes message and queued inputs)
      */
     async handleSubmit(input) {
         // Clear any previous suggestion when new input is submitted
         this.footer.setSuggestion(null);
+        // Handle memory prefix: "# note" creates a persistent anchor
+        if (isMemoryInput(input)) {
+            handleMemoryInput(input, { agent: this.agent, footer: this.footer });
+            return;
+        }
         await this.processMessage(input);
         // Process queued inputs (FIFO)
         while (this.footer.hasQueuedInput() && this.isRunning) {
@@ -533,6 +359,57 @@ export class REPL {
     // ===========================================================================
     // Command Handling
     // ===========================================================================
+    /**
+     * Create command context for handler execution.
+     */
+    getCommandContext() {
+        return {
+            // Agent and model
+            agent: this.agent,
+            model: this.model,
+            currentModel: this.currentModel,
+            provider: this.provider,
+            version: this.version,
+            // UI components
+            footer: this.footer,
+            state: this.state,
+            // Session info
+            startTime: this.startTime,
+            sessionInputTokens: this.sessionInputTokens,
+            sessionOutputTokens: this.sessionOutputTokens,
+            sessionRequests: this.sessionRequests,
+            // Callbacks
+            onModeChange: this.onModeChange,
+            setShouldReturnToMenu: (value) => {
+                this.shouldReturnToMenu = value;
+            },
+            // REPL methods (bound to this instance)
+            processMessage: (message, options) => this.processMessage(message, options),
+            handleCommand: (cmd, cmdArgs) => this.handleCommand(cmd, cmdArgs),
+            setModel: (model) => {
+                this.setModel(model);
+            },
+            // UI helper methods
+            showTools: () => this.showTools(),
+            showTokens: () => {
+                this.showTokens();
+            },
+            showContext: () => {
+                this.showContext();
+            },
+            showStatus: () => {
+                this.showStatus();
+            },
+            showTodos: () => {
+                this.showTodos();
+            },
+            handleCompact: () => this.handleCompact(),
+            handleExport: (exportArgs) => this.handleExport(exportArgs),
+            reloadProjectAnchors: (oldId, newId) => {
+                this.reloadProjectAnchors(oldId, newId);
+            },
+        };
+    }
     /**
      * Handle slash command
      * Returns false if REPL should exit
@@ -559,639 +436,15 @@ export class REPL {
             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;
+        // Try command registry first (for extracted handlers)
+        const ctx = this.getCommandContext();
+        const registryResult = await commandRegistry.execute(resolved, args, ctx);
+        if (registryResult !== null) {
+            return registryResult;
         }
-        // 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.' });
+        // All commands are now handled by the registry
+        // This shouldn't happen if resolveCommand works correctly
+        conversation.printWarning(`Unknown command: /${command}`);
         return true;
     }
     // ===========================================================================
@@ -1249,6 +502,10 @@ Read COMPILR.md and PRD.md first to understand the tech stack, then create the a
         this.agentRunning = true;
         setAgentRunning(this.state, true);
         this.footer.setAgentRunning(true);
+        // Clear subagent tracking to prevent stale data from previous runs
+        // (both in agent.ts and in footer's SubagentRenderer)
+        this.clearSubagentTracking?.();
+        this.footer.clearSubagents();
         this.abortController = new AbortController();
         let totalInputTokens = 0;
         let totalOutputTokens = 0;
@@ -1258,6 +515,16 @@ Read COMPILR.md and PRD.md first to understand the tech stack, then create the a
         let lastToolInput = null;
         // Event-based rendering: accumulate text, render complete blocks
         let textAccumulator = '';
+        // Set up text buffer flusher so permission handler can flush before showing overlay
+        this.textBufferFlusher = () => {
+            if (textAccumulator.trim()) {
+                this.footer.clearForOutput();
+                conversation.printAssistantResponse(textAccumulator.trim());
+                terminal.writeLine('');
+                this.footer.forceRender();
+                textAccumulator = '';
+            }
+        };
         debug('processMessage', 'Starting agent stream', {
             inputLength: cleanedInput.length,
             toolCount: selectedNames.length,
@@ -1370,48 +637,32 @@ Read COMPILR.md and PRD.md first to understand the tech stack, then create the a
                         this.footer.forceRender();
                         continue;
                     }
-                    // Clear footer for output
-                    this.footer.clearForOutput();
-                    // Handle edit tool - diff was already shown on tool_start
+                    // Handle edit tool - diff was already shown on tool_start (no output needed)
                     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);
+                    // Handle task tool - print sub-agent completion summary to scrolling zone
+                    // Format: ● Explore(description) \n   ⎿  Done (stats)
+                    if (toolName === 'task') {
                         this.footer.setCurrentTool(null);
+                        // Get stats BEFORE clearing (so we have the data to print)
+                        const stats = this.footer.getLastSubagentStats();
+                        // Clear footer BEFORE clearing subagent data (so lastRenderHeight is still accurate)
+                        this.footer.clearForOutput();
+                        // Print the completion summary to scrolling zone
+                        if (stats) {
+                            conversation.printSubagentResponse(stats);
+                        }
+                        // Now clear the subagent data
+                        this.footer.clearSubagents();
                         this.footer.forceRender();
                         continue;
                     }
+                    // Clear footer for output (for tools that actually print output)
+                    this.footer.clearForOutput();
                     // Build argument summary for other tools
                     let argSummary = '';
                     if (toolInput) {
@@ -1448,6 +699,23 @@ Read COMPILR.md and PRD.md first to understand the tech stack, then create the a
                     this.footer.setCurrentTool(null);
                     this.footer.forceRender();
                 }
+                else if (event.type === 'guardrail_warning') {
+                    // Show guardrail warning to user (non-blocking)
+                    const result = event.result;
+                    const name = result.guardrail?.name ?? 'Unknown';
+                    const message = event.message || result.guardrail?.message || 'Risky operation detected';
+                    const category = result.guardrail?.tags?.[0] ?? 'general';
+                    this.footer.clearForOutput();
+                    conversation.printWarning(`[${category}] ${name}: ${message}`);
+                    this.footer.forceRender();
+                }
+                else if (event.type === 'guardrail_blocked') {
+                    // Show guardrail block message (operation was prevented)
+                    const message = event.message || 'Operation blocked by guardrail';
+                    this.footer.clearForOutput();
+                    conversation.printError(`Blocked: ${message}`);
+                    this.footer.forceRender();
+                }
             }
             debug('processMessage', 'Stream completed', {
                 hasTextOutput,
@@ -1481,6 +749,8 @@ Read COMPILR.md and PRD.md first to understand the tech stack, then create the a
             this.sessionInputTokens += totalInputTokens;
             this.sessionOutputTokens += totalOutputTokens;
             this.sessionRequests++;
+            // Clear subagents BEFORE printing stats so footer won't show them afterward
+            this.footer.clearSubagents();
             // Show token usage
             if (totalInputTokens > 0 || totalOutputTokens > 0) {
                 this.footer.clearForOutput();
@@ -1489,6 +759,7 @@ Read COMPILR.md and PRD.md first to understand the tech stack, then create the a
                 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('');
+                this.footer.forceRender();
             }
             // Stop spinner and re-render footer (AFTER all output is printed)
             this.agentRunning = false;
@@ -1509,6 +780,11 @@ Read COMPILR.md and PRD.md first to understand the tech stack, then create the a
             setAgentRunning(this.state, false);
             this.footer.setAgentRunning(false);
             this.abortController = null;
+            // Clear text buffer flusher
+            this.textBufferFlusher = null;
+            // Ensure footer is rendered and isPaused is reset
+            // (clearForOutput sets isPaused=true, forceRender resets it)
+            this.footer.forceRender();
             // Notify that agent has finished (for applying deferred suggestions)
             this.onAgentFinish?.();
         }
@@ -1519,12 +795,16 @@ Read COMPILR.md and PRD.md first to understand the tech stack, then create the a
     async handleCompact() {
         const contextManager = this.agent.getContextManager();
         if (!contextManager) {
+            this.footer.clearForOutput();
             conversation.printWarning('Context manager not available');
+            this.footer.forceRender();
             return;
         }
         const history = this.agent.getHistory();
         if (history.length === 0) {
+            this.footer.clearForOutput();
             conversation.printInfo('No conversation history to compact');
+            this.footer.forceRender();
             return;
         }
         const stats = contextManager.getStats(history.length);
@@ -1630,15 +910,8 @@ Read COMPILR.md and PRD.md first to understand the tech stack, then create the a
                 permission,
             };
         });
-        // Pause footer during overlay
-        this.footer.pauseAnimation();
-        try {
-            await showToolsOverlay(tools);
-        }
-        finally {
-            this.footer.resumeAnimation();
-            this.footer.forceRender();
-        }
+        // Overlay lifecycle handles footer pause/resume
+        await showToolsOverlay(tools);
     }
     showTokens() {
         this.footer.clearForOutput();