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.1211Una sessione che non hai nominato può comunque avere un [titolo generato](/docs/it/sessions#name-your-sessions). Quel titolo non è un titolo personalizzato e non appare in `session_title`.
1212
1213Quando `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 1214
1217| Campo | Descrizione |1215| Campo | Descrizione |
1218| :- | :- |1216| :- | :- |
1219| `seconds_since_last_response` | Secondi di tempo reale trascorsi dall'ultima risposta nella trascrizione ripresa |1217| `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 |1218| `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 |1219| `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 |1220| `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 1221
1224Questo esempio mostra l'input per una sessione ripresa 90 minuti dopo la sua ultima risposta:1222Questo esempio mostra l'input per una sessione ripresa 90 minuti dopo la sua ultima risposta:
1247| Campo | Descrizione |1245| Campo | Descrizione |
1248| :- | :- |1246| :- | :- |
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 |1247| `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 |1248| `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"` |1249| `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 |1250| `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 |1251| `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}1260}
1263```1261```
1264 1262
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`.1263Poiché 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 1264
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:1265Usa `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 1266
1281 Persistere variabili di ambiente1279 Persistere variabili di ambiente
1282</h4>1280</h4>
1283 1281
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.1282Gli 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 1283
1286Per impostare singole variabili di ambiente, scrivi istruzioni `export` su `CLAUDE_ENV_FILE`. Usa append (`>>`) per preservare le variabili impostate da altri hook:1284Per impostare singole variabili di ambiente, scrivi istruzioni `export` in `CLAUDE_ENV_FILE`. Usa append (`>>`) per preservare le variabili impostate da altri hook:
1287 1285
1288```bash theme={null}1286```bash theme={null}
1289#!/bin/bash1287#!/bin/bash
1324 Setup1322 Setup
1325</h3>1323</h3>
1326 1324
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.1325Si 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 1326
1329Il valore del matcher corrisponde al flag CLI che ha attivato l'hook:1327Il valore del matcher corrisponde al flag CLI che ha attivato l'hook:
1330 1328
1339 1337
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.1338Al 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 1339
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.1340Poiché 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 1341
1344<h4 id="setup-input">1342<h4 id="setup-input">
1345 Input Setup1343 Input Setup
1361 Controllo decisionale Setup1359 Controllo decisionale Setup
1362</h4>1360</h4>
1363 1361
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`.1362Gli 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 1363
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).1364Gli 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 1365
1368<h3 id="instructionsloaded">1366<h3 id="instructionsloaded">
1369 InstructionsLoaded1367 InstructionsLoaded
1370</h3>1368</h3>
1371 1369
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à.1370Si 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 1371
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.1372Questo 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 1373
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.1374Il 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 1375
1378<h4 id="instructionsloaded-input">1376<h4 id="instructionsloaded-input">
1379 Input InstructionsLoaded1377 Input InstructionsLoaded
1385| :- | :- |1383| :- | :- |
1386| `file_path` | Percorso assoluto al file di istruzioni che è stato caricato |1384| `file_path` | Percorso assoluto al file di istruzioni che è stato caricato |
1387| `memory_type` | Ambito del file: `"User"`, `"Project"`, `"Local"`, o `"Managed"` |1385| `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 |1386| `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` |1387| `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 |1388| `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` |1389| `parent_file_path` | Percorso al file di istruzioni genitore che ha incluso questo, per i caricamenti `include` |
1414 1412
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.1413Si 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 1414
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.1415Gli 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 1416
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.1417A 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 1418
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.1419Un [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 1420
1426 1424
1427Oltre ai [campi di input comuni](#common-input-fields), gli hook UserPromptSubmit ricevono il campo `prompt` contenente il testo che l'utente ha inviato. Il contenuto incollato che è crollato in un segnaposto `[Pasted text #N]` arriva espanso al suo posto. Nelle sessioni in cui Claude Code [contrassegna il testo incollato per Claude](/docs/it/terminal-config#how-claude-treats-pasted-text), quel contenuto espanso si trova tra una riga `<pasted_content id="…">` e una riga `</pasted_content id="…">`, quindi tieni conto di quelle righe se il tuo hook analizza il prompt.1425Oltre ai [campi di input comuni](#common-input-fields), gli hook UserPromptSubmit ricevono il campo `prompt` contenente il testo che l'utente ha inviato. Il contenuto incollato che è crollato in un segnaposto `[Pasted text #N]` arriva espanso al suo posto. Nelle sessioni in cui Claude Code [contrassegna il testo incollato per Claude](/docs/it/terminal-config#how-claude-treats-pasted-text), quel contenuto espanso si trova tra una riga `<pasted_content id="…">` e una riga `</pasted_content id="…">`, quindi tieni conto di quelle righe se il tuo hook analizza il prompt.
1428 1426
1427Gli hook UserPromptSubmit ricevono anche `session_title` quando la sessione ha un titolo personalizzato, con lo stesso significato del [campo SessionStart `session_title`](#sessionstart-input).
1428
1429```json theme={null}1429```json theme={null}
1430{1430{
1431 "session_id": "abc123",1431 "session_id": "abc123",
1448* **Stdout di testo semplice**: Claude Code aggiunge stdout che [tratta come testo semplice](#exit-code-0) al contesto di Claude1448* **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 contesto1449* **JSON con `additionalContext`**: usa il formato JSON sottostante per più controllo. Il campo `additionalContext` viene aggiunto come contesto
1450 1450
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).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 [debug log](#debug-hooks).
1452 1452
1453Per bloccare un prompt, restituisci un oggetto JSON con `decision` impostato su `"block"`:1453Per bloccare un prompt, restituisci un oggetto JSON con `decision` impostato su `"block"`:
1454 1454
1455| Campo | Descrizione |1455| Campo | Descrizione |
1456| :- | :- |1456| :- | :- |
1457| `decision` | `"block"` impedisce l'elaborazione del prompt e lo cancella dal contesto. Ometti per consentire al prompt di procedere |1457| `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 |1458| `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) |1459| `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 |1460| `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 |1461| `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 1462
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.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.
1464 1464
1469 "hookSpecificOutput": {1469 "hookSpecificOutput": {
1470 "hookEventName": "UserPromptSubmit",1470 "hookEventName": "UserPromptSubmit",
1471 "additionalContext": "My additional context here",1471 "additionalContext": "My additional context here",
1472 "sessionTitle": "My session title"1472 "sessionTitle": "My session title",
1473 "suppressOriginalPrompt": true
1473 }1474 }
1474}1475}
1475```1476```
1476 1477
1478<h4 id="what-a-blocked-prompt-leaves-behind">
1479 Cosa lascia dietro un prompt bloccato
1480</h4>
1481
1482Un 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.
1483
1484`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).
1485
1477<h3 id="userpromptexpansion">1486<h3 id="userpromptexpansion">
1478 UserPromptExpansion1487 UserPromptExpansion
1479</h3>1488</h3>
1480 1489
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`.1490Si 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 1491
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.1492Questo 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 1493
1485Corrisponde a `command_name`. Lascia il matcher vuoto per attivarsi su ogni comando di tipo prompt.1494Corrisponde su `command_name`. Lascia il matcher vuoto per eseguire su ogni comando di tipo prompt.
1486 1495
1487<h4 id="userpromptexpansion-input">1496<h4 id="userpromptexpansion-input">
1488 Input UserPromptExpansion1497 Input UserPromptExpansion
1513 1522
1514| Campo | Descrizione |1523| Campo | Descrizione |
1515| :- | :- |1524| :- | :- |
1516| `decision` | `"block"` impedisce l'espansione del comando. Ometti per consentire al comando di procedere |1525| `decision` | `"block"` impedisce al comando di espandersi. Ometti per consentirgli di procedere |
1517| `reason` | Mostrato all'utente quando `decision` è `"block"` |1526| `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) |1527| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt espanso. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |
1519 1528
1534 MessageDisplay1543 MessageDisplay
1535</h3>1544</h3>
1536 1545
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.1546Si 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 1547
1539Usa MessageDisplay per:1548Usa MessageDisplay per:
1540 1549
1541* rimuovere il markdown per una visualizzazione minima1550* rimuovere markdown per una visualizzazione minima
1542* trasformare il testo che un'applicazione Agent SDK mostra ai suoi utenti1551* trasformare il testo che un'applicazione Agent SDK mostra ai suoi utenti
1543* redarre chiavi API o nomi host interni dalle risposte di Claude1552* redarre chiavi API o nomi host interni dalle risposte di Claude
1544 1553
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.1554Claude 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 1555
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.1556MessageDisplay è 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 1557
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.1558MessageDisplay 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 1559
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à.1560Nelle 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 1561
1553<h4 id="messagedisplay-input">1562<h4 id="messagedisplay-input">
1554 Input MessageDisplay1563 Input MessageDisplay
1559| Campo | Descrizione |1568| Campo | Descrizione |
1560| :- | :- |1569| :- | :- |
1561| `turn_id` | UUID del turno corrente |1570| `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 |1571| `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 |1572| `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 |1573| `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 |1574| `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 1575
1567```json theme={null}1576```json theme={null}
1568{1577{
1672 PreToolUse1681 PreToolUse
1673</h3>1682</h3>
1674 1683
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).1684Si 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 1685
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.1686Per 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 1687
1679<Warning>1688<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.1689 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 1690
1682 PreToolUse inoltre non si attiva per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).1691 PreToolUse inoltre non si esegue per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).
1683</Warning>1692</Warning>
1684 1693
1685Usa il [controllo decisionale PreToolUse](#pretooluse-decision-control) per consentire, negare, chiedere, o differire la chiamata dello strumento.1694Usa [Controllo decisionale PreToolUse](#pretooluse-decision-control) per consentire, negare, chiedere, o differire la chiamata dello strumento.
1686 1695
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.1696Un [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 1697
1734 1743
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.1744Quando 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 1745
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.1746Il 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 1747
1739<Note>1748<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.1749 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>1750</Note>
1742 1751
1743`changedFiles` e `files` elencano ciò che il comando ha cambiato; i campi rimanenti dicono quanto è completo e quanto è affidabile quell'elenco.1752`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` |1758| `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 |1759| `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 |1760| `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 |1761| `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 1762
1754<a id="powershell" />1763<a id="powershell" />
1755 1764
1768| `timeout` | number | `120000` | Timeout facoltativo in millisecondi |1777| `timeout` | number | `120000` | Timeout facoltativo in millisecondi |
1769| `run_in_background` | boolean | `false` | Se eseguire il comando in background |1778| `run_in_background` | boolean | `false` | Se eseguire il comando in background |
1770 1779
1771Corrisponde a `Bash|PowerShell` negli hook che ispezionano i comandi shell, in modo che coprano entrambi gli strumenti:1780Corrisponde a `Bash|PowerShell` negli hook che ispezionano i comandi shell, quindi coprono entrambi gli strumenti:
1772 1781
1773* Su Windows, ovunque lo strumento PowerShell sia abilitato, Claude tratta PowerShell come la shell primaria e instrada i comandi shell attraverso di esso.1782* 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.1783* 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ì.1784* Un hook che corrisponde solo a `Bash` non si esegue mai lì.
1776 1785
1777<h5 id="write">1786<h5 id="write">
1778 Write1787 Write
1802 Read1811 Read
1803</h5>1812</h5>
1804 1813
1805Legge il contenuto dei file.1814Legge i contenuti del file.
1806 1815
1807| Campo | Tipo | Esempio | Descrizione |1816| Campo | Tipo | Esempio | Descrizione |
1808| :- | :- | :- | :- |1817| :- | :- | :- | :- |
1825 Grep1834 Grep
1826</h5>1835</h5>
1827 1836
1828Cerca il contenuto dei file con espressioni regolari.1837Cerca i contenuti dei file con espressioni regolari.
1829 1838
1830| Campo | Tipo | Esempio | Descrizione |1839| Campo | Tipo | Esempio | Descrizione |
1831| :- | :- | :- | :- |1840| :- | :- | :- | :- |
1832| `pattern` | string | `"TODO.*fix"` | Modello di espressione regolare da cercare |1841| `pattern` | string | `"TODO.*fix"` | Modello di espressione regolare da cercare |
1833| `path` | string | `"/path/to/dir"` | File o directory facoltativa da cercare |1842| `path` | string | `"/path/to/dir"` | File o directory facoltativo da cercare |
1834| `glob` | string | `"*.ts"` | Modello glob facoltativo per filtrare i file |1843| `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"` |1844| `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 |1845| `-i` | boolean | `true` | Ricerca senza distinzione tra maiuscole e minuscole |
1837| `multiline` | boolean | `false` | Abilita la corrispondenza multiriga |1846| `multiline` | boolean | `false` | Abilita la corrispondenza multilinea |
1838 1847
1839<h5 id="webfetch">1848<h5 id="webfetch">
1840 WebFetch1849 WebFetch
1870| `prompt` | string | `"Find all API endpoints"` | L'attività per l'agente da eseguire |1879| `prompt` | string | `"Find all API endpoints"` | L'attività per l'agente da eseguire |
1871| `description` | string | `"Find API endpoints"` | Breve descrizione dell'attività |1880| `description` | string | `"Find API endpoints"` | Breve descrizione dell'attività |
1872| `subagent_type` | string | `"Explore"` | Tipo di agente specializzato da usare |1881| `subagent_type` | string | `"Explore"` | Tipo di agente specializzato da usare |
1873| `model` | string | `"sonnet"` | Alias del modello facoltativo per sovrascrivere il predefinito |1882| `model` | string | `"sonnet"` | Alias di modello facoltativo per sovrascrivere il predefinito |
1874 1883
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:1884Quando 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 1885
1877| Campo | Tipo | Esempio | Descrizione |1886| Campo | Tipo | Esempio | Descrizione |
1878| :- | :- | :- | :- |1887| :- | :- | :- | :- |
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"` |1888| `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 |1889| `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 |1890| `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 |1891| `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 |1892| `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 |1893| `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 |1894| `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 |1895| `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` |1896| `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 1897
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`.1898Su 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 1899
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`.1900Per 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 1901
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.1902Su 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 1903
1895<a id="askuserquestion" />1904<a id="askuserquestion" />
1896 1905
1903| Campo | Tipo | Esempio | Descrizione |1912| Campo | Tipo | Esempio | Descrizione |
1904| :- | :- | :- | :- |1913| :- | :- | :- | :- |
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 |1914| `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 |1915| `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 1916
1908<h5 id="exitplanmode">1917<h5 id="exitplanmode">
1909 ExitPlanMode1918 ExitPlanMode
1915| :- | :- | :- | :- |1924| :- | :- | :- | :- |
1916| `plan` | string | `"## Refactor auth\n1. Extract..."` | Contenuto del piano in Markdown. Iniettato dal file del piano su disco |1925| `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 |1926| `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 |1927| `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 1928
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.1929In `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 1930
1922<h4 id="pretooluse-decision-control">1931<h4 id="pretooluse-decision-control">
1923 Controllo decisionale PreToolUse1932 Controllo decisionale PreToolUse
1924</h4>1933</h4>
1925 1934
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.1935Gli 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 1936
1928| Campo | Descrizione |1937| Campo | Descrizione |
1929| :- | :- |1938| :- | :- |
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 |1939| `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 |1940| `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 |1941| `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) |1942| `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 1943
1938 1947
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.1948Quando 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 1949
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.1950Un `"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 1951
1943```json theme={null}1952```json theme={null}
1944{1953{
1956 1965
1957<span id="allow-with-updatedinput" />1966<span id="allow-with-updatedinput" />
1958 1967
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.1968In [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 1969
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.1970A 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 1971
1963<Note>1972<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.1973 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>1974</Note>
1966 1975
1967<h4 id="defer-a-tool-call-for-later">1976<h4 id="defer-a-tool-call-for-later">
1970 1979
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.1980`"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 1981
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ì:1982Lo 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 1983
19751. Claude chiama `AskUserQuestion`. L'hook `PreToolUse` si attiva.19841. 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.19852. 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.19863. 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.19874. 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.19885. L'hook restituisce `permissionDecision: "allow"` con la risposta in `updatedInput`. Lo strumento si esegue e Claude continua.
1980 1989
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:1990Il 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}2003}
1995```2004```
1996 2005
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.2006Non 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 2007
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.2008`"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 2009
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.2010Se 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 2011
2003<Note>2012<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.2013 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 2014
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).2015 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>2016</Note>
2008 2017
2009<h3 id="permissionrequest">2018<h3 id="permissionrequest">
2011</h3>2020</h3>
2012 2021
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.2022Si 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.2023Usa [Controllo decisionale PermissionRequest](#permissionrequest-decision-control) per consentire o negare per conto dell'utente.
2015 2024
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.2025Usa 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 2026
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`.2027Claude 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 2028
2020Corrisponde al nome dello strumento, gli stessi valori di PreToolUse.2029Corrisponde al nome dello strumento, stessi valori di PreToolUse.
2021 2030
2022<h4 id="permissionrequest-input">2031<h4 id="permissionrequest-input">
2023 Input PermissionRequest2032 Input PermissionRequest
2025 2034
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.2035Gli 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 2036
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.2037L'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 2038
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).2039Gli 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 2040
2032```json theme={null}2041```json theme={null}
2033{2042{
2086 Voci di aggiornamento di permesso2095 Voci di aggiornamento di permesso
2087</h4>2096</h4>
2088 2097
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.2098Sia 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 2099
2091| `type` | Campi | Effetto |2100| `type` | Campi | Effetto |
2092| :- | :- | :- |2101| :- | :- | :- |
2103 `bypassPermissions` non viene mai persistito come `defaultMode` indipendentemente da `destination`.2112 `bypassPermissions` non viene mai persistito come `defaultMode` indipendentemente da `destination`.
2104</Note>2113</Note>
2105 2114
2106Il campo `destination` su ogni voce determina se il cambiamento rimane in memoria o persiste in un file di impostazioni.2115Il campo `destination` su ogni voce determina se il cambio rimane in memoria o persiste in un file di impostazioni.
2107 2116
2108| `destination` | Scrive su |2117| `destination` | Scrive in |
2109| :- | :- |2118| :- | :- |
2110| `session` | solo in memoria, scartato quando la sessione termina |2119| `session` | solo in memoria, scartato quando la sessione termina |
2111| `localSettings` | `.claude/settings.local.json` |2120| `localSettings` | `.claude/settings.local.json` |
2118 PostToolUse2127 PostToolUse
2119</h3>2128</h3>
2120 2129
2121Si esegue immediatamente dopo che uno strumento si completa con successo.2130Si esegue immediatamente dopo che uno strumento completa con successo.
2122 2131
2123Corrisponde al nome dello strumento, gli stessi valori di PreToolUse.2132Corrisponde al nome dello strumento, stessi valori di PreToolUse.
2124 2133
2125Corrisponde più ampiamente quando il nome dello strumento non è il filtro giusto:2134Corrisponde più ampiamente quando il nome dello strumento non è il filtro giusto:
2126 2135
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).2136* 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.2137* 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 2138
2130<h4 id="posttooluse-input">2139<h4 id="posttooluse-input">
2131 Input PostToolUse2140 Input PostToolUse
2132</h4>2141</h4>
2133 2142
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).2143Gli 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 2144
2136```json theme={null}2145```json theme={null}
2137{2146{
2191```2200```
2192 2201
2193<Warning>2202<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.2203 `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 2204
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.2205 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>2206</Warning>
2198 2207
2199<h4 id="annotate-a-result-for-the-auto-mode-classifier">2208<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2216Quanto peso il classificatore dà alla nota dipende da dove hai configurato l'hook:2225Quanto peso il classificatore dà alla nota dipende da dove hai configurato l'hook:
2217 2226
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 conversazione2227* **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 verificata2228* **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 2229
2221Claude Code applica questi limiti quando consegna la nota:2230Claude Code applica questi limiti quando consegna la nota:
2222 2231
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 chiamata2232* **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 strumento2233* **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 chiamate2234* **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'output2235* **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 2236
2228<Warning>2237<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.2238 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 PostToolUseFailure2242 PostToolUseFailure
2234</h3>2243</h3>
2235 2244
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.2245Si 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 2246
2238Corrisponde al nome dello strumento, gli stessi valori di PreToolUse.2247Corrisponde al nome dello strumento, stessi valori di PreToolUse.
2239 2248
2240<Note>2249<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).2250 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>2251</Note>
2243 2252
2244<h4 id="posttoolusefailure-input">2253<h4 id="posttoolusefailure-input">
2269| Campo | Descrizione |2278| Campo | Descrizione |
2270| :- | :- |2279| :- | :- |
2271| `error` | Stringa che descrive cosa è andato male. Il formato dipende dallo strumento che ha fallito |2280| `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 |2281| `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 |2282| `duration_ms` | Facoltativo. Tempo di esecuzione dello strumento in millisecondi. Esclude il tempo trascorso nei prompt di permesso e negli hook PreToolUse |
2274 2283
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.2284La 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 2285
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 intercalati2286* 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 stesso2287* 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`2288* 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 2289
2281<h4 id="posttoolusefailure-decision-control">2290<h4 id="posttoolusefailure-decision-control">
2301 PostToolBatch2310 PostToolBatch
2302</h3>2311</h3>
2303 2312
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.2313Si 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 2314
2306<h4 id="posttoolbatch-input">2315<h4 id="posttoolbatch-input">
2307 Input PostToolBatch2316 Input PostToolBatch
2333}2342}
2334```2343```
2335 2344
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.2345`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 2346
2338<Note>2347<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.2348 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}2367}
2359```2368```
2360 2369
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.2370Restituire `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 2371
2363<h3 id="permissiondenied">2372<h3 id="permissiondenied">
2364 PermissionDenied2373 PermissionDenied
2365</h3>2374</h3>
2366 2375
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.2376Si 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 2377
2369Corrisponde al nome dello strumento, gli stessi valori di PreToolUse.2378Corrisponde al nome dello strumento, stessi valori di PreToolUse.
2370 2379
2371<h4 id="permissiondenied-input">2380<h4 id="permissiondenied-input">
2372 Input PermissionDenied2381 Input PermissionDenied
2399 Controllo decisionale PermissionDenied2408 Controllo decisionale PermissionDenied
2400</h4>2409</h4>
2401 2410
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`:2411Gli 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 2412
2404```json theme={null}2413```json theme={null}
2405{2414{
2410}2419}
2411```2420```
2412 2421
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.2422Quando `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 2423
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.2424Claude 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 2425
2417<h3 id="notification">2426<h3 id="notification">
2418 Notification2427 Notification
2420 2429
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.2430Si 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 2431
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.2432Ricevi 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 2433
2425| Matcher | Quando si attiva |2434| Matcher | Quando si attiva |
2426| :- | :- |2435| :- | :- |
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 |2436| `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 |2437| `idle_prompt` | Claude ha finito di rispondere circa 60 secondi fa e non hai digitato da allora |
2429| `auth_success` | L'autenticazione si completa |2438| `auth_success` | L'autenticazione completa |
2430| `elicitation_dialog` | Un server MCP apre un modulo di elicitazione e non hai digitato per circa sei secondi |2439| `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 |2440| `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 |2441| `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 |2442| `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 |2443| `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 |2444| `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) |2445| `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 |2446| `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** |2447| `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 2448
2440I tipi `agent_needs_input` e `agent_completed` richiedono Claude Code v2.1.198 o successivo.2449I tipi `agent_needs_input` e `agent_completed` richiedono Claude Code v2.1.198 o successivo.
2441 2450
2442I tipi `quota_auto_resume_fired`, `quota_auto_resume_stale`, e `quota_auto_resume_disabled` richiedono Claude Code v2.1.234 o successivo.2451I tipi `quota_auto_resume_fired`, `quota_auto_resume_stale`, e `quota_auto_resume_disabled` richiedono Claude Code v2.1.234 o successivo.
2443 2452
2444Nelle sessioni di terminale, `permission_prompt` per la richiesta di rete di un comando in sandbox richiede Claude Code v2.1.246 o successivo.2453Nelle sessioni di terminale, `permission_prompt` per la richiesta di rete di un comando sandboxed richiede Claude Code v2.1.246 o successivo.
2445 2454
2446`agent_needs_input` per la domanda di configurazione del terminale di un compagno di squadra richiede Claude Code v2.1.248 o successivo.2455`agent_needs_input` per una domanda di configurazione del terminale del compagno di squadra richiede Claude Code v2.1.248 o successivo.
2447 2456
2448<Note>2457<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:2458 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 2459
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.2460 * 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.2461 * 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.2462 * 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 2463
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.2464 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:2467Claude 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 2468
2460* Aspettati `permission_prompt` circa sei secondi dopo che Claude chiede il permesso. Claude Code non lo rinvia mentre digiti.2469* Aspettati `permission_prompt` circa sei secondi dopo che Claude chiede il permesso. Claude Code non lo rinvia mentre digiti.
2461* Se tu o un hook [PermissionRequest](#permissionrequest) rispondi prima, Claude Code non esegue `permission_prompt`.2470* 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.2471* Imposta [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/it/env-vars) su `1` per disattivare `permission_prompt` in queste sessioni.
2463 2472
2464Prima della v2.1.233, `permission_prompt` non si attivava in queste sessioni.2473Prima della v2.1.233, `permission_prompt` non si eseguiva in queste sessioni.
2465 2474
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:2475Usa 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 2476
2468```json theme={null}2477```json theme={null}
2469{2478{
2496 Input Notification2505 Input Notification
2497</h4>2506</h4>
2498 2507
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.2508Oltre ai [campi di input comuni](#common-input-fields), gli hook Notification ricevono `message` con il testo della notifica, un `title` facoltativo, e `notification_type` che indica quale tipo si è eseguito.
2500 2509
2501```json theme={null}2510```json theme={null}
2502{2511{
2516 SubagentStart2525 SubagentStart
2517</h3>2526</h3>
2518 2527
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.2528Si 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 2529
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$`.2530Per 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 2531
2523<h4 id="subagentstart-input">2532<h4 id="subagentstart-input">
2524 Input SubagentStart2533 Input SubagentStart
2525</h4>2534</h4>
2526 2535
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.2536Oltre 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 2537
2529```json theme={null}2538```json theme={null}
2530{2539{
2552}2561}
2553```2562```
2554 2563
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.2564Quando 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 2565
2557<h3 id="subagentstop">2566<h3 id="subagentstop">
2558 SubagentStop2567 SubagentStop
2559</h3>2568</h3>
2560 2569
2561Si esegue quando un subagente di Claude Code ha finito di rispondere. Corrisponde al tipo di agente, gli stessi valori di SubagentStart.2570Si esegue quando un subagente di Claude Code ha finito di rispondere. Corrisponde al tipo di agente, stessi valori di SubagentStart.
2562 2571
2563<h4 id="subagentstop-input">2572<h4 id="subagentstop-input">
2564 Input SubagentStop2573 Input SubagentStop
2565</h4>2574</h4>
2566 2575
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.2576Oltre ai [campi di input comuni](#common-input-fields), gli hook SubagentStop ricevono `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path`, e `last_assistant_message`. Il campo `agent_type` è il valore usato per il 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 2577
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.2578Non 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 2579
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.2580Un `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 2581
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`.2582Su 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 2583
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.2584Gli 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 2585
2591}2600}
2592```2601```
2593 2602
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.2603Gli 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 2604
2596<h3 id="taskcreated">2605<h3 id="taskcreated">
2597 TaskCreated2606 TaskCreated
2598</h3>2607</h3>
2599 2608
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.2609Si 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 2610
2602Gli hook TaskCreated non supportano i matcher e si attivano su ogni occorrenza.2611Gli hook TaskCreated non supportano i matcher e si eseguono su ogni occorrenza.
2603 2612
2604<h4 id="taskcreated-input">2613<h4 id="taskcreated-input">
2605 Input TaskCreated2614 Input TaskCreated
2606</h4>2615</h4>
2607 2616
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`.2617Oltre ai [campi di input comuni](#common-input-fields), gli hook TaskCreated ricevono `task_id`, `task_subject`, e facoltativamente `task_description`, `teammate_name`, e `team_name`.
2609 2618
2610```json theme={null}2619```json theme={null}
2611{2620{
2625| :- | :- |2634| :- | :- |
2626| `task_id` | Identificatore dell'attività in fase di creazione |2635| `task_id` | Identificatore dell'attività in fase di creazione |
2627| `task_subject` | Titolo dell'attività |2636| `task_subject` | Titolo dell'attività |
2628| `task_description` | Descrizione dettagliata dell'attività. Potrebbe essere assente |2637| `task_description` | Descrizione dettagliata dell'attività. Può essere assente |
2629| `teammate_name` | Nome del compagno di squadra che crea l'attività. Potrebbe essere assente |2638| `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 |2639| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |
2631 2640
2632<h4 id="taskcreated-decision-control">2641<h4 id="taskcreated-decision-control">
2657 TaskCompleted2666 TaskCompleted
2658</h3>2667</h3>
2659 2668
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.2669Si 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 2670
2662Gli hook TaskCompleted non supportano i matcher e si attivano su ogni occorrenza.2671Gli hook TaskCompleted non supportano i matcher e si eseguono su ogni occorrenza.
2663 2672
2664<h4 id="taskcompleted-input">2673<h4 id="taskcompleted-input">
2665 Input TaskCompleted2674 Input TaskCompleted
2666</h4>2675</h4>
2667 2676
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`.2677Oltre ai [campi di input comuni](#common-input-fields), gli hook TaskCompleted ricevono `task_id`, `task_subject`, e facoltativamente `task_description`, `teammate_name`, e `team_name`.
2669 2678
2670```json theme={null}2679```json theme={null}
2671{2680{
2686| :- | :- |2695| :- | :- |
2687| `task_id` | Identificatore dell'attività in fase di completamento |2696| `task_id` | Identificatore dell'attività in fase di completamento |
2688| `task_subject` | Titolo dell'attività |2697| `task_subject` | Titolo dell'attività |
2689| `task_description` | Descrizione dettagliata dell'attività. Potrebbe essere assente |2698| `task_description` | Descrizione dettagliata dell'attività. Può essere assente |
2690| `teammate_name` | Nome del compagno di squadra che completa l'attività. Potrebbe essere assente |2699| `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 |2700| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |
2692 2701
2693<h4 id="taskcompleted-decision-control">2702<h4 id="taskcompleted-decision-control">
2719 Stop2728 Stop
2720</h3>2729</h3>
2721 2730
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.2731Si esegue quando l'agente Claude Code principale ha finito di rispondere. Non si esegue se l'arresto è av venuto a causa di un'interruzione dell'utente. Gli errori API eseguono [StopFailure](#stopfailure) invece.
2723 2732
2724<Tip>2733<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.2734 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>2735</Tip>
2727 2736
2728<h4 id="stop-input">2737<h4 id="stop-input">
2731 2740
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).2741Oltre 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 2742
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.2743Il 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 2744
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.2745Gli 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 2746
2738Ogni voce in `background_tasks` descrive un'attività in volo e usa questi campi:2747Ogni voce in `background_tasks` descrive un'attività in volo e usa questi campi:
2739 2748
2741| :- | :- |2750| :- | :- |
2742| `id` | Identificatore dell'attività |2751| `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 |2752| `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à |2753| `status` | Stato dell'attività corrente |
2745| `description` | Descrizione in testo libero, limitata a 1000 caratteri con un marcatore `… [+N chars]` in-stringa quando ritagliato |2754| `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` |2755| `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` |2756| `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 |2810| `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 |2811| `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 2812
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.2813Un 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 2814
2806```json theme={null}2815```json theme={null}
2807{2816{
2810}2819}
2811```2820```
2812 2821
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:2822Usa `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 2823
2815```json theme={null}2824```json theme={null}
2816{2825{
2825 StopFailure2834 StopFailure
2826</h3>2835</h3>
2827 2836
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.2837Si 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 2838
2830<h4 id="stopfailure-input">2839<h4 id="stopfailure-input">
2831 Input StopFailure2840 Input StopFailure
2857 TeammateIdle2866 TeammateIdle
2858</h3>2867</h3>
2859 2868
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.2869Si 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 2870
2862Gli hook TeammateIdle non supportano i matcher e si attivano su ogni occorrenza.2871Gli hook TeammateIdle non supportano i matcher e si eseguono su ogni occorrenza.
2863 2872
2864<h4 id="teammateidle-input">2873<h4 id="teammateidle-input">
2865 Input TeammateIdle2874 Input TeammateIdle
2948 Input ConfigChange2957 Input ConfigChange
2949</h4>2958</h4>
2950 2959
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.2960Oltre 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 2961
2953```json theme={null}2962```json theme={null}
2954{2963{
2965 Controllo decisionale ConfigChange2974 Controllo decisionale ConfigChange
2966</h4>2975</h4>
2967 2976
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.2977Gli 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 2978
2970| Campo | Descrizione |2979| Campo | Descrizione |
2971| :- | :- |2980| :- | :- |
2972| `decision` | `"block"` impedisce l'applicazione del cambiamento di configurazione. Ometti per consentire il cambiamento |2981| `decision` | `"block"` impedisce l'applicazione del cambio di configurazione. Ometti per consentire il cambio |
2973| `reason` | Accettato ma mai mostrato |2982| `reason` | Accettato ma mai mostrato |
2974 2983
2975```json theme={null}2984```json theme={null}
2979}2988}
2980```2989```
2981 2990
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.2991I 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 2992
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.2993Claude 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 2994
2986<h3 id="cwdchanged">2995<h3 id="cwdchanged">
2987 CwdChanged2996 CwdChanged
2988</h3>2997</h3>
2989 2998
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.2999Si 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 3000
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.3001Gli 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 3002
2994CwdChanged non supporta i matcher e si attiva su ogni occorrenza.3003CwdChanged non supporta i matcher e si esegue su ogni occorrenza.
2995 3004
2996<h4 id="cwdchanged-input">3005<h4 id="cwdchanged-input">
2997 Input CwdChanged3006 Input CwdChanged
3020| :- | :- |3029| :- | :- |
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 |3030| `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 3031
3023Gli hook CwdChanged non hanno controllo decisionale. Non possono bloccare il cambiamento di directory.3032Gli hook CwdChanged non hanno controllo decisionale. Non possono bloccare il cambio di directory.
3024 3033
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.3034Claude 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 3035
3030 3039
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.3040Si 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 3041
3033Claude Code non attiva questo evento quando:3042Claude Code non esegue questo evento quando:
3034 3043
3035* Passi una directory con il flag di avvio `--add-dir`; [SessionStart](#sessionstart) copre quelle directory3044* Passi una directory con il flag di avvio `--add-dir`; [SessionStart](#sessionstart) copre quelle directory
3036* Aggiungi una directory sulla scheda Workspace `/permissions`3045* Aggiungi una directory sulla scheda Workspace `/permissions`
3037* Aggiungi una directory che è già una directory di lavoro o dentro una3046* Aggiungi una directory che è già una directory di lavoro o dentro una
3038 3047
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.3048Claude 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 3049
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.3050Claude Code non attende l'hook: l'aggiunta completa immediatamente, e l'hook si esegue in background con il timeout predefinito di 600 secondi.
3042 3051
3043Il matcher filtra su come la directory è stata aggiunta:3052Il matcher filtra su come la directory è stata aggiunta:
3044 3053
3071 3080
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:3081Gli 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 3082
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 debug3083* `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 solo3084* `register_repo_root`: Claude Code scrive l'output `systemMessage` e l'output di fallimento nel debug log solo
3076 3085
3077<h3 id="filechanged">3086<h3 id="filechanged">
3078 FileChanged3087 FileChanged
3079</h3>3088</h3>
3080 3089
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.3090Si 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 3091
3083Il `matcher` per questo evento serve due ruoli:3092Il `matcher` per questo evento serve due ruoli:
3084 3093
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`.3094* **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.3095* **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 3096
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:3097Questo 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 3098
3090```json theme={null}3099```json theme={null}
3091{3100{
3105}3114}
3106```3115```
3107 3116
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:3117L'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 3118
3110```bash theme={null}3119```bash theme={null}
3111#!/bin/bash3120#!/bin/bash
3117 3126
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.3127Per 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 3128
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 `*`.3129Per 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 3130
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.3131Gli 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 3132
3124<h4 id="filechanged-input">3133<h4 id="filechanged-input">
3125 Input FileChanged3134 Input FileChanged
3147 Output FileChanged3156 Output FileChanged
3148</h4>3157</h4>
3149 3158
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:3159Oltre 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 3160
3152| Campo | Descrizione |3161| Campo | Descrizione |
3153| :- | :- |3162| :- | :- |
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 |3163| `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 3164
3156Gli hook FileChanged non hanno controllo decisionale. Non possono bloccare il cambiamento del file dall'occorrenza.3165Gli hook FileChanged non hanno controllo decisionale. Non possono bloccare il cambio del file dal verificarsi.
3157 3166
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.3167Claude 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 3168
3163 3172
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.3173Si 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 3174
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.3175Poiché 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 3176
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.3177L'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 3178
3179Claude Code agisce sul successo dell'hook e sul percorso restituito, e scarta `systemMessage` e `continue`.
3180
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:3181Questo 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 3182
3172```json theme={null}3183```json theme={null}
3186}3197}
3187```3198```
3188 3199
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.3200L'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 3201
3191<h4 id="worktreecreate-input">3202<h4 id="worktreecreate-input">
3192 Input WorktreeCreate3203 Input WorktreeCreate
3208 Output WorktreeCreate3219 Output WorktreeCreate
3209</h4>3220</h4>
3210 3221
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:3222Gli 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 3223
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.3224* **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.3225* **Hook HTTP** (`type: "http"`): restituisci `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` nel corpo della risposta.
3215 3226
3216Se l'hook fallisce o non produce un percorso, la creazione del worktree fallisce con un errore.3227Se l'hook fallisce o non produce alcun percorso, la creazione del worktree fallisce con un errore.
3217 3228
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.3229Claude 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 3230
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.3231Claude 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 3232
3222<h3 id="worktreeremove">3233<h3 id="worktreeremove">
3223 WorktreeRemove3234 WorktreeRemove
3224</h3>3235</h3>
3225 3236
3226Si esegue quando un worktree viene rimosso. Questo è la controparte di pulizia di [WorktreeCreate](#worktreecreate). L'evento si attiva quando:3237Si esegue quando un worktree viene rimosso. Questo è il contrapparte di pulizia di [WorktreeCreate](#worktreecreate). L'evento si esegue quando:
3227 3238
3228* esci da una sessione `--worktree` e scegli di rimuoverla3239* esci da una sessione `--worktree` e scegli di rimuoverla
3229* un subagente con `isolation: "worktree"` finisce3240* un subagente con `isolation: "worktree"` finisce
3231 3242
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:3243Per 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 3244
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.3245* **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.3246* **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).3247* **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 3248
3239 3250
3240Claude Code scarta i [campi di output JSON](#json-output) di un hook WorktreeRemove, come `systemMessage` e `continue`.3251Claude Code scarta i [campi di output JSON](#json-output) di un hook WorktreeRemove, come `systemMessage` e `continue`.
3241 3252
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.3253Per 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 3254
3244Claude Code passa il percorso restituito da WorktreeCreate come `worktree_path` nell'input dell'hook. Questo esempio legge quel percorso e rimuove la directory:3255Claude Code passa il percorso restituito da WorktreeCreate come `worktree_path` nell'input dell'hook. Questo esempio legge quel percorso e rimuove la directory:
3245 3256
3278 3289
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:3290Il 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 3291
3281* Il worktree rimane su disco, e il comando dell'hook e stderr vanno al [log di debug](#debug-hooks).3292* 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.3293* 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 3294
3284<h3 id="precompact">3295<h3 id="precompact">
3296 3307
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"`.3308Esci 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 3309
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.3310Bloccare 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 3311
3301Claude Code scarta i campi `systemMessage` e `continue` di un hook PreCompact.3312Claude Code scarta i campi `systemMessage` e `continue` di un hook PreCompact.
3302 3313
3353 PreModelSwitch3364 PreModelSwitch
3354</h3>3365</h3>
3355 3366
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.3367Si 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 3368
3358PreModelSwitch richiede Claude Code v2.1.251 o successivo. Claude Code lo esegue per queste richieste:3369PreModelSwitch richiede Claude Code v2.1.251 o successivo. Claude Code lo esegue per queste richieste:
3359 3370
3360* `/model <name>` e il selettore `/model`3371* `/model <name>` e il picker `/model`
3361* Il selettore del modello `Option+P` o `Alt+P`3372* Il picker del modello `Option+P` o `Alt+P`
3362* L'impostazione Model in `/config`3373* L'impostazione Model in `/config`
3363* Attivare la [modalità veloce](/docs/it/fast-mode) quando questo cambia il modello della sessione3374* 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)3375* 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 3376
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.3377Claude 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 3378
3441 Input PreModelSwitch3452 Input PreModelSwitch
3442</h4>3453</h4>
3443 3454
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.3455Oltre 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 3456
3446| Campo | Tipo | Descrizione |3457| Campo | Tipo | Descrizione |
3447| :- | :- | :- |3458| :- | :- | :- |
3448| `from_model` | string | ID del modello da cui il cambio cambia |3459| `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 |3460| `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 |3461| `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 |3462| `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 |3463| `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 |3464| `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"` |3465| `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 |3466| `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 |3467| `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 3468
3458Questo esempio mostra l'input per `/model opus` in una sessione che esegue Sonnet 5:3469Questo esempio mostra l'input per `/model opus` in una sessione che esegue Sonnet 5:
3506 3517
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.3518Claude 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 3519
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.3520Un 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 3521
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).3522Un 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 3523
3513<h3 id="postmodelswitch">3524<h3 id="postmodelswitch">
3514 PostModelSwitch3525 PostModelSwitch
3547}3558}
3548```3559```
3549 3560
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.3561Per 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 3562
3552<h4 id="postmodelswitch-input">3563<h4 id="postmodelswitch-input">
3553 Input PostModelSwitch3564 Input PostModelSwitch
3554</h4>3565</h4>
3555 3566
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.3567Gli 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 3568
3558`requested_model` è `null` quando `source` è `"auto"`. Quando `source` è `"resume"`, è l'impostazione del modello salvato che Claude Code ha ripristinato.3569`requested_model` è `null` quando `source` è `"auto"`. Quando `source` è `"resume"`, è l'impostazione del modello salvato che Claude Code ha ripristinato.
3559 3570
3561 Controllo decisionale PostModelSwitch3572 Controllo decisionale PostModelSwitch
3562</h4>3573</h4>
3563 3574
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:3575Claude 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 3576
3566| Campo | Descrizione |3577| Campo | Descrizione |
3567| :- | :- |3578| :- | :- |
3568| `additionalContext` | Stringa aggiunta al contesto di Claude con la richiesta successiva. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |3579| `additionalContext` | Stringa aggiunta al contesto di Claude con la richiesta successiva. Vedi [Aggiungi contesto per Claude](#add-context-for-claude) |
3569 3580
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.3581Se 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 3582
3572<h3 id="sessionend">3583<h3 id="sessionend">
3573 SessionEnd3584 SessionEnd
3574</h3>3585</h3>
3575 3586
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.3587Si 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 3588
3578Il campo `reason` nell'input dell'hook indica perché la sessione è terminata:3589Il campo `reason` nell'input dell'hook indica perché la sessione è terminata:
3579 3590
3584| `logout` | L'utente ha effettuato il logout |3595| `logout` | L'utente ha effettuato il logout |
3585| `prompt_input_exit` | L'utente è uscito mentre l'input del prompt era visibile |3596| `prompt_input_exit` | L'utente è uscito mentre l'input del prompt era visibile |
3586| `other` | Altri motivi di uscita |3597| `other` | Altri motivi di uscita |
3587| `bypass_permissions_disabled` | Rimosso nella v2.1.234; Claude Code non lo invia. Rimuovilo dai tuoi matcher `SessionEnd` |3598| `bypass_permissions_disabled` | Rimosso nella v2.1.234; Claude Code non lo invia. Eliminalo dai tuoi matcher `SessionEnd` |
3588 3599
3589<h4 id="sessionend-input">3600<h4 id="sessionend-input">
3590 Input SessionEnd3601 Input SessionEnd
3629 Input Elicitation3640 Input Elicitation
3630</h4>3641</h4>
3631 3642
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`.3643Oltre 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 3644
3634Per l'elicitazione in modalità modulo, il caso più comune:3645Per l'elicitazione in modalità modulo, il caso più comune:
3635 3646
3697 ElicitationResult3708 ElicitationResult
3698</h3>3709</h3>
3699 3710
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.3711Si 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 3712
3702Il campo matcher corrisponde al nome del server MCP.3713Il campo matcher corrisponde al nome del server MCP.
3703 3714
3705 Input ElicitationResult3716 Input ElicitationResult
3706</h4>3717</h4>
3707 3718
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`.3719Oltre 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 3720
3710```json theme={null}3721```json theme={null}
3711{3722{
