[DOCS] SDK/print mode docs omit interrupted partial response persistence

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/headless

Section/Topic

Stream responses and Continue conversations for claude -p sessions

Current Documentation

The docs currently say:

"Use --output-format stream-json with --verbose and --include-partial-messages to receive tokens as they're generated. Each line is a JSON object representing an event:"

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

The Agent SDK session docs also say:

"A session is the conversation history the SDK accumulates while your agent works. It contains your prompt, every tool call the agent made, every tool result, and every response."

"Returning to a session means the agent has full context from before: files it already read, analysis it already performed, decisions it already made. You can ask a follow-up question, recover from an interruption, or branch off to try a different approach."

And the Python SDK interrupt example says:

"interrupt() sends a stop signal but does not clear the message buffer. Messages already produced by the interrupted task, including its ResultMessage (with subtype="error_during_execution"), remain in the stream."

None of these pages explain whether assistant text that was already emitted before an SDK or claude -p interruption is persisted into the saved conversation history.

What's Wrong or Missing?

A. The interrupted-stream persistence behavior is undocumented

The docs explain streaming output, session resume, and interrupt handling separately, but they do not state what happens when a response is interrupted mid-stream after partial assistant text has already been emitted.

B. Resume and transcript behavior are ambiguous for SDK/print-mode users

Today the docs promise that sessions contain "every response" and that users can recover from interruptions, but they never clarify whether partially streamed assistant output is durable session history or only ephemeral stream output.

Changelog v2.1.94 explicitly fixed this behavior: SDK/print mode now preserves the partial assistant response in conversation history when interrupted mid-stream. That makes this a supported behavior users can rely on, but the current docs do not describe it.

Suggested Improvement

Add a short note to the headless and Agent SDK session/streaming docs that explains:

1. If an SDK or claude -p streaming response is interrupted after assistant text has started, the already-generated assistant text is preserved in the session's conversation history.
2. Resuming the session (--continue, --resume, or SDK resume) continues from that preserved history rather than treating the partial output as lost.
3. This applies to saved session/transcript history, which is distinct from raw stream_event chunks emitted during live streaming.

Suggested placement:

• In Run Claude Code programmatically, directly after Stream responses or Continue conversations
• In Work with sessions, near the "recover from an interruption" guidance
• In Stream responses in real-time, as a note clarifying what is persisted if streaming is interrupted

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/headless | claude -p streaming output and resume behavior |
| https://code.claude.com/docs/en/how-claude-code-works | Session continuity and restored conversation history |
| https://platform.claude.com/docs/en/agent-sdk/sessions | Session contents and interruption recovery |
| https://platform.claude.com/docs/en/agent-sdk/streaming-output | Partial-message streaming and message flow |
| https://platform.claude.com/docs/en/agent-sdk/python | interrupt() buffer behavior example |

Total scope: 5 pages affected

Source: Changelog v2.1.94

Changelog entry: Fixed SDK/print mode not preserving the partial assistant response in conversation history when interrupted mid-stream