Hook di Claude Code: eventi, configurazione e sicurezza
Scopri dove configurare gli hook di Claude Code, quali eventi li attivano e perché il codice di uscita 2 annulla una chiamata allo strumento prima dell'esecuzione.
Cos'è un hook di Claude Code
Gli hook di Claude Code sono comandi shell che Claude Code esegue autonomamente in punti prestabiliti del proprio ciclo di vita. Questa è l'intera differenza tra un hook e un file di regole. Un'istruzione in CLAUDE.md è un suggerimento che il modello valuta insieme a tutto il resto del contesto. Un hook è codice e viene eseguito indipendentemente dalla decisione del modello. Se l'agente continua a ignorare il formatter anche dopo che glielo hai indicato due volte, non ti serve un'istruzione più rigida. Ti serve un hook.
Il meccanismo è semplice. Registri un comando in un file di impostazioni associandolo al nome di un evento. Quando l'evento si verifica, Claude Code esegue il comando e scrive i dati dell'evento nel suo standard input (stdin) in formato JSON (JavaScript object notation). Il comando legge questi dati, esegue le proprie operazioni e restituisce uno stato di uscita. L'uscita 2 di un hook PreToolUse annulla la chiamata allo strumento prima dell'esecuzione. Qualsiasi contenuto scritto dallo script sullo standard error (stderr) viene restituito al modello come motivazione, a meno che l'hook non stampi anche JSON contenente una decisione di blocco, nel qual caso prevale la relativa motivazione.
I nomi degli eventi e dei campi riportati qui provengono dalla documentazione di riferimento degli hook di Claude Code, verificata il 12 novembre 2026. Questa interfaccia cambia rapidamente. Prima di copiare JSON da un post di un blog, incluso questo, consulta la documentazione relativa alla tua versione. Visualizza la tua versione con claude --version.
Dove si trova la configurazione degli hook
Un hook è un blocco JSON in un file di impostazioni. Può essere definito in sei posizioni; l'ambito del file determina l'ambito dell'hook.
~/.claude/settings.json: tutti i progetti del tuo computer, ma nessun progetto di altri computer..claude/settings.json: un singolo progetto, salvato nel repository, quindi tutti quelli che lo clonano ricevono l'hook..claude/settings.local.json: un singolo progetto, soltanto sul tuo computer.- Impostazioni dei criteri gestiti: valide per l'intera organizzazione e definite da un amministratore.
hooks/hooks.jsonall'interno di un plugin, attivo finché il plugin è abilitato.- Frontmatter di una skill o di un subagent. Gli hook di una skill restano attivi per il resto della sessione dopo l'invocazione della skill; quelli di un subagent restano attivi mentre il subagent è in esecuzione.
Le voci degli hook provenienti da questi file vengono unite e non si sovrascrivono. Un file di impostazioni del progetto aggiunge i propri hook a quelli delle impostazioni utente, invece di sostituirli. Di conseguenza, uno stesso evento può contenere più hook provenienti da file diversi. L'impostazione "disableAllHooks": true li disattiva, con un'eccezione: gli hook provenienti dalle impostazioni dei criteri gestiti continuano a essere eseguiti, a meno che l'impostazione non venga applicata anche nelle impostazioni gestite.
Esegui /hooks all'interno di una sessione per elencare tutti gli hook attualmente registrati, raggruppati per evento, indicando per ciascuno il file di origine e il matcher. Il menu è in sola lettura, quindi per modificare un hook devi intervenire nel file di impostazioni. Il file watcher rileva normalmente la modifica senza richiedere un riavvio.
Quali eventi hook esistono in Claude Code
Il riferimento degli hook elenca trentatré eventi, da SessionStart a SessionEnd, che coprono compattazione, subagent, worktree e file di configurazione. In un server ne bastano alcuni.
PreToolUse: prima dell'esecuzione di una chiamata a uno strumento, tranneEndConversation. È l'evento che può bloccare l'operazione.PostToolUse: dopo il completamento corretto di una chiamata a uno strumento, tranneEndConversation.PostToolUseFailureviene generato invece quando la chiamata non riesce; quindi, per intercettare ogni risultato, l'hook deve gestire entrambi.PermissionRequest: quando una chiamata a uno strumento richiede una decisione sui permessi, cioè nel momento in cui verrebbe visualizzata la richiesta di approvazione.UserPromptSubmit: quando si invia un prompt, prima che Claude lo elabori. L'output stdout in testo semplice di un hook completato correttamente viene aggiunto al contesto del modello.SessionStarteSessionEnd: a ogni termine di una sessione.SessionStartviene generato anche dopo la compattazione, con il valore del matchercompact.Stop: quando Claude termina la risposta. Si verifica una volta per turno, non una volta per ogni attività completata.
Negli eventi che supportano i matcher, un gruppo può includere un matcher che stabilisce per quali occorrenze eseguire l'hook. Negli eventi degli strumenti filtra in base al nome dello strumento, quindi "Edit|Write" viene generato per le modifiche ai file e per nient'altro. I matcher distinguono tra maiuscole e minuscole. Un matcher vuoto viene applicato a ogni occorrenza. Gli strumenti di un server MCP (model context protocol) vengono denominati mcp__<server>__<tool>; quindi un matcher "mcp__github__.*" intercetta gli strumenti di un server e non quelli degli altri.
Gli hook Stop presentano un comportamento particolare da conoscere prima di scriverne uno. Un hook Stop che blocca l'operazione rimanda il modello al lavoro e, per impostazione predefinita, Claude Code ignora il blocco successivo dopo otto continuazioni consecutive. Il conteggio viene azzerato ogni volta che Claude chiama uno strumento. Leggi il campo stop_hook_active dall'input dell'hook e restituisci il codice di uscita 0 quando il suo valore è true; in caso contrario, l'hook potrebbe continuare a rimandare Claude al lavoro.
Cosa riceve un hook su stdin
Quando Claude sta per eseguire npm test, un hook PreToolUse su Bash legge questi dati da stdin:
{
"session_id": "abc123",
"cwd": "/home/deploy/myproject",
"hook_event_name": "PreToolUse",
"tool_name": "Bash",
"tool_input": {
"command": "npm test"
}
}I campi di input comuni includono session_id, cwd, transcript_path e hook_event_name; permission_mode non viene inviato per ogni evento. Gli eventi degli strumenti aggiungono tool_name, tool_input e tool_use_id. Gli altri eventi contengono campi specifici: UserPromptSubmit riceve il testo prompt, mentre SessionStart riceve un source di startup, resume, clear, compact o fork.
jq è il metodo usuale per leggere questi dati in uno script shell, ma un'immagine server minimale non lo include. Installalo prima con sudo apt install -y jq su Ubuntu e Debian.
Cosa comporta lo stato di uscita per la chiamata allo strumento in corso
Sono possibili tre risultati.
- Exit 0 indica il successo. I campi di decisione JSON validi continuano ad applicarsi, inclusi il blocco o il diniego. Su
PreToolUse, exit 0 senza una decisione non equivale all'approvazione e viene comunque eseguito il normale flusso di autorizzazione. SuUserPromptSubmit,UserPromptExpansion,SessionStartePostModelSwitch, lo stdout in testo semplice viene aggiunto al contesto del modello. Nella maggior parte degli altri eventi, lo stdout viene scritto soltanto nel log di debug. - Exit 2 blocca l'azione negli eventi che supportano il blocco, incluso
PreToolUse. Lo stderr diventa il messaggio associato al blocco, a meno che l'output JSON non contenga una decisione di blocco; in quel caso prevale il relativo motivo. Il destinatario del messaggio dipende dall'evento. SuPreToolUseeStopil modello lo vede come motivo. SuUserPromptSubmitePreModelSwitchviene mostrato a te e non viene aggiunto al contesto del modello. SuPostToolUseePostToolUseFailure, che non supportano il blocco, il blocco viene ignorato, ma lo stderr viene comunque inviato al modello come feedback. Nella maggior parte degli altri eventi che non supportano il blocco, lo stderr viene mostrato soltanto a te oppure ignorato. SuStop,SubagentStop,TaskCompletede sull'hookUserPromptSubmitdi un plugin, exit 2 con stdout vuoto e un errore di file mancante su stderr viene trattato come un errore che non blocca l'azione. - Qualsiasi altro codice di uscita con stdout in testo semplice o vuoto è normalmente un errore che non blocca l'azione. La trascrizione mostra una notifica di errore dell'hook contenente la prima riga dello stderr dopo il testo
Failed with non-blocking status code:. Il JSON valido può comunque determinare l'esito in eventi comePreToolUse, a meno che l'errore dell'hook non blocchi l'azione.WorktreeCreatefallisce in presenza di qualsiasi exit diverso da 0, mentreWorktreeRemovefallisce in presenza di un exit diverso da 0 se la directory esiste ancora al termine.
Per ottenere un risultato diverso dal blocco o dall'assenza di azione, usa exit 0 e stampa invece un oggetto JSON su stdout. Un hook PreToolUse prende la decisione con permissionDecision:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Database drops go through a migration, not through the agent."
}
}"allow" salta il prompt interattivo quando le regole di autorizzazione e i requisiti di approvazione dello strumento lo consentono, "deny" annulla la chiamata e invia il motivo al modello, mentre "ask" richiede una conferma. Scegli uno stile per ogni hook. Usare exit 2 insieme a una decisione JSON su stdout mantiene il blocco, anche se il JSON indica "allow".
Quando più hook corrispondono allo stesso evento, vengono eseguiti in parallelo. Gli hook prompt e agent sono limitati a dodici esecuzioni simultanee. Un deny di un hook non interrompe gli hook associati, quindi un hook di logging scrive comunque la propria riga mentre un hook di protezione nega la stessa chiamata. Per PreToolUse, Claude Code unisce quindi le risposte e mantiene quella più restrittiva, nell'ordine diniego, rinvio, richiesta di conferma, autorizzazione.
Esempio 1: bloccare un comando distruttivo prima dell'esecuzione
Salva questo contenuto come .claude/hooks/block-destructive.sh nel progetto:
#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
exit 2
fi
done
exit 0Rendilo eseguibile, quindi registralo in PreToolUse all'interno di .claude/settings.json:
chmod +x .claude/hooks/block-destructive.sh{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
"timeout": 10,
"statusMessage": "Checking the command against policy"
}
]
}
]
}
}Verifica manualmente lo script prima di considerarlo affidabile, perché un hook che va in errore durante l'elaborazione del proprio input normalmente consente l'operazione quando onFailure non è impostato. Su Windows senza Git Bash, un hook di tipo shell PreToolUse o PermissionRequest che restituisce un errore può invece bloccare la chiamata allo strumento:
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
| .claude/hooks/block-destructive.sh
echo $?Dovresti vedere la riga Blocked by policy: su stderr e un codice di uscita 2. Passagli un comando innocuo, ad esempio ls -la, e non dovresti vedere alcun output; il codice di uscita dovrebbe essere 0. In una sessione, la chiamata negata compare nella trascrizione con il tuo messaggio come motivazione, quindi il modello legge il messaggio e si adatta.
Una proprietà rende utile questa configurazione: gli hook PreToolUse vengono eseguiti prima del controllo della modalità delle autorizzazioni, indipendentemente dalla modalità attiva. Di conseguenza, un rifiuto resta effettivo anche con bypassPermissions. Per questo un hook è utile insieme a modalità automatica e impostazioni delle autorizzazioni di Claude Code, quando le richieste di conferma sono ridotte ma l'hook continua a essere eseguito.
È importante chiarire i limiti di questa soluzione. La ricerca di corrispondenze in una stringa di comando è una protezione contro la disattenzione di un agent, ma non è una barriera contro un agent che cerca di aggirarla, perché lo stesso comando può essere scritto in una forma che il tuo grep non rileva. Le regole vincolanti devono essere definite nel sistema delle autorizzazioni e nell'account con cui viene eseguito il processo.
Esempio 2: formattazione e lint dopo ogni modifica
PostToolUse con un matcher Edit|Write viene eseguito dopo il completamento corretto di uno dei due strumenti di modifica dei file. Salvalo come .claude/hooks/after-edit.sh:
#!/bin/bash
# Format the edited file, then report lint failures back to the model.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0
case "$FILE" in
*.py)
ruff format "$FILE" >/dev/null 2>&1
if ! ruff check "$FILE" >&2; then
exit 2
fi
;;
*.sh)
if ! shellcheck "$FILE" >&2; then
exit 2
fi
;;
esac
exit 0{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.sh",
"timeout": 60
}
]
}
]
}
}Chiedi a Claude di aggiungere a un file Python una funzione con indentazione errata, quindi apri il file. Il file risulta formattato. Questo conferma che l’hook è stato eseguito, perché un hook completato correttamente non visualizza nulla nella conversazione.
In questo caso, l’uscita 2 non annulla alcuna modifica. PostToolUse viene eseguito dopo che lo strumento ha già completato l’operazione, quindi la modifica viene comunque scritta su disco. Il vantaggio dell’uscita 2 è che l’output di ruff check viene restituito al modello come feedback, consentendogli di correggere l’errore appena introdotto invece di proseguire. Questa è la differenza tra un errore di linting rilevato al momento del commit e un errore corretto dall’agente nello stesso turno.
In questo contesto sono importanti due limiti dei matcher. Edit|Write non rileva i file modificati da un comando della shell, e Claude scrive i file tramite Bash con una frequenza sufficiente a rendere concreto questo limite. Per una copertura a ogni chiamata, esegui il matching anche su Bash e fai in modo che lo script elenchi i file modificati con git status --porcelain. Per una copertura una volta per turno, inserisci la scansione in un hook Stop.
Esempio 3: registrare ogni chiamata agli strumenti per l'audit
Un matcher vuoto su PostToolUse viene eseguito per ogni chiamata allo strumento completata correttamente, tranne EndConversation. Inviare il record al journal di sistema invece di salvarlo in un file nella directory home non lo rende inaccessibile alla shell dell'agent: l'accesso dipende dai permessi dell'account. Gli utenti possono leggere i propri journal privati, mentre root e i membri di systemd-journal, adm o wheel possono leggere tutti i file del journal:
{
"hooks": {
"PostToolUse": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "jq -c '{time: now|todate, session: .session_id, cwd: .cwd, tool: .tool_name, input: .tool_input}' | logger -t claude-code -p local0.info"
}
]
}
]
}
}Rileggere i record con journalctl -t claude-code -o cat | tail -n 5. Se si dispone dell'autorizzazione a leggerli, dovrebbe essere presente una riga JSON per ogni chiamata allo strumento completata correttamente, diversa da EndConversation, con la più recente alla fine. Se non compare nulla, verificare sia l'accesso al journal sia l'esecuzione dell'hook; la sezione sulla risoluzione dei problemi più avanti descrive l'hook.
Aggiungere lo stesso blocco sotto PostToolUseFailure per acquisire le chiamate non riuscite, perché PostToolUse viene eseguito solo in caso di successo e un comando non riuscito è in genere quello più interessante. Il motivo per usare logger invece di aggiungere dati a un file nella directory home è la proprietà: un hook viene eseguito con lo stesso utente della shell dell'agent, quindi tutto ciò a cui quell'utente può aggiungere dati può anche essere troncato dallo stesso utente. Il journal viene scritto da systemd-journald; impedirne l'eliminazione dipende comunque dai privilegi dell'account dell'agent.
Per quanto tempo può essere eseguito un hook
I dati alla base di questo grafico
[
{
"label": "command, http or mcp_tool hook",
"default_timeout_seconds": 600
},
{
"label": "agent hook",
"default_timeout_seconds": 60
},
{
"label": "prompt hook",
"default_timeout_seconds": 30
},
{
"label": "command, http or mcp_tool on UserPromptSubmit, PreModelSwitch or PostModelSwitch",
"default_timeout_seconds": 30
},
{
"label": "command, http or mcp_tool on MessageDisplay",
"default_timeout_seconds": 10
},
{
"label": "any hook on SessionEnd",
"default_timeout_seconds": 1.5
}
]Per impostazione predefinita, un command hook ha a disposizione 600 secondi, cioè dieci minuti. Alcuni eventi riducono drasticamente questo limite. Gli hook SessionEnd condividono un budget di 1.5 secondi complessivi, quindi le attività di pulizia al termine della sessione devono essere rapide. Tuttavia, impostando un timeout più lungo su un hook nei file di configurazione, il budget condiviso aumenta allo stesso valore, fino a 60 secondi.
Un hook sincrono di tipo command, HTTP o MCP tool che raggiunge il timeout viene annullato e normalmente non produce alcuna decisione; con PreModelSwitch, invece, il timeout impedisce il passaggio. Per un controllo PreToolUse, il timeout consente normalmente alla chiamata dello strumento di proseguire nel normale flusso di autorizzazione, con l'eccezione Windows descritta sopra quando onFailure non è impostato. Per questo motivo, gli script di controllo devono essere brevi. A partire dalla release 2.1.295, è possibile invertire questo comportamento predefinito su un hook command o http con "onFailure": "block". In questo modo un timeout, un arresto anomalo o un codice di uscita imprevisto causano un blocco. Questa impostazione non ha effetto su Stop, SubagentStop, TaskCompleted, TeammateIdle o sugli hook command in background. Per le attività lente che non richiedono un'attesa, ad esempio l'invio di un log a un'altra destinazione, impostare "async": true. L'hook viene eseguito in background senza ritardare la chiamata dello strumento.
Hook, file di regole, skill e server MCP
Quattro elementi vengono spesso confusi perché modificano tutti il comportamento di un agent. Solo uno di questi smette di essere un suggerimento.
Un file di regole (CLAUDE.md oppure un file sotto .claude/rules/) è testo caricato nel contesto del modello. Influisce sul comportamento, ma non impone nulla. In una conversazione lunga, con un diff esteso e una nuova richiesta dell'utente, una sua riga può passare inosservata. Questo è il meccanismo ordinario alla base degli agent che ignorano le istruzioni scritte.
Una skill è una directory di istruzioni e script che il modello carica quando ritiene pertinente. Questa valutazione è lo scopo di una skill, ma anche il suo limite: la decisione resta al modello. Entrambi gli aspetti sono visibili in una skill come Ponytail, che orienta l'agent verso la modifica minima funzionante, perché definisce il modo di affrontare un'intera attività in un modo che nessun hook potrebbe offrire, e solo finché il modello sceglie di caricarla.
Un server MCP (model context protocol) fornisce al modello nuovi strumenti da chiamare. Amplia ciò che l'agent può raggiungere. Non fa sì che l'agent utilizzi necessariamente questi strumenti. Inoltre è un processo separato che devi gestire, ed è un'attività autonoma: vedi come eseguire server MCP su un VPS.
Un hook è l'unico dei quattro che viene eseguito senza una scelta del modello. Usa un file di regole per una preferenza e una skill per una procedura che il modello deve seguire quando è pertinente. Usa un hook per il passaggio che deve essere eseguito ogni volta o per l'azione che non deve mai essere eseguita. Il confronto completo, incluso quando una skill è preferibile a un file di regole, è disponibile in confronto tra skill, MCP e file di regole.
Un plugin è un sistema di pacchettizzazione, non un quinto meccanismo. Raggruppa hook e skill in un'unica unità installabile. In questo modo un team può distribuire la stessa protezione su ogni macchina: vedi come funzionano i plugin di Claude Code.
La decisione di sicurezza su un VPS condiviso
Un hook è codice attivato dall'agente e viene eseguito con l'utente che ha avviato Claude Code. Eredita i permessi sui file e l'ambiente di quell'utente. Su un laptop è una questione di flusso di lavoro. Su un VPS in cui un agente viene eseguito senza supervisione, è una questione di sicurezza con quattro aspetti pratici.
Un hook in un repository è codice che non hai scritto tu. .claude/settings.json è sottoposto a commit. Di conseguenza, clonare un repository e avviare una sessione al suo interno può registrare gli hook inclusi nel repository. In una sessione interattiva, Claude Code sottopone gli hook del progetto alla finestra di dialogo di attendibilità dell'area di lavoro per quella directory. Accettare l'attendibilità è quindi il momento in cui decidi di eseguirli. Leggi prima il blocco hooks. Una sessione claude -p o SDK, che è il modo abituale per eseguire un agente senza supervisione, non mostra mai quella finestra di dialogo e considera attendibile la directory. Gli hook del repository vengono quindi eseguiti senza richiesta di conferma. Esamina i relativi file .claude/ prima di creare script che interagiscono con il repository oppure esegui con --settings '{"disableAllHooks": true}'.
Un hook vede l'intero input dello strumento. Un hook di audit che registra tool_input scrive in un log ogni argomento di ogni comando, inclusi eventuali token presenti nella riga di comando. Quel log richiede quindi la stessa protezione del secret. Questo rientra nel problema più ampio di tenere i secret fuori dalla portata di un agente AI.
Un hook può scrivere nel contesto del modello. Lo stdout in testo semplice di un hook SessionStart o UserPromptSubmit completato correttamente viene aggiunto alla conversazione. Un hook che inserisce testo proveniente dall'esterno, da un issue tracker o da un file di log, consegna al modello testo non attendibile come se lo avessi scritto tu. Un hook che inoltra una nota da un'altra sessione di Claude Code sullo stesso VPS fa la stessa cosa. L'output di un agente non merita più fiducia di quello dell'issue tracker. Tratta quello stdout come input, non come output.
Il privilegio è il controllo effettivo. Esegui l'agente con un utente dedicato e senza privilegi, concedendogli soltanto le regole sudo necessarie. Un deny PreToolUse è utile, ma per progettazione offre le migliori garanzie possibili senza essere assoluto: la documentazione afferma lo stesso del filtro if e indica di usare il sistema dei permessi quando serve un deny effettivo. Le regole dei permessi e l'account con cui viene eseguito il processo sono gli elementi che restano validi anche in condizioni critiche.
Una proprietà vale in ogni modalità di autorizzazione. Gli hook PreToolUse vengono eseguiti prima del controllo della modalità di autorizzazione, in ogni modalità. Di conseguenza, un hook che restituisce deny blocca lo strumento anche con bypassPermissions. Gli hook possono rendere più restrittivo ciò che consentono le regole dei permessi. Non possono renderlo meno restrittivo. L'eccezione è un mod. Su una macchina senza impostazioni gestite e senza un file managed-mcp.json, in una sessione che non ha effettuato l'accesso tramite /login a un piano Team o Enterprise, un mod installato che gestisce tool.check può autorizzare una chiamata bloccata dal tuo hook PreToolUse. Con impostazioni gestite, un file managed-mcp.json oppure una credenziale /login di Team o Enterprise usata dalla sessione, una chiamata bloccata da un hook PreToolUse resta bloccata per impostazione predefinita, indipendentemente dal file di impostazioni da cui proviene l'hook. Una sessione eseguita con una chiave API o con un CLAUDE_CODE_OAUTH_TOKEN di lunga durata, modalità usata da molti server, viene considerata non autenticata anche quando è memorizzato un accesso. Prima di installare un mod su un server, verifica cosa possono modificare i mod di Claude Code.
Perché il mio hook non viene eseguito?
Segui questi passaggi nell'ordine indicato. Ogni passaggio descrive il sintomo che vedrai effettivamente.
- Esegui
/hookse verifica che l'hook compaia sotto l'evento previsto. Se un hook manca dal menu, di solito significa che il file delle impostazioni contiene un errore di sintassi JSON, perché le virgole finali e i commenti non sono consentiti, oppure che il file non si trova in una delle sei posizioni precedenti. - Confronta il matcher con il nome dello strumento, carattere per carattere. I matcher distinguono tra maiuscole e minuscole, quindi
"bash"non corrisponde mai allo strumentoBash. - Esegui manualmente lo script con un input di esempio, come nell'esempio 1 precedente. Un codice di uscita diverso da quello previsto indica un problema nello script; controlla anche il relativo stdout, perché un JSON valido può comunque fornire una decisione per eventi come
PreToolUse. - Un messaggio
jq: command not foundindica chejqnon è disponibile su quella macchina. Uncommand not foundper lo script personalizzato indica che il percorso non è stato risolto; usa quindi${CLAUDE_PROJECT_DIR}o un percorso assoluto. Se lo script non viene mai eseguito, probabilmente non dispone del permesso di esecuzione. - L'hook stampa JSON valido, ma non accade nulla. Su macOS e Linux, un hook in formato shell viene eseguito tramite
sh -cin una shell non interattiva, ma alcune configurazioni caricano comunque il profilo, ad esempioBASH_ENVche punta a~/.bashrc. Se quel profilo stampa un banner, il banner viene anteposto al JSON. Lo stdout non inizia più con{, quindi Claude Code interpreta l'intero contenuto come testo normale e ignora la decisione. Poiché l'hook termina con codice 0, nella trascrizione non compare alcun errore. Nella maggior parte degli eventi, quel testo viene scritto soltanto nel log di debug; perUserPromptSubmit,UserPromptExpansion,SessionStartePostModelSwitch, invece, viene aggiunto al contesto del modello, incluso il banner. Racchiudi qualsiasiechonel profilo in modo che venga eseguito soltanto nelle shell interattive. - Se il problema persiste, avvia la sessione con
claude --debug-file /tmp/claude.loged eseguitail -f /tmp/claude.login un secondo terminale. Il log di debug registra quali hook hanno trovato corrispondenza, il codice di uscita restituito da ciascuno e tutto ciò che hanno scritto su stdout e stderr.
FAQ
Qual è la differenza tra un hook di Claude Code e un'istruzione CLAUDE.md?
Un'istruzione CLAUDE.md è testo nel contesto del modello. Pertanto compete per l'attenzione con la conversazione e con la richiesta corrente, e il modello può valutarla insieme a questi elementi. Un hook è un comando shell eseguito da Claude Code in un punto preciso del proprio ciclo di vita. Viene quindi eseguito a ogni occorrenza dell'evento, indipendentemente dalla decisione del modello. Usa un'istruzione per esprimere una preferenza. Usa un hook per un passaggio che deve avvenire sempre o per un'azione che non deve mai avvenire.
Come posso impedire a Claude Code di eseguire uno specifico comando shell?
Registra un hook PreToolUse con un matcher Bash che legge il comando da .tool_input.command, scrive una motivazione su stderr ed esce con codice 2. Claude Code annulla la chiamata e mostra la motivazione al modello. Questo avviene prima del controllo della modalità di autorizzazione, quindi il diniego resta valido anche in modalità bypassPermissions. La corrispondenza su una stringa di comando è una misura di protezione, non un confine di sicurezza, perché lo stesso comando può essere scritto in una forma che il pattern non rileva. Affiancala quindi alle regole di autorizzazione e a un account senza privilegi.
Il mio hook stampa JSON valido, ma non succede nulla. Perché?
Controlla che il profilo della shell non stampi testo prima del JSON. Su macOS e Linux, un hook privo del campo args viene eseguito tramite sh -c. In configurazioni che caricano ancora il profilo, ad esempio quando BASH_ENV punta a ~/.bashrc, un profilo che stampa un banner lo inserisce su stdout prima del JSON. Poiché l'output non inizia più con {, Claude Code tratta tutto il contenuto come testo normale e ignora la decisione. Inoltre, poiché l'hook è terminato con codice 0, nella trascrizione non compare alcun errore. Racchiudi qualsiasi echo nel profilo in un controllo che verifichi l'esecuzione di una shell interattiva. Conferma quindi la correzione leggendo il log di debug da claude --debug-file /tmp/claude.log.
È sicuro eseguire gli hook di Claude Code su un server condiviso?
Gli hook vengono eseguiti con l'account che ha avviato Claude Code e con le autorizzazioni sui file di quell'utente. Pertanto, un hook può eseguire qualsiasi operazione consentita a quell'account. Due pratiche coprono la maggior parte dei rischi: esegui l'agente con un account dedicato senza privilegi e con una policy sudo restrittiva; inoltre, leggi il blocco hooks di qualsiasi repository prima di accettare la relativa finestra di dialogo per considerare attendibile l'area di lavoro o di eseguire claude -p al suo interno. Gli hook di progetto sono inclusi in .claude/settings.json e la modalità -p non mostra mai questa finestra di dialogo. Imposta "disableAllHooks": true nel file delle impostazioni per disabilitare gli hook, tranne gli hook gestiti, che richiedono questa impostazione a livello gestito. Un'impostazione di progetto false può sovrascrivere un'impostazione utente true.