Claude Code Hooks: guida pratica in italiano

I Claude Code Hooks sono reazioni automatiche agli eventi della sessione: prima di una chiamata a uno strumento, dopo una modifica, quando arriva una richiesta di permesso o quando termina una risposta. Un hook collega un evento a un controllo concreto. Può avviare un formatter, aggiungere contesto dinamico o restituire una decisione prima dell’esecuzione di un tool. La documentazione distingue cinque tipi di handler: command, http, mcp_tool, prompt e agent. Reference ufficiale dei Hooks.

La scelta utile parte dal problema: quale fatto deve provocare quale azione, con quali dati e quale risultato osservabile? “Ricordati di fare attenzione” è un’istruzione. “Prima di modificare questo percorso verifica una regola” è una possibile automazione. Un hook ben progettato ha un confine leggibile, un modo di provare gli errori e un responsabile della manutenzione. Il nome della funzione conta meno di questi elementi.

Questa guida usa la documentazione verificata il 9 ottobre 2026. Gli esempi originali sono proposte didattiche con dati sintetici, non configurazioni eseguite da Giallo né risultati misurati presso clienti. Chi sta iniziando con lo sviluppo assistito può leggere prima Claude per codice; chi cerca un’interfaccia personalizzata dovrebbe confrontare anche che cosa sono i Mods di Claude.

Come funzionano evento, matcher e handler?

L’evento descrive un momento del ciclo di lavoro. Il matcher seleziona le occorrenze pertinenti. L’handler esegue la reazione. Con PostToolUse, matcher Edit|Write e handler command, il progetto può chiamare uno script dopo gli edit eseguiti con quei tool. Non significa che lo script vedrà ogni cambiamento sul disco: una scrittura attraverso Bash o un’applicazione esterna segue un percorso differente. La reference spiega i campi filtrati per ciascun evento. Lifecycle e matcher.

Conviene descrivere il controllo in una frase prima di scrivere JSON: “Dopo una modifica a un file TypeScript, formatta soltanto quel file e restituisci un messaggio breve se il comando fallisce”. Questa frase contiene già momento, ambito, azione ed esito. Se la frase diventa “controlla tutto, aggiorna tutto e comunica a tutti”, la responsabilità è troppo ampia per un primo hook.

Il matcher non è un linguaggio universale di policy. Nei tool event filtra il nome del tool; in SessionStart filtra il motivo di avvio; in Notification il tipo di notifica. Trattare tutti i matcher come percorsi del filesystem è una causa frequente di configurazioni apparentemente corrette ma inattive.

Quale tipo di hook scegliere?

La reference corrente elenca cinque handler e un insieme di 33 eventi, ma il conteggio serve a orientarsi, non a scegliere una configurazione. La tabella seguente confronta le cinque forme dal punto di vista del lavoro da svolgere. Un handler non è automaticamente compatibile con ogni evento: verifica la sezione del contratto che stai usando. Tipi e campi ufficiali.

Per un formatter presente nel repository, un comando è spesso la scelta più leggibile. Per una policy condivisa fra repository può essere sensato un servizio HTTP. Per capire se una risposta soddisfa una consegna complessa può essere utile una valutazione, ma introdurre un modello dove basta un confronto di stringhe rende il comportamento meno prevedibile.

Dove mettere la configurazione dei Hooks?

Le impostazioni utente vivono in ~/.claude/settings.json; quelle condivise del progetto in .claude/settings.json; quelle locali in .claude/settings.local.json. Le organizzazioni possono applicare managed settings. La precedenza dei valori e l’unione di alcune liste rendono importante conoscere tutte le fonti: una modifica nel file locale non dimostra che un controllo aziendale sia stato rimosso. Settings di Claude Code.

Scegli lo scope in base alla responsabilità. Una notifica desktop dipende dalla macchina e può essere personale. Un formatter che tutti devono usare appartiene al progetto, insieme allo script e alla documentazione dei prerequisiti. Un controllo obbligatorio per l’organizzazione deve essere distribuito attraverso il livello amministrativo appropriato, invece di sperare che ogni sviluppatore copi il medesimo file.

