476| `async` | no | Se `true`, viene eseguito in background senza bloccare. Vedi [Run hooks in the background](#run-hooks-in-the-background) |476| `async` | no | Se `true`, viene eseguito in background senza bloccare. Vedi [Run hooks in the background](#run-hooks-in-the-background) |
477| `asyncRewake` | no | Se `true`, viene eseguito in background e riattiva Claude al codice di uscita 2. Lo stderr dell'hook, o stdout se stderr è vuoto, viene mostrato a Claude come un [promemoria di sistema](/docs/it/glossary#system-reminder) in modo che possa reagire a un fallimento di background di lunga durata |477| `asyncRewake` | no | Se `true`, viene eseguito in background e riattiva Claude al codice di uscita 2. Lo stderr dell'hook, o stdout se stderr è vuoto, viene mostrato a Claude come un [promemoria di sistema](/docs/it/glossary#system-reminder) in modo che possa reagire a un fallimento di background di lunga durata |
478| `shell` | no | Shell da utilizzare per questo hook. Accetta `"bash"` o `"powershell"`. Impostazione predefinita `"bash"`, o `"powershell"` su Windows quando Git Bash non è installato. L'impostazione di `"powershell"` esegue il comando tramite PowerShell su Windows. Non richiede `CLAUDE_CODE_USE_POWERSHELL_TOOL` poiché gli hook generano PowerShell direttamente. Ignorato quando `args` è impostato |478| `shell` | no | Shell da utilizzare per questo hook. Accetta `"bash"` o `"powershell"`. Impostazione predefinita `"bash"`, o `"powershell"` su Windows quando Git Bash non è installato. L'impostazione di `"powershell"` esegue il comando tramite PowerShell su Windows. Non richiede `CLAUDE_CODE_USE_POWERSHELL_TOOL` poiché gli hook generano PowerShell direttamente. Ignorato quando `args` è impostato |
479| `onFailure` | no | Cosa succede all'azione quando l'hook fallisce: `"continue"`, il valore predefinito, o `"block"`. Vedi [Blocca l'azione quando un hook fallisce](#block-the-action-when-a-hook-fails). Richiede Claude Code v2.1.295 o successivo |
479 480
480<a id="exec-form-and-shell-form" />481<a id="exec-form-and-shell-form" />
481 482
533| `url` | sì | URL a cui inviare la richiesta POST |534| `url` | sì | URL a cui inviare la richiesta POST |
534| `headers` | no | Header HTTP aggiuntivi come coppie chiave-valore. I valori supportano l'interpolazione delle variabili di ambiente utilizzando la sintassi `$VAR_NAME` o `${VAR_NAME}`. Solo le variabili elencate in `allowedEnvVars` vengono risolte |535| `headers` | no | Header HTTP aggiuntivi come coppie chiave-valore. I valori supportano l'interpolazione delle variabili di ambiente utilizzando la sintassi `$VAR_NAME` o `${VAR_NAME}`. Solo le variabili elencate in `allowedEnvVars` vengono risolte |
535| `allowedEnvVars` | no | Lista di nomi di variabili di ambiente che possono essere interpolate nei valori degli header. I riferimenti alle variabili non elencate vengono sostituiti con stringhe vuote. Obbligatorio affinché avvenga qualsiasi interpolazione di variabili di ambiente |536| `allowedEnvVars` | no | Lista di nomi di variabili di ambiente che possono essere interpolate nei valori degli header. I riferimenti alle variabili non elencate vengono sostituiti con stringhe vuote. Obbligatorio affinché avvenga qualsiasi interpolazione di variabili di ambiente |
537| `onFailure` | no | Cosa succede all'azione quando l'hook fallisce: `"continue"`, il valore predefinito, o `"block"`. Vedi [Blocca l'azione quando un hook fallisce](#block-the-action-when-a-hook-fails). Richiede Claude Code v2.1.295 o successivo |
536 538
537Claude Code invia l'[input JSON](#hook-input-and-output) dell'hook come corpo della richiesta POST con `Content-Type: application/json`. Il corpo della risposta utilizza lo stesso [formato di output JSON](#json-output) degli hook di comando.539Claude Code invia l'[input JSON](#hook-input-and-output) dell'hook come corpo della richiesta POST con `Content-Type: application/json`. Il corpo della risposta utilizza lo stesso [formato di output JSON](#json-output) degli hook di comando.
538 540
821 Output del codice di uscita823 Output del codice di uscita
822</h3>824</h3>
823 825
824Il codice di uscita del comando dell'hook dice a Claude Code se l'azione deve procedere, essere bloccata o essere ignorata. Il codice di uscita non agisce da solo. Claude Code legge i [campi di output JSON](#json-output) da stdout su ogni codice di uscita, non solo 0, e per gli eventi che usano il modello di decisione standard, un oggetto analizzato che supera la convalida dello schema ha effetto insieme al codice. Il blocco di exit 2 è l'unico risultato che JSON non può sovrascrivere.826Il codice di uscita del tuo hook dice a Claude Code se continuare con l'azione che ha attivato l'hook, come una chiamata a uno strumento o un prompt. Un'esecuzione che termina ha uno di tre risultati:
825 827
826Due tabelle raccolgono le eccezioni per evento: [Exit code 2 behavior per event](#exit-code-2-behavior-per-event) dice cosa fanno i codici di uscita per ogni evento, e [Decision control](#decision-control) dice quali campi di decisione ogni evento rispetta. I campi universali come `systemMessage` funzionano sulla maggior parte degli eventi e sono elencati nella tabella [JSON output](#json-output).828* **Successo**: il tuo hook esce con 0. Claude Code applica tutti i campi di [output JSON](#json-output) che il tuo hook ha stampato, e l'azione procede a meno che quei campi non la blocchino o la neghino.
829* **Errore bloccante**: il tuo hook esce con 2. Sugli [eventi che possono bloccare](#exit-code-2-behavior-per-event), Claude Code interrompe l'azione.
830* **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, e su eventi come `PreToolUse` vedi un avviso `<hook name> hook error` nella trascrizione. Se vuoi che un hook fallito blocchi l'azione, imposta [`onFailure: "block"`](#block-the-action-when-a-hook-fails).
831
832Ciò che il tuo hook stampa su stdout può cambiare il risultato. Ad esempio, se un hook `PreToolUse` esce con 1 ma stampa JSON che supera la convalida, l'esecuzione è un successo e sono i campi JSON a 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:
833
834| Stdout | Exit 0 | Exit 2 | Qualsiasi altro codice di uscita |
835| :- | :- | :- | :- |
836| Oggetto JSON che supera la [convalida dello schema](#json-output) | Successo. I campi si applicano | Errore bloccante. Claude Code legge comunque i campi, ma non possono sovrascrivere il blocco | Successo. Claude Code ignora il codice di uscita, e decidono solo i campi. Con [`onFailure: "block"`](#block-the-action-when-a-hook-fails), questo conta come un fallimento |
837| JSON che [non può essere analizzato](#exit-code-0) o non supera la convalida dello schema | Errore non bloccante. L'avviso riporta il messaggio di analisi o di convalida | Errore bloccante. Il tuo stderr è il motivo | Errore non bloccante. L'avviso riporta il messaggio di analisi o di convalida |
838| [Testo semplice](#exit-code-0), o niente | Successo | Errore bloccante. Il tuo stderr è il motivo | Errore non bloccante. L'avviso riporta la prima riga del tuo stderr |
839
840Alcuni eventi hanno regole proprie:
841
842* **`WorktreeCreate`**: qualsiasi codice di uscita diverso da zero fa fallire la creazione del worktree, indipendentemente da ciò che dice il tuo JSON.
843* **`WorktreeRemove`**: qualsiasi codice di uscita diverso da zero fa fallire la rimozione del worktree se la directory esiste ancora dopo.
844* **`Stop`, `SubagentStop`, `TaskCompleted` e l'hook `UserPromptSubmit` di un plugin**: quando il tuo hook esce con 2 senza nulla su stdout e il suo stderr dice che manca un file, ad esempio `No such file or directory`, Claude Code tratta l'esecuzione come un errore non bloccante.
845* **`Elicitation` e `ElicitationResult`**: Claude Code applica il tuo `hookSpecificOutput` quando il tuo hook esce con 0, e lo ignora su qualsiasi altro codice di uscita.
846* **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 come `terminalSequence`, che si attivano comunque.
847
848Per verificare cosa fa il codice di uscita 2 sul tuo evento, consulta [Exit code 2 behavior per event](#exit-code-2-behavior-per-event). Per verificare quali campi di decisione rispetta, consulta [Decision control](#decision-control).
827 849
828<h4 id="exit-code-0">850<h4 id="exit-code-0">
829 Exit code 0851 Exit code 0
835 857
836Se Claude Code legge il tuo stdout come [JSON output](#json-output) o come testo semplice dipende da come inizia e finisce, ignorando gli spazi bianchi circostanti:858Se Claude Code legge il tuo stdout come [JSON output](#json-output) o come testo semplice dipende da come inizia e finisce, ignorando gli spazi bianchi circostanti:
837 859
838* **Inizia con `{` e finisce con `}`**: Claude Code lo analizza come JSON. Quando l'output è composto da due o più righe che si analizzano ciascuna come JSON da sole, e nessuna riga è un oggetto [JSON output](#json-output) che imposta un campo, Claude Code tratta l'intero output come testo semplice. Quando una di quelle righe imposta un campo, l'intero output è un errore di analisi, descritto di seguito.860* **Inizia con `{` e finisce con `}`**: Claude Code lo analizza come JSON. Quando l'output è composto da due o più righe che si analizzano ciascuna come JSON da sole, e nessuna riga è un oggetto [JSON output](#json-output) che imposta un campo, Claude Code tratta l'intero output come testo semplice. Quando una di quelle righe imposta un campo, l'intero output è un errore di analisi.
839* **Inizia con `{` ma non finisce con `}`**: Claude Code lo tratta come testo semplice.861* **Inizia con `{` ma non finisce con `}`**: Claude Code lo tratta come testo semplice.
840* **Inizia con qualsiasi altra cosa**: Claude Code lo tratta come testo semplice, anche quando è un array JSON o una stringa JSON tra virgolette.862* **Inizia con qualsiasi altra cosa**: Claude Code lo tratta come testo semplice, anche quando è un array JSON o una stringa JSON tra virgolette.
841 863
842Per gli eventi che usano il modello di decisione standard, exit 0 con un oggetto analizzato che non supera la convalida dello schema è un errore non bloccante: l'azione procede, e la trascrizione mostra un avviso `<hook name> hook error` con il messaggio di convalida. Lo stesso accade su qualsiasi codice di uscita diverso da 2, mentre [exit 2 blocca comunque](#exit-code-2).864Quando Claude Code tenta di analizzare il tuo stdout come JSON e non ci riesce, oppure l'oggetto analizzato non supera la [convalida dello schema](#json-output), l'esecuzione è un [errore non bloccante](#exit-code-output). L'avviso `<hook name> hook error` riporta il messaggio di analisi o di convalida. Sugli eventi che aggiungono lo stdout in testo semplice come contesto, Claude Code non aggiunge lo stdout che non è riuscito ad analizzare.
843
844Per gli eventi che usano il modello di decisione standard, quando Claude Code tenta di analizzare il tuo stdout come JSON e non ci riesce, segnala un errore non bloccante su ogni codice di uscita diverso da 2. La trascrizione mostra un avviso `<hook name> hook error` con il messaggio di analisi. Sugli eventi che aggiungono lo stdout in testo semplice come contesto, Claude Code non aggiunge il testo. Prima di v2.1.248, Claude Code trattava quello stdout come testo semplice.
845 865
846Lo stderr di un hook che esce con 0 va solo nel log di debug, mai nella trascrizione, e Claude non lo vede. Per leggerlo tu stesso, abilita il [debug logging](#debug-hooks). Per mostrare un avviso a Claude da un hook `PostToolUse` o `PostToolUseFailure`, esci invece con 2 in modo che [Claude veda lo stderr](#exit-code-2-behavior-per-event) anche se lo strumento è già stato eseguito.866Claude non vede mai lo stderr di un hook che esce con 0. Per leggerlo tu stesso su eventi come `PreToolUse`, abilita il [debug logging](#debug-hooks). Per mostrare un avviso a Claude da un hook `PostToolUse` o `PostToolUseFailure`, esci invece con 2 in modo che [Claude veda lo stderr](#exit-code-2-behavior-per-event) anche se lo strumento è già stato eseguito.
847 867
848<h4 id="exit-code-2">868<h4 id="exit-code-2">
849 Exit code 2869 Exit code 2
850</h4>870</h4>
851 871
852Exit 2 significa un errore bloccante. Sugli [eventi che possono bloccare](#exit-code-2-behavior-per-event), exit 2 blocca indipendentemente dal fatto che tu stampi JSON: nemmeno un `permissionDecision` JSON con valore `"allow"` può sovrascriverlo. Claude Code legge comunque qualsiasi [JSON output](#json-output) valido su stdout. Su `Elicitation` e `ElicitationResult`, l'`hookSpecificOutput` di un hook che esce con 2 viene ignorato.872Esci con il codice 2 per bloccare l'azione. Sugli [eventi che possono bloccare](#exit-code-2-behavior-per-event), Claude Code interrompe l'azione: un hook `PreToolUse` blocca la chiamata allo strumento, ad esempio, e un hook `UserPromptSubmit` rifiuta il prompt.
853 873
854Il messaggio di blocco è il motivo della decisione di blocco del tuo JSON quando ne prende una, e altrimenti il tuo testo stderr. Cosa fa il blocco varia per evento: `PreToolUse` blocca la chiamata allo strumento, `UserPromptSubmit` rifiuta il prompt, e così via. [Exit code 2 behavior per event](#exit-code-2-behavior-per-event) elenca l'effetto per ogni evento, e ogni sezione dell'evento dice dove va il messaggio.874Il 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.
855 875
856Un hook che esce con 2 mentre stampa JSON che non supera la convalida dello schema [JSON output](#json-output) blocca comunque: Claude Code usa stderr come motivo di blocco e registra l'errore di convalida nel log di debug. Prima di v2.1.214, Claude Code trattava quella combinazione come un errore non bloccante e l'azione procedeva.876Exit 2 blocca anche quando il tuo hook stampa JSON:
877
878* **JSON che supera la convalida dello schema**: Claude Code legge comunque i campi di [JSON output](#json-output), ma non possono sovrascrivere il blocco. Nemmeno un `permissionDecision` con valore `"allow"` lascia passare l'azione. Su `Elicitation` e `ElicitationResult`, l'`hookSpecificOutput` di un hook che esce con 2 viene ignorato.
879* **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.
857 880
858Questo script blocca i comandi `rm` uscendo con 2 e lascia ogni altro comando al normale flusso dei permessi:881Questo script blocca i comandi `rm` uscendo con 2 e lascia ogni altro comando al normale flusso dei permessi:
859 882
871exit 0 # Nessuna decisione: si applica il normale flusso dei permessi894exit 0 # Nessuna decisione: si applica il normale flusso dei permessi
872```895```
873 896
897Con questo script registrato come hook `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:
898
899```text theme={null}
900PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/no-rm.sh]: Blocked: rm commands are not allowed
901```
902
874<h4 id="other-exit-codes">903<h4 id="other-exit-codes">
875 Altri codici di uscita904 Altri codici di uscita
876</h4>905</h4>
877 906
878Qualsiasi altro codice di uscita non blocca da solo per la maggior parte degli eventi hook. Cosa accade dipende dal tuo stdout:907Quando il tuo hook esce con un codice diverso da 0 o 2 e stampa testo semplice o niente su stdout, l'esecuzione è un [errore non bloccante](#exit-code-output). Vedi un avviso `<hook name> hook error` nella trascrizione con `Failed with non-blocking status code:` e la prima riga dello stderr del tuo 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:
879 908
880* Con un oggetto analizzato che supera la convalida dello schema, per gli eventi che usano il modello di decisione standard, Claude Code ignora il codice di uscita e solo il JSON decide il risultato:909```text theme={null}
881 * Ogni campo che l'evento supporta viene rispettato, inclusi `permissionDecision`, `additionalContext`, `updatedInput` e `systemMessage`, e l'hook non viene segnalato come errore.910Failed with non-blocking status code: something broke
882 * [Decision control](#decision-control) elenca i campi di decisione per evento; i campi universali come `systemMessage` seguono la tabella [JSON output](#json-output).911```
883* Con un oggetto analizzato che non supera la convalida dello schema, per gli eventi che usano il modello di decisione standard, è lo stesso errore non bloccante [di exit 0](#exit-code-0): l'azione procede, e l'avviso `<hook name> hook error` riporta il messaggio di convalida.
884* Con stdout che Claude Code [tenta di analizzare come JSON](#exit-code-0) senza riuscirci, Claude Code segnala lo stesso errore non bloccante di exit 0 per gli eventi che usano il modello di decisione standard. L'azione procede, e l'avviso riporta il messaggio di analisi.
885* Con stdout che Claude Code [tratta come testo semplice](#exit-code-0), o con stdout vuoto, è un errore non bloccante per la maggior parte degli eventi hook: l'azione procede, e la trascrizione mostra un avviso `<hook name> hook error` seguito dalla prima riga di stderr, con il prefisso `Failed with non-blocking status code:`. Per acquisire lo stderr completo, abilita il [debug logging](#debug-hooks).
886 912
887Gli eventi al di fuori del modello di decisione standard mantengono le loro proprie righe nella [tabella per evento](#exit-code-2-behavior-per-event): `WorktreeCreate` fa fallire la creazione su qualsiasi uscita diversa da zero indipendentemente da ciò che dice il tuo JSON, e gli eventi che scartano completamente l'output dell'hook, come `StopFailure`, ignorano il tuo JSON su ogni codice di uscita, a parte i campi con effetti collaterali come `terminalSequence`, che si attivano comunque.913Per acquisire lo stderr completo anziché la sua prima riga, abilita il [debug logging](#debug-hooks).
888 914
889Un hook che non riesce ad avviarsi finisce nella stessa categoria non bloccante. Quando il percorso dello script non esiste o non è eseguibile, la shell esce con un codice come 127 e vedi lo stesso avviso con il messaggio dell'interprete, ad esempio `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`. Per la maggior parte degli eventi hook, l'azione procede. Quando configuri un hook di policy, controlla se compare questo avviso alla sua prima esecuzione: un percorso digitato male in `settings.json` lascia il controllo silenziosamente disabilitato.915Anche un hook che non riesce ad avviarsi è un errore non bloccante. In forma shell, quando il percorso dello script non esiste o non è eseguibile, la shell esce con un codice come 127 e l'avviso riporta il messaggio dell'interprete, ad esempio `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`. Quando configuri un hook di policy, controlla se compare questo avviso alla sua prima esecuzione, perché un percorso digitato male in `settings.json` significa che l'hook non viene mai eseguito. Per bloccare invece l'azione, imposta [`onFailure: "block"`](#block-the-action-when-a-hook-fails).
890 916
891<Warning>917<Warning>
892 Per la maggior parte degli eventi hook, il codice di uscita 2 è l'unico codice di uscita che blocca solo attraverso il codice. Senza JSON valido su stdout, Claude Code tratta il codice di uscita 1 come un errore non bloccante e procede con l'azione, anche se 1 è il codice di errore Unix convenzionale. Se il tuo hook è destinato ad applicare una policy, usa `exit 2`. Gli eventi worktree sono diversi: qualsiasi codice di uscita diverso da zero da `WorktreeCreate` interrompe la creazione del worktree, e qualsiasi codice di uscita diverso da zero da `WorktreeRemove` fa fallire la rimozione del worktree se la directory esiste ancora dopo.918 Senza JSON valido su stdout, Claude Code tratta il codice di uscita 1 come un errore non bloccante, anche se 1 è il codice di errore Unix convenzionale. Se il tuo hook è destinato ad applicare una policy, usa `exit 2`.
893</Warning>919</Warning>
894 920
895<h4 id="timeouts">921<h4 id="timeouts">
900 926
901Su [`PreModelSwitch`](#premodelswitch), un hook annullato al suo timeout blocca il cambio di modello. Su `PreToolUse`, le due famiglie di hook si comportano diversamente:927Su [`PreModelSwitch`](#premodelswitch), un hook annullato al suo timeout blocca il cambio di modello. Su `PreToolUse`, le due famiglie di hook si comportano diversamente:
902 928
903* Un hook `command`, `http` o `mcp_tool` scaduto non blocca la chiamata allo strumento. La chiamata continua attraverso il normale [flusso dei permessi](/docs/it/permissions), quindi non contare su un hook bloccato perché agisca da controllo.929* Un hook `command`, `http` o `mcp_tool` scaduto non blocca la chiamata allo strumento. La chiamata continua attraverso il normale [flusso dei permessi](/docs/it/permissions), 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"`](#block-the-action-when-a-hook-fails).
904* Un [hook di callback dell'Agent SDK](/docs/it/agent-sdk/hooks) che supera il suo timeout [blocca la chiamata allo strumento](#pretooluse).930* Un [hook di callback dell'Agent SDK](/docs/it/agent-sdk/hooks) che supera il suo timeout [blocca la chiamata allo strumento](#pretooluse).
905 931
932<h4 id="block-the-action-when-a-hook-fails">
933 Bloccare l'azione quando un hook fallisce
934</h4>
935
936Sulla maggior parte degli eventi, quando un hook fallisce o va in timeout, Claude Code esegue comunque l'azione, quindi un hook di policy con un percorso sbagliato o uno script che si arresta in modo anomalo lascia passare tutto. Per bloccare invece l'azione, imposta `"onFailure": "block"` su un hook `command` o `http`. Il valore predefinito è `"continue"`. Richiede Claude Code v2.1.295 o successivo.
937
938Questo hook `PreToolUse` in `.claude/settings.json` esegue uno script di progetto prima di ogni comando Bash, e blocca il comando se lo script fallisce:
939
940```json theme={null}
941{
942 "hooks": {
943 "PreToolUse": [
944 {
945 "matcher": "Bash",
946 "hooks": [
947 {
948 "type": "command",
949 "command": "node",
950 "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js"],
951 "onFailure": "block"
952 }
953 ]
954 }
955 ]
956 }
957}
958```
959
960Per provarlo, lascia mancante `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:
961
962```text theme={null}
963PreToolUse:Bash hook error: [node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js]: failed; blocking because onFailure is "block"
964Error: Cannot find module '/path/to/project/.claude/hooks/check-command.js'
965```
966
967Dopo un timeout, il messaggio dice `timed out` invece di `failed`. Senza `onFailure` impostato, lo stesso script mancante è un errore non bloccante e `ls` viene eseguito.
968
969Ciascuno dei seguenti casi conta come un fallimento:
970
971* **Impossibile avviarsi**: un command hook non riesce ad avviarsi, ad esempio perché lo script o l'eseguibile non esiste
972* **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
973* **Errore HTTP**: la connessione di un HTTP hook fallisce, oppure lo stato della risposta non è 2xx
974* **Timeout**: l'hook raggiunge il suo [`timeout`](#common-fields)
975* **Output non valido**: l'output JSON [non può essere analizzato](#exit-code-0) o non supera la [convalida dello schema](#json-output). 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
976
977Con `"block"` impostato, un fallimento fa ciò che fa il [codice di uscita 2 su quell'evento](#exit-code-2-behavior-per-event), 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.
978
979Il campo non ha effetto su questi hook:
980
981* **Hook `Stop`, `SubagentStop`, `TaskCompleted` e `TeammateIdle`**: 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
982* **Command hook in background**: i command hook che impostano [`async` o `asyncRewake`](#run-hooks-in-the-background)
983
906<h4 id="exit-code-2-behavior-per-event">984<h4 id="exit-code-2-behavior-per-event">
907 Exit code 2 behavior per event985 Exit code 2 behavior per event
908</h4>986</h4>
960* **Errore di connessione**: errore non bloccante, l'esecuzione continua1038* **Errore di connessione**: errore non bloccante, l'esecuzione continua
961* **Timeout**: l'hook viene annullato, come descritto in [Timeouts](#timeouts)1039* **Timeout**: l'hook viene annullato, come descritto in [Timeouts](#timeouts)
962 1040
963A differenza dei command hook, gli HTTP hook non possono segnalare un errore bloccante solo attraverso i codici di stato. 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.1041Gli HTTP hook non possono segnalare un errore bloccante solo attraverso il codice di stato: uno stato non-2xx o una connessione fallita è un [errore non bloccante](#exit-code-output). 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. Per bloccare l'azione quando la richiesta fallisce o restituisce uno stato non-2xx, imposta [`onFailure: "block"`](#block-the-action-when-a-hook-fails).
964 1042
965<h3 id="json-output">1043<h3 id="json-output">
966 Output JSON1044 Output JSON
1237 Controllo delle decisioni di SessionStart1315 Controllo delle decisioni di SessionStart
1238</h4>1316</h4>
1239 1317
1240Claude Code aggiunge al contesto di Claude lo stdout che [tratta come testo semplice](#exit-code-0). Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, puoi restituire questi campi specifici dell'evento:1318Un hook SessionStart può aggiungere contesto per Claude, fornire il primo messaggio dell'utente, impostare il titolo della sessione, monitorare file e ricaricare le skill. Restituisci il campo corrispondente a ciascuna di queste azioni, oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook:
1241 1319
1242| Campo | Descrizione |1320| Campo | Descrizione |
1243| :- | :- |1321| :- | :- |
1244| `additionalContext` | Stringa aggiunta al contesto di Claude all'inizio della conversazione, prima del primo prompt. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) per sapere come viene consegnato il testo e cosa inserirvi |1322| `additionalContext` | Stringa aggiunta al contesto di Claude all'inizio della conversazione, prima del primo prompt. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) per sapere come viene consegnato il testo e cosa inserirvi |
1245| `initialUserMessage` | Stringa usata come primo messaggio utente della sessione. Si applica in [modalità non interattiva](/docs/it/headless) con il flag `-p`, dove diventa il primo turno anche se non viene fornito alcun prompt. Se viene fornito un prompt, questo segue come turno successivo. A differenza di `additionalContext`, che si collega a un turno esistente, questo crea il turno |1323| `initialUserMessage` | Stringa usata come primo messaggio dell'utente della sessione, in [modalità non interattiva](/docs/it/headless) con il flag `-p`. Diventa il primo turno anche se non passi alcun prompt. Un prompt che passi lo segue come turno successivo |
1246| `sessionTitle` | Imposta il titolo della sessione, con lo stesso effetto di `/rename`. Usalo per assegnare automaticamente un nome alle sessioni in base alla cartella di avvio, al branch git o al nome del worktree. Si applica quando `source` è `"startup"`, `"resume"` o `"fork"`; viene ignorato con `"clear"` e `"compact"` |1324| `sessionTitle` | Imposta il titolo della sessione, con lo stesso effetto di `/rename`. Si applica quando `source` è `"startup"`, `"resume"` o `"fork"` |
1247| `watchPaths` | Array di percorsi assoluti da monitorare per gli eventi [FileChanged](#filechanged) durante questa sessione |1325| `watchPaths` | Array di percorsi assoluti da monitorare per gli eventi [FileChanged](#filechanged) durante questa sessione |
1248| `reloadSkills` | Booleano. Quando è `true`, Claude Code esegue una nuova scansione delle directory delle [skill](/docs/it/skills) e dei comandi dopo il completamento degli hook SessionStart, così le skill installate dall'hook sono disponibili nella stessa sessione, a partire dal primo prompt |1326| `reloadSkills` | Booleano. Quando è `true`, Claude Code analizza di nuovo le directory delle [skill](/docs/it/skills) e dei comandi dopo il completamento degli hook SessionStart. Consulta [Ricaricare le skill installate da un hook](#reload-skills-that-a-hook-installs) |
1327
1328Questo output aggiunge contesto e assegna un nome alla sessione:
1249 1329
1250```json theme={null}1330```json theme={null}
1251{1331{
1257}1337}
1258```1338```
1259 1339
1260Poiché per questo evento lo stdout semplice raggiunge già Claude, un hook che carica solo contesto può stampare direttamente su stdout senza costruire JSON. Usa la forma JSON quando devi combinare il contesto con altri campi come `sessionTitle`.1340Un hook che aggiunge solo contesto può stamparlo senza costruire JSON, perché Claude Code aggiunge lo [stdout in testo semplice](#exit-code-0) di un hook SessionStart al contesto di Claude.
1341
1342Se l'hook SessionStart del tuo plugin fornisce `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 che gli hook SessionStart sono stati eseguiti.
1343
1344<h4 id="reload-skills-that-a-hook-installs">
1345 Ricaricare le skill installate da un hook
1346</h4>
1347
1348Per rendere disponibili nella stessa sessione le skill installate da un hook SessionStart, restituisci `reloadSkills`. Il rilevamento delle skill viene normalmente eseguito prima che gli hook SessionStart terminino, quindi senza questo campo i file che un hook scrive in `~/.claude/skills/` o `.claude/skills/` possono mancare quando viene eseguito il primo prompt.
1261 1349
1262Usa `reloadSkills` quando un hook SessionStart installa o aggiorna skill. Il rilevamento delle skill normalmente viene eseguito prima che gli hook SessionStart terminino, quindi i file che l'hook scrive in `~/.claude/skills/` o `.claude/skills/` altrimenti apparirebbero solo nella sessione successiva. Questo esempio sincronizza un repository di skill condiviso e richiede la nuova scansione:1350Questo esempio sincronizza un repository di skill condiviso e richiede la nuova analisi:
1263 1351
1264```bash theme={null}1352```bash theme={null}
1265#!/bin/bash1353#!/bin/bash
1270echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1358echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1271```1359```
1272 1360
1273L'URL del repository è un segnaposto; sostituiscilo con il tuo repository di skill. Con il segnaposto, il clone fallisce e stampa un messaggio `fatal:` su stderr. Lo stderr di un hook SessionStart che esce con 0 è solo informativo, quindi la richiesta `reloadSkills` si applica comunque.1361L'URL del repository è un segnaposto. Sostituiscilo con il tuo repository di skill.
1274 1362
1275<h4 id="persist-environment-variables">1363<h4 id="persist-environment-variables">
1276 Rendere persistenti le variabili d'ambiente1364 Rendere persistenti le variabili d'ambiente
1419 1507
1420Gli hook `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 paralizza la sessione. Se il tuo hook ha bisogno di più tempo, imposta il campo `timeout` nella voce dell'hook.1508Gli hook `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 paralizza la sessione. Se il tuo hook ha bisogno di più tempo, imposta il campo `timeout` nella voce dell'hook.
1421 1509
1422A parte un hook di comando che esegui con [`async: true`](#run-hooks-in-the-background), un hook di comando, HTTP o di strumento MCP su `UserPromptSubmit` che raggiunge il timeout viene annullato e il suo output, incluso qualsiasi `additionalContext`, viene scartato. Il prompt raggiunge comunque Claude senza quel contesto. La trascrizione mostra un avviso che indica l'hook, il timeout scattato e che l'output è stato scartato.1510Fatta eccezione per un hook di comando che esegui con [`async: true`](#run-hooks-in-the-background), un hook `UserPromptSubmit` di comando, HTTP o 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"`](#block-the-action-when-a-hook-fails) su un hook di comando o HTTP. La trascrizione mostra un avviso che indica l'hook, il timeout scattato e il fatto che l'output è stato scartato.
1423 1511
1424Un [hook di callback dell'Agent SDK](/docs/it/agent-sdk/hooks) su `UserPromptSubmit` che raggiunge il timeout blocca il prompt con un messaggio che indica l'hook e il timeout, perché lì un callback può fungere da controllo di policy che non deve fallire in modo permissivo. La sessione continua. Prima della v2.1.208, un timeout di callback su quell'evento terminava il turno con un errore di esecuzione.1512Un [hook di callback dell'Agent SDK](/docs/it/agent-sdk/hooks) su `UserPromptSubmit` che raggiunge il timeout blocca il prompt con un messaggio che indica l'hook e il timeout, perché lì un callback può fungere da controllo di policy che non deve fallire in modo permissivo. La sessione continua. Prima della v2.1.208, un timeout di callback su quell'evento terminava il turno con un errore di esecuzione.
1425 1513
1860| :- | :- | :- | :- |1948| :- | :- | :- | :- |
1861| `url` | string | `"https://example.com/api"` | URL da cui recuperare il contenuto |1949| `url` | string | `"https://example.com/api"` | URL da cui recuperare il contenuto |
1862| `prompt` | string | `"Extract the API endpoints"` | Prompt da eseguire sul contenuto recuperato |1950| `prompt` | string | `"Extract the API endpoints"` | Prompt da eseguire sul contenuto recuperato |
1951| `offset` | number | `100000` | Numero facoltativo di caratteri da saltare dall'inizio della pagina. Claude lo imposta per continuare a leggere una pagina lunga. Richiede Claude Code v2.1.290 o successiva |
1863 1952
1864<h5 id="websearch">1953<h5 id="websearch">
1865 WebSearch1954 WebSearch
2112| `message` | Solo per `"deny"`: comunica a Claude perché il permesso è stato negato |2201| `message` | Solo per `"deny"`: comunica a Claude perché il permesso è stato negato |
2113| `interrupt` | Solo per `"deny"`: se `true`, ferma Claude |2202| `interrupt` | Solo per `"deny"`: se `true`, ferma Claude |
2114 2203
2115Un hook che esce con 2 senza un oggetto `decision` lascia invariato il flusso dei permessi, e il suo stderr viene scartato. Solo l'oggetto `decision` può concedere o negare la richiesta.2204Un hook che esce 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`.
2116 2205
2117```json theme={null}2206```json theme={null}
2118{2207{
2678 Controllo delle decisioni di TaskCreated2767 Controllo delle decisioni di TaskCreated
2679</h4>2768</h4>
2680 2769
2681Un hook TaskCreated può bloccare la creazione in due modi. In entrambi i casi, Claude Code elimina l'attività e restituisce il tuo messaggio a Claude come errore dello strumento. Claude Code ignora `continue: false` da questo evento e Claude continua a lavorare.2770Un 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 ignora `continue: false` da questo evento e Claude continua a lavorare.
2682 2771
2683* **Codice di uscita 2**: Claude Code restituisce il testo di stderr come messaggio.2772* **Codice di uscita 2**: Claude Code restituisce il testo di stderr come messaggio.
2684* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code restituisce `reason` come messaggio.2773* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code restituisce `reason` come messaggio.
3561 3650
3562Claude 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.3651Claude 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.
3563 3652
3564Un hook PreModelSwitch che non risponde prima del suo timeout blocca il cambio. Per [PreToolUse](#timeouts), invece, un hook di comando andato in timeout lascia proseguire la chiamata allo strumento. Il timeout predefinito per questo evento è di 30 secondi. `PreModelSwitch` esegue solo hook `command`, `http` e `mcp_tool`, quindi i valori predefiniti di `prompt` e `agent` non si applicano.3653Un hook PreModelSwitch che non risponde prima del suo timeout blocca il cambio. Per sapere cosa fa un timeout negli altri eventi, consulta [Timeout](#timeouts). Il timeout predefinito per questo evento è di 30 secondi. `PreModelSwitch` esegue solo hook `command`, `http` e `mcp_tool`, quindi i valori predefiniti di `prompt` e `agent` non si applicano.
3565 3654
3566Un hook che esce con un codice diverso da 0 o 2 e non stampa alcuna decisione JSON non blocca: Claude Code mostra il suo stderr e applica il cambio, come descritto in [Altri codici di uscita](#other-exit-codes).3655Un hook che esce con un codice diverso da 0 o 2 e non stampa alcuna decisione JSON è un errore non bloccante, come descritto in [Altri codici di uscita](#other-exit-codes).
3567 3656
3568<h3 id="postmodelswitch">3657<h3 id="postmodelswitch">
3569 PostModelSwitch3658 PostModelSwitch
4279Gli hook asincroni hanno vincoli aggiuntivi rispetto agli hook sincroni:4368Gli hook asincroni hanno vincoli aggiuntivi rispetto agli hook sincroni:
4280 4369
4281* 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 `asyncRewake` che esce con il codice 2 riattiva Claude immediatamente anche quando la sessione è inattiva.4370* 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 `asyncRewake` che esce con il codice 2 riattiva Claude immediatamente anche quando la sessione è inattiva.
4282* Ogni esecuzione crea un processo in background separato. Non c'è deduplicazione tra più attivazioni dello stesso hook asincrono.4371* Ogni esecuzione crea un processo in background separato.
4283 4372
4284<h2 id="security-considerations">4373<h2 id="security-considerations">
4285 Considerazioni sulla sicurezza4374 Considerazioni sulla sicurezza
