I Claude Code Hooks sono comandi shell che Claude Code esegue automaticamente in punti precisi del suo ciclo di vita, cosi imponi i tuoi quality gate in modo deterministico piuttosto che sperare che l'agente se ne ricordi. Dove una regola CLAUDE.md e un suggerimento che il modello puo seguire o meno, un hook si attiva sempre: puo far girare il tuo formatter dopo ogni scrittura di file, eseguire i tuoi test prima che l'agente si fermi, o bloccare direttamente un comando pericoloso. Questa guida spiega gli eventi degli hook, come si configurano gli hook, e un setup pratico che puoi adottare oggi stesso.
Parte di: Tutorial Claude Code per principianti
Cos'e davvero un hook
Ogni hook ha tre parti: un evento (il momento del ciclo di vita in cui si attiva), un matcher opzionale (un filtro perche giri solo per certi tool) e un'azione (il comando shell che esegue). Quando un hook si attiva, Claude Code gli passa JSON via standard input che descrive l'evento (ID di sessione, directory di lavoro, il nome del tool e il suo input), e il tuo script decide cosa fare. Il codice di uscita del comando pilota il flusso: exit 0 significa continuare, e un exit diverso da zero (per convenzione 2) blocca l'azione e restituisce il tuo messaggio all'agente perche reagisca.
- Evento: quando l'hook si attiva (per esempio dopo che un tool e girato).
- Matcher: un filtro opzionale, per esempio solo sulle modifiche di file.
- Azione: il comando shell che Claude Code esegue.
Gli eventi del ciclo di vita che puoi agganciare
Gli hook coprono tutto il ciclo di vita dei tool. Quelli che usi di piu sono PreToolUse e PostToolUse (attorno a ogni chiamata di tool), Stop (quando l'agente vuole terminare) e SessionStart (quando una sessione comincia). Per un controllo piu fine, ce ne sono altri.
- PreToolUse: prima che un tool giri, per validare o bloccare l'azione.
- PostToolUse: dopo che un tool e girato, per formattare, lintare o verificare il risultato.
- UserPromptSubmit: quando invii un prompt, per iniettare contesto o mettere in sicurezza l'input.
- Stop e SubagentStop: quando l'agente (o un subagent) vuole fermarsi, per lanciare i test come ultimo gate.
- SessionStart e Notification: setup di sessione e quando l'agente ha bisogno della tua attenzione.
Dove gli hook si configurano
Gli hook vivono nel tuo settings.json Claude Code. Metti i gate non negoziabili a livello di squadra nel file di progetto sotto .claude/settings.json, cosi tutti condividono gli stessi guard rail, e tieni le preferenze personali nei tuoi user settings. Ogni voce associa un evento a un matcher e al comando da eseguire.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "bun run lint --fix" }
]
}
]
}
}Un setup pratico di quality gate
Il setup piu potente e piccolo: formattare e lintare a ogni scrittura, e far girare la tua suite di test come gate Stop, cosi l'agente non puo dichiarare un compito finito con test rossi. Aggiungi un guard PreToolUse se vuoi bloccare i comandi shell distruttivi. Tieni gli script degli hook veloci e idempotenti, perche girano spesso, e in caso di blocco, scrivi un messaggio chiaro sull'errore standard perche l'agente sappia come correggerlo.
Passo dopo passo
Creare il tuo file di settings
Crea .claude/settings.json alla radice del tuo progetto se non esiste. Qui vivono gli hook condivisi a livello di squadra.
Aggiungere un hook PostToolUse per formattare e lintare
Sotto hooks.PostToolUse, aggiungi un matcher "Edit|Write" e un comando che esegue il tuo formatter e il tuo linter, cosi il codice viene ripulito dopo ogni cambiamento dell'agente.
Aggiungere un hook Stop che esegue i tuoi test
Sotto hooks.Stop, aggiungi un comando che esegue la tua suite di test. Exit diverso da zero in caso di fallimento, cosi l'agente non puo terminare con test che falliscono e continua invece a correggerli.
Aggiungere un guard PreToolUse per i comandi rischiosi
Sotto hooks.PreToolUse con un matcher Bash, aggiungi uno script che controlla il comando dal JSON stdin e blocca con exit 2 le operazioni distruttive come il force-push o la cancellazione ricorsiva.
Testare e fare commit
Fai una piccola modifica e conferma che gli hook si attivano come previsto, poi fai commit del file di settings perche tutta la squadra erediti gli stessi guard rail.