[DOCS] `--resume` session picker behavior for `claude -p` and SDK sessions is not documented

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/common-workflows

Section/Topic

The "Resume previous conversations" section, especially "Use the session picker," plus the related --resume CLI reference and headless "Continue conversations" guidance.

Current Documentation

From common-workflows:

Sessions are stored per project directory. The /resume picker shows sessions from the same git repository, including worktrees.

The /resume command (or claude --resume without arguments) opens an interactive session picker with these features:

From cli-reference:

--resume, -r | Resume a specific session by ID or name, or show an interactive picker to choose a session

From headless:

Use --continue to continue the most recent conversation, or --resume with a session ID to continue a specific conversation.

What's Wrong or Missing?

The docs do not explain the boundary between interactive sessions and sessions created by claude -p or Agent SDK integrations.

As of v2.1.90, the interactive --resume picker no longer shows sessions created by claude -p or SDK invocations. However, the documentation still describes the picker as a general session browser and never states that programmatic sessions are excluded.

This creates two gaps:

1. Users are not told that the interactive picker is for interactive CLI sessions, not all persisted sessions.
2. Users running headless or SDK workflows are not told that those sessions remain resumable only through programmatic flows like claude -p --continue or claude -p --resume <session-id>.

Without this distinction, users can reasonably conclude that a claude -p or SDK session was not saved correctly when it does not appear in the picker, even though the session still exists and can be resumed by ID.

Suggested Improvement

Update the session docs to distinguish clearly between interactive and programmatic resume flows.

On https://code.claude.com/docs/en/common-workflows, add a note under "Use the session picker" such as:

The interactive /resume picker only lists interactive Claude Code sessions. Sessions created by claude -p or Agent SDK integrations do not appear in the picker. To continue those sessions, use the headless resume flow with claude -p --continue or claude -p --resume <session-id>.

On https://code.claude.com/docs/en/headless, add a cross-reference in "Continue conversations" explaining that headless and SDK sessions are resumed programmatically and are not surfaced in the interactive picker.

The commands and cli-reference pages should also clarify that opening the picker is an interactive-session workflow, while headless and SDK sessions require ID-based or --continue-based resume.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/common-workflows | Describes the /resume picker as a general session browser but does not mention exclusions for headless or SDK sessions |
| https://code.claude.com/docs/en/cli-reference | --resume flag description does not distinguish interactive picker behavior from programmatic resume flows |
| https://code.claude.com/docs/en/headless | Documents claude -p --continue and claude -p --resume <session-id> but does not explain that these sessions do not appear in the interactive picker |
| https://code.claude.com/docs/en/commands | /resume [session] command description does not clarify that the picker is for interactive sessions only |

Total scope: 4 pages affected

Source: Changelog v2.1.90

"Changed --resume picker to no longer show sessions created by claude -p or SDK invocations"