17```17```
18 18
19<Note>19<Note>
20 L'SDK raggruppa un binario nativo Claude Code per la tua piattaforma come dipendenza opzionale come `@anthropic-ai/claude-agent-sdk-darwin-arm64`. Non è necessario installare Claude Code separatamente. Se il tuo gestore di pacchetti salta le dipendenze opzionali, l'SDK genera `Native CLI binary for <platform> not found`; imposta [`pathToClaudeCodeExecutable`](#options) su un binario `claude` installato separatamente.20 L'SDK raggruppa un binario nativo Claude Code per la tua piattaforma come dipendenza opzionale come `@anthropic-ai/claude-agent-sdk-darwin-arm64`. La maggior parte delle installazioni non necessita di un'installazione separata di Claude Code. La versione dell'SDK traccia la versione del Claude Code raggruppato. SDK v0.3.191 raggruppa Claude Code v2.1.191, quindi una funzione su questa pagina che richiede una versione di Claude Code necessita della versione SDK con lo stesso numero di patch o successivo. Se il tuo gestore di pacchetti salta le dipendenze opzionali, l'SDK genera `Native CLI binary for <platform>-<arch> not found`; imposta [`pathToClaudeCodeExecutable`](#options) su un binario `claude` installato separatamente.
21
22 Se il tuo gestore di pacchetti non applica il campo `libc` di npm, come non fa Yarn 1.x, ottieni sia i pacchetti della piattaforma glibc che musl su Linux, raddoppiando approssimativamente la dimensione dell'installazione. Su Agent SDK v0.2.141 o successivo, l'SDK avvia comunque la variante corretta. Per recuperare lo spazio in un'immagine contenitore, elimina il pacchetto della piattaforma che non corrisponde al libc dove viene eseguita la tua app; per un runtime glibc su x64, è `rm -rf node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl`. Su una macchina di sviluppo l'eliminazione è temporanea, poiché Yarn reinstalla il pacchetto al prossimo cambio di dipendenza.
21</Note>23</Note>
22 24
23<h3 id="compile-to-a-single-executable">25<h3 id="compile-to-a-single-executable">
24 Compilare in un singolo eseguibile26 Compilare in un singolo eseguibile
25</h3>27</h3>
26 28
27Quando compili la tua applicazione in un eseguibile a file singolo con `bun build --compile`, l'SDK non può risolvere il binario CLI raggruppato in fase di esecuzione. `require.resolve` non funziona all'interno del filesystem virtuale `$bunfs` dell'eseguibile compilato, quindi l'SDK genera `Native CLI binary for <platform> not found`.29Quando compili la tua applicazione in un eseguibile a file singolo con `bun build --compile`, l'SDK non può risolvere il binario CLI raggruppato in fase di esecuzione. `require.resolve` non funziona all'interno del filesystem virtuale `$bunfs` dell'eseguibile compilato, quindi l'SDK genera `Native CLI binary for <platform>-<arch> not found`.
28 30
29Per aggirare questo problema, incorpora il binario della piattaforma come risorsa file, estrailo in un percorso reale all'avvio con `extractFromBunfs()` e passa quel percorso a [`pathToClaudeCodeExecutable`](#options).31Per aggirare questo problema, incorpora il binario della piattaforma come risorsa file, estrailo in un percorso reale all'avvio con `extractFromBunfs()` e passa quel percorso a [`pathToClaudeCodeExecutable`](#options).
30 32
145 description: string,147 description: string,
146 inputSchema: Schema,148 inputSchema: Schema,
147 handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,149 handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,
148 extras?: { annotations?: ToolAnnotations }150 extras?: { annotations?: ToolAnnotations; searchHint?: string; alwaysLoad?: boolean }
149): SdkMcpToolDefinition<Schema>;151): SdkMcpToolDefinition<Schema>;
150```152```
151 153
154</h4>156</h4>
155 157
156| Parametro | Tipo | Descrizione |158| Parametro | Tipo | Descrizione |
157| :------------ | :---------------------------------------------------------------- | :------------------------------------------------------------------------------------ |159| :------------ | :----------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
158| `name` | `string` | Il nome del tool |160| `name` | `string` | Il nome del tool |
159| `description` | `string` | Una descrizione di cosa fa il tool |161| `description` | `string` | Una descrizione di cosa fa il tool |
160| `inputSchema` | `Schema extends AnyZodRawShape` | Schema Zod che definisce i parametri di input del tool (supporta sia Zod 3 che Zod 4) |162| `inputSchema` | `Schema extends AnyZodRawShape` | Schema Zod che definisce i parametri di input del tool (supporta sia Zod 3 che Zod 4) |
161| `handler` | `(args, extra) => Promise<`[`CallToolResult`](#calltoolresult)`>` | Funzione asincrona che esegue la logica del tool |163| `handler` | `(args, extra) => Promise<`[`CallToolResult`](#calltoolresult)`>` | Funzione asincrona che esegue la logica del tool |
162| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)` }` | Annotazioni MCP tool opzionali che forniscono suggerimenti comportamentali ai client |164| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)`; searchHint?: string; alwaysLoad?: boolean }` | Extras opzionali. `annotations` fornisce suggerimenti comportamentali MCP ai client. `searchHint` è una frase di capacità su una riga mostrata nell'elenco dei tool differiti quando [tool search](/docs/it/agent-sdk/tool-search) è attivo. `alwaysLoad: true` mantiene lo schema completo di questo tool nel prompt iniziale invece di differirlo |
163 165
164<h4 id="toolannotations">166<h4 id="toolannotations">
165 `ToolAnnotations`167 `ToolAnnotations`
200function createSdkMcpServer(options: {202function createSdkMcpServer(options: {
201 name: string;203 name: string;
202 version?: string;204 version?: string;
205 instructions?: string;
203 tools?: Array<SdkMcpToolDefinition<any>>;206 tools?: Array<SdkMcpToolDefinition<any>>;
207 alwaysLoad?: boolean;
208 timeout?: number;
204}): McpSdkServerConfigWithInstance;209}): McpSdkServerConfigWithInstance;
205```210```
206 211
209</h4>214</h4>
210 215
211| Parametro | Tipo | Descrizione |216| Parametro | Tipo | Descrizione |
212| :---------------- | :---------------------------- | :-------------------------------------------------------- |217| :--------------------- | :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
213| `options.name` | `string` | Il nome del server MCP |218| `options.name` | `string` | Il nome del server MCP |
214| `options.version` | `string` | Stringa di versione opzionale |219| `options.version` | `string` | Stringa di versione opzionale |
220| `options.instructions` | `string` | Istruzioni del server opzionali, restituite da `initialize` e presentate al modello come un blocco di istruzioni MCP |
215| `options.tools` | `Array<SdkMcpToolDefinition>` | Array di definizioni di tool create con [`tool()`](#tool) |221| `options.tools` | `Array<SdkMcpToolDefinition>` | Array di definizioni di tool create con [`tool()`](#tool) |
222| `options.alwaysLoad` | `boolean` | Quando `true`, ogni tool da questo server rimane nel prompt iniziale e non viene mai differito dietro [tool search](/docs/it/agent-sdk/tool-search). Si combina con `alwaysLoad` per tool in [`tool()`](#tool) |
223| `options.timeout` | `number` | Timeout in millisecondi per le chiamate ai tool di questo server. Claude Code lo applica a questo server al posto di [`MCP_TOOL_TIMEOUT`](/docs/it/env-vars). Passa un numero intero di almeno 1000. Claude Code ignora altri valori. Richiede TypeScript Agent SDK v0.3.248 o successivo |
216 224
217<h3 id="listsessions">225<h3 id="listsessions">
218 `listSessions()`226 `listSessions()`
296</h4>304</h4>
297 305
298| Proprietà | Tipo | Descrizione |306| Proprietà | Tipo | Descrizione |
299| :------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |307| :------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
300| `type` | `"user" \| "assistant"` | Ruolo del messaggio |308| `type` | `"user" \| "assistant"` | Ruolo del messaggio |
301| `uuid` | `string` | Identificatore di messaggio univoco |309| `uuid` | `string` | Identificatore di messaggio univoco |
302| `session_id` | `string` | Sessione a cui appartiene questo messaggio |310| `session_id` | `string` | Sessione a cui appartiene questo messaggio |
303| `message` | `unknown` | Payload del messaggio grezzo dalla trascrizione |311| `message` | `unknown` | Payload del messaggio grezzo dalla trascrizione |
304| `parent_tool_use_id` | `string \| null` | Per i messaggi dei subagent, l'`tool_use_id` della chiamata del tool `Agent` che lo ha generato. `null` per i messaggi della sessione principale e le sessioni precedenti |312| `parent_tool_use_id` | `string \| null` | Per i messaggi dei subagent, l'`tool_use_id` della chiamata del tool `Agent` che lo ha generato. `null` per i messaggi della sessione principale e le sessioni precedenti |
305| `parent_agent_id` | `string \| null` | Per i messaggi da un [subagent annidato](/docs/it/sub-agents#spawn-nested-subagents), l'`agentId` del subagent che lo ha generato. `null` per i messaggi della sessione principale, i messaggi dai subagent di primo livello e le sessioni precedenti. Richiede Claude Code v2.1.202 o successivo |313| `parent_agent_id` | `string \| null` | Per i messaggi da un [subagent annidato](/docs/it/sub-agents#let-subagents-spawn-their-own-subagents), l'`agentId` del subagent che lo ha generato. `null` per i messaggi della sessione principale, i messaggi dai subagent di primo livello e le sessioni precedenti. Richiede Claude Code v2.1.202 o successivo |
306 314
307<h4 id="example-3">315<h4 id="example-3">
308 Esempio316 Esempio
404Risolve le impostazioni effettive di Claude Code per una determinata directory utilizzando lo stesso motore di merge della CLI, senza generare la CLI Claude. Utilizzalo per ispezionare quale configurazione una chiamata `query()` vedrebbe prima di invocarne una.412Risolve le impostazioni effettive di Claude Code per una determinata directory utilizzando lo stesso motore di merge della CLI, senza generare la CLI Claude. Utilizzalo per ispezionare quale configurazione una chiamata `query()` vedrebbe prima di invocarne una.
405 413
406<Note>414<Note>
407 Questa funzione è in fase alpha e la sua API potrebbe cambiare prima della stabilizzazione. Legge le fonti MDM, inclusi plist macOS e Windows HKLM/HKCU, per la parità con l'avvio della CLI, ma non esegue il subprocess `policyHelper` configurato dall'amministratore. Il campo `permissions.defaultMode` viene restituito così com'è da tutti i livelli incluse le impostazioni del progetto. Il filtro di fiducia che la CLI applica prima di onorare i modi di autorizzazione crescenti non viene applicato.415 Questa funzione è in fase alpha e la sua API potrebbe cambiare prima della stabilizzazione.
408</Note>416</Note>
409 417
418Lo snapshot differisce da quello che una sessione `query()` live applica:
419
420* **`policyHelper`**: `resolveSettings()` legge le fonti MDM, inclusi plist macOS e Windows HKLM/HKCU, ma non esegue il subprocess `policyHelper` configurato dall'amministratore.
421* **Impostazioni gestite dal server**: `resolveSettings()` non recupera [impostazioni gestite dal server](/docs/it/server-managed-settings#fetch-and-caching-behavior). Passale come `options.serverManagedSettings` per includerle.
422* **`defaultMode`**: lo snapshot restituisce `permissions.defaultMode` così com'è da ogni livello, quindi può includere i valori `'auto'` e `'bypassPermissions'` dalle impostazioni di progetto e locali, che [una sessione live ignora](/docs/it/permission-modes#which-mode-a-session-starts-in).
423
410```typescript theme={null}424```typescript theme={null}
411function resolveSettings(425function resolveSettings(
412 options?: ResolveSettingsOptions426 options?: ResolveSettingsOptions
420`resolveSettings()` accetta un singolo oggetto di opzioni. Tutti i campi sono opzionali.434`resolveSettings()` accetta un singolo oggetto di opzioni. Tutti i campi sono opzionali.
421 435
422| Parametro | Tipo | Predefinito | Descrizione |436| Parametro | Tipo | Predefinito | Descrizione |
423| :------------------------------ | :------------------------------------ | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |437| :------------------------------ | :------------------------------------ | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
424| `options.cwd` | `string` | `process.cwd()` | Directory per risolvere le impostazioni di progetto e locali relative a |438| `options.cwd` | `string` | `process.cwd()` | Directory per risolvere le impostazioni di progetto e locali relative a |
425| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | Tutte le fonti | Quali fonti del filesystem caricare. Passa `[]` per saltare le impostazioni utente, progetto e locali. Le impostazioni della politica gestita si caricano in tutti i casi. Le impostazioni gestite dal server vengono prese da `serverManagedSettings` quando l'host le passa, o lette dalla cache su disco della CLI altrimenti; lo snapshot non le recupera dalla rete |439| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | Tutte le fonti | Quali fonti del filesystem caricare. Passa `[]` per saltare le impostazioni utente, progetto e locali. La [politica gestita dall'endpoint](/docs/it/managed-settings#delivery-mechanisms) si carica in tutti i casi. `resolveSettings()` include le impostazioni gestite dal server solo quando passi `options.serverManagedSettings` |
426| `options.managedSettings` | `Settings` | `undefined` | Impostazioni della politica restrittiva fornite dall'host di incorporamento. Eliminate quando è presente un livello gestito distribuito dall'amministratore; unite sotto quel livello quando [`parentSettingsBehavior`](/docs/it/settings#available-settings) è `"merge"`. Le chiavi non restrittive come `model` vengono silenziosamente eliminate in modo che questa opzione possa restringere la politica gestita ma non allentarla |440| `options.managedSettings` | `Settings` | `undefined` | Impostazioni della politica fornite dall'host di incorporamento. Segue le stesse regole di [`managedSettings` in `Options`](#options), tranne che `resolveSettings()` non esegue un [`policyHelper`](/docs/it/settings-reference#policyhelper) configurato, quindi lo snapshot può includere impostazioni che una sessione live scarta |
427| `options.serverManagedSettings` | `Settings` | `undefined` | Payload delle impostazioni gestite dal server da `/api/claude_code/settings`. Le chiavi non restrittive passano attraverso senza filtri |441| `options.serverManagedSettings` | `Settings` | `undefined` | Payload delle impostazioni gestite dal server da `/api/claude_code/settings`. Le chiavi non restrittive passano attraverso senza filtri |
428 442
429<h4 id="return-type-resolvedsettings">443<h4 id="return-type-resolvedsettings">
442 Esempio456 Esempio
443</h4>457</h4>
444 458
445L'esempio seguente risolve le impostazioni per una directory di progetto e stampa la fonte che controlla il periodo di pulizia.459L'esempio seguente risolve le impostazioni per una directory di progetto e stampa la fonte che controlla il periodo di pulizia. Su una macchina dove nessun file di impostazioni imposta `cleanupPeriodDays`, entrambe le righe stampate mostrano `undefined` per il valore, che è l'output previsto piuttosto che un errore.
446 460
447```typescript theme={null}461```typescript theme={null}
448import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";462import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";
467Oggetto di configurazione per la funzione `query()`.481Oggetto di configurazione per la funzione `query()`.
468 482
469| Proprietà | Tipo | Predefinito | Descrizione |483| Proprietà | Tipo | Predefinito | Descrizione |
470| :-------------------------------- | :------------------------------------------------------------------------------------------------------- | :---------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |484| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
471| `abortController` | `AbortController` | `new AbortController()` | Controller per annullare le operazioni |485| `abortController` | `AbortController` | `new AbortController()` | Controller per annullare le operazioni |
472| `additionalDirectories` | `string[]` | `[]` | Directory aggiuntive a cui Claude può accedere |486| `additionalDirectories` | `string[]` | `[]` | Directory aggiuntive a cui Claude può accedere. L'SDK passa ogni voce a Claude Code come `--add-dir`, quindi con l'impostazione `project` source Claude Code anche [carica le skill, i comandi e i subagenti della directory](/docs/it/permissions#additional-directories-grant-file-access-not-configuration) |
473| `agent` | `string` | `undefined` | Nome dell'agente per il thread principale. L'agente deve essere definito nell'opzione `agents` o nelle impostazioni |487| `agent` | `string` | `undefined` | Nome dell'agente per il thread principale. L'agente deve essere definito nell'opzione `agents` o nelle impostazioni |
474| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | Definisci programmaticamente i subagenti |488| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | Definisci programmaticamente i subagenti |
475| `agentProgressSummaries` | `boolean` | `false` | Quando `true`, genera riassunti di progresso a una riga per i subagenti e inoltrarli su eventi [`task_progress`](#sdktaskprogressmessage) tramite il campo `summary`. Si applica ai subagenti in primo piano e in background |489| `agentProgressSummaries` | `boolean` | `false` | Quando `true`, genera riassunti di progresso a una riga per i subagenti e inoltrarli su eventi [`task_progress`](#sdktaskprogressmessage) tramite il campo `summary`. Si applica ai subagenti in primo piano e in background |
476| `allowDangerouslySkipPermissions` | `boolean` | `false` | Abilita il bypass dei permessi. Obbligatorio quando si usa `permissionMode: 'bypassPermissions'` |490| `allowDangerouslySkipPermissions` | `boolean` | `false` | Abilita il bypass dei permessi. Obbligatorio quando si usa `permissionMode: 'bypassPermissions'` |
477| `allowedTools` | `string[]` | `[]` | Tool da approvare automaticamente senza richiedere. Questo non limita Claude a solo questi tool; i tool non elencati ricadono in `permissionMode` e `canUseTool`. Usa `disallowedTools` per bloccare i tool. Vedi [Permessi](/docs/it/agent-sdk/permissions#allow-and-deny-rules) |491| `allowedTools` | `string[]` | `[]` | Tool da approvare automaticamente senza richiedere. Questo non limita Claude a solo questi tool. Se nomini uno dei [tool di tracciamento delle attività](/docs/it/agent-sdk/todo-tracking#model-availability) qui, Claude Code anche opta la sessione in. Gli altri tool non elencati ricadono in `permissionMode` e `canUseTool`. Usa `disallowedTools` per bloccare i tool. Vedi [Permessi](/docs/it/agent-sdk/permissions#allow-and-deny-rules) |
478| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | Abilita le funzioni beta |492| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | Abilita le funzioni beta |
479| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Funzione di permesso personalizzata, invocata solo quando il [flusso di permesso](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated) ricade in un prompt. Non invocata per le chiamate pre-approvate da `allowedTools`, regole di autorizzazione, o `permissionMode`. `AskUserQuestion`, tool connettore [impostati dalla tua organizzazione su `ask`](/docs/it/mcp#organization-controls-on-connector-tools), e tool MCP contrassegnati [`requiresUserInteraction`](/docs/it/mcp#require-approval-for-a-specific-tool) la raggiungono anche se li hai consentiti; in modalità `dontAsk` questi vengono negati invece. Vedi [`CanUseTool`](#canusetool) per i dettagli |493| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Funzione di permesso personalizzata, invocata solo quando il [flusso di permesso](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated) ricade in un prompt. Non invocata per le chiamate pre-approvate da `allowedTools`, regole di autorizzazione, o `permissionMode`. Una regola di autorizzazione non pre-approva le [azioni che nessuna modalità auto-approva](/docs/it/permission-modes#actions-no-mode-auto-approves). Vedi [`CanUseTool`](#canusetool) per i dettagli |
480| `continue` | `boolean` | `false` | Continua la conversazione più recente |494| `continue` | `boolean` | `false` | Continua la conversazione più recente |
481| `cwd` | `string` | `process.cwd()` | Directory di lavoro corrente |495| `cwd` | `string` | `process.cwd()` | Directory di lavoro corrente |
482| `debug` | `boolean` | `false` | Abilita la modalità debug per il processo Claude Code |496| `debug` | `boolean` | `false` | Abilita la modalità debug per il processo Claude Code |
483| `debugFile` | `string` | `undefined` | Scrivi i log di debug in un percorso di file specifico. Abilita implicitamente la modalità debug |497| `debugFile` | `string` | `undefined` | Scrivi i log di debug in un percorso di file specifico. Abilita implicitamente la modalità debug |
484| `disallowedTools` | `string[]` | `[]` | Tool da negare. Un nome semplice come `"Bash"` rimuove il tool dal contesto di Claude. Una regola con ambito come `"Bash(rm *)"` lascia il tool disponibile e nega le chiamate corrispondenti in ogni modalità di permesso, incluso `bypassPermissions`. Vedi [Permessi](/docs/it/agent-sdk/permissions#allow-and-deny-rules) |498| `disallowedTools` | `string[]` | `[]` | Tool da negare. Un nome semplice come `"Bash"` rimuove il tool dal contesto di Claude. Una regola con ambito come `"Bash(rm *)"` lascia il tool disponibile e nega le chiamate corrispondenti in ogni modalità di permesso, incluso `bypassPermissions`, per il comando [come scritto](/docs/it/permissions#bash-rule-limits). Vedi [Permessi](/docs/it/agent-sdk/permissions#allow-and-deny-rules) |
485| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | Predefinito del modello | Controlla quanto sforzo Claude mette nella sua risposta. Funziona con il pensiero adattivo per guidare la profondità del pensiero. Vedi [regola il livello di sforzo](/docs/it/model-config#adjust-effort-level) |499| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `undefined` | Controlla quanto sforzo Claude mette nella sua risposta. Funziona con il pensiero adattivo per guidare la profondità del pensiero. Vedi [regola il livello di sforzo](/docs/it/model-config#adjust-effort-level) |
486| `enableFileCheckpointing` | `boolean` | `false` | Abilita il tracciamento dei cambiamenti di file per il rewind. Vedi [File checkpointing](/docs/it/agent-sdk/file-checkpointing) |500| `enableFileCheckpointing` | `boolean` | `false` | Abilita il tracciamento dei cambiamenti di file per il rewind. Vedi [File checkpointing](/docs/it/agent-sdk/file-checkpointing) |
487| `env` | `Record<string, string \| undefined>` | `process.env` | Variabili di ambiente. Quando impostato, questo sostituisce l'ambiente del subprocess invece di unirsi a `process.env`, quindi passa `{ ...process.env, YOUR_VAR: 'value' }` per mantenere le variabili ereditate come `PATH`. Vedi [Gestisci risposte API lente o bloccate](#handle-slow-or-stalled-api-responses) per un esempio di questo modello, e [Variabili di ambiente](/docs/it/env-vars) per le variabili che la CLI sottostante legge. Imposta `CLAUDE_AGENT_SDK_CLIENT_APP` per identificare la tua app nell'intestazione User-Agent |501| `env` | `Record<string, string \| undefined>` | `process.env` | Variabili di ambiente. Quando impostato, questo sostituisce l'ambiente del subprocess invece di unirsi a `process.env`, quindi passa `{ ...process.env, YOUR_VAR: 'value' }` per mantenere le variabili ereditate come `PATH`. Vedi [Gestisci risposte API lente o bloccate](#handle-slow-or-stalled-api-responses) per un esempio di questo modello, e [Variabili di ambiente](/docs/it/env-vars) per le variabili che la CLI sottostante legge. Imposta `CLAUDE_AGENT_SDK_CLIENT_APP` per identificare la tua app nell'intestazione User-Agent |
488| `executable` | `'bun' \| 'deno' \| 'node'` | Auto-rilevato | Runtime JavaScript da usare |502| `executable` | `'bun' \| 'deno' \| 'node'` | Auto-rilevato | Runtime JavaScript da usare |
490| `extraArgs` | `Record<string, string \| null>` | `{}` | Argomenti aggiuntivi |504| `extraArgs` | `Record<string, string \| null>` | `{}` | Argomenti aggiuntivi |
491| `fallbackModel` | `string` | `undefined` | Modello da usare se il primario fallisce |505| `fallbackModel` | `string` | `undefined` | Modello da usare se il primario fallisce |
492| `forkSession` | `boolean` | `false` | Quando si riprende con `resume`, esegui il fork a un nuovo ID di sessione invece di continuare la sessione originale |506| `forkSession` | `boolean` | `false` | Quando si riprende con `resume`, esegui il fork a un nuovo ID di sessione invece di continuare la sessione originale |
493| `forwardSubagentText` | `boolean` | `false` | Inoltra i blocchi di testo e pensiero dei subagenti come messaggi dell'assistente e dell'utente con `parent_tool_use_id` impostato, in modo che i consumer possano renderizzare una trascrizione nidificata. Per impostazione predefinita, solo i blocchi `tool_use` e `tool_result` dai subagenti vengono emessi |507| `forwardSubagentText` | `boolean` | `false` | Inoltra i blocchi di testo e pensiero dei subagenti come messaggi dell'assistente e dell'utente con `parent_tool_use_id` impostato, in modo che i consumer possano renderizzare una trascrizione nidificata. Senza questa opzione, Claude Code emette blocchi `tool_use` e `tool_result` dai subagenti ma non testo o pensiero. I messaggi dai subagenti a ogni profondità di nidificazione vengono inoltrati su Claude Code v2.1.219 e successivo; prima di v2.1.219, solo i messaggi dai subagenti di profondità-1 apparivano |
494| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Callback hook per gli eventi |508| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Callback hook per gli eventi |
495| `includeHookEvents` | `boolean` | `false` | Includi gli eventi del ciclo di vita hook per ogni evento hook nel flusso di 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 hanno bisogno di questa opzione |509| `includeHookEvents` | `boolean` | `false` | Includi gli eventi del ciclo di vita hook nel flusso di 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 hanno bisogno di questa opzione. Alcuni eventi hook, come `Notification`, `SessionEnd`, `PreCompact`, e `PostCompact`, non producono mai un `SDKHookStartedMessage`, anche con questa opzione. Per questi eventi, Claude Code emette comunque un `SDKHookProgressMessage` mentre un hook di comando che viene eseguito per più di un secondo produce output, ed emette un `SDKHookResponseMessage` solo quando un hook [che viene eseguito in background](/docs/it/hooks#run-hooks-in-the-background) finisce |
496| `includePartialMessages` | `boolean` | `false` | Includi gli eventi di messaggi parziali |510| `includePartialMessages` | `boolean` | `false` | Includi gli eventi di messaggi parziali |
497| `loadTimeoutMs` | `number` | `60000` | *Alpha.* Timeout in millisecondi per ogni chiamata `sessionStore.load()` e `sessionStore.listSubkeys()` durante la materializzazione del resume. Se l'adapter non si stabilizza entro questa finestra, la query fallisce invece di bloccarsi. Ignorato quando `sessionStore` non è impostato |511| `loadTimeoutMs` | `number` | `60000` | *Alpha.* Timeout in millisecondi per ogni chiamata `sessionStore.load()` e `sessionStore.listSubkeys()` durante la materializzazione del resume. Se l'adapter non si stabilizza entro questa finestra, la query fallisce invece di bloccarsi. Ignorato quando `sessionStore` non è impostato |
498| `managedSettings` | `Settings` | `undefined` | Impostazioni a livello di politica fornite dal processo genitore che genera. Eliminate quando un livello di impostazioni gestite controllato da IT esiste già sulla macchina, a meno che l'amministratore non acconsenta con `parentSettingsBehavior: 'merge'`. Filtrate solo alle chiavi restrittive indipendentemente |512| `managedSettings` | `Settings` | `undefined` | Impostazioni a livello di politica che il tuo processo host fornisce alla sessione generata. Su macchine con impostazioni gestite distribuite da admin, Claude Code ignora queste a meno che la fonte gestita di priorità più alta dell'admin imposti `parentSettingsBehavior: 'merge'`, e non le unisce mai mentre un [`policyHelper`](/docs/it/settings-reference#policyhelper) fornisce impostazioni gestite. I valori uniti passano attraverso un filtro solo restrittivo; [Limita le impostazioni padre](/docs/it/claude-apps-gateway#restrict-parent-settings) copre cosa il filtro ammette e i blocchi `allowManaged*Only`. Un host che imposta [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/it/env-vars) ha tre chiavi lette direttamente da questo payload: la sua [configurazione del modello](/docs/it/model-config#restrict-model-selection) su Claude Code v2.1.222 o successivo, [`modelPricing`](/docs/it/settings-reference#modelpricing) quando nessuna fonte gestita lo imposta su v2.1.246 o successivo, e la sua voce `ENABLE_TOOL_SEARCH` env su v2.1.247 o successivo |
499| `maxBudgetUsd` | `number` | `undefined` | Interrompi la query quando la stima del costo lato client raggiunge questo valore in USD. Confrontato con la stessa stima di `total_cost_usd`; vedi [Traccia costo e utilizzo](/docs/it/agent-sdk/cost-tracking) per le avvertenze di accuratezza |513| `maxBudgetUsd` | `number` | `undefined` | Interrompi la query quando la stima del costo lato client raggiunge questo valore in USD. Confrontato con la stessa stima di `total_cost_usd`; vedi [Traccia costo e utilizzo](/docs/it/agent-sdk/cost-tracking) per le avvertenze di accuratezza |
500| `maxThinkingTokens` | `number` | `undefined` | *Deprecato:* Usa `thinking` invece. Token massimi per il processo di pensiero |514| `maxThinkingTokens` | `number` | `undefined` | *Deprecato:* Usa `thinking` invece. Token massimi per il processo di pensiero |
501| `maxTurns` | `number` | `undefined` | Turni agentici massimi (round trip di uso dei tool) |515| `maxTurns` | `number` | `undefined` | Turni agentici massimi (round trip di uso dei tool) |
507| `pathToClaudeCodeExecutable` | `string` | Auto-risolto dal binario nativo raggruppato | Percorso all'eseguibile Claude Code. Necessario solo se le dipendenze opzionali sono state saltate durante l'installazione o la tua piattaforma non è nel set supportato |521| `pathToClaudeCodeExecutable` | `string` | Auto-risolto dal binario nativo raggruppato | Percorso all'eseguibile Claude Code. Necessario solo se le dipendenze opzionali sono state saltate durante l'installazione o la tua piattaforma non è nel set supportato |
508| `permissionMode` | [`PermissionMode`](#permissionmode) | `'default'` | Modalità di permesso per la sessione |522| `permissionMode` | [`PermissionMode`](#permissionmode) | `'default'` | Modalità di permesso per la sessione |
509| `permissionPromptToolName` | `string` | `undefined` | Nome del tool MCP per i prompt di permesso |523| `permissionPromptToolName` | `string` | `undefined` | Nome del tool MCP per i prompt di permesso |
524| `permissionPrompts` | `'host' \| 'none'` | `'host'` | Chi risponde ai prompt di permesso: `'host'` li instrada al tuo callback [`canUseTool`](#canusetool) o al tool `permissionPromptToolName`, e `'none'` [nega le chiamate che avrebbero richiesto](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated). Richiede Claude Code v2.1.259 o successivo |
510| `persistSession` | `boolean` | `true` | Quando `false`, disabilita la persistenza della sessione su disco. Le sessioni non possono essere riprese in seguito |525| `persistSession` | `boolean` | `true` | Quando `false`, disabilita la persistenza della sessione su disco. Le sessioni non possono essere riprese in seguito |
511| `planModeInstructions` | `string` | `undefined` | Istruzioni di flusso di lavoro personalizzate per la modalità plan. Quando `permissionMode` è `'plan'`, questa stringa sostituisce il corpo del flusso di lavoro della modalità plan predefinito. La CLI lo avvolge comunque con il preambolo di applicazione di sola lettura e il footer del protocollo ExitPlanMode |526| `planModeInstructions` | `string` | `undefined` | Istruzioni di flusso di lavoro personalizzate per la modalità plan. Quando `permissionMode` è `'plan'`, questa stringa sostituisce il corpo del flusso di lavoro della modalità plan predefinito. La CLI lo avvolge comunque con il preambolo di applicazione di sola lettura e il footer del protocollo ExitPlanMode |
512| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Carica plugin personalizzati da percorsi locali. Vedi [Plugins](/docs/it/agent-sdk/plugins) per i dettagli |527| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Carica plugin personalizzati da percorsi locali. Vedi [Plugins](/docs/it/agent-sdk/plugins) per i dettagli |
513| `promptSuggestions` | `boolean` | `false` | Abilita i suggerimenti di prompt. Emette un messaggio `prompt_suggestion` dopo ogni turno con un prompt utente successivo previsto |528| `promptSuggestions` | `boolean` | `false` | Abilita i suggerimenti di prompt. Dopo un turno, Claude Code emette un messaggio `prompt_suggestion` che trasporta un prompt utente successivo previsto. Claude Code non genera alcun suggerimento per alcuni turni, come quando il tuo account è vicino o al suo limite di utilizzo. Vedi [Quando Claude Code salta i suggerimenti](/docs/it/interactive-mode#when-claude-code-skips-suggestions) |
514| `resume` | `string` | `undefined` | ID della sessione da riprendere |529| `resume` | `string` | `undefined` | ID della sessione da riprendere |
530| `resumeDropsTurn` | `string` | `undefined` | Con `resumeSessionAt`: l'UUID del prompt del turno che il resume di troncamento intende scartare. Claude Code rifiuta il resume quando l'intervallo scartato contiene qualcosa non attribuibile a quel turno, come messaggi in coda assorbiti o notifiche di attività, e nomina il flag `--resume-drops-turn` nel messaggio di rifiuto. Solo l'Agent SDK e i resume in modalità print leggono la coppia. Richiede Claude Code v2.1.223 o successivo |
515| `resumeSessionAt` | `string` | `undefined` | Riprendi la sessione a un UUID di messaggio specifico |531| `resumeSessionAt` | `string` | `undefined` | Riprendi la sessione a un UUID di messaggio specifico |
516| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | Configura il comportamento della sandbox a livello di programmazione. Vedi [Impostazioni sandbox](#sandboxsettings) per i dettagli |532| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | Configura il comportamento della sandbox a livello di programmazione. Vedi [Impostazioni sandbox](#sandboxsettings) per i dettagli |
517| `sessionId` | `string` | Auto-generato | Usa un UUID specifico per la sessione invece di generarne uno automaticamente |533| `sessionId` | `string` | Auto-generato | Usa un UUID specifico per la sessione invece di generarne uno automaticamente |
518| `sessionStore` | [`SessionStore`](/docs/it/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Specchia i trascritti della sessione in un backend esterno in modo che qualsiasi host possa riprenderli. Vedi [Persisti le sessioni nell'archiviazione esterna](/docs/it/agent-sdk/session-storage) |534| `sessionStore` | [`SessionStore`](/docs/it/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Specchia i trascritti della sessione in un backend esterno in modo che un altro host possa riprenderli. Vedi [Persisti le sessioni nell'archiviazione esterna](/docs/it/agent-sdk/session-storage) |
519| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alpha.* Modalità di flush per `sessionStore`. Ignorato quando `sessionStore` non è impostato |535| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alpha.* Modalità di flush per `sessionStore`. Ignorato quando `sessionStore` non è impostato |
520| `settings` | `string \| Settings` | `undefined` | Oggetto [impostazioni](/docs/it/settings) inline o percorso a un file di impostazioni. Popola il livello flag-settings nell'[ordine di precedenza](/docs/it/settings#settings-precedence). Cambia a runtime con [`applyFlagSettings()`](#applyflagsettings) |536| `settings` | `string \| Settings` | `undefined` | Oggetto [impostazioni](/docs/it/settings) inline o percorso a un file di impostazioni. Popola il livello flag-settings nell'[ordine di precedenza](/docs/it/settings#settings-precedence). Cambia a runtime con [`applyFlagSettings()`](#applyflagsettings) |
521| `settingSources` | [`SettingSource`](#settingsource)`[]` | Impostazioni predefinite CLI (tutte le fonti) | Controlla quali impostazioni del filesystem caricare. Passa `[]` per disabilitare le impostazioni utente, progetto e locali. Le impostazioni della politica gestita vengono caricate indipendentemente; le impostazioni gestite dal server vengono recuperate quando la sessione si autentica con una credenziale organizzativa su una [configurazione idonea](/docs/it/server-managed-settings#platform-availability). Vedi [Usa le funzioni Claude Code](/docs/it/agent-sdk/claude-code-features#what-settingsources-does-not-control) |537| `settingSources` | [`SettingSource`](#settingsource)`[]` | Impostazioni predefinite CLI (tutte le fonti) | Controlla quali impostazioni del filesystem caricare. Passa `[]` per disabilitare le impostazioni utente, progetto e locali. [Politica gestita da endpoint](/docs/it/managed-settings#delivery-mechanisms) viene caricata indipendentemente; le impostazioni gestite dal server vengono recuperate quando la sessione si autentica con una credenziale organizzativa su una [configurazione idonea](/docs/it/server-managed-settings#platform-availability). Vedi [Usa le funzioni Claude Code](/docs/it/agent-sdk/claude-code-features#what-settingsources-does-not-control) |
522| `skills` | `string[] \| 'all'` | `undefined` | Skills disponibili per la sessione. Passa `'all'` per abilitare ogni skill scoperta, o un elenco di nomi di skill. Quando impostato, l'SDK aggiunge automaticamente lo strumento Skill a `allowedTools`. Se passi anche `tools`, includi `'Skill'` in quell'elenco. Vedi [Skills](/docs/it/agent-sdk/skills) |538| `skills` | `string[] \| 'all'` | `undefined` | Skills disponibili per la sessione. Passa `'all'` per abilitare ogni skill scoperta, o un elenco di nomi di skill. Passa solo nomi esatti. Su Agent SDK v0.3.221 o successivo, l'SDK rifiuta i nomi malformati 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. Vedi [Skills](/docs/it/agent-sdk/skills) |
523| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Funzione personalizzata per generare il processo Claude Code. Usa per eseguire Claude Code in VM, container o ambienti remoti |539| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Funzione personalizzata per generare il processo Claude Code. Usa per eseguire Claude Code in VM, container o ambienti remoti |
524| `stderr` | `(data: string) => void` | `undefined` | Callback per l'output stderr |540| `stderr` | `(data: string) => void` | `undefined` | Callback per l'output stderr |
525| `strictMcpConfig` | `boolean` | `false` | Usa solo i server passati in `mcpServers` e ignora il progetto `.mcp.json`, le impostazioni utente, i server MCP forniti dai plugin e i [connettori claude.ai](/docs/it/mcp#use-mcp-servers-from-claude-ai) |541| `strictMcpConfig` | `boolean` | `false` | Usa solo i server passati in `mcpServers` e ignora il progetto `.mcp.json`, le impostazioni utente, i server MCP forniti dai plugin, e i [connettori claude.ai](/docs/it/mcp#use-mcp-servers-from-claude-ai) |
526| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (prompt minimo) | Configurazione del prompt di sistema. Passa una stringa per un prompt personalizzato, o `{ type: 'preset', preset: 'claude_code' }` per usare il prompt di sistema di Claude Code. Quando si usa la forma dell'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 [migliore riutilizzo della cache dei prompt tra le macchine](/docs/it/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |542| `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, o `{ 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 le parti statiche e per-richiesta per [memorizzare nella cache la parte statica di un prompt personalizzato](/docs/it/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt). Quando si usa la forma dell'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 [migliore riutilizzo della cache dei prompt tra le macchine](/docs/it/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines). Imposta `snapshot: false` per ricostruire il prompt su ogni richiesta invece di [riutilizzare il prompt che la sessione ha registrato sulla sua prima richiesta](/docs/it/agent-sdk/modifying-system-prompts#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 |
527| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* Budget di attività lato API in token. Quando impostato, il modello viene informato del suo budget di token rimanente in modo che possa regolare l'uso dei tool e concludere prima del limite |543| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* Budget di attività lato API in token. Quando impostato, il modello viene informato del suo budget di token rimanente in modo che possa regolare l'uso dei tool e concludere prima del limite |
528| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` per i modelli supportati | Controlla il comportamento di pensiero/ragionamento di Claude. Vedi [`ThinkingConfig`](#thinkingconfig) per le opzioni |544| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` per i modelli supportati | Controlla il comportamento di pensiero/ragionamento di Claude. Vedi [`ThinkingConfig`](#thinkingconfig) per le opzioni |
529| `title` | `string` | `undefined` | Titolo di visualizzazione per la sessione. Quando si riprende tramite `resume` o `continue`, il titolo persistente della sessione ripresa ha la precedenza; usa [`renameSession()`](#renamesession) per rinominare una sessione esistente |545| `title` | `string` | `undefined` | Titolo di visualizzazione per la sessione. Quando si riprende tramite `resume` o `continue`, il titolo persistente della sessione ripresa ha la precedenza; usa [`renameSession()`](#renamesession) per rinominare una sessione esistente |
538Il subprocess CLI legge diverse variabili di ambiente che controllano i timeout dell'API e il rilevamento dei blocchi. Passale attraverso l'opzione `env`:554Il subprocess CLI legge diverse variabili di ambiente che controllano i timeout dell'API e il rilevamento dei blocchi. Passale attraverso l'opzione `env`:
539 555
540```typescript theme={null}556```typescript theme={null}
557import { query } from "@anthropic-ai/claude-agent-sdk";
558
541const result = query({559const result = query({
542 prompt: "Analyze this code",560 prompt: "Analyze this code",
543 options: {561 options: {
552```570```
553 571
554* `API_TIMEOUT_MS`: timeout per richiesta sul client Anthropic, in millisecondi. Predefinito `600000`. Si applica al loop principale e a tutti i subagenti.572* `API_TIMEOUT_MS`: timeout per richiesta sul client Anthropic, in millisecondi. Predefinito `600000`. Si applica al loop principale e a tutti i subagenti.
555* `CLAUDE_CODE_MAX_RETRIES`: numero massimo di tentativi API. Predefinito `10`, limitato a `15`. Ogni tentativo ottiene la propria finestra `API_TIMEOUT_MS`, quindi il tempo wall case peggiore è approssimativamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` più backoff. Per esecuzioni incustodite che devono attendere attraverso interruzioni più lunghe, imposta `CLAUDE_CODE_RETRY_WATCHDOG=1`: ritenta gli errori di capacità indefinitamente, e a partire da Claude Code v2.1.199 aumenta il predefinito per altri errori transitori a `300` e rimuove il limite su questa variabile.573* `CLAUDE_CODE_MAX_RETRIES`: numero massimo di tentativi API. Predefinito `10`, limitato a `15`. Ogni tentativo ottiene la propria finestra `API_TIMEOUT_MS`, quindi il tempo wall case peggiore è approssimativamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` più backoff. Per esecuzioni incustodite che devono attendere attraverso interruzioni più lunghe, imposta [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/it/errors#tune-retry-behavior): ritenta gli errori di capacità transitori indefinitamente e, su Claude Code v2.1.199 o successivo, aumenta il predefinito per altri errori transitori a `300` e rimuove il limite su questa variabile.
556* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog di blocco per i subagenti lanciati con `run_in_background`. Predefinito `600000`. Si ripristina su ogni evento di stream; al blocco interrompe il subagente, contrassegna l'attività come fallita e presenta l'errore al genitore con qualsiasi risultato parziale. Non si applica ai subagenti sincroni.574* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog di blocco per i subagenti. Mentre il watchdog di stream è attivo, il predefinito è `CLAUDE_STREAM_IDLE_TIMEOUT_MS` più 5 minuti, che arriva a `600000` a meno che non aumenti quella variabile. Con il watchdog di stream spento, il predefinito è `600000`. Prima di v2.1.257, il predefinito era sempre `600000`.
557* `CLAUDE_ENABLE_STREAM_WATCHDOG` con `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: interrompe la richiesta quando le intestazioni sono arrivate ma il corpo della risposta smette di trasmettere. Il watchdog è attivo per impostazione predefinita per tutti i provider; imposta `CLAUDE_ENABLE_STREAM_WATCHDOG=0` per disabilitarlo. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` predefinito a `300000` ed è limitato a quel minimo. La richiesta interrotta passa attraverso il percorso di tentativo normale.575
576 Il timer si ripristina su ogni evento di stream. Al blocco, Claude Code interrompe il subagente e segnala il blocco al genitore. Per un subagente in background, contrassegna anche l'attività come fallita e allega qualsiasi risultato parziale.
577* `CLAUDE_ENABLE_STREAM_WATCHDOG` con `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: watchdog di stream che interrompe la richiesta quando le intestazioni sono arrivate ma il corpo della risposta smette di trasmettere. Il watchdog è attivo per impostazione predefinita per tutti i provider; imposta `CLAUDE_ENABLE_STREAM_WATCHDOG=0` per disabilitarlo. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` predefinito a `300000` ed è limitato a quel minimo. Dopo l'interruzione, [Tentativi automatici](/docs/it/errors#automatic-retries) copre cosa Claude Code fa, in base a quanto la risposta aveva progredito.
578
579 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 di `ping` [stream](#sdkpartialassistantmessage), quindi leggi questi frame come vivacità piuttosto che cronometrare la sessione su silenzio. Prima di v2.1.257, i frame si fermavano 5 minuti dopo l'ultimo evento di stream reale.
558 580
559<h3 id="query-object">581<h3 id="query-object">
560 Oggetto `Query`582 Oggetto `Query`
572 setPermissionMode(mode: PermissionMode): Promise<void>;594 setPermissionMode(mode: PermissionMode): Promise<void>;
573 setModel(model?: string): Promise<void>;595 setModel(model?: string): Promise<void>;
574 setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;596 setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
575 applyFlagSettings(settings: { [K in keyof Settings]?: Settings[K] | null }): Promise<void>;597 applyFlagSettings(settings: {
598 [K in keyof Settings]?: K extends 'effortLevel'
599 ? 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null
600 : Settings[K] | null;
601 }): Promise<void>;
602 updateSettings(
603 source: 'localSettings',
604 settings: Record<string, unknown>,
605 ): Promise<void>;
576 initializationResult(): Promise<SDKControlInitializeResponse>;606 initializationResult(): Promise<SDKControlInitializeResponse>;
577 reinitialize(): Promise<SDKControlInitializeResponse>;607 reinitialize(): Promise<SDKControlInitializeResponse>;
578 supportedCommands(): Promise<SlashCommand[]>;608 supportedCommands(): Promise<SlashCommand[]>;
579 supportedModels(): Promise<ModelInfo[]>;609 supportedModels(): Promise<ModelInfo[]>;
580 supportedAgents(): Promise<AgentInfo[]>;610 supportedAgents(): Promise<AgentInfo[]>;
581 mcpServerStatus(): Promise<McpServerStatus[]>;611 mcpServerStatus(): Promise<McpServerStatus[]>;
612 getContextUsage(opts?: {
613 detail?: 'summary' | 'full';
614 }): Promise<SDKControlGetContextUsageResponse>;
615 readFile(
616 path: string,
617 options?: { maxBytes?: number; encoding?: 'utf-8' | 'base64' }
618 ): Promise<SDKControlReadFileResponse | null>;
619 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;
582 accountInfo(): Promise<AccountInfo>;620 accountInfo(): Promise<AccountInfo>;
583 reconnectMcpServer(serverName: string): Promise<void>;621 reconnectMcpServer(serverName: string): Promise<void>;
584 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;622 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;
595 633
596| Metodo | Descrizione |634| Metodo | Descrizione |
597| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |635| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
598| `interrupt()` | Interrompe la query. Disponibile solo in modalità input streaming. Quando la CLI pubblicizza la capacità `interrupt_receipt_v1` in [`SDKSystemMessage.capabilities`](#sdksystemmessage), si risolve con un [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) che elenca i messaggi in coda che sopravvivono all'interruzione. Si risolve `undefined` su CLI prima della v2.1.205 |636| `interrupt()` | Interrompe la query. Disponibile solo in modalità input streaming. Quando la CLI pubblicizza la capacità `interrupt_receipt_v1` in [`SDKSystemMessage.capabilities`](#sdksystemmessage), si risolve con un [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) che elenca i messaggi che erano in sospeso quando l'interruzione è arrivata. Si risolve `undefined` su CLI prima della v2.1.205 |
599| `rewindFiles(userMessageId, options?)` | Ripristina i file al loro stato al messaggio utente specificato. Passa `{ dryRun: true }` per visualizzare in anteprima i cambiamenti. Richiede `enableFileCheckpointing: true`. Vedi [File checkpointing](/docs/it/agent-sdk/file-checkpointing) |637| `rewindFiles(userMessageId, options?)` | Ripristina i file al loro stato al messaggio utente specificato. Passa `{ dryRun: true }` per visualizzare in anteprima i cambiamenti. Richiede `enableFileCheckpointing: true`. Vedi [File checkpointing](/docs/it/agent-sdk/file-checkpointing) |
600| `setPermissionMode()` | Cambia la modalità di permesso (disponibile solo in modalità input streaming) |638| `setPermissionMode()` | Cambia la modalità di permesso (disponibile solo in modalità input streaming) |
601| `setModel()` | Cambia il modello (disponibile solo in modalità input streaming) |639| `setModel()` | Cambia il modello (disponibile solo in modalità input streaming). Passare `undefined` o la stringa `"default"` ripristina il modello predefinito della sessione |
602| `setMaxThinkingTokens()` | *Deprecato:* Usa l'opzione `thinking` invece. Cambia i token di pensiero massimi. Passare `null` ripristina il pensiero al predefinito della sessione: un override a metà sessione viene cancellato, e il pensiero rimane disattivato per le sessioni che lo hanno disabilitato |640| `setMaxThinkingTokens()` | *Deprecato:* Usa l'opzione `thinking` invece. Cambia i token di pensiero massimi. Passare `null` ripristina il pensiero al predefinito della sessione: un override a metà sessione viene cancellato, e il pensiero rimane disattivato per le sessioni che lo hanno disabilitato |
603| `applyFlagSettings(settings)` | Unisce le impostazioni nel livello flag settings della sessione a runtime (disponibile solo in modalità input streaming). Vedi [`applyFlagSettings()`](#applyflagsettings) |641| `applyFlagSettings(settings)` | Unisce le impostazioni nel livello flag settings della sessione a runtime (disponibile solo in modalità input streaming). Vedi [`applyFlagSettings()`](#applyflagsettings) |
642| `updateSettings(source, settings)` | Unisce le impostazioni nel file di impostazioni locali del progetto, `.claude/settings.local.json`; hanno effetto sulla richiesta successiva. Accetta solo `source: 'localSettings'` e un set di chiavi consentite, attualmente `outputStyle`, con valori stringa; l'eliminazione di una chiave non è supportata. Rifiuta su trasporti remoti e in sessioni il cui [`settingSources`](#options) esclude `local`. Richiede TypeScript SDK v0.3.257 o successivo, che raggruppa Claude Code v2.1.257 |
604| `initializationResult()` | Restituisce il risultato di inizializzazione completo inclusi i comandi supportati, i modelli, le informazioni dell'account e la configurazione dello stile di output |643| `initializationResult()` | Restituisce il risultato di inizializzazione completo inclusi i comandi supportati, i modelli, le informazioni dell'account e la configurazione dello stile di output |
605| `reinitialize()` | Rinvia la richiesta di controllo `initialize` al CLI in esecuzione e restituisce un risultato fresco invece del risultato della prima connessione memorizzato nella cache. Usalo dopo un gap di trasporto, come il ricollegamento a una sessione dopo una disconnessione, in modo che le richieste di permesso in sospeso raggiungano di nuovo il tuo callback `canUseTool`. Rendi il callback idempotente per ID di richiesta, perché una richiesta la cui risposta è stata persa viene inviata di nuovo. Richiede Claude Code v2.1.195 o successivo |644| `reinitialize()` | Rinvia la richiesta di controllo `initialize` al CLI in esecuzione e restituisce un risultato fresco invece del risultato della prima connessione memorizzato nella cache. Usalo dopo un gap di trasporto, come il ricollegamento a una sessione dopo una disconnessione, in modo che le richieste di permesso in sospeso raggiungano di nuovo il tuo callback `canUseTool`. Rendi il callback idempotente per ID di richiesta, perché una richiesta la cui risposta è stata persa viene inviata di nuovo. Richiede Claude Code v2.1.195 o successivo |
606| `supportedCommands()` | Restituisce i comandi slash disponibili |645| `supportedCommands()` | Restituisce i comandi disponibili. Da Agent SDK v0.3.216 l'elenco riflette i cambiamenti di comando a metà sessione; vedi [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |
607| `supportedModels()` | Restituisce i modelli disponibili con le informazioni di visualizzazione |646| `supportedModels()` | Restituisce i modelli disponibili con le informazioni di visualizzazione |
608| `supportedAgents()` | Restituisce i subagenti disponibili come [`AgentInfo`](#agentinfo)`[]` |647| `supportedAgents()` | Restituisce i subagenti disponibili come [`AgentInfo`](#agentinfo)`[]` |
609| `mcpServerStatus()` | Restituisce lo stato dei server MCP connessi |648| `mcpServerStatus()` | Restituisce lo stato dei server MCP connessi |
649| `getContextUsage(opts?)` | Restituisce un [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) che suddivide l'utilizzo della finestra di contesto della sessione per categoria, skill e tool. Con il `detail` predefinito, è lo stesso dato che `/context` mostra in una sessione interattiva. L'[opzione `detail`](#sdkcontrolgetcontextusageresponse) richiede Agent SDK v0.3.257 o successivo |
650| `readFile(path, options?)` | Legge un file dal filesystem della sessione. Claude Code risolve il percorso rispetto a `cwd`; [Cosa `readFile()` può leggere](#what-readfile-can-read) elenca i file che serve. Passa `{ maxBytes }` per cambiare il limite di lettura (predefinito 1 MB, massimo 10 MB) e `{ encoding: 'base64' }` per file binari come immagini. Si risolve con un [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), o `null` su rifiuto di permesso, un file mancante, o un errore di trasporto. Richiede TypeScript SDK v0.2.121 o successivo |
651| `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 successivo |
610| `accountInfo()` | Restituisce le informazioni dell'account |652| `accountInfo()` | Restituisce le informazioni dell'account |
611| `reconnectMcpServer(serverName)` | Ricollega un server MCP per nome |653| `reconnectMcpServer(serverName)` | Ricollega 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 ricollega il server che hai configurato tramite [`mcpServers`](#options) o `setMcpServers()`, non la voce del file di impostazioni. Quell'ordine di risoluzione richiede Claude Code v2.1.257 o successivo |
612| `toggleMcpServer(serverName, enabled)` | Abilita o disabilita un server MCP per nome |654| `toggleMcpServer(serverName, enabled)` | Abilita o disabilita un server MCP per nome, con la stessa risoluzione del nome di `reconnectMcpServer()`. Disabilitare disconnette il server |
613| `setMcpServers(servers)` | Sostituisci dinamicamente l'insieme dei server MCP per questa sessione. Restituisce informazioni su quali server sono stati aggiunti, rimossi e eventuali errori |655| `setMcpServers(servers)` | Sostituisci dinamicamente l'insieme dei server MCP per questa sessione. Si risolve con un [`McpSetServersResult`](#mcpsetserversresult) che nomina quali server sono stati aggiunti e rimossi, e eventuali errori |
614| `streamInput(stream)` | Trasmetti i messaggi di input alla query per le conversazioni multi-turno |656| `streamInput(stream)` | Trasmetti i messaggi di input alla query per le conversazioni multi-turno |
615| `stopTask(taskId)` | Interrompi un'attività di background in esecuzione per ID |657| `stopTask(taskId)` | Interrompi un'attività di background in esecuzione per ID |
616| `close()` | Chiudi la query e termina il processo sottostante. Termina forzatamente la query e pulisce tutte le risorse |658| `close()` | Chiudi la query e termina il processo sottostante. Termina forzatamente la query e pulisce tutte le risorse |
619 `applyFlagSettings()`661 `applyFlagSettings()`
620</h4>662</h4>
621 663
622Cambia qualsiasi [impostazione](/docs/it/settings) su una sessione in esecuzione senza riavviare la query. Usalo quando un'impostazione che non ha un setter dedicato deve cambiare a metà sessione, come irrigidire `permissions` dopo che l'agente legge input non attendibile. `setModel()` e `setPermissionMode()` sono setter dedicati per quelle due chiavi; `applyFlagSettings()` è la forma generale che accetta qualsiasi sottoinsieme delle chiavi di impostazioni, e passare `model` qui si comporta come `setModel()`.664Cambia [impostazioni](/docs/it/settings) su una sessione in esecuzione senza riavviare la query. Usalo quando un'impostazione che non ha un setter dedicato deve cambiare a metà sessione, come irrigidire `permissions` dopo che l'agente legge input non attendibile. `setModel()` e `setPermissionMode()` sono setter dedicati per quelle due chiavi; `applyFlagSettings()` è la forma generale che accetta qualsiasi sottoinsieme delle chiavi di impostazioni, e passare `model` qui si comporta come `setModel()`.
623 665
624Solo alcune chiavi hanno effetto a metà sessione:666Solo alcune chiavi hanno effetto a metà sessione:
625 667
626* **Applicate al turno successivo**: `model`, `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `agent`. Cambiare `agent` applica anche l'override del modello di quell'agente, gli hook e il prompt di sistema al turno successivo.668* **Applicate al turno successivo**: `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `agent`. Cambiare `agent` applica anche l'override del modello di quell'agente e gli hook al turno successivo. Il suo prompt di sistema si applica al turno successivo, o, in una sessione che [riutilizza un prompt di sistema registrato](/docs/it/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session), una volta che la sessione è compattata.
669* **Applicate durante il turno corrente**: `model`. Se cambi `model` mentre Claude sta lavorando su un turno, la risposta che Claude sta già generando finisce sul vecchio modello, e il resto del turno, a partire dalla prossima chiamata che Claude Code fa al modello, usa quello nuovo. I subagenti mantengono il loro modello. Prima di v2.1.212, un cambio a metà turno attendeva il turno successivo.
627* **Nessun effetto a metà sessione**: le opzioni del prompt di sistema. Questi vengono risolti una volta all'avvio, quindi la sessione in esecuzione mantiene il valore originale anche se la chiamata ha successo. Per cambiarli, avvia una nuova sessione.670* **Nessun effetto a metà sessione**: le opzioni del prompt di sistema. Questi vengono risolti una volta all'avvio, quindi la sessione in esecuzione mantiene il valore originale anche se la chiamata ha successo. Per cambiarli, avvia una nuova sessione.
628 671
629`effortLevel` accetta un nome di [livello di sforzo](/docs/it/model-config#adjust-effort-level). Accetta anche `"ultracode"`, che esegue la sessione a sforzo `xhigh` e attiva [ultracode](/docs/it/workflows#let-claude-decide-with-ultracode). Il tipo `Settings` dichiara `effortLevel` senza quel valore, quindi passa l'equivalente `{ ultracode: true }` in TypeScript. 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.672`effortLevel` accetta un nome di [livello di sforzo](/docs/it/model-config#adjust-effort-level). Accetta anche `"ultracode"`, che richiede sforzo `xhigh` con [ultracode](/docs/it/workflows#let-claude-decide-with-ultracode) attivo. `applyFlagSettings()` dichiara `effortLevel` senza quel valore, quindi passa l'equivalente `{ ultracode: true }` in TypeScript. 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.
630 673
631I valori vengono scritti nel livello flag-settings, lo stesso livello che l'opzione `settings` inline di `query()` popola all'avvio. Le impostazioni flag si trovano vicino alla parte superiore dell'[ordine di precedenza delle impostazioni](/docs/it/settings#settings-precedence): sovrascrivono le impostazioni utente, progetto e locali, e solo le impostazioni della politica gestita possono sovrascriverle. Questo è lo stesso livello che la [sezione di precedenza in pagina](#settings-precedence) chiama opzioni programmatiche.674I valori vengono scritti nel livello flag-settings, lo stesso livello che l'opzione `settings` inline di `query()` popola all'avvio. Questo è lo stesso livello che la [sezione di precedenza in pagina](#settings-precedence) chiama opzioni programmatiche.
632 675
633Le chiamate successive eseguono un shallow-merge delle chiavi di livello superiore. Una seconda chiamata con `{ permissions: {...} }` sostituisce l'intero oggetto `permissions` dalla chiamata precedente piuttosto che eseguire un deep-merge in esso. Per cancellare una chiave dal livello flag e ricadere in fonti di precedenza inferiore, passa `null` per quella chiave. Passare `undefined` non ha effetto perché la serializzazione JSON lo elimina.676Le chiamate successive eseguono un shallow-merge delle chiavi di livello superiore. Una seconda chiamata con `{ permissions: {...} }` sostituisce l'intero oggetto `permissions` dalla chiamata precedente piuttosto che eseguire un deep-merge in esso. Per cancellare una chiave dal livello flag e ricadere in fonti di precedenza inferiore, passa `null` per quella chiave. Passare `undefined` non ha effetto perché la serializzazione JSON lo elimina.
634 677
637L'esempio seguente cambia il modello attivo a metà sessione, quindi cancella l'override in modo che il modello ricada in qualsiasi cosa specifichino le impostazioni utente o progetto.680L'esempio seguente cambia il modello attivo a metà sessione, quindi cancella l'override in modo che il modello ricada in qualsiasi cosa specifichino le impostazioni utente o progetto.
638 681
639```typescript theme={null}682```typescript theme={null}
683import { query } from "@anthropic-ai/claude-agent-sdk";
684
640const q = query({ prompt: messageStream });685const q = query({ prompt: messageStream });
641 686
642// Sovrascrivi il modello per il resto della sessione687// Sovrascrivi il modello per il resto della sessione
689 models: ModelInfo[];734 models: ModelInfo[];
690 account: AccountInfo;735 account: AccountInfo;
691 fast_mode_state?: "off" | "cooldown" | "on";736 fast_mode_state?: "off" | "cooldown" | "on";
737 fast_mode_disabled_reason?: FastModeDisabledReason;
738 hooks_applied?: boolean;
692};739};
693```740```
694 741
695Quando un client invia `initialize` a una sessione che è già in esecuzione, il wrapper di risposta di controllo porta anche un array `pending_permission_requests` opzionale. Il campo si trova sul wrapper di risposta stesso, non nel payload `SDKControlInitializeResponse` sopra. Ogni voce è un messaggio `control_request` completo con la stessa forma `{ type: "control_request", request_id, request }` che la sessione trasmette per le richieste di permesso durante l'esecuzione.742`hooks_applied` segnala se Claude Code ha registrato gli `hooks` che la richiesta `initialize` ha trasportato. L'SDK invia quella richiesta una volta quando la sessione inizia e di nuovo su ogni chiamata [`reinitialize()`](#query-object). Il campo richiede Agent SDK v0.3.238 o successivo.
743
744Claude Code omette il campo quando la richiesta non ha trasportato hook. Quando la richiesta ha trasportato hook, il valore dipende dal fatto che sia la prima inizializzazione della sessione e, per una ripetuta, da come ha raggiunto la sessione:
745
746* `true`: Claude Code ha registrato gli hook. Una prima inizializzazione della sessione restituisce questo valore. Un'inizializzazione ripetuta inviata sullo stdin della CLI restituisce anche `true`. In quel caso gli hook nella nuova richiesta sostituiscono gli hook registrati in precedenza.
747* `false`: Claude Code ha ignorato gli hook. Un'inizializzazione ripetuta inviata a una sessione remota restituisce questo valore, quindi un secondo client che si unisce a una sessione non può sostituire gli hook che il primo client ha registrato.
748
749Prima di Agent SDK v0.3.238, la risposta non ha mai trasportato il campo, e Claude Code ha ignorato `hooks` su ogni inizializzazione ripetuta.
696 750
697Queste sono richieste che sono state emesse prima che il client si connettesse e sono ancora in attesa di una risposta. L'SDK legge l'array per te e invia ogni voce al tuo callback [`canUseTool`](#canusetool), lo stesso reinvio che [`reinitialize()`](#query-object) attiva dopo un gap di trasporto. Gestisci gli ID di richiesta ripetuti in modo idempotente, perché una voce può ripetere una richiesta che il callback ha già ricevuto prima che la connessione si interrompesse.751La risposta sempre segnala `fast_mode_state`, e quando qualcosa blocca [fast mode](/docs/it/fast-mode), `fast_mode_disabled_reason` trasporta il codice di motivo insieme ad esso, in modo che tu possa spiegare lo stato bloccato invece di ri-derivare la disponibilità. Entrambi i comportamenti richiedono Claude Code v2.1.219 o successivo. Prima di v2.1.219, la risposta ometteva `fast_mode_state` quando fast mode non era disponibile e non trasportava mai un motivo. Per i codici di motivo e i loro significati, vedi [`fast_mode_disabled_reason`](#sdkresultmessage) sul messaggio di risultato.
752
753Il wrapper di risposta di controllo per un `initialize` riuscito trasporta anche un array `pending_permission_requests`. Il campo si trova sul wrapper di risposta stesso, non nel payload `SDKControlInitializeResponse` sopra. Ogni voce è un messaggio `control_request` completo con la stessa forma `{ type: "control_request", request_id, request }` che la sessione trasmette per le richieste di permesso durante l'esecuzione.
754
755L'array elenca le richieste di permesso che questo processo Claude Code ha emesso e non ancora risolto. L'SDK legge l'array per te e invia ogni voce al tuo callback [`canUseTool`](#canusetool), lo stesso reinvio che [`reinitialize()`](#query-object) attiva dopo un gap di trasporto. Gestisci gli ID di richiesta ripetuti in modo idempotente, perché una voce può ripetere una richiesta che il callback ha già ricevuto prima che la connessione si interrompesse.
756
757L'array è sempre presente su una risposta `initialize` riuscita ed è vuoto quando questo processo non ha alcuna richiesta di permesso non risolta. Richiede Claude Code v2.1.268 o successivo. Le versioni precedenti potrebbero omettere il campo, quindi se analizzi il protocollo wire tu stesso, tratta un campo mancante come una CLI più vecchia piuttosto che come prova che nulla è in sospeso.
698 758
699<h3 id="sdkcontrolinterruptresponse">759<h3 id="sdkcontrolinterruptresponse">
700 `SDKControlInterruptResponse`760 `SDKControlInterruptResponse`
705```typescript theme={null}765```typescript theme={null}
706type SDKControlInterruptResponse = {766type SDKControlInterruptResponse = {
707 still_queued: string[];767 still_queued: string[];
768 cancelled?: string[];
708};769};
709```770```
710 771
711`still_queued` elenca gli UUID dei messaggi utente che sopravvivono all'interruzione: messaggi ancora nella coda, più qualsiasi batch già rimosso dalla coda per il turno successivo ma non ancora raggiungibile dall'interruzione. Ognuno viene eseguito come il suo turno dopo l'interruzione a meno che non lo annulli per primo. Usa la ricevuta per decidere se rinviare qualcosa; rinviare un messaggio che è già elencato produce un turno duplicato.772`still_queued` elenca gli UUID dei messaggi utente che erano in sospeso quando l'interruzione è arrivata: messaggi ancora nella coda, più qualsiasi messaggio Claude Code aveva già tolto dalla coda per il turno successivo. Una volta che il primo turno della sessione ha iniziato, Claude Code elabora i messaggi elencati dopo l'interruzione a meno che non li annulli per primo, e può unire diversi in un turno. Se interrompi prima che il primo turno inizi, Claude Code interrompe quel turno non appena inizia, e i messaggi elencati in quel turno non ricevono risposta.
773
774Usa la ricevuta per decidere se rinviare qualcosa. Un messaggio elencato che non annulli entra nella conversazione indipendentemente dal fatto che riceva una risposta, quindi rinviarlo lo consegna a Claude due volte.
712 775
713Interpreta l'elenco con questi avvertimenti:776Interpreta l'elenco con questi avvertimenti:
714 777
716* Solo i messaggi del thread principale sono elencati. I messaggi indirizzati a un subagente sono fuori portata.779* Solo i messaggi del thread principale sono elencati. I messaggi indirizzati a un subagente sono fuori portata.
717* L'elenco può includere UUID che il tuo client non ha mai inviato, come i trigger di [attività pianificate](/docs/it/scheduled-tasks). Ignora gli UUID che non riconosci invece di trattarli come un errore.780* L'elenco può includere UUID che il tuo client non ha mai inviato, come i trigger di [attività pianificate](/docs/it/scheduled-tasks). Ignora gli UUID che non riconosci invece di trattarli come un errore.
718 781
782Un client che guida il protocollo di controllo della CLI direttamente, piuttosto che tramite `interrupt()`, può impostare `cancel_queued: true` sulla richiesta di controllo `interrupt`. Claude Code v2.1.219 e successivo pubblicizza il supporto con la capacità `interrupt_cancel_queued_v1` in [`SDKSystemMessage.capabilities`](#sdksystemmessage); le CLI più vecchie ignorano il campo e lasciano i messaggi in coda per funzionare come al solito. Un tale interruzione cancella anche ogni messaggio che altrimenti sarebbe elencato sotto `still_queued`: la ricevuta li elenca sotto `cancelled` invece, `still_queued` è vuoto, e nessuno di loro viene eseguito.
783
784L'elenco `cancelled` trasporta gli stessi avvertimenti di `still_queued`. Il metodo `interrupt()` non invia mai `cancel_queued`, quindi le ricevute che si risolve non trasportano `cancelled`.
785
719La ricevuta è uno snapshot scattato nel momento in cui l'interruzione viene elaborata, e su un'interruzione pulita arriva prima del [`SDKResultMessage`](#sdkresultmessage) del turno interrotto. Leggi la ricevuta piuttosto che ispezionare la coda dopo quel risultato: il loop avvia il turno in coda successivo immediatamente, quindi la coda che ispezioni dopo il risultato è già cambiata.786La ricevuta è uno snapshot scattato nel momento in cui l'interruzione viene elaborata, e su un'interruzione pulita arriva prima del [`SDKResultMessage`](#sdkresultmessage) del turno interrotto. Leggi la ricevuta piuttosto che ispezionare la coda dopo quel risultato: il loop avvia il turno in coda successivo immediatamente, quindi la coda che ispezioni dopo il risultato è già cambiata.
720 787
788<h3 id="sdkcontrolgetcontextusageresponse">
789 `SDKControlGetContextUsageResponse`
790</h3>
791
792Tipo di ritorno di [`getContextUsage()`](#query-object). Con il `detail` predefinito, questo è lo stesso payload che Claude Code renderizza per il comando `/context` in una sessione interattiva, quindi insieme ai conteggi di token trasporta campi di visualizzazione come `color` e `gridRows` che Claude Code usa per disegnare la griglia di utilizzo `/context`.
793
794L'argomento `detail` opzionale del metodo sceglie come Claude Code conta ogni categoria. Con il predefinito, `'full'`, Claude Code conta ogni categoria con richieste API di conteggio dei token. Passa `{ detail: 'summary' }` per ottenere una risposta dall'utilizzo dell'ultima risposta e dalle stime locali. Nessuna richiesta di conteggio dei token esce, e i numeri per categoria sono approssimativi. L'argomento `detail` richiede Agent SDK v0.3.257 o successivo.
795
796Quando 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 consegna il risultato. Quel campo richiede Agent SDK v0.3.232 o successivo.
797
798```typescript theme={null}
799type SDKControlGetContextUsageResponse = {
800 categories: {
801 name: string;
802 tokens: number;
803 color: string;
804 isDeferred?: boolean;
805 }[];
806 totalTokens: number;
807 maxTokens: number;
808 rawMaxTokens: number;
809 percentage: number;
810 gridRows: {
811 color: string;
812 isFilled: boolean;
813 categoryName: string;
814 tokens: number;
815 percentage: number;
816 squareFullness: number;
817 }[][];
818 model: string;
819 memoryFiles: {
820 path: string;
821 type: string;
822 tokens: number;
823 }[];
824 mcpTools: {
825 name: string;
826 serverName: string;
827 tokens: number;
828 isLoaded?: boolean;
829 }[];
830 deferredBuiltinTools?: {
831 name: string;
832 tokens: number;
833 isLoaded: boolean;
834 }[];
835 systemTools?: {
836 name: string;
837 tokens: number;
838 }[];
839 systemPromptSections?: {
840 name: string;
841 tokens: number;
842 }[];
843 agents: {
844 agentType: string;
845 source: string;
846 tokens: number;
847 }[];
848 slashCommands?: {
849 totalCommands: number;
850 includedCommands: number;
851 tokens: number;
852 };
853 skills?: {
854 totalSkills: number;
855 includedSkills: number;
856 tokens: number;
857 skillFrontmatter: {
858 name: string;
859 source: string;
860 tokens: number;
861 }[];
862 };
863 autoCompactThreshold?: number;
864 isAutoCompactEnabled: boolean;
865 messageBreakdown?: {
866 toolCallTokens: number;
867 toolResultTokens: number;
868 attachmentTokens: number;
869 assistantMessageTokens: number;
870 userMessageTokens: number;
871 redirectedContextTokens: number;
872 unattributedTokens: number;
873 toolCallsByType: {
874 name: string;
875 callTokens: number;
876 resultTokens: number;
877 }[];
878 attachmentsByType: {
879 name: string;
880 tokens: number;
881 }[];
882 };
883 apiUsage: {
884 input_tokens: number;
885 output_tokens: number;
886 cache_creation_input_tokens: number;
887 cache_read_input_tokens: number;
888 } | null;
889};
890```
891
892Leggi l'attribuzione dei token dalle raccolte di campi:
893
894* `categories` contiene i totali per categoria.
895* `mcpTools` e `agents` attribuiscono i token ai singoli tool MCP e subagenti.
896* `memoryFiles` elenca ogni file di memoria caricato con il suo costo.
897* `skills.skillFrontmatter` attribuisce i token della lista di skill a ogni skill inclusa. I conteggi per skill misurano ogni voce di lista di skill come Claude Code effettivamente la invia, che può essere più breve del frontmatter completo della skill. Confronta `skills.totalSkills` con `skills.includedSkills` per vedere se ogni skill scoperta ha fatto nella lista.
898
899`totalTokens` è l'utilizzo di contesto corrente della sessione, e `maxTokens` è la finestra rispetto alla quale l'utilizzo viene misurato. Quella finestra è la finestra di contesto del modello, o la finestra di auto-compattazione inferiore quando una si applica. `rawMaxTokens` trasporta lo stesso valore di `maxTokens`, e `percentage` è `totalTokens` come percentuale arrotondata di quella finestra.
900
901Claude Code lascia i diagnostici opzionali `deferredBuiltinTools`, `systemTools`, e `systemPromptSections` non impostati, quindi aspettati che siano assenti anche se il tipo li dichiara.
902
903<h3 id="sdkcontrolreadfileresponse">
904 `SDKControlReadFileResponse`
905</h3>
906
907Tipo di ritorno di [`readFile()`](#query-object).
908
909```typescript theme={null}
910type SDKControlReadFileResponse = {
911 contents: string;
912 absPath: string;
913 truncated?: boolean;
914 encoding?: 'base64';
915};
916```
917
918`contents` contiene il testo del file, o dati base64 quando hai richiesto `encoding: 'base64'`; il campo `encoding` della risposta è impostato a `'base64'` in quel caso. `absPath` è il percorso assoluto risolto. `truncated` è impostato quando il file era più lungo del limite `maxBytes` e i contenuti sono stati tagliati a quel limite.
919
920<h4 id="what-readfile-can-read">
921 Cosa `readFile()` può leggere
922</h4>
923
924`readFile()` serve un insieme più ristretto di file rispetto allo strumento Read:
925
926* Un file regolare all'interno di una delle directory di lavoro della sessione, come `cwd` e `additionalDirectories`
927* Alcuni dei file di Claude Code stesso per la sessione, come i risultati dei tool
928
929Le regole di negazione e 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 altra cosa la chiamata si risolve con `null`.
930
931<h3 id="sdkcontrolreloadskillsresponse">
932 `SDKControlReloadSkillsResponse`
933</h3>
934
935Tipo di ritorno di [`reloadSkills()`](#query-object).
936
937```typescript theme={null}
938type SDKControlReloadSkillsResponse = {
939 skills: SlashCommand[];
940};
941```
942
943`skills` elenca le skill disponibili dopo il ricaricamento, nella stessa forma [`SlashCommand`](#slashcommand) che `supportedCommands()` restituisce.
944
721<h3 id="agentdefinition">945<h3 id="agentdefinition">
722 `AgentDefinition`946 `AgentDefinition`
723</h3>947</h3>
744```968```
745 969
746| Campo | Obbligatorio | Descrizione |970| Campo | Obbligatorio | Descrizione |
747| :------------------------------------ | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |971| :------------------------------------ | :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
748| `description` | Sì | Descrizione in linguaggio naturale di quando usare questo agente |972| `description` | Sì | Descrizione in linguaggio naturale di quando usare questo agente |
749| `tools` | No | Array di nomi di tool consentiti. Se omesso, eredita tutti i tool dal genitore. Per precaricare Skills nel contesto dell'agente, usa il campo `skills` piuttosto che elencando `'Skill'` qui |973| `tools` | No | Array di nomi di tool consentiti. Se omesso, eredita ogni [tool disponibile ai subagenti](/docs/it/sub-agents#available-tools). Per precaricare Skills nel contesto dell'agente, usa il campo `skills` piuttosto che elencando `'Skill'` qui |
750| `disallowedTools` | No | Array di nomi di tool da esplicitamente disabilitare per questo agente. Sono accettati anche i modelli a livello di server MCP: `mcp__server` o `mcp__server__*` rimuove ogni tool da quel server, e `mcp__*` rimuove ogni tool MCP da qualsiasi server |974| `disallowedTools` | No | Array di nomi di tool da esplicitamente disabilitare per questo agente. Sono accettati anche i modelli a livello di server MCP: `mcp__server` o `mcp__server__*` rimuove ogni tool da quel server, e `mcp__*` rimuove ogni tool MCP da qualsiasi server |
751| `prompt` | Sì | Il prompt di sistema dell'agente |975| `prompt` | Sì | Il prompt di sistema dell'agente |
752| `model` | No | Override del modello per questo agente. Accetta un alias come `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, o un ID modello completo. Se omesso o `'inherit'`, usa il modello principale |976| `model` | No | Override del modello per questo agente. Accetta un alias come `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, o un ID modello completo. `'inherit'` usa il modello principale. Quando lo ometti, Claude Code sceglie il modello nell'[ordine del modello del subagente](/docs/it/sub-agents#choose-a-model) |
753| `mcpServers` | No | Specifiche del server MCP per questo agente |977| `mcpServers` | No | Specifiche del server MCP per questo agente |
754| `skills` | No | Array di nomi di skill da precaricare nel contesto dell'agente |978| `skills` | No | Array di nomi di skill da precaricare nel contesto dell'agente |
755| `initialPrompt` | No | Auto-inviato come il primo turno utente quando questo agente viene eseguito come agente del thread principale |979| `initialPrompt` | No | Auto-inviato come il primo turno utente quando questo agente viene eseguito come agente del thread principale |
757| `background` | No | Esegui questo agente come un'attività di background non bloccante quando invocato |981| `background` | No | Esegui questo agente come un'attività di background non bloccante quando invocato |
758| `memory` | No | Fonte di memoria per questo agente: `'user'`, `'project'`, o `'local'` |982| `memory` | No | Fonte di memoria per questo agente: `'user'`, `'project'`, o `'local'` |
759| `effort` | No | Livello di sforzo di ragionamento per questo agente. Accetta un livello denominato o un numero intero |983| `effort` | No | Livello di sforzo di ragionamento per questo agente. Accetta un livello denominato o un numero intero |
760| `permissionMode` | No | Modalità di permesso per l'esecuzione dei tool all'interno di questo agente. Vedi [`PermissionMode`](#permissionmode) |984| `permissionMode` | No | Modalità di permesso per l'esecuzione dei tool all'interno di questo agente. Le [regole di eredità del subagente](/docs/it/agent-sdk/permissions#available-modes) decidono quando si applica. Vedi [`PermissionMode`](#permissionmode) |
761| `criticalSystemReminder_EXPERIMENTAL` | No | Sperimentale: Promemoria critico aggiunto al prompt di sistema |985| `criticalSystemReminder_EXPERIMENTAL` | No | Sperimentale: Promemoria critico aggiunto al prompt di sistema |
762 986
763<h3 id="agentmcpserverspec">987<h3 id="agentmcpserverspec">
783```1007```
784 1008
785| Valore | Descrizione | Posizione |1009| Valore | Descrizione | Posizione |
786| :---------- | :---------------------------------------------------------------- | :---------------------------- |1010| :---------- | :--------------------------------------------------------------------------------------------- | :---------------------------- |
787| `'user'` | Impostazioni globali dell'utente | `~/.claude/settings.json` |1011| `'user'` | Impostazioni globali dell'utente | `~/.claude/settings.json` |
788| `'project'` | Impostazioni del progetto condivise (controllate dalla versione) | `.claude/settings.json` |1012| `'project'` | Impostazioni del progetto condivise (controllate dalla versione) | `.claude/settings.json` |
789| `'local'` | Impostazioni del progetto locale (non controllate dalla versione) | `.claude/settings.local.json` |1013| `'local'` | Impostazioni del progetto locale, gitignorate quando Claude Code salva un'impostazione in essa | `.claude/settings.local.json` |
790 1014
791<h4 id="default-behavior">1015<h4 id="default-behavior">
792 Comportamento predefinito1016 Comportamento predefinito
793</h4>1017</h4>
794 1018
795Quando `settingSources` è omesso o `undefined`, `query()` carica le stesse impostazioni del filesystem del CLI Claude Code: utente, progetto e locale. Le impostazioni della politica gestita vengono caricate in tutti i casi; le impostazioni gestite dal server vengono recuperate quando la sessione si autentica con una credenziale organizzativa su una [configurazione idonea](/docs/it/server-managed-settings#platform-availability). Vedi [Cosa settingSources non controlla](/docs/it/agent-sdk/claude-code-features#what-settingsources-does-not-control) per gli input che vengono letti indipendentemente da questa opzione, e come disabilitarli.1019Quando `settingSources` è omesso o `undefined`, `query()` carica le stesse impostazioni del filesystem del CLI Claude Code: utente, progetto e locale. Vedi [Cosa settingSources non controlla](/docs/it/agent-sdk/claude-code-features#what-settingsources-does-not-control) per gli input che vengono letti indipendentemente da questa opzione, e come disabilitarli.
796 1020
797<h4 id="why-use-settingsources">1021<h4 id="why-use-settingsources">
798 Perché usare settingSources1022 Perché usare settingSources
801**Disabilita le impostazioni del filesystem:**1025**Disabilita le impostazioni del filesystem:**
802 1026
803```typescript theme={null}1027```typescript theme={null}
1028import { query } from "@anthropic-ai/claude-agent-sdk";
1029
804// Non caricare le impostazioni utente, progetto o locali dal disco1030// Non caricare le impostazioni utente, progetto o locali dal disco
805const result = query({1031const result = query({
806 prompt: "Analyze this code",1032 prompt: "Analyze this code",
808});1034});
809```1035```
810 1036
811**Carica tutte le impostazioni del filesystem esplicitamente:**
812
813```typescript theme={null}
814const result = query({
815 prompt: "Analyze this code",
816 options: {
817 settingSources: ["user", "project", "local"] // Carica tutte le impostazioni
818 }
819});
820```
821
822**Carica solo fonti di impostazioni specifiche:**1037**Carica solo fonti di impostazioni specifiche:**
823 1038
824```typescript theme={null}1039```typescript theme={null}
1040import { query } from "@anthropic-ai/claude-agent-sdk";
1041
825// Carica solo le impostazioni del progetto, ignora utente e locale1042// Carica solo le impostazioni del progetto, ignora utente e locale
826const result = query({1043const result = query({
827 prompt: "Run CI checks",1044 prompt: "Run CI checks",
831});1048});
832```1049```
833 1050
834**Ambienti di test e CI:**1051Per caricare le istruzioni del progetto CLAUDE.md, includi `"project"` in `settingSources`. Vedi [Modifica i prompt di sistema](/docs/it/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions) per come il caricamento di CLAUDE.md interagisce con le opzioni del prompt di sistema.
835
836```typescript theme={null}
837// Assicura un comportamento coerente in CI escludendo le impostazioni locali
838const result = query({
839 prompt: "Run tests",
840 options: {
841 settingSources: ["project"], // Solo impostazioni condivise dal team
842 permissionMode: "bypassPermissions"
843 }
844});
845```
846
847**Applicazioni solo SDK:**
848
849```typescript theme={null}
850// Definisci tutto a livello di programmazione.
851// Passa [] per rinunciare alle fonti di impostazioni del filesystem.
852const result = query({
853 prompt: "Review this PR",
854 options: {
855 settingSources: [],
856 agents: {
857 /* ... */
858 },
859 mcpServers: {
860 /* ... */
861 },
862 allowedTools: ["Read", "Grep", "Glob"]
863 }
864});
865```
866
867**Caricamento delle istruzioni del progetto CLAUDE.md:**
868
869```typescript theme={null}
870// Carica le impostazioni del progetto per includere i file CLAUDE.md
871const result = query({
872 prompt: "Add a new feature following project conventions",
873 options: {
874 systemPrompt: {
875 type: "preset",
876 preset: "claude_code" // Usa il prompt di sistema di Claude Code
877 },
878 settingSources: ["project"], // Carica CLAUDE.md dalla directory del progetto
879 allowedTools: ["Read", "Write", "Edit"]
880 }
881});
882```
883 1052
884<h4 id="settings-precedence">1053<h4 id="settings-precedence">
885 Precedenza delle impostazioni1054 Precedenza delle impostazioni
904 | "bypassPermissions" // Bypass di tutti i controlli di permesso; le regole di richiesta esplicita richiedono comunque1073 | "bypassPermissions" // Bypass di tutti i controlli di permesso; le regole di richiesta esplicita richiedono comunque
905 | "plan" // Modalità di pianificazione - esplora senza modificare1074 | "plan" // Modalità di pianificazione - esplora senza modificare
906 | "dontAsk" // Non richiedere i permessi, nega se non pre-approvato1075 | "dontAsk" // Non richiedere i permessi, nega se non pre-approvato
907 | "auto"; // Usa un classificatore di modello per approvare o negare ogni chiamata di tool1076 | "auto"; // Classificatore di modello approva o nega i prompt di permesso
908```1077```
909 1078
910<h3 id="canusetool">1079<h3 id="canusetool">
915 1084
916La funzione è la sostituzione SDK per il prompt di permesso interattivo: viene invocata solo quando il [flusso di valutazione del permesso](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated) si risolve in un prompt. Le chiamate di tool già approvate da una voce `allowedTools`, una regola di autorizzazione nelle impostazioni, o la modalità di permesso, come `acceptEdits` o `bypassPermissions`, non la invocano mai. Per controllare ogni chiamata di tool, usa un [hook `PreToolUse`](/docs/it/agent-sdk/hooks) invece.1085La funzione è la sostituzione SDK per il prompt di permesso interattivo: viene invocata solo quando il [flusso di valutazione del permesso](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated) si risolve in un prompt. Le chiamate di tool già approvate da una voce `allowedTools`, una regola di autorizzazione nelle impostazioni, o la modalità di permesso, come `acceptEdits` o `bypassPermissions`, non la invocano mai. Per controllare ogni chiamata di tool, usa un [hook `PreToolUse`](/docs/it/agent-sdk/hooks) invece.
917 1086
918`AskUserQuestion`, tool MCP contrassegnati [`requiresUserInteraction`](/docs/it/mcp#require-approval-for-a-specific-tool), e tool connettore [impostati dalla tua organizzazione su `ask`](/docs/it/mcp#organization-controls-on-connector-tools) la raggiungono anche quando una regola di autorizzazione corrisponde. In modalità `dontAsk` queste chiamate vengono negate invece, senza invocarla.1087Una regola di autorizzazione non pre-approva le [azioni che nessuna modalità auto-approva](/docs/it/permission-modes#actions-no-mode-auto-approves); vedi [Come i permessi vengono valutati](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated) per quali di loro raggiungono il callback e cosa succede in modalità `dontAsk` e `auto`.
919 1088
920```typescript theme={null}1089```typescript theme={null}
921type CanUseTool = (1090type CanUseTool = (
984```1153```
985 1154
986| Campo | Tipo | Descrizione |1155| Campo | Tipo | Descrizione |
987| :------------------------------ | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1156| :------------------------------ | :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
988| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | Acconsente al campo `preview` su [`AskUserQuestion`](/docs/it/agent-sdk/user-input#question-format) opzioni e imposta il suo formato di contenuto. Se non impostato, Claude non emette anteprime |1157| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | Acconsente al campo `preview` su [`AskUserQuestion`](/docs/it/agent-sdk/user-input#question-format) opzioni e imposta il suo formato di contenuto. Quando non impostato, Claude non emette anteprime |
989 1158
990<h3 id="mcpserverconfig">1159<h3 id="mcpserverconfig">
991 `McpServerConfig`1160 `McpServerConfig`
1046type McpSdkServerConfigWithInstance = {1215type McpSdkServerConfigWithInstance = {
1047 type: "sdk";1216 type: "sdk";
1048 name: string;1217 name: string;
1218 timeout?: number;
1049 instance: McpServer;1219 instance: McpServer;
1050};1220};
1051```1221```
1077```1247```
1078 1248
1079| Campo | Tipo | Descrizione |1249| Campo | Tipo | Descrizione |
1080| :----------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1250| :----------------- | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1081| `type` | `'local'` | Deve essere `'local'` (attualmente supportati solo plugin locali) |1251| `type` | `'local'` | Deve essere `'local'` (attualmente supportati solo plugin locali) |
1082| `path` | `string` | Percorso assoluto o relativo alla directory del plugin |1252| `path` | `string` | Percorso assoluto o relativo alla directory del plugin |
1083| `skipMcpDiscovery` | `boolean` | Quando `true`, l'SDK carica skills, hooks, agenti e comandi da questo plugin ma non legge il suo `.mcp.json` o il manifest `mcpServers`. Imposta questo quando la tua applicazione possiede le connessioni MCP del plugin. |1253| `skipMcpDiscovery` | `boolean` | Quando `true`, l'SDK carica skill, hook, agenti e comandi da questo plugin ma non legge il suo `.mcp.json` o il manifest `mcpServers`. Imposta questo quando la tua applicazione possiede le connessioni MCP del plugin. |
1084 1254
1085**Esempio:**1255**Esempio:**
1086 1256
1157 message: BetaMessage; // Dall'SDK Anthropic1327 message: BetaMessage; // Dall'SDK Anthropic
1158 parent_tool_use_id: string | null;1328 parent_tool_use_id: string | null;
1159 error?: SDKAssistantMessageError;1329 error?: SDKAssistantMessageError;
1330 aborted?: true;
1331 timestamp?: string;
1332 context_usage?: SDKContextUsage;
1333 user_message_uuid?: string;
1334 user_message_uuids?: string[];
1160};1335};
1161```1336```
1162 1337
1163Il campo `message` è un [`BetaMessage`](https://platform.claude.com/docs/it/api/messages/create) dall'SDK Anthropic. Include campi come `id`, `content`, `model`, `stop_reason` e `usage`.1338Il campo `message` è un [`BetaMessage`](https://platform.claude.com/docs/it/api/messages/create) dall'SDK Anthropic. Include campi come `id`, `content`, `model`, `stop_reason` e `usage`.
1164 1339
1165`SDKAssistantMessageError` è uno di: `'authentication_failed'`, `'oauth_org_not_allowed'`, `'billing_error'`, `'rate_limit'`, `'overloaded'`, `'invalid_request'`, `'model_not_found'`, `'server_error'`, `'max_output_tokens'`, o `'unknown'`. `'model_not_found'` significa che il modello selezionato non esiste o non è disponibile per il tuo account o deployment. `'overloaded'` significa che l'API ha restituito un 529 perché il server è al massimo della capacità, a differenza di `'rate_limit'`, che è un 429 rispetto alla tua quota.1340`SDKAssistantMessageError` è uno di: `'authentication_failed'`, `'oauth_org_not_allowed'`, `'account_on_hold'`, `'billing_error'`, `'rate_limit'`, `'overloaded'`, `'invalid_request'`, `'model_not_found'`, `'server_error'`, `'max_output_tokens'`, `'cloud_credential_error'`, o `'unknown'`. Quattro di questi valori significano più di quanto i loro nomi dicono:
1341
1342* `'model_not_found'`: il modello selezionato non esiste o non è disponibile per il tuo account o deployment
1343* `'overloaded'`: l'API ha restituito un 529 perché il server è al massimo della capacità, a differenza di `'rate_limit'`, che è un 429 rispetto alla tua quota
1344* `'account_on_hold'`: [il tuo account è in sospeso](/docs/it/errors#your-account-is-on-hold)
1345* `'cloud_credential_error'`: Claude Code non ha potuto ottenere credenziali AWS o Google Cloud utilizzabili sulla macchina su cui viene eseguito, quindi nessuna richiesta ha raggiunto il provider cloud. La causa solita è un accesso al cloud scaduto o mai completato su quella macchina, anche se un servizio di credenziali brevemente irraggiungibile segnala lo stesso valore. Vedi [Impossibile caricare le credenziali AWS o Google Cloud](/docs/it/errors#could-not-load-aws-or-google-cloud-credentials). Richiede TypeScript Agent SDK v0.3.267 o successivo, che raggruppa Claude Code v2.1.267
1346
1347`aborted` è `true` quando un'interruzione o un'interruzione 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.
1348
1349Claude Code imposta `user_message_uuid` e `user_message_uuids` sul primo messaggio dell'assistente del turno, secondo le condizioni in [`user_message_uuid`](#user_message_uuid).
1350
1351`timestamp` è l'ora ISO 8601 quando il contenuto del messaggio ha finito di generarsi sul processo che lo ha prodotto. Il valore proviene dall'orologio di quella macchina, quindi usalo solo per la visualizzazione e non ordinare i messaggi per esso. Un turno API può produrre diversi messaggi dell'assistente che condividono un `message.id`, ciascuno con il proprio `timestamp`. Quando il campo è assente, ricadi al momento in cui hai ricevuto il messaggio.
1352
1353`context_usage` è una copia strutturata del rapporto `/context`, tipizzata come [`SDKContextUsage`](#sdkcontextusage), e richiede Agent SDK v0.3.232 o successivo. Quando invii `/context` come prompt, Claude Code consegna il rapporto come messaggio dell'assistente il cui `message.content` contiene la tabella markdown, e allega `context_usage` a quello stesso messaggio. Claude Code non imposta il campo su nessun altro messaggio dell'assistente, e le versioni precedenti consegnano la tabella `/context` senza di esso, quindi leggi la suddivisione dal campo quando è presente e ricadi al testo markdown quando non lo è.
1166 1354
1167<h3 id="sdkusermessage">1355<h3 id="sdkusermessage">
1168 `SDKUserMessage`1356 `SDKUserMessage`
1190 1378
1191Per lo strumento `Agent`, `tool_use_result` è [`AgentOutput`](#agent-2). Su un risultato `completed`, `content` contiene il rapporto del subagente senza l'ID agente e il trailer di utilizzo che Claude Code aggiunge al testo `tool_result`, quindi esegui il rendering da `tool_use_result` invece di analizzare quel testo.1379Per lo strumento `Agent`, `tool_use_result` è [`AgentOutput`](#agent-2). Su un risultato `completed`, `content` contiene il rapporto del subagente senza l'ID agente e il trailer di utilizzo che Claude Code aggiunge al testo `tool_result`, quindi esegui il rendering da `tool_use_result` invece di analizzare quel testo.
1192 1380
1381Per uno strumento MCP il cui risultato contiene blocchi `resource_link`, `tool_use_result` è un oggetto con un array `resourceLinks` di voci [`SDKMcpResourceLink`](#sdkmcpresourcelink). Claude riceve ogni link come una riga di testo nel blocco `tool_result`, quindi leggi `resourceLinks` per rendere i file che il server ha restituito invece di analizzare quel testo. Claude Code omette `resourceLinks` quando il risultato non ha link e sui risultati dei subagenti, mantiene al massimo 50 link per risultato, e smette di aggiungere link una volta che l'array raggiunge 64 KiB di JSON serializzato. `resourceLinks` richiede Agent SDK v0.3.257 o successivo.
1382
1193<h3 id="sdkusermessagereplay">1383<h3 id="sdkusermessagereplay">
1194 `SDKUserMessageReplay`1384 `SDKUserMessageReplay`
1195</h3>1385</h3>
1234 stop_reason: string | null;1424 stop_reason: string | null;
1235 ttft_ms?: number;1425 ttft_ms?: number;
1236 ttft_stream_ms?: number;1426 ttft_stream_ms?: number;
1427 user_message_uuid?: string;
1428 user_message_uuids?: string[];
1429 request_sent_wall_ms?: number;
1430 first_content_frame_ms?: number;
1431 first_stream_post_ms?: number;
1432 first_stream_post_ack_ms?: number;
1433 first_stream_post_wall_ms?: number;
1237 total_cost_usd: number;1434 total_cost_usd: number;
1238 usage: NonNullableUsage;1435 usage: NonNullableUsage;
1239 modelUsage: { [modelName: string]: ModelUsage };1436 modelUsage: { [modelName: string]: ModelUsage };
1240 permission_denials: SDKPermissionDenial[];1437 permission_denials: SDKPermissionDenial[];
1438 queued_turn_count?: number;
1241 structured_output?: unknown;1439 structured_output?: unknown;
1242 deferred_tool_use?: { id: string; name: string; input: Record<string, unknown> };1440 deferred_tool_use?: { id: string; name: string; input: Record<string, unknown> };
1243 terminal_reason?: TerminalReason;1441 terminal_reason?: TerminalReason;
1244 fast_mode_state?: FastModeState;1442 fast_mode_state?: FastModeState;
1443 fast_mode_disabled_reason?: FastModeDisabledReason;
1245 origin?: SDKMessageOrigin;1444 origin?: SDKMessageOrigin;
1246 }1445 }
1247 | {1446 | {
1262 usage: NonNullableUsage;1461 usage: NonNullableUsage;
1263 modelUsage: { [modelName: string]: ModelUsage };1462 modelUsage: { [modelName: string]: ModelUsage };
1264 permission_denials: SDKPermissionDenial[];1463 permission_denials: SDKPermissionDenial[];
1464 queued_turn_count?: number;
1265 errors: string[];1465 errors: string[];
1466 user_message_uuid?: string;
1467 user_message_uuids?: string[];
1266 terminal_reason?: TerminalReason;1468 terminal_reason?: TerminalReason;
1267 fast_mode_state?: FastModeState;1469 fast_mode_state?: FastModeState;
1470 fast_mode_disabled_reason?: FastModeDisabledReason;
1268 origin?: SDKMessageOrigin;1471 origin?: SDKMessageOrigin;
1269 };1472 };
1270```1473```
1274* `api_error_status`: il codice di stato HTTP dell'errore API che ha terminato la conversazione. Assente o `null` quando il turno è terminato senza un errore API.1477* `api_error_status`: il codice di stato HTTP dell'errore API che ha terminato la conversazione. Assente o `null` quando il turno è terminato senza un errore API.
1275* `ttft_ms`: tempo al primo token in millisecondi, misurato quando arriva il primo messaggio dell'assistente completo. Presente solo sul ramo di successo.1478* `ttft_ms`: tempo al primo token in millisecondi, misurato quando arriva il primo messaggio dell'assistente completo. Presente solo sul ramo di successo.
1276* `ttft_stream_ms`: tempo in millisecondi fino al primo evento di flusso `message_start`, quando il flusso di risposta si apre. Inferiore a `ttft_ms`; il divario tra i due è il tempo impiegato per lo streaming del primo messaggio. Presente solo sul ramo di successo.1479* `ttft_stream_ms`: tempo in millisecondi fino al primo evento di flusso `message_start`, quando il flusso di risposta si apre. Inferiore a `ttft_ms`; il divario tra i due è il tempo impiegato per lo streaming del primo messaggio. Presente solo sul ramo di successo.
1480* `user_message_uuid`: l'`uuid` del messaggio che hai inviato a cui questo turno ha risposto. Vedi [`user_message_uuid`](#user_message_uuid) per quali risultati lo contengono.
1481* `user_message_uuids`: gli `uuid` di ogni messaggio che hai inviato a cui Claude Code ha risposto in questo turno. Vedi [`user_message_uuids`](#user_message_uuids).
1482* `request_sent_wall_ms`: millisecondi di epoca in cui Claude Code ha inviato la richiesta API, per join rispetto ai timestamp lato server. Presente solo insieme a [`user_message_uuid`](#user_message_uuid), su un risultato di successo con `is_error` false il cui turno ha inviato una richiesta API.
1483* `first_content_frame_ms`: tempo in millisecondi fino al primo evento di flusso `content_block_start` o `content_block_delta`, contando i blocchi di pensiero come contenuto. Presente sul ramo di successo solo, quando `is_error` è false. Richiede Agent SDK v0.3.260 o successivo.
1484* `first_stream_post_ms`, `first_stream_post_ack_ms`, `first_stream_post_wall_ms`: tempi per il caricamento del primo evento di flusso del turno. Claude Code li registra solo nelle sessioni che trasmette a claude.ai, come [sessioni cloud](/docs/it/claude-code-on-the-web), e i risultati che `query()` produce non li contengono. Richiede Agent SDK v0.3.260 o successivo.
1485* `usage`: solo ciclo agente principale. Esclude le chiamate di subagente e modello ausiliario, ed è per turno nelle sessioni di input in streaming. Preferisci `modelUsage` per la contabilità di token/costo.
1486* `modelUsage`: totali per modello per ogni chiamata di modello effettuata attraverso la pipeline di query durante questa chiamata `query()`, incluso il ciclo principale, i subagenti e le chiamate interne come la compattazione e gli agenti Workflow. Le chiamate helper al di fuori di quella pipeline, come il classificatore di autorizzazione e le richieste di conteggio dei token, sono escluse. Nelle sessioni di input in streaming i totali sono cumulativi tra i turni, quindi leggi il risultato più recente piuttosto che sommare tra i risultati. Vedi [Traccia i costi in modalità input in streaming](/docs/it/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode) per i reset e [Recupera i totali dopo un arresto anomalo della sessione](/docs/it/agent-sdk/cost-tracking#recover-totals-after-a-session-crash) per i risultati azzerati.
1487* `total_cost_usd`: costo stimato cumulativo in USD per questa chiamata `query()`, coprendo le stesse chiamate di `modelUsage` e reset negli stessi punti. È una stima, non un estratto conto di fatturazione. Vedi [Traccia costo e utilizzo](/docs/it/agent-sdk/cost-tracking) per le avvertenze di accuratezza.
1488* `queued_turn_count`: il numero di messaggi che hai inviato con `origin: { kind: "human" }` che sono ancora in attesa quando Claude Code ha prodotto il risultato. Vedi [`queued_turn_count`](#queued_turn_count) per cosa significano `0` e un campo assente.
1277* `terminal_reason`: il motivo per cui il ciclo è terminato. Uno di `"completed"`, `"max_turns"`, `"tool_deferred"`, `"aborted_streaming"`, `"aborted_tools"`, `"hook_stopped"`, `"stop_hook_prevented"`, `"background_requested"`, `"blocking_limit"`, `"rapid_refill_breaker"`, `"prompt_too_long"`, `"image_error"`, `"model_error"`, `"api_error"`, `"malformed_tool_use_exhausted"`, `"budget_exhausted"`, `"structured_output_retry_exhausted"`, `"tool_deferred_unavailable"`, o `"turn_setup_failed"`.1489* `terminal_reason`: il motivo per cui il ciclo è terminato. Uno di `"completed"`, `"max_turns"`, `"tool_deferred"`, `"aborted_streaming"`, `"aborted_tools"`, `"hook_stopped"`, `"stop_hook_prevented"`, `"background_requested"`, `"blocking_limit"`, `"rapid_refill_breaker"`, `"prompt_too_long"`, `"image_error"`, `"model_error"`, `"api_error"`, `"malformed_tool_use_exhausted"`, `"budget_exhausted"`, `"structured_output_retry_exhausted"`, `"tool_deferred_unavailable"`, o `"turn_setup_failed"`.
1278* `fast_mode_state`: uno di `"on"`, `"off"`, o `"cooldown"`.1490* `fast_mode_state`: uno di `"on"`, `"off"`, o `"cooldown"`.
1491* `fast_mode_disabled_reason`: il motivo per cui [fast mode](/docs/it/fast-mode) non è disponibile in questo momento. Assente quando nulla blocca fast mode, anche se una richiesta potrebbe comunque essere eseguita a velocità standard. Durante il cooldown dopo un limite di velocità fast mode, Claude Code segnala `fast_mode_state: "cooldown"` senza codice di motivo e riabilita fast mode quando il cooldown scade. Richiede Claude Code v2.1.219 o successivo.
1492
1493Usa il codice di motivo per spiegare perché fast mode è disattivato nella tua interfaccia utente invece di derivare nuovamente la disponibilità. Ogni codice nomina il controllo che ha bloccato fast mode:
1279 1494
1280Il campo `origin` inoltro l'[`SDKMessageOrigin`](#sdkmessageorigin) del messaggio utente che ha attivato questo risultato. Quando un'attività in background finisce e l'SDK inietta un turno di follow-up sintetico, il `SDKResultMessage` risultante contiene `origin: { kind: "task-notification" }`. Controlla questo campo per distinguere i risultati che rispondono al tuo prompt dai risultati emessi per i follow-up di attività in background, in modo da poter instradare o sopprimere questi ultimi. Il campo è assente per i risultati emessi prima di qualsiasi turno utente, come gli errori di avvio.1495| Codice di motivo | Significato |
1496| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1497| `free` | L'account non ha l'abbonamento a pagamento o i crediti di utilizzo che fast mode richiede |
1498| `preference` | L'organizzazione ha disabilitato fast mode |
1499| `extra_usage_disabled` | I crediti di utilizzo sono disattivati per l'account |
1500| `network_error` | Il [controllo di disponibilità](/docs/it/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) non ha potuto raggiungere `api.anthropic.com` |
1501| `unknown` | Claude Code non ha potuto determinare la disponibilità |
1502| `not_first_party` | La sessione utilizza un provider diverso dall'API Anthropic |
1503| `disabled_by_env` | [`CLAUDE_CODE_DISABLE_FAST_MODE`](/docs/it/env-vars) è impostato |
1504| `model_not_allowed` | Il modello Opus fast mode non è nella lista di autorizzazione [`availableModels`](/docs/it/model-config#restrict-model-selection) dell'organizzazione |
1505| `sdk_opt_in_required` | La sessione non ha acconsentito a fast mode: passa `fastMode: true` nell'opzione [`settings`](#options) o tramite [`applyFlagSettings()`](#applyflagsettings) |
1506| `pending` | Il controllo di disponibilità non è ancora completato |
1507
1508La stessa coppia di campi appare su [`SDKSystemMessage`](#sdksystemmessage) e su [`SDKControlInitializeResponse`](#sdkcontrolinitializeresponse), quindi puoi leggere lo stato fast mode prima del primo turno.
1509
1510Il campo `origin` inoltro l'[`SDKMessageOrigin`](#sdkmessageorigin) del messaggio utente che ha attivato questo risultato. Quando l'SDK inietta un turno di follow-up sintetico, come per un'attività finita in background, il `SDKResultMessage` risultante contiene `origin: { kind: "task-notification" }`. Le routine il cui trigger si è attivato e i messaggi verificati dal server dalle tue altre sessioni arrivano con questo tipo anche, ciascuno con il `subkind` descritto in [Subkind di notifica attività](#task-notification-subkinds). Controlla `kind` per distinguere i risultati che rispondono al tuo prompt dai follow-up iniettati prima di instradare o sopprimere questi ultimi.
1511
1512Il campo è assente per i risultati emessi prima di qualsiasi turno utente, come gli errori di avvio.
1281 1513
1282Quando un hook `PreToolUse` restituisce `permissionDecision: "defer"`, il risultato ha `stop_reason: "tool_deferred"` e `deferred_tool_use` contiene l'`id`, il `name` e l'`input` del tool in sospeso. Leggi questo campo per visualizzare la richiesta nella tua interfaccia utente, quindi riprendi con lo stesso `session_id` per continuare. Vedi [Rinvia una chiamata di tool per dopo](/docs/it/hooks#defer-a-tool-call-for-later) per il percorso completo.1514Quando un hook `PreToolUse` restituisce `permissionDecision: "defer"`, il risultato ha `stop_reason: "tool_deferred"` e `deferred_tool_use` contiene l'`id`, il `name` e l'`input` del tool in sospeso. Leggi questo campo per visualizzare la richiesta nella tua interfaccia utente, quindi riprendi con lo stesso `session_id` per continuare. Vedi [Rinvia una chiamata di tool per dopo](/docs/it/hooks#defer-a-tool-call-for-later) per il percorso completo.
1283 1515
1516<h4 id="user_message_uuid">
1517 `user_message_uuid`
1518</h4>
1519
1520L'`uuid` del [`SDKUserMessage`](#sdkusermessage) a cui il turno sta rispondendo, ripetuto in modo da poter abbinare la risposta di Claude Code al messaggio che hai inviato. Claude Code ripete un `uuid` solo se ne hai impostato uno sul messaggio. Il campo è facoltativo su `SDKUserMessage`, e un prompt di stringa passato a `query()` non ne contiene nessuno.
1521
1522Quale dei tuoi messaggi un turno risponde dipende da come il turno è iniziato:
1523
1524* **Un messaggio regolare che hai inviato**, cioè uno senza `isSynthetic: true`: il turno risponde a quel messaggio per tutta la sua esecuzione. Quando invii diversi messaggi uno dopo l'altro, Claude Code può unirli in un turno, e il campo contiene solo l'`uuid` dell'ultimo messaggio. Per abbinare la risposta a uno qualsiasi dei messaggi uniti, usa [`user_message_uuids`](#user_message_uuids).
1525* **Un messaggio che hai inviato con `isSynthetic: true`**: il turno risponde a quel messaggio all'inizio. Se Claude Code raccoglie un messaggio regolare tuo tra le chiamate di tool, il turno risponde al messaggio raccolto da allora in poi. L'eco di un `uuid` di messaggio sintetico richiede Agent SDK v0.3.265 o successivo; le versioni precedenti non ecolano nulla sui turni sintetici.
1526* **Un prompt che Claude Code ha generato da solo**, come il turno che continua il lavoro interrotto dopo il riavvio di una sessione: il turno non risponde a nessun messaggio tuo all'inizio e i suoi frame non contengono alcun eco. Se Claude Code raccoglie un messaggio regolare tuo tra le chiamate di tool, il turno risponde a quel messaggio da allora in poi. L'eco di raccolta richiede Agent SDK v0.3.265 o successivo; le versioni precedenti non ecolano nulla su questi turni.
1527
1528Claude Code ripete l'`uuid` del messaggio a cui ha risposto su tre tipi di frame:
1529
1530* **Il risultato**: ogni risultato di un turno che ha risposto a un messaggio che hai inviato. Ogni tale risultato lo contiene su Agent SDK v0.3.265 o successivo. Prima della v0.3.265, il risultato di successo di un turno che un messaggio regolare ha avviato non lo conteneva quando il turno non ha inviato alcuna richiesta API o è terminato con una chiamata di tool differita. Prima della v0.3.246, anche i risultati di errore non lo contenevano, e prima della v0.3.216 ogni risultato non lo conteneva.
1531* **La prima risposta del turno**: il primo [messaggio dell'assistente](#sdkassistantmessage), o con `includePartialMessages` il primo [evento di flusso](#sdkpartialassistantmessage) il cui `event.type` non è `ping`, in modo da poter associare la risposta prima che il risultato arrivi. Quando un turno non trasmette nulla, Claude Code lo imposta sul primo messaggio dell'assistente. L'eco della prima risposta richiede Agent SDK v0.3.246 o successivo. Quando il messaggio a cui il turno sta rispondendo cambia a metà turno, la prima risposta dopo il cambio contiene il campo anche, su Agent SDK v0.3.265 o successivo; le versioni precedenti lo impostano su un frame di risposta per turno.
1532* **Ogni frame [`thinking_tokens`](#sdkthinkingtokensmessage) del turno**: in modo da poter attribuire il progresso del pensiero al messaggio che hai inviato senza aspettare la prima risposta del turno. Richiede Agent SDK v0.3.260 o successivo.
1533
1534Claude Code omette il campo in questi casi:
1535
1536* Frame di risposta diversi da quelle prime risposte
1537* Frame di subagente
1538* Turni che non rispondono a nessun messaggio con un `uuid`: il turno ha risposto a un messaggio che hai inviato senza uno, o Claude Code ha avviato il turno stesso e non ha raccolto nessun messaggio regolare che ne ha uno
1539* Risultati che non rispondono a nessun messaggio che hai inviato, come il risultato azzerato dopo un arresto anomalo del processo worker
1540
1541<h4 id="user_message_uuids">
1542 `user_message_uuids`
1543</h4>
1544
1545Gli `uuid` di ogni messaggio che hai inviato a cui Claude Code ha risposto in questo turno. Quando invii diversi messaggi uno dopo l'altro, Claude Code può unirli in un turno, e `user_message_uuid` nomina solo l'ultimo di essi. Per abbinare la risposta a uno qualsiasi dei messaggi uniti, cerca l'`uuid` di quel messaggio ovunque in questo elenco. Richiede Agent SDK v0.3.259 o successivo.
1546
1547Claude Code imposta l'elenco insieme a `user_message_uuid` su ogni frame di risposta che contiene quel campo e sul risultato. Per l'insieme completo di frame che contengono `user_message_uuid`, e la versione che ciascuno richiede, vedi [`user_message_uuid`](#user_message_uuid). L'elenco contiene sempre `user_message_uuid` e contiene al massimo 64 voci.
1548
1549Quando Claude Code raccoglie un messaggio regolare che hai inviato mentre un turno era in esecuzione, aggiunge l'`uuid` di quel messaggio all'elenco del risultato.
1550
1551Quando una prima risposta o un risultato contiene `user_message_uuid` senza l'elenco, proviene da una versione precedente di Claude Code, quindi ricadi al campo singolo.
1552
1553<h4 id="queued_turn_count">
1554 `queued_turn_count`
1555</h4>
1556
1557Il numero di messaggi che hai inviato con [`origin: { kind: "human" }`](#sdkmessageorigin) che sono ancora in attesa nella coda di comando quando Claude Code ha prodotto il risultato. Richiede Agent SDK v0.3.242 o successivo.
1558
1559Cosa significano `0` e un campo assente:
1560
1561* **`0`**: Claude Code non conta i messaggi che hai inviato senza quel `origin`, e non conta le notifiche di attività, quindi un turno può comunque seguire.
1562* **Assente**: il risultato finale che Claude Code emette dopo un arresto anomalo o un errore di avvio fatale omette il campo, e [può contenere totali azzerati](/docs/it/agent-sdk/cost-tracking#recover-totals-after-a-session-crash).
1563
1284<h3 id="sdksystemmessage">1564<h3 id="sdksystemmessage">
1285 `SDKSystemMessage`1565 `SDKSystemMessage`
1286</h3>1566</h3>
1306 model: string;1586 model: string;
1307 permissionMode: PermissionMode;1587 permissionMode: PermissionMode;
1308 slash_commands: string[];1588 slash_commands: string[];
1589 terminal_slash_commands?: string[];
1309 output_style: string;1590 output_style: string;
1310 skills: string[];1591 skills: string[];
1311 plugins: { name: string; path: string }[];1592 plugins: { name: string; path: string }[];
1593 fast_mode_state?: FastModeState;
1594 fast_mode_disabled_reason?: FastModeDisabledReason;
1595 effort?: "low" | "medium" | "high" | "xhigh" | "max" | null;
1312 capabilities?: string[];1596 capabilities?: string[];
1313};1597};
1314```1598```
1315 1599
1316L'array `capabilities` nomina i comportamenti del protocollo che questa CLI implementa, in modo da poter rilevare le funzionalità invece di confrontare le stringhe `claude_code_version`. È un insieme aperto: ignora i valori che non riconosci e controlla la capacità specifica su cui fai affidamento. Il campo richiede Claude Code v2.1.205 o successivo ed è assente su CLI precedenti.1600`fast_mode_state` segnala lo stato [fast mode](/docs/it/fast-mode) della sessione. Quando qualcosa blocca fast mode, `fast_mode_disabled_reason` nomina il controllo che lo ha bloccato; il campo richiede Claude Code v2.1.219 o successivo. Per i codici di motivo e i loro significati, vedi [`fast_mode_disabled_reason`](#sdkresultmessage) sul messaggio di risultato.
1601
1602`terminal_slash_commands` nomina le voci in `slash_commands` la cui interfaccia è associata al terminale locale, come `exit`. Puoi inviarle come qualsiasi altra voce in `slash_commands`; il campo esiste in modo che un client remoto o mobile possa nasconderle dai suoi menu di comando. Il campo è presente solo quando non vuoto, e richiede Agent SDK v0.3.229 o successivo.
1603
1604* `effort`: il [livello di sforzo](/docs/it/model-config#adjust-effort-level) che Claude Code invia sulla prossima richiesta della sessione, o `null` quando non ne invia nessuno. Claude Code imposta il campo solo sul messaggio di init che invia ai client [Remote Control](/docs/it/remote-control), e lo omette dal messaggio di init che la tua applicazione legge. Richiede Agent SDK v0.3.234 o successivo.
1605
1606L'array `capabilities` nomina i comportamenti del protocollo che questa CLI implementa, in modo da poter rilevare le funzionalità invece di confrontare le stringhe `claude_code_version`. È un insieme aperto: ignora i valori che non riconosci, e controlla la capacità specifica su cui fai affidamento. Il campo richiede Claude Code v2.1.205 o successivo ed è assente su CLI precedenti.
1317 1607
1318| Capacità | Significato |1608| Capacità | Significato |
1319| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1609| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1320| `interrupt_receipt_v1` | [`interrupt()`](#query-object) si risolve con una ricevuta [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) che nomina i messaggi in coda che sopravvivono all'interruzione |1610| `interrupt_receipt_v1` | [`interrupt()`](#query-object) si risolve con una ricevuta [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) che nomina i messaggi che erano in sospeso quando l'interruzione è arrivata |
1611| `interrupt_cancel_queued_v1` | La richiesta di controllo `interrupt` onora `cancel_queued: true`, annullando i messaggi che la ricevuta altrimenti elencherebbe sotto `still_queued` e elencandoli sotto `cancelled` invece. Vedi [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse). Richiede Claude Code v2.1.219 o successivo |
1321 1612
1322<h3 id="sdkpartialassistantmessage">1613<h3 id="sdkpartialassistantmessage">
1323 `SDKPartialAssistantMessage`1614 `SDKPartialAssistantMessage`
1333 uuid: UUID;1624 uuid: UUID;
1334 session_id: string;1625 session_id: string;
1335 ttft_ms?: number; // Tempo al primo token in ms, presente solo negli eventi message_start1626 ttft_ms?: number; // Tempo al primo token in ms, presente solo negli eventi message_start
1627 user_message_uuid?: string;
1628 user_message_uuids?: string[];
1336};1629};
1337```1630```
1338 1631
1632Claude Code imposta `user_message_uuid` e `user_message_uuids` sul primo evento di flusso non-ping del turno, e di nuovo quando il messaggio a cui il turno sta rispondendo cambia, secondo le condizioni in [`user_message_uuid`](#user_message_uuid).
1633
1339<h3 id="sdkcompactboundarymessage">1634<h3 id="sdkcompactboundarymessage">
1340 `SDKCompactBoundaryMessage`1635 `SDKCompactBoundaryMessage`
1341</h3>1636</h3>
1359 `SDKInformationalMessage`1654 `SDKInformationalMessage`
1360</h3>1655</h3>
1361 1656
1362Banner di testo generico emesso dal ciclo. Contiene righe di stato non di errore, feedback di hook come il motivo del blocco di un hook `UserPromptSubmit`, e output di comando. Renderizza `content` come testo semplice al livello specificato.1657Banner di testo generico emesso dal ciclo. Contiene righe di stato non di errore, feedback di hook come il motivo del blocco di un hook `UserPromptSubmit`, e output di comando. Su Claude Code v2.1.227 o successivo, il [`systemMessage`](/docs/it/hooks#json-output) di un hook può arrivare come questo messaggio, con ogni riga prefissata dal nome dell'hook, come `PostToolUse:Bash says:`. Se il `systemMessage` di un hook arriva come questo messaggio dipende dall'evento. Ogni [sezione dell'evento](/docs/it/hooks#hook-events) sulla pagina dei hook dice come l'output viene visualizzato. Renderizza `content` come testo semplice al livello specificato.
1363 1658
1364```typescript theme={null}1659```typescript theme={null}
1365type SDKInformationalMessage = {1660type SDKInformationalMessage = {
1412 `SDKPermissionDeniedMessage`1707 `SDKPermissionDeniedMessage`
1413</h3>1708</h3>
1414 1709
1415Evento di flusso emesso quando il sistema di autorizzazione nega automaticamente una chiamata di tool senza un prompt interattivo. Usalo per rendere il rifiuto nella tua interfaccia utente mentre accade, piuttosto che osservare solo il risultato del tool `is_error` che segue. Il percorso della richiesta interattiva raggiunge la tua applicazione separatamente tramite il callback [`canUseTool`](#canusetool). I rifiuti emessi da un hook `PreToolUse` non vengono segnalati tramite questo evento.1710Evento di flusso emesso quando il sistema di autorizzazione nega una chiamata di tool senza un prompt interattivo. Usalo per rendere il rifiuto nella tua interfaccia utente mentre accade, piuttosto che osservare solo il risultato del tool `is_error` che segue. Quali rifiuti segnala dipende da come l'esecuzione gestisce i prompt di autorizzazione:
1416 1711
1417Questo evento richiede Claude Code v2.1.136 o successivo.1712* **Con un callback [`canUseTool`](#canusetool) e il [`permissionPrompts: 'host'`](#options) predefinito**: i prompt di autorizzazione vanno al tuo callback, e questo evento segnala i rifiuti che Claude Code decide da solo senza chiamarlo.
1713* **Con nessuno dei due**: un'esecuzione `-p` nuda, o `query()` che non imposta né `canUseTool` né `permissionPromptToolName`, nega qualsiasi chiamata di tool che avrebbe richiesto un prompt, e questo evento segnala anche quei rifiuti oltre a quelli che Claude Code decide da solo. Prima della v2.1.223, Claude Code non emetteva questo evento nelle esecuzioni senza un callback.
1714* **Con uno strumento di prompt MCP**, impostato con `permissionPromptToolName` o il flag [`--permission-prompt-tool`](/docs/it/cli-reference#cli-flags), e il `permissionPrompts: 'host'` predefinito: Claude Code non emette questo evento affatto, nemmeno per i rifiuti di regola che decide da solo.
1715* **Con [`permissionPrompts: 'none'`](#options)**: Claude Code nega le chiamate che avrebbero richiesto un prompt, anche quando `canUseTool` o uno strumento di prompt MCP è anche impostato, e questo evento segnala anche quei rifiuti oltre a quelli che Claude Code decide da solo. Richiede Claude Code v2.1.259 o successivo.
1716
1717In ogni configurazione, questo evento salta qualsiasi rifiuto deciso sul percorso dell'hook `PreToolUse`, indipendentemente dal fatto che l'hook abbia negato la chiamata stessa o una regola di negazione abbia sovrascritto la decisione di consentire o chiedere dell'hook. L'evento è anche best-effort: occasionalmente Claude Code registra un rifiuto senza emettere questo evento, quindi `permission_denials` sul [messaggio di risultato](#sdkresultmessage) è il record autorevole.
1418 1718
1419```typescript theme={null}1719```typescript theme={null}
1420type SDKPermissionDeniedMessage = {1720type SDKPermissionDeniedMessage = {
1454};1754};
1455```1755```
1456 1756
1757<h3 id="sdkcontextusage">
1758 `SDKContextUsage`
1759</h3>
1760
1761Forma strutturata del rapporto `/context`, portata come `context_usage` sul [`SDKAssistantMessage`](#sdkassistantmessage) che consegna un risultato `/context`. Agent SDK v0.3.232 e successivo esportano il tipo. A differenza di [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse), contiene solo i dati necessari per rendere la suddivisione dell'utilizzo, senza campi di visualizzazione come `color` e `gridRows`.
1762
1763```typescript theme={null}
1764type SDKContextUsage = {
1765 model: string;
1766 total_tokens: number;
1767 raw_max_tokens: number;
1768 percentage: number;
1769 over_limit?: {
1770 tokens_over: number;
1771 kind: "hard_limit" | "compaction_window";
1772 };
1773 categories: SDKContextUsageCategory[];
1774 mcp_tools: {
1775 name: string;
1776 server_name: string;
1777 tokens: number;
1778 }[];
1779 memory_files: {
1780 path: string;
1781 type: string;
1782 tokens: number;
1783 }[];
1784 agents: {
1785 agent_type: string;
1786 source: string;
1787 tokens: number;
1788 }[];
1789 skills?: {
1790 name: string;
1791 source: string;
1792 plugin_name?: string;
1793 tokens: number;
1794 }[];
1795};
1796```
1797
1798La tabella elenca cosa Claude Code mette in ogni campo. I campi da `model` a `over_limit` descrivono la sessione nel suo insieme, e i campi di raccolta attribuiscono i token a elementi individuali.
1799
1800| Campo | Tipo | Descrizione |
1801| ---------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1802| `model` | `string` | Il modello del ciclo principale per il quale Claude Code ha calcolato l'utilizzo, non quello di un subagente |
1803| `total_tokens` | `number` | La stima di Claude Code dei token in uso. Non limitato alla finestra, quindi può superare `raw_max_tokens` quando la sessione è oltre il limite |
1804| `raw_max_tokens` | `number` | La finestra di contesto del modello, o la [finestra di auto-compattazione](/docs/it/model-config#context-window-and-auto-compaction) inferiore quando una si applica, come una che hai impostato o il limite di 200K che Claude Code applica ad alcuni modelli con una finestra di 1M token. Claude Code misura `total_tokens` rispetto a questa finestra |
1805| `percentage` | `number` | `total_tokens` come percentuale arrotondata di `raw_max_tokens`, quindi può superare 100 quando la sessione è oltre il limite |
1806| `over_limit` | `object` | Presente solo quando `total_tokens` supera `raw_max_tokens`. `tokens_over` è l'importo in eccesso, e `kind` dice come Claude Code ha risolto la finestra |
1807| `categories` | [`SDKContextUsageCategory`](#sdkcontextusagecategory)`[]` | Una voce per riga della suddivisione dell'utilizzo per categoria |
1808| `mcp_tools` | `object[]` | Token attribuiti a ogni tool MCP, con il suo nome di trasmissione, come `mcp__linear__create_issue`, e il suo `server_name` |
1809| `memory_files` | `object[]` | Token attribuiti a ogni file di memoria caricato, con il suo `path` e un'etichetta di origine come `Project` o `User` in `type` |
1810| `agents` | `object[]` | Token attribuiti a ogni definizione di subagente personalizzato, con un identificatore di origine come `projectSettings`, `userSettings`, o `plugin`. I subagenti integrati non sono elencati |
1811| `skills` | `object[]` | Token attribuiti a ogni skill nell'elenco di skill, con un identificatore di origine e, per le skill di plugin, il nome del plugin in `plugin_name`. Assente quando nessuna skill contribuisce token |
1812
1813`over_limit.kind` registra come Claude Code ha risolto la finestra, non se l'API accetta la prossima richiesta:
1814
1815* `hard_limit`: la finestra è quella che Claude Code crede sia il limite proprio del modello, oltre il quale l'API rifiuta le richieste
1816* `compaction_window`: la finestra è una finestra di politica di compattazione, che può o non può coincidere con il limite del modello
1817
1818Claude Code evolve il tipo in modo additivo, aggiungendo nuovi dati come campi facoltativi piuttosto che rimodellando quelli esistenti. Leggi i campi che conosci e ignora quelli che non riconosci.
1819
1820<h3 id="sdkcontextusagecategory">
1821 `SDKContextUsageCategory`
1822</h3>
1823
1824Una riga della suddivisione dell'utilizzo `/context` per categoria.
1825
1826```typescript theme={null}
1827type SDKContextUsageCategory = {
1828 name: string;
1829 tokens: number;
1830 kind: "used" | "free" | "buffer" | "deferred";
1831};
1832```
1833
1834La tabella elenca cosa Claude Code mette in ogni campo di una riga.
1835
1836| Campo | Tipo | Descrizione |
1837| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
1838| `name` | `string` | Il nome di visualizzazione della riga come `/context` lo stampa, come `Messages`. Classifica le righe per `kind`, non per nome |
1839| `tokens` | `number` | Il conteggio dei token della riga. Le righe possono contenere zero token |
1840| `kind` | `string` | Cosa rappresenta la riga: `used`, `free`, `buffer`, o `deferred` |
1841
1842Ogni valore `kind` dice cosa sono i token della riga:
1843
1844* `used`: contenuto che occupa la finestra di contesto
1845* `free`: la finestra rimanente
1846* `buffer`: la riserva di compattazione
1847* `deferred`: schemi di tool che Claude Code tiene fuori dalla finestra ed esclude dal calcolo dell'utilizzo, elencati per consapevolezza
1848
1457<h3 id="sdkmessageorigin">1849<h3 id="sdkmessageorigin">
1458 `SDKMessageOrigin`1850 `SDKMessageOrigin`
1459</h3>1851</h3>
1467 | {1859 | {
1468 kind: "peer";1860 kind: "peer";
1469 from: string;1861 from: string;
1862 fromMode?: "bypass" | "prompting";
1470 name?: string;1863 name?: string;
1864 fromSession?: string;
1471 senderTaskId?: string;1865 senderTaskId?: string;
1472 body?: string;1866 body?: string;
1867 verifiedPeerPid?: number;
1868 }
1869 | {
1870 kind: "task-notification";
1871 subkind?: "scheduled-trigger" | "peer-send-message";
1473 }1872 }
1474 | { kind: "task-notification" }
1475 | { kind: "coordinator" }1873 | { kind: "coordinator" }
1476 | { kind: "auto-continuation" };1874 | { kind: "auto-continuation" }
1875 | { kind: "unclassified" };
1477```1876```
1478 1877
1479| `kind` | Significato |1878| `kind` | Significato |
1480| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1879| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1481| `human` | Input diretto dall'utente finale. Sui messaggi utente, un `origin` assente significa anche input umano. |1880| `human` | Input diretto dall'utente finale. Se la tua applicazione inoltro quello che l'utente ha digitato come messaggio utente, imposta il suo `origin` a `{ kind: "human" }` esplicitamente: Claude Code tratta un messaggio utente senza `origin` come non attribuito, e controlla che richiedono un prompt digitato dall'utente, come la [parola chiave del workflow `ultracode`](/docs/it/workflows#ask-for-a-workflow-in-your-prompt), non lo accettano. Prima della v2.1.210, Claude Code trattava un `origin` assente su un messaggio utente come input umano. |
1482| `channel` | Messaggio in arrivo su un [canale](/docs/it/channels). `server` è il nome del server MCP di origine. |1881| `channel` | Messaggio in arrivo su un [canale](/docs/it/channels). `server` è il nome del server MCP di origine. |
1483| `peer` | Messaggio da un altro agente. Per un [collega](/docs/it/agent-teams) in-process che invia a `main` tramite `SendMessage`, `from` è il nome del collega e `senderTaskId` è il suo ID attività. Per un peer tra sessioni come un altro processo Claude Code locale, `from` è l'indirizzo del mittente e `senderTaskId` è assente. }`name` e `body` richiedono Claude Code v2.1.205 o successivo. `name` è il nome visualizzato del mittente, normalizzato da Claude Code: rimuove i punti di codice di controllo, formato, surrogato e separatore di riga o paragrafo Unicode, quindi taglia il risultato e lo limita a 64 punti di codice con un'ellissi. `body` è il corpo del messaggio decodificato con l'involucro peer rimosso, byte-esatto con quello che il modello vede. Per un messaggio di collega `body` è sempre presente; per un peer tra sessioni è presente solo quando il turno è esattamente un involucro peer formato da Claude Code. Renderizza `name` e `body` invece di ri-analizzare il testo del messaggio. |1882| `peer` | Messaggio da un altro agente: un [collega](/docs/it/agent-teams) in-process o un [peer tra sessioni](/docs/it/cross-session-messaging), un'altra delle tue sessioni Claude Code. Vedi [Campi di origine peer](#peer-origin-fields) per la semantica per campo e il modello di fiducia. |
1484| `task-notification` | Turno sintetico iniettato dopo il completamento di un'attività in background. Vedi [`SDKTaskNotificationMessage`](#sdktasknotificationmessage). |1883| `task-notification` | Turno sintetico iniettato per una consegna che arriva senza un prompt utente fresco, come un'attività finita in background; vedi [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) per quel ramo. Il `subkind` facoltativo marca cosa ha sollevato la notifica. Vedi [Subkind di notifica attività](#task-notification-subkinds). |
1485| `coordinator` | Messaggio da un coordinatore di team in un [team di agenti](/docs/it/agent-teams). |1884| `coordinator` | Messaggio da un coordinatore di team in un [team di agenti](/docs/it/agent-teams). |
1486| `auto-continuation` | Turno sintetico iniettato quando la sessione continua senza input utente fresco, come un risultato di comando che attiva un prompt di follow-up. |1885| `auto-continuation` | Turno sintetico iniettato quando la sessione continua senza input utente fresco, come un risultato di comando che attiva un prompt di follow-up. |
1886| `unclassified` | Turno iniettato il cui origin non ha potuto essere determinato. Richiede Claude Code v2.1.223 o successivo. Quando Claude Code riceve un [`SDKUserMessage`](#sdkusermessage) con `isSynthetic: true` e non può classificarlo come nessun altro `kind`, imposta questo kind mentre il messaggio arriva e inquadra il turno al modello come una fonte non utente piuttosto che trattarlo come input umano. La tua applicazione non dovrebbe impostare questo valore. |
1887
1888<h3 id="task-notification-subkinds">
1889 Task-notification subkinds
1890</h3>
1891
1892Quando Claude Code consegna una notifica di attività in una sessione, imposta `subkind` sull'`origin` della notifica solo se i server Anthropic hanno verificato da dove proveniva quella notifica. `subkind` richiede Claude Code v2.1.213 o successivo, e assume uno di due valori:
1893
1894* `scheduled-trigger`: la notifica è il prompt memorizzato di una [routine](/docs/it/routines), consegnato perché uno dei trigger della routine si è attivato: il suo programma, il suo [trigger API](/docs/it/routines#add-an-api-trigger), il suo [trigger GitHub](/docs/it/routines#add-a-github-trigger), o **Esegui ora**. Claude Code inquadra questi al modello come l'attività assegnata della sessione, con un avviso diverso dall'[avviso che altre notifiche di attività contengono](#sdktasknotificationmessage).
1895* `peer-send-message`: la notifica è un messaggio che un'altra delle tue sessioni ha inviato con lo strumento `send_message` lato server che le sessioni [Claude Code sul web](/docs/it/claude-code-on-the-web) usano per messaggiarsi l'una con l'altra, non lo [strumento `SendMessage` tra sessioni](/docs/it/cross-session-messaging), e i server Anthropic hanno verificato che entrambe le sessioni appartengono allo stesso gruppo privato di sessioni. Richiede Claude Code v2.1.224 o successivo. Una consegna `send_message` che i server non hanno verificato in quel modo non ha `subkind`.
1896
1897Ogni altra notifica di attività non ha `subkind`. Questo include [attività programmate](/docs/it/scheduled-tasks) che si attivano sulla tua stessa macchina, [attività PR](/docs/it/claude-code-on-the-web#how-claude-responds-to-pr-activity) consegnate in una sessione, e eventi in background come un'attività finita. I messaggi dallo strumento [`SendMessage`](/docs/it/cross-session-messaging) tra sessioni non sono notifiche di attività affatto: che provengano da una sessione sulla stessa macchina o attraverso i server Anthropic da un'altra macchina, Claude Code dà loro `kind: "peer"` e i [campi di origine peer](#peer-origin-fields).
1898
1899<h3 id="peer-origin-fields">
1900 Peer origin fields
1901</h3>
1902
1903Un'origine `peer` identifica quale agente ha inviato il messaggio: un [collega](/docs/it/agent-teams) in-process che invia a `main` con `SendMessage`, o un [peer tra sessioni](/docs/it/cross-session-messaging), un'altra delle tue sessioni Claude Code. I peer tra sessioni richiedono Claude Code v2.1.224 o successivo su macOS e Linux; vedi [disponibilità di messaggistica tra sessioni](/docs/it/cross-session-messaging#availability) per il requisito di Windows nativo. Un peer tra sessioni può essere eseguito sulla stessa macchina, o su [un'altra delle tue macchine](/docs/it/cross-session-messaging#message-sessions-on-other-machines) o [Claude Code sul web](/docs/it/claude-code-on-the-web) quando il suo messaggio arriva attraverso Remote Control. I due tipi di mittente riempiono i campi diversamente:
1904
1905* `from`: il nome del collega, o l'indirizzo del mittente per un peer tra sessioni. Per un [messaggio tra macchine unidirezionale](/docs/it/cross-session-messaging#message-sessions-on-other-machines), il mittente non ha indirizzo di risposta e `from` è `"unknown"`. Il valore è creato dal mittente; `verifiedPeerPid` è l'identità verificata.
1906* `fromMode`: la classe di autorizzazione della sessione di invio, `bypass` o `prompting`, dichiarata da un host che inoltro un messaggio peer tra le tue sessioni, come l'[app desktop](/docs/it/desktop#work-across-sessions). Claude Code lo legge nella sessione ricevente quando applica i [controlli in entrata](/docs/it/cross-session-messaging#control-inbound-messages). Richiede Agent SDK v0.3.234 o successivo.
1907* `senderTaskId`: l'ID attività del collega. Assente per un peer tra sessioni.
1908* `name`: il nome di visualizzazione del mittente, normalizzato da Claude Code: rimuove i punti di codice di controllo, formato, surrogato e separatore di riga o paragrafo Unicode, quindi taglia il risultato e lo limita a 64 punti di codice con un'ellissi. Richiede Claude Code v2.1.205 o successivo.
1909* `body`: il corpo del messaggio decodificato con l'involucro peer rimosso, byte-esatto con quello che il modello vede. Sempre presente per un messaggio di collega; per un peer tra sessioni, presente solo quando il turno è esattamente un involucro peer formato da Claude Code. Renderizza `name` e `body` invece di ri-analizzare il testo del messaggio. Richiede Claude Code v2.1.205 o successivo.
1910* `fromSession`: l'ID sessione del mittente apribile dall'host, impostato dall'host del mittente in modo che la tua interfaccia utente possa collegarsi di nuovo alla sessione di invio. Come `from`, è asserito dal mittente: usalo solo come destinazione di navigazione, e non trattarlo come prova dell'identità del mittente. Richiede Claude Code v2.1.216 o successivo.
1911* `verifiedPeerPid`: l'ID del processo del processo che si è connesso al socket di messaggistica tra sessioni di questa sessione, verificato dal kernel e letto dalla connessione stessa, mai dal payload. Usalo, non `from`, per identificare il mittente: `from` è falsificabile da qualsiasi processo dello stesso utente. Il campo è assente quando Claude Code non può verificarlo, come su Windows o ingresso non-socket, quindi un valore assente significa che il mittente non è verificato. Per il traffico inoltrato identifica l'inoltro piuttosto che l'autore del messaggio, e gli ID di processo sono riciclabili, quindi trattalo come provenienza piuttosto che come token di autenticazione. Richiede Claude Code v2.1.216 o successivo.
1487 1912
1488<h2 id="hook-types">1913<h2 id="hook-types">
1489 Tipi di hook1914 Tipi di hook
1505 | "PostToolBatch"1930 | "PostToolBatch"
1506 | "Notification"1931 | "Notification"
1507 | "UserPromptSubmit"1932 | "UserPromptSubmit"
1933 | "UserPromptExpansion"
1508 | "SessionStart"1934 | "SessionStart"
1509 | "SessionEnd"1935 | "SessionEnd"
1510 | "Stop"1936 | "Stop"
1937 | "StopFailure"
1511 | "SubagentStart"1938 | "SubagentStart"
1512 | "SubagentStop"1939 | "SubagentStop"
1513 | "PreCompact"1940 | "PreCompact"
1941 | "PostCompact"
1942 | "PreModelSwitch"
1943 | "PostModelSwitch"
1514 | "PermissionRequest"1944 | "PermissionRequest"
1945 | "PermissionDenied"
1515 | "Setup"1946 | "Setup"
1516 | "TeammateIdle"1947 | "TeammateIdle"
1948 | "TaskCreated"
1517 | "TaskCompleted"1949 | "TaskCompleted"
1950 | "Elicitation"
1951 | "ElicitationResult"
1518 | "ConfigChange"1952 | "ConfigChange"
1953 | "DirectoryAdded"
1519 | "WorktreeCreate"1954 | "WorktreeCreate"
1520 | "WorktreeRemove"1955 | "WorktreeRemove"
1956 | "InstructionsLoaded"
1957 | "CwdChanged"
1958 | "FileChanged"
1521 | "MessageDisplay";1959 | "MessageDisplay";
1522```1960```
1523 1961
1561 | PostToolUseHookInput1999 | PostToolUseHookInput
1562 | PostToolUseFailureHookInput2000 | PostToolUseFailureHookInput
1563 | PostToolBatchHookInput2001 | PostToolBatchHookInput
2002 | PermissionDeniedHookInput
1564 | NotificationHookInput2003 | NotificationHookInput
1565 | UserPromptSubmitHookInput2004 | UserPromptSubmitHookInput
2005 | UserPromptExpansionHookInput
1566 | SessionStartHookInput2006 | SessionStartHookInput
1567 | SessionEndHookInput2007 | SessionEndHookInput
1568 | StopHookInput2008 | StopHookInput
2009 | StopFailureHookInput
1569 | SubagentStartHookInput2010 | SubagentStartHookInput
1570 | SubagentStopHookInput2011 | SubagentStopHookInput
1571 | PreCompactHookInput2012 | PreCompactHookInput
2013 | PostCompactHookInput
2014 | PreModelSwitchHookInput
2015 | PostModelSwitchHookInput
1572 | PermissionRequestHookInput2016 | PermissionRequestHookInput
1573 | SetupHookInput2017 | SetupHookInput
1574 | TeammateIdleHookInput2018 | TeammateIdleHookInput
2019 | TaskCreatedHookInput
1575 | TaskCompletedHookInput2020 | TaskCompletedHookInput
2021 | ElicitationHookInput
2022 | ElicitationResultHookInput
1576 | ConfigChangeHookInput2023 | ConfigChangeHookInput
2024 | InstructionsLoadedHookInput
2025 | DirectoryAddedHookInput
1577 | WorktreeCreateHookInput2026 | WorktreeCreateHookInput
1578 | WorktreeRemoveHookInput2027 | WorktreeRemoveHookInput
2028 | CwdChangedHookInput
2029 | FileChangedHookInput
1579 | MessageDisplayHookInput;2030 | MessageDisplayHookInput;
1580```2031```
1581 2032
1664};2115};
1665```2116```
1666 2117
2118<h4 id="permissiondeniedhookinput">
2119 `PermissionDeniedHookInput`
2120</h4>
2121
2122```typescript theme={null}
2123type PermissionDeniedHookInput = BaseHookInput & {
2124 hook_event_name: "PermissionDenied";
2125 tool_name: string;
2126 tool_input: unknown;
2127 tool_use_id: string;
2128 reason: string;
2129};
2130```
2131
1667<h4 id="notificationhookinput">2132<h4 id="notificationhookinput">
1668 `NotificationHookInput`2133 `NotificationHookInput`
1669</h4>2134</h4>
1685type UserPromptSubmitHookInput = BaseHookInput & {2150type UserPromptSubmitHookInput = BaseHookInput & {
1686 hook_event_name: "UserPromptSubmit";2151 hook_event_name: "UserPromptSubmit";
1687 prompt: string;2152 prompt: string;
2153 session_title?: string;
2154};
2155```
2156
2157<h4 id="userpromptexpansionhookinput">
2158 `UserPromptExpansionHookInput`
2159</h4>
2160
2161```typescript theme={null}
2162type UserPromptExpansionHookInput = BaseHookInput & {
2163 hook_event_name: "UserPromptExpansion";
2164 expansion_type: "slash_command" | "mcp_prompt";
2165 command_name: string;
2166 command_args: string;
2167 command_source?: string;
2168 prompt: string;
1688};2169};
1689```2170```
1690 2171
1695```typescript theme={null}2176```typescript theme={null}
1696type SessionStartHookInput = BaseHookInput & {2177type SessionStartHookInput = BaseHookInput & {
1697 hook_event_name: "SessionStart";2178 hook_event_name: "SessionStart";
1698 source: "startup" | "resume" | "clear" | "compact";2179 source: "startup" | "resume" | "clear" | "compact" | "fork";
1699 agent_type?: string;2180 agent_type?: string;
1700 model?: string;2181 model?: string;
2182 session_title?: string;
1701};2183};
1702```2184```
1703 2185
1726};2208};
1727```2209```
1728 2210
2211<h4 id="stopfailurehookinput">
2212 `StopFailureHookInput`
2213</h4>
2214
2215```typescript theme={null}
2216type StopFailureHookInput = BaseHookInput & {
2217 hook_event_name: "StopFailure";
2218 error: SDKAssistantMessageError;
2219 error_details?: string;
2220 last_assistant_message?: string;
2221};
2222```
2223
1729<h4 id="subagentstarthookinput">2224<h4 id="subagentstarthookinput">
1730 `SubagentStartHookInput`2225 `SubagentStartHookInput`
1731</h4>2226</h4>
1786};2281};
1787```2282```
1788 2283
2284<h4 id="postcompacthookinput">
2285 `PostCompactHookInput`
2286</h4>
2287
2288```typescript theme={null}
2289type PostCompactHookInput = BaseHookInput & {
2290 hook_event_name: "PostCompact";
2291 trigger: "manual" | "auto";
2292 compact_summary: string;
2293};
2294```
2295
2296<h4 id="premodelswitchhookinput">
2297 `PreModelSwitchHookInput`
2298</h4>
2299
2300Si attiva prima che un cambio di modello richiesto abbia effetto. `context_tokens` e i campi dopo di esso stimano il costo di reinviare la conversazione al nuovo modello. Per le descrizioni complete dei campi e la semantica di blocco, vedi [PreModelSwitch](/docs/it/hooks#premodelswitch).
2301
2302```typescript theme={null}
2303type PreModelSwitchHookInput = BaseHookInput & {
2304 hook_event_name: "PreModelSwitch";
2305 from_model: string;
2306 to_model: string;
2307 requested_model: string | null;
2308 source: "command" | "picker" | "sdk";
2309 context_tokens: number;
2310 prompt_cache_warm: boolean;
2311 cache_ttl: "5m" | "1h";
2312 estimated_cache_write_usd: number;
2313 pricing: "configured" | "catalog" | "default";
2314};
2315```
2316
2317<h4 id="postmodelswitchhookinput">
2318 `PostModelSwitchHookInput`
2319</h4>
2320
2321Si attiva dopo che il modello della sessione cambia. Contiene gli stessi campi di `PreModelSwitchHookInput`, con due valori `source` aggiuntivi. Vedi [PostModelSwitch](/docs/it/hooks#postmodelswitch).
2322
2323```typescript theme={null}
2324type PostModelSwitchHookInput = BaseHookInput & {
2325 hook_event_name: "PostModelSwitch";
2326 from_model: string;
2327 to_model: string;
2328 requested_model: string | null;
2329 source: "command" | "picker" | "sdk" | "auto" | "resume";
2330 context_tokens: number;
2331 prompt_cache_warm: boolean;
2332 cache_ttl: "5m" | "1h";
2333 estimated_cache_write_usd: number;
2334 pricing: "configured" | "catalog" | "default";
2335};
2336```
2337
1789<h4 id="permissionrequesthookinput">2338<h4 id="permissionrequesthookinput">
1790 `PermissionRequestHookInput`2339 `PermissionRequestHookInput`
1791</h4>2340</h4>
1823};2372};
1824```2373```
1825 2374
1826<h4 id="taskcompletedhookinput">2375<h4 id="taskcreatedhookinput">
1827 `TaskCompletedHookInput`2376 `TaskCreatedHookInput`
1828</h4>2377</h4>
1829 2378
1830```typescript theme={null}2379```typescript theme={null}
1831type TaskCompletedHookInput = BaseHookInput & {2380type TaskCreatedHookInput = BaseHookInput & {
1832 hook_event_name: "TaskCompleted";2381 hook_event_name: "TaskCreated";
1833 task_id: string;2382 task_id: string;
1834 task_subject: string;2383 task_subject: string;
1835 task_description?: string;2384 task_description?: string;
1839};2388};
1840```2389```
1841 2390
2391<h4 id="taskcompletedhookinput">
2392 `TaskCompletedHookInput`
2393</h4>
2394
2395```typescript theme={null}
2396type TaskCompletedHookInput = BaseHookInput & {
2397 hook_event_name: "TaskCompleted";
2398 task_id: string;
2399 task_subject: string;
2400 task_description?: string;
2401 teammate_name?: string;
2402 /** @deprecated da v2.1.178. Contiene il nome del team derivato dalla sessione; verrà rimosso. */
2403 team_name?: string;
2404};
2405```
2406
2407<h4 id="elicitationhookinput">
2408 `ElicitationHookInput`
2409</h4>
2410
2411```typescript theme={null}
2412type ElicitationHookInput = BaseHookInput & {
2413 hook_event_name: "Elicitation";
2414 mcp_server_name: string;
2415 message: string;
2416 mode?: "form" | "url";
2417 url?: string;
2418 elicitation_id?: string;
2419 requested_schema?: Record<string, unknown>;
2420};
2421```
2422
2423<h4 id="elicitationresulthookinput">
2424 `ElicitationResultHookInput`
2425</h4>
2426
2427```typescript theme={null}
2428type ElicitationResultHookInput = BaseHookInput & {
2429 hook_event_name: "ElicitationResult";
2430 mcp_server_name: string;
2431 elicitation_id?: string;
2432 mode?: "form" | "url";
2433 action: "accept" | "decline" | "cancel";
2434 content?: Record<string, unknown>;
2435};
2436```
2437
1842<h4 id="configchangehookinput">2438<h4 id="configchangehookinput">
1843 `ConfigChangeHookInput`2439 `ConfigChangeHookInput`
1844</h4>2440</h4>
1856};2452};
1857```2453```
1858 2454
2455<h4 id="instructionsloadedhookinput">
2456 `InstructionsLoadedHookInput`
2457</h4>
2458
2459```typescript theme={null}
2460type InstructionsLoadedHookInput = BaseHookInput & {
2461 hook_event_name: "InstructionsLoaded";
2462 file_path: string;
2463 memory_type: "User" | "Project" | "Local" | "Managed";
2464 load_reason:
2465 | "session_start"
2466 | "nested_traversal"
2467 | "path_glob_match"
2468 | "include"
2469 | "compact";
2470 globs?: string[];
2471 trigger_file_path?: string;
2472 parent_file_path?: string;
2473};
2474```
2475
2476<h4 id="directoryaddedhookinput">
2477 `DirectoryAddedHookInput`
2478</h4>
2479
2480```typescript theme={null}
2481type DirectoryAddedHookInput = BaseHookInput & {
2482 hook_event_name: "DirectoryAdded";
2483 directory: string;
2484 source: "slash_command" | "register_repo_root";
2485};
2486```
2487
2488`directory` è il percorso assoluto della directory che è stata aggiunta. `source` è `"slash_command"` quando `/add-dir` l'ha aggiunta e `"register_repo_root"` quando la richiesta di controllo SDK l'ha fatto.
2489
1859<h4 id="worktreecreatehookinput">2490<h4 id="worktreecreatehookinput">
1860 `WorktreeCreateHookInput`2491 `WorktreeCreateHookInput`
1861</h4>2492</h4>
1878};2509};
1879```2510```
1880 2511
2512<h4 id="cwdchangedhookinput">
2513 `CwdChangedHookInput`
2514</h4>
2515
2516```typescript theme={null}
2517type CwdChangedHookInput = BaseHookInput & {
2518 hook_event_name: "CwdChanged";
2519 old_cwd: string;
2520 new_cwd: string;
2521};
2522```
2523
2524<h4 id="filechangedhookinput">
2525 `FileChangedHookInput`
2526</h4>
2527
2528```typescript theme={null}
2529type FileChangedHookInput = BaseHookInput & {
2530 hook_event_name: "FileChanged";
2531 file_path: string;
2532 event: "change" | "add" | "unlink";
2533};
2534```
2535
1881<h4 id="messagedisplayhookinput">2536<h4 id="messagedisplayhookinput">
1882 `MessageDisplayHookInput`2537 `MessageDisplayHookInput`
1883</h4>2538</h4>
1925 stopReason?: string;2580 stopReason?: string;
1926 decision?: "approve" | "block";2581 decision?: "approve" | "block";
1927 systemMessage?: string;2582 systemMessage?: string;
2583 /**
2584 * Una sequenza di escape del terminale (ad es. OSC 9 / OSC 777 desktop-notification)
2585 * per Claude Code da emettere per tuo conto. Solo notification/title OSCs
2586 * (0, 1, 2, 9, 99, 777) e BEL sono consentiti; un valore contenente
2587 * qualcos'altro viene ignorato nel complesso. Solo la CLI interattiva lo emette;
2588 * l'SDK ignora il campo.
2589 */
2590 terminalSequence?: string;
1928 reason?: string;2591 reason?: string;
1929 hookSpecificOutput?:2592 hookSpecificOutput?:
1930 | {2593 | {
1937 | {2600 | {
1938 hookEventName: "UserPromptSubmit";2601 hookEventName: "UserPromptSubmit";
1939 additionalContext?: string;2602 additionalContext?: string;
2603 sessionTitle?: string;
2604 /** Quando decision è "block", ometti il prompt originale dal messaggio di blocco. */
2605 suppressOriginalPrompt?: boolean;
2606 }
2607 | {
2608 hookEventName: "UserPromptExpansion";
2609 additionalContext?: string;
1940 }2610 }
1941 | {2611 | {
1942 hookEventName: "SessionStart";2612 hookEventName: "SessionStart";
1943 additionalContext?: string;2613 additionalContext?: string;
2614 initialUserMessage?: string;
2615 sessionTitle?: string;
2616 watchPaths?: string[];
2617 /**
2618 * Riscannerizza le directory di skill e comandi dopo che gli hook SessionStart
2619 * sono completati, in modo che le skill installate dall'hook siano disponibili nella
2620 * stessa sessione.
2621 */
2622 reloadSkills?: boolean;
1944 }2623 }
1945 | {2624 | {
1946 hookEventName: "Setup";2625 hookEventName: "Setup";
1947 additionalContext?: string;2626 additionalContext?: string;
1948 }2627 }
2628 | {
2629 hookEventName: "PreModelSwitch";
2630 /**
2631 * Stesso contratto di PreToolUse: "allow" procede, "deny" annulla
2632 * il cambio, "ask" chiede all'utente di confermare. Solo /model in una
2633 * sessione interattiva mostra quel prompt; ogni altra superficie,
2634 * incluse le richieste set_model, tratta "ask" come un rifiuto.
2635 */
2636 permissionDecision?: "allow" | "deny" | "ask";
2637 permissionDecisionReason?: string;
2638 }
2639 | {
2640 hookEventName: "PostModelSwitch";
2641 /** Raggiunge il modello con la prossima richiesta che il nuovo modello serve. */
2642 additionalContext?: string;
2643 }
1949 | {2644 | {
1950 hookEventName: "SubagentStart";2645 hookEventName: "SubagentStart";
1951 additionalContext?: string;2646 additionalContext?: string;
1953 | {2648 | {
1954 hookEventName: "PostToolUse";2649 hookEventName: "PostToolUse";
1955 additionalContext?: string;2650 additionalContext?: string;
2651 /**
2652 * Breve nota sul risultato di questa chiamata di strumento per il classificatore
2653 * di autorizzazione in modalità auto. Limitato a 2000 caratteri, condiviso tra
2654 * tutti gli hook che rispondono alla stessa chiamata; rispettato solo su
2655 * risposte di hook sincrone. Non copiare output di strumento non attendibile in esso.
2656 */
2657 classifierContext?: string;
1956 updatedToolOutput?: unknown;2658 updatedToolOutput?: unknown;
1957 /** @deprecated Usa `updatedToolOutput`, che funziona per tutti gli strumenti. */2659 /** @deprecated Usa `updatedToolOutput`, che funziona per tutti gli strumenti. */
1958 updatedMCPToolOutput?: unknown;2660 updatedMCPToolOutput?: unknown;
1965 hookEventName: "PostToolBatch";2667 hookEventName: "PostToolBatch";
1966 additionalContext?: string;2668 additionalContext?: string;
1967 }2669 }
2670 | {
2671 hookEventName: "Stop";
2672 additionalContext?: string;
2673 }
2674 | {
2675 hookEventName: "SubagentStop";
2676 additionalContext?: string;
2677 }
2678 | {
2679 hookEventName: "PermissionDenied";
2680 retry?: boolean;
2681 }
1968 | {2682 | {
1969 hookEventName: "Notification";2683 hookEventName: "Notification";
1970 additionalContext?: string;2684 additionalContext?: string;
1982 message?: string;2696 message?: string;
1983 interrupt?: boolean;2697 interrupt?: boolean;
1984 };2698 };
2699 }
2700 | {
2701 hookEventName: "Elicitation";
2702 action?: "accept" | "decline" | "cancel";
2703 content?: Record<string, unknown>;
2704 }
2705 | {
2706 hookEventName: "ElicitationResult";
2707 action?: "accept" | "decline" | "cancel";
2708 content?: Record<string, unknown>;
2709 }
2710 | {
2711 hookEventName: "CwdChanged";
2712 watchPaths?: string[];
2713 }
2714 | {
2715 hookEventName: "FileChanged";
2716 watchPaths?: string[];
2717 }
2718 | {
2719 hookEventName: "WorktreeCreate";
2720 worktreePath: string;
2721 }
2722 | {
2723 hookEventName: "MessageDisplay";
2724 /** Testo visualizzato al posto del delta. Ometti (o restituisci il delta invariato) per visualizzare l'originale. */
2725 displayContent?: string;
1985 };2726 };
1986};2727};
1987```2728```
1996 `ToolInputSchemas`2737 `ToolInputSchemas`
1997</h3>2738</h3>
1998 2739
1999Unione di tutti i tipi di input dei tool, esportati da `@anthropic-ai/claude-agent-sdk`.2740Unione di tipi di input dei tool esportati da `@anthropic-ai/claude-agent-sdk`; i membri includono:
2000 2741
2001```typescript theme={null}2742```typescript theme={null}
2002type ToolInputSchemas =2743type ToolInputSchemas =
2003 | AgentInput2744 | AgentInput
2745 | ArtifactInput
2004 | AskUserQuestionInput2746 | AskUserQuestionInput
2005 | BashInput2747 | BashInput
2006 | TaskOutputInput2748 | CronCreateInput
2749 | CronDeleteInput
2750 | CronListInput
2751 | EnterPlanModeInput
2007 | EnterWorktreeInput2752 | EnterWorktreeInput
2008 | ExitPlanModeInput2753 | ExitPlanModeInput
2754 | ExitWorktreeInput
2009 | FileEditInput2755 | FileEditInput
2010 | FileReadInput2756 | FileReadInput
2011 | FileWriteInput2757 | FileWriteInput
2015 | McpInput2761 | McpInput
2016 | MonitorInput2762 | MonitorInput
2017 | NotebookEditInput2763 | NotebookEditInput
2764 | ProjectsInput
2765 | PushNotificationInput
2766 | ReadMcpResourceDirInput
2018 | ReadMcpResourceInput2767 | ReadMcpResourceInput
2019 | SubscribeMcpResourceInput2768 | RefreshMcpToolsInput
2020 | SubscribePollingInput2769 | RemoteTriggerInput
2770 | REPLInput
2771 | ReportFindingsInput
2772 | ScheduleWakeupInput
2773 | ShowOnboardingRolePickerInput
2021 | TaskCreateInput2774 | TaskCreateInput
2022 | TaskGetInput2775 | TaskGetInput
2023 | TaskListInput2776 | TaskListInput
2777 | TaskOutputInput
2024 | TaskStopInput2778 | TaskStopInput
2025 | TaskUpdateInput2779 | TaskUpdateInput
2026 | TodoWriteInput2780 | TodoWriteInput
2027 | UnsubscribeMcpResourceInput
2028 | UnsubscribePollingInput
2029 | WebFetchInput2781 | WebFetchInput
2030 | WebSearchInput2782 | WebSearchInput
2031 | WorkflowInput;2783 | WorkflowInput;
2035 Agent2787 Agent
2036</h3>2788</h3>
2037 2789
2038**Nome del tool:** `Agent` (precedentemente `Task`, che è ancora accettato come alias)2790**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.
2791
2792<Note>
2793 Il campo `mode` è deprecato e ignorato su Claude Code v2.1.212 o successivo. Un subagente viene eseguito in modalità di permesso della sessione padre o della sua definizione [`permissionMode`](#agentdefinition), e le [regole di ereditarietà del subagente](/docs/it/agent-sdk/permissions#available-modes) decidono quale.
2794</Note>
2039 2795
2040```typescript theme={null}2796```typescript theme={null}
2041type AgentInput = {2797type AgentInput = {
2045 model?: "sonnet" | "opus" | "haiku" | "fable";2801 model?: "sonnet" | "opus" | "haiku" | "fable";
2046 run_in_background?: boolean;2802 run_in_background?: boolean;
2047 name?: string;2803 name?: string;
2048 mode?: "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan";2804 team_name?: string; // Deprecato; ignorato
2049 isolation?: "worktree";2805 mode?: "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan"; // Deprecato; ignorato. Le regole di ereditarietà del subagente decidono la modalità di permesso di un subagente
2806 isolation?: "worktree" | "remote";
2050};2807};
2051```2808```
2052 2809
2066 options: Array<{ label: string; description: string; preview?: string }>;2823 options: Array<{ label: string; description: string; preview?: string }>;
2067 multiSelect: boolean;2824 multiSelect: boolean;
2068 }>;2825 }>;
2826 answers?: Record<string, string>;
2827 annotations?: Record<string, { preview?: string; notes?: string }>;
2828 metadata?: { source?: string };
2069};2829};
2070```2830```
2071 2831
2087};2847};
2088```2848```
2089 2849
2090Esegue comandi bash in una sessione shell persistente con timeout opzionale ed esecuzione in background.2850Esegue comandi Bash con timeout opzionale ed esecuzione in background. La directory di lavoro persiste tra i comandi, inclusi i comandi eseguiti in turni successivi di una sessione multi-turno; lo stato della shell come le variabili di ambiente esportate non persiste. Per i limiti su quali cambiamenti di directory si mantengono, vedi [Cosa persiste tra i comandi](/docs/it/tools-reference#what-persists-between-commands).
2091 2851
2092<h3 id="monitor">2852<h3 id="monitor">
2093 Monitor2853 Monitor
2103 protocols?: string[];2863 protocols?: string[];
2104 };2864 };
2105 description: string;2865 description: string;
2106 timeout_ms?: number;2866 timeout_ms: number;
2107 persistent?: boolean;2867 persistent: boolean;
2108};2868};
2109```2869```
2110 2870
2111Esegue una fonte di background e consegna ogni evento a Claude in modo che possa reagire senza polling: `command` esegue uno script e emette un evento per riga stdout, e `ws` apre un WebSocket e emette un evento per frame di testo. Fornisci esattamente uno tra `command` o `ws`. La fonte `ws` richiede Claude Code v2.1.195 o successivo.2871Esegue una fonte di background e consegna ogni evento a Claude in modo che possa reagire senza polling: `command` esegue uno script e emette un evento per riga stdout, e `ws` apre un WebSocket e emette un evento per frame di testo. Fornisci esattamente uno tra `command` o `ws`. La fonte `ws` richiede Claude Code v2.1.195 o successivo.
2112 2872
2113Imposta `persistent: true` per i watch di lunghezza della sessione come code tail. Quando Monitor esegue un comando, segue le stesse regole di permesso di Bash; un watch WebSocket richiede l'approvazione separatamente. Vedi il [riferimento del tool Monitor](/docs/it/tools-reference#monitor-tool) per il comportamento e la disponibilità del provider.2873Imposta `persistent: true` per i watch di lunghezza della sessione come code tail. Quando Monitor esegue un comando, segue le stesse regole di permesso di Bash; un watch WebSocket richiede l'approvazione separatamente. Vedi il [riferimento del tool Monitor](/docs/it/tools-reference#monitor-tool) per il comportamento e la disponibilità del provider. Il tipo esportato contrassegna `timeout_ms` e `persistent` come obbligatori perché lo schema riempie i loro valori predefiniti, 300000 e `false`; una chiamata che li omette convalida.
2114 2874
2115<h3 id="taskoutput">2875<h3 id="taskoutput">
2116 TaskOutput2876 TaskOutput
2118 2878
2119**Nome del tool:** `TaskOutput`2879**Nome del tool:** `TaskOutput`
2120 2880
2881<Note>`TaskOutput` è deprecato; preferisci `Read` sul percorso del file di output dell'attività. Gli schemi sottostanti rimangono validi per gli hook e i gestori di permessi che incontrano il tool.</Note>
2882
2121```typescript theme={null}2883```typescript theme={null}
2122type TaskOutputInput = {2884type TaskOutputInput = {
2123 task_id: string;2885 task_id: string;
2162 2924
2163Legge i file dal filesystem locale, inclusi testo, immagini, PDF e notebook Jupyter. Usa `pages` per gli intervalli di pagine PDF (ad esempio, `"1-5"`).2925Legge i file dal filesystem locale, inclusi testo, immagini, PDF e notebook Jupyter. Usa `pages` per gli intervalli di pagine PDF (ad esempio, `"1-5"`).
2164 2926
2927Per un PDF, Claude riceve il contenuto del file all'interno del `tool_result` della chiamata Read. Una lettura che restituisce l'output `pdf` [output](#tool-output-types) contiene un blocco `text` di riepilogo seguito da un blocco `document`. Una che restituisce l'output `parts` contiene il blocco `text` di riepilogo seguito da un blocco per ogni pagina estratta: un blocco `image`, o un blocco `text` che nomina la pagina quando Claude Code non poteva renderla come immagine. Prima di Agent SDK v0.3.242, Claude Code consegnava il contenuto del file come messaggio `user` separato dopo il risultato del tool.
2928
2165<h3 id="write">2929<h3 id="write">
2166 Write2930 Write
2167</h3>2931</h3>
2206 type?: string;2970 type?: string;
2207 output_mode?: "content" | "files_with_matches" | "count";2971 output_mode?: "content" | "files_with_matches" | "count";
2208 "-i"?: boolean;2972 "-i"?: boolean;
2973 "-o"?: boolean; // print only the matched parts of each line; requires output_mode: "content"
2209 "-n"?: boolean;2974 "-n"?: boolean;
2210 "-B"?: number;2975 "-B"?: number;
2211 "-A"?: number;2976 "-A"?: number;
2294 script?: string;3059 script?: string;
2295 name?: string;3060 name?: string;
2296 scriptPath?: string;3061 scriptPath?: string;
2297 args?: unknown;3062 args?: unknown; // any JSON value; the published typings render this as an object map
2298 resumeFromRunId?: string;3063 resumeFromRunId?: string;
3064 title?: string; // ignored; the script's meta block sets the title
3065 description?: string; // ignored; the script's meta block sets the description
2299};3066};
2300```3067```
2301 3068
2302Esegue un [workflow dinamico](/docs/it/workflows): uno script che orchestra molti subagenti in background e restituisce un risultato consolidato. Il tool `Workflow` è disponibile in Agent SDK v0.3.149 e versioni successive. Almeno uno tra `script`, `name` o `scriptPath` è obbligatorio.3069Esegue un [workflow dinamico](/docs/it/workflows): uno script che orchestra molti subagenti in background e restituisce un risultato consolidato. Il tool `Workflow` è disponibile in Agent SDK v0.3.149 e versioni successive. Almeno uno tra `script`, `name` o `scriptPath` è obbligatorio.
2303 3070
2304| Campo | Tipo | Descrizione |3071| Campo | Tipo | Descrizione |
2305| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3072| ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2306| `script` | `string` | Script di workflow inline. Deve iniziare con `export const meta = { name, description }` come letterale, seguito dal corpo dello script usando `agent()`, `parallel()`, `pipeline()` e `phase()`. Un array `phases` facoltativo in `meta` raggruppa gli agenti sotto fasi denominate nella vista di progresso |3073| `script` | `string` | Script di workflow inline. Deve iniziare con `export const meta = { name, description }` come letterale, seguito dal corpo dello script usando `agent()`, `parallel()`, `pipeline()` e `phase()`. Un array `phases` facoltativo in `meta` raggruppa gli agenti sotto fasi denominate nella vista di progresso |
2307| `name` | `string` | Nome di un workflow incorporato o uno salvato in `.claude/workflows/`. Risolto in uno script |3074| `name` | `string` | Nome di un workflow incorporato o uno salvato in `.claude/workflows/`. Risolto in uno script |
2308| `scriptPath` | `string` | Percorso a un file di script di workflow su disco. Ha la precedenza su `script` e `name`. Ogni invocazione persiste il suo script e restituisce il percorso nel risultato, quindi puoi modificare quel file e reinvocare con lo stesso `scriptPath` per iterare |3075| `scriptPath` | `string` | Percorso a un file di script di workflow su disco. Ha la precedenza su `script` e `name`. Claude Code persiste ogni invocazione dello script e restituisce il percorso nel risultato, quindi puoi modificare quel file e reinvocare con lo stesso `scriptPath` per iterare |
2309| `args` | `unknown` | Valore di input esposto allo script come `args` globale, per workflow denominati parametrizzati come una domanda di ricerca o un elenco di percorsi di file. Passa array e oggetti come valori JSON effettivi, non come stringa codificata in JSON |3076| `args` | `unknown` | Valore di input esposto allo script come `args` globale, per workflow denominati parametrizzati come una domanda di ricerca o un elenco di percorsi di file. Passa array e oggetti come valori JSON effettivi, non come stringa codificata in JSON |
2310| `resumeFromRunId` | `string` | ID di esecuzione di una precedente invocazione di `Workflow` da riprendere. Le chiamate `agent()` completate con input invariati restituiscono risultati memorizzati nella cache; solo le chiamate modificate o nuove vengono eseguite live. Solo la stessa sessione |3077| `resumeFromRunId` | `string` | ID di esecuzione di una precedente invocazione di `Workflow` da riprendere. Le chiamate `agent()` completate con input invariati restituiscono solitamente risultati memorizzati nella cache; il resto viene eseguito live. [Riprendi dopo una pausa](/docs/it/workflows#resume-after-a-pause) copre quali chiamate completate vengono rieseguite. Solo la stessa sessione |
3078| `title` | `string` | Ignorato; il blocco `meta` dello script imposta il titolo |
3079| `description` | `string` | Ignorato; il blocco `meta` dello script imposta la descrizione |
2311 3080
2312<h3 id="todowrite">3081<h3 id="todowrite">
2313 TodoWrite3082 TodoWrite
2328Crea e gestisce un elenco di attività strutturato per il tracciamento del progresso.3097Crea e gestisce un elenco di attività strutturato per il tracciamento del progresso.
2329 3098
2330<Note>3099<Note>
2331 A partire da TypeScript Agent SDK 0.3.142, `TodoWrite` è disabilitato per impostazione predefinita. Usa `TaskCreate`, `TaskGet`, `TaskUpdate` e `TaskList` invece. Vedi [Migra ai tool Task](/docs/it/agent-sdk/todo-tracking#migrate-to-task-tools) per aggiornare il tuo codice di monitoraggio, oppure imposta `CLAUDE_CODE_ENABLE_TASKS=0` per ripristinare `TodoWrite`.3100 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:
3101
3102 * `TodoWrite`
3103 * `TaskCreate`
3104 * `TaskGet`
3105 * `TaskUpdate`
3106 * `TaskList`
3107
3108 Wherever the tools are available, Claude Code provides the four Task tools, or `TodoWrite` instead when you set `CLAUDE_CODE_ENABLE_TASKS=0`.
3109
3110 This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.
3111
3112 Vedi [Disponibilità del modello](/docs/it/agent-sdk/todo-tracking#model-availability) per aderire.
2332</Note>3113</Note>
2333 3114
2334<h3 id="taskcreate">3115<h3 id="taskcreate">
2409 tool: "Bash";3190 tool: "Bash";
2410 prompt: string;3191 prompt: string;
2411 }>;3192 }>;
3193 [k: string]: unknown;
2412};3194};
2413```3195```
2414 3196
2458 3240
2459Crea e entra in un worktree git temporaneo per il lavoro isolato. Passa `path` per passare a un worktree esistente invece di crearne uno nuovo. Su primo ingresso il target deve essere un worktree registrato del repository corrente o, in uno spazio di lavoro multi-repo, di un repository annidato al suo interno; da una sessione worktree deve essere sotto `.claude/worktrees/` del repository della sessione. `name` e `path` si escludono a vicenda.3241Crea e entra in un worktree git temporaneo per il lavoro isolato. Passa `path` per passare a un worktree esistente invece di crearne uno nuovo. Su primo ingresso il target deve essere un worktree registrato del repository corrente o, in uno spazio di lavoro multi-repo, di un repository annidato al suo interno; da una sessione worktree deve essere sotto `.claude/worktrees/` del repository della sessione. `name` e `path` si escludono a vicenda.
2460 3242
3243<h3 id="exitworktree">
3244 ExitWorktree
3245</h3>
3246
3247**Nome del tool:** `ExitWorktree`
3248
3249```typescript theme={null}
3250type ExitWorktreeInput = {
3251 action: "keep" | "remove";
3252 discard_changes?: boolean;
3253};
3254```
3255
3256Esce dal worktree git corrente e ritorna alla directory di lavoro originale. L'azione `keep` lascia il worktree e il ramo su disco, mentre `remove` elimina entrambi. `discard_changes` deve essere `true` quando si rimuove un worktree che ha file non committati o commit non uniti.
3257
3258<h3 id="enterplanmode">
3259 EnterPlanMode
3260</h3>
3261
3262**Nome del tool:** `EnterPlanMode`
3263
3264```typescript theme={null}
3265type EnterPlanModeInput = {};
3266```
3267
3268Entra in modalità di pianificazione, dove Claude ricerca e presenta un piano prima di apportare modifiche.
3269
3270<h3 id="croncreate">
3271 CronCreate
3272</h3>
3273
3274**Nome del tool:** `CronCreate`
3275
3276```typescript theme={null}
3277type CronCreateInput = {
3278 cron: string;
3279 prompt: string;
3280 recurring?: boolean;
3281 durable?: boolean;
3282};
3283```
3284
3285Pianifica un prompt da eseguire su una pianificazione cron a 5 campi nell'ora locale. Imposta `recurring` a `false` per attivare una volta al prossimo match. I job sono scoped alla sessione per impostazione predefinita: avviare una conversazione fresca li cancella, e riprendere con `--resume` o `--continue` ripristina i job che non sono scaduti. Vedi [Attività pianificate](/docs/it/scheduled-tasks).
3286
3287Impostare `durable` a `true` richiede la persistenza a `.claude/scheduled_tasks.json` in modo che il job sopravviva ai riavvii. La pianificazione duratura non è disponibile in ogni sessione: quando non lo è, Claude Code accetta `durable: true` ma crea il job solo per la sessione. Leggi il campo `durable` dell'output per vedere se il job è persistito.
3288
3289<h3 id="crondelete">
3290 CronDelete
3291</h3>
3292
3293**Nome del tool:** `CronDelete`
3294
3295```typescript theme={null}
3296type CronDeleteInput = {
3297 id: string;
3298};
3299```
3300
3301Elimina un job cron pianificato per l'ID restituito da `CronCreate`.
3302
3303<h3 id="cronlist">
3304 CronList
3305</h3>
3306
3307**Nome del tool:** `CronList`
3308
3309```typescript theme={null}
3310type CronListInput = {};
3311```
3312
3313Elenca i job cron pianificati: job durevoli da `.claude/scheduled_tasks.json` e job solo per la sessione dalla sessione corrente.
3314
3315<h3 id="schedulewakeup">
3316 ScheduleWakeup
3317</h3>
3318
3319**Nome del tool:** `ScheduleWakeup`
3320
3321```typescript theme={null}
3322type ScheduleWakeupInput = {
3323 delaySeconds?: number;
3324 reason?: string;
3325 prompt?: string;
3326 noop?: boolean;
3327 stop?: boolean;
3328};
3329```
3330
3331Pianifica un wake-up una tantum che attiva il prompt dato dopo un ritardo. Questo tool supporta il comando `/loop` auto-paced. Il runtime limita `delaySeconds` tra 60 e 3600 secondi. I campi `delaySeconds`, `reason`, `prompt` e `noop` sono obbligatori a meno che `stop` non sia true. `noop: true` segnala un wake-up dove nulla è cambiato. Impostare `stop: true` annulla il wakeup in sospeso e termina il `/loop` auto-paced. Il campo `stop` richiede Claude Code v2.1.202 o successivo. Vedi la [riga ScheduleWakeup nel riferimento dei tool](/docs/it/tools-reference).
3332
3333<h3 id="remotetrigger">
3334 RemoteTrigger
3335</h3>
3336
3337**Nome del tool:** `RemoteTrigger`
3338
3339```typescript theme={null}
3340type RemoteTriggerInput = {
3341 action:
3342 | "list"
3343 | "get"
3344 | "create"
3345 | "update"
3346 | "run"
3347 | "create_webhook_trigger"
3348 | "list_runs"
3349 | "get_run_log";
3350 trigger_id?: string;
3351 session_id?: string;
3352 cursor?: string;
3353 body?: {
3354 [k: string]: unknown;
3355 };
3356};
3357```
3358
3359Gestisce [Routine](/docs/it/routines), le esecuzioni Claude Code pianificate e attivate ospitate nel cloud. Questo tool supporta il comando `/schedule`. `trigger_id` è obbligatorio per le azioni `get`, `update`, `run` e `list_runs`. `body` è obbligatorio per `create`, `update` e `create_webhook_trigger`, e facoltativo per `run`.
3360
3361`create_webhook_trigger` allega una fonte di evento a una routine esistente, come un [evento GitHub](/docs/it/routines#add-a-github-trigger) che lo attiva. Il `body` nomina la fonte, gli eventi e la routine da attivare. Richiede Claude Code v2.1.225 o successivo.
3362
3363`list_runs` elenca le esecuzioni recenti di una routine, e `get_run_log` legge il log di un'esecuzione. `session_id` nomina l'esecuzione da leggere, da un risultato `list_runs`, e `cursor` pagina attraverso i risultati di entrambe le azioni. Entrambe le azioni richiedono Claude Code v2.1.227 o successivo.
3364
3365Questo tool è disponibile solo quando la sessione è autenticata con un account claude.ai su un piano con Routine abilitate, ed è assente quando la politica della tua organizzazione disabilita [Claude Code sul web](/docs/it/claude-code-on-the-web). Su Claude Code v2.1.227 o successivo, il tool è anche assente quando un Proprietario ha [disattivato le routine per l'organizzazione](/docs/it/routines#routines-are-disabled-by-your-organizations-policy). Prima di v2.1.227, una sessione con solo il toggle delle routine disattivato mostrava comunque il tool, e il server negava le sue chiamate.
3366
3367<h3 id="pushnotification">
3368 PushNotification
3369</h3>
3370
3371**Nome del tool:** `PushNotification`
3372
3373```typescript theme={null}
3374type PushNotificationInput = {
3375 message: string;
3376 status: "proactive";
3377};
3378```
3379
3380Invia una notifica push proattiva all'utente. Mantieni `message` sotto 200 caratteri perché i sistemi operativi mobili troncano il testo più lungo. Vedi la [riga PushNotification nel riferimento dei tool](/docs/it/tools-reference) per la disponibilità del provider; la consegna push viene eseguita attraverso l'infrastruttura ospitata da Anthropic che non è accessibile da Amazon Bedrock, Claude Platform su AWS, Agent Platform di Google Cloud, o Microsoft Foundry.
3381
3382<h3 id="repl">
3383 REPL
3384</h3>
3385
3386**Nome del tool:** `REPL`
3387
3388```typescript theme={null}
3389type REPLInput = {
3390 code: string;
3391 description?: string;
3392 timeout?: number;
3393};
3394```
3395
3396Esegue il codice JavaScript in un REPL persistente. Lo stato persiste tra le chiamate e top-level await è supportato. `timeout` è in millisecondi, con un valore predefinito di 30000 e un massimo di 600000.
3397
3398I tipi vengono esportati, ma il tool è disattivato nelle sessioni SDK a meno che non imposti `CLAUDE_CODE_REPL=1` nell'[opzione `env`](#options). Richiede anche l'eseguibile `claude` basato su Bun che il programma di installazione nativo fornisce.
3399
3400<h3 id="reportfindings">
3401 ReportFindings
3402</h3>
3403
3404**Nome del tool:** `ReportFindings`
3405
3406```typescript theme={null}
3407type ReportFindingsInput = {
3408 level?: "low" | "medium" | "high" | "xhigh" | "max";
3409 findings: Array<{
3410 file: string;
3411 line?: number;
3412 summary: string;
3413 failure_scenario: string;
3414 short_summary?: string;
3415 category?: string;
3416 verdict?: "CONFIRMED" | "PLAUSIBLE";
3417 outcome?: "fixed" | "skipped" | "no_change_needed";
3418 }>;
3419};
3420```
3421
3422Segnala i risultati della revisione del codice come un elenco strutturato in modo che Claude Code possa renderli invece di stamparli come testo. `level` è il livello di sforzo con cui è stata eseguita la revisione. I risultati sono ordinati dal più grave al meno grave, con al massimo 32 per chiamata, e l'array è vuoto quando nessuno è sopravvissuto. Richiede Claude Code v2.1.196 o successivo.
3423
3424Ogni risultato contiene questi campi:
3425
3426* `file`: percorso relativo al repository in cui si trova il risultato. L'opzionale `line` è la riga 1-indicizzata a cui si ancora.
3427* `summary`: dichiarazione di una frase del difetto. `failure_scenario` descrive gli input concreti e lo stato che portano all'output errato o al crash.
3428* `short_summary`: etichetta compressa opzionale di al massimo 60 caratteri per la visualizzazione compatta. Richiede Claude Code v2.1.212 o successivo.
3429* `category`: slug opzionale in kebab-case breve del tipo di risultato, come `correctness` o `test-coverage`. Richiede Claude Code v2.1.199 o successivo.
3430* `verdict`: impostato quando è stata eseguita una pass di verifica; assente nelle revisioni solo inline.
3431* `outcome`: impostato solo quando si segnala di nuovo dopo aver applicato le correzioni.
3432
3433<h3 id="artifact">
3434 Artifact
3435</h3>
3436
3437**Nome del tool:** `Artifact`
3438
3439```typescript theme={null}
3440type ArtifactInput = {
3441 action?: "publish" | "list";
3442 file_path?: string;
3443 favicon?: string;
3444 limit?: number;
3445 scope?: "mine" | "shared" | "all";
3446 title?: string;
3447 description?: string;
3448 label?: string;
3449 url?: string;
3450 force?: boolean;
3451 capabilities?: Record<string, unknown>;
3452 contract?: "latest" | string;
3453};
3454```
3455
3456Pubblica un file `.html` o `.md` locale come pagina di artifact ospitata, o elenca gli artifact pubblicati dell'utente. Ometti `action` o passa `"publish"` per pubblicare `file_path`, che è obbligatorio per l'azione di pubblicazione insieme a `favicon`, uno o due emoji che contrassegnano l'artifact nella galleria dell'utente. `title` nomina la pagina pubblicata nella scheda del browser e nella galleria quando il file HTML non ha un tag `<title>`. `url` indirizza un artifact esistente da aggiornare sul posto invece di crearne uno nuovo.
3457
3458`force` è un'ultima risorsa di sovrascrittura che scarta una versione più recente che un'altra sessione ha pubblicato. In caso di conflitto, la pubblicazione non riuscita restituisce il contenuto più recente; Claude unisce le sue modifiche a quel contenuto, o rilegge l'artifact, e pubblica di nuovo. Passa `force` solo quando l'utente chiede esplicitamente di scartare quella versione.
3459
3460Passa `"list"` per enumerare gli artifact pubblicati dell'utente; solo `limit` e `scope` possono accompagnarlo. `scope` predefinito a `"mine"`, che elenca gli artifact che l'utente possiede; `"shared"` elenca gli artifact che altre persone hanno condiviso con l'utente, e `"all"` elenca entrambi.
3461
3462* `capabilities`: le capacità di runtime che la pagina pubblicata utilizza, codificate per nome di capacità, come i [connettori che la pagina può chiamare](/docs/it/artifacts#pull-live-data-with-mcp-connectors). Il servizio di artifact convalida la dichiarazione e rifiuta una pubblicazione che nomina una capacità che l'account non può utilizzare o ne fornisce una con una configurazione non valida. Passa `{}` per cancellare una dichiarazione memorizzata, e ometti il campo su una ridistribuzione per mantenerla. Richiede Agent SDK v0.3.235 o successivo.
3463* `contract`: la versione di runtime su cui viene eseguita la pagina pubblicata. Omettilo per mantenere la versione corrente dell'artifact, passa `"latest"` per aggiornare, o passa una versione specifica per fissare o eseguire il rollback. Richiede Agent SDK v0.3.235 o successivo.
3464
3465I tipi vengono esportati, ma il tool è disattivato per impostazione predefinita nelle sessioni Agent SDK. La pubblicazione richiede anche ogni condizione nella [tabella di disponibilità degli artifact](/docs/it/artifacts#availability), che le sessioni autenticate con una chiave API non soddisfano.
3466
3467<h3 id="projects">
3468 Projects
3469</h3>
3470
3471**Nome del tool:** `Projects`
3472
3473```typescript theme={null}
3474type ProjectsInput = {
3475 method:
3476 | "project_info"
3477 | "project_read"
3478 | "project_search"
3479 | "project_write"
3480 | "project_delete";
3481 path?: string;
3482 content?: string;
3483 local_path?: string;
3484 present_to_user?: boolean;
3485 query?: string;
3486 n?: number;
3487};
3488```
3489
3490Legge e scrive il Progetto claude.ai allegato alla sessione. Invia a `method`:
3491
3492* `project_info`: restituisce i metadati del progetto e l'elenco dei documenti.
3493* `project_read`: legge un documento per `path`.
3494* `project_search`: interroga la base di conoscenza del progetto con `query`. `n` limita i risultati e predefinito a 5.
3495* `project_write`: crea o sostituisce un documento in `path` da esattamente uno tra `content`, che contiene testo inline, o `local_path`, che nomina un file all'interno della directory di lavoro. `present_to_user: true` contrassegna il documento scritto come il deliverable che l'utente deve vedere.
3496* `project_delete`: elimina un documento per `path`.
3497
3498<h3 id="readmcpresourcedir">
3499 ReadMcpResourceDir
3500</h3>
3501
3502**Nome del tool:** `ReadMcpResourceDirTool`
3503
3504```typescript theme={null}
3505type ReadMcpResourceDirInput = {
3506 server: string;
3507 uri: string;
3508};
3509```
3510
3511Elenca i figli diretti di una risorsa di directory su un server MCP. Utilizzabile solo su un server che ha dichiarato il supporto per l'elenco delle directory; l'elenco non è ricorsivo. L'elenco delle directory non è abilitato in ogni sessione: quando è disattivato, la chiamata restituisce un elenco `resources` vuoto e il campo `error` segnala che l'elenco delle directory non è abilitato.
3512
3513<h3 id="refreshmcptools">
3514 RefreshMcpTools
3515</h3>
3516
3517**Nome del tool:** `RefreshMcpTools`
3518
3519```typescript theme={null}
3520type RefreshMcpToolsInput = {
3521 server?: string; // refresh only this server; omit to refresh all connected servers
3522};
3523```
3524
3525Riesamina l'elenco dei tool dei server MCP connessi e applica eventuali modifiche. I tipi vengono esportati, ma Claude Code registra il tool solo quando imposti `CLAUDE_CODE_ENABLE_REFRESH_MCP_TOOLS=1` nell'[opzione `env`](#options), e solo nelle sessioni con almeno un server MCP. Richiede Claude Code v2.1.211 o successivo.
3526
3527<h3 id="showonboardingrolepicker">
3528 ShowOnboardingRolePicker
3529</h3>
3530
3531**Nome del tool:** `ShowOnboardingRolePicker`
3532
3533```typescript theme={null}
3534type ShowOnboardingRolePickerInput = {};
3535```
3536
3537Renderizza una riga di chip selettore di ruolo cliccabile durante l'onboarding di Cowork in modo che l'utente possa scegliere il suo ruolo e ottenere un plugin corrispondente installato. Non accetta argomenti; l'elenco dei ruoli è definito dal client. La chiamata si blocca fino a quando l'utente non risponde.
3538
3539<h3 id="mcpinput">
3540 McpInput
3541</h3>
3542
3543**Nome del tool:** nomi di tool MCP dinamici della forma `mcp__<server>__<tool>`
3544
3545```typescript theme={null}
3546type McpInput = {
3547 [k: string]: unknown;
3548};
3549```
3550
3551Gli argomenti dei tool MCP sono un oggetto aperto: ogni server definisce i suoi propri parametri, quindi il tipo non pone vincoli sui nomi dei campi o sui valori. Consulta lo schema dei tool del server per i campi che uno strumento specifico accetta.
3552
2461<h2 id="tool-output-types">3553<h2 id="tool-output-types">
2462 Tipi di output dei tool3554 Tipi di output dei tool
2463</h2>3555</h2>
2468 `ToolOutputSchemas`3560 `ToolOutputSchemas`
2469</h3>3561</h3>
2470 3562
2471Unione di tutti i tipi di output dei tool.3563Unione di tipi di output dei tool esportati da `@anthropic-ai/claude-agent-sdk`; i membri includono:
2472 3564
2473```typescript theme={null}3565```typescript theme={null}
2474type ToolOutputSchemas =3566type ToolOutputSchemas =
2475 | AgentOutput3567 | AgentOutput
3568 | ArtifactOutput
2476 | AskUserQuestionOutput3569 | AskUserQuestionOutput
2477 | BashOutput3570 | BashOutput
3571 | CronCreateOutput
3572 | CronDeleteOutput
3573 | CronListOutput
3574 | EnterPlanModeOutput
2478 | EnterWorktreeOutput3575 | EnterWorktreeOutput
2479 | ExitPlanModeOutput3576 | ExitPlanModeOutput
3577 | ExitWorktreeOutput
2480 | FileEditOutput3578 | FileEditOutput
2481 | FileReadOutput3579 | FileReadOutput
2482 | FileWriteOutput3580 | FileWriteOutput
2483 | GlobOutput3581 | GlobOutput
2484 | GrepOutput3582 | GrepOutput
2485 | ListMcpResourcesOutput3583 | ListMcpResourcesOutput
3584 | McpOutput
2486 | MonitorOutput3585 | MonitorOutput
2487 | NotebookEditOutput3586 | NotebookEditOutput
3587 | ProjectsOutput
3588 | PushNotificationOutput
3589 | ReadMcpResourceDirOutput
2488 | ReadMcpResourceOutput3590 | ReadMcpResourceOutput
3591 | RefreshMcpToolsOutput
3592 | RemoteTriggerOutput
3593 | REPLOutput
3594 | ReportFindingsOutput
3595 | ScheduleWakeupOutput
3596 | ShowOnboardingRolePickerOutput
2489 | TaskCreateOutput3597 | TaskCreateOutput
2490 | TaskGetOutput3598 | TaskGetOutput
2491 | TaskListOutput3599 | TaskListOutput
2501 Agent3609 Agent
2502</h3>3610</h3>
2503 3611
2504**Nome del tool:** `Agent` (precedentemente `Task`, che è ancora accettato come alias)3612**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à con le versioni precedenti.
2505 3613
2506```typescript theme={null}3614```typescript theme={null}
2507type AgentOutput =3615type AgentOutput =
2511 agentType?: string;3619 agentType?: string;
2512 content: Array<{ type: "text"; text: string; citations?: unknown[] | null }>;3620 content: Array<{ type: "text"; text: string; citations?: unknown[] | null }>;
2513 resolvedModel?: string;3621 resolvedModel?: string;
3622 modelsUsed?: string[];
2514 totalToolUseCount: number;3623 totalToolUseCount: number;
2515 totalDurationMs: number;3624 totalDurationMs: number;
2516 totalTokens: number;3625 totalTokens: number;
2531 inference_geo?: string | null;3640 inference_geo?: string | null;
2532 speed?: string | null;3641 speed?: string | null;
2533 iterations?: unknown;3642 iterations?: unknown;
3643 output_tokens_details?: {
3644 thinking_tokens?: number | null;
3645 } | null;
2534 };3646 };
2535 toolStats?: {3647 toolStats?: {
2536 readCount: number;3648 readCount: number;
2552 agentId: string;3664 agentId: string;
2553 description: string;3665 description: string;
2554 resolvedModel?: string;3666 resolvedModel?: string;
3667 modelsUsed?: string[];
2555 prompt: string;3668 prompt: string;
2556 outputFile: string;3669 outputFile: string;
2557 canReadOutputFile?: boolean;3670 canReadOutputFile?: boolean;
2568 3681
2569Restituisce il risultato dal subagente. Discriminato sul campo `status`: `"completed"` per le attività finite, `"async_launched"` per le attività di background, e `"remote_launched"` per le attività che Claude Code ha inviato a una sessione cloud remota, dove `sessionUrl` si collega a quella sessione e `taskId` l'identifica.3682Restituisce il risultato dal subagente. Discriminato sul campo `status`: `"completed"` per le attività finite, `"async_launched"` per le attività di background, e `"remote_launched"` per le attività che Claude Code ha inviato a una sessione cloud remota, dove `sessionUrl` si collega a quella sessione e `taskId` l'identifica.
2570 3683
2571Il campo `resolvedModel` sulle varianti `completed` e `async_launched` nomina il modello su cui il subagente ha effettivamente eseguito, che può differire dal `model` input richiesto quando [`availableModels`](/docs/it/model-config#restrict-model-selection) o un altro override si applica. Questo campo richiede Claude Code v2.1.174 o successivo.3684Sulla variante `completed`, `resolvedModel` nomina il modello su cui il subagente ha iniziato, che può differire dal `model` input richiesto quando [`availableModels`](/docs/it/model-config#restrict-model-selection) o un altro override si applica. Questo campo richiede Claude Code v2.1.174 o successivo. Su `async_launched`, nomina il modello in uso quando l'attività è passata allo sfondo.
3685
3686`modelsUsed` elenca i modelli utilizzati dal subagente, in ordine. Il campo è presente solo quando si è verificato uno scambio a metà esecuzione, e un modello appare di nuovo quando l'esecuzione è tornata a esso. Su `async_launched`, l'elenco copre i modelli utilizzati prima di passare allo sfondo. Sia `modelsUsed` che il comportamento di passaggio allo sfondo di `resolvedModel` richiedono Claude Code v2.1.212 o successivo.
3687
3688Se Claude Code [ha mantenuto il worktree isolato del subagente](/docs/it/worktrees#isolate-subagents-with-worktrees), `worktreePath` sul risultato `completed` è dove trovarlo. `worktreeBranch` è il suo ramo, presente quando Claude Code ha creato il worktree con git.
2572 3689
2573Sulla variante `completed`, `worktreePath` viene impostato quando il subagente è stato eseguito in un worktree git isolato, e `worktreeBranch` nomina il ramo di quel worktree quando Claude Code l'ha creato. `usage.service_tier` contiene la stringa del livello di servizio che l'API ha segnalato per le richieste del subagente.3690Claude Code riempie `usage` e `totalTokens` dalla richiesta API finale del subagente, non dall'intera esecuzione, quindi `usage.service_tier` è la stringa del livello di servizio che l'API ha segnalato su quella richiesta. Quando presente, `usage.output_tokens_details.thinking_tokens` è il numero di token di output di quella richiesta che erano token di thinking. Il campo `output_tokens_details` richiede TypeScript SDK v0.3.228 o successivo, che raggruppa Claude Code v2.1.228.
3691
3692`usage.output_tokens_details` corrisponde a [`Usage.output_tokens_details`](#usage) nel significato, limitato a quella richiesta finale, ma ogni livello di esso è opzionale qui. Proteggi sia l'oggetto che il campo, ad esempio `usage.output_tokens_details?.thinking_tokens ?? 0`, piuttosto che leggerlo direttamente.
2574 3693
2575Prima della v2.1.207, il tipo pubblicato era più ristretto. Ometteva `worktreePath`, `worktreeBranch`, `citations`, `toolStats.frameCount`, e i campi di utilizzo `inference_geo`, `speed` e `iterations`, e tipizzava `service_tier` come `"standard" | "priority" | "batch"`. I campi che il tipo contrassegna come opzionali possono essere assenti nei risultati registrati da versioni precedenti.3694Prima della v2.1.207, il tipo pubblicato era più ristretto. Ometteva `worktreePath`, `worktreeBranch`, `citations`, `toolStats.frameCount`, e i campi di utilizzo `inference_geo`, `speed` e `iterations`, e tipizzava `service_tier` come `"standard" | "priority" | "batch"`. I campi che il tipo contrassegna come opzionali possono essere assenti nei risultati registrati da versioni precedenti.
2576 3695
2590 }>;3709 }>;
2591 answers: Record<string, string>;3710 answers: Record<string, string>;
2592 response?: string;3711 response?: string;
3712 annotations?: Record<string, { preview?: string; notes?: string }>;
3713 afkTimeoutMs?: number;
2593};3714};
2594```3715```
2595 3716
2610 isImage?: boolean;3731 isImage?: boolean;
2611 backgroundTaskId?: string;3732 backgroundTaskId?: string;
2612 backgroundedByUser?: boolean;3733 backgroundedByUser?: boolean;
3734 timedOutAfterMs?: number;
3735 backgroundCwdHint?: string;
3736 backgroundEndsWithFinalResponse?: true;
2613 dangerouslyDisableSandbox?: boolean;3737 dangerouslyDisableSandbox?: boolean;
2614 returnCodeInterpretation?: string;3738 returnCodeInterpretation?: string;
3739 noOutputExpected?: boolean;
2615 structuredContent?: unknown[];3740 structuredContent?: unknown[];
2616 persistedOutputPath?: string;3741 persistedOutputPath?: string;
2617 persistedOutputSize?: number;3742 persistedOutputSize?: number;
3743 staleReadFileStateHint?: string;
3744 ghRateLimitHint?: string;
3745 gitOperation?: {
3746 commit?: { sha: string; kind: "committed" | "amended" | "cherry-picked"; branch?: string };
3747 push?: { branch: string };
3748 branch?: { ref: string; action: "merged" | "rebased" };
3749 pr?: {
3750 number: number;
3751 url?: string;
3752 action: "created" | "edited" | "merged" | "commented" | "closed" | "reopened" | "ready" | "draft" | "auto-merge-enabled" | "auto-merge-disabled";
3753 };
3754 };
2618};3755};
2619```3756```
2620 3757
2621Restituisce l'output del comando con stdout/stderr divisi. I comandi di background includono un `backgroundTaskId`.3758I campi `stdout`, `stderr` e `backgroundTaskId` contengono:
3759
3760| Campo | Cosa contiene |
3761| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
3762| `stdout` | Lo stdout e stderr del comando, uniti in un unico flusso intercalato |
3763| `stderr` | Avvisi che lo strumento stesso aggiunge, come un ripristino della directory di lavoro della shell, non lo stderr del comando |
3764| `backgroundTaskId` | Presente per i comandi di background |
3765
3766`timedOutAfterMs` è il timeout in millisecondi, impostato quando il comando ha raggiunto il suo timeout e si è spostato allo sfondo piuttosto che iniziare lì esplicitamente. `backgroundCwdHint` viene impostato quando il comando in background conteneva un builtin di cambio directory come `cd`, `pushd`, `popd` o `chdir`, e nota che la directory di lavoro della sessione non è cambiata. Entrambi i campi richiedono Claude Code v2.1.210 o successivo.
3767
3768Quando un subagente in esecuzione in primo piano possiede un comando in background, Claude Code termina il comando quando quel subagente fornisce la sua risposta finale. Claude Code imposta `backgroundEndsWithFinalResponse` su `true` su tali comandi, e omette il campo quando il comando sopravvive al turno, come i comandi avviati dalla conversazione principale o dai subagenti di background. Il campo richiede Claude Code v2.1.227 o successivo.
3769
3770Claude Code imposta `gitOperation.commit.branch` al ramo denominato nella riga di riepilogo del commit di git, e lo omette per un commit effettuato su un HEAD staccato. Il campo richiede Agent SDK v0.3.227 o successivo. Claude Code segnala un comando `gh pr reopen` come l'azione PR `reopened`, che richiede Agent SDK v0.3.234 o successivo.
2622 3771
2623<h3 id="monitor-2">3772<h3 id="monitor-2">
2624 Monitor3773 Monitor
2647 filePath: string;3796 filePath: string;
2648 oldString: string;3797 oldString: string;
2649 newString: string;3798 newString: string;
2650 originalFile: string;3799 originalFile: string | null;
2651 structuredPatch: Array<{3800 structuredPatch: Array<{
2652 oldStart: number;3801 oldStart: number;
2653 oldLines: number;3802 oldLines: number;
2664 deletions: number;3813 deletions: number;
2665 changes: number;3814 changes: number;
2666 patch: string;3815 patch: string;
3816 repository?: string | null;
2667 };3817 };
2668};3818};
2669```3819```
2686 numLines: number;3836 numLines: number;
2687 startLine: number;3837 startLine: number;
2688 totalLines: number;3838 totalLines: number;
3839 /** True quando una lettura di file intero è stata impaginata automaticamente perché ha superato il limite di token (il contenuto è una prima pagina parziale). */
3840 truncatedByTokenCap?: boolean;
2689 };3841 };
2690 }3842 }
2691 | {3843 | {
2725 count: number;3877 count: number;
2726 outputDir: string;3878 outputDir: string;
2727 };3879 };
3880 /** Numero di pagina del documento della prima pagina estratta; etichetta le immagini della pagina nel contenuto tool_result. */
3881 firstPage?: number;
3882 /** Solo in-process: i byte dell'immagine della pagina vengono consegnati come blocchi di immagine nel contenuto tool_result e non vengono conservati nel tool_use_result emesso, quindi questa chiave è assente lì. */
3883 pages?: {
3884 base64: string;
3885 mediaType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
3886 error?: string;
3887 }[];
3888 }
3889 | {
3890 type: "file_unchanged";
3891 file: {
3892 filePath: string;
3893 };
3894 /** Impostato quando la dedup ha corrisposto a una voce seminata all'avvio (CLAUDE.md / memoria nidificata) piuttosto che a un precedente risultato tool_result di Read. */
3895 source?: "seeded";
2728 };3896 };
2729```3897```
2730 3898
2756 deletions: number;3924 deletions: number;
2757 changes: number;3925 changes: number;
2758 patch: string;3926 patch: string;
3927 repository?: string | null;
2759 };3928 };
3929 userModified?: boolean;
2760};3930};
2761```3931```
2762 3932
2763Restituisce il risultato della scrittura con informazioni sul diff strutturato.3933Restituisce il risultato della scrittura con informazioni sul diff strutturato. Ciò che `originalFile` e `structuredPatch` contengono dipende dalla scrittura:
3934
3935* Per un file appena creato, `originalFile` è null e `structuredPatch` è vuoto
3936* Su una sovrascrittura, `originalFile` contiene il contenuto precedente, tranne quando quel contenuto è più grande di circa 10 MB: Claude Code quindi salta il diff e restituisce `originalFile` null e `structuredPatch` vuoto
3937* `structuredPatch` è anche vuoto quando la scrittura non ha cambiato nulla o il diff è scaduto
2764 3938
2765<h3 id="glob-2">3939<h3 id="glob-2">
2766 Glob3940 Glob
2774 numFiles: number;3948 numFiles: number;
2775 filenames: string[];3949 filenames: string[];
2776 truncated: boolean;3950 truncated: boolean;
3951 totalMatches?: number;
3952 countIsComplete?: boolean;
2777};3953};
2778```3954```
2779 3955
2780Restituisce i percorsi dei file che corrispondono al pattern glob, ordinati per tempo di modifica.3956Restituisce i percorsi dei file che corrispondono al pattern glob, ordinati per tempo di modifica.
2781 3957
3958`totalMatches` e `countIsComplete` richiedono Claude Code v2.1.191 o successivo. `totalMatches` segnala il numero di file corrispondenti prima del troncamento. Quando `countIsComplete` è false, `totalMatches` è un limite inferiore perché la ricerca sottostante ha troncato il suo stesso output.
3959
2782<h3 id="grep-2">3960<h3 id="grep-2">
2783 Grep3961 Grep
2784</h3>3962</h3>
2793 content?: string;3971 content?: string;
2794 numLines?: number;3972 numLines?: number;
2795 numMatches?: number;3973 numMatches?: number;
3974 totalFiles?: number;
3975 totalLines?: number;
2796 appliedLimit?: number;3976 appliedLimit?: number;
2797 appliedOffset?: number;3977 appliedOffset?: number;
2798};3978};
2799```3979```
2800 3980
2801Restituisce i risultati della ricerca. La forma varia in base a `mode`: elenco di file, contenuto con corrispondenze o conteggi di corrispondenze.3981Restituisce i risultati della ricerca. La forma varia in base a `mode`: elenco di file, contenuto con corrispondenze o conteggi di corrispondenze. In modalità `count`, `numFiles` e `numMatches` sono totali sull'intero set di risultati, non sulla sezione impaginata. Prima della v2.1.208, un `head_limit` o `offset` che troncava le voci elencate troncava anche questi totali.
3982
3983`totalFiles` richiede Claude Code v2.1.208 o successivo e segnala il numero totale di risultati prima della paginazione `head_limit` e `offset` in modalità `files_with_matches`. `totalLines` richiede Claude Code v2.1.210 o successivo e segnala il numero totale di righe prima della paginazione in modalità `content`.
2802 3984
2803<h3 id="taskstop-2">3985<h3 id="taskstop-2">
2804 TaskStop3986 TaskStop
2826```typescript theme={null}4008```typescript theme={null}
2827type NotebookEditOutput = {4009type NotebookEditOutput = {
2828 new_source: string;4010 new_source: string;
4011 old_source?: string;
2829 cell_id?: string;4012 cell_id?: string;
2830 cell_type: "code" | "markdown";4013 cell_type: "code" | "markdown";
2831 language: string;4014 language: string;
2853 result: string;4036 result: string;
2854 durationMs: number;4037 durationMs: number;
2855 url: string;4038 url: string;
4039 artifactRead?: {
4040 slug: string;
4041 ver?: string;
4042 seeded?: false;
4043 };
2856};4044};
2857```4045```
2858 4046
2859Restituisce il contenuto recuperato con lo stato HTTP e i metadati.4047Restituisce il contenuto recuperato con lo stato HTTP e i metadati.
2860 4048
4049`artifactRead` è il record proprio di Claude Code di una lettura di artifact, presente solo quando Claude ha recuperato un artifact che la sessione può pubblicare. Claude Code lo legge di nuovo quando una sessione riprende in modo che una successiva pubblicazione si basi sulla versione giusta; il tuo codice non ha bisogno di agire su di esso. `slug` nomina l'artifact, `ver` è la versione che la lettura ha messo in record ed è assente quando non ne ha registrata nessuna, e `seeded: false` contrassegna una lettura il cui codice sorgente completo non ha raggiunto Claude. Il campo `seeded` richiede Agent SDK v0.3.239 o successivo.
4050
2861<h3 id="websearch-2">4051<h3 id="websearch-2">
2862 WebSearch4052 WebSearch
2863</h3>4053</h3>
2875 | string4065 | string
2876 >;4066 >;
2877 durationSeconds: number;4067 durationSeconds: number;
4068 searchCount?: number;
2878};4069};
2879```4070```
2880 4071
2888 4079
2889```typescript theme={null}4080```typescript theme={null}
2890type WorkflowOutput = {4081type WorkflowOutput = {
2891 status: "async_launched";4082 status: "async_launched" | "remote_launched";
2892 taskId: string;4083 taskId: string;
4084 taskType?: "local_workflow" | "remote_agent";
4085 workflowName?: string;
2893 runId?: string;4086 runId?: string;
2894 summary?: string;4087 summary?: string;
2895 transcriptDir?: string;4088 transcriptDir?: string;
2896 scriptPath?: string;4089 scriptPath?: string;
4090 sessionUrl?: string; // impostato quando il workflow è stato avviato come sessione remota
4091 warning?: string;
2897 error?: string;4092 error?: string;
2898};4093};
2899```4094```
2901Restituisce immediatamente dopo che il tool accetta l'invocazione. Il risultato finale arriva successivamente come completamento di un'attività. Controlla `error` prima di trattare l'esecuzione come avviata: uno script che non supera il controllo della sintassi restituisce `status: "async_launched"` con `error` impostato e non viene mai eseguito.4096Restituisce immediatamente dopo che il tool accetta l'invocazione. Il risultato finale arriva successivamente come completamento di un'attività. Controlla `error` prima di trattare l'esecuzione come avviata: uno script che non supera il controllo della sintassi restituisce `status: "async_launched"` con `error` impostato e non viene mai eseguito.
2902 4097
2903| Campo | Tipo | Descrizione |4098| Campo | Tipo | Descrizione |
2904| --------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |4099| --------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2905| `status` | `"async_launched"` | Il tool ha accettato l'invocazione. Questo è l'unico valore che il campo assume |4100| `status` | `"async_launched" \| "remote_launched"` | Il tool ha accettato l'invocazione. `"async_launched"` per le esecuzioni in-process, `"remote_launched"` per le esecuzioni inviate a una sessione remota invece di essere eseguite in-process |
2906| `taskId` | `string` | Identificatore dell'attività di background per l'esecuzione |4101| `taskId` | `string` | Identificatore dell'attività di background per l'esecuzione |
2907| `runId` | `string` | Identificatore dell'esecuzione del workflow da passare come `resumeFromRunId` in una successiva invocazione |4102| `taskType` | `"local_workflow" \| "remote_agent"` | Tipo di attività dell'attività di background registrata, corrispondente al ramo `status` |
4103| `workflowName` | `string` | Il `meta.name` dallo script del workflow |
4104| `runId` | `string` | Identificatore dell'esecuzione del workflow da passare come `resumeFromRunId` in una successiva invocazione. Assente per le esecuzioni `remote_launched`, dove l'URL della sessione cloud è l'handle di ripresa |
2908| `summary` | `string` | Descrizione in una riga di ciò che fa il workflow |4105| `summary` | `string` | Descrizione in una riga di ciò che fa il workflow |
2909| `transcriptDir` | `string` | Directory dove i transcript dei subagenti vengono scritti durante l'esecuzione |4106| `transcriptDir` | `string` | Directory dove i transcript dei subagenti vengono scritti durante l'esecuzione |
2910| `scriptPath` | `string` | Percorso dello script del workflow persistente per questa esecuzione. Modificalo e passalo come `scriptPath` per rieseguire senza inviare nuovamente lo script |4107| `scriptPath` | `string` | Percorso dello script del workflow persistente per questa esecuzione. Modificalo e passalo come `scriptPath` per rieseguire senza inviare nuovamente lo script |
2911| `error` | `string` | Impostato quando lo script non supera il controllo della sintassi. Quando presente, l'esecuzione non è stata avviata nonostante lo stato `async_launched` |4108| `sessionUrl` | `string` | URL della sessione cloud, impostato quando `status` è `"remote_launched"` |
4109| `warning` | `string` | Avviso non bloccante, come lo stato git locale che diverge dal ramo spinto che una sessione cloud clonerà |
4110| `error` | `string` | Impostato quando lo script non supera il controllo della sintassi. Quando presente, l'esecuzione non è stata avviata nonostante lo stato di avvio |
2912 4111
2913<h3 id="todowrite-2">4112<h3 id="todowrite-2">
2914 TodoWrite4113 TodoWrite
2934Restituisce gli elenchi di attività precedenti e aggiornati.4133Restituisce gli elenchi di attività precedenti e aggiornati.
2935 4134
2936<Note>4135<Note>
2937 A partire da TypeScript Agent SDK 0.3.142, `TodoWrite` è disabilitato per impostazione predefinita. Usa invece `TaskCreate`, `TaskGet`, `TaskUpdate` e `TaskList`. Vedi [Migrazione ai tool Task](/docs/it/agent-sdk/todo-tracking#migrate-to-task-tools) per aggiornare il tuo codice di monitoraggio, oppure imposta `CLAUDE_CODE_ENABLE_TASKS=0` per ripristinare `TodoWrite`.4136 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:
4137
4138 * `TodoWrite`
4139 * `TaskCreate`
4140 * `TaskGet`
4141 * `TaskUpdate`
4142 * `TaskList`
4143
4144 Wherever the tools are available, Claude Code provides the four Task tools, or `TodoWrite` instead when you set `CLAUDE_CODE_ENABLE_TASKS=0`.
4145
4146 This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.
4147
4148 Vedi [Disponibilità del modello](/docs/it/agent-sdk/todo-tracking#model-availability) per aderire.
2938</Note>4149</Note>
2939 4150
2940<h3 id="taskcreate-2">4151<h3 id="taskcreate-2">
3028 isAgent: boolean;4239 isAgent: boolean;
3029 filePath?: string;4240 filePath?: string;
3030 hasTaskTool?: boolean;4241 hasTaskTool?: boolean;
4242 planWasEdited?: boolean;
3031 awaitingLeaderApproval?: boolean;4243 awaitingLeaderApproval?: boolean;
3032 requestId?: string;4244 requestId?: string;
3033};4245};
3065 uri: string;4277 uri: string;
3066 mimeType?: string;4278 mimeType?: string;
3067 text?: string;4279 text?: string;
4280 blobSavedTo?: string;
3068 }>;4281 }>;
4282 error?: string;
3069};4283};
3070```4284```
3071 4285
3087 4301
3088Restituisce le informazioni sul worktree git.4302Restituisce le informazioni sul worktree git.
3089 4303
4304<h3 id="exitworktree-2">
4305 ExitWorktree
4306</h3>
4307
4308**Nome del tool:** `ExitWorktree`
4309
4310```typescript theme={null}
4311type ExitWorktreeOutput = {
4312 action: "keep" | "remove";
4313 originalCwd: string;
4314 worktreePath: string;
4315 worktreeBranch?: string;
4316 tmuxSessionName?: string;
4317 discardedFiles?: number;
4318 discardedCommits?: number;
4319 message: string;
4320};
4321```
4322
4323Restituisce l'azione intrapresa e i dettagli sul worktree che è stato abbandonato.
4324
4325<h3 id="enterplanmode-2">
4326 EnterPlanMode
4327</h3>
4328
4329**Nome del tool:** `EnterPlanMode`
4330
4331```typescript theme={null}
4332type EnterPlanModeOutput = {
4333 message: string;
4334};
4335```
4336
4337Restituisce una conferma che la modalità di pianificazione è stata attivata.
4338
4339<h3 id="croncreate-2">
4340 CronCreate
4341</h3>
4342
4343**Nome del tool:** `CronCreate`
4344
4345```typescript theme={null}
4346type CronCreateOutput = {
4347 id: string;
4348 humanSchedule: string;
4349 recurring: boolean;
4350 durable?: boolean; // true quando persistito in .claude/scheduled_tasks.json; false quando solo sessione
4351};
4352```
4353
4354Restituisce l'ID del lavoro e una descrizione leggibile della pianificazione.
4355
4356<h3 id="crondelete-2">
4357 CronDelete
4358</h3>
4359
4360**Nome del tool:** `CronDelete`
4361
4362```typescript theme={null}
4363type CronDeleteOutput = {
4364 id: string;
4365};
4366```
4367
4368Restituisce l'ID del lavoro eliminato.
4369
4370<h3 id="cronlist-2">
4371 CronList
4372</h3>
4373
4374**Nome del tool:** `CronList`
4375
4376```typescript theme={null}
4377type CronListOutput = {
4378 jobs: {
4379 id: string;
4380 cron: string;
4381 humanSchedule: string;
4382 prompt: string;
4383 recurring?: boolean;
4384 durable?: boolean;
4385 }[];
4386};
4387```
4388
4389Restituisce i lavori cron pianificati: lavori durevoli da `.claude/scheduled_tasks.json` e lavori solo sessione dalla sessione corrente. Un lavoro solo sessione porta `durable: false`; i lavori letti dal disco omettono il campo.
4390
4391<h3 id="schedulewakeup-2">
4392 ScheduleWakeup
4393</h3>
4394
4395**Nome del tool:** `ScheduleWakeup`
4396
4397```typescript theme={null}
4398type ScheduleWakeupOutput = {
4399 scheduledFor: number;
4400 clampedDelaySeconds: number;
4401 wasClamped: boolean;
4402 stopped?: boolean;
4403 cancelledWakeups?: number;
4404};
4405```
4406
4407Restituisce quando il risveglio si attiverà come timestamp di epoca in millisecondi, il ritardo effettivamente utilizzato, e se il ritardo richiesto è stato limitato. Il campo `stopped` è `true` quando la chiamata ha terminato il loop con `stop: true`. Richiede Claude Code v2.1.202 o successivo. Il campo `cancelledWakeups` conta quanti risvegli in sospeso una chiamata `stop: true` ha annullato. Un valore di 0 significa che nulla era in sospeso, e un cron `/loop` ricorrente non viene annullato da `stop: true`. Richiede Claude Code v2.1.206 o successivo.
4408
4409<h3 id="remotetrigger-2">
4410 RemoteTrigger
4411</h3>
4412
4413**Nome del tool:** `RemoteTrigger`
4414
4415```typescript theme={null}
4416type RemoteTriggerOutput = {
4417 status: number;
4418 json: string;
4419 summary?: string;
4420};
4421```
4422
4423Restituisce lo stato della risposta API e il corpo per l'operazione di attivazione.
4424
4425<h3 id="pushnotification-2">
4426 PushNotification
4427</h3>
4428
4429**Nome del tool:** `PushNotification`
4430
4431```typescript theme={null}
4432type PushNotificationOutput = {
4433 message: string;
4434 pushSent?: boolean;
4435 localSent?: boolean;
4436 disabledReason?: "config_off" | "user_present" | "no_transport";
4437 sentAt?: string;
4438};
4439```
4440
4441Restituisce i dettagli di consegna, incluso se una notifica push o locale è stata inviata e perché la consegna è stata saltata.
4442
4443<h3 id="repl-2">
4444 REPL
4445</h3>
4446
4447**Nome del tool:** `REPL`
4448
4449```typescript theme={null}
4450type REPLOutput = {
4451 code: string;
4452 result: {
4453 [k: string]: unknown;
4454 };
4455 stdout: string;
4456 stderr: string;
4457 error?: string;
4458 registeredTools?: string[];
4459 images?: {
4460 base64: string;
4461 mediaType: string;
4462 }[];
4463 documents?: {
4464 base64: string;
4465 }[];
4466};
4467```
4468
4469Restituisce il risultato dell'esecuzione, l'output della console acquisito, e qualsiasi immagine o documento esposto da chiamate `Read` interne.
4470
4471<h3 id="reportfindings-2">
4472 ReportFindings
4473</h3>
4474
4475**Nome del tool:** `ReportFindings`
4476
4477```typescript theme={null}
4478type ReportFindingsOutput = {
4479 count: number;
4480 level?: "low" | "medium" | "high" | "xhigh" | "max";
4481 findings: Array<{
4482 file: string;
4483 line?: number;
4484 summary: string;
4485 failure_scenario: string;
4486 short_summary?: string;
4487 category?: string;
4488 verdict?: "CONFIRMED" | "PLAUSIBLE";
4489 outcome?: "fixed" | "skipped" | "no_change_needed";
4490 }>;
4491};
4492```
4493
4494Restituisce il numero di risultati segnalati, il livello di sforzo con cui la revisione è stata eseguita, e i risultati ripetuti per il corpo del risultato. Richiede Claude Code v2.1.196 o successivo. Il campo `short_summary` ripetuto richiede Claude Code v2.1.212 o successivo.
4495
4496<h3 id="artifact-2">
4497 Artifact
4498</h3>
4499
4500**Nome del tool:** `Artifact`
4501
4502```typescript theme={null}
4503type ArtifactOutput =
4504 | {
4505 url: string;
4506 path: string;
4507 title?: string;
4508 version?: string;
4509 capabilities?: unknown;
4510 stored?: {
4511 contract: string;
4512 capabilities?: Record<string, unknown>;
4513 };
4514 warnings?: string[];
4515 contract?: string;
4516 updated?: boolean;
4517 liveSubscription?: string;
4518 }
4519 | {
4520 artifacts: Array<{
4521 title: string;
4522 url: string;
4523 updatedAt?: string;
4524 rel?: "mine" | "shared";
4525 }>;
4526 truncated?: boolean;
4527 scope?: "shared" | "all";
4528 };
4529```
4530
4531Restituisce l'`url` della pagina pubblicata e il `path` locale che è stato pubblicato per l'azione di pubblicazione, con `updated` impostato su true quando la pubblicazione ha ridistribuito un artifact esistente, e `warnings` che contiene eventuali avvisi al momento della pubblicazione. L'azione di elenco restituisce invece le righe `artifacts`, con `truncated` impostato quando esistono più artifact del limite richiesto. Negli elenchi il cui ambito non è `"mine"`, ogni riga contiene `rel` che contrassegna se l'utente possiede l'artifact o se è stato condiviso con loro, e l'`scope` dell'output registra quale ambito non predefinito ha prodotto l'elenco; entrambi sono assenti negli elenchi predefiniti.
4532
4533<h3 id="projects-2">
4534 Projects
4535</h3>
4536
4537**Nome del tool:** `Projects`
4538
4539```typescript theme={null}
4540type ProjectsOutput =
4541 | {
4542 method: "project_info";
4543 notice?: string;
4544 name: string;
4545 description: string;
4546 instructions: string;
4547 docs: Array<{ path: string; created_at: string | null }>;
4548 files?: Array<{
4549 path: string;
4550 file_kind: string;
4551 created_at: string | null;
4552 }>;
4553 sync_sources?: Array<{
4554 type: string | null;
4555 config: Record<string, unknown>;
4556 }>;
4557 knowledge: {
4558 knowledge_size: number;
4559 max_knowledge_size: number;
4560 };
4561 }
4562 | {
4563 method: "project_read";
4564 notice?: string;
4565 path: string;
4566 file_kind?: string;
4567 content?: string;
4568 local_file?: string;
4569 created_at: string | null;
4570 }
4571 | {
4572 method: "project_search";
4573 notice?: string;
4574 rag: boolean;
4575 hits?: Array<{ name?: string; doc_uuid?: string; text?: string }>;
4576 docs?: string[];
4577 }
4578 | {
4579 method: "project_write";
4580 notice?: string;
4581 path: string;
4582 doc_uuid: string;
4583 replaced: boolean;
4584 present_to_user?: boolean;
4585 local_path?: string;
4586 }
4587 | {
4588 method: "project_delete";
4589 notice?: string;
4590 path: string;
4591 deleted: boolean;
4592 };
4593```
4594
4595Discriminato sul campo `method`, rispecchiando l'input. `project_read` restituisce piccoli documenti di testo inline in `content` e scrive documenti più grandi in un percorso `local_file` invece; `project_search` restituisce `hits` RAG con `rag: true` quando l'indice del progetto è disponibile e ricade su un elenco di percorsi `docs` altrimenti.
4596
4597<h3 id="readmcpresourcedir-2">
4598 ReadMcpResourceDir
4599</h3>
4600
4601**Nome del tool:** `ReadMcpResourceDirTool`
4602
4603```typescript theme={null}
4604type ReadMcpResourceDirOutput = {
4605 resources: Array<{
4606 uri: string;
4607 name: string;
4608 mimeType?: string;
4609 }>;
4610 error?: string;
4611};
4612```
4613
4614Restituisce i figli diretti della risorsa directory. Le sottodirectory appaiono con mimeType `"inode/directory"`; `error` contiene un messaggio leggibile quando il server non poteva elencare la directory.
4615
4616<h3 id="refreshmcptools-2">
4617 RefreshMcpTools
4618</h3>
4619
4620**Nome del tool:** `RefreshMcpTools`
4621
4622```typescript theme={null}
4623type RefreshMcpToolsOutput = Array<{
4624 server: string;
4625 status: "refreshed" | "error" | "not_connected";
4626 toolCount?: number; // strumenti ora disponibili da questo server
4627 added?: string[]; // nomi degli strumenti che questo aggiornamento ha aggiunto
4628 removed?: string[]; // nomi degli strumenti che questo aggiornamento ha rimosso
4629 error?: string; // perché l'aggiornamento non è riuscito o il server non era disponibile
4630}>;
4631```
4632
4633Restituisce una voce per server: `refreshed` significa che l'elenco degli strumenti ri-interrogato è stato applicato, `error` significa che la ri-interrogazione non è riuscita e il set di strumenti precedente è stato mantenuto, e `not_connected` significa che il server non ha una connessione live per interrogare.
4634
4635<h3 id="showonboardingrolepicker-2">
4636 ShowOnboardingRolePicker
4637</h3>
4638
4639**Nome del tool:** `ShowOnboardingRolePicker`
4640
4641```typescript theme={null}
4642type ShowOnboardingRolePickerOutput = {
4643 role?: string;
4644 dismissed?: boolean;
4645};
4646```
4647
4648Restituisce la selezione dell'utente: `role` quando ha scelto un chip di ruolo o ne ha digitato uno, e `dismissed: true` quando ha chiuso il selettore. Un oggetto vuoto significa che l'utente ha approvato la chiamata senza scegliere un ruolo.
4649
4650<h3 id="mcpoutput">
4651 McpOutput
4652</h3>
4653
4654**Nome del tool:** nomi di tool MCP dinamici della forma `mcp__<server>__<tool>`
4655
4656```typescript theme={null}
4657type McpOutput =
4658 | string
4659 | {
4660 type: string;
4661 [k: string]: unknown;
4662 }[]
4663 | {
4664 [k: string]: unknown;
4665 };
4666```
4667
4668I risultati degli strumenti MCP vengono restituiti come stringa o come array di blocchi di contenuto, a seconda del server. Il ramo di oggetto semplice finale nel tipo esportato è un artefatto della generazione dello schema: l'SDK non restituisce un oggetto nudo, perché l'output strutturato di un server viene serializzato in una stringa JSON prima di essere restituito. Al runtime il valore può anche essere `undefined`, sebbene il tipo esportato non modelli questo.
4669
3090<h2 id="permission-types">4670<h2 id="permission-types">
3091 Tipi di permesso4671 Tipi di permesso
3092</h2>4672</h2>
3174 `ApiKeySource`4754 `ApiKeySource`
3175</h3>4755</h3>
3176 4756
4757Da dove proviene la chiave API per le richieste della sessione, segnalata come `apiKeySource` nel messaggio di inizializzazione [`SDKSystemMessage`](#sdksystemmessage).
4758
3177```typescript theme={null}4759```typescript theme={null}
3178type ApiKeySource = "user" | "project" | "org" | "temporary" | "oauth";4760type ApiKeySource =
4761 | "ANTHROPIC_API_KEY"
4762 | "apiKeyHelper"
4763 | "/login managed key"
4764 | "none"
4765 | "user"
4766 | "project"
4767 | "org"
4768 | "temporary"
4769 | "oauth";
3179```4770```
3180 4771
4772Claude Code segnala uno di quattro valori:
4773
4774| Valore | Chiave in uso |
4775| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
4776| `ANTHROPIC_API_KEY` | La chiave nella variabile di ambiente `ANTHROPIC_API_KEY` |
4777| `apiKeyHelper` | La chiave restituita dal tuo comando [`apiKeyHelper`](/docs/it/settings-reference#apikeyhelper) |
4778| `/login managed key` | La chiave che Claude Code ha memorizzato quando hai effettuato l'accesso con un [account Claude Console](/docs/it/authentication#claude-console-authentication) |
4779| `none` | Nessuna chiave API. La sessione si autentica in un altro modo, ad esempio un accesso a claude.ai, un token bearer, o un provider cloud |
4780
4781Agent SDK v0.3.234 e versioni successive elencano questi quattro valori nel tipo. Il tipo mantiene anche `user`, `project`, `org`, `temporary` e `oauth` affinché il codice più vecchio continui a compilarsi, e Claude Code non li segnala.
4782
3181<h3 id="sdkbeta">4783<h3 id="sdkbeta">
3182 `SdkBeta`4784 `SdkBeta`
3183</h3>4785</h3>
3184 4786
3185Funzioni beta disponibili che possono essere abilitate tramite l'opzione `betas`. Vedi [Intestazioni beta](https://platform.claude.com/docs/it/api/beta-headers) per ulteriori informazioni.4787Funzioni beta disponibili che possono essere abilitate tramite l'opzione `betas`. Vedi [Intestazioni beta](https://platform.claude.com/docs/en/api/beta-headers) per ulteriori informazioni.
3186 4788
3187```typescript theme={null}4789```typescript theme={null}
3188type SdkBeta = "context-1m-2025-08-07";4790type SdkBeta = "context-1m-2025-08-07";
3189```4791```
3190 4792
3191<Warning>4793<Warning>
3192 La beta `context-1m-2025-08-07` è ritirata a partire dal 30 aprile 2026. Passare questo valore con Claude Sonnet 4.5 o Sonnet 4 non ha effetto, e le richieste che superano la finestra di contesto standard di 200k token restituiscono un errore. Per usare una finestra di contesto di 1M token, esegui la migrazione a [Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.6, Claude Opus 4.7, o Claude Opus 4.8](https://platform.claude.com/docs/it/about-claude/models/overview), che includono 1M di contesto ai prezzi standard senza intestazione beta richiesta.4794 La beta `context-1m-2025-08-07` è ritirata a partire dal 30 aprile 2026. Passare questo valore con Claude Sonnet 4.5 o Sonnet 4 non ha effetto, e le richieste che superano la finestra di contesto standard di 200k token restituiscono un errore. Per usare una finestra di contesto di 1M token, esegui la migrazione a [Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.6, Claude Opus 4.7, o Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview), che includono 1M di contesto ai prezzi standard senza intestazione beta richiesta.
3193</Warning>4795</Warning>
3194 4796
3195<h3 id="slashcommand">4797<h3 id="slashcommand">
3196 `SlashCommand`4798 `SlashCommand`
3197</h3>4799</h3>
3198 4800
3199Informazioni su un comando slash disponibile.4801Informazioni su un comando disponibile.
3200 4802
3201```typescript theme={null}4803```typescript theme={null}
3202type SlashCommand = {4804type SlashCommand = {
3254```4856```
3255 4857
3256| Campo | Tipo | Descrizione |4858| Campo | Tipo | Descrizione |
3257| :------------ | :-------------------- | :---------------------------------------------------------------------------------- |4859| :------------ | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3258| `name` | `string` | Identificatore del tipo di agente (ad esempio, `"Explore"`, `"general-purpose"`) |4860| `name` | `string` | Identificatore del tipo di agente (ad esempio, `"Explore"`, `"general-purpose"`) |
3259| `description` | `string` | Descrizione di quando usare questo agente |4861| `description` | `string` | Descrizione di quando usare questo agente |
3260| `model` | `string \| undefined` | Alias del modello che questo agente usa. Se omesso, eredita il modello del genitore |4862| `model` | `string \| undefined` | Modello che questo agente usa: un alias o un ID di modello, o `'inherit'` per il modello del genitore. Quando è `undefined`, Claude Code sceglie il modello nell'[ordine del modello del subagente](/docs/it/sub-agents#choose-a-model) |
3261 4863
3262<h3 id="mcpserverstatus">4864<h3 id="mcpserverstatus">
3263 `McpServerStatus`4865 `McpServerStatus`
3331type ModelUsage = {4933type ModelUsage = {
3332 inputTokens: number;4934 inputTokens: number;
3333 outputTokens: number;4935 outputTokens: number;
4936 thinkingTokens?: number;
3334 cacheReadInputTokens: number;4937 cacheReadInputTokens: number;
3335 cacheCreationInputTokens: number;4938 cacheCreationInputTokens: number;
3336 webSearchRequests: number;4939 webSearchRequests: number;
3337 costUSD: number;4940 costUSD: number;
3338 contextWindow: number;4941 contextWindow: number;
3339 maxOutputTokens: number;4942 maxOutputTokens: number;
4943 canonicalModel?: string;
4944 provider?: string;
4945 costBasis?: 'list' | 'managed' | 'unknown';
3340};4946};
3341```4947```
3342 4948
4949`thinkingTokens` conta i token di pensiero che questo modello ha generato. `outputTokens` li include già, quindi non sommare i due insieme. Il campo è assente fino a quando un turno non viene eseguito su una versione di Claude Code che lo registra, quindi una sessione ripresa che è iniziata su una versione precedente segnala un conteggio parziale. `thinkingTokens` richiede Agent SDK v0.3.257 o successivo.
4950
4951I campi `canonicalModel` e `provider` richiedono Claude Code v2.1.218 o successivo. `canonicalModel` è l'ID del modello canonico che la ricerca dei prezzi utilizza; può differire dalla stringa del modello grezzo che chiave la voce, ad esempio quando quella stringa è un ID specifico del provider o un alias.
4952
4953`provider` nomina il backend API che ha servito il modello, come `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle`, o `gateway`.
4954
4955`costBasis` nomina la tabella dei prezzi che ha prezzato la richiesta più recente del modello: `list` per il prezzo di listino, `managed` per una tabella [`modelPricing`](/docs/it/settings-reference#modelpricing), o `unknown` quando nessuno dei due ha corrisposto all'ID del modello. Il campo richiede Claude Code v2.1.246 o successivo.
4956
3343<h3 id="configscope">4957<h3 id="configscope">
3344 `ConfigScope`4958 `ConfigScope`
3345</h3>4959</h3>
3381 speed: "standard" | "fast" | null;4995 speed: "standard" | "fast" | null;
3382 inference_geo: string | null;4996 inference_geo: string | null;
3383 iterations: BetaIterationsUsage | null;4997 iterations: BetaIterationsUsage | null;
4998 output_tokens_details: BetaOutputTokensDetails | null;
3384};4999};
3385```5000```
3386 5001
3387`BetaServerToolUsage` e `BetaIterationsUsage` sono definiti in `@anthropic-ai/sdk`.5002`BetaServerToolUsage`, `BetaIterationsUsage` e `BetaOutputTokensDetails` sono definiti in `@anthropic-ai/sdk`.
5003
5004`output_tokens_details` suddivide l'output fatturato per categoria. Attualmente contiene un campo, `thinking_tokens: number`, che conta i token di output che il modello ha generato come ragionamento interno, inclusi i delimitatori del blocco di pensiero. Il campo `output_tokens_details` richiede TypeScript SDK v0.3.228 o successivo, che raggruppa Claude Code v2.1.228.
5005
5006* **Fatturazione**: leggi la suddivisione per l'osservabilità, non per la fatturazione. `output_tokens` rimane il totale autorevole, e `output_tokens - thinking_tokens` approssima l'output non di ragionamento.
5007* **Cosa conta il conteggio**: il ragionamento grezzo che il modello ha prodotto, che può essere più lungo del testo di pensiero restituito nel corpo della risposta. L'API lo calcola ritokenizzando quel testo grezzo, quindi può differire dal conteggio esatto della generazione del modello di alcuni token.
5008* **Streaming**: sui messaggi dell'assistente trasmessi questa suddivisione, come `output_tokens`, è un placeholder `message_start` e non contiene un conteggio reale, quindi leggilo dal messaggio di risultato `usage` come [Leggi i token di output dal messaggio di risultato](/docs/it/agent-sdk/cost-tracking#read-output-tokens-from-the-result-message) descrive. Nel messaggio di risultato, `thinking_tokens` legge `0` quando il modello o il provider non segnala alcuna suddivisione.
5009* **Casi `null`**: `output_tokens_details` stesso è `null` sui messaggi dell'assistente che Claude Code sintetizza, come i messaggi di errore API.
3388 5010
3389<h3 id="calltoolresult">5011<h3 id="calltoolresult">
3390 `CallToolResult`5012 `CallToolResult`
3403};5025};
3404```5026```
3405 5027
5028<h3 id="sdkmcpresourcelink">
5029 `SDKMcpResourceLink`
5030</h3>
5031
5032Un file che un tool MCP ha restituito per riferimento. Claude Code costruisce ogni voce da un blocco `resource_link` nel risultato del tool e fornisce l'elenco come `resourceLinks` su [`SDKUserMessage.tool_use_result`](#sdkusermessage), o come `resource_links` su [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) quando la chiamata è terminata in background. Richiede Agent SDK v0.3.257 o successivo.
5033
5034```typescript theme={null}
5035type SDKMcpResourceLink = {
5036 uri: string;
5037 name: string;
5038 title?: string;
5039 description?: string;
5040 mimeType?: string;
5041 size?: number;
5042 annotations?: Record<string, unknown>;
5043};
5044```
5045
5046Claude Code scarta un blocco il cui `uri` o `name` non è una stringa, e omette un campo opzionale il cui valore non è del tipo elencato.
5047
5048| Campo | Tipo | Descrizione |
5049| :------------ | :------------------------------------- | :------------------------------------------------------------------------- |
5050| `uri` | `string` | URI della risorsa, come il server l'ha restituito |
5051| `name` | `string` | Nome che il server ha dato alla risorsa |
5052| `title` | `string \| undefined` | Titolo di visualizzazione, quando il server ne ha impostato uno |
5053| `description` | `string \| undefined` | Descrizione, quando il server ne ha impostato una |
5054| `mimeType` | `string \| undefined` | Tipo MIME, quando il server ne ha impostato uno |
5055| `size` | `number \| undefined` | Dimensione in byte, quando il server ne ha impostato una |
5056| `annotations` | `Record<string, unknown> \| undefined` | L'oggetto annotazioni MCP del blocco, quando il server ne ha impostato uno |
5057
3406<h3 id="thinkingconfig">5058<h3 id="thinkingconfig">
3407 `ThinkingConfig`5059 `ThinkingConfig`
3408</h3>5060</h3>
3418 | { type: "disabled" }; // Nessun pensiero esteso5070 | { type: "disabled" }; // Nessun pensiero esteso
3419```5071```
3420 5072
3421Il campo opzionale `display` controlla se il testo di pensiero viene restituito `"summarized"` o `"omitted"`. Su Claude Opus 4.7 e versioni successive, l'impostazione predefinita dell'API è `"omitted"`, quindi imposta `"summarized"` per ricevere il contenuto di pensiero nei blocchi `thinking`.5073Il campo opzionale `display` controlla se il testo di pensiero viene restituito `"summarized"` o `"omitted"`. Su Claude Opus 4.7 e versioni successive, l'impostazione predefinita dell'API è `"omitted"`, quindi imposta `"summarized"` per ricevere il contenuto di pensiero nei blocchi `thinking`. Claude Code non invia `display` ad Amazon Bedrock o alla piattaforma Agent di Google Cloud, quindi su quei provider Opus 4.7 e versioni successive restituiscono blocchi `thinking` vuoti anche quando imposti `display` su `"summarized"`.
3422 5074
3423<h3 id="spawnedprocess">5075<h3 id="spawnedprocess">
3424 `SpawnedProcess`5076 `SpawnedProcess`
3487};5139};
3488```5140```
3489 5141
5142Quando chiami `setMcpServers()`, Claude Code applica queste regole:
5143
5144* **Server che la chiamata non nomina**: Claude Code mantiene i server forniti dai plugin in esecuzione. Richiede Agent SDK v0.3.210 o successivo.
5145* **Server che la chiamata nomina**: ad eccezione dei server integrati che la CLI ha avviato all'avvio, Claude Code sostituisce un server in esecuzione solo quando la sua configurazione differisce da quella che hai passato.
5146* **Server integrati che la CLI ha avviato all'avvio**: se la chiamata ne nomina uno, Claude Code scarta quella voce e la segnala in `errors`.
5147
5148La promessa si risolve dopo che i server stdio, HTTP e SSE appena aggiunti si connettono o falliscono, quindi i tool dai server che si sono connessi sono disponibili al turno successivo.
5149
5150`added` elenca i server che Claude Code ha aggiunto o sostituito, indipendentemente dal fatto che si siano connessi. Un server che non si è connesso appare sia in `added` che in `errors`, con il testo di errore sotto `errors` e una riga `failed` in [`mcpServerStatus()`](#methods). Prima di Claude Code v2.1.257, un server il cui tentativo di connessione ha lanciato un'eccezione era segnalato solo sotto `errors`.
5151
3490<h3 id="rewindfilesresult">5152<h3 id="rewindfilesresult">
3491 `RewindFilesResult`5153 `RewindFilesResult`
3492</h3>5154</h3>
3500 filesChanged?: string[];5162 filesChanged?: string[];
3501 insertions?: number;5163 insertions?: number;
3502 deletions?: number;5164 deletions?: number;
5165 skippedLinks?: number;
3503};5166};
3504```5167```
3505 5168
5169`skippedLinks` conta i percorsi tracciati che il rewind ha rifiutato di ripristinare o eliminare per la sicurezza dei link: un symlink, hard link, o altro file non regolare nel percorso tracciato, una directory padre che non si risolve più a dove puntava quando il checkpoint è stato preso, o un backup che non poteva essere letto in sicurezza. Il campo richiede Claude Code v2.1.216 o successivo. Una chiamata di anteprima con `rewindFiles(userMessageId, { dryRun: true })` non lo imposta mai.
5170
3506<h3 id="sdkstatusmessage">5171<h3 id="sdkstatusmessage">
3507 `SDKStatusMessage`5172 `SDKStatusMessage`
3508</h3>5173</h3>
3524 `SDKTaskNotificationMessage`5189 `SDKTaskNotificationMessage`
3525</h3>5190</h3>
3526 5191
3527Notifica quando un'attività di background si completa, fallisce o viene interrotta. Le attività di background includono i comandi Bash `run_in_background`, i watch [Monitor](#monitor) e i subagenti di background.5192Notifica quando un'attività di background si completa, fallisce o viene interrotta. Le attività di background includono i comandi Bash `run_in_background`, i watch [Monitor](#monitor) e i subagenti di background. Per il campo `ambient`, vedi [`SDKTaskStartedMessage`](#sdktaskstartedmessage), che lo definisce e il suo requisito di versione.
3528 5193
3529```typescript theme={null}5194```typescript theme={null}
3530type SDKTaskNotificationMessage = {5195type SDKTaskNotificationMessage = {
3535 status: "completed" | "failed" | "stopped";5200 status: "completed" | "failed" | "stopped";
3536 output_file: string;5201 output_file: string;
3537 summary: string;5202 summary: string;
5203 ambient?: boolean;
3538 usage?: {5204 usage?: {
3539 total_tokens: number;5205 total_tokens: number;
3540 tool_uses: number;5206 tool_uses: number;
3541 duration_ms: number;5207 duration_ms: number;
3542 };5208 };
5209 resource_links?: SDKMcpResourceLink[];
3543 uuid: UUID;5210 uuid: UUID;
3544 session_id: string;5211 session_id: string;
3545};5212};
3546```5213```
3547 5214
5215Quando Claude Code [sposta una lunga chiamata al tool MCP in background](/docs/it/mcp#automatic-backgrounding-of-long-tool-calls), il blocco `tool_result` per quella chiamata contiene solo un placeholder e il risultato reale della chiamata arriva in questa notifica. Abbina la notifica alla chiamata con `tool_use_id`. Su una notifica `completed`, `resource_links` elenca i file che il tool ha restituito per riferimento come voci [`SDKMcpResourceLink`](#sdkmcpresourcelink), con gli stessi limiti di 50 link e 64 KiB di [`tool_use_result.resourceLinks`](#sdkusermessage). Claude Code omette `resource_links` quando il risultato non aveva link e sulle notifiche per attività che non sono chiamate al tool MCP. `resource_links` richiede Agent SDK v0.3.257 o successivo.
5216
5217Claude Code antepone un avviso a ogni notifica di attività che invia al modello, ad eccezione delle consegne contrassegnate con il sottotipo [`scheduled-trigger`](#task-notification-subkinds), che portano invece un inquadramento di attività assegnata. L'avviso afferma che non si è verificato alcun input umano, quindi il modello non tratta la notifica come un'istruzione o un'approvazione dell'utente.
5218
5219Per rilevare un turno di notifica di attività, controlla `origin.kind === "task-notification"` su [`SDKUserMessage`](#sdkusermessage) o [`SDKResultMessage`](#sdkresultmessage) piuttosto che abbinare il testo dell'avviso. Leggi `subkind` dallo stesso campo se hai bisogno di sapere cosa l'ha sollevato. Prima di v2.1.205, Claude Code ometteva l'avviso dalle notifiche che arrivavano mentre la sessione era inattiva.
5220
3548<h3 id="sdktoolusesummarymessage">5221<h3 id="sdktoolusesummarymessage">
3549 `SDKToolUseSummaryMessage`5222 `SDKToolUseSummaryMessage`
3550</h3>5223</h3>
3639 parent_tool_use_id: string | null;5312 parent_tool_use_id: string | null;
3640 elapsed_time_seconds: number;5313 elapsed_time_seconds: number;
3641 task_id?: string;5314 task_id?: string;
5315 heartbeat?: boolean;
5316 subagent_type?: string;
5317 subagent_retry?: {
5318 agent_id: string;
5319 attempt: number;
5320 max_retries: number;
5321 retry_delay_ms: number;
5322 error_status: number | null;
5323 error_category: string;
5324 };
3642 uuid: UUID;5325 uuid: UUID;
3643 session_id: string;5326 session_id: string;
3644};5327};
3645```5328```
3646 5329
5330Mentre una chiamata al tool viene eseguita nella conversazione principale, Claude Code emette un messaggio `tool_progress` ogni 30 secondi con `heartbeat: true`. Ogni heartbeat contiene il nome del tool e i secondi trascorsi, quindi puoi distinguere una chiamata di lunga durata da una sessione bloccata. Claude Code non emette heartbeat per le chiamate al tool all'interno di un subagente. Il campo `heartbeat` richiede Agent SDK v0.3.214 o successivo. Prima di v2.1.257, Claude Code non emetteva heartbeat nemmeno per una chiamata al tool Agent in primo piano.
5331
5332Sui messaggi `tool_progress` per il tool Agent diversi dagli heartbeat, `subagent_type` nomina il tipo di subagente in esecuzione, come `general-purpose`. `subagent_retry` è presente mentre quel subagente attende un backoff di errore API, come un limite di velocità o un sovraccarico, con un messaggio per tentativo di ripetizione. Entrambi i campi richiedono Agent SDK v0.3.214 o successivo.
5333
5334Per rendere un indicatore di ripetizione da `subagent_retry`:
5335
5336* Traccia l'indicatore per `parent_tool_use_id`, che è univoco per subagente. `tool_use_id` è condiviso da subagenti paralleli da un turno dell'assistente, quindi tracciare per esso lascerebbe che l'aggiornamento di un subagente cancelli l'indicatore di un altro.
5337* Cancella l'indicatore quando un successivo `tool_progress` per lo stesso `parent_tool_use_id` arriva senza `subagent_retry` né `heartbeat: true`, o quando arriva il messaggio di risultato del tool. I frame con `heartbeat: true` segnalano solo vivacità, quindi mantieni l'indicatore quando uno arriva. `attempt` può superare `max_retries` sotto ripetizione persistente, quindi non derivare la cancellazione dai contatori.
5338* Tratta `error_category` come un token per scegliere il tuo testo di messaggio, non come testo di visualizzazione. I valori sono `rate_limit`, `overloaded`, `authentication_failed`, `server_error`, `cloud_credential_error` e `unknown`. Gestisci un valore che non riconosci come gestisci `unknown`, perché le versioni successive possono aggiungere valori.
5339
3647<h3 id="sdkauthstatusmessage">5340<h3 id="sdkauthstatusmessage">
3648 `SDKAuthStatusMessage`5341 `SDKAuthStatusMessage`
3649</h3>5342</h3>
3665 `SDKTaskStartedMessage`5358 `SDKTaskStartedMessage`
3666</h3>5359</h3>
3667 5360
3668Emesso quando un'attività di background inizia. Il campo `task_type` è `"local_bash"` per i comandi Bash di background e i watch [Monitor](#monitor), `"local_agent"` per i subagenti, o `"remote_agent"`.5361Emesso quando un'attività inizia. Il campo `task_type` è `"local_bash"` per i comandi Bash e i watch [Monitor](#monitor), `"local_agent"` per i subagenti, o `"remote_agent"`.
3669 5362
3670```typescript theme={null}5363```typescript theme={null}
3671type SDKTaskStartedMessage = {5364type SDKTaskStartedMessage = {
3675 tool_use_id?: string;5368 tool_use_id?: string;
3676 description: string;5369 description: string;
3677 task_type?: string;5370 task_type?: string;
5371 is_backgrounded?: boolean;
5372 spawn_depth?: number;
5373 ambient?: boolean;
3678 uuid: UUID;5374 uuid: UUID;
3679 session_id: string;5375 session_id: string;
3680};5376};
3681```5377```
3682 5378
5379`ambient` è `true` per le attività che non fanno parte del lavoro della sessione, come le attività che Claude Code esegue per la sua stessa operazione. I watcher di aggiornamento dal vivo sono anche ambient, inclusi i watcher che l'utente ha chiesto. Escludi le attività ambient dagli indicatori di attività. Il campo richiede Agent SDK v0.3.247 o successivo.
5380
5381`ambient` appare anche su [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) e su voci [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage).
5382
5383`is_backgrounded` e `spawn_depth` descrivono come Claude Code ha avviato l'attività. Entrambi i campi richiedono Agent SDK v0.3.238 o successivo.
5384
5385* `is_backgrounded`: Claude Code lo imposta su attività `"local_agent"` e `"local_bash"`. `true` significa che l'attività viene eseguita in background. `false` significa che l'attività viene eseguita in primo piano, e la chiamata al tool che l'ha avviata rimane bloccata fino a quando l'attività non finisce o si sposta in background.
5386* `spawn_depth`: Claude Code lo imposta solo su attività `"local_agent"`. Un subagente che il thread principale ha generato ha profondità `1`. Un subagente che un subagente di profondità `1` ha generato ha profondità `2`, e così via.
5387
5388Un [subagente ripreso](/docs/it/agent-sdk/subagents#resume-subagents) segnala sempre `is_backgrounded: true`, perché Claude Code esegue ogni subagente ripreso in background. Quando un'attività in primo piano si sposta in background in seguito, Claude Code segnala il nuovo valore `is_backgrounded` in un messaggio [`task_updated`](#sdktaskupdatedmessage) piuttosto che inviare un secondo `task_started`.
5389
3683<h3 id="sdktaskprogressmessage">5390<h3 id="sdktaskprogressmessage">
3684 `SDKTaskProgressMessage`5391 `SDKTaskProgressMessage`
3685</h3>5392</h3>
3734 `SDKBackgroundTasksChangedMessage`5441 `SDKBackgroundTasksChangedMessage`
3735</h3>5442</h3>
3736 5443
3737Emesso ogni volta che l'insieme delle attività di background attive cambia: un'attività inizia, si completa, viene terminata, o un agente in primo piano viene messo in background. L'array `tasks` è l'insieme completo attivo. Sostituisci qualsiasi insieme memorizzato nella cache con ogni payload invece di abbinare gli eventi `task_started` e `task_notification`, in modo che il prossimo cambio di appartenenza corregga qualsiasi evento che hai perso.5444Emesso ogni volta che l'insieme delle attività di background attive cambia: un'attività inizia, si completa, viene terminata, un agente in primo piano viene messo in background, o il campo `description` o `ambient` di un'attività cambia.
5445
5446L'array `tasks` è l'insieme completo attivo. Sostituisci qualsiasi insieme memorizzato nella cache con ogni payload invece di abbinare gli eventi `task_started` e `task_notification`, in modo che il prossimo cambio di appartenenza corregga qualsiasi evento che hai perso.
3738 5447
3739L'ordine relativo a quegli eventi per attività è non specificato, quindi non correlare i due flussi.5448L'ordine relativo a quegli eventi per attività è non specificato, quindi non correlare i due flussi.
3740 5449
3741Nulla viene emesso all'avvio. Reimposta a un insieme vuoto ogni volta che il processo CLI della sessione inizia o si riavvia e lascia che il prossimo cambio di appartenenza lo ripopoli.5450Nulla viene emesso all'avvio. Reimposta a un insieme vuoto ogni volta che il processo CLI della sessione inizia o si riavvia e lascia che il prossimo cambio di appartenenza lo ripopoli.
3742 5451
5452Quando invii una richiesta di controllo `initialize` ripetuta a una sessione in esecuzione, ad esempio con [`reinitialize()`](#query-object) dopo un gap di trasporto, Claude Code segue la risposta con uno snapshot dell'insieme attivo corrente, anche quando è vuoto. Un host che si ricollega quindi apprende cosa è in esecuzione senza aspettare il prossimo cambio di appartenenza. Prima di Agent SDK v0.3.239, Claude Code non inviava snapshot dopo un `initialize` ripetuto.
5453
3743Richiede Claude Code v2.1.203 o successivo.5454Richiede Claude Code v2.1.203 o successivo.
3744 5455
3745```typescript theme={null}5456```typescript theme={null}
3750 task_id: string;5461 task_id: string;
3751 task_type: string;5462 task_type: string;
3752 description: string;5463 description: string;
5464 ambient?: boolean;
3753 }[];5465 }[];
3754 uuid: UUID;5466 uuid: UUID;
3755 session_id: string;5467 session_id: string;
3760 `SDKThinkingTokensMessage`5472 `SDKThinkingTokensMessage`
3761</h3>5473</h3>
3762 5474
3763Emesso mentre Claude sta producendo un blocco di pensiero, incluso uno redatto, con una stima in esecuzione dei token di pensiero generati finora. `estimated_tokens` è il totale in esecuzione per il blocco di pensiero corrente e `estimated_tokens_delta` è l'incremento portato da questo frame. Usalo per la visualizzazione del progresso. Il conteggio finale per il ciclo dell'agente di primo livello è il `usage.output_tokens` del messaggio di risultato, che [non include i token dei subagenti](/docs/it/agent-sdk/cost-tracking#get-the-total-cost-of-a-query); usa [`modelUsage`](#modelusage) per la contabilità dell'intero albero.5475Emesso mentre Claude sta producendo un blocco di pensiero, incluso uno redatto. `estimated_tokens` è una stima in esecuzione dei token di pensiero generati finora nel blocco corrente, e `estimated_tokens_delta` è l'incremento portato da questo frame. Usa queste stime per la visualizzazione del progresso.
5476
5477Quando il modello o il provider segnala una suddivisione, il conteggio finale per il ciclo dell'agente di primo livello è il [`usage.output_tokens_details.thinking_tokens`](#usage) del messaggio di risultato, che [non include i token dei subagenti](/docs/it/agent-sdk/cost-tracking#get-the-total-cost-of-a-query).
3764 5478
3765Richiede Claude Code v2.1.153 o successivo.5479Richiede Claude Code v2.1.153 o successivo.
3766 5480
3770 subtype: "thinking_tokens";5484 subtype: "thinking_tokens";
3771 estimated_tokens: number;5485 estimated_tokens: number;
3772 estimated_tokens_delta: number;5486 estimated_tokens_delta: number;
5487 user_message_uuid?: string;
3773 uuid: UUID;5488 uuid: UUID;
3774 session_id: string;5489 session_id: string;
3775};5490};
3821 `SDKLocalCommandOutputMessage`5536 `SDKLocalCommandOutputMessage`
3822</h3>5537</h3>
3823 5538
3824Output da un comando slash locale (ad esempio, `/voice` o `/usage`). Visualizzato come testo in stile assistente nella trascrizione.5539Claude Code non emette questo tipo di messaggio. Quando invii un comando come `/context` o `/usage` come prompt, il suo output arriva come [`SDKAssistantMessage`](#sdkassistantmessage).
3825 5540
3826```typescript theme={null}5541```typescript theme={null}
3827type SDKLocalCommandOutputMessage = {5542type SDKLocalCommandOutputMessage = {
3837 `SDKCommandsChangedMessage`5552 `SDKCommandsChangedMessage`
3838</h3>5553</h3>
3839 5554
3840Emesso quando l'insieme dei comandi disponibili cambia durante la sessione, ad esempio quando le skill vengono scoperte mentre l'agente entra in una sottodirectory. L'array `commands` è l'elenco completo aggiornato, quindi sostituisci qualsiasi elenco di comandi memorizzato nella cache con questo payload. Chiamare di nuovo `supportedCommands()` non è equivalente: quel metodo restituisce lo snapshot acquisito all'inizializzazione e non riflette i cambiamenti durante la sessione.5555Emesso quando l'insieme dei comandi disponibili cambia durante la sessione, ad esempio quando Claude Code scopre skill mentre l'agente entra in una sottodirectory. L'array `commands` è l'elenco completo aggiornato, quindi sostituisci qualsiasi elenco di comandi memorizzato nella cache con questo payload. Chiamare [`supportedCommands()`](#query-object) dopo questo messaggio restituisce lo stesso elenco aggiornato, perché il metodo traccia l'ultimo push; questo richiede Agent SDK v0.3.216 o successivo. Nelle versioni SDK precedenti, `supportedCommands()` restituisce lo snapshot acquisito all'inizializzazione e non riflette mai i cambiamenti durante la sessione.
3841 5556
3842```typescript theme={null}5557```typescript theme={null}
3843type SDKCommandsChangedMessage = {5558type SDKCommandsChangedMessage = {
3853 `SDKPromptSuggestionMessage`5568 `SDKPromptSuggestionMessage`
3854</h3>5569</h3>
3855 5570
3856Emesso dopo ogni turno quando `promptSuggestions` è abilitato. Contiene un prompt utente successivo previsto.5571Emesso dopo un turno quando [`promptSuggestions`](#options) è abilitato e Claude Code ha generato un suggerimento per quel turno. Contiene il prompt utente successivo previsto. Per i turni che non ne ricevono, vedi [Quando Claude Code salta i suggerimenti](/docs/it/interactive-mode#when-claude-code-skips-suggestions).
3857 5572
3858```typescript theme={null}5573```typescript theme={null}
3859type SDKPromptSuggestionMessage = {5574type SDKPromptSuggestionMessage = {
3868 `SDKConversationResetMessage`5583 `SDKConversationResetMessage`
3869</h3>5584</h3>
3870 5585
3871Emesso quando la conversazione della sessione viene sostituita senza terminare la sessione, ad esempio dopo `/clear`, all'uscita dalla modalità piano, o quando inizia una conversazione nuova. Monta una trascrizione vuota sotto `new_conversation_id` e scarta qualsiasi titolo di sessione memorizzato nella cache.5586Emesso quando la conversazione della sessione viene sostituita senza terminare la sessione. In una chiamata `query()`, solo `/clear` e i suoi alias producono questo messaggio. Monta una trascrizione vuota sotto `new_conversation_id` e scarta qualsiasi titolo di sessione memorizzato nella cache.
3872 5587
3873```typescript theme={null}5588```typescript theme={null}
3874type SDKConversationResetMessage = {5589type SDKConversationResetMessage = {
3891class AbortError extends Error {}5606class AbortError extends Error {}
3892```5607```
3893 5608
5609`AbortError` è l'unica classe di errore nell'API tipizzata dell'SDK. Altri errori, come il processo Claude Code che esce o non riesce ad avviarsi, rifiutano l'iterazione del messaggio con errori che non portano alcuna classe SDK su cui abbinare. [Troubleshooting](/docs/it/agent-sdk/troubleshooting) chiave quegli errori per messaggio, con la causa e la correzione per ciascuno.
5610
3894<h2 id="sandbox-configuration">5611<h2 id="sandbox-configuration">
3895 Configurazione della sandbox5612 Configurazione della sandbox
3896</h2>5613</h2>
3925| `allowUnsandboxedCommands` | `boolean` | `true` | Consenti al modello di richiedere l'esecuzione di comandi al di fuori della sandbox. Quando `true`, il modello può impostare `dangerouslyDisableSandbox` nell'input del tool, che ricade nel [sistema di permessi](#permissions-fallback-for-unsandboxed-commands) |5642| `allowUnsandboxedCommands` | `boolean` | `true` | Consenti al modello di richiedere l'esecuzione di comandi al di fuori della sandbox. Quando `true`, il modello può impostare `dangerouslyDisableSandbox` nell'input del tool, che ricade nel [sistema di permessi](#permissions-fallback-for-unsandboxed-commands) |
3926| `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `undefined` | Configurazione della sandbox specifica della rete |5643| `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `undefined` | Configurazione della sandbox specifica della rete |
3927| `filesystem` | [`SandboxFilesystemConfig`](#sandboxfilesystemconfig) | `undefined` | Configurazione della sandbox specifica del filesystem per le restrizioni di lettura/scrittura |5644| `filesystem` | [`SandboxFilesystemConfig`](#sandboxfilesystemconfig) | `undefined` | Configurazione della sandbox specifica del filesystem per le restrizioni di lettura/scrittura |
3928| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Mappa delle categorie di violazione ai pattern da ignorare (ad esempio, `{ file: ['/tmp/*'], network: ['localhost'] }`) |5645| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Mappa delle sottostringhe di comando, o `*` per ogni comando, alle sottostringhe del testo di violazione da ignorare, come `{ "*": ['/etc/hosts'] }`; vedi [`sandbox.ignoreViolations`](/docs/it/settings-reference#sandbox-ignoreviolations) |
3929| `enableWeakerNestedSandbox` | `boolean` | `false` | Abilita una sandbox nidificata più debole per la compatibilità |5646| `enableWeakerNestedSandbox` | `boolean` | `false` | Abilita una sandbox nidificata più debole per la compatibilità |
3930| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Configurazione del binario ripgrep personalizzato per gli ambienti sandbox |5647| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Configurazione del binario ripgrep personalizzato per gli ambienti sandbox |
3931 5648
3965```5682```
3966 5683
3967<Warning>5684<Warning>
3968 **Sicurezza del socket Unix:** L'opzione `allowUnixSockets` può concedere l'accesso a potenti servizi di sistema. Ad esempio, consentire `/var/run/docker.sock` concede effettivamente l'accesso completo al sistema host tramite l'API Docker, bypassando l'isolamento della sandbox. Consenti solo i socket Unix strettamente necessari e comprendi le implicazioni di sicurezza di ciascuno.5685 **Sicurezza del socket Unix:** L'opzione `allowUnixSockets` può concedere l'accesso a servizi di sistema che raggiungono al di fuori della sandbox. Ad esempio, consentire `/var/run/docker.sock` concede effettivamente l'accesso completo al sistema host tramite l'API Docker, bypassando l'isolamento della sandbox. Consenti solo i socket Unix strettamente necessari e comprendi le implicazioni di sicurezza di ciascuno.
3969</Warning>5686</Warning>
3970 5687
3971<h3 id="sandboxnetworkconfig">5688<h3 id="sandboxnetworkconfig">
3978type SandboxNetworkConfig = {5695type SandboxNetworkConfig = {
3979 allowedDomains?: string[];5696 allowedDomains?: string[];
3980 deniedDomains?: string[];5697 deniedDomains?: string[];
5698 strictAllowlist?: boolean;
3981 allowManagedDomainsOnly?: boolean;5699 allowManagedDomainsOnly?: boolean;
3982 allowLocalBinding?: boolean;5700 allowLocalBinding?: boolean;
3983 allowUnixSockets?: string[];5701 allowUnixSockets?: string[];
3988```5706```
3989 5707
3990| Proprietà | Tipo | Predefinito | Descrizione |5708| Proprietà | Tipo | Predefinito | Descrizione |
3991| :------------------------ | :--------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |5709| :------------------------ | :--------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
3992| `allowedDomains` | `string[]` | `[]` | Nomi di dominio a cui i processi in sandbox possono accedere |5710| `allowedDomains` | `string[]` | `[]` | Nomi di dominio a cui i processi in sandbox possono accedere |
3993| `deniedDomains` | `string[]` | `[]` | Nomi di dominio a cui i processi in sandbox non possono accedere. Ha la precedenza su `allowedDomains` |5711| `deniedDomains` | `string[]` | `[]` | Nomi di dominio a cui i processi in sandbox non possono accedere. Ha la precedenza su `allowedDomains` |
3994| `allowManagedDomainsOnly` | `boolean` | `false` | Solo impostazioni gestite. Quando impostato nelle [impostazioni gestite](/docs/it/permissions#managed-settings), solo le voci `allowedDomains` dalle impostazioni gestite vengono rispettate e le voci dalle impostazioni utente, progetto o locali vengono ignorate. Non ha effetto quando impostato tramite le opzioni SDK |5712| `strictAllowlist` | `boolean` | `false` | Nega ai comandi in sandbox l'accesso agli host al di fuori della [lista di autorizzazione della rete](/docs/it/sandboxing#network-isolation) invece di richiedere conferma. Applicato solo ai comandi in sandbox; i tool in-process come WebFetch non sono controllati da esso. Rispettato solo dalle impostazioni utente, gestite o CLI `--settings`; le impostazioni del progetto vengono ignorate. Richiede Claude Code v2.1.219 o successivo |
5713| `allowManagedDomainsOnly` | `boolean` | `false` | Solo impostazioni gestite. Quando impostato nelle [impostazioni gestite](/docs/it/managed-settings), 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. Non ha effetto quando impostato tramite le opzioni SDK |
3995| `allowLocalBinding` | `boolean` | `false` | Consenti ai processi di associarsi alle porte locali (ad esempio, per i server di sviluppo) |5714| `allowLocalBinding` | `boolean` | `false` | Consenti ai processi di associarsi alle porte locali (ad esempio, per i server di sviluppo) |
3996| `allowUnixSockets` | `string[]` | `[]` | Percorsi dei socket Unix a cui i processi possono accedere (ad esempio, socket Docker) |5715| `allowUnixSockets` | `string[]` | `[]` | Percorsi dei socket Unix a cui i processi possono accedere (ad esempio, socket Docker) |
3997| `allowAllUnixSockets` | `boolean` | `false` | Consenti l'accesso a tutti i socket Unix |5716| `allowAllUnixSockets` | `boolean` | `false` | Consenti l'accesso a tutti i socket Unix |
4026 Fallback dei permessi per i comandi senza sandbox5745 Fallback dei permessi per i comandi senza sandbox
4027</h3>5746</h3>
4028 5747
4029Quando `allowUnsandboxedCommands` è abilitato, il modello può richiedere di eseguire comandi al di fuori della sandbox impostando `dangerouslyDisableSandbox: true` nell'input del tool. Queste richieste ricadono nel sistema di permessi esistente, il che significa che il tuo handler `canUseTool` viene invocato, permettendoti di implementare la logica di autorizzazione personalizzata. Nell'esempio seguente, `isCommandAuthorized` rappresenta un controllo di autorizzazione che definisci.5748Quando `allowUnsandboxedCommands` è abilitato, il modello può richiedere di eseguire comandi al di fuori della sandbox impostando `dangerouslyDisableSandbox: true` nell'input del tool. Queste richieste ricadono nel sistema di permessi esistente, il che significa che il tuo handler `canUseTool` viene invocato, permettendoti di implementare la logica di autorizzazione personalizzata. I comandi elencati in `excludedCommands` invece bypassano la sandbox automaticamente, senza coinvolgimento del modello; vedi [`SandboxSettings`](#sandboxsettings).
4030
4031<Note>
4032 **`excludedCommands` vs `allowUnsandboxedCommands`:**
4033 5749
4034 * `excludedCommands`: Un elenco statico di comandi che sempre bypassano la sandbox automaticamente (ad esempio, `['docker']`). Il modello non ha controllo su questo.5750Nell'esempio seguente, `isCommandAuthorized` rappresenta un controllo di autorizzazione che definisci.
4035 * `allowUnsandboxedCommands`: Consenti al modello di decidere in fase di esecuzione se richiedere l'esecuzione senza sandbox impostando `dangerouslyDisableSandbox: true` nell'input del tool.
4036</Note>
4037 5751
4038```typescript theme={null}5752```typescript theme={null}
4039import { query } from "@anthropic-ai/claude-agent-sdk";5753import { query } from "@anthropic-ai/claude-agent-sdk";
4068}5782}
4069```5783```
4070 5784
4071Questo pattern ti consente di:
4072
4073* **Controllare le richieste del modello:** Registra quando il modello richiede l'esecuzione senza sandbox
4074* **Implementare allowlist:** Consenti solo comandi specifici di essere eseguiti senza sandbox
4075* **Aggiungere flussi di lavoro di approvazione:** Richiedi l'autorizzazione esplicita per le operazioni privilegiate
4076
4077<Warning>5785<Warning>
4078 I comandi in esecuzione con `dangerouslyDisableSandbox: true` hanno accesso completo al sistema. Assicurati che il tuo handler `canUseTool` convalidi queste richieste attentamente.5786 I comandi in esecuzione con `dangerouslyDisableSandbox: true` hanno accesso completo al sistema. Assicurati che il tuo handler `canUseTool` convalidi queste richieste attentamente.
4079 5787
4080 Se `permissionMode` è impostato su `bypassPermissions` e `allowUnsandboxedCommands` è abilitato, il modello può autonomamente eseguire comandi al di fuori della sandbox senza alcun prompt di approvazione (una [regola `ask`](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated) esplicita ne forza comunque una). Questa combinazione consente effettivamente al modello di sfuggire all'isolamento della sandbox silenziosamente.5788 Se `permissionMode` è impostato su `bypassPermissions` e `allowUnsandboxedCommands` è abilitato, il modello può autonomamente eseguire comandi al di fuori della sandbox senza prompt di approvazione, a parte le [azioni che nessuna modalità auto-approva](/docs/it/permission-modes#actions-no-mode-auto-approves). Questa combinazione consente effettivamente al modello di sfuggire all'isolamento della sandbox silenziosamente.
4081</Warning>5789</Warning>
4082 5790
4083<h2 id="see-also">5791<h2 id="see-also">
