Ripristino di Claude Code: safe mode, /cd e fallback

Materiali pratici per lavorare con gli agenti: documentazione Ailoot.

Cosa cambia in Claude Code a giugno 2026?#

In precedenza, quando Claude Code iniziava a comportarsi in modo strano—un indicatore di caricamento infinito, un arresto anomalo all'avvio, l'agente che ignorava le regole in CLAUDE.md, un hook che non si attivava senza dare segnali—c'era una sola via d'uscita: commentare manualmente le sezioni di .claude/settings.json, disabilitare i server MCP uno per uno o, nel peggiore dei casi, eliminare ~/.claude e reinstallare. In un caso descritto, è stata eliminata ~/.claude ed è andata persa la configurazione dei server MCP, che aveva richiesto un'ora e mezza di lavoro. In seguito è emerso che la causa era una riga in CLAUDE.md, che si sarebbe potuta individuare in 10 secondi, ma lo si è capito solo dopo un ripristino completo.

Nel giugno 2026, Anthropic ha introdotto tre meccanismi che cambiano questo scenario. In breve, cosa è arrivato e quando:

Di seguito, ogni meccanismo viene spiegato passo dopo passo, insieme all'ordine in cui applicarli quando una sessione di Claude Code deraglia.

Cosa manda più spesso in crisi Claude Code?#

Nell'esempio descritto, CLAUDE.md era stato inizialmente composto da 80 righe e aveva funzionato per un mese. Nel secondo mese, si è iniziato a notare che una volta a settimana Claude violava tutte le regole impostate: toccava .env, eseguiva git push --force, frugava in node_modules. Non per malizia: semplicemente dimenticava. Una volta è stato eliminato .gitignore e non era subito chiaro il motivo. Questo scenario è trattato più nel dettaglio nella guida a CLAUDE.md.

Quando CLAUDE.md supera le 400 righe, inizia a creare problemi silenziosamente: occupa una parte significativa della finestra di contesto all'avvio della sessione e diluisce le istruzioni importanti tra quelle secondarie. Claude continua formalmente a leggere il file, quindi dall'esterno sembra che «le regole ci siano, ma non funzionino»: un segnale tipico di un contratto troppo esteso.

Gli hook sono la seconda causa comune. Claude Code hooks presentano una particolarità che Anthropic non sottolinea.

In altre parole, sys.exit(1) in un hook Python (o qualsiasi convenzionale «errore» Unix) non fermerà Claude. Solo il codice 2 è bloccante. Nel caso descritto, l'hook era considerato un «divieto assoluto», ma in pratica registrava una segnalazione e consentiva l'azione.

I server MCP sono il terzo livello e possono rompersi a modo loro.

Spesso il sintomo è lo stesso: i comandi MCP sono disponibili, ma restituiscono failed senza traceback. Per saperne di più sulla configurazione di MCP e sull'aggiunta di server con claude mcp add, consulta la guida dedicata.

La quarta causa è la gerarchia a tre livelli di settings.json. Ci sono ~/.claude/settings.json (livello utente), .claude/settings.json nella radice del progetto (progetto), .claude/settings.local.json (locale) e, facoltativamente, le impostazioni gestite da un amministratore aziendale. Vengono combinate secondo regole di priorità. Quando qualcuno aggiunge un server MCP a livello di progetto mentre al livello utente ne hai una voce simile con una configurazione di avvio diversa, si verifica un conflitto silenzioso che dà l'impressione che «Claude Code sia rotto».

Come funziona --safe-mode e cosa disabilita?#

La formulazione originale di Anthropic nel changelog della v2.1.169 è:

Anthropic chiarisce nella documentazione sulla configurazione del modello:

È uno strumento diagnostico, non un «ambiente pulito». Safe mode aiuta a rispondere a una domanda: il problema dipende dal comportamento predefinito di Claude Code o dalle personalizzazioni aggiunte? Questo rientra nel context engineering: gestire ciò che Claude vede e non vede in un dato momento. Se in safe mode funziona tutto, è chiaro che i livelli vanno controllati con una ricerca binaria. Se non funziona, il problema riguarda l'installazione, l'autorizzazione, la rete o l'infrastruttura; in tal caso ha senso controllare claude doctor e i log.

Cosa disabilita safe mode (elenco ufficiale di Anthropic: 5 livelli principali):

• CLAUDE.md a tutti i livelli (utente / progetto)
• Plugin
• Skill
• Hook
• Server MCP

Cosa continua a funzionare:

