[DOCS] [Agent view] Background-session supervisor no longer inherits the parent shell's `ANTHROPIC_*` env on dispatch, but `agent-view.md` never said the supervisor inherited from the starting shell in the first place

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The "Permission mode, model, and effort" subsection and the "The supervisor process" subsection in docs/en/agent-view.md. The v2.1.174 changelog fixes a case where the background daemon started from a shell passed its ANTHROPIC_* provider env (gateway URL, custom headers, /model aliases) into background sessions; agent-view.md does not document which environment the supervisor launches from.

Current Documentation

docs/en/agent-view.md (line 385-388) currently says:

"### Permission mode, model, and effort A background session reads its settings from the directory it runs in, the same as if you had started claude there."

docs/en/agent-view.md (line 461-465) 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."

The v2.1.174 changelog entry reads:

"Fixed background sessions inheriting another session's ANTHROPIC_* provider env (gateway URL, custom headers, /model aliases) from the shell that started the background daemon"

What's Wrong or Missing?

A. agent-view.md does not say which env the supervisor launches in

The "supervisor process" section says the supervisor "authenticates with the same credentials as your interactive sessions" but does not say which session, which env block, or which moment of capture. Before v2.1.174 the supervisor captured ANTHROPIC_* from the shell that started the daemon (e.g. an interactive claude session with a gateway URL set), and that captured env leaked into every background session that ran on the supervisor afterwards. The fix isolates the supervisor, but the page does not say what the supervisor's env is or how the credentials are sourced.

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

Line 387 — "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.174, only true for settings files. The ANTHROPIC_* provider env (gateway URL, custom headers, /model aliases) was not in the settings file, so it came from the supervisor's own inherited shell, not the directory. Users on a project ANTHROPIC_BASE_URL had no way to know why their background session hit a different gateway than the foreground session in the same directory.

C. The supervisor's authentication model is under-documented

The supervisor auth flow is described at line 465 only as "authenticates with the same credentials as your interactive sessions". After v2.1.174, "the same credentials" means the credential store the supervisor was started with, not the shell env of the moment. The page does not say:

• The supervisor launches once, on first dispatch, and keeps running across sessions.
• The env that the supervisor launches with is the env of whatever process first triggered it (interactive claude session, a claude --bg shell, or claude agents).
• ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, and the ANTHROPIC_DEFAULT_*_MODEL env vars are now scoped to the supervisor's launch env, not inherited by background sessions from any later shell.

Suggested Improvement

Option A: Comprehensive fix

1. In docs/en/agent-view.md (line 461-465), expand the "The supervisor process" section to describe the supervisor's launch env:

> "### 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 launches once with the environment of whatever process triggered the first dispatch — typically the interactive claude session or shell where you ran claude --bg or claude agents. It captures that environment's authentication and provider settings, including ANTHROPIC_BASE_URL (gateway URL), ANTHROPIC_AUTH_TOKEN and custom headers, and the ANTHROPIC_DEFAULT_*_MODEL aliases.
>
> The supervisor and its sessions authenticate with the same credentials as your interactive sessions and make no additional network connections beyond the model API. As of v2.1.174, the supervisor's captured env is the source of truth for ANTHROPIC_* provider settings across every background session it hosts, so a background session no longer inherits those values from the shell that started a particular dispatch. If you change the provider env (e.g. switch gateway URLs) and want new background sessions to pick it up, restart the supervisor with claude daemon stop --any --keep-workers and re-trigger it from the new shell."

1. In the "Permission mode, model, and effort" subsection (line 385-388), append a short note:

> "Project-level env values in .claude/settings.json are honored for background sessions, including on the pre-warmed worker dispatch path (see [supervisor process](#the-supervisor-process)). The ANTHROPIC_* provider env (gateway URL, auth token, /model aliases) comes from the supervisor's own launch env as of v2.1.174, not from the project directory."

Option B: Minimum fix

Add the supervisor launch env paragraph only. Leave 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 | 385-388 | "Permission mode, model, and effort" — does not say the ANTHROPIC_* env comes from the supervisor's launch env, not the working directory |
| https://code.claude.com/docs/en/agent-view | 461-465 | "The supervisor process" — does not describe the supervisor's launch env or how ANTHROPIC_* provider settings are captured |
| https://code.claude.com/docs/en/settings | 239 | env setting row — does not mention that ANTHROPIC_* provider env on background sessions comes from the supervisor's launch env, not from env in project settings |
| https://code.claude.com/docs/en/env-vars | (table) | ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, and ANTHROPIC_DEFAULT_*_MODEL rows describe foreground behavior only; no note about background-session scoping |
| https://code.claude.com/docs/en/changelog | 18 | Sole mention of the v2.1.174 fix; no cross-references |

Total scope: 4 pages affected, plus the changelog.

Cross-references:

• https://code.claude.com/docs/en/agent-view#troubleshooting — line 522 already discusses supervisor restarts for "background service did not respond" errors; the new supervisor launch env paragraph should cross-reference the restart command
• https://code.claude.com/docs/en/llm-gateway — gateway URL behavior on background sessions should match what the LLM gateway page documents for foreground sessions
• https://code.claude.com/docs/en/troubleshoot-install — Could not resolve authentication method errors on background dispatches would surface here if the supervisor's launch env was empty

Version: v2.1.174 (June 12, 2026)