[DOCS] Bash backgrounding docs do not explain that `cd` does not change the session directory

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

The Bash tool behavior section's working-directory persistence rules and its run_in_background guidance. The related Background Bash commands section in the interactive-mode reference should also be aligned.

Current Documentation

The Bash reference currently says:

The Bash tool runs each command in a separate process with the following persistence behavior: 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. For long-running processes such as dev servers or watch builds, Claude can set run_in_background: true to start the command as a background task and continue working while it runs.

The interactive-mode reference similarly says:

When Claude Code runs a command in the background, it runs the command asynchronously and immediately returns a background task ID.

What's Wrong or Missing?

The documentation explains that cd normally carries over between Bash calls and that commands can be moved to the background, but it does not explain the interaction between those two behaviors. In Claude Code v2.1.210, when a Bash command containing cd is moved to the background, the command runs asynchronously but the session's working directory remains unchanged; the tool result explicitly states that the working directory is unchanged.

Without this distinction, a user or an SDK/tooling author can reasonably expect a backgrounded cd command to affect the next foreground Bash call, just as a completed foreground cd does. That can cause subsequent commands to run from the wrong directory. The change is recorded in the v2.1.210 release notes, but the operational rule is absent from the Bash and background-command references.

Suggested Improvement

Add an explicit note to the Bash tool behavior section, near the working-directory persistence rule, for example:

A command moved to the background does not change the session's working directory. If a backgrounded command includes cd, the command runs from the requested directory, but subsequent Bash commands keep the session's previous working directory. The tool result states that the working directory is unchanged.

Add the same constraint, or a cross-reference to it, in the Background Bash commands section. Clarify that a foreground cd can carry over while a command moved to the background cannot, and mention that this behavior requires Claude Code v2.1.210 or later.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Section | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/tools-reference | Bash tool behavior | Working-directory persistence and run_in_background behavior |
| https://code.claude.com/docs/en/interactive-mode#background-bash-commands | Background Bash commands | Asynchronous command execution and task handoff |

Total scope: 2 pages affected

Claude Code v2.1.210 records this behavior change as: “Fixed Claude assuming a cd took effect after its command was moved to the background; the tool result now states the working directory is unchanged.”