Documentation Type
Missing documentation (feature not documented)
Documentation Location
https://code.claude.com/docs/en/headless
Section/Topic
Continue conversations in print mode, especially how deferred tool calls are resumed with claude -p --continue and claude -p --resume
Current Documentation
The headless docs currently say:
Use --continue to continue the most recent conversation, or --resume with a session ID to continue a specific conversation. This example runs a review, then sends follow-up prompts:
The CLI reference currently says:
| --continue, -c | Load the most recent conversation in the current directory |
| --resume, -r | Resume a specific session by ID or name, or show an interactive picker to choose a session |
The workflow docs describe only generic resume behavior:
claude --continue continues the most recent conversation in the current directoryclaude --resume opens a conversation picker or resumes by name
- Message Deserialization: When resuming, the entire message history is restored to maintain context
- Tool State: Tool usage and results from the previous conversation are preserved
And the session model page says:
When you resume a session with claude --continue or claude --resume, you pick up where you left off using the same session ID. New messages append to the existing conversation. Your full conversation history is restored, but session-scoped permissions are not.
What's Wrong or Missing?
Changelog v2.1.89 says:
Fixed -p --resume hangs when the deferred tool input exceeds 64KB or no deferred marker exists, and -p --continue not resuming deferred tools
The 64KB and missing-marker edge cases are implementation details, but this entry still confirms a user-visible print-mode contract that the docs do not currently explain: a headless session can contain a deferred tool call, and continuing the same session should resume that pending tool flow rather than just append a new prompt.
The current docs cover generic conversation resume, but they do not explain:
A. Deferred tool state in print mode
That claude -p sessions can pause with a deferred tool call that remains pending in session state.
B. --continue and --resume behavior for deferred tools
That both claude -p --continue and claude -p --resume <session-id> can resume that deferred tool state.
C. The practical workflow for scripted integrations
A scripted integration reading the current docs would know how to resume a conversation, but not that resuming is also the mechanism for re-entering a deferred tool call after external state changes.
Suggested Improvement
Add a short note to the print-mode/session-resume docs that explains:
- In
-p mode, a run can pause with a deferred tool call that remains attached to the session.
- Resuming the same session with
claude -p --continue or claude -p --resume <session-id> resumes that pending tool workflow.
- This depends on session persistence remaining enabled and on resuming the same session rather than starting a new one.
- Include a minimal example that captures a
session_id, pauses, then resumes the deferred tool later.
The primary update belongs in https://code.claude.com/docs/en/headless, with short cross-references in the CLI/session docs.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
Total scope: 4 pages affected
Source: Changelog v2.1.89
Changelog entry:
Fixed -p --resume hangs when the deferred tool input exceeds 64KB or no deferred marker exists, and -p --continue not resuming deferred tools
Documentation Type
Missing documentation (feature not documented)
Documentation Location
https://code.claude.com/docs/en/headless
Section/Topic
Continue conversationsin print mode, especially how deferred tool calls are resumed withclaude -p --continueandclaude -p --resumeCurrent Documentation
The headless docs currently say:
The CLI reference currently says:
The workflow docs describe only generic resume behavior:
And the session model page says:
What's Wrong or Missing?
Changelog v2.1.89 says:
The 64KB and missing-marker edge cases are implementation details, but this entry still confirms a user-visible print-mode contract that the docs do not currently explain: a headless session can contain a deferred tool call, and continuing the same session should resume that pending tool flow rather than just append a new prompt.
The current docs cover generic conversation resume, but they do not explain:
A. Deferred tool state in print mode
That
claude -psessions can pause with a deferred tool call that remains pending in session state.B.
--continueand--resumebehavior for deferred toolsThat both
claude -p --continueandclaude -p --resume <session-id>can resume that deferred tool state.C. The practical workflow for scripted integrations
A scripted integration reading the current docs would know how to resume a conversation, but not that resuming is also the mechanism for re-entering a deferred tool call after external state changes.
Suggested Improvement
Add a short note to the print-mode/session-resume docs that explains:
-pmode, a run can pause with a deferred tool call that remains attached to the session.claude -p --continueorclaude -p --resume <session-id>resumes that pending tool workflow.session_id, pauses, then resumes the deferred tool later.The primary update belongs in
https://code.claude.com/docs/en/headless, with short cross-references in the CLI/session docs.Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
Continue conversationsdocuments generic-presume usage but not deferred tool continuation--continueand--resumeflag entries omit deferred-tool resumption behaviorTotal scope: 4 pages affected
Source: Changelog v2.1.89
Changelog entry: