44 Funzioni44 Funzioni
45</h2>45</h2>
46 46
47<Note>I blocchi di firma e i frammenti `async for` / `async with` nudi in questa pagina sono illustrativi. Per eseguirli, avvolgete il corpo in `async def main(): ...` e chiamate `asyncio.run(main())`.</Note>47<Note>I blocchi di firma e i frammenti `async for` / `async with` nudi in questa pagina sono illustrativi. Per eseguirli, avvolgi il corpo in `async def main(): ...` e chiama `asyncio.run(main())`.</Note>
48 48
49<h3 id="query">49<h3 id="query">
50 `query()`50 `query()`
51</h3>51</h3>
52 52
53Crea una nuova sessione per ogni interazione con Claude Code per impostazione predefinita. Restituisce un iteratore asincrono che produce messaggi man mano che arrivano. Ogni chiamata a `query()` inizia da zero senza memoria di interazioni precedenti a meno che non passiate `continue_conversation=True` o `resume` in [`ClaudeAgentOptions`](#claudeagentoptions). Vedi [Sessions](/docs/it/agent-sdk/sessions).53Crea una nuova sessione per ogni interazione con Claude Code per impostazione predefinita. Restituisce un iteratore asincrono che produce messaggi man mano che arrivano. Ogni chiamata a `query()` inizia da zero senza memoria di interazioni precedenti a meno che non passi `continue_conversation=True` o `resume` in [`ClaudeAgentOptions`](#claudeagentoptions). Vedi [Sessions](/docs/it/agent-sdk/sessions).
54 54
55```python theme={null}55```python theme={null}
56async def query(56async def query(
194 `ToolAnnotations`194 `ToolAnnotations`
195</h4>195</h4>
196 196
197Suggerimenti comportamentali per uno strumento, passati come argomento `annotations` di [`tool()`](#tool). `ToolAnnotations` estende `mcp.types.ToolAnnotations` dell'SDK MCP con un campo `maxResultSizeChars`, e potete scrivere ogni suggerimento in camelCase o snake\_case: `ToolAnnotations(readOnlyHint=True)` e `ToolAnnotations(read_only_hint=True)` sono equivalenti. Potete anche passare un semplice `mcp.types.ToolAnnotations` ovunque l'SDK accetti annotazioni.197Suggerimenti comportamentali per uno strumento, passati come argomento `annotations` di [`tool()`](#tool). `ToolAnnotations` estende `mcp.types.ToolAnnotations` dell'SDK MCP con un campo `maxResultSizeChars`, e puoi scrivere ogni suggerimento in camelCase o snake\_case: `ToolAnnotations(readOnlyHint=True)` e `ToolAnnotations(read_only_hint=True)` sono equivalenti. Per rileggere un suggerimento dall'oggetto, usa la grafia dichiarata dal pacchetto `mcp` installato: `.readOnlyHint` su `mcp` 1.x e `.read_only_hint` su 2.x, mentre `.maxResultSizeChars` funziona su entrambi. Puoi anche passare un semplice `mcp.types.ToolAnnotations` ovunque l'SDK accetti annotazioni.
198 198
199I nomi snake\_case e il campo tipizzato `maxResultSizeChars` richiedono Python Agent SDK 0.2.140 o successivo. Le versioni da 0.1.31 a 0.2.139 riesportano `mcp.types.ToolAnnotations` senza modifiche. Nelle versioni da 0.1.55 a 0.2.139 potete comunque passare `maxResultSizeChars` come argomento di parola chiave: la classe MCP accetta campi extra e l'SDK invia il valore a Claude Code.199I nomi snake\_case e il campo tipizzato `maxResultSizeChars` richiedono Python Agent SDK 0.2.140 o successivo. Le versioni da 0.1.31 a 0.2.139 riesportano `mcp.types.ToolAnnotations` senza modifiche. Nelle versioni da 0.1.55 a 0.2.139 puoi comunque passare `maxResultSizeChars` come argomento di parola chiave: la classe MCP accetta campi extra e l'SDK invia il valore a Claude Code.
200 200
201Tutti i campi sono opzionali. I client non dovrebbero fare affidamento sui suggerimenti per decisioni di sicurezza.201Tutti i campi sono opzionali. I client non dovrebbero fare affidamento sui suggerimenti per decisioni di sicurezza.
202 202
318| Proprietà | Tipo | Descrizione |318| Proprietà | Tipo | Descrizione |
319| :- | :- | :- |319| :- | :- | :- |
320| `session_id` | `str` | Identificatore di sessione univoco |320| `session_id` | `str` | Identificatore di sessione univoco |
321| `summary` | `str` | Titolo di visualizzazione: titolo personalizzato, riepilogo generato automaticamente o primo prompt |321| `summary` | `str` | Titolo di visualizzazione: titolo personalizzato, prompt più recente, riepilogo generato automaticamente o primo prompt |
322| `last_modified` | `int` | Ora dell'ultima modifica in millisecondi dall'epoca |322| `last_modified` | `int` | Ora dell'ultima modifica in millisecondi dall'epoca |
323| `file_size` | `int \| None` | Dimensione del file di sessione in byte (`None` per backend di archiviazione remota) |323| `file_size` | `int \| None` | Dimensione del file di sessione in byte (`None` per backend di archiviazione remota) |
324| `custom_title` | `str \| None` | Titolo della sessione impostato dall'utente |324| `custom_title` | `str \| None` | Titolo della sessione: il titolo impostato dall'utente, o il titolo generato automaticamente quando non ne è impostato nessuno |
325| `first_prompt` | `str \| None` | Primo prompt utente significativo nella sessione |325| `first_prompt` | `str \| None` | Primo prompt utente significativo nella sessione |
326| `git_branch` | `str \| None` | Ramo Git alla fine della sessione |326| `git_branch` | `str \| None` | Branch Git alla fine della sessione |
327| `cwd` | `str \| None` | Directory di lavoro per la sessione |327| `cwd` | `str \| None` | Directory di lavoro per la sessione |
328| `tag` | `str \| None` | Tag della sessione impostato dall'utente (vedi [`tag_session()`](#tag_session)) |328| `tag` | `str \| None` | Tag della sessione impostato dall'utente (vedi [`tag_session()`](#tag_session)) |
329| `created_at` | `int \| None` | Ora di creazione della sessione in millisecondi dall'epoca |329| `created_at` | `int \| None` | Ora di creazione della sessione in millisecondi dall'epoca |
782</h2>782</h2>
783 783
784<Note>784<Note>
785 **`@dataclass` vs `TypedDict`:** Questo SDK utilizza due tipi di tipi. Le classi decorate con `@dataclass` (come `ResultMessage`, `AgentDefinition`, `TextBlock`) sono istanze di oggetti in fase di esecuzione e supportano l'accesso agli attributi: `msg.result`. Le classi definite con `TypedDict` (come `ThinkingConfigEnabled`, `McpStdioServerConfig`, `SyncHookJSONOutput`) sono **dicts semplici in fase di esecuzione** e richiedono l'accesso alle chiavi: `config["budget_tokens"]`, non `config.budget_tokens`. La sintassi di chiamata `ClassName(field=value)` funziona per entrambi, ma solo le dataclass producono oggetti con attributi.785 **`@dataclass` vs `TypedDict`:** Questo SDK utilizza due tipi di tipi. Le classi decorate con `@dataclass` (come `ResultMessage`, `AgentDefinition`, `TextBlock`) sono istanze di oggetti in fase di esecuzione e supportano l'accesso agli attributi: `msg.result`. Le classi definite con `TypedDict` (come `ThinkingConfigEnabled`, `McpStdioServerConfig`, `SyncHookJSONOutput`) sono **dict semplici in fase di esecuzione** e richiedono l'accesso alle chiavi: `config["budget_tokens"]`, non `config.budget_tokens`. La sintassi di chiamata `ClassName(field=value)` funziona per entrambi, ma solo le dataclass producono oggetti con attributi.
786</Note>786</Note>
787 787
788<h3 id="sdkmcptool">788<h3 id="sdkmcptool">
919| Proprietà | Tipo | Predefinito | Descrizione |919| Proprietà | Tipo | Predefinito | Descrizione |
920| :- | :- | :- | :- |920| :- | :- | :- | :- |
921| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Configurazione degli strumenti. Usa `{"type": "preset", "preset": "claude_code"}` per gli strumenti predefiniti di Claude Code |921| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Configurazione degli strumenti. Usa `{"type": "preset", "preset": "claude_code"}` per gli strumenti predefiniti di Claude Code |
922| `allowed_tools` | `list[str]` | `[]` | Strumenti da approvare automaticamente senza chiedere. Questo non limita Claude a solo questi strumenti. Se nomini uno dei [strumenti di tracciamento delle attività](/docs/it/agent-sdk/todo-tracking#model-availability) qui, Claude Code opta anche la sessione. Gli altri strumenti non elencati ricadono in `permission_mode` e `can_use_tool`. Usa `disallowed_tools` per bloccare gli strumenti. Vedi [Autorizzazioni](/docs/it/agent-sdk/permissions#allow-and-deny-rules) |922| `allowed_tools` | `list[str]` | `[]` | Strumenti da approvare automaticamente senza chiedere. Questo non limita Claude a solo questi strumenti. Se nomini uno degli [strumenti di tracciamento delle attività](/docs/it/agent-sdk/todo-tracking#model-availability) qui, Claude Code abilita anche la sessione. Gli altri strumenti non elencati passano a `permission_mode` e `can_use_tool`. Usa `disallowed_tools` per bloccare gli strumenti. Vedi [Permessi](/docs/it/agent-sdk/permissions#allow-and-deny-rules) |
923| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | Configurazione del prompt di sistema. Passa una stringa per un prompt personalizzato, `{"type": "preset", "preset": "claude_code"}` per il prompt di sistema di Claude Code con `"append"` opzionale, `{"type": "custom", "prompt": "..."}` per un prompt personalizzato che può anche impostare `"snapshot"`, o `{"type": "file", "path": "..."}` per caricare un prompt grande da disco. Vedi [`SystemPromptPreset`](#systempromptpreset), [`SystemPromptCustom`](#systempromptcustom), e [`SystemPromptFile`](#systempromptfile) |923| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | Configurazione del prompt di sistema. Passa una stringa per un prompt personalizzato, `{"type": "preset", "preset": "claude_code"}` per il prompt di sistema di Claude Code con `"append"` opzionale, `{"type": "custom", "prompt": "..."}` per un prompt personalizzato che può anche impostare `"snapshot"`, o `{"type": "file", "path": "..."}` per caricare un prompt grande da disco. Vedi [`SystemPromptPreset`](#systempromptpreset), [`SystemPromptCustom`](#systempromptcustom), e [`SystemPromptFile`](#systempromptfile) |
924| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | Configurazioni del server MCP o percorso al file di configurazione |924| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | Configurazioni del server MCP o percorso al file di configurazione |
925| `strict_mcp_config` | `bool` | `False` | Quando `True`, usa solo i server passati in `mcp_servers` 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). Mappa al flag CLI `--strict-mcp-config` |925| `strict_mcp_config` | `bool` | `False` | Quando `True`, usa solo i server passati in `mcp_servers` 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). Mappa al flag CLI `--strict-mcp-config` |
926| `permission_mode` | `PermissionMode \| None` | `None` | Modalità di autorizzazione per l'utilizzo dello strumento |926| `permission_mode` | `PermissionMode \| None` | `None` | Modalità di permesso per l'utilizzo degli strumenti |
927| `continue_conversation` | `bool` | `False` | Continua la conversazione più recente |927| `continue_conversation` | `bool` | `False` | Continua la conversazione più recente |
928| `resume` | `str \| None` | `None` | ID della sessione da riprendere |928| `resume` | `str \| None` | `None` | ID della sessione da riprendere |
929| `session_id` | `str \| None` | `None` | Usa un ID di sessione specifico invece di uno generato automaticamente. Deve essere un UUID valido. Non può essere combinato con `continue_conversation` o `resume` a meno che `fork_session` non sia anche impostato |929| `session_id` | `str \| None` | `None` | Usa un ID di sessione specifico invece di uno generato automaticamente. Deve essere un UUID valido. Non può essere combinato con `continue_conversation` o `resume` a meno che `fork_session` non sia anche impostato |
930| `max_turns` | `int \| None` | `None` | Numero massimo di turni agentici (round trip di utilizzo dello strumento) |930| `max_turns` | `int \| None` | `None` | Numero massimo di turni agentici (round trip di utilizzo degli strumenti) |
931| `max_budget_usd` | `float \| None` | `None` | Interrompi la query quando la stima del costo lato client raggiunge questo valore in USD. Conta solo la spesa della chiamata stessa; i totali ripristinati da una sessione ripresa non contano. Per le avvertenze di accuratezza e il comportamento di ripristino, vedi [Traccia costo e utilizzo](/docs/it/agent-sdk/cost-tracking) |931| `max_budget_usd` | `float \| None` | `None` | Interrompi la query quando la stima del costo lato client raggiunge questo valore in USD. Conta solo la spesa della chiamata stessa; i totali ripristinati da una sessione ripresa non contano. Per le avvertenze di accuratezza e il comportamento di ripristino, vedi [Traccia costo e utilizzo](/docs/it/agent-sdk/cost-tracking) |
932| `disallowed_tools` | `list[str]` | `[]` | Strumenti da negare. Un nome semplice come `"Bash"` rimuove lo strumento dal contesto di Claude. Una regola con ambito come `"Bash(rm *)"` lascia lo strumento disponibile e nega le chiamate corrispondenti in ogni modalità di autorizzazione, incluso `bypassPermissions`, per il comando [come scritto](/docs/it/permissions#bash-rule-limits). Vedi [Autorizzazioni](/docs/it/agent-sdk/permissions#allow-and-deny-rules) |932| `disallowed_tools` | `list[str]` | `[]` | Strumenti da negare. Un nome semplice come `"Bash"` rimuove lo strumento dal contesto di Claude. Una regola con ambito come `"Bash(rm *)"` lascia lo strumento disponibile e nega le chiamate corrispondenti in ogni modalità di permesso, incluso `bypassPermissions`, per il comando [come scritto](/docs/it/permissions#bash-rule-limits). Vedi [Permessi](/docs/it/agent-sdk/permissions#allow-and-deny-rules) |
933| `enable_file_checkpointing` | `bool` | `False` | Abilita il tracciamento dei cambiamenti dei file per il rewind. Vedi [File checkpointing](/docs/it/agent-sdk/file-checkpointing) |933| `enable_file_checkpointing` | `bool` | `False` | Abilita il tracciamento dei cambiamenti dei file per il rewind. Vedi [File checkpointing](/docs/it/agent-sdk/file-checkpointing) |
934| `model` | `str \| None` | `None` | Alias del modello Claude o nome completo del modello. Vedi [valori accettati e ID specifici del provider](/docs/it/model-config#available-models) |934| `model` | `str \| None` | `None` | Alias del modello Claude o nome completo del modello. Vedi [valori accettati e ID specifici del provider](/docs/it/model-config#available-models) |
935| `fallback_model` | `str \| None` | `None` | Modello di fallback da utilizzare se il modello primario fallisce. Accetta un elenco separato da virgole. Per indicazioni, vedi [Scegli un modello](/docs/it/agent-sdk/configuration#choose-a-model) |935| `fallback_model` | `str \| None` | `None` | Modello di fallback da utilizzare se il modello primario fallisce. Accetta un elenco separato da virgole. Per indicazioni, vedi [Scegli un modello](/docs/it/agent-sdk/configuration#choose-a-model) |
936| `betas` | `list[SdkBeta]` | `[]` | Funzionalità beta da abilitare. Vedi [`SdkBeta`](#sdkbeta) per le opzioni disponibili |936| `betas` | `list[SdkBeta]` | `[]` | Funzionalità beta da abilitare. Vedi [`SdkBeta`](#sdkbeta) per le opzioni disponibili |
937| `output_format` | `dict[str, Any] \| None` | `None` | Formato di output per risposte strutturate (ad es. `{"type": "json_schema", "schema": {...}}`). Vedi [Output strutturati](/docs/it/agent-sdk/structured-outputs) per i dettagli |937| `output_format` | `dict[str, Any] \| None` | `None` | Formato di output per risposte strutturate (ad es. `{"type": "json_schema", "schema": {...}}`). Vedi [Output strutturati](/docs/it/agent-sdk/structured-outputs) per i dettagli |
938| `permission_prompt_tool_name` | `str \| None` | `None` | Nome dello strumento MCP per i prompt di autorizzazione |938| `permission_prompt_tool_name` | `str \| None` | `None` | Nome dello strumento MCP per le richieste di permesso |
939| `cwd` | `str \| Path \| None` | `None` | Directory di lavoro corrente |939| `cwd` | `str \| Path \| None` | `None` | Directory di lavoro corrente |
940| `cli_path` | `str \| Path \| None` | `None` | Percorso personalizzato all'eseguibile CLI di Claude Code |940| `cli_path` | `str \| Path \| None` | `None` | Percorso personalizzato all'eseguibile CLI di Claude Code |
941| `settings` | `str \| None` | `None` | Percorso al file di impostazioni o una stringa JSON inline |941| `settings` | `str \| None` | `None` | Percorso al file di impostazioni o una stringa JSON inline |
942| `add_dirs` | `list[str \| Path]` | `[]` | Directory aggiuntive a cui Claude può accedere. L'SDK passa ogni voce a Claude Code come `--add-dir`, quindi con l'impostazione della fonte `project` Claude Code [carica anche le skills, i comandi e i subagenti della directory](/docs/it/permissions#additional-directories-grant-file-access-not-configuration) |942| `add_dirs` | `list[str \| Path]` | `[]` | Directory aggiuntive a cui Claude può accedere. L'SDK passa ogni voce a Claude Code come `--add-dir`, quindi con la fonte di impostazioni `project` Claude Code [carica anche le skill, i comandi e i subagent della directory](/docs/it/permissions#additional-directories-grant-file-access-not-configuration) |
943| `env` | `dict[str, str]` | `{}` | Variabili di ambiente unite in cima all'ambiente del processo ereditato. Vedi [Variabili di ambiente](/docs/it/env-vars) per le variabili che la CLI sottostante legge, e [Gestisci risposte API lente o bloccate](#handle-slow-or-stalled-api-responses) per le variabili relative ai timeout. Imposta `CLAUDE_AGENT_SDK_CLIENT_APP` per identificare la tua app nell'intestazione User-Agent |943| `env` | `dict[str, str]` | `{}` | Variabili d'ambiente unite in cima all'ambiente del processo ereditato. Vedi [Variabili d'ambiente](/docs/it/env-vars) per le variabili che la CLI sottostante legge, e [Gestisci risposte API lente o bloccate](#handle-slow-or-stalled-api-responses) per le variabili relative ai timeout. Imposta `CLAUDE_AGENT_SDK_CLIENT_APP` per identificare la tua app nell'intestazione User-Agent |
944| `extra_args` | `dict[str, str \| None]` | `{}` | Argomenti CLI aggiuntivi da passare direttamente alla CLI |944| `extra_args` | `dict[str, str \| None]` | `{}` | Argomenti CLI aggiuntivi da passare direttamente alla CLI |
945| `max_buffer_size` | `int \| None` | `None` | Byte massimi durante il buffering dell'stdout della CLI |945| `max_buffer_size` | `int \| None` | `None` | Byte massimi durante il buffering dello stdout della CLI |
946| `debug_stderr` | `Any` | `sys.stderr` | *Deprecato* - L'SDK ignora questo valore. Usa il callback `stderr` per l'output stderr della CLI |946| `debug_stderr` | `Any` | `sys.stderr` | *Deprecato* - L'SDK ignora questo valore. Usa il callback `stderr` per l'output stderr della CLI |
947| `stderr` | `Callable[[str], None] \| None` | `None` | Funzione di callback per l'output stderr dalla CLI |947| `stderr` | `Callable[[str], None] \| None` | `None` | Funzione di callback per l'output stderr dalla CLI |
948| `can_use_tool` | [`CanUseTool`](#canusetool) ` \| None` | `None` | Funzione di callback per l'autorizzazione dello strumento, invocata solo quando il [flusso di autorizzazione](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated) ricade in un prompt. Non invocata per le chiamate auto-approvate da `allowed_tools`, regole di autorizzazione, o `permission_mode`. 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 |948| `can_use_tool` | [`CanUseTool`](#canusetool) ` \| None` | `None` | Funzione di callback per i permessi degli strumenti, invocata solo quando il [flusso dei permessi](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated) arriva a una richiesta di permesso. Non invocata per le chiamate approvate automaticamente da `allowed_tools`, regole di consenso, o `permission_mode`. Una regola di consenso non pre-approva le [azioni che nessuna modalità approva automaticamente](/docs/it/permission-modes#actions-no-mode-auto-approves). Vedi [`CanUseTool`](#canusetool) per i dettagli |
949| `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | Configurazioni hook per intercettare gli eventi |949| `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | Configurazioni degli hook per intercettare gli eventi |
950| `user` | `str \| None` | `None` | Su piattaforme POSIX, l'account utente del sistema operativo in cui viene eseguito il subprocess Claude Code. Claude Code mantiene l'ambiente del processo genitore, incluso `HOME`, e viene eseguito in `cwd` |950| `user` | `str \| None` | `None` | Su piattaforme POSIX, l'account utente del sistema operativo con cui viene eseguito il subprocess Claude Code. Claude Code mantiene l'ambiente del processo genitore, incluso `HOME`, e viene eseguito in `cwd` |
951| `include_partial_messages` | `bool` | `False` | Includi eventi di streaming di messaggi parziali. Se abilitato, i messaggi [`StreamEvent`](#streamevent) vengono prodotti |951| `include_partial_messages` | `bool` | `False` | Includi eventi di streaming di messaggi parziali. Se abilitato, vengono prodotti i messaggi [`StreamEvent`](#streamevent) |
952| `include_hook_events` | `bool` | `False` | Includi eventi del ciclo di vita dei hook nel flusso di messaggi come oggetti `HookEventMessage` |952| `include_hook_events` | `bool` | `False` | Includi eventi del ciclo di vita degli hook nel flusso di messaggi come oggetti `HookEventMessage` |
953| `forward_subagent_text` | `bool` | `False` | Inoltra i blocchi di testo e pensiero dei subagenti nel flusso di messaggi. Senza questa opzione, Claude Code emette blocchi `tool_use` e `tool_result` dei subagenti ma non testo o pensiero. Richiede Python Agent SDK 0.2.140 o successivo |953| `forward_subagent_text` | `bool` | `False` | Inoltra i blocchi di testo e di ragionamento dei subagent nel flusso di messaggi. Senza questa opzione, Claude Code emette i blocchi `tool_use` e `tool_result` dei subagent ma non testo o ragionamento. Richiede Python Agent SDK 0.2.140 o successivo |
954| `verbatim_prompts` | `bool` | `False` | Consegna ogni prompt come scritto. L'SDK invia ogni messaggio utente con `client_composed` impostato a `True`. Vedi [`client_composed`](/docs/it/agent-sdk/typescript#sdkusermessage) per ciò che Claude Code salta su quei messaggi. Usa questa opzione quando il testo del prompt include contenuto che l'utente finale non ha digitato. Per il controllo per turno, lascialo disattivato e imposta `"client_composed": True` su singoli messaggi trasmessi invece. Mentre l'opzione è attiva, l'SDK sovrascrive qualsiasi valore `client_composed` che imposti. Richiede Python Agent SDK 0.2.158 o successivo e Claude Code v2.1.248 o successivo; la CLI fornita con quelle versioni dell'SDK soddisfa il requisito di Claude Code |954| `verbatim_prompts` | `bool` | `False` | Consegna ogni prompt come scritto. L'SDK invia ogni messaggio utente con `client_composed` impostato a `True`. Vedi [`client_composed`](/docs/it/agent-sdk/typescript#sdkusermessage) per ciò che Claude Code salta su quei messaggi. Usa questa opzione quando il testo del prompt include contenuto che l'utente finale non ha digitato. Per il controllo per turno, lasciala disattivata e imposta invece `"client_composed": True` su singoli messaggi trasmessi in streaming. Mentre l'opzione è attiva, l'SDK sovrascrive qualsiasi valore `client_composed` che imposti. Richiede Python Agent SDK 0.2.158 o successivo e Claude Code v2.1.248 o successivo; la CLI fornita con quelle versioni dell'SDK soddisfa il requisito di Claude Code |
955| `fork_session` | `bool` | `False` | Quando si riprende con `resume`, esegui il fork a un nuovo ID di sessione invece di continuare la sessione originale |955| `fork_session` | `bool` | `False` | Quando si riprende con `resume`, esegui il fork a un nuovo ID di sessione invece di continuare la sessione originale |
956| `resume_session_at` | `str \| None` | `None` | Quando si riprende, carica la conversazione solo fino a e includendo il messaggio con questo UUID. Usa con `resume`, e solitamente `fork_session`, per ramificarsi da un punto precedente. Richiede Python Agent SDK 0.2.137 o successivo |956| `resume_session_at` | `str \| None` | `None` | Quando si riprende, carica la conversazione solo fino al messaggio con questo UUID, incluso. Usa con `resume`, e solitamente `fork_session`, per creare un branch da un punto precedente. Richiede Python Agent SDK 0.2.137 o successivo |
957| `resume_drops_turn` | `str \| None` | `None` | UUID del prompt utente il cui turno un troncamento `resume_session_at` scarta. Quando impostato, la CLI rifiuta la ripresa se l'intervallo scartato contiene voci non attribuibili a quel turno. Richiede Python Agent SDK 0.2.137 o successivo e Claude Code v2.1.223 o successivo; la CLI fornita con quelle versioni dell'SDK soddisfa il requisito di Claude Code |957| `resume_drops_turn` | `str \| None` | `None` | UUID del prompt utente il cui turno un troncamento `resume_session_at` scarta. Quando impostato, la CLI rifiuta la ripresa se l'intervallo scartato contiene voci non attribuibili a quel turno. Richiede Python Agent SDK 0.2.137 o successivo e Claude Code v2.1.223 o successivo; la CLI fornita con quelle versioni dell'SDK soddisfa il requisito di Claude Code |
958| `agents` | `dict[str, AgentDefinition] \| None` | `None` | Subagenti definiti programmaticamente |958| `agents` | `dict[str, AgentDefinition] \| None` | `None` | Subagent definiti programmaticamente |
959| `plugins` | `list[SdkPluginConfig]` | `[]` | Carica plugin personalizzati da percorsi locali. Vedi [Plugin](/docs/it/agent-sdk/plugins) per i dettagli |959| `plugins` | `list[SdkPluginConfig]` | `[]` | Carica plugin personalizzati da percorsi locali. Vedi [Plugin](/docs/it/agent-sdk/plugins) per i dettagli |
960| `sandbox` | [`SandboxSettings`](#sandboxsettings) ` \| None` | `None` | Configura il comportamento della sandbox a livello di programmazione. Vedi [Impostazioni sandbox](#sandboxsettings) per i dettagli |960| `sandbox` | [`SandboxSettings`](#sandboxsettings) ` \| None` | `None` | Configura il comportamento della sandbox a livello di programmazione. Vedi [Impostazioni sandbox](#sandboxsettings) per i dettagli |
961| `setting_sources` | `list[SettingSource] \| None` | `None` (Impostazioni predefinite CLI: tutte le fonti) | Controlla quali impostazioni del filesystem caricare. Passa `[]` per disabilitare le impostazioni utente, progetto e locali. Con `skills` impostato e questo campo non impostato, solo le fonti utente e progetto si caricano. Imposta `setting_sources` esplicitamente per mantenere le impostazioni locali. La politica gestita dall'endpoint si carica 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). Per gli input letti indipendentemente da questa opzione, vedi [Cosa settingSources non controlla](/docs/it/agent-sdk/claude-code-features#what-settingsources-does-not-control) |961| `setting_sources` | `list[SettingSource] \| None` | `None` (Impostazioni predefinite CLI: tutte le fonti) | Controlla quali impostazioni del filesystem caricare. Passa `[]` per disabilitare le impostazioni utente, progetto e locali. Con `skills` impostato e questo campo non impostato, si caricano solo le fonti utente e progetto. Imposta `setting_sources` esplicitamente per mantenere le impostazioni locali. La politica gestita dall'endpoint si carica indipendentemente; le impostazioni gestite dal server vengono recuperate quando la sessione si autentica con una credenziale dell'organizzazione su una [configurazione idonea](/docs/it/server-managed-settings#platform-availability). Per gli input letti indipendentemente da questa opzione, vedi [Cosa settingSources non controlla](/docs/it/agent-sdk/claude-code-features#what-settingsources-does-not-control) |
962| `skills` | `list[str] \| Literal["all"] \| None` | `None` | Skills disponibili per la sessione. Passa `"all"` per abilitare ogni skill scoperta, o un elenco di nomi di skill. Passa solo nomi esatti. L'SDK rifiuta i nomi malformati e in forma wildcard con un `ValueError` prima di avviare il processo Claude Code; questo controllo richiede Python Agent SDK 0.2.129 o successivo. Quando impostato, l'SDK aggiunge lo strumento Skill a `allowed_tools` automaticamente. Se passi anche `tools`, includi `"Skill"` in quell'elenco. Vedi [Skills](/docs/it/agent-sdk/skills) |962| `skills` | `list[str] \| Literal["all"] \| None` | `None` | Skill disponibili per la sessione. Passa `"all"` per abilitare ogni skill scoperta, o un elenco di nomi di skill. Passa solo nomi esatti. L'SDK rifiuta i nomi malformati e in forma wildcard con un `ValueError` prima di avviare il processo Claude Code; questo controllo richiede Python Agent SDK 0.2.129 o successivo. Quando impostato, l'SDK aggiunge automaticamente lo strumento Skill a `allowed_tools`. Se passi anche `tools`, includi `"Skill"` in quell'elenco. Vedi [Skill](/docs/it/agent-sdk/skills) |
963| `max_thinking_tokens` | `int \| None` | `None` | *Deprecato* - Token massimi per i blocchi di pensiero. Usa `thinking` invece |963| `max_thinking_tokens` | `int \| None` | `None` | *Deprecato* - Token massimi per i blocchi di ragionamento. Usa invece `thinking` |
964| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | Controlla il comportamento del pensiero esteso. Ha la precedenza su `max_thinking_tokens` |964| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | Controlla il comportamento del ragionamento esteso. Ha la precedenza su `max_thinking_tokens` |
965| `effort` | [`EffortLevel`](#effortlevel) ` \| None` | `None` | Livello di sforzo per la profondità del pensiero. Vedi [regola il livello di sforzo](/docs/it/model-config#adjust-effort-level) |965| `effort` | [`EffortLevel`](#effortlevel) ` \| None` | `None` | Livello di sforzo per la profondità del ragionamento. Vedi [regola il livello di sforzo](/docs/it/model-config#adjust-effort-level) |
966| `session_store` | [`SessionStore`](/docs/it/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | Specchia i trascritti di 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) |966| `session_store` | [`SessionStore`](/docs/it/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | Replica le trascrizioni di sessione in un backend esterno in modo che un altro host possa riprenderle. Vedi [Persisti le sessioni nell'archiviazione esterna](/docs/it/agent-sdk/session-storage) |
967| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | Quando eseguire il flush delle voci di trascritto mirrorato a `session_store`. `"batched"` esegue il flush una volta per turno o quando il buffer si riempie; `"eager"` attiva un flush in background dopo ogni frame. Ignorato quando `session_store` è `None` |967| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | Quando eseguire il flush delle voci di trascrizione replicate in `session_store`. `"batched"` esegue il flush una volta per turno o quando il buffer si riempie; `"eager"` attiva un flush in background dopo ogni frame. Ignorato quando `session_store` è `None` |
968| `load_timeout_ms` | `int` | `60000` | Timeout per chiamata per `session_store.load()` e `list_subkeys()` durante la materializzazione della ripresa, in millisecondi |968| `load_timeout_ms` | `int` | `60000` | Timeout per chiamata per `session_store.load()` e `list_subkeys()` durante la materializzazione della ripresa, in millisecondi |
969| `task_budget` | `TaskBudget \| None` | `None` | Budget di token lato API. Inviato come `output_config.task_budget` con l'intestazione beta `task-budgets-2026-03-13`. Passa `{"total": <int>}`. |969| `task_budget` | `TaskBudget \| None` | `None` | Budget di token lato API. Inviato come `output_config.task_budget` con l'intestazione beta `task-budgets-2026-03-13`. Passa `{"total": <int>}`. |
970 970
972 Gestisci risposte API lente o bloccate972 Gestisci risposte API lente o bloccate
973</h4>973</h4>
974 974
975Il subprocess CLI legge diverse variabili di ambiente che controllano i timeout dell'API e il rilevamento dei blocchi. Passale attraverso `ClaudeAgentOptions.env`:975Il subprocess CLI legge diverse variabili d'ambiente che controllano i timeout dell'API e il rilevamento dei blocchi. Passale attraverso `ClaudeAgentOptions.env`:
976 976
977```python theme={null}977```python theme={null}
978from claude_agent_sdk import ClaudeAgentOptions978from claude_agent_sdk import ClaudeAgentOptions
986)986)
987```987```
988 988
989* `API_TIMEOUT_MS`: timeout per richiesta sul client Anthropic, in millisecondi. Predefinito `600000`. Si applica al ciclo principale e a tutti i subagenti.989* `API_TIMEOUT_MS`: timeout per richiesta sul client Anthropic, in millisecondi. Predefinito `600000`. Si applica al ciclo principale e a tutti i subagent.
990* `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 di parete nel caso peggiore è approssimativamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` più backoff. Per esecuzioni incustodite che devono attendere interruzioni più lunghe, imposta [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/it/errors#tune-retry-behavior): ritenta gli errori di capacità transitori indefinitamente e, a partire da Claude Code v2.1.199, aumenta il valore predefinito per altri errori transitori a `300` e rimuove il limite su questa variabile.990* `CLAUDE_CODE_MAX_RETRIES`: numero massimo di nuovi tentativi API. Predefinito `10`, limitato a `15`. Ogni nuovo tentativo ottiene la propria finestra `API_TIMEOUT_MS`, quindi il tempo reale nel caso peggiore è approssimativamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` più backoff. Per esecuzioni incustodite che devono attendere interruzioni più lunghe, imposta [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/it/errors#tune-retry-behavior): riprova indefinitamente in caso di errori di capacità transitori e, a partire da Claude Code v2.1.199, aumenta il valore predefinito per altri errori transitori a `300` e rimuove il limite su questa variabile.
991* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog di blocco per i subagenti. Mentre il watchdog del flusso è attivo, il predefinito è `CLAUDE_STREAM_IDLE_TIMEOUT_MS` più 5 minuti, che ammonta a `600000` a meno che non aumenti quella variabile. Con il watchdog del flusso disattivato, il predefinito è `600000`. Prima di v2.1.257, il predefinito era sempre `600000`.991* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog di blocco per i subagent. Mentre il watchdog del flusso è attivo, il predefinito è `CLAUDE_STREAM_IDLE_TIMEOUT_MS` più 5 minuti, che ammonta a `600000` a meno che non aumenti quella variabile. Con il watchdog del flusso disattivato, il predefinito è `600000`. Prima di v2.1.257, il predefinito era sempre `600000`.
992 992
993 Il timer si ripristina su ogni evento di flusso. In caso di blocco, Claude Code interrompe il subagente e segnala il blocco al genitore. Per un subagente in background, contrassegna anche l'attività come non riuscita e allega qualsiasi risultato parziale.993 Il timer si azzera a ogni evento del flusso. In caso di blocco, Claude Code interrompe il subagent e segnala il blocco al genitore. Per un subagent in background, contrassegna anche l'attività come non riuscita e allega qualsiasi risultato parziale.
994* `CLAUDE_ENABLE_STREAM_WATCHDOG` con `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: watchdog del flusso 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` e viene bloccato 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.994* `CLAUDE_ENABLE_STREAM_WATCHDOG` con `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: watchdog del flusso che interrompe la richiesta quando le intestazioni sono arrivate ma il corpo della risposta smette di essere trasmesso in streaming. Il watchdog è attivo per impostazione predefinita per tutti i provider; imposta `CLAUDE_ENABLE_STREAM_WATCHDOG=0` per disabilitarlo. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` ha come predefinito `300000` e non può scendere sotto quel minimo. Dopo l'interruzione, [Nuovi tentativi automatici](/docs/it/errors#automatic-retries) descrive cosa fa Claude Code, in base a quanto la risposta era avanzata.
995 995
996 Mentre il watchdog attende una risposta che un gateway dietro `ANTHROPIC_BASE_URL` tiene aperta con ping keep-alive, un host che imposta `include_partial_messages` continua a ricevere messaggi [`StreamEvent`](#streamevent) di `ping`. Leggi quei 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 flusso reale.996 Mentre il watchdog attende una risposta che un gateway dietro `ANTHROPIC_BASE_URL` tiene aperta con ping keep-alive, un host che imposta `include_partial_messages` continua a ricevere messaggi [`StreamEvent`](#streamevent) di `ping`. Interpreta quei frame come segnali di attività invece di far scadere la sessione per inattività. Prima di v2.1.257, i frame si fermavano 5 minuti dopo l'ultimo evento di flusso reale.
997 997
998<h3 id="outputformat">998<h3 id="outputformat">
999 `OutputFormat`999 `OutputFormat`
1035| `preset` | Sì | Deve essere `"claude_code"` per utilizzare il prompt di sistema di Claude Code |1035| `preset` | Sì | Deve essere `"claude_code"` per utilizzare il prompt di sistema di Claude Code |
1036| `append` | No | Istruzioni aggiuntive da aggiungere al prompt di sistema preset |1036| `append` | No | Istruzioni aggiuntive da aggiungere al prompt di sistema preset |
1037| `exclude_dynamic_sections` | No | Sposta il contesto per utente, come la posizione della memoria automatica, dal prompt di sistema nel primo messaggio utente. Migliora il riutilizzo della cache dei prompt tra utenti e macchine. Vedi [Modifica i prompt di sistema](/docs/it/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |1037| `exclude_dynamic_sections` | No | Sposta il contesto per utente, come la posizione della memoria automatica, dal prompt di sistema nel primo messaggio utente. Migliora il riutilizzo della cache dei prompt tra utenti e macchine. Vedi [Modifica i prompt di sistema](/docs/it/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |
1038| `snapshot` | No | Imposta a `False` per ricostruire il prompt di sistema su ogni richiesta invece di [riutilizzare il prompt che la sessione ha registrato alla sua prima richiesta](/docs/it/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session). Richiede `claude-agent-sdk` v0.2.153 o successivo |1038| `snapshot` | No | Imposta a `False` per ricostruire il prompt di sistema a ogni richiesta invece di [riutilizzare il prompt che la sessione ha registrato alla sua prima richiesta](/docs/it/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session). Richiede `claude-agent-sdk` v0.2.153 o successivo |
1039 1039
1040<h3 id="systempromptcustom">1040<h3 id="systempromptcustom">
1041 `SystemPromptCustom`1041 `SystemPromptCustom`
1053| Campo | Obbligatorio | Descrizione |1053| Campo | Obbligatorio | Descrizione |
1054| :- | :- | :- |1054| :- | :- | :- |
1055| `type` | Sì | Deve essere `"custom"` |1055| `type` | Sì | Deve essere `"custom"` |
1056| `prompt` | Sì | Il testo del prompt di sistema. Passato alla CLI come argomento della riga di comando, quindi i [limiti di lunghezza della riga di comando](#systempromptfile) si applicano |1056| `prompt` | Sì | Il testo del prompt di sistema. Passato alla CLI come argomento della riga di comando, quindi si applicano i [limiti di lunghezza della riga di comando](#systempromptfile) |
1057| `snapshot` | No | Uguale a [`SystemPromptPreset.snapshot`](#systempromptpreset), applicato a `prompt` |1057| `snapshot` | No | Uguale a [`SystemPromptPreset.snapshot`](#systempromptpreset), applicato a `prompt` |
1058 1058
1059<h3 id="systempromptfile">1059<h3 id="systempromptfile">
1060 `SystemPromptFile`1060 `SystemPromptFile`
1061</h3>1061</h3>
1062 1062
1063Configurazione per il caricamento di un prompt di sistema personalizzato da un file invece di passarlo come stringa. L'SDK mappa questo al flag CLI [`--system-prompt-file`](/docs/it/cli-reference#system-prompt-flags). Usa il modulo file quando il prompt è grande: l'SDK passa una stringa `system_prompt` sull'argv del subprocess CLI, che è soggetto ai limiti di lunghezza della riga di comando del sistema operativo prima che l'SDK invii qualsiasi richiesta API. Su Linux un singolo argomento più lungo di circa 128 KB fallisce al spawn del processo con `Argument list too long`. Su Windows l'intera riga di comando è limitata a circa 32 KB, quindi il modulo stringa fallisce a una soglia inferiore.1063Configurazione per il caricamento di un prompt di sistema personalizzato da un file invece di passarlo come stringa. L'SDK mappa questo al flag CLI [`--system-prompt-file`](/docs/it/cli-reference#system-prompt-flags). Usa la forma file quando il prompt è grande: l'SDK passa una stringa `system_prompt` sull'argv del subprocess CLI, che è soggetto ai limiti di lunghezza della riga di comando del sistema operativo prima che l'SDK invii qualsiasi richiesta API. Su Linux un singolo argomento più lungo di circa 128 KB fallisce all'avvio del processo con `Argument list too long`. Su Windows l'intera riga di comando è limitata a circa 32 KB, quindi la forma stringa fallisce a una soglia inferiore.
1064 1064
1065```python theme={null}1065```python theme={null}
1066class SystemPromptFile(TypedDict):1066class SystemPromptFile(TypedDict):
1077 `SettingSource`1077 `SettingSource`
1078</h3>1078</h3>
1079 1079
1080Controlla quali fonti di configurazione basate su filesystem l'SDK carica le impostazioni da.1080Controlla da quali fonti di configurazione basate su filesystem l'SDK carica le impostazioni.
1081 1081
1082```python theme={null}1082```python theme={null}
1083SettingSource = Literal["user", "project", "local"]1083SettingSource = Literal["user", "project", "local"]
1086| Valore | Descrizione | Posizione |1086| Valore | Descrizione | Posizione |
1087| :- | :- | :- |1087| :- | :- | :- |
1088| `"user"` | Impostazioni utente globali | `~/.claude/settings.json` |1088| `"user"` | Impostazioni utente globali | `~/.claude/settings.json` |
1089| `"project"` | Impostazioni di progetto condivise (controllate dalla versione) | `.claude/settings.json` |1089| `"project"` | Impostazioni di progetto condivise (sotto controllo di versione) | `.claude/settings.json` |
1090| `"local"` | Impostazioni di progetto locali, gitignored quando Claude Code salva un'impostazione in essa | `.claude/settings.local.json` |1090| `"local"` | Impostazioni di progetto locali, aggiunte a gitignore quando Claude Code vi salva un'impostazione | `.claude/settings.local.json` |
1091 1091
1092<h4 id="default-behavior">1092<h4 id="default-behavior">
1093 Comportamento predefinito1093 Comportamento predefinito
1094</h4>1094</h4>
1095 1095
1096Quando `setting_sources` è omesso o `None` e `skills` non è impostato, `query()` carica le stesse impostazioni del filesystem della CLI di Claude Code: utente, progetto e locale. Con `skills` impostato, la riga [`setting_sources`](#claudeagentoptions) descrive il valore predefinito corrente. La politica gestita dall'endpoint viene caricata 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). Per ulteriori informazioni, vedi [Cosa settingSources non controlla](/docs/it/agent-sdk/claude-code-features#what-settingsources-does-not-control).1096Quando `setting_sources` è omesso o `None` e `skills` non è impostato, `query()` carica le stesse impostazioni del filesystem della CLI di Claude Code: utente, progetto e locale. Con `skills` impostato, la riga [`setting_sources`](#claudeagentoptions) descrive il valore predefinito corrente. La politica gestita dall'endpoint viene caricata in tutti i casi; le impostazioni gestite dal server vengono recuperate quando la sessione si autentica con una credenziale dell'organizzazione su una [configurazione idonea](/docs/it/server-managed-settings#platform-availability). Per ulteriori informazioni, vedi [Cosa settingSources non controlla](/docs/it/agent-sdk/claude-code-features#what-settingsources-does-not-control).
1097 1097
1098<h4 id="why-use-setting_sources">1098<h4 id="why-use-setting_sources">
1099 Perché usare setting\_sources1099 Perché usare setting\_sources
1192 `AgentDefinition`1192 `AgentDefinition`
1193</h3>1193</h3>
1194 1194
1195Configurazione per un subagente definito programmaticamente.1195Configurazione per un subagent definito programmaticamente.
1196 1196
1197```python theme={null}1197```python theme={null}
1198@dataclass1198@dataclass
1216| :- | :- | :- |1216| :- | :- | :- |
1217| `description` | Sì | Descrizione in linguaggio naturale di quando utilizzare questo agente |1217| `description` | Sì | Descrizione in linguaggio naturale di quando utilizzare questo agente |
1218| `prompt` | Sì | Il prompt di sistema dell'agente |1218| `prompt` | Sì | Il prompt di sistema dell'agente |
1219| `tools` | No | Array di nomi di strumenti consentiti. Se omesso, eredita ogni [strumento disponibile ai subagenti](/docs/it/sub-agents#available-tools) |1219| `tools` | No | Array di nomi di strumenti consentiti. Se omesso, eredita ogni [strumento disponibile ai subagent](/docs/it/sub-agents#available-tools) |
1220| `disallowedTools` | No | Array di nomi di strumenti da rimuovere dal set di strumenti dell'agente. Sono accettati anche i pattern a livello di server MCP: `mcp__server` o `mcp__server__*` rimuove ogni strumento da quel server, e `mcp__*` rimuove ogni strumento MCP da qualsiasi server |1220| `disallowedTools` | No | Array di nomi di strumenti da rimuovere dal set di strumenti dell'agente. Sono accettati anche i pattern a livello di server MCP: `mcp__server` o `mcp__server__*` rimuove ogni strumento da quel server, e `mcp__*` rimuove ogni strumento MCP da qualsiasi server |
1221| `model` | No | Override del modello per questo agente. Accetta un alias come `"sonnet"`, `"opus"`, `"haiku"`, o `"inherit"`, o un ID modello completo. Quando lo ometti, Claude Code sceglie il modello nell'[ordine del modello subagente](/docs/it/sub-agents#choose-a-model) |1221| `model` | No | Override del modello per questo agente. Accetta un alias come `"sonnet"`, `"opus"`, `"haiku"`, o `"inherit"`, o un ID modello completo. Quando lo ometti, Claude Code sceglie il modello secondo l'[ordine dei modelli dei subagent](/docs/it/sub-agents#choose-a-model) |
1222| `skills` | No | Elenco dei nomi di skills da precaricare nel contesto dell'agente all'avvio. Le skills non elencate rimangono invocabili attraverso lo strumento Skill |1222| `skills` | No | Elenco dei nomi di skill da precaricare nel contesto dell'agente all'avvio. Le skill non elencate rimangono invocabili attraverso lo strumento Skill |
1223| `memory` | No | Fonte di memoria per questo agente: `"user"`, `"project"`, o `"local"` |1223| `memory` | No | Fonte di memoria per questo agente: `"user"`, `"project"`, o `"local"` |
1224| `mcpServers` | No | Server MCP disponibili per questo agente. Ogni voce è un nome di server o un dict `{name: config}` inline |1224| `mcpServers` | No | Server MCP disponibili per questo agente. Ogni voce è un nome di server o un dict `{name: config}` inline |
1225| `initialPrompt` | No | Auto-inviato come il primo turno utente quando questo agente viene eseguito come agente del thread principale |1225| `initialPrompt` | No | Inviato automaticamente come primo turno utente quando questo agente viene eseguito come agente del thread principale |
1226| `maxTurns` | No | Numero massimo di turni agentici prima che l'agente si fermi |1226| `maxTurns` | No | Numero massimo di turni agentici prima che l'agente si fermi |
1227| `background` | No | Esegui questo agente come attività in background non bloccante quando invocato |1227| `background` | No | Esegui questo agente come attività in background non bloccante quando invocato |
1228| `effort` | No | Livello di sforzo di ragionamento per questo agente. Accetta un livello denominato o un numero intero. Vedi [`EffortLevel`](#effortlevel) |1228| `effort` | No | Livello di sforzo di ragionamento per questo agente. Accetta un livello denominato o un numero intero. Vedi [`EffortLevel`](#effortlevel) |
1229| `permissionMode` | No | Modalità di autorizzazione per l'esecuzione dello strumento 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) |1229| `permissionMode` | No | Modalità di permesso per l'esecuzione degli strumenti all'interno di questo agente. Le [regole di ereditarietà dei subagent](/docs/it/agent-sdk/permissions#available-modes) decidono quando si applica. Vedi [`PermissionMode`](#permissionmode) |
1230 1230
1231<Note>1231<Note>
1232 I nomi dei campi `AgentDefinition` usano camelCase, come `disallowedTools`, `permissionMode` e `maxTurns`. Questi nomi si mappano direttamente al formato wire condiviso con TypeScript SDK. Questo differisce da `ClaudeAgentOptions`, che usa Python snake\_case per i campi di livello superiore equivalenti come `disallowed_tools` e `permission_mode`. Poiché `AgentDefinition` è una dataclass, passare una parola chiave snake\_case genera un `TypeError` al momento della costruzione.1232 I nomi dei campi di `AgentDefinition` usano camelCase, come `disallowedTools`, `permissionMode` e `maxTurns`. Questi nomi si mappano direttamente al formato wire condiviso con TypeScript SDK. Questo differisce da `ClaudeAgentOptions`, che usa lo snake\_case di Python per i campi di livello superiore equivalenti come `disallowed_tools` e `permission_mode`. Poiché `AgentDefinition` è una dataclass, passare una parola chiave snake\_case genera un `TypeError` al momento della costruzione.
1233</Note>1233</Note>
1234 1234
1235<h3 id="permissionmode">1235<h3 id="permissionmode">
1236 `PermissionMode`1236 `PermissionMode`
1237</h3>1237</h3>
1238 1238
1239Modalità di autorizzazione per controllare l'esecuzione dello strumento.1239Modalità di permesso per controllare l'esecuzione degli strumenti.
1240 1240
1241```python theme={null}1241```python theme={null}
1242PermissionMode = Literal[1242PermissionMode = Literal[
1253 `EffortLevel`1253 `EffortLevel`
1254</h3>1254</h3>
1255 1255
1256Livelli di sforzo per guidare la profondità del pensiero.1256Livelli di sforzo per guidare la profondità del ragionamento.
1257 1257
1258```python theme={null}1258```python theme={null}
1259EffortLevel = Literal[1259EffortLevel = Literal[
1269 `CanUseTool`1269 `CanUseTool`
1270</h3>1270</h3>
1271 1271
1272Alias di tipo per le funzioni di callback di autorizzazione dello strumento.1272Alias di tipo per le funzioni di callback dei permessi degli strumenti.
1273 1273
1274```python theme={null}1274```python theme={null}
1275CanUseTool = Callable[1275CanUseTool = Callable[
1283* `input_data`: I parametri di input dello strumento1283* `input_data`: I parametri di input dello strumento
1284* `context`: Un `ToolPermissionContext` con informazioni aggiuntive1284* `context`: Un `ToolPermissionContext` con informazioni aggiuntive
1285 1285
1286Restituisce un `PermissionResult` (sia `PermissionResultAllow` che `PermissionResultDeny`).1286Restituisce un `PermissionResult` (`PermissionResultAllow` oppure `PermissionResultDeny`).
1287 1287
1288Il callback è il sostituto SDK per il prompt di autorizzazione interattivo: viene invocato solo quando il [flusso di valutazione delle autorizzazioni](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated) si risolve in un prompt. Le chiamate dello strumento già approvate da una voce `allowed_tools`, una regola di autorizzazione nelle impostazioni, o la modalità di autorizzazione, come `acceptEdits` o `bypassPermissions`, non lo invocano mai. Per controllare ogni chiamata dello strumento, usa un [hook `PreToolUse`](/docs/it/agent-sdk/hooks) invece.1288Il callback è il sostituto SDK della richiesta di permesso interattiva: viene invocato solo quando il [flusso di valutazione dei permessi](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated) si risolve in una richiesta di permesso. Le chiamate agli strumenti già approvate da una voce `allowed_tools`, da una regola di consenso nelle impostazioni, o dalla modalità di permesso, come `acceptEdits` o `bypassPermissions`, non lo invocano mai. Per controllare ogni chiamata a uno strumento, usa invece un [hook `PreToolUse`](/docs/it/agent-sdk/hooks).
1289 1289
1290Una regola di autorizzazione non pre-approva le [azioni che nessuna modalità auto-approva](/docs/it/permission-modes#actions-no-mode-auto-approves); vedi [Come vengono valutate le autorizzazioni](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated) per quali di esse raggiungono il callback e cosa accade in modalità `dontAsk` e `auto`.1290Una regola di consenso non pre-approva le [azioni che nessuna modalità approva automaticamente](/docs/it/permission-modes#actions-no-mode-auto-approves); vedi [Come vengono valutati i permessi](/docs/it/agent-sdk/permissions#how-permissions-are-evaluated) per sapere quali di esse raggiungono il callback e cosa accade in modalità `dontAsk` e `auto`.
1291 1291
1292<h3 id="toolpermissioncontext">1292<h3 id="toolpermissioncontext">
1293 `ToolPermissionContext`1293 `ToolPermissionContext`
1294</h3>1294</h3>
1295 1295
1296Informazioni di contesto passate ai callback di autorizzazione dello strumento.1296Informazioni di contesto passate ai callback dei permessi degli strumenti.
1297 1297
1298```python theme={null}1298```python theme={null}
1299@dataclass1299@dataclass
1312| Campo | Tipo | Descrizione |1312| Campo | Tipo | Descrizione |
1313| :- | :- | :- |1313| :- | :- | :- |
1314| `signal` | `Any \| None` | Riservato per il supporto futuro del segnale di interruzione |1314| `signal` | `Any \| None` | Riservato per il supporto futuro del segnale di interruzione |
1315| `suggestions` | `list[PermissionUpdate]` | Suggerimenti di aggiornamento delle autorizzazioni dalla CLI. I prompt Bash includono un suggerimento con la destinazione `localSettings`, quindi restituirlo in `updated_permissions` scrive la regola in `.claude/settings.local.json` e persiste tra le sessioni. |1315| `suggestions` | `list[PermissionUpdate]` | Suggerimenti di aggiornamento dei permessi dalla CLI. Le richieste di permesso di Bash includono un suggerimento con la destinazione `localSettings`, quindi restituirlo in `updated_permissions` scrive la regola in `.claude/settings.local.json` e persiste tra le sessioni. |
1316| `tool_use_id` | `str \| None` | Identificatore della chiamata dello strumento specifica per cui è questo prompt. Sempre popolato quando consegnato a `can_use_tool` |1316| `tool_use_id` | `str \| None` | Identificatore della specifica chiamata allo strumento a cui si riferisce questa richiesta. Sempre popolato quando consegnato a `can_use_tool` |
1317| `agent_id` | `str \| None` | ID del sub-agente quando la chiamata proviene da un subagente; `None` per l'agente principale |1317| `agent_id` | `str \| None` | ID del subagent quando la chiamata proviene da un subagent; `None` per l'agente principale |
1318| `blocked_path` | `str \| None` | Percorso del file che ha attivato la richiesta di autorizzazione, se applicabile. Ad esempio, quando un comando Bash tenta di accedere a un percorso al di fuori delle directory consentite |1318| `blocked_path` | `str \| None` | Percorso del file che ha attivato la richiesta di permesso, se applicabile. Ad esempio, quando un comando Bash tenta di accedere a un percorso al di fuori delle directory consentite |
1319| `decision_reason` | `str \| None` | Motivo per cui questa richiesta di autorizzazione è stata attivata. Inoltrato dal `permissionDecisionReason` di un hook PreToolUse quando l'hook ha restituito `"ask"` |1319| `decision_reason` | `str \| None` | Motivo per cui questa richiesta di permesso è stata attivata. Inoltrato dal `permissionDecisionReason` di un hook PreToolUse quando l'hook ha restituito `"ask"` |
1320| `title` | `str \| None` | Frase completa del prompt di autorizzazione, come `Claude wants to read foo.txt`. Usa come testo del prompt principale quando presente |1320| `title` | `str \| None` | Frase completa della richiesta di permesso, come `Claude wants to read foo.txt`. Usala come testo principale della richiesta quando presente |
1321| `display_name` | `str \| None` | Breve frase nominale per l'azione dello strumento, come `Read file`, adatta per etichette di pulsanti |1321| `display_name` | `str \| None` | Breve frase nominale per l'azione dello strumento, come `Read file`, adatta per etichette di pulsanti |
1322| `description` | `str \| None` | Sottotitolo leggibile per l'interfaccia utente di autorizzazione |1322| `description` | `str \| None` | Sottotitolo leggibile per l'interfaccia utente dei permessi |
1323 1323
1324<h3 id="permissionresult">1324<h3 id="permissionresult">
1325 `PermissionResult`1325 `PermissionResult`
1326</h3>1326</h3>
1327 1327
1328Tipo di unione per i risultati del callback di autorizzazione.1328Tipo di unione per i risultati del callback dei permessi.
1329 1329
1330```python theme={null}1330```python theme={null}
1331PermissionResult = PermissionResultAllow | PermissionResultDeny1331PermissionResult = PermissionResultAllow | PermissionResultDeny
1335 `PermissionResultAllow`1335 `PermissionResultAllow`
1336</h3>1336</h3>
1337 1337
1338Risultato che indica che la chiamata dello strumento deve essere consentita.1338Risultato che indica che la chiamata allo strumento deve essere consentita.
1339 1339
1340```python theme={null}1340```python theme={null}
1341@dataclass1341@dataclass
1349| :- | :- | :- | :- |1349| :- | :- | :- | :- |
1350| `behavior` | `Literal["allow"]` | `"allow"` | Deve essere "allow" |1350| `behavior` | `Literal["allow"]` | `"allow"` | Deve essere "allow" |
1351| `updated_input` | `dict[str, Any] \| None` | `None` | Input modificato da utilizzare al posto dell'originale |1351| `updated_input` | `dict[str, Any] \| None` | `None` | Input modificato da utilizzare al posto dell'originale |
1352| `updated_permissions` | `list[PermissionUpdate] \| None` | `None` | Aggiornamenti delle autorizzazioni da applicare |1352| `updated_permissions` | `list[PermissionUpdate] \| None` | `None` | Aggiornamenti dei permessi da applicare |
1353 1353
1354<h3 id="permissionresultdeny">1354<h3 id="permissionresultdeny">
1355 `PermissionResultDeny`1355 `PermissionResultDeny`
1356</h3>1356</h3>
1357 1357
1358Risultato che indica che la chiamata dello strumento deve essere negata.1358Risultato che indica che la chiamata allo strumento deve essere negata.
1359 1359
1360```python theme={null}1360```python theme={null}
1361@dataclass1361@dataclass
1375 `PermissionUpdate`1375 `PermissionUpdate`
1376</h3>1376</h3>
1377 1377
1378Configurazione per l'aggiornamento delle autorizzazioni a livello di programmazione.1378Configurazione per l'aggiornamento dei permessi a livello di programmazione.
1379 1379
1380```python theme={null}1380```python theme={null}
1381@dataclass1381@dataclass
1399 1399
1400| Campo | Tipo | Descrizione |1400| Campo | Tipo | Descrizione |
1401| :- | :- | :- |1401| :- | :- | :- |
1402| `type` | `Literal[...]` | Il tipo di operazione di aggiornamento delle autorizzazioni |1402| `type` | `Literal[...]` | Il tipo di operazione di aggiornamento dei permessi |
1403| `rules` | `list[PermissionRuleValue] \| None` | Regole per le operazioni add/replace/remove |1403| `rules` | `list[PermissionRuleValue] \| None` | Regole per le operazioni add/replace/remove |
1404| `behavior` | `Literal["allow", "deny", "ask"] \| None` | Comportamento per le operazioni basate su regole |1404| `behavior` | `Literal["allow", "deny", "ask"] \| None` | Comportamento per le operazioni basate su regole |
1405| `mode` | `PermissionMode \| None` | Modalità per l'operazione setMode |1405| `mode` | `PermissionMode \| None` | Modalità per l'operazione setMode |
1406| `directories` | `list[str] \| None` | Directory per le operazioni add/remove directory |1406| `directories` | `list[str] \| None` | Directory per le operazioni add/remove directory |
1407| `destination` | `Literal[...] \| None` | Dove applicare l'aggiornamento delle autorizzazioni |1407| `destination` | `Literal[...] \| None` | Dove applicare l'aggiornamento dei permessi |
1408 1408
1409<h3 id="permissionrulevalue">1409<h3 id="permissionrulevalue">
1410 `PermissionRuleValue`1410 `PermissionRuleValue`
1411</h3>1411</h3>
1412 1412
1413Una regola da aggiungere, sostituire o rimuovere in un aggiornamento delle autorizzazioni.1413Una regola da aggiungere, sostituire o rimuovere in un aggiornamento dei permessi.
1414 1414
1415```python theme={null}1415```python theme={null}
1416@dataclass1416@dataclass
1435 `ThinkingConfig`1435 `ThinkingConfig`
1436</h3>1436</h3>
1437 1437
1438Controlla il comportamento del pensiero esteso. Un'unione di tre configurazioni:1438Controlla il comportamento del ragionamento esteso. Un'unione di tre configurazioni:
1439 1439
1440```python theme={null}1440```python theme={null}
1441ThinkingDisplay = Literal["summarized", "omitted"]1441ThinkingDisplay = Literal["summarized", "omitted"]
1461 1461
1462| Variante | Campi | Descrizione |1462| Variante | Campi | Descrizione |
1463| :- | :- | :- |1463| :- | :- | :- |
1464| `adaptive` | `type`, `display` | Claude decide adattivamente quando pensare |1464| `adaptive` | `type`, `display` | Claude decide in modo adattivo quando ragionare |
1465| `enabled` | `type`, `budget_tokens`, `display` | Abilita il pensiero con un budget di token specifico |1465| `enabled` | `type`, `budget_tokens`, `display` | Abilita il ragionamento con un budget di token specifico |
1466| `disabled` | `type` | Disabilita il pensiero |1466| `disabled` | `type` | Disabilita il ragionamento |
1467 1467
1468Il 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 negli output [`ThinkingBlock`](#thinkingblock). Claude Code non invia `display` ad Amazon Bedrock o alla piattaforma agente di Google Cloud, quindi su quei provider Opus 4.7 e versioni successive restituiscono output `ThinkingBlock` vuoti anche quando imposti `display` a `"summarized"`.1468Il campo opzionale `display` controlla se il testo del ragionamento 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 del ragionamento negli output [`ThinkingBlock`](#thinkingblock). Claude Code omette `display` dalle richieste verso alcuni provider, come Amazon Bedrock e l'Agent Platform di Google Cloud. Su quei provider, Opus 4.7 e versioni successive restituiscono output `ThinkingBlock` vuoti anche quando imposti `display` a `"summarized"`.
1469 1469
1470Poiché queste sono classi `TypedDict`, sono dicts semplici in fase di esecuzione. Costruiscile come letterali dict o chiama la classe come costruttore; entrambi producono un `dict`. Accedi ai campi con `config["budget_tokens"]`, non `config.budget_tokens`:1470Poiché queste sono classi `TypedDict`, sono dict semplici in fase di esecuzione. Costruiscile come letterali dict o chiama la classe come un costruttore; entrambi producono un `dict`. Accedi ai campi con `config["budget_tokens"]`, non `config.budget_tokens`:
1471 1471
1472```python theme={null}1472```python theme={null}
1473from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled1473from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled
1577 `McpServerStatusConfig`1577 `McpServerStatusConfig`
1578</h3>1578</h3>
1579 1579
1580La configurazione di un server MCP come riportato da [`get_mcp_status()`](#methods). Questa è l'unione di tutte le varianti di trasporto [`McpServerConfig`](#mcpserverconfig) più una variante di output-only `claudeai-proxy` per i server proxy attraverso claude.ai.1580La configurazione di un server MCP come riportata da [`get_mcp_status()`](#methods). Questa è l'unione di tutte le varianti di trasporto di [`McpServerConfig`](#mcpserverconfig) più una variante di solo output `claudeai-proxy` per i server instradati tramite proxy attraverso claude.ai.
1581 1581
1582```python theme={null}1582```python theme={null}
1583McpServerStatusConfig = (1583McpServerStatusConfig = (
1589)1589)
1590```1590```
1591 1591
1592`McpSdkServerConfigStatus` è la forma serializzabile di [`McpSdkServerConfig`](#mcpsdkserverconfig) con solo i campi `type` (`"sdk"`) e `name` (`str`); l'`instance` in-process viene omesso. `McpClaudeAIProxyServerConfig` ha i campi `type` (`"claudeai-proxy"`), `url` (`str`), e `id` (`str`).1592`McpSdkServerConfigStatus` è la forma serializzabile di [`McpSdkServerConfig`](#mcpsdkserverconfig) con solo i campi `type` (`"sdk"`) e `name` (`str`); l'`instance` in-process viene omessa. `McpClaudeAIProxyServerConfig` ha i campi `type` (`"claudeai-proxy"`), `url` (`str`), e `id` (`str`).
1593 1593
1594<h3 id="mcpstatusresponse">1594<h3 id="mcpstatusresponse">
1595 `McpStatusResponse`1595 `McpStatusResponse`
1596</h3>1596</h3>
1597 1597
1598Risposta da [`ClaudeSDKClient.get_mcp_status()`](#methods). Avvolge l'elenco degli stati del server sotto la chiave `mcpServers`.1598Risposta da [`ClaudeSDKClient.get_mcp_status()`](#methods). Racchiude l'elenco degli stati dei server sotto la chiave `mcpServers`.
1599 1599
1600```python theme={null}1600```python theme={null}
1601class McpStatusResponse(TypedDict):1601class McpStatusResponse(TypedDict):
1622| Campo | Tipo | Descrizione |1622| Campo | Tipo | Descrizione |
1623| :- | :- | :- |1623| :- | :- | :- |
1624| `name` | `str` | Nome del server |1624| `name` | `str` | Nome del server |
1625| `status` | `str` | Uno di `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, o `"disabled"` |1625| `status` | `str` | Uno tra `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, o `"disabled"` |
1626| `serverInfo` | `dict` (opzionale) | Nome e versione del server (`{"name": str, "version": str}`) |1626| `serverInfo` | `dict` (opzionale) | Nome e versione del server (`{"name": str, "version": str}`) |
1627| `error` | `str` (opzionale) | Messaggio di errore se il server non si è connesso |1627| `error` | `str` (opzionale) | Messaggio di errore se il server non si è connesso |
1628| `config` | [`McpServerStatusConfig`](#mcpserverstatusconfig) (opzionale) | Configurazione del server. Stessa forma di [`McpServerConfig`](#mcpserverconfig) (stdio, SSE, HTTP, o SDK), più una variante `claudeai-proxy` per i server connessi tramite claude.ai |1628| `config` | [`McpServerStatusConfig`](#mcpserverstatusconfig) (opzionale) | Configurazione del server. Stessa forma di [`McpServerConfig`](#mcpserverconfig) (stdio, SSE, HTTP, o SDK), più una variante `claudeai-proxy` per i server connessi tramite claude.ai |
1633 `ContextUsageResponse`1633 `ContextUsageResponse`
1634</h3>1634</h3>
1635 1635
1636Risposta da [`ClaudeSDKClient.get_context_usage()`](#methods). Questo è lo stesso payload che Claude Code renderizza per il comando `/context` in una sessione interattiva, quindi insieme ai conteggi dei token contiene campi di visualizzazione come `color` e `gridRows` che Claude Code utilizza per disegnare la griglia di utilizzo `/context`.1636Risposta da [`ClaudeSDKClient.get_context_usage()`](#methods). Questo è lo stesso payload che Claude Code visualizza per il comando `/context` in una sessione interattiva, quindi insieme ai conteggi dei token contiene campi di visualizzazione come `color` e `gridRows` che Claude Code utilizza per disegnare la griglia di utilizzo di `/context`.
1637 1637
1638Claude Code costruisce questo payload inviando diverse richieste all'API di [token-counting](https://platform.claude.com/docs/en/build-with-claude/token-counting). Queste richieste non appaiono nel flusso di messaggi, quindi il tracciamento dei costi che legge il flusso non le vedrà. Sull'API Anthropic, il conteggio dei token non viene fatturato.1638Claude Code costruisce questo payload inviando diverse richieste all'API di [token-counting](https://platform.claude.com/docs/en/build-with-claude/token-counting). Queste richieste non appaiono nel flusso di messaggi, quindi il tracciamento dei costi che legge il flusso non le vedrà. Sull'API Anthropic, il conteggio dei token non viene fatturato.
1639 1639
1660 apiUsage: NotRequired[dict[str, Any] | None]1660 apiUsage: NotRequired[dict[str, Any] | None]
1661```1661```
1662 1662
1663Ogni voce `ContextUsageCategory` contiene `name`, `tokens`, `color` e un flag opzionale `isDeferred`. `totalTokens` è l'utilizzo del contesto corrente della sessione, e `maxTokens` è la finestra rispetto alla quale viene misurato l'utilizzo. Quella finestra è la finestra di contesto del modello, o la finestra di auto-compattazione inferiore quando se ne applica una, e `rawMaxTokens` contiene lo stesso valore di `maxTokens`. `apiUsage` contiene l'utilizzo dalla risposta API più recente, non un totale in esecuzione per la sessione. Claude Code lascia i campi opzionali `deferredBuiltinTools`, `systemTools` e `systemPromptSections` non impostati, quindi aspettati che siano assenti anche se il tipo li dichiara.1663Ogni voce `ContextUsageCategory` contiene `name`, `tokens`, `color` e un flag opzionale `isDeferred`. `totalTokens` è l'utilizzo del contesto corrente della sessione, e `maxTokens` è la finestra rispetto alla quale viene misurato l'utilizzo. Quella finestra è la finestra di contesto del modello, o la finestra di compattazione automatica inferiore quando se ne applica una, e `rawMaxTokens` contiene lo stesso valore di `maxTokens`. `apiUsage` contiene l'utilizzo dalla risposta API più recente, non un totale progressivo per la sessione. Claude Code lascia non impostate le chiavi opzionali `deferredBuiltinTools`, `systemTools` e `systemPromptSections`, quindi aspettati che siano assenti anche se il tipo le dichiara.
1664 1664
1665<h3 id="sdkpluginconfig">1665<h3 id="sdkpluginconfig">
1666 `SdkPluginConfig`1666 `SdkPluginConfig`
1738 1738
1739L'SDK passa `tool_use_result` attraverso dalla CLI senza modifiche. Per uno strumento su un server MCP esterno il cui risultato contiene blocchi `resource_link`, il dict ha una chiave `resourceLinks` che contiene un elenco di dict con le chiavi del tipo TypeScript [`SDKMcpResourceLink`](/docs/it/agent-sdk/typescript#sdkmcpresourcelink). Claude riceve ogni link come una riga di testo nel risultato dello strumento. Per renderizzare i file restituiti dal server, leggi `resourceLinks` invece di analizzare quel testo. La chiave `resourceLinks` richiede Python Agent SDK 0.2.150 o successivo e Claude Code v2.1.257 o successivo; la CLI fornita con quella versione dell'SDK soddisfa il requisito di Claude Code.1739L'SDK passa `tool_use_result` attraverso dalla CLI senza modifiche. Per uno strumento su un server MCP esterno il cui risultato contiene blocchi `resource_link`, il dict ha una chiave `resourceLinks` che contiene un elenco di dict con le chiavi del tipo TypeScript [`SDKMcpResourceLink`](/docs/it/agent-sdk/typescript#sdkmcpresourcelink). Claude riceve ogni link come una riga di testo nel risultato dello strumento. Per renderizzare i file restituiti dal server, leggi `resourceLinks` invece di analizzare quel testo. La chiave `resourceLinks` richiede Python Agent SDK 0.2.150 o successivo e Claude Code v2.1.257 o successivo; la CLI fornita con quella versione dell'SDK soddisfa il requisito di Claude Code.
1740 1740
1741La CLI omette la chiave quando il risultato non ha link e sui risultati dei subagenti. La CLI mantiene al massimo 50 link per risultato e smette di aggiungere link una volta che l'elenco raggiunge 64 KiB di JSON serializzato. Uno strumento che definisci in-process con [`tool()`](#tool) non produce mai la chiave, perché l'SDK appiattisce i suoi blocchi `resource_link` a testo prima che la CLI veda il risultato.1741La CLI omette la chiave quando il risultato non ha link e sui risultati dei subagent. La CLI mantiene al massimo 50 link per risultato e smette di aggiungere link una volta che l'elenco raggiunge 64 KiB di JSON serializzato. Uno strumento che definisci in-process con [`tool()`](#tool) non produce mai la chiave, perché l'SDK appiattisce i suoi blocchi `resource_link` a testo prima che la CLI veda il risultato.
1742 1742
1743<h3 id="assistantmessage">1743<h3 id="assistantmessage">
1744 `AssistantMessage`1744 `AssistantMessage`
1847* `terminal_reason`: perché il ciclo di query è terminato, come `"completed"`, `"max_turns"`, `"api_error"`, `"aborted_streaming"`, o `"aborted_tools"`. Un valore di `"aborted_streaming"` o `"aborted_tools"` significa che il turno è stato interrotto prima del completamento. Le cause comuni sono [`interrupt()`](#claudesdkclient) e un callback di permesso che restituisce [`PermissionResultDeny`](#permissionresultdeny) con `interrupt=True`. `None` su versioni CLI che precedono il campo, su risultati da comandi locali come `/voice` o `/usage`, che bypassano il ciclo di query, o su risultati di errore sintetizzati emessi quando la sessione fallisce fatalmente. Rispecchia il [`SDKResultMessage.terminal_reason`](/docs/it/agent-sdk/typescript#sdkresultmessage) dell'SDK TypeScript, che elenca l'insieme completo di valori.1847* `terminal_reason`: perché il ciclo di query è terminato, come `"completed"`, `"max_turns"`, `"api_error"`, `"aborted_streaming"`, o `"aborted_tools"`. Un valore di `"aborted_streaming"` o `"aborted_tools"` significa che il turno è stato interrotto prima del completamento. Le cause comuni sono [`interrupt()`](#claudesdkclient) e un callback di permesso che restituisce [`PermissionResultDeny`](#permissionresultdeny) con `interrupt=True`. `None` su versioni CLI che precedono il campo, su risultati da comandi locali come `/voice` o `/usage`, che bypassano il ciclo di query, o su risultati di errore sintetizzati emessi quando la sessione fallisce fatalmente. Rispecchia il [`SDKResultMessage.terminal_reason`](/docs/it/agent-sdk/typescript#sdkresultmessage) dell'SDK TypeScript, che elenca l'insieme completo di valori.
1848* `origin`: origine del messaggio utente che ha attivato questo turno. In [modalità input streaming](/docs/it/agent-sdk/streaming-vs-single-mode), controlla questo per distinguere il risultato del tuo prompt, dove `origin` è `None` o `{"kind": "human"}`, dal risultato di un turno iniettato come una notifica di attività in background. Richiede Python Agent SDK 0.2.137 o successivo.1848* `origin`: origine del messaggio utente che ha attivato questo turno. In [modalità input streaming](/docs/it/agent-sdk/streaming-vs-single-mode), controlla questo per distinguere il risultato del tuo prompt, dove `origin` è `None` o `{"kind": "human"}`, dal risultato di un turno iniettato come una notifica di attività in background. Richiede Python Agent SDK 0.2.137 o successivo.
1849 1849
1850Il dict `usage` copre solo il ciclo dell'agente principale ed esclude i subagenti e altre chiamate di modello nidificate o ausiliarie. In [modalità input streaming](/docs/it/agent-sdk/streaming-vs-single-mode), i valori sono per turno. Preferisci `model_usage` per la contabilità dei token e dei costi. Il dict `usage` contiene le seguenti chiavi quando presenti:1850Il dict `usage` copre solo il ciclo dell'agente principale ed esclude i subagent e altre chiamate di modello nidificate o ausiliarie. In [modalità input streaming](/docs/it/agent-sdk/streaming-vs-single-mode), i valori sono per turno. Preferisci `model_usage` per la contabilità dei token e dei costi. Il dict `usage` contiene le seguenti chiavi quando presenti:
1851 1851
1852| Chiave | Tipo | Descrizione |1852| Chiave | Tipo | Descrizione |
1853| - | - | - |1853| - | - | - |
1854| `input_tokens` | `int` | Token di input consumati dal ciclo dell'agente di livello superiore. [I token dei subagenti non sono inclusi](/docs/it/agent-sdk/cost-tracking#get-the-total-cost-of-a-query); usa `model_usage` per la contabilità dell'intero albero. |1854| `input_tokens` | `int` | Token di input consumati dal ciclo dell'agente di livello superiore. [I token dei subagent non sono inclusi](/docs/it/agent-sdk/cost-tracking#get-the-total-cost-of-a-query); usa `model_usage` per la contabilità dell'intero albero. |
1855| `output_tokens` | `int` | Token di output generati dal ciclo dell'agente di livello superiore. I token dei subagenti non sono inclusi. |1855| `output_tokens` | `int` | Token di output generati dal ciclo dell'agente di livello superiore. I token dei subagent non sono inclusi. |
1856| `cache_creation_input_tokens` | `int` | Token utilizzati per creare nuove voci di cache. |1856| `cache_creation_input_tokens` | `int` | Token utilizzati per creare nuove voci di cache. |
1857| `cache_read_input_tokens` | `int` | Token letti dalle voci di cache esistenti. |1857| `cache_read_input_tokens` | `int` | Token letti dalle voci di cache esistenti. |
1858 1858
1859Il dict `model_usage` mappa i nomi dei modelli all'utilizzo per modello. Copre ogni chiamata di modello effettuata attraverso la pipeline di query: 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 permessi e le richieste di conteggio dei token, sono escluse da `model_usage`. Tratta `model_usage` come una stima, non come un estratto conto di fatturazione.1859Il dict `model_usage` mappa i nomi dei modelli all'utilizzo per modello. Copre ogni chiamata di modello effettuata attraverso la pipeline di query: il ciclo principale, i subagent e le chiamate interne come la compattazione e gli agenti Workflow. Le chiamate helper al di fuori di quella pipeline, come il classificatore di permessi e le richieste di conteggio dei token, sono escluse da `model_usage`. Tratta `model_usage` come una stima, non come un estratto conto di fatturazione.
1860 1860
1861In [modalità input streaming](/docs/it/agent-sdk/streaming-vs-single-mode), `model_usage` e `total_cost_usd` sono cumulativi tra i turni, quindi leggi il risultato più recente piuttosto che sommare tra i risultati. Una chiamata che riprende una sessione conta anche i [totali ripristinati dalle chiamate precedenti della sessione](/docs/it/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls). Vedi [Traccia i costi in modalità input streaming](/docs/it/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode) per i ripristini e [Recupera i totali dopo un crash della sessione](/docs/it/agent-sdk/cost-tracking#recover-totals-after-a-session-crash) per i risultati azzerati.1861In [modalità input streaming](/docs/it/agent-sdk/streaming-vs-single-mode), `model_usage` e `total_cost_usd` sono cumulativi tra i turni, quindi leggi il risultato più recente piuttosto che sommare tra i risultati. Una chiamata che riprende una sessione conta anche i [totali ripristinati dalle chiamate precedenti della sessione](/docs/it/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls). Vedi [Traccia i costi in modalità input streaming](/docs/it/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode) per i ripristini e [Recupera i totali dopo un crash della sessione](/docs/it/agent-sdk/cost-tracking#recover-totals-after-a-session-crash) per i risultati azzerati.
1862 1862
1869| `cacheReadInputTokens` | `int` | Token di lettura della cache per questo modello. |1869| `cacheReadInputTokens` | `int` | Token di lettura della cache per questo modello. |
1870| `cacheCreationInputTokens` | `int` | Token di creazione della cache per questo modello. |1870| `cacheCreationInputTokens` | `int` | Token di creazione della cache per questo modello. |
1871| `webSearchRequests` | `int` | Richieste di ricerca web effettuate da questo modello. |1871| `webSearchRequests` | `int` | Richieste di ricerca web effettuate da questo modello. |
1872| `thinkingTokens` | `int` | Token di thinking generati da questo modello, già contati in `outputTokens`. Assenti fino a quando un turno non viene eseguito su una versione di Claude Code che lo registra, e non dichiarati sul TypedDict, quindi leggilo con `.get()`. Richiede Python Agent SDK 0.2.150 o successivo, il cui CLI fornito lo registra. |1872| `thinkingTokens` | `int` | Token di ragionamento generati da questo modello, già contati in `outputTokens`. Assenti fino a quando un turno non viene eseguito su una versione di Claude Code che lo registra, e non dichiarati sul TypedDict, quindi leggilo con `.get()`. Richiede Python Agent SDK 0.2.150 o successivo, il cui CLI fornito lo registra. |
1873| `costUSD` | `float` | Costo stimato in USD per questo modello, calcolato lato client. Vedi [Traccia costo e utilizzo](/docs/it/agent-sdk/cost-tracking) per avvertenze di fatturazione. |1873| `costUSD` | `float` | Costo stimato in USD per questo modello, calcolato lato client. Vedi [Traccia costo e utilizzo](/docs/it/agent-sdk/cost-tracking) per avvertenze di fatturazione. |
1874| `contextWindow` | `int` | Dimensione della finestra di contesto per questo modello. |1874| `contextWindow` | `int` | Dimensione della finestra di contesto per questo modello. |
1875| `maxOutputTokens` | `int` | Limite massimo di token di output per questo modello. |1875| `maxOutputTokens` | `int` | Limite massimo di token di output per questo modello. |
1876| `canonicalModel` | `str` | ID del modello canonico utilizzato per la ricerca dei prezzi. Può differire dalla stringa del modello grezzo per cui la voce è codificata, come un ID specifico del provider o un alias. Non sempre presente. |1876| `canonicalModel` | `str` | ID del modello canonico utilizzato per la ricerca dei prezzi. Può differire dalla stringa del modello grezzo per cui la voce è codificata, come un ID specifico del provider o un alias. Non sempre presente. |
1877| `provider` | `str` | Provider API che ha servito questo modello, come `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle`, o `gateway`. Non sempre presente. |1877| `provider` | `str` | Provider API che ha servito questo modello, come `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle`, o `gateway`. Non sempre presente. |
1878| `costBasis` | `str` | Tabella dei prezzi usata per calcolare il prezzo dell'ultima richiesta di questo modello: `list` per il prezzo di listino, `managed` per una tabella [`modelPricing`](/docs/it/settings-reference#modelpricing), o `unknown` quando nessuna delle due corrispondeva all'ID del modello. Non sempre presente, e non dichiarato sul TypedDict, quindi leggilo con `.get()`. Richiede Claude Code v2.1.246 o successivo. |
1878 1879
1879<h3 id="streamevent">1880<h3 id="streamevent">
1880 `StreamEvent`1881 `StreamEvent`
1896| `uuid` | `str` | Identificatore univoco per questo evento |1897| `uuid` | `str` | Identificatore univoco per questo evento |
1897| `session_id` | `str` | Identificatore di sessione |1898| `session_id` | `str` | Identificatore di sessione |
1898| `event` | `dict[str, Any]` | I dati dell'evento di flusso dell'API Claude grezzo |1899| `event` | `dict[str, Any]` | I dati dell'evento di flusso dell'API Claude grezzo |
1899| `parent_tool_use_id` | `str \| None` | Sempre `None`. Gli eventi di flusso vengono emessi solo per la sessione principale. Per l'attribuzione dei subagenti, utilizza messaggi completi come [`AssistantMessage`](#assistantmessage) |1900| `parent_tool_use_id` | `str \| None` | Sempre `None`. Gli eventi di flusso vengono emessi solo per la sessione principale. Per l'attribuzione dei subagent, utilizza messaggi completi come [`AssistantMessage`](#assistantmessage) |
1900 1901
1901<h3 id="ratelimitevent">1902<h3 id="ratelimitevent">
1902 `RateLimitEvent`1903 `RateLimitEvent`
1903</h3>1904</h3>
1904 1905
1905Emesso quando lo stato del limite di velocità cambia (ad esempio, da `"allowed"` a `"allowed_warning"`). Usalo per avvertire gli utenti prima che raggiungano un limite rigido, o per fare backoff quando lo stato è `"rejected"`.1906Emesso quando lo stato del rate limit cambia (ad esempio, da `"allowed"` a `"allowed_warning"`). Usalo per avvertire gli utenti prima che raggiungano un limite rigido, o per fare backoff quando lo stato è `"rejected"`.
1906 1907
1907```python theme={null}1908```python theme={null}
1908@dataclass1909@dataclass
1914 1915
1915| Campo | Tipo | Descrizione |1916| Campo | Tipo | Descrizione |
1916| :- | :- | :- |1917| :- | :- | :- |
1917| `rate_limit_info` | [`RateLimitInfo`](#ratelimitinfo) | Stato del limite di velocità corrente |1918| `rate_limit_info` | [`RateLimitInfo`](#ratelimitinfo) | Stato corrente del rate limit |
1918| `uuid` | `str` | Identificatore di evento univoco |1919| `uuid` | `str` | Identificatore di evento univoco |
1919| `session_id` | `str` | Identificatore di sessione |1920| `session_id` | `str` | Identificatore di sessione |
1920 1921
1922 `RateLimitInfo`1923 `RateLimitInfo`
1923</h3>1924</h3>
1924 1925
1925Stato del limite di velocità trasportato da [`RateLimitEvent`](#ratelimitevent).1926Stato del rate limit trasportato da [`RateLimitEvent`](#ratelimitevent).
1926 1927
1927```python theme={null}1928```python theme={null}
1928RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]1929RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]
1946| Campo | Tipo | Descrizione |1947| Campo | Tipo | Descrizione |
1947| :- | :- | :- |1948| :- | :- | :- |
1948| `status` | `RateLimitStatus` | Stato corrente, uno di `"allowed"`, `"allowed_warning"`, o `"rejected"`. `"allowed_warning"` significa avvicinarsi al limite; `"rejected"` significa che il limite è stato raggiunto |1949| `status` | `RateLimitStatus` | Stato corrente, uno di `"allowed"`, `"allowed_warning"`, o `"rejected"`. `"allowed_warning"` significa avvicinarsi al limite; `"rejected"` significa che il limite è stato raggiunto |
1949| `resets_at` | `int \| None` | Timestamp Unix quando la finestra del limite di velocità si ripristina |1950| `resets_at` | `int \| None` | Timestamp Unix quando la finestra del rate limit si ripristina |
1950| `rate_limit_type` | `RateLimitType \| None` | Quale finestra del limite di velocità si applica |1951| `rate_limit_type` | `RateLimitType \| None` | Quale finestra del rate limit si applica |
1951| `utilization` | `float \| None` | Frazione del limite di velocità consumato (0.0 a 1.0) |1952| `utilization` | `float \| None` | Frazione del rate limit consumata (0.0 a 1.0) |
1952| `overage_status` | `RateLimitStatus \| None` | Stato dell'utilizzo di overage pay-as-you-go, se applicabile |1953| `overage_status` | `RateLimitStatus \| None` | Stato dell'utilizzo di overage pay-as-you-go, se applicabile |
1953| `overage_resets_at` | `int \| None` | Timestamp Unix quando la finestra di overage si ripristina |1954| `overage_resets_at` | `int \| None` | Timestamp Unix quando la finestra di overage si ripristina |
1954| `overage_disabled_reason` | `str \| None` | Perché l'overage non è disponibile, se lo stato è `"rejected"` |1955| `overage_disabled_reason` | `str \| None` | Perché l'overage non è disponibile, se lo stato è `"rejected"` |
1978 `TaskStartedMessage`1979 `TaskStartedMessage`
1979</h3>1980</h3>
1980 1981
1981Emesso quando un'attività in background inizia. Un'attività in background è qualsiasi cosa tracciata al di fuori del turno principale: un comando Bash in background, un watch [Monitor](#monitor), un subagente generato tramite lo strumento Agent, o un agente remoto. Il campo `task_type` ti dice quale. Questo nome non è correlato al rinomina dello strumento `Task`-to-`Agent`.1982Emesso quando un'attività in background inizia. Un'attività in background è qualsiasi cosa tracciata al di fuori del turno principale: un comando Bash in background, un watch [Monitor](#monitor), un subagent generato tramite lo strumento Agent, o un agente remoto. Il campo `task_type` ti dice quale. Questo nome non è correlato alla rinomina dello strumento da `Task` ad `Agent`.
1982 1983
1983```python theme={null}1984```python theme={null}
1984@dataclass1985@dataclass
2045 `TaskNotificationMessage`2046 `TaskNotificationMessage`
2046</h3>2047</h3>
2047 2048
2048Emesso quando un'attività in background si completa, fallisce o viene interrotta. Le attività in background includono comandi Bash `run_in_background`, watch Monitor e subagenti in background.2049Emesso quando un'attività in background si completa, fallisce o viene interrotta. Le attività in background includono comandi Bash `run_in_background`, watch Monitor e subagent in background.
2049 2050
2050```python theme={null}2051```python theme={null}
2051@dataclass2052@dataclass
2071| `tool_use_id` | `str \| None` | ID di utilizzo dello strumento associato |2072| `tool_use_id` | `str \| None` | ID di utilizzo dello strumento associato |
2072| `usage` | `TaskUsage \| None` | Utilizzo dei token finale per l'attività |2073| `usage` | `TaskUsage \| None` | Utilizzo dei token finale per l'attività |
2073 2074
2074Quando la CLI [sposta una lunga chiamata di strumento MCP in background](/docs/it/mcp#automatic-backgrounding-of-long-tool-calls), il risultato dello strumento per quella chiamata contiene solo un placeholder e il risultato reale della chiamata arriva in questo messaggio. Su una notifica `"completed"` per tale chiamata, la CLI aggiunge una chiave `resource_links` che elenca i file restituiti dallo strumento per riferimento, con le stesse voci e limiti della chiave `resourceLinks` su [`UserMessage.tool_use_result`](#usermessage). La chiave `resource_links` richiede Python Agent SDK 0.2.150 o successivo e Claude Code v2.1.257 o successivo; la CLI fornita con quella versione dell'SDK soddisfa il requisito di Claude Code.2075Quando la CLI [sposta una lunga chiamata a uno strumento MCP in background](/docs/it/mcp#automatic-backgrounding-of-long-tool-calls), il risultato dello strumento per quella chiamata contiene solo un placeholder e il risultato reale della chiamata arriva in questo messaggio. Su una notifica `"completed"` per tale chiamata, la CLI aggiunge una chiave `resource_links` che elenca i file restituiti dallo strumento per riferimento, con le stesse voci e limiti della chiave `resourceLinks` su [`UserMessage.tool_use_result`](#usermessage). La chiave `resource_links` richiede Python Agent SDK 0.2.150 o successivo e Claude Code v2.1.257 o successivo; la CLI fornita con quella versione dell'SDK soddisfa il requisito di Claude Code.
2075 2076
2076La dataclass non ha un campo per `resource_links`. Leggilo dal dict `data` che il messaggio eredita da [`SystemMessage`](#systemmessage): `message.data.get("resource_links")`. Abbina la notifica alla chiamata con `tool_use_id`. La CLI omette la chiave quando il risultato non aveva link e su notifiche per attività che non sono chiamate di strumento MCP.2077La dataclass non ha un campo per `resource_links`. Leggilo dal dict `data` che il messaggio eredita da [`SystemMessage`](#systemmessage): `message.data.get("resource_links")`. Abbina la notifica alla chiamata con `tool_use_id`. La CLI omette la chiave quando il risultato non aveva link e su notifiche per attività che non sono chiamate a strumenti MCP.
2077 2078
2078<h2 id="content-block-types">2079<h2 id="content-block-types">
2079 Tipi di blocco di contenuto2080 Tipi di blocco di contenuto
2153 Tipi di errore2154 Tipi di errore
2154</h2>2155</h2>
2155 2156
2156I tipi di seguito definiscono cosa il vostro codice cattura. Per le voci associate ai messaggi di errore che questi tipi generano, con la causa e la correzione per ciascuno, consultate [Troubleshooting](/docs/it/agent-sdk/troubleshooting).2157I tipi di seguito definiscono cosa il tuo codice cattura. Per le voci associate ai messaggi di errore che questi tipi generano, con la causa e la correzione per ciascuno, consulta [Risoluzione dei problemi](/docs/it/agent-sdk/troubleshooting).
2157 2158
2158<h3 id="claudesdkerror">2159<h3 id="claudesdkerror">
2159 `ClaudeSDKError`2160 `ClaudeSDKError`
2166 """Base error for Claude SDK."""2167 """Base error for Claude SDK."""
2167```2168```
2168 2169
2169Quando una singola `query()` termina con un risultato di errore, ad esempio un errore di limite di turni, l'SDK genera un [`ResultError`](#resulterror) dopo aver restituito il messaggio di risultato finale. Le versioni di Python Agent SDK precedenti alla 0.2.140 generavano una semplice `Exception` che non era una sottoclasse di `ClaudeSDKError`.2170Quando una singola `query()` termina con un risultato di errore, ad esempio un errore di limite di turni, l'SDK genera un [`ResultError`](#resulterror).
2170 2171
2171<h3 id="clinotfounderror">2172<h3 id="clinotfounderror">
2172 `CLINotFoundError`2173 `CLINotFoundError`
2216 `ResultError`2217 `ResultError`
2217</h3>2218</h3>
2218 2219
2219Generato dopo il [`ResultMessage`](#resultmessage) finale quando il processo Claude Code esce perché l'esecuzione è terminata con un risultato di errore, come un errore di limite di turni o un errore API. `ResultError` è una sottoclasse di `ProcessError`, quindi un gestore `except ProcessError` esistente lo cattura anche. I suoi attributi contengono i campi di quel messaggio di risultato, quindi potete distinguere il motivo del fallimento dell'esecuzione senza analizzare il testo del messaggio. Richiede Python Agent SDK 0.2.140 o successivo.2220Generato quando il processo Claude Code esce perché l'esecuzione è terminata con un [messaggio di risultato](#resultmessage) di errore, come un errore di limite di turni o un errore API. `ResultError` è una sottoclasse di `ProcessError`, quindi un gestore `except ProcessError` esistente lo cattura anche. I suoi attributi contengono i campi di quel messaggio di risultato, quindi puoi distinguere il motivo del fallimento dell'esecuzione senza analizzare il testo del messaggio. Richiede Python Agent SDK 0.2.140 o successivo.
2220 2221
2221```python theme={null}2222```python theme={null}
2222class ResultError(ProcessError):2223class ResultError(ProcessError):
2223 subtype: str | None # "error_max_turns", "error_during_execution", ...; "success" quando l'esecuzione è terminata su una richiesta non riuscita2224 subtype: str | None # "error_max_turns", "error_during_execution", ...; "success" when the run ended on a failed request
2224 errors: list[str] # un elenco vuoto quando il messaggio di risultato non ne ha segnalati2225 errors: list[str] # an empty list when the result message reported none
2225 result: str | None2226 result: str | None
2226 api_error_status: int | None2227 api_error_status: int | None
2227 terminal_reason: str | None # "max_turns", "api_error", ...; controllate questo prima di subtype2228 terminal_reason: str | None # "max_turns", "api_error", ...; check this before subtype
2228 session_id: str | None2229 session_id: str | None
2229 data: dict[str, Any] # il payload del messaggio di risultato grezzo2230 data: dict[str, Any] # the raw result message payload
2230```2231```
2231 2232
2232Per distinguere i fallimenti, controllate `terminal_reason` prima di `subtype`. Quando la richiesta finale fallisce, ad esempio su un errore API, Claude Code segnala `subtype` `"success"` con la causa in `terminal_reason`, ad esempio `"api_error"`; quando un limite che avete impostato termina l'esecuzione, come `max_turns` o `max_budget_usd`, segnala un `subtype` di tipo `error_*`.2233Per distinguere i fallimenti, controlla `terminal_reason` prima di `subtype`. Quando la richiesta finale fallisce, ad esempio su un errore API, Claude Code segnala `subtype` `"success"` con la causa in `terminal_reason`, ad esempio `"api_error"`; quando un limite che hai impostato termina l'esecuzione, come `max_turns` o `max_budget_usd`, segnala un `subtype` di tipo `error_*`.
2233 2234
2234<h3 id="clijsondecodeerror">2235<h3 id="clijsondecodeerror">
2235 `CLIJSONDecodeError`2236 `CLIJSONDecodeError`
2253 Tipi di Hook2254 Tipi di Hook
2254</h2>2255</h2>
2255 2256
2256Per una guida completa sull'utilizzo degli hooks con esempi e modelli comuni, vedi la [guida Hooks](/docs/it/agent-sdk/hooks).2257Per una guida completa sull'utilizzo degli hook con esempi e modelli comuni, vedi la [guida Hooks](/docs/it/agent-sdk/hooks).
2257 2258
2258<h3 id="hookevent">2259<h3 id="hookevent">
2259 `HookEvent`2260 `HookEvent`
2368| Campo | Tipo | Descrizione |2369| Campo | Tipo | Descrizione |
2369| :- | :- | :- |2370| :- | :- | :- |
2370| `session_id` | `str` | Identificatore di sessione corrente |2371| `session_id` | `str` | Identificatore di sessione corrente |
2371| `transcript_path` | `str` | Percorso al file di trascritto della sessione |2372| `transcript_path` | `str` | Percorso al file di trascrizione della sessione |
2372| `cwd` | `str` | Directory di lavoro corrente |2373| `cwd` | `str` | Directory di lavoro corrente |
2373| `permission_mode` | `str` (opzionale) | Modalità di autorizzazione corrente |2374| `permission_mode` | `str` (opzionale) | Modalità di permesso corrente |
2374 2375
2375<h3 id="pretoolusehookinput">2376<h3 id="pretoolusehookinput">
2376 `PreToolUseHookInput`2377 `PreToolUseHookInput`
2394| `tool_name` | `str` | Nome dello strumento che sta per essere eseguito |2395| `tool_name` | `str` | Nome dello strumento che sta per essere eseguito |
2395| `tool_input` | `dict[str, Any]` | Parametri di input per lo strumento |2396| `tool_input` | `dict[str, Any]` | Parametri di input per lo strumento |
2396| `tool_use_id` | `str` | Identificatore univoco per questo utilizzo dello strumento |2397| `tool_use_id` | `str` | Identificatore univoco per questo utilizzo dello strumento |
2397| `agent_id` | `str` (opzionale) | Identificatore del subagente, presente quando l'hook si attiva all'interno di un subagente |2398| `agent_id` | `str` (opzionale) | Identificatore del subagent, presente quando l'hook si attiva all'interno di un subagent |
2398| `agent_type` | `str` (opzionale) | Tipo di subagente, presente quando l'hook si attiva all'interno di un subagente |2399| `agent_type` | `str` (opzionale) | Tipo di subagent, presente quando l'hook si attiva all'interno di un subagent |
2399 2400
2400<h3 id="posttoolusehookinput">2401<h3 id="posttoolusehookinput">
2401 `PostToolUseHookInput`2402 `PostToolUseHookInput`
2421| `tool_input` | `dict[str, Any]` | Parametri di input che sono stati utilizzati |2422| `tool_input` | `dict[str, Any]` | Parametri di input che sono stati utilizzati |
2422| `tool_response` | `Any` | Risposta dall'esecuzione dello strumento |2423| `tool_response` | `Any` | Risposta dall'esecuzione dello strumento |
2423| `tool_use_id` | `str` | Identificatore univoco per questo utilizzo dello strumento |2424| `tool_use_id` | `str` | Identificatore univoco per questo utilizzo dello strumento |
2424| `agent_id` | `str` (opzionale) | Identificatore del subagente, presente quando l'hook si attiva all'interno di un subagente |2425| `agent_id` | `str` (opzionale) | Identificatore del subagent, presente quando l'hook si attiva all'interno di un subagent |
2425| `agent_type` | `str` (opzionale) | Tipo di subagente, presente quando l'hook si attiva all'interno di un subagente |2426| `agent_type` | `str` (opzionale) | Tipo di subagent, presente quando l'hook si attiva all'interno di un subagent |
2426 2427
2427<h3 id="posttoolusefailurehookinput">2428<h3 id="posttoolusefailurehookinput">
2428 `PostToolUseFailureHookInput`2429 `PostToolUseFailureHookInput`
2450| `tool_use_id` | `str` | Identificatore univoco per questo utilizzo dello strumento |2451| `tool_use_id` | `str` | Identificatore univoco per questo utilizzo dello strumento |
2451| `error` | `str` | Messaggio di errore dall'esecuzione fallita |2452| `error` | `str` | Messaggio di errore dall'esecuzione fallita |
2452| `is_interrupt` | `bool` (opzionale) | True quando il fallimento è arrivato a Claude Code come un'interruzione piuttosto che come un errore segnalato dallo strumento. L'annullamento di uno strumento in esecuzione con `interrupt()` non attiva questo hook; il risultato dello strumento contiene il messaggio di interruzione |2453| `is_interrupt` | `bool` (opzionale) | True quando il fallimento è arrivato a Claude Code come un'interruzione piuttosto che come un errore segnalato dallo strumento. L'annullamento di uno strumento in esecuzione con `interrupt()` non attiva questo hook; il risultato dello strumento contiene il messaggio di interruzione |
2453| `agent_id` | `str` (opzionale) | Identificatore del subagente, presente quando l'hook si attiva all'interno di un subagente |2454| `agent_id` | `str` (opzionale) | Identificatore del subagent, presente quando l'hook si attiva all'interno di un subagent |
2454| `agent_type` | `str` (opzionale) | Tipo di subagente, presente quando l'hook si attiva all'interno di un subagente |2455| `agent_type` | `str` (opzionale) | Tipo di subagent, presente quando l'hook si attiva all'interno di un subagent |
2455 2456
2456<h3 id="userpromptsubmithookinput">2457<h3 id="userpromptsubmithookinput">
2457 `UserPromptSubmitHookInput`2458 `UserPromptSubmitHookInput`
2506| :- | :- | :- |2507| :- | :- | :- |
2507| `hook_event_name` | `Literal["SubagentStop"]` | Sempre "SubagentStop" |2508| `hook_event_name` | `Literal["SubagentStop"]` | Sempre "SubagentStop" |
2508| `stop_hook_active` | `bool` | Se l'hook di arresto è attivo |2509| `stop_hook_active` | `bool` | Se l'hook di arresto è attivo |
2509| `agent_id` | `str` | Identificatore univoco per il subagente |2510| `agent_id` | `str` | Identificatore univoco per il subagent |
2510| `agent_transcript_path` | `str` | Percorso al file di trascritto del subagente |2511| `agent_transcript_path` | `str` | Percorso al file di trascrizione del subagent |
2511| `agent_type` | `str` | Tipo del subagente |2512| `agent_type` | `str` | Tipo del subagent |
2512 2513
2513<h3 id="precompacthookinput">2514<h3 id="precompacthookinput">
2514 `PreCompactHookInput`2515 `PreCompactHookInput`
2566| Campo | Tipo | Descrizione |2567| Campo | Tipo | Descrizione |
2567| :- | :- | :- |2568| :- | :- | :- |
2568| `hook_event_name` | `Literal["SubagentStart"]` | Sempre "SubagentStart" |2569| `hook_event_name` | `Literal["SubagentStart"]` | Sempre "SubagentStart" |
2569| `agent_id` | `str` | Identificatore univoco per il subagente |2570| `agent_id` | `str` | Identificatore univoco per il subagent |
2570| `agent_type` | `str` | Tipo del subagente |2571| `agent_type` | `str` | Tipo del subagent |
2571 2572
2572<h3 id="permissionrequesthookinput">2573<h3 id="permissionrequesthookinput">
2573 `PermissionRequestHookInput`2574 `PermissionRequestHookInput`
2574</h3>2575</h3>
2575 2576
2576Dati di input per gli eventi hook `PermissionRequest`. Consente agli hook di gestire le decisioni di autorizzazione a livello di programmazione.2577Dati di input per gli eventi hook `PermissionRequest`. Consente agli hook di gestire le decisioni di permesso a livello di programmazione.
2577 2578
2578```python theme={null}2579```python theme={null}
2579class PermissionRequestHookInput(BaseHookInput):2580class PermissionRequestHookInput(BaseHookInput):
2588| Campo | Tipo | Descrizione |2589| Campo | Tipo | Descrizione |
2589| :- | :- | :- |2590| :- | :- | :- |
2590| `hook_event_name` | `Literal["PermissionRequest"]` | Sempre "PermissionRequest" |2591| `hook_event_name` | `Literal["PermissionRequest"]` | Sempre "PermissionRequest" |
2591| `tool_name` | `str` | Nome dello strumento che richiede l'autorizzazione |2592| `tool_name` | `str` | Nome dello strumento che richiede il permesso |
2592| `tool_input` | `dict[str, Any]` | Parametri di input per lo strumento |2593| `tool_input` | `dict[str, Any]` | Parametri di input per lo strumento |
2593| `permission_suggestions` | `list[Any]` (opzionale) | Aggiornamenti di autorizzazione suggeriti dalla CLI |2594| `permission_suggestions` | `list[Any]` (opzionale) | Aggiornamenti dei permessi suggeriti dalla CLI |
2594| `agent_id` | `str` (opzionale) | Identificatore del subagente, presente quando l'hook si attiva all'interno di un subagente |2595| `agent_id` | `str` (opzionale) | Identificatore del subagent, presente quando l'hook si attiva all'interno di un subagent |
2595| `agent_type` | `str` (opzionale) | Tipo di subagente, presente quando l'hook si attiva all'interno di un subagente |2596| `agent_type` | `str` (opzionale) | Tipo di subagent, presente quando l'hook si attiva all'interno di un subagent |
2596 2597
2597<h3 id="hookjsonoutput">2598<h3 id="hookjsonoutput">
2598 `HookJSONOutput`2599 `HookJSONOutput`
2634 `HookSpecificOutput`2635 `HookSpecificOutput`
2635</h4>2636</h4>
2636 2637
2637Un'unione discriminata di tipi di output specifici dell'evento `TypedDict`. Il campo `hookEventName` determina quali campi sono validi. Per i dettagli completi sui campi disponibili per evento hook, vedi [Controlla l'esecuzione con gli hooks](/docs/it/agent-sdk/hooks#outputs).2638Un'unione discriminata di tipi di output specifici dell'evento `TypedDict`. Il campo `hookEventName` determina quali campi sono validi. Per i dettagli completi sui campi disponibili per evento hook, vedi [Controlla l'esecuzione con gli hook](/docs/it/agent-sdk/hooks#outputs).
2638 2639
2639```python theme={null}2640```python theme={null}
2640class PreToolUseHookSpecificOutput(TypedDict):2641class PreToolUseHookSpecificOutput(TypedDict):
2649 hookEventName: Literal["PostToolUse"]2650 hookEventName: Literal["PostToolUse"]
2650 additionalContext: NotRequired[str]2651 additionalContext: NotRequired[str]
2651 updatedToolOutput: NotRequired[Any]2652 updatedToolOutput: NotRequired[Any]
2652 updatedMCPToolOutput: NotRequired[Any] # Deprecated: use updatedToolOutput, which works for all tools2653 updatedMCPToolOutput: NotRequired[Any] # MCP tools only. Prefer updatedToolOutput, which works for all tools
2653 2654
2654 2655
2655class PostToolUseFailureHookSpecificOutput(TypedDict):2656class PostToolUseFailureHookSpecificOutput(TypedDict):
2708 Esempio di utilizzo di Hook2709 Esempio di utilizzo di Hook
2709</h3>2710</h3>
2710 2711
2711Questo esempio registra due hook: uno che blocca i comandi bash pericolosi come `rm -rf /`, e un altro che registra tutto l'utilizzo dello strumento per il controllo. L'hook di sicurezza viene eseguito solo sui comandi Bash (tramite il `matcher`), mentre l'hook di registrazione viene eseguito su tutti gli strumenti.2712Questo esempio registra due hook: uno che blocca i comandi Bash pericolosi come `rm -rf /`, e un altro che registra nei log tutto l'utilizzo degli strumenti per il controllo. L'hook di sicurezza viene eseguito solo sui comandi Bash (tramite il `matcher`), mentre l'hook di logging viene eseguito su tutti gli strumenti.
2712 2713
2713```python theme={null}2714```python theme={null}
2714import asyncio2715import asyncio
2767 Tipi di input/output dello strumento2768 Tipi di input/output dello strumento
2768</h2>2769</h2>
2769 2770
2770Documentazione degli schemi di input/output per tutti gli strumenti Claude Code integrati. Mentre Python SDK non esporta questi come tipi, rappresentano la struttura degli input e output dello strumento nei messaggi.2771Documentazione degli schemi di input/output per gli strumenti Claude Code integrati. Mentre Python SDK non esporta questi come tipi, rappresentano la struttura degli input e output dello strumento nei messaggi.
2771 2772
2772Ogni output mostrato è il valore che leggete da [`UserMessage.tool_use_result`](#usermessage) per quello strumento. I nomi delle chiavi appaiono esattamente come Claude Code li emette. Una chiave annotata `| None` con un commento "presente quando" o "opzionale" viene omessa quando non si applica.2773Ogni output mostrato è il valore che leggi da [`UserMessage.tool_use_result`](#usermessage) per quello strumento. I nomi delle chiavi appaiono esattamente come Claude Code li emette. Una chiave annotata `| None` con un commento "presente quando" o "opzionale" viene omessa quando non si applica.
2773 2774
2774<h3 id="agent">2775<h3 id="agent">
2775 Agent2776 Agent
2788 "run_in_background": bool | None, # Gli agenti vengono eseguiti in background per impostazione predefinita; impostare su False per eseguire in modo sincrono2789 "run_in_background": bool | None, # Gli agenti vengono eseguiti in background per impostazione predefinita; impostare su False per eseguire in modo sincrono
2789 "name": str | None, # Nome per l'agente generato2790 "name": str | None, # Nome per l'agente generato
2790 "team_name": str | None, # Deprecato; ignorato2791 "team_name": str | None, # Deprecato; ignorato
2791 "mode": "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan" | None, # Deprecato; ignorato. Le regole di ereditarietà dei subagenti decidono la modalità di autorizzazione di un subagente2792 "mode": "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan" | None, # Deprecato; ignorato. Le regole di ereditarietà dei subagent decidono la modalità di permesso di un subagent
2792 "isolation": "worktree" | "remote" | None, # Modalità di isolamento per le modifiche dell'agente2793 "isolation": "worktree" | "remote" | None, # Modalità di isolamento per le modifiche dell'agente
2793}2794}
2794```2795```
2873}2874}
2874```2875```
2875 2876
2876Restituisce il risultato dal subagente. L'output è discriminato sul campo `status`: `"completed"` per compiti terminati, `"async_launched"` per compiti in background, e `"remote_launched"` per compiti che Claude Code ha inviato a una sessione cloud, dove `sessionUrl` si collega a quella sessione e `taskId` l'identifica. Se Claude Code [ha mantenuto il worktree isolato del subagente](/docs/it/worktrees#isolate-subagents-with-worktrees), `worktreePath` sulla variante `completed` è dove trovarlo, e `worktreeBranch` è il suo ramo quando Claude Code ha creato il worktree con git.2877Restituisce il risultato dal subagent. L'output è discriminato sul campo `status`: `"completed"` per compiti terminati, `"async_launched"` per compiti in background, e `"remote_launched"` per compiti che Claude Code ha inviato a una sessione cloud, dove `sessionUrl` si collega a quella sessione e `taskId` l'identifica. Se Claude Code [ha mantenuto il worktree isolato del subagent](/docs/it/worktrees#isolate-subagents-with-worktrees), `worktreePath` sulla variante `completed` è dove trovarlo, e `worktreeBranch` è il suo branch quando Claude Code ha creato il worktree con git.
2877 2878
2878Sulla 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. Sulla variante `async_launched`, `resolvedModel` nomina il modello in uso quando l'agente si è spostato in background, quindi uno scambio che è accaduto prima del backgrounding si riflette lì. Il campo `modelsUsed` su entrambe le varianti elenca i modelli utilizzati in ordine, con ripetizioni consecutive compresse; è impostato solo quando il modello è stato scambiato durante l'esecuzione. `modelsUsed` e il comportamento di `resolvedModel` al momento del backgrounding richiedono Claude Code v2.1.212 o successivo.2879Sulla variante `completed`, `resolvedModel` nomina il modello su cui il subagent 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. Sulla variante `async_launched`, `resolvedModel` nomina il modello in uso quando l'agente si è spostato in background, quindi uno scambio che è accaduto prima del backgrounding si riflette lì. Il campo `modelsUsed` su entrambe le varianti elenca i modelli utilizzati in ordine, con ripetizioni consecutive compresse; è impostato solo quando il modello è stato scambiato durante l'esecuzione. `modelsUsed` e il comportamento di `resolvedModel` al momento del backgrounding richiedono Claude Code v2.1.212 o successivo.
2879 2880
2880Claude Code riempie `usage` e `totalTokens` dalla richiesta API finale del subagent, non dall'intera esecuzione. Quando presente, `thinking_tokens` sotto `output_tokens_details` in `usage` è il numero di token di output di quella richiesta che erano token di ragionamento. La chiave `output_tokens_details` richiede Python SDK v0.2.136 o successivo, che raggruppa Claude Code v2.1.228. La chiave `fallback_credit` richiede Python SDK v0.2.162 o successivo, che raggruppa Claude Code v2.1.285.2881Claude Code riempie `usage` e `totalTokens` dalla richiesta API finale del subagent, non dall'intera esecuzione. Quando presente, `thinking_tokens` sotto `output_tokens_details` in `usage` è il numero di token di output di quella richiesta che erano token di ragionamento. La chiave `output_tokens_details` richiede Python SDK v0.2.136 o successivo, che raggruppa Claude Code v2.1.228. La chiave `fallback_credit` richiede Python SDK v0.2.162 o successivo, che raggruppa Claude Code v2.1.285.
2881 2882
2906 }2907 }
2907 ],2908 ],
2908 "answers": dict[str, str] | None,2909 "answers": dict[str, str] | None,
2909 # Risposte dell'utente popolate dal sistema di autorizzazione. Le risposte2910 # Risposte dell'utente popolate dal sistema di permessi. Le risposte
2910 # multi-select sono una stringa unita da virgole delle etichette selezionate; un2911 # multi-select sono una stringa unita da virgole delle etichette selezionate; un
2911 # elenco di etichette è accettato su input e coercizzato in quella forma2912 # elenco di etichette è accettato su input e coercizzato in quella forma
2912 "annotations": dict[str, dict] | None,2913 "annotations": dict[str, dict] | None,
2933 # Le risposte multi-select sono separate da virgole2934 # Le risposte multi-select sono separate da virgole
2934 "response": str | None,2935 "response": str | None,
2935 # Risposta in testo libero digitata invece di rispondere alle domande; quando impostato,2936 # Risposta in testo libero digitata invece di rispondere alle domande; quando impostato,
2936 # Claude riceve "L'utente ha risposto: ..." al posto dell'elenco di risposte2937 # Claude riceve "The user responded: ..." al posto dell'elenco di risposte
2937 "annotations": dict[str, dict] | None, # "preview" e "notes" per domanda dalle selezioni dell'utente2938 "annotations": dict[str, dict] | None, # "preview" e "notes" per domanda dalle selezioni dell'utente
2938 "afkTimeoutMs": int | None, # Impostato quando la finestra di dialogo si è auto-risolta dopo questo numero di millisecondi di inattività dell'utente; assente quando l'utente ha risposto2939 "afkTimeoutMs": int | None, # Impostato quando la finestra di dialogo si è auto-risolta dopo questo numero di millisecondi di inattività dell'utente; assente quando l'utente ha risposto
2939}2940}
2976 2977
2977**Nome dello strumento:** `Monitor`2978**Nome dello strumento:** `Monitor`
2978 2979
2979Esegue una sorgente in background e fornisce 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 ed emette un evento per frame di testo. Fornire esattamente uno tra `command` o `ws`.2980Esegue una sorgente in background e fornisce 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 ed emette un evento per frame di testo. Fornisci esattamente uno tra `command` o `ws`.
2980 2981
2981Quando Monitor esegue un comando, segue le stesse regole di autorizzazione di Bash; un monitoraggio WebSocket richiede l'approvazione separatamente. L'origine `ws` richiede Claude Code v2.1.195 o successivo. Vedi il [riferimento dello strumento Monitor](/docs/it/tools-reference#monitor-tool) per il comportamento e la disponibilità del provider.2982Quando Monitor esegue un comando, segue le stesse regole di permesso di Bash; un monitoraggio WebSocket richiede l'approvazione separatamente. L'origine `ws` richiede Claude Code v2.1.195 o successivo. Vedi il [riferimento dello strumento Monitor](/docs/it/tools-reference#monitor-tool) per il comportamento e la disponibilità del provider.
2982 2983
2983**Input:**2984**Input:**
2984 2985
3065}3066}
3066```3067```
3067 3068
3068L'output assume una delle seguenti forme a seconda di ciò che Claude ha letto. Controllare la chiave `type` per distinguerle.3069L'output assume una delle seguenti forme a seconda di ciò che Claude ha letto. Controlla la chiave `type` per distinguerle.
3069 3070
3070**Output (type: `"text"`):**3071**Output (type: `"text"`):**
3071 3072
3150 "file": {3151 "file": {
3151 "filePath": str,3152 "filePath": str,
3152 },3153 },
3153 "source": "seeded" | None, # Presente quando la copia precedente proveniva da un file CLAUDE.md o memory caricato all'avvio piuttosto che da una chiamata Read3154 "source": "seeded" | None, # Presente quando la copia precedente proveniva da un file CLAUDE.md o di memoria caricato all'avvio piuttosto che da una chiamata Read
3154}3155}
3155```3156```
3156 3157
3544 TaskOutput3545 TaskOutput
3545</h3>3546</h3>
3546 3547
3547Rimosso in Claude Code v2.1.277. In precedenza recuperava l'output da un'attività in background o completata in esecuzione, con `BashOutput` accettato come alias; Claude legge il file di output di un'attività in background con `Read` invece.3548Rimosso in Claude Code v2.1.277. In precedenza recuperava l'output da un'attività in background in esecuzione o completata, con `BashOutput` accettato come alias; Claude legge invece il file di output di un'attività in background con `Read`.
3548 3549
3549Una voce `disallowed_tools` o una regola di negazione che ancora nomina uno dei due nomi viene ignorata senza un avviso.3550Una voce `disallowed_tools` o una regola di negazione che ancora nomina uno dei due nomi viene ignorata senza un avviso.
3550 3551
3584 3585
3585```python theme={null}3586```python theme={null}
3586{3587{
3587 "plan": str # Il piano da eseguire dall'utente per l'approvazione3588 "plan": str # Il piano da sottoporre all'utente per l'approvazione
3588}3589}
3589```3590```
3590 3591
3593```python theme={null}3594```python theme={null}
3594{3595{
3595 "plan": str | None, # Il piano che è stato presentato all'utente3596 "plan": str | None, # Il piano che è stato presentato all'utente
3596 "isAgent": bool, # True quando un subagente ha chiamato lo strumento3597 "isAgent": bool, # True quando un subagent ha chiamato lo strumento
3597 "filePath": str | None, # Presente quando il piano è stato salvato in un file3598 "filePath": str | None, # Presente quando il piano è stato salvato in un file
3598 "hasTaskTool": bool | None, # Opzionale; se lo strumento Agent è disponibile nel contesto corrente3599 "hasTaskTool": bool | None, # Opzionale; se lo strumento Agent è disponibile nel contesto corrente
3599 "planWasEdited": bool | None, # Presente e True quando l'utente ha modificato il piano prima di approvarlo3600 "planWasEdited": bool | None, # Presente e True quando l'utente ha modificato il piano prima di approvarlo
