[DOCS] Background agent docs do not mention the pre-warmed worker dispatch path or its `env` settings behavior

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

• The "Permission mode, model, and effort" section in agent-view.md (currently states unconditionally that a background session reads its settings from the directory it runs in)
• The "How background sessions are hosted" / "The supervisor process" section in agent-view.md (does not document the pre-warmed worker / warm-spare worker dispatch path)
• The env setting row in the "Available settings" table in settings.md (does not mention dispatch-path behavior for background agents)

Current Documentation

The v2.1.169 changelog entry reads:

"Fixed background agents ignoring project-level settings env values (e.g. ANTHROPIC_MODEL) when dispatched onto a pre-warmed worker"

docs/code.claude.com/docs/en/agent-view.md (line 386) states unconditionally:

"A background session reads its settings from the directory it runs in, the same as if you had started claude there."

docs/code.claude.com/docs/en/settings.md (line 212) documents the env setting row as:

"env — Environment variables applied to every session and to subprocesses Claude Code spawns from it. {/ min-version: 2.1.143 /}As of v2.1.143, NO_COLOR and FORCE_COLOR set here are passed to subprocesses but do not change Claude Code's own interface colors. Set those in your shell before launching claude to change interface colors."

docs/code.claude.com/docs/en/agent-view.md (lines 456-468, "The supervisor process" section) describes how background sessions are hosted but does not mention the concept of a pre-warmed / warm-spare worker that handles dispatch:

"Each background session is its own Claude Code process, managed by the supervisor rather than tied to your terminal. … Once a session finishes and sits unattached for about an hour, the supervisor stops its process to free resources. … 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."

The only other reference to pre-warmed workers in the docs mirror is the Agent SDK TypeScript reference (docs/code.claude.com/docs/en/agent-sdk/typescript.md:585), which uses the term in a different (SDK subprocess) context.

What's Wrong or Missing?

A. The agent-view page does not document the pre-warmed worker dispatch path

The "How background sessions are hosted" section describes the supervisor process and how individual session processes are spun up or torn down, but it does not mention that the supervisor may keep one or more pre-warmed (warm-spare) worker processes to make dispatch from claude agents or claude --bg faster. The pre-warmed worker is the dispatch path that was affected by the v2.1.169 bug, 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.

B. The "Permission mode, model, and effort" statement is now correct, but the previous bug had no documentation trail

The line "A background session reads its settings from the directory it runs in, the same as if you had started claude there" was, before v2.1.169, only true on the cold-start dispatch path. On the pre-warmed worker dispatch path, project-level env values (e.g. ANTHROPIC_MODEL, CLAUDE_CODE_* overrides) were silently dropped. The docs never described this gap, and the v2.1.169 fix is presented in the changelog with no corresponding documentation note explaining what changed or why users might have hit the bug. Users who relied on env in .claude/settings.json to set ANTHROPIC_MODEL (or other env-driven overrides) for background agents had no way to predict that a project-level env could be ignored depending on the dispatch path.

C. The env setting row in settings.md does not mention background-agent dispatch behavior

The env setting is documented as "Environment variables applied to every session and to subprocesses Claude Code spawns from it." There is no note about the supervisor, pre-warmed workers, or the fact that env is what makes settings like ANTHROPIC_MODEL actually take effect in a background session. Users who set env.ANTHROPIC_MODEL in a project settings.json and then watch a background agent pick a different model have no documentation path that would explain why — and now that v2.1.169 fixes the case, no documentation path that would confirm the fix is in place.

D. No cross-reference from the changelog line to the affected pages

The v2.1.169 changelog line in changelog.md is the only place this behavior is described. agent-view.md and settings.md do not cross-reference it. A user who reads the changelog and wants to verify the fix or understand the dispatch model has to reverse-engineer it from the changelog text.

Suggested Improvement

Option A: Comprehensive fix

Add short, scoped documentation updates to make the pre-warmed worker dispatch path and its env behavior explicit, all referencing the v2.1.169 changelog:

1. In docs/code.claude.com/docs/en/agent-view.md, add a short paragraph to the "The supervisor process" section (after line 468) describing the pre-warmed worker:

"To make dispatch from claude agents or claude --bg faster, the supervisor keeps one or more pre-warmed background worker processes ready. A dispatch is normally served by a pre-warmed worker, and falls back to a fresh launch only if no healthy pre-warmed worker is available. As of v2.1.169, project-level env values (e.g. ANTHROPIC_MODEL) configured in .claude/settings.json are applied to a session dispatched onto a pre-warmed worker the same way they are for a cold-start launch."

1. In docs/code.claude.com/docs/en/agent-view.md (line 386 area), refine the "Permission mode, model, and effort" line so the settings-loading claim is paired with the dispatch-path note above. For example:

"A background session reads its settings from the directory it runs in, the same as if you had started claude there. As of v2.1.169, this includes project-level env values when the session is dispatched onto a pre-warmed worker; before v2.1.169 those values could be ignored on the pre-warmed dispatch path."

1. In docs/code.claude.com/docs/en/settings.md (line 212, the env row), add a sentence linking to the agent-view dispatch-path behavior and noting the v2.1.169 fix:

"Set in .claude/settings.json under env to apply to background agents dispatched via claude agents or claude --bg, including on the pre-warmed worker dispatch path. As of v2.1.169, these values are honored for pre-warmed dispatches; before v2.1.169 they could be ignored. See agent view."

Option B: Minimum fix

Add the new paragraph to "The supervisor process" in agent-view.md (item 1 above) so the pre-warmed worker is at least named and the v2.1.169 env fix is documented in passing. Leave settings.md and the "Permission mode, model, and effort" refinement 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 | 386 | "Permission mode, model, and effort" — unconditional claim about background sessions reading settings from the working directory; does not mention the pre-warmed worker dispatch path |
| https://code.claude.com/docs/en/agent-view | 456-468 | "The supervisor process" section — does not describe the pre-warmed / warm-spare worker concept |
| https://code.claude.com/docs/en/settings | 212 | env setting row — no note about background-agent dispatch or pre-warmed worker behavior |
| https://code.claude.com/docs/en/changelog | 27 | Sole mention of the v2.1.169 fix; no cross-references to agent-view or settings |

Total scope: 3 pages affected (one with two distinct gaps).

Cross-references:

• https://code.claude.com/docs/en/env-vars — should be cross-referenced from the new env wording in settings.md (the env-vars page already documents ANTHROPIC_MODEL precedence at line 80)
• https://code.claude.com/docs/en/model-config — relevant because ANTHROPIC_MODEL is the most common env value users set in project settings to pin a model; the new wording should not contradict the existing ANTHROPIC_MODEL precedence documentation

Version: v2.1.169 (June 8, 2026)