docs(cli): update keyboard shortcut documentation for unfocus shell input

- Update Command.UNFOCUS_SHELL_INPUT to explicitly require shift: true.
- Allow UNFOCUS_SHELL_INPUT to bubble up from ShellInputPrompt.
- Update AppContainer to handle UNFOCUS_SHELL_INPUT for unfocusing the shell.
- Add unit tests for ShellInputPrompt and AppContainer.

docs/cli/keyboard-shortcuts.md

@@ -115,7 +115,7 @@ available combinations.
 | Tab                                                                                                   | `Tab (no Shift)`           |
 | Tab                                                                                                   | `Tab (no Shift)`           |
 | Focus the shell input from the gemini input.                                                          | `Tab (no Shift)`           |
-| Focus the Gemini input from the shell input.                                                          | `Tab`                      |
+| Focus the Gemini input from the shell input.                                                          | `Shift + Tab`              |
 | Clear the terminal screen and redraw the UI.                                                          | `Ctrl + L`                 |
 | Restart the application.                                                                              | `R`                        |
 | Suspend the application (not yet implemented).                                                        | `Ctrl + Z`                 |

packages/cli/src/config/keyBindings.ts

@@ -288,7 +288,7 @@ export const defaultKeyBindings: KeyBindingConfig = {
     { key: 's', ctrl: true },
   ],
   [Command.FOCUS_SHELL_INPUT]: [{ key: 'tab', shift: false }],
-  [Command.UNFOCUS_SHELL_INPUT]: [{ key: 'tab' }],
+  [Command.UNFOCUS_SHELL_INPUT]: [{ key: 'tab', shift: true }],
   [Command.CLEAR_SCREEN]: [{ key: 'l', ctrl: true }],
   [Command.RESTART_APP]: [{ key: 'r' }],
   [Command.SUSPEND_APP]: [{ key: 'z', ctrl: true }],

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

@@ -1940,6 +1940,28 @@ describe('AppContainer State Management', () => {
         unmount();
       });
     });
+
+    describe('Shell Focus', () => {
+      it('should unfocus shell when Shift+Tab is pressed', async () => {
+        mockedUseGeminiStream.mockReturnValue({
+          ...DEFAULT_GEMINI_STREAM_MOCK,
+          activePtyId: 1,
+        });
+
+        await setupKeypressTest();
+
+        act(() => {
+          capturedUIActions.setEmbeddedShellFocused(true);
+        });
+        rerender();
+        expect(capturedUIState.embeddedShellFocused).toBe(true);
+
+        pressKey({ name: 'tab', shift: true });
+
+        expect(capturedUIState.embeddedShellFocused).toBe(false);
+        unmount();
+      });
+    });
   });
 
   describe('Copy Mode (CTRL+S)', () => {

packages/cli/src/ui/AppContainer.tsx

@@ -1500,10 +1500,11 @@ Logging in with Google... Restarting Gemini CLI to continue.
         setConstrainHeight(false);
         return true;
       } else if (
-        keyMatchers[Command.FOCUS_SHELL_INPUT](key) &&
+        (keyMatchers[Command.FOCUS_SHELL_INPUT](key) ||
+          keyMatchers[Command.UNFOCUS_SHELL_INPUT](key)) &&
         (activePtyId || (isBackgroundShellVisible && backgroundShells.size > 0))
       ) {
-        if (key.name === 'tab' && key.shift) {
+        if (keyMatchers[Command.UNFOCUS_SHELL_INPUT](key)) {
           // Always change focus
           setEmbeddedShellFocused(false);
           return true;

packages/cli/src/ui/components/ShellInputPrompt.test.tsx

@@ -111,4 +111,22 @@ describe('ShellInputPrompt', () => {
 
     expect(mockWriteToPty).not.toHaveBeenCalled();
   });
+
+  it('bubbles up Shift+Tab for unfocusing', () => {
+    render(<ShellInputPrompt activeShellPtyId={1} focus={true} />);
+
+    const handler = mockUseKeypress.mock.calls[0][0];
+
+    const result = handler({
+      name: 'tab',
+      shift: true,
+      alt: false,
+      ctrl: false,
+      cmd: false,
+      sequence: '\x1b[Z',
+    });
+
+    expect(result).toBe(false);
+    expect(mockWriteToPty).not.toHaveBeenCalled();
+  });
 });

packages/cli/src/ui/components/ShellInputPrompt.tsx

@@ -40,6 +40,11 @@ export const ShellInputPrompt: React.FC<ShellInputPromptProps> = ({
         return false;
       }
 
+      // Allow unfocus to bubble up
+      if (keyMatchers[Command.UNFOCUS_SHELL_INPUT](key)) {
+        return false;
+      }
+
       if (key.ctrl && key.shift && key.name === 'up') {
         ShellExecutionService.scrollPty(activeShellPtyId, -1);
         return true;