• Autorizzazione (la sessione OAuth o la chiave API)
• Selezione del modello (--model sonnet, --model opus)
• Strumenti integrati (Read, Write, Bash, Grep e così via)
• Permessi
• Stato di Git
• Nomi delle directory

Un dettaglio importante: safe mode non disabilita le impostazioni gestite o di policy definite da un amministratore aziendale. Se lavori in un team in cui Bedrock GovCloud o una configurazione MDM imposta availableModels, tali restrizioni restano attive: safe mode disabilita solo le tue personalizzazioni, non le policy aziendali.

Come isolare un livello e trovare il colpevole in 60 secondi?#

Uno scenario diagnostico per quando Claude Code «ha smesso di ascoltare». La versione minima per tutti i comandi seguenti è Claude Code v2.1.169. Se la tua è più vecchia, aggiornala prima (npm update -g @anthropic-ai/claude-code o il programma di installazione nativo di Anthropic).

1. Apri la stessa cartella in cui si verificavano i problemi.
2. Esegui claude --safe-mode.
3. Se si avvia correttamente, verifica la richiesta originale. Ha funzionato? Allora la causa è in uno dei livelli. Vai al passaggio 4.
4. Se non funziona neanche in safe mode, non toccare le configurazioni. Esegui prima claude doctor; controlla l'autenticazione, la versione e le installazioni in conflitto.

Quando safe mode si avvia correttamente, riattiva i livelli uno alla volta, cominciando dal più probabile responsabile. L'ordine basato sull'esperienza descritta:

1. CLAUDE.md. Esegui claude senza safe mode, ma rinomina temporaneamente il file: mv CLAUDE.md CLAUDE.md.bak. Se funziona, la causa è quel file. Puoi poi fare una ricerca binaria: mantieni metà delle righe e verifica.
2. Hook. Apri .claude/settings.json e imposta temporaneamente [] nella sezione hooks. Riavvia claude. Funziona? Allora la causa è uno degli hook. Riattivali uno alla volta.
3. Server MCP. Allo stesso modo, in ~/.claude.json o .claude/settings.json, imposta temporaneamente la sezione mcpServers come oggetto vuoto, riavvia e controlla.
4. Skill. Sposta .claude/skills/ in una cartella temporanea. Avvia e controlla.

Cosa significa «rinominare temporaneamente»: durante la diagnosi i file non vengono eliminati. mv o git stash consentono di ripristinare tutto con un solo comando se quel livello non è la causa.

Come cambiare la cartella di lavoro con /cd senza perdere il contesto?#

Dal changelog della v2.1.169 dell'8 giugno:

Perché è utile quando si cerca di risolvere un problema. Supponi di trovarti nella cartella del progetto ~/work/myapp e che Claude Code si comporti in modo strano. Prima, l'unico modo per verificare «funziona almeno?» era chiudere la sessione, spostarsi in un'altra cartella e ricominciare. Perdevi contesto, cronologia e cache dei prompt già riscaldata. Ora:

# In the same session:
/cd ~/sandbox/test

Claude passa alla nuova cartella e legge il suo CLAUDE.md (se presente) come messaggio, non come sostituzione del prompt di sistema: la cache viene quindi preservata. Se in ~/sandbox/test funziona tutto, è chiaro che il problema era nella configurazione di ~/work/myapp.

Il 12 giugno, la v2.1.176 ha corretto una regressione fastidiosa: /cd mostrava il vecchio branch git fino a un riavvio completo. Se la tua versione è più vecchia, aggiornala oppure ignora semplicemente git status per i primi messaggi dopo il passaggio: si aggiornerà.

Come configurare i modelli di fallback per un errore 529?#

Nello scenario descritto, una volta a settimana un'attività lunga viene eseguita su Opus in un progetto; dopo 10 minuti, l'API restituisce 529 Overloaded e la sessione si arresta. Prima bisognava aspettare oppure passare manualmente a Sonnet con --model sonnet, perdendo tutto il contesto già riscaldato. In una cartella business/ estesa con una configurazione second-brain, servono circa venti minuti di lavoro. Ora esiste un meccanismo apposito.

La citazione esatta della documentazione ufficiale:

E, separatamente, il funzionamento della catena:

Due modi per configurarlo. Tramite CLI:

claude --fallback-model sonnet,haiku

Tramite ~/.claude/settings.json:

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

