Automatizzare le azioni con hooks

Esegui comandi shell automaticamente quando Claude Code modifica file, completa attività o ha bisogno di input. Formatta il codice, invia notifiche, convalida comandi e applica le regole del progetto.

Gli hooks sono comandi shell definiti dall'utente. Claude Code li esegue in punti specifici del suo ciclo di vita, il che ti dà un controllo deterministico: determinate azioni avvengono sempre piuttosto che affidarsi al modello linguistico per scegliere di eseguirle. Utilizza gli hooks per applicare le regole del progetto, automatizzare attività ripetitive e integrare Claude Code con i tuoi strumenti esistenti.

Per decisioni che richiedono giudizio piuttosto che regole deterministiche, potete anche utilizzare hooks basati su prompt o hooks basati su agenti che utilizzano un modello Claude per valutare le condizioni.

Per altri modi di estendere Claude Code, consultate skills per fornire a Claude istruzioni aggiuntive e comandi eseguibili, subagents per eseguire attività in contesti isolati, e plugins per pacchettizzare estensioni da condividere tra i progetti.

Configurare il vostro primo hook

Per creare un hook, aggiungete un blocco hooks a un file di impostazioni. Questa procedura crea un hook di notifica desktop, in modo da ricevere un avviso ogni volta che Claude sta aspettando il vostro input invece di guardare il terminale.

{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}

{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
}
],
"Notification": [
{
"matcher": "",
"hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
}
]
}
}

Cosa potete automatizzare

Gli hooks vi permettono di eseguire codice in punti chiave del ciclo di vita di Claude Code: formattare file dopo le modifiche, bloccare comandi prima che si eseguano, inviare notifiche quando Claude ha bisogno di input, iniettare contesto all'inizio della sessione, e altro ancora. Per l'elenco completo degli eventi hook, consultate il riferimento Hooks.

Ogni esempio include un blocco di configurazione pronto all'uso che aggiungete a un file di impostazioni.

Per un esempio di produzione di hooks che eseguono una revisione di un modello separato e reinseriscono i risultati nella sessione, consultate come il plugin security-guidance si integra con Claude Code.

Ricevere una notifica quando Claude ha bisogno di input

Ricevete una notifica desktop ogni volta che Claude finisce di lavorare e ha bisogno del vostro input, in modo da poter passare ad altri compiti senza controllare il terminale.

Questo hook utilizza l'evento Notification, che Claude Code attiva quando Claude è in attesa di input o di un permesso. Consulta quando si attiva ogni tipo di notifica per le tempistiche esatte.

Ogni scheda qui sotto utilizza il comando di notifica nativo della piattaforma. Aggiungi questo a ~/.claude/settings.json:

{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}

osascript -e 'display notification "test"'

{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
}
]
}
]
}
}

notify-send 'Claude Code' 'test'

{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
}
]
}
]
}
}

Il matcher vuoto si attiva su tutti i tipi di notifica. Per attivarsi solo su eventi specifici, impostatelo a uno di questi valori:

Claude Code cronometra permission_prompt diversamente in un terminale e in Claude Desktop, l'estensione VS Code e altri host che rispondono alle richieste di autorizzazione attraverso l'Agent SDK. Consultate quando ogni tipo di notifica si attiva per entrambi i timing.

I matcher quota_auto_resume_fired, quota_auto_resume_stale e quota_auto_resume_disabled richiedono Claude Code v2.1.234 o successivo.

Nelle sessioni di terminale, permission_prompt per una richiesta di rete di un comando sandboxed richiede Claude Code v2.1.246 o successivo.

agent_needs_input per una domanda di configurazione del terminale di un compagno di squadra richiede Claude Code v2.1.248 o successivo.

Digita /hooks nel prompt di Claude Code e verifica che l'hook compaia sotto Notification.

Formattare automaticamente il codice dopo le modifiche

Eseguite automaticamente Prettier su ogni file che Claude modifica, in modo che la formattazione rimanga coerente senza intervento manuale.

Questo hook utilizza l'evento PostToolUse con un matcher Edit|Write, quindi si esegue solo dopo gli strumenti di modifica dei file. Il comando estrae il percorso del file modificato con jq e lo passa a Prettier. Aggiungete questo a .claude/settings.json nella radice del vostro progetto:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Per testare l'hook, chiedete a Claude di aggiungere una riga con stringhe tra virgolette singole a un file JavaScript, quindi aprite il file: con le impostazioni predefinite di Prettier, l'hook le riscrive in virgolette doppie.

Quando l'hook ha successo, Claude Code non mostra nulla nella conversazione. Per confermare che l'hook è stato eseguito, controllate che il file modificato sia riformattato, o consultate Tecniche di debug.

Per riformattare un file specifico comunque cambi, incluso quando un comando Bash lo riscrive, utilizzate un hook FileChanged invece.

Bloccare le modifiche ai file protetti

Impedite a Claude di modificare file sensibili come .env, package-lock.json, o qualsiasi cosa in .git/. Claude riceve un feedback che spiega perché la modifica è stata bloccata, in modo da poter adattare il suo approccio.

Questo esempio utilizza un file di script separato che l'hook chiama. Lo script controlla il percorso del file di destinazione rispetto a un elenco di modelli protetti ed esce con il codice 2 per bloccare la modifica.

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Normalize Windows backslash separators so the patterns below match
FILE_PATH="${FILE_PATH//\\//}"

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
if [[ "$FILE_PATH" == *"$pattern"* ]]; then
echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
exit 2
fi
done

exit 0

chmod +x .claude/hooks/protect-files.sh

{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
}
]
}
]
}
}

Reiniettare il contesto dopo la compattazione

Quando la finestra di contesto di Claude si riempie, la compattazione riassume la conversazione per liberare spazio. Questo può perdere dettagli importanti. Utilizzate un hook SessionStart con un matcher compact per reiniettare il contesto critico dopo ogni compattazione.

Claude Code aggiunge il testo semplice che il vostro comando scrive su stdout al contesto di Claude. Questo esempio ricorda a Claude le convenzioni del progetto e il lavoro recente. Aggiungete questo a .claude/settings.json nella radice del vostro progetto:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

Potete sostituire l'echo con qualsiasi comando che produce output dinamico, come git log --oneline -5 per mostrare i commit recenti. Per iniettare contesto all'inizio di ogni sessione, considerate di utilizzare CLAUDE.md invece. Per le variabili di ambiente, consultate CLAUDE_ENV_FILE nel riferimento.

Controllare le modifiche di configurazione

Tracciate quando i file di impostazioni o skills cambiano durante una sessione. L'evento ConfigChange si attiva quando un processo esterno o un editor modifica un file di configurazione, in modo da poter registrare le modifiche per la conformità o bloccare le modifiche non autorizzate.

Questo esempio aggiunge ogni modifica a un registro di controllo. Aggiungete questo a ~/.claude/settings.json:

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

Il matcher filtra per tipo di configurazione: user_settings, project_settings, local_settings, policy_settings, o skills. Per bloccare una modifica dall'avere effetto, uscite con il codice 2 o restituite {"decision": "block"}. Consultate il riferimento ConfigChange per lo schema di input completo.

Per confermare che l'hook registra le modifiche, modificate un file di impostazioni in un altro editor mentre una sessione è in esecuzione, quindi aprite ~/claude-config-audit.log: l'hook aggiunge una riga JSON per modifica con il timestamp, la fonte e il percorso del file.

Ricaricare l'ambiente quando la directory o i file cambiano

Alcuni progetti impostano variabili di ambiente diverse a seconda di quale directory siete. Strumenti come direnv lo fanno automaticamente nella vostra shell, ma lo strumento Bash di Claude non raccoglie quei cambiamenti da solo.

L'accoppiamento di un hook SessionStart con un hook CwdChanged risolve questo. SessionStart carica le variabili per la directory in cui avviate, e CwdChanged le ricarica ogni volta che Claude cambia directory. Entrambi scrivono su CLAUDE_ENV_FILE, che Claude Code esegue come preambolo di script prima di ogni comando Bash. Aggiungete questo a ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

Eseguite direnv allow una volta in ogni directory che ha un .envrc in modo che direnv sia autorizzato a caricarlo. Se utilizzate devbox o nix invece di direnv, lo stesso modello funziona con devbox shellenv o devbox global shellenv al posto di direnv export bash.

Per reagire a file specifici invece di ogni cambio di directory, utilizzate FileChanged con un matcher che elenca i nomi dei file da guardare, separati da |. Quando costruite l'elenco di osservazione, Claude Code divide questo valore in nomi di file letterali piuttosto che valutarlo come regex. Consultate FileChanged per come lo stesso valore filtra anche quali gruppi di hook si eseguono quando un file cambia. Questo esempio guarda .envrc e .env nella directory di lavoro:

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

Consultate le voci di riferimento CwdChanged e FileChanged per gli schemi di input, l'output watchPaths, e i dettagli di CLAUDE_ENV_FILE.

Approvare automaticamente specifici prompt di autorizzazione

Saltate la finestra di dialogo di approvazione per le chiamate di strumenti che consentite sempre. Questo esempio approva automaticamente ExitPlanMode, lo strumento che Claude chiama quando finisce di presentare un piano e chiede di procedere, in modo da non essere richiesto ogni volta che un piano è pronto.

A differenza degli esempi di codice di uscita sopra, l'approvazione automatica richiede che il vostro hook scriva una decisione JSON su stdout. Claude Code esegue gli hook PermissionRequest quando sta per chiedervi l'autorizzazione, e se il vostro hook restituisce "behavior": "allow", Claude Code risponde alla richiesta per vostro conto.

Il matcher limita l'hook a ExitPlanMode solo, in modo che nessun altro prompt sia interessato. Aggiungete questo a ~/.claude/settings.json:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

Quando l'hook approva, Claude Code esce dalla modalità piano e ripristina qualsiasi modalità di autorizzazione fosse attiva prima di entrare in modalità piano. La trascrizione mostra "Allowed by PermissionRequest hook" dove la finestra di dialogo sarebbe apparsa. Il percorso dell'hook mantiene sempre la conversazione corrente: non può cancellare il contesto e avviare una sessione di implementazione fresca come la finestra di dialogo può.

Per impostare una modalità di autorizzazione specifica invece, l'output del vostro hook può includere un array updatedPermissions con una voce setMode. Il valore mode è qualsiasi modalità di autorizzazione come default, acceptEdits, o bypassPermissions, e destination: "session" la applica solo per la sessione corrente.

Per passare la sessione a acceptEdits, il vostro hook scrive questo JSON su stdout:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        { "type": "setMode", "mode": "acceptEdits", "destination": "session" }
      ]
    }
  }
}

Mantenete il matcher il più ristretto possibile. Corrispondere a .* o lasciare il matcher vuoto approverebbe automaticamente ogni prompt di autorizzazione, incluse le scritture di file e i comandi shell. Consultate il riferimento PermissionRequest per l'insieme completo di campi di decisione.

Come funzionano gli hooks

Claude Code attiva eventi hook in punti specifici del suo ciclo di vita. Quando un evento si attiva, Claude Code esegue tutti gli hooks corrispondenti in parallelo; consultate Campi del gestore hook per come vengono trattati i gestori duplicati. La tabella sottostante mostra ogni evento e quando si attiva:

Ogni hook ha un type che determina come si esegue. La maggior parte degli hooks utilizza "type": "command", che esegue un comando shell. Sono disponibili altri quattro tipi:

• "type": "http": POST dei dati dell'evento a un URL. Consultate HTTP hooks.
• "type": "mcp_tool": chiama uno strumento su un server MCP già configurato. Consultate MCP tool hooks.
• "type": "prompt": valutazione LLM a turno singolo. Consultate Prompt-based hooks.
• "type": "agent": verifica multi-turno con accesso agli strumenti. Gli agent hooks sono sperimentali e potrebbero cambiare. Consultate Agent-based hooks.

Combinare i risultati da più hooks

Quando più hooks corrispondono allo stesso evento, il comando di ogni hook si esegue fino al completamento prima che Claude Code unisca i risultati. Un hook che restituisce deny non impedisce ai sibling hooks di eseguirsi. Non affidatevi al deny di un hook per sopprimere gli effetti collaterali in un altro hook.

Dopo che tutti gli hooks corrispondenti terminano, Claude Code combina i loro output. Per le decisioni di autorizzazione PreToolUse, la risposta più restrittiva vince, nell'ordine deny, defer, ask, allow. Il testo da additionalContext viene mantenuto da ogni hook e passato a Claude insieme.

L'esempio sottostante registra due hooks PreToolUse su Bash. Il primo aggiunge ogni comando a un file di log e esce con 0. Il secondo esegue uno script che esce con 2 per negare quando il comando contiene rm -rf:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

Quando Claude tenta di eseguire rm -rf /tmp/build, entrambi gli hooks si eseguono in parallelo. L'hook di logging scrive il comando a ~/.claude/bash.log e esce con 0, il che non riporta alcuna decisione. L'hook di guardrail esce con 2, il che nega la chiamata dello strumento. Il deny vince, quindi Claude Code blocca il comando e mostra a Claude lo stderr del guardrail. La voce di log viene comunque scritta perché l'hook di logging si è già eseguito.

Leggere l'input e restituire l'output

Gli hooks comunicano con Claude Code attraverso stdin, stdout, stderr e codici di uscita. Quando un evento si attiva, Claude Code passa i dati specifici dell'evento come JSON allo stdin del vostro script. Il vostro script legge quei dati, fa il suo lavoro, e dice a Claude Code cosa fare dopo tramite il codice di uscita.

Input dell'hook

Ogni evento include campi comuni come session_id, un ID univoco per la sessione, e cwd, la directory di lavoro quando l'evento si è attivato, ma ogni tipo di evento aggiunge dati diversi. Quando Claude esegue un comando Bash, un hook PreToolUse riceve questi campi su stdin:

• hook_event_name: l'evento che ha attivato l'hook
• tool_name: lo strumento che Claude sta per utilizzare
• tool_input: gli argomenti che Claude ha passato allo strumento. Per Bash, il suo campo command contiene il comando shell.

Ad esempio, l'input dell'hook per un comando npm test assomiglia a questo:

{
  "session_id": "abc123",
  "cwd": "/Users/sarah/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

Il vostro script può analizzare quel JSON e agire su qualsiasi di quei campi. Gli hooks UserPromptSubmit ricevono il testo prompt invece, gli hook SessionStart ricevono una source di startup, resume, clear, compact, o fork, e così via. Consultate Campi di input comuni nel riferimento per i campi condivisi, e la sezione di ogni evento per gli schemi specifici dell'evento.

Output dell'hook

Il vostro script dice a Claude Code cosa fare dopo scrivendo su stdout o stderr e uscendo con un codice specifico. Il seguente hook PreToolUse blocca un comando:

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr becomes Claude's feedback
  exit 2 # exit 2 = block the action
fi

exit 0  # exit 0 = no decision; the normal permission flow applies

Il codice di uscita determina cosa succede dopo:

• Exit 0: il vostro hook non riporta obiezioni attraverso il suo codice di uscita.
  • Per un hook PreToolUse questo non approva la chiamata dello strumento: il normale flusso di autorizzazione si applica ancora.
  • Per gli hook UserPromptSubmit, UserPromptExpansion, SessionStart e PostModelSwitch, Claude Code aggiunge stdout che tratta come testo semplice al contesto di Claude.
• Exit 2: Claude Code blocca l'azione. Scrivete un motivo su stderr. Dove finisce dipende dall'evento: alcuni eventi lo alimentano a Claude come feedback in modo che possa adattarsi, altri lo mostrano all'utente, e alcuni, come ConfigChange e Elicitation, non mostrano alcun messaggio. Alcuni eventi non possono essere bloccati: per SessionStart e altri, exit 2 mostra stderr all'utente e l'esecuzione continua. Consultate exit code 2 behavior per evento per l'elenco completo.
• Qualsiasi altro codice di uscita: per la maggior parte degli eventi, il risultato dipende da quello che il vostro hook ha stampato su stdout:
  • Un oggetto analizzato che passa la validazione dello schema: Claude Code ignora il codice di uscita, il JSON da solo decide il risultato, e l'hook non viene segnalato come errore. Le eccezioni per evento, come WorktreeCreate che fallisce su qualsiasi uscita diversa da zero, sono elencate nella sezione Exit code output del riferimento.
  • Un oggetto analizzato che fallisce la validazione dello schema, o stdout che Claude Code tenta di analizzare come JSON ma che non è JSON valido: un errore non bloccante; l'avviso contiene il messaggio di validazione o analisi.
  • Stdout che Claude Code tratta come testo semplice, o stdout vuoto: l'azione procede come errore non bloccante. La trascrizione mostra un avviso <hook name> hook error, quindi la prima riga di stderr con prefisso Failed with non-blocking status code:. Per catturare lo stderr completo, abilitate il debug logging con claude --debug o eseguendo /debug durante la sessione.

Output JSON strutturato

I codici di uscita vi permettono solo di bloccare o stare in silenzio. Per un controllo maggiore, uscite con 0 e stampate un oggetto JSON su stdout invece.

Ad esempio, un hook PreToolUse può negare una chiamata di strumento e dire a Claude perché, o escalarlo all'utente per l'approvazione:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

Con "deny", Claude Code annulla la chiamata dello strumento e alimenta permissionDecisionReason di nuovo a Claude.

Su PreToolUse, Claude Code gestisce ogni valore permissionDecision come segue:

• "allow": salta il prompt di autorizzazione interattivo. Le regole di negazione e richiesta, incluse le liste di negazione gestite dall'azienda, si applicano ancora, così come i prompt per gli strumenti MCP contrassegnati requiresUserInteraction e per gli strumenti connettore che la vostra organizzazione ha impostato su ask nelle sessioni dove quella impostazione raggiunge Claude Code
• "deny": annulla la chiamata dello strumento e invia il motivo a Claude
• "ask": mostra il prompt di autorizzazione all'utente come al solito

Un quarto valore, "defer", è disponibile in modalità non interattiva con il flag -p. Esce dal processo con la chiamata dello strumento preservata in modo che un wrapper SDK Agent possa raccogliere input e riprendere. Consultate Rinviare una chiamata di strumento per dopo nel riferimento.

Un hook PreModelSwitch restituisce lo stesso campo permissionDecision: "allow" lascia procedere un cambio di modello, e "deny" lo annulla. "ask" vi chiede di confermare il cambio quando eseguite /model in una sessione interattiva; in tutti gli altri casi, Claude Code tratta "ask" come un rifiuto. Consultate PreModelSwitch decision control.

Altri eventi utilizzano modelli di decisione diversi. Ad esempio, gli hook PostToolUse e Stop utilizzano un campo decision: "block" di livello superiore, mentre PermissionRequest utilizza hookSpecificOutput.decision.behavior. Consultate la tabella di riepilogo nel riferimento per una suddivisione completa per evento.

Per gli hook UserPromptSubmit, utilizzate hookSpecificOutput.additionalContext invece per iniettare testo nel contesto di Claude. Annidare additionalContext dentro hookSpecificOutput; se lo posizionate al livello superiore del JSON, Claude Code lo ignora silenziosamente. Ad esempio, questo output aggiunge lo stato del ramo corrente a ogni prompt:

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Current branch: release-42. Deploy freeze until Friday."
  }
}

Consultate UserPromptSubmit decision control per la forma di output completa, incluso il blocco dei prompt e l'impostazione del titolo della sessione.

Gli hooks con type: "prompt" gestiscono l'output diversamente: consultate Prompt-based hooks.

Filtrare gli hooks con i matcher

Senza un matcher, un hook si attiva su ogni occorrenza del suo evento. I matcher vi permettono di restringerlo. Ad esempio, se volete eseguire un formattatore solo dopo le modifiche ai file, non dopo ogni chiamata di strumento, aggiungete un matcher al vostro hook PostToolUse:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

Il matcher "Edit|Write" si attiva solo quando Claude utilizza lo strumento Edit o Write, non quando utilizza Bash, Read, o qualsiasi altro strumento. Una virgola separa le alternative allo stesso modo, quindi "Edit, Write" è equivalente. Consultate Matcher patterns per come i nomi semplici e le espressioni regolari vengono valutati.

Ogni tipo di evento corrisponde a un campo specifico:

Le schede sottostanti mostrano alcuni altri matcher su diversi tipi di evento.

{
"hooks": {
"PostToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
}
]
}
]
}
}

{
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__github__.*",
"hooks": [
{
"type": "command",
"command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
}
]
}
]
}
}

{
"hooks": {
"SessionEnd": [
{
"matcher": "clear",
"hooks": [
{
"type": "command",
"command": "rm -f /tmp/claude-scratch-*.txt"
}
]
}
]
}
}

Filtrare per nome dello strumento e argomenti con il campo `if`

Il campo if utilizza la permission rule syntax per filtrare gli hooks per nome dello strumento e argomenti insieme, in modo che il processo dell'hook si generi solo quando la chiamata dello strumento corrisponde. Questo va oltre il matcher, che filtra a livello di gruppo per nome dello strumento solo.

Ad esempio, questa configurazione esegue un hook solo quando Claude utilizza comandi git piuttosto che tutti i comandi Bash:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

Se il vostro hook comando si esegue dipende dalla forma del vostro modello if e dal comando Bash che Claude sta invocando:

Quando Claude Code non può determinare quali comandi l'input Bash esegue, esegue il vostro hook indipendentemente dal modello. La tabella di corrispondenza Bash copre le forme di comando che Claude Code può e non può restringere per sottocomando. Poiché il filtro è best-effort, utilizzate il sistema di autorizzazione piuttosto che un hook per applicare un hard allow o deny.

Il campo if accetta gli stessi modelli delle regole di autorizzazione: "Bash(git *)", "Edit(*.ts)", e così via. Per corrispondere a più nomi di strumenti, utilizzate handler separati ognuno con il suo valore if, o corrispondere a livello di matcher dove l'alternazione con pipe è supportata.

if funziona solo su eventi di strumenti: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest e PermissionDenied. Aggiungerlo a qualsiasi altro evento impedisce all'hook di eseguirsi.

Configurare la posizione dell'hook

Dove aggiungete un hook determina il suo ambito:

Eseguite /hooks in Claude Code per sfogliare tutti gli hooks configurati raggruppati per evento.

Per disabilitare gli hooks, impostate "disableAllHooks": true nel vostro file di impostazioni. Claude Code legge il valore rimasto dopo che la precedenza delle impostazioni si applica, in modo che il file di impostazioni di un progetto possa sovrascrivere il vostro. Gli hooks configurati nelle impostazioni gestite si eseguono comunque a meno che disableAllHooks non sia impostato anche lì. Per la portata completa di ogni livello, consultate disableAllHooks.

Se modificate i file di impostazioni direttamente mentre Claude Code è in esecuzione, il file watcher normalmente raccoglie i cambiamenti degli hook automaticamente.

Hooks basati su prompt

Per decisioni che richiedono giudizio piuttosto che regole deterministiche, utilizzate gli hook type: "prompt". Invece di eseguire un comando shell, Claude Code invia il vostro prompt e i dati di input dell'hook a un modello Claude per prendere la decisione. Potete specificare un modello diverso con il campo model se avete bisogno di più capacità.

L'unico lavoro del modello è restituire la sua decisione come JSON:

• "ok": true: l'azione procede
• "ok": false: ciò che accade dipende dall'evento:
  • Stop e SubagentStop: il reason viene alimentato di nuovo a Claude in modo che continui a lavorare, a meno che la risposta non imposti anche "impossible": true per contrassegnare la condizione come una che non può mai essere soddisfatta, nel qual caso Claude Code consente lo stop e il turno termina
  • PreToolUse: la chiamata dello strumento viene negata; per impostazione predefinita il turno termina e il reason di negazione appare nella chat come una riga di avviso. Impostate continueOnBlock: true sull'hook per restituire invece il reason a Claude come errore dello strumento, in modo che possa adattarsi e continuare. Prima della v2.1.210, il reason di negazione veniva restituito a Claude come errore dello strumento e il turno continuava
  • PostToolUse: per impostazione predefinita il turno termina e il reason appare nella chat come una riga di avviso. Impostate continueOnBlock: true per alimentare il reason di nuovo a Claude e continuare il turno invece
  • PostToolBatch, UserPromptSubmit e UserPromptExpansion: il turno termina e il reason appare nella chat come una riga di avviso

Questo esempio utilizza un hook Stop per chiedere al modello se tutti i compiti richiesti sono completi. Se il modello restituisce "ok": false perché la condizione non è ancora soddisfatta, Claude continua a lavorare e utilizza il reason come sua prossima istruzione:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

Per le opzioni di configurazione complete, consultate Hooks basati su prompt nel riferimento.

Hooks basati su agenti

Quando la verifica richiede l'ispezione di file o l'esecuzione di comandi, utilizzate gli hook type: "agent". A differenza degli hook di prompt che effettuano una singola chiamata LLM, gli hook di agenti generano un subagent che può leggere file, cercare codice e utilizzare altri strumenti per verificare le condizioni prima di restituire una decisione.

Gli hook di agenti utilizzano il formato di risposta "ok" / "reason" con un timeout predefinito più lungo di 60 secondi e fino a 50 turni di utilizzo dello strumento. Non supportano il campo impossible degli hook di prompt. Su ok: false, Claude Code gestisce un agent hook nello stesso modo in cui gestisce un hook di prompt con continueOnBlock: true sullo stesso evento, quindi su PreToolUse e PostToolUse il turno continua; gli agent hook non hanno un campo continueOnBlock. Consultate la configurazione degli agent hook per i campi, incluso il placeholder $ARGUMENTS che Claude Code sostituisce con l'input JSON dell'hook.

Questo esempio verifica che i test passino prima di consentire a Claude di fermarsi:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Utilizzate gli hook di prompt quando i dati di input dell'hook da soli sono sufficienti per prendere una decisione. Utilizzate gli hook di agenti quando avete bisogno di verificare qualcosa rispetto allo stato effettivo della base di codice.

Per le opzioni di configurazione complete, consultate Hooks basati su agenti nel riferimento.

HTTP hooks

Utilizzate gli hook type: "http" per POST dei dati dell'evento a un endpoint HTTP invece di eseguire un comando shell. L'endpoint riceve lo stesso JSON che un hook di comando riceverebbe su stdin, e restituisce i risultati attraverso il corpo della risposta HTTP utilizzando lo stesso formato JSON.

Gli HTTP hooks sono utili quando volete che un server web, una funzione cloud o un servizio esterno gestisca la logica dell'hook: ad esempio, un servizio di controllo condiviso che registra gli eventi di utilizzo dello strumento in un team.

Questo esempio pubblica ogni utilizzo dello strumento a un servizio di registrazione locale:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

L'endpoint dovrebbe restituire un corpo di risposta JSON utilizzando lo stesso formato di output degli hook di comando. Per bloccare una chiamata di strumento, restituite una risposta 2xx con i campi hookSpecificOutput appropriati. I codici di stato HTTP da soli non possono bloccare le azioni.

I valori dell'intestazione supportano l'interpolazione delle variabili di ambiente utilizzando la sintassi $VAR_NAME o ${VAR_NAME}. Solo le variabili elencate nell'array allowedEnvVars vengono risolte; tutti gli altri riferimenti $VAR rimangono vuoti.

Per le opzioni di configurazione complete e la gestione delle risposte, consultate HTTP hooks nel riferimento.

Limitazioni e risoluzione dei problemi

Limitazioni

Tieni a mente questi vincoli quando progetti gli hook:

• Gli hook di tipo command comunicano solo tramite stdout, stderr e codici di uscita. Non possono attivare comandi / o chiamate agli strumenti. Il testo restituito tramite additionalContext viene inserito come promemoria di sistema che Claude legge come testo semplice. Gli hook HTTP comunicano invece tramite il corpo della risposta.
• I timeout degli hook variano in base al tipo. Puoi sovrascriverli per ciascun hook con il campo timeout in secondi.
  • command, http, mcp_tool: 10 minuti. Claude Code abbassa questo valore predefinito a 30 secondi per gli hook UserPromptSubmit, PreModelSwitch e PostModelSwitch, e a 10 secondi per MessageDisplay.
  • prompt: 30 secondi.
  • agent: 60 secondi.
  • Gli hook SessionEnd di qualsiasi tipo condividono un budget di 1,5 secondi. Se le tue impostazioni definiscono un timeout per hook più lungo, Claude Code aumenta il budget di conseguenza, fino a 60 secondi.
