fix(cli): correct backspace handling in Windows Terminal

[secreal]

Summary

Fix incorrect backspace handling in Windows Terminal.

In some Windows Terminal setups, normal Backspace could be treated like Ctrl+Backspace, causing it to delete the previous word instead of a single character.

Details

This change narrows the Windows fallback that interprets raw \b as Ctrl+Backspace.
The fallback is now disabled in Windows Terminal (WT_SESSION) and remains available only for non-Windows-Terminal Windows consoles where that behavior may still be needed.

Regression coverage was also added for the Windows Terminal case.

Related Issues

Fixes #25856

How to Validate

1. Run the targeted test:

   npm --workspace @google/gemini-cli test -- src/ui/contexts/KeypressContext.test.tsx
   

2. In Windows Terminal, run the CLI and type some text with a typo.
3. Press Backspace and confirm it deletes a single character.
4. Press Ctrl+Backspace and confirm it does not cause normal Backspace to be treated as word-delete.
5. Confirm the Windows Terminal regression test passes.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses an issue where the backspace key was incorrectly triggering word-deletion behavior in Windows Terminal. By adjusting the input interpretation logic to account for the presence of the Kitty keyboard protocol and Windows Terminal sessions, the change ensures that standard backspace inputs are handled correctly as single-character deletions while maintaining necessary legacy support for other Windows console environments.

Highlights

• Backspace Handling Logic: Refined the logic for interpreting the backspace character (\b) to prevent it from being incorrectly identified as Ctrl+Backspace in Windows Terminal environments.
• Conditional Fallback: Disabled the \b to Ctrl+Backspace fallback when the Kitty keyboard protocol is active or when running inside a Windows Terminal session.
• Regression Testing: Added comprehensive test cases to verify correct backspace behavior across different terminal configurations and OS environments.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request refines the backspace key handling in KeypressContext.tsx by incorporating checks for the Kitty keyboard protocol and Windows Terminal sessions. It ensures that the \b character is only treated as Ctrl+Backspace in legacy Windows console environments where Kitty is disabled and no WT_SESSION is active. The changes include updated logic in the key emitter and new test cases in KeypressContext.test.tsx to validate the behavior across different terminal configurations. I have no feedback to provide.

[TiagoSimoes1990]

Tested on v0.41.0-nightly.20260423 (Windows 11, Windows Terminal).

I can confirm the backspace bug persists even when manually setting:

$env:WT_SESSION="1"

$env:KITTY_KI_ENABLED="1"

In this version, the standard Backspace (and Ctrl+H) still incorrectly triggers deleteWordLeft, while Ctrl + Backspace is currently the only way to delete a single character (deleteLeft).

It appears the CLI's keyboard handler is defaulting to a legacy \x08 fallback for Windows that forces the Ctrl modifier to true, regardless of the environment variables or the terminal being used (Windows Terminal vs. legacy console). This report is intended to help validate that the logic in this PR.

[dogukanozen]

@TiagoSimoes1990 #25882 fixes the reported input issues by narrowing the scope of the \b (backspace) handler. The previous logic was over-generalizing all Windows environments, forcing ctrl: true even in legacy consoles (CMD/PowerShell) where \b is a standard backspace.
I've updated the logic to strictly map \b to ctrl: true only when WT_SESSION is detected. This restores correct backspace behavior for legacy users while maintaining Ctrl+Backspace support for Windows Terminal. Tested and verified

[TinyblackQvQ]

Hey @secreal, thanks for your work on #25862.

I've been digging into the root cause and found the key issue is a missing mapping for key code 8 (Backspace) in KITTY_CODE_MAP on advanced terminals like xterm when they fall back to modifyOtherKeys mode. This causes the \x1b[27;5;8~ sequence to be dropped.

To clarify the context:

• On most modern terminals, the Kitty protocol is widely used and handles Ctrl+Backspace correctly, so no extra handling is needed there.
• However, in specific scenarios where Kitty is not available but modifyOtherKeys is active (which in code it already enables), the terminal sends \x1b[27;5;8~. The current code correctly parses the modifier (ctrl=true) but lacks the mapping for key code 8, causing the event to be lost.
• For very old terminals (e.g., legacy CMD), there is no reliable way to distinguish Ctrl+Backspace from plain Backspace. The best approach is to simply ignore Ctrl+Backspace in those environments, rather than attempting a heuristic that could lead to potential problems and even break basic Backspace functionality.

Your PR tries to rely on environment variables and Kitty availability to gate the \b handling. This approach still carries a risk: on Windows terminals where Kitty is unavailable, it would force ctrl=true on \b, which could mis-map a plain Backspace and reintroduce the original bug for some users.

The right solution is to let modifyOtherKeys work as intended. Since the ctrl state is already being set correctly by ctrl = !!(modifier & 4); (KeypressContext#587), we only need to add a mapping so the event can be recognized. I've implemented this in PR#25943 and would appreciate your thoughts.

The key change required is simply:

const KITTY_CODE_MAP: Record<number, string> = {
  // ... existing mappings
  8: 'backspace', // Add this line
};

This properly decodes the \x1b[27;5;8~ sequence, restoring Ctrl+Backspace functionality without any side effects.

[secreal]

Hey @secreal, thanks for your work on #25862.

I've been digging into the root cause and found the key issue is a missing mapping for key code 8 (Backspace) in KITTY_CODE_MAP on advanced terminals like xterm when they fall back to modifyOtherKeys mode. This causes the \x1b[27;5;8~ sequence to be dropped.

To clarify the context:

• On most modern terminals, the Kitty protocol is widely used and handles Ctrl+Backspace correctly, so no extra handling is needed there.
• However, in specific scenarios where Kitty is not available but modifyOtherKeys is active (which in code it already enables), the terminal sends \x1b[27;5;8~. The current code correctly parses the modifier (ctrl=true) but lacks the mapping for key code 8, causing the event to be lost.
• For very old terminals (e.g., legacy CMD), there is no reliable way to distinguish Ctrl+Backspace from plain Backspace. The best approach is to simply ignore Ctrl+Backspace in those environments, rather than attempting a heuristic that could lead to potential problems and even break basic Backspace functionality.

Your PR tries to rely on environment variables and Kitty availability to gate the \b handling. This approach still carries a risk: on Windows terminals where Kitty is unavailable, it would force ctrl=true on \b, which could mis-map a plain Backspace and reintroduce the original bug for some users.

The right solution is to let modifyOtherKeys work as intended. Since the ctrl state is already being set correctly by ctrl = !!(modifier & 4); (KeypressContext#587), we only need to add a mapping so the event can be recognized. I've implemented this in PR#25943 and would appreciate your thoughts.

The key change required is simply:

const KITTY_CODE_MAP: Record<number, string> = {
  // ... existing mappings
  8: 'backspace', // Add this line
};

This properly decodes the \x1b[27;5;8~ sequence, restoring Ctrl+Backspace functionality without any side effects.

Thanks for digging into this and for the detailed explanation.

After upgrading from Node 22 to Node 24.15.0, I can no longer reproduce the keyboard issue on my side. So in my case, this appears to have been tied to the older runtime/environment rather than something I still need to fix with this PR.

Your explanation and PR #25943 make sense to me, especially the part about handling modifyOtherKeys / Kitty code 8 directly instead of relying on \b heuristics.

I’m going to close this PR for now. Thanks again for the investigation and for working on a cleaner fix