feat(cli): support Ctrl-Z suspension

- Implement Ctrl+Z suspension with robust terminal state handling.
- Rebind Undo/Redo to Alt+Z / Alt+Shift+Z to avoid conflicts.
- Fix macOS Option key character mapping for Undo/Redo.
- Improve type safety for app.rerender() in AppContainer.
- Add comprehensive suspension test suite.
- Fix environment leakage in core tests.
- Update keyboard shortcut documentation.

Fixes google-gemini#5018

Author: brtkwr

docs/cli/keyboard-shortcuts.md

@@ -118,7 +118,7 @@ available combinations.
 | Focus the Gemini input from the shell input.                                                          | `Tab`                      |
 | Clear the terminal screen and redraw the UI.                                                          | `Ctrl + L`                 |
 | Restart the application.                                                                              | `R`                        |
-| Suspend the application (not yet implemented).                                                        | `Ctrl + Z`                 |
+| Suspend the CLI and move it to the background.                                                        | `Ctrl + Z`                 |
 
 <!-- KEYBINDINGS-AUTOGEN:END -->
 
@@ -137,4 +137,4 @@ available combinations.
   the numbered radio option and confirm when the full number is entered.
 - `Double-click` on a paste placeholder (`[Pasted Text: X lines]`) in alternate
   buffer mode: Expand to view full content inline. Double-click again to
-  collapse.
+  collapse.

packages/cli/src/config/keyBindings.ts

@@ -94,7 +94,7 @@ export enum Command {
   UNFOCUS_SHELL_INPUT = 'app.unfocusShellInput',
   CLEAR_SCREEN = 'app.clearScreen',
   RESTART_APP = 'app.restart',
-  SUSPEND_APP = 'app.suspend',
+  SUSPEND = 'app.suspend',
 }
 
 /**
@@ -283,6 +283,7 @@ export const defaultKeyBindings: KeyBindingConfig = {
   ],
   [Command.BACKGROUND_SHELL_SELECT]: [{ key: 'return' }],
   [Command.BACKGROUND_SHELL_ESCAPE]: [{ key: 'escape' }],
+  [Command.SUSPEND]: [{ key: 'z', ctrl: true }],
   [Command.SHOW_MORE_LINES]: [
     { key: 'o', ctrl: true },
     { key: 's', ctrl: true },
@@ -291,7 +292,6 @@ export const defaultKeyBindings: KeyBindingConfig = {
   [Command.UNFOCUS_SHELL_INPUT]: [{ key: 'tab' }],
   [Command.CLEAR_SCREEN]: [{ key: 'l', ctrl: true }],
   [Command.RESTART_APP]: [{ key: 'r' }],
-  [Command.SUSPEND_APP]: [{ key: 'z', ctrl: true }],
 };
 
 interface CommandCategory {
@@ -409,7 +409,7 @@ export const commandCategories: readonly CommandCategory[] = [
       Command.UNFOCUS_SHELL_INPUT,
       Command.CLEAR_SCREEN,
       Command.RESTART_APP,
-      Command.SUSPEND_APP,
+      Command.SUSPEND,
     ],
   },
 ];
@@ -494,6 +494,7 @@ export const commandDescriptions: Readonly<Record<Command, string>> = {
   [Command.TOGGLE_YOLO]: 'Toggle YOLO (auto-approval) mode for tool calls.',
   [Command.CYCLE_APPROVAL_MODE]:
     'Cycle through approval modes: default (prompt), auto_edit (auto-approve edits), and plan (read-only).',
+  [Command.SUSPEND]: 'Suspend the CLI and move it to the background.',
   [Command.SHOW_MORE_LINES]:
     'Expand a height-constrained response to show additional lines when not in alternate buffer mode.',
   [Command.BACKGROUND_SHELL_SELECT]: 'Enter',
@@ -508,5 +509,4 @@ export const commandDescriptions: Readonly<Record<Command, string>> = {
   [Command.UNFOCUS_SHELL_INPUT]: 'Focus the Gemini input from the shell input.',
   [Command.CLEAR_SCREEN]: 'Clear the terminal screen and redraw the UI.',
   [Command.RESTART_APP]: 'Restart the application.',
-  [Command.SUSPEND_APP]: 'Suspend the application (not yet implemented).',
 };