clawtap/docs/superpowers/specs/2026-03-27-interactive-prompts-design.md

Interactive Prompts — Normalized Handling Across All Adapters

Date: 2026-03-27 Status: Draft

Problem

Gemini and Codex CLIs show interactive terminal prompts (tool confirmation, ask user question, plan approval, etc.) that ClawTap doesn't detect or handle. The UI freezes with a blinking cursor while the CLI waits for input. Claude's prompts are handled via hooks, but Gemini/Codex have no equivalent hook mechanism for runtime prompts.

Design Principle

One normalized format, adapter-agnostic frontend.

Each adapter detects prompts in its own way (Claude: hooks, Gemini/Codex: pane monitor), but all emit the same InteractivePrompt format. Frontend renders based on format, not adapter identity.

Normalized Types

interface InteractivePrompt {
  requestId: string;
  type: 'permission' | 'question' | 'plan' | 'loop-detected';
  title: string;
  description: string;
  toolName?: string;
  toolInput?: any;
  options?: { value: string; label: string }[];
  textInput?: { placeholder?: string };
}

interface PromptResponse {
  requestId: string;
  selectedOption?: string;
  textValue?: string;
}

Render logic:

• options only → button list (permission overlay)
• textInput only → text input field (ask question)
• Both → buttons + text field (plan mode: approve buttons + feedback)

Changes

Change 1: Gemini pane monitor — detect interactive prompts

File: server/adapters/gemini/pane-monitor.ts

Add prompt detection to the existing poll loop. Each poll, check for known prompt patterns before processing streaming text:

Tool Confirmation ("Action Required"):

Pattern: content includes "Action Required" AND numbered options (● N.)
Extract: title, description (command/file/tool info), options list
Emit: { type: 'permission', options: [...] }

AskUser ("Answer Questions"):

Pattern: content includes "Answer Questions" AND "> " input prompt
Extract: question text, input type (detect options vs free text)
Emit: { type: 'question', textInput or options }

Plan Approval ("Approval"):

Pattern: content includes "Approval" header with plan content
Extract: plan text, approval options + feedback field
Emit: { type: 'plan', options: [...], textInput: { placeholder: 'Type your feedback...' } }

Loop Detection:

Pattern: content includes "potential loop was detected"
Extract: options
Emit: { type: 'loop-detected', options: [...] }

Dedup: track last emitted requestId to avoid re-emitting the same prompt on each poll.

Change 2: Codex pane monitor — detect interactive prompts

File: server/adapters/codex/pane-monitor.ts

Command/File/Network Approval:

Pattern: content includes "(y) Yes, proceed" or "Would you like to run"
Extract: command/file info, available options (y/a/p/d/n)
Emit: { type: 'permission', options: [...] }

Request User Input:

Pattern: content includes "Question" header with "> " input
Extract: question text, options or free text field
Emit: { type: 'question', textInput or options }

Change 3: Gemini adapter — respondPermission / respondQuestion

File: server/adapters/gemini/gemini-tmux-adapter.ts

Add methods to send keystrokes based on PromptResponse:

• Permission (numbered options): Navigate Down × N to selected option, press Enter
• Question (text): Type answer text, press Enter
• Question (select): Navigate to selected option, press Enter
• Plan: Select approve option OR type feedback, press Enter

Change 4: Codex adapter — respondPermission / respondQuestion

File: server/adapters/codex/codex-tmux-adapter.ts

• Permission: Send the keyboard shortcut key (y/a/p/d/n)
• Question (text): Type answer text, press Enter
• Question (select): Navigate to option, press Enter

Change 5: Claude adapter — normalize existing events

File: server/adapters/claude/tmux-adapter.ts

Current permission-request and ask-question events already work but use adapter-specific format. Map to InteractivePrompt format in session-manager.ts event handlers (minimal change — add missing fields).

Change 6: Session manager — unified event handling

File: server/session-manager.ts

Current event listeners:

adapter.on('permission-request', ...) → broadcast WS.PERMISSION_REQUEST
adapter.on('ask-question', ...) → broadcast WS.PERMISSION_REQUEST (toolName: 'AskUserQuestion')

Change to emit unified format:

adapter.on('interactive-prompt', (sessionId, prompt: InteractivePrompt) => {
  broadcast(sessionId, { type: WS.INTERACTIVE_PROMPT, ...prompt });
});

Change 7: Frontend — InteractivePromptOverlay component

File: src/components/InteractivePromptOverlay.tsx (new)

Replaces PermissionOverlay and AskQuestion with a single adapter-agnostic component:

• Renders title + description
• If options → button list
• If textInput → text input field
• If both → buttons + text field (plan mode layout)
• Sends PromptResponse back via WS

File: src/components/ChatView.tsx + src/components/FloatingReviewPanel.tsx

Replace PermissionOverlay / AskQuestion usage with InteractivePromptOverlay.

Change 8: useChat — handle new WS message type

File: src/hooks/useChat.ts

Replace WS.PERMISSION_REQUEST handler with WS.INTERACTIVE_PROMPT:

case WS.INTERACTIVE_PROMPT:
  setInteractivePrompt(msg); // replaces setPermissionRequest
  break;

Change 9: Remaining _waitForReady prompts

File: server/adapters/gemini/gemini-tmux-adapter.ts

Add detection for remaining startup prompts:

• Privacy Notice → send Esc
• Multi-folder trust → send option 1
• IDE integration nudge → send "No"

These are handled in _waitForReady (auto-bypass), not sent to frontend.

What Doesn't Change

• WS protocol: Still uses WebSocket for all communication
• tmux management: Still uses tmux for CLI process management
• JSONL watching: Still uses file watchers for message history
• Claude hooks: Still uses hooks for Claude tool events (just normalizes the output format)

Scope Notes

Phase 1 (this spec):

• Gemini: tool confirmation, ask user, plan approval, loop detection
• Codex: command/file/network approval, request user input
• Claude: normalize existing events to new format
• Frontend: InteractivePromptOverlay component

Phase 2 (future):

• Diff rendering in file edit permissions
• Codex MCP elicitation forms (structured multi-field forms)
• Codex multi-agent thread approval routing