[DOCS] Agent SDK transcript viewer docs missing final token usage semantics

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/agent-sdk/sessions

Section/Topic

getSessionMessages() / get_session_messages() transcript viewer guidance and transcript token-usage semantics

Current Documentation

The sessions guide currently says:

Both SDKs expose functions for enumerating sessions on disk and reading their messages: listSessions() and getSessionMessages() in TypeScript, list_sessions() and get_session_messages() in Python. Use them to build custom session pickers, cleanup logic, or transcript viewers.

The TypeScript reference currently says:

message | unknown | Raw message payload from the transcript

The Python reference currently says:

message | Any | Raw message content

The cost-tracking guide currently says:

Each assistant message contains a nested BetaMessage (accessed via message.message) with an id and usage object with token counts.

When the query() call completes, the SDK emits a result message with total_cost_usd and cumulative usage.

The docs describe transcript access and live per-step usage separately, but they do not explain what token-usage values transcript-derived per-block entries contain.

What's Wrong or Missing?

Changelog v2.1.97 introduced a transcript-facing behavior change:

Improved transcript accuracy: per-block entries now carry the final token usage instead of the streaming placeholder

That matters for developers who read ~/.claude/projects/<project>/<session>.jsonl directly or use getSessionMessages() / get_session_messages() to build transcript viewers or usage analytics.

What's missing is a clear explanation of transcript token-usage semantics:

A. No transcript-specific usage guidance

The docs say session messages come from the transcript, but they do not explain whether transcript-derived assistant/per-block entries include token usage, or how those values should be interpreted.

B. No note about the v2.1.97 accuracy change

There is no documentation stating that per-block transcript entries now carry the final token usage instead of a streaming placeholder.

C. No guidance on per-block usage vs final totals

The cost-tracking guide explains per-step usage and the authoritative final ResultMessage.usage, but it does not connect that guidance to transcript readers who need to know when transcript usage is suitable for display versus when they should rely on the final result totals.

Suggested Improvement

Add a short “Transcript usage semantics” note to the sessions guide, with cross-links from the TypeScript and Python API references.

Suggested content:

1. State that session transcripts are stored in ~/.claude/projects/<project>/<session>.jsonl and can be read directly or via getSessionMessages() / get_session_messages().
2. Document that transcript-derived assistant/per-block entries can include token-usage data.
3. Note that as of v2.1.97, those per-block entries carry the final token usage rather than the earlier streaming placeholder.
4. Clarify that transcript viewers can display those finalized per-block values, but billing/whole-query totals should still use the final result message (usage, total_cost_usd, and per-model breakdowns).
5. Cross-reference the existing cost-tracking guidance about deduplicating assistant messages that share the same message ID during parallel tool turns.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/agent-sdk/sessions | Tells users to use session-message APIs to build transcript viewers |
| https://code.claude.com/docs/en/agent-sdk/typescript | getSessionMessages() return type and SDKAssistantMessage.message.usage context |
| https://code.claude.com/docs/en/agent-sdk/python | get_session_messages() return type and AssistantMessage.usage context |
| https://code.claude.com/docs/en/agent-sdk/cost-tracking | Explains per-step usage and authoritative final totals, but only for streamed query output |
| https://code.claude.com/docs/en/claude-directory | Documents where transcript JSONL files are stored |

Total scope: 5 pages affected

Source: Changelog v2.1.97

Exact changelog entry: “Improved transcript accuracy: per-block entries now carry the final token usage instead of the streaming placeholder”