[DOCS] `[Bash tool] Windows crash when launch directory is deleted, locked, or unmounted mid-command is not documented`

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

The ## Bash tool behavior section (currently around line 112 of tools-reference.md), specifically the part that introduces the Bash tool's persistence behavior. The Bash tool docs do not mention what happens on Windows when the directory Claude Code was launched from disappears during a running command.

Current Documentation

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

## Bash tool behavior 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. To disable this carry-over so every Bash command starts in the project directory, set CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1. Environment variables don't persist. An export in one command won't be available in the next. * Aliases and shell functions defined in your shell startup file are available. At session start, Claude Code sources ~/.zshrc, ~/.bashrc, or ~/.profile depending on your shell, captures the resulting aliases, functions, and shell options, and applies them to every Bash command.

The section then documents the two-line timeout/output ceiling and the run_in_background shortcut. It never describes what the Bash tool does when the launch directory disappears, is locked, or is unmounted while a command is in flight, and it does not distinguish Windows from other platforms. The troubleshooting.md page similarly has no entry for launch-directory loss on Windows — its only Windows touches are Git for Windows install paths, the WSL cross-filesystem performance note, and the USE_BUILTIN_RIPGREP=0 / winget guidance.

What's Wrong or Missing?

A. The Bash tool docs make no provision for the launch directory disappearing mid-command

The v2.1.205 changelog states:

Fixed a Windows crash when the directory Claude was launched from is deleted, locked, or unmounted while a command is running

Before v2.1.205, a Windows session whose launch directory was removed (deleted, locked by another process, or had its containing volume unmounted) while a Bash or PowerShell command was still in flight could crash. After v2.1.205 that crash is fixed, but the Bash tool behavior section still describes the working-directory lifetime only in terms of the cd carry-over scope: nothing in the section tells a Windows reader that the directory Claude was launched from has any special lifetime guarantee during in-flight commands, or that v2.1.205 added one.

B. The failure modes are Windows-specific and not enumerated anywhere

The three trigger conditions in the v2.1.205 entry — directory deleted, directory locked, drive unmounted — are each a distinct Windows filesystem event. The closest existing note in troubleshooting.md is the Windows-Tab performance block, which is unrelated. There is no troubleshooting entry that describes a mid-command directory-going-away scenario, and no Bash tool reference text that maps the trigger conditions to the expected post-fix behavior.

C. The Windows cross-platform launch directory fix from v2.1.121 is documented nowhere either

The v2.1.121 changelog says:

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

The Bash tool docs continue to make no statement about launch-directory lifetime on any platform. The two fixes together (v2.1.121 for delete/move, v2.1.205 for delete/locked/unmount on Windows) describe a recovery behavior the docs never acknowledge, so a Windows reader whose launch directory becomes inaccessible still has no official source that explains what to expect from Claude Code after the directory returns.

Suggested Improvement

Add a Windows note to the ## Bash tool behavior section in tools-reference.md after the current persistence-behavior bullets, for example:

{/ min-version: 2.1.205 /}On Windows, the Bash and PowerShell tools handle the directory Claude Code was launched from being deleted, locked, or unmounted while a command is running without crashing the session. If the launch directory becomes inaccessible mid-command, the current command returns an error that names the missing path, and the next command can still run from a valid working directory set with cd. Earlier v2.1.205 versions could crash the whole Claude Code process in this scenario. The same protection applies on macOS and Linux when the launch directory is renamed or moved away while a command is running (see [the launch-directory lifetime fix in v2.1.121](#bash-tool-behavior)).

Also consider adding a short Windows-specific troubleshooting entry to troubleshooting.md near the existing Windows-Tab section:

### Windows Bash command fails when the launch directory was deleted, locked, or unmounted On Windows, if Claude Code was launched from a directory that has since been deleted, locked by another process, or had its drive unmounted, the current Bash or PowerShell command returns an error that names the missing path. After v2.1.205 this no longer crashes the session — launch Claude Code again from a valid directory, or cd to one, and subsequent commands run normally. See Bash tool behavior.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/tools-reference | ~112-129 | ## Bash tool behavior describes cd carry-over, env persistence, and shell snapshots but says nothing about launch-directory lifetime or Windows-specific failure modes |
| https://code.claude.com/docs/en/troubleshooting | 95-118 | The Troubleshooting page's only Windows entries are about ripgrep install, WSL cross-filesystem search performance, and switching to a Linux filesystem — no launch-directory-during-command entry |

Total scope: 2 pages affected (1 page with a missing Windows note, 1 page missing a Windows troubleshooting entry).

Version: v2.1.205 for the Windows-specific delete/locked/unmount crash; v2.1.121 for the earlier cross-platform rename/move case that tools-reference.md has likewise never documented.