827 827
828Il codice di uscita del tuo hook dice a Claude Code se continuare con l'azione che ha attivato l'hook, come una chiamata a uno strumento o un prompt. Un'esecuzione che termina ha uno di tre risultati:828Il codice di uscita del tuo hook dice a Claude Code se continuare con l'azione che ha attivato l'hook, come una chiamata a uno strumento o un prompt. Un'esecuzione che termina ha uno di tre risultati:
829 829
830* **Successo**: il tuo hook esce con 0. Claude Code applica tutti i campi di [output JSON](#json-output) che il tuo hook ha stampato, e l'azione procede a meno che quei campi non la blocchino o la neghino.830* **Successo**: il tuo hook esce con 0. Claude Code applica tutti i campi di [output JSON](#json-output) che il tuo hook ha stampato, e l'azione procede a meno che quei campi non la blocchino o la neghino. [Hook che avviano un processo in background](#hooks-that-start-a-background-process) descrive l'eccezione.
831* **Errore bloccante**: il tuo hook esce con 2. Sugli [eventi che possono bloccare](#exit-code-2-behavior-per-event), Claude Code interrompe l'azione.831* **Errore bloccante**: il tuo hook esce con 2. Sugli [eventi che possono bloccare](#exit-code-2-behavior-per-event), Claude Code interrompe l'azione.
832* **Errore non bloccante**: il tuo hook esce con qualsiasi altro codice, oppure fallisce in qualche altro modo, ad esempio non avviandosi o stampando JSON non valido. L'azione procede, e su eventi come `PreToolUse` vedi un avviso `<hook name> hook error` nella trascrizione. Se vuoi che un hook fallito blocchi l'azione, imposta [`onFailure: "block"`](#block-the-action-when-a-hook-fails).832* **Errore non bloccante**: il tuo hook esce con qualsiasi altro codice, oppure fallisce in qualche altro modo, ad esempio non avviandosi o stampando JSON non valido. L'azione procede, e su eventi come `PreToolUse` vedi un avviso `<hook name> hook error` nella trascrizione. Se vuoi che un hook fallito blocchi l'azione, imposta [`onFailure: "block"`](#block-the-action-when-a-hook-fails).
833 833
932* Un hook `command`, `http` o `mcp_tool` scaduto non blocca la chiamata allo strumento. La chiamata continua attraverso il normale [flusso dei permessi](/docs/it/permissions), quindi non contare su un hook bloccato perché agisca da controllo. Per bloccare la chiamata quando un hook `command` o `http` va in timeout, imposta [`onFailure: "block"`](#block-the-action-when-a-hook-fails).932* Un hook `command`, `http` o `mcp_tool` scaduto non blocca la chiamata allo strumento. La chiamata continua attraverso il normale [flusso dei permessi](/docs/it/permissions), quindi non contare su un hook bloccato perché agisca da controllo. Per bloccare la chiamata quando un hook `command` o `http` va in timeout, imposta [`onFailure: "block"`](#block-the-action-when-a-hook-fails).
933* Un [hook di callback dell'Agent SDK](/docs/it/agent-sdk/hooks) che supera il suo timeout [blocca la chiamata allo strumento](#pretooluse).933* Un [hook di callback dell'Agent SDK](/docs/it/agent-sdk/hooks) che supera il suo timeout [blocca la chiamata allo strumento](#pretooluse).
934 934
935<h4 id="hooks-that-start-a-background-process">
936 Hook che avviano un processo in background
937</h4>
938
939Se il tuo command hook prende la sua decisione in un processo in background ed esce, un deny che quel processo stampa dopo che Claude Code ha smesso di leggere non blocca la chiamata allo strumento. Per un hook che non è [async](#run-hooks-in-the-background), Claude Code finisce di leggere l'output dell'hook poco dopo l'uscita del processo stesso dell'hook.
940
941Stampa la decisione prima di avviare un processo in background, e reindirizza lo stdout e lo stderr di quel processo. Se il tuo script stampa un allow e poi avvia un processo in background senza reindirizzarne lo stdout e lo stderr, Claude Code blocca la chiamata allo strumento. L'errore dell'hook include `refusing to honor the suspect capture`.
942
943Questo script di hook `PreToolUse` stampa la decisione con `policy-check.sh`, poi carica le metriche in background:
944
945```bash theme={null}
946#!/bin/bash
947"$CLAUDE_PROJECT_DIR"/.claude/hooks/policy-check.sh || exit $?
948"$CLAUDE_PROJECT_DIR"/.claude/hooks/upload-metrics.sh >/dev/null 2>&1 &
949```
950
951Il resto dello script fa quanto segue:
952
953* **`|| exit $?`**: rende il codice di uscita del controllo quello dell'hook stesso, così un controllo che esce con 2 per negare blocca comunque. Altrimenti l'hook esce con il codice dell'ultima riga, che è 0.
954* **`>/dev/null 2>&1 &`**: esegue `upload-metrics.sh` in background con il suo output reindirizzato, così non mantiene aperto l'output dell'hook.
955
956Per provare lo script, fai uscire `policy-check.sh` con 2, poi attiva una chiamata a uno strumento a cui corrisponde l'hook. La chiamata allo strumento viene bloccata.
957
935<h4 id="block-the-action-when-a-hook-fails">958<h4 id="block-the-action-when-a-hook-fails">
936 Bloccare l'azione quando un hook fallisce959 Bloccare l'azione quando un hook fallisce
937</h4>960</h4>
1242Per esempi estesi, tra cui la convalida dei comandi Bash, il filtraggio dei prompt e gli script di approvazione automatica, consulta [What you can automate](/docs/it/hooks-guide#what-you-can-automate) nella guida e l'[implementazione di riferimento del validatore di comandi Bash](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py).1265Per esempi estesi, tra cui la convalida dei comandi Bash, il filtraggio dei prompt e gli script di approvazione automatica, consulta [What you can automate](/docs/it/hooks-guide#what-you-can-automate) nella guida e l'[implementazione di riferimento del validatore di comandi Bash](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py).
1243 1266
1244<h2 id="hook-events">1267<h2 id="hook-events">
1245 Eventi hook1268 Eventi degli hook
1246</h2>1269</h2>
1247 1270
1248Ogni evento corrisponde a un punto del ciclo di vita di Claude Code in cui gli hook possono essere eseguiti. Le sezioni seguenti sono ordinate secondo il ciclo di vita: dalla configurazione della sessione, attraverso il ciclo agentico, fino alla fine della sessione. Ogni sezione descrive quando l'evento viene attivato, quali matcher supporta, l'input JSON che riceve e come controllare il comportamento tramite l'output.1271Ogni evento corrisponde a un punto del ciclo di vita di Claude Code in cui gli hook possono essere eseguiti. Le sezioni seguenti sono ordinate secondo il ciclo di vita: dalla configurazione della sessione, attraverso il ciclo agentico, fino alla fine della sessione. Ogni sezione descrive quando si attiva l'evento, quali matcher supporta, l'input JSON che riceve e come controllare il comportamento tramite l'output.
1249 1272
1250<h3 id="sessionstart">1273<h3 id="sessionstart">
1251 SessionStart1274 SessionStart
1252</h3>1275</h3>
1253 1276
1254Viene eseguito quando Claude Code avvia una nuova sessione o riprende una sessione esistente. È utile per caricare il contesto di sviluppo, come le issue esistenti o le modifiche recenti al tuo codebase, o per impostare le variabili d'ambiente. Per un contesto statico che non richiede uno script, usa invece [CLAUDE.md](/docs/it/memory).1277Viene eseguito quando Claude Code avvia una nuova sessione o riprende una sessione esistente. Utile per caricare contesto di sviluppo come issue esistenti o modifiche recenti al tuo codebase, o per impostare variabili d'ambiente. Per un contesto statico che non richiede uno script, usa invece [CLAUDE.md](/docs/it/memory).
1255 1278
1256SessionStart viene eseguito in ogni sessione, quindi mantieni questi hook veloci. Sono supportati solo gli hook `type: "command"` e `type: "mcp_tool"`. Consulta [Campi degli hook per strumenti MCP](#mcp-tool-hook-fields) per sapere quando vengono eseguiti gli hook `mcp_tool`.1279SessionStart viene eseguito a ogni sessione, quindi mantieni questi hook veloci. Sono supportati solo gli hook `type: "command"` e `type: "mcp_tool"`. Consulta [Campi degli hook di strumenti MCP](#mcp-tool-hook-fields) per sapere quando vengono eseguiti gli hook `mcp_tool`.
1257 1280
1258Il valore del matcher corrisponde al modo in cui è stata avviata la sessione:1281Il valore del matcher corrisponde al modo in cui è stata avviata la sessione:
1259 1282
1260| Matcher | Quando viene attivato |1283| Matcher | Quando si attiva |
1261| :- | :- |1284| :- | :- |
1262| `startup` | Nuova sessione |1285| `startup` | Nuova sessione |
1263| `resume` | `--resume`, `--continue` o `/resume` |1286| `resume` | `--resume`, `--continue` o `/resume` |
1267 1290
1268Prima della v2.1.214, le sessioni derivate riportavano come origine `"resume"`.1291Prima della v2.1.214, le sessioni derivate riportavano come origine `"resume"`.
1269 1292
1270Quando avvii una sessione interattiva, riprendi una conversazione all'avvio con `--continue` o `--resume`, oppure esegui `/clear`, gli hook SessionStart vengono eseguiti in background. Puoi digitare subito, e una conversazione ripresa appare senza attendere gli hook. La prima risposta di Claude attende comunque il completamento degli hook, così il loro contesto raggiunge Claude.1293Quando avvii una sessione interattiva, riprendi una conversazione all'avvio con `--continue` o `--resume`, oppure esegui `/clear`, gli hook SessionStart vengono eseguiti in background. Puoi digitare subito, e una conversazione che hai ripreso appare senza attendere gli hook. La prima risposta di Claude attende comunque che gli hook terminino, così il loro contesto raggiunge Claude.
1271 1294
1272Quando cambi conversazione con `/resume` all'interno di una sessione, il cambio attende invece il completamento degli hook. Se esegui `/clear` o passi a un'altra conversazione mentre gli hook in background sono ancora in esecuzione, nulla di ciò che restituiscono viene applicato alla sessione.1295Quando cambi conversazione con `/resume` all'interno di una sessione, il cambio attende invece che gli hook terminino. Se esegui `/clear` o passi a un'altra conversazione mentre gli hook in background sono ancora in esecuzione, nulla di ciò che restituiscono si applica alla sessione.
1273 1296
1274La stessa attesa si applica all'avvio, anche per una sessione ripresa: un prompt che invii mentre gli hook SessionStart sono ancora in esecuzione non raggiunge Claude finché non terminano.1297La stessa attesa si applica all'avvio, inclusa una sessione ripresa: un prompt che invii mentre gli hook SessionStart sono ancora in esecuzione non raggiunge Claude finché non terminano.
1275 1298
1276Durante entrambe le attese, premi `Esc` per riportare il prompt nell'input senza inviarlo. Gli hook continuano a essere eseguiti.1299Durante entrambe le attese, premi `Esc` per riportare il prompt nell'input senza inviarlo. Gli hook continuano l'esecuzione.
1277 1300
1278<h4 id="sessionstart-input">1301<h4 id="sessionstart-input">
1279 Input di SessionStart1302 Input di SessionStart
1280</h4>1303</h4>
1281 1304
1282Oltre ai [campi di input comuni](#common-input-fields), gli hook SessionStart ricevono `source` e, facoltativamente, `model`, `agent_type` e `session_title`:1305Oltre ai [campi di input comuni](#common-input-fields), gli hook SessionStart ricevono `source` e facoltativamente `model`, `agent_type` e `session_title`:
1283 1306
1284| Campo | Descrizione |1307| Campo | Descrizione |
1285| :- | :- |1308| :- | :- |
1290 1313
1291Una sessione a cui non hai dato un nome può comunque avere un [titolo generato](/docs/it/sessions#name-your-sessions). Quel titolo non è un titolo personalizzato e non appare in `session_title`.1314Una sessione a cui non hai dato un nome può comunque avere un [titolo generato](/docs/it/sessions#name-your-sessions). Quel titolo non è un titolo personalizzato e non appare in `session_title`.
1292 1315
1293Quando `source` è `"resume"` o `"fork"` e la trascrizione contiene almeno una risposta di Claude, gli hook SessionStart ricevono anche i quattro campi seguenti. Il tuo hook può usarli per riportare quanto costa riprendere una conversazione inattiva prima della prima richiesta, ad esempio in un [`systemMessage`](#json-output). Questi campi richiedono Claude Code v2.1.251 o successiva.1316Quando `source` è `"resume"` o `"fork"` e la trascrizione contiene almeno una risposta di Claude, gli hook SessionStart ricevono anche i quattro campi seguenti. Il tuo hook può usarli per segnalare quanto costa riprendere una conversazione datata prima della prima richiesta, ad esempio in un [`systemMessage`](#json-output). Questi campi richiedono Claude Code v2.1.251 o successivo.
1294 1317
1295| Campo | Descrizione |1318| Campo | Descrizione |
1296| :- | :- |1319| :- | :- |
1297| `seconds_since_last_response` | Secondi di tempo reale trascorsi dall'ultima risposta nella trascrizione ripresa |1320| `seconds_since_last_response` | Secondi di tempo reale trascorsi dall'ultima risposta nella trascrizione ripresa |
1298| `context_tokens` | Token che la prima richiesta della sessione ripresa invia di nuovo come prompt |1321| `context_tokens` | Token che la prima richiesta della sessione ripresa reinvia come prompt |
1299| `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 |1322| `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 |
1300| `estimated_cache_write_usd` | Costo stimato in dollari USA per scrivere `context_tokens` nella cache del prompt sul modello della sessione, esclusa la risposta |1323| `estimated_cache_write_usd` | Costo stimato in dollari USA della scrittura di `context_tokens` nella cache del prompt sul modello della sessione, esclusa la risposta |
1301 1324
1302Questo esempio mostra l'input per una sessione ripresa 90 minuti dopo la sua ultima risposta:1325Questo esempio mostra l'input per una sessione ripresa 90 minuti dopo la sua ultima risposta:
1303 1326
1320 Controllo delle decisioni di SessionStart1343 Controllo delle decisioni di SessionStart
1321</h4>1344</h4>
1322 1345
1323Un hook SessionStart può aggiungere contesto per Claude, fornire il primo messaggio dell'utente, impostare il titolo della sessione, monitorare file e ricaricare le skill. Restituisci il campo corrispondente a ciascuna di queste azioni, oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook:1346Un hook SessionStart può aggiungere contesto per Claude, fornire il primo messaggio utente, impostare il titolo della sessione, osservare file e ricaricare le skill. Restituisci il campo per ciascuna di queste azioni, oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook:
1324 1347
1325| Campo | Descrizione |1348| Campo | Descrizione |
1326| :- | :- |1349| :- | :- |
1327| `additionalContext` | Stringa aggiunta al contesto di Claude all'inizio della conversazione, prima del primo prompt. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) per sapere come viene consegnato il testo e cosa inserirvi |1350| `additionalContext` | Stringa aggiunta al contesto di Claude all'inizio della conversazione, prima del primo prompt. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) per sapere come viene consegnato il testo e cosa inserirvi |
1328| `initialUserMessage` | Stringa usata come primo messaggio dell'utente della sessione, in [modalità non interattiva](/docs/it/headless) con il flag `-p`. Diventa il primo turno anche se non passi alcun prompt. Un prompt che passi lo segue come turno successivo |1351| `initialUserMessage` | Stringa usata come primo messaggio utente della sessione, in [modalità non interattiva](/docs/it/headless) con il flag `-p`. Diventa il primo turno anche se non passi alcun prompt. Un prompt che passi segue come turno successivo |
1329| `sessionTitle` | Imposta il titolo della sessione, con lo stesso effetto di `/rename`. Si applica quando `source` è `"startup"`, `"resume"` o `"fork"` |1352| `sessionTitle` | Imposta il titolo della sessione, con lo stesso effetto di `/rename`. Si applica quando `source` è `"startup"`, `"resume"` o `"fork"` |
1330| `watchPaths` | Array di percorsi assoluti da monitorare per gli eventi [FileChanged](#filechanged) durante questa sessione |1353| `watchPaths` | Array di percorsi assoluti da osservare per gli eventi [FileChanged](#filechanged) durante questa sessione |
1331| `reloadSkills` | Booleano. Quando è `true`, Claude Code analizza di nuovo le directory delle [skill](/docs/it/skills) e dei comandi dopo il completamento degli hook SessionStart. Consulta [Ricaricare le skill installate da un hook](#reload-skills-that-a-hook-installs) |1354| `reloadSkills` | Booleano. Quando è `true`, Claude Code riesamina le directory delle [skill](/docs/it/skills) e dei comandi dopo il completamento degli hook SessionStart. Consulta [Ricaricare le skill installate da un hook](#reload-skills-that-a-hook-installs) |
1332 1355
1333Questo output aggiunge contesto e assegna un nome alla sessione:1356Questo output aggiunge contesto e assegna un nome alla sessione:
1334 1357
1342}1365}
1343```1366```
1344 1367
1345Un hook che aggiunge solo contesto può stamparlo senza costruire JSON, perché Claude Code aggiunge lo [stdout in testo semplice](#exit-code-0) di un hook SessionStart al contesto di Claude.1368Un hook che aggiunge solo contesto può stamparlo senza costruire JSON, perché Claude Code aggiunge al contesto di Claude lo [stdout in testo semplice](#exit-code-0) di un hook SessionStart.
1346 1369
1347Se l'hook SessionStart del tuo plugin fornisce `initialUserMessage` o `sessionTitle`, installa il plugin prima dell'avvio della sessione. Claude Code ignora entrambi i campi provenienti da un plugin la cui installazione termina dopo che gli hook SessionStart sono stati eseguiti.1370Se l'hook SessionStart del tuo plugin fornisce `initialUserMessage` o `sessionTitle`, installa il plugin prima dell'avvio della sessione. Claude Code ignora entrambi i campi provenienti da un plugin la cui installazione termina dopo l'esecuzione degli hook SessionStart.
1348 1371
1349<h4 id="reload-skills-that-a-hook-installs">1372<h4 id="reload-skills-that-a-hook-installs">
1350 Ricaricare le skill installate da un hook1373 Ricaricare le skill installate da un hook
1351</h4>1374</h4>
1352 1375
1353Per rendere disponibili nella stessa sessione le skill installate da un hook SessionStart, restituisci `reloadSkills`. Il rilevamento delle skill viene normalmente eseguito prima che gli hook SessionStart terminino, quindi senza questo campo i file che un hook scrive in `~/.claude/skills/` o `.claude/skills/` possono mancare quando viene eseguito il primo prompt.1376Per rendere disponibili nella stessa sessione le skill installate da un hook SessionStart, restituisci `reloadSkills`. Il rilevamento delle skill viene normalmente eseguito prima che gli hook SessionStart terminino, quindi senza di esso i file che un hook scrive in `~/.claude/skills/` o `.claude/skills/` possono mancare quando viene eseguito il primo prompt.
1354 1377
1355Questo esempio sincronizza un repository di skill condiviso e richiede la nuova analisi:1378Questo esempio sincronizza un repository di skill condiviso e richiede il nuovo esame:
1356 1379
1357```bash theme={null}1380```bash theme={null}
1358#!/bin/bash1381#!/bin/bash
1371 1394
1372Gli hook SessionStart hanno accesso alla variabile d'ambiente `CLAUDE_ENV_FILE`, che fornisce un percorso di file in cui puoi rendere persistenti le variabili d'ambiente per i comandi shell che Claude esegue più avanti nella sessione.1395Gli hook SessionStart hanno accesso alla variabile d'ambiente `CLAUDE_ENV_FILE`, che fornisce un percorso di file in cui puoi rendere persistenti le variabili d'ambiente per i comandi shell che Claude esegue più avanti nella sessione.
1373 1396
1374Per impostare singole variabili d'ambiente, scrivi istruzioni `export` in `CLAUDE_ENV_FILE`. Usa l'accodamento (`>>`) per preservare le variabili impostate da altri hook:1397Per impostare singole variabili d'ambiente, scrivi istruzioni `export` in `CLAUDE_ENV_FILE`. Usa l'aggiunta in coda (`>>`) per preservare le variabili impostate da altri hook:
1375 1398
1376```bash theme={null}1399```bash theme={null}
1377#!/bin/bash1400#!/bin/bash
1385exit 01408exit 0
1386```1409```
1387 1410
1388Per catturare tutte le modifiche all'ambiente dai comandi di configurazione, confronta le variabili esportate prima e dopo:1411Per catturare tutte le modifiche all'ambiente provenienti dai comandi di configurazione, confronta le variabili esportate prima e dopo:
1389 1412
1390```bash theme={null}1413```bash theme={null}
1391#!/bin/bash1414#!/bin/bash
1404exit 01427exit 0
1405```1428```
1406 1429
1407Ogni comando Bash esegue il contenuto del file come codice shell prima del comando stesso, quindi una riga al suo interno può usare qualsiasi cosa Bash valuti, come il riferimento a `$PATH` in `export PATH="$PATH:./node_modules/.bin"`.1430Ogni comando Bash esegue il contenuto del file come codice shell prima del comando stesso, quindi una riga lì può usare qualsiasi cosa Bash valuti, come il riferimento a `$PATH` in `export PATH="$PATH:./node_modules/.bin"`.
1408 1431
1409<a id="persisted-variables-in-powershell-commands" />1432<a id="persisted-variables-in-powershell-commands" />
1410 1433
1412 Variabili persistenti nei comandi PowerShell1435 Variabili persistenti nei comandi PowerShell
1413</h5>1436</h5>
1414 1437
1415Anche i comandi [PowerShell](/docs/it/tools-reference#powershell-tool) ricevono le variabili da `CLAUDE_ENV_FILE`, in Claude Code v2.1.296 o successiva, ma PowerShell non esegue mai il file. Claude Code legge invece le assegnazioni dal file e le copia nell'ambiente del comando PowerShell. Lo fa solo quando ogni riga è di uno dei tipi seguenti, considerando ciò che ogni hook di questa sessione ha scritto e qualsiasi script a cui hai [impostato `CLAUDE_ENV_FILE`](/docs/it/env-vars) prima dell'avvio:1438Anche i comandi [PowerShell](/docs/it/tools-reference#powershell-tool) ricevono le variabili da `CLAUDE_ENV_FILE`, in Claude Code v2.1.296 o successivo, ma PowerShell non esegue mai il file. Claude Code legge invece le assegnazioni dal file e le copia nell'ambiente del comando PowerShell. Lo fa solo quando ogni riga è di uno dei tipi seguenti, considerando ciò che ogni hook di questa sessione ha scritto e qualsiasi script su cui hai [impostato `CLAUDE_ENV_FILE`](/docs/it/env-vars) prima dell'avvio:
1416 1439
1417* Una riga vuota o un commento `#`1440* Una riga vuota o un commento `#`
1418* Un'unica assegnazione all'inizio della riga, scritta `export NAME=value`, `declare -x NAME=value` o `NAME=value`, con un valore che Bash userebbe esattamente come scritto, composto da una qualsiasi combinazione di queste parti: testo senza virgolette che usa solo lettere, cifre e i caratteri `_ @ % + = : , . / -`, testo tra virgolette singole e testo tra virgolette doppie in cui ogni `$`, backtick o `"` al suo interno è preceduto da una barra rovesciata di escape1441* Un'assegnazione all'inizio della riga, scritta `export NAME=value`, `declare -x NAME=value` o `NAME=value`, con un valore che Bash userebbe esattamente come scritto, composto da qualsiasi combinazione di queste parti: testo senza virgolette che usa solo lettere, cifre e i caratteri `_ @ % + = : , . / -`, testo tra virgolette singole e testo tra virgolette doppie in cui ogni `$`, backtick o `"` al suo interno è preceduto da una barra rovesciata di escape
1419 1442
1420Se una qualsiasi riga è di un altro tipo, come `export PATH="$PATH:./node_modules/.bin"` con il suo `$PATH` senza escape, un comando `source` o le stringhe `$'...'` stampate da `direnv export bash`, i comandi PowerShell non ricevono nessuna delle variabili e `claude --debug` registra `Session environment is not all plain assignments`. I comandi Bash le ricevono comunque tutte. Su Windows, inoltre, i comandi PowerShell non ricevono una variabile il cui valore contiene `/` o `\`, perché Git Bash e Windows scrivono i percorsi in modo diverso. Un comando PowerShell in [sandbox](/docs/it/sandboxing) non riceve nessuna delle variabili.1443Se una qualsiasi riga è di un altro tipo, come `export PATH="$PATH:./node_modules/.bin"` con il suo `$PATH` senza escape, un comando `source` o le stringhe `$'...'` che `direnv export bash` stampa, i comandi PowerShell non ricevono nessuna delle variabili e `claude --debug` registra `Session environment is not all plain assignments`. I comandi Bash le ricevono comunque tutte. Su Windows, i comandi PowerShell non ricevono inoltre una variabile il cui valore contiene `/` o `\`, perché Git Bash e Windows scrivono i percorsi in modo diverso. Un comando PowerShell in [sandbox](/docs/it/sandboxing) non riceve nessuna delle variabili.
1421 1444
1422<Note>1445<Note>
1423 `CLAUDE_ENV_FILE` è disponibile per gli hook SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged) e [FileChanged](#filechanged). Gli altri eventi hook non hanno accesso a questa variabile, e nemmeno un hook eseguito in PowerShell, sia tramite [`"shell": "powershell"`](#command-hook-fields) sia per impostazione predefinita su Windows senza Git Bash.1446 `CLAUDE_ENV_FILE` è disponibile per gli hook SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged) e [FileChanged](#filechanged). Gli altri eventi degli hook non hanno accesso a questa variabile, e nemmeno un hook eseguito in PowerShell, sia tramite [`"shell": "powershell"`](#command-hook-fields) sia per impostazione predefinita su Windows senza Git Bash.
1424</Note>1447</Note>
1425 1448
1426<h3 id="setup">1449<h3 id="setup">
1427 Setup1450 Setup
1428</h3>1451</h3>
1429 1452
1430Viene attivato solo quando avvii Claude Code con `--init-only`, oppure con `--init` o `--maintenance` in [modalità non interattiva](/docs/it/headless) con il flag `-p`. Non viene attivato al normale avvio. Usalo per l'installazione una tantum di dipendenze o per una pulizia pianificata che attivi esplicitamente da CI o da script, separatamente dal normale avvio della sessione. Per l'inizializzazione per sessione, usa invece [SessionStart](#sessionstart).1453Si attiva solo quando avvii Claude Code con `--init-only`, oppure con `--init` o `--maintenance` in [modalità non interattiva](/docs/it/headless) con il flag `-p`. Non si attiva durante il normale avvio. Usalo per l'installazione una tantum di dipendenze o per la pulizia pianificata che attivi esplicitamente da CI o da script, separatamente dal normale avvio della sessione. Per l'inizializzazione di ogni sessione, usa invece [SessionStart](#sessionstart).
1431 1454
1432Il valore del matcher corrisponde al flag CLI che ha attivato l'hook:1455Il valore del matcher corrisponde al flag della CLI che ha attivato l'hook:
1433 1456
1434| Matcher | Quando viene attivato |1457| Matcher | Quando si attiva |
1435| :- | :- |1458| :- | :- |
1436| `init` | `claude --init-only` o `claude -p --init` |1459| `init` | `claude --init-only` o `claude -p --init` |
1437| `maintenance` | `claude -p --maintenance` |1460| `maintenance` | `claude -p --maintenance` |
1440 1463
1441Quando avvii o continui una conversazione con `-p`, devi anche fornire un prompt, come argomento o tramite pipe su stdin. Puoi omettere il prompt quando un hook `SessionStart` fornisce [`initialUserMessage`](#sessionstart-decision-control) o quando riprendi una sessione con una [chiamata a uno strumento differita](#defer-a-tool-call-for-later).1464Quando avvii o continui una conversazione con `-p`, devi anche fornire un prompt, come argomento o tramite pipe su stdin. Puoi omettere il prompt quando un hook `SessionStart` fornisce [`initialUserMessage`](#sessionstart-decision-control) o quando riprendi una sessione con una [chiamata a uno strumento differita](#defer-a-tool-call-for-later).
1442 1465
1443In caso di successo, `--init-only` non stampa nulla nel terminale. Per confermare che gli hook sono stati eseguiti, avvia con `claude --debug-file <path> --init-only`, sostituendo `<path>` con il percorso di un file di log, e controlla nel log le voci degli hook Setup e SessionStart.1466In caso di successo, `--init-only` non stampa nulla sul terminale. Per verificare che gli hook siano stati eseguiti, avvia con `claude --debug-file <path> --init-only`, sostituendo `<path>` con la posizione di un file di log, e controlla nel log le voci degli hook Setup e SessionStart.
1444 1467
1445Poiché Setup non viene attivato a ogni avvio, un plugin che necessita di una dipendenza installata non può basarsi solo su Setup. Lo schema pratico consiste nel verificare la dipendenza al primo utilizzo e installarla se manca, ad esempio con un hook o una skill che verifica la presenza di `${CLAUDE_PLUGIN_DATA}/node_modules` ed esegue `npm install` se assente. Consulta la [directory dei dati persistenti](/docs/it/plugins/components#path-variables-and-persistent-data) per sapere dove archiviare le dipendenze installate. Se distribuisci il tuo plugin tramite un marketplace, potresti non aver bisogno di questo schema: Claude Code [installa automaticamente le dipendenze dei pacchetti Node.js idonee](/docs/it/plugins/loading#node-js-package-dependencies) quando memorizza il plugin nella cache.1468Poiché Setup non si attiva a ogni avvio, un plugin che necessita dell'installazione di una dipendenza non può basarsi solo su Setup. Lo schema pratico è verificare la dipendenza al primo utilizzo e installarla se manca, ad esempio un hook o una skill che verifica la presenza di `${CLAUDE_PLUGIN_DATA}/node_modules` ed esegue `npm install` se assente. Consulta la [directory dei dati persistenti](/docs/it/plugins/components#path-variables-and-persistent-data) per sapere dove archiviare le dipendenze installate. Se distribuisci il tuo plugin tramite un marketplace, potresti non aver bisogno di questo schema: Claude Code [installa automaticamente le dipendenze idonee dei pacchetti Node.js](/docs/it/plugins/loading#node-js-package-dependencies) quando memorizza il plugin nella cache.
1446 1469
1447<h4 id="setup-input">1470<h4 id="setup-input">
1448 Input di Setup1471 Input di Setup
1464 Controllo delle decisioni di Setup1487 Controllo delle decisioni di Setup
1465</h4>1488</h4>
1466 1489
1467Gli hook Setup non possono bloccare; l'esecuzione continua con qualsiasi codice di uscita. Con qualsiasi codice di uscita, Claude Code scarta i [campi di output JSON](#json-output) di un hook Setup, come `systemMessage`, `continue` e `hookSpecificOutput.additionalContext`. Con `-p`, lo stdout, lo stderr e il codice di uscita di un hook Setup appaiono nell'output dell'esecuzione solo come [eventi `hook_response`](/docs/it/headless#read-session-metadata) quando avvii con `--output-format stream-json --verbose`.1490Gli hook Setup non possono bloccare; l'esecuzione continua con qualsiasi codice di uscita. Con qualsiasi codice di uscita, Claude Code scarta i [campi di output JSON](#json-output) di un hook Setup, come `systemMessage`, `continue` e `hookSpecificOutput.additionalContext`. Con `-p`, lo stdout, lo stderr e il codice di uscita di un hook Setup compaiono nell'output dell'esecuzione solo come [eventi `hook_response`](/docs/it/headless#read-session-metadata) quando avvii con `--output-format stream-json --verbose`.
1468 1491
1469Gli hook Setup hanno accesso a `CLAUDE_ENV_FILE`. Le variabili scritte in quel file persistono nei successivi comandi Bash della sessione, come negli [hook SessionStart](#persist-environment-variables). Su `Setup` vengono eseguiti solo gli hook `type: "command"`. Un hook `type: "mcp_tool"` su `Setup` viene sempre saltato, come descritto in [Campi degli hook per strumenti MCP](#mcp-tool-hook-fields).1492Gli hook Setup hanno accesso a `CLAUDE_ENV_FILE`. Le variabili scritte in quel file persistono nei successivi comandi Bash della sessione, come negli [hook SessionStart](#persist-environment-variables). Su `Setup` vengono eseguiti solo gli hook `type: "command"`. Un hook `type: "mcp_tool"` su `Setup` viene sempre saltato, come descritto in [Campi degli hook di strumenti MCP](#mcp-tool-hook-fields).
1470 1493
1471<h3 id="instructionsloaded">1494<h3 id="instructionsloaded">
1472 InstructionsLoaded1495 InstructionsLoaded
1473</h3>1496</h3>
1474 1497
1475Viene attivato quando un file `CLAUDE.md` o `.claude/rules/*.md` viene caricato nel contesto. Questo evento viene attivato all'avvio della sessione per i file caricati immediatamente e di nuovo in seguito quando i file vengono caricati in modo differito, ad esempio quando Claude accede a una sottodirectory che contiene un `CLAUDE.md` annidato o quando le regole condizionali con frontmatter `paths:` corrispondono. L'hook non supporta il blocco né il controllo delle decisioni. Viene eseguito in modo asincrono per scopi di osservabilità.1498Si attiva quando un file `CLAUDE.md` o `.claude/rules/*.md` viene caricato nel contesto. Questo evento si attiva all'avvio della sessione per i file caricati subito e di nuovo più tardi quando i file vengono caricati in modo differito, 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 né il controllo delle decisioni. Viene eseguito in modo asincrono a scopo di osservabilità.
1476 1499
1477Questo evento non viene attivato quando Claude [legge direttamente `AGENTS.md`](/docs/it/memory#agents-md) tramite l'impostazione **Project instructions**. Viene invece attivato quando un `CLAUDE.md` importa il tuo `AGENTS.md`, con `load_reason` impostato su `include` come per qualsiasi altro file importato, e quando `CLAUDE.md` è un collegamento simbolico a esso, come un normale caricamento di `CLAUDE.md`.1500Questo evento non si attiva quando Claude [legge direttamente `AGENTS.md`](/docs/it/memory#agents-md) tramite l'impostazione **Project instructions**. Si attiva invece quando un `CLAUDE.md` importa il tuo `AGENTS.md`, con `load_reason` impostato su `include` come per qualsiasi altro file importato, e quando `CLAUDE.md` è un collegamento simbolico ad esso, come un normale caricamento di `CLAUDE.md`.
1478 1501
1479Il matcher viene confrontato con `load_reason`. Ad esempio, usa `"matcher": "session_start"` per attivarlo solo per i file caricati all'avvio della sessione, oppure `"matcher": "path_glob_match|nested_traversal"` per attivarlo solo per i caricamenti differiti.1502Il matcher viene confrontato con `load_reason`. Ad esempio, usa `"matcher": "session_start"` per attivarlo solo per i file caricati all'avvio della sessione, oppure `"matcher": "path_glob_match|nested_traversal"` per attivarlo solo per i caricamenti differiti.
1480 1503
1488| :- | :- |1511| :- | :- |
1489| `file_path` | Percorso assoluto del file di istruzioni caricato |1512| `file_path` | Percorso assoluto del file di istruzioni caricato |
1490| `memory_type` | Ambito del file: `"User"`, `"Project"`, `"Local"` o `"Managed"` |1513| `memory_type` | Ambito del file: `"User"`, `"Project"`, `"Local"` o `"Managed"` |
1491| `load_reason` | Perché il file è stato caricato: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` o `"compact"`. Il valore `"compact"` viene attivato quando i file di istruzioni vengono ricaricati dopo un evento di compattazione |1514| `load_reason` | Motivo per cui 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 |
1492| `globs` | Pattern glob di percorso dal frontmatter `paths:` del file, se presenti. Presente solo per i caricamenti `path_glob_match` |1515| `globs` | Pattern glob di percorso dal frontmatter `paths:` del file, se presenti. Presente solo per i caricamenti `path_glob_match` |
1493| `trigger_file_path` | Percorso del file il cui accesso ha attivato questo caricamento, per i caricamenti differiti |1516| `trigger_file_path` | Percorso del file il cui accesso ha attivato questo caricamento, per i caricamenti differiti |
1494| `parent_file_path` | Percorso del file di istruzioni padre che ha incluso questo, per i caricamenti `include` |1517| `parent_file_path` | Percorso del file di istruzioni padre che ha incluso questo, per i caricamenti `include` |
1509 Controllo delle decisioni di InstructionsLoaded1532 Controllo delle decisioni di InstructionsLoaded
1510</h4>1533</h4>
1511 1534
1512Gli hook InstructionsLoaded non hanno controllo delle decisioni. Non possono bloccare né modificare il caricamento delle istruzioni. Claude Code scarta i loro [campi di output JSON](#json-output), come `systemMessage` e `continue`. Usa questo evento per il logging di audit, il monitoraggio della conformità o l'osservabilità.1535Gli hook InstructionsLoaded non hanno controllo delle decisioni. Non possono bloccare né modificare il caricamento delle istruzioni. Claude Code scarta i loro [campi di output JSON](#json-output), come `systemMessage` e `continue`. Usa questo evento per log di audit, monitoraggio della conformità o osservabilità.
1513 1536
1514<h3 id="userpromptsubmit">1537<h3 id="userpromptsubmit">
1515 UserPromptSubmit1538 UserPromptSubmit
1516</h3>1539</h3>
1517 1540
1518Viene eseguito quando viene inviato un prompt, prima che Claude lo elabori. Ti consente1541Viene eseguito quando viene inviato un prompt, prima che Claude lo elabori. Questo ti permette
1519di aggiungere contesto aggiuntivo in base al prompt/alla conversazione, di convalidare i prompt o1542di aggiungere contesto aggiuntivo in base al prompt/alla conversazione, convalidare i prompt o
1520di bloccare determinati tipi di prompt.1543bloccare determinati tipi di prompt.
1521 1544
1522Gli hook `UserPromptSubmit` non vengono attivati solo sui prompt che digiti. Claude Code li esegue anche quando:1545Gli hook `UserPromptSubmit` non si attivano solo sui prompt che digiti. Claude Code li esegue anche quando:
1523 1546
1524* Si attiva un'[attività pianificata](/docs/it/scheduled-tasks), inclusa un'iterazione di `/loop`1547* Si attiva un'[attività pianificata](/docs/it/scheduled-tasks), inclusa un'iterazione di `/loop`
1525* Un [subagent in background](/docs/it/sub-agents#run-subagents-in-foreground-or-background) riferisce alla sessione che lo ha avviato1548* Un [subagent in background](/docs/it/sub-agents#run-subagents-in-foreground-or-background) riferisce alla sessione che lo ha avviato
1526* Un'[altra sessione invia un messaggio](/docs/it/cross-session-messaging) alla tua conversazione principale1549* Un [messaggio inviato da un'altra sessione](/docs/it/cross-session-messaging) arriva alla tua conversazione principale
1527 1550
1528Gli hook `UserPromptSubmit` hanno un timeout predefinito di 30 secondi per i tipi `command`, `http` e `mcp_tool`, più breve del valore predefinito di 600 secondi per quei tipi nella maggior parte degli altri eventi. Poiché questo hook viene eseguito prima di ogni prompt e blocca l'elaborazione del modello finché non termina, un hook bloccato paralizza la sessione. Se il tuo hook ha bisogno di più tempo, imposta il campo `timeout` nella voce dell'hook.1551Gli hook `UserPromptSubmit` hanno un timeout predefinito di 30 secondi per i tipi `command`, `http` e `mcp_tool`, più breve del valore predefinito di 600 secondi per quei tipi nella maggior parte degli altri eventi. Poiché questo hook viene eseguito prima di ogni prompt e blocca l'elaborazione del modello finché non termina, un hook bloccato blocca la sessione. Se il tuo hook ha bisogno di più tempo, imposta il campo `timeout` nella voce dell'hook.
1529 1552
1530Fatta eccezione per un hook di comando che esegui con [`async: true`](#run-hooks-in-the-background), un hook `UserPromptSubmit` di comando, HTTP o strumento MCP che raggiunge il suo timeout viene annullato e il suo output, incluso qualsiasi `additionalContext`, viene scartato. Il prompt raggiunge comunque Claude senza quel contesto. Per bloccare invece il prompt, imposta [`onFailure: "block"`](#block-the-action-when-a-hook-fails) su un hook di comando o HTTP. La trascrizione mostra un avviso che indica l'hook, il timeout scattato e il fatto che l'output è stato scartato.1553Fatta eccezione per un hook di comando che esegui con [`async: true`](#run-hooks-in-the-background), un hook `UserPromptSubmit` di comando, HTTP o di strumento MCP che raggiunge il suo timeout viene annullato e il suo output, incluso qualsiasi `additionalContext`, viene scartato. Il prompt raggiunge comunque Claude senza quel contesto. Per bloccare invece il prompt, imposta [`onFailure: "block"`](#block-the-action-when-a-hook-fails) su un hook di comando o HTTP. La trascrizione mostra un avviso che indica l'hook, il timeout scattato e che l'output è stato scartato.
1531 1554
1532Un [hook di callback dell'Agent SDK](/docs/it/agent-sdk/hooks) su `UserPromptSubmit` che raggiunge il timeout blocca il prompt con un messaggio che indica l'hook e il timeout, perché lì un callback può fungere da controllo di policy che non deve fallire in modo permissivo. La sessione continua. Prima della v2.1.208, un timeout di callback su quell'evento terminava il turno con un errore di esecuzione.1555Un [hook di callback dell'Agent SDK](/docs/it/agent-sdk/hooks) su `UserPromptSubmit` che raggiunge il suo timeout blocca il prompt con un messaggio che indica l'hook e il timeout, perché lì un callback può fungere da controllo di policy che non deve fallire in modo permissivo. La sessione continua. Prima della v2.1.208, un timeout di callback su quell'evento terminava il turno con un errore di esecuzione.
1533 1556
1534<h4 id="userpromptsubmit-input">1557<h4 id="userpromptsubmit-input">
1535 Input di UserPromptSubmit1558 Input di UserPromptSubmit
1561* **Stdout in testo semplice**: Claude Code aggiunge al contesto di Claude lo stdout che [tratta come testo semplice](#exit-code-0)1584* **Stdout in testo semplice**: Claude Code aggiunge al contesto di Claude lo stdout che [tratta come testo semplice](#exit-code-0)
1562* **JSON con `additionalContext`**: usa il formato JSON riportato sotto per un maggiore controllo. Il campo `additionalContext` viene aggiunto come contesto1585* **JSON con `additionalContext`**: usa il formato JSON riportato sotto per un maggiore controllo. Il campo `additionalContext` viene aggiunto come contesto
1563 1586
1564Nessuno dei due canali produce una voce visibile nella trascrizione. Lo stdout semplice e il valore di `additionalContext` vengono inseriti ciascuno come promemoria di sistema che inizia con il nome dell'hook; Claude li legge entrambi. Per confermare la consegna, controlla il [log di debug](#debug-hooks).1587Nessuno dei due canali produce una voce visibile nella trascrizione. Lo stdout semplice e il valore di `additionalContext` vengono ciascuno inseriti come promemoria di sistema che inizia con il nome dell'hook; Claude li legge entrambi. Per verificare la consegna, controlla il [log di debug](#debug-hooks).
1565 1588
1566Per bloccare un prompt, restituisci un oggetto JSON con `decision` impostato su `"block"`:1589Per bloccare un prompt, restituisci un oggetto JSON con `decision` impostato su `"block"`:
1567 1590
1571| `reason` | Mostrato all'utente quando `decision` è `"block"`. Non viene aggiunto al contesto |1594| `reason` | Mostrato all'utente quando `decision` è `"block"`. Non viene aggiunto al contesto |
1572| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt inviato. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |1595| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt inviato. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |
1573| `sessionTitle` | Imposta il titolo della sessione. Usalo per assegnare automaticamente un nome alle sessioni in base al contenuto del prompt |1596| `sessionTitle` | Imposta il titolo della sessione. Usalo per assegnare automaticamente un nome alle sessioni in base al contenuto del prompt |
1574| `suppressOriginalPrompt` | Se `true` quando l'hook blocca il prompt, esclude il testo del prompt dal messaggio di blocco. Consulta [Cosa lascia un prompt bloccato](#what-a-blocked-prompt-leaves-behind) |1597| `suppressOriginalPrompt` | Se è `true` quando l'hook blocca il prompt, omette il testo del prompt dal messaggio di blocco. Consulta [Cosa lascia dietro di sé un prompt bloccato](#what-a-blocked-prompt-leaves-behind) |
1575 1598
1576Un hook che blocca uscendo con 2 segue lo stesso percorso di `reason`: il messaggio di blocco mostra all'utente il testo di stderr, che non viene aggiunto al contesto.1599Un hook che blocca uscendo con 2 viene instradato allo stesso modo di `reason`: il messaggio di blocco mostra all'utente il testo di stderr, che non viene aggiunto al contesto.
1577 1600
1578```json theme={null}1601```json theme={null}
1579{1602{
1589```1612```
1590 1613
1591<h4 id="what-a-blocked-prompt-leaves-behind">1614<h4 id="what-a-blocked-prompt-leaves-behind">
1592 Cosa lascia un prompt bloccato1615 Cosa lascia dietro di sé un prompt bloccato
1593</h4>1616</h4>
1594 1617
1595Un prompt bloccato non raggiunge mai Claude, ma il suo testo non viene rimosso ovunque. Per impostazione predefinita, il messaggio di blocco mostrato all'utente termina con `Original prompt:` seguito dal testo inviato, e Claude Code scrive quel messaggio nel file di trascrizione della sessione su disco. Per escludere il testo dal messaggio, stampa un JSON con `"suppressOriginalPrompt": true` all'interno di `hookSpecificOutput`. Funziona sia che l'hook blocchi con `decision: "block"` sia uscendo con 2.1618Un 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 della trascrizione della sessione su disco. Per omettere il testo dal messaggio, stampa JSON con `"suppressOriginalPrompt": true` all'interno di `hookSpecificOutput`. Funziona sia che l'hook blocchi con `decision: "block"` sia che esca con 2.
1596 1619
1597`suppressOriginalPrompt` modifica solo il messaggio di blocco. Il testo inviato può comunque comparire in file locali come la trascrizione della sessione e la cronologia dei tuoi prompt, quindi un hook di blocco non è un modo per tenere un segreto fuori dal disco. Per limitare o rimuovere quei file, consulta [Archiviazione in testo semplice](/docs/it/claude-directory#plaintext-storage) e [Cancellare i dati locali](/docs/it/claude-directory#clear-local-data).1620`suppressOriginalPrompt` modifica solo il messaggio di blocco. Il testo inviato può comunque apparire in file locali come la trascrizione della sessione e la cronologia dei prompt, quindi un hook di blocco non è un modo per tenere un segreto lontano dal disco. Per limitare o rimuovere quei file, consulta [Archiviazione in testo semplice](/docs/it/claude-directory#plaintext-storage) e [Cancellare i dati locali](/docs/it/claude-directory#clear-local-data).
1598 1621
1599<h3 id="userpromptexpansion">1622<h3 id="userpromptexpansion">
1600 UserPromptExpansion1623 UserPromptExpansion
1602 1625
1603Viene eseguito quando un comando digitato dall'utente si espande in un prompt prima di raggiungere Claude. Usalo per impedire l'invocazione diretta di comandi specifici, inserire contesto per una particolare skill o registrare quali comandi invocano gli utenti. Ad esempio, un hook che corrisponde a `deploy` può bloccare `/deploy` a meno che non sia presente un file di approvazione, oppure un hook che corrisponde a una skill di revisione può aggiungere la checklist di revisione del team come `additionalContext`.1626Viene eseguito quando un comando digitato dall'utente si espande in un prompt prima di raggiungere Claude. Usalo per impedire l'invocazione diretta di comandi specifici, inserire contesto per una particolare skill o registrare quali comandi invocano gli utenti. Ad esempio, un hook che corrisponde a `deploy` può bloccare `/deploy` a meno che non sia presente un file di approvazione, oppure un hook che corrisponde a una skill di revisione può aggiungere la checklist di revisione del team come `additionalContext`.
1604 1627
1605Questo evento copre il percorso che `PreToolUse` non copre: un hook `PreToolUse` che corrisponde allo strumento `Skill` viene attivato solo quando Claude chiama lo strumento, ma digitare direttamente `/skillname` aggira `PreToolUse`. `UserPromptExpansion` viene attivato su quel percorso diretto.1628Questo evento copre il percorso che `PreToolUse` non copre: un hook `PreToolUse` che corrisponde allo strumento `Skill` si attiva solo quando Claude chiama lo strumento, ma digitare direttamente `/skillname` aggira `PreToolUse`. `UserPromptExpansion` si attiva su quel percorso diretto.
1606 1629
1607Corrisponde su `command_name`. Lascia vuoto il matcher per attivarlo su ogni comando di tipo prompt.1630Corrisponde su `command_name`. Lascia il matcher vuoto per attivarlo su ogni comando di tipo prompt.
1608 1631
1609<h4 id="userpromptexpansion-input">1632<h4 id="userpromptexpansion-input">
1610 Input di UserPromptExpansion1633 Input di UserPromptExpansion
1639| `reason` | Mostrato all'utente quando `decision` è `"block"` |1662| `reason` | Mostrato all'utente quando `decision` è `"block"` |
1640| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt espanso. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |1663| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt espanso. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |
1641 1664
1642Un hook che blocca uscendo con 2 segue lo stesso percorso di `reason`: il messaggio di blocco mostra all'utente il testo di stderr.1665Un hook che blocca uscendo con 2 viene instradato allo stesso modo di `reason`: il messaggio di blocco mostra all'utente il testo di stderr.
1643 1666
1644```json theme={null}1667```json theme={null}
1645{1668{
1656 MessageDisplay1679 MessageDisplay
1657</h3>1680</h3>
1658 1681
1659Viene eseguito mentre un messaggio dell'assistente viene trasmesso sullo schermo. Claude Code mostra il messaggio a incrementi: ogni volta che un gruppo di righe appena completate è pronto per essere visualizzato, l'hook viene eseguito una volta con quelle righe e Claude Code visualizza al loro posto il testo sostitutivo dell'hook. Un messaggio lungo produce diverse chiamate; un messaggio breve può produrne solo una.1682Viene eseguito mentre un messaggio dell'assistente viene trasmesso sullo schermo. Claude Code visualizza il messaggio in incrementi: ogni volta che un gruppo di righe appena completate è pronto per il rendering, l'hook viene eseguito una volta con quelle righe e Claude Code visualizza al loro posto il testo sostitutivo dell'hook. Un messaggio lungo produce diverse chiamate; un messaggio breve può produrne solo una.
1660 1683
1661Usa MessageDisplay per:1684Usa MessageDisplay per:
1662 1685
1663* rimuovere il markdown per una visualizzazione minimale1686* rimuovere il markdown per una visualizzazione minimale
1664* trasformare il testo che un'applicazione dell'Agent SDK mostra ai suoi utenti1687* trasformare il testo che un'applicazione Agent SDK mostra ai suoi utenti
1665* oscurare chiavi API o nomi host interni dalle risposte di Claude1688* oscurare chiavi API o nomi host interni dalle risposte di Claude
1666 1689
1667Claude Code trattiene ogni gruppo finché il tuo hook non restituisce un risultato, quindi mantieni l'hook veloce. Se l'hook fallisce o va in timeout, Claude Code visualizza il testo originale. Il timeout predefinito per questo evento è di 10 secondi; se il tuo hook ha bisogno di più tempo, imposta il campo `timeout` nella voce dell'hook.1690Claude Code trattiene ogni gruppo finché il tuo hook non restituisce un risultato, quindi mantieni l'hook veloce. Se l'hook fallisce o va in timeout, Claude Code visualizza il testo originale. Il timeout predefinito per questo evento è di 10 secondi; se il tuo hook ha bisogno di più tempo, imposta il campo `timeout` nella voce dell'hook.
1668 1691
1669MessageDisplay riguarda solo la visualizzazione: il testo sostitutivo cambia solo ciò che viene mostrato sullo schermo. La trascrizione e ciò che vede Claude mantengono il testo originale, quindi Claude non vede mai la sostituzione, e la modalità verbose mostra l'originale. L'hook riceve solo il testo dei messaggi dell'assistente, quindi i risultati degli strumenti e il testo che digiti vengono visualizzati invariati.1692MessageDisplay riguarda solo la visualizzazione: il testo sostitutivo cambia solo ciò che viene mostrato sullo schermo. La trascrizione e ciò che vede Claude mantengono il testo originale, quindi Claude non vede mai la sostituzione, e la modalità verbose mostra l'originale. L'hook riceve solo il testo dei messaggi dell'assistente, quindi i risultati degli strumenti e il testo che digiti vengono visualizzati senza modifiche.
1670 1693
1671MessageDisplay non supporta i matcher e viene attivato per ogni messaggio dell'assistente che trasmette testo; i messaggi senza testo, come le risposte composte solo da chiamate a strumenti, non lo attivano.1694MessageDisplay non supporta i matcher e si attiva per ogni messaggio dell'assistente che trasmette testo; i messaggi senza testo, come le risposte composte solo da chiamate a strumenti, non lo attivano.
1672 1695
1673Nelle esecuzioni non interattive, incluse le query dell'Agent SDK e `claude -p`, MessageDisplay viene eseguito una volta per messaggio dell'assistente anziché una volta per gruppo di righe. L'unica chiamata arriva dopo il completamento del messaggio e contiene il testo completo del messaggio: `index` è `0`, `final` è `true` e `delta` contiene l'intero messaggio. Un hook che raccoglie il testo `delta` per ogni messaggio riceve lo stesso testo totale in entrambe le modalità.1696Nelle esecuzioni non interattive, incluse le query dell'Agent SDK e `claude -p`, MessageDisplay viene eseguito una volta per messaggio dell'assistente anziché una volta per gruppo di righe. L'unica chiamata arriva dopo il completamento del messaggio e contiene l'intero testo del messaggio: `index` è `0`, `final` è `true` e `delta` contiene l'intero messaggio. Un hook che raccoglie il testo di `delta` per ogni messaggio riceve lo stesso testo complessivo in entrambe le modalità.
1674 1697
1675<h4 id="messagedisplay-input">1698<h4 id="messagedisplay-input">
1676 Input di MessageDisplay1699 Input di MessageDisplay
1677</h4>1700</h4>
1678 1701
1679Oltre ai [campi di input comuni](#common-input-fields), gli hook MessageDisplay ricevono gli identificatori del turno e del messaggio, la posizione di questa chiamata all'interno del messaggio e il nuovo testo in `delta`. I confini dei gruppi dipendono da come viene trasmesso il testo, quindi usa `index` e `final` per tracciare l'avanzamento all'interno di un messaggio anziché aspettarti che le righe siano raggruppate in un modo particolare.1702Oltre ai [campi di input comuni](#common-input-fields), gli hook MessageDisplay ricevono gli identificatori del turno e del messaggio, la posizione di questa chiamata all'interno del messaggio e il nuovo testo in `delta`. I confini dei gruppi dipendono da come viene trasmesso il testo, quindi usa `index` e `final` per monitorare l'avanzamento in un messaggio anziché aspettarti che le righe siano raggruppate in un modo particolare.
1680 1703
1681| Campo | Descrizione |1704| Campo | Descrizione |
1682| :- | :- |1705| :- | :- |
1684| `message_id` | UUID del messaggio dell'assistente visualizzato. Stabile in tutti i gruppi dello stesso messaggio. Non è l'id `msg_…` dell'API, quindi non può essere correlato con gli id dei messaggi della trascrizione |1707| `message_id` | UUID del messaggio dell'assistente visualizzato. Stabile in tutti i gruppi dello stesso messaggio. Non è l'id `msg_…` dell'API, quindi non può essere correlato con gli id dei messaggi della trascrizione |
1685| `index` | Indice a base zero di questo gruppo all'interno del messaggio |1708| `index` | Indice a base zero di questo gruppo all'interno del messaggio |
1686| `final` | `true` sull'ultimo gruppo del messaggio. Ogni messaggio ha esattamente un gruppo finale |1709| `final` | `true` sull'ultimo gruppo del messaggio. Ogni messaggio ha esattamente un gruppo finale |
1687| `delta` | Le righe appena completate dal gruppo precedente, inclusi i caratteri di nuova riga finali. Sempre righe intere, tranne il gruppo finale, che può terminare a metà riga. Nelle esecuzioni interattive, il delta del gruppo finale è vuoto quando il messaggio termina con una nuova riga, quindi considera `final`, e non un delta non vuoto, come segnale di fine messaggio. Nelle esecuzioni dell'Agent SDK e di `claude -p`, l'unica chiamata contiene l'intero messaggio |1710| `delta` | Le righe appena completate dal gruppo precedente, inclusi i caratteri di nuova riga finali. Sempre righe intere, tranne il gruppo finale che può terminare a metà riga. Nelle esecuzioni interattive, il delta del gruppo finale è vuoto quando il messaggio termina con una nuova riga, quindi considera `final`, e non un delta non vuoto, come segnale di fine messaggio. Nelle esecuzioni dell'Agent SDK e di `claude -p`, l'unica chiamata contiene l'intero messaggio |
1688 1711
1689```json theme={null}1712```json theme={null}
1690{1713{
1712 1735
1713Gli hook MessageDisplay non hanno controllo delle decisioni. Non possono bloccare il messaggio né modificare ciò che viene archiviato nella trascrizione o inviato a Claude. Claude Code agisce su `displayContent` dal loro output JSON e scarta `systemMessage` e `continue`.1736Gli hook MessageDisplay non hanno controllo delle decisioni. Non possono bloccare il messaggio né modificare ciò che viene archiviato nella trascrizione o inviato a Claude. Claude Code agisce su `displayContent` dal loro output JSON e scarta `systemMessage` e `continue`.
1714 1737
1715Questo esempio rimuove la formattazione markdown dalle risposte di Claude per una visualizzazione in testo semplice. Lo script legge ogni gruppo da stdin, rimuove da `delta` i marcatori del grassetto e i backtick del codice inline, e restituisce il risultato come `displayContent`.1738Questo esempio rimuove la formattazione markdown dalle risposte di Claude per una visualizzazione in testo semplice. Lo script legge ogni gruppo da stdin, rimuove i marcatori del grassetto e i backtick del codice inline da `delta` e restituisce il risultato come `displayContent`.
1716 1739
1717<Tabs>1740<Tabs>
1718 <Tab title="macOS/Linux">1741 <Tab title="macOS/Linux">
1771 }1794 }
1772 ```1795 ```
1773 1796
1774 Il flag `-NoProfile` salta il caricamento del tuo profilo PowerShell in modo che l'hook si avvii rapidamente, e `-ExecutionPolicy Bypass` consente a PowerShell di eseguire il file di script locale.1797 Il flag `-NoProfile` salta il caricamento del tuo profilo PowerShell così l'hook si avvia rapidamente, e `-ExecutionPolicy Bypass` consente a PowerShell di eseguire il file di script locale.
1775 1798
1776 Salva questo script in `.claude/hooks/plain-display.ps1` nel tuo progetto:1799 Salva questo script in `.claude/hooks/plain-display.ps1` nel tuo progetto:
1777 1800
1788 </Tab>1811 </Tab>
1789</Tabs>1812</Tabs>
1790 1813
1791I gruppi senza markdown passano invariati. Se lo script fallisce, ad esempio perché `jq` manca, Claude Code visualizza il testo originale e segnala l'errore solo nell'[output di debug](#debug-hooks), non nella sessione.1814I gruppi senza markdown passano senza modifiche. Se lo script fallisce, ad esempio perché manca `jq`, Claude Code visualizza il testo originale e segnala il fallimento solo nell'[output di debug](#debug-hooks), non nella sessione.
1792 1815
1793<h3 id="pretooluse">1816<h3 id="pretooluse">
1794 PreToolUse1817 PreToolUse
1795</h3>1818</h3>
1796 1819
1797Viene eseguito dopo che Claude ha creato i parametri dello strumento e prima di elaborare la chiamata allo strumento. Corrisponde a qualsiasi nome di strumento tranne `EndConversation`: strumenti integrati come `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion` e `ExitPlanMode`, e qualsiasi [nome di strumento MCP](#match-mcp-tools).1820Viene eseguito dopo che Claude ha creato i parametri dello strumento e prima dell'elaborazione della chiamata allo strumento. Corrisponde a qualsiasi nome di strumento eccetto `EndConversation`: strumenti integrati come `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion` e `ExitPlanMode`, e qualsiasi [nome di strumento MCP](#match-mcp-tools).
1798 1821
1799Per eseguire un hook quando un file specifico cambia su disco, indipendentemente da chi lo ha scritto, usa [FileChanged](#filechanged) anziché far corrispondere per nome gli strumenti di modifica dei file. A differenza di PreToolUse, Claude Code esegue gli hook FileChanged dopo la modifica, e questi non hanno controllo delle decisioni, quindi non possono bloccare la scrittura.1822Per eseguire un hook quando un file specifico cambia su disco, indipendentemente da chi lo ha scritto, usa [FileChanged](#filechanged) invece di far corrispondere per nome gli strumenti di modifica dei file. A differenza di PreToolUse, Claude Code esegue gli hook FileChanged dopo la modifica, e non hanno controllo delle decisioni, quindi non possono bloccare la scrittura.
1800 1823
1801<Warning>1824<Warning>
1802 PreToolUse viene eseguito solo quando Claude chiama uno strumento. I file a cui [fai riferimento con `@` nel tuo prompt](/docs/it/common-workflows#reference-files-and-directories) vengono aggiunti senza alcuna chiamata a uno strumento: Claude Code inserisce il loro contenuto durante la costruzione del prompt, quindi per essi non viene attivato alcun hook PreToolUse, inclusi gli hook che corrispondono a `Read`. Per impedire che percorsi specifici vengano referenziati con `@`, usa invece una [regola di negazione `Read`](/docs/it/permissions#read-and-edit).1825 PreToolUse viene eseguito solo quando Claude chiama uno strumento. Per impostazione predefinita, i file che [referenzi con `@` nel tuo prompt](/docs/it/common-workflows#reference-files-and-directories) vengono aggiunti senza alcuna chiamata a uno strumento. Claude Code ne inserisce il contenuto durante la costruzione del prompt, quindi nessun hook PreToolUse si attiva per essi, inclusi gli hook che corrispondono a `Read`. PreToolUse inoltre non si attiva per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).
1803 1826
1804 PreToolUse inoltre non viene attivato per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).1827 Puoi bloccare percorsi specifici dai riferimenti `@`, oppure disattivare l'inserimento:
1828
1829 * **Bloccare percorsi specifici**: aggiungi una [regola di negazione `Read`](/docs/it/permissions#read-and-edit) per essi
1830 * **Disattivare l'inserimento**: imposta [`CLAUDE_CODE_DISABLE_FILE_MENTIONS=1`](/docs/it/env-vars#variables) nella tua shell, nelle impostazioni utente o nelle impostazioni gestite. Claude riceve quindi i percorsi menzionati con una nota che gli chiede di leggerli usando i suoi strumenti per i file. Se lo fa, i tuoi hook PreToolUse corrispondenti vengono eseguiti. La variabile richiede Claude Code v2.1.299 o successivo, e Claude Code la ignora nelle impostazioni di progetto e locali.
1805</Warning>1831</Warning>
1806 1832
1807Usa il [controllo delle decisioni di PreToolUse](#pretooluse-decision-control) per consentire, negare, chiedere o differire la chiamata allo strumento.1833Usa il [controllo delle decisioni di PreToolUse](#pretooluse-decision-control) per consentire, negare, chiedere conferma o differire la chiamata allo strumento.
1808 1834
1809Un [hook di callback dell'Agent SDK](/docs/it/agent-sdk/hooks) su `PreToolUse` che supera il timeout blocca la chiamata allo strumento, e Claude riceve un risultato di errore che indica il timeout. Una negazione esplicita restituita da un altro hook ha comunque la precedenza.1835Un [hook di callback dell'Agent SDK](/docs/it/agent-sdk/hooks) su `PreToolUse` che supera il suo timeout blocca la chiamata allo strumento, e Claude riceve un risultato di errore che indica il timeout. Una negazione esplicita restituita da un altro hook ha comunque la precedenza.
1810 1836
1811<h4 id="pretooluse-input">1837<h4 id="pretooluse-input">
1812 Input di PreToolUse1838 Input di PreToolUse
1814 1840
1815Oltre ai [campi di input comuni](#common-input-fields), gli hook PreToolUse ricevono `tool_name`, `tool_input` e `tool_use_id`.1841Oltre ai [campi di input comuni](#common-input-fields), gli hook PreToolUse ricevono `tool_name`, `tool_input` e `tool_use_id`.
1816 1842
1817Per uno [strumento MCP](#match-mcp-tools), l'input contiene anche `mcp_server`, un oggetto con il `name` del server e un `source` che indica da dove proviene la definizione del server. I valori di `source` includono `plugin`, `sdk` e ambiti di configurazione come `user` e `project`. [`McpServerProvenance`](/docs/it/agent-sdk/typescript#mcpserverprovenance) nel riferimento dell'Agent SDK li elenca tutti e spiega come trattare un valore che non riconosci. Basa le decisioni di fiducia su `source` anziché su `name` o sul prefisso del nome dello strumento `mcp__<server>__`. Il campo `mcp_server` richiede Claude Code v2.1.274 o successiva.1843Per uno [strumento MCP](#match-mcp-tools), l'input contiene anche `mcp_server`, un oggetto con il `name` del server e un `source` che indica da dove proviene la definizione del server. I valori di `source` includono `plugin`, `sdk` e ambiti di configurazione come `user` e `project`. [`McpServerProvenance`](/docs/it/agent-sdk/typescript#mcpserverprovenance) nel riferimento dell'Agent SDK li elenca tutti e spiega come trattarne uno che non riconosci. Basa le decisioni di fiducia su `source` anziché su `name` o sul prefisso del nome dello strumento `mcp__<server>__`. Il campo `mcp_server` richiede Claude Code v2.1.274 o successivo.
1818 1844
1819Per gli strumenti di file `Write`, `Edit` e `Read`, `tool_input.file_path` è sempre assoluto:1845Per gli strumenti di file `Write`, `Edit` e `Read`, `tool_input.file_path` è sempre assoluto:
1820 1846
1821* Claude Code espande `~` e i percorsi relativi prima dell'esecuzione degli hook, quindi un hook che corrisponde sui percorsi non può essere aggirato tramite `~` o una scrittura relativa dello stesso percorso1847* Claude Code espande `~` e i percorsi relativi prima dell'esecuzione degli hook, quindi un hook che effettua la corrispondenza sui percorsi non può essere aggirato tramite `~` o una scrittura relativa dello stesso percorso
1822* Su Windows, il percorso arriva con separatori backslash, anche quando il tuo hook viene eseguito in Git Bash dove `$PWD` appare come `/c/project`1848* Su Windows, il percorso arriva con separatori a barra rovesciata, anche quando il tuo hook viene eseguito in Git Bash, dove `$PWD` appare come `/c/project`
1823* Un confronto scritto con le barre normali, come un controllo su `/src/`, non corrisponde mai a un percorso con backslash, e la chiamata allo strumento procede come se l'hook non avesse nulla da bloccare1849* Un confronto scritto con barre normali, come un controllo su `/src/`, non corrisponde mai a un percorso con barre rovesciate, e la chiamata allo strumento procede come se l'hook non avesse nulla da bloccare
1824* Normalizza i separatori prima del confronto: `FILE_PATH="${FILE_PATH//\\//}"` in Bash, oppure `file_path.replace("\\", "/")` in Python, poi fai corrispondere un segmento di percorso come `/src/` anziché ancorare con `^`, poiché il percorso è assoluto1850* Normalizza i separatori prima del confronto: `FILE_PATH="${FILE_PATH//\\//}"` in Bash, oppure `file_path.replace("\\", "/")` in Python, poi fai corrispondere un segmento di percorso come `/src/` anziché ancorare con `^`, dato che il percorso è assoluto
1825 1851
1826Una chiamata `Write` su Windows fornisce:1852Una chiamata `Write` su Windows fornisce:
1827 1853
1854| `timeout` | number | `120000` | Timeout facoltativo in millisecondi. I valori superiori al [massimo](/docs/it/tools-reference#bash-tool-behavior) vengono ridotti al massimo anziché rifiutati |1880| `timeout` | number | `120000` | Timeout facoltativo in millisecondi. I valori superiori al [massimo](/docs/it/tools-reference#bash-tool-behavior) vengono ridotti al massimo anziché rifiutati |
1855| `run_in_background` | boolean | `false` | Se eseguire il comando in background |1881| `run_in_background` | boolean | `false` | Se eseguire il comando in background |
1856 1882
1857Quando un comando Bash modifica file in un repository Git, Claude Code può registrare cosa è cambiato. Registra le modifiche in ogni modalità di permesso quando l'impostazione [`bashEditDiffEnabled`](/docs/it/settings-reference#basheditdiffenabled) attiva la registrazione; la voce di quell'impostazione indica quali file possono impostarla. Altrimenti le registra solo in modalità auto e in modalità `bypassPermissions`, e solo quando Claude Code indica a Claude di modificare i file tramite Bash. Imposta `bashEditDiffEnabled` su `false` per disattivare la registrazione. I comandi in background e i comandi di sola lettura non contengono alcun diff.1883Quando un comando Bash modifica file in un repository Git, Claude Code può registrare cosa è cambiato. Registra le modifiche in ogni modalità di permesso quando l'impostazione [`bashEditDiffEnabled`](/docs/it/settings-reference#basheditdiffenabled) attiva la registrazione; la voce di quell'impostazione indica quali file possono impostarla. Altrimenti le registra solo in modalità auto e in modalità `bypassPermissions`, e solo quando Claude Code indica a Claude di modificare i file tramite Bash. Imposta `bashEditDiffEnabled` su `false` per disattivare la registrazione. I comandi in background e i comandi di sola lettura non includono alcun diff.
1858 1884
1859Il tuo [hook PostToolUse](#posttooluse) riceve quindi i file modificati in `tool_response.bashEditDiff`. L'elenco copre ciò che è cambiato nel repository durante l'esecuzione del comando. I file ignorati da Git e i file nei submodule non sono elencati. Richiede Claude Code v2.1.269 o successiva.1885Il tuo [hook PostToolUse](#posttooluse) riceve quindi i file modificati in `tool_response.bashEditDiff`. L'elenco copre ciò che è cambiato nel repository durante l'esecuzione del comando. I file ignorati da Git e i file nei submodule non sono elencati. Richiede Claude Code v2.1.269 o successivo.
1860 1886
1861<Note>1887<Note>
1862 L'elenco è fornito al meglio delle possibilità ed è in beta pubblica. Claude Code può non rilevare una modifica, includere un file che un altro processo ha modificato nello stesso momento o fermarsi ai propri limiti di dimensione. La struttura del campo potrebbe cambiare. Usa l'elenco per capire cosa rivedere, non per applicare una policy.1888 L'elenco è fornito al meglio delle possibilità ed è in beta pubblica. Claude Code può non rilevare una modifica, includere un file che un altro processo ha modificato nello stesso momento o fermarsi ai suoi limiti di dimensione. La struttura del campo può cambiare. Usa l'elenco per trovare cosa rivedere, non per applicare una policy.
1863</Note>1889</Note>
1864 1890
1865`changedFiles` e `files` elencano ciò che il comando ha modificato; i campi rimanenti indicano quanto è completo e affidabile quell'elenco.1891`changedFiles` e `files` elencano ciò che il comando ha modificato; i campi rimanenti indicano quanto è completo e affidabile quell'elenco.
1871| `moreFiles` | number | `2` | Numero di file modificati senza diff in `files` |1897| `moreFiles` | number | `2` | Numero di file modificati senza diff in `files` |
1872| `unavailable` | boolean | `true` | Impostato quando il diff è incompleto o non è stato possibile ottenerlo |1898| `unavailable` | boolean | `true` | Impostato quando il diff è incompleto o non è stato possibile ottenerlo |
1873| `skipped` | boolean | `true` | Impostato per un comando Git che sposta l'albero di lavoro, come `git checkout` o `git stash`, per cui Claude Code non calcola alcun diff |1899| `skipped` | boolean | `true` | Impostato per un comando Git che sposta l'albero di lavoro, come `git checkout` o `git stash`, per cui Claude Code non calcola alcun diff |
1874| `shared` | boolean | `true` | Impostato quando un'altra chiamata allo strumento Bash, ad esempio quella di un subagent, è stata eseguita nello stesso repository nello stesso momento, per cui alcune modifiche elencate potrebbero appartenere a quel comando |1900| `shared` | boolean | `true` | Impostato quando un'altra chiamata allo strumento Bash, come quella di un subagent, è stata eseguita nello stesso repository nello stesso momento, quindi alcune modifiche elencate potrebbero appartenere a quel comando |
1875 1901
1876<a id="powershell" />1902<a id="powershell" />
1877 1903
1890| `timeout` | number | `120000` | Timeout facoltativo in millisecondi |1916| `timeout` | number | `120000` | Timeout facoltativo in millisecondi |
1891| `run_in_background` | boolean | `false` | Se eseguire il comando in background |1917| `run_in_background` | boolean | `false` | Se eseguire il comando in background |
1892 1918
1893Usa `Bash|PowerShell` negli hook che ispezionano i comandi shell, così coprono entrambi gli strumenti:1919Fai corrispondere `Bash|PowerShell` negli hook che ispezionano i comandi shell, in modo che coprano entrambi gli strumenti:
1894 1920
1895* Su Windows, ovunque lo strumento PowerShell sia abilitato, Claude tratta PowerShell come shell principale e instrada i comandi shell attraverso di essa.1921* Su Windows, ovunque sia abilitato lo strumento PowerShell, Claude tratta PowerShell come shell principale e vi instrada i comandi shell.
1896* Su Windows senza Git Bash, lo strumento viene abilitato automaticamente e Claude Code non registra affatto lo strumento Bash.1922* Su Windows senza Git Bash, lo strumento viene abilitato automaticamente e Claude Code non registra affatto lo strumento Bash.
1897* Un hook che corrisponde solo a `Bash` non viene mai attivato in quel caso.1923* Un hook che corrisponde solo a `Bash` non si attiva mai lì.
1898 1924
1899<h5 id="write">1925<h5 id="write">
1900 Write1926 Write
1968| :- | :- | :- | :- |1994| :- | :- | :- | :- |
1969| `url` | string | `"https://example.com/api"` | URL da cui recuperare il contenuto |1995| `url` | string | `"https://example.com/api"` | URL da cui recuperare il contenuto |
1970| `prompt` | string | `"Extract the API endpoints"` | Prompt da eseguire sul contenuto recuperato |1996| `prompt` | string | `"Extract the API endpoints"` | Prompt da eseguire sul contenuto recuperato |
1971| `offset` | number | `100000` | Numero facoltativo di caratteri da saltare dall'inizio della pagina. Claude lo imposta per continuare a leggere una pagina lunga. Richiede Claude Code v2.1.290 o successiva |1997| `offset` | number | `100000` | Numero facoltativo di caratteri da saltare dall'inizio della pagina. Claude lo imposta per continuare a leggere una pagina lunga. Richiede Claude Code v2.1.290 o successivo |
1972 1998
1973<h5 id="websearch">1999<h5 id="websearch">
1974 WebSearch2000 WebSearch
1979| Campo | Tipo | Esempio | Descrizione |2005| Campo | Tipo | Esempio | Descrizione |
1980| :- | :- | :- | :- |2006| :- | :- | :- | :- |
1981| `query` | string | `"react hooks best practices"` | Query di ricerca |2007| `query` | string | `"react hooks best practices"` | Query di ricerca |
1982| `allowed_domains` | array | `["docs.example.com"]` | Facoltativo: include solo i risultati da questi domini |2008| `allowed_domains` | array | `["docs.example.com"]` | Facoltativo: include solo i risultati di questi domini |
1983| `blocked_domains` | array | `["spam.example.com"]` | Facoltativo: esclude i risultati da questi domini |2009| `blocked_domains` | array | `["spam.example.com"]` | Facoltativo: esclude i risultati di questi domini |
1984 2010
1985<h5 id="agent">2011<h5 id="agent">
1986 Agent2012 Agent
1993| `prompt` | string | `"Find all API endpoints"` | L'attività che l'agente deve svolgere |2019| `prompt` | string | `"Find all API endpoints"` | L'attività che l'agente deve svolgere |
1994| `description` | string | `"Find API endpoints"` | Breve descrizione dell'attività |2020| `description` | string | `"Find API endpoints"` | Breve descrizione dell'attività |
1995| `subagent_type` | string | `"Explore"` | Tipo di agente specializzato da usare |2021| `subagent_type` | string | `"Explore"` | Tipo di agente specializzato da usare |
1996| `model` | string | `"sonnet"` | Alias di modello facoltativo per sovrascrivere il valore predefinito |2022| `model` | string | `"sonnet"` | Alias di modello facoltativo per sovrascrivere quello predefinito |
1997 2023
1998Quando una chiamata Agent in primo piano termina, il tuo [hook PostToolUse](#posttooluse) riceve il risultato del subagent e la telemetria dell'esecuzione in `tool_response`. Leggi questi campi per ispezionare l'esecuzione; per i totali di token e costi tra i subagent, usa i [contatori di token e costi](/docs/it/monitoring-usage#token-counter) filtrati su `query_source` `"subagent"`, poiché `totalTokens` e `usage` coprono solo la richiesta finale:2024Quando una chiamata Agent in primo piano termina, il tuo [hook PostToolUse](#posttooluse) riceve il risultato del subagent e la telemetria dell'esecuzione in `tool_response`. Leggi questi campi per ispezionare l'esecuzione; per i totali di token e costi tra i subagent, usa i [contatori di token e costi](/docs/it/monitoring-usage#token-counter) filtrati su `query_source` `"subagent"`, poiché `totalTokens` e `usage` coprono solo la richiesta finale:
1999 2025
2000| Campo | Tipo | Esempio | Descrizione |2026| Campo | Tipo | Esempio | Descrizione |
2001| :- | :- | :- | :- |2027| :- | :- | :- | :- |
2002| `status` | string | `"completed"` | `"completed"` per i subagent in primo piano, `"async_launched"` per i subagent in background. Per impostazione predefinita i subagent vengono eseguiti in background, quindi anche una chiamata Agent che omette `run_in_background` produce `"async_launched"` |2028| `status` | string | `"completed"` | `"completed"` per i subagent in primo piano, `"async_launched"` per i subagent in background. I subagent vengono eseguiti in background per impostazione predefinita, quindi anche una chiamata Agent che omette `run_in_background` produce `"async_launched"` |
2003| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificatore dell'esecuzione del subagent |2029| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificatore dell'esecuzione del subagent |
2004| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | I blocchi di testo finali del subagent oppure, per un subagent il cui report passa attraverso `SubagentHandback`, una breve nota su quella consegna al loro posto |2030| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | I blocchi di testo finali del subagent oppure, per un subagent il cui resoconto passa attraverso `SubagentHandback`, una breve nota su quella consegna al loro posto |
2005| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modello con cui il subagent è partito, che può differire dal modello richiesto |2031| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modello con cui il subagent è partito, che può differire dal modello richiesto |
2006| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelli usati in ordine, con le ripetizioni consecutive compresse; impostato solo quando il modello è stato cambiato durante l'esecuzione. Richiede Claude Code v2.1.212 o successiva |2032| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelli usati in ordine, con le ripetizioni consecutive compresse; impostato solo quando il modello è stato cambiato durante l'esecuzione. Richiede Claude Code v2.1.212 o successivo |
2007| `totalTokens` | number | `12450` | Numero di token dalla richiesta API finale del subagent: token di input, output e cache combinati. Non è un totale sull'intera esecuzione |2033| `totalTokens` | number | `12450` | Numero di token dalla richiesta API finale del subagent: token di input, di output e di cache combinati. Non è un totale sull'intera esecuzione |
2008| `totalDurationMs` | number | `48211` | Durata in tempo reale dell'esecuzione del subagent |2034| `totalDurationMs` | number | `48211` | Durata in tempo reale dell'esecuzione del subagent |
2009| `totalToolUseCount` | number | `7` | Numero di chiamate a strumenti effettuate dal subagent |2035| `totalToolUseCount` | number | `7` | Numero di chiamate agli strumenti effettuate dal subagent |
2010| `usage` | object | `{"input_tokens": 8320, ...}` | Suddivisione per tipo dei token della richiesta API finale: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |2036| `usage` | object | `{"input_tokens": 8320, ...}` | Ripartizione per tipo dei token della richiesta API finale: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |
2011 2037
2012Su Claude Code v2.1.271 o successiva, un subagent che viene eseguito con lo strumento [`SubagentHandback`](/docs/it/tools-reference), che Claude Code fornisce in [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), consegna il suo report tramite quello strumento anziché restituirlo come testo. Il campo `content` del suo risultato `completed` contiene allora una breve nota su quella consegna anziché il report stesso. Per leggere il report, fai corrispondere un hook `PreToolUse` o `PostToolUse` su `SubagentHandback` e leggi `tool_input.message`.2038In Claude Code v2.1.271 o successivo, un subagent eseguito con lo strumento [`SubagentHandback`](/docs/it/tools-reference), che Claude Code fornisce in [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), consegna il suo resoconto tramite quello strumento anziché restituirlo come testo. Il campo `content` del suo risultato `completed` contiene quindi una breve nota su quella consegna anziché il resoconto stesso. Per leggere il resoconto, fai corrispondere un hook `PreToolUse` o `PostToolUse` su `SubagentHandback` e leggi `tool_input.message`.
2013 2039
2014Per i subagent in background, lo strumento restituisce un risultato quando l'attività passa in background, quindi `tool_response` non contiene campi di utilizzo: un avvio in background restituisce immediatamente, e un'attività in primo piano che Claude Code sposta in background durante l'esecuzione restituisce in corrispondenza di quella transizione. Contiene `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel`.2040Per i subagent in background, lo strumento restituisce un risultato quando l'attività passa in background, quindi `tool_response` non contiene campi di utilizzo: un avvio in background restituisce immediatamente, e un'attività in primo piano che Claude Code sposta in background durante l'esecuzione restituisce al momento di quella transizione. Contiene `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel`.
2015 2041
2016In una risposta `completed`, `resolvedModel` indica il modello con cui il subagent è partito, che può differire dal valore `model` in `tool_input`, ad esempio quando si applica `availableModels` o un altro override. In una risposta `async_launched`, `resolvedModel` indica il modello in uso quando l'agente è passato in background, quindi un cambio avvenuto prima del passaggio in background viene riflesso lì. `modelsUsed` e il comportamento di `resolvedModel` al momento del passaggio in background richiedono Claude Code v2.1.212 o successiva.2042In una risposta `completed`, `resolvedModel` indica il modello con cui il subagent è partito, che può differire dal valore `model` in `tool_input`, ad esempio quando si applica `availableModels` o un altro override. In una risposta `async_launched`, `resolvedModel` indica il modello in uso quando l'agente è passato in background, quindi un cambio avvenuto prima del passaggio in background vi si riflette. `modelsUsed` e il comportamento di `resolvedModel` al momento del passaggio in background richiedono Claude Code v2.1.212 o successivo.
2017 2043
2018<a id="askuserquestion" />2044<a id="askuserquestion" />
2019 2045
2032 ExitPlanMode2058 ExitPlanMode
2033</h5>2059</h5>
2034 2060
2035Presenta un piano e chiede all'utente di approvarlo prima che Claude esca dal [plan mode](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode). Claude scrive il piano in un file su disco prima di chiamare lo strumento, quindi il `tool_input` letterale del modello è in genere vuoto. Claude Code inserisce il contenuto del piano e il percorso del file prima di passare l'input agli hook.2061Presenta un piano e chiede all'utente di approvarlo prima che Claude esca dal [plan mode](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode). Claude scrive il piano in un file su disco prima di chiamare lo strumento, quindi il `tool_input` letterale proveniente dal modello è tipicamente vuoto. Claude Code inserisce il contenuto del piano e il percorso del file prima di passare l'input agli hook.
2036 2062
2037| Campo | Tipo | Esempio | Descrizione |2063| Campo | Tipo | Esempio | Descrizione |
2038| :- | :- | :- | :- |2064| :- | :- | :- | :- |
2040| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Percorso del file del piano. Inserito |2066| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Percorso del file del piano. Inserito |
2041| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Deprecato. Claude Code accetta il campo ma lo ignora. Prima della v2.1.205, conteneva i permessi basati su prompt che Claude richiedeva per implementare il piano |2067| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Deprecato. Claude Code accetta il campo ma lo ignora. Prima della v2.1.205, conteneva i permessi basati su prompt che Claude richiedeva per implementare il piano |
2042 2068
2043In `PostToolUse`, `tool_response` è un oggetto con i campi `plan` e `filePath` che contengono il piano approvato, più alcuni flag di stato interni. Leggi `tool_response.plan` per il contenuto del piano anziché rileggere il file dal disco.2069In `PostToolUse`, `tool_response` è un oggetto con i campi `plan` e `filePath` che contengono il piano approvato, più flag di stato interni. Leggi `tool_response.plan` per il contenuto del piano anziché rileggere il file dal disco.
2044 2070
2045<h4 id="pretooluse-decision-control">2071<h4 id="pretooluse-decision-control">
2046 Controllo delle decisioni di PreToolUse2072 Controllo delle decisioni di PreToolUse
2047</h4>2073</h4>
2048 2074
2049Gli hook `PreToolUse` possono controllare se una chiamata a uno strumento procede. A differenza di altri hook che usano un campo `decision` di primo livello, PreToolUse restituisce la sua decisione all'interno di un oggetto `hookSpecificOutput`. Questo gli offre un controllo più ricco: quattro esiti (allow, deny, ask o defer) più la possibilità di modificare l'input dello strumento prima dell'esecuzione.2075Gli hook `PreToolUse` possono controllare se una chiamata a uno strumento procede. A differenza di altri hook che usano un campo `decision` di primo livello, PreToolUse restituisce la sua decisione all'interno di un oggetto `hookSpecificOutput`. Questo gli conferisce un controllo più ricco: quattro esiti (consentire, negare, chiedere conferma o differire) più la possibilità di modificare l'input dello strumento prima dell'esecuzione.
2050 2076
2051| Campo | Descrizione |2077| Campo | Descrizione |
2052| :- | :- |2078| :- | :- |
2053| `permissionDecision` | `"allow"` salta la richiesta di permesso, tranne per le [azioni che nessuna modalità approva automaticamente](/docs/it/permission-modes#actions-no-mode-auto-approves), per le [letture da percorsi di rete](/docs/it/permissions#network-paths), e per `AskUserQuestion` ed `ExitPlanMode`, che richiedono [`updatedInput` abbinato](#allow-with-updatedinput). `"deny"` impedisce la chiamata allo strumento. `"ask"` chiede all'utente di confermare. `"defer"` esce in modo ordinato così che lo strumento possa essere ripreso in seguito. Le [regole di negazione e di richiesta](/docs/it/permissions#manage-permissions) vengono comunque valutate indipendentemente da ciò che l'hook restituisce |2079| `permissionDecision` | `"allow"` salta la richiesta di permesso, tranne per le [azioni che nessuna modalità approva automaticamente](/docs/it/permission-modes#actions-no-mode-auto-approves), per le [letture da percorsi di rete](/docs/it/permissions#network-paths) e per `AskUserQuestion` e `ExitPlanMode`, che richiedono [`updatedInput` abbinato](#allow-with-updatedinput). `"deny"` impedisce la chiamata allo strumento. `"ask"` chiede all'utente di confermare. `"defer"` esce in modo ordinato così lo strumento può essere ripreso più tardi. Le [regole di negazione e di richiesta di conferma](/docs/it/permissions#manage-permissions) vengono comunque valutate indipendentemente da ciò che l'hook restituisce |
2054| `permissionDecisionReason` | Per `"ask"`, mostrato all'utente nella richiesta di permesso. Quando Claude Code [nega la chiamata](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs) in un'esecuzione `-p` in cui nessuno può rispondere a quella richiesta, Claude legge invece il motivo nel risultato dello strumento. Per `"deny"`, mostrato a Claude. Per `"allow"` e `"defer"`, scritto solo nel [log di debug](#debug-hooks) |2080| `permissionDecisionReason` | Per `"ask"`, mostrato all'utente nella richiesta di permesso. Quando Claude Code [nega la chiamata](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs) in un'esecuzione `-p` in cui nessuno può rispondere a quella richiesta, Claude legge invece il motivo nel risultato dello strumento. Per `"deny"`, mostrato a Claude. Per `"allow"` e `"defer"`, scritto solo nel [log di debug](#debug-hooks) |
2055| `updatedInput` | Modifica i parametri di input dello strumento prima dell'esecuzione. Sostituisce l'intero oggetto di input, quindi includi i campi invariati insieme a quelli modificati. Claude Code valuta le regole di permesso e l'[idoneità al passaggio automatico in background](/docs/it/tools-reference#foreground-commands-that-move-to-the-background) di un comando Bash rispetto all'input restituito dal tuo hook, non all'input inviato da Claude. Combinalo con `"allow"` per approvare automaticamente, oppure con `"ask"` per mostrare l'input modificato all'utente. Per `"defer"`, viene ignorato |2081| `updatedInput` | Modifica i parametri di input dello strumento prima dell'esecuzione. Sostituisce l'intero oggetto di input, quindi includi i campi non modificati insieme a quelli modificati. Claude Code valuta le regole di permesso e l'[idoneità al passaggio automatico in background](/docs/it/tools-reference#foreground-commands-that-move-to-the-background) di un comando Bash sull'input restituito dal tuo hook, non sull'input inviato da Claude. Combinalo con `"allow"` per approvare automaticamente, oppure con `"ask"` per mostrare all'utente l'input modificato. Per `"defer"`, ignorato |
2056| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Ignorata quando `permissionDecision` è `"defer"`. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |2082| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Ignorata quando `permissionDecision` è `"defer"`. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |
2057 2083
2058Quando più hook PreToolUse restituiscono decisioni diverse, la precedenza è `deny` > `defer` > `ask` > `allow`.2084Quando più hook PreToolUse restituiscono decisioni diverse, l'ordine di precedenza è `deny` > `defer` > `ask` > `allow`.
2059 2085
2060Un hook che blocca uscendo con 2 segue lo stesso percorso di `"deny"`: Claude vede il messaggio di stderr come motivo della negazione.2086Un hook che blocca uscendo con 2 viene instradato allo stesso modo di `"deny"`: Claude vede il messaggio di stderr come motivo della negazione.
2061 2087
2062Quando un hook restituisce `"ask"`, la richiesta di permesso mostrata all'utente include un'etichetta che identifica la provenienza dell'hook: `[settings]` per un hook da qualsiasi file di impostazioni o dal frontmatter di un agente, `[plugin:<name>]` per l'hook di un plugin, oppure `[skill]` per un hook dal frontmatter di una skill. Questo aiuta gli utenti a capire quale fonte di configurazione sta richiedendo la conferma.2088Quando un hook restituisce `"ask"`, la richiesta di permesso mostrata all'utente include un'etichetta che identifica la provenienza dell'hook: `[settings]` per un hook da qualsiasi file di impostazioni o dal frontmatter di un agente, `[plugin:<name>]` per l'hook di un plugin, oppure `[skill]` per un hook dal frontmatter di una skill. Questo aiuta gli utenti a capire quale fonte di configurazione sta richiedendo la conferma.
2063 2089
2064Un `"ask"` di un hook forza una richiesta di permesso anche in [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode): il classificatore può comunque negare la chiamata allo strumento, ma non può approvarla silenziosamente. Prima della v2.1.211, il classificatore poteva approvare un comando Bash eseguito fuori dalla [sandbox](/docs/it/sandboxing) senza mostrare la richiesta voluta dall'hook; il classificatore applicava comunque le proprie regole di sicurezza a quel comando, e un `"deny"` di un hook veniva sempre rispettato.2090Un `"ask"` di un hook forza una richiesta di permesso anche in [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode): il classificatore può comunque negare la chiamata allo strumento, ma non può approvarla silenziosamente. Prima della v2.1.211, il classificatore poteva approvare un comando Bash eseguito al di fuori della [sandbox](/docs/it/sandboxing) senza mostrare la richiesta richiesta dall'hook; il classificatore applicava comunque a quel comando le proprie regole di sicurezza, e un `"deny"` di un hook veniva sempre rispettato.
2065 2091
2066```json theme={null}2092```json theme={null}
2067{2093{
2078```2104```
2079 2105
2080<Note>2106<Note>
2081 In precedenza PreToolUse usava i campi di primo livello `decision` e `reason`, ma questi sono deprecati per questo evento. Usa invece `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason`. I valori deprecati `"approve"` e `"block"` corrispondono rispettivamente a `"allow"` e `"deny"`. Altri eventi come PostToolUse e Stop continuano a usare `decision` e `reason` di primo livello come formato corrente.2107 In precedenza PreToolUse usava i campi di primo livello `decision` e `reason`, ma questi sono deprecati per questo evento. Usa invece `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason`. I valori deprecati `"approve"` e `"block"` corrispondono rispettivamente a `"allow"` e `"deny"`. Altri eventi come PostToolUse e Stop continuano a usare `decision` e `reason` di primo livello come formato attuale.
2082</Note>2108</Note>
2083 2109
2084<h4 id="allow-with-updatedinput">2110<h4 id="allow-with-updatedinput">
2085 Strumenti che richiedono l'interazione dell'utente2111 Strumenti che richiedono l'interazione dell'utente
2086</h4>2112</h4>
2087 2113
2088`AskUserQuestion` e `ExitPlanMode` richiedono l'interazione dell'utente. In [modalità non interattiva](/docs/it/headless) con il flag `-p`, Claude Code li offre solo quando l'esecuzione dispone di un [host dei permessi](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs) che riceva la richiesta, come un callback `canUseTool` dell'Agent SDK.2114`AskUserQuestion` e `ExitPlanMode` richiedono l'interazione dell'utente. In [modalità non interattiva](/docs/it/headless) con il flag `-p`, Claude Code li offre solo quando l'esecuzione ha un [host dei permessi](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs) che riceva la richiesta, come un callback `canUseTool` dell'Agent SDK.
2089 2115
2090Un hook `PreToolUse` soddisfa quel requisito quando fa quanto segue:2116Un hook `PreToolUse` soddisfa questo requisito quando fa quanto segue:
2091 2117
20921. Legge l'input dello strumento da stdin21181. Legge l'input dello strumento da stdin
20932. Raccoglie la risposta tramite la tua interfaccia utente21192. Raccoglie la risposta tramite la tua interfaccia utente
20943. Restituisce `permissionDecision: "allow"` insieme a un `updatedInput` che contiene la risposta, così lo strumento viene eseguito senza chiedere21203. Restituisce `permissionDecision: "allow"` insieme a `updatedInput` contenente la risposta, così lo strumento viene eseguito senza chiedere conferma
2095 2121
2096Restituire solo `"allow"` non è sufficiente per questi strumenti.2122Restituire solo `"allow"` non è sufficiente per questi strumenti.
2097 2123
2098Per `AskUserQuestion`, restituisci l'array `questions` originale e aggiungi un oggetto [`answers`](#askuserquestion) che associa il testo di ogni domanda alla risposta scelta. Questo output risponde a una domanda con `React`:2124Per `AskUserQuestion`, restituisci l'array `questions` originale e aggiungi un oggetto [`answers`](#askuserquestion) che associa il testo di ciascuna domanda alla risposta scelta. Questo output risponde a una domanda con `React`:
2099 2125
2100```json theme={null}2126```json theme={null}
2101{2127{
2117}2143}
2118```2144```
2119 2145
2120Uno strumento MCP che il suo server contrassegna con [`_meta["anthropic/requiresUserInteraction"]`](/docs/it/mcp#require-approval-for-a-specific-tool) è più restrittivo: un hook non può saltare la sua richiesta di approvazione con `"allow"`, con o senza `updatedInput`, perché Claude Code non può confermare che l'hook abbia raccolto l'interazione di cui lo strumento ha bisogno.2146Uno strumento MCP che il suo server contrassegna con [`_meta["anthropic/requiresUserInteraction"]`](/docs/it/mcp#require-approval-for-a-specific-tool) è più restrittivo: un hook non può saltare la sua richiesta di approvazione con `"allow"`, con o senza `updatedInput`, perché Claude Code non può verificare che l'hook abbia raccolto l'interazione di cui lo strumento ha bisogno.
2121 2147
2122<h4 id="defer-a-tool-call-for-later">2148<h4 id="defer-a-tool-call-for-later">
2123 Differire una chiamata a uno strumento2149 Differire una chiamata a uno strumento
2124</h4>2150</h4>
2125 2151
2126`"defer"` è pensato per le integrazioni che eseguono `claude -p` come sottoprocesso e leggono il suo output JSON, come un'app dell'Agent SDK o un'interfaccia utente personalizzata costruita su Claude Code. Consente a quel processo chiamante di mettere in pausa Claude a una chiamata a uno strumento, raccogliere input tramite la propria interfaccia e riprendere da dove si era interrotto. Claude Code rispetta questo valore solo in [modalità non interattiva](/docs/it/headless) con il flag `-p`. Nelle sessioni interattive registra un avviso e ignora il risultato dell'hook.2152`"defer"` è pensato per le integrazioni che eseguono `claude -p` come sottoprocesso e ne leggono l'output JSON, come un'app Agent SDK o un'interfaccia utente personalizzata costruita su Claude Code. Consente a quel processo chiamante di mettere in pausa Claude a una chiamata a uno strumento, raccogliere input tramite la propria interfaccia e riprendere da dove si era interrotto. Claude Code rispetta questo valore solo in [modalità non interattiva](/docs/it/headless) con il flag `-p`. Nelle sessioni interattive registra un avviso e ignora il risultato dell'hook.
2127 2153
2128Lo strumento `AskUserQuestion` è il caso tipico: Claude vuole chiedere qualcosa all'utente, ma non c'è alcun terminale in cui rispondere. Un'esecuzione `-p` offre `AskUserQuestion` solo quando dispone di un [host dei permessi](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs), come uno strumento MCP che passi con `--permission-prompt-tool`, quindi avvia l'esecuzione con uno di essi. Il ciclo completo funziona così:2154Lo strumento `AskUserQuestion` è il caso tipico: Claude vuole chiedere qualcosa all'utente, ma non c'è un terminale in cui rispondere. Un'esecuzione `-p` offre `AskUserQuestion` solo quando ha un [host dei permessi](/docs/it/headless#turn-off-permission-prompts-in-unattended-runs), come uno strumento MCP che passi con `--permission-prompt-tool`, quindi avvia l'esecuzione con uno di essi. Il ciclo completo funziona così:
2129 2155
21301. Claude chiama `AskUserQuestion`. L'hook `PreToolUse` viene attivato.21561. Claude chiama `AskUserQuestion`. L'hook `PreToolUse` si attiva.
21312. L'hook restituisce `permissionDecision: "defer"`. Lo strumento non viene eseguito. Il processo esce con `stop_reason: "tool_deferred"` e la chiamata allo strumento in sospeso viene conservata nella trascrizione.21572. L'hook restituisce `permissionDecision: "defer"`. Lo strumento non viene eseguito. Il processo esce con `stop_reason: "tool_deferred"` e la chiamata allo strumento in sospeso viene preservata nella trascrizione.
21323. Il processo chiamante legge `deferred_tool_use` dal risultato dell'SDK, presenta la domanda nella propria interfaccia utente e attende una risposta.21583. Il processo chiamante legge `deferred_tool_use` dal risultato dell'SDK, presenta la domanda nella propria interfaccia utente e attende una risposta.
21334. Il processo chiamante esegue `claude -p --resume <session-id>` con lo stesso host dei permessi. La stessa chiamata allo strumento attiva di nuovo `PreToolUse`.21594. Il processo chiamante esegue `claude -p --resume <session-id>` con lo stesso host dei permessi. La stessa chiamata allo strumento attiva di nuovo `PreToolUse`.
21345. L'hook restituisce `permissionDecision: "allow"` con la risposta in `updatedInput`. Lo strumento viene eseguito e Claude continua.21605. L'hook restituisce `permissionDecision: "allow"` con la risposta in `updatedInput`. Lo strumento viene eseguito e Claude continua.
2135 2161
2136Il campo `deferred_tool_use` contiene `id`, `name` e `input` dello strumento. L'`input` è costituito dai parametri generati da Claude per la chiamata allo strumento, acquisiti prima dell'esecuzione:2162Il campo `deferred_tool_use` contiene `id`, `name` e `input` dello strumento. L'`input` sono i parametri che Claude ha generato per la chiamata allo strumento, catturati prima dell'esecuzione:
2137 2163
2138```json theme={null}2164```json theme={null}
2139{2165{
2149}2175}
2150```2176```
2151 2177
2152Non esiste alcun timeout né limite di nuovi tentativi. La sessione rimane su disco finché non la riprendi, salvo la pulizia di conservazione di [`cleanupPeriodDays`](/docs/it/settings-reference#cleanupperioddays), che elimina i file di sessione dopo 30 giorni per impostazione predefinita, secondo le [regole della pulizia di conservazione](/docs/it/claude-directory#cleaned-up-automatically). Se la risposta non è pronta quando riprendi, l'hook può restituire di nuovo `"defer"` e il processo esce allo stesso modo. Il processo chiamante decide quando interrompere il ciclo restituendo infine `"allow"` o `"deny"` dall'hook.2178Non esiste alcun timeout né limite di nuovi tentativi. La sessione rimane su disco finché non la riprendi, fatto salvo il ciclo di pulizia per la conservazione di [`cleanupPeriodDays`](/docs/it/settings-reference#cleanupperioddays), che per impostazione predefinita elimina i file di sessione dopo 30 giorni, secondo le [regole del ciclo di pulizia](/docs/it/claude-directory#cleaned-up-automatically). Se la risposta non è pronta quando riprendi, l'hook può restituire di nuovo `"defer"` e il processo esce allo stesso modo. Il processo chiamante decide quando interrompere il ciclo restituendo infine `"allow"` o `"deny"` dall'hook.
2153 2179
2154`"defer"` funziona solo quando Claude effettua una singola chiamata a uno strumento nel turno. Se Claude effettua più chiamate a strumenti contemporaneamente, `"defer"` viene ignorato con un avviso e lo strumento procede attraverso il normale flusso dei permessi. Il vincolo esiste perché la ripresa può rieseguire un solo strumento: non c'è modo di differire una chiamata di un gruppo senza lasciare irrisolte le altre.2180`"defer"` funziona solo quando Claude effettua una singola chiamata a uno strumento nel turno. Se Claude effettua più chiamate agli strumenti contemporaneamente, `"defer"` viene ignorato con un avviso e lo strumento procede attraverso il normale flusso dei permessi. Il vincolo esiste perché la ripresa può rieseguire un solo strumento: non c'è modo di differire una chiamata di un gruppo senza lasciare le altre irrisolte.
2155 2181
2156Se 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 venga attivato. Questo accade quando un server MCP che forniva lo strumento non è connesso per la sessione ripresa. Il payload `deferred_tool_use` è comunque incluso, così puoi identificare quale strumento è venuto a mancare.2182Se lo strumento differito non è più disponibile quando riprendi, il processo esce con `stop_reason: "tool_deferred_unavailable"` e `is_error: true` prima che l'hook si attivi. Questo accade quando un server MCP che forniva lo strumento non è connesso per la sessione ripresa. Il payload `deferred_tool_use` viene comunque incluso così puoi identificare quale strumento è venuto a mancare.
2157 2183
2158<Note>2184<Note>
2159 Per riprendere una sessione differita in plan mode, 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. Per le altre condizioni, consulta [Riprendere in plan mode con `-p`](/docs/it/sessions#resume-in-plan-mode-with-p). Richiede Claude Code v2.1.246 o successiva.2185 Per riprendere una sessione differita in plan mode, 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. Per le altre condizioni, consulta [Riprendere in plan mode con `-p`](/docs/it/sessions#resume-in-plan-mode-with-p). Richiede Claude Code v2.1.246 o successivo.
2160 2186
2161 Quando riprendi con `-p`, Claude Code non ripristina nessun'altra modalità di permesso memorizzata. Avvia l'esecuzione nella modalità di permesso in cui partirebbe una nuova esecuzione `claude -p`, quindi passa di nuovo `--permission-mode` o `--dangerously-skip-permissions` se la sessione differita ne usava uno. Quando riprendi con `claude --resume <session-id>` senza `-p`, Claude Code ripristina la modalità di permesso memorizzata, con le eccezioni elencate in [modalità di permesso alla ripresa](/docs/it/sessions#permission-mode-on-resume).2187 Quando riprendi con `-p`, Claude Code non ripristina nessun'altra modalità di permesso memorizzata. Avvia l'esecuzione nella modalità di permesso in cui partirebbe una nuova esecuzione `claude -p`, quindi passa di nuovo `--permission-mode` o `--dangerously-skip-permissions` se la sessione differita ne usava uno. Quando riprendi con `claude --resume <session-id>` senza `-p`, Claude Code ripristina la modalità di permesso memorizzata, con le eccezioni elencate in [modalità di permesso alla ripresa](/docs/it/sessions#permission-mode-on-resume).
2162</Note>2188</Note>
2178 Input di PermissionRequest2204 Input di PermissionRequest
2179</h4>2205</h4>
2180 2206
2181Gli hook PermissionRequest ricevono i campi `tool_name` e `tool_input` come gli hook PreToolUse, ma senza `tool_use_id`. Per uno strumento MCP, ricevono anche l'oggetto [`mcp_server`](#pretooluse-input). Un array facoltativo `permission_suggestions` contiene gli [aggiornamenti dei permessi](#permission-update-entries) che Claude Code suggerisce per questa richiesta, come l'aggiunta di una regola di consenso o la modifica della modalità di permesso.2207Gli hook PermissionRequest ricevono i campi `tool_name` e `tool_input` come gli hook PreToolUse, ma senza `tool_use_id`. Per uno strumento MCP, ricevono anche l'oggetto [`mcp_server`](#pretooluse-input). Un array facoltativo `permission_suggestions` contiene gli [aggiornamenti dei permessi](#permission-update-entries) che Claude Code suggerisce per questa richiesta, come l'aggiunta di una regola allow o la modifica della modalità di permesso.
2182 2208
2183L'array `permission_suggestions` non è un elenco esatto delle opzioni che vedi, perché ogni finestra di dialogo dei permessi costruisce le proprie opzioni. Alcune finestre di dialogo, come quella per le modifiche ai file, non leggono affatto l'array e ricavano le loro opzioni dalla richiesta stessa. Una finestra di dialogo che lo legge può comunque nascondere un'opzione il cui suggerimento resta 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 alcuna voce di suggerimento, come [**Yes, and switch to auto mode**](/docs/it/permission-modes#switch-permission-modes), che cambia direttamente la modalità di permesso anziché tramite un aggiornamento dei permessi.2209L'array `permission_suggestions` non è un elenco esatto delle opzioni che vedi, perché ogni finestra di dialogo dei permessi costruisce le proprie opzioni. Alcune finestre di dialogo, come quella per le modifiche ai file, non leggono affatto l'array e ricavano le proprie opzioni dalla richiesta stessa. Una finestra di dialogo che lo legge può comunque nascondere un'opzione il cui suggerimento rimane nell'array, ad esempio quando [`allowManagedPermissionRulesOnly`](/docs/it/settings-reference#allowmanagedpermissionrulesonly) nasconde le opzioni per salvare le 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 direttamente la modalità di permesso anziché tramite un aggiornamento dei permessi.
2184 2210
2185Gli hook PreToolUse vengono eseguiti prima di ogni chiamata a uno strumento, che richieda o meno un permesso. Gli hook PermissionRequest vengono eseguiti solo quando Claude Code sta per chiederti il permesso, oppure quando altrimenti negherebbe automaticamente una chiamata che non può mostrare una richiesta. Nessuno dei due eventi viene attivato per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).2211Gli hook PreToolUse vengono eseguiti prima di ogni chiamata a uno strumento, che richieda o meno un permesso. Gli hook PermissionRequest vengono eseguiti solo quando Claude Code sta per chiederti un permesso, o quando altrimenti negherebbe automaticamente una chiamata che non può mostrare una richiesta. Nessuno dei due eventi si attiva per [`EndConversation`](/docs/it/tools-reference#endconversation-tool-behavior).
2186 2212
2187```json theme={null}2213```json theme={null}
2188{2214{
2211 Controllo delle decisioni di PermissionRequest2237 Controllo delle decisioni di PermissionRequest
2212</h4>2238</h4>
2213 2239
2214Gli hook `PermissionRequest` possono consentire o negare le richieste di permesso. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, il tuo script di hook può restituire un oggetto `decision` con questi campi specifici dell'evento:2240Gli hook `PermissionRequest` possono consentire o negare le richieste di permesso. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, lo script del tuo hook può restituire un oggetto `decision` con questi campi specifici dell'evento:
2215 2241
2216| Campo | Descrizione |2242| Campo | Descrizione |
2217| :- | :- |2243| :- | :- |
2218| `behavior` | `"allow"` concede il permesso, `"deny"` lo nega. Le [regole di negazione e di richiesta](/docs/it/permissions#manage-permissions) vengono comunque valutate, quindi un hook che restituisce `"allow"` non sovrascrive una regola di negazione corrispondente |2244| `behavior` | `"allow"` concede il permesso, `"deny"` lo nega. Le [regole deny e ask](/docs/it/permissions#manage-permissions) vengono comunque valutate, quindi un hook che restituisce `"allow"` non sovrascrive una regola deny corrispondente |
2219| `updatedInput` | Solo per `"allow"`: modifica i parametri di input dello strumento prima dell'esecuzione. Sostituisce l'intero oggetto di input, quindi includi i campi invariati insieme a quelli modificati. L'input modificato viene rivalutato rispetto alle regole di negazione e di richiesta |2245| `updatedInput` | Solo per `"allow"`: modifica i parametri di input dello strumento prima dell'esecuzione. Sostituisce l'intero oggetto di input, quindi includi i campi invariati insieme a quelli modificati. L'input modificato viene rivalutato rispetto alle regole deny e ask |
2220| `updatedPermissions` | Solo per `"allow"`: array di [voci di aggiornamento dei permessi](#permission-update-entries) da applicare, come l'aggiunta di una regola di consenso o la modifica della modalità di permesso della sessione |2246| `updatedPermissions` | Solo per `"allow"`: array di [voci di aggiornamento dei permessi](#permission-update-entries) da applicare, come l'aggiunta di una regola allow o la modifica della modalità di permesso della sessione |
2221| `message` | Solo per `"deny"`: comunica a Claude perché il permesso è stato negato |2247| `message` | Solo per `"deny"`: indica a Claude perché il permesso è stato negato |
2222| `interrupt` | Solo per `"deny"`: se `true`, ferma Claude |2248| `interrupt` | Solo per `"deny"`: se `true`, arresta Claude |
2223 2249
2224Un hook che esce con codice 2 senza un oggetto `decision` lascia invariato il flusso dei permessi, e il suo stderr viene scartato. Per concedere o negare la richiesta, restituisci l'oggetto `decision`.2250Un hook che termina con codice 2 senza un oggetto `decision` lascia invariato il flusso dei permessi, e il suo stderr viene scartato. Per concedere o negare la richiesta, restituisci l'oggetto `decision`.
2225 2251
2226```json theme={null}2252```json theme={null}
2227{2253{
2241 Voci di aggiornamento dei permessi2267 Voci di aggiornamento dei permessi
2242</h4>2268</h4>
2243 2269
2244Il campo di output `updatedPermissions` e il [campo di input `permission_suggestions`](#permissionrequest-input) usano entrambi lo stesso array di oggetti voce. Ogni voce ha un `type` che determina i suoi altri campi e una `destination` che controlla dove viene scritta la modifica.2270Il campo di output `updatedPermissions` e il [campo di input `permission_suggestions`](#permissionrequest-input) usano entrambi lo stesso array di oggetti voce. Ogni voce ha un `type` che determina gli altri campi e una `destination` che controlla dove viene scritta la modifica.
2245 2271
2246| `type` | Campi | Effetto |2272| `type` | Campi | Effetto |
2247| :- | :- | :- |2273| :- | :- | :- |
2253| `removeDirectories` | `directories`, `destination` | Rimuove directory di lavoro |2279| `removeDirectories` | `directories`, `destination` | Rimuove directory di lavoro |
2254 2280
2255<Note>2281<Note>
2256 `setMode` con `bypassPermissions` ha effetto solo se hai avviato la sessione con la modalità bypass già disponibile: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` oppure `permissions.defaultMode: "bypassPermissions"` nelle [impostazioni utente, in `--settings` o nelle impostazioni gestite](/docs/it/settings-reference#permissions-defaultmode). Altrimenti l'aggiornamento non ha alcun effetto. L'aggiornamento non ha effetto neanche quando [`permissions.disableBypassPermissionsMode`](/docs/it/permissions#managed-settings) disabilita la modalità, o quando la sessione si avvia in [modalità limitata](/docs/it/cli-reference#cli-flags).2282 `setMode` con `bypassPermissions` ha effetto solo se hai avviato la sessione con la modalità bypass già disponibile: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` oppure `permissions.defaultMode: "bypassPermissions"` nelle [impostazioni utente, `--settings` o impostazioni gestite](/docs/it/settings-reference#permissions-defaultmode). Altrimenti l'aggiornamento non ha alcun effetto. L'aggiornamento non ha effetto neanche quando [`permissions.disableBypassPermissionsMode`](/docs/it/permissions#managed-settings) disabilita la modalità, o quando la sessione si avvia in [modalità con restrizioni](/docs/it/cli-reference#cli-flags).
2257 2283
2258 `bypassPermissions` non viene mai salvato in modo persistente come `defaultMode`, indipendentemente dalla `destination`.2284 `bypassPermissions` non viene mai salvato come `defaultMode`, indipendentemente da `destination`.
2259</Note>2285</Note>
2260 2286
2261Il campo `destination` di ogni voce determina se la modifica resta in memoria o viene salvata in modo persistente in un file di impostazioni.2287Il campo `destination` di ogni voce determina se la modifica rimane in memoria o viene salvata in un file di impostazioni.
2262 2288
2263| `destination` | Scrive in |2289| `destination` | Scrive in |
2264| :- | :- |2290| :- | :- |
2265| `session` | solo in memoria, scartata quando la sessione termina |2291| `session` | solo in memoria, scartato al termine della sessione |
2266| `localSettings` | `.claude/settings.local.json` |2292| `localSettings` | `.claude/settings.local.json` |
2267| `projectSettings` | `.claude/settings.json` |2293| `projectSettings` | `.claude/settings.json` |
2268| `userSettings` | `~/.claude/settings.json` |2294| `userSettings` | `~/.claude/settings.json` |
2280Usa una corrispondenza più ampia quando il nome dello strumento non è il filtro giusto:2306Usa una corrispondenza più ampia quando il nome dello strumento non è il filtro giusto:
2281 2307
2282* Per eseguire un hook dopo che qualsiasi strumento è stato completato con successo, ometti il `matcher` o impostalo su `"*"`. Il tuo hook può quindi scoprire da solo cosa è cambiato, ad esempio eseguendo `git status --porcelain`, che elenca anche i file non tracciati che `git diff` non rileva. Per le chiamate agli strumenti che falliscono, aggiungi lo stesso hook sotto [PostToolUseFailure](#posttoolusefailure).2308* Per eseguire un hook dopo che qualsiasi strumento è stato completato con successo, ometti il `matcher` o impostalo su `"*"`. Il tuo hook può quindi scoprire da solo cosa è cambiato, ad esempio eseguendo `git status --porcelain`, che elenca anche i file non tracciati che `git diff` non rileva. Per le chiamate agli strumenti che falliscono, aggiungi lo stesso hook sotto [PostToolUseFailure](#posttoolusefailure).
2283* Per eseguire un hook quando un file specifico cambia su disco, indipendentemente da chi lo abbia scritto, usa [FileChanged](#filechanged). Claude Code non esegue un hook `PostToolUse` con corrispondenza `Edit|Write` quando un comando `Bash` o un processo esterno a Claude Code riscrive lo stesso file.2309* Per eseguire un hook quando un file specifico cambia su disco, indipendentemente da chi l'ha scritto, usa [FileChanged](#filechanged). Claude Code non esegue un hook `PostToolUse` che corrisponde a `Edit|Write` quando un comando `Bash` o un processo esterno a Claude Code riscrive lo stesso file.
2284 2310
2285<h4 id="posttooluse-input">2311<h4 id="posttooluse-input">
2286 Input di PostToolUse2312 Input di PostToolUse
2287</h4>2313</h4>
2288 2314
2289Gli hook `PostToolUse` si attivano dopo che uno strumento è già stato eseguito con successo. L'input include sia `tool_input`, gli argomenti inviati allo strumento, sia `tool_response`, il risultato che ha restituito. Lo schema esatto di entrambi dipende dallo strumento. I percorsi in `tool_input` degli strumenti per i file arrivano nello stesso formato di [PreToolUse](#pretooluse-input): sempre assoluti, con i separatori nativi della piattaforma, quindi barre rovesciate su Windows. Per uno strumento MCP, l'input contiene anche l'oggetto [`mcp_server`](#pretooluse-input).2315Gli hook `PostToolUse` si attivano dopo che uno strumento è già stato eseguito con successo. L'input include sia `tool_input`, gli argomenti inviati allo strumento, sia `tool_response`, il risultato restituito. Lo schema esatto di entrambi dipende dallo strumento. I percorsi in `tool_input` degli strumenti per i file arrivano nello stesso formato di [PreToolUse](#pretooluse-input): sempre assoluti, con i separatori nativi della piattaforma, quindi barre rovesciate su Windows. Per uno strumento MCP, l'input contiene anche l'oggetto [`mcp_server`](#pretooluse-input).
2290 2316
2291```json theme={null}2317```json theme={null}
2292{2318{
2317 Controllo delle decisioni di PostToolUse2343 Controllo delle decisioni di PostToolUse
2318</h4>2344</h4>
2319 2345
2320Gli hook `PostToolUse` possono fornire feedback a Claude dopo l'esecuzione dello strumento. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, il tuo script di hook può restituire questi campi specifici dell'evento:2346Gli hook `PostToolUse` possono fornire un feedback a Claude dopo l'esecuzione dello strumento. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, lo script del tuo hook può restituire questi campi specifici dell'evento:
2321 2347
2322| Campo | Descrizione |2348| Campo | Descrizione |
2323| :- | :- |2349| :- | :- |
2324| `decision` | `"block"` aggiunge il `reason` accanto al risultato dello strumento. Claude vede comunque l'output originale; per sostituirlo, usa `updatedToolOutput` |2350| `decision` | `"block"` aggiunge il `reason` accanto al risultato dello strumento. Claude vede comunque l'output originale; per sostituirlo, usa `updatedToolOutput` |
2325| `reason` | Spiegazione mostrata a Claude quando `decision` è `"block"` |2351| `reason` | Spiegazione mostrata a Claude quando `decision` è `"block"` |
2326| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |2352| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Vedi [Aggiungere contesto per Claude](#add-context-for-claude) |
2327| `classifierContext` | Breve nota sul risultato di questa chiamata destinata al classificatore della [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) anziché a Claude. Consulta [Annotare un risultato per il classificatore della modalità auto](#annotate-a-result-for-the-auto-mode-classifier). Richiede Claude Code v2.1.236 o successiva |2353| `classifierContext` | Breve nota sul risultato di questa chiamata destinata al classificatore della [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) anziché a Claude. Vedi [Annotare un risultato per il classificatore della modalità auto](#annotate-a-result-for-the-auto-mode-classifier). Richiede Claude Code v2.1.236 o successivo |
2328| `updatedToolOutput` | Sostituisce l'output dello strumento con il valore fornito prima che venga inviato a Claude. Il valore deve corrispondere alla struttura dell'output dello strumento |2354| `updatedToolOutput` | Sostituisce l'output dello strumento con il valore fornito prima che venga inviato a Claude. Il valore deve corrispondere alla struttura dell'output dello strumento |
2329| `updatedMCPToolOutput` | Sostituisce l'output solo per gli [strumenti MCP](#match-mcp-tools). Preferisci `updatedToolOutput`, che funziona per tutti gli strumenti |2355| `updatedMCPToolOutput` | Sostituisce l'output solo per gli [strumenti MCP](#match-mcp-tools). Preferisci `updatedToolOutput`, che funziona per tutti gli strumenti |
2330 2356
2346```2372```
2347 2373
2348<Warning>2374<Warning>
2349 `updatedToolOutput` modifica solo ciò che vede Claude. Lo strumento è già stato eseguito quando l'hook si attiva, quindi eventuali file scritti, comandi eseguiti o richieste di rete inviate hanno già avuto effetto. Anche la telemetria, come gli span degli strumenti OpenTelemetry e gli eventi di analisi, acquisisce l'output originale prima dell'esecuzione dell'hook. Per impedire o modificare una chiamata a uno strumento prima che venga eseguita, usa invece un hook [PreToolUse](#pretooluse).2375 `updatedToolOutput` cambia solo ciò che vede Claude. Lo strumento è già stato eseguito quando l'hook si attiva, quindi eventuali file scritti, comandi eseguiti o richieste di rete inviate hanno già avuto effetto. Anche la telemetria, come gli span degli strumenti OpenTelemetry e gli eventi di analisi, acquisisce l'output originale prima che l'hook venga eseguito. Per impedire o modificare una chiamata a uno strumento prima che venga eseguita, usa invece un hook [PreToolUse](#pretooluse).
2350 2376
2351 Il valore sostitutivo deve corrispondere alla struttura dell'output dello strumento. Gli strumenti integrati restituiscono oggetti strutturati anziché semplici stringhe. Ad esempio, `Bash` restituisce un oggetto con i campi `stdout`, `stderr`, `interrupted` e `isImage`. Per gli strumenti integrati, un valore che non corrisponde allo schema di output dello strumento viene ignorato e viene usato l'output originale. L'output degli strumenti MCP viene passato senza validazione dello schema. Rimuovere dettagli di errore di cui Claude ha bisogno può indurlo a procedere sulla base di un presupposto errato.2377 Il valore sostitutivo deve corrispondere alla struttura dell'output dello strumento. Gli strumenti integrati restituiscono oggetti strutturati anziché semplici stringhe. Ad esempio, `Bash` restituisce un oggetto con i campi `stdout`, `stderr`, `interrupted` e `isImage`. Per gli strumenti integrati, un valore che non corrisponde allo schema di output dello strumento viene ignorato e viene usato l'output originale. L'output degli strumenti MCP viene passato senza validazione dello schema. Rimuovere dettagli sugli errori di cui Claude ha bisogno può portarlo a procedere sulla base di un presupposto errato.
2352</Warning>2378</Warning>
2353 2379
2354<h4 id="annotate-a-result-for-the-auto-mode-classifier">2380<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2355 Annotare un risultato per il classificatore della modalità auto2381 Annotare un risultato per il classificatore della modalità auto
2356</h4>2382</h4>
2357 2383
2358Restituisci `classifierContext` per inviare una breve nota sul risultato della chiamata allo strumento al classificatore della [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) anziché a Claude. Il classificatore [non riceve mai i risultati degli strumenti in sé](/docs/it/permission-modes#how-the-classifier-evaluates-actions), quindi questo campo è il modo supportato per comunicargli qualcosa su ciò che una chiamata ha restituito prima che esamini le azioni successive. Il campo richiede Claude Code v2.1.236 o successiva.2384Restituisci `classifierContext` per inviare una breve nota sul risultato della chiamata allo strumento al classificatore della [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) anziché a Claude. Il classificatore [non riceve mai i risultati degli strumenti in sé](/docs/it/permission-modes#how-the-classifier-evaluates-actions), quindi questo campo è il modo supportato per comunicargli qualcosa su ciò che una chiamata ha restituito prima che esamini le azioni successive. Il campo richiede Claude Code v2.1.236 o successivo.
2359 2385
2360L'esempio seguente indica al classificatore da dove proviene l'output di una query:2386L'esempio seguente indica al classificatore da dove proviene l'output di una query:
2361 2387
2371Il peso che il classificatore attribuisce alla nota dipende da dove hai configurato l'hook:2397Il peso che il classificatore attribuisce alla nota dipende da dove hai configurato l'hook:
2372 2398
2373* **Hook configurati in Claude Code**: per gli hook provenienti da file di impostazioni, plugin, skill e frontmatter degli agenti, il classificatore tratta la nota come contesto non verificato fornito dall'applicazione. La nota non stabilisce mai l'intento dell'utente e, se afferma che hai approvato o richiesto qualcosa, il classificatore verifica tale affermazione confrontandola con i tuoi messaggi nella conversazione2399* **Hook configurati in Claude Code**: per gli hook provenienti da file di impostazioni, plugin, skill e frontmatter degli agenti, il classificatore tratta la nota come contesto non verificato fornito dall'applicazione. La nota non stabilisce mai l'intento dell'utente e, se afferma che hai approvato o richiesto qualcosa, il classificatore verifica tale affermazione confrontandola con i tuoi messaggi nella conversazione
2374* **Callback in-process dell'Agent SDK**: quando un'applicazione che incorpora Claude Code registra l'hook come [callback del TypeScript SDK](/docs/it/agent-sdk/hooks) e restituisce la nota durante la sessione attiva, il classificatore può considerare come intento dell'utente una dichiarazione dell'utente riportata nella nota. Tale dichiarazione può soddisfare un requisito di consenso che il classificatore accetterebbe da un messaggio che invii tu, ma non rimuove mai un blocco che nemmeno un tuo messaggio potrebbe rimuovere. Dopo la ripresa di una sessione, Claude Code tratta le note ripristinate come contesto non verificato. Quando hook di entrambi i gruppi annotano la stessa chiamata, il classificatore tratta la nota combinata come non verificata2400* **Callback in-process dell'Agent SDK**: quando un'applicazione che incorpora Claude Code registra l'hook come [callback del TypeScript SDK](/docs/it/agent-sdk/hooks) e restituisce la nota durante la sessione attiva, il classificatore può considerare come intento dell'utente una dichiarazione dell'utente riportata nella nota. Tale dichiarazione può soddisfare un requisito di consenso che il classificatore accetterebbe da un messaggio inviato da te, ma non rimuove mai un blocco che neanche un tuo messaggio potrebbe rimuovere. Dopo la ripresa di una sessione, Claude Code tratta le note ripristinate come contesto non verificato. Quando hook di entrambi i gruppi annotano la stessa chiamata, il classificatore tratta la nota combinata come non verificata
2375 2401
2376Claude Code applica questi limiti quando consegna la nota:2402Claude Code applica questi limiti quando consegna la nota:
2377 2403
2378* **Lunghezza**: Claude Code limita le note per una singola chiamata a uno strumento a 2.000 caratteri e tronca il resto. Il limite è condiviso tra tutti gli hook che rispondono a quella chiamata2404* **Lunghezza**: Claude Code limita le note per una singola chiamata a uno strumento a 2.000 caratteri e tronca il resto. Il limite è condiviso tra tutti gli hook che rispondono a quella chiamata
2379* **Solo risposte sincrone**: Claude Code ignora il campo nella risposta di un hook che [viene eseguito in background](#run-hooks-in-the-background), perché quella risposta arriva dopo che Claude Code ha registrato il risultato dello strumento2405* **Solo risposte sincrone**: Claude Code ignora il campo nella risposta di un hook che [viene eseguito in background](#run-hooks-in-the-background), perché tale risposta arriva dopo che Claude Code ha registrato il risultato dello strumento
2380* **Chiamate che il classificatore non registra**: la trascrizione del classificatore omette le consultazioni di sola lettura, come le letture di file e le ricerche. Claude Code scarta una nota associata a una di queste chiamate2406* **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 associata a una di queste chiamate
2381* **Interazione con le riscritture**: quando la nota descrive un output che stai sostituendo con `updatedToolOutput`, restituisci entrambi i campi nella stessa risposta dell'hook. Claude Code scarta la nota se quella riscrittura viene rifiutata o se la riscrittura di un altro hook la sostituisce. Claude Code consegna una nota restituita senza riscrittura anche quando un altro hook riscrive l'output2407* **Interazione con le riscritture**: quando la nota descrive un output che stai sostituendo con `updatedToolOutput`, restituisci entrambi i campi nella stessa risposta dell'hook. Claude Code scarta la nota se la riscrittura viene rifiutata o se la riscrittura di un altro hook la sostituisce. Claude Code consegna una nota restituita senza una riscrittura anche quando un altro hook riscrive l'output
2382 2408
2383<Warning>2409<Warning>
2384 Il classificatore legge il contenuto che inserisci in `classifierContext` come informazione proveniente dall'applicazione che ospita la sessione, quindi non copiarvi output di strumenti non attendibili o testo di terze parti. Limita la nota a una breve affermazione su questa singola chiamata, come un fatto sulla sua origine o una dichiarazione dell'utente in merito; non usare il campo per consegnare messaggi non correlati o un flusso di eventi.2410 Il classificatore legge il contenuto che inserisci in `classifierContext` come informazione proveniente dall'applicazione che ospita la sessione, quindi non copiarci output di strumenti non attendibili o testo di terze parti. Limita la nota a una breve affermazione su questa singola chiamata, come un fatto sulla sua origine o una dichiarazione dell'utente al riguardo; non usare il campo per consegnare messaggi non correlati o un flusso di eventi.
2385</Warning>2411</Warning>
2386 2412
2387<h3 id="posttoolusefailure">2413<h3 id="posttoolusefailure">
2388 PostToolUseFailure2414 PostToolUseFailure
2389</h3>2415</h3>
2390 2416
2391Viene eseguito quando uno strumento che ha iniziato l'esecuzione fallisce: lo strumento ha generato un errore, oppure uno strumento MCP ha restituito un risultato di errore. Usalo per registrare i fallimenti, inviare avvisi o fornire feedback correttivo a Claude.2417Viene eseguito quando uno strumento che ha iniziato l'esecuzione fallisce: lo strumento ha generato un errore, oppure uno strumento MCP ha restituito un risultato di errore. Usalo per registrare i fallimenti, inviare avvisi o fornire un feedback correttivo a Claude.
2392 2418
2393Corrisponde sul nome dello strumento, con gli stessi valori di PreToolUse.2419Corrisponde sul nome dello strumento, con gli stessi valori di PreToolUse.
2394 2420
2395<Note>2421<Note>
2396 Questo evento non si attiva per le chiamate agli strumenti rifiutate prima dell'esecuzione: un nome di strumento sconosciuto, un input che non supera la validazione dello schema o quella specifica dello strumento, oppure un rifiuto del permesso. I rifiuti per validazione vengono restituiti come risultati `tool_use_error` e avvengono prima dell'esecuzione degli hook, quindi non attivano né `PreToolUse` né `PostToolUseFailure`. I rifiuti del permesso attivano `PreToolUse` ma non questo evento; consulta [PermissionDenied](#permissiondenied).2422 Questo evento non si attiva per le chiamate agli strumenti rifiutate prima dell'esecuzione: un nome di strumento sconosciuto, un input che non supera la validazione dello schema o la validazione specifica dello strumento, oppure un permesso negato. I rifiuti per validazione vengono restituiti come risultati `tool_use_error` e avvengono prima dell'esecuzione degli hook, quindi non attivano né `PreToolUse` né `PostToolUseFailure`. I permessi negati attivano `PreToolUse` ma non questo evento; vedi [PermissionDenied](#permissiondenied).
2397</Note>2423</Note>
2398 2424
2399<h4 id="posttoolusefailure-input">2425<h4 id="posttoolusefailure-input">
2424| Campo | Descrizione |2450| Campo | Descrizione |
2425| :- | :- |2451| :- | :- |
2426| `error` | Stringa che descrive cosa è andato storto. Il formato dipende dallo strumento che ha fallito |2452| `error` | Stringa che descrive cosa è andato storto. Il formato dipende dallo strumento che ha fallito |
2427| `is_interrupt` | Booleano facoltativo. True quando il fallimento ha raggiunto Claude Code come interruzione anziché come errore segnalato dallo strumento. Annullare uno strumento in esecuzione non attiva questo hook; il risultato dello strumento contiene invece il messaggio di interruzione |2453| `is_interrupt` | Booleano facoltativo. True quando il fallimento ha raggiunto Claude Code come interruzione anziché come errore segnalato dallo strumento. L'annullamento di uno strumento in esecuzione non attiva questo hook; il risultato dello strumento contiene invece il messaggio di interruzione |
2428| `duration_ms` | Facoltativo. Tempo di esecuzione dello strumento in millisecondi. Esclude il tempo trascorso nelle richieste di permesso e negli hook PreToolUse |2454| `duration_ms` | Facoltativo. Tempo di esecuzione dello strumento in millisecondi. Esclude il tempo trascorso nelle richieste di permesso e negli hook PreToolUse |
2429 2455
2430La stringa `error` è generalmente lo stesso testo che Claude riceve come risultato dello strumento fallito. Il suo formato varia in base allo strumento e al tipo di fallimento. Basa il tuo hook su `tool_name`, `is_interrupt` e sulla prima riga `Exit code N`; tratta il resto della stringa come testo di visualizzazione, non come un formato stabile.2456La stringa `error` è generalmente lo stesso testo che Claude riceve come risultato dello strumento fallito. Il suo formato varia in base allo strumento e al tipo di fallimento. Basa il tuo hook su `tool_name`, `is_interrupt` e sulla prima riga `Exit code N`; tratta il resto della stringa come testo da visualizzare, non come un formato stabile.
2431 2457
2432* Per Bash e PowerShell, un comando che è stato eseguito ed è terminato produce una prima riga `Exit code N`, seguita da qualsiasi output prodotto dal comando come un unico blocco con stdout e stderr intercalati2458* Per Bash e PowerShell, un comando che è stato eseguito ed è terminato produce una prima riga `Exit code N`, seguita dall'eventuale output prodotto dal comando come un unico blocco con stdout e stderr intercalati
2433* Un payload può anche contenere un semplice messaggio di fallimento senza riga del codice di uscita, quando Claude Code non è riuscito ad avviare il processo della shell stesso2459* Un payload può anche contenere un semplice messaggio di fallimento senza la riga del codice di uscita, quando Claude Code non è riuscito ad avviare il processo della shell stesso
2434* Claude Code tronca al centro le stringhe lunghe attorno a un marcatore `... [N characters truncated] ...` e può inserire righe proprie, come `Command timed out after 2m 0s`2460* Claude Code tronca al centro le stringhe lunghe attorno a un indicatore `... [N characters truncated] ...` e può inserire righe proprie, come `Command timed out after 2m 0s`
2435 2461
2436<h4 id="posttoolusefailure-decision-control">2462<h4 id="posttoolusefailure-decision-control">
2437 Controllo delle decisioni di PostToolUseFailure2463 Controllo delle decisioni di PostToolUseFailure
2438</h4>2464</h4>
2439 2465
2440Gli hook `PostToolUseFailure` possono fornire contesto a Claude dopo il fallimento di uno strumento. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, il tuo script di hook può restituire questi campi specifici dell'evento:2466Gli hook `PostToolUseFailure` possono fornire contesto a Claude dopo il fallimento di uno strumento. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, lo script del tuo hook può restituire questi campi specifici dell'evento:
2441 2467
2442| Campo | Descrizione |2468| Campo | Descrizione |
2443| :- | :- |2469| :- | :- |
2444| `additionalContext` | Stringa aggiunta al contesto di Claude insieme all'errore. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |2470| `additionalContext` | Stringa aggiunta al contesto di Claude insieme all'errore. Vedi [Aggiungere contesto per Claude](#add-context-for-claude) |
2445 2471
2446```json theme={null}2472```json theme={null}
2447{2473{
2456 PostToolBatch2482 PostToolBatch
2457</h3>2483</h3>
2458 2484
2459Viene eseguito una volta dopo che ogni chiamata a uno strumento in un batch è stata risolta, prima che Claude Code invii la richiesta successiva al modello. `PostToolUse` si attiva una volta per strumento, il che significa che si attiva in modo concorrente quando Claude effettua chiamate agli strumenti in parallelo. `PostToolBatch` si attiva esattamente una volta con l'intero batch, quindi è il posto giusto per iniettare contesto che dipende dall'insieme di strumenti eseguiti anziché da un singolo strumento. Non esiste un matcher per questo evento.2485Viene eseguito una volta dopo che ogni chiamata a uno strumento in un batch è stata risolta, prima che Claude Code invii la richiesta successiva al modello. `PostToolUse` si attiva una volta per strumento, il che significa che si attiva in modo concorrente quando Claude effettua chiamate agli strumenti in parallelo. `PostToolBatch` si attiva esattamente una volta con l'intero batch, quindi è il punto giusto per inserire contesto che dipende dall'insieme degli strumenti eseguiti anziché da un singolo strumento. Non esiste un matcher per questo evento.
2460 2486
2461<h4 id="posttoolbatch-input">2487<h4 id="posttoolbatch-input">
2462 Input di PostToolBatch2488 Input di PostToolBatch
2488}2514}
2489```2515```
2490 2516
2491`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 ha emesso lo strumento. Per `Read`, ciò significa testo con il numero di riga come prefisso anziché il contenuto grezzo del file. Le risposte possono essere grandi, quindi analizza solo i campi di cui hai bisogno.2517`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`, ciò significa testo preceduto dai numeri di riga anziché il contenuto grezzo del file. Le risposte possono essere grandi, quindi analizza solo i campi di cui hai bisogno.
2492 2518
2493<Note>2519<Note>
2494 La struttura di `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 vede il modello.2520 La struttura di `tool_response` è diversa da quella di `PostToolUse`. `PostToolUse` passa l'oggetto `Output` strutturato dello strumento, come `{filePath: "...", type: "create"}` per `Write`; `PostToolBatch` passa il contenuto `tool_result` serializzato che vede il modello.
2495</Note>2521</Note>
2496 2522
2497<h4 id="posttoolbatch-decision-control">2523<h4 id="posttoolbatch-decision-control">
2498 Controllo delle decisioni di PostToolBatch2524 Controllo delle decisioni di PostToolBatch
2499</h4>2525</h4>
2500 2526
2501Gli hook `PostToolBatch` possono iniettare contesto per Claude. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, il tuo script di hook può restituire questi campi specifici dell'evento:2527Gli hook `PostToolBatch` possono inserire contesto per Claude. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, lo script del tuo hook può restituire questi campi specifici dell'evento:
2502 2528
2503| Campo | Descrizione |2529| Campo | Descrizione |
2504| :- | :- |2530| :- | :- |
2505| `additionalContext` | Stringa di contesto iniettata una volta prima della chiamata successiva al modello. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) per i dettagli sulla consegna, su cosa inserirvi e su come le sessioni riprese gestiscono i valori passati |2531| `additionalContext` | Stringa di contesto inserita una volta prima della successiva chiamata al modello. Vedi [Aggiungere contesto per Claude](#add-context-for-claude) per i dettagli sulla consegna, cosa inserirvi e come le sessioni riprese gestiscono i valori passati |
2506 2532
2507```json theme={null}2533```json theme={null}
2508{2534{
2513}2539}
2514```2540```
2515 2541
2516Restituire `decision: "block"` o `continue: false` arresta il ciclo agentico prima della chiamata successiva al modello. Il messaggio di blocco proviene dal `reason` o dallo `stopReason` JSON, oppure da stderr con uscita 2. Lo vedi come avviso nella trascrizione, e rimane nella conversazione, quindi Claude lo vede quando la conversazione continua.2542Restituire `decision: "block"` o `continue: false` arresta il ciclo agentico prima della successiva chiamata al modello. Il messaggio di blocco proviene dal `reason` o dallo `stopReason` JSON, oppure dallo stderr con codice di uscita 2. Lo vedi come avviso nella trascrizione, e rimane nella conversazione, quindi Claude lo vede quando la conversazione continua.
2517 2543
2518<h3 id="permissiondenied">2544<h3 id="permissiondenied">
2519 PermissionDenied2545 PermissionDenied
2520</h3>2546</h3>
2521 2547
2522Viene eseguito quando la [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) rifiuta una chiamata a uno strumento, anche quando la rifiuta senza un verdetto del classificatore perché [un controllo di sicurezza separato dalla modalità auto ha rifiutato la richiesta del classificatore stesso](/docs/it/errors#auto-mode-cannot-determine-the-safety-of-an-action) o la sua risposta non è stata interpretabile. Questo hook si attiva solo in modalità auto: non viene eseguito quando rifiuti manualmente una finestra di dialogo di permesso, quando un hook `PreToolUse` blocca una chiamata o quando corrisponde una regola `deny`. Usalo per registrare i rifiuti, modificare la configurazione o comunicare al modello che può riprovare la chiamata allo strumento.2548Viene eseguito quando la [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) nega una chiamata a uno strumento, anche quando la nega senza un verdetto del classificatore perché [un controllo di sicurezza separato dalla modalità auto ha rifiutato la richiesta del classificatore stesso](/docs/it/errors#auto-mode-cannot-determine-the-safety-of-an-action) o la sua risposta non è stata analizzata correttamente. Questo hook si attiva solo in modalità auto: non viene eseguito quando neghi manualmente una finestra di dialogo dei permessi, quando un hook `PreToolUse` blocca una chiamata o quando una regola `deny` corrisponde. Usalo per registrare i rifiuti, regolare la configurazione o indicare al modello che può riprovare la chiamata allo strumento.
2523 2549
2524Corrisponde sul nome dello strumento, con gli stessi valori di PreToolUse.2550Corrisponde sul nome dello strumento, con gli stessi valori di PreToolUse.
2525 2551
2548 2574
2549| Campo | Descrizione |2575| Campo | Descrizione |
2550| :- | :- |2576| :- | :- |
2551| `reason` | Il motivo del rifiuto. Per un verdetto del classificatore, nella maggior parte delle sessioni indica la regola corrispondente tra parentesi quadre, come `[Data Exfiltration]`; consulta [Esaminare i rifiuti](/docs/it/auto-mode-config#review-denials) per le altre forme. Per un [rifiuto senza verdetto](#permissiondenied-decision-control), inizia con `Auto mode could not evaluate this action and is blocking it for safety`. Per un rifiuto dovuto all'indisponibilità del modello classificatore, è il testo fisso `Classifier unavailable` |2577| `reason` | Il motivo del rifiuto. Per un verdetto del classificatore, nella maggior parte delle sessioni indica la regola corrispondente tra parentesi quadre, come `[Data Exfiltration]`; vedi [Esaminare i rifiuti](/docs/it/auto-mode-config#review-denials) per le altre forme. Per un [rifiuto senza verdetto](#permissiondenied-decision-control), inizia con `Auto mode could not evaluate this action and is blocking it for safety`. Per un rifiuto dovuto all'indisponibilità del modello del classificatore, è il testo fisso `Classifier unavailable` |
2552 2578
2553<h4 id="permissiondenied-decision-control">2579<h4 id="permissiondenied-decision-control">
2554 Controllo delle decisioni di PermissionDenied2580 Controllo delle decisioni di PermissionDenied
2555</h4>2581</h4>
2556 2582
2557Gli hook PermissionDenied possono comunicare al modello che può riprovare la chiamata allo strumento rifiutata. Restituisci un oggetto JSON con `hookSpecificOutput.retry` impostato su `true`:2583Gli hook PermissionDenied possono indicare al modello che può riprovare la chiamata allo strumento negata. Restituisci un oggetto JSON con `hookSpecificOutput.retry` impostato su `true`:
2558 2584
2559```json theme={null}2585```json theme={null}
2560{2586{
2565}2591}
2566```2592```
2567 2593
2568Quando `retry` è `true`, Claude Code aggiunge un messaggio alla conversazione che comunica al modello che può riprovare la chiamata allo strumento. Claude Code non annulla il rifiuto stesso. Se il tuo hook non restituisce JSON, o restituisce `retry: false`, il rifiuto resta valido e il modello riceve il messaggio di rifiuto originale.2594Quando `retry` è `true`, Claude Code aggiunge alla conversazione un messaggio che indica al modello che può riprovare la chiamata allo strumento. Claude Code non annulla il rifiuto in sé. Se il tuo hook non restituisce JSON, o restituisce `retry: false`, il rifiuto resta valido e il modello riceve il messaggio di rifiuto originale.
2569 2595
2570Claude Code ignora `retry: true` quando il classificatore non ha prodotto [alcun verdetto sull'azione](/docs/it/errors#auto-mode-cannot-determine-the-safety-of-an-action): la sua risposta non è stata interpretabile, oppure un controllo di sicurezza separato dalla modalità auto ha rifiutato la richiesta del classificatore stesso. Per questi rifiuti, Claude Code indica già al modello nel messaggio di rifiuto se riprovare più tardi o andare avanti.2596Claude Code ignora `retry: true` quando il classificatore non ha prodotto [alcun verdetto sull'azione](/docs/it/errors#auto-mode-cannot-determine-the-safety-of-an-action): la sua risposta non è stata analizzata correttamente, oppure un controllo di sicurezza separato dalla modalità auto ha rifiutato la richiesta del classificatore stesso. Per questi rifiuti, Claude Code indica già al modello nel messaggio di rifiuto se riprovare più tardi o andare avanti.
2571 2597
2572<h3 id="notification">2598<h3 id="notification">
2573 Notification2599 Notification
2575 2601
2576Viene eseguito quando Claude Code invia notifiche. Corrisponde sul tipo di notifica. Ometti il matcher per eseguire gli hook per tutti i tipi di notifica.2602Viene eseguito quando Claude Code invia notifiche. Corrisponde sul tipo di notifica. Ometti il matcher per eseguire gli hook per tutti i tipi di notifica.
2577 2603
2578Ricevi questi eventi di hook anche con le notifiche desktop disattivate: l'impostazione `preferredNotifChannel`, incluso `notifications_disabled`, cambia solo il modo in cui vieni avvisato, non se il tuo hook viene eseguito.2604Ricevi questi eventi hook anche con le notifiche desktop disattivate: l'impostazione `preferredNotifChannel`, incluso `notifications_disabled`, cambia solo il modo in cui vieni avvisato, non se il tuo hook viene eseguito.
2579 2605
2580| Matcher | Quando si attiva |2606| Matcher | Quando si attiva |
2581| :- | :- |2607| :- | :- |
2582| `permission_prompt` | Claude ha bisogno che tu approvi l'uso di uno strumento o la [richiesta di rete](/docs/it/sandboxing#network-isolation) di un comando in sandbox, e la richiesta è in attesa da circa sei secondi |2608| `permission_prompt` | Claude ha bisogno che tu approvi l'uso di uno strumento o la [richiesta di rete](/docs/it/sandboxing#network-isolation) di un comando in sandbox, e la richiesta è in attesa da circa sei secondi |
2583| `idle_prompt` | Claude ha finito di rispondere circa 60 secondi fa e da allora non hai digitato nulla |2609| `idle_prompt` | Claude ha finito di rispondere circa 60 secondi fa e da allora non hai digitato nulla |
2584| `auth_success` | L'autenticazione viene completata |2610| `auth_success` | L'autenticazione viene completata |
2585| `elicitation_dialog` | Un server MCP apre un modulo di elicitazione e non digiti da circa sei secondi |2611| `elicitation_dialog` | Un server MCP apre un modulo di elicitation e non digiti da circa sei secondi |
2586| `elicitation_url_dialog` | Un server MCP ti chiede di aprire un URL nel browser e non digiti da circa sei secondi |2612| `elicitation_url_dialog` | Un server MCP ti chiede di aprire un URL nel browser e non digiti da circa sei secondi |
2587| `elicitation_complete` | Un server MCP segnala che un'[elicitazione in modalità URL](#elicitation-input) è completata |2613| `elicitation_complete` | Un server MCP segnala che un'[elicitation in modalità URL](#elicitation-input) è completata |
2588| `elicitation_response` | Una risposta di elicitazione MCP viene inviata al server |2614| `elicitation_response` | Una risposta di elicitation MCP viene inviata al server |
2589| `agent_needs_input` | Una sessione in background inizia ad attendere un tuo input mentre la [vista agenti](/docs/it/agent-view) è aperta in un terminale. Si attiva anche quando una sessione del terminale ti mostra una [domanda di configurazione del terminale di un membro di un team di agenti](/docs/it/agent-teams#choose-a-display-mode) o l'avviso della modalità auto sugli [addebiti per le richieste del classificatore](/docs/it/auto-mode-classifier-billing) e non digiti da circa sei secondi |2615| `agent_needs_input` | Una sessione in background inizia ad attendere un tuo input mentre la [vista agenti](/docs/it/agent-view) è aperta in un terminale. Si attiva anche quando una sessione del terminale ti mostra la [domanda di configurazione del terminale di un compagno di un team di agenti](/docs/it/agent-teams#choose-a-display-mode) o l'avviso della modalità auto sugli [addebiti per le richieste del classificatore](/docs/it/auto-mode-classifier-billing) e non digiti da circa sei secondi |
2590| `agent_completed` | Una sessione in background termina o fallisce. Si attiva solo mentre la [vista agenti](/docs/it/agent-view) è aperta in un terminale |2616| `agent_completed` | Una sessione in background termina o fallisce. Si attiva solo mentre la [vista agenti](/docs/it/agent-view) è aperta in un terminale |
2591| `quota_auto_resume_fired` | Claude Code riprende la tua attività dopo che un limite di utilizzo di claude.ai l'aveva messa in pausa: al momento del ripristino, oppure prima quando qualcosa che fai in Claude Code durante l'attesa, come aggiungere crediti di utilizzo, passare a un piano superiore o cambiare modello, rende di nuovo disponibile l'utilizzo, con l'[eccezione relativa all'impostazione del modello](/docs/it/interactive-mode#wait-for-a-usage-limit-to-reset) |2617| `quota_auto_resume_fired` | Claude Code prosegue il tuo task dopo che un limite di utilizzo di claude.ai lo aveva messo in pausa: al ripristino, o prima quando qualcosa che fai in Claude Code durante l'attesa, come aggiungere crediti di utilizzo, eseguire l'upgrade del piano o cambiare modello, rende di nuovo disponibile l'utilizzo, con l'[eccezione relativa all'impostazione del modello](/docs/it/interactive-mode#wait-for-a-usage-limit-to-reset) |
2592| `quota_auto_resume_stale` | Un limite di utilizzo di claude.ai è stato ripristinato mentre il tuo computer era in sospensione per più di circa 30 minuti. Claude Code attende che tu prema `Enter` invece di continuare. Dopo una sospensione più breve continua e attiva invece `quota_auto_resume_fired` |2618| `quota_auto_resume_stale` | Un limite di utilizzo di claude.ai si è ripristinato mentre il tuo computer era in stop per più di circa 30 minuti. Claude Code attende che tu prema `Enter` invece di proseguire. Dopo uno stop più breve prosegue e attiva invece `quota_auto_resume_fired` |
2593| `quota_auto_resume_disabled` | Claude Code termina l'attesa per un limite di utilizzo di claude.ai senza riprendere la tua attività: [`autoContinueAtUsageLimit`](/docs/it/settings-reference#autocontinueatusagelimit) è stato disattivato o il ripristino si è spostato a più di 24 ore di distanza durante un'attesa avviata da Claude Code in autonomia, l'attività ripresa ha continuato a raggiungere il limite, oppure la ripresa è stata bloccata prima di raggiungere il modello. Non si attiva quando premi `Esc` o `Ctrl+C`, o scegli **Don't continue automatically** |2619| `quota_auto_resume_disabled` | Claude Code termina l'attesa per un limite di utilizzo di claude.ai senza proseguire il tuo task: [`autoContinueAtUsageLimit`](/docs/it/settings-reference#autocontinueatusagelimit) è stato disattivato o il ripristino si è spostato di oltre 24 ore durante un'attesa avviata autonomamente da Claude Code, il task proseguito ha continuato a raggiungere il limite, oppure la prosecuzione è stata bloccata prima di raggiungere il modello. Non si attiva quando premi `Esc` o `Ctrl+C`, o scegli **Don't continue automatically** |
2594 2620
2595I tipi `quota_auto_resume_fired`, `quota_auto_resume_stale` e `quota_auto_resume_disabled` richiedono Claude Code v2.1.234 o successiva.2621I tipi `quota_auto_resume_fired`, `quota_auto_resume_stale` e `quota_auto_resume_disabled` richiedono Claude Code v2.1.234 o successivo.
2596 2622
2597Nelle sessioni del terminale, `permission_prompt` per la richiesta di rete di un comando in sandbox richiede Claude Code v2.1.246 o successiva.2623Nelle sessioni del terminale, `permission_prompt` per la richiesta di rete di un comando in sandbox richiede Claude Code v2.1.246 o successivo.
2598 2624
2599`agent_needs_input` per la domanda di configurazione del terminale di un membro del team richiede Claude Code v2.1.248 o successiva.2625`agent_needs_input` per la domanda di configurazione del terminale di un compagno di team richiede Claude Code v2.1.248 o successivo.
2600 2626
2601<Note>2627<Note>
2602 I tipi `permission_prompt`, `idle_prompt`, `elicitation_dialog` ed `elicitation_url_dialog` condividono la tempistica con le notifiche desktop, quindi nelle sessioni del terminale li vedi solo quando sembri essere lontano dal terminale:2628 I tipi `permission_prompt`, `idle_prompt`, `elicitation_dialog` e `elicitation_url_dialog` condividono la tempistica con le notifiche desktop, quindi nelle sessioni del terminale li vedi solo quando sembri lontano dal terminale:
2603 2629
2604 * Aspettati `permission_prompt` quando non digiti da circa sei secondi. Il timer parte quando appare la richiesta di permesso, e ogni pressione di tasto lo rinvia. Per eseguire un hook immediatamente quando Claude chiede il permesso di usare uno strumento, usa invece [PermissionRequest](#permissionrequest).2630 * Aspettati `permission_prompt` una volta che non digiti da circa sei secondi. Il timer parte quando compare la richiesta di permesso e ogni pressione di tasto lo rinvia. Per eseguire un hook immediatamente quando Claude chiede il permesso di usare uno strumento, usa invece [PermissionRequest](#permissionrequest).
2605 * Aspettati `idle_prompt` circa 60 secondi dopo che Claude ha finito di rispondere, e solo se da allora non hai digitato e nessun agente in background, come un [subagent](/docs/it/sub-agents) in background, è ancora in esecuzione. Claude Code non invia `idle_prompt` mentre attende il ripristino di un limite di utilizzo di claude.ai. Quando l'attesa termina da sola, si attiva invece uno dei tipi `quota_auto_resume_*`.2631 * Aspettati `idle_prompt` circa 60 secondi dopo che Claude ha finito di rispondere, e solo se da allora non hai digitato nulla e nessun agente in background, come un [subagent](/docs/it/sub-agents) in background, è ancora in esecuzione. Claude Code non invia `idle_prompt` mentre attende il ripristino di un limite di utilizzo di claude.ai. Quando l'attesa termina da sola, si attiva invece uno dei tipi `quota_auto_resume_*`.
2606 * Aspettati `elicitation_dialog` per un modulo di elicitazione, o `elicitation_url_dialog` per una richiesta di URL nel browser, quando non digiti da circa sei secondi. Entrambi condividono la stessa soglia di sei secondi di `permission_prompt`: il timer parte quando appare la finestra di dialogo, e ogni pressione di tasto lo rinvia.2632 * Aspettati `elicitation_dialog` per un modulo di elicitation, o `elicitation_url_dialog` per una richiesta di URL nel browser, una volta che non digiti da circa sei secondi. Entrambi condividono la stessa soglia di sei secondi di `permission_prompt`: il timer parte quando compare la finestra di dialogo e ogni pressione di tasto lo rinvia.
2607 2633
2608 Una richiesta di permesso o un'elicitazione che arriva mentre un'altra finestra di dialogo è sullo schermo mantiene la stessa soglia di sei secondi, calcolata dal momento in cui arriva la richiesta. La sua notifica può raggiungerti mentre la richiesta è ancora in attesa dietro la finestra di dialogo aperta.2634 Una richiesta di permesso o un'elicitation che arriva mentre sullo schermo è presente un'altra finestra di dialogo mantiene la stessa soglia di sei secondi, calcolata dal momento in cui arriva la richiesta. La sua notifica può raggiungerti mentre la richiesta è ancora in attesa dietro la finestra di dialogo aperta.
2609</Note>2635</Note>
2610 2636
2611Claude Code calcola la tempistica di `permission_prompt` in modo diverso nelle sessioni in cui invia le richieste di permesso alla [callback `canUseTool`](/docs/it/agent-sdk/user-input) dell'Agent SDK, che è il modo in cui Claude Desktop e l'estensione VS Code ospitano Claude Code:2637Claude Code gestisce la tempistica di `permission_prompt` in modo diverso nelle sessioni in cui invia le richieste di permesso alla [callback `canUseTool`](/docs/it/agent-sdk/user-input) dell'Agent SDK, che è il modo in cui Claude Desktop e l'estensione VS Code ospitano Claude Code:
2612 2638
2613* Aspettati `permission_prompt` circa sei secondi dopo che Claude chiede il permesso. Claude Code non lo rinvia mentre digiti.2639* Aspettati `permission_prompt` circa sei secondi dopo che Claude chiede il permesso. Claude Code non lo rinvia mentre digiti.
2614* Se tu o un hook [PermissionRequest](#permissionrequest) rispondete prima, Claude Code non esegue `permission_prompt`.2640* Se tu o un hook [PermissionRequest](#permissionrequest) rispondete prima, Claude Code non esegue `permission_prompt`.
2649 Input di Notification2675 Input di Notification
2650</h4>2676</h4>
2651 2677
2652Oltre 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.2678Oltre 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.
2653 2679
2654```json theme={null}2680```json theme={null}
2655{2681{
2669 SubagentStart2695 SubagentStart
2670</h3>2696</h3>
2671 2697
2672Viene eseguito quando Claude genera un subagent con lo strumento Agent, quando Claude [riprende un subagent](/docs/it/sub-agents#resume-subagents), e ogni volta che un membro in-process di un [team di agenti](/docs/it/agent-teams) gestisce un nuovo messaggio. Supporta i matcher per filtrare in base al nome del tipo di agente. Per gli agenti integrati, è il nome dell'agente, come `general-purpose`, `Explore` o `Plan`. Per i [subagent personalizzati](/docs/it/sub-agents), è il campo `name` del frontmatter dell'agente, non il nome del file.2698Viene eseguito quando Claude avvia un subagent con lo strumento Agent, quando Claude [riprende un subagent](/docs/it/sub-agents#resume-subagents) e ogni volta che un compagno in-process di un [team di agenti](/docs/it/agent-teams) gestisce un nuovo messaggio. Supporta i matcher per filtrare in base al nome del tipo di agente. Per gli agenti integrati, è il nome dell'agente come `general-purpose`, `Explore` o `Plan`. Per i [subagent personalizzati](/docs/it/sub-agents), è il campo `name` del frontmatter dell'agente, non il nome del file.
2673 2699
2674Per i subagent forniti da un [plugin](/docs/it/plugins/overview), il tipo di agente è l'identificatore con ambito del plugin, come `my-plugin:reviewer`, non il semplice nome del frontmatter. I due punti collocano un nome con ambito del plugin sul percorso delle espressioni regolari, quindi ancora il matcher con `^` e `$` per una corrispondenza esatta: `^my-plugin:reviewer$`.2700Per i subagent forniti da un [plugin](/docs/it/plugins/overview), il tipo di agente è l'identificatore con ambito del plugin, come `my-plugin:reviewer`, non il semplice nome del frontmatter. I due punti fanno sì che un nome con ambito del plugin venga trattato come espressione regolare, quindi ancora il matcher con `^` e `$` per una corrispondenza esatta: `^my-plugin:reviewer$`.
2675 2701
2676<h4 id="subagentstart-input">2702<h4 id="subagentstart-input">
2677 Input di SubagentStart2703 Input di SubagentStart
2690}2716}
2691```2717```
2692 2718
2693Gli hook SubagentStart non possono bloccare la creazione del subagent, ma possono iniettare contesto nel subagent. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, puoi restituire:2719Gli hook SubagentStart non possono bloccare la creazione del subagent, ma possono inserire contesto nel subagent. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, puoi restituire:
2694 2720
2695| Campo | Descrizione |2721| Campo | Descrizione |
2696| :- | :- |2722| :- | :- |
2697| `additionalContext` | Stringa aggiunta al contesto del subagent all'inizio della sua conversazione, prima del suo primo prompt. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) |2723| `additionalContext` | Stringa aggiunta al contesto del subagent all'inizio della sua conversazione, prima del suo primo prompt. Vedi [Aggiungere contesto per Claude](#add-context-for-claude) |
2698 2724
2699```json theme={null}2725```json theme={null}
2700{2726{
2705}2731}
2706```2732```
2707 2733
2708Quando l'hook viene eseguito di nuovo per lo stesso subagent, Claude Code inietta il contesto restituito solo quando il contesto del subagent non contiene già la copia di un'esecuzione precedente. La copia iniettata all'avvio rimane al suo posto, lasciando intatta la [cache del prompt](/docs/it/prompt-caching#subagents-and-the-cache) del subagent. Dopo che la [compattazione automatica](/docs/it/sub-agents#auto-compaction) scarta quella copia, Claude Code inietta di nuovo il contesto dell'esecuzione successiva.2734Quando l'hook viene eseguito di nuovo per lo stesso subagent, Claude Code inserisce il contesto restituito solo se il contesto del subagent non contiene già la copia di un'esecuzione precedente. La copia inserita all'avvio resta al suo posto, lasciando intatta la [prompt cache](/docs/it/prompt-caching#subagents-and-the-cache) del subagent. Dopo che la [compattazione automatica](/docs/it/sub-agents#auto-compaction) scarta quella copia, Claude Code inserisce di nuovo il contesto dell'esecuzione successiva.
2709 2735
2710<h3 id="subagentstop">2736<h3 id="subagentstop">
2711 SubagentStop2737 SubagentStop
2717 Input di SubagentStop2743 Input di SubagentStop
2718</h4>2744</h4>
2719 2745
2720Oltre 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 del subagent stesso, archiviata in una cartella annidata `subagents/`. Il campo `last_assistant_message` contiene il contenuto testuale della risposta finale del subagent, così gli hook possono accedervi senza analizzare il file della trascrizione.2746Oltre 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 del subagent stesso, archiviata in una cartella annidata `subagents/`. Il campo `last_assistant_message` contiene il testo della risposta finale del subagent, così gli hook possono accedervi senza analizzare il file della trascrizione.
2721 2747
2722Non tutti gli eventi SubagentStop provengono da un subagent generato da Claude. Claude Code esegue anche agenti interni per alcune delle sue funzionalità, come i [suggerimenti di prompt](/docs/it/interactive-mode#prompt-suggestions) e le [domande laterali `/btw`](/docs/it/interactive-mode#side-questions-with-%2Fbtw), e SubagentStop si attiva anche quando uno di questi termina. Per questi eventi, `agent_type` è il nome dell'agente con cui viene eseguita la sessione stessa, come quello impostato con [`--agent`](/docs/it/cli-reference#cli-flags) o con l'[impostazione `agent`](/docs/it/settings-reference#agent), ed è una stringa vuota quando la sessione viene eseguita senza.2748Non tutti gli eventi SubagentStop provengono da un subagent avviato da Claude. Claude Code esegue anche agenti interni per alcune delle proprie funzionalità, come i [suggerimenti di prompt](/docs/it/interactive-mode#prompt-suggestions) e le [domande laterali con `/btw`](/docs/it/interactive-mode#side-questions-with-%2Fbtw), e SubagentStop si attiva anche quando uno di questi termina. Per questi eventi, `agent_type` è il nome dell'agente con cui viene eseguita la sessione stessa, come quello impostato con [`--agent`](/docs/it/cli-reference#cli-flags) o con l'[impostazione `agent`](/docs/it/settings-reference#agent), ed è una stringa vuota quando la sessione viene eseguita senza di esso.
2723 2749
2724Un `matcher` che nomina tipi di agente non corrisponde a un `agent_type` vuoto. Un hook il cui matcher è omesso, `""` o `"*"`, oppure è un'espressione regolare che corrisponde a una stringa vuota, viene eseguito anche per gli eventi con un `agent_type` vuoto.2750Un `matcher` che specifica tipi di agente non corrisponde a un `agent_type` vuoto. Un hook il cui matcher è omesso, `""` o `"*"`, oppure è un'espressione regolare che corrisponde a una stringa vuota, viene eseguito anche per gli eventi con un `agent_type` vuoto.
2725 2751
2726Su Claude Code v2.1.271 o successiva, un subagent eseguito con lo strumento [`SubagentHandback`](/docs/it/tools-reference) consegna il proprio resoconto tramite quello strumento prima di fermarsi. Il campo `last_assistant_message` contiene quindi il testo conclusivo del subagent, se presente, che non è il resoconto consegnato. Il resoconto è l'input `message` di quella chiamata, che un hook `PreToolUse` o `PostToolUse` con corrispondenza su `SubagentHandback` riceve come `tool_input.message`.2752Su Claude Code v2.1.271 o successivo, un subagent eseguito con lo strumento [`SubagentHandback`](/docs/it/tools-reference) consegna il proprio report tramite quello strumento prima di arrestarsi. Il campo `last_assistant_message` contiene quindi l'eventuale testo conclusivo del subagent, che non è il report consegnato. Il report è l'input `message` di quella chiamata, che un hook `PreToolUse` o `PostToolUse` con corrispondenza su `SubagentHandback` riceve come `tool_input.message`.
2727 2753
2728Gli hook SubagentStop ricevono anche gli array `background_tasks` e `session_crons` descritti in [Input di Stop](#stop-input). Entrambi gli array hanno come ambito la sessione padre, non il subagent.2754Gli hook SubagentStop ricevono anche gli array `background_tasks` e `session_crons` descritti in [Input di Stop](#stop-input). Entrambi gli array hanno come ambito la sessione padre, non il subagent.
2729 2755
2744}2770}
2745```2771```
2746 2772
2747Gli hook SubagentStop usano lo stesso formato di controllo delle decisioni degli [hook Stop](#stop-decision-control), incluso `hookSpecificOutput.additionalContext` con `hookEventName` impostato su `"SubagentStop"`, per un feedback non di errore che mantiene in esecuzione il subagent. Restituire `decision: "block"` con un `reason` mantiene in esecuzione il subagent e consegna `reason` al subagent come sua istruzione successiva. Un hook che blocca uscendo con 2 consegna il suo messaggio stderr nello stesso modo. Per iniettare contesto nella sessione padre dopo che un subagent ha restituito il controllo, usa invece un hook [`PostToolUse`](#posttooluse) sullo strumento `Agent`.2773Gli hook SubagentStop usano lo stesso formato di controllo delle decisioni degli [hook Stop](#stop-decision-control), incluso `hookSpecificOutput.additionalContext` con `hookEventName` impostato su `"SubagentStop"`, per un feedback non di errore che mantiene in esecuzione il subagent. Restituire `decision: "block"` con un `reason` mantiene in esecuzione il subagent e consegna `reason` al subagent come sua istruzione successiva. Un hook che blocca terminando con codice 2 consegna il proprio messaggio stderr allo stesso modo. Per inserire contesto nella sessione padre dopo che un subagent ha restituito il risultato, usa invece un hook [`PostToolUse`](#posttooluse) sullo strumento `Agent`.
2748 2774
2749<h3 id="taskcreated">2775<h3 id="taskcreated">
2750 TaskCreated2776 TaskCreated
2751</h3>2777</h3>
2752 2778
2753Viene eseguito quando un'attività viene creata tramite lo strumento `TaskCreate`. Usalo per imporre convenzioni di denominazione, richiedere descrizioni delle attività o impedire la creazione di determinate attività. In una [sessione senza gli strumenti Task](/docs/it/tools-reference#task-tool-availability), questo evento non si attiva.2779Viene eseguito quando un task viene creato tramite lo strumento `TaskCreate`. Usalo per imporre convenzioni di denominazione, richiedere descrizioni dei task o impedire la creazione di determinati task. In una [sessione senza gli strumenti Task](/docs/it/tools-reference#task-tool-availability), questo evento non si attiva.
2754 2780
2755Gli hook TaskCreated non supportano i matcher e si attivano a ogni occorrenza.2781Gli hook TaskCreated non supportano i matcher e si attivano a ogni occorrenza.
2756 2782
2776 2802
2777| Campo | Descrizione |2803| Campo | Descrizione |
2778| :- | :- |2804| :- | :- |
2779| `task_id` | Identificatore dell'attività in fase di creazione |2805| `task_id` | Identificatore del task in fase di creazione |
2780| `task_subject` | Titolo dell'attività |2806| `task_subject` | Titolo del task |
2781| `task_description` | Descrizione dettagliata dell'attività. Può essere assente |2807| `task_description` | Descrizione dettagliata del task. Può essere assente |
2782| `teammate_name` | Nome del membro del team che crea l'attività. Può essere assente |2808| `teammate_name` | Nome del compagno di team che crea il task. Può essere assente |
2783| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |2809| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |
2784| `agent_id` | In questo evento, il [campo di input comune](#common-input-fields) identifica il subagent o il [membro del team in-process](/docs/it/agent-teams#choose-a-display-mode) che crea l'attività. Può essere assente. Richiede Claude Code v2.1.290 o successiva |2810| `agent_id` | In questo evento, il [campo di input comune](#common-input-fields) identifica il subagent o il [compagno di team in-process](/docs/it/agent-teams#choose-a-display-mode) che crea il task. Può essere assente. Richiede Claude Code v2.1.290 o successivo |
2785 2811
2786<h4 id="taskcreated-decision-control">2812<h4 id="taskcreated-decision-control">
2787 Controllo delle decisioni di TaskCreated2813 Controllo delle decisioni di TaskCreated
2792* **Codice di uscita 2**: Claude Code restituisce il testo di stderr come messaggio.2818* **Codice di uscita 2**: Claude Code restituisce il testo di stderr come messaggio.
2793* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code restituisce `reason` come messaggio.2819* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code restituisce `reason` come messaggio.
2794 2820
2795Questo esempio blocca le attività i cui oggetti non seguono il formato richiesto:2821Questo esempio blocca i task i cui oggetti non seguono il formato richiesto:
2796 2822
2797```bash theme={null}2823```bash theme={null}
2798#!/bin/bash2824#!/bin/bash
2811 TaskCompleted2837 TaskCompleted
2812</h3>2838</h3>
2813 2839
2814Viene eseguito quando un'attività viene contrassegnata come completata. Si attiva in due situazioni: quando un agente qualsiasi contrassegna esplicitamente un'attività come completata tramite lo strumento TaskUpdate, oppure quando un membro di un [team di agenti](/docs/it/agent-teams) termina il proprio turno con attività in corso. Usalo per imporre criteri di completamento, come il superamento dei test o dei controlli lint, prima che un'attività possa essere chiusa.2840Viene eseguito quando un task sta per essere contrassegnato come completato. Si attiva in due situazioni: quando un qualsiasi agente contrassegna esplicitamente un task come completato tramite lo strumento TaskUpdate, oppure quando un compagno di un [team di agenti](/docs/it/agent-teams) termina il proprio turno con task in corso. Usalo per imporre criteri di completamento, come il superamento dei test o dei controlli lint, prima che un task possa essere chiuso.
2815 2841
2816Gli hook TaskCompleted non supportano i matcher e si attivano a ogni occorrenza.2842Gli hook TaskCompleted non supportano i matcher e si attivano a ogni occorrenza.
2817 2843
2838 2864
2839| Campo | Descrizione |2865| Campo | Descrizione |
2840| :- | :- |2866| :- | :- |
2841| `task_id` | Identificatore dell'attività in fase di completamento |2867| `task_id` | Identificatore del task in fase di completamento |
2842| `task_subject` | Titolo dell'attività |2868| `task_subject` | Titolo del task |
2843| `task_description` | Descrizione dettagliata dell'attività. Può essere assente |2869| `task_description` | Descrizione dettagliata del task. Può essere assente |
2844| `teammate_name` | Nome del membro del team che completa l'attività. Può essere assente |2870| `teammate_name` | Nome del compagno di team che completa il task. Può essere assente |
2845| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |2871| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |
2846| `agent_id` | In questo evento, il [campo di input comune](#common-input-fields) identifica il subagent o il [membro del team in-process](/docs/it/agent-teams#choose-a-display-mode) che completa l'attività. Può essere assente. Richiede Claude Code v2.1.290 o successiva |2872| `agent_id` | In questo evento, il [campo di input comune](#common-input-fields) identifica il subagent o il [compagno di team in-process](/docs/it/agent-teams#choose-a-display-mode) che completa il task. Può essere assente. Richiede Claude Code v2.1.290 o successivo |
2847 2873
2848<h4 id="taskcompleted-decision-control">2874<h4 id="taskcompleted-decision-control">
2849 Controllo delle decisioni di TaskCompleted2875 Controllo delle decisioni di TaskCompleted
2850</h4>2876</h4>
2851 2877
2852Gli hook TaskCompleted supportano due modi per controllare il completamento delle attività:2878Gli hook TaskCompleted supportano due modi per controllare il completamento dei task:
2853 2879
2854* **Codice di uscita 2**: l'attività non viene contrassegnata come completata e il messaggio di stderr viene restituito al modello come feedback.2880* **Codice di uscita 2**: il task non viene contrassegnato come completato e il messaggio stderr viene restituito al modello come feedback.
2855* **JSON `{"continue": false, "stopReason": "..."}`**: quando l'evento è stato attivato da un membro del team che termina il proprio turno, arresta completamente il membro del team, in modo analogo al comportamento dell'hook `Stop`. Lo `stopReason` viene mostrato all'utente. Quando l'evento è stato attivato dallo strumento `TaskUpdate`, Claude Code ignora `continue: false`; il codice di uscita 2 blocca comunque il completamento.2881* **JSON `{"continue": false, "stopReason": "..."}`**: quando l'evento è stato attivato da un compagno di team che termina il proprio turno, arresta completamente il compagno di team, in modo analogo al comportamento dell'hook `Stop`. Lo `stopReason` viene mostrato all'utente. Quando l'evento è stato attivato dallo strumento `TaskUpdate`, Claude Code ignora `continue: false`; il codice di uscita 2 blocca comunque il completamento.
2856 2882
2857Questo esempio esegue i test e blocca il completamento dell'attività se falliscono:2883Questo esempio esegue i test e blocca il completamento del task se falliscono:
2858 2884
2859```bash theme={null}2885```bash theme={null}
2860#!/bin/bash2886#!/bin/bash
2875</h3>2901</h3>
2876 2902
2877Viene eseguito quando l'agente principale di Claude Code ha finito di rispondere. Non viene eseguito se2903Viene eseguito quando l'agente principale di Claude Code ha finito di rispondere. Non viene eseguito se
2878l'arresto è avvenuto a causa di un'interruzione da parte dell'utente. Gli errori API attivano invece2904l'arresto è avvenuto a causa di un'interruzione da parte dell'utente. Gli errori API attivano
2879[StopFailure](#stopfailure).2905invece [StopFailure](#stopfailure).
2880 2906
2881<Tip>2907<Tip>
2882 Il comando [`/goal`](/docs/it/goal) è una scorciatoia integrata per un hook Stop basato su prompt con ambito di sessione. Usalo quando vuoi che Claude continui a lavorare verso una condizione senza scrivere la configurazione dell'hook.2908 Il comando [`/goal`](/docs/it/goal) è una scorciatoia integrata per un hook Stop basato su prompt con ambito di sessione. Usalo quando vuoi che Claude continui a lavorare verso una condizione senza scrivere la configurazione dell'hook.
2886 Input di Stop2912 Input di Stop
2887</h4>2913</h4>
2888 2914
2889Oltre 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 a causa di un hook stop. Controlla questo valore o elabora la trascrizione per evitare di bloccare su una condizione che non si risolverà mai.2915Oltre ai [campi di input comuni](#common-input-fields), gli hook Stop ricevono `stop_hook_active`, `last_assistant_message`, `background_tasks` e `session_crons`. Il campo `stop_hook_active` è `true` quando Claude Code sta già proseguendo a seguito di uno stop hook. Controlla questo valore o elabora la trascrizione per evitare di bloccare su una condizione che non si risolverà mai.
2890 2916
2891Claude Code applica un limite di 8 continuazioni consecutive: dopo che gli hook stop hanno fatto continuare il turno otto volte di seguito, Claude Code sovrascrive il blocco successivo e termina il turno. Il conteggio delle continuazioni consecutive si azzera ogni volta che Claude chiama uno strumento. Per aumentare il limite, imposta [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/it/env-vars).2917Claude Code applica un limite di 8 prosecuzioni consecutive: dopo che gli stop hook hanno fatto proseguire il turno otto volte di seguito, Claude Code sovrascrive il blocco successivo e termina il turno. Il conteggio delle prosecuzioni consecutive si azzera ogni volta che Claude chiama uno strumento. Per aumentare il limite, imposta [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/it/env-vars).
2892 2918
2893Il campo `last_assistant_message` contiene il contenuto testuale della risposta finale di Claude, così gli hook possono accedervi senza analizzare il file della trascrizione. Per gli hook che agiscono sul turno appena completato, come gli hook di lettura ad alta voce o di notifica, usa questo campo anziché leggere `transcript_path`: non è garantito che il file della trascrizione includa il messaggio finale al momento di Stop in tutte le versioni.2919Il campo `last_assistant_message` contiene il testo della risposta finale di Claude, così gli hook possono accedervi senza analizzare il file della trascrizione. Per gli hook che agiscono sul turno appena completato, come gli hook di lettura ad alta voce o di notifica, usa questo campo anziché leggere `transcript_path`: non è garantito che il file della trascrizione includa il messaggio finale al momento di Stop in tutte le versioni.
2894 2920
2895Gli array `background_tasks` e `session_crons` permettono agli hook di distinguere tra "la sessione è terminata" e "la sessione è in pausa in attesa che un lavoro in background la riattivi". Entrambi gli array sono presenti quando il registro delle attività è raggiungibile e sono vuoti quando non c'è nulla in corso o pianificato.2921Gli array `background_tasks` e `session_crons` permettono agli hook di distinguere tra "la sessione è terminata" e "la sessione è in pausa in attesa che un lavoro in background la riattivi". Entrambi gli array sono presenti quando il registro dei task è raggiungibile e sono vuoti quando non c'è nulla in corso o pianificato.
2896 2922
2897Ogni voce in `background_tasks` descrive un'attività in corso e usa questi campi:2923Ogni voce in `background_tasks` descrive un task in corso e usa questi campi:
2898 2924
2899| Campo | Descrizione |2925| Campo | Descrizione |
2900| :- | :- |2926| :- | :- |
2901| `id` | Identificatore dell'attività |2927| `id` | Identificatore del task |
2902| `type` | Etichetta descrittiva del tipo di attività, come `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session` o `MCP task`. Ogni etichetta identifica quale funzionalità di Claude Code ha creato l'attività. Ricade sul discriminante grezzo per i tipi non riconosciuti |2928| `type` | Etichetta descrittiva del tipo di task, come `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session` o `MCP task`. Ogni etichetta identifica quale funzionalità di Claude Code ha creato il task. Per i tipi non riconosciuti, ripiega sul discriminante grezzo |
2903| `status` | Stato attuale dell'attività |2929| `status` | Stato attuale del task |
2904| `description` | Descrizione in testo libero, limitata a 1000 caratteri con un marcatore `… [+N chars]` nella stringa quando viene troncata |2930| `description` | Descrizione in testo libero, limitata a 1000 caratteri con un indicatore `… [+N chars]` nella stringa quando viene troncata |
2905| `command` | Riga di comando della shell, limitata a 1000 caratteri. Presente solo per le attività `shell` |2931| `command` | Riga di comando della shell, limitata a 1000 caratteri. Presente solo per i task `shell` |
2906| `agent_type` | Nome del tipo di subagent. Presente solo per le attività `subagent` |2932| `agent_type` | Nome del tipo di subagent. Presente solo per i task `subagent` |
2907| `server` | Nome del server MCP. Presente solo per le attività `monitor` e `MCP task` |2933| `server` | Nome del server MCP. Presente solo per i task `monitor` e `MCP task` |
2908| `tool` | Nome dello strumento MCP. Presente solo per le attività `monitor` e `MCP task` |2934| `tool` | Nome dello strumento MCP. Presente solo per i task `monitor` e `MCP task` |
2909| `name` | Nome del workflow. Presente solo per le attività `workflow` |2935| `name` | Nome del workflow. Presente solo per i task `workflow` |
2910 2936
2911Ogni voce in `session_crons` descrive un risveglio pianificato con ambito di sessione, proveniente da `CronCreate`, `ScheduleWakeup` e `/loop`:2937Ogni voce in `session_crons` descrive una riattivazione pianificata con ambito di sessione, proveniente da `CronCreate`, `ScheduleWakeup` e `/loop`:
2912 2938
2913| Campo | Descrizione |2939| Campo | Descrizione |
2914| :- | :- |2940| :- | :- |
2915| `id` | Identificatore dell'attività cron |2941| `id` | Identificatore del task cron |
2916| `schedule` | Espressione cron, ad esempio `0 9 * * 1-5` |2942| `schedule` | Espressione cron, ad esempio `0 9 * * 1-5` |
2917| `recurring` | `false` per i risvegli singoli la cui pianificazione codifica un unico momento di attivazione, `true` per le attività che si riattivano a ogni corrispondenza |2943| `recurring` | `false` per le riattivazioni singole la cui pianificazione codifica un unico momento di attivazione, `true` per i task che si riattivano a ogni corrispondenza |
2918| `prompt` | Prompt inviato quando il cron si attiva, limitato a 1000 caratteri con lo stesso marcatore `… [+N chars]` |2944| `prompt` | Prompt inviato quando il cron si attiva, limitato a 1000 caratteri con lo stesso indicatore `… [+N chars]` |
2919 2945
2920Questo esempio mostra un input di Stop con un'attività shell in corso e un cron ricorrente:2946Questo esempio mostra un input di Stop con un task shell in corso e un cron ricorrente:
2921 2947
2922```json theme={null}2948```json theme={null}
2923{2949{
2952 Controllo delle decisioni di Stop2978 Controllo delle decisioni di Stop
2953</h4>2979</h4>
2954 2980
2955Gli hook `Stop` e `SubagentStop` possono controllare se Claude continua. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, il tuo script di hook può restituire questi campi specifici dell'evento:2981Gli hook `Stop` e `SubagentStop` possono controllare se Claude prosegue. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, lo script del tuo hook può restituire questi campi specifici dell'evento:
2956 2982
2957| Campo | Descrizione |2983| Campo | Descrizione |
2958| :- | :- |2984| :- | :- |
2959| `decision` | `"block"` impedisce a Claude di fermarsi. Omettilo per consentire a Claude di fermarsi |2985| `decision` | `"block"` impedisce a Claude di arrestarsi. Omettilo per consentire a Claude di arrestarsi |
2960| `reason` | Obbligatorio quando `decision` è `"block"`. Indica a Claude perché dovrebbe continuare |2986| `reason` | Obbligatorio quando `decision` è `"block"`. Indica a Claude perché deve proseguire |
2961| `hookSpecificOutput.additionalContext` | Feedback non di errore per Claude. La conversazione continua così Claude può agire di conseguenza, ma a differenza di `decision: "block"` viene mostrato nella trascrizione come feedback dell'hook anziché come errore dell'hook |2987| `hookSpecificOutput.additionalContext` | Feedback non di errore per Claude. La conversazione prosegue in modo che Claude possa agire di conseguenza, ma a differenza di `decision: "block"` viene mostrato nella trascrizione come feedback dell'hook anziché come errore dell'hook |
2962 2988
2963Un hook che blocca uscendo con 2 segue lo stesso percorso di `reason`: Claude riceve il messaggio di stderr come spiegazione del motivo per cui dovrebbe continuare.2989Un hook che blocca terminando con codice 2 viene instradato allo stesso modo di `reason`: Claude riceve il messaggio stderr come spiegazione del motivo per cui deve proseguire.
2964 2990
2965```json theme={null}2991```json theme={null}
2966{2992{
2969}2995}
2970```2996```
2971 2997
2972Usa `additionalContext` quando l'hook funziona come previsto e fornisce indicazioni a Claude, come "esegui la suite di test prima di finire". Mantiene attiva la conversazione tramite le stesse protezioni dai cicli di `decision: "block"`, ovvero l'input `stop_hook_active` e il limite di 8 continuazioni consecutive, ma la trascrizione lo etichetta come `Stop hook feedback` e non viene mostrata alcuna notifica di errore dell'hook:2998Usa `additionalContext` quando l'hook funziona come previsto e fornisce indicazioni a Claude, come "esegui la suite di test prima di terminare". Mantiene attiva la conversazione con le stesse protezioni contro i cicli di `decision: "block"`, ovvero l'input `stop_hook_active` e il limite di 8 prosecuzioni consecutive, ma la trascrizione lo etichetta come `Stop hook feedback` e non viene mostrata alcuna notifica di errore dell'hook:
2973 2999
2974```json theme={null}3000```json theme={null}
2975{3001{
3010}3036}
3011```3037```
3012 3038
3013Gli hook StopFailure non hanno controllo delle decisioni. Vengono eseguiti solo a scopo di notifica e di log.3039Gli hook StopFailure non hanno controllo delle decisioni. Vengono eseguiti solo a scopo di notifica e di registrazione nei log.
3014 3040
3015<h3 id="teammateidle">3041<h3 id="teammateidle">
3016 TeammateIdle3042 TeammateIdle
3017</h3>3043</h3>
3018 3044
3019Viene eseguito quando un membro di un [team di agenti](/docs/it/agent-teams) sta per diventare inattivo dopo aver terminato il proprio turno. Usalo per imporre controlli di qualità prima che un membro del team smetta di lavorare, come richiedere il superamento dei controlli lint o verificare che i file di output esistano.3045Viene eseguito quando un compagno di un [team di agenti](/docs/it/agent-teams) sta per diventare inattivo dopo aver terminato il proprio turno. Usalo per imporre controlli di qualità prima che un compagno di team smetta di lavorare, ad esempio richiedendo il superamento dei controlli lint o verificando l'esistenza dei file di output.
3020 3046
3021Gli hook TeammateIdle non supportano i matcher e si attivano a ogni occorrenza.3047Gli hook TeammateIdle non supportano i matcher e si attivano a ogni occorrenza.
3022 3048
3040 3066
3041| Campo | Descrizione |3067| Campo | Descrizione |
3042| :- | :- |3068| :- | :- |
3043| `teammate_name` | Nome del membro del team che sta per diventare inattivo |3069| `teammate_name` | Nome del compagno di team che sta per diventare inattivo |
3044| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |3070| `team_name` | Deprecato. Nome del team derivato dalla sessione; verrà rimosso in una versione futura |
3045| `agent_id` | In questo evento, il [campo di input comune](#common-input-fields) identifica il [membro del team in-process](/docs/it/agent-teams#choose-a-display-mode) che sta per diventare inattivo. Può essere assente. Richiede Claude Code v2.1.290 o successiva |3071| `agent_id` | In questo evento, il [campo di input comune](#common-input-fields) identifica il [compagno di team in-process](/docs/it/agent-teams#choose-a-display-mode) che sta per diventare inattivo. Può essere assente. Richiede Claude Code v2.1.290 o successivo |
3046 3072
3047<h4 id="teammateidle-decision-control">3073<h4 id="teammateidle-decision-control">
3048 Controllo delle decisioni di TeammateIdle3074 Controllo delle decisioni di TeammateIdle
3049</h4>3075</h4>
3050 3076
3051Gli hook TeammateIdle supportano due modi per controllare il comportamento dei membri del team:3077Gli hook TeammateIdle supportano due modi per controllare il comportamento del compagno di team:
3052 3078
3053* **Codice di uscita 2**: il membro del team riceve il messaggio di stderr come feedback e continua a lavorare invece di diventare inattivo.3079* **Codice di uscita 2**: il compagno di team riceve il messaggio stderr come feedback e continua a lavorare invece di diventare inattivo.
3054* **JSON `{"continue": false, "stopReason": "..."}`**: arresta completamente il membro del team, in modo analogo al comportamento dell'hook `Stop`. Lo `stopReason` viene mostrato all'utente.3080* **JSON `{"continue": false, "stopReason": "..."}`**: arresta completamente il compagno di team, in modo analogo al comportamento dell'hook `Stop`. Lo `stopReason` viene mostrato all'utente.
3055 3081
3056Questo esempio verifica che un artefatto di build esista prima di consentire a un membro del team di diventare inattivo:3082Questo esempio verifica che esista un artefatto di build prima di consentire a un compagno di team di diventare inattivo:
3057 3083
3058```bash theme={null}3084```bash theme={null}
3059#!/bin/bash3085#!/bin/bash
3070 ConfigChange3096 ConfigChange
3071</h3>3097</h3>
3072 3098
3073Viene eseguito quando un file di configurazione cambia durante una sessione. Usalo per controllare le modifiche alle impostazioni, applicare criteri di sicurezza o bloccare modifiche non autorizzate ai file di configurazione.3099Viene eseguito quando un file di configurazione cambia durante una sessione. Usalo per verificare le modifiche alle impostazioni, applicare policy di sicurezza o bloccare modifiche non autorizzate ai file di configurazione.
3074 3100
3075Claude Code esegue gli hook ConfigChange quando cambia un file di impostazioni, un file di criteri gestiti o un file di skill. Per i criteri gestiti, li esegue solo quando cambia `managed-settings.json` o un file in `managed-settings.d/`. Applica le [impostazioni gestite dal server](/docs/it/server-managed-settings) e le modifiche alle preferenze gestite di macOS o ai criteri del registro di Windows senza eseguirli. Su WSL con [`wslInheritsWindowsSettings`](/docs/it/settings-reference#wslinheritswindowssettings), applica anche un file di impostazioni gestite lato Windows modificato durante il proprio polling dei criteri senza eseguirli.3101Claude Code esegue gli hook ConfigChange quando cambia un file di impostazioni, un file di policy gestita o un file di skill. Per la policy gestita, li esegue solo quando cambia `managed-settings.json` o un file in `managed-settings.d/`. Applica le [impostazioni gestite dal server](/docs/it/server-managed-settings) e le modifiche alle preferenze gestite di macOS o alle policy del registro di Windows senza eseguirli. Su WSL con [`wslInheritsWindowsSettings`](/docs/it/settings-reference#wslinheritswindowssettings), applica anche un file di impostazioni gestite lato Windows modificato durante il proprio polling delle policy, senza eseguirli.
3076 3102
3077Il matcher filtra in base all'origine della configurazione:3103Il matcher filtra in base all'origine della configurazione:
3078 3104
3084| `policy_settings` | Cambia `managed-settings.json` o un file in `managed-settings.d/` |3110| `policy_settings` | Cambia `managed-settings.json` o un file in `managed-settings.d/` |
3085| `skills` | Cambia un file di skill in `.claude/skills/` |3111| `skills` | Cambia un file di skill in `.claude/skills/` |
3086 3112
3087Questo esempio registra tutte le modifiche alla configurazione per il controllo di sicurezza:3113Questo esempio registra tutte le modifiche alla configurazione per la verifica della sicurezza:
3088 3114
3089```json theme={null}3115```json theme={null}
3090{3116{
3139}3165}
3140```3166```
3141 3167
3142Le modifiche `policy_settings` non possono essere bloccate. Gli hook si attivano comunque per le origini `policy_settings` quando cambia un file di impostazioni gestite sulla macchina, quindi puoi usarli per registrare queste modifiche, ma qualsiasi decisione di blocco viene ignorata. Ciò garantisce che le impostazioni gestite dall'azienda abbiano sempre effetto. Claude Code non esegue gli hook `ConfigChange` quando le [impostazioni gestite dal server](/docs/it/server-managed-settings) arrivano o vengono aggiornate.3168Le modifiche `policy_settings` non possono essere bloccate. Gli hook si attivano comunque per le origini `policy_settings` quando cambia un file di impostazioni gestite sulla macchina, quindi puoi usarli per registrare tali modifiche, ma qualsiasi decisione di blocco viene ignorata. Ciò garantisce che le impostazioni gestite dall'azienda abbiano sempre effetto. Claude Code non esegue gli hook `ConfigChange` quando le [impostazioni gestite dal server](/docs/it/server-managed-settings) arrivano o vengono aggiornate.
3143 3169
3144Claude Code agisce sulla decisione di blocco dall'output JSON di un hook ConfigChange e scarta `systemMessage` e `continue`. Una modifica bloccata non mostra alcun messaggio né a te né a Claude, sia che tu blocchi con `reason` sia con stderr e uscita 2. Claude Code scrive solo una riga nel log di debug.3170Claude Code applica la decisione di blocco dall'output JSON di un hook ConfigChange e scarta `systemMessage` e `continue`. Una modifica bloccata non mostra alcun messaggio né a te né a Claude, sia che tu blocchi con `reason` sia con stderr e codice di uscita 2. Claude Code scrive solo una riga nel log di debug.
3145 3171
3146<h3 id="cwdchanged">3172<h3 id="cwdchanged">
3147 CwdChanged3173 CwdChanged
3174 Output di CwdChanged3200 Output di CwdChanged
3175</h4>3201</h4>
3176 3202
3177Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, gli hook CwdChanged possono restituire `watchPaths` per impostare dinamicamente quali percorsi di file vengono monitorati da [FileChanged](#filechanged):3203Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, gli hook CwdChanged possono restituire `watchPaths` per impostare dinamicamente quali percorsi di file vengono osservati da [FileChanged](#filechanged):
3178 3204
3179| Campo | Descrizione |3205| Campo | Descrizione |
3180| :- | :- |3206| :- | :- |
3181| `watchPaths` | Array di percorsi assoluti. Sostituisce l'attuale elenco di monitoraggio dinamico. I percorsi della configurazione del tuo `matcher` vengono sempre monitorati. Restituire un array vuoto cancella l'elenco dinamico, il che è tipico quando si entra in una nuova directory |3207| `watchPaths` | Array di percorsi assoluti. Sostituisce l'attuale elenco dinamico dei percorsi osservati. I percorsi della tua configurazione `matcher` vengono sempre osservati. Restituire un array vuoto cancella l'elenco dinamico, cosa tipica quando si entra in una nuova directory |
3182 3208
3183Gli hook CwdChanged non hanno controllo delle decisioni. Non possono bloccare il cambio di directory.3209Gli hook CwdChanged non hanno controllo delle decisioni. Non possono bloccare il cambio di directory.
3184 3210
3188 DirectoryAdded3214 DirectoryAdded
3189</h3>3215</h3>
3190 3216
3191Viene eseguito dopo che aggiungi una directory di lavoro a sessione in corso con il comando `/add-dir`, oppure dopo che un client SDK ne aggiunge una con la richiesta di controllo `register_repo_root`. Usalo per preparare un repository appena aggiunto, ad esempio installandone le dipendenze.3217Viene eseguito dopo che aggiungi una directory di lavoro a sessione in corso con il comando `/add-dir`, o dopo che un client SDK ne aggiunge una con la richiesta di controllo `register_repo_root`. Usalo per preparare un repository appena aggiunto, ad esempio installandone le dipendenze.
3192 3218
3193Claude Code non attiva questo evento quando:3219Claude Code non attiva questo evento quando:
3194 3220
3195* Passi una directory con il flag di avvio `--add-dir`; [SessionStart](#sessionstart) copre quelle directory3221* Passi una directory con il flag di avvio `--add-dir`; [SessionStart](#sessionstart) copre queste directory
3196* Aggiungi una directory nella scheda Workspace di `/permissions`3222* Aggiungi una directory nella scheda Workspace di `/permissions`
3197* Aggiungi una directory che è già una directory di lavoro o si trova al suo interno3223* Aggiungi una directory che è già una directory di lavoro o si trova all'interno di una
3198 3224
3199Claude Code attiva DirectoryAdded dopo aver aggiornato lo stato della sandbox e dei permessi, quindi gli strumenti in sandbox vedono già la nuova directory quando il tuo hook viene eseguito. I comandi degli hook stessi vengono eseguiti senza sandbox.3225Claude Code attiva DirectoryAdded dopo aver aggiornato lo stato della sandbox e dei permessi, quindi gli strumenti in sandbox vedono già la nuova directory quando il tuo hook viene eseguito. I comandi degli hook stessi vengono eseguiti fuori dalla sandbox.
3200 3226
3201Claude Code non attende l'hook: l'aggiunta viene completata immediatamente e l'hook viene eseguito in background con il timeout predefinito di 600 secondi.3227Claude Code non attende l'hook: l'aggiunta viene completata immediatamente e l'hook viene eseguito in background con il timeout predefinito di 600 secondi.
3202 3228
3203Il matcher filtra in base a come è stata aggiunta la directory:3229Il matcher filtra in base al modo in cui è stata aggiunta la directory:
3204 3230
3205| Matcher | Quando si attiva |3231| Matcher | Quando si attiva |
3206| :- | :- |3232| :- | :- |
3215 3241
3216| Campo | Descrizione |3242| Campo | Descrizione |
3217| :- | :- |3243| :- | :- |
3218| `directory` | Percorso assoluto della directory che è stata aggiunta |3244| `directory` | Percorso assoluto della directory aggiunta |
3219| `source` | Come è stata aggiunta la directory, `"slash_command"` per `/add-dir` o `"register_repo_root"` per la richiesta di controllo dell'SDK |3245| `source` | Il modo in cui è stata aggiunta la directory: `"slash_command"` per `/add-dir` o `"register_repo_root"` per la richiesta di controllo dell'SDK |
3220 3246
3221```json theme={null}3247```json theme={null}
3222{3248{
3229}3255}
3230```3256```
3231 3257
3232Gli hook DirectoryAdded non hanno controllo delle decisioni. Non possono bloccare l'aggiunta, che è già stata completata quando l'hook viene eseguito. Claude Code scarta il campo `continue` dal loro output JSON e gestisce il resto in modo diverso in base all'origine:3258Gli hook DirectoryAdded non hanno controllo delle decisioni. Non possono bloccare l'aggiunta, che è già completata quando l'hook viene eseguito. Claude Code scarta il campo `continue` dal loro output JSON e gestisce il resto in modo diverso a seconda dell'origine:
3233 3259
3234* `slash_command`: Claude Code consegna il `systemMessage` dell'hook a Claude come contesto al turno successivo della conversazione, anziché mostrarlo a te. Nella trascrizione appare il conteggio degli hook falliti. L'output completo degli errori va nel log di debug3260* `slash_command`: Claude Code consegna il `systemMessage` dell'hook a Claude come contesto nel turno successivo della conversazione, anziché mostrarlo a te. Nella trascrizione compare il conteggio degli hook falliti. L'output completo dei fallimenti va nel log di debug
3235* `register_repo_root`: Claude Code scrive l'output di `systemMessage` e l'output degli errori solo nel log di debug3261* `register_repo_root`: Claude Code scrive l'output di `systemMessage` e l'output dei fallimenti solo nel log di debug
3236 3262
3237<h3 id="filechanged">3263<h3 id="filechanged">
3238 FileChanged3264 FileChanged
3239</h3>3265</h3>
3240 3266
3241Viene eseguito quando un file monitorato cambia su disco. Claude Code rileva le modifiche con un watcher del filesystem, non ispezionando le chiamate agli strumenti, quindi esegue l'hook indipendentemente da cosa abbia modificato il file: una chiamata allo strumento `Edit` o `Write`, uno script che Claude esegue con `Bash` o un processo completamente esterno a Claude Code. Un uso comune è ricaricare le variabili d'ambiente quando cambiano i file di configurazione del progetto.3267Viene eseguito quando un file monitorato cambia sul disco. Claude Code rileva le modifiche con un watcher del filesystem, non esaminando le chiamate agli strumenti, quindi esegue l'hook indipendentemente da cosa abbia modificato il file: una chiamata allo strumento `Edit` o `Write`, uno script che Claude esegue con `Bash` o un processo completamente esterno a Claude Code. Un uso comune è ricaricare le variabili d'ambiente quando cambiano i file di configurazione del progetto.
3242 3268
3243Il `matcher` per questo evento ha due ruoli:3269Il `matcher` per questo evento ha due ruoli:
3244 3270
3245* **Costruire l'elenco di monitoraggio**: il valore viene suddiviso su `|` e ogni segmento viene registrato come nome di file letterale nella directory di lavoro, quindi `".envrc|.env"` monitora esattamente quei due file. I pattern regex non sono utili qui: un valore come `^\.env` monitorerebbe un file chiamato letteralmente `^\.env`.3271* **Creare l'elenco dei file monitorati**: il valore viene suddiviso in corrispondenza di `|` e ogni segmento viene registrato come nome di file letterale nella directory di lavoro, quindi `".envrc|.env"` monitora esattamente quei due file. I pattern regex non sono utili qui: un valore come `^\.env` monitorerebbe un file chiamato letteralmente `^\.env`.
3246* **Filtrare quali hook vengono eseguiti**: quando un file monitorato cambia, lo stesso valore filtra quali gruppi di hook vengono eseguiti usando le [regole standard dei matcher](#matcher-patterns) sul nome base del file modificato.3272* **Filtrare quali hook vengono eseguiti**: quando un file monitorato cambia, lo stesso valore filtra quali gruppi di hook vengono eseguiti usando le [regole standard del matcher](#matcher-patterns) sul basename del file modificato.
3247 3273
3248Questo esempio normalizza i fine riga in `data.csv` dopo qualsiasi modifica, inclusa la riscrittura del file da parte di un comando `Bash` o di uno script esterno:3274Questo esempio normalizza i fine riga in `data.csv` dopo qualsiasi modifica, incluso un comando `Bash` o uno script esterno che riscrive il file:
3249 3275
3250```json theme={null}3276```json theme={null}
3251{3277{
3265}3291}
3266```3292```
3267 3293
3268L'hook legge il percorso assoluto del file modificato dal campo `file_path` dell'[input JSON](#filechanged-input) su stdin. Il suo controllo con `grep` verifica la stessa cosa che `perl` rimuove, un CR alla fine di una riga, quindi l'esecuzione successiva a una normalizzazione termina senza toccare il file. Un controllo meno rigoroso entra in un ciclo infinito, perché `perl -i` riscrive il file anche quando non sostituisce nulla e Claude Code esegue di nuovo l'hook dopo ogni riscrittura. Salva questo script in `/path/to/normalize-line-endings.sh` e rendilo eseguibile:3294L'hook legge il percorso assoluto del file modificato dal campo `file_path` dell'[input JSON](#filechanged-input) su stdin. Il suo controllo con `grep` verifica la stessa cosa che `perl` rimuove, un CR alla fine di una riga, quindi l'esecuzione successiva a una normalizzazione termina senza toccare il file. Un controllo meno preciso entra in un ciclo infinito, perché `perl -i` riscrive il file anche quando non sostituisce nulla e Claude Code esegue di nuovo l'hook dopo ogni riscrittura. Salva questo script in `/path/to/normalize-line-endings.sh` e rendilo eseguibile:
3269 3295
3270```bash theme={null}3296```bash theme={null}
3271#!/bin/bash3297#!/bin/bash
3277 3303
3278Per verificare che l'hook funzioni, chiedi a Claude di aggiungere una riga CRLF a `data.csv` con un comando `Bash`. Claude Code esegue l'hook e il file finisce con fine riga LF.3304Per verificare che l'hook funzioni, chiedi a Claude di aggiungere una riga CRLF a `data.csv` con un comando `Bash`. Claude Code esegue l'hook e il file finisce con fine riga LF.
3279 3305
3280Per monitorare file che non puoi nominare in anticipo, restituisci [`watchPaths`](#filechanged-output) da un hook per aggiornare dinamicamente l'elenco di monitoraggio. Claude Code avvia il watcher solo quando qualcosa nomina un file da monitorare, quindi inizializza l'elenco con un gruppo FileChanged il cui matcher nomina almeno un file, oppure con un hook [SessionStart](#sessionstart-decision-control) o [CwdChanged](#cwdchanged) che restituisce `watchPaths`. Il matcher filtra comunque quali gruppi di hook vengono eseguiti quando un file monitorato cambia, quindi assegna al gruppo che gestisce i percorsi dinamici un matcher omesso, che corrisponde a ogni file monitorato e non aggiunge nulla all'elenco di monitoraggio. Anche un matcher `"*"` corrisponde a ogni file, ma Claude Code lo registra nell'elenco di monitoraggio come qualsiasi altro valore, come un file letterale chiamato `*`.3306Per monitorare file che non puoi nominare in anticipo, restituisci [`watchPaths`](#filechanged-output) da un hook per aggiornare dinamicamente l'elenco dei file monitorati. Claude Code avvia il watcher solo quando qualcosa indica un file da monitorare, quindi inizializza l'elenco con un gruppo FileChanged il cui matcher nomina almeno un file, oppure con un hook [SessionStart](#sessionstart-decision-control) o [CwdChanged](#cwdchanged) che restituisce `watchPaths`. Il matcher filtra comunque quali gruppi di hook vengono eseguiti quando un file monitorato cambia, quindi ometti il matcher nel gruppo che gestisce i percorsi dinamici: così corrisponde a ogni file monitorato e non aggiunge nulla all'elenco. Anche un matcher `"*"` corrisponde a ogni file, ma Claude Code lo registra nell'elenco dei file monitorati come qualsiasi altro valore, cioè come un file chiamato letteralmente `*`.
3281 3307
3282Gli hook FileChanged hanno accesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Le variabili scritte in quel file persistono nei comandi Bash successivi fino al successivo evento [CwdChanged](#cwdchanged), quando Claude Code le cancella.3308Gli hook FileChanged hanno accesso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Le variabili scritte in quel file persistono nei comandi Bash successivi fino al prossimo evento [CwdChanged](#cwdchanged), quando Claude Code le cancella.
3283 3309
3284<h4 id="filechanged-input">3310<h4 id="filechanged-input">
3285 Input di FileChanged3311 Input di FileChanged
3289 3315
3290| Campo | Descrizione |3316| Campo | Descrizione |
3291| :- | :- |3317| :- | :- |
3292| `file_path` | Percorso assoluto del file che è cambiato |3318| `file_path` | Percorso assoluto del file modificato |
3293| `event` | Cosa è successo: `"change"` per un file modificato, `"add"` per un file creato o `"unlink"` per un file eliminato |3319| `event` | Cosa è successo: `"change"` per un file modificato, `"add"` per un file creato o `"unlink"` per un file eliminato |
3294 3320
3295```json theme={null}3321```json theme={null}
3311 3337
3312| Campo | Descrizione |3338| Campo | Descrizione |
3313| :- | :- |3339| :- | :- |
3314| `watchPaths` | Array di percorsi assoluti. Sostituisce l'attuale elenco di monitoraggio dinamico. I percorsi della configurazione del tuo `matcher` vengono sempre monitorati. Usalo quando il tuo script di hook scopre file aggiuntivi da monitorare in base al file modificato |3340| `watchPaths` | Array di percorsi assoluti. Sostituisce l'elenco dinamico corrente dei file monitorati. I percorsi dalla configurazione del tuo `matcher` vengono sempre monitorati. Usalo quando lo script del tuo hook individua file aggiuntivi da monitorare in base al file modificato |
3315 3341
3316Gli hook FileChanged non hanno controllo delle decisioni. Non possono impedire che la modifica del file avvenga.3342Gli hook FileChanged non hanno controllo decisionale. Non possono impedire che la modifica del file avvenga.
3317 3343
3318Claude Code legge `watchPaths` e `systemMessage` dal loro output JSON e scarta `continue`. Nelle sessioni interattive, mostra il `systemMessage` come breve notifica nel terminale. Il messaggio non raggiunge il flusso di messaggi dell'SDK.3344Claude Code legge `watchPaths` e `systemMessage` dal loro output JSON e scarta `continue`. Nelle sessioni interattive, mostra `systemMessage` come una breve notifica nel terminale. Il messaggio non raggiunge lo stream di messaggi dell'SDK.
3319 3345
3320<h3 id="worktreecreate">3346<h3 id="worktreecreate">
3321 WorktreeCreate3347 WorktreeCreate
3324Viene eseguito quando Claude Code crea un worktree in casi come questi:3350Viene eseguito quando Claude Code crea un worktree in casi come questi:
3325 3351
3326* Avvii una sessione con `claude --worktree`3352* Avvii una sessione con `claude --worktree`
3327* Claude crea un worktree durante una sessione e vi si sposta con lo strumento [`EnterWorktree`](/docs/it/tools-reference)3353* Claude crea un worktree durante una sessione e ci passa con lo strumento [`EnterWorktree`](/docs/it/tools-reference)
3328* Un [subagent usa `isolation: "worktree"`](/docs/it/sub-agents#choose-the-subagent-scope)3354* Un [subagent usa `isolation: "worktree"`](/docs/it/sub-agents#choose-the-subagent-scope)
3329* Un [workflow](/docs/it/workflows#migrate-many-files-in-parallel) esegue un agente nel proprio worktree3355* Un [workflow](/docs/it/workflows#migrate-many-files-in-parallel) esegue un agente nel proprio worktree
3330* Claude Code isola una [sessione in background](/docs/it/agent-view#how-file-edits-are-isolated) nel proprio worktree3356* Claude Code isola una [sessione in background](/docs/it/agent-view#how-file-edits-are-isolated) nel proprio worktree
3331* [`claude remote-control`](/docs/it/remote-control#start-a-remote-control-session) in modalità `worktree` avvia una sessione nel proprio worktree3357* [`claude remote-control`](/docs/it/remote-control#start-a-remote-control-session) in modalità `worktree` avvia una sessione nel proprio worktree
3332 3358
3333Quando Claude esegue `git worktree add` tramite lo strumento Bash invece di chiamare `EnterWorktree`, il tuo hook WorktreeCreate non viene eseguito. Per ispezionare o bloccare quel comando, aggiungi un hook [`PreToolUse`](#pretooluse) con il matcher `Bash`.3359Quando Claude esegue `git worktree add` tramite lo strumento Bash invece di chiamare `EnterWorktree`, il tuo hook WorktreeCreate non viene eseguito. Per esaminare o bloccare quel comando, aggiungi un hook [`PreToolUse`](#pretooluse) con il matcher `Bash`.
3334 3360
3335Per 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 versione diverso come SVN, Perforce o Mercurial.3361Per impostazione predefinita Claude Code crea la copia di lavoro isolata con `git worktree`. Configurare un hook WorktreeCreate sostituisce quel comportamento predefinito di git, permettendoti di usare un diverso sistema di controllo versione come SVN, Perforce o Mercurial.
3336 3362
3337Poiché l'hook sostituisce interamente il comportamento predefinito, [`.worktreeinclude`](/docs/it/worktrees#copy-gitignored-files-into-worktrees) non viene elaborato. Se devi copiare file di configurazione locali come `.env` nel nuovo worktree, fallo all'interno del tuo script hook.3363Poiché l'hook sostituisce interamente il comportamento predefinito, [`.worktreeinclude`](/docs/it/worktrees#copy-gitignored-files-into-worktrees) non viene elaborato. Se devi copiare file di configurazione locali come `.env` nel nuovo worktree, fallo all'interno dello script del tuo hook.
3338 3364
3339L'hook deve restituire il percorso della directory del worktree creato. Claude Code usa questo percorso come directory di lavoro per la sessione isolata. Consulta [Output di WorktreeCreate](#worktreecreate-output) per sapere come ciascun tipo di hook restituisce il percorso.3365L'hook deve restituire il percorso della directory del worktree creato. Claude Code usa questo percorso come directory di lavoro per la sessione isolata. Consulta [Output di WorktreeCreate](#worktreecreate-output) per sapere come ogni tipo di hook restituisce il percorso.
3340 3366
3341Claude Code agisce in base al successo dell'hook e al percorso restituito, e scarta `systemMessage` e `continue`.3367Claude Code agisce in base all'esito positivo dell'hook e al percorso restituito, e scarta `systemMessage` e `continue`.
3342 3368
3343Questo esempio crea una copia di lavoro SVN e stampa il percorso che Claude Code dovrà usare. Sostituisci l'URL del repository con il tuo:3369Questo esempio crea una copia di lavoro SVN e stampa il percorso che Claude Code deve usare. Sostituisci l'URL del repository con il tuo:
3344 3370
3345```json theme={null}3371```json theme={null}
3346{3372{
3359}3385}
3360```3386```
3361 3387
3362L'hook legge il `name` del worktree dall'input JSON su stdin, esegue il checkout di una copia nuova in una nuova directory e stampa il percorso della directory. L'`echo` sull'ultima riga è ciò che Claude Code legge come percorso del worktree. Reindirizza qualsiasi altro output su stderr in modo che non interferisca con il percorso.3388L'hook legge il `name` del worktree dall'input JSON su stdin, esegue il checkout di una copia nuova in una nuova directory e stampa il percorso della directory. L'`echo` nell'ultima riga è ciò che Claude Code legge come percorso del worktree. Reindirizza qualsiasi altro output su stderr in modo che non interferisca con il percorso.
3363 3389
3364<h4 id="worktreecreate-input">3390<h4 id="worktreecreate-input">
3365 Input di WorktreeCreate3391 Input di WorktreeCreate
3381 Output di WorktreeCreate3407 Output di WorktreeCreate
3382</h4>3408</h4>
3383 3409
3384Gli hook WorktreeCreate non usano il modello decisionale standard allow/block. Al contrario, è il successo o il fallimento dell'hook a determinare l'esito. L'hook deve restituire il percorso della directory del worktree creato:3410Gli hook WorktreeCreate non usano il modello decisionale standard allow/block. L'esito dipende invece dal successo o dal fallimento dell'hook. L'hook deve restituire il percorso della directory del worktree creato:
3385 3411
3386* **Hook di comando** (`type: "command"`): stampa il percorso come ultima riga non vuota di stdout. Claude Code rimuove i codici di escape ANSI prima di leggere quella riga, quindi i banner di avvio della shell stampati prima del tuo `echo` vengono ignorati. Reindirizza qualsiasi altro output dell'hook su stderr.3412* **Hook di tipo command** (`type: "command"`): stampa il percorso come ultima riga non vuota di stdout. Claude Code rimuove i codici di escape ANSI prima di leggere quella riga, quindi i banner di avvio della shell stampati prima del tuo `echo` vengono ignorati. Reindirizza qualsiasi altro output dell'hook su stderr.
3387* **Hook HTTP** (`type: "http"`): restituisci `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` nel corpo della risposta.3413* **Hook HTTP** (`type: "http"`): restituisci `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` nel corpo della risposta.
3388 3414
3389Se l'hook fallisce o non produce alcun percorso, la creazione del worktree fallisce con un errore.3415Se l'hook fallisce o non produce alcun percorso, la creazione del worktree fallisce con un errore.
3390 3416
3391Claude Code risolve un percorso relativo rispetto alla directory in cui è stato eseguito l'hook, riducendo gli eventuali segmenti `.` o `..` al suo interno. Se il percorso risultante non è una directory in cui Claude Code può entrare, la sessione stampa un errore che indica il percorso ed esce con codice 1.3417Claude Code risolve un percorso relativo rispetto alla directory in cui è stato eseguito l'hook, comprimendo eventuali segmenti `.` o `..` al suo interno. Se il percorso risultante non è una directory in cui Claude Code può entrare, la sessione stampa un errore che indica il percorso ed esce con codice 1.
3392 3418
3393Claude Code rifiuta un percorso assoluto che contiene segmenti `.` o `..`, e qualsiasi percorso che passa attraverso un collegamento simbolico sotto la radice del repository, perché un collegamento simbolico sottoposto a commit nel repository potrebbe reindirizzare il worktree al di fuori di esso. L'errore indica il componente rifiutato. Restituisci un percorso normalizzato che non passi attraverso un collegamento simbolico all'interno del repository. Prima della v2.1.216, la creazione del worktree seguiva il percorso dell'hook senza questo controllo.3419Claude Code rifiuta un percorso assoluto che contiene segmenti `.` o `..`, e qualsiasi percorso che passa attraverso un collegamento simbolico sotto la radice del repository, perché un collegamento simbolico di cui è stato fatto il commit nel repository potrebbe reindirizzare il worktree al di fuori di esso. L'errore indica il componente rifiutato. Restituisci un percorso normalizzato che non passi attraverso un collegamento simbolico all'interno del repository. Prima della v2.1.216, la creazione del worktree seguiva il percorso dell'hook senza questo controllo.
3394 3420
3395<h3 id="worktreeremove">3421<h3 id="worktreeremove">
3396 WorktreeRemove3422 WorktreeRemove
3402* Esci da una sessione worktree interattiva a cui non hai [dato un nome](/docs/it/sessions#name-your-sessions), Claude Code non trova file modificati o non tracciati e rimuove il worktree senza chiedertelo3428* Esci da una sessione worktree interattiva a cui non hai [dato un nome](/docs/it/sessions#name-your-sessions), Claude Code non trova file modificati o non tracciati e rimuove il worktree senza chiedertelo
3403* Elimini una [sessione in background](/docs/it/agent-view#what-deleting-a-session-removes) che viene eseguita nel worktree3429* Elimini una [sessione in background](/docs/it/agent-view#what-deleting-a-session-removes) che viene eseguita nel worktree
3404* Chiedi a Claude di uscire e rimuovere il worktree durante una sessione, e Claude lo rimuove con lo strumento [`ExitWorktree`](/docs/it/tools-reference)3430* Chiedi a Claude di uscire e rimuovere il worktree durante una sessione, e Claude lo rimuove con lo strumento [`ExitWorktree`](/docs/it/tools-reference)
3405* Una sessione che [`claude remote-control`](/docs/it/remote-control#start-a-remote-control-session) ha avviato in modalità `worktree` termina senza arresti anomali, e Claude Code non trova file modificati o non tracciati né nuovi commit nel suo worktree3431* Una sessione avviata da [`claude remote-control`](/docs/it/remote-control#start-a-remote-control-session) in modalità `worktree` termina senza arresti anomali, e Claude Code non trova file modificati o non tracciati né nuovi commit nel suo worktree
3406* Arresti `claude remote-control` mentre le sessioni che ha avviato in modalità `worktree` sono ancora in esecuzione, e Claude Code non trova file modificati o non tracciati né nuovi commit nei loro worktree3432* Arresti `claude remote-control` mentre le sessioni che ha avviato in modalità `worktree` sono ancora in esecuzione, e Claude Code non trova file modificati o non tracciati né nuovi commit nei loro worktree
3407 3433
3408Quando un subagent o un agente di un workflow termina, Claude Code mantiene il worktree che il tuo hook WorktreeCreate ha creato per esso e non esegue il tuo hook WorktreeRemove. Rimuovi tu stesso quei worktree quando il lavoro è terminato.3434Quando un subagent o un agente di un workflow termina, Claude Code mantiene il worktree che il tuo hook WorktreeCreate ha creato per esso e non esegue il tuo hook WorktreeRemove. Rimuovi tu stesso quei worktree quando il lavoro è finito.
3409 3435
3410Claude Code non ti chiede conferma prima che il tuo hook venga eseguito per una chiamata a `ExitWorktree` o per una pulizia di `claude remote-control`. `ExitWorktree` si rifiuta di rimuovere un worktree creato da un hook a meno che la chiamata non passi [`discard_changes: true`](/docs/it/agent-sdk/typescript#exitworktree), il che rende il tuo hook l'ultimo controllo su quel percorso.3436Claude Code non ti chiede conferma prima che il tuo hook venga eseguito per una chiamata `ExitWorktree` o per una pulizia di `claude remote-control`. `ExitWorktree` si rifiuta di rimuovere un worktree creato da un hook a meno che la chiamata non passi [`discard_changes: true`](/docs/it/agent-sdk/typescript#exitworktree), il che rende il tuo hook l'ultimo controllo su quel percorso.
3411 3437
3412Claude Code usa git per cercare file modificati o non tracciati, quindi non ne trova nessuno in un worktree che non è un checkout git né si trova all'interno di uno, anche quando la directory contiene lavoro non sottoposto a commit. Controlla la presenza di tale lavoro nel tuo hook WorktreeRemove prima che elimini qualsiasi cosa.3438Claude Code usa git per cercare file modificati o non tracciati, quindi non ne trova nessuno in un worktree che non è un checkout git né si trova all'interno di uno, anche quando la directory contiene lavoro non sottoposto a commit. Verifica la presenza di quel lavoro nel tuo hook WorktreeRemove prima che elimini qualcosa.
3413 3439
3414Per i worktree basati su Git, Claude Code gestisce la pulizia automaticamente con `git worktree remove`. Se hai configurato un hook WorktreeCreate, abbinalo a un hook WorktreeRemove per controllare la pulizia:3440Per i worktree basati su git, Claude Code gestisce la pulizia automaticamente con `git worktree remove`. Se hai configurato un hook WorktreeCreate, abbinalo a un hook WorktreeRemove per controllare la pulizia:
3415 3441
3416* **Nessun hook WorktreeRemove**: Claude Code ripiega su Git per una rimozione all'uscita o tramite `ExitWorktree`, e mantiene il worktree quando è `claude remote-control` a eseguire la pulizia:3442* **Nessun hook WorktreeRemove**: Claude Code ripiega su git per una rimozione all'uscita o tramite `ExitWorktree`, e mantiene il worktree quando `claude remote-control` esegue la pulizia:
3417 * **Esci da una sessione in un worktree, oppure Claude chiama `ExitWorktree`**: Claude Code rimuove il percorso restituito dal tuo hook WorktreeCreate come farebbe `git worktree remove --force`, quindi un worktree riconosciuto da Git viene rimosso. Un worktree che Git non riconosce, ad esempio uno che il tuo hook ha creato con un sistema di controllo versione diverso da Git, rimane su disco.3443 * **Esci da una sessione worktree, oppure Claude chiama `ExitWorktree`**: Claude Code rimuove il percorso restituito dal tuo hook WorktreeCreate come farebbe `git worktree remove --force`, quindi un worktree riconosciuto da git viene rimosso. Un worktree che git non riconosce, ad esempio uno creato dal tuo hook con un sistema di controllo versione diverso da git, rimane sul disco.
3418 * **`claude remote-control` rimuove il worktree di una sessione**: il worktree rimane su disco e il terminale in cui è in esecuzione `claude remote-control` mostra `worktree removal failed, kept: <path>`.3444 * **`claude remote-control` ripulisce il worktree di una sessione**: il worktree rimane sul disco, e il terminale che esegue `claude remote-control` mostra `worktree removal failed, kept: <path>`.
3419 * **Elimini una sessione in background**: consulta [Cosa rimuove l'eliminazione di una sessione](/docs/it/agent-view#what-deleting-a-session-removes).3445 * **Elimini una sessione in background**: consulta [Cosa rimuove l'eliminazione di una sessione](/docs/it/agent-view#what-deleting-a-session-removes).
3420* **L'hook esce con 0**: il worktree viene considerato rimosso. Claude Code non legge nient'altro dall'hook, quindi assicurati che il tuo hook abbia eliminato la directory.3446* **L'hook esce con 0**: il worktree è considerato rimosso. Claude Code non legge nient'altro dall'hook, quindi assicurati che il tuo hook abbia eliminato la directory.
3421* **L'hook esce con un codice diverso da zero**: la rimozione fallisce se la directory in `worktree_path` esiste ancora in seguito, e il worktree rimane su disco senza fallback git. Un hook che ha eliminato la directory prima di uscire con un codice diverso da zero viene considerato come rimosso. Per sapere come viene segnalato il fallimento, consulta [Input di WorktreeRemove](#worktreeremove-input).3447* **L'hook esce con un codice diverso da zero**: la rimozione fallisce se la directory in `worktree_path` esiste ancora dopo l'esecuzione, e il worktree rimane sul disco senza alcun fallback su git. Un hook che ha eliminato la directory prima di uscire con un codice diverso da zero è considerato come rimosso. Per sapere come viene segnalato l'errore, consulta [Input di WorktreeRemove](#worktreeremove-input).
3422 3448
3423Claude Code non elimina mai un branch appartenente a un worktree creato da un hook, perché conosce solo il percorso restituito dal tuo hook WorktreeCreate. Se il tuo hook WorktreeCreate crea un branch, eliminalo nel tuo hook WorktreeRemove.3449Claude Code non elimina mai un branch appartenente a un worktree creato da un hook, perché conosce solo il percorso restituito dal tuo hook WorktreeCreate. Se il tuo hook WorktreeCreate crea un branch, eliminalo nel tuo hook WorktreeRemove.
3424 3450
3425Claude Code scarta i [campi di output JSON](#json-output) di un hook WorktreeRemove, come `systemMessage` e `continue`.3451Claude Code scarta i [campi di output JSON](#json-output) di un hook WorktreeRemove, come `systemMessage` e `continue`.
3426 3452
3427Per l'eliminazione di una sessione in background, Claude Code verifica il percorso del worktree memorizzato prima di eseguire l'hook e rifiuta un percorso che è un collegamento simbolico o che ne attraversa uno sotto la root del repository. In quel caso, l'hook viene eseguito per un worktree che contiene ancora file solo quando confermi l'eliminazione nella [vista degli agenti](/docs/it/agent-view#what-deleting-a-session-removes); per un worktree di questo tipo, [`claude rm`](/docs/it/agent-view#manage-sessions-from-the-shell) mantiene invece la sessione e il worktree. Prima della v2.1.216, l'hook veniva eseguito sul percorso memorizzato senza questi controlli.3453Per l'eliminazione di una sessione in background, Claude Code verifica il percorso del worktree memorizzato prima di eseguire l'hook e rifiuta un percorso che è un collegamento simbolico o che passa attraverso uno di essi sotto la radice del repository. In quel caso, l'hook viene eseguito per un worktree che contiene ancora file solo quando confermi l'eliminazione nella [vista agenti](/docs/it/agent-view#what-deleting-a-session-removes); per un worktree di questo tipo, [`claude rm`](/docs/it/agent-view#manage-sessions-from-the-shell) mantiene invece la sessione e il worktree. Prima della v2.1.216, l'hook veniva eseguito sul percorso memorizzato senza questi controlli.
3428 3454
3429Claude Code passa il percorso restituito da WorktreeCreate come `worktree_path` nell'input dell'hook. Questo esempio legge quel percorso e rimuove la directory:3455Claude Code passa il percorso restituito da WorktreeCreate come `worktree_path` nell'input dell'hook. Questo esempio legge quel percorso e rimuove la directory:
3430 3456
3461}3487}
3462```3488```
3463 3489
3464Il codice di uscita di un hook WorktreeRemove decide l'esito. Quando un hook esce con un codice diverso da zero e la directory in `worktree_path` esiste ancora in seguito, la rimozione fallisce:3490Il codice di uscita di un hook WorktreeRemove determina l'esito. Quando un hook esce con un codice diverso da zero e la directory in `worktree_path` esiste ancora dopo l'esecuzione, la rimozione fallisce:
3465 3491
3466* Il worktree rimane su disco, e il comando e lo stderr dell'hook finiscono nel [log di debug](#debug-hooks).3492* Il worktree rimane sul disco, e il comando e lo stderr dell'hook finiscono nel [log di debug](#debug-hooks).
3467* Se stavi eliminando una sessione in background, anche la sessione rimane. Il messaggio di rifiuto nella [vista agente](/docs/it/agent-view#what-deleting-a-session-removes) riporta come è terminato l'hook, ad esempio `exited 1`, cita l'inizio del suo stderr e indica se eliminare di nuovo la sessione rimuove comunque la directory.3493* Se stavi eliminando una sessione in background, anche la sessione rimane. Il messaggio di rifiuto nella [vista agenti](/docs/it/agent-view#what-deleting-a-session-removes) riporta come è terminato l'hook, ad esempio `exited 1`, cita l'inizio del suo stderr e indica se eliminando di nuovo la sessione la directory viene comunque rimossa.
3468* Se `claude remote-control` stava rimuovendo il worktree di una sessione, il terminale in cui è in esecuzione mostra `worktree removal failed, kept: <path>`.3494* Se `claude remote-control` stava ripulendo il worktree di una sessione, il terminale che lo esegue mostra `worktree removal failed, kept: <path>`.
3469 3495
3470<h3 id="precompact">3496<h3 id="precompact">
3471 PreCompact3497 PreCompact
3472</h3>3498</h3>
3473 3499
3474Viene eseguito prima che Claude Code stia per eseguire un'operazione di compattazione.3500Viene eseguito prima che Claude Code esegua un'operazione di compattazione.
3475 3501
3476Il valore del matcher indica se la compattazione è stata attivata manualmente o automaticamente:3502Il valore del matcher indica se la compattazione è stata attivata manualmente o automaticamente:
3477 3503
3478| Matcher | Quando si attiva |3504| Matcher | Quando si attiva |
3479| :- | :- |3505| :- | :- |
3480| `manual` | `/compact` |3506| `manual` | `/compact` |
3481| `auto` | Compattazione automatica quando la conversazione raggiunge la [finestra di compattazione automatica](/docs/it/model-config#set-the-auto-compact-window) |3507| `auto` | Compattazione automatica quando la conversazione raggiunge la [finestra di compattazione automatica](/docs/it/model-config#set-the-auto-compact-window), e [compattazione in caso di inattività](/docs/it/settings-reference#idlecompaction) |
3482 3508
3483Esci 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"`.3509Esci con codice 2 per bloccare la compattazione. Per un `/compact` manuale, il messaggio stderr viene mostrato all'utente. Puoi anche bloccare restituendo un JSON con `"decision": "block"`.
3484 3510
3485Bloccare la compattazione automatica ha effetti diversi a seconda di quando si attiva. Se la compattazione è stata attivata in modo proattivo prima del limite di contesto, Claude Code la salta e la conversazione continua senza compattazione. Se la compattazione è stata attivata per recuperare da un errore di limite di contesto già restituito dall'API, l'errore sottostante emerge e la richiesta corrente fallisce.3511Bloccare la compattazione automatica ha effetti diversi a seconda di quando si attiva. Se la compattazione è stata attivata in modo preventivo prima del limite di contesto, Claude Code la salta e la conversazione continua senza essere 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.
3486 3512
3487Claude Code scarta i campi `systemMessage` e `continue` di un hook PreCompact.3513Claude Code scarta i campi `systemMessage` e `continue` di un hook PreCompact.
3488 3514
3507 PostCompact3533 PostCompact
3508</h3>3534</h3>
3509 3535
3510Viene eseguito dopo che Claude Code ha completato un'operazione di compattazione. Usa questo evento per reagire al nuovo stato compattato, ad esempio per registrare il riepilogo generato o aggiornare uno stato esterno. Claude Code scarta i campi `systemMessage` e `continue` di un hook PostCompact.3536Viene eseguito dopo che Claude Code completa un'operazione di compattazione. Usa questo evento per reagire al nuovo stato compattato, ad esempio per registrare il riepilogo generato o aggiornare uno stato esterno. Claude Code scarta i campi `systemMessage` e `continue` di un hook PostCompact.
3511 3537
3512Si applicano gli stessi valori del matcher di `PreCompact`:3538Si applicano gli stessi valori del matcher di `PreCompact`:
3513 3539
3514| Matcher | Quando si attiva |3540| Matcher | Quando si attiva |
3515| :- | :- |3541| :- | :- |
3516| `manual` | Dopo `/compact` |3542| `manual` | Dopo `/compact` |
3517| `auto` | Dopo la compattazione automatica quando la conversazione raggiunge la [finestra di compattazione automatica](/docs/it/model-config#set-the-auto-compact-window) |3543| `auto` | Dopo la compattazione automatica quando la conversazione raggiunge la [finestra di compattazione automatica](/docs/it/model-config#set-the-auto-compact-window), e dopo la [compattazione in caso di inattività](/docs/it/settings-reference#idlecompaction) |
3518 3544
3519<h4 id="postcompact-input">3545<h4 id="postcompact-input">
3520 Input di PostCompact3546 Input di PostCompact
3533}3559}
3534```3560```
3535 3561
3536Gli hook PostCompact non hanno controllo decisionale. Non possono influire sul risultato della compattazione, ma possono eseguire attività successive.3562Gli hook PostCompact non hanno controllo decisionale. Non possono influenzare il risultato della compattazione ma possono eseguire attività successive.
3537 3563
3538<h3 id="premodelswitch">3564<h3 id="premodelswitch">
3539 PreModelSwitch3565 PreModelSwitch
3544PreModelSwitch richiede Claude Code v2.1.251 o successiva. Claude Code lo esegue per queste richieste:3570PreModelSwitch richiede Claude Code v2.1.251 o successiva. Claude Code lo esegue per queste richieste:
3545 3571
3546* `/model <name>` e il selettore di `/model`3572* `/model <name>` e il selettore di `/model`
3547* Il selettore di modello `Option+P` o `Alt+P`3573* Il selettore di modelli `Option+P` o `Alt+P`
3548* L'impostazione Model in `/config`3574* L'impostazione Model in `/config`
3549* L'attivazione della [modalità veloce](/docs/it/fast-mode) quando questa cambia il modello della sessione3575* L'attivazione della [modalità veloce](/docs/it/fast-mode) quando questa cambia il modello della sessione
3550* Una richiesta `set_model`, o un cambio di modello in una richiesta `apply_flag_settings`, da un host dell'[Agent SDK](/docs/it/agent-sdk/typescript#query-object) o da [Remote Control](/docs/it/remote-control)3576* Una richiesta `set_model`, o un cambio di modello in una richiesta `apply_flag_settings`, da un host dell'[Agent SDK](/docs/it/agent-sdk/typescript#query-object) o da [Remote Control](/docs/it/remote-control)
3551 3577
3552Claude Code non esegue gli hook PreModelSwitch per i cambi che effettua autonomamente, come un [fallback automatico del modello](/docs/it/model-config#automatic-model-fallback) o il ripristino del modello quando riprendi una sessione. Queste modifiche raggiungono solo [PostModelSwitch](#postmodelswitch).3578Claude Code non esegue gli hook PreModelSwitch per i cambi che effettua autonomamente, come un [fallback automatico del modello](/docs/it/model-config#automatic-model-fallback) o il ripristino del modello quando riprendi una sessione. Queste modifiche raggiungono solo [PostModelSwitch](#postmodelswitch).
3553 3579
3554Claude Code confronta il matcher con il nome canonico del modello a cui la sessione sta passando, ignorando un eventuale suffisso `[1m]`. Un alias come `opus`, un ID di modello con data e un ID specifico del provider come un ID di modello Amazon Bedrock corrispondono tutti all'unico nome canonico in cui si risolvono, quindi `claude-opus-5` copre ogni grafia di Opus 5.3580Claude Code confronta il matcher con il nome canonico del modello a cui la sessione sta passando, ignorando qualsiasi suffisso `[1m]`. Un alias come `opus`, un ID di modello con data e un ID specifico del provider come un ID di modello Amazon Bedrock corrispondono tutti all'unico nome canonico a cui si risolvono, quindi `claude-opus-5` copre ogni variante di scrittura di Opus 5.
3555 3581
3556Quando Claude Code non riesce a determinare un nome canonico per la destinazione, ad esempio un ID di modello personalizzato noto solo al tuo [gateway LLM](/docs/it/llm-gateway), esegue ogni hook PreModelSwitch indipendentemente dal matcher. Un hook che blocca dovrebbe quindi controllare `to_model` dal proprio input anziché affidarsi solo al matcher.3582Quando Claude Code non riesce a determinare un nome canonico per il modello di destinazione, ad esempio un ID di modello personalizzato che solo il tuo [gateway LLM](/docs/it/llm-gateway) conosce, esegue ogni hook PreModelSwitch indipendentemente dal matcher. Un hook che blocca dovrebbe quindi controllare `to_model` dal suo input invece di affidarsi solo al matcher.
3557 3583
3558Scrivi il matcher come nome esatto, come elenco separato da `|` come `claude-opus-4-6|claude-opus-5`, o come espressione regolare come `.*opus.*`. Questo esempio usa un matcher con nome esatto e controlla anche `to_model` dall'input dell'hook, quindi rifiuta un cambio a Opus 4.6 uscendo con codice 2 e lascia passare qualsiasi altra destinazione:3584Scrivi il matcher come nome esatto, come elenco separato da `|` come `claude-opus-4-6|claude-opus-5`, o come espressione regolare come `.*opus.*`. Questo esempio usa un matcher con nome esatto e controlla anche `to_model` dall'input dell'hook, quindi rifiuta un passaggio a Opus 4.6 uscendo con codice 2 e lascia passare qualsiasi altra destinazione:
3559 3585
3560<Tabs>3586<Tabs>
3561 <Tab title="macOS/Linux">3587 <Tab title="macOS/Linux">
3581 </Tab>3607 </Tab>
3582 3608
3583 <Tab title="Windows (PowerShell)">3609 <Tab title="Windows (PowerShell)">
3584 Registra un hook di comando che esegue uno script tramite PowerShell:3610 Registra un hook di tipo command che esegue uno script tramite PowerShell:
3585 3611
3586 ```json theme={null}3612 ```json theme={null}
3587 {3613 {
3627 Input di PreModelSwitch3653 Input di PreModelSwitch
3628</h4>3654</h4>
3629 3655
3630Oltre ai [campi di input comuni](#common-input-fields), gli hook PreModelSwitch ricevono i campi in questa tabella. Gli ultimi cinque descrivono quanto costa reinviare la conversazione al nuovo modello, così un hook può mostrare quella cifra prima che il cambio avvenga.3656Oltre ai [campi di input comuni](#common-input-fields), gli hook PreModelSwitch ricevono i campi di questa tabella. Gli ultimi cinque descrivono quanto costa reinviare la conversazione al nuovo modello, così un hook può mostrare quella cifra prima che il cambio avvenga.
3631 3657
3632| Campo | Tipo | Descrizione |3658| Campo | Tipo | Descrizione |
3633| :- | :- | :- |3659| :- | :- | :- |
3634| `from_model` | string | ID del modello da cui parte il cambio |3660| `from_model` | string | ID del modello da cui parte il cambio |
3635| `to_model` | string | ID del modello a cui porta il cambio. Il matcher viene confrontato con il nome canonico di questo modello |3661| `to_model` | string | ID del modello verso cui avviene il cambio. Il matcher si confronta con il nome canonico di questo modello |
3636| `requested_model` | string o `null` | Il modello indicato dalla richiesta: un alias come `opus`, un ID di modello completo, oppure `null` quando la richiesta era per il modello predefinito |3662| `requested_model` | string o `null` | Il modello indicato dalla richiesta: un alias come `opus`, un ID di modello completo, oppure `null` quando la richiesta era per il modello predefinito |
3637| `source` | string | Da dove proviene la richiesta: `"command"` per `/model <name>`, l'impostazione Model in `/config` o l'attivazione della modalità veloce; `"picker"` per un selettore di modello; `"sdk"` per una richiesta `set_model`, o un cambio di modello in una richiesta `apply_flag_settings`, da un host dell'Agent SDK o da Remote Control |3663| `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 modelli; `"sdk"` per una richiesta `set_model`, o un cambio di modello in una richiesta `apply_flag_settings`, da un host dell'Agent SDK o da Remote Control |
3638| `context_tokens` | number | Token che la richiesta successiva reinvia come prompt: i token di input, lettura dalla cache, creazione della cache e output dell'ultima risposta nella conversazione principale, combinati. `0` prima della prima risposta |3664| `context_tokens` | number | Token che la richiesta successiva reinvia come prompt: i token di input, di lettura dalla cache, di creazione della cache e di output dell'ultima risposta nella conversazione principale, sommati. `0` prima della prima risposta |
3639| `prompt_cache_warm` | boolean | Indica se la cache del prompt del modello corrente è probabilmente ancora calda, il che significa che il cambio la perde |3665| `prompt_cache_warm` | boolean | Se la cache del prompt del modello corrente è probabilmente ancora calda, il che significa che il cambio la fa perdere |
3640| `cache_ttl` | string | [Durata della cache del prompt](/docs/it/prompt-caching#cache-lifetime) che Claude Code richiede per questa sessione: `"5m"` o `"1h"` |3666| `cache_ttl` | string | [Durata della cache del prompt](/docs/it/prompt-caching#cache-lifetime) che Claude Code richiede per questa sessione: `"5m"` o `"1h"` |
3641| `estimated_cache_write_usd` | number | Costo stimato in dollari USA della scrittura di `context_tokens` nella cache del prompt su `to_model` alla tariffa di `cache_ttl`, esclusa la risposta successiva. Il server potrebbe non dover rimemorizzare nella cache l'intero contesto, quindi consideralo una stima |3667| `estimated_cache_write_usd` | number | Costo stimato in dollari USA della scrittura di `context_tokens` nella cache del prompt su `to_model` alla tariffa di `cache_ttl`, esclusa la risposta successiva. Il server potrebbe non dover rimemorizzare nella cache l'intero contesto, quindi consideralo una stima |
3642| `pricing` | string | Come Claude Code ha calcolato il prezzo di `estimated_cache_write_usd`: `"configured"` alle tariffe della tua organizzazione quando le ha configurate, `"catalog"` al prezzo di listino, oppure `"default"` quando `to_model` non ha un prezzo noto e Claude Code ha ipotizzato una tariffa predefinita |3668| `pricing` | string | Come Claude Code ha calcolato il prezzo di `estimated_cache_write_usd`: `"configured"` alle tariffe della tua organizzazione quando le ha configurate, `"catalog"` al prezzo di listino, oppure `"default"` quando `to_model` non ha un prezzo noto e Claude Code ha assunto una tariffa predefinita |
3643 3669
3644Questo esempio mostra l'input per `/model opus` in una sessione che usa Sonnet 5:3670Questo esempio mostra l'input per `/model opus` in una sessione che usa Sonnet 5:
3645 3671
3667 3693
3668Gli hook `PreModelSwitch` possono annullare il cambio, chiedere all'utente di confermarlo o lasciarlo procedere. Il codice di uscita 2 o un `decision: "block"` di primo livello annulla il cambio.3694Gli hook `PreModelSwitch` possono annullare il cambio, chiedere all'utente di confermarlo o lasciarlo procedere. Il codice di uscita 2 o un `decision: "block"` di primo livello annulla il cambio.
3669 3695
3670Per un controllo più preciso, restituisci `permissionDecision` e `permissionDecisionReason` in un oggetto `hookSpecificOutput`, come per [PreToolUse](#pretooluse-decision-control). `PreModelSwitch` accetta `"allow"`, `"deny"` e `"ask"`. Non accetta `"defer"`, `updatedInput` né `additionalContext`. La tabella seguente descrive entrambi i campi:3696Per un controllo più preciso, restituisci `permissionDecision` e `permissionDecisionReason` in un oggetto `hookSpecificOutput`, come in [PreToolUse](#pretooluse-decision-control). `PreModelSwitch` accetta `"allow"`, `"deny"` e `"ask"`. Non accetta `"defer"`, `updatedInput` o `additionalContext`. La tabella seguente descrive entrambi i campi:
3671 3697
3672| Campo | Descrizione |3698| Campo | Descrizione |
3673| :- | :- |3699| :- | :- |
3674| `permissionDecision` | `"allow"` procede e salta la [conferma che Claude Code mostra mentre la cache del prompt è calda](/docs/it/prompt-caching#switching-models). `"deny"` annulla il cambio. `"ask"` chiede all'utente di confermarlo |3700| `permissionDecision` | `"allow"` procede e salta la [conferma che Claude Code mostra mentre la cache del prompt è calda](/docs/it/prompt-caching#switching-models). `"deny"` annulla il cambio. `"ask"` chiede all'utente di confermarlo |
3675| `permissionDecisionReason` | Per `"deny"`, viene mostrato all'utente come motivo del blocco del cambio, oppure restituito come errore per una richiesta `set_model`. Per `"ask"`, viene mostrato nella richiesta di conferma. Ignorato per `"allow"` |3701| `permissionDecisionReason` | Per `"deny"`, viene mostrato all'utente come motivo per cui il cambio è stato bloccato, oppure restituito come errore per una richiesta `set_model`. Per `"ask"`, viene mostrato nella richiesta di conferma. Ignorato per `"allow"` |
3676 3702
3677Solo `/model` in una sessione interattiva può mostrare la richiesta `"ask"`. Su ogni altra superficie, inclusa la modalità non interattiva con il flag `-p`, `/config` e le richieste `set_model`, Claude Code tratta `"ask"` come un rifiuto.3703Solo `/model` in una sessione interattiva può mostrare la richiesta di conferma di `"ask"`. Su ogni altra superficie, inclusa la modalità non interattiva con il flag `-p`, `/config` e le richieste `set_model`, Claude Code tratta `"ask"` come un rifiuto.
3678 3704
3679Questo esempio chiede all'utente di confermare e cita il numero di token da `context_tokens`:3705Questo esempio chiede all'utente di confermare e cita il numero di token da `context_tokens`:
3680 3706
3688}3714}
3689```3715```
3690 3716
3691Quando più hook PreModelSwitch restituiscono decisioni diverse, la precedenza è `deny` > `ask` > `allow`.3717Quando più hook PreModelSwitch restituiscono decisioni diverse, l'ordine di precedenza è `deny` > `ask` > `allow`.
3692 3718
3693Claude Code mostra all'utente qualsiasi `systemMessage` restituito dal tuo hook indipendentemente dalla decisione, quindi un hook che riporta i costi può restituire `{"systemMessage": "..."}` e uscire con 0.3719Claude Code mostra all'utente qualsiasi `systemMessage` restituito dal tuo hook indipendentemente dalla decisione, quindi un hook che riporta i costi può restituire `{"systemMessage": "..."}` e uscire con 0.
3694 3720
3695Un hook PreModelSwitch che non risponde prima del suo timeout blocca il cambio. Per sapere cosa fa un timeout negli altri eventi, consulta [Timeout](#timeouts). Il timeout predefinito per questo evento è di 30 secondi. `PreModelSwitch` esegue solo hook `command`, `http` e `mcp_tool`, quindi i valori predefiniti di `prompt` e `agent` non si applicano.3721Un hook PreModelSwitch che non risponde prima del suo timeout blocca il cambio. Per sapere cosa comporta un timeout negli altri eventi, consulta [Timeout](#timeouts). Il timeout predefinito per questo evento è di 30 secondi. `PreModelSwitch` esegue solo hook `command`, `http` e `mcp_tool`, quindi i valori predefiniti di `prompt` e `agent` non si applicano.
3696 3722
3697Un hook che esce con un codice diverso da 0 o 2 e non stampa alcuna decisione JSON è un errore non bloccante, come descritto in [Altri codici di uscita](#other-exit-codes).3723Un hook che esce con un codice diverso da 0 o 2 e non stampa alcuna decisione JSON è un errore non bloccante, come descritto in [Altri codici di uscita](#other-exit-codes).
3698 3724
3700 PostModelSwitch3726 PostModelSwitch
3701</h3>3727</h3>
3702 3728
3703Viene eseguito dopo che il modello della sessione è cambiato. Usalo per dare a Claude indicazioni specifiche per il modello senza modificare ogni CLAUDE.md, ad esempio un'istruzione a livello di organizzazione che si applica su determinati modelli.3729Viene eseguito dopo che il modello della sessione è cambiato. Usalo per dare a Claude indicazioni specifiche per il modello senza modificare ogni CLAUDE.md, ad esempio un'istruzione valida per tutta l'organizzazione che si applica a determinati modelli.
3704 3730
3705PostModelSwitch richiede Claude Code v2.1.251 o successiva. Non può bloccare, perché il modello è già cambiato. Claude Code esegue gli hook PostModelSwitch dopo uno qualsiasi di questi cambiamenti:3731PostModelSwitch richiede Claude Code v2.1.251 o successiva. Non può bloccare, perché il modello è già cambiato. Claude Code esegue gli hook PostModelSwitch dopo una qualsiasi di queste modifiche:
3706 3732
3707* Un cambio richiesto da te o da un client3733* Un cambio richiesto da te o da un client
3708* Un [fallback automatico del modello](/docs/it/model-config#automatic-model-fallback), che cambia il modello della sessione3734* Un [fallback automatico del modello](/docs/it/model-config#automatic-model-fallback), che cambia il modello della sessione
3709* Un'impostazione come [`opusplan`](/docs/it/model-config#opusplan-model-setting) che entra o esce dal plan mode3735* Un'impostazione come [`opusplan`](/docs/it/model-config#opusplan-model-setting) che entra o esce dal plan mode
3710* Claude Code che ripristina il modello quando riprendi una sessione3736* Il ripristino del modello da parte di Claude Code quando riprendi una sessione
3711 3737
3712Claude Code non esegue gli hook PostModelSwitch quando un modello di una [catena di modelli di fallback](/docs/it/model-config#fallback-model-chains) gestisce un turno, perché quella sostituzione dura un solo turno e lascia invariato il modello della sessione.3738Claude Code non esegue gli hook PostModelSwitch quando un modello di una [catena di modelli di fallback](/docs/it/model-config#fallback-model-chains) gestisce un turno, perché quella sostituzione dura un turno e lascia invariato il modello della sessione.
3713 3739
3714Il matcher segue le stesse regole di [PreModelSwitch](#premodelswitch): Claude Code lo confronta con il nome canonico del modello a cui la sessione è passata.3740Il matcher segue le stesse regole di [PreModelSwitch](#premodelswitch): Claude Code lo confronta con il nome canonico del modello a cui la sessione è passata.
3715 3741
3733}3759}
3734```3760```
3735 3761
3736Per verificare che l'hook funzioni, passa a un modello Opus da una sessione che usa un modello diverso, ad esempio esegui `/model opus` da una sessione Sonnet, quindi chiedi a Claude quali indicazioni ha sul modello corrente.3762Per verificare che l'hook funzioni, passa a un modello Opus da una sessione che usa un modello diverso, ad esempio esegui `/model opus` da una sessione Sonnet, poi chiedi a Claude quali indicazioni ha riguardo al modello corrente.
3737 3763
3738<h4 id="postmodelswitch-input">3764<h4 id="postmodelswitch-input">
3739 Input di PostModelSwitch3765 Input di PostModelSwitch
3740</h4>3766</h4>
3741 3767
3742Gli hook PostModelSwitch ricevono gli stessi campi di [PreModelSwitch](#premodelswitch-input), con `hook_event_name` impostato su `"PostModelSwitch"` e due ulteriori valori di `source`: `"auto"` per un fallback automatico o un'altra modifica che Claude Code ha effettuato autonomamente, e `"resume"` per il modello ripristinato quando riprendi una sessione.3768Gli hook PostModelSwitch ricevono gli stessi campi di [PreModelSwitch](#premodelswitch-input), con `hook_event_name` impostato su `"PostModelSwitch"` e due valori aggiuntivi di `source`: `"auto"` per un fallback automatico o un'altra modifica effettuata autonomamente da Claude Code, e `"resume"` per il modello ripristinato quando riprendi una sessione.
3743 3769
3744`requested_model` è `null` quando `source` è `"auto"`. Quando `source` è `"resume"`, è l'impostazione del modello salvata che Claude Code ha ripristinato.3770`requested_model` è `null` quando `source` è `"auto"`. Quando `source` è `"resume"`, è l'impostazione del modello salvata che Claude Code ha ripristinato.
3745 3771
3760</h3>3786</h3>
3761 3787
3762Viene eseguito quando una sessione di Claude Code termina. Utile per attività di pulizia, per registrare le statistiche3788Viene eseguito quando una sessione di Claude Code termina. Utile per attività di pulizia, per registrare le statistiche
3763della sessione o salvare lo stato della sessione. Supporta i matcher per filtrare in base al motivo di uscita.3789della sessione o per salvare lo stato della sessione. Supporta i matcher per filtrare in base al motivo dell'uscita.
3764 3790
3765Il campo `reason` nell'input dell'hook indica perché la sessione è terminata:3791Il campo `reason` nell'input dell'hook indica perché la sessione è terminata:
3766 3792
3771| `logout` | L'utente è uscito dall'account |3797| `logout` | L'utente è uscito dall'account |
3772| `prompt_input_exit` | L'utente è uscito mentre l'input del prompt era visibile |3798| `prompt_input_exit` | L'utente è uscito mentre l'input del prompt era visibile |
3773| `other` | Altri motivi di uscita |3799| `other` | Altri motivi di uscita |
3774| `bypass_permissions_disabled` | Rimosso nella v2.1.234; Claude Code non lo invia. Rimuovilo dai tuoi matcher `SessionEnd` |3800| `bypass_permissions_disabled` | Rimosso nella v2.1.234; Claude Code non lo invia. Eliminalo dai tuoi matcher `SessionEnd` |
3775 3801
3776<h4 id="sessionend-input">3802<h4 id="sessionend-input">
3777 Input di SessionEnd3803 Input di SessionEnd
3789}3815}
3790```3816```
3791 3817
3792Gli hook SessionEnd non hanno controllo decisionale. Non possono bloccare la terminazione della sessione, ma possono eseguire attività di pulizia. Claude Code scarta i loro [campi di output JSON](#json-output), come `systemMessage`.3818Gli hook SessionEnd non hanno controllo decisionale. Non possono bloccare la chiusura della sessione ma possono eseguire attività di pulizia. Claude Code scarta i loro [campi di output JSON](#json-output), come `systemMessage`.
3793 3819
3794Gli hook SessionEnd hanno un timeout predefinito di 1,5 secondi. Si applica quando esci, esegui `/clear` o cambi sessione con `/resume` interattivo. Puoi concedere più tempo a un hook in due modi:3820Gli hook SessionEnd hanno un timeout predefinito di 1,5 secondi. Si applica quando esci, esegui `/clear` o cambi sessione con `/resume` interattivo. Puoi concedere più tempo a un hook in due modi:
3795 3821
3796* **`timeout` per hook**: imposta `timeout` nella configurazione di quell'hook. Il budget complessivo aumenta automaticamente fino al `timeout` per hook più alto nei tuoi file di impostazioni, fino a 60 secondi. Se aumenti il budget in questo modo, un hook senza un proprio `timeout` mantiene comunque il valore predefinito. I timeout impostati sugli hook forniti dai plugin non aumentano il budget.3822* **`timeout` per singolo hook**: imposta `timeout` nella configurazione di quell'hook. Il budget complessivo aumenta automaticamente per corrispondere al `timeout` per singolo hook più alto nei tuoi file di impostazioni, fino a 60 secondi. Se aumenti il budget in questo modo, un hook senza un proprio `timeout` mantiene comunque il valore predefinito. I timeout impostati sugli hook forniti dai plugin non aumentano il budget.
3797* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: imposta questa variabile d'ambiente in millisecondi per sovrascrivere esplicitamente il budget. Il valore impostato diventa anche il timeout per ogni hook senza un proprio `timeout`.3823* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: imposta questa variabile d'ambiente in millisecondi per sovrascrivere esplicitamente il budget. Il valore che imposti diventa anche il timeout per ogni hook senza un proprio `timeout`.
3798 3824
3799Questo esempio imposta il budget a 5 secondi:3825Questo esempio imposta il budget a 5 secondi:
3800 3826
3808 Elicitation3834 Elicitation
3809</h3>3835</h3>
3810 3836
3811Viene eseguito quando un server MCP richiede l'input dell'utente durante un'attività. Per impostazione predefinita, Claude Code mostra una finestra di dialogo interattiva a cui l'utente risponde. Gli hook possono intercettare questa richiesta e rispondere in modo programmatico, saltando completamente la finestra di dialogo.3837Viene eseguito quando un server MCP richiede un input all'utente durante un'attività. Per impostazione predefinita, Claude Code mostra una finestra di dialogo interattiva a cui l'utente risponde. Gli hook possono intercettare questa richiesta e rispondere in modo programmatico, saltando del tutto la finestra di dialogo.
3812 3838
3813Per un hook completo con la relativa voce di impostazioni e lo script, consulta [Rispondere a una richiesta di modulo da uno script](#answer-a-form-request-from-a-script).3839Per un hook completo con la relativa voce delle impostazioni e lo script, consulta [Rispondere a una richiesta di modulo da uno script](#answer-a-form-request-from-a-script).
3814 3840
3815Il campo matcher viene confrontato con il nome del server MCP.3841Il campo matcher viene confrontato con il nome del server MCP.
3816 3842
3818 Input di Elicitation3844 Input di Elicitation
3819</h4>3845</h4>
3820 3846
3821Oltre ai [campi di input comuni](#common-input-fields), gli hook Elicitation ricevono `mcp_server_name`, `message` e i campi opzionali `mode`, `url`, `elicitation_id` e `requested_schema`.3847Oltre 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`.
3822 3848
3823Per l'elicitation in modalità modulo, il caso più comune:3849Per l'elicitation in modalità form, il caso più comune:
3824 3850
3825```json theme={null}3851```json theme={null}
3826{3852{
3840}3866}
3841```3867```
3842 3868
3843Per l'elicitation in modalità URL, usata per l'autenticazione basata su browser:3869Per l'elicitation in modalità URL, usata per l'autenticazione tramite browser:
3844 3870
3845```json theme={null}3871```json theme={null}
3846{3872{
3859 Output di Elicitation3885 Output di Elicitation
3860</h4>3886</h4>
3861 3887
3862Un hook Elicitation può rispondere alla richiesta al posto dell'utente, rifiutarla o annullarla, oppure lasciarla alla finestra di dialogo. Per rispondere, rifiutare o annullare, esci con 0 e stampa un oggetto `hookSpecificOutput` con un `action`. Il server riceve la tua risposta e non compare alcuna finestra di dialogo. Ogni riga di questa tabella mostra cosa restituire per un esito e cosa riceve il server MCP:3888Un hook Elicitation può rispondere alla richiesta al posto dell'utente, rifiutarla o annullarla, oppure lasciarla alla finestra di dialogo. Per rispondere, rifiutare o annullare, esci con 0 e stampa un oggetto `hookSpecificOutput` con un `action`. Il server riceve la tua risposta e non appare alcuna finestra di dialogo. Ogni riga di questa tabella mostra cosa restituire per un determinato esito e cosa riceve il server MCP:
3863 3889
3864| Per | Restituisci | Il server riceve |3890| Per | Restituisci | Il server riceve |
3865| :- | :- | :- |3891| :- | :- | :- |
3868| Annullare la richiesta | `"action": "cancel"` | `cancel` |3894| Annullare la richiesta | `"action": "cancel"` | `cancel` |
3869| Lasciare la richiesta all'utente | Nessun output, con codice di uscita 0 | La risposta dell'utente dalla [finestra di dialogo](/docs/it/mcp#respond-to-mcp-elicitation-requests) |3895| Lasciare la richiesta all'utente | Nessun output, con codice di uscita 0 | La risposta dell'utente dalla [finestra di dialogo](/docs/it/mcp#respond-to-mcp-elicitation-requests) |
3870 3896
3871Questo output risponde alla richiesta in modalità modulo mostrata in [Input di Elicitation](#elicitation-input). Le chiavi in `content` sono i nomi delle proprietà dal `requested_schema` di quella richiesta:3897Questo output risponde alla richiesta in modalità form mostrata in [Input di Elicitation](#elicitation-input). Le chiavi in `content` sono i nomi delle proprietà dal `requested_schema` di quella richiesta:
3872 3898
3873```json theme={null}3899```json theme={null}
3874{3900{
3897 3923
3898Per una richiesta in modalità URL, un hook che restituisce `accept` salta la finestra di dialogo, quindi l'URL non viene mai aperto.3924Per una richiesta in modalità URL, un hook che restituisce `accept` salta la finestra di dialogo, quindi l'URL non viene mai aperto.
3899 3925
3900Claude Code scarta `reason`, `systemMessage` e `continue` dall'output JSON di un hook Elicitation, qualunque `action` tu restituisca.3926Claude Code scarta `reason`, `systemMessage` e `continue` dall'output JSON di un hook Elicitation, qualunque sia l'`action` che restituisci.
3901 3927
3902<h4 id="other-ways-to-decline-an-elicitation">3928<h4 id="other-ways-to-decline-an-elicitation">
3903 Altri modi per rifiutare un'elicitation3929 Altri modi per rifiutare un'elicitation
3921 3947
3922Né l'utente né il server vedono perché il tuo hook ha rifiutato, perché Claude Code non mostra il tuo stderr né il tuo `reason`.3948Né l'utente né il server vedono perché il tuo hook ha rifiutato, perché Claude Code non mostra il tuo stderr né il tuo `reason`.
3923 3949
3924Claude Code ignorava un `decision` di primo livello dagli hook `Elicitation` ed `ElicitationResult` dalla v2.1.105 fino alla correzione nella v2.1.284.3950Claude Code ha ignorato un `decision` di primo livello dagli hook `Elicitation` ed `ElicitationResult` dalla v2.1.105 fino alla correzione nella v2.1.284.
3925 3951
3926<h4 id="answer-a-form-request-from-a-script">3952<h4 id="answer-a-form-request-from-a-script">
3927 Rispondere a una richiesta di modulo da uno script3953 Rispondere a una richiesta di modulo da uno script
3928</h4>3954</h4>
3929 3955
3930Questo esempio risponde a una domanda ricorrente al posto dell'utente. Un server MCP chiamato `issue-tracker` chiede una chiave di progetto in un modulo, e l'hook inserisce `DOCS`. Lo script accetta quando `project_key` è l'unico campo del modulo. Per qualsiasi altra richiesta non stampa nulla, quindi compare la finestra di dialogo.3956Questo esempio risponde a una domanda ricorrente al posto dell'utente. Un server MCP chiamato `issue-tracker` chiede una chiave di progetto in un modulo, e l'hook inserisce `DOCS`. Lo script accetta quando `project_key` è l'unico campo del modulo. Per qualsiasi altra richiesta non stampa nulla, quindi appare la finestra di dialogo.
3931 3957
3932<Tabs>3958<Tabs>
3933 <Tab title="macOS/Linux">3959 <Tab title="macOS/Linux">
3934 Registra un hook di comando per l'evento nel tuo file di impostazioni, con il nome del server come matcher:3960 Registra un hook di tipo command per l'evento nel tuo file di impostazioni, con il nome del server come matcher:
3935 3961
3936 ```json theme={null}3962 ```json theme={null}
3937 {3963 {
3966 </Tab>3992 </Tab>
3967 3993
3968 <Tab title="Windows (PowerShell)">3994 <Tab title="Windows (PowerShell)">
3969 Registra un hook di comando che esegue lo script tramite PowerShell, con il nome del server come matcher:3995 Registra un hook di tipo command che esegue lo script tramite PowerShell, con il nome del server come matcher:
3970 3996
3971 ```json theme={null}3997 ```json theme={null}
3972 {3998 {
4012 </Tab>4038 </Tab>
4013</Tabs>4039</Tabs>
4014 4040
4015Per verificare che l'hook funzioni, avvia Claude Code con `claude --debug` e assegna a Claude un'attività che porti il server a chiedere la chiave di progetto. Non compare alcuna finestra di dialogo, e il [log di debug](#debug-hooks) contiene una riga che termina con `Elicitation resolved by hook: {"action":"accept","content":{"project_key":"DOCS"}}`.4041Per verificare che l'hook funzioni, avvia Claude Code con `claude --debug` e dai a Claude un'attività che porti il server a chiedere la chiave di progetto. Non appare alcuna finestra di dialogo, e il [log di debug](#debug-hooks) contiene una riga che termina con `Elicitation resolved by hook: {"action":"accept","content":{"project_key":"DOCS"}}`.
4016 4042
4017<h3 id="elicitationresult">4043<h3 id="elicitationresult">
4018 ElicitationResult4044 ElicitationResult
4028 Input di ElicitationResult4054 Input di ElicitationResult
4029</h4>4055</h4>
4030 4056
4031Oltre ai [campi di input comuni](#common-input-fields), gli hook ElicitationResult ricevono `mcp_server_name`, `action` e i campi opzionali `mode`, `elicitation_id` e `content`.4057Oltre 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`.
4032 4058
4033```json theme={null}4059```json theme={null}
4034{4060{
4047 Output di ElicitationResult4073 Output di ElicitationResult
4048</h4>4074</h4>
4049 4075
4050Un hook ElicitationResult può lasciar passare la risposta dell'utente, modificarne i valori o bloccarla. Per modificare o bloccare la risposta, esci con 0 e stampa un oggetto `hookSpecificOutput` con un `action`. Ogni riga di questa tabella mostra cosa restituire per un esito e cosa riceve il server MCP:4076Un hook ElicitationResult può lasciar passare la risposta dell'utente, modificarne i valori o bloccarla. Per modificare o bloccare la risposta, esci con 0 e stampa un oggetto `hookSpecificOutput` con un `action`. Ogni riga di questa tabella mostra cosa restituire per un determinato esito e cosa riceve il server MCP:
4051 4077
4052| Per | Restituisci | Il server riceve |4078| Per | Restituisci | Il server riceve |
4053| :- | :- | :- |4079| :- | :- | :- |
4054| Lasciar passare la risposta | Nessun output, con codice di uscita 0 | La risposta dell'utente, invariata |4080| Lasciar passare la risposta | Nessun output, con codice di uscita 0 | La risposta dell'utente, invariata |
4055| Modificare i valori inviati | `"action": "accept"`, con i nuovi valori in `content` | `accept` con il tuo `content` al posto dei valori dell'utente |4081| Modificare i valori inviati | `"action": "accept"`, con i nuovi valori in `content` | `accept` con il tuo `content` al posto dei valori dell'utente |
4056| Bloccare la risposta | `"action": "decline"` | `decline`, senza i valori dell'utente |4082| Bloccare la risposta | `"action": "decline"` | `decline`, senza i valori dell'utente |
4057| Annullare la richiesta | `"action": "cancel"` | `cancel`, insieme ai valori inviati dall'utente. Per non inviarli, restituisci `"decline"` |4083| Annullare la richiesta | `"action": "cancel"` | `cancel`, insieme ai valori inviati dall'utente. Per non trasmetterli, restituisci `"decline"` |
4058 4084
4059Questo output modifica la risposta mostrata in [Input di ElicitationResult](#elicitationresult-input), così il server riceve `alice@example.com` dove l'utente ha inviato `alice`:4085Questo output modifica la risposta mostrata in [Input di ElicitationResult](#elicitationresult-input), così il server riceve `alice@example.com` dove l'utente ha inviato `alice`:
4060 4086
4070}4096}
4071```4097```
4072 4098
4073Il tuo `content` sostituisce l'intero oggetto `content` dell'utente, quindi includi i campi che non stai modificando. Restituisci `action` insieme a esso, perché Claude Code ignora un `hookSpecificOutput` che non ha `action`.4099Il tuo `content` sostituisce l'intero oggetto `content` dell'utente, quindi includi i campi che non stai modificando. Restituisci anche `action`, perché Claude Code ignora un `hookSpecificOutput` privo di `action`.
4074 4100
4075Gli hook ElicitationResult vengono eseguiti anche quando l'utente rifiuta o annulla, e il tuo `action` sostituisce il suo. Verifica che l'`action` dell'input sia `accept` prima di restituire `accept`, altrimenti il tuo hook trasforma una richiesta rifiutata in una accettata. Questo script apporta la stessa modifica quando l'utente ha accettato, mantiene gli altri campi e altrimenti non stampa nulla:4101Gli hook ElicitationResult vengono eseguiti anche quando l'utente rifiuta o annulla, e il tuo `action` sostituisce il suo. Verifica che l'`action` dell'input sia `accept` prima di restituire `accept`, altrimenti il tuo hook trasforma una richiesta rifiutata in una accettata. Questo script applica la stessa modifica quando l'utente ha accettato, mantiene gli altri campi e non stampa nulla negli altri casi:
4076 4102
4077```bash theme={null}4103```bash theme={null}
4078#!/bin/bash4104#!/bin/bash
4096 4122
4097Anche il codice di uscita 2 e un `"decision": "block"` di primo livello bloccano la risposta. [Altri modi per rifiutare un'elicitation](#other-ways-to-decline-an-elicitation) spiega quale ha effetto quando un hook li combina, cosa vede l'utente e quali versioni ignoravano `decision`.4123Anche il codice di uscita 2 e un `"decision": "block"` di primo livello bloccano la risposta. [Altri modi per rifiutare un'elicitation](#other-ways-to-decline-an-elicitation) spiega quale ha effetto quando un hook li combina, cosa vede l'utente e quali versioni ignoravano `decision`.
4098 4124
4099Claude Code scarta `reason`, `systemMessage` e `continue` dall'output JSON di un hook ElicitationResult, qualunque `action` tu restituisca.4125Claude Code scarta `reason`, `systemMessage` e `continue` dall'output JSON di un hook ElicitationResult, qualunque sia l'`action` che restituisci.
4100 4126
4101<h2 id="prompt-based-hooks">4127<h2 id="prompt-based-hooks">
4102 Hook basati su prompt4128 Hook basati su prompt
4351* **Da sola su stdout**: quando la risposta è l'unico testo su stdout, può estendersi su più righe, come l'output formattato di `jq`. L'estensione su più righe richiede Claude Code v2.1.295 o versioni successive.4377* **Da sola su stdout**: quando la risposta è l'unico testo su stdout, può estendersi su più righe, come l'output formattato di `jq`. L'estensione su più righe richiede Claude Code v2.1.295 o versioni successive.
4352* **Su una riga a sé stante**: un hook asincrono può stampare altro testo su stdout quando la risposta sta da sola su una riga, ad esempio con `jq -c`.4378* **Su una riga a sé stante**: un hook asincrono può stampare altro testo su stdout quando la risposta sta da sola su una riga, ad esempio con `jq -c`.
4353 4379
4354Claude Code convalida quella risposta JSON rispetto allo stesso [schema di output](#json-output) degli hook sincroni e scarta qualsiasi campo il cui valore ha il tipo errato, come un `systemMessage` che non è una stringa, invece di consegnarlo. Eseguire con `--debug` per vedere un avviso che nomina ogni campo scartato. Prima della v2.1.202, l'output JSON malformato da un hook asincrono poteva causare l'arresto della sessione e l'arresto si ripeteva ogni volta che la sessione veniva ripresa.4380Claude Code convalida quella risposta JSON rispetto allo stesso [schema di output](#json-output) degli hook sincroni e scarta qualsiasi campo il cui valore ha il tipo errato, come un `systemMessage` che non è una stringa, invece di consegnarlo. Esegui con `--debug` per vedere un avviso che nomina ogni campo scartato.
4355 4381
4356Le notifiche di completamento degli hook asincroni sono soppresse per impostazione predefinita. Per vederle, abilitare la modalità verbose con `Ctrl+O` o avviare Claude Code con `--verbose`.4382Le notifiche di completamento degli hook asincroni sono soppresse per impostazione predefinita. Per vederle, abilitare la modalità verbose con `Ctrl+O` o avviare Claude Code con `--verbose`.
4357 4383
