[DOCS] Headless docs omit deferred tool resumption with `-p --continue` and `--resume`

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 directory claude --resume opens a conversation picker or resumes by name

2. Message Deserialization: When resuming, the entire message history is restored to maintain context 3. 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:

1. In -p mode, a run can pause with a deferred tool call that remains attached to the session.
2. Resuming the same session with claude -p --continue or claude -p --resume <session-id> resumes that pending tool workflow.
3. This depends on session persistence remaining enabled and on resuming the same session rather than starting a new one.
4. 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:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/headless | 177-193 | Continue conversations documents generic -p resume usage but not deferred tool continuation |
| https://code.claude.com/docs/en/cli-reference | 50, 84 | --continue and --resume flag entries omit deferred-tool resumption behavior |
| https://code.claude.com/docs/en/common-workflows | 553-555, 633, 639-642 | Resume guide and script tip explain generic resume plus restored tool state, but not pending deferred tools |
| https://code.claude.com/docs/en/how-claude-code-works | 111-121 | Session model explains restored history and same-session resume, but not paused deferred tool calls |

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