@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/ui/footer.js

@@ -17,7 +17,10 @@ import { MODE_INFO } from './types.js';
 import { getStyles } from '../themes/index.js';
 import * as terminal from './terminal.js';
 import { TodoZone } from './todo-zone.js';
-import { InputPrompt, DEFAULT_COMMANDS } from './input-prompt-v2.js';
+import { InputPrompt, DEFAULT_COMMANDS } from './input-prompt.js';
+import { SubagentRenderer } from './subagent-renderer.js';
+import { debugLog, debugRender } from '../utils/debug-log.js';
+import { getPhysicalLineCount, getVisibleLength } from './line-utils.js';
 // =============================================================================
 // Footer Class
 // =============================================================================
@@ -25,13 +28,17 @@ export class Footer extends EventEmitter {
     // Child components
     todoZone;
     inputPrompt;
+    subagentRenderer;
     // State
     agentRunning = false;
     mode;
     lastRenderHeight = 0;
     isRunning = false;
     isPaused = false; // Prevents rendering even if callback is queued
+    isRendering = false; // Prevents re-entrant renders
     cursorLineFromBottom = 0; // Track cursor position for clear()
+    projectName = null; // Current active project name
+    externalRendererEnabled = false; // When true, skip internal render loop
     // Render loop
     renderInterval;
     renderTimer = null;
@@ -48,10 +55,15 @@ export class Footer extends EventEmitter {
             showSeparators: options.showSeparators ?? true,
             commands: DEFAULT_COMMANDS,
         });
+        this.subagentRenderer = new SubagentRenderer();
         // Wire up TodoZone animation callback
         this.todoZone.setAnimationCallback(() => {
             this.needsRender = true;
         });
