[DOCS] `claude agents` background sessions now pick up `effortLevel` changes from `settings.json` when forked by the daemon, but the persistence prose and Version history in agent-view still describe the old "effort from dispatch is locked" behavior

Open 💬 0 comments Opened Jul 7, 2026 by coygeek

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

The "Permission mode, model, and effort" subsection under "Background sessions" (around line 427-435 of agent-view.md) and the "Version history" table at the bottom of the same page. Cross-references in https://code.claude.com/docs/en/settings for the effortLevel row and https://code.claude.com/docs/en/model-config for the "Adjust effort level" → "Set the effort level" → "Settings" bullet should be checked in the same pass.

Current Documentation

The agent-view.md "Permission mode, model, and effort" section currently reads (line 429-435):

A background session reads its settings from the directory it runs in, the same as if you had started claude there. This includes env values in project settings, so an ANTHROPIC_MODEL or provider variable set there applies to background sessions in that directory. Cloud provider selection, such as CLAUDE_CODE_USE_BEDROCK or CLAUDE_CODE_USE_VERTEX, and ANTHROPIC_DEFAULT_*_MODEL aliases follow the shell that dispatched the session. Gateway endpoint variables such as ANTHROPIC_BASE_URL and its paired ANTHROPIC_AUTH_TOKEN don't. See [the supervisor process](#the-supervisor-process) for how background sessions source provider settings and credentials. The permission mode depends on how you started the session. Backgrounding an existing session with /bg or ← keeps the current permission mode, so a session you switched to acceptEdits or auto stays in that mode after detaching. Dispatching from the agent view input or running claude --bg from your shell uses the defaultMode from that directory's settings, or the permissionMode from the dispatched subagent's frontmatter. The permission mode, model, and effort a background session was started with, along with the [configuration flags it carries](#from-inside-a-session), all persist when the supervisor later [stops and restarts](#the-supervisor-process) its process. A session you launched with claude --bg --dangerously-skip-permissions or claude --bg --permission-mode bypassPermissions stays in bypassPermissions after that restart instead of falling back to the directory's defaultMode, and a model or effort you changed mid-session with /model or /effort is kept.

The agent-view.md Version history table ends with the v2.1.202 row:

| v2.1.202 | {/ min-version: 2.1.202 /}A name set with /rename or Ctrl+R on a background session persists when the supervisor stops and restarts its process, instead of reverting to the name the session was dispatched with. |

There is no v2.1.203 row, and the "Permission mode, model, and effort" prose above is unchanged from earlier versions.

The settings.md effortLevel row (line 251) describes the setting as:

effortLevel — Persist the effort level across sessions. Accepts "low", "medium", "high", or "xhigh". Written automatically when you run /effort with one of those values. --effort and CLAUDE_CODE_EFFORT_LEVEL override this for one session.

model-config.md line 436 lists the effortLevel setting as one of the effort-level sources but does not describe any background-session-specific fork/restart rule for settings.json changes.

What's Wrong or Missing?

A. The v2.1.203 fork-time `effortLevel` fix is not described anywhere

The v2.1.203 changelog entry reads:

Fixed background sessions ignoring effortLevel changes in settings.json when forked through the daemon

Before v2.1.203, when the supervisor (the "daemon" the entry refers to) forked/restarted a background session's process — for example after the supervisor stop/restart path, the binary auto-update path, or the on-wake idle-resume path — the forked session kept using the effortLevel it inherited at dispatch, even if the user had since edited settings.json to a different value. After v2.1.203, the forked session honors the current effortLevel from the project or user settings.json at the moment the daemon forks it.

Neither the agent-view.md "Permission mode, model, and effort" prose nor the agent-view.md Version history table mentions this fix. A user editing effortLevel in .claude/settings.json or ~/.claude/settings.json has no way to tell from the docs whether their next daemon-initiated fork will pick up the new value or stick to the dispatch-time value.

B. The persistence prose now reads as a guarantee that no longer holds

The "Permission mode, model, and effort" paragraph is currently phrased as a single "all of these persist" statement:

The permission mode, model, and effort a background session was started with...all persist when the supervisor later stops and restarts its process.

