{"version":"2.1.274","anchor":"structured-startup-refusal-reasons-for-host-integrations","canonical_anchor":"structured-startup-refusal-reasons-for-host-integrations","heading":"Structured startup-refusal reasons for host integrations","tier":"use","area":"Host Integrations","scope":null,"heads_up":null,"url":"https:\/\/changelogs.core-directive.com\/v\/2.1.274\/e\/structured-startup-refusal-reasons-for-host-integrations","release_url":"https:\/\/changelogs.core-directive.com\/v\/2.1.274","markdown":"### Structured startup-refusal reasons for host integrations\n\nNew structured reason codes let a host app tell why Claude Code refused to start\n\n**What**\n\nClaude 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:\n\n- `worktree_resume_refused` and `worktree_unverified` (problems resuming a git worktree, an isolated working copy of a repo)\n\n- `session_held_by_background` (another process is using the session)\n\n- `bypass_root` (a root-related safety check)\n\n- `shell_tool_missing`, tied to the `CLAUDE_CODE_USE_POWERSHELL_TOOL` setting\n\n- `cli_version_too_old`\n\n- `gateway_signin_required` and `gateway_access_denied`\n\n- `org_pin_api_key_conflict`, `org_verify_failed`, `org_pin_mismatch`\n\n- `managed_settings_invalid` and `remote_settings_required_unavailable`\n\n- `proxy_invalid`\n\n- `temp_dir_unusable` and `cwd_unavailable`\n\n**Why**\n\nGiving 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.\n\n- Area: Host Integrations\n- Tier: Use it now\n- Useful: 3\/5\n- Signal: 2\/5"}