+        // Wire up SubagentRenderer update callback
+        this.subagentRenderer.setUpdateCallback(() => {
+            this.needsRender = true;
+        });
         // Wire up InputPrompt events
         this.inputPrompt.on('submit', (input) => {
             this.emit('submit', input);
@@ -71,6 +83,11 @@ export class Footer extends EventEmitter {
         this.inputPrompt.on('change', () => {
             this.needsRender = true;
         });
+        // Toggle subagent expand on Ctrl+O
+        this.inputPrompt.on('toggleSubagentExpand', () => {
+            this.subagentRenderer.toggleExpand();
+            this.needsRender = true;
+        });
     }
     // ===========================================================================
     // Public API
@@ -88,7 +105,7 @@ export class Footer extends EventEmitter {
         // Start render loop
         this.render();
         this.renderTimer = setInterval(() => {
-            if (this.needsRender && !this.isPaused) {
+            if (this.isRunning && this.needsRender && !this.isPaused) {
                 this.render();
                 this.needsRender = false;
             }
@@ -121,14 +138,31 @@ export class Footer extends EventEmitter {
         this.agentRunning = running;
         this.todoZone.setAgentRunning(running);
         this.inputPrompt.setQueueMode(running);
-        // When stopping, immediately clear and re-render to remove spinner
-        // This prevents ghost spinner from render interval races
-        if (wasRunning && !running) {
-            this.clear();
-            this.render();
+        // When starting a new run, clear previous subagents
+        if (!wasRunning && running) {
+            this.subagentRenderer.clear();
+            // When external renderer manages rendering, just mark needsRender
+            if (this.externalRendererEnabled) {
+                this.needsRender = true;
+            }
+            else {
+                // Legacy mode: IMMEDIATELY render so lastRenderHeight includes spinner
+                this.clear();
+                this.render();
+            }
         }
-        else {
-            this.needsRender = true;
+        // When stopping, clear subagents
+        if (wasRunning && !running) {
+            this.subagentRenderer.clear();
+            // When external renderer manages rendering, just mark needsRender
+            if (this.externalRendererEnabled) {
+                this.needsRender = true;
+            }
+            else {
+                // Legacy mode: immediately re-render to remove spinner
+                this.clear();
+                this.render();
+            }
         }
     }
     /**
@@ -150,6 +184,19 @@ export class Footer extends EventEmitter {
     getMode() {
         return this.mode;
     }
+    /**
+     * Set the current project name (displayed in footer)
+     */
+    setProjectName(name) {
+        this.projectName = name;
+        this.needsRender = true;
+    }
+    /**
+     * Get the current project name
+     */
+    getProjectName() {
+        return this.projectName;
+    }
     /**
      * Update the todo list
      */
@@ -185,6 +232,69 @@ export class Footer extends EventEmitter {
     addTokens(count) {
         this.todoZone.addTokens(count);
     }
+    // ===========================================================================
+    // Subagent API
+    // ===========================================================================
+    /**
+     * Called when a subagent starts
+     */
+    onSubagentStart(agentId, agentType, description) {
+        this.subagentRenderer.onSubagentStart(agentId, agentType, description);
+    }
+    /**
+     * Called when a subagent uses a tool
+     */
+    onSubagentToolUse(agentId, toolName, summary) {
+        this.subagentRenderer.onToolUse(agentId, toolName, summary);
+    }
+    /**
+     * Called when a subagent completes
+     *
+     * CRITICAL (legacy mode only): We must pause rendering immediately to prevent a race condition.
+     * The render loop could fire between onSubagentEnd and clearForOutput, which would:
+     * 1. See the subagent as 'done'
+     * 2. Render with 0 subagent lines
+     * 3. Update lastRenderHeight to a smaller value
+     * 4. Then clearForOutput would not clear enough lines → ghost lines!
+     *
+     * In external renderer mode: No pause needed since the internal render loop is disabled.
+     */
+    onSubagentEnd(agentId, success, tokenCount, error) {
+        // Only pause in legacy mode (internal render loop is running)
+        // In external renderer mode, the loop is already stopped
+        if (!this.externalRendererEnabled) {
+            // Pause rendering BEFORE updating state to prevent race condition
+            // The caller (repl.ts) will call clearForOutput() and forceRender() which will unpause
+            this.isPaused = true;
+        }
+        this.subagentRenderer.onSubagentEnd(agentId, success, tokenCount, error);
+        this.needsRender = true;
+    }
+    /**
+     * Toggle expanded view for subagents (Ctrl+O)
+     */
+    toggleSubagentExpand() {
+        this.subagentRenderer.toggleExpand();
+    }
+    /**
+     * Check if there are active subagents
+     */
+    hasActiveSubagents() {
+        return this.subagentRenderer.hasActiveSubagents();
+    }
+    /**
+     * Clear subagent tracking (after completion displayed)
+     */
+    clearSubagents() {
+        this.subagentRenderer.clear();
+        this.needsRender = true;
+    }
+    /**
+     * Get the last subagent's stats before clearing
+     */
+    getLastSubagentStats() {
+        return this.subagentRenderer.getLastAgentStats();
+    }
     /**
      * Get queued inputs
      */
@@ -217,22 +327,58 @@ export class Footer extends EventEmitter {
     /**
      * Clear footer before scrolling output
      * Call this before writing to the scrolling zone
+     * Pauses interval rendering to prevent ghost lines during output
+     *
+     * When external renderer is enabled (scroll region mode):
+     * - Footer doesn't need clearing (it's in a separate scroll region)
+     * - Just mark that we need a re-render
      */
     clearForOutput() {
+        // When external renderer manages rendering, footer is in a fixed region
+        // and doesn't need to be cleared before output
+        if (this.externalRendererEnabled) {
+            debugRender('Footer:clearForOutput', 'external renderer mode - skipping clear');
+            return;
+        }
+        // Pause interval rendering to prevent ghost lines during output
+        this.isPaused = true;
+        debugRender('Footer:clearForOutput', `lastRenderHeight=${String(this.lastRenderHeight)}`);
+        // Clear the footer
         this.clear();
     }
     /**
      * Force an immediate render
+     * Resumes interval rendering after clearForOutput()
+     *
+     * When external renderer is enabled (scroll region mode):
+     * - Just mark that we need a re-render (TerminalRenderer's loop will pick it up)
      */
     forceRender() {
+        // When external renderer manages rendering, just mark that we need re-render
+        if (this.externalRendererEnabled) {
+            debugRender('Footer:forceRender', 'external renderer mode - marking needsRender');
+            this.needsRender = true;
+            return;
+        }
+        // Resume interval rendering BEFORE calling render (so render() isn't skipped)
+        this.isPaused = false;
         this.render();
         this.needsRender = false;
     }
+    /**
+     * Restart input prompt after a command completes
+     * Use this for non-overlay commands where finishInput() stopped the prompt
+     */
+    restartInput() {
+        this.inputPrompt.start();
+        this.render();
+    }
     /**
      * Pause footer completely (for overlays)
      * Stops render loop, input capture, and animation
      */
     pauseAnimation() {
+        debugLog('Footer:pauseAnimation', 'start');
         // Set paused flag FIRST - this prevents any queued render callbacks from executing
         this.isPaused = true;
         // Stop render loop
@@ -240,12 +386,16 @@ export class Footer extends EventEmitter {
             clearInterval(this.renderTimer);
             this.renderTimer = null;
         }
+        debugLog('Footer:pauseAnimation', 'render loop stopped');
         // Stop input capture
         this.inputPrompt.stop();
+        debugLog('Footer:pauseAnimation', 'input stopped');
         // Stop animation
         this.todoZone.pauseAnimation();
+        debugLog('Footer:pauseAnimation', 'animation stopped');
         // Clear footer from screen
         this.clear();
+        debugLog('Footer:pauseAnimation', 'footer cleared');
     }
     /**
      * Resume footer after pause
@@ -261,7 +411,7 @@ export class Footer extends EventEmitter {
         // Restart render loop
         this.render();
         this.renderTimer = setInterval(() => {
-            if (this.needsRender && !this.isPaused) {
+            if (this.isRunning && this.needsRender && !this.isPaused) {
                 this.render();
                 this.needsRender = false;
             }
@@ -273,6 +423,99 @@ export class Footer extends EventEmitter {
     getLastRenderHeight() {
         return this.lastRenderHeight;
     }
+    /**
+     * Get all footer lines for rendering (for TerminalRenderer integration)
+     * Returns the lines WITHOUT writing to terminal
+     */
+    getFooterLines() {
+        const allLines = [];
+        const s = getStyles();
+        // 1. Subagent zone (only if agent is running)
+        if (this.agentRunning) {
+            const subagentLines = this.subagentRenderer.render();
+            allLines.push(...subagentLines);
+        }
+        // 2. Todo zone (spinner + todos)
+        const todoLines = this.todoZone.render();
+        allLines.push(...todoLines);
+        // 3. Queued inputs
+        const queuedInputs = this.inputPrompt.getQueuedInputs();
+        for (const queued of queuedInputs) {
+            allLines.push(s.muted(`queued: "${queued}"`));
+        }
+        // 4. Input prompt
+        const inputLines = this.inputPrompt.render();
+        allLines.push(...inputLines);
+        // 5. Mode indicator (below input, before autocomplete)
+        allLines.push(this.renderModeIndicator());
+        // 6. Autocomplete dropdown (if active)
+        const autocompleteLines = this.inputPrompt.getAutocompleteLines();
+        allLines.push(...autocompleteLines);
+        return allLines;
+    }
+    /**
+     * Get cursor position within footer content (for TerminalRenderer)
+     * Returns { row, col } where row is 0-indexed from start of footer lines
+     */
+    getFooterCursorPosition() {
+        const cursorInfo = this.inputPrompt.getCursorInfo();
+        // Calculate lines before input prompt
+        let linesBeforeInput = 0;
+        // Subagent lines
+        if (this.agentRunning) {
+            linesBeforeInput += this.subagentRenderer.render().length;
+        }
+        // Todo lines
+        linesBeforeInput += this.todoZone.render().length;
+        // Queued inputs
+        linesBeforeInput += this.inputPrompt.getQueuedInputs().length;
+        // cursorInfo.row is 1-indexed (row 1 = first line after separator)
+        // Convert to 0-indexed row within footer
+        const row = linesBeforeInput + cursorInfo.row - 1;
+        return { row, col: cursorInfo.col };
+    }
+    /**
+     * Enable external renderer mode (TerminalRenderer manages rendering)
+     * When enabled:
+     * - Footer's internal render loop is disabled
+     * - Input capture remains active
+     * - Event forwarding remains active
+     * - TerminalRenderer calls getFooterLines() and renders
+     */
+    setExternalRenderer(enabled) {
+        this.externalRendererEnabled = enabled;
+        if (enabled && this.renderTimer) {
+            // Stop the internal render loop (TerminalRenderer will handle rendering)
+            clearInterval(this.renderTimer);
+            this.renderTimer = null;
+            debugLog('Footer:setExternalRenderer', 'enabled - internal render loop stopped');
+        }
+        else if (!enabled && this.isRunning && !this.renderTimer) {
+            // Restart the internal render loop
+            this.renderTimer = setInterval(() => {
+                if (this.isRunning && this.needsRender && !this.isPaused) {
+                    this.render();
+                    this.needsRender = false;
+                }
+            }, this.renderInterval);
+            debugLog('Footer:setExternalRenderer', 'disabled - internal render loop restarted');
+        }
+    }
+    /**
+     * Check if external renderer is enabled
+     */
+    isExternalRendererEnabled() {
+        return this.externalRendererEnabled;
+    }
+    /**
+     * Request a render from external renderer
+     * Call this to notify TerminalRenderer that footer needs re-rendering
+     */
+    requestExternalRender() {
+        this.needsRender = true;
+        // External renderer will poll this or listen for events
+        // For now, just set the flag
+    }
     /**
      * Refresh the prompt with current theme colors
      * Call after theme changes to apply new colors immediately
@@ -287,17 +530,26 @@ export class Footer extends EventEmitter {
     // ===========================================================================
     /**
      * Clear the footer area
+     *
+     * Strategy: Simply move to the top of the CURRENT footer and clear to end.
+     * - When footer SHRINKS: clearToEndOfScreen handles the extra lines
+     * - When footer GROWS: terminal scrolls naturally when we write more lines
+     *
+     * We NEVER move up into the scrolling zone - that would eat content!
      */
     clear() {
+        debugRender('Footer:clear', `lastHeight=${String(this.lastRenderHeight)} cursorFromBottom=${String(this.cursorLineFromBottom)}`);
         if (this.lastRenderHeight > 0) {
             // Move to start of current line
             terminal.moveCursorToLineStart();
-            // First move DOWN to the last line of footer (cursor may be positioned in input area)
-            if (this.cursorLineFromBottom > 0) {
-                terminal.moveCursorDown(this.cursorLineFromBottom);
+            // Calculate DIRECT movement to top of footer
+            const cursorRowFromTop = this.lastRenderHeight - this.cursorLineFromBottom;
+            const rowsToMoveUp = cursorRowFromTop - 1;
+            debugRender('Footer:clear', `cursorRowFromTop=${String(cursorRowFromTop)} rowsToMoveUp=${String(rowsToMoveUp)}`);
+            if (rowsToMoveUp > 0) {
+                terminal.moveCursorUp(rowsToMoveUp);
             }
-            // Now move up to the first line of footer
-            terminal.moveCursorUp(this.lastRenderHeight - 1);
+            // Clear from here to end of screen
             terminal.clearToEndOfScreen();
         }
         this.lastRenderHeight = 0;
@@ -307,47 +559,68 @@ export class Footer extends EventEmitter {
      * Render the entire footer
      */
     render() {
-        // Clear and redraw footer
-        this.clear();
-        const allLines = [];
-        // 1. Todo zone (spinner + todos)
-        const todoLines = this.todoZone.render();
-        allLines.push(...todoLines);
-        // 2. Queued inputs
-        const s = getStyles();
-        const queuedInputs = this.inputPrompt.getQueuedInputs();
-        for (const queued of queuedInputs) {
-            allLines.push(s.muted(`queued: "${queued}"`));
-        }
-        // 3. Input prompt
-        const inputLines = this.inputPrompt.render();
-        allLines.push(...inputLines);
-        // 4. Mode indicator (below input, before autocomplete)
-        allLines.push(this.renderModeIndicator());
-        // 5. Autocomplete dropdown (if active)
-        const autocompleteLines = this.inputPrompt.getAutocompleteLines();
-        allLines.push(...autocompleteLines);
-        // Write all lines
-        for (let i = 0; i < allLines.length; i++) {
-            terminal.write(allLines[i]);
-            if (i < allLines.length - 1) {
-                terminal.write('\n');
+        // Don't render if footer has been stopped, we're paused, or already rendering
+        if (!this.isRunning || this.isPaused || this.isRendering)
+            return;
+        // Prevent re-entrant renders
+        this.isRendering = true;
+        try {
+            // Build all lines FIRST to know new height before clearing
+            const allLines = [];
+            let subagentLineCount = 0;
+            // 1. Subagent zone (only if agent is running - prevents showing after completion)
+            if (this.agentRunning) {
+                const subagentLines = this.subagentRenderer.render();
+                subagentLineCount = subagentLines.length;
+                allLines.push(...subagentLines);
             }
+            // 2. Todo zone (spinner + todos)
+            const todoLines = this.todoZone.render();
+            allLines.push(...todoLines);
+            // 3. Queued inputs
+            const s = getStyles();
+            const queuedInputs = this.inputPrompt.getQueuedInputs();
+            for (const queued of queuedInputs) {
+                allLines.push(s.muted(`queued: "${queued}"`));
+            }
+            // 4. Input prompt
+            const inputLines = this.inputPrompt.render();
+            allLines.push(...inputLines);
+            // 5. Mode indicator (below input, before autocomplete)
+            allLines.push(this.renderModeIndicator());
+            // 6. Autocomplete dropdown (if active)
+            const autocompleteLines = this.inputPrompt.getAutocompleteLines();
+            allLines.push(...autocompleteLines);
+            // Calculate new height BEFORE clearing (to clear extra lines if growing)
+            const termWidth = process.stdout.columns || 80;
+            let newHeight = 0;
+            const lineHeights = [];
+            for (const line of allLines) {
+                // Use unified line-utils for consistent height calculation
+                const lineHeight = getPhysicalLineCount(line, termWidth);
+                lineHeights.push(lineHeight);
+                newHeight += lineHeight;
+            }
+            debugRender('Footer:render', `subagent=${String(subagentLineCount)} todo=${String(todoLines.length)} queued=${String(queuedInputs.length)} input=${String(inputLines.length)} autocomplete=${String(autocompleteLines.length)}`);
+            debugRender('Footer:render', `termWidth=${String(termWidth)} lineHeights=[${lineHeights.join(',')}] newHeight=${String(newHeight)}`);
+            // Clear the current footer (terminal scrolls naturally if we write more lines)
+            this.clear();
+            // Write all lines
+            for (let i = 0; i < allLines.length; i++) {
+                terminal.write(allLines[i]);
+                if (i < allLines.length - 1) {
+                    terminal.write('\n');
+                }
+            }
+            // Track height for next clear
+            this.lastRenderHeight = newHeight;
+            debugRender('Footer:render', `lastRenderHeight set to ${String(newHeight)}`);
+            // Position cursor within input prompt
+            this.positionCursor(allLines, subagentLineCount + todoLines.length + queuedInputs.length);
         }
-        // Track height - account for line wrapping in terminal
-        const termWidth = process.stdout.columns || 80;
-        let actualTerminalRows = 0;
-        for (const line of allLines) {
-            // Strip ANSI codes to get visible length
-            // eslint-disable-next-line no-control-regex
-            const visibleLength = line.replace(/\x1b\[[0-9;]*m/g, '').length;
-            // Each line takes at least 1 row, plus extra rows if it wraps
-            actualTerminalRows += Math.max(1, Math.ceil(visibleLength / termWidth));
+        finally {
+            this.isRendering = false;
         }
-        this.lastRenderHeight = actualTerminalRows;
-        // Position cursor within input prompt
-        // linesBeforeInput = todoLines + queuedInputs (mode indicator is now AFTER input)
-        this.positionCursor(allLines, todoLines.length + queuedInputs.length);
     }
     /**
      * Render mode indicator line
@@ -355,30 +628,43 @@ export class Footer extends EventEmitter {
     renderModeIndicator() {
         const s = getStyles();
         const modeInfo = MODE_INFO[this.mode];
+        const termWidth = process.stdout.columns || 80;
+        // Build left side (mode indicator)
+        let leftPart;
         switch (this.mode) {
             case 'normal':
-                // Subtle indicator in normal mode
-                return s.muted(`mode: ${modeInfo.label}  (Shift+Tab to change)`);
+                leftPart = s.muted(`mode: ${modeInfo.label}  (Shift+Tab to change)`);
+                break;
             case 'auto-accept':
-                // Warning color for auto-accept
-                return s.warning(`⚡ mode: ${modeInfo.label}`) + s.muted('  (Shift+Tab to change)');
+                leftPart = s.warning(`⚡ mode: ${modeInfo.label}`) + s.muted('  (Shift+Tab to change)');
+                break;
             case 'plan':
-                // Different color for plan mode
-                return s.info(`📋 mode: ${modeInfo.label}`) + s.muted('  (Shift+Tab to change)');
+                leftPart = s.info(`📋 mode: ${modeInfo.label}`) + s.muted('  (Shift+Tab to change)');
+                break;
             default:
-                return s.muted(`mode: ${modeInfo.label}  (Shift+Tab to change)`);
+                leftPart = s.muted(`mode: ${modeInfo.label}  (Shift+Tab to change)`);
+        }
+        // If no project, just return the mode indicator
+        if (!this.projectName) {
+            return leftPart;
         }
+        // Build right side (project name)
+        const projectText = `Project: ${this.projectName}`;
+        const rightPart = s.muted(projectText);
+        // Calculate visible lengths (using unified line-utils)
+        const leftVisible = getVisibleLength(leftPart);
+        const rightVisible = projectText.length;
+        // Calculate padding to right-align project name
+        const padding = Math.max(2, termWidth - leftVisible - rightVisible);
+        return leftPart + ' '.repeat(padding) + rightPart;
     }
     /**
      * Calculate how many terminal rows a line takes (accounting for wrapping)
+     * Uses unified line-utils for consistent calculation across all components.
      */
     getTerminalRowsForLine(line) {
         const termWidth = process.stdout.columns || 80;
-        // Strip ANSI codes to get visible length
-        // eslint-disable-next-line no-control-regex
-        const visibleLength = line.replace(/\x1b\[[0-9;]*m/g, '').length;
-        // Each line takes at least 1 row, plus extra rows if it wraps
-        return Math.max(1, Math.ceil(visibleLength / termWidth));
+        return getPhysicalLineCount(line, termWidth);
     }
     /**
      * Position cursor correctly within the input prompt
@@ -406,11 +692,17 @@ export class Footer extends EventEmitter {
         for (let i = inputEndIndex; i < allLines.length; i++) {
             rowsAfterInput += this.getTerminalRowsForLine(allLines[i]);
         }
-        // Cursor target row from start of footer = rows before input + cursor row within input
+        // Cursor target row from start of footer (1-indexed) = rows before input + cursor row within input
         const cursorRowFromStart = rowsBeforeInput + cursorInfo.row;
-        // Total rows to move up from end = total rows - cursor row - 1
+        // Total rows in footer
         const totalRows = rowsBeforeInput + inputTotalRows + rowsAfterInput;
+        // After writing all lines, cursor is at the END of the last row (row totalRows).
+        // cursorInfo.row starts at 1 (after separator), so actual footer row = cursorRowFromStart + 1
+        // To move to actual row, we move up: totalRows - (cursorRowFromStart + 1) = totalRows - cursorRowFromStart - 1
+        // Example: totalRows=7, cursorRowFromStart=4, actual row=5 → move up 2 rows (from row 7 to row 5)
         const rowsToMoveUp = totalRows - cursorRowFromStart - 1;
+        debugRender('Footer:positionCursor', `cursorInfo={row:${String(cursorInfo.row)},col:${String(cursorInfo.col)}} rowsBefore=${String(rowsBeforeInput)} inputRows=${String(inputTotalRows)} rowsAfter=${String(rowsAfterInput)}`);
+        debugRender('Footer:positionCursor', `totalRows=${String(totalRows)} cursorRowFromStart=${String(cursorRowFromStart)} rowsToMoveUp=${String(rowsToMoveUp)}`);
         if (rowsToMoveUp > 0) {
             terminal.moveCursorUp(rowsToMoveUp);
         }

package/dist/ui/guardrail-overlay.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Guardrail Confirmation Overlay
+ *
+ * Shows when a guardrail with action='confirm' is triggered.
+ * User must approve or deny the risky operation.
+ */
+export interface GuardrailConfirmOptions {
+    /** Guardrail name */
+    name: string;
+    /** Guardrail description/message */
+    message: string;
+    /** Action type (for display) */
+    action: 'warn' | 'confirm' | 'block';
+    /** Tool that triggered the guardrail */
+    toolName: string;
+    /** The input that matched the pattern */
+    matchedInput: string;
+    /** Category (e.g., 'git', 'filesystem', 'database') */
+    category?: string;
+}
+export interface GuardrailConfirmResult {
+    /** Whether to proceed with the operation */
+    approved: boolean;
+}
+/**
+ * Show the guardrail confirmation overlay.
+ * Returns { approved: true } if user allows, { approved: false } if denied.
+ */
+export declare function showGuardrailOverlay(options: GuardrailConfirmOptions): Promise<GuardrailConfirmResult>;