[DOCS] [Background agents] v2.1.203 startup failures now surface the actual error in `claude agents` rows instead of only `exit_with_message`

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

• The "Troubleshooting" subsection named "A session fails before starting with a possibly low memory note"
• The "Version history" table at the bottom of the same page

Both areas describe a startup-exit failure case but only cover the v2.1.199 low-memory special-case behavior. They do not say what users on v2.1.203 will see for the broader case of a background agent failing to start, and they still frame the v2.1.199 wording in terms of an "earlier versions" behavior that v2.1.203 has now changed in a different direction.

Current Documentation

The relevant troubleshooting entry on https://code.claude.com/docs/en/agent-view currently reads:

### A session fails before starting with a possibly low memory note As of v2.1.199, when a background session's process exits before it finishes starting and the host is low on memory, the row's status names the exit and adds possibly low memory — free some up and retry. Earlier versions showed only the bare exit reason for this failure. The note is a hypothesis, not a confirmed cause. Claude Code adds it only when the process exited silently, without writing an error and without being stopped by a signal, and the host reported low memory at that moment. When the process did write an error before exiting, the row shows that error instead. Free up memory on the machine, then attach, peek, or reply to the row and the supervisor starts a fresh process for the session. When memory stays low, the supervisor also [stops idle sessions](#the-supervisor-process) to free resources on its own.

The same page's "Version history" table begins with the v2.1.202 row and does not yet have a v2.1.203 row:

| Version | Change | | -------- | ------------------------------------------------------------------------------------- | | v2.1.202 | {/ min-version: 2.1.202 /}A name set with /rename or Ctrl+R on a background session persists when the supervisor stops and restarts its process, instead of reverting to the name the session was dispatched with. | | v2.1.200 | {/ min-version: 2.1.200 /}An older Claude Code version that rewrites the session list in roster.json preserves fields written by a newer version, matching the existing state.json guarantee, so sessions started by the newer version keep accepting input after the supervisor restarts. ... | | v2.1.199 | {/ min-version: 2.1.199 /}A background session whose process exits before it finishes starting on a low-memory host shows possibly low memory — free some up and retry in its row status instead of only the bare exit reason. Backgrounding a session with ← or /background carries its /color over to the new row. |

What's Wrong or Missing?

A. The v2.1.203 startup-error reveal is not described anywhere on the page

The v2.1.203 changelog entry reads:

Fixed background agent startup failures showing only "exit_with_message" instead of the actual error

Before v2.1.203, when a background agent's process exited during startup with a real error (for example a missing dependency, a permission denial, or a malformed startup config), the row in claude agents showed the placeholder string exit_with_message instead of the underlying error. After v2.1.203 the row surfaces the actual error text, which is the same code path that already shows process-written errors in the low-memory case.

The troubleshooting entry only describes the low-memory special case and frames the error-revealing behavior as the post-v2.1.199 norm ("When the process did write an error before exiting, the row shows that error instead"). It never acknowledges that v2.1.203 made that promise true for the exit_with_message case — every other startup-exit error that the page omits is the very error users on pre-v2.1.203 versions have been seeing as exit_with_message.

The result is that the page implies the startup error is already surfaced, while readers running v2.1.202 or older with a misconfigured background agent see only exit_with_message and have no doc-level explanation that this is a known fixed-in-v2.1.203 gap.

B. The "Version history" table is missing the v2.1.203 row

Every other flagged background-agent fix in the table has a one-line row; v2.1.203 does not. Users browsing the version table cannot learn that exit_with_message is resolved in v2.1.203, and reviewers cannot audit which version to upgrade to.

Suggested Improvement

A. Add a sentence under the existing troubleshooting entry

Under "A session fails before starting with a possibly low memory note", extend the prose that already promises "the row shows that error instead":

Before: > As of v2.1.199, when a background session's process exits before it finishes starting and the host is low on memory, the row's status names the exit and adds possibly low memory — free some up and retry. Earlier versions showed only the bare exit reason for this failure. > > The note is a hypothesis, not a confirmed cause. Claude Code adds it only when the process exited silently, without writing an error and without being stopped by a signal, and the host reported low memory at that moment. When the process did write an error before exiting, the row shows that error instead. > > Free up memory on the machine, then attach, peek, or reply to the row and the supervisor starts a fresh process for the session. When memory stays low, the supervisor also stops idle sessions to free resources on its own. After: > As of v2.1.199, when a background session's process exits before it finishes starting and the host is low on memory, the row's status names the exit and adds possibly low memory — free some up and retry. Earlier versions showed only the bare exit reason for this failure. > > The note is a hypothesis, not a confirmed cause. Claude Code adds it only when the process exited silently, without writing an error and without being stopped by a signal, and the host reported low memory at that moment. When the process did write an error before exiting, the row shows that error instead. > > As of v2.1.203, startup failures that earlier surfaced as the placeholder string exit_with_message now show the underlying error text in the row, so a missing dependency, permission denial, or configuration problem surfaces with the same detail as any other startup exit. The placeholder string only remains for cases where no specific error is available. > > Free up memory on the machine, then attach, peek, or reply to the row and the supervisor starts a fresh process for the session. When memory stays low, the supervisor also stops idle sessions to free resources on its own.

B. Add a v2.1.203 row to the "Version history" table

| Version | Change | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | v2.1.203 | {/ min-version: 2.1.203 /}When a background agent's process exits before it finishes starting, the row in claude agents shows the underlying error text instead of the exit_with_message placeholder, so a missing dependency, permission denial, or configuration problem is visible without attaching to the row. | | v2.1.202 | {/ min-version: 2.1.202 /}A name set with /rename or Ctrl+R on a background session persists when the supervisor stops and restarts its process, instead of reverting to the name the session was dispatched with. |

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/agent-view | 582-588 | Troubleshooting entry describing the v2.1.199 low-memory case and implying startup errors are always surfaced |
| https://code.claude.com/docs/en/agent-view | 650-670 | Version history table starts with v2.1.202 and has no v2.1.203 row |

Total scope: 1 page affected (two regions of the same page).

Mentioning v2.1.203 in user-facing copy follows the convention used elsewhere on the page: every other row in the Version history table and every other troubleshooting-by-version note uses the {/* min-version: X.Y.Z */} and "As of vX.Y.Z" patterns.