[DOCS] Agent View supervisor: `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` from the starting shell now propagate to `claude agents` workers (v2.1.178)

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

"The supervisor process" subsection under "How background sessions are hosted" — and, by extension, the cross-reference to https://code.claude.com/docs/en/llm-gateway, which is the gateway setup page that does not call out the daemon propagation behavior at all.

Current Documentation

docs/code.claude.com/docs/en/agent-view.md says, in the supervisor section:

"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 LLM gateway page (docs/code.claude.com/docs/en/llm-gateway.md) only documents the foreground-CLI flow: it walks through setting ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL in the shell, but never mentions the supervisor or background sessions:

``bash # Set in environment export ANTHROPIC_AUTH_TOKEN=<gateway-token> ` `bash export ANTHROPIC_BASE_URL=https://litellm-server:4000 ``

The v2.1.178 changelog entry that introduced the relevant fix is not referenced from either page:

"Fixed claude agents workers failing with 401 Invalid bearer token when the daemon was started from a shell with a custom API gateway via ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN"

A related earlier fix in v2.1.174 is also unreferenced:

"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. The supervisor's environment inheritance is not documented

The current "supervisor authenticates with the same credentials as your interactive sessions" line is a black-box statement. A gateway operator reading the page has no way to learn that:

1. The supervisor is a per-user process that starts once and outlives the terminal that launched it.
2. The ANTHROPIC_* provider environment variables present in the shell at the moment claude agents (or claude --bg) is first invoked are captured by the supervisor and propagated to every worker process it spawns.
3. Prior to v2.1.174, this propagation leaked a previous session's provider env, and prior to v2.1.178, a worker spawned against a gateway that expects a bearer token from the launching shell received 401 Invalid bearer token even when ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN were correctly set in the user's shell.

This matters because the typical "Claude Code through a corporate gateway" deployment requires the user's shell to export ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN once, and expect every interactive and backgrounded session — including agents dispatched from claude agents — to honor those values. Before v2.1.178 that was silently broken for the background path.

B. The LLM gateway page does not mention the background-session path

llm-gateway.md walks the reader through setting ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL, then uses the resulting endpoint for foreground CLI work. It never states whether the same values apply to the supervisor, to workers dispatched from claude agents, or to claude --bg sessions. Gateway operators who rely on claude agents to triage work across repos have no signal from the gateway page that this is now supported, and no pointer to the v2.1.178 fix if they hit 401 errors against the gateway.

C. The v2.1.174 and v2.1.178 fixes are unmentioned on the relevant doc pages

The two changelog entries are factual, version-pinned behavior changes that affect how background sessions authenticate. A reader of the agent view or LLM gateway pages has no in-page cue that this corner of the system has recently changed, and no link to the changelog for the exact behavior.

Suggested Improvement

Add a short subsection under "The supervisor process" in agent-view.md that explains the propagation model and links to the gateway page, then add a pointer from the gateway page back to the supervisor behavior.

A. New subsection in agent-view.md, after the existing "The supervisor and its sessions authenticate…" paragraph

Suggested wording:

"### How the supervisor picks up provider environment variables The supervisor captures the ANTHROPIC_* provider environment variables (notably ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN) from the shell that first starts it, and reuses them for every worker process it spawns. This is what makes a background session or an agent dispatched from claude agents reach the same gateway as your interactive session. If you start the supervisor from a shell that does not export those variables, every worker it spawns authenticates against the first-party Anthropic API regardless of what other sessions on the machine are using. To re-pick the variables, stop the supervisor with claude daemon stop --any and start a new one from a shell that exports the gateway you want background sessions to use. See LLM gateway configuration for the supported gateway setup. Fixed in v2.1.178: workers previously failed with 401 Invalid bearer token when the supervisor was started from a shell that exported a gateway via ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN. Fixed in v2.1.174: background sessions no longer inherit a different session's ANTHROPIC_* provider env from the supervisor."

B. Pointer in llm-gateway.md, at the end of the "Configure Claude Code" block

Suggested wording:

"### Background sessions and the gateway The same ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN exports also apply to background sessions and to workers dispatched from claude agents. The supervisor process captures them from the shell that first starts it, so background workers reach the same gateway as your interactive session. If a worker fails with 401 Invalid bearer token, stop the supervisor with claude daemon stop --any and start it again from a shell that exports the gateway you want it to use. This was fixed for claude agents workers in v2.1.178."

C. Minimum fix (if a full subsection is too heavy)

If only one change is made, add the pointer from llm-gateway.md (item B). The gateway page is the natural place a user setting up ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN will read, and the pointer captures both the propagation behavior and the v2.1.178 fix in one short paragraph.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/agent-view | "The supervisor process" subsection under "How background sessions are hosted" — primary location that needs the new propagation explainer |
| https://code.claude.com/docs/en/llm-gateway | "Configure Claude Code" block — needs a pointer that the same exports apply to background workers and to claude agents |
| https://code.claude.com/docs/en/env-vars | The ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN rows describe the variables' foreground behavior; a "see also" link to the supervisor subsection would help gateway users land in the right place |
| https://code.claude.com/docs/en/changelog | v2.1.178 and v2.1.174 are the source of truth for the change; the two pages above are the ones users will land on first |

Version context: The fix was shipped in Claude Code v2.1.178. A related fix in v2.1.174 (background sessions no longer inheriting a different session's ANTHROPIC_* provider env) and v2.1.178 (workers correctly receive the launching shell's gateway bearer token) together make the "shell exports → supervisor → workers" path reliable for the first time.

Total scope: 2 pages need new content (agent view + LLM gateway); 1 page (env vars) benefits from a cross-reference link.