[DOCS] Flawed "Resuming to Rewind" Workflow in Python SDK Documentation

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

The "Implement checkpointing" section, specifically Step 3 and the associated Python code block.

Current Documentation

The documentation suggests using query("") to open a connection for a session resumption when the goal is only to perform a file rewind:

"Step 3: Later, rewind by resuming the session with an empty prompt... await client.query("") # Empty prompt to open the connection"

What's Wrong or Missing?

Calling client.query("") sends a literal message containing an empty string to Claude. This triggers an unintended inference turn where the model generates a response (e.g., "How can I help you?").

This approach has several negative impacts:

1. Token Inefficiency: It consumes output tokens for a useless model response.
2. History Pollution: It adds an unnecessary user/assistant exchange to the conversation history, which will increase the cost of all subsequent turns in that session.
3. Model Confusion: Triggering a response with an empty string can occasionally lead the model to hallucinate or break its "persona" if it tries to interpret the empty input.

Suggested Improvement

The documentation should be updated to use await client.connect() without a prompt. The SDK's underlying logic in client.py is specifically designed to initialize the connection with an empty stream if no prompt is provided. This allows the developer to call rewind_files() immediately after the connection is established without sending a message to the model.

Updated Python code suggestion for Step 3:

# Step 3: Later, rewind by resuming the session
if checkpoint_id and session_id:
    async with ClaudeSDKClient(ClaudeAgentOptions(
        enable_file_checkpointing=True,
        resume=session_id
    )) as client:
        await client.connect()  # Establish connection without sending a message
        await client.rewind_files(checkpoint_id)
    print(f"Rewound to checkpoint: {checkpoint_id}")

Impact

High - Prevents users from using a feature

Additional Context

• Internal Logic Reference: In the SDK source (src/claude_agent_sdk/client.py), the connect method includes an internal _empty_stream() generator specifically to handle this use case.
• Related Documentation: This same pattern appears in the "Interactive Example" (try_checkpointing.py) further down the page and should be updated there as well.
• TypeScript Parity: The TypeScript documentation for this feature also uses query({ prompt: "" }). While the TS SDK implementation may handle this differently, it should be verified to ensure it isn't also causing a redundant model turn.