claude-code - 💡(How to fix) Fix [DOCS] Windows background-session worktree cleanup docs omit NTFS junction safety

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/agent-view

Section/Topic

Deleting background sessions and the related worktree-cleanup guidance

Current Documentation

The docs currently say:

Deleting removes the session from agent view. If Claude created a worktree for the session, deleting removes that worktree too, including any uncommitted changes in it, so push or commit work you want to keep first. A worktree you created yourself and started the session inside is left in place.

The worktree cleanup page also says:

Uncommitted changes, untracked files, or new commits exist: Claude prompts you to keep or remove the worktree. Keeping preserves the directory and branch so you can return later. Removing deletes the worktree directory and its branch, discarding any uncommitted changes, untracked files, and commits

What's Wrong or Missing?

Changelog v2.1.146 includes a Windows-specific safety fix:

Fixed on Windows, removing a background-job worktree no longer follows NTFS junctions into the main repo.

The current docs still describe background-session and worktree removal as straightforward deletion, but they do not explain the Windows-specific safeguard around NTFS junctions.

That leaves two gaps:

A. Windows junction traversal behavior is undocumented

The docs do not say that background-session worktree removal on Windows now avoids following NTFS junctions that point back into the main repository.

B. The cleanup risk model is incomplete for repos that use linked directories

Users who rely on Windows junctions or linked directories to share content between the main checkout and Claude-created worktrees have no documentation telling them that cleanup is now bounded to the worktree instead of traversing into the main repo.

Suggested Improvement

Add a short Windows-specific note anywhere the docs describe deleting a background session or removing a Claude-created worktree.

Suggested wording:

On Windows, Claude does not follow NTFS junctions when removing a background-session worktree. If a worktree contains a junction that points back into your main repository or another directory, cleanup removes the worktree entry itself without traversing into the junction target.

Add a cross-reference from the general worktree cleanup page so the same safety behavior is documented outside agent view.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

Total scope: 3 pages affected

Version: v2.1.146