Una precisazione sui limiti di richieste. Anthropic non passa deliberatamente un errore 429 alla catena, così non è possibile aggirare il limite passando al modello successivo. Il fallback funziona solo quando il modello primario è sovraccarico, non disponibile o restituisce un errore del server non ritentabile (ad esempio, 529 Overloaded). Per i limiti di richieste si usano la normale logica dei tentativi e l'attesa progressiva.

Un'altra precisazione: il 12 giugno, la v2.1.174 ha corretto una regressione: la compattazione non rispettava --fallback-model. Se hai una sessione lunga e viene compattata mentre il servizio è sovraccarico, prima di questa correzione il modello di fallback non veniva chiamato. Se lavori con sessioni lunghe (/compact, /loop durante la notte), aggiorna almeno alla v2.1.174.

Cosa correggere se la causa è CLAUDE.md, un hook, MCP o una skill?#

Strategie specifiche per ogni livello.

Se la causa è CLAUDE.md

Apri il file e controllane la lunghezza. Sulla base dell'esperienza descritta, mantieni il CLAUDE.md attivo entro un massimo di 200 righe; sposta il resto in router e documenti di supporto accanto al progetto (la struttura completa second-brain è nella guida al second brain). Se supera le 400 righe, è quasi certamente la causa. Passaggi:

1. Crea un backup: cp CLAUDE.md CLAUDE.md.full.
2. Ripristina un modello breve e funzionante. Ne trovi uno pronto nella guida «Come configurare CLAUDE.md».
3. Riavvia Claude Code. Verifica.
4. Se funziona, ripristina le regole in piccoli blocchi da 10–20 righe, verificando dopo ogni blocco.
5. Individua il blocco che altera il comportamento. Riscrivilo come hook con il codice di uscita corretto (i codici di uscita degli hook sono trattati nella sottosezione successiva di questo H2).

Se la causa è un hook

La domanda principale è se il codice di uscita è corretto. Gli hook di Claude Code usano:

• Exit 0 — tutto a posto; l'azione procede.
• Exit 1 — un errore, ma non bloccante. Claude continua come se nulla fosse.
• Exit 2 — un errore bloccante. Solo questo ferma davvero l'azione.

Se hai scritto sys.exit(1) o exit 1 in un hook shell pensando di bloccare, in Claude Code quel codice funziona come un avviso nel log e non ferma l'azione. Cambialo in 2. Per i dettagli sugli hook e su come configurarli evitando questa insidia, consulta la guida dedicata.

Il secondo caso comune è un hook che restituisce JSON non valido su stdout. Claude Code analizza la risposta dell'hook come JSON e, se contiene elementi estranei (un log, un indicatore di avanzamento, un'emoji), considera l'hook fallito e l'azione prosegue. Regola: solo JSON su stdout; tutto il resto va su stderr.

Il terzo caso riguarda un hook che legge qualcosa da ~/.claude/ che safe mode ha nascosto. È uno scenario normale: invece di modificare l'hook, controlla os.environ.get('CLAUDE_CODE_SAFE_MODE') all'inizio e termina con 0.

Se la causa è un server MCP

Sintomi: i comandi MCP sono disponibili, ma restituiscono failed senza un traceback chiaro. Passaggi:

1. Esegui claude mcp list: quali server sono definiti?
2. Disabilita i server uno alla volta in ~/.claude.json: rinomina la chiave claude-server-A in _claude-server-A (la disattiva senza eliminarla).
3. Riavvia claude. Verifica quali chiamate funzionano.
4. Una volta individuato il server responsabile, controllane il log: claude mcp logs <name>.
5. Se è un server di terze parti (@modelcontextprotocol/server-postgres e simili), controlla se è disponibile una versione recente. L'ecosistema MCP è ancora in subbuglio: i server si rompono regolarmente con gli aggiornamenti di Claude Code.

Se incontri «arresti all'avvio solo con due MCP», confronta il comportamento in safe mode, senza MCP.

Se la causa è una skill

Una skill è composta da SKILL.md e dal codice in .claude/skills/<name>/. Sintomi: Claude ignora la skill, la applica al momento sbagliato oppure la applica ma produce risultati scadenti. Passaggi:

1. Apri SKILL.md. Controlla la descrizione: dovrebbe essere di 1–2 frasi e indicare nello specifico quando usarla. Se dice «un assistente universale per ogni cosa», Claude non capisce quando attivarla.
2. Controlla che non ci siano contraddizioni con CLAUDE.md. Se CLAUDE.md dice «scrivi sempre test», ma la descrizione della skill dice «usala per prototipi rapidi senza test», c'è un conflitto.
3. Se la skill usa comandi esterni (npm, python, git), controlla che siano disponibili nel PATH di sistema. Una skill ha un proprio ambiente minimale.

