[DOCS] PowerShell tool docs still say Windows users may need to ask Claude to use PowerShell

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/tools-reference

Section/Topic

"PowerShell tool" section, especially the Windows shell-selection guidance

Current Documentation

The docs currently say:

On Windows, Claude Code auto-detects pwsh.exe for PowerShell 7+ with a fallback to powershell.exe for PowerShell 5.1. The Bash tool remains registered alongside the PowerShell tool, so you may need to ask Claude to use PowerShell.

The same section also frames PowerShell use as controlled by extra settings:

Three additional settings control where PowerShell is used: * "defaultShell": "powershell" in settings.json: routes interactive ! commands through PowerShell. Requires the PowerShell tool to be enabled.

What's Wrong or Missing?

The v2.1.126 changelog says: "Windows: when the PowerShell tool is enabled, Claude now treats PowerShell as the primary shell instead of defaulting to Bash."

That makes the current guidance outdated for Windows users who have enabled the PowerShell tool. The docs still tell users that Bash remains registered alongside PowerShell and that they may need to ask Claude to use PowerShell, but the new behavior is that PowerShell becomes the primary shell when the PowerShell tool is enabled.

This can lead users to add unnecessary prompting or settings workarounds after enabling the PowerShell tool, because the docs do not explain that v2.1.126 changed the default selection behavior.

Suggested Improvement

Update the Windows paragraph in the PowerShell tool section to describe the v2.1.126 behavior. For example:

Before:

On Windows, Claude Code auto-detects pwsh.exe for PowerShell 7+ with a fallback to powershell.exe for PowerShell 5.1. The Bash tool remains registered alongside the PowerShell tool, so you may need to ask Claude to use PowerShell.

After:

On Windows, Claude Code auto-detects pwsh.exe for PowerShell 7+ with a fallback to powershell.exe for PowerShell 5.1. When the PowerShell tool is enabled, Claude treats PowerShell as the primary shell instead of defaulting to Bash.

Also clarify how this interacts with "defaultShell": "powershell" so readers can distinguish the new primary shell behavior from explicit configuration for interactive ! commands.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/tools-reference | 98, 114, 116-124 | PowerShell tool section says commands run in PowerShell, but later says Bash remains registered and users may need to ask Claude to use PowerShell |
| https://code.claude.com/docs/en/settings | 183 | defaultShell description may need clarification now that enabled PowerShell is the primary shell on Windows |

Total scope: 2 pages affected

The behavior changed in v2.1.126.