claude-code - 💡(How to fix) Fix [DOCS] Bash tool docs omit deleted or moved launch-directory recovery behavior [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

## Bash tool behavior and the related runtime-error guidance for working-directory failures

Current Documentation

The Bash tool reference currently explains normal working-directory persistence, but not what happens if the original launch directory disappears mid-session:

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. Subagent sessions never carry over working directory changes.
  • 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.

Related pages also define the launch directory, but stop short of documenting deleted or moved directory behavior:

By default, Claude has access to files in the directory where it was launched.

workspace.project_dir | Directory where Claude Code was launched, which may differ from cwd if the working directory changes during a session

What's Wrong or Missing?

Changelog v2.1.121 says:

Fixed Bash tool becoming permanently unusable when the directory Claude was started in is deleted or moved mid-session

That is a user-visible Bash behavior change, but the docs do not explain:

A. What Claude Code does when the launch directory is renamed, moved, or deleted during an active session

The current Bash tool docs only cover cd carry-over and resetting when Claude changes into a path outside the allowed directories. They do not describe the separate edge case where the original project directory itself disappears.

B. What users should expect for recovery or troubleshooting

The runtime error reference does not document the deleted/moved working-directory case, so users who rename a repo, delete a temporary worktree, or otherwise invalidate the original launch path do not have an authoritative explanation of the resulting Bash behavior or recovery path.

Suggested Improvement

Add a short subsection to tools-reference that explains how Bash behaves when the original launch directory or carried-over working directory no longer exists mid-session.

At minimum, document:

1. That Claude tracks both the current shell cwd and the original project/launch directory.
2. What user-visible behavior now occurs when that launch directory is moved or deleted mid-session.
3. Any recovery message or reset behavior users should expect.
4. A cross-reference from errors (or troubleshooting) so users can find this when Bash commands start failing after a repo rename, move, or worktree deletion.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 4 pages affected

Source: Changelog v2.1.121

Exact changelog entry: Fixed Bash tool becoming permanently unusable when the directory Claude was started in is deleted or moved mid-session