[DOCS] PowerShell docs omit workspace-boundary behavior for built-in `cd` forms

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

PowerShell tool working-directory behavior and how workspace/additional-directory boundaries apply to built-in location-changing forms

Current Documentation

The docs currently say:

When Claude runs cd in the main session, the new working directory carries over to later Bash commands as long as it stays inside the project directory or an additional working directory you added with --add-dir, /add-dir, or additionalDirectories in settings. * If cd lands outside those directories, Claude Code resets to the project directory and appends Shell cwd was reset to <dir> to the tool result.

Later on the same page they say:

The same main-session working-directory reset behavior described under the Bash tool section applies to PowerShell commands, including the CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR environment variable.

The permissions page also says:

PowerShell permission rules use the same shape as Bash rules. Claude Code parses the PowerShell AST and checks each command in a compound command independently.

What's Wrong or Missing?

Changelog v2.1.149 says:

Fixed a PowerShell permission bypass: built-in cd functions (cd.., cd\, cd~, X:) changed the working directory undetected, letting a later command read outside the workspace

The current documentation explains the generic PowerShell/Bash working-directory reset behavior, but it never explains that PowerShell-specific built-in location changes are part of that boundary.

That leaves two user-facing gaps:

A. No PowerShell-specific examples for location-changing built-ins

Windows users are told that PowerShell follows the same reset behavior as Bash, but there is no explicit guidance that built-in forms such as cd.., cd\, cd~, and drive switches like X: are treated as working-directory changes.

B. No explanation of how later relative-path commands are evaluated after those changes

The docs do not explain that these built-ins affect the working directory used by later PowerShell commands, and that the workspace/additional-directory boundary should still be enforced after those changes.

Suggested Improvement

Add a short PowerShell-specific note under the PowerShell tool section, and cross-reference it from the PowerShell subsection of the permissions page.

Minimum fix:

PowerShell location-changing built-ins such as cd.., cd\, cd~, Set-Location, and drive switches like X: are treated as working-directory changes. The resulting working directory follows the same project/additional-directory boundary rules as Bash: if the new location is outside the allowed working directories, Claude Code resets the shell cwd to the project directory before later commands run.

An example showing one in-scope directory change and one out-of-scope reset on Windows would make the boundary much clearer.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/tools-reference | 110-112 | Bash working-directory carry-over and reset behavior |
| https://code.claude.com/docs/en/tools-reference | 240-247 | PowerShell says the same behavior applies, but gives no PowerShell-specific examples |
| https://code.claude.com/docs/en/permissions | 167-188 | PowerShell permission parsing is described generically, without location-changing built-in coverage |
| https://code.claude.com/docs/en/security | 27-30 | High-level boundary description without a Windows/PowerShell clarification |

Total scope: 4 pages affected