• Gli hook PostToolUse non possono annullare le azioni, poiché lo strumento è già stato eseguito.
• Gli hook PermissionRequest si attivano quando Claude Code sta per chiederti un permesso, oppure quando altrimenti negherebbe automaticamente una chiamata che non può mostrare una richiesta di permesso. In modalità non interattiva con il flag -p, vengono comunque eseguiti al di fuori della modalità dontAsk, e una chiamata su cui nessun hook decide e a cui nient'altro può rispondere viene negata.
• Gli hook Stop si attivano ogni volta che Claude termina di rispondere, non solo al completamento di un'attività. Non si attivano in caso di interruzioni da parte dell'utente. Gli errori API attivano invece StopFailure.
• Quando più hook PreToolUse restituiscono updatedInput per riscrivere gli argomenti di uno strumento, ha effetto l'ultimo che termina. Poiché gli hook vengono eseguiti in parallelo, l'ordine non è deterministico. Evita di avere più di un hook che modifica l'input dello stesso strumento.

Hook e modalità di permesso

Gli hook PreToolUse si attivano prima di qualsiasi controllo della modalità di permesso, in ogni modalità di permesso, incluso dontAsk. Un hook che restituisce permissionDecision: "deny" blocca lo strumento anche in modalità bypassPermissions o con --dangerously-skip-permissions. Questo ti consente di applicare criteri che gli utenti non possono aggirare cambiando la propria modalità di permesso.

Il contrario non vale: un hook che restituisce "allow" non aggira le regole di negazione delle impostazioni, e non può sopprimere la richiesta di permesso per gli strumenti MCP contrassegnati con requiresUserInteraction o per gli strumenti dei connettori che la tua organizzazione ha impostato su ask nelle sessioni in cui tale impostazione raggiunge Claude Code. Gli hook nei file di impostazioni e nel file hooks/hooks.json di un plugin possono rendere più rigide le restrizioni, ma non allentarle oltre quanto consentito dalle regole di permesso.

Un mod che installi e che gestisce tool.check può approvare una chiamata bloccata dal tuo hook PreToolUse, a meno che l'hook non si trovi nelle impostazioni gestite. Estendere i permessi con gli hook elenca quali regole prevalgono su un mod.

L'hook non si attiva

L'hook è configurato ma non viene mai eseguito.

• Esegui /hooks e verifica che l'hook compaia sotto l'evento corretto
• Controlla che il pattern del matcher corrisponda esattamente al nome dello strumento. I matcher distinguono tra maiuscole e minuscole
• Verifica di attivare il tipo di evento corretto: PreToolUse si attiva prima dell'esecuzione dello strumento, PostToolUse dopo. Un hook PermissionRequest si attiva quando Claude Code sta per chiederti un permesso; consulta le limitazioni per i casi non interattivi

Errore dell'hook nell'output

Nella trascrizione vedi un messaggio come "PreToolUse hook error: ...".

• Il tuo script è terminato inaspettatamente con un codice diverso da zero. Testalo manualmente passandogli un JSON di esempio tramite pipe:

  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Check the exit code
  

• Se vedi "command not found", usa percorsi assoluti o ${CLAUDE_PROJECT_DIR} per fare riferimento agli script. Per evitare del tutto il quoting della shell, aggiungi "args": [] per passare alla forma exec, che avvia lo script direttamente senza una shell

• Se vedi "jq: command not found", installa jq oppure usa Python/Node.js per il parsing del JSON

• Se l'avviso mostra un messaggio di convalida JSON, lo stdout del tuo hook è stato interpretato come JSON ma non ha superato la convalida dello schema. Se mostra un messaggio di parsing JSON, lo stdout sembrava un oggetto JSON ma non era JSON valido. Entrambi i casi si verificano anche con uscita 0.

  Per correggere un errore di parsing, crea il payload con un encoder JSON come jq invece di concatenare stringhe, in modo che virgolette e barre rovesciate all'interno dei valori vengano sottoposte a escape. La sezione Output del codice di uscita del riferimento descrive le combinazioni di codice di uscita e JSON

• Se lo script non viene eseguito affatto, rendilo eseguibile: chmod +x ./my-hook.sh

`/hooks` non mostra hook configurati

Hai modificato un file di impostazioni ma gli hook non compaiono nel menu.

• Le modifiche ai file vengono normalmente rilevate in automatico. Se non sono comparse dopo qualche secondo, il file watcher potrebbe non aver rilevato la modifica: riavvia la sessione per forzare il ricaricamento.
• Verifica che il tuo JSON sia valido: virgole finali e commenti non sono consentiti
• Conferma che il file di impostazioni si trovi nella posizione corretta: .claude/settings.json per gli hook di progetto, ~/.claude/settings.json per gli hook globali
• Se il menu mostra Only hooks from managed settings run here, la tua organizzazione ha impostato allowManagedHooksOnly. Gli hook nei tuoi file di impostazioni utente, di progetto e locali non vengono eseguiti e non sono elencati

L'hook Stop raggiunge il limite di blocchi

Claude continua a lavorare invece di fermarsi, poi termina il turno con un avviso che indica che l'hook Stop ha bloccato troppe volte consecutive.

Claude Code prende il sopravvento su un hook Stop e ne sovrascrive il blocco dopo che questo ha bloccato otto volte di seguito senza progressi. Il tuo script di hook deve verificare se ha già attivato una continuazione. Analizza il campo stop_hook_active dall'input JSON ed esci subito se è true:

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Allow Claude to stop
fi
# ... rest of your hook logic

Se il tuo hook ha legittimamente bisogno di più di otto iterazioni per convergere, aumenta il limite con CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

Il JSON dell'hook non ha effetto

Il tuo hook stampa un JSON valido, ma la decisione non ha effetto e nella trascrizione non compare alcun errore. Verifica quale causa si applica:

• Output aggiuntivo prima del JSON: qualcos'altro scrive prima su stdout, di solito un echo incondizionato nel profilo della tua shell, quindi l'output non inizia più con { e Claude Code non lo interpreta come JSON. La causa e la soluzione sono descritte dopo questo elenco.
• Un campo al livello sbagliato: confronta la posizione di ciascun campo con il formato dell'output JSON. Ad esempio, permissionDecision va all'interno di hookSpecificOutput, non al livello superiore.

Quando Claude Code esegue un hook command in forma shell, cioè senza args, avvia sh -c su macOS e Linux, Git Bash su Windows, oppure PowerShell quando Git Bash non è installato per impostazione predefinita. Questa shell non è interattiva, ma Git Bash e alcune configurazioni, come BASH_ENV che punta a ~/.bashrc, caricano comunque il tuo profilo. Se quel profilo contiene istruzioni echo incondizionate, il loro output viene anteposto al JSON del tuo hook:

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

L'output combinato non inizia più con {, quindi Claude Code tratta tutto lo stdout come testo semplice e ignora il JSON. Con uscita 0 non viene segnalato nulla nella trascrizione; il tentativo di parsing viene registrato solo nel log di debug. Per risolvere, racchiudi le istruzioni echo nel profilo della tua shell in modo che vengano eseguite solo nelle shell interattive:

# In ~/.zshrc or ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

La variabile $- contiene i flag della shell, e i significa interattiva. Gli hook vengono eseguiti in shell non interattive, quindi l'echo viene saltato.

Quando il tuo hook restituisce permissionDecision o additionalContext al livello superiore invece che all'interno di hookSpecificOutput, il JSON viene comunque interpretato, e Claude Code ignora i campi fuori posto senza segnalare errori. Per vedere quali campi ha ignorato, avvia Claude Code con claude --debug e cerca Hook JSON output had unrecognized keys nel log di debug.

Tecniche di debug

Premi Ctrl+O per aprire la vista della trascrizione e controllare l'esito dell'esecuzione di un hook:

• Esecuzione riuscita: non vedi nulla, a meno che il JSON dell'hook non faccia emergere qualcosa, come systemMessage o il feedback di un hook Stop.
  • Per confermare che un hook è stato eseguito, verificane l'effetto, ad esempio un file riformattato, oppure attiva il logging di debug come descritto di seguito e attiva nuovamente l'hook
• Errore bloccante: nella maggior parte degli eventi vedi il feedback dell'hook. Quando il JSON dell'hook ha preso una decisione bloccante, il feedback è il motivo di quella decisione; altrimenti è lo stderr dell'hook. In alcuni eventi, come ConfigChange ed Elicitation, un blocco non mostra alcun messaggio.
• Errore non bloccante: l'azione è proseguita e vedi un avviso <hook name> hook error con una breve spiegazione, come la prima riga dello stderr preceduta da Failed with non-blocking status code:, oppure un messaggio di convalida o di parsing JSON.

Quali combinazioni di codice di uscita e JSON producono ciascun esito, incluse le eccezioni per singolo evento, è definito nella sezione Output del codice di uscita del riferimento.

Per i dettagli completi dell'esecuzione, inclusi quali hook hanno trovato corrispondenza, i loro codici di uscita, stdout e stderr, leggi il log di debug. Avvia Claude Code con claude --debug-file /tmp/claude.log per scrivere in un percorso noto, quindi esegui tail -f /tmp/claude.log in un altro terminale. Se hai avviato senza quel flag, esegui /debug durante la sessione per abilitare il logging e trovare il percorso del log.

Ulteriori informazioni

• Riferimento Hooks: schemi di eventi completi, formato di output JSON, hooks asincroni e hooks di strumenti MCP
• Considerazioni sulla sicurezza: esaminate prima di distribuire gli hooks in ambienti condivisi o di produzione
• Esempio di validatore di comandi Bash: implementazione di riferimento completa