[DOCS] Bash tool: 'working directory persists' claim omits workspace-boundary auto-reset

Summary

The Bash tool description (both in the tool-use system prompt and in tools-reference docs) states:

"The working directory persists between commands, but shell state does not."

…or, in the public docs:

"Working directory persists across commands. Set CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 to reset to the project directory after each command."

Both framings strongly imply: default = persist; reset = opt-in. In practice there's a third, undocumented case that the docs should mention.

What actually happens

The harness silently auto-resets cwd when a command cds outside the session's approved working directories. The only visible signal is a post-hoc notice appended to the Bash tool result:

Shell cwd was reset to /Users/.../approved-working-dir

Empirically verified just now in a session whose primary working directory was .../Ebrain:

| Invocation | Command | Tool output | Behavior |
|---|---|---|---|
| 1 | pwd | /Users/fbarthelemy/.ebrain-vault | baseline |
| 2 | cd /tmp && pwd | /tmp + Shell cwd was reset to /Users/…/Ebrain | auto-reset (outside workspace) |
| 3 | pwd | /Users/fbarthelemy/.ebrain-vault | back at baseline |
| 4 | cd Inbox && pwd | .../Ebrain/Inbox | no reset |
| 5 | pwd | .../Ebrain/Inbox | persisted (inside workspace) |

So the behavior is actually: cwd persists only for paths inside the session's approved working directories; any attempt to leave them is silently reverted. That's a reasonable sandbox guard — but it isn't documented anywhere I can find, and the current wording actively misleads agents (including me) into believing cwd either always persists or never does.

Why this matters

This isn't just pedantic — it shapes how Claude plans multi-step Bash work:

1. Agents write incorrect workarounds. Believing cwd doesn't persist at all, agents default to cd /path && cmd compound invocations everywhere, which is exactly the pattern that trips the \"bare git repository\" permission prompt for git commands. A correctly-documented model would let agents cd once in an isolated invocation and then use bare commands.
2. The auto-reset notice is easy to miss. It's appended as a system line on the same tool result; agents reading just the command's stdout will conclude \"the cd worked\" and proceed to operate from the wrong directory on the next call.
3. The public docs are actively wrong about the opt-in direction. tools-reference currently says CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 is the opt-in to reset — implying the default is free persistence. That framing doesn't match reality: the default is scoped persistence with a workspace boundary, and the env var presumably tightens it further.

Related issues

• #42844 (\"Can no longer tell Claude to change its working directory mid-session\") — filed as a behavior regression. This docs issue is complementary: regardless of whether the auto-reset is intended behavior or a regression, the docs should describe it.
• #42837 (superseded by #42844)
• #31471 (statusLine cwd reset — separate root cause)

This issue is not asking for the auto-reset behavior to be removed. It's asking for the Bash tool description and public tools-reference docs to accurately describe it, so agents can plan around it correctly.

Requested change

Update the Bash tool description (system prompt) and the public tools-reference docs to say something like:

The working directory persists between commands for paths inside the session's approved working directories. Attempts to cd outside those directories are silently reverted, and a Shell cwd was reset to <dir> notice is appended to the tool result. Shell state (env vars, aliases, functions) does not persist between commands regardless.

Bonus: mention the git -C <path> / make -C <path> pattern as the recommended way to operate on paths inside the workspace -- nested repos or sub-projects.

Environment

• Claude Code: latest as of 2026-04-08
• Model: claude-opus-4-6[1m]
• OS: macOS (Darwin 25.4.0)
• Shell: zsh