Documentation Type
Incorrect/outdated documentation
Documentation Location
https://code.claude.com/docs/en/agent-view#troubleshooting
Section/Topic
The Troubleshooting section near the bottom of the agent-view.md page, alongside the existing platform-specific macOS entries "Background sessions can't read Desktop, Documents, or Downloads on macOS" and "Background sessions can't reach local-network hosts on macOS". The Version history table at the very end of the same page also needs a row entry.
Current Documentation
The agent-view Troubleshooting section currently includes two macOS-specific entries that document failure modes introduced and fixed in recent releases:
Background sessions can't read Desktop, Documents, or Downloads on macOS
On macOS, the background session host runs as its own process and requests access to protected folders separately from your terminal. If a background session reports Operation not permitted when reading ~/Desktop, ~/Documents, ~/Downloads, or another protected location, grant access in System Settings under Privacy & Security > Files and Folders, or enable Full Disk Access for the entry.
With the native installer, the entry appears as Claude Code and the grant persists across updates. With other install methods such as Homebrew or npm, the entry shows the binary path and may need to be granted again after updating.
Background sessions can't reach local-network hosts on macOS
On macOS 15 and later, the system blocks a process from reaching devices on your local network until you grant Local Network permission. Before v2.1.198 the background session host never requested that permission, so commands targeting a LAN address failed with connect: no route to host even though the same command worked in a foreground terminal. As of v2.1.198, the first command in a background session that connects to a local-network address triggers the macOS Local Network permission prompt for Claude Code. Grant it once and those commands reach LAN hosts the same way they do in a foreground terminal.
The v2.1.199 row in the Version history table at the bottom of agent-view.md lists two changes:
| v2.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. |
There is no troubleshooting entry for the "Could not switch to audit session" error, and no mention of the v2.1.199 audit-session cold-start fix in the version history.
What's Wrong or Missing?
The 2.1.199 release notes include the fix:
Fixed background agents failing to cold-start over SSH on macOS with "Could not switch to audit session" (regression in 2.1.196)
This regression affected every user who dispatched a background agent over an SSH session into a macOS host on 2.1.196, 2.1.197, or 2.1.198, since the supervisor failed to attach to the required audit session when starting a fresh worker process. The page already documents two other macOS-specific background-agent failure modes in the same Troubleshooting section, but the audit-session regression is undocumented there, so:
A. No troubleshooting entry for the error message
A user who dispatched claude --bg or opened claude agents over SSH into a macOS host between 2.1.196 and 2.1.198 would see the session fail to cold-start with a Could not switch to audit session error. Without a troubleshooting entry, that error string does not appear anywhere in the agent view docs, and the user has no path from the symptom to the fix. This matches the pattern of the existing two macOS entries, which both name a specific error string and walk the user through the cause and remediation.
B. Version history is missing the fix
The v2.1.199 row in the Version history table omits the audit-session cold-start fix entirely. Other background-agent fixes shipped in the same release (SendMessage name disambiguation, /color carry-over, low-memory hint) are listed, but this one is not. Users who search the page for "audit session" or "cold-start" find nothing.
C. SSH as a background-agent launch context is undocumented
The Troubleshooting section does not call out SSH-on-macOS as a background-agent launch context with its own failure modes. The page currently mentions SSH only in the context of Voice dictation and Desktop SSH sessions. Users who run claude --bg over SSH into a remote macOS host have no signal that this is a supported deployment shape, nor a place to look when it breaks.
Suggested Improvement
Add a new macOS troubleshooting entry to agent-view.md following the existing two-entry pattern, and add the fix to the v2.1.199 row of the Version history table.
Option A — Comprehensive fix (recommended)
Insert a new subsection after "Background sessions can't reach local-network hosts on macOS":
Background sessions fail to cold-start with Could not switch to audit session over SSH on macOS
When you dispatch a background agent over an SSH session into a macOS host, the supervisor starts a fresh worker process for the session. On Claude Code v2.1.196 through v2.1.198, that worker failed to attach to the required macOS audit session, and the dispatched session did not start. The dispatch returned Could not switch to audit session and the row in claude agents stayed in a failed state.
Update to Claude Code v2.1.199 or later to pick up the fix. The audit-session transition happens during worker cold-start, so a session that was already running before the update is not affected; only newly dispatched background sessions over SSH on macOS were broken in the affected versions.
Then extend the v2.1.199 row in the Version history table to mention the fix:
| v2.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. Background agents dispatched over SSH on macOS no longer fail to cold-start with Could not switch to audit session, regressing 2.1.196–2.1.198. SendMessage to a name that now resolves to a different agent than it did earlier in the conversation is refused instead of delivered. |
Option B — Minimum fix
Only extend the v2.1.199 Version history row (the bullet above) and skip the standalone Troubleshooting entry. This still surfaces the fix on the page, but loses the error-string-to-fix linkage that the existing two macOS entries provide.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
Total scope: 1 page affected (1 Troubleshooting section, 1 Version history row).
Version numbers: Regression introduced in v2.1.196 and fixed in v2.1.199. Affects every background-agent dispatch over SSH on macOS on v2.1.196, v2.1.197, and v2.1.198.
Related changelog entries in the same release that are documented but this one is not:
The v2.1.199 release also documents the SendMessage name-disambiguation change in sub-agents.md ("As of v2.1.199, SendMessage checks that a name still refers to the same agent it reached earlier in the conversation...") and the claude --teleport SSH-host-alias change in claude-code-on-the-web.md. Both have user-visible behavior described in the docs. The audit-session cold-start fix is the only user-visible 2.1.199 change on the agent-view side that has no documentation entry.
Cross-reference: This is a regression fix; the docs team can rely on the changelog.md entry for v2.1.199 as the source of the regression scope. The page already follows a similar "document the user-visible regression scope inline" pattern for v2.1.198 (Background sessions can't reach local-network hosts on macOS), v2.1.196 (A single ← press backgrounds a foreground session; earlier versions required two presses), and v2.1.174 (background sessions no longer inherit gateway endpoint variables from the supervisor's launch shell).
Documentation Type
Incorrect/outdated documentation
Documentation Location
https://code.claude.com/docs/en/agent-view#troubleshooting
Section/Topic
The Troubleshooting section near the bottom of the
agent-view.mdpage, alongside the existing platform-specific macOS entries "Background sessions can't read Desktop, Documents, or Downloads on macOS" and "Background sessions can't reach local-network hosts on macOS". The Version history table at the very end of the same page also needs a row entry.Current Documentation
The
agent-viewTroubleshooting section currently includes two macOS-specific entries that document failure modes introduced and fixed in recent releases:The
v2.1.199row in the Version history table at the bottom ofagent-view.mdlists two changes:There is no troubleshooting entry for the "Could not switch to audit session" error, and no mention of the v2.1.199 audit-session cold-start fix in the version history.
What's Wrong or Missing?
The 2.1.199 release notes include the fix:
This regression affected every user who dispatched a background agent over an SSH session into a macOS host on 2.1.196, 2.1.197, or 2.1.198, since the supervisor failed to attach to the required audit session when starting a fresh worker process. The page already documents two other macOS-specific background-agent failure modes in the same Troubleshooting section, but the audit-session regression is undocumented there, so:
A. No troubleshooting entry for the error message
A user who dispatched
claude --bgor openedclaude agentsover SSH into a macOS host between 2.1.196 and 2.1.198 would see the session fail to cold-start with aCould not switch to audit sessionerror. Without a troubleshooting entry, that error string does not appear anywhere in the agent view docs, and the user has no path from the symptom to the fix. This matches the pattern of the existing two macOS entries, which both name a specific error string and walk the user through the cause and remediation.B. Version history is missing the fix
The
v2.1.199row in the Version history table omits the audit-session cold-start fix entirely. Other background-agent fixes shipped in the same release (SendMessagename disambiguation,/colorcarry-over, low-memory hint) are listed, but this one is not. Users who search the page for "audit session" or "cold-start" find nothing.C. SSH as a background-agent launch context is undocumented
The Troubleshooting section does not call out SSH-on-macOS as a background-agent launch context with its own failure modes. The page currently mentions SSH only in the context of Voice dictation and Desktop SSH sessions. Users who run
claude --bgover SSH into a remote macOS host have no signal that this is a supported deployment shape, nor a place to look when it breaks.Suggested Improvement
Add a new macOS troubleshooting entry to
agent-view.mdfollowing the existing two-entry pattern, and add the fix to thev2.1.199row of the Version history table.Option A — Comprehensive fix (recommended)
Insert a new subsection after "Background sessions can't reach local-network hosts on macOS":
Then extend the
v2.1.199row in the Version history table to mention the fix:Option B — Minimum fix
Only extend the
v2.1.199Version history row (the bullet above) and skip the standalone Troubleshooting entry. This still surfaces the fix on the page, but loses the error-string-to-fix linkage that the existing two macOS entries provide.Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
Total scope: 1 page affected (1 Troubleshooting section, 1 Version history row).
Version numbers: Regression introduced in v2.1.196 and fixed in v2.1.199. Affects every background-agent dispatch over SSH on macOS on v2.1.196, v2.1.197, and v2.1.198.
Related changelog entries in the same release that are documented but this one is not:
The v2.1.199 release also documents the
SendMessagename-disambiguation change insub-agents.md("As of v2.1.199,SendMessagechecks that a name still refers to the same agent it reached earlier in the conversation...") and theclaude --teleportSSH-host-alias change inclaude-code-on-the-web.md. Both have user-visible behavior described in the docs. The audit-session cold-start fix is the only user-visible 2.1.199 change on the agent-view side that has no documentation entry.Cross-reference: This is a regression fix; the docs team can rely on the
changelog.mdentry for v2.1.199 as the source of the regression scope. The page already follows a similar "document the user-visible regression scope inline" pattern for v2.1.198 (Background sessions can't reach local-network hosts on macOS), v2.1.196 (A single ← press backgrounds a foreground session; earlier versions required two presses), and v2.1.174 (background sessions no longer inherit gateway endpoint variables from the supervisor's launch shell).