[DOCS] `claude agents` background-session docs do not cover data loss when read by an older Claude Code version (v2.1.195 fix)

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/agent-view

Section/Topic

The "Supervisor process" / "Background sessions across updates" section, specifically the discussion of how session state persists across supervisor restarts and binary upgrades. The docs do not address the v2.1.195 fix for background jobs disappearing from claude agents or losing data when written by a newer Claude Code version and then read by an older one.

Current Documentation

The agent-view guide currently explains version-skew only in the supervisor-restart direction:

The supervisor watches the installed Claude Code binary on disk and restarts into the new version after the regular auto-updater replaces it. This is a local file watch, not a network check. Background sessions are detached processes, so they keep running through the restart and the new supervisor reconnects to them. An idle pinned session is also restarted in place onto the new version so it picks up the update without you reattaching.

The command also warns when the running supervisor is on a different version than the claude you invoked, which happens after an update the supervisor hasn't restarted into yet. The warning shows both versions and tells you to run claude daemon stop --any to pick up the new version.

To inspect this state without reading the files directly, run claude daemon status. It reports whether the supervisor is reachable, its process ID and version, the socket directory, and how many background sessions are live. /doctor includes a summary of the same check.

The guide never describes what happens when claude agents reads background-job state written by a newer Claude Code version than the one currently running the supervisor. There is no mention of forward-compatibility or rollback risk.

What's Wrong or Missing?

Claude Code v2.1.195 fixed an issue where background jobs would disappear from claude agents or lose data when the on-disk session state had been written by a newer Claude Code version and then read by an older one. Before the fix, an older claude agents (or an older supervisor) reading newer-format state could drop the row entirely or strip the conversation data.

After the fix, the loader handles newer-format state gracefully, but the agent-view guide does not say so. Users with mixed-version environments (auto-update in flight, slow supervisor restart, or an explicit downgrade for debugging) have no doc-level signal that an older claude agents is now safe to run against newer-written state.

Suggested Improvement

Add a paragraph to the supervisor section covering forward compatibility:

Background-session state written by a newer Claude Code version is readable by an older claude agents and an older supervisor without dropping rows or losing data. Claude Code v2.1.195 fixes the loader so that an older CLI reading newer-format state preserves the session and shows the row in claude agents. Earlier versions could hide the row or strip the conversation. The reverse direction (an older supervisor reading older state from a newer claude agents) is unchanged: state written by older versions continues to load on newer ones.

Cross-link from claude daemon status so users running /doctor after a downgrade can find the note.

Impact

Medium - Makes feature difficult to understand

Additional Context

The agents.md overview page also references claude agents for background sessions and could link to this paragraph in agent-view. The claude daemon status and claude daemon stop --any table rows in agent-view.md are the natural anchors for the cross-reference.

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/agent-view | "Supervisor process" / "Background sessions across updates" section |
| https://code.claude.com/docs/en/agents | Background-sessions overview referencing claude agents |

Total scope: 2 pages affected