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 #5018

refactor(cli): address suspend PR review feedback

Author: brtkwr

docs/cli/keyboard-shortcuts.md

@@ -120,7 +120,7 @@ available combinations.
 | Move focus from the shell back to Gemini.                                                             | `Shift + 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 -->
 

packages/cli/src/config/keyBindings.ts

@@ -523,5 +523,5 @@ export const commandDescriptions: Readonly<Record<Command, string>> = {
   [Command.UNFOCUS_SHELL_INPUT]: 'Move focus from the shell back to Gemini.',
   [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).',
+  [Command.SUSPEND_APP]: 'Suspend the CLI and move it to the background.',
 };

packages/cli/src/ui/AppContainer.test.tsx

@@ -135,6 +135,7 @@ vi.mock('./hooks/useFocus.js');
 vi.mock('./hooks/useBracketedPaste.js');
 vi.mock('./hooks/useKeypress.js');
 vi.mock('./hooks/useLoadingIndicator.js');
+vi.mock('./hooks/useSuspend.js');
 vi.mock('./hooks/useFolderTrust.js');
 vi.mock('./hooks/useIdeTrustListener.js');
 vi.mock('./hooks/useMessageQueue.js');
@@ -198,6 +199,7 @@ import { useLogger } from './hooks/useLogger.js';
 import { useLoadingIndicator } from './hooks/useLoadingIndicator.js';
 import { useInputHistoryStore } from './hooks/useInputHistoryStore.js';
 import { useKeypress, type Key } from './hooks/useKeypress.js';
+import { useSuspend } from './hooks/useSuspend.js';
 import { measureElement } from 'ink';
 import { useTerminalSize } from './hooks/useTerminalSize.js';
 import {
@@ -269,6 +271,7 @@ describe('AppContainer State Management', () => {
   const mockedUseLogger = useLogger as Mock;
   const mockedUseLoadingIndicator = useLoadingIndicator as Mock;
   const mockedUseKeypress = useKeypress as Mock;
+  const mockedUseSuspend = useSuspend as Mock;
   const mockedUseInputHistoryStore = useInputHistoryStore as Mock;
   const mockedUseHookDisplayState = useHookDisplayState as Mock;
   const mockedUseTerminalTheme = useTerminalTheme as Mock;
@@ -400,6 +403,9 @@ describe('AppContainer State Management', () => {
       elapsedTime: '0.0s',
       currentLoadingPhrase: '',
     });
+    mockedUseSuspend.mockReturnValue({
+      handleSuspend: vi.fn(),
+    });
     mockedUseHookDisplayState.mockReturnValue([]);
     mockedUseTerminalTheme.mockReturnValue(undefined);
     mockedUseShellInactivityStatus.mockReturnValue({
@@ -1970,6 +1976,19 @@ describe('AppContainer State Management', () => {
       });
     });
 
+    describe('CTRL+Z', () => {
+      it('should call handleSuspend', async () => {
+        const handleSuspend = vi.fn();
+        mockedUseSuspend.mockReturnValue({ handleSuspend });
+        await setupKeypressTest();
+
+        pressKey({ name: 'z', ctrl: true });
+
+        expect(handleSuspend).toHaveBeenCalledTimes(1);
+        unmount();
+      });
+    });
+
     describe('Focus Handling (Tab / Shift+Tab)', () => {
       beforeEach(() => {
         // Mock activePtyId to enable focus

packages/cli/src/ui/AppContainer.tsx

@@ -12,7 +12,14 @@ import {
   useRef,
   useLayoutEffect,
 } from 'react';
-import { type DOMElement, measureElement } from 'ink';
+import {
+  type DOMElement,
+  measureElement,
+  useApp,
+  useStdout,
+  useStdin,
+  type AppProps,
+} from 'ink';
 import { App } from './App.js';
 import { AppContext } from './contexts/AppContext.js';
 import { UIStateContext, type UIState } from './contexts/UIStateContext.js';
@@ -87,7 +94,6 @@ import { useVimMode } from './contexts/VimModeContext.js';
 import { useConsoleMessages } from './hooks/useConsoleMessages.js';
 import { useTerminalSize } from './hooks/useTerminalSize.js';
 import { calculatePromptWidths } from './components/InputPrompt.js';
-import { useApp, useStdout, useStdin } from 'ink';
 import { calculateMainAreaWidth } from './utils/ui-sizing.js';
 import ansiEscapes from 'ansi-escapes';
 import { basename } from 'node:path';
@@ -145,7 +151,7 @@ import { NewAgentsChoice } from './components/NewAgentsNotification.js';
 import { isSlashCommand } from './utils/commandUtils.js';
 import { useTerminalTheme } from './hooks/useTerminalTheme.js';
 import { useTimedMessage } from './hooks/useTimedMessage.js';
-import { isITerm2 } from './utils/terminalUtils.js';
+import { useSuspend } from './hooks/useSuspend.js';
 
 function isToolExecuting(pendingHistoryItems: HistoryItemWithoutId[]) {
   return pendingHistoryItems.some((item) => {
@@ -199,6 +205,7 @@ export const AppContainer = (props: AppContainerProps) => {
   useMemoryMonitor(historyManager);
   const isAlternateBuffer = useAlternateBuffer();
   const [corgiMode, setCorgiMode] = useState(false);
+  const [forceRerenderKey, setForceRerenderKey] = useState(0);
   const [debugMessage, setDebugMessage] = useState<string>('');
   const [quittingMessages, setQuittingMessages] = useState<
     HistoryItem[] | null
@@ -345,7 +352,7 @@ export const AppContainer = (props: AppContainerProps) => {
   const { columns: terminalWidth, rows: terminalHeight } = useTerminalSize();
   const { stdin, setRawMode } = useStdin();
   const { stdout } = useStdout();
-  const app = useApp();
+  const app: AppProps = useApp();
 
   // Additional hooks moved from App.tsx
   const { stats: sessionStats } = useSessionStats();
@@ -1366,6 +1373,23 @@ Logging in with Google... Restarting Gemini CLI to continue.
     };
   }, [showTransientMessage]);
 
+  const handleWarning = useCallback(
+    (message: string) => {
+      showTransientMessage({
+        text: message,
+        type: TransientMessageType.Warning,
+      });
+    },
+    [showTransientMessage],
+  );
+
+  const { handleSuspend } = useSuspend({
+    handleWarning,
+    setRawMode,
+    refreshStatic,
+    setForceRerenderKey,
+  });
+
   useEffect(() => {
     if (ideNeedsRestart) {
       // IDE trust changed, force a restart.
@@ -1517,6 +1541,9 @@ Logging in with Google... Restarting Gemini CLI to continue.
       } else if (keyMatchers[Command.EXIT](key)) {
         setCtrlDPressCount((prev) => prev + 1);
         return true;
+      } else if (keyMatchers[Command.SUSPEND_APP](key)) {
+        handleSuspend();
+        return true;
       }
 
       let enteringConstrainHeightMode = false;
@@ -1528,15 +1555,6 @@ Logging in with Google... Restarting Gemini CLI to continue.
       if (keyMatchers[Command.SHOW_ERROR_DETAILS](key)) {
         setShowErrorDetails((prev) => !prev);
         return true;
-      } else if (keyMatchers[Command.SUSPEND_APP](key)) {
-        const undoMessage = isITerm2()
-          ? 'Undo has been moved to Option + Z'
-          : 'Undo has been moved to Alt/Option + Z or Cmd + Z';
-        showTransientMessage({
-          text: undoMessage,
-          type: TransientMessageType.Warning,
-        });
-        return true;
       } else if (keyMatchers[Command.SHOW_FULL_TODOS](key)) {
         setShowFullTodos((prev) => !prev);
         return true;
@@ -1645,11 +1663,12 @@ Logging in with Google... Restarting Gemini CLI to continue.
       handleSlashCommand,
       cancelOngoingRequest,
       activePtyId,
+      handleSuspend,
       embeddedShellFocused,
       settings.merged.general.debugKeystrokeLogging,
       refreshStatic,
-      setCopyModeEnabled,
-      copyModeEnabled,
+      tabFocusTimeoutRef,
+      handleWarning,
       isAlternateBuffer,
       backgroundCurrentShell,
       toggleBackgroundShell,
@@ -1659,6 +1678,9 @@ Logging in with Google... Restarting Gemini CLI to continue.
       lastOutputTimeRef,
       tabFocusTimeoutRef,
       showTransientMessage,
+      handleWarning,
+      setCopyModeEnabled,
+      copyModeEnabled,
     ],
   );
 
@@ -2223,7 +2245,7 @@ Logging in with Google... Restarting Gemini CLI to continue.
           >
             <ToolActionsProvider config={config} toolCalls={allToolCalls}>
               <ShellFocusContext.Provider value={isFocused}>
-                <App />
+                <App key={`app-${forceRerenderKey}`} />
               </ShellFocusContext.Provider>
             </ToolActionsProvider>
           </AppContext.Provider>

packages/cli/src/ui/components/__snapshots__/InputPrompt.test.tsx.snap

@@ -77,6 +77,12 @@ exports[`InputPrompt > mouse interaction > should toggle paste expansion on doub
 ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄"
 `;
 
+exports[`InputPrompt > mouse interaction > should toggle paste expansion on double-click 4`] = `
+"▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+ > [Pasted Text: 10 lines]
+▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄"
+`;
+
 exports[`InputPrompt > snapshots > should not show inverted cursor when shell is focused 1`] = `
 "▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  >   Type your message or @path/to/file

packages/cli/src/ui/hooks/useSuspend.ts

@@ -0,0 +1,109 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useState, useRef, useEffect, useCallback } from 'react';
+import {
+  writeToStdout,
+  disableMouseEvents,
+  enableMouseEvents,
+} from '@google/gemini-cli-core';
+import process from 'node:process';
+import {
+  cleanupTerminalOnExit,
+  terminalCapabilityManager,
+} from '../utils/terminalCapabilityManager.js';
+import { WARNING_PROMPT_DURATION_MS } from '../constants.js';
+
+interface UseSuspendProps {
+  handleWarning: (message: string) => void;
+  setRawMode: (mode: boolean) => void;
+  refreshStatic: () => void;
+  setForceRerenderKey: (updater: (prev: number) => number) => void;
+}
+
+export function useSuspend({
+  handleWarning,
+  setRawMode,
+  refreshStatic,
+  setForceRerenderKey,
+}: UseSuspendProps) {
+  const [ctrlZPressCount, setCtrlZPressCount] = useState(0);
+  const ctrlZTimerRef = useRef<NodeJS.Timeout | null>(null);
+
+  useEffect(() => {
+    if (ctrlZTimerRef.current) {
+      clearTimeout(ctrlZTimerRef.current);
+      ctrlZTimerRef.current = null;
+    }
+    if (ctrlZPressCount > 1) {
+      setCtrlZPressCount(0);
+      if (process.platform === 'win32') {
+        handleWarning('Ctrl+Z suspend is not supported on Windows.');
+        return;
+      }
+
+      // Cleanup before suspend.
+      writeToStdout('\x1b[?25h'); // Show cursor
+      disableMouseEvents();
+      cleanupTerminalOnExit();
+
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+      }
+      setRawMode(false);
+
+      const onResume = () => {
+        // Restore terminal state.
+        if (process.stdin.isTTY) {
+          process.stdin.setRawMode(true);
+          process.stdin.resume();
+          process.stdin.ref();
+        }
+        setRawMode(true);
+
+        terminalCapabilityManager.enableSupportedModes();
+        writeToStdout('\x1b[?25l'); // Hide cursor
+        enableMouseEvents();
+
+        // Force Ink to do a complete repaint by:
+        // 1. Emitting a resize event (tricks Ink into full redraw)
+        // 2. Remounting components via state changes
+        process.stdout.emit('resize');
+
+        // Give a tick for resize to process, then trigger remount
+        setImmediate(() => {
+          refreshStatic();
+          setForceRerenderKey((prev) => prev + 1);
+        });
+
+        process.off('SIGCONT', onResume);
+      };
+      process.on('SIGCONT', onResume);
+
+      process.kill(0, 'SIGTSTP');
+    } else if (ctrlZPressCount > 0) {
+      handleWarning(
+        'Press Ctrl+Z again to suspend. Undo has moved to Cmd + Z or Alt/Opt + Z.',
+      );
+      ctrlZTimerRef.current = setTimeout(() => {
+        setCtrlZPressCount(0);
+        ctrlZTimerRef.current = null;
+      }, WARNING_PROMPT_DURATION_MS);
+    }
+  }, [
+    ctrlZPressCount,
+    handleWarning,
+    setRawMode,
+    refreshStatic,
+    setForceRerenderKey,
+  ]);
+
+  const handleSuspend = useCallback(() => {
+    setCtrlZPressCount((prev) => prev + 1);
+  }, []);
+
+  return { handleSuspend };
+}

packages/cli/src/ui/keyMatchers.test.ts

@@ -330,6 +330,18 @@ describe('keyMatchers', () => {
       positive: [createKey('d', { ctrl: true })],
       negative: [createKey('d'), createKey('c', { ctrl: true })],
     },
+    {
+      command: Command.SUSPEND_APP,
+      positive: [
+        createKey('z', { ctrl: true }),
+        createKey('z', { ctrl: true, shift: true }),
+      ],
+      negative: [
+        createKey('z'),
+        createKey('y', { ctrl: true }),
+        createKey('z', { alt: true }),
+      ],
+    },
     {
       command: Command.SHOW_MORE_LINES,
       positive: [

packages/cli/src/ui/utils/terminalCapabilityManager.ts

@@ -18,6 +18,13 @@ import { parseColor } from '../themes/color-utils.js';
 
 export type TerminalBackgroundColor = string | undefined;
 
+export function cleanupTerminalOnExit() {
+  // Don't bother catching errors since if one write fails, the others likely will.
+  disableKittyKeyboardProtocol();
+  disableModifyOtherKeys();
+  disableBracketedPasteMode();
+}
+
 export class TerminalCapabilityManager {
   private static instance: TerminalCapabilityManager | undefined;
 
@@ -77,16 +84,9 @@ export class TerminalCapabilityManager {
       return;
     }
 
-    const cleanupOnExit = () => {
-      // don't bother catching errors since if one write
-      // fails, the other probably will too
-      disableKittyKeyboardProtocol();
-      disableModifyOtherKeys();
-      disableBracketedPasteMode();
-    };
-    process.on('exit', cleanupOnExit);
-    process.on('SIGTERM', cleanupOnExit);
-    process.on('SIGINT', cleanupOnExit);
+    process.on('exit', cleanupTerminalOnExit);
+    process.on('SIGTERM', cleanupTerminalOnExit);
+    process.on('SIGINT', cleanupTerminalOnExit);
 
     return new Promise((resolve) => {
       const originalRawMode = process.stdin.isRaw;