claude-code - 💡(How to fix) Fix [DOCS] PowerShell tool docs omit ExecutionPolicy Bypass default and opt-out variable

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

PowerShell tool documentation, especially the default process launch behavior and the environment-variable controls for that behavior

Current Documentation

The PowerShell tool section currently says:

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.

On Windows, Claude Code auto-detects pwsh.exe for PowerShell 7+ with a fallback to powershell.exe for PowerShell 5.1. When the tool is enabled, Claude treats PowerShell as the primary shell. The Bash tool remains available for POSIX scripts when Git Bash is installed.

The environment variable reference currently documents:

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. On Linux, macOS, and WSL, set to 1 to enable it, which requires pwsh on your PATH. When enabled on Windows, Claude can run PowerShell commands natively instead of routing through Git Bash.

No page currently mentions -ExecutionPolicy Bypass or CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY.

What's Wrong or Missing?

Changelog v2.1.143 documents a user-visible PowerShell behavior change:

PowerShell tool now passes -ExecutionPolicy Bypass. Opt out with CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1

The current docs do not explain that behavior anywhere.

A. The default PowerShell invocation behavior is undocumented

The PowerShell tool page explains how the tool is enabled and which executable Claude uses, but it does not state that PowerShell tool invocations now pass -ExecutionPolicy Bypass by default.

B. The opt-out control is undocumented

The environment variable reference does not list CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY, so users cannot discover how to restore normal execution-policy handling.

C. The docs leave a policy-sensitive behavior change discoverable only in the changelog

Execution policy affects how PowerShell commands run in managed Windows environments. Without a doc update, users and admins have to infer this behavior from the release notes instead of finding it in the PowerShell tool docs or env var reference.

Suggested Improvement

Update the PowerShell tool section to document the default launch behavior explicitly.

Suggested content:

By default, PowerShell tool commands pass -ExecutionPolicy Bypass.

To make Claude Code respect the system or user PowerShell execution policy instead, set CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1.

Also add an environment-variable reference entry for CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY that explains:

• it applies to PowerShell tool commands,
• 1 opts out of the default bypass behavior, and
• it is relevant for Windows environments where execution policy is managed or expected to remain enforced.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 pages affected

Source: Changelog v2.1.143

Exact changelog entry:

PowerShell tool now passes -ExecutionPolicy Bypass. Opt out with CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1