hermes - 💡(How to fix) Fix macOS iTerm2: Shift+Enter should insert newline in prompt_toolkit CLI

Description

On macOS iTerm2, pressing Shift+Enter in the default hermes CLI (prompt_toolkit-based) submits the prompt instead of inserting a newline. Users composing multi-line messages (code blocks, long prompts) cannot insert line breaks.

This is a common convention in CLI tools — Claude Code, Warp, OpenAI Codex CLI all support Shift+Enter for newline insertion.

Steps to Reproduce

1. Open iTerm2 on macOS
2. Run hermes (default prompt_toolkit CLI)
3. Type a partial sentence, then press Shift+Enter
4. The prompt submits instead of inserting a newline

Expected Behavior

Shift+Enter should insert a newline in the input buffer, allowing multi-line message composition. Enter (without Shift) should still submit.

Environment

• OS: macOS 26.5
• Terminal: iTerm2
• Hermes mode: CLI (prompt_toolkit, the default hermes command)
• Related PRs:
  • #31176 — portable newline keys in the TUI (React/Ink-based composer, not the prompt_toolkit CLI)
  • #31285 — fix for Warp Shift+Enter (different terminal app)
  • #23650, #23921, #21512 — previous Shift+Enter fixes

Suggested Fix

In iTerm2 with default settings (no kitty keyboard protocol / CSI-u), Shift+Enter typically sends the same byte sequence as plain Enter (\r). Without a distinct keycode, prompt_toolkit cannot distinguish Shift+Enter from Enter.

Possible approaches in the prompt_toolkit CLI (cli.py / _bind_prompt_submit_keys):

1. Backslash+Enter inline escape — same approach as #31176's resolveReturn: if the character before the cursor is a backslash, consume it and insert \n in-place. Universal, no terminal detection needed.
2. Ctrl+J / Ctrl+M hotkeys — document that Ctrl+J inserts a newline on macOS (as the Windows section already documents for Windows Terminal).
3. Terminal probe — detect iTerm2 and register a c-j -> newline binding, similar to _preserve_ctrl_enter_newline().

The backslash+Enter approach is simplest and matches Claude Code's convention.