[DOCS] TypeScript cost tracking example uses nonexistent `onMessage` callback in Options

Documentation Type

unclear/confusing documentation

Documentation Location

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

Section/Topic

"Usage Reporting Structure" section - TypeScript code examples

Current Documentation

const result = await query({
prompt: "Analyze this codebase and run tests",
options: {
onMessage: (message) => {
if (message.type === 'assistant' && message.usage) {
console.log(`Message ID: ${message.id}`);
console.log(`Usage:`, message.usage);
}
}
}
});

What's Wrong or Missing?

The TypeScript example demonstrates three patterns that contradict the SDK architecture:

1. onMessage callback does not exist: The Options interface (documented in platform.claude.com/docs/en/agent-sdk/typescript) does not contain an onMessage property
2. await query() is incorrect: The query() function returns an AsyncGenerator<Message>, not a Promise that resolves to a result
3. Callback pattern vs iterator pattern: The SDK uses for await...of iteration, not callbacks

Affected Pages:

| Page | Line(s) | Issue |
|------|---------|-------|
| platform.claude.com/docs/en/agent-sdk/cost-tracking | 38, 168 | onMessage callback + await query() |
| platform.claude.com/docs/en/agent-sdk/cost-tracking | 113, 139 | await query() → result.usage access |

Total scope: 1 page, 4 occurrences (2 with onMessage, 2 with direct result access)

Suggested Improvement

Replace the callback pattern with the standard async iterator pattern:

import { query } from "@anthropic-ai/claude-agent-sdk";

const q = query({
prompt: "Analyze this codebase and run tests"
});

for await (const message of q) {
if (message.type === 'assistant' && message.usage) {
console.log(`Message ID: ${message.id}`);
console.log(`Usage:`, message.usage);
}
}

Impact

Medium - Makes feature difficult to understand

Additional Context

• The TypeScript SDK Reference (platform.claude.com/docs/en/agent-sdk/typescript) defines query() as returning AsyncGenerator<Message>
• All other SDK examples use for await...of iteration pattern
• This appears to be an AI hallucination of a common callback pattern from other SDKs