Follow Discord
Sweep 22 Sep 2026 · 17:19Z Build v2.1.280 501 read Stable v2.1.267 Latest v2.1.280 Next v2.1.280 Feeds RSS JSON llms.txt Unofficial
Claude Code v2.1.274 ·

Structured startup-refusal reasons for host integrations

New structured reason codes let a host app tell why Claude Code refused to start

TierUse it nowhow much it should matter to you
Useful3my rating, 1 to 5
Signal2worth watching, 1 to 5
AreaHost Integrationswhat it touches
KindNew Featuresin v2.1.274,
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_refused and worktree_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 the CLAUDE_CODE_USE_POWERSHELL_TOOL setting
  • cli_version_too_old
  • gateway_signin_required and gateway_access_denied
  • org_pin_api_key_conflict, org_verify_failed, org_pin_mismatch
  • managed_settings_invalid and remote_settings_required_unavailable
  • proxy_invalid
  • temp_dir_unusable and cwd_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.

See this entry in the whole of v2.1.274 →

Feedback