fix(terminal): Shift+Enter inserts a newline instead of submitting

src/renderer/src/components/terminalKeys.ts

@@ -0,0 +1,51 @@
+/**
+ * Modifier-key encoding for the embedded terminal.
+ *
+ * xterm.js encodes Shift+Enter exactly like Enter — a bare CR — so a TUI cannot
+ * tell the two apart, and Shift+Enter at a prompt submits instead of opening a
+ * new line (#481). Terminals that get this right send a distinct sequence, and
+ * the one Claude Code's `/terminal-setup` installs for iTerm2 and VS Code is
+ * ESC CR. Nothing configures that for our pane, so it has to be sent here.
+ *
+ * Kept structural and free of imports — no xterm, no window — so the mapping is
+ * unit-testable on its own, the same way askMeOrder.ts and queueDelivery.ts are.
+ * The caller supplies the fields it reads from a KeyboardEvent.
+ */
+
+/** ESC CR — "insert a newline, do not submit". Provider-neutral: it is the
+ *  convention `/terminal-setup` writes for Claude Code, and the same sequence
+ *  Alt+Enter has always produced, so any TUI that honours one honours the other. */
+export const NEWLINE_SEQUENCE = '\x1b\r';
+
+/** The fields this needs from a KeyboardEvent. */
+export interface TerminalKey {
+  type: string;
+  key: string;
+  shiftKey: boolean;
+  ctrlKey: boolean;
+  metaKey: boolean;
+  altKey: boolean;
+}
+
+/**
+ * The bytes to send for a key the terminal would otherwise encode wrongly, or
+ * null to let xterm handle it as usual.
+ *
+ * Deliberately narrow. Only Shift+Enter is claimed, and only when it is the ONLY
+ * modifier held:
+ *   - plain Enter still submits, which is the whole point of the prompt;
+ *   - Alt+Enter already produces this sequence natively, so intercepting it
+ *     would be a no-op at best and a double-encode at worst;
+ *   - Ctrl+Enter and Cmd+Enter belong to the TUI (and to the app's own
+ *     shortcuts), so they are left alone rather than quietly redefined.
+ *
+ * keydown only: xterm's custom-key hook also sees keypress and keyup, and
+ * answering on more than one of them would insert the newline two or three times.
+ */
+export function terminalKeySequence(ev: TerminalKey): string | null {
+  if (ev.type !== 'keydown') return null;
+  if (ev.key !== 'Enter') return null;
+  if (!ev.shiftKey) return null;
+  if (ev.ctrlKey || ev.metaKey || ev.altKey) return null;
+  return NEWLINE_SEQUENCE;
+}

src/renderer/src/components/terminalPool.ts

@@ -39,6 +39,7 @@ import {
   type TerminalAutomationBlock
 } from './terminalAutomation';
 import { sanitizeTerminalSelection } from './terminalSelection';
+import { terminalKeySequence } from './terminalKeys';
 import '@xterm/xterm/css/xterm.css';
 
 export interface TerminalEntry {
@@ -255,6 +256,18 @@ export function acquireTerminal(ptyId: string, theme?: ThemeMap, fontSize = 14):
   };
   term.attachCustomKeyEventHandler((ev) => {
     if (ev.type !== 'keydown') return true;
+    // Keys xterm would encode in a way the TUI cannot read. Checked BEFORE the
+    // Ctrl/Cmd gate below, because Shift+Enter holds neither: without this it
+    // fell straight through to xterm's default, which sends the same bare CR as
+    // Enter — so Shift+Enter submitted the prompt instead of opening a new line
+    // (#481). Writing to the pty directly is the same path the OSC colour replies
+    // below already use.
+    const seq = terminalKeySequence(ev);
+    if (seq !== null) {
+      if (!entry.exited) window.cth.writePty(ptyId, seq);
+      ev.preventDefault();
+      return false;
+    }
     if (!(ev.ctrlKey || ev.metaKey)) return true;
     const key = ev.key.toLowerCase();
     if (key === 'c' && (ev.shiftKey || term.hasSelection())) {

test/terminal-keys.test.cjs

@@ -0,0 +1,51 @@
+'use strict';
+/**
+ * Upstream issue #481: Shift+Enter at a prompt inside the embedded terminal
+ * submits instead of inserting a newline. xterm.js encodes Shift+Enter exactly
+ * like Enter — a bare CR — so the TUI cannot tell them apart. Terminals that
+ * get this right send ESC CR, which is what Claude Code's `/terminal-setup`
+ * installs for iTerm2 and VS Code; nothing configures our pane, so the pane has
+ * to send it. These tests pin the mapping, and pin how narrow it is: every other
+ * Enter combination is left to xterm and to the TUI.
+ */
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const loadTs = require('./load-ts.cjs');
+
+const { terminalKeySequence, NEWLINE_SEQUENCE } = loadTs('src/renderer/src/components/terminalKeys.ts');
+
+/** A KeyboardEvent as the handler sees it. */
+const key = (over = {}) => ({
+  type: 'keydown', key: 'Enter',
+  shiftKey: false, ctrlKey: false, metaKey: false, altKey: false, ...over
+});
+
+test('Shift+Enter sends ESC CR — the sequence /terminal-setup installs', () => {
+  assert.equal(terminalKeySequence(key({ shiftKey: true })), '\x1b\r');
+  assert.equal(NEWLINE_SEQUENCE, '\x1b\r');
+});
+
+test('plain Enter is left alone, so the prompt still submits', () => {
+  assert.equal(terminalKeySequence(key()), null);
+});
+
+test('Enter with another modifier is left to the TUI', () => {
+  // Alt+Enter already produces ESC CR natively — intercepting it would double-encode.
+  assert.equal(terminalKeySequence(key({ shiftKey: true, altKey: true })), null);
+  assert.equal(terminalKeySequence(key({ altKey: true })), null);
+  // Ctrl+Enter / Cmd+Enter belong to the TUI and to the app's own shortcuts.
+  assert.equal(terminalKeySequence(key({ shiftKey: true, ctrlKey: true })), null);
+  assert.equal(terminalKeySequence(key({ shiftKey: true, metaKey: true })), null);
+});
+
+test('only keydown answers, so the newline is not inserted two or three times', () => {
+  // xterm's custom-key hook also sees keypress and keyup for the same press.
+  assert.equal(terminalKeySequence(key({ shiftKey: true, type: 'keypress' })), null);
+  assert.equal(terminalKeySequence(key({ shiftKey: true, type: 'keyup' })), null);
+});
+
+test('Shift with any other key is not claimed', () => {
+  for (const k of ['a', 'Tab', 'Backspace', 'ArrowUp', 'NumpadEnter']) {
+    assert.equal(terminalKeySequence(key({ shiftKey: true, key: k })), null, k);
+  }
+});