754Le modifiche dirette agli hook nei file di impostazioni vengono normalmente rilevate automaticamente dal file watcher.754Le modifiche dirette agli hook nei file di impostazioni vengono normalmente rilevate automaticamente dal file watcher.
755 755
756<h2 id="hook-input-and-output">756<h2 id="hook-input-and-output">
757 Input e output del hook757 Input e output dell'hook
758</h2>758</h2>
759 759
760I command hook ricevono dati JSON tramite stdin e comunicano i risultati attraverso codici di uscita, stdout e stderr. Gli HTTP hook ricevono lo stesso JSON come corpo della richiesta POST e comunicano i risultati attraverso il corpo della risposta HTTP. Questa sezione copre i campi e il comportamento comuni a tutti gli eventi. Ogni sezione dell'evento sotto [Hook events](#hook-events) include il suo schema di input specifico e le opzioni di controllo della decisione.760I command hook ricevono dati JSON tramite stdin e comunicano i risultati attraverso codici di uscita, stdout e stderr. Gli HTTP hook ricevono lo stesso JSON come corpo della richiesta POST e comunicano i risultati attraverso il corpo della risposta HTTP. Questa sezione copre i campi e il comportamento comuni a tutti gli eventi. Ogni sezione dell'evento sotto [Hook events](#hook-events) include il suo schema di input specifico e le opzioni di controllo della decisione.
761 761
762Su macOS e Linux, i command hook vengono eseguiti nella loro propria sessione senza un terminale di controllo. Il processo hook e qualsiasi processo figlio non possono aprire `/dev/tty` o inviare sequenze di escape direttamente all'interfaccia Claude Code. Windows non ha `/dev/tty`.762Su macOS e Linux, i command hook vengono eseguiti nella loro propria sessione senza un terminale di controllo. Il processo hook e qualsiasi processo figlio non possono aprire `/dev/tty` o inviare sequenze di escape direttamente all'interfaccia Claude Code. Windows non ha `/dev/tty`.
763 763
764Per visualizzare un messaggio all'utente su qualsiasi piattaforma, restituire [`systemMessage`](#json-output) nell'output JSON. Alcuni eventi lo scartano o lo consegnano altrove, e ogni [sezione dell'evento](#hook-events) lo specifica. Per attivare una notifica desktop, impostare un titolo della finestra o suonare il campanello, restituire [`terminalSequence`](#emit-terminal-notifications) invece.764Per mostrare un messaggio all'utente su qualsiasi piattaforma, restituisci [`systemMessage`](#json-output) nell'output JSON. Alcuni eventi lo scartano o lo consegnano altrove, e ogni [sezione dell'evento](#hook-events) lo specifica. Per attivare una notifica desktop, impostare un titolo della finestra o suonare il campanello, restituisci invece [`terminalSequence`](#emit-terminal-notifications).
765 765
766<h3 id="common-input-fields">766<h3 id="common-input-fields">
767 Campi di input comuni767 Campi di input comuni
772| Campo | Descrizione |772| Campo | Descrizione |
773| :- | :- |773| :- | :- |
774| `session_id` | Identificatore della sessione corrente |774| `session_id` | Identificatore della sessione corrente |
775| `prompt_id` | UUID che identifica il prompt dell'utente attualmente in elaborazione. Corrisponde all'attributo [`prompt.id` sugli eventi OpenTelemetry](/docs/it/monitoring-usage#event-correlation-attributes), quindi puoi correlare l'output del hook con la telemetria per un singolo prompt. Assente fino al primo input dell'utente |775| `prompt_id` | UUID che identifica il prompt dell'utente attualmente in elaborazione. Corrisponde all'attributo [`prompt.id` sugli eventi OpenTelemetry](/docs/it/monitoring-usage#event-correlation-attributes), quindi puoi correlare l'output dell'hook con la telemetria per un singolo prompt. Assente fino al primo input dell'utente |
776| `transcript_path` | Percorso al JSON della conversazione. Il file della trascrizione viene scritto in modo asincrono e potrebbe rimanere indietro rispetto alla conversazione in memoria, quindi potrebbe non includere ancora i messaggi più recenti del turno corrente quando un hook si attiva. Gli hook che necessitano del testo dell'assistente finale del turno corrente dovrebbero utilizzare `last_assistant_message` su [Stop](#stop) e [SubagentStop](#subagentstop) invece di leggere la trascrizione |776| `transcript_path` | Percorso al JSON della conversazione. Il file della trascrizione viene scritto in modo asincrono e potrebbe rimanere indietro rispetto alla conversazione in memoria, quindi potrebbe non includere ancora i messaggi più recenti del turno corrente quando un hook si attiva. Gli hook che necessitano del testo finale dell'assistente del turno corrente dovrebbero usare `last_assistant_message` su [Stop](#stop) e [SubagentStop](#subagentstop) invece di leggere la trascrizione |
777| `cwd` | Directory di lavoro corrente quando l'hook viene invocato |777| `cwd` | Directory di lavoro corrente quando l'hook viene invocato |
778| `scratchpad_dir` | Percorso alla [directory scratchpad della sessione](/docs/it/claude-directory#session-scratchpad-directory), dove Claude mantiene i file di lavoro temporanei. Assente quando la sessione non ha uno scratchpad o la directory temporanea non è disponibile. Richiede Claude Code v2.1.257 o successivo |778| `scratchpad_dir` | Percorso alla [directory scratchpad della sessione](/docs/it/claude-directory#session-scratchpad-directory), dove Claude mantiene i file di lavoro temporanei. Assente quando la sessione non ha uno scratchpad o la directory temporanea non è disponibile. Richiede Claude Code v2.1.257 o successivo |
779| `permission_mode` | [Modalità di autorizzazione](/docs/it/permissions#permission-modes) corrente: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` o `"bypassPermissions"`. La modalità etichettata **Manual** arriva come `"default"`, mai come `"manual"`, quindi gli script che corrispondono a `"default"` continuano a funzionare. Non tutti gli eventi ricevono questo campo. Controllare l'esempio JSON in ogni sezione [hook event](#hook-events) |779| `permission_mode` | [Modalità di permesso](/docs/it/permissions#permission-modes) corrente: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` o `"bypassPermissions"`. La modalità etichettata **Manual** arriva come `"default"`, mai come `"manual"`, quindi gli script che corrispondono a `"default"` continuano a funzionare. Non tutti gli eventi ricevono questo campo. Controlla l'esempio JSON in ogni sezione [hook event](#hook-events) |
780| `effort` | Oggetto con un campo `level` che contiene il [livello di effort](/docs/it/model-config#adjust-effort-level) in vigore quando l'hook viene eseguito: `"low"`, `"medium"`, `"high"`, `"xhigh"` o `"max"`. Se si imposta un livello che il modello attivo non supporta, `level` segnala il livello che Claude Code ha effettivamente eseguito; [Adjust effort level](/docs/it/model-config#adjust-effort-level) dice come lo sceglie. L'oggetto corrisponde al campo `effort` della [riga di stato](/docs/it/statusline#available-data). Presente per gli eventi che si attivano all'interno di un contesto di utilizzo dello strumento, come `PreToolUse`, `PostToolUse`, `Stop` e `SubagentStop`, quando il modello corrente supporta il parametro effort. Il livello è disponibile anche ai comandi hook e allo strumento Bash come variabile di ambiente `$CLAUDE_EFFORT`. |780| `effort` | Oggetto con un campo `level` che contiene il [livello di sforzo](/docs/it/model-config#adjust-effort-level) in vigore quando l'hook viene eseguito: `"low"`, `"medium"`, `"high"`, `"xhigh"` o `"max"`. Se imposti un livello che il modello attivo non supporta, `level` segnala il livello che Claude Code ha effettivamente eseguito; [Adjust effort level](/docs/it/model-config#adjust-effort-level) spiega come lo sceglie. L'oggetto corrisponde al campo `effort` della [riga di stato](/docs/it/statusline#available-data). Presente per gli eventi che si attivano all'interno di un contesto di utilizzo degli strumenti, come `PreToolUse`, `PostToolUse`, `Stop` e `SubagentStop`, quando il modello corrente supporta il parametro effort. Il livello è disponibile anche ai comandi hook e allo strumento Bash come variabile d'ambiente `$CLAUDE_EFFORT`. |
781| `hook_event_name` | Nome dell'evento che si è attivato |781| `hook_event_name` | Nome dell'evento che si è attivato |
782 782
783Quando si esegue con `--agent` o all'interno di un subagent, vengono inclusi due campi aggiuntivi:783Quando si esegue con `--agent` o all'interno di un subagent, vengono inclusi due campi aggiuntivi:
784 784
785| Campo | Descrizione |785| Campo | Descrizione |
786| :- | :- |786| :- | :- |
787| `agent_id` | Identificatore univoco per il subagent. Presente solo quando l'hook si attiva all'interno di una chiamata di subagent. Utilizzare questo per distinguere le chiamate del hook del subagent dalle chiamate del thread principale. |787| `agent_id` | Identificatore univoco per il subagent. Presente solo quando l'hook si attiva all'interno di una chiamata di subagent. Usalo per distinguere le chiamate dell'hook del subagent dalle chiamate del thread principale. |
788| `agent_type` | Nome dell'agente (ad esempio, `"Explore"` o `"security-reviewer"`). Presente quando la sessione utilizza `--agent` o l'hook si attiva all'interno di un subagent. Per i subagent, il tipo del subagent ha la precedenza sul valore `--agent` della sessione. Consultare [SubagentStart](#subagentstart) per i valori che i subagent personalizzati e plugin segnalano e come scrivere un matcher rispetto a un nome con ambito plugin. |788| `agent_type` | Nome dell'agente (ad esempio, `"Explore"` o `"security-reviewer"`). Presente quando la sessione usa `--agent` o l'hook si attiva all'interno di un subagent. Per i subagent, il tipo del subagent ha la precedenza sul valore `--agent` della sessione. Consulta [SubagentStart](#subagentstart) per i valori che i subagent personalizzati e dei plugin segnalano e per come scrivere un matcher rispetto a un nome con ambito plugin. |
789 789
790Solo gli hook [`SessionStart`](#sessionstart) possono ricevere un campo `model`, e Claude Code non lo include sempre. Gli hook [`PreModelSwitch`](#premodelswitch) e [`PostModelSwitch`](#postmodelswitch) ricevono `from_model` e `to_model` invece, quindi utilizzare un hook PostModelSwitch per seguire il modello mentre cambia durante una sessione.790Solo gli hook [`SessionStart`](#sessionstart) possono ricevere un campo `model`, e Claude Code non lo include sempre. Gli hook [`PreModelSwitch`](#premodelswitch) e [`PostModelSwitch`](#postmodelswitch) ricevono invece `from_model` e `to_model`, quindi usa un hook PostModelSwitch per seguire il modello mentre cambia durante una sessione.
791 791
792Non esiste una variabile di ambiente `$CLAUDE_MODEL`. L'hook può leggere `$ANTHROPIC_MODEL` se lo imposti nella tua shell, ma quel valore non cambia quando cambi modelli con `/model` durante una sessione.792Non esiste una variabile d'ambiente `$CLAUDE_MODEL`. L'hook può leggere `$ANTHROPIC_MODEL` se lo imposti nella tua shell, ma quel valore non cambia quando cambi modello con `/model` durante una sessione.
793 793
794Un processo hook eredita l'ambiente padre, a parte le variabili dell'esportatore `OTEL_*` che Claude Code [rimuove da ogni sottoprocesso che genera](/docs/it/monitoring-usage#administrator-configuration) e, quando [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/it/env-vars#variables) è impostato su `1`, le variabili che rimuove. In una sessione che [riceve la configurazione HIPAA](/docs/it/hipaa-setup#check-how-developers-sign-in-and-connect), Claude Code [rimuove anche le credenziali Anthropic](/docs/it/hipaa-setup#anthropic-credentials-in-commands-hooks-and-mcp-servers) dall'ambiente del hook.794Un processo hook eredita l'ambiente padre, a parte le variabili dell'esportatore `OTEL_*` che Claude Code [rimuove da ogni sottoprocesso che genera](/docs/it/monitoring-usage#administrator-configuration) e, quando [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/it/env-vars#variables) è impostato su `1`, le variabili che rimuove. In una sessione che [riceve la configurazione HIPAA](/docs/it/hipaa-setup#check-how-developers-sign-in-and-connect), Claude Code [rimuove anche le credenziali Anthropic](/docs/it/hipaa-setup#anthropic-credentials-in-commands-hooks-and-mcp-servers) dall'ambiente dell'hook.
795 795
796Ad esempio, un hook `PreToolUse` per un comando Bash riceve questo su stdin:796Ad esempio, un hook `PreToolUse` per un comando Bash riceve questo su stdin:
797 797
821 Output del codice di uscita821 Output del codice di uscita
822</h3>822</h3>
823 823
824Il codice di uscita dal comando del 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 utilizzano il modello di decisione standard, un oggetto analizzato che passa la convalida dello schema ha effetto insieme al codice. Il blocco di Exit 2 è l'unico risultato che JSON non può sovrascrivere.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.
825 825
826Due tabelle possiedono 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 onora. I campi universali come `systemMessage` funzionano su la maggior parte degli eventi e sono elencati nella tabella [JSON output](#json-output).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).
827 827
828<h4 id="exit-code-0">828<h4 id="exit-code-0">
829 Exit code 0829 Exit code 0
831 831
832Exit 0 significa successo, ed è il codice di uscita previsto quando stampi JSON per il controllo strutturato.832Exit 0 significa successo, ed è il codice di uscita previsto quando stampi JSON per il controllo strutturato.
833 833
834Per la maggior parte degli eventi, Claude Code scrive stdout nel log di debug e non lo mostra nella trascrizione. Le eccezioni sono `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart` e `PostModelSwitch`, dove Claude Code aggiunge stdout in testo semplice come contesto che Claude può vedere e su cui agire.834Per la maggior parte degli eventi, Claude Code scrive stdout nel log di debug e non lo mostra nella trascrizione. Le eccezioni sono `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart` e `PostModelSwitch`, dove Claude Code aggiunge lo stdout in testo semplice come contesto che Claude può vedere e su cui può agire.
835 835
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: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:
837 837
838* **Inizia con `{` e finisce con `}`**: Claude Code lo analizza come JSON. Quando l'output è 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.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.
839* **Inizia con `{` ma non finisce con `}`**: Claude Code lo tratta come testo semplice.839* **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.840* **Inizia con qualsiasi altra cosa**: Claude Code lo tratta come testo semplice, anche quando è un array JSON o una stringa JSON tra virgolette.
841 841
842Per gli eventi che utilizzano 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 ancora](#exit-code-2).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).
843 843
844Per gli eventi che utilizzano il modello di decisione standard, quando Claude Code tenta di analizzare il tuo stdout come JSON e non può, 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 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.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 845
846Stderr da un hook che esce 0 va solo nel log di debug, mai nella trascrizione, e Claude non lo vede. Per leggerlo tu stesso, abilita [debug logging](#debug-hooks). Per visualizzare un avviso a Claude da un hook `PostToolUse` o `PostToolUseFailure`, esci 2 invece in modo che [Claude veda stderr](#exit-code-2-behavior-per-event) anche se lo strumento è già stato eseguito.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.
847 847
848<h4 id="exit-code-2">848<h4 id="exit-code-2">
849 Exit code 2849 Exit code 2
850</h4>850</h4>
851 851
852Exit 2 significa un errore bloccante. Su [eventi che possono bloccare](#exit-code-2-behavior-per-event), exit 2 blocca indipendentemente dal fatto che stampi JSON: anche un `permissionDecision` JSON di `"allow"` non può sovrascriverlo. Claude Code legge comunque qualsiasi [JSON output](#json-output) valido su stdout. Su `Elicitation` e `ElicitationResult`, l'`hookSpecificOutput` di un hook exit-2 viene ignorato.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.
853 853
854Il messaggio di blocco è il motivo dalla decisione di blocco del tuo JSON quando ne fa una, e il tuo testo stderr altrimenti. Cosa fa il blocco varia per evento: `PreToolUse` blocca la chiamata dello 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.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.
855 855
856Un hook che esce 2 mentre stampa JSON che non supera la convalida dello schema [JSON output](#json-output) blocca comunque: Claude Code utilizza 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.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.
857 857
858Questo script blocca i comandi `rm` uscendo 2 e lascia ogni altro comando al flusso di autorizzazione normale:858Questo script blocca i comandi `rm` uscendo con 2 e lascia ogni altro comando al normale flusso dei permessi:
859 859
860```bash theme={null}860```bash theme={null}
861#!/bin/bash861#!/bin/bash
865 865
866if [[ "$command" == rm* ]]; then866if [[ "$command" == rm* ]]; then
867 echo "Blocked: rm commands are not allowed" >&2867 echo "Blocked: rm commands are not allowed" >&2
868 exit 2 # Errore bloccante: la chiamata dello strumento viene impedita868 exit 2 # Errore bloccante: la chiamata allo strumento viene impedita
869fi869fi
870 870
871exit 0 # Nessuna decisione: il flusso di autorizzazione normale si applica871exit 0 # Nessuna decisione: si applica il normale flusso dei permessi
872```872```
873 873
874<h4 id="other-exit-codes">874<h4 id="other-exit-codes">
877 877
878Qualsiasi altro codice di uscita non blocca da solo per la maggior parte degli eventi hook. Cosa accade dipende dal tuo stdout:878Qualsiasi altro codice di uscita non blocca da solo per la maggior parte degli eventi hook. Cosa accade dipende dal tuo stdout:
879 879
880* Con un oggetto analizzato che passa la convalida dello schema, per gli eventi che utilizzano il modello di decisione standard, Claude Code ignora il codice di uscita e solo JSON decide il risultato: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:
881 * Ogni campo che l'evento supporta è onorato, inclusi `permissionDecision`, `additionalContext`, `updatedInput` e `systemMessage`, e l'hook non viene segnalato come errore.881 * Ogni campo che l'evento supporta viene rispettato, inclusi `permissionDecision`, `additionalContext`, `updatedInput` e `systemMessage`, e l'hook non viene segnalato come errore.
882 * [Decision control](#decision-control) elenca i campi di decisione per evento; i campi universali come `systemMessage` seguono la tabella [JSON output](#json-output).882 * [Decision control](#decision-control) elenca i campi di decisione per evento; i campi universali come `systemMessage` seguono la tabella [JSON output](#json-output).
883* Con un oggetto analizzato che non supera la convalida dello schema, per gli eventi che utilizzano il modello di decisione standard, è lo stesso errore non bloccante di [su exit 0](#exit-code-0): l'azione procede, e l'avviso `<hook name> hook error` porta il messaggio di convalida.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) e non può, Claude Code segnala lo stesso errore non bloccante di exit 0 per gli eventi che utilizzano il modello di decisione standard. L'azione procede, e l'avviso porta il messaggio di analisi.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 [debug logging](#debug-hooks).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 886
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` non riesce nella creazione su qualsiasi uscita diversa da zero indipendentemente da ciò che dice il tuo JSON, e gli eventi che scartano completamente l'output del hook, come `StopFailure`, ignorano il tuo JSON su ogni codice di uscita, a parte i campi di effetto collaterale come `terminalSequence`, che ancora si attivano.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.
888 888
889Un hook che non può avviarsi finisce nello stesso bucket 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, guarda questo avviso alla sua prima esecuzione: un percorso digitato male in `settings.json` lascia il gate silenziosamente disabilitato.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.
890 890
891<Warning>891<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 a applicare una policy, usa `exit 2`. Gli eventi worktree differiscono: 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.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.
893</Warning>893</Warning>
894 894
895<h4 id="timeouts">895<h4 id="timeouts">
896 Timeout896 Timeout
897</h4>897</h4>
898 898
899A parte un command hook che esegui con [`async: true`](#run-hooks-in-the-background), Claude Code annulla un hook `command`, `http` o `mcp_tool` che raggiunge il suo [`timeout`](#common-fields), scartando l'output del hook, quindi su la maggior parte degli eventi un hook scaduto non rende alcuna decisione.899A parte un command hook che esegui con [`async: true`](#run-hooks-in-the-background), Claude Code annulla un hook `command`, `http` o `mcp_tool` che raggiunge il suo [`timeout`](#common-fields), scartando l'output dell'hook, quindi sulla maggior parte degli eventi un hook scaduto non produce alcuna decisione.
900 900
901Su [`PreModelSwitch`](#premodelswitch), un hook annullato al suo timeout blocca il cambio di modello. Su `PreToolUse`, le due famiglie di hook differiscono:901Su [`PreModelSwitch`](#premodelswitch), un hook annullato al suo timeout blocca il cambio di modello. Su `PreToolUse`, le due famiglie di hook si comportano diversamente:
902 902
903* Un hook `command`, `http` o `mcp_tool` scaduto non blocca la chiamata dello strumento. La chiamata continua attraverso il [flusso di autorizzazione](/docs/it/permissions) normale, quindi non contare su un hook bloccato per agire come gate.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.
904* Un hook di callback [Agent SDK](/docs/it/agent-sdk/hooks) che supera il suo timeout [blocca la chiamata dello strumento](#pretooluse).904* Un [hook di callback dell'Agent SDK](/docs/it/agent-sdk/hooks) che supera il suo timeout [blocca la chiamata allo strumento](#pretooluse).
905 905
906<h4 id="exit-code-2-behavior-per-event">906<h4 id="exit-code-2-behavior-per-event">
907 Exit code 2 behavior per event907 Exit code 2 behavior per event
908</h4>908</h4>
909 909
910Exit code 2 è il modo in cui un hook segnala "fermarsi, non farlo". L'effetto dipende dall'evento, perché alcuni eventi rappresentano azioni che possono essere bloccate (come una chiamata dello strumento che non è ancora accaduta) e altri rappresentano cose che sono già accadute o non possono essere prevenute.910Il codice di uscita 2 è il modo in cui un hook segnala "fermati, non farlo". L'effetto dipende dall'evento, perché alcuni eventi rappresentano azioni che possono essere bloccate (come una chiamata a uno strumento che non è ancora avvenuta) e altri rappresentano cose che sono già accadute o non possono essere impedite.
911 911
912| Hook event | Può bloccare? | Cosa accade su exit 2 |912| Hook event | Può bloccare? | Cosa accade con exit 2 |
913| :- | :- | :- |913| :- | :- | :- |
914| `PreToolUse` | Sì | Blocca la chiamata dello strumento |914| `PreToolUse` | Sì | Blocca la chiamata allo strumento |
915| `PermissionRequest` | No | Il codice di uscita 2 non è onorato per questo evento e il flusso di autorizzazione procede invariato. Nega attraverso l'oggetto [`decision`](#permissionrequest-decision-control) invece |915| `PermissionRequest` | No | Il codice di uscita 2 non viene rispettato per questo evento e il flusso dei permessi procede invariato. Nega invece tramite l'[oggetto `decision`](#permissionrequest-decision-control) |
916| `UserPromptSubmit` | Sì | Blocca il prompt, quindi non raggiunge mai Claude. Consultare [What a blocked prompt leaves behind](#what-a-blocked-prompt-leaves-behind) |916| `UserPromptSubmit` | Sì | Blocca il prompt, quindi non raggiunge mai Claude. Consulta [What a blocked prompt leaves behind](#what-a-blocked-prompt-leaves-behind) |
917| `UserPromptExpansion` | Sì | Blocca l'espansione |917| `UserPromptExpansion` | Sì | Blocca l'espansione |
918| `Stop` | Sì | Impedisce a Claude di fermarsi, continua la conversazione |918| `Stop` | Sì | Impedisce a Claude di fermarsi, continua la conversazione |
919| `SubagentStop` | Sì | Impedisce al subagent di fermarsi |919| `SubagentStop` | Sì | Impedisce al subagent di fermarsi |
920| `TeammateIdle` | Sì | Impedisce al compagno di squadra di andare inattivo, quindi continua a lavorare |920| `TeammateIdle` | Sì | Impedisce al compagno di squadra di andare inattivo, quindi continua a lavorare |
921| `TaskCreated` | Sì | Annulla la creazione dell'attività |921| `TaskCreated` | Sì | Annulla la creazione dell'attività |
922| `TaskCompleted` | Sì | Impedisce che l'attività sia contrassegnata come completata |922| `TaskCompleted` | Sì | Impedisce che l'attività sia contrassegnata come completata |
923| `ConfigChange` | Sì | Blocca la modifica della configurazione dall'avere effetto (tranne `policy_settings`) |923| `ConfigChange` | Sì | Impedisce che la modifica della configurazione abbia effetto (tranne `policy_settings`) |
924| `StopFailure` | No | L'output e il codice di uscita vengono ignorati, tranne `terminalSequence` |924| `StopFailure` | No | L'output e il codice di uscita vengono ignorati, tranne `terminalSequence` |
925| `PostToolUse` | No | Mostra stderr a Claude; lo strumento è già stato eseguito |925| `PostToolUse` | No | Mostra stderr a Claude; lo strumento è già stato eseguito |
926| `PostToolUseFailure` | No | Mostra stderr a Claude; lo strumento è già fallito |926| `PostToolUseFailure` | No | Mostra stderr a Claude; lo strumento è già fallito |
927| `PostToolBatch` | Sì | Interrompe il loop agentico prima della prossima chiamata del modello |927| `PostToolBatch` | Sì | Interrompe il ciclo agentico prima della successiva chiamata al modello |
928| `PermissionDenied` | No | Il codice di uscita e stderr vengono ignorati perché il rifiuto è già avvenuto. Usa JSON `hookSpecificOutput.retry: true` per dire al modello che può riprovare; Claude Code ignora `retry: true` per [no-verdict denials](#permissiondenied-decision-control) |928| `PermissionDenied` | No | Il codice di uscita e stderr vengono ignorati perché il rifiuto è già avvenuto. Usa il JSON `hookSpecificOutput.retry: true` per dire al modello che può riprovare; Claude Code ignora `retry: true` per i [no-verdict denials](#permissiondenied-decision-control) |
929| `Notification` | No | Il codice di uscita e stderr vengono ignorati |929| `Notification` | No | Il codice di uscita e stderr vengono ignorati |
930| `SubagentStart` | No | Mostra stderr solo all'utente |930| `SubagentStart` | No | Mostra stderr solo all'utente |
931| `SessionStart` | No | Mostra stderr solo all'utente |931| `SessionStart` | No | Mostra stderr solo all'utente |
932| `Setup` | No | Il codice di uscita e stderr vengono ignorati |932| `Setup` | No | Il codice di uscita e stderr vengono ignorati |
933| `SessionEnd` | No | Mostra stderr solo all'utente |933| `SessionEnd` | No | Mostra stderr solo all'utente |
934| `CwdChanged` | No | Mostra stderr solo all'utente |934| `CwdChanged` | No | Mostra stderr solo all'utente |
935| `DirectoryAdded` | No | Stderr va nel log di debug; la directory è già aggiunta |935| `DirectoryAdded` | No | Stderr va nel log di debug; la directory è già stata aggiunta |
936| `FileChanged` | No | Mostra stderr solo all'utente |936| `FileChanged` | No | Mostra stderr solo all'utente |
937| `PreCompact` | Sì | Blocca la compattazione |937| `PreCompact` | Sì | Blocca la compattazione |
938| `PostCompact` | No | Mostra stderr solo all'utente |938| `PostCompact` | No | Mostra stderr solo all'utente |
939| `PreModelSwitch` | Sì | Blocca il cambio di modello e mostra stderr all'utente |939| `PreModelSwitch` | Sì | Blocca il cambio di modello e mostra stderr all'utente |
940| `PostModelSwitch` | No | Mostra stderr solo all'utente; il modello è già cambiato |940| `PostModelSwitch` | No | Mostra stderr solo all'utente; il modello è già cambiato |
941| `Elicitation` | Sì | Nega l'elicitazione |941| `Elicitation` | Sì | Rifiuta la richiesta, e non compare alcuna finestra di dialogo |
942| `ElicitationResult` | Sì | Blocca la risposta (l'azione diventa decline) |942| `ElicitationResult` | Sì | Blocca la risposta (l'azione diventa decline) |
943| `WorktreeCreate` | Sì | Qualsiasi codice di uscita diverso da zero causa il fallimento della creazione del worktree |943| `WorktreeCreate` | Sì | Qualsiasi codice di uscita diverso da zero fa fallire la creazione del worktree |
944| `WorktreeRemove` | Sì | Qualsiasi codice di uscita diverso da zero causa il fallimento della rimozione del worktree se la directory esiste ancora dopo. Consultare [WorktreeRemove](#worktreeremove) per cosa accade alla directory |944| `WorktreeRemove` | Sì | Qualsiasi codice di uscita diverso da zero fa fallire la rimozione del worktree se la directory esiste ancora dopo. Consulta [WorktreeRemove](#worktreeremove) per cosa accade alla directory |
945| `InstructionsLoaded` | No | Il codice di uscita viene ignorato |945| `InstructionsLoaded` | No | Il codice di uscita viene ignorato |
946| `MessageDisplay` | No | Il testo originale viene visualizzato |946| `MessageDisplay` | No | Il testo originale viene visualizzato |
947 947
948Per `SessionStart`, `SubagentStart` e `PostModelSwitch`, Claude Code rende lo stderr del codice di uscita 2 nella trascrizione come un avviso `<hook name> hook error`, nello stesso modo in cui rende un [errore non bloccante](#exit-code-output). Claude non lo vede, e la sessione o il subagent procede. Per `SubagentStart`, l'avviso appare nella trascrizione del subagent stesso, non nella conversazione padre.948Per `SessionStart`, `SubagentStart` e `PostModelSwitch`, Claude Code mostra lo stderr del codice di uscita 2 nella trascrizione come un avviso `<hook name> hook error`, nello stesso modo in cui mostra un [errore non bloccante](#exit-code-output). Claude non lo vede, e la sessione o il subagent procede. Per `SubagentStart`, l'avviso appare nella trascrizione del subagent stesso, non nella conversazione padre.
949 949
950<h3 id="http-response-handling">950<h3 id="http-response-handling">
951 Gestione della risposta HTTP951 Gestione della risposta HTTP
952</h3>952</h3>
953 953
954Gli HTTP hook utilizzano i codici di stato HTTP e i corpi della risposta invece dei codici di uscita e stdout. I risultati di seguito si applicano a la maggior parte degli eventi; un evento con il suo proprio contratto di fallimento nella [tabella per evento](#exit-code-2-behavior-per-event), come `WorktreeCreate`, applica quel contratto a un hook HTTP fallito anche:954Gli HTTP hook usano i codici di stato HTTP e i corpi della risposta invece dei codici di uscita e di stdout. I risultati seguenti si applicano alla maggior parte degli eventi; un evento con un proprio contratto di fallimento nella [tabella per evento](#exit-code-2-behavior-per-event), come `WorktreeCreate`, applica quel contratto anche a un HTTP hook fallito:
955 955
956* **2xx con corpo vuoto**: successo, equivalente al codice di uscita 0 senza output956* **2xx con corpo vuoto**: successo, equivalente al codice di uscita 0 senza output
957* **2xx con corpo di oggetto JSON**: analizzato utilizzando lo stesso schema [JSON output](#json-output) dei command hook. Un corpo che non supera la convalida dello schema è un errore non bloccante957* **2xx con corpo costituito da un oggetto JSON**: analizzato usando lo stesso schema [JSON output](#json-output) dei command hook. Un corpo che non supera la convalida dello schema è un errore non bloccante
958* **2xx con qualsiasi altro corpo, come testo semplice**: errore non bloccante, gestito nello stesso modo di uno stato non-2xx. Claude Code non aggiunge il testo al contesto di Claude958* **2xx con qualsiasi altro corpo, come testo semplice**: errore non bloccante, gestito nello stesso modo di uno stato non-2xx. Claude Code non aggiunge il testo al contesto di Claude
959* **Stato non-2xx**: errore non bloccante, l'esecuzione continua959* **Stato non-2xx**: errore non bloccante, l'esecuzione continua
960* **Guasto di connessione**: errore non bloccante, l'esecuzione continua960* **Errore di connessione**: errore non bloccante, l'esecuzione continua
961* **Timeout**: l'hook viene annullato, come descritto sotto [Timeouts](#timeouts)961* **Timeout**: l'hook viene annullato, come descritto in [Timeouts](#timeouts)
962 962
963A differenza dei command hook, gli HTTP hook non possono segnalare un errore bloccante solo attraverso i codici di stato. Per bloccare una chiamata dello strumento o negare un'autorizzazione, restituire una risposta 2xx con un corpo JSON contenente i campi di decisione appropriati.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.
964 964
965<h3 id="json-output">965<h3 id="json-output">
966 Output JSON966 Output JSON
967</h3>967</h3>
968 968
969I codici di uscita ti permettono solo di bloccare o stare in silenzio, ma l'output JSON ti dà un controllo più granulare. Invece di uscire con il codice 2 per bloccare, esci 0 e stampa un oggetto JSON su stdout. Claude Code legge campi specifici da quel JSON per controllare il comportamento, incluso [decision control](#decision-control) per bloccare, consentire o escalare all'utente.969I codici di uscita ti permettono solo di bloccare o restare in silenzio, ma l'output JSON ti dà un controllo più granulare. Invece di uscire con il codice 2 per bloccare, esci con 0 e stampa un oggetto JSON su stdout. Claude Code legge campi specifici da quel JSON per controllare il comportamento, incluso il [decision control](#decision-control) per bloccare, consentire o inoltrare la decisione all'utente.
970 970
971<Note>971<Note>
972 Scegli un approccio per hook: usa i codici di uscita da soli per la segnalazione, o esci 0 e stampa JSON per il controllo strutturato. Se li mescoli, exit 2 mantiene il suo [effetto di blocco](#exit-code-2-behavior-per-event), e Claude Code legge comunque i campi JSON, con l'eccezione di elicitazione notata sotto [Exit code 2](#exit-code-2).972 Scegli un approccio per hook: usa solo i codici di uscita per la segnalazione, oppure esci con 0 e stampa JSON per il controllo strutturato. Se li mescoli, exit 2 mantiene il suo [effetto di blocco](#exit-code-2-behavior-per-event), e Claude Code legge comunque i campi JSON, con l'unica eccezione relativa all'elicitazione indicata in [Exit code 2](#exit-code-2).
973</Note>973</Note>
974 974
975Lo stdout del tuo hook deve contenere solo l'oggetto JSON. Se il tuo profilo shell stampa testo all'avvio, può interferire con l'analisi JSON. Consultare [Hook JSON has no effect](/docs/it/hooks-guide#hook-json-has-no-effect) nella guida alla risoluzione dei problemi.975Lo stdout del tuo hook deve contenere solo l'oggetto JSON. Se il profilo della tua shell stampa testo all'avvio, può interferire con l'analisi del JSON. Consulta [Hook JSON has no effect](/docs/it/hooks-guide#hook-json-has-no-effect) nella guida alla risoluzione dei problemi.
976 976
977Le stringhe di `additionalContext`, `systemMessage` e `initialUserMessage` del tuo hook, e il suo stdout semplice, sono limitate a 10.000 caratteri:977Le stringhe `additionalContext`, `systemMessage` e `initialUserMessage` di un hook, e il suo stdout semplice, sono limitate a 10.000 caratteri:
978 978
979* **Ambito**: Claude Code misura ogni stringa da sola, anche quando più hook vengono eseguiti per lo stesso evento. Per l'output JSON, ogni campo viene misurato separatamente; lo stdout semplice viene misurato nel complesso.979* **Ambito**: Claude Code misura ogni stringa singolarmente, anche quando più hook vengono eseguiti per lo stesso evento. Per l'output JSON, ogni campo viene misurato separatamente; lo stdout semplice viene misurato nel complesso.
980* **Oltre il limite**: Claude Code salva l'output in un file nella directory della sessione e lo sostituisce con il percorso del file e un'anteprima di fino ai primi 2.000 caratteri. Un grande risultato Bash valido viene gestito nello stesso modo, descritto sotto [Output limits](/docs/it/tools-reference#output-limits). A differenza di quel limite Bash, questo limite non ha un'impostazione o una variabile di ambiente per aumentarlo.980* **Oltre il limite**: Claude Code salva l'output in un file nella directory della sessione e lo sostituisce con il percorso del file e un'anteprima fino ai primi 2.000 caratteri. Un risultato Bash valido di grandi dimensioni viene gestito nello stesso modo, descritto in [Output limits](/docs/it/tools-reference#output-limits). A differenza di quel limite Bash, questo limite non ha un'impostazione o una variabile d'ambiente per aumentarlo.
981* **Lettura del file**: Claude Code non chiede a Claude di leggere il file, quindi mantieni tutto ciò che Claude deve sempre vedere entro il limite.981* **Lettura del file**: Claude Code non chiede a Claude di leggere il file, quindi mantieni entro il limite tutto ciò che Claude deve sempre vedere.
982 982
983L'oggetto JSON supporta tre tipi di campi:983L'oggetto JSON supporta tre tipi di campi:
984 984
985* **Campi universali** come `continue` sono elencati nella tabella di seguito. Ogni evento li accetta, ma alcuni eventi li scartano o consegnano `systemMessage` da qualche parte diversa dalla trascrizione. Ogni sezione dell'evento lo specifica. `terminalSequence` funziona su quegli eventi anche, con le eccezioni elencate sotto [Emit terminal notifications](#emit-terminal-notifications).985* I **campi universali** come `continue` sono elencati nella tabella seguente. Ogni evento li accetta, ma alcuni eventi li scartano o consegnano `systemMessage` in un punto diverso dalla trascrizione. Ogni sezione dell'evento lo specifica. `terminalSequence` funziona anche su quegli eventi, con le eccezioni elencate in [Emit terminal notifications](#emit-terminal-notifications).
986* **`decision` e `reason` di livello superiore** sono utilizzati da alcuni eventi per bloccare o fornire feedback.986* **`decision` e `reason` di livello superiore** sono usati da alcuni eventi per bloccare o fornire feedback.
987* **`hookSpecificOutput`** è un oggetto annidato per gli eventi che necessitano di un controllo più ricco. Richiede un campo `hookEventName` impostato sul nome dell'evento.987* **`hookSpecificOutput`** è un oggetto annidato per gli eventi che necessitano di un controllo più ricco. Richiede un campo `hookEventName` impostato sul nome dell'evento.
988 988
989| Campo | Predefinito | Descrizione |989| Campo | Predefinito | Descrizione |
990| :- | :- | :- |990| :- | :- | :- |
991| `continue` | `true` | Se `false`, Claude interrompe completamente l'elaborazione dopo l'esecuzione del hook. Ha la precedenza su qualsiasi campo di decisione specifico dell'evento |991| `continue` | `true` | Se `false`, Claude interrompe completamente l'elaborazione dopo l'esecuzione dell'hook. Ha la precedenza su qualsiasi campo di decisione specifico dell'evento |
992| `stopReason` | nessuno | Messaggio mostrato all'utente quando `continue` è `false`. Rimane nella conversazione, quindi Claude lo vede se la conversazione continua |992| `stopReason` | nessuno | Messaggio mostrato all'utente quando `continue` è `false`. Rimane nella conversazione, quindi Claude lo vede se la conversazione continua |
993| `suppressOutput` | `false` | Non ha effetto: Claude Code accetta il campo ma non agisce su di esso. Lo stdout di un hook riuscito non viene mai mostrato nella trascrizione e viene registrato nel log di debug |993| `suppressOutput` | `false` | Non ha effetto: Claude Code accetta il campo ma non agisce su di esso. Lo stdout di un hook riuscito non viene mai mostrato nella trascrizione e viene registrato nel log di debug |
994| `systemMessage` | nessuno | Messaggio di avviso mostrato all'utente. In [Agent SDK](/docs/it/agent-sdk/overview) e output [`--output-format stream-json`](/docs/it/headless), può arrivare come [`SDKInformationalMessage`](/docs/it/agent-sdk/typescript#sdkinformationalmessage) |994| `systemMessage` | nessuno | Messaggio di avviso mostrato all'utente. Nell'output dell'[Agent SDK](/docs/it/agent-sdk/overview) e di [`--output-format stream-json`](/docs/it/headless), può arrivare come [`SDKInformationalMessage`](/docs/it/agent-sdk/typescript#sdkinformationalmessage) |
995| `terminalSequence` | nessuno | Una sequenza di escape del terminale per Claude Code da emettere per conto vostro, come una notifica desktop, un titolo della finestra o un campanello. Limitato a OSC `0`/`1`/`2`/`9`/`99`/`777` e BEL. Se il valore contiene qualcosa al di fuori della lista di autorizzazione, il campo viene ignorato. Usa questo invece di scrivere su `/dev/tty`, che non è disponibile per gli hook |995| `terminalSequence` | nessuno | Una sequenza di escape del terminale che Claude Code emette per tuo conto, come una notifica desktop, un titolo della finestra o un campanello. Limitato a OSC `0`/`1`/`2`/`9`/`99`/`777` e BEL. Se il valore contiene qualcosa al di fuori dell'allowlist, il campo viene ignorato. Usalo invece di scrivere su `/dev/tty`, che non è disponibile per gli hook |
996 996
997Per fermare Claude completamente:997Per fermare Claude completamente:
998 998
1000{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }1000{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }
1001```1001```
1002 1002
1003Per gli hook `PreToolUse` e `PostToolUse`, l'arresto si applica anche quando la chiamata dello strumento fallisce o si completa mentre Claude sta ancora trasmettendo una risposta.1003Per gli hook `PreToolUse` e `PostToolUse`, l'arresto si applica anche quando la chiamata allo strumento fallisce o si completa mentre Claude sta ancora trasmettendo in streaming una risposta.
1004 1004
1005<h4 id="emit-terminal-notifications">1005<h4 id="emit-terminal-notifications">
1006 Emettere notifiche del terminale1006 Emettere notifiche del terminale
1007</h4>1007</h4>
1008 1008
1009Gli hook vengono eseguiti senza un terminale di controllo, quindi scrivere sequenze di escape direttamente su `/dev/tty` non riesce. Invece, restituire la sequenza di escape nel campo `terminalSequence` e Claude Code la emetterà per voi attraverso il suo percorso di scrittura del terminale. Questo è privo di race condition, funziona all'interno di tmux e GNU screen, e funziona su Windows dove non esiste `/dev/tty`.1009Gli hook vengono eseguiti senza un terminale di controllo, quindi scrivere sequenze di escape direttamente su `/dev/tty` non funziona. Restituisci invece la sequenza di escape nel campo `terminalSequence` e Claude Code la emette per te attraverso il proprio percorso di scrittura sul terminale. Questo è privo di race condition, funziona all'interno di tmux e GNU screen, e funziona su Windows dove non esiste `/dev/tty`.
1010 1010
1011Il campo accetta una stringa di una o più sequenze di escape nella lista di autorizzazione:1011Il campo accetta una stringa di una o più sequenze di escape presenti nell'allowlist:
1012 1012
1013* OSC `0`, `1`, `2`: titoli della finestra e dell'icona1013* OSC `0`, `1`, `2`: titoli della finestra e dell'icona
1014* OSC `9`: notifiche iTerm2, ConEmu, Windows Terminal e WezTerm, incluso `9;4` progresso della barra delle applicazioni1014* OSC `9`: notifiche di iTerm2, ConEmu, Windows Terminal e WezTerm, incluso l'avanzamento nella barra delle applicazioni `9;4`
1015* OSC `99`: notifiche Kitty1015* OSC `99`: notifiche di Kitty
1016* OSC `777`: notifiche urxvt, Ghostty e Warp1016* OSC `777`: notifiche di urxvt, Ghostty e Warp
1017* BEL nudo1017* BEL semplice
1018 1018
1019Le sequenze possono essere terminate con BEL o con ST. Qualsiasi cosa al di fuori della lista di autorizzazione, incluse le sequenze CSI del cursore e del colore, le sequenze della tavolozza OSC, i collegamenti ipertestuali OSC 8, le scritture degli appunti OSC 52 e OSC 1337, viene rifiutata e il campo viene ignorato.1019Le sequenze possono essere terminate con BEL o con ST. Qualsiasi cosa al di fuori dell'allowlist, incluse le sequenze CSI per cursore e colore, le sequenze OSC della tavolozza, i collegamenti ipertestuali OSC 8, le scritture negli appunti OSC 52 e OSC 1337, viene rifiutata e il campo viene ignorato.
1020 1020
1021Claude Code scrive la sequenza stessa quando elabora l'output del tuo hook, quindi il campo funziona su eventi che scartano `systemMessage` e `continue`, come `Notification` e `StopFailure`. Ha due limiti:1021Claude Code scrive la sequenza autonomamente quando elabora l'output del tuo hook, quindi il campo funziona sugli eventi che scartano `systemMessage` e `continue`, come `Notification` e `StopFailure`. Ha due limiti:
1022 1022
1023* Claude Code scrive la sequenza solo in una sessione interattiva, e solo mentre la sua interfaccia è sullo schermo. In modalità non interattiva con il flag `-p` e in Agent SDK, ignora il campo.1023* Claude Code scrive la sequenza solo in una sessione interattiva, e solo mentre la sua interfaccia è sullo schermo. In modalità non interattiva con il flag `-p` e nell'Agent SDK, ignora il campo.
1024* Un hook `WorktreeCreate` command non può restituire JSON, perché Claude Code legge il suo stdout come il percorso del worktree. Un hook HTTP `WorktreeCreate` restituisce JSON e può includere il campo.1024* Un command hook `WorktreeCreate` non può restituire JSON, perché Claude Code legge il suo stdout come percorso del worktree. Un HTTP hook `WorktreeCreate` restituisce JSON e può includere il campo.
1025 1025
1026L'esempio di seguito attiva una notifica desktop da un hook `Notification`. La sequenza di escape viene costruita con escape ottali `printf` in modo che i byte di controllo non compaiano mai sulla riga di comando della shell, e `jq -n --arg` costruisce l'output JSON in modo che le virgolette, le barre rovesciate e le nuove righe nel messaggio di notifica siano correttamente sfuggite:1026L'esempio seguente attiva una notifica desktop da un hook `Notification`. La sequenza di escape viene costruita con escape ottali di `printf` in modo che i byte di controllo non compaiano mai sulla riga di comando della shell, e `jq -n --arg` costruisce l'output JSON in modo che virgolette, barre rovesciate e a capo nel messaggio di notifica siano correttamente sottoposti a escape:
1027 1027
1028```bash theme={null}1028```bash theme={null}
1029#!/bin/bash1029#!/bin/bash
1041 Aggiungere contesto per Claude1041 Aggiungere contesto per Claude
1042</h4>1042</h4>
1043 1043
1044Il campo `additionalContext` passa una stringa dal tuo hook nel contesto della finestra di Claude. Claude Code avvolge la stringa in un [promemoria di sistema](/docs/it/glossary#system-reminder) e la inserisce nella conversazione nel punto in cui l'hook si è attivato. Claude legge il promemoria nella prossima richiesta del modello, ma non appare come messaggio di chat nell'interfaccia.1044Il campo `additionalContext` passa una stringa dal tuo hook nella finestra di contesto di Claude. Claude Code avvolge la stringa in un [promemoria di sistema](/docs/it/glossary#system-reminder) e la inserisce nella conversazione nel punto in cui l'hook si è attivato. Claude legge il promemoria alla successiva richiesta al modello, ma non appare come messaggio di chat nell'interfaccia.
1045 1045
1046Restituire `additionalContext` all'interno di `hookSpecificOutput` insieme al nome dell'evento:1046Restituisci `additionalContext` all'interno di `hookSpecificOutput` insieme al nome dell'evento:
1047 1047
1048```json theme={null}1048```json theme={null}
1049{1049{
1059* [SessionStart](#sessionstart) e [SubagentStart](#subagentstart): all'inizio della conversazione, prima del primo prompt1059* [SessionStart](#sessionstart) e [SubagentStart](#subagentstart): all'inizio della conversazione, prima del primo prompt
1060* [UserPromptSubmit](#userpromptsubmit) e [UserPromptExpansion](#userpromptexpansion): insieme al prompt inviato1060* [UserPromptSubmit](#userpromptsubmit) e [UserPromptExpansion](#userpromptexpansion): insieme al prompt inviato
1061* [PreToolUse](#pretooluse), [PostToolUse](#posttooluse), [PostToolUseFailure](#posttoolusefailure) e [PostToolBatch](#posttoolbatch): accanto al risultato dello strumento1061* [PreToolUse](#pretooluse), [PostToolUse](#posttooluse), [PostToolUseFailure](#posttoolusefailure) e [PostToolBatch](#posttoolbatch): accanto al risultato dello strumento
1062* [Stop](#stop) e [SubagentStop](#subagentstop): alla fine del turno. La conversazione continua in modo che Claude possa agire sul feedback. Consultare [Stop decision control](#stop-decision-control)1062* [Stop](#stop) e [SubagentStop](#subagentstop): alla fine del turno. La conversazione continua in modo che Claude possa agire sul feedback. Consulta [Stop decision control](#stop-decision-control)
1063* [PostModelSwitch](#postmodelswitch): con la prossima richiesta dopo il cambio. Consultare [PostModelSwitch decision control](#postmodelswitch-decision-control) per i tempi1063* [PostModelSwitch](#postmodelswitch): con la richiesta successiva al cambio. Consulta [PostModelSwitch decision control](#postmodelswitch-decision-control) per le tempistiche
1064 1064
1065Quando più hook restituiscono `additionalContext` per lo stesso evento, Claude riceve tutti i valori.1065Quando più hook restituiscono `additionalContext` per lo stesso evento, Claude riceve tutti i valori.
1066 1066
1067Se un valore supera 10.000 caratteri, Claude Code scrive il testo in un file nella directory della sessione e passa a Claude il percorso del file con un'anteprima di fino ai primi 2.000 caratteri invece. Claude può leggere il file, ma Claude Code non lo chiede.1067Se un valore supera i 10.000 caratteri, Claude Code scrive invece il testo in un file nella directory della sessione e passa a Claude il percorso del file con un'anteprima fino ai primi 2.000 caratteri. Claude può leggere il file, ma Claude Code non glielo chiede.
1068 1068
1069Usa `additionalContext` per informazioni che Claude dovrebbe conoscere sullo stato corrente del tuo ambiente o sull'operazione appena eseguita:1069Usa `additionalContext` per informazioni che Claude dovrebbe conoscere sullo stato corrente del tuo ambiente o sull'operazione appena eseguita:
1070 1070
1071* **Stato dell'ambiente**: il ramo corrente, la destinazione di distribuzione o i flag di funzionalità attivi1071* **Stato dell'ambiente**: il branch corrente, la destinazione del deploy o i feature flag attivi
1072* **Regole di progetto condizionali**: quale comando di test si applica al file appena modificato, quali directory sono di sola lettura in questo worktree1072* **Regole di progetto condizionali**: quale comando di test si applica al file appena modificato, quali directory sono di sola lettura in questo worktree
1073* **Dati esterni**: problemi aperti assegnati a voi, risultati CI recenti, contenuto recuperato da un servizio interno1073* **Dati esterni**: issue aperte assegnate a te, risultati CI recenti, contenuto recuperato da un servizio interno
1074 1074
1075Per le istruzioni che non cambiano mai, preferire [CLAUDE.md](/docs/it/memory). Si carica senza eseguire uno script ed è il luogo standard per le convenzioni di progetto statiche.1075Per le istruzioni che non cambiano mai, preferisci [CLAUDE.md](/docs/it/memory). Si carica senza eseguire uno script ed è il luogo standard per le convenzioni di progetto statiche.
1076 1076
1077Scrivi il testo come affermazioni fattuali piuttosto che istruzioni di sistema imperative. Frasi come "La destinazione di distribuzione è produzione" o "Questo repository utilizza `bun test`" si leggono come informazioni di progetto. Il testo inquadrato come comandi di sistema fuori banda può attivare le difese di iniezione di prompt di Claude, il che causa a Claude di far emergere il testo a voi invece di trattarlo come contesto.1077Scrivi il testo come affermazioni fattuali anziché come istruzioni di sistema imperative. Frasi come "La destinazione del deploy è la produzione" o "Questo repository usa `bun test`" si leggono come informazioni di progetto. Il testo formulato come comandi di sistema fuori banda può attivare le difese di Claude contro la prompt injection, il che porta Claude a segnalarti il testo invece di trattarlo come contesto.
1078 1078
1079Claude Code salva il testo iniettato nella trascrizione della sessione. Per gli eventi a metà sessione come `PostToolUse` o `UserPromptSubmit`, quando riprendi con `--continue` o `--resume`, Claude Code riproduce il testo salvato piuttosto che rieseguire l'hook per i turni passati, quindi i valori come timestamp o SHA di commit diventano obsoleti. Gli hook `SessionStart` vengono eseguiti di nuovo al ripristino con `source` impostato su `"resume"`, o `"fork"` se hai aggiunto `--fork-session`, quindi possono aggiornare il loro contesto.1079Claude Code salva il testo iniettato nella trascrizione della sessione. Per gli eventi a metà sessione come `PostToolUse` o `UserPromptSubmit`, quando riprendi con `--continue` o `--resume`, Claude Code riproduce il testo salvato anziché rieseguire l'hook per i turni passati, quindi valori come timestamp o SHA di commit diventano obsoleti. Gli hook `SessionStart` vengono eseguiti di nuovo alla ripresa con `source` impostato su `"resume"`, o su `"fork"` se hai aggiunto `--fork-session`, quindi possono aggiornare il loro contesto.
1080 1080
1081<h4 id="decision-control">1081<h4 id="decision-control">
1082 Controllo della decisione1082 Controllo della decisione
1083</h4>1083</h4>
1084 1084
1085Non ogni evento supporta il blocco o il controllo del comportamento attraverso JSON. Gli eventi che lo fanno utilizzano ciascuno un insieme diverso di campi per esprimere quella decisione. Usa questa tabella come riferimento rapido prima di scrivere un hook:1085Non tutti gli eventi supportano il blocco o il controllo del comportamento tramite JSON. Gli eventi che lo fanno usano ciascuno un insieme diverso di campi per esprimere quella decisione. Usa questa tabella come riferimento rapido prima di scrivere un hook:
1086 1086
1087| Eventi | Modello di decisione | Campi chiave |1087| Eventi | Modello di decisione | Campi chiave |
1088| :- | :- | :- |1088| :- | :- | :- |
1089| UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, SubagentStop, ConfigChange, PreCompact | `decision` di livello superiore | `decision: "block"`, `reason`. Stop e SubagentStop accettano anche `hookSpecificOutput.additionalContext` per [feedback non-errore che continua la conversazione](#stop-decision-control) |1089| UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, SubagentStop, ConfigChange, PreCompact | `decision` di livello superiore | `decision: "block"`, `reason`. Stop e SubagentStop accettano anche `hookSpecificOutput.additionalContext` per [feedback non di errore che continua la conversazione](#stop-decision-control) |
1090| TeammateIdle, TaskCompleted | Codice di uscita o `continue: false` | Il codice di uscita 2 blocca l'azione con feedback stderr. JSON `{"continue": false, "stopReason": "..."}` interrompe anche completamente il compagno di squadra, corrispondendo al comportamento dell'hook `Stop`; [TaskCompleted lo ignora quando lo strumento `TaskUpdate` ha attivato l'evento](#taskcompleted-decision-control) |1090| TeammateIdle, TaskCompleted | Codice di uscita o `continue: false` | Il codice di uscita 2 blocca l'azione con feedback stderr. Il JSON `{"continue": false, "stopReason": "..."}` interrompe anche completamente il compagno di squadra, come il comportamento dell'hook `Stop`; [TaskCompleted lo ignora quando è lo strumento `TaskUpdate` ad attivare l'evento](#taskcompleted-decision-control) |
1091| TaskCreated | Codice di uscita o `decision` di livello superiore | Il codice di uscita 2 o `decision: "block"` [annulla l'attività](#taskcreated-decision-control) e restituisce il messaggio a Claude. `continue: false` viene ignorato |1091| TaskCreated | Codice di uscita o `decision` di livello superiore | Il codice di uscita 2 o `decision: "block"` [annulla l'attività](#taskcreated-decision-control) e restituisce il messaggio a Claude. `continue: false` viene ignorato |
1092| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask/defer), `permissionDecisionReason` |1092| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask/defer), `permissionDecisionReason` |
1093| PreModelSwitch | `hookSpecificOutput` o `decision` di livello superiore | `permissionDecision` (allow/deny/ask), `permissionDecisionReason`. `decision: "block"` [annulla anche il cambio](#premodelswitch-decision-control) |1093| PreModelSwitch | `hookSpecificOutput` o `decision` di livello superiore | `permissionDecision` (allow/deny/ask), `permissionDecisionReason`. Anche `decision: "block"` [annulla il cambio](#premodelswitch-decision-control) |
1094| PermissionRequest | `hookSpecificOutput` | `decision.behavior` (allow/deny) |1094| PermissionRequest | `hookSpecificOutput` | `decision.behavior` (allow/deny) |
1095| PermissionDenied | `hookSpecificOutput` | `retry: true` dice al modello che può riprovare la chiamata dello strumento negata; Claude Code lo ignora per [no-verdict denials](#permissiondenied-decision-control) |1095| PermissionDenied | `hookSpecificOutput` | `retry: true` dice al modello che può riprovare la chiamata allo strumento negata; Claude Code lo ignora per i [no-verdict denials](#permissiondenied-decision-control) |
1096| WorktreeCreate | percorso return | Il command hook stampa il percorso su stdout; l'HTTP hook restituisce `hookSpecificOutput.worktreePath`. Il fallimento del hook o il percorso mancante non riesce nella creazione |1096| WorktreeCreate | restituzione del percorso | Il command hook stampa il percorso su stdout; l'HTTP hook restituisce `hookSpecificOutput.worktreePath`. Il fallimento dell'hook o un percorso mancante fa fallire la creazione |
1097| WorktreeRemove | Codice di uscita | Qualsiasi codice di uscita diverso da zero fa fallire la rimozione se la directory esiste ancora dopo. L'output JSON viene scartato |1097| WorktreeRemove | Codice di uscita | Qualsiasi codice di uscita diverso da zero fa fallire la rimozione se la directory esiste ancora dopo. L'output JSON viene scartato |
1098| Elicitation | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (valori dei campi del modulo per accept) |1098| Elicitation, ElicitationResult | `hookSpecificOutput` o `decision` di livello superiore | `action` (accept/decline/cancel), `content` (valori dei campi del modulo). Anche `decision: "block"` [rifiuta](#other-ways-to-decline-an-elicitation) |
1099| ElicitationResult | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (valori dei campi del modulo override) |
1100| MessageDisplay | `hookSpecificOutput` | `displayContent` sostituisce il testo visualizzato sullo schermo. Solo visualizzazione: la trascrizione e ciò che Claude vede mantengono l'originale |1099| MessageDisplay | `hookSpecificOutput` | `displayContent` sostituisce il testo visualizzato sullo schermo. Solo visualizzazione: la trascrizione e ciò che Claude vede mantengono l'originale |
1101| SessionStart, SubagentStart, PostModelSwitch | Solo contesto | `hookSpecificOutput.additionalContext` aggiunge contesto per Claude. SessionStart accetta anche [`initialUserMessage`, `watchPaths`, `sessionTitle` e `reloadSkills`](#sessionstart-decision-control). Nessun blocco o controllo della decisione |1100| SessionStart, SubagentStart, PostModelSwitch | Solo contesto | `hookSpecificOutput.additionalContext` aggiunge contesto per Claude. SessionStart accetta anche [`initialUserMessage`, `watchPaths`, `sessionTitle` e `reloadSkills`](#sessionstart-decision-control). Nessun blocco o controllo della decisione |
1102| Setup, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, DirectoryAdded, FileChanged | Nessuno | Nessun controllo della decisione. Utilizzato per effetti collaterali come la registrazione o la pulizia |1101| Setup, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, DirectoryAdded, FileChanged | Nessuno | Nessun controllo della decisione. Usati per effetti collaterali come il logging o la pulizia |
1103 1102
1104Alcuni eventi possono anche riscrivere il contenuto piuttosto che solo consentire o bloccare:1103Alcuni eventi possono anche riscrivere il contenuto anziché limitarsi a consentirlo o bloccarlo:
1105 1104
1106* `PreToolUse`: `updatedInput` direttamente sotto `hookSpecificOutput` sostituisce gli argomenti di uno strumento prima che venga eseguito. Consultare [PreToolUse decision control](#pretooluse-decision-control)1105* `PreToolUse`: `updatedInput` direttamente sotto `hookSpecificOutput` sostituisce gli argomenti di uno strumento prima che venga eseguito. Consulta [PreToolUse decision control](#pretooluse-decision-control)
1107* `PermissionRequest`: `updatedInput` all'interno dell'oggetto `decision`. Consultare [PermissionRequest decision control](#permissionrequest-decision-control)1106* `PermissionRequest`: `updatedInput` all'interno dell'oggetto `decision`. Consulta [PermissionRequest decision control](#permissionrequest-decision-control)
1108* `PostToolUse`: `updatedToolOutput` sostituisce il risultato dello strumento. Consultare [PostToolUse decision control](#posttooluse-decision-control)1107* `PostToolUse`: `updatedToolOutput` sostituisce il risultato dello strumento. Consulta [PostToolUse decision control](#posttooluse-decision-control)
1109* `UserPromptSubmit`: non può sostituire il prompt; solo inietta `additionalContext` insieme ad esso1108* `UserPromptSubmit`: non può sostituire il prompt; si limita a iniettare `additionalContext` insieme a esso
1110 1109
1111Per i casi di uso di redazione o trasformazione, intercettare a `PreToolUse` per gli input dello strumento in uscita e `PostToolUse` per i risultati dello strumento in entrata.1110Per i casi d'uso di oscuramento o trasformazione, intercetta in `PreToolUse` gli input degli strumenti in uscita e in `PostToolUse` i risultati degli strumenti in entrata.
1112 1111
1113Ecco esempi di ogni modello in azione:1112Ecco esempi di ogni modello in azione:
1114 1113
1115<Tabs>1114<Tabs>
1116 <Tab title="Decisione di livello superiore">1115 <Tab title="Decisione di livello superiore">
1117 L'unico valore per `decision` è `"block"`. Per consentire all'azione di procedere, omettere `decision` dal JSON, o uscire 0 senza alcun JSON:1116 L'unico valore per `decision` è `"block"`. Per consentire all'azione di procedere, ometti `decision` dal JSON, oppure esci con 0 senza alcun JSON:
1118 1117
1119 ```json theme={null}1118 ```json theme={null}
1120 {1119 {
1125 </Tab>1124 </Tab>
1126 1125
1127 <Tab title="PreToolUse">1126 <Tab title="PreToolUse">
1128 Utilizza `hookSpecificOutput` per un controllo più ricco: consentire, negare, chiedere o rinviare all'utente. Puoi anche modificare l'input dello strumento prima che venga eseguito o iniettare contesto aggiuntivo per Claude. Consultare [PreToolUse decision control](#pretooluse-decision-control) per l'insieme completo di opzioni.1127 Usa `hookSpecificOutput` per un controllo più ricco: consentire, negare o inoltrare la decisione all'utente. Puoi anche modificare l'input dello strumento prima che venga eseguito o iniettare contesto aggiuntivo per Claude. Consulta [PreToolUse decision control](#pretooluse-decision-control) per l'insieme completo di opzioni.
1129 1128
1130 ```json theme={null}1129 ```json theme={null}
1131 {1130 {
1139 </Tab>1138 </Tab>
1140 1139
1141 <Tab title="PermissionRequest">1140 <Tab title="PermissionRequest">
1142 Utilizza `hookSpecificOutput` per consentire o negare una richiesta di autorizzazione per conto dell'utente. Quando consenti, puoi anche modificare l'input dello strumento o applicare regole di autorizzazione in modo che l'utente non venga richiesto di nuovo. Consultare [PermissionRequest decision control](#permissionrequest-decision-control) per l'insieme completo di opzioni.1141 Usa `hookSpecificOutput` per consentire o negare una richiesta di permesso per conto dell'utente. Quando consenti, puoi anche modificare l'input dello strumento o applicare regole di permesso in modo che all'utente non venga chiesto di nuovo. Consulta [PermissionRequest decision control](#permissionrequest-decision-control) per l'insieme completo di opzioni.
1143 1142
1144 ```json theme={null}1143 ```json theme={null}
1145 {1144 {
1157 </Tab>1156 </Tab>
1158</Tabs>1157</Tabs>
1159 1158
1160Per esempi estesi inclusa la convalida dei comandi Bash, il filtraggio dei prompt e gli script di approvazione automatica, consultare [What you can automate](/docs/it/hooks-guide#what-you-can-automate) nella guida e l'[implementazione di riferimento del validatore di comandi Bash](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py).1159Per esempi estesi, tra cui la convalida dei comandi Bash, il filtraggio dei prompt e gli script di approvazione automatica, consulta [What you can automate](/docs/it/hooks-guide#what-you-can-automate) nella guida e l'[implementazione di riferimento del validatore di comandi Bash](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py).
1161 1160
1162<h2 id="hook-events">1161<h2 id="hook-events">
1163 Eventi degli hook1162 Eventi hook
1164</h2>1163</h2>
1165 1164
1166Ogni evento corrisponde a un punto nel ciclo di vita di Claude Code in cui gli hook possono essere eseguiti. Le sezioni seguenti sono ordinate in base al ciclo di vita: dalla configurazione della sessione, attraverso il ciclo agentico, fino alla fine della sessione. Ogni sezione descrive quando l'evento si attiva, quali matcher supporta, l'input JSON che riceve e come controllarne il comportamento tramite l'output.1165Ogni evento corrisponde a un punto del ciclo di vita di Claude Code in cui gli hook possono essere eseguiti. Le sezioni seguenti sono ordinate secondo il ciclo di vita: dalla configurazione della sessione, attraverso il ciclo agentico, fino alla fine della sessione. Ogni sezione descrive quando l'evento viene attivato, quali matcher supporta, l'input JSON che riceve e come controllare il comportamento tramite l'output.
1167 1166
1168<h3 id="sessionstart">1167<h3 id="sessionstart">
1169 SessionStart1168 SessionStart
1170</h3>1169</h3>
1171 1170
1172Viene eseguito quando Claude Code avvia una nuova sessione o riprende una sessione esistente. Utile per caricare il contesto di sviluppo, come le issue esistenti o le modifiche recenti al tuo codebase, o per configurare variabili d'ambiente. Per un contesto statico che non richiede uno script, usa invece [CLAUDE.md](/docs/it/memory).1171Viene eseguito quando Claude Code avvia una nuova sessione o riprende una sessione esistente. È utile per caricare il contesto di sviluppo, come le issue esistenti o le modifiche recenti al tuo codebase, o per impostare le variabili d'ambiente. Per un contesto statico che non richiede uno script, usa invece [CLAUDE.md](/docs/it/memory).
1173 1172
1174SessionStart viene eseguito a ogni sessione, quindi mantieni questi hook veloci. Sono supportati solo gli hook `type: "command"` e `type: "mcp_tool"`. Consulta [Campi degli hook per strumenti MCP](#mcp-tool-hook-fields) per sapere quando vengono eseguiti gli hook `mcp_tool`.1173SessionStart viene eseguito in ogni sessione, quindi mantieni questi hook veloci. Sono supportati solo gli hook `type: "command"` e `type: "mcp_tool"`. Consulta [Campi degli hook per strumenti MCP](#mcp-tool-hook-fields) per sapere quando vengono eseguiti gli hook `mcp_tool`.
1175 1174
1176Il valore del matcher corrisponde al modo in cui è stata avviata la sessione:1175Il valore del matcher corrisponde al modo in cui è stata avviata la sessione:
1177 1176
1178| Matcher | Quando si attiva |1177| Matcher | Quando viene attivato |
1179| :- | :- |1178| :- | :- |
1180| `startup` | Nuova sessione |1179| `startup` | Nuova sessione |
1181| `resume` | `--resume`, `--continue` o `/resume` |1180| `resume` | `--resume`, `--continue` o `/resume` |
1182| `clear` | `/clear` |1181| `clear` | `/clear` |
1183| `compact` | Compattazione automatica o manuale |1182| `compact` | Compattazione automatica o manuale |
1184| `fork` | Una nuova sessione derivata da una esistente: `--fork-session` con `--resume` o `--continue`, la copia in background di `/fork`, `/branch`, o una conversazione che [sposti in background](/docs/it/agent-view#from-inside-a-session) |1183| `fork` | Una nuova sessione derivata da una esistente: `--fork-session` con `--resume` o `--continue`, la copia in background di `/fork`, `/branch` o una conversazione che [sposti in background](/docs/it/agent-view#from-inside-a-session) |
1185 1184
1186Prima della v2.1.214, le sessioni derivate riportavano la sorgente `"resume"`.1185Prima della v2.1.214, le sessioni derivate riportavano come origine `"resume"`.
1187 1186
1188Quando avvii una sessione interattiva, riprendi una conversazione all'avvio con `--continue` o `--resume`, oppure esegui `/clear`, gli hook SessionStart vengono eseguiti in background. Puoi digitare subito, e una conversazione ripresa appare senza attendere gli hook. La prima risposta di Claude attende comunque il completamento degli hook, così il loro contesto raggiunge Claude.1187Quando avvii una sessione interattiva, riprendi una conversazione all'avvio con `--continue` o `--resume`, oppure esegui `/clear`, gli hook SessionStart vengono eseguiti in background. Puoi digitare subito, e una conversazione ripresa appare senza attendere gli hook. La prima risposta di Claude attende comunque il completamento degli hook, così il loro contesto raggiunge Claude.
1189 1188
1190Quando cambi conversazione con `/resume` all'interno di una sessione, il cambio invece attende il completamento degli hook. Se esegui `/clear` o passi a un'altra conversazione mentre gli hook in background sono ancora in esecuzione, nulla di ciò che restituiscono si applica alla sessione.1189Quando cambi conversazione con `/resume` all'interno di una sessione, il cambio attende invece il completamento degli hook. Se esegui `/clear` o passi a un'altra conversazione mentre gli hook in background sono ancora in esecuzione, nulla di ciò che restituiscono viene applicato alla sessione.
1191 1190
1192La stessa attesa si applica all'avvio, inclusa una sessione ripresa: un prompt che invii mentre gli hook SessionStart sono ancora in esecuzione non raggiunge Claude finché non terminano.1191La stessa attesa si applica all'avvio, anche per una sessione ripresa: un prompt che invii mentre gli hook SessionStart sono ancora in esecuzione non raggiunge Claude finché non terminano.
1193 1192
1194Durante entrambe le attese, premi `Esc` per riportare il prompt nell'input senza inviarlo. Gli hook continuano a essere eseguiti.1193Durante entrambe le attese, premi `Esc` per riportare il prompt nell'input senza inviarlo. Gli hook continuano a essere eseguiti.
1195 1194
1201 1200
1202| Campo | Descrizione |1201| Campo | Descrizione |
1203| :- | :- |1202| :- | :- |
1204| `source` | Come è iniziata la sessione: `"startup"` per le nuove sessioni, `"resume"` per le sessioni riprese, `"clear"` dopo `/clear`, `"compact"` dopo la compattazione, o `"fork"` per una nuova sessione derivata da una esistente |1203| `source` | Come è stata avviata la sessione: `"startup"` per le nuove sessioni, `"resume"` per le sessioni riprese, `"clear"` dopo `/clear`, `"compact"` dopo la compattazione o `"fork"` per una nuova sessione derivata da una esistente |
1205| `model` | L'identificatore del modello attivo. Può essere omesso, ad esempio dopo `/clear` o quando una sessione viene ripristinata tramite il recupero della conversazione, quindi verifica la presenza del campo prima di leggerlo |1204| `model` | L'identificatore del modello attivo. Può essere omesso, ad esempio dopo `/clear` o quando una sessione viene ripristinata tramite il recupero della conversazione, quindi verifica la presenza del campo prima di leggerlo |
1206| `agent_type` | Il nome dell'agente, presente quando avvii Claude Code con `claude --agent <name>` |1205| `agent_type` | Il nome dell'agente, presente quando avvii Claude Code con `claude --agent <name>` |
1207| `session_title` | Il titolo personalizzato della sessione, presente quando ne è impostato uno, ad esempio con `--name`, `/rename`, l'output `sessionTitle` di un hook o `renameSession()` dell'Agent SDK. Un hook che emette `sessionTitle` può controllare prima questo campo per evitare di sovrascrivere un titolo personalizzato esistente |1206| `session_title` | Il titolo personalizzato della sessione, presente quando ne è impostato uno, ad esempio con `--name`, `/rename`, l'output `sessionTitle` di un hook o `renameSession()` dell'Agent SDK. Un hook che emette `sessionTitle` può controllare prima questo campo per evitare di sovrascrivere un titolo personalizzato esistente |
1208 1207
1209Una sessione a cui non hai dato un nome può comunque avere un [titolo generato](/docs/it/sessions#name-your-sessions). Quel titolo non è un titolo personalizzato e non compare in `session_title`.1208Una sessione a cui non hai dato un nome può comunque avere un [titolo generato](/docs/it/sessions#name-your-sessions). Quel titolo non è un titolo personalizzato e non appare in `session_title`.
1210 1209
1211Quando `source` è `"resume"` o `"fork"` e la trascrizione contiene almeno una risposta di Claude, gli hook SessionStart ricevono anche i quattro campi seguenti. Il tuo hook può usarli per riportare quanto costa riprendere una conversazione datata prima della prima richiesta, ad esempio in un [`systemMessage`](#json-output). Questi campi richiedono Claude Code v2.1.251 o successiva.1210Quando `source` è `"resume"` o `"fork"` e la trascrizione contiene almeno una risposta di Claude, gli hook SessionStart ricevono anche i quattro campi seguenti. Il tuo hook può usarli per riportare quanto costa riprendere una conversazione inattiva prima della prima richiesta, ad esempio in un [`systemMessage`](#json-output). Questi campi richiedono Claude Code v2.1.251 o successiva.
1212 1211
1213| Campo | Descrizione |1212| Campo | Descrizione |
1214| :- | :- |1213| :- | :- |
1215| `seconds_since_last_response` | Secondi reali trascorsi dall'ultima risposta nella trascrizione ripresa |1214| `seconds_since_last_response` | Secondi di tempo reale trascorsi dall'ultima risposta nella trascrizione ripresa |
1216| `context_tokens` | Token che la prima richiesta della sessione ripresa invia di nuovo come prompt |1215| `context_tokens` | Token che la prima richiesta della sessione ripresa invia di nuovo come prompt |
1217| `prompt_cache_likely_expired` | `true` quando l'ultima risposta è più vecchia della [durata del prompt caching](/docs/it/prompt-caching#cache-lifetime) della sessione o una compattazione successiva ha sostituito la conversazione memorizzata nella cache |1216| `prompt_cache_likely_expired` | `true` quando l'ultima risposta è più vecchia della [durata della cache del prompt](/docs/it/prompt-caching#cache-lifetime) della sessione o una compattazione successiva ha sostituito la conversazione memorizzata nella cache |
1218| `estimated_cache_write_usd` | Costo stimato in dollari statunitensi della scrittura di `context_tokens` nella cache del prompt sul modello della sessione, esclusa la risposta |1217| `estimated_cache_write_usd` | Costo stimato in dollari USA per scrivere `context_tokens` nella cache del prompt sul modello della sessione, esclusa la risposta |
1219 1218
1220Questo esempio mostra l'input per una sessione ripresa 90 minuti dopo la sua ultima risposta:1219Questo esempio mostra l'input per una sessione ripresa 90 minuti dopo la sua ultima risposta:
1221 1220
1242 1241
1243| Campo | Descrizione |1242| Campo | Descrizione |
1244| :- | :- |1243| :- | :- |
1245| `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 recapitato il testo e cosa inserirvi |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 |
1246| `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 aggancia a un turno esistente, questo crea il turno |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 |
1247| `sessionTitle` | Imposta il titolo della sessione, con lo stesso effetto di `/rename`. Usalo per dare 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"` |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"` |
1248| `watchPaths` | Array di percorsi assoluti da monitorare per gli eventi [FileChanged](#filechanged) durante questa sessione |1247| `watchPaths` | Array di percorsi assoluti da monitorare per gli eventi [FileChanged](#filechanged) durante questa sessione |
1249| `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, così le skill installate dall'hook sono disponibili nella stessa sessione, a partire dal primo prompt |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 |
1250 1249
1251```json theme={null}1250```json theme={null}
1252{1251{
1258}1257}
1259```1258```
1260 1259
1261Poiché per questo evento lo stdout semplice raggiunge già Claude, un hook che carica solo contesto può stampare direttamente su stdout senza costruire JSON. Usa il formato JSON quando devi combinare il contesto con altri campi come `sessionTitle`.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`.
1262 1261
1263Usa `reloadSkills` quando un hook SessionStart installa o aggiorna delle skill. Il rilevamento delle skill viene normalmente eseguito prima che gli hook SessionStart terminino, quindi i file che l'hook scrive in `~/.claude/skills/` o `.claude/skills/` apparirebbero altrimenti solo nella sessione successiva. Questo esempio sincronizza un repository di skill condiviso e richiede la nuova analisi: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:
1264 1263
1265```bash theme={null}1264```bash theme={null}
1266#!/bin/bash1265#!/bin/bash
1271echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1270echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1272```1271```
1273 1272
1274L'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 termina con 0 è solo informativo, quindi la richiesta `reloadSkills` si applica comunque.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.
1275 1274
1276<h4 id="persist-environment-variables">1275<h4 id="persist-environment-variables">
1277 Rendere persistenti le variabili d'ambiente1276 Rendere persistenti le variabili d'ambiente
1278</h4>1277</h4>
1279 1278
1280Gli hook SessionStart hanno accesso alla variabile d'ambiente `CLAUDE_ENV_FILE`, che fornisce il percorso di un file in cui puoi rendere persistenti le variabili d'ambiente per i successivi comandi Bash.1279Gli hook SessionStart hanno accesso alla variabile d'ambiente `CLAUDE_ENV_FILE`, che fornisce un percorso di file in cui puoi rendere persistenti le variabili d'ambiente per i successivi comandi Bash.
1281 1280
1282Per impostare singole variabili d'ambiente, scrivi istruzioni `export` in `CLAUDE_ENV_FILE`. Usa l'accodamento (`>>`) per preservare le variabili impostate da altri hook:1281Per impostare singole variabili d'ambiente, scrivi istruzioni `export` in `CLAUDE_ENV_FILE`. Usa l'accodamento (`>>`) per preservare le variabili impostate da altri hook:
1283 1282
1320 Setup1319 Setup
1321</h3>1320</h3>
1322 1321
1323Si attiva solo quando avvii Claude Code con `--init-only`, oppure con `--init` o `--maintenance` in [modalità non interattiva](/docs/it/headless) con il flag `-p`. Non si attiva al normale avvio. Usalo per l'installazione una tantum di dipendenze o per una pulizia pianificata che attivi esplicitamente da CI o da script, separatamente dal normale avvio della sessione. Per l'inizializzazione per sessione, usa invece [SessionStart](#sessionstart).1322Viene attivato solo quando avvii Claude Code con `--init-only`, oppure con `--init` o `--maintenance` in [modalità non interattiva](/docs/it/headless) con il flag `-p`. Non viene attivato al normale avvio. Usalo per l'installazione una tantum di dipendenze o per una pulizia pianificata che attivi esplicitamente da CI o da script, separatamente dal normale avvio della sessione. Per l'inizializzazione per sessione, usa invece [SessionStart](#sessionstart).
1324 1323
1325Il valore del matcher corrisponde al flag CLI che ha attivato l'hook:1324Il valore del matcher corrisponde al flag CLI che ha attivato l'hook:
1326 1325
1327| Matcher | Quando si attiva |1326| Matcher | Quando viene attivato |
1328| :- | :- |1327| :- | :- |
1329| `init` | `claude --init-only` o `claude -p --init` |1328| `init` | `claude --init-only` o `claude -p --init` |
1330| `maintenance` | `claude -p --maintenance` |1329| `maintenance` | `claude -p --maintenance` |
1333 1332
1334Quando avvii o continui una conversazione con `-p`, devi anche fornire un prompt, come argomento o tramite pipe su stdin. Puoi omettere il prompt quando un hook `SessionStart` fornisce [`initialUserMessage`](#sessionstart-decision-control) o quando riprendi una sessione con una [chiamata a uno strumento differita](#defer-a-tool-call-for-later).1333Quando avvii o continui una conversazione con `-p`, devi anche fornire un prompt, come argomento o tramite pipe su stdin. Puoi omettere il prompt quando un hook `SessionStart` fornisce [`initialUserMessage`](#sessionstart-decision-control) o quando riprendi una sessione con una [chiamata a uno strumento differita](#defer-a-tool-call-for-later).
1335 1334
1336In caso di successo, `--init-only` non stampa nulla nel terminale. Per verificare che gli hook siano stati eseguiti, avvia con `claude --debug-file <path> --init-only`, sostituendo `<path>` con la posizione di un file di log, e cerca nel log le voci degli hook Setup e SessionStart.1335In caso di successo, `--init-only` non stampa nulla nel terminale. Per confermare che gli hook sono stati eseguiti, avvia con `claude --debug-file <path> --init-only`, sostituendo `<path>` con il percorso di un file di log, e controlla nel log le voci degli hook Setup e SessionStart.
1337 1336
1338Poiché Setup non si attiva a ogni avvio, un plugin che necessita di una dipendenza installata non può fare affidamento solo su Setup. Lo schema pratico è verificare la dipendenza al primo utilizzo e installarla se manca, ad esempio con un hook o una skill che controlla `${CLAUDE_PLUGIN_DATA}/node_modules` ed esegue `npm install` se assente. Consulta la [directory dei dati persistenti](/docs/it/plugins/components#path-variables-and-persistent-data) per sapere dove archiviare le dipendenze installate. Se distribuisci il tuo plugin tramite un marketplace, potresti non aver bisogno di questo schema: Claude Code [installa automaticamente le dipendenze idonee dei pacchetti Node.js](/docs/it/plugins/loading#node-js-package-dependencies) quando memorizza il plugin nella cache.1337Poiché Setup non viene attivato a ogni avvio, un plugin che necessita di una dipendenza installata non può basarsi solo su Setup. Lo schema pratico consiste nel verificare la dipendenza al primo utilizzo e installarla se manca, ad esempio con un hook o una skill che verifica la presenza di `${CLAUDE_PLUGIN_DATA}/node_modules` ed esegue `npm install` se assente. Consulta la [directory dei dati persistenti](/docs/it/plugins/components#path-variables-and-persistent-data) per sapere dove archiviare le dipendenze installate. Se distribuisci il tuo plugin tramite un marketplace, potresti non aver bisogno di questo schema: Claude Code [installa automaticamente le dipendenze dei pacchetti Node.js idonee](/docs/it/plugins/loading#node-js-package-dependencies) quando memorizza il plugin nella cache.
1339 1338
1340<h4 id="setup-input">1339<h4 id="setup-input">
1341 Input di Setup1340 Input di Setup
1357 Controllo delle decisioni di Setup1356 Controllo delle decisioni di Setup
1358</h4>1357</h4>
1359 1358
1360Gli hook Setup non possono bloccare; l'esecuzione continua con qualsiasi codice di uscita. Con ogni codice di uscita, Claude Code scarta i [campi di output JSON](#json-output) di un hook Setup, come `systemMessage`, `continue` e `hookSpecificOutput.additionalContext`. Con `-p`, lo stdout, lo stderr e il codice di uscita di un hook Setup compaiono nell'output dell'esecuzione solo come [eventi `hook_response`](/docs/it/headless#read-session-metadata) quando avvii con `--output-format stream-json --verbose`.1359Gli hook Setup non possono bloccare; l'esecuzione continua con qualsiasi codice di uscita. Con qualsiasi codice di uscita, Claude Code scarta i [campi di output JSON](#json-output) di un hook Setup, come `systemMessage`, `continue` e `hookSpecificOutput.additionalContext`. Con `-p`, lo stdout, lo stderr e il codice di uscita di un hook Setup appaiono nell'output dell'esecuzione solo come [eventi `hook_response`](/docs/it/headless#read-session-metadata) quando avvii con `--output-format stream-json --verbose`.
1361 1360
1362Gli hook Setup hanno accesso a `CLAUDE_ENV_FILE`. Le variabili scritte in quel file persistono nei successivi comandi Bash della sessione, come negli [hook SessionStart](#persist-environment-variables). Su `Setup` vengono eseguiti solo gli hook `type: "command"`. Un hook `type: "mcp_tool"` su `Setup` viene sempre saltato, come descritto in [Campi degli hook per strumenti MCP](#mcp-tool-hook-fields).1361Gli hook Setup hanno accesso a `CLAUDE_ENV_FILE`. Le variabili scritte in quel file persistono nei successivi comandi Bash della sessione, come negli [hook SessionStart](#persist-environment-variables). Su `Setup` vengono eseguiti solo gli hook `type: "command"`. Un hook `type: "mcp_tool"` su `Setup` viene sempre saltato, come descritto in [Campi degli hook per strumenti MCP](#mcp-tool-hook-fields).
1363 1362
1365 InstructionsLoaded1364 InstructionsLoaded
1366</h3>1365</h3>
1367 1366
1368Si attiva quando un file `CLAUDE.md` o `.claude/rules/*.md` viene caricato nel contesto. Questo evento si attiva all'avvio della sessione per i file caricati subito e di nuovo in seguito quando i file vengono caricati in modo differito, ad esempio quando Claude accede a una sottodirectory che contiene un `CLAUDE.md` annidato o quando corrispondono regole condizionali con frontmatter `paths:`. L'hook non supporta il blocco né il controllo delle decisioni. Viene eseguito in modo asincrono a scopo di osservabilità.1367Viene attivato quando un file `CLAUDE.md` o `.claude/rules/*.md` viene caricato nel contesto. Questo evento viene attivato all'avvio della sessione per i file caricati immediatamente e di nuovo in seguito quando i file vengono caricati in modo differito, ad esempio quando Claude accede a una sottodirectory che contiene un `CLAUDE.md` annidato o quando le regole condizionali con frontmatter `paths:` corrispondono. L'hook non supporta il blocco né il controllo delle decisioni. Viene eseguito in modo asincrono per scopi di osservabilità.
1369 1368
1370Questo evento non si attiva quando Claude [legge direttamente `AGENTS.md`](/docs/it/memory#agents-md) tramite l'impostazione **Project instructions**. Si attiva invece quando un `CLAUDE.md` importa il tuo `AGENTS.md`, con `load_reason` impostato su `include` come per qualsiasi altro file importato, e quando `CLAUDE.md` è un collegamento simbolico ad esso, come un normale caricamento di `CLAUDE.md`.1369Questo evento non viene attivato quando Claude [legge direttamente `AGENTS.md`](/docs/it/memory#agents-md) tramite l'impostazione **Project instructions**. Viene invece attivato quando un `CLAUDE.md` importa il tuo `AGENTS.md`, con `load_reason` impostato su `include` come per qualsiasi altro file importato, e quando `CLAUDE.md` è un collegamento simbolico a esso, come un normale caricamento di `CLAUDE.md`.
1371 1370
1372Il matcher viene confrontato con `load_reason`. Ad esempio, usa `"matcher": "session_start"` per attivarlo solo per i file caricati all'avvio della sessione, oppure `"matcher": "path_glob_match|nested_traversal"` per attivarlo solo per i caricamenti differiti.1371Il matcher viene confrontato con `load_reason`. Ad esempio, usa `"matcher": "session_start"` per attivarlo solo per i file caricati all'avvio della sessione, oppure `"matcher": "path_glob_match|nested_traversal"` per attivarlo solo per i caricamenti differiti.
1373 1372
1379 1378
1380| Campo | Descrizione |1379| Campo | Descrizione |
1381| :- | :- |1380| :- | :- |
1382| `file_path` | Percorso assoluto del file di istruzioni che è stato caricato |1381| `file_path` | Percorso assoluto del file di istruzioni caricato |
1383| `memory_type` | Ambito del file: `"User"`, `"Project"`, `"Local"` o `"Managed"` |1382| `memory_type` | Ambito del file: `"User"`, `"Project"`, `"Local"` o `"Managed"` |
1384| `load_reason` | Perché il file è stato caricato: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` o `"compact"`. Il valore `"compact"` si attiva quando i file di istruzioni vengono ricaricati dopo un evento di compattazione |1383| `load_reason` | Perché il file è stato caricato: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` o `"compact"`. Il valore `"compact"` viene attivato quando i file di istruzioni vengono ricaricati dopo un evento di compattazione |
1385| `globs` | Pattern glob di percorso dal frontmatter `paths:` del file, se presenti. Presente solo per i caricamenti `path_glob_match` |1384| `globs` | Pattern glob di percorso dal frontmatter `paths:` del file, se presenti. Presente solo per i caricamenti `path_glob_match` |
1386| `trigger_file_path` | Percorso del file il cui accesso ha attivato questo caricamento, per i caricamenti differiti |1385| `trigger_file_path` | Percorso del file il cui accesso ha attivato questo caricamento, per i caricamenti differiti |
1387| `parent_file_path` | Percorso del file di istruzioni padre che ha incluso questo, per i caricamenti `include` |1386| `parent_file_path` | Percorso del file di istruzioni padre che ha incluso questo, per i caricamenti `include` |
1402 Controllo delle decisioni di InstructionsLoaded1401 Controllo delle decisioni di InstructionsLoaded
1403</h4>1402</h4>
1404 1403
1405Gli hook InstructionsLoaded non hanno controllo delle decisioni. Non possono bloccare né modificare il caricamento delle istruzioni. Claude Code scarta i loro [campi di output JSON](#json-output), come `systemMessage` e `continue`. Usa questo evento per log di audit, tracciamento della conformità o osservabilità.1404Gli hook InstructionsLoaded non hanno controllo delle decisioni. Non possono bloccare né modificare il caricamento delle istruzioni. Claude Code scarta i loro [campi di output JSON](#json-output), come `systemMessage` e `continue`. Usa questo evento per il logging di audit, il monitoraggio della conformità o l'osservabilità.
1406 1405
1407<h3 id="userpromptsubmit">1406<h3 id="userpromptsubmit">
1408 UserPromptSubmit1407 UserPromptSubmit
1409</h3>1408</h3>
1410 1409
1411Viene eseguito quando viene inviato un prompt, prima che Claude lo elabori. Questo ti consente1410Viene eseguito quando viene inviato un prompt, prima che Claude lo elabori. Ti consente
1412di aggiungere contesto in base al prompt o alla conversazione, convalidare i prompt o1411di aggiungere contesto aggiuntivo in base al prompt/alla conversazione, di convalidare i prompt o
1413bloccare determinati tipi di prompt.1412di bloccare determinati tipi di prompt.
1414 1413
1415Gli hook `UserPromptSubmit` non vengono attivati solo sui prompt che digiti. Claude Code li esegue anche quando:1414Gli hook `UserPromptSubmit` non vengono attivati solo sui prompt che digiti. Claude Code li esegue anche quando:
1416 1415
1417* Viene attivata un'[attività pianificata](/docs/it/scheduled-tasks), inclusa un'iterazione di `/loop`1416* Si attiva un'[attività pianificata](/docs/it/scheduled-tasks), inclusa un'iterazione di `/loop`
1418* Un [subagent in background](/docs/it/sub-agents#run-subagents-in-foreground-or-background) riferisce alla sessione che l'ha avviato1417* Un [subagent in background](/docs/it/sub-agents#run-subagents-in-foreground-or-background) riferisce alla sessione che lo ha avviato
1419* Un [messaggio inviato da un'altra sessione](/docs/it/cross-session-messaging) arriva alla tua conversazione principale1418* Un'[altra sessione invia un messaggio](/docs/it/cross-session-messaging) alla tua conversazione principale
1420 1419
1421Gli 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 blocca la sessione. Se il tuo hook ha bisogno di più tempo, imposta il campo `timeout` nella voce dell'hook.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.
1422 1421
1423Fatta eccezione per un hook di comando che esegui con [`async: true`](#run-hooks-in-the-background), un hook `UserPromptSubmit` di comando, HTTP o di strumento MCP che raggiunge il suo timeout viene annullato e il suo output, incluso qualsiasi `additionalContext`, viene scartato. Il prompt raggiunge comunque Claude senza quel contesto. La trascrizione mostra un avviso che indica l'hook, il timeout scattato e che l'output è stato scartato.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.
1424 1423
1425Un [hook di callback dell'Agent SDK](/docs/it/agent-sdk/hooks) su `UserPromptSubmit` che raggiunge il suo timeout blocca il prompt con un messaggio che indica l'hook e il timeout, perché un callback in quel punto può fungere da controllo di policy che non deve fallire in modo permissivo. La sessione continua. Prima della v2.1.208, un timeout di callback su quell'evento terminava il turno con un errore di esecuzione.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.
1426 1425
1427<h4 id="userpromptsubmit-input">1426<h4 id="userpromptsubmit-input">
1428 Input di UserPromptSubmit1427 Input di UserPromptSubmit
1429</h4>1428</h4>
1430 1429
1431Oltre ai [campi di input comuni](#common-input-fields), gli hook UserPromptSubmit ricevono il campo `prompt` contenente il testo inviato. Il contenuto incollato che è stato compresso in un segnaposto `[Pasted text #N]` arriva espanso sul posto. Nelle sessioni in cui Claude Code [contrassegna il testo incollato per Claude](/docs/it/terminal-config#how-claude-treats-pasted-text), quel contenuto espanso si trova tra una riga `<pasted_content id="…">` e una riga `</pasted_content id="…">`, quindi tieni conto di queste righe se il tuo hook analizza il prompt.1430Oltre ai [campi di input comuni](#common-input-fields), gli hook UserPromptSubmit ricevono il campo `prompt` contenente il testo inviato. Il contenuto incollato che è stato compresso in un segnaposto `[Pasted text #N]` arriva espanso al suo posto. Nelle sessioni in cui Claude Code [contrassegna il testo incollato per Claude](/docs/it/terminal-config#how-claude-treats-pasted-text), quel contenuto espanso si trova tra una riga `<pasted_content id="…">` e una riga `</pasted_content id="…">`, quindi tieni conto di quelle righe se il tuo hook analizza il prompt.
1432 1431
1433Gli hook UserPromptSubmit ricevono anche `session_title` quando la sessione ha un titolo personalizzato, con lo stesso significato del [campo `session_title` di SessionStart](#sessionstart-input).1432Gli hook UserPromptSubmit ricevono anche `session_title` quando la sessione ha un titolo personalizzato, con lo stesso significato del [campo `session_title` di SessionStart](#sessionstart-input).
1434 1433
1447 Controllo delle decisioni di UserPromptSubmit1446 Controllo delle decisioni di UserPromptSubmit
1448</h4>1447</h4>
1449 1448
1450Gli hook `UserPromptSubmit` possono controllare se un prompt inviato viene elaborato e aggiungere contesto. Sono disponibili tutti i [campi di output JSON](#json-output).1449Gli hook `UserPromptSubmit` possono controllare se un prompt inviato viene elaborato e aggiungere contesto. Tutti i [campi di output JSON](#json-output) sono disponibili.
1451 1450
1452Ci sono due modi per aggiungere contesto alla conversazione con codice di uscita 0:1451Esistono due modi per aggiungere contesto alla conversazione con codice di uscita 0:
1453 1452
1454* **Stdout in testo semplice**: Claude Code aggiunge al contesto di Claude lo stdout che [tratta come testo semplice](#exit-code-0)1453* **Stdout in testo semplice**: Claude Code aggiunge al contesto di Claude lo stdout che [tratta come testo semplice](#exit-code-0)
1455* **JSON con `additionalContext`**: usa il formato JSON seguente per un maggiore controllo. Il campo `additionalContext` viene aggiunto come contesto1454* **JSON con `additionalContext`**: usa il formato JSON riportato sotto per un maggiore controllo. Il campo `additionalContext` viene aggiunto come contesto
1456 1455
1457Nessuno dei due canali produce una voce visibile nella trascrizione. Lo stdout semplice e il valore di `additionalContext` vengono ciascuno inseriti come promemoria di sistema che inizia con il nome dell'hook; Claude li legge entrambi. Per verificare il recapito, controlla il [log di debug](#debug-hooks).1456Nessuno dei due canali produce una voce visibile nella trascrizione. Lo stdout semplice e il valore di `additionalContext` vengono inseriti ciascuno come promemoria di sistema che inizia con il nome dell'hook; Claude li legge entrambi. Per confermare la consegna, controlla il [log di debug](#debug-hooks).
1458 1457
1459Per bloccare un prompt, restituisci un oggetto JSON con `decision` impostato su `"block"`:1458Per bloccare un prompt, restituisci un oggetto JSON con `decision` impostato su `"block"`:
1460 1459
1463| `decision` | `"block"` ferma il prompt prima che raggiunga Claude. Omettilo per consentire al prompt di procedere |1462| `decision` | `"block"` ferma il prompt prima che raggiunga Claude. Omettilo per consentire al prompt di procedere |
1464| `reason` | Mostrato all'utente quando `decision` è `"block"`. Non viene aggiunto al contesto |1463| `reason` | Mostrato all'utente quando `decision` è `"block"`. Non viene aggiunto al contesto |
1465| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt inviato. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |1464| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt inviato. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |
1466| `sessionTitle` | Imposta il titolo della sessione. Usalo per dare automaticamente un nome alle sessioni in base al contenuto del prompt |1465| `sessionTitle` | Imposta il titolo della sessione. Usalo per assegnare automaticamente un nome alle sessioni in base al contenuto del prompt |
1467| `suppressOriginalPrompt` | Se è `true` quando l'hook blocca il prompt, esclude il testo del prompt dal messaggio di blocco. Consulta [Cosa lascia un prompt bloccato](#what-a-blocked-prompt-leaves-behind) |1466| `suppressOriginalPrompt` | Se `true` quando l'hook blocca il prompt, esclude il testo del prompt dal messaggio di blocco. Consulta [Cosa lascia un prompt bloccato](#what-a-blocked-prompt-leaves-behind) |
1468 1467
1469Un hook che blocca terminando con 2 segue lo stesso percorso di `reason`: il messaggio di blocco mostra il testo di stderr all'utente e non viene aggiunto al contesto.1468Un hook che blocca uscendo con 2 segue lo stesso percorso di `reason`: il messaggio di blocco mostra all'utente il testo di stderr, che non viene aggiunto al contesto.
1470 1469
1471```json theme={null}1470```json theme={null}
1472{1471{
1485 Cosa lascia un prompt bloccato1484 Cosa lascia un prompt bloccato
1486</h4>1485</h4>
1487 1486
1488Un prompt bloccato non raggiunge mai Claude, ma il suo testo non viene rimosso ovunque. Per impostazione predefinita, il messaggio di blocco mostrato all'utente termina con `Original prompt:` seguito dal testo inviato, e Claude Code scrive quel messaggio nel file di trascrizione della sessione su disco. Per escludere il testo dal messaggio, stampa JSON con `"suppressOriginalPrompt": true` all'interno di `hookSpecificOutput`. Funziona sia che l'hook blocchi con `decision: "block"` sia che esca con 2.1487Un prompt bloccato non raggiunge mai Claude, ma il suo testo non viene rimosso ovunque. Per impostazione predefinita, il messaggio di blocco mostrato all'utente termina con `Original prompt:` seguito dal testo inviato, e Claude Code scrive quel messaggio nel file di trascrizione della sessione su disco. Per escludere il testo dal messaggio, stampa un JSON con `"suppressOriginalPrompt": true` all'interno di `hookSpecificOutput`. Funziona sia che l'hook blocchi con `decision: "block"` sia uscendo con 2.
1489 1488
1490`suppressOriginalPrompt` modifica solo il messaggio di blocco. Il testo inviato può comunque comparire in file locali come la trascrizione della sessione e la cronologia dei prompt, quindi un hook di blocco non è un modo per tenere un segreto fuori dal disco. Per limitare o rimuovere questi file, consulta [Archiviazione in testo semplice](/docs/it/claude-directory#plaintext-storage) e [Cancellare i dati locali](/docs/it/claude-directory#clear-local-data).1489`suppressOriginalPrompt` modifica solo il messaggio di blocco. Il testo inviato può comunque comparire in file locali come la trascrizione della sessione e la cronologia dei tuoi prompt, quindi un hook di blocco non è un modo per tenere un segreto fuori dal disco. Per limitare o rimuovere quei file, consulta [Archiviazione in testo semplice](/docs/it/claude-directory#plaintext-storage) e [Cancellare i dati locali](/docs/it/claude-directory#clear-local-data).
1491 1490
1492<h3 id="userpromptexpansion">1491<h3 id="userpromptexpansion">
1493 UserPromptExpansion1492 UserPromptExpansion
1495 1494
1496Viene eseguito quando un comando digitato dall'utente si espande in un prompt prima di raggiungere Claude. Usalo per impedire l'invocazione diretta di comandi specifici, inserire contesto per una particolare skill o registrare quali comandi invocano gli utenti. Ad esempio, un hook che corrisponde a `deploy` può bloccare `/deploy` a meno che non sia presente un file di approvazione, oppure un hook che corrisponde a una skill di revisione può aggiungere la checklist di revisione del team come `additionalContext`.1495Viene eseguito quando un comando digitato dall'utente si espande in un prompt prima di raggiungere Claude. Usalo per impedire l'invocazione diretta di comandi specifici, inserire contesto per una particolare skill o registrare quali comandi invocano gli utenti. Ad esempio, un hook che corrisponde a `deploy` può bloccare `/deploy` a meno che non sia presente un file di approvazione, oppure un hook che corrisponde a una skill di revisione può aggiungere la checklist di revisione del team come `additionalContext`.
1497 1496
1498Questo evento copre il percorso che `PreToolUse` non copre: un hook `PreToolUse` che corrisponde allo strumento `Skill` si attiva solo quando Claude chiama lo strumento, ma digitare direttamente `/skillname` aggira `PreToolUse`. `UserPromptExpansion` si attiva su quel percorso diretto.1497Questo evento copre il percorso che `PreToolUse` non copre: un hook `PreToolUse` che corrisponde allo strumento `Skill` viene attivato solo quando Claude chiama lo strumento, ma digitare direttamente `/skillname` aggira `PreToolUse`. `UserPromptExpansion` viene attivato su quel percorso diretto.
1499 1498
1500Effettua la corrispondenza su `command_name`. Lascia vuoto il matcher per attivarlo su ogni comando di tipo prompt.1499Corrisponde su `command_name`. Lascia vuoto il matcher per attivarlo su ogni comando di tipo prompt.
1501 1500
1502<h4 id="userpromptexpansion-input">1501<h4 id="userpromptexpansion-input">
1503 Input di UserPromptExpansion1502 Input di UserPromptExpansion
1524 Controllo delle decisioni di UserPromptExpansion1523 Controllo delle decisioni di UserPromptExpansion
1525</h4>1524</h4>
1526 1525
1527Gli hook `UserPromptExpansion` possono bloccare l'espansione o aggiungere contesto. Sono disponibili tutti i [campi di output JSON](#json-output).1526Gli hook `UserPromptExpansion` possono bloccare l'espansione o aggiungere contesto. Tutti i [campi di output JSON](#json-output) sono disponibili.
1528 1527
1529| Campo | Descrizione |1528| Campo | Descrizione |
1530| :- | :- |1529| :- | :- |
1532| `reason` | Mostrato all'utente quando `decision` è `"block"` |1531| `reason` | Mostrato all'utente quando `decision` è `"block"` |
1533| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt espanso. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |1532| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt espanso. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |
1534 1533
1535Un hook che blocca terminando con 2 segue lo stesso percorso di `reason`: il messaggio di blocco mostra il testo di stderr all'utente.1534Un hook che blocca uscendo con 2 segue lo stesso percorso di `reason`: il messaggio di blocco mostra all'utente il testo di stderr.
1536 1535
1537```json theme={null}1536```json theme={null}
1538{1537{
1549 MessageDisplay1548 MessageDisplay
1550</h3>1549</h3>
1551 1550
1552Viene eseguito mentre un messaggio dell'assistente viene trasmesso sullo schermo. Claude Code mostra il messaggio a incrementi: ogni volta che un gruppo di righe appena completate è pronto per essere visualizzato, l'hook viene eseguito una volta con quelle righe e Claude Code visualizza al loro posto il testo sostitutivo dell'hook. Un messaggio lungo produce diverse chiamate; un messaggio breve può produrne una sola.1551Viene eseguito mentre un messaggio dell'assistente viene trasmesso sullo schermo. Claude Code mostra il messaggio a incrementi: ogni volta che un gruppo di righe appena completate è pronto per essere visualizzato, l'hook viene eseguito una volta con quelle righe e Claude Code visualizza al loro posto il testo sostitutivo dell'hook. Un messaggio lungo produce diverse chiamate; un messaggio breve può produrne solo una.
1553 1552
1554Usa MessageDisplay per:1553Usa MessageDisplay per:
1555 1554
1556* rimuovere il markdown per una visualizzazione minimale1555* rimuovere il markdown per una visualizzazione minimale
1557* trasformare il testo che un'applicazione Agent SDK mostra ai suoi utenti1556* trasformare il testo che un'applicazione dell'Agent SDK mostra ai suoi utenti
1558* oscurare chiavi API o nomi host interni dalle risposte di Claude1557* oscurare chiavi API o nomi host interni dalle risposte di Claude
1559 1558
1560Claude Code trattiene ogni gruppo finché il tuo hook non restituisce, quindi mantieni l'hook veloce. Se l'hook fallisce o va in timeout, Claude Code mostra il testo originale. Il timeout predefinito per questo evento è di 10 secondi; se il tuo hook ha bisogno di più tempo, imposta il campo `timeout` nella voce dell'hook.1559Claude Code trattiene ogni gruppo finché il tuo hook non restituisce un risultato, quindi mantieni l'hook veloce. Se l'hook fallisce o va in timeout, Claude Code visualizza il testo originale. Il timeout predefinito per questo evento è di 10 secondi; se il tuo hook ha bisogno di più tempo, imposta il campo `timeout` nella voce dell'hook.
1561 1560
1562MessageDisplay riguarda solo la visualizzazione: il testo sostitutivo cambia solo ciò che viene mostrato sullo schermo. La trascrizione e ciò che vede Claude mantengono il testo originale, quindi Claude non vede mai la sostituzione, e la modalità verbose mostra l'originale. L'hook riceve solo il testo dei messaggi dell'assistente, quindi i risultati degli strumenti e il testo che digiti vengono visualizzati senza modifiche.1561MessageDisplay riguarda solo la visualizzazione: il testo sostitutivo cambia solo ciò che viene mostrato sullo schermo. La trascrizione e ciò che vede Claude mantengono il testo originale, quindi Claude non vede mai la sostituzione, e la modalità verbose mostra l'originale. L'hook riceve solo il testo dei messaggi dell'assistente, quindi i risultati degli strumenti e il testo che digiti vengono visualizzati invariati.
1563 1562
1564MessageDisplay non supporta i matcher e si attiva per ogni messaggio dell'assistente che trasmette testo; i messaggi senza testo, come le risposte composte solo da chiamate agli strumenti, non lo attivano.1563MessageDisplay non supporta i matcher e viene attivato per ogni messaggio dell'assistente che trasmette testo; i messaggi senza testo, come le risposte composte solo da chiamate a strumenti, non lo attivano.
1565 1564
1566Nelle esecuzioni non interattive, incluse le query dell'Agent SDK e `claude -p`, MessageDisplay viene eseguito una volta per messaggio dell'assistente invece che una volta per gruppo di righe. La singola chiamata arriva dopo il completamento del messaggio e contiene il testo completo del messaggio: `index` è `0`, `final` è `true` e `delta` contiene l'intero messaggio. Un hook che raccoglie il testo `delta` di ogni messaggio riceve lo stesso testo totale in entrambe le modalità.1565Nelle esecuzioni non interattive, incluse le query dell'Agent SDK e `claude -p`, MessageDisplay viene eseguito una volta per messaggio dell'assistente anziché una volta per gruppo di righe. L'unica chiamata arriva dopo il completamento del messaggio e contiene il testo completo del messaggio: `index` è `0`, `final` è `true` e `delta` contiene l'intero messaggio. Un hook che raccoglie il testo `delta` per ogni messaggio riceve lo stesso testo totale in entrambe le modalità.
1567 1566
1568<h4 id="messagedisplay-input">1567<h4 id="messagedisplay-input">
1569 Input di MessageDisplay1568 Input di MessageDisplay
1570</h4>1569</h4>
1571 1570
1572Oltre ai [campi di input comuni](#common-input-fields), gli hook MessageDisplay ricevono gli identificatori del turno e del messaggio, la posizione di questa chiamata all'interno del messaggio e il nuovo testo in `delta`. I limiti dei gruppi dipendono da come viene trasmesso il testo, quindi usa `index` e `final` per seguire l'avanzamento in un messaggio invece di aspettarti che le righe siano raggruppate in un modo particolare.1571Oltre ai [campi di input comuni](#common-input-fields), gli hook MessageDisplay ricevono gli identificatori del turno e del messaggio, la posizione di questa chiamata all'interno del messaggio e il nuovo testo in `delta`. I confini dei gruppi dipendono da come viene trasmesso il testo, quindi usa `index` e `final` per tracciare l'avanzamento all'interno di un messaggio anziché aspettarti che le righe siano raggruppate in un modo particolare.
1573 1572
1574| Campo | Descrizione |1573| Campo | Descrizione |
1575| :- | :- |1574| :- | :- |
1576| `turn_id` | UUID del turno corrente |1575| `turn_id` | UUID del turno corrente |
1577| `message_id` | UUID del messaggio dell'assistente visualizzato. Stabile in tutti i gruppi dello stesso messaggio. Non è l'id API `msg_…`, quindi non può essere correlato con gli id dei messaggi della trascrizione |1576| `message_id` | UUID del messaggio dell'assistente visualizzato. Stabile in tutti i gruppi dello stesso messaggio. Non è l'id `msg_…` dell'API, quindi non può essere correlato con gli id dei messaggi della trascrizione |
1578| `index` | Indice a base zero di questo gruppo all'interno del messaggio |1577| `index` | Indice a base zero di questo gruppo all'interno del messaggio |
1579| `final` | `true` nell'ultimo gruppo del messaggio. Ogni messaggio ha esattamente un gruppo finale |1578| `final` | `true` sull'ultimo gruppo del messaggio. Ogni messaggio ha esattamente un gruppo finale |
1580| `delta` | Le righe appena completate dal gruppo precedente, inclusi i caratteri di nuova riga finali. Sempre righe intere, tranne il gruppo finale che può terminare a metà riga. Nelle esecuzioni interattive, il delta del gruppo finale è vuoto quando il messaggio termina con una nuova riga, quindi considera `final`, e non un delta non vuoto, come segnale di fine messaggio. Nelle esecuzioni Agent SDK e `claude -p`, la singola chiamata contiene l'intero messaggio |1579| `delta` | Le righe appena completate dal gruppo precedente, inclusi i caratteri di nuova riga finali. Sempre righe intere, tranne il gruppo finale, che può terminare a metà riga. Nelle esecuzioni interattive, il delta del gruppo finale è vuoto quando il messaggio termina con una nuova riga, quindi considera `final`, e non un delta non vuoto, come segnale di fine messaggio. Nelle esecuzioni dell'Agent SDK e di `claude -p`, l'unica chiamata contiene l'intero messaggio |
1581 1580
1582```json theme={null}1581```json theme={null}
1583{1582{
1664 }1663 }
1665 ```1664 ```
1666 1665
1667 Il flag `-NoProfile` salta il caricamento del tuo profilo PowerShell così l'hook si avvia rapidamente, e `-ExecutionPolicy Bypass` permette a PowerShell di eseguire il file di script locale.1666 Il flag `-NoProfile` salta il caricamento del tuo profilo PowerShell in modo che l'hook si avvii rapidamente, e `-ExecutionPolicy Bypass` consente a PowerShell di eseguire il file di script locale.
1668 1667
1669 Salva questo script in `.claude/hooks/plain-display.ps1` nel tuo progetto:1668 Salva questo script in `.claude/hooks/plain-display.ps1` nel tuo progetto:
1670 1669
1681 </Tab>1680 </Tab>
1682</Tabs>1681</Tabs>
1683 1682
1684I gruppi senza markdown passano invariati. Se lo script fallisce, ad esempio perché manca `jq`, Claude Code mostra il testo originale e segnala l'errore solo nell'[output di debug](#debug-hooks), non nella sessione.1683I gruppi senza markdown passano invariati. Se lo script fallisce, ad esempio perché `jq` manca, Claude Code visualizza il testo originale e segnala l'errore solo nell'[output di debug](#debug-hooks), non nella sessione.
1685 1684
1686<h3 id="pretooluse">1685<h3 id="pretooluse">
1687 PreToolUse1686 PreToolUse
1688</h3>1687</h3>
1689 1688
1690Viene eseguito dopo che Claude ha creato i parametri dello strumento e prima di elaborare la chiamata allo strumento. Effettua la corrispondenza su qualsiasi nome di strumento tranne `EndConversation`: strumenti integrati come `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion` e `ExitPlanMode`, e qualsiasi [nome di strumento MCP](#match-mcp-tools).1689Viene eseguito dopo che Claude ha creato i parametri dello strumento e prima di elaborare la chiamata allo strumento. Corrisponde a qualsiasi nome di strumento tranne `EndConversation`: strumenti integrati come `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion` e `ExitPlanMode`, e qualsiasi [nome di strumento MCP](#match-mcp-tools).
1691 1690
1692Per eseguire un hook quando un file specifico cambia su disco, indipendentemente da chi l'ha scritto, usa [FileChanged](#filechanged) invece di far corrispondere per nome gli strumenti di modifica dei file. A differenza di PreToolUse, Claude Code esegue gli hook FileChanged dopo la modifica, e questi non hanno controllo delle decisioni, quindi non possono bloccare la scrittura.1691Per eseguire un hook quando un file specifico cambia su disco, indipendentemente da chi lo ha scritto, usa [FileChanged](#filechanged) anziché far corrispondere per nome gli strumenti di modifica dei file. A differenza di PreToolUse, Claude Code esegue gli hook FileChanged dopo la modifica, e questi non hanno controllo delle decisioni, quindi non possono bloccare la scrittura.
1693 1692
1694<Warning>1693<Warning>
1695 PreToolUse viene eseguito solo quando Claude chiama uno strumento. I file che [fai riferimento con `@` nel tuo prompt](/docs/it/common-workflows#reference-files-and-directories) vengono aggiunti senza alcuna chiamata a uno strumento: Claude Code ne inserisce il contenuto durante la costruzione del prompt, quindi nessun hook PreToolUse si attiva per essi, inclusi gli hook che corrispondono a `Read`. Per bloccare percorsi specifici dai riferimenti `@`, usa invece una [regola deny di `Read`](/docs/it/permissions#read-and-edit).1694 PreToolUse viene eseguito solo quando Claude chiama uno strumento. I file a cui [fai riferimento con `@` nel tuo prompt](/docs/it/common-workflows#reference-files-and-directories) vengono aggiunti senza alcuna chiamata a uno strumento: Claude Code inserisce il loro contenuto durante la costruzione del prompt, quindi per essi non viene attivato alcun hook PreToolUse, inclusi gli hook che corrispondono a `Read`. Per impedire che percorsi specifici vengano referenziati con `@`, usa invece una [regola di negazione `Read`](/docs/it/permissions#read-and-edit).
1696 1695
1697 PreToolUse inoltre non si attiva per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).1696 PreToolUse inoltre non viene attivato per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).
1698</Warning>1697</Warning>
1699 1698
1700Usa il [controllo delle decisioni di PreToolUse](#pretooluse-decision-control) per consentire, negare, chiedere o differire la chiamata allo strumento.1699Usa il [controllo delle decisioni di PreToolUse](#pretooluse-decision-control) per consentire, negare, chiedere o differire la chiamata allo strumento.
1701 1700
1702Un [hook di callback dell'Agent SDK](/docs/it/agent-sdk/hooks) su `PreToolUse` che supera il suo timeout blocca la chiamata allo strumento, e Claude riceve un risultato di errore che indica il timeout. Un deny esplicito restituito da un altro hook ha comunque la precedenza.1701Un [hook di callback dell'Agent SDK](/docs/it/agent-sdk/hooks) su `PreToolUse` che supera il timeout blocca la chiamata allo strumento, e Claude riceve un risultato di errore che indica il timeout. Una negazione esplicita restituita da un altro hook ha comunque la precedenza.
1703 1702
1704<h4 id="pretooluse-input">1703<h4 id="pretooluse-input">
1705 Input di PreToolUse1704 Input di PreToolUse
1707 1706
1708Oltre ai [campi di input comuni](#common-input-fields), gli hook PreToolUse ricevono `tool_name`, `tool_input` e `tool_use_id`.1707Oltre ai [campi di input comuni](#common-input-fields), gli hook PreToolUse ricevono `tool_name`, `tool_input` e `tool_use_id`.
1709 1708
1710Per uno [strumento MCP](#match-mcp-tools), l'input contiene anche `mcp_server`, un oggetto con il `name` del server e un `source` che indica da dove proviene la definizione del server. I valori di `source` includono `plugin`, `sdk` e ambiti di configurazione come `user` e `project`. [`McpServerProvenance`](/docs/it/agent-sdk/typescript#mcpserverprovenance) nel riferimento dell'Agent SDK li elenca tutti e spiega come trattarne uno che non riconosci. Basa le decisioni di fiducia su `source` anziché su `name` o sul prefisso `mcp__<server>__` del nome dello strumento. Il campo `mcp_server` richiede Claude Code v2.1.274 o successiva.1709Per uno [strumento MCP](#match-mcp-tools), l'input contiene anche `mcp_server`, un oggetto con il `name` del server e un `source` che indica da dove proviene la definizione del server. I valori di `source` includono `plugin`, `sdk` e ambiti di configurazione come `user` e `project`. [`McpServerProvenance`](/docs/it/agent-sdk/typescript#mcpserverprovenance) nel riferimento dell'Agent SDK li elenca tutti e spiega come trattare un valore che non riconosci. Basa le decisioni di fiducia su `source` anziché su `name` o sul prefisso del nome dello strumento `mcp__<server>__`. Il campo `mcp_server` richiede Claude Code v2.1.274 o successiva.
1711 1710
1712Per gli strumenti sui file `Write`, `Edit` e `Read`, `tool_input.file_path` è sempre assoluto:1711Per gli strumenti di file `Write`, `Edit` e `Read`, `tool_input.file_path` è sempre assoluto:
1713 1712
1714* Claude Code espande `~` e i percorsi relativi prima che gli hook vengano eseguiti, quindi un hook che effettua la corrispondenza sui percorsi non può essere aggirato tramite `~` o una forma relativa dello stesso percorso1713* Claude Code espande `~` e i percorsi relativi prima dell'esecuzione degli hook, quindi un hook che corrisponde sui percorsi non può essere aggirato tramite `~` o una scrittura relativa dello stesso percorso
1715* Su Windows, il percorso arriva con separatori backslash, anche quando il tuo hook viene eseguito in Git Bash dove `$PWD` appare come `/c/project`1714* Su Windows, il percorso arriva con separatori backslash, anche quando il tuo hook viene eseguito in Git Bash dove `$PWD` appare come `/c/project`
1716* Un confronto scritto con slash, come un controllo `/src/`, non corrisponde mai a un percorso con backslash, e la chiamata allo strumento procede come se l'hook non avesse nulla da bloccare1715* Un confronto scritto con le barre normali, come un controllo su `/src/`, non corrisponde mai a un percorso con backslash, e la chiamata allo strumento procede come se l'hook non avesse nulla da bloccare
1717* Normalizza i separatori prima di confrontare: `FILE_PATH="${FILE_PATH//\\//}"` in Bash, o `file_path.replace("\\", "/")` in Python, poi fai corrispondere un segmento di percorso come `/src/` anziché ancorare con `^`, poiché il percorso è assoluto1716* Normalizza i separatori prima del confronto: `FILE_PATH="${FILE_PATH//\\//}"` in Bash, oppure `file_path.replace("\\", "/")` in Python, poi fai corrispondere un segmento di percorso come `/src/` anziché ancorare con `^`, poiché il percorso è assoluto
1718 1717
1719Una chiamata `Write` su Windows fornisce:1718Una chiamata `Write` su Windows fornisce:
1720 1719
1747| `timeout` | number | `120000` | Timeout facoltativo in millisecondi. I valori superiori al [massimo](/docs/it/tools-reference#bash-tool-behavior) vengono ridotti al massimo anziché rifiutati |1746| `timeout` | number | `120000` | Timeout facoltativo in millisecondi. I valori superiori al [massimo](/docs/it/tools-reference#bash-tool-behavior) vengono ridotti al massimo anziché rifiutati |
1748| `run_in_background` | boolean | `false` | Se eseguire il comando in background |1747| `run_in_background` | boolean | `false` | Se eseguire il comando in background |
1749 1748
1750Quando un comando Bash modifica file in un repository Git, Claude Code può registrare cosa è cambiato. Registra le modifiche in ogni modalità di permesso quando l'impostazione [`bashEditDiffEnabled`](/docs/it/settings-reference#basheditdiffenabled) attiva la registrazione; la voce di quell'impostazione indica quali file possono impostarla. Altrimenti le registra solo in modalità auto e in modalità `bypassPermissions`, e solo quando Claude Code indica a Claude di modificare i file tramite Bash. Imposta `bashEditDiffEnabled` su `false` per disattivare la registrazione. I comandi in background e i comandi di sola lettura non includono alcun diff.1749Quando un comando Bash modifica file in un repository Git, Claude Code può registrare cosa è cambiato. Registra le modifiche in ogni modalità di permesso quando l'impostazione [`bashEditDiffEnabled`](/docs/it/settings-reference#basheditdiffenabled) attiva la registrazione; la voce di quell'impostazione indica quali file possono impostarla. Altrimenti le registra solo in modalità auto e in modalità `bypassPermissions`, e solo quando Claude Code indica a Claude di modificare i file tramite Bash. Imposta `bashEditDiffEnabled` su `false` per disattivare la registrazione. I comandi in background e i comandi di sola lettura non contengono alcun diff.
1751 1750
1752Il tuo [hook PostToolUse](#posttooluse) riceve quindi i file modificati in `tool_response.bashEditDiff`. L'elenco copre ciò che è cambiato nel repository durante l'esecuzione del comando. I file ignorati da Git e i file nei submodule non sono elencati. Richiede Claude Code v2.1.269 o successiva.1751Il tuo [hook PostToolUse](#posttooluse) riceve quindi i file modificati in `tool_response.bashEditDiff`. L'elenco copre ciò che è cambiato nel repository durante l'esecuzione del comando. I file ignorati da Git e i file nei submodule non sono elencati. Richiede Claude Code v2.1.269 o successiva.
1753 1752
1754<Note>1753<Note>
1755 L'elenco è fornito al meglio delle possibilità ed è in beta pubblica. Claude Code può perdere una modifica, includere un file che un altro processo ha modificato nello stesso momento o fermarsi ai suoi limiti di dimensione. La struttura del campo potrebbe cambiare. Usa l'elenco per trovare cosa revisionare, non per applicare una policy.1754 L'elenco è fornito al meglio delle possibilità ed è in beta pubblica. Claude Code può non rilevare una modifica, includere un file che un altro processo ha modificato nello stesso momento o fermarsi ai propri limiti di dimensione. La struttura del campo potrebbe cambiare. Usa l'elenco per capire cosa rivedere, non per applicare una policy.
1756</Note>1755</Note>
1757 1756
1758`changedFiles` e `files` elencano ciò che il comando ha modificato; i campi rimanenti indicano quanto è completo e quanto è affidabile quell'elenco.1757`changedFiles` e `files` elencano ciò che il comando ha modificato; i campi rimanenti indicano quanto è completo e affidabile quell'elenco.
1759 1758
1760| Campo | Tipo | Esempio | Descrizione |1759| Campo | Tipo | Esempio | Descrizione |
1761| :- | :- | :- | :- |1760| :- | :- | :- | :- |
1762| `changedFiles` | array | `["/path/to/src/app.ts"]` | Percorsi assoluti dei file modificati dal comando, al massimo 200. Presente ogni volta che `files` contiene un diff o `moreFiles` è maggiore di zero |1761| `changedFiles` | array | `["/path/to/src/app.ts"]` | Percorsi assoluti dei file modificati dal comando, al massimo 200. Presente ogni volta che `files` contiene un diff o `moreFiles` è superiore a zero |
1763| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | Diff di un massimo di 5 file modificati, per la visualizzazione. `created` o `deleted` è `true` per un file che il comando ha aggiunto o rimosso |1762| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | Diff di un massimo di 5 file modificati, per la visualizzazione. `created` o `deleted` è `true` per un file che il comando ha aggiunto o rimosso |
1764| `moreFiles` | number | `2` | Numero di file modificati senza diff in `files` |1763| `moreFiles` | number | `2` | Numero di file modificati senza diff in `files` |
1765| `unavailable` | boolean | `true` | Impostato quando il diff è incompleto o non è stato possibile ottenerlo |1764| `unavailable` | boolean | `true` | Impostato quando il diff è incompleto o non è stato possibile ottenerlo |
1766| `skipped` | boolean | `true` | Impostato per un comando Git che sposta l'albero di lavoro, come `git checkout` o `git stash`, per cui Claude Code non calcola alcun diff |1765| `skipped` | boolean | `true` | Impostato per un comando Git che sposta l'albero di lavoro, come `git checkout` o `git stash`, per cui Claude Code non calcola alcun diff |
1767| `shared` | boolean | `true` | Impostato quando un'altra chiamata allo strumento Bash, ad esempio di un subagent, è stata eseguita nello stesso repository nello stesso momento, per cui alcune modifiche elencate potrebbero appartenere a quel comando |1766| `shared` | boolean | `true` | Impostato quando un'altra chiamata allo strumento Bash, ad esempio quella di un subagent, è stata eseguita nello stesso repository nello stesso momento, per cui alcune modifiche elencate potrebbero appartenere a quel comando |
1768 1767
1769<a id="powershell" />1768<a id="powershell" />
1770 1769
1783| `timeout` | number | `120000` | Timeout facoltativo in millisecondi |1782| `timeout` | number | `120000` | Timeout facoltativo in millisecondi |
1784| `run_in_background` | boolean | `false` | Se eseguire il comando in background |1783| `run_in_background` | boolean | `false` | Se eseguire il comando in background |
1785 1784
1786Usa `Bash|PowerShell` come corrispondenza negli hook che ispezionano i comandi shell, così coprono entrambi gli strumenti:1785Usa `Bash|PowerShell` negli hook che ispezionano i comandi shell, così coprono entrambi gli strumenti:
1787 1786
1788* Su Windows, ovunque lo strumento PowerShell sia abilitato, Claude tratta PowerShell come shell principale e vi instrada i comandi shell.1787* Su Windows, ovunque lo strumento PowerShell sia abilitato, Claude tratta PowerShell come shell principale e instrada i comandi shell attraverso di essa.
1789* Su Windows senza Git Bash, lo strumento è abilitato automaticamente e Claude Code non registra affatto lo strumento Bash.1788* Su Windows senza Git Bash, lo strumento viene abilitato automaticamente e Claude Code non registra affatto lo strumento Bash.
1790* Un hook che corrisponde solo a `Bash` non si attiva mai in quel caso.1789* Un hook che corrisponde solo a `Bash` non viene mai attivato in quel caso.
1791 1790
1792<h5 id="write">1791<h5 id="write">
1793 Write1792 Write
1845| Campo | Tipo | Esempio | Descrizione |1844| Campo | Tipo | Esempio | Descrizione |
1846| :- | :- | :- | :- |1845| :- | :- | :- | :- |
1847| `pattern` | string | `"TODO.*fix"` | Pattern di espressione regolare da cercare |1846| `pattern` | string | `"TODO.*fix"` | Pattern di espressione regolare da cercare |
1848| `path` | string | `"/path/to/dir"` | File o directory facoltativa in cui cercare |1847| `path` | string | `"/path/to/dir"` | File o directory facoltativi in cui cercare |
1849| `glob` | string | `"*.ts"` | Pattern glob facoltativo per filtrare i file |1848| `glob` | string | `"*.ts"` | Pattern glob facoltativo per filtrare i file |
1850| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"` o `"count"`. Il valore predefinito è `"files_with_matches"` |1849| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"` o `"count"`. Il valore predefinito è `"files_with_matches"` |
1851| `-i` | boolean | `true` | Ricerca senza distinzione tra maiuscole e minuscole |1850| `-i` | boolean | `true` | Ricerca senza distinzione tra maiuscole e minuscole |
1866 WebSearch1865 WebSearch
1867</h5>1866</h5>
1868 1867
1869Esegue ricerche sul web.1868Effettua ricerche sul web.
1870 1869
1871| Campo | Tipo | Esempio | Descrizione |1870| Campo | Tipo | Esempio | Descrizione |
1872| :- | :- | :- | :- |1871| :- | :- | :- | :- |
1885| `prompt` | string | `"Find all API endpoints"` | L'attività che l'agente deve svolgere |1884| `prompt` | string | `"Find all API endpoints"` | L'attività che l'agente deve svolgere |
1886| `description` | string | `"Find API endpoints"` | Breve descrizione dell'attività |1885| `description` | string | `"Find API endpoints"` | Breve descrizione dell'attività |
1887| `subagent_type` | string | `"Explore"` | Tipo di agente specializzato da usare |1886| `subagent_type` | string | `"Explore"` | Tipo di agente specializzato da usare |
1888| `model` | string | `"sonnet"` | Alias di modello facoltativo per sovrascrivere quello predefinito |1887| `model` | string | `"sonnet"` | Alias di modello facoltativo per sovrascrivere il valore predefinito |
1889 1888
1890Quando una chiamata Agent in primo piano viene completata, il tuo [hook PostToolUse](#posttooluse) riceve il risultato del subagent e la telemetria dell'esecuzione in `tool_response`. Leggi questi campi per ispezionare l'esecuzione; per i totali di token e costi tra i subagent, usa i [contatori di token e costi](/docs/it/monitoring-usage#token-counter) filtrati per `query_source` `"subagent"`, poiché `totalTokens` e `usage` coprono solo la richiesta finale:1889Quando una chiamata Agent in primo piano termina, il tuo [hook PostToolUse](#posttooluse) riceve il risultato del subagent e la telemetria dell'esecuzione in `tool_response`. Leggi questi campi per ispezionare l'esecuzione; per i totali di token e costi tra i subagent, usa i [contatori di token e costi](/docs/it/monitoring-usage#token-counter) filtrati su `query_source` `"subagent"`, poiché `totalTokens` e `usage` coprono solo la richiesta finale:
1891 1890
1892| Campo | Tipo | Esempio | Descrizione |1891| Campo | Tipo | Esempio | Descrizione |
1893| :- | :- | :- | :- |1892| :- | :- | :- | :- |
1894| `status` | string | `"completed"` | `"completed"` per i subagent in primo piano, `"async_launched"` per i subagent in background. I subagent vengono eseguiti in background per impostazione predefinita, quindi anche una chiamata Agent che omette `run_in_background` produce `"async_launched"` |1893| `status` | string | `"completed"` | `"completed"` per i subagent in primo piano, `"async_launched"` per i subagent in background. Per impostazione predefinita i subagent vengono eseguiti in background, quindi anche una chiamata Agent che omette `run_in_background` produce `"async_launched"` |
1895| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificatore dell'esecuzione del subagent |1894| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificatore dell'esecuzione del subagent |
1896| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | I blocchi di testo finali del subagent oppure, per un subagent il cui rapporto passa attraverso `SubagentHandback`, una breve nota su quella consegna al loro posto |1895| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | I blocchi di testo finali del subagent oppure, per un subagent il cui report passa attraverso `SubagentHandback`, una breve nota su quella consegna al loro posto |
1897| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modello con cui è partito il subagent, che può differire dal modello richiesto |1896| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modello con cui il subagent è partito, che può differire dal modello richiesto |
1898| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelli usati in ordine, con le ripetizioni consecutive unite; impostato solo quando il modello è stato cambiato durante l'esecuzione. Richiede Claude Code v2.1.212 o successiva |1897| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelli usati in ordine, con le ripetizioni consecutive compresse; impostato solo quando il modello è stato cambiato durante l'esecuzione. Richiede Claude Code v2.1.212 o successiva |
1899| `totalTokens` | number | `12450` | Conteggio dei token dalla richiesta API finale del subagent: token di input, output e cache combinati. Non è un totale sull'intera esecuzione |1898| `totalTokens` | number | `12450` | Numero di token dalla richiesta API finale del subagent: token di input, output e cache combinati. Non è un totale sull'intera esecuzione |
1900| `totalDurationMs` | number | `48211` | Durata reale dell'esecuzione del subagent |1899| `totalDurationMs` | number | `48211` | Durata in tempo reale dell'esecuzione del subagent |
1901| `totalToolUseCount` | number | `7` | Numero di chiamate agli strumenti effettuate dal subagent |1900| `totalToolUseCount` | number | `7` | Numero di chiamate a strumenti effettuate dal subagent |
1902| `usage` | object | `{"input_tokens": 8320, ...}` | Suddivisione per tipo dei token della richiesta API finale: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1901| `usage` | object | `{"input_tokens": 8320, ...}` | Suddivisione per tipo dei token della richiesta API finale: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |
1903 1902
1904Su Claude Code v2.1.271 o successiva, un subagent che viene eseguito con lo strumento [`SubagentHandback`](/docs/it/tools-reference), che Claude Code fornisce in [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), consegna il suo rapporto tramite quello strumento anziché restituirlo come testo. Il campo `content` del suo risultato `completed` contiene quindi una breve nota su quella consegna anziché il rapporto stesso. Per leggere il rapporto, fai corrispondere un hook `PreToolUse` o `PostToolUse` a `SubagentHandback` e leggi `tool_input.message`.1903Su Claude Code v2.1.271 o successiva, un subagent che viene eseguito con lo strumento [`SubagentHandback`](/docs/it/tools-reference), che Claude Code fornisce in [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), consegna il suo report tramite quello strumento anziché restituirlo come testo. Il campo `content` del suo risultato `completed` contiene allora una breve nota su quella consegna anziché il report stesso. Per leggere il report, fai corrispondere un hook `PreToolUse` o `PostToolUse` su `SubagentHandback` e leggi `tool_input.message`.
1905 1904
1906Per i subagent in background, lo strumento restituisce quando l'attività passa in background, quindi `tool_response` non contiene campi di utilizzo: un avvio in background restituisce immediatamente, e un'attività in primo piano che Claude Code sposta in background durante l'esecuzione restituisce in quel momento di transizione. Ha `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel`.1905Per i subagent in background, lo strumento restituisce un risultato quando l'attività passa in background, quindi `tool_response` non contiene campi di utilizzo: un avvio in background restituisce immediatamente, e un'attività in primo piano che Claude Code sposta in background durante l'esecuzione restituisce in corrispondenza di quella transizione. Contiene `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel`.
1907 1906
1908In una risposta `completed`, `resolvedModel` indica il modello con cui è partito il subagent, che può differire dal valore `model` in `tool_input`, ad esempio quando si applica `availableModels` o un altro override. In una risposta `async_launched`, `resolvedModel` indica il modello in uso quando l'agente è passato in background, quindi un cambio avvenuto prima del passaggio in background si riflette lì. `modelsUsed` e il comportamento di `resolvedModel` al momento del passaggio in background richiedono Claude Code v2.1.212 o successiva.1907In una risposta `completed`, `resolvedModel` indica il modello con cui il subagent è partito, che può differire dal valore `model` in `tool_input`, ad esempio quando si applica `availableModels` o un altro override. In una risposta `async_launched`, `resolvedModel` indica il modello in uso quando l'agente è passato in background, quindi un cambio avvenuto prima del passaggio in background viene riflesso lì. `modelsUsed` e il comportamento di `resolvedModel` al momento del passaggio in background richiedono Claude Code v2.1.212 o successiva.
1909 1908
1910<a id="askuserquestion" />1909<a id="askuserquestion" />
1911 1910
1917 1916
1918| Campo | Tipo | Esempio | Descrizione |1917| Campo | Tipo | Esempio | Descrizione |
1919| :- | :- | :- | :- |1918| :- | :- | :- | :- |
1920| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false}]` | Domande da presentare, ciascuna con una stringa `question`, un breve `header`, un array `options` e un flag facoltativo `multiSelect` |1919| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false}]` | Domande da presentare, ciascuna con una stringa `question`, un breve `header`, un array `options` e un flag `multiSelect` facoltativo |
1921| `answers` | object | `{"Which framework?": "React"}` | Facoltativo. Associa il testo della domanda all'etichetta dell'opzione selezionata. Le risposte a selezione multipla uniscono le etichette con virgole. Claude non imposta questo campo; forniscilo tramite `updatedInput` per rispondere in modo programmatico |1920| `answers` | object | `{"Which framework?": "React"}` | Facoltativo. Associa il testo della domanda all'etichetta dell'opzione selezionata. Le risposte a selezione multipla uniscono le etichette con virgole. Claude non imposta questo campo; forniscilo tramite `updatedInput` per rispondere in modo programmatico |
1922 1921
1923<h5 id="exitplanmode">1922<h5 id="exitplanmode">
1932| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Percorso del file del piano. Inserito |1931| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Percorso del file del piano. Inserito |
1933| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Deprecato. Claude Code accetta il campo ma lo ignora. Prima della v2.1.205, conteneva i permessi basati su prompt che Claude richiedeva per implementare il piano |1932| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Deprecato. Claude Code accetta il campo ma lo ignora. Prima della v2.1.205, conteneva i permessi basati su prompt che Claude richiedeva per implementare il piano |
1934 1933
1935In `PostToolUse`, `tool_response` è un oggetto con i campi `plan` e `filePath` che contengono il piano approvato, oltre a flag di stato interni. Leggi `tool_response.plan` per il contenuto del piano anziché rileggere il file dal disco.1934In `PostToolUse`, `tool_response` è un oggetto con i campi `plan` e `filePath` che contengono il piano approvato, più alcuni flag di stato interni. Leggi `tool_response.plan` per il contenuto del piano anziché rileggere il file dal disco.
1936 1935
1937<h4 id="pretooluse-decision-control">1936<h4 id="pretooluse-decision-control">
1938 Controllo delle decisioni di PreToolUse1937 Controllo delle decisioni di PreToolUse
1942 1941
1943| Campo | Descrizione |1942| Campo | Descrizione |
1944| :- | :- |1943| :- | :- |
1945| `permissionDecision` | `"allow"` salta la richiesta di permesso, tranne per le [azioni che nessuna modalità approva automaticamente](/docs/it/permission-modes#actions-no-mode-auto-approves) e per `AskUserQuestion` e `ExitPlanMode`, che richiedono [`updatedInput` abbinato](#allow-with-updatedinput). `"deny"` impedisce la chiamata allo strumento. `"ask"` chiede all'utente di confermare. `"defer"` esce in modo controllato così lo strumento può essere ripreso in seguito. Le [regole deny e ask](/docs/it/permissions#manage-permissions) vengono comunque valutate indipendentemente da ciò che restituisce l'hook |1944| `permissionDecision` | `"allow"` salta la richiesta di permesso, tranne per le [azioni che nessuna modalità approva automaticamente](/docs/it/permission-modes#actions-no-mode-auto-approves) e per `AskUserQuestion` e `ExitPlanMode`, che necessitano di [`updatedInput` abbinato](#allow-with-updatedinput). `"deny"` impedisce la chiamata allo strumento. `"ask"` chiede all'utente di confermare. `"defer"` esce in modo ordinato così che lo strumento possa essere ripreso in seguito. Le [regole di negazione e di richiesta](/docs/it/permissions#manage-permissions) vengono comunque valutate indipendentemente da ciò che restituisce l'hook |
1946| `permissionDecisionReason` | Per `"ask"`, mostrato all'utente nella richiesta di permesso. Quando Claude Code [nega la chiamata](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs) in un'esecuzione `-p` in cui nessuno può rispondere a quella richiesta, Claude legge invece il motivo nel risultato dello strumento. Per `"deny"`, mostrato a Claude. Per `"allow"` e `"defer"`, scritto solo nel [log di debug](#debug-hooks) |1945| `permissionDecisionReason` | Per `"ask"`, mostrato all'utente nella richiesta di permesso. Quando Claude Code [nega la chiamata](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs) in un'esecuzione `-p` in cui nessuno può rispondere a quella richiesta, Claude legge invece il motivo nel risultato dello strumento. Per `"deny"`, mostrato a Claude. Per `"allow"` e `"defer"`, scritto solo nel [log di debug](#debug-hooks) |
1947| `updatedInput` | Modifica i parametri di input dello strumento prima dell'esecuzione. Sostituisce l'intero oggetto di input, quindi includi i campi invariati insieme a quelli modificati. Claude Code valuta le regole di permesso e l'[idoneità al passaggio automatico in background](/docs/it/tools-reference#foreground-commands-that-move-to-the-background) di un comando Bash sull'input restituito dal tuo hook, non sull'input inviato da Claude. Combinalo con `"allow"` per approvare automaticamente, o con `"ask"` per mostrare all'utente l'input modificato. Per `"defer"`, viene ignorato |1946| `updatedInput` | Modifica i parametri di input dello strumento prima dell'esecuzione. Sostituisce l'intero oggetto di input, quindi includi i campi invariati insieme a quelli modificati. Claude Code valuta le regole di permesso e l'[idoneità al passaggio automatico in background](/docs/it/tools-reference#foreground-commands-that-move-to-the-background) di un comando Bash rispetto all'input restituito dal tuo hook, non all'input inviato da Claude. Combinalo con `"allow"` per approvare automaticamente, oppure con `"ask"` per mostrare l'input modificato all'utente. Per `"defer"`, viene ignorato |
1948| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Ignorata quando `permissionDecision` è `"defer"`. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |1947| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Ignorata quando `permissionDecision` è `"defer"`. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |
1949 1948
1950Quando più hook PreToolUse restituiscono decisioni diverse, l'ordine di precedenza è `deny` > `defer` > `ask` > `allow`.1949Quando più hook PreToolUse restituiscono decisioni diverse, la precedenza è `deny` > `defer` > `ask` > `allow`.
1951 1950
1952Un hook che blocca terminando con 2 segue lo stesso percorso di `"deny"`: Claude vede il messaggio di stderr come motivo del rifiuto.1951Un hook che blocca uscendo con 2 segue lo stesso percorso di `"deny"`: Claude vede il messaggio di stderr come motivo della negazione.
1953 1952
1954Quando un hook restituisce `"ask"`, la richiesta di permesso mostrata all'utente include un'etichetta che identifica la provenienza dell'hook: `[settings]` per un hook da qualsiasi file di impostazioni o dal frontmatter di un agente, `[plugin:<name>]` per l'hook di un plugin, o `[skill]` per un hook dal frontmatter di una skill. Questo aiuta gli utenti a capire quale fonte di configurazione sta richiedendo la conferma.1953Quando un hook restituisce `"ask"`, la richiesta di permesso mostrata all'utente include un'etichetta che identifica la provenienza dell'hook: `[settings]` per un hook da qualsiasi file di impostazioni o dal frontmatter di un agente, `[plugin:<name>]` per l'hook di un plugin, oppure `[skill]` per un hook dal frontmatter di una skill. Questo aiuta gli utenti a capire quale fonte di configurazione sta richiedendo la conferma.
1955 1954
1956Un `"ask"` di un hook forza una richiesta di permesso anche in [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode): il classificatore può comunque negare la chiamata allo strumento, ma non può approvarla silenziosamente. Prima della v2.1.211, il classificatore poteva approvare un comando Bash eseguito fuori dalla [sandbox](/docs/it/sandboxing) senza mostrare la richiesta voluta dall'hook; il classificatore applicava comunque le proprie regole di sicurezza a quel comando, e un `"deny"` di un hook veniva sempre rispettato.1955Un `"ask"` di un hook forza una richiesta di permesso anche in [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode): il classificatore può comunque negare la chiamata allo strumento, ma non può approvarla silenziosamente. Prima della v2.1.211, il classificatore poteva approvare un comando Bash eseguito fuori dalla [sandbox](/docs/it/sandboxing) senza mostrare la richiesta voluta dall'hook; il classificatore applicava comunque le proprie regole di sicurezza a quel comando, e un `"deny"` di un hook veniva sempre rispettato.
1957 1956
1970```1969```
1971 1970
1972<Note>1971<Note>
1973 In precedenza PreToolUse usava i campi di primo livello `decision` e `reason`, ma questi sono deprecati per questo evento. Usa invece `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason`. I valori deprecati `"approve"` e `"block"` corrispondono rispettivamente a `"allow"` e `"deny"`. Altri eventi come PostToolUse e Stop continuano a usare `decision` e `reason` di primo livello come formato attuale.1972 In precedenza PreToolUse usava i campi di primo livello `decision` e `reason`, ma questi sono deprecati per questo evento. Usa invece `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason`. I valori deprecati `"approve"` e `"block"` corrispondono rispettivamente a `"allow"` e `"deny"`. Altri eventi come PostToolUse e Stop continuano a usare `decision` e `reason` di primo livello come formato corrente.
1974</Note>1973</Note>
1975 1974
1976<h4 id="allow-with-updatedinput">1975<h4 id="allow-with-updatedinput">
1977 Strumenti che richiedono l'interazione dell'utente1976 Strumenti che richiedono l'interazione dell'utente
1978</h4>1977</h4>
1979 1978
1980`AskUserQuestion` e `ExitPlanMode` richiedono l'interazione dell'utente. In [modalità non interattiva](/docs/it/headless) con il flag `-p`, Claude Code li offre solo quando l'esecuzione ha un [host dei permessi](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs) che riceve la richiesta, come un callback `canUseTool` dell'Agent SDK.1979`AskUserQuestion` e `ExitPlanMode` richiedono l'interazione dell'utente. In [modalità non interattiva](/docs/it/headless) con il flag `-p`, Claude Code li offre solo quando l'esecuzione dispone di un [host dei permessi](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs) che riceva la richiesta, come un callback `canUseTool` dell'Agent SDK.
1981 1980
1982Un hook `PreToolUse` soddisfa questo requisito quando fa quanto segue:1981Un hook `PreToolUse` soddisfa quel requisito quando fa quanto segue:
1983 1982
19841. Legge l'input dello strumento da stdin19831. Legge l'input dello strumento da stdin
19852. Raccoglie la risposta tramite la tua interfaccia utente19842. Raccoglie la risposta tramite la tua interfaccia utente
19863. Restituisce `permissionDecision: "allow"` insieme a `updatedInput` contenente la risposta, così lo strumento viene eseguito senza chiedere conferma19853. Restituisce `permissionDecision: "allow"` insieme a un `updatedInput` che contiene la risposta, così lo strumento viene eseguito senza chiedere
1987 1986
1988Restituire solo `"allow"` non è sufficiente per questi strumenti.1987Restituire solo `"allow"` non è sufficiente per questi strumenti.
1989 1988
2009}2008}
2010```2009```
2011 2010
2012Uno strumento MCP che il suo server contrassegna con [`_meta["anthropic/requiresUserInteraction"]`](/docs/it/mcp#require-approval-for-a-specific-tool) è più restrittivo: un hook non può saltarne la richiesta di approvazione con `"allow"`, con o senza `updatedInput`, perché Claude Code non può verificare che l'hook abbia raccolto l'interazione di cui lo strumento ha bisogno.2011Uno strumento MCP che il suo server contrassegna con [`_meta["anthropic/requiresUserInteraction"]`](/docs/it/mcp#require-approval-for-a-specific-tool) è più restrittivo: un hook non può saltare la sua richiesta di approvazione con `"allow"`, con o senza `updatedInput`, perché Claude Code non può confermare che l'hook abbia raccolto l'interazione di cui lo strumento ha bisogno.
2013 2012
2014<h4 id="defer-a-tool-call-for-later">2013<h4 id="defer-a-tool-call-for-later">
2015 Differire una chiamata a uno strumento2014 Differire una chiamata a uno strumento
2016</h4>2015</h4>
2017 2016
2018`"defer"` è pensato per le integrazioni che eseguono `claude -p` come sottoprocesso e ne leggono l'output JSON, come un'app Agent SDK o un'interfaccia personalizzata costruita su Claude Code. Permette a quel processo chiamante di mettere in pausa Claude a una chiamata a uno strumento, raccogliere input tramite la propria interfaccia e riprendere da dove si era interrotto. Claude Code rispetta questo valore solo in [modalità non interattiva](/docs/it/headless) con il flag `-p`. Nelle sessioni interattive registra un avviso e ignora il risultato dell'hook.2017`"defer"` è pensato per le integrazioni che eseguono `claude -p` come sottoprocesso e leggono il suo output JSON, come un'app dell'Agent SDK o un'interfaccia utente personalizzata costruita su Claude Code. Consente a quel processo chiamante di mettere in pausa Claude a una chiamata a uno strumento, raccogliere input tramite la propria interfaccia e riprendere da dove si era interrotto. Claude Code rispetta questo valore solo in [modalità non interattiva](/docs/it/headless) con il flag `-p`. Nelle sessioni interattive registra un avviso e ignora il risultato dell'hook.
2019 2018
2020Lo strumento `AskUserQuestion` è il caso tipico: Claude vuole chiedere qualcosa all'utente, ma non c'è un terminale in cui rispondere. Un'esecuzione `-p` offre `AskUserQuestion` solo quando ha un [host dei permessi](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs), come uno strumento MCP che passi con `--permission-prompt-tool`, quindi avvia l'esecuzione con uno di essi. Il ciclo completo funziona così:2019Lo strumento `AskUserQuestion` è il caso tipico: Claude vuole chiedere qualcosa all'utente, ma non c'è alcun terminale in cui rispondere. Un'esecuzione `-p` offre `AskUserQuestion` solo quando dispone di un [host dei permessi](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs), come uno strumento MCP che passi con `--permission-prompt-tool`, quindi avvia l'esecuzione con uno di essi. Il ciclo completo funziona così:
2021 2020
20221. Claude chiama `AskUserQuestion`. L'hook `PreToolUse` si attiva.20211. Claude chiama `AskUserQuestion`. L'hook `PreToolUse` viene attivato.
20232. L'hook restituisce `permissionDecision: "defer"`. Lo strumento non viene eseguito. Il processo esce con `stop_reason: "tool_deferred"` e la chiamata allo strumento in sospeso conservata nella trascrizione.20222. L'hook restituisce `permissionDecision: "defer"`. Lo strumento non viene eseguito. Il processo esce con `stop_reason: "tool_deferred"` e la chiamata allo strumento in sospeso viene conservata nella trascrizione.
20243. Il processo chiamante legge `deferred_tool_use` dal risultato dell'SDK, presenta la domanda nella propria interfaccia e attende una risposta.20233. Il processo chiamante legge `deferred_tool_use` dal risultato dell'SDK, presenta la domanda nella propria interfaccia utente e attende una risposta.
20254. Il processo chiamante esegue `claude -p --resume <session-id>` con lo stesso host dei permessi. La stessa chiamata allo strumento attiva di nuovo `PreToolUse`.20244. Il processo chiamante esegue `claude -p --resume <session-id>` con lo stesso host dei permessi. La stessa chiamata allo strumento attiva di nuovo `PreToolUse`.
20265. L'hook restituisce `permissionDecision: "allow"` con la risposta in `updatedInput`. Lo strumento viene eseguito e Claude continua.20255. L'hook restituisce `permissionDecision: "allow"` con la risposta in `updatedInput`. Lo strumento viene eseguito e Claude continua.
2027 2026
2028Il campo `deferred_tool_use` contiene `id`, `name` e `input` dello strumento. L'`input` è costituito dai parametri che Claude ha generato per la chiamata allo strumento, catturati prima dell'esecuzione:2027Il campo `deferred_tool_use` contiene `id`, `name` e `input` dello strumento. L'`input` è costituito dai parametri generati da Claude per la chiamata allo strumento, acquisiti prima dell'esecuzione:
2029 2028
2030```json theme={null}2029```json theme={null}
2031{2030{
2041}2040}
2042```2041```
2043 2042
2044Non c'è alcun timeout né limite di nuovi tentativi. La sessione rimane su disco finché non la riprendi, fatta salva la pulizia di conservazione [`cleanupPeriodDays`](/docs/it/settings-reference#cleanupperioddays), che elimina i file di sessione dopo 30 giorni per impostazione predefinita, secondo le [regole di pulizia di conservazione](/docs/it/claude-directory#cleaned-up-automatically). Se la risposta non è pronta quando riprendi, l'hook può restituire di nuovo `"defer"` e il processo esce allo stesso modo. Il processo chiamante controlla quando interrompere il ciclo restituendo infine `"allow"` o `"deny"` dall'hook.2043Non esiste alcun timeout né limite di nuovi tentativi. La sessione rimane su disco finché non la riprendi, salvo la pulizia di conservazione di [`cleanupPeriodDays`](/docs/it/settings-reference#cleanupperioddays), che elimina i file di sessione dopo 30 giorni per impostazione predefinita, secondo le [regole della pulizia di conservazione](/docs/it/claude-directory#cleaned-up-automatically). Se la risposta non è pronta quando riprendi, l'hook può restituire di nuovo `"defer"` e il processo esce allo stesso modo. Il processo chiamante decide quando interrompere il ciclo restituendo infine `"allow"` o `"deny"` dall'hook.
2045 2044
2046`"defer"` funziona solo quando Claude effettua una singola chiamata a uno strumento nel turno. Se Claude effettua più chiamate agli strumenti contemporaneamente, `"defer"` viene ignorato con un avviso e lo strumento procede attraverso il normale flusso dei permessi. Il vincolo esiste perché la ripresa può rieseguire un solo strumento: non c'è modo di differire una chiamata di un gruppo senza lasciare irrisolte le altre.2045`"defer"` funziona solo quando Claude effettua una singola chiamata a uno strumento nel turno. Se Claude effettua più chiamate a strumenti contemporaneamente, `"defer"` viene ignorato con un avviso e lo strumento procede attraverso il normale flusso dei permessi. Il vincolo esiste perché la ripresa può rieseguire un solo strumento: non c'è modo di differire una chiamata di un gruppo senza lasciare irrisolte le altre.
2047 2046
2048Se lo strumento differito non è più disponibile quando riprendi, il processo esce con `stop_reason: "tool_deferred_unavailable"` e `is_error: true` prima che l'hook si attivi. Questo accade quando un server MCP che forniva lo strumento non è connesso per la sessione ripresa. Il payload `deferred_tool_use` viene comunque incluso così puoi identificare quale strumento è venuto a mancare.2047Se lo strumento differito non è più disponibile quando riprendi, il processo esce con `stop_reason: "tool_deferred_unavailable"` e `is_error: true` prima che l'hook venga attivato. Questo accade quando un server MCP che forniva lo strumento non è connesso per la sessione ripresa. Il payload `deferred_tool_use` è comunque incluso, così puoi identificare quale strumento è venuto a mancare.
2049 2048
2050<Note>2049<Note>
2051 Per riprendere una sessione differita in plan mode, passa [`--permission-prompt-tool`](/docs/it/cli-reference#cli-flags) insieme a `--resume` così che Claude Code possa presentare il piano per l'approvazione. Se passi determinati altri flag di avvio, l'esecuzione ripresa non torna al plan mode; consulta [Riprendere in plan mode con `-p`](/docs/it/sessions#resume-in-plan-mode-with-p). Richiede Claude Code v2.1.246 o successiva.2050 Per riprendere una sessione differita in plan mode, passa [`--permission-prompt-tool`](/docs/it/cli-reference#cli-flags) insieme a `--resume` in modo che Claude Code possa presentare il piano per l'approvazione. Se passi alcuni altri flag di avvio, l'esecuzione ripresa non torna al plan mode; consulta [Riprendere in plan mode con `-p`](/docs/it/sessions#resume-in-plan-mode-with-p). Richiede Claude Code v2.1.246 o successiva.
2052 2051
2053 Quando riprendi con `-p`, Claude Code non ripristina nessun'altra modalità di permesso memorizzata. Avvia l'esecuzione nella modalità di permesso in cui si avvierebbe una nuova esecuzione `claude -p`, quindi passa di nuovo `--permission-mode` o `--dangerously-skip-permissions` se la sessione differita ne usava uno. Quando riprendi con `claude --resume <session-id>` senza `-p`, Claude Code ripristina la modalità di permesso memorizzata, con le eccezioni elencate in [modalità di permesso alla ripresa](/docs/it/sessions#permission-mode-on-resume).2052 Quando riprendi con `-p`, Claude Code non ripristina nessun'altra modalità di permesso memorizzata. Avvia l'esecuzione nella modalità di permesso in cui partirebbe una nuova esecuzione `claude -p`, quindi passa di nuovo `--permission-mode` o `--dangerously-skip-permissions` se la sessione differita ne usava uno. Quando riprendi con `claude --resume <session-id>` senza `-p`, Claude Code ripristina la modalità di permesso memorizzata, con le eccezioni elencate in [modalità di permesso alla ripresa](/docs/it/sessions#permission-mode-on-resume).
2054</Note>2053</Note>
2055 2054
2056<h3 id="permissionrequest">2055<h3 id="permissionrequest">
2057 PermissionRequest2056 PermissionRequest
2058</h3>2057</h3>
2059 2058
2060Viene eseguito quando Claude Code sta per chiederti il permesso di usare uno strumento. Nelle sessioni che non possono mostrare una richiesta, come i subagent in background in [modalità non interattiva](/docs/it/headless), Claude Code esegue comunque questi hook, e se nessun hook restituisce una decisione, nega la chiamata allo strumento. Per una chiamata che raggiunge un `--permission-prompt-tool` o il [callback `canUseTool`](/docs/it/agent-sdk/permissions) dell'Agent SDK, gli hook vengono eseguiti insieme al tuo host, e si applica chi decide per primo.2059Viene eseguito quando Claude Code sta per chiederti il permesso di usare uno strumento. Nelle sessioni che non possono mostrare una richiesta, come i subagent in background in [modalità non interattiva](/docs/it/headless), Claude Code esegue comunque questi hook e, se nessun hook restituisce una decisione, nega la chiamata allo strumento. Per una chiamata che raggiunge un `--permission-prompt-tool` o il [callback `canUseTool`](/docs/it/agent-sdk/permissions) dell'Agent SDK, gli hook vengono eseguiti insieme al tuo host, e si applica la decisione di chi decide per primo.
2061Usa il [controllo delle decisioni di PermissionRequest](#permissionrequest-decision-control) per consentire o negare per conto dell'utente.2060Usa il [controllo delle decisioni di PermissionRequest](#permissionrequest-decision-control) per consentire o negare per conto dell'utente.
2062 2061
2063Usa questo evento quando ti serve un segnale nel momento in cui Claude chiede il permesso di usare uno strumento. Claude Code esegue un hook [Notification](#notification) con il tipo `permission_prompt` solo dopo che la richiesta è rimasta in attesa per circa sei secondi.2062Usa questo evento quando hai bisogno di un segnale nel momento in cui Claude chiede il permesso di usare uno strumento. Claude Code esegue un hook [Notification](#notification) con il tipo `permission_prompt` solo dopo che la richiesta è rimasta in attesa per circa sei secondi.
2064 2063
2065Claude Code non esegue gli hook PermissionRequest per la [richiesta di rete](/docs/it/sandboxing#network-isolation) di un comando in sandbox. Per ottenere un segnale per quella richiesta, usa il tipo di notifica `permission_prompt`.2064Claude Code non esegue gli hook PermissionRequest per la [richiesta di rete](/docs/it/sandboxing#network-isolation) di un comando in sandbox. Per ottenere un segnale per quella richiesta, usa il tipo di notifica `permission_prompt`.
2066 2065
2067Effettua la corrispondenza sul nome dello strumento, con gli stessi valori di PreToolUse.2066Corrisponde sul nome dello strumento, con gli stessi valori di PreToolUse.
2068 2067
2069<h4 id="permissionrequest-input">2068<h4 id="permissionrequest-input">
2070 Input di PermissionRequest2069 Input di PermissionRequest
2071</h4>2070</h4>
2072 2071
2073Gli hook PermissionRequest ricevono i campi `tool_name` e `tool_input` come gli hook PreToolUse, ma senza `tool_use_id`. Per uno strumento MCP, ricevono anche l'oggetto [`mcp_server`](#pretooluse-input). Un array facoltativo `permission_suggestions` contiene gli [aggiornamenti dei permessi](#permission-update-entries) che Claude Code suggerisce per questa richiesta, come l'aggiunta di una regola allow o il cambio della modalità di permesso.2072Gli hook PermissionRequest ricevono i campi `tool_name` e `tool_input` come gli hook PreToolUse, ma senza `tool_use_id`. Per uno strumento MCP, ricevono anche l'oggetto [`mcp_server`](#pretooluse-input). Un array facoltativo `permission_suggestions` contiene gli [aggiornamenti dei permessi](#permission-update-entries) che Claude Code suggerisce per questa richiesta, come l'aggiunta di una regola di consenso o la modifica della modalità di permesso.
2074 2073
2075L'array `permission_suggestions` non è un elenco esatto delle opzioni che vedi, perché ogni finestra di dialogo dei permessi costruisce le proprie opzioni. Alcune finestre, come quella per le modifiche ai file, non leggono affatto l'array e ricavano le opzioni dalla richiesta stessa. Una finestra che lo legge può comunque nascondere un'opzione il cui suggerimento rimane nell'array, ad esempio quando [`allowManagedPermissionRulesOnly`](/docs/it/settings-reference#allowmanagedpermissionrulesonly) nasconde le opzioni di salvataggio delle regole. Può anche offrire opzioni che non hanno una voce di suggerimento, come [**Yes, and switch to auto mode**](/docs/it/permission-modes#switch-permission-modes), che cambia la modalità di permesso direttamente anziché tramite un aggiornamento dei permessi.2074L'array `permission_suggestions` non è un elenco esatto delle opzioni che vedi, perché ogni finestra di dialogo dei permessi costruisce le proprie opzioni. Alcune finestre di dialogo, come quella per le modifiche ai file, non leggono affatto l'array e ricavano le loro opzioni dalla richiesta stessa. Una finestra di dialogo che lo legge può comunque nascondere un'opzione il cui suggerimento resta nell'array, ad esempio quando [`allowManagedPermissionRulesOnly`](/docs/it/settings-reference#allowmanagedpermissionrulesonly) nasconde le opzioni di salvataggio delle regole. Può anche offrire opzioni che non hanno alcuna voce di suggerimento, come [**Yes, and switch to auto mode**](/docs/it/permission-modes#switch-permission-modes), che cambia direttamente la modalità di permesso anziché tramite un aggiornamento dei permessi.
2076 2075
2077Gli hook PreToolUse vengono eseguiti prima di ogni chiamata a uno strumento, che richieda o meno un permesso. Gli hook PermissionRequest vengono eseguiti solo quando Claude Code sta per chiederti un permesso, o quando altrimenti negherebbe automaticamente una chiamata che non può mostrare una richiesta. Nessuno dei due eventi si attiva per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).2076Gli hook PreToolUse vengono eseguiti prima di ogni chiamata a uno strumento, che richieda o meno un permesso. Gli hook PermissionRequest vengono eseguiti solo quando Claude Code sta per chiederti il permesso, oppure quando altrimenti negherebbe automaticamente una chiamata che non può mostrare una richiesta. Nessuno dei due eventi viene attivato per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).
2078 2077
2079```json theme={null}2078```json theme={null}
2080{2079{
2107 2106
2108| Campo | Descrizione |2107| Campo | Descrizione |
2109| :- | :- |2108| :- | :- |
2110| `behavior` | `"allow"` concede il permesso, `"deny"` lo nega. Le [regole deny e ask](/docs/it/permissions#manage-permissions) vengono comunque valutate, quindi un hook che restituisce `"allow"` non sovrascrive una regola deny corrispondente |2109| `behavior` | `"allow"` concede il permesso, `"deny"` lo nega. Le [regole di negazione e di richiesta](/docs/it/permissions#manage-permissions) vengono comunque valutate, quindi un hook che restituisce `"allow"` non sovrascrive una regola di negazione corrispondente |
2111| `updatedInput` | Solo per `"allow"`: modifica i parametri di input dello strumento prima dell'esecuzione. Sostituisce l'intero oggetto di input, quindi includi i campi invariati insieme a quelli modificati. L'input modificato viene rivalutato rispetto alle regole deny e ask |2110| `updatedInput` | Solo per `"allow"`: modifica i parametri di input dello strumento prima dell'esecuzione. Sostituisce l'intero oggetto di input, quindi includi i campi invariati insieme a quelli modificati. L'input modificato viene rivalutato rispetto alle regole di negazione e di richiesta |
2112| `updatedPermissions` | Solo per `"allow"`: array di [voci di aggiornamento dei permessi](#permission-update-entries) da applicare, come l'aggiunta di una regola allow o il cambio della modalità di permesso della sessione |2111| `updatedPermissions` | Solo per `"allow"`: array di [voci di aggiornamento dei permessi](#permission-update-entries) da applicare, come l'aggiunta di una regola di consenso o la modifica della modalità di permesso della sessione |
2113| `message` | Solo per `"deny"`: indica a Claude perché il permesso è stato negato |2112| `message` | Solo per `"deny"`: comunica a Claude perché il permesso è stato negato |
2114| `interrupt` | Solo per `"deny"`: se `true`, ferma Claude |2113| `interrupt` | Solo per `"deny"`: se `true`, ferma Claude |
2115 2114
2116Un hook che termina 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.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.
2117 2116
2118```json theme={null}2117```json theme={null}
2119{2118{
2133 Voci di aggiornamento dei permessi2132 Voci di aggiornamento dei permessi
2134</h4>2133</h4>
2135 2134
2136Il campo di output `updatedPermissions` e il [campo di input `permission_suggestions`](#permissionrequest-input) usano entrambi lo stesso array di oggetti voce. Ogni voce ha un `type` che determina gli altri campi e una `destination` che controlla dove viene scritta la modifica.2135Il campo di output `updatedPermissions` e il [campo di input `permission_suggestions`](#permissionrequest-input) usano entrambi lo stesso array di oggetti voce. Ogni voce ha un `type` che determina i suoi altri campi e una `destination` che controlla dove viene scritta la modifica.
2137 2136
2138| `type` | Campi | Effetto |2137| `type` | Campi | Effetto |
2139| :- | :- | :- |2138| :- | :- | :- |
2140| `addRules` | `rules`, `behavior`, `destination` | Aggiunge regole di permesso. `rules` è un array di oggetti `{toolName, ruleContent?}`. Ometti `ruleContent` per far corrispondere l'intero strumento. `behavior` è `"allow"`, `"deny"` o `"ask"` |2139| `addRules` | `rules`, `behavior`, `destination` | Aggiunge regole di permesso. `rules` è un array di oggetti `{toolName, ruleContent?}`. Ometti `ruleContent` per corrispondere all'intero strumento. `behavior` è `"allow"`, `"deny"` o `"ask"` |
2141| `replaceRules` | `rules`, `behavior`, `destination` | Sostituisce tutte le regole del `behavior` indicato nella `destination` con le `rules` fornite |2140| `replaceRules` | `rules`, `behavior`, `destination` | Sostituisce tutte le regole del `behavior` indicato nella `destination` con le `rules` fornite |
2142| `removeRules` | `rules`, `behavior`, `destination` | Rimuove le regole corrispondenti del `behavior` indicato |2141| `removeRules` | `rules`, `behavior`, `destination` | Rimuove le regole corrispondenti del `behavior` indicato |
2143| `setMode` | `mode`, `destination` | Cambia la modalità di permesso. Le modalità valide sono `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` e `manual` come alias di `default` |2142| `setMode` | `mode`, `destination` | Cambia la modalità di permesso. Le modalità valide sono `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` e `manual` come alias di `default` |
2145| `removeDirectories` | `directories`, `destination` | Rimuove directory di lavoro |2144| `removeDirectories` | `directories`, `destination` | Rimuove directory di lavoro |
2146 2145
2147<Note>2146<Note>
2148 `setMode` con `bypassPermissions` ha effetto solo se hai avviato la sessione con la modalità bypass già disponibile: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` o `permissions.defaultMode: "bypassPermissions"` nelle [impostazioni utente, `--settings` o impostazioni gestite](/docs/it/settings-reference#permissions-defaultmode). Altrimenti l'aggiornamento non ha alcun effetto. L'aggiornamento non ha effetto anche quando [`permissions.disableBypassPermissionsMode`](/docs/it/permissions#managed-settings) disabilita la modalità, o quando la sessione si avvia in [modalità ristretta](/docs/it/cli-reference#cli-flags).2147 `setMode` con `bypassPermissions` ha effetto solo se hai avviato la sessione con la modalità bypass già disponibile: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` oppure `permissions.defaultMode: "bypassPermissions"` nelle [impostazioni utente, in `--settings` o nelle impostazioni gestite](/docs/it/settings-reference#permissions-defaultmode). Altrimenti l'aggiornamento non ha alcun effetto. L'aggiornamento non ha effetto neanche quando [`permissions.disableBypassPermissionsMode`](/docs/it/permissions#managed-settings) disabilita la modalità, o quando la sessione si avvia in [modalità limitata](/docs/it/cli-reference#cli-flags).
2149 2148
2150 `bypassPermissions` non viene mai reso persistente come `defaultMode`, indipendentemente da `destination`.2149 `bypassPermissions` non viene mai salvato in modo persistente come `defaultMode`, indipendentemente dalla `destination`.
2151</Note>2150</Note>
2152 2151
2153Il campo `destination` di ogni voce determina se la modifica rimane in memoria o viene resa persistente in un file di impostazioni.2152Il campo `destination` di ogni voce determina se la modifica resta in memoria o viene salvata in modo persistente in un file di impostazioni.
2154 2153
2155| `destination` | Scrive in |2154| `destination` | Scrive in |
2156| :- | :- |2155| :- | :- |
2157| `session` | solo in memoria, scartata al termine della sessione |2156| `session` | solo in memoria, scartata quando la sessione termina |
2158| `localSettings` | `.claude/settings.local.json` |2157| `localSettings` | `.claude/settings.local.json` |
2159| `projectSettings` | `.claude/settings.json` |2158| `projectSettings` | `.claude/settings.json` |
2160| `userSettings` | `~/.claude/settings.json` |2159| `userSettings` | `~/.claude/settings.json` |
2165 PostToolUse2164 PostToolUse
2166</h3>2165</h3>
2167 2166
2168Viene eseguito subito dopo che uno strumento è stato completato con successo.2167Viene eseguito immediatamente dopo che uno strumento è stato completato con successo.
2169 2168
2170Fa corrispondere il nome dello strumento, con gli stessi valori di PreToolUse.2169Corrisponde sul nome dello strumento, con gli stessi valori di PreToolUse.
2171 2170
2172Usa una corrispondenza più ampia quando il nome dello strumento non è il filtro giusto:2171Usa una corrispondenza più ampia quando il nome dello strumento non è il filtro giusto:
2173 2172
2174* Per eseguire un hook dopo che qualsiasi strumento è stato completato con successo, ometti il `matcher` o impostalo su `"*"`. Il tuo hook può quindi scoprire da solo cosa è cambiato, ad esempio eseguendo `git status --porcelain`, che elenca anche i file non tracciati che `git diff` non rileva. Per le chiamate agli strumenti che falliscono, aggiungi lo stesso hook sotto [PostToolUseFailure](#posttoolusefailure).2173* Per eseguire un hook dopo che qualsiasi strumento è stato completato con successo, ometti il `matcher` o impostalo su `"*"`. Il tuo hook può quindi scoprire da solo cosa è cambiato, ad esempio eseguendo `git status --porcelain`, che elenca anche i file non tracciati che `git diff` non rileva. Per le chiamate agli strumenti che falliscono, aggiungi lo stesso hook sotto [PostToolUseFailure](#posttoolusefailure).
2175* Per eseguire un hook quando un file specifico cambia su disco, qualunque cosa lo abbia scritto, usa [FileChanged](#filechanged). Claude Code non esegue un hook `PostToolUse` che corrisponde a `Edit|Write` quando un comando `Bash` o un processo esterno a Claude Code riscrive lo stesso file.2174* Per eseguire un hook quando un file specifico cambia su disco, indipendentemente da chi lo abbia scritto, usa [FileChanged](#filechanged). Claude Code non esegue un hook `PostToolUse` con corrispondenza `Edit|Write` quando un comando `Bash` o un processo esterno a Claude Code riscrive lo stesso file.
2176 2175
2177<h4 id="posttooluse-input">2176<h4 id="posttooluse-input">
2178 Input di PostToolUse2177 Input di PostToolUse
2179</h4>2178</h4>
2180 2179
2181Gli hook `PostToolUse` si attivano dopo che uno strumento è già stato eseguito con successo. L'input include sia `tool_input`, gli argomenti inviati allo strumento, sia `tool_response`, il risultato che ha restituito. Lo schema esatto di entrambi dipende dallo strumento. I percorsi in `tool_input` degli strumenti per i file arrivano nello stesso formato di [PreToolUse](#pretooluse-input): sempre assoluti, con i separatori nativi della piattaforma, quindi barre rovesciate su Windows. Per uno strumento MCP, l'input include anche l'oggetto [`mcp_server`](#pretooluse-input).2180Gli hook `PostToolUse` si attivano dopo che uno strumento è già stato eseguito con successo. L'input include sia `tool_input`, gli argomenti inviati allo strumento, sia `tool_response`, il risultato che ha restituito. Lo schema esatto di entrambi dipende dallo strumento. I percorsi in `tool_input` degli strumenti per i file arrivano nello stesso formato di [PreToolUse](#pretooluse-input): sempre assoluti, con i separatori nativi della piattaforma, quindi barre rovesciate su Windows. Per uno strumento MCP, l'input contiene anche l'oggetto [`mcp_server`](#pretooluse-input).
2182 2181
2183```json theme={null}2182```json theme={null}
2184{2183{
2209 Controllo delle decisioni di PostToolUse2208 Controllo delle decisioni di PostToolUse
2210</h4>2209</h4>
2211 2210
2212Gli hook `PostToolUse` possono fornire feedback a Claude dopo l'esecuzione dello strumento. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, lo script del tuo hook può restituire questi campi specifici dell'evento:2211Gli hook `PostToolUse` possono fornire feedback a Claude dopo l'esecuzione dello strumento. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, il tuo script di hook può restituire questi campi specifici dell'evento:
2213 2212
2214| Campo | Descrizione |2213| Campo | Descrizione |
2215| :- | :- |2214| :- | :- |
2217| `reason` | Spiegazione mostrata a Claude quando `decision` è `"block"` |2216| `reason` | Spiegazione mostrata a Claude quando `decision` è `"block"` |
2218| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |2217| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |
2219| `classifierContext` | Breve nota sul risultato di questa chiamata destinata al classificatore della [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) anziché a Claude. Consulta [Annotare un risultato per il classificatore della modalità auto](#annotate-a-result-for-the-auto-mode-classifier). Richiede Claude Code v2.1.236 o successiva |2218| `classifierContext` | Breve nota sul risultato di questa chiamata destinata al classificatore della [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) anziché a Claude. Consulta [Annotare un risultato per il classificatore della modalità auto](#annotate-a-result-for-the-auto-mode-classifier). Richiede Claude Code v2.1.236 o successiva |
2220| `updatedToolOutput` | Sostituisce l'output dello strumento con il valore fornito prima che venga inviato a Claude. Il valore deve corrispondere alla forma dell'output dello strumento |2219| `updatedToolOutput` | Sostituisce l'output dello strumento con il valore fornito prima che venga inviato a Claude. Il valore deve corrispondere alla struttura dell'output dello strumento |
2221| `updatedMCPToolOutput` | Sostituisce l'output solo per gli [strumenti MCP](#match-mcp-tools). Preferisci `updatedToolOutput`, che funziona per tutti gli strumenti |2220| `updatedMCPToolOutput` | Sostituisce l'output solo per gli [strumenti MCP](#match-mcp-tools). Preferisci `updatedToolOutput`, che funziona per tutti gli strumenti |
2222 2221
2223L'esempio seguente sostituisce l'output di una chiamata `Bash`. Il valore sostitutivo corrisponde alla forma dell'output dello strumento `Bash`:2222L'esempio seguente sostituisce l'output di una chiamata `Bash`. Il valore sostitutivo corrisponde alla struttura dell'output dello strumento `Bash`:
2224 2223
2225```json theme={null}2224```json theme={null}
2226{2225{
2238```2237```
2239 2238
2240<Warning>2239<Warning>
2241 `updatedToolOutput` modifica solo ciò che Claude vede. Lo strumento è già stato eseguito quando l'hook si attiva, quindi eventuali file scritti, comandi eseguiti o richieste di rete inviate hanno già avuto effetto. Anche la telemetria, come gli span OpenTelemetry degli strumenti e gli eventi di analisi, acquisisce l'output originale prima che l'hook venga eseguito. Per impedire o modificare una chiamata a uno strumento prima che venga eseguita, usa invece un hook [PreToolUse](#pretooluse).2240 `updatedToolOutput` modifica solo ciò che vede Claude. Lo strumento è già stato eseguito quando l'hook si attiva, quindi eventuali file scritti, comandi eseguiti o richieste di rete inviate hanno già avuto effetto. Anche la telemetria, come gli span degli strumenti OpenTelemetry e gli eventi di analisi, acquisisce l'output originale prima dell'esecuzione dell'hook. Per impedire o modificare una chiamata a uno strumento prima che venga eseguita, usa invece un hook [PreToolUse](#pretooluse).
2242 2241
2243 Il valore sostitutivo deve corrispondere alla forma dell'output dello strumento. Gli strumenti integrati restituiscono oggetti strutturati anziché semplici stringhe. Ad esempio, `Bash` restituisce un oggetto con i campi `stdout`, `stderr`, `interrupted` e `isImage`. Per gli strumenti integrati, un valore che non corrisponde allo schema di output dello strumento viene ignorato e viene usato l'output originale. L'output degli strumenti MCP viene passato senza convalida dello schema. Rimuovere dettagli di errore di cui Claude ha bisogno può portarlo a procedere sulla base di un presupposto errato.2242 Il valore sostitutivo deve corrispondere alla struttura dell'output dello strumento. Gli strumenti integrati restituiscono oggetti strutturati anziché semplici stringhe. Ad esempio, `Bash` restituisce un oggetto con i campi `stdout`, `stderr`, `interrupted` e `isImage`. Per gli strumenti integrati, un valore che non corrisponde allo schema di output dello strumento viene ignorato e viene usato l'output originale. L'output degli strumenti MCP viene passato senza validazione dello schema. Rimuovere dettagli di errore di cui Claude ha bisogno può indurlo a procedere sulla base di un presupposto errato.
2244</Warning>2243</Warning>
2245 2244
2246<h4 id="annotate-a-result-for-the-auto-mode-classifier">2245<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2263Il peso che il classificatore attribuisce alla nota dipende da dove hai configurato l'hook:2262Il peso che il classificatore attribuisce alla nota dipende da dove hai configurato l'hook:
2264 2263
2265* **Hook configurati in Claude Code**: per gli hook provenienti da file di impostazioni, plugin, skill e frontmatter degli agenti, il classificatore tratta la nota come contesto non verificato fornito dall'applicazione. La nota non stabilisce mai l'intento dell'utente e, se afferma che hai approvato o richiesto qualcosa, il classificatore verifica tale affermazione confrontandola con i tuoi messaggi nella conversazione2264* **Hook configurati in Claude Code**: per gli hook provenienti da file di impostazioni, plugin, skill e frontmatter degli agenti, il classificatore tratta la nota come contesto non verificato fornito dall'applicazione. La nota non stabilisce mai l'intento dell'utente e, se afferma che hai approvato o richiesto qualcosa, il classificatore verifica tale affermazione confrontandola con i tuoi messaggi nella conversazione
2266* **Callback in-process dell'Agent SDK**: quando un'applicazione che incorpora Claude Code registra l'hook come [callback dell'SDK TypeScript](/docs/it/agent-sdk/hooks) e restituisce la nota durante la sessione attiva, il classificatore può considerare come intento dell'utente una dichiarazione dell'utente riportata nella nota. Tale dichiarazione può soddisfare un requisito di consenso che il classificatore accetterebbe da un messaggio inviato da te, ma non rimuove mai un blocco che nemmeno un tuo messaggio potrebbe rimuovere. Dopo la ripresa di una sessione, Claude Code tratta le note ripristinate come contesto non verificato. Quando hook di entrambi i gruppi annotano la stessa chiamata, il classificatore tratta la nota combinata come non verificata2265* **Callback in-process dell'Agent SDK**: quando un'applicazione che incorpora Claude Code registra l'hook come [callback del TypeScript SDK](/docs/it/agent-sdk/hooks) e restituisce la nota durante la sessione attiva, il classificatore può considerare come intento dell'utente una dichiarazione dell'utente riportata nella nota. Tale dichiarazione può soddisfare un requisito di consenso che il classificatore accetterebbe da un messaggio che invii tu, ma non rimuove mai un blocco che nemmeno un tuo messaggio potrebbe rimuovere. Dopo la ripresa di una sessione, Claude Code tratta le note ripristinate come contesto non verificato. Quando hook di entrambi i gruppi annotano la stessa chiamata, il classificatore tratta la nota combinata come non verificata
2267 2266
2268Claude Code applica questi limiti quando consegna la nota:2267Claude Code applica questi limiti quando consegna la nota:
2269 2268
2270* **Lunghezza**: Claude Code limita le note per una singola chiamata a uno strumento a 2.000 caratteri e tronca il resto. Il limite è condiviso tra tutti gli hook che rispondono a quella chiamata2269* **Lunghezza**: Claude Code limita le note per una singola chiamata a uno strumento a 2.000 caratteri e tronca il resto. Il limite è condiviso tra tutti gli hook che rispondono a quella chiamata
2271* **Solo risposte sincrone**: Claude Code ignora il campo nella risposta di un hook che [viene eseguito in background](#run-hooks-in-the-background), perché quella risposta arriva dopo che Claude Code ha registrato il risultato dello strumento2270* **Solo risposte sincrone**: Claude Code ignora il campo nella risposta di un hook che [viene eseguito in background](#run-hooks-in-the-background), perché quella risposta arriva dopo che Claude Code ha registrato il risultato dello strumento
2272* **Chiamate che il classificatore non registra**: la trascrizione del classificatore omette le consultazioni di sola lettura come letture di file e ricerche. Claude Code scarta una nota associata a una di queste chiamate2271* **Chiamate che il classificatore non registra**: la trascrizione del classificatore omette le consultazioni di sola lettura, come le letture di file e le ricerche. Claude Code scarta una nota associata a una di queste chiamate
2273* **Interazione con le riscritture**: quando la nota descrive un output che stai sostituendo con `updatedToolOutput`, restituisci entrambi i campi nella stessa risposta dell'hook. Claude Code scarta la nota se quella riscrittura viene rifiutata o se la riscrittura di un altro hook la sostituisce. Claude Code consegna una nota restituita senza riscrittura anche quando un altro hook riscrive l'output2272* **Interazione con le riscritture**: quando la nota descrive un output che stai sostituendo con `updatedToolOutput`, restituisci entrambi i campi nella stessa risposta dell'hook. Claude Code scarta la nota se quella riscrittura viene rifiutata o se la riscrittura di un altro hook la sostituisce. Claude Code consegna una nota restituita senza riscrittura anche quando un altro hook riscrive l'output
2274 2273
2275<Warning>2274<Warning>
2276 Il classificatore legge il contenuto che inserisci in `classifierContext` come informazione proveniente dall'applicazione che ospita la sessione, quindi non copiarvi output di strumenti non attendibili o testo di terze parti. Limita la nota a una breve affermazione su questa singola chiamata, ad esempio un fatto sulla sua origine o una dichiarazione dell'utente al riguardo; non usare il campo per consegnare messaggi non correlati o un flusso di eventi.2275 Il classificatore legge il contenuto che inserisci in `classifierContext` come informazione proveniente dall'applicazione che ospita la sessione, quindi non copiarvi output di strumenti non attendibili o testo di terze parti. Limita la nota a una breve affermazione su questa singola chiamata, come un fatto sulla sua origine o una dichiarazione dell'utente in merito; non usare il campo per consegnare messaggi non correlati o un flusso di eventi.
2277</Warning>2276</Warning>
2278 2277
2279<h3 id="posttoolusefailure">2278<h3 id="posttoolusefailure">
2280 PostToolUseFailure2279 PostToolUseFailure
2281</h3>2280</h3>
2282 2281
2283Viene eseguito quando uno strumento che ha iniziato l'esecuzione fallisce: lo strumento ha generato un errore o uno strumento MCP ha restituito un risultato di errore. Usalo per registrare i fallimenti, inviare avvisi o fornire feedback correttivo a Claude.2282Viene eseguito quando uno strumento che ha iniziato l'esecuzione fallisce: lo strumento ha generato un errore, oppure uno strumento MCP ha restituito un risultato di errore. Usalo per registrare i fallimenti, inviare avvisi o fornire feedback correttivo a Claude.
2284 2283
2285Fa corrispondere il nome dello strumento, con gli stessi valori di PreToolUse.2284Corrisponde sul nome dello strumento, con gli stessi valori di PreToolUse.
2286 2285
2287<Note>2286<Note>
2288 Questo evento non si attiva per le chiamate agli strumenti rifiutate prima dell'esecuzione: un nome di strumento sconosciuto, un input che non supera la convalida dello schema o quella specifica dello strumento, o un permesso negato. I rifiuti di convalida vengono restituiti come risultati `tool_use_error` e avvengono prima dell'esecuzione degli hook, quindi non attivano né `PreToolUse` né `PostToolUseFailure`. I permessi negati attivano `PreToolUse` ma non questo evento; consulta [PermissionDenied](#permissiondenied).2287 Questo evento non si attiva per le chiamate agli strumenti rifiutate prima dell'esecuzione: un nome di strumento sconosciuto, un input che non supera la validazione dello schema o quella specifica dello strumento, oppure un rifiuto del permesso. I rifiuti per validazione vengono restituiti come risultati `tool_use_error` e avvengono prima dell'esecuzione degli hook, quindi non attivano né `PreToolUse` né `PostToolUseFailure`. I rifiuti del permesso attivano `PreToolUse` ma non questo evento; consulta [PermissionDenied](#permissiondenied).
2289</Note>2288</Note>
2290 2289
2291<h4 id="posttoolusefailure-input">2290<h4 id="posttoolusefailure-input">
2292 Input di PostToolUseFailure2291 Input di PostToolUseFailure
2293</h4>2292</h4>
2294 2293
2295Gli hook PostToolUseFailure ricevono gli stessi campi `tool_name` e `tool_input` di PostToolUse, insieme alle informazioni sull'errore come campi di primo livello. Per uno strumento MCP, ricevono anche l'oggetto [`mcp_server`](#pretooluse-input). Ad esempio, un comando `npm test` fallito potrebbe restituire:2294Gli hook PostToolUseFailure ricevono gli stessi campi `tool_name` e `tool_input` di PostToolUse, insieme alle informazioni sull'errore come campi di primo livello. Per uno strumento MCP, ricevono anche l'oggetto [`mcp_server`](#pretooluse-input). Ad esempio, un comando `npm test` fallito potrebbe fornire:
2296 2295
2297```json theme={null}2296```json theme={null}
2298{2297{
2316| Campo | Descrizione |2315| Campo | Descrizione |
2317| :- | :- |2316| :- | :- |
2318| `error` | Stringa che descrive cosa è andato storto. Il formato dipende dallo strumento che ha fallito |2317| `error` | Stringa che descrive cosa è andato storto. Il formato dipende dallo strumento che ha fallito |
2319| `is_interrupt` | Booleano facoltativo. True quando il fallimento ha raggiunto Claude Code come interruzione anziché come errore segnalato dallo strumento. L'annullamento di uno strumento in esecuzione non attiva questo hook; il risultato dello strumento contiene invece il messaggio di interruzione |2318| `is_interrupt` | Booleano facoltativo. True quando il fallimento ha raggiunto Claude Code come interruzione anziché come errore segnalato dallo strumento. Annullare uno strumento in esecuzione non attiva questo hook; il risultato dello strumento contiene invece il messaggio di interruzione |
2320| `duration_ms` | Facoltativo. Tempo di esecuzione dello strumento in millisecondi. Esclude il tempo trascorso nelle richieste di permesso e negli hook PreToolUse |2319| `duration_ms` | Facoltativo. Tempo di esecuzione dello strumento in millisecondi. Esclude il tempo trascorso nelle richieste di permesso e negli hook PreToolUse |
2321 2320
2322La stringa `error` è generalmente lo stesso testo che Claude riceve come risultato dello strumento fallito. Il suo formato varia in base allo strumento e al tipo di fallimento. Basa il tuo hook su `tool_name`, `is_interrupt` e sulla prima riga `Exit code N`; tratta il resto della stringa come testo di visualizzazione, non come un formato stabile.2321La stringa `error` è generalmente lo stesso testo che Claude riceve come risultato dello strumento fallito. Il suo formato varia in base allo strumento e al tipo di fallimento. Basa il tuo hook su `tool_name`, `is_interrupt` e sulla prima riga `Exit code N`; tratta il resto della stringa come testo di visualizzazione, non come un formato stabile.
2323 2322
2324* Per Bash e PowerShell, un comando eseguito e terminato produce una prima riga `Exit code N`, seguita da qualsiasi output prodotto dal comando come un unico blocco con stdout e stderr intercalati2323* Per Bash e PowerShell, un comando che è stato eseguito ed è terminato produce una prima riga `Exit code N`, seguita da qualsiasi output prodotto dal comando come un unico blocco con stdout e stderr intercalati
2325* Un payload può anche contenere un semplice messaggio di errore senza riga del codice di uscita, quando Claude Code non è riuscito ad avviare il processo della shell stesso2324* Un payload può anche contenere un semplice messaggio di fallimento senza riga del codice di uscita, quando Claude Code non è riuscito ad avviare il processo della shell stesso
2326* Claude Code tronca al centro le stringhe lunghe attorno a un indicatore `... [N characters truncated] ...` e può inserire righe proprie, come `Command timed out after 2m 0s`2325* Claude Code tronca al centro le stringhe lunghe attorno a un marcatore `... [N characters truncated] ...` e può inserire righe proprie, come `Command timed out after 2m 0s`
2327 2326
2328<h4 id="posttoolusefailure-decision-control">2327<h4 id="posttoolusefailure-decision-control">
2329 Controllo delle decisioni di PostToolUseFailure2328 Controllo delle decisioni di PostToolUseFailure
2330</h4>2329</h4>
2331 2330
2332Gli hook `PostToolUseFailure` possono fornire contesto a Claude dopo il fallimento di uno strumento. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, lo script del tuo hook può restituire questi campi specifici dell'evento:2331Gli hook `PostToolUseFailure` possono fornire contesto a Claude dopo il fallimento di uno strumento. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, il tuo script di hook può restituire questi campi specifici dell'evento:
2333 2332
2334| Campo | Descrizione |2333| Campo | Descrizione |
2335| :- | :- |2334| :- | :- |
2348 PostToolBatch2347 PostToolBatch
2349</h3>2348</h3>
2350 2349
2351Viene eseguito una volta dopo che ogni chiamata a uno strumento in un batch è stata risolta, prima che Claude Code invii la richiesta successiva al modello. `PostToolUse` si attiva una volta per strumento, il che significa che si attiva in modo concorrente quando Claude effettua chiamate agli strumenti in parallelo. `PostToolBatch` si attiva esattamente una volta con l'intero batch, quindi è il punto giusto per iniettare contesto che dipende dall'insieme degli strumenti eseguiti anziché da un singolo strumento. Non esiste un matcher per questo evento.2350Viene eseguito una volta dopo che ogni chiamata a uno strumento in un batch è stata risolta, prima che Claude Code invii la richiesta successiva al modello. `PostToolUse` si attiva una volta per strumento, il che significa che si attiva in modo concorrente quando Claude effettua chiamate agli strumenti in parallelo. `PostToolBatch` si attiva esattamente una volta con l'intero batch, quindi è il posto giusto per iniettare contesto che dipende dall'insieme di strumenti eseguiti anziché da un singolo strumento. Non esiste un matcher per questo evento.
2352 2351
2353<h4 id="posttoolbatch-input">2352<h4 id="posttoolbatch-input">
2354 Input di PostToolBatch2353 Input di PostToolBatch
2380}2379}
2381```2380```
2382 2381
2383`tool_response` contiene lo stesso contenuto che il modello riceve nel blocco `tool_result` corrispondente. Il valore è una stringa serializzata o un array di blocchi di contenuto, esattamente come lo strumento l'ha emesso. Per `Read`, ciò significa testo con prefisso del numero di riga anziché il contenuto grezzo del file. Le risposte possono essere di grandi dimensioni, quindi analizza solo i campi di cui hai bisogno.2382`tool_response` contiene lo stesso contenuto che il modello riceve nel blocco `tool_result` corrispondente. Il valore è una stringa serializzata o un array di blocchi di contenuto, esattamente come lo ha emesso lo strumento. Per `Read`, ciò significa testo con il numero di riga come prefisso anziché il contenuto grezzo del file. Le risposte possono essere grandi, quindi analizza solo i campi di cui hai bisogno.
2384 2383
2385<Note>2384<Note>
2386 La forma di `tool_response` è diversa da quella di `PostToolUse`. `PostToolUse` passa l'oggetto `Output` strutturato dello strumento, come `{filePath: "...", type: "create"}` per `Write`; `PostToolBatch` passa il contenuto `tool_result` serializzato che vede il modello.2385 La struttura di `tool_response` differisce da quella di `PostToolUse`. `PostToolUse` passa l'oggetto `Output` strutturato dello strumento, come `{filePath: "...", type: "create"}` per `Write`; `PostToolBatch` passa il contenuto `tool_result` serializzato che vede il modello.
2387</Note>2386</Note>
2388 2387
2389<h4 id="posttoolbatch-decision-control">2388<h4 id="posttoolbatch-decision-control">
2390 Controllo delle decisioni di PostToolBatch2389 Controllo delle decisioni di PostToolBatch
2391</h4>2390</h4>
2392 2391
2393Gli hook `PostToolBatch` possono iniettare contesto per Claude. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, lo script del tuo hook può restituire questi campi specifici dell'evento:2392Gli hook `PostToolBatch` possono iniettare contesto per Claude. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, il tuo script di hook può restituire questi campi specifici dell'evento:
2394 2393
2395| Campo | Descrizione |2394| Campo | Descrizione |
2396| :- | :- |2395| :- | :- |
2397| `additionalContext` | Stringa di contesto iniettata una volta prima della chiamata successiva al modello. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) per i dettagli di consegna, cosa inserirvi e come le sessioni riprese gestiscono i valori passati |2396| `additionalContext` | Stringa di contesto iniettata una volta prima della chiamata successiva al modello. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) per i dettagli sulla consegna, su cosa inserirvi e su come le sessioni riprese gestiscono i valori passati |
2398 2397
2399```json theme={null}2398```json theme={null}
2400{2399{
2405}2404}
2406```2405```
2407 2406
2408Restituire `decision: "block"` o `continue: false` interrompe il ciclo agentico prima della chiamata successiva al modello. Il messaggio di blocco proviene dal `reason` o dallo `stopReason` del JSON, oppure da stderr con uscita 2. Lo vedi come avviso nella trascrizione e rimane nella conversazione, quindi Claude lo vede quando la conversazione prosegue.2407Restituire `decision: "block"` o `continue: false` arresta il ciclo agentico prima della chiamata successiva al modello. Il messaggio di blocco proviene dal `reason` o dallo `stopReason` JSON, oppure da stderr con uscita 2. Lo vedi come avviso nella trascrizione, e rimane nella conversazione, quindi Claude lo vede quando la conversazione continua.
2409 2408
2410<h3 id="permissiondenied">2409<h3 id="permissiondenied">
2411 PermissionDenied2410 PermissionDenied
2412</h3>2411</h3>
2413 2412
2414Viene eseguito quando la [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) nega una chiamata a uno strumento, anche quando la nega senza un verdetto del classificatore perché [un controllo di sicurezza separato dalla modalità auto ha rifiutato la richiesta del classificatore stesso](/docs/it/errors#auto-mode-cannot-determine-the-safety-of-an-action) o la sua risposta non è stata analizzata correttamente. Questo hook si attiva solo in modalità auto: non viene eseguito quando neghi manualmente una finestra di dialogo dei permessi, quando un hook `PreToolUse` blocca una chiamata o quando corrisponde una regola `deny`. Usalo per registrare i dinieghi, modificare la configurazione o dire al modello che può riprovare la chiamata allo strumento.2413Viene eseguito quando la [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) rifiuta una chiamata a uno strumento, anche quando la rifiuta senza un verdetto del classificatore perché [un controllo di sicurezza separato dalla modalità auto ha rifiutato la richiesta del classificatore stesso](/docs/it/errors#auto-mode-cannot-determine-the-safety-of-an-action) o la sua risposta non è stata interpretabile. Questo hook si attiva solo in modalità auto: non viene eseguito quando rifiuti manualmente una finestra di dialogo di permesso, quando un hook `PreToolUse` blocca una chiamata o quando corrisponde una regola `deny`. Usalo per registrare i rifiuti, modificare la configurazione o comunicare al modello che può riprovare la chiamata allo strumento.
2415 2414
2416Fa corrispondere il nome dello strumento, con gli stessi valori di PreToolUse.2415Corrisponde sul nome dello strumento, con gli stessi valori di PreToolUse.
2417 2416
2418<h4 id="permissiondenied-input">2417<h4 id="permissiondenied-input">
2419 Input di PermissionDenied2418 Input di PermissionDenied
2440 2439
2441| Campo | Descrizione |2440| Campo | Descrizione |
2442| :- | :- |2441| :- | :- |
2443| `reason` | Il motivo del diniego. Per un verdetto del classificatore, nella maggior parte delle sessioni indica la regola corrispondente tra parentesi quadre, come `[Data Exfiltration]`; consulta [Esaminare i dinieghi](/docs/it/auto-mode-config#review-denials) per le altre forme. Per un [diniego senza verdetto](#permissiondenied-decision-control), inizia con `Auto mode could not evaluate this action and is blocking it for safety`. Per un diniego dovuto al fatto che il modello del classificatore non era disponibile, è il testo fisso `Classifier unavailable` |2442| `reason` | Il motivo del rifiuto. Per un verdetto del classificatore, nella maggior parte delle sessioni indica la regola corrispondente tra parentesi quadre, come `[Data Exfiltration]`; consulta [Esaminare i rifiuti](/docs/it/auto-mode-config#review-denials) per le altre forme. Per un [rifiuto senza verdetto](#permissiondenied-decision-control), inizia con `Auto mode could not evaluate this action and is blocking it for safety`. Per un rifiuto dovuto all'indisponibilità del modello classificatore, è il testo fisso `Classifier unavailable` |
2444 2443
2445<h4 id="permissiondenied-decision-control">2444<h4 id="permissiondenied-decision-control">
2446 Controllo delle decisioni di PermissionDenied2445 Controllo delle decisioni di PermissionDenied
2447</h4>2446</h4>
2448 2447
2449Gli hook PermissionDenied possono dire al modello che può riprovare la chiamata allo strumento negata. Restituisci un oggetto JSON con `hookSpecificOutput.retry` impostato su `true`:2448Gli hook PermissionDenied possono comunicare al modello che può riprovare la chiamata allo strumento rifiutata. Restituisci un oggetto JSON con `hookSpecificOutput.retry` impostato su `true`:
2450 2449
2451```json theme={null}2450```json theme={null}
2452{2451{
2457}2456}
2458```2457```
2459 2458
2460Quando `retry` è `true`, Claude Code aggiunge un messaggio alla conversazione che dice al modello che può riprovare la chiamata allo strumento. Claude Code non annulla il diniego stesso. Se il tuo hook non restituisce JSON o restituisce `retry: false`, il diniego resta valido e il modello riceve il messaggio di rifiuto originale.2459Quando `retry` è `true`, Claude Code aggiunge un messaggio alla conversazione che comunica al modello che può riprovare la chiamata allo strumento. Claude Code non annulla il rifiuto stesso. Se il tuo hook non restituisce JSON, o restituisce `retry: false`, il rifiuto resta valido e il modello riceve il messaggio di rifiuto originale.
2461 2460
2462Claude Code ignora `retry: true` quando il classificatore non ha prodotto [alcun verdetto sull'azione](/docs/it/errors#auto-mode-cannot-determine-the-safety-of-an-action): la sua risposta non è stata analizzata correttamente, oppure un controllo di sicurezza separato dalla modalità auto ha rifiutato la richiesta del classificatore stesso. Per questi dinieghi, Claude Code indica già al modello nel messaggio di rifiuto se riprovare più tardi o andare avanti.2461Claude Code ignora `retry: true` quando il classificatore non ha prodotto [alcun verdetto sull'azione](/docs/it/errors#auto-mode-cannot-determine-the-safety-of-an-action): la sua risposta non è stata interpretabile, oppure un controllo di sicurezza separato dalla modalità auto ha rifiutato la richiesta del classificatore stesso. Per questi rifiuti, Claude Code indica già al modello nel messaggio di rifiuto se riprovare più tardi o andare avanti.
2463 2462
2464<h3 id="notification">2463<h3 id="notification">
2465 Notification2464 Notification
2466</h3>2465</h3>
2467 2466
2468Viene eseguito quando Claude Code invia notifiche. Fa corrispondere il tipo di notifica. Ometti il matcher per eseguire gli hook per tutti i tipi di notifica.2467Viene eseguito quando Claude Code invia notifiche. Corrisponde sul tipo di notifica. Ometti il matcher per eseguire gli hook per tutti i tipi di notifica.
2469 2468
2470Ricevi questi eventi hook anche con le notifiche desktop disattivate: l'impostazione `preferredNotifChannel`, incluso `notifications_disabled`, cambia solo il modo in cui vieni avvisato, non se il tuo hook viene eseguito.2469Ricevi questi eventi di hook anche con le notifiche desktop disattivate: l'impostazione `preferredNotifChannel`, incluso `notifications_disabled`, cambia solo il modo in cui vieni avvisato, non se il tuo hook viene eseguito.
2471 2470
2472| Matcher | Quando si attiva |2471| Matcher | Quando si attiva |
2473| :- | :- |2472| :- | :- |
2476| `auth_success` | L'autenticazione viene completata |2475| `auth_success` | L'autenticazione viene completata |
2477| `elicitation_dialog` | Un server MCP apre un modulo di elicitazione e non digiti da circa sei secondi |2476| `elicitation_dialog` | Un server MCP apre un modulo di elicitazione e non digiti da circa sei secondi |
2478| `elicitation_url_dialog` | Un server MCP ti chiede di aprire un URL nel browser e non digiti da circa sei secondi |2477| `elicitation_url_dialog` | Un server MCP ti chiede di aprire un URL nel browser e non digiti da circa sei secondi |
2479| `elicitation_complete` | Un server MCP segnala che un'[elicitazione in modalità URL](#elicitation-input) è completa |2478| `elicitation_complete` | Un server MCP segnala che un'[elicitazione in modalità URL](#elicitation-input) è completata |
2480| `elicitation_response` | Una risposta di elicitazione MCP viene inviata al server |2479| `elicitation_response` | Una risposta di elicitazione MCP viene inviata al server |
2481| `agent_needs_input` | Una sessione in background inizia ad attendere un tuo input mentre la [vista agenti](/docs/it/agent-view) è aperta in un terminale. Si attiva anche quando una sessione nel terminale ti mostra la [domanda di configurazione del terminale di un compagno di un team di agenti](/docs/it/agent-teams#choose-a-display-mode) o l'avviso della modalità auto sugli [addebiti per le richieste del classificatore](/docs/it/auto-mode-classifier-billing) e non digiti da circa sei secondi |2480| `agent_needs_input` | Una sessione in background inizia ad attendere un tuo input mentre la [vista agenti](/docs/it/agent-view) è aperta in un terminale. Si attiva anche quando una sessione del terminale ti mostra una [domanda di configurazione del terminale di un membro di un team di agenti](/docs/it/agent-teams#choose-a-display-mode) o l'avviso della modalità auto sugli [addebiti per le richieste del classificatore](/docs/it/auto-mode-classifier-billing) e non digiti da circa sei secondi |
2482| `agent_completed` | Una sessione in background termina o fallisce. Si attiva solo mentre la [vista agenti](/docs/it/agent-view) è aperta in un terminale |2481| `agent_completed` | Una sessione in background termina o fallisce. Si attiva solo mentre la [vista agenti](/docs/it/agent-view) è aperta in un terminale |
2483| `quota_auto_resume_fired` | Claude Code prosegue il tuo task dopo che un limite di utilizzo di claude.ai lo aveva messo in pausa: al reset, o prima quando qualcosa che fai in Claude Code durante l'attesa, come aggiungere crediti di utilizzo, effettuare l'upgrade del piano o cambiare modello, rende di nuovo disponibile l'utilizzo, con l'[eccezione relativa all'impostazione del modello](/docs/it/interactive-mode#wait-for-a-usage-limit-to-reset) |2482| `quota_auto_resume_fired` | Claude Code riprende la tua attività dopo che un limite di utilizzo di claude.ai l'aveva messa in pausa: al momento del ripristino, oppure prima quando qualcosa che fai in Claude Code durante l'attesa, come aggiungere crediti di utilizzo, passare a un piano superiore o cambiare modello, rende di nuovo disponibile l'utilizzo, con l'[eccezione relativa all'impostazione del modello](/docs/it/interactive-mode#wait-for-a-usage-limit-to-reset) |
2484| `quota_auto_resume_stale` | Un limite di utilizzo di claude.ai è stato reimpostato mentre il tuo computer era in sospensione per più di circa 30 minuti. Claude Code attende che tu prema `Enter` invece di proseguire. Dopo una sospensione più breve prosegue e attiva invece `quota_auto_resume_fired` |2483| `quota_auto_resume_stale` | Un limite di utilizzo di claude.ai è stato ripristinato mentre il tuo computer era in sospensione per più di circa 30 minuti. Claude Code attende che tu prema `Enter` invece di continuare. Dopo una sospensione più breve continua e attiva invece `quota_auto_resume_fired` |
2485| `quota_auto_resume_disabled` | Claude Code termina l'attesa per un limite di utilizzo di claude.ai senza proseguire il tuo task: [`autoContinueAtUsageLimit`](/docs/it/settings-reference#autocontinueatusagelimit) è stato disattivato o il reset si è spostato a più di 24 ore di distanza durante un'attesa avviata autonomamente da Claude Code, il task proseguito ha continuato a raggiungere il limite, oppure la prosecuzione è stata bloccata prima di raggiungere il modello. Non si attiva quando premi `Esc` o `Ctrl+C`, o scegli **Don't continue automatically** |2484| `quota_auto_resume_disabled` | Claude Code termina l'attesa per un limite di utilizzo di claude.ai senza riprendere la tua attività: [`autoContinueAtUsageLimit`](/docs/it/settings-reference#autocontinueatusagelimit) è stato disattivato o il ripristino si è spostato a più di 24 ore di distanza durante un'attesa avviata da Claude Code in autonomia, l'attività ripresa ha continuato a raggiungere il limite, oppure la ripresa è stata bloccata prima di raggiungere il modello. Non si attiva quando premi `Esc` o `Ctrl+C`, o scegli **Don't continue automatically** |
2486 2485
2487I tipi `quota_auto_resume_fired`, `quota_auto_resume_stale` e `quota_auto_resume_disabled` richiedono Claude Code v2.1.234 o successiva.2486I tipi `quota_auto_resume_fired`, `quota_auto_resume_stale` e `quota_auto_resume_disabled` richiedono Claude Code v2.1.234 o successiva.
2488 2487
2489Nelle sessioni nel terminale, `permission_prompt` per la richiesta di rete di un comando in sandbox richiede Claude Code v2.1.246 o successiva.2488Nelle sessioni del terminale, `permission_prompt` per la richiesta di rete di un comando in sandbox richiede Claude Code v2.1.246 o successiva.
2490 2489
2491`agent_needs_input` per la domanda di configurazione del terminale di un compagno di team richiede Claude Code v2.1.248 o successiva.2490`agent_needs_input` per la domanda di configurazione del terminale di un membro del team richiede Claude Code v2.1.248 o successiva.
2492 2491
2493<Note>2492<Note>
2494 I tipi `permission_prompt`, `idle_prompt`, `elicitation_dialog` ed `elicitation_url_dialog` condividono le tempistiche con le notifiche desktop, quindi nelle sessioni nel terminale li vedi solo quando sembri essere lontano dal terminale:2493 I tipi `permission_prompt`, `idle_prompt`, `elicitation_dialog` ed `elicitation_url_dialog` condividono la tempistica con le notifiche desktop, quindi nelle sessioni del terminale li vedi solo quando sembri essere lontano dal terminale:
2495 2494
2496 * Aspettati `permission_prompt` quando non digiti da circa sei secondi. Il timer parte quando appare la richiesta di permesso e ogni pressione di tasto lo posticipa. Per eseguire un hook immediatamente quando Claude chiede il permesso di usare uno strumento, usa invece [PermissionRequest](#permissionrequest).2495 * Aspettati `permission_prompt` quando non digiti da circa sei secondi. Il timer parte quando appare la richiesta di permesso, e ogni pressione di tasto lo rinvia. Per eseguire un hook immediatamente quando Claude chiede il permesso di usare uno strumento, usa invece [PermissionRequest](#permissionrequest).
2497 * Aspettati `idle_prompt` circa 60 secondi dopo che Claude ha finito di rispondere, e solo se da allora non hai digitato nulla e nessun agente in background, come un [subagent](/docs/it/sub-agents) in background, è ancora in esecuzione. Claude Code non invia `idle_prompt` mentre attende il reset di un limite di utilizzo di claude.ai. Quando l'attesa termina da sola, si attiva invece uno dei tipi `quota_auto_resume_*`.2496 * Aspettati `idle_prompt` circa 60 secondi dopo che Claude ha finito di rispondere, e solo se da allora non hai digitato e nessun agente in background, come un [subagent](/docs/it/sub-agents) in background, è ancora in esecuzione. Claude Code non invia `idle_prompt` mentre attende il ripristino di un limite di utilizzo di claude.ai. Quando l'attesa termina da sola, si attiva invece uno dei tipi `quota_auto_resume_*`.
2498 * Aspettati `elicitation_dialog` per un modulo di elicitazione, o `elicitation_url_dialog` per una richiesta di URL nel browser, quando non digiti da circa sei secondi. Entrambi condividono la stessa soglia di sei secondi di `permission_prompt`: il timer parte quando appare la finestra di dialogo e ogni pressione di tasto lo posticipa.2497 * Aspettati `elicitation_dialog` per un modulo di elicitazione, o `elicitation_url_dialog` per una richiesta di URL nel browser, quando non digiti da circa sei secondi. Entrambi condividono la stessa soglia di sei secondi di `permission_prompt`: il timer parte quando appare la finestra di dialogo, e ogni pressione di tasto lo rinvia.
2499 2498
2500 Una richiesta di permesso o un'elicitazione che arriva mentre un'altra finestra di dialogo è sullo schermo mantiene la stessa soglia di sei secondi, calcolata dal momento in cui arriva la richiesta. La sua notifica può raggiungerti mentre la richiesta è ancora in attesa dietro la finestra di dialogo aperta.2499 Una richiesta di permesso o un'elicitazione che arriva mentre un'altra finestra di dialogo è sullo schermo mantiene la stessa soglia di sei secondi, calcolata dal momento in cui arriva la richiesta. La sua notifica può raggiungerti mentre la richiesta è ancora in attesa dietro la finestra di dialogo aperta.
2501</Note>2500</Note>
2502 2501
2503Claude Code calcola i tempi di `permission_prompt` in modo diverso nelle sessioni in cui invia le richieste di permesso alla [callback `canUseTool`](/docs/it/agent-sdk/user-input) dell'Agent SDK, che è il modo in cui Claude Desktop e l'estensione VS Code ospitano Claude Code:2502Claude Code calcola la tempistica di `permission_prompt` in modo diverso nelle sessioni in cui invia le richieste di permesso alla [callback `canUseTool`](/docs/it/agent-sdk/user-input) dell'Agent SDK, che è il modo in cui Claude Desktop e l'estensione VS Code ospitano Claude Code:
2504 2503
2505* Aspettati `permission_prompt` circa sei secondi dopo che Claude chiede il permesso. Claude Code non lo posticipa mentre digiti.2504* Aspettati `permission_prompt` circa sei secondi dopo che Claude chiede il permesso. Claude Code non lo rinvia mentre digiti.
2506* Se tu o un hook [PermissionRequest](#permissionrequest) rispondete prima, Claude Code non esegue `permission_prompt`.2505* Se tu o un hook [PermissionRequest](#permissionrequest) rispondete prima, Claude Code non esegue `permission_prompt`.
2507* Imposta [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/it/env-vars) su `1` per disattivare `permission_prompt` in queste sessioni.2506* Imposta [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/it/env-vars) su `1` per disattivare `permission_prompt` in queste sessioni.
2508 2507
2541 Input di Notification2540 Input di Notification
2542</h4>2541</h4>
2543 2542
2544Oltre ai [campi di input comuni](#common-input-fields), gli hook Notification ricevono `message` con il testo della notifica, un `title` facoltativo e `notification_type` che indica quale tipo si è attivato.2543Oltre ai [campi di input comuni](#common-input-fields), gli hook Notification ricevono `message` con il testo della notifica, un `title` facoltativo e `notification_type`, che indica quale tipo si è attivato.
2545 2544
2546```json theme={null}2545```json theme={null}
2547{2546{
2555}2554}
2556```2555```
2557 2556
2558Gli hook Notification non possono bloccare né modificare le notifiche. Claude Code scarta i loro campi `systemMessage` e `continue` ma emette comunque [`terminalSequence`](#emit-terminal-notifications), su cui si basa l'esempio di notifica desktop. Gli hook Notification sono pensati per effetti collaterali come l'inoltro della notifica a un servizio esterno.2557Gli hook Notification non possono bloccare o modificare le notifiche. Claude Code scarta i loro campi `systemMessage` e `continue` ma emette comunque [`terminalSequence`](#emit-terminal-notifications), su cui si basa l'esempio di notifica desktop. Gli hook Notification sono pensati per effetti collaterali come l'inoltro della notifica a un servizio esterno.
2559 2558
2560<h3 id="subagentstart">2559<h3 id="subagentstart">
2561 SubagentStart2560 SubagentStart
2562</h3>2561</h3>
2563 2562
2564Viene eseguito quando Claude genera un subagent con lo strumento Agent, quando Claude [riprende un subagent](/docs/it/sub-agents#resume-subagents) e ogni volta che un compagno in-process di un [team di agenti](/docs/it/agent-teams) gestisce un nuovo messaggio. Supporta i matcher per filtrare in base al nome del tipo di agente. Per gli agenti integrati, si tratta del nome dell'agente come `general-purpose`, `Explore` o `Plan`. Per i [subagent personalizzati](/docs/it/sub-agents), si tratta del campo `name` del frontmatter dell'agente, non del nome del file.2563Viene eseguito quando Claude genera un subagent con lo strumento Agent, quando Claude [riprende un subagent](/docs/it/sub-agents#resume-subagents), e ogni volta che un membro in-process di un [team di agenti](/docs/it/agent-teams) gestisce un nuovo messaggio. Supporta i matcher per filtrare in base al nome del tipo di agente. Per gli agenti integrati, è il nome dell'agente, come `general-purpose`, `Explore` o `Plan`. Per i [subagent personalizzati](/docs/it/sub-agents), è il campo `name` del frontmatter dell'agente, non il nome del file.
2565 2564
2566Per i subagent forniti da un [plugin](/docs/it/plugins/overview), il tipo di agente è l'identificatore con ambito del plugin come `my-plugin:reviewer`, non il semplice nome del frontmatter. I due punti fanno sì che un nome con ambito del plugin venga trattato come espressione regolare, quindi ancora il matcher con `^` e `$` per una corrispondenza esatta: `^my-plugin:reviewer$`.2565Per i subagent forniti da un [plugin](/docs/it/plugins/overview), il tipo di agente è l'identificatore con ambito del plugin, come `my-plugin:reviewer`, non il semplice nome del frontmatter. I due punti collocano un nome con ambito del plugin sul percorso delle espressioni regolari, quindi ancora il matcher con `^` e `$` per una corrispondenza esatta: `^my-plugin:reviewer$`.
2567 2566
2568<h4 id="subagentstart-input">2567<h4 id="subagentstart-input">
2569 Input di SubagentStart2568 Input di SubagentStart
2597}2596}
2598```2597```
2599 2598
2600Quando l'hook viene eseguito di nuovo per lo stesso subagent, Claude Code inietta il contesto restituito solo se il contesto del subagent non contiene già la copia di un'esecuzione precedente. La copia iniettata all'avvio rimane al suo posto, lasciando intatta la [cache del prompt](/docs/it/prompt-caching#subagents-and-the-cache) del subagent. Dopo che la [compattazione automatica](/docs/it/sub-agents#auto-compaction) scarta quella copia, Claude Code inietta di nuovo il contesto dell'esecuzione successiva.2599Quando l'hook viene eseguito di nuovo per lo stesso subagent, Claude Code inietta il contesto restituito solo quando il contesto del subagent non contiene già la copia di un'esecuzione precedente. La copia iniettata all'avvio rimane al suo posto, lasciando intatta la [cache del prompt](/docs/it/prompt-caching#subagents-and-the-cache) del subagent. Dopo che la [compattazione automatica](/docs/it/sub-agents#auto-compaction) scarta quella copia, Claude Code inietta di nuovo il contesto dell'esecuzione successiva.
2601 2600
2602<h3 id="subagentstop">2601<h3 id="subagentstop">
2603 SubagentStop2602 SubagentStop
2604</h3>2603</h3>
2605 2604
2606Viene eseguito quando un subagent di Claude Code ha finito di rispondere. Fa corrispondere il tipo di agente, con gli stessi valori di SubagentStart.2605Viene eseguito quando un subagent di Claude Code ha finito di rispondere. Corrisponde sul tipo di agente, con gli stessi valori di SubagentStart.
2607 2606
2608<h4 id="subagentstop-input">2607<h4 id="subagentstop-input">
2609 Input di SubagentStop2608 Input di SubagentStop
2610</h4>2609</h4>
2611 2610
2612Oltre ai [campi di input comuni](#common-input-fields), gli hook SubagentStop ricevono `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path` e `last_assistant_message`. Il campo `agent_type` è il valore usato per il filtro del matcher. `transcript_path` è la trascrizione della sessione principale, mentre `agent_transcript_path` è la trascrizione del subagent stesso, archiviata in una cartella annidata `subagents/`. Il campo `last_assistant_message` contiene il contenuto testuale della risposta finale del subagent, quindi gli hook possono accedervi senza analizzare il file della trascrizione.2611Oltre ai [campi di input comuni](#common-input-fields), gli hook SubagentStop ricevono `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path` e `last_assistant_message`. Il campo `agent_type` è il valore usato per il filtraggio del matcher. Il `transcript_path` è la trascrizione della sessione principale, mentre `agent_transcript_path` è la trascrizione del subagent stesso, archiviata in una cartella annidata `subagents/`. Il campo `last_assistant_message` contiene il contenuto testuale della risposta finale del subagent, così gli hook possono accedervi senza analizzare il file della trascrizione.
2613 2612
2614Non tutti gli eventi SubagentStop provengono da un subagent generato da Claude. Claude Code esegue anche agenti interni per alcune delle sue funzionalità, come i [suggerimenti di prompt](/docs/it/interactive-mode#prompt-suggestions) e le [domande laterali con `/btw`](/docs/it/interactive-mode#side-questions-with-%2Fbtw), e SubagentStop si attiva anche quando uno di questi termina. Per questi eventi, `agent_type` è il nome dell'agente con cui viene eseguita la sessione stessa, ad esempio quello impostato con [`--agent`](/docs/it/cli-reference#cli-flags) o con l'[impostazione `agent`](/docs/it/settings-reference#agent), e una stringa vuota quando la sessione viene eseguita senza.2613Non tutti gli eventi SubagentStop provengono da un subagent generato da Claude. Claude Code esegue anche agenti interni per alcune delle sue funzionalità, come i [suggerimenti di prompt](/docs/it/interactive-mode#prompt-suggestions) e le [domande laterali `/btw`](/docs/it/interactive-mode#side-questions-with-%2Fbtw), e SubagentStop si attiva anche quando uno di questi termina. Per questi eventi, `agent_type` è il nome dell'agente con cui viene eseguita la sessione stessa, come quello impostato con [`--agent`](/docs/it/cli-reference#cli-flags) o con l'[impostazione `agent`](/docs/it/settings-reference#agent), ed è una stringa vuota quando la sessione viene eseguita senza.
2615 2614
2616Un `matcher` che nomina tipi di agente non corrisponde a un `agent_type` vuoto. Un hook il cui matcher è omesso, `""` o `"*"`, oppure è un'espressione regolare che corrisponde a una stringa vuota, viene eseguito anche per gli eventi con un `agent_type` vuoto.2615Un `matcher` che nomina tipi di agente non corrisponde a un `agent_type` vuoto. Un hook il cui matcher è omesso, `""` o `"*"`, oppure è un'espressione regolare che corrisponde a una stringa vuota, viene eseguito anche per gli eventi con un `agent_type` vuoto.
2617 2616
2618Su Claude Code v2.1.271 o successiva, un subagent che viene eseguito con lo strumento [`SubagentHandback`](/docs/it/tools-reference) consegna il proprio resoconto tramite quello strumento prima di fermarsi. Il campo `last_assistant_message` contiene quindi l'eventuale testo conclusivo del subagent, che non è il resoconto consegnato. Il resoconto è l'input `message` di quella chiamata, che un hook `PreToolUse` o `PostToolUse` con matcher su `SubagentHandback` riceve come `tool_input.message`.2617Su Claude Code v2.1.271 o successiva, un subagent eseguito con lo strumento [`SubagentHandback`](/docs/it/tools-reference) consegna il proprio resoconto tramite quello strumento prima di fermarsi. Il campo `last_assistant_message` contiene quindi il testo conclusivo del subagent, se presente, che non è il resoconto consegnato. Il resoconto è l'input `message` di quella chiamata, che un hook `PreToolUse` o `PostToolUse` con corrispondenza su `SubagentHandback` riceve come `tool_input.message`.
2619 2618
2620Gli hook SubagentStop ricevono anche gli array `background_tasks` e `session_crons` descritti in [Input di Stop](#stop-input). Entrambi gli array hanno come ambito la sessione padre, non il subagent.2619Gli hook SubagentStop ricevono anche gli array `background_tasks` e `session_crons` descritti in [Input di Stop](#stop-input). Entrambi gli array hanno come ambito la sessione padre, non il subagent.
2621 2620
2636}2635}
2637```2636```
2638 2637
2639Gli hook SubagentStop usano lo stesso formato di controllo delle decisioni degli [hook Stop](#stop-decision-control), incluso `hookSpecificOutput.additionalContext` con `hookEventName` impostato su `"SubagentStop"`, per un feedback non di errore che mantiene il subagent in esecuzione. Restituire `decision: "block"` con un `reason` mantiene il subagent in esecuzione e consegna `reason` al subagent come sua istruzione successiva. Un hook che blocca uscendo con codice 2 consegna il proprio messaggio stderr allo stesso modo. Per iniettare contesto nella sessione padre dopo che un subagent ha restituito il risultato, usa invece un hook [`PostToolUse`](#posttooluse) sullo strumento `Agent`.2638Gli hook SubagentStop usano lo stesso formato di controllo delle decisioni degli [hook Stop](#stop-decision-control), incluso `hookSpecificOutput.additionalContext` con `hookEventName` impostato su `"SubagentStop"`, per un feedback non di errore che mantiene in esecuzione il subagent. Restituire `decision: "block"` con un `reason` mantiene in esecuzione il subagent e consegna `reason` al subagent come sua istruzione successiva. Un hook che blocca uscendo con 2 consegna il suo messaggio stderr nello stesso modo. Per iniettare contesto nella sessione padre dopo che un subagent ha restituito il controllo, usa invece un hook [`PostToolUse`](#posttooluse) sullo strumento `Agent`.
2640 2639
2641<h3 id="taskcreated">2640<h3 id="taskcreated">
2642 TaskCreated2641 TaskCreated
2643</h3>2642</h3>
2644 2643
2645Viene eseguito quando un task viene creato tramite lo strumento `TaskCreate`. Usalo per imporre convenzioni di denominazione, richiedere descrizioni dei task o impedire la creazione di determinati task. In una [sessione senza gli strumenti Task](/docs/it/tools-reference#task-tool-availability), questo evento non si attiva.2644Viene eseguito quando un'attività viene creata tramite lo strumento `TaskCreate`. Usalo per imporre convenzioni di denominazione, richiedere descrizioni delle attività o impedire la creazione di determinate attività. In una [sessione senza gli strumenti Task](/docs/it/tools-reference#task-tool-availability), questo evento non si attiva.
2646 2645
2647Gli hook TaskCreated non supportano i matcher e si attivano a ogni occorrenza.2646Gli hook TaskCreated non supportano i matcher e si attivano a ogni occorrenza.
2648 2647
2668 2667
2669| Campo | Descrizione |2668| Campo | Descrizione |
2670| :- | :- |2669| :- | :- |
2671| `task_id` | Identificatore del task in fase di creazione |2670| `task_id` | Identificatore dell'attività in fase di creazione |
2672| `task_subject` | Titolo del task |2671| `task_subject` | Titolo dell'attività |
2673| `task_description` | Descrizione dettagliata del task. Può essere assente |2672| `task_description` | Descrizione dettagliata dell'attività. Può essere assente |
2674| `teammate_name` | Nome del compagno di team che crea il task. Può essere assente |2673| `teammate_name` | Nome del membro del team che crea l'attività. Può essere assente |
2675| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |2674| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |
2675| `agent_id` | In questo evento, il [campo di input comune](#common-input-fields) identifica il subagent o il [membro del team in-process](/docs/it/agent-teams#choose-a-display-mode) che crea l'attività. Può essere assente. Richiede Claude Code v2.1.290 o successiva |
2676 2676
2677<h4 id="taskcreated-decision-control">2677<h4 id="taskcreated-decision-control">
2678 Controllo delle decisioni di TaskCreated2678 Controllo delle decisioni di TaskCreated
2679</h4>2679</h4>
2680 2680
2681Un hook TaskCreated può bloccare la creazione in due modi. 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.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.
2682 2682
2683* **Codice di uscita 2**: Claude Code restituisce il testo di stderr come messaggio.2683* **Codice di uscita 2**: Claude Code restituisce il testo di stderr come messaggio.
2684* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code restituisce `reason` come messaggio.2684* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code restituisce `reason` come messaggio.
2685 2685
2686Questo esempio blocca i task i cui oggetti non seguono il formato richiesto:2686Questo esempio blocca le attività i cui oggetti non seguono il formato richiesto:
2687 2687
2688```bash theme={null}2688```bash theme={null}
2689#!/bin/bash2689#!/bin/bash
2702 TaskCompleted2702 TaskCompleted
2703</h3>2703</h3>
2704 2704
2705Viene eseguito quando un task viene contrassegnato come completato. Si attiva in due situazioni: quando un qualsiasi agente contrassegna esplicitamente un task come completato tramite lo strumento TaskUpdate, o quando un compagno di un [team di agenti](/docs/it/agent-teams) termina il proprio turno con task in corso. Usalo per imporre criteri di completamento, come il superamento dei test o dei controlli di lint, prima che un task possa essere chiuso.2705Viene eseguito quando un'attività viene contrassegnata come completata. Si attiva in due situazioni: quando un agente qualsiasi contrassegna esplicitamente un'attività come completata tramite lo strumento TaskUpdate, oppure quando un membro di un [team di agenti](/docs/it/agent-teams) termina il proprio turno con attività in corso. Usalo per imporre criteri di completamento, come il superamento dei test o dei controlli lint, prima che un'attività possa essere chiusa.
2706 2706
2707Gli hook TaskCompleted non supportano i matcher e si attivano a ogni occorrenza.2707Gli hook TaskCompleted non supportano i matcher e si attivano a ogni occorrenza.
2708 2708
2729 2729
2730| Campo | Descrizione |2730| Campo | Descrizione |
2731| :- | :- |2731| :- | :- |
2732| `task_id` | Identificatore del task in fase di completamento |2732| `task_id` | Identificatore dell'attività in fase di completamento |
2733| `task_subject` | Titolo del task |2733| `task_subject` | Titolo dell'attività |
2734| `task_description` | Descrizione dettagliata del task. Può essere assente |2734| `task_description` | Descrizione dettagliata dell'attività. Può essere assente |
2735| `teammate_name` | Nome del compagno di team che completa il task. Può essere assente |2735| `teammate_name` | Nome del membro del team che completa l'attività. Può essere assente |
2736| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |2736| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |
2737| `agent_id` | In questo evento, il [campo di input comune](#common-input-fields) identifica il subagent o il [membro del team in-process](/docs/it/agent-teams#choose-a-display-mode) che completa l'attività. Può essere assente. Richiede Claude Code v2.1.290 o successiva |
2737 2738
2738<h4 id="taskcompleted-decision-control">2739<h4 id="taskcompleted-decision-control">
2739 Controllo delle decisioni di TaskCompleted2740 Controllo delle decisioni di TaskCompleted
2740</h4>2741</h4>
2741 2742
2742Gli hook TaskCompleted supportano due modi per controllare il completamento dei task:2743Gli hook TaskCompleted supportano due modi per controllare il completamento delle attività:
2743 2744
2744* **Codice di uscita 2**: il task non viene contrassegnato come completato e il messaggio stderr viene restituito al modello come feedback.2745* **Codice di uscita 2**: l'attività non viene contrassegnata come completata e il messaggio di stderr viene restituito al modello come feedback.
2745* **JSON `{"continue": false, "stopReason": "..."}`**: quando l'evento è stato attivato da un compagno di team che termina il proprio turno, ferma completamente il compagno di team, in modo analogo al comportamento dell'hook `Stop`. Lo `stopReason` viene mostrato all'utente. Quando l'evento è stato attivato dallo strumento `TaskUpdate`, Claude Code ignora `continue: false`; il codice di uscita 2 blocca comunque il completamento.2746* **JSON `{"continue": false, "stopReason": "..."}`**: quando l'evento è stato attivato da un membro del team che termina il proprio turno, arresta completamente il membro del team, in modo analogo al comportamento dell'hook `Stop`. Lo `stopReason` viene mostrato all'utente. Quando l'evento è stato attivato dallo strumento `TaskUpdate`, Claude Code ignora `continue: false`; il codice di uscita 2 blocca comunque il completamento.
2746 2747
2747Questo esempio esegue i test e blocca il completamento del task se falliscono:2748Questo esempio esegue i test e blocca il completamento dell'attività se falliscono:
2748 2749
2749```bash theme={null}2750```bash theme={null}
2750#!/bin/bash2751#!/bin/bash
2765</h3>2766</h3>
2766 2767
2767Viene eseguito quando l'agente principale di Claude Code ha finito di rispondere. Non viene eseguito se2768Viene eseguito quando l'agente principale di Claude Code ha finito di rispondere. Non viene eseguito se
2768l'arresto è avvenuto a causa di un'interruzione da parte dell'utente. Gli errori API attivano2769l'arresto è avvenuto a causa di un'interruzione da parte dell'utente. Gli errori API attivano invece
2769invece [StopFailure](#stopfailure).2770[StopFailure](#stopfailure).
2770 2771
2771<Tip>2772<Tip>
2772 Il comando [`/goal`](/docs/it/goal) è una scorciatoia integrata per un hook Stop basato su prompt con ambito di sessione. Usalo quando vuoi che Claude continui a lavorare verso una condizione senza scrivere la configurazione dell'hook.2773 Il comando [`/goal`](/docs/it/goal) è una scorciatoia integrata per un hook Stop basato su prompt con ambito di sessione. Usalo quando vuoi che Claude continui a lavorare verso una condizione senza scrivere la configurazione dell'hook.
2776 Input di Stop2777 Input di Stop
2777</h4>2778</h4>
2778 2779
2779Oltre ai [campi di input comuni](#common-input-fields), gli hook Stop ricevono `stop_hook_active`, `last_assistant_message`, `background_tasks` e `session_crons`. Il campo `stop_hook_active` è `true` quando Claude Code sta già proseguendo a seguito di uno stop hook. Controlla questo valore o elabora la trascrizione per evitare di bloccare su una condizione che non si risolverà mai.2780Oltre ai [campi di input comuni](#common-input-fields), gli hook Stop ricevono `stop_hook_active`, `last_assistant_message`, `background_tasks` e `session_crons`. Il campo `stop_hook_active` è `true` quando Claude Code sta già continuando a causa di un hook stop. Controlla questo valore o elabora la trascrizione per evitare di bloccare su una condizione che non si risolverà mai.
2780 2781
2781Claude Code applica un limite di 8 prosecuzioni consecutive: dopo che gli stop hook hanno fatto proseguire il turno otto volte di seguito, Claude Code sovrascrive il blocco successivo e termina il turno. Il conteggio delle prosecuzioni consecutive si azzera ogni volta che Claude chiama uno strumento. Per aumentare il limite, imposta [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/it/env-vars).2782Claude Code applica un limite di 8 continuazioni consecutive: dopo che gli hook stop hanno fatto continuare il turno otto volte di seguito, Claude Code sovrascrive il blocco successivo e termina il turno. Il conteggio delle continuazioni consecutive si azzera ogni volta che Claude chiama uno strumento. Per aumentare il limite, imposta [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/it/env-vars).
2782 2783
2783Il campo `last_assistant_message` contiene il contenuto testuale della risposta finale di Claude, quindi gli hook possono accedervi senza analizzare il file della trascrizione. Per gli hook che agiscono sul turno appena completato, come gli hook di lettura ad alta voce o di notifica, usa questo campo anziché leggere `transcript_path`: non è garantito che il file della trascrizione includa il messaggio finale al momento di Stop in tutte le versioni.2784Il campo `last_assistant_message` contiene il contenuto testuale della risposta finale di Claude, così gli hook possono accedervi senza analizzare il file della trascrizione. Per gli hook che agiscono sul turno appena completato, come gli hook di lettura ad alta voce o di notifica, usa questo campo anziché leggere `transcript_path`: non è garantito che il file della trascrizione includa il messaggio finale al momento di Stop in tutte le versioni.
2784 2785
2785Gli array `background_tasks` e `session_crons` consentono agli hook di distinguere tra "la sessione è terminata" e "la sessione è in pausa in attesa che un lavoro in background la riattivi". Entrambi gli array sono presenti quando il registro dei task è raggiungibile e sono vuoti quando non c'è nulla in corso o pianificato.2786Gli array `background_tasks` e `session_crons` permettono agli hook di distinguere tra "la sessione è terminata" e "la sessione è in pausa in attesa che un lavoro in background la riattivi". Entrambi gli array sono presenti quando il registro delle attività è raggiungibile e sono vuoti quando non c'è nulla in corso o pianificato.
2786 2787
2787Ogni voce in `background_tasks` descrive un task in corso e usa questi campi:2788Ogni voce in `background_tasks` descrive un'attività in corso e usa questi campi:
2788 2789
2789| Campo | Descrizione |2790| Campo | Descrizione |
2790| :- | :- |2791| :- | :- |
2791| `id` | Identificatore del task |2792| `id` | Identificatore dell'attività |
2792| `type` | Etichetta descrittiva del tipo di task, come `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session` o `MCP task`. Ogni etichetta identifica quale funzionalità di Claude Code ha creato il task. Per i tipi non riconosciuti ricade sul discriminante grezzo |2793| `type` | Etichetta descrittiva del tipo di attività, come `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session` o `MCP task`. Ogni etichetta identifica quale funzionalità di Claude Code ha creato l'attività. Ricade sul discriminante grezzo per i tipi non riconosciuti |
2793| `status` | Stato attuale del task |2794| `status` | Stato attuale dell'attività |
2794| `description` | Descrizione in testo libero, limitata a 1000 caratteri con un indicatore `… [+N chars]` all'interno della stringa quando viene troncata |2795| `description` | Descrizione in testo libero, limitata a 1000 caratteri con un marcatore `… [+N chars]` nella stringa quando viene troncata |
2795| `command` | Riga di comando della shell, limitata a 1000 caratteri. Presente solo per i task `shell` |2796| `command` | Riga di comando della shell, limitata a 1000 caratteri. Presente solo per le attività `shell` |
2796| `agent_type` | Nome del tipo di subagent. Presente solo per i task `subagent` |2797| `agent_type` | Nome del tipo di subagent. Presente solo per le attività `subagent` |
2797| `server` | Nome del server MCP. Presente solo per i task `monitor` e `MCP task` |2798| `server` | Nome del server MCP. Presente solo per le attività `monitor` e `MCP task` |
2798| `tool` | Nome dello strumento MCP. Presente solo per i task `monitor` e `MCP task` |2799| `tool` | Nome dello strumento MCP. Presente solo per le attività `monitor` e `MCP task` |
2799| `name` | Nome del workflow. Presente solo per i task `workflow` |2800| `name` | Nome del workflow. Presente solo per le attività `workflow` |
2800 2801
2801Ogni voce in `session_crons` descrive una riattivazione pianificata con ambito di sessione, proveniente da `CronCreate`, `ScheduleWakeup` e `/loop`:2802Ogni voce in `session_crons` descrive un risveglio pianificato con ambito di sessione, proveniente da `CronCreate`, `ScheduleWakeup` e `/loop`:
2802 2803
2803| Campo | Descrizione |2804| Campo | Descrizione |
2804| :- | :- |2805| :- | :- |
2805| `id` | Identificatore del task cron |2806| `id` | Identificatore dell'attività cron |
2806| `schedule` | Espressione cron, ad esempio `0 9 * * 1-5` |2807| `schedule` | Espressione cron, ad esempio `0 9 * * 1-5` |
2807| `recurring` | `false` per le riattivazioni una tantum la cui pianificazione codifica un unico orario di attivazione, `true` per i task che si riattivano a ogni corrispondenza |2808| `recurring` | `false` per i risvegli singoli la cui pianificazione codifica un unico momento di attivazione, `true` per le attività che si riattivano a ogni corrispondenza |
2808| `prompt` | Prompt inviato quando il cron si attiva, limitato a 1000 caratteri con lo stesso indicatore `… [+N chars]` |2809| `prompt` | Prompt inviato quando il cron si attiva, limitato a 1000 caratteri con lo stesso marcatore `… [+N chars]` |
2809 2810
2810Questo esempio mostra un input di Stop con un task shell in corso e un cron ricorrente:2811Questo esempio mostra un input di Stop con un'attività shell in corso e un cron ricorrente:
2811 2812
2812```json theme={null}2813```json theme={null}
2813{2814{
2842 Controllo delle decisioni di Stop2843 Controllo delle decisioni di Stop
2843</h4>2844</h4>
2844 2845
2845Gli hook `Stop` e `SubagentStop` possono controllare se Claude prosegue. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, lo script del tuo hook può restituire questi campi specifici dell'evento:2846Gli hook `Stop` e `SubagentStop` possono controllare se Claude continua. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, il tuo script di hook può restituire questi campi specifici dell'evento:
2846 2847
2847| Campo | Descrizione |2848| Campo | Descrizione |
2848| :- | :- |2849| :- | :- |
2849| `decision` | `"block"` impedisce a Claude di fermarsi. Omettilo per consentire a Claude di fermarsi |2850| `decision` | `"block"` impedisce a Claude di fermarsi. Omettilo per consentire a Claude di fermarsi |
2850| `reason` | Obbligatorio quando `decision` è `"block"`. Indica a Claude perché deve proseguire |2851| `reason` | Obbligatorio quando `decision` è `"block"`. Indica a Claude perché dovrebbe continuare |
2851| `hookSpecificOutput.additionalContext` | Feedback non di errore per Claude. La conversazione prosegue affinché Claude possa agire di conseguenza, ma a differenza di `decision: "block"` viene mostrato nella trascrizione come feedback dell'hook anziché come errore dell'hook |2852| `hookSpecificOutput.additionalContext` | Feedback non di errore per Claude. La conversazione continua così Claude può agire di conseguenza, ma a differenza di `decision: "block"` viene mostrato nella trascrizione come feedback dell'hook anziché come errore dell'hook |
2852 2853
2853Un hook che blocca uscendo con codice 2 viene instradato allo stesso modo di `reason`: Claude riceve il messaggio stderr come spiegazione del motivo per cui deve proseguire.2854Un hook che blocca uscendo con 2 segue lo stesso percorso di `reason`: Claude riceve il messaggio di stderr come spiegazione del motivo per cui dovrebbe continuare.
2854 2855
2855```json theme={null}2856```json theme={null}
2856{2857{
2859}2860}
2860```2861```
2861 2862
2862Usa `additionalContext` quando l'hook funziona come previsto e fornisce indicazioni a Claude, come "esegui la suite di test prima di terminare". Mantiene attiva la conversazione attraverso le stesse protezioni dai cicli di `decision: "block"`, ovvero l'input `stop_hook_active` e il limite di 8 prosecuzioni consecutive, ma la trascrizione lo etichetta come `Stop hook feedback` e non viene mostrata alcuna notifica di errore dell'hook:2863Usa `additionalContext` quando l'hook funziona come previsto e fornisce indicazioni a Claude, come "esegui la suite di test prima di finire". Mantiene attiva la conversazione tramite le stesse protezioni dai cicli di `decision: "block"`, ovvero l'input `stop_hook_active` e il limite di 8 continuazioni consecutive, ma la trascrizione lo etichetta come `Stop hook feedback` e non viene mostrata alcuna notifica di errore dell'hook:
2863 2864
2864```json theme={null}2865```json theme={null}
2865{2866{
2880 Input di StopFailure2881 Input di StopFailure
2881</h4>2882</h4>
2882 2883
2883Oltre ai [campi di input comuni](#common-input-fields), gli hook StopFailure ricevono `error`, `error_details` facoltativo e `last_assistant_message` facoltativo. Il campo `error` identifica il tipo di errore ed è usato per il filtro del matcher.2884Oltre ai [campi di input comuni](#common-input-fields), gli hook StopFailure ricevono `error`, `error_details` facoltativo e `last_assistant_message` facoltativo. Il campo `error` identifica il tipo di errore e viene usato per il filtraggio del matcher.
2884 2885
2885| Campo | Descrizione |2886| Campo | Descrizione |
2886| :- | :- |2887| :- | :- |
2906 TeammateIdle2907 TeammateIdle
2907</h3>2908</h3>
2908 2909
2909Viene eseguito quando un compagno di un [team di agenti](/docs/it/agent-teams) sta per diventare inattivo dopo aver terminato il proprio turno. Usalo per imporre controlli di qualità prima che un compagno di team smetta di lavorare, ad esempio richiedendo il superamento dei controlli di lint o verificando che i file di output esistano.2910Viene eseguito quando un membro di un [team di agenti](/docs/it/agent-teams) sta per diventare inattivo dopo aver terminato il proprio turno. Usalo per imporre controlli di qualità prima che un membro del team smetta di lavorare, come richiedere il superamento dei controlli lint o verificare che i file di output esistano.
2910 2911
2911Gli hook TeammateIdle non supportano i matcher e si attivano a ogni occorrenza.2912Gli hook TeammateIdle non supportano i matcher e si attivano a ogni occorrenza.
2912 2913
2930 2931
2931| Campo | Descrizione |2932| Campo | Descrizione |
2932| :- | :- |2933| :- | :- |
2933| `teammate_name` | Nome del compagno di team che sta per diventare inattivo |2934| `teammate_name` | Nome del membro del team che sta per diventare inattivo |
2934| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |2935| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |
2936| `agent_id` | In questo evento, il [campo di input comune](#common-input-fields) identifica il [membro del team in-process](/docs/it/agent-teams#choose-a-display-mode) che sta per diventare inattivo. Può essere assente. Richiede Claude Code v2.1.290 o successiva |
2935 2937
2936<h4 id="teammateidle-decision-control">2938<h4 id="teammateidle-decision-control">
2937 Controllo delle decisioni di TeammateIdle2939 Controllo delle decisioni di TeammateIdle
2938</h4>2940</h4>
2939 2941
2940Gli hook TeammateIdle supportano due modi per controllare il comportamento dei compagni di team:2942Gli hook TeammateIdle supportano due modi per controllare il comportamento dei membri del team:
2941 2943
2942* **Codice di uscita 2**: il compagno di team riceve il messaggio stderr come feedback e continua a lavorare invece di diventare inattivo.2944* **Codice di uscita 2**: il membro del team riceve il messaggio di stderr come feedback e continua a lavorare invece di diventare inattivo.
2943* **JSON `{"continue": false, "stopReason": "..."}`**: ferma completamente il compagno di team, in modo analogo al comportamento dell'hook `Stop`. Lo `stopReason` viene mostrato all'utente.2945* **JSON `{"continue": false, "stopReason": "..."}`**: arresta completamente il membro del team, in modo analogo al comportamento dell'hook `Stop`. Lo `stopReason` viene mostrato all'utente.
2944 2946
2945Questo esempio verifica che un artefatto di build esista prima di consentire a un compagno di team di diventare inattivo:2947Questo esempio verifica che un artefatto di build esista prima di consentire a un membro del team di diventare inattivo:
2946 2948
2947```bash theme={null}2949```bash theme={null}
2948#!/bin/bash2950#!/bin/bash
2959 ConfigChange2961 ConfigChange
2960</h3>2962</h3>
2961 2963
2962Viene eseguito quando un file di configurazione cambia durante una sessione. Usalo per verificare le modifiche alle impostazioni, applicare criteri di sicurezza o bloccare modifiche non autorizzate ai file di configurazione.2964Viene eseguito quando un file di configurazione cambia durante una sessione. Usalo per controllare le modifiche alle impostazioni, applicare criteri di sicurezza o bloccare modifiche non autorizzate ai file di configurazione.
2963 2965
2964Claude Code esegue gli hook ConfigChange quando cambia un file di impostazioni, un file di criteri gestiti o un file di skill. Per i criteri gestiti, li esegue solo quando cambia `managed-settings.json` o un file in `managed-settings.d/`. Applica le [impostazioni gestite dal server](/docs/it/server-managed-settings) e le modifiche alle preferenze gestite di macOS o ai criteri del registro di Windows senza eseguirli. Su WSL con [`wslInheritsWindowsSettings`](/docs/it/settings-reference#wslinheritswindowssettings), applica inoltre un file di impostazioni gestite lato Windows modificato durante il suo controllo periodico dei criteri senza eseguirli.2966Claude Code esegue gli hook ConfigChange quando cambia un file di impostazioni, un file di criteri gestiti o un file di skill. Per i criteri gestiti, li esegue solo quando cambia `managed-settings.json` o un file in `managed-settings.d/`. Applica le [impostazioni gestite dal server](/docs/it/server-managed-settings) e le modifiche alle preferenze gestite di macOS o ai criteri del registro di Windows senza eseguirli. Su WSL con [`wslInheritsWindowsSettings`](/docs/it/settings-reference#wslinheritswindowssettings), applica anche un file di impostazioni gestite lato Windows modificato durante il proprio polling dei criteri senza eseguirli.
2965 2967
2966Il matcher filtra in base all'origine della configurazione:2968Il matcher filtra in base all'origine della configurazione:
2967 2969
2973| `policy_settings` | Cambia `managed-settings.json` o un file in `managed-settings.d/` |2975| `policy_settings` | Cambia `managed-settings.json` o un file in `managed-settings.d/` |
2974| `skills` | Cambia un file di skill in `.claude/skills/` |2976| `skills` | Cambia un file di skill in `.claude/skills/` |
2975 2977
2976Questo esempio registra tutte le modifiche alla configurazione per la verifica della sicurezza:2978Questo esempio registra tutte le modifiche alla configurazione per il controllo di sicurezza:
2977 2979
2978```json theme={null}2980```json theme={null}
2979{2981{
2997 Input di ConfigChange2999 Input di ConfigChange
2998</h4>3000</h4>
2999 3001
3000Oltre ai [campi di input comuni](#common-input-fields), gli hook ConfigChange ricevono `source` e, facoltativamente, `file_path`. Il campo `source` indica quale tipo di configurazione è cambiato e `file_path` fornisce il percorso del file specifico che è stato modificato.3002Oltre ai [campi di input comuni](#common-input-fields), gli hook ConfigChange ricevono `source` e, facoltativamente, `file_path`. Il campo `source` indica quale tipo di configurazione è cambiato, e `file_path` fornisce il percorso del file specifico che è stato modificato.
3001 3003
3002```json theme={null}3004```json theme={null}
3003{3005{
3028}3030}
3029```3031```
3030 3032
3031Le modifiche `policy_settings` non possono essere bloccate. Gli hook si attivano comunque per le origini `policy_settings` quando cambia un file di impostazioni gestite sulla macchina, quindi puoi usarli per registrare tali modifiche, ma qualsiasi decisione di blocco viene ignorata. Questo garantisce che le impostazioni gestite dall'azienda abbiano sempre effetto. Claude Code non esegue gli hook `ConfigChange` quando le [impostazioni gestite dal server](/docs/it/server-managed-settings) arrivano o vengono aggiornate.3033Le modifiche `policy_settings` non possono essere bloccate. Gli hook si attivano comunque per le origini `policy_settings` quando cambia un file di impostazioni gestite sulla macchina, quindi puoi usarli per registrare queste modifiche, ma qualsiasi decisione di blocco viene ignorata. Ciò garantisce che le impostazioni gestite dall'azienda abbiano sempre effetto. Claude Code non esegue gli hook `ConfigChange` quando le [impostazioni gestite dal server](/docs/it/server-managed-settings) arrivano o vengono aggiornate.
3032 3034
3033Claude Code agisce sulla decisione di blocco dall'output JSON di un hook ConfigChange e scarta `systemMessage` e `continue`. Una modifica bloccata non mostra alcun messaggio né a te né a Claude, sia che tu blocchi con `reason` sia con stderr con uscita 2. Claude Code scrive solo una riga nel log di debug.3035Claude Code agisce sulla decisione di blocco dall'output JSON di un hook ConfigChange e scarta `systemMessage` e `continue`. Una modifica bloccata non mostra alcun messaggio né a te né a Claude, sia che tu blocchi con `reason` sia con stderr e uscita 2. Claude Code scrive solo una riga nel log di debug.
3034 3036
3035<h3 id="cwdchanged">3037<h3 id="cwdchanged">
3036 CwdChanged3038 CwdChanged
3063 Output di CwdChanged3065 Output di CwdChanged
3064</h4>3066</h4>
3065 3067
3066Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, gli hook CwdChanged possono restituire `watchPaths` per impostare dinamicamente quali percorsi di file [FileChanged](#filechanged) monitora:3068Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, gli hook CwdChanged possono restituire `watchPaths` per impostare dinamicamente quali percorsi di file vengono monitorati da [FileChanged](#filechanged):
3067 3069
3068| Campo | Descrizione |3070| Campo | Descrizione |
3069| :- | :- |3071| :- | :- |
3070| `watchPaths` | Array di percorsi assoluti. Sostituisce l'attuale elenco dinamico di monitoraggio. I percorsi della configurazione del tuo `matcher` sono sempre monitorati. Restituire un array vuoto svuota l'elenco dinamico, cosa tipica quando si entra in una nuova directory |3072| `watchPaths` | Array di percorsi assoluti. Sostituisce l'attuale elenco di monitoraggio dinamico. I percorsi della configurazione del tuo `matcher` vengono sempre monitorati. Restituire un array vuoto cancella l'elenco dinamico, il che è tipico quando si entra in una nuova directory |
3071 3073
3072Gli hook CwdChanged non hanno controllo delle decisioni. Non possono bloccare il cambio di directory.3074Gli hook CwdChanged non hanno controllo delle decisioni. Non possono bloccare il cambio di directory.
3073 3075
3077 DirectoryAdded3079 DirectoryAdded
3078</h3>3080</h3>
3079 3081
3080Viene eseguito dopo che aggiungi una directory di lavoro a sessione in corso con il comando `/add-dir`, o dopo che un client SDK ne aggiunge una con la richiesta di controllo `register_repo_root`. Usalo per preparare un repository appena aggiunto, ad esempio installandone le dipendenze.3082Viene eseguito dopo che aggiungi una directory di lavoro a sessione in corso con il comando `/add-dir`, oppure dopo che un client SDK ne aggiunge una con la richiesta di controllo `register_repo_root`. Usalo per preparare un repository appena aggiunto, ad esempio installandone le dipendenze.
3081 3083
3082Claude Code non attiva questo evento quando:3084Claude Code non attiva questo evento quando:
3083 3085
3084* Passi una directory con il flag di avvio `--add-dir`; [SessionStart](#sessionstart) copre quelle directory3086* Passi una directory con il flag di avvio `--add-dir`; [SessionStart](#sessionstart) copre quelle directory
3085* Aggiungi una directory nella scheda Workspace di `/permissions`3087* Aggiungi una directory nella scheda Workspace di `/permissions`
3086* Aggiungi una directory che è già una directory di lavoro o che si trova all'interno di una3088* Aggiungi una directory che è già una directory di lavoro o si trova al suo interno
3087 3089
3088Claude Code attiva DirectoryAdded dopo aver aggiornato lo stato della sandbox e dei permessi, quindi gli strumenti in sandbox vedono già la nuova directory quando il tuo hook viene eseguito. I comandi degli hook stessi vengono eseguiti fuori dalla sandbox.3090Claude Code attiva DirectoryAdded dopo aver aggiornato lo stato della sandbox e dei permessi, quindi gli strumenti in sandbox vedono già la nuova directory quando il tuo hook viene eseguito. I comandi degli hook stessi vengono eseguiti senza sandbox.
3089 3091
3090Claude Code non attende l'hook: l'aggiunta viene completata immediatamente e l'hook viene eseguito in background con il timeout predefinito di 600 secondi.3092Claude Code non attende l'hook: l'aggiunta viene completata immediatamente e l'hook viene eseguito in background con il timeout predefinito di 600 secondi.
3091 3093
3104 3106
3105| Campo | Descrizione |3107| Campo | Descrizione |
3106| :- | :- |3108| :- | :- |
3107| `directory` | Percorso assoluto della directory aggiunta |3109| `directory` | Percorso assoluto della directory che è stata aggiunta |
3108| `source` | Come è stata aggiunta la directory, `"slash_command"` per `/add-dir` o `"register_repo_root"` per la richiesta di controllo dell'SDK |3110| `source` | Come è stata aggiunta la directory, `"slash_command"` per `/add-dir` o `"register_repo_root"` per la richiesta di controllo dell'SDK |
3109 3111
3110```json theme={null}3112```json theme={null}
3120 3122
3121Gli hook DirectoryAdded non hanno controllo delle decisioni. Non possono bloccare l'aggiunta, che è già stata completata quando l'hook viene eseguito. Claude Code scarta il campo `continue` dal loro output JSON e gestisce il resto in modo diverso in base all'origine:3123Gli hook DirectoryAdded non hanno controllo delle decisioni. Non possono bloccare l'aggiunta, che è già stata completata quando l'hook viene eseguito. Claude Code scarta il campo `continue` dal loro output JSON e gestisce il resto in modo diverso in base all'origine:
3122 3124
3123* `slash_command`: Claude Code consegna il `systemMessage` dell'hook a Claude come contesto nel turno successivo della conversazione, anziché mostrarlo a te. Nella trascrizione appare un conteggio degli hook falliti. L'output completo dei fallimenti va nel log di debug3125* `slash_command`: Claude Code consegna il `systemMessage` dell'hook a Claude come contesto al turno successivo della conversazione, anziché mostrarlo a te. Nella trascrizione appare il conteggio degli hook falliti. L'output completo degli errori va nel log di debug
3124* `register_repo_root`: Claude Code scrive l'output di `systemMessage` e l'output dei fallimenti solo nel log di debug3126* `register_repo_root`: Claude Code scrive l'output di `systemMessage` e l'output degli errori solo nel log di debug
3125 3127
3126<h3 id="filechanged">3128<h3 id="filechanged">
3127 FileChanged3129 FileChanged
3129 3131
3130Viene eseguito quando un file monitorato cambia su disco. Claude Code rileva le modifiche con un watcher del filesystem, non ispezionando le chiamate agli strumenti, quindi esegue l'hook indipendentemente da cosa abbia modificato il file: una chiamata allo strumento `Edit` o `Write`, uno script che Claude esegue con `Bash` o un processo completamente esterno a Claude Code. Un uso comune è ricaricare le variabili d'ambiente quando cambiano i file di configurazione del progetto.3132Viene eseguito quando un file monitorato cambia su disco. Claude Code rileva le modifiche con un watcher del filesystem, non ispezionando le chiamate agli strumenti, quindi esegue l'hook indipendentemente da cosa abbia modificato il file: una chiamata allo strumento `Edit` o `Write`, uno script che Claude esegue con `Bash` o un processo completamente esterno a Claude Code. Un uso comune è ricaricare le variabili d'ambiente quando cambiano i file di configurazione del progetto.
3131 3133
3132Il `matcher` per questo evento svolge due ruoli:3134Il `matcher` per questo evento ha due ruoli:
3133 3135
3134* **Costruire l'elenco di monitoraggio**: il valore viene suddiviso su `|` e ogni segmento viene registrato come nome di file letterale nella directory di lavoro, quindi `".envrc|.env"` monitora esattamente quei due file. I pattern regex non sono utili qui: un valore come `^\.env` monitorerebbe un file chiamato letteralmente `^\.env`.3136* **Costruire l'elenco di monitoraggio**: il valore viene suddiviso su `|` e ogni segmento viene registrato come nome di file letterale nella directory di lavoro, quindi `".envrc|.env"` monitora esattamente quei due file. I pattern regex non sono utili qui: un valore come `^\.env` monitorerebbe un file chiamato letteralmente `^\.env`.
3135* **Filtrare quali hook vengono eseguiti**: quando un file monitorato cambia, lo stesso valore filtra quali gruppi di hook vengono eseguiti usando le [regole standard dei matcher](#matcher-patterns) sul nome base del file modificato.3137* **Filtrare quali hook vengono eseguiti**: quando un file monitorato cambia, lo stesso valore filtra quali gruppi di hook vengono eseguiti usando le [regole standard dei matcher](#matcher-patterns) sul nome base del file modificato.
3136 3138
3137Questo esempio normalizza i caratteri di fine riga in `data.csv` dopo qualsiasi modifica, inclusa la riscrittura del file da parte di un comando `Bash` o di uno script esterno:3139Questo esempio normalizza i fine riga in `data.csv` dopo qualsiasi modifica, inclusa la riscrittura del file da parte di un comando `Bash` o di uno script esterno:
3138 3140
3139```json theme={null}3141```json theme={null}
3140{3142{
3154}3156}
3155```3157```
3156 3158
3157L'hook legge il percorso assoluto del file modificato dal campo `file_path` dell'[input JSON](#filechanged-input) su stdin. Il suo controllo `grep` verifica la stessa cosa che `perl` rimuove, un CR alla fine di una riga, quindi l'esecuzione successiva a una normalizzazione termina senza toccare il file. Un controllo meno rigoroso genera un ciclo infinito, perché `perl -i` riscrive il file anche quando non sostituisce nulla e Claude Code esegue di nuovo l'hook dopo ogni riscrittura. Salva questo script in `/path/to/normalize-line-endings.sh` e rendilo eseguibile:3159L'hook legge il percorso assoluto del file modificato dal campo `file_path` dell'[input JSON](#filechanged-input) su stdin. Il suo controllo con `grep` verifica la stessa cosa che `perl` rimuove, un CR alla fine di una riga, quindi l'esecuzione successiva a una normalizzazione termina senza toccare il file. Un controllo meno rigoroso entra in un ciclo infinito, perché `perl -i` riscrive il file anche quando non sostituisce nulla e Claude Code esegue di nuovo l'hook dopo ogni riscrittura. Salva questo script in `/path/to/normalize-line-endings.sh` e rendilo eseguibile:
3158 3160
3159```bash theme={null}3161```bash theme={null}
3160#!/bin/bash3162#!/bin/bash
3164fi3166fi
3165```3167```
3166 3168
3167Per verificare che l'hook funzioni, chiedi a Claude di aggiungere una riga CRLF a `data.csv` con un comando `Bash`. Claude Code esegue l'hook e il file termina con fine riga LF.3169Per verificare che l'hook funzioni, chiedi a Claude di aggiungere una riga CRLF a `data.csv` con un comando `Bash`. Claude Code esegue l'hook e il file finisce con fine riga LF.
3168 3170
3169Per monitorare file che non puoi nominare in anticipo, restituisci [`watchPaths`](#filechanged-output) da un hook per aggiornare dinamicamente l'elenco di monitoraggio. Claude Code avvia il watcher solo quando qualcosa nomina un file da monitorare, quindi inizializza l'elenco con un gruppo FileChanged il cui matcher nomina almeno un file, oppure con un hook [SessionStart](#sessionstart-decision-control) o [CwdChanged](#cwdchanged) che restituisce `watchPaths`. Il matcher filtra comunque quali gruppi di hook vengono eseguiti quando un file monitorato cambia, quindi assegna al gruppo che gestisce i percorsi dinamici un matcher omesso, che corrisponde a ogni file monitorato e non aggiunge nulla all'elenco di monitoraggio. Anche un matcher `"*"` corrisponde a ogni file, ma Claude Code lo registra nell'elenco di monitoraggio come qualsiasi altro valore, ovvero come un file chiamato letteralmente `*`.3171Per monitorare file che non puoi nominare in anticipo, restituisci [`watchPaths`](#filechanged-output) da un hook per aggiornare dinamicamente l'elenco di monitoraggio. Claude Code avvia il watcher solo quando qualcosa nomina un file da monitorare, quindi inizializza l'elenco con un gruppo FileChanged il cui matcher nomina almeno un file, oppure con un hook [SessionStart](#sessionstart-decision-control) o [CwdChanged](#cwdchanged) che restituisce `watchPaths`. Il matcher filtra comunque quali gruppi di hook vengono eseguiti quando un file monitorato cambia, quindi assegna al gruppo che gestisce i percorsi dinamici un matcher omesso, che corrisponde a ogni file monitorato e non aggiunge nulla all'elenco di monitoraggio. Anche un matcher `"*"` corrisponde a ogni file, ma Claude Code lo registra nell'elenco di monitoraggio come qualsiasi altro valore, come un file letterale chiamato `*`.
3170 3172
3171Gli hook FileChanged hanno accesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Le variabili scritte in quel file persistono nei comandi Bash successivi fino al successivo evento [CwdChanged](#cwdchanged), quando Claude Code le cancella.3173Gli hook FileChanged hanno accesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Le variabili scritte in quel file persistono nei comandi Bash successivi fino al successivo evento [CwdChanged](#cwdchanged), quando Claude Code le cancella.
3172 3174
3178 3180
3179| Campo | Descrizione |3181| Campo | Descrizione |
3180| :- | :- |3182| :- | :- |
3181| `file_path` | Percorso assoluto del file modificato |3183| `file_path` | Percorso assoluto del file che è cambiato |
3182| `event` | Cosa è successo: `"change"` per un file modificato, `"add"` per un file creato o `"unlink"` per un file eliminato |3184| `event` | Cosa è successo: `"change"` per un file modificato, `"add"` per un file creato o `"unlink"` per un file eliminato |
3183 3185
3184```json theme={null}3186```json theme={null}
3200 3202
3201| Campo | Descrizione |3203| Campo | Descrizione |
3202| :- | :- |3204| :- | :- |
3203| `watchPaths` | Array di percorsi assoluti. Sostituisce l'attuale elenco dinamico di monitoraggio. I percorsi della configurazione del tuo `matcher` sono sempre monitorati. Usalo quando lo script del tuo hook individua file aggiuntivi da monitorare in base al file modificato |3205| `watchPaths` | Array di percorsi assoluti. Sostituisce l'attuale elenco di monitoraggio dinamico. I percorsi della configurazione del tuo `matcher` vengono sempre monitorati. Usalo quando il tuo script di hook scopre file aggiuntivi da monitorare in base al file modificato |
3204 3206
3205Gli hook FileChanged non hanno controllo delle decisioni. Non possono impedire che la modifica del file avvenga.3207Gli hook FileChanged non hanno controllo delle decisioni. Non possono impedire che la modifica del file avvenga.
3206 3208
3210 WorktreeCreate3212 WorktreeCreate
3211</h3>3213</h3>
3212 3214
3213Viene eseguito quando viene creato un worktree, che sia da `claude --worktree`, da un [subagent che usa `isolation: "worktree"`](/docs/it/sub-agents#choose-the-subagent-scope) o per una [sessione in background](/docs/it/agent-view#how-file-edits-are-isolated) che Claude Code isola nel proprio worktree. Per impostazione predefinita, Claude Code crea la copia di lavoro isolata con `git worktree`. Configurare un hook WorktreeCreate sostituisce quel comportamento git predefinito, consentendoti di usare un diverso sistema di controllo di versione come SVN, Perforce o Mercurial.3215Viene eseguito quando viene creato un worktree, sia da `claude --worktree`, sia da un [subagent che usa `isolation: "worktree"`](/docs/it/sub-agents#choose-the-subagent-scope), sia per una [sessione in background](/docs/it/agent-view#how-file-edits-are-isolated) che Claude Code isola nel proprio worktree. Per impostazione predefinita Claude Code crea la copia di lavoro isolata con `git worktree`. Configurare un hook WorktreeCreate sostituisce questo comportamento git predefinito, permettendoti di usare un sistema di controllo versione diverso come SVN, Perforce o Mercurial.
3214 3216
3215Poiché l'hook sostituisce interamente il comportamento predefinito, [`.worktreeinclude`](/docs/it/worktrees#copy-gitignored-files-into-worktrees) non viene elaborato. Se devi copiare file di configurazione locali come `.env` nel nuovo worktree, fallo all'interno dello script del tuo hook.3217Poiché l'hook sostituisce interamente il comportamento predefinito, [`.worktreeinclude`](/docs/it/worktrees#copy-gitignored-files-into-worktrees) non viene elaborato. Se devi copiare file di configurazione locali come `.env` nel nuovo worktree, fallo all'interno del tuo script hook.
3216 3218
3217L'hook deve restituire il percorso della directory del worktree creato. Claude Code usa questo percorso come directory di lavoro per la sessione isolata. Consulta [Output di WorktreeCreate](#worktreecreate-output) per come ciascun tipo di hook restituisce il percorso.3219L'hook deve restituire il percorso della directory del worktree creato. Claude Code usa questo percorso come directory di lavoro per la sessione isolata. Consulta [Output di WorktreeCreate](#worktreecreate-output) per sapere come ciascun tipo di hook restituisce il percorso.
3218 3220
3219Claude Code agisce sull'esito positivo dell'hook e sul percorso restituito, e scarta `systemMessage` e `continue`.3221Claude Code agisce in base al successo dell'hook e al percorso restituito, e scarta `systemMessage` e `continue`.
3220 3222
3221Questo esempio crea una copia di lavoro SVN e stampa il percorso che Claude Code deve usare. Sostituisci l'URL del repository con il tuo:3223Questo esempio crea una copia di lavoro SVN e stampa il percorso che Claude Code dovrà usare. Sostituisci l'URL del repository con il tuo:
3222 3224
3223```json theme={null}3225```json theme={null}
3224{3226{
3237}3239}
3238```3240```
3239 3241
3240L'hook legge il `name` del worktree dall'input JSON su stdin, effettua il checkout di una copia nuova in una nuova directory e stampa il percorso della directory. L'`echo` sull'ultima riga è ciò che Claude Code legge come percorso del worktree. Reindirizza qualsiasi altro output su stderr in modo che non interferisca con il percorso.3242L'hook legge il `name` del worktree dall'input JSON su stdin, esegue il checkout di una copia nuova in una nuova directory e stampa il percorso della directory. L'`echo` sull'ultima riga è ciò che Claude Code legge come percorso del worktree. Reindirizza qualsiasi altro output su stderr in modo che non interferisca con il percorso.
3241 3243
3242<h4 id="worktreecreate-input">3244<h4 id="worktreecreate-input">
3243 Input di WorktreeCreate3245 Input di WorktreeCreate
3259 Output di WorktreeCreate3261 Output di WorktreeCreate
3260</h4>3262</h4>
3261 3263
3262Gli hook WorktreeCreate non usano il modello decisionale standard di consenso/blocco. L'esito è invece determinato dal successo o dal fallimento dell'hook. L'hook deve restituire il percorso della directory del worktree creato:3264Gli hook WorktreeCreate non usano il modello decisionale standard allow/block. Al contrario, è il successo o il fallimento dell'hook a determinare l'esito. L'hook deve restituire il percorso della directory del worktree creato:
3263 3265
3264* **Hook di comando** (`type: "command"`): stampa il percorso come ultima riga non vuota di stdout. Claude Code rimuove i codici di escape ANSI prima di leggere quella riga, quindi i banner di avvio della shell stampati prima del tuo `echo` vengono ignorati. Reindirizza qualsiasi altro output dell'hook su stderr.3266* **Hook di comando** (`type: "command"`): stampa il percorso come ultima riga non vuota di stdout. Claude Code rimuove i codici di escape ANSI prima di leggere quella riga, quindi i banner di avvio della shell stampati prima del tuo `echo` vengono ignorati. Reindirizza qualsiasi altro output dell'hook su stderr.
3265* **Hook HTTP** (`type: "http"`): restituisci `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` nel corpo della risposta.3267* **Hook HTTP** (`type: "http"`): restituisci `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` nel corpo della risposta.
3266 3268
3267Se l'hook fallisce o non produce alcun percorso, la creazione del worktree fallisce con un errore.3269Se l'hook fallisce o non produce alcun percorso, la creazione del worktree fallisce con un errore.
3268 3270
3269Claude Code risolve un percorso relativo rispetto alla directory in cui è stato eseguito l'hook, comprimendo eventuali segmenti `.` o `..` al suo interno. Se il percorso risultante non è una directory in cui Claude Code può entrare, la sessione stampa un errore che indica il percorso ed esce con codice 1.3271Claude Code risolve un percorso relativo rispetto alla directory in cui è stato eseguito l'hook, riducendo gli eventuali segmenti `.` o `..` al suo interno. Se il percorso risultante non è una directory in cui Claude Code può entrare, la sessione stampa un errore che indica il percorso ed esce con codice 1.
3270 3272
3271Claude Code rifiuta un percorso assoluto che contiene segmenti `.` o `..`, e qualsiasi percorso che attraversa un collegamento simbolico sotto la radice del repository, perché un collegamento simbolico sottoposto a commit nel repository potrebbe reindirizzare il worktree al di fuori di esso. L'errore indica il componente rifiutato. Restituisci un percorso normalizzato che non attraversi un collegamento simbolico all'interno del repository. Prima della v2.1.216, la creazione del worktree seguiva il percorso dell'hook senza questo controllo.3273Claude Code rifiuta un percorso assoluto che contiene segmenti `.` o `..`, e qualsiasi percorso che passa attraverso un collegamento simbolico sotto la radice del repository, perché un collegamento simbolico sottoposto a commit nel repository potrebbe reindirizzare il worktree al di fuori di esso. L'errore indica il componente rifiutato. Restituisci un percorso normalizzato che non passi attraverso un collegamento simbolico all'interno del repository. Prima della v2.1.216, la creazione del worktree seguiva il percorso dell'hook senza questo controllo.
3272 3274
3273<h3 id="worktreeremove">3275<h3 id="worktreeremove">
3274 WorktreeRemove3276 WorktreeRemove
3280* Esci da una sessione worktree interattiva a cui non hai [dato un nome](/docs/it/sessions#name-your-sessions), Claude Code non trova file modificati o non tracciati e rimuove il worktree senza chiedertelo3282* Esci da una sessione worktree interattiva a cui non hai [dato un nome](/docs/it/sessions#name-your-sessions), Claude Code non trova file modificati o non tracciati e rimuove il worktree senza chiedertelo
3281* Elimini una [sessione in background](/docs/it/agent-view#what-deleting-a-session-removes) che viene eseguita nel worktree3283* Elimini una [sessione in background](/docs/it/agent-view#what-deleting-a-session-removes) che viene eseguita nel worktree
3282 3284
3283Claude Code usa git per cercare file modificati o non tracciati, quindi non ne trova nessuno in un worktree che non è un checkout git né si trova all'interno di uno, anche quando la directory contiene lavoro non sottoposto a commit. Verifica la presenza di tale lavoro nel tuo hook WorktreeRemove prima che elimini qualsiasi cosa.3285Claude Code usa git per cercare file modificati o non tracciati, quindi non ne trova nessuno in un worktree che non è un checkout git né si trova all'interno di uno, anche quando la directory contiene lavoro non sottoposto a commit. Controlla la presenza di tale lavoro nel tuo hook WorktreeRemove prima che elimini qualsiasi cosa.
3284 3286
3285Per i worktree basati su git, Claude Code gestisce la pulizia automaticamente con `git worktree remove`. Se hai configurato un hook WorktreeCreate, abbinalo a un hook WorktreeRemove per controllare la pulizia dei worktree che crea:3287Per i worktree basati su git, Claude Code gestisce la pulizia automaticamente con `git worktree remove`. Se hai configurato un hook WorktreeCreate, abbinalo a un hook WorktreeRemove per controllare la pulizia dei worktree che crea:
3286 3288
3287* **Nessun hook WorktreeRemove**: quando Claude Code rimuove il worktree mentre esci da una sessione worktree, ripiega su `git worktree remove --force` sul percorso restituito dal tuo hook WorktreeCreate, quindi un worktree riconosciuto da git viene rimosso. Un worktree non riconosciuto da git, ad esempio uno creato dal tuo hook con un sistema di controllo versione diverso da git, rimane su disco. Per sapere cosa comporta l'eliminazione di una [sessione in background](/docs/it/agent-view#what-deleting-a-session-removes) per un worktree creato da un hook, consulta le regole di eliminazione della vista agente.3289* **Nessun hook WorktreeRemove**: quando Claude Code rimuove il worktree mentre esci da una sessione worktree, ripiega su `git worktree remove --force` sul percorso restituito dal tuo hook WorktreeCreate, quindi un worktree riconosciuto da git viene rimosso. Un worktree che git non riconosce, ad esempio uno creato dal tuo hook con un sistema di controllo versione non git, rimane su disco. Per sapere cosa comporta l'eliminazione di una [sessione in background](/docs/it/agent-view#what-deleting-a-session-removes) per un worktree creato da un hook, consulta le regole di eliminazione della vista agente.
3288* **L'hook esce con 0**: il worktree viene considerato rimosso. Claude Code non legge nient'altro dall'hook, quindi assicurati che il tuo hook abbia eliminato la directory.3290* **L'hook esce con 0**: il worktree viene considerato rimosso. Claude Code non legge nient'altro dall'hook, quindi assicurati che il tuo hook abbia eliminato la directory.
3289* **L'hook esce con un valore diverso da zero**: la rimozione fallisce se la directory in `worktree_path` esiste ancora in seguito, e il worktree rimane su disco senza fallback su git. Un hook che ha eliminato la directory prima di uscire con un valore diverso da zero viene considerato come rimozione riuscita. Per sapere come viene segnalato l'errore, consulta [Input di WorktreeRemove](#worktreeremove-input).3291* **L'hook esce con un codice diverso da zero**: la rimozione fallisce se la directory in `worktree_path` esiste ancora in seguito, e il worktree rimane su disco senza fallback git. Un hook che ha eliminato la directory prima di uscire con un codice diverso da zero viene considerato come rimosso. Per sapere come viene segnalato il fallimento, consulta [Input di WorktreeRemove](#worktreeremove-input).
3290 3292
3291Claude Code non elimina mai un branch appartenente a un worktree creato da un hook, perché conosce solo il percorso restituito dal tuo hook WorktreeCreate. Se il tuo hook WorktreeCreate crea un branch, eliminalo nel tuo hook WorktreeRemove.3293Claude Code non elimina mai un branch appartenente a un worktree creato da un hook, perché conosce solo il percorso restituito dal tuo hook WorktreeCreate. Se il tuo hook WorktreeCreate crea un branch, eliminalo nel tuo hook WorktreeRemove.
3292 3294
3293Claude Code scarta i [campi di output JSON](#json-output) di un hook WorktreeRemove, come `systemMessage` e `continue`.3295Claude Code scarta i [campi di output JSON](#json-output) di un hook WorktreeRemove, come `systemMessage` e `continue`.
3294 3296
3295Per l'eliminazione di una sessione in background, Claude Code verifica il percorso del worktree memorizzato prima di eseguire l'hook e rifiuta un percorso che sia un collegamento simbolico o che ne attraversi uno sotto la radice del repository. L'hook viene eseguito per un worktree che contiene ancora file solo quando confermi l'eliminazione nella [vista agenti](/docs/it/agent-view#what-deleting-a-session-removes); per un worktree di questo tipo, [`claude rm`](/docs/it/agent-view#manage-sessions-from-the-shell) mantiene invece la sessione e il worktree. Prima della v2.1.216, l'hook veniva eseguito sul percorso memorizzato senza questi controlli.3297Per l'eliminazione di una sessione in background, Claude Code verifica il percorso del worktree memorizzato prima di eseguire l'hook e rifiuta un percorso che è un collegamento simbolico o che ne attraversa uno sotto la radice del repository. L'hook viene eseguito per un worktree che contiene ancora file solo quando confermi l'eliminazione nella [vista agente](/docs/it/agent-view#what-deleting-a-session-removes); per un worktree di questo tipo, [`claude rm`](/docs/it/agent-view#manage-sessions-from-the-shell) mantiene invece la sessione e il worktree. Prima della v2.1.216, l'hook veniva eseguito sul percorso memorizzato senza questi controlli.
3296 3298
3297Claude Code passa il percorso restituito da WorktreeCreate come `worktree_path` nell'input dell'hook. Questo esempio legge quel percorso e rimuove la directory:3299Claude Code passa il percorso restituito da WorktreeCreate come `worktree_path` nell'input dell'hook. Questo esempio legge quel percorso e rimuove la directory:
3298 3300
3317 Input di WorktreeRemove3319 Input di WorktreeRemove
3318</h4>3320</h4>
3319 3321
3320Oltre ai [campi di input comuni](#common-input-fields), gli hook WorktreeRemove ricevono il campo `worktree_path`, che è il percorso assoluto del worktree in fase di rimozione.3322Oltre ai [campi di input comuni](#common-input-fields), gli hook WorktreeRemove ricevono il campo `worktree_path`, che è il percorso assoluto del worktree da rimuovere.
3321 3323
3322```json theme={null}3324```json theme={null}
3323{3325{
3329}3331}
3330```3332```
3331 3333
3332Il codice di uscita di un hook WorktreeRemove determina l'esito. Quando un hook esce con un valore diverso da zero e la directory in `worktree_path` esiste ancora in seguito, la rimozione fallisce:3334Il codice di uscita di un hook WorktreeRemove decide l'esito. Quando un hook esce con un codice diverso da zero e la directory in `worktree_path` esiste ancora in seguito, la rimozione fallisce:
3333 3335
3334* Il worktree rimane su disco, e il comando e lo stderr dell'hook vanno nel [log di debug](#debug-hooks).3336* Il worktree rimane su disco, e il comando e lo stderr dell'hook finiscono nel [log di debug](#debug-hooks).
3335* Se stavi eliminando una sessione in background, anche la sessione rimane. Il messaggio di rifiuto nella [vista agenti](/docs/it/agent-view#what-deleting-a-session-removes) riporta come è terminato l'hook, ad esempio `exited 1`, cita l'inizio del suo stderr e indica se eliminare di nuovo la sessione rimuove comunque la directory.3337* Se stavi eliminando una sessione in background, anche la sessione rimane. Il messaggio di rifiuto nella [vista agente](/docs/it/agent-view#what-deleting-a-session-removes) riporta come è terminato l'hook, ad esempio `exited 1`, cita l'inizio del suo stderr e indica se eliminare di nuovo la sessione rimuove comunque la directory.
3336 3338
3337<h3 id="precompact">3339<h3 id="precompact">
3338 PreCompact3340 PreCompact
3374 PostCompact3376 PostCompact
3375</h3>3377</h3>
3376 3378
3377Viene eseguito dopo che Claude Code completa un'operazione di compattazione. Usa questo evento per reagire al nuovo stato compattato, ad esempio per registrare il riepilogo generato o aggiornare uno stato esterno. Claude Code scarta i campi `systemMessage` e `continue` di un hook PostCompact.3379Viene eseguito dopo che Claude Code ha completato un'operazione di compattazione. Usa questo evento per reagire al nuovo stato compattato, ad esempio per registrare il riepilogo generato o aggiornare uno stato esterno. Claude Code scarta i campi `systemMessage` e `continue` di un hook PostCompact.
3378 3380
3379Si applicano gli stessi valori del matcher di `PreCompact`:3381Si applicano gli stessi valori del matcher di `PreCompact`:
3380 3382
3400}3402}
3401```3403```
3402 3404
3403Gli hook PostCompact non hanno controllo decisionale. Non possono influenzare il risultato della compattazione ma possono eseguire attività successive.3405Gli hook PostCompact non hanno controllo decisionale. Non possono influire sul risultato della compattazione, ma possono eseguire attività successive.
3404 3406
3405<h3 id="premodelswitch">3407<h3 id="premodelswitch">
3406 PreModelSwitch3408 PreModelSwitch
3408 3410
3409Viene eseguito prima che Claude Code applichi un cambio di modello richiesto da te o da un client. Usalo per bloccare un cambio, richiedere una conferma o mostrare quanto costerà il cambio prima che avvenga.3411Viene eseguito prima che Claude Code applichi un cambio di modello richiesto da te o da un client. Usalo per bloccare un cambio, richiedere una conferma o mostrare quanto costerà il cambio prima che avvenga.
3410 3412
3411PreModelSwitch richiede Claude Code v2.1.251 o successivo. Claude Code lo esegue per queste richieste:3413PreModelSwitch richiede Claude Code v2.1.251 o successiva. Claude Code lo esegue per queste richieste:
3412 3414
3413* `/model <name>` e il selettore di `/model`3415* `/model <name>` e il selettore di `/model`
3414* Il selettore di modello `Option+P` o `Alt+P`3416* Il selettore di modello `Option+P` o `Alt+P`
3416* L'attivazione della [modalità veloce](/docs/it/fast-mode) quando questa cambia il modello della sessione3418* L'attivazione della [modalità veloce](/docs/it/fast-mode) quando questa cambia il modello della sessione
3417* Una richiesta `set_model`, o un cambio di modello in una richiesta `apply_flag_settings`, da un host dell'[Agent SDK](/docs/it/agent-sdk/typescript#query-object) o da [Remote Control](/docs/it/remote-control)3419* Una richiesta `set_model`, o un cambio di modello in una richiesta `apply_flag_settings`, da un host dell'[Agent SDK](/docs/it/agent-sdk/typescript#query-object) o da [Remote Control](/docs/it/remote-control)
3418 3420
3419Claude Code non esegue gli hook PreModelSwitch per i cambi che effettua autonomamente, come un [fallback automatico del modello](/docs/it/model-config#automatic-model-fallback) o il ripristino del modello quando riprendi una sessione. Questi cambi raggiungono solo [PostModelSwitch](#postmodelswitch).3421Claude Code non esegue gli hook PreModelSwitch per i cambi che effettua autonomamente, come un [fallback automatico del modello](/docs/it/model-config#automatic-model-fallback) o il ripristino del modello quando riprendi una sessione. Queste modifiche raggiungono solo [PostModelSwitch](#postmodelswitch).
3420 3422
3421Claude Code confronta il matcher con il nome canonico del modello verso cui la sessione sta passando, ignorando qualsiasi suffisso `[1m]`. Un alias come `opus`, un ID di modello con data e un ID specifico del provider, come un ID di modello di Amazon Bedrock, corrispondono tutti all'unico nome canonico a cui si risolvono, quindi `claude-opus-5` copre ogni variante di scrittura di Opus 5.3423Claude Code confronta il matcher con il nome canonico del modello a cui la sessione sta passando, ignorando un eventuale suffisso `[1m]`. Un alias come `opus`, un ID di modello con data e un ID specifico del provider come un ID di modello Amazon Bedrock corrispondono tutti all'unico nome canonico in cui si risolvono, quindi `claude-opus-5` copre ogni grafia di Opus 5.
3422 3424
3423Quando Claude Code non riesce a determinare un nome canonico per la destinazione, ad esempio un ID di modello personalizzato noto solo al tuo [gateway LLM](/docs/it/llm-gateway), esegue ogni hook PreModelSwitch indipendentemente dal matcher. Un hook che blocca dovrebbe quindi controllare `to_model` dal suo input anziché affidarsi al solo matcher.3425Quando Claude Code non riesce a determinare un nome canonico per la destinazione, ad esempio un ID di modello personalizzato noto solo al tuo [gateway LLM](/docs/it/llm-gateway), esegue ogni hook PreModelSwitch indipendentemente dal matcher. Un hook che blocca dovrebbe quindi controllare `to_model` dal proprio input anziché affidarsi solo al matcher.
3424 3426
3425Scrivi il matcher come nome esatto, come elenco separato da `|` come `claude-opus-4-6|claude-opus-5`, o come espressione regolare come `.*opus.*`. Questo esempio usa un matcher con nome esatto e controlla anche `to_model` dall'input dell'hook, quindi rifiuta un passaggio a Opus 4.6 uscendo con codice 2 e lascia passare qualsiasi altra destinazione:3427Scrivi il matcher come nome esatto, come elenco separato da `|` come `claude-opus-4-6|claude-opus-5`, o come espressione regolare come `.*opus.*`. Questo esempio usa un matcher con nome esatto e controlla anche `to_model` dall'input dell'hook, quindi rifiuta un cambio a Opus 4.6 uscendo con codice 2 e lascia passare qualsiasi altra destinazione:
3426 3428
3427<Tabs>3429<Tabs>
3428 <Tab title="macOS/Linux">3430 <Tab title="macOS/Linux">
3494 Input di PreModelSwitch3496 Input di PreModelSwitch
3495</h4>3497</h4>
3496 3498
3497Oltre ai [campi di input comuni](#common-input-fields), gli hook PreModelSwitch ricevono i campi di questa tabella. Gli ultimi cinque descrivono quanto costa reinviare la conversazione al nuovo modello, così un hook può mostrare quella cifra prima che avvenga il cambio.3499Oltre ai [campi di input comuni](#common-input-fields), gli hook PreModelSwitch ricevono i campi in questa tabella. Gli ultimi cinque descrivono quanto costa reinviare la conversazione al nuovo modello, così un hook può mostrare quella cifra prima che il cambio avvenga.
3498 3500
3499| Campo | Tipo | Descrizione |3501| Campo | Tipo | Descrizione |
3500| :- | :- | :- |3502| :- | :- | :- |
3501| `from_model` | string | ID del modello da cui avviene il cambio |3503| `from_model` | string | ID del modello da cui parte il cambio |
3502| `to_model` | string | ID del modello verso cui avviene il cambio. Il matcher viene confrontato con il nome canonico di questo modello |3504| `to_model` | string | ID del modello a cui porta il cambio. Il matcher viene confrontato con il nome canonico di questo modello |
3503| `requested_model` | string o `null` | Il modello indicato nella richiesta: un alias come `opus`, un ID di modello completo, oppure `null` quando la richiesta riguardava il modello predefinito |3505| `requested_model` | string o `null` | Il modello indicato dalla richiesta: un alias come `opus`, un ID di modello completo, oppure `null` quando la richiesta era per il modello predefinito |
3504| `source` | string | Da dove proviene la richiesta: `"command"` per `/model <name>`, l'impostazione Model in `/config` o l'attivazione della modalità veloce; `"picker"` per un selettore di modello; `"sdk"` per una richiesta `set_model`, o un cambio di modello in una richiesta `apply_flag_settings`, da un host dell'Agent SDK o da Remote Control |3506| `source` | string | Da dove proviene la richiesta: `"command"` per `/model <name>`, l'impostazione Model in `/config` o l'attivazione della modalità veloce; `"picker"` per un selettore di modello; `"sdk"` per una richiesta `set_model`, o un cambio di modello in una richiesta `apply_flag_settings`, da un host dell'Agent SDK o da Remote Control |
3505| `context_tokens` | number | Token che la richiesta successiva reinvia come prompt: i token di input, di lettura dalla cache, di creazione della cache e di output dell'ultima risposta nella conversazione principale, sommati. `0` prima della prima risposta |3507| `context_tokens` | number | Token che la richiesta successiva reinvia come prompt: i token di input, lettura dalla cache, creazione della cache e output dell'ultima risposta nella conversazione principale, combinati. `0` prima della prima risposta |
3506| `prompt_cache_warm` | boolean | Se la cache del prompt del modello corrente è probabilmente ancora attiva, il che significa che il cambio la fa perdere |3508| `prompt_cache_warm` | boolean | Indica se la cache del prompt del modello corrente è probabilmente ancora calda, il che significa che il cambio la perde |
3507| `cache_ttl` | string | [Durata della cache del prompt](/docs/it/prompt-caching#cache-lifetime) che Claude Code richiede per questa sessione: `"5m"` o `"1h"` |3509| `cache_ttl` | string | [Durata della cache del prompt](/docs/it/prompt-caching#cache-lifetime) che Claude Code richiede per questa sessione: `"5m"` o `"1h"` |
3508| `estimated_cache_write_usd` | number | Costo stimato in dollari USA della scrittura di `context_tokens` nella cache del prompt su `to_model` alla tariffa di `cache_ttl`, esclusa la risposta successiva. Il server potrebbe non dover rimemorizzare nella cache l'intero contesto, quindi consideralo una stima |3510| `estimated_cache_write_usd` | number | Costo stimato in dollari USA della scrittura di `context_tokens` nella cache del prompt su `to_model` alla tariffa di `cache_ttl`, esclusa la risposta successiva. Il server potrebbe non dover rimemorizzare nella cache l'intero contesto, quindi consideralo una stima |
3509| `pricing` | string | Come Claude Code ha calcolato il prezzo di `estimated_cache_write_usd`: `"configured"` alle tariffe della tua organizzazione quando le ha configurate, `"catalog"` al prezzo di listino, oppure `"default"` quando `to_model` non ha un prezzo noto e Claude Code ha assunto una tariffa predefinita |3511| `pricing` | string | Come Claude Code ha calcolato il prezzo di `estimated_cache_write_usd`: `"configured"` alle tariffe della tua organizzazione quando le ha configurate, `"catalog"` al prezzo di listino, oppure `"default"` quando `to_model` non ha un prezzo noto e Claude Code ha ipotizzato una tariffa predefinita |
3510 3512
3511Questo esempio mostra l'input per `/model opus` in una sessione che usa Sonnet 5:3513Questo esempio mostra l'input per `/model opus` in una sessione che usa Sonnet 5:
3512 3514
3534 3536
3535Gli hook `PreModelSwitch` possono annullare il cambio, chiedere all'utente di confermarlo o lasciarlo procedere. Il codice di uscita 2 o un `decision: "block"` di primo livello annulla il cambio.3537Gli hook `PreModelSwitch` possono annullare il cambio, chiedere all'utente di confermarlo o lasciarlo procedere. Il codice di uscita 2 o un `decision: "block"` di primo livello annulla il cambio.
3536 3538
3537Per un controllo più preciso, restituisci `permissionDecision` e `permissionDecisionReason` in un oggetto `hookSpecificOutput`, come per [PreToolUse](#pretooluse-decision-control). `PreModelSwitch` accetta `"allow"`, `"deny"` e `"ask"`. Non accetta `"defer"`, `updatedInput` o `additionalContext`. La tabella seguente descrive entrambi i campi:3539Per un controllo più preciso, restituisci `permissionDecision` e `permissionDecisionReason` in un oggetto `hookSpecificOutput`, come per [PreToolUse](#pretooluse-decision-control). `PreModelSwitch` accetta `"allow"`, `"deny"` e `"ask"`. Non accetta `"defer"`, `updatedInput` né `additionalContext`. La tabella seguente descrive entrambi i campi:
3538 3540
3539| Campo | Descrizione |3541| Campo | Descrizione |
3540| :- | :- |3542| :- | :- |
3541| `permissionDecision` | `"allow"` procede e salta la [conferma che Claude Code mostra mentre la cache del prompt è attiva](/docs/it/prompt-caching#switching-models). `"deny"` annulla il cambio. `"ask"` chiede all'utente di confermarlo |3543| `permissionDecision` | `"allow"` procede e salta la [conferma che Claude Code mostra mentre la cache del prompt è calda](/docs/it/prompt-caching#switching-models). `"deny"` annulla il cambio. `"ask"` chiede all'utente di confermarlo |
3542| `permissionDecisionReason` | Per `"deny"`, mostrato all'utente come motivo del blocco del cambio, o restituito come errore per una richiesta `set_model`. Per `"ask"`, mostrato nella richiesta di conferma. Ignorato per `"allow"` |3544| `permissionDecisionReason` | Per `"deny"`, viene mostrato all'utente come motivo del blocco del cambio, oppure restituito come errore per una richiesta `set_model`. Per `"ask"`, viene mostrato nella richiesta di conferma. Ignorato per `"allow"` |
3543 3545
3544Solo `/model` in una sessione interattiva può mostrare la richiesta di conferma di `"ask"`. Su ogni altra superficie, inclusa la modalità non interattiva con il flag `-p`, `/config` e le richieste `set_model`, Claude Code tratta `"ask"` come un rifiuto.3546Solo `/model` in una sessione interattiva può mostrare la richiesta `"ask"`. Su ogni altra superficie, inclusa la modalità non interattiva con il flag `-p`, `/config` e le richieste `set_model`, Claude Code tratta `"ask"` come un rifiuto.
3545 3547
3546Questo esempio chiede all'utente di confermare e cita il numero di token da `context_tokens`:3548Questo esempio chiede all'utente di confermare e cita il numero di token da `context_tokens`:
3547 3549
3555}3557}
3556```3558```
3557 3559
3558Quando più hook PreModelSwitch restituiscono decisioni diverse, l'ordine di precedenza è `deny` > `ask` > `allow`.3560Quando più hook PreModelSwitch restituiscono decisioni diverse, la precedenza è `deny` > `ask` > `allow`.
3559 3561
3560Claude Code mostra all'utente qualsiasi `systemMessage` restituito dal tuo hook indipendentemente dalla decisione, quindi un hook di report dei costi può restituire `{"systemMessage": "..."}` e uscire con 0.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.
3561 3563
3562Un hook PreModelSwitch che non risponde prima del suo timeout blocca il cambio. Al contrario, su [PreToolUse](#timeouts), 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.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.
3563 3565
3564Un 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).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).
3565 3567
3567 PostModelSwitch3569 PostModelSwitch
3568</h3>3570</h3>
3569 3571
3570Viene eseguito dopo che il modello della sessione cambia. Usalo per fornire a Claude indicazioni specifiche per il modello senza modificare ogni CLAUDE.md, ad esempio un'istruzione valida per tutta l'organizzazione che si applica a determinati modelli.3572Viene eseguito dopo che il modello della sessione è cambiato. Usalo per dare a Claude indicazioni specifiche per il modello senza modificare ogni CLAUDE.md, ad esempio un'istruzione a livello di organizzazione che si applica su determinati modelli.
3571 3573
3572PostModelSwitch richiede Claude Code v2.1.251 o successivo. Non può bloccare, perché il modello è già cambiato. Claude Code esegue gli hook PostModelSwitch dopo uno qualsiasi di questi cambi:3574PostModelSwitch richiede Claude Code v2.1.251 o successiva. Non può bloccare, perché il modello è già cambiato. Claude Code esegue gli hook PostModelSwitch dopo uno qualsiasi di questi cambiamenti:
3573 3575
3574* Un cambio richiesto da te o da un client3576* Un cambio richiesto da te o da un client
3575* Un [fallback automatico del modello](/docs/it/model-config#automatic-model-fallback), che cambia il modello della sessione3577* Un [fallback automatico del modello](/docs/it/model-config#automatic-model-fallback), che cambia il modello della sessione
3578 3580
3579Claude Code non esegue gli hook PostModelSwitch quando un modello di una [catena di modelli di fallback](/docs/it/model-config#fallback-model-chains) gestisce un turno, perché quella sostituzione dura un solo turno e lascia invariato il modello della sessione.3581Claude Code non esegue gli hook PostModelSwitch quando un modello di una [catena di modelli di fallback](/docs/it/model-config#fallback-model-chains) gestisce un turno, perché quella sostituzione dura un solo turno e lascia invariato il modello della sessione.
3580 3582
3581Il matcher segue le stesse regole di [PreModelSwitch](#premodelswitch): Claude Code lo confronta con il nome canonico del modello verso cui la sessione è passata.3583Il matcher segue le stesse regole di [PreModelSwitch](#premodelswitch): Claude Code lo confronta con il nome canonico del modello a cui la sessione è passata.
3582 3584
3583Questo esempio aggiunge indicazioni ogni volta che il modello della sessione passa a un qualsiasi modello Opus:3585Questo esempio aggiunge indicazioni ogni volta che il modello della sessione passa a un qualsiasi modello Opus:
3584 3586
3600}3602}
3601```3603```
3602 3604
3603Per verificare che l'hook funzioni, passa a un modello Opus da una sessione che usa un modello diverso, ad esempio esegui `/model opus` da una sessione Sonnet, poi chiedi a Claude quali indicazioni ha sul modello corrente.3605Per verificare che l'hook funzioni, passa a un modello Opus da una sessione che usa un modello diverso, ad esempio esegui `/model opus` da una sessione Sonnet, quindi chiedi a Claude quali indicazioni ha sul modello corrente.
3604 3606
3605<h4 id="postmodelswitch-input">3607<h4 id="postmodelswitch-input">
3606 Input di PostModelSwitch3608 Input di PostModelSwitch
3607</h4>3609</h4>
3608 3610
3609Gli hook PostModelSwitch ricevono gli stessi campi di [PreModelSwitch](#premodelswitch-input), con `hook_event_name` impostato su `"PostModelSwitch"` e due valori aggiuntivi di `source`: `"auto"` per un fallback automatico o un altro cambio effettuato autonomamente da Claude Code, e `"resume"` per il modello ripristinato quando riprendi una sessione.3611Gli hook PostModelSwitch ricevono gli stessi campi di [PreModelSwitch](#premodelswitch-input), con `hook_event_name` impostato su `"PostModelSwitch"` e due ulteriori valori di `source`: `"auto"` per un fallback automatico o un'altra modifica che Claude Code ha effettuato autonomamente, e `"resume"` per il modello ripristinato quando riprendi una sessione.
3610 3612
3611`requested_model` è `null` quando `source` è `"auto"`. Quando `source` è `"resume"`, è l'impostazione del modello salvata che Claude Code ha ripristinato.3613`requested_model` è `null` quando `source` è `"auto"`. Quando `source` è `"resume"`, è l'impostazione del modello salvata che Claude Code ha ripristinato.
3612 3614
3614 Controllo decisionale di PostModelSwitch3616 Controllo decisionale di PostModelSwitch
3615</h4>3617</h4>
3616 3618
3617Claude Code prende lo [stdout in testo semplice](#exit-code-0) del tuo hook all'uscita con 0, o `additionalContext` dall'output JSON, e lo consegna a Claude con la richiesta successiva al cambio. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, puoi restituire:3619Claude Code prende lo [stdout in testo semplice](#exit-code-0) del tuo hook all'uscita con 0, oppure `additionalContext` dall'output JSON, e lo consegna a Claude con la richiesta successiva al cambio. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, puoi restituire:
3618 3620
3619| Campo | Descrizione |3621| Campo | Descrizione |
3620| :- | :- |3622| :- | :- |
3626 SessionEnd3628 SessionEnd
3627</h3>3629</h3>
3628 3630
3629Viene eseguito quando una sessione di Claude Code termina. Utile per attività di pulizia, registrazione delle3631Viene eseguito quando una sessione di Claude Code termina. Utile per attività di pulizia, per registrare le statistiche
3630statistiche della sessione o salvataggio dello stato della sessione. Supporta i matcher per filtrare in base al motivo di uscita.3632della sessione o salvare lo stato della sessione. Supporta i matcher per filtrare in base al motivo di uscita.
3631 3633
3632Il campo `reason` nell'input dell'hook indica perché la sessione è terminata:3634Il campo `reason` nell'input dell'hook indica perché la sessione è terminata:
3633 3635
3656}3658}
3657```3659```
3658 3660
3659Gli hook SessionEnd non hanno controllo decisionale. Non possono bloccare la chiusura della sessione ma possono eseguire attività di pulizia. Claude Code scarta i loro [campi di output JSON](#json-output), come `systemMessage`.3661Gli hook SessionEnd non hanno controllo decisionale. Non possono bloccare la terminazione della sessione, ma possono eseguire attività di pulizia. Claude Code scarta i loro [campi di output JSON](#json-output), come `systemMessage`.
3660 3662
3661Gli hook SessionEnd hanno un timeout predefinito di 1,5 secondi. Si applica quando esci, esegui `/clear` o cambi sessione con `/resume` interattivo. Puoi concedere più tempo a un hook in due modi:3663Gli hook SessionEnd hanno un timeout predefinito di 1,5 secondi. Si applica quando esci, esegui `/clear` o cambi sessione con `/resume` interattivo. Puoi concedere più tempo a un hook in due modi:
3662 3664
3663* **`timeout` per singolo hook**: imposta `timeout` nella configurazione di quell'hook. Il budget complessivo aumenta automaticamente fino a corrispondere al `timeout` per singolo hook più alto nei tuoi file di impostazioni, fino a 60 secondi. Se aumenti il budget in questo modo, un hook senza un proprio `timeout` mantiene comunque il valore predefinito. I timeout impostati sugli hook forniti dai plugin non aumentano il budget.3665* **`timeout` per hook**: imposta `timeout` nella configurazione di quell'hook. Il budget complessivo aumenta automaticamente fino al `timeout` per hook più alto nei tuoi file di impostazioni, fino a 60 secondi. Se aumenti il budget in questo modo, un hook senza un proprio `timeout` mantiene comunque il valore predefinito. I timeout impostati sugli hook forniti dai plugin non aumentano il budget.
3664* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: imposta questa variabile d'ambiente in millisecondi per sovrascrivere esplicitamente il budget. Il valore che imposti diventa anche il timeout per ogni hook senza un proprio `timeout`.3666* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: imposta questa variabile d'ambiente in millisecondi per sovrascrivere esplicitamente il budget. Il valore impostato diventa anche il timeout per ogni hook senza un proprio `timeout`.
3665 3667
3666Questo esempio imposta il budget a 5 secondi:3668Questo esempio imposta il budget a 5 secondi:
3667 3669
3675 Elicitation3677 Elicitation
3676</h3>3678</h3>
3677 3679
3678Viene eseguito quando un server MCP richiede un input dell'utente durante un'attività. Per impostazione predefinita, Claude Code mostra una finestra di dialogo interattiva a cui l'utente può rispondere. Gli hook possono intercettare questa richiesta e rispondere in modo programmatico, saltando completamente la finestra di dialogo.3680Viene eseguito quando un server MCP richiede l'input dell'utente durante un'attività. Per impostazione predefinita, Claude Code mostra una finestra di dialogo interattiva a cui l'utente risponde. Gli hook possono intercettare questa richiesta e rispondere in modo programmatico, saltando completamente la finestra di dialogo.
3681
3682Per un hook completo con la relativa voce di impostazioni e lo script, consulta [Rispondere a una richiesta di modulo da uno script](#answer-a-form-request-from-a-script).
3679 3683
3680Il campo matcher viene confrontato con il nome del server MCP.3684Il campo matcher viene confrontato con il nome del server MCP.
3681 3685
3683 Input di Elicitation3687 Input di Elicitation
3684</h4>3688</h4>
3685 3689
3686Oltre ai [campi di input comuni](#common-input-fields), gli hook Elicitation ricevono `mcp_server_name`, `message` e i campi facoltativi `mode`, `url`, `elicitation_id` e `requested_schema`.3690Oltre ai [campi di input comuni](#common-input-fields), gli hook Elicitation ricevono `mcp_server_name`, `message` e i campi opzionali `mode`, `url`, `elicitation_id` e `requested_schema`.
3687 3691
3688Per l'elicitation in modalità form, il caso più comune:3692Per l'elicitation in modalità modulo, il caso più comune:
3689 3693
3690```json theme={null}3694```json theme={null}
3691{3695{
3724 Output di Elicitation3728 Output di Elicitation
3725</h4>3729</h4>
3726 3730
3727Per rispondere in modo programmatico senza mostrare la finestra di dialogo, restituisci un oggetto JSON con `hookSpecificOutput`:3731Un hook Elicitation può rispondere alla richiesta al posto dell'utente, rifiutarla o annullarla, oppure lasciarla alla finestra di dialogo. Per rispondere, rifiutare o annullare, esci con 0 e stampa un oggetto `hookSpecificOutput` con un `action`. Il server riceve la tua risposta e non compare alcuna finestra di dialogo. Ogni riga di questa tabella mostra cosa restituire per un esito e cosa riceve il server MCP:
3732
3733| Per | Restituisci | Il server riceve |
3734| :- | :- | :- |
3735| Rispondere al posto dell'utente | `"action": "accept"`, con i valori dei campi del modulo in `content` | `accept` con il tuo `content` |
3736| Rifiutare la richiesta | `"action": "decline"` | `decline` |
3737| Annullare la richiesta | `"action": "cancel"` | `cancel` |
3738| Lasciare la richiesta all'utente | Nessun output, con codice di uscita 0 | La risposta dell'utente dalla [finestra di dialogo](/docs/it/mcp#respond-to-mcp-elicitation-requests) |
3739
3740Questo output risponde alla richiesta in modalità modulo mostrata in [Input di Elicitation](#elicitation-input). Le chiavi in `content` sono i nomi delle proprietà dal `requested_schema` di quella richiesta:
3728 3741
3729```json theme={null}3742```json theme={null}
3730{3743{
3738}3751}
3739```3752```
3740 3753
3741| Campo | Valori | Descrizione |3754Questo output rifiuta una richiesta:
3742| :- | :- | :- |3755
3743| `action` | `accept`, `decline`, `cancel` | Se accettare, rifiutare o annullare la richiesta |3756```json theme={null}
3744| `content` | object | Valori dei campi del form da inviare. Usato solo quando `action` è `accept` |3757{
3758 "hookSpecificOutput": {
3759 "hookEventName": "Elicitation",
3760 "action": "decline"
3761 }
3762}
3763```
3764
3765Nella finestra di dialogo, selezionare **Decline** invia `decline` e premere `Esc` invia `cancel`, quindi restituisci quello che vuoi che il server veda.
3766
3767Per una richiesta in modalità URL, un hook che restituisce `accept` salta la finestra di dialogo, quindi l'URL non viene mai aperto.
3768
3769Claude Code scarta `reason`, `systemMessage` e `continue` dall'output JSON di un hook Elicitation, qualunque `action` tu restituisca.
3770
3771<h4 id="other-ways-to-decline-an-elicitation">
3772 Altri modi per rifiutare un'elicitation
3773</h4>
3774
3775Il tuo hook può anche rifiutare nei modi seguenti. Il server riceve lo stesso `decline` di `"action": "decline"`:
3776
3777* **Esce con codice 2**: Claude Code ignora un `hookSpecificOutput` stampato dallo stesso hook
3778* **Stampa un `"decision": "block"` di primo livello**: il blocco ha la precedenza su un `action` nello stesso output
3779
3780Quando più hook corrispondono alla stessa richiesta, un rifiuto da parte di uno di essi ha la precedenza su un `accept` o un `cancel` di un altro.
3781
3782Questo script rifiuta le richieste in modalità URL e lascia le richieste di modulo alla finestra di dialogo:
3783
3784```bash theme={null}
3785#!/bin/bash
3786if [ "$(jq -r '.mode')" = "url" ]; then
3787 exit 2
3788fi
3789```
3790
3791Né l'utente né il server vedono perché il tuo hook ha rifiutato, perché Claude Code non mostra il tuo stderr né il tuo `reason`.
3745 3792
3746Il codice di uscita 2 nega l'elicitation. Claude Code non mostra il tuo messaggio stderr da nessuna parte.3793Claude Code ignorava un `decision` di primo livello dagli hook `Elicitation` ed `ElicitationResult` dalla v2.1.105 fino alla correzione nella v2.1.284.
3747 3794
3748Claude Code agisce su `hookSpecificOutput` dall'output JSON di un hook Elicitation e scarta `systemMessage` e `continue`.3795<h4 id="answer-a-form-request-from-a-script">
3796 Rispondere a una richiesta di modulo da uno script
3797</h4>
3798
3799Questo esempio risponde a una domanda ricorrente al posto dell'utente. Un server MCP chiamato `issue-tracker` chiede una chiave di progetto in un modulo, e l'hook inserisce `DOCS`. Lo script accetta quando `project_key` è l'unico campo del modulo. Per qualsiasi altra richiesta non stampa nulla, quindi compare la finestra di dialogo.
3800
3801<Tabs>
3802 <Tab title="macOS/Linux">
3803 Registra un hook di comando per l'evento nel tuo file di impostazioni, con il nome del server come matcher:
3804
3805 ```json theme={null}
3806 {
3807 "hooks": {
3808 "Elicitation": [
3809 {
3810 "matcher": "issue-tracker",
3811 "hooks": [
3812 {
3813 "type": "command",
3814 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.sh",
3815 "args": []
3816 }
3817 ]
3818 }
3819 ]
3820 }
3821 }
3822 ```
3823
3824 Salva questo script in `.claude/hooks/answer-project-key.sh` nel tuo progetto e rendilo eseguibile con `chmod +x`:
3825
3826 ```bash theme={null}
3827 #!/bin/bash
3828 input=$(cat)
3829 fields=$(jq -c '.requested_schema.properties // {} | keys' <<<"$input")
3830
3831 if [ "$fields" = '["project_key"]' ]; then
3832 jq -n '{hookSpecificOutput: {hookEventName: "Elicitation", action: "accept", content: {project_key: "DOCS"}}}'
3833 fi
3834 ```
3835 </Tab>
3836
3837 <Tab title="Windows (PowerShell)">
3838 Registra un hook di comando che esegue lo script tramite PowerShell, con il nome del server come matcher:
3839
3840 ```json theme={null}
3841 {
3842 "hooks": {
3843 "Elicitation": [
3844 {
3845 "matcher": "issue-tracker",
3846 "hooks": [
3847 {
3848 "type": "command",
3849 "command": "powershell.exe",
3850 "args": [
3851 "-NoProfile",
3852 "-ExecutionPolicy",
3853 "Bypass",
3854 "-File",
3855 "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.ps1"
3856 ]
3857 }
3858 ]
3859 }
3860 ]
3861 }
3862 }
3863 ```
3864
3865 Salva questo script in `.claude/hooks/answer-project-key.ps1` nel tuo progetto:
3866
3867 ```powershell theme={null}
3868 $request = [Console]::In.ReadToEnd() | ConvertFrom-Json
3869 $fields = @($request.requested_schema.properties.PSObject.Properties.Name)
3870
3871 if ($fields.Count -eq 1 -and $fields[0] -eq 'project_key') {
3872 @{
3873 hookSpecificOutput = @{
3874 hookEventName = "Elicitation"
3875 action = "accept"
3876 content = @{ project_key = "DOCS" }
3877 }
3878 } | ConvertTo-Json -Depth 3
3879 }
3880 ```
3881 </Tab>
3882</Tabs>
3883
3884Per verificare che l'hook funzioni, avvia Claude Code con `claude --debug` e assegna a Claude un'attività che porti il server a chiedere la chiave di progetto. Non compare alcuna finestra di dialogo, e il [log di debug](#debug-hooks) contiene una riga che termina con `Elicitation resolved by hook: {"action":"accept","content":{"project_key":"DOCS"}}`.
3749 3885
3750<h3 id="elicitationresult">3886<h3 id="elicitationresult">
3751 ElicitationResult3887 ElicitationResult
3753 3889
3754Viene eseguito dopo che un utente risponde a un'elicitation MCP. Gli hook possono osservare, modificare o bloccare la risposta prima che venga rinviata al server MCP.3890Viene eseguito dopo che un utente risponde a un'elicitation MCP. Gli hook possono osservare, modificare o bloccare la risposta prima che venga rinviata al server MCP.
3755 3891
3892Quando un hook [Elicitation](#elicitation) risponde a una richiesta, Claude Code invia quella risposta al server senza eseguire gli hook ElicitationResult.
3893
3756Il campo matcher viene confrontato con il nome del server MCP.3894Il campo matcher viene confrontato con il nome del server MCP.
3757 3895
3758<h4 id="elicitationresult-input">3896<h4 id="elicitationresult-input">
3759 Input di ElicitationResult3897 Input di ElicitationResult
3760</h4>3898</h4>
3761 3899
3762Oltre ai [campi di input comuni](#common-input-fields), gli hook ElicitationResult ricevono `mcp_server_name`, `action` e i campi facoltativi `mode`, `elicitation_id` e `content`.3900Oltre ai [campi di input comuni](#common-input-fields), gli hook ElicitationResult ricevono `mcp_server_name`, `action` e i campi opzionali `mode`, `elicitation_id` e `content`.
3763 3901
3764```json theme={null}3902```json theme={null}
3765{3903{
3770 "mcp_server_name": "my-mcp-server",3908 "mcp_server_name": "my-mcp-server",
3771 "action": "accept",3909 "action": "accept",
3772 "content": { "username": "alice" },3910 "content": { "username": "alice" },
3773 "mode": "form",3911 "mode": "form"
3774 "elicitation_id": "elicit-123"
3775}3912}
3776```3913```
3777 3914
3779 Output di ElicitationResult3916 Output di ElicitationResult
3780</h4>3917</h4>
3781 3918
3782Per sovrascrivere la risposta dell'utente, restituisci un oggetto JSON con `hookSpecificOutput`:3919Un hook ElicitationResult può lasciar passare la risposta dell'utente, modificarne i valori o bloccarla. Per modificare o bloccare la risposta, esci con 0 e stampa un oggetto `hookSpecificOutput` con un `action`. Ogni riga di questa tabella mostra cosa restituire per un esito e cosa riceve il server MCP:
3920
3921| Per | Restituisci | Il server riceve |
3922| :- | :- | :- |
3923| Lasciar passare la risposta | Nessun output, con codice di uscita 0 | La risposta dell'utente, invariata |
3924| Modificare i valori inviati | `"action": "accept"`, con i nuovi valori in `content` | `accept` con il tuo `content` al posto dei valori dell'utente |
3925| Bloccare la risposta | `"action": "decline"` | `decline`, senza i valori dell'utente |
3926| Annullare la richiesta | `"action": "cancel"` | `cancel`, insieme ai valori inviati dall'utente. Per non inviarli, restituisci `"decline"` |
3927
3928Questo output modifica la risposta mostrata in [Input di ElicitationResult](#elicitationresult-input), così il server riceve `alice@example.com` dove l'utente ha inviato `alice`:
3783 3929
3784```json theme={null}3930```json theme={null}
3785{3931{
3786 "hookSpecificOutput": {3932 "hookSpecificOutput": {
3787 "hookEventName": "ElicitationResult",3933 "hookEventName": "ElicitationResult",
3788 "action": "decline",3934 "action": "accept",
3789 "content": {}3935 "content": {
3936 "username": "alice@example.com"
3937 }
3790 }3938 }
3791}3939}
3792```3940```
3793 3941
3794| Campo | Valori | Descrizione |3942Il tuo `content` sostituisce l'intero oggetto `content` dell'utente, quindi includi i campi che non stai modificando. Restituisci `action` insieme a esso, perché Claude Code ignora un `hookSpecificOutput` che non ha `action`.
3795| :- | :- | :- |3943
3796| `action` | `accept`, `decline`, `cancel` | Sovrascrive l'azione dell'utente |3944Gli hook ElicitationResult vengono eseguiti anche quando l'utente rifiuta o annulla, e il tuo `action` sostituisce il suo. Verifica che l'`action` dell'input sia `accept` prima di restituire `accept`, altrimenti il tuo hook trasforma una richiesta rifiutata in una accettata. Questo script apporta la stessa modifica quando l'utente ha accettato, mantiene gli altri campi e altrimenti non stampa nulla:
3797| `content` | object | Sovrascrive i valori dei campi del form. Significativo solo quando `action` è `accept` |3945
3946```bash theme={null}
3947#!/bin/bash
3948input=$(cat)
3798 3949
3799Il codice di uscita 2 blocca la risposta, cambiando l'azione effettiva in `decline`. Claude Code non mostra il tuo messaggio stderr da nessuna parte.3950if [ "$(jq -r '.action' <<<"$input")" = "accept" ]; then
3951 jq '{hookSpecificOutput: {hookEventName: "ElicitationResult", action: "accept", content: (.content + {username: (.content.username + "@example.com")})}}' <<<"$input"
3952fi
3953```
3800 3954
3801Claude Code agisce su `hookSpecificOutput` dall'output JSON di un hook ElicitationResult e scarta `systemMessage` e `continue`.3955Questo output blocca la risposta:
3956
3957```json theme={null}
3958{
3959 "hookSpecificOutput": {
3960 "hookEventName": "ElicitationResult",
3961 "action": "decline"
3962 }
3963}
3964```
3965
3966Anche il codice di uscita 2 e un `"decision": "block"` di primo livello bloccano la risposta. [Altri modi per rifiutare un'elicitation](#other-ways-to-decline-an-elicitation) spiega quale ha effetto quando un hook li combina, cosa vede l'utente e quali versioni ignoravano `decision`.
3967
3968Claude Code scarta `reason`, `systemMessage` e `continue` dall'output JSON di un hook ElicitationResult, qualunque `action` tu restituisca.
3802 3969
3803<h2 id="prompt-based-hooks">3970<h2 id="prompt-based-hooks">
3804 Hook basati su prompt3971 Hook basati su prompt
3862 4029
3863Impostare `type` su `"prompt"` e fornire una stringa `prompt` invece di un `command`. Utilizzare il segnaposto `$ARGUMENTS` per iniettare i dati di input JSON del hook nel testo del prompt.4030Impostare `type` su `"prompt"` e fornire una stringa `prompt` invece di un `command`. Utilizzare il segnaposto `$ARGUMENTS` per iniettare i dati di input JSON del hook nel testo del prompt.
3864 4031
4032In un hook di prompt o in un [hook agente](#agent-based-hooks), puoi scrivere il `prompt` come una regola su cosa bloccare o consentire, ad esempio "Blocca qualsiasi comando Bash che legge file `.env`", oppure come una condizione che deve essere soddisfatta, ad esempio "Tutti i test unitari passano".
4033
3865Questo hook `Stop` chiede all'LLM di valutare se tutti i compiti sono completi prima di consentire a Claude di terminare:4034Questo hook `Stop` chiede all'LLM di valutare se tutti i compiti sono completi prima di consentire a Claude di terminare:
3866 4035
3867```json theme={null}4036```json theme={null}
