[DOCS] Session documentation omits warnings for failed transcript writes and disabled persistence

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The session persistence introduction, Where transcripts are stored, and the troubleshooting guidance for transcript writes.

Current Documentation

The page currently says:

Sessions are saved continuously to local transcript files as you work, so you can return to one after exiting or running /clear.

Its configuration table documents only the controls that suppress writes:

Suppress transcript writes in all modes | CLAUDE_CODE_SKIP_PROMPT_HISTORY | Environment variable

Suppress writes for one non-interactive run | --no-session-persistence | CLI flag with claude -p

The environment-variable reference explains that CLAUDE_CODE_CHILD_SESSION can exclude a nested interactive session from resume history and that CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 overrides that exclusion, but the sessions page does not explain the warning shown when persistence is disabled or when a transcript write fails.

What's Wrong or Missing?

Claude Code v2.1.217 adds warnings when transcript writes fail, such as when the disk is full, and when session saving is disabled because an inherited environment variable turns persistence off. This prevents users from assuming that the continuously-saved-session guarantee still holds after writes have stopped.

The sessions page describes sessions as being saved continuously and lists opt-out controls, but it does not explain the new warning condition, how to distinguish an intentional persistence opt-out from a failed write, or what recovery steps to take. A user who sees the warning has no documented path to check disk capacity and permissions, inspect inherited environment variables, or restore persistence when the disabling condition is accidental.

Suggested Improvement

Add a Transcript persistence warnings subsection to the sessions page that:

• Explains that Claude Code warns when it cannot write a transcript instead of silently continuing without a current transcript.
• Gives the common recovery steps for a write failure, including checking available disk space, the transcript directory, and write permissions.
• Explains that an inherited persistence-related environment variable can intentionally or accidentally disable session saving.
• Links to the relevant environment-variable rows, including CLAUDE_CODE_SKIP_PROMPT_HISTORY, CLAUDE_CODE_CHILD_SESSION, and CLAUDE_CODE_FORCE_SESSION_PERSISTENCE, and explains when the override is appropriate.
• States what happens to --resume, --continue, /resume, and prompt history while persistence is disabled.

Add a short cross-reference from the environment-variable descriptions back to this troubleshooting section.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/sessions | 9, 15, 149-158 | Continuous-save description and transcript write configuration table |
| https://code.claude.com/docs/en/env-vars | 189, 245, 315 | Inherited child-session behavior, forced persistence, and prompt-history suppression |

Total scope: 2 pages should explain the same persistence-warning and recovery behavior.

The relevant release is Claude Code v2.1.217. The release entry is listed in the Claude Code changelog under version 2.1.217.