Interactive Overlays and Approvals

Relevant source files

• codex-rs/core/src/codex.rs
• codex-rs/protocol/src/protocol.rs
• codex-rs/tui/src/app.rs
• codex-rs/tui/src/app_event.rs
• codex-rs/tui/src/bottom_pane/chat_composer.rs
• codex-rs/tui/src/bottom_pane/mod.rs
• codex-rs/tui/src/chatwidget.rs
• codex-rs/tui/src/chatwidget/tests.rs
• codex-rs/tui/src/history_cell.rs
• codex-rs/tui/src/slash_command.rs

Purpose and Scope

This page documents the interactive overlay system in the TUI, focusing on approval flows for tool execution, patch application, and MCP elicitation. These overlays are modal UI components displayed in the BottomPane that pause normal input processing to collect user decisions before tool calls proceed.

For general bottom pane architecture and input routing, see 4.1.3. For tool execution mechanics after approval, see 5.5.

---

Overview

Interactive overlays are full-screen modal views that replace the normal chat composer to request explicit user consent for potentially destructive operations. The TUI supports three primary overlay types:

Overlay Type	Protocol Event	User Response Op	Purpose
ApprovalOverlay	ExecApprovalRequestEvent	Op::ExecApproval	Approve/deny shell command execution
ApprovalOverlay	ApplyPatchApprovalRequestEvent	Op::PatchApproval	Approve/deny file patch application
RequestUserInputOverlay	RequestUserInputEvent	Op::UserInputAnswer	Answer structured questions from tools
(inline)	ElicitationRequestEvent	Op::ResolveElicitation	Approve/deny MCP resource access

All overlays are rendered via the BottomPane view stack and consume input until the user makes a decision or dismisses the overlay.

Sources: codex-rs/tui/src/bottom_pane/mod.rs42-50 codex-rs/protocol/src/protocol.rs54-60 codex-rs/protocol/src/protocol.rs248-284

---

Approval Flow Architecture

Approval Request Event Flow

When codex-core determines that a tool call requires user approval (based on AskForApproval policy), it emits an approval request event. The TUI receives this via the event stream, constructs an ApprovalRequest structure containing the tool context (command, justification, policy amendment options), and pushes an ApprovalOverlay onto the bottom pane view stack. The overlay blocks normal input until the user makes a decision, then submits the corresponding Op back to core.

Sources: codex-rs/tui/src/chatwidget.rs73-99 codex-rs/tui/src/app_event.rs21 codex-rs/tui/src/app_event.rs339

---

ApprovalOverlay Component

Structure and Rendering

ApprovalOverlay is a BottomPaneView implementation that displays:

• Command or patch content: The shell command or file diff requiring approval
• Justification: Model-provided reasoning for why the operation is needed
• Approval options: Buttons for Approve, Deny, and optionally Edit/Details
• Policy amendment UI: Checkboxes to update trust rules (e.g., "Always approve this pattern")

The overlay occupies the full bottom pane area and is styled distinctly from the normal composer to signal that user action is required.

Sources: codex-rs/tui/src/bottom_pane/mod.rs42 codex-rs/tui/src/bottom_pane/mod.rs48-49

ApprovalRequest Structure

The ApprovalRequest carries:

• id/turn_id: Submission identifiers to correlate the response with the in-flight request
• kind: Whether this is an exec or patch approval (affects UI rendering)
• justification: Model-provided explanation shown to the user
• policy_amendment: Optional trust rule update that can be applied with the approval decision

Sources: codex-rs/tui/src/bottom_pane/mod.rs49 codex-rs/protocol/src/protocol.rs54-59

Decision Handling

When the user selects an option, the overlay transitions to complete state and the BottomPane pops it from the view stack. The decision is translated into an Op::ExecApproval or Op::PatchApproval submission with:

• decision: ReviewDecision::Approved, ReviewDecision::Rejected, or ReviewDecision::EditAndResubmit
• policy_amendment: Applied if the user checked the "always allow" option

The core agent receives the decision and either proceeds with execution or aborts the tool call based on the response.

Sources: codex-rs/protocol/src/protocol.rs248-265 codex-rs/tui/src/bottom_pane/mod.rs400-420

---

RequestUserInputOverlay

Purpose

The request_user_input tool allows the model to ask structured questions during a turn (for example, "Which authentication method should I use?" with enumerated choices). Unlike approval overlays that gate execution, request_user_input overlays collect arbitrary user answers and resume the turn with those answers as tool output.

Sources: codex-rs/tui/src/bottom_pane/mod.rs44 codex-rs/tui/src/bottom_pane/mod.rs50 codex-rs/protocol/src/protocol.rs60

Question/Answer Flow

The overlay renders:

• Title/prompt: Free-form question text from the tool call
• Question list: Each question has a type (text, choice, multi-choice) and optional default
• Answer inputs: Text fields, radio buttons, or checkboxes based on question type
• Submit button: Packages answers and sends Op::UserInputAnswer

The agent receives the response, formats it as the tool call result, and continues the turn with the model observing the user's answers.

Sources: codex-rs/protocol/src/protocol.rs277-284 codex-rs/tui/src/bottom_pane/mod.rs44-50

---

Elicitation Handling for MCP

MCP Resource Access Approval

MCP servers can issue "elicitations" to request user consent for sensitive operations (for example, accessing private files or making API calls). Unlike exec/patch approvals which use full-screen overlays, elicitations are handled inline as history cells with approve/deny buttons.

Sources: codex-rs/tui/src/chatwidget.rs73 codex-rs/protocol/src/protocol.rs267-275

Elicitation Event Structure

When core receives ElicitationRequestEvent from an MCP server:

1. The TUI inserts an ElicitationHistoryCell into the transcript with approve/deny buttons
2. User clicks a button, triggering Op::ResolveElicitation with the decision
3. Core forwards the decision to the MCP server
4. The MCP tool call proceeds or fails based on the decision

This inline approach avoids blocking the entire UI for MCP-specific consent flows while maintaining the same approval protocol pattern.

Sources: codex-rs/protocol/src/protocol.rs16 codex-rs/protocol/src/protocol.rs267-275

---

Overlay Integration with Bottom Pane

View Stack Architecture

The BottomPane maintains a view_stack: Vec<Box<dyn BottomPaneView>> where overlays are pushed to replace the composer. Input routing prioritizes the top view:

When an overlay is active:

• Key events are routed to the top view first via BottomPaneView::handle_key_event
• Ctrl+C is offered to the view via on_ctrl_c(), which can dismiss the overlay
• Rendering uses the view's render() implementation instead of the composer

The composer retains its state (text buffer, attachments, history position) while overlays are displayed, so dismissing an overlay restores the draft message exactly as it was.

Sources: codex-rs/tui/src/bottom_pane/mod.rs322-389 codex-rs/tui/src/bottom_pane/mod.rs145-152

Overlay Lifecycle in ChatWidget

ChatWidget orchestrates the approval flow by:

1. Receiving ExecApprovalRequestEvent or similar from the event stream
2. Constructing an ApprovalRequest with the necessary context
3. Emitting AppEvent::FullScreenApprovalRequest
4. The App handles this event by calling BottomPane::show_approval()
5. When the overlay completes, ChatWidget submits the corresponding Op

This separation allows the approval UI to be independent of the core agent implementation while maintaining a clean request/response protocol.

Sources: codex-rs/tui/src/chatwidget.rs91-99 codex-rs/tui/src/app_event.rs339 codex-rs/tui/src/bottom_pane/mod.rs322-366

---

Approval Protocol Details

ExecApproval Op

Submitted in response to ExecApprovalRequestEvent to approve or deny shell command execution:

Op::ExecApproval {
    id: String,                    // Original event submission id
    turn_id: Option<String>,       // Turn context
    decision: ReviewDecision,      // Approved/Rejected/EditAndResubmit
}

The decision field determines what happens next:

• Approved: Command executes via the configured tool handler
• Rejected: Tool call fails with a rejection message to the model
• EditAndResubmit: TUI populates composer with the command for user editing (then submits as Op::UserTurn)

Sources: codex-rs/protocol/src/protocol.rs248-257

PatchApproval Op

Submitted in response to ApplyPatchApprovalRequestEvent to approve or deny file modifications:

Op::PatchApproval {
    id: String,                    // Original event submission id
    decision: ReviewDecision,      // Approved/Rejected/EditAndResubmit
}

Patch approvals follow the same decision model as exec approvals. When approved, core applies the patch and reports success/failure via PatchApplyEndEvent.

Sources: codex-rs/protocol/src/protocol.rs259-265

ReviewDecision Enum

All approval decisions use the ReviewDecision enum:

• Approved: Proceed with the operation
• Rejected: Abort the operation and inform the model
• EditAndResubmit: Return control to the user for manual editing (only available for some approval types)

This shared enum maintains consistency across all approval flows and simplifies downstream handling in core.

Sources: codex-rs/protocol/src/protocol.rs248-265

---

Cancellation and Input Routing

Ctrl+C Handling

Approval overlays implement special Ctrl+C semantics to allow dismissal without approving:

When an overlay consumes Ctrl+C via on_ctrl_c(), it returns CancellationEvent::Handled and the overlay is popped. If not handled, Ctrl+C propagates to ChatWidget where it may trigger the quit shortcut flow.

This ensures users can always escape approval prompts without making a choice, which is critical for avoiding locked UI states.

Sources: codex-rs/tui/src/bottom_pane/mod.rs393-420 codex-rs/tui/src/bottom_pane/mod.rs121-127

Input Priority

The bottom pane input routing follows this priority:

1. Active overlay: Top view on view_stack gets first chance at all input
2. Composer popups: File search, slash commands, skill mentions (when no overlay active)
3. Composer text area: Normal text editing (when no overlay or popup active)
4. Status line Esc: Special case where Esc sends Op::Interrupt when task is running

This layered routing ensures that modal interactions take precedence without disrupting the normal input flow when overlays are dismissed.

Sources: codex-rs/tui/src/bottom_pane/mod.rs328-389

---

Approval Policies and Trust Rules

Policy Context

Approval overlays are only shown when the agent's AskForApproval policy requires user consent. The policy is configured per-session and can be updated via Op::OverrideTurnContext or approval presets. Common policies:

• OnRequest: Model decides when to ask (default)
• UnlessTrusted: Auto-approve safe read-only commands, prompt for everything else
• Never: Auto-approve all commands (useful for non-interactive exec mode)
• Always: Always prompt (not recommended, very noisy)

The overlay displays the current policy context so users understand why they're being prompted.

Sources: codex-rs/protocol/src/protocol.rs390-450 codex-rs/tui/src/chatwidget.rs91-99

Policy Amendments

Some approval overlays offer a "Trust this command" or "Always allow" checkbox that applies a policy amendment. When checked and approved, core updates the persistent exec policy rules to auto-approve matching commands in future turns.

Policy amendments use pattern matching (for exec commands) or file path patterns (for patch operations) to define trust boundaries. This allows users to gradually build up trust rules without fully disabling approval prompts.

Sources: codex-rs/protocol/src/protocol.rs54-59

---

Summary

Interactive overlays provide the TUI's approval flow for tool execution, patch application, and MCP resource access. The system uses:

• ApprovalOverlay for exec and patch approvals (full-screen modal)
• RequestUserInputOverlay for structured model questions (full-screen modal)
• Inline elicitation cells for MCP resource consent (transcript-based)

All overlays use the same view stack architecture in BottomPane, ensuring consistent input routing and Ctrl+C dismissal semantics. The approval protocol is bidirectional: core emits approval request events, the TUI displays overlays and collects user decisions, and submits response ops back to core to continue execution.