That phrasing was true for permissionMode (still true), for model (still true per the existing /model sentence), and for effortLevel only up to v2.1.202. After v2.1.203 the effortLevel case is the exception: a forked session re-reads effortLevel from settings.json rather than retaining the dispatch-time value. The paragraph does not separate the three, so a reader following the docs will infer that effort persistence behaves like permission-mode persistence and will be surprised when an edited effortLevel does start applying to forked sessions.

C. The Version history table is missing a v2.1.203 row

Every recent agent-view behavioral change (v2.1.195, v2.1.196, v2.1.198, v2.1.199, v2.1.200, v2.1.202) has its own row in the Version history table. The v2.1.203 fork/effortLevel fix has no row, so users who land on the page and skim the table will not learn that fork-time effort sourcing changed. Cross-references from https://code.claude.com/docs/en/settings (effortLevel row) and https://code.claude.com/docs/en/model-config ("Settings" bullet under "Set the effort level") also do not mention the background-session fork rule, so even readers who reach those pages have no path to the new behavior.

Suggested Improvement

Option A — Targeted prose fix in `agent-view.md`

Replace the current fourth paragraph in "Permission mode, model, and effort" with a versioned statement that distinguishes effortLevel from the other two fields, for example:

Before:

The permission mode, model, and effort a background session was started with, along with the [configuration flags it carries](#from-inside-a-session), all persist when the supervisor later [stops and restarts](#the-supervisor-process) its process. A session you launched with claude --bg --dangerously-skip-permissions or claude --bg --permission-mode bypassPermissions stays in bypassPermissions after that restart instead of falling back to the directory's defaultMode, and a model or effort you changed mid-session with /model or /effort is kept.

After:

The permission mode, model, and effort a background session was started with, along with the [configuration flags it carries](#from-inside-a-session), persist when the supervisor later [stops and restarts](#the-supervisor-process) its process. A session you launched with claude --bg --dangerously-skip-permissions or claude --bg --permission-mode bypassPermissions stays in bypassPermissions after that restart instead of falling back to the directory's defaultMode, and a model or effort you changed mid-session with /model or /effort is kept. {/ min-version: 2.1.203 /}effortLevel is the exception: when the daemon forks a background session's process, the fork re-reads the current effortLevel from the project or user settings.json instead of carrying the dispatch-time value over. Edit effortLevel in .claude/settings.json or ~/.claude/settings.json and the next daemon-initiated fork of any background session in that directory will use the new level.

Then add a v2.1.203 row to the Version history table at the bottom of agent-view.md:

| v2.1.203 | {/ min-version: 2.1.203 /}When the daemon forks a background session, the fork honors the current effortLevel value in the project or user settings.json instead of carrying the dispatch-time effort level over. |

Option B — Minimum-fix fallback

If only one change can ship in this release, at minimum add the Version history row for v2.1.203 (Option A's table change) so the new behavior is at least discoverable from the page footer, and add a single inline {/* min-version: 2.1.203 */} note after the existing persistence paragraph pointing at the effortLevel exception. The full paragraph rewrite can follow in a later doc pass.

Cross-reference updates

In the same pass, check these pages for related wording:

https://code.claude.com/docs/en/settings, effortLevel row — currently says "--effort and CLAUDE_CODE_EFFORT_LEVEL override this for one session" but does not describe how a background-session fork interacts with the persistent value. Add one sentence: "When the daemon forks a background session, the fork re-reads this value rather than using the dispatch-time value (v2.1.203+)."
https://code.claude.com/docs/en/model-config, "Adjust effort level" → "Set the effort level" → "Settings" bullet — currently lists effortLevel as a settings-file source alongside /effort, --effort, and the env var, but does not note the background-session fork rule. Add a parenthetical pointing back to the agent-view note.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/agent-view | 429-435 | "Permission mode, model, and effort" persistence prose now reads as a blanket guarantee that v2.1.203 weakens for effortLevel |
| https://code.claude.com/docs/en/agent-view | 656-668 | Version history table ends at v2.1.202; no v2.1.203 row for the fork/effortLevel fix |
| https://code.claude.com/docs/en/settings | 251 | effortLevel row does not describe the background-session fork rule |
| https://code.claude.com/docs/en/model-config | 436 | "Settings" bullet under "Set the effort level" does not describe the background-session fork rule |

Total scope: 4 pages affected

v2.1.203 changelog entry: