[DOCS] Architecture Discrepancy: Python SDK Exposes ClaudeSDKClient Class While TypeScript SDK Only Documents query() Function

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

Python SDK: "Choosing Between query() and ClaudeSDKClient" section (lines 221-244)
TypeScript SDK: Main API documentation (lines 19-45, 103)

Current Documentation

Python SDK (line 223):

Maintains a conversation session across multiple exchanges. This is the Python equivalent of how the TypeScript SDK's query() function works internally - it creates a client object that can continue conversations.

Python SDK provides two distinct APIs:

1. query() function - for one-off tasks
2. ClaudeSDKClient class - for stateful conversations with interrupt(), hooks, etc.

TypeScript SDK exposes only:

1. query() function - uses continue: true option for multi-turn conversations
2. No separate Client class documented

What's Wrong or Missing?

The documentation creates a confusing asymmetry:

1. Python explicitly separates concerns: stateless query() vs. stateful ClaudeSDKClient
2. TypeScript uses a single query() function with options for all use cases

The Python docs claim ClaudeSDKClient is "equivalent to how TypeScript SDK's query() function works internally" - but this comparison is backwards. It implies TypeScript has an internal Client that isn't exposed, while Python exposes it explicitly.

Problems this causes:

• Developers porting code between languages don't know the equivalent patterns
• The comparison table in Python docs references capabilities (interrupts, hooks) that TypeScript achieves differently
• No guidance on achieving Python's ClaudeSDKClient behavior in TypeScript

Suggested Improvement

Option A: Add TypeScript Client equivalent documentation

If TypeScript has an internal client that can be exposed, document it:

// For stateful conversations in TypeScript
const client = createClaudeClient(options);
await client.query("First message");
await client.query("Follow-up"); // Same session
await client.interrupt();

Option B: Clarify the pattern mapping

Add a cross-reference section explaining how to achieve equivalent functionality:

| Python Pattern | TypeScript Equivalent |
|----------------|----------------------|
| query() one-shot | query() with default options |
| ClaudeSDKClient context manager | query() with continue: true and stored conversation ID |
| client.interrupt() | queryInstance.interrupt() (Query object method) |

Option C: Update the misleading comparison

Remove or reword the "Python equivalent of TypeScript" statement since the architectures are fundamentally different.

Impact

Medium - Makes feature difficult to understand

Additional Context

• Mirror locations:
• platform.claude.com/docs/en/agent-sdk/python.md (lines 13-40, 221-244)
• platform.claude.com/docs/en/agent-sdk/typescript.md (lines 19-45, 103, 139-149)
• The TypeScript V2 preview (line 10) mentions send()/receive() patterns which may provide different architecture
• The Query interface returned by TypeScript's query() has methods like interrupt() and rewindFiles() but isn't presented as a constructor-based client