40| :- | :- |40| :- | :- |
41| `SessionStart` | Quando una sessione inizia o riprende |41| `SessionStart` | Quando una sessione inizia o riprende |
42| `Setup` | Quando avvii Claude Code con `--init-only`, o con `--init` o `--maintenance` in modalità `-p`. Per la preparazione una tantum in CI o script |42| `Setup` | Quando avvii Claude Code con `--init-only`, o con `--init` o `--maintenance` in modalità `-p`. Per la preparazione una tantum in CI o script |
43| `UserPromptSubmit` | Quando invii un prompt, prima che Claude lo elabori |43| `UserPromptSubmit` | Quando viene inviato un prompt, prima che Claude lo elabori. Si attiva anche nei [turni che Claude Code avvia autonomamente](/docs/it/hooks#userpromptsubmit) |
44| `UserPromptExpansion` | Quando un comando digitato dall'utente si espande in un prompt, prima che raggiunga Claude. Può bloccare l'espansione |44| `UserPromptExpansion` | Quando un comando digitato dall'utente si espande in un prompt, prima che raggiunga Claude. Può bloccare l'espansione |
45| `PreToolUse` | Prima che una chiamata a uno strumento si esegua. Può bloccarla |45| `PreToolUse` | Prima che una chiamata a uno strumento si esegua. Può bloccarla |
46| `PermissionRequest` | Quando una chiamata a uno strumento necessita di una decisione di autorizzazione |46| `PermissionRequest` | Quando una chiamata a uno strumento necessita di una decisione di autorizzazione |
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 viene inviato un prompt, prima che Claude lo elabori. Questo ti consente
1408di aggiungere contesto in base al prompt o 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` non vengono attivati solo sui prompt che digiti. Claude Code li esegue anche quando:
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.1413* Viene attivata un'[attività pianificata](/docs/it/scheduled-tasks), inclusa un'iterazione di `/loop`
1414* Un [subagent in background](/docs/it/sub-agents#run-subagents-in-foreground-or-background) riferisce alla sessione che l'ha avviato
1415* Un [messaggio inviato da un'altra sessione](/docs/it/cross-session-messaging) arriva alla tua conversazione principale
1412 1416
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.1417Gli 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.
1418
1419Fatta 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.
1420
1421Un [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 1422
1415<h4 id="userpromptsubmit-input">1423<h4 id="userpromptsubmit-input">
1416 Input UserPromptSubmit1424 Input di UserPromptSubmit
1417</h4>1425</h4>
1418 1426
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.1427Oltre ai [campi di input comuni](#common-input-fields), gli hook UserPromptSubmit ricevono il campo `prompt` contenente il testo inviato. Il contenuto incollato che è stato compresso in un segnaposto `[Pasted text #N]` arriva espanso sul posto. Nelle sessioni in cui Claude Code [contrassegna il testo incollato per Claude](/docs/it/terminal-config#how-claude-treats-pasted-text), quel contenuto espanso si trova tra una riga `<pasted_content id="…">` e una riga `</pasted_content id="…">`, quindi tieni conto di queste righe se il tuo hook analizza il prompt.
1420 1428
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).1429Gli 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 1430
1423```json theme={null}1431```json theme={null}
1424{1432{
1432```1440```
1433 1441
1434<h4 id="userpromptsubmit-decision-control">1442<h4 id="userpromptsubmit-decision-control">
1435 Controllo decisionale UserPromptSubmit1443 Controllo delle decisioni di UserPromptSubmit
1436</h4>1444</h4>
1437 1445
1438Gli hook `UserPromptSubmit` possono controllare se un prompt utente viene elaborato e aggiungere contesto. Tutti i [campi di output JSON](#json-output) sono disponibili.1446Gli hook `UserPromptSubmit` possono controllare se un prompt inviato viene elaborato e aggiungere contesto. Sono disponibili tutti i [campi di output JSON](#json-output).
1439 1447
1440Ci sono due modi per aggiungere contesto alla conversazione all'uscita del codice 0:1448Ci sono due modi per aggiungere contesto alla conversazione con codice di uscita 0:
1441 1449
1442* **Stdout di testo semplice**: Claude Code aggiunge stdout che [tratta come testo semplice](#exit-code-0) al contesto di Claude1450* **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 contesto1451* **JSON con `additionalContext`**: usa il formato JSON seguente per un maggiore controllo. Il campo `additionalContext` viene aggiunto come contesto
1444 1452
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).1453Nessuno 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 1454
1447Per bloccare un prompt, restituisci un oggetto JSON con `decision` impostato su `"block"`:1455Per bloccare un prompt, restituisci un oggetto JSON con `decision` impostato su `"block"`:
1448 1456
1449| Campo | Descrizione |1457| Campo | Descrizione |
1450| :- | :- |1458| :- | :- |
1451| `decision` | `"block"` ferma il prompt prima che raggiunga Claude. Ometti per consentire al prompt di procedere |1459| `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 |1460| `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) |1461| `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 |1462| `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) |1463| `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 1464
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.1465Un 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 1466
1459```json theme={null}1467```json theme={null}
1460{1468{
1470```1478```
1471 1479
1472<h4 id="what-a-blocked-prompt-leaves-behind">1480<h4 id="what-a-blocked-prompt-leaves-behind">
1473 Cosa lascia dietro un prompt bloccato1481 Cosa lascia un prompt bloccato
1474</h4>1482</h4>
1475 1483
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.1484Un 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 1485
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).1486`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 1487
1480<h3 id="userpromptexpansion">1488<h3 id="userpromptexpansion">
1481 UserPromptExpansion1489 UserPromptExpansion
1482</h3>1490</h3>
1483 1491
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`.1492Viene 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 1493
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.1494Questo 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 1495
1488Corrisponde su `command_name`. Lascia il matcher vuoto per eseguire su ogni comando di tipo prompt.1496Effettua la corrispondenza su `command_name`. Lascia vuoto il matcher per attivarlo su ogni comando di tipo prompt.
1489 1497
1490<h4 id="userpromptexpansion-input">1498<h4 id="userpromptexpansion-input">
1491 Input UserPromptExpansion1499 Input di UserPromptExpansion
1492</h4>1500</h4>
1493 1501
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.1502Oltre 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 1503
1496```json theme={null}1504```json theme={null}
1497{1505{
1509```1517```
1510 1518
1511<h4 id="userpromptexpansion-decision-control">1519<h4 id="userpromptexpansion-decision-control">
1512 Controllo decisionale UserPromptExpansion1520 Controllo delle decisioni di UserPromptExpansion
1513</h4>1521</h4>
1514 1522
1515Gli hook `UserPromptExpansion` possono bloccare l'espansione o aggiungere contesto. Tutti i [campi di output JSON](#json-output) sono disponibili.1523Gli hook `UserPromptExpansion` possono bloccare l'espansione o aggiungere contesto. Sono disponibili tutti i [campi di output JSON](#json-output).
1516 1524
1517| Campo | Descrizione |1525| Campo | Descrizione |
1518| :- | :- |1526| :- | :- |
1519| `decision` | `"block"` impedisce al comando di espandersi. Ometti per consentirgli di procedere |1527| `decision` | `"block"` impedisce l'espansione del comando. Omettilo per consentirgli di procedere |
1520| `reason` | Mostrato all'utente quando `decision` è `"block"` |1528| `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) |1529| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt espanso. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |
1522 1530
1523Un hook che blocca uscendo con 2 si instrada allo stesso modo di `reason`: il messaggio di blocco mostra il testo stderr all'utente.1531Un hook che blocca terminando con 2 segue lo stesso percorso di `reason`: il messaggio di blocco mostra il testo di stderr all'utente.
1524 1532
1525```json theme={null}1533```json theme={null}
1526{1534{
1537 MessageDisplay1545 MessageDisplay
1538</h3>1546</h3>
1539 1547
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.1548Viene 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 1549
1542Usa MessageDisplay per:1550Usa MessageDisplay per:
1543 1551
1544* rimuovere markdown per una visualizzazione minima1552* rimuovere il markdown per una visualizzazione minimale
1545* trasformare il testo che un'applicazione Agent SDK mostra ai suoi utenti1553* trasformare il testo che un'applicazione Agent SDK mostra ai suoi utenti
1546* redarre chiavi API o nomi host interni dalle risposte di Claude1554* oscurare chiavi API o nomi host interni dalle risposte di Claude
1547 1555
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.1556Claude 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 1557
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.1558MessageDisplay 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 1559
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.1560MessageDisplay 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 1561
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à.1562Nelle 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 1563
1556<h4 id="messagedisplay-input">1564<h4 id="messagedisplay-input">
1557 Input MessageDisplay1565 Input di MessageDisplay
1558</h4>1566</h4>
1559 1567
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.1568Oltre 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 1569
1562| Campo | Descrizione |1570| Campo | Descrizione |
1563| :- | :- |1571| :- | :- |
1564| `turn_id` | UUID del turno corrente |1572| `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 |1573| `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 |1574| `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 |1575| `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 |1576| `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 1577
1570```json theme={null}1578```json theme={null}
1571{1579{
1582```1590```
1583 1591
1584<h4 id="messagedisplay-output">1592<h4 id="messagedisplay-output">
1585 Output MessageDisplay1593 Output di MessageDisplay
1586</h4>1594</h4>
1587 1595
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:1596Oltre 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| :- | :- |1599| :- | :- |
1592| `displayContent` | Testo visualizzato al posto del delta. Omettilo per visualizzare l'originale |1600| `displayContent` | Testo visualizzato al posto del delta. Omettilo per visualizzare l'originale |
1593 1601
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`.1602Gli 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 1603
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`.1604Questo 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 1605
1598<Tabs>1606<Tabs>
1599 <Tab title="macOS/Linux">1607 <Tab title="macOS/Linux">
1652 }1660 }
1653 ```1661 ```
1654 1662
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.1663 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 1664
1657 Salva questo script in `.claude/hooks/plain-display.ps1` nel tuo progetto:1665 Salva questo script in `.claude/hooks/plain-display.ps1` nel tuo progetto:
1658 1666
1669 </Tab>1677 </Tab>
1670</Tabs>1678</Tabs>
1671 1679
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.1680I 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 1681
1674<h3 id="pretooluse">1682<h3 id="pretooluse">
1675 PreToolUse1683 PreToolUse
1676</h3>1684</h3>
1677 1685
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).1686Viene 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 1687
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.1688Per 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 1689
1682<Warning>1690<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.1691 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 1692
1685 PreToolUse inoltre non si esegue per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).1693 PreToolUse inoltre non si attiva per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).
1686</Warning>1694</Warning>
1687 1695
1688Usa [Controllo decisionale PreToolUse](#pretooluse-decision-control) per consentire, negare, chiedere, o differire la chiamata dello strumento.1696Usa il [controllo delle decisioni di PreToolUse](#pretooluse-decision-control) per consentire, negare, chiedere o differire la chiamata allo strumento.
1689 1697
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.1698Un [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 1699
1692<h4 id="pretooluse-input">1700<h4 id="pretooluse-input">
1693 Input PreToolUse1701 Input di PreToolUse
1694</h4>1702</h4>
1695 1703
1696Oltre ai [campi di input comuni](#common-input-fields), gli hook PreToolUse ricevono `tool_name`, `tool_input`, e `tool_use_id`.1704Oltre ai [campi di input comuni](#common-input-fields), gli hook PreToolUse ricevono `tool_name`, `tool_input` e `tool_use_id`.
1697 1705
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.1706Per 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 1707
1700Per gli strumenti di file `Write`, `Edit`, e `Read`, `tool_input.file_path` è sempre assoluto:1708Per gli strumenti sui file `Write`, `Edit` e `Read`, `tool_input.file_path` è sempre assoluto:
1701 1709
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 percorso1710* 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`1711* 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 bloccare1712* 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 è assoluto1713* 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 1714
1707Una chiamata `Write` su Windows consegna:1715Una chiamata `Write` su Windows fornisce:
1708 1716
1709```json theme={null}1717```json theme={null}
1710{1718{
1718}1726}
1719```1727```
1720 1728
1721I campi `tool_input` dipendono dallo strumento:1729I campi di `tool_input` dipendono dallo strumento:
1722 1730
1723<a id="bash" />1731<a id="bash" />
1724 1732
1731| Campo | Tipo | Esempio | Descrizione |1739| Campo | Tipo | Esempio | Descrizione |
1732| :- | :- | :- | :- |1740| :- | :- | :- | :- |
1733| `command` | string | `"npm test"` | Il comando shell da eseguire |1741| `command` | string | `"npm test"` | Il comando shell da eseguire |
1734| `description` | string | `"Run test suite"` | Descrizione facoltativa di cosa fa il comando |1742| `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 |1743| `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 |1744| `run_in_background` | boolean | `false` | Se eseguire il comando in background |
1737 1745
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.1746Quando 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 1747
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.1748Il 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 1749
1742<Note>1750<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.1751 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>1752</Note>
1745 1753
1746`changedFiles` e `files` elencano ciò che il comando ha cambiato; i campi rimanenti dicono quanto è completo e quanto è affidabile quell'elenco.1754`changedFiles` e `files` elencano ciò che il comando ha modificato; i campi rimanenti indicano quanto è completo e quanto è affidabile quell'elenco.
1747 1755
1748| Campo | Tipo | Esempio | Descrizione |1756| Campo | Tipo | Esempio | Descrizione |
1749| :- | :- | :- | :- |1757| :- | :- | :- | :- |
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 |1758| `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 |1759| `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` |1760| `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 |1761| `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 |1762| `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 |1763| `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 1764
1757<a id="powershell" />1765<a id="powershell" />
1758 1766
1760 PowerShell1768 PowerShell
1761</h5>1769</h5>
1762 1770
1763Esegue comandi PowerShell. Vedi lo [strumento PowerShell](/docs/it/tools-reference#powershell-tool) per la disponibilità per piattaforma.1771Esegue comandi PowerShell. Consulta lo [strumento PowerShell](/docs/it/tools-reference#powershell-tool) per la disponibilità per piattaforma.
1764 1772
1765I campi corrispondono allo strumento Bash, con la stringa di comando in `command`:1773I campi corrispondono a quelli dello strumento Bash, con la stringa del comando in `command`:
1766 1774
1767| Campo | Tipo | Esempio | Descrizione |1775| Campo | Tipo | Esempio | Descrizione |
1768| :- | :- | :- | :- |1776| :- | :- | :- | :- |
1769| `command` | string | `"Get-ChildItem -Recurse"` | Il comando PowerShell da eseguire |1777| `command` | string | `"Get-ChildItem -Recurse"` | Il comando PowerShell da eseguire |
1770| `description` | string | `"List files recursively"` | Descrizione facoltativa di cosa fa il comando |1778| `description` | string | `"List files recursively"` | Descrizione facoltativa di ciò che fa il comando |
1771| `timeout` | number | `120000` | Timeout facoltativo in millisecondi |1779| `timeout` | number | `120000` | Timeout facoltativo in millisecondi |
1772| `run_in_background` | boolean | `false` | Se eseguire il comando in background |1780| `run_in_background` | boolean | `false` | Se eseguire il comando in background |
1773 1781
1774Corrisponde a `Bash|PowerShell` negli hook che ispezionano i comandi shell, quindi coprono entrambi gli strumenti:1782Usa `Bash|PowerShell` come corrispondenza negli hook che ispezionano i comandi shell, così coprono entrambi gli strumenti:
1775 1783
1776* Su Windows, ovunque lo strumento PowerShell sia abilitato, Claude tratta PowerShell come la shell primaria e instrada i comandi shell attraverso di esso.1784* 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.1785* 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ì.1786* Un hook che corrisponde solo a `Bash` non si attiva mai in quel caso.
1779 1787
1780<h5 id="write">1788<h5 id="write">
1781 Write1789 Write
1785 1793
1786| Campo | Tipo | Esempio | Descrizione |1794| Campo | Tipo | Esempio | Descrizione |
1787| :- | :- | :- | :- |1795| :- | :- | :- | :- |
1788| `file_path` | string | `"/path/to/file.txt"` | Percorso assoluto al file da scrivere |1796| `file_path` | string | `"/path/to/file.txt"` | Percorso assoluto del file da scrivere |
1789| `content` | string | `"file content"` | Contenuto da scrivere nel file |1797| `content` | string | `"file content"` | Contenuto da scrivere nel file |
1790 1798
1791<h5 id="edit">1799<h5 id="edit">
1796 1804
1797| Campo | Tipo | Esempio | Descrizione |1805| Campo | Tipo | Esempio | Descrizione |
1798| :- | :- | :- | :- |1806| :- | :- | :- | :- |
1799| `file_path` | string | `"/path/to/file.txt"` | Percorso assoluto al file da modificare |1807| `file_path` | string | `"/path/to/file.txt"` | Percorso assoluto del file da modificare |
1800| `old_string` | string | `"original text"` | Testo da trovare e sostituire |1808| `old_string` | string | `"original text"` | Testo da trovare e sostituire |
1801| `new_string` | string | `"replacement text"` | Testo di sostituzione |1809| `new_string` | string | `"replacement text"` | Testo sostitutivo |
1802| `replace_all` | boolean | `false` | Se sostituire tutte le occorrenze |1810| `replace_all` | boolean | `false` | Se sostituire tutte le occorrenze |
1803 1811
1804<h5 id="read">1812<h5 id="read">
1805 Read1813 Read
1806</h5>1814</h5>
1807 1815
1808Legge i contenuti del file.1816Legge il contenuto dei file.
1809 1817
1810| Campo | Tipo | Esempio | Descrizione |1818| Campo | Tipo | Esempio | Descrizione |
1811| :- | :- | :- | :- |1819| :- | :- | :- | :- |
1812| `file_path` | string | `"/path/to/file.txt"` | Percorso assoluto al file da leggere |1820| `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 |1821| `offset` | number | `10` | Numero di riga facoltativo da cui iniziare la lettura |
1814| `limit` | number | `50` | Numero facoltativo di righe da leggere |1822| `limit` | number | `50` | Numero facoltativo di righe da leggere |
1815 1823
1817 Glob1825 Glob
1818</h5>1826</h5>
1819 1827
1820Trova file che corrispondono a un modello glob.1828Trova i file che corrispondono a un pattern glob.
1821 1829
1822| Campo | Tipo | Esempio | Descrizione |1830| Campo | Tipo | Esempio | Descrizione |
1823| :- | :- | :- | :- |1831| :- | :- | :- | :- |
1824| `pattern` | string | `"**/*.ts"` | Modello glob per corrispondere ai file |1832| `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 |1833| `path` | string | `"/path/to/dir"` | Directory facoltativa in cui cercare. Il valore predefinito è la directory di lavoro corrente |
1826 1834
1827<h5 id="grep">1835<h5 id="grep">
1828 Grep1836 Grep
1829</h5>1837</h5>
1830 1838
1831Cerca i contenuti dei file con espressioni regolari.1839Cerca nel contenuto dei file con espressioni regolari.
1832 1840
1833| Campo | Tipo | Esempio | Descrizione |1841| Campo | Tipo | Esempio | Descrizione |
1834| :- | :- | :- | :- |1842| :- | :- | :- | :- |
1835| `pattern` | string | `"TODO.*fix"` | Modello di espressione regolare da cercare |1843| `pattern` | string | `"TODO.*fix"` | Pattern di espressione regolare da cercare |
1836| `path` | string | `"/path/to/dir"` | File o directory facoltativo da cercare |1844| `path` | string | `"/path/to/dir"` | File o directory facoltativa in cui cercare |
1837| `glob` | string | `"*.ts"` | Modello glob facoltativo per filtrare i file |1845| `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"` |1846| `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 |1847| `-i` | boolean | `true` | Ricerca senza distinzione tra maiuscole e minuscole |
1840| `multiline` | boolean | `false` | Abilita la corrispondenza multilinea |1848| `multiline` | boolean | `false` | Abilita la corrispondenza su più righe |
1841 1849
1842<h5 id="webfetch">1850<h5 id="webfetch">
1843 WebFetch1851 WebFetch
1844</h5>1852</h5>
1845 1853
1846Recupera ed elabora il contenuto web.1854Recupera ed elabora contenuti web.
1847 1855
1848| Campo | Tipo | Esempio | Descrizione |1856| Campo | Tipo | Esempio | Descrizione |
1849| :- | :- | :- | :- |1857| :- | :- | :- | :- |
1854 WebSearch1862 WebSearch
1855</h5>1863</h5>
1856 1864
1857Cerca il web.1865Esegue ricerche sul web.
1858 1866
1859| Campo | Tipo | Esempio | Descrizione |1867| Campo | Tipo | Esempio | Descrizione |
1860| :- | :- | :- | :- |1868| :- | :- | :- | :- |
1861| `query` | string | `"react hooks best practices"` | Query di ricerca |1869| `query` | string | `"react hooks best practices"` | Query di ricerca |
1862| `allowed_domains` | array | `["docs.example.com"]` | Facoltativo: includi solo risultati da questi domini |1870| `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 |1871| `blocked_domains` | array | `["spam.example.com"]` | Facoltativo: esclude i risultati da questi domini |
1864 1872
1865<h5 id="agent">1873<h5 id="agent">
1866 Agent1874 Agent
1867</h5>1875</h5>
1868 1876
1869Genera un [subagente](/docs/it/sub-agents).1877Avvia un [subagent](/docs/it/sub-agents).
1870 1878
1871| Campo | Tipo | Esempio | Descrizione |1879| Campo | Tipo | Esempio | Descrizione |
1872| :- | :- | :- | :- |1880| :- | :- | :- | :- |
1873| `prompt` | string | `"Find all API endpoints"` | L'attività per l'agente da eseguire |1881| `prompt` | string | `"Find all API endpoints"` | L'attività che l'agente deve svolgere |
1874| `description` | string | `"Find API endpoints"` | Breve descrizione dell'attività |1882| `description` | string | `"Find API endpoints"` | Breve descrizione dell'attività |
1875| `subagent_type` | string | `"Explore"` | Tipo di agente specializzato da usare |1883| `subagent_type` | string | `"Explore"` | Tipo di agente specializzato da usare |
1876| `model` | string | `"sonnet"` | Alias di modello facoltativo per sovrascrivere il predefinito |1884| `model` | string | `"sonnet"` | Alias di modello facoltativo per sovrascrivere quello predefinito |
1877 1885
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:1886Quando 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 1887
1880| Campo | Tipo | Esempio | Descrizione |1888| Campo | Tipo | Esempio | Descrizione |
1881| :- | :- | :- | :- |1889| :- | :- | :- | :- |
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"` |1890| `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 |1891| `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 |1892| `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 |1893| `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 |1894| `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 |1895| `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 |1896| `totalDurationMs` | number | `48211` | Durata reale dell'esecuzione del subagent |
1889| `totalToolUseCount` | number | `7` | Conteggio delle chiamate di strumento che il subagente ha fatto |1897| `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` |1898| `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 1899
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`.1900Su 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 1901
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`.1902Per 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 1903
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.1904In 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 1905
1898<a id="askuserquestion" />1906<a id="askuserquestion" />
1899 1907
1901 AskUserQuestion1909 AskUserQuestion
1902</h5>1910</h5>
1903 1911
1904Chiede all'utente da una a quattro domande a scelta multipla.1912Pone all'utente da una a quattro domande a scelta multipla.
1905 1913
1906| Campo | Tipo | Esempio | Descrizione |1914| Campo | Tipo | Esempio | Descrizione |
1907| :- | :- | :- | :- |1915| :- | :- | :- | :- |
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 |1916| `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 |1917| `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 1918
1911<h5 id="exitplanmode">1919<h5 id="exitplanmode">
1912 ExitPlanMode1920 ExitPlanMode
1913</h5>1921</h5>
1914 1922
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.1923Presenta 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 1924
1917| Campo | Tipo | Esempio | Descrizione |1925| Campo | Tipo | Esempio | Descrizione |
1918| :- | :- | :- | :- |1926| :- | :- | :- | :- |
1919| `plan` | string | `"## Refactor auth\n1. Extract..."` | Contenuto del piano in Markdown. Iniettato dal file del piano su disco |1927| `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 |1928| `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 |1929| `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 1930
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.1931In `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 1932
1925<h4 id="pretooluse-decision-control">1933<h4 id="pretooluse-decision-control">
1926 Controllo decisionale PreToolUse1934 Controllo delle decisioni di PreToolUse
1927</h4>1935</h4>
1928 1936
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.1937Gli 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 1938
1931| Campo | Descrizione |1939| Campo | Descrizione |
1932| :- | :- |1940| :- | :- |
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 |1941| `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 |1942| `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 |1943| `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) |1944| `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 1945
1938Quando più hook PreToolUse restituiscono decisioni diverse, la precedenza è `deny` > `defer` > `ask` > `allow`.1946Quando più hook PreToolUse restituiscono decisioni diverse, l'ordine di precedenza è `deny` > `defer` > `ask` > `allow`.
1939 1947
1940Un hook che blocca uscendo con 2 si instrada allo stesso modo di `"deny"`: Claude vede il messaggio stderr come il motivo della negazione.1948Un hook che blocca terminando con 2 segue lo stesso percorso di `"deny"`: Claude vede il messaggio di stderr come motivo del rifiuto.
1941 1949
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.1950Quando 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 1951
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.1952Un `"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 1953
1946```json theme={null}1954```json theme={null}
1947{1955{
1959 1967
1960<span id="allow-with-updatedinput" />1968<span id="allow-with-updatedinput" />
1961 1969
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.1970In [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 1971
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.1972Uno 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 1973
1966<Note>1974<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.1975 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>1976</Note>
1969 1977
1970<h4 id="defer-a-tool-call-for-later">1978<h4 id="defer-a-tool-call-for-later">
1971 Differisci una chiamata di strumento per dopo1979 Differire una chiamata a uno strumento
1972</h4>1980</h4>
1973 1981
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.1982`"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 1983
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ì:1984Lo 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 1985
19781. Claude chiama `AskUserQuestion`. L'hook `PreToolUse` si esegue.19861. 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.19872. 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.19883. 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.19894. 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.19905. L'hook restituisce `permissionDecision: "allow"` con la risposta in `updatedInput`. Lo strumento viene eseguito e Claude continua.
1983 1991
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:1992Il 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 1993
1986```json theme={null}1994```json theme={null}
1987{1995{
1997}2005}
1998```2006```
1999 2007
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.2008Non 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 2009
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.2010`"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 2011
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.2012Se 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 2013
2006<Note>2014<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.2015 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 2016
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).2017 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>2018</Note>
2011 2019
2012<h3 id="permissionrequest">2020<h3 id="permissionrequest">
2013 PermissionRequest2021 PermissionRequest
2014</h3>2022</h3>
2015 2023
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.2024Viene 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.2025Usa il [controllo delle decisioni di PermissionRequest](#permissionrequest-decision-control) per consentire o negare per conto dell'utente.
2018 2026
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.2027Usa 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 2028
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`.2029Claude 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 2030
2023Corrisponde al nome dello strumento, stessi valori di PreToolUse.2031Effettua la corrispondenza sul nome dello strumento, con gli stessi valori di PreToolUse.
2024 2032
2025<h4 id="permissionrequest-input">2033<h4 id="permissionrequest-input">
2026 Input PermissionRequest2034 Input di PermissionRequest
2027</h4>2035</h4>
2028 2036
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.2037Gli 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 2038
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.2039L'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 2040
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).2041Gli 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 2042
2035```json theme={null}2043```json theme={null}
2036{2044{
2056```2064```
2057 2065
2058<h4 id="permissionrequest-decision-control">2066<h4 id="permissionrequest-decision-control">
2059 Controllo decisionale PermissionRequest2067 Controllo delle decisioni di PermissionRequest
2060</h4>2068</h4>
2061 2069
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:2070Gli 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 2071
2064| Campo | Descrizione |2072| Campo | Descrizione |
2065| :- | :- |2073| :- | :- |
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 |2074| `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 |2075| `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 |2076| `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 |2077| `message` | Solo per `"deny"`: indica a Claude perché il permesso è stato negato |
2070| `interrupt` | Per `"deny"` solo: se `true`, ferma Claude |2078| `interrupt` | Solo per `"deny"`: se `true`, ferma Claude |
2071 2079
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.2080Un 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 2081
2074```json theme={null}2082```json theme={null}
2075{2083{
2086```2094```
2087 2095
2088<h4 id="permission-update-entries">2096<h4 id="permission-update-entries">
2089 Voci di aggiornamento di permesso2097 Voci di aggiornamento dei permessi
2090</h4>2098</h4>
2091 2099
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.2100Il 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 2101
2094| `type` | Campi | Effetto |2102| `type` | Campi | Effetto |
2095| :- | :- | :- |2103| :- | :- | :- |
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"` |2104| `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 |2105| `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 |2106| `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 |2107| `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 |2108| `addDirectories` | `directories`, `destination` | Aggiunge directory di lavoro. `directories` è un array di stringhe di percorso |
2101| `removeDirectories` | `directories`, `destination` | Rimuove directory di lavoro |2109| `removeDirectories` | `directories`, `destination` | Rimuove directory di lavoro |
2102 2110
2103<Note>2111<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).2112 `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 2113
2106 `bypassPermissions` non viene mai persistito come `defaultMode` indipendentemente da `destination`.2114 `bypassPermissions` non viene mai reso persistente come `defaultMode`, indipendentemente da `destination`.
2107</Note>2115</Note>
2108 2116
2109Il campo `destination` su ogni voce determina se il cambio rimane in memoria o persiste in un file di impostazioni.2117Il campo `destination` di ogni voce determina se la modifica rimane in memoria o viene resa persistente in un file di impostazioni.
2110 2118
2111| `destination` | Scrive in |2119| `destination` | Scrive in |
2112| :- | :- |2120| :- | :- |
2113| `session` | solo in memoria, scartato quando la sessione termina |2121| `session` | solo in memoria, scartata al termine della sessione |
2114| `localSettings` | `.claude/settings.local.json` |2122| `localSettings` | `.claude/settings.local.json` |
2115| `projectSettings` | `.claude/settings.json` |2123| `projectSettings` | `.claude/settings.json` |
2116| `userSettings` | `~/.claude/settings.json` |2124| `userSettings` | `~/.claude/settings.json` |
2117 2125
2118Un hook può ripetere uno dei `permission_suggestions` che ha ricevuto come suo proprio output `updatedPermissions`.2126Un hook può restituire uno dei `permission_suggestions` ricevuti come proprio output `updatedPermissions`.
2119 2127
2120<h3 id="posttooluse">2128<h3 id="posttooluse">
2121 PostToolUse2129 PostToolUse
2122</h3>2130</h3>
2123 2131
2124Si esegue immediatamente dopo che uno strumento completa con successo.2132Viene eseguito subito dopo che uno strumento è stato completato con successo.
2125 2133
2126Corrisponde al nome dello strumento, stessi valori di PreToolUse.2134Fa corrispondere il nome dello strumento, con gli stessi valori di PreToolUse.
2127 2135
2128Corrisponde più ampiamente quando il nome dello strumento non è il filtro giusto:2136Usa una corrispondenza più ampia quando il nome dello strumento non è il filtro giusto:
2129 2137
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).2138* 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.2139* 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 2140
2133<h4 id="posttooluse-input">2141<h4 id="posttooluse-input">
2134 Input PostToolUse2142 Input di PostToolUse
2135</h4>2143</h4>
2136 2144
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).2145Gli 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 2146
2139```json theme={null}2147```json theme={null}
2140{2148{
2159 2167
2160| Campo | Descrizione |2168| Campo | Descrizione |
2161| :- | :- |2169| :- | :- |
2162| `duration_ms` | Facoltativo. Tempo di esecuzione dello strumento in millisecondi. Esclude il tempo trascorso nei prompt di permesso e negli hook PreToolUse |2170| `duration_ms` | Facoltativo. Tempo di esecuzione dello strumento in millisecondi. Esclude il tempo trascorso nelle richieste di permesso e negli hook PreToolUse |
2163 2171
2164<h4 id="posttooluse-decision-control">2172<h4 id="posttooluse-decision-control">
2165 Controllo decisionale PostToolUse2173 Controllo delle decisioni di PostToolUse
2166</h4>2174</h4>
2167 2175
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:2176Gli 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 2177
2170| Campo | Descrizione |2178| Campo | Descrizione |
2171| :- | :- |2179| :- | :- |
2172| `decision` | `"block"` aggiunge il `reason` accanto al risultato dello strumento. Claude vede comunque l'output originale; per sostituirlo, usa `updatedToolOutput` |2180| `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"` |2181| `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) |2182| `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 |2183| `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 |2184| `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 |2185| `updatedMCPToolOutput` | Sostituisce l'output solo per gli [strumenti MCP](#match-mcp-tools). Preferisci `updatedToolOutput`, che funziona per tutti gli strumenti |
2178 2186
2179L'esempio sottostante sostituisce l'output di una chiamata `Bash`. Il valore di sostituzione corrisponde alla forma di output dello strumento `Bash`:2187L'esempio seguente sostituisce l'output di una chiamata `Bash`. Il valore sostitutivo corrisponde alla forma dell'output dello strumento `Bash`:
2180 2188
2181```json theme={null}2189```json theme={null}
2182{2190{
2194```2202```
2195 2203
2196<Warning>2204<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.2205 `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 2206
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.2207 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>2208</Warning>
2201 2209
2202<h4 id="annotate-a-result-for-the-auto-mode-classifier">2210<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2203 Annota un risultato per il classificatore della modalità auto2211 Annotare un risultato per il classificatore della modalità auto
2204</h4>2212</h4>
2205 2213
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.2214Restituisci `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 2215
2208L'esempio sottostante dice al classificatore da dove proviene l'output di una query:2216L'esempio seguente indica al classificatore da dove proviene l'output di una query:
2209 2217
2210```json theme={null}2218```json theme={null}
2211{2219{
2216}2224}
2217```2225```
2218 2226
2219Quanto peso il classificatore dà alla nota dipende da dove hai configurato l'hook:2227Il peso che il classificatore attribuisce alla nota dipende da dove hai configurato l'hook:
2220 2228
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 conversazione2229* **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 verificata2230* **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 2231
2224Claude Code applica questi limiti quando consegna la nota:2232Claude Code applica questi limiti quando consegna la nota:
2225 2233
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 chiamata2234* **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 strumento2235* **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 chiamate2236* **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'output2237* **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 2238
2231<Warning>2239<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.2240 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>2241</Warning>
2234 2242
2235<h3 id="posttoolusefailure">2243<h3 id="posttoolusefailure">
2236 PostToolUseFailure2244 PostToolUseFailure
2237</h3>2245</h3>
2238 2246
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.2247Viene 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 2248
2241Corrisponde al nome dello strumento, stessi valori di PreToolUse.2249Fa corrispondere il nome dello strumento, con gli stessi valori di PreToolUse.
2242 2250
2243<Note>2251<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).2252 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>2253</Note>
2246 2254
2247<h4 id="posttoolusefailure-input">2255<h4 id="posttoolusefailure-input">
2248 Input PostToolUseFailure2256 Input di PostToolUseFailure
2249</h4>2257</h4>
2250 2258
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:2259Gli 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 2260
2253```json theme={null}2261```json theme={null}
2254{2262{
2271 2279
2272| Campo | Descrizione |2280| Campo | Descrizione |
2273| :- | :- |2281| :- | :- |
2274| `error` | Stringa che descrive cosa è andato male. Il formato dipende dallo strumento che ha fallito |2282| `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 |2283| `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 |2284| `duration_ms` | Facoltativo. Tempo di esecuzione dello strumento in millisecondi. Esclude il tempo trascorso nelle richieste di permesso e negli hook PreToolUse |
2277 2285
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.2286La 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 2287
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 intercalati2288* 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 stesso2289* 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`2290* 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 2291
2284<h4 id="posttoolusefailure-decision-control">2292<h4 id="posttoolusefailure-decision-control">
2285 Controllo decisionale PostToolUseFailure2293 Controllo delle decisioni di PostToolUseFailure
2286</h4>2294</h4>
2287 2295
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:2296Gli 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 2297
2290| Campo | Descrizione |2298| Campo | Descrizione |
2291| :- | :- |2299| :- | :- |
2292| `additionalContext` | Stringa aggiunta al contesto di Claude insieme all'errore. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |2300| `additionalContext` | Stringa aggiunta al contesto di Claude insieme all'errore. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |
2293 2301
2294```json theme={null}2302```json theme={null}
2295{2303{
2304 PostToolBatch2312 PostToolBatch
2305</h3>2313</h3>
2306 2314
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.2315Viene 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 2316
2309<h4 id="posttoolbatch-input">2317<h4 id="posttoolbatch-input">
2310 Input PostToolBatch2318 Input di PostToolBatch
2311</h4>2319</h4>
2312 2320
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:2321Oltre 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 2322
2315```json theme={null}2323```json theme={null}
2316{2324{
2336}2344}
2337```2345```
2338 2346
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.2347`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 2348
2341<Note>2349<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.2350 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>2351</Note>
2344 2352
2345<h4 id="posttoolbatch-decision-control">2353<h4 id="posttoolbatch-decision-control">
2346 Controllo decisionale PostToolBatch2354 Controllo delle decisioni di PostToolBatch
2347</h4>2355</h4>
2348 2356
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:2357Gli 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 2358
2351| Campo | Descrizione |2359| Campo | Descrizione |
2352| :- | :- |2360| :- | :- |
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 |2361| `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 2362
2355```json theme={null}2363```json theme={null}
2356{2364{
2361}2369}
2362```2370```
2363 2371
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.2372Restituire `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 2373
2366<h3 id="permissiondenied">2374<h3 id="permissiondenied">
2367 PermissionDenied2375 PermissionDenied
2368</h3>2376</h3>
2369 2377
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.2378Viene 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 2379
2372Corrisponde al nome dello strumento, stessi valori di PreToolUse.2380Fa corrispondere il nome dello strumento, con gli stessi valori di PreToolUse.
2373 2381
2374<h4 id="permissiondenied-input">2382<h4 id="permissiondenied-input">
2375 Input PermissionDenied2383 Input di PermissionDenied
2376</h4>2384</h4>
2377 2385
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).2386Oltre 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 2387
2380```json theme={null}2388```json theme={null}
2381{2389{
2396 2404
2397| Campo | Descrizione |2405| Campo | Descrizione |
2398| :- | :- |2406| :- | :- |
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` |2407| `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 2408
2401<h4 id="permissiondenied-decision-control">2409<h4 id="permissiondenied-decision-control">
2402 Controllo decisionale PermissionDenied2410 Controllo delle decisioni di PermissionDenied
2403</h4>2411</h4>
2404 2412
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`:2413Gli 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 2414
2407```json theme={null}2415```json theme={null}
2408{2416{
2413}2421}
2414```2422```
2415 2423
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.2424Quando `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 2425
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.2426Claude 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 2427
2420<h3 id="notification">2428<h3 id="notification">
2421 Notification2429 Notification
2422</h3>2430</h3>
2423 2431
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.2432Viene 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 2433
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.2434Ricevi 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 2435
2428| Matcher | Quando si attiva |2436| Matcher | Quando si attiva |
2429| :- | :- |2437| :- | :- |
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 |2438| `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 |2439| `idle_prompt` | Claude ha finito di rispondere circa 60 secondi fa e da allora non hai digitato nulla |
2432| `auth_success` | L'autenticazione completa |2440| `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 |2441| `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 |2442| `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 |2443| `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 |2444| `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 |2445| `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 |2446| `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) |2447| `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 |2448| `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** |2449| `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 2450
2443I tipi `quota_auto_resume_fired`, `quota_auto_resume_stale`, e `quota_auto_resume_disabled` richiedono Claude Code v2.1.234 o successivo.2451I tipi `quota_auto_resume_fired`, `quota_auto_resume_stale` e `quota_auto_resume_disabled` richiedono Claude Code v2.1.234 o successiva.
2444 2452
2445Nelle sessioni di terminale, `permission_prompt` per la richiesta di rete di un comando sandboxed richiede Claude Code v2.1.246 o successivo.2453Nelle sessioni nel terminale, `permission_prompt` per la richiesta di rete di un comando in sandbox richiede Claude Code v2.1.246 o successiva.
2446 2454
2447`agent_needs_input` per una domanda di configurazione del terminale del compagno di squadra richiede Claude Code v2.1.248 o successivo.2455`agent_needs_input` per la domanda di configurazione del terminale di un compagno di team richiede Claude Code v2.1.248 o successiva.
2448 2456
2449<Note>2457<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:2458 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 2459
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.2460 * 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.2461 * 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.2462 * 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 2463
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.2464 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>2465</Note>
2458 2466
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:2467Claude 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 2468
2461* Aspettati `permission_prompt` circa sei secondi dopo che Claude chiede il permesso. Claude Code non lo rinvia mentre digiti.2469* 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`.2470* 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.2471* Imposta [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/it/env-vars) su `1` per disattivare `permission_prompt` in queste sessioni.
2464 2472
2465Prima della v2.1.233, `permission_prompt` non si eseguiva in queste sessioni.2473Prima della v2.1.233, `permission_prompt` non si attivava in queste sessioni.
2466 2474
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:2475Usa 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 2476
2469```json theme={null}2477```json theme={null}
2470{2478{
2494```2502```
2495 2503
2496<h4 id="notification-input">2504<h4 id="notification-input">
2497 Input Notification2505 Input di Notification
2498</h4>2506</h4>
2499 2507
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.2508Oltre 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 2509
2502```json theme={null}2510```json theme={null}
2503{2511{
2511}2519}
2512```2520```
2513 2521
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.2522Gli 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 2523
2516<h3 id="subagentstart">2524<h3 id="subagentstart">
2517 SubagentStart2525 SubagentStart
2518</h3>2526</h3>
2519 2527
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.2528Viene 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 2529
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$`.2530Per 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 2531
2524<h4 id="subagentstart-input">2532<h4 id="subagentstart-input">
2525 Input SubagentStart2533 Input di SubagentStart
2526</h4>2534</h4>
2527 2535
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.2536Oltre 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 2537
2530```json theme={null}2538```json theme={null}
2531{2539{
2538}2546}
2539```2547```
2540 2548
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:2549Gli 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 2550
2543| Campo | Descrizione |2551| Campo | Descrizione |
2544| :- | :- |2552| :- | :- |
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) |2553| `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 2554
2547```json theme={null}2555```json theme={null}
2548{2556{
2553}2561}
2554```2562```
2555 2563
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.2564Quando 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 2565
2558<h3 id="subagentstop">2566<h3 id="subagentstop">
2559 SubagentStop2567 SubagentStop
2560</h3>2568</h3>
2561 2569
2562Si esegue quando un subagente di Claude Code ha finito di rispondere. Corrisponde al tipo di agente, stessi valori di SubagentStart.2570Viene eseguito quando un subagent di Claude Code ha finito di rispondere. Fa corrispondere il tipo di agente, con gli stessi valori di SubagentStart.
2563 2571
2564<h4 id="subagentstop-input">2572<h4 id="subagentstop-input">
2565 Input SubagentStop2573 Input di SubagentStop
2566</h4>2574</h4>
2567 2575
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.2576Oltre 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 2577
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.2578Non 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 2579
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.2580Un `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 2581
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`.2582Su 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 2583
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.2584Gli 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 2585
2578```json theme={null}2586```json theme={null}
2579{2587{
2592}2600}
2593```2601```
2594 2602
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.2603Gli 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 2604
2597<h3 id="taskcreated">2605<h3 id="taskcreated">
2598 TaskCreated2606 TaskCreated
2599</h3>2607</h3>
2600 2608
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.2609Viene 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 2610
2603Gli hook TaskCreated non supportano i matcher e si eseguono su ogni occorrenza.2611Gli hook TaskCreated non supportano i matcher e si attivano a ogni occorrenza.
2604 2612
2605<h4 id="taskcreated-input">2613<h4 id="taskcreated-input">
2606 Input TaskCreated2614 Input di TaskCreated
2607</h4>2615</h4>
2608 2616
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`.2617Oltre 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 2618
2611```json theme={null}2619```json theme={null}
2612{2620{
2624 2632
2625| Campo | Descrizione |2633| Campo | Descrizione |
2626| :- | :- |2634| :- | :- |
2627| `task_id` | Identificatore dell'attività in fase di creazione |2635| `task_id` | Identificatore del task in fase di creazione |
2628| `task_subject` | Titolo dell'attività |2636| `task_subject` | Titolo del task |
2629| `task_description` | Descrizione dettagliata dell'attività. Può essere assente |2637| `task_description` | Descrizione dettagliata del task. Può essere assente |
2630| `teammate_name` | Nome del compagno di squadra che crea l'attività. Può essere assente |2638| `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 |2639| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |
2632 2640
2633<h4 id="taskcreated-decision-control">2641<h4 id="taskcreated-decision-control">
2634 Controllo decisionale TaskCreated2642 Controllo delle decisioni di TaskCreated
2635</h4>2643</h4>
2636 2644
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.2645Un 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 2646
2639* **Codice di uscita 2**: Claude Code restituisce il testo stderr come messaggio.2647* **Codice di uscita 2**: Claude Code restituisce il testo di stderr come messaggio.
2640* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code restituisce `reason` come messaggio.2648* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code restituisce `reason` come messaggio.
2641 2649
2642Questo esempio blocca le attività i cui soggetti non seguono il formato richiesto:2650Questo esempio blocca i task i cui oggetti non seguono il formato richiesto:
2643 2651
2644```bash theme={null}2652```bash theme={null}
2645#!/bin/bash2653#!/bin/bash
2658 TaskCompleted2666 TaskCompleted
2659</h3>2667</h3>
2660 2668
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.2669Viene 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 2670
2663Gli hook TaskCompleted non supportano i matcher e si eseguono su ogni occorrenza.2671Gli hook TaskCompleted non supportano i matcher e si attivano a ogni occorrenza.
2664 2672
2665<h4 id="taskcompleted-input">2673<h4 id="taskcompleted-input">
2666 Input TaskCompleted2674 Input di TaskCompleted
2667</h4>2675</h4>
2668 2676
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`.2677Oltre 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 2678
2671```json theme={null}2679```json theme={null}
2672{2680{
2685 2693
2686| Campo | Descrizione |2694| Campo | Descrizione |
2687| :- | :- |2695| :- | :- |
2688| `task_id` | Identificatore dell'attività in fase di completamento |2696| `task_id` | Identificatore del task in fase di completamento |
2689| `task_subject` | Titolo dell'attività |2697| `task_subject` | Titolo del task |
2690| `task_description` | Descrizione dettagliata dell'attività. Può essere assente |2698| `task_description` | Descrizione dettagliata del task. Può essere assente |
2691| `teammate_name` | Nome del compagno di squadra che completa l'attività. Può essere assente |2699| `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 |2700| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |
2693 2701
2694<h4 id="taskcompleted-decision-control">2702<h4 id="taskcompleted-decision-control">
2695 Controllo decisionale TaskCompleted2703 Controllo delle decisioni di TaskCompleted
2696</h4>2704</h4>
2697 2705
2698Gli hook TaskCompleted supportano due modi per controllare il completamento dell'attività:2706Gli hook TaskCompleted supportano due modi per controllare il completamento dei task:
2699 2707
2700* **Codice di uscita 2**: l'attività non viene contrassegnata come completata e il messaggio stderr viene restituito al modello come feedback.2708* **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.2709* **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 2710
2703Questo esempio esegue i test e blocca il completamento dell'attività se falliscono:2711Questo esempio esegue i test e blocca il completamento del task se falliscono:
2704 2712
2705```bash theme={null}2713```bash theme={null}
2706#!/bin/bash2714#!/bin/bash
2720 Stop2728 Stop
2721</h3>2729</h3>
2722 2730
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.2731Viene eseguito quando l'agente principale di Claude Code ha finito di rispondere. Non viene eseguito se
2732l'arresto è avvenuto a causa di un'interruzione da parte dell'utente. Gli errori API attivano
2733invece [StopFailure](#stopfailure).
2724 2734
2725<Tip>2735<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.2736 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>2737</Tip>
2728 2738
2729<h4 id="stop-input">2739<h4 id="stop-input">
2730 Input Stop2740 Input di Stop
2731</h4>2741</h4>
2732 2742
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).2743Oltre 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 2744
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.2745Il 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 2746
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.2747Gli 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 2748
2739Ogni voce in `background_tasks` descrive un'attività in volo e usa questi campi:2749Ogni voce in `background_tasks` descrive un task in corso e usa questi campi:
2740 2750
2741| Campo | Descrizione |2751| Campo | Descrizione |
2742| :- | :- |2752| :- | :- |
2743| `id` | Identificatore dell'attività |2753| `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 |2754| `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 |2755| `status` | Stato attuale del task |
2746| `description` | Descrizione in testo libero, limitata a 1000 caratteri con un marcatore `… [+N chars]` in-stringa quando ritagliato |2756| `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` |2757| `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` |2758| `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` |2759| `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` |2760| `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` |2761| `name` | Nome del workflow. Presente solo per i task `workflow` |
2752 2762
2753Ogni voce in `session_crons` descrive un risveglio programmato con ambito di sessione, proveniente da `CronCreate`, `ScheduleWakeup`, e `/loop`:2763Ogni voce in `session_crons` descrive una riattivazione pianificata con ambito di sessione, proveniente da `CronCreate`, `ScheduleWakeup` e `/loop`:
2754 2764
2755| Campo | Descrizione |2765| Campo | Descrizione |
2756| :- | :- |2766| :- | :- |
2757| `id` | Identificatore dell'attività cron |2767| `id` | Identificatore del task cron |
2758| `schedule` | Espressione cron, ad esempio `0 9 * * 1-5` |2768| `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 |2769| `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]` |2770| `prompt` | Prompt inviato quando il cron si attiva, limitato a 1000 caratteri con lo stesso indicatore `… [+N chars]` |
2761 2771
2762Questo esempio mostra un input Stop con un'attività shell in volo e un cron ricorrente:2772Questo esempio mostra un input di Stop con un task shell in corso e un cron ricorrente:
2763 2773
2764```json theme={null}2774```json theme={null}
2765{2775{
2791```2801```
2792 2802
2793<h4 id="stop-decision-control">2803<h4 id="stop-decision-control">
2794 Controllo decisionale Stop2804 Controllo delle decisioni di Stop
2795</h4>2805</h4>
2796 2806
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:2807Gli 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 2808
2799| Campo | Descrizione |2809| Campo | Descrizione |
2800| :- | :- |2810| :- | :- |
2801| `decision` | `"block"` impedisce a Claude di fermarsi. Ometti per consentire a Claude di fermarsi |2811| `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 |2812| `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 |2813| `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 2814
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.2815Un 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 2816
2807```json theme={null}2817```json theme={null}
2808{2818{
2811}2821}
2812```2822```
2813 2823
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:2824Usa `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 2825
2816```json theme={null}2826```json theme={null}
2817{2827{
2826 StopFailure2836 StopFailure
2827</h3>2837</h3>
2828 2838
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.2839Viene 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 2840
2831<h4 id="stopfailure-input">2841<h4 id="stopfailure-input">
2832 Input StopFailure2842 Input di StopFailure
2833</h4>2843</h4>
2834 2844
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.2845Oltre 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 2846
2837| Campo | Descrizione |2847| Campo | Descrizione |
2838| :- | :- |2848| :- | :- |
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` |2849| `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 |2850| `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"` |2851| `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 2852
2843```json theme={null}2853```json theme={null}
2844{2854{
2852}2862}
2853```2863```
2854 2864
2855Gli hook StopFailure non hanno controllo decisionale. Si eseguono solo per scopi di notifica e logging.2865Gli hook StopFailure non hanno controllo delle decisioni. Vengono eseguiti solo a scopo di notifica e di log.
2856 2866
2857<h3 id="teammateidle">2867<h3 id="teammateidle">
2858 TeammateIdle2868 TeammateIdle
2859</h3>2869</h3>
2860 2870
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.2871Viene 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 2872
2863Gli hook TeammateIdle non supportano i matcher e si eseguono su ogni occorrenza.2873Gli hook TeammateIdle non supportano i matcher e si attivano a ogni occorrenza.
2864 2874
2865<h4 id="teammateidle-input">2875<h4 id="teammateidle-input">
2866 Input TeammateIdle2876 Input di TeammateIdle
2867</h4>2877</h4>
2868 2878
2869Oltre ai [campi di input comuni](#common-input-fields), gli hook TeammateIdle ricevono `teammate_name` e `team_name`.2879Oltre ai [campi di input comuni](#common-input-fields), gli hook TeammateIdle ricevono `teammate_name` e `team_name`.
2882 2892
2883| Campo | Descrizione |2893| Campo | Descrizione |
2884| :- | :- |2894| :- | :- |
2885| `teammate_name` | Nome del compagno di squadra che sta per andare inattivo |2895| `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 |2896| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |
2887 2897
2888<h4 id="teammateidle-decision-control">2898<h4 id="teammateidle-decision-control">
2889 Controllo decisionale TeammateIdle2899 Controllo delle decisioni di TeammateIdle
2890</h4>2900</h4>
2891 2901
2892Gli hook TeammateIdle supportano due modi per controllare il comportamento del compagno di squadra:2902Gli hook TeammateIdle supportano due modi per controllare il comportamento dei compagni di team:
2893 2903
2894* **Codice di uscita 2**: il compagno di squadra riceve il messaggio stderr come feedback e continua a lavorare invece di andare inattivo.2904* **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.2905* **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 2906
2897Questo esempio controlla che un artefatto di build esista prima di consentire a un compagno di squadra di andare inattivo:2907Questo esempio verifica che un artefatto di build esista prima di consentire a un compagno di team di diventare inattivo:
2898 2908
2899```bash theme={null}2909```bash theme={null}
2900#!/bin/bash2910#!/bin/bash
2911 ConfigChange2921 ConfigChange
2912</h3>2922</h3>
2913 2923
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.2924Viene 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 2925
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.2926Claude 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 2927
2918Il matcher filtra sulla fonte di configurazione:2928Il matcher filtra in base all'origine della configurazione:
2919 2929
2920| Matcher | Quando si attiva |2930| Matcher | Quando si attiva |
2921| :- | :- |2931| :- | :- |
2922| `user_settings` | `~/.claude/settings.json` cambia |2932| `user_settings` | Cambia `~/.claude/settings.json` |
2923| `project_settings` | `.claude/settings.json` cambia |2933| `project_settings` | Cambia `.claude/settings.json` |
2924| `local_settings` | `.claude/settings.local.json` cambia |2934| `local_settings` | Cambia `.claude/settings.local.json` |
2925| `policy_settings` | `managed-settings.json` o un file in `managed-settings.d/` cambia |2935| `policy_settings` | Cambia `managed-settings.json` o un file in `managed-settings.d/` |
2926| `skills` | Un file di skill in `.claude/skills/` cambia |2936| `skills` | Cambia un file di skill in `.claude/skills/` |
2927 2937
2928Questo esempio registra tutti i cambiamenti di configurazione per il controllo di sicurezza:2938Questo esempio registra tutte le modifiche alla configurazione per la verifica della sicurezza:
2929 2939
2930```json theme={null}2940```json theme={null}
2931{2941{
2946```2956```
2947 2957
2948<h4 id="configchange-input">2958<h4 id="configchange-input">
2949 Input ConfigChange2959 Input di ConfigChange
2950</h4>2960</h4>
2951 2961
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.2962Oltre 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 2963
2954```json theme={null}2964```json theme={null}
2955{2965{
2963```2973```
2964 2974
2965<h4 id="configchange-decision-control">2975<h4 id="configchange-decision-control">
2966 Controllo decisionale ConfigChange2976 Controllo delle decisioni di ConfigChange
2967</h4>2977</h4>
2968 2978
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.2979Gli 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 2980
2971| Campo | Descrizione |2981| Campo | Descrizione |
2972| :- | :- |2982| :- | :- |
2973| `decision` | `"block"` impedisce l'applicazione del cambio di configurazione. Ometti per consentire il cambio |2983| `decision` | `"block"` impedisce che la modifica alla configurazione venga applicata. Omettilo per consentire la modifica |
2974| `reason` | Accettato ma mai mostrato |2984| `reason` | Accettato ma mai mostrato |
2975 2985
2976```json theme={null}2986```json theme={null}
2980}2990}
2981```2991```
2982 2992
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.2993Le 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 2994
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.2995Claude 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 2996
2987<h3 id="cwdchanged">2997<h3 id="cwdchanged">
2988 CwdChanged2998 CwdChanged
2989</h3>2999</h3>
2990 3000
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.3001Viene 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 3002
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.3003Gli 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 3004
2995CwdChanged non supporta i matcher e si esegue su ogni occorrenza.3005CwdChanged non supporta i matcher e si attiva a ogni occorrenza.
2996 3006
2997<h4 id="cwdchanged-input">3007<h4 id="cwdchanged-input">
2998 Input CwdChanged3008 Input di CwdChanged
2999</h4>3009</h4>
3000 3010
3001Oltre ai [campi di input comuni](#common-input-fields), gli hook CwdChanged ricevono `old_cwd` e `new_cwd`.3011Oltre ai [campi di input comuni](#common-input-fields), gli hook CwdChanged ricevono `old_cwd` e `new_cwd`.
3012```3022```
3013 3023
3014<h4 id="cwdchanged-output">3024<h4 id="cwdchanged-output">
3015 Output CwdChanged3025 Output di CwdChanged
3016</h4>3026</h4>
3017 3027
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:3028Oltre 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 3029
3020| Campo | Descrizione |3030| Campo | Descrizione |
3021| :- | :- |3031| :- | :- |
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 |3032| `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 3033
3024Gli hook CwdChanged non hanno controllo decisionale. Non possono bloccare il cambio di directory.3034Gli hook CwdChanged non hanno controllo delle decisioni. Non possono bloccare il cambio di directory.
3025 3035
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.3036Claude 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 3037
3028<h3 id="directoryadded">3038<h3 id="directoryadded">
3029 DirectoryAdded3039 DirectoryAdded
3030</h3>3040</h3>
3031 3041
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.3042Viene 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 3043
3034Claude Code non esegue questo evento quando:3044Claude Code non attiva questo evento quando:
3035 3045
3036* Passi una directory con il flag di avvio `--add-dir`; [SessionStart](#sessionstart) copre quelle directory3046* Passi una directory con il flag di avvio `--add-dir`; [SessionStart](#sessionstart) copre quelle directory
3037* Aggiungi una directory sulla scheda Workspace `/permissions`3047* Aggiungi una directory nella scheda Workspace di `/permissions`
3038* Aggiungi una directory che è già una directory di lavoro o dentro una3048* Aggiungi una directory che è già una directory di lavoro o che si trova all'interno di una
3039 3049
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.3050Claude 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 3051
3042Claude Code non attende l'hook: l'aggiunta completa immediatamente, e l'hook si esegue in background con il timeout predefinito di 600 secondi.3052Claude 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 3053
3044Il matcher filtra su come la directory è stata aggiunta:3054Il matcher filtra in base a come è stata aggiunta la directory:
3045 3055
3046| Matcher | Quando si attiva |3056| Matcher | Quando si attiva |
3047| :- | :- |3057| :- | :- |
3049| `register_repo_root` | Un client SDK aggiunge una directory con la richiesta di controllo `register_repo_root` |3059| `register_repo_root` | Un client SDK aggiunge una directory con la richiesta di controllo `register_repo_root` |
3050 3060
3051<h4 id="directoryadded-input">3061<h4 id="directoryadded-input">
3052 Input DirectoryAdded3062 Input di DirectoryAdded
3053</h4>3063</h4>
3054 3064
3055Oltre ai [campi di input comuni](#common-input-fields), gli hook DirectoryAdded ricevono `directory` e `source`.3065Oltre ai [campi di input comuni](#common-input-fields), gli hook DirectoryAdded ricevono `directory` e `source`.
3056 3066
3057| Campo | Descrizione |3067| Campo | Descrizione |
3058| :- | :- |3068| :- | :- |
3059| `directory` | Percorso assoluto della directory che è stata aggiunta |3069| `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 |3070| `source` | Come è stata aggiunta la directory, `"slash_command"` per `/add-dir` o `"register_repo_root"` per la richiesta di controllo dell'SDK |
3061 3071
3062```json theme={null}3072```json theme={null}
3063{3073{
3070}3080}
3071```3081```
3072 3082
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:3083Gli 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 3084
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 log3085* `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 solo3086* `register_repo_root`: Claude Code scrive l'output di `systemMessage` e l'output dei fallimenti solo nel log di debug
3077 3087
3078<h3 id="filechanged">3088<h3 id="filechanged">
3079 FileChanged3089 FileChanged
3080</h3>3090</h3>
3081 3091
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.3092Viene 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 3093
3084Il `matcher` per questo evento serve due ruoli:3094Il `matcher` per questo evento svolge due ruoli:
3085 3095
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`.3096* **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.3097* **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 3098
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:3099Questo 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 3100
3091```json theme={null}3101```json theme={null}
3092{3102{
3106}3116}
3107```3117```
3108 3118
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:3119L'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 3120
3111```bash theme={null}3121```bash theme={null}
3112#!/bin/bash3122#!/bin/bash
3116fi3126fi
3117```3127```
3118 3128
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.3129Per 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 3130
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 `*`.3131Per 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 3132
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.3133Gli 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 3134
3125<h4 id="filechanged-input">3135<h4 id="filechanged-input">
3126 Input FileChanged3136 Input di FileChanged
3127</h4>3137</h4>
3128 3138
3129Oltre ai [campi di input comuni](#common-input-fields), gli hook FileChanged ricevono `file_path` e `event`.3139Oltre ai [campi di input comuni](#common-input-fields), gli hook FileChanged ricevono `file_path` ed `event`.
3130 3140
3131| Campo | Descrizione |3141| Campo | Descrizione |
3132| :- | :- |3142| :- | :- |
3133| `file_path` | Percorso assoluto al file che è cambiato |3143| `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 |3144| `event` | Cosa è successo: `"change"` per un file modificato, `"add"` per un file creato o `"unlink"` per un file eliminato |
3135 3145
3136```json theme={null}3146```json theme={null}
3137{3147{
3145```3155```
3146 3156
3147<h4 id="filechanged-output">3157<h4 id="filechanged-output">
3148 Output FileChanged3158 Output di FileChanged
3149</h4>3159</h4>
3150 3160
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:3161Oltre 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 3162
3153| Campo | Descrizione |3163| Campo | Descrizione |
3154| :- | :- |3164| :- | :- |
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 |3165| `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 3166
3157Gli hook FileChanged non hanno controllo decisionale. Non possono bloccare il cambio del file dal verificarsi.3167Gli hook FileChanged non hanno controllo delle decisioni. Non possono impedire che la modifica del file avvenga.
3158 3168
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.3169Claude 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 3170
3161<h3 id="worktreecreate">3171<h3 id="worktreecreate">
3162 WorktreeCreate3172 WorktreeCreate
3163</h3>3173</h3>
3164 3174
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.3175Viene 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 3176
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.3177Poiché 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 3178
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.3179L'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 3180
3171Claude Code agisce sul successo dell'hook e sul percorso restituito, e scarta `systemMessage` e `continue`.3181Claude Code agisce sull'esito positivo dell'hook e sul percorso restituito, e scarta `systemMessage` e `continue`.
3172 3182
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:3183Questo 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 3184
3175```json theme={null}3185```json theme={null}
3176{3186{
3189}3199}
3190```3200```
3191 3201
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.3202L'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 3203
3194<h4 id="worktreecreate-input">3204<h4 id="worktreecreate-input">
3195 Input WorktreeCreate3205 Input di WorktreeCreate
3196</h4>3206</h4>
3197 3207
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`.3208Oltre 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 3209
3200```json theme={null}3210```json theme={null}
3201{3211{
3208```3218```
3209 3219
3210<h4 id="worktreecreate-output">3220<h4 id="worktreecreate-output">
3211 Output WorktreeCreate3221 Output di WorktreeCreate
3212</h4>3222</h4>
3213 3223
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:3224Gli 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 3225
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.3226* **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.3227* **Hook HTTP** (`type: "http"`): restituisci `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` nel corpo della risposta.
3218 3228
3219Se l'hook fallisce o non produce alcun percorso, la creazione del worktree fallisce con un errore.3229Se l'hook fallisce o non produce alcun percorso, la creazione del worktree fallisce con un errore.
3220 3230
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.3231Claude 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 3232
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.3233Claude 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 3234
3225<h3 id="worktreeremove">3235<h3 id="worktreeremove">
3226 WorktreeRemove3236 WorktreeRemove
3227</h3>3237</h3>
3228 3238
3229Si esegue quando un worktree viene rimosso. Questo è il contrapparte di pulizia di [WorktreeCreate](#worktreecreate). L'evento si esegue quando:3239Viene eseguito quando un worktree sta per essere rimosso. È la controparte di pulizia di [WorktreeCreate](#worktreecreate). L'evento si attiva quando:
3230 3240
3231* esci da una sessione `--worktree` e scegli di rimuoverla3241* esci da una sessione `--worktree` e scegli di rimuoverlo
3232* un subagente con `isolation: "worktree"` finisce3242* 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 creato3243* elimini una [sessione in background](/docs/it/agent-view#what-deleting-a-session-removes) il cui worktree è stato creato dall'hook
3234 3244
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:3245Per 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 3246
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.3247* **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.3248* **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).3249* **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 3250
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.3251Claude 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 3252
3243Claude Code scarta i [campi di output JSON](#json-output) di un hook WorktreeRemove, come `systemMessage` e `continue`.3253Claude Code scarta i [campi di output JSON](#json-output) di un hook WorktreeRemove, come `systemMessage` e `continue`.
3244 3254
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.3255Per 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 3256
3247Claude Code passa il percorso restituito da WorktreeCreate come `worktree_path` nell'input dell'hook. Questo esempio legge quel percorso e rimuove la directory:3257Claude Code passa il percorso restituito da WorktreeCreate come `worktree_path` nell'input dell'hook. Questo esempio legge quel percorso e rimuove la directory:
3248 3258
3264```3274```
3265 3275
3266<h4 id="worktreeremove-input">3276<h4 id="worktreeremove-input">
3267 Input WorktreeRemove3277 Input di WorktreeRemove
3268</h4>3278</h4>
3269 3279
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.3280Oltre 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 3281
3272```json theme={null}3282```json theme={null}
3273{3283{
3279}3289}
3280```3290```
3281 3291
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:3292Il 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 3293
3284* Il worktree rimane su disco, e il comando dell'hook e stderr vanno nel [debug log](#debug-hooks).3294* 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.3295* 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 3296
3287<h3 id="precompact">3297<h3 id="precompact">
3288 PreCompact3298 PreCompact
3289</h3>3299</h3>
3290 3300
3291Si esegue prima che Claude Code stia per eseguire un'operazione di compattazione.3301Viene eseguito prima che Claude Code stia per eseguire un'operazione di compattazione.
3292 3302
3293Il valore del matcher indica se la compattazione è stata attivata manualmente o automaticamente:3303Il valore del matcher indica se la compattazione è stata attivata manualmente o automaticamente:
3294 3304
3299 3309
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"`.3310Esci 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 3311
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.3312Bloccare 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 3313
3304Claude Code scarta i campi `systemMessage` e `continue` di un hook PreCompact.3314Claude Code scarta i campi `systemMessage` e `continue` di un hook PreCompact.
3305 3315
3306<h4 id="precompact-input">3316<h4 id="precompact-input">
3307 Input PreCompact3317 Input di PreCompact
3308</h4>3318</h4>
3309 3319
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`.3320Oltre 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 3321
3312```json theme={null}3322```json theme={null}
3313{3323{
3324 PostCompact3334 PostCompact
3325</h3>3335</h3>
3326 3336
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.3337Viene 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 3338
3329Gli stessi valori di matcher si applicano come per `PreCompact`:3339Si applicano gli stessi valori del matcher di `PreCompact`:
3330 3340
3331| Matcher | Quando si attiva |3341| Matcher | Quando si attiva |
3332| :- | :- |3342| :- | :- |
3334| `auto` | Dopo la compattazione automatica quando la conversazione raggiunge la [finestra di compattazione automatica](/docs/it/model-config#set-the-auto-compact-window) |3344| `auto` | Dopo la compattazione automatica quando la conversazione raggiunge la [finestra di compattazione automatica](/docs/it/model-config#set-the-auto-compact-window) |
3335 3345
3336<h4 id="postcompact-input">3346<h4 id="postcompact-input">
3337 Input PostCompact3347 Input di PostCompact
3338</h4>3348</h4>
3339 3349
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.3350Oltre 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}3360}
3351```3361```
3352 3362
3353Gli hook PostCompact non hanno controllo decisionale. Non possono influenzare il risultato della compattazione ma possono eseguire attività di follow-up.3363Gli hook PostCompact non hanno controllo decisionale. Non possono influenzare il risultato della compattazione ma possono eseguire attività successive.
3354 3364
3355<h3 id="premodelswitch">3365<h3 id="premodelswitch">
3356 PreModelSwitch3366 PreModelSwitch
3357</h3>3367</h3>
3358 3368
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.3369Viene 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 3370
3361PreModelSwitch richiede Claude Code v2.1.251 o successivo. Claude Code lo esegue per queste richieste:3371PreModelSwitch richiede Claude Code v2.1.251 o successivo. Claude Code lo esegue per queste richieste:
3362 3372
3363* `/model <name>` e il picker `/model`3373* `/model <name>` e il selettore di `/model`
3364* Il picker del modello `Option+P` o `Alt+P`3374* Il selettore di modello `Option+P` o `Alt+P`
3365* L'impostazione Model in `/config`3375* L'impostazione Model in `/config`
3366* Attivare la [modalità veloce](/docs/it/fast-mode) quando questo cambia il modello della sessione3376* 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)3377* 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 3378
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.3379Claude 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 3380
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.3381Claude 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 3382
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.3383Quando 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 3384
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:3385Scrivi 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 3386
3377<Tabs>3387<Tabs>
3378 <Tab title="macOS/Linux">3388 <Tab title="macOS/Linux">
3438 </Tab>3448 </Tab>
3439</Tabs>3449</Tabs>
3440 3450
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.3451Per 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 3452
3443<h4 id="premodelswitch-input">3453<h4 id="premodelswitch-input">
3444 Input PreModelSwitch3454 Input di PreModelSwitch
3445</h4>3455</h4>
3446 3456
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.3457Oltre 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 3458
3449| Campo | Tipo | Descrizione |3459| Campo | Tipo | Descrizione |
3450| :- | :- | :- |3460| :- | :- | :- |
3451| `from_model` | string | ID del modello da cui il cambio cambia |3461| `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 |3462| `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 |3463| `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 |3464| `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 |3465| `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 |3466| `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"` |3467| `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 |3468| `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 |3469| `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 3470
3461Questo esempio mostra l'input per `/model opus` in una sessione che esegue Sonnet 5:3471Questo esempio mostra l'input per `/model opus` in una sessione che usa Sonnet 5:
3462 3472
3463```json theme={null}3473```json theme={null}
3464{3474{
3479```3489```
3480 3490
3481<h4 id="premodelswitch-decision-control">3491<h4 id="premodelswitch-decision-control">
3482 Controllo decisionale PreModelSwitch3492 Controllo decisionale di PreModelSwitch
3483</h4>3493</h4>
3484 3494
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.3495Gli 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 3496
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:3497Per 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 3498
3489| Campo | Descrizione |3499| Campo | Descrizione |
3490| :- | :- |3500| :- | :- |
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 |3501| `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"` |3502| `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 3503
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.3504Solo `/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 3505
3496Questo esempio chiede all'utente di confermare e cita il conteggio dei token da `context_tokens`:3506Questo esempio chiede all'utente di confermare e cita il numero di token da `context_tokens`:
3497 3507
3498```json theme={null}3508```json theme={null}
3499{3509{
3505}3515}
3506```3516```
3507 3517
3508Quando più hook PreModelSwitch restituiscono decisioni diverse, la precedenza è `deny` > `ask` > `allow`.3518Quando più hook PreModelSwitch restituiscono decisioni diverse, l'ordine di precedenza è `deny` > `ask` > `allow`.
3509 3519
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.3520Claude 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 3521
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.3522Un 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 3523
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).3524Un 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 3525
3516<h3 id="postmodelswitch">3526<h3 id="postmodelswitch">
3517 PostModelSwitch3527 PostModelSwitch
3518</h3>3528</h3>
3519 3529
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.3530Viene 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 3531
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:3532PostModelSwitch 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 3533
3524* Un cambio che hai richiesto tu o un client3534* 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 sessione3535* 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à piano3536* 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 sessione3537* Claude Code che ripristina il modello quando riprendi una sessione
3528 3538
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.3539Claude 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 3540
3531Il matcher segue le stesse regole di [PreModelSwitch](#premodelswitch): Claude Code lo confronta rispetto al nome canonico del modello a cui la sessione è passata.3541Il matcher segue le stesse regole di [PreModelSwitch](#premodelswitch): Claude Code lo confronta con il nome canonico del modello verso cui la sessione è passata.
3532 3542
3533Questo esempio aggiunge una guida ogni volta che il modello della sessione cambia a qualsiasi modello Opus:3543Questo esempio aggiunge indicazioni ogni volta che il modello della sessione passa a un qualsiasi modello Opus:
3534 3544
3535```json theme={null}3545```json theme={null}
3536{3546{
3550}3560}
3551```3561```
3552 3562
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.3563Per 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 3564
3555<h4 id="postmodelswitch-input">3565<h4 id="postmodelswitch-input">
3556 Input PostModelSwitch3566 Input di PostModelSwitch
3557</h4>3567</h4>
3558 3568
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.3569Gli 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 3570
3561`requested_model` è `null` quando `source` è `"auto"`. Quando `source` è `"resume"`, è l'impostazione del modello salvato che Claude Code ha ripristinato.3571`requested_model` è `null` quando `source` è `"auto"`. Quando `source` è `"resume"`, è l'impostazione del modello salvata che Claude Code ha ripristinato.
3562 3572
3563<h4 id="postmodelswitch-decision-control">3573<h4 id="postmodelswitch-decision-control">
3564 Controllo decisionale PostModelSwitch3574 Controllo decisionale di PostModelSwitch
3565</h4>3575</h4>
3566 3576
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:3577Claude 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 3578
3569| Campo | Descrizione |3579| Campo | Descrizione |
3570| :- | :- |3580| :- | :- |
3571| `additionalContext` | Stringa aggiunta al contesto di Claude con la richiesta successiva. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |3581| `additionalContext` | Stringa aggiunta al contesto di Claude con la richiesta successiva. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |
3572 3582
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.3583Se 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 3584
3575<h3 id="sessionend">3585<h3 id="sessionend">
3576 SessionEnd3586 SessionEnd
3577</h3>3587</h3>
3578 3588
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.3589Viene eseguito quando una sessione di Claude Code termina. Utile per attività di pulizia, registrazione delle
3590statistiche della sessione o salvataggio dello stato della sessione. Supporta i matcher per filtrare in base al motivo di uscita.
3580 3591
3581Il campo `reason` nell'input dell'hook indica perché la sessione è terminata:3592Il campo `reason` nell'input dell'hook indica perché la sessione è terminata:
3582 3593
3584| :- | :- |3595| :- | :- |
3585| `clear` | Sessione cancellata con il comando `/clear` |3596| `clear` | Sessione cancellata con il comando `/clear` |
3586| `resume` | Sessione cambiata tramite `/resume` interattivo |3597| `resume` | Sessione cambiata tramite `/resume` interattivo |
3587| `logout` | L'utente ha effettuato il logout |3598| `logout` | L'utente è uscito dall'account |
3588| `prompt_input_exit` | L'utente è uscito mentre l'input del prompt era visibile |3599| `prompt_input_exit` | L'utente è uscito mentre l'input del prompt era visibile |
3589| `other` | Altri motivi di uscita |3600| `other` | Altri motivi di uscita |
3590| `bypass_permissions_disabled` | Rimosso nella v2.1.234; Claude Code non lo invia. Eliminalo dai tuoi matcher `SessionEnd` |3601| `bypass_permissions_disabled` | Rimosso nella v2.1.234; Claude Code non lo invia. Rimuovilo dai tuoi matcher `SessionEnd` |
3591 3602
3592<h4 id="sessionend-input">3603<h4 id="sessionend-input">
3593 Input SessionEnd3604 Input di SessionEnd
3594</h4>3605</h4>
3595 3606
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.3607Oltre 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 3608
3598```json theme={null}3609```json theme={null}
3599{3610{
3605}3616}
3606```3617```
3607 3618
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`.3619Gli 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 3620
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:3621Gli 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 3622
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.3623* **`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`.3624* **`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 3625
3615Questo esempio imposta il budget a 5 secondi:3626Questo esempio imposta il budget a 5 secondi:
3616 3627
3618CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude3629CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude
3619```3630```
3620 3631
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.3632Prima 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 3633
3623<h3 id="elicitation">3634<h3 id="elicitation">
3624 Elicitation3635 Elicitation
3625</h3>3636</h3>
3626 3637
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.3638Viene 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 3639
3629Il campo matcher corrisponde al nome del server MCP.3640Il campo matcher viene confrontato con il nome del server MCP.
3630 3641
3631<h4 id="elicitation-input">3642<h4 id="elicitation-input">
3632 Input Elicitation3643 Input di Elicitation
3633</h4>3644</h4>
3634 3645
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`.3646Oltre 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 3647
3637Per l'elicitazione in modalità modulo, il caso più comune:3648Per l'elicitation in modalità form, il caso più comune:
3638 3649
3639```json theme={null}3650```json theme={null}
3640{3651{
3654}3665}
3655```3666```
3656 3667
3657Per l'elicitazione in modalità URL, usata per l'autenticazione basata su browser:3668Per l'elicitation in modalità URL, usata per l'autenticazione basata su browser:
3658 3669
3659```json theme={null}3670```json theme={null}
3660{3671{
3670```3681```
3671 3682
3672<h4 id="elicitation-output">3683<h4 id="elicitation-output">
3673 Output Elicitation3684 Output di Elicitation
3674</h4>3685</h4>
3675 3686
3676Per rispondere programmaticamente senza mostrare il dialogo, restituisci un oggetto JSON con `hookSpecificOutput`:3687Per rispondere in modo programmatico senza mostrare la finestra di dialogo, restituisci un oggetto JSON con `hookSpecificOutput`:
3677 3688
3678```json theme={null}3689```json theme={null}
3679{3690{
3689 3700
3690| Campo | Valori | Descrizione |3701| Campo | Valori | Descrizione |
3691| :- | :- | :- |3702| :- | :- | :- |
3692| `action` | `accept`, `decline`, `cancel` | Se accettare, rifiutare, o annullare la richiesta |3703| `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` |3704| `content` | object | Valori dei campi del form da inviare. Usato solo quando `action` è `accept` |
3694 3705
3695L'uscita con codice 2 nega l'elicitazione. Claude Code non mostra il tuo messaggio stderr da nessuna parte.3706Il codice di uscita 2 nega l'elicitation. Claude Code non mostra il tuo messaggio stderr da nessuna parte.
3696 3707
3697Claude Code agisce su `hookSpecificOutput` dall'output JSON di un hook Elicitation e scarta `systemMessage` e `continue`.3708Claude Code agisce su `hookSpecificOutput` dall'output JSON di un hook Elicitation e scarta `systemMessage` e `continue`.
3698 3709
3700 ElicitationResult3711 ElicitationResult
3701</h3>3712</h3>
3702 3713
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.3714Viene 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 3715
3705Il campo matcher corrisponde al nome del server MCP.3716Il campo matcher viene confrontato con il nome del server MCP.
3706 3717
3707<h4 id="elicitationresult-input">3718<h4 id="elicitationresult-input">
3708 Input ElicitationResult3719 Input di ElicitationResult
3709</h4>3720</h4>
3710 3721
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`.3722Oltre 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 3723
3713```json theme={null}3724```json theme={null}
3714{3725{
3725```3736```
3726 3737
3727<h4 id="elicitationresult-output">3738<h4 id="elicitationresult-output">
3728 Output ElicitationResult3739 Output di ElicitationResult
3729</h4>3740</h4>
3730 3741
3731Per sovrascrivere la risposta dell'utente, restituisci un oggetto JSON con `hookSpecificOutput`:3742Per sovrascrivere la risposta dell'utente, restituisci un oggetto JSON con `hookSpecificOutput`:
3743| Campo | Valori | Descrizione |3754| Campo | Valori | Descrizione |
3744| :- | :- | :- |3755| :- | :- | :- |
3745| `action` | `accept`, `decline`, `cancel` | Sovrascrive l'azione dell'utente |3756| `action` | `accept`, `decline`, `cancel` | Sovrascrive l'azione dell'utente |
3746| `content` | object | Sovrascrive i valori dei campi del modulo. Significativo solo quando `action` è `accept` |3757| `content` | object | Sovrascrive i valori dei campi del form. Significativo solo quando `action` è `accept` |
3747 3758
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.3759Il 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 3760
3750Claude Code agisce su `hookSpecificOutput` dall'output JSON di un hook ElicitationResult e scarta `systemMessage` e `continue`.3761Claude Code agisce su `hookSpecificOutput` dall'output JSON di un hook ElicitationResult e scarta `systemMessage` e `continue`.
3751 3762
