[DOCS] Permissions docs only describe `cd`, not `pushd`/`popd` directory-stack behavior

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/permissions

Section/Topic

Read-only commands and compound-command handling for directory-changing shell builtins

Current Documentation

The permissions docs currently say:

Claude Code recognizes a built-in set of Bash commands as read-only and runs them without a permission prompt in every mode. These include ls, cat, echo, pwd, head, tail, grep, find, wc, which, diff, stat, du, cd, and read-only forms of git. A cd into a path inside your working directory or an additional directory is also read-only. A compound command like cd packages/api && ls runs without a prompt when each part qualifies on its own. Combining cd with git in one compound command always prompts, regardless of the target directory.

Related Bash behavior docs 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.

What's Wrong or Missing?

Changelog v2.1.149 says:

Fixed a permission-analysis gap where the parser trusted stale variable-tracking values for PWD/OLDPWD/DIRSTACK across cd/pushd/popd

The current docs only describe cd as the directory-changing shell builtin that affects Claude Code's tracked working directory and permission behavior.

That leaves the documentation narrower than the product behavior implied by the v2.1.149 fix:

A. pushd/popd behavior is undocumented

The docs never say whether pushd and popd are treated like cd for working-directory carry-over, read-only classification, or compound-command permission checks.

B. Permission guidance is incomplete for directory-stack changes

Users reading the current pages cannot tell whether later commands are evaluated against the updated directory after pushd/popd, or whether the same in-scope/out-of-scope rules documented for cd also apply to directory-stack navigation.

Suggested Improvement

Update the permissions and Bash behavior docs to explicitly cover directory-stack builtins alongside cd.

Minimum fix:

• State whether pushd and popd update Claude Code's tracked working directory the same way cd does.
• State whether they are treated as read-only only when the resulting directory stays inside the working directory or an additionalDirectories path.
• Add one compound-command example such as pushd packages/api && ls and one persistence example showing how a later Bash command resolves after pushd or popd.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/permissions | 143-147 | Read-only command list and cd-specific compound-command guidance |
| https://code.claude.com/docs/en/tools-reference | 108-113 | Bash working-directory carry-over behavior only documented for cd |

Total scope: 2 pages affected

This issue is based on the v2.1.149 release note about permission analysis across cd/pushd/popd and is scoped to documenting directory-stack behavior in Claude Code's shell and permissions docs.