Ciclo di vita dei hook
Claude Code esegue i hook in punti specifici durante una sessione. Quando un evento si attiva e un matcher corrisponde, Claude Code passa il contesto JSON dell’evento al gestore del hook. Per i hook di comando, l’input arriva su stdin. Per i hook HTTP, arriva come corpo della richiesta POST. Il gestore può quindi ispezionare l’input, intraprendere un’azione e facoltativamente restituire una decisione. Gli eventi si dividono in tre cadenze:- per sessione:
SessionStarteSessionEnd - per turno:
UserPromptSubmit,StopeStopFailure - ad ogni chiamata dello strumento all’interno del ciclo agentico:
PreToolUseePostToolUse, ad eccezione delle chiamateEndConversation, che saltano entrambe
Come si risolve un hook
Per vedere come l’evento, il matcher e il gestore si combinano insieme, considera questo hookPreToolUse che blocca i comandi rm -rf.
- macOS/Linux
- Windows (PowerShell)
Il Lo script legge l’input JSON da stdin, estrae il comando e restituisce una Questo script, come gli altri esempi Bash su questa pagina che analizzano l’input JSON, utilizza
matcher si restringe alle chiamate allo strumento Bash e ai comandi Monitor, e la condizione if si restringe ulteriormente ai sottocomandi Bash che corrispondono a rm *, quindi block-rm.sh viene avviato solo quando entrambi i filtri corrispondono:permissionDecision di "deny" se contiene rm -rf. Salvarlo in .claude/hooks/block-rm.sh nel progetto e renderlo eseguibile con chmod +x .claude/hooks/block-rm.sh in modo che Claude Code possa eseguirlo:jq, quindi installa jq e assicurati che sia nel tuo PATH prima di provarli.Bash "rm -rf /tmp/build" rispetto alla configurazione macOS/Linux. Ecco cosa accade:
1
L'evento si attiva
L’evento
PreToolUse si attiva. Claude Code invia l’input dello strumento come JSON su stdin al hook:2
Il matcher controlla
Il matcher
"Bash" corrisponde al nome dello strumento, quindi questo gruppo di hook si attiva. Se si omette il matcher o si utilizza "*", il gruppo si attiva ad ogni occorrenza dell’evento.3
La condizione if controlla
La condizione
if "Bash(rm *)" corrisponde perché rm -rf /tmp/build è un sottocomando che corrisponde a rm *, quindi questo gestore viene eseguito. Se il comando fosse stato npm test, il controllo if avrebbe fallito e block-rm.sh non sarebbe mai stato eseguito, evitando il sovraccarico di spawn del processo. Il campo if è facoltativo; senza di esso, ogni gestore nel gruppo corrispondente viene eseguito.4
Il gestore del hook viene eseguito
Lo script ispeziona il comando completo e trova Se il comando fosse stato una variante più sicura di
rm -rf, quindi stampa una decisione su stdout:rm come rm file.txt, lo script avrebbe raggiunto exit 0 invece. Il codice di uscita 0 senza output significa che l’hook non ha alcuna decisione da segnalare, quindi la chiamata dello strumento continua attraverso il normale flusso di autorizzazione. L’hook può negare la chiamata, ma rimanere in silenzio non la approva.5
Claude Code agisce sul risultato
Claude Code legge la decisione JSON, blocca la chiamata dello strumento e mostra a Claude il motivo.
Configurazione
Gli hook sono definiti in file di impostazioni JSON. La configurazione ha tre livelli di annidamento:- Scegli un evento hook a cui rispondere, come
PreToolUseoStop - Aggiungi un gruppo matcher per filtrare quando si attiva, ad esempio “per lo strumento Bash”
- Definisci uno o più handler hook da eseguire quando corrisponde
Questa pagina utilizza termini specifici per ogni livello: hook event per il punto del ciclo di vita, matcher group per il filtro, e hook handler per il comando shell, endpoint HTTP, strumento MCP, prompt, o agente che viene eseguito. “Hook” da solo si riferisce alla funzione generale.
Posizioni degli hook
Il luogo in cui definisci un hook determina il suo ambito:
Le sessioni cloud non leggono il tuo
~/.claude/settings.json locale. In un ambiente self-hosted, Claude Code esegue anche gli hook che l’operatore ha seminato da ~/.claude/ dell’host runner, e esegue gli hook nel file di impostazioni gestite dell’immagine runner quando quel file è tra le fonti gestite che Claude Code applica, il che per impostazione predefinita significa solo quando né le impostazioni gestite dal server né una policy Claude Code consegnata da MDM forniscono il livello gestito. Vedi cosa viene trasferito dalla tua configurazione per quali file di impostazioni e plugin, e quindi quali hook, raggiungono una sessione cloud.
Per i dettagli sulla risoluzione dei file di impostazioni, vedi settings.
Gli hook dai file di impostazioni, dalle impostazioni di policy gestite e dai plugin vengono eseguiti anche all’interno di subagenti. Quando un subagent chiama uno strumento, gli eventi dello strumento come PreToolUse e PostToolUse attivano gli stessi hook configurati della conversazione principale, e l’input contiene i campi di input comuni agent_id e agent_type che identificano il subagent.
Gli amministratori possono utilizzare allowManagedHooksOnly nelle impostazioni gestite per limitare quali hook vengono eseguiti:
- I tuoi hook utente, progetto, locale e plugin sono bloccati. Gli hook dai plugin forzatamente abilitati nelle impostazioni gestite
enabledPluginssono esenti - Claude Code restringe anche le tue impostazioni
statusLineefileSuggestionalle impostazioni gestite - Claude Code disabilita anche i plugin con una
commandsource, inclusi i plugin forzatamente abilitati nelle impostazioni gestiteenabledPlugins, a meno chedisableCommandPluginSourcesnon sia esplicitamente impostato sufalse. Lecommandsources richiedono Claude Code v2.1.229 o successivo - Claude Code blocca anche i comandi
headersHelperdel marketplace a meno chedisableCommandPluginSourcesnon sia esplicitamente impostato sufalse, tranne per un marketplace che le impostazioni gestite stesse dichiarano
allowManagedHooksOnly.
Le voci degli hook si uniscono tra i livelli di impostazioni piuttosto che sostituirsi a vicenda: le impostazioni utente, progetto e locale aggiungono i loro hook senza rimuovere quelli gestiti, e l’impostazione disableAllHooks non può disabilitare gli hook gestiti da fuori le impostazioni gestite.
Le allowlist degli hook HTTP si applicano agli hook da ogni fonte, incluse le impostazioni di policy gestite:
allowedHttpHookUrls: quando definito a qualsiasi livello di impostazioni, Claude Code esegue un handler hook HTTP solo se il suo URL corrisponde all’allowlist unitohttpHookAllowedEnvVars: quando definito, Claude Code interpola solo le variabili di ambiente in quella lista negli header degli hook
Modelli matcher
Il campomatcher filtra quando gli hook si attivano. Come viene valutato un matcher dipende dai caratteri che contiene:
Un matcher sul percorso dell’espressione regolare viene testato con
RegExp.prototype.test di JavaScript, che ha successo su una corrispondenza in qualsiasi punto del valore. Edit.* corrisponde sia a Edit che a NotebookEdit; racchiudi il pattern in ^ e $, come in ^Edit$, quando hai bisogno di una corrispondenza di intera stringa.
FileChanged e StopFailure utilizzano un set di corrispondenza esatta più ristretto di sole lettere, cifre, _, e |. Un trattino, spazio, o virgola in un matcher per questi due eventi lo mantiene sul percorso dell’espressione regolare, e solo | separa le alternative. Ogni altro evento con supporto matcher nella tabella che segue accetta | o ,.
L’evento FileChanged non segue queste regole quando costruisce la sua lista di osservazione. Vedi FileChanged.
Ogni tipo di evento corrisponde su un campo diverso:
La corrispondenza di
StopFailure su cloud_credential_error richiede Claude Code v2.1.267 o successivo, la prima versione che segnala i fallimenti di caricamento delle credenziali sotto quel valore piuttosto che server_error o unknown.
Per la maggior parte degli eventi, Claude Code valuta il matcher rispetto a un campo dall’input JSON che invia al tuo hook su stdin. Per gli eventi dello strumento, quel campo è tool_name. Per PreModelSwitch e PostModelSwitch, Claude Code valuta il matcher rispetto al nome canonico che deriva da to_model, come descritto sotto PreModelSwitch. Ogni sezione hook event elenca l’insieme completo dei valori matcher e lo schema di input per quell’evento.
Questo esempio esegue uno script di linting solo quando Claude scrive o modifica un file:
matcher a un evento senza supporto matcher, viene silenziosamente ignorato.
Per gli eventi dello strumento, puoi filtrare più strettamente impostando il campo if sui singoli handler hook. if utilizza la sintassi delle regole di permesso per corrispondere al nome dello strumento e agli argomenti insieme, quindi "Bash(git *)" viene eseguito quando qualsiasi sottocomando dell’input Bash corrisponde a git * e "Edit(*.ts)" viene eseguito solo per i file TypeScript.
Corrispondere ai tool MCP
I tool del server MCP appaiono come tool regolari negli eventi dello strumento (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied), quindi puoi farli corrispondere allo stesso modo di qualsiasi altro nome di strumento.
I tool MCP seguono il modello di denominazione mcp__<server>__<tool>, ad esempio:
mcp__memory__create_entities: tool create entities del server Memorymcp__filesystem__read_file: tool read file del server Filesystemmcp__github__search_repositories: tool search del server GitHub
.* al prefisso del server. .* è obbligatorio: un matcher come mcp__memory o mcp__brave-search contiene solo caratteri di corrispondenza esatta, quindi viene confrontato come una stringa esatta e non corrisponde a nessun tool.
mcp__memory__.*corrisponde a tutti i tool dal servermemorymcp__brave-search__.*corrisponde a tutti i tool da un server il cui nome contiene un trattinomcp__.*__write.*corrisponde a qualsiasi tool il cui nome inizia conwriteda qualsiasi server
mcp__plugin_<plugin-name>_<server-name>__<tool>. Un matcher scritto rispetto alla chiave del server nudo non si attiva mai per questi tool. Per un plugin denominato my-plugin che raggruppa un server sotto la chiave db, un tool query appare come mcp__plugin_my-plugin_db__query, quindi il matcher per ogni tool da quel server è mcp__plugin_my-plugin_db__.*. Utilizza lo stesso nome di tool con scope nel campo if di un handler. Vedi Plugin-provided MCP servers per come viene costruito il nome con scope.
Questo esempio registra tutte le operazioni del server memory e convalida le operazioni di scrittura da qualsiasi server MCP:
Corrispondere ai comandi Monitor
Un hookPreToolUse o PermissionRequest con un matcher Bash viene eseguito anche sui comandi shell che Claude avvia con lo strumento Monitor, ma i suoi allow e updatedInput non hanno effetto su di essi. Richiede Claude Code v2.1.314 o successivo. Anche matcher come Bash|PowerShell, ^Bash$ e Bash.* sono matcher Bash. Un hook con un matcher Bash non viene eseguito per un watch WebSocket, e un hook PostToolUse con un tale matcher non viene eseguito per Monitor.
Un hook che viene eseguito per un comando Monitor può negarlo o fare in modo che Claude Code te lo chieda. Per consentire o riscrivere il comando, passa da un matcher Bash a uno che include Monitor:
- Matcher che include Monitor: con un matcher come
Bash|Monitoro.*, o senza matcher, l’hook riceve l’input della chiamata Monitor stessa, ealloweupdatedInputsi applicano. Inif, indica Monitor, come inMonitor(tail *), che corrisponde secondo le regole seguite daBash(tail *). Se il suoifindica Bash, l’hook riceve comunque l’input della chiamata Monitor, maalloweupdatedInputnon hanno effetto - Matcher
Bash: l’hook riceve una chiamata Bash. Inif, indica Bash, come inBash(tail *). L’hook non viene eseguito se il suoifindica Monitor
Campi handler hook
Ogni oggetto nell’arrayhooks interno è un handler hook: il comando shell, endpoint HTTP, tool MCP, prompt LLM, o agente che viene eseguito quando il matcher corrisponde. Ci sono cinque tipi:
- Command hooks (
type: "command"): esegui un comando shell. Il tuo script riceve l’input JSON dell’evento su stdin e comunica i risultati indietro attraverso codici di uscita e stdout. - HTTP hooks (
type: "http"): invia l’input JSON dell’evento come richiesta HTTP POST a un URL. L’endpoint comunica i risultati indietro attraverso il corpo della risposta utilizzando lo stesso formato di output JSON degli hook di comando. - MCP tool hooks (
type: "mcp_tool"): chiama un tool su un server MCP configurato. L’output di testo del tool viene trattato come stdout di hook di comando. - Prompt hooks (
type: "prompt"): invia un prompt a un modello Claude per la valutazione a turno singolo. Il modello restituisce la sua decisione come JSON. Vedi Prompt-based hooks. - Agent hooks (
type: "agent"): genera un subagent che può utilizzare tool come Read, Grep, e Glob per verificare le condizioni prima di restituire una decisione. Gli agent hook sono sperimentali e potrebbero cambiare. Vedi Agent-based hooks.
timeout di ogni hook in attesa inizia a contare quando quell’hook parte.
Se definisci lo stesso handler in più di un file di impostazioni, viene eseguito una volta. Una copia dello stesso handler di un plugin o di una skill rimane separata.
Gli handler vengono eseguiti nella directory corrente con l’ambiente di Claude Code. Se la directory corrente non esiste più, ad esempio un worktree o una directory temporanea che un’altra shell ha eliminato a metà sessione, Claude Code esegue gli hook di comando dal primo di questi che esiste ancora: la directory in cui è iniziata la sessione, la radice del progetto, la tua directory home, o la directory temporanea del sistema. Claude Code registra un avviso che nomina la directory di fallback nel debug log. Per una sessione worktree che avvii dall’app desktop, vedi Cosa condividono i worktree con il checkout principale.
La variabile di ambiente $CLAUDE_CODE_REMOTE è "true" negli ambienti web remoti e non è impostata nella CLI locale. Claude Code v2.1.199 e successivo imposta $CLAUDE_CODE_BRIDGE_SESSION_ID all’ID della sessione Remote Control mentre la sessione locale ha una connessione Remote Control attiva.
Campi comuni
Questi campi si applicano a tutti i tipi di hook:
Il campo
if contiene esattamente una regola di permesso. Non c’è sintassi &&, ||, o lista per combinare le regole; per applicare più condizioni, definisci un handler hook separato per ciascuna.
In una condizione if per uno strumento di file, un pattern di directory a segmento singolo come "Edit(src/**)" corrisponde solo alla directory src nella directory di lavoro e ai file sotto di essa. Per corrispondere a una directory denominata src a qualsiasi profondità, scrivi "Edit(**/src/**)".
Come i pattern if corrispondono ai comandi Bash
Per i pattern Bash nel campo if, se il tuo comando hook viene eseguito dipende dalla forma del pattern e dal comando Bash che Claude sta invocando. Gli assegnamenti VAR=value iniziali vengono rimossi prima della corrispondenza.
Quando Claude Code non riesce a suddividere l’input Bash in sottocomandi, esegue il tuo hook indipendentemente dal pattern. Poiché il filtro
if è best-effort, utilizza il sistema di permessi piuttosto che un hook per applicare un allow o deny rigido.
Campi command hook
Oltre ai campi comuni, gli hook di comando accettano questi campi:Exec form e shell form
Un hook di comando viene eseguito come exec form quandoargs è impostato, e shell form quando args è omesso. Imposta args ogni volta che l’hook fa riferimento a un placeholder di percorso, poiché ogni elemento viene passato come un argomento senza virgolette. Ometti args quando hai bisogno di funzioni shell come pipe o &&, o quando nessuno dei due problemi si applica.
Exec form viene eseguito quando args è presente. Claude Code risolve command come un eseguibile su PATH e lo genera direttamente con args come vettore di argomenti. Non c’è shell, quindi ogni elemento args è un argomento esattamente come scritto, e i placeholder di percorso come ${CLAUDE_PLUGIN_ROOT} vengono sostituiti in command e in ogni elemento args come stringhe semplici. I caratteri speciali come apostrofi, $, e backtick passano attraverso verbatim perché non c’è shell per interpretarli. Non avviene tokenizzazione shell su nessuna piattaforma.
Shell form viene eseguito quando args è assente. La stringa command viene passata a una shell: sh -c su macOS e Linux, Git Bash su Windows, o PowerShell quando Git Bash non è installato. Imposta il campo shell per scegliere esplicitamente. La shell tokenizza la stringa, espande le variabili, e interpreta pipe, &&, reindirizzamenti, e glob.
Su Windows, exec form richiede che
command si risolva in un vero eseguibile come .exe. Gli shim .cmd e .bat che npm, npx, eslint, e altri tool installano in node_modules/.bin non sono eseguibili e non possono essere generati senza una shell. Per eseguirli in exec form, invoca lo script sottostante con node direttamente, ad esempio "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/node_modules/eslint/bin/eslint.js"]. Il pattern node più script-path funziona su ogni piattaforma perché node.exe è un vero binario. Per eseguire uno shim .cmd o .bat per nome, utilizza shell form.CLAUDE_PROJECT_DIR, CLAUDE_PLUGIN_ROOT, e CLAUDE_PLUGIN_DATA sul processo generato, quindi uno script può leggere process.env.CLAUDE_PLUGIN_ROOT indipendentemente da come è stato lanciato.
Gli hook plugin inoltre sostituiscono i valori ${user_config.*}, solo in exec form: il valore viene sostituito in command e in ogni elemento args come una stringa semplice, quindi nessuna shell lo ri-analizza.
Un hook plugin in shell form il cui command fa riferimento a ${user_config.*} fallisce con un errore invece di essere eseguito. Per utilizzare un valore di opzione da un hook in shell form, leggi la variabile di ambiente $CLAUDE_PLUGIN_OPTION_<KEY>, come $CLAUDE_PLUGIN_OPTION_WEBHOOK_URL per un’opzione webhook_url, o imposta args per passare l’hook a exec form. Prima di v2.1.207, i comandi degli hook plugin in shell form sostituivano anche ${user_config.*}.
In exec form,
command è solo il nome o il percorso dell’eseguibile. Se command è un nome nudo senza separatore di percorso e contiene spazi insieme a args, Claude Code registra un avviso perché la generazione fallirà: non c’è un eseguibile denominato node script.js. Sposta i token extra in args. I percorsi assoluti con spazi, come C:\Program Files\nodejs\node.exe, sono un singolo eseguibile valido e non attivano l’avviso.Campi HTTP hook
Oltre ai campi comuni, gli hook HTTP accettano questi campi:
Claude Code invia l’input JSON dell’hook come corpo della richiesta POST con
Content-Type: application/json. Il corpo della risposta utilizza lo stesso formato di output JSON degli hook di comando.
La gestione degli errori differisce dagli hook di comando; vedi HTTP response handling.
Questo esempio invia gli eventi PreToolUse a un servizio di convalida locale, autenticandosi con un token dalla variabile di ambiente MY_TOKEN:
Campi MCP tool hook
Oltre ai campi comuni, gli hook MCP tool accettano questi campi:
Questo esempio chiama il tool
security_scan sul server MCP my_server dopo ogni Write o Edit, passando il percorso del file modificato:
Come viene letto il risultato del tool
Claude Code legge il contenuto di testo del tool allo stesso modo in cui legge stdout di hook di comando, seguendo la regola di analisi sotto il codice di uscita 0. Se il tool restituisceisError: true, l’hook produce un errore non bloccante e l’esecuzione continua.
Se un errore dell’hook contiene uno di questi messaggi, Claude Code non è riuscito a leggere la risposta dello strumento, quindi l’hook non ha dato alcun verdetto:
PreToolUse, Claude Code rifiuta la chiamata allo strumento che l’hook stava controllando. Su altri eventi come UserPromptSubmit, PostToolUse e Stop, l’errore non è bloccante.
Se l’errore continua a comparire, fai restituire meno dati allo strumento, oppure modifica tool o input dell’hook in modo che la risposta sia più piccola.
Quando il server è ancora in connessione
Su eventi dove un hook può bloccare o cambiare il risultato, comePreToolUse o Stop, Claude Code attende un server in connessione prima di chiamare il tool, per al massimo MCP_TIMEOUT e entro il timeout dell’hook stesso. Su eventi osservazionali, come Notification o SessionEnd, non attende.
Un server che mostra lo stato cached si connette quando l’hook chiama il suo tool. Se il server non è connesso a quel punto, l’hook produce un errore non bloccante e l’esecuzione continua. L’hook non avvia mai un flusso OAuth, quindi autentica il server da /mcp prima.
Eventi che si attivano prima che i server MCP siano disponibili
SessionStart al lancio, incluso con --continue o --resume, e ogni evento Setup si attivano prima che i server MCP della sessione siano disponibili agli hook. Claude Code salta i loro hook mcp_tool senza chiamare il tool, e il debug log registra mcp_tool hooks are not available for the 'SessionStart' hook event (no MCP client context), o lo stesso messaggio che nomina Setup. Quando SessionStart si attiva di nuovo più tardi nella sessione, dopo /clear o una compattazione, i suoi hook mcp_tool vengono eseguiti. Per qualsiasi cosa la sessione abbia bisogno al lancio, utilizza un hook type: "command" su SessionStart invece.
Campi prompt e agent hook
Oltre ai campi comuni, gli hook prompt e agent accettano questi campi:Riferisci gli script per percorso
Utilizza questi placeholder per fare riferimento agli script degli hook relativi alla radice del progetto o del plugin, indipendentemente dalla directory di lavoro quando l’hook viene eseguito:${CLAUDE_PROJECT_DIR}: la radice del progetto dove è iniziata la sessione. Claude Code imposta anche questa variabile nell’ambiente dei server MCP stdio e dei server LSP dei plugin.${CLAUDE_PLUGIN_ROOT}: la directory di installazione del plugin, per gli script raggruppati con un plugin. Vedi variabili di ambiente del plugin per come il percorso si comporta tra gli aggiornamenti.${CLAUDE_PLUGIN_DATA}: la directory di dati persistenti del plugin, per le dipendenze e lo stato che dovrebbero sopravvivere agli aggiornamenti del plugin.
I worktree sono diversi. Se Claude entra in un worktree durante la sessione, Claude Code mantiene
${CLAUDE_PROJECT_DIR} dove era e passa il percorso del worktree ai tuoi hook in un modo diverso:${CLAUDE_PROJECT_DIR}rimane fermo: punta ancora alla radice del progetto dove è iniziata la sessione, quindi un comando come${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.shesegue ancora lo script nel checkout principale.cwdsegue Claude: il campocwdnell’input JSON dell’hook è la radice del worktree dopo che Claude entra in un worktree, e la nuova directory dopo che Claude eseguecd. Leggilo quando un hook ha bisogno di sapere quale directory Claude sta utilizzando.
${CLAUDE_PROJECT_DIR}.- Project scripts
- Plugin scripts
Questo esempio utilizza
${CLAUDE_PROJECT_DIR} per eseguire un verificatore di stile dalla directory .claude/hooks/ del progetto dopo qualsiasi chiamata dello strumento Write o Edit:Hook in skill e agenti
Oltre ai file di impostazioni e ai plugin, gli hook possono essere definiti direttamente negli skill e nei subagenti utilizzando il frontmatter, nello stesso formato di configurazione degli hook basati su impostazioni. Per quanto tempo Claude Code li mantiene registrati dipende dal componente:- Hook del subagent: Claude Code li esegue solo mentre quel subagent è in esecuzione e li rimuove quando finisce. Claude Code converte un hook
Stopqui inSubagentStop, l’evento che si attiva quando un subagent si completa. - Hook dello skill: Claude Code li registra quando tu o Claude invocate lo skill e continua a eseguirli per il resto della sessione, su turni dopo il turno dello skill stesso. Per fare in modo che Claude Code rimuova un hook dopo la sua prima esecuzione riuscita, imposta
once: truesu di esso.
PreToolUse che esegue uno script di convalida della sicurezza prima di ogni comando Bash:
-p in una cartella che non hai ancora fidata.
Gli hook del frontmatter in un subagent del progetto vengono eseguiti solo dopo che accetti la finestra di dialogo di fiducia del workspace per la cartella da cui proviene il file dell’agente. Una sessione -p non conta come accettazione. Cosa viene eseguito prima di fidarti di una cartella confronta questo con la regola del file di impostazioni, e la pagina dei subagent elenca quali ambiti sono esenti.
Limiti sugli hook delle skill
Quando gli hook del frontmatter di una skill non si attivano dopo che tu o Claude avete invocato la skill, esegui/hooks in quella sessione. Se li elenca, consulta Hook non attivato. Se non ne elenca nessuno, la skill potrebbe essere soggetta a un blocco solo plugin o aver superato un limite di hook, e viene eseguita senza nessuno dei suoi hook del frontmatter. Verifica ciascun caso:
- Blocco solo plugin: l’amministratore della tua organizzazione può limitare gli hook ai plugin e alle impostazioni gestite con l’impostazione gestita
strictPluginOnlyCustomization. Una skill mantiene i suoi hook del frontmatter sotto quel blocco solo se è una skill di un plugin, una skill inclusa, o una skill nella directory delle impostazioni gestite. Nemmeno gli hook nei tuoi file di impostazioni vengono eseguiti.- Verifica: digita
/statusin una sessione di Claude Code. Se la rigaSetting sourcesincludeEnterprise managed settings, chiedi al tuo amministratore sestrictPluginOnlyCustomizationblocca gli hook. - Soluzione: sposta la skill in un plugin, perché le skill dei plugin mantengono i loro hook del frontmatter. Elenca il plugin in un marketplace, poi installalo da lì. Se Claude Code rifiuta il marketplace con
is blocked by enterprise policy, chiedi al tuo amministratore di consentire quel marketplace.
- Verifica: digita
- Limite di hook: in Claude Code v2.1.304 o successivo, ogni fonte di skill ha il proprio limite per sessione. Il tuo progetto, la tua cartella di skill personali e ciascun plugin contano come fonti separate. Le skill di una stessa fonte possono registrare al massimo 1.024 hook. I matcher di quegli hook possono totalizzare al massimo 16.384 caratteri. Un matcher con più hook sotto di sé conta una volta per ciascun hook.
- Verifica: ripeti la sessione in cui l’hook non si è attivato, con il log di debug attivo:
- Avvia una nuova sessione dalla tua shell con
claude --debug. Se non avvii le sessioni da una shell, digita invece prima/debugnella nuova sessione. - Invoca le stesse skill nello stesso ordine, comprese quelle invocate da Claude, perché entrambi i totali si accumulano skill dopo skill. Chiedi a Claude di invocare qualsiasi skill che non puoi digitare come comando.
- Cerca
registers none of its hooksnel debug log. Una riga che contiene quel testo indica la skill che ha superato il limite.
- Avvia una nuova sessione dalla tua shell con
- Soluzione: dichiara meno hook o matcher più brevi in quella skill o nelle altre skill della stessa fonte, poi avvia una nuova sessione. Se non puoi modificare quelle skill, chiedi quella modifica al loro autore. Fino ad allora, avvia una nuova sessione e invoca la skill che ti serve prima di qualsiasi altra skill della stessa fonte.
- Verifica: ripeti la sessione in cui l’hook non si è attivato, con il log di debug attivo:
Il menu /hooks
Digita /hooks in Claude Code per aprire un browser di sola lettura per i tuoi hook configurati. L’elenco etichetta ogni hook con la sua provenienza, come le impostazioni utente, le impostazioni di progetto, le impostazioni locali, un plugin o la sessione corrente.
Seleziona un hook per vedere il testo completo di ciò che esegue e dove è definito, come il percorso del suo file di impostazioni o il nome del suo plugin.
Per sfogliare tutti gli eventi hook, compresi quelli senza hook configurati, seleziona All events alla fine dell’elenco.
Disabilita o rimuovi gli hook
Per rimuovere un hook definito in un file di impostazioni, elimina la sua voce da quel file. Per disabilitare temporaneamente tutti gli hook senza rimuoverli, imposta"disableAllHooks": true nel tuo file di impostazioni. Claude Code legge il valore rimasto dopo che la precedenza delle impostazioni si applica, quindi un "disableAllHooks": false nel .claude/settings.json di un progetto sostituisce un true nelle tue impostazioni utente. Per disattivare gli hook per un’esecuzione qualunque siano le impostazioni del progetto, passa --settings '{"disableAllHooks": true}', che ha la precedenza sulle impostazioni di progetto e locale. Non c’è modo di disabilitare un singolo hook mantenendolo nella configurazione.
L’impostazione disableAllHooks rispetta la gerarchia delle impostazioni gestite. Se un amministratore ha configurato gli hook attraverso le impostazioni di policy gestite, disableAllHooks impostato nelle impostazioni utente, progetto, o locale non può disabilitare quegli hook gestiti. Solo disableAllHooks impostato a livello di impostazioni gestite può disabilitare gli hook gestiti. Per la portata completa di ogni livello, vedi disableAllHooks.
Le modifiche dirette agli hook nei file di impostazioni vengono normalmente rilevate automaticamente dal file watcher.
Input e output dell’hook
I command hook ricevono dati JSON tramite stdin e comunicano i risultati attraverso codici di uscita, stdout e stderr. Gli HTTP hook ricevono lo stesso JSON come corpo della richiesta POST e comunicano i risultati attraverso il corpo della risposta HTTP. Questa sezione copre i campi e il comportamento comuni a tutti gli eventi. Ogni sezione dell’evento sotto Hook events include il suo schema di input specifico e le opzioni di controllo della decisione. Su macOS e Linux, i command hook vengono eseguiti nella loro propria sessione senza un terminale di controllo. Il processo hook e qualsiasi processo figlio non possono aprire/dev/tty o inviare sequenze di escape direttamente all’interfaccia Claude Code. Windows non ha /dev/tty.
Per mostrare un messaggio all’utente su qualsiasi piattaforma, restituisci systemMessage nell’output JSON. Alcuni eventi lo scartano o lo consegnano altrove, e ogni sezione dell’evento lo specifica. Per attivare una notifica desktop, impostare un titolo della finestra o suonare il campanello, restituisci invece terminalSequence.
Campi di input comuni
Gli hook event ricevono questi campi come JSON, oltre ai campi specifici dell’evento documentati in ogni sezione hook event. Per i command hook, questo JSON arriva tramite stdin. Per gli HTTP hook, arriva come corpo della richiesta POST.agent_id e agent_type indicano al tuo script in quale agente si è attivato un hook, ad esempio un subagent, un compagno di squadra in-process o l’agente che hai scelto con --agent:
Solo gli hook
SessionStart possono ricevere un campo model, e Claude Code non lo include sempre. Gli hook PreModelSwitch e PostModelSwitch ricevono invece from_model e to_model, quindi usa un hook PostModelSwitch per seguire il modello mentre cambia durante una sessione.
Non esiste una variabile d’ambiente $CLAUDE_MODEL. L’hook può leggere $ANTHROPIC_MODEL se lo imposti nella tua shell, ma quel valore non cambia quando cambi modello con /model durante una sessione.
Un processo hook eredita l’ambiente padre, a parte le variabili dell’esportatore OTEL_* che Claude Code rimuove da ogni sottoprocesso che genera e, quando CLAUDE_CODE_SUBPROCESS_ENV_SCRUB è impostato su 1, le variabili che rimuove. In una sessione che riceve la configurazione HIPAA, Claude Code rimuove anche le credenziali Anthropic dall’ambiente dell’hook.
Ad esempio, un hook PreToolUse per un comando Bash riceve questo su stdin:
tool_name, tool_input e tool_use_id sono specifici dell’evento. Ogni sezione hook event documenta i campi aggiuntivi per quell’evento.
Output del codice di uscita
Quando l’esecuzione del tuo hook termina, Claude Code usa il suo codice di uscita per decidere se continuare con l’azione che lo ha attivato, come una chiamata a uno strumento o un prompt:- Successo: il tuo hook esce con 0. Claude Code applica tutti i campi di output JSON che il tuo hook ha stampato, e l’azione procede a meno che quei campi non la blocchino o la neghino. Hook che avviano un processo in background descrive l’eccezione.
- Errore bloccante: il tuo hook esce con 2. Sugli eventi che possono bloccare, Claude Code interrompe l’azione.
- Errore non bloccante: il tuo hook esce con qualsiasi altro codice, oppure fallisce in qualche altro modo, ad esempio non avviandosi o stampando JSON non valido. L’azione procede, tranne che per gli hook il cui fallimento blocca l’azione, ad esempio un hook con
onFailureimpostato su"block". Su eventi comePreToolUse, vedi un avviso<hook name> hook errornella trascrizione.
PreToolUse esce con 1 ma stampa JSON che supera la convalida, quel JSON può comunque decidere cosa accade. Per trovare il risultato del tuo hook su un evento come PreToolUse, fai corrispondere ciò che ha stampato su stdout nella prima colonna con il suo codice di uscita nella riga in alto:
Alcuni eventi hanno regole proprie:
WorktreeCreate: qualsiasi codice di uscita diverso da zero fa fallire la creazione del worktree, indipendentemente da ciò che dice il tuo JSON.WorktreeRemove: qualsiasi codice di uscita diverso da zero fa fallire la rimozione del worktree se la directory esiste ancora dopo.Stop,SubagentStop,TaskCompletede l’hookUserPromptSubmitdi un plugin: quando il tuo hook esce con 2 senza nulla su stdout e il suo stderr dice che manca un file, ad esempioNo such file or directory, Claude Code tratta l’esecuzione come un errore non bloccante.ElicitationeElicitationResult: Claude Code applica il tuohookSpecificOutputquando il tuo hook esce con 0, e lo ignora su qualsiasi altro codice di uscita.- Eventi che scartano l’output dell’hook, come
StopFailure: Claude Code ignora il tuo JSON su qualsiasi codice di uscita, a parte i campi con effetti collaterali cometerminalSequence, che si attivano comunque.
Exit code 0
Exit 0 significa successo, ed è il codice di uscita previsto quando stampi JSON per il controllo strutturato. Quando il tuo hook esce con 0 ma stampa JSON che non può essere analizzato o non supera la convalida dello schema, l’azione procede a meno che l’hook non sia uno di quelli il cui fallimento blocca l’azione. Invece di un successo con i tuoi campi applicati, l’esecuzione è un errore non bloccante. Se un avviso<hook name> hook error riporta un messaggio di analisi o di convalida, usalo per correggere il tuo output. Per un hook che non è asincrono, il tuo stdout conta come output JSON solo quando stampi un unico oggetto JSON, su una riga o su più righe, senza nient’altro intorno se non spazi vuoti. Claude Code interpreta qualsiasi altro stdout come testo semplice o come un errore di analisi:
- Output che non inizia con
{, oppure che inizia con{e non finisce con}: testo semplice. In base a questa regola, un array JSON e una stringa JSON tra virgolette sono testo semplice. - Due o più righe che si analizzano ciascuna come JSON da sole, la prima che inizia con
{e l’ultima che finisce con}: testo semplice quando nessuna riga è un oggetto JSON output che imposta un campo. Quando una lo è, l’output è un errore di analisi, quindi stampa quell’oggetto senza nient’altro su stdout. - Qualsiasi altra cosa che inizia con
{e finisce con}ma non è JSON valido: errore di analisi.
UserPromptSubmit,UserPromptExpansion,SessionStartePostModelSwitch: Claude Code aggiunge lo stdout in testo semplice come contesto che Claude può vedere e su cui può agire. Non aggiunge lo stdout che non è riuscito ad analizzare.PreCompact: il tuo stdout diventa istruzioni per il riepilogo della compattazione
PreToolUse, abilita il debug logging. Per mostrare un avviso a Claude da un hook PostToolUse o PostToolUseFailure, esci invece con 2 in modo che Claude veda lo stderr anche se lo strumento è già stato eseguito.
Exit code 2
Esci con il codice 2 per bloccare l’azione. Sugli eventi che possono bloccare, Claude Code interrompe l’azione: un hookPreToolUse blocca la chiamata allo strumento, ad esempio, e un hook UserPromptSubmit rifiuta il prompt.
Il messaggio che accompagna il blocco è lo stderr del tuo hook. Se il tuo hook ha stampato anche JSON che prende una decisione di blocco, Claude Code usa invece il motivo di quella decisione.
Il codice di uscita 2 blocca comunque con la maggior parte del JSON che il tuo hook stampa:
- JSON che imposta
continue: false: su eventi comeStopeSubagentStop, il campo ha la precedenza sul codice di uscita 2, quindi Claude o il subagent termina il proprio turno. Per far continuare a lavorare Claude o il subagent, ometti il campo. SuPreToolUse, la chiamata allo strumento resta bloccata con o senza il campo. - Altro JSON che supera la convalida dello schema: Claude Code legge comunque i campi di JSON output. Nemmeno un
permissionDecisioncon valore"allow"lascia passare l’azione. SuElicitationeElicitationResult, l’hookSpecificOutputdi un hook che esce con 2 viene ignorato. - JSON che non supera la convalida dello schema: l’hook blocca comunque. Claude Code usa il tuo stderr come motivo di blocco e registra l’errore di convalida nel log di debug.
rm uscendo con 2 e lascia ogni altro comando al normale flusso dei permessi:
PreToolUse su Bash, un comando che inizia con rm viene bloccato, e Claude riceve lo stderr dell’hook come errore dello strumento, preceduto dal nome dell’evento, dal nome dello strumento e dal comando dell’hook:
Altri codici di uscita
Un avviso<hook name> hook error con Failed with non-blocking status code: significa che il codice di uscita del tuo hook non era 0 o 2 e il suo stdout era testo semplice o vuoto. L’esecuzione è un errore non bloccante, quindi il tuo hook non ha interrotto l’azione. Se l’avviso tronca il tuo stderr, attiva il debug logging come descritto in Debug hooks ed esegui di nuovo l’hook.
Ad esempio, quando un hook PreToolUse su Bash stampa something broke su stderr ed esce con 1, l’avviso PreToolUse:Bash hook error riporta questa riga:
No such file or directory della shell, come nella riga seguente, l’hook non è mai stato eseguito, ad esempio perché il percorso del suo script non esiste:
settings.json significa che l’hook non viene mai eseguito. Per bloccare l’azione quando l’hook non riesce ad avviarsi, imposta onFailure: "block".
Timeout
A parte un command hook che esegui conasync: true, Claude Code annulla un hook command, http o mcp_tool che raggiunge il suo timeout, scartando l’output dell’hook, quindi sulla maggior parte degli eventi un hook scaduto non produce alcuna decisione. Su PreModelSwitch, un hook annullato al suo timeout blocca il cambio di modello.
Su PreToolUse, un hook command, http o mcp_tool scaduto non blocca la chiamata allo strumento, tranne che per gli hook il cui fallimento blocca l’azione. La chiamata continua attraverso il normale flusso dei permessi, quindi non contare su un hook bloccato perché agisca da controllo. Per bloccare la chiamata quando un hook command o http va in timeout, imposta onFailure: "block". Un hook di callback dell’Agent SDK che supera il suo timeout blocca la chiamata allo strumento.
Se usi Code Mode, i timeout su
PreToolUse funzionano in modo diverso. Consulta Tool call refused by a hook.Hook che avviano un processo in background
Un hook può avviare un programma di lunga durata, come un server di sviluppo, e lasciarlo in esecuzione mentre la sessione continua. Nello script dell’hook o nel comando in forma shell:- Esegui il programma in background
- Reindirizza il suo stdout e il suo stderr. Ad esempio, il comando Bash
npm run dev > dev-server.log 2>&1 &li invia entrambi a un file. Se non li reindirizzi, un hook che non è async impiega fino a 10 secondi per terminare dopo l’uscita del proprio processo.
stdio went quiet e refusing to honor the suspect capture.
Questo script di hook PreToolUse stampa la decisione con policy-check.sh, poi carica le metriche in background:
|| exit $?: rende il codice di uscita del controllo quello dell’hook stesso, così un controllo che esce con 2 per negare blocca comunque. Altrimenti l’hook esce con il codice dell’ultima riga, che è 0.>/dev/null 2>&1 &: esegueupload-metrics.shin background con il suo output reindirizzato, così non mantiene aperto l’output dell’hook.
policy-check.sh con 2, poi attiva una chiamata a uno strumento a cui corrisponde l’hook. La chiamata allo strumento viene bloccata.
Bloccare l’azione quando un hook fallisce
Sulla maggior parte degli eventi, quando un hook fallisce o va in timeout, Claude Code esegue comunque l’azione. Un hook di policy con un percorso sbagliato o uno script che si arresta in modo anomalo lascia quindi passare tutto. Per bloccare invece l’azione, imposta"onFailure": "block" su un hook command o http. Richiede Claude Code v2.1.295 o successivo. Per gli hook di callback dell’Agent SDK, consulta Bloccare l’azione quando un callback fallisce.
Su Windows senza Git Bash, un command hook
PreToolUse o PermissionRequest in forma shell che fallisce senza onFailure impostato può invece bloccare la chiamata allo strumento.PreToolUse in .claude/settings.json esegue uno script di progetto prima di ogni comando Bash, e blocca il comando se lo script fallisce:
check-command.js e chiedi a Claude di eseguire un comando Bash come ls. Claude Code blocca la chiamata, e l’errore include failed; blocking because onFailure is "block" seguito dall’output di errore di node, qui ridotto a una riga:
timed out invece di failed. Senza onFailure impostato, lo stesso script mancante è un errore non bloccante e ls viene eseguito.
Ciascuno dei seguenti casi conta come un fallimento:
- Impossibile avviarsi: un command hook non riesce ad avviarsi, ad esempio perché lo script o l’eseguibile non esiste
- Codice di uscita diverso da 0 o 2: conta per un command hook anche se ha stampato JSON che consente l’azione, come
permissionDecision: "allow". Per restituire una decisione JSON, esci con 0 - Errore HTTP: la connessione di un HTTP hook fallisce, oppure lo stato della risposta non è 2xx
- Timeout: l’hook raggiunge il suo
timeout - Output non valido: l’output JSON non può essere analizzato o non supera la convalida dello schema. Per un HTTP hook, conta anche un corpo 2xx che non è né vuoto né un oggetto JSON. Lo stdout in testo semplice di un command hook non è un fallimento
"block" impostato, un fallimento fa ciò che fa il codice di uscita 2 su quell’evento, tranne su PermissionRequest, dove nega la richiesta. Ad esempio, un fallimento di PreToolUse blocca la chiamata allo strumento e un fallimento di UserPromptSubmit blocca il prompt.
Il campo non ha effetto su questi hook:
- Hook
Stop,SubagentStop,TaskCompletedeTeammateIdle: il codice di uscita 2 su questi eventi rimanda Claude a continuare a lavorare, e Claude non può riparare un hook che non viene eseguito - Command hook in background: i command hook che impostano
asyncoasyncRewake
Se usi Code Mode, i fallimenti su
PreToolUse funzionano in modo diverso. Consulta Tool call refused by a hook.Hook falliti su Windows senza Git Bash
Se l’errore di una chiamata a uno strumento bloccata include questo testo, un command hookPreToolUse o PermissionRequest è fallito o è andato in timeout e ha bloccato la chiamata:
PowerShell started no program, inizia dalle correzioni per un command composto solo da stringhe tra virgolette, che PowerShell stampa invece di eseguire.
Senza Git Bash, qualsiasi codice di uscita diverso da 0 o 2 di quell’hook conta come un fallimento, anche quando stampa JSON che non nega la chiamata. Per scoprire perché l’hook è fallito, controlla il log di debug. Poi scegli la correzione adatta al tuo hook:
- La chiamata deve procedere quando l’hook fallisce: aggiungi
"onFailure": "continue"all’hook - L’hook esce con 1 per avvisare ma deve bloccare quando si arresta in modo anomalo: con
"onFailure": "continue", la chiamata procede con il codice di uscita 1, che si tratti di un avviso o di un arresto anomalo. Aggiungi invece"onFailure": "block", e termina lo script con il codice di uscita 0 nei punti in cui avvisa, così quelle chiamate procedono. Per mostrare comunque l’avviso suPreToolUse, stampalo su stdout nel camposystemMessagedi un unico oggetto JSON. - L’hook è scritto per Bash: senza Git Bash, un hook in forma shell senza
shellimpostato viene eseguito in PowerShell, dove può fallire. Installa Git for Windows, oppure impostaCLAUDE_CODE_GIT_BASH_PATHse Git Bash è installato in una posizione in cui Claude Code non lo trova. Poi avvia una nuova sessione. - L’hook esegue un solo
.exe, non un file.cmdo.bat: metti il programma incommande i suoi argomenti inargsper usare la forma exec, e aggiungi"onFailure": "block". Claude Code avvia quindi il programma senza shell. Senza"onFailure": "block", la chiamata può procedere quando il programma fallisce, manca o va in timeout - Un hook di controllo PowerShell che deve bloccare in caso di fallimento: senza
onFailureimpostato, smette di farlo una volta che Git for Windows è installato e Claude Code trova Git Bash. Aggiungi"onFailure": "block"in modo che un fallimento o un timeout blocchi la chiamata con o senza Git Bash. Imposta anche"shell": "powershell"in modo che da quel momento l’hook continui a essere eseguito in PowerShell invece che in Git Bash
blocking because Git Bash wasn't found and this hook doesn't set "shell" to "powershell", so only exit code 0 or 2 counts as its verdict.
PowerShell started no program
Un hook con questo errore è stato eseguito in PowerShell, che stampa uncommand composto solo da stringhe tra virgolette, come "command": "\"C:\\Tools\\guard.exe\"", invece di eseguirlo.
- Per stampare testo, come JSON: imposta
"shell": "powershell", e l’hook esce con 0 - Per eseguire un file
.ps1,.cmdo.bat, oppure un.exeil cui percorso contiene una variabile: imposta"shell": "powershell"e metti&prima del percorso tra virgolette. Lascia$HOMEcosì com’è scritto, e scrivi le variabili d’ambiente come l’esempiocheck.ps1scrive$env:CLAUDE_PROJECT_DIR - Per eseguire un solo
.exein un percorso senza$: rimuovi le virgolette interne dacommand, poi applica la correzione per un hook che esegue un solo.exe, scrivendo"args": []se il programma non accetta argomenti - Per eseguire uno script scritto per Bash: applica la correzione per un hook scritto per Bash
Exit code 2 behavior per event
Il codice di uscita 2 è il modo in cui un hook segnala “fermati, non farlo”. L’effetto dipende dall’evento, perché alcuni eventi rappresentano azioni che possono essere bloccate (come una chiamata a uno strumento che non è ancora avvenuta) e altri rappresentano cose che sono già accadute o non possono essere impedite. Se il tuo hook esce con 2 e imposta anchecontinue: false, controlla prima Exit code 2, perché il risultato può differire dalla riga del tuo evento.
Per
SessionStart, SubagentStart e PostModelSwitch, Claude Code mostra lo stderr del codice di uscita 2 nella trascrizione come un avviso <hook name> hook error, nello stesso modo in cui mostra un errore non bloccante. Claude non lo vede, e la sessione o il subagent procede. Per SubagentStart, l’avviso appare nella trascrizione del subagent stesso, non nella conversazione padre.
Gestione della risposta HTTP
Gli HTTP hook usano i codici di stato HTTP e i corpi della risposta invece dei codici di uscita e di stdout. Per bloccare l’azione quando la richiesta fallisce o restituisce uno stato non-2xx, impostaonFailure: "block". Per bloccare una chiamata a uno strumento o negare un permesso, restituisci una risposta 2xx con un corpo JSON contenente i campi di decisione appropriati.
Dopo un errore non bloccante, l’azione procede a meno che l’hook non sia uno di quelli il cui fallimento blocca l’azione. Tranne che sugli eventi con un proprio contratto di fallimento nella tabella per evento, come WorktreeCreate, ottieni questi risultati per ciascuna risposta o fallimento:
- 2xx con corpo vuoto: successo, equivalente al codice di uscita 0 senza output
- 2xx con corpo costituito da un oggetto JSON: analizzato usando lo stesso schema JSON output dei command hook. Un corpo che non supera la convalida dello schema è un errore non bloccante
- 2xx con qualsiasi altro corpo, come testo semplice: errore non bloccante, gestito nello stesso modo di uno stato non-2xx. Claude Code non aggiunge il testo al contesto di Claude
- Stato non-2xx: errore non bloccante
- Errore di connessione: errore non bloccante
- Timeout: l’hook viene annullato, come descritto in Timeouts
Output JSON
I codici di uscita ti permettono solo di bloccare o restare in silenzio, ma l’output JSON ti dà un controllo più granulare. Invece di uscire con il codice 2 per bloccare, esci con 0 e stampa un oggetto JSON su stdout. Claude Code legge campi specifici da quel JSON per controllare il comportamento, incluso il decision control per bloccare, consentire o inoltrare la decisione all’utente.Scegli un approccio per hook: usa solo i codici di uscita per la segnalazione, oppure esci con 0 e stampa JSON per il controllo strutturato. Per sapere cosa accade se li mescoli, consulta Exit code output.
additionalContext, systemMessage e initialUserMessage di un hook, e il suo stdout semplice, sono limitate a 10.000 caratteri:
- Ambito: Claude Code misura ogni stringa singolarmente, anche quando più hook vengono eseguiti per lo stesso evento. Per l’output JSON, ogni campo viene misurato separatamente; lo stdout semplice viene misurato nel complesso.
- Oltre il limite: tranne che per lo stdout di PreCompact, Claude Code salva l’output in un file nella directory della sessione. Sostituisce l’output con il percorso del file e un’anteprima fino ai primi 2.000 caratteri. Un risultato Bash valido di grandi dimensioni viene gestito nello stesso modo, descritto in Output limits. A differenza di quel limite Bash, questo limite non ha un’impostazione o una variabile d’ambiente per aumentarlo.
- Lettura del file: Claude Code non chiede a Claude di leggere il file, quindi mantieni entro il limite tutto ciò che Claude deve sempre vedere.
- I campi universali come
continuesono elencati nella tabella seguente. Ogni evento li accetta, ma alcuni eventi li scartano o consegnanosystemMessagein un punto diverso dalla trascrizione. Ogni sezione dell’evento lo specifica.terminalSequencefunziona anche su quegli eventi, con le eccezioni elencate in Emit terminal notifications. decisionereasondi livello superiore sono usati da alcuni eventi per bloccare o fornire feedback.hookSpecificOutputè un oggetto annidato per gli eventi che necessitano di un controllo più ricco. Richiede un campohookEventNameimpostato sul nome dell’evento.
Per fermare Claude completamente:
PreToolUse e PostToolUse, l’arresto si applica anche quando la chiamata allo strumento fallisce o si completa mentre Claude sta ancora trasmettendo in streaming una risposta. Non si applica quando il controllo dei permessi rifiuta una chiamata PreToolUse.
Emettere notifiche del terminale
Gli hook vengono eseguiti senza un terminale di controllo, quindi scrivere sequenze di escape direttamente su/dev/tty non funziona. Restituisci invece la sequenza di escape nel campo terminalSequence e Claude Code la emette per te attraverso il proprio percorso di scrittura sul terminale. Questo è privo di race condition e funziona su Windows dove non esiste /dev/tty.
Il campo accetta una stringa di una o più sequenze di escape presenti nell’allowlist:
- OSC
0,1,2: titoli della finestra e dell’icona - OSC
9: notifiche di iTerm2, ConEmu, Windows Terminal e WezTerm, incluso l’avanzamento nella barra delle applicazioni9;4 - OSC
99: notifiche di Kitty - OSC
777: notifiche di urxvt, Ghostty e Warp - BEL semplice
systemMessage e continue, come Notification e StopFailure. Ha alcuni limiti:
- Claude Code scrive la sequenza solo in una sessione interattiva, e solo mentre la sua interfaccia è aperta. In modalità non interattiva con il flag
-pe nell’Agent SDK, ignora il campo. - Il campo funziona solo da un hook che non viene eseguito in background, quindi lascia disattivati
asynceasyncRewake. - Un command hook
WorktreeCreatenon può restituire JSON, perché Claude Code legge il suo stdout come percorso del worktree. Un HTTP hookWorktreeCreaterestituisce JSON e può includere il campo.
Notification in un terminale che legge OSC 777, come Ghostty o Warp. La chiamata jq -nc --arg dello script costruisce l’output JSON e sottopone a escape eventuali virgolette, barre rovesciate e a capo nel messaggio di notifica:
{ "terminalSequence": "..." } è la stessa da qualsiasi shell o linguaggio.
Ricevere notifiche del terminale all’interno di tmux o GNU screen
Quando Claude Code viene eseguito all’interno di tmux o GNU screen, le sequenze OSC richiedono quanto segue per raggiungere la tua applicazione di terminale:- tmux 3.3 o successivo: aggiungi
set -g allow-passthrough ona~/.tmux.conf, poi eseguitmux source-file ~/.tmux.confda una shell. L’opzione si applica a ogni programma in quei riquadri, non solo a Claude Code. Conon, solo i riquadri che tmux sta mostrando possono inviarle. Per consentire di inviarle anche agli altri riquadri di una sessione a cui sei collegato, usaallal posto dion, su tmux 3.4 o successivo. - GNU screen: mantieni visibile in screen la finestra di Claude Code, perché le sequenze provenienti da una finestra in background non raggiungono la tua applicazione di terminale
Aggiungere contesto per Claude
Il campoadditionalContext passa una stringa dal tuo hook nella finestra di contesto di Claude. Claude Code avvolge la stringa in un promemoria di sistema e la inserisce nella conversazione nel punto in cui l’hook si è attivato. Claude legge il promemoria alla successiva richiesta al modello, ma non appare come messaggio di chat nell’interfaccia.
Restituisci additionalContext all’interno di hookSpecificOutput insieme al nome dell’evento:
- SessionStart e SubagentStart: all’inizio della conversazione, prima del primo prompt
- UserPromptSubmit e UserPromptExpansion: insieme al prompt inviato
- PreToolUse, PostToolUse, PostToolUseFailure e PostToolBatch: accanto al risultato dello strumento
- Stop e SubagentStop: alla fine del turno. La conversazione continua in modo che Claude possa agire sul feedback. Consulta Stop decision control
- PostModelSwitch: con la richiesta successiva al cambio. Consulta PostModelSwitch decision control per le tempistiche
additionalContext per lo stesso evento, Claude riceve tutti i valori.
Se la tua stringa contiene un tag <system-reminder> o </system-reminder>, Claude riceve la stringa con il < di quel tag sostituito da <.
Se un valore supera i 10.000 caratteri, Claude Code scrive invece il testo in un file nella directory della sessione e passa a Claude il percorso del file con un’anteprima fino ai primi 2.000 caratteri. Claude può leggere il file, ma Claude Code non glielo chiede.
Usa additionalContext per informazioni che Claude dovrebbe conoscere sullo stato corrente del tuo ambiente o sull’operazione appena eseguita:
- Stato dell’ambiente: il branch corrente, la destinazione del deploy o i feature flag attivi
- Regole di progetto condizionali: quale comando di test si applica al file appena modificato, quali directory sono di sola lettura in questo worktree
- Dati esterni: issue aperte assegnate a te, risultati CI recenti, contenuto recuperato da un servizio interno
bun test” si leggono come informazioni di progetto. Il testo formulato come comandi di sistema fuori banda può attivare le difese di Claude contro la prompt injection, il che porta Claude a segnalarti il testo invece di trattarlo come contesto.
Claude Code salva il testo iniettato nella trascrizione della sessione. Per gli eventi a metà sessione come PostToolUse o UserPromptSubmit, quando riprendi con --continue o --resume, Claude Code riproduce il testo salvato anziché rieseguire l’hook per i turni passati, quindi valori come timestamp o SHA di commit diventano obsoleti. Gli hook SessionStart vengono eseguiti di nuovo alla ripresa con source impostato su "resume", o su "fork" se hai aggiunto --fork-session, quindi possono aggiornare il loro contesto.
Controllo della decisione
Non tutti gli eventi supportano il blocco o il controllo del comportamento tramite JSON. Gli eventi che lo fanno usano ciascuno un insieme diverso di campi per esprimere quella decisione. Usa questa tabella come riferimento rapido prima di scrivere un hook:
Alcuni eventi possono anche riscrivere il contenuto anziché limitarsi a consentirlo o bloccarlo:
PreToolUse:updatedInputdirettamente sottohookSpecificOutputsostituisce gli argomenti di uno strumento prima che venga eseguito. Consulta PreToolUse decision controlPermissionRequest:updatedInputall’interno dell’oggettodecision. Consulta PermissionRequest decision controlPostToolUse:updatedToolOutputsostituisce il risultato dello strumento. In una sessione cloud di Cowork, Claude Code ignoraupdatedToolOutputquando lo strumento èAskUserQuestionoExitPlanMode, e Claude legge la risposta o il piano originale. Consulta PostToolUse decision controlUserPromptSubmit: non può sostituire il prompt; si limita a iniettareadditionalContextinsieme a esso
PreToolUse gli input degli strumenti in uscita e in PostToolUse i risultati delle chiamate riuscite. PostToolUseFailure non può riscrivere un risultato, quindi l’output di un comando che fallisce raggiunge Claude invariato.
Ecco esempi di ogni modello in azione:
- Decisione di livello superiore
- PreToolUse
- PermissionRequest
L’unico valore per
decision è "block". Per consentire all’azione di procedere, ometti decision dal JSON, oppure esci con 0 senza alcun JSON:Eventi degli hook
Ogni evento corrisponde a un punto del ciclo di vita di Claude Code in cui gli hook possono essere eseguiti. Le sezioni seguenti sono ordinate secondo il ciclo di vita: dalla configurazione della sessione, attraverso il ciclo agentico, fino alla fine della sessione. Ogni sezione descrive quando si attiva l’evento, quali matcher supporta, l’input JSON che riceve e come controllare il comportamento tramite l’output.SessionStart
Viene eseguito quando Claude Code avvia una nuova sessione o riprende una sessione esistente. Utile per caricare contesto di sviluppo come issue esistenti o modifiche recenti al tuo codebase, o per impostare variabili d’ambiente. Per un contesto statico che non richiede uno script, usa invece CLAUDE.md. SessionStart viene eseguito a ogni sessione, quindi mantieni questi hook veloci. Sono supportati solo gli hooktype: "command" e type: "mcp_tool". Consulta Campi degli hook di strumenti MCP per sapere quando vengono eseguiti gli hook mcp_tool.
Il valore del matcher corrisponde al modo in cui è stata avviata la sessione:
Quando avvii una sessione interattiva, riprendi una conversazione all’avvio con
--continue o --resume, oppure esegui /clear, gli hook SessionStart vengono eseguiti in background. Puoi digitare subito, e una conversazione che hai ripreso appare senza attendere gli hook. La prima risposta di Claude attende comunque che gli hook terminino, così il loro contesto raggiunge Claude.
Quando cambi conversazione con /resume all’interno di una sessione, il cambio attende invece che gli hook terminino. Se esegui /clear o passi a un’altra conversazione mentre gli hook in background sono ancora in esecuzione, nulla di ciò che restituiscono si applica alla sessione.
La stessa attesa si applica all’avvio, inclusa una sessione ripresa: un prompt che invii mentre gli hook SessionStart sono ancora in esecuzione non raggiunge Claude finché non terminano.
Durante entrambe le attese, premi Esc per riportare il prompt nell’input senza inviarlo. Gli hook continuano l’esecuzione.
Input di SessionStart
Oltre ai campi di input comuni, gli hook SessionStart ricevonosource e facoltativamente model, agent_type e session_title:
Una sessione a cui non hai dato un nome può comunque avere un titolo generato. Quel titolo non è un titolo personalizzato e non appare in
session_title.
Quando source è "resume" o "fork" e la trascrizione contiene almeno una risposta di Claude, gli hook SessionStart ricevono anche i quattro campi seguenti. Il tuo hook può usarli per segnalare quanto costa riprendere una conversazione datata prima della prima richiesta, ad esempio in un systemMessage. Questi campi richiedono Claude Code v2.1.251 o successivo.
Questo esempio mostra l’input per una sessione ripresa 90 minuti dopo la sua ultima risposta:
Controllo delle decisioni di SessionStart
Un hook SessionStart può aggiungere contesto per Claude, fornire il primo messaggio utente, impostare il titolo della sessione, osservare file e ricaricare le skill. Restituisci il campo per ciascuna di queste azioni, oltre ai campi di output JSON disponibili per tutti gli hook:
Questo output aggiunge contesto e assegna un nome alla sessione:
initialUserMessage o sessionTitle, installa il plugin prima dell’avvio della sessione. Claude Code ignora entrambi i campi provenienti da un plugin la cui installazione termina dopo l’esecuzione degli hook SessionStart.
Ricaricare le skill installate da un hook
Per rendere disponibili nella stessa sessione le skill installate da un hook SessionStart, restituiscireloadSkills. Il rilevamento delle skill viene normalmente eseguito prima che gli hook SessionStart terminino, quindi senza di esso i file che un hook scrive in ~/.claude/skills/ o .claude/skills/ possono mancare quando viene eseguito il primo prompt.
Questo esempio sincronizza un repository di skill condiviso e richiede il nuovo esame:
Rendere persistenti le variabili d’ambiente
Gli hook SessionStart hanno accesso alla variabile d’ambienteCLAUDE_ENV_FILE, che fornisce un percorso di file in cui puoi rendere persistenti le variabili d’ambiente per i comandi shell che Claude esegue più avanti nella sessione.
Per impostare singole variabili d’ambiente, scrivi istruzioni export in CLAUDE_ENV_FILE. Usa l’aggiunta in coda (>>) per preservare le variabili impostate da altri hook:
$PATH in export PATH="$PATH:./node_modules/.bin".
Variabili persistenti nei comandi PowerShell
Anche i comandi PowerShell ricevono le variabili daCLAUDE_ENV_FILE, in Claude Code v2.1.296 o successivo, ma PowerShell non esegue mai il file. Claude Code legge invece le assegnazioni dal file e le copia nell’ambiente del comando PowerShell. Lo fa solo quando ogni riga è di uno dei tipi seguenti, considerando ciò che ogni hook di questa sessione ha scritto e qualsiasi script su cui hai impostato CLAUDE_ENV_FILE prima dell’avvio:
- Una riga vuota o un commento
# - Un’assegnazione all’inizio della riga, scritta
export NAME=value,declare -x NAME=valueoNAME=value, con un valore che Bash userebbe esattamente come scritto, composto da qualsiasi combinazione di queste parti: testo senza virgolette che usa solo lettere, cifre e i caratteri_ @ % + = : , . / -, testo tra virgolette singole e testo tra virgolette doppie in cui ogni$, backtick o"al suo interno è preceduto da una barra rovesciata di escape
export PATH="$PATH:./node_modules/.bin" con il suo $PATH senza escape, un comando source o le stringhe $'...' che direnv export bash stampa, i comandi PowerShell non ricevono nessuna delle variabili e claude --debug registra Session environment is not all plain assignments. I comandi Bash le ricevono comunque tutte. Su Windows, i comandi PowerShell non ricevono inoltre una variabile il cui valore contiene / o \, perché Git Bash e Windows scrivono i percorsi in modo diverso. Un comando PowerShell in sandbox non riceve nessuna delle variabili.
CLAUDE_ENV_FILE è disponibile per gli hook SessionStart, Setup, CwdChanged e FileChanged. Gli altri eventi degli hook non hanno accesso a questa variabile, e nemmeno un hook eseguito in PowerShell, sia tramite "shell": "powershell" sia per impostazione predefinita su Windows senza Git Bash.Setup
Si attiva solo quando avvii Claude Code con--init-only, oppure con --init o --maintenance in modalità non interattiva con il flag -p. Non si attiva durante il normale avvio. Usalo per l’installazione una tantum di dipendenze o per la pulizia pianificata che attivi esplicitamente da CI o da script, separatamente dal normale avvio della sessione. Per l’inizializzazione di ogni sessione, usa invece SessionStart.
Il valore del matcher corrisponde al flag della CLI che ha attivato l’hook:
Quando esegui
claude --init-only, Claude Code esegue gli hook Setup e gli hook SessionStart con il matcher startup, poi esce senza avviare una conversazione.
Quando avvii o continui una conversazione con -p, devi anche fornire un prompt, come argomento o tramite pipe su stdin. Puoi omettere il prompt quando un hook SessionStart fornisce initialUserMessage o quando riprendi una sessione con una chiamata a uno strumento differita.
In caso di successo, --init-only non stampa nulla sul terminale. Per verificare che gli hook siano stati eseguiti, avvia con claude --debug-file <path> --init-only, sostituendo <path> con la posizione di un file di log, e controlla nel log le voci degli hook Setup e SessionStart.
Poiché Setup non si attiva a ogni avvio, un plugin che necessita dell’installazione di una dipendenza non può basarsi solo su Setup. Lo schema pratico è verificare la dipendenza al primo utilizzo e installarla se manca, ad esempio un hook o una skill che verifica la presenza di ${CLAUDE_PLUGIN_DATA}/node_modules ed esegue npm install se assente. Consulta la directory dei dati persistenti per sapere dove archiviare le dipendenze installate. Se distribuisci il tuo plugin tramite un marketplace, potresti non aver bisogno di questo schema: Claude Code installa automaticamente le dipendenze idonee dei pacchetti Node.js quando memorizza il plugin nella cache.
Input di Setup
Oltre ai campi di input comuni, gli hook Setup ricevono un campotrigger impostato su "init" o "maintenance":
Controllo delle decisioni di Setup
Gli hook Setup non possono bloccare; l’esecuzione continua con qualsiasi codice di uscita. Con qualsiasi codice di uscita, Claude Code scarta i campi di output JSON di un hook Setup, comesystemMessage, continue e hookSpecificOutput.additionalContext. Con -p, lo stdout, lo stderr e il codice di uscita di un hook Setup compaiono nell’output dell’esecuzione solo come eventi hook_response quando avvii con --output-format stream-json --verbose.
Gli hook Setup hanno accesso a CLAUDE_ENV_FILE. Se il tuo hook scrive variabili in quel file, queste persistono nei successivi comandi Bash della sessione, come negli hook SessionStart. Su Setup vengono eseguiti solo gli hook type: "command". Un hook type: "mcp_tool" su Setup viene sempre saltato, come descritto in Campi degli hook di strumenti MCP.
InstructionsLoaded
Si attiva quando un fileCLAUDE.md o .claude/rules/*.md viene caricato nel contesto. Questo evento si attiva all’avvio della sessione per i file caricati subito e di nuovo più tardi quando i file vengono caricati in modo differito, ad esempio quando Claude accede a una sottodirectory che contiene un CLAUDE.md annidato o quando le regole condizionali con frontmatter paths: corrispondono. L’hook non supporta il blocco né il controllo delle decisioni. Viene eseguito in modo asincrono a scopo di osservabilità.
Questo evento non si attiva quando Claude legge direttamente AGENTS.md tramite l’impostazione Project instructions. Si attiva invece quando un CLAUDE.md importa il tuo AGENTS.md, con load_reason impostato su include come per qualsiasi altro file importato, e quando CLAUDE.md è un collegamento simbolico ad esso, come un normale caricamento di CLAUDE.md.
Il matcher viene confrontato con load_reason. Ad esempio, usa "matcher": "session_start" per attivarlo solo per i file caricati all’avvio della sessione, oppure "matcher": "path_glob_match|nested_traversal" per attivarlo solo per i caricamenti differiti.
Input di InstructionsLoaded
Oltre ai campi di input comuni, gli hook InstructionsLoaded ricevono questi campi:Controllo delle decisioni di InstructionsLoaded
Gli hook InstructionsLoaded non hanno controllo delle decisioni. Non possono bloccare né modificare il caricamento delle istruzioni. Claude Code scarta i loro campi di output JSON, comesystemMessage e continue. Usa questo evento per log di audit, monitoraggio della conformità o osservabilità.
UserPromptSubmit
Viene eseguito quando viene inviato un prompt, prima che Claude lo elabori. Questo ti permette di aggiungere contesto aggiuntivo in base al prompt/alla conversazione, convalidare i prompt o bloccare determinati tipi di prompt. Gli hookUserPromptSubmit non si attivano solo sui prompt che digiti. Claude Code li esegue anche quando:
- Viene attivata un’attività pianificata limitata alla sessione, inclusa un’iterazione di
/loop - Un subagent in background riferisce alla sessione che lo ha avviato
- Un messaggio inviato da un’altra sessione arriva alla tua conversazione principale
- L’output del codice che Claude esegue in una sessione Code Mode, per gli hook
command,httpemcp_tool, quando il codice può essere eseguito in background
UserPromptSubmit hanno un timeout predefinito di 30 secondi per i tipi command, http e mcp_tool, più breve del valore predefinito di 600 secondi per quei tipi nella maggior parte degli altri eventi. Poiché questo hook viene eseguito prima di ogni prompt e blocca l’elaborazione del modello finché non termina, un hook bloccato blocca la sessione. Se il tuo hook ha bisogno di più tempo, imposta il campo timeout nella voce dell’hook.
Fatta eccezione per un hook di comando che esegui con async: true, un hook UserPromptSubmit di comando, HTTP o di strumento MCP che raggiunge il suo timeout viene annullato e il suo output, incluso qualsiasi additionalContext, viene scartato. Il prompt raggiunge comunque Claude senza quel contesto. Per bloccare invece il prompt, imposta onFailure: "block" su un hook di comando o HTTP. La trascrizione mostra un avviso che indica l’hook, il timeout scattato e che l’output è stato scartato.
Un hook di callback dell’Agent SDK su UserPromptSubmit che raggiunge il timeout blocca il prompt con un messaggio che indica l’hook e il timeout, perché un callback in quel punto può fungere da controllo di policy che non deve fallire in modo permissivo. La sessione continua.
Esc durante il controllo di un prompt
Se premi Esc o interrompi la sessione mentre gli hook stanno ancora controllando un prompt, il controllo si interrompe e il prompt non raggiunge Claude. Il testo che hai digitato nel terminale torna nell’input del prompt, e gli hook lo controllano di nuovo quando lo reinvii.
Un hook può bloccare il prompt nello stesso momento in cui interrompi. Il prompt rimane quindi bloccato: vedi il messaggio di blocco di quell’hook e il testo non torna nell’input.
Input di UserPromptSubmit
Oltre ai campi di input comuni, gli hook UserPromptSubmit ricevono il campoprompt contenente il testo inviato. Il contenuto incollato che è stato compresso in un segnaposto [Pasted text #N] arriva espanso al suo posto. Nelle sessioni in cui Claude Code contrassegna il testo incollato per Claude, quel contenuto espanso si trova tra una riga <pasted_content id="…"> e una riga </pasted_content id="…">, quindi tieni conto di quelle righe se il tuo hook analizza il prompt.
Gli hook UserPromptSubmit ricevono anche session_title quando la sessione ha un titolo personalizzato, con lo stesso significato del campo session_title di SessionStart.
/deploy staging, l’hook riceve quella riga così come l’hai digitata anziché il contenuto espanso della skill. Se l’hook blocca il prompt, il comando non viene eseguito, quindi non vengono eseguiti nemmeno i comandi shell che la skill inserisce con !`<command>`. Per basare la corrispondenza sul nome o sugli argomenti del comando, usa invece UserPromptExpansion.
Controllo delle decisioni di UserPromptSubmit
Gli hookUserPromptSubmit possono controllare se un prompt inviato viene elaborato e aggiungere contesto. Tutti i campi di output JSON sono disponibili.
Esistono due modi per aggiungere contesto alla conversazione con codice di uscita 0:
- Stdout in testo semplice: Claude Code aggiunge al contesto di Claude lo stdout che tratta come testo semplice
- JSON con
additionalContext: usa il formato JSON riportato sotto per un maggiore controllo. Il campoadditionalContextviene aggiunto come contesto
additionalContext vengono ciascuno inseriti come promemoria di sistema che inizia con il nome dell’hook; Claude li legge entrambi. Per verificare la consegna, controlla il log di debug.
Per bloccare un prompt, restituisci un oggetto JSON con decision impostato su "block":
Se il tuo hook blocca uscendo con 2, il suo testo stderr viene trattato allo stesso modo di
reason.
Cosa lascia dietro di sé un prompt bloccato
Un prompt bloccato non raggiunge mai Claude, ma il suo testo non viene rimosso ovunque. Per impostazione predefinita, il messaggio di blocco mostrato all’utente termina conOriginal prompt: seguito dal testo inviato, e Claude Code scrive quel messaggio nel file della trascrizione della sessione su disco. Per omettere il testo dal messaggio, stampa JSON con "suppressOriginalPrompt": true all’interno di hookSpecificOutput. Funziona sia che l’hook blocchi con decision: "block" sia che esca con 2.
suppressOriginalPrompt modifica solo il messaggio di blocco. Il testo inviato può comunque apparire in file locali come la trascrizione della sessione e la cronologia dei prompt, quindi un hook di blocco non è un modo per tenere un segreto lontano dal disco. Per limitare o rimuovere quei file, consulta Archiviazione in testo semplice e Cancellare i dati locali.
UserPromptExpansion
Viene eseguito quando un comando digitato dall’utente si espande in un prompt prima di raggiungere Claude. Usalo per impedire l’invocazione diretta di comandi specifici, inserire contesto per una particolare skill o registrare quali comandi invocano gli utenti. Ad esempio, un hook che corrisponde adeploy può bloccare /deploy a meno che non sia presente un file di approvazione, oppure un hook che corrisponde a una skill di revisione può aggiungere la checklist di revisione del team come additionalContext.
Questo evento copre il percorso che PreToolUse non copre: un hook PreToolUse che corrisponde allo strumento Skill si attiva solo quando Claude chiama lo strumento, ma digitare direttamente /skillname aggira PreToolUse. UserPromptExpansion si attiva su quel percorso diretto.
Corrisponde su command_name. Lascia il matcher vuoto per attivarlo su ogni comando di tipo prompt.
Input di UserPromptExpansion
Oltre ai campi di input comuni, gli hook UserPromptExpansion ricevonoexpansion_type, command_name, command_args, command_source e la stringa prompt. Il campo expansion_type è slash_command per le skill e i comandi personalizzati, oppure mcp_prompt per i prompt dei server MCP.
Controllo delle decisioni di UserPromptExpansion
Gli hookUserPromptExpansion possono bloccare l’espansione o aggiungere contesto. Tutti i campi di output JSON sono disponibili.
Un hook che blocca uscendo con 2 viene instradato allo stesso modo di
reason: il messaggio di blocco mostra all’utente il testo di stderr.
MessageDisplay
Viene eseguito mentre un messaggio dell’assistente viene trasmesso sullo schermo. Claude Code visualizza il messaggio in incrementi: ogni volta che un gruppo di righe appena completate è pronto per il rendering, l’hook viene eseguito una volta con quelle righe e Claude Code visualizza al loro posto il testo sostitutivo dell’hook. Un messaggio lungo produce diverse chiamate; un messaggio breve può produrne solo una. Usa MessageDisplay per:- rimuovere il markdown per una visualizzazione minimale
- trasformare il testo che un’applicazione Agent SDK mostra ai suoi utenti
- oscurare chiavi API o nomi host interni dalle risposte di Claude
timeout nella voce dell’hook.
MessageDisplay riguarda solo la visualizzazione: il testo sostitutivo cambia solo ciò che viene mostrato sullo schermo. La trascrizione e ciò che vede Claude mantengono il testo originale, quindi Claude non vede mai la sostituzione, e la modalità verbose mostra l’originale. L’hook riceve solo il testo dei messaggi dell’assistente, quindi i risultati degli strumenti e il testo che digiti vengono visualizzati senza modifiche.
MessageDisplay non supporta i matcher e si attiva per ogni messaggio dell’assistente che trasmette testo; i messaggi senza testo, come le risposte composte solo da chiamate a strumenti, non lo attivano.
Nelle esecuzioni non interattive, incluse le query dell’Agent SDK e claude -p, MessageDisplay viene eseguito una volta per messaggio dell’assistente anziché una volta per gruppo di righe. L’unica chiamata arriva dopo il completamento del messaggio e contiene l’intero testo del messaggio: index è 0, final è true e delta contiene l’intero messaggio. Un hook che raccoglie il testo di delta per ogni messaggio riceve lo stesso testo complessivo in entrambe le modalità.
Input di MessageDisplay
Oltre ai campi di input comuni, gli hook MessageDisplay ricevono gli identificatori del turno e del messaggio, la posizione di questa chiamata all’interno del messaggio e il nuovo testo indelta. I confini dei gruppi dipendono da come viene trasmesso il testo, quindi usa index e final per monitorare l’avanzamento in un messaggio anziché aspettarti che le righe siano raggruppate in un modo particolare.
Output di MessageDisplay
Oltre ai campi di output JSON disponibili per tutti gli hook, gli hook MessageDisplay possono restituiredisplayContent per sostituire il delta sullo schermo:
Gli hook MessageDisplay non hanno controllo delle decisioni. Non possono bloccare il messaggio né modificare ciò che viene archiviato nella trascrizione o inviato a Claude. Claude Code agisce su
displayContent dal loro output JSON e scarta systemMessage e continue.
Questo esempio rimuove la formattazione markdown dalle risposte di Claude per una visualizzazione in testo semplice. Lo script legge ogni gruppo da stdin, rimuove i marcatori del grassetto e i backtick del codice inline da delta e restituisce il risultato come displayContent.
- macOS/Linux
- Windows (PowerShell)
Registra un hook di comando per l’evento nel tuo file di impostazioni:Salva questo script in
.claude/hooks/plain-display.sh nel tuo progetto e rendilo eseguibile con chmod +x:jq, Claude Code visualizza il testo originale e segnala il fallimento solo nell’output di debug, non nella sessione.
PreToolUse
Viene eseguito dopo che Claude ha creato i parametri dello strumento e prima dell’elaborazione della chiamata allo strumento. Corrisponde a qualsiasi nome di strumento eccettoEndConversation: strumenti integrati come Bash, PowerShell, Edit, Write, Read, Glob, Grep, Agent, Workflow, WebFetch, WebSearch, AskUserQuestion e ExitPlanMode, e qualsiasi nome di strumento MCP.
Per eseguire un hook quando un file specifico cambia su disco, indipendentemente da chi lo ha scritto, usa FileChanged invece di far corrispondere per nome gli strumenti di modifica dei file. A differenza di PreToolUse, Claude Code esegue gli hook FileChanged dopo la modifica, e non hanno controllo delle decisioni, quindi non possono bloccare la scrittura.
Usa il controllo delle decisioni di PreToolUse per consentire, negare, chiedere conferma o differire la chiamata allo strumento.
Un hook callback dell’Agent SDK su PreToolUse che supera il timeout blocca la chiamata allo strumento.
Input di PreToolUse
Oltre ai campi di input comuni, gli hook PreToolUse ricevonotool_name, tool_input e tool_use_id.
Per uno strumento MCP, l’input contiene anche mcp_server, un oggetto con il name del server e un source che indica da dove proviene la definizione del server. I valori di source includono plugin, sdk e ambiti di configurazione come user e project. McpServerProvenance nel riferimento dell’Agent SDK li elenca tutti e spiega come trattarne uno che non riconosci. Basa le decisioni di fiducia su source anziché su name o sul prefisso del nome dello strumento mcp__<server>__. Il campo mcp_server richiede Claude Code v2.1.274 o successivo.
Per gli strumenti di file Write, Edit e Read, tool_input.file_path è sempre assoluto:
- Claude Code espande
~e i percorsi relativi prima dell’esecuzione degli hook, quindi un hook che effettua la corrispondenza sui percorsi non può essere aggirato tramite~o una scrittura relativa dello stesso percorso - Su Windows, il percorso arriva con separatori a barra rovesciata, anche quando il tuo hook viene eseguito in Git Bash, dove
$PWDappare come/c/project - Un confronto scritto con barre normali, come un controllo su
/src/, non corrisponde mai a un percorso con barre rovesciate, e la chiamata allo strumento procede come se l’hook non avesse nulla da bloccare - Normalizza i separatori prima del confronto:
FILE_PATH="${FILE_PATH//\\//}"in Bash, oppurefile_path.replace("\\", "/")in Python, poi fai corrispondere un segmento di percorso come/src/anziché ancorare con^, dato che il percorso è assoluto
Write su Windows fornisce:
tool_input dipendono dallo strumento:
Bash
Esegue comandi shell.
Quando un comando Bash modifica file in un repository Git, Claude Code può registrare cosa è cambiato. Registra le modifiche in ogni modalità di permesso quando l’impostazione
bashEditDiffEnabled attiva la registrazione; la voce di quell’impostazione indica quali file possono impostarla. Altrimenti le registra solo in modalità auto e in modalità bypassPermissions, e solo quando Claude Code indica a Claude di modificare i file tramite Bash. Imposta bashEditDiffEnabled su false per disattivare la registrazione. I comandi in background e i comandi di sola lettura non includono alcun diff.
Il tuo hook PostToolUse riceve quindi i file modificati in tool_response.bashEditDiff. L’elenco copre ciò che è cambiato nel repository durante l’esecuzione del comando. I file ignorati da Git e i file nei submodule non sono elencati. Richiede Claude Code v2.1.269 o successivo.
L’elenco è fornito al meglio delle possibilità ed è in beta pubblica. Claude Code può non rilevare una modifica, includere un file che un altro processo ha modificato nello stesso momento o fermarsi ai suoi limiti di dimensione. La struttura del campo può cambiare. Usa l’elenco per trovare cosa rivedere, non per applicare una policy.
changedFiles e files elencano ciò che il comando ha modificato; i campi rimanenti indicano quanto è completo e affidabile quell’elenco.
PowerShell
Esegue comandi PowerShell. Consulta lo strumento PowerShell per la disponibilità per piattaforma. I campi corrispondono a quelli dello strumento Bash, con la stringa del comando incommand:
Fai corrispondere
Bash|PowerShell negli hook che ispezionano i comandi shell, in modo che coprano entrambi gli strumenti:
- Su Windows, ovunque sia abilitato lo strumento PowerShell, Claude tratta PowerShell come shell principale e vi instrada i comandi shell.
- Su Windows senza Git Bash, lo strumento viene abilitato automaticamente e Claude Code non registra affatto lo strumento Bash.
- Un hook che corrisponde solo a
Bashnon si attiva mai lì.
Write
Crea o sovrascrive un file.Edit
Sostituisce una stringa in un file esistente.Read
Legge il contenuto dei file.Glob
Trova i file che corrispondono a un pattern glob.Grep
Cerca nel contenuto dei file con espressioni regolari.WebFetch
Recupera ed elabora contenuti web.WebSearch
Effettua ricerche sul web.Agent
Avvia un subagent.
Quando una chiamata Agent in primo piano termina, il tuo hook PostToolUse riceve il risultato del subagent e la telemetria dell’esecuzione in
tool_response. Leggi questi campi per ispezionare l’esecuzione; per i totali di token e costi tra i subagent, usa i contatori di token e costi filtrati su query_source "subagent", poiché totalTokens e usage coprono solo la richiesta finale:
In Claude Code v2.1.271 o successivo, un subagent eseguito con lo strumento
SubagentHandback, che Claude Code fornisce in modalità auto, consegna il suo resoconto tramite quello strumento anziché restituirlo come testo. Il campo content del suo risultato completed contiene quindi una breve nota su quella consegna anziché il resoconto stesso. Per leggere il resoconto, fai corrispondere un hook PreToolUse o PostToolUse su SubagentHandback e leggi tool_input.message.
Per i subagent in background, lo strumento restituisce un risultato quando l’attività passa in background, quindi tool_response non contiene campi di utilizzo: un avvio in background restituisce immediatamente, e un’attività in primo piano che Claude Code sposta in background durante l’esecuzione restituisce al momento di quella transizione. Contiene status: "async_launched", agentId, description, prompt, outputFile e resolvedModel.
In una risposta completed, resolvedModel indica il modello con cui è partito il subagent, che può differire dal valore model in tool_input, ad esempio quando si applica availableModels o un altro override. In una risposta async_launched, resolvedModel indica il modello in uso quando l’agente è passato in background, quindi un cambio avvenuto prima del passaggio in background vi si riflette.
AskUserQuestion
Pone all’utente da una a quattro domande a scelta multipla.ExitPlanMode
Presenta un piano e chiede all’utente di approvarlo prima che Claude esca dal plan mode. Claude scrive il piano in un file su disco prima di chiamare lo strumento, quindi iltool_input letterale proveniente dal modello è tipicamente vuoto. Claude Code inserisce il contenuto del piano e il percorso del file prima di passare l’input agli hook.
In
PostToolUse, tool_response è un oggetto con i campi plan e filePath che contengono il piano approvato, più flag di stato interni. Leggi tool_response.plan per il contenuto del piano anziché rileggere il file dal disco.
Controllo delle decisioni di PreToolUse
Gli hookPreToolUse possono controllare se una chiamata a uno strumento procede. A differenza di altri hook che usano un campo decision di primo livello, PreToolUse restituisce la sua decisione all’interno di un oggetto hookSpecificOutput. Questo gli offre un controllo più ricco: quattro esiti (consentire, negare, chiedere conferma o differire) più la possibilità di modificare l’input dello strumento prima dell’esecuzione. Per consentire o riscrivere un comando Monitor, consulta Confrontare i comandi Monitor.
Quando più hook PreToolUse restituiscono decisioni diverse, l’ordine di precedenza è
deny > defer > ask > allow.
Un hook che blocca uscendo con 2 viene instradato allo stesso modo di "deny": Claude vede il messaggio di stderr come motivo della negazione.
Quando un hook restituisce "ask", la richiesta di permesso mostrata all’utente include un’etichetta che identifica la provenienza dell’hook: [settings] per un hook da qualsiasi file di impostazioni o dal frontmatter di un agente, [plugin:<name>] per l’hook di un plugin, oppure [skill] per un hook dal frontmatter di una skill. Questo aiuta gli utenti a capire quale fonte di configurazione sta richiedendo la conferma.
In precedenza PreToolUse usava i campi di primo livello
decision e reason, ma questi sono deprecati per questo evento. Usa invece hookSpecificOutput.permissionDecision e hookSpecificOutput.permissionDecisionReason. I valori deprecati "approve" e "block" corrispondono rispettivamente a "allow" e "deny". Altri eventi come PostToolUse e Stop continuano a usare decision e reason di primo livello come formato attuale.updatedInput di PreToolUse in modalità auto
Quando il tuo hook restituisce updatedInput senza permissionDecision in modalità auto, Claude Code può negare la chiamata modificata. Il server ha esaminato l’input scritto da Claude, non l’input restituito dal tuo hook. Nelle sessioni interattive del terminale e nelle sessioni VS Code con una connessione diretta all’API di Anthropic, la negazione include questo testo:
- Può negare la chiamata o inviarla alla richiesta di permesso
- Qualsiasi
updatedInputche restituisce viene scartato, quindi ciò che viene eseguito è ciò che il server ha esaminato
command nelle impostazioni o nel file degli hook di un plugin può modificare le chiamate Bash, PowerShell, Monitor, Edit, Write e NotebookEdit senza questa negazione. La negazione può comunque comparire, ad esempio quando un hook qualsiasi ha modificato una chiamata precedente nella stessa risposta di Claude o quando un comando Bash chiede di essere eseguito fuori dalla sandbox.
Decisioni ask di PreToolUse in modalità auto
In modalità auto, l’"ask" di un hook PreToolUse normalmente invia la chiamata allo strumento alla richiesta di permesso, e il classificatore non la decide. Alcune chiamate seguono un percorso diverso:
- Chiamate segnalate anche dai controlli interni di Claude Code: includono le scritture in percorsi protetti e i comandi che chiedono di essere eseguiti fuori dalla sandbox. Il classificatore può negare una di queste chiamate prima che compaia qualsiasi richiesta. Se la approva, la chiamata normalmente va comunque alla richiesta di permesso.
- Chiamate
SubagentHandback: questo strumento consegna il report di un subagent. Per esso non compare alcuna richiesta, e la chiamata viene eseguita anche se il classificatore si oppone.
SubagentHandback, restituisci "deny". Claude Code comunica quindi al subagent, fino a tre volte, che il suo report non è stato consegnato e che deve chiamare di nuovo lo strumento. Se il tuo hook continua a negare, il subagent termina senza consegnare un report tramite questo strumento, e la conversazione in attesa riceve una nota che lo segnala.
Strumenti che richiedono l’interazione dell’utente
AskUserQuestion e ExitPlanMode richiedono l’interazione dell’utente. In modalità non interattiva con il flag -p, Claude Code li offre solo quando l’esecuzione ha un host dei permessi che riceva la richiesta, come un callback canUseTool dell’Agent SDK.
Un hook PreToolUse soddisfa questo requisito quando fa quanto segue:
- Legge l’input dello strumento da stdin
- Raccoglie la risposta tramite la tua interfaccia utente
- Restituisce
permissionDecision: "allow"insieme aupdatedInputcontenente la risposta, così lo strumento viene eseguito senza chiedere conferma
"allow" non è sufficiente per questi strumenti.
Per AskUserQuestion, restituisci l’array questions originale e aggiungi un oggetto answers che associa il testo di ciascuna domanda alla risposta scelta. Questo output risponde a una domanda con React:
_meta["anthropic/requiresUserInteraction"] è più restrittivo: un hook non può saltare la sua richiesta di approvazione con "allow", con o senza updatedInput, perché Claude Code non può verificare che l’hook abbia raccolto l’interazione di cui lo strumento ha bisogno.
Differire una chiamata a uno strumento
"defer" è pensato per le integrazioni che eseguono claude -p come sottoprocesso e ne leggono l’output JSON, come un’app Agent SDK o un’interfaccia personalizzata costruita su Claude Code. Consente a quel processo chiamante di mettere in pausa Claude in corrispondenza di una chiamata a uno strumento, raccogliere input tramite la propria interfaccia e riprendere da dove si era interrotto.
Claude Code rispetta "defer" solo in modalità non interattiva con il flag -p, e solo quando Claude effettua una singola chiamata a uno strumento nel turno:
- Nelle sessioni interattive: registra un avviso e ignora il risultato dell’hook
- Più chiamate agli strumenti contemporaneamente:
"defer"viene ignorato con un avviso e lo strumento procede attraverso il normale flusso dei permessi
AskUserQuestion è il caso tipico: Claude vuole chiedere qualcosa all’utente, ma non c’è un terminale in cui rispondere. Un’esecuzione -p offre AskUserQuestion solo quando ha un host dei permessi, come uno strumento MCP che passi con --permission-prompt-tool, quindi avvia l’esecuzione con uno di essi. Il ciclo completo funziona così:
- Claude chiama
AskUserQuestion. L’hookPreToolUsesi attiva. - L’hook restituisce
permissionDecision: "defer". Lo strumento non viene eseguito. Il turno termina con un risultato che contienestop_reason: "tool_deferred", e la chiamata allo strumento in sospeso rimane nella trascrizione. - Il processo chiamante legge
deferred_tool_usedal risultato dell’SDK, presenta la domanda nella propria interfaccia utente e attende una risposta. - Il processo chiamante esegue
claude -p --resume <session-id>con lo stesso host dei permessi. La stessa chiamata allo strumento attiva di nuovoPreToolUse. - L’hook restituisce
permissionDecision: "allow"con la risposta inupdatedInput. Lo strumento viene eseguito e Claude continua.
deferred_tool_use contiene id, name e input dello strumento:
cleanupPeriodDays non la elimina, dopo 30 giorni per impostazione predefinita.
Se la risposta non è pronta quando riprendi, l’hook può restituire di nuovo "defer". Se hai inviato un prompt con quella ripresa, Claude risponde senza il risultato dello strumento e non esegue la chiamata. Riprendi senza un prompt finché l’hook non restituisce "allow" o "deny".
Per riprendere una sessione differita in plan mode, passa
--permission-prompt-tool insieme a --resume in modo che Claude Code possa presentare il piano per l’approvazione. Per le altre condizioni, consulta Riprendere in plan mode con -p. Richiede Claude Code v2.1.246 o successivo.Quando riprendi con -p, Claude Code non ripristina nessun’altra modalità di permesso memorizzata. Avvia l’esecuzione nella modalità di permesso in cui partirebbe una nuova esecuzione claude -p, quindi passa di nuovo --permission-mode o --dangerously-skip-permissions se la sessione rinviata ne usava uno.Riprendere quando uno strumento rinviato non è disponibile
Un risultato constop_reason: "tool_deferred_unavailable" indica che lo strumento di una chiamata rinviata non è disponibile nella sessione ripresa, ad esempio perché il suo server MCP non è connesso. Il tuo hook PreToolUse non si attiva, e il campo deferred_tool_use del risultato indica lo strumento.
Finché la chiamata è in sospeso, qualsiasi prompt che invii non raggiunge Claude e l’esecuzione termina con codice 1. Il campo result inizia con <tool> isn't available, so its deferred call didn't run. Esegui la chiamata, oppure scartala in modo che non venga eseguita:
- Per eseguire la chiamata: rendi disponibile lo strumento e riprendi di nuovo.
- Per scartare la chiamata: riprendi con un prompt e con
CLAUDE_CODE_DROP_UNAVAILABLE_DEFERRED_TOOLimpostata su1. Claude riceve un errore come risultato della chiamata e risponde al tuo prompt. Quando riprendi in seguito, nessuna chiamata è in sospeso.
tool_deferred_unavailable con un campo result vuoto, poi la risposta di Claude in un secondo risultato. Termina con codice 0 a meno che quella risposta non sia un errore. Se imposti la variabile e non invii alcun prompt, l’esecuzione scarta comunque la chiamata e termina con codice 1.
Prima della v2.1.319, Claude Code rispondeva a un prompt senza il risultato dello strumento e scartava la chiamata. Su quelle versioni, invia un nuovo prompt una volta che lo strumento è disponibile.
PermissionRequest
Viene eseguito quando Claude Code sta per chiederti il permesso di usare uno strumento. Nelle sessioni che non possono mostrare una richiesta, come i subagent in background in modalità non interattiva, Claude Code esegue comunque questi hook e, se nessun hook restituisce una decisione, nega la chiamata allo strumento. Per una chiamata che raggiunge un--permission-prompt-tool o il callback canUseTool dell’Agent SDK, gli hook vengono eseguiti insieme al tuo host, e si applica la decisione di chi decide per primo.
Usa il controllo delle decisioni di PermissionRequest per consentire o negare per conto dell’utente.
Usa questo evento quando hai bisogno di un segnale nel momento in cui Claude chiede il permesso di usare uno strumento. Claude Code esegue un hook Notification con il tipo permission_prompt solo dopo che la richiesta è rimasta in attesa per circa sei secondi.
Claude Code non esegue gli hook PermissionRequest per la richiesta di rete di un comando in sandbox. Per ottenere un segnale per quella richiesta, usa il tipo di notifica permission_prompt.
Corrisponde sul nome dello strumento, con gli stessi valori di PreToolUse.
Input di PermissionRequest
Gli hook PermissionRequest ricevono i campitool_name e tool_input come gli hook PreToolUse, ma senza tool_use_id. Per uno strumento MCP, ricevono anche l’oggetto mcp_server. Un array facoltativo permission_suggestions contiene gli aggiornamenti dei permessi che Claude Code suggerisce per questa richiesta, come l’aggiunta di una regola allow o la modifica della modalità di permesso.
L’array permission_suggestions non è un elenco esatto delle opzioni che vedi, perché ogni finestra di dialogo dei permessi costruisce le proprie opzioni. Alcune finestre di dialogo, come quella per le modifiche ai file, non leggono affatto l’array e ricavano le proprie opzioni dalla richiesta stessa. Una finestra di dialogo che lo legge può comunque nascondere un’opzione il cui suggerimento rimane nell’array, ad esempio quando allowManagedPermissionRulesOnly nasconde le opzioni per salvare le regole. Può anche offrire opzioni che non hanno una voce di suggerimento, come Yes, and switch to auto mode, che cambia direttamente la modalità di permesso anziché tramite un aggiornamento dei permessi.
Gli hook PreToolUse vengono eseguiti prima di ogni chiamata a uno strumento, che richieda o meno un permesso. Gli hook PermissionRequest vengono eseguiti solo quando Claude Code sta per chiederti un permesso, o quando altrimenti negherebbe automaticamente una chiamata che non può mostrare una richiesta. Nessuno dei due eventi si attiva per EndConversation.
Controllo delle decisioni di PermissionRequest
Gli hookPermissionRequest possono consentire o negare le richieste di permesso. Oltre ai campi di output JSON disponibili per tutti gli hook, lo script del tuo hook può restituire un oggetto decision con questi campi specifici dell’evento:
Per consentire o riscrivere un comando Monitor, consulta Corrispondenza dei comandi Monitor.
Un hook che termina con codice 2 senza un oggetto
decision lascia invariato il flusso dei permessi, e il suo stderr viene scartato. Per concedere o negare la richiesta, restituisci l’oggetto decision.
Voci di aggiornamento dei permessi
Il campo di outputupdatedPermissions e il campo di input permission_suggestions usano entrambi lo stesso array di oggetti voce. Ogni voce ha un type che determina gli altri campi e una destination che controlla dove viene scritta la modifica.
In
rules, per una regola di permesso scritta Tool(specifier), toolName è il nome dello strumento e ruleContent è lo specificatore:
Bash(npm test):{ "toolName": "Bash", "ruleContent": "npm test" }BashoBash(*):{ "toolName": "Bash" }, perché entrambi corrispondono all’intero strumentomcp__github__get_issue:{ "toolName": "mcp__github__get_issue" }
ruleContent in una regola allow per uno strumento MCP. Se lo aggiungi, la regola non corrisponde a nessuna chiamata.
setMode con bypassPermissions ha effetto solo se hai avviato la sessione con la modalità bypass già disponibile: --dangerously-skip-permissions, --permission-mode bypassPermissions, --allow-dangerously-skip-permissions oppure permissions.defaultMode: "bypassPermissions" nelle impostazioni utente, --settings o impostazioni gestite. Altrimenti l’aggiornamento non ha alcun effetto. L’aggiornamento non ha effetto neanche quando permissions.disableBypassPermissionsMode disabilita la modalità, o quando la sessione si avvia in modalità con restrizioni.bypassPermissions non viene mai salvato come defaultMode, indipendentemente da destination.destination di ogni voce determina se la modifica rimane in memoria o viene salvata in un file di impostazioni.
Un hook può restituire uno dei
permission_suggestions ricevuti come proprio output updatedPermissions.
PostToolUse
Viene eseguito immediatamente dopo che uno strumento è stato completato con successo. Corrisponde sul nome dello strumento, con gli stessi valori di PreToolUse. Usa una corrispondenza più ampia quando il nome dello strumento non è il filtro giusto:- Per eseguire un hook dopo che qualsiasi strumento è stato completato con successo, ometti il
matchero impostalo su"*". Il tuo hook può quindi scoprire da solo cosa è cambiato, ad esempio eseguendogit status --porcelain, che elenca anche i file non tracciati chegit diffnon rileva. Per le chiamate agli strumenti che falliscono, aggiungi lo stesso hook sotto PostToolUseFailure. - Per eseguire un hook quando un file specifico cambia su disco, indipendentemente da chi l’ha scritto, usa FileChanged. Claude Code non esegue un hook
PostToolUseche corrisponde aEdit|Writequando un comandoBasho un processo esterno a Claude Code riscrive lo stesso file.
PostToolUse dopo un’interruzione
Se un hookPostToolUse si arresta in anticipo dopo che invii un messaggio o interrompi durante una chiamata a uno strumento, verifica se hai premuto Ctrl+Enter, Enter o Esc:
Ctrl+Enter: se premerlo termina il turno mentre uno strumento è in esecuzione e lo strumento termina, i tuoi hookPostToolUsevengono eseguiti sul suo risultato e hanno 10 secondi per terminare. Il tasto agisce comeEscse hai messo in coda un comando!prima dei tuoi messaggi o se le attività in background sono disabilitate, ad esempio conCLAUDE_CODE_DISABLE_BACKGROUND_TASKS.Enter: un messaggio che metti in coda conEnternon interrompe il turno, quindi gli hook mantengono il lorotimeoutabituale.Esc: annulli immediatamente gli hook, quindi invia il messaggio conEnteroCtrl+Enterquando gli hook devono essere eseguiti.
timeout. Per consentire a un hook di tipo command più lungo di terminare, eseguilo con async: true, il che significa che l’hook non può bloccare o riscrivere il risultato.
Prima della v2.1.319, gli hook non si avviavano dopo che avevi interrotto il turno con un messaggio, e un hook in esecuzione veniva arrestato.
Input di PostToolUse
Gli hookPostToolUse si attivano dopo che uno strumento è già stato eseguito con successo. L’input include sia tool_input, gli argomenti inviati allo strumento, sia tool_response, il risultato restituito. Lo schema esatto di entrambi dipende dallo strumento. I percorsi in tool_input degli strumenti per i file arrivano nello stesso formato di PreToolUse: sempre assoluti, con i separatori nativi della piattaforma, quindi barre rovesciate su Windows. Per uno strumento MCP, l’input contiene anche l’oggetto mcp_server.
Controllo delle decisioni di PostToolUse
Gli hookPostToolUse possono fornire un feedback a Claude dopo l’esecuzione dello strumento. Oltre ai campi di output JSON disponibili per tutti gli hook, lo script del tuo hook può restituire questi campi specifici dell’evento:
L’esempio seguente sostituisce l’output di una chiamata
Bash. Il valore sostitutivo corrisponde alla struttura dell’output dello strumento Bash:
Annotare un risultato per il classificatore della modalità auto
RestituisciclassifierContext per inviare una breve nota sul risultato della chiamata allo strumento al classificatore della modalità auto anziché a Claude. La nota serve al classificatore per la revisione delle azioni successive. Il campo richiede Claude Code v2.1.236 o versioni successive.
L’esempio seguente indica al classificatore da dove proviene l’output di una query:
- Hook configurati in Claude Code: per gli hook provenienti da file di impostazioni, plugin, skill e frontmatter degli agenti, il classificatore tratta la nota come contesto non verificato fornito dall’applicazione. La nota non stabilisce mai l’intento dell’utente e, se afferma che hai approvato o richiesto qualcosa, il classificatore verifica tale affermazione confrontandola con i tuoi messaggi nella conversazione
- Callback in-process dell’Agent SDK: quando un’applicazione che incorpora Claude Code registra l’hook come callback del TypeScript SDK e restituisce la nota durante la sessione attiva, il classificatore può considerare come intento dell’utente una dichiarazione dell’utente riportata nella nota. Tale dichiarazione può soddisfare un requisito di consenso che il classificatore accetterebbe da un messaggio inviato da te, ma non rimuove mai un blocco che neanche un tuo messaggio potrebbe rimuovere. Dopo la ripresa di una sessione, Claude Code tratta le note ripristinate come contesto non verificato. Quando hook di entrambi i gruppi annotano la stessa chiamata, il classificatore tratta la nota combinata come non verificata
- Lunghezza: Claude Code limita le note per una singola chiamata a uno strumento a 2.000 caratteri e tronca il resto. Il limite è condiviso tra tutti gli hook che rispondono a quella chiamata
- Solo risposte sincrone: Claude Code ignora il campo nella risposta di un hook che viene eseguito in background, perché tale risposta arriva dopo che Claude Code ha registrato il risultato dello strumento
- Chiamate che il classificatore non registra: la trascrizione del classificatore omette le ricerche di sola lettura, come le letture di file e le ricerche. Claude Code scarta una nota associata a una di queste chiamate
- Interazione con le riscritture: quando la nota descrive un output che stai sostituendo con
updatedToolOutput, restituisci entrambi i campi nella stessa risposta dell’hook. Claude Code scarta la nota se la riscrittura viene rifiutata o se la riscrittura di un altro hook la sostituisce. Claude Code consegna una nota restituita senza una riscrittura anche quando un altro hook riscrive l’output
PostToolUseFailure
Viene eseguito quando uno strumento che ha iniziato l’esecuzione fallisce: lo strumento ha generato un errore, oppure uno strumento MCP ha restituito un risultato di errore. Usalo per registrare i fallimenti, inviare avvisi o fornire un feedback correttivo a Claude. Corrisponde sul nome dello strumento, con gli stessi valori di PreToolUse.Questo evento non si attiva per le chiamate agli strumenti rifiutate prima dell’esecuzione: un nome di strumento sconosciuto, un input che non supera la validazione dello schema o la validazione specifica dello strumento, oppure un permesso negato. I rifiuti per validazione vengono restituiti come risultati
tool_use_error e avvengono prima dell’esecuzione degli hook, quindi non attivano né PreToolUse né PostToolUseFailure. I permessi negati attivano PreToolUse ma non questo evento; vedi PermissionDenied.Input di PostToolUseFailure
Gli hook PostToolUseFailure ricevono gli stessi campitool_name e tool_input di PostToolUse, insieme alle informazioni sull’errore come campi di primo livello. Per uno strumento MCP, ricevono anche l’oggetto mcp_server. Ad esempio, un comando npm test fallito potrebbe fornire:
La stringa
error è generalmente lo stesso testo che Claude riceve come risultato dello strumento fallito. Il suo formato varia in base allo strumento e al tipo di fallimento. Basa il tuo hook su tool_name, is_interrupt e sulla prima riga Exit code N; tratta il resto della stringa come testo da visualizzare, non come un formato stabile.
- Per Bash e PowerShell, un comando che è stato eseguito ed è terminato produce una prima riga
Exit code N, seguita dall’eventuale output prodotto dal comando come un unico blocco con stdout e stderr intercalati - Un payload può anche contenere un semplice messaggio di fallimento senza la riga del codice di uscita, quando Claude Code non è riuscito ad avviare il processo della shell stesso
- Claude Code tronca al centro le stringhe lunghe attorno a un indicatore
... [N characters truncated] ...e può inserire righe proprie, comeCommand timed out after 2m 0s
Controllo delle decisioni di PostToolUseFailure
Gli hookPostToolUseFailure possono fornire contesto a Claude dopo il fallimento di uno strumento. Oltre ai campi di output JSON disponibili per tutti gli hook, lo script del tuo hook può restituire questi campi specifici dell’evento:
PostToolBatch
Viene eseguito una volta dopo che ogni chiamata a uno strumento in un batch è stata risolta, prima che Claude Code invii la richiesta successiva al modello.PostToolUse si attiva una volta per strumento, il che significa che si attiva in modo concorrente quando Claude effettua chiamate agli strumenti in parallelo. PostToolBatch si attiva esattamente una volta con l’intero batch, quindi è il punto giusto per inserire contesto che dipende dall’insieme degli strumenti eseguiti anziché da un singolo strumento. Non esiste un matcher per questo evento.
Input di PostToolBatch
Oltre ai campi di input comuni, gli hook PostToolBatch ricevonotool_calls, un array che descrive ogni chiamata a uno strumento nel batch:
tool_response contiene lo stesso contenuto che il modello riceve nel blocco tool_result corrispondente. Il valore è una stringa serializzata o un array di blocchi di contenuto, esattamente come lo strumento lo ha emesso. Per Read, ciò significa testo preceduto dai numeri di riga anziché il contenuto grezzo del file. Le risposte possono essere grandi, quindi analizza solo i campi di cui hai bisogno.
La struttura di
tool_response è diversa da quella di PostToolUse. PostToolUse passa l’oggetto Output strutturato dello strumento, come {filePath: "...", type: "create"} per Write; PostToolBatch passa il contenuto tool_result serializzato che vede il modello.Controllo delle decisioni di PostToolBatch
Gli hookPostToolBatch possono inserire contesto per Claude. Oltre ai campi di output JSON disponibili per tutti gli hook, lo script del tuo hook può restituire questi campi specifici dell’evento:
decision: "block" o continue: false arresta il ciclo agentico prima della successiva chiamata al modello. Il messaggio di blocco proviene dal reason o dallo stopReason JSON, oppure dallo stderr con codice di uscita 2. Lo vedi come avviso nella trascrizione, e rimane nella conversazione, quindi Claude lo vede quando la conversazione continua.
PermissionDenied
Viene eseguito quando la modalità auto nega una chiamata a uno strumento, anche quando la nega senza un verdetto del classificatore perché un controllo di sicurezza separato dalla modalità auto ha rifiutato la richiesta del classificatore stesso o la sua risposta non è stata analizzata correttamente. Questo hook si attiva solo in modalità auto: non viene eseguito quando neghi manualmente una finestra di dialogo dei permessi, quando un hookPreToolUse blocca una chiamata o quando una regola deny corrisponde. Usalo per registrare i rifiuti, regolare la configurazione o indicare al modello che può riprovare la chiamata allo strumento.
Corrisponde sul nome dello strumento, con gli stessi valori di PreToolUse.
Input di PermissionDenied
Oltre ai campi di input comuni, gli hook PermissionDenied ricevonotool_name, tool_input, tool_use_id e reason. Per uno strumento MCP, ricevono anche l’oggetto mcp_server.
Controllo delle decisioni di PermissionDenied
Gli hook PermissionDenied possono indicare al modello che può riprovare la chiamata allo strumento negata. Restituisci un oggetto JSON conhookSpecificOutput.retry impostato su true:
retry è true, Claude Code aggiunge alla conversazione un messaggio che indica al modello che può riprovare la chiamata allo strumento. Claude Code non annulla il rifiuto in sé. Se il tuo hook non restituisce JSON, o restituisce retry: false, il rifiuto resta valido e il modello riceve il messaggio di rifiuto originale.
Claude Code ignora retry: true quando il classificatore non ha prodotto alcun verdetto sull’azione: la sua risposta non è stata analizzata correttamente, oppure un controllo di sicurezza separato dalla modalità auto ha rifiutato la richiesta del classificatore stesso. Per questi rifiuti, Claude Code indica già al modello nel messaggio di rifiuto se riprovare più tardi o andare avanti.
Notification
Viene eseguito quando Claude Code invia notifiche. Corrisponde sul tipo di notifica. Ometti il matcher per eseguire gli hook per tutti i tipi di notifica. Ricevi questi eventi hook anche con le notifiche desktop disattivate: l’impostazionepreferredNotifChannel, incluso notifications_disabled, cambia solo il modo in cui vieni avvisato, non se il tuo hook viene eseguito.
I tipi
quota_auto_resume_fired, quota_auto_resume_stale e quota_auto_resume_disabled richiedono Claude Code v2.1.234 o successiva. Il tipo auth_storage_failure richiede v2.1.288 o successiva.
Nelle sessioni del terminale, permission_prompt per la richiesta di rete di un comando in sandbox richiede Claude Code v2.1.246 o successivo.
agent_needs_input per la domanda di configurazione del terminale di un compagno di team richiede Claude Code v2.1.248 o successivo.
I tipi
permission_prompt, idle_prompt, elicitation_dialog e elicitation_url_dialog condividono la tempistica con le notifiche desktop, quindi nelle sessioni del terminale li vedi solo quando sembri lontano dal terminale:- Aspettati
permission_promptuna volta che non digiti da circa sei secondi. Il timer parte quando compare la richiesta di permesso e ogni pressione di tasto lo rinvia. Per eseguire un hook immediatamente quando Claude chiede il permesso di usare uno strumento, usa invece PermissionRequest. - Aspettati
idle_promptcirca 60 secondi dopo che Claude ha finito di rispondere, e solo se da allora non hai digitato nulla e nessun agente in background, come un subagent in background, è ancora in esecuzione. Claude Code non inviaidle_promptmentre attende il ripristino di un limite di utilizzo di claude.ai. Quando l’attesa termina da sola, si attiva invece uno dei tipiquota_auto_resume_*. - Aspettati
elicitation_dialogper un modulo di elicitation, oelicitation_url_dialogper una richiesta di URL nel browser, una volta che non digiti da circa sei secondi. Entrambi condividono la stessa soglia di sei secondi dipermission_prompt: il timer parte quando compare la finestra di dialogo e ogni pressione di tasto lo rinvia.
permission_prompt in modo diverso nelle sessioni in cui invia le richieste di permesso alla callback canUseTool dell’Agent SDK, che è il modo in cui Claude Desktop e l’estensione VS Code ospitano Claude Code:
- Aspettati
permission_promptcirca sei secondi dopo che Claude chiede il permesso. Claude Code non lo rinvia mentre digiti. - Se tu o un hook PermissionRequest rispondete prima, Claude Code non esegue
permission_prompt. - Imposta
CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKSsu1per disattivarepermission_promptin queste sessioni.
permission_prompt non si attivava in queste sessioni.
Usa matcher separati per eseguire gestori diversi a seconda del tipo di notifica. Questa configurazione attiva uno script di avviso specifico per i permessi quando Claude ha bisogno di un’approvazione dei permessi e una notifica diversa quando Claude è inattivo:
Input di Notification
Oltre ai campi di input comuni, gli hook Notification ricevonomessage con il testo della notifica, un title facoltativo e notification_type che indica quale tipo si è attivato.
systemMessage e continue ma emette comunque terminalSequence, su cui si basa l’esempio di notifica desktop. Gli hook Notification sono pensati per effetti collaterali come l’inoltro della notifica a un servizio esterno.
SubagentStart
Viene eseguito quando Claude avvia un subagent con lo strumento Agent, quando Claude riprende un subagent e ogni volta che un compagno in-process di un team di agenti gestisce un nuovo messaggio. Supporta i matcher per filtrare in base al nome del tipo di agente. Per gli agenti integrati, è il nome dell’agente comegeneral-purpose, Explore o Plan. Per i subagent personalizzati, è il campo name del frontmatter dell’agente, non il nome del file.
Per i subagent forniti da un plugin, il tipo di agente è l’identificatore con ambito del plugin, come my-plugin:reviewer, non il semplice nome del frontmatter. I due punti fanno sì che un nome con ambito del plugin venga trattato come espressione regolare, quindi ancora il matcher con ^ e $ per una corrispondenza esatta: ^my-plugin:reviewer$.
Input di SubagentStart
Oltre ai campi di input comuni, gli hook SubagentStart ricevonoagent_id con l’identificatore univoco del subagent e agent_type con il nome dell’agente su cui filtra il matcher.
SubagentStop
Viene eseguito quando un subagent di Claude Code ha finito di rispondere. Corrisponde sul tipo di agente, con gli stessi valori di SubagentStart.Input di SubagentStop
Oltre ai campi di input comuni, gli hook SubagentStop ricevonostop_hook_active, agent_id, agent_type, agent_transcript_path e last_assistant_message. Il campo agent_type è il valore usato per il filtraggio del matcher. Il transcript_path è la trascrizione della sessione principale, mentre agent_transcript_path è la trascrizione del subagent stesso, archiviata in una cartella annidata subagents/. Il campo last_assistant_message contiene il testo della risposta finale del subagent, così gli hook possono accedervi senza analizzare il file della trascrizione.
Non tutti gli eventi SubagentStop provengono da un subagent avviato da Claude. Claude Code esegue anche agenti interni per alcune delle proprie funzionalità, come i suggerimenti di prompt e le domande laterali con /btw, e SubagentStop si attiva anche quando uno di questi termina. Per questi eventi, agent_type è il nome dell’agente con cui viene eseguita la sessione stessa, come quello impostato con --agent o con l’impostazione agent, ed è una stringa vuota quando la sessione viene eseguita senza di esso.
Un matcher che specifica tipi di agente non corrisponde a un agent_type vuoto. Un hook il cui matcher è omesso, "" o "*", oppure è un’espressione regolare che corrisponde a una stringa vuota, viene eseguito anche per gli eventi con un agent_type vuoto.
Su Claude Code v2.1.271 o successivo, un subagent eseguito con lo strumento SubagentHandback consegna il proprio report tramite quello strumento prima di arrestarsi. Il campo last_assistant_message contiene quindi l’eventuale testo conclusivo del subagent, che non è il report consegnato. Il report è l’input message di quella chiamata, che un hook PreToolUse o PostToolUse con corrispondenza su SubagentHandback riceve come tool_input.message.
Gli hook SubagentStop ricevono anche gli array background_tasks e session_crons descritti in Input di Stop. Entrambi gli array hanno come ambito la sessione padre, non il subagent.
hookSpecificOutput.additionalContext con hookEventName impostato su "SubagentStop", per un feedback non di errore che mantiene in esecuzione il subagent. Restituire decision: "block" con un reason mantiene in esecuzione il subagent e consegna reason al subagent come sua istruzione successiva. Un hook che blocca terminando con codice 2 consegna il proprio messaggio stderr allo stesso modo. Per inserire contesto nella sessione padre dopo che un subagent ha restituito il risultato, usa invece un hook PostToolUse sullo strumento Agent.
TaskCreated
Viene eseguito quando un task viene creato tramite lo strumentoTaskCreate. Usalo per imporre convenzioni di denominazione, richiedere descrizioni dei task o impedire la creazione di determinati task. In una sessione senza gli strumenti Task, questo evento non si attiva.
Gli hook TaskCreated non supportano i matcher e si attivano a ogni occorrenza.
Input di TaskCreated
Oltre ai campi di input comuni, gli hook TaskCreated ricevonotask_id, task_subject e, facoltativamente, task_description, teammate_name e team_name.
Controllo delle decisioni di TaskCreated
Un hook TaskCreated può bloccare la creazione con il codice di uscita 2 o con una decisione JSON. In entrambi i casi, Claude Code elimina il task e restituisce il tuo messaggio a Claude come errore dello strumento. Claude Code ignoracontinue: false da questo evento e Claude continua a lavorare.
- Codice di uscita 2: Claude Code restituisce il testo di stderr come messaggio.
- JSON
{"decision": "block", "reason": "..."}: Claude Code restituiscereasoncome messaggio.
TaskCompleted
Viene eseguito quando un task sta per essere contrassegnato come completato. Si attiva in due situazioni: quando un qualsiasi agente contrassegna esplicitamente un task come completato tramite lo strumento TaskUpdate, oppure quando un compagno di un team di agenti termina il proprio turno con task in corso. Usalo per imporre criteri di completamento, come il superamento dei test o dei controlli lint, prima che un task possa essere chiuso. Gli hook TaskCompleted non supportano i matcher e si attivano a ogni occorrenza.Input di TaskCompleted
Oltre ai campi di input comuni, gli hook TaskCompleted ricevonotask_id, task_subject e, facoltativamente, task_description, teammate_name e team_name.
Controllo delle decisioni di TaskCompleted
Con un hook TaskCompleted, puoi mantenere aperta l’attività o lasciare che un membro del team diventi inattivo:- Codice di uscita 2: il task non viene contrassegnato come completato e il messaggio stderr viene restituito al modello come feedback.
- JSON
{"decision": "block", "reason": "..."}: l’attività resta aperta. Claude ricevereasone continua a lavorare. - JSON
{"continue": false, "stopReason": "..."}: alla fine del turno di un membro del team, il membro diventa inattivo con l’attività ancora in corso, anche se un altro dei tuoi hook TaskCompleted blocca. LostopReasonappare nella trascrizione del membro del team. In una chiamataTaskUpdate, Claude Code ignoracontinue: false.
Stop
Viene eseguito quando l’agente principale di Claude Code ha finito di rispondere. Non viene eseguito se l’arresto è avvenuto a causa di un’interruzione da parte dell’utente. Gli errori API attivano invece StopFailure.Input di Stop
Oltre ai campi di input comuni, gli hook Stop ricevonostop_hook_active, last_assistant_message, background_tasks e session_crons. Il campo stop_hook_active è true quando Claude Code sta già proseguendo a seguito di uno stop hook. Controlla questo valore o elabora la trascrizione per evitare di bloccare su una condizione che non si risolverà mai.
Claude Code applica un limite di 8 prosecuzioni consecutive: dopo che gli stop hook hanno fatto proseguire il turno otto volte di seguito, Claude Code sovrascrive il blocco successivo e termina il turno. Il conteggio delle prosecuzioni consecutive si azzera ogni volta che Claude chiama uno strumento. Per aumentare il limite, imposta CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.
Il campo last_assistant_message contiene il testo della risposta finale di Claude, così gli hook possono accedervi senza analizzare il file della trascrizione. Per gli hook che agiscono sul turno appena completato, come gli hook di lettura ad alta voce o di notifica, usa questo campo anziché leggere transcript_path: non è garantito che il file della trascrizione includa il messaggio finale al momento di Stop in tutte le versioni.
Gli array background_tasks e session_crons permettono agli hook di distinguere tra “la sessione è terminata” e “la sessione è in pausa in attesa che un lavoro in background la riattivi”. Entrambi gli array sono presenti quando il registro dei task è raggiungibile e sono vuoti quando non c’è nulla in corso o pianificato.
Ogni voce in background_tasks descrive un task in corso e usa questi campi:
Ogni voce in
session_crons descrive una riattivazione pianificata con ambito di sessione, proveniente da CronCreate, ScheduleWakeup e /loop:
Questo esempio mostra un input di Stop con un task shell in corso e un cron ricorrente:
Controllo delle decisioni di Stop
Gli hookStop e SubagentStop possono controllare se Claude prosegue. Oltre ai campi di output JSON disponibili per tutti gli hook, lo script del tuo hook può restituire questi campi specifici dell’evento:
Un hook che blocca terminando con codice 2 viene instradato allo stesso modo di
reason: Claude riceve il messaggio stderr come spiegazione del motivo per cui deve proseguire.
additionalContext quando l’hook funziona come previsto e fornisce indicazioni a Claude, come “esegui la suite di test prima di terminare”. Mantiene attiva la conversazione con le stesse protezioni contro i cicli di decision: "block", ovvero l’input stop_hook_active e il limite di 8 prosecuzioni consecutive, ma la trascrizione lo etichetta come Stop hook feedback e non viene mostrata alcuna notifica di errore dell’hook:
StopFailure
Viene eseguito al posto di Stop quando il turno termina a causa di un errore API. Claude Code ignora l’output e il codice di uscita dell’hook, a parteterminalSequence. Usalo per registrare i fallimenti, inviare avvisi o intraprendere azioni di ripristino quando Claude non riesce a completare una risposta a causa di rate limit, problemi di autenticazione o altri errori API.
Input di StopFailure
Oltre ai campi di input comuni, gli hook StopFailure ricevonoerror, error_details facoltativo e last_assistant_message facoltativo. Il campo error identifica il tipo di errore e viene usato per il filtraggio del matcher.
TeammateIdle
Viene eseguito quando un compagno di un team di agenti sta per diventare inattivo dopo aver terminato il proprio turno. Usalo per imporre controlli di qualità prima che un compagno di team smetta di lavorare, ad esempio richiedendo il superamento dei controlli lint o verificando l’esistenza dei file di output. Gli hook TeammateIdle non supportano i matcher e si attivano a ogni occorrenza.Input di TeammateIdle
Oltre ai campi di input comuni, gli hook TeammateIdle ricevonoteammate_name e team_name.
Controllo delle decisioni di TeammateIdle
Con un hook TeammateIdle, puoi far continuare a lavorare il membro del team o lasciarlo diventare inattivo:- Codice di uscita 2: il membro del team riceve il messaggio stderr come feedback e continua a lavorare.
- JSON
{"decision": "block", "reason": "..."}: il membro del team ricevereasone continua a lavorare. - JSON
{"continue": false, "stopReason": "..."}: il membro del team diventa inattivo anche se un altro dei tuoi hook TeammateIdle blocca. LostopReasonappare nella trascrizione del membro del team.
ConfigChange
Viene eseguito quando un file di configurazione cambia durante una sessione. Usalo per verificare le modifiche alle impostazioni, applicare policy di sicurezza o bloccare modifiche non autorizzate ai file di configurazione. Claude Code esegue gli hook ConfigChange quando cambia un file di impostazioni, un file di policy gestita o un file di skill. Per le policy gestite, li esegue solo quando cambiamanaged-settings.json o un file in managed-settings.d/.
Il matcher filtra in base all’origine della configurazione:
Modifiche come queste hanno effetto senza eseguire gli hook:
- Regole e impostazioni che salvi con Yes, and don’t ask again,
/permissionso/model, nella sessione da cui le hai salvate. Se un’altra sessione aperta carica lo stesso file, gli hook vengono eseguiti lì. - Aggiornamenti alle impostazioni gestite dal server, alle preferenze gestite di macOS o ai criteri del registro di Windows
- Su WSL con
wslInheritsWindowsSettings, un file di impostazioni gestite lato Windows modificato, che Claude Code rileva durante il suo polling dei criteri
Input di ConfigChange
Oltre ai campi di input comuni, gli hook ConfigChange ricevonosource e, facoltativamente, file_path. Il campo source indica quale tipo di configurazione è cambiato, e file_path fornisce il percorso del file specifico che è stato modificato.
Controllo delle decisioni di ConfigChange
Gli hook ConfigChange possono impedire che le modifiche alla configurazione abbiano effetto. Usa il codice di uscita 2 o unadecision JSON per impedire la modifica. Quando viene bloccata, le nuove impostazioni non vengono applicate alla sessione in esecuzione.
policy_settings non possono essere bloccate. Gli hook si attivano comunque per le origini policy_settings quando cambia un file di impostazioni gestite sulla macchina, quindi puoi usarli per registrare tali modifiche, ma qualsiasi decisione di blocco viene ignorata. Ciò garantisce che le impostazioni gestite dall’azienda abbiano sempre effetto. Claude Code non esegue gli hook ConfigChange quando le impostazioni gestite dal server arrivano o vengono aggiornate.
Claude Code applica la decisione di blocco dall’output JSON di un hook ConfigChange e scarta systemMessage e continue. Una modifica bloccata non mostra alcun messaggio né a te né a Claude, sia che tu blocchi con reason sia con stderr e codice di uscita 2. Claude Code scrive solo una riga nel log di debug.
CwdChanged
Viene eseguito quando un comando della shell nella conversazione principale cambia la directory di lavoro, ad esempio quando Claude esegue un comandocd. Usalo per reagire ai cambi di directory: ricaricare le variabili d’ambiente, attivare toolchain specifiche del progetto o eseguire automaticamente script di configurazione. Si abbina a FileChanged per strumenti come direnv che gestiscono l’ambiente per directory.
Gli hook CwdChanged hanno accesso a CLAUDE_ENV_FILE. Se il tuo hook scrive variabili in quel file, queste persistono nei comandi Bash successivi fino al prossimo evento CwdChanged, quando Claude Code le cancella.
CwdChanged non supporta i matcher e si attiva a ogni occorrenza.
Input di CwdChanged
Oltre ai campi di input comuni, gli hook CwdChanged ricevonoold_cwd e new_cwd.
Output di CwdChanged
Oltre ai campi di output JSON disponibili per tutti gli hook, gli hook CwdChanged possono restituirewatchPaths per impostare dinamicamente quali percorsi di file vengono osservati da FileChanged:
Gli hook CwdChanged non hanno controllo delle decisioni. Non possono bloccare il cambio di directory.
Claude Code legge
watchPaths e systemMessage dal loro output JSON e scarta continue. Nelle sessioni interattive, mostra il systemMessage come breve notifica nel terminale. Il messaggio non raggiunge il flusso di messaggi dell’SDK.
DirectoryAdded
Viene eseguito dopo che aggiungi una directory di lavoro a sessione in corso con il comando/add-dir, o dopo che un client SDK ne aggiunge una con la richiesta di controllo register_repo_root. Usalo per preparare un repository appena aggiunto, ad esempio installandone le dipendenze.
Claude Code non attiva questo evento quando:
- Passi una directory con il flag di avvio
--add-dir; SessionStart copre queste directory - Aggiungi una directory nella scheda Workspace di
/permissions - Aggiungi una directory che è già una directory di lavoro o si trova all’interno di una
Input di DirectoryAdded
Oltre ai campi di input comuni, gli hook DirectoryAdded ricevonodirectory e source.
continue dal loro output JSON e gestisce il resto in modo diverso a seconda dell’origine:
slash_command: Claude Code consegna ilsystemMessagedell’hook a Claude come contesto nel turno successivo della conversazione, anziché mostrarlo a te. Nella trascrizione compare il conteggio degli hook falliti. L’output completo dei fallimenti va nel log di debugregister_repo_root: Claude Code scrive l’output disystemMessagee l’output dei fallimenti solo nel log di debug
FileChanged
Viene eseguito quando un file monitorato cambia sul disco. Claude Code rileva le modifiche con un watcher del filesystem, non esaminando le chiamate agli strumenti, quindi esegue l’hook indipendentemente da cosa abbia modificato il file: una chiamata allo strumentoEdit o Write, uno script che Claude esegue con Bash o un processo completamente esterno a Claude Code. Un uso comune è ricaricare le variabili d’ambiente quando cambiano i file di configurazione del progetto.
Il matcher per questo evento ha due ruoli:
- Creare l’elenco dei file monitorati: il valore viene suddiviso in corrispondenza di
|e ogni segmento viene registrato come nome di file letterale nella directory di lavoro, quindi".envrc|.env"monitora esattamente quei due file. I pattern regex non sono utili qui: un valore come^\.envmonitorerebbe un file chiamato letteralmente^\.env. - Filtrare quali hook vengono eseguiti: quando un file monitorato cambia, lo stesso valore filtra quali gruppi di hook vengono eseguiti usando le regole standard del matcher sul basename del file modificato.
data.csv dopo qualsiasi modifica, incluso un comando Bash o uno script esterno che riscrive il file:
file_path dell’input JSON su stdin. Il suo controllo con grep verifica la stessa cosa che perl rimuove, un CR alla fine di una riga, quindi l’esecuzione successiva a una normalizzazione termina senza toccare il file. Un controllo meno preciso entra in un ciclo infinito, perché perl -i riscrive il file anche quando non sostituisce nulla e Claude Code esegue di nuovo l’hook dopo ogni riscrittura. Salva questo script in /path/to/normalize-line-endings.sh e rendilo eseguibile:
data.csv con un comando Bash. Claude Code esegue l’hook e il file finisce con fine riga LF.
Per monitorare file che non puoi nominare in anticipo, restituisci watchPaths da un hook per aggiornare dinamicamente l’elenco dei file monitorati. Claude Code avvia il watcher solo quando qualcosa indica un file da monitorare, quindi inizializza l’elenco con un gruppo FileChanged il cui matcher nomina almeno un file, oppure con un hook SessionStart o CwdChanged che restituisce watchPaths. Il matcher filtra comunque quali gruppi di hook vengono eseguiti quando un file monitorato cambia, quindi ometti il matcher nel gruppo che gestisce i percorsi dinamici: così corrisponde a ogni file monitorato e non aggiunge nulla all’elenco. Anche un matcher "*" corrisponde a ogni file, ma Claude Code lo registra nell’elenco dei file monitorati come qualsiasi altro valore, cioè come un file chiamato letteralmente *.
Gli hook FileChanged hanno accesso a CLAUDE_ENV_FILE. Le variabili scritte in quel file persistono nei comandi Bash successivi fino al prossimo evento CwdChanged, quando Claude Code le cancella.
Input di FileChanged
Oltre ai campi di input comuni, gli hook FileChanged ricevonofile_path ed event.
Output di FileChanged
Oltre ai campi di output JSON disponibili per tutti gli hook, gli hook FileChanged possono restituirewatchPaths per aggiornare dinamicamente quali percorsi di file vengono monitorati:
Gli hook FileChanged non hanno controllo decisionale. Non possono impedire che la modifica del file avvenga.
Claude Code legge
watchPaths e systemMessage dal loro output JSON e scarta continue. Nelle sessioni interattive, mostra systemMessage come una breve notifica nel terminale. Il messaggio non raggiunge lo stream di messaggi dell’SDK.
WorktreeCreate
Viene eseguito quando Claude Code crea un worktree in casi come questi:- Avvii una sessione con
claude --worktree - Claude crea un worktree durante una sessione e ci passa con lo strumento
EnterWorktree - Un subagent usa
isolation: "worktree" - Un workflow esegue un agente nel proprio worktree
- Claude Code isola una sessione in background nel proprio worktree
claude remote-controlin modalitàworktreeavvia una sessione nel proprio worktree
--worktree e --tmux:
git worktree addtramite Bash: per ispezionare o bloccare quel comando, aggiungi un hookPreToolUsecon il matcherBash.--worktreecon--tmux: Claude Code crea il worktree prima di caricare i plugin, quindi un hook WorktreeCreate di un plugin non viene eseguito. Per far eseguire il tuo hook con entrambi i flag, definiscilo invece in un file di impostazioni. Prima della v2.1.300, l’hook WorktreeCreate di un plugin non veniva eseguito nemmeno con il solo--worktree.
git worktree. Configurare un hook WorktreeCreate sostituisce quel comportamento predefinito di git, permettendoti di usare un diverso sistema di controllo versione come SVN, Perforce o Mercurial.
Poiché l’hook sostituisce interamente il comportamento predefinito, .worktreeinclude non viene elaborato. Se devi copiare file di configurazione locali come .env nel nuovo worktree, fallo all’interno dello script del tuo hook.
L’hook deve restituire il percorso della directory del worktree creato. Claude Code usa questo percorso come directory di lavoro per la sessione isolata. Consulta Output di WorktreeCreate per sapere come ogni tipo di hook restituisce il percorso.
Claude Code agisce in base all’esito positivo dell’hook e al percorso restituito, e scarta systemMessage e continue.
Questo esempio crea una copia di lavoro SVN e stampa il percorso che Claude Code deve usare. Sostituisci l’URL del repository con il tuo:
name del worktree dall’input JSON su stdin, esegue il checkout di una copia nuova in una nuova directory e stampa il percorso della directory. L’echo nell’ultima riga è ciò che Claude Code legge come percorso del worktree. Reindirizza qualsiasi altro output su stderr in modo che non interferisca con il percorso.
Input di WorktreeCreate
Oltre ai campi di input comuni, gli hook WorktreeCreate ricevono il camponame. Si tratta di un identificatore slug per il nuovo worktree, specificato dall’utente o generato automaticamente, ad esempio bold-oak-a3f2.
Output di WorktreeCreate
Gli hook WorktreeCreate non usano il modello decisionale standard allow/block. L’esito dipende invece dal successo o dal fallimento dell’hook. L’hook deve restituire il percorso della directory del worktree creato:- Hook di tipo command (
type: "command"): stampa il percorso come ultima riga non vuota di stdout. Claude Code rimuove i codici di escape ANSI prima di leggere quella riga, quindi i banner di avvio della shell stampati prima del tuoechovengono ignorati. Reindirizza qualsiasi altro output dell’hook su stderr. - Hook HTTP (
type: "http"): restituisci{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }nel corpo della risposta.
. o .. al suo interno. Se il percorso risultante non è una directory in cui Claude Code può entrare, la sessione stampa un errore che indica il percorso e termina con codice 1.
Claude Code rifiuta un percorso assoluto che contiene segmenti . o .., e qualsiasi percorso che attraversa un collegamento simbolico sotto la radice del repository. L’errore indica il componente rifiutato. Un collegamento simbolico incluso in un commit del repository potrebbe reindirizzare il worktree al di fuori di esso. Restituisci un percorso normalizzato che non attraversi un collegamento simbolico all’interno del repository.
WorktreeRemove
Viene eseguito quando Claude Code ripulisce un worktree creato dal tuo hookWorktreeCreate. L’evento si attiva quando:
- Esci da una sessione worktree interattiva e scegli di rimuovere il worktree quando Claude Code te lo chiede
- Esci da una sessione worktree interattiva a cui non hai dato un nome, Claude Code non trova file modificati o non tracciati e rimuove il worktree senza chiedertelo
- Elimini una sessione in background che viene eseguita nel worktree
- Chiedi a Claude di uscire e rimuovere il worktree durante una sessione, e Claude lo rimuove con lo strumento
ExitWorktree - Una sessione avviata da
claude remote-controlin modalitàworktreetermina senza arresti anomali, e Claude Code non trova file modificati o non tracciati né nuovi commit nel suo worktree - Arresti
claude remote-controlmentre le sessioni che ha avviato in modalitàworktreesono ancora in esecuzione, e Claude Code non trova file modificati o non tracciati né nuovi commit nei loro worktree
ExitWorktree o per una pulizia di claude remote-control. ExitWorktree si rifiuta di rimuovere un worktree creato da un hook a meno che la chiamata non passi discard_changes: true, il che rende il tuo hook l’ultimo controllo su quel percorso.
Claude Code usa git per cercare file modificati o non tracciati, quindi non ne trova nessuno in un worktree che non è un checkout git né si trova all’interno di uno, anche quando la directory contiene lavoro non sottoposto a commit. Verifica la presenza di quel lavoro nel tuo hook WorktreeRemove prima che elimini qualcosa.
Per i worktree basati su git, Claude Code gestisce la pulizia automaticamente con git worktree remove. Se hai configurato un hook WorktreeCreate, abbinalo a un hook WorktreeRemove per controllare la pulizia:
- Nessun hook WorktreeRemove: Claude Code ripiega su git per una rimozione all’uscita o tramite
ExitWorktree, e mantiene il worktree quandoclaude remote-controlesegue la pulizia:- Esci da una sessione worktree, oppure Claude chiama
ExitWorktree: Claude Code rimuove il percorso restituito dal tuo hook WorktreeCreate come farebbegit worktree remove --force, quindi un worktree riconosciuto da git viene rimosso. Un worktree che git non riconosce, ad esempio uno creato dal tuo hook con un sistema di controllo versione diverso da git, rimane sul disco. claude remote-controlripulisce il worktree di una sessione: il worktree rimane sul disco, e il terminale che esegueclaude remote-controlmostraworktree removal failed, kept: <path>.- Elimini una sessione in background: consulta Cosa rimuove l’eliminazione di una sessione.
- Esci da una sessione worktree, oppure Claude chiama
- L’hook esce con 0: il worktree è considerato rimosso. Claude Code non legge nient’altro dall’hook, quindi assicurati che il tuo hook abbia eliminato la directory.
- L’hook esce con un codice diverso da zero: la rimozione fallisce se la directory in
worktree_pathesiste ancora dopo l’esecuzione, e il worktree rimane sul disco senza alcun fallback su git. Un hook che ha eliminato la directory prima di uscire con un codice diverso da zero è considerato come rimosso. Per sapere come viene segnalato l’errore, consulta Input di WorktreeRemove.
systemMessage e continue.
Per l’eliminazione di una sessione in background, Claude Code verifica il percorso del worktree memorizzato prima di eseguire l’hook, rifiutando un percorso che è un collegamento simbolico o che ne attraversa uno sotto la radice del repository. In quel caso, l’hook viene eseguito per un worktree che contiene ancora file solo quando confermi l’eliminazione nella vista agenti. Per un worktree di questo tipo, claude rm mantiene invece la sessione e il worktree.
Claude Code passa il percorso restituito da WorktreeCreate come worktree_path nell’input dell’hook. Questo esempio legge quel percorso e rimuove la directory:
Input di WorktreeRemove
Oltre ai campi di input comuni, gli hook WorktreeRemove ricevono il campoworktree_path, che è il percorso assoluto del worktree da rimuovere.
worktree_path esiste ancora dopo l’esecuzione, la rimozione fallisce:
- Se stavi eliminando una sessione in background, anche la sessione rimane. Il messaggio di rifiuto nella vista agenti riporta come è terminato l’hook, ad esempio
exited 1, cita l’inizio del suo stderr e indica se eliminando di nuovo la sessione la directory viene comunque rimossa. - Se
claude remote-controlstava ripulendo il worktree di una sessione, il terminale che lo esegue mostraworktree removal failed, kept: <path>.
PreCompact
Viene eseguito prima che Claude Code esegua un’operazione di compattazione. Il valore del matcher indica se la compattazione è stata attivata manualmente o automaticamente:
Esci con codice 2 per bloccare la compattazione. Per un
/compact manuale, il messaggio stderr viene mostrato all’utente. Puoi anche bloccare restituendo un JSON con "decision": "block".
Bloccare la compattazione automatica ha effetti diversi a seconda di quando si attiva. Se la compattazione è stata attivata in modo preventivo prima del limite di contesto, Claude Code la salta e la conversazione continua senza essere compattata. Se la compattazione è stata attivata per recuperare da un errore di limite di contesto già restituito dall’API, l’errore sottostante emerge e la richiesta corrente fallisce.
Claude Code scarta i campi systemMessage e continue di un hook PreCompact.
Input di PreCompact
Oltre ai campi di input comuni, gli hook PreCompact ricevonotrigger e custom_instructions. Per manual, custom_instructions contiene ciò che l’utente passa a /compact ed è null quando non passa nulla. Per auto, custom_instructions è null.
Output di PreCompact
Quando un hook PreCompact esce con 0 e non blocca, Claude Code usa il suo stdout come istruzioni per il riepilogo della compattazione. Mantieni quello stdout sotto i 10.000 caratteri per hook. Claude Code tronca l’output più lungo al limite e aggiunge un indicatore.PostCompact
Viene eseguito dopo che Claude Code completa un’operazione di compattazione. Usa questo evento per reagire al nuovo stato compattato, ad esempio per registrare il riepilogo generato o aggiornare uno stato esterno. Claude Code scarta i campisystemMessage e continue di un hook PostCompact.
Si applicano gli stessi valori del matcher di PreCompact:
Input di PostCompact
Oltre ai campi di input comuni, gli hook PostCompact ricevonotrigger e compact_summary. Il campo compact_summary contiene il riepilogo della conversazione generato dall’operazione di compattazione.
PreModelSwitch
Viene eseguito prima che Claude Code applichi un cambio di modello richiesto da te o da un client. Usalo per bloccare un cambio, richiedere una conferma o mostrare quanto costerà il cambio prima che avvenga. PreModelSwitch richiede Claude Code v2.1.251 o successiva. Claude Code lo esegue per queste richieste:/model <name>e il selettore di/model- Il selettore di modelli
Option+PoAlt+P - L’impostazione Model in
/config - L’attivazione della modalità veloce quando questa cambia il modello della sessione
- Una richiesta
set_model, o un cambio di modello in una richiestaapply_flag_settings, da un host dell’Agent SDK o da Remote Control
[1m]. Un alias come opus, un ID di modello con data e un ID specifico del provider come un ID di modello Amazon Bedrock corrispondono tutti all’unico nome canonico a cui si risolvono, quindi claude-opus-5 copre ogni variante di scrittura di Opus 5.
Quando Claude Code non riesce a determinare un nome canonico per il modello di destinazione, ad esempio un ID di modello personalizzato che solo il tuo gateway LLM conosce, esegue ogni hook PreModelSwitch indipendentemente dal matcher. Un hook che blocca dovrebbe quindi controllare to_model dal suo input invece di affidarsi solo al matcher.
Scrivi il matcher come nome esatto, come elenco separato da | come claude-opus-4-6|claude-opus-5, o come espressione regolare come .*opus.*. Questo esempio usa un matcher con nome esatto e controlla anche to_model dall’input dell’hook, quindi rifiuta un passaggio a Opus 4.6 uscendo con codice 2 e lascia passare qualsiasi altra destinazione:
- macOS/Linux
- Windows (PowerShell)
Il comando controlla
to_model con jq:/model claude-opus-4-6 da una sessione che usa un modello diverso. Claude Code mantiene il modello corrente e segnala che un hook PreModelSwitch ha bloccato il cambio, con il tuo messaggio come motivo.
Input di PreModelSwitch
Oltre ai campi di input comuni, gli hook PreModelSwitch ricevono i campi di questa tabella. Gli ultimi cinque descrivono quanto costa reinviare la conversazione al nuovo modello, così un hook può mostrare quella cifra prima che il cambio avvenga.
Questo esempio mostra l’input per
/model opus in una sessione che usa Sonnet 5:
Controllo decisionale di PreModelSwitch
Gli hookPreModelSwitch possono annullare il cambio, chiedere all’utente di confermarlo o lasciarlo procedere. Il codice di uscita 2 o un decision: "block" di primo livello annulla il cambio.
Per un controllo più preciso, restituisci permissionDecision e permissionDecisionReason in un oggetto hookSpecificOutput, come in PreToolUse. PreModelSwitch accetta "allow", "deny" e "ask". Non accetta "defer", updatedInput o additionalContext. La tabella seguente descrive entrambi i campi:
Solo
/model in una sessione interattiva può mostrare la richiesta di conferma di "ask". Su ogni altra superficie, inclusa la modalità non interattiva con il flag -p, /config e le richieste set_model, Claude Code tratta "ask" come un rifiuto.
Questo esempio chiede all’utente di confermare e cita il numero di token da context_tokens:
deny > ask > allow.
Claude Code mostra all’utente qualsiasi systemMessage restituito dal tuo hook indipendentemente dalla decisione, quindi un hook che riporta i costi può restituire {"systemMessage": "..."} e uscire con 0.
Timeout di PreModelSwitch e altri codici di uscita
Un hook PreModelSwitch che non risponde prima del suo timeout blocca il cambio. Il timeout predefinito per questo evento è di 30 secondi. Un codice di uscita diverso da 0 o 2 senza un output JSON valido è un errore non bloccante, quindi il cambio procede, tranne che per gli hook il cui fallimento lo blocca.PostModelSwitch
Viene eseguito dopo che il modello della sessione è cambiato. Usalo per dare a Claude indicazioni specifiche per il modello senza modificare ogni CLAUDE.md, ad esempio un’istruzione valida per tutta l’organizzazione che si applica a determinati modelli. PostModelSwitch richiede Claude Code v2.1.251 o successiva. Non può bloccare, perché il modello è già cambiato. Claude Code esegue gli hook PostModelSwitch dopo una qualsiasi di queste modifiche:- Un cambio richiesto da te o da un client
- Un fallback automatico del modello, che cambia il modello della sessione
- Un’impostazione come
opusplanche entra o esce dal plan mode - Il ripristino del modello da parte di Claude Code quando riprendi una sessione
/model opus da una sessione Sonnet, poi chiedi a Claude quali indicazioni ha riguardo al modello corrente.
Input di PostModelSwitch
Gli hook PostModelSwitch ricevono gli stessi campi di PreModelSwitch, conhook_event_name impostato su "PostModelSwitch" e due valori aggiuntivi di source: "auto" per un fallback automatico o un’altra modifica effettuata autonomamente da Claude Code, e "resume" per il modello ripristinato quando riprendi una sessione.
requested_model è null quando source è "auto". Quando source è "resume", è l’impostazione del modello salvata che Claude Code ha ripristinato.
Controllo decisionale di PostModelSwitch
Claude Code prende lo stdout in testo semplice del tuo hook all’uscita con 0, oppureadditionalContext dall’output JSON, e lo consegna a Claude con la richiesta successiva al cambio. Oltre ai campi di output JSON disponibili per tutti gli hook, puoi restituire:
Se l’hook non ha terminato entro cinque secondi dall’invio del prompt successivo, Claude Code invia quella richiesta senza l’output e lo allega invece alla richiesta seguente. Se il modello cambia più volte prima della richiesta successiva, Claude Code consegna solo l’output relativo al modello di destinazione dell’ultimo cambio.
SessionEnd
Viene eseguito quando una sessione di Claude Code termina. Utile per attività di pulizia, per registrare le statistiche della sessione o per salvare lo stato della sessione. Supporta i matcher per filtrare in base al motivo dell’uscita. Il camporeason nell’input dell’hook indica perché la sessione è terminata:
Input di SessionEnd
Oltre ai campi di input comuni, gli hook SessionEnd ricevono un camporeason che indica perché la sessione è terminata. Consulta la tabella dei motivi sopra per tutti i valori.
systemMessage.
Gli hook SessionEnd hanno un timeout predefinito di 1,5 secondi. Si applica quando esci, esegui /clear o cambi sessione con /resume interattivo. Puoi concedere più tempo a un hook in due modi:
timeoutper singolo hook: impostatimeoutnella configurazione di quell’hook. Il budget complessivo aumenta automaticamente per corrispondere altimeoutper singolo hook più alto nei tuoi file di impostazioni, fino a 60 secondi. Se aumenti il budget in questo modo, un hook senza un propriotimeoutmantiene comunque il valore predefinito. I timeout impostati sugli hook forniti dai plugin non aumentano il budget.CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS: imposta questa variabile d’ambiente in millisecondi per sovrascrivere esplicitamente il budget. Il valore che imposti diventa anche il timeout per ogni hook senza un propriotimeout.
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS aumentava solo il budget complessivo, e un hook senza un proprio timeout veniva comunque annullato dopo 1,5 secondi.
Elicitation
Viene eseguito quando un server MCP richiede un input all’utente durante un’attività. Per impostazione predefinita, Claude Code mostra una finestra di dialogo interattiva a cui l’utente risponde. Gli hook possono intercettare questa richiesta e rispondere in modo programmatico, saltando del tutto la finestra di dialogo. Per un hook completo con la relativa voce delle impostazioni e lo script, consulta Rispondere a una richiesta di modulo da uno script. Il campo matcher viene confrontato con il nome del server MCP.Input di Elicitation
Oltre ai campi di input comuni, gli hook Elicitation ricevonomcp_server_name, message e i campi facoltativi mode, url, elicitation_id e requested_schema.
Per l’elicitation in modalità form, il caso più comune:
Output di Elicitation
Un hook Elicitation può rispondere alla richiesta al posto dell’utente, rifiutarla o annullarla, oppure lasciarla alla finestra di dialogo. Per rispondere, rifiutare o annullare, esci con 0 e stampa un oggettohookSpecificOutput con un action. Il server riceve la tua risposta e non appare alcuna finestra di dialogo. Ogni riga di questa tabella mostra cosa restituire per un determinato esito e cosa riceve il server MCP:
Questo output risponde alla richiesta in modalità form mostrata in Input di Elicitation. Le chiavi in
content sono i nomi delle proprietà dal requested_schema di quella richiesta:
accept salta la finestra di dialogo, quindi l’URL non viene mai aperto.
Claude Code scarta reason, systemMessage e continue dall’output JSON di un hook Elicitation, qualunque sia l’action che restituisci.
Altri modi per rifiutare un’elicitation
Il tuo hook può anche rifiutare nei modi seguenti. Il server riceve lo stessodecline di "action": "decline":
- Esce con codice 2: Claude Code ignora un
hookSpecificOutputstampato dallo stesso hook - Stampa un
"decision": "block"di primo livello: il blocco ha la precedenza su unactionnello stesso output
accept o un cancel di un altro.
Questo script rifiuta le richieste in modalità URL e lascia le richieste di modulo alla finestra di dialogo:
reason.
Claude Code ha ignorato un decision di primo livello dagli hook Elicitation ed ElicitationResult dalla v2.1.105 fino alla correzione nella v2.1.284.
Rispondere a una richiesta di modulo da uno script
Questo esempio risponde a una domanda ricorrente al posto dell’utente. Un server MCP chiamatoissue-tracker chiede una chiave di progetto in un modulo, e l’hook inserisce DOCS. Lo script accetta quando project_key è l’unico campo del modulo. Per qualsiasi altra richiesta non stampa nulla, quindi appare la finestra di dialogo.
- macOS/Linux
- Windows (PowerShell)
Registra un hook di tipo command per l’evento nel tuo file di impostazioni, con il nome del server come matcher:Salva questo script in
.claude/hooks/answer-project-key.sh nel tuo progetto e rendilo eseguibile con chmod +x:claude --debug e assegna a Claude un’attività che porti il server a chiedere la chiave di progetto. Non compare alcuna finestra di dialogo e il log di debug contiene una riga con Elicitation resolved by hook: e accept.
ElicitationResult
Viene eseguito dopo che un utente risponde a un’elicitation MCP. Gli hook possono osservare, modificare o bloccare la risposta prima che venga rinviata al server MCP. Quando un hook Elicitation risponde a una richiesta, Claude Code invia quella risposta al server senza eseguire gli hook ElicitationResult. Il campo matcher viene confrontato con il nome del server MCP.Input di ElicitationResult
Oltre ai campi di input comuni, gli hook ElicitationResult ricevonomcp_server_name, action e i campi facoltativi mode, elicitation_id e content.
Output di ElicitationResult
Un hook ElicitationResult può lasciar passare la risposta dell’utente, modificarne i valori o bloccarla. Per modificare o bloccare la risposta, esci con 0 e stampa un oggettohookSpecificOutput con un action. Ogni riga di questa tabella mostra cosa restituire per un determinato esito e cosa riceve il server MCP:
Questo output modifica la risposta mostrata in Input di ElicitationResult, così il server riceve
alice@example.com dove l’utente ha inviato alice:
content sostituisce l’intero oggetto content dell’utente, quindi includi i campi che non stai modificando. Restituisci anche action, perché Claude Code ignora un hookSpecificOutput privo di action.
Gli hook ElicitationResult vengono eseguiti anche quando l’utente rifiuta o annulla, e il tuo action sostituisce il suo. Verifica che l’action dell’input sia accept prima di restituire accept, altrimenti il tuo hook trasforma una richiesta rifiutata in una accettata. Questo script applica la stessa modifica quando l’utente ha accettato, mantiene gli altri campi e non stampa nulla negli altri casi:
"decision": "block" di primo livello bloccano la risposta. Altri modi per rifiutare un’elicitation spiega quale ha effetto quando un hook li combina, cosa vede l’utente e quali versioni ignoravano decision.
Claude Code scarta reason, systemMessage e continue dall’output JSON di un hook ElicitationResult, qualunque sia l’action che restituisci.
Hook basati su prompt
Oltre agli hook di comando, HTTP e MCP tool, Claude Code supporta gli hook basati su prompt (type: "prompt") che utilizzano un LLM per valutare se consentire o bloccare un’azione, e gli hook basati su agenti (type: "agent") che generano un verificatore agentico con accesso agli strumenti. Non tutti gli eventi supportano ogni tipo di hook.
Gli eventi che supportano tutti e cinque i tipi di hook (command, http, mcp_tool, prompt e agent):
PermissionDeniedPostToolBatchPostToolUsePostToolUseFailurePreToolUseStopSubagentStopTaskCompletedTaskCreatedTeammateIdleUserPromptExpansionUserPromptSubmit
PermissionRequest supporta gli hook command, http, mcp_tool e prompt ma non gli hook agent. Se configuri un hook agent su questo evento, Claude Code lo salta e il flusso di autorizzazione procede invariato. Per consentire o negare da un hook, restituisci l’oggetto decisione da un hook di comando o HTTP.
Gli eventi che supportano gli hook command, http e mcp_tool ma non prompt o agent:
ConfigChangeCwdChangedDirectoryAddedElicitationElicitationResultFileChangedInstructionsLoadedMessageDisplayNotificationPostCompactPostModelSwitchPreCompactPreModelSwitchSessionEndStopFailureSubagentStartWorktreeCreateWorktreeRemove
Setup supporta solo gli hook command. SessionStart supporta solo gli hook command e mcp_tool, e i campi degli hook MCP tool descrivono quando i suoi hook mcp_tool vengono eseguiti.
Come funzionano gli hook basati su prompt
Invece di eseguire un comando Bash, gli hook basati su prompt:- Inviano l’input del hook e il prompt a un modello Claude, per impostazione predefinita quello che Claude Code utilizza per la funzionalità in background
- L’LLM risponde con JSON strutturato contenente una decisione
- Claude Code elabora automaticamente la decisione
Configurazione del prompt hook
Impostaretype su "prompt" e fornire una stringa prompt invece di un command. Utilizzare il segnaposto $ARGUMENTS per iniettare i dati di input JSON del hook nel testo del prompt.
In un hook di prompt o in un hook agente, puoi scrivere il prompt come una regola su cosa bloccare o consentire, ad esempio “Blocca qualsiasi comando Bash che legge file .env”, oppure come una condizione che deve essere soddisfatta, ad esempio “Tutti i test unitari passano”.
Questo hook Stop chiede all’LLM di valutare se tutti i compiti sono completi prima di consentire a Claude di terminare:
Schema di risposta
L’LLM deve rispondere con JSON contenente:
Ciò che accade con
ok: false dipende dall’evento:
StopeSubagentStop: il motivo viene reinviato a Claude come sua prossima istruzione e il turno continua, a meno che la risposta non imposti ancheimpossible: true, nel qual caso Claude Code consente lo stop e il turno terminaPreToolUse: la chiamata allo strumento viene negata; per impostazione predefinita il turno termina e il motivo della negazione appare nella chat come una riga di avviso. ImpostarecontinueOnBlock: trueper reinviare invece il motivo a Claude come errore dello strumento in modo che possa adattarsi e continuare, equivalente a un hook di comando conpermissionDecision: "deny"PostToolUse: per impostazione predefinita il turno termina e il motivo appare nella chat come una riga di avviso. ImpostarecontinueOnBlock: trueper reinviare il motivo a Claude e continuare il turno invecePostToolBatch,UserPromptSubmiteUserPromptExpansion: il turno termina e il motivo appare come una riga di avviso. Questi eventi terminano il turno sudecision: "block"indipendentemente dacontinuePostToolUseFailureeTaskCreated: il motivo viene restituito a Claude come errore dello strumento e il turno continua, indipendentemente dacontinueOnBlockTaskCompletedsu una chiamataTaskUpdate: Claude riceve il motivo come risultato dello strumento e il turno continua, indipendentemente dacontinueOnBlockTeammateIdle, eTaskCompletedalla fine del turno di un compagno di squadra: per impostazione predefinita il compagno di squadra diventa inattivo e il motivo appare nella sua trascrizione. ImpostacontinueOnBlock: trueper inviare il motivo al compagno di squadra e mantenerlo al lavoroPermissionRequest:ok: falsenon ha effetto. Per negare un’approvazione da un hook, utilizzare un hook di comando che restituiscehookSpecificOutput.decision.behavior: "deny"PermissionDenied:ok: falsenon ha effetto perché il rifiuto è già avvenuto. L’unico output che questo evento legge èhookSpecificOutput.retry, che gli hook di prompt e agenti non possono impostare. Vengono eseguiti su questo evento, ma il loro output viene scartato. Utilizzare un hook di comando per restituireretry
Controllare più condizioni prima di fermarsi
Questo hookStop utilizza un prompt dettagliato per controllare tre condizioni prima di consentire a Claude di fermarsi. Gli hook SubagentStop utilizzano lo stesso formato per valutare se un subagent dovrebbe fermarsi. Se il modello restituisce "ok": false perché la condizione non è ancora soddisfatta, Claude continua a lavorare con il motivo fornito come sua prossima istruzione:
Hook basati su agenti
Gli hook basati su agenti (type: "agent") sono come gli hook basati su prompt ma con accesso agli strumenti multi-turno. Invece di una singola chiamata LLM, un hook agente genera un subagent che può leggere file, cercare codice e ispezionare il codebase per verificare le condizioni. Gli hook agente supportano gli stessi eventi degli hook basati su prompt, ad eccezione di PermissionRequest.
Come funzionano gli hook basati su agenti
Quando un hook agente si attiva:- Claude Code genera un subagent con il prompt e l’input JSON del hook
- Il subagent può utilizzare strumenti come Read, Grep e Glob per investigare
- Dopo fino a 50 turni, il subagent restituisce una decisione strutturata
{ "ok": true/false } - Claude Code consente l’azione se
okètrue. Seokèfalse, Claude Code gestisce il blocco nello stesso modo di un hook di prompt concontinueOnBlock: truesu quell’evento, come elencato sotto Schema di risposta
Configurazione dell’hook agente
Impostaretype su "agent" e fornire una stringa prompt, utilizzando $ARGUMENTS come segnaposto per l’input JSON del hook. I campi di configurazione sono gli stessi degli hook di prompt, ad eccezione del fatto che gli hook agente hanno un timeout predefinito più lungo di 60 secondi e nessun campo continueOnBlock.
Lo schema di risposta è { "ok": true } per consentire o { "ok": false, "reason": "..." } per bloccare. Su ok: false, Claude Code gestisce un hook agente nello stesso modo in cui gestisce un hook di prompt con continueOnBlock: true sullo stesso evento; gli hook agente non hanno un campo continueOnBlock e non supportano il campo impossible dell’hook di prompt.
Questo hook Stop verifica che tutti i test unitari passino prima di consentire a Claude di finire:
Eseguire i hook in background
Per impostazione predefinita, gli hook bloccano l’esecuzione di Claude fino al completamento. Per le attività a lunga esecuzione come distribuzioni, suite di test o chiamate API esterne, impostare"async": true per eseguire l’hook in background mentre Claude continua a lavorare. Gli hook asincroni non possono bloccare o controllare il comportamento di Claude: i campi di risposta come decision, permissionDecision e continue non hanno effetto, perché l’azione che avrebbero controllato è già stata completata.
Configurare un hook asincrono
Aggiungere"async": true alla configurazione di un command hook per eseguirlo in background senza bloccare Claude. Questo campo è disponibile solo sui hook type: "command".
Questo hook esegue uno script di test dopo ogni chiamata dello strumento Write. Claude continua a lavorare immediatamente mentre run-tests.sh viene eseguito. Quando lo script termina, l’output viene consegnato al turno di conversazione successivo:
timeout su di esso. Claude Code continua ad applicare timeout su un hook che si esegue con asyncRewake.
Claude Code consegna i risultati di un hook asincrono solo mentre la sessione è in esecuzione:
- In modalità non interattiva con il flag
-p, Claude Code termina qualsiasi hook asincrono ancora in esecuzione al teardown e lo finalizza con esitocancelled - Se il lavoro del vostro hook deve sopravvivere a una sessione
claude -p, avviate un processo completamente staccato da esso
Come vengono eseguiti gli hook asincroni
Quando un hook asincrono si attiva, Claude Code avvia il processo del hook e continua immediatamente senza aspettare il completamento. L’hook riceve lo stesso input JSON tramite stdin di un hook sincrono. Dopo che il processo in background esce, Claude Code consegna i campiadditionalContext e systemMessage dalla risposta JSON dell’hook a Claude al turno di conversazione successivo, tranne che per l’output ripetuto di SessionStart. A differenza del systemMessage di un hook sincrono, nessuno dei due campi viene mostrato a te.
Stampa la risposta JSON da sola su stdout oppure su una riga a sé stante:
- Da sola su stdout: quando la risposta è l’unico testo su stdout, può estendersi su più righe, come l’output formattato di
jq. L’estensione su più righe richiede Claude Code v2.1.295 o versioni successive. - Su una riga a sé stante: un hook asincrono può stampare altro testo su stdout quando la risposta sta da sola su una riga, ad esempio con
jq -c.
systemMessage che non è una stringa, invece di consegnarlo. Esegui con --debug per vedere un avviso che nomina ogni campo scartato.
Le notifiche di completamento degli hook asincroni sono soppresse per impostazione predefinita. Per vederle, abilitare la modalità verbose con Ctrl+O o avviare Claude Code con --verbose.
Eseguire i test dopo le modifiche ai file
Questo hook avvia una suite di test in background ogni volta che Claude scrive un file, quindi segnala i risultati a Claude quando i test terminano. Salvare questo script in.claude/hooks/run-tests-async.sh nel progetto e renderlo eseguibile con chmod +x:
.claude/settings.json nella radice del progetto. Il flag async: true consente a Claude di continuare a lavorare mentre i test vengono eseguiti:
Limitazioni
Gli hook asincroni hanno vincoli aggiuntivi rispetto agli hook sincroni:- L’output del hook viene consegnato al turno di conversazione successivo. Se la sessione è inattiva, la risposta attende fino alla prossima interazione dell’utente. Eccezione: un hook
asyncRewakeche esce con il codice 2 riattiva Claude immediatamente anche quando la sessione è inattiva. - Ogni esecuzione crea un processo in background separato.
- Un hook
SessionStartasincrono viene eseguito ogni volta che l’evento si attiva. Claude Code salta l’output dell’hook quando il testo diadditionalContextesystemMessagecorrisponde a quello che Claude ha ricevuto l’ultima volta da quell’hook, a meno che nel frattempo un hookSessionStartsincrono non abbia aggiunto altro testo. Claude Code consegna il testo quando cambia, e di nuovo la volta successiva in cui l’hook viene eseguito dopo una compattazione o/clear. Prima della v2.1.295, Claude Code aggiungeva di nuovo lo stesso testo alla conversazione a ogni ripresa.
Considerazioni sulla sicurezza
Disclaimer
Fiducia nell’area di lavoro
Claude Code verifica la fiducia nell’area di lavoro prima di eseguire qualsiasi hook da un file di impostazioni. Ciò che conta come attendibile dipende dal tipo di sessione:- Sessione interattiva: Claude Code trattiene i hook da ogni file di impostazioni, incluso il vostro
~/.claude/settings.json, fino a quando non accettate la finestra di dialogo di fiducia nell’area di lavoro per la cartella, o per una directory padre la cui fiducia si estende ad essa - Sessione
-po SDK: Claude Code non mostra mai la finestra di dialogo e tratta la cartella come attendibile, quindi i hook sottoposti a commit nel.claude/settings.jsondi un repository vengono eseguiti in una cartella che non avete mai considerato attendibile
claude -p su un repository che non avete scritto, rivedete i file di impostazioni .claude/, iniziate con --bare, o disattivate i hook per quella esecuzione con --settings '{"disableAllHooks": true}'. I hook nel frontmatter in un subagent di progetto seguono una regola più ristretta rispetto ai hook dei file di impostazioni. Ciò che viene eseguito prima di considerare attendibile una cartella elenca ogni tipo di contenuto del repository per tipo di sessione.
Migliori pratiche di sicurezza
Tenere presenti queste pratiche quando si scrivono i hook:- Convalidare e disinfettare gli input: non fidarsi mai ciecamente dei dati di input
- Citare sempre le variabili shell: utilizzare
"$VAR"non$VAR - Bloccare l’attraversamento del percorso: controllare
..nei percorsi dei file - Utilizzare percorsi assoluti: specificare percorsi completi per gli script. Nel modulo exec, utilizzare
${CLAUDE_PROJECT_DIR}e il percorso non necessita di virgolette. Nel modulo shell, racchiuderlo tra virgolette doppie - Saltare i file sensibili: evitare
.env,.git/, chiavi, ecc.
Strumento Windows PowerShell
Su Windows, è possibile eseguire singoli hook in PowerShell impostando"shell": "powershell" su un command hook. Claude Code rileva automaticamente pwsh.exe, l’eseguibile di PowerShell 7 e versioni successive, e ricade su powershell.exe per Windows PowerShell 5.1.
Fare riferimento agli script tramite percorso negli hook PowerShell
Per fare riferimento alla directory radice del progetto da un comando in forma shell di PowerShell, scrivi${CLAUDE_PROJECT_DIR} o $env:CLAUDE_PROJECT_DIR. Claude Code riscrive i segnaposti ${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_ROOT} e ${CLAUDE_PLUGIN_DATA} in un comando in forma shell di PowerShell nella forma ${env:NAME} di PowerShell, indipendentemente dal fatto che l’hook sia definito in settings.json, un plugin o una skill. PowerShell quindi risolve il valore dall’ambiente esportato dopo l’analisi, quindi il segnaposto funziona all’interno di stringhe tra virgolette doppie ma non all’interno di stringhe tra virgolette singole, dove PowerShell non espande mai le variabili.
Non scrivere la forma nuda $CLAUDE_PROJECT_DIR in un hook di PowerShell. PowerShell la analizza come una variabile locale non definita e la risolve in $null, il che lascia il percorso dello script senza il prefisso della directory radice del progetto. Claude Code non riscrive quella forma; invece registra un avviso nel log di debug.
L’esempio seguente mostra un hook settings.json che esegue uno script di progetto con la forma $env::
Debug dei hook
I dettagli dell’esecuzione dei hook vengono scritti nel file di log di debug. Avviare Claude Code conclaude --debug-file <path> per scrivere il log in una posizione nota, oppure eseguire claude --debug e leggere il log in ~/.claude/debug/<session-id>.txt. Il flag --debug non stampa nel terminale.
Ad esempio, un hook PostToolUse su Write il cui comando stampa hook-ran produce voci come:
Hooks: che terminano con una durata. In Claude Code v2.1.296 o versioni successive, ogni hook di comando su un evento di strumento, UserPromptSubmit, SessionStart, Stop e diversi altri eventi ne lascia una quando termina, indipendentemente da ciò che ha stampato. La riga riporta il nome dell’evento, unito con i due punti al nome dello strumento o a un altro valore su cui l’hook ha trovato corrispondenza, quindi il comando dell’hook tra parentesi quadre, il plugin da cui proviene se presente, come si è conclusa l’esecuzione e quanto tempo ha impiegato, come in Hooks: PostToolUse:Write [.claude/hooks/log-write.sh] finished with status 0 (31ms). Un’esecuzione può anche concludersi con timed out after <N>ms, cancelled, moved to the background o failed to start. Su alcuni eventi, come Notification, SessionEnd e PreCompact, un hook di comando lascia invece una riga completed with status senza durata.
Per dettagli di corrispondenza dei hook più granulari, impostare CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose per visualizzare righe di log aggiuntive come i conteggi dei matcher del hook e la corrispondenza delle query.
Per la risoluzione dei problemi comuni come i hook che non si attivano, i Stop hook che continuano a bloccare, o gli errori di configurazione, consultare Limitations and troubleshooting nella guida. Per una procedura diagnostica più ampia che copre /context, /doctor e la precedenza delle impostazioni, consultare Debug your config.