297| :-------------- | :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |297| :-------------- | :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
298| `type` | sì | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` o `"agent"` |298| `type` | sì | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` o `"agent"` |
299| `if` | no | Sintassi della regola di autorizzazione per filtrare quando questo hook viene eseguito, come `"Bash(git *)"` o `"Edit(*.ts)"`. L'hook viene eseguito solo se la chiamata dello strumento corrisponde al modello, o se un comando Bash è troppo complesso da analizzare. Valutato solo su eventi degli strumenti: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` e `PermissionDenied`. Su altri eventi, un hook con `if` impostato non viene mai eseguito. Utilizza la stessa sintassi delle [regole di autorizzazione](/it/permissions) |299| `if` | no | Sintassi della regola di autorizzazione per filtrare quando questo hook viene eseguito, come `"Bash(git *)"` o `"Edit(*.ts)"`. L'hook viene eseguito solo se la chiamata dello strumento corrisponde al modello, o se un comando Bash è troppo complesso da analizzare. Valutato solo su eventi degli strumenti: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` e `PermissionDenied`. Su altri eventi, un hook con `if` impostato non viene mai eseguito. Utilizza la stessa sintassi delle [regole di autorizzazione](/it/permissions) |
300| `timeout` | no | Secondi prima dell'annullamento. Impostazioni predefinite: 600 per command, 30 per prompt, 60 per agent |300| `timeout` | no | Secondi prima dell'annullamento. Impostazioni predefinite: 600 per `command`, `http` e `mcp_tool`; 30 per `prompt`; 60 per `agent`. [`UserPromptSubmit`](#userpromptsubmit) abbassa l'impostazione predefinita di `command`, `http` e `mcp_tool` a 30 |
301| `statusMessage` | no | Messaggio spinner personalizzato visualizzato mentre l'hook viene eseguito |301| `statusMessage` | no | Messaggio spinner personalizzato visualizzato mentre l'hook viene eseguito |
302| `once` | no | Se `true`, viene eseguito una sola volta per sessione e poi rimosso. Solo onorato per gli hook dichiarati nel [frontmatter della skill](#hooks-in-skills-and-agents); ignorato nei file di impostazioni e nel frontmatter dell'agente |302| `once` | no | Se `true`, viene eseguito una sola volta per sessione e poi rimosso. Solo onorato per gli hook dichiarati nel [frontmatter della skill](#hooks-in-skills-and-agents); ignorato nei file di impostazioni e nel frontmatter dell'agente |
303 303
558 558
559I 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.559I 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.
560 560
561Su macOS e Linux, i command hook vengono eseguiti nella loro propria sessione senza un terminale di controllo a partire da v2.1.139. Il processo hook e qualsiasi processo figlio non possono aprire `/dev/tty` o inviare sequenze di escape direttamente all'interfaccia Claude Code. Windows non ha `/dev/tty`. Per visualizzare un messaggio all'utente su qualsiasi piattaforma, restituire [`systemMessage`](#json-output) nell'output JSON. Per attivare una notifica desktop, impostare un titolo della finestra o suonare il campanello, restituire [`terminalSequence`](#emit-terminal-notifications) invece.
562
561### Campi di input comuni563### Campi di input comuni
562 564
563Gli hook event ricevono questi campi come JSON, oltre ai campi specifici dell'evento documentati in ogni sezione [hook event](#hook-events). Per i command hook, questo JSON arriva tramite stdin. Per gli HTTP hook, arriva come corpo della richiesta POST.565Gli hook event ricevono questi campi come JSON, oltre ai campi specifici dell'evento documentati in ogni sezione [hook event](#hook-events). Per i command hook, questo JSON arriva tramite stdin. Per gli HTTP hook, arriva come corpo della richiesta POST.
694* **`hookSpecificOutput`** è un oggetto annidato per gli eventi che necessitano di un controllo più ricco. Richiede un campo `hookEventName` impostato sul nome dell'evento.696* **`hookSpecificOutput`** è un oggetto annidato per gli eventi che necessitano di un controllo più ricco. Richiede un campo `hookEventName` impostato sul nome dell'evento.
695 697
696| Campo | Impostazione predefinita | Descrizione |698| Campo | Impostazione predefinita | Descrizione |
697| :--------------- | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |699| :----------------- | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
698| `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 |700| `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 |
699| `stopReason` | nessuno | Messaggio mostrato all'utente quando `continue` è `false`. Non mostrato a Claude |701| `stopReason` | nessuno | Messaggio mostrato all'utente quando `continue` è `false`. Non mostrato a Claude |
700| `suppressOutput` | `false` | Se `true`, omette stdout dal log di debug |702| `suppressOutput` | `false` | Se `true`, omette stdout dal log di debug |
701| `systemMessage` | nessuno | Messaggio di avviso mostrato all'utente |703| `systemMessage` | nessuno | Messaggio di avviso mostrato all'utente |
704| `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. Utilizzare questo invece di scrivere su `/dev/tty`, che non è disponibile per gli hook |
702 705
703Per fermare Claude completamente indipendentemente dal tipo di evento:706Per fermare Claude completamente indipendentemente dal tipo di evento:
704 707
706{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }709{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }
707```710```
708 711
712#### Emettere notifiche del terminale
713
714Il campo `terminalSequence` richiede Claude Code v2.1.141 o successivo.
715
716Gli hook vengono eseguiti senza un terminale di controllo, quindi la scrittura di 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`.
717
718Il campo accetta una stringa di una o più sequenze di escape nella lista di autorizzazione:
719
720* OSC `0`, `1`, `2`: titoli della finestra e dell'icona
721* OSC `9`: notifiche iTerm2, ConEmu, Windows Terminal e WezTerm, incluso `9;4` progresso della barra delle applicazioni
722* OSC `99`: notifiche Kitty
723* OSC `777`: notifiche urxvt, Ghostty e Warp
724* BEL nudo
725
726Le 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.
727
728L'esempio seguente attiva una notifica desktop da un hook `Notification`. La sequenza di escape viene costruita con `printf` escape ottali 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:
729
730```bash theme={null}
731#!/bin/bash
732# Hook di notifica: avvisa il desktop quando Claude Code ha bisogno di attenzione.
733input=$(cat)
734title="Claude Code'
735body=$(jq -r '.message // "Needs your attention"' <<<"$input")
736seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
737jq -nc --arg seq "$seq" '{terminalSequence: $seq}'
738```
739
740La forma `{ "terminalSequence": "..." }` è la stessa da qualsiasi shell o linguaggio. Su Windows, costruire la stringa di escape in PowerShell o uno script e emettere lo stesso oggetto JSON.
741
742<Note>
743 `terminalSequence` è la sostituzione supportata per gli hook che in precedenza scrivevano sequenze di escape direttamente su `/dev/tty`. La lista di autorizzazione è limitata alle sequenze che non possono spostare il cursore o alterare i colori, quindi un hook non può mai corrompere un prompt sullo schermo.
744</Note>
745
709#### Aggiungere contesto per Claude746#### Aggiungere contesto per Claude
710 747
711Il campo `additionalContext` passa una stringa dal hook nel contesto della finestra di Claude. Claude Code avvolge la stringa in un promemoria di sistema e la inserisce nella conversazione nel punto in cui l'hook si è attivato. Claude legge il promemoria nella prossima richiesta del modello, ma non appare come messaggio di chat nell'interfaccia.748Il campo `additionalContext` passa una stringa dal hook nel contesto della finestra di Claude. Claude Code avvolge la stringa in un promemoria di sistema e la inserisce nella conversazione nel punto in cui l'hook si è attivato. Claude legge il promemoria nella prossima richiesta del modello, ma non appare come messaggio di chat nell'interfaccia.
989 1026
990Viene eseguito quando l'utente invia un prompt, prima che Claude lo elabori. Ciò consente di aggiungere contesto aggiuntivo in base al prompt/conversazione, convalidare i prompt o bloccare determinati tipi di prompt.1027Viene eseguito quando l'utente invia un prompt, prima che Claude lo elabori. Ciò consente di aggiungere contesto aggiuntivo in base al prompt/conversazione, convalidare i prompt o bloccare determinati tipi di prompt.
991 1028
1029Gli hook `UserPromptSubmit` hanno un timeout predefinito di 30 secondi per i tipi `command`, `http` e `mcp_tool`, più breve del default di 600 secondi per questi tipi su altri eventi. Poiché questo hook viene eseguito prima di ogni prompt e blocca l'elaborazione del modello fino al completamento, un hook bloccato blocca la sessione. Se l'hook ha bisogno di più tempo, impostare il campo `timeout` nella voce dell'hook.
1030
992#### Input di UserPromptSubmit1031#### Input di UserPromptSubmit
993 1032
994Oltre ai [campi di input comuni](#common-input-fields), gli hook UserPromptSubmit ricevono il campo `prompt` contenente il testo che l'utente ha inviato.1033Oltre ai [campi di input comuni](#common-input-fields), gli hook UserPromptSubmit ricevono il campo `prompt` contenente il testo che l'utente ha inviato.
2598 2637
2599Quando un hook asincrono si attiva, Claude Code avvia il processo del hook e continua immediatamente senza aspettare il completamento. L'hook riceve lo stesso input JSON tramite stdin di un hook sincrono.2638Quando un hook asincrono si attiva, Claude Code avvia il processo del hook e continua immediatamente senza aspettare il completamento. L'hook riceve lo stesso input JSON tramite stdin di un hook sincrono.
2600 2639
2601Dopo che il processo in background esce, se l'hook ha prodotto una risposta JSON con un campo `systemMessage` o `additionalContext`, quel contenuto viene consegnato a Claude come contesto al turno di conversazione successivo.2640Dopo che il processo in background esce, se l'hook ha prodotto una risposta JSON con un campo `additionalContext`, quel contenuto viene consegnato a Claude come contesto al turno di conversazione successivo. Un campo `systemMessage` viene mostrato a voi, non a Claude.
2602 2641
2603Le notifiche di completamento degli hook asincroni sono soppresse per impostazione predefinita. Per vederle, abilitare la modalità verbose con `Ctrl+O` o avviare Claude Code con `--verbose`.2642Le notifiche di completamento degli hook asincroni sono soppresse per impostazione predefinita. Per vederle, abilitare la modalità verbose con `Ctrl+O` o avviare Claude Code con `--verbose`.
2604 2643
2619 exit 02658 exit 0
2620fi2659fi
2621 2660
2622# Eseguire i test e segnalare i risultati tramite systemMessage2661# Eseguire i test e segnalare i risultati a Claude tramite additionalContext
2623RESULT=$(npm test 2>&1)2662RESULT=$(npm test 2>&1)
2624EXIT_CODE=$?2663EXIT_CODE=$?
2625 2664
2626if [ $EXIT_CODE -eq 0 ]; then2665if [ $EXIT_CODE -eq 0 ]; then
2627 echo "{\"systemMessage\": \"Tests passed after editing $FILE_PATH\"}"2666 MSG="Tests passed after editing $FILE_PATH"
2628else2667else
2629 echo "{\"systemMessage\": \"Tests failed after editing $FILE_PATH: $RESULT\"}"2668 MSG="Tests failed after editing $FILE_PATH: $RESULT"
2630fi2669fi
2670jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'
2631```2671```
2632 2672
2633Quindi aggiungere questa configurazione a `.claude/settings.json` nella radice del progetto. Il flag `async: true` consente a Claude di continuare a lavorare mentre i test vengono eseguiti:2673Quindi aggiungere questa configurazione a `.claude/settings.json` nella radice del progetto. Il flag `async: true` consente a Claude di continuare a lavorare mentre i test vengono eseguiti:
