claude-code - 💡(How to fix) Fix [DOCS] Agent view docs omit `--fallback-model` persistence for `/bg` and `←` detach

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Set the model and Permission mode, model, and effort in the agent view/background session docs

Current Documentation

The agent view docs currently say:

The model name shown in the agent view header is the dispatch default. New sessions you start from the input use this model, which is the same setting /model controls in any session. To override it for the whole agent view session, pass --model when opening agent view.

Each background session can run on a different model. To override it for one session:

• From the shell, pass --model with claude --bg.
• Attach to a running session and run /model there. The change persists if the session is respawned.

The CLI reference currently says:

--fallback-model | Enable automatic fallback to specified model when default model is overloaded (print mode only)

The v2.1.143 changelog says:

/bg and ←-detach now preserve --fallback-model, so backgrounded workers degrade to the fallback model on overload instead of hard-failing.

What's Wrong or Missing?

The current docs do not reflect the new background-session behavior in v2.1.143.

A. Agent view does not document fallback-model persistence across /bg and ←

The page already documents persistence for some session attributes, such as /model changes persisting after respawn and permission mode persisting when backgrounding an existing session. It does not say that a session backgrounded with /bg or ← now also preserves --fallback-model for overload recovery.

B. CLI reference now appears incomplete or misleading for this workflow

The CLI reference still describes --fallback-model as print mode only. After v2.1.143, the changelog explicitly says the flag is preserved when sessions are backgrounded with /bg or ← detach, which is user-visible behavior in interactive/background-session workflows.

C. Users lack documentation for the failure mode this change fixes

Without this note, users reading the background-session docs have no indication that overload handling changes after backgrounding. The changelog describes a concrete behavioral difference: backgrounded workers now degrade to the fallback model instead of hard-failing.

Suggested Improvement

Update agent-view.md to document that backgrounding an existing session with /bg or ← preserves --fallback-model for future overload recovery.

Suggested wording near the existing persistence notes:

Backgrounding an existing session with /bg or ← also preserves --fallback-model. If the session later hits an overload condition that triggers model fallback, the backgrounded worker degrades to the configured fallback model instead of failing.

Also update cli-reference.md so the --fallback-model entry no longer implies this behavior is limited to print mode only, or add a cross-reference clarifying the interactive/background-session behavior introduced in v2.1.143.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 pages affected

Version context: v2.1.143