70 70
71> [tab] macOS/Linux71> [tab] macOS/Linux
72>72>
73> Il `matcher` si restringe alle chiamate dello strumento Bash e la condizione `if` si restringe ulteriormente ai sottocomandi Bash che corrispondono a `rm *`, quindi `block-rm.sh` viene eseguito solo quando entrambi i filtri corrispondono:73> Il `matcher` si restringe alle chiamate allo strumento Bash e ai [comandi Monitor](#match-monitor-commands), e la condizione `if` si restringe ulteriormente ai sottocomandi Bash che corrispondono a `rm *`, quindi `block-rm.sh` viene avviato solo quando entrambi i filtri corrispondono:
74>74>
75> ```json theme={null}75> ```json theme={null}
76> {76> {
108> }108> }
109> }'109> }'
110> else110> else
111> exit 0 # nessuna decisione; il flusso di autorizzazione normale si applica111> exit 0 # nessuna decisione; si applica il normale flusso dei permessi
112> fi112> fi
113> ```113> ```
114>114>
115> Questo script, come gli altri esempi Bash su questa pagina che analizzano l'input JSON, utilizza `jq`, quindi installare `jq` e assicurarsi che sia nel `PATH` prima di provarli.115> Questo script, come gli altri esempi Bash su questa pagina che analizzano l'input JSON, utilizza `jq`, quindi installa `jq` e assicurati che sia nel tuo `PATH` prima di provarli.
116 116
117> [tab] Windows (PowerShell)117> [tab] Windows (PowerShell)
118>118>
119> Il matcher `Bash|PowerShell` copre lo [strumento PowerShell](#powershell) così come Bash. Una singola regola `if` corrisponde solo alle chiamate di uno strumento, quindi ogni strumento ottiene il suo gestore: il primo si restringe ai sottocomandi Bash che corrispondono a `rm *`, il secondo ai comandi PowerShell che corrispondono a `Remove-Item *`. Entrambi eseguono lo stesso script tramite `powershell.exe`:119> Il matcher `Bash|PowerShell` copre lo [strumento PowerShell](#powershell) così come Bash. Una singola regola `if` indica un solo strumento, quindi ogni strumento ottiene il proprio gestore: il primo si restringe ai sottocomandi Bash che corrispondono a `rm *`, il secondo ai comandi PowerShell che corrispondono a `Remove-Item *`. Entrambi eseguono lo stesso script tramite `powershell.exe`:
120>120>
121> ```json theme={null}121> ```json theme={null}
122> {122> {
174> }174> }
175> } | ConvertTo-Json175> } | ConvertTo-Json
176> } else {176> } else {
177> exit 0 # nessuna decisione; il flusso di autorizzazione normale si applica177> exit 0 # nessuna decisione; si applica il normale flusso dei permessi
178> }178> }
179> ```179> ```
180 180
225Gli hook sono definiti in file di impostazioni JSON. La configurazione ha tre livelli di annidamento:225Gli hook sono definiti in file di impostazioni JSON. La configurazione ha tre livelli di annidamento:
226 226
2271. Scegli un [evento hook](#hook-events) a cui rispondere, come `PreToolUse` o `Stop`2271. Scegli un [evento hook](#hook-events) a cui rispondere, come `PreToolUse` o `Stop`
2282. Aggiungi un [gruppo matcher](#matcher-patterns) per filtrare quando si attiva, come "solo per lo strumento Bash"2282. Aggiungi un [gruppo matcher](#matcher-patterns) per filtrare quando si attiva, ad esempio "per lo strumento Bash"
2293. Definisci uno o più [handler hook](#hook-handler-fields) da eseguire quando corrisponde2293. Definisci uno o più [handler hook](#hook-handler-fields) da eseguire quando corrisponde
230 230
231Vedi [Come si risolve un hook](#how-a-hook-resolves) sopra per una procedura dettagliata completa con un esempio annotato.231Vedi [Come si risolve un hook](#how-a-hook-resolves) sopra per una procedura dettagliata completa con un esempio annotato.
277| Valore matcher | Valutato come | Esempio |277| Valore matcher | Valutato come | Esempio |
278| :- | :- | :- |278| :- | :- | :- |
279| `"*"`, `""`, o omesso | Corrisponde a tutto | si attiva ad ogni occorrenza dell'evento |279| `"*"`, `""`, o omesso | Corrisponde a tutto | si attiva ad ogni occorrenza dell'evento |
280| Solo lettere, cifre, `_`, `-`, spazi, `,`, e `\|` | Stringa esatta, o lista di stringhe esatte separate da `\|` o `,` con spazi bianchi opzionali circostanti | `Bash` corrisponde solo allo strumento Bash; `Edit\|Write` e `Edit, Write` corrispondono ciascuno a uno dei due strumenti esattamente; `code-reviewer` corrisponde solo a quel tipo di agente |280| Solo lettere, cifre, `_`, `-`, spazi, `,`, e `\|` | Stringa esatta, o lista di stringhe esatte separate da `\|` o `,` con spazi bianchi opzionali circostanti | `Bash` corrisponde allo strumento Bash e, su `PreToolUse` e `PermissionRequest`, anche ai [comandi Monitor](#match-monitor-commands); `Edit\|Write` e `Edit, Write` corrispondono ciascuno a uno dei due strumenti esattamente; `code-reviewer` corrisponde solo a quel tipo di agente |
281| Contiene qualsiasi altro carattere | Espressione regolare JavaScript, non ancorata | `^Notebook` corrisponde a qualsiasi strumento il cui nome inizia con `Notebook`; `mcp__memory__.*` corrisponde a ogni strumento dal server `memory` |281| Contiene qualsiasi altro carattere | Espressione regolare JavaScript, non ancorata | `^Notebook` corrisponde a qualsiasi strumento il cui nome inizia con `Notebook`; `mcp__memory__.*` corrisponde a ogni strumento dal server `memory` |
282 282
283Un matcher sul percorso dell'espressione regolare viene testato con `RegExp.prototype.test` di JavaScript, che ha successo su una corrispondenza in qualsiasi punto del valore. `Edit.*` corrisponde sia a `Edit` che a `NotebookEdit`; racchiudi il pattern in `^` e `$`, come in `^Edit$`, quando hai bisogno di una corrispondenza di intera stringa.283Un matcher sul percorso dell'espressione regolare viene testato con `RegExp.prototype.test` di JavaScript, che ha successo su una corrispondenza in qualsiasi punto del valore. `Edit.*` corrisponde sia a `Edit` che a `NotebookEdit`; racchiudi il pattern in `^` e `$`, come in `^Edit$`, quando hai bisogno di una corrispondenza di intera stringa.
294| `SessionStart` | come è iniziata la sessione | `startup`, `resume`, `clear`, `compact`, `fork` |294| `SessionStart` | come è iniziata la sessione | `startup`, `resume`, `clear`, `compact`, `fork` |
295| `Setup` | quale flag CLI ha attivato il setup | `init`, `maintenance` |295| `Setup` | quale flag CLI ha attivato il setup | `init`, `maintenance` |
296| `SessionEnd` | perché è terminata la sessione | `clear`, `resume`, `logout`, `prompt_input_exit`, `other` |296| `SessionEnd` | perché è terminata la sessione | `clear`, `resume`, `logout`, `prompt_input_exit`, `other` |
297| `Notification` | tipo di notifica | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed`, `quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled`, `plugin_notification` |297| `Notification` | tipo di notifica | `permission_prompt`, `idle_prompt`, `auth_success`, `auth_storage_failure`, `elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed`, `quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled`, `plugin_notification` |
298| `SubagentStart` | tipo di agente | `general-purpose`, `Explore`, `Plan`, nomi di agenti personalizzati, o nomi con scope plugin come `^my-plugin:reviewer$` |298| `SubagentStart` | tipo di agente | `general-purpose`, `Explore`, `Plan`, nomi di agenti personalizzati, o nomi con scope plugin come `^my-plugin:reviewer$` |
299| `PreCompact`, `PostCompact` | cosa ha attivato la compattazione | `manual`, `auto` |299| `PreCompact`, `PostCompact` | cosa ha attivato la compattazione | `manual`, `auto` |
300| `PreModelSwitch`, `PostModelSwitch` | nome canonico del modello a cui la sessione passa, come descritto sotto [PreModelSwitch](#premodelswitch) | `claude-opus-5`, `claude-opus-4-6\|claude-opus-5`, `.*opus.*` |300| `PreModelSwitch`, `PostModelSwitch` | nome canonico del modello a cui la sessione passa, come descritto sotto [PreModelSwitch](#premodelswitch) | `claude-opus-5`, `claude-opus-4-6\|claude-opus-5`, `.*opus.*` |
385}385}
386```386```
387 387
388#### Corrispondere ai comandi Monitor
389
390Un hook [`PreToolUse`](#pretooluse) o [`PermissionRequest`](#permissionrequest) con un matcher `Bash` viene eseguito anche sui comandi shell che Claude avvia con lo [strumento Monitor](https://code.claude.com/docs/it/tools-reference.md#monitor-tool), ma i suoi `allow` e [`updatedInput`](#pretooluse-decision-control) non hanno effetto su di essi. Richiede Claude Code v2.1.314 o successivo. Anche matcher come `Bash|PowerShell`, `^Bash$` e `Bash.*` sono matcher `Bash`. Un hook con un matcher `Bash` non viene eseguito per un [watch WebSocket](https://code.claude.com/docs/it/tools-reference.md#websocket-source), e un hook `PostToolUse` con un tale matcher non viene eseguito per Monitor.
391
392Un hook che viene eseguito per un comando Monitor può negarlo o fare in modo che Claude Code te lo chieda. Per consentire o riscrivere il comando, passa da un matcher `Bash` a uno che include Monitor:
393
394* **Matcher che include Monitor**: con un matcher come `Bash|Monitor` o `.*`, o senza matcher, l'hook riceve l'input della chiamata Monitor stessa, e `allow` e `updatedInput` si applicano. In [`if`](#common-fields), indica Monitor, come in `Monitor(tail *)`, che corrisponde secondo [le regole seguite da `Bash(tail *)`](#bash-if-matching). Se il suo `if` indica Bash, l'hook riceve comunque l'input della chiamata Monitor, ma `allow` e `updatedInput` non hanno effetto
395* **Matcher `Bash`**: l'hook riceve una chiamata Bash. In `if`, indica Bash, come in `Bash(tail *)`. L'hook non viene eseguito se il suo `if` indica Monitor
396
388### Campi handler hook397### Campi handler hook
389 398
390Ogni oggetto nell'array `hooks` interno è un handler hook: il comando shell, endpoint HTTP, tool MCP, prompt LLM, o agente che viene eseguito quando il matcher corrisponde. Ci sono cinque tipi:399Ogni oggetto nell'array `hooks` interno è un handler hook: il comando shell, endpoint HTTP, tool MCP, prompt LLM, o agente che viene eseguito quando il matcher corrisponde. Ci sono cinque tipi:
811* **Due o più righe che si analizzano ciascuna come JSON da sole, la prima che inizia con `{` e l'ultima che finisce con `}`**: testo semplice quando nessuna riga è un oggetto JSON output che imposta un campo. Quando una lo è, l'output è un errore di analisi, quindi stampa quell'oggetto senza nient'altro su stdout.820* **Due o più righe che si analizzano ciascuna come JSON da sole, la prima che inizia con `{` e l'ultima che finisce con `}`**: testo semplice quando nessuna riga è un oggetto JSON output che imposta un campo. Quando una lo è, l'output è un errore di analisi, quindi stampa quell'oggetto senza nient'altro su stdout.
812* **Qualsiasi altra cosa che inizia con `{` e finisce con `}` ma non è JSON valido**: errore di analisi.821* **Qualsiasi altra cosa che inizia con `{` e finisce con `}` ma non è JSON valido**: errore di analisi.
813 822
814Per la maggior parte degli eventi, Claude Code scrive stdout nel log di debug e non lo mostra nella trascrizione. Le eccezioni sono `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart` e `PostModelSwitch`, dove Claude Code aggiunge lo stdout in testo semplice come contesto che Claude può vedere e su cui può agire. Su quegli eventi, Claude Code non aggiunge lo stdout che non è riuscito ad analizzare.823Per la maggior parte degli eventi, Claude Code scrive stdout nel log di debug e non lo mostra nella trascrizione. Su questi eventi, il tuo stdout raggiunge Claude o il riepilogo della compattazione:
824
825* **`UserPromptSubmit`, `UserPromptExpansion`, `SessionStart` e `PostModelSwitch`**: Claude Code aggiunge lo stdout in testo semplice come contesto che Claude può vedere e su cui può agire. Non aggiunge lo stdout che non è riuscito ad analizzare.
826* **`PreCompact`**: il tuo stdout diventa [istruzioni per il riepilogo della compattazione](#precompact-output)
815 827
816Claude non vede mai lo stderr di un hook che esce con 0. Per leggerlo tu stesso su eventi come `PreToolUse`, abilita il [debug logging](#debug-hooks). Per mostrare un avviso a Claude da un hook `PostToolUse` o `PostToolUseFailure`, esci invece con 2 in modo che [Claude veda lo stderr](#exit-code-2-behavior-per-event) anche se lo strumento è già stato eseguito.828Claude non vede mai lo stderr di un hook che esce con 0. Per leggerlo tu stesso su eventi come `PreToolUse`, abilita il [debug logging](#debug-hooks). Per mostrare un avviso a Claude da un hook `PostToolUse` o `PostToolUseFailure`, esci invece con 2 in modo che [Claude veda lo stderr](#exit-code-2-behavior-per-event) anche se lo strumento è già stato eseguito.
817 829
1050Le stringhe `additionalContext`, `systemMessage` e `initialUserMessage` di un hook, e il suo stdout semplice, sono limitate a 10.000 caratteri:1062Le stringhe `additionalContext`, `systemMessage` e `initialUserMessage` di un hook, e il suo stdout semplice, sono limitate a 10.000 caratteri:
1051 1063
1052* **Ambito**: Claude Code misura ogni stringa singolarmente, anche quando più hook vengono eseguiti per lo stesso evento. Per l'output JSON, ogni campo viene misurato separatamente; lo stdout semplice viene misurato nel complesso.1064* **Ambito**: Claude Code misura ogni stringa singolarmente, anche quando più hook vengono eseguiti per lo stesso evento. Per l'output JSON, ogni campo viene misurato separatamente; lo stdout semplice viene misurato nel complesso.
1053* **Oltre il limite**: Claude Code salva l'output in un file nella directory della sessione e lo sostituisce con il percorso del file e un'anteprima fino ai primi 2.000 caratteri. Un risultato Bash valido di grandi dimensioni viene gestito nello stesso modo, descritto in [Output limits](https://code.claude.com/docs/it/tools-reference.md#output-limits). A differenza di quel limite Bash, questo limite non ha un'impostazione o una variabile d'ambiente per aumentarlo.1065* **Oltre il limite**: tranne che per lo [stdout di PreCompact](#precompact-output), Claude Code salva l'output in un file nella directory della sessione. Sostituisce l'output con il percorso del file e un'anteprima fino ai primi 2.000 caratteri. Un risultato Bash valido di grandi dimensioni viene gestito nello stesso modo, descritto in [Output limits](https://code.claude.com/docs/it/tools-reference.md#output-limits). A differenza di quel limite Bash, questo limite non ha un'impostazione o una variabile d'ambiente per aumentarlo.
1054* **Lettura del file**: Claude Code non chiede a Claude di leggere il file, quindi mantieni entro il limite tutto ciò che Claude deve sempre vedere.1066* **Lettura del file**: Claude Code non chiede a Claude di leggere il file, quindi mantieni entro il limite tutto ciò che Claude deve sempre vedere.
1055 1067
1056L'oggetto JSON supporta tre tipi di campi:1068L'oggetto JSON supporta tre tipi di campi:
1954 1966
1955#### Controllo delle decisioni di PreToolUse1967#### Controllo delle decisioni di PreToolUse
1956 1968
1957Gli 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.1969Gli 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 (consentire, negare, chiedere conferma o differire) più la possibilità di modificare l'input dello strumento prima dell'esecuzione. Per consentire o riscrivere un comando Monitor, consulta [Confrontare i comandi Monitor](#match-monitor-commands).
1958 1970
1959| Campo | Descrizione |1971| Campo | Descrizione |
1960| :- | :- |1972| :- | :- |
2051 2063
2052#### Differire una chiamata a uno strumento2064#### Differire una chiamata a uno strumento
2053 2065
2054`"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](https://code.claude.com/docs/it/headless.md) con il flag `-p`. Nelle sessioni interattive registra un avviso e ignora il risultato dell'hook.2066`"defer"` è pensato per le integrazioni che eseguono `claude -p` come sottoprocesso e ne leggono l'output JSON, come un'app Agent SDK o un'interfaccia personalizzata costruita su Claude Code. Consente a quel processo chiamante di mettere in pausa Claude in corrispondenza di una chiamata a uno strumento, raccogliere input tramite la propria interfaccia e riprendere da dove si era interrotto.
2067
2068Claude Code rispetta `"defer"` solo in [modalità non interattiva](https://code.claude.com/docs/it/headless.md) con il flag `-p`, e solo quando Claude effettua una singola chiamata a uno strumento nel turno:
2069
2070* **Nelle sessioni interattive**: registra un avviso e ignora il risultato dell'hook
2071* **Più chiamate agli strumenti contemporaneamente**: `"defer"` viene ignorato con un avviso e lo strumento procede attraverso il normale flusso dei permessi
2055 2072
2056Lo 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](https://code.claude.com/docs/it/headless.md#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ì:2073Lo 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](https://code.claude.com/docs/it/headless.md#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ì:
2057 2074
20614. Il processo chiamante esegue `claude -p --resume <session-id>` con lo stesso host dei permessi. La stessa chiamata allo strumento attiva di nuovo `PreToolUse`.20784. Il processo chiamante esegue `claude -p --resume <session-id>` con lo stesso host dei permessi. La stessa chiamata allo strumento attiva di nuovo `PreToolUse`.
20625. L'hook restituisce `permissionDecision: "allow"` con la risposta in `updatedInput`. Lo strumento viene eseguito e Claude continua.20795. L'hook restituisce `permissionDecision: "allow"` con la risposta in `updatedInput`. Lo strumento viene eseguito e Claude continua.
2063 2080
2064Il 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:2081Il campo `deferred_tool_use` contiene `id`, `name` e `input` dello strumento:
2065 2082
2066```json theme={null}2083```json theme={null}
2067{2084{
2077}2094}
2078```2095```
2079 2096
2080Non esiste alcun timeout né limite di nuovi tentativi. La sessione rimane su disco finché non la riprendi, fatta salva la pulizia periodica prevista da [`cleanupPeriodDays`](https://code.claude.com/docs/it/settings-reference#cleanupperioddays), che per impostazione predefinita elimina i file di sessione dopo 30 giorni, secondo le [regole di pulizia periodica](https://code.claude.com/docs/it/claude-directory.md#cleaned-up-automatically).2097Non esiste un timeout né un limite di nuovi tentativi. La sessione rimane su disco finché la [pulizia periodica](https://code.claude.com/docs/it/claude-directory.md#cleaned-up-automatically) di [`cleanupPeriodDays`](https://code.claude.com/docs/it/settings-reference#cleanupperioddays) non la elimina, dopo 30 giorni per impostazione predefinita.
2081
2082Se lo strumento differito non è più disponibile quando riprendi, il primo risultato della ripresa ha `stop_reason: "tool_deferred_unavailable"` e `is_error: true`, e l'hook non si attiva. 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.
2083
2084* **Se non hai inviato alcun prompt, né con la ripresa né dopo**, la chiamata è ancora in sospeso. Riprendi di nuovo con lo strumento disponibile e verrà eseguita per prima.
2085* **Se hai inviato un prompt, con la ripresa o dopo**, Claude Code risponde senza il risultato dello strumento ed elimina la chiamata differita. Invia un nuovo prompt quando lo strumento è disponibile, se hai ancora bisogno che venga chiamato.
2086 2098
2087Se la risposta che stai aspettando non è pronta quando riprendi senza un prompt, l'hook può restituire di nuovo `"defer"`. Se hai inviato un prompt e l'hook differisce di nuovo, Claude Code tratta il prompt allo stesso modo: risponde senza il risultato dello strumento ed elimina la chiamata. Riprendi senza prompt finché l'hook non restituisce `"allow"` o `"deny"`, che è il modo in cui il processo chiamante interrompe il ciclo.2099Se la risposta non è pronta quando riprendi, l'hook può restituire di nuovo `"defer"`. Se hai inviato un prompt con quella ripresa, Claude risponde senza il risultato dello strumento e non esegue la chiamata. Riprendi senza un prompt finché l'hook non restituisce `"allow"` o `"deny"`.
2088
2089`"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.
2090 2100
2091> [!NOTE]2101> [!NOTE]
2092>2102>
2093> Per riprendere una sessione differita in plan mode, passa [`--permission-prompt-tool`](https://code.claude.com/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`](https://code.claude.com/docs/it/sessions#resume-in-plan-mode-with-p). Richiede Claude Code v2.1.246 o successivo.2103> Per riprendere una sessione differita in plan mode, passa [`--permission-prompt-tool`](https://code.claude.com/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`](https://code.claude.com/docs/it/sessions#resume-in-plan-mode-with-p). Richiede Claude Code v2.1.246 o successivo.
2094>2104>
2095> 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](https://code.claude.com/docs/it/sessions.md#permission-mode-on-resume).2105> 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 rinviata ne usava uno.
2106
2107##### Riprendere quando uno strumento rinviato non è disponibile
2108
2109Un risultato con `stop_reason: "tool_deferred_unavailable"` indica che lo strumento di una chiamata rinviata non è disponibile nella sessione ripresa, ad esempio perché il suo server MCP non è connesso. Il tuo hook `PreToolUse` non si attiva, e il campo `deferred_tool_use` del risultato indica lo strumento.
2110
2111Finché la chiamata è in sospeso, qualsiasi prompt che invii non raggiunge Claude e l'esecuzione termina con codice 1. Il campo `result` inizia con `<tool> isn't available, so its deferred call didn't run.` Esegui la chiamata, oppure scartala in modo che non venga eseguita:
2112
2113* **Per eseguire la chiamata**: rendi disponibile lo strumento e riprendi di nuovo.
2114* **Per scartare la chiamata**: riprendi con un prompt e con [`CLAUDE_CODE_DROP_UNAVAILABLE_DEFERRED_TOOL`](https://code.claude.com/docs/it/env-vars#variables) impostata su `1`. Claude riceve un errore come risultato della chiamata e risponde al tuo prompt. Quando riprendi in seguito, nessuna chiamata è in sospeso.
2115
2116Quando scarti la chiamata, l'esecuzione scrive il risultato `tool_deferred_unavailable` con un campo `result` vuoto, poi la risposta di Claude in un secondo risultato. Termina con codice 0 a meno che quella risposta non sia un errore. Se imposti la variabile e non invii alcun prompt, l'esecuzione scarta comunque la chiamata e termina con codice 1.
2117
2118Prima della v2.1.319, Claude Code rispondeva a un prompt senza il risultato dello strumento e scartava la chiamata. Su quelle versioni, invia un nuovo prompt una volta che lo strumento è disponibile.
2096 2119
2097### PermissionRequest2120### PermissionRequest
2098 2121
2148| `message` | Solo per `"deny"`: indica a Claude perché il permesso è stato negato |2171| `message` | Solo per `"deny"`: indica a Claude perché il permesso è stato negato |
2149| `interrupt` | Solo per `"deny"`: se `true`, arresta Claude |2172| `interrupt` | Solo per `"deny"`: se `true`, arresta Claude |
2150 2173
2174Per consentire o riscrivere un comando Monitor, consulta [Corrispondenza dei comandi Monitor](#match-monitor-commands).
2175
2151Un 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`.2176Un 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`.
2152 2177
2153```json theme={null}2178```json theme={null}
2205* 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).2230* 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).
2206* 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.2231* 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.
2207 2232
2233#### PostToolUse dopo un'interruzione
2234
2235Se un hook `PostToolUse` si arresta in anticipo dopo che invii un messaggio o interrompi durante una chiamata a uno strumento, verifica se hai premuto `Ctrl+Enter`, `Enter` o `Esc`:
2236
2237* **`Ctrl+Enter`**: se premerlo [termina il turno](https://code.claude.com/docs/it/interactive-mode.md#when-claude-code-sends-what-you-queued) mentre uno strumento è in esecuzione e lo strumento termina, i tuoi hook `PostToolUse` vengono eseguiti sul suo risultato e hanno 10 secondi per terminare. Il tasto agisce come `Esc` se hai messo in coda un comando `!` prima dei tuoi messaggi o se le attività in background sono disabilitate, ad esempio con [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/it/env-vars#variables).
2238* **`Enter`**: un messaggio che metti in coda con `Enter` non interrompe il turno, quindi gli hook mantengono il loro `timeout` abituale.
2239* **`Esc`**: annulli immediatamente gli hook, quindi invia il messaggio con `Enter` o `Ctrl+Enter` quando gli hook devono essere eseguiti.
2240
2241Allo scadere dei 10 secondi, Claude Code termina un hook di tipo command ancora in esecuzione, qualunque sia il suo [`timeout`](#common-fields). Per consentire a un hook di tipo command più lungo di terminare, eseguilo con [`async: true`](#run-hooks-in-the-background), il che significa che l'hook non può bloccare o riscrivere il risultato.
2242
2243Prima della v2.1.319, gli hook non si avviavano dopo che avevi interrotto il turno con un messaggio, e un hook in esecuzione veniva arrestato.
2244
2208#### Input di PostToolUse2245#### Input di PostToolUse
2209 2246
2210Gli 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).2247Gli 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).
2479| `permission_prompt` | Claude ha bisogno che tu approvi l'uso di uno strumento o la [richiesta di rete](https://code.claude.com/docs/it/sandboxing.md#network-isolation) di un comando in sandbox, e la richiesta è in attesa da circa sei secondi |2516| `permission_prompt` | Claude ha bisogno che tu approvi l'uso di uno strumento o la [richiesta di rete](https://code.claude.com/docs/it/sandboxing.md#network-isolation) di un comando in sandbox, e la richiesta è in attesa da circa sei secondi |
2480| `idle_prompt` | Claude ha finito di rispondere circa 60 secondi fa e da allora non hai digitato nulla |2517| `idle_prompt` | Claude ha finito di rispondere circa 60 secondi fa e da allora non hai digitato nulla |
2481| `auth_success` | L'autenticazione viene completata |2518| `auth_success` | L'autenticazione viene completata |
2519| `auth_storage_failure` | Il tuo accesso viene completato, ma Claude Code non riesce a salvare le nuove credenziali nel proprio [archivio delle credenziali](https://code.claude.com/docs/it/authentication.md#credential-management). Si attiva al posto di `auth_success` |
2482| `elicitation_dialog` | Un server MCP apre un modulo di elicitation e non digiti da circa sei secondi |2520| `elicitation_dialog` | Un server MCP apre un modulo di elicitation e non digiti da circa sei secondi |
2483| `elicitation_url_dialog` | Un server MCP ti chiede di aprire un URL nel browser e non digiti da circa sei secondi |2521| `elicitation_url_dialog` | Un server MCP ti chiede di aprire un URL nel browser e non digiti da circa sei secondi |
2484| `elicitation_complete` | Un server MCP segnala che un'[elicitation in modalità URL](#elicitation-input) è completata |2522| `elicitation_complete` | Un server MCP segnala che un'[elicitation in modalità URL](#elicitation-input) è completata |
2490| `quota_auto_resume_disabled` | Claude Code termina l'attesa per un limite di utilizzo di claude.ai senza proseguire il tuo task: [`autoContinueAtUsageLimit`](https://code.claude.com/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** |2528| `quota_auto_resume_disabled` | Claude Code termina l'attesa per un limite di utilizzo di claude.ai senza proseguire il tuo task: [`autoContinueAtUsageLimit`](https://code.claude.com/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** |
2491| `plugin_notification` | Un [mod](https://code.claude.com/docs/it/plugins/mods/api.md#show-something-without-starting-a-turn) genera una notifica con `$.ui.notify`. Il `title` dell'hook è il nome del mod, a meno che il mod non ne abbia impostato uno |2529| `plugin_notification` | Un [mod](https://code.claude.com/docs/it/plugins/mods/api.md#show-something-without-starting-a-turn) genera una notifica con `$.ui.notify`. Il `title` dell'hook è il nome del mod, a meno che il mod non ne abbia impostato uno |
2492 2530
2493I tipi `quota_auto_resume_fired`, `quota_auto_resume_stale` e `quota_auto_resume_disabled` richiedono Claude Code v2.1.234 o successivo.2531I tipi `quota_auto_resume_fired`, `quota_auto_resume_stale` e `quota_auto_resume_disabled` richiedono Claude Code v2.1.234 o successiva. Il tipo `auth_storage_failure` richiede v2.1.288 o successiva.
2494 2532
2495Nelle sessioni del terminale, `permission_prompt` per la richiesta di rete di un comando in sandbox richiede Claude Code v2.1.246 o successivo.2533Nelle sessioni del terminale, `permission_prompt` per la richiesta di rete di un comando in sandbox richiede Claude Code v2.1.246 o successivo.
2496 2534
3326}3364}
3327```3365```
3328 3366
3367#### Output di PreCompact
3368
3369Quando un hook PreCompact esce con 0 e non blocca, Claude Code usa il suo stdout come istruzioni per il riepilogo della compattazione. Mantieni quello stdout sotto i 10.000 caratteri per hook. Claude Code tronca l'output più lungo al limite e aggiunge un indicatore.
3370
3329### PostCompact3371### PostCompact
3330 3372
3331Viene eseguito dopo che Claude Code completa un'operazione di compattazione. Usa questo evento per reagire al nuovo stato compattato, ad esempio per registrare il riepilogo generato o aggiornare uno stato esterno. Claude Code scarta i campi `systemMessage` e `continue` di un hook PostCompact.3373Viene 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.
