Use it now
New structured reason codes let a host app tell why Claude Code refused to start
What
Claude Code can now report a specific, structured reason when it refuses to start, instead of just failing silently or with a generic message. This is meant for a host application (like an IDE extension or desktop wrapper) that embeds Claude Code, so it can react to the specific cause rather than just retrying blindly. New reason values include:
worktree_resume_refusedandworktree_unverified(problems resuming a git worktree, an isolated working copy of a repo)session_held_by_background(another process is using the session)bypass_root(a root-related safety check)shell_tool_missing, tied to theCLAUDE_CODE_USE_POWERSHELL_TOOLsettingcli_version_too_oldgateway_signin_requiredandgateway_access_deniedorg_pin_api_key_conflict,org_verify_failed,org_pin_mismatchmanaged_settings_invalidandremote_settings_required_unavailableproxy_invalidtemp_dir_unusableandcwd_unavailable
Why
Giving each startup failure a distinct machine-readable reason lets host applications show the right message or take the right corrective action automatically, rather than treating every startup refusal the same way.