[DOCS] Missing Documentation for receive_response() Buffer Behavior After interrupt()

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://platform.claude.com/docs/en/agent-sdk/python

Section/Topic

"Example - Using interrupts" section (lines 345-376) and the receive_response() method documentation.

Current Documentation

The example shows this pattern:

async with ClaudeSDKClient(options=options) as client:
    # Start a long-running task
    await client.query("Count from 1 to 100 slowly")

    # Let it run for a bit
    await asyncio.sleep(2)

    # Interrupt the task
    await client.interrupt()
    print("Task interrupted!")

    # Send a new command
    await client.query("Just say hello instead")

    async for message in client.receive_response():
        # Process the new response
        pass

The receive_response() documentation states:

Receive messages until and including a ResultMessage

What's Wrong or Missing?

The documentation fails to explain critical buffer behavior after calling interrupt():

1. Does interrupt() clear the message buffer? - If the interrupted "Count from 1 to 100" task produced partial messages, are they flushed or preserved?

1. What does receive_response() return after interrupt? - Will it contain:

• Only messages from the new "Just say hello" query?
• A mix of leftover messages from the interrupted task AND the new query?
• The last ResultMessage from the interrupted task before the new messages?

1. Message ordering guarantees - Is the message stream guaranteed to be clean after interrupt, or might developers need to drain/discard pending messages?

This is critical for developers building interactive applications where task interruption is common.

Suggested Improvement

Add a section explaining buffer behavior after interrupt():

### Buffer behavior after interrupt

When you call `interrupt()`, any pending messages from the interrupted task may still be in the buffer. The `receive_response()` iterator will:

1. First yield any remaining messages from the interrupted task (up to and including its ResultMessage with `stop_reason` indicating interruption)
2. Then yield messages from subsequent queries

If you want to discard messages from the interrupted task:
```python
await client.interrupt()
# Drain remaining messages from interrupted task
async for msg in client.receive_response():
    if isinstance(msg, ResultMessage):
        break  # Interrupted task complete

# Now safe to start fresh
await client.query("New task")

Impact

Medium - Makes feature difficult to understand

Additional Context

• Mirror location: platform.claude.com/docs/en/agent-sdk/python.md (lines 345-376, 254, 270)
• The documentation notes to "avoid using break to exit early" from receive_response() which suggests buffer management is important
• max_buffer_size config option exists (line 477) but its relationship to interrupt behavior is undocumented