Mantieni fuori dai settings condivisi token, password e percorsi personali. Per una configurazione riutilizzabile serve sapere quali eseguibili sono necessari e dove si trovano. Anche uno script di poche righe può interrompere il workflow se presuppone uno strumento installato soltanto sul computer dell’autore. La registrazione visibile in /hooks aiuta a controllare il risultato del caricamento.

Come fare un primo setup leggibile?

Parti con un comando locale e innocuo. Il seguente blocco è uno smoke test del caricamento: quando arriva una richiesta di permesso, scrive su stdout, che Claude Code cattura. Non aggiunge una notifica visibile nella UI normale; verifica l’output nella modalità verbose. È un esempio di configurazione, non eseguito in questa guida; l’ambiente deve fornire printf attraverso la shell usata da Claude Code. Quickstart e menu Hooks.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "printf 'Claude Code richiede attenzione\\n'"
          }
        ]
      }
    ]
  }
}

In un file esistente va integrato il campo hooks, mantenendo gli altri settings. Non creare due proprietà JSON con lo stesso nome per comodità: il risultato del parser potrebbe nascondere la configurazione che volevi conservare. Apri /hooks, verifica evento e matcher, quindi provoca una richiesta di permesso in un repository di prova con dati sintetici.

L’output del comando visto in verbose dimostra soltanto che l’evento è arrivato a quell’handler. Non dimostra che i controlli sui file funzionino o che il progetto sia completato. Per un avviso desktop serve un effetto nativo, come gli esempi della guida alle notifiche con Claude Code Hooks. Il primo setup serve a separare problemi di registrazione da problemi nello script successivo.

Quando usare PreToolUse per bloccare un’azione?

PreToolUse interviene prima della tool call e può restituire decisioni come allow, ask e deny. È il posto da valutare per una regola preventiva: proteggere un percorso, richiedere una decisione su un comando o rifiutare un’operazione fuori ambito. Nei settings hook, un allow non elimina la valutazione delle permission rules deny e ask. Permessi e hook.

Il punto delicato è la copertura. Intercettare Edit|Write può limitare una forma di modifica, ma non ogni processo capace di scrivere. Per questo una policy va descritta con il suo perimetro: tool osservati, input interpretati, percorsi normalizzati e canali esclusi. “Protegge tutti i segreti” sarebbe una promessa molto più ampia di una regola su due nomi di tool.

La guida PreToolUse per proteggere file e comandi approfondisce questi confini. Se il bisogno riguarda un’anteprima visiva di un comando, Blast Radius affronta il medesimo momento del workflow attraverso un mod: l’interfaccia e la regola di controllo restano responsabilità distinte.

Perché PostToolUse non è un rollback?

PostToolUse arriva dopo una tool call riuscita. Può avviare un formatter o fornire feedback, ma non annulla l’azione appena eseguita. Se un file contiene un errore, quel contenuto è già sul disco. Occorre una correzione successiva o un ripristino consapevole attraverso il controllo di versione. Contratto PostToolUse.

Questo cambia la lettura di un controllo: una risposta che segnala un problema è utile, ma non è una barriera precedente alla scrittura. La sequenza ragionevole può essere modifica, formattazione, test pertinente, lettura del risultato e nuova modifica se necessaria. Non tutte queste attività devono essere lanciate dopo ogni carattere: il costo di avvio e la concorrenza possono rendere il processo più rumoroso.

Per progettare il flusso consulta formatter e test con PostToolUse. Quando serve capire quali edit sono stati tentati, Replay Theater può aiutare a leggere il turno; una visualizzazione del turno non sostituisce il diff del repository né l’esito dei test.

Come scegliere tra esecuzione sincrona e async?

La modalità async dei settings hook riguarda gli handler command. Il lavoro prosegue in background e la sua risposta non può bloccare retroattivamente l’azione che lo ha avviato. Inoltre, i handler che corrispondono allo stesso evento possono essere eseguiti in parallelo. Questi comportamenti impongono attenzione quando un processo modifica i file mentre un altro li verifica. Hook in background.

Un formatter rapido sul file appena scritto può richiedere ordinamento prima del prossimo controllo. Una suite lunga può essere avviata separatamente, purché il risultato indichi quale stato ha verificato e sia arrivato prima della dichiarazione di completamento. Mettere entrambi in due handler e presumere l’ordine scritto nel JSON è una scorciatoia fragile.

