[DOCS] Background session docs omit `--bg --dangerously-skip-permissions` persistence across retire/wake in v2.1.142

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Background session lifecycle and the "Permission mode, model, and effort" section for retired sessions that wake on attach, peek, or reply

Current Documentation

The docs currently say:

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.

And in the permission-mode section:

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 same page also explicitly documents persistence for model changes:

Attach to a running session and run /model there. The change persists if the session is respawned.

What's Wrong or Missing?

The background-session docs explain that retired sessions wake back up from saved state, and they separately explain how permission mode is chosen when a session starts, but they do not document whether a session started with claude --bg --dangerously-skip-permissions keeps bypassPermissions after that retire/wake cycle.

That leaves a user-visible gap for the v2.1.142 behavior change:

A. The docs do not state that bypass-permissions startup survives retire/wake

Users can learn that retired sessions restart from saved state, but not whether a session launched with --bg --dangerously-skip-permissions comes back in the same permission mode instead of reverting to the directory defaultMode.

B. The page documents persistence for model changes but not for this permission-mode case

Because the page already calls out that /model changes persist when a session is respawned, readers have no comparable guidance for bypassPermissions persistence across the same lifecycle.

Suggested Improvement

Add a short note in agent-view near the retire/wake lifecycle text or the permission-mode section clarifying that a background session launched with claude --bg --dangerously-skip-permissions keeps bypassPermissions when the process is retired and later restarted from saved state.

Suggested wording:

A background session launched with claude --bg --dangerously-skip-permissions keeps bypassPermissions when the supervisor retires the process and later wakes it on attach, peek, or reply. It does not fall back to the directory's defaultMode on wake.

If this guarantee also applies to the equivalent --permission-mode bypassPermissions form, document that alongside the direct flag so the two entry points are clearly aligned.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/agent-view | 302-318 | Explains how permission mode is chosen for claude --bg, but not whether bypass mode persists across retire/wake |
| https://code.claude.com/docs/en/agent-view | 366-366 | Explains that retired sessions wake from saved state on attach, peek, or reply |
| https://code.claude.com/docs/en/agent-view | 295-295 | Explicitly documents respawn persistence for /model, highlighting the missing parallel note for permission mode |

Total scope: 1 page affected

Version context: v2.1.142