Summary
When an agent container starts, the provisioned ~/.claude.json does not contain the onboarding-completion flags expected by the installed Claude Code version, so Claude Code shows interactive onboarding dialogs (theme selection, trust-folder dialog, bypass-permissions warning) on first launch. These dialogs block the agent from starting until keystrokes are sent into the tmux session manually.
Observed
- Installed Claude Code in the agent image: v2.1.158
- Onboarding flags in the provisioned/template
.claude.json: generated for v2.0.76
- Result: a freshly started agent hangs at the onboarding prompts instead of running its task. Seen during state-fixes integration testing on the
scion-integration VM.
Impact
- New agents can fail to start unattended (no interactive TTY to dismiss the dialogs), which is especially problematic for hub/headless/automated runs.
- Version drift will recur whenever the bundled Claude Code version is bumped without refreshing the onboarding flags.
Likely root cause
The template/seed .claude.json (in the harness/home overlay) carries onboarding-completion keys tied to a specific Claude Code version. When the installed Claude Code version advances, the expected keys/shape change and the stale flags no longer suppress onboarding.
Suggested fix (options)
- Refresh the seed
.claude.json onboarding flags to match the Claude Code version pinned in the agent image, and keep them in sync when bumping the version.
- Programmatically set the onboarding-skip flags during provisioning based on the installed Claude Code version (so it can't drift), rather than shipping static values.
- Launch Claude Code with whatever non-interactive/onboarding-skip flag it supports, if available, as a belt-and-suspenders.
Notes
- Tangential to the agent state/lifecycle work (suspend/resume, crash→error) but discovered during that testing; filing separately per maintainer request.
Summary
When an agent container starts, the provisioned
~/.claude.jsondoes not contain the onboarding-completion flags expected by the installed Claude Code version, so Claude Code shows interactive onboarding dialogs (theme selection, trust-folder dialog, bypass-permissions warning) on first launch. These dialogs block the agent from starting until keystrokes are sent into the tmux session manually.Observed
.claude.json: generated for v2.0.76scion-integrationVM.Impact
Likely root cause
The template/seed
.claude.json(in the harness/home overlay) carries onboarding-completion keys tied to a specific Claude Code version. When the installed Claude Code version advances, the expected keys/shape change and the stale flags no longer suppress onboarding.Suggested fix (options)
.claude.jsononboarding flags to match the Claude Code version pinned in the agent image, and keep them in sync when bumping the version.Notes