claude-code - 💡(How to fix) Fix [DOCS] Background sessions docs omit effort-level persistence across idle wake

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

Set the model and Permission mode, model, and effort in the background session lifecycle documentation

Current Documentation

The docs currently say:

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.
• Dispatch a subagent whose frontmatter sets a model field.

And later:

To set defaults for every session you dispatch from agent view, pass any of --permission-mode, --model, or --effort when opening it:

claude agents --permission-mode plan --model opus --effort high

The page also explains the idle lifecycle:

Once a session finishes and sits unattached for about an hour, the supervisor stops its process to free resources. The transcript and state stay on disk, and the next time you attach, peek, or reply, the supervisor starts a fresh process from where it left off.

What's Wrong or Missing?

The page explicitly documents that a /model change persists when a background session is respawned, but it does not say whether an effort level changed with /effort or set with claude agents --effort is preserved across the same idle retire and wake cycle.

That leaves an important gap for background-session users in v2.1.143, whose changelog entry says:

Background sessions now preserve the model and effort level you set after waking from idle

Without a matching note in agent-view, readers can infer model persistence from the existing /model sentence, but they have no comparable guidance for effort. This is especially confusing because the page groups permission mode, model, and effort together, while only model gets an explicit respawn-persistence guarantee.

Suggested Improvement

Add a short parallel note for effort persistence anywhere the page already discusses model persistence or idle wake behavior.

For example, update the model/effort guidance to say:

Attach to a running session and run /model or /effort there. Those changes persist if the session is respawned after being retired while idle.

Or add a note under Permission mode, model, and effort clarifying that a background session keeps the model and effort level you set when the supervisor retires the process and later wakes it on attach, peek, or reply.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 1 page affected

Version context: Changelog v2.1.143 says background sessions now preserve the model and effort level you set after waking from idle.