Cosa fare se safe mode non è servito: diagnosi e conservazione dello stato prima della riparazione#

Rimuovere lo stato utente non è una scorciatoia diagnostica. Usa i controlli seguenti per individuare il guasto; se non sono conclusivi, conserva le prove e indaga ancora. Ogni riparazione inizia con un backup verificato e mantiene account e identità dell’archivio credenziali esistenti. Ordine:

1. claude doctor — diagnosi automatica. Anthropic scrive nella documentazione:

2. Controlla le installazioni in conflitto. Molte persone hanno installato contemporaneamente una versione globale npm e il programma di installazione nativo:

3. Controlla se ANTHROPIC_API_KEY sta intercettando la sessione OAuth. È una causa comune di «non funziona niente, la chiave è scaduta»:

Soluzione: esegui unset ANTHROPIC_API_KEY nella sessione shell corrente oppure rimuovila da ~/.zshrc / ~/.bashrc.

4. Ripara soltanto l’installazione identificata dalla diagnostica; conserva prima tutto lo stato utente. Un guasto in safe mode o un rapporto doctor inconcludente non dimostrano che i dati utente vadano rimossi. Ferma tutte le sessioni Claude e gli altri processi che scrivono prima di eseguire un backup coerente. Mantieni stesso account Unix, HOME, archivio credenziali del sistema operativo e account Anthropic; non ruotare le chiavi né creare un’identità sostitutiva.

L’esempio seguente è per Linux con GNU tar. Su macOS o Windows usa un backup che conservi ACL, attributi estesi, collegamenti e metadati della piattaforma e verificane il ripristino prima di procedere; non presumere che i flag GNU funzionino lì. L’archivio contiene credenziali e trascrizioni: mantienilo privato e fuori dai repository.

# Run as the same user who owns the Claude state, after stopping writers.
set -eu
umask 077
backup_dir=$(mktemp -d "$HOME/.claude-recovery-XXXXXXXX")
set --
if [ -e "$HOME/.claude" ] || [ -L "$HOME/.claude" ]; then
  set -- "$@" .claude
fi
if [ -e "$HOME/.claude.json" ] || [ -L "$HOME/.claude.json" ]; then
  set -- "$@" .claude.json
fi
[ "$#" -gt 0 ] || exit 1
tar --acls --xattrs --numeric-owner -cpf "$backup_dir/claude-state.tar" -C "$HOME" "$@"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$HOME"
sha256sum "$backup_dir/claude-state.tar" > "$backup_dir/claude-state.sha256"
(cd "$backup_dir" && sha256sum -c claude-state.sha256)
mkdir "$backup_dir/restore-check"
tar --acls --xattrs -xpf "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
printf 'Verified recovery directory: %s\n' "$backup_dir"

Tutti i comandi devono riuscire. L’archivio comprende l’intero albero .claude esistente, incluse sessioni ignorate/non tracciate e stato dei plugin, più .claude.json: non soltanto impostazioni tracciate da Git. Se un percorso è un collegamento simbolico o i dati sono in una posizione configurata separatamente, fermati e includi la destinazione risolta nello stesso backup verificato; archiviare solo il collegamento non salva la destinazione. L’archivio non contiene Portachiavi macOS o altri archivi esterni: conserva quelle identità al loro posto.

Se la diagnostica identifica proprio l’installazione locale legacy come copia in conflitto, sposta soltanto quella nella directory privata di recupero, senza eliminare configurazioni e sessioni:

# Use the verified backup_dir from the previous block.
if [ -d "$HOME/.claude/local" ]; then
  mv "$HOME/.claude/local" "$backup_dir/legacy-local"
fi

Rimuovi un’installazione npm solo se la diagnostica la identifica come conflitto e intendi mantenere quella nativa. Usa poi l’installer nativo documentato senza eliminare .claude o .claude.json:

curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor

Su Windows il comando nativo resta:

irm https://claude.ai/install.ps1 | iex

Ripristina separatamente. Ferma di nuovo i processi che scrivono. Controlla il checksum ed estrai in una directory di recupero vuota come sopra; confronta con esito positivo prima di usare i file. Per ripristinare l’installazione legacy spostata, conferma prima l’assenza di $HOME/.claude/local, poi riporta $backup_dir/legacy-local in quel percorso esatto. Ripristina un file di impostazioni diagnosticato dall’estrazione verificata solo dopo aver conservato l’eventuale sostituto attuale; non sovrascrivere alla cieca l’intero albero. Sessioni, impostazioni MCP e identità originale restano conservate. Uno snapshot Git da solo non copre trascrizioni ignorate/non tracciate, credenziali o metadati del file system.

Cosa NON fare quando Claude Code non funziona?#

Non cambiare le chiavi prima della diagnosi

Nel 90% dei casi, «l'autorizzazione non funziona» è dovuto a ANTHROPIC_API_KEY che intercetta l'abbonamento, a un bug UI di un hook o a un MCP non funzionante. La rotazione delle chiavi non risolverà nulla di tutto questo, ma causerà un'altra ora di interruzione: bisogna revocare la vecchia chiave, emetterne una nuova, aggiornare la CI con la nuova chiave e modificare le variabili in produzione. Esegui prima claude --safe-mode. Funziona? Allora il problema è nelle personalizzazioni; non c'è bisogno di toccare le chiavi.

Non eseguire un ripristino completo prima di safe mode

Safe mode offre un ambiente isolato in 1 secondo. Eliminare .claude può distruggere sessioni, configurazione MCP e altro stato non tracciato. Esegui prima la diagnosi, verifica un backup privato e usa uno spostamento reversibile solo per il livello di installazione o configurazione effettivamente coinvolto.

Non farti prendere dal panico per un errore UI in un hook

Prima di correggere qualsiasi cosa, verifica se l'hook è stato effettivamente eseguito (tramite un log su stderr o una stampa esplicita), invece di affidarti all'indicatore visivo.

Non alzare il codice di uscita di un hook prima di correggerne la logica

Quando il tuo hook bloccante non blocca, viene spontaneo impostare exit 2 e considerare il problema risolto. È una correzione funzionante, ma nasconde un altro problema: se il blocco non ha funzionato per un mese, allora è passato tutto ciò che l'hook avrebbe dovuto impedire. Prima controlla il log git e scopri esattamente cosa è sfuggito. Poi aggiungi il blocco. Altrimenti, chiudere il varco non annulla ciò che è successo prima.

Non modificare il CLAUDE.md di produzione senza la protezione di safe mode

Nel caso descritto: modifichi CLAUDE.md, Claude comincia a comportarsi in modo strano, esegui git diff e vedi che quella sera qualcuno ha aggiunto anche un server MCP e un hook al repository. Dai la colpa alla tua modifica, la annulli e Claude continua a comportarsi in modo strano. Regola: prima di git revert, esegui claude --safe-mode. Se il problema persiste in safe mode, la tua modifica non c'entra; non serve annullarla.

Non credere che «Claude ripari da solo il proprio MCP»

Uno scenario tipico: chiedi a Claude di «aggiungere un certo strumento al server MCP»; Claude riscrive la configurazione funzionante, si rompe tutto e poi Claude passa diversi turni a diagnosticare il danno che ha causato, consumando nel frattempo la quota della sessione. Quando MCP non funziona, recupera manualmente la configurazione; non lasciare che se ne occupi l'agente. Parte del suo arsenale di strumenti funziona anch'essa su MCP e, se MCP è guasto, anche chi diagnostica è compromesso.

Dove andare dopo aver risolto il problema?#

Dopo aver analizzato l'incidente, non riprendere subito il lavoro. Aggiungi prima misure preventive per evitare che si ripeta. Si possono perdere ore su un second brain (la cartella business/ con la struttura del progetto) e su CLAUDE.md, e ripristinarli manualmente è difficile: è un motivo più che valido. Set minimo:

1. ~/.claude/settings.json con permissions.disableBypassPermissionsMode: "disable": un divieto architetturale della modalità bypass, così un --dangerously-skip-permissions avviato per errore semplicemente non funzionerà.
2. Hook per Read(./env*), Bash(git push --force), Write(./node_modules/**): cose che vanno intercettate come una legge, non lasciate alla buona volontà.
3. Configurazione della sandbox per le lunghe esecuzioni autonome (/loop, /schedule).
4. /compact con regole personalizzate su cosa eliminare dal contesto, così Claude non si sovraccarica.

Lo schema completo di protezione a quattro livelli è nella guida «Come configurare Claude Code affinché non danneggi il tuo progetto durante la notte». Una guida tratta la prevenzione prima di avviare /loop; l'altra il ripristino dopo che /loop ha già danneggiato qualcosa. Una coppia logica.

Materiali pratici: documentazione Ailoot.

Altri materiali e strumenti: Ailoot.