[DOCS] PowerShell docs omit key permission-check behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The PowerShell tool section, with a cross-reference to the permissions documentation where appropriate.

Current Documentation

The PowerShell tool page currently documents setup and preview limitations, for example:

On Windows, Claude Code can run PowerShell commands natively instead of routing through Git Bash. This is an opt-in preview.

and:

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

By contrast, the permissions docs contain Bash-specific safety guidance such as:

Claude Code is aware of shell operators (like &&) so a prefix match rule like Bash(safe-cmd *) won't give it permission to run the command safe-cmd && other-cmd.

There is no equivalent documentation explaining PowerShell-specific permission-check behavior.

What's Wrong or Missing?

The PowerShell docs explain how to enable the tool, but they do not document important permission-check behavior that users need in order to understand the tool's security model.

The v2.1.90 release notes call out a set of PowerShell permission-check hardenings:

"Hardened PowerShell tool permission checks: fixed trailing & background job bypass, -ErrorAction Break debugger hang, archive-extraction TOCTOU, and parse-fail fallback deny-rule degradation"

However, the docs still do not explain:

1. That PowerShell has its own permission-check edge cases distinct from Bash.
2. How background jobs and other PowerShell-specific syntax interact with permission checks.
3. That parse failures should fail closed rather than silently degrade safety.
4. Where users should look to understand PowerShell tool safety boundaries compared with the existing Bash guidance.

Suggested Improvement

Add a short PowerShell-specific permission behavior note to the PowerShell tool section, or add a cross-reference to a new subsection on the permissions page.

That documentation should explain, at a high level:

1. The PowerShell tool has its own permission parser and safety checks.
2. PowerShell-specific syntax such as background jobs can affect how commands are evaluated.
3. Permission parsing failures should fail closed rather than weakening enforcement.
4. Security-sensitive PowerShell behavior is intentionally hardened separately from Bash.

This does not need to expose internal implementation details, but it should give users a clear safety model comparable to the Bash documentation.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/tools-reference | Documents how to enable and use the PowerShell tool, but not its permission-check behavior |
| https://code.claude.com/docs/en/permissions | Contains Bash-specific safety guidance, but no equivalent cross-reference or explanation for PowerShell-specific permission behavior |

Total scope: 2 pages affected

Source: Changelog v2.1.90

"Hardened PowerShell tool permission checks: fixed trailing & background job bypass, -ErrorAction Break debugger hang, archive-extraction TOCTOU, and parse-fail fallback deny-rule degradation"