TUI: Shift+Enter submits instead of newline on macOS Terminal.app and Alacritty

[ivrylobs]

Issue

In the Hermes interactive TUI on macOS, Shift+Enter submits the message instead of inserting a newline. The only working multi-line input method is Escape then Enter.

Ctrl+Enter has the same problem — it submits rather than inserting a newline.

Expected behavior

• Shift+Enter → insert newline (standard convention across chat apps and most AI agent CLIs)
• Ctrl+Enter → insert newline
• Alt/Option+Enter → insert newline (works with Option-as-Meta terminal setting)
• Esc then Enter → insert newline (currently works, but not discoverable)
• Enter → submit

Actual behavior

Shift+Enter and Ctrl+Enter are not distinguished from plain Enter — all three submit immediately.

Root Cause Analysis

macOS Terminal.app and Alacritty send the same byte (\\r) for Enter, Shift+Enter, and Ctrl+Enter. The key modifier is lost at the terminal/OS layer and never reaches prompt_toolkit. So there is no byte sequence for Hermes to intercept and rebind.

The existing ANSI escape aliases in hermes_cli/pt_input_extras.py (for \\x1b[13;2u, \\x1b[27;2;13~, etc.) only fire in terminals that implement the Kitty keyboard protocol or xterm modifyOtherKeys — which macOS Terminal.app and Alacritty do not enable by default.

Alt/Option+Enter works because macOS terminals can send Option as "Meta" (Escape prefix), producing \\x1b\\r (Escape + Enter), which prompt_toolkit sees as (Escape, Enter) and triggers the existing kb.add('escape', 'enter') newline handler.

Terminals Tested

Terminal	OS	Shift+Enter	Ctrl+Enter	Alt/Option+Enter	Esc+Enter
Terminal.app	macOS 26.4.1	Submit	Submit	Newline (Meta enabled)	Newline
Alacritty	macOS 26.4.1	Submit	Submit	Newline (Meta enabled)	Newline

Note: _preserve_ctrl_enter_newline() in cli.py (line 1913) returns False on native macOS, so c-j is bound to submit (line 1959) rather than newline. This is correct for SSH/docker-over-TTY where \\n IS the Enter key, but it means Ctrl+Enter has no newline path on POSIX.

Proposed Solutions

Option 1: Document a workaround (lowest effort)

Add a note to the docs / /help output explaining that on macOS Terminal.app and Alacritty, users must either:

1. Enable Option-as-Meta for Alt+Enter newline
2. Use Esc then Enter

This is honest but does not improve the UX.

Option 2: Add a config setting for a dedicated newline key (medium effort)

Allow users to bind an additional key to "insert newline" in config.yaml:

tui:
  newline_key: c-n   # or "c-o", "m-enter", etc.

Users who find Esc+Enter awkward could pick Ctrl+N (or another unused key) as their newline. This would require adding a config knob and wiring it into the keybinding section of cli.py (_bind_prompt_submit_keys area, around line 1944-1960).

Option 3: Double-Enter for multi-line (highest UX impact)

Detect when the user types Enter on an empty line or at the end of their input to insert a newline, and only submit on a second Enter. This is how some chat apps work (e.g., Slack in certain modes). Would require a small change to the submit handler logic.

Option 4: Kitty keyboard protocol support in TUI

Enable the Kitty keyboard protocol in the prompt_appkit TUI (the app already enables some kitty features at line 1906-1908). If prompt_toolkit supports Kitty keyboard mode natively or via a plugin, enabling it could make Shift+Enter/Ctrl+Enter emit distinct CSI-u sequences, making the existing pt_input_extras.py mappings work.

Related Issues

• [UX] Add Shift+Enter newline support in CLI input #5346 -- [UX] Add Shift+Enter newline support in CLI input
• TUI: Shift+Enter and Alt+Enter both submit instead of inserting newline in Warp terminal #21512 -- TUI Shift+Enter/Alt+Enter both submit in Warp terminal
• [Docker] Shift+Enter / Alt+Enter newline does not work in TUI via docker exec #15824 -- [Docker] Shift+Enter/Alt+Enter newline does not work in TUI via docker exec

[alt-glitch]

Duplicate of #22909 — same fundamental limitation: macOS Terminal.app and Alacritty don't send distinct escape sequences for Shift+Enter/Ctrl+Enter (all map to \r). Fix PR #22917 is open for the TUI path. Workaround: Escape then Enter, or Option+Enter with Meta enabled.

[teknium1]

Closing as duplicate of #22909.

Triage notes (high confidence):
Already labeled duplicate. Maintainer comment by @alt-glitch: 'Duplicate of #22909 — same fundamental limitation: macOS Terminal.app and Alacritty don't send distinct escape sequences for Shift+Enter/Ctrl+Enter (all map to \r). Fix PR #22917 is open for the TUI path.'

Please follow #22909 for updates. If this isn't actually a duplicate, comment and we'll reopen.

(Bulk-closed during a CLI issue triage sweep.)