[DOCS] Agent SDK session resume docs incomplete — hook messages can silently corrupt history reconstruction

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/headless

Section/Topic

Sessions — "Resume by ID" section and the hooks integration pages

Current Documentation

The sessions page documents how to resume a session by ID:

Pass a session ID to resume to return to that specific session. The agent picks up with full context from wherever the session left off.

The TypeScript SDK reference documents SDKHookProgressMessage (emitted while a hook is running) as one of the message types yielded during a session. The Python SDK similarly includes hook events in the message stream.

There is no documentation of how hook-emitted messages (progress events, attachment messages) interact with the session transcript's parentUuid chain, nor any mention of the risk that these messages can corrupt the chain on resume.

What's Wrong or Missing?

Claude Code v2.1.83 fixed a bug where hook progress and hook attachment messages were forking the parentUuid chain in the session transcript. When a user resumed that session via the SDK (resume option in Python/TypeScript), the history reconstruction walked the corrupted chain and silently returned an incomplete or empty conversation history — the agent appeared to start fresh instead of picking up from where it left off.

This was a silent failure: no error was raised, no warning was emitted, and the session ID was valid. The resume call succeeded but produced wrong results.

The docs currently describe no known failure modes for resume beyond a mismatched cwd. There is no guidance that:

1. Hook-emitted messages (progress events, attachment messages) are persisted to the transcript and participate in the parentUuid chain.
2. A bug in hook message ordering could silently break history reconstruction on resume.
3. Users should verify that a resumed session actually contains prior context (e.g., by checking message count or inspecting the first few messages) rather than assuming resume is always correct.

The existing tip on the sessions page covers only the cwd mismatch case:

If a resume call returns a fresh session instead of the expected history, the most common cause is a mismatched cwd.

This is now incomplete: a corrupted parentUuid chain (previously caused by hook messages, potentially by other future causes) is a second class of failure that produces the same symptom — resume appears to succeed but delivers no prior history.

Source: Changelog v2.1.83 — "Fixed SDK session history loss on resume caused by hook progress/attachment messages forking the parentUuid chain"

Suggested Improvement

Expand the tip in the "Resume by ID" section of https://platform.claude.com/docs/en/agent-sdk/sessions to cover both known failure modes:

If a resume call returns a fresh session instead of the expected history: - Mismatched cwd: Sessions are stored under ~/.claude/projects/<encoded-cwd>/*.jsonl. If your resume call runs from a different directory, the SDK looks in the wrong place. - Corrupted transcript chain: In rare cases (e.g., a Claude Code bug prior to v2.1.83 involving hook messages), the session transcript's internal message chain can be malformed, causing history reconstruction to return an empty result even though the session file exists and the ID is valid. To confirm a resume is working correctly, check that the resumed session contains the expected prior messages. In Python, use get_session_messages(session_id) before calling query(); in TypeScript, use getSessionMessages(sessionId).

Additionally, consider adding a brief note to the hooks documentation (both code.claude.com/docs/en/hooks and platform.claude.com/docs/en/agent-sdk/typescript under SDKHookProgressMessage) explaining that hook-generated messages are written to the session transcript and affect session continuity, so SDK consumers using resume should be aware that hook behavior can influence history reconstruction.

Impact

Medium - Makes feature difficult to understand

Additional Context