fallback-model-setup

name	fallback-model-setup
description	Configures Claude Code's fallbackModel chain, --safe-mode troubleshooting protocol, and /cd workspace hygiene for production-resilient autonomous coding sessions. Audits current settings, installs the optimal three-model fallback chain, and documents a fast debugging loop. Requires Claude Code v2.1.166+.
version	1.0.0
category	productivity
platforms	["CLAUDE_CODE"]

You are configuring Claude Code for production resilience. Work autonomously — do not ask questions.

TARGET: $ARGUMENTS (defaults to current project if not specified)

============================================================ PHASE 1: AUDIT CURRENT CONFIGURATION

1. LOCATE SETTINGS FILES Find all active settings files in order of precedence:

   • ~/.claude/settings.json (user-global)
   • /.claude/settings.json (project-level)
   • /.claude/settings.local.json (local overrides, gitignored)

   For each file found, record:

   • Current model value
   • Whether fallbackModel is already set (and its current value)
   • Whether autoMode is configured
   • Hook definitions (PreToolCall, PostToolCall, Stop, etc.)
   • Plugin and skill configuration

2. CHECK CLAUDE CODE VERSION Run: claude --version

   fallbackModel, --safe-mode, and /cd all require v2.1.166 or higher. If the installed version is older, output the upgrade command and stop:

   npm install -g @anthropic-ai/claude-code@latest
   

3. IDENTIFY RUNNING ENVIRONMENT Check environment variables for CI context: CI, GITHUB_ACTIONS, CIRCLECI, BUILDKITE, JENKINS_URL, TRAVIS.

   Record environment type:

   • CI/CD pipeline: benefits most from fallbackModel (prevents failed overnight runs)
   • Developer workstation: benefits most from --safe-mode and /cd hygiene
   • Both: configure everything

============================================================ PHASE 2: CONFIGURE FALLBACKMODEL CHAIN

1. DETERMINE PRIMARY MODEL Read model from the effective settings.json. If unset, the runtime default is claude-opus-4-8.

2. WRITE FALLBACK CHAIN Apply to the project-level .claude/settings.json (create if absent). Use descending capability — most capable first, Haiku as the budget safety net:

   If primary is claude-opus-4-8:

   {
     "model": "claude-opus-4-8",
     "fallbackModel": [
       "claude-sonnet-4-6",
       "claude-haiku-4-5-20251001"
     ]
   }
   

   If primary is claude-sonnet-4-6:

   {
     "model": "claude-sonnet-4-6",
     "fallbackModel": [
       "claude-haiku-4-5-20251001"
     ]
   }
   

   If primary is already Haiku — no fallback exists. Flag this and recommend upgrading to Sonnet or Opus as the primary for any autonomous pipeline, then adding Haiku as the fallback.

3. VERIFY TOOL CAPABILITY ALIGNMENT Check whether the project uses tools that not all models support:

   • Computer use: not supported on Haiku — remove from chain if present
   • Extended thinking: not supported on Haiku — remove from chain if present
   • Agent tool (sub-agents): supported on all current models

   If a mismatch is found, remove the incompatible model from the chain and add a comment explaining why in the settings file.

4. VALIDATE JSON SYNTAX After writing settings.json, verify it parses:

   node -e "JSON.parse(require('fs').readFileSync('.claude/settings.json','utf8'))" && echo OK
   

   Fix and re-validate if the check fails.

============================================================ PHASE 3: INSTALL SAFE-MODE TROUBLESHOOTING PROTOCOL

