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

[coygeek]

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"

[coygeek]

Issue #42311 Verification

Title: [DOCS] --resume session picker behavior for claude -p and SDK sessions is not documented
Issue Date: 2026-04-02
Verification Date: 2026-04-27
Status: RESOLVED

---

Issue Summary

This issue reports that the docs did not explain that the interactive --resume picker excludes sessions created by claude -p or SDK invocations, and that users had no guidance on how to resume those sessions programmatically.

---

Verification Results

Claim 1: Docs don't state that the picker excludes claude -p / SDK sessions

Status: RESOLVED

At https://code.claude.com/docs/en/common-workflows, line 569 now states the picker shows "interactive sessions from the current worktree" (no longer described as a general session browser). Line 577 explicitly notes: "Sessions created by claude -p or SDK invocations do not appear in the picker, but you can still resume one by passing its session ID directly to claude --resume <session-id>."

Verdict: The picker scope limitation and programmatic resumption path are both now documented.

Claim 2: No guidance for resuming headless/SDK sessions

Status: RESOLVED

The same section now provides the explicit instruction to use claude --resume <session-id> for non-interactive sessions, closing the gap where users previously had no way to discover this workflow.

Verdict: Users of headless and SDK workflows now have clear guidance on resuming their sessions.

---

Current State

Claim	Status
Picker exclusion of claude -p/SDK sessions not documented	RESOLVED
No guidance on resuming non-interactive sessions	RESOLVED

---

Suggested Fix

N/A — issue has been resolved.

---

References

• https://code.claude.com/docs/en/common-workflows — "Resume previous conversations" section (lines 569–577)

---

Conclusion & Recommendation

Primary Concern: The --resume session picker's exclusion of claude -p and SDK sessions was undocumented, leaving users unable to find or resume those sessions.

Resolution Status: RESOLVED

Recommendation: CLOSE

Both gaps — the picker scope limitation and the programmatic resumption path — are now documented in the common workflows session management section.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.