[BUG] --agent flag triggers full onboarding (login/theme/trust, ~9 steps) on every restart in Docker, regardless of persisted state or credential type

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Starting a session with --agent <name> (loading a subagent's system prompt/tools/model as the identity of the top-level CLI process, not via the Task tool) triggers a full re-onboarding flow — login confirmation, theme selection, trust dialog, and other first-run screens (roughly 9 steps) — on every single container restart, even when:

• The container's ~/.claude.json already has hasCompletedOnboarding: true, hasTrustDialogAccepted: true at the root, and a projects["<cwd>"].hasTrustDialogAccepted: true entry for the exact working directory used.
• A valid, working OAuth credential is mounted (~/.claude/.credentials.json) — confirmed working, since after clicking through the 9 screens the session operates completely normally (tools, cross-session messaging via Remote Control, etc.).
• A valid ANTHROPIC_API_KEY from Claude Console is supplied via env var instead of OAuth, with no .credentials.json present at all.

Removing --agent (using only --name <name> for cosmetic identification, with actual identity/tool-restriction handled separately via a mounted CLAUDE.md + settings.json override) makes the 9-step prompt disappear entirely, and the session starts cleanly. So the flag itself — not the account state, not the credential type, not the filesystem — appears to be what triggers the repeated onboarding.

I tested three independent variables to isolate the cause, all with --agent <name> active:

| Variable | Home directory | Credential | Result |
|---|---|---|---|
| 1 | Shared ~/.claude across multiple concurrent containers | OAuth (.credentials.json) | 9-step onboarding on restart |
| 2 | Fully isolated ~/.claude per container (own claude.json with trust pre-populated, no shared files at all) | OAuth (.credentials.json, copied and valid) | 9-step onboarding on restart |
| 3 | Fully isolated ~/.claude (new, clean, no .credentials.json) | ANTHROPIC_API_KEY env var (no OAuth involved) | 9-step onboarding on restart |

All three reproduce the same signature. This rules out shared-state/concurrency as the cause, and rules out the credential type/method as the cause.

What Should Happen?

--agent <name> at CLI startup should respect the same persisted onboarding/trust state that a plain claude --name <name> (or a session without --agent) already respects — i.e., it shouldn't force first-run screens on every restart once onboarding/trust has already been completed and persisted for that config directory + working directory + account.

Steps to Reproduce

1. Build/use any Claude Code Docker image with a valid ~/.claude/agents/<name>.md custom agent definition (frontmatter tools:/model: + body as system prompt).
2. Run once interactively: docker run -it --rm -v $HOME/.claude:/home/claude/.claude -v $HOME/.claude.json:/home/claude/.claude.json --network host <image> claude --agent <name>. Complete the onboarding/login/theme/trust flow once.
3. Exit the container (--rm removes it, but the mounted ~/.claude directory persists on the host with the completed onboarding state).
4. Run the exact same command again.
5. Expected: clean start, no onboarding screens (state was persisted).
6. Actual: the full ~9-step onboarding/login/theme/trust flow reappears, every time, as long as --agent is present. Removing only the --agent flag (keeping everything else identical, including the mounted config) makes it start cleanly.

Claude Model

None — reproduces regardless of --model.

Is this a regression?

I don't know — first time this setup used --agent as a CLI flag (previously the agent's identity/system-prompt was applied via a different mechanism).

Last Working Version

_No response_

Claude Code Version

2.1.239 (Claude Code) — reproduced inside the Docker image. Host CLI (not used for reproduction, only for context) is 2.1.240.

Platform

Anthropic API / Claude Pro-Max subscription (OAuth), also reproduced with a Claude Console ANTHROPIC_API_KEY.

Operating System

Linux (Docker container, Debian/Node-based dev image), host is Linux. --network host is used on the container.

Terminal/Shell

bash, docker run -it

Additional Information

This is a multi-agent setup: several specialized Claude Code identities (each with a distinct ~/.claude/agents/<name>.md custom agent definition, restricted tools:) are meant to run as separate long-lived Docker containers, restarted frequently (sometimes daily/on-demand). --agent is the natural mechanism to apply each identity's system prompt + hard tool restrictions at the CLI level, but the repeated 9-step confirmation on every restart makes it impractical for unattended/frequent restarts — we ended up working around it by not using --agent at all (relying on a mounted CLAUDE.md for identity and settings.json permissions.deny for tool restriction instead), which works but loses the native, single-flag mechanism --agent is meant to provide.

Happy to provide --debug logs from a fresh reproduction if useful — didn't include them here since I don't currently have a live container running for this issue, but can capture on request.