1. CREATE OR UPDATE DEBUGGING RUNBOOK Create .claude/DEBUGGING.md (or append to it if it already exists):

   ## Claude Code — Troubleshooting Protocol
   
   ### Step 1: Safe mode isolation
   If Claude Code behaves unexpectedly (loops, crashes, wrong tool use,
   unexpected prompts):
   
       claude --safe-mode
   
   Safe mode disables ALL customizations: CLAUDE.md, hooks, plugins,
   bundled skills. If the problem disappears → the culprit is in your
   config stack.
   
   ### Step 2: Layer bisect (when safe mode is clean)
   Re-enable layers one at a time, testing after each:
   1. Hooks (most common source of loops — check PreToolCall first)
   2. Plugins
   3. CLAUDE.md / nested .claude/ directories
   4. Bundled skills (`disableBundledSkills: false`)
   
   ### Step 3: Hook log inspection
   Hooks write to stderr by default. To capture hook output during a
   session, temporarily add verbose logging:
   
       "hooks": {
         "PreToolCall": [{
           "matcher": ".*",
           "hooks": [{"type": "command", "command": "echo \"[hook] $CLAUDE_TOOL_NAME\" >&2"}]
         }]
       }
   
   ### Step 4: Change directory without restarting
   To switch project root mid-session without losing context or cache:
   
       /cd <new-directory>
   
   Prompt cache is fully preserved. /cd does not rebuild context from
   scratch. Use it instead of opening a new session.
   
   ### Step 5: Fallback model verification
   If you suspect a fallbackModel switch caused unexpected behavior,
   check the session log (~/.claude/logs/) for lines containing
   "fallback" to confirm which model was active at each point.
   

2. VERIFY HOOK STDERR OUTPUT (IF HOOKS EXIST) For any existing hook command, confirm it writes actionable output to stderr on failure. A hook that silently exits non-zero is harder to debug than one that prints a clear error message. Update any silent hooks to log to stderr:

   <your-hook-command> || echo "[hook failed] <hook-name>" >&2
   

============================================================ PHASE 4: AUDIT NESTED SUB-AGENT DEPTH (IF APPLICABLE)

1. SCAN FOR AGENT DEFINITIONS Check .claude/agents/*.md for sub-agent definitions. If no agent files exist, skip this phase and note "no agent files found."

2. AUDIT DEPTH CONSTRAINTS With v2.1.166+, sub-agents nest up to 5 levels deep. For each agent file found:

   • Determine whether it spawns child sub-agents
   • Estimate the maximum pipeline depth
   • Flag any pipelines exceeding depth 3 (they should be intentional and justified with a comment)

   Recommended depth budget:

   • Level 1: Orchestrator (parent session)
   • Level 2: Domain specialists (implement, test, review)
   • Level 3: Per-file workers (optional)
   • Levels 4–5: Reserved for deep recursive analysis only

3. ENSURE CHILD FAILURE HANDLING For each sub-agent that spawns children, verify its system prompt includes explicit failure handling. If it doesn't, add:

   If any child sub-agent fails its acceptance criteria, halt immediately
   and surface the child's transcript to the parent. Do not auto-retry.
   

   Auto-retry masks real problems. Hard-fail with transcript is the correct default.

============================================================ OUTPUT

Produce a concise audit report:

Claude Code Production Resilience Audit

Claude Code version: [installed version] — [OK ≥ 2.1.166 / UPGRADE REQUIRED]

fallbackModel chain:

• Primary: [model]
• Fallback 1: [model or "not configured"]
• Fallback 2: [model or "not configured"]
• Capability mismatches removed: [list or "none"]

Safe mode: [available / not available — old version] Debugging runbook: [created at .claude/DEBUGGING.md / updated / already exists]

Sub-agent audit:

• Agent definition files found: [count]
• Estimated max pipeline depth: [N levels]
• Failure-handling gaps fixed: [count]
• Depth concerns: [list or "none"]

Files modified:

• [list each file and what changed]

Next steps (manual):

• [anything requiring action outside this session]

============================================================ SELF-HEALING VALIDATION (max 2 iterations)

After producing output, validate:

1. All modified JSON files parse without errors.
2. The fallbackModel array contains only valid model IDs (no typos).
3. .claude/DEBUGGING.md exists and contains non-empty content.
4. If version check failed, the upgrade command is clearly stated.

If any check fails:

• Fix the failing item
• Re-run only that check
• Update the report

After 2 iterations, note any remaining gaps and stop.