105 105
106Restituisce una `Promise<`[`WarmQuery`](#warmquery)`>` che si risolve una volta che il subprocess è stato generato e ha completato il suo handshake di inizializzazione.106Restituisce una `Promise<`[`WarmQuery`](#warmquery)`>` che si risolve una volta che il subprocess è stato generato e ha completato il suo handshake di inizializzazione.
107 107
108Dei messaggi [`hook_progress`](#sdkhookprogressmessage) che un hook `SessionStart` o `Setup` emette prima del completamento dell'handshake, ricevi solo il più recente, che contiene tutto l'output dell'hook fino a quel momento. `startup()` trattiene quel messaggio, il messaggio [`hook_started`](#sdkhookstartedmessage) dell'hook e qualsiasi altra cosa il subprocess emetta prima del completamento dell'handshake. I messaggi trattenuti ti arrivano quando chiami `.query()` sul `WarmQuery` e iteri il risultato.
109
108#### Esempio110#### Esempio
109 111
110Chiama `startup()` presto, ad esempio all'avvio dell'applicazione, quindi chiama `.query()` sull'handle restituito una volta che un prompt è pronto. Questo sposta la generazione del subprocess e l'inizializzazione fuori dal percorso critico.112Chiama `startup()` presto, ad esempio all'avvio dell'applicazione, quindi chiama `.query()` sull'handle restituito una volta che un prompt è pronto. Questo sposta la generazione del subprocess e l'inizializzazione fuori dal percorso critico.
495| Proprietà | Tipo | Predefinito | Descrizione |497| Proprietà | Tipo | Predefinito | Descrizione |
496| :- | :- | :- | :- |498| :- | :- | :- | :- |
497| `abortController` | `AbortController` | `new AbortController()` | Controller per annullare le operazioni |499| `abortController` | `AbortController` | `new AbortController()` | Controller per annullare le operazioni |
498| `additionalDirectories` | `string[]` | `[]` | Directory aggiuntive a cui Claude può accedere. L'SDK passa ogni voce a Claude Code come `--add-dir`, quindi con l'origine di impostazioni `project` Claude Code [carica anche le skill, i comandi e i subagent della directory](https://code.claude.com/docs/it/permissions.md#additional-directories-grant-file-access-not-configuration) |500| `additionalDirectories` | `string[]` | `[]` | Directory aggiuntive a cui Claude può accedere. L'SDK passa ogni voce a Claude Code come `--add-dir`, quindi con l'origine delle impostazioni `project` Claude Code [carica anche le skill, i comandi e i subagent della directory](https://code.claude.com/docs/it/permissions.md#additional-directories-grant-file-access-not-configuration) |
499| `agent` | `string` | `undefined` | Nome dell'agente per il thread principale. L'agente deve essere definito nell'opzione `agents` o nelle impostazioni |501| `agent` | `string` | `undefined` | Nome dell'agente per il thread principale. L'agente deve essere definito nell'opzione `agents` o nelle impostazioni |
500| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | Definisci i subagent a livello di codice |502| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | Definisci i subagent a livello di codice |
501| `agentProgressSummaries` | `boolean` | `false` | Quando è `true`, genera riepiloghi di avanzamento di una riga per i subagent e li inoltra negli eventi [`task_progress`](#sdktaskprogressmessage) tramite il campo `summary`. Si applica ai subagent in primo piano e in background |503| `agentProgressSummaries` | `boolean` | `false` | Quando è `true`, genera riepiloghi di avanzamento di una riga per i subagent e li inoltra negli eventi [`task_progress`](#sdktaskprogressmessage) tramite il campo `summary`. Si applica ai subagent in primo piano e in background |
502| `allowDangerouslySkipPermissions` | `boolean` | `false` | Abilita l'aggiramento dei permessi. Obbligatorio quando usi `permissionMode: 'bypassPermissions'`, all'avvio o in seguito tramite `setPermissionMode()`. Consulta [plan mode](https://code.claude.com/docs/it/agent-sdk/permissions.md#plan-mode-plan) per come interagisce con `permissionMode: 'plan'` |504| `allowDangerouslySkipPermissions` | `boolean` | `false` | Abilita l'aggiramento dei permessi. Obbligatorio quando usi `permissionMode: 'bypassPermissions'`, all'avvio o in seguito tramite `setPermissionMode()`. Consulta [plan mode](https://code.claude.com/docs/it/agent-sdk/permissions.md#plan-mode-plan) per sapere come interagisce con `permissionMode: 'plan'` |
503| `allowedTools` | `string[]` | `[]` | Strumenti da approvare automaticamente senza chiedere conferma, escluse le letture da [percorsi di rete](https://code.claude.com/docs/it/permissions.md#network-paths). Questo non limita Claude ai soli strumenti indicati. Se qui indichi uno degli [strumenti di tracciamento delle attività](https://code.claude.com/docs/it/agent-sdk/todo-tracking.md#model-availability), Claude Code li abilita anche per la sessione. Gli altri strumenti non elencati passano a `permissionMode` e `canUseTool`. Usa `disallowedTools` per bloccare gli strumenti. Consulta [Permessi](https://code.claude.com/docs/it/agent-sdk/permissions.md#allow-and-deny-rules) |505| `allowedTools` | `string[]` | `[]` | Strumenti da approvare automaticamente senza chiedere, escluse le letture da [percorsi di rete](https://code.claude.com/docs/it/permissions.md#network-paths). Non limita Claude a usare solo questi strumenti. Se qui indichi uno degli [strumenti di tracciamento delle attività](https://code.claude.com/docs/it/agent-sdk/todo-tracking.md#model-availability), Claude Code li abilita anche per la sessione. Gli altri strumenti non elencati passano a `permissionMode` e `canUseTool`. Usa `disallowedTools` per bloccare gli strumenti. Consulta [Permessi](https://code.claude.com/docs/it/agent-sdk/permissions.md#allow-and-deny-rules) |
504| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | Abilita le funzionalità beta |506| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | Abilita le funzionalità beta |
505| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Funzione di permesso personalizzata, invocata solo quando il [flusso dei permessi](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated) arriva a una richiesta di permesso. Non viene invocata per le chiamate approvate automaticamente da `allowedTools`, dalle regole allow o da `permissionMode`. Una regola allow non pre-approva le [azioni che nessuna modalità approva automaticamente](https://code.claude.com/docs/it/permission-modes.md#actions-no-mode-auto-approves). Consulta [`CanUseTool`](#canusetool) per i dettagli |507| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Funzione di permesso personalizzata, invocata solo quando il [flusso dei permessi](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated) arriva a una richiesta di permesso. Non viene invocata per le chiamate approvate automaticamente da `allowedTools`, dalle regole di autorizzazione o da `permissionMode`. Una regola di autorizzazione non pre-approva le [azioni che nessuna modalità approva automaticamente](https://code.claude.com/docs/it/permission-modes.md#actions-no-mode-auto-approves). Consulta [`CanUseTool`](#canusetool) per i dettagli |
506| `continue` | `boolean` | `false` | Continua la conversazione più recente |508| `continue` | `boolean` | `false` | Continua la conversazione più recente |
507| `cwd` | `string` | `process.cwd()` | Directory di lavoro corrente |509| `cwd` | `string` | `process.cwd()` | Directory di lavoro corrente |
508| `debug` | `boolean` | `false` | Abilita la modalità di debug per il processo Claude Code |510| `debug` | `boolean` | `false` | Abilita la modalità di debug per il processo Claude Code |
510| `disallowedTools` | `string[]` | `[]` | Strumenti da negare. Un nome semplice come `"Bash"` rimuove lo strumento dal contesto di Claude. Una regola con ambito come `"Bash(rm *)"` lascia lo strumento disponibile e nega le chiamate corrispondenti in ogni modalità di permesso, incluso `bypassPermissions`, per il comando [così come è scritto](https://code.claude.com/docs/it/permissions.md#bash-rule-limits). Consulta [Permessi](https://code.claude.com/docs/it/agent-sdk/permissions.md#allow-and-deny-rules) |512| `disallowedTools` | `string[]` | `[]` | Strumenti da negare. Un nome semplice come `"Bash"` rimuove lo strumento dal contesto di Claude. Una regola con ambito come `"Bash(rm *)"` lascia lo strumento disponibile e nega le chiamate corrispondenti in ogni modalità di permesso, incluso `bypassPermissions`, per il comando [così come è scritto](https://code.claude.com/docs/it/permissions.md#bash-rule-limits). Consulta [Permessi](https://code.claude.com/docs/it/agent-sdk/permissions.md#allow-and-deny-rules) |
511| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `undefined` | Controlla quanto sforzo Claude dedica alla risposta. Funziona con il ragionamento adattivo per guidare la profondità del ragionamento. Consulta [regolare il livello di sforzo](https://code.claude.com/docs/it/model-config.md#adjust-effort-level) |513| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `undefined` | Controlla quanto sforzo Claude dedica alla risposta. Funziona con il ragionamento adattivo per guidare la profondità del ragionamento. Consulta [regolare il livello di sforzo](https://code.claude.com/docs/it/model-config.md#adjust-effort-level) |
512| `enableFileCheckpointing` | `boolean` | `false` | Abilita il tracciamento delle modifiche ai file per il riavvolgimento. Consulta [Checkpointing dei file](https://code.claude.com/docs/it/agent-sdk/file-checkpointing.md) |514| `enableFileCheckpointing` | `boolean` | `false` | Abilita il tracciamento delle modifiche ai file per il riavvolgimento. Consulta [Checkpointing dei file](https://code.claude.com/docs/it/agent-sdk/file-checkpointing.md) |
513| `env` | `Record<string, string \| undefined>` | `process.env` | Variabili d'ambiente. Quando è impostato, sostituisce l'ambiente del sottoprocesso invece di fare il merge con `process.env`, quindi passa `{ ...process.env, YOUR_VAR: 'value' }` per mantenere le variabili ereditate come `PATH`. Consulta [Gestire risposte API lente o bloccate](#handle-slow-or-stalled-api-responses) per un esempio di questo pattern, e [Variabili d'ambiente](https://code.claude.com/docs/it/env-vars.md) per le variabili lette dalla CLI sottostante. Imposta `CLAUDE_AGENT_SDK_CLIENT_APP` per identificare la tua app nell'header User-Agent |515| `env` | `Record<string, string \| undefined>` | `process.env` | Variabili d'ambiente. Quando è impostato, sostituisce l'ambiente del sottoprocesso invece di fare il merge con `process.env`, quindi passa `{ ...process.env, YOUR_VAR: 'value' }` per mantenere le variabili ereditate come `PATH`. Consulta [Gestire risposte API lente o bloccate](#handle-slow-or-stalled-api-responses) per un esempio di questo schema e [Variabili d'ambiente](https://code.claude.com/docs/it/env-vars.md) per le variabili lette dalla CLI sottostante. Imposta `CLAUDE_AGENT_SDK_CLIENT_APP` per identificare la tua app nell'header User-Agent |
514| `executable` | `'bun' \| 'deno' \| 'node'` | Rilevato automaticamente | Runtime JavaScript da usare |516| `executable` | `'bun' \| 'deno' \| 'node'` | Rilevato automaticamente | Runtime JavaScript da usare |
515| `executableArgs` | `string[]` | `[]` | Argomenti da passare all'eseguibile |517| `executableArgs` | `string[]` | `[]` | Argomenti da passare all'eseguibile |
516| `extraArgs` | `Record<string, string \| null>` | `{}` | Argomenti aggiuntivi |518| `extraArgs` | `Record<string, string \| null>` | `{}` | Argomenti aggiuntivi |
517| `fallbackModel` | `string` | `undefined` | Modello da usare se il modello principale non riesce. Accetta un elenco separato da virgole. Per l'ordine e il limite, consulta [Catene di modelli di fallback](https://code.claude.com/docs/it/model-config.md#fallback-model-chains). Per indicazioni, consulta [Scegliere un modello](https://code.claude.com/docs/it/agent-sdk/configuration.md#choose-a-model) |519| `fallbackModel` | `string` | `undefined` | Modello da usare se il modello principale non riesce. Accetta un elenco separato da virgole. Per l'ordine e il limite, consulta [Catene di modelli di fallback](https://code.claude.com/docs/it/model-config.md#fallback-model-chains). Per indicazioni, consulta [Scegliere un modello](https://code.claude.com/docs/it/agent-sdk/configuration.md#choose-a-model) |
518| `forkSession` | `boolean` | `false` | Quando riprendi con `resume`, esegue il fork verso un nuovo ID di sessione invece di continuare la sessione originale |520| `forkSession` | `boolean` | `false` | Quando riprendi con `resume`, crea un fork verso un nuovo ID di sessione invece di continuare la sessione originale |
519| `forwardSubagentText` | `boolean` | `false` | Inoltra il testo e i blocchi di ragionamento dei subagent come messaggi assistant e user con `parent_tool_use_id` impostato, così i consumer possono mostrare una trascrizione annidata. Senza questa opzione, Claude Code omette il testo e i blocchi di ragionamento di un subagent eseguito in [primo piano](https://code.claude.com/docs/it/sub-agents.md#run-subagents-in-foreground-or-background). Per i subagent annidati, le skill con `context: fork` e la versione di Claude Code richiesta da ciascuno, consulta [Seguire i messaggi dei subagent](https://code.claude.com/docs/it/headless.md#follow-subagent-messages) |521| `forwardSubagentText` | `boolean` | `false` | Inoltra il testo e i blocchi di ragionamento dei subagent come messaggi dell'assistente e dell'utente con `parent_tool_use_id` impostato, così i consumer possono visualizzare una trascrizione annidata. Senza questa opzione, Claude Code omette il testo e i blocchi di ragionamento di un subagent eseguito in [primo piano](https://code.claude.com/docs/it/sub-agents.md#run-subagents-in-foreground-or-background). Per i subagent annidati, le skill con `context: fork` e la versione di Claude Code richiesta da ciascuno, consulta [Seguire i messaggi dei subagent](https://code.claude.com/docs/it/headless.md#follow-subagent-messages) |
520| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Callback degli hook per gli eventi |522| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Callback degli hook per gli eventi |
521| `includeHookEvents` | `boolean` | `false` | Include gli eventi del ciclo di vita degli hook nel flusso dei messaggi come [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage) e [`SDKHookResponseMessage`](#sdkhookresponsemessage). Gli eventi del ciclo di vita per gli hook `SessionStart` e `Setup` sono sempre inclusi e non richiedono questa opzione. Alcuni eventi hook, come `Notification`, `SessionEnd`, `PreCompact` e `PostCompact`, non producono mai un `SDKHookStartedMessage`, nemmeno con questa opzione. Per questi eventi, Claude Code emette comunque un `SDKHookProgressMessage` mentre un hook di comando che dura più di un secondo produce output, ed emette un `SDKHookResponseMessage` solo quando termina un hook [eseguito in background](https://code.claude.com/docs/it/hooks.md#run-hooks-in-the-background) |523| `includeHookEvents` | `boolean` | `false` | Include gli eventi del ciclo di vita degli hook nel flusso dei messaggi come [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage) e [`SDKHookResponseMessage`](#sdkhookresponsemessage). Gli eventi del ciclo di vita degli hook `SessionStart` e `Setup` sono sempre inclusi e non richiedono questa opzione. Alcuni eventi degli hook, come `Notification`, `SessionEnd`, `PreCompact` e `PostCompact`, non producono mai un `SDKHookStartedMessage`, nemmeno con questa opzione. Per questi eventi, Claude Code emette comunque un `SDKHookProgressMessage` mentre un hook di comando in esecuzione da più di un secondo produce output, ed emette un `SDKHookResponseMessage` solo quando termina un hook [eseguito in background](https://code.claude.com/docs/it/hooks.md#run-hooks-in-the-background) |
522| `includePartialMessages` | `boolean` | `false` | Include gli eventi dei messaggi parziali |524| `includePartialMessages` | `boolean` | `false` | Include gli eventi dei messaggi parziali |
523| `loadTimeoutMs` | `number` | `60000` | *Alpha.* Timeout in millisecondi per ogni chiamata a `sessionStore.load()` e `sessionStore.listSubkeys()` durante la materializzazione della ripresa. Se l'adattatore non si risolve entro questo intervallo, la query fallisce invece di bloccarsi. Ignorato quando `sessionStore` non è impostato |525| `loadTimeoutMs` | `number` | `60000` | *Alpha.* Timeout in millisecondi per ogni chiamata a `sessionStore.load()` e `sessionStore.listSubkeys()` durante la materializzazione della ripresa. Se l'adattatore non si conclude entro questo intervallo, la query non riesce invece di bloccarsi. Ignorato quando `sessionStore` non è impostato |
524| `managedSettings` | `Settings` | `undefined` | Impostazioni di livello policy che il tuo processo host fornisce alla sessione avviata. Sui computer con impostazioni gestite distribuite dall'amministratore, Claude Code le ignora a meno che la fonte gestita con la massima priorità dell'amministratore non imposti `parentSettingsBehavior: 'merge'`, e non ne esegue mai il merge mentre un [`policyHelper`](https://code.claude.com/docs/it/settings-reference#policyhelper) fornisce impostazioni gestite. I valori sottoposti a merge passano attraverso un filtro solo restrittivo; [Limitare le impostazioni padre](https://code.claude.com/docs/it/claude-apps-gateway#restrict-parent-settings) descrive cosa ammette il filtro e i blocchi `allowManaged*Only`. Un host che imposta [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/it/env-vars) legge invece tre chiavi direttamente da questo payload: la sua [configurazione del modello](https://code.claude.com/docs/it/model-config.md#restrict-model-selection) su Claude Code v2.1.222 o successivo, [`modelPricing`](https://code.claude.com/docs/it/settings-reference#modelpricing) quando nessuna fonte gestita lo imposta su v2.1.246 o successivo, e la sua voce env `ENABLE_TOOL_SEARCH` su v2.1.247 o successivo |526| `managedSettings` | `Settings` | `undefined` | Impostazioni di livello policy che il tuo processo host fornisce alla sessione avviata. Sulle macchine con impostazioni gestite distribuite dall'amministratore, Claude Code le ignora a meno che l'origine gestita con la massima priorità dell'amministratore non imposti `parentSettingsBehavior: 'merge'`, e non ne esegue mai il merge mentre un [`policyHelper`](https://code.claude.com/docs/it/settings-reference#policyhelper) fornisce impostazioni gestite. I valori uniti tramite merge passano attraverso un filtro solo restrittivo; [Limitare le impostazioni del processo padre](https://code.claude.com/docs/it/claude-apps-gateway#restrict-parent-settings) descrive cosa ammette il filtro e i blocchi `allowManaged*Only`. Un host che imposta [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/it/env-vars) ha invece tre chiavi lette direttamente da questo payload: la sua [configurazione del modello](https://code.claude.com/docs/it/model-config.md#restrict-model-selection) su Claude Code v2.1.222 o successiva, [`modelPricing`](https://code.claude.com/docs/it/settings-reference#modelpricing) quando nessuna origine gestita la imposta su v2.1.246 o successiva, e la sua voce env `ENABLE_TOOL_SEARCH` su v2.1.247 o successiva |
525| `maxBudgetUsd` | `number` | `undefined` | Interrompe la query quando la stima dei costi lato client raggiunge questo valore in USD. La stima può superare questo valore, quindi [lascia un margine](https://code.claude.com/docs/it/agent-sdk/agent-loop.md#budget-headroom). Conta solo la spesa della chiamata stessa; i totali ripristinati da una sessione ripresa non vengono conteggiati. Per le avvertenze sull'accuratezza e il comportamento di reimpostazione, consulta [Monitorare costi e utilizzo](https://code.claude.com/docs/it/agent-sdk/cost-tracking.md) |527| `maxBudgetUsd` | `number` | `undefined` | Interrompe la query quando la stima dei costi lato client raggiunge questo valore in USD. La stima può superare questo valore, quindi [lascia un margine](https://code.claude.com/docs/it/agent-sdk/agent-loop.md#budget-headroom). Conta solo la spesa della chiamata stessa; i totali ripristinati da una sessione ripresa non vengono conteggiati. Per le avvertenze sulla precisione e il comportamento di azzeramento, consulta [Tracciare costi e utilizzo](https://code.claude.com/docs/it/agent-sdk/cost-tracking.md) |
526| `maxThinkingTokens` | `number` | `undefined` | *Deprecato:* usa invece `thinking`. Numero massimo di token per il processo di ragionamento |528| `maxThinkingTokens` | `number` | `undefined` | *Deprecato:* usa invece `thinking`. Numero massimo di token per il processo di ragionamento |
527| `maxTurns` | `number` | `undefined` | Numero massimo di turni agentici (round trip di uso degli strumenti) |529| `maxTurns` | `number` | `undefined` | Numero massimo di [turni](https://code.claude.com/docs/it/agent-sdk/agent-loop.md#turns-and-messages) agentici |
528| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurazioni dei server MCP |530| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurazioni dei server MCP |
529| `model` | `string` | Predefinito dalla CLI | Alias del modello Claude o nome completo del modello. Consulta [valori accettati e ID specifici del provider](https://code.claude.com/docs/it/model-config.md#available-models) |531| `model` | `string` | Predefinito dalla CLI | Alias del modello Claude o nome completo del modello. Consulta [valori accettati e ID specifici del provider](https://code.claude.com/docs/it/model-config.md#available-models) |
530| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | Callback per gestire le richieste di elicitation MCP. Viene chiamata quando un server MCP richiede input dall'utente e nessun hook la gestisce prima. Se non fornita, le richieste di elicitation non gestite vengono rifiutate automaticamente |532| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | Callback per gestire le richieste di elicitation MCP. Viene chiamata quando un server MCP richiede input all'utente e nessun hook la gestisce prima. Se non viene fornita, le richieste di elicitation non gestite vengono rifiutate automaticamente |
531| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Definisce il formato di output per i risultati dell'agente. Consulta [Output strutturati](https://code.claude.com/docs/it/agent-sdk/structured-outputs.md) per i dettagli |533| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Definisce il formato di output per i risultati dell'agente. Consulta [Output strutturati](https://code.claude.com/docs/it/agent-sdk/structured-outputs.md) per i dettagli |
532| `outputStyle` | `string` | `undefined` | Non è un campo di `Options`. Imposta invece `outputStyle` nell'oggetto [`settings`](https://code.claude.com/docs/it/settings) inline o in un file di impostazioni. Consulta [Attivare uno stile di output](https://code.claude.com/docs/it/agent-sdk/modifying-system-prompts.md#activate-an-output-style) |534| `outputStyle` | `string` | `undefined` | Non è un campo di `Options`. Imposta invece `outputStyle` nell'oggetto [`settings`](https://code.claude.com/docs/it/settings) inline o in un file di impostazioni. Consulta [Attivare uno stile di output](https://code.claude.com/docs/it/agent-sdk/modifying-system-prompts.md#activate-an-output-style) |
533| `pathToClaudeCodeExecutable` | `string` | Risolto automaticamente dal binario nativo incluso | Percorso dell'eseguibile di Claude Code. Necessario solo se le dipendenze opzionali sono state saltate durante l'installazione o se la tua piattaforma non è tra quelle supportate |535| `pathToClaudeCodeExecutable` | `string` | Risolto automaticamente dal binario nativo incluso | Percorso dell'eseguibile di Claude Code. Necessario solo se le dipendenze opzionali sono state saltate durante l'installazione o se la tua piattaforma non è tra quelle supportate |
534| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | Modalità di permesso per la sessione. Se la ometti e nient'altro imposta una modalità di permesso, come un'impostazione [`permissions.defaultMode`](https://code.claude.com/docs/it/settings-reference#permissions-defaultmode), la sessione si avvia in `default`. Consulta [Modalità di permesso](https://code.claude.com/docs/it/agent-sdk/permissions.md#permission-modes) |536| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | Modalità di permesso per la sessione. Se la ometti e nient'altro imposta una modalità di permesso, come un'impostazione [`permissions.defaultMode`](https://code.claude.com/docs/it/settings-reference#permissions-defaultmode), la sessione si avvia in `default`. Consulta [Modalità di permesso](https://code.claude.com/docs/it/agent-sdk/permissions.md#permission-modes) |
535| `permissionPromptToolName` | `string` | `undefined` | Nome dello strumento MCP per le richieste di permesso |537| `permissionPromptToolName` | `string` | `undefined` | Nome dello strumento MCP per le richieste di permesso |
536| `permissionPrompts` | `'host' \| 'none'` | `'host'` | Chi risponde alle richieste di permesso: `'host'` le instrada alla tua callback [`canUseTool`](#canusetool) o allo strumento `permissionPromptToolName`, mentre `'none'` [nega le chiamate che avrebbero richiesto conferma](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated). Richiede Claude Code v2.1.259 o successivo |538| `permissionPrompts` | `'host' \| 'none'` | `'host'` | Chi risponde alle richieste di permesso: `'host'` le instrada alla tua callback [`canUseTool`](#canusetool) o allo strumento `permissionPromptToolName`, mentre `'none'` [nega le chiamate che avrebbero generato una richiesta](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated). Richiede Claude Code v2.1.259 o successiva |
537| `persistSession` | `boolean` | `true` | Quando è `false`, disabilita la persistenza della sessione su disco. Le sessioni non possono essere riprese in seguito |539| `persistSession` | `boolean` | `true` | Quando è `false`, disabilita la persistenza della sessione su disco. Le sessioni non possono essere riprese in seguito |
538| `planModeInstructions` | `string` | `undefined` | Istruzioni di workflow personalizzate per il plan mode. Quando `permissionMode` è `'plan'`, questa stringa sostituisce il corpo predefinito del workflow del plan mode. La CLI la racchiude comunque con il preambolo di applicazione della sola lettura e il piè di pagina del protocollo ExitPlanMode |540| `planModeInstructions` | `string` | `undefined` | Istruzioni di workflow personalizzate per il plan mode. Quando `permissionMode` è `'plan'`, questa stringa sostituisce il corpo predefinito del workflow del plan mode. La CLI la racchiude comunque con il preambolo che impone la sola lettura e il footer del protocollo ExitPlanMode |
539| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Carica plugin personalizzati da percorsi locali. Consulta [Plugin](https://code.claude.com/docs/it/agent-sdk/plugins.md) per i dettagli |541| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Carica plugin personalizzati da percorsi locali. Consulta [Plugin](https://code.claude.com/docs/it/agent-sdk/plugins.md) per i dettagli |
540| `projectConfigRoot` | `string` | `undefined` | Percorso assoluto del checkout attendibile di cui `cwd` è un worktree. Claude Code legge le impostazioni di progetto, `.mcp.json` e i comandi, gli agenti, le skill, i workflow, le routine e gli stili di output in `.claude/` del progetto da questa directory invece che da `cwd`, e imposta `CLAUDE_PROJECT_DIR` su di essa. Gli hook, gli script di supporto come `apiKeyHelper` e i server MCP stdio si avviano con questa directory come directory di lavoro. I file `CLAUDE.md` e `.claude/rules/` vengono comunque caricati da `cwd`. Richiede Claude Code v2.1.275 o successivo |542| `projectConfigRoot` | `string` | `undefined` | Percorso assoluto del checkout attendibile di cui `cwd` è un worktree. Claude Code legge le impostazioni di progetto, `.mcp.json` e i comandi, gli agenti, le skill, i workflow, le routine e gli stili di output in `.claude/` del progetto da questa directory invece che da `cwd`, e imposta `CLAUDE_PROJECT_DIR` su di essa. Gli hook, gli script di supporto come `apiKeyHelper` e i server MCP stdio si avviano con questa directory come directory di lavoro. I file `CLAUDE.md` e `.claude/rules/` vengono comunque caricati da `cwd`. Richiede Claude Code v2.1.275 o successiva |
541| `promptSuggestions` | `boolean` | `false` | Abilita i suggerimenti di prompt. Dopo un turno, Claude Code emette un messaggio `prompt_suggestion` che contiene un prompt utente successivo previsto. Claude Code non genera alcun suggerimento per alcuni turni, ad esempio quando il tuo account è vicino al limite di utilizzo o lo ha raggiunto. Consulta [Quando Claude Code salta i suggerimenti](https://code.claude.com/docs/it/interactive-mode.md#when-claude-code-skips-suggestions) |543| `promptSuggestions` | `boolean` | `false` | Abilita i suggerimenti di prompt. Dopo un turno, Claude Code emette un messaggio `prompt_suggestion` contenente un prossimo prompt dell'utente previsto. Claude Code non genera suggerimenti per alcuni turni, ad esempio quando il tuo account è vicino al limite di utilizzo o lo ha raggiunto. Consulta [Quando Claude Code salta i suggerimenti](https://code.claude.com/docs/it/interactive-mode.md#when-claude-code-skips-suggestions) |
542| `resume` | `string` | `undefined` | ID della sessione da riprendere |544| `resume` | `string` | `undefined` | ID della sessione da riprendere |
543| `resumeDropsTurn` | `string` | `undefined` | Con `resumeSessionAt`: l'UUID del prompt del turno che la ripresa con troncamento intende scartare. Claude Code rifiuta la ripresa quando l'intervallo scartato contiene qualcosa non attribuibile a quel turno, come messaggi in coda assorbiti o notifiche di attività, e indica il flag `--resume-drops-turn` nel messaggio di rifiuto. Solo l'Agent SDK e le riprese in modalità print leggono la coppia. Richiede Claude Code v2.1.223 o successivo |545| `resumeDropsTurn` | `string` | `undefined` | Con `resumeSessionAt`: l'UUID del prompt del turno che la ripresa con troncamento intende scartare. Claude Code rifiuta la ripresa quando l'intervallo scartato contiene qualcosa di non attribuibile a quel turno, come messaggi in coda assorbiti o notifiche di attività, e indica il flag `--resume-drops-turn` nel messaggio di rifiuto. Solo l'Agent SDK e le riprese in modalità print leggono la coppia. Richiede Claude Code v2.1.223 o successiva |
544| `resumeSessionAt` | `string` | `undefined` | Riprende la sessione a un UUID di messaggio specifico |546| `resumeSessionAt` | `string` | `undefined` | Riprende la sessione a partire da uno specifico UUID di messaggio |
545| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | Configura il comportamento della sandbox a livello di codice. Consulta [Impostazioni della sandbox](#sandboxsettings) per i dettagli |547| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | Configura il comportamento della sandbox a livello di codice. Consulta [Impostazioni della sandbox](#sandboxsettings) per i dettagli |
546| `sessionId` | `string` | Generato automaticamente | Usa un UUID specifico per la sessione invece di generarne uno automaticamente |548| `sessionId` | `string` | Generato automaticamente | Usa un UUID specifico per la sessione invece di generarne uno automaticamente |
547| `sessionStore` | [`SessionStore`](https://code.claude.com/docs/it/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Replica le trascrizioni delle sessioni su un backend esterno così che un altro host possa riprenderle. Consulta [Rendere persistenti le sessioni in uno storage esterno](https://code.claude.com/docs/it/agent-sdk/session-storage.md) |549| `sessionStore` | [`SessionStore`](https://code.claude.com/docs/it/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Replica le trascrizioni delle sessioni su un backend esterno in modo che un altro host possa riprenderle. Consulta [Rendere persistenti le sessioni su uno storage esterno](https://code.claude.com/docs/it/agent-sdk/session-storage.md) |
548| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alpha.* Modalità di flush per `sessionStore`. Ignorato quando `sessionStore` non è impostato |550| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alpha.* Modalità di flush per `sessionStore`. Ignorato quando `sessionStore` non è impostato |
549| `settings` | `string \| Settings` | `undefined` | Oggetto di [impostazioni](https://code.claude.com/docs/it/settings.md) inline, percorso di un file di impostazioni o stringa JSON inline. Popola il livello delle impostazioni da flag nell'[ordine di precedenza](https://code.claude.com/docs/it/settings.md#settings-precedence). Modificalo in fase di esecuzione con [`applyFlagSettings()`](#applyflagsettings) |551| `settings` | `string \| Settings` | `undefined` | Oggetto di [impostazioni](https://code.claude.com/docs/it/settings.md) inline, percorso di un file di impostazioni o stringa JSON inline. Popola il livello di impostazioni dei flag nell'[ordine di precedenza](https://code.claude.com/docs/it/settings.md#settings-precedence). Modificalo in fase di esecuzione con [`applyFlagSettings()`](#applyflagsettings) |
550| `settingSources` | [`SettingSource`](#settingsource)`[]` | Predefiniti della CLI (tutte le fonti) | Controlla quali impostazioni del filesystem caricare. Passa `[]` per disabilitare le impostazioni utente, di progetto e locali. La [policy gestita dagli endpoint](https://code.claude.com/docs/it/managed-settings.md#delivery-mechanisms) viene caricata in ogni caso; le impostazioni gestite dal server vengono recuperate quando la sessione si autentica con una credenziale dell'organizzazione su una [configurazione idonea](https://code.claude.com/docs/it/server-managed-settings.md#platform-availability). Consulta [Usare le funzionalità di Claude Code](https://code.claude.com/docs/it/agent-sdk/claude-code-features.md#what-settingsources-does-not-control) |552| `settingSources` | [`SettingSource`](#settingsource)`[]` | Valori predefiniti della CLI (tutte le origini) | Controlla quali impostazioni del filesystem caricare. Passa `[]` per disabilitare le impostazioni utente, di progetto e locali. La [policy gestita sull'endpoint](https://code.claude.com/docs/it/managed-settings.md#delivery-mechanisms) viene caricata in ogni caso; le impostazioni gestite dal server vengono recuperate quando la sessione si autentica con una credenziale dell'organizzazione su una [configurazione idonea](https://code.claude.com/docs/it/server-managed-settings.md#platform-availability). Consulta [Usare le funzionalità di Claude Code](https://code.claude.com/docs/it/agent-sdk/claude-code-features.md#what-settingsources-does-not-control) |
551| `skills` | `string[] \| 'all'` | `undefined` | Skill disponibili per la sessione. Passa `'all'` per abilitare ogni skill rilevata, oppure un elenco di nomi di skill. Passa solo nomi esatti. Su Agent SDK v0.3.221 o successivo, l'SDK rifiuta i nomi non validi e in forma wildcard con un errore prima di avviare il processo Claude Code. Quando è impostato, l'SDK aggiunge automaticamente lo strumento Skill a `allowedTools`. Se passi anche `tools`, includi `'Skill'` in quell'elenco. Consulta [Skill](https://code.claude.com/docs/it/agent-sdk/skills.md) |553| `skills` | `string[] \| 'all'` | `undefined` | Skill disponibili per la sessione. Passa `'all'` per abilitare ogni skill rilevata, oppure un elenco di nomi di skill. Passa solo nomi esatti. Su Agent SDK v0.3.221 o successiva, l'SDK rifiuta con un errore i nomi non validi e quelli in forma di carattere jolly prima di avviare il processo Claude Code. Quando è impostato, l'SDK aggiunge automaticamente lo strumento Skill a `allowedTools`. Se passi anche `tools`, includi `'Skill'` in quell'elenco. Consulta [Skill](https://code.claude.com/docs/it/agent-sdk/skills.md) |
552| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Funzione personalizzata per avviare il processo Claude Code. Usala per eseguire Claude Code in VM, container o ambienti remoti |554| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Funzione personalizzata per avviare il processo Claude Code. Usala per eseguire Claude Code in VM, container o ambienti remoti |
553| `stderr` | `(data: string) => void` | `undefined` | Callback per l'output stderr |555| `stderr` | `(data: string) => void` | `undefined` | Callback per l'output di stderr |
554| `strictMcpConfig` | `boolean` | `false` | Usa solo i server passati in `mcpServers` e ignora il `.mcp.json` del progetto, le impostazioni utente, i server MCP forniti dai plugin e i [connettori claude.ai](https://code.claude.com/docs/it/mcp.md#use-mcp-servers-from-claude-ai) |556| `strictMcpConfig` | `boolean` | `false` | Usa solo i server passati in `mcpServers` e ignora il file `.mcp.json` del progetto, le impostazioni utente, i server MCP forniti dai plugin e i [connettori di claude.ai](https://code.claude.com/docs/it/mcp.md#use-mcp-servers-from-claude-ai) |
555| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined` (prompt minimo) | Configurazione del prompt di sistema. Passa una stringa per un prompt personalizzato, oppure `{ type: 'preset', preset: 'claude_code' }` per usare il prompt di sistema di Claude Code. Passa un array di stringhe con la costante esportata `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` tra la parte statica e quella per richiesta per [memorizzare nella cache la parte statica di un prompt personalizzato](https://code.claude.com/docs/it/agent-sdk/modifying-system-prompts.md#cache-the-static-part-of-a-custom-prompt). Quando usi la forma a oggetto preset, aggiungi `append` per estenderlo con istruzioni aggiuntive, e imposta `excludeDynamicSections: true` per spostare il contesto per sessione nel primo messaggio utente per [un miglior riutilizzo della cache dei prompt tra computer](https://code.claude.com/docs/it/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines). Imposta `snapshot: false` per ricostruire il prompt a ogni richiesta invece di [riutilizzare il prompt che la sessione ha registrato alla prima richiesta](https://code.claude.com/docs/it/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session). Per impostare `snapshot` su un prompt personalizzato, passa la forma `{ type: 'custom', prompt }`. La forma `{ type: 'custom' }` e il campo `snapshot` richiedono TypeScript Agent SDK v0.3.257 o successivo |557| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined` (prompt minimo) | Configurazione del prompt di sistema. Passa una stringa per un prompt personalizzato, oppure `{ type: 'preset', preset: 'claude_code' }` per usare il prompt di sistema di Claude Code. Passa un array di stringhe con la costante esportata `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` tra la parte statica e quella per richiesta per [memorizzare nella cache la parte statica di un prompt personalizzato](https://code.claude.com/docs/it/agent-sdk/modifying-system-prompts.md#cache-the-static-part-of-a-custom-prompt). Quando usi la forma a oggetto preset, aggiungi `append` per estenderlo con istruzioni aggiuntive e imposta `excludeDynamicSections: true` per spostare il contesto per sessione nel primo messaggio dell'utente, per un [migliore riuso della cache dei prompt tra macchine](https://code.claude.com/docs/it/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines). Imposta `snapshot: false` per ricostruire il prompt a ogni richiesta invece di [riusare il prompt che la sessione ha registrato alla prima richiesta](https://code.claude.com/docs/it/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session). Per impostare `snapshot` su un prompt personalizzato, passa la forma `{ type: 'custom', prompt }`. La forma `{ type: 'custom' }` e il campo `snapshot` richiedono TypeScript Agent SDK v0.3.257 o successiva |
556| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* Budget dell'attività lato API in token. Quando è impostato, al modello viene comunicato il budget di token rimanente, così può dosare l'uso degli strumenti e concludere prima del limite |558| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* Budget dell'attività lato API in token. Quando è impostato, al modello viene comunicato il budget di token rimanente in modo che possa dosare l'uso degli strumenti e concludere prima del limite |
557| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` per i modelli supportati | Controlla il comportamento di ragionamento di Claude. Consulta [`ThinkingConfig`](#thinkingconfig) per le opzioni |559| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` per i modelli supportati | Controlla il comportamento di ragionamento di Claude. Consulta [`ThinkingConfig`](#thinkingconfig) per le opzioni |
558| `title` | `string` | `undefined` | Titolo visualizzato per la sessione. Quando riprendi tramite `resume` o `continue`, il titolo salvato della sessione ripresa ha la precedenza; usa [`renameSession()`](#renamesession) per rinominare una sessione esistente |560| `title` | `string` | `undefined` | Titolo visualizzato per la sessione. Quando riprendi tramite `resume` o `continue`, il titolo persistito della sessione ripresa ha la precedenza; usa [`renameSession()`](#renamesession) per rinominare una sessione esistente |
559| `toolAliases` | `Record<string, string>` | `undefined` | Mappa i nomi degli strumenti integrati ai nomi di strumenti MCP, così che Claude chiami la tua implementazione MCP al posto di quella integrata. Ad esempio, `{ Bash: 'mcp__workspace__bash' }` |561| `toolAliases` | `Record<string, string>` | `undefined` | Mappa i nomi degli strumenti integrati ai nomi degli strumenti MCP in modo che Claude chiami la tua implementazione MCP al posto di quella integrata. Ad esempio, `{ Bash: 'mcp__workspace__bash' }` |
560| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | Configurazione del comportamento degli strumenti integrati. Consulta [`ToolConfig`](#toolconfig) per i dettagli |562| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | Configurazione del comportamento degli strumenti integrati. Consulta [`ToolConfig`](#toolconfig) per i dettagli |
561| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configurazione degli strumenti. Passa un array di nomi di strumenti o usa il preset per ottenere gli strumenti predefiniti di Claude Code |563| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configurazione degli strumenti. Passa un array di nomi di strumenti o usa il preset per ottenere gli strumenti predefiniti di Claude Code |
562| `verbatimPrompts` | `boolean` | `false` | Recapita ogni prompt così come è scritto. L'SDK invia ogni messaggio utente con `client_composed: true`. Consulta [`client_composed`](#sdkusermessage) per ciò che Claude Code salta su quei messaggi. Usa questa opzione quando il testo del prompt include contenuti che l'utente finale non ha digitato. Per il controllo per turno, lasciala disattivata e imposta invece `client_composed` sui singoli messaggi in streaming. Richiede TypeScript Agent SDK v0.3.280 o successivo e Claude Code v2.1.248 o successivo; la versione di Claude Code inclusa in quelle versioni dell'SDK soddisfa il requisito di Claude Code |564| `verbatimPrompts` | `boolean` | `false` | Consegna ogni prompt così come è scritto. L'SDK invia ogni messaggio dell'utente con `client_composed: true`. Consulta [`client_composed`](#sdkusermessage) per sapere cosa salta Claude Code su questi messaggi. Usa questa opzione quando il testo del tuo prompt include contenuti che l'utente finale non ha digitato. Per un controllo per turno, lasciala disattivata e imposta invece `client_composed` sui singoli messaggi trasmessi in streaming. Richiede TypeScript Agent SDK v0.3.280 o successiva e Claude Code v2.1.248 o successiva; la versione di Claude Code inclusa in queste versioni dell'SDK soddisfa il requisito di Claude Code |
563 565
564#### Gestire risposte API lente o bloccate566#### Gestire risposte API lente o bloccate
565 567
581});583});
582```584```
583 585
584* [`API_TIMEOUT_MS`](https://code.claude.com/docs/it/env-vars): quanto può attendere ogni tentativo di richiesta per le intestazioni della risposta, in millisecondi. Non limita la durata di una risposta in streaming dopo l'arrivo delle intestazioni. Predefinito `600000`. Si applica al ciclo principale e a tutti i subagent.586* [`API_TIMEOUT_MS`](https://code.claude.com/docs/it/env-vars): quanto a lungo ogni tentativo di richiesta può attendere gli header della risposta, in millisecondi. Non limita la durata di una risposta in streaming dopo l'arrivo degli header. Valore predefinito `600000`. Si applica al ciclo principale e a tutti i subagent.
585* `CLAUDE_CODE_MAX_RETRIES`: numero massimo di nuovi tentativi API. Valore predefinito `10`, con un limite di `15`. Ogni nuovo tentativo ha la propria finestra `API_TIMEOUT_MS`.587* `CLAUDE_CODE_MAX_RETRIES`: numero massimo di nuovi tentativi API. Valore predefinito `10`, con un limite di `15`. Ogni nuovo tentativo ha la propria finestra `API_TIMEOUT_MS`.
586 588
587 Per le esecuzioni non presidiate che devono attendere durante interruzioni più lunghe, imposta [`CLAUDE_CODE_RETRY_WATCHDOG=1`](https://code.claude.com/docs/it/errors#tune-retry-behavior): riprova indefinitamente in caso di errori di capacità transitori e, su Claude Code v2.1.199 o successive, alza il valore predefinito per gli altri errori transitori a `300` e rimuove il limite su questa variabile.589 Per le esecuzioni non presidiate che devono attendere interruzioni più lunghe, imposta [`CLAUDE_CODE_RETRY_WATCHDOG=1`](https://code.claude.com/docs/it/errors#tune-retry-behavior): riprova indefinitamente in caso di errori di capacità transitori e, su Claude Code v2.1.199 o successiva, aumenta il valore predefinito per gli altri errori transitori a `300` e rimuove il limite su questa variabile.
588* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog dei blocchi per i subagent. Mentre il watchdog dello stream è attivo, il valore predefinito è `CLAUDE_STREAM_IDLE_TIMEOUT_MS` più 5 minuti, ovvero `600000` a meno che tu non aumenti quella variabile. Con il watchdog dello stream disattivato, il valore predefinito è `600000`. Prima della v2.1.257, il valore predefinito era sempre `600000`.590* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog dei blocchi per i subagent. Mentre il watchdog dello stream è attivo, il valore predefinito è `CLAUDE_STREAM_IDLE_TIMEOUT_MS` più 5 minuti, cioè `600000` a meno che tu non aumenti quella variabile. Con il watchdog dello stream disattivato, il valore predefinito è `600000`. Prima della v2.1.257, il valore predefinito era sempre `600000`.
589 591
590 Il timer si azzera a ogni evento dello stream. In caso di blocco, Claude Code interrompe il subagent e segnala il blocco al padre. Per un subagent in background, contrassegna anche l'attività come non riuscita e allega l'eventuale risultato parziale.592 Il timer si azzera a ogni evento dello stream. In caso di blocco, Claude Code interrompe il subagent e segnala il blocco al processo padre. Per un subagent in background, contrassegna anche l'attività come non riuscita e allega l'eventuale risultato parziale.
591* `CLAUDE_ENABLE_STREAM_WATCHDOG` con `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: watchdog dello stream che interrompe la richiesta quando gli header sono arrivati ma il corpo della risposta smette di essere trasmesso. Il watchdog è attivo per impostazione predefinita per tutti i provider; imposta `CLAUDE_ENABLE_STREAM_WATCHDOG=0` per disabilitarlo. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` ha come valore predefinito `300000` e non può scendere sotto tale minimo. Dopo l'interruzione, [Nuovi tentativi automatici](https://code.claude.com/docs/it/errors.md#automatic-retries) descrive cosa fa Claude Code, in base a quanto era avanzata la risposta.593* `CLAUDE_ENABLE_STREAM_WATCHDOG` con `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: watchdog dello stream che interrompe la richiesta quando gli header sono arrivati ma il corpo della risposta smette di essere trasmesso. Il watchdog è attivo per impostazione predefinita per tutti i provider; imposta `CLAUDE_ENABLE_STREAM_WATCHDOG=0` per disattivarlo. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` ha come valore predefinito `300000` ed è vincolato a quel minimo. Dopo l'interruzione, [Nuovi tentativi automatici](https://code.claude.com/docs/it/errors.md#automatic-retries) descrive cosa fa Claude Code, in base a quanto era avanzata la risposta.
592 594
593 Mentre il watchdog attende una risposta che un gateway dietro `ANTHROPIC_BASE_URL` mantiene aperta con ping keep-alive, un host che imposta `includePartialMessages` continua a ricevere [eventi dello stream](#sdkpartialassistantmessage) `ping`, quindi interpreta quei frame come segnali di attività invece di far scadere la sessione per il silenzio. Prima della v2.1.257, i frame si interrompevano 5 minuti dopo l'ultimo evento reale dello stream.595 Mentre il watchdog attende una risposta che un gateway dietro `ANTHROPIC_BASE_URL` tiene aperta con ping keep-alive, un host che imposta `includePartialMessages` continua a ricevere [eventi dello stream](#sdkpartialassistantmessage) `ping`, quindi interpreta questi frame come segnali di attività invece di far scadere la sessione per silenzio. Prima della v2.1.257, i frame si interrompevano 5 minuti dopo l'ultimo evento reale dello stream.
594 596
595### Oggetto `Query`597### Oggetto `Query`
596 598
655 657
656| Metodo | Descrizione |658| Metodo | Descrizione |
657| :- | :- |659| :- | :- |
658| `interrupt()` | Interrompe la query. Disponibile solo in modalità di input in streaming. Quando la CLI dichiara la capacità `interrupt_receipt_v1` in [`SDKSystemMessage.capabilities`](#sdksystemmessage), si risolve con un [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) che elenca i messaggi in sospeso al momento dell'arrivo dell'interruzione. Si risolve con `undefined` sulle CLI precedenti alla v2.1.205 |660| `interrupt()` | Interrompe la query. Disponibile solo in modalità di input in streaming. Quando la CLI dichiara la capacità `interrupt_receipt_v1` in [`SDKSystemMessage.capabilities`](#sdksystemmessage), si risolve con un [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) che elenca i messaggi in sospeso al momento dell'interruzione. Si risolve con `undefined` sulle CLI precedenti alla v2.1.205 |
659| `rewindFiles(userMessageId, options?)` | Ripristina i file allo stato in cui si trovavano al messaggio utente specificato. Passa `{ dryRun: true }` per visualizzare un'anteprima delle modifiche. Richiede `enableFileCheckpointing: true`. Consulta [Checkpointing dei file](https://code.claude.com/docs/it/agent-sdk/file-checkpointing.md) |661| `rewindFiles(userMessageId, options?)` | Ripristina i file allo stato in cui si trovavano al messaggio dell'utente specificato. Passa `{ dryRun: true }` per visualizzare in anteprima le modifiche. Richiede `enableFileCheckpointing: true`. Consulta [Checkpointing dei file](https://code.claude.com/docs/it/agent-sdk/file-checkpointing.md) |
660| `setPermissionMode()` | Cambia la modalità di permesso (disponibile solo in modalità di input in streaming) |662| `setPermissionMode()` | Cambia la modalità di permesso (disponibile solo in modalità di input in streaming) |
661| `setModel()` | Cambia il modello (disponibile solo in modalità di input in streaming). Passare `undefined` o la stringa `"default"` ripristina il [modello predefinito di Claude Code](https://code.claude.com/docs/it/model-config.md). Una sessione in modalità `auto` [passa alla modalità `default`](https://code.claude.com/docs/it/agent-sdk/permissions#auto-mode-auto) se il nuovo modello non supporta la modalità auto |663| `setModel()` | Cambia il modello (disponibile solo in modalità di input in streaming). Passando `undefined` o la stringa `"default"` si ripristina il [modello predefinito di Claude Code](https://code.claude.com/docs/it/model-config.md). Una sessione in modalità `auto` [passa alla modalità `default`](https://code.claude.com/docs/it/agent-sdk/permissions#auto-mode-auto) se il nuovo modello non supporta la modalità auto |
662| `setMaxThinkingTokens()` | *Deprecato:* usa invece l'opzione `thinking`. Cambia il numero massimo di token di ragionamento. Passare `null` ripristina il ragionamento al valore predefinito della sessione: un override impostato a metà sessione viene rimosso, e il ragionamento resta disattivato per le sessioni in cui è disabilitato |664| `setMaxThinkingTokens()` | *Deprecato:* usa invece l'opzione `thinking`. Cambia il numero massimo di token di ragionamento. Passando `null` si ripristina il ragionamento al valore predefinito della sessione: un override impostato a metà sessione viene cancellato e il ragionamento resta disattivato per le sessioni in cui è disabilitato |
663| `applyFlagSettings(settings)` | Esegue il merge delle impostazioni nel livello delle impostazioni da flag della sessione in fase di esecuzione (disponibile solo in modalità di input in streaming). Consulta [`applyFlagSettings()`](#applyflagsettings) |665| `applyFlagSettings(settings)` | Esegue il merge delle impostazioni nel livello di impostazioni dei flag della sessione in fase di esecuzione (disponibile solo in modalità di input in streaming). Consulta [`applyFlagSettings()`](#applyflagsettings) |
664| `updateSettings(source, settings)` | Scrive una chiave consentita nel file di impostazioni locali del progetto o nel tuo file di impostazioni utente, così che il valore persista per le sessioni successive. Consulta [`updateSettings()`](#updatesettings). Richiede TypeScript SDK v0.3.257 o successivo, che include Claude Code v2.1.257 |666| `updateSettings(source, settings)` | Scrive una chiave consentita nel file di impostazioni locali del progetto o nel tuo file di impostazioni utente, in modo che il valore persista per le sessioni successive. Consulta [`updateSettings()`](#updatesettings). Richiede TypeScript SDK v0.3.257 o successiva, che include Claude Code v2.1.257 |
665| `initializationResult()` | Restituisce il risultato completo dell'inizializzazione, inclusi comandi supportati, modelli, informazioni sull'account e configurazione dello stile di output |667| `initializationResult()` | Restituisce il risultato completo dell'inizializzazione, inclusi i comandi supportati, i modelli, le informazioni sull'account e la configurazione dello stile di output |
666| `reinitialize()` | Invia di nuovo la richiesta di controllo `initialize` alla CLI in esecuzione e restituisce un risultato aggiornato invece del risultato memorizzato della prima connessione. Usalo dopo un'interruzione del trasporto, ad esempio quando ti ricolleghi a una sessione dopo una disconnessione, così che le richieste di permesso in sospeso raggiungano di nuovo la tua callback `canUseTool`. Rendi la callback idempotente per ID di richiesta, perché una richiesta la cui risposta è andata persa viene inviata di nuovo. Richiede Claude Code v2.1.195 o successivo |668| `reinitialize()` | Invia di nuovo la richiesta di controllo `initialize` alla CLI in esecuzione e restituisce un risultato aggiornato invece del risultato memorizzato della prima connessione. Usalo dopo un'interruzione del trasporto, ad esempio quando ti ricolleghi a una sessione dopo una disconnessione, in modo che le richieste di permesso in sospeso raggiungano di nuovo la tua callback `canUseTool`. Rendi la callback idempotente per ID di richiesta, perché una richiesta la cui risposta è andata persa viene inviata di nuovo. Richiede Claude Code v2.1.195 o successiva |
667| `supportedCommands()` | Restituisce i comandi disponibili. A partire da Agent SDK v0.3.216 l'elenco riflette le modifiche ai comandi avvenute a metà sessione; consulta [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |669| `supportedCommands()` | Restituisce i comandi disponibili. Da Agent SDK v0.3.216 l'elenco riflette le modifiche ai comandi avvenute a metà sessione; consulta [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |
668| `supportedModels()` | Restituisce i modelli disponibili con le informazioni di visualizzazione |670| `supportedModels()` | Restituisce i modelli disponibili con le informazioni di visualizzazione |
669| `supportedAgents()` | Restituisce i subagent disponibili come [`AgentInfo`](#agentinfo)`[]` |671| `supportedAgents()` | Restituisce i subagent disponibili come [`AgentInfo`](#agentinfo)`[]` |
670| `mcpServerStatus()` | Restituisce lo stato dei server MCP connessi come [`McpServerStatus`](#mcpserverstatus)`[]` |672| `mcpServerStatus()` | Restituisce lo stato dei server MCP connessi come [`McpServerStatus`](#mcpserverstatus)`[]` |
671| `getContextUsage(opts?)` | Restituisce un [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) che scompone l'utilizzo della finestra di contesto della sessione per categoria, skill e strumento. Con il `detail` predefinito, include i dati che `/context` mostra in una sessione interattiva, calcolati con richieste API di conteggio dei token che non compaiono nel flusso dei messaggi; consulta [come vengono gestite queste richieste](#sdkcontrolgetcontextusageresponse). L'[opzione `detail`](#sdkcontrolgetcontextusageresponse) richiede Agent SDK v0.3.257 o successivo |673| `getContextUsage(opts?)` | Restituisce un [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) che scompone l'utilizzo della finestra di contesto della sessione per categoria, skill e strumento. Con il valore predefinito di `detail`, include i dati che `/context` mostra in una sessione interattiva, calcolati con richieste API di conteggio dei token che non compaiono nel flusso dei messaggi; consulta [come vengono gestite queste richieste](#sdkcontrolgetcontextusageresponse). L'[opzione `detail`](#sdkcontrolgetcontextusageresponse) richiede Agent SDK v0.3.257 o successiva |
672| `readFile(path, options?)` | Legge un file dal filesystem della sessione. Claude Code risolve il percorso rispetto a `cwd`; [Cosa può leggere `readFile()`](#what-readfile-can-read) elenca i file che fornisce. Passa `{ maxBytes }` per cambiare il limite di lettura (predefinito 1 MB, massimo 10 MB) e `{ encoding: 'base64' }` per i file binari come le immagini. Si risolve con un [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), oppure con `null` in caso di permesso negato, file mancante o errore di trasporto. Richiede TypeScript SDK v0.2.121 o successivo |674| `readFile(path, options?)` | Legge un file dal filesystem della sessione. Claude Code risolve il percorso rispetto a `cwd`; [Cosa può leggere `readFile()`](#what-readfile-can-read) elenca i file che fornisce. Passa `{ maxBytes }` per cambiare il limite di lettura (predefinito 1 MB, massimo 10 MB) e `{ encoding: 'base64' }` per i file binari come le immagini. Si risolve con un [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), oppure con `null` in caso di permesso negato, file mancante o errore di trasporto. Richiede TypeScript SDK v0.2.121 o successiva |
673| `reloadPlugins(options?)` | Ricarica i plugin dal disco, in modo che i plugin che installi o modifichi a metà sessione raggiungano la sessione in esecuzione. Si risolve con un [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) che elenca i comandi, i subagent, i plugin e lo stato dei server MCP della sessione. Richiede Agent SDK v0.2.85 o successive. L'[opzione `holdOnCacheImpact`](#sdkcontrolreloadpluginsresponse) richiede Agent SDK v0.3.268 o successive. L'[opzione `addPlugins`](#load-more-plugin-folders-with-addplugins) richiede Agent SDK v0.3.301 o successive |675| `reloadPlugins(options?)` | Ricarica i plugin dal disco, in modo che i plugin che installi o modifichi a metà sessione raggiungano la sessione in esecuzione. Si risolve con un [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) che elenca i comandi, i subagent, i plugin e lo stato dei server MCP della sessione. Richiede Agent SDK v0.2.85 o successiva. L'[opzione `holdOnCacheImpact`](#sdkcontrolreloadpluginsresponse) richiede Agent SDK v0.3.268 o successiva. L'[opzione `addPlugins`](#load-more-plugin-folders-with-addplugins) richiede Agent SDK v0.3.301 o successiva |
674| `reloadSkills()` | Ricarica le skill dal disco, così che le skill che aggiungi o modifichi a metà sessione diventino disponibili per la sessione in esecuzione. Si risolve con un [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) che elenca le skill disponibili dopo il ricaricamento. Richiede Agent SDK v0.3.163 o successivo |676| `reloadSkills()` | Ricarica le skill dal disco, in modo che le skill che aggiungi o modifichi a metà sessione diventino disponibili per la sessione in esecuzione. Si risolve con un [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) che elenca le skill disponibili dopo il ricaricamento. Richiede Agent SDK v0.3.163 o successiva |
675| `reloadOutputStyles()` | Rilegge gli [stili di output](https://code.claude.com/docs/it/output-styles.md) dal disco, così che un file di stile che aggiungi o modifichi a metà sessione diventi disponibile per la sessione in esecuzione. Si risolve con un [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) che elenca i nomi degli stili disponibili dopo il ricaricamento. Richiede Agent SDK v0.3.261 o successivo |677| `reloadOutputStyles()` | Rilegge gli [stili di output](https://code.claude.com/docs/it/output-styles.md) dal disco, in modo che un file di stile che aggiungi o modifichi a metà sessione diventi disponibile per la sessione in esecuzione. Si risolve con un [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) che elenca i nomi degli stili disponibili dopo il ricaricamento. Richiede Agent SDK v0.3.261 o successiva |
676| `seedReadState(path, mtime)` | Contrassegna un file come già letto in modo che un Edit successivo non fallisca con `File has not been read yet`. Consulta [`seedReadState()`](#seedreadstate). Richiede TypeScript SDK v0.2.83 o versioni successive |678| `seedReadState(path, mtime)` | Contrassegna un file come già letto in modo che un Edit successivo non fallisca con `File has not been read yet`. Consulta [`seedReadState()`](#seedreadstate). Richiede TypeScript SDK v0.2.83 o successiva |
677| `accountInfo()` | Restituisce le informazioni sull'account |679| `accountInfo()` | Restituisce le informazioni sull'account |
678| `reconnectMcpServer(serverName)` | Riconnette un server MCP per nome. Se il nome corrisponde anche a una voce in un file di impostazioni come `.mcp.json` o `~/.claude.json`, Claude Code riconnette il server che hai configurato tramite [`mcpServers`](#options) o `setMcpServers()`, non la voce del file di impostazioni. Questo ordine di risoluzione richiede Claude Code v2.1.257 o successivo |680| `reconnectMcpServer(serverName)` | Riconnette un server MCP per nome. Se il nome corrisponde anche a una voce in un file di impostazioni come `.mcp.json` o `~/.claude.json`, Claude Code riconnette il server che hai configurato tramite [`mcpServers`](#options) o `setMcpServers()`, non la voce del file di impostazioni. Questo ordine di risoluzione richiede Claude Code v2.1.257 o successiva |
679| `toggleMcpServer(serverName, enabled)` | Abilita o disabilita un server MCP per nome, con la stessa risoluzione dei nomi di `reconnectMcpServer()`. Disabilitare un server lo disconnette e ne rimuove gli strumenti. Consulta [`toggleMcpServer()`](#togglemcpserver) per la versione di Claude Code richiesta per ciascun tipo di server |681| `toggleMcpServer(serverName, enabled)` | Abilita o disabilita un server MCP per nome, con la stessa risoluzione dei nomi di `reconnectMcpServer()`. La disabilitazione di un server lo disconnette e ne rimuove gli strumenti. Consulta [`toggleMcpServer()`](#togglemcpserver) per la versione di Claude Code richiesta per ciascun tipo di server |
680| `setMcpServers(servers)` | Sostituisce i server MCP gestiti da questo metodo: i server aggiunti tramite esso e i [server SDK in-process](#createsdkmcpserver). Si risolve con un [`McpSetServersResult`](#mcpsetserversresult) che indica quali server sono stati aggiunti e rimossi, più eventuali errori; quella sezione indica quali altri server restano connessi |682| `setMcpServers(servers)` | Sostituisce i server MCP gestiti da questo metodo: i server aggiunti tramite esso e i [server SDK in-process](#createsdkmcpserver). Si risolve con un [`McpSetServersResult`](#mcpsetserversresult) che indica quali server sono stati aggiunti e rimossi ed eventuali errori; quella sezione spiega quali altri server restano connessi |
681| `setMcpPermissionModeOverride(serverName, mode)` | Sovrascrive la modalità di permesso per gli strumenti di un server MCP con una modalità più restrittiva di quella della sessione, oppure cancella l'override con `null`. Disponibile solo in modalità di input in streaming. Consulta [`setMcpPermissionModeOverride()`](#setmcppermissionmodeoverride). Richiede TypeScript SDK v0.3.187 o versioni successive |683| `setMcpPermissionModeOverride(serverName, mode)` | Sovrascrive la modalità di permesso per gli strumenti di un server MCP con una modalità più restrittiva di quella della sessione, oppure cancella l'override con `null`. Disponibile solo in modalità di input in streaming. Consulta [`setMcpPermissionModeOverride()`](#setmcppermissionmodeoverride). Richiede TypeScript SDK v0.3.187 o successiva |
682| `readMcpResource(serverName, uri)` | *Alpha.* Legge una risorsa MCP Apps `ui://` da un server MCP connesso, così che la tua applicazione possa mostrare il widget di uno strumento. Si risolve con un [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse). Richiede TypeScript Agent SDK v0.3.280 o successivo |684| `readMcpResource(serverName, uri)` | *Alpha.* Legge una risorsa MCP Apps `ui://` da un server MCP connesso in modo che la tua applicazione possa visualizzare il widget di uno strumento. Si risolve con un [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse). Richiede TypeScript Agent SDK v0.3.280 o successiva |
683| `streamInput(stream)` | Trasmette in streaming i messaggi di input alla query per le conversazioni a più turni |685| `streamInput(stream)` | Trasmette in streaming messaggi di input alla query per conversazioni a più turni |
684| `stopTask(taskId)` | Interrompe un'attività in background in esecuzione tramite ID |686| `stopTask(taskId)` | Interrompe un'attività in background in esecuzione tramite ID |
685| `backgroundTasks(toolUseId?)` | Sposta in background i comandi Bash e i subagent in esecuzione che il turno sta attendendo, come quando premi Ctrl+B nel terminale interattivo. Consulta [`backgroundTasks()`](#backgroundtasks). Richiede TypeScript SDK v0.2.139 o versioni successive |687| `backgroundTasks(toolUseId?)` | Sposta in background i comandi Bash e i subagent in esecuzione che il turno sta attendendo, come premere Ctrl+B nel terminale interattivo. Consulta [`backgroundTasks()`](#backgroundtasks). Richiede TypeScript SDK v0.2.139 o successiva |
686| `close()` | Chiude la query e termina il processo sottostante. Termina forzatamente la query e libera tutte le risorse |688| `close()` | Chiude la query e termina il processo sottostante. Termina forzatamente la query e libera tutte le risorse |
687 689
688#### `setMcpPermissionModeOverride()`690#### `setMcpPermissionModeOverride()`
689 691
690Sovrascrive la modalità di permesso per gli strumenti di un server MCP con una modalità più restrittiva di quella della sessione, oppure cancella l'override con `null`. Usalo quando una sessione viene eseguita in una modalità che salta le richieste di permesso per singola azione, ma gli strumenti di un server devono comunque essere verificati. Richiede TypeScript SDK v0.3.187 o versioni successive.692Sovrascrive la modalità di permesso per gli strumenti di un server MCP con una modalità più restrittiva di quella della sessione, oppure cancella l'override con `null`. Usalo quando una sessione viene eseguita in una modalità che salta le richieste di permesso per singola azione, ma gli strumenti di un server devono comunque essere revisionati. Richiede TypeScript SDK v0.3.187 o successiva.
691 693
692Passa uno di questi tre valori come `mode`:694Passa uno di tre valori come `mode`:
693 695
694* `'default'`: Claude Code valuta le chiamate agli strumenti di quel server come fa la [modalità manuale](https://code.claude.com/docs/it/permission-modes.md#available-modes).696* `'default'`: Claude Code valuta le chiamate agli strumenti di quel server come fa la [modalità Manual](https://code.claude.com/docs/it/permission-modes.md#available-modes).
695* `'auto'`: Claude Code instrada le chiamate agli strumenti di quel server attraverso il classificatore della [modalità auto](https://code.claude.com/docs/it/permission-modes.md#eliminate-prompts-with-auto-mode). Claude Code rifiuta questo valore quando il classificatore non è disponibile per la sessione.697* `'auto'`: Claude Code instrada le chiamate agli strumenti di quel server attraverso il classificatore della [modalità auto](https://code.claude.com/docs/it/permission-modes.md#eliminate-prompts-with-auto-mode). Claude Code rifiuta questo valore quando il classificatore non è disponibile per la sessione.
696* `null`: cancella l'override.698* `null`: cancella l'override.
697 699
698L'override ha effetto solo mentre la sessione si trova in una modalità che salta le richieste di permesso per singola azione: `bypassPermissions` o `auto`. In qualsiasi altra modalità della sessione Claude Code ignora l'override, quindi non può mai ampliare ciò che la sessione consente.700L'override ha effetto solo mentre la sessione si trova in una modalità che salta le richieste di permesso per singola azione: `bypassPermissions` o `auto`. In qualsiasi altra modalità della sessione Claude Code non applica l'override, quindi non può mai ampliare ciò che la sessione consente.
699 701
700La promise si risolve con `{ warning }` quando non è ancora noto alcun server con quel nome. Claude Code memorizza comunque l'override e lo applica non appena si connette un server con quel nome esatto, quindi l'avviso serve a verificare gli errori di battitura, non indica un fallimento.702La promise si risolve con `{ warning }` quando non è ancora noto alcun server con quel nome. Claude Code memorizza comunque l'override e lo applica quando si connette un server con esattamente quel nome, quindi l'avviso serve a rilevare errori di battitura, non indica un fallimento.
701 703
702Disponibile solo in modalità di input in streaming, lo stesso vincolo di `setModel()` e `setPermissionMode()`.704Disponibile solo in modalità di input in streaming, con lo stesso vincolo di `setModel()` e `setPermissionMode()`.
703 705
704#### `seedReadState()`706#### `seedReadState()`
705 707
706Contrassegna un file come già letto in modo che un Edit successivo non fallisca con `File has not been read yet`. Usalo quando la tua applicazione ha rimosso dal contesto della conversazione un risultato `Read` precedente e Claude modificherà quel file subito dopo. Richiede TypeScript SDK v0.2.83 o versioni successive.708Contrassegna un file come già letto in modo che un Edit successivo non fallisca con `File has not been read yet`. Usalo quando la tua applicazione ha eliminato dal contesto della conversazione un risultato `Read` precedente e Claude modificherà quel file subito dopo. Richiede TypeScript SDK v0.2.83 o successiva.
707 709
708Passa `mtime` come ora di modifica del file al momento di quella lettura precedente, in millisecondi interi dall'epoch, ad esempio `Math.floor(stat.mtimeMs)`. Se il file su disco è cambiato dopo quel momento, Claude Code salta il contrassegno.710Passa `mtime` come data di modifica del file al momento di quella lettura precedente, in millisecondi interi dall'epoch, ad esempio `Math.floor(stat.mtimeMs)`. Se il file su disco è cambiato dopo quel momento, Claude Code salta il contrassegno.
709 711
710La promise si risolve indipendentemente dal fatto che il file sia stato contrassegnato, quindi una promise risolta non ti dice quale dei due casi si è verificato.712La promise si risolve sia che il file sia stato contrassegnato sia che non lo sia, quindi una promise risolta non ti dice quale dei due casi si è verificato.
711 713
712#### `backgroundTasks()`714#### `backgroundTasks()`
713 715
714Sposta in background i comandi Bash e i subagent in esecuzione che il turno sta attendendo, come quando premi Ctrl+B nel terminale interattivo. Passa il `toolUseId` di una chiamata a uno strumento per spostare in background solo il comando Bash o il subagent avviato da quella chiamata, oppure omettilo per spostare in background ogni attività in primo piano. Richiede TypeScript SDK v0.2.139 o versioni successive.716Sposta in background i comandi Bash e i subagent in esecuzione che il turno sta attendendo, come premere Ctrl+B nel terminale interattivo. Passa il `toolUseId` di una chiamata a uno strumento per spostare in background solo il comando Bash o il subagent avviato da quella chiamata, oppure omettilo per spostare in background ogni attività in primo piano. Richiede TypeScript SDK v0.2.139 o successiva.
715 717
716Ogni chiamata a uno strumento spostata in background restituisce immediatamente a Claude un risultato che indica l'esecuzione in background, il turno continua e Claude Code emette un [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) quando l'attività termina.718Ogni chiamata a uno strumento spostata in background restituisce immediatamente a Claude un risultato di esecuzione in background, il turno continua e Claude Code emette un [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) quando l'attività termina.
717 719
718In una sessione in cui le attività in background sono abilitate, la promise si risolve in un booleano:720In una sessione in cui le attività in background sono abilitate, la promise si risolve con un valore booleano:
719 721
720* **`true`**: un'attività è stata spostata in background, oppure hai omesso `toolUseId`.722* **`true`**: un'attività è stata spostata in background, oppure hai omesso `toolUseId`.
721* **`false`**: il `toolUseId` che hai passato non corrisponde ad alcuna attività in primo piano.723* **`false`**: il `toolUseId` che hai passato non corrisponde ad alcuna attività in primo piano.
724 726
725#### `applyFlagSettings()`727#### `applyFlagSettings()`
726 728
727Modifica le [impostazioni](https://code.claude.com/docs/it/settings.md) di una sessione in esecuzione senza riavviare la query. Usalo quando un'impostazione priva di un setter dedicato deve cambiare a metà sessione, ad esempio per restringere `permissions` dopo che l'agente ha letto input non attendibile. `setModel()` e `setPermissionMode()` sono setter dedicati per quelle due chiavi; `applyFlagSettings()` è la forma generale che accetta qualsiasi sottoinsieme delle chiavi delle impostazioni, e passare `model` qui si comporta allo stesso modo di `setModel()`.729Modifica le [impostazioni](https://code.claude.com/docs/it/settings.md) di una sessione in esecuzione senza riavviare la query. Usalo quando un'impostazione che non ha un setter dedicato deve cambiare a metà sessione, ad esempio per restringere `permissions` dopo che l'agente ha letto input non attendibile. `setModel()` e `setPermissionMode()` sono setter dedicati per queste due chiavi; `applyFlagSettings()` è la forma generica che accetta qualsiasi sottoinsieme delle chiavi delle impostazioni, e passare `model` qui si comporta come `setModel()`.
728 730
729Solo alcune chiavi hanno effetto a metà sessione:731Solo alcune chiavi hanno effetto a metà sessione:
730 732
731* **Applicate al turno successivo**: `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `agent`. Cambiare `agent` applica al turno successivo anche l'override del modello e gli hook di quell'agente. Il suo prompt di sistema si applica al turno successivo oppure, in una sessione che [riutilizza un prompt di sistema registrato](https://code.claude.com/docs/it/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session), una volta che la sessione viene compattata.733* **Applicate al turno successivo**: `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `agent`. Il cambio di `agent` applica anche l'override del modello e gli hook di quell'agente al turno successivo. Il suo prompt di sistema si applica al turno successivo oppure, in una sessione che [riusa un prompt di sistema registrato](https://code.claude.com/docs/it/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session), una volta che la sessione viene compattata.
732* **Applicate durante il turno corrente**: `model`. Se cambi `model` mentre Claude sta lavorando a un turno, la risposta che Claude sta già generando termina con il vecchio modello, e il resto del turno, a partire dalla chiamata successiva che Claude Code fa al modello, usa quello nuovo. I subagent mantengono il proprio modello. Prima della v2.1.212, un cambio a metà turno attendeva il turno successivo.734* **Applicate durante il turno corrente**: `model`. Se cambi `model` mentre Claude sta lavorando a un turno, la risposta che Claude sta già generando termina con il vecchio modello, e il resto del turno, a partire dalla chiamata successiva che Claude Code effettua al modello, usa quello nuovo. I subagent mantengono il proprio modello. Prima della v2.1.212, un cambio a metà turno attendeva il turno successivo.
733* **Nessun effetto a metà sessione**: le opzioni del prompt di sistema. Vengono risolte una sola volta all'avvio, quindi la sessione in esecuzione mantiene il valore originale anche se la chiamata riesce. Per cambiarle, avvia una nuova sessione.735* **Nessun effetto a metà sessione**: le opzioni del prompt di sistema. Vengono risolte una sola volta all'avvio, quindi la sessione in esecuzione mantiene il valore originale anche se la chiamata va a buon fine. Per modificarle, avvia una nuova sessione.
734 736
735`effortLevel` accetta il nome di un [livello di sforzo](https://code.claude.com/docs/it/model-config.md#adjust-effort-level). Accetta anche `"ultracode"`, che richiede lo sforzo `xhigh` con [ultracode](https://code.claude.com/docs/it/workflows.md#let-claude-decide-with-ultracode) attivo. `applyFlagSettings()` dichiara `effortLevel` senza quel valore, quindi in TypeScript passa `{ ultracode: true, effortLevel: "xhigh" }` per ottenere lo stesso risultato, oppure la sola chiave [`ultracode`](https://code.claude.com/docs/it/settings-reference#ultracode) per attivare ultracode al livello di sforzo corrente della sessione. Il valore `ultracode` richiede Claude Code v2.1.203 o successivo ed è accettato solo da `applyFlagSettings()`, non dalla chiave `effortLevel` in un file di impostazioni. Prima della v2.1.284, la sola chiave `ultracode` impostava anche il livello su `xhigh`.737`effortLevel` accetta il nome di un [livello di sforzo](https://code.claude.com/docs/it/model-config.md#adjust-effort-level). Accetta anche `"ultracode"`, che richiede uno sforzo `xhigh` con [ultracode](https://code.claude.com/docs/it/workflows.md#let-claude-decide-with-ultracode) attivo. `applyFlagSettings()` dichiara `effortLevel` senza quel valore, quindi in TypeScript passa `{ ultracode: true, effortLevel: "xhigh" }` per ottenere lo stesso risultato, oppure solo la chiave [`ultracode`](https://code.claude.com/docs/it/settings-reference#ultracode) per attivare ultracode al livello di sforzo corrente della sessione. Il valore `ultracode` richiede Claude Code v2.1.203 o successiva ed è accettato solo da `applyFlagSettings()`, non dalla chiave `effortLevel` in un file di impostazioni. Prima della v2.1.284, la sola chiave `ultracode` impostava anche il livello su `xhigh`.
736 738
737I valori vengono scritti nel livello delle impostazioni da flag, sottoposti a merge sopra quanto impostato all'avvio dall'opzione `settings` inline di `query()`. Si tratta dello stesso livello che la [sezione sulla precedenza in questa pagina](#settings-precedence) chiama opzioni programmatiche.739I valori vengono scritti nel livello di impostazioni dei flag, con merge sopra ciò che l'opzione inline `settings` di `query()` ha impostato all'avvio. Si tratta dello stesso livello che la [sezione sulla precedenza in questa pagina](#settings-precedence) chiama opzioni programmatiche.
738 740
739Le chiamate successive eseguono un merge superficiale delle chiavi di primo livello. Una seconda chiamata con `{ permissions: {...} }` sostituisce l'intero oggetto `permissions` della chiamata precedente invece di eseguirne un merge profondo.741Le chiamate successive eseguono un merge superficiale delle chiavi di primo livello. Una seconda chiamata con `{ permissions: {...} }` sostituisce l'intero oggetto `permissions` della chiamata precedente invece di eseguirne un merge profondo.
740 742
741Per rimuovere una chiave impostata con `applyFlagSettings()`, passa `null` per quella chiave. La maggior parte delle chiavi ripiega quindi prima su un valore impostato all'avvio dall'opzione `settings` di `query()`, poi sulle fonti con precedenza inferiore. Un `model` rimosso torna al [modello predefinito di Claude Code](https://code.claude.com/docs/it/model-config.md), anche quando un file di impostazioni imposta `model`. Passare `undefined` non ha alcun effetto perché la serializzazione JSON lo scarta.743Per cancellare una chiave impostata con `applyFlagSettings()`, passa `null` per quella chiave. La maggior parte delle chiavi ripiega quindi prima su un valore che l'opzione `settings` di `query()` ha impostato all'avvio, poi sulle origini con precedenza inferiore. Un `model` cancellato torna al [modello predefinito di Claude Code](https://code.claude.com/docs/it/model-config.md), anche quando un file di impostazioni imposta `model`. Passare `undefined` non ha effetto perché la serializzazione JSON lo elimina.
742 744
743Oltre a `model`, tre chiavi reimpostano lo stato della sessione invece di ripiegare su un altro valore:745Tre chiavi oltre a `model` reimpostano lo stato della sessione invece di ripiegare su un altro valore:
744 746
745* `effortLevel: null` riporta la sessione al livello di sforzo predefinito del modello, non all'opzione `effort` di `query()` né a un `effortLevel` di un file di impostazioni.747* `effortLevel: null` riporta la sessione al livello di sforzo predefinito del modello, non all'opzione `effort` di `query()` né a un `effortLevel` da un file di impostazioni.
746* `agent: null` esegue il thread principale senza agente, a partire dal turno successivo, invece di ripristinare l'opzione `agent` di `query()` o un `agent` di un file di impostazioni. Se l'agente rimosso aveva applicato il proprio modello, la sessione torna al modello risolto all'avvio.748* `agent: null` esegue il thread principale senza agente, a partire dal turno successivo, invece di ripristinare l'opzione `agent` di `query()` o un `agent` da un file di impostazioni. Se l'agente cancellato aveva applicato un proprio modello, la sessione torna al modello che aveva risolto all'avvio.
747* `ultracode: null` disattiva ultracode, come fa `false`, invece di ripristinare un valore `ultracode` di un file di impostazioni. La sessione mantiene il livello di sforzo corrente, quindi passa `effortLevel` nella stessa chiamata per cambiarlo.749* `ultracode: null` disattiva ultracode, come fa `false`, invece di ripristinare un valore `ultracode` da un file di impostazioni. La sessione mantiene il livello di sforzo corrente, quindi passa `effortLevel` nella stessa chiamata per modificarlo.
748 750
749Disponibile solo in modalità di input in streaming, lo stesso vincolo di `setModel()` e `setPermissionMode()`.751Disponibile solo in modalità di input in streaming, con lo stesso vincolo di `setModel()` e `setPermissionMode()`.
750 752
751L'esempio seguente cambia il modello attivo a metà sessione, poi rimuove l'override così che il modello torni al [modello predefinito di Claude Code](https://code.claude.com/docs/it/model-config.md).753L'esempio seguente cambia il modello attivo a metà sessione, poi cancella l'override in modo che il modello torni al [modello predefinito di Claude Code](https://code.claude.com/docs/it/model-config.md).
752 754
753```typescript theme={null}755```typescript theme={null}
754import { query } from "@anthropic-ai/claude-agent-sdk";756import { query } from "@anthropic-ai/claude-agent-sdk";
768 770
769#### `updateSettings()`771#### `updateSettings()`
770 772
771Scrive una chiave consentita in un file di impostazioni su disco, così che il valore persista per le sessioni successive che caricano quella fonte. Ogni fonte accetta una sola chiave, con un valore stringa:773Scrive una chiave consentita in un file di impostazioni su disco, in modo che il valore persista per le sessioni successive che caricano quell'origine. Ogni origine accetta una chiave, con un valore stringa:
772 774
773* **`"localSettings"`**: accetta `outputStyle` e ne esegue il merge nel file di impostazioni locali del progetto, `.claude/settings.local.json`. Il nuovo stile ha effetto alla richiesta successiva della sessione.775* **`"localSettings"`**: accetta `outputStyle` e ne esegue il merge nel file di impostazioni locali del progetto, `.claude/settings.local.json`. Il nuovo stile ha effetto alla richiesta successiva della sessione.
774* **`"userSettings"`**: accetta `effortLevel` e lo salva come [livello di sforzo](https://code.claude.com/docs/it/model-config.md#adjust-effort-level) predefinito per il modello corrente della sessione, sotto [`modelSettings`](https://code.claude.com/docs/it/settings-reference#modelsettings) nel tuo file di impostazioni utente. Passare `max` non scrive nulla, perché `max` vale solo per la sessione. In ogni caso la sessione in esecuzione mantiene il livello di sforzo corrente, quindi chiama [`applyFlagSettings()`](#applyflagsettings) quando vuoi cambiare anche quello. Questa fonte richiede TypeScript SDK v0.3.277 o successivo, che include Claude Code v2.1.277.776* **`"userSettings"`**: accetta `effortLevel` e lo salva come [livello di sforzo](https://code.claude.com/docs/it/model-config.md#adjust-effort-level) predefinito per il modello corrente della sessione, sotto [`modelSettings`](https://code.claude.com/docs/it/settings-reference#modelsettings) nel tuo file di impostazioni utente. Passando `max` non viene scritto nulla, perché `max` vale solo per la sessione. In entrambi i casi la sessione in esecuzione mantiene il livello di sforzo corrente, quindi chiama [`applyFlagSettings()`](#applyflagsettings) se vuoi modificare anche quello. Questa origine richiede TypeScript SDK v0.3.277 o successiva, che include Claude Code v2.1.277.
775 777
776La chiamata viene rifiutata quando la richiesta contiene qualsiasi altra chiave, quando la sessione viene eseguita su un trasporto remoto e quando le [`settingSources`](#options) della sessione escludono la fonte indicata. L'eliminazione di una chiave non è supportata.778La chiamata viene rifiutata quando la richiesta contiene qualsiasi altra chiave, quando la sessione viene eseguita su un trasporto remoto e quando i [`settingSources`](#options) della sessione escludono l'origine che indichi. L'eliminazione di una chiave non è supportata.
777 779
778#### `toggleMcpServer()`780#### `toggleMcpServer()`
779 781
780Disabilitare un server lo disconnette e ne rimuove gli strumenti dalla sessione. Per i server aggiunti a metà sessione e per i server in-process, questo dipende dalla tua versione di Claude Code:782La disabilitazione di un server lo disconnette e rimuove i suoi strumenti dalla sessione. Per i server aggiunti a metà sessione e per i server in-process, questo dipende dalla tua versione di Claude Code:
781 783
782* Un server stdio, SSE o HTTP aggiunto a metà sessione con `setMcpServers()`: la rimozione dei suoi strumenti richiede Claude Code v2.1.285 o successivo.784* Un server stdio, SSE o HTTP che hai aggiunto a metà sessione con `setMcpServers()`: la rimozione dei suoi strumenti richiede Claude Code v2.1.285 o successiva.
783* Un server in-process creato con [`createSdkMcpServer()`](#createsdkmcpserver), che tu lo abbia passato in `mcpServers` o con `setMcpServers()`: la sua disconnessione e la rimozione dei suoi strumenti richiedono Claude Code v2.1.286 o successivo. Disabilitarne uno fa inoltre fallire le sue chiamate agli strumenti ancora in esecuzione, così Claude riceve immediatamente un risultato di errore per ciascuna di esse, senza attendere che il tuo handler restituisca un valore.785* Un server in-process che hai creato con [`createSdkMcpServer()`](#createsdkmcpserver), sia che tu l'abbia passato in `mcpServers` sia con `setMcpServers()`: la sua disconnessione e la rimozione dei suoi strumenti richiedono Claude Code v2.1.286 o successiva. La disabilitazione fa anche fallire le sue chiamate agli strumenti ancora in esecuzione, quindi Claude riceve immediatamente un risultato di errore per ciascuna di esse, senza attendere che il tuo handler restituisca un valore.
784 786
785### `WarmQuery`787### `WarmQuery`
786 788
798| Metodo | Descrizione |800| Metodo | Descrizione |
799| :- | :- |801| :- | :- |
800| `query(prompt)` | Invia un prompt al sottoprocesso preriscaldato e restituisce una [`Query`](#query-object). Può essere chiamato una sola volta per `WarmQuery` |802| `query(prompt)` | Invia un prompt al sottoprocesso preriscaldato e restituisce una [`Query`](#query-object). Può essere chiamato una sola volta per `WarmQuery` |
801| `close()` | Chiude il sottoprocesso senza inviare un prompt. Usalo per scartare una warm query non più necessaria |803| `close()` | Chiude il sottoprocesso senza inviare un prompt. Usalo per scartare una warm query che non serve più |
802 804
803`WarmQuery` implementa `AsyncDisposable`, quindi può essere usato con `await using` per la pulizia automatica.805`WarmQuery` implementa `AsyncDisposable`, quindi può essere usato con `await using` per la pulizia automatica.
804 806
805### `SpareProcess`807### `SpareProcess`
806 808
807*Alpha.* Handle restituito da [`prewarm()`](#prewarm): un processo Claude Code avviato che non è ancora associato a una sessione e può essere rivendicato una sola volta. Richiede TypeScript Agent SDK v0.3.282 o successivo.809*Alpha.* Handle restituito da [`prewarm()`](#prewarm): un processo Claude Code avviato che non è ancora associato a una sessione e può essere rivendicato una sola volta. Richiede TypeScript Agent SDK v0.3.282 o successiva.
808 810
809```typescript theme={null}811```typescript theme={null}
810interface SpareProcess extends AsyncDisposable {812interface SpareProcess extends AsyncDisposable {
822 824
823| Membro | Descrizione |825| Membro | Descrizione |
824| :- | :- |826| :- | :- |
825| `claim({ prompt, options })` | Associa il processo di riserva a una sessione in `options.cwd` e invia il primo messaggio. Restituisce una [`Query`](#query-object) in modo sincrono, come fa `query()`. Può essere chiamato una sola volta |827| `claim({ prompt, options })` | Associa il processo di riserva a una sessione in `options.cwd` e invia il suo primo messaggio. Restituisce una [`Query`](#query-object) in modo sincrono, come fa `query()`. Può essere chiamato una sola volta |
826| `claimed` | Si risolve con la directory di lavoro e l'ID della sessione una volta che Claude Code accetta la rivendicazione. Viene rifiutata quando Claude Code rifiuta la rivendicazione, quando il processo è terminato o è stato chiuso prima e, con un messaggio che inizia con `option_not_applied`, quando la sessione è in esecuzione senza il `model` o il `maxThinkingTokens` che hai richiesto |828| `claimed` | Si risolve con la directory di lavoro e l'ID della sessione quando Claude Code accetta la rivendicazione. Viene rifiutata quando Claude Code rifiuta la rivendicazione, quando il processo è terminato o è stato chiuso prima e, con un messaggio che inizia con `option_not_applied`, quando la sessione è in esecuzione senza il `model` o il `maxThinkingTokens` che hai richiesto |
827| `exited` | Si conclude quando il processo termina, rivendicato o meno. Sostituisci un processo di riserva che termina prima che tu lo rivendichi |829| `exited` | Si conclude quando il processo termina, che sia stato rivendicato o meno. Sostituisci un processo di riserva che termina prima che tu lo rivendichi |
828| `close()` | Termina il processo. Prima di una rivendicazione, scarta il processo di riserva e rifiuta `claimed` |830| `close()` | Termina il processo. Prima di una rivendicazione, scarta il processo di riserva e rifiuta `claimed` |
829 831
830`options.cwd` è obbligatorio. Una rivendicazione può anche impostare `additionalDirectories`, `model`, `permissionMode`, `maxThinkingTokens`, una sovrapposizione di impostazioni da flag in `settings`, `appendSystemPrompt`, `title`, `agents` e token per sessione in `env`.832`options.cwd` è obbligatorio. Una rivendicazione può anche impostare `additionalDirectories`, `model`, `permissionMode`, `maxThinkingTokens`, una sovrapposizione delle impostazioni dei flag in `settings`, `appendSystemPrompt`, `title`, `agents` e token per sessione in `env`.
831 833
832Claude Code può rifiutare una rivendicazione, ad esempio per una cartella che non esiste o per una cartella le cui impostazioni di progetto impostano `env`, `agent` o `model`. Dopo un rifiuto, un prompt già inviato da `claim()` riceve un risultato di errore il cui testo inizia con `not_claimed`, e la query restituita genera quindi un'eccezione. Racchiudi il ciclo della query in un blocco try per proseguire oltre l'eccezione. Quando `claimed` viene rifiutata con un messaggio che inizia con `option_not_applied`, la sessione è in esecuzione senza il `model` o il `maxThinkingTokens` che hai richiesto. Dopo qualsiasi altro rifiuto il tuo prompt non è stato eseguito, quindi avvia invece la sessione con `query()`.834Claude Code può rifiutare una rivendicazione, ad esempio per una cartella che non esiste o per una le cui impostazioni di progetto impostano `env`, `agent` o `model`. Dopo un rifiuto, un prompt che `claim()` ha già inviato riceve un risultato di errore il cui testo inizia con `not_claimed`, e la query restituita genera quindi un'eccezione. Racchiudi il ciclo della query in un blocco try per proseguire oltre l'eccezione. Quando `claimed` viene rifiutata con un messaggio che inizia con `option_not_applied`, la sessione è in esecuzione senza il `model` o il `maxThinkingTokens` che hai richiesto. Dopo qualsiasi altro rifiuto il tuo prompt non è stato eseguito, quindi avvia invece la sessione con `query()`.
833 835
834### `SDKControlInitializeResponse`836### `SDKControlInitializeResponse`
835 837
858};860};
859```861```
860 862
861`hooks_applied` indica se Claude Code ha registrato gli `hooks` contenuti nella richiesta `initialize`. L'SDK invia quella richiesta una volta all'avvio della sessione e di nuovo a ogni chiamata a [`reinitialize()`](#query-object). Il campo richiede Agent SDK v0.3.238 o successivo.863`hooks_applied` indica se Claude Code ha registrato gli `hooks` contenuti nella richiesta `initialize`. L'SDK invia questa richiesta una volta all'avvio della sessione e di nuovo a ogni chiamata a [`reinitialize()`](#query-object). Il campo richiede Agent SDK v0.3.238 o successiva.
862 864
863Claude Code omette il campo quando la richiesta non conteneva hook. Quando la richiesta conteneva hook, il valore dipende dal fatto che la richiesta sia il primo initialize della sessione e, per uno ripetuto, da come ha raggiunto la sessione:865Claude Code omette il campo quando la richiesta non conteneva hook. Quando la richiesta conteneva hook, il valore dipende dal fatto che la richiesta sia la prima inizializzazione della sessione e, per una ripetuta, da come ha raggiunto la sessione:
864 866
865* `true`: Claude Code ha registrato gli hook. Il primo initialize di una sessione restituisce questo valore. Anche un initialize ripetuto inviato tramite lo stdin della CLI restituisce `true`. In quel caso gli hook della nuova richiesta sostituiscono quelli registrati in precedenza.867* `true`: Claude Code ha registrato gli hook. La prima inizializzazione di una sessione restituisce questo valore. Anche un'inizializzazione ripetuta inviata tramite lo stdin della CLI restituisce `true`. In questo caso gli hook della nuova richiesta sostituiscono quelli registrati in precedenza.
866* `false`: Claude Code ha ignorato gli hook. Un initialize ripetuto inviato a una sessione remota restituisce questo valore, così un secondo client che si unisce a una sessione non può sostituire gli hook registrati dal primo client.868* `false`: Claude Code ha ignorato gli hook. Un'inizializzazione ripetuta inviata a una sessione remota restituisce questo valore, in modo che un secondo client che si unisce a una sessione non possa sostituire gli hook registrati dal primo client.
867 869
868Prima di Agent SDK v0.3.238, la risposta non conteneva mai il campo e Claude Code ignorava `hooks` a ogni initialize ripetuto.870Prima di Agent SDK v0.3.238, la risposta non conteneva mai il campo e Claude Code ignorava `hooks` a ogni inizializzazione ripetuta.
869 871
870Il campo `sdkMcpServerManifests` della richiesta e il campo `sdk_mcp_manifests_parked` della risposta riguardano i [server MCP SDK](https://code.claude.com/docs/it/agent-sdk/custom-tools.md) in-process creati con [`createSdkMcpServer()`](#createsdkmcpserver). La tua applicazione non imposta né legge nessuno dei due campi.872Il campo `sdkMcpServerManifests` della richiesta e il campo `sdk_mcp_manifests_parked` della risposta riguardano i [server MCP SDK](https://code.claude.com/docs/it/agent-sdk/custom-tools.md) in-process che hai creato con [`createSdkMcpServer()`](#createsdkmcpserver). La tua applicazione non imposta né legge nessuno dei due campi.
871 873
872`claude_code_version` è la versione di Claude Code del processo che esegue i turni della sessione. È lo stesso valore contenuto nel messaggio init [`SDKSystemMessage`](#sdksystemmessage), quindi puoi leggere la versione della CLI prima del primo turno.874`claude_code_version` è la versione di Claude Code del processo che esegue i turni della sessione. È lo stesso valore contenuto nel messaggio di inizializzazione [`SDKSystemMessage`](#sdksystemmessage), quindi puoi leggere la versione della CLI prima del primo turno.
873 875
874* Il campo richiede Agent SDK v0.3.296 o successiva, che include Claude Code v2.1.296.876* Il campo richiede Agent SDK v0.3.296 o successiva, che include Claude Code v2.1.296.
875* Se il campo è `undefined` e hai impostato `pathToClaudeCodeExecutable`, puntalo a Claude Code v2.1.296 o successiva.877* Se il campo è `undefined` e hai impostato `pathToClaudeCodeExecutable`, puntalo a Claude Code v2.1.296 o successiva.
876 878
877La risposta riporta sempre `fast_mode_state` e, quando qualcosa blocca la [modalità veloce](https://code.claude.com/docs/it/fast-mode.md), `fast_mode_disabled_reason` contiene accanto ad esso il codice del motivo, così puoi spiegare lo stato bloccato invece di ricavare di nuovo la disponibilità. Entrambi i comportamenti richiedono Claude Code v2.1.219 o successivo. Prima della v2.1.219, la risposta ometteva `fast_mode_state` quando la modalità veloce non era disponibile e non conteneva mai un motivo. Per i codici dei motivi e il loro significato, consulta [`fast_mode_disabled_reason`](#sdkresultmessage) nel messaggio di risultato.879La risposta riporta sempre `fast_mode_state` e, quando qualcosa blocca la [modalità veloce](https://code.claude.com/docs/it/fast-mode.md), `fast_mode_disabled_reason` riporta accanto il codice del motivo, così puoi spiegare lo stato di blocco invece di ricavare di nuovo la disponibilità. Entrambi i comportamenti richiedono Claude Code v2.1.219 o successiva. Prima della v2.1.219, la risposta ometteva `fast_mode_state` quando la modalità veloce non era disponibile e non riportava mai un motivo. Per i codici dei motivi e il loro significato, consulta [`fast_mode_disabled_reason`](#sdkresultmessage) nel messaggio di risultato.
878 880
879Il wrapper della risposta di controllo per un `initialize` riuscito contiene anche un array `pending_permission_requests`. Il campo si trova sul wrapper della risposta stesso, non nel payload `SDKControlInitializeResponse` riportato sopra. Ogni voce è un messaggio `control_request` completo, con la stessa forma `{ type: "control_request", request_id, request }` che la sessione trasmette in streaming per le richieste di permesso durante l'esecuzione.881Il wrapper della risposta di controllo per un `initialize` riuscito contiene anche un array `pending_permission_requests`. Il campo si trova sul wrapper della risposta stesso, non nel payload `SDKControlInitializeResponse` riportato sopra. Ogni voce è un messaggio `control_request` completo con la stessa forma `{ type: "control_request", request_id, request }` che la sessione trasmette in streaming per le richieste di permesso durante l'esecuzione.
880 882
881L'array elenca le richieste di permesso che questo processo Claude Code ha emesso e non ha ancora risolto. L'SDK legge l'array al posto tuo e inoltra ogni voce alla tua callback [`canUseTool`](#canusetool), lo stesso nuovo recapito che [`reinitialize()`](#query-object) attiva dopo un'interruzione del trasporto. Gestisci gli ID di richiesta ripetuti in modo idempotente, perché una voce può ripetere una richiesta che la callback ha già ricevuto prima che la connessione cadesse.883L'array elenca le richieste di permesso che questo processo Claude Code ha emesso e non ha ancora risolto. L'SDK legge l'array per te e invia ogni voce alla tua callback [`canUseTool`](#canusetool), la stessa riconsegna che [`reinitialize()`](#query-object) attiva dopo un'interruzione del trasporto. Gestisci gli ID di richiesta ripetuti in modo idempotente, perché una voce può ripetere una richiesta che la callback ha già ricevuto prima che la connessione cadesse.
882 884
883L'array è sempre presente in una risposta `initialize` riuscita ed è vuoto quando questo processo non ha richieste di permesso irrisolte. Richiede Claude Code v2.1.268 o successivo. Le versioni precedenti potevano omettere il campo, quindi se analizzi tu stesso il protocollo wire, considera un campo mancante come segno di una CLI meno recente e non come prova che non ci sia nulla in sospeso.885L'array è sempre presente in una risposta `initialize` riuscita ed è vuoto quando questo processo non ha richieste di permesso non risolte. Richiede Claude Code v2.1.268 o successiva. Le versioni precedenti potevano omettere il campo, quindi se analizzi tu stesso il protocollo wire, interpreta un campo mancante come indice di una CLI meno recente e non come prova che non ci sia nulla in sospeso.
884 886
885### `SDKControlInterruptResponse`887### `SDKControlInterruptResponse`
886 888
887La ricevuta dell'interruzione: il valore con cui [`interrupt()`](#query-object) si risolve su una CLI che dichiara la capacità `interrupt_receipt_v1` in [`SDKSystemMessage.capabilities`](#sdksystemmessage). Richiede Claude Code v2.1.205 o successivo. Le CLI precedenti rispondono all'interruzione con un payload di successo vuoto, quindi `interrupt()` si risolve con `undefined`.889La ricevuta dell'interruzione: il valore con cui [`interrupt()`](#query-object) si risolve su una CLI che dichiara la capacità `interrupt_receipt_v1` in [`SDKSystemMessage.capabilities`](#sdksystemmessage). Richiede Claude Code v2.1.205 o successiva. Le CLI precedenti rispondono all'interruzione con un payload di successo vuoto, quindi `interrupt()` si risolve con `undefined`.
888 890
889```typescript theme={null}891```typescript theme={null}
890type SDKControlInterruptResponse = {892type SDKControlInterruptResponse = {
893};895};
894```896```
895 897
896`still_queued` elenca gli UUID dei messaggi utente in sospeso al momento dell'arrivo dell'interruzione: i messaggi ancora in coda, più quelli che Claude Code aveva già prelevato dalla coda per il turno successivo. Una volta avviato il primo turno della sessione, Claude Code elabora i messaggi elencati dopo l'interruzione, a meno che tu non li annulli prima, e può accorparne diversi in un unico turno. Se interrompi prima dell'avvio del primo turno, Claude Code interrompe quel turno non appena inizia, e i messaggi elencati in quel turno non ricevono risposta.898`still_queued` elenca gli UUID dei messaggi dell'utente che erano in sospeso al momento dell'interruzione: i messaggi ancora in coda, più quelli che Claude Code aveva già prelevato dalla coda per il turno successivo. Una volta iniziato il primo turno della sessione, Claude Code elabora i messaggi elencati dopo l'interruzione a meno che tu non li annulli prima, e può unirne diversi in un unico turno. Se interrompi prima che inizi il primo turno, Claude Code interrompe quel turno non appena inizia e i messaggi elencati in quel turno non ricevono risposta.
897 899
898Usa la ricevuta per decidere se inviare di nuovo qualcosa. Un messaggio elencato che non annulli entra nella conversazione indipendentemente dal fatto che riceva una risposta, quindi inviarlo di nuovo lo recapita a Claude due volte.900Usa la ricevuta per decidere se inviare di nuovo qualcosa. Un messaggio elencato che non annulli entra nella conversazione indipendentemente dal fatto che riceva una risposta, quindi inviarlo di nuovo lo consegna a Claude due volte.
899 901
900Interpreta l'elenco tenendo conto di queste avvertenze:902Interpreta l'elenco tenendo conto di queste avvertenze:
901 903
902* Compaiono solo i messaggi accodati con un UUID. Un array vuoto non significa che non verrà eseguito nient'altro.904* Compaiono solo i messaggi accodati con un UUID. Un array vuoto non significa che nient'altro verrà eseguito.
903* Vengono elencati solo i messaggi del thread principale. I messaggi indirizzati a un subagent non sono inclusi.905* Vengono elencati solo i messaggi del thread principale. I messaggi indirizzati a un subagent sono esclusi.
904* L'elenco può includere UUID che il tuo client non ha mai inviato, come i trigger delle [attività pianificate con ambito di sessione](https://code.claude.com/docs/it/scheduled-tasks.md). Ignora gli UUID che non riconosci invece di trattarli come un errore.906* L'elenco può includere UUID che il tuo client non ha mai inviato, come i trigger delle [attività pianificate con ambito di sessione](https://code.claude.com/docs/it/scheduled-tasks.md). Ignora gli UUID che non riconosci invece di trattarli come un errore.
905 907
906Un client che gestisce direttamente il protocollo di controllo della CLI, invece di passare da `interrupt()`, può impostare `cancel_queued: true` nella richiesta di controllo `interrupt`. Claude Code v2.1.219 e successivi dichiarano il supporto con la capacità `interrupt_cancel_queued_v1` in [`SDKSystemMessage.capabilities`](#sdksystemmessage); le CLI meno recenti ignorano il campo e lasciano che i messaggi in coda vengano eseguiti normalmente. Un'interruzione di questo tipo annulla anche ogni messaggio che altrimenti verrebbe elencato in `still_queued`: la ricevuta li elenca invece in `cancelled`, `still_queued` è vuoto e nessuno di essi viene eseguito.908Un client che gestisce direttamente il protocollo di controllo della CLI, anziché tramite `interrupt()`, può impostare `cancel_queued: true` sulla richiesta di controllo `interrupt`. Claude Code v2.1.219 e successive dichiarano il supporto con la capacità `interrupt_cancel_queued_v1` in [`SDKSystemMessage.capabilities`](#sdksystemmessage); le CLI meno recenti ignorano il campo e lasciano che i messaggi in coda vengano eseguiti come di consueto. Un'interruzione di questo tipo annulla anche ogni messaggio che altrimenti verrebbe elencato in `still_queued`: la ricevuta li elenca invece in `cancelled`, `still_queued` è vuoto e nessuno di essi viene eseguito.
907 909
908L'elenco `cancelled` ha le stesse avvertenze di `still_queued`. Il metodo `interrupt()` non invia mai `cancel_queued`, quindi le ricevute con cui si risolve non contengono `cancelled`.910L'elenco `cancelled` ha le stesse avvertenze di `still_queued`. Il metodo `interrupt()` non invia mai `cancel_queued`, quindi le ricevute con cui si risolve non contengono `cancelled`.
909 911
910La ricevuta è un'istantanea acquisita nel momento in cui l'interruzione viene elaborata e, in caso di interruzione pulita, arriva prima del [`SDKResultMessage`](#sdkresultmessage) del turno interrotto. Leggi la ricevuta invece di ispezionare la coda dopo quel risultato: il ciclo avvia immediatamente il turno successivo in coda, quindi la coda che ispezioni dopo il risultato è già cambiata.912La ricevuta è un'istantanea acquisita nel momento in cui l'interruzione viene elaborata e, in caso di interruzione pulita, arriva prima dell'[`SDKResultMessage`](#sdkresultmessage) del turno interrotto. Leggi la ricevuta invece di esaminare la coda dopo quel risultato: il ciclo avvia immediatamente il turno successivo in coda, quindi la coda che esamini dopo il risultato è già cambiata.
911 913
912### `SDKControlGetContextUsageResponse`914### `SDKControlGetContextUsageResponse`
913 915
914Tipo restituito da [`getContextUsage()`](#query-object). Con il `detail` predefinito, la risposta include il payload che Claude Code visualizza per il comando `/context` in una sessione interattiva. Oltre ai conteggi dei token, quel payload contiene campi di visualizzazione come `color` e `gridRows` che Claude Code usa per disegnare la griglia di utilizzo di `/context`.916Tipo restituito da [`getContextUsage()`](#query-object). Con il valore predefinito di `detail`, la risposta include il payload che Claude Code visualizza per il comando `/context` in una sessione interattiva. Oltre ai conteggi dei token, quel payload contiene campi di visualizzazione come `color` e `gridRows` che Claude Code usa per disegnare la griglia di utilizzo di `/context`.
915 917
916L'argomento facoltativo `detail` del metodo sceglie come Claude Code conta ogni categoria. L'argomento `detail` richiede Agent SDK v0.3.257 o successivo.918L'argomento facoltativo `detail` del metodo sceglie come Claude Code conta ciascuna categoria. L'argomento `detail` richiede Agent SDK v0.3.257 o successiva.
917 919
918* **`'full'`**: il valore predefinito. Claude Code conta ogni categoria con richieste API di [conteggio dei token](https://platform.claude.com/docs/en/build-with-claude/token-counting). Queste richieste non compaiono nel flusso dei messaggi, quindi un tracciamento dei costi basato sul flusso non le vede. Sull'API Anthropic, il conteggio dei token non viene addebitato.920* **`'full'`**: il valore predefinito. Claude Code conta ciascuna categoria con richieste API di [conteggio dei token](https://platform.claude.com/docs/en/build-with-claude/token-counting). Queste richieste non compaiono nel flusso dei messaggi, quindi il tracciamento dei costi che legge il flusso non le vede. Sull'API di Anthropic, il conteggio dei token non viene fatturato.
919* **`'summary'`**: passa `{ detail: 'summary' }` per ottenere invece una risposta basata sull'utilizzo dell'ultima risposta e su stime locali. Non viene inviata alcuna richiesta di conteggio dei token, e i numeri per categoria sono approssimativi.921* **`'summary'`**: passa `{ detail: 'summary' }` per ottenere invece una risposta basata sull'utilizzo dell'ultima risposta e su stime locali. Non viene inviata alcuna richiesta di conteggio dei token e i numeri per categoria sono approssimativi.
920 922
921Quando invii `/context` come prompt invece di chiamare il metodo, Claude Code allega un payload [`SDKContextUsage`](#sdkcontextusage) al campo `context_usage` del messaggio dell'assistente che restituisce il risultato. Quel campo richiede Agent SDK v0.3.232 o successivo.923Quando invii `/context` come prompt invece di chiamare il metodo, Claude Code allega un payload [`SDKContextUsage`](#sdkcontextusage) al campo `context_usage` del messaggio dell'assistente che fornisce il risultato. Quel campo richiede Agent SDK v0.3.232 o successiva.
922 924
923In `SDKControlGetContextUsageResponse`, `categories[].id`, `mcpInstructions` e i campi `pluginId` e `path` delle voci di `agents` e `skills.skillFrontmatter` richiedono Agent SDK v0.3.304 o successivo.925In `SDKControlGetContextUsageResponse`, `categories[].id`, `mcpInstructions` e i campi `pluginId` e `path` delle voci `agents` e `skills.skillFrontmatter` richiedono Agent SDK v0.3.304 o successiva.
924 926
925```typescript theme={null}927```typescript theme={null}
926type SDKControlGetContextUsageResponse = {928type SDKControlGetContextUsageResponse = {
1042 1044
1043Leggi l'attribuzione dei token dai campi di tipo collezione:1045Leggi l'attribuzione dei token dai campi di tipo collezione:
1044 1046
1045* `categories` contiene i totali per categoria. Il campo `kind` di ogni voce classifica la riga con gli stessi valori di [`SDKContextUsageCategory`](#sdkcontextusagecategory). Classifica le righe in base a questo campo anziché al `name` visualizzato. Il campo richiede Agent SDK v0.3.268 o successivo.1047* `categories` contiene i totali per categoria. Il campo `kind` di ogni voce classifica la riga con gli stessi valori di [`SDKContextUsageCategory`](#sdkcontextusagecategory). Classifica le righe in base a questo campo anziché al `name` visualizzato. Il campo richiede Agent SDK v0.3.268 o successiva.
1046* `mcpTools` e `agents` attribuiscono i token ai singoli strumenti MCP e ai subagent.1048* `mcpTools` e `agents` attribuiscono i token ai singoli strumenti MCP e subagent.
1047* `memoryFiles` elenca ogni file di memoria caricato con il relativo costo.1049* `memoryFiles` elenca ogni file di memoria caricato con il relativo costo.
1048* `skills.skillFrontmatter` attribuisce i token dell'elenco delle skill a ciascuna skill inclusa. I conteggi per skill misurano la voce di elenco di ciascuna skill così come Claude Code la invia effettivamente, che può essere più breve del frontmatter completo della skill. Confronta `skills.totalSkills` con `skills.includedSkills` per verificare se ogni skill rilevata è stata inclusa nell'elenco.1050* `skills.skillFrontmatter` attribuisce i token dell'elenco delle skill a ciascuna skill inclusa. I conteggi per skill misurano la voce di elenco di ciascuna skill così come Claude Code la invia effettivamente, che può essere più breve del frontmatter completo della skill. Confronta `skills.totalSkills` con `skills.includedSkills` per verificare se ogni skill rilevata è stata inclusa nell'elenco.
1049 1051
1050`totalTokens` è l'utilizzo corrente del contesto della sessione, e `maxTokens` è la finestra rispetto alla quale viene misurato tale utilizzo. Quella finestra è la finestra di contesto del modello, oppure la finestra inferiore di compattazione automatica quando applicabile. `rawMaxTokens` contiene lo stesso valore di `maxTokens`, e `percentage` è `totalTokens` espresso come percentuale arrotondata di quella finestra. `apiUsage` contiene l'utilizzo dell'ultima risposta API, non un totale progressivo della sessione.1052`totalTokens` è l'utilizzo corrente del contesto della sessione e `maxTokens` è la finestra rispetto alla quale viene misurato tale utilizzo. Quella finestra è la finestra di contesto del modello, oppure la finestra inferiore di compattazione automatica quando applicabile. `rawMaxTokens` contiene lo stesso valore di `maxTokens` e `percentage` è `totalTokens` espresso come percentuale arrotondata di quella finestra. `apiUsage` contiene l'utilizzo dell'ultima risposta API, non un totale progressivo per la sessione.
1051 1053
1052Claude Code lascia non impostate le diagnostiche facoltative `deferredBuiltinTools`, `systemTools` e `systemPromptSections`, quindi aspettati che siano assenti anche se il tipo le dichiara.1054Claude Code lascia non impostate le diagnostiche facoltative `deferredBuiltinTools`, `systemTools` e `systemPromptSections`, quindi aspettati che siano assenti anche se il tipo le dichiara.
1053 1055
1054#### Trovare una riga per ID, i token delle istruzioni di un server o il plugin e il file di una voce1056#### Trovare una riga per ID, i token delle istruzioni di un server o il plugin e il file di una voce
1055 1057
1056Le istruzioni dei server MCP sono le note d'uso che i server connessi forniscono e che Claude Code aggiunge al contesto, e la riga `mcp_instructions` di `categories` ne conta i token. Usa questi campi di [`getContextUsage()`](#query-object) per individuare una riga di `categories` tramite `id`, suddividere i token di `mcp_instructions` per server o trovare il plugin e il file dietro una voce di agente o skill:1058Le istruzioni dei server MCP sono le note d'uso che i server connessi forniscono e che Claude Code aggiunge al contesto, e la riga `mcp_instructions` di `categories` ne conta i token. Usa questi campi di [`getContextUsage()`](#query-object) per individuare una riga di `categories` tramite `id`, suddividere i token di `mcp_instructions` per server o trovare il plugin e il file dietro una voce di agente o di skill:
1057 1059
1058| Campo | Dove si trova | Cosa contiene |1060| Campo | Dove si trova | Cosa contiene |
1059| :- | :- | :- |1061| :- | :- | :- |
1060| `id` | Ogni riga di `categories` | L'identificatore della riga, uno dei valori elencati dal [tipo di risposta](#sdkcontrolgetcontextusageresponse), come `mcp_instructions`. Confronta `id` per individuare una riga, oppure `kind` per raggruppare le righe. Una versione successiva di Claude Code può inviare un valore non elencato nei tipi installati, quindi tratta un `id` che non riconosci come assente |1062| `id` | Ogni riga di `categories` | L'identificatore della riga, uno dei valori elencati dal [tipo di risposta](#sdkcontrolgetcontextusageresponse), come `mcp_instructions`. Confronta `id` per individuare una riga, oppure `kind` per raggruppare le righe. Una versione successiva di Claude Code può inviare un valore che i tipi installati non elencano, quindi tratta un `id` che non riconosci come assente |
1061| `mcpInstructions` | La risposta | Una voce `{ serverName, tokens }` per ogni server MCP connesso che fornisce istruzioni, oppure un array vuoto quando nessuno lo fa. I valori `tokens` sono stime la cui somma corrisponde ai `tokens` della riga `mcp_instructions`. `serverName` è il `name` che [`mcpServerStatus()`](#query-object) riporta per quel server |1063| `mcpInstructions` | La risposta | Una voce `{ serverName, tokens }` per ogni server MCP connesso che fornisce istruzioni, oppure un array vuoto quando nessuno lo fa. I valori di `tokens` sono stime la cui somma corrisponde ai `tokens` della riga `mcp_instructions`. `serverName` è il `name` che [`mcpServerStatus()`](#query-object) riporta per quel server |
1062| `pluginId` | Voci di `agents` e `skills.skillFrontmatter` | Indica il plugin da cui proviene la voce, come ID nella forma `name@marketplace`, ed è assente per una voce che non proviene da un plugin. Quando il plugin non proviene da un marketplace, la parte dopo `@` indica invece [la sua origine](https://code.claude.com/docs/it/plugins/loading.md#find-where-a-plugin-came-from), ad esempio `inline` per un plugin caricato tramite l'opzione [`plugins`](#options) |1064| `pluginId` | Voci di `agents` e `skills.skillFrontmatter` | Indica il plugin da cui proviene la voce, come ID nella forma `name@marketplace`, ed è assente per una voce che non proviene da un plugin. Quando il plugin non proviene da un marketplace, la parte dopo `@` indica invece [la sua origine](https://code.claude.com/docs/it/plugins/loading.md#find-where-a-plugin-came-from), ad esempio `inline` per un plugin caricato tramite l'opzione [`plugins`](#options) |
1063| `path` | Voci di `agents` e `skills.skillFrontmatter` | Percorso assoluto del file che definisce l'agente o la skill, sulla macchina in cui viene eseguito Claude Code. Il campo è assente quando nessun file definisce la voce, ad esempio un agente dall'opzione [`agents`](#options) o una skill integrata in Claude Code |1065| `path` | Voci di `agents` e `skills.skillFrontmatter` | Percorso assoluto del file che definisce l'agente o la skill, sulla macchina in cui viene eseguito Claude Code. Il campo è assente quando nessun file definisce la voce, ad esempio un agente dell'opzione [`agents`](#options) o una skill integrata in Claude Code |
1064 1066
1065Come esempio di confronto su `id`, questo esempio trova la riga `mcp_instructions`:1067Come esempio di confronto su `id`, questo codice trova la riga `mcp_instructions`:
1066 1068
1067```typescript theme={null}1069```typescript theme={null}
1068// q is the Query object that query() returned1070// q is the Query object that query() returned
1088 1090
1089#### Cosa può leggere `readFile()`1091#### Cosa può leggere `readFile()`
1090 1092
1091`readFile()` fornisce un insieme di file più ristretto rispetto allo strumento Read:1093`readFile()` serve un insieme di file più ristretto rispetto allo strumento Read:
1092 1094
1093* Un file regolare all'interno di una delle directory di lavoro della sessione, come `cwd` e `additionalDirectories`1095* Un file regolare all'interno di una delle directory di lavoro della sessione, come `cwd` e `additionalDirectories`
1094* Alcuni file propri di Claude Code per la sessione, come i risultati degli strumenti1096* Alcuni file di Claude Code relativi alla sessione, come i risultati degli strumenti
1095 1097
1096Le regole deny e ask di `Read` bloccano comunque un percorso corrispondente, e un'ampia regola allow di `Read` non apre il resto del filesystem a `readFile()`. Per qualsiasi altra cosa la chiamata si risolve con `null`.1098Le regole di negazione e di richiesta di `Read` bloccano comunque un percorso corrispondente, e una regola di autorizzazione `Read` ampia non apre il resto del filesystem a `readFile()`. Per qualsiasi altro file la chiamata si risolve con `null`.
1097 1099
1098### `SDKControlReloadPluginsResponse`1100### `SDKControlReloadPluginsResponse`
1099 1101
1120};1122};
1121```1123```
1122 1124
1123I campi di tipo collezione descrivono la sessione dopo la chiamata:1125I campi di raccolta descrivono la sessione dopo la chiamata:
1124 1126
1125* `commands`, `agents` e `mcpServers`: i comandi, i subagent e lo stato dei server MCP della sessione, nelle stesse forme restituite da `supportedCommands()`, `supportedAgents()` e `mcpServerStatus()`. `supportedAgents()` continua a restituire l'elenco acquisito all'inizializzazione, quindi leggi `agents` qui per ottenere l'insieme dopo un ricaricamento1127* `commands`, `agents` e `mcpServers`: i comandi, i subagent e lo stato dei server MCP della sessione, nelle stesse forme restituite da `supportedCommands()`, `supportedAgents()` e `mcpServerStatus()`. `supportedAgents()` continua a restituire l'elenco acquisito all'inizializzazione, quindi leggi `agents` qui per ottenere l'insieme dopo un ricaricamento
1126* `plugins`: ogni plugin caricato con il suo `name` e il `path` di installazione. `version` ripete quanto dichiarato nel manifest del plugin ed è controllato dall'autore del plugin, quindi convalidalo prima di considerarlo attendibile. Viene omesso quando il manifest non ne dichiara alcuno1128* `plugins`: ogni plugin caricato con il suo `name` e il `path` di installazione. `version` riporta ciò che dichiara il manifest del plugin ed è controllato dall'autore del plugin, quindi convalidalo prima di fidarti. Viene omesso quando il manifest non ne dichiara nessuna
1127* `error_count`: il numero di errori durante il caricamento dei plugin1129* `error_count`: il numero di errori durante il caricamento dei plugin
1128 1130
1129Passa `{ holdOnCacheImpact: true }` a `reloadPlugins()` per trattenere, invece di applicarlo, un ricaricamento che invaliderebbe la cache dei prompt della conversazione. Claude Code esegue lo stesso controllo che il comando interattivo `/reload-plugins` effettua prima di [avvisare del costo per la cache](https://code.claude.com/docs/it/prompt-caching.md#enabling-or-disabling-a-plugin). L'opzione richiede Agent SDK v0.3.268 o successivo. Un eseguibile di Claude Code precedente alla v2.1.268, come uno a cui punti con `pathToClaudeCodeExecutable`, ignora l'opzione e applica il ricaricamento.1131Passa `{ holdOnCacheImpact: true }` a `reloadPlugins()` per sospendere un ricaricamento che invaliderebbe la cache del prompt della conversazione invece di applicarlo. Claude Code esegue il controllo che il comando interattivo `/reload-plugins` effettua prima di [avvisare del costo sulla cache](https://code.claude.com/docs/it/prompt-caching.md#enabling-or-disabling-a-plugin). L'opzione richiede Agent SDK v0.3.268 o successiva. Un eseguibile di Claude Code precedente alla v2.1.268, come quello a cui punti con `pathToClaudeCodeExecutable`, ignora l'opzione e applica il ricaricamento.
1130 1132
1131Quando passi l'opzione, leggi `held` per sapere cosa è successo:1133Quando passi l'opzione, leggi `held` per sapere cosa è successo:
1132 1134
1133* `true`: il ricaricamento non è stato applicato, e i campi di tipo collezione descrivono la sessione così com'è ancora. `cache_impact` indica cosa cambierebbe applicandolo. Per applicarlo comunque, chiama di nuovo `reloadPlugins()` senza l'opzione.1135* `true`: il ricaricamento non è stato applicato e i campi di raccolta descrivono la sessione così com'è ancora. `cache_impact` indica cosa cambierebbe applicandolo. Per applicarlo comunque, chiama di nuovo `reloadPlugins()` senza l'opzione.
1134* `false`: il controllo non ha rilevato alcun impatto sulla cache, e il ricaricamento è stato applicato.1136* `false`: il controllo non ha rilevato alcun impatto sulla cache e il ricaricamento è stato applicato.
1135* Assente: non hai passato l'opzione, oppure l'eseguibile di Claude Code è precedente alla v2.1.268 e ha applicato il ricaricamento.1137* Assente: non hai passato l'opzione, oppure l'eseguibile di Claude Code è precedente alla v2.1.268 e ha applicato il ricaricamento.
1136 1138
1137`cache_impact` è presente solo insieme a `held: true`. `mcp_servers_added` e `mcp_servers_removed` indicano i server MCP dei plugin che il ricaricamento registrerebbe o eliminerebbe, con nomi con ambito `plugin:<plugin>:<server>`. I nomi sono definiti dagli autori dei plugin, quindi convalidali prima di mostrarli. `lsp_tool_change` indica se l'applicazione aggiungerebbe o rimuoverebbe lo strumento LSP, oppure `null` quando non farebbe nessuna delle due cose. Le forme `may-` indicano che il controllo non è riuscito a vedere completamente l'insieme dei plugin in sospeso.1139`cache_impact` è presente solo insieme a `held: true`. `mcp_servers_added` e `mcp_servers_removed` indicano i server MCP dei plugin che il ricaricamento registrerebbe o rimuoverebbe, come nomi con ambito `plugin:<plugin>:<server>`. I nomi sono scritti dagli autori dei plugin, quindi convalidali prima di mostrarli. `lsp_tool_change` indica se l'applicazione aggiungerebbe o rimuoverebbe lo strumento LSP, oppure `null` se non farebbe nessuna delle due cose. Le forme `may-` indicano che il controllo non è riuscito a vedere completamente l'insieme di plugin in sospeso.
1138 1140
1139#### Caricare altre cartelle di plugin con `addPlugins`1141#### Caricare altre cartelle di plugin con `addPlugins`
1140 1142
1141Per caricare cartelle di plugin che non erano nell'opzione [`plugins`](#options) all'avvio, passale a `reloadPlugins()` come `addPlugins`, un elenco di voci [`SdkPluginConfig`](#sdkpluginconfig) il cui `path` è assoluto. Claude Code carica le nuove cartelle e ricarica i plugin esistenti della sessione in un unico passaggio. Anche i server MCP di ogni plugin aggiunto si connettono, a meno che tu non imposti [`skipMcpDiscovery`](#sdkpluginconfig) nella voce di quella cartella. Richiede Agent SDK v0.3.301 o successiva e Claude Code v2.1.301 o successiva.1143Per caricare cartelle di plugin che non erano nell'opzione [`plugins`](#options) all'avvio, passale a `reloadPlugins()` come `addPlugins`, un elenco di voci [`SdkPluginConfig`](#sdkpluginconfig) il cui `path` è assoluto. Claude Code carica le nuove cartelle e ricarica i plugin esistenti della sessione in un unico passaggio. Si connettono anche i server MCP di ogni plugin aggiunto, a meno che tu non imposti [`skipMcpDiscovery`](#sdkpluginconfig) nella voce di quella cartella. Richiede Agent SDK v0.3.301 o successiva e Claude Code v2.1.301 o successiva.
1142 1144
1143Questo esempio aggiunge una cartella a una query `q` in esecuzione e stampa il percorso di installazione di ogni plugin caricato dalla sessione quando la chiamata restituisce:1145Questo esempio aggiunge una cartella a una query `q` in esecuzione e, quando la chiamata restituisce, stampa il percorso di installazione di ogni plugin caricato dalla sessione:
1144 1146
1145```typescript theme={null}1147```typescript theme={null}
1146const result = await q.reloadPlugins({1148const result = await q.reloadPlugins({
1150console.log(result.plugins.map((plugin) => plugin.path));1152console.log(result.plugins.map((plugin) => plugin.path));
1151```1153```
1152 1154
1153Se la cartella è stata caricata, l'elenco stampato include `/opt/my-app/plugins/reports`, e i comandi e i subagent del plugin compaiono in `result.commands` e `result.agents`.1155Se la cartella è stata caricata, l'elenco stampato include `/opt/my-app/plugins/reports` e i comandi e i subagent del plugin compaiono in `result.commands` e `result.agents`.
1154 1156
1155Una cartella aggiunta rimane parte della sessione. Quando chiami di nuovo `reloadPlugins()`, Claude Code la ricarica insieme agli altri plugin e non devi passarla di nuovo in `addPlugins`.1157Una cartella aggiunta resta parte della sessione. Quando chiami di nuovo `reloadPlugins()`, Claude Code la ricarica insieme agli altri plugin e non devi passarla di nuovo in `addPlugins`.
1156 1158
1157##### Quando `reloadPlugins()` non carica le cartelle di `addPlugins`1159##### Quando `reloadPlugins()` non carica le cartelle di `addPlugins`
1158 1160
1159Se `reloadPlugins()` viene rifiutata, nessuna delle cartelle di `addPlugins` viene aggiunta, quindi passale di nuovo in `addPlugins` quando riprovi. Quando il rifiuto ha una delle seguenti cause, la sessione mantiene i plugin che aveva già:1161Se `reloadPlugins()` viene rifiutata, nessuna delle cartelle di `addPlugins` viene aggiunta, quindi passale di nuovo in `addPlugins` quando riprovi. Quando il rifiuto ha una delle seguenti cause, la sessione mantiene i plugin che aveva già:
1160 1162
1161* **Un `path` relativo o una voce malformata**: il messaggio di errore indica `add_plugins must be a list of { type: "local", path } entries with absolute paths`. Claude Code rifiuta l'intero elenco per una sola voce errata, quindi passa ogni voce come `{ type: "local", path }` con un `path` assoluto1163* **Un `path` relativo o una voce malformata**: il messaggio di errore indica `add_plugins must be a list of { type: "local", path } entries with absolute paths`. Claude Code rifiuta l'intero elenco a causa di una sola voce errata, quindi passa ogni voce come `{ type: "local", path }` con un `path` assoluto
1162* **Un amministratore ha attivato [`disableSideloadFlags`](https://code.claude.com/docs/it/settings-reference#disablesideloadflags) nelle tue impostazioni gestite**: il messaggio indica `reload_plugins add_plugins is disabled by managed settings (disableSideloadFlags)`. Per caricare la cartella, chiedi a quell'amministratore di rimuovere l'impostazione1164* **Un amministratore ha attivato [`disableSideloadFlags`](https://code.claude.com/docs/it/settings-reference#disablesideloadflags) nelle tue impostazioni gestite**: il messaggio indica `reload_plugins add_plugins is disabled by managed settings (disableSideloadFlags)`. Per caricare la cartella, chiedi a quell'amministratore di rimuovere l'impostazione
1163* **Non è stato possibile ricostruire la [sandbox](https://code.claude.com/docs/it/sandboxing.md)**: con il [sandboxing](#sandboxsettings) attivo, Claude Code ricostruisce la configurazione della sandbox in modo che i comandi shell in sandbox non possano scrivere nelle cartelle che aggiungi. Il messaggio indica `the sandbox could not be rebuilt to keep shell commands out of this folder`. Verifica che le tue [impostazioni della sandbox](#sandboxsettings) formino ancora una configurazione valida1165* **Non è stato possibile ricostruire la [sandbox](https://code.claude.com/docs/it/sandboxing.md)**: con il [sandboxing](#sandboxsettings) attivo, Claude Code ricostruisce la configurazione della sandbox in modo che i comandi shell eseguiti nella sandbox non possano scrivere nelle cartelle che aggiungi. Il messaggio indica `the sandbox could not be rebuilt to keep shell commands out of this folder`. Verifica che le tue [impostazioni della sandbox](#sandboxsettings) formino ancora una configurazione valida
1164 1166
1165Se passi `holdOnCacheImpact` e la chiamata si risolve con [`held: true`](#sdkcontrolreloadpluginsresponse), le cartelle di `addPlugins` non vengono aggiunte. Per aggiungerle comunque, chiama di nuovo `reloadPlugins()` con lo stesso elenco `addPlugins` e senza `holdOnCacheImpact`.1167Se passi `holdOnCacheImpact` e la chiamata si risolve con [`held: true`](#sdkcontrolreloadpluginsresponse), le cartelle di `addPlugins` non vengono aggiunte. Per aggiungerle comunque, chiama di nuovo `reloadPlugins()` con lo stesso elenco `addPlugins` e senza `holdOnCacheImpact`.
1166 1168
1167Quando la chiamata si risolve senza `held: true` e una cartella manca ancora da `result.plugins`, inizia verificando queste cause:1169Quando la chiamata si risolve senza `held: true` e una cartella manca ancora da `result.plugins`, inizia verificando queste cause:
1168 1170
1169* **La cartella non esiste o il suo plugin non è stato caricato**: `result.error_count` è `1` o superiore. La cartella rimane comunque parte della sessione. Dopo aver corretto la cartella, chiama di nuovo `reloadPlugins()` per caricarla, questa volta senza elencarla in `addPlugins`1171* **La cartella non esiste o il suo plugin non è stato caricato**: `result.error_count` è `1` o superiore. La cartella resta comunque parte della sessione. Dopo aver sistemato la cartella, chiama di nuovo `reloadPlugins()` per caricarla, questa volta senza elencarla in `addPlugins`
1170* **L'eseguibile di Claude Code è precedente alla v2.1.301**: un eseguibile precedente alla v2.1.301 ignora `addPlugins` e ricarica solo i plugin che la sessione aveva già. Controlla `claude_code_version` nel [messaggio init](#sdksystemmessage) ed esegui un eseguibile alla v2.1.301 o successiva1172* **L'eseguibile di Claude Code è precedente alla v2.1.301**: un eseguibile precedente alla v2.1.301 ignora `addPlugins` e ricarica solo i plugin che la sessione aveva già. Controlla `claude_code_version` nel [messaggio di init](#sdksystemmessage) ed esegui un eseguibile alla v2.1.301 o successiva
1171 1173
1172### `SDKControlReloadSkillsResponse`1174### `SDKControlReloadSkillsResponse`
1173 1175
1195 1197
1196### `SDKControlMcpReadResourceResponse`1198### `SDKControlMcpReadResourceResponse`
1197 1199
1198Tipo restituito da [`readMcpResource()`](#query-object), che contiene il risultato `resources/read` del server MCP. Richiede TypeScript Agent SDK v0.3.280 o successivo.1200Tipo restituito da [`readMcpResource()`](#query-object), che contiene il risultato di `resources/read` del server MCP. Richiede TypeScript Agent SDK v0.3.280 o successiva.
1199 1201
1200```typescript theme={null}1202```typescript theme={null}
1201type SDKControlMcpReadResourceResponse = {1203type SDKControlMcpReadResourceResponse = {
1209};1211};
1210```1212```
1211 1213
1212Passa a `readMcpResource()` il nome del server così come lo riporta `mcpServerStatus()` e un URI `ui://`, ad esempio il `ui.resourceUri` che uno strumento dichiara nel suo [`_meta`](#mcpserverstatus). La chiamata viene rifiutata per qualsiasi altro schema di URI, per un [server MCP SDK](#createsdkmcpserver) ospitato dalla tua applicazione stessa e per un server non connesso. È disponibile quando le [`capabilities`](#sdksystemmessage) del messaggio di init includono `mcp_read_resource_v1`.1214Passa a `readMcpResource()` il nome del server come lo riporta `mcpServerStatus()` e un URI `ui://`, come il `ui.resourceUri` che uno strumento dichiara nel suo [`_meta`](#mcpserverstatus). La chiamata viene rifiutata per qualsiasi altro schema URI, per un [server MCP SDK](#createsdkmcpserver) ospitato dalla tua applicazione stessa e per un server non connesso. È disponibile quando le [`capabilities`](#sdksystemmessage) del messaggio di init includono `mcp_read_resource_v1`.
1213 1215
1214Ogni voce di `contents` è un elemento di contenuto così come il server lo ha inviato, meno qualsiasi chiave `_meta` con il prefisso `com.anthropic/`, riservato a Claude Code. `blob` contiene dati base64 per un elemento binario, e `_meta` è il `_meta` dell'elemento stesso, dove un server MCP Apps inserisce `ui.csp` e `ui.permissions` della risorsa.1216Ogni voce di `contents` è un elemento di contenuto così come inviato dal server, privato di qualsiasi chiave `_meta` con il prefisso `com.anthropic/`, che è riservato a Claude Code. `blob` contiene dati base64 per un elemento binario, e `_meta` è il `_meta` proprio dell'elemento, dove un server MCP Apps inserisce `ui.csp` e `ui.permissions` della risorsa.
1215 1217
1216I contenuti sono HTML di terze parti non attendibile, quindi visualizzali in una sandbox.1218Il contenuto è HTML di terze parti non attendibile, quindi visualizzalo in una sandbox.
1217 1219
1218### `AgentDefinition`1220### `AgentDefinition`
1219 1221
1243| Campo | Obbligatorio | Descrizione |1245| Campo | Obbligatorio | Descrizione |
1244| :- | :- | :- |1246| :- | :- | :- |
1245| `description` | Sì | Descrizione in linguaggio naturale di quando usare questo agente |1247| `description` | Sì | Descrizione in linguaggio naturale di quando usare questo agente |
1246| `tools` | No | Array dei nomi degli strumenti consentiti. Se omesso, eredita ogni [strumento disponibile per i subagent](https://code.claude.com/docs/it/sub-agents.md#available-tools). Per precaricare le skill nel contesto dell'agente, usa il campo `skills` invece di elencare `'Skill'` qui |1248| `tools` | No | Array di nomi di strumenti consentiti. Se omesso, eredita ogni [strumento disponibile per i subagent](https://code.claude.com/docs/it/sub-agents.md#available-tools). Per precaricare le skill nel contesto dell'agente, usa il campo `skills` invece di elencare `'Skill'` qui |
1247| `disallowedTools` | No | Array dei nomi degli strumenti da vietare esplicitamente per questo agente. Sono accettati anche pattern a livello di server MCP: `mcp__server` o `mcp__server__*` rimuove ogni strumento di quel server, e `mcp__*` rimuove ogni strumento MCP di qualsiasi server |1249| `disallowedTools` | No | Array di nomi di strumenti da vietare esplicitamente per questo agente. Sono accettati anche pattern a livello di server MCP: `mcp__server` o `mcp__server__*` rimuove ogni strumento di quel server, e `mcp__*` rimuove ogni strumento MCP di qualsiasi server |
1248| `prompt` | Sì | Il prompt di sistema dell'agente |1250| `prompt` | Sì | Il prompt di sistema dell'agente |
1249| `model` | No | Override del modello per questo agente. Accetta un alias come `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'` oppure un ID di modello completo. `'inherit'` usa il modello principale. Se lo ometti, Claude Code sceglie il modello secondo l'[ordine dei modelli dei subagent](https://code.claude.com/docs/it/sub-agents.md#choose-a-model) |1251| `model` | No | Override del modello per questo agente. Accetta un alias come `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'` o un ID di modello completo. `'inherit'` usa il modello principale. Se lo ometti, Claude Code sceglie il modello secondo l'[ordine dei modelli dei subagent](https://code.claude.com/docs/it/sub-agents.md#choose-a-model) |
1250| `mcpServers` | No | Specifiche dei server MCP per questo agente |1252| `mcpServers` | No | Specifiche dei server MCP per questo agente |
1251| `skills` | No | Array dei nomi delle skill da precaricare nel contesto dell'agente |1253| `skills` | No | Array di nomi di skill da precaricare nel contesto dell'agente |
1252| `initialPrompt` | No | Inviato automaticamente come primo turno utente quando questo agente viene eseguito come agente del thread principale |1254| `initialPrompt` | No | Inviato automaticamente come primo turno utente quando questo agente viene eseguito come agente del thread principale |
1253| `maxTurns` | No | Numero massimo di turni agentici (round trip API) prima dell'arresto |1255| `maxTurns` | No | Numero massimo di turni agentici (round trip dell'API) prima dell'arresto |
1254| `autoCompactWindow` | No | Riduci la [finestra di compattazione automatica](https://code.claude.com/docs/it/sub-agents.md#subagent-auto-compact-window) per questo agente quando viene eseguito come subagent, a un numero di token compreso tra `100000` e `1000000`. Richiede TypeScript Agent SDK v0.3.296 o successive |1256| `autoCompactWindow` | No | Riduce la [finestra di compattazione automatica](https://code.claude.com/docs/it/sub-agents.md#subagent-auto-compact-window) per questo agente quando viene eseguito come subagent, a un numero di token compreso tra `100000` e `1000000`. Richiede TypeScript Agent SDK v0.3.296 o successiva |
1255| `background` | No | Esegue questo agente come attività in background non bloccante quando viene invocato |1257| `background` | No | Esegue questo agente come attività in background non bloccante quando viene invocato |
1256| `omitClaudeMd` | No | Esclude i file CLAUDE.md utente, di progetto e locali dal contesto iniziale di questo agente; i file di policy gestiti vengono comunque caricati. Usalo per agenti che ricevono tutto ciò di cui hanno bisogno dal prompt dello strumento Agent. Ignorato quando questo agente viene eseguito come agente del thread principale. Richiede TypeScript Agent SDK v0.3.271 o successive |1258| `omitClaudeMd` | No | Esclude i file CLAUDE.md utente, di progetto e locali dal contesto iniziale di questo agente; i file delle policy gestite vengono comunque caricati. Usalo per agenti che ricevono tutto ciò di cui hanno bisogno dal prompt dello strumento Agent. Ignorato quando questo agente viene eseguito come agente del thread principale. Richiede TypeScript Agent SDK v0.3.271 o successiva |
1257| `memory` | No | Fonte di memoria per questo agente: `'user'`, `'project'` o `'local'` |1259| `memory` | No | Origine della memoria per questo agente: `'user'`, `'project'` o `'local'` |
1258| `effort` | No | Livello di sforzo di ragionamento per questo agente. Accetta un livello con nome o un numero intero |1260| `effort` | No | Livello di sforzo di ragionamento per questo agente. Accetta un livello con nome o un numero intero |
1259| `permissionMode` | No | Modalità di permesso per l'esecuzione degli strumenti all'interno di questo agente. Le [regole di ereditarietà dei subagent](https://code.claude.com/docs/it/agent-sdk/permissions.md#available-modes) stabiliscono quando si applica. Consulta [`PermissionMode`](#permissionmode) |1261| `permissionMode` | No | Modalità di permesso per l'esecuzione degli strumenti all'interno di questo agente. Le [regole di ereditarietà dei subagent](https://code.claude.com/docs/it/agent-sdk/permissions.md#available-modes) determinano quando si applica. Vedi [`PermissionMode`](#permissionmode) |
1260| `criticalSystemReminder_EXPERIMENTAL` | No | Sperimentale: promemoria critico aggiunto al prompt di sistema |1262| `criticalSystemReminder_EXPERIMENTAL` | No | Sperimentale: promemoria critico aggiunto al prompt di sistema |
1261 1263
1262### `AgentMcpServerSpec`1264### `AgentMcpServerSpec`
1263 1265
1264Specifica i server MCP disponibili per un subagent. Può essere il nome di un server (stringa che fa riferimento a un server della configurazione `mcpServers` del genitore) oppure un record di configurazione inline dei server che associa i nomi dei server alle relative configurazioni.1266Specifica i server MCP disponibili per un subagent. Può essere un nome di server (stringa che fa riferimento a un server dalla configurazione `mcpServers` del genitore) o un record di configurazione del server inline che associa i nomi dei server alle configurazioni.
1265 1267
1266```typescript theme={null}1268```typescript theme={null}
1267type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;1269type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;
1285 1287
1286#### Comportamento predefinito1288#### Comportamento predefinito
1287 1289
1288Quando `settingSources` è omesso o `undefined`, `query()` carica le stesse impostazioni del filesystem della CLI di Claude Code: utente, progetto e locali. Consulta [Cosa settingSources non controlla](https://code.claude.com/docs/it/agent-sdk/claude-code-features.md#what-settingsources-does-not-control) per gli input che vengono letti indipendentemente da questa opzione e per sapere come disabilitarli.1290Quando `settingSources` è omesso o `undefined`, `query()` carica le stesse impostazioni dal filesystem della CLI di Claude Code: utente, progetto e locali. Consulta [Cosa non controlla settingSources](https://code.claude.com/docs/it/agent-sdk/claude-code-features.md#what-settingsources-does-not-control) per gli input che vengono letti indipendentemente da questa opzione e per come disattivarli.
1289 1291
1290#### Perché usare settingSources1292#### Perché usare settingSources
1291 1293
1292**Disabilitare le impostazioni del filesystem:**1294**Disattivare le impostazioni dal filesystem:**
1293 1295
1294```typescript theme={null}1296```typescript theme={null}
1295import { query } from "@anthropic-ai/claude-agent-sdk";1297import { query } from "@anthropic-ai/claude-agent-sdk";
1315});1317});
1316```1318```
1317 1319
1318Per caricare le istruzioni di progetto di CLAUDE.md, includi `"project"` in `settingSources`. Consulta [Modificare i prompt di sistema](https://code.claude.com/docs/it/agent-sdk/modifying-system-prompts.md#claude-md-files-for-project-level-instructions) per capire come il caricamento di CLAUDE.md interagisce con le opzioni del prompt di sistema.1320Per caricare le istruzioni di progetto di CLAUDE.md, includi `"project"` in `settingSources`. Consulta [Modificare i prompt di sistema](https://code.claude.com/docs/it/agent-sdk/modifying-system-prompts.md#claude-md-files-for-project-level-instructions) per sapere come il caricamento di CLAUDE.md interagisce con le opzioni del prompt di sistema.
1319 1321
1320#### Precedenza delle impostazioni1322#### Precedenza delle impostazioni
1321 1323
13252. Impostazioni di progetto (`.claude/settings.json`)13272. Impostazioni di progetto (`.claude/settings.json`)
13263. Impostazioni utente (`~/.claude/settings.json`)13283. Impostazioni utente (`~/.claude/settings.json`)
1327 1329
1328Le opzioni programmatiche come `agents`, `allowedTools` e `settings` hanno la precedenza sulle impostazioni del filesystem utente, di progetto e locali. Le impostazioni delle policy gestite hanno la precedenza sulle opzioni programmatiche.1330Le opzioni programmatiche come `agents`, `allowedTools` e `settings` hanno la precedenza sulle impostazioni utente, di progetto e locali del filesystem. Le impostazioni delle policy gestite hanno la precedenza sulle opzioni programmatiche.
1329 1331
1330### `PermissionMode`1332### `PermissionMode`
1331 1333
1343 1345
1344Tipo di funzione di permesso personalizzata per controllare l'uso degli strumenti.1346Tipo di funzione di permesso personalizzata per controllare l'uso degli strumenti.
1345 1347
1346La funzione è il sostituto nell'SDK della richiesta di permesso interattiva: viene invocata solo quando il [flusso di valutazione dei permessi](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated) si risolve in una richiesta di conferma. Le chiamate agli strumenti già approvate da una voce di `allowedTools`, da una regola allow nelle impostazioni o dalla modalità di permesso, come `acceptEdits` o `bypassPermissions`, non la invocano mai. Per controllare ogni chiamata a uno strumento, usa invece un [hook `PreToolUse`](https://code.claude.com/docs/it/agent-sdk/hooks).1348La funzione è il sostituto nell'SDK della richiesta di permesso interattiva: viene invocata solo quando il [flusso di valutazione dei permessi](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated) si risolve in una richiesta. Le chiamate agli strumenti già approvate da una voce di `allowedTools`, da una regola di autorizzazione nelle impostazioni o dalla modalità di permesso, come `acceptEdits` o `bypassPermissions`, non la invocano mai. Per controllare ogni chiamata a uno strumento, usa invece un [hook `PreToolUse`](https://code.claude.com/docs/it/agent-sdk/hooks).
1347 1349
1348Una regola allow non pre-approva le [azioni che nessuna modalità approva automaticamente](https://code.claude.com/docs/it/permission-modes.md#actions-no-mode-auto-approves); consulta [Come vengono valutati i permessi](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated) per sapere quali di esse raggiungono la callback e cosa succede in modalità `dontAsk` e `auto`.1350Una regola di autorizzazione non pre-approva le [azioni che nessuna modalità approva automaticamente](https://code.claude.com/docs/it/permission-modes.md#actions-no-mode-auto-approves); consulta [Come vengono valutati i permessi](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated) per sapere quali di esse raggiungono la callback e cosa succede in modalità `dontAsk` e `auto`.
1349 1351
1350```typescript theme={null}1352```typescript theme={null}
1351type CanUseTool = (1353type CanUseTool = (
1369| Opzione | Tipo | Descrizione |1371| Opzione | Tipo | Descrizione |
1370| :- | :- | :- |1372| :- | :- | :- |
1371| `signal` | `AbortSignal` | Segnalato se l'operazione deve essere interrotta |1373| `signal` | `AbortSignal` | Segnalato se l'operazione deve essere interrotta |
1372| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | Aggiornamenti dei permessi suggeriti affinché all'utente non venga chiesto di nuovo per questo strumento. Le richieste di conferma di Bash includono un suggerimento con la [destinazione](#permissionupdatedestination) `localSettings`, quindi restituirlo in `updatedPermissions` scrive la regola in `.claude/settings.local.json` e la mantiene tra le sessioni. |1374| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | Aggiornamenti dei permessi suggeriti in modo che all'utente non venga chiesto di nuovo per questo strumento. Le richieste di Bash includono un suggerimento con la [destinazione](#permissionupdatedestination) `localSettings`, quindi restituirlo in `updatedPermissions` scrive la regola in `.claude/settings.local.json` e persiste tra le sessioni. |
1373| `blockedPath` | `string` | Il percorso del file che ha attivato la richiesta di permesso, se applicabile |1375| `blockedPath` | `string` | Il percorso del file che ha attivato la richiesta di permesso, se applicabile |
1374| `mcpServer` | `{ name: string; source: string }` | Per uno strumento `mcp__*`, il server MCP che lo fornisce e la provenienza della definizione di quel server, con i campi di [`McpServerProvenance`](#mcpserverprovenance). Assente per gli altri strumenti. Richiede Agent SDK v0.3.274 o successiva |1376| `mcpServer` | `{ name: string; source: string }` | Per uno strumento `mcp__*`, il server MCP che lo fornisce e da dove proviene la definizione di quel server, con i campi di [`McpServerProvenance`](#mcpserverprovenance). Assente per gli altri strumenti. Richiede Agent SDK v0.3.274 o successiva |
1375| `decisionReason` | `string` | Spiega perché è stata attivata questa richiesta di permesso |1377| `decisionReason` | `string` | Spiega perché è stata attivata questa richiesta di permesso |
1376| `defaultToNo` | `boolean` | Quando è `true`, un singolo tasto premuto per errore non deve approvare questa richiesta: apri la tua richiesta di conferma sull'opzione di rifiuto, non preselezionare l'approvazione e non offrire scorciatoie di approvazione a un solo tasto. Richiede Agent SDK v0.3.268 o successiva |1378| `defaultToNo` | `boolean` | Quando è `true`, un singolo tasto premuto per errore non deve approvare questa richiesta: apri la tua richiesta sull'opzione di rifiuto, non preselezionare l'approvazione e non offrire scorciatoie di approvazione con un solo tasto. Richiede Agent SDK v0.3.268 o successiva |
1377| `suppressAlwaysAllowRule` | `boolean` | Quando è `true`, non offrire una scelta persistente "consenti sempre" per questa richiesta. Richiede Agent SDK v0.3.268 o successiva |1379| `suppressAlwaysAllowRule` | `boolean` | Quando è `true`, non offrire una scelta persistente di autorizzazione permanente per questa richiesta. Richiede Agent SDK v0.3.268 o successiva |
1378| `toolUseID` | `string` | Identificatore univoco per questa specifica chiamata allo strumento all'interno del messaggio dell'assistente |1380| `toolUseID` | `string` | Identificatore univoco di questa specifica chiamata allo strumento all'interno del messaggio dell'assistente |
1379| `agentID` | `string` | Se in esecuzione all'interno di un subagent, l'ID del subagent |1381| `agentID` | `string` | Se in esecuzione all'interno di un subagent, l'ID del subagent |
1380| `requestId` | `string` | Il `request_id` dell'envelope `control_request`. Una `control_response` che la tua applicazione invia al di fuori dell'SDK, come una HTTP POST firmata, deve riportare questo valore affinché il processo di Claude Code possa associare la risposta alla richiesta |1382| `requestId` | `string` | Il `request_id` dell'envelope `control_request`. Una `control_response` che la tua applicazione invia al di fuori dell'SDK, come una richiesta HTTP POST firmata, deve riportare questo valore affinché il processo di Claude Code possa associare la risposta alla richiesta |
1381 1383
1382La callback normalmente risolve la richiesta restituendo un [`PermissionResult`](#permissionresult), che l'SDK riscrive sul proprio trasporto come `control_response`. Restituisci `null` solo quando la tua applicazione ha già inviato la `control_response` per questa richiesta tramite il proprio canale, riportando `requestId`; l'SDK salta quindi la scrittura della risposta sul proprio trasporto. Restituire `null` in qualsiasi altro caso lascia la chiamata allo strumento bloccata indefinitamente, perché nessuna `control_response` viene mai inviata e le richieste di permesso non vanno in timeout.1384La callback normalmente risolve la richiesta restituendo un [`PermissionResult`](#permissionresult), che l'SDK riscrive sul proprio trasporto come `control_response`. Restituisci `null` solo quando la tua applicazione ha già inviato la `control_response` per questa richiesta tramite il proprio canale, riportando `requestId`; l'SDK quindi salta la scrittura della risposta sul proprio trasporto. Restituire `null` in qualsiasi altro caso lascia la chiamata allo strumento bloccata indefinitamente, perché nessuna `control_response` viene mai inviata e le richieste di permesso non vanno in timeout.
1383 1385
1384L'opzione `requestId` e il valore di ritorno `null` richiedono Claude Code v2.1.199 o successiva.1386L'opzione `requestId` e il valore restituito `null` richiedono Claude Code v2.1.199 o successiva.
1385 1387
1386### `PermissionResult`1388### `PermissionResult`
1387 1389
1403 };1405 };
1404```1406```
1405 1407
1408Se restituisci `allow` con più di 4.096 elementi in `updatedPermissions`, Claude Code considera il risultato non valido e nega la chiamata allo strumento. Ogni aggiornamento conta come un elemento, così come ogni voce del suo elenco `rules` o `directories`. Il messaggio di rifiuto termina con `updatedPermissions may hold at most 4096 updates, rules and directories in all`. Perché la chiamata venga consentita, restituisci 4.096 elementi o meno.
1409
1406### `ToolConfig`1410### `ToolConfig`
1407 1411
1408Configurazione del comportamento degli strumenti integrati.1412Configurazione del comportamento degli strumenti integrati.
1417 1421
1418| Campo | Tipo | Descrizione |1422| Campo | Tipo | Descrizione |
1419| :- | :- | :- |1423| :- | :- | :- |
1420| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | Abilita il campo `preview` nelle opzioni di [`AskUserQuestion`](https://code.claude.com/docs/it/agent-sdk/user-input#question-format) e ne imposta il formato del contenuto. Quando non è impostato, Claude non emette anteprime |1424| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | Attiva il campo `preview` nelle opzioni di [`AskUserQuestion`](https://code.claude.com/docs/it/agent-sdk/user-input#question-format) e ne imposta il formato del contenuto. Se non impostato, Claude non emette anteprime |
1421 1425
1422### `McpServerConfig`1426### `McpServerConfig`
1423 1427
1464 1468
1465#### `McpSdkServerConfigWithInstance`1469#### `McpSdkServerConfigWithInstance`
1466 1470
1467La configurazione per un server MCP in-process, creato da [`createSdkMcpServer()`](#createsdkmcpserver) ed eseguito all'interno del processo della tua applicazione. È l'oggetto restituito da `createSdkMcpServer()`, più un elenco `tools` facoltativo di voci [`McpServerToolPolicy`](#mcpservertoolpolicy) che aggiungi tu stesso. Per richiedere l'approvazione per le chiamate a uno degli strumenti del server, o per negarle, aggiungi una voce che indichi lo strumento.1471Configurazione per un server MCP in-process. È ciò che restituisce [`createSdkMcpServer()`](#createsdkmcpserver), più un elenco `tools` opzionale di voci [`McpServerToolPolicy`](#mcpservertoolpolicy) che aggiungi tu.
1468 1472
1469```typescript theme={null}1473```typescript theme={null}
1470type McpSdkServerConfigWithInstance = {1474type McpSdkServerConfigWithInstance = {
1476};1480};
1477```1481```
1478 1482
1479Per impostare una policy, espandi l'oggetto restituito da `createSdkMcpServer()` in un nuovo oggetto in `mcpServers` e aggiungi l'elenco `tools` a quel nuovo oggetto. L'opzione `tools` di `createSdkMcpServer()` stessa è un elenco diverso, che contiene le definizioni degli strumenti e non accetta voci di policy. L'elenco delle policy richiede Agent SDK v0.3.301 o successiva, e [`McpServerToolPolicy`](#mcpservertoolpolicy) descrive cosa fa ciascun valore di `permission_policy`.1483Per richiedere l'approvazione delle chiamate a uno degli strumenti del server, o per negarle, aggiungi una voce di policy che nomina lo strumento. Espandi ciò che restituisce `createSdkMcpServer()` in un oggetto sotto `mcpServers` e inserisci la voce in un elenco `tools` su quell'oggetto, perché l'opzione `tools` della funzione accetta definizioni di strumenti e non voci di policy. L'elenco di policy richiede Agent SDK v0.3.301 o successiva, e [`McpServerToolPolicy`](#mcpservertoolpolicy) descrive cosa fa ciascun valore di `permission_policy`.
1480 1484
1481Questo esempio pre-approva ogni strumento del server `records` con un carattere jolly in `allowedTools`, quindi contrassegna `delete_record` come `always_ask` affinché le chiamate a esso vadano comunque a `canUseTool`. Con l'annotazione `destructiveHint: true`, la chiamata raggiunge comunque la callback se la sessione è in esecuzione in modalità `auto`, dove altrimenti il [classificatore](https://code.claude.com/docs/it/permission-modes.md#eliminate-prompts-with-auto-mode) della modalità auto potrebbe approvarla.1485In questo script, un carattere jolly in `allowedTools` pre-approva ogni strumento del server `records`, ma `delete_record` è contrassegnato come `always_ask`, quindi le chiamate a esso arrivano comunque a `canUseTool`. Con l'annotazione `destructiveHint: true`, la chiamata raggiunge la callback anche se la sessione viene eseguita in modalità `auto`, dove il [classificatore](https://code.claude.com/docs/it/permission-modes.md#eliminate-prompts-with-auto-mode) della modalità auto potrebbe altrimenti approvarla.
1482 1486
1483```typescript theme={null}1487```typescript theme={null}
1484import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";1488import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
1517}1521}
1518```1522```
1519 1523
1520Quando Claude chiama lo strumento, lo script stampa `Approval requested for mcp__records__delete_record` prima che lo strumento `delete_record` venga eseguito, anche se la voce `allowedTools` avrebbe altrimenti approvato la chiamata.1524Quando Claude chiama `delete_record`, lo script stampa `Approval requested for mcp__records__delete_record`.
1521 1525
1522Per modificare o rimuovere la policy di uno strumento mentre la sessione è in esecuzione, passa la configurazione del server con un nuovo valore `tools` a [`setMcpServers()`](#mcpsetserversresult). Il valore `tools` che passi ha effetto dalla successiva chiamata di Claude agli strumenti di quel server:1526Per modificare o rimuovere la policy di uno strumento mentre la sessione è in esecuzione, passa la configurazione del server con un nuovo valore `tools` a [`setMcpServers()`](#mcpsetserversresult). Il valore `tools` che passi ha effetto a partire dalla successiva chiamata di Claude agli strumenti di quel server:
1523 1527
1524* **Un elenco con voci**: le voci sostituiscono le policy correnti1528* **Un elenco con voci**: le voci sostituiscono le policy correnti
1525* **Un elenco vuoto**: ogni policy del server viene cancellata1529* **Un elenco vuoto**: tutte le policy del server vengono cancellate
1526* **Nessuna chiave `tools`**: le policy correnti restano1530* **Nessuna chiave `tools`**: le policy correnti restano
1527 1531
1528Includi in quella chiamata gli altri tuoi server in-process e qualsiasi server aggiunto da una precedente chiamata a `setMcpServers()`, altrimenti la chiamata li disconnette.1532Includi in quella chiamata gli altri tuoi server in-process e qualsiasi server aggiunto da una precedente chiamata a `setMcpServers()`, altrimenti la chiamata li disconnette.
1529 1533
1530#### `McpServerToolPolicy`1534#### `McpServerToolPolicy`
1531 1535
1532Una voce nell'elenco `tools` di un [`McpSdkServerConfigWithInstance`](#mcpsdkserverconfigwithinstance), che indica uno degli strumenti del server e imposta la policy dei permessi per le chiamate a quello strumento. L'elenco richiede Agent SDK v0.3.301 o successiva e Claude Code v2.1.301 o successiva. Un eseguibile di Claude Code precedente, come un eseguibile a cui punti con `pathToClaudeCodeExecutable`, ignora l'elenco. In quel caso `always_ask` e `always_deny` non vengono applicati, e ogni chiamata passa attraverso il [flusso dei permessi](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated).1536Una voce nell'elenco `tools` di un [`McpSdkServerConfigWithInstance`](#mcpsdkserverconfigwithinstance), che nomina uno degli strumenti del server e imposta la policy di permesso per le chiamate a quello strumento. L'elenco richiede Agent SDK v0.3.301 o successiva e Claude Code v2.1.301 o successiva. Un eseguibile di Claude Code precedente, come un eseguibile a cui punti con `pathToClaudeCodeExecutable`, ignora l'elenco. In quel caso `always_ask` e `always_deny` non vengono applicati e ogni chiamata passa attraverso il [flusso dei permessi](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated).
1533 1537
1534```typescript theme={null}1538```typescript theme={null}
1535type McpServerToolPolicy = {1539type McpServerToolPolicy = {
1541 1545
1542| Campo | Tipo | Descrizione |1546| Campo | Tipo | Descrizione |
1543| :- | :- | :- |1547| :- | :- | :- |
1544| `name` | `string` | Il nome semplice dello strumento così come passato a [`tool()`](#tool), senza il prefisso `mcp__<server>__` |1548| `name` | `string` | Il nome semplice dello strumento come passato a [`tool()`](#tool), senza il prefisso `mcp__<server>__` |
1545| `permission_policy` | `'always_allow' \| 'always_ask' \| 'always_deny'` | La policy di approvazione per le chiamate allo strumento, [`always_ask` o `always_deny`](#permission-policy-values). `always_allow` viene ignorato su un server in-process: per pre-approvare uno strumento, elencalo invece in [`allowedTools`](#options) |1549| `permission_policy` | `'always_allow' \| 'always_ask' \| 'always_deny'` | La policy di approvazione per le chiamate allo strumento, [`always_ask` o `always_deny`](#permission-policy-values). `always_allow` viene ignorato su un server in-process: per pre-approvare uno strumento, elencalo invece in [`allowedTools`](#options) |
1546| `org_max_permission` | `'allow' \| 'ask' \| 'blocked'` | Un limite massimo per strumento impostato da un amministratore dell'organizzazione. Ignorato su un server in-process, quindi lascialo non impostato |1550| `org_max_permission` | `'allow' \| 'ask' \| 'blocked'` | Un limite massimo per strumento impostato da un amministratore dell'organizzazione. Ignorato su un server in-process, quindi lascialo non impostato |
1547 1551
1549 1553
1550Scegli `always_ask` per approvare tu stesso ogni chiamata, oppure `always_deny` per bloccare completamente lo strumento:1554Scegli `always_ask` per approvare tu stesso ogni chiamata, oppure `always_deny` per bloccare completamente lo strumento:
1551 1555
1552* **`always_ask`**: ogni chiamata allo strumento [richiede approvazione](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated), anche se una voce `allowedTools` o una regola allow la copre. La chiamata va alla tua callback `canUseTool` o allo strumento [`permissionPromptToolName`](#options), a meno che non venga risolta prima. Un [mod](https://code.claude.com/docs/it/plugins/mods/overview.md) in un plugin che carichi [può approvarla prima](https://code.claude.com/docs/it/permissions.md#precedence-among-rules-hooks-and-mods). Altrimenti, in modalità `dontAsk` viene negata, e nelle [modalità `auto`, `plan` e `bypassPermissions`](#permission-modes-that-can-approve-an-always_ask-call) può essere approvata prima di raggiungere la tua callback1556* **`always_ask`**: ogni chiamata allo strumento [richiede l'approvazione](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated), anche se una voce di `allowedTools` o una regola di autorizzazione la copre. La chiamata arriva alla tua callback `canUseTool` o allo strumento [`permissionPromptToolName`](#options), a meno che non venga risolta prima. Un [mod](https://code.claude.com/docs/it/plugins/mods/overview.md) in un plugin che carichi [può approvarla prima](https://code.claude.com/docs/it/permissions.md#precedence-among-rules-hooks-and-mods). Altrimenti, in modalità `dontAsk` viene negata, e nelle [modalità `auto`, `plan` e `bypassPermissions`](#permission-modes-that-can-approve-an-always_ask-call) può essere approvata prima di raggiungere la tua callback
1553* **`always_deny`**: una chiamata allo strumento [viene negata](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated) in ogni modalità di permesso, incluso `bypassPermissions`, ma un mod in un plugin che carichi [può comunque approvarla](https://code.claude.com/docs/it/permissions.md#precedence-among-rules-hooks-and-mods)1557* **`always_deny`**: una chiamata allo strumento [viene negata](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated) in ogni modalità di permesso, incluso `bypassPermissions`, ma un mod in un plugin che carichi [può comunque approvarla](https://code.claude.com/docs/it/permissions.md#precedence-among-rules-hooks-and-mods)
1554 1558
1555Se non passi né `canUseTool` né `permissionPromptToolName`, oppure imposti [`permissionPrompts`](#options) su `'none'`, una chiamata `always_ask` che non viene risolta prima viene negata, a meno che un [hook `PermissionRequest`](https://code.claude.com/docs/it/hooks#permissionrequest) non la consenta.1559Se non passi né `canUseTool` né `permissionPromptToolName`, oppure imposti [`permissionPrompts`](#options) su `'none'`, una chiamata `always_ask` che non viene risolta prima viene negata, a meno che un [hook `PermissionRequest`](https://code.claude.com/docs/it/hooks#permissionrequest) non la consenta.
1556 1560
1557##### Modalità di permesso che possono approvare una chiamata `always_ask`1561##### Modalità di permesso che possono approvare una chiamata `always_ask`
1558 1562
1559Nelle modalità `auto`, `plan` e `bypassPermissions`, una chiamata a uno strumento contrassegnato come [`always_ask`](#permission-policy-values) può essere approvata prima di raggiungere la tua callback `canUseTool`. Trova la modalità della tua sessione in questo elenco per vedere quando avviene tale approvazione e cosa impostare affinché la chiamata raggiunga comunque la tua callback:1563Nelle modalità `auto`, `plan` e `bypassPermissions`, una chiamata a uno strumento contrassegnato come [`always_ask`](#permission-policy-values) può essere approvata prima di raggiungere la tua callback `canUseTool`.
1560 1564
1561* **`auto`**: il [classificatore](https://code.claude.com/docs/it/permission-modes.md#eliminate-prompts-with-auto-mode) della modalità auto esamina la chiamata e può consentirla. Per fare in modo che ogni chiamata raggiunga la tua callback in modalità `auto`, imposta `destructiveHint: true` nelle [annotazioni](#toolannotations) dello strumento1565* **`auto`**: il [classificatore](https://code.claude.com/docs/it/permission-modes.md#eliminate-prompts-with-auto-mode) della modalità auto esamina la chiamata e può consentirla. Per far sì che ogni chiamata raggiunga la tua callback in modalità `auto`, imposta `destructiveHint: true` nelle [annotazioni](#toolannotations) dello strumento
1562* **`plan`**: finché la [modalità auto è disponibile](https://code.claude.com/docs/it/permission-modes.md#eliminate-prompts-with-auto-mode) per la sessione, le chiamate a uno strumento `always_ask` annotato con `readOnlyHint: true` vanno al classificatore della modalità auto, che può consentirle. Le chiamate ad altri strumenti `always_ask` raggiungono la tua callback. Per fare in modo che anche le chiamate di uno strumento di sola lettura raggiungano la tua callback, aggiungi `destructiveHint: true` alle annotazioni di quello strumento insieme a `readOnlyHint: true`. In alternativa, imposta [`useAutoModeDuringPlan`](https://code.claude.com/docs/it/settings-reference#useautomodeduringplan) su `false`, il che disattiva il classificatore durante la pianificazione1566* **`plan`**: finché la [modalità auto è disponibile](https://code.claude.com/docs/it/permission-modes.md#eliminate-prompts-with-auto-mode) per la sessione, le chiamate a uno strumento `always_ask` annotato con `readOnlyHint: true` vanno al classificatore della modalità auto, che può consentirle. Le chiamate ad altri strumenti `always_ask` raggiungono la tua callback. Per far sì che anche le chiamate di uno strumento di sola lettura raggiungano la tua callback, aggiungi `destructiveHint: true` alle annotazioni di quello strumento insieme a `readOnlyHint: true`. In alternativa, imposta [`useAutoModeDuringPlan`](https://code.claude.com/docs/it/settings-reference#useautomodeduringplan) su `false`, che disattiva il classificatore durante la pianificazione
1563* **`bypassPermissions`**: quando la variabile d'ambiente [`CLAUDE_CODE_REMOTE`](https://code.claude.com/docs/it/env-vars#variables) è `true`, come avviene in una [sessione cloud](https://code.claude.com/docs/it/claude-code-on-the-web.md), la chiamata viene approvata senza la tua callback, indipendentemente dalle annotazioni dello strumento. In qualsiasi altro contesto la chiamata raggiunge la tua callback. Per fare in modo che raggiunga la tua callback anche in una sessione cloud, esegui invece la sessione in modalità `default` o `acceptEdits`1567* **`bypassPermissions`**: quando la variabile d'ambiente [`CLAUDE_CODE_REMOTE`](https://code.claude.com/docs/it/env-vars#variables) è `true`, come avviene in una [sessione cloud](https://code.claude.com/docs/it/claude-code-on-the-web.md), la chiamata viene approvata senza la tua callback, indipendentemente dalle annotazioni dello strumento. Altrove la chiamata raggiunge la tua callback. Per farla arrivare alla tua callback anche in una sessione cloud, esegui invece la sessione in modalità `default` o `acceptEdits`
1564 1568
1565Imposta esplicitamente `destructiveHint` su `true` nelle modalità `auto` e `plan`. Per le chiamate `always_ask`, Claude Code interpreta un `destructiveHint` non impostato come `false`, anche se il valore predefinito indicato in [`ToolAnnotations`](#toolannotations) è `true`.1569Imposta esplicitamente `destructiveHint` su `true` nelle modalità `auto` e `plan`. Per le chiamate `always_ask`, Claude Code interpreta un `destructiveHint` non impostato come `false`, anche se il valore predefinito indicato in [`ToolAnnotations`](#toolannotations) è `true`.
1566 1570
1590| :- | :- | :- |1594| :- | :- | :- |
1591| `type` | `'local'` | Deve essere `'local'` (attualmente sono supportati solo i plugin locali) |1595| `type` | `'local'` | Deve essere `'local'` (attualmente sono supportati solo i plugin locali) |
1592| `path` | `string` | Percorso della directory del plugin. Un percorso relativo viene risolto rispetto all'opzione [`cwd`](#options) all'avvio della sessione. Il percorso deve essere assoluto quando carichi il plugin a sessione in corso con [`addPlugins`](#load-more-plugin-folders-with-addplugins) |1596| `path` | `string` | Percorso della directory del plugin. Un percorso relativo viene risolto rispetto all'opzione [`cwd`](#options) all'avvio della sessione. Il percorso deve essere assoluto quando carichi il plugin a sessione in corso con [`addPlugins`](#load-more-plugin-folders-with-addplugins) |
1593| `skipMcpDiscovery` | `boolean` | Quando è `true`, l'SDK carica skill, hook, agenti e comandi da questo plugin ma non legge il suo `.mcp.json` né i `mcpServers` del manifest. Impostalo quando è la tua applicazione a gestire le connessioni MCP del plugin. |1597| `skipMcpDiscovery` | `boolean` | Quando è `true`, l'SDK carica skill, hook, agenti e comandi da questo plugin ma non legge il suo `.mcp.json` né i `mcpServers` del manifest. Impostalo quando la tua applicazione gestisce le connessioni MCP del plugin. |
1594 1598
1595**Esempio:**1599**Esempio:**
1596 1600
1601];1605];
1602```1606```
1603 1607
1604Per informazioni complete sulla creazione e sull'uso dei plugin, consulta [Plugin](https://code.claude.com/docs/it/agent-sdk/plugins.md).1608Per informazioni complete sulla creazione e l'uso dei plugin, consulta [Plugin](https://code.claude.com/docs/it/agent-sdk/plugins.md).
1605 1609
1606## Tipi di messaggio1610## Tipi di messaggio
1607 1611
1692 1696
1693`aborted` è `true` quando un'interruzione o un annullamento ha troncato il messaggio dell'assistente prima del completamento del flusso: il messaggio non ha `stop_reason` e il contenuto può terminare a metà parola. Il campo è assente sui messaggi completati normalmente. Richiede Agent SDK v0.3.214 o successivo.1697`aborted` è `true` quando un'interruzione o un annullamento ha troncato il messaggio dell'assistente prima del completamento del flusso: il messaggio non ha `stop_reason` e il contenuto può terminare a metà parola. Il campo è assente sui messaggi completati normalmente. Richiede Agent SDK v0.3.214 o successivo.
1694 1698
1695`agent_id` identifica il subagent che ha prodotto il messaggio ed è assente nei messaggi del thread principale. Il valore è uguale al `task_id` nel [`task_started`](#sdktaskstartedmessage) di quel subagent e negli altri eventi di attività, e non cambia quando il subagent viene [ripreso](https://code.claude.com/docs/it/agent-sdk/subagents.md#resume-subagents). Il campo richiede Agent SDK v0.3.292 o successiva.1699`agent_id` identifica il subagent che ha prodotto il messaggio ed è assente nei messaggi del thread principale. Il valore è uguale al `task_id` presente nel [`task_started`](#sdktaskstartedmessage) di quel subagent e negli altri eventi delle attività, e non cambia quando il subagent viene [ripreso](https://code.claude.com/docs/it/agent-sdk/subagents.md#resume-subagents). Nei messaggi di un [subagent annidato](https://code.claude.com/docs/it/sub-agents.md#let-subagents-spawn-their-own-subagents), indica il subagent annidato, non il subagent che lo ha generato. Il campo richiede Agent SDK v0.3.292 o successiva.
1696 1700
1697Associa i messaggi di un subagent ai suoi eventi di attività tramite `agent_id`, anziché abbinare il `parent_tool_use_id` di un messaggio con il `tool_use_id` di un evento di attività. Quando una chiamata a uno strumento riprende il subagent, gli eventi di attività riportano il `tool_use_id` di quella chiamata, mentre i messaggi mantengono il `parent_tool_use_id` della chiamata allo strumento che ha avviato per primo il subagent, quindi i due non corrispondono più.1701Associa i messaggi di un subagent ai suoi eventi di attività tramite `agent_id`, anziché abbinare il `parent_tool_use_id` di un messaggio con il `tool_use_id` di un evento di attività. Quando una chiamata a uno strumento riprende il subagent, gli eventi di attività riportano il `tool_use_id` di quella chiamata, mentre i messaggi mantengono il `parent_tool_use_id` della chiamata allo strumento che ha avviato per primo il subagent, quindi i due non corrispondono più.
1698 1702
3273 3277
3274### Agent3278### Agent
3275 3279
3276**Nome del tool:** `Agent`. Il nome precedente `Task` è ancora accettato come alias, e l'array `tools` nel messaggio di inizializzazione [`SDKSystemMessage`](#sdksystemmessage) attualmente elenca questo tool come `Task` per compatibilità all'indietro.3280**Nome dello strumento:** `Agent`. Il nome precedente `Task` è ancora accettato come alias quando questo strumento è disponibile per la sessione.
3281
3282L'array `tools` nel messaggio di inizializzazione [`SDKSystemMessage`](#sdksystemmessage) elenca questo strumento come `Task` per compatibilità all'indietro.
3277 3283
3278> [!NOTE]3284> [!NOTE]
3279>3285>
4010 4016
4011### Agent4017### Agent
4012 4018
4013**Nome dello strumento:** `Agent`. Il nome precedente `Task` è ancora accettato come alias, e l'array `tools` nel messaggio di inizializzazione [`SDKSystemMessage`](#sdksystemmessage) attualmente elenca questo strumento come `Task` per compatibilità con le versioni precedenti.4019**Nome dello strumento:** `Agent`. Il nome precedente `Task` è ancora accettato come alias quando questo strumento è disponibile per la sessione.
4014 4020
4015```typescript theme={null}4021```typescript theme={null}
4016type AgentOutput =4022type AgentOutput =
5210 5216
5211#### Quando il `_meta.ui` di uno strumento contiene solo `visibility`5217#### Quando il `_meta.ui` di uno strumento contiene solo `visibility`
5212 5218
5213Se il tuo server dichiara `ui.resourceUri` per uno strumento ma il `_meta.ui` che la tua applicazione riceve contiene solo `visibility`, l'oggetto `ui` inviato dal server non ha superato uno dei controlli di Claude Code. Claude Code controlla `ui` e `ui/resourceUri` separatamente, quindi una chiave può raggiungere la tua applicazione anche quando l'altra non supera i controlli. Confronta il `_meta` nella risposta `tools/list` del tuo server con i controlli per ciascuna chiave:5219Se il tuo server dichiara `ui.resourceUri` per uno strumento ma il `_meta.ui` che la tua applicazione riceve contiene solo `visibility`, l'oggetto `ui` inviato dal server non ha superato uno dei controlli di Claude Code. Confronta il `_meta` nella risposta `tools/list` del tuo server con i controlli per ciascuna chiave:
5214 5220
5215* **`ui`**: raggiunge la tua applicazione invariato, inclusi eventuali membri diversi da `resourceUri` e `visibility`, se tutti e tre i controlli vengono superati:5221* **`ui`**: raggiunge la tua applicazione invariato, inclusi eventuali membri diversi da `resourceUri` e `visibility`, se tutti e tre i controlli vengono superati:
5216 5222
5553 5559
5554Claude Code consegna questo messaggio, [`SDKHookProgressMessage`](#sdkhookprogressmessage) e [`SDKHookResponseMessage`](#sdkhookresponsemessage) al flusso dei messaggi immediatamente, anche mentre un hook `SessionStart` o `Setup` è ancora in esecuzione durante l'avvio della sessione. Claude Code dalla v2.1.169 alla v2.1.203 consegnava questi messaggi in un unico blocco dopo il completamento di un hook `SessionStart` o `Setup`; la v2.1.204 ha ripristinato la consegna in tempo reale.5560Claude Code consegna questo messaggio, [`SDKHookProgressMessage`](#sdkhookprogressmessage) e [`SDKHookResponseMessage`](#sdkhookresponsemessage) al flusso dei messaggi immediatamente, anche mentre un hook `SessionStart` o `Setup` è ancora in esecuzione durante l'avvio della sessione. Claude Code dalla v2.1.169 alla v2.1.203 consegnava questi messaggi in un unico blocco dopo il completamento di un hook `SessionStart` o `Setup`; la v2.1.204 ha ripristinato la consegna in tempo reale.
5555 5561
5562Se avvii la sessione con [`startup()`](#startup), questi messaggi ti raggiungono una volta che chiami `.query()` e ne iteri il risultato.
5563
5556```typescript theme={null}5564```typescript theme={null}
5557type SDKHookStartedMessage = {5565type SDKHookStartedMessage = {
5558 type: "system";5566 type: "system";
6072| `allowManagedDomainsOnly` | `boolean` | `false` | Solo impostazioni gestite. Quando impostato nelle [impostazioni gestite](https://code.claude.com/docs/it/managed-settings.md), solo le voci `allowedDomains` e le regole di autorizzazione `WebFetch(domain:...)` dalle impostazioni gestite vengono rispettate, e le voci di autorizzazione dalle impostazioni utente, progetto o locali vengono ignorate. Dall'SDK, passalo attraverso l'opzione [`managedSettings`](#options) |6080| `allowManagedDomainsOnly` | `boolean` | `false` | Solo impostazioni gestite. Quando impostato nelle [impostazioni gestite](https://code.claude.com/docs/it/managed-settings.md), solo le voci `allowedDomains` e le regole di autorizzazione `WebFetch(domain:...)` dalle impostazioni gestite vengono rispettate, e le voci di autorizzazione dalle impostazioni utente, progetto o locali vengono ignorate. Dall'SDK, passalo attraverso l'opzione [`managedSettings`](#options) |
6073| `allowLocalBinding` | `boolean` | `false` | Consenti ai processi di associarsi alle porte locali (ad esempio, per i server di sviluppo) |6081| `allowLocalBinding` | `boolean` | `false` | Consenti ai processi di associarsi alle porte locali (ad esempio, per i server di sviluppo) |
6074| `allowUnixSockets` | `string[]` | `[]` | Percorsi dei socket Unix a cui i processi possono accedere (ad esempio, socket Docker) |6082| `allowUnixSockets` | `string[]` | `[]` | Percorsi dei socket Unix a cui i processi possono accedere (ad esempio, socket Docker) |
6075| `allowAllUnixSockets` | `boolean` | `false` | Consenti l'accesso a tutti i socket Unix |6083| `allowAllUnixSockets` | `boolean` | `false` | Consenti l'accesso a tutti i socket Unix e, su Linux, ai socket VM (`AF_VSOCK`) |
6076| `httpProxyPort` | `number` | `undefined` | Porta del proxy HTTP per le richieste di rete |6084| `httpProxyPort` | `number` | `undefined` | Porta del proxy HTTP per le richieste di rete |
6077| `socksProxyPort` | `number` | `undefined` | Porta del proxy SOCKS per le richieste di rete |6085| `socksProxyPort` | `number` | `undefined` | Porta del proxy SOCKS per le richieste di rete |
6078 6086
