Cos’è un hook e come si scrive negli agenti di programmazione?

Perché il file delle regole non basta?

Una regola puoi darla a un agente di programmazione in due modi. Il primo è il file delle regole: in AGENTS.md, CLAUDE.md o GEMINI.md scrivi «chiedimi prima di fare il merge». Il secondo è un hook: trasformi la stessa regola in un piccolo script che l’agente esegue da solo in un momento preciso.

La differenza la spiega nel modo più chiaro la documentazione di Claude Code: «Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.» Cioè, per l’agente il file delle regole è solo un’informazione, e l’agente non sempre ne tiene conto. Se vuoi bloccare un’azione qualunque cosa decida l’agente, usi un hook.

Al 18 ottobre 2026 gli hook ci sono in tutti e cinque gli strumenti di cui parliamo: Claude Code, Codex di OpenAI, Cursor, Gemini CLI di Google e GitHub Copilot (la CLI e l’agente cloud). In tutti la logica è la stessa: l’hook si aggancia a un evento, riceve i dettagli dell’evento in JSON e, se serve, blocca un comando prima che venga eseguito.

Gli esempi vengono dal repository in cui sviluppiamo diffox e che usiamo ogni giorno. Lì usiamo Claude Code; ciò che raccontiamo non è una funzione del prodotto, ma il modo in cui lavora il team.

Dove si definiscono gli hook nei cinque strumenti?

In ogni strumento gli hook si scrivono in un file di impostazioni; la differenza sta soprattutto nel nome del file e dell’evento. Per imporre una regola si usa più spesso l’evento che scatta subito prima che l’agente usi un tool (per esempio esegua un comando o modifichi un file):

Fonte: la documentazione sugli hook di ogni strumento, 18 ottobre 2026. La decisione in JSON si dà con l’output che l’hook scrive a schermo (stdout). Codex legge la stessa configurazione anche in config.toml. In Copilot il file utente vale solo per la CLI; l’agente cloud legge il file del repository dal branch predefinito.

Quando l’evento scatta, il tuo hook riceve i dettagli in JSON: quale tool è stato chiamato e con quale input. In Claude Code l’input che arriva prima di un comando Bash è fatto così:

Gli strumenti sanno leggere anche i file degli altri: Copilot legge anche il file .claude/settings.json del repository, Cursor può caricare gli hook di Claude Code e Gemini CLI definisce la variabile CLAUDE_PROJECT_DIR perché gli script scritti per Claude Code continuino a funzionare. Quindi un hook si può scrivere una volta e usare in più strumenti. Ma i nomi degli eventi e i campi di output sono diversi: prova l’hook in ciascuno strumento.

Il 18 giugno 2026 Google ha smesso di servire Gemini CLI agli utenti gratuiti e agli abbonati Google AI Pro e Ultra, indirizzandoli ad Antigravity CLI; con una chiave API a pagamento o una licenza aziendale puoi continuare a usare Gemini CLI. Secondo l’annuncio di Google, anche Antigravity CLI ha gli hook; abbiamo letto la sua documentazione il 28 ottobre 2026. Gli hook si scrivono in .agents/hooks.json per un progetto e in ~/.gemini/config/hooks.json per l’utente. L’evento che scatta prima che si usi un tool si chiama PreToolUse, come in Claude Code. Per bloccare l’azione, l’hook restituisce decision: "deny" nel JSON. Il timeout predefinito è di 30 secondi; la documentazione non dice che cosa fanno i codici di uscita.

Come fa un hook a bloccare un’azione?

L’hook comunica la sua decisione in due modi: con il codice di uscita o con il JSON che scrive a schermo. In tutti e cinque gli strumenti, se l’hook esce con il codice 2 l’azione si ferma, e la spiegazione che l’hook ha scritto sull’output di errore (stderr) arriva all’agente. Gli strumenti si comportano invece in modo diverso quando l’hook esce con un altro codice di errore o va in timeout:

Fonte: la documentazione sugli hook di ogni strumento, 18 ottobre 2026. «La documentazione non lo dice»: nelle pagine che abbiamo letto quel giorno non abbiamo trovato una frase che descriva questo caso. In Claude Code l’impostazione esiste dalla versione 2.1.295. Su Windows senza Git Bash, un hook di comando PreToolUse in forma shell che fallisce può bloccare l’azione anche senza onFailure.

Parti dalla prima colonna. In Unix, per un errore si usa di solito 1. Claude Code, Cursor e Gemini CLI lo trattano come un errore che non blocca l’azione; Copilot invece, con lo stesso codice, la blocca. Per questo la documentazione di Claude Code ti dice di usare exit 2 negli hook che impongono una regola. Gemini CLI, al contrario, consiglia di uscire con 0 e scrivere JSON anche quando si blocca un’azione di proposito; se l’hook scrive a schermo qualcosa che non è JSON, l’azione viene permessa.

Il problema della seconda colonna è più difficile da notare: se il percorso dell’hook è sbagliato o lo script si pianta, è come se la regola non ci fosse. Dove l’azione deve fermarsi per forza, attiva onFailure in Claude Code e failClosed in Cursor.

L’esempio qui sotto è una versione semplificata, per Claude Code, del controllo sul merge del nostro repository. Prima il file di impostazioni:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/merge-gate.sh"
          }
        ]
      }
    ]
  }
}

Poi lo script:

#!/bin/bash
# L'input arriva in JSON da stdin. Se non si legge, l'azione si ferma.
COMMAND=$(jq -r '.tool_input.command // empty') || {
  echo "Hook: input non leggibile, azione bloccata." >&2
  exit 2
}

case "$COMMAND" in
  *"MERGE_APPROVED=1 gh pr merge"*) exit 0 ;;  # approvazione scritta nel comando
  *"gh pr merge"*)
    echo "Il merge lo decide il proprietario del progetto. Chiedi prima." >&2
    exit 2 ;;                                 # l'azione si ferma
esac
exit 0                                        # nessuna obiezione

Quando lo script esce con 2, Claude Code non esegue il comando e passa all’agente la frase che hai scritto sull’output di errore. La stessa decisione puoi darla anche uscendo con 0 e scrivendo JSON: nel campo permissionDecision va deny (rifiuta), ask (chiedi) o allow (consenti). Gli hook PreToolUse girano prima delle impostazioni dei permessi; una decisione deny vale anche in modalità bypassPermissions, quella che salta tutte le richieste di permesso. Codex non supporta ancora il valore ask: l’hook viene considerato fallito e l’azione prosegue.

Quali hook usiamo nel nostro repository?

Nel file .claude/settings.json del nostro repository ci sono 3 hook. Li abbiamo scritti tutti e tre perché non si ripetesse un errore che ci era già capitato.

Apertura della sessione. Quando una sessione parte, l’hook SessionStart dice su quale branch si è, quanti file non sono stati committati e quali worktree sono aperti, poi dà un verdetto: «puoi lavorare in questa directory» oppure «prima apri un worktree a parte». La regola era già scritta in CLAUDE.md. Ma una sessione l’ha letta, non l’ha applicata alla propria situazione e ha pianificato modifiche in una directory che in quaranta minuti ha cambiato branch tre volte. Una regola che dipende dalla memoria dell’agente non protegge; l’hook fa questa domanda al posto dell’agente.

Controllo sul merge. Nel nostro repository non facciamo il merge di una pull request senza l’approvazione del proprietario del progetto. Ma un agente, quando i test passano, può provare a eseguire gh pr merge come passo successivo. L’hook PreToolUse che scatta prima del tool Bash blocca questo comando con il codice 2 e dice all’agente di chiedere prima l’approvazione. Quando l’approvazione arriva, il comando viene rieseguito con una variabile d’ambiente davanti; così, nel log della sessione, l’approvazione sta proprio accanto al merge. L’hook blocca l’azione anche quando non riesce a leggere l’input: la prima versione, davanti a un comando che non riusciva a leggere, usciva con 0 e lo lasciava passare.

Avviso di cambio branch. Il verdetto dato all’apertura descrive la situazione di quel momento e col tempo può invecchiare: se di due sessioni aperte sullo stesso branch una passa a un branch nuovo, cambia anche il punto in cui lavora l’altra. Il secondo hook PreToolUse scatta prima dei tool che modificano i file e, prima di ogni modifica, confronta branch e commit con quello che era stato detto l’ultima volta alla sessione. Se c’è una differenza, manda all’agente una nota che comincia con questa riga: «drift: this checkout MOVED since the session was last told what it is». Non blocca l’azione; passa la nota con il campo additionalContext ed esce con 0.

Un hook di git è un’altra cosa. Nello stesso repository c’è anche un hook pre-push: impedisce il push diretto sui branch protetti. Non lo esegue l’agente di programmazione ma git; per questo vale per chiunque faccia push da quel clone, agenti compresi, qualunque strumento usino. Tutti e due girano solo sulla tua macchina: con --no-verify il pre-push si può saltare, quindi non sostituisce i controlli lato server.

Che differenza c’è tra hook, skill e file delle regole?

Tutti e tre decidono come si comporta l’agente, ma entrano in gioco in momenti diversi. Ecco il confronto nella documentazione di Claude Code:

Fonte: documentazione di Claude Code, pagina «Extend Claude Code», 18 ottobre 2026.

In breve: se deve essere l’agente a decidere come applicare i passi, usa una skill; se l’operazione va fatta ogni volta allo stesso modo, usa un hook. La checklist per pubblicare una release è una skill; formattare ogni file salvato è un hook. Come dice la stessa pagina, un’istruzione nel file delle regole o in una skill è una richiesta, non una garanzia. Le regole che, una volta violate, non si possono più rimediare (un push sul branch sbagliato, un merge fatto troppo presto) non affidarle solo a un’istruzione.

Gli hook non si definiscono solo nel file di impostazioni: anche skill e subagenti possono averne nella propria definizione. In Claude Code l’hook di un subagente vale solo mentre quel subagente è in esecuzione; l’hook di una skill, invece, dopo che la skill è stata chiamata una volta, continua a girare fino alla fine della sessione. In Copilot l’hook di un agente personalizzato gira solo mentre quell’agente è selezionato.

Non trasformare ogni regola in un hook

Un hook gira ogni volta; e un hook scritto male sbaglia ogni volta. Prima di scriverne uno, controlla questi punti:

• Le informazioni che non cambiano tienile nel file delle regole. La documentazione di Claude Code consiglia CLAUDE.md per le informazioni fisse. Un hook è più adatto a passare lo stato del momento (su quale branch sei, com’è andata l’ultima CI).
• Non lasciare a un hook le decisioni che richiedono un giudizio. A una domanda come «questa modifica ha bisogno di test?» un semplice controllo sul testo non sa rispondere; un passo del genere si scrive in una skill.
• Non bloccare senza motivo. Due dei nostri tre hook danno solo informazioni e non bloccano l’azione. Un hook che ferma il lavoro a torto viene presto disattivato, invece che corretto.
• Un hook che cerca un testo non è una misura di sicurezza. Il nostro controllo sul merge non intercetta un comando di merge scritto dentro una variabile o dentro eval. Ferma l’agente che si dimentica di chiedere, non chi cerca apposta di aggirare la regola. Anche la documentazione di Codex descrive gli hook come «a useful guardrail, not a complete enforcement boundary». Per permessi e divieti rigidi, la documentazione di Claude Code consiglia le regole dei permessi.
• Esamina un hook scritto da altri come faresti con il codice. Gli hook di tipo comando girano con i permessi del tuo utente. Codex non esegue un hook arrivato dal repository finché non lo hai esaminato e approvato; Cursor esegue gli hook di progetto solo nei workspace di cui ti fidi; e Gemini CLI tratta un hook modificato come un hook nuovo e non attendibile.

Gli hook girano sulla tua macchina, prima che l’azione avvenga; non guardano se il codice scritto è corretto. Quello è il lavoro della code review: quando diffox esamina una pull request, legge anche le regole da rispettare nel file delle regole del repository (AGENTS.md, o CLAUDE.md se manca) e le usa come regole della review.