La domanda da porre è: “La prossima azione può procedere senza questo risultato?”. Se la risposta è sì, il background può essere appropriato. Se la risposta è no, il controllo deve partecipare a un punto del workflow che attende davvero il risultato. Il nome async non trasforma una verifica incompleta in una verifica positiva.

Come ricevere un avviso senza inviare dati fuori?

Notification permette di selezionare tipi come una richiesta di permesso o un momento di attesa. Un comando del sistema operativo può mostrare un avviso sul computer. Questo è spesso sufficiente per chi lascia lavorare Claude Code mentre passa a un’altra attività. Il testo dell’avviso dovrebbe essere breve, stabile e privo del contenuto del prompt. Guida ufficiale alle notifiche.

Una notifica non dimostra che il progetto sia finito. Avvisa che una condizione osservata richiede attenzione. Distinguere “serve un permesso”, “risposta terminata” e “task validato” evita che un suono venga interpretato come un via libera alla pubblicazione. La differenza è operativa, soprattutto quando il lavoro tocca un gestionale o un sito già usato da clienti.

In notifiche Claude Code su Mac, Windows e Linux trovi un percorso di verifica locale. Il primo controllo è eseguire il comando nativo fuori da Claude Code: se il sistema non mostra l’avviso, modificare il matcher non risolve i permessi dell’applicazione o la modalità concentrazione.

SessionStart deve ricaricare tutta la memoria?

SessionStart può aggiungere contesto quando una sessione inizia o riprende, compresa la ripresa legata alla compaction. È utile per dati dinamici, come il branch corrente o un riferimento allo stato del task. Gli instruction file seguono però regole proprie: non bisogna assumere che la compaction cancelli ogni istruzione persistente e richieda una copia integrale a ogni ripresa. Memoria di Claude Code.

Il risultato migliore è un piccolo orientamento verificabile. “Branch attuale: questo; checklist: quel file; stato letto alle ore indicate” è più utile di una stampa di intere cartelle. Lo script deve anche evitare output contenenti credenziali o dati dei clienti: un hook di contesto può rendere informazioni inutilmente disponibili al modello se raccoglie più del necessario.

La guida SessionStart e compaction spiega come distinguere istruzioni, riepilogo, dati del progetto e ambiente. Per chi desidera osservare l’occupazione del contesto, Token Weather riguarda la visualizzazione: osservare un indicatore non prova un risparmio di costo né una memoria perfetta.

Come evitare loop quando Claude termina una risposta?

Stop riguarda la fine di una risposta. Un hook può chiedere una continuazione, ma deve riconoscere stop_hook_active, che indica una continuazione già provocata dal controllo. La reference documenta anche un limite alle continuazioni consecutive: il limite del prodotto non sostituisce una condizione sensata nel progetto. Evento Stop.

Un criterio verificabile può essere “esiste un esito di test riferito all’ultima modifica”. “Migliora ancora tutto” non ha un termine osservabile. Anche un controllo valido deve gestire il caso in cui mancano login, una dipendenza o un servizio esterno: ripetere la stessa richiesta non crea il prerequisito mancante.

Consulta Stop hook senza loop per confrontare script, prompt e agent. La disponibilità di un agente capace di leggere file non elimina la necessità di limitarne il compito. Chiedere una revisione indipendente è diverso da autorizzare una catena senza fine di agenti che invocano altri agenti.

HTTP e MCP: quando servono controlli condivisi?

Un handler HTTP invia il contesto dell’evento con un POST. Il servizio deve restituire il JSON previsto: uno status 500 o 403 non equivale da solo a deny. La release 2.1.295, dell’8 ottobre 2026, introduce onFailure: "block" per command e HTTP, ma in questa verifica lo schema completo per tutti gli eventi non è stato confermato; va verificato prima di usarlo come garanzia operativa. Release ufficiale.

Un handler mcp_tool è un’altra possibilità: il controllo viene eseguito mediante un tool di un server collegato. È diverso dall’intercettare una normale chiamata MCP di Claude attraverso PreToolUse. Nel primo caso il tool esegue il controllo; nel secondo la chiamata è l’oggetto del controllo.

Le due guide HTTP Hooks e Hooks con MCP descrivono i contratti e i prerequisiti. Per un servizio condiviso conta anche quali dati lasciare sul computer: non inviare l’intero transcript se alla policy bastano nome del tool e identificatore della categoria di operazione.

