Gli hook di Claude Code spiegati: ogni evento e a cosa serve

01Com'è fatto un hook

La configurazione di un hook ha tre livelli:

1. L'evento hook, ad esempio PreToolUse o Stop.
2. Un gruppo matcher, che filtra quando scatta, ad esempio "solo per il tool Bash".
3. Uno o più handler, cioè ciò che viene effettivamente eseguito.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

Questo esegue uno script di lint dopo che Claude scrive o modifica un file. Per aggiungere un secondo evento, aggiungi una chiave allo stesso livello dentro lo stesso oggetto hooks.

02Dove si trovano gli hook

Gli hook di file diversi si sommano, non si sostituiscono. Digita /hooks in Claude Code per vedere tutti gli hook attivi e da dove arrivano.

In una sessione interattiva, Claude Code non esegue gli hook, nemmeno i tuoi, finché non accetti la finestra di fiducia del workspace per quella cartella.

03Tipi di handler

La maggior parte degli hook è "type": "command", che esegue un comando shell. Ce ne sono altri quattro:

• http: invia il JSON dell'evento in POST a un URL e legge il body della risposta.
• mcp_tool: chiama un tool su un server MCP che hai configurato.
• prompt: fa una domanda singola a un modello Claude e legge una decisione in JSON.
• agent: avvia un subagent che può leggere file prima di decidere (sperimentale).

Gli hook di tipo command girano con tutti i permessi del tuo utente, tramite sh -c su macOS e Linux e Git Bash (o PowerShell) su Windows. Aggiungi "async": true per eseguirne uno in background; in quel caso però non può più prendere decisioni.

04Matcher

Il matcher stabilisce quali occorrenze di un evento eseguono l'hook. Il valore confrontato dipende dall'evento: il nome del tool per gli eventi dei tool, il tipo di notifica per Notification, il modo in cui è partita la sessione per SessionStart e così via.

• "*", "" o l'assenza di matcher corrispondono a tutto.
• Lettere, cifre, _, -, spazi, | e , vengono trattati come nomi esatti. Edit|Write corrisponde a uno qualsiasi dei due tool.
• Tutto il resto è un'espressione regolare JavaScript, quindi mcp__memory__.* corrisponde a tutti i tool di un server MCP.

I matcher distinguono maiuscole e minuscole. Alcuni eventi, tra cui Stop e UserPromptSubmit, ignorano i matcher. Per gli eventi dei tool, un campo if con una regola di permesso come "Bash(git *)" restringe ulteriormente un singolo handler.

05Input: cosa riceve il tuo hook

Ogni hook riceve su stdin un JSON con alcuni campi comuni, tra cui session_id, transcript_path, cwd e hook_event_name, più i campi specifici dell'evento. Un hook PreToolUse per una chiamata Bash, ad esempio, riceve anche tool_name e tool_input.command. Leggilo con jq o con qualsiasi parser JSON:

#!/bin/bash
input=$(cat)
cmd=$(jq -r '.tool_input.command // empty' <<<"$input")
echo "Claude wants to run: $cmd" >> ~/claude-commands.log
exit 0

06Output: exit code e JSON

Un hook può rispondere in due modi.

Exit code. 0 indica successo. 2 è un errore bloccante: sugli eventi che possono bloccare, l'azione si ferma e il tuo stderr diventa la motivazione. Qualsiasi altro codice, compreso il classico 1, è un errore non bloccante: l'azione prosegue e vedi un avviso di errore dell'hook. Se un hook deve far rispettare una regola, esci con 2, non con 1.

JSON su stdout. Per un controllo più preciso, esci con 0 e stampa un singolo oggetto JSON. Alcuni campi funzionano ovunque, come continue: false per fermare del tutto Claude. Altri dipendono dall'evento: Stop usa decision: "block" con un reason, mentre PreToolUse e PermissionRequest mettono la decisione dentro hookSpecificOutput. Non stampare nient'altro su stdout: basta una riga di troppo dal profilo della shell perché Claude Code non riesca a leggere il JSON.

07Tutti gli eventi hook

Anthropic aggiunge eventi di tanto in tanto, quindi consulta il riferimento sugli hook per l'elenco aggiornato e i campi di input di ogni evento.

08Quali eventi contano per le notifiche

Quattro eventi coprono quasi tutto ciò di cui vuoi essere avvisato:

• Stop per "Claude ha finito". Vedi la guida allo Stop hook.
• Notification per "Claude ti sta aspettando", con tipi come permission_prompt e idle_prompt. Vedi la guida al Notification hook.
• PermissionRequest per essere avvisato, o rispondere, nell'istante in cui serve un permesso. Vedi la guida a PermissionRequest.
• PreToolUse sul tool AskUserQuestion, per vedere o rispondere alle domande a scelta multipla di Claude. Vedi come rispondere alle domande dal telefono.

Per una configurazione desktop pronta da incollare, parti da come ricevere una notifica quando Claude Code finisce.

09Dove si inserisce Claude Code Notifier

Claude Code Notifier è costruito interamente su questi hook. Il suo tool da riga di comando gratuito, ccn, funziona su Mac, Windows e Linux. L'installazione aggiunge sette voci di hook a ~/.claude/settings.json, ognuna delle quali esegue ccn hook, e crea un backup una tantum del file. ccn gira per pochi millisecondi a ogni evento e poi termina, quindi non resta nulla in esecuzione.

Da solo mostra notifiche desktop. Con l'app per iPhone o Android abbinata, gli stessi hook riportano indietro le tue risposte: consentire o negare un permesso, rispondere a una domanda o inviare l'istruzione successiva quando Claude si ferma. È indipendente e non è realizzato da Anthropic. Se ti serve solo un log o un passaggio di lint, qualche riga scritta da te è più semplice. Trovi i dettagli nella pagina di ccn.

10FAQ