1156Per 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).1156Per 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).
1157 1157
1158<h2 id="hook-events">1158<h2 id="hook-events">
1159 Eventi hook1159 Eventi degli hook
1160</h2>1160</h2>
1161 1161
1162Ogni evento corrisponde a un punto nel ciclo di vita di Claude Code in cui gli hook possono essere eseguiti. Le sezioni seguenti sono ordinate per corrispondere al ciclo di vita: dalla configurazione della sessione attraverso il loop agentivo fino alla fine della sessione. Ogni sezione descrive quando l'evento si attiva, quali matcher supporta, l'input JSON che riceve e come controllare il comportamento attraverso l'output.1162Ogni 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.
1163 1163
1164<h3 id="sessionstart">1164<h3 id="sessionstart">
1165 SessionStart1165 SessionStart
1166</h3>1166</h3>
1167 1167
1168Si esegue quando Claude Code avvia una nuova sessione o riprende una sessione esistente. Utile per caricare il contesto di sviluppo come problemi esistenti o modifiche recenti al tuo codebase, o per configurare variabili di ambiente. Per il contesto statico che non richiede uno script, usa [CLAUDE.md](/docs/it/memory) invece.1168Viene 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).
1169 1169
1170SessionStart si esegue su ogni sessione, quindi mantieni questi hook veloci. Solo gli hook `type: "command"` e `type: "mcp_tool"` sono supportati. Vedi [MCP tool hook fields](#mcp-tool-hook-fields) per quando gli hook `mcp_tool` si eseguono.1170SessionStart 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`.
1171 1171
1172Il valore del matcher corrisponde a come la sessione è stata avviata:1172Il valore del matcher corrisponde al modo in cui è stata avviata la sessione:
1173 1173
1174| Matcher | Quando si attiva |1174| Matcher | Quando si attiva |
1175| :- | :- |1175| :- | :- |
1176| `startup` | Nuova sessione |1176| `startup` | Nuova sessione |
1177| `resume` | `--resume`, `--continue`, o `/resume` |1177| `resume` | `--resume`, `--continue` o `/resume` |
1178| `clear` | `/clear` |1178| `clear` | `/clear` |
1179| `compact` | Compattazione automatica o manuale |1179| `compact` | Compattazione automatica o manuale |
1180| `fork` | Una nuova sessione creata da una sessione esistente: `--fork-session` con `--resume` o `--continue`, la copia di background `/fork`, `/branch`, o una conversazione che [sposti in background](/docs/it/agent-view#from-inside-a-session) |1180| `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) |
1181 1181
1182Prima della v2.1.214, le sessioni create da fork segnalano la sorgente `"resume"`.1182Prima della v2.1.214, le sessioni derivate riportavano la sorgente `"resume"`.
1183 1183
1184Quando avvii una sessione interattiva, riprendi una conversazione al lancio con `--continue` o `--resume`, o esegui `/clear`, gli hook SessionStart si eseguono in background. Puoi digitare subito, e una conversazione che hai ripreso appare senza aspettare gli hook. La prima risposta di Claude attende comunque che gli hook finiscano, quindi il loro contesto raggiunge Claude.1184Quando 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.
1185 1185
1186Quando cambi conversazioni con `/resume` all'interno di una sessione, il cambio attende che gli hook finiscano. Se esegui `/clear` o cambi a un'altra conversazione mentre gli hook di background sono ancora in esecuzione, nulla di ciò che restituiscono si applica alla sessione.1186Quando 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.
1187 1187
1188Lo stesso attesa si applica al lancio, inclusa una sessione ripresa: un prompt che invii mentre gli hook SessionStart sono ancora in esecuzione non raggiunge Claude finché non finiscono.1188La 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.
1189 1189
1190Durante uno qualsiasi di questi attese, premi `Esc` per riprendere il prompt nell'input senza inviarlo. Gli hook continuano a essere eseguiti.1190Durante entrambe le attese, premi `Esc` per riportare il prompt nell'input senza inviarlo. Gli hook continuano a essere eseguiti.
1191 1191
1192<h4 id="sessionstart-input">1192<h4 id="sessionstart-input">
1193 Input SessionStart1193 Input di SessionStart
1194</h4>1194</h4>
1195 1195
1196Oltre ai [campi di input comuni](#common-input-fields), gli hook SessionStart ricevono `source` e facoltativamente `model`, `agent_type`, e `session_title`:1196Oltre ai [campi di input comuni](#common-input-fields), gli hook SessionStart ricevono `source` e, facoltativamente, `model`, `agent_type` e `session_title`:
1197 1197
1198| Campo | Descrizione |1198| Campo | Descrizione |
1199| :- | :- |1199| :- | :- |
1200| `source` | Come la sessione è stata avviata: `"startup"` per nuove sessioni, `"resume"` per sessioni riprese, `"clear"` dopo `/clear`, `"compact"` dopo compattazione, o `"fork"` per una nuova sessione creata da una sessione esistente |1200| `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 |
1201| `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 controlla il campo prima di leggerlo |1201| `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 |
1202| `agent_type` | Il nome dell'agente, presente quando avvii Claude Code con `claude --agent <name>` |1202| `agent_type` | Il nome dell'agente, presente quando avvii Claude Code con `claude --agent <name>` |
1203| `session_title` | Il titolo della sessione corrente se già impostato, ad esempio tramite `--name` o `/rename`. Un hook che emette `sessionTitle` può controllare `session_title` prima per evitare di sovrascrivere un titolo che l'utente ha impostato esplicitamente |1203| `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 |
1204 1204
1205Una sessione che non hai nominato può comunque avere un [titolo generato](/docs/it/sessions#name-your-sessions). Quel titolo non è un titolo personalizzato e non appare in `session_title`.1205Una 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`.
1206 1206
1207Quando `source` è `"resume"` o `"fork"` e la trascrizione contiene almeno una risposta da Claude, gli hook SessionStart ricevono anche i quattro campi seguenti. Il tuo hook può usarli per segnalare quale costo ha la ripresa di una conversazione obsoleta prima della prima richiesta, ad esempio in un [`systemMessage`](#json-output). Questi campi richiedono Claude Code v2.1.251 o successivo.1207Quando `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.
1208 1208
1209| Campo | Descrizione |1209| Campo | Descrizione |
1210| :- | :- |1210| :- | :- |
1211| `seconds_since_last_response` | Secondi di tempo reale dalla risposta più recente nella trascrizione ripresa |1211| `seconds_since_last_response` | Secondi reali trascorsi dall'ultima risposta nella trascrizione ripresa |
1212| `context_tokens` | Token che la prima richiesta della sessione ripresa invia di nuovo come suo prompt |1212| `context_tokens` | Token che la prima richiesta della sessione ripresa invia di nuovo come prompt |
1213| `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 |1213| `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 |
1214| `estimated_cache_write_usd` | Costo stimato in dollari USA della scrittura di `context_tokens` nella cache del prompt sul modello della sessione, escludendo la risposta |1214| `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 |
1215 1215
1216Questo esempio mostra l'input per una sessione ripresa 90 minuti dopo la sua ultima risposta:1216Questo esempio mostra l'input per una sessione ripresa 90 minuti dopo la sua ultima risposta:
1217 1217
1231```1231```
1232 1232
1233<h4 id="sessionstart-decision-control">1233<h4 id="sessionstart-decision-control">
1234 Controllo decisionale SessionStart1234 Controllo delle decisioni di SessionStart
1235</h4>1235</h4>
1236 1236
1237Claude Code aggiunge stdout che [tratta come testo semplice](#exit-code-0) al contesto di Claude. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, puoi restituire questi campi specifici dell'evento:1237Claude Code aggiunge al contesto di Claude lo stdout che [tratta come testo semplice](#exit-code-0). Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, puoi restituire questi campi specifici dell'evento:
1238 1238
1239| Campo | Descrizione |1239| Campo | Descrizione |
1240| :- | :- |1240| :- | :- |
1241| `additionalContext` | Stringa aggiunta al contesto di Claude all'inizio della conversazione, prima del primo prompt. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) per come il testo viene consegnato e cosa metterci |1241| `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 |
1242| `initialUserMessage` | Stringa utilizzata 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, segue come turno successivo. A differenza di `additionalContext`, che si allega a un turno esistente, questo crea il turno |1242| `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 |
1243| `sessionTitle` | Imposta il titolo della sessione, con lo stesso effetto di `/rename`. Usa per nominare le sessioni automaticamente dalla cartella di lancio, dal ramo git, o dal nome del worktree. Si applica quando `source` è `"startup"`, `"resume"`, o `"fork"`; ignorato su `"clear"` e `"compact"` |1243| `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"` |
1244| `watchPaths` | Array di percorsi assoluti da osservare per gli eventi [FileChanged](#filechanged) durante questa sessione |1244| `watchPaths` | Array di percorsi assoluti da monitorare per gli eventi [FileChanged](#filechanged) durante questa sessione |
1245| `reloadSkills` | Booleano. Quando `true`, Claude Code ripete la scansione delle directory [skill](/docs/it/skills) e command dopo che gli hook SessionStart completano, quindi le skill che l'hook ha installato sono disponibili nella stessa sessione, a partire dal primo prompt |1245| `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 |
1246 1246
1247```json theme={null}1247```json theme={null}
1248{1248{
1254}1254}
1255```1255```
1256 1256
1257Poiché lo stdout semplice raggiunge già Claude per questo evento, un hook che carica solo il contesto può stampare su stdout direttamente senza costruire JSON. Usa il modulo JSON quando hai bisogno di combinare il contesto con altri campi come `sessionTitle`.1257Poiché 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`.
1258 1258
1259Usa `reloadSkills` quando un hook SessionStart installa o aggiorna skill. La scoperta delle skill normalmente si esegue prima che gli hook SessionStart finiscano, 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 ripetizione della scansione:1259Usa `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:
1260 1260
1261```bash theme={null}1261```bash theme={null}
1262#!/bin/bash1262#!/bin/bash
1267echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1267echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1268```1268```
1269 1269
1270L'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. Stderr da un hook SessionStart che esce con 0 è solo informativo, quindi la richiesta `reloadSkills` si applica comunque.1270L'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.
1271 1271
1272<h4 id="persist-environment-variables">1272<h4 id="persist-environment-variables">
1273 Persistere variabili di ambiente1273 Rendere persistenti le variabili d'ambiente
1274</h4>1274</h4>
1275 1275
1276Gli hook SessionStart hanno accesso alla variabile di ambiente `CLAUDE_ENV_FILE`, che fornisce un percorso di file dove puoi persistere le variabili di ambiente per i comandi Bash successivi.1276Gli 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.
1277 1277
1278Per impostare singole variabili di ambiente, scrivi istruzioni `export` in `CLAUDE_ENV_FILE`. Usa append (`>>`) per preservare le variabili impostate da altri hook:1278Per impostare singole variabili d'ambiente, scrivi istruzioni `export` in `CLAUDE_ENV_FILE`. Usa l'accodamento (`>>`) per preservare le variabili impostate da altri hook:
1279 1279
1280```bash theme={null}1280```bash theme={null}
1281#!/bin/bash1281#!/bin/bash
1289exit 01289exit 0
1290```1290```
1291 1291
1292Per catturare tutti i cambiamenti di ambiente dai comandi di configurazione, confronta le variabili esportate prima e dopo:1292Per catturare tutte le modifiche all'ambiente dai comandi di configurazione, confronta le variabili esportate prima e dopo:
1293 1293
1294```bash theme={null}1294```bash theme={null}
1295#!/bin/bash1295#!/bin/bash
1309```1309```
1310 1310
1311<Note>1311<Note>
1312 `CLAUDE_ENV_FILE` è disponibile per gli hook SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged), e [FileChanged](#filechanged). Altri tipi di hook non hanno accesso a questa variabile.1312 `CLAUDE_ENV_FILE` è disponibile per gli hook SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged) e [FileChanged](#filechanged). Gli altri tipi di hook non hanno accesso a questa variabile.
1313</Note>1313</Note>
1314 1314
1315<h3 id="setup">1315<h3 id="setup">
1316 Setup1316 Setup
1317</h3>1317</h3>
1318 1318
1319Si esegue solo quando avvii Claude Code con `--init-only`, o con `--init` o `--maintenance` in [modalità non interattiva](/docs/it/headless) con il flag `-p`. Non si esegue all'avvio normale. Usalo per l'installazione di dipendenze una tantum o la pulizia programmata che attivi esplicitamente da CI o script, separato dall'avvio della sessione normale. Per l'inizializzazione per sessione, usa [SessionStart](#sessionstart) invece.1319Si 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).
1320 1320
1321Il valore del matcher corrisponde al flag CLI che ha attivato l'hook:1321Il valore del matcher corrisponde al flag CLI che ha attivato l'hook:
1322 1322
1325| `init` | `claude --init-only` o `claude -p --init` |1325| `init` | `claude --init-only` o `claude -p --init` |
1326| `maintenance` | `claude -p --maintenance` |1326| `maintenance` | `claude -p --maintenance` |
1327 1327
1328Quando esegui `claude --init-only`, Claude Code esegue gli hook Setup e gli hook `SessionStart` con il matcher `startup`, quindi esce senza avviare una conversazione.1328Quando esegui `claude --init-only`, Claude Code esegue gli hook Setup e gli hook `SessionStart` con il matcher `startup`, poi esce senza avviare una conversazione.
1329 1329
1330Quando avvii o continui una conversazione con `-p`, devi anche fornire un prompt, come argomento o tramite pipe su stdin. Puoi saltare il prompt quando un hook `SessionStart` fornisce [`initialUserMessage`](#sessionstart-decision-control) o quando riprendi una sessione con una [chiamata di tool differita](#defer-a-tool-call-for-later).1330Quando 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).
1331 1331
1332Al successo, `--init-only` non stampa nulla al terminale. Per confermare che gli hook si sono eseguiti, avvia con `claude --debug-file <path> --init-only`, sostituendo `<path>` con una posizione di file di log, e controlla il log per le voci degli hook Setup e SessionStart.1332In 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.
1333 1333
1334Poiché Setup non si esegue ad ogni lancio, un plugin che ha bisogno di una dipendenza installata non può fare affidamento solo su Setup. Il modello pratico è controllare la dipendenza al primo utilizzo e installare se assente, ad esempio un hook o una skill che testa per `${CLAUDE_PLUGIN_DATA}/node_modules` ed esegue `npm install` se assente. Vedi la [directory di dati persistenti](/docs/it/plugins/components#path-variables-and-persistent-data) per dove archiviare le dipendenze installate. Se distribuisci il tuo plugin tramite un marketplace, potresti non aver bisogno di questo modello: Claude Code [installa automaticamente le dipendenze del pacchetto Node.js idonee](/docs/it/plugins/loading#node-js-package-dependencies) quando memorizza il plugin nella cache.1334Poiché 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.
1335 1335
1336<h4 id="setup-input">1336<h4 id="setup-input">
1337 Input Setup1337 Input di Setup
1338</h4>1338</h4>
1339 1339
1340Oltre ai [campi di input comuni](#common-input-fields), gli hook Setup ricevono un campo `trigger` impostato su `"init"` o `"maintenance"`:1340Oltre ai [campi di input comuni](#common-input-fields), gli hook Setup ricevono un campo `trigger` impostato su `"init"` o `"maintenance"`:
1350```1350```
1351 1351
1352<h4 id="setup-decision-control">1352<h4 id="setup-decision-control">
1353 Controllo decisionale Setup1353 Controllo delle decisioni di Setup
1354</h4>1354</h4>
1355 1355
1356Gli hook Setup non possono bloccare; l'esecuzione continua su qualsiasi codice di uscita. Su 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, stderr e il codice di uscita di un hook Setup appaiono nell'output dell'esecuzione solo come [`hook_response` events](/docs/it/headless#read-session-metadata) quando avvii con `--output-format stream-json --verbose`.1356Gli 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`.
1357 1357
1358Gli hook Setup hanno accesso a `CLAUDE_ENV_FILE`. Le variabili scritte in quel file persistono nei comandi Bash successivi per la sessione, proprio come negli [hook SessionStart](#persist-environment-variables). Solo gli hook `type: "command"` si eseguono su `Setup`. Un hook `type: "mcp_tool"` su `Setup` viene sempre saltato, come descritto sotto [MCP tool hook fields](#mcp-tool-hook-fields).1358Gli hook Setup hanno accesso a `CLAUDE_ENV_FILE`. Le variabili scritte in quel file persistono nei successivi comandi Bash della sessione, esattamente 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).
1359 1359
1360<h3 id="instructionsloaded">1360<h3 id="instructionsloaded">
1361 InstructionsLoaded1361 InstructionsLoaded
1362</h3>1362</h3>
1363 1363
1364Si esegue quando un file `CLAUDE.md` o `.claude/rules/*.md` viene caricato nel contesto. Questo evento si esegue all'avvio della sessione per i file caricati con entusiasmo e di nuovo più tardi quando i file vengono caricati pigrizia, 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 o il controllo decisionale. Si esegue in modo asincrono per scopi di osservabilità.1364Si 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à.
1365 1365
1366Questo evento non si esegue quando Claude [legge `AGENTS.md` direttamente](/docs/it/memory#agents-md) tramite l'impostazione **Project instructions**. Si esegue 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 symlink ad esso, come un caricamento `CLAUDE.md` normale.1366Questo 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`.
1367 1367
1368Il matcher viene eseguito su `load_reason`. Ad esempio, usa `"matcher": "session_start"` per eseguire solo per i file caricati all'avvio della sessione, o `"matcher": "path_glob_match|nested_traversal"` per eseguire solo per i caricamenti pigri.1368Il 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.
1369 1369
1370<h4 id="instructionsloaded-input">1370<h4 id="instructionsloaded-input">
1371 Input InstructionsLoaded1371 Input di InstructionsLoaded
1372</h4>1372</h4>
1373 1373
1374Oltre ai [campi di input comuni](#common-input-fields), gli hook InstructionsLoaded ricevono questi campi:1374Oltre ai [campi di input comuni](#common-input-fields), gli hook InstructionsLoaded ricevono questi campi:
1375 1375
1376| Campo | Descrizione |1376| Campo | Descrizione |
1377| :- | :- |1377| :- | :- |
1378| `file_path` | Percorso assoluto al file di istruzioni che è stato caricato |1378| `file_path` | Percorso assoluto del file di istruzioni che è stato caricato |
1379| `memory_type` | Ambito del file: `"User"`, `"Project"`, `"Local"`, o `"Managed"` |1379| `memory_type` | Ambito del file: `"User"`, `"Project"`, `"Local"` o `"Managed"` |
1380| `load_reason` | Perché il file è stato caricato: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"`, o `"compact"`. Il valore `"compact"` si esegue quando i file di istruzioni vengono ricaricati dopo un evento di compattazione |1380| `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 |
1381| `globs` | Modelli di glob di percorso dal frontmatter `paths:` del file, se presenti. Presente solo per i caricamenti `path_glob_match` |1381| `globs` | Pattern glob di percorso dal frontmatter `paths:` del file, se presenti. Presente solo per i caricamenti `path_glob_match` |
1382| `trigger_file_path` | Percorso al file il cui accesso ha attivato questo caricamento, per i caricamenti pigri |1382| `trigger_file_path` | Percorso del file il cui accesso ha attivato questo caricamento, per i caricamenti differiti |
1383| `parent_file_path` | Percorso al file di istruzioni genitore che ha incluso questo, per i caricamenti `include` |1383| `parent_file_path` | Percorso del file di istruzioni padre che ha incluso questo, per i caricamenti `include` |
1384 1384
1385```json theme={null}1385```json theme={null}
1386{1386{
1395```1395```
1396 1396
1397<h4 id="instructionsloaded-decision-control">1397<h4 id="instructionsloaded-decision-control">
1398 Controllo decisionale InstructionsLoaded1398 Controllo delle decisioni di InstructionsLoaded
1399</h4>1399</h4>
1400 1400
1401Gli hook InstructionsLoaded non hanno controllo decisionale. Non possono bloccare o 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 tracciamento della conformità, o l'osservabilità.1401Gli 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à.
1402 1402
1403<h3 id="userpromptsubmit">1403<h3 id="userpromptsubmit">
1404 UserPromptSubmit1404 UserPromptSubmit
1405</h3>1405</h3>
1406 1406
1407Si esegue quando l'utente invia un prompt, prima che Claude lo elabori. Questo ti consente di aggiungere contesto aggiuntivo basato sul prompt/conversazione, convalidare i prompt, o bloccare determinati tipi di prompt.1407Viene eseguito quando l'utente invia un prompt, prima che Claude lo elabori. Questo ti permette
1408di aggiungere contesto aggiuntivo in base al prompt/alla conversazione, convalidare i prompt o
1409bloccare determinati tipi di prompt.
1408 1410
1409Gli 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 quei tipi sulla maggior parte degli altri eventi. Poiché questo hook si esegue prima di ogni prompt e blocca l'elaborazione del modello finché non completa, un hook bloccato blocca la sessione. Se il tuo hook ha bisogno di più tempo, imposta il campo `timeout` nella voce dell'hook.1411Gli 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.
1410 1412
1411A parte un hook di comando che esegui con [`async: true`](#run-hooks-in-the-background), un hook `UserPromptSubmit` di comando, HTTP, o MCP tool 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 nomina l'hook, il timeout che si è attivato, e che l'output è stato scartato.1413Fatta 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.
1412 1414
1413Un [hook di callback Agent SDK](/docs/it/agent-sdk/hooks) su `UserPromptSubmit` che raggiunge il suo timeout blocca il prompt con un messaggio che nomina l'hook e il timeout, perché un callback lì può agire come un gate di policy che non deve fallire aperto. La sessione continua. Prima della v2.1.208, un timeout di callback su quell'evento terminava il turno con un errore di esecuzione.1415Un [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.
1414 1416
1415<h4 id="userpromptsubmit-input">1417<h4 id="userpromptsubmit-input">
1416 Input UserPromptSubmit1418 Input di UserPromptSubmit
1417</h4>1419</h4>
1418 1420
1419Oltre ai [campi di input comuni](#common-input-fields), gli hook UserPromptSubmit ricevono il campo `prompt` contenente il testo che l'utente ha inviato. Il contenuto incollato che è crollato 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.1421Oltre ai [campi di input comuni](#common-input-fields), gli hook UserPromptSubmit ricevono il campo `prompt` contenente il testo inviato dall'utente. 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.
1420 1422
1421Gli hook UserPromptSubmit ricevono anche `session_title` quando la sessione ha un titolo personalizzato, con lo stesso significato del [campo SessionStart `session_title`](#sessionstart-input).1423Gli 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).
1422 1424
1423```json theme={null}1425```json theme={null}
1424{1426{
1432```1434```
1433 1435
1434<h4 id="userpromptsubmit-decision-control">1436<h4 id="userpromptsubmit-decision-control">
1435 Controllo decisionale UserPromptSubmit1437 Controllo delle decisioni di UserPromptSubmit
1436</h4>1438</h4>
1437 1439
1438Gli hook `UserPromptSubmit` possono controllare se un prompt utente viene elaborato e aggiungere contesto. Tutti i [campi di output JSON](#json-output) sono disponibili.1440Gli hook `UserPromptSubmit` possono controllare se un prompt dell'utente viene elaborato e aggiungere contesto. Sono disponibili tutti i [campi di output JSON](#json-output).
1439 1441
1440Ci sono due modi per aggiungere contesto alla conversazione all'uscita del codice 0:1442Ci sono due modi per aggiungere contesto alla conversazione con codice di uscita 0:
1441 1443
1442* **Stdout di testo semplice**: Claude Code aggiunge stdout che [tratta come testo semplice](#exit-code-0) al contesto di Claude1444* **Stdout in testo semplice**: Claude Code aggiunge al contesto di Claude lo stdout che [tratta come testo semplice](#exit-code-0)
1443* **JSON con `additionalContext`**: usa il formato JSON sottostante per più controllo. Il campo `additionalContext` viene aggiunto come contesto1445* **JSON con `additionalContext`**: usa il formato JSON seguente per un maggiore controllo. Il campo `additionalContext` viene aggiunto come contesto
1444 1446
1445Nessuno dei due canali produce una voce di trascrizione visibile. Lo stdout semplice e il valore `additionalContext` vengono ciascuno iniettati come un promemoria di sistema che inizia con il nome dell'hook; Claude legge entrambi. Per confermare la consegna, controlla il [debug log](#debug-hooks).1447Nessuno 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).
1446 1448
1447Per bloccare un prompt, restituisci un oggetto JSON con `decision` impostato su `"block"`:1449Per bloccare un prompt, restituisci un oggetto JSON con `decision` impostato su `"block"`:
1448 1450
1449| Campo | Descrizione |1451| Campo | Descrizione |
1450| :- | :- |1452| :- | :- |
1451| `decision` | `"block"` ferma il prompt prima che raggiunga Claude. Ometti per consentire al prompt di procedere |1453| `decision` | `"block"` ferma il prompt prima che raggiunga Claude. Omettilo per consentire al prompt di procedere |
1452| `reason` | Mostrato all'utente quando `decision` è `"block"`. Non aggiunto al contesto |1454| `reason` | Mostrato all'utente quando `decision` è `"block"`. Non viene aggiunto al contesto |
1453| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt inviato. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |1455| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt inviato. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |
1454| `sessionTitle` | Imposta il titolo della sessione. Usa per nominare le sessioni automaticamente in base al contenuto del prompt |1456| `sessionTitle` | Imposta il titolo della sessione. Usalo per dare automaticamente un nome alle sessioni in base al contenuto del prompt |
1455| `suppressOriginalPrompt` | Se `true` quando l'hook blocca il prompt, lascia il testo del prompt fuori dal messaggio di blocco. Vedi [Cosa lascia dietro un prompt bloccato](#what-a-blocked-prompt-leaves-behind) |1457| `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) |
1456 1458
1457Un hook che blocca uscendo con 2 si instrada allo stesso modo di `reason`: il messaggio di blocco mostra il testo stderr all'utente, e non viene aggiunto al contesto.1459Un 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.
1458 1460
1459```json theme={null}1461```json theme={null}
1460{1462{
1470```1472```
1471 1473
1472<h4 id="what-a-blocked-prompt-leaves-behind">1474<h4 id="what-a-blocked-prompt-leaves-behind">
1473 Cosa lascia dietro un prompt bloccato1475 Cosa lascia un prompt bloccato
1474</h4>1476</h4>
1475 1477
1476Un 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 lasciare il testo fuori dal messaggio, stampa JSON con `"suppressOriginalPrompt": true` dentro `hookSpecificOutput`. Questo funziona se l'hook blocca con `decision: "block"` o uscendo con 2. Un hook di uscita-2 che non stampa JSON ottiene sempre il testo del prompt nel suo messaggio di blocco.1478Un 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 terminando con 2. Un hook con uscita 2 che non stampa JSON riceve sempre il testo del prompt nel suo messaggio di blocco.
1477 1479
1478`suppressOriginalPrompt` cambia solo il messaggio di blocco. Il testo inviato può ancora apparire in file locali come la trascrizione della sessione e la tua cronologia dei prompt, quindi un hook di blocco non è un modo per mantenere un segreto fuori dal disco. Per limitare o rimuovere quei file, vedi [Plaintext storage](/docs/it/claude-directory#plaintext-storage) e [Clear local data](/docs/it/claude-directory#clear-local-data).1480`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).
1479 1481
1480<h3 id="userpromptexpansion">1482<h3 id="userpromptexpansion">
1481 UserPromptExpansion1483 UserPromptExpansion
1482</h3>1484</h3>
1483 1485
1484Si esegue quando un comando digitato dall'utente si espande in un prompt prima di raggiungere Claude. Usa questo per bloccare comandi specifici dall'invocazione diretta, iniettare contesto per una skill particolare, o registrare quali comandi gli utenti invocano. Ad esempio, un hook che corrisponde a `deploy` può bloccare `/deploy` a meno che un file di approvazione non sia presente, o un hook che corrisponde a una skill di revisione può aggiungere la lista di controllo di revisione del team come `additionalContext`.1486Viene 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`.
1485 1487
1486Questo evento copre il percorso che `PreToolUse` non copre: un hook `PreToolUse` che corrisponde allo strumento `Skill` si esegue solo quando Claude chiama lo strumento, ma digitare `/skillname` direttamente bypassa `PreToolUse`. `UserPromptExpansion` si esegue su quel percorso diretto.1488Questo 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.
1487 1489
1488Corrisponde su `command_name`. Lascia il matcher vuoto per eseguire su ogni comando di tipo prompt.1490Effettua la corrispondenza su `command_name`. Lascia vuoto il matcher per attivarlo su ogni comando di tipo prompt.
1489 1491
1490<h4 id="userpromptexpansion-input">1492<h4 id="userpromptexpansion-input">
1491 Input UserPromptExpansion1493 Input di UserPromptExpansion
1492</h4>1494</h4>
1493 1495
1494Oltre ai [campi di input comuni](#common-input-fields), gli hook UserPromptExpansion ricevono `expansion_type`, `command_name`, `command_args`, `command_source`, e la stringa `prompt` originale. Il campo `expansion_type` è `slash_command` per skill e comandi personalizzati, o `mcp_prompt` per i prompt del server MCP.1496Oltre ai [campi di input comuni](#common-input-fields), gli hook UserPromptExpansion ricevono `expansion_type`, `command_name`, `command_args`, `command_source` e la stringa `prompt` originale. Il campo `expansion_type` è `slash_command` per le skill e i comandi personalizzati, oppure `mcp_prompt` per i prompt dei server MCP.
1495 1497
1496```json theme={null}1498```json theme={null}
1497{1499{
1509```1511```
1510 1512
1511<h4 id="userpromptexpansion-decision-control">1513<h4 id="userpromptexpansion-decision-control">
1512 Controllo decisionale UserPromptExpansion1514 Controllo delle decisioni di UserPromptExpansion
1513</h4>1515</h4>
1514 1516
1515Gli hook `UserPromptExpansion` possono bloccare l'espansione o aggiungere contesto. Tutti i [campi di output JSON](#json-output) sono disponibili.1517Gli hook `UserPromptExpansion` possono bloccare l'espansione o aggiungere contesto. Sono disponibili tutti i [campi di output JSON](#json-output).
1516 1518
1517| Campo | Descrizione |1519| Campo | Descrizione |
1518| :- | :- |1520| :- | :- |
1519| `decision` | `"block"` impedisce al comando di espandersi. Ometti per consentirgli di procedere |1521| `decision` | `"block"` impedisce l'espansione del comando. Omettilo per consentirgli di procedere |
1520| `reason` | Mostrato all'utente quando `decision` è `"block"` |1522| `reason` | Mostrato all'utente quando `decision` è `"block"` |
1521| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt espanso. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |1523| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt espanso. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |
1522 1524
1523Un hook che blocca uscendo con 2 si instrada allo stesso modo di `reason`: il messaggio di blocco mostra il testo stderr all'utente.1525Un hook che blocca terminando con 2 segue lo stesso percorso di `reason`: il messaggio di blocco mostra il testo di stderr all'utente.
1524 1526
1525```json theme={null}1527```json theme={null}
1526{1528{
1537 MessageDisplay1539 MessageDisplay
1538</h3>1540</h3>
1539 1541
1540Si esegue mentre un messaggio dell'assistente scorre sullo schermo. Claude Code visualizza il messaggio in incrementi: ogni volta che un batch di righe appena completate è pronto per il rendering, l'hook si esegue una volta con quelle righe e Claude Code esegue il rendering del testo di sostituzione dell'hook al loro posto. Un messaggio lungo produce diverse chiamate; un messaggio breve può produrne solo una.1542Viene 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.
1541 1543
1542Usa MessageDisplay per:1544Usa MessageDisplay per:
1543 1545
1544* rimuovere markdown per una visualizzazione minima1546* rimuovere il markdown per una visualizzazione minimale
1545* trasformare il testo che un'applicazione Agent SDK mostra ai suoi utenti1547* trasformare il testo che un'applicazione Agent SDK mostra ai suoi utenti
1546* redarre chiavi API o nomi host interni dalle risposte di Claude1548* oscurare chiavi API o nomi host interni dalle risposte di Claude
1547 1549
1548Claude Code tiene ogni batch finché il tuo hook non ritorna, quindi mantieni l'hook veloce. Se l'hook fallisce o scade, Claude Code visualizza il testo originale. Il timeout predefinito per questo evento è 10 secondi; se il tuo hook ha bisogno di più tempo, imposta il campo `timeout` nella voce dell'hook.1550Claude 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.
1549 1551
1550MessageDisplay è solo visualizzazione: il testo di sostituzione cambia solo ciò che viene renderizzato sullo schermo. La trascrizione e ciò che Claude vede mantengono il testo originale, quindi Claude non vede mai la sostituzione, e la modalità verbose mostra l'originale. L'hook riceve solo il testo del messaggio dell'assistente, quindi i risultati degli strumenti e il testo che digiti vengono renderizzati invariati.1552MessageDisplay 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.
1551 1553
1552MessageDisplay non supporta i matcher e si esegue per ogni messaggio dell'assistente che scorre il testo; i messaggi senza testo, come le risposte solo di chiamate di strumenti, non lo attivano.1554MessageDisplay 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.
1553 1555
1554Nelle esecuzioni non interattive, incluse le query Agent SDK e `claude -p`, MessageDisplay si esegue una volta per messaggio dell'assistente invece che una volta per batch di righe. La singola chiamata arriva dopo che il messaggio completa e porta 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à.1556Nelle 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à.
1555 1557
1556<h4 id="messagedisplay-input">1558<h4 id="messagedisplay-input">
1557 Input MessageDisplay1559 Input di MessageDisplay
1558</h4>1560</h4>
1559 1561
1560Oltre ai [campi di input comuni](#common-input-fields), gli hook MessageDisplay ricevono identificatori per il turno e il messaggio, la posizione di questa chiamata all'interno del messaggio, e il nuovo testo in `delta`. I confini dei batch dipendono da come il testo scorre, quindi usa `index` e `final` per tracciare il progresso attraverso un messaggio piuttosto che aspettarsi che le righe siano raggruppate in un modo particolare.1562Oltre 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.
1561 1563
1562| Campo | Descrizione |1564| Campo | Descrizione |
1563| :- | :- |1565| :- | :- |
1564| `turn_id` | UUID del turno corrente |1566| `turn_id` | UUID del turno corrente |
1565| `message_id` | UUID del messaggio dell'assistente visualizzato. Stabile in ogni batch dello stesso messaggio. Questo non è l'ID API `msg_…`, quindi non può essere correlato con gli ID dei messaggi di trascrizione |1567| `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 |
1566| `index` | Indice a base zero di questo batch all'interno del messaggio |1568| `index` | Indice a base zero di questo gruppo all'interno del messaggio |
1567| `final` | `true` sul batch finale del messaggio. Ogni messaggio ha esattamente un batch finale |1569| `final` | `true` nell'ultimo gruppo del messaggio. Ogni messaggio ha esattamente un gruppo finale |
1568| `delta` | Le righe appena completate dalla batch precedente, incluse le newline finali. Sempre righe intere, tranne il batch finale che può terminare a metà riga. Nelle esecuzioni interattive, il delta del batch finale è vuoto quando il messaggio termina su una newline, quindi tratta `final`, non un delta non vuoto, come il segnale di fine messaggio. Nelle esecuzioni Agent SDK e `claude -p`, la singola chiamata porta l'intero messaggio |1570| `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 |
1569 1571
1570```json theme={null}1572```json theme={null}
1571{1573{
1582```1584```
1583 1585
1584<h4 id="messagedisplay-output">1586<h4 id="messagedisplay-output">
1585 Output MessageDisplay1587 Output di MessageDisplay
1586</h4>1588</h4>
1587 1589
1588Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, gli hook MessageDisplay possono restituire `displayContent` per sostituire il delta sullo schermo:1590Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, gli hook MessageDisplay possono restituire `displayContent` per sostituire il delta sullo schermo:
1591| :- | :- |1593| :- | :- |
1592| `displayContent` | Testo visualizzato al posto del delta. Omettilo per visualizzare l'originale |1594| `displayContent` | Testo visualizzato al posto del delta. Omettilo per visualizzare l'originale |
1593 1595
1594Gli hook MessageDisplay non hanno controllo decisionale. Non possono bloccare il messaggio o cambiare ciò che viene archiviato nella trascrizione o inviato a Claude. Claude Code agisce su `displayContent` dal loro output JSON e scarta `systemMessage` e `continue`.1596Gli hook MessageDisplay non hanno controllo delle decisioni. Non possono bloccare il messaggio né modificare ciò che viene archiviato nella trascrizione o inviato a Claude. Claude Code agisce su `displayContent` dal loro output JSON e scarta `systemMessage` e `continue`.
1595 1597
1596Questo esempio rimuove la formattazione markdown dalle risposte di Claude per una visualizzazione di testo semplice. Lo script legge ogni batch da stdin, rimuove i marcatori di grassetto e i backtick di codice inline da `delta`, e restituisce il risultato come `displayContent`.1598Questo esempio rimuove la formattazione markdown dalle risposte di Claude per una visualizzazione in testo semplice. Lo script legge ogni gruppo da stdin, rimuove da `delta` i marcatori del grassetto e i backtick del codice inline, e restituisce il risultato come `displayContent`.
1597 1599
1598<Tabs>1600<Tabs>
1599 <Tab title="macOS/Linux">1601 <Tab title="macOS/Linux">
1652 }1654 }
1653 ```1655 ```
1654 1656
1655 Il flag `-NoProfile` salta il caricamento del tuo profilo PowerShell in modo che l'hook si avvii velocemente, e `-ExecutionPolicy Bypass` consente a PowerShell di eseguire il file di script locale.1657 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.
1656 1658
1657 Salva questo script in `.claude/hooks/plain-display.ps1` nel tuo progetto:1659 Salva questo script in `.claude/hooks/plain-display.ps1` nel tuo progetto:
1658 1660
1669 </Tab>1671 </Tab>
1670</Tabs>1672</Tabs>
1671 1673
1672I batch senza markdown passano invariati. Se lo script fallisce, ad esempio perché `jq` manca, Claude Code visualizza il testo originale e nota il fallimento solo nell'[output di debug](#debug-hooks), non nella sessione.1674I 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.
1673 1675
1674<h3 id="pretooluse">1676<h3 id="pretooluse">
1675 PreToolUse1677 PreToolUse
1676</h3>1678</h3>
1677 1679
1678Si esegue dopo che Claude crea i parametri dello strumento e prima di elaborare la chiamata dello strumento. Corrisponde a qualsiasi nome di strumento tranne `EndConversation`: strumenti incorporati come `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion`, e `ExitPlanMode`, e qualsiasi [nome di strumento MCP](#match-mcp-tools).1680Viene 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).
1679 1681
1680Per eseguire un hook quando un file specifico cambia su disco, qualunque cosa lo abbia scritto, usa [FileChanged](#filechanged) invece di corrispondere ai file-editing tools per nome. A differenza di PreToolUse, Claude Code esegue gli hook FileChanged dopo il cambio, e non hanno controllo decisionale, quindi non possono bloccare la scrittura.1682Per 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.
1681 1683
1682<Warning>1684<Warning>
1683 PreToolUse si esegue solo quando Claude chiama uno strumento. I file che [riferisci con `@` nel tuo prompt](/docs/it/common-workflows#reference-files-and-directories) vengono aggiunti senza alcuna chiamata di strumento: Claude Code inserisce i loro contenuti mentre costruisce il prompt, quindi nessun hook PreToolUse si esegue per loro, inclusi gli hook che corrispondono a `Read`. Per bloccare percorsi specifici dai riferimenti `@`, usa una [regola di negazione `Read`](/docs/it/permissions#read-and-edit) invece.1685 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).
1684 1686
1685 PreToolUse inoltre non si esegue per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).1687 PreToolUse inoltre non si attiva per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).
1686</Warning>1688</Warning>
1687 1689
1688Usa [Controllo decisionale PreToolUse](#pretooluse-decision-control) per consentire, negare, chiedere, o differire la chiamata dello strumento.1690Usa il [controllo delle decisioni di PreToolUse](#pretooluse-decision-control) per consentire, negare, chiedere o differire la chiamata allo strumento.
1689 1691
1690Un [hook di callback Agent SDK](/docs/it/agent-sdk/hooks) su `PreToolUse` che supera il suo timeout blocca la chiamata dello strumento, e Claude riceve un risultato di errore che nomina il timeout. Un'esplicita negazione restituita da un altro hook ha ancora la precedenza.1692Un [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.
1691 1693
1692<h4 id="pretooluse-input">1694<h4 id="pretooluse-input">
1693 Input PreToolUse1695 Input di PreToolUse
1694</h4>1696</h4>
1695 1697
1696Oltre ai [campi di input comuni](#common-input-fields), gli hook PreToolUse ricevono `tool_name`, `tool_input`, e `tool_use_id`.1698Oltre ai [campi di input comuni](#common-input-fields), gli hook PreToolUse ricevono `tool_name`, `tool_input` e `tool_use_id`.
1697 1699
1698Per uno [strumento MCP](#match-mcp-tools), l'input porta anche `mcp_server`, un oggetto con il `name` del server e una `source` che dice da dove viene la definizione del server. I valori `source` includono `plugin`, `sdk`, e ambiti di configurazione come `user` e `project`. [`McpServerProvenance`](/docs/it/agent-sdk/typescript#mcpserverprovenance) nel riferimento Agent SDK li elenca tutti e dice come trattarne uno che non riconosci. Basa le decisioni di fiducia su `source` piuttosto che su `name` o il prefisso del nome dello strumento `mcp__<server>__`. Il campo `mcp_server` richiede Claude Code v2.1.274 o successivo.1700Per 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.
1699 1701
1700Per gli strumenti di file `Write`, `Edit`, e `Read`, `tool_input.file_path` è sempre assoluto:1702Per gli strumenti sui file `Write`, `Edit` e `Read`, `tool_input.file_path` è sempre assoluto:
1701 1703
1702* Claude Code espande `~` e i percorsi relativi prima che gli hook si eseguano, quindi un hook che corrisponde ai percorsi non può essere bypassato tramite `~` o un'ortografia relativa dello stesso percorso1704* 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 percorso
1703* Su Windows, il percorso arriva con separatori backslash, anche quando il tuo hook si esegue sotto Git Bash dove `$PWD` sembra `/c/project`1705* Su Windows, il percorso arriva con separatori backslash, anche quando il tuo hook viene eseguito in Git Bash dove `$PWD` appare come `/c/project`
1704* Un confronto scritto con barre in avanti, come un controllo `/src/`, non corrisponde mai a un percorso backslash, e la chiamata dello strumento procede come se l'hook non avesse nulla da bloccare1706* 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 bloccare
1705* Normalizza i separatori prima di confrontare: `FILE_PATH="${FILE_PATH//\\//}"` in Bash, o `file_path.replace("\\", "/")` in Python, quindi corrisponde a un segmento di percorso come `/src/` piuttosto che ancorare con `^`, poiché il percorso è assoluto1707* 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 è assoluto
1706 1708
1707Una chiamata `Write` su Windows consegna:1709Una chiamata `Write` su Windows fornisce:
1708 1710
1709```json theme={null}1711```json theme={null}
1710{1712{
1718}1720}
1719```1721```
1720 1722
1721I campi `tool_input` dipendono dallo strumento:1723I campi di `tool_input` dipendono dallo strumento:
1722 1724
1723<a id="bash" />1725<a id="bash" />
1724 1726
1731| Campo | Tipo | Esempio | Descrizione |1733| Campo | Tipo | Esempio | Descrizione |
1732| :- | :- | :- | :- |1734| :- | :- | :- | :- |
1733| `command` | string | `"npm test"` | Il comando shell da eseguire |1735| `command` | string | `"npm test"` | Il comando shell da eseguire |
1734| `description` | string | `"Run test suite"` | Descrizione facoltativa di cosa fa il comando |1736| `description` | string | `"Run test suite"` | Descrizione facoltativa di ciò che fa il comando |
1735| `timeout` | number | `120000` | Timeout facoltativo in millisecondi. I valori superiori al [massimo](/docs/it/tools-reference#bash-tool-behavior) vengono ridotti al massimo piuttosto che rifiutati |1737| `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 |
1736| `run_in_background` | boolean | `false` | Se eseguire il comando in background |1738| `run_in_background` | boolean | `false` | Se eseguire il comando in background |
1737 1739
1738Quando un comando Bash cambia i file in un repository Git, Claude Code può registrare cosa è cambiato. Registra i cambiamenti in ogni modalità di permesso quando l'impostazione [`bashEditDiffEnabled`](/docs/it/settings-reference#basheditdiffenabled) attiva la registrazione; la voce di quell'impostazione dice quali file possono impostarla. Altrimenti la registra solo in modalità auto e modalità `bypassPermissions`, e solo quando Claude Code dirige Claude a modificare i file tramite Bash. Imposta `bashEditDiffEnabled` su `false` per disattivare la registrazione. I comandi di background e i comandi di sola lettura non portano alcun diff.1740Quando 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.
1739 1741
1740Il tuo [hook PostToolUse](#posttooluse) riceve quindi i file modificati in `tool_response.bashEditDiff`. L'elenco copre ciò che è cambiato sotto il repository mentre il comando era in esecuzione. I file che Git ignora e i file nei submoduli non sono elencati. Richiede Claude Code v2.1.269 o successivo.1742Il 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.
1741 1743
1742<Note>1744<Note>
1743 L'elenco è best effort e in beta pubblica. Claude Code può perdere un cambio, includere un file che un altro processo ha cambiato nello stesso momento, o fermarsi ai suoi limiti di dimensione. La forma del campo può cambiare. Usa l'elenco per trovare cosa rivedere, non per applicare una policy.1745 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.
1744</Note>1746</Note>
1745 1747
1746`changedFiles` e `files` elencano ciò che il comando ha cambiato; i campi rimanenti dicono quanto è completo e quanto è affidabile quell'elenco.1748`changedFiles` e `files` elencano ciò che il comando ha modificato; i campi rimanenti indicano quanto è completo e quanto è affidabile quell'elenco.
1747 1749
1748| Campo | Tipo | Esempio | Descrizione |1750| Campo | Tipo | Esempio | Descrizione |
1749| :- | :- | :- | :- |1751| :- | :- | :- | :- |
1750| `changedFiles` | array | `["/path/to/src/app.ts"]` | Percorsi assoluti dei file che il comando ha cambiato, al massimo 200. Presente ogni volta che `files` contiene un diff o `moreFiles` è superiore a zero |1752| `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 |
1751| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | Diff di fino a 5 file modificati, per la visualizzazione. `created` o `deleted` è `true` per un file che il comando ha aggiunto o rimosso |1753| `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 |
1752| `moreFiles` | number | `2` | Conteggio dei file modificati senza diff in `files` |1754| `moreFiles` | number | `2` | Numero di file modificati senza diff in `files` |
1753| `unavailable` | boolean | `true` | Impostato quando il diff è incompleto o non poteva essere preso |1755| `unavailable` | boolean | `true` | Impostato quando il diff è incompleto o non è stato possibile ottenerlo |
1754| `skipped` | boolean | `true` | Impostato per un comando Git che sposta l'albero di lavoro, come `git checkout` o `git stash`, quindi Claude Code non prende alcun diff |1756| `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 |
1755| `shared` | boolean | `true` | Impostato quando un'altra chiamata di strumento Bash, come quella di un subagente, si è eseguita nello stesso repository nello stesso momento, quindi alcuni cambiamenti elencati possono essere di quel comando |1757| `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 |
1756 1758
1757<a id="powershell" />1759<a id="powershell" />
1758 1760
1760 PowerShell1762 PowerShell
1761</h5>1763</h5>
1762 1764
1763Esegue comandi PowerShell. Vedi lo [strumento PowerShell](/docs/it/tools-reference#powershell-tool) per la disponibilità per piattaforma.1765Esegue comandi PowerShell. Consulta lo [strumento PowerShell](/docs/it/tools-reference#powershell-tool) per la disponibilità per piattaforma.
1764 1766
1765I campi corrispondono allo strumento Bash, con la stringa di comando in `command`:1767I campi corrispondono a quelli dello strumento Bash, con la stringa del comando in `command`:
1766 1768
1767| Campo | Tipo | Esempio | Descrizione |1769| Campo | Tipo | Esempio | Descrizione |
1768| :- | :- | :- | :- |1770| :- | :- | :- | :- |
1769| `command` | string | `"Get-ChildItem -Recurse"` | Il comando PowerShell da eseguire |1771| `command` | string | `"Get-ChildItem -Recurse"` | Il comando PowerShell da eseguire |
1770| `description` | string | `"List files recursively"` | Descrizione facoltativa di cosa fa il comando |1772| `description` | string | `"List files recursively"` | Descrizione facoltativa di ciò che fa il comando |
1771| `timeout` | number | `120000` | Timeout facoltativo in millisecondi |1773| `timeout` | number | `120000` | Timeout facoltativo in millisecondi |
1772| `run_in_background` | boolean | `false` | Se eseguire il comando in background |1774| `run_in_background` | boolean | `false` | Se eseguire il comando in background |
1773 1775
1774Corrisponde a `Bash|PowerShell` negli hook che ispezionano i comandi shell, quindi coprono entrambi gli strumenti:1776Usa `Bash|PowerShell` come corrispondenza negli hook che ispezionano i comandi shell, così coprono entrambi gli strumenti:
1775 1777
1776* Su Windows, ovunque lo strumento PowerShell sia abilitato, Claude tratta PowerShell come la shell primaria e instrada i comandi shell attraverso di esso.1778* Su Windows, ovunque lo strumento PowerShell sia abilitato, Claude tratta PowerShell come shell principale e vi instrada i comandi shell.
1777* Su Windows senza Git Bash, lo strumento è abilitato automaticamente e Claude Code non registra affatto lo strumento Bash.1779* Su Windows senza Git Bash, lo strumento è abilitato automaticamente e Claude Code non registra affatto lo strumento Bash.
1778* Un hook che corrisponde solo a `Bash` non si esegue mai lì.1780* Un hook che corrisponde solo a `Bash` non si attiva mai in quel caso.
1779 1781
1780<h5 id="write">1782<h5 id="write">
1781 Write1783 Write
1785 1787
1786| Campo | Tipo | Esempio | Descrizione |1788| Campo | Tipo | Esempio | Descrizione |
1787| :- | :- | :- | :- |1789| :- | :- | :- | :- |
1788| `file_path` | string | `"/path/to/file.txt"` | Percorso assoluto al file da scrivere |1790| `file_path` | string | `"/path/to/file.txt"` | Percorso assoluto del file da scrivere |
1789| `content` | string | `"file content"` | Contenuto da scrivere nel file |1791| `content` | string | `"file content"` | Contenuto da scrivere nel file |
1790 1792
1791<h5 id="edit">1793<h5 id="edit">
1796 1798
1797| Campo | Tipo | Esempio | Descrizione |1799| Campo | Tipo | Esempio | Descrizione |
1798| :- | :- | :- | :- |1800| :- | :- | :- | :- |
1799| `file_path` | string | `"/path/to/file.txt"` | Percorso assoluto al file da modificare |1801| `file_path` | string | `"/path/to/file.txt"` | Percorso assoluto del file da modificare |
1800| `old_string` | string | `"original text"` | Testo da trovare e sostituire |1802| `old_string` | string | `"original text"` | Testo da trovare e sostituire |
1801| `new_string` | string | `"replacement text"` | Testo di sostituzione |1803| `new_string` | string | `"replacement text"` | Testo sostitutivo |
1802| `replace_all` | boolean | `false` | Se sostituire tutte le occorrenze |1804| `replace_all` | boolean | `false` | Se sostituire tutte le occorrenze |
1803 1805
1804<h5 id="read">1806<h5 id="read">
1805 Read1807 Read
1806</h5>1808</h5>
1807 1809
1808Legge i contenuti del file.1810Legge il contenuto dei file.
1809 1811
1810| Campo | Tipo | Esempio | Descrizione |1812| Campo | Tipo | Esempio | Descrizione |
1811| :- | :- | :- | :- |1813| :- | :- | :- | :- |
1812| `file_path` | string | `"/path/to/file.txt"` | Percorso assoluto al file da leggere |1814| `file_path` | string | `"/path/to/file.txt"` | Percorso assoluto del file da leggere |
1813| `offset` | number | `10` | Numero di riga facoltativo da cui iniziare la lettura |1815| `offset` | number | `10` | Numero di riga facoltativo da cui iniziare la lettura |
1814| `limit` | number | `50` | Numero facoltativo di righe da leggere |1816| `limit` | number | `50` | Numero facoltativo di righe da leggere |
1815 1817
1817 Glob1819 Glob
1818</h5>1820</h5>
1819 1821
1820Trova file che corrispondono a un modello glob.1822Trova i file che corrispondono a un pattern glob.
1821 1823
1822| Campo | Tipo | Esempio | Descrizione |1824| Campo | Tipo | Esempio | Descrizione |
1823| :- | :- | :- | :- |1825| :- | :- | :- | :- |
1824| `pattern` | string | `"**/*.ts"` | Modello glob per corrispondere ai file |1826| `pattern` | string | `"**/*.ts"` | Pattern glob con cui confrontare i file |
1825| `path` | string | `"/path/to/dir"` | Directory facoltativa da cercare. Predefinito alla directory di lavoro corrente |1827| `path` | string | `"/path/to/dir"` | Directory facoltativa in cui cercare. Il valore predefinito è la directory di lavoro corrente |
1826 1828
1827<h5 id="grep">1829<h5 id="grep">
1828 Grep1830 Grep
1829</h5>1831</h5>
1830 1832
1831Cerca i contenuti dei file con espressioni regolari.1833Cerca nel contenuto dei file con espressioni regolari.
1832 1834
1833| Campo | Tipo | Esempio | Descrizione |1835| Campo | Tipo | Esempio | Descrizione |
1834| :- | :- | :- | :- |1836| :- | :- | :- | :- |
1835| `pattern` | string | `"TODO.*fix"` | Modello di espressione regolare da cercare |1837| `pattern` | string | `"TODO.*fix"` | Pattern di espressione regolare da cercare |
1836| `path` | string | `"/path/to/dir"` | File o directory facoltativo da cercare |1838| `path` | string | `"/path/to/dir"` | File o directory facoltativa in cui cercare |
1837| `glob` | string | `"*.ts"` | Modello glob facoltativo per filtrare i file |1839| `glob` | string | `"*.ts"` | Pattern glob facoltativo per filtrare i file |
1838| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"`, o `"count"`. Predefinito a `"files_with_matches"` |1840| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"` o `"count"`. Il valore predefinito è `"files_with_matches"` |
1839| `-i` | boolean | `true` | Ricerca senza distinzione tra maiuscole e minuscole |1841| `-i` | boolean | `true` | Ricerca senza distinzione tra maiuscole e minuscole |
1840| `multiline` | boolean | `false` | Abilita la corrispondenza multilinea |1842| `multiline` | boolean | `false` | Abilita la corrispondenza su più righe |
1841 1843
1842<h5 id="webfetch">1844<h5 id="webfetch">
1843 WebFetch1845 WebFetch
1844</h5>1846</h5>
1845 1847
1846Recupera ed elabora il contenuto web.1848Recupera ed elabora contenuti web.
1847 1849
1848| Campo | Tipo | Esempio | Descrizione |1850| Campo | Tipo | Esempio | Descrizione |
1849| :- | :- | :- | :- |1851| :- | :- | :- | :- |
1854 WebSearch1856 WebSearch
1855</h5>1857</h5>
1856 1858
1857Cerca il web.1859Esegue ricerche sul web.
1858 1860
1859| Campo | Tipo | Esempio | Descrizione |1861| Campo | Tipo | Esempio | Descrizione |
1860| :- | :- | :- | :- |1862| :- | :- | :- | :- |
1861| `query` | string | `"react hooks best practices"` | Query di ricerca |1863| `query` | string | `"react hooks best practices"` | Query di ricerca |
1862| `allowed_domains` | array | `["docs.example.com"]` | Facoltativo: includi solo risultati da questi domini |1864| `allowed_domains` | array | `["docs.example.com"]` | Facoltativo: include solo i risultati da questi domini |
1863| `blocked_domains` | array | `["spam.example.com"]` | Facoltativo: escludi risultati da questi domini |1865| `blocked_domains` | array | `["spam.example.com"]` | Facoltativo: esclude i risultati da questi domini |
1864 1866
1865<h5 id="agent">1867<h5 id="agent">
1866 Agent1868 Agent
1867</h5>1869</h5>
1868 1870
1869Genera un [subagente](/docs/it/sub-agents).1871Avvia un [subagent](/docs/it/sub-agents).
1870 1872
1871| Campo | Tipo | Esempio | Descrizione |1873| Campo | Tipo | Esempio | Descrizione |
1872| :- | :- | :- | :- |1874| :- | :- | :- | :- |
1873| `prompt` | string | `"Find all API endpoints"` | L'attività per l'agente da eseguire |1875| `prompt` | string | `"Find all API endpoints"` | L'attività che l'agente deve svolgere |
1874| `description` | string | `"Find API endpoints"` | Breve descrizione dell'attività |1876| `description` | string | `"Find API endpoints"` | Breve descrizione dell'attività |
1875| `subagent_type` | string | `"Explore"` | Tipo di agente specializzato da usare |1877| `subagent_type` | string | `"Explore"` | Tipo di agente specializzato da usare |
1876| `model` | string | `"sonnet"` | Alias di modello facoltativo per sovrascrivere il predefinito |1878| `model` | string | `"sonnet"` | Alias di modello facoltativo per sovrascrivere quello predefinito |
1877 1879
1878Quando una chiamata Agent in primo piano completa, il tuo [hook PostToolUse](#posttooluse) riceve il risultato del subagente e la telemetria di esecuzione in `tool_response`. Leggi questi campi per ispezionare l'esecuzione; per i rollup di token e costo tra i subagenti, usa i [contatori di token e costo](/docs/it/monitoring-usage#token-counter) filtrati a `query_source` `"subagent"`, poiché `totalTokens` e `usage` coprono solo la richiesta finale:1880Quando 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:
1879 1881
1880| Campo | Tipo | Esempio | Descrizione |1882| Campo | Tipo | Esempio | Descrizione |
1881| :- | :- | :- | :- |1883| :- | :- | :- | :- |
1882| `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"` |1884| `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"` |
1883| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificatore per l'esecuzione del subagente |1885| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificatore dell'esecuzione del subagent |
1884| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | I blocchi di testo finali del subagente, o, per un subagente il cui rapporto passa attraverso `SubagentHandback`, una breve nota su quel hand-back al loro posto |1886| `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 |
1885| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modello su cui il subagente ha iniziato, che può differire dal modello richiesto |1887| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modello con cui è partito il subagent, che può differire dal modello richiesto |
1886| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelli usati in ordine, con ripetizioni consecutive collassate; impostato solo quando il modello è stato scambiato a metà esecuzione. Richiede Claude Code v2.1.212 o successivo |1888| `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 |
1887| `totalTokens` | number | `12450` | Conteggio dei token dalla richiesta API finale del subagente: token di input, output, e cache combinati. Questo non è un totale su tutta l'esecuzione |1889| `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 |
1888| `totalDurationMs` | number | `48211` | Durata di tempo reale dell'esecuzione del subagente |1890| `totalDurationMs` | number | `48211` | Durata reale dell'esecuzione del subagent |
1889| `totalToolUseCount` | number | `7` | Conteggio delle chiamate di strumento che il subagente ha fatto |1891| `totalToolUseCount` | number | `7` | Numero di chiamate agli strumenti effettuate dal subagent |
1890| `usage` | object | `{"input_tokens": 8320, ...}` | Breakdown dei token per tipo della richiesta API finale: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1892| `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` |
1891 1893
1892Su Claude Code v2.1.271 o successivo, un subagente che si esegue 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 attraverso quello strumento piuttosto che restituirlo come testo. Il campo `content` del suo risultato `completed` porta quindi una breve nota su quel hand-back piuttosto che il rapporto stesso. Per leggere il rapporto, corrisponde a un hook `PreToolUse` o `PostToolUse` su `SubagentHandback` e leggi `tool_input.message`.1894Su 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`.
1893 1895
1894Per i subagenti di background, lo strumento ritorna quando l'attività si sposta in background, quindi `tool_response` non porta campi di utilizzo: un lancio di background ritorna immediatamente, e un'attività in primo piano che Claude Code sposta in background a metà esecuzione ritorna a quella transizione. Ha `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, e `resolvedModel`.1896Per 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`.
1895 1897
1896Su una risposta `completed`, `resolvedModel` nomina il modello su cui il subagente ha iniziato, che può differire dal valore `model` in `tool_input`, come quando `availableModels` o un altro override si applica. Su una risposta `async_launched`, `resolvedModel` nomina il modello in uso quando l'agente si è spostato in background, quindi uno scambio che è accaduto prima dello spostamento in background si riflette lì. `modelsUsed` e il comportamento `resolvedModel` al momento dello spostamento in background richiedono Claude Code v2.1.212 o successivo.1898In 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.
1897 1899
1898<a id="askuserquestion" />1900<a id="askuserquestion" />
1899 1901
1901 AskUserQuestion1903 AskUserQuestion
1902</h5>1904</h5>
1903 1905
1904Chiede all'utente da una a quattro domande a scelta multipla.1906Pone all'utente da una a quattro domande a scelta multipla.
1905 1907
1906| Campo | Tipo | Esempio | Descrizione |1908| Campo | Tipo | Esempio | Descrizione |
1907| :- | :- | :- | :- |1909| :- | :- | :- | :- |
1908| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Domande da presentare, ciascuna con una stringa `question`, un breve `header`, un array `options`, e un flag `multiSelect` facoltativo |1910| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Domande da presentare, ciascuna con una stringa `question`, un breve `header`, un array `options` e un flag `multiSelect` facoltativo |
1909| `answers` | object | `{"Which framework?": "React"}` | Facoltativo. Mappa il testo della domanda all'etichetta dell'opzione selezionata. Le risposte multi-selezione uniscono le etichette con virgole. Claude non imposta questo campo; forniscilo tramite `updatedInput` per rispondere programmaticamente |1911| `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 |
1910 1912
1911<h5 id="exitplanmode">1913<h5 id="exitplanmode">
1912 ExitPlanMode1914 ExitPlanMode
1913</h5>1915</h5>
1914 1916
1915Presenta un piano e chiede all'utente di approvarlo prima che Claude lasci la [modalità piano](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode). Claude scrive il piano in un file su disco prima di chiamare lo strumento, quindi il `tool_input` letterale dal modello è tipicamente vuoto. Claude Code inietta il contenuto del piano e il percorso del file prima di passare l'input agli hook.1917Presenta un piano e chiede all'utente di approvarlo prima che Claude esca dal [plan mode](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode). Claude scrive il piano in un file su disco prima di chiamare lo strumento, quindi il `tool_input` letterale del modello è in genere vuoto. Claude Code inserisce il contenuto del piano e il percorso del file prima di passare l'input agli hook.
1916 1918
1917| Campo | Tipo | Esempio | Descrizione |1919| Campo | Tipo | Esempio | Descrizione |
1918| :- | :- | :- | :- |1920| :- | :- | :- | :- |
1919| `plan` | string | `"## Refactor auth\n1. Extract..."` | Contenuto del piano in Markdown. Iniettato dal file del piano su disco |1921| `plan` | string | `"## Refactor auth\n1. Extract..."` | Contenuto del piano in Markdown. Inserito dal file del piano su disco |
1920| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Percorso al file del piano. Iniettato |1922| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Percorso del file del piano. Inserito |
1921| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Deprecato. Claude Code accetta il campo ma lo ignora. Prima della v2.1.205, portava permessi basati su prompt che Claude ha richiesto di implementare il piano |1923| `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 |
1922 1924
1923In `PostToolUse`, `tool_response` è un oggetto con campi `plan` e `filePath` che contengono il piano approvato, più flag di stato interno. Leggi `tool_response.plan` per il contenuto del piano piuttosto che rileggere il file da disco.1925In `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.
1924 1926
1925<h4 id="pretooluse-decision-control">1927<h4 id="pretooluse-decision-control">
1926 Controllo decisionale PreToolUse1928 Controllo delle decisioni di PreToolUse
1927</h4>1929</h4>
1928 1930
1929Gli hook `PreToolUse` possono controllare se una chiamata di strumento procede. A differenza di altri hook che usano un campo `decision` di livello superiore, PreToolUse restituisce la sua decisione dentro un oggetto `hookSpecificOutput`. Questo gli dà un controllo più ricco: quattro risultati (consenti, nega, chiedi, o differisci) più la capacità di modificare l'input dello strumento prima dell'esecuzione.1931Gli hook `PreToolUse` possono controllare se una chiamata a uno strumento procede. A differenza di altri hook che usano un campo `decision` di primo livello, PreToolUse restituisce la sua decisione all'interno di un oggetto `hookSpecificOutput`. Questo gli offre un controllo più ricco: quattro esiti (allow, deny, ask o defer) più la possibilità di modificare l'input dello strumento prima dell'esecuzione.
1930 1932
1931| Campo | Descrizione |1933| Campo | Descrizione |
1932| :- | :- |1934| :- | :- |
1933| `permissionDecision` | `"allow"` salta il prompt di permesso, tranne per le [azioni che nessuna modalità auto-approva](/docs/it/permission-modes#actions-no-mode-auto-approves) e per `AskUserQuestion` e `ExitPlanMode`, che hanno bisogno di [`updatedInput` accoppiato con esso](#allow-with-updatedinput). `"deny"` impedisce la chiamata dello strumento. `"ask"` chiede all'utente di confermare. `"defer"` esce con grazia in modo che lo strumento possa essere ripreso in seguito. Le [regole di negazione e richiesta](/docs/it/permissions#manage-permissions) vengono comunque valutate indipendentemente da ciò che l'hook restituisce |1935| `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 |
1934| `permissionDecisionReason` | Per `"ask"`, mostrato all'utente ma non a Claude. Per `"deny"`, mostrato a Claude. Per `"allow"` e `"defer"`, scritto nel [debug log](#debug-hooks) solo |1936| `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) |
1935| `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à [auto-background](/docs/it/tools-reference#background-commands) di un comando Bash rispetto all'input che il tuo hook restituisce, non l'input che Claude ha inviato. Combina con `"allow"` per auto-approvare, o `"ask"` per mostrare l'input modificato all'utente. Per `"defer"`, ignorato |1937| `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 |
1936| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Ignorato quando `permissionDecision` è `"defer"`. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |1938| `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) |
1937 1939
1938Quando più hook PreToolUse restituiscono decisioni diverse, la precedenza è `deny` > `defer` > `ask` > `allow`.1940Quando più hook PreToolUse restituiscono decisioni diverse, l'ordine di precedenza è `deny` > `defer` > `ask` > `allow`.
1939 1941
1940Un hook che blocca uscendo con 2 si instrada allo stesso modo di `"deny"`: Claude vede il messaggio stderr come il motivo della negazione.1942Un hook che blocca terminando con 2 segue lo stesso percorso di `"deny"`: Claude vede il messaggio di stderr come motivo del rifiuto.
1941 1943
1942Quando un hook restituisce `"ask"`, il prompt di permesso visualizzato all'utente include un'etichetta che identifica da dove viene l'hook: `[settings]` per un hook da qualsiasi file di impostazioni o dal frontmatter dell'agente, `[plugin:<name>]` per l'hook di un plugin, o `[skill]` per un hook dal frontmatter della skill. Questo aiuta gli utenti a capire quale fonte di configurazione sta richiedendo la conferma.1944Quando 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.
1943 1945
1944Un `"ask"` di un hook forza anche un prompt di permesso in [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode): il classificatore può ancora negare la chiamata dello strumento, ma non può approvare la chiamata silenziosamente. Prima della v2.1.211, il classificatore poteva approvare un comando Bash in esecuzione al di fuori della [sandbox](/docs/it/sandboxing) senza mostrare il prompt che l'hook ha richiesto; il classificatore ha comunque applicato le sue stesse regole di sicurezza a quel comando, e un `"deny"` di un hook è sempre stato onorato.1946Un `"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.
1945 1947
1946```json theme={null}1948```json theme={null}
1947{1949{
1959 1961
1960<span id="allow-with-updatedinput" />1962<span id="allow-with-updatedinput" />
1961 1963
1962In [modalità non interattiva](/docs/it/headless) con il flag `-p`, Claude Code offre `AskUserQuestion` e `ExitPlanMode` solo quando l'esecuzione ha un [permission host](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs) per ricevere il prompt, come un callback `canUseTool` di Agent SDK. Questi strumenti richiedono l'interazione dell'utente. Restituire `permissionDecision: "allow"` insieme a `updatedInput` soddisfa quel requisito: l'hook legge l'input dello strumento da stdin, raccoglie la risposta attraverso la tua UI, e la restituisce in `updatedInput` in modo che lo strumento si esegua senza chiedere. Restituire `"allow"` da solo non è sufficiente per questi strumenti. Per `AskUserQuestion`, ripeti l'array `questions` originale e aggiungi un oggetto [`answers`](#askuserquestion) che mappa il testo di ogni domanda alla risposta scelta.1964In [modalità non interattiva](/docs/it/headless) con il flag `-p`, Claude Code offre `AskUserQuestion` e `ExitPlanMode` solo quando l'esecuzione ha 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. Questi strumenti richiedono l'interazione dell'utente. Restituire `permissionDecision: "allow"` insieme a `updatedInput` soddisfa questo requisito: l'hook legge l'input dello strumento da stdin, raccoglie la risposta tramite la tua interfaccia e la restituisce in `updatedInput` così lo strumento viene eseguito senza chiedere. Restituire solo `"allow"` non è sufficiente per questi strumenti. Per `AskUserQuestion`, restituisci l'array `questions` originale e aggiungi un oggetto [`answers`](#askuserquestion) che associ il testo di ogni domanda alla risposta scelta.
1963 1965
1964A partire dalla v2.1.199, uno strumento MCP il cui server lo contrassegna con [`_meta["anthropic/requiresUserInteraction"]`](/docs/it/mcp#require-approval-for-a-specific-tool) è più rigoroso: un hook non può saltare il suo prompt di approvazione con `"allow"`, con o senza `updatedInput`, perché Claude Code non può confermare che l'hook ha raccolto l'interazione di cui lo strumento ha bisogno.1966Uno 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.
1965 1967
1966<Note>1968<Note>
1967 PreToolUse in precedenza usava campi `decision` e `reason` di livello superiore, ma questi sono deprecati per questo evento. Usa `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason` invece. I valori deprecati `"approve"` e `"block"` si mappano a `"allow"` e `"deny"` rispettivamente. Altri eventi come PostToolUse e Stop continuano a usare `decision` e `reason` di livello superiore come loro formato corrente.1969 PreToolUse in precedenza 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.
1968</Note>1970</Note>
1969 1971
1970<h4 id="defer-a-tool-call-for-later">1972<h4 id="defer-a-tool-call-for-later">
1971 Differisci una chiamata di strumento per dopo1973 Differire una chiamata a uno strumento
1972</h4>1974</h4>
1973 1975
1974`"defer"` è per le integrazioni che eseguono `claude -p` come un sottoprocesso e leggono il suo output JSON, come un'app Agent SDK o un'UI personalizzata costruita su Claude Code. Ti consente a quel processo di chiamata di mettere in pausa Claude a una chiamata di strumento, raccogliere l'input attraverso la sua interfaccia, e riprendere da dove si era fermato. Claude Code onora 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.1976`"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.
1975 1977
1976Lo strumento `AskUserQuestion` è il caso tipico: Claude vuole chiedere qualcosa all'utente, ma non c'è terminale per rispondere. Un'esecuzione `-p` offre `AskUserQuestion` solo quando ha un [permission host](/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. Il round trip funziona così:1978Lo 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ì:
1977 1979
19781. Claude chiama `AskUserQuestion`. L'hook `PreToolUse` si esegue.19801. Claude chiama `AskUserQuestion`. L'hook `PreToolUse` si attiva.
19792. L'hook restituisce `permissionDecision: "defer"`. Lo strumento non si esegue. Il processo esce con `stop_reason: "tool_deferred"` e la chiamata dello strumento in sospeso preservata nella trascrizione.19812. 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.
19803. Il processo di chiamata legge `deferred_tool_use` dal risultato dell'SDK, visualizza la domanda nella sua UI, e attende una risposta.19823. Il processo chiamante legge `deferred_tool_use` dal risultato dell'SDK, presenta la domanda nella propria interfaccia e attende una risposta.
19814. Il processo di chiamata esegue `claude -p --resume <session-id>` con lo stesso permission host. La stessa chiamata dello strumento esegue `PreToolUse` di nuovo.19834. Il processo chiamante esegue `claude -p --resume <session-id>` con lo stesso host dei permessi. La stessa chiamata allo strumento attiva di nuovo `PreToolUse`.
19825. L'hook restituisce `permissionDecision: "allow"` con la risposta in `updatedInput`. Lo strumento si esegue e Claude continua.19845. L'hook restituisce `permissionDecision: "allow"` con la risposta in `updatedInput`. Lo strumento viene eseguito e Claude continua.
1983 1985
1984Il campo `deferred_tool_use` porta l'`id` dello strumento, il `name`, e l'`input`. L'`input` è i parametri che Claude ha generato per la chiamata dello strumento, catturati prima dell'esecuzione:1986Il 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:
1985 1987
1986```json theme={null}1988```json theme={null}
1987{1989{
1997}1999}
1998```2000```
1999 2001
2000Non c'è timeout o limite di tentativi. La sessione rimane su disco finché non la riprendi, soggetta alla spazzata di conservazione [`cleanupPeriodDays`](/docs/it/settings-reference#cleanupperioddays), che elimina i file di sessione dopo 30 giorni per impostazione predefinita, seguendo le [regole di spazzata di conservazione](/docs/it/claude-directory#cleaned-up-automatically). Se la risposta non è pronta quando riprendi, l'hook può restituire `"defer"` di nuovo e il processo esce allo stesso modo. Il processo di chiamata controlla quando interrompere il ciclo restituendo infine `"allow"` o `"deny"` dall'hook.2002Non 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.
2001 2003
2002`"defer"` funziona solo quando Claude fa una singola chiamata di strumento nel turno. Se Claude fa diverse chiamate di strumento contemporaneamente, `"defer"` viene ignorato con un avviso e lo strumento procede attraverso il flusso di permesso normale. Il vincolo esiste perché la ripresa può solo ri-eseguire uno strumento: non c'è modo di differire una chiamata da un batch senza lasciare le altre irrisolte.2004`"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.
2003 2005
2004Se 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 esegua. Questo accade quando un server MCP che ha fornito lo strumento non è connesso per la sessione ripresa. Il payload `deferred_tool_use` è ancora incluso in modo che tu possa identificare quale strumento è scomparso.2006Se 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.
2005 2007
2006<Note>2008<Note>
2007 Per riprendere una sessione differita in modalità piano, 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 certi altri flag di lancio, l'esecuzione ripresa non ritorna alla modalità piano; vedi [Riprendi in modalità piano con `-p`](/docs/it/sessions#resume-in-plan-mode-with-p). Richiede Claude Code v2.1.246 o successivo.2009 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.
2008 2010
2009 Quando riprendi con `-p`, Claude Code non ripristina alcun'altra modalità di permesso archiviata. Avvia l'esecuzione nella modalità di permesso che una nuova esecuzione `claude -p` avvierebbe, quindi passa `--permission-mode` o `--dangerously-skip-permissions` di nuovo se la sessione differita ne ha usata una. Quando riprendi con `claude --resume <session-id>` senza `-p`, Claude Code ripristina la modalità di permesso archiviata, con le eccezioni elencate in [modalità di permesso alla ripresa](/docs/it/sessions#permission-mode-on-resume).2011 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).
2010</Note>2012</Note>
2011 2013
2012<h3 id="permissionrequest">2014<h3 id="permissionrequest">
2013 PermissionRequest2015 PermissionRequest
2014</h3>2016</h3>
2015 2017
2016Viene 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, rifiuta la chiamata allo strumento. Per una chiamata che raggiunge un `--permission-prompt-tool` o la [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.2018Viene 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.
2017Usa il [controllo delle decisioni di PermissionRequest](#permissionrequest-decision-control) per consentire o rifiutare per conto dell'utente.2019Usa il [controllo delle decisioni di PermissionRequest](#permissionrequest-decision-control) per consentire o negare per conto dell'utente.
2018 2020
2019Usa 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 il prompt ha atteso circa sei secondi.2021Usa 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.
2020 2022
2021Claude Code non esegue hook PermissionRequest per la [richiesta di rete](/docs/it/sandboxing#network-isolation) di un comando sandboxed. Per ottenere un segnale per quel prompt, usa il tipo di notifica `permission_prompt`.2023Claude 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`.
2022 2024
2023Corrisponde al nome dello strumento, stessi valori di PreToolUse.2025Effettua la corrispondenza sul nome dello strumento, con gli stessi valori di PreToolUse.
2024 2026
2025<h4 id="permissionrequest-input">2027<h4 id="permissionrequest-input">
2026 Input PermissionRequest2028 Input di PermissionRequest
2027</h4>2029</h4>
2028 2030
2029Gli 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 `permission_suggestions` facoltativo contiene gli [aggiornamenti di permesso](#permission-update-entries) che Claude Code suggerisce per questa richiesta, come aggiungere una regola di consentimento o cambiare la modalità di permesso.2031Gli 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.
2030 2032
2031L'array `permission_suggestions` non è un elenco esatto delle opzioni che vedi, perché ogni dialogo di permesso costruisce le sue stesse opzioni. Alcuni dialoghi, come quello per le modifiche ai file, non leggono affatto l'array e derivano le loro opzioni dalla richiesta stessa. Un dialogo che lo legge può comunque trattenere 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 piuttosto che attraverso un aggiornamento di permesso.2033L'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.
2032 2034
2033Gli hook PreToolUse si eseguono prima di ogni chiamata di strumento, indipendentemente dal fatto che abbia bisogno di permesso. Gli hook PermissionRequest si eseguono solo quando Claude Code sta per chiederti il permesso, o quando altrimenti auto-negherebbe una chiamata che non può chiedere. Nessuno dei due eventi si esegue per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).2035Gli 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).
2034 2036
2035```json theme={null}2037```json theme={null}
2036{2038{
2056```2058```
2057 2059
2058<h4 id="permissionrequest-decision-control">2060<h4 id="permissionrequest-decision-control">
2059 Controllo decisionale PermissionRequest2061 Controllo delle decisioni di PermissionRequest
2060</h4>2062</h4>
2061 2063
2062Gli hook `PermissionRequest` possono consentire o negare le richieste di permesso. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, il tuo script hook può restituire un oggetto `decision` con questi campi specifici dell'evento:2064Gli hook `PermissionRequest` possono consentire o negare le richieste di permesso. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, il tuo script di hook può restituire un oggetto `decision` con questi campi specifici dell'evento:
2063 2065
2064| Campo | Descrizione |2066| Campo | Descrizione |
2065| :- | :- |2067| :- | :- |
2066| `behavior` | `"allow"` concede il permesso, `"deny"` lo nega. Le [regole di negazione e richiesta](/docs/it/permissions#manage-permissions) vengono comunque valutate, quindi un hook che restituisce `"allow"` non sovrascrive una regola di negazione corrispondente |2068| `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 |
2067| `updatedInput` | Per `"allow"` solo: 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 richiesta |2069| `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 |
2068| `updatedPermissions` | Per `"allow"` solo: array di [voci di aggiornamento di permesso](#permission-update-entries) da applicare, come aggiungere una regola di consentimento o cambiare la modalità di permesso della sessione |2070| `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 |
2069| `message` | Per `"deny"` solo: dice a Claude perché il permesso è stato negato |2071| `message` | Solo per `"deny"`: indica a Claude perché il permesso è stato negato |
2070| `interrupt` | Per `"deny"` solo: se `true`, ferma Claude |2072| `interrupt` | Solo per `"deny"`: se `true`, ferma Claude |
2071 2073
2072Un hook che esce con 2 senza un oggetto `decision` lascia il flusso di permesso invariato, e il suo stderr viene scartato. Solo l'oggetto `decision` può concedere o negare la richiesta.2074Un 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.
2073 2075
2074```json theme={null}2076```json theme={null}
2075{2077{
2086```2088```
2087 2089
2088<h4 id="permission-update-entries">2090<h4 id="permission-update-entries">
2089 Voci di aggiornamento di permesso2091 Voci di aggiornamento dei permessi
2090</h4>2092</h4>
2091 2093
2092Sia il campo di output `updatedPermissions` che il campo di input [`permission_suggestions`](#permissionrequest-input) usano lo stesso array di oggetti di voce. Ogni voce ha un `type` che determina i suoi altri campi, e una `destination` che controlla dove il cambio viene scritto.2094Il 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.
2093 2095
2094| `type` | Campi | Effetto |2096| `type` | Campi | Effetto |
2095| :- | :- | :- |2097| :- | :- | :- |
2096| `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"` |2098| `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"` |
2097| `replaceRules` | `rules`, `behavior`, `destination` | Sostituisce tutte le regole del `behavior` dato alla `destination` con le `rules` fornite |2099| `replaceRules` | `rules`, `behavior`, `destination` | Sostituisce tutte le regole del `behavior` indicato nella `destination` con le `rules` fornite |
2098| `removeRules` | `rules`, `behavior`, `destination` | Rimuove le regole corrispondenti del `behavior` dato |2100| `removeRules` | `rules`, `behavior`, `destination` | Rimuove le regole corrispondenti del `behavior` indicato |
2099| `setMode` | `mode`, `destination` | Cambia la modalità di permesso. Le modalità valide sono `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan`, e `manual` come alias per `default`. L'alias `manual` richiede Claude Code v2.1.200 o successivo |2101| `setMode` | `mode`, `destination` | Cambia la modalità di permesso. Le modalità valide sono `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` e `manual` come alias di `default`. L'alias `manual` richiede Claude Code v2.1.200 o successiva |
2100| `addDirectories` | `directories`, `destination` | Aggiunge directory di lavoro. `directories` è un array di stringhe di percorso |2102| `addDirectories` | `directories`, `destination` | Aggiunge directory di lavoro. `directories` è un array di stringhe di percorso |
2101| `removeDirectories` | `directories`, `destination` | Rimuove directory di lavoro |2103| `removeDirectories` | `directories`, `destination` | Rimuove directory di lavoro |
2102 2104
2103<Note>2105<Note>
2104 `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 gestite](/docs/it/settings-reference#permissions-defaultmode). Altrimenti l'aggiornamento è un no-op. L'aggiornamento è anche un no-op quando [`permissions.disableBypassPermissionsMode`](/docs/it/permissions#managed-settings) disabilita la modalità, o quando la sessione inizia in [modalità ristretta](/docs/it/cli-reference#cli-flags).2106 `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).
2105 2107
2106 `bypassPermissions` non viene mai persistito come `defaultMode` indipendentemente da `destination`.2108 `bypassPermissions` non viene mai reso persistente come `defaultMode`, indipendentemente da `destination`.
2107</Note>2109</Note>
2108 2110
2109Il campo `destination` su ogni voce determina se il cambio rimane in memoria o persiste in un file di impostazioni.2111Il campo `destination` di ogni voce determina se la modifica rimane in memoria o viene resa persistente in un file di impostazioni.
2110 2112
2111| `destination` | Scrive in |2113| `destination` | Scrive in |
2112| :- | :- |2114| :- | :- |
2113| `session` | solo in memoria, scartato quando la sessione termina |2115| `session` | solo in memoria, scartata al termine della sessione |
2114| `localSettings` | `.claude/settings.local.json` |2116| `localSettings` | `.claude/settings.local.json` |
2115| `projectSettings` | `.claude/settings.json` |2117| `projectSettings` | `.claude/settings.json` |
2116| `userSettings` | `~/.claude/settings.json` |2118| `userSettings` | `~/.claude/settings.json` |
2117 2119
2118Un hook può ripetere uno dei `permission_suggestions` che ha ricevuto come suo proprio output `updatedPermissions`.2120Un hook può restituire uno dei `permission_suggestions` ricevuti come proprio output `updatedPermissions`.
2119 2121
2120<h3 id="posttooluse">2122<h3 id="posttooluse">
2121 PostToolUse2123 PostToolUse
2122</h3>2124</h3>
2123 2125
2124Si esegue immediatamente dopo che uno strumento completa con successo.2126Viene eseguito subito dopo che uno strumento è stato completato con successo.
2125 2127
2126Corrisponde al nome dello strumento, stessi valori di PreToolUse.2128Fa corrispondere il nome dello strumento, con gli stessi valori di PreToolUse.
2127 2129
2128Corrisponde più ampiamente quando il nome dello strumento non è il filtro giusto:2130Usa una corrispondenza più ampia quando il nome dello strumento non è il filtro giusto:
2129 2131
2130* Per eseguire un hook dopo che qualsiasi strumento completa con successo, ometti il `matcher` o impostalo su `"*"`. Il tuo hook può quindi scoprire cosa è cambiato da solo, ad esempio eseguendo `git status --porcelain`, che elenca anche i file non tracciati che `git diff` perde. Per le chiamate di strumento che falliscono, aggiungi lo stesso hook sotto [PostToolUseFailure](#posttoolusefailure).2132* 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).
2131* 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 al di fuori di Claude Code riscrive lo stesso file.2133* 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.
2132 2134
2133<h4 id="posttooluse-input">2135<h4 id="posttooluse-input">
2134 Input PostToolUse2136 Input di PostToolUse
2135</h4>2137</h4>
2136 2138
2137Gli hook `PostToolUse` si eseguono dopo che uno strumento si è già eseguito con successo. L'input include sia `tool_input`, gli argomenti inviati allo strumento, che `tool_response`, il risultato che ha restituito. Lo schema esatto per entrambi dipende dallo strumento. I percorsi `tool_input` degli strumenti di file arrivano nello stesso formato di [PreToolUse](#pretooluse-input): sempre assoluti, con i separatori nativi della piattaforma, quindi backslash su Windows. Per uno strumento MCP, l'input porta anche l'oggetto [`mcp_server`](#pretooluse-input).2139Gli 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).
2138 2140
2139```json theme={null}2141```json theme={null}
2140{2142{
2159 2161
2160| Campo | Descrizione |2162| Campo | Descrizione |
2161| :- | :- |2163| :- | :- |
2162| `duration_ms` | Facoltativo. Tempo di esecuzione dello strumento in millisecondi. Esclude il tempo trascorso nei prompt di permesso e negli hook PreToolUse |2164| `duration_ms` | Facoltativo. Tempo di esecuzione dello strumento in millisecondi. Esclude il tempo trascorso nelle richieste di permesso e negli hook PreToolUse |
2163 2165
2164<h4 id="posttooluse-decision-control">2166<h4 id="posttooluse-decision-control">
2165 Controllo decisionale PostToolUse2167 Controllo delle decisioni di PostToolUse
2166</h4>2168</h4>
2167 2169
2168Gli 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 hook può restituire questi campi specifici dell'evento:2170Gli 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:
2169 2171
2170| Campo | Descrizione |2172| Campo | Descrizione |
2171| :- | :- |2173| :- | :- |
2172| `decision` | `"block"` aggiunge il `reason` accanto al risultato dello strumento. Claude vede comunque l'output originale; per sostituirlo, usa `updatedToolOutput` |2174| `decision` | `"block"` aggiunge il `reason` accanto al risultato dello strumento. Claude vede comunque l'output originale; per sostituirlo, usa `updatedToolOutput` |
2173| `reason` | Spiegazione mostrata a Claude quando `decision` è `"block"` |2175| `reason` | Spiegazione mostrata a Claude quando `decision` è `"block"` |
2174| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |2176| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |
2175| `classifierContext` | Breve nota su questo risultato della chiamata per il classificatore della [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) piuttosto che per Claude. Vedi [Annota un risultato per il classificatore della modalità auto](#annotate-a-result-for-the-auto-mode-classifier). Richiede Claude Code v2.1.236 o successivo |2177| `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 |
2176| `updatedToolOutput` | Sostituisce l'output dello strumento con il valore fornito prima che venga inviato a Claude. Il valore deve corrispondere alla forma di output dello strumento |2178| `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 |
2177| `updatedMCPToolOutput` | Sostituisce l'output per gli [strumenti MCP](#match-mcp-tools) solo. Preferisci `updatedToolOutput`, che funziona per tutti gli strumenti |2179| `updatedMCPToolOutput` | Sostituisce l'output solo per gli [strumenti MCP](#match-mcp-tools). Preferisci `updatedToolOutput`, che funziona per tutti gli strumenti |
2178 2180
2179L'esempio sottostante sostituisce l'output di una chiamata `Bash`. Il valore di sostituzione corrisponde alla forma di output dello strumento `Bash`:2181L'esempio seguente sostituisce l'output di una chiamata `Bash`. Il valore sostitutivo corrisponde alla forma dell'output dello strumento `Bash`:
2180 2182
2181```json theme={null}2183```json theme={null}
2182{2184{
2194```2196```
2195 2197
2196<Warning>2198<Warning>
2197 `updatedToolOutput` cambia solo ciò che Claude vede. Lo strumento si è già eseguito nel momento in cui l'hook si esegue, quindi qualsiasi file scritto, comando eseguito, o richiesta di rete inviata ha già avuto effetto. La telemetria come gli span di strumenti OpenTelemetry e gli eventi di analitiche catturano anche l'output originale prima che l'hook si esegua. Per prevenire o modificare una chiamata di strumento prima che si esegua, usa un hook [PreToolUse](#pretooluse) invece.2199 `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).
2198 2200
2199 Il valore di sostituzione deve corrispondere alla forma di output dello strumento. Gli strumenti incorporati restituiscono oggetti strutturati piuttosto che stringhe semplici. Ad esempio, `Bash` restituisce un oggetto con campi `stdout`, `stderr`, `interrupted`, e `isImage`. Per gli strumenti incorporati, un valore che non corrisponde allo schema di output dello strumento viene ignorato e viene usato l'output originale. L'output dello strumento MCP viene passato senza convalida dello schema. Rimuovere i dettagli di errore di cui Claude ha bisogno può causargli di procedere su un'assunzione falsa.2201 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.
2200</Warning>2202</Warning>
2201 2203
2202<h4 id="annotate-a-result-for-the-auto-mode-classifier">2204<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2203 Annota un risultato per il classificatore della modalità auto2205 Annotare un risultato per il classificatore della modalità auto
2204</h4>2206</h4>
2205 2207
2206Restituisci `classifierContext` per inviare una breve nota sul risultato della chiamata dello strumento al classificatore della [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) piuttosto che a Claude. Il classificatore [non riceve mai i risultati degli strumenti stessi](/docs/it/permission-modes#how-the-classifier-evaluates-actions), quindi questo campo è il modo supportato per dirgli qualcosa su ciò che una chiamata ha restituito prima che riveda le azioni successive. Il campo richiede Claude Code v2.1.236 o successivo.2208Restituisci `classifierContext` per inviare una breve nota sul risultato della chiamata allo strumento al classificatore della [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) anziché a Claude. Il classificatore [non riceve mai i risultati degli strumenti in sé](/docs/it/permission-modes#how-the-classifier-evaluates-actions), quindi questo campo è il modo supportato per comunicargli qualcosa su ciò che una chiamata ha restituito prima che esamini le azioni successive. Il campo richiede Claude Code v2.1.236 o successiva.
2207 2209
2208L'esempio sottostante dice al classificatore da dove proviene l'output di una query:2210L'esempio seguente indica al classificatore da dove proviene l'output di una query:
2209 2211
2210```json theme={null}2212```json theme={null}
2211{2213{
2216}2218}
2217```2219```
2218 2220
2219Quanto peso il classificatore dà alla nota dipende da dove hai configurato l'hook:2221Il peso che il classificatore attribuisce alla nota dipende da dove hai configurato l'hook:
2220 2222
2221* **Hook configurati in Claude Code**: per gli hook dai file di impostazioni, dai plugin, dalle skill, e dal frontmatter dell'agente, 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 controlla quell'affermazione rispetto ai tuoi stessi messaggi nella conversazione2223* **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
2222* **Callback Agent SDK in-process**: quando un'applicazione che incorpora Claude Code registra l'hook come un [callback SDK TypeScript](/docs/it/agent-sdk/hooks) e restituisce la nota durante la sessione dal vivo, il classificatore può pesare un'affermazione dell'utente trasmessa nella nota come intento dell'utente. Tale affermazione può soddisfare un requisito di consenso che il classificatore accetterebbe da un messaggio che invii, ma non solleva mai un blocco che il tuo stesso messaggio non potrebbe sollevare neanche. Dopo che una sessione riprende, Claude Code tratta le note ripristinate come contesto non verificato. Quando gli hook di entrambi i gruppi annotano la stessa chiamata, il classificatore tratta la nota combinata come non verificata2224* **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 verificata
2223 2225
2224Claude Code applica questi limiti quando consegna la nota:2226Claude Code applica questi limiti quando consegna la nota:
2225 2227
2226* **Lunghezza**: Claude Code limita le note per una chiamata di strumento a 2.000 caratteri e tronca il resto. Il limite è condiviso tra ogni hook che risponde a quella chiamata2228* **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
2227* **Solo risposte sincrone**: Claude Code ignora il campo nella risposta di un hook che [si esegue in background](#run-hooks-in-the-background), perché quella risposta arriva dopo che Claude Code registra il risultato dello strumento2229* **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
2228* **Chiamate che il classificatore non registra**: la trascrizione del classificatore omette le ricerche di sola lettura come le letture di file e le ricerche. Claude Code scarta una nota allegata a una di quelle chiamate2230* **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 chiamate
2229* **Interazione con le riscritture**: quando la nota descrive l'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 la riscrittura di un altro hook la sostituisce. Claude Code consegna una nota che restituisci senza una riscrittura anche quando un altro hook riscrive l'output2231* **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
2230 2232
2231<Warning>2233<Warning>
2232 Il classificatore legge il contenuto che metti in `classifierContext` come informazioni dall'applicazione che ospita la sessione, quindi non copiare l'output dello strumento non attendibile o il testo di terze parti in esso. Mantieni la nota a una breve affermazione su questa una chiamata, come un fatto sulla sua origine o un'affermazione dell'utente su di essa; non usare il campo per consegnare messaggi non correlati o un flusso di eventi.2234 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.
2233</Warning>2235</Warning>
2234 2236
2235<h3 id="posttoolusefailure">2237<h3 id="posttoolusefailure">
2236 PostToolUseFailure2238 PostToolUseFailure
2237</h3>2239</h3>
2238 2240
2239Si esegue quando uno strumento che ha iniziato a eseguirsi fallisce: lo strumento ha lanciato un errore, o uno strumento MCP ha restituito un risultato di errore. Usa questo per registrare i fallimenti, inviare avvisi, o fornire feedback correttivo a Claude.2241Viene 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.
2240 2242
2241Corrisponde al nome dello strumento, stessi valori di PreToolUse.2243Fa corrispondere il nome dello strumento, con gli stessi valori di PreToolUse.
2242 2244
2243<Note>2245<Note>
2244 Questo evento non si esegue per le chiamate di strumento rifiutate prima dell'esecuzione: un nome di strumento sconosciuto, input che fallisce la convalida dello schema o specifica dello strumento, o una negazione di permesso. I rifiuti di convalida vengono restituiti come risultati `tool_use_error` e accadono prima che gli hook si eseguano, quindi non eseguono né `PreToolUse` né `PostToolUseFailure`. Le negazioni di permesso eseguono `PreToolUse` ma non questo evento; vedi [PermissionDenied](#permissiondenied).2246 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).
2245</Note>2247</Note>
2246 2248
2247<h4 id="posttoolusefailure-input">2249<h4 id="posttoolusefailure-input">
2248 Input PostToolUseFailure2250 Input di PostToolUseFailure
2249</h4>2251</h4>
2250 2252
2251Gli hook PostToolUseFailure ricevono gli stessi campi `tool_name` e `tool_input` di PostToolUse, insieme alle informazioni di errore come campi di livello superiore. Per uno strumento MCP, ricevono anche l'oggetto [`mcp_server`](#pretooluse-input). Ad esempio, un comando `npm test` fallito potrebbe consegnare:2253Gli 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:
2252 2254
2253```json theme={null}2255```json theme={null}
2254{2256{
2271 2273
2272| Campo | Descrizione |2274| Campo | Descrizione |
2273| :- | :- |2275| :- | :- |
2274| `error` | Stringa che descrive cosa è andato male. Il formato dipende dallo strumento che ha fallito |2276| `error` | Stringa che descrive cosa è andato storto. Il formato dipende dallo strumento che ha fallito |
2275| `is_interrupt` | Booleano facoltativo. True quando il fallimento ha raggiunto Claude Code come un'interruzione piuttosto che come un errore che lo strumento ha segnalato. L'annullamento di uno strumento in esecuzione non esegue questo hook; il risultato dello strumento porta il messaggio di interruzione invece |2277| `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 |
2276| `duration_ms` | Facoltativo. Tempo di esecuzione dello strumento in millisecondi. Esclude il tempo trascorso nei prompt di permesso e negli hook PreToolUse |2278| `duration_ms` | Facoltativo. Tempo di esecuzione dello strumento in millisecondi. Esclude il tempo trascorso nelle richieste di permesso e negli hook PreToolUse |
2277 2279
2278La stringa `error` è generalmente lo stesso testo che Claude riceve come risultato dello strumento fallito. Il suo formato varia per strumento e fallimento. Chiavi il tuo hook su `tool_name`, `is_interrupt`, e la prima riga `Exit code N`; tratta il resto della stringa come testo di visualizzazione, non un formato stabile.2280La 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.
2279 2281
2280* Per Bash e PowerShell, un comando che si è eseguito e ha uscito produce una prima riga `Exit code N`, quindi qualsiasi output che il comando ha prodotto come un blocco con stdout e stderr intercalati2282* 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 intercalati
2281* Un payload può anche portare un messaggio di fallimento nudo senza una riga di codice di uscita, quando Claude Code non poteva avviare il processo shell stesso2283* 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 stesso
2282* Claude Code tronca nel mezzo le stringhe lunghe intorno a un marcatore `... [N characters truncated] ...`, e può inserire righe proprie, come `Command timed out after 2m 0s`2284* 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`
2283 2285
2284<h4 id="posttoolusefailure-decision-control">2286<h4 id="posttoolusefailure-decision-control">
2285 Controllo decisionale PostToolUseFailure2287 Controllo delle decisioni di PostToolUseFailure
2286</h4>2288</h4>
2287 2289
2288Gli hook `PostToolUseFailure` possono fornire contesto a Claude dopo un fallimento dello strumento. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, il tuo script hook può restituire questi campi specifici dell'evento:2290Gli 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:
2289 2291
2290| Campo | Descrizione |2292| Campo | Descrizione |
2291| :- | :- |2293| :- | :- |
2292| `additionalContext` | Stringa aggiunta al contesto di Claude insieme all'errore. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |2294| `additionalContext` | Stringa aggiunta al contesto di Claude insieme all'errore. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |
2293 2295
2294```json theme={null}2296```json theme={null}
2295{2297{
2304 PostToolBatch2306 PostToolBatch
2305</h3>2307</h3>
2306 2308
2307Si esegue una volta dopo che ogni chiamata di strumento in un batch si è risolta, prima che Claude Code invii la richiesta successiva al modello. `PostToolUse` si esegue una volta per strumento, il che significa che si esegue contemporaneamente quando Claude fa chiamate di strumento parallele. `PostToolBatch` si esegue esattamente una volta con il batch completo, quindi è il posto giusto per iniettare contesto che dipende dall'insieme di strumenti che si sono eseguiti piuttosto che da qualsiasi singolo strumento. Non c'è matcher per questo evento.2309Viene 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.
2308 2310
2309<h4 id="posttoolbatch-input">2311<h4 id="posttoolbatch-input">
2310 Input PostToolBatch2312 Input di PostToolBatch
2311</h4>2313</h4>
2312 2314
2313Oltre ai [campi di input comuni](#common-input-fields), gli hook PostToolBatch ricevono `tool_calls`, un array che descrive ogni chiamata di strumento nel batch:2315Oltre ai [campi di input comuni](#common-input-fields), gli hook PostToolBatch ricevono `tool_calls`, un array che descrive ogni chiamata a uno strumento nel batch:
2314 2316
2315```json theme={null}2317```json theme={null}
2316{2318{
2336}2338}
2337```2339```
2338 2340
2339`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`, questo significa testo con prefisso numero di riga piuttosto che contenuti di file grezzi. Le risposte possono essere grandi, quindi analizza solo i campi di cui hai bisogno.2341`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.
2340 2342
2341<Note>2343<Note>
2342 La forma `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 il modello vede.2344 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.
2343</Note>2345</Note>
2344 2346
2345<h4 id="posttoolbatch-decision-control">2347<h4 id="posttoolbatch-decision-control">
2346 Controllo decisionale PostToolBatch2348 Controllo delle decisioni di PostToolBatch
2347</h4>2349</h4>
2348 2350
2349Gli hook `PostToolBatch` possono iniettare contesto per Claude. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, il tuo script hook può restituire questi campi specifici dell'evento:2351Gli 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:
2350 2352
2351| Campo | Descrizione |2353| Campo | Descrizione |
2352| :- | :- |2354| :- | :- |
2353| `additionalContext` | Stringa di contesto iniettata una volta prima della richiesta del modello successivo. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) per i dettagli di consegna, cosa metterci, e come le sessioni riprese gestiscono i valori passati |2355| `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 |
2354 2356
2355```json theme={null}2357```json theme={null}
2356{2358{
2361}2363}
2362```2364```
2363 2365
2364Restituire `decision: "block"` o `continue: false` ferma il loop agentivo prima della richiesta del modello successivo. Il messaggio di blocco viene dal JSON `reason` o `stopReason`, o da stderr all'uscita 2. Lo vedi come un avviso nella trascrizione, e rimane nella conversazione, quindi Claude lo vede quando la conversazione continua.2366Restituire `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.
2365 2367
2366<h3 id="permissiondenied">2368<h3 id="permissiondenied">
2367 PermissionDenied2369 PermissionDenied
2368</h3>2370</h3>
2369 2371
2370Si esegue quando la [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) nega una chiamata di strumento, incluso quando 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 ha analizzato. Questo hook si esegue solo in modalità auto: non si esegue quando neghi manualmente un dialogo di permesso, quando un hook `PreToolUse` blocca una chiamata, o quando una regola `deny` corrisponde. Usalo per registrare le negazioni, regolare la configurazione, o dire al modello che può ritentare la chiamata dello strumento.2372Viene 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.
2371 2373
2372Corrisponde al nome dello strumento, stessi valori di PreToolUse.2374Fa corrispondere il nome dello strumento, con gli stessi valori di PreToolUse.
2373 2375
2374<h4 id="permissiondenied-input">2376<h4 id="permissiondenied-input">
2375 Input PermissionDenied2377 Input di PermissionDenied
2376</h4>2378</h4>
2377 2379
2378Oltre ai [campi di input comuni](#common-input-fields), gli hook PermissionDenied ricevono `tool_name`, `tool_input`, `tool_use_id`, e `reason`. Per uno strumento MCP, ricevono anche l'oggetto [`mcp_server`](#pretooluse-input).2380Oltre ai [campi di input comuni](#common-input-fields), gli hook PermissionDenied ricevono `tool_name`, `tool_input`, `tool_use_id` e `reason`. Per uno strumento MCP, ricevono anche l'oggetto [`mcp_server`](#pretooluse-input).
2379 2381
2380```json theme={null}2382```json theme={null}
2381{2383{
2396 2398
2397| Campo | Descrizione |2399| Campo | Descrizione |
2398| :- | :- |2400| :- | :- |
2399| `reason` | Il motivo della negazione. Per un verdetto del classificatore, nella maggior parte delle sessioni nomina la regola corrispondente tra parentesi quadre, come `[Data Exfiltration]`; vedi [Rivedi le negazioni](/docs/it/auto-mode-config#review-denials) per le altre forme. Per una [negazione senza verdetto](#permissiondenied-decision-control), inizia con `Auto mode could not evaluate this action and is blocking it for safety`. Per una negazione perché il modello del classificatore non era disponibile, è il testo fisso `Classifier unavailable` |2401| `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` |
2400 2402
2401<h4 id="permissiondenied-decision-control">2403<h4 id="permissiondenied-decision-control">
2402 Controllo decisionale PermissionDenied2404 Controllo delle decisioni di PermissionDenied
2403</h4>2405</h4>
2404 2406
2405Gli hook PermissionDenied possono dire al modello che può ritentare la chiamata dello strumento negata. Restituisci un oggetto JSON con `hookSpecificOutput.retry` impostato su `true`:2407Gli hook PermissionDenied possono dire al modello che può riprovare la chiamata allo strumento negata. Restituisci un oggetto JSON con `hookSpecificOutput.retry` impostato su `true`:
2406 2408
2407```json theme={null}2409```json theme={null}
2408{2410{
2413}2415}
2414```2416```
2415 2417
2416Quando `retry` è `true`, Claude Code aggiunge un messaggio alla conversazione dicendo al modello che può ritentare la chiamata dello strumento. Claude Code non inverte la negazione stessa. Se il tuo hook non restituisce JSON, o restituisce `retry: false`, la negazione rimane e il modello riceve il messaggio di rifiuto originale.2418Quando `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.
2417 2419
2418Claude Code ignora `retry: true` quando il classificatore ha prodotto [nessun verdetto sull'azione](/docs/it/errors#auto-mode-cannot-determine-the-safety-of-an-action): la sua risposta non ha analizzato, o un controllo di sicurezza separato dalla modalità auto ha rifiutato la richiesta del classificatore. Per quelle negazioni, Claude Code già dice al modello nel messaggio di rifiuto se ritentare più tardi o procedere.2420Claude 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.
2419 2421
2420<h3 id="notification">2422<h3 id="notification">
2421 Notification2423 Notification
2422</h3>2424</h3>
2423 2425
2424Si esegue quando Claude Code invia notifiche. Corrisponde al tipo di notifica. Ometti il matcher per eseguire gli hook per tutti i tipi di notifica.2426Viene 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.
2425 2427
2426Ricevi questi eventi hook anche con le notifiche desktop disattivate: l'impostazione `preferredNotifChannel`, incluso `notifications_disabled`, cambia solo come sei avvisato, non se il tuo hook si esegue.2428Ricevi 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.
2427 2429
2428| Matcher | Quando si attiva |2430| Matcher | Quando si attiva |
2429| :- | :- |2431| :- | :- |
2430| `permission_prompt` | Claude ha bisogno della tua approvazione per usare uno strumento o la [richiesta di rete](/docs/it/sandboxing#network-isolation) di un comando sandboxed, e il prompt ha atteso circa sei secondi |2432| `permission_prompt` | Claude ha bisogno che tu approvi l'uso di uno strumento o la [richiesta di rete](/docs/it/sandboxing#network-isolation) di un comando in sandbox, e la richiesta è in attesa da circa sei secondi |
2431| `idle_prompt` | Claude ha finito di rispondere circa 60 secondi fa e non hai digitato da allora |2433| `idle_prompt` | Claude ha finito di rispondere circa 60 secondi fa e da allora non hai digitato nulla |
2432| `auth_success` | L'autenticazione completa |2434| `auth_success` | L'autenticazione viene completata |
2433| `elicitation_dialog` | Un server MCP apre un modulo di elicitazione e non hai digitato per circa sei secondi |2435| `elicitation_dialog` | Un server MCP apre un modulo di elicitazione e non digiti da circa sei secondi |
2434| `elicitation_url_dialog` | Un server MCP ti chiede di aprire un URL del browser e non hai digitato per circa sei secondi |2436| `elicitation_url_dialog` | Un server MCP ti chiede di aprire un URL nel browser e non digiti da circa sei secondi |
2435| `elicitation_complete` | Un server MCP segnala che un'[elicitazione in modalità URL](#elicitation-input) è completa |2437| `elicitation_complete` | Un server MCP segnala che un'[elicitazione in modalità URL](#elicitation-input) è completa |
2436| `elicitation_response` | Una risposta di elicitazione MCP viene inviata di nuovo al server |2438| `elicitation_response` | Una risposta di elicitazione MCP viene inviata al server |
2437| `agent_needs_input` | Una sessione di background inizia ad aspettare il tuo input mentre la [vista agente](/docs/it/agent-view) è aperta in un terminale. Si esegue anche quando una sessione di terminale ti mostra una [domanda di configurazione del terminale del compagno di squadra dell'agente](/docs/it/agent-teams#choose-a-display-mode) o l'avviso della modalità auto sui [costi di richiesta del classificatore](/docs/it/auto-mode-classifier-billing) e non hai digitato per circa sei secondi |2439| `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 |
2438| `agent_completed` | Una sessione di background finisce o fallisce. Si esegue solo mentre la [vista agente](/docs/it/agent-view) è aperta in un terminale |2440| `agent_completed` | Una sessione in background termina o fallisce. Si attiva solo mentre la [vista agenti](/docs/it/agent-view) è aperta in un terminale |
2439| `quota_auto_resume_fired` | Claude Code continua il tuo compito dopo che un limite di utilizzo di claude.ai lo ha messo in pausa: al reset, o prima quando qualcosa che fai in Claude Code durante l'attesa, come aggiungere crediti di utilizzo, aggiornare il tuo piano, o cambiare modelli, rende l'utilizzo disponibile di nuovo, con l'[eccezione dell'impostazione del modello](/docs/it/interactive-mode#wait-for-a-usage-limit-to-reset) |2441| `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) |
2440| `quota_auto_resume_stale` | Un limite di utilizzo di claude.ai si è resettato mentre il tuo computer dormiva per più di circa 30 minuti. Claude Code attende che tu prema `Enter` invece di continuare. Dopo un sonno più breve continua e esegue `quota_auto_resume_fired` invece |2442| `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` |
2441| `quota_auto_resume_disabled` | Claude Code termina la sua attesa per un limite di utilizzo di claude.ai senza continuare il tuo compito: [`autoContinueAtUsageLimit`](/docs/it/settings-reference#autocontinueatusagelimit) è stato disattivato o il reset si è spostato più di 24 ore lontano durante un'attesa che Claude Code ha avviato da solo, il compito continuato ha continuato a colpire il limite, o la continuazione è stata bloccata prima di raggiungere il modello. Non si esegue quando premi `Esc` o `Ctrl+C`, o scegli **Don't continue automatically** |2443| `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** |
2442 2444
2443I tipi `quota_auto_resume_fired`, `quota_auto_resume_stale`, e `quota_auto_resume_disabled` richiedono Claude Code v2.1.234 o successivo.2445I tipi `quota_auto_resume_fired`, `quota_auto_resume_stale` e `quota_auto_resume_disabled` richiedono Claude Code v2.1.234 o successiva.
2444 2446
2445Nelle sessioni di terminale, `permission_prompt` per la richiesta di rete di un comando sandboxed richiede Claude Code v2.1.246 o successivo.2447Nelle sessioni nel terminale, `permission_prompt` per la richiesta di rete di un comando in sandbox richiede Claude Code v2.1.246 o successiva.
2446 2448
2447`agent_needs_input` per una domanda di configurazione del terminale del compagno di squadra richiede Claude Code v2.1.248 o successivo.2449`agent_needs_input` per la domanda di configurazione del terminale di un compagno di team richiede Claude Code v2.1.248 o successiva.
2448 2450
2449<Note>2451<Note>
2450 I tipi `permission_prompt`, `idle_prompt`, `elicitation_dialog`, e `elicitation_url_dialog` condividono il loro timing con le notifiche desktop, quindi nelle sessioni di terminale li vedi solo quando sembri essere lontano dal terminale:2452 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:
2451 2453
2452 * Aspettati `permission_prompt` una volta che non hai digitato per circa sei secondi. Il timer inizia quando il prompt di permesso appare, e ogni pressione di tasto lo rinvia. Per eseguire un hook immediatamente quando Claude chiede il permesso di usare uno strumento, usa [PermissionRequest](#permissionrequest) invece.2454 * 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).
2453 * Aspettati `idle_prompt` circa 60 secondi dopo che Claude finisce di rispondere, e solo se non hai digitato da allora. Claude Code non invia `idle_prompt` mentre attende che un limite di utilizzo di claude.ai si resetti. Quando l'attesa termina da sola, uno dei tipi `quota_auto_resume_*` si esegue invece.2455 * 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_*`.
2454 * Aspettati `elicitation_dialog` per un modulo di elicitazione, o `elicitation_url_dialog` per una richiesta di URL del browser, una volta che non hai digitato per circa sei secondi. Entrambi condividono lo stesso gate di sei secondi di `permission_prompt`: il timer inizia quando il dialogo appare, e ogni pressione di tasto lo rinvia.2456 * 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.
2455 2457
2456 Una richiesta di permesso o elicitazione che arriva mentre un altro dialogo è sullo schermo mantiene lo stesso gate di sei secondi, cronometrato da quando la richiesta arriva. La sua notifica può raggiungerti mentre la richiesta attende ancora dietro il dialogo aperto.2458 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.
2457</Note>2459</Note>
2458 2460
2459Claude Code cronometra `permission_prompt` diversamente nelle sessioni in cui invia richieste di permesso al callback [`canUseTool`](/docs/it/agent-sdk/user-input) dell'Agent SDK, che è come Claude Desktop e l'estensione VS Code ospitano Claude Code:2461Claude 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:
2460 2462
2461* Aspettati `permission_prompt` circa sei secondi dopo che Claude chiede il permesso. Claude Code non lo rinvia mentre digiti.2463* Aspettati `permission_prompt` circa sei secondi dopo che Claude chiede il permesso. Claude Code non lo posticipa mentre digiti.
2462* Se tu o un hook [PermissionRequest](#permissionrequest) rispondete prima, Claude Code non esegue `permission_prompt`.2464* Se tu o un hook [PermissionRequest](#permissionrequest) rispondete prima, Claude Code non esegue `permission_prompt`.
2463* Imposta [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/it/env-vars) su `1` per disattivare `permission_prompt` in queste sessioni.2465* Imposta [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/it/env-vars) su `1` per disattivare `permission_prompt` in queste sessioni.
2464 2466
2465Prima della v2.1.233, `permission_prompt` non si eseguiva in queste sessioni.2467Prima della v2.1.233, `permission_prompt` non si attivava in queste sessioni.
2466 2468
2467Usa matcher separati per eseguire diversi handler a seconda del tipo di notifica. Questa configurazione attiva uno script di avviso specifico per il permesso quando Claude ha bisogno dell'approvazione del permesso e una notifica diversa quando Claude è stato inattivo:2469Usa matcher separati per eseguire gestori diversi a seconda del tipo di notifica. Questa configurazione attiva uno script di avviso specifico per i permessi quando Claude ha bisogno di un'approvazione dei permessi e una notifica diversa quando Claude è inattivo:
2468 2470
2469```json theme={null}2471```json theme={null}
2470{2472{
2494```2496```
2495 2497
2496<h4 id="notification-input">2498<h4 id="notification-input">
2497 Input Notification2499 Input di Notification
2498</h4>2500</h4>
2499 2501
2500Oltre 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 è eseguito.2502Oltre 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.
2501 2503
2502```json theme={null}2504```json theme={null}
2503{2505{
2511}2513}
2512```2514```
2513 2515
2514Gli 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 destinati agli effetti collaterali come l'inoltro della notifica a un servizio esterno.2516Gli 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.
2515 2517
2516<h3 id="subagentstart">2518<h3 id="subagentstart">
2517 SubagentStart2519 SubagentStart
2518</h3>2520</h3>
2519 2521
2520Si esegue quando Claude genera un subagente con lo strumento Agent, quando Claude [riprende un subagente](/docs/it/sub-agents#resume-subagents), e ogni volta che un compagno di squadra dell'[agente team](/docs/it/agent-teams) in-process gestisce un nuovo messaggio. Supporta i matcher per filtrare per nome del tipo di agente. Per gli agenti incorporati, questo è il nome dell'agente come `general-purpose`, `Explore`, o `Plan`. Per i [subagenti personalizzati](/docs/it/sub-agents), questo è il campo `name` dal frontmatter dell'agente, non il nome del file.2522Viene 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.
2521 2523
2522Per i subagenti forniti da un [plugin](/docs/it/plugins/overview), il tipo di agente è l'identificatore con ambito del plugin come `my-plugin:reviewer`, non il nome del frontmatter nudo. I due punti mettono un nome con ambito del plugin sul percorso dell'espressione regolare, quindi ancora il matcher con `^` e `$` per una corrispondenza esatta: `^my-plugin:reviewer$`.2524Per 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$`.
2523 2525
2524<h4 id="subagentstart-input">2526<h4 id="subagentstart-input">
2525 Input SubagentStart2527 Input di SubagentStart
2526</h4>2528</h4>
2527 2529
2528Oltre ai [campi di input comuni](#common-input-fields), gli hook SubagentStart ricevono `agent_id` con l'identificatore univoco per il subagente e `agent_type` con il nome dell'agente su cui il matcher filtra.2530Oltre ai [campi di input comuni](#common-input-fields), gli hook SubagentStart ricevono `agent_id` con l'identificatore univoco del subagent e `agent_type` con il nome dell'agente su cui filtra il matcher.
2529 2531
2530```json theme={null}2532```json theme={null}
2531{2533{
2538}2540}
2539```2541```
2540 2542
2541Gli hook SubagentStart non possono bloccare la creazione del subagente, ma possono iniettare contesto nel subagente. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, puoi restituire:2543Gli hook SubagentStart non possono bloccare la creazione del subagent, ma possono iniettare contesto nel subagent. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, puoi restituire:
2542 2544
2543| Campo | Descrizione |2545| Campo | Descrizione |
2544| :- | :- |2546| :- | :- |
2545| `additionalContext` | Stringa aggiunta al contesto del subagente all'inizio della sua conversazione, prima del suo primo prompt. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |2547| `additionalContext` | Stringa aggiunta al contesto del subagent all'inizio della sua conversazione, prima del suo primo prompt. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |
2546 2548
2547```json theme={null}2549```json theme={null}
2548{2550{
2553}2555}
2554```2556```
2555 2557
2556Quando l'hook si esegue di nuovo per lo stesso subagente, Claude Code inietta il contesto restituito solo quando il contesto del subagente non contiene già la copia da un'esecuzione precedente. La copia iniettata al lancio rimane al suo posto, lasciando la [cache del prompt](/docs/it/prompt-caching#subagents-and-the-cache) del subagente intatta. Dopo che la [compattazione automatica](/docs/it/sub-agents#auto-compaction) scarta quella copia, Claude Code inietta il contesto dell'esecuzione successiva di nuovo.2558Quando 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.
2557 2559
2558<h3 id="subagentstop">2560<h3 id="subagentstop">
2559 SubagentStop2561 SubagentStop
2560</h3>2562</h3>
2561 2563
2562Si esegue quando un subagente di Claude Code ha finito di rispondere. Corrisponde al tipo di agente, stessi valori di SubagentStart.2564Viene eseguito quando un subagent di Claude Code ha finito di rispondere. Fa corrispondere il tipo di agente, con gli stessi valori di SubagentStart.
2563 2565
2564<h4 id="subagentstop-input">2566<h4 id="subagentstop-input">
2565 Input SubagentStop2567 Input di SubagentStop
2566</h4>2568</h4>
2567 2569
2568Oltre 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 propria del subagente archiviata in una cartella `subagents/` annidato. Il campo `last_assistant_message` contiene il contenuto di testo della risposta finale del subagente, quindi gli hook possono accedervi senza analizzare il file di trascrizione.2570Oltre 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.
2569 2571
2570Non ogni evento SubagentStop viene da un subagente che Claude ha generato. Claude Code esegue anche agenti interni per alcune delle sue stesse 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 esegue quando uno di quelli finisce anche. Per quegli eventi, `agent_type` è il nome dell'agente che la sessione stessa esegue, come uno impostato con [`--agent`](/docs/it/cli-reference#cli-flags) o l'impostazione [`agent`](/docs/it/settings-reference#agent), e una stringa vuota quando la sessione si esegue senza uno.2572Non 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.
2571 2573
2572Un `matcher` che nomina i tipi di agente non corrisponde a un `agent_type` vuoto. Un hook il cui matcher è omesso, `""`, o `"*"`, o è un'espressione regolare che corrisponde a una stringa vuota, si esegue per gli eventi con un `agent_type` vuoto anche.2574Un `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.
2573 2575
2574Su Claude Code v2.1.271 o successivo, un subagente che si esegue con lo strumento [`SubagentHandback`](/docs/it/tools-reference) consegna il suo rapporto attraverso quello strumento prima che si fermi. Il campo `last_assistant_message` contiene il testo di chiusura del subagente, se presente, che non è il rapporto consegnato. Il rapporto è l'input `message` di quella chiamata, che un hook `PreToolUse` o `PostToolUse` che corrisponde a `SubagentHandback` riceve come `tool_input.message`.2576Su 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`.
2575 2577
2576Gli hook SubagentStop ricevono anche gli array `background_tasks` e `session_crons` descritti sotto [Input Stop](#stop-input). Entrambi gli array sono limitati alla sessione genitore, non al subagente.2578Gli 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.
2577 2579
2578```json theme={null}2580```json theme={null}
2579{2581{
2592}2594}
2593```2595```
2594 2596
2595Gli hook SubagentStop usano lo stesso formato di controllo decisionale degli [hook Stop](#stop-decision-control), incluso `hookSpecificOutput.additionalContext` con `hookEventName` impostato su `"SubagentStop"`, per il feedback non di errore che mantiene il subagente in esecuzione. Restituire `decision: "block"` con un `reason` mantiene il subagente in esecuzione e consegna `reason` al subagente come sua istruzione successiva. Un hook che blocca uscendo con 2 consegna il suo messaggio stderr allo stesso modo. Per iniettare contesto nella sessione genitore dopo che un subagente ritorna, usa un hook [`PostToolUse`](#posttooluse) sullo strumento `Agent` invece.2597Gli 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`.
2596 2598
2597<h3 id="taskcreated">2599<h3 id="taskcreated">
2598 TaskCreated2600 TaskCreated
2599</h3>2601</h3>
2600 2602
2601Si esegue quando un'attività viene creata tramite lo strumento `TaskCreate`. Usalo per applicare convenzioni di denominazione, richiedere descrizioni di attività, o prevenire la creazione di determinate attività. In una [sessione senza gli strumenti Task](/docs/it/tools-reference#task-tool-availability), questo evento non si esegue.2603Viene 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.
2602 2604
2603Gli hook TaskCreated non supportano i matcher e si eseguono su ogni occorrenza.2605Gli hook TaskCreated non supportano i matcher e si attivano a ogni occorrenza.
2604 2606
2605<h4 id="taskcreated-input">2607<h4 id="taskcreated-input">
2606 Input TaskCreated2608 Input di TaskCreated
2607</h4>2609</h4>
2608 2610
2609Oltre ai [campi di input comuni](#common-input-fields), gli hook TaskCreated ricevono `task_id`, `task_subject`, e facoltativamente `task_description`, `teammate_name`, e `team_name`.2611Oltre ai [campi di input comuni](#common-input-fields), gli hook TaskCreated ricevono `task_id`, `task_subject` e, facoltativamente, `task_description`, `teammate_name` e `team_name`.
2610 2612
2611```json theme={null}2613```json theme={null}
2612{2614{
2624 2626
2625| Campo | Descrizione |2627| Campo | Descrizione |
2626| :- | :- |2628| :- | :- |
2627| `task_id` | Identificatore dell'attività in fase di creazione |2629| `task_id` | Identificatore del task in fase di creazione |
2628| `task_subject` | Titolo dell'attività |2630| `task_subject` | Titolo del task |
2629| `task_description` | Descrizione dettagliata dell'attività. Può essere assente |2631| `task_description` | Descrizione dettagliata del task. Può essere assente |
2630| `teammate_name` | Nome del compagno di squadra che crea l'attività. Può essere assente |2632| `teammate_name` | Nome del compagno di team che crea il task. Può essere assente |
2631| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |2633| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |
2632 2634
2633<h4 id="taskcreated-decision-control">2635<h4 id="taskcreated-decision-control">
2634 Controllo decisionale TaskCreated2636 Controllo delle decisioni di TaskCreated
2635</h4>2637</h4>
2636 2638
2637Un 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.2639Un 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.
2638 2640
2639* **Codice di uscita 2**: Claude Code restituisce il testo stderr come messaggio.2641* **Codice di uscita 2**: Claude Code restituisce il testo di stderr come messaggio.
2640* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code restituisce `reason` come messaggio.2642* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code restituisce `reason` come messaggio.
2641 2643
2642Questo esempio blocca le attività i cui soggetti non seguono il formato richiesto:2644Questo esempio blocca i task i cui oggetti non seguono il formato richiesto:
2643 2645
2644```bash theme={null}2646```bash theme={null}
2645#!/bin/bash2647#!/bin/bash
2658 TaskCompleted2660 TaskCompleted
2659</h3>2661</h3>
2660 2662
2661Si esegue quando un'attività viene contrassegnata come completata. Questo si esegue in due situazioni: quando qualsiasi agente contrassegna esplicitamente un'attività come completata tramite lo strumento TaskUpdate, o quando un compagno di squadra dell'[agente team](/docs/it/agent-teams) finisce il suo turno con attività in corso. Usalo per applicare criteri di completamento come il passaggio dei test o dei controlli lint prima che un'attività possa chiudersi.2663Viene 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.
2662 2664
2663Gli hook TaskCompleted non supportano i matcher e si eseguono su ogni occorrenza.2665Gli hook TaskCompleted non supportano i matcher e si attivano a ogni occorrenza.
2664 2666
2665<h4 id="taskcompleted-input">2667<h4 id="taskcompleted-input">
2666 Input TaskCompleted2668 Input di TaskCompleted
2667</h4>2669</h4>
2668 2670
2669Oltre ai [campi di input comuni](#common-input-fields), gli hook TaskCompleted ricevono `task_id`, `task_subject`, e facoltativamente `task_description`, `teammate_name`, e `team_name`.2671Oltre ai [campi di input comuni](#common-input-fields), gli hook TaskCompleted ricevono `task_id`, `task_subject` e, facoltativamente, `task_description`, `teammate_name` e `team_name`.
2670 2672
2671```json theme={null}2673```json theme={null}
2672{2674{
2685 2687
2686| Campo | Descrizione |2688| Campo | Descrizione |
2687| :- | :- |2689| :- | :- |
2688| `task_id` | Identificatore dell'attività in fase di completamento |2690| `task_id` | Identificatore del task in fase di completamento |
2689| `task_subject` | Titolo dell'attività |2691| `task_subject` | Titolo del task |
2690| `task_description` | Descrizione dettagliata dell'attività. Può essere assente |2692| `task_description` | Descrizione dettagliata del task. Può essere assente |
2691| `teammate_name` | Nome del compagno di squadra che completa l'attività. Può essere assente |2693| `teammate_name` | Nome del compagno di team che completa il task. Può essere assente |
2692| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |2694| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |
2693 2695
2694<h4 id="taskcompleted-decision-control">2696<h4 id="taskcompleted-decision-control">
2695 Controllo decisionale TaskCompleted2697 Controllo delle decisioni di TaskCompleted
2696</h4>2698</h4>
2697 2699
2698Gli hook TaskCompleted supportano due modi per controllare il completamento dell'attività:2700Gli hook TaskCompleted supportano due modi per controllare il completamento dei task:
2699 2701
2700* **Codice di uscita 2**: l'attività non viene contrassegnata come completata e il messaggio stderr viene restituito al modello come feedback.2702* **Codice di uscita 2**: il task non viene contrassegnato come completato e il messaggio stderr viene restituito al modello come feedback.
2701* **JSON `{"continue": false, "stopReason": "..."}`**: quando un compagno di squadra che finisce il suo turno ha attivato l'evento, ferma completamente il compagno di squadra, corrispondendo al comportamento dell'hook `Stop`. Il `stopReason` viene mostrato all'utente. Quando lo strumento `TaskUpdate` ha attivato l'evento, Claude Code ignora `continue: false`; il codice di uscita 2 blocca comunque il completamento.2703* **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.
2702 2704
2703Questo esempio esegue i test e blocca il completamento dell'attività se falliscono:2705Questo esempio esegue i test e blocca il completamento del task se falliscono:
2704 2706
2705```bash theme={null}2707```bash theme={null}
2706#!/bin/bash2708#!/bin/bash
2720 Stop2722 Stop
2721</h3>2723</h3>
2722 2724
2723Si esegue quando l'agente Claude Code principale ha finito di rispondere. Non si esegue se l'arresto è av venuto a causa di un'interruzione dell'utente. Gli errori API eseguono [StopFailure](#stopfailure) invece.2725Viene eseguito quando l'agente principale di Claude Code ha finito di rispondere. Non viene eseguito se
2726l'arresto è avvenuto a causa di un'interruzione da parte dell'utente. Gli errori API attivano
2727invece [StopFailure](#stopfailure).
2724 2728
2725<Tip>2729<Tip>
2726 Il comando [`/goal`](/docs/it/goal) è un collegamento incorporato per un hook Stop con ambito di sessione basato su prompt. Usalo quando vuoi che Claude continui a lavorare verso una condizione senza scrivere la configurazione dell'hook.2730 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.
2727</Tip>2731</Tip>
2728 2732
2729<h4 id="stop-input">2733<h4 id="stop-input">
2730 Input Stop2734 Input di Stop
2731</h4>2735</h4>
2732 2736
2733Oltre 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 come risultato di un hook stop. Controlla questo valore o elabora la trascrizione per evitare di bloccarsi su una condizione che non si risolverà mai. Claude Code applica un limite di 8 continuazioni consecutive: dopo che gli hook stop hanno continuato il turno otto volte di fila, Claude Code sovrascrive il blocco successivo e termina il turno. Per aumentare il limite, imposta [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/it/env-vars).2737Oltre 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. Claude Code applica un limite di 8 prosecuzioni consecutive: dopo che gli stop hook hanno fatto proseguire il turno otto volte di fila, Claude Code sovrascrive il blocco successivo e termina il turno. Per aumentare il limite, imposta [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/it/env-vars).
2734 2738
2735Il campo `last_assistant_message` contiene il contenuto di testo della risposta finale di Claude, quindi gli hook possono accedervi senza analizzare il file di trascrizione. Per gli hook che agiscono sul turno appena completato, come gli hook di lettura ad alta voce o notifica, usa questo campo piuttosto che leggere `transcript_path`: il file di trascrizione non è garantito di includere il messaggio finale al momento di Stop su tutte le versioni.2739Il 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.
2736 2740
2737Gli array `background_tasks` e `session_crons` consentono agli hook di distinguere "la sessione è finita" da "la sessione è in pausa in attesa che il lavoro di background la risvegli di nuovo". Entrambi gli array sono presenti quando il registro delle attività è raggiungibile e sono vuoti quando nulla è in volo o programmato.2741Gli 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.
2738 2742
2739Ogni voce in `background_tasks` descrive un'attività in volo e usa questi campi:2743Ogni voce in `background_tasks` descrive un task in corso e usa questi campi:
2740 2744
2741| Campo | Descrizione |2745| Campo | Descrizione |
2742| :- | :- |2746| :- | :- |
2743| `id` | Identificatore dell'attività |2747| `id` | Identificatore del task |
2744| `type` | Etichetta del tipo di attività amichevole come `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session`, o `MCP task`. Ogni etichetta identifica quale funzionalità di Claude Code ha creato l'attività. Ritorna al discriminante grezzo per i tipi non riconosciuti |2748| `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 |
2745| `status` | Stato dell'attività corrente |2749| `status` | Stato attuale del task |
2746| `description` | Descrizione in testo libero, limitata a 1000 caratteri con un marcatore `… [+N chars]` in-stringa quando ritagliato |2750| `description` | Descrizione in testo libero, limitata a 1000 caratteri con un indicatore `… [+N chars]` all'interno della stringa quando viene troncata |
2747| `command` | Riga di comando shell, limitata a 1000 caratteri. Presente solo per le attività `shell` |2751| `command` | Riga di comando della shell, limitata a 1000 caratteri. Presente solo per i task `shell` |
2748| `agent_type` | Nome del tipo di subagente. Presente solo per le attività `subagent` |2752| `agent_type` | Nome del tipo di subagent. Presente solo per i task `subagent` |
2749| `server` | Nome del server MCP. Presente solo per le attività `monitor` e `MCP task` |2753| `server` | Nome del server MCP. Presente solo per i task `monitor` e `MCP task` |
2750| `tool` | Nome dello strumento MCP. Presente solo per le attività `monitor` e `MCP task` |2754| `tool` | Nome dello strumento MCP. Presente solo per i task `monitor` e `MCP task` |
2751| `name` | Nome del workflow. Presente solo per le attività `workflow` |2755| `name` | Nome del workflow. Presente solo per i task `workflow` |
2752 2756
2753Ogni voce in `session_crons` descrive un risveglio programmato con ambito di sessione, proveniente da `CronCreate`, `ScheduleWakeup`, e `/loop`:2757Ogni voce in `session_crons` descrive una riattivazione pianificata con ambito di sessione, proveniente da `CronCreate`, `ScheduleWakeup` e `/loop`:
2754 2758
2755| Campo | Descrizione |2759| Campo | Descrizione |
2756| :- | :- |2760| :- | :- |
2757| `id` | Identificatore dell'attività cron |2761| `id` | Identificatore del task cron |
2758| `schedule` | Espressione cron, ad esempio `0 9 * * 1-5` |2762| `schedule` | Espressione cron, ad esempio `0 9 * * 1-5` |
2759| `recurring` | `false` per i risvegli una tantum il cui programma codifica un singolo tempo di attivazione, `true` per le attività che si riattivano su ogni corrispondenza |2763| `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 |
2760| `prompt` | Prompt inviato quando il cron si attiva, limitato a 1000 caratteri con lo stesso marcatore `… [+N chars]` |2764| `prompt` | Prompt inviato quando il cron si attiva, limitato a 1000 caratteri con lo stesso indicatore `… [+N chars]` |
2761 2765
2762Questo esempio mostra un input Stop con un'attività shell in volo e un cron ricorrente:2766Questo esempio mostra un input di Stop con un task shell in corso e un cron ricorrente:
2763 2767
2764```json theme={null}2768```json theme={null}
2765{2769{
2791```2795```
2792 2796
2793<h4 id="stop-decision-control">2797<h4 id="stop-decision-control">
2794 Controllo decisionale Stop2798 Controllo delle decisioni di Stop
2795</h4>2799</h4>
2796 2800
2797Gli 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 hook può restituire questi campi specifici dell'evento:2801Gli 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:
2798 2802
2799| Campo | Descrizione |2803| Campo | Descrizione |
2800| :- | :- |2804| :- | :- |
2801| `decision` | `"block"` impedisce a Claude di fermarsi. Ometti per consentire a Claude di fermarsi |2805| `decision` | `"block"` impedisce a Claude di fermarsi. Omettilo per consentire a Claude di fermarsi |
2802| `reason` | Richiesto quando `decision` è `"block"`. Dice a Claude perché dovrebbe continuare |2806| `reason` | Obbligatorio quando `decision` è `"block"`. Indica a Claude perché deve proseguire |
2803| `hookSpecificOutput.additionalContext` | Feedback non di errore per Claude. La conversazione continua in modo che Claude possa agire su di esso, ma a differenza di `decision: "block"` viene mostrato nella trascrizione come feedback dell'hook piuttosto che un errore dell'hook |2807| `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 |
2804 2808
2805Un hook che blocca uscendo con 2 si instrada allo stesso modo di `reason`: Claude riceve il messaggio stderr come la spiegazione del perché dovrebbe continuare.2809Un 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.
2806 2810
2807```json theme={null}2811```json theme={null}
2808{2812{
2811}2815}
2812```2816```
2813 2817
2814Usa `additionalContext` quando l'hook funziona come progettato e dà a Claude una guida, come "esegui la suite di test prima di finire". Mantiene la conversazione attraverso gli stessi loop protections di `decision: "block"`, vale a dire l'input `stop_hook_active` e il limite di 8 continuazioni consecutive, ma la trascrizione lo etichetta come `Stop hook feedback` e nessuna notifica di errore dell'hook viene mostrata:2818Usa `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:
2815 2819
2816```json theme={null}2820```json theme={null}
2817{2821{
2826 StopFailure2830 StopFailure
2827</h3>2831</h3>
2828 2832
2829Si esegue invece di [Stop](#stop) quando il turno termina a causa di un errore API. Claude Code ignora l'output e il codice di uscita dell'hook, a parte [`terminalSequence`](#emit-terminal-notifications). Usalo per registrare i fallimenti, inviare avvisi, o intraprendere azioni di recupero quando Claude non può completare una risposta a causa di limiti di velocità, problemi di autenticazione, o altri errori API.2833Viene eseguito al posto di [Stop](#stop) quando il turno termina a causa di un errore API. Claude Code ignora l'output e il codice di uscita dell'hook, a parte [`terminalSequence`](#emit-terminal-notifications). Usalo per registrare i fallimenti, inviare avvisi o intraprendere azioni di ripristino quando Claude non riesce a completare una risposta a causa di rate limit, problemi di autenticazione o altri errori API.
2830 2834
2831<h4 id="stopfailure-input">2835<h4 id="stopfailure-input">
2832 Input StopFailure2836 Input di StopFailure
2833</h4>2837</h4>
2834 2838
2835Oltre 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 filtraggio del matcher.2839Oltre 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.
2836 2840
2837| Campo | Descrizione |2841| Campo | Descrizione |
2838| :- | :- |2842| :- | :- |
2839| `error` | Tipo di errore: `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, o `unknown` |2843| `error` | Tipo di errore: `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error` o `unknown` |
2840| `error_details` | Dettagli aggiuntivi sull'errore, quando disponibili |2844| `error_details` | Dettagli aggiuntivi sull'errore, quando disponibili |
2841| `last_assistant_message` | Il testo di errore renderizzato mostrato nella conversazione. A differenza di `Stop` e `SubagentStop`, dove questo campo contiene l'output conversazionale di Claude, per `StopFailure` contiene la stringa di errore API stessa, come `"API Error: Rate limit reached"` |2845| `last_assistant_message` | Il testo dell'errore visualizzato nella conversazione. A differenza di `Stop` e `SubagentStop`, dove questo campo contiene l'output conversazionale di Claude, per `StopFailure` contiene la stringa dell'errore API stessa, come `"API Error: Rate limit reached"` |
2842 2846
2843```json theme={null}2847```json theme={null}
2844{2848{
2852}2856}
2853```2857```
2854 2858
2855Gli hook StopFailure non hanno controllo decisionale. Si eseguono solo per scopi di notifica e logging.2859Gli hook StopFailure non hanno controllo delle decisioni. Vengono eseguiti solo a scopo di notifica e di log.
2856 2860
2857<h3 id="teammateidle">2861<h3 id="teammateidle">
2858 TeammateIdle2862 TeammateIdle
2859</h3>2863</h3>
2860 2864
2861Si esegue quando un compagno di squadra dell'[agente team](/docs/it/agent-teams) sta per andare inattivo dopo aver finito il suo turno. Usalo per applicare gate di qualità prima che un compagno di squadra smetta di lavorare, come richiedere il passaggio dei controlli lint o verificare che i file di output esistano.2865Viene 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.
2862 2866
2863Gli hook TeammateIdle non supportano i matcher e si eseguono su ogni occorrenza.2867Gli hook TeammateIdle non supportano i matcher e si attivano a ogni occorrenza.
2864 2868
2865<h4 id="teammateidle-input">2869<h4 id="teammateidle-input">
2866 Input TeammateIdle2870 Input di TeammateIdle
2867</h4>2871</h4>
2868 2872
2869Oltre ai [campi di input comuni](#common-input-fields), gli hook TeammateIdle ricevono `teammate_name` e `team_name`.2873Oltre ai [campi di input comuni](#common-input-fields), gli hook TeammateIdle ricevono `teammate_name` e `team_name`.
2882 2886
2883| Campo | Descrizione |2887| Campo | Descrizione |
2884| :- | :- |2888| :- | :- |
2885| `teammate_name` | Nome del compagno di squadra che sta per andare inattivo |2889| `teammate_name` | Nome del compagno di team che sta per diventare inattivo |
2886| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |2890| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |
2887 2891
2888<h4 id="teammateidle-decision-control">2892<h4 id="teammateidle-decision-control">
2889 Controllo decisionale TeammateIdle2893 Controllo delle decisioni di TeammateIdle
2890</h4>2894</h4>
2891 2895
2892Gli hook TeammateIdle supportano due modi per controllare il comportamento del compagno di squadra:2896Gli hook TeammateIdle supportano due modi per controllare il comportamento dei compagni di team:
2893 2897
2894* **Codice di uscita 2**: il compagno di squadra riceve il messaggio stderr come feedback e continua a lavorare invece di andare inattivo.2898* **Codice di uscita 2**: il compagno di team riceve il messaggio stderr come feedback e continua a lavorare invece di diventare inattivo.
2895* **JSON `{"continue": false, "stopReason": "..."}`**: ferma completamente il compagno di squadra, corrispondendo al comportamento dell'hook `Stop`. Il `stopReason` viene mostrato all'utente.2899* **JSON `{"continue": false, "stopReason": "..."}`**: ferma completamente il compagno di team, in modo analogo al comportamento dell'hook `Stop`. Lo `stopReason` viene mostrato all'utente.
2896 2900
2897Questo esempio controlla che un artefatto di build esista prima di consentire a un compagno di squadra di andare inattivo:2901Questo esempio verifica che un artefatto di build esista prima di consentire a un compagno di team di diventare inattivo:
2898 2902
2899```bash theme={null}2903```bash theme={null}
2900#!/bin/bash2904#!/bin/bash
2911 ConfigChange2915 ConfigChange
2912</h3>2916</h3>
2913 2917
2914Si esegue quando un file di configurazione cambia durante una sessione. Usalo per controllare i cambiamenti delle impostazioni, applicare policy di sicurezza, o bloccare modifiche non autorizzate ai file di configurazione.2918Viene 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.
2915 2919
2916Claude Code esegue gli hook ConfigChange quando un file di impostazioni, un file di policy gestito, o un file di skill cambia. Per la policy gestita, li esegue solo quando `managed-settings.json` o un file in `managed-settings.d/` cambia. Applica le [impostazioni gestite dal server](/docs/it/server-managed-settings) e i cambiamenti alle preferenze gestite di macOS o alla policy del registro di Windows senza eseguirli. Su WSL con [`wslInheritsWindowsSettings`](/docs/it/settings-reference#wslinheritswindowssettings), applica anche un file di impostazioni gestite di Windows modificato sul suo sondaggio di policy senza eseguirli.2920Claude 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.
2917 2921
2918Il matcher filtra sulla fonte di configurazione:2922Il matcher filtra in base all'origine della configurazione:
2919 2923
2920| Matcher | Quando si attiva |2924| Matcher | Quando si attiva |
2921| :- | :- |2925| :- | :- |
2922| `user_settings` | `~/.claude/settings.json` cambia |2926| `user_settings` | Cambia `~/.claude/settings.json` |
2923| `project_settings` | `.claude/settings.json` cambia |2927| `project_settings` | Cambia `.claude/settings.json` |
2924| `local_settings` | `.claude/settings.local.json` cambia |2928| `local_settings` | Cambia `.claude/settings.local.json` |
2925| `policy_settings` | `managed-settings.json` o un file in `managed-settings.d/` cambia |2929| `policy_settings` | Cambia `managed-settings.json` o un file in `managed-settings.d/` |
2926| `skills` | Un file di skill in `.claude/skills/` cambia |2930| `skills` | Cambia un file di skill in `.claude/skills/` |
2927 2931
2928Questo esempio registra tutti i cambiamenti di configurazione per il controllo di sicurezza:2932Questo esempio registra tutte le modifiche alla configurazione per la verifica della sicurezza:
2929 2933
2930```json theme={null}2934```json theme={null}
2931{2935{
2946```2950```
2947 2951
2948<h4 id="configchange-input">2952<h4 id="configchange-input">
2949 Input ConfigChange2953 Input di ConfigChange
2950</h4>2954</h4>
2951 2955
2952Oltre 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 al file specifico che è stato modificato.2956Oltre 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.
2953 2957
2954```json theme={null}2958```json theme={null}
2955{2959{
2963```2967```
2964 2968
2965<h4 id="configchange-decision-control">2969<h4 id="configchange-decision-control">
2966 Controllo decisionale ConfigChange2970 Controllo delle decisioni di ConfigChange
2967</h4>2971</h4>
2968 2972
2969Gli hook ConfigChange possono bloccare i cambiamenti di configurazione dal prendere effetto. Usa il codice di uscita 2 o un JSON `decision` per prevenire il cambio. Quando bloccato, le nuove impostazioni non vengono applicate alla sessione in esecuzione.2973Gli hook ConfigChange possono impedire che le modifiche alla configurazione abbiano effetto. Usa il codice di uscita 2 o una `decision` JSON per impedire la modifica. Quando viene bloccata, le nuove impostazioni non vengono applicate alla sessione in esecuzione.
2970 2974
2971| Campo | Descrizione |2975| Campo | Descrizione |
2972| :- | :- |2976| :- | :- |
2973| `decision` | `"block"` impedisce l'applicazione del cambio di configurazione. Ometti per consentire il cambio |2977| `decision` | `"block"` impedisce che la modifica alla configurazione venga applicata. Omettilo per consentire la modifica |
2974| `reason` | Accettato ma mai mostrato |2978| `reason` | Accettato ma mai mostrato |
2975 2979
2976```json theme={null}2980```json theme={null}
2980}2984}
2981```2985```
2982 2986
2983I cambiamenti di `policy_settings` non possono essere bloccati. Gli hook si eseguono comunque per le fonti `policy_settings` quando un file di impostazioni gestite sulla macchina cambia, quindi puoi usarli per registrare quelle modifiche, ma qualsiasi decisione di blocco viene ignorata. Questo assicura 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 si aggiornano.2987Le 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.
2984 2988
2985Claude Code agisce sulla decisione di blocco dall'output JSON di un hook ConfigChange e scarta `systemMessage` e `continue`. Un cambio bloccato non mostra alcun messaggio a te o a Claude, indipendentemente dal fatto che blocchi con `reason` o con stderr all'uscita 2. Claude Code scrive solo una riga nel debug log.2989Claude 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.
2986 2990
2987<h3 id="cwdchanged">2991<h3 id="cwdchanged">
2988 CwdChanged2992 CwdChanged
2989</h3>2993</h3>
2990 2994
2991Si esegue quando un comando shell nella conversazione principale cambia la directory di lavoro, ad esempio quando Claude esegue un comando `cd`. Usalo per reagire ai cambiamenti di directory: ricaricare le variabili di ambiente, attivare toolchain specifiche del progetto, o eseguire script di configurazione automaticamente. Si accoppia con [FileChanged](#filechanged) per strumenti come [direnv](https://direnv.net/) che gestiscono l'ambiente per directory.2995Viene eseguito quando un comando della shell nella conversazione principale cambia la directory di lavoro, ad esempio quando Claude esegue un comando `cd`. Usalo per reagire ai cambi di directory: ricaricare le variabili d'ambiente, attivare toolchain specifiche del progetto o eseguire automaticamente script di configurazione. Si abbina a [FileChanged](#filechanged) per strumenti come [direnv](https://direnv.net/) che gestiscono l'ambiente per directory.
2992 2996
2993Gli hook CwdChanged hanno accesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Le variabili scritte in quel file persistono nei comandi Bash successivi finché il prossimo evento CwdChanged, quando Claude Code le cancella.2997Gli hook CwdChanged 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, quando Claude Code le cancella.
2994 2998
2995CwdChanged non supporta i matcher e si esegue su ogni occorrenza.2999CwdChanged non supporta i matcher e si attiva a ogni occorrenza.
2996 3000
2997<h4 id="cwdchanged-input">3001<h4 id="cwdchanged-input">
2998 Input CwdChanged3002 Input di CwdChanged
2999</h4>3003</h4>
3000 3004
3001Oltre ai [campi di input comuni](#common-input-fields), gli hook CwdChanged ricevono `old_cwd` e `new_cwd`.3005Oltre ai [campi di input comuni](#common-input-fields), gli hook CwdChanged ricevono `old_cwd` e `new_cwd`.
3012```3016```
3013 3017
3014<h4 id="cwdchanged-output">3018<h4 id="cwdchanged-output">
3015 Output CwdChanged3019 Output di CwdChanged
3016</h4>3020</h4>
3017 3021
3018Oltre 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) osserva:3022Oltre 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:
3019 3023
3020| Campo | Descrizione |3024| Campo | Descrizione |
3021| :- | :- |3025| :- | :- |
3022| `watchPaths` | Array di percorsi assoluti. Sostituisce l'elenco di osservazione dinamico corrente. I percorsi dalla tua configurazione `matcher` vengono sempre osservati. Restituire un array vuoto cancella l'elenco dinamico, che è tipico quando si entra in una nuova directory |3026| `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 |
3023 3027
3024Gli hook CwdChanged non hanno controllo decisionale. Non possono bloccare il cambio di directory.3028Gli hook CwdChanged non hanno controllo delle decisioni. Non possono bloccare il cambio di directory.
3025 3029
3026Claude Code legge `watchPaths` e `systemMessage` dal loro output JSON e scarta `continue`. Nelle sessioni interattive, mostra il `systemMessage` come una breve notifica di terminale. Il messaggio non raggiunge il flusso di messaggi dell'SDK.3030Claude Code legge `watchPaths` e `systemMessage` dal loro output JSON e scarta `continue`. Nelle sessioni interattive, mostra il `systemMessage` come breve notifica nel terminale. Il messaggio non raggiunge il flusso di messaggi dell'SDK.
3027 3031
3028<h3 id="directoryadded">3032<h3 id="directoryadded">
3029 DirectoryAdded3033 DirectoryAdded
3030</h3>3034</h3>
3031 3035
3032Si esegue dopo che aggiungi una directory di lavoro a metà sessione 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 installando le sue dipendenze.3036Viene 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.
3033 3037
3034Claude Code non esegue questo evento quando:3038Claude Code non attiva questo evento quando:
3035 3039
3036* Passi una directory con il flag di avvio `--add-dir`; [SessionStart](#sessionstart) copre quelle directory3040* Passi una directory con il flag di avvio `--add-dir`; [SessionStart](#sessionstart) copre quelle directory
3037* Aggiungi una directory sulla scheda Workspace `/permissions`3041* Aggiungi una directory nella scheda Workspace di `/permissions`
3038* Aggiungi una directory che è già una directory di lavoro o dentro una3042* Aggiungi una directory che è già una directory di lavoro o che si trova all'interno di una
3039 3043
3040Claude Code esegue DirectoryAdded dopo aver aggiornato lo stato della sandbox e del permesso, quindi gli strumenti sandboxed vedono già la nuova directory quando il tuo hook si esegue. I comandi dell'hook stessi si eseguono non sandboxed.3044Claude 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.
3041 3045
3042Claude Code non attende l'hook: l'aggiunta completa immediatamente, e l'hook si esegue in background con il timeout predefinito di 600 secondi.3046Claude Code non attende l'hook: l'aggiunta viene completata immediatamente e l'hook viene eseguito in background con il timeout predefinito di 600 secondi.
3043 3047
3044Il matcher filtra su come la directory è stata aggiunta:3048Il matcher filtra in base a come è stata aggiunta la directory:
3045 3049
3046| Matcher | Quando si attiva |3050| Matcher | Quando si attiva |
3047| :- | :- |3051| :- | :- |
3049| `register_repo_root` | Un client SDK aggiunge una directory con la richiesta di controllo `register_repo_root` |3053| `register_repo_root` | Un client SDK aggiunge una directory con la richiesta di controllo `register_repo_root` |
3050 3054
3051<h4 id="directoryadded-input">3055<h4 id="directoryadded-input">
3052 Input DirectoryAdded3056 Input di DirectoryAdded
3053</h4>3057</h4>
3054 3058
3055Oltre ai [campi di input comuni](#common-input-fields), gli hook DirectoryAdded ricevono `directory` e `source`.3059Oltre ai [campi di input comuni](#common-input-fields), gli hook DirectoryAdded ricevono `directory` e `source`.
3056 3060
3057| Campo | Descrizione |3061| Campo | Descrizione |
3058| :- | :- |3062| :- | :- |
3059| `directory` | Percorso assoluto della directory che è stata aggiunta |3063| `directory` | Percorso assoluto della directory aggiunta |
3060| `source` | Come la directory è stata aggiunta, `"slash_command"` per `/add-dir` o `"register_repo_root"` per la richiesta di controllo dell'SDK |3064| `source` | Come è stata aggiunta la directory, `"slash_command"` per `/add-dir` o `"register_repo_root"` per la richiesta di controllo dell'SDK |
3061 3065
3062```json theme={null}3066```json theme={null}
3063{3067{
3070}3074}
3071```3075```
3072 3076
3073Gli hook DirectoryAdded non hanno controllo decisionale. Non possono bloccare l'aggiunta, che si è già completata quando l'hook si esegue. Claude Code scarta il campo `continue` dal loro output JSON e visualizza il resto diversamente per fonte:3077Gli 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:
3074 3078
3075* `slash_command`: Claude Code consegna il `systemMessage` dell'hook a Claude come contesto sul turno di conversazione successivo, piuttosto che mostrartelo. Un conteggio degli hook falliti appare nella trascrizione. L'output di fallimento completo va nel debug log3079* `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 debug
3076* `register_repo_root`: Claude Code scrive l'output `systemMessage` e l'output di fallimento nel debug log solo3080* `register_repo_root`: Claude Code scrive l'output di `systemMessage` e l'output dei fallimenti solo nel log di debug
3077 3081
3078<h3 id="filechanged">3082<h3 id="filechanged">
3079 FileChanged3083 FileChanged
3080</h3>3084</h3>
3081 3085
3082Si esegue quando un file osservato cambia su disco. Claude Code rileva i cambiamenti con un osservatore del file system, non ispezionando le chiamate di strumento, quindi esegue l'hook indipendentemente da cosa ha cambiato il file: una chiamata di strumento `Edit` o `Write`, uno script che Claude esegue con `Bash`, o un processo al di fuori di Claude Code interamente. Un uso comune è ricaricare le variabili di ambiente quando i file di configurazione del progetto cambiano.3086Viene 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.
3083 3087
3084Il `matcher` per questo evento serve due ruoli:3088Il `matcher` per questo evento svolge due ruoli:
3085 3089
3086* **Costruisci l'elenco di osservazione**: il valore viene diviso su `|` e ogni segmento viene registrato come un nome di file letterale nella directory di lavoro, quindi `".envrc|.env"` osserva esattamente quei due file. I modelli regex non sono utili qui: un valore come `^\.env` osserverebbe un file letteralmente denominato `^\.env`.3090* **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`.
3087* **Filtra quali hook si eseguono**: quando un file osservato cambia, lo stesso valore filtra quali gruppi di hook si eseguono usando le [regole di matcher](#matcher-patterns) standard rispetto al basename del file modificato.3091* **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.
3088 3092
3089Questo esempio normalizza le terminazioni di riga in `data.csv` dopo qualsiasi cambio, incluso un comando `Bash` o uno script esterno che riscrive il file:3093Questo 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:
3090 3094
3091```json theme={null}3095```json theme={null}
3092{3096{
3106}3110}
3107```3111```
3108 3112
3109L'hook legge il percorso assoluto del file modificato dal campo `file_path` dell'[input JSON](#filechanged-input) su stdin. La sua guardia `grep` testa la stessa cosa che `perl` rimuove, un CR alla fine di una riga, quindi l'esecuzione dopo una normalizzazione esce senza toccare il file. Una guardia più sciolta si cicla per sempre, perché `perl -i` riscrive il file anche quando non sostituisce nulla e Claude Code esegue l'hook di nuovo dopo ogni riscrittura. Salva questo script in `/path/to/normalize-line-endings.sh` e rendilo eseguibile:3113L'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:
3110 3114
3111```bash theme={null}3115```bash theme={null}
3112#!/bin/bash3116#!/bin/bash
3116fi3120fi
3117```3121```
3118 3122
3119Per confermare che l'hook funziona, 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 terminazioni LF.3123Per 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.
3120 3124
3121Per osservare i file che non puoi nominare in anticipo, restituisci [`watchPaths`](#filechanged-output) da un hook per aggiornare l'elenco di osservazione dinamicamente. Claude Code avvia l'osservatore solo quando qualcosa nomina un file da osservare, quindi semina l'elenco con un gruppo FileChanged il cui matcher nomina almeno un file, o con un hook [SessionStart](#sessionstart-decision-control) o [CwdChanged](#cwdchanged-output) che restituisce `watchPaths`. Il matcher filtra comunque quali gruppi di hook si eseguono quando un file osservato cambia, quindi dai al gruppo che gestisce i percorsi dinamici un matcher omesso, che corrisponde a ogni file osservato e non aggiunge nulla all'elenco di osservazione. Un matcher `"*"` corrisponde anche a ogni file, ma Claude Code lo registra nell'elenco di osservazione come qualsiasi altro valore, come un file letterale denominato `*`.3125Per 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 `*`.
3122 3126
3123Gli hook FileChanged hanno accesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Le variabili scritte in quel file persistono nei comandi Bash successivi finché il prossimo evento [CwdChanged](#cwdchanged), quando Claude Code le cancella.3127Gli 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.
3124 3128
3125<h4 id="filechanged-input">3129<h4 id="filechanged-input">
3126 Input FileChanged3130 Input di FileChanged
3127</h4>3131</h4>
3128 3132
3129Oltre ai [campi di input comuni](#common-input-fields), gli hook FileChanged ricevono `file_path` e `event`.3133Oltre ai [campi di input comuni](#common-input-fields), gli hook FileChanged ricevono `file_path` ed `event`.
3130 3134
3131| Campo | Descrizione |3135| Campo | Descrizione |
3132| :- | :- |3136| :- | :- |
3133| `file_path` | Percorso assoluto al file che è cambiato |3137| `file_path` | Percorso assoluto del file modificato |
3134| `event` | Cosa è accaduto: `"change"` per un file modificato, `"add"` per un file creato, o `"unlink"` per un file eliminato |3138| `event` | Cosa è successo: `"change"` per un file modificato, `"add"` per un file creato o `"unlink"` per un file eliminato |
3135 3139
3136```json theme={null}3140```json theme={null}
3137{3141{
3145```3149```
3146 3150
3147<h4 id="filechanged-output">3151<h4 id="filechanged-output">
3148 Output FileChanged3152 Output di FileChanged
3149</h4>3153</h4>
3150 3154
3151Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, gli hook FileChanged possono restituire `watchPaths` per aggiornare dinamicamente quali percorsi di file vengono osservati:3155Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, gli hook FileChanged possono restituire `watchPaths` per aggiornare dinamicamente quali percorsi di file vengono monitorati:
3152 3156
3153| Campo | Descrizione |3157| Campo | Descrizione |
3154| :- | :- |3158| :- | :- |
3155| `watchPaths` | Array di percorsi assoluti. Sostituisce l'elenco di osservazione dinamico corrente. I percorsi dalla tua configurazione `matcher` vengono sempre osservati. Usalo quando il tuo script hook scopre file aggiuntivi da osservare in base al file modificato |3159| `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 |
3156 3160
3157Gli hook FileChanged non hanno controllo decisionale. Non possono bloccare il cambio del file dal verificarsi.3161Gli hook FileChanged non hanno controllo delle decisioni. Non possono impedire che la modifica del file avvenga.
3158 3162
3159Claude Code legge `watchPaths` e `systemMessage` dal loro output JSON e scarta `continue`. Nelle sessioni interattive, mostra il `systemMessage` come una breve notifica di terminale. Il messaggio non raggiunge il flusso di messaggi dell'SDK.3163Claude Code legge `watchPaths` e `systemMessage` dal loro output JSON e scarta `continue`. Nelle sessioni interattive, mostra il `systemMessage` come breve notifica nel terminale. Il messaggio non raggiunge il flusso di messaggi dell'SDK.
3160 3164
3161<h3 id="worktreecreate">3165<h3 id="worktreecreate">
3162 WorktreeCreate3166 WorktreeCreate
3163</h3>3167</h3>
3164 3168
3165Si esegue quando un worktree viene creato, sia da `claude --worktree`, da un [subagente che usa `isolation: "worktree"`](/docs/it/sub-agents#choose-the-subagent-scope), o per una [sessione di background](/docs/it/agent-view#how-file-edits-are-isolated) che Claude Code isola nel suo 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, permettendoti di usare un sistema di controllo della versione diverso come SVN, Perforce, o Mercurial.3169Viene 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.
3166 3170
3167Poiché l'hook sostituisce completamente il comportamento predefinito, [`.worktreeinclude`](/docs/it/worktrees#copy-gitignored-files-into-worktrees) non viene elaborato. Se hai bisogno di copiare file di configurazione locali come `.env` nel nuovo worktree, fallo dentro il tuo script hook.3171Poiché 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.
3168 3172
3169L'hook deve restituire il percorso alla directory del worktree creato. Claude Code usa questo percorso come directory di lavoro per la sessione isolata. Vedi [Output WorktreeCreate](#worktreecreate-output) per come ogni tipo di hook restituisce il percorso.3173L'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.
3170 3174
3171Claude Code agisce sul successo dell'hook e sul percorso restituito, e scarta `systemMessage` e `continue`.3175Claude Code agisce sull'esito positivo dell'hook e sul percorso restituito, e scarta `systemMessage` e `continue`.
3172 3176
3173Questo esempio crea una copia di lavoro SVN e stampa il percorso per Claude Code da usare. Sostituisci l'URL del repository con il tuo:3177Questo esempio crea una copia di lavoro SVN e stampa il percorso che Claude Code deve usare. Sostituisci l'URL del repository con il tuo:
3174 3178
3175```json theme={null}3179```json theme={null}
3176{3180{
3189}3193}
3190```3194```
3191 3195
3192L'hook legge il `name` del worktree dall'input JSON su stdin, controlla una copia fresca in una nuova directory, e stampa il percorso della directory. L'`echo` sull'ultima riga è ciò che Claude Code legge come il percorso del worktree. Reindirizza qualsiasi altro output a stderr in modo che non interferisca con il percorso.3196L'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.
3193 3197
3194<h4 id="worktreecreate-input">3198<h4 id="worktreecreate-input">
3195 Input WorktreeCreate3199 Input di WorktreeCreate
3196</h4>3200</h4>
3197 3201
3198Oltre ai [campi di input comuni](#common-input-fields), gli hook WorktreeCreate ricevono il campo `name`. Questo è un identificatore slug per il nuovo worktree, specificato dall'utente o auto-generato, ad esempio `bold-oak-a3f2`.3202Oltre ai [campi di input comuni](#common-input-fields), gli hook WorktreeCreate ricevono il campo `name`. Si tratta di un identificatore slug per il nuovo worktree, specificato dall'utente o generato automaticamente, ad esempio `bold-oak-a3f2`.
3199 3203
3200```json theme={null}3204```json theme={null}
3201{3205{
3208```3212```
3209 3213
3210<h4 id="worktreecreate-output">3214<h4 id="worktreecreate-output">
3211 Output WorktreeCreate3215 Output di WorktreeCreate
3212</h4>3216</h4>
3213 3217
3214Gli hook WorktreeCreate non usano il modello di decisione standard consenti/blocca. Invece, il successo o il fallimento dell'hook determina il risultato. L'hook deve restituire il percorso alla directory del worktree creato:3218Gli 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:
3215 3219
3216* **Hook di comando** (`type: "command"`): stampa il percorso come l'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 a stderr.3220* **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.
3217* **Hook HTTP** (`type: "http"`): restituisci `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` nel corpo della risposta.3221* **Hook HTTP** (`type: "http"`): restituisci `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` nel corpo della risposta.
3218 3222
3219Se l'hook fallisce o non produce alcun percorso, la creazione del worktree fallisce con un errore.3223Se l'hook fallisce o non produce alcun percorso, la creazione del worktree fallisce con un errore.
3220 3224
3221Claude Code risolve un percorso relativo rispetto alla directory in cui l'hook si è eseguito, collassando qualsiasi segmento `.` o `..` in esso. Se il percorso risultante non è una directory in cui Claude Code può entrare, la sessione stampa un errore che nomina il percorso ed esce con codice 1.3225Claude 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.
3222 3226
3223Claude Code rifiuta un percorso assoluto che contiene segmenti `.` o `..`, e qualsiasi percorso che passa attraverso un symlink sotto la radice del repository, perché un symlink committato nel repository potrebbe reindirizzare il worktree al di fuori di esso. L'errore nomina il componente rifiutato. Restituisci un percorso normalizzato che non passa attraverso un symlink dentro il repository. Prima della v2.1.216, la creazione del worktree seguiva il percorso dell'hook senza questo screening.3227Claude 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.
3224 3228
3225<h3 id="worktreeremove">3229<h3 id="worktreeremove">
3226 WorktreeRemove3230 WorktreeRemove
3227</h3>3231</h3>
3228 3232
3229Si esegue quando un worktree viene rimosso. Questo è il contrapparte di pulizia di [WorktreeCreate](#worktreecreate). L'evento si esegue quando:3233Viene eseguito quando un worktree sta per essere rimosso. È la controparte di pulizia di [WorktreeCreate](#worktreecreate). L'evento si attiva quando:
3230 3234
3231* esci da una sessione `--worktree` e scegli di rimuoverla3235* esci da una sessione `--worktree` e scegli di rimuoverlo
3232* un subagente con `isolation: "worktree"` finisce3236* un subagent con `isolation: "worktree"` termina
3233* elimini una [sessione di background](/docs/it/agent-view#what-deleting-a-session-removes) il cui worktree l'hook ha creato3237* elimini una [sessione in background](/docs/it/agent-view#what-deleting-a-session-removes) il cui worktree è stato creato dall'hook
3234 3238
3235Per i worktree basati su git, Claude Code gestisce la pulizia automaticamente con `git worktree remove`. Se hai configurato un hook WorktreeCreate, accoppialo con un hook WorktreeRemove per controllare la pulizia dei worktree che crea:3239Per 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:
3236 3240
3237* **Nessun hook WorktreeRemove**: quando esci da una sessione `--worktree` e scegli la rimozione, Claude Code ritorna a `git worktree remove --force` sul percorso che il tuo hook WorktreeCreate ha restituito, quindi un worktree che git riconosce viene rimosso. Un worktree che git non riconosce, ad esempio uno che il tuo hook ha creato con un sistema di controllo della versione non git, rimane su disco. Per cosa elimina una [sessione di background](/docs/it/agent-view#what-deleting-a-session-removes), vedi le regole di eliminazione della vista agente.3241* **Nessun hook WorktreeRemove**: quando esci da una sessione `--worktree` e scegli la rimozione, Claude Code 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, per esempio uno creato dal tuo hook con un sistema di controllo versione diverso da git, rimane su disco. Per sapere cosa fa l'eliminazione di una [sessione in background](/docs/it/agent-view#what-deleting-a-session-removes) con un worktree creato da un hook, consulta le regole di eliminazione della vista agenti.
3238* **L'hook esce con 0**: il worktree conta come rimosso. Claude Code non legge nient'altro dall'hook, quindi assicurati che il tuo hook abbia eliminato la directory.3242* **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.
3239* **L'hook esce con non-zero**: la rimozione fallisce se la directory in `worktree_path` esiste ancora dopo, e il worktree rimane su disco senza fallback git. Un hook che ha eliminato la directory prima di uscire con non-zero conta come rimosso. Per come il fallimento viene segnalato, vedi [Input WorktreeRemove](#worktreeremove-input).3243* **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).
3240 3244
3241Claude Code non elimina mai un ramo appartenente a un worktree creato da hook, perché conosce solo il percorso che il tuo hook WorktreeCreate ha restituito. Se il tuo hook WorktreeCreate crea un ramo, eliminalo nel tuo hook WorktreeRemove.3245Claude 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.
3242 3246
3243Claude Code scarta i [campi di output JSON](#json-output) di un hook WorktreeRemove, come `systemMessage` e `continue`.3247Claude Code scarta i [campi di output JSON](#json-output) di un hook WorktreeRemove, come `systemMessage` e `continue`.
3244 3248
3245Per un'eliminazione di sessione di background, Claude Code verifica il percorso del worktree archiviato prima di eseguire l'hook e rifiuta un percorso che è un symlink o passa attraverso uno sotto la radice del repository. L'hook si esegue 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 tale worktree, [`claude rm`](/docs/it/agent-view#manage-sessions-from-the-shell) mantiene la sessione e il worktree invece. Prima della v2.1.216, l'hook si eseguiva sul percorso archiviato senza questi controlli.3249Per 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.
3246 3250
3247Claude Code passa il percorso restituito da WorktreeCreate come `worktree_path` nell'input dell'hook. Questo esempio legge quel percorso e rimuove la directory:3251Claude Code passa il percorso restituito da WorktreeCreate come `worktree_path` nell'input dell'hook. Questo esempio legge quel percorso e rimuove la directory:
3248 3252
3264```3268```
3265 3269
3266<h4 id="worktreeremove-input">3270<h4 id="worktreeremove-input">
3267 Input WorktreeRemove3271 Input di WorktreeRemove
3268</h4>3272</h4>
3269 3273
3270Oltre ai [campi di input comuni](#common-input-fields), gli hook WorktreeRemove ricevono il campo `worktree_path`, che è il percorso assoluto al worktree in fase di rimozione.3274Oltre 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.
3271 3275
3272```json theme={null}3276```json theme={null}
3273{3277{
3279}3283}
3280```3284```
3281 3285
3282Il codice di uscita di un hook WorktreeRemove decide il risultato. Quando un hook esce con non-zero e la directory in `worktree_path` esiste ancora dopo, la rimozione fallisce:3286Il 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:
3283 3287
3284* Il worktree rimane su disco, e il comando dell'hook e stderr vanno nel [debug log](#debug-hooks).3288* Il worktree rimane su disco, e il comando e lo stderr dell'hook vanno nel [log di debug](#debug-hooks).
3285* Se stavi eliminando una sessione di background, la sessione rimane anche. Il messaggio di rifiuto nella [vista agente](/docs/it/agent-view#what-deleting-a-session-removes) segnala come l'hook è terminato, come `exited 1`, cita l'inizio del suo stderr, e dice se eliminare la sessione di nuovo rimuove comunque la directory.3289* 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.
3286 3290
3287<h3 id="precompact">3291<h3 id="precompact">
3288 PreCompact3292 PreCompact
3289</h3>3293</h3>
3290 3294
3291Si esegue prima che Claude Code stia per eseguire un'operazione di compattazione.3295Viene eseguito prima che Claude Code stia per eseguire un'operazione di compattazione.
3292 3296
3293Il valore del matcher indica se la compattazione è stata attivata manualmente o automaticamente:3297Il valore del matcher indica se la compattazione è stata attivata manualmente o automaticamente:
3294 3298
3299 3303
3300Esci con codice 2 per bloccare la compattazione. Per un `/compact` manuale, il messaggio stderr viene mostrato all'utente. Puoi anche bloccare restituendo JSON con `"decision": "block"`.3304Esci con codice 2 per bloccare la compattazione. Per un `/compact` manuale, il messaggio stderr viene mostrato all'utente. Puoi anche bloccare restituendo JSON con `"decision": "block"`.
3301 3305
3302Bloccare la compattazione automatica ha effetti diversi a seconda di quando si esegue. Se la compattazione è stata attivata in modo proattivo prima del limite di contesto, Claude Code la salta e la conversazione continua non compattata. Se la compattazione è stata attivata per recuperare da un errore di limite di contesto già restituito dall'API, l'errore sottostante emerge e la richiesta corrente fallisce.3306Bloccare la compattazione automatica ha effetti diversi a seconda di quando si attiva. Se la compattazione è stata attivata in modo proattivo prima del limite di contesto, Claude Code la salta e la conversazione continua senza compattazione. Se la compattazione è stata attivata per recuperare da un errore di limite di contesto già restituito dall'API, l'errore sottostante emerge e la richiesta corrente fallisce.
3303 3307
3304Claude Code scarta i campi `systemMessage` e `continue` di un hook PreCompact.3308Claude Code scarta i campi `systemMessage` e `continue` di un hook PreCompact.
3305 3309
3306<h4 id="precompact-input">3310<h4 id="precompact-input">
3307 Input PreCompact3311 Input di PreCompact
3308</h4>3312</h4>
3309 3313
3310Oltre ai [campi di input comuni](#common-input-fields), gli hook PreCompact ricevono `trigger` e `custom_instructions`. Per `manual`, `custom_instructions` contiene ciò che l'utente passa in `/compact` ed è `null` quando non passa nulla. Per `auto`, `custom_instructions` è `null`.3314Oltre ai [campi di input comuni](#common-input-fields), gli hook PreCompact ricevono `trigger` e `custom_instructions`. Per `manual`, `custom_instructions` contiene ciò che l'utente passa a `/compact` ed è `null` quando non passa nulla. Per `auto`, `custom_instructions` è `null`.
3311 3315
3312```json theme={null}3316```json theme={null}
3313{3317{
3324 PostCompact3328 PostCompact
3325</h3>3329</h3>
3326 3330
3327Si esegue dopo che Claude Code completa un'operazione di compattazione. Usalo per reagire al nuovo stato compattato, ad esempio per registrare il riepilogo generato o aggiornare lo stato esterno. Claude Code scarta i campi `systemMessage` e `continue` di un hook PostCompact.3331Viene 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.
3328 3332
3329Gli stessi valori di matcher si applicano come per `PreCompact`:3333Si applicano gli stessi valori del matcher di `PreCompact`:
3330 3334
3331| Matcher | Quando si attiva |3335| Matcher | Quando si attiva |
3332| :- | :- |3336| :- | :- |
3334| `auto` | Dopo la compattazione automatica quando la conversazione raggiunge la [finestra di compattazione automatica](/docs/it/model-config#set-the-auto-compact-window) |3338| `auto` | Dopo la compattazione automatica quando la conversazione raggiunge la [finestra di compattazione automatica](/docs/it/model-config#set-the-auto-compact-window) |
3335 3339
3336<h4 id="postcompact-input">3340<h4 id="postcompact-input">
3337 Input PostCompact3341 Input di PostCompact
3338</h4>3342</h4>
3339 3343
3340Oltre ai [campi di input comuni](#common-input-fields), gli hook PostCompact ricevono `trigger` e `compact_summary`. Il campo `compact_summary` contiene il riepilogo della conversazione generato dall'operazione di compattazione.3344Oltre ai [campi di input comuni](#common-input-fields), gli hook PostCompact ricevono `trigger` e `compact_summary`. Il campo `compact_summary` contiene il riepilogo della conversazione generato dall'operazione di compattazione.
3350}3354}
3351```3355```
3352 3356
3353Gli hook PostCompact non hanno controllo decisionale. Non possono influenzare il risultato della compattazione ma possono eseguire attività di follow-up.3357Gli hook PostCompact non hanno controllo decisionale. Non possono influenzare il risultato della compattazione ma possono eseguire attività successive.
3354 3358
3355<h3 id="premodelswitch">3359<h3 id="premodelswitch">
3356 PreModelSwitch3360 PreModelSwitch
3357</h3>3361</h3>
3358 3362
3359Si esegue prima che Claude Code applichi un cambio di modello che hai richiesto tu o un client. Usalo per bloccare un cambio, richiedere conferma, o mostrare quale costo avrà il cambio prima che accada.3363Viene 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.
3360 3364
3361PreModelSwitch richiede Claude Code v2.1.251 o successivo. Claude Code lo esegue per queste richieste:3365PreModelSwitch richiede Claude Code v2.1.251 o successivo. Claude Code lo esegue per queste richieste:
3362 3366
3363* `/model <name>` e il picker `/model`3367* `/model <name>` e il selettore di `/model`
3364* Il picker del modello `Option+P` o `Alt+P`3368* Il selettore di modello `Option+P` o `Alt+P`
3365* L'impostazione Model in `/config`3369* L'impostazione Model in `/config`
3366* Attivare la [modalità veloce](/docs/it/fast-mode) quando questo cambia il modello della sessione3370* L'attivazione della [modalità veloce](/docs/it/fast-mode) quando questa cambia il modello della sessione
3367* Una richiesta `set_model`, o un cambio di modello in una richiesta `apply_flag_settings`, da un host [Agent SDK](/docs/it/agent-sdk/typescript#query-object) o [Remote Control](/docs/it/remote-control)3371* 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)
3368 3372
3369Claude Code non esegue gli hook PreModelSwitch per i cambi che fa da solo, come un [fallback di modello automatico](/docs/it/model-config#automatic-model-fallback) o il ripristino del modello quando riprendi una sessione. Quei cambi raggiungono [PostModelSwitch](#postmodelswitch) solo.3373Claude 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).
3370 3374
3371Claude Code confronta il matcher rispetto al nome canonico del modello a cui la sessione sta passando, ignorando qualsiasi suffisso `[1m]`. Un alias come `opus`, un ID di modello datato, e un ID specifico del provider come un ID di modello Amazon Bedrock corrispondono tutti al nome canonico unico a cui si risolvono, quindi `claude-opus-5` copre ogni ortografia di Opus 5.3375Claude 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.
3372 3376
3373Quando Claude Code non può determinare un nome canonico per il target, ad esempio un ID di modello personalizzato che solo il tuo [gateway LLM](/docs/it/llm-gateway) conosce, esegue ogni hook PreModelSwitch indipendentemente dal matcher. Un hook che blocca dovrebbe quindi controllare `to_model` dal suo input piuttosto che fare affidamento solo sul matcher.3377Quando 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.
3374 3378
3375Scrivi il matcher come un nome esatto, un elenco separato da `|` come `claude-opus-4-6|claude-opus-5`, o un'espressione regolare come `.*opus.*`. Questo esempio usa un matcher di nome esatto e controlla anche `to_model` dall'input dell'hook, quindi rifiuta un cambio a Opus 4.6 uscendo con codice 2 e consente qualsiasi altro target:3379Scrivi 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:
3376 3380
3377<Tabs>3381<Tabs>
3378 <Tab title="macOS/Linux">3382 <Tab title="macOS/Linux">
3438 </Tab>3442 </Tab>
3439</Tabs>3443</Tabs>
3440 3444
3441Per confermare che l'hook funziona, esegui `/model claude-opus-4-6` da una sessione che esegue un modello diverso. Claude Code mantiene il modello corrente e segnala che un hook PreModelSwitch ha bloccato il cambio, con il tuo messaggio come motivo.3445Per verificare che l'hook funzioni, esegui `/model claude-opus-4-6` da una sessione che usa un modello diverso. Claude Code mantiene il modello corrente e segnala che un hook PreModelSwitch ha bloccato il cambio, con il tuo messaggio come motivo.
3442 3446
3443<h4 id="premodelswitch-input">3447<h4 id="premodelswitch-input">
3444 Input PreModelSwitch3448 Input di PreModelSwitch
3445</h4>3449</h4>
3446 3450
3447Oltre ai [campi di input comuni](#common-input-fields), gli hook PreModelSwitch ricevono i campi in questa tabella. Gli ultimi cinque descrivono quale costo ha il reinvio della conversazione al nuovo modello, quindi un hook può mostrare quella cifra prima che il cambio accada.3451Oltre 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.
3448 3452
3449| Campo | Tipo | Descrizione |3453| Campo | Tipo | Descrizione |
3450| :- | :- | :- |3454| :- | :- | :- |
3451| `from_model` | string | ID del modello da cui il cambio cambia |3455| `from_model` | string | ID del modello da cui avviene il cambio |
3452| `to_model` | string | ID del modello a cui il cambio cambia. Il matcher confronta rispetto al nome canonico di questo modello |3456| `to_model` | string | ID del modello verso cui avviene il cambio. Il matcher viene confrontato con il nome canonico di questo modello |
3453| `requested_model` | string o `null` | Il modello che la richiesta ha nominato: un alias come `opus`, un ID di modello completo, o `null` quando la richiesta era per il modello predefinito |3457| `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 |
3454| `source` | string | Da dove viene la richiesta: `"command"` per `/model <name>`, l'impostazione Model in `/config`, o l'attivazione della modalità veloce; `"picker"` per un picker di modello; `"sdk"` per una richiesta `set_model`, o un cambio di modello in una richiesta `apply_flag_settings`, da un host Agent SDK o Remote Control |3458| `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 |
3455| `context_tokens` | number | Token che la richiesta successiva invia di nuovo come suo prompt: i token di input, lettura della cache, creazione della cache, e output dell'ultima risposta nella conversazione principale, combinati. `0` prima della prima risposta |3459| `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 |
3456| `prompt_cache_warm` | boolean | Se la cache del prompt del modello corrente è probabilmente ancora calda, il che significa che il cambio la perde |3460| `prompt_cache_warm` | boolean | Se la cache del prompt del modello corrente è probabilmente ancora attiva, il che significa che il cambio la fa perdere |
3457| `cache_ttl` | string | [Durata della cache del prompt](/docs/it/prompt-caching#cache-lifetime) che Claude Code richiede per questa sessione: `"5m"` o `"1h"` |3461| `cache_ttl` | string | [Durata della cache del prompt](/docs/it/prompt-caching#cache-lifetime) che Claude Code richiede per questa sessione: `"5m"` o `"1h"` |
3458| `estimated_cache_write_usd` | number | Costo stimato in dollari USA della scrittura di `context_tokens` nella cache del prompt su `to_model` al tasso `cache_ttl`, escludendo la richiesta successiva. Il server potrebbe non aver bisogno di ri-memorizzare l'intero contesto, quindi trattalo come una stima |3462| `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 |
3459| `pricing` | string | Come Claude Code ha prezzato `estimated_cache_write_usd`: `"configured"` ai tuoi tassi organizzativi quando li ha configurati, `"catalog"` al prezzo di listino, o `"default"` quando `to_model` non ha un prezzo noto e Claude Code ha assunto un tasso predefinito |3463| `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 |
3460 3464
3461Questo esempio mostra l'input per `/model opus` in una sessione che esegue Sonnet 5:3465Questo esempio mostra l'input per `/model opus` in una sessione che usa Sonnet 5:
3462 3466
3463```json theme={null}3467```json theme={null}
3464{3468{
3479```3483```
3480 3484
3481<h4 id="premodelswitch-decision-control">3485<h4 id="premodelswitch-decision-control">
3482 Controllo decisionale PreModelSwitch3486 Controllo decisionale di PreModelSwitch
3483</h4>3487</h4>
3484 3488
3485Gli hook `PreModelSwitch` possono annullare il cambio, chiedere all'utente di confermarlo, o consentirgli di procedere. Il codice di uscita 2 o un `decision: "block"` di livello superiore annulla il cambio.3489Gli 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.
3486 3490
3487Per un controllo più fine, restituisci `permissionDecision` e `permissionDecisionReason` in un oggetto `hookSpecificOutput`, come su [PreToolUse](#pretooluse-decision-control). `PreModelSwitch` accetta `"allow"`, `"deny"`, e `"ask"`. Non accetta `"defer"`, `updatedInput`, o `additionalContext`. La tabella sottostante descrive entrambi i campi:3491Per 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:
3488 3492
3489| Campo | Descrizione |3493| Campo | Descrizione |
3490| :- | :- |3494| :- | :- |
3491| `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 |3495| `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 |
3492| `permissionDecisionReason` | Per `"deny"`, mostrato all'utente come il motivo per cui il cambio è stato bloccato, o restituito come errore per una richiesta `set_model`. Per `"ask"`, mostrato nel prompt di conferma. Ignorato per `"allow"` |3496| `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"` |
3493 3497
3494Solo `/model` in una sessione interattiva può mostrare il prompt `"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.3498Solo `/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.
3495 3499
3496Questo esempio chiede all'utente di confermare e cita il conteggio dei token da `context_tokens`:3500Questo esempio chiede all'utente di confermare e cita il numero di token da `context_tokens`:
3497 3501
3498```json theme={null}3502```json theme={null}
3499{3503{
3505}3509}
3506```3510```
3507 3511
3508Quando più hook PreModelSwitch restituiscono decisioni diverse, la precedenza è `deny` > `ask` > `allow`.3512Quando più hook PreModelSwitch restituiscono decisioni diverse, l'ordine di precedenza è `deny` > `ask` > `allow`.
3509 3513
3510Claude Code mostra all'utente qualsiasi `systemMessage` che il tuo hook restituisce indipendentemente dalla decisione, quindi un hook di rapporto dei costi può restituire `{"systemMessage": "..."}` e uscire con 0.3514Claude 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.
3511 3515
3512Un hook PreModelSwitch che non risponde prima del suo timeout blocca il cambio. Su [PreToolUse](#timeouts), al contrario, un hook di comando che scade lascia che la chiamata dello strumento continui. Il timeout predefinito per questo evento è 30 secondi. `PreModelSwitch` esegue solo gli hook `command`, `http`, e `mcp_tool`, quindi i default `prompt` e `agent` non si applicano.3516Un 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.
3513 3517
3514Un 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 sotto [Codici di uscita diversi](#other-exit-codes).3518Un 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).
3515 3519
3516<h3 id="postmodelswitch">3520<h3 id="postmodelswitch">
3517 PostModelSwitch3521 PostModelSwitch
3518</h3>3522</h3>
3519 3523
3520Si esegue dopo che il modello della sessione cambia. Usalo per dare a Claude una guida specifica del modello senza modificare ogni CLAUDE.md, ad esempio un'istruzione a livello di organizzazione che si applica su determinati modelli.3524Viene 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.
3521 3525
3522PostModelSwitch 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:3526PostModelSwitch 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:
3523 3527
3524* Un cambio che hai richiesto tu o un client3528* Un cambio richiesto da te o da un client
3525* Un [fallback di modello automatico](/docs/it/model-config#automatic-model-fallback), che cambia il modello della sessione3529* Un [fallback automatico del modello](/docs/it/model-config#automatic-model-fallback), che cambia il modello della sessione
3526* Un'impostazione come [`opusplan`](/docs/it/model-config#opusplan-model-setting) che entra o esce dalla modalità piano3530* Un'impostazione come [`opusplan`](/docs/it/model-config#opusplan-model-setting) che entra o esce dal plan mode
3527* Claude Code che ripristina il modello quando riprendi una sessione3531* Claude Code che ripristina il modello quando riprendi una sessione
3528 3532
3529Claude Code non esegue gli hook PostModelSwitch quando un modello da una [catena di modelli di fallback](/docs/it/model-config#fallback-model-chains) serve un turno, perché quella sostituzione dura un turno e lascia il modello della sessione invariato.3533Claude 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.
3530 3534
3531Il matcher segue le stesse regole di [PreModelSwitch](#premodelswitch): Claude Code lo confronta rispetto al nome canonico del modello a cui la sessione è passata.3535Il matcher segue le stesse regole di [PreModelSwitch](#premodelswitch): Claude Code lo confronta con il nome canonico del modello verso cui la sessione è passata.
3532 3536
3533Questo esempio aggiunge una guida ogni volta che il modello della sessione cambia a qualsiasi modello Opus:3537Questo esempio aggiunge indicazioni ogni volta che il modello della sessione passa a un qualsiasi modello Opus:
3534 3538
3535```json theme={null}3539```json theme={null}
3536{3540{
3550}3554}
3551```3555```
3552 3556
3553Per confermare che l'hook funziona, cambia a un modello Opus da una sessione che esegue un modello diverso, ad esempio esegui `/model opus` da una sessione Sonnet, quindi chiedi a Claude quale guida ha sul modello corrente.3557Per 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.
3554 3558
3555<h4 id="postmodelswitch-input">3559<h4 id="postmodelswitch-input">
3556 Input PostModelSwitch3560 Input di PostModelSwitch
3557</h4>3561</h4>
3558 3562
3559Gli hook PostModelSwitch ricevono gli stessi campi di [PreModelSwitch](#premodelswitch-input), con `hook_event_name` impostato su `"PostModelSwitch"` e due valori `source` aggiuntivi: `"auto"` per un fallback automatico o un altro cambio che Claude Code ha fatto da solo, e `"resume"` per il modello ripristinato quando riprendi una sessione.3563Gli 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.
3560 3564
3561`requested_model` è `null` quando `source` è `"auto"`. Quando `source` è `"resume"`, è l'impostazione del modello salvato che Claude Code ha ripristinato.3565`requested_model` è `null` quando `source` è `"auto"`. Quando `source` è `"resume"`, è l'impostazione del modello salvata che Claude Code ha ripristinato.
3562 3566
3563<h4 id="postmodelswitch-decision-control">3567<h4 id="postmodelswitch-decision-control">
3564 Controllo decisionale PostModelSwitch3568 Controllo decisionale di PostModelSwitch
3565</h4>3569</h4>
3566 3570
3567Claude Code prende il tuo stdout di [testo semplice](#exit-code-0) dell'hook all'uscita 0, o `additionalContext` dall'output JSON, e lo consegna a Claude con la richiesta successiva dopo il cambio. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, puoi restituire:3571Claude 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:
3568 3572
3569| Campo | Descrizione |3573| Campo | Descrizione |
3570| :- | :- |3574| :- | :- |
3571| `additionalContext` | Stringa aggiunta al contesto di Claude con la richiesta successiva. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |3575| `additionalContext` | Stringa aggiunta al contesto di Claude con la richiesta successiva. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |
3572 3576
3573Se l'hook non finisce entro cinque secondi dopo che invii la richiesta successiva, Claude Code invia quella richiesta senza l'output e lo allega alla richiesta successiva. Se il modello cambia più volte prima della richiesta successiva, Claude Code consegna solo l'output per il cambio del modello target finale.3577Se l'hook non ha terminato entro cinque secondi dall'invio del prompt successivo, Claude Code invia quella richiesta senza l'output e lo allega invece alla richiesta seguente. Se il modello cambia più volte prima della richiesta successiva, Claude Code consegna solo l'output relativo al modello di destinazione dell'ultimo cambio.
3574 3578
3575<h3 id="sessionend">3579<h3 id="sessionend">
3576 SessionEnd3580 SessionEnd
3577</h3>3581</h3>
3578 3582
3579Si esegue quando una sessione di Claude Code termina. Utile per attività di pulizia, registrazione delle statistiche della sessione, o salvataggio dello stato della sessione. Supporta i matcher per filtrare per motivo di uscita.3583Viene eseguito quando una sessione di Claude Code termina. Utile per attività di pulizia, registrazione delle
3584statistiche della sessione o salvataggio dello stato della sessione. Supporta i matcher per filtrare in base al motivo di uscita.
3580 3585
3581Il campo `reason` nell'input dell'hook indica perché la sessione è terminata:3586Il campo `reason` nell'input dell'hook indica perché la sessione è terminata:
3582 3587
3584| :- | :- |3589| :- | :- |
3585| `clear` | Sessione cancellata con il comando `/clear` |3590| `clear` | Sessione cancellata con il comando `/clear` |
3586| `resume` | Sessione cambiata tramite `/resume` interattivo |3591| `resume` | Sessione cambiata tramite `/resume` interattivo |
3587| `logout` | L'utente ha effettuato il logout |3592| `logout` | L'utente è uscito dall'account |
3588| `prompt_input_exit` | L'utente è uscito mentre l'input del prompt era visibile |3593| `prompt_input_exit` | L'utente è uscito mentre l'input del prompt era visibile |
3589| `other` | Altri motivi di uscita |3594| `other` | Altri motivi di uscita |
3590| `bypass_permissions_disabled` | Rimosso nella v2.1.234; Claude Code non lo invia. Eliminalo dai tuoi matcher `SessionEnd` |3595| `bypass_permissions_disabled` | Rimosso nella v2.1.234; Claude Code non lo invia. Rimuovilo dai tuoi matcher `SessionEnd` |
3591 3596
3592<h4 id="sessionend-input">3597<h4 id="sessionend-input">
3593 Input SessionEnd3598 Input di SessionEnd
3594</h4>3599</h4>
3595 3600
3596Oltre ai [campi di input comuni](#common-input-fields), gli hook SessionEnd ricevono un campo `reason` che indica perché la sessione è terminata. Vedi la [tabella dei motivi](#sessionend) sopra per tutti i valori.3601Oltre ai [campi di input comuni](#common-input-fields), gli hook SessionEnd ricevono un campo `reason` che indica perché la sessione è terminata. Consulta la [tabella dei motivi](#sessionend) sopra per tutti i valori.
3597 3602
3598```json theme={null}3603```json theme={null}
3599{3604{
3605}3610}
3606```3611```
3607 3612
3608Gli 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`.3613Gli 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`.
3609 3614
3610Gli hook SessionEnd hanno un timeout predefinito di 1,5 secondi. Si applica quando esci, esegui `/clear`, o cambi sessioni con `/resume` interattivo. Puoi dare a un hook più tempo in due modi:3615Gli 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:
3611 3616
3612* **`timeout` per hook**: imposta `timeout` nella configurazione di quell'hook. Il budget complessivo aumenta automaticamente per corrispondere 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 il suo `timeout` mantiene comunque il default. I timeout impostati su hook forniti da plugin non aumentano il budget.3617* **`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.
3613* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: imposta questa variabile di ambiente in millisecondi per sovrascrivere il budget esplicitamente. Il valore che imposti diventa anche il timeout per ogni hook senza il suo `timeout`.3618* **`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`.
3614 3619
3615Questo esempio imposta il budget a 5 secondi:3620Questo esempio imposta il budget a 5 secondi:
3616 3621
3618CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude3623CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude
3619```3624```
3620 3625
3621Prima della v2.1.268, `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` aumentava solo il budget complessivo, e un hook senza il suo `timeout` veniva comunque annullato dopo 1,5 secondi.3626Prima della v2.1.268, `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` aumentava solo il budget complessivo, e un hook senza un proprio `timeout` veniva comunque annullato dopo 1,5 secondi.
3622 3627
3623<h3 id="elicitation">3628<h3 id="elicitation">
3624 Elicitation3629 Elicitation
3625</h3>3630</h3>
3626 3631
3627Si esegue quando un server MCP richiede l'input dell'utente a metà attività. Per impostazione predefinita, Claude Code mostra un dialogo interattivo per l'utente per rispondere. Gli hook possono intercettare questa richiesta e rispondere programmaticamente, saltando completamente il dialogo.3632Viene 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.
3628 3633
3629Il campo matcher corrisponde al nome del server MCP.3634Il campo matcher viene confrontato con il nome del server MCP.
3630 3635
3631<h4 id="elicitation-input">3636<h4 id="elicitation-input">
3632 Input Elicitation3637 Input di Elicitation
3633</h4>3638</h4>
3634 3639
3635Oltre ai [campi di input comuni](#common-input-fields), gli hook Elicitation ricevono `mcp_server_name`, `message`, e campi facoltativi `mode`, `url`, `elicitation_id`, e `requested_schema`.3640Oltre 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`.
3636 3641
3637Per l'elicitazione in modalità modulo, il caso più comune:3642Per l'elicitation in modalità form, il caso più comune:
3638 3643
3639```json theme={null}3644```json theme={null}
3640{3645{
3654}3659}
3655```3660```
3656 3661
3657Per l'elicitazione in modalità URL, usata per l'autenticazione basata su browser:3662Per l'elicitation in modalità URL, usata per l'autenticazione basata su browser:
3658 3663
3659```json theme={null}3664```json theme={null}
3660{3665{
3670```3675```
3671 3676
3672<h4 id="elicitation-output">3677<h4 id="elicitation-output">
3673 Output Elicitation3678 Output di Elicitation
3674</h4>3679</h4>
3675 3680
3676Per rispondere programmaticamente senza mostrare il dialogo, restituisci un oggetto JSON con `hookSpecificOutput`:3681Per rispondere in modo programmatico senza mostrare la finestra di dialogo, restituisci un oggetto JSON con `hookSpecificOutput`:
3677 3682
3678```json theme={null}3683```json theme={null}
3679{3684{
3689 3694
3690| Campo | Valori | Descrizione |3695| Campo | Valori | Descrizione |
3691| :- | :- | :- |3696| :- | :- | :- |
3692| `action` | `accept`, `decline`, `cancel` | Se accettare, rifiutare, o annullare la richiesta |3697| `action` | `accept`, `decline`, `cancel` | Se accettare, rifiutare o annullare la richiesta |
3693| `content` | object | Valori dei campi del modulo da inviare. Usato solo quando `action` è `accept` |3698| `content` | object | Valori dei campi del form da inviare. Usato solo quando `action` è `accept` |
3694 3699
3695L'uscita con codice 2 nega l'elicitazione. Claude Code non mostra il tuo messaggio stderr da nessuna parte.3700Il codice di uscita 2 nega l'elicitation. Claude Code non mostra il tuo messaggio stderr da nessuna parte.
3696 3701
3697Claude Code agisce su `hookSpecificOutput` dall'output JSON di un hook Elicitation e scarta `systemMessage` e `continue`.3702Claude Code agisce su `hookSpecificOutput` dall'output JSON di un hook Elicitation e scarta `systemMessage` e `continue`.
3698 3703
3700 ElicitationResult3705 ElicitationResult
3701</h3>3706</h3>
3702 3707
3703Si esegue dopo che un utente risponde a un'elicitazione MCP. Gli hook possono osservare, modificare, o bloccare la risposta prima che venga inviata di nuovo al server MCP.3708Viene 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.
3704 3709
3705Il campo matcher corrisponde al nome del server MCP.3710Il campo matcher viene confrontato con il nome del server MCP.
3706 3711
3707<h4 id="elicitationresult-input">3712<h4 id="elicitationresult-input">
3708 Input ElicitationResult3713 Input di ElicitationResult
3709</h4>3714</h4>
3710 3715
3711Oltre ai [campi di input comuni](#common-input-fields), gli hook ElicitationResult ricevono `mcp_server_name`, `action`, e campi facoltativi `mode`, `elicitation_id`, e `content`.3716Oltre 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`.
3712 3717
3713```json theme={null}3718```json theme={null}
3714{3719{
3725```3730```
3726 3731
3727<h4 id="elicitationresult-output">3732<h4 id="elicitationresult-output">
3728 Output ElicitationResult3733 Output di ElicitationResult
3729</h4>3734</h4>
3730 3735
3731Per sovrascrivere la risposta dell'utente, restituisci un oggetto JSON con `hookSpecificOutput`:3736Per sovrascrivere la risposta dell'utente, restituisci un oggetto JSON con `hookSpecificOutput`:
3743| Campo | Valori | Descrizione |3748| Campo | Valori | Descrizione |
3744| :- | :- | :- |3749| :- | :- | :- |
3745| `action` | `accept`, `decline`, `cancel` | Sovrascrive l'azione dell'utente |3750| `action` | `accept`, `decline`, `cancel` | Sovrascrive l'azione dell'utente |
3746| `content` | object | Sovrascrive i valori dei campi del modulo. Significativo solo quando `action` è `accept` |3751| `content` | object | Sovrascrive i valori dei campi del form. Significativo solo quando `action` è `accept` |
3747 3752
3748L'uscita con codice 2 blocca la risposta, cambiando l'azione effettiva a `decline`. Claude Code non mostra il tuo messaggio stderr da nessuna parte.3753Il codice di uscita 2 blocca la risposta, cambiando l'azione effettiva in `decline`. Claude Code non mostra il tuo messaggio stderr da nessuna parte.
3749 3754
3750Claude Code agisce su `hookSpecificOutput` dall'output JSON di un hook ElicitationResult e scarta `systemMessage` e `continue`.3755Claude Code agisce su `hookSpecificOutput` dall'output JSON di un hook ElicitationResult e scarta `systemMessage` e `continue`.
3751 3756