Quali controlli valgono nei subagent e nei team?

I settings hook si applicano anche alle tool call dei subagent. I hook nel frontmatter di un agente supportato hanno invece durata legata alla sua attività. Esiste un’eccezione importante: gli agenti distribuiti dentro un plugin ignorano il campo frontmatter hooks; i controlli vanno dichiarati al livello del plugin. Componenti plugin.

Un lavoro delegato ha diversi momenti di fine. L’agente può terminare una risposta, un task può essere segnato completato e un compagno di team può diventare inattivo. Non sono sinonimi. La policy va collegata al momento che rappresenta davvero la condizione da verificare, con identificazione dell’agente e della prova prodotta.

In Hooks per subagent e team trovi una matrice di responsabilità. Se il team distribuisce anche personalizzazioni dell’interfaccia, policy e distribuzione dei Mods completa il percorso: approvare un plugin non significa sandboxare automaticamente tutto il codice che esegue.

Due progetti italiani da cui partire

Esempio ipotetico, non testato: una software house di Padova gestisce un portale per prenotazioni. Il team vuole uniformare i file appena modificati senza lanciare ogni volta l’intera suite. Può iniziare con PostToolUse sui tool di edit, un formatter limitato ai percorsi supportati e una verifica finale separata. La prova richiede almeno un file valido, un’estensione esclusa e un fallimento del formatter. Il risultato atteso va annotato prima della prova, senza inventare un miglioramento percentuale.

Esempio ipotetico, non testato: un produttore di componenti di Brescia mantiene uno script per importare listini sintetici in un gestionale di prova. Vuole impedire modifiche accidentali alla cartella di configurazione durante gli esperimenti. Una regola PreToolUse sui tool di scrittura può aiutare, ma il team deve elencare anche shell, copie e altri processi che scrivono. Per dati reali serve un confine di accesso nel sistema, non soltanto una convenzione dell’assistente.

Entrambi i progetti possono partire con un hook solo. Il criterio per aggiungerne un altro è una necessità osservata: errori ripetuti, attese non segnalate o verifica dimenticata. Installare molte automazioni prima di conoscere il flusso rende più difficile capire quale abbia prodotto un risultato o un blocco.

Quali errori rendono un hook poco affidabile?

Gli errori più costosi sono confondere registrazione ed esecuzione, scegliere matcher troppo ampi, stampare dati non necessari, presumere l’ordine dei handler e trattare un errore tecnico come una decisione di policy. Un output JSON valido deve inoltre appartenere all’evento corretto: copiare una risposta PreToolUse dentro Stop non trasferisce automaticamente il suo significato.

Una prova minima prima dell’adozione

Prepara un repository con soli dati sintetici. Prova una chiamata inclusa e una esclusa dal matcher, un esito positivo, un rifiuto previsto e un errore del comando. Registra separatamente il risultato del controllo e l’effetto osservato sul tool. La disponibilità della registrazione nel menu non basta a certificare l’intero percorso.

Per un problema già presente usa debug dei Claude Code Hooks. Il percorso più utile va dal sintomo alla prova: configurazione caricata, evento prodotto, matcher, input, output e comportamento finale. Aggiungere log indiscriminati può esporre dati senza chiarire quale passaggio manca.

Come trasformare il primo hook in un processo mantenibile?

Per ogni controllo conserva scopo, scope, prerequisiti, esempi di input, risultati attesi e responsabile. Una PMI con un solo sviluppatore può farlo in un breve documento del repository. Un team più ampio deve anche decidere chi può aggiornare la regola, come provare una nuova versione e cosa succede se il servizio di controllo non è disponibile.

La consegna non è “abbiamo i Hooks”. È “questa condizione produce questo risultato, abbiamo provato anche i casi negativi e sappiamo dove il controllo non copre il workflow”. Le verifiche finali del software rimangono nella pipeline del progetto, con risultati leggibili e coerenti con la modifica consegnata.

Per impostare questi controlli su un’applicazione interna, il servizio di software su misura può partire dalle operazioni reali e dalle prove richieste. Scegli poi un approfondimento fra protezione preventiva dei file e feedback dopo le modifiche: sono due responsabilità diverse, da progettare e verificare separatamente.