Documentation — Spybara

agent-sdk/agent-loop.md +7 −1

Details

217| :- | :- | :- |217| :- | :- | :- |

220 220

221Quando uno dei due limiti viene raggiunto, l'SDK restituisce un `ResultMessage` con un sottotipo di errore corrispondente (`error_max_turns` o `error_max_budget_usd`). Vedere [Gestire il risultato](#handle-the-result) per come controllare questi sottotipi e [`ClaudeAgentOptions`](/docs/it/agent-sdk/python#claudeagentoptions) / [`Options`](/docs/it/agent-sdk/typescript#options) per la sintassi.221Quando uno dei due limiti viene raggiunto, l'SDK restituisce un `ResultMessage` con un sottotipo di errore corrispondente (`error_max_turns` o `error_max_budget_usd`). Vedere [Gestire il risultato](#handle-the-result) per come controllare questi sottotipi e [`ClaudeAgentOptions`](/docs/it/agent-sdk/python#claudeagentoptions) / [`Options`](/docs/it/agent-sdk/typescript#options) per la sintassi.

222 222

224 224

225Con [streaming input](/docs/it/agent-sdk/streaming-vs-single-mode), un messaggio che è ancora in coda quando un turno termina al limite di max-turni rimane in coda. Claude Code non lo aggiunge alla chiamata del modello finale di quel turno. Inizia un nuovo turno per il messaggio e il conteggio di max-turni ricomincia da capo per quel turno. Il totale del budget continua ad accumularsi tra i messaggi e una volta che la spesa raggiunge `maxBudgetUsd`, i messaggi successivi nella stessa conversazione terminano con il risultato `error_max_budget_usd`. Un [`/clear`](/docs/it/agent-sdk/cost-tracking) ricomincia il budget da capo.225Con [streaming input](/docs/it/agent-sdk/streaming-vs-single-mode), un messaggio che è ancora in coda quando un turno termina al limite di max-turni rimane in coda. Claude Code non lo aggiunge alla chiamata del modello finale di quel turno. Inizia un nuovo turno per il messaggio e il conteggio di max-turni ricomincia da capo per quel turno. Il totale del budget continua ad accumularsi tra i messaggi e una volta che la spesa raggiunge `maxBudgetUsd`, i messaggi successivi nella stessa conversazione terminano con il risultato `error_max_budget_usd`. Un [`/clear`](/docs/it/agent-sdk/cost-tracking) ricomincia il budget da capo.

226 226

227<h4 id="budget-headroom">

228 Margine del budget

229</h4>

230

231Claude Code confronta la spesa con il limite `max_budget_usd` / `maxBudgetUsd` dopo l'arrivo delle risposte del modello, perché il costo di ogni risposta deriva dall'utilizzo di token che l'API restituisce insieme ad essa. La risposta che raggiunge il limite viene comunque completata e conta in [`total_cost_usd`](/docs/it/agent-sdk/cost-tracking#get-the-total-cost-of-a-query). La spesa può quindi superare il limite fino al costo di quella singola risposta, più quanto spendono i subagent ancora in esecuzione in quel momento prima di fermarsi. Lascia un margine per questo quando imposti il limite.

232

227<h3 id="effort-level">233<h3 id="effort-level">

228 Livello di sforzo234 Livello di sforzo

229</h3>235</h3>

agent-sdk/permissions.md +1 −1

Details

146| `auto` | Approvazioni classificate dal modello | Un classificatore del modello esamina azioni come comandi shell e richieste di rete, consentendo o bloccando ciascuna che esamina. Vedere [Modalità Auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) per la disponibilità e l'ordine di decisione |146| `auto` | Approvazioni classificate dal modello | Un classificatore del modello esamina azioni come comandi shell e richieste di rete, consentendo o bloccando ciascuna che esamina. Vedere [Modalità Auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) per la disponibilità e l'ordine di decisione |

147 147

148<Warning>148<Warning>

149 **Ereditarietà dei subagent:** Un subagent viene eseguito nella modalità di autorizzazione della sessione padre a meno che non si imposti `permissionMode` sulla sua [`AgentDefinition`](/docs/it/agent-sdk/typescript#agentdefinition) e la sessione padre sia in modalità `default`, `dontAsk` o `plan`. Anche in questo caso, Claude Code non applica mai un valore `"bypassPermissions"`. Un subagent viene eseguito in modalità `bypassPermissions` solo quando la sessione padre stessa lo fa. L'eccezione `bypassPermissions` richiede Claude Code v2.1.267 o successivo.149 **Ereditarietà dei subagent:** Un subagent viene eseguito nella modalità di permesso della sessione padre a meno che tu non imposti `permissionMode` sulla sua [`AgentDefinition`](/docs/it/agent-sdk/typescript#agentdefinition) e la sessione padre sia in modalità `default`, `dontAsk` o `plan`. Anche in questo caso, Claude Code non applica mai un valore `"bypassPermissions"` e applica un valore `"auto"` solo quando la [modalità auto è disponibile](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) per quel subagent. Un subagent viene eseguito in modalità `bypassPermissions` solo quando lo è la sessione padre stessa. L'eccezione `bypassPermissions` richiede Claude Code v2.1.267 o successivo.

150 150

151 I subagent possono avere prompt di sistema diversi e comportamenti meno vincolati rispetto all'agente principale, quindi ereditare `bypassPermissions` concede loro accesso completo e autonomo al sistema. Le [azioni che nessuna modalità approva automaticamente](/docs/it/permission-modes#actions-no-mode-auto-approves) si applicano comunque.151 I subagent possono avere prompt di sistema diversi e comportamenti meno vincolati rispetto all'agente principale, quindi ereditare `bypassPermissions` concede loro accesso completo e autonomo al sistema. Le [azioni che nessuna modalità approva automaticamente](/docs/it/permission-modes#actions-no-mode-auto-approves) si applicano comunque.

152</Warning>152</Warning>

agent-sdk/python.md +2 −1

Details

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 |

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. La stima può superare questo valore, quindi [lascia un margine](/docs/it/agent-sdk/agent-loop#budget-headroom). 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 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) |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) |

3327{3327{

3328 "url": str, # L'URL da cui recuperare il contenuto3328 "url": str, # L'URL da cui recuperare il contenuto

3329 "prompt": str, # Il prompt da eseguire sul contenuto recuperato3329 "prompt": str, # Il prompt da eseguire sul contenuto recuperato

3330 "offset": int | None, # Numero di caratteri da saltare dall'inizio della pagina. Richiede Python Agent SDK 0.2.164 o successivo

3330}3331}

3331```3332```

3332 3333

agent-sdk/subagents.md +9 −2

Details

323 Rilevare l'invocazione di subagent323 Rilevare l'invocazione di subagent

324</h2>324</h2>

325 325

326Claude invoca i subagent tramite lo strumento Agent. Per rilevare quando un subagent viene invocato, verificare i blocchi `tool_use` dove `name` è `"Agent"`. I messaggi provenienti dal contesto di un subagent includono un campo `parent_tool_use_id`.326Claude invoca i subagent tramite lo strumento Agent. Per rilevare quando un subagent viene invocato, verifica i blocchi `tool_use` dove `name` è `"Agent"`.

327

328I messaggi provenienti dal contesto di un subagent includono un campo `parent_tool_use_id`. In TypeScript, ogni messaggio assistant e user prodotto da un subagent contiene anche [`agent_id`](/docs/it/agent-sdk/typescript#sdkassistantmessage): il `task_id` degli [eventi task](/docs/it/agent-sdk/typescript#sdktaskstartedmessage) di quel subagent. `agent_id` richiede TypeScript Agent SDK v0.3.292 o versioni successive.

327 329

328<Note>330<Note>

329 Lo strumento appare come `"Agent"` nei blocchi `tool_use` ma come `"Task"` nell'elenco degli strumenti `system:init`. Prima di Claude Code v2.1.63, i blocchi `tool_use` lo denominano anche `"Task"`. Per mantenere il rilevamento funzionante tra le versioni dell'SDK, abbinare entrambi i valori in `block.name`.331 Lo strumento appare come `"Agent"` nei blocchi `tool_use` ma come `"Task"` nell'elenco degli strumenti `system:init`. Prima di Claude Code v2.1.63, i blocchi `tool_use` lo denominano anche `"Task"`. Per mantenere il rilevamento funzionante tra le versioni dell'SDK, abbinare entrambi i valori in `block.name`.

331 333

332La struttura del messaggio differisce tra gli SDK. In Python, si accede ai blocchi di contenuto direttamente tramite `message.content`. In TypeScript, `SDKAssistantMessage` racchiude il messaggio dell'API Claude, quindi si accede al contenuto tramite `message.message.content`.334La struttura del messaggio differisce tra gli SDK. In Python, si accede ai blocchi di contenuto direttamente tramite `message.content`. In TypeScript, `SDKAssistantMessage` racchiude il messaggio dell'API Claude, quindi si accede al contenuto tramite `message.message.content`.

333 335

334Questo esempio itera attraverso i messaggi in streaming, registrando quando un subagent viene invocato e quando i messaggi successivi provengono dal contesto di esecuzione di quel subagent.336Questo esempio itera attraverso i messaggi in streaming, registrando quando un subagent viene invocato e quando i messaggi successivi provengono dal contesto di esecuzione di quel subagent. La versione TypeScript registra anche l'`agent_id` di ogni messaggio del subagent che ne contiene uno.

335 337

336<CodeGroup>338<CodeGroup>

337 ```python Python theme={null}339 ```python Python theme={null}

403 // Check if this message is from within a subagent's context405 // Check if this message is from within a subagent's context

404 if (msg.parent_tool_use_id) {406 if (msg.parent_tool_use_id) {

405 console.log(" (running inside subagent)");407 console.log(" (running inside subagent)");

408 // On assistant and user messages, agent_id matches the task_id

409 // on that subagent's task_started and other task events

410 if (msg.agent_id) {

411 console.log(` agent_id: ${msg.agent_id}`);

412 }

406 }413 }

407 414

408 if ("result" in message) {415 if ("result" in message) {

agent-sdk/typescript.md +28 −5

Details

570| `loadTimeoutMs` | `number` | `60000` | *Alpha.* Timeout in millisecondi per ogni chiamata a `sessionStore.load()` e `sessionStore.listSubkeys()` durante la materializzazione della ripresa. Se l'adattatore non si risolve entro questo intervallo, la query fallisce invece di bloccarsi. Ignorato quando `sessionStore` non è impostato |570| `loadTimeoutMs` | `number` | `60000` | *Alpha.* Timeout in millisecondi per ogni chiamata a `sessionStore.load()` e `sessionStore.listSubkeys()` durante la materializzazione della ripresa. Se l'adattatore non si risolve entro questo intervallo, la query fallisce invece di bloccarsi. Ignorato quando `sessionStore` non è impostato |

571| `managedSettings` | `Settings` | `undefined` | Impostazioni di livello policy che il tuo processo host fornisce alla sessione avviata. Sui computer con impostazioni gestite distribuite dall'amministratore, Claude Code le ignora a meno che la fonte gestita con la massima priorità dell'amministratore non imposti `parentSettingsBehavior: 'merge'`, e non ne esegue mai il merge mentre un [`policyHelper`](/docs/it/settings-reference#policyhelper) fornisce impostazioni gestite. I valori sottoposti a merge passano attraverso un filtro solo restrittivo; [Limitare le impostazioni padre](/docs/it/claude-apps-gateway#restrict-parent-settings) descrive cosa ammette il filtro e i blocchi `allowManaged*Only`. Un host che imposta [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/it/env-vars) legge invece tre chiavi direttamente da questo payload: la sua [configurazione del modello](/docs/it/model-config#restrict-model-selection) su Claude Code v2.1.222 o successivo, [`modelPricing`](/docs/it/settings-reference#modelpricing) quando nessuna fonte gestita lo imposta su v2.1.246 o successivo, e la sua voce env `ENABLE_TOOL_SEARCH` su v2.1.247 o successivo |571| `managedSettings` | `Settings` | `undefined` | Impostazioni di livello policy che il tuo processo host fornisce alla sessione avviata. Sui computer con impostazioni gestite distribuite dall'amministratore, Claude Code le ignora a meno che la fonte gestita con la massima priorità dell'amministratore non imposti `parentSettingsBehavior: 'merge'`, e non ne esegue mai il merge mentre un [`policyHelper`](/docs/it/settings-reference#policyhelper) fornisce impostazioni gestite. I valori sottoposti a merge passano attraverso un filtro solo restrittivo; [Limitare le impostazioni padre](/docs/it/claude-apps-gateway#restrict-parent-settings) descrive cosa ammette il filtro e i blocchi `allowManaged*Only`. Un host che imposta [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/it/env-vars) legge invece tre chiavi direttamente da questo payload: la sua [configurazione del modello](/docs/it/model-config#restrict-model-selection) su Claude Code v2.1.222 o successivo, [`modelPricing`](/docs/it/settings-reference#modelpricing) quando nessuna fonte gestita lo imposta su v2.1.246 o successivo, e la sua voce env `ENABLE_TOOL_SEARCH` su v2.1.247 o successivo |

572| `maxBudgetUsd` | `number` | `undefined` | Interrompe la query quando la stima dei costi lato client raggiunge questo valore in USD. Conta solo la spesa della chiamata stessa; i totali ripristinati da una sessione ripresa non vengono conteggiati. Per le avvertenze sulla precisione e il comportamento di azzeramento, consulta [Tracciare costi e utilizzo](/docs/it/agent-sdk/cost-tracking) |572| `maxBudgetUsd` | `number` | `undefined` | Interrompe la query quando la stima dei costi lato client raggiunge questo valore in USD. La stima può superare questo valore, quindi [lascia un margine](/docs/it/agent-sdk/agent-loop#budget-headroom). Conta solo la spesa della chiamata stessa; i totali ripristinati da una sessione ripresa non vengono conteggiati. Per le avvertenze sull'accuratezza e il comportamento di reimpostazione, consulta [Monitorare costi e utilizzo](/docs/it/agent-sdk/cost-tracking) |

575| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurazioni dei server MCP |575| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurazioni dei server MCP |

1557 type: "assistant";1557 type: "assistant";

1558 uuid: UUID;1558 uuid: UUID;

1559 session_id: string;1559 session_id: string;

1560 message: BetaMessage; // Dall'SDK Anthropic1560 message: BetaMessage; // From Anthropic SDK

1561 parent_tool_use_id: string | null;1561 parent_tool_use_id: string | null;

1562 error?: SDKAssistantMessageError;1562 error?: SDKAssistantMessageError;

1563 aborted?: true;1563 aborted?: true;

1564 agent_id?: string;

1564 timestamp?: string;1565 timestamp?: string;

1565 context_usage?: SDKContextUsage;1566 context_usage?: SDKContextUsage;

1566 user_message_uuid?: string;1567 user_message_uuid?: string;

1580 1581

1581`aborted` è `true` quando un'interruzione o un annullamento ha troncato il messaggio dell'assistente prima del completamento del flusso: il messaggio non ha `stop_reason` e il contenuto può terminare a metà parola. Il campo è assente sui messaggi completati normalmente. Richiede Agent SDK v0.3.214 o successivo.1582`aborted` è `true` quando un'interruzione o un annullamento ha troncato il messaggio dell'assistente prima del completamento del flusso: il messaggio non ha `stop_reason` e il contenuto può terminare a metà parola. Il campo è assente sui messaggi completati normalmente. Richiede Agent SDK v0.3.214 o successivo.

1582 1583

1584`agent_id` identifica il subagent che ha prodotto il messaggio ed è assente nei messaggi del thread principale. Il valore è uguale al `task_id` nel [`task_started`](#sdktaskstartedmessage) di quel subagent e negli altri eventi di attività, e non cambia quando il subagent viene [ripreso](/docs/it/agent-sdk/subagents#resume-subagents). Il campo richiede Agent SDK v0.3.292 o successiva.

1585

1586Associa i messaggi di un subagent ai suoi eventi di attività tramite `agent_id`, anziché abbinare il `parent_tool_use_id` di un messaggio con il `tool_use_id` di un evento di attività. Quando una chiamata a uno strumento riprende il subagent, gli eventi di attività riportano il `tool_use_id` di quella chiamata, mentre i messaggi mantengono il `parent_tool_use_id` della chiamata allo strumento che ha avviato per primo il subagent, quindi i due non corrispondono più.

1587

1583Claude Code imposta `user_message_uuid` e `user_message_uuids` sul primo messaggio dell'assistente del turno, secondo le condizioni descritte in [`user_message_uuid`](#user_message_uuid). Quando Claude Code riesegue un turno che un riavvio ha interrotto, i messaggi dell'assistente della riesecuzione che contengono questi campi contengono anche [`resume_reason`](#resume_reason).1588Claude Code imposta `user_message_uuid` e `user_message_uuids` sul primo messaggio dell'assistente del turno, secondo le condizioni descritte in [`user_message_uuid`](#user_message_uuid). Quando Claude Code riesegue un turno che un riavvio ha interrotto, i messaggi dell'assistente della riesecuzione che contengono questi campi contengono anche [`resume_reason`](#resume_reason).

1584 1589

1585`timestamp` è l'ora ISO 8601 in cui il contenuto del messaggio ha finito di essere generato sul processo che lo ha prodotto. Il valore proviene dall'orologio di quella macchina, quindi usalo solo per la visualizzazione e non ordinare i messaggi in base a esso. Un turno API può produrre diversi messaggi dell'assistente che condividono un `message.id`, ciascuno con il proprio `timestamp`. Quando il campo è assente, usa come ripiego il momento in cui hai ricevuto il messaggio.1590`timestamp` è l'ora ISO 8601 in cui il contenuto del messaggio ha finito di essere generato sul processo che lo ha prodotto. Il valore proviene dall'orologio di quella macchina, quindi usalo solo per la visualizzazione e non ordinare i messaggi in base a esso. Un turno API può produrre diversi messaggi dell'assistente che condividono un `message.id`, ciascuno con il proprio `timestamp`. Quando il campo è assente, usa come ripiego il momento in cui hai ricevuto il messaggio.

1597 type: "user";1602 type: "user";

1598 uuid?: UUID;1603 uuid?: UUID;

1599 session_id?: string;1604 session_id?: string;

1605 agent_id?: string;

1600 message: MessageParam; // From Anthropic SDK1606 message: MessageParam; // From Anthropic SDK

1601 pasted_content?: MessageParam["content"][];1607 pasted_content?: MessageParam["content"][];

1602 parent_tool_use_id: string | null;1608 parent_tool_use_id: string | null;

1636};1642};

1637```1643```

1638 1644

1645Un messaggio dell'utente prodotto da un subagent, come il `tool_result` di una delle sue chiamate a strumenti, riporta `agent_id`. Consulta [`SDKAssistantMessage`](#sdkassistantmessage), che definisce il campo e il relativo requisito di versione.

1646

1639In un messaggio che contiene un blocco `tool_result`, `tool_use_result` è l'oggetto di output strutturato dello strumento anziché il testo inviato al modello. La sua forma dipende dallo strumento indicato dal blocco `tool_use` corrispondente, quindi il campo è di tipo `unknown`; le forme integrate sono elencate in [Tool Output Types](#tool-output-types). Questi risultati richiedono una gestione che va oltre la forma elencata:1647In un messaggio che contiene un blocco `tool_result`, `tool_use_result` è l'oggetto di output strutturato dello strumento anziché il testo inviato al modello. La sua forma dipende dallo strumento indicato dal blocco `tool_use` corrispondente, quindi il campo è di tipo `unknown`; le forme integrate sono elencate in [Tool Output Types](#tool-output-types). Questi risultati richiedono una gestione che va oltre la forma elencata:

1640 1648

1641* Lo strumento `Agent`: `tool_use_result` è [`AgentOutput`](#agent-2). Esegui il rendering a partire da esso anziché analizzare il testo di `tool_result`. Il `content` di un risultato `completed` contiene il report del subagent oppure, per un subagent il cui report passa attraverso una chiamata allo strumento `SubagentHandback`, una breve nota su quella restituzione al posto del report. In [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) su Claude Code v2.1.271 o successiva, ogni subagent che produce un risultato `completed` riporta in quel modo a meno che non sia un [fork](/docs/it/sub-agents#fork-the-current-conversation), e Claude riceve il report come messaggio separato dal subagent.1649* Lo strumento `Agent`: `tool_use_result` è [`AgentOutput`](#agent-2). Esegui il rendering a partire da esso anziché analizzare il testo di `tool_result`. Il `content` di un risultato `completed` contiene il report del subagent oppure, per un subagent il cui report passa attraverso una chiamata allo strumento `SubagentHandback`, una breve nota su quella restituzione al posto del report. In [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) su Claude Code v2.1.271 o successiva, ogni subagent che produce un risultato `completed` riporta in quel modo a meno che non sia un [fork](/docs/it/sub-agents#fork-the-current-conversation), e Claude riceve il report come messaggio separato dal subagent.

1992 `SDKPartialAssistantMessage`2000 `SDKPartialAssistantMessage`

1993</h3>2001</h3>

1994 2002

1995Messaggio parziale in streaming (solo quando `includePartialMessages` è true). Il campo `parent_tool_use_id` è sempre `null`: gli eventi di flusso vengono emessi solo per la sessione principale. Per attribuire i messaggi ai subagent, usa i messaggi completi, che contengono `parent_tool_use_id`, oppure abilita [`forwardSubagentText`](#options) per ricevere il testo e il ragionamento dei subagent come messaggi completi.2003Messaggio parziale in streaming (solo quando `includePartialMessages` è true).

2004

2005Il campo `parent_tool_use_id` è sempre `null`: gli eventi di stream vengono emessi solo per la sessione principale. Per l'attribuzione ai subagent, usa i messaggi completi, che riportano [`agent_id`](#sdkassistantmessage) e `parent_tool_use_id`, oppure abilita [`forwardSubagentText`](#options) per ricevere il testo e il ragionamento dei subagent come messaggi completi.

1996 2006

1997```typescript theme={null}2007```typescript theme={null}

1998type SDKPartialAssistantMessage = {2008type SDKPartialAssistantMessage = {

3418type WebFetchInput = {3428type WebFetchInput = {

3419 url: string;3429 url: string;

3420 prompt: string;3430 prompt: string;

3431 offset?: number;

3421};3432};

3422```3433```

3423 3434

3424Recupera il contenuto da un URL e lo elabora con un modello AI.3435Recupera il contenuto da un URL e lo elabora con un modello AI.

3425 3436

3437`offset` è il numero di caratteri da saltare dall'inizio della pagina. Claude lo imposta per continuare a leggere una pagina lunga. Il campo richiede Agent SDK v0.3.290 o successivo.

3438

3426<h3 id="websearch">3439<h3 id="websearch">

3427 WebSearch3440 WebSearch

3428</h3>3441</h3>

5777 task_type?: string;5790 task_type?: string;

5778 is_backgrounded?: boolean;5791 is_backgrounded?: boolean;

5779 spawn_depth?: number;5792 spawn_depth?: number;

5793 parent_task_id?: string;

5780 ambient?: boolean;5794 ambient?: boolean;

5781 uuid: UUID;5795 uuid: UUID;

5782 session_id: string;5796 session_id: string;

5794 5808

5795Un [subagent ripreso](/docs/it/agent-sdk/subagents#resume-subagents) riporta sempre `is_backgrounded: true`, perché Claude Code esegue ogni subagent ripreso in background. Quando un'attività in primo piano passa in seguito in background, Claude Code riporta il nuovo valore di `is_backgrounded` in un messaggio [`task_updated`](#sdktaskupdatedmessage) invece di inviare un secondo `task_started`.5809Un [subagent ripreso](/docs/it/agent-sdk/subagents#resume-subagents) riporta sempre `is_backgrounded: true`, perché Claude Code esegue ogni subagent ripreso in background. Quando un'attività in primo piano passa in seguito in background, Claude Code riporta il nuovo valore di `is_backgrounded` in un messaggio [`task_updated`](#sdktaskupdatedmessage) invece di inviare un secondo `task_started`.

5796 5810

5811`parent_task_id` contiene il `task_id` del subagent che ha avviato questa attività. Usalo per raggruppare ogni attività sotto il subagent che l'ha avviata. Claude Code lo imposta sulle attività di subagent, Bash e [Monitor](#monitor). Il campo richiede Agent SDK v0.3.292 o versioni successive. È assente quando:

5812

5813* L'attività è stata avviata dal thread principale

5814* Claude Code non tiene più traccia dell'attività padre

5815* L'attività è stata avviata da un [membro di un team di agenti](/docs/it/agent-teams) o da un agente all'interno di un workflow

5816

5817L'attività padre può essere un'attività in primo piano o un'attività già terminata, quindi tratta un ID che non riconosci come assenza di attività padre.

5818

5797<h3 id="sdktaskprogressmessage">5819<h3 id="sdktaskprogressmessage">

5798 `SDKTaskProgressMessage`5820 `SDKTaskProgressMessage`

5799</h3>5821</h3>

5850 `SDKBackgroundTasksChangedMessage`5872 `SDKBackgroundTasksChangedMessage`

5851</h3>5873</h3>

5852 5874

5853Emesso ogni volta che l'insieme delle attività in background attive cambia: un'attività inizia, viene completata, viene terminata, un agente in primo piano passa in background, oppure cambia il campo `description` o `ambient` di un'attività.5875Emesso ogni volta che l'insieme delle attività in background attive cambia: un'attività inizia, viene completata o viene terminata; un agente in primo piano passa in background; oppure cambia il campo `description`, `ambient` o `parent_task_id` di un'attività. Per il campo `parent_task_id` di ciascuna voce, consulta [`SDKTaskStartedMessage`](#sdktaskstartedmessage), che lo definisce insieme al relativo requisito di versione.

5854 5876

5855L'array `tasks` è l'intero insieme attivo. Sostituisci qualsiasi insieme memorizzato nella cache con ogni payload invece di abbinare gli eventi `task_started` e `task_notification`, in modo che la successiva modifica dell'insieme corregga qualsiasi evento che ti sei perso.5877L'array `tasks` è l'intero insieme attivo. Sostituisci qualsiasi insieme memorizzato nella cache con ogni payload invece di abbinare gli eventi `task_started` e `task_notification`, in modo che la successiva modifica dell'insieme corregga qualsiasi evento che ti sei perso.

5856 5878

5857L'ordinamento rispetto a quegli eventi per singola attività non è specificato, quindi non correlare i due flussi.5879Quando un'attività termina, i suoi [`task_updated`](#sdktaskupdatedmessage) e [`task_notification`](#sdktasknotificationmessage) arrivano prima del `background_tasks_changed` che la rimuove dall'elenco. Per il resto, l'ordinamento rispetto agli eventi per singola attività non è specificato.

5858 5880

5859All'avvio non viene emesso nulla. Reimposta su un insieme vuoto ogni volta che il processo CLI della sessione si avvia o si riavvia e lascia che la successiva modifica dell'insieme lo ripopoli.5881All'avvio non viene emesso nulla. Reimposta su un insieme vuoto ogni volta che il processo CLI della sessione si avvia o si riavvia e lascia che la successiva modifica dell'insieme lo ripopoli.

5860 5882

5871 task_type: string;5893 task_type: string;

5872 subagent_type?: string;5894 subagent_type?: string;

5873 description: string;5895 description: string;

5896 parent_task_id?: string;

5874 ambient?: boolean;5897 ambient?: boolean;

5875 }[];5898 }[];

5876 uuid: UUID;5899 uuid: UUID;

agent-sdk/user-input.md +10 −5

Details

36 ```36 ```

37 37

38 ```typescript TypeScript theme={null}38 ```typescript TypeScript theme={null}

~~39 async function handleToolRequest(toolName, input, options) {~~39 import type { CanUseTool } from "@anthropic-ai/claude-agent-sdk";

41 const handleToolRequest: CanUseTool = async (toolName, input, options) => {

40 // options includes { signal: AbortSignal, suggestions?: PermissionUpdate[] }42 // options includes { signal: AbortSignal, suggestions?: PermissionUpdate[] }

~~41 // Chiedi all'utente e restituisci allow o deny~~43 // Chiedi all'utente qui, poi restituisci allow o deny

~~42 }~~44 return { behavior: "deny", message: "User declined" };

45 };

43 46

44 const options = { canUseTool: handleToolRequest };47 const options = { canUseTool: handleToolRequest };

45 ```48 ```

440 // Includi AskUserQuestion nella tua lista di strumenti443 // Includi AskUserQuestion nella tua lista di strumenti

441 tools: ["Read", "Glob", "Grep", "AskUserQuestion"],444 tools: ["Read", "Glob", "Grep", "AskUserQuestion"],

442 canUseTool: async (toolName, input) => {445 canUseTool: async (toolName, input) => {

443 // Gestisci le domande di chiarimento qui446 // Segnaposto che approva ogni chiamata. Il passaggio Rileva AskUserQuestion lo sostituisce.

447 return { behavior: "allow", updatedInput: input };

444 }448 }

445 }449 }

446 })) {450 })) {

763 767

764 ```typescript TypeScript theme={null}768 ```typescript TypeScript theme={null}

765 import { query } from "@anthropic-ai/claude-agent-sdk";769 import { query } from "@anthropic-ai/claude-agent-sdk";

770 import type { PermissionResult } from "@anthropic-ai/claude-agent-sdk";

766 import * as readline from "readline/promises";771 import * as readline from "readline/promises";

767 772

768 // Helper per chiedere all'utente l'input nel terminale773 // Helper per chiedere all'utente l'input nel terminale

783 }788 }

784 789

785 // Visualizza le domande di Claude e raccogli le risposte dell'utente790 // Visualizza le domande di Claude e raccogli le risposte dell'utente

786 async function handleAskUserQuestion(input: any) {791 async function handleAskUserQuestion(input: any): Promise<PermissionResult> {

787 const answers: Record<string, string> = {};792 const answers: Record<string, string> = {};

788 793

789 for (const q of input.questions) {794 for (const q of input.questions) {

agent-view.md +1 −1

Details

603 603

604Al di fuori di un repository git, le sessioni scrivono direttamente nella directory di lavoro e non sono isolate l'una dall'altra, quindi evita di inviare sessioni parallele che modificano gli stessi file. Se usi un sistema di controllo della versione diverso, configura un [hook `WorktreeCreate`](/docs/it/worktrees#non-git-version-control) e Claude isola le modifiche nello stesso modo in cui lo fa per git.604Al di fuori di un repository git, le sessioni scrivono direttamente nella directory di lavoro e non sono isolate l'una dall'altra, quindi evita di inviare sessioni parallele che modificano gli stessi file. Se usi un sistema di controllo della versione diverso, configura un [hook `WorktreeCreate`](/docs/it/worktrees#non-git-version-control) e Claude isola le modifiche nello stesso modo in cui lo fa per git.

605 605

606Quando l'hook fallisce in una directory che non è un repository git, Claude salta l'isolamento per quella directory e modifica la directory di lavoro in posizione. All'interno di un repository git, una sessione che Claude sposta in un worktree prima di modificare non può modificare i file nel checkout condiviso finché quello spostamento non avviene.606Quando l'hook fallisce in una directory che non è un repository git, Claude salta l'isolamento per quella directory e modifica la directory di lavoro in posizione. All'interno di un repository git, una sessione che Claude sposta in un worktree prima di modificare non può usare gli strumenti `Edit`, `Write` o `NotebookEdit` sul checkout condiviso finché quello spostamento non avviene.

607 607

608Per trovare il percorso del worktree di una sessione, collegati e controlla la sua directory di lavoro.608Per trovare il percorso del worktree di una sessione, collegati e controlla la sua directory di lavoro.

609 609

claude-apps-gateway-config.md +1 −1

Details

1237 1237

1238La CLI invia metriche, log e, quando abilitate, tracce al gateway, che le inoltra alla lettera a ogni destinazione configurata. Le esportazioni utilizzano OpenTelemetry Protocol (OTLP) su HTTP. Per saltare l'inoltro e far esportare le sessioni direttamente al tuo collettore, [nomina il collettore in una policy](#export-directly-to-your-collector). Vedi [Monitoraggio dell'utilizzo](/docs/it/monitoring-usage) per le metriche e gli eventi che la CLI emette.1238La CLI invia metriche, log e, quando abilitate, tracce al gateway, che le inoltra alla lettera a ogni destinazione configurata. Le esportazioni utilizzano OpenTelemetry Protocol (OTLP) su HTTP. Per saltare l'inoltro e far esportare le sessioni direttamente al tuo collettore, [nomina il collettore in una policy](#export-directly-to-your-collector). Vedi [Monitoraggio dell'utilizzo](/docs/it/monitoring-usage) per le metriche e gli eventi che la CLI emette.

1239 1239

1240Nelle sessioni con accesso effettuato tramite `/login`, la CLI contrassegna ogni esportazione con l'identità dell'utente autenticato, letta dal JWT emesso dal gateway: gli attributi `user.id`, `user.email` e `user.groups`. L'attribuzione di costi e utilizzo per sviluppatore funziona quindi senza alcuna configurazione lato sviluppatore.1240Nelle sessioni con accesso effettuato tramite `/login`, la CLI contrassegna ogni esportazione con l'identità dell'utente autenticato, letta dal JWT emesso dal gateway: gli attributi `user.id`, `user.email` e `user.groups`. L'attribuzione di costi e utilizzo per sviluppatore funziona quindi senza alcuna configurazione lato sviluppatore. Gli eventi che Claude Code registra prima che lo sviluppatore effettui l'accesso [non contengono questa identità](/docs/it/monitoring-usage#standard-attributes).

1241 1241

1242Le sessioni di [Claude Desktop](#claude-desktop-overlay) e Cowork con accesso effettuato tramite il gateway contrassegnano la loro telemetria con `user.email` e `user.groups` insieme a `enduser.id`, quindi puoi coprire l'utilizzo da terminale, Desktop e Cowork con un'unica query su `user.email` o `user.groups`. `user.groups` è l'elenco dei gruppi IdP separati da virgole.1242Le sessioni di [Claude Desktop](#claude-desktop-overlay) e Cowork con accesso effettuato tramite il gateway contrassegnano la loro telemetria con `user.email` e `user.groups` insieme a `enduser.id`, quindi puoi coprire l'utilizzo da terminale, Desktop e Cowork con un'unica query su `user.email` o `user.groups`. `user.groups` è l'elenco dei gruppi IdP separati da virgole.

1243 1243

claude-apps-gateway-on-aws.md +1 −1

Details

516 Telemetry516 Telemetry

517</h2>517</h2>

518 518

519Il gateway fornisce metriche di utilizzo per sviluppatore senza alcuna configurazione OTEL per macchina. Claude Code emette metriche, log e tracce OpenTelemetry (OTLP) opzionali; [Monitoring usage](/docs/it/monitoring-usage) copre tutto ciò che il CLI segnala. Nelle sessioni accedute tramite `/login`, il CLI contrassegna ogni esportazione con gli attributi di identità IdP autenticati `user.id`, `user.email` e `user.groups`, in modo che l'utilizzo si accumuli per sviluppatore.519Il gateway ti fornisce metriche di utilizzo per sviluppatore senza alcuna configurazione OTEL per macchina. Claude Code emette metriche, log e tracce opzionali OpenTelemetry (OTLP); [Monitorare l'utilizzo](/docs/it/monitoring-usage) copre tutto ciò che il CLI segnala. Nelle sessioni in cui l'accesso è stato effettuato tramite `/login`, il CLI [contrassegna ogni esportazione](/docs/it/monitoring-usage#standard-attributes) con gli attributi di identità IdP autenticati `user.id`, `user.email` e `user.groups`, in modo che l'utilizzo venga aggregato per sviluppatore.

520 520

521Il gateway stesso è un relay OTLP autenticato. Impostare [`telemetry.forward_to`](/docs/it/claude-apps-gateway-config#telemetry) insieme a `listen.public_url`, e spingerà le impostazioni dell'esportatore OTEL a ogni client connesso e inoltrerà il loro traffico OTLP verbatim a ogni destinazione che elencate. Ogni destinazione acconsente a metriche, log e tracce indipendentemente, e l'impostazione predefinita è solo metriche; vedere il [riferimento `telemetry`](/docs/it/claude-apps-gateway-config#telemetry) per i campi per segnale e i loro compromessi di sensibilità. Il gateway non memorizza nel buffer, non aggrega e non archivia telemetria, quindi il luogo in cui i dati arrivano dipende interamente dalla configurazione dell'esportatore del collector.521Il gateway stesso è un relay OTLP autenticato. Impostare [`telemetry.forward_to`](/docs/it/claude-apps-gateway-config#telemetry) insieme a `listen.public_url`, e spingerà le impostazioni dell'esportatore OTEL a ogni client connesso e inoltrerà il loro traffico OTLP verbatim a ogni destinazione che elencate. Ogni destinazione acconsente a metriche, log e tracce indipendentemente, e l'impostazione predefinita è solo metriche; vedere il [riferimento `telemetry`](/docs/it/claude-apps-gateway-config#telemetry) per i campi per segnale e i loro compromessi di sensibilità. Il gateway non memorizza nel buffer, non aggrega e non archivia telemetria, quindi il luogo in cui i dati arrivano dipende interamente dalla configurazione dell'esportatore del collector.

522 522

claude-projects.md +1 −1

Details

489* **Routine**: quando chiedi il lavoro programmato in un project, Claude crea una [routine](/docs/it/routines) che viene eseguita come thread in quel project e appare sulla sua scheda **Routines**. Le routine che crei al di fuori di un project continuano a funzionare da sole.489* **Routine**: quando chiedi il lavoro programmato in un project, Claude crea una [routine](/docs/it/routines) che viene eseguita come thread in quel project e appare sulla sua scheda **Routines**. Le routine che crei al di fuori di un project continuano a funzionare da sole.

490* **Remote Control**: [Remote Control](/docs/it/remote-control) connette claude.ai a una sessione Claude Code in esecuzione sulla tua macchina. Quando chiedi a Claude in un project di eseguire un thread sul tuo computer, il project [usa Remote Control per farlo](#run-a-thread-on-your-own-computer).490* **Remote Control**: [Remote Control](/docs/it/remote-control) connette claude.ai a una sessione Claude Code in esecuzione sulla tua macchina. Quando chiedi a Claude in un project di eseguire un thread sul tuo computer, il project [usa Remote Control per farlo](#run-a-thread-on-your-own-computer).

491* **Sessioni locali e agent view**: una sessione che avvii da solo nel tuo terminale, IDE o nell'ambiente locale dell'app desktop non può essere aggiunta a un project. [Agent view](/docs/it/agent-view) è una schermata per tracciare diverse sessioni locali fianco a fianco, e tu avvii ancora ognuna e le dai il suo compito da solo.491* **Sessioni locali e agent view**: una sessione che avvii da solo nel tuo terminale, IDE o nell'ambiente locale dell'app desktop non può essere aggiunta a un project. [Agent view](/docs/it/agent-view) è una schermata per tracciare diverse sessioni locali fianco a fianco, e tu avvii ancora ognuna e le dai il suo compito da solo.

492* **Worktrees**: un [worktree](/docs/it/worktrees) dà a ogni sessione locale la sua copia di lavoro di un repository in modo che le sessioni parallele sulla tua macchina non si sovrascrivano a vicenda. I thread cloud non ne hanno bisogno: ognuno clona i suoi repository nella sua sandbox cloud e lavora sul suo branch.492* **Worktree**: un [worktree](/docs/it/worktrees) dà a ogni sessione locale la sua copia di lavoro di un repository. I thread cloud non ne hanno bisogno: ognuno clona i suoi repository nella sua sandbox cloud e lavora sul suo branch.

493* **Agent teams**: un [agent team](/docs/it/agent-teams) è una sessione che avvia sessioni di compagno per un singolo compito, sulla tua macchina o dentro una sessione cloud, e finisce con quel compito.493* **Agent teams**: un [agent team](/docs/it/agent-teams) è una sessione che avvia sessioni di compagno per un singolo compito, sulla tua macchina o dentro una sessione cloud, e finisce con quel compito.

494* **Subagents**: un [subagent](/docs/it/sub-agents) viene eseguito dentro una sessione, esegue un compito secondario nella sua finestra di contesto propria, e restituisce un riepilogo a quella sessione. I thread di un project sono sessioni intere che Claude avvia e che riferiscono di nuovo alla conversazione del project, e un thread può comunque usare subagent per i suoi propri compiti secondari.494* **Subagents**: un [subagent](/docs/it/sub-agents) viene eseguito dentro una sessione, esegue un compito secondario nella sua finestra di contesto propria, e restituisce un riepilogo a quella sessione. I thread di un project sono sessioni intere che Claude avvia e che riferiscono di nuovo alla conversazione del project, e un thread può comunque usare subagent per i suoi propri compiti secondari.

495* **Projects in claude.ai chat e Cowork**: l'[esperienza Projects precedente](https://support.claude.com/en/articles/9517075-what-are-projects), che raggruppa conversazioni e file di riferimento senza thread o un coordinatore. Questi project continuano a funzionare come fanno oggi fino a quando l'esperienza riprogettata li raggiunge.495* **Projects in claude.ai chat e Cowork**: l'[esperienza Projects precedente](https://support.claude.com/en/articles/9517075-what-are-projects), che raggruppa conversazioni e file di riferimento senza thread o un coordinatore. Questi project continuano a funzionare come fanno oggi fino a quando l'esperienza riprogettata li raggiunge.

cli-reference.md +1 −1

Details

106| `--input-format` | Specifica il formato di input per la modalità print (opzioni: `text`, `stream-json`) | `claude -p --output-format json --input-format stream-json` |106| `--input-format` | Specifica il formato di input per la modalità print (opzioni: `text`, `stream-json`) | `claude -p --output-format json --input-format stream-json` |

107| `--json-schema` | Ottieni output JSON convalidato corrispondente a uno JSON Schema dopo che l'agente completa il suo flusso di lavoro (solo modalità print). Vedi [output strutturati](/docs/it/agent-sdk/structured-outputs). Claude Code esce con un errore su uno schema non valido e accetta la parola chiave `format` come annotazione senza convalida lato client | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |107| `--json-schema` | Ottieni output JSON convalidato corrispondente a uno JSON Schema dopo che l'agente completa il suo flusso di lavoro (solo modalità print). Vedi [output strutturati](/docs/it/agent-sdk/structured-outputs). Claude Code esce con un errore su uno schema non valido e accetta la parola chiave `format` come annotazione senza convalida lato client | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

108| `--maintenance` | Esegui gli [hook di Setup](/docs/it/hooks#setup) con il matcher `maintenance` prima della sessione (solo modalità print) | `claude -p --maintenance "query"` |108| `--maintenance` | Esegui gli [hook di Setup](/docs/it/hooks#setup) con il matcher `maintenance` prima della sessione (solo modalità print) | `claude -p --maintenance "query"` |

109| `--max-budget-usd` | Importo massimo in dollari da spendere nelle chiamate API prima di fermarsi (solo modalità print). Claude Code confronta il limite con la sua [stima dei costi lato client](/docs/it/agent-sdk/cost-tracking#estimates-not-billing), che può differire dalla tua fattura. La spesa dei [subagent](/docs/it/sub-agents) conta verso il limite. Quando torni a una conversazione con `--continue` o `--resume`, i totali [ripristinati da esecuzioni precedenti](/docs/it/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls) non contano verso di esso. Una volta che la spesa raggiunge il limite, generare un altro subagent fallisce con `Budget limit reached`, e Claude Code ferma i subagent in background ancora in esecuzione; i comportamenti di applicazione del limite richiedono Claude Code v2.1.217 o successivo | `claude -p --max-budget-usd 5.00 "query"` |109| `--max-budget-usd` | Ferma l'esecuzione quando la spesa stimata per le chiamate API raggiunge questo importo (solo modalità print). Claude Code confronta il limite con la sua [stima dei costi lato client](/docs/it/agent-sdk/cost-tracking#estimates-not-billing), che può differire dalla tua fattura. La spesa dei [subagent](/docs/it/sub-agents) conta verso il limite. La spesa può superare il limite, quindi [lascia un margine](/docs/it/agent-sdk/agent-loop#budget-headroom). Quando torni a una conversazione con `--continue` o `--resume`, i totali [ripristinati da esecuzioni precedenti](/docs/it/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls) non contano verso di esso. Una volta che la spesa raggiunge il limite, l'avvio di un altro subagent fallisce con `Budget limit reached`, e Claude Code ferma i subagent in background ancora in esecuzione; i comportamenti di applicazione del limite richiedono Claude Code v2.1.217 o successivo | `claude -p --max-budget-usd 5.00 "query"` |

110| `--max-turns` | Limita il numero di turni agentici (solo modalità print). Esce con un errore quando il limite viene raggiunto. Nessun limite per impostazione predefinita. Con `--input-format stream-json`, un messaggio ancora in coda quando il limite termina un turno rimane in coda e inizia un nuovo turno con il suo proprio limite | `claude -p --max-turns 3 "query"` |110| `--max-turns` | Limita il numero di turni agentici (solo modalità print). Esce con un errore quando il limite viene raggiunto. Nessun limite per impostazione predefinita. Con `--input-format stream-json`, un messaggio ancora in coda quando il limite termina un turno rimane in coda e inizia un nuovo turno con il suo proprio limite | `claude -p --max-turns 3 "query"` |

111| `--mcp-config` | Carica i server MCP da file JSON o stringhe (separati da spazi). Quando passi questo flag con `-p`, Claude Code attende che i server ancora in sospeso si connettano prima di eseguire il primo turno, fino al timeout di avvio [`MCP_TIMEOUT`](/docs/it/env-vars), 30 secondi per impostazione predefinita; un server con un [elenco di strumenti memorizzato nella cache](/docs/it/mcp#managing-your-servers) salta l'attesa e si connette al primo utilizzo. L'attesa richiede Claude Code v2.1.221 o successivo | `claude --mcp-config ./mcp.json` |111| `--mcp-config` | Carica i server MCP da file JSON o stringhe (separati da spazi). Quando passi questo flag con `-p`, Claude Code attende che i server ancora in sospeso si connettano prima di eseguire il primo turno, fino al timeout di avvio [`MCP_TIMEOUT`](/docs/it/env-vars), 30 secondi per impostazione predefinita; un server con un [elenco di strumenti memorizzato nella cache](/docs/it/mcp#managing-your-servers) salta l'attesa e si connette al primo utilizzo. L'attesa richiede Claude Code v2.1.221 o successivo | `claude --mcp-config ./mcp.json` |

112| `--model` | Imposta il modello per la sessione corrente con un [alias di modello](/docs/it/model-config#model-aliases) come `sonnet`, `opus`, `haiku`, o `fable`, o il nome completo di un modello. Sostituisce l'impostazione [`model`](/docs/it/settings-reference#model) e [`ANTHROPIC_MODEL`](/docs/it/model-config#environment-variables) | `claude --model claude-sonnet-5` |112| `--model` | Imposta il modello per la sessione corrente con un [alias di modello](/docs/it/model-config#model-aliases) come `sonnet`, `opus`, `haiku`, o `fable`, o il nome completo di un modello. Sostituisce l'impostazione [`model`](/docs/it/settings-reference#model) e [`ANTHROPIC_MODEL`](/docs/it/model-config#environment-variables) | `claude --model claude-sonnet-5` |

cloud-environments.md +3 −3

Details

307| | Disponibile nelle sessioni cloud | Perché |307| | Disponibile nelle sessioni cloud | Perché |

308| :- | :- | :- |308| :- | :- | :- |

309| Il `CLAUDE.md` del tuo repository | Sì | Parte del clone |309| Il `CLAUDE.md` del tuo repository | Sì | Parte del clone |

310| Gli hook e le regole di permesso in `.claude/settings.json` del tuo repository | Sì, in una sessione con un solo repository | Parte del clone. Una sessione con più repository, incluso un thread di [progetto](/docs/it/claude-projects#what-threads-pick-up-from-your-repositories), parte al di sopra dei clone e non li legge |310| Gli hook e le regole di permesso in `.claude/settings.json` del tuo repository | Sì, in una sessione con un solo repository | Parte del clone. Per una sessione con più repository, consulta [quali impostazioni legge](/docs/it/settings#settings-in-cloud-sessions) |

311| I server MCP in `.mcp.json` del tuo repository | Sì, in una sessione con un solo repository | Parte del clone, trovato a partire dalla directory di lavoro della sessione |311| I server MCP in `.mcp.json` del tuo repository | Sì, in una sessione con un solo repository | Parte del clone, trovato a partire dalla directory di lavoro della sessione. Per un ambiente self-hosted, consulta [quali impostazioni del repository si applicano](/docs/it/self-hosted-environments-configuration#repository-settings-in-sessions-with-several-repositories) |

312| La directory `.claude/rules/` del tuo repository | Sì | Parte del clone |312| La directory `.claude/rules/` del tuo repository | Sì | Parte del clone |

313| Le directory `.claude/skills/`, `.claude/agents/`, `.claude/commands/` del tuo repository | Sì | Parte del clone |313| Le directory `.claude/skills/`, `.claude/agents/`, `.claude/commands/` del tuo repository | Sì | Parte del clone |

314| Plugin e marketplace dichiarati in `.claude/settings.json` del tuo repository | No | Una sessione cloud non installa i plugin che un repository attiva in [`enabledPlugins`](/docs/it/settings-reference#enabledplugins), inclusi quelli dei marketplace che elenca in [`extraKnownMarketplaces`](/docs/it/settings-reference#extraknownmarketplaces) |314| Plugin e marketplace dichiarati in `.claude/settings.json` del tuo repository | No | Una sessione cloud non installa i plugin che un repository attiva in [`enabledPlugins`](/docs/it/settings-reference#enabledplugins), inclusi quelli dei marketplace che elenca in [`extraKnownMarketplaces`](/docs/it/settings-reference#extraknownmarketplaces) |

575 575

576Gli hook SessionStart si comportano allo stesso modo nel cloud che localmente, con questi avvertimenti:576Gli hook SessionStart si comportano allo stesso modo nel cloud che localmente, con questi avvertimenti:

577 577

578* **Una repository per sessione**: una sessione con più repository non carica gli hook da nessuno dei `.claude/settings.json` della repository, quindi un hook SessionStart che si definisce lì non viene eseguito. Installare le dipendenze per quelle sessioni con uno [script di configurazione](#setup-scripts) invece.578* **Un repository per sessione**: in un ambiente ospitato da Anthropic, una sessione con più repository non carica gli hook dal `.claude/settings.json` di nessun repository, quindi un hook SessionStart che definisci lì non viene eseguito. Installa invece le dipendenze per quelle sessioni con uno [script di configurazione](#setup-scripts). Per un ambiente self-hosted, consulta [quali impostazioni del repository si applicano](/docs/it/self-hosted-environments-configuration#repository-settings-in-sessions-with-several-repositories).

579* **Nessun ambito solo cloud**: gli hook vengono eseguiti sia nelle sessioni locali che in quelle cloud. Per saltare l'esecuzione locale, uscire anticipatamente a meno che la variabile di ambiente `CLAUDE_CODE_REMOTE` non sia `true`, come fa lo [script di installazione delle dipendenze](#install-dependencies-with-a-sessionstart-hook).579* **Nessun ambito solo cloud**: gli hook vengono eseguiti sia nelle sessioni locali che in quelle cloud. Per saltare l'esecuzione locale, uscire anticipatamente a meno che la variabile di ambiente `CLAUDE_CODE_REMOTE` non sia `true`, come fa lo [script di installazione delle dipendenze](#install-dependencies-with-a-sessionstart-hook).

580* **Richiede accesso di rete**: i comandi di installazione devono raggiungere i registri dei pacchetti. Se l'ambiente utilizza accesso di rete **None**, questi hook non riescono. L'[elenco consentiti predefinito](#default-allowed-domains) sotto **Trusted** copre npm, PyPI, RubyGems e crates.io.580* **Richiede accesso di rete**: i comandi di installazione devono raggiungere i registri dei pacchetti. Se l'ambiente utilizza accesso di rete **None**, questi hook non riescono. L'[elenco consentiti predefinito](#default-allowed-domains) sotto **Trusted** copre npm, PyPI, RubyGems e crates.io.

581* **Compatibilità proxy**: negli ambienti ospitati da Anthropic, tutto il traffico in uscita passa attraverso un [proxy di sicurezza](#security-proxy), e alcuni gestori di pacchetti non funzionano correttamente con esso; Bun è un esempio noto. In un [ambiente self-hosted](/docs/it/self-hosted-environments-deploy#default-deny-egress), il traffico in uscita passa attraverso il proprio confine di rete.581* **Compatibilità proxy**: negli ambienti ospitati da Anthropic, tutto il traffico in uscita passa attraverso un [proxy di sicurezza](#security-proxy), e alcuni gestori di pacchetti non funzionano correttamente con esso; Bun è un esempio noto. In un [ambiente self-hosted](/docs/it/self-hosted-environments-deploy#default-deny-egress), il traffico in uscita passa attraverso il proprio confine di rete.

desktop.md +1 −1

Details

396 Lavora in parallelo con le sessioni396 Lavora in parallelo con le sessioni

397</h3>397</h3>

398 398

399Fai clic su **+ New session** nella barra laterale, o premi **Cmd+N** su macOS o **Ctrl+N** su Windows, per lavorare su più compiti in parallelo. Premi **Ctrl+Tab** e **Ctrl+Shift+Tab** per scorrere le sessioni nella barra laterale. Per i repository Git, seleziona l'opzione **worktree** accanto al nome del branch per dare alla sessione la sua copia isolata del tuo progetto usando [Git worktrees](/docs/it/worktrees), in modo che le modifiche in una sessione non influiscano su altre sessioni fino a quando non ne esegui il commit.399Fai clic su **+ New session** nella barra laterale, o premi **Cmd+N** su macOS o **Ctrl+N** su Windows, per lavorare su più compiti in parallelo. Premi **Ctrl+Tab** e **Ctrl+Shift+Tab** per scorrere le sessioni nella barra laterale. Per i repository Git, seleziona l'opzione **worktree** accanto al nome del branch per dare alla sessione la sua copia isolata del tuo progetto usando [Git worktrees](/docs/it/worktrees).

400 400

401Per visualizzare due sessioni contemporaneamente, tieni premuto **Cmd** su macOS o **Ctrl** su Windows e fai clic su una sessione nella barra laterale. La sessione si apre in un secondo riquadro accanto a quello che hai già aperto. Mentre la divisione è attiva, facendo clic su un'altra sessione della barra laterale si sostituisce il riquadro che ha il focus. Premi **Cmd+\\** su macOS o **Ctrl+\\** su Windows per chiudere il riquadro con focus e tornare a una singola sessione.401Per visualizzare due sessioni contemporaneamente, tieni premuto **Cmd** su macOS o **Ctrl** su Windows e fai clic su una sessione nella barra laterale. La sessione si apre in un secondo riquadro accanto a quello che hai già aperto. Mentre la divisione è attiva, facendo clic su un'altra sessione della barra laterale si sostituisce il riquadro che ha il focus. Premi **Cmd+\\** su macOS o **Ctrl+\\** su Windows per chiudere il riquadro con focus e tornare a una singola sessione.

402 402

env-vars.md +2 −1

Details

204| `CLAUDE_AFK_TIMEOUT_MS` | Quanti millisecondi di inattività devono trascorrere prima che una finestra di dialogo [`AskUserQuestion`](/docs/it/tools-reference) senza risposta continui automaticamente senza di te. La continuazione automatica è disattivata per impostazione predefinita; attivala con l'impostazione [`askUserQuestionTimeout`](/docs/it/settings-reference#askuserquestiontimeout). Questa variabile è un override per demo e test automatizzati: quando è impostata, ha la precedenza su quell'impostazione e attiva la continuazione automatica anche quando l'impostazione non è impostata o è `never`. Impostare `0` non disattiva il timeout, ma chiude immediatamente la finestra di dialogo. Ignorata nelle [impostazioni di progetto e locali](/docs/it/settings-reference#variables-claude-code-ignores-in-env). Prima della v2.1.200, la continuazione automatica era attiva per impostazione predefinita con un timeout di `60000` (60 secondi). Richiede Claude Code v2.1.198 o successiva |204| `CLAUDE_AFK_TIMEOUT_MS` | Quanti millisecondi di inattività devono trascorrere prima che una finestra di dialogo [`AskUserQuestion`](/docs/it/tools-reference) senza risposta continui automaticamente senza di te. La continuazione automatica è disattivata per impostazione predefinita; attivala con l'impostazione [`askUserQuestionTimeout`](/docs/it/settings-reference#askuserquestiontimeout). Questa variabile è un override per demo e test automatizzati: quando è impostata, ha la precedenza su quell'impostazione e attiva la continuazione automatica anche quando l'impostazione non è impostata o è `never`. Impostare `0` non disattiva il timeout, ma chiude immediatamente la finestra di dialogo. Ignorata nelle [impostazioni di progetto e locali](/docs/it/settings-reference#variables-claude-code-ignores-in-env). Prima della v2.1.200, la continuazione automatica era attiva per impostazione predefinita con un timeout di `60000` (60 secondi). Richiede Claude Code v2.1.198 o successiva |

205| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | Imposta su `1` per disattivare tutti i tipi di [subagent](/docs/it/sub-agents) integrati, come Explore e Plan. Si applica solo in modalità non interattiva (il flag `-p`). Utile per gli utenti dell'SDK che vogliono partire da zero. Questo rimuove anche `general-purpose`, il subagent che Claude Code esegue quando una chiamata allo strumento Agent omette `subagent_type`. Una chiamata di questo tipo fallisce quindi con [`subagent_type is required`](/docs/it/errors#subagent-type-is-required) |205| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | Imposta su `1` per disattivare tutti i tipi di [subagent](/docs/it/sub-agents) integrati, come Explore e Plan. Si applica solo in modalità non interattiva (il flag `-p`). Utile per gli utenti dell'SDK che vogliono partire da zero. Questo rimuove anche `general-purpose`, il subagent che Claude Code esegue quando una chiamata allo strumento Agent omette `subagent_type`. Una chiamata di questo tipo fallisce quindi con [`subagent_type is required`](/docs/it/errors#subagent-type-is-required) |

206| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | Imposta su `1` per omettere il prefisso `mcp__<server>__` dai nomi degli strumenti dei server MCP creati dall'SDK. Gli strumenti usano i loro nomi originali. Solo per l'uso dell'SDK |206| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | Imposta su `1` per omettere il prefisso `mcp__<server>__` dai nomi degli strumenti dei server MCP creati dall'SDK. Gli strumenti usano i loro nomi originali. Solo per l'uso dell'SDK |

207| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Timeout di stallo in millisecondi per i subagent. Predefinito `600000` (10 minuti); se aumenti `CLAUDE_STREAM_IDLE_TIMEOUT_MS` mentre il watchdog dello stream è attivo, il valore predefinito aumenta di conseguenza, come descritto in [Gestire risposte API lente o bloccate](/docs/it/agent-sdk/typescript#handle-slow-or-stalled-api-responses). Il timer si azzera a ogni evento di avanzamento dello streaming; se non arriva alcun avanzamento entro la finestra, Claude Code interrompe il subagent e segnala lo stallo al processo padre |207| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Timeout di stallo in millisecondi per i subagent. Copre anche gli [agenti dei workflow](/docs/it/workflows#when-an-agent-stalls-and-restarts) su Claude Code v2.1.286 o successiva. Predefinito `600000` (10 minuti); se aumenti `CLAUDE_STREAM_IDLE_TIMEOUT_MS` mentre il watchdog dello streaming è attivo, il valore predefinito aumenta di conseguenza, come descritto in [Gestire le risposte API lente o bloccate](/docs/it/agent-sdk/typescript#handle-slow-or-stalled-api-responses) |

208| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Imposta la percentuale (1-100) della finestra di compattazione automatica alla quale si attiva la compattazione automatica. Usa valori più bassi come `50` per compattare prima; la variabile non può alzare la soglia, quindi i valori superiori alla percentuale predefinita vengono ignorati. Si applica solo nelle sessioni che [compattano prima del limite di contesto del modello](/docs/it/model-config#context-window-and-auto-compaction). Si applica sia alle conversazioni principali sia ai subagent |208| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Imposta la percentuale (1-100) della finestra di compattazione automatica alla quale si attiva la compattazione automatica. Usa valori più bassi come `50` per compattare prima; la variabile non può alzare la soglia, quindi i valori superiori alla percentuale predefinita vengono ignorati. Si applica solo nelle sessioni che [compattano prima del limite di contesto del modello](/docs/it/model-config#context-window-and-auto-compaction). Si applica sia alle conversazioni principali sia ai subagent |

209| `CLAUDE_AUTO_BACKGROUND_TASKS` | Imposta su `1` per forzare l'attivazione dello spostamento automatico in background delle attività degli agenti a lunga esecuzione. Quando è attivo, i subagent vengono spostati in background dopo circa due minuti di esecuzione. Attiva anche lo [spostamento automatico in background delle chiamate lunghe agli strumenti MCP](/docs/it/mcp#automatic-backgrounding-of-long-tool-calls) in modalità non interattiva su Claude Code v2.1.212 o successiva |209| `CLAUDE_AUTO_BACKGROUND_TASKS` | Imposta su `1` per forzare l'attivazione dello spostamento automatico in background delle attività degli agenti a lunga esecuzione. Quando è attivo, i subagent vengono spostati in background dopo circa due minuti di esecuzione. Attiva anche lo [spostamento automatico in background delle chiamate lunghe agli strumenti MCP](/docs/it/mcp#automatic-backgrounding-of-long-tool-calls) in modalità non interattiva su Claude Code v2.1.212 o successiva |

210| `CLAUDE_AX_PREPARK_MS` | In [modalità screen reader](/docs/it/accessibility), quanti millisecondi Claude Code attende prima di scrivere una riga nuova o modificata. Predefinito `0`, quindi Claude Code non attende. Prima della v2.1.287, il valore predefinito era `50`. Claude Code limita l'attesa a `5000`. Richiede Claude Code v2.1.233 o successiva |210| `CLAUDE_AX_PREPARK_MS` | In [modalità screen reader](/docs/it/accessibility), quanti millisecondi Claude Code attende prima di scrivere una riga nuova o modificata. Predefinito `0`, quindi Claude Code non attende. Prima della v2.1.287, il valore predefinito era `50`. Claude Code limita l'attesa a `5000`. Richiede Claude Code v2.1.233 o successiva |

378| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | Età massima in millisecondi dell'ultimo messaggio della trascrizione affinché una sessione terminata a metà turno continui automaticamente alla ripresa. Quando l'ultimo messaggio è più vecchio di questo limite, Claude Code salta la ripresa automatica di `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` e il relativo messaggio di continuazione `CLAUDE_CODE_RESUME_PROMPT`, e la sessione si avvia inattiva, così prosegui in modo esplicito. Non impostata o `0` significa nessun limite, tranne per il fatto che un turno la cui ultima richiesta è fallita con un errore API riprende solo finché quell'errore ha meno di sei ore. Un valore positivo limita ogni turno, compresi quelli; un valore negativo o non numerico applica un limite di un'ora. Gli script di avvio per agenti a lunga esecuzione possono impostarla affinché un riavvio su una trascrizione vecchia non esegua di nuovo un prompt obsoleto. Claude Code imposta autonomamente un limite di un'ora quando riavvia una sessione della [vista agenti](/docs/it/agent-view) andata in crash che ha ereditato la conversazione da una sessione interattiva. Richiede Claude Code v2.1.211 o successiva |378| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | Età massima in millisecondi dell'ultimo messaggio della trascrizione affinché una sessione terminata a metà turno continui automaticamente alla ripresa. Quando l'ultimo messaggio è più vecchio di questo limite, Claude Code salta la ripresa automatica di `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` e il relativo messaggio di continuazione `CLAUDE_CODE_RESUME_PROMPT`, e la sessione si avvia inattiva, così prosegui in modo esplicito. Non impostata o `0` significa nessun limite, tranne per il fatto che un turno la cui ultima richiesta è fallita con un errore API riprende solo finché quell'errore ha meno di sei ore. Un valore positivo limita ogni turno, compresi quelli; un valore negativo o non numerico applica un limite di un'ora. Gli script di avvio per agenti a lunga esecuzione possono impostarla affinché un riavvio su una trascrizione vecchia non esegua di nuovo un prompt obsoleto. Claude Code imposta autonomamente un limite di un'ora quando riavvia una sessione della [vista agenti](/docs/it/agent-view) andata in crash che ha ereditato la conversazione da una sessione interattiva. Richiede Claude Code v2.1.211 o successiva |

379| `CLAUDE_CODE_RESUME_PROMPT` | Sovrascrive il messaggio di continuazione che Claude Code invia a Claude quando `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` continua un turno interrotto invece di inviarne di nuovo il prompt, o quando riprendi una [chiamata a uno strumento differita](/docs/it/hooks#defer-a-tool-call-for-later) con `-p`. Il valore predefinito è `Continue from where you left off.`. Una stringa vuota usa il valore predefinito |379| `CLAUDE_CODE_RESUME_PROMPT` | Sovrascrive il messaggio di continuazione che Claude Code invia a Claude quando `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` continua un turno interrotto invece di inviarne di nuovo il prompt, o quando riprendi una [chiamata a uno strumento differita](/docs/it/hooks#defer-a-tool-call-for-later) con `-p`. Il valore predefinito è `Continue from where you left off.`. Una stringa vuota usa il valore predefinito |

380| `CLAUDE_CODE_RETRY_WATCHDOG` | Imposta a `1` per sessioni non presidiate come harness di valutazione, job CI o worker remoti. Riprova indefinitamente in caso di errori di capacità `429` e `529` invece di fallire dopo `CLAUDE_CODE_MAX_RETRIES` tentativi. Claude Code fallisce subito quando una richiesta a velocità standard riceve un `429` che segnala un limite di spesa o crediti di utilizzo esauriti, anche se proviene da un [limite di spesa del gateway](/docs/it/errors#spend-limit-reached) che si azzera secondo una pianificazione. Prima della v2.1.239, il watchdog riprovava indefinitamente anche in questi casi. Per le richieste in modalità veloce, consulta [Gestire i rate limit](/docs/it/fast-mode#handle-rate-limits). Il watchdog attende fino a 5 minuti tra un tentativo e l'altro, o fino all'azzeramento del limite quando la risposta riporta un orario di azzeramento del rate limit, così una sessione che raggiunge un limite di utilizzo attende la fine della finestra rimanente. Nella v2.1.199 o successiva aumenta inoltre a 300 il numero predefinito di nuovi tentativi per altri errori transitori, come errori del server, timeout e connessioni interrotte, pari a circa tre ore di backoff, e rimuove il limite di 15 su `CLAUDE_CODE_MAX_RETRIES` se imposti esplicitamente quella variabile. Richiede Claude Code v2.1.186 o successiva |380| `CLAUDE_CODE_RETRY_WATCHDOG` | Imposta a `1` per sessioni non presidiate come harness di valutazione, job CI o worker remoti. Riprova indefinitamente in caso di errori di capacità `429` e `529` invece di fallire dopo `CLAUDE_CODE_MAX_RETRIES` tentativi. Claude Code fallisce subito quando una richiesta a velocità standard riceve un `429` che segnala un limite di spesa o crediti di utilizzo esauriti, anche se proviene da un [limite di spesa del gateway](/docs/it/errors#spend-limit-reached) che si azzera secondo una pianificazione. Prima della v2.1.239, il watchdog riprovava indefinitamente anche in questi casi. Per le richieste in modalità veloce, consulta [Gestire i rate limit](/docs/it/fast-mode#handle-rate-limits). Il watchdog attende fino a 5 minuti tra un tentativo e l'altro, o fino all'azzeramento del limite quando la risposta riporta un orario di azzeramento del rate limit, così una sessione che raggiunge un limite di utilizzo attende la fine della finestra rimanente. Nella v2.1.199 o successiva aumenta inoltre a 300 il numero predefinito di nuovi tentativi per altri errori transitori, come errori del server, timeout e connessioni interrotte, pari a circa tre ore di backoff, e rimuove il limite di 15 su `CLAUDE_CODE_MAX_RETRIES` se imposti esplicitamente quella variabile. Richiede Claude Code v2.1.186 o successiva |

381| `CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS` | Tempo massimo in millisecondi che ogni richiesta API trascorre in attesa durante gli errori `429` e `529` quando `CLAUDE_CODE_RETRY_WATCHDOG` è impostata. Una volta trascorso quel tempo, l'errore successivo di questo tipo termina la richiesta. Indica un numero intero positivo in cifre semplici, come `1800000` per 30 minuti. Quando non è impostata, l'attesa non ha limiti. Richiede Claude Code v2.1.295 o successiva |

381| `CLAUDE_CODE_SAFE_MODE` | Imposta a `1` per avviare in modalità provvisoria: CLAUDE.md, skill, plugin, hook, server MCP, comandi e agenti personalizzati, stili di output, workflow, temi personalizzati, scorciatoie da tastiera personalizzate, comandi della riga di stato e dei suggerimenti di file, server LSP e memoria automatica non vengono caricati, per la risoluzione dei problemi di una configurazione danneggiata. La policy delle impostazioni gestite continua ad applicarsi, inclusi gli hook, la riga di stato e i comandi dei suggerimenti di file configurati tramite policy; i plugin gestiti, le skill gestite, il CLAUDE.md gestito e i server MCP configurati tramite policy invece no. Equivale a passare [`--safe-mode`](/docs/it/cli-reference#cli-flags). I processi figli avviati direttamente ereditano la variabile |382| `CLAUDE_CODE_SAFE_MODE` | Imposta a `1` per avviare in modalità provvisoria: CLAUDE.md, skill, plugin, hook, server MCP, comandi e agenti personalizzati, stili di output, workflow, temi personalizzati, scorciatoie da tastiera personalizzate, comandi della riga di stato e dei suggerimenti di file, server LSP e memoria automatica non vengono caricati, per la risoluzione dei problemi di una configurazione danneggiata. La policy delle impostazioni gestite continua ad applicarsi, inclusi gli hook, la riga di stato e i comandi dei suggerimenti di file configurati tramite policy; i plugin gestiti, le skill gestite, il CLAUDE.md gestito e i server MCP configurati tramite policy invece no. Equivale a passare [`--safe-mode`](/docs/it/cli-reference#cli-flags). I processi figli avviati direttamente ereditano la variabile |

382| `CLAUDE_CODE_SCRIPT_CAPS` | Oggetto JSON che limita quante volte script specifici possono essere invocati per sessione quando è impostata `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`. Le chiavi sono sottostringhe confrontate con il testo del comando; i valori sono limiti interi di chiamate. Ad esempio, `{"deploy.sh": 2}` consente di chiamare `deploy.sh` al massimo due volte. Il confronto si basa sulle sottostringhe, quindi trucchi di espansione della shell come `./scripts/deploy.sh $(evil)` vengono comunque conteggiati nel limite. Il fan-out a runtime tramite `xargs` o `find -exec` non viene rilevato; si tratta di un controllo di difesa in profondità |383| `CLAUDE_CODE_SCRIPT_CAPS` | Oggetto JSON che limita quante volte script specifici possono essere invocati per sessione quando è impostata `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`. Le chiavi sono sottostringhe confrontate con il testo del comando; i valori sono limiti interi di chiamate. Ad esempio, `{"deploy.sh": 2}` consente di chiamare `deploy.sh` al massimo due volte. Il confronto si basa sulle sottostringhe, quindi trucchi di espansione della shell come `./scripts/deploy.sh $(evil)` vengono comunque conteggiati nel limite. Il fan-out a runtime tramite `xargs` o `find -exec` non viene rilevato; si tratta di un controllo di difesa in profondità |

383| `CLAUDE_CODE_SCROLL_SPEED` | Imposta il moltiplicatore di scorrimento della rotella del mouse nel [rendering a schermo intero](/docs/it/fullscreen#mouse-wheel-scrolling). Accetta qualsiasi valore positivo fino a 20, inclusi valori frazionari inferiori a 1 come `0.5` per rallentare lo scorrimento accelerato di trackpad e rotella nei terminali che già amplificano gli eventi della rotella. Imposta a `3` per allinearti a `vim` se il tuo terminale invia un evento della rotella per scatto senza amplificazione. Ignorata nel terminale degli IDE JetBrains, dove Claude Code usa una propria gestione dello scorrimento |384| `CLAUDE_CODE_SCROLL_SPEED` | Imposta il moltiplicatore di scorrimento della rotella del mouse nel [rendering a schermo intero](/docs/it/fullscreen#mouse-wheel-scrolling). Accetta qualsiasi valore positivo fino a 20, inclusi valori frazionari inferiori a 1 come `0.5` per rallentare lo scorrimento accelerato di trackpad e rotella nei terminali che già amplificano gli eventi della rotella. Imposta a `3` per allinearti a `vim` se il tuo terminale invia un evento della rotella per scatto senza amplificazione. Ignorata nel terminale degli IDE JetBrains, dove Claude Code usa una propria gestione dello scorrimento |

errors.md +1 −1

Details

4064 Marketplace è già aggiunto da una fonte diversa4064 Marketplace è già aggiunto da una fonte diversa

4065</h3>4065</h3>

4066 4066

4067Hai confermato l'aggiunta di un marketplace tramite [`/plugin install <plugin> --marketplace <source>`](/docs/it/plugins/install#add-a-marketplace-and-install-in-one-command), e il catalogo che Claude Code ha recuperato da quella fonte nomina se stesso come un marketplace che hai già aggiunto da una fonte diversa. Claude Code mantiene il marketplace esistente invece di sostituirlo, e il plugin non viene installato.4067Hai indicato una nuova fonte di marketplace con [`--marketplace <source>` nel comando di installazione](/docs/it/plugins/install#add-a-marketplace-and-install-in-one-command), in una sessione o dalla tua shell. Il catalogo che Claude Code ha recuperato da quella fonte ha lo stesso nome di un marketplace che hai già aggiunto da una fonte diversa. Claude Code mantiene il marketplace esistente invece di sostituirlo, e il plugin non viene installato.

4068 4068

4069```text theme={null}4069```text theme={null}

4070Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.4070Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

glossary.md +1 −1

Details

511 Worktree isolation511 Worktree isolation

512</h3>512</h3>

513 513

514Una modalità di isolamento che esegue Claude in un worktree git separato in `.claude/worktrees/`, abilitata con il flag `-w` o `isolation: worktree` nella configurazione del subagent. Le modifiche rimangono su un branch separato in una directory separata, in modo che gli agenti paralleli non sovrascrivano i file l'uno dell'altro.514Una modalità di isolamento che esegue Claude in un worktree git separato in `.claude/worktrees/`, abilitata con il flag `-w` o `isolation: worktree` nella configurazione del subagent. Le modifiche rimangono su un branch separato in una directory separata, in modo che ogni agente parallelo modifichi la propria copia dei file.

515 515

516Scopri di più: [Run parallel sessions with git worktrees](/docs/it/worktrees)516Scopri di più: [Run parallel sessions with git worktrees](/docs/it/worktrees)

517 517

hooks.md +19 −8

Details

1237 Controllo delle decisioni di SessionStart1237 Controllo delle decisioni di SessionStart

1238</h4>1238</h4>

1239 1239

1240Claude Code aggiunge al contesto di Claude lo stdout che [tratta come testo semplice](#exit-code-0). Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, puoi restituire questi campi specifici dell'evento:1240Un hook SessionStart può aggiungere contesto per Claude, fornire il primo messaggio dell'utente, impostare il titolo della sessione, monitorare file e ricaricare le skill. Restituisci il campo corrispondente a ciascuna di queste azioni, oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook:

1241 1241

1242| Campo | Descrizione |1242| Campo | Descrizione |

1243| :- | :- |1243| :- | :- |

1244| `additionalContext` | Stringa aggiunta al contesto di Claude all'inizio della conversazione, prima del primo prompt. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) per sapere come viene consegnato il testo e cosa inserirvi |1244| `additionalContext` | Stringa aggiunta al contesto di Claude all'inizio della conversazione, prima del primo prompt. Consulta [Aggiungere contesto per Claude](#add-context-for-claude) per sapere come viene consegnato il testo e cosa inserirvi |

1245| `initialUserMessage` | Stringa usata come primo messaggio utente della sessione. Si applica in [modalità non interattiva](/docs/it/headless) con il flag `-p`, dove diventa il primo turno anche se non viene fornito alcun prompt. Se viene fornito un prompt, questo segue come turno successivo. A differenza di `additionalContext`, che si collega a un turno esistente, questo crea il turno |1245| `initialUserMessage` | Stringa usata come primo messaggio dell'utente della sessione, in [modalità non interattiva](/docs/it/headless) con il flag `-p`. Diventa il primo turno anche se non passi alcun prompt. Un prompt che passi lo segue come turno successivo |

1246| `sessionTitle` | Imposta il titolo della sessione, con lo stesso effetto di `/rename`. Usalo per assegnare automaticamente un nome alle sessioni in base alla cartella di avvio, al branch git o al nome del worktree. Si applica quando `source` è `"startup"`, `"resume"` o `"fork"`; viene ignorato con `"clear"` e `"compact"` |1246| `sessionTitle` | Imposta il titolo della sessione, con lo stesso effetto di `/rename`. Si applica quando `source` è `"startup"`, `"resume"` o `"fork"` |

1247| `watchPaths` | Array di percorsi assoluti da monitorare per gli eventi [FileChanged](#filechanged) durante questa sessione |1247| `watchPaths` | Array di percorsi assoluti da monitorare per gli eventi [FileChanged](#filechanged) durante questa sessione |

1248| `reloadSkills` | Booleano. Quando è `true`, Claude Code esegue una nuova scansione delle directory delle [skill](/docs/it/skills) e dei comandi dopo il completamento degli hook SessionStart, così le skill installate dall'hook sono disponibili nella stessa sessione, a partire dal primo prompt |1248| `reloadSkills` | Booleano. Quando è `true`, Claude Code analizza di nuovo le directory delle [skill](/docs/it/skills) e dei comandi dopo il completamento degli hook SessionStart. Consulta [Ricaricare le skill installate da un hook](#reload-skills-that-a-hook-installs) |

1249

1250Questo output aggiunge contesto e assegna un nome alla sessione:

1249 1251

1250```json theme={null}1252```json theme={null}

1251{1253{

1257}1259}

1258```1260```

1259 1261

1260Poiché per questo evento lo stdout semplice raggiunge già Claude, un hook che carica solo contesto può stampare direttamente su stdout senza costruire JSON. Usa la forma JSON quando devi combinare il contesto con altri campi come `sessionTitle`.1262Un hook che aggiunge solo contesto può stamparlo senza costruire JSON, perché Claude Code aggiunge lo [stdout in testo semplice](#exit-code-0) di un hook SessionStart al contesto di Claude.

1263

1264Se l'hook SessionStart del tuo plugin fornisce `initialUserMessage` o `sessionTitle`, installa il plugin prima dell'avvio della sessione. Claude Code ignora entrambi i campi provenienti da un plugin la cui installazione termina dopo che gli hook SessionStart sono stati eseguiti.

1265

1266<h4 id="reload-skills-that-a-hook-installs">

1267 Ricaricare le skill installate da un hook

1268</h4>

1269

1270Per rendere disponibili nella stessa sessione le skill installate da un hook SessionStart, restituisci `reloadSkills`. Il rilevamento delle skill viene normalmente eseguito prima che gli hook SessionStart terminino, quindi senza questo campo i file che un hook scrive in `~/.claude/skills/` o `.claude/skills/` possono mancare quando viene eseguito il primo prompt.

1261 1271

1262Usa `reloadSkills` quando un hook SessionStart installa o aggiorna skill. Il rilevamento delle skill normalmente viene eseguito prima che gli hook SessionStart terminino, quindi i file che l'hook scrive in `~/.claude/skills/` o `.claude/skills/` altrimenti apparirebbero solo nella sessione successiva. Questo esempio sincronizza un repository di skill condiviso e richiede la nuova scansione:1272Questo esempio sincronizza un repository di skill condiviso e richiede la nuova analisi:

1263 1273

1264```bash theme={null}1274```bash theme={null}

1265#!/bin/bash1275#!/bin/bash

1270echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1280echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'

1271```1281```

1272 1282

1273L'URL del repository è un segnaposto; sostituiscilo con il tuo repository di skill. Con il segnaposto, il clone fallisce e stampa un messaggio `fatal:` su stderr. Lo stderr di un hook SessionStart che esce con 0 è solo informativo, quindi la richiesta `reloadSkills` si applica comunque.1283L'URL del repository è un segnaposto. Sostituiscilo con il tuo repository di skill.

1274 1284

1275<h4 id="persist-environment-variables">1285<h4 id="persist-environment-variables">

1276 Rendere persistenti le variabili d'ambiente1286 Rendere persistenti le variabili d'ambiente

1860| :- | :- | :- | :- |1870| :- | :- | :- | :- |

1863 1874

1864<h5 id="websearch">1875<h5 id="websearch">

1865 WebSearch1876 WebSearch

4279Gli hook asincroni hanno vincoli aggiuntivi rispetto agli hook sincroni:4290Gli hook asincroni hanno vincoli aggiuntivi rispetto agli hook sincroni:

4280 4291

4281* L'output del hook viene consegnato al turno di conversazione successivo. Se la sessione è inattiva, la risposta attende fino alla prossima interazione dell'utente. Eccezione: un hook `asyncRewake` che esce con il codice 2 riattiva Claude immediatamente anche quando la sessione è inattiva.4292* L'output del hook viene consegnato al turno di conversazione successivo. Se la sessione è inattiva, la risposta attende fino alla prossima interazione dell'utente. Eccezione: un hook `asyncRewake` che esce con il codice 2 riattiva Claude immediatamente anche quando la sessione è inattiva.

4282* Ogni esecuzione crea un processo in background separato. Non c'è deduplicazione tra più attivazioni dello stesso hook asincrono.4293* Ogni esecuzione crea un processo in background separato.

4283 4294

4284<h2 id="security-considerations">4295<h2 id="security-considerations">

4285 Considerazioni sulla sicurezza4296 Considerazioni sulla sicurezza

monitoring-usage.md +4 −0

Details

599 599

600In sessioni autenticate a un [gateway di app Claude](/docs/it/claude-apps-gateway) tramite `/login`, la CLI contrassegna le esportazioni con l'identità autenticata: `user.id` è il soggetto IdP, `user.email` è l'email con cui hai effettuato l'accesso, e `user.groups` contiene l'appartenenza al gruppo IdP come stringa separata da virgole. Ogni esportazione contiene anche `identity.source: gateway-oidc`. L'identità del gateway viene applicata per ultima, quindi le chiavi `user.*` e `identity.*` impostate tramite `OTEL_RESOURCE_ATTRIBUTES` vengono ignorate sulle sessioni del gateway.600In sessioni autenticate a un [gateway di app Claude](/docs/it/claude-apps-gateway) tramite `/login`, la CLI contrassegna le esportazioni con l'identità autenticata: `user.id` è il soggetto IdP, `user.email` è l'email con cui hai effettuato l'accesso, e `user.groups` contiene l'appartenenza al gruppo IdP come stringa separata da virgole. Ogni esportazione contiene anche `identity.source: gateway-oidc`. L'identità del gateway viene applicata per ultima, quindi le chiavi `user.*` e `identity.*` impostate tramite `OTEL_RESOURCE_ATTRIBUTES` vengono ignorate sulle sessioni del gateway.

601 601

602<Note>

603 Gli eventi che Claude Code registra prima che uno sviluppatore acceda non riportano l'identità del gateway. Quando Claude Code apre una sessione senza accesso al gateway, ad esempio dopo che [il gateway ha terminato l'accesso](/docs/it/errors#cloud-gateway-session-expired), gli eventi di avvio registrati prima dell'accesso riportano lo `user.id` anonimo e nessun `identity.source`. Tra questi ci sono [`managed_settings_resolved`](#managed-settings-resolved-event), [`plugin_loaded`](#plugin-loaded-event) e [`mcp_server_connection`](#mcp-server-connection-event).

604</Note>

605

602Per gli attributi di identità su sessioni Claude Desktop e Cowork che si connettono tramite un gateway, vedi il [riferimento `telemetry` del gateway](/docs/it/claude-apps-gateway-config#telemetry).606Per gli attributi di identità su sessioni Claude Desktop e Cowork che si connettono tramite un gateway, vedi il [riferimento `telemetry` del gateway](/docs/it/claude-apps-gateway-config#telemetry).

603 607

604Gli eventi includono inoltre i seguenti attributi. Questi non vengono mai allegati alle metriche perché causerebbero cardinalità illimitata:608Gli eventi includono inoltre i seguenti attributi. Questi non vengono mai allegati alle metriche perché causerebbero cardinalità illimitata:

plugins/cli-reference.md +1 −0

Details

91| `-y, --yes` | Accetta il comando di installazione visualizzato senza il prompt `Run this command now?`. Ignorato quando il comando viene eseguito all'interno di una sessione Claude Code, ad esempio dallo strumento Bash o da un hook. Richiede Claude Code v2.1.229 o successivo |91| `-y, --yes` | Accetta il comando di installazione visualizzato senza il prompt `Run this command now?`. Ignorato quando il comando viene eseguito all'interno di una sessione Claude Code, ad esempio dallo strumento Bash o da un hook. Richiede Claude Code v2.1.229 o successivo |

92| `--accept-command <sha256>` | Accetta il comando di installazione visualizzato il cui `sha256` un'esecuzione precedente [`--json`](#plugin-json-result) ha riportato in `shownCommand`, al posto di `-y`. Non può essere combinato con `-y`. Vedi [Accetta un comando di installazione visualizzato](#accept-a-displayed-install-command). Richiede Claude Code v2.1.271 o successivo |92| `--accept-command <sha256>` | Accetta il comando di installazione visualizzato il cui `sha256` un'esecuzione precedente [`--json`](#plugin-json-result) ha riportato in `shownCommand`, al posto di `-y`. Non può essere combinato con `-y`. Vedi [Accetta un comando di installazione visualizzato](#accept-a-displayed-install-command). Richiede Claude Code v2.1.271 o successivo |

93| `--json` | Stampa il risultato come un oggetto JSON sull'ultima riga di stdout invece del messaggio leggibile, per l'uso negli script. Vedi [Formato risultato JSON](#plugin-json-result). Richiede Claude Code v2.1.268 o successivo |93| `--json` | Stampa il risultato come un oggetto JSON sull'ultima riga di stdout invece del messaggio leggibile, per l'uso negli script. Vedi [Formato risultato JSON](#plugin-json-result). Richiede Claude Code v2.1.268 o successivo |

94| `--marketplace <source>` | Installa `<plugin>`, indicato con il suo nome semplice, dal marketplace in `<source>`, aggiungendo prima il marketplace se non l'hai ancora aggiunto. Vedi [Aggiungi un marketplace e installa con un solo comando](/docs/it/plugins/install#add-a-marketplace-and-install-in-one-command). Richiede Claude Code v2.1.292 o successivo |

94 95

95Esegui `claude plugin install --help` nella tua shell per vedere ogni opzione che la tua versione supporta.96Esegui `claude plugin install --help` nella tua shell per vedere ogni opzione che la tua versione supporta.

96 97

plugins/install.md +20 −4

Details

189 189

190* **Scope**: ambito utente per impostazione predefinita. Passa `--scope project` o `--scope local` per cambiarlo.190* **Scope**: ambito utente per impostazione predefinita. Passa `--scope project` o `--scope local` per cambiarlo.

191* **Quando i plugin si caricano**: i plugin che installa si caricano la prossima volta che avvii Claude Code, o quando esegui `/reload-plugins` in una sessione già aperta.191* **Quando i plugin si caricano**: i plugin che installa si caricano la prossima volta che avvii Claude Code, o quando esegui `/reload-plugins` in una sessione già aperta.

192* **Il marketplace deve essere aggiunto prima**: su una macchina in cui nessuno ha ancora aperto una sessione Claude Code interattiva, il marketplace ufficiale non è registrato, quindi uno script che installa da esso esegue `claude plugin marketplace add anthropics/claude-plugins-official` prima dell'installazione.192* **Il marketplace su una nuova macchina**: su una macchina in cui nessuno ha ancora aperto una sessione Claude Code interattiva, il marketplace ufficiale non è registrato, quindi uno script che installa da esso esegue `claude plugin marketplace add anthropics/claude-plugins-official` prima dell'installazione. Vedi [Aggiungere e installare dalla tua shell](#add-and-install-from-your-shell).

193 193

194```bash theme={null}194```bash theme={null}

195claude plugin install formatter@your-org --scope project195claude plugin install formatter@your-org --scope project

232 Aggiungi un marketplace e installa in un comando232 Aggiungi un marketplace e installa in un comando

233</h3>233</h3>

234 234

235Per installare un plugin da un marketplace che non hai ancora aggiunto, esegui `/plugin install` in una sessione Claude Code e nomina la fonte del marketplace con `--marketplace`. Richiede Claude Code v2.1.275 o successivo.235Per installare un plugin da un marketplace che non hai ancora aggiunto, indica la fonte del marketplace con `--marketplace` nel comando di installazione, in una sessione o dalla tua shell. La fonte accetta [le stesse forme di `/plugin marketplace add`](#add-a-marketplace), come GitHub `owner/repo`, un URL git o un percorso locale. Dai il nome del plugin da solo, senza un suffisso `@marketplace`.

236

237<h4 id="add-and-install-in-a-session">

238 Aggiungi e installa in una sessione

239</h4>

240

241Esegui `/plugin install` in una sessione Claude Code con il plugin e la fonte. Richiede Claude Code v2.1.275 o successivo. In una sessione, la fonte non può contenere spazi.

236 242

237```text theme={null}243```text theme={null}

238/plugin install deploy-helper --marketplace your-org/plugins244/plugin install deploy-helper --marketplace your-org/plugins

239```245```

240 246

241La fonte accetta [le stesse forme di `/plugin marketplace add`](#add-a-marketplace), come GitHub `owner/repo`, un URL git o un percorso locale, tranne che non può contenere spazi. Dai il nome del plugin da solo, senza un suffisso `@marketplace`.

~~242~~

243Se non hai ancora aggiunto quel marketplace, Claude Code mostra la fonte che ha risolto e ti chiede di confermare prima di aggiungerla. Una volta aggiunto il marketplace, i dettagli del plugin si aprono e scegli un [ambito di installazione](#install-a-plugin). Se la fonte corrisponde a un marketplace che hai già aggiunto, Claude Code salta la conferma e apre i dettagli del plugin in quel marketplace.247Se non hai ancora aggiunto quel marketplace, Claude Code mostra la fonte che ha risolto e ti chiede di confermare prima di aggiungerla. Una volta aggiunto il marketplace, i dettagli del plugin si aprono e scegli un [ambito di installazione](#install-a-plugin). Se la fonte corrisponde a un marketplace che hai già aggiunto, Claude Code salta la conferma e apre i dettagli del plugin in quel marketplace.

244 248

249<h4 id="add-and-install-from-your-shell">

250 Aggiungi e installa dalla tua shell

251</h4>

252

253Nella tua shell, senza avviare una sessione, esegui `claude plugin install` con il plugin e la fonte. Richiede Claude Code v2.1.292 o successivo.

254

255```bash theme={null}

256claude plugin install deploy-helper --marketplace your-org/plugins

257```

258

259Il comando della shell aggiunge il marketplace senza un passaggio di conferma. Un marketplace che hai già aggiunto da quella fonte viene riutilizzato. Uno nuovo viene aggiunto con gli stessi [controlli delle policy dell'organizzazione](/docs/it/plugins/org#restrict-what-users-can-install) di `claude plugin marketplace add` e viene dichiarato nelle tue impostazioni utente anche quando passi `--scope project`.

260

245<h3 id="add-a-private-marketplace">261<h3 id="add-a-private-marketplace">

246 Aggiungi un marketplace privato262 Aggiungi un marketplace privato

247</h3>263</h3>

plugins/mods/admin.md +1 −1

Details

141| `$.session.send` | Invia un messaggio che viene letto dal Claude di un'altra sessione o di un subagent |141| `$.session.send` | Invia un messaggio che viene letto dal Claude di un'altra sessione, di un subagent o di un [compagno di team](/docs/it/agent-teams) |

142 142

143Nella riga `hooks:`, [`tool.call`](/docs/it/plugins/mods/reference#tools) e [`prompt.submit`](/docs/it/plugins/mods/reference#prompts-and-what-claude-reads) indicano che il mod vede ogni chiamata a uno strumento e ogni prompt, e può modificarli. [`session.append`](/docs/it/plugins/mods/reference#session) indica che il mod può riscrivere ogni riga della conversazione prima che venga memorizzata. [`ui.render{component=AskUserQuestion}`](/docs/it/plugins/mods/interface#change-what-claude-code-already-draws) indica che il mod può ridisegnare la finestra di dialogo che Claude usa per porre una domanda all'utente. `tool.check` indica che il mod può approvare o negare una chiamata a uno strumento prima che compaia una richiesta di permesso. [Sapere cosa succede per impostazione predefinita](#know-what-happens-by-default) elenca quali delle tue regole e dei tuoi hook hanno la precedenza sulla sua risposta.143Nella riga `hooks:`, [`tool.call`](/docs/it/plugins/mods/reference#tools) e [`prompt.submit`](/docs/it/plugins/mods/reference#prompts-and-what-claude-reads) indicano che il mod vede ogni chiamata a uno strumento e ogni prompt, e può modificarli. [`session.append`](/docs/it/plugins/mods/reference#session) indica che il mod può riscrivere ogni riga della conversazione prima che venga memorizzata. [`ui.render{component=AskUserQuestion}`](/docs/it/plugins/mods/interface#change-what-claude-code-already-draws) indica che il mod può ridisegnare la finestra di dialogo che Claude usa per porre una domanda all'utente. `tool.check` indica che il mod può approvare o negare una chiamata a uno strumento prima che compaia una richiesta di permesso. [Sapere cosa succede per impostazione predefinita](#know-what-happens-by-default) elenca quali delle tue regole e dei tuoi hook hanno la precedenza sulla sua risposta.

144 144

plugins/mods/api.md +10 −2

Details

140| Chiamata | Cosa vede l'utente |140| Chiamata | Cosa vede l'utente |

141| :- | :- |141| :- | :- |

142| `$.ui.status(text)` | Una riga sotto il prompt che rimane finché non la modifichi. Inizia con `⚠` e il nome del mod, come in `⚠ my-mod: checks: 3 passing`. |142| `$.ui.status(text)` | Una riga sotto il prompt che rimane finché non la modifichi. Inizia con `⚠` e il nome del mod, come in `⚠ my-mod: checks: 3 passing`. |

143| `$.ui.toast(text)` | Una notifica toast in alto a destra, con il nome del mod sopra il testo, che scompare dopo qualche secondo |143| `$.ui.toast(text)` | Una notifica toast con il nome del mod che scompare dopo qualche secondo. È un riquadro in alto a destra nel [rendering a schermo intero](/docs/it/fullscreen), e una riga a destra sotto il prompt nel renderer classico. |

144| `$.ui.log(text)` | Una riga attenuata nella trascrizione che Claude non legge. Inizia con `●` e il nome del mod, come in `● my-mod: build finished`. |144| `$.ui.log(text)` | Una riga attenuata nella trascrizione che Claude non legge. Inizia con `●` e il nome del mod, come in `● my-mod: build finished`. |

145 145

146<h3 id="start-a-turn-from-a-background-job">146<h3 id="start-a-turn-from-a-background-job">

159 Inviare e ricevere messaggi tra sessioni159 Inviare e ricevere messaggi tra sessioni

160</h2>160</h2>

161 161

162Un mod può inviare un messaggio di testo semplice a un'altra delle tue sessioni o a uno dei subagent di questa sessione, e osservare i messaggi che arrivano e partono. `$.session.send({ to, text })` ne invia uno, con la stessa consegna effettuata dallo strumento SendMessage. `to` è `{ sessionId }` per una sessione, `{ agentId }` per un subagent ottenuto da `$.agent.list()`, oppure l'indirizzo stringa da cui proviene un messaggio ricevuto. La chiamata si risolve non appena il messaggio viene messo in coda, con `{ isDelivered: true }`. Quando non è stato consegnato nulla, si risolve con `{ isDelivered: false, reason }`, e `reason` ne indica il motivo.162Un mod può inviare un messaggio di testo semplice a un'altra delle tue sessioni, a uno dei subagent di questa sessione o a un membro del suo [team di agenti](/docs/it/agent-teams). Può anche osservare i messaggi che arrivano e partono.

163

164Per inviarne uno, chiama `$.session.send({ to, text })`, che effettua la stessa consegna dello strumento SendMessage. Imposta `to` in base a chi riceve il messaggio:

165

166* **Un'altra delle tue sessioni**: `{ sessionId }`

167* **Un subagent o un membro del team**: `{ agentId }`, con un id ottenuto da `$.agent.list()`

168* **Il mittente di un messaggio che hai ricevuto**: l'indirizzo stringa da cui proviene quel messaggio

169

170La chiamata si risolve non appena il messaggio viene messo in coda, con `{ isDelivered: true }`. Quando non è stato consegnato nulla, si risolve con `{ isDelivered: false, reason }`, e `reason` ne indica il motivo.

163 171

164Questo hook risponde a un comando `/ping`, [registrato come comando](#add-a-command), chiedendo uno stato alla sessione il cui id digiti dopo di esso:172Questo hook risponde a un comando `/ping`, [registrato come comando](#add-a-command), chiedendo uno stato alla sessione il cui id digiti dopo di esso:

165 173

plugins/mods/events.md +2 −0

Details

281 281

282`result.usage` contiene i conteggi di token che la Claude API riporta per una richiesta, più il `model` che ha risposto: `input_tokens`, `output_tokens`, `cache_read_input_tokens` e `cache_creation_input_tokens`. L'hook viene eseguito anche per le richieste dei subagent, quindi controlla `e.agentId` quando vuoi solo la conversazione principale.282`result.usage` contiene i conteggi di token che la Claude API riporta per una richiesta, più il `model` che ha risposto: `input_tokens`, `output_tokens`, `cache_read_input_tokens` e `cache_creation_input_tokens`. L'hook viene eseguito anche per le richieste dei subagent, quindi controlla `e.agentId` quando vuoi solo la conversazione principale.

283 283

284Per vedere le chiamate agli strumenti che l'API ha eseguito autonomamente durante la richiesta, come le chiamate allo [strumento advisor](/docs/it/advisor), leggi `result.serverToolUses`. Claude Code non esegue queste chiamate, quindi nessun hook `tool.call` o `tool.check` si attiva per esse. Il campo è assente quando la risposta non contiene chiamate di questo tipo e richiede Claude Code v2.1.290 o successivo.

285

284<h3 id="hook-the-settings-hook-events">286<h3 id="hook-the-settings-hook-events">

285 Gestire gli eventi degli hook delle impostazioni287 Gestire gli eventi degli hook delle impostazioni

286</h3>288</h3>

plugins/mods/interface.md +11 −3

Details

10 10

11Questa mappa mostra dove un mod può disegnare in una sessione del terminale:11Questa mappa mostra dove un mod può disegnare in una sessione del terminale:

12 12

13<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5fda26b6609c62b68c6f9e528c1590ea" className="dark:hidden" alt="Mappa di una sessione del terminale di Claude Code. Un mod può aggiungere un riquadro come barra laterale a destra, un toast in alto a destra della trascrizione, una riga di log nella trascrizione, una fascia sopra il prompt e una riga di stato sotto il prompt. Un mod può ridisegnare i messaggi, le righe delle chiamate agli strumenti e lo spinner. Il prompt appartiene a Claude Code." width="600" height="336" data-path="images/mods-screen-map.svg" />13<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5fda26b6609c62b68c6f9e528c1590ea" className="dark:hidden" alt="Mappa di una sessione del terminale di Claude Code con il rendering a schermo intero. Un mod può aggiungere un riquadro come barra laterale a destra, un toast in alto a destra della trascrizione, una riga di log nella trascrizione, una fascia sopra il prompt e una riga di stato sotto il prompt. Un mod può ridisegnare i messaggi, le righe delle chiamate agli strumenti e lo spinner. Il prompt appartiene a Claude Code." width="600" height="336" data-path="images/mods-screen-map.svg" />

14 14

15<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map-dark.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5b4161581a1bd2c0450b0c8b57bc1225" className="hidden dark:block" alt="Mappa di una sessione del terminale di Claude Code. Un mod può aggiungere un riquadro come barra laterale a destra, un toast in alto a destra della trascrizione, una riga di log nella trascrizione, una fascia sopra il prompt e una riga di stato sotto il prompt. Un mod può ridisegnare i messaggi, le righe delle chiamate agli strumenti e lo spinner. Il prompt appartiene a Claude Code." width="600" height="336" data-path="images/mods-screen-map-dark.svg" />15<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map-dark.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5b4161581a1bd2c0450b0c8b57bc1225" className="hidden dark:block" alt="Mappa di una sessione del terminale di Claude Code con il rendering a schermo intero. Un mod può aggiungere un riquadro come barra laterale a destra, un toast in alto a destra della trascrizione, una riga di log nella trascrizione, una fascia sopra il prompt e una riga di stato sotto il prompt. Un mod può ridisegnare i messaggi, le righe delle chiamate agli strumenti e lo spinner. Il prompt appartiene a Claude Code." width="600" height="336" data-path="images/mods-screen-map-dark.svg" />

16 16

17In un terminale più stretto, il riquadro si trova sopra il prompt anziché accanto alla trascrizione.17In un terminale più stretto, il riquadro si trova sopra il prompt anziché accanto alla trascrizione.

18 18

327| `holdToasts` | Trattiene i toast, i piccoli avvisi di [`$.ui.toast`](/docs/it/plugins/mods/api#show-something-without-starting-a-turn), finché il pannello non si chiude |327| `holdToasts` | Nel terminale, trattiene i toast finché è questo il pannello mostrato. Vedi [Trattieni i toast dietro una finestra di dialogo](#hold-toasts-behind-a-dialog). |

328| `rows` | L'altezza da richiedere quando il pannello si trova sopra il prompt. Il valore predefinito è un terzo dello spazio. |328| `rows` | L'altezza da richiedere quando il pannello si trova sopra il prompt. Il valore predefinito è un terzo dello spazio. |

330 330

337 337

338Per consentire a un comando di aprire il pannello mentre Claude sta lavorando, aggiungi `immediate: true` quando [registri il comando](/docs/it/plugins/mods/api#add-a-command). Senza di esso, un comando digitato durante un turno attende la fine del turno.338Per consentire a un comando di aprire il pannello mentre Claude sta lavorando, aggiungi `immediate: true` quando [registri il comando](/docs/it/plugins/mods/api#add-a-command). Senza di esso, un comando digitato durante un turno attende la fine del turno.

339 339

340<h4 id="hold-toasts-behind-a-dialog">

341 Trattieni i toast dietro una finestra di dialogo

342</h4>

343

344Passa `holdToasts: true` a `$.ui.open` quando il pannello è una finestra di dialogo a cui l'utente risponde e che poi lascia, così i toast non compaiono mentre decide. Nel terminale, la trattenuta dura finché è quel pannello a essere mostrato, e un toast generato in quel lasso di tempo attende la fine della trattenuta.

345

346Claude Code trattiene i toast degli altri mod e le proprie notifiche di breve durata, oltre a quelli che il tuo mod genera con [`$.ui.toast`](/docs/it/plugins/mods/api#show-something-without-starting-a-turn). Ometti il campo in un pannello che resta aperto, così l'utente continua a vederli.

347

340<h4 id="when-a-pane-waits-for-a-wider-terminal">348<h4 id="when-a-pane-waits-for-a-wider-terminal">

341 Quando un pannello attende un terminale più ampio349 Quando un pannello attende un terminale più ampio

342</h4>350</h4>

plugins/mods/reference.md +2 −1

Details

209| [`$.ui`](/docs/it/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, `focus`, `scroll`, `toast`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit` |209| [`$.ui`](/docs/it/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, `focus`, `scroll`, `toast`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit` |

212| `$.agent` | `register`, `spawn`, `list` |212| `$.agent` | `register`, `spawn`, `list`. `list()` restituisce i subagent e i compagni di squadra di questa sessione, ciascuno con uno `status` tra `pending`, `running`, `waiting`, `idle`, `completed`, `failed` o `killed`, dove `idle` e `waiting` richiedono Claude Code v2.1.289 o versioni successive. |

214| [`$.prompt`](/docs/it/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`, `read`, `fill`, `suggest`, `compose`. Claude legge il testo di `submit({ text })` dopo una frase che indica il tuo mod come mittente. `submit({ text, asUser: true })` invia il testo come parole dell'utente stesso, senza quella frase. |214| [`$.prompt`](/docs/it/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`, `read`, `fill`, `suggest`, `compose`. Claude legge il testo di `submit({ text })` dopo una frase che indica il tuo mod come mittente. `submit({ text, asUser: true })` invia il testo come parole dell'utente stesso, senza quella frase. |

320| Il motivo `drop` di un hook o il motivo `deny` di `config.set` | 4.096 caratteri. La parte finale di un motivo più lungo viene troncata, e il drop o il deny si applica comunque. Il troncamento richiede Claude Code v2.1.292 o versioni successive; nelle versioni precedenti l'hook invece [non riesce](/docs/it/plugins/mods/events#handle-a-hook-that-fails). |

320| Testo in un singolo albero | Vengono disegnati i primi 100.000 caratteri |321| Testo in un singolo albero | Vengono disegnati i primi 100.000 caratteri |

321| Il `language` o il `path` di un `Code`, il `value` di un'opzione `Select` o il `module` di un `Client` | 10.000 caratteri. Se uno è più lungo, Claude Code [disegna la propria versione del sito](/docs/it/plugins/mods/interface#build-a-tree-from-elements). |322| Il `language` o il `path` di un `Code`, il `value` di un'opzione `Select` o il `module` di un `Client` | 10.000 caratteri. Se uno è più lungo, Claude Code [disegna la propria versione del sito](/docs/it/plugins/mods/interface#build-a-tree-from-elements). |

plugins/mods/test.md +7 −2

Details

110* `returned neither { value } nor { deny }`: uno stub per una chiamata della mods API ha restituito un valore semplice, il che fa fallire il test110* `returned neither { value } nor { deny }`: uno stub per una chiamata della mods API ha restituito un valore semplice, il che fa fallire il test

111* `no implementation for` seguito da un nome: il tuo mod ha effettuato quella chiamata e nessuno stub risponde111* `no implementation for` seguito da un nome: il tuo mod ha effettuato quella chiamata e nessuno stub risponde

112 112

113Il kit esporta anche mock in memoria che rispondono per te a un intero namespace. `mock.clock(on)` risponde a [`$.clock`](/docs/it/plugins/mods/api#run-work-in-the-background), `mock.store(on, { count: 7 })` risponde a `$.store` da uno store che inizia con quelle voci, e `mock.env(on, { CI: 'true' })` risponde a `$.env.get` da quelle variabili. `mock.clock` restituisce un orologio mock che il tuo test fa avanzare, così un test di un timer non deve attendere. `mock.store` non restituisce nulla, quindi per verificare cosa ha salvato il tuo mod, scrivi tu stesso i due stub `store` come fa il [test di disegno](#test-a-drawing).113Il kit esporta anche mock pronti all'uso per l'orologio, lo store, le variabili d'ambiente e le righe aggiunte alla conversazione:

114

115* **`mock.clock(on)`**: risponde a [`$.clock`](/docs/it/plugins/mods/api#run-work-in-the-background) e restituisce un orologio mock che il tuo test fa avanzare, così un test di un timer non deve attendere.

116* **`mock.store(on, { count: 7 })`**: risponde a `$.store` da uno store che inizia con quelle voci. Non restituisce nulla, quindi per verificare cosa ha salvato il tuo mod, scrivi tu stesso i due stub `store` come fa il [test di disegno](#test-a-drawing).

117* **`mock.env(on, { CI: 'true' })`**: risponde a `$.env.get` da quelle variabili.

118* **`mock.session(on)`**: restituisce una sessione mock il cui metodo `appended()` elenca le righe che il tuo mod ha aggiunto con [`$.session.append`](/docs/it/plugins/mods/reference#session), a partire dalla più vecchia; richiede Claude Code v2.1.293 o successiva.

114 119

115<h3 id="follow-the-test-kit’s-rules">120<h3 id="follow-the-test-kit’s-rules">

116 Seguire le regole del test kit121 Seguire le regole del test kit

168 Consultare cosa restituisce uno stub173 Consultare cosa restituisce uno stub

169</h3>174</h3>

170 175

171Ogni chiamata della mods API che il tuo mod effettua in un test ha bisogno di uno stub che risponda al posto di Claude Code, tranne le poche a cui risponde il kit stesso: le chiamate [`$.ui.invalidate`](/docs/it/plugins/mods/interface#redraw-when-something-changes) e [`$.state`](/docs/it/plugins/mods/interface#keep-state). Per le chiamate `$.clock`, usa `mock.clock(on)`, altrimenti il `$.clock.now()` del tuo mod fallisce con `no implementation for clock.now`.176Ogni chiamata della mods API che il tuo mod effettua in un test ha bisogno di uno stub che risponda al posto di Claude Code, tranne le poche a cui risponde il kit stesso: le chiamate [`$.ui.invalidate`](/docs/it/plugins/mods/interface#redraw-when-something-changes), [`$.state`](/docs/it/plugins/mods/interface#keep-state) e `$.session.append`. Per le chiamate `$.clock`, usa `mock.clock(on)`, altrimenti il `$.clock.now()` del tuo mod fallisce con `no implementation for clock.now`.

172 177

173Questa tabella elenca quelle che i mod usano più spesso. La prima colonna è la chiamata che il tuo mod effettua o l'evento che passa con `next(e)`. La seconda è la funzione da passare a `on` con quel nome, così la riga `$.store.get` diventa `on('store.get', ($, e) => ({ value: saved.get(e.key) }))`. Un `'...'` in uno stub indica un testo da compilare:178Questa tabella elenca quelle che i mod usano più spesso. La prima colonna è la chiamata che il tuo mod effettua o l'evento che passa con `next(e)`. La seconda è la funzione da passare a `on` con quel nome, così la riga `$.store.get` diventa `on('store.get', ($, e) => ({ value: saved.get(e.key) }))`. Un `'...'` in uno stub indica un testo da compilare:

174 179

plugins/mods/troubleshoot.md +15 −1

Details

209 Un disegno non appare o non risponde209 Un disegno non appare o non risponde

210</h2>210</h2>

211 211

212Il mod è stato caricato, ma il suo riquadro, la sua banda o i suoi controlli non si comportano come ti aspetti.212Il mod è stato caricato, ma il suo riquadro, la sua banda, il suo toast o i suoi controlli non si comportano come ti aspetti.

213 213

214<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">214<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">

215 Un riquadro o una banda è vuota o mostra il contenuto abituale di Claude Code215 Un riquadro o una banda è vuota o mostra il contenuto abituale di Claude Code

247 247

248Apri il riquadro da un comando o da un pulsante, oppure controlla il risultato `isPlaced` della chiamata. Consulta [Aprire un riquadro al momento giusto](/docs/it/plugins/mods/interface#open-a-pane-at-the-right-time).248Apri il riquadro da un comando o da un pulsante, oppure controlla il risultato `isPlaced` della chiamata. Consulta [Aprire un riquadro al momento giusto](/docs/it/plugins/mods/interface#open-a-pane-at-the-right-time).

249 249

250<h3 id="a-toast-doesn’t-appear">

251 Un toast non appare

252</h3>

253

254Il tuo mod chiama [`$.ui.toast`](/docs/it/plugins/mods/api#show-something-without-starting-a-turn) in una sessione interattiva del terminale e non vedi il toast. Per confermare che la chiamata sia stata eseguita, cerca nel [log di debug](#read-the-debug-log) una riga con il nome del tuo mod e il testo del toast, come in `$.ui.toast (first-mod): build finished`. Poi verifica cause come queste:

255

256* **La riga relativa alla chiamata manca**: cerca una riga che spieghi perché Claude Code ha rifiutato la chiamata, come in `first-mod: $.ui.toast dropped: timeoutMs is a whole number of ms, 1 to 60000`.

257* **Un riquadro sta trattenendo i toast**: il tuo mod o un altro ha passato [`holdToasts`](/docs/it/plugins/mods/interface#hold-toasts-behind-a-dialog) quando ha aperto il riquadro visualizzato. Chiudi il riquadro per terminare la trattenuta. Se il riquadro è tuo ed è pensato per restare aperto, rimuovi `holdToasts` dalla sua chiamata `$.ui.open` e apri di nuovo il riquadro.

258* **Il toast è sotto il prompt**: nel [renderer classico](/docs/it/fullscreen#enable-fullscreen-rendering), guarda a destra sotto il prompt. Lì un toast è una singola riga che inizia con il nome del mod, anziché una casella in alto a destra.

259* **Il tuo mod ha generato un toast più recente**: nel renderer classico, un toast più recente del tuo mod può prendere il posto di uno visualizzato o in attesa di essere visualizzato. Il log di debug contiene un'altra riga per il toast più vecchio, che termina con `gave way, cut short` se era visualizzato, oppure con `gave way, unseen` se non è mai apparso. Per mostrare entrambi i messaggi, inseriscili in un unico toast.

260* **Il tempo del toast è scaduto prima che venisse disegnato**: nel rendering a schermo intero, Claude Code disegna al massimo tre toast alla volta, quindi il tempo di un toast può scadere prima che venga disegnato. Il log di debug contiene un'altra riga per quel toast, che termina con `left the stack, never drawn`. Quando il tuo mod ne genera diversi contemporaneamente, inserisci i messaggi in un unico toast.

261

262Prima della v2.1.290, Claude Code scartava un toast generato entro due secondi dall'ultimo mostrato per il tuo mod, e la riga del log di debug relativa al toast scartato riportava `within 2000ms of the last; dropped`.

263

250<h3 id="hotkeys-do-nothing">264<h3 id="hotkeys-do-nothing">

251 I tasti di scelta rapida non fanno nulla265 I tasti di scelta rapida non fanno nulla

252</h3>266</h3>

plugins/publish.md +1 −0

Details

129* Aggiungi il marketplace una volta: `claude plugin marketplace add your-org/your-marketplace`, dove l'argomento è una scorciatoia GitHub `owner/repo`, un URL o un percorso129* Aggiungi il marketplace una volta: `claude plugin marketplace add your-org/your-marketplace`, dove l'argomento è una scorciatoia GitHub `owner/repo`, un URL o un percorso

130* Installa il plugin: `claude plugin install deploy-helper@your-marketplace`130* Installa il plugin: `claude plugin install deploy-helper@your-marketplace`

131* Oppure fai entrambi da dentro una sessione: `/plugin install deploy-helper --marketplace your-org/your-marketplace`. Richiede Claude Code v2.1.275 o successivo. Vedi [Aggiungi un marketplace e installa in un comando](/docs/it/plugins/install#add-a-marketplace-and-install-in-one-command)131* Oppure fai entrambi da dentro una sessione: `/plugin install deploy-helper --marketplace your-org/your-marketplace`. Richiede Claude Code v2.1.275 o successivo. Vedi [Aggiungi un marketplace e installa in un comando](/docs/it/plugins/install#add-a-marketplace-and-install-in-one-command)

132* Oppure fai entrambi dalla shell in un solo comando: `claude plugin install deploy-helper --marketplace your-org/your-marketplace`. Richiede Claude Code v2.1.292 o successivo

132 133

133<h3 id="ship-updates-to-users">134<h3 id="ship-updates-to-users">

134 Spedisci aggiornamenti agli utenti135 Spedisci aggiornamenti agli utenti

plugins/troubleshooting.md +2 −2

Details

163 `Invalid marketplace source format`163 `Invalid marketplace source format`

164</h3>164</h3>

165 165

166È stato eseguito `/plugin marketplace add <source>` o `claude plugin marketplace add <source>` e Claude Code ha risposto `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`.166Hai eseguito `/plugin marketplace add <source>`, `claude plugin marketplace add <source>` o `claude plugin install <plugin> --marketplace <source>` e Claude Code ha risposto `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`.

167 167

168Claude Code accetta una fonte in una di queste forme:168Claude Code accetta una fonte in una di queste forme:

169 169

568 `Marketplace "<name>" is already added from a different source`568 `Marketplace "<name>" is already added from a different source`

569</h3>569</h3>

570 570

571Hai confermato l'aggiunta di un marketplace tramite [`/plugin install <plugin> --marketplace <source>`](/docs/it/plugins/install#add-a-marketplace-and-install-in-one-command), e il catalogo che Claude Code ha recuperato da quella sorgente ha lo stesso nome di un marketplace che hai già aggiunto da una sorgente diversa. Claude Code mantiene il marketplace esistente invece di sostituirlo, e il plugin non viene installato.571Hai indicato una nuova sorgente di marketplace con [`--marketplace <source>` nel comando di installazione](/docs/it/plugins/install#add-a-marketplace-and-install-in-one-command), in una sessione o dalla shell. Il catalogo che Claude Code ha recuperato da quella sorgente ha lo stesso nome di un marketplace che hai già aggiunto da una sorgente diversa. Claude Code mantiene il marketplace esistente invece di sostituirlo, e il plugin non viene installato.

572 572

573Il messaggio completo è simile a questo:573Il messaggio completo è simile a questo:

574 574

self-hosted-environments-configuration.md +16 −3

Details

403 403

404* Il [file MCP gestito](/docs/it/managed-mcp) con ambito enterprise nel suo percorso di sistema standard: `/etc/claude-code/managed-mcp.json` sugli host runner Linux, `/Library/Application Support/ClaudeCode/managed-mcp.json` sugli host macOS. Usalo per flotte bloccate in cui possono essere caricati solo i server elencati dall'amministratore. Consulta [controllo esclusivo con managed-mcp.json](/docs/it/managed-mcp#exclusive-control-with-managed-mcp-json) per le regole di precedenza. Quando questo file si trova sull'host del runner, Claude Code ignora i server MCP che il control plane di Anthropic fornisce a una sessione, inclusi i connettori di claude.ai, e li nomina in un avviso sullo stderr del processo figlio della sessione, che il runner registra al livello di log `debug`. Prima della v2.1.229, quelle sessioni terminavano all'avvio con `You cannot dynamically configure MCP servers when an enterprise MCP config is present`.404* Il [file MCP gestito](/docs/it/managed-mcp) con ambito enterprise nel suo percorso di sistema standard: `/etc/claude-code/managed-mcp.json` sugli host runner Linux, `/Library/Application Support/ClaudeCode/managed-mcp.json` sugli host macOS. Usalo per flotte bloccate in cui possono essere caricati solo i server elencati dall'amministratore. Consulta [controllo esclusivo con managed-mcp.json](/docs/it/managed-mcp#exclusive-control-with-managed-mcp-json) per le regole di precedenza. Quando questo file si trova sull'host del runner, Claude Code ignora i server MCP che il control plane di Anthropic fornisce a una sessione, inclusi i connettori di claude.ai, e li nomina in un avviso sullo stderr del processo figlio della sessione, che il runner registra al livello di log `debug`. Prima della v2.1.229, quelle sessioni terminavano all'avvio con `You cannot dynamically configure MCP servers when an enterprise MCP config is present`.

405* La chiave [`managedMcpServers`](/docs/it/settings-reference#managedmcpservers) nelle [impostazioni gestite](/docs/it/managed-settings) sull'host del runner: fornisce server HTTP e SSE senza assumere il controllo esclusivo, quindi i server delle altre fonti vengono comunque caricati. Richiede Claude Code v2.1.259 o successiva.405* La chiave [`managedMcpServers`](/docs/it/settings-reference#managedmcpservers) nelle [impostazioni gestite](/docs/it/managed-settings) sull'host del runner: fornisce server HTTP e SSE senza assumere il controllo esclusivo, quindi i server delle altre fonti vengono comunque caricati. Richiede Claude Code v2.1.259 o successiva.

406* `<repo>/.mcp.json`: ambito di progetto. Esegui il commit del file nel repository; i suoi server vengono approvati automaticamente nelle sessioni cloud.406* `<repo>/.mcp.json`: ambito di progetto. Esegui il commit del file nel repository; i suoi server vengono approvati automaticamente nelle sessioni cloud. In una sessione con più repository, [viene caricato al massimo il file di un solo repository](#repository-settings-in-sessions-with-several-repositories).

407 407

408Quando la distribuzione dei connettori è abilitata per la tua organizzazione, il control plane di Anthropic fornisce i connettori che hai configurato su claude.ai alle sessioni create in modo interattivo tramite una configurazione MCP fornita dal server, instradata attraverso `api.anthropic.com`. Le sessioni create in modo programmatico, come i [dispatch da CLI](/docs/it/self-hosted-environments-testing#run-the-test-loop), non ricevono i connettori; fornisci loro i server MCP tramite una qualsiasi delle altre fonti elencate in questa sezione. Il token OAuth del processo figlio non include uno scope per recuperare direttamente i connettori, quindi il processo figlio non tenta autonomamente quel recupero; la distribuzione è gestita dal server.408Quando la distribuzione dei connettori è abilitata per la tua organizzazione, il control plane di Anthropic fornisce i connettori che hai configurato su claude.ai alle sessioni create in modo interattivo tramite una configurazione MCP fornita dal server, instradata attraverso `api.anthropic.com`. Le sessioni create in modo programmatico, come i [dispatch da CLI](/docs/it/self-hosted-environments-testing#run-the-test-loop), non ricevono i connettori; fornisci loro i server MCP tramite una qualsiasi delle altre fonti elencate in questa sezione. Il token OAuth del processo figlio non include uno scope per recuperare direttamente i connettori, quindi il processo figlio non tenta autonomamente quel recupero; la distribuzione è gestita dal server.

409 409

543exit 0543exit 0

544```544```

545 545

546L'hook spinge Claude a committare e spingere prima della fine della sessione, e rimane silenzioso quando la directory non è un repository git o non ha un remoto.546L'hook chiede a Claude di fare il commit e il push prima che la sessione termini, e rimane silenzioso quando la directory non è un repository git o non ha un remoto. Per una sessione con più repository, consulta [cosa indica `$CLAUDE_PROJECT_DIR`](#repository-settings-in-sessions-with-several-repositories).

547 547

548<h2 id="permissions-and-tool-approval">548<h2 id="permissions-and-tool-approval">

549 Autorizzazioni e approvazione degli strumenti549 Autorizzazioni e approvazione degli strumenti

572 572

573Impostare `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` per seminare da un percorso diverso, o puntarlo a una directory vuota per disabilitare la semina.573Impostare `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` per seminare da un percorso diverso, o puntarlo a una directory vuota per disabilitare la semina.

574 574

575Il `.claude/settings.json` committato nel repository si sovrappone come impostazioni del progetto. Le sessioni leggono anche [`managed-settings.json`](/docs/it/settings#where-settings-live) dal percorso di sistema standard nell'immagine del runner. Se le sue chiavi si applicano insieme alle [impostazioni gestite dal server](/docs/it/server-managed-settings) segue [come Claude Code combina le fonti gestite](/docs/it/managed-settings#how-claude-code-combines-managed-sources): per impostazione predefinita, quando l'organizzazione fornisce qualsiasi chiave gestita dal server, le sessioni ignorano il file dell'immagine del runner a parte le [chiavi che Claude Code legge da ogni fonte di amministrazione](/docs/it/managed-settings#keys-read-from-every-admin-source), come il blocco `env`, i blocchi sandbox, i percorsi binari sandbox e `forceRemoteSettingsRefresh`. Consultare [settings precedence](/docs/it/settings#settings-precedence).575Il `.claude/settings.json` committato nel repository si sovrappone come impostazioni di progetto. In una sessione con più repository, [ha effetto al massimo il file di un solo repository](#repository-settings-in-sessions-with-several-repositories). Le sessioni leggono anche [`managed-settings.json`](/docs/it/settings#where-settings-live) dal percorso di sistema standard nell'immagine del runner. Se le sue chiavi si applicano insieme alle [impostazioni gestite dal server](/docs/it/server-managed-settings) dipende da [come Claude Code combina le fonti gestite](/docs/it/managed-settings#how-claude-code-combines-managed-sources): per impostazione predefinita, quando la tua organizzazione fornisce chiavi gestite dal server, le sessioni ignorano il file dell'immagine del runner, ad eccezione delle [chiavi che Claude Code legge da ogni fonte di amministrazione](/docs/it/managed-settings#keys-read-from-every-admin-source), come il blocco `env`, i blocchi della sandbox, i percorsi dei binari della sandbox e `forceRemoteSettingsRefresh`. Consulta [precedenza delle impostazioni](/docs/it/settings#settings-precedence).

576 576

577Quando il piano di controllo di Anthropic fornisce una sessione con [hook Claude Code](/docs/it/hooks), il runner li installa insieme, non sopra, la propria configurazione. Richiede Claude Code v2.1.229 o successivo.577Quando il piano di controllo di Anthropic fornisce una sessione con [hook Claude Code](/docs/it/hooks), il runner li installa insieme, non sopra, la propria configurazione. Richiede Claude Code v2.1.229 o successivo.

578 578

584 584

585Lo snapshot di `~/.claude/` dell'host acquisito dal runner esclude la directory `projects/`. La posizione di archiviazione predefinita della memoria automatica si trova in quella directory. Se vi inserisci file di memoria, il runner non li copia nelle sessioni e questi non attivano la memoria automatica.585Lo snapshot di `~/.claude/` dell'host acquisito dal runner esclude la directory `projects/`. La posizione di archiviazione predefinita della memoria automatica si trova in quella directory. Se vi inserisci file di memoria, il runner non li copia nelle sessioni e questi non attivano la memoria automatica.

586 586

587<h3 id="repository-settings-in-sessions-with-several-repositories">

588 Impostazioni dei repository nelle sessioni con più repository

589</h3>

590

591In una sessione con più repository, Claude Code legge le impostazioni di progetto dalla directory in cui si avvia la sessione, quindi al massimo il `.claude/settings.json` di un solo repository ha effetto come impostazioni di progetto. Un hook definito nel file di un altro repository non viene eseguito, una regola deny al suo interno non si applica e il relativo `env` non viene impostato.

592

593* **`--capacity 1`, il valore predefinito, con il checkout integrato**: la sessione si avvia nel primo repository del suo elenco di repository. Il `.claude/settings.json` di quel repository ha effetto come impostazioni di progetto e il suo `.mcp.json` viene caricato, mentre quelli degli altri repository no.

594* **Un `--capacity` superiore a uno, oppure un [hook `checkout`](#checkout)**: la sessione si avvia in una directory per sessione che contiene i checkout. Il `.claude/settings.json` di nessun repository ha effetto come impostazioni di progetto, il `.mcp.json` di nessun repository viene caricato e [`$CLAUDE_PROJECT_DIR`](/docs/it/hooks#reference-scripts-by-path) in un comando di hook corrisponde a quella directory, non a un checkout.

595

596Il `CLAUDE.md` e le skill di ciascun repository vengono caricati ovunque si avvii la sessione. Il runner passa ogni repository a Claude Code come [directory aggiuntiva](/docs/it/permissions#additional-directories-grant-file-access-not-configuration), quindi Claude Code legge anche le chiavi `enabledPlugins` ed `extraKnownMarketplaces` dal `.claude/settings.json` di ciascun repository.

597

598Per eseguire un hook o applicare una regola di permesso in ogni sessione, inseriscili in `~/.claude/settings.json` sull'host del runner. Il runner [copia il file dell'host in ogni sessione](#how-each-session’s-config-is-assembled), ovunque si avvii la sessione. Scrivi un percorso in una regola `Read` o `Edit` come [pattern](/docs/it/permissions#read-and-edit) assoluto con `//` o relativo alla home con `~/`, perché gli altri pattern sono ancorati alla fonte delle impostazioni o alla directory corrente.

599

587<h3 id="repository-committed-permission-rules">600<h3 id="repository-committed-permission-rules">

588 Regole di autorizzazione committate nel repository601 Regole di autorizzazione committate nel repository

589</h3>602</h3>

server-managed-settings.md +6 −2

Details

87 87

88 Poiché gli hook eseguono comandi shell, gli utenti in sessioni interattive vedono una [finestra di dialogo di approvazione della sicurezza](#security-approval-dialogs) prima che Claude Code li applichi.88 Poiché gli hook eseguono comandi shell, gli utenti in sessioni interattive vedono una [finestra di dialogo di approvazione della sicurezza](#security-approval-dialogs) prima che Claude Code li applichi.

89 89

90 Per configurare il classificatore della [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) in modo che conosca quali repository, bucket e domini la vostra organizzazione ritiene affidabili, fornire un blocco `autoMode` nello stesso modo; vedere [Configurare la modalità auto](/docs/it/auto-mode-config) per come le voci `autoMode` influenzano ciò che il classificatore blocca e avvertimenti importanti sui campi `environment`, `allow`, `soft_deny` e `hard_deny`.90 Per configurare il classificatore della [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) in modo che conosca quali repository, bucket e domini la tua organizzazione ritiene affidabili, fornisci un blocco `autoMode` nello stesso modo; consulta [Configurare la modalità auto](/docs/it/auto-mode-config) per come le voci `autoMode` influenzano ciò che il classificatore blocca e avvertimenti importanti sui campi `environment`, `allow`, `soft_deny` e `hard_deny`.

91 </Step>91 </Step>

92 92

93 <Step title="Salvare e distribuire">93 <Step title="Salvare e distribuire">

~~94 Salvare le modifiche. I client di Claude Code ricevono le impostazioni aggiornate al prossimo avvio o ciclo di polling orario.~~94 Salva le modifiche. I client di Claude Code ricevono le impostazioni aggiornate al prossimo avvio o ciclo di polling orario.

96 L'editor confronta il tuo JSON con lo schema JSON pubblicato per le impostazioni di Claude Code. Se trova un problema in un JSON che viene analizzato correttamente, mostra un avviso e cambia l'etichetta del pulsante di salvataggio. L'etichetta è **Update with errors** quando le impostazioni sono già salvate e **Add with errors** quando non è ancora stata salvata alcuna impostazione. Quel pulsante salva comunque, perché un avviso dello schema non blocca il salvataggio.

98 Lo schema [può essere in ritardo rispetto alle versioni più recenti](/docs/it/settings#edit-a-settings-file), quindi l'editor può segnalare una chiave o un valore documentato nel [riferimento delle impostazioni](/docs/it/settings-reference#all-settings). Claude Code riceve le chiavi e i valori che hai salvato ed esegue [la propria convalida](#invalid-entries-in-delivered-settings) quando li carica.

95 </Step>99 </Step>

96</Steps>100</Steps>

97 101

settings.md +41 −41

Details

402 402

403Claude Code legge le impostazioni da quattro file, e un'organizzazione può anche fornire impostazioni gestite dalla console claude.ai. Ogni fonte ha un ambito: l'insieme di persone e progetti a cui si applica un'impostazione salvata in essa, che sia solo tu, tutti in un progetto o tutti nella tua organizzazione.403Claude Code legge le impostazioni da quattro file, e un'organizzazione può anche fornire impostazioni gestite dalla console claude.ai. Ogni fonte ha un ambito: l'insieme di persone e progetti a cui si applica un'impostazione salvata in essa, che sia solo tu, tutti in un progetto o tutti nella tua organizzazione.

404 404

406| :- | :- | :- | :- |406| :- | :- | :- | :- |

408| Progetto condiviso | `.claude/settings.json` | Tutti coloro che lavorano nella cartella che lo contiene. In un repository git, eseguite il commit in modo che i vostri colleghi lo ottengano | Autorizzazioni del team, hooks, plugins, e le variabili di ambiente di cui il progetto ha bisogno |408| Progetto condiviso | `.claude/settings.json` | Tutti coloro che lavorano nella cartella che lo contiene. In un repository git, esegui il commit in modo che i tuoi colleghi lo ricevano | Permessi del team, hook, plugin e le variabili d'ambiente di cui il progetto ha bisogno |

409| Progetto locale | `.claude/settings.local.json` | Voi, in questo solo progetto. Claude Code lo mantiene fuori da git quando crea il file; se lo create manualmente, aggiungetelo a `.gitignore` voi stessi | Override personali per un progetto, e test prima di condividere |409| Progetto locale | `.claude/settings.local.json` | Te, solo in questo progetto. Claude Code lo tiene fuori da git quando crea il file; se lo crei manualmente, aggiungilo tu stesso a `.gitignore` | Override personali per un progetto e test prima di condividere |

410| Gestito | `managed-settings.json` e altre [fonti gestite](/docs/it/managed-settings#delivery-mechanisms) | Tutti coloro a cui la tua organizzazione lo distribuisce; [Precedenza delle impostazioni](#settings-precedence) indica cosa può sovrascriverlo | Politiche di sicurezza e requisiti di conformità |410| Gestito | `managed-settings.json` e altre [fonti gestite](/docs/it/managed-settings#delivery-mechanisms) | Tutti coloro a cui la tua organizzazione lo distribuisce; [Precedenza delle impostazioni](#settings-precedence) indica cosa può sovrascriverlo | Politiche di sicurezza e requisiti di conformità |

411 411

412Nella colonna File, `~/.claude` è la cartella `.claude` nella vostra home directory, e un `.claude` semplice è la cartella `.claude` all'interno del vostro progetto.412Nella colonna File, `~/.claude` è la cartella `.claude` nella tua directory home, e un `.claude` semplice è la cartella `.claude` all'interno del tuo progetto.

413 413

414<span id="where-each-file-applies" />414<span id="where-each-file-applies" />

415 415

419 Confrontare l'ambito di ogni file di impostazioni419 Confrontare l'ambito di ogni file di impostazioni

420</h3>420</h3>

421 421

422Supponiamo che abbiate tre progetti sulla vostra macchina, `website/`, `api/`, e `acme-app/`, un vostro collega ha il suo clone di `acme-app/`, e avviate una [sessione cloud](#settings-in-cloud-sessions) su `acme-app/`.422Supponi di avere tre progetti sulla tua macchina, `website/`, `api/` e `acme-app/`, che un tuo collega abbia il proprio clone di `acme-app/` e che tu avvii una [sessione cloud](#settings-in-cloud-sessions) su `acme-app/`.

423 423

424Il grafico sottostante mostra in quali di quelle cartelle si applica un'impostazione quando avviate Claude Code da esse. Fate clic su un file di impostazioni per vedere le cartelle che raggiunge.424Il grafico sottostante mostra in quali di quelle cartelle si applica un'impostazione quando avvii Claude Code da esse. Fai clic su un file di impostazioni per vedere le cartelle che raggiunge.

425 425

426<SettingsScope />426<SettingsScope />

427 427

428* **`~/.claude/settings.json`**: ogni progetto sulla vostra macchina, e nulla su quella del vostro collega o nella sessione cloud428* **`~/.claude/settings.json`**: ogni progetto sulla tua macchina, e nulla su quella del tuo collega o nella sessione cloud

429* **`acme-app/.claude/settings.json`**: il vostro `acme-app/`. Raggiunge il clone del vostro collega e la sessione cloud solo se eseguite il commit del file nel controllo di versione; fino a quando non lo fate, è un file sul vostro disco come qualsiasi altro e nessun altro lo ha429* **`acme-app/.claude/settings.json`**: il tuo `acme-app/`. Raggiunge il clone del tuo collega e la sessione cloud solo se esegui il commit del file nel controllo di versione; finché non lo fai, è un file sul tuo disco come qualsiasi altro e nessun altro lo ha

430* **`acme-app/.claude/settings.local.json`**: il vostro `acme-app/` solo. Claude Code lo aggiunge alle vostre esclusioni git globali la prima volta che scrive il file, quindi rimane fuori dai vostri commit; se create il file manualmente, [aggiungetelo a `.gitignore` voi stessi](#keep-personal-settings-out-of-a-repository)430* **`acme-app/.claude/settings.local.json`**: solo il tuo `acme-app/`. Claude Code lo aggiunge alle tue esclusioni git globali la prima volta che scrive il file, quindi rimane fuori dai tuoi commit; se crei il file manualmente, [aggiungilo tu stesso a `.gitignore`](#keep-personal-settings-out-of-a-repository)

431* **Impostazioni gestite**, che sia un file `managed-settings.json`, una politica MDM, o [impostazioni gestite dal server](/docs/it/server-managed-settings) dalla console claude.ai: ogni progetto su ogni macchina a cui la vostra organizzazione lo distribuisce, o a cui accedete con il vostro account organizzativo. Solo le impostazioni gestite dal server raggiungono la sessione cloud431* **Impostazioni gestite**, che si tratti di un file `managed-settings.json`, di una politica MDM o di [impostazioni gestite dal server](/docs/it/server-managed-settings) dalla console claude.ai: ogni progetto su ogni macchina a cui la tua organizzazione le distribuisce, o a cui accedi con l'account della tua organizzazione. Solo le impostazioni gestite dal server raggiungono la sessione cloud

432 432

433<span id="which-files-you-have" />433<span id="which-files-you-have" />

434 434

435<h3 id="find-or-create-your-settings-files">435<h3 id="find-or-create-your-settings-files">

436 Trovare o creare i vostri file di impostazioni436 Trovare o creare i tuoi file di impostazioni

437</h3>437</h3>

438 438

439L'installazione di Claude Code non crea alcun file di impostazioni. Se la vostra macchina o il vostro progetto ne ha già uno, è venuto da una di queste fonti:439L'installazione di Claude Code non crea alcun file di impostazioni. Se la tua macchina o il tuo progetto ne ha già uno, proviene da una di queste fonti:

440 440

441* **Gestito**: la vostra organizzazione lo distribuisce. Non lo create o modificate.441* **Gestito**: lo distribuisce la tua organizzazione. Non lo crei né lo modifichi tu.

442* **Progetto condiviso**: un progetto che già utilizza Claude Code potrebbe averne uno sottoposto a commit. Se no, createlo in `.claude/settings.json` nella cartella del progetto.442* **Progetto condiviso**: un progetto che utilizza già Claude Code potrebbe averne uno sottoposto a commit. In caso contrario, crealo in `.claude/settings.json` nella cartella del progetto.

443* **Utente** e **Progetto locale**: createli voi stessi, o lasciate che Claude Code li crei. Scrive `~/.claude/settings.json` la prima volta che cambiate un'opzione nel menu `/config` che memorizza nelle impostazioni utente, come il tema, e `.claude/settings.local.json` la prima volta che date un'approvazione permanente su un prompt di autorizzazione, come "Sì, e non chiedere di nuovo" per un comando Bash. Poche opzioni `/config`, incluso **Show tips**, vengono salvate in `.claude/settings.local.json` invece che nel file utente.443* **Utente** e **Progetto locale**: creali tu stesso, oppure lascia che sia Claude Code a crearli. Scrive `~/.claude/settings.json` la prima volta che modifichi un'opzione nel menu `/config` che memorizza nelle impostazioni utente, come il tema, e `.claude/settings.local.json` la prima volta che dai un'approvazione permanente a una richiesta di permesso, come "Sì, e non chiedere di nuovo" per un comando Bash. Alcune opzioni di `/config`, tra cui **Show tips**, vengono invece salvate in `.claude/settings.local.json` anziché nel file utente.

444 444

445<Info>445<Info>

446 Su Windows, `~/.claude` significa `%USERPROFILE%\.claude`. Per mantenere i file della home directory altrove, impostate [`CLAUDE_CONFIG_DIR`](/docs/it/env-vars); Claude Code memorizza quindi le vostre impostazioni, la cronologia delle sessioni, e i plugins lì invece.446 Su Windows, `~/.claude` significa `%USERPROFILE%\.claude`. Per tenere i file della directory home altrove, imposta [`CLAUDE_CONFIG_DIR`](/docs/it/env-vars); Claude Code memorizzerà quindi lì le tue impostazioni, la cronologia delle sessioni e i plugin.

447</Info>447</Info>

448 448

449Claude Code mantiene anche un quinto file, [`~/.claude.json`](/docs/it/claude-directory#ce-claude-json), che scrive per se stesso; non dovete modificarlo. Contiene la vostra sessione di accesso, configurazioni [MCP server](/docs/it/mcp), stato per progetto come decisioni di fiducia, e le [chiavi di configurazione globale](/docs/it/settings-reference#global-config-settings) che `/config` scrive per voi.449Claude Code mantiene anche un quinto file, [`~/.claude.json`](/docs/it/claude-directory#ce-claude-json), che scrive per sé; non hai bisogno di modificarlo. Contiene la tua sessione di accesso, le configurazioni dei [server MCP](/docs/it/mcp), lo stato per progetto come le decisioni di fiducia e le [chiavi di configurazione globale](/docs/it/settings-reference#global-config-settings) che `/config` scrive per te.

450 450

451<h3 id="share-settings-with-your-team">451<h3 id="share-settings-with-your-team">

452 Condividere le impostazioni con il vostro team452 Condividere le impostazioni con il tuo team

453</h3>453</h3>

454 454

455Eseguite il commit di `.claude/settings.json` in modo che tutti coloro che clonano il repository ottengano le stesse autorizzazioni, hooks, e plugins. Ogni collega può comunque sostituirlo per se stesso nel proprio `.claude/settings.local.json`, quindi le eccezioni personali non hanno bisogno di un commit. Per un file team completo, vedete [le impostazioni condivise di un team](/docs/it/settings-example#a-teams-shared-settings).455Esegui il commit di `.claude/settings.json` in modo che tutti coloro che clonano il repository ricevano gli stessi permessi, hook e plugin. Ogni collega può comunque sovrascriverlo per sé nel proprio `.claude/settings.local.json`, quindi le eccezioni personali non richiedono un commit. Per un file di team completo, consulta [le impostazioni condivise di un team](/docs/it/settings-example#a-teams-shared-settings).

456 456

457Parte di quello che eseguite il commit attende fino a quando ogni collega [non si fida della cartella](/docs/it/permissions#project-allow-rules-and-workspace-trust), e poche chiavi non hanno mai effetto da un file di repository; [Troubleshoot a setting that doesn't apply](#common-cases) copre entrambi.457Parte di ciò di cui esegui il commit resta in attesa finché ogni collega non [considera attendibile la cartella](/docs/it/permissions#project-allow-rules-and-workspace-trust), e alcune chiavi non hanno mai effetto da un file del repository; [Risolvere i problemi di un'impostazione che non si applica](#common-cases) tratta entrambi i casi.

458 458

459<span id="local-settings-file" />459<span id="local-settings-file" />

460 460

465<span id="keep-personal-settings-out-of-the-repository" />465<span id="keep-personal-settings-out-of-the-repository" />

466 466

467<h3 id="keep-personal-settings-out-of-a-repository">467<h3 id="keep-personal-settings-out-of-a-repository">

468 Mantenere le impostazioni personali fuori da un repository468 Tenere le impostazioni personali fuori da un repository

469</h3>469</h3>

470 470

471Per cambiare un'impostazione per voi stessi in un progetto senza cambiarla per i vostri colleghi, salvatela in `.claude/settings.local.json` all'interno del progetto. Claude Code applica quel file sopra il `.claude/settings.json` sottoposto a commit, quindi se il file del vostro team imposta `"model": "claude-sonnet-5"` e volete Opus, mettete `"model": "claude-opus-5-5"` nel vostro file locale e solo le vostre sessioni cambiano.471Per modificare un'impostazione solo per te in un progetto senza cambiarla per i tuoi colleghi, salvala in `.claude/settings.local.json` all'interno del progetto. Claude Code applica quel file sopra il `.claude/settings.json` sottoposto a commit, quindi se il file del tuo team imposta `"model": "claude-sonnet-5"` e tu vuoi Opus, inserisci `"model": "claude-opus-5-5"` nel tuo file locale e cambiano solo le tue sessioni.

472 472

473Claude Code scrive anche in questo file, lo mantiene fuori dai vostri commit, e applica le sue regole di autorizzazione senza il passaggio di fiducia:473Claude Code scrive anche in questo file, lo tiene fuori dai tuoi commit e applica le sue regole allow senza il passaggio di attendibilità:

474 474

475* **Claude Code lo scrive anche.** Quando Claude chiede il permesso di eseguire un comando Bash e scegliete "Sì, e non chiedere di nuovo", Claude Code salva quella [approvazione di autorizzazione](/docs/it/permissions#permission-system) qui come una regola `allow`.475* **Anche Claude Code lo scrive.** Quando Claude chiede il permesso di eseguire un comando Bash e scegli "Sì, e non chiedere di nuovo", Claude Code salva qui quell'[approvazione del permesso](/docs/it/permissions#permission-system) come regola `allow`.

476* **Non dovete gitignore voi stessi, a meno che non l'abbiate creato manualmente.** La prima volta che Claude Code scrive il file in un repository git che non lo ignora già, aggiunge `**/.claude/settings.local.json` al vostro file di esclusioni git globale, quindi il file rimane fuori dai vostri commit in ogni repository. Quel file è `core.excludesFile` quando la vostra configurazione git globale lo imposta su un percorso assoluto o con prefisso `~`; altrimenti è `$XDG_CONFIG_HOME/git/ignore`, o `~/.config/git/ignore` quando `XDG_CONFIG_HOME` non è impostato. Se avete creato il file manualmente e Claude Code non ha ancora scritto in esso, aggiungetelo a `.gitignore` voi stessi.476* **Non devi aggiungerlo tu a gitignore, a meno che tu non l'abbia creato manualmente.** La prima volta che Claude Code scrive il file in un repository git che non lo ignora già, aggiunge `**/.claude/settings.local.json` al tuo file di esclusioni git globale, così il file rimane fuori dai tuoi commit in ogni repository. Quel file è `core.excludesFile` quando la tua configurazione git globale lo imposta su un percorso assoluto o con prefisso `~`; altrimenti è `$XDG_CONFIG_HOME/git/ignore`, oppure `~/.config/git/ignore` quando `XDG_CONFIG_HOME` non è impostato. Se hai creato il file manualmente e Claude Code non vi ha ancora scritto, aggiungilo tu stesso a `.gitignore`.

477* **Le sue regole di autorizzazione non attendono la fiducia mentre il file rimane non tracciato.** Poiché il file è vostro e non del repository, Claude Code applica le sue regole `allow` senza il passaggio [workspace trust](/docs/it/permissions#project-allow-rules-and-workspace-trust) che richiede per il file sottoposto a commit. Se il file è tracciato da git, il passaggio di fiducia si applica anche ad esso; vedete [When your local settings file needs trust](/docs/it/permissions#when-your-local-settings-file-needs-trust).477* **Le sue regole allow non attendono l'attendibilità finché il file resta non tracciato.** Poiché il file è tuo e non del repository, Claude Code applica le sue regole `allow` senza il passaggio di [attendibilità del workspace](/docs/it/permissions#project-allow-rules-and-workspace-trust) che richiede per il file sottoposto a commit. Se il file è tracciato da git, il passaggio di attendibilità si applica anche a esso; consulta [Quando il tuo file di impostazioni locali richiede l'attendibilità](/docs/it/permissions#when-your-local-settings-file-needs-trust).

478 478

479<span id="where-claude-code-looks-for-each-file" />479<span id="where-claude-code-looks-for-each-file" />

480 480

486 Dove Claude Code mantiene il file locale in un repository git486 Dove Claude Code mantiene il file locale in un repository git

487</h4>487</h4>

488 488

489Quando Claude chiede il permesso di eseguire un comando Bash e scegliete "Sì, e non chiedere di nuovo", Claude Code salva quella approvazione come una regola `allow` in `.claude/settings.local.json`. Se avviate Claude Code in una sottodirectory di un repository git, legge e scrive quel file alla radice del repository e applica l'approvazione in tutto il repository. In un [worktree](/docs/it/worktrees), utilizza il file alla radice del checkout principale.489Quando Claude chiede il permesso di eseguire un comando Bash e scegli "Sì, e non chiedere di nuovo", Claude Code salva quell'approvazione come regola `allow` in `.claude/settings.local.json`. Se avvii Claude Code in una sottodirectory di un repository git, legge e scrive quel file nella radice del repository e applica l'approvazione all'intero repository. In un [worktree](/docs/it/worktrees), utilizza il file nella radice del checkout principale.

490 490

491Due regole qualificano la posizione della radice:491Due regole precisano la posizione nella radice:

492 492

493* **Quando il file rimane con `.claude/settings.json` invece**: fuori da un repository git, quando la radice del repository è la vostra home directory, su Windows, o quando la radice del repository o la sua voce `.git` o `.claude` non è di proprietà del vostro utente.493* **Quando il file resta invece accanto a `.claude/settings.json`**: fuori da un repository git, quando la radice del repository è la tua directory home, su Windows, oppure quando la radice del repository o la sua voce `.git` o `.claude` non è di proprietà del tuo utente.

494* **I percorsi nel file non si ancorano alla radice del repository**: una regola di autorizzazione che inizia con `/` o un percorso sandbox relativo [si ancora alla directory di lavoro primaria della sessione](/docs/it/permissions#read-and-edit) invece.494* **I percorsi nel file non si ancorano alla radice del repository**: una regola di permesso che inizia con `/` o un percorso sandbox relativo [si ancora invece alla directory di lavoro primaria della sessione](/docs/it/permissions#read-and-edit).

495 495

496Prima della v2.1.211, Claude Code manteneva il file nella directory di avvio. Legge ancora un file che una versione precedente ha lasciato lì accanto al file radice; dove entrambi impostano la stessa chiave, il valore della radice si applica, e le regole di autorizzazione da entrambi i file si applicano. L'helper [`resolveSettings()`](/docs/it/agent-sdk/typescript#resolvesettings) dell'Agent SDK legge sempre il file dalla directory di avvio.496Prima della v2.1.211, Claude Code manteneva il file nella directory di avvio. Legge ancora un file lasciato lì da una versione precedente insieme al file nella radice; dove entrambi impostano la stessa chiave, si applica il valore della radice, e si applicano le regole di permesso di entrambi i file. L'helper [`resolveSettings()`](/docs/it/agent-sdk/typescript#resolvesettings) dell'Agent SDK legge sempre il file dalla directory di avvio.

497 497

498Claude Code legge il `.claude/settings.json` condiviso dalla [directory di lavoro primaria](/docs/it/permissions#working-directories) della sessione, quindi per utilizzare un file sottoposto a commit alla radice del repository, avviate Claude Code lì. Dopo aver [spostato la sessione con `/cd`](/docs/it/permissions#move-the-session-to-another-directory), Claude Code legge entrambi i file del progetto dalla nuova directory invece, posizionando il file locale secondo le stesse regole. Leggerli dalla directory in cui vi siete spostati richiede Claude Code v2.1.246 o successivo.498Claude Code legge il `.claude/settings.json` condiviso dalla [directory di lavoro primaria](/docs/it/permissions#working-directories) della sessione, quindi per utilizzare un file sottoposto a commit nella radice del repository, avvia Claude Code lì. Dopo aver [spostato la sessione con `/cd`](/docs/it/permissions#move-the-session-to-another-directory), Claude Code legge invece entrambi i file di progetto dalla nuova directory, posizionando il file locale secondo le stesse regole. Leggerli dalla directory in cui ti sei spostato richiede Claude Code v2.1.246 o successivo.

499 499

500<span id="managed-settings-delivery" />500<span id="managed-settings-delivery" />

501 501

508<span id="settings-your-organization-manages" />508<span id="settings-your-organization-manages" />

509 509

510<h3 id="check-what-your-organization-enforces">510<h3 id="check-what-your-organization-enforces">

511 Verificare cosa la vostra organizzazione applica511 Verificare cosa impone la tua organizzazione

512</h3>512</h3>

513 513

514Se la vostra organizzazione gestisce Claude Code, alcune impostazioni sono decise per voi e nulla di quello che mettete nei vostri file cambia loro. Per vedere quali, eseguite `/status`: la riga `Setting sources` nomina la fonte gestita che si applica a voi. Le impostazioni gestite si applicano ovunque Claude Code funzioni su questa macchina; [What a developer can change](/docs/it/managed-settings#what-a-developer-can-change) copre i diritti di amministratore locale e gli strumenti diversi da Claude Code.514Se la tua organizzazione gestisce Claude Code, alcune impostazioni sono decise per te e nulla di ciò che inserisci nei tuoi file le modifica. Per vedere quali, esegui `/status`: la riga `Setting sources` indica la fonte gestita che si applica a te. Le impostazioni gestite si applicano ovunque Claude Code venga eseguito su questa macchina; [Cosa può modificare uno sviluppatore](/docs/it/managed-settings#what-a-developer-can-change) tratta i diritti di amministratore locale e gli strumenti diversi da Claude Code.

515 515

516Le impostazioni gestite vi raggiungono attraverso i [delivery mechanisms](/docs/it/managed-settings#delivery-mechanisms) sulla pagina delle impostazioni gestite, più comunemente:516Le impostazioni gestite ti raggiungono attraverso i [meccanismi di distribuzione](/docs/it/managed-settings#delivery-mechanisms) descritti nella pagina delle impostazioni gestite, più comunemente:

517 517

518* [Server-managed settings](/docs/it/server-managed-settings), che Claude Code recupera dalla console di amministrazione claude.ai o da un [Claude apps gateway](/docs/it/claude-apps-gateway) auto-ospitato518* [Impostazioni gestite dal server](/docs/it/server-managed-settings), che Claude Code recupera dalla console di amministrazione claude.ai o da un [gateway Claude apps](/docs/it/claude-apps-gateway) self-hosted

519* Politiche MDM o a livello di sistema operativo, e file `managed-settings.json` in una directory di sistema519* Politiche MDM o a livello di sistema operativo, e file `managed-settings.json` in una directory di sistema

520* Un host di incorporamento come Claude Desktop, attraverso l'opzione SDK `managedSettings`; vedete [Control policy from an embedding host](/docs/it/managed-settings#parent-settings-from-embedding-hosts)520* Un host di incorporamento come Claude Desktop, tramite l'opzione `managedSettings` dell'SDK; consulta [Controllare le politiche da un host di incorporamento](/docs/it/managed-settings#parent-settings-from-embedding-hosts)

521 521

522In una sessione [Cowork](https://claude.com/docs/cowork/overview) che funziona sulla vostra macchina nell'app Claude Desktop, Claude Code non recupera le impostazioni gestite dal server dalla console di amministrazione claude.ai, e legge la politica distribuita al vostro dispositivo a meno che la configurazione Claude Desktop della vostra organizzazione non imposti `requireCoworkFullVmSandbox`. [Where and when a policy applies](/docs/it/managed-settings#where-and-when-a-policy-applies) copre Cowork e le sessioni cloud.522In una sessione [Cowork](https://claude.com/docs/cowork/overview) eseguita sulla tua macchina nell'app Claude Desktop, Claude Code non recupera le impostazioni gestite dal server dalla console di amministrazione claude.ai, e legge le politiche distribuite al tuo dispositivo a meno che la configurazione di Claude Desktop della tua organizzazione non imposti `requireCoworkFullVmSandbox`. [Dove e quando si applica una politica](/docs/it/managed-settings#where-and-when-a-policy-applies) tratta Cowork e le sessioni cloud.

523 523

524Se siete l'amministratore, [Set up Claude Code for your organization](/docs/it/admin-setup) vi guida attraverso la scelta di cosa applicare, e [Deploy managed settings](/docs/it/managed-settings) copre la distribuzione e come confermare che una politica è in vigore.524Se sei l'amministratore, [Configurare Claude Code per la tua organizzazione](/docs/it/admin-setup) ti guida nella scelta di cosa imporre, e [Distribuire le impostazioni gestite](/docs/it/managed-settings) tratta la distribuzione e come confermare che una politica è in vigore. Per l'avviso che l'editor delle impostazioni gestite nella console di amministrazione claude.ai può mostrare, consulta [Configurare le impostazioni gestite dal server](/docs/it/server-managed-settings#configure-server-managed-settings).

525 525

526<h2 id="change-a-setting">526<h2 id="change-a-setting">

527 Modificate un'impostazione527 Modificate un'impostazione

809 809

810Una [sessione cloud](/docs/it/claude-code-on-the-web) viene eseguita in un [ambiente cloud](/docs/it/cloud-environments) su un clone fresco del vostro repository, non sulla vostra macchina. Questo cambia quali impostazioni la raggiungono:810Una [sessione cloud](/docs/it/claude-code-on-the-web) viene eseguita in un [ambiente cloud](/docs/it/cloud-environments) su un clone fresco del vostro repository, non sulla vostra macchina. Questo cambia quali impostazioni la raggiungono:

811 811

812* **Impostazioni di progetto condivise** (`.claude/settings.json`): lette in una sessione con un repository, perché il file fa parte del clone e la sessione inizia al suo interno. Committate un'impostazione lì per applicarla in quelle sessioni. Una sessione con più repository inizia sopra i clone e legge solo i tasti `enabledPlugins` e `extraKnownMarketplaces` da ogni `.claude/settings.json` del repository, non le regole di permesso, gli hook, `env` o altre chiavi. I marketplace e i plugin che questi due tasti dichiarano ancora [non si caricano in una sessione cloud](/docs/it/cloud-environments#what-carries-over-from-your-setup).812* **Impostazioni di progetto condivise** (`.claude/settings.json`): lette in una sessione con un repository, perché il file fa parte del clone e la sessione inizia al suo interno. Esegui il commit di un'impostazione lì per applicarla in quelle sessioni. In un ambiente ospitato da Anthropic, una sessione con più repository inizia sopra i clone e legge solo le chiavi `enabledPlugins` e `extraKnownMarketplaces` dal `.claude/settings.json` di ogni repository, non le regole di permesso, gli hook, `env` o altre chiavi. I marketplace e i plugin che queste due chiavi dichiarano comunque [non si caricano in una sessione cloud](/docs/it/cloud-environments#what-carries-over-from-your-setup). Per un ambiente auto-ospitato, consulta [quali impostazioni del repository si applicano](/docs/it/self-hosted-environments-configuration#repository-settings-in-sessions-with-several-repositories).

813* **Impostazioni utente e di progetto locale** (`~/.claude/settings.json` e `.claude/settings.local.json`): non lette. Entrambe rimangono sulla vostra macchina, e il file locale non è nel clone.813* **Impostazioni utente e di progetto locale** (`~/.claude/settings.json` e `.claude/settings.local.json`): non lette. Entrambe rimangono sulla vostra macchina, e il file locale non è nel clone.

814* **Impostazioni gestite**: un file `managed-settings.json` o un profilo MDM sul vostro dispositivo non raggiunge una sessione cloud. Le [impostazioni gestite dal server](/docs/it/server-managed-settings) della vostra organizzazione lo fanno; la [copertura della superficie](/docs/it/model-config#surface-coverage) elenca quali sessioni cloud le ricevono. Un [ambiente auto-ospitato](/docs/it/self-hosted-environments) legge anche il file di impostazioni gestite nella sua immagine di runner. [Come Claude Code combina le fonti gestite](/docs/it/managed-settings#how-claude-code-combines-managed-sources) dice quando quel file si applica.814* **Impostazioni gestite**: un file `managed-settings.json` o un profilo MDM sul vostro dispositivo non raggiunge una sessione cloud. Le [impostazioni gestite dal server](/docs/it/server-managed-settings) della vostra organizzazione lo fanno; la [copertura della superficie](/docs/it/model-config#surface-coverage) elenca quali sessioni cloud le ricevono. Un [ambiente auto-ospitato](/docs/it/self-hosted-environments) legge anche il file di impostazioni gestite nella sua immagine di runner. [Come Claude Code combina le fonti gestite](/docs/it/managed-settings#how-claude-code-combines-managed-sources) dice quando quel file si applica.

815* **`/config`**: nel vostro browser su claude.ai/code, apre la sezione Claude Code delle vostre impostazioni claude.ai invece di modificare un valore. Per modificare un'impostazione per una sessione cloud, impostate una [variabile di ambiente](/docs/it/cloud-environments#set-environment-variables) sull'ambiente, o in una sessione con un repository, committate la chiave al `.claude/settings.json` di quel repository.815* **`/config`**: nel vostro browser su claude.ai/code, apre la sezione Claude Code delle vostre impostazioni claude.ai invece di modificare un valore. Per modificare un'impostazione per una sessione cloud, impostate una [variabile di ambiente](/docs/it/cloud-environments#set-environment-variables) sull'ambiente, o in una sessione con un repository, committate la chiave al `.claude/settings.json` di quel repository.

skills.md +2 −0

Details

97| `managed-agents-onboard <url>` | Crea il Managed Agent descritto dalla pagina all'URL, ad esempio una pagina della [documentazione di Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) | v2.1.290 o successivo |

98| `managed-agents-onboard <quickstart-name>` | Crea uno dei template di guida rapida della Console, come `deep-researcher`. Se indichi una sola parola che non è il nome di un template, Claude elenca i nomi validi | v2.1.290 o successivo |

98| `cost-optimize` | Profilare dove va la spesa Claude API del vostro progetto e proporre risparmi da opzioni come prompt caching, riduzione di token di input e output non necessari, batch processing, effort, e scelta del modello, una modifica alla volta | v2.1.247 o successivo |100| `cost-optimize` | Profilare dove va la spesa Claude API del vostro progetto e proporre risparmi da opzioni come prompt caching, riduzione di token di input e output non necessari, batch processing, effort, e scelta del modello, una modifica alla volta | v2.1.247 o successivo |

sub-agents.md +3 −1

Details

609La modalità di autorizzazione della conversazione principale decide se Claude Code utilizza il valore che imposta:609La modalità di autorizzazione della conversazione principale decide se Claude Code utilizza il valore che imposta:

610 610

611* Quando la conversazione principale è in `bypassPermissions`, `acceptEdits`, o [auto mode](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), il subagent viene eseguito in quella stessa modalità e Claude Code ignora il `permissionMode` che imposta. Sotto auto mode, il classificatore valuta le chiamate di strumenti del subagent con le regole di blocco e consentimento della conversazione principale. Quando il subagent finisce, il classificatore esamina anche il suo lavoro e il suo rapporto finale prima che il rapporto venga consegnato, come [Come auto mode gestisce i subagent](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) descrive.611* Quando la conversazione principale è in `bypassPermissions`, `acceptEdits`, o [auto mode](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), il subagent viene eseguito in quella stessa modalità e Claude Code ignora il `permissionMode` che imposta. Sotto auto mode, il classificatore valuta le chiamate di strumenti del subagent con le regole di blocco e consentimento della conversazione principale. Quando il subagent finisce, il classificatore esamina anche il suo lavoro e il suo rapporto finale prima che il rapporto venga consegnato, come [Come auto mode gestisce i subagent](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) descrive.

612* Quando la conversazione principale è in modalità `default`, `dontAsk`, o `plan`, il subagent viene eseguito nella modalità di autorizzazione che imposta, tranne `bypassPermissions`. Un subagent che dichiara `bypassPermissions` mantiene la modalità della conversazione principale. L'eccezione `bypassPermissions` richiede Claude Code v2.1.267 o successivo.612* Quando la conversazione principale è in modalità `default`, `dontAsk` o `plan`, il subagent viene eseguito nella modalità di permesso che imposti. Mantiene invece la modalità di permesso della conversazione principale in questi casi:

613 * Imposti `bypassPermissions`. L'eccezione per `bypassPermissions` richiede Claude Code v2.1.267 o successivo.

614 * Imposti `auto` e la [modalità auto non è disponibile](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) per il subagent, ad esempio quando un file di impostazioni imposta [`disableAutoMode`](/docs/it/settings-reference#disableautomode) o il modello del subagent non supporta la modalità auto.

613 615

614`permissionMode` accetta questi valori, e `manual` come alias per `default`:616`permissionMode` accetta questi valori, e `manual` come alias per `default`:

615 617

tools-reference.md +1 −1

Details

666 666

667* WebFetch rifiuta `localhost` e qualsiasi altro nome host senza un punto, come un nome intranet nudo, prima di effettuare una richiesta. L'[errore che restituisce](/docs/it/errors#webfetch-cannot-fetch-localhost) dice a Claude di raggiungere i server locali con `curl` tramite Bash invece.667* WebFetch rifiuta `localhost` e qualsiasi altro nome host senza un punto, come un nome intranet nudo, prima di effettuare una richiesta. L'[errore che restituisce](/docs/it/errors#webfetch-cannot-fetch-localhost) dice a Claude di raggiungere i server locali con `curl` tramite Bash invece.

668* Gli URL HTTP vengono automaticamente aggiornati a HTTPS.668* Gli URL HTTP vengono automaticamente aggiornati a HTTPS.

669* Le pagine grandi vengono troncate a un limite di caratteri fisso prima dell'elaborazione.669* WebFetch legge fino a 100.000 caratteri del contenuto di una pagina per chiamata. Su Claude Code v2.1.290 o versioni successive, il risultato per una pagina più lunga indica a Claude quanta parte non è stata letta, così Claude può recuperare la parte successiva.

670* WebFetch memorizza nella cache ogni risposta per 15 minuti per impostazione predefinita, quindi i recuperi ripetuti dello stesso URL vengono restituiti rapidamente. Su Claude Code v2.1.233 o versioni successive, impostare [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/it/env-vars#variables) per modificare il tempo in cui WebFetch mantiene ogni risposta.670* WebFetch memorizza nella cache ogni risposta per 15 minuti per impostazione predefinita, quindi i recuperi ripetuti dello stesso URL vengono restituiti rapidamente. Su Claude Code v2.1.233 o versioni successive, impostare [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/it/env-vars#variables) per modificare il tempo in cui WebFetch mantiene ogni risposta.

671* Una pagina che non ha terminato il download entro cinque minuti, inclusi tutti i reindirizzamenti che WebFetch segue, fallisce con un errore di deadline. Su Claude Code v2.1.268 o versioni successive, impostare [`CLAUDE_CODE_WEBFETCH_DEADLINE_MS`](/docs/it/env-vars#variables) per modificare il limite, o a `0` per rimuoverlo.671* Una pagina che non ha terminato il download entro cinque minuti, inclusi tutti i reindirizzamenti che WebFetch segue, fallisce con un errore di deadline. Su Claude Code v2.1.268 o versioni successive, impostare [`CLAUDE_CODE_WEBFETCH_DEADLINE_MS`](/docs/it/env-vars#variables) per modificare il limite, o a `0` per rimuoverlo.

672* Quando un URL reindirizza a un host diverso, WebFetch restituisce un risultato di testo che nomina l'URL originale e la destinazione del reindirizzamento invece di seguirlo. Claude quindi recupera il nuovo URL con una seconda chiamata WebFetch.672* Quando un URL reindirizza a un host diverso, WebFetch restituisce un risultato di testo che nomina l'URL originale e la destinazione del reindirizzamento invece di seguirlo. Claude quindi recupera il nuovo URL con una seconda chiamata WebFetch.

ultrareview.md +6 −6

Details

56 Esamina una pull request56 Esamina una pull request

57</h3>57</h3>

58 58

~~59Per esaminare una pull request di GitHub invece di un branch locale, passa il numero della PR:~~59Per esaminare una pull request su `github.com` invece di un branch locale, passa il numero della PR:

60 60

61```text theme={null}61```text theme={null}

62/code-review ultra 123462/code-review ultra 1234

64 64

65Il comando accetta anche `#1234`, `PR 1234` e URL di PR incollati; un URL incollato deve puntare al repository nella tua directory attuale.65Il comando accetta anche `#1234`, `PR 1234` e URL di PR incollati; un URL incollato deve puntare al repository nella tua directory attuale.

66 66

67In modalità PR, la sandbox cloud clona la pull request direttamente dall'host invece di raggruppare il tuo albero di lavoro locale. La modalità PR funziona con i repository su `github.com` e sulle istanze di [GitHub Enterprise Server](/docs/it/github-enterprise-server) che un Owner ha collegato a Claude Code.67La modalità PR richiede un repository su `github.com`. Per un repository su un'istanza di [GitHub Enterprise Server](/docs/it/github-enterprise-server), esegui invece `/code-review ultra` senza un numero di PR per esaminare il tuo branch locale.

68 68

~~69Per i repository su `github.com`, la sandbox clona con l'account GitHub collegato al tuo account Claude, quindi l'account deve poter leggere il repository della PR.~~69In modalità PR, la sandbox cloud clona la pull request da `github.com` invece di caricare il tuo albero di lavoro. Usa l'account GitHub collegato al tuo account Claude, quindi quell'account deve avere accesso in lettura al repository.

70 70

71Esegui [`/web-setup`](/docs/it/web-quickstart#connect-from-your-terminal) per collegare il tuo login della GitHub CLI al tuo account Claude.71Esegui [`/web-setup`](/docs/it/web-quickstart#connect-from-your-terminal) per collegare il tuo login della GitHub CLI al tuo account Claude.

72 72

74 Pubblica i risultati sulla pull request74 Pubblica i risultati sulla pull request

75</h3>75</h3>

76 76

77Su Claude Code v2.1.227 o successivo, quando esamini una pull request su `github.com`, puoi fare in modo che Claude pubblichi i risultati finali sulla PR come un singolo commento semplice dal tuo account GitHub. Il commento non è una review né un'approvazione, e termina con una nota "Generated by Claude Code". Quando esamini un branch o una pull request di GitHub Enterprise Server, Claude Code mostra i risultati solo nella tua sessione.77Su Claude Code v2.1.227 o successivo, quando esamini una pull request su `github.com`, puoi fare in modo che Claude pubblichi i risultati finali sulla PR come un singolo commento semplice dal tuo account GitHub. Il commento non è una review né un'approvazione, e termina con una nota "Generated by Claude Code". Quando esamini un branch, Claude Code mostra i risultati solo nella tua sessione.

78 78

79Claude Code non pubblica mai a meno che tu non lo scelga per quell'esecuzione, e `--no-post` è l'impostazione predefinita. La pubblicazione è una scelta che fai per ogni esecuzione:79Claude Code non pubblica mai a meno che tu non lo scelga per quell'esecuzione, e `--no-post` è l'impostazione predefinita. La pubblicazione è una scelta che fai per ogni esecuzione:

80 80

106Claude Code tratta il tuo testo come nota solo quando contiene più di una parola e non è un nome di branch o un riferimento a una PR. Interpreta una singola parola come nome di branch o riferimento a una PR, quindi un nome di branch digitato male produce l'errore del branch più simile descritto in [Revisione rispetto a una base diversa](#review-against-a-different-base) invece di avviare la revisione con una nota. Se il tuo testo combina un riferimento a una PR con altre parole, come `check PR 123 again`, Claude Code non avvia nemmeno la revisione; ti chiede di rieseguire il comando con il solo numero della PR per esaminare quella PR, oppure senza il riferimento per esaminare il tuo branch attuale.106Claude Code tratta il tuo testo come nota solo quando contiene più di una parola e non è un nome di branch o un riferimento a una PR. Interpreta una singola parola come nome di branch o riferimento a una PR, quindi un nome di branch digitato male produce l'errore del branch più simile descritto in [Revisione rispetto a una base diversa](#review-against-a-different-base) invece di avviare la revisione con una nota. Se il tuo testo combina un riferimento a una PR con altre parole, come `check PR 123 again`, Claude Code non avvia nemmeno la revisione; ti chiede di rieseguire il comando con il solo numero della PR per esaminare quella PR, oppure senza il riferimento per esaminare il tuo branch attuale.

107 107

108<Tip>108<Tip>

109 Se il tuo repository è troppo grande per essere raggruppato, Claude Code ti chiede di usare invece la modalità PR. Esegui il push del tuo branch e apri una PR in bozza, quindi esegui `/code-review ultra <PR-number>`.109 Se il tuo repository è troppo grande per essere raggruppato, Claude Code ti chiede di usare invece la modalità PR. Per un repository su `github.com`, esegui il push del tuo branch e apri una PR in bozza, quindi esegui `/code-review ultra <PR-number>`.

110</Tip>110</Tip>

111 111

112<h3 id="diff-limits-and-fallbacks">112<h3 id="diff-limits-and-fallbacks">

173claude ultrareview origin/main173claude ultrareview origin/main

174```174```

175 175

176Senza argomenti, il sottocomando esamina il diff tra il tuo branch corrente e il branch predefinito, con lo stesso [fallback sull'intero repository](#diff-limits-and-fallbacks) di `/code-review ultra` quando non esiste una base di merge. Passa un numero di PR per esaminare una pull request, oppure un branch di base per eseguire la revisione rispetto a quello; la [gestione del branch di base](#review-against-a-different-base) corrisponde a quella del comando interattivo.176Senza argomenti, il sottocomando esamina il diff tra il tuo branch corrente e il branch predefinito, con lo stesso [fallback sull'intero repository](#diff-limits-and-fallbacks) di `/code-review ultra` quando non esiste una base di merge. Passa un numero di PR per [esaminare una pull request su `github.com`](#review-a-pull-request), oppure un branch di base per eseguire la revisione rispetto a quello; la [gestione del branch di base](#review-against-a-different-base) corrisponde a quella del comando interattivo.

177 177

178Quando esegui il sottocomando, acconsenti al fallback sull'intero repository e al prompt relativo a fatturazione e termini, quindi l'esecuzione parte senza attendere input. È il fatto di eseguirlo tu stesso a valere come consenso. Quando invece è Claude a eseguire il sottocomando per te, ad esempio tramite lo strumento Bash, Claude Code rifiuta la revisione dell'intero repository.178Quando esegui il sottocomando, acconsenti al fallback sull'intero repository e al prompt relativo a fatturazione e termini, quindi l'esecuzione parte senza attendere input. È il fatto di eseguirlo tu stesso a valere come consenso. Quando invece è Claude a eseguire il sottocomando per te, ad esempio tramite lo strumento Bash, Claude Code rifiuta la revisione dell'intero repository.

179 179

workflows.md +27 −1

Details

354 354

355Il corpo è JavaScript semplice con `await` di livello superiore. `agent()` genera un subagente, `pipeline()` ne esegue uno per elemento in un elenco, e `parallel()` esegue un insieme di attività di agente contemporaneamente e attende che tutte si completino.355Il corpo è JavaScript semplice con `await` di livello superiore. `agent()` genera un subagente, `pipeline()` ne esegue uno per elemento in un elenco, e `parallel()` esegue un insieme di attività di agente contemporaneamente e attende che tutte si completino.

356 356

357Una chiamata `agent()` si risolve in `null` se la interrompi a metà esecuzione o se raggiunge un errore API irrecuperabile. `pipeline()` mantiene ogni `null` nell'array dei risultati, motivo per cui l'esempio termina con `.filter(Boolean)` per eliminare quelle voci.357Una chiamata `agent()` si risolve in `null` se la interrompi a metà esecuzione o se raggiunge un errore API irrecuperabile. `pipeline()` mantiene ogni `null` nell'array dei risultati, motivo per cui l'esempio termina con `.filter(Boolean)` per eliminare quelle voci, incluso lo slot di [un agente che si è bloccato a ogni tentativo](#when-an-agent-stalls-and-restarts).

358 358

359In [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), il prompt che il tuo script passa a `agent()` non conta come una richiesta da te quando il classificatore esamina le azioni di quel subagente, perché Claude Code lo contrassegna come testo che lo script ha calcolato.359In [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), il prompt che il tuo script passa a `agent()` non conta come una richiesta da te quando il classificatore esamina le azioni di quel subagente, perché Claude Code lo contrassegna come testo che lo script ha calcolato.

360 360

463* Il limite si ripristina entro 24 ore. Un limite settimanale può ripristinarsi più avanti.463* Il limite si ripristina entro 24 ore. Un limite settimanale può ripristinarsi più avanti.

464* L'esecuzione non ha già aspettato due volte. Quando raggiunge il limite una terza volta, l'agente fallisce.464* L'esecuzione non ha già aspettato due volte. Quando raggiunge il limite una terza volta, l'agente fallisce.

465 465

466<h3 id="when-an-agent-stalls-and-restarts">

467 Quando un agente si blocca e si riavvia

468</h3>

469

470Un agente il cui output smette di arrivare per un tempo sufficientemente lungo ricomincia dallo stesso prompt. In [`/workflows`](#watch-the-run), al suo nome viene aggiunto il suffisso `(retry 1)` e il suo dettaglio mostra `attempt 2 (stalled)`. Il riavvio è automatico, quindi non devi fare nulla.

471

472Il nuovo tentativo parte senza la trascrizione del tentativo bloccato. I file che il tentativo bloccato ha già modificato restano modificati, e i token che ha speso restano nel totale dell'esecuzione. La finestra di stallo è il tempo per cui Claude Code attende output da un agente prima di terminare il tentativo. Il tempo che l'agente trascorre in attesa delle proprie chiamate agli strumenti o del [ripristino di un limite di utilizzo](#when-a-run-hits-your-usage-limit) non conta ai fini della finestra di stallo.

473

474Un agente si riavvia al massimo cinque volte, contando qualsiasi riavvio che richiedi con `r`. Se anche il sesto tentativo si blocca, la chiamata `agent()` fallisce, e l'inizio dell'errore ne indica il motivo:

475

476* `agent stalled on all 6 attempts`: ogni tentativo ha trascorso l'intera finestra senza output. Se il lavoro dell'agente lo mantiene silenzioso così a lungo, allunga la finestra

477* `agent lost its reply on all 6 attempts`: lo stream della risposta di ogni tentativo è diventato silenzioso e Claude Code ha smesso di attenderlo. Allungare la finestra di stallo non aiuta, poiché un [watchdog di inattività dello streaming](/docs/it/network-config#streaming-idle-watchdogs) ha terminato prima la risposta e `CLAUDE_STREAM_IDLE_TIMEOUT_MS` imposta il timeout di quel watchdog

478* `agent abandoned after 6 attempts`: i tentativi sono terminati in modi diversi, che l'errore elenca in ordine

479

480Per dare a un agente più tempo per produrre output prima che la finestra termini:

481

482* **Un agente**: passa `stallMs` in millisecondi nella sua chiamata `agent()`, ad esempio `agent(prompt, { stallMs: 1800000 })` per 30 minuti

483* **Ogni agente**: imposta [`CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`](/docs/it/env-vars#variables), che si applica anche ai subagent al di fuori dei workflow

484

485Se l'esecuzione continua dopo l'errore dipende da come il tuo script ha chiamato l'agente:

486

487* **All'interno di [`parallel()` o `pipeline()`](#what-the-saved-script-looks-like)**: l'esecuzione prosegue con `null` al posto del risultato dell'agente

488* **Atteso direttamente**: l'esecuzione termina con l'errore

489

490Per riprovare, chiedi a Claude di riavviare il workflow. [Riprendere dopo una pausa](#resume-after-a-pause) spiega cosa viene eseguito di nuovo.

491

466<h3 id="cost">492<h3 id="cost">

467 Costo493 Costo

468</h3>494</h3>

worktrees.md +1 −1

Details

104* **Reindirizzamenti git**: Claude Code blocca un comando Bash o Monitor che reindirizza git nel checkout principale. Il reindirizzamento può provenire attraverso `git -C`, `--git-dir`, una variabile `GIT_DIR` o `GIT_WORK_TREE`, o un `cd` nel checkout principale prima di eseguire git.104* **Reindirizzamenti git**: Claude Code blocca un comando Bash o Monitor che reindirizza git nel checkout principale. Il reindirizzamento può provenire attraverso `git -C`, `--git-dir`, una variabile `GIT_DIR` o `GIT_WORK_TREE`, o un `cd` nel checkout principale prima di eseguire git.

105* **Forma del comando**: Claude Code blocca un comando Bash o Monitor quando non può verificare dal testo del comando che qualsiasi git che il comando esegue rimane all'interno del worktree. Questo accade, ad esempio, quando il nome del comando è calcolato a runtime, quando la sintassi non può essere analizzata, o quando un'espansione come `${!name}` o `${ command; }` potrebbe eseguire un comando che il testo non esplicita. Claude Code dice a Claude come riscrivere il comando rifiutato, come dividerlo in comandi semplici e separati. Non potete disattivare questo controllo.105* **Forma del comando**: Claude Code blocca un comando Bash o Monitor quando non può verificare dal testo del comando che qualsiasi git che il comando esegue rimane all'interno del worktree. Questo accade, ad esempio, quando il nome del comando è calcolato a runtime, quando la sintassi non può essere analizzata, o quando un'espansione come `${!name}` o `${ command; }` potrebbe eseguire un comando che il testo non esplicita. Claude Code dice a Claude come riscrivere il comando rifiutato, come dividerlo in comandi semplici e separati. Non potete disattivare questo controllo.

106 106

107Questi controlli leggono il percorso a cui è destinata una modifica, la directory in cui viene eseguito un comando e il testo del comando. Nessuno di essi tiene traccia di quali file scrive un comando della shell, quindi un comando che scrive nel checkout principale senza eseguirvi git, come `cp` o un reindirizzamento della shell, non viene rifiutato da questi controlli. Claude Code tratta quel comando come qualsiasi altro comando della shell, quindi se viene eseguito o se ti chiede conferma dipende dalla tua [modalità di permesso](/docs/it/permission-modes) e dalle tue regole.107Questi controlli leggono il percorso a cui è destinata una modifica, la directory in cui viene eseguito un comando e il testo del comando. Nessuno di essi tiene traccia di quali file scrive un comando della shell, quindi un comando che scrive nel checkout principale senza eseguirvi git, come `cp` o un reindirizzamento della shell, non viene rifiutato da questi controlli. Claude Code tratta quel comando come qualsiasi altro comando della shell, in base alle tue impostazioni di [permessi](/docs/it/permissions) e [sandboxing](/docs/it/sandboxing).

108 108

109I controlli si applicano al repository da cui avete lanciato Claude Code. Coprono anche il checkout principale da cui un worktree collegato è collegato. Per i comandi PowerShell, Claude Code applica solo il controllo della directory di lavoro.109I controlli si applicano al repository da cui avete lanciato Claude Code. Coprono anche il checkout principale da cui un worktree collegato è collegato. Per i comandi PowerShell, Claude Code applica solo il controllo della directory di lavoro.

110 110

Documentation 2026-10-08 22:58 UTC to 2026-10-09 11:01 UTC