Riepilogo rapido: I hook di Claude Code sono script di automazione che vengono eseguiti in specifici punti del ciclo di vita durante le sessioni di codifica AI, consentendo agli sviluppatori di eseguire comandi personalizzati, convalidare azioni, formattare codice, inviare notifiche e applicare regole del progetto. Questi hook si integrano con il flusso di lavoro di Claude tramite eventi come SessionStart, PreToolUse e PostToolUse, supportando schemi di esecuzione basati su comandi, HTTP e prompt con timeout configurabili e comportamento del codice di uscita.
Il sistema di hook di Claude Code trasforma l'assistente di codifica AI da uno strumento utile a un ambiente di sviluppo completamente automatizzato. La maggior parte degli sviluppatori non si rende conto dell'entità del controllo disponibile tramite gli hook.
Ecco la cosa, però: gli hook non servono solo a eseguire script dopo le modifiche ai file. Forniscono punti di intercettazione durante l'intero processo decisionale di Claude. Prima che esegua un comando. Dopo che una chiamata a uno strumento è fallita. Quando ha bisogno di un permesso. Persino prima di elaborare i prompt degli utenti.
Questa guida copre tutto ciò che la documentazione ufficiale fornisce, oltre a pattern pratici che le discussioni della community rivelano funzionare effettivamente in ambienti di produzione.
Cosa fanno effettivamente gli hook di Claude Code
Secondo la documentazione ufficiale di Claude Code, gli hook sono comandi shell definiti dall'utente, endpoint HTTP o injection di prompt che vengono eseguiti in punti specifici del ciclo di vita di Claude Code. Ricevono input JSON strutturati tramite stdin e controllano il flusso di lavoro tramite codici di uscita o risposte HTTP.
L'automazione va più a fondo di quanto suggeriscano la maggior parte delle guide. Gli hook possono bloccare completamente l'esecuzione degli strumenti, iniettare contesto aggiuntivo nel ragionamento di Claude, attivare servizi esterni e applicare regole di convalida che Claude deve rispettare.
Esistono tre tipi principali di hook:
- Hook di comando: script shell che comunicano tramite stdout, stderr e codici di uscita
- Hook HTTP: endpoint remoti che ricevono richieste POST e restituiscono risposte JSON
- Hook di prompt: istruzioni dinamiche iniettate nel contesto di Claude in eventi specifici
Ogni tipo serve a diversi pattern di automazione. Gli hook di comando gestiscono la convalida e la formattazione locale. Gli hook HTTP si integrano con servizi e database esterni. Gli hook di prompt modificano il comportamento di Claude senza processi esterni.
Ciclo di vita degli hook e sistema di eventi
La documentazione ufficiale definisce molteplici eventi di hook (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification e altri) che vengono attivati durante il flusso di esecuzione di Claude Code. Comprendere quando ciascuno viene attivato determina quale automazione diventa possibile.
| Evento | Quando viene attivato | Può bloccare |
|---|---|---|
| SessionStart | Quando una sessione inizia o riprende | No |
| UserPromptSubmit | Quando si invia un prompt, prima che Claude lo elabori | Sì |
| PreToolUse | Prima che venga eseguita una chiamata a uno strumento | Sì |
| PermissionRequest | Quando compare una finestra di dialogo di autorizzazione | Sì |
| PostToolUse | Dopo che una chiamata a uno strumento ha avuto successo | No |
| PostToolUseFailure | Dopo che una chiamata a uno strumento è fallita | No |
| Notification | Quando Claude Code invia una notifica | No |
| SubmitMessage | Quando Claude invia un messaggio all'utente | No |
| ContextCompaction | Quando la finestra di contesto si avvicina ai limiti | No |
La capacità di blocco è la cosa più importante. Gli hook PreToolUse possono impedire operazioni pericolose prima che vengano eseguite. Il codice di uscita 1 blocca l'azione. Il codice di uscita 0 la consente. Il codice di uscita 2 chiede a Claude di riconsiderare.
Ma aspetta. Gli hook PostToolUse non possono annullare le azioni poiché lo strumento è già stato eseguito. Questa limitazione modella come viene strutturata la logica di convalida. I controlli critici appartengono a PreToolUse. La pulizia e la formattazione appartengono a PostToolUse.
Sfoglia i vantaggi degli strumenti AI durante la configurazione di Claude Code
Se stai lavorando con gli hook di Claude Code, potresti anche scegliere altri strumenti AI nel tuo flusso di lavoro. Get AI Perks raccoglie crediti di startup e sconti software per strumenti AI e cloud in un unico posto. La piattaforma include oltre 200 offerte, con condizioni di vantaggio e guida per richiederle per ciascuna.
Cerchi vantaggi per Claude o altri strumenti AI?
Controlla Get AI Perks per:
- sfogliare offerte per Claude e altri strumenti AI
- confrontare le condizioni di vantaggio prima di fare domanda
- trovare sconti per startup su tutto lo stack di strumenti
👉 Visita Get AI Perks per esplorare i vantaggi attuali del software AI.
Configurazione e struttura dei file
Gli hook sono definiti nel file .claude/settings.json all'interno di un progetto. Lo schema di configurazione supporta hook globali e matcher specifici per gli strumenti che filtrano quando gli hook vengono eseguiti.
Struttura di base di un hook di comando:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
La variabile ${file} si espande nel percorso effettivo del file dall'input dello strumento. Secondo la documentazione ufficiale, gli hook supportano queste espansioni di variabili nei campi command e args.
Gerarchia di localizzazione degli hook
Claude Code controlla più posizioni per le definizioni degli hook, con un chiaro ordine di precedenza:
- A livello di progetto: .claude/settings.json nell'area di lavoro corrente
- A livello utente: ~/.claude/settings.json per tutte le sessioni
- Forniti da plugin: hook inclusi nei plugin installati
Gli hook di progetto sovrascrivono gli hook utente per lo stesso evento. Ciò consente regole di formattazione specifiche del progetto mantenendo gestori di notifiche globali.
Pattern di corrispondenza per esecuzione selettiva
Il sistema di corrispondenza filtra gli hook per strumenti o condizioni specifiche. Senza matcher, gli hook vengono attivati per ogni occorrenza del loro evento.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Il campo pathPattern accetta la sintassi glob. Il campo toolName corrisponde agli strumenti integrati di Claude come edit_file, execute_command, read_file e create_directory.
Le discussioni della community rivelano che le combinazioni di matcher funzionano con logica AND. Tutti i matcher specificati devono corrispondere affinché l'hook venga eseguito.
Hook di comando: Integrazione di script shell
Gli hook di comando eseguono comandi o script shell con input JSON strutturato. Rappresentano il tipo di hook più comune per l'automazione locale.
La documentazione ufficiale specifica che gli hook di comando ricevono JSON tramite stdin con questa struttura:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Gli script analizzano questo input per prendere decisioni. Un hook di convalida Python potrebbe apparire così:#!/usr/bin/env python3 import sys import json input_data = json.load(sys.stdin) tool_input = input_data.get(‘toolInput’, {}) file_path = tool_input.get(‘path’, ”) if file_path.startswith(‘protected/’): print(“Cannot edit protected files”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Il codice di uscita 0 consente l'operazione. Il codice di uscita 1 la blocca e mostra il messaggio stderr a Claude. Il codice di uscita 2 attiva un comportamento speciale a seconda dell'evento.
Comportamento del codice di uscita 2
Secondo la documentazione ufficiale di riferimento degli hook, il codice di uscita 2 ha un significato specifico dell'evento (PreToolUse: blocca e chiede riconsiderazione; UserPromptSubmit: fornisce contesto senza bloccare; PermissionRequest: blocca l'autorizzazione):
- PreToolUse: Blocca lo strumento e chiede a Claude di riconsiderare con il messaggio stderr come contesto
- UserPromptSubmit: Fornisce l'output stderr come contesto aggiuntivo senza bloccare
- PermissionRequest: Blocca la concessione dell'autorizzazione
Ciò crea una via di mezzo tra il blocco rigido e la consentita. Claude riceve feedback sul motivo per cui l'azione potrebbe essere problematica e può adeguare il suo approccio.
Hook di comando asincroni
Il flag async: true esegue gli hook in background senza bloccare il flusso di lavoro di Claude. Ciò è importante per operazioni lente come notifiche di distribuzione o raccolta di metriche.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Quando viene attivato un hook asincrono, Claude Code avvia il processo e prosegue immediatamente. Il campo timeout imposta il tempo massimo di esecuzione in secondi. Se non specificato, gli hook asincroni utilizzano un timeout predefinito di 10 minuti.
Parlando francamente: gli hook asincroni non possono bloccare le operazioni poiché vengono eseguiti dopo che Claude procede. Funzionano per il logging, le notifiche e la pulizia, non per la convalida.
Hook HTTP: Integrazione di servizi esterni
Gli hook HTTP inviano payload JSON a endpoint remoti e analizzano le risposte per il controllo delle decisioni. Consentono l'integrazione con servizi di convalida, database e strumenti di terze parti.
Configurazione di base di un hook HTTP:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
La struttura del payload corrisponde all'input del hook di comando ma arriva come corpo POST HTTP. La risposta determina la prossima azione di Claude.
Gestione delle risposte HTTP
Secondo la documentazione ufficiale, gli hook HTTP interpretano le risposte in base al codice di stato e al contenuto del corpo:
| Codice di stato | Effetto | Origine del messaggio |
|---|---|---|
| 200 | Consente l'operazione | Corpo della risposta (facoltativo) |
| 400 | Blocca l'operazione | Corpo della risposta mostrato a Claude |
| 500 | Errore di hook, consente l'operazione | Registrato ma non mostrato a Claude |
| Altro | Consente l'operazione | Il fallimento dell'hook non blocca il flusso di lavoro |
Il corpo della risposta può includere un campo di messaggio che Claude vede come contesto. Ciò consente ai servizi di convalida di spiegare perché un'operazione è stata bloccata.
Interpolazione di variabili d'ambiente
Gli hook HTTP supportano la sintassi ${VAR} in url, header e altri campi stringa. Le variabili vengono espanse dall'ambiente in cui viene eseguito Claude Code.
Secondo la documentazione ufficiale di MCP, l'espansione delle variabili d'ambiente include una sintassi di fallback predefinita: ${VAR:-default} si espande in VAR se impostato, altrimenti utilizza il valore predefinito.
Vincolo di sicurezza: secondo il problema di GitHub #28044, gli hook HTTP possono accedere solo alle variabili d'ambiente esplicitamente elencate nel campo di configurazione allowedEnvVars. Ciò impedisce l'esposizione accidentale di credenziali.
Hook di prompt: Iniezione di contesto
Gli hook di prompt iniettano istruzioni dinamiche nel contesto di Claude in eventi specifici. Modificano il comportamento senza processi esterni o chiamate API.
| { “event”: “SessionStart”, “prompt”: “Stai lavorando su un progetto TypeScript. Usa sempre controlli strict null e preferisci async/await alle promise.” } |
Il testo iniettato diventa parte delle istruzioni di sistema di Claude per quella sessione. Gli hook di prompt possono anche utilizzare variabili di template che si espandono in base ai dati dell'evento.
Generazione dinamica di prompt
Secondo la documentazione ufficiale, gli hook di prompt supportano campi di comando che generano prompt dinamici:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Il comando riceve l'input JSON standard tramite stdin e produce il testo del prompt in stdout. Ciò consente la generazione di istruzioni consapevoli del contesto basata sullo stato del progetto.
Hook basati su agenti
Gli hook di agenti specificano un sottoagente che gestisce l'evento invece dell'iniezione diretta di prompt. Il sottoagente riceve contesto sull'evento e può eseguire ragionamenti multi-passo.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Una chiamata a uno strumento è fallita. Analizza l'errore e suggerisci correzioni.” } |
Il sottoagente denominato deve essere definito nella configurazione del progetto. Gli hook di agenti consentono una logica decisionale complessa che la semplice iniezione di prompt non può fornire.
Pattern pratici di hook
Le discussioni della community e gli esempi ufficiali rivelano specifici pattern di automazione che funzionano in modo affidabile in produzione.
Formattazione automatica del codice dopo le modifiche
Il pattern più comune formatta il codice automaticamente dopo che Claude ha modificato i file:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
La variabile ${toolInput.path} si espande nel percorso del file modificato. PostToolUse garantisce che la formattazione avvenga dopo modifiche riuscite ma non blocchi il flusso di lavoro di Claude.
Blocca modifiche ai file protetti
Gli hook PreToolUse applicano le regole di protezione dei file:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Lo script convalida il percorso di destinazione rispetto ai pattern protetti ed esce con codice 1 per bloccare le modifiche proibite.
Ricevi notifiche quando Claude necessita di input
Secondo la guida ufficiale sul flusso di lavoro, gli hook di notifica possono attivare avvisi desktop o inviare messaggi a servizi esterni:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Questo viene attivato ogni volta che Claude Code invia una notifica, incluso quando attende l'input dell'utente o dopo il completamento di un'attività.
Re-inietta il contesto dopo la compattazione
Gli hook ContextCompaction ripristinano il contesto importante quando la finestra di conversazione si riempie:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
L'output del comando viene re-iniettato nel contesto di Claude dopo che la compattazione rimuove i messaggi precedenti. Ciò impedisce la perdita di istruzioni critiche specifiche del progetto.
Audit delle modifiche alla configurazione
Tieni traccia di quando Claude modifica i file di configurazione:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
L'esecuzione asincrona impedisce di bloccare Claude mentre le operazioni git vengono completate. Ciò crea una traccia di audit delle modifiche di configurazione senza staging manuale.
Output JSON e controllo delle decisioni
Gli hook di comando possono produrre JSON strutturato per fornire feedback dettagliato oltre ai semplici codici di uscita. Secondo il riferimento ufficiale, l'output JSON consente risposte multi-campo che Claude interpreta per il processo decisionale.
| { “allowed”: false, “message”: “Questo file è protetto dalla policy del team”, “suggestion”: “Crea un nuovo file in src/features/ invece” } |
Il campo allowed controlla se l'operazione procede. Il messaggio appare a Claude come contesto. Il campo suggestion fornisce approcci alternativi.
Affinché gli hook producano JSON, devono:
- Scrivere JSON valido su stdout
- Uscire con codice 0 (per consentito) o 1 (per bloccato)
- Includere almeno il campo booleano allowed
Claude Code analizza il JSON e lo utilizza per migliorare il ciclo di feedback. I codici di uscita determinano ancora la decisione primaria, ma il JSON fornisce un contesto più ricco.
Riferimento ai campi di input degli hook
Tutti gli hook ricevono un oggetto JSON tramite stdin con campi comuni più dati specifici dell'evento. Comprendere lo schema completo consente una logica di hook più sofisticata.
Campi di input comuni
Ogni hook riceve questi campi di base:
- event: Il nome dell'evento dell'hook (ad es. “PreToolUse”)
- sessionId: Identificatore univoco della sessione Claude corrente
- turnId: Identificatore del turno di conversazione corrente
- timestamp: Timestamp in formato ISO 8601 quando l'evento è stato attivato
Campi evento strumento
Gli eventi PreToolUse, PostToolUse e PostToolUseFailure includono:
- toolName: Nome dello strumento che viene invocato (edit_file, execute_command, ecc.)
- toolInput: Oggetto contenente i parametri di input dello strumento
- toolResponse: Dati di output dello strumento (solo PostToolUse)
- error: Dettagli dell'errore inclusi messaggio e codice (solo PostToolUseFailure)
La struttura di toolInput varia in base allo strumento. Per edit_file contiene path e content. Per execute_command contiene command e args.
Campi evento autorizzazione
Gli eventi PermissionRequest includono:
- permissionType: Tipo di autorizzazione richiesta (file_write, command_execute, ecc.)
- requestedAction: Azione specifica che richiede autorizzazione
- resourcePath: Percorso del file o identificatore della risorsa interessata
Hook MCP Tool
Secondo il riferimento ufficiale degli hook, gli hook possono corrispondere agli strumenti del Model Context Protocol (MCP) utilizzando il campo matcher mcpTool. Ciò consente l'esecuzione di hook quando Claude utilizza strumenti esterni forniti dai server MCP.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
Il valore mcpTool corrisponde al nome dello strumento in formato nome-server/nome-strumento. Ciò consente la logica di convalida per query di database, chiamate API o altre operazioni esterne.
Le richieste di funzionalità su GitHub indicano un crescente interesse per una maggiore integrazione MCP, inclusi hook che possono ispezionare le notifiche del server MCP e rispondere a eventi esterni.
Considerazioni sulla sicurezza
Gli hook vengono eseguiti con le stesse autorizzazioni di Claude Code stesso. Ciò crea implicazioni di sicurezza per ambienti multi-utente e configurazioni condivise.
Sandbox di esecuzione comandi
Secondo il problema di GitHub #28044, gli hook HTTP vengono instradati tramite un proxy sandbox che limita l'accesso alla rete e filtra le variabili d'ambiente. Gli hook di comando non hanno restrizioni di questo tipo: vengono eseguiti con pieno accesso alla shell.
La documentazione consiglia queste pratiche:
- Non archiviare mai credenziali nei comandi degli hook
- Utilizzare variabili d'ambiente per dati sensibili
- Convalidare tutti gli input dalle espansioni ${...}
- Implementare limiti di timeout per servizi esterni
- Utilizzare hook asincroni per operazioni non critiche per evitare blocchi in caso di errori
Isolamento dell'esecuzione degli hook
Gli hook a livello utente in ~/.claude/settings.json si applicano a tutti i progetti. Ciò crea rischi quando si lavora tra diversi confini di fiducia. Gli hook a livello di progetto sovrascrivono gli hook utente ma non possono disabilitarli completamente.
Il menu /hooks in Claude Code mostra tutti gli hook attivi per la sessione corrente. La revisione di questo elenco prima di lavorare su progetti sensibili aiuta a identificare potenziali problemi di sicurezza.
Debug e risoluzione dei problemi
I fallimenti degli hook non emergono sempre chiaramente nella conversazione di Claude. La documentazione ufficiale fornisce diversi approcci al debug.
Log di esecuzione degli hook
Claude Code registra l'esecuzione degli hook nell'output di debug della sessione. Secondo la guida alla risoluzione dei problemi, l'abilitazione del logging di debug rivela:
- Quali hook hanno corrisposto per ciascun evento
- L'input JSON inviato a ciascun hook
- Output stdout e stderr dai processi degli hook
- Codici di uscita e tempo di esecuzione
- Codici di stato e corpi delle risposte per gli hook HTTP
Abilita il logging di debug impostando CLAUDE_DEBUG=1 nell'ambiente prima di avviare Claude Code.
Test degli hook in modo indipendente
Gli hook di comando possono essere testati al di fuori di Claude Code costruendo manualmente input JSON:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Ciò convalida la logica dell'hook senza attivare operazioni effettive di Claude. Il codice di uscita e l'output stdout/stderr dovrebbero corrispondere al comportamento previsto.
Errori frequenti degli hook
Le discussioni della community identificano questi problemi frequenti:
- Errori di timeout: il timeout predefinito di 10 minuti è troppo breve per operazioni lente: aumentalo con il campo timeout
- Errori di espansione del percorso: variabili come ${file} non definite per eventi che non includono il contesto del file
- Errori di autorizzazione: gli script degli hook non hanno permessi di esecuzione: esegui chmod +x script.sh
- Errori di analisi JSON: output JSON malformato dagli hook: convalida con jq prima di restituire
- Indisponibilità delle variabili d'ambiente: variabili non propagate al processo dell'hook: controlla l'ambiente di Claude Code
Implicazioni di performance degli hook
Gli hook sincroni bloccano il flusso di lavoro di Claude fino al completamento. Il timeout predefinito di 10 minuti impedisce blocchi indefiniti, ma anche brevi ritardi si accumulano tra più operazioni.
I professionisti riferiscono che semplici hook di convalida hanno un impatto trascurabile sulle prestazioni. Gli hook di formattazione dei file causano un impatto sulle prestazioni notevole ma accettabile. Le chiamate API esterne possono creare attriti nel flusso di lavoro. Le operazioni di calcolo intensive beneficiano dell'esecuzione asincrona.
Batching di hook
Più hook possono corrispondere allo stesso evento. Secondo la documentazione di riferimento, gli hook vengono eseguiti sequenzialmente nell'ordine di definizione. Se un hook blocca l'operazione, gli hook rimanenti non vengono eseguiti.
Questo è importante per le prestazioni. Cinque hook sincroni da 200 ms ciascuno aggiungono un secondo per evento. L'unione di convalide correlate in un unico hook riduce l'overhead.
Pattern avanzati
Oltre all'automazione di base, gli hook consentono una personalizzazione avanzata del flusso di lavoro.
Catene di hook stateful
Gli hook possono mantenere lo stato tra le esecuzioni utilizzando file o database. Un hook PostToolUse potrebbe registrare operazioni riuscite che un hook PreToolUse convaliderà successivamente:
| #!/bin/bash # Registra le modifiche riuscite echo “${toolInput.path}” >> .claude/edit-history.txt |
Un hook PreToolUse complementare potrebbe controllare questa cronologia per prevenire operazioni ridondanti o applicare vincoli di ordinamento.
Attivazione condizionale di hook
Le variabili d'ambiente controllano il comportamento degli hook in fase di runtime. Impostando CLAUDE_SKIP_HOOKS=1 si disabilitano gli hook per situazioni di emergenza.
Gli hook stessi possono controllare flag ambientali:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Applica convalida rigorosa exit 1 fi exit 0 |
Ciò consente un comportamento in modalità sviluppo rispetto alla modalità produzione senza modifiche alla configurazione.
Convalida multi-stadio
Gli hook PreToolUse possono implementare convalida multi-livello in cui il codice di uscita 2 consente a Claude di procedere con avvisi:
- Fallimenti rigidi (uscita 1): blocca operazioni pericolose
- Avvisi soft (uscita 2): avvisa Claude di riconsiderare
- Passa con contesto (uscita 0 + JSON): fornisce informazioni aggiuntive
Ciò crea uno spettro di convalida più sfumato rispetto al binario consenti/nega.
Integrazione con CI/CD
Secondo la documentazione ufficiale sull'integrazione della piattaforma, Claude Code viene eseguito in ambienti CI/CD per la revisione automatica del codice e il triage dei problemi. Gli hook estendono questa automazione.
I workflow di GitHub Actions possono definire hook che applicano le policy del team durante le sessioni automatizzate:
| – name: Esegui Claude Code con hook rigorosi env: STRICT_MODE: 1 run: | claude “Rivedi questo PR e suggerisci miglioramenti” |
Il flag STRICT_MODE attiva la logica di convalida condizionale negli script degli hook. Ciò garantisce che le sessioni automatizzate seguano regole più rigide rispetto allo sviluppo interattivo.
Generazione di tracce di audit
Gli hook PostToolUse in ambienti CI creano log di audit dettagliati di tutte le operazioni di Claude:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Il logging in background non influisce sulle prestazioni ma fornisce una cronologia completa delle operazioni per la conformità e il debug.
Il menu /hooks
Claude Code fornisce un comando /hooks che visualizza tutti gli hook attivi per la sessione corrente. Secondo la documentazione ufficiale, questo menu mostra:
- Tipo di evento dell'hook
- Pattern di corrispondenza
- Comando o endpoint URL
- Se l'hook viene eseguito in modalità async
- Origine della configurazione (progetto, utente o plugin)
Selezionare un hook mostra la sua configurazione completa e consente la disabilitazione temporanea per la sessione corrente.
Disabilita o rimuovi hook
Gli hook possono essere disabilitati senza rimuovere la configurazione aggiungendo “enabled”: false alla definizione dell'hook. Ciò preserva la configurazione impedendone l'esecuzione.
Per rimuovere definitivamente un hook, elimina la sua voce dal file settings.json appropriato. Le modifiche diventano effettive al successivo riavvio della sessione o quando si esegue /reload.
Hook in Skills e Agenti
Secondo la documentazione ufficiale, gli hook definiti all'interno delle configurazioni di skill o sottoagenti si applicano solo quando quella skill o agente viene eseguita. Ciò consente un'automazione specializzata per flussi di lavoro specifici.
Un sottoagente di debug potrebbe includere hook che registrano tutte le chiamate agli strumenti:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Questi hook vengono attivati solo durante le sessioni dell'agente debugger, non durante il normale funzionamento di Claude Code.
Script di riferimento per percorso
I comandi degli hook supportano sia percorsi relativi che assoluti. I percorsi relativi vengono risolti dalla radice del progetto in cui viene eseguito Claude Code.
Best practice dalle discussioni della community:
- Archivia gli script degli hook nella directory .claude/hooks/
- Utilizza nomi descrittivi: validate-typescript.sh invece di hook1.sh
- Rendi gli script eseguibili: chmod +x .claude/hooks/*.sh
- Includi la riga shebang: #!/usr/bin/env bash o #!/usr/bin/env python3
- Aggiungi la gestione degli errori con set -e negli script bash
Capacità future degli hook
Le richieste di funzionalità su GitHub rivelano miglioramenti pianificati e richiesti per gli hook:
- Hook di script inline: definisci la logica degli hook direttamente in settings.json senza file esterni
- Integrazione con strumenti MCP: invoca strumenti del server MCP dagli hook invece di comandi shell
- Collaborazione multi-agente: hook che coordinano tra istanze Claude su macchine diverse
- Tipizzazione avanzata: definizioni di tipi TypeScript per schemi di input/output degli hook
Secondo il problema di GitHub #4274, la richiesta di tipi di hook integrati (strumento MCP, script inline, chiamata API) mira a semplificare la configurazione e migliorare l'esperienza dello sviluppatore.
Domande frequenti
Gli hook possono impedire a Claude di eseguire comandi pericolosi?
Sì. Gli hook PreToolUse possono bloccare qualsiasi esecuzione di strumento uscendo con codice 1. Ciò include modifiche ai file, esecuzione di comandi e chiamate a strumenti MCP. L'hook riceve l'input completo dello strumento e può convalidare qualsiasi criterio prima di consentire l'operazione.
Come si debugga un hook che non funziona?
Abilita il logging di debug con CLAUDE_DEBUG=1 prima di avviare Claude Code. Controlla i log della sessione per i dettagli sull'esecuzione degli hook, inclusi quali hook hanno corrisposto, l'input JSON inviato, l'output stdout/stderr e i codici di uscita. Testa gli hook in modo indipendente inviando JSON di esempio allo script dell'hook.
Gli hook funzionano con tutte le piattaforme di Claude Code?
Gli hook funzionano nella CLI, nell'app desktop e nell'estensione VS Code. Secondo la documentazione ufficiale, gli hook vengono eseguiti ovunque Claude Code venga eseguito con accesso al file system. Claude basato su browser e le app mobili non supportano gli hook a causa dei vincoli di sandboxing.
Gli hook possono modificare le risposte o il comportamento di Claude?
Gli hook di prompt iniettano istruzioni che influenzano il comportamento di Claude. Gli hook di agenti delegano la gestione degli eventi a sottoagenti specializzati. Tuttavia, gli hook non possono modificare direttamente il testo generato o il processo di ragionamento di Claude: funzionano fornendo contesto e bloccando le operazioni.
Qual è la differenza tra hook asincroni e sincroni?
Gli hook sincroni bloccano il flusso di lavoro di Claude fino al completamento o al timeout. Gli hook asincroni vengono eseguiti in background senza bloccare. Gli hook sincroni possono prevenire operazioni tramite codici di uscita. Gli hook asincroni non possono bloccare poiché Claude continua prima che l'hook sia completato. Utilizza async per il logging e le notifiche, sync per la convalida.
Come si condividono gli hook tra un team?
Effettua il commit del file .claude/settings.json nel controllo versione. Gli hook a livello di progetto si applicano a tutti i membri del team che clonano il repository. Per le policy a livello di organizzazione, i team possono mantenere un file di impostazioni utente condiviso che i membri copiano in ~/.claude/settings.json.
Gli hook HTTP possono chiamare API interne dietro firewall?
Sì, se Claude Code viene eseguito in un ambiente con accesso di rete a tali API. Gli hook HTTP effettuano richieste POST standard dalla macchina che esegue Claude Code. Firewall aziendali e VPN si applicano normalmente. Il proxy sandbox menzionato nella documentazione controlla l'esposizione delle variabili d'ambiente, non il routing di rete.
Gli hook aumentano l'utilizzo dei token di Claude Code?
Gli hook di prompt iniettano testo nel contesto di Claude, il che consuma token. Gli hook di comando e HTTP non influiscono direttamente sull'utilizzo dei token, ma il loro output (messaggi di errore, suggerimenti) diventa parte del contesto della conversazione. Il codice di uscita 2 con messaggi esplicativi aggiunge più contesto del codice di uscita 1 con un semplice blocco.
Conclusione
Gli hook di Claude Code trasformano l'assistente AI da uno strumento potente a una piattaforma di sviluppo completamente automatizzata. Il sistema di eventi fornisce punti di intercettazione durante il flusso di lavoro di Claude, dall'inizializzazione della sessione alla compattazione del contesto.
Gli hook di comando gestiscono la convalida e la formattazione locale. Gli hook HTTP integrano servizi e database esterni. Gli hook di prompt modificano il comportamento tramite l'iniezione di contesto. Insieme, consentono pattern di automazione che applicano le policy del team, mantengono la qualità del codice e si integrano con l'infrastruttura di sviluppo esistente.
Il sistema di corrispondenza filtra gli hook per strumenti e pattern di file specifici. I codici di uscita e l'output JSON controllano il flusso decisionale. L'esecuzione asincrona impedisce il blocco su operazioni lente. Lo schema di configurazione completo supporta tutto, dalla semplice formattazione automatica alla complessa convalida multi-stadio.
Inizia con semplici hook PostToolUse per la formattazione del codice. Aggiungi la convalida PreToolUse man mano che emergono le policy. Sperimenta con gli hook di prompt per la modifica del comportamento. Costruisci integrazioni HTTP per l'applicazione a livello di team.
Controlla la documentazione ufficiale di Claude Code per il riferimento completo degli hook e lo schema di configurazione aggiornato man mano che vengono rilasciate nuove funzionalità.
