[DOCS] PowerShell tool docs omit PS 5.1 quoted-whitespace prompt behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

PowerShell tool preview limitations / approval behavior on Windows PowerShell 5.1, especially for external-command arguments that contain both a double quote and whitespace

Current Documentation

The PowerShell tool page currently says:

On Windows, Claude Code can run PowerShell commands natively instead of routing through Git Bash. This is an opt-in preview. Claude Code auto-detects pwsh.exe (PowerShell 7+) with a fallback to powershell.exe (PowerShell 5.1).

And its preview-limitations section currently says:

The PowerShell tool has the following known limitations during the preview: Auto mode does not work with the PowerShell tool yet PowerShell profiles are not loaded Sandboxing is not supported Only supported on native Windows, not WSL * Git Bash is still required to start Claude Code

No current PowerShell tool documentation explains any PowerShell 5.1-specific permission-prompt behavior for quoted arguments with spaces.

What's Wrong or Missing?

Changelog v2.1.89 says:

PowerShell tool on Windows: external-command arguments containing both a double-quote and whitespace now prompt instead of auto-allowing (PS 5.1 argument-splitting hardening)

That is a user-visible approval-flow change, but the PowerShell tool docs do not explain it.

The missing details are:

A. The PowerShell 5.1 fallback has a shell-specific hardening case

The page tells users that Claude Code can fall back to powershell.exe (PowerShell 5.1), but it does not document that this fallback has stricter prompting behavior for certain external-command arguments.

B. Quoted arguments with embedded whitespace can prompt instead of auto-allowing

Users enabling the PowerShell tool have no documentation telling them that an external-command argument containing both " and whitespace may intentionally trigger a prompt on Windows PowerShell 5.1.

C. The reason for the prompt is undocumented

The changelog explains that this is PS 5.1 argument-splitting hardening. Without that note in the main docs, users may reasonably assume the extra prompt is a bug or a broken permission rule rather than expected security behavior.

Suggested Improvement

Add a short note to the PowerShell tool section describing this PowerShell 5.1-specific behavior.

For example, near the preview limitations or permission-related guidance, document that:

• when Claude Code uses the powershell.exe fallback on Windows,
• external-command arguments containing both a double quote and whitespace are handled conservatively,
• and those invocations may prompt instead of being auto-approved because of PowerShell 5.1 argument-splitting hardening.

This gives Windows users an explanation for the prompt and makes it clear that the behavior is intentional.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/tools-reference#powershell-tool | Primary PowerShell preview documentation; currently covers enablement and general limitations, but not this PowerShell 5.1-specific prompt behavior |

Total scope: 1 page affected

Source: Changelog v2.1.89

Exact changelog entry:

PowerShell tool on Windows: external-command arguments containing both a double-quote and whitespace now prompt instead of auto-allowing (PS 5.1 argument-splitting hardening)