cleveragents/cleveragents-core

Fork 3

UAT: TUI double-tap escape for terminal focus exit not implemented — single escape not disambiguated from terminal escape sequences #5081

New issue

Open

opened 2026-04-09 00:56:21 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-09 00:56:21 +00:00

Owner

Bug Report

Feature Area: Sandbox and Checkpoint / TUI Safety Behaviors
Tested By: UAT worker (uat-pool-1), feature area: Sandbox and Checkpoint
Severity: Medium (UX safety behavior missing — users cannot reliably exit terminal focus)

What Was Tested

The TUI double-tap escape behavior for terminal widget focus was checked against the specification's Safety Behaviors section (§Safety Behaviors — Double-Tap Escape for Terminal, lines 30336–30344).

Expected Behavior (from spec)

When a terminal widget (TerminalEmbed or ShellTerminal) has focus, a single escape press is ambiguous — the terminal itself may use escape sequences. The TUI requires a double-tap within 400ms:

First escape: Starts a 400ms timer
Second escape within 400ms: Exits terminal focus, returns focus to the prompt
No second escape within 400ms: The escape keypress is forwarded to the terminal as a normal escape sequence

A flash hint appears on the first escape: Press escape again to exit terminal.

Actual Behavior (from code)

The TUI app (src/cleveragents/tui/app.py) has no escape key handling at all. There is no:

400ms timer for double-tap detection
Flash hint message
Terminal focus exit logic
Escape forwarding to terminal PTY

The BINDINGS list only contains ctrl+q, f1, and ctrl+t. There is no escape binding or on_key handler for escape.

Code Location

src/cleveragents/tui/app.py — no escape handling exists anywhere in the file

Steps to Reproduce

Start the TUI: agents tui
Activate shell mode (press ! or $ at position 0 in the prompt)
Press escape once
Expected: Flash hint "Press escape again to exit terminal", 400ms timer starts
Actual: No response or immediate exit of terminal mode (undefined behavior)

Impact

UX: Users cannot reliably exit terminal focus — the spec-required double-tap mechanism is absent
Safety: Without the 400ms disambiguation, escape sequences intended for the terminal may accidentally exit terminal focus
Accessibility: The flash hint "Press escape again to exit terminal" is never shown, leaving users without guidance

§Safety Behaviors — Double-Tap Escape for Terminal (lines 30336–30344):

When a terminal widget (TerminalEmbed or ShellTerminal) has focus, a single escape press is ambiguous — the terminal itself may use escape sequences. The TUI requires a double-tap within 400ms:

First escape: Starts a 400ms timer

Second escape within 400ms: Exits terminal focus, returns focus to the prompt

No second escape within 400ms: The escape keypress is forwarded to the terminal as a normal escape sequence
A flash hint appears on the first escape: Press escape again to exit terminal.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report **Feature Area**: Sandbox and Checkpoint / TUI Safety Behaviors **Tested By**: UAT worker (uat-pool-1), feature area: Sandbox and Checkpoint **Severity**: Medium (UX safety behavior missing — users cannot reliably exit terminal focus) --- ## What Was Tested The TUI double-tap escape behavior for terminal widget focus was checked against the specification's Safety Behaviors section (§Safety Behaviors — Double-Tap Escape for Terminal, lines 30336–30344). ## Expected Behavior (from spec) When a terminal widget (TerminalEmbed or ShellTerminal) has focus, a single `escape` press is ambiguous — the terminal itself may use escape sequences. The TUI requires a double-tap within 400ms: 1. **First `escape`**: Starts a 400ms timer 2. **Second `escape` within 400ms**: Exits terminal focus, returns focus to the prompt 3. **No second `escape` within 400ms**: The escape keypress is forwarded to the terminal as a normal escape sequence A flash hint appears on the first escape: `Press escape again to exit terminal`. ## Actual Behavior (from code) The TUI app (`src/cleveragents/tui/app.py`) has no escape key handling at all. There is no: - 400ms timer for double-tap detection - Flash hint message - Terminal focus exit logic - Escape forwarding to terminal PTY The `BINDINGS` list only contains `ctrl+q`, `f1`, and `ctrl+t`. There is no `escape` binding or `on_key` handler for escape. ## Code Location `src/cleveragents/tui/app.py` — no escape handling exists anywhere in the file ## Steps to Reproduce 1. Start the TUI: `agents tui` 2. Activate shell mode (press `!` or `$` at position 0 in the prompt) 3. Press `escape` once 4. Expected: Flash hint "Press escape again to exit terminal", 400ms timer starts 5. Actual: No response or immediate exit of terminal mode (undefined behavior) ## Impact - **UX**: Users cannot reliably exit terminal focus — the spec-required double-tap mechanism is absent - **Safety**: Without the 400ms disambiguation, escape sequences intended for the terminal may accidentally exit terminal focus - **Accessibility**: The flash hint "Press escape again to exit terminal" is never shown, leaving users without guidance ## Related Spec Section §Safety Behaviors — Double-Tap Escape for Terminal (lines 30336–30344): > When a terminal widget (TerminalEmbed or ShellTerminal) has focus, a single `escape` press is ambiguous — the terminal itself may use escape sequences. The TUI requires a double-tap within 400ms: > 1. First `escape`: Starts a 400ms timer > 2. Second `escape` within 400ms: Exits terminal focus, returns focus to the prompt > 3. No second `escape` within 400ms: The escape keypress is forwarded to the terminal as a normal escape sequence > A flash hint appears on the first escape: `Press escape again to exit terminal`. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 00:56:26 +00:00

HAL9000 added this to the v3.7.0 milestone

2026-04-09 01:02:20 +00:00

HAL9000 commented

2026-04-09 01:02:20 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — TUI spec compliance bug; deviates from documented TUI behavior
Milestone: v3.7.0 (TUI milestone)
Story Points: 3 — M
MoSCoW: Must Have — TUI spec compliance is required for the TUI Legendary
Parent Epic: #4963 or #4966 (TUI Epics)

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — TUI spec compliance bug; deviates from documented TUI behavior - **Milestone**: v3.7.0 (TUI milestone) - **Story Points**: 3 — M - **MoSCoW**: Must Have — TUI spec compliance is required for the TUI Legendary - **Parent Epic**: #4963 or #4966 (TUI Epics) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 added a new dependency

2026-04-09 01:05:04 +00:00

#4963 EPIC: TUI Core Layout & Navigation — MainScreen, Sidebar, Hotkeys

HAL9000 referenced this issue

2026-04-09 01:05:25 +00:00

[AUTO-PROJ-OWN] Project Owner Report (Cycle 2) #5115

~~HAL9000 referenced this issue 2026-04-09 01:06:02 +00:00~~

[AUTO-EPIC] Epic Planning Health Report (Cycle 1) #4985

HAL9000 referenced this issue

2026-04-09 05:51:33 +00:00

feat(tui): implement ctrl+c double-tap interrupt behavior and escape double-tap terminal focus exit #5327

~~HAL9000 referenced this issue 2026-04-09 05:54:23 +00:00~~