[DOCS] [Agent view] Pre-warmed background workers no longer fail with "Could not resolve authentication method" when claimed after sitting idle, but the pre-warmed worker dispatch path is still not documented in `agent-view.md`

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The "The supervisor process" subsection in docs/en/agent-view.md and the "Troubleshooting" section. The v2.1.174 changelog fixes a case where pre-warmed background workers fail with "Could not resolve authentication method" when claimed after sitting idle, but agent-view.md does not document the pre-warmed worker concept or what triggers the "Could not resolve authentication method" error.

Current Documentation

docs/en/agent-view.md (line 461-475) currently says:

"### The supervisor process Background sessions are hosted by a per-user supervisor process, separate from your terminal and from agent view. The supervisor starts automatically the first time you background a session or open agent view, and you don't manage it directly. The supervisor and its sessions authenticate with the same credentials as your interactive sessions and make no additional network connections beyond the model API. Each background session is its own Claude Code process, managed by the supervisor rather than tied to your terminal. A session that's actively working, waiting for your input, or has a terminal attached keeps its process running. A running background shell command, subagent, dynamic workflow, or monitor counts as active work, so a long-running process such as a dev server keeps the session alive. Once a session finishes and sits unattached for about an hour, the supervisor stops its process to free resources. A session you have [pinned](#organize-the-list) with Ctrl+T is exempt and keeps its process running while idle. The transcript and state stay on disk either way, and the next time you attach, peek, or reply to a stopped session, the supervisor starts a fresh process from where it left off. When every session has finished and no terminal is connected, the supervisor itself exits and starts again the next time you need it."

docs/en/agent-view.md (line 519-528) currently says:

"### Agent view says the background service did not respond If attaching, peeking, or claude logs reports that the background service did not respond, the supervisor process has likely stalled. Stop it and let the next claude agents start a fresh one. To keep your background sessions running through the restart, pass --keep-workers: ``bash theme={null} claude daemon stop --any --keep-workers ``"

The v2.1.174 changelog entry reads:

"Fixed pre-warmed background workers failing with 'Could not resolve authentication method' when claimed after sitting idle"

The closest related changelog entries are at line 26 and line 71 of changelog.md:

"Fixed background agents potentially reading another directory's project settings (.mcp.json approvals, trust) when dispatched onto a pre-warmed worker" "Fixed background agents ignoring project-level settings env values (e.g. ANTHROPIC_MODEL) when dispatched onto a pre-warmed worker"

The only existing open issue referencing pre-warmed workers in the docs mirror is titled "[DOCS] Background agent docs do not mention the pre-warmed worker dispatch path or its env settings behavior" (open against the same agent-view.md page). The new v2.1.174 fix is a different bug ("Could not resolve authentication method" after idle), so it warrants a separate issue.

What's Wrong or Missing?

A. The pre-warmed worker dispatch path is not described in agent-view.md

The "supervisor process" subsection describes the supervisor and how individual session processes are started and stopped, but does not mention the pre-warmed (warm-spare) worker pool. The pre-warmed worker is the dispatch path the v2.1.174 bug affected, and the user-facing description of background agent behavior is silent about it. A user reading the page has no way to know that a dispatch can be served by a pre-existing worker process rather than a freshly spawned one, and no way to predict when "Could not resolve authentication method" might surface.

B. The "Could not resolve authentication method" error is not in the troubleshooting section

The v2.1.174 changelog is the only place the error string appears in the docs mirror. A user who hits it has no documentation path to identify the cause (idle pre-warmed worker) or the recovery (claim a fresh worker, or restart the supervisor). The existing "background service did not respond" entry at line 522 covers a different error path (stalled supervisor).

C. The "About an hour" idle window for the pre-warmed worker is undocumented

The supervisor stops individual session processes after about an hour of idleness, but a pre-warmed worker is a different kind of idle resource (it has no session attached to it, only the supervisor's claim pool). The page does not say whether pre-warmed workers time out the same way, persist indefinitely, or are recycled on a different schedule. The v2.1.174 fix is specifically for the "after sitting idle" case, so the idle window is relevant for users who dispatch a background session after a long gap.

D. The fix has no documentation trail for the authentication resolution path

The "Could not resolve authentication method" error suggests Claude Code failed to pick a credential source (env, settings file, or interactive login) for the pre-warmed worker's first request. The page does not say which credential sources a background session can use, or whether pre-warmed workers cache credentials the way they cache the project directory.

Suggested Improvement

Option A: Comprehensive fix

1. In docs/en/agent-view.md (line 461-475), add a new paragraph to "The supervisor process" describing the pre-warmed worker pool:

> "The supervisor keeps a small pool of pre-warmed background worker processes ready, separate from any session, so a dispatch from claude agents or claude --bg is normally served by a pre-warmed worker rather than a cold launch. A pre-warmed worker carries the project directory the supervisor launched it with and inherits the supervisor's captured authentication env, but does not load per-session state. A cold launch is used only when no healthy pre-warmed worker is available.
>
> Pre-warmed workers that sit idle for a long time can lose their cached authentication resolution and fail with Could not resolve authentication method on the first claim. As of v2.1.174, the supervisor falls back to a fresh worker when a claimed pre-warmed worker fails to authenticate, so a single stale worker no longer surfaces this error to the user. If the error persists after the fix, restart the supervisor with claude daemon stop --any --keep-workers to recycle the pre-warmed pool."

1. In the "Troubleshooting" section (after line 528), add a new entry:

> "### Dispatch fails with 'Could not resolve authentication method'
>
> If a background dispatch fails with Could not resolve authentication method even though your interactive sessions authenticate normally, the pre-warmed worker that handled the dispatch lost its cached credential resolution while sitting idle. As of v2.1.174, the supervisor retries on a fresh worker and the error does not surface. If the error recurs, stop and restart the supervisor to recycle the pre-warmed pool:
>
> ``bash theme={null}
> claude daemon stop --any --keep-workers
> ``
>
> See [the supervisor process](#the-supervisor-process) for how the pre-warmed worker pool is sized and when it is used."

1. In docs/en/errors.md, add a new error entry for Could not resolve authentication method pointing to the new troubleshooting section.

Option B: Minimum fix

Add the pre-warmed worker paragraph to "The supervisor process" only. Leave the troubleshooting entry and the errors.md cross-reference for a later pass.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/agent-view | 461-475 | "The supervisor process" — does not describe the pre-warmed worker pool or the dispatch path |
| https://code.claude.com/docs/en/agent-view | 519-528 | "Troubleshooting" — "background service did not respond" entry covers a different error; no entry for Could not resolve authentication method |
| https://code.claude.com/docs/en/errors | (table) | No entry for Could not resolve authentication method |
| https://code.claude.com/docs/en/changelog | 26 | Sole mention of the v2.1.174 fix; related fixes at lines 26 (project settings) and 71 (env values) |

Total scope: 2 pages with two distinct gaps, plus the changelog and a related open issue that covers the pre-warmed worker concept from a different angle (the env fix in v2.1.169).

Cross-references:

• https://code.claude.com/docs/en/agent-view#how-background-sessions-are-hosted — the new paragraph should sit under the existing "supervisor process" subsection, not duplicate it
• https://code.claude.com/docs/en/settings#available-settings — the env setting row at line 239 already documents project-level env behavior; the new pre-warmed worker paragraph should be consistent with that documentation
• https://code.claude.com/docs/en/llm-gateway — gateway URL behavior on background sessions should be cross-referenced; the same authentication resolution path is at issue

Related open issue: [DOCS] Background agent docs do not mention the pre-warmed worker dispatch path or its env settings behavior (open, against agent-view.md) covers a related but distinct gap (the env values dropped in v2.1.169 vs the authentication resolution fix in v2.1.174). The new pre-warmed worker paragraph proposed here overlaps with the existing issue's Option A (item 1) and could be merged in a future documentation pass, but is filed separately because the v2.1.174 fix introduces a new error string and a new troubleshooting entry that the existing issue does not cover.

Version: v2.1.174 (June 12, 2026)