[DOCS] Forked session storage docs still describe each transcript as a full copy

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/claude-directory

Section/Topic

Application data (projects/<project>/<session>.jsonl) and forked-session transcript storage semantics

Current Documentation

The docs currently say:

| projects/<project>/<session>.jsonl | Full conversation transcript: every message, tool call, and tool result |

The Agent SDK session docs also say:

* Move the session file. Persist ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl from the first run and restore it to the same path on the new host before calling resume. The cwd must match.

What's Wrong or Missing?

Changelog v2.1.118 says: Fixed /fork writing the full parent conversation to disk per fork — now writes a pointer and hydrates on read.

That means forked sessions are no longer stored as a full standalone copy of the parent conversation on disk. The current docs still describe each session JSONL as a full transcript, and the cross-host resume guidance implies that copying a single session file is sufficient.

For forked sessions, that storage description is now outdated. Users who inspect transcript files for privacy/storage reasons, or who move session files between hosts, need the docs to explain that a fork can depend on parent-history data instead of duplicating the entire conversation into the fork's own file.

Suggested Improvement

Update the storage docs to distinguish logical session history from on-disk fork storage.

Suggested changes:

1. In claude-directory, revise the projects/<project>/<session>.jsonl row to clarify that forked sessions may store parent-history references rather than a full duplicated transcript.
2. In agent-sdk/sessions, add a note in Resume across hosts explaining the fork-parent dependency when copying/restoring forked sessions.
3. If hydration requires the parent chain to be present, state that explicitly and give the minimum safe migration rule for forked sessions.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/claude-directory | Application data table currently says each session JSONL is a full transcript |
| https://code.claude.com/docs/en/agent-sdk/sessions | Resume-across-hosts guidance currently tells users to move a single session file |

Total scope: 2 pages affected

Source: Changelog v2.1.118

Exact changelog entry: Fixed /fork writing the full parent conversation to disk per fork — now writes a pointer and hydrates on read