274 274
275Gli hook dai file di impostazioni, dalle impostazioni di policy gestite e dai plugin vengono eseguiti anche all'interno di [subagenti](/docs/it/sub-agents). Quando un subagent chiama uno strumento, gli eventi dello strumento come `PreToolUse` e `PostToolUse` attivano gli stessi hook configurati della conversazione principale, e l'input contiene i campi di input comuni `agent_id` e `agent_type` [](#common-input-fields) che identificano il subagent.275Gli hook dai file di impostazioni, dalle impostazioni di policy gestite e dai plugin vengono eseguiti anche all'interno di [subagenti](/docs/it/sub-agents). Quando un subagent chiama uno strumento, gli eventi dello strumento come `PreToolUse` e `PostToolUse` attivano gli stessi hook configurati della conversazione principale, e l'input contiene i campi di input comuni `agent_id` e `agent_type` [](#common-input-fields) che identificano il subagent.
276 276
277Gli amministratori aziendali possono utilizzare `allowManagedHooksOnly` per limitare quali hook vengono eseguiti:277Gli amministratori possono utilizzare [`allowManagedHooksOnly`](/docs/it/settings-reference#allowmanagedhooksonly) nelle [impostazioni gestite](/docs/it/managed-settings) per limitare quali hook vengono eseguiti:
278 278
279* I tuoi hook utente, progetto, locale e plugin sono bloccati. Gli hook dai plugin forzatamente abilitati nelle impostazioni gestite `enabledPlugins` sono esenti279* I tuoi hook utente, progetto, locale e plugin sono bloccati. Gli hook dai plugin forzatamente abilitati nelle impostazioni gestite `enabledPlugins` sono esenti
280* Claude Code restringe anche le tue impostazioni [`statusLine`](/docs/it/statusline), [`fileSuggestion`](/docs/it/settings-reference#filesuggestion), e [`subagentStatusLine`](/docs/it/statusline#subagent-status-lines) alle impostazioni gestite280* Claude Code restringe anche le tue impostazioni [`statusLine`](/docs/it/statusline), [`fileSuggestion`](/docs/it/settings-reference#filesuggestion), e [`subagentStatusLine`](/docs/it/statusline#subagent-status-lines) alle impostazioni gestite
304 304
305Un matcher sul percorso dell'espressione regolare viene testato con `RegExp.prototype.test` di JavaScript, che ha successo su una corrispondenza in qualsiasi punto del valore. `Edit.*` corrisponde sia a `Edit` che a `NotebookEdit`; racchiudi il pattern in `^` e `$`, come in `^Edit$`, quando hai bisogno di una corrispondenza di intera stringa.305Un matcher sul percorso dell'espressione regolare viene testato con `RegExp.prototype.test` di JavaScript, che ha successo su una corrispondenza in qualsiasi punto del valore. `Edit.*` corrisponde sia a `Edit` che a `NotebookEdit`; racchiudi il pattern in `^` e `$`, come in `^Edit$`, quando hai bisogno di una corrispondenza di intera stringa.
306 306
307I trattini nel set di corrispondenza esatta richiedono Claude Code v2.1.195 o successivo. Nelle versioni precedenti un nome con trattino come `code-reviewer` viene valutato come un'espressione regolare non ancorata, quindi si attiva anche per `senior-code-reviewer`; ancoratelo come `^code-reviewer$` in quelle versioni per corrispondere solo a quel nome.
308
309`FileChanged` e `StopFailure` utilizzano un set di corrispondenza esatta più ristretto di sole lettere, cifre, `_`, e `|`. Un trattino, spazio, o virgola in un matcher per questi due eventi lo mantiene sul percorso dell'espressione regolare, e solo `|` separa le alternative. Ogni altro evento con supporto matcher nella tabella che segue accetta `|` o `,`.307`FileChanged` e `StopFailure` utilizzano un set di corrispondenza esatta più ristretto di sole lettere, cifre, `_`, e `|`. Un trattino, spazio, o virgola in un matcher per questi due eventi lo mantiene sul percorso dell'espressione regolare, e solo `|` separa le alternative. Ogni altro evento con supporto matcher nella tabella che segue accetta `|` o `,`.
310 308
311L'evento `FileChanged` non segue queste regole quando costruisce la sua lista di osservazione. Vedi [FileChanged](#filechanged).309L'evento `FileChanged` non segue queste regole quando costruisce la sua lista di osservazione. Vedi [FileChanged](#filechanged).
380* `mcp__brave-search__.*` corrisponde a tutti i tool da un server il cui nome contiene un trattino378* `mcp__brave-search__.*` corrisponde a tutti i tool da un server il cui nome contiene un trattino
381* `mcp__.*__write.*` corrisponde a qualsiasi tool il cui nome inizia con `write` da qualsiasi server379* `mcp__.*__write.*` corrisponde a qualsiasi tool il cui nome inizia con `write` da qualsiasi server
382 380
383I trattini nel set di corrispondenza esatta richiedono Claude Code v2.1.195 o successivo. Nelle versioni precedenti un prefisso nudo con trattino come `mcp__brave-search` viene valutato come un'espressione regolare non ancorata e corrisponde a ogni tool da quel server. La forma `mcp__brave-search__.*` funziona su ogni versione.
384
385I tool da un [server MCP fornito da plugin](/docs/it/mcp#plugin-provided-mcp-servers) utilizzano un segmento di server con scope che include il nome del plugin: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. Un matcher scritto rispetto alla chiave del server nudo non si attiva mai per questi tool. Per un plugin denominato `my-plugin` che raggruppa un server sotto la chiave `db`, un tool `query` appare come `mcp__plugin_my-plugin_db__query`, quindi il matcher per ogni tool da quel server è `mcp__plugin_my-plugin_db__.*`. Utilizza lo stesso nome di tool con scope nel campo [`if`](#common-fields) di un handler. Vedi [Plugin-provided MCP servers](/docs/it/mcp#plugin-provided-mcp-servers) per come viene costruito il nome con scope.381I tool da un [server MCP fornito da plugin](/docs/it/mcp#plugin-provided-mcp-servers) utilizzano un segmento di server con scope che include il nome del plugin: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. Un matcher scritto rispetto alla chiave del server nudo non si attiva mai per questi tool. Per un plugin denominato `my-plugin` che raggruppa un server sotto la chiave `db`, un tool `query` appare come `mcp__plugin_my-plugin_db__query`, quindi il matcher per ogni tool da quel server è `mcp__plugin_my-plugin_db__.*`. Utilizza lo stesso nome di tool con scope nel campo [`if`](#common-fields) di un handler. Vedi [Plugin-provided MCP servers](/docs/it/mcp#plugin-provided-mcp-servers) per come viene costruito il nome con scope.
386 382
387Questo esempio registra tutte le operazioni del server memory e convalida le operazioni di scrittura da qualsiasi server MCP:383Questo esempio registra tutte le operazioni del server memory e convalida le operazioni di scrittura da qualsiasi server MCP:
919| :- | :- | :- |915| :- | :- | :- |
920| `PreToolUse` | Sì | Blocca la chiamata dello strumento |916| `PreToolUse` | Sì | Blocca la chiamata dello strumento |
921| `PermissionRequest` | No | Il codice di uscita 2 non è onorato per questo evento e il flusso di autorizzazione procede invariato. Nega attraverso l'oggetto [`decision`](#permissionrequest-decision-control) invece |917| `PermissionRequest` | No | Il codice di uscita 2 non è onorato per questo evento e il flusso di autorizzazione procede invariato. Nega attraverso l'oggetto [`decision`](#permissionrequest-decision-control) invece |
922| `UserPromptSubmit` | Sì | Blocca l'elaborazione del prompt e cancella il prompt |918| `UserPromptSubmit` | Sì | Blocca il prompt, quindi non raggiunge mai Claude. Consultare [What a blocked prompt leaves behind](#what-a-blocked-prompt-leaves-behind) |
923| `UserPromptExpansion` | Sì | Blocca l'espansione |919| `UserPromptExpansion` | Sì | Blocca l'espansione |
924| `Stop` | Sì | Impedisce a Claude di fermarsi, continua la conversazione |920| `Stop` | Sì | Impedisce a Claude di fermarsi, continua la conversazione |
925| `SubagentStop` | Sì | Impedisce al subagent di fermarsi |921| `SubagentStop` | Sì | Impedisce al subagent di fermarsi |
1177 1173
1178Si 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.1174Si 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.
1179 1175
1180SessionStart si esegue su ogni sessione, quindi mantieni questi hook veloci. Solo gli hook `type: "command"` e `type: "mcp_tool"` sono supportati. Vedi [Campi hook MCP tool](#mcp-tool-hook-fields) per quando gli hook `mcp_tool` si eseguono.1176SessionStart 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.
1181 1177
1182Il valore del matcher corrisponde a come la sessione è stata avviata:1178Il valore del matcher corrisponde a come la sessione è stata avviata:
1183 1179
1187| `resume` | `--resume`, `--continue`, o `/resume` |1183| `resume` | `--resume`, `--continue`, o `/resume` |
1188| `clear` | `/clear` |1184| `clear` | `/clear` |
1189| `compact` | Compattazione automatica o manuale |1185| `compact` | Compattazione automatica o manuale |
1190| `fork` | Una nuova sessione creata da una sessione esistente: `--fork-session` con `--resume` o `--continue`, la copia di background `/fork`, o `/branch` |1186| `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) |
1191 1187
1192Prima della v2.1.214, le sessioni create da fork segnalano la sorgente `"resume"`.1188Prima della v2.1.214, le sessioni create da fork segnalano la sorgente `"resume"`.
1193 1189
1194Quando 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.1190Quando 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.
1195 1191
1196Quando cambi conversazione 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.1192Quando 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.
1197 1193
1198Lo 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 fino a quando non finiscono.1194Lo 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.
1199 1195
1200Durante uno qualsiasi di questi attese, premi `Esc` per riprendere il prompt nell'input senza inviarlo. Gli hook continuano a eseguirsi.1196Durante uno qualsiasi di questi attese, premi `Esc` per riprendere il prompt nell'input senza inviarlo. Gli hook continuano a essere eseguiti.
1201 1197
1202<h4 id="sessionstart-input">1198<h4 id="sessionstart-input">
1203 Input SessionStart1199 Input SessionStart
1204</h4>1200</h4>
1205 1201
1206Oltre ai [campi di input comuni](#common-input-fields), gli hook SessionStart ricevono `source` e opzionalmente `model`, `agent_type`, e `session_title`:1202Oltre ai [campi di input comuni](#common-input-fields), gli hook SessionStart ricevono `source` e facoltativamente `model`, `agent_type`, e `session_title`:
1207 1203
1208| Campo | Descrizione |1204| Campo | Descrizione |
1209| :- | :- |1205| :- | :- |
1212| `agent_type` | Il nome dell'agente, presente quando avvii Claude Code con `claude --agent <name>` |1208| `agent_type` | Il nome dell'agente, presente quando avvii Claude Code con `claude --agent <name>` |
1213| `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 |1209| `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 |
1214 1210
1215Quando `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 riprendere una conversazione stantia prima della prima richiesta, ad esempio in un [`systemMessage`](#json-output). Questi campi richiedono Claude Code v2.1.251 o successivo.1211Quando `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.
1216 1212
1217| Campo | Descrizione |1213| Campo | Descrizione |
1218| :- | :- |1214| :- | :- |
1219| `seconds_since_last_response` | Secondi di tempo reale trascorsi dall'ultima risposta nella trascrizione ripresa |1215| `seconds_since_last_response` | Secondi di tempo reale dalla risposta più recente nella trascrizione ripresa |
1220| `context_tokens` | Token che la prima richiesta della sessione ripresa reinvia come suo prompt |1216| `context_tokens` | Token che la prima richiesta della sessione ripresa invia di nuovo come suo prompt |
1221| `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 in cache |1217| `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 |
1222| `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 |1218| `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 |
1223 1219
1224Questo esempio mostra l'input per una sessione ripresa 90 minuti dopo la sua ultima risposta:1220Questo esempio mostra l'input per una sessione ripresa 90 minuti dopo la sua ultima risposta:
1247| Campo | Descrizione |1243| Campo | Descrizione |
1248| :- | :- |1244| :- | :- |
1249| `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 |1245| `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 |
1250| `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, segue come turno successivo. A differenza di `additionalContext`, che si allega a un turno esistente, questo crea il turno |1246| `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 |
1251| `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"` |1247| `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"` |
1252| `watchPaths` | Array di percorsi assoluti da osservare per gli eventi [FileChanged](#filechanged) durante questa sessione |1248| `watchPaths` | Array di percorsi assoluti da osservare per gli eventi [FileChanged](#filechanged) durante questa sessione |
1253| `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 |1249| `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 |
1262}1258}
1263```1259```
1264 1260
1265Poiché lo stdout semplice raggiunge già Claude per questo evento, un hook che carica solo 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`.1261Poiché 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`.
1266 1262
1267Usa `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:1263Usa `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:
1268 1264
1281 Persistere variabili di ambiente1277 Persistere variabili di ambiente
1282</h4>1278</h4>
1283 1279
1284Gli hook SessionStart hanno accesso alla variabile di ambiente `CLAUDE_ENV_FILE`, che fornisce un percorso di file dove puoi persistere variabili di ambiente per i comandi Bash successivi.1280Gli 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.
1285 1281
1286Per impostare singole variabili di ambiente, scrivi istruzioni `export` su `CLAUDE_ENV_FILE`. Usa append (`>>`) per preservare le variabili impostate da altri hook:1282Per impostare singole variabili di ambiente, scrivi istruzioni `export` in `CLAUDE_ENV_FILE`. Usa append (`>>`) per preservare le variabili impostate da altri hook:
1287 1283
1288```bash theme={null}1284```bash theme={null}
1289#!/bin/bash1285#!/bin/bash
1324 Setup1320 Setup
1325</h3>1321</h3>
1326 1322
1327Si attiva 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 attiva 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.1323Si 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.
1328 1324
1329Il valore del matcher corrisponde al flag CLI che ha attivato l'hook:1325Il valore del matcher corrisponde al flag CLI che ha attivato l'hook:
1330 1326
1339 1335
1340Al 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.1336Al 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.
1341 1337
1342Poiché Setup non si attiva 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.1338Poiché 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.
1343 1339
1344<h4 id="setup-input">1340<h4 id="setup-input">
1345 Input Setup1341 Input Setup
1361 Controllo decisionale Setup1357 Controllo decisionale Setup
1362</h4>1358</h4>
1363 1359
1364Gli 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 [eventi `hook_response`](/docs/it/headless#read-session-metadata) quando avvii con `--output-format stream-json --verbose`.1360Gli 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`.
1365 1361
1366Gli hook Setup hanno accesso a `CLAUDE_ENV_FILE`. Le variabili scritte su 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 [Campi hook MCP tool](#mcp-tool-hook-fields).1362Gli 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).
1367 1363
1368<h3 id="instructionsloaded">1364<h3 id="instructionsloaded">
1369 InstructionsLoaded1365 InstructionsLoaded
1370</h3>1366</h3>
1371 1367
1372Si 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 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à.1368Si 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à.
1373 1369
1374Questo evento non si attiva quando Claude [legge `AGENTS.md` direttamente](/docs/it/memory#agents-md) tramite l'impostazione **Project instructions**. Si attiva 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.1370Questo 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.
1375 1371
1376Il matcher viene eseguito su `load_reason`. Ad esempio, usa `"matcher": "session_start"` per attivarsi solo per i file caricati all'avvio della sessione, o `"matcher": "path_glob_match|nested_traversal"` per attivarsi solo per i caricamenti pigri.1372Il 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.
1377 1373
1378<h4 id="instructionsloaded-input">1374<h4 id="instructionsloaded-input">
1379 Input InstructionsLoaded1375 Input InstructionsLoaded
1385| :- | :- |1381| :- | :- |
1386| `file_path` | Percorso assoluto al file di istruzioni che è stato caricato |1382| `file_path` | Percorso assoluto al file di istruzioni che è stato caricato |
1387| `memory_type` | Ambito del file: `"User"`, `"Project"`, `"Local"`, o `"Managed"` |1383| `memory_type` | Ambito del file: `"User"`, `"Project"`, `"Local"`, o `"Managed"` |
1388| `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 |1384| `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 |
1389| `globs` | Modelli di glob di percorso dal frontmatter `paths:` del file, se presenti. Presente solo per i caricamenti `path_glob_match` |1385| `globs` | Modelli di glob di percorso dal frontmatter `paths:` del file, se presenti. Presente solo per i caricamenti `path_glob_match` |
1390| `trigger_file_path` | Percorso al file il cui accesso ha attivato questo caricamento, per i caricamenti pigri |1386| `trigger_file_path` | Percorso al file il cui accesso ha attivato questo caricamento, per i caricamenti pigri |
1391| `parent_file_path` | Percorso al file di istruzioni genitore che ha incluso questo, per i caricamenti `include` |1387| `parent_file_path` | Percorso al file di istruzioni genitore che ha incluso questo, per i caricamenti `include` |
1414 1410
1415Si 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.1411Si 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.
1416 1412
1417Gli 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 fino al completamento, un hook bloccato blocca la sessione. Se il tuo hook ha bisogno di più tempo, imposta il campo `timeout` nella voce dell'hook.1413Gli 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.
1418 1414
1419A 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.1415A 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.
1420 1416
1421Un [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.1417Un [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.
1422 1418
1448* **Stdout di testo semplice**: Claude Code aggiunge stdout che [tratta come testo semplice](#exit-code-0) al contesto di Claude1444* **Stdout di testo semplice**: Claude Code aggiunge stdout che [tratta come testo semplice](#exit-code-0) al contesto di Claude
1449* **JSON con `additionalContext`**: usa il formato JSON sottostante per più controllo. Il campo `additionalContext` viene aggiunto come contesto1445* **JSON con `additionalContext`**: usa il formato JSON sottostante per più controllo. Il campo `additionalContext` viene aggiunto come contesto
1450 1446
1451Nessuno 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 [log di debug](#debug-hooks).1447Nessuno 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).
1452 1448
1453Per bloccare un prompt, restituisci un oggetto JSON con `decision` impostato su `"block"`:1449Per bloccare un prompt, restituisci un oggetto JSON con `decision` impostato su `"block"`:
1454 1450
1455| Campo | Descrizione |1451| Campo | Descrizione |
1456| :- | :- |1452| :- | :- |
1457| `decision` | `"block"` impedisce l'elaborazione del prompt e lo cancella dal contesto. Ometti per consentire al prompt di procedere |1453| `decision` | `"block"` ferma il prompt prima che raggiunga Claude. Ometti per consentire al prompt di procedere |
1458| `reason` | Mostrato all'utente quando `decision` è `"block"`. Non aggiunto al contesto |1454| `reason` | Mostrato all'utente quando `decision` è `"block"`. Non aggiunto al contesto |
1459| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt inviato. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |1455| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt inviato. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |
1460| `sessionTitle` | Imposta il titolo della sessione. Usa per nominare le sessioni automaticamente in base al contenuto del prompt |1456| `sessionTitle` | Imposta il titolo della sessione. Usa per nominare le sessioni automaticamente in base al contenuto del prompt |
1461| `suppressOriginalPrompt` | Se `true` quando `decision` è `"block"`, omette il testo del prompt originale dal messaggio di blocco mostrato all'utente |1457| `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) |
1462 1458
1463Un hook che blocca uscendo con 2 si instrada allo stesso modo di `reason`: il messaggio di blocco mostra il testo stderr all'utente, e non viene aggiunto al contesto.1459Un hook che blocca 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.
1464 1460
1469 "hookSpecificOutput": {1465 "hookSpecificOutput": {
1470 "hookEventName": "UserPromptSubmit",1466 "hookEventName": "UserPromptSubmit",
1471 "additionalContext": "My additional context here",1467 "additionalContext": "My additional context here",
1472 "sessionTitle": "My session title"1468 "sessionTitle": "My session title",
1469 "suppressOriginalPrompt": true
1473 }1470 }
1474}1471}
1475```1472```
1476 1473
1474<h4 id="what-a-blocked-prompt-leaves-behind">
1475 Cosa lascia dietro un prompt bloccato
1476</h4>
1477
1478Un prompt bloccato non raggiunge mai Claude, ma il suo testo non viene rimosso ovunque. Per impostazione predefinita il messaggio di blocco mostrato all'utente termina con `Original prompt:` seguito dal testo inviato, e Claude Code scrive quel messaggio nel file di trascrizione della sessione su disco. Per 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.
1479
1480`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).
1481
1477<h3 id="userpromptexpansion">1482<h3 id="userpromptexpansion">
1478 UserPromptExpansion1483 UserPromptExpansion
1479</h3>1484</h3>
1480 1485
1481Si esegue quando un comando digitato dall'utente si espande in un prompt prima di raggiungere Claude. Usalo 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 checklist di revisione del team come `additionalContext`.1486Si 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`.
1482 1487
1483Questo 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 `/skillname` direttamente bypassa `PreToolUse`. `UserPromptExpansion` si attiva su quel percorso diretto.1488Questo 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.
1484 1489
1485Corrisponde a `command_name`. Lascia il matcher vuoto per attivarsi su ogni comando di tipo prompt.1490Corrisponde su `command_name`. Lascia il matcher vuoto per eseguire su ogni comando di tipo prompt.
1486 1491
1487<h4 id="userpromptexpansion-input">1492<h4 id="userpromptexpansion-input">
1488 Input UserPromptExpansion1493 Input UserPromptExpansion
1513 1518
1514| Campo | Descrizione |1519| Campo | Descrizione |
1515| :- | :- |1520| :- | :- |
1516| `decision` | `"block"` impedisce l'espansione del comando. Ometti per consentire al comando di procedere |1521| `decision` | `"block"` impedisce al comando di espandersi. Ometti per consentirgli di procedere |
1517| `reason` | Mostrato all'utente quando `decision` è `"block"` |1522| `reason` | Mostrato all'utente quando `decision` è `"block"` |
1518| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt espanso. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |1523| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt espanso. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |
1519 1524
1534 MessageDisplay1539 MessageDisplay
1535</h3>1540</h3>
1536 1541
1537Si 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 potrebbe produrne solo una.1542Si 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.
1538 1543
1539Usa MessageDisplay per:1544Usa MessageDisplay per:
1540 1545
1541* rimuovere il markdown per una visualizzazione minima1546* rimuovere markdown per una visualizzazione minima
1542* trasformare il testo che un'applicazione Agent SDK mostra ai suoi utenti1547* trasformare il testo che un'applicazione Agent SDK mostra ai suoi utenti
1543* redarre chiavi API o nomi host interni dalle risposte di Claude1548* redarre chiavi API o nomi host interni dalle risposte di Claude
1544 1549
1545Claude Code tiene ogni batch fino a quando il tuo hook non ritorna, quindi mantieni l'hook veloce. Se l'hook fallisce o scade, Claude Code visualizza il testo originale. Il timeout predefinito per questo evento è 10 secondi; se il tuo hook ha bisogno di più tempo, imposta il campo `timeout` nella voce dell'hook.1550Claude Code 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.
1546 1551
1547MessageDisplay è solo per la visualizzazione: il testo di sostituzione cambia solo ciò che viene renderizzato sullo schermo. La trascrizione e ciò che Claude vede mantengono il testo originale, quindi Claude non vede mai la sostituzione, e la modalità verbose mostra l'originale. L'hook riceve solo il testo del messaggio dell'assistente, quindi i risultati degli strumenti e il testo che digiti vengono renderizzati invariati.1552MessageDisplay è 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.
1548 1553
1549MessageDisplay non supporta i matcher e si attiva per ogni messaggio dell'assistente che scorre il testo; i messaggi senza testo, come le risposte solo di chiamate di strumenti, non lo attivano.1554MessageDisplay non supporta i matcher e si 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.
1550 1555
1551Nelle 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 il completamento del messaggio e porta il testo completo del messaggio: `index` è `0`, `final` è `true`, e `delta` contiene l'intero messaggio. Un hook che raccoglie il testo `delta` per ogni messaggio riceve lo stesso testo totale in entrambe le modalità.1556Nelle esecuzioni non interattive, incluse le query 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à.
1552 1557
1553<h4 id="messagedisplay-input">1558<h4 id="messagedisplay-input">
1554 Input MessageDisplay1559 Input MessageDisplay
1559| Campo | Descrizione |1564| Campo | Descrizione |
1560| :- | :- |1565| :- | :- |
1561| `turn_id` | UUID del turno corrente |1566| `turn_id` | UUID del turno corrente |
1562| `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 della trascrizione |1567| `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 |
1563| `index` | Indice a base zero di questo batch all'interno del messaggio |1568| `index` | Indice a base zero di questo batch all'interno del messaggio |
1564| `final` | `true` sul batch finale del messaggio. Ogni messaggio ha esattamente un batch finale |1569| `final` | `true` sul batch finale del messaggio. Ogni messaggio ha esattamente un batch finale |
1565| `delta` | Le righe appena completate dall'ultimo batch, incluse le newline finali. Sempre righe intere, tranne il batch finale che potrebbe terminare a metà riga. Nelle esecuzioni interattive, il delta del batch finale è vuoto quando il messaggio termina su una newline, quindi tratta `final`, non un delta non vuoto, come il segnale di fine messaggio. Nelle esecuzioni Agent SDK e `claude -p`, la singola chiamata porta l'intero messaggio |1570| `delta` | Le righe appena completate 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 |
1566 1571
1567```json theme={null}1572```json theme={null}
1568{1573{
1672 PreToolUse1677 PreToolUse
1673</h3>1678</h3>
1674 1679
1675Si esegue dopo che Claude crea i parametri dello strumento e prima dell'elaborazione della 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).1680Si 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).
1676 1681
1677Per eseguire un hook quando un file specifico cambia su disco, indipendentemente da chi lo ha scritto, usa [FileChanged](#filechanged) invece di corrispondere ai nomi degli strumenti di modifica dei file. A differenza di PreToolUse, Claude Code esegue gli hook FileChanged dopo il cambiamento, e non hanno controllo decisionale, quindi non possono bloccare la scrittura.1682Per 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.
1678 1683
1679<Warning>1684<Warning>
1680 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 attiva per loro, inclusi gli hook che corrispondono a `Read`. Per bloccare percorsi specifici dai riferimenti `@`, usa una [regola di negazione `Read`](/docs/it/permissions#read-and-edit) invece.1685 PreToolUse 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.
1681 1686
1682 PreToolUse inoltre non si attiva per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).1687 PreToolUse inoltre non si esegue per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).
1683</Warning>1688</Warning>
1684 1689
1685Usa il [controllo decisionale PreToolUse](#pretooluse-decision-control) per consentire, negare, chiedere, o differire la chiamata dello strumento.1690Usa [Controllo decisionale PreToolUse](#pretooluse-decision-control) per consentire, negare, chiedere, o differire la chiamata dello strumento.
1686 1691
1687Un [hook di callback Agent SDK](/docs/it/agent-sdk/hooks) su `PreToolUse` che supera il suo timeout blocca la chiamata dello strumento, e Claude riceve un risultato di errore che nomina il timeout. Un'esplicita negazione restituita da un altro hook ha ancora la precedenza.1692Un [hook di callback 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.
1688 1693
1734 1739
1735Quando un comando Bash cambia i file in un repository Git, Claude Code può registrare cosa è cambiato. Registra i cambiamenti in ogni modalità di permesso quando l'impostazione [`bashEditDiffEnabled`](/docs/it/settings-reference#basheditdiffenabled) attiva la registrazione; la voce di quell'impostazione dice quali file possono impostarla. Altrimenti la registra solo in modalità auto e modalità `bypassPermissions`, e solo quando Claude Code dirige Claude a modificare i file tramite Bash. Imposta `bashEditDiffEnabled` su `false` per disattivare la registrazione. I comandi di background e i comandi di sola lettura non portano alcun diff.1740Quando un comando Bash 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.
1736 1741
1737Il tuo [hook PostToolUse](#posttooluse) riceve quindi i file modificati in `tool_response.bashEditDiff`. L'elenco copre ciò che è cambiato nel repository mentre il comando era in esecuzione. I file che Git ignora e i file nei submoduli non sono elencati. Richiede Claude Code v2.1.269 o successivo.1742Il tuo [hook PostToolUse](#posttooluse) riceve quindi i file modificati in `tool_response.bashEditDiff`. L'elenco copre ciò che è cambiato 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.
1738 1743
1739<Note>1744<Note>
1740 L'elenco è best effort e in beta pubblica. Claude Code può perdere un cambiamento, includere un file che un altro processo ha cambiato nello stesso momento, o fermarsi ai suoi limiti di dimensione. La forma del campo potrebbe cambiare. Usa l'elenco per trovare cosa rivedere, non per applicare una policy.1745 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.
1741</Note>1746</Note>
1742 1747
1743`changedFiles` e `files` elencano ciò che il comando ha cambiato; i campi rimanenti dicono quanto è completo e quanto è affidabile quell'elenco.1748`changedFiles` e `files` elencano ciò che il comando ha cambiato; i campi rimanenti dicono quanto è completo e quanto è affidabile quell'elenco.
1749| `moreFiles` | number | `2` | Conteggio dei file modificati senza diff in `files` |1754| `moreFiles` | number | `2` | Conteggio dei file modificati senza diff in `files` |
1750| `unavailable` | boolean | `true` | Impostato quando il diff è incompleto o non poteva essere preso |1755| `unavailable` | boolean | `true` | Impostato quando il diff è incompleto o non poteva essere preso |
1751| `skipped` | boolean | `true` | Impostato per un comando Git che sposta l'albero di lavoro, come `git checkout` o `git stash`, quindi Claude Code non prende alcun diff |1756| `skipped` | boolean | `true` | Impostato per un comando Git che sposta l'albero di lavoro, come `git checkout` o `git stash`, quindi Claude Code non prende alcun diff |
1752| `shared` | boolean | `true` | Impostato quando un'altra chiamata dello strumento Bash, come quella di un subagente, si è eseguita nello stesso repository nello stesso momento, quindi alcuni cambiamenti elencati potrebbero essere di quel comando |1757| `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 |
1753 1758
1754<a id="powershell" />1759<a id="powershell" />
1755 1760
1768| `timeout` | number | `120000` | Timeout facoltativo in millisecondi |1773| `timeout` | number | `120000` | Timeout facoltativo in millisecondi |
1769| `run_in_background` | boolean | `false` | Se eseguire il comando in background |1774| `run_in_background` | boolean | `false` | Se eseguire il comando in background |
1770 1775
1771Corrisponde a `Bash|PowerShell` negli hook che ispezionano i comandi shell, in modo che coprano entrambi gli strumenti:1776Corrisponde a `Bash|PowerShell` negli hook che ispezionano i comandi shell, quindi coprono entrambi gli strumenti:
1772 1777
1773* Su Windows, ovunque lo strumento PowerShell sia abilitato, Claude tratta PowerShell come la shell primaria e instrada i comandi shell attraverso di esso.1778* Su Windows, ovunque lo strumento PowerShell sia abilitato, Claude tratta PowerShell come la shell primaria e instrada i comandi shell attraverso di esso.
1774* Su Windows senza Git Bash, lo strumento è abilitato automaticamente e Claude Code non registra affatto lo strumento Bash.1779* Su Windows senza Git Bash, lo strumento è abilitato automaticamente e Claude Code non registra affatto lo strumento Bash.
1775* Un hook che corrisponde solo a `Bash` non si attiva mai lì.1780* Un hook che corrisponde solo a `Bash` non si esegue mai lì.
1776 1781
1777<h5 id="write">1782<h5 id="write">
1778 Write1783 Write
1802 Read1807 Read
1803</h5>1808</h5>
1804 1809
1805Legge il contenuto dei file.1810Legge i contenuti del file.
1806 1811
1807| Campo | Tipo | Esempio | Descrizione |1812| Campo | Tipo | Esempio | Descrizione |
1808| :- | :- | :- | :- |1813| :- | :- | :- | :- |
1825 Grep1830 Grep
1826</h5>1831</h5>
1827 1832
1828Cerca il contenuto dei file con espressioni regolari.1833Cerca i contenuti dei file con espressioni regolari.
1829 1834
1830| Campo | Tipo | Esempio | Descrizione |1835| Campo | Tipo | Esempio | Descrizione |
1831| :- | :- | :- | :- |1836| :- | :- | :- | :- |
1832| `pattern` | string | `"TODO.*fix"` | Modello di espressione regolare da cercare |1837| `pattern` | string | `"TODO.*fix"` | Modello di espressione regolare da cercare |
1833| `path` | string | `"/path/to/dir"` | File o directory facoltativa da cercare |1838| `path` | string | `"/path/to/dir"` | File o directory facoltativo da cercare |
1834| `glob` | string | `"*.ts"` | Modello glob facoltativo per filtrare i file |1839| `glob` | string | `"*.ts"` | Modello glob facoltativo per filtrare i file |
1835| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"`, o `"count"`. Predefinito a `"files_with_matches"` |1840| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"`, o `"count"`. Predefinito a `"files_with_matches"` |
1836| `-i` | boolean | `true` | Ricerca senza distinzione tra maiuscole e minuscole |1841| `-i` | boolean | `true` | Ricerca senza distinzione tra maiuscole e minuscole |
1837| `multiline` | boolean | `false` | Abilita la corrispondenza multiriga |1842| `multiline` | boolean | `false` | Abilita la corrispondenza multilinea |
1838 1843
1839<h5 id="webfetch">1844<h5 id="webfetch">
1840 WebFetch1845 WebFetch
1870| `prompt` | string | `"Find all API endpoints"` | L'attività per l'agente da eseguire |1875| `prompt` | string | `"Find all API endpoints"` | L'attività per l'agente da eseguire |
1871| `description` | string | `"Find API endpoints"` | Breve descrizione dell'attività |1876| `description` | string | `"Find API endpoints"` | Breve descrizione dell'attività |
1872| `subagent_type` | string | `"Explore"` | Tipo di agente specializzato da usare |1877| `subagent_type` | string | `"Explore"` | Tipo di agente specializzato da usare |
1873| `model` | string | `"sonnet"` | Alias del modello facoltativo per sovrascrivere il predefinito |1878| `model` | string | `"sonnet"` | Alias di modello facoltativo per sovrascrivere il predefinito |
1874 1879
1875Quando una chiamata Agent in primo piano si completa, il tuo [hook PostToolUse](#posttooluse) riceve il risultato del subagente e la telemetria di esecuzione in `tool_response`. Leggi questi campi per ispezionare l'esecuzione; per i rollup di token e costo tra i subagenti, usa i [contatori di token e costo](/docs/it/monitoring-usage#token-counter) filtrati a `query_source` `"subagent"`, poiché `totalTokens` e `usage` coprono solo la richiesta finale:1880Quando una chiamata Agent in primo piano 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:
1876 1881
1877| Campo | Tipo | Esempio | Descrizione |1882| Campo | Tipo | Esempio | Descrizione |
1878| :- | :- | :- | :- |1883| :- | :- | :- | :- |
1879| `status` | string | `"completed"` | `"completed"` per i subagenti in primo piano, `"async_launched"` per i subagenti di background. A partire dalla v2.1.198, i subagenti si eseguono in background per impostazione predefinita, quindi un `run_in_background` omesso produce anche `"async_launched"` |1884| `status` | string | `"completed"` | `"completed"` per i subagenti in primo piano, `"async_launched"` per i subagenti di background. A partire dalla v2.1.198, i subagenti si eseguono in background per impostazione predefinita, quindi un `run_in_background` omesso produce anche `"async_launched"` |
1880| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificatore per l'esecuzione del subagente |1885| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificatore per l'esecuzione del subagente |
1881| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | I blocchi di testo finali del subagente, o, per un subagente il cui rapporto passa attraverso `SubagentHandback`, una breve nota su quel hand-back al loro posto |1886| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | I blocchi di testo finali del subagente, o, per un subagente il cui rapporto passa attraverso `SubagentHandback`, una breve nota su quel hand-back al loro posto |
1882| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modello su cui il subagente ha iniziato, che potrebbe differire dal modello richiesto |1887| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modello su cui il subagente ha iniziato, che può differire dal modello richiesto |
1883| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelli usati in ordine, con ripetizioni consecutive compresse; impostato solo quando il modello è stato scambiato a metà esecuzione. Richiede Claude Code v2.1.212 o successivo |1888| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelli usati in ordine, con ripetizioni consecutive collassate; impostato solo quando il modello è stato scambiato a metà esecuzione. Richiede Claude Code v2.1.212 o successivo |
1884| `totalTokens` | number | `12450` | Conteggio dei token dalla richiesta API finale del subagente: token di input, output, e cache combinati. Questo non è un totale su tutta l'esecuzione |1889| `totalTokens` | number | `12450` | Conteggio dei token dalla richiesta API finale del subagente: token di input, output, e cache combinati. Questo non è un totale su tutta l'esecuzione |
1885| `totalDurationMs` | number | `48211` | Durata di tempo reale dell'esecuzione del subagente |1890| `totalDurationMs` | number | `48211` | Durata di tempo reale dell'esecuzione del subagente |
1886| `totalToolUseCount` | number | `7` | Conteggio delle chiamate di strumenti che il subagente ha effettuato |1891| `totalToolUseCount` | number | `7` | Conteggio delle chiamate di strumento che il subagente ha fatto |
1887| `usage` | object | `{"input_tokens": 8320, ...}` | Breakdown dei token per tipo della richiesta API finale: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1892| `usage` | object | `{"input_tokens": 8320, ...}` | Breakdown dei token per tipo della richiesta API finale: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |
1888 1893
1889Su Claude Code v2.1.271 o successivo, un subagente che si esegue con lo strumento [`SubagentHandback`](/docs/it/tools-reference), che Claude Code fornisce in [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), consegna il suo rapporto attraverso quello strumento piuttosto che restituirlo come testo. Il campo `content` del suo risultato `completed` porta quindi una breve nota su quel hand-back piuttosto che il rapporto stesso. Per leggere il rapporto, corrisponde a un hook `PreToolUse` o `PostToolUse` su `SubagentHandback` e leggi `tool_input.message`.1894Su Claude Code v2.1.271 o 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`.
1890 1895
1891Per i subagenti di background, lo strumento ritorna quando l'attività passa al background, quindi `tool_response` non porta campi di utilizzo: un lancio di background ritorna immediatamente, e un'attività in primo piano che Claude Code passa al background a metà esecuzione ritorna a quella transizione. Ha `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, e `resolvedModel`.1896Per 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`.
1892 1897
1893Su 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 è passato al background, quindi uno scambio che è accaduto prima del passaggio al background si riflette lì. `modelsUsed` e il comportamento `resolvedModel` al momento del passaggio al background richiedono Claude Code v2.1.212 o successivo.1898Su 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.
1894 1899
1895<a id="askuserquestion" />1900<a id="askuserquestion" />
1896 1901
1903| Campo | Tipo | Esempio | Descrizione |1908| Campo | Tipo | Esempio | Descrizione |
1904| :- | :- | :- | :- |1909| :- | :- | :- | :- |
1905| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Domande da presentare, ciascuna con una stringa `question`, un breve `header`, un array `options`, e un flag `multiSelect` facoltativo |1910| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Domande da presentare, ciascuna con una stringa `question`, un breve `header`, un array `options`, e un flag `multiSelect` facoltativo |
1906| `answers` | object | `{"Which framework?": "React"}` | Facoltativo. Mappa il testo della domanda all'etichetta dell'opzione selezionata. Le risposte multi-select uniscono le etichette con virgole. Claude non imposta questo campo; forniscilo tramite `updatedInput` per rispondere programmaticamente |1911| `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 |
1907 1912
1908<h5 id="exitplanmode">1913<h5 id="exitplanmode">
1909 ExitPlanMode1914 ExitPlanMode
1915| :- | :- | :- | :- |1920| :- | :- | :- | :- |
1916| `plan` | string | `"## Refactor auth\n1. Extract..."` | Contenuto del piano in Markdown. Iniettato dal file del piano su disco |1921| `plan` | string | `"## Refactor auth\n1. Extract..."` | Contenuto del piano in Markdown. Iniettato dal file del piano su disco |
1917| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Percorso al file del piano. Iniettato |1922| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Percorso al file del piano. Iniettato |
1918| `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 per implementare il piano |1923| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Deprecato. Claude Code accetta il campo ma lo ignora. Prima della v2.1.205, portava permessi basati su prompt che Claude ha richiesto di implementare il piano |
1919 1924
1920In `PostToolUse`, `tool_response` è un oggetto con campi `plan` e `filePath` che contengono il piano approvato, più flag di stato interni. Leggi `tool_response.plan` per il contenuto del piano piuttosto che rileggere il file da disco.1925In `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.
1921 1926
1922<h4 id="pretooluse-decision-control">1927<h4 id="pretooluse-decision-control">
1923 Controllo decisionale PreToolUse1928 Controllo decisionale PreToolUse
1924</h4>1929</h4>
1925 1930
1926Gli 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 all'interno di un oggetto `hookSpecificOutput`. Questo gli dà un controllo più ricco: quattro risultati (consenti, nega, chiedi, o differisci) più la capacità di modificare l'input dello strumento prima dell'esecuzione.1931Gli hook `PreToolUse` possono controllare se una chiamata 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.
1927 1932
1928| Campo | Descrizione |1933| Campo | Descrizione |
1929| :- | :- |1934| :- | :- |
1930| `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 correttamente in modo che lo strumento possa essere ripreso in seguito. Le [regole di negazione e richiesta](/docs/it/permissions#manage-permissions) vengono comunque valutate indipendentemente da ciò che l'hook restituisce |1935| `permissionDecision` | `"allow"` salta 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 |
1931| `permissionDecisionReason` | Per `"ask"`, mostrato all'utente ma non a Claude. Per `"deny"`, mostrato a Claude. Per `"allow"` e `"defer"`, scritto nel [log di debug](#debug-hooks) solo |1936| `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 |
1932| `updatedInput` | Modifica i parametri di input dello strumento prima dell'esecuzione. Sostituisce l'intero oggetto di input, quindi includi i campi invariati insieme a quelli modificati. Claude Code valuta le regole di permesso e l'idoneità [auto-background](/docs/it/tools-reference#background-commands) di un comando Bash rispetto all'input che il tuo hook restituisce, non l'input che Claude ha inviato. Combina con `"allow"` per auto-approvare, o `"ask"` per mostrare l'input modificato all'utente. Per `"defer"`, ignorato |1937| `updatedInput` | Modifica i parametri di input dello strumento prima dell'esecuzione. Sostituisce l'intero oggetto di input, quindi includi i campi invariati insieme a quelli modificati. Claude Code valuta le regole di permesso e l'idoneità [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 |
1933| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Ignorato quando `permissionDecision` è `"defer"`. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |1938| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Ignorato quando `permissionDecision` è `"defer"`. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |
1934 1939
1938 1943
1939Quando un hook restituisce `"ask"`, il prompt di permesso visualizzato all'utente include un'etichetta che identifica da dove viene l'hook: `[settings]` per un hook da qualsiasi file di impostazioni o dal frontmatter dell'agente, `[plugin:<name>]` per l'hook di un plugin, o `[skill]` per un hook dal frontmatter della skill. Questo aiuta gli utenti a capire quale fonte di configurazione sta richiedendo la conferma.1944Quando un hook restituisce `"ask"`, 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.
1940 1945
1941Un `"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ò comunque negare la chiamata dello strumento, ma non può approvare la chiamata silenziosamente. Prima della v2.1.211, il classificatore potrebbe 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"` dell'hook è sempre stato onorato.1946Un `"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.
1942 1947
1943```json theme={null}1948```json theme={null}
1944{1949{
1956 1961
1957<span id="allow-with-updatedinput" />1962<span id="allow-with-updatedinput" />
1958 1963
1959In [modalità non interattiva](/docs/it/headless) con il flag `-p`, Claude Code offre `AskUserQuestion` e `ExitPlanMode` solo quando l'esecuzione ha un [host di permesso](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs) per ricevere il prompt, come un callback `canUseTool` di Agent SDK. Questi strumenti richiedono l'interazione dell'utente. Restituire `permissionDecision: "allow"` insieme a `updatedInput` soddisfa quel requisito: l'hook legge l'input dello strumento da stdin, raccoglie la risposta attraverso la tua UI, e la restituisce in `updatedInput` in modo che lo strumento si esegua senza chiedere. Restituire `"allow"` da solo non è sufficiente per questi strumenti. Per `AskUserQuestion`, ripeti l'array `questions` originale e aggiungi un oggetto [`answers`](#askuserquestion) che mappa il testo di ogni domanda alla risposta scelta.1964In [modalità non interattiva](/docs/it/headless) con il flag `-p`, Claude Code offre `AskUserQuestion` e `ExitPlanMode` solo quando l'esecuzione ha un [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.
1960 1965
1961A 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.1966A 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.
1962 1967
1963<Note>1968<Note>
1964 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 attuale.1969 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.
1965</Note>1970</Note>
1966 1971
1967<h4 id="defer-a-tool-call-for-later">1972<h4 id="defer-a-tool-call-for-later">
1970 1975
1971`"defer"` è per le integrazioni che eseguono `claude -p` come un sottoprocesso e leggono il suo output JSON, come un'app Agent SDK o un'UI personalizzata costruita su Claude Code. Ti consente a quel processo di chiamata di mettere in pausa Claude a una chiamata di strumento, raccogliere l'input attraverso la sua interfaccia, e riprendere da dove si era fermato. Claude Code onora questo valore solo in [modalità non interattiva](/docs/it/headless) con il flag `-p`. Nelle sessioni interattive registra un avviso e ignora il risultato dell'hook.1976`"defer"` è 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.
1972 1977
1973Lo 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 [host di permesso](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs), come uno strumento MCP che passi con `--permission-prompt-tool`, quindi avvia l'esecuzione con uno. Il round trip funziona così:1978Lo strumento `AskUserQuestion` è il caso tipico: Claude vuole chiedere qualcosa all'utente, ma non c'è 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ì:
1974 1979
19751. Claude chiama `AskUserQuestion`. L'hook `PreToolUse` si attiva.19801. Claude chiama `AskUserQuestion`. L'hook `PreToolUse` si esegue.
19762. L'hook restituisce `permissionDecision: "defer"`. Lo strumento non si esegue. Il processo esce con `stop_reason: "tool_deferred"` e la chiamata dello strumento in sospeso preservata nella trascrizione.19812. L'hook restituisce `permissionDecision: "defer"`. Lo strumento non si esegue. Il processo esce con `stop_reason: "tool_deferred"` e la chiamata dello strumento in sospeso preservata nella trascrizione.
19773. Il processo di chiamata legge `deferred_tool_use` dal risultato dell'SDK, visualizza la domanda nella sua UI, e attende una risposta.19823. Il processo di chiamata legge `deferred_tool_use` dal risultato dell'SDK, visualizza la domanda nella sua UI, e attende una risposta.
19784. Il processo di chiamata esegue `claude -p --resume <session-id>` con lo stesso host di permesso. La stessa chiamata dello strumento attiva `PreToolUse` di nuovo.19834. Il processo di chiamata esegue `claude -p --resume <session-id>` con lo stesso permission host. La stessa chiamata dello strumento esegue `PreToolUse` di nuovo.
19795. L'hook restituisce `permissionDecision: "allow"` con la risposta in `updatedInput`. Lo strumento si esegue e Claude continua.19845. L'hook restituisce `permissionDecision: "allow"` con la risposta in `updatedInput`. Lo strumento si esegue e Claude continua.
1980 1985
1981Il campo `deferred_tool_use` porta l'`id` dello strumento, il `name`, e l'`input`. L'`input` è i parametri che Claude ha generato per la chiamata dello strumento, catturati prima dell'esecuzione:1986Il campo `deferred_tool_use` 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:
1994}1999}
1995```2000```
1996 2001
1997Non c'è timeout o limite di tentativi. La sessione rimane su disco fino a quando 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 loop restituendo infine `"allow"` o `"deny"` dall'hook.2002Non 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.
1998 2003
1999`"defer"` funziona solo quando Claude effettua una singola chiamata di strumento nel turno. Se Claude effettua diverse chiamate di strumenti contemporaneamente, `"defer"` viene ignorato con un avviso e lo strumento procede attraverso il flusso di permesso normale. Il vincolo esiste perché resume può solo rieseguire uno strumento: non c'è modo di differire una chiamata da un batch senza lasciare le altre irrisolte.2004`"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.
2000 2005
2001Se 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 ha fornito lo strumento non è connesso per la sessione ripresa. Il payload `deferred_tool_use` è ancora incluso in modo che tu possa identificare quale strumento è scomparso.2006Se lo strumento differito non è più disponibile quando riprendi, il processo esce con `stop_reason: "tool_deferred_unavailable"` e `is_error: true` prima che l'hook si 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.
2002 2007
2003<Note>2008<Note>
2004 Per riprendere una sessione differita in modalità piano, passa [`--permission-prompt-tool`](/docs/it/cli-reference#cli-flags) insieme a `--resume` in modo che Claude Code possa presentare il piano per l'approvazione. Se passi certi altri flag di lancio, l'esecuzione ripresa non ritorna alla modalità piano; vedi [Riprendi in modalità piano con `-p`](/docs/it/sessions#resume-in-plan-mode-with-p). Richiede Claude Code v2.1.246 o successivo.2009 Per riprendere una sessione differita in 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.
2005 2010
2006 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 su resume](/docs/it/sessions#permission-mode-on-resume).2011 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).
2007</Note>2012</Note>
2008 2013
2009<h3 id="permissionrequest">2014<h3 id="permissionrequest">
2011</h3>2016</h3>
2012 2017
2013Si esegue quando Claude Code sta per chiederti il permesso di usare uno strumento. Nelle sessioni che non possono mostrare un prompt, come i subagenti di background in [modalità non interattiva](/docs/it/headless), Claude Code esegue comunque questi hook, e se nessun hook restituisce una decisione, nega la chiamata dello strumento.2018Si esegue quando Claude Code sta per chiederti il permesso di usare uno strumento. Nelle sessioni che non possono mostrare un prompt, come i subagenti di background in [modalità non interattiva](/docs/it/headless), Claude Code esegue comunque questi hook, e se nessun hook restituisce una decisione, nega la chiamata dello strumento.
2014Usa il [controllo decisionale PermissionRequest](#permissionrequest-decision-control) per consentire o negare per conto dell'utente.2019Usa [Controllo decisionale PermissionRequest](#permissionrequest-decision-control) per consentire o negare per conto dell'utente.
2015 2020
2016Usa questo evento quando hai bisogno di un segnale nel momento in cui Claude chiede il permesso di usare uno strumento. Claude Code esegue un hook [Notification](#notification) con il tipo `permission_prompt` solo dopo che il prompt ha atteso circa sei secondi.2021Usa questo evento quando 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.
2017 2022
2018Claude Code non esegue hook PermissionRequest per la [richiesta di rete](/docs/it/sandboxing#network-isolation) di un comando in sandbox. Per ottenere un segnale per quel prompt, usa il tipo di notifica `permission_prompt`.2023Claude 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`.
2019 2024
2020Corrisponde al nome dello strumento, gli stessi valori di PreToolUse.2025Corrisponde al nome dello strumento, stessi valori di PreToolUse.
2021 2026
2022<h4 id="permissionrequest-input">2027<h4 id="permissionrequest-input">
2023 Input PermissionRequest2028 Input PermissionRequest
2025 2030
2026Gli hook PermissionRequest ricevono i campi `tool_name` e `tool_input` come gli hook PreToolUse, ma senza `tool_use_id`. Per uno strumento MCP, ricevono anche l'oggetto [`mcp_server`](#pretooluse-input). Un array `permission_suggestions` facoltativo contiene gli [aggiornamenti di permesso](#permission-update-entries) che Claude Code suggerisce per questa richiesta, come aggiungere una regola di consentimento o cambiare la modalità di permesso.2031Gli hook PermissionRequest ricevono i campi `tool_name` e `tool_input` come gli hook PreToolUse, ma senza `tool_use_id`. Per uno strumento MCP, ricevono anche l'oggetto [`mcp_server`](#pretooluse-input). Un array `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.
2027 2032
2028L'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 voce di suggerimento, come [**Sì, e passa alla modalità auto**](/docs/it/permission-modes#switch-permission-modes), che cambia la modalità di permesso direttamente piuttosto che attraverso un aggiornamento di permesso.2033L'array `permission_suggestions` non è un elenco esatto delle opzioni che vedi, perché ogni 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.
2029 2034
2030Gli 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 attiva per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).2035Gli 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).
2031 2036
2032```json theme={null}2037```json theme={null}
2033{2038{
2086 Voci di aggiornamento di permesso2091 Voci di aggiornamento di permesso
2087</h4>2092</h4>
2088 2093
2089Il campo di output `updatedPermissions` e il campo di input [`permission_suggestions`](#permissionrequest-input) usano entrambi lo stesso array di oggetti di voce. Ogni voce ha un `type` che determina i suoi altri campi, e una `destination` che controlla dove viene scritto il cambiamento.2094Sia 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.
2090 2095
2091| `type` | Campi | Effetto |2096| `type` | Campi | Effetto |
2092| :- | :- | :- |2097| :- | :- | :- |
2103 `bypassPermissions` non viene mai persistito come `defaultMode` indipendentemente da `destination`.2108 `bypassPermissions` non viene mai persistito come `defaultMode` indipendentemente da `destination`.
2104</Note>2109</Note>
2105 2110
2106Il campo `destination` su ogni voce determina se il cambiamento rimane in memoria o persiste in un file di impostazioni.2111Il campo `destination` su ogni voce determina se il cambio rimane in memoria o persiste in un file di impostazioni.
2107 2112
2108| `destination` | Scrive su |2113| `destination` | Scrive in |
2109| :- | :- |2114| :- | :- |
2110| `session` | solo in memoria, scartato quando la sessione termina |2115| `session` | solo in memoria, scartato quando la sessione termina |
2111| `localSettings` | `.claude/settings.local.json` |2116| `localSettings` | `.claude/settings.local.json` |
2118 PostToolUse2123 PostToolUse
2119</h3>2124</h3>
2120 2125
2121Si esegue immediatamente dopo che uno strumento si completa con successo.2126Si esegue immediatamente dopo che uno strumento completa con successo.
2122 2127
2123Corrisponde al nome dello strumento, gli stessi valori di PreToolUse.2128Corrisponde al nome dello strumento, stessi valori di PreToolUse.
2124 2129
2125Corrisponde più ampiamente quando il nome dello strumento non è il filtro giusto:2130Corrisponde più ampiamente quando il nome dello strumento non è il filtro giusto:
2126 2131
2127* Per eseguire un hook dopo che qualsiasi strumento si 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 strumenti che falliscono, aggiungi lo stesso hook sotto [PostToolUseFailure](#posttoolusefailure).2132* 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).
2128* Per eseguire un hook quando un file specifico cambia su disco, indipendentemente da chi lo ha scritto, usa [FileChanged](#filechanged). Claude Code non esegue un hook `PostToolUse` che corrisponde a `Edit|Write` quando un comando `Bash` o un processo al di fuori di Claude Code riscrive lo stesso file.2133* Per eseguire un hook quando un file specifico cambia su disco, qualunque cosa lo abbia scritto, usa [FileChanged](#filechanged). Claude Code non esegue un hook `PostToolUse` che corrisponde a `Edit|Write` quando un comando `Bash` o un processo al di fuori di Claude Code riscrive lo stesso file.
2129 2134
2130<h4 id="posttooluse-input">2135<h4 id="posttooluse-input">
2131 Input PostToolUse2136 Input PostToolUse
2132</h4>2137</h4>
2133 2138
2134Gli hook `PostToolUse` si attivano 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` dello strumento di file arrivano nello stesso formato di [PreToolUse](#pretooluse-input): sempre assoluti, con i separatori nativi della piattaforma, quindi backslash su Windows. Per uno strumento MCP, l'input porta anche l'oggetto [`mcp_server`](#pretooluse-input).2139Gli hook `PostToolUse` si 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).
2135 2140
2136```json theme={null}2141```json theme={null}
2137{2142{
2191```2196```
2192 2197
2193<Warning>2198<Warning>
2194 `updatedToolOutput` cambia solo ciò che Claude vede. Lo strumento si è già eseguito nel momento in cui l'hook si attiva, quindi tutti i file scritti, i comandi eseguiti, o le richieste di rete inviate hanno già avuto effetto. La telemetria come gli span degli strumenti OpenTelemetry e gli eventi di analisi catturano anche l'output originale prima che l'hook si esegua. Per prevenire o modificare una chiamata di strumento prima che si esegua, usa un hook [PreToolUse](#pretooluse) invece.2199 `updatedToolOutput` 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.
2195 2200
2196 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ò causare che proceda su un'assunzione falsa.2201 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.
2197</Warning>2202</Warning>
2198 2203
2199<h4 id="annotate-a-result-for-the-auto-mode-classifier">2204<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2216Quanto peso il classificatore dà alla nota dipende da dove hai configurato l'hook:2221Quanto peso il classificatore dà alla nota dipende da dove hai configurato l'hook:
2217 2222
2218* **Hook configurati in Claude Code**: per gli hook dai file di impostazioni, dai plugin, dalle skill, e dal frontmatter dell'agente, il classificatore tratta la nota come contesto non verificato fornito dall'applicazione. La nota non stabilisce mai l'intento dell'utente, e se afferma che hai approvato o richiesto qualcosa, il classificatore controlla quell'affermazione rispetto ai tuoi stessi messaggi nella conversazione2223* **Hook configurati in Claude Code**: per gli hook 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 conversazione
2219* **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 potrebbe pesare un'affermazione dell'utente trasmessa nella nota come intento dell'utente. Tale affermazione può soddisfare un requisito di consenso che il classificatore accetterebbe da un messaggio che invii, ma non solleva mai un blocco che il tuo stesso messaggio non potrebbe sollevare neanche. Dopo che una sessione riprende, Claude Code tratta le note ripristinate come contesto non verificato. Quando gli hook di entrambi i gruppi annotano la stessa chiamata, il classificatore tratta la nota combinata come non verificata2224* **Callback 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 verificata
2220 2225
2221Claude Code applica questi limiti quando consegna la nota:2226Claude Code applica questi limiti quando consegna la nota:
2222 2227
2223* **Lunghezza**: Claude Code limita le note per una chiamata di strumento a 2.000 caratteri e tronca il resto. Il limite è condiviso tra ogni hook che risponde a quella chiamata2228* **Lunghezza**: Claude Code limita le note per una chiamata di strumento a 2.000 caratteri e tronca il resto. Il limite è condiviso tra ogni hook che risponde a quella chiamata
2224* **Solo risposte sincrone**: Claude Code ignora il campo nella risposta di un hook che [si esegue in background](#run-hooks-in-the-background), perché quella risposta arriva dopo che Claude Code registra il risultato dello strumento2229* **Solo risposte sincrone**: Claude Code ignora il campo nella risposta di un hook che [si esegue in background](#run-hooks-in-the-background), perché quella risposta arriva dopo che Claude Code registra il risultato dello strumento
2225* **Chiamate che il classificatore non registra**: la trascrizione del classificatore omette le ricerche di sola lettura come le letture di file e le ricerche. Claude Code scarta una nota allegata a una di quelle chiamate2230* **Chiamate che il classificatore non registra**: la trascrizione del classificatore omette le ricerche di sola lettura come le letture di file e le ricerche. Claude Code scarta una nota allegata a una di quelle chiamate
2226* **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 un'altra riscrittura dell'hook la sostituisce. Claude Code consegna una nota che restituisci senza una riscrittura anche quando un altro hook riscrive l'output2231* **Interazione con le riscritture**: quando la nota descrive 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'output
2227 2232
2228<Warning>2233<Warning>
2229 Il classificatore legge il contenuto che metti in `classifierContext` come informazioni dall'applicazione che ospita la sessione, quindi non copiare l'output dello strumento non attendibile o il testo di terze parti in esso. Mantieni la nota a una breve affermazione su questa una chiamata, come un fatto sulla sua origine o un'affermazione dell'utente su di essa; non usare il campo per consegnare messaggi non correlati o un flusso di eventi.2234 Il classificatore legge il contenuto che 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.
2233 PostToolUseFailure2238 PostToolUseFailure
2234</h3>2239</h3>
2235 2240
2236Si 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. Usalo per registrare i fallimenti, inviare avvisi, o fornire feedback correttivo a Claude.2241Si 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.
2237 2242
2238Corrisponde al nome dello strumento, gli stessi valori di PreToolUse.2243Corrisponde al nome dello strumento, stessi valori di PreToolUse.
2239 2244
2240<Note>2245<Note>
2241 Questo evento non si attiva per le chiamate di strumenti 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 attivano né `PreToolUse` né `PostToolUseFailure`. Le negazioni di permesso attivano `PreToolUse` ma non questo evento; vedi [PermissionDenied](#permissiondenied).2246 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).
2242</Note>2247</Note>
2243 2248
2244<h4 id="posttoolusefailure-input">2249<h4 id="posttoolusefailure-input">
2269| Campo | Descrizione |2274| Campo | Descrizione |
2270| :- | :- |2275| :- | :- |
2271| `error` | Stringa che descrive cosa è andato male. Il formato dipende dallo strumento che ha fallito |2276| `error` | Stringa che descrive cosa è andato male. Il formato dipende dallo strumento che ha fallito |
2272| `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 attiva questo hook; il risultato dello strumento porta il messaggio di interruzione invece |2277| `is_interrupt` | Booleano facoltativo. True quando il fallimento ha raggiunto Claude Code come 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 |
2273| `duration_ms` | Facoltativo. Tempo di esecuzione dello strumento in millisecondi. Esclude il tempo trascorso nei prompt di permesso e negli hook PreToolUse |2278| `duration_ms` | Facoltativo. Tempo di esecuzione dello strumento in millisecondi. Esclude il tempo trascorso nei prompt di permesso e negli hook PreToolUse |
2274 2279
2275La stringa `error` è generalmente lo stesso testo che Claude riceve come risultato dello strumento fallito. Il suo formato varia per strumento e fallimento. Chiavi il tuo hook su `tool_name`, `is_interrupt`, e la prima riga `Exit code N`; tratta il resto della stringa come testo di visualizzazione, non un formato stabile.2280La stringa `error` è generalmente lo stesso testo che Claude riceve come risultato dello strumento fallito. Il suo formato varia 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.
2276 2281
2277* Per Bash e PowerShell, un comando che si è eseguito e ha uscito produce una prima riga `Exit code N`, quindi qualsiasi output che il comando ha prodotto come un blocco con stdout e stderr intercalati2282* Per Bash e PowerShell, un comando 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 intercalati
2278* Un payload potrebbe anche portare un messaggio di fallimento nudo senza una riga di codice di uscita, quando Claude Code non poteva avviare il processo shell stesso2283* Un payload può anche portare un messaggio di fallimento nudo senza una riga di codice di uscita, quando Claude Code non poteva avviare il processo shell stesso
2279* Claude Code tronca nel mezzo le stringhe lunghe intorno a un marcatore `... [N characters truncated] ...`, e può inserire righe proprie, come `Command timed out after 2m 0s`2284* Claude Code tronca nel mezzo le stringhe lunghe intorno a un marcatore `... [N characters truncated] ...`, e può inserire righe proprie, come `Command timed out after 2m 0s`
2280 2285
2281<h4 id="posttoolusefailure-decision-control">2286<h4 id="posttoolusefailure-decision-control">
2301 PostToolBatch2306 PostToolBatch
2302</h3>2307</h3>
2303 2308
2304Si 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 attiva una volta per strumento, il che significa che si attiva contemporaneamente quando Claude effettua chiamate di strumenti parallele. `PostToolBatch` si attiva 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.2309Si 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.
2305 2310
2306<h4 id="posttoolbatch-input">2311<h4 id="posttoolbatch-input">
2307 Input PostToolBatch2312 Input PostToolBatch
2333}2338}
2334```2339```
2335 2340
2336`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 lo ha emesso. Per `Read`, questo significa testo con prefisso numero di riga piuttosto che contenuti di file grezzi. Le risposte possono essere grandi, quindi analizza solo i campi di cui hai bisogno.2341`tool_response` contiene lo stesso contenuto che il modello riceve nel blocco `tool_result` corrispondente. Il valore è una stringa serializzata o un array di blocchi di contenuto, esattamente come lo strumento l'ha emesso. Per `Read`, 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.
2337 2342
2338<Note>2343<Note>
2339 La forma `tool_response` differisce da quella di `PostToolUse`. `PostToolUse` passa l'oggetto `Output` strutturato dello strumento, come `{filePath: "...", type: "create"}` per `Write`; `PostToolBatch` passa il contenuto `tool_result` serializzato che il modello vede.2344 La forma `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.
2358}2363}
2359```2364```
2360 2365
2361Restituire `decision: "block"` o `continue: false` ferma il loop agentivo prima della richiesta del modello successivo. Il messaggio di blocco viene da `reason` JSON o `stopReason`, o da stderr all'uscita 2. Lo vedi come un avviso nella trascrizione, e rimane nella conversazione, quindi Claude lo vede quando la conversazione continua.2366Restituire `decision: "block"` o `continue: false` 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.
2362 2367
2363<h3 id="permissiondenied">2368<h3 id="permissiondenied">
2364 PermissionDenied2369 PermissionDenied
2365</h3>2370</h3>
2366 2371
2367Si 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 attiva 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 potrebbe riprovare la chiamata dello strumento.2372Si 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.
2368 2373
2369Corrisponde al nome dello strumento, gli stessi valori di PreToolUse.2374Corrisponde al nome dello strumento, stessi valori di PreToolUse.
2370 2375
2371<h4 id="permissiondenied-input">2376<h4 id="permissiondenied-input">
2372 Input PermissionDenied2377 Input PermissionDenied
2399 Controllo decisionale PermissionDenied2404 Controllo decisionale PermissionDenied
2400</h4>2405</h4>
2401 2406
2402Gli hook PermissionDenied possono dire al modello che potrebbe riprovare la chiamata dello strumento negata. Restituisci un oggetto JSON con `hookSpecificOutput.retry` impostato su `true`:2407Gli hook PermissionDenied possono dire al modello che può ritentare la chiamata dello strumento negata. Restituisci un oggetto JSON con `hookSpecificOutput.retry` impostato su `true`:
2403 2408
2404```json theme={null}2409```json theme={null}
2405{2410{
2410}2415}
2411```2416```
2412 2417
2413Quando `retry` è `true`, Claude Code aggiunge un messaggio alla conversazione dicendo al modello che potrebbe riprovare la chiamata dello strumento. Claude Code non inverte la negazione stessa. Se il tuo hook non restituisce JSON, o restituisce `retry: false`, la negazione rimane e il modello riceve il messaggio di rifiuto originale.2418Quando `retry` è `true`, Claude Code aggiunge un messaggio alla conversazione 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.
2414 2419
2415Claude 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 riprovare più tardi o andare avanti.2420Claude 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.
2416 2421
2417<h3 id="notification">2422<h3 id="notification">
2418 Notification2423 Notification
2420 2425
2421Si esegue quando Claude Code invia notifiche. Corrisponde al tipo di notifica. Ometti il matcher per eseguire gli hook per tutti i tipi di notifica.2426Si esegue quando Claude Code invia notifiche. Corrisponde al tipo di notifica. Ometti il matcher per eseguire gli hook per tutti i tipi di notifica.
2422 2427
2423Ricevi questi eventi di hook anche con le notifiche desktop disattivate: l'impostazione `preferredNotifChannel`, incluso `notifications_disabled`, cambia solo come sei avvisato, non se il tuo hook si esegue.2428Ricevi questi eventi hook anche con le notifiche desktop disattivate: l'impostazione `preferredNotifChannel`, incluso `notifications_disabled`, cambia solo come sei avvisato, non se il tuo hook si esegue.
2424 2429
2425| Matcher | Quando si attiva |2430| Matcher | Quando si attiva |
2426| :- | :- |2431| :- | :- |
2427| `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 in sandbox, e il prompt ha atteso circa sei secondi |2432| `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 |
2428| `idle_prompt` | Claude ha finito di rispondere circa 60 secondi fa e non hai digitato da allora |2433| `idle_prompt` | Claude ha finito di rispondere circa 60 secondi fa e non hai digitato da allora |
2429| `auth_success` | L'autenticazione si completa |2434| `auth_success` | L'autenticazione completa |
2430| `elicitation_dialog` | Un server MCP apre un modulo di elicitazione e non hai digitato per circa sei secondi |2435| `elicitation_dialog` | Un server MCP apre un modulo di elicitazione e non hai digitato per circa sei secondi |
2431| `elicitation_url_dialog` | Un server MCP ti chiede di aprire un URL del browser e non hai digitato per circa sei secondi |2436| `elicitation_url_dialog` | Un server MCP ti chiede di aprire un URL del browser e non hai digitato per circa sei secondi |
2432| `elicitation_complete` | Un server MCP segnala che un'[elicitazione in modalità URL](#elicitation-input) è completa |2437| `elicitation_complete` | Un server MCP segnala che un'[elicitazione in modalità URL](#elicitation-input) è completa |
2433| `elicitation_response` | Una risposta di elicitazione MCP viene inviata al server |2438| `elicitation_response` | Una risposta di elicitazione MCP viene inviata di nuovo al server |
2434| `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, o la sessione corrente ti chiede una domanda di configurazione del terminale di un [compagno di squadra del team agente](/docs/it/agent-teams#choose-a-display-mode) e non hai digitato per circa sei secondi |2439| `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 |
2435| `agent_completed` | Una sessione di background finisce o fallisce. Si attiva solo mentre la [vista agente](/docs/it/agent-view) è aperta in un terminale |2440| `agent_completed` | Una sessione di background finisce o fallisce. Si esegue solo mentre la [vista agente](/docs/it/agent-view) è aperta in un terminale |
2436| `quota_auto_resume_fired` | Claude Code continua il tuo compito dopo che un limite di utilizzo di claude.ai lo ha messo in pausa: al reset, o prima quando qualcosa che fai in Claude Code durante l'attesa, come aggiungere crediti di utilizzo, aggiornare il tuo piano, o cambiare modelli, rende l'utilizzo disponibile di nuovo, con l'[eccezione dell'impostazione del modello](/docs/it/interactive-mode#wait-for-a-usage-limit-to-reset) |2441| `quota_auto_resume_fired` | Claude Code 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) |
2437| `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 attiva `quota_auto_resume_fired` invece |2442| `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 |
2438| `quota_auto_resume_disabled` | Claude Code termina l'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 attiva quando premi `Esc` o `Ctrl+C`, o scegli **Non continuare automaticamente** |2443| `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** |
2439 2444
2440I tipi `agent_needs_input` e `agent_completed` richiedono Claude Code v2.1.198 o successivo.2445I tipi `agent_needs_input` e `agent_completed` richiedono Claude Code v2.1.198 o successivo.
2441 2446
2442I tipi `quota_auto_resume_fired`, `quota_auto_resume_stale`, e `quota_auto_resume_disabled` richiedono Claude Code v2.1.234 o successivo.2447I tipi `quota_auto_resume_fired`, `quota_auto_resume_stale`, e `quota_auto_resume_disabled` richiedono Claude Code v2.1.234 o successivo.
2443 2448
2444Nelle sessioni di terminale, `permission_prompt` per la richiesta di rete di un comando in sandbox richiede Claude Code v2.1.246 o successivo.2449Nelle sessioni di terminale, `permission_prompt` per la richiesta di rete di un comando sandboxed richiede Claude Code v2.1.246 o successivo.
2445 2450
2446`agent_needs_input` per la domanda di configurazione del terminale di un compagno di squadra richiede Claude Code v2.1.248 o successivo.2451`agent_needs_input` per una domanda di configurazione del terminale del compagno di squadra richiede Claude Code v2.1.248 o successivo.
2447 2452
2448<Note>2453<Note>
2449 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:2454 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:
2450 2455
2451 * 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.2456 * 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.
2452 * 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 attiva invece.2457 * 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.
2453 * 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.2458 * 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.
2454 2459
2455 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.2460 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.
2458Claude 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:2463Claude 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:
2459 2464
2460* Aspettati `permission_prompt` circa sei secondi dopo che Claude chiede il permesso. Claude Code non lo rinvia mentre digiti.2465* Aspettati `permission_prompt` circa sei secondi dopo che Claude chiede il permesso. Claude Code non lo rinvia mentre digiti.
2461* Se tu o un hook [PermissionRequest](#permissionrequest) rispondi prima, Claude Code non esegue `permission_prompt`.2466* Se tu o un hook [PermissionRequest](#permissionrequest) rispondete prima, Claude Code non esegue `permission_prompt`.
2462* Imposta [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/it/env-vars) su `1` per disattivare `permission_prompt` in queste sessioni.2467* Imposta [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/it/env-vars) su `1` per disattivare `permission_prompt` in queste sessioni.
2463 2468
2464Prima della v2.1.233, `permission_prompt` non si attivava in queste sessioni.2469Prima della v2.1.233, `permission_prompt` non si eseguiva in queste sessioni.
2465 2470
2466Usa matcher separati per eseguire diversi gestori 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:2471Usa 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:
2467 2472
2468```json theme={null}2473```json theme={null}
2469{2474{
2496 Input Notification2501 Input Notification
2497</h4>2502</h4>
2498 2503
2499Oltre 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.2504Oltre 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.
2500 2505
2501```json theme={null}2506```json theme={null}
2502{2507{
2516 SubagentStart2521 SubagentStart
2517</h3>2522</h3>
2518 2523
2519Si 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 del [team agente](/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 gli [agenti personalizzati](/docs/it/sub-agents), questo è il campo `name` dal frontmatter dell'agente, non il nome del file.2524Si 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.
2520 2525
2521Per i subagenti spediti 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$`.2526Per 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$`.
2522 2527
2523<h4 id="subagentstart-input">2528<h4 id="subagentstart-input">
2524 Input SubagentStart2529 Input SubagentStart
2525</h4>2530</h4>
2526 2531
2527Oltre 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 che il matcher filtra.2532Oltre 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.
2528 2533
2529```json theme={null}2534```json theme={null}
2530{2535{
2552}2557}
2553```2558```
2554 2559
2555Quando 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 intatta la [cache del prompt](/docs/it/prompt-caching#subagents-and-the-cache) del subagente. Dopo che la [compattazione automatica](/docs/it/sub-agents#auto-compaction) scarta quella copia, Claude Code inietta il contesto dell'esecuzione successiva di nuovo.2560Quando 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.
2556 2561
2557<h3 id="subagentstop">2562<h3 id="subagentstop">
2558 SubagentStop2563 SubagentStop
2559</h3>2564</h3>
2560 2565
2561Si esegue quando un subagente di Claude Code ha finito di rispondere. Corrisponde al tipo di agente, gli stessi valori di SubagentStart.2566Si esegue quando un subagente di Claude Code ha finito di rispondere. Corrisponde al tipo di agente, stessi valori di SubagentStart.
2562 2567
2563<h4 id="subagentstop-input">2568<h4 id="subagentstop-input">
2564 Input SubagentStop2569 Input SubagentStop
2565</h4>2570</h4>
2566 2571
2567Oltre 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 della trascrizione.2572Oltre 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.
2568 2573
2569Non ogni evento SubagentStop proviene 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 attiva 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.2574Non 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.
2570 2575
2571Un `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 anche per gli eventi con un `agent_type` vuoto.2576Un `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.
2572 2577
2573Su 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 quindi 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`.2578Su 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`.
2574 2579
2575Gli 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.2580Gli 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.
2576 2581
2591}2596}
2592```2597```
2593 2598
2594Gli 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) su lo strumento `Agent` invece.2599Gli 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.
2595 2600
2596<h3 id="taskcreated">2601<h3 id="taskcreated">
2597 TaskCreated2602 TaskCreated
2598</h3>2603</h3>
2599 2604
2600Si 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 attiva.2605Si 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.
2601 2606
2602Gli hook TaskCreated non supportano i matcher e si attivano su ogni occorrenza.2607Gli hook TaskCreated non supportano i matcher e si eseguono su ogni occorrenza.
2603 2608
2604<h4 id="taskcreated-input">2609<h4 id="taskcreated-input">
2605 Input TaskCreated2610 Input TaskCreated
2606</h4>2611</h4>
2607 2612
2608Oltre ai [campi di input comuni](#common-input-fields), gli hook TaskCreated ricevono `task_id`, `task_subject`, e opzionalmente `task_description`, `teammate_name`, e `team_name`.2613Oltre 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`.
2609 2614
2610```json theme={null}2615```json theme={null}
2611{2616{
2625| :- | :- |2630| :- | :- |
2626| `task_id` | Identificatore dell'attività in fase di creazione |2631| `task_id` | Identificatore dell'attività in fase di creazione |
2627| `task_subject` | Titolo dell'attività |2632| `task_subject` | Titolo dell'attività |
2628| `task_description` | Descrizione dettagliata dell'attività. Potrebbe essere assente |2633| `task_description` | Descrizione dettagliata dell'attività. Può essere assente |
2629| `teammate_name` | Nome del compagno di squadra che crea l'attività. Potrebbe essere assente |2634| `teammate_name` | Nome del compagno di squadra che crea l'attività. Può essere assente |
2630| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |2635| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |
2631 2636
2632<h4 id="taskcreated-decision-control">2637<h4 id="taskcreated-decision-control">
2657 TaskCompleted2662 TaskCompleted
2658</h3>2663</h3>
2659 2664
2660Si esegue quando un'attività viene contrassegnata come completata. Questo si attiva in due situazioni: quando qualsiasi agente contrassegna esplicitamente un'attività come completata tramite lo strumento TaskUpdate, o quando un compagno di squadra del [team agente](/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 di lint prima che un'attività possa chiudersi.2665Si 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.
2661 2666
2662Gli hook TaskCompleted non supportano i matcher e si attivano su ogni occorrenza.2667Gli hook TaskCompleted non supportano i matcher e si eseguono su ogni occorrenza.
2663 2668
2664<h4 id="taskcompleted-input">2669<h4 id="taskcompleted-input">
2665 Input TaskCompleted2670 Input TaskCompleted
2666</h4>2671</h4>
2667 2672
2668Oltre ai [campi di input comuni](#common-input-fields), gli hook TaskCompleted ricevono `task_id`, `task_subject`, e opzionalmente `task_description`, `teammate_name`, e `team_name`.2673Oltre 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`.
2669 2674
2670```json theme={null}2675```json theme={null}
2671{2676{
2686| :- | :- |2691| :- | :- |
2687| `task_id` | Identificatore dell'attività in fase di completamento |2692| `task_id` | Identificatore dell'attività in fase di completamento |
2688| `task_subject` | Titolo dell'attività |2693| `task_subject` | Titolo dell'attività |
2689| `task_description` | Descrizione dettagliata dell'attività. Potrebbe essere assente |2694| `task_description` | Descrizione dettagliata dell'attività. Può essere assente |
2690| `teammate_name` | Nome del compagno di squadra che completa l'attività. Potrebbe essere assente |2695| `teammate_name` | Nome del compagno di squadra che completa l'attività. Può essere assente |
2691| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |2696| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |
2692 2697
2693<h4 id="taskcompleted-decision-control">2698<h4 id="taskcompleted-decision-control">
2719 Stop2724 Stop
2720</h3>2725</h3>
2721 2726
2722Si esegue quando l'agente Claude Code principale ha finito di rispondere. Non si esegue se l'arresto è avvenuto a causa di un'interruzione dell'utente. Gli errori API attivano [StopFailure](#stopfailure) invece.2727Si esegue quando l'agente Claude Code principale ha finito di rispondere. Non si esegue se l'arresto è avvenuto a causa di un'interruzione dell'utente. Gli errori API eseguono [StopFailure](#stopfailure) invece.
2723 2728
2724<Tip>2729<Tip>
2725 Il comando [`/goal`](/docs/it/goal) è una scorciatoia incorporata per un hook Stop con ambito di sessione basato su prompt. Usalo quando vuoi che Claude continui a lavorare verso una condizione senza scrivere la configurazione dell'hook.2730 Il comando [`/goal`](/docs/it/goal) è 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.
2726</Tip>2731</Tip>
2727 2732
2728<h4 id="stop-input">2733<h4 id="stop-input">
2731 2736
2732Oltre ai [campi di input comuni](#common-input-fields), gli hook Stop ricevono `stop_hook_active`, `last_assistant_message`, `background_tasks`, e `session_crons`. Il campo `stop_hook_active` è `true` quando Claude Code sta già continuando come risultato di un hook stop. Controlla questo valore o elabora la trascrizione per evitare di bloccarsi su una condizione che non si risolverà mai. Claude Code applica un limite di 8 continuazioni consecutive: dopo che gli hook stop hanno continuato il turno otto volte di fila, Claude Code sovrascrive il blocco successivo e termina il turno. Per aumentare il limite, imposta [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/it/env-vars).2737Oltre ai [campi di input comuni](#common-input-fields), gli hook Stop ricevono `stop_hook_active`, `last_assistant_message`, `background_tasks`, e `session_crons`. Il campo `stop_hook_active` è `true` quando Claude Code sta già 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).
2733 2738
2734Il campo `last_assistant_message` contiene il contenuto di testo 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 notifica, usa questo campo piuttosto che leggere `transcript_path`: il file della trascrizione non è garantito che includa il messaggio finale al momento di Stop su tutte le versioni.2739Il 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.
2735 2740
2736Gli 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". Entrambi gli array sono presenti quando il registro delle attività è raggiungibile e sono vuoti quando nulla è in volo o programmato.2741Gli array `background_tasks` e `session_crons` consentono agli hook di distinguere "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.
2737 2742
2738Ogni voce in `background_tasks` descrive un'attività in volo e usa questi campi:2743Ogni voce in `background_tasks` descrive un'attività in volo e usa questi campi:
2739 2744
2741| :- | :- |2746| :- | :- |
2742| `id` | Identificatore dell'attività |2747| `id` | Identificatore dell'attività |
2743| `type` | Etichetta del tipo di attività amichevole come `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session`, o `MCP task`. Ogni etichetta identifica quale funzionalità di Claude Code ha creato l'attività. Ritorna al discriminante grezzo per i tipi non riconosciuti |2748| `type` | Etichetta 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 |
2744| `status` | Stato attuale dell'attività |2749| `status` | Stato dell'attività corrente |
2745| `description` | Descrizione in testo libero, limitata a 1000 caratteri con un marcatore `… [+N chars]` in-stringa quando ritagliato |2750| `description` | Descrizione in testo libero, limitata a 1000 caratteri con un marcatore `… [+N chars]` in-stringa quando ritagliato |
2746| `command` | Riga di comando shell, limitata a 1000 caratteri. Presente solo per le attività `shell` |2751| `command` | Riga di comando shell, limitata a 1000 caratteri. Presente solo per le attività `shell` |
2747| `agent_type` | Nome del tipo di subagente. Presente solo per le attività `subagent` |2752| `agent_type` | Nome del tipo di subagente. Presente solo per le attività `subagent` |
2801| `reason` | Richiesto quando `decision` è `"block"`. Dice a Claude perché dovrebbe continuare |2806| `reason` | Richiesto quando `decision` è `"block"`. Dice a Claude perché dovrebbe continuare |
2802| `hookSpecificOutput.additionalContext` | Feedback non di errore per Claude. La conversazione continua in modo che Claude possa agire su di esso, ma a differenza di `decision: "block"` viene mostrato nella trascrizione come feedback dell'hook piuttosto che un errore dell'hook |2807| `hookSpecificOutput.additionalContext` | Feedback non di errore per Claude. La conversazione 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 |
2803 2808
2804Un hook che blocca uscendo con 2 si instrada allo stesso modo di `reason`: Claude riceve il messaggio stderr come spiegazione del perché dovrebbe continuare.2809Un 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.
2805 2810
2806```json theme={null}2811```json theme={null}
2807{2812{
2810}2815}
2811```2816```
2812 2817
2813Usa `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 in corso attraverso le stesse protezioni di loop di `decision: "block"`, vale a dire l'input `stop_hook_active` e il limite di 8 continuazioni consecutive, ma la trascrizione lo etichetta come `Stop hook feedback` e nessuna notifica di errore dell'hook viene mostrata:2818Usa `additionalContext` quando l'hook funziona come 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:
2814 2819
2815```json theme={null}2820```json theme={null}
2816{2821{
2825 StopFailure2830 StopFailure
2826</h3>2831</h3>
2827 2832
2828Si esegue 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 recupero quando Claude non può completare una risposta a causa di limiti di velocità, problemi di autenticazione, o altri errori API.2833Si 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.
2829 2834
2830<h4 id="stopfailure-input">2835<h4 id="stopfailure-input">
2831 Input StopFailure2836 Input StopFailure
2857 TeammateIdle2862 TeammateIdle
2858</h3>2863</h3>
2859 2864
2860Si esegue quando un compagno di squadra del [team agente](/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 di lint o verificare che i file di output esistano.2865Si 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.
2861 2866
2862Gli hook TeammateIdle non supportano i matcher e si attivano su ogni occorrenza.2867Gli hook TeammateIdle non supportano i matcher e si eseguono su ogni occorrenza.
2863 2868
2864<h4 id="teammateidle-input">2869<h4 id="teammateidle-input">
2865 Input TeammateIdle2870 Input TeammateIdle
2948 Input ConfigChange2953 Input ConfigChange
2949</h4>2954</h4>
2950 2955
2951Oltre ai [campi di input comuni](#common-input-fields), gli hook ConfigChange ricevono `source` e opzionalmente `file_path`. Il campo `source` indica quale tipo di configurazione è cambiato, e `file_path` fornisce il percorso al file specifico che è stato modificato.2956Oltre ai [campi di input comuni](#common-input-fields), gli hook ConfigChange ricevono `source` e facoltativamente `file_path`. Il campo `source` indica quale tipo di configurazione è cambiato, e `file_path` fornisce il percorso al file specifico che è stato modificato.
2952 2957
2953```json theme={null}2958```json theme={null}
2954{2959{
2965 Controllo decisionale ConfigChange2970 Controllo decisionale ConfigChange
2966</h4>2971</h4>
2967 2972
2968Gli hook ConfigChange possono bloccare i cambiamenti di configurazione dall'avere effetto. Usa il codice di uscita 2 o un JSON `decision` per prevenire il cambiamento. Quando bloccato, le nuove impostazioni non vengono applicate alla sessione in esecuzione.2973Gli 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.
2969 2974
2970| Campo | Descrizione |2975| Campo | Descrizione |
2971| :- | :- |2976| :- | :- |
2972| `decision` | `"block"` impedisce l'applicazione del cambiamento di configurazione. Ometti per consentire il cambiamento |2977| `decision` | `"block"` impedisce l'applicazione del cambio di configurazione. Ometti per consentire il cambio |
2973| `reason` | Accettato ma mai mostrato |2978| `reason` | Accettato ma mai mostrato |
2974 2979
2975```json theme={null}2980```json theme={null}
2979}2984}
2980```2985```
2981 2986
2982I cambiamenti `policy_settings` non possono essere bloccati. Gli hook si attivano 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.2987I 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.
2983 2988
2984Claude Code agisce sulla decisione di blocco dall'output JSON di un hook ConfigChange e scarta `systemMessage` e `continue`. Un cambiamento 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 log di debug.2989Claude 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.
2985 2990
2986<h3 id="cwdchanged">2991<h3 id="cwdchanged">
2987 CwdChanged2992 CwdChanged
2988</h3>2993</h3>
2989 2994
2990Si 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 i toolchain specifici 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.2995Si 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.
2991 2996
2992Gli hook CwdChanged hanno accesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Le variabili scritte su quel file persistono nei comandi Bash successivi fino al prossimo evento [CwdChanged](#cwdchanged), quando Claude Code le cancella.2997Gli hook CwdChanged hanno accesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Le variabili scritte in quel file persistono nei comandi Bash successivi finché il prossimo evento CwdChanged, quando Claude Code le cancella.
2993 2998
2994CwdChanged non supporta i matcher e si attiva su ogni occorrenza.2999CwdChanged non supporta i matcher e si esegue su ogni occorrenza.
2995 3000
2996<h4 id="cwdchanged-input">3001<h4 id="cwdchanged-input">
2997 Input CwdChanged3002 Input CwdChanged
3020| :- | :- |3025| :- | :- |
3021| `watchPaths` | Array di percorsi assoluti. Sostituisce l'elenco di osservazione dinamico corrente. I percorsi dalla tua configurazione `matcher` vengono sempre osservati. Restituire un array vuoto cancella l'elenco dinamico, che è tipico quando si entra in una nuova directory |3026| `watchPaths` | Array di percorsi assoluti. Sostituisce l'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 |
3022 3027
3023Gli hook CwdChanged non hanno controllo decisionale. Non possono bloccare il cambiamento di directory.3028Gli hook CwdChanged non hanno controllo decisionale. Non possono bloccare il cambio di directory.
3024 3029
3025Claude Code legge `watchPaths` e `systemMessage` dal loro output JSON e scarta `continue`. Nelle sessioni interattive, mostra il `systemMessage` come una breve notifica di terminale. Il messaggio non raggiunge il flusso di messaggi dell'SDK.3030Claude Code legge `watchPaths` e `systemMessage` dal loro output JSON e scarta `continue`. Nelle sessioni interattive, mostra il `systemMessage` come una breve notifica di terminale. Il messaggio non raggiunge il flusso di messaggi dell'SDK.
3026 3031
3030 3035
3031Si 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.3036Si 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.
3032 3037
3033Claude Code non attiva questo evento quando:3038Claude Code non esegue questo evento quando:
3034 3039
3035* Passi una directory con il flag di avvio `--add-dir`; [SessionStart](#sessionstart) copre quelle directory3040* Passi una directory con il flag di avvio `--add-dir`; [SessionStart](#sessionstart) copre quelle directory
3036* Aggiungi una directory sulla scheda Workspace `/permissions`3041* Aggiungi una directory sulla scheda Workspace `/permissions`
3037* Aggiungi una directory che è già una directory di lavoro o dentro una3042* Aggiungi una directory che è già una directory di lavoro o dentro una
3038 3043
3039Claude Code attiva DirectoryAdded dopo aver aggiornato lo stato della sandbox e del permesso, quindi gli strumenti in sandbox vedono già la nuova directory quando il tuo hook si esegue. I comandi dell'hook stessi si eseguono non in sandbox.3044Claude 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.
3040 3045
3041Claude Code non attende l'hook: l'aggiunta si completa immediatamente, e l'hook si esegue in background con il timeout predefinito di 600 secondi.3046Claude Code non attende l'hook: l'aggiunta completa immediatamente, e l'hook si esegue in background con il timeout predefinito di 600 secondi.
3042 3047
3043Il matcher filtra su come la directory è stata aggiunta:3048Il matcher filtra su come la directory è stata aggiunta:
3044 3049
3071 3076
3072Gli hook DirectoryAdded non hanno controllo decisionale. Non possono bloccare l'aggiunta, che si è già completata quando l'hook si esegue. Claude Code scarta il campo `continue` dal loro output JSON e visualizza il resto diversamente per fonte:3077Gli hook DirectoryAdded non hanno controllo 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:
3073 3078
3074* `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 al log di debug3079* `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 log
3075* `register_repo_root`: Claude Code scrive l'output `systemMessage` e l'output di fallimento nel log di debug solo3080* `register_repo_root`: Claude Code scrive l'output `systemMessage` e l'output di fallimento nel debug log solo
3076 3081
3077<h3 id="filechanged">3082<h3 id="filechanged">
3078 FileChanged3083 FileChanged
3079</h3>3084</h3>
3080 3085
3081Si esegue quando un file osservato cambia su disco. Claude Code rileva i cambiamenti con un osservatore del file system, non ispezionando le chiamate di strumenti, 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.3086Si 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.
3082 3087
3083Il `matcher` per questo evento serve due ruoli:3088Il `matcher` per questo evento serve due ruoli:
3084 3089
3085* **Costruisci l'elenco di osservazione**: il valore è diviso su `|` e ogni segmento è registrato come un nome di file letterale nella directory di lavoro, quindi `".envrc|.env"` osserva esattamente quei due file. I modelli regex non sono utili qui: un valore come `^\.env` osserverebbe un file letteralmente denominato `^\.env`.3090* **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`.
3086* **Filtra quali hook si eseguono**: quando un file osservato cambia, lo stesso valore filtra quali gruppi di hook si eseguono usando le [regole di matcher](#matcher-patterns) standard rispetto al basename del file modificato.3091* **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.
3087 3092
3088Questo esempio normalizza le terminazioni di riga in `data.csv` dopo qualsiasi cambiamento, incluso un comando `Bash` o uno script esterno che riscrive il file:3093Questo esempio normalizza le terminazioni di riga in `data.csv` dopo qualsiasi cambio, incluso un comando `Bash` o uno script esterno che riscrive il file:
3089 3094
3090```json theme={null}3095```json theme={null}
3091{3096{
3105}3110}
3106```3111```
3107 3112
3108L'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ù sciatta si ripete per sempre, perché `perl -i` riscrive il file anche quando non sostituisce nulla e Claude Code esegue l'hook di nuovo dopo ogni riscrittura. Salva questo script in `/path/to/normalize-line-endings.sh` e rendilo eseguibile:3113L'hook legge il percorso assoluto del file modificato dal campo `file_path` dell'[input JSON](#filechanged-input) su stdin. 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:
3109 3114
3110```bash theme={null}3115```bash theme={null}
3111#!/bin/bash3116#!/bin/bash
3117 3122
3118Per confermare che l'hook funziona, chiedi a Claude di aggiungere una riga CRLF a `data.csv` con un comando `Bash`. Claude Code esegue l'hook e il file finisce con terminazioni LF.3123Per 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.
3119 3124
3120Per 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) 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 un file letterale denominato `*`.3125Per 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 `*`.
3121 3126
3122Gli hook FileChanged hanno accesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Le variabili scritte su quel file persistono nei comandi Bash successivi fino al prossimo evento [CwdChanged](#cwdchanged), quando Claude Code le cancella.3127Gli hook FileChanged hanno accesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Le variabili scritte in quel file persistono nei comandi Bash successivi finché il prossimo evento [CwdChanged](#cwdchanged), quando Claude Code le cancella.
3123 3128
3124<h4 id="filechanged-input">3129<h4 id="filechanged-input">
3125 Input FileChanged3130 Input FileChanged
3147 Output FileChanged3152 Output FileChanged
3148</h4>3153</h4>
3149 3154
3150Oltre 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 sono osservati:3155Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, gli hook FileChanged possono restituire `watchPaths` per aggiornare dinamicamente quali percorsi di file vengono osservati:
3151 3156
3152| Campo | Descrizione |3157| Campo | Descrizione |
3153| :- | :- |3158| :- | :- |
3154| `watchPaths` | Array di percorsi assoluti. Sostituisce l'elenco di osservazione dinamico corrente. I percorsi dalla tua configurazione `matcher` vengono sempre osservati. Usalo quando il tuo script hook scopre file aggiuntivi da osservare in base al file modificato |3159| `watchPaths` | Array di percorsi assoluti. Sostituisce l'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 |
3155 3160
3156Gli hook FileChanged non hanno controllo decisionale. Non possono bloccare il cambiamento del file dall'occorrenza.3161Gli hook FileChanged non hanno controllo decisionale. Non possono bloccare il cambio del file dal verificarsi.
3157 3162
3158Claude Code legge `watchPaths` e `systemMessage` dal loro output JSON e scarta `continue`. Nelle sessioni interattive, mostra il `systemMessage` come una breve notifica di terminale. Il messaggio non raggiunge il flusso di messaggi dell'SDK.3163Claude Code legge `watchPaths` e `systemMessage` dal loro output JSON e scarta `continue`. Nelle sessioni interattive, mostra il `systemMessage` come una breve notifica di terminale. Il messaggio non raggiunge il flusso di messaggi dell'SDK.
3159 3164
3163 3168
3164Si 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.3169Si 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.
3165 3170
3166Poiché 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 locale come `.env` nel nuovo worktree, fallo dentro il tuo script hook.3171Poiché 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.
3167 3172
3168L'hook deve restituire il percorso alla directory del worktree creato. Claude Code usa questo percorso come directory di lavoro per la sessione isolata. Vedi [Output WorktreeCreate](#worktreecreate-output) per come ogni tipo di hook restituisce il percorso.3173L'hook deve restituire il percorso 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.
3169 3174
3175Claude Code agisce sul successo dell'hook e sul percorso restituito, e scarta `systemMessage` e `continue`.
3176
3170Questo esempio crea una copia di lavoro SVN e stampa il percorso per Claude Code da usare. Sostituisci l'URL del repository con il tuo:3177Questo esempio crea una copia di lavoro SVN e stampa il percorso per Claude Code da usare. Sostituisci l'URL del repository con il tuo:
3171 3178
3172```json theme={null}3179```json theme={null}
3186}3193}
3187```3194```
3188 3195
3189L'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 percorso del worktree. Reindirizza qualsiasi altro output a stderr in modo che non interferisca con il percorso.3196L'hook legge il `name` del worktree dall'input JSON su stdin, 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.
3190 3197
3191<h4 id="worktreecreate-input">3198<h4 id="worktreecreate-input">
3192 Input WorktreeCreate3199 Input WorktreeCreate
3208 Output WorktreeCreate3215 Output WorktreeCreate
3209</h4>3216</h4>
3210 3217
3211Gli hook WorktreeCreate non usano il modello di decisione di consentimento/blocco standard. Invece, il successo o il fallimento dell'hook determina il risultato. L'hook deve restituire il percorso alla directory del worktree creato:3218Gli hook WorktreeCreate non usano il modello 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:
3212 3219
3213* **Hook di comando** (`type: "command"`): stampa il percorso come l'ultima riga non vuota di stdout. Claude Code rimuove i codici di escape ANSI prima di leggere quella riga, quindi i banner di avvio della shell stampati prima del tuo `echo` vengono ignorati. Reindirizza qualsiasi altro output dell'hook a stderr.3220* **Hook di comando** (`type: "command"`): stampa il percorso come 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.
3214* **Hook HTTP** (`type: "http"`): restituisci `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` nel corpo della risposta.3221* **Hook HTTP** (`type: "http"`): restituisci `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` nel corpo della risposta.
3215 3222
3216Se l'hook fallisce o non produce un percorso, la creazione del worktree fallisce con un errore.3223Se l'hook fallisce o non produce alcun percorso, la creazione del worktree fallisce con un errore.
3217 3224
3218Claude Code risolve un percorso relativo rispetto alla directory in cui l'hook si è eseguito, comprimendo qualsiasi segmento `.` o `..` in esso. Se il percorso risultante non è una directory in cui Claude Code può entrare, la sessione stampa un errore che nomina il percorso ed esce con codice 1.3225Claude Code risolve un percorso relativo rispetto alla directory in cui 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.
3219 3226
3220Claude Code rifiuta un percorso assoluto che contiene segmenti `.` o `..`, e qualsiasi percorso che passa attraverso un symlink al di sotto della radice del repository, perché un symlink impegnato nel repository potrebbe reindirizzare il worktree al di fuori di esso. L'errore nomina il componente rifiutato. Restituisci un percorso normalizzato che non passa attraverso un symlink dentro il repository. Prima della v2.1.216, la creazione del worktree seguiva il percorso dell'hook senza questo screening.3227Claude Code rifiuta un percorso assoluto che contiene segmenti `.` o `..`, e qualsiasi percorso che 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.
3221 3228
3222<h3 id="worktreeremove">3229<h3 id="worktreeremove">
3223 WorktreeRemove3230 WorktreeRemove
3224</h3>3231</h3>
3225 3232
3226Si esegue quando un worktree viene rimosso. Questo è la controparte di pulizia di [WorktreeCreate](#worktreecreate). L'evento si attiva quando:3233Si esegue quando un worktree viene rimosso. Questo è il contrapparte di pulizia di [WorktreeCreate](#worktreecreate). L'evento si esegue quando:
3227 3234
3228* esci da una sessione `--worktree` e scegli di rimuoverla3235* esci da una sessione `--worktree` e scegli di rimuoverla
3229* un subagente con `isolation: "worktree"` finisce3236* un subagente con `isolation: "worktree"` finisce
3231 3238
3232Per i worktree basati su git, Claude Code gestisce la pulizia automaticamente con `git worktree remove`. Se hai configurato un hook WorktreeCreate, accoppialo con un hook WorktreeRemove per controllare la pulizia dei worktree che crea:3239Per i worktree basati su git, Claude Code gestisce la pulizia automaticamente con `git worktree remove`. Se hai configurato un hook WorktreeCreate, accoppialo con un hook WorktreeRemove per controllare la pulizia dei worktree che crea:
3233 3240
3234* **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) con un worktree creato da hook, vedi le regole di eliminazione della vista agente.3241* **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.
3235* **L'hook esce con 0**: il worktree conta come rimosso. Claude Code non legge nient'altro dall'hook, quindi assicurati che il tuo hook abbia eliminato la directory.3242* **L'hook esce con 0**: il worktree conta come rimosso. Claude Code non legge nient'altro dall'hook, quindi assicurati che il tuo hook abbia eliminato la directory.
3236* **L'hook esce con non-zero**: la rimozione fallisce se la directory in `worktree_path` esiste ancora dopo, e il worktree rimane su disco senza fallback git. Un hook che ha eliminato la directory prima di uscire con non-zero conta come rimosso. Per come il fallimento viene segnalato, vedi [Input WorktreeRemove](#worktreeremove-input).3243* **L'hook esce con 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).
3237 3244
3239 3246
3240Claude Code scarta i [campi di output JSON](#json-output) di un hook WorktreeRemove, come `systemMessage` e `continue`.3247Claude Code scarta i [campi di output JSON](#json-output) di un hook WorktreeRemove, come `systemMessage` e `continue`.
3241 3248
3242Per 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 al di sotto della 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 un worktree di questo tipo, [`claude rm`](/docs/it/agent-view#manage-sessions-from-the-shell) mantiene la sessione e il worktree invece. Prima della v2.1.216, l'hook si eseguiva sul percorso archiviato senza questi controlli.3249Per 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.
3243 3250
3244Claude Code passa il percorso restituito da WorktreeCreate come `worktree_path` nell'input dell'hook. Questo esempio legge quel percorso e rimuove la directory:3251Claude Code passa il percorso restituito da WorktreeCreate come `worktree_path` nell'input dell'hook. Questo esempio legge quel percorso e rimuove la directory:
3245 3252
3278 3285
3279Il codice di uscita di un hook WorktreeRemove decide il risultato. Quando un hook esce con non-zero e la directory in `worktree_path` esiste ancora dopo, la rimozione fallisce:3286Il codice di uscita di un hook WorktreeRemove decide il risultato. Quando un hook esce con non-zero e la directory in `worktree_path` esiste ancora dopo, la rimozione fallisce:
3280 3287
3281* Il worktree rimane su disco, e il comando dell'hook e stderr vanno al [log di debug](#debug-hooks).3288* Il worktree rimane su disco, e il comando dell'hook e stderr vanno nel [debug log](#debug-hooks).
3282* Se stavi eliminando una sessione di background, la sessione rimane anche. Il messaggio di rifiuto nella [vista agente](/docs/it/agent-view#what-deleting-a-session-removes) segnala come l'hook è terminato, come `exited 1`, cita l'inizio del suo stderr, e dice se eliminare la sessione di nuovo rimuove comunque la directory.3289* Se stavi eliminando una sessione 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.
3283 3290
3284<h3 id="precompact">3291<h3 id="precompact">
3296 3303
3297Esci con codice 2 per bloccare la compattazione. Per un `/compact` manuale, il messaggio stderr viene mostrato all'utente. Puoi anche bloccare restituendo JSON con `"decision": "block"`.3304Esci con codice 2 per bloccare la compattazione. Per un `/compact` manuale, il messaggio stderr viene mostrato all'utente. Puoi anche bloccare restituendo JSON con `"decision": "block"`.
3298 3305
3299Bloccare 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 non compattata. Se la compattazione è stata attivata per recuperare da un errore di limite di contesto già restituito dall'API, l'errore sottostante emerge e la richiesta corrente fallisce.3306Bloccare la compattazione automatica ha effetti diversi a seconda di quando si 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.
3300 3307
3301Claude Code scarta i campi `systemMessage` e `continue` di un hook PreCompact.3308Claude Code scarta i campi `systemMessage` e `continue` di un hook PreCompact.
3302 3309
3353 PreModelSwitch3360 PreModelSwitch
3354</h3>3361</h3>
3355 3362
3356Si 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 sarà il costo del cambio prima che accada.3363Si 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.
3357 3364
3358PreModelSwitch richiede Claude Code v2.1.251 o successivo. Claude Code lo esegue per queste richieste:3365PreModelSwitch richiede Claude Code v2.1.251 o successivo. Claude Code lo esegue per queste richieste:
3359 3366
3360* `/model <name>` e il selettore `/model`3367* `/model <name>` e il picker `/model`
3361* Il selettore del modello `Option+P` o `Alt+P`3368* Il picker del modello `Option+P` o `Alt+P`
3362* L'impostazione Model in `/config`3369* L'impostazione Model in `/config`
3363* Attivare la [modalità veloce](/docs/it/fast-mode) quando questo cambia il modello della sessione3370* Attivare la [modalità veloce](/docs/it/fast-mode) quando questo cambia il modello della sessione
3364* Una richiesta `set_model`, o un cambiamento di modello in una richiesta `apply_flag_settings`, da un host [Agent SDK](/docs/it/agent-sdk/typescript#query-object) o [Remote Control](/docs/it/remote-control)3371* Una richiesta `set_model`, o un cambio di modello in una richiesta `apply_flag_settings`, da un host [Agent SDK](/docs/it/agent-sdk/typescript#query-object) o [Remote Control](/docs/it/remote-control)
3365 3372
3366Claude Code non esegue gli hook PreModelSwitch per i cambi che fa da solo, come un [fallback di modello automatico](/docs/it/model-config#automatic-model-fallback) o il ripristino del modello quando riprendi una sessione. Quei cambi raggiungono [PostModelSwitch](#postmodelswitch) solo.3373Claude Code non esegue gli hook PreModelSwitch per i cambi che 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.
3367 3374
3441 Input PreModelSwitch3448 Input PreModelSwitch
3442</h4>3449</h4>
3443 3450
3444Oltre ai [campi di input comuni](#common-input-fields), gli hook PreModelSwitch ricevono i campi in questa tabella. Gli ultimi cinque descrivono quale costo ha reinviare la conversazione al nuovo modello, quindi un hook può mostrare quella cifra prima che il cambio accada.3451Oltre ai [campi di input comuni](#common-input-fields), gli hook PreModelSwitch ricevono i campi 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.
3445 3452
3446| Campo | Tipo | Descrizione |3453| Campo | Tipo | Descrizione |
3447| :- | :- | :- |3454| :- | :- | :- |
3448| `from_model` | string | ID del modello da cui il cambio cambia |3455| `from_model` | string | ID del modello da cui il cambio cambia |
3449| `to_model` | string | ID del modello a cui il cambio cambia. Il matcher confronta rispetto al nome canonico di questo modello |3456| `to_model` | string | ID del modello a cui il cambio cambia. Il matcher confronta rispetto al nome canonico di questo modello |
3450| `requested_model` | string o `null` | Il modello che la richiesta ha nominato: un alias come `opus`, un ID di modello completo, o `null` quando la richiesta era per il modello predefinito |3457| `requested_model` | string o `null` | Il modello che la richiesta ha nominato: un alias come `opus`, un ID di modello completo, o `null` quando la richiesta era per il modello predefinito |
3451| `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 cambiamento di modello in una richiesta `apply_flag_settings`, da un host Agent SDK o Remote Control |3458| `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 |
3452| `context_tokens` | number | Token che la richiesta successiva reinvia come suo prompt: l'input, la lettura della cache, la creazione della cache, e i token di output dell'ultima risposta nella conversazione principale, combinati. `0` prima della prima risposta |3459| `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 |
3453| `prompt_cache_warm` | boolean | Se la cache del prompt del modello corrente è probabilmente ancora calda, il che significa che il cambio la perde |3460| `prompt_cache_warm` | boolean | Se la cache del prompt del modello corrente è probabilmente ancora calda, il che significa che il cambio la perde |
3454| `cache_ttl` | string | [Durata della cache del prompt](/docs/it/prompt-caching#cache-lifetime) che Claude Code richiede per questa sessione: `"5m"` o `"1h"` |3461| `cache_ttl` | string | [Durata della cache del prompt](/docs/it/prompt-caching#cache-lifetime) che Claude Code richiede per questa sessione: `"5m"` o `"1h"` |
3455| `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 risposta successiva. Il server potrebbe non aver bisogno di ri-memorizzare l'intero contesto, quindi trattalo come una stima |3462| `estimated_cache_write_usd` | number | Costo stimato in dollari USA della scrittura di `context_tokens` nella cache del prompt su `to_model` 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 |
3456| `pricing` | string | Come Claude Code ha prezzato `estimated_cache_write_usd`: `"configured"` ai tuoi tassi organizzativi quando li ha configurati, `"catalog"` al prezzo di listino, o `"default"` quando `to_model` non ha un prezzo noto e Claude Code ha assunto un tasso predefinito |3463| `pricing` | string | Come Claude Code ha 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 |
3457 3464
3458Questo esempio mostra l'input per `/model opus` in una sessione che esegue Sonnet 5:3465Questo esempio mostra l'input per `/model opus` in una sessione che esegue Sonnet 5:
3506 3513
3507Claude Code mostra all'utente qualsiasi `systemMessage` che il tuo hook restituisce indipendentemente dalla decisione, quindi un hook di rapporto dei costi può restituire `{"systemMessage": "..."}` e uscire con 0.3514Claude Code mostra all'utente qualsiasi `systemMessage` che il tuo hook restituisce indipendentemente dalla decisione, quindi un hook di rapporto dei costi può restituire `{"systemMessage": "..."}` e uscire con 0.
3508 3515
3509Un hook PreModelSwitch che non risponde prima del suo timeout blocca il cambio. Su [PreToolUse](#timeouts), al contrario, un hook di comando che scade consente alla chiamata dello strumento di continuare. Il timeout predefinito per questo evento è 30 secondi. `PreModelSwitch` esegue solo gli hook `command`, `http`, e `mcp_tool`, quindi i default `prompt` e `agent` non si applicano.3516Un hook PreModelSwitch che non risponde prima del suo timeout blocca il cambio. 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.
3510 3517
3511Un 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 [Altri codici di uscita](#other-exit-codes).3518Un hook che esce con un codice diverso da 0 o 2 e non stampa alcuna decisione JSON non blocca: Claude Code mostra il suo stderr e applica il cambio, come descritto sotto [Codici di uscita diversi](#other-exit-codes).
3512 3519
3513<h3 id="postmodelswitch">3520<h3 id="postmodelswitch">
3514 PostModelSwitch3521 PostModelSwitch
3547}3554}
3548```3555```
3549 3556
3550Per confermare che l'hook funziona, passa a un modello Opus da una sessione che esegue un modello diverso, ad esempio esegui `/model opus` da una sessione Sonnet, quindi chiedi a Claude quale guida ha sul modello corrente.3557Per 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.
3551 3558
3552<h4 id="postmodelswitch-input">3559<h4 id="postmodelswitch-input">
3553 Input PostModelSwitch3560 Input PostModelSwitch
3554</h4>3561</h4>
3555 3562
3556Gli 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 cambiamento che Claude Code ha fatto da solo, e `"resume"` per il modello ripristinato quando riprendi una sessione.3563Gli hook PostModelSwitch ricevono gli stessi campi di [PreModelSwitch](#premodelswitch-input), con `hook_event_name` impostato su `"PostModelSwitch"` e due valori `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.
3557 3564
3558`requested_model` è `null` quando `source` è `"auto"`. Quando `source` è `"resume"`, è l'impostazione del modello salvato che Claude Code ha ripristinato.3565`requested_model` è `null` quando `source` è `"auto"`. Quando `source` è `"resume"`, è l'impostazione del modello salvato che Claude Code ha ripristinato.
3559 3566
3561 Controllo decisionale PostModelSwitch3568 Controllo decisionale PostModelSwitch
3562</h4>3569</h4>
3563 3570
3564Claude Code prende il tuo stdout in testo semplice dell'hook all'uscita 0, o `additionalContext` dall'output JSON, e lo consegna a Claude con la richiesta successiva dopo il cambio. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, puoi restituire:3571Claude Code prende 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:
3565 3572
3566| Campo | Descrizione |3573| Campo | Descrizione |
3567| :- | :- |3574| :- | :- |
3568| `additionalContext` | Stringa aggiunta al contesto di Claude con la richiesta successiva. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |3575| `additionalContext` | Stringa aggiunta al contesto di Claude con la richiesta successiva. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |
3569 3576
3570Se 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 modello target dell'ultimo cambio.3577Se 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.
3571 3578
3572<h3 id="sessionend">3579<h3 id="sessionend">
3573 SessionEnd3580 SessionEnd
3574</h3>3581</h3>
3575 3582
3576Si esegue quando una sessione di Claude Code termina. Utile per le attività di pulizia, la registrazione delle statistiche della sessione, o il salvataggio dello stato della sessione. Supporta i matcher per filtrare per motivo di uscita.3583Si 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.
3577 3584
3578Il campo `reason` nell'input dell'hook indica perché la sessione è terminata:3585Il campo `reason` nell'input dell'hook indica perché la sessione è terminata:
3579 3586
3584| `logout` | L'utente ha effettuato il logout |3591| `logout` | L'utente ha effettuato il logout |
3585| `prompt_input_exit` | L'utente è uscito mentre l'input del prompt era visibile |3592| `prompt_input_exit` | L'utente è uscito mentre l'input del prompt era visibile |
3586| `other` | Altri motivi di uscita |3593| `other` | Altri motivi di uscita |
3587| `bypass_permissions_disabled` | Rimosso nella v2.1.234; Claude Code non lo invia. Rimuovilo dai tuoi matcher `SessionEnd` |3594| `bypass_permissions_disabled` | Rimosso nella v2.1.234; Claude Code non lo invia. Eliminalo dai tuoi matcher `SessionEnd` |
3588 3595
3589<h4 id="sessionend-input">3596<h4 id="sessionend-input">
3590 Input SessionEnd3597 Input SessionEnd
3629 Input Elicitation3636 Input Elicitation
3630</h4>3637</h4>
3631 3638
3632Oltre 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`.3639Oltre 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`.
3633 3640
3634Per l'elicitazione in modalità modulo, il caso più comune:3641Per l'elicitazione in modalità modulo, il caso più comune:
3635 3642
3697 ElicitationResult3704 ElicitationResult
3698</h3>3705</h3>
3699 3706
3700Si esegue dopo che un utente risponde a un'elicitazione MCP. Gli hook possono osservare, modificare, o bloccare la risposta prima che venga inviata al server MCP.3707Si 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.
3701 3708
3702Il campo matcher corrisponde al nome del server MCP.3709Il campo matcher corrisponde al nome del server MCP.
3703 3710
3705 Input ElicitationResult3712 Input ElicitationResult
3706</h4>3713</h4>
3707 3714
3708Oltre 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`.3715Oltre ai [campi di input comuni](#common-input-fields), gli hook ElicitationResult ricevono `mcp_server_name`, `action`, e campi facoltativi `mode`, `elicitation_id`, e `content`.
3709 3716
3710```json theme={null}3717```json theme={null}
3711{3718{
