[DOCS] `--resume` docs conflict on cross-worktree session resumption

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/how-claude-code-works

Section/Topic

Work across branches section

Current Documentation

The docs currently say:

"Each Claude Code conversation is a session tied to your current directory. When you resume, you only see sessions from that directory."

But the Common workflows page says:

"claude --continue continues the most recent conversation in the current directory" "claude --resume opens a conversation picker or resumes by name" "Sessions are stored per project directory. The /resume picker shows interactive sessions from the same git repository, including worktrees."

What's Wrong or Missing?

Changelog v2.1.94 says:

Improved --resume to resume sessions from other worktrees of the same repo directly instead of printing a cd command

The documentation is now inconsistent about what --resume can see and do:

• how-claude-code-works still says resumed sessions are only visible from the current directory.
• common-workflows says the picker includes sessions from the same git repository, including worktrees.
• Neither page clearly states that resuming a session from another worktree of the same repo switches directly into that worktree.

Users who work with git worktrees can reasonably conclude that --resume is directory-scoped only, or that they still need to manually cd into the matching worktree before resuming.

Suggested Improvement

Update the resume/session docs to use one consistent rule:

• claude --continue resumes the most recent session in the current directory.
• claude --resume can resume interactive sessions from the same git repository, including other worktrees.
• If the selected session belongs to another worktree in the same repo, Claude resumes it directly in that worktree instead of printing a cd command.

A minimal fix would be to replace the current-directory claim in how-claude-code-works with wording that matches common-workflows, then add one explicit sentence in the --resume docs about direct cross-worktree resumption.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/how-claude-code-works | 103 | Says resumed sessions are only visible from the current directory |
| https://code.claude.com/docs/en/common-workflows | 553-559 | Distinguishes --continue from --resume and says the picker includes worktree sessions from the same repo |
| https://code.claude.com/docs/en/cli-reference | 85 | --resume flag description does not mention same-repo worktree behavior |

Total scope: 3 pages affected

Source: Changelog v2.1.94

Exact changelog entry:
Improved --resume to resume sessions from other worktrees of the same repo directly instead of printing a cd command