fix(core): prefer pwsh.exe over Windows PowerShell 5.1 (#25859)

[kaluchi]

Summary

Fixes #25859. Related: closes-as-effectively-same #18374; addresses the feature-request spirit of #15493, #2353, #6413.

On Windows, run_shell_command with embedded double quotes (e.g. node -e 'console.log(\"test\")') fails because Windows PowerShell 5.1 silently strips \" during native-command argument passing. PowerShell 7 (pwsh.exe) uses standards-compliant argument passing (\$PSNativeCommandArgumentPassing = 'Windows' by default since 7.3) and does not exhibit this behavior.

This PR makes getShellConfiguration prefer pwsh.exe from PATH over powershell.exe on Windows. Users with PowerShell 7 installed get the fix; users without keep the existing behavior — no regression either way.

Context

Windows PowerShell 5.1 is in legacy maintenance mode. Microsoft itself displays this banner when 5.1 starts:

```
Windows PowerShell
Copyright (C) Microsoft Corporation. All rights reserved.

Install the latest PowerShell for new features and improvements!
https://aka.ms/PSWindows
```

PS 5.1 is .NET Framework-bound, Windows-only, and lags PS 7 on shell behavior. `$PSNativeCommandArgumentPassing` (fixes native-cmd arg passing) and bash-style `&&`/`||` chain operators were added in PS 7 and cannot be backported to 5.1.

Respecting the user's environment. gemini-cli is a developer tool, and developers who work on Windows overwhelmingly install PowerShell 7 — it's the modern, cross-platform, actively-maintained runtime Microsoft recommends. Currently gemini-cli ignores the user's choice and pins Windows invocations to `powershell.exe` (5.1 on any modern Windows) regardless of whether pwsh 7 is installed. This PR follows both Microsoft's own guidance and the user's clear intent: prefer PS 7 when it's on their system, fall back to 5.1 only when it isn't.

Side benefits

PowerShell 7 also addresses other Windows-specific pain reported against gemini-cli:

• `&&` / `||` operators (added in PS 7.0): unblocks CLI throws ParserError on Windows PowerShell 5.1 due to '&&' operator #20773, the gemini cli agent keeps trying to use "&&" in powershell commands with git. Powershell commands do not accept "&&", so it has to try twice. #18022, Gemini always uses && for command chaining in powershell, despiteinstructions not to #21997. LLM-generated commands with bash-style `&&` will parse correctly on pwsh 7.
• UTF-8 by default (PS 7): improves the encoding issues reported in Windows PowerShell Output Encoding Bug #20968, Bug Report: run_shell_command output is garbled for Japanese characters on Windows #12468, Character Encoding Corruption (Garbled Korean Text) on Windows PowerShell #20186 (avoids 5.1's legacy codepage mangling).

These aren't explicitly targeted by the fix but improve as a natural consequence for users who have pwsh 7 installed.

Verification

Reproduce directly in each shell — same commands, different results.

Issue 1: embedded double quotes stripped (#25859)

Windows PowerShell 5.1:
```
PS C:\Users\EugenPC> node -e 'console.log("test")'
[eval]:1
console.log(test)
^
ReferenceError: test is not defined
at [eval]:1:13
...
Node.js v22.18.0
```

PowerShell 7.6.1:
```
PS C:\Users\EugenPC> node -e 'console.log("test")'
test
```

Issue 2: `&&` / `||` operators rejected (#20773, #21997, #18022)

Windows PowerShell 5.1:
```
PS C:\Users\EugenPC> echo a && echo b
At line:1 char:8

• echo a && echo b

•    ~~
  

The token '&&' is not a valid statement separator in this version.
```

PowerShell 7.6.1:
```
PS C:\Users\EugenPC> echo a && echo b
a
b
```

With this PR, gemini-cli routes through `pwsh.exe` on Windows when it's installed, inheriting the correct behavior for both issues.

Behavior matrix

Environment	Before	After
Windows + `pwsh.exe` in PATH	powershell	pwsh (fix)
Windows, no `pwsh.exe`	powershell	powershell
Windows, explicit `ComSpec`	honored	honored
Windows sandbox (`windows-native`)	cmd.exe /c	cmd.exe /c
macOS / Linux	bash	bash

Only the first row changes behavior.

Tests

• Unit tests in `shell-utils.test.ts` covering new pwsh preference, path-extension handling, unset `PATH`.
• New Windows-only integration file (`shellExecutionService.windows.integration.test.ts`, skipped on non-Windows): 5 cases driving real spawns through `ShellExecutionService`, asserting byte-exact preservation of embedded `"`.
• Full core suite: 0 regressions vs. `main`.

Root cause

PR #11157 (2025-10-16) changed the default Windows shell from `cmd.exe /d /s /c` to `powershell.exe -NoProfile -Command`. Windows PowerShell 5.1 lacks `$PSNativeCommandArgumentPassing` (introduced in PS 7.2 as experimental, default since 7.3) and has a long-standing runtime limitation: `"` inside arguments is dropped when invoking native executables. Fixable only by running through PS 7 — which is what this PR does.

[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 improves shell command execution on Windows by prioritizing PowerShell 7 (pwsh.exe) over the legacy Windows PowerShell 5.1. This change resolves long-standing issues with argument quoting and improves compatibility with modern shell features like '&&' and '||' operators, while maintaining backward compatibility for users without PowerShell 7 installed.

Highlights

• PowerShell 7 Preference: Updated the shell configuration to prefer 'pwsh.exe' (PowerShell 7) over 'powershell.exe' (Windows PowerShell 5.1) on Windows when available in the PATH.
• Resolved Argument Quoting Issue: Addressed the issue where Windows PowerShell 5.1 incorrectly strips embedded double quotes from arguments passed to native executables.
• Synchronous Executable Resolution: Refactored 'resolveExecutable' to be synchronous, allowing it to be used during shell configuration initialization.
• New Integration Tests: Added Windows-specific integration tests to verify that shell commands with inline double quotes are executed correctly.

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 updates the shell configuration to prefer pwsh.exe on Windows to resolve quoting issues and adds integration tests for verification. It also refactors the resolveExecutable utility to be synchronous and updates the test suite to use vi.stubEnv. Feedback indicates that the switch to synchronous I/O blocks the event loop and violates project conventions, identifies a regression in Windows executable resolution for extensionless files, and suggests using asynchronous operations with real-path resolution for better security and performance.

[kaluchi]

/gemini review

[kaluchi]

For reference — GitHub's own https://github.com/github/copilot-cli ships with pwsh as the default shell on Windows. Same repro from this PR (node -e 'console.log("test")') runs cleanly there, for the same reason this PR fixes it in gemini-cli.

[kaluchi]

Note this PR is non-breaking by design: Copilot CLI refuses to run without pwsh 7 (#847) and won't support 5.1 (#411, not planned). Here, 5.1 users keep working exactly as before — only users who already installed pwsh get the fix.

[izambe]

good

[kaluchi]

Thanks for the review.

The auto-close bot fired again on the PR after you reopened it — same misconfigured policy.

The lint failure from the main-merge is fixed and pushed to the branch (PR head won't show it until reopen). The help wanted label would stop the bot loop.

I resolved the main conflict in favor of the sync resolveExecutable:

a) the alternative has a large transitive blast radius — cascading async through the consumers of getShellConfiguration (4 sync sites in shell-utils itself, plus a React render in SessionSummaryDisplay.tsx);

b) the previous async version was already synchronous in effect — serial for ... of over PATH with sequential await fs.promises.access per entry, no Promise.all;

c) the surrounding execution flow has large synchronous sections — command parsing (parsePowerShellCommandDetails uses spawnSync('powershell.exe', ...)), argument-safety checks, and resolveExecutable itself is called from a synchronous prepare stage in shellExecutionService.

[kaluchi]

@scidomino — the auto-close bot closed the PR again after your reopen (request-review button isn't available while it's closed). Could you reopen and add the 'help wanted' label?

Lint fix and rationale for the sync conflict are in the comment above.

[github-actions]

✅ 69 tests passed successfully on gemini-3-flash-preview.

🧠 Model Steering Guidance

This PR modifies files that affect the model's behavior (prompts, tools, or instructions).

• ⚠️ Consider adding Evals: No behavioral evaluations (evals/*.eval.ts) were added or updated in this PR. Consider adding a test case to verify the new behavior and prevent regressions.
• 🚀 Maintainer Reminder: Please ensure that these changes do not regress results on benchmark evals before merging.

---

This is an automated guidance message triggered by steering logic signatures.