claude-code - 💡(How to fix) Fix [DOCS] PowerShell tool docs still describe opt-in rollout instead of default-enable behavior for Bedrock, Vertex, and Foundry on Windows

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

PowerShell tool setup guidance on Windows, plus related shell-selection references that describe when CLAUDE_CODE_USE_POWERSHELL_TOOL must be set

Current Documentation

The docs currently say:

The PowerShell tool lets Claude run PowerShell commands natively. On Windows, this means commands run in PowerShell instead of routing through Git Bash. On Windows without Git Bash, the tool is enabled automatically. On Windows with Git Bash installed, the tool is rolling out progressively. On Linux, macOS, and WSL, the tool is opt-in.

Set CLAUDE_CODE_USE_POWERSHELL_TOOL=1 in your environment or in settings.json:

The environment variable reference says:

CLAUDE_CODE_USE_POWERSHELL_TOOL | Controls the PowerShell tool. On Windows without Git Bash, the tool is enabled automatically; set to 0 to disable it. On Windows with Git Bash installed, the tool is rolling out progressively: set to 1 to opt in or 0 to opt out.

The Windows setup guide says:

Claude Code can also run PowerShell natively on Windows. When Git Bash is installed, the PowerShell tool is rolling out progressively as an additional option: set CLAUDE_CODE_USE_POWERSHELL_TOOL=1 to opt in or 0 to opt out.

Related settings pages also still require an explicit opt-in:

Setting "powershell" routes interactive ! commands through PowerShell on Windows. Requires CLAUDE_CODE_USE_POWERSHELL_TOOL=1.

What's Wrong or Missing?

Changelog v2.1.143 says:

The PowerShell tool is now enabled by default on Windows for Bedrock, Vertex, and Foundry users. Opt out with CLAUDE_CODE_USE_POWERSHELL_TOOL=0.

The current docs still present the Windows PowerShell tool as either automatically enabled only when Git Bash is absent, or as a gradual opt-in rollout that requires CLAUDE_CODE_USE_POWERSHELL_TOOL=1 when Git Bash is installed.

That is now outdated for a specific user group: Windows users on Bedrock, Vertex, and Foundry.

A. The provider-specific default behavior is undocumented

The docs do not explain that these third-party provider users now get the PowerShell tool by default on Windows.

B. The opt-in guidance is now misleading for affected users

Pages still instruct users to set CLAUDE_CODE_USE_POWERSHELL_TOOL=1, even though v2.1.143 changed the behavior to opt-out-by-default for Bedrock, Vertex, and Foundry on Windows.

C. Downstream shell-selection docs inherit the outdated assumption

Settings, skills, and slash-command docs still frame PowerShell shell selection as requiring a manual enable step, which no longer matches the default behavior for those provider-specific Windows deployments.

Suggested Improvement

Update the PowerShell tool and env-var docs to describe Windows behavior in three cases instead of two:

Before:

On Windows without Git Bash, the tool is enabled automatically. On Windows with Git Bash installed, the tool is rolling out progressively.

After:

On Windows, the default depends on your environment:

• If Git Bash is unavailable, Claude Code uses PowerShell automatically.
• For Bedrock, Vertex, and Foundry users on Windows, the PowerShell tool is enabled by default; set CLAUDE_CODE_USE_POWERSHELL_TOOL=0 to opt out.
• On Linux, macOS, and WSL, set CLAUDE_CODE_USE_POWERSHELL_TOOL=1 to opt in.

Suggested minimum fix:

• Update tools-reference and env-vars so they explicitly mention the Bedrock/Vertex/Foundry default-enable behavior added in v2.1.143
• Update setup so Windows guidance no longer implies that all Git-Bash-installed users must opt in manually
• Update settings, skills, and slash-commands so Requires CLAUDE_CODE_USE_POWERSHELL_TOOL=1 is qualified for the cases where that is still true instead of stated as a universal Windows requirement

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 6 pages affected

Source: Changelog v2.1.143

Exact changelog entry:

The PowerShell tool is now enabled by default on Windows for Bedrock, Vertex, and Foundry users. Opt out with CLAUDE_CODE_USE_POWERSHELL_TOOL=0.