Documentation — Spybara

admin-setup.md +2 −0

Details

91| [Required version range](/it/settings) | Rifiutare di avviarsi completamente quando la versione in esecuzione è al di fuori di un intervallo approvato dall'organizzazione. Più forte di `minimumVersion`, che blocca solo i downgrade | `requiredMinimumVersion`, `requiredMaximumVersion` |91| [Required version range](/it/settings) | Rifiutare di avviarsi completamente quando la versione in esecuzione è al di fuori di un intervallo approvato dall'organizzazione. Più forte di `minimumVersion`, che blocca solo i downgrade | `requiredMinimumVersion`, `requiredMaximumVersion` |

92 92

93Le organizzazioni i cui membri si autenticano tramite claude.ai o l'API Anthropic possono anche governare i modelli senza distribuire impostazioni: le [restrizioni del modello dell'organizzazione](/it/model-config#organization-model-restrictions) disabilitano i singoli modelli, un [modello predefinito dell'organizzazione](/it/model-config#organization-default-model) imposta quale modello le nuove sessioni iniziano, e i [limiti di sforzo dell'organizzazione](/it/model-config#organization-effort-limits) limitano i livelli di sforzo per ruolo. Tutti e tre i controlli richiedono un piano Claude Enterprise. Le restrizioni dei modelli e i limiti di sforzo sono applicati lato server; il modello predefinito è un punto di partenza che gli utenti possono modificare, a meno che l'organizzazione non lo applichi. L'applicazione è disponibile per un set limitato di organizzazioni; chiedi al tuo team di account Anthropic sulla disponibilità. Nessuno di questi controlli raggiunge le sessioni su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, o [Claude Platform on AWS](/it/claude-platform-on-aws); su questi provider, utilizza `availableModels` sopra per le restrizioni e la chiave `model` nelle impostazioni gestite per un valore predefinito.

93Le regole di autorizzazione e il sandboxing coprono livelli diversi. Negare WebFetch blocca lo strumento fetch di Claude, ma se Bash è consentito, `curl` e `wget` possono comunque raggiungere qualsiasi URL. Il sandboxing chiude questo divario con un allowlist di domini di rete applicato a livello di sistema operativo.95Le regole di autorizzazione e il sandboxing coprono livelli diversi. Negare WebFetch blocca lo strumento fetch di Claude, ma se Bash è consentito, `curl` e `wget` possono comunque raggiungere qualsiasi URL. Il sandboxing chiude questo divario con un allowlist di domini di rete applicato a livello di sistema operativo.

94 96

95Per il modello di minaccia che questi controlli difendono, consulta [Security](/it/security).97Per il modello di minaccia che questi controlli difendono, consulta [Security](/it/security).

advisor.md +4 −3

Details

85L'advisor deve essere almeno altrettanto capace del modello principale. Gli advisor accettati per ogni modello principale sono:85L'advisor deve essere almeno altrettanto capace del modello principale. Gli advisor accettati per ogni modello principale sono:

86 86

88| ----------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |88| ----------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

90| Sonnet 4.6 | Fable, Opus, Sonnet | |90| Sonnet 4.6 | Fable, Opus, Sonnet | |

93| Opus 4.7 o successivo | Fable, Opus 4.7, Opus 4.8 | Opus 4.7 e Opus 4.8 sono classificati come ugualmente capaci, quindi uno accetta l'altro come advisor. Un Opus 4.7 principale con un advisor Opus 4.6 o Sonnet 5 viene rifiutato |

93| Fable 5 ({/* min-version: 2.1.170 */}v2.1.170+) | Fable | Un advisor Opus o Sonnet viene rifiutato |94| Fable 5 ({/* min-version: 2.1.170 */}v2.1.170+) | Fable | Un advisor Opus o Sonnet viene rifiutato |

94 95

95Fable 5 richiede Claude Code v2.1.170 o successivo e accesso a Fable 5, sia che agisca come modello principale che come advisor.96Fable 5 richiede Claude Code v2.1.170 o successivo e accesso a Fable 5, sia che agisca come modello principale che come advisor.

174/advisor off175/advisor off

175```176```

176 177

177Per disabilitare completamente lo strumento advisor, incluso il comando `/advisor` e il flag `--advisor`, imposta `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`. Vedi [Environment variables](/it/env-vars).178Per disabilitare completamente lo strumento advisor, imposta `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`. Il comando `/advisor` diventa non disponibile e qualsiasi `advisorModel` configurato viene ignorato. Il flag `--advisor` è accettato ma non ha alcun effetto; gli script esistenti che lo passano continuano a funzionare senza errori. Vedi [Environment variables](/it/env-vars).

178 179

179<h2 id="compare-with-related-features">180<h2 id="compare-with-related-features">

180 Confronta con funzionalità correlate181 Confronta con funzionalità correlate

agent-sdk/agent-loop.md +41 −0

Details

86<Accordion title="Esempio: Controllare i tipi di messaggi e gestire i risultati">86<Accordion title="Esempio: Controllare i tipi di messaggi e gestire i risultati">

87 <CodeGroup>87 <CodeGroup>

88 ```python Python theme={null}88 ```python Python theme={null}

89 import asyncio

89 from claude_agent_sdk import query, AssistantMessage, ResultMessage90 from claude_agent_sdk import query, AssistantMessage, ResultMessage

90 91

93 async def main():

94 try:

91 async for message in query(prompt="Summarize this project"):95 async for message in query(prompt="Summarize this project"):

92 if isinstance(message, AssistantMessage):96 if isinstance(message, AssistantMessage):

93 print(f"Turn completed: {len(message.content)} content blocks")97 print(f"Turn completed: {len(message.content)} content blocks")

96 print(message.result)100 print(message.result)

97 else:101 else:

98 print(f"Stopped: {message.subtype}")102 print(f"Stopped: {message.subtype}")

103 except Exception as error:

104 # A single-shot query() raises after yielding an error result. If the

105 # failure was an error result, the error subtype branches above have

106 # already run; connection or process failures yield no result message.

107 print(f"Session ended with an error: {error}")

108

109

110 asyncio.run(main())

99 ```111 ```

100 112

101 ```typescript TypeScript theme={null}113 ```typescript TypeScript theme={null}

102 import { query } from "@anthropic-ai/claude-agent-sdk";114 import { query } from "@anthropic-ai/claude-agent-sdk";

103 115

116 try {

104 for await (const message of query({ prompt: "Summarize this project" })) {117 for await (const message of query({ prompt: "Summarize this project" })) {

105 if (message.type === "assistant") {118 if (message.type === "assistant") {

106 console.log(`Turn completed: ${message.message.content.length} content blocks`);119 console.log(`Turn completed: ${message.message.content.length} content blocks`);

113 }126 }

114 }127 }

115 }128 }

129 } catch (error) {

130 // A single-shot query() throws after yielding an error result. If the

131 // failure was an error result, the error subtype branches above have

132 // already run; connection or process failures yield no result message.

133 console.log(`Session ended with an error: ${error}`);

134 }

116 ```135 ```

117 </CodeGroup>136 </CodeGroup>

118</Accordion>137</Accordion>

321 340

322Il campo `result` (l'output di testo finale) è presente solo sulla variante `success`, quindi controllate sempre il sottotipo prima di leggerlo. Tutti i sottotipi di risultato portano `total_cost_usd`, `usage`, `num_turns` e `session_id` in modo che possiate tracciare il costo e riprendere anche dopo gli errori. In Python, `total_cost_usd` e `usage` sono tipizzati come opzionali e possono essere `None` su alcuni percorsi di errore, quindi proteggete prima di formattarli. Vedere [Tracciamento di costi e utilizzo](/it/agent-sdk/cost-tracking) per i dettagli sull'interpretazione dei campi `usage`.341Il campo `result` (l'output di testo finale) è presente solo sulla variante `success`, quindi controllate sempre il sottotipo prima di leggerlo. Tutti i sottotipi di risultato portano `total_cost_usd`, `usage`, `num_turns` e `session_id` in modo che possiate tracciare il costo e riprendere anche dopo gli errori. In Python, `total_cost_usd` e `usage` sono tipizzati come opzionali e possono essere `None` su alcuni percorsi di errore, quindi proteggete prima di formattarli. Vedere [Tracciamento di costi e utilizzo](/it/agent-sdk/cost-tracking) per i dettagli sull'interpretazione dei campi `usage`.

323 342

343<Note>

344 Quando una query termina con un risultato di errore:

345

346 * Una singola chiamata `query()` produce il messaggio di risultato finale, quindi genera un errore che include il testo dell'errore, come `Reached maximum number of turns`. L'eccezione è intenzionale — avvolgete il ciclo in un blocco try se il vostro codice deve continuare oltre. Anche il processo Claude Code sottostante esce con un codice diverso da zero.

347 * Una sessione di input in streaming rimane attiva e potete continuare a inviare messaggi.

348</Note>

349

324Il risultato include anche un campo `stop_reason` (`string | null` in TypeScript, `str | None` in Python) che indica perché il modello ha smesso di generare al suo turno finale. I valori comuni sono `end_turn` (il modello ha terminato normalmente), `max_tokens` (ha raggiunto il limite di token di output) e `refusal` (il modello ha rifiutato la richiesta). Su sottotipi di risultato di errore, `stop_reason` porta il valore dall'ultima risposta dell'assistente prima che il ciclo terminasse. Per rilevare i rifiuti, controllate `stop_reason === "refusal"` (TypeScript) o `stop_reason == "refusal"` (Python). Vedere [`SDKResultMessage`](/it/agent-sdk/typescript#sdkresultmessage) (TypeScript) o [`ResultMessage`](/it/agent-sdk/python#resultmessage) (Python) per il tipo completo.350Il risultato include anche un campo `stop_reason` (`string | null` in TypeScript, `str | None` in Python) che indica perché il modello ha smesso di generare al suo turno finale. I valori comuni sono `end_turn` (il modello ha terminato normalmente), `max_tokens` (ha raggiunto il limite di token di output) e `refusal` (il modello ha rifiutato la richiesta). Su sottotipi di risultato di errore, `stop_reason` porta il valore dall'ultima risposta dell'assistente prima che il ciclo terminasse. Per rilevare i rifiuti, controllate `stop_reason === "refusal"` (TypeScript) o `stop_reason == "refusal"` (Python). Vedere [`SDKResultMessage`](/it/agent-sdk/typescript#sdkresultmessage) (TypeScript) o [`ResultMessage`](/it/agent-sdk/python#resultmessage) (Python) per il tipo completo.

325 351

326<h2 id="hooks">352<h2 id="hooks">

348 374

349Questo esempio combina i concetti chiave di questa pagina in un singolo agente che corregge i test falliti. Configura l'agente con strumenti consentiti (pre-approvati in modo che l'agente funzioni autonomamente), impostazioni del progetto e limiti di sicurezza su turni e sforzo di ragionamento. Mentre il ciclo viene eseguito, cattura l'ID della sessione per una potenziale ripresa, gestisce il risultato finale e stampa il costo totale.375Questo esempio combina i concetti chiave di questa pagina in un singolo agente che corregge i test falliti. Configura l'agente con strumenti consentiti (pre-approvati in modo che l'agente funzioni autonomamente), impostazioni del progetto e limiti di sicurezza su turni e sforzo di ragionamento. Mentre il ciclo viene eseguito, cattura l'ID della sessione per una potenziale ripresa, gestisce il risultato finale e stampa il costo totale.

350 376

377Poiché una singola chiamata `query()` genera un'eccezione dopo aver restituito un risultato di errore, il ciclo è avvolto in un blocco try in modo che lo script esca correttamente quando viene raggiunto un limite.

378

351<CodeGroup>379<CodeGroup>

352 ```python Python theme={null}380 ```python Python theme={null}

353 import asyncio381 import asyncio

357 async def run_agent():385 async def run_agent():

358 session_id = None386 session_id = None

359 387

388 try:

360 async for message in query(389 async for message in query(

361 prompt="Find and fix the bug causing test failures in the auth module",390 prompt="Find and fix the bug causing test failures in the auth module",

362 options=ClaudeAgentOptions(391 options=ClaudeAgentOptions(

389 print(f"Stopped: {message.subtype}")418 print(f"Stopped: {message.subtype}")

390 if message.total_cost_usd is not None:419 if message.total_cost_usd is not None:

391 print(f"Cost: ${message.total_cost_usd:.4f}")420 print(f"Cost: ${message.total_cost_usd:.4f}")

421 except Exception as error:

422 # A single-shot query() raises after yielding an error result. If the

423 # failure was an error result, the error subtype branches above have

424 # already run; connection or process failures yield no result message.

425 print(f"Session ended with an error: {error}")

392 426

393 427

394 asyncio.run(run_agent())428 asyncio.run(run_agent())

399 433

400 let sessionId: string | undefined;434 let sessionId: string | undefined;

401 435

436 try {

402 for await (const message of query({437 for await (const message of query({

403 prompt: "Find and fix the bug causing test failures in the auth module",438 prompt: "Find and fix the bug causing test failures in the auth module",

404 options: {439 options: {

428 console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);463 console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);

429 }464 }

430 }465 }

466 } catch (error) {

467 // A single-shot query() throws after yielding an error result. If the

468 // failure was an error result, the error subtype branches above have

469 // already run; connection or process failures yield no result message.

470 console.log(`Session ended with an error: ${error}`);

471 }

431 ```472 ```

432</CodeGroup>473</CodeGroup>

433 474

agent-sdk/cost-tracking.md +45 −2

Details

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

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

65 65

66 try {

66 for await (const message of query({ prompt: "Summarize this project" })) {67 for await (const message of query({ prompt: "Summarize this project" })) {

67 if (message.type === "result") {68 if (message.type === "result") {

68 console.log(`Total cost: $${message.total_cost_usd}`);69 console.log(`Total cost: $${message.total_cost_usd}`);

69 }70 }

70 }71 }

72 } catch (error) {

73 // A single-shot query() throws after yielding an error result. If the

74 // failure was an error result, it still carried total_cost_usd and the

75 // branch above has already run; connection or process failures yield

76 // no result message.

77 console.error(`Session ended with an error: ${error}`);

78 }

71 ```79 ```

72 80

73 ```python Python theme={null}81 ```python Python theme={null}

76 84

77 85

78 async def main():86 async def main():

87 try:

79 async for message in query(prompt="Summarize this project"):88 async for message in query(prompt="Summarize this project"):

80 if isinstance(message, ResultMessage):89 if isinstance(message, ResultMessage):

81 print(f"Total cost: ${message.total_cost_usd or 0}")90 print(f"Total cost: ${message.total_cost_usd or 0}")

91 except Exception as error:

92 # A single-shot query() raises after yielding an error result. If the

93 # failure was an error result, it still carried total_cost_usd and the

94 # branch above has already run; connection or process failures yield

95 # no result message.

96 print(f"Session ended with an error: {error}")

82 97

83 98

84 asyncio.run(main())99 asyncio.run(main())

110let totalInputTokens = 0;125let totalInputTokens = 0;

111let totalOutputTokens = 0;126let totalOutputTokens = 0;

112 127

113for await (const message of query({ prompt: "Summarize this project" })) {128try {

129 for await (const message of query({ prompt: "Summarize this project" })) {

114 if (message.type === "assistant") {130 if (message.type === "assistant") {

115 const msgId = message.message.id;131 const msgId = message.message.id;

116 132

121 totalOutputTokens += message.message.usage.output_tokens;137 totalOutputTokens += message.message.usage.output_tokens;

122 }138 }

123 }139 }

140 }

141} catch (error) {

142 // A single-shot query() throws after yielding an error result, so the

143 // totals below still reflect the steps that ran before the failure.

144 console.error(`Session ended with an error: ${error}`);

124}145}

125 146

126console.log(`Steps: ${seenIds.size}`);147console.log(`Steps: ${seenIds.size}`);

139```typescript theme={null}160```typescript theme={null}

140import { query } from "@anthropic-ai/claude-agent-sdk";161import { query } from "@anthropic-ai/claude-agent-sdk";

141 162

142for await (const message of query({ prompt: "Summarize this project" })) {163try {

164 for await (const message of query({ prompt: "Summarize this project" })) {

143 if (message.type !== "result") continue;165 if (message.type !== "result") continue;

144 166

145 for (const [modelName, usage] of Object.entries(message.modelUsage)) {167 for (const [modelName, usage] of Object.entries(message.modelUsage)) {

149 console.log(` Cache read: ${usage.cacheReadInputTokens}`);171 console.log(` Cache read: ${usage.cacheReadInputTokens}`);

150 console.log(` Cache creation: ${usage.cacheCreationInputTokens}`);172 console.log(` Cache creation: ${usage.cacheCreationInputTokens}`);

151 }173 }

174 }

175} catch (error) {

176 // A single-shot query() throws after yielding an error result. If the

177 // failure was an error result, the per-model breakdown above has already

178 // printed; connection or process failures yield no result message.

179 console.error(`Session ended with an error: ${error}`);

152}180}

153```181```

154 182

173 ];201 ];

174 202

175 for (const prompt of prompts) {203 for (const prompt of prompts) {

204 try {

176 for await (const message of query({ prompt })) {205 for await (const message of query({ prompt })) {

177 if (message.type === "result") {206 if (message.type === "result") {

178 totalSpend += message.total_cost_usd;207 totalSpend += message.total_cost_usd;

179 console.log(`This call: $${message.total_cost_usd}`);208 console.log(`This call: $${message.total_cost_usd}`);

180 }209 }

181 }210 }

211 } catch (error) {

212 // A single-shot query() throws after yielding an error result. If the

213 // failure was an error result, this call's cost was already counted;

214 // connection or process failures yield no result message. Continue

215 // with the next prompt.

216 console.error(`Call failed: ${error}`);

217 }

182 }218 }

183 219

184 console.log(`Total spend: $${totalSpend.toFixed(4)}`);220 console.log(`Total spend: $${totalSpend.toFixed(4)}`);

199 ]235 ]

200 236

201 for prompt in prompts:237 for prompt in prompts:

238 try:

202 async for message in query(prompt=prompt):239 async for message in query(prompt=prompt):

203 if isinstance(message, ResultMessage):240 if isinstance(message, ResultMessage):

204 cost = message.total_cost_usd or 0241 cost = message.total_cost_usd or 0

205 total_spend += cost242 total_spend += cost

206 print(f"This call: ${cost}")243 print(f"This call: ${cost}")

244 except Exception as error:

245 # A single-shot query() raises after yielding an error result. If

246 # the failure was an error result, this call's cost was already

247 # counted; connection or process failures yield no result message.

248 # Continue with the next prompt.

249 print(f"Call failed: {error}")

207 250

208 print(f"Total spend: ${total_spend:.4f}")251 print(f"Total spend: ${total_spend:.4f}")

209 252

agent-sdk/file-checkpointing.md +25 −7

Details

50 50

51Per utilizzare il checkpointing dei file, abilitalo nelle tue opzioni, acquisisci gli UUID di checkpoint dal flusso di risposta, quindi chiama `rewindFiles()` (TypeScript) o `rewind_files()` (Python) quando hai bisogno di ripristinare.51Per utilizzare il checkpointing dei file, abilitalo nelle tue opzioni, acquisisci gli UUID di checkpoint dal flusso di risposta, quindi chiama `rewindFiles()` (TypeScript) o `rewind_files()` (Python) quando hai bisogno di ripristinare.

52 52

53L'esempio seguente mostra il flusso completo: abilita il checkpointing, acquisisci l'UUID di checkpoint e l'ID di sessione dal flusso di risposta, quindi riprendi la sessione in seguito per ripristinare i file. Ogni passaggio è spiegato in dettaglio di seguito.53L'esempio seguente mostra il flusso completo: abilita il checkpointing, acquisisci l'UUID di checkpoint e l'ID di sessione dal flusso di risposta, quindi riprendi la sessione in seguito per ripristinare i file. Ogni passaggio è spiegato in dettaglio di seguito. Gli esempi in questa sezione utilizzano il prompt "Refactor the authentication module". Eseguili in un progetto che contiene un modulo di autenticazione, oppure modifica il prompt per nominare file che esistono nel tuo progetto, in modo da poter osservare i file cambiare e vedere il ripristino ripristinarli.

54 54

55<CodeGroup>55<CodeGroup>

56 ```python Python theme={null}56 ```python Python theme={null}

197 session_id = None197 session_id = None

198 198

199 async for message in client.receive_response():199 async for message in client.receive_response():

200 # Update checkpoint on each user message (keeps the latest)200 # Capture the first user message UUID as the checkpoint

201 if isinstance(message, UserMessage) and message.uuid:201 if isinstance(message, UserMessage) and message.uuid and checkpoint_id is None:

202 checkpoint_id = message.uuid202 checkpoint_id = message.uuid

203 # Capture session ID from the result message203 # Capture session ID from the result message

204 if isinstance(message, ResultMessage):204 if isinstance(message, ResultMessage):

210 let sessionId: string | undefined;210 let sessionId: string | undefined;

211 211

212 for await (const message of response) {212 for await (const message of response) {

213 // Update checkpoint on each user message (keeps the latest)213 // Capture the first user message UUID as the checkpoint

214 if (message.type === "user" && message.uuid) {214 if (message.type === "user" && message.uuid && !checkpointId) {

215 checkpointId = message.uuid;215 checkpointId = message.uuid;

216 }216 }

217 // Capture session ID from any message that has it217 // Capture session ID from any message that has it

250 ```250 ```

251 </CodeGroup>251 </CodeGroup>

252 252

253 Se acquisisci l'ID di sessione e l'ID di checkpoint, puoi anche ripristinare dalla CLI:253 Se acquisisci l'ID di sessione e l'ID di checkpoint, puoi anche ripristinare dalla CLI. Questo comando richiede l'eseguibile `claude`, che proviene da [installazione di Claude Code](/it/setup) e non è installato dal pacchetto SDK. L'SDK abilita il checkpointing per te, ma quando esegui `claude -p` direttamente devi impostare la variabile di ambiente `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING`:

254 254

255 ```bash theme={null}255 ```bash theme={null}

256 claude -p --resume <session-id> --rewind-files <checkpoint-uuid>256 CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>

257 ```257 ```

258

259 Il flag `--rewind-files` non appare nell'output di `claude --help`, ma la CLI lo accetta come mostrato.

258 </Step>260 </Step>

259</Steps>261</Steps>

260 262

270 272

271Questo modello mantiene solo l'UUID di checkpoint più recente, aggiornandolo prima di ogni turno dell'agente. Se qualcosa va storto durante l'elaborazione, puoi immediatamente ripristinare all'ultimo stato sicuro e uscire dal ciclo.273Questo modello mantiene solo l'UUID di checkpoint più recente, aggiornandolo prima di ogni turno dell'agente. Se qualcosa va storto durante l'elaborazione, puoi immediatamente ripristinare all'ultimo stato sicuro e uscire dal ciclo.

272 274

275Prima di eseguire questo esempio, sostituisci `your_revert_condition` (Python) o `yourRevertCondition` (TypeScript) con il tuo controllo personale, come il rilevamento di errori o un errore di convalida; il segnaposto non è definito nell'esempio.

276

273<CodeGroup>277<CodeGroup>

274 ```python Python theme={null}278 ```python Python theme={null}

275 import asyncio279 import asyncio

752 756

753**Soluzione**: Assicurati che `enable_file_checkpointing=True` (Python) o `enableFileCheckpointing: true` (TypeScript) fosse impostato sulla sessione originale, quindi utilizza il modello mostrato negli esempi: acquisisci il primo UUID del messaggio dell'utente, completa la sessione completamente, quindi riprendi con un prompt vuoto e chiama `rewindFiles()` una volta.757**Soluzione**: Assicurati che `enable_file_checkpointing=True` (Python) o `enableFileCheckpointing: true` (TypeScript) fosse impostato sulla sessione originale, quindi utilizza il modello mostrato negli esempi: acquisisci il primo UUID del messaggio dell'utente, completa la sessione completamente, quindi riprendi con un prompt vuoto e chiama `rewindFiles()` una volta.

754 758

759<h3 id="file-rewinding-is-not-enabled-error">

760 Errore "File rewinding is not enabled"

761</h3>

762

763Questo errore si verifica quando tenti un rewind non interattivo senza checkpointing abilitato: eseguire il bare `claude -p` con `--rewind-files`, o eseguire una sessione SDK, inclusa una ripresa, le cui opzioni non abilitano il checkpointing. L'SDK imposta la variabile di ambiente `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING` internamente solo quando `enable_file_checkpointing` (Python) o `enableFileCheckpointing` (TypeScript) è abilitato sulla sessione che esegue il rewind; il bare CLI non la imposta mai.

764

765**Soluzione**: Per il bare CLI, imposta la variabile di ambiente quando esegui il comando:

766

767```bash theme={null}

768CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>

769```

770

771Per l'SDK, imposta `enable_file_checkpointing=True` (Python) o `enableFileCheckpointing: true` (TypeScript) sulla sessione ripresa, come fanno gli esempi su questa pagina.

772

755<h3 id="processtransport-is-not-ready-for-writing-error">773<h3 id="processtransport-is-not-ready-for-writing-error">

756 Errore "ProcessTransport is not ready for writing"774 Errore "ProcessTransport is not ready for writing"

757</h3>775</h3>

agent-sdk/permissions.md +13 −2

Details

28 </Step>28 </Step>

29 29

30 <Step title="Regole di richiesta">30 <Step title="Regole di richiesta">

31 Controlla le regole `ask` da [settings.json](/it/settings#permission-settings). Se una regola di richiesta corrisponde, la chiamata passa al tuo callback [`canUseTool`](/it/agent-sdk/user-input) per la conferma, anche in modalità `bypassPermissions`. In modalità `dontAsk` una regola di richiesta corrispondente viene negata invece, perché quella modalità non richiede mai conferma.31 Controlla le regole `ask` da [settings.json](/it/settings#permission-settings). Se una regola di richiesta corrisponde, la chiamata passa al tuo callback [`canUseTool`](/it/agent-sdk/user-input) per la conferma, anche in modalità `bypassPermissions`.

33 Gli strumenti che richiedono l'interazione dell'utente si comportano allo stesso modo: `AskUserQuestion` e gli strumenti MCP il cui server imposta [`_meta["anthropic/requiresUserInteraction"]`](/it/mcp#require-approval-for-a-specific-tool) passano sempre al callback, anche quando una regola di consentimento corrisponde. In modalità `dontAsk` entrambi i casi vengono negati invece, perché quella modalità non richiede mai conferma. {/* min-version: 2.1.199 */}L'annotazione MCP richiede Claude Code v2.1.199 o successivo.

32 </Step>34 </Step>

33 35

34 <Step title="Modalità di permesso">36 <Step title="Modalità di permesso">

46 48

47<img src="https://mintcdn.com/claude-code/jYgs7qigNjO1Badj/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=jYgs7qigNjO1Badj&q=85&s=c771ad9085b1277d3708027a49c744bc" alt="Diagramma del flusso di valutazione dei permessi in sei passaggi che corrisponde ai passaggi precedenti: una richiesta di strumento passa attraverso hook, regole di negazione, regole di richiesta, modalità di permesso, regole di consentimento e canUseTool. Hook, regole di negazione e canUseTool possono instradare verso Bloccato; bypass della modalità di permesso, regole di consentimento e canUseTool possono instradare verso Esegui; regole di richiesta instradano verso canUseTool." width="1180" height="260" data-path="images/agent-sdk/permissions-flow.svg" />49<img src="https://mintcdn.com/claude-code/jYgs7qigNjO1Badj/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=jYgs7qigNjO1Badj&q=85&s=c771ad9085b1277d3708027a49c744bc" alt="Diagramma del flusso di valutazione dei permessi in sei passaggi che corrisponde ai passaggi precedenti: una richiesta di strumento passa attraverso hook, regole di negazione, regole di richiesta, modalità di permesso, regole di consentimento e canUseTool. Hook, regole di negazione e canUseTool possono instradare verso Bloccato; bypass della modalità di permesso, regole di consentimento e canUseTool possono instradare verso Esegui; regole di richiesta instradano verso canUseTool." width="1180" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

48 50

51A partire da v2.1.198, se passi un callback `canUseTool` che questo ordine di valutazione non può mai raggiungere, l'SDK TypeScript emette un avviso del processo Node.js una volta quando la query viene costruita. Il codice dell'avviso è `CLAUDE_SDK_CAN_USE_TOOL_SHADOWED`. Due configurazioni lo attivano:

53* `permissionMode: 'bypassPermissions'`, che approva automaticamente ogni chiamata che raggiunge il passaggio della modalità di permesso

54* Ogni voce `allowedTools` semplice come `"Read"`, che approva automaticamente quello strumento intero prima che il callback sia consultato

56Le voci con uno specificatore come `Bash(ls *)` e la modalità `acceptEdits` non lo attivano, e le regole di consentimento provenienti da file di impostazioni non sono visibili al controllo.

58Ascolta con `process.on('warning', ...)` e abbina il codice per registrarlo o sopprimerlo. Per controllare ogni chiamata di strumento indipendentemente dalla modalità e dalle regole, utilizza invece un hook [`PreToolUse`](/it/agent-sdk/hooks).

49Questa pagina si concentra su **regole di consentimento e negazione** e **modalità di permesso**. Per gli altri passaggi:60Questa pagina si concentra su **regole di consentimento e negazione** e **modalità di permesso**. Per gli altri passaggi:

50 61

51* **Hooks:** esegui codice personalizzato per consentire, negare o modificare le richieste di strumenti. Vedi [Controllare l'esecuzione con gli hook](/it/agent-sdk/hooks).62* **Hooks:** esegui codice personalizzato per consentire, negare o modificare le richieste di strumenti. Vedi [Controllare l'esecuzione con gli hook](/it/agent-sdk/hooks).

67Le regole di consentimento accettano glob dei nomi degli strumenti solo dopo un prefisso letterale `mcp__<server>__`. Il segmento del server deve essere privo di glob in modo che la regola nomini un server specifico che hai configurato: `mcp__puppeteer__*` corrisponde a ogni strumento dal server `puppeteer` e `mcp__github__get_*` corrisponde ai suoi strumenti `get_`. Una voce non ancorata come `allowed_tools=["*"]` o `allowed_tools=["mcp__*"]` viene ignorata con un avviso di avvio e non approva automaticamente nulla.78Le regole di consentimento accettano glob dei nomi degli strumenti solo dopo un prefisso letterale `mcp__<server>__`. Il segmento del server deve essere privo di glob in modo che la regola nomini un server specifico che hai configurato: `mcp__puppeteer__*` corrisponde a ogni strumento dal server `puppeteer` e `mcp__github__get_*` corrisponde ai suoi strumenti `get_`. Una voce non ancorata come `allowed_tools=["*"]` o `allowed_tools=["mcp__*"]` viene ignorata con un avviso di avvio e non approva automaticamente nulla.

68 79

69<Warning>80<Warning>

70 **Gli strumenti approvati automaticamente non raggiungono mai `canUseTool`.** Una chiamata a uno strumento approvata in qualsiasi fase precedente, da `acceptEdits` o `bypassPermissions`, o da una regola di consentimento, salta il tuo callback `canUseTool`, quindi i controlli di permesso che inserisci lì vengono silenziosamente ignorati per quello strumento. La copertura dipende dalla forma della voce: un nome semplice come `Read` o `mcp__github__get_issue` approva automaticamente ogni chiamata a quello strumento, mentre una regola limitata come `Bash(ls *)` approva automaticamente solo le chiamate corrispondenti e altre chiamate `Bash` passano comunque al callback. Per i controlli che devono essere eseguiti su ogni chiamata a uno strumento, utilizza un hook [`PreToolUse`](/it/agent-sdk/hooks): gli hook vengono eseguiti prima di ogni altro passaggio e un hook di negazione si applica anche in modalità `bypassPermissions`.81 **Gli strumenti approvati automaticamente non raggiungono mai `canUseTool`.** Una chiamata a uno strumento approvata in qualsiasi fase precedente, da `acceptEdits` o `bypassPermissions`, o da una regola di consentimento, salta il tuo callback `canUseTool`, quindi i controlli di permesso che inserisci lì vengono silenziosamente ignorati per quello strumento. L'eccezione riguarda gli strumenti che richiedono l'interazione dell'utente, `AskUserQuestion` e gli strumenti MCP contrassegnati con [`_meta["anthropic/requiresUserInteraction"]`](/it/mcp#require-approval-for-a-specific-tool), che raggiungono il callback anche quando una regola di consentimento corrisponde. La copertura dipende dalla forma della voce: un nome semplice come `Read` o `mcp__github__get_issue` approva automaticamente ogni chiamata a quello strumento, mentre una regola limitata come `Bash(ls *)` approva automaticamente solo le chiamate corrispondenti e altre chiamate `Bash` passano comunque al callback. Per i controlli che devono essere eseguiti su ogni chiamata a uno strumento, utilizza un hook [`PreToolUse`](/it/agent-sdk/hooks): gli hook vengono eseguiti prima di ogni altro passaggio e un hook di negazione si applica anche in modalità `bypassPermissions`.

71</Warning>82</Warning>

72 83

73Per un agente bloccato, abbina `allowedTools` con `permissionMode: "dontAsk"`. Gli strumenti elencati vengono approvati; tutto il resto viene negato completamente invece di richiedere:84Per un agente bloccato, abbina `allowedTools` con `permissionMode: "dontAsk"`. Gli strumenti elencati vengono approvati; tutto il resto viene negato completamente invece di richiedere:

agent-sdk/python.md +1 −1

Details

958```958```

959 959

960* `API_TIMEOUT_MS`: timeout per richiesta sul client Anthropic, in millisecondi. Predefinito `600000`. Si applica al ciclo principale e a tutti i subagenti.960* `API_TIMEOUT_MS`: timeout per richiesta sul client Anthropic, in millisecondi. Predefinito `600000`. Si applica al ciclo principale e a tutti i subagenti.

961* `CLAUDE_CODE_MAX_RETRIES`: numero massimo di tentativi API. Predefinito `10`, limitato a `15`. Ogni tentativo ottiene la propria finestra `API_TIMEOUT_MS`, quindi il tempo di parete nel caso peggiore è approssimativamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` più backoff. Per esecuzioni incustodite che devono attendere interruzioni più lunghe, imposta `CLAUDE_CODE_RETRY_WATCHDOG=1` per ritentare gli errori di capacità indefinitamente.961* `CLAUDE_CODE_MAX_RETRIES`: numero massimo di tentativi API. Predefinito `10`, limitato a `15`. Ogni tentativo ottiene la propria finestra `API_TIMEOUT_MS`, quindi il tempo di parete nel caso peggiore è approssimativamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` più backoff. Per esecuzioni incustodite che devono attendere interruzioni più lunghe, imposta `CLAUDE_CODE_RETRY_WATCHDOG=1`: ritenta gli errori di capacità indefinitamente, e {/* min-version: 2.1.199 */}a partire da Claude Code v2.1.199 aumenta il valore predefinito per altri errori transitori a `300` e rimuove il limite su questa variabile.

962* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog di blocco per i subagenti lanciati con `run_in_background`. Predefinito `600000`. Si ripristina su ogni evento di flusso; in caso di blocco interrompe il subagente, contrassegna l'attività come non riuscita e presenta l'errore al genitore con qualsiasi risultato parziale. Non si applica ai subagenti sincroni.962* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog di blocco per i subagenti lanciati con `run_in_background`. Predefinito `600000`. Si ripristina su ogni evento di flusso; in caso di blocco interrompe il subagente, contrassegna l'attività come non riuscita e presenta l'errore al genitore con qualsiasi risultato parziale. Non si applica ai subagenti sincroni.

963* `CLAUDE_ENABLE_STREAM_WATCHDOG` con `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: interrompe la richiesta quando le intestazioni sono arrivate ma il corpo della risposta smette di trasmettere. Il watchdog è attivo per impostazione predefinita per tutti i provider; imposta `CLAUDE_ENABLE_STREAM_WATCHDOG=0` per disabilitarlo. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` predefinito a `300000` e viene bloccato a quel minimo. La richiesta interrotta passa attraverso il percorso di ripetizione normale.963* `CLAUDE_ENABLE_STREAM_WATCHDOG` con `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: interrompe la richiesta quando le intestazioni sono arrivate ma il corpo della risposta smette di trasmettere. Il watchdog è attivo per impostazione predefinita per tutti i provider; imposta `CLAUDE_ENABLE_STREAM_WATCHDOG=0` per disabilitarlo. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` predefinito a `300000` e viene bloccato a quel minimo. La richiesta interrotta passa attraverso il percorso di ripetizione normale.

964 964

agent-sdk/subagents.md +43 −27

Details

7> Definisci e richiama subagenti per isolare il contesto, eseguire attività in parallelo e applicare istruzioni specializzate nelle tue applicazioni Claude Agent SDK.7> Definisci e richiama subagenti per isolare il contesto, eseguire attività in parallelo e applicare istruzioni specializzate nelle tue applicazioni Claude Agent SDK.

8 8

9I subagenti sono istanze di agente separate che il tuo agente principale può generare per gestire sottoattività mirate.9I subagenti sono istanze di agente separate che il tuo agente principale può generare per gestire sottoattività mirate.

~~10Utilizza i subagenti per isolare il contesto per sottoattività mirate, eseguire più analisi in parallelo e applicare istruzioni specializzate senza appesantire il prompt dell'agente principale.~~10Utilizza i subagenti per isolare il contesto, eseguire più analisi in parallelo e applicare istruzioni specializzate senza appesantire il prompt dell'agente principale.

11 11

12Questa guida spiega come definire e utilizzare i subagenti nell'SDK utilizzando il parametro `agents`.12Questa guida spiega come definire e utilizzare i subagenti nell'SDK utilizzando il parametro `agents`.

13 13

17 17

18Puoi creare subagenti in tre modi:18Puoi creare subagenti in tre modi:

19 19

~~20* **A livello di programmazione**: utilizza il parametro `agents` nelle tue opzioni `query()` ([TypeScript](/it/agent-sdk/typescript#agentdefinition), [Python](/it/agent-sdk/python#agentdefinition))~~20* **A livello di programmazione**: utilizza il parametro `agents` nelle tue opzioni `query()`. Vedi i riferimenti [TypeScript](/it/agent-sdk/typescript#agentdefinition) e [Python](/it/agent-sdk/python#agentdefinition)

~~21* **Basato su file system**: definisci gli agenti come file markdown nelle directory `.claude/agents/` (vedi [definizione di subagenti come file](/it/sub-agents))~~21* **Basato su file system**: definisci gli agenti come file markdown nelle directory `.claude/agents/`. Vedi [definizione di subagenti come file](/it/sub-agents)

22* **Generale integrato**: Claude può richiamare il subagente `general-purpose` integrato in qualsiasi momento tramite lo strumento Agent senza che tu debba definire nulla22* **Generale integrato**: Claude può richiamare il subagente `general-purpose` integrato in qualsiasi momento tramite lo strumento Agent senza che tu debba definire nulla

23 23

24Questa guida si concentra sull'approccio programmatico, che è consigliato per le applicazioni SDK.24Questa guida si concentra sull'approccio programmatico, che è consigliato per le applicazioni SDK.

25 25

26Quando definisci i subagenti, Claude determina se richiamarli in base al campo `description` di ogni subagente. Scrivi descrizioni chiare che spieghino quando il subagente dovrebbe essere utilizzato, e Claude delegherà automaticamente i compiti appropriati. Puoi anche richiedere esplicitamente un subagente per nome nel tuo prompt (ad esempio, "Usa l'agente code-reviewer per...").26Quando definisci i subagenti, Claude determina se richiamarli in base al campo `description` di ogni subagente. Scrivi descrizioni chiare che spieghino quando il subagente dovrebbe essere utilizzato, e Claude delegherà automaticamente i compiti appropriati. Puoi anche richiedere esplicitamente un subagente per nome nel tuo prompt, ad esempio "Usa l'agente code-reviewer per...".

27 27

28<h2 id="benefits-of-using-subagents">28<h2 id="benefits-of-using-subagents">

29 Vantaggi dell'utilizzo dei subagenti29 Vantaggi dell'utilizzo dei subagenti

61 61

62**Esempio:** un subagente `doc-reviewer` potrebbe avere accesso solo agli strumenti Read e Grep, assicurando che possa analizzare ma non modifichi mai accidentalmente i tuoi file di documentazione.62**Esempio:** un subagente `doc-reviewer` potrebbe avere accesso solo agli strumenti Read e Grep, assicurando che possa analizzare ma non modifichi mai accidentalmente i tuoi file di documentazione.

63 63

~~64<h2 id="creating-subagents">~~64<h2 id="create-subagents">

65 Creazione di subagenti65 Creazione di subagenti

66</h2>66</h2>

67 67

69 Definizione programmatica (consigliata)69 Definizione programmatica (consigliata)

70</h3>70</h3>

71 71

72Definisci i subagenti direttamente nel tuo codice utilizzando il parametro `agents`. Questo esempio crea due subagenti: un revisore di codice con accesso in sola lettura e un esecutore di test che può eseguire comandi. Claude richiama i subagenti tramite lo strumento `Agent`, quindi includi `Agent` in `allowedTools` per approvare automaticamente le invocazioni dei subagenti senza una richiesta di autorizzazione.72Definisci i subagenti direttamente nel tuo codice utilizzando il parametro `agents`. Claude richiama i subagenti tramite lo strumento `Agent`, quindi includi `Agent` in `allowedTools` per approvare automaticamente le invocazioni dei subagenti senza una richiesta di autorizzazione.

73 73

74La maggior parte degli esempi in questa pagina stampa solo il risultato finale. Per confermare che Claude ha delegato a un subagente piuttosto che rispondere direttamente, vedi [Rilevamento dell'invocazione del subagente](#detecting-subagent-invocation).74La maggior parte degli esempi in questa pagina stampa solo il risultato finale. Per confermare che Claude ha delegato a un subagente piuttosto che rispondere direttamente, vedi [Rilevamento dell'invocazione del subagente](#detect-subagent-invocation).

76Questo esempio crea due subagenti: un revisore di codice con accesso in sola lettura e un esecutore di test che può eseguire comandi.

75 77

76<CodeGroup>78<CodeGroup>

77 ```python Python theme={null}79 ```python Python theme={null}

197 199

198Nell'SDK Python, i nomi di campo con più parole come `disallowedTools` e `mcpServers` mantengono la loro ortografia camelCase per corrispondere al formato wire piuttosto che seguire la convenzione snake\_case di Python. Vedi il riferimento [`AgentDefinition`](/it/agent-sdk/python#agentdefinition) per i dettagli.200Nell'SDK Python, i nomi di campo con più parole come `disallowedTools` e `mcpServers` mantengono la loro ortografia camelCase per corrispondere al formato wire piuttosto che seguire la convenzione snake\_case di Python. Vedi il riferimento [`AgentDefinition`](/it/agent-sdk/python#agentdefinition) per i dettagli.

199 201

202Due comportamenti dei subagenti sono cambiati in Claude Code v2.1.198:

203

204* I subagenti vengono eseguiti in background per impostazione predefinita. Una chiamata dello strumento Agent che omette l'input [`run_in_background`](/it/agent-sdk/typescript) avvia un subagente in background, e Claude imposta `run_in_background: false` quando ha bisogno del risultato prima di continuare. Prima della v2.1.198, omettere `run_in_background` eseguiva il subagente in modo sincrono. Imposta il campo `background` su `true` per forzare l'esecuzione in background per un agente specifico indipendentemente da ciò che Claude richiede.

205* Un subagente eredita la configurazione del pensiero esteso della sessione principale. Nelle versioni precedenti, il pensiero esteso è disabilitato all'interno dei subagenti indipendentemente dall'impostazione della sessione principale.

206

200<Note>207<Note>

201 {/* min-version: 2.1.172 */}A partire da Claude Code v2.1.172, i subagenti possono generare i propri subagenti. Un subagente cinque livelli al di sotto dell'agente principale non può generare ulteriori subagenti, indipendentemente dal fatto che venga eseguito in primo piano o in background. Per impedire a un subagente di generare altri, ometti `Agent` dal suo array `tools` o aggiungilo a `disallowedTools`. Vedi [subagenti annidati](/it/sub-agents#spawn-nested-subagents) per le regole di profondità complete.208 {/* min-version: 2.1.172 */}A partire da Claude Code v2.1.172, i subagenti possono generare i propri subagenti. Un subagente cinque livelli al di sotto dell'agente principale non può generare ulteriori subagenti, indipendentemente dal fatto che venga eseguito in primo piano o in background. Per impedire a un subagente di generare altri, ometti `Agent` dal suo array `tools` o aggiungilo a `disallowedTools`. Vedi [subagenti annidati](/it/sub-agents#spawn-nested-subagents) per le regole di profondità complete.

202</Note>209</Note>

215 Cosa ereditano i subagenti222 Cosa ereditano i subagenti

216</h2>223</h2>

217 224

218La finestra di contesto di un subagente inizia da zero (nessuna conversazione genitore) ma non è vuota. L'unico canale dal genitore al subagente è la stringa di prompt dello strumento Agent, quindi includi direttamente nel prompt qualsiasi percorso di file, messaggio di errore o decisione di cui il subagente ha bisogno.225La finestra di contesto di un subagente inizia da zero, senza conversazione genitore, ma non è vuota. L'unico canale dal genitore al subagente è la stringa di prompt dello strumento Agent, quindi includi direttamente nel prompt qualsiasi percorso di file, messaggio di errore o decisione di cui il subagente ha bisogno.

219 226

220| Il subagente riceve | Il subagente non riceve |227| Il subagente riceve | Il subagente non riceve |

221| :----------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- |228| :----------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- |

225 232

226<Note>233<Note>

227 Il genitore riceve il messaggio finale del subagente verbatim come risultato dello strumento Agent, ma potrebbe riassumerlo nella sua risposta. Per preservare l'output del subagente verbatim nella risposta rivolta all'utente, includi un'istruzione per farlo nel prompt o nell'opzione `systemPrompt` che passi alla chiamata **principale** `query()`.234 Il genitore riceve il messaggio finale del subagente verbatim come risultato dello strumento Agent, ma potrebbe riassumerlo nella sua risposta. Per preservare l'output del subagente verbatim nella risposta rivolta all'utente, includi un'istruzione per farlo nel prompt o nell'opzione `systemPrompt` che passi alla chiamata principale `query()`.

228</Note>235</Note>

229 236

230<h2 id="invoking-subagents">237{/* min-version: 2.1.199 */}A partire da Claude Code v2.1.199, un errore API che termina il subagente anticipatamente, come un limite di velocità, non viene mai consegnato come risultato. Se il subagente ha già prodotto output, lo strumento Agent restituisce quell'output parziale con una nota che il subagente non ha terminato; altrimenti il risultato dello strumento è un messaggio di errore, `Agent terminated early due to an API error`, seguito dal dettaglio dell'errore. Vedi [API errors in subagents](/it/sub-agents#api-errors-in-subagents) per il comportamento in primo piano e in background.

238

239<h2 id="invoke-subagents">

231 Richiamo dei subagenti240 Richiamo dei subagenti

232</h2>241</h2>

233 242

329 ```338 ```

330</CodeGroup>339</CodeGroup>

331 340

332<h2 id="detecting-subagent-invocation">341<h2 id="detect-subagent-invocation">

333 Rilevamento dell'invocazione del subagente342 Rilevamento dell'invocazione del subagente

334</h2>343</h2>

335 344

336I subagenti vengono richiamati tramite lo strumento Agent. Per rilevare quando un subagente viene richiamato, controlla i blocchi `tool_use` dove `name` è `"Agent"`. I messaggi provenienti dal contesto di un subagente includono un campo `parent_tool_use_id`.345Claude richiama i subagenti tramite lo strumento Agent. Per rilevare quando un subagente viene richiamato, controlla i blocchi `tool_use` dove `name` è `"Agent"`. I messaggi provenienti dal contesto di un subagente includono un campo `parent_tool_use_id`.

337 346

338<Note>347<Note>

339 Il nome dello strumento è stato rinominato da `"Task"` a `"Agent"` in Claude Code v2.1.63. Le versioni attuali dell'SDK emettono `"Agent"` nei blocchi `tool_use` ma utilizzano ancora `"Task"` nell'elenco degli strumenti `system:init` e in `result.permission_denials[].tool_name`. Controllare entrambi i valori in `block.name` garantisce la compatibilità tra le versioni dell'SDK.348 Il nome dello strumento è stato rinominato da `"Task"` a `"Agent"` in Claude Code v2.1.63. Le versioni attuali dell'SDK emettono `"Agent"` nei blocchi `tool_use` ma utilizzano ancora `"Task"` nell'elenco degli strumenti `system:init` e in `result.permission_denials[].tool_name`. Controllare entrambi i valori in `block.name` garantisce la compatibilità tra le versioni dell'SDK.

422 ```431 ```

423</CodeGroup>432</CodeGroup>

424 433

425<h2 id="resuming-subagents">434<h2 id="resume-subagents">

426 Ripresa dei subagenti435 Ripresa dei subagenti

427</h2>436</h2>

428 437

429I subagenti possono essere ripresi per continuare da dove si erano fermati. I subagenti ripresi mantengono la loro cronologia di conversazione completa, incluse tutte le chiamate agli strumenti precedenti, i risultati e il ragionamento. Il subagente riprende esattamente da dove si era fermato piuttosto che iniziare da zero.438È possibile riprendere un subagente per continuare da dove si era fermato piuttosto che iniziare da zero. Un subagente ripreso mantiene la sua cronologia di conversazione completa, incluse tutte le chiamate agli strumenti precedenti, i risultati e il ragionamento.

430 439

431Quando un subagente si completa, il risultato dello strumento Agent include un blocco di testo contenente `agentId: <id>`. Gli agenti integrati [`Explore` e `Plan`](/it/sub-agents#built-in-subagents) sono monouso e non restituiscono un `agentId`, quindi utilizzare un agente personalizzato o `general-purpose` quando è necessario riprendere. Per riprendere un subagente a livello di programmazione:440Quando un subagente si completa, il risultato dello strumento Agent include un blocco di testo contenente `agentId: <id>`. Gli agenti integrati [`Explore` e `Plan`](/it/sub-agents#built-in-subagents) sono monouso e non restituiscono un `agentId`, quindi utilizzare un agente personalizzato o `general-purpose` quando è necessario riprendere. Per riprendere un subagente a livello di programmazione:

432 441

4331. **Cattura l'ID della sessione**: Estrai `session_id` dai messaggi durante la prima query4421. **Cattura l'ID della sessione**: estrai `session_id` dai messaggi durante la prima query

4342. **Estrai l'ID dell'agente**: Analizza `agentId` dal testo del risultato dello strumento Agent4432. **Estrai l'ID dell'agente**: analizza `agentId` dal testo del risultato dello strumento Agent

4353. **Riprendi la sessione**: Passa `resume: sessionId` nelle opzioni della seconda query e includi l'ID dell'agente nel tuo prompt4443. **Riprendi la sessione**: passa `resume: sessionId` nelle opzioni della seconda query e includi l'ID dell'agente nel tuo prompt

436 445

437<Note>446<Note>

438 Devi riprendere la stessa sessione per accedere alla trascrizione del subagente. Ogni chiamata `query()` avvia una nuova sessione per impostazione predefinita, quindi passa `resume: sessionId` per continuare nella stessa sessione.447 Devi riprendere la stessa sessione per accedere alla trascrizione del subagente. Ogni chiamata `query()` avvia una nuova sessione per impostazione predefinita, quindi passa `resume: sessionId` per continuare nella stessa sessione.

566 575

567Le trascrizioni dei subagenti persistono indipendentemente dalla conversazione principale:576Le trascrizioni dei subagenti persistono indipendentemente dalla conversazione principale:

568 577

569* **Compattazione della conversazione principale**: Quando la conversazione principale si compatta, le trascrizioni dei subagenti non sono interessate. Sono archiviate in file separati.578* **Compattazione della conversazione principale**: quando la conversazione principale si compatta, le trascrizioni dei subagenti non sono interessate. Sono archiviate in file separati.

570* **Persistenza della sessione**: Le trascrizioni dei subagenti persistono all'interno della loro sessione. Puoi riprendere un subagente dopo il riavvio di Claude Code riprendendo la stessa sessione.579* **Persistenza della sessione**: le trascrizioni dei subagenti persistono all'interno della loro sessione. È possibile riprendere un subagente dopo il riavvio di Claude Code riprendendo la stessa sessione.

571* **Pulizia automatica**: Le trascrizioni vengono pulite in base all'impostazione `cleanupPeriodDays` (predefinito: 30 giorni).580* **Pulizia automatica**: le trascrizioni vengono pulite in base all'impostazione `cleanupPeriodDays`, che per impostazione predefinita è di 30 giorni.

572 581

573<h2 id="tool-restrictions-1">582<h2 id="tool-restrictions-1">

574 Restrizioni degli strumenti583 Restrizioni degli strumenti

662 671

663Se Claude completa i compiti direttamente invece di delegare al tuo subagente:672Se Claude completa i compiti direttamente invece di delegare al tuo subagente:

664 673

6651. **Verifica che le invocazioni di Agent siano approvate**: includi `Agent` in `allowedTools` per approvare automaticamente le chiamate ai subagenti. Senza di esso, le invocazioni di Agent passano al tuo callback `canUseTool` oppure, in modalità `dontAsk`, vengono negate674* **Verifica che le invocazioni di Agent siano approvate**: includi `Agent` in `allowedTools` per approvare automaticamente le chiamate ai subagenti. Senza di esso, le invocazioni di Agent passano al tuo callback `canUseTool` oppure, in modalità `dontAsk`, vengono negate

6662. **Usa prompt espliciti**: menziona il subagente per nome nel tuo prompt (ad esempio, "Usa l'agente code-reviewer per...")675* **Usa prompt espliciti**: menziona il subagente per nome nel tuo prompt, ad esempio "Usa l'agente code-reviewer per..."

6673. **Scrivi una descrizione chiara**: spiega esattamente quando il subagente dovrebbe essere utilizzato in modo che Claude possa abbinare i compiti in modo appropriato676* **Scrivi una descrizione chiara**: spiega esattamente quando utilizzare il subagente in modo che Claude possa abbinare i compiti in modo appropriato

668 677

669<h3 id="filesystem-based-agents-not-loading">678<h3 id="filesystem-based-agents-not-loading">

670 Agenti basati su file system non caricati679 Agenti basati su file system non caricati

671</h3>680</h3>

672 681

673Gli agenti definiti in `.claude/agents/` vengono caricati solo all'avvio. Se crei un nuovo file di agente mentre Claude Code è in esecuzione, riavvia la sessione per caricarlo.682Claude Code monitora `~/.claude/agents/` e `.claude/agents/` e rileva un file di agente nuovo o modificato entro pochi secondi, senza necessità di riavvio. Se una definizione non appare mai, esamina queste cause:

683

684* **Nuova directory `agents`**: il monitoraggio copre solo le directory che esistevano all'avvio della sessione, quindi il primo file in una nuova directory richiede un riavvio della sessione. Questa è la causa più comune.

685* **Frontmatter non valido o un `name` duplicato**: controlla il YAML del file e se un agente esistente utilizza già il `name`.

686* **`--disable-slash-commands`**: le sessioni avviate con questo flag non monitorano queste directory e richiedono sempre un riavvio per caricare i nuovi file.

687* **Un agente programmatico con lo stesso nome**: gli `agents` passati a `query()` sovrascrivono un agente del file system con lo stesso nome.

688

689Per il formato del file, vedi [come scrivere file di subagente](/it/sub-agents#write-subagent-files).

674 690

675<h3 id="windows-long-prompt-failures">691<h3 id="long-prompt-failures-on-windows">

676 Windows: errori di prompt lungo692 Errori di prompt lungo su Windows

677</h3>693</h3>

678 694

679Su Windows, i subagenti con prompt molto lunghi potrebbero non riuscire a causa dei limiti di lunghezza della riga di comando (8191 caratteri). Mantieni i prompt concisi o utilizza agenti basati su file system per istruzioni complesse.695Su Windows, i subagenti con prompt molto lunghi potrebbero non riuscire a causa del limite di lunghezza della riga di comando di 8191 caratteri. Mantieni i prompt concisi o utilizza agenti basati su file system per istruzioni complesse.

680 696

681<h2 id="related-documentation">697<h2 id="related-documentation">

682 Documentazione correlata698 Documentazione correlata

agent-sdk/todo-tracking.md +68 −6

Details

9Il tracciamento dei todo fornisce un modo strutturato per gestire le attività e visualizzare i progressi agli utenti. Claude Agent SDK include funzionalità todo integrate che aiutano a organizzare flussi di lavoro complessi e mantengono gli utenti informati sulla progressione delle attività.9Il tracciamento dei todo fornisce un modo strutturato per gestire le attività e visualizzare i progressi agli utenti. Claude Agent SDK include funzionalità todo integrate che aiutano a organizzare flussi di lavoro complessi e mantengono gli utenti informati sulla progressione delle attività.

10 10

11<Note>11<Note>

12 A partire da TypeScript Agent SDK 0.3.142 e Claude Code v2.1.142, le sessioni utilizzano i tool Task strutturati `TaskCreate`, `TaskUpdate`, `TaskGet` e `TaskList` al posto di `TodoWrite`. Vedere [Migrazione ai tool Task](#migrate-to-task-tools) per come monitorare i cambiamenti del codice. Gli esempi in questa pagina impostano `CLAUDE_CODE_ENABLE_TASKS=0` per continuare a mostrare `TodoWrite` per le sessioni che non hanno ancora eseguito la migrazione.12 A partire da TypeScript Agent SDK 0.3.142 e Claude Code v2.1.142, le sessioni utilizzano i tool Task strutturati `TaskCreate`, `TaskUpdate`, `TaskGet` e `TaskList` al posto di `TodoWrite`. L'SDK Python riceve questo cambiamento dalla CLI Claude Code che avvia, non dalla versione del pacchetto Python: il passaggio si applica una volta che quella CLI — la copia inclusa nel pacchetto pip, o una a cui punti con `cli_path` — è v2.1.142 o successiva. Vedere [Migrazione ai tool Task](#migrate-to-task-tools) per come monitorare i cambiamenti del codice. Gli esempi in questa pagina impostano `CLAUDE_CODE_ENABLE_TASKS=0` per continuare a mostrare `TodoWrite` per le sessioni che non hanno ancora eseguito la migrazione.

13</Note>13</Note>

14 14

15<h3 id="todo-lifecycle">15<h3 id="todo-lifecycle">

27 Quando vengono utilizzati i Todo27 Quando vengono utilizzati i Todo

28</h3>28</h3>

29 29

~~30L'SDK crea automaticamente todo per:~~30L'SDK crea todo per la maggior parte del lavoro multi-step, come:

31 31

32* **Attività complesse multi-step** che richiedono 3 o più azioni distinte32* **Attività complesse multi-step** che richiedono 3 o più azioni distinte

33* **Elenchi di attività forniti dall'utente** quando vengono menzionati più elementi33* **Elenchi di attività forniti dall'utente** quando vengono menzionati più elementi

34* **Operazioni non banali** che traggono beneficio dal tracciamento dei progressi34* **Operazioni non banali** che traggono beneficio dal tracciamento dei progressi

35* **Richieste esplicite** quando gli utenti chiedono l'organizzazione dei todo35* **Richieste esplicite** quando gli utenti chiedono l'organizzazione dei todo

36 36

37Potrebbe saltare i todo per richieste molto brevi o a singolo step.

37<h2 id="examples">39<h2 id="examples">

38 Esempi40 Esempi

39</h2>41</h2>

40 42

43Prima di eseguire questi esempi, installare Claude Agent SDK seguendo la [guida rapida](/it/agent-sdk/quickstart).

45Ogni esempio viene eseguito fino a quando l'agente non termina e produce il suo messaggio di risultato finale. Se una sessione raggiunge prima il limite di turni, quel messaggio di risultato ha il sottotipo `error_max_turns`. Controllare `subtype` per rilevare quella conclusione.

47Questi esempi utilizzano chiamate `query()` a singolo scatto. Dopo aver prodotto un risultato `error_max_turns`, `query()` genera un errore che include `Reached maximum number of turns`. Ogni esempio racchiude il suo ciclo in un blocco try per uscire correttamente quando ciò accade.

49Vedere [Gestire il risultato](/it/agent-sdk/agent-loop#handle-the-result) per i sottotipi di risultato.

41<h3 id="monitoring-todo-changes">51<h3 id="monitoring-todo-changes">

42 Monitoraggio dei cambiamenti dei Todo52 Monitoraggio dei cambiamenti dei Todo

43</h3>53</h3>

46 ```typescript TypeScript theme={null}56 ```typescript TypeScript theme={null}

47 import { query } from "@anthropic-ai/claude-agent-sdk";57 import { query } from "@anthropic-ai/claude-agent-sdk";

48 58

59 try {

49 for await (const message of query({60 for await (const message of query({

50 prompt: "Optimize my React app performance and track progress with todos",61 prompt: "Optimize my React app performance and track progress with todos",

51 // Re-enable TodoWrite, which this example monitors. Without it, the SDK uses62 // Re-enable TodoWrite, which this example monitors. Without it, the SDK uses

68 }79 }

69 }80 }

70 }81 }

82 } catch (error) {

83 // A single-shot query() throws after yielding an error result,

84 // such as when the maxTurns limit is hit.

85 console.log(`Session ended with an error: ${error}`);

86 }

71 ```87 ```

72 88

73 ```python Python theme={null}89 ```python Python theme={null}

90 import asyncio

74 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock92 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

75 93

95 async def main():

96 try:

76 async for message in query(97 async for message in query(

77 prompt="Optimize my React app performance and track progress with todos",98 prompt="Optimize my React app performance and track progress with todos",

78 # Re-enable TodoWrite, which this example monitors. Without it, the SDK uses99 # Re-enable TodoWrite, which this example monitors. Without it, the SDK uses

95 else "❌"116 else "❌"

96 )117 )

97 print(f"{i + 1}. {status} {todo['content']}")118 print(f"{i + 1}. {status} {todo['content']}")

119 except Exception as error:

120 # A single-shot query() raises after yielding an error result,

121 # such as when the max_turns limit is hit.

122 print(f"Session ended with an error: {error}")

123

124

125 asyncio.run(main())

98 ```126 ```

99</CodeGroup>127</CodeGroup>

100 128

128 }156 }

129 157

130 async trackQuery(prompt: string) {158 async trackQuery(prompt: string) {

159 try {

131 for await (const message of query({160 for await (const message of query({

132 prompt,161 prompt,

133 // Re-enable TodoWrite, which this tracker watches for.162 // Re-enable TodoWrite, which this tracker watches for.

142 }171 }

143 }172 }

144 }173 }

174 } catch (error) {

175 // A single-shot query() throws after yielding an error result,

176 // such as when the maxTurns limit is hit.

177 console.log(`Session ended with an error: ${error}`);

178 }

145 }179 }

146 }180 }

147 181

151 ```185 ```

152 186

153 ```python Python theme={null}187 ```python Python theme={null}

188 import asyncio

189

154 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock190 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

155 from typing import List, Dict191 from typing import List, Dict

156 192

186 print(f"{i + 1}. {icon} {text}")222 print(f"{i + 1}. {icon} {text}")

187 223

188 async def track_query(self, prompt: str):224 async def track_query(self, prompt: str):

225 try:

189 async for message in query(226 async for message in query(

190 prompt=prompt,227 prompt=prompt,

191 # Re-enable TodoWrite, which this tracker watches for.228 # Re-enable TodoWrite, which this tracker watches for.

196 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":233 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

197 self.todos = block.input["todos"]234 self.todos = block.input["todos"]

198 self.display_progress()235 self.display_progress()

236 except Exception as error:

237 # A single-shot query() raises after yielding an error result,

238 # such as when the max_turns limit is hit.

239 print(f"Session ended with an error: {error}")

199 240

200 241

201 # Usage242 # Usage

243 async def main():

202 tracker = TodoTracker()244 tracker = TodoTracker()

203 await tracker.track_query("Build a complete authentication system with todos")245 await tracker.track_query("Build a complete authentication system with todos")

246

247

248 asyncio.run(main())

204 ```249 ```

205</CodeGroup>250</CodeGroup>

206 251

217| Forma dell'elemento: `{ content, status, activeForm }` | Input `TaskCreate`: `{ subject, description, activeForm?, metadata? }`. Input `TaskUpdate`: `{ taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }`. `status` è `"pending"`, `"in_progress"` o `"completed"`; impostare `status: "deleted"` per eliminare |262| Forma dell'elemento: `{ content, status, activeForm }` | Input `TaskCreate`: `{ subject, description, activeForm?, metadata? }`. Input `TaskUpdate`: `{ taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }`. `status` è `"pending"`, `"in_progress"` o `"completed"`; impostare `status: "deleted"` per eliminare |

218| Renderizza `block.input.todos` direttamente | Accumula elementi tra le chiamate, o leggi uno snapshot da un risultato dello strumento `TaskList` |263| Renderizza `block.input.todos` direttamente | Accumula elementi tra le chiamate, o leggi uno snapshot da un risultato dello strumento `TaskList` |

219 264

220L'ID attività assegnato non è nell'input `TaskCreate`. Ritorna nel `tool_result` corrispondente come `{ task: { id, subject } }`, quindi acquisiscilo dal blocco del risultato per inserire la chiave nella mappa. L'esempio seguente mostra il cambio minimo al ciclo [Monitoraggio dei cambiamenti dei Todo](#monitoring-todo-changes). Per renderizzare un elenco completo, guarda un risultato dello strumento `TaskList` nel flusso o accumula i risultati `TaskCreate` e gli input `TaskUpdate` in una mappa.265L'ID attività assegnato non è nell'input `TaskCreate`. Ritorna nel `tool_result` corrispondente come `{ task: { id, subject } }`, quindi acquisiscilo dal blocco del risultato per inserire la chiave nella mappa. L'esempio seguente mostra il cambio minimo al ciclo [Monitoraggio dei cambiamenti dei Todo](#monitoring-todo-changes). Legge solo gli input `tool_use` e salta l'acquisizione degli ID dai blocchi `tool_result`. Per renderizzare un elenco completo, guarda un risultato dello strumento `TaskList` nel flusso o accumula i risultati `TaskCreate` e gli input `TaskUpdate` in una mappa.

221 266

222L'input `tool_use` trasmesso è la forma grezza che il modello ha emesso. Claude Code ripara alcuni nomi di chiave quasi corretti ma non del tutto prima dell'esecuzione, mappando `id` o `task_id` a `taskId` e `active_form` a `activeForm`, ma questa riparazione non si riflette nel flusso. Leggi i campi di input `TaskUpdate` in modo difensivo, come fanno gli esempi seguenti, piuttosto che assumere che il nome canonico sia sempre presente.267L'input `tool_use` trasmesso è la forma grezza che il modello ha emesso. Claude Code ripara alcuni nomi di chiave quasi corretti ma non del tutto prima dell'esecuzione, mappando `id` o `task_id` a `taskId` e `active_form` a `activeForm`, ma questa riparazione non si riflette nel flusso. Leggi i campi di input `TaskUpdate` in modo difensivo, come fanno gli esempi seguenti, piuttosto che assumere che il nome canonico sia sempre presente.

223 268

225 ```typescript TypeScript theme={null}270 ```typescript TypeScript theme={null}

226 import { query } from "@anthropic-ai/claude-agent-sdk";271 import { query } from "@anthropic-ai/claude-agent-sdk";

227 272

273 try {

228 for await (const message of query({274 for await (const message of query({

229 prompt: "Optimize my React app performance",275 prompt: "Optimize my React app performance and track progress with todos",

276 options: { maxTurns: 15 },

230 })) {277 })) {

231 if (message.type !== "assistant") continue;278 if (message.type !== "assistant") continue;

232 for (const block of message.message.content) {279 for (const block of message.message.content) {

246 }293 }

247 }294 }

248 }295 }

296 } catch (error) {

297 // A single-shot query() throws after yielding an error result.

298 console.log(`Session ended with an error: ${error}`);

299 }

249 ```300 ```

250 301

251 ```python Python theme={null}302 ```python Python theme={null}

252 from claude_agent_sdk import query, AssistantMessage, ToolUseBlock303 import asyncio

253 304

305 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

306

307 async def main():

308 try:

254 async for message in query(309 async for message in query(

255 prompt="Optimize my React app performance",310 prompt="Optimize my React app performance and track progress with todos",

311 options=ClaudeAgentOptions(max_turns=15),

256 ):312 ):

257 if not isinstance(message, AssistantMessage):313 if not isinstance(message, AssistantMessage):

258 continue314 continue

269 )325 )

270 if task_id:326 if task_id:

271 print(f" {task_id} -> {block.input['status']}")327 print(f" {task_id} -> {block.input['status']}")

328 except Exception as error:

329 # A single-shot query() raises after yielding an error result.

330 print(f"Session ended with an error: {error}")

331

332

333 asyncio.run(main())

272 ```334 ```

273</CodeGroup>335</CodeGroup>

274 336

agent-sdk/typescript.md +19 −7

Details

551```551```

552 552

553* `API_TIMEOUT_MS`: timeout per richiesta sul client Anthropic, in millisecondi. Predefinito `600000`. Si applica al loop principale e a tutti i subagenti.553* `API_TIMEOUT_MS`: timeout per richiesta sul client Anthropic, in millisecondi. Predefinito `600000`. Si applica al loop principale e a tutti i subagenti.

554* `CLAUDE_CODE_MAX_RETRIES`: numero massimo di tentativi API. Predefinito `10`, limitato a `15`. Ogni tentativo ottiene la propria finestra `API_TIMEOUT_MS`, quindi il tempo wall case peggiore è approssimativamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` più backoff. Per esecuzioni incustodite che devono attendere attraverso interruzioni più lunghe, imposta `CLAUDE_CODE_RETRY_WATCHDOG=1` per ritentare gli errori di capacità indefinitamente.554* `CLAUDE_CODE_MAX_RETRIES`: numero massimo di tentativi API. Predefinito `10`, limitato a `15`. Ogni tentativo ottiene la propria finestra `API_TIMEOUT_MS`, quindi il tempo wall case peggiore è approssimativamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` più backoff. Per esecuzioni incustodite che devono attendere attraverso interruzioni più lunghe, imposta `CLAUDE_CODE_RETRY_WATCHDOG=1`: ritenta gli errori di capacità indefinitamente, e {/* min-version: 2.1.199 */}a partire da Claude Code v2.1.199 aumenta il predefinito per altri errori transitori a `300` e rimuove il limite su questa variabile.

555* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog di blocco per i subagenti lanciati con `run_in_background`. Predefinito `600000`. Si ripristina su ogni evento di stream; al blocco interrompe il subagente, contrassegna l'attività come fallita e presenta l'errore al genitore con qualsiasi risultato parziale. Non si applica ai subagenti sincroni.555* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog di blocco per i subagenti lanciati con `run_in_background`. Predefinito `600000`. Si ripristina su ogni evento di stream; al blocco interrompe il subagente, contrassegna l'attività come fallita e presenta l'errore al genitore con qualsiasi risultato parziale. Non si applica ai subagenti sincroni.

556* `CLAUDE_ENABLE_STREAM_WATCHDOG` con `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: interrompe la richiesta quando le intestazioni sono arrivate ma il corpo della risposta smette di trasmettere. Il watchdog è attivo per impostazione predefinita per tutti i provider; imposta `CLAUDE_ENABLE_STREAM_WATCHDOG=0` per disabilitarlo. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` predefinito a `300000` ed è limitato a quel minimo. La richiesta interrotta passa attraverso il percorso di tentativo normale.556* `CLAUDE_ENABLE_STREAM_WATCHDOG` con `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: interrompe la richiesta quando le intestazioni sono arrivate ma il corpo della risposta smette di trasmettere. Il watchdog è attivo per impostazione predefinita per tutti i provider; imposta `CLAUDE_ENABLE_STREAM_WATCHDOG=0` per disabilitarlo. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` predefinito a `300000` ed è limitato a quel minimo. La richiesta interrotta passa attraverso il percorso di tentativo normale.

557 557

901 decisionReason?: string;901 decisionReason?: string;

902 toolUseID: string;902 toolUseID: string;

903 agentID?: string;903 agentID?: string;

904 requestId: string;

904 }905 }

905) => Promise<PermissionResult>;906) => Promise<PermissionResult | null>;

906```907```

907 908

917| `requestId` | `string` | L'`request_id` dell'envelope `control_request`. Una `control_response` che la tua applicazione invia al di fuori dell'SDK, come un POST HTTP firmato, deve ripetere questo valore in modo che il processo Claude Code possa abbinare la risposta alla richiesta |

918

919Il callback normalmente risolve la richiesta restituendo un [`PermissionResult`](#permissionresult), che l'SDK scrive di nuovo sul suo trasporto come `control_response`. Restituisci `null` solo quando la tua applicazione ha già inviato la `control_response` per questa richiesta sul suo canale, ripetendo `requestId`; l'SDK quindi salta la scrittura della risposta al suo trasporto. Restituire `null` in qualsiasi altro caso lascia la chiamata di tool bloccata indefinitamente, perché nessuna `control_response` viene mai inviata e i prompt di permesso non scadono.

920

921L'opzione `requestId` e il valore di ritorno `null` richiedono Claude Code v2.1.199 o successivo.

916 922

917<h3 id="permissionresult">923<h3 id="permissionresult">

918 `PermissionResult`924 `PermissionResult`

2179};2185};

2180```2186```

2181 2187

2182Interrompe un'attività di background o shell in esecuzione per ID.2188Interrompe un'attività di background o shell in esecuzione per ID. {/* min-version: 2.1.198 */}A partire da v2.1.198, `task_id` accetta anche un compagno di squadra agent-team o un agente di background denominato per ID agente o nome.

2183 2189

2184<h3 id="notebookedit">2190<h3 id="notebookedit">

2185 NotebookEdit2191 NotebookEdit

3788| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Configurazione del binario ripgrep personalizzato per gli ambienti sandbox |3794| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Configurazione del binario ripgrep personalizzato per gli ambienti sandbox |

3789 3795

3790<Note>3796<Note>

3791 La sandbox dipende dal supporto della piattaforma e, su Linux, da strumenti come `bubblewrap` e `socat`. Quando `enabled` è `true` e la sandbox non può avviarsi, `query()` segnala un messaggio `result` con `subtype: "error_during_execution"` e il motivo in `errors`, quindi si arresta. Guarda quel sottotipo piuttosto che aspettarti che `query()` generi un'eccezione prima di cedere i messaggi.3797 La sandbox dipende dal supporto della piattaforma e, su Linux, da strumenti come `bubblewrap` e `socat`. Quando `enabled` è `true` e la sandbox non può avviarsi, `query()` segnala un messaggio `result` con `subtype: "error_during_execution"` e il motivo in `errors`. Per una singola chiamata `query()`, l'SDK genera un'eccezione dopo aver ceduto quel risultato di errore, quindi racchiudi il ciclo in un blocco try per continuare oltre. Vedi [Gestire il risultato](/it/agent-sdk/agent-loop#handle-the-result) per il contratto di errore.

3792 3798

3793 Per eseguire senza sandbox, imposta `failIfUnavailable: false`.3799 Per eseguire senza sandbox, imposta `failIfUnavailable: false`.

3794</Note>3800</Note>

3800```typescript theme={null}3806```typescript theme={null}

3801import { query } from "@anthropic-ai/claude-agent-sdk";3807import { query } from "@anthropic-ai/claude-agent-sdk";

3802 3808

3803for await (const message of query({3809try {

3810 for await (const message of query({

3804 prompt: "Build and test my project",3811 prompt: "Build and test my project",

3805 options: {3812 options: {

3806 sandbox: {3813 sandbox: {

3811 }3818 }

3812 }3819 }

3813 }3820 }

3814})) {3821 })) {

3815 if ("result" in message) console.log(message.result);3822 if ("result" in message) console.log(message.result);

3823 }

3824} catch (error) {

3825 // A single-shot query() throws after yielding an error result,

3826 // such as when the sandbox can't start (failIfUnavailable defaults to true).

3827 console.log(`Session ended with an error: ${error}`);

3816}3828}

3817```3829```

3818 3830

3929<Warning>3941<Warning>

3930 I comandi in esecuzione con `dangerouslyDisableSandbox: true` hanno accesso completo al sistema. Assicurati che il tuo handler `canUseTool` convalidi queste richieste attentamente.3942 I comandi in esecuzione con `dangerouslyDisableSandbox: true` hanno accesso completo al sistema. Assicurati che il tuo handler `canUseTool` convalidi queste richieste attentamente.

3931 3943

3932 Se `permissionMode` è impostato su `bypassPermissions` e `allowUnsandboxedCommands` è abilitato, il modello può autonomamente eseguire comandi al di fuori della sandbox senza alcun prompt di approvazione. Questa combinazione consente effettivamente al modello di sfuggire all'isolamento della sandbox silenziosamente.3944 Se `permissionMode` è impostato su `bypassPermissions` e `allowUnsandboxedCommands` è abilitato, il modello può autonomamente eseguire comandi al di fuori della sandbox senza alcun prompt di approvazione (una [regola `ask`](/it/agent-sdk/permissions#how-permissions-are-evaluated) esplicita ne forza comunque una). Questa combinazione consente effettivamente al modello di sfuggire all'isolamento della sandbox silenziosamente.

3933</Warning>3945</Warning>

3934 3946

3935<h2 id="see-also">3947<h2 id="see-also">

agent-teams.md +12 −3

Details

89* **Invio**: aprire la trascrizione del compagno di team selezionato e messaggiargli direttamente89* **Invio**: aprire la trascrizione del compagno di team selezionato e messaggiargli direttamente

90* **Escape**: interrompere il turno corrente del compagno di team selezionato90* **Escape**: interrompere il turno corrente del compagno di team selezionato

91 91

92{/* min-version: 2.1.181 */}A partire dalla v2.1.181, la riga di un compagno di team inattivo si nasconde dopo 30 secondi e riappare al suo turno successivo. Il compagno di team rimane in esecuzione e indirizzabile mentre nascosto.92{/* min-version: 2.1.199 */}A partire dalla v2.1.199, la riga di un compagno di team inattivo rimane nel pannello mentre qualsiasi compagno di team o subagente è ancora al lavoro, quindi potete selezionarlo per rivedere la sua trascrizione o assegnargli più lavoro. Una volta che ogni agente nel pannello è inattivo, le righe inattive si nascondono dopo 30 secondi e riappaiono al turno successivo del compagno di team; il compagno di team rimane in esecuzione e indirizzabile mentre nascosto. Nella v2.1.181 fino alla v2.1.198, una riga inattiva si nascondeva 30 secondi dopo la fine del suo turno, anche mentre altri compagni di team erano ancora al lavoro; le righe inattive non sono nascoste nelle versioni precedenti alla v2.1.181.

94Quando più di tre compagni di team sono inattivi contemporaneamente, le righe oltre le prime tre si comprimono in una singola riga che conta i compagni di team compressi, come `2 idle agents` quando cinque sono inattivi. Selezionatela e premete Invio per espandere le righe compresse, oppure premete Esc per comprimerle di nuovo. I compagni di team al lavoro, i compagni di team non riusciti, e il compagno di team che state visualizzando mantengono sempre le loro righe proprie.

93 95

94Se desiderate che ogni compagno di team sia in un riquadro diviso proprio, consultate [Scegliere una modalità di visualizzazione](#choose-a-display-mode).96Se desiderate che ogni compagno di team sia in un riquadro diviso proprio, consultate [Scegliere una modalità di visualizzazione](#choose-a-display-mode).

95 97

174* **Modalità in-process**: utilizzate i tasti freccia su e giù nel pannello dell'agente per selezionare un compagno di team, quindi premete Invio per visualizzare la sua sessione e digitate per inviargli un messaggio. Premete `x` su un compagno di team selezionato per fermarlo. Premete Ctrl+T per attivare/disattivare l'elenco delle attività.176* **Modalità in-process**: utilizzate i tasti freccia su e giù nel pannello dell'agente per selezionare un compagno di team, quindi premete Invio per visualizzare la sua sessione e digitate per inviargli un messaggio. Premete `x` su un compagno di team selezionato per fermarlo. Premete Ctrl+T per attivare/disattivare l'elenco delle attività.

175* **Modalità split-pane**: fate clic nel riquadro di un compagno di team per interagire direttamente con la sua sessione. Ogni compagno di team ha una visualizzazione completa del proprio terminale.177* **Modalità split-pane**: fate clic nel riquadro di un compagno di team per interagire direttamente con la sua sessione. Ogni compagno di team ha una visualizzazione completa del proprio terminale.

176 178

179Mentre state visualizzando un compagno di team in-process, il testo semplice e le [skills](/it/skills) vanno a quel compagno di team, ma i comandi integrati vengono comunque eseguiti nella sessione del lead.

180

181Il modello e la modalità veloce di un compagno di team sono fissi quando viene generato, quindi `/model` e `/fast` cambiano solo le impostazioni del lead. {/* min-version: 2.1.199 */}A partire dalla versione 2.1.199, digitando uno di questi comandi mentre si visualizza un compagno di team viene mostrato un avviso che il cambiamento si applica al lead; le versioni precedenti lo applicavano al lead senza indicazione. `/effort` si applica comunque ai turni successivi del compagno di team visualizzato, perché i compagni di team seguono il [livello di sforzo](/it/model-config#adjust-effort-level) del lead.

182

177<h3 id="assign-and-claim-tasks">183<h3 id="assign-and-claim-tasks">

178 Assegnare e rivendicare attività184 Assegnare e rivendicare attività

179</h3>185</h3>

295**Come i compagni di team condividono le informazioni:**301**Come i compagni di team condividono le informazioni:**

296 302

297* **Consegna automatica dei messaggi**: quando i compagni di team inviano messaggi, vengono consegnati automaticamente ai destinatari. Il lead non ha bisogno di eseguire il polling per gli aggiornamenti.303* **Consegna automatica dei messaggi**: quando i compagni di team inviano messaggi, vengono consegnati automaticamente ai destinatari. Il lead non ha bisogno di eseguire il polling per gli aggiornamenti.

298* **Notifiche di inattività**: quando un compagno di team finisce e si ferma, notifica automaticamente il lead.304* **Notifiche di inattività**: quando un compagno di team finisce e si ferma, notifica automaticamente il lead. {/* min-version: 2.1.198 */}A partire dalla v2.1.198, un compagno di team la cui sessione termina a causa di un errore API notifica al lead che ha avuto un errore e include il testo dell'errore, invece di sembrare di terminare normalmente.

299* **Elenco di attività condiviso**: tutti gli agenti possono vedere lo stato delle attività e rivendicare il lavoro disponibile.305* **Elenco di attività condiviso**: tutti gli agenti possono vedere lo stato delle attività e rivendicare il lavoro disponibile.

300* **Messaggistica dei compagni di team**: invia un messaggio a un compagno di team specifico per nome. Per raggiungere tutti, inviate un messaggio per destinatario.306* **Messaggistica dei compagni di team**: invia un messaggio a un compagno di team specifico per nome. Per raggiungere tutti, inviate un messaggio per destinatario.

301 307

430Se i compagni di team non appaiono dopo aver chiesto a Claude di creare un team:436Se i compagni di team non appaiono dopo aver chiesto a Claude di creare un team:

431 437

432* In modalità in-process, i compagni di team appaiono nel pannello agente sotto l'input del prompt. Utilizzate i tasti freccia su e giù per selezionarne uno, quindi premete Invio per visualizzarlo.438* In modalità in-process, i compagni di team appaiono nel pannello agente sotto l'input del prompt. Utilizzate i tasti freccia su e giù per selezionarne uno, quindi premete Invio per visualizzarlo.

433* Una riga di compagno di team che è scomparsa dopo essere rimasta inattiva è stata nascosta, non interrotta. Le righe inattive si nascondono dopo 30 secondi e riappaiono al turno successivo del compagno di team. Inviate un messaggio al compagno di team per nome per riportarlo indietro.439* Una riga di compagno di team che è scomparsa dopo essere rimasta inattiva è stata nascosta, non interrotta. Le righe inattive si nascondono 30 secondi dopo che l'intero pannello diventa inattivo e riappaiono al turno successivo del compagno di team. Quando più di tre compagni di team sono inattivi, le loro righe in eccesso si comprimono in una singola riga `N idle agents` che Invio espande. Inviate un messaggio al compagno di team per nome per riportare una riga nascosta.

434* Controllate che il compito che avete dato a Claude fosse abbastanza complesso da giustificare un team. Claude decide se creare compagni di team in base al compito.440* Controllate che il compito che avete dato a Claude fosse abbastanza complesso da giustificare un team. Claude decide se creare compagni di team in base al compito.

435* Se avete esplicitamente richiesto split panes, assicuratevi che tmux sia installato e disponibile nel vostro PATH:441* Se avete esplicitamente richiesto split panes, assicuratevi che tmux sia installato e disponibile nel vostro PATH:

436 ```bash theme={null}442 ```bash theme={null}

453* Date loro istruzioni aggiuntive direttamente459* Date loro istruzioni aggiuntive direttamente

454* Generate un compagno di team sostitutivo per continuare il lavoro460* Generate un compagno di team sostitutivo per continuare il lavoro

455 461

462{/* min-version: 2.1.198 */}A partire dalla v2.1.198, un messaggio dal lead o da un altro compagno di team riattiva un compagno di team in-process che è in attesa di riprovare una richiesta API non riuscita, quindi riprova immediatamente invece di aspettare il ritardo di ripetizione completo.

463

456<h3 id="lead-shuts-down-before-work-is-done">464<h3 id="lead-shuts-down-before-work-is-done">

457 Il lead si spegne prima che il lavoro sia finito465 Il lead si spegne prima che il lavoro sia finito

458</h3>466</h3>

481* **L'arresto può essere lento**: i compagni di team finiscono la loro richiesta attuale o la chiamata dello strumento prima di spegnersi, il che può richiedere tempo.489* **L'arresto può essere lento**: i compagni di team finiscono la loro richiesta attuale o la chiamata dello strumento prima di spegnersi, il che può richiedere tempo.

482* **Un team per sessione**: una sessione ha esattamente un team, limitato a quella sessione. Non potete creare team denominati aggiuntivi o condividere un team tra sessioni.490* **Un team per sessione**: una sessione ha esattamente un team, limitato a quella sessione. Non potete creare team denominati aggiuntivi o condividere un team tra sessioni.

483* **Nessun team annidato**: i compagni di team non possono generare i loro propri compagni di team. Solo il lead può gestire il team.491* **Nessun team annidato**: i compagni di team non possono generare i loro propri compagni di team. Solo il lead può gestire il team.

492* **Nessun subagent in background da compagni di team in-process**: i propri subagent di un compagno di team in-process vengono eseguiti in primo piano. Chiedere uno in background, sia con `run_in_background` che con una definizione di subagent che imposta `background: true`, restituisce un errore, perché il lavoro in background di un compagno di team non può sopravvivere al processo del lead. I subagent lanciati dalla conversazione principale seguono il [default in background](/it/sub-agents#run-subagents-in-foreground-or-background).

484* **Il lead è fisso**: la sessione principale è il lead per tutta la sua durata. Non potete promuovere un compagno di team a lead o trasferire la leadership.493* **Il lead è fisso**: la sessione principale è il lead per tutta la sua durata. Non potete promuovere un compagno di team a lead o trasferire la leadership.

485* **Permessi impostati al momento della generazione**: tutti i compagni di team iniziano con la modalità di permesso del lead. Potete cambiare le modalità dei singoli compagni di team dopo la generazione, ma non potete impostare modalità per compagno di team al momento della generazione.494* **Permessi impostati al momento della generazione**: tutti i compagni di team iniziano con la modalità di permesso del lead. Potete cambiare le modalità dei singoli compagni di team dopo la generazione, ma non potete impostare modalità per compagno di team al momento della generazione.

486* **Split panes richiedono tmux o iTerm2**: la modalità in-process predefinita funziona in qualsiasi terminale. La modalità split-pane non è supportata nel terminale integrato di VS Code, Windows Terminal o Ghostty.495* **Split panes richiedono tmux o iTerm2**: la modalità in-process predefinita funziona in qualsiasi terminale. La modalità split-pane non è supportata nel terminale integrato di VS Code, Windows Terminal o Ghostty.

agent-view.md +63 −12

Details

27* [Avvio rapido](#quick-start): dai a Claude un compito su cui lavorare in background, controlla come sta andando e intervieni quando necessario27* [Avvio rapido](#quick-start): dai a Claude un compito su cui lavorare in background, controlla come sta andando e intervieni quando necessario

28* [Monitorare le sessioni con agent view](#monitor-sessions-with-agent-view), inclusi icone di stato, peek e reply, collegamento, organizzazione e scorciatoie da tastiera28* [Monitorare le sessioni con agent view](#monitor-sessions-with-agent-view), inclusi icone di stato, peek e reply, collegamento, organizzazione e scorciatoie da tastiera

29* [Invia nuovi agenti](#dispatch-new-agents) da agent view, da dentro una sessione, o dalla tua shell29* [Invia nuovi agenti](#dispatch-new-agents) da agent view, da dentro una sessione, o dalla tua shell

~~30* [Gestire le sessioni dalla shell](#manage-sessions-from-the-shell)~~30* [Gestire le sessioni dalla shell](#manage-sessions-from-the-shell) con `claude agents`, `claude attach` e comandi correlati

31* [Come sono ospitate le sessioni in background](#how-background-sessions-are-hosted) dal processo supervisor31* [Come sono ospitate le sessioni in background](#how-background-sessions-are-hosted) dal processo supervisor

32 32

33<h2 id="quick-start">33<h2 id="quick-start">

76 76

77Esegui `claude agents` per aprire agent view. Prende il controllo del terminale completo ed elenca ogni sessione raggruppata per stato, con sessioni fissate e quelle che hanno bisogno di te in cima. Ogni riga mostra il nome della sessione, l'attività corrente e quanto tempo fa è cambiata l'ultima volta.77Esegui `claude agents` per aprire agent view. Prende il controllo del terminale completo ed elenca ogni sessione raggruppata per stato, con sessioni fissate e quelle che hanno bisogno di te in cima. Ogni riga mostra il nome della sessione, l'attività corrente e quanto tempo fa è cambiata l'ultima volta.

78 78

79Il nome è tinto con il colore impostato da [`/color`](/it/commands) in quella sessione. A partire da v2.1.199 il colore si trasporta quando [metti in background una sessione](#from-inside-a-session) con `←` o `/background`.

79Per impostazione predefinita, l'elenco mostra ogni sessione in background che hai avviato, in tutti i tuoi progetti. Una sessione che lavora in un repository e un'altra in un worktree diverso appaiono entrambe qui, indipendentemente da quale directory hai aperto agent view. Per limitare l'elenco a un progetto, passa `--cwd`:81Per impostazione predefinita, l'elenco mostra ogni sessione in background che hai avviato, in tutti i tuoi progetti. Una sessione che lavora in un repository e un'altra in un worktree diverso appaiono entrambe qui, indipendentemente da quale directory hai aperto agent view. Per limitare l'elenco a un progetto, passa `--cwd`:

80 82

81```bash theme={null}83```bash theme={null}

91 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m93 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m

92 94

93Ready for review95Ready for review

~~94 ∙ jump physics Opened PR with collision fix PR #2048 2h~~96 ∙ jump physics Opened PR with collision fix #2048 2h

95 97

96Needs input98Needs input

97 ✻ power-up design needs input: double jump or wall climb? 1m99 ✻ power-up design needs input: double jump or wall climb? 1m

129| `∙` | Il processo è uscito. Puoi ancora fare peek, rispondere o collegarti, e Claude riavvia da dove l'ha lasciato |131| `∙` | Il processo è uscito. Puoi ancora fare peek, rispondere o collegarti, e Claude riavvia da dove l'ha lasciato |

130| `✢` | Una sessione [`/loop`](/it/scheduled-tasks) che dorme tra le iterazioni. La riga mostra il conteggio delle esecuzioni e un conto alla rovescia |132| `✢` | Una sessione [`/loop`](/it/scheduled-tasks) che dorme tra le iterazioni. La riga mostra il conteggio delle esecuzioni e un conto alla rovescia |

131 133

132L'etichetta `PR #N` che può apparire al bordo destro di una riga è la [pull request che la sessione ha aperto](#pull-request-status), non parte dell'icona di stato. Quando una sessione ha aperto più di una pull request, l'etichetta mostra un conteggio invece, come `3 PRs`.134L'etichetta `#N` che può apparire al bordo destro di una riga è la [pull request che la sessione ha aperto](#pull-request-status), non parte dell'icona di stato.

133 135

134Il titolo della scheda del terminale mostra il conteggio awaiting-input mentre agent view è aperto: `2 awaiting input · claude agents` quando le sessioni hanno bisogno di input, o `claude agents` quando nessuna lo fa.136Il titolo della scheda del terminale mostra il conteggio awaiting-input mentre agent view è aperto: `2 awaiting input · claude agents` quando le sessioni hanno bisogno di input, o `claude agents` quando nessuna lo fa.

135 137

138A partire da v2.1.198, mentre agent view è aperto, Claude Code invia anche una notifica attraverso il tuo [canale di notifica del terminale](/it/terminal-config#get-a-terminal-bell-or-notification) configurato quando una sessione in background locale inizia ad aver bisogno del tuo input, finisce, o fallisce. Le sessioni che vengono eseguite secondo una pianificazione, come le sessioni [`/loop`](/it/scheduled-tasks), notificano solo quando hanno bisogno del tuo input. Le notifiche utilizzano la stessa impostazione [`preferredNotifChannel`](/it/settings#available-settings) del resto di Claude Code e attivano l'hook [`Notification`](/it/hooks#notification) con il tipo `agent_needs_input` o `agent_completed`.

139

136Le sessioni in background non hanno bisogno di alcun terminale aperto per continuare a lavorare. Un [processo supervisor](#the-supervisor-process) separato le esegue, quindi puoi chiudere agent view, chiudere la tua shell, o avviare una nuova sessione interattiva e il tuo lavoro inviato continua.140Le sessioni in background non hanno bisogno di alcun terminale aperto per continuare a lavorare. Un [processo supervisor](#the-supervisor-process) separato le esegue, quindi puoi chiudere agent view, chiudere la tua shell, o avviare una nuova sessione interattiva e il tuo lavoro inviato continua.

137 141

138Lo stato della sessione persiste su disco attraverso gli auto-update e i riavvii del supervisor. Le sessioni sono anche preservate quando la tua macchina dorme. I loro processi riprendono al risveglio e il supervisor si ricollega a loro invece di trattare il gap di tempo come inattività. Lo spegnimento ferma comunque le sessioni in esecuzione; vedi [Le sessioni mostrano come non riuscite dopo lo spegnimento](#sessions-show-as-failed-after-shutdown) per come recuperarle.142Lo stato della sessione persiste su disco attraverso gli auto-update e i riavvii del supervisor. Le sessioni sono anche preservate quando la tua macchina dorme. I loro processi riprendono al risveglio e il supervisor si ricollega a loro invece di trattare il gap di tempo come inattività. Lo spegnimento ferma comunque le sessioni in esecuzione; vedi [Le sessioni mostrano come non riuscite dopo lo spegnimento](#sessions-show-as-failed-after-shutdown) per come recuperarle.

151 Stato della pull request155 Stato della pull request

152</h3>156</h3>

153 157

154Quando una sessione apre una pull request, un'etichetta `PR #1234` appare al bordo destro della riga, collegata alla pull request nei terminali che supportano i hyperlink. L'etichetta persiste quando invii un follow-up alla sessione, quindi la pull request rimane visibile mentre la riga ritorna al progresso live.158Quando una sessione apre una pull request, un'etichetta `#1234` appare al bordo destro della riga, collegata alla pull request nei terminali che supportano i hyperlink. L'etichetta persiste quando invii un follow-up alla sessione, quindi la pull request rimane visibile mentre la riga ritorna al progresso live. Le sessioni in background che hanno isolato i loro cambiamenti in un worktree aprono queste pull request da sole; [Come i file edits sono isolati](#how-file-edits-are-isolated) copre quando accade e cosa una sessione non fa mai senza chiedere.

155 159

156Quando una sessione ha aperto più di una pull request, l'etichetta mostra un conteggio invece, come `3 PRs`, colorato dalla pull request aperta che ha più bisogno di attenzione. Apri il [pannello peek](#peek-and-reply) per vederle tutte.160Quando una sessione ha aperto più di una pull request, l'etichetta mostra un conteggio invece, come `3 PRs`, colorato dalla pull request aperta che ha più bisogno di attenzione. Apri il [pannello peek](#peek-and-reply) per vederle tutte.

157 161

190 194

191Le sessioni collegate si rendono sempre in [modalità fullscreen](/it/fullscreen), indipendentemente dalla tua impostazione `tui`, perché una sessione in background non ha scrollback del terminale a cui aggiungere. Scorri con `PgUp`, `PgDn`, o la rotella del mouse, e premi `Ctrl+O` per la modalità transcript. Lo scroll nativo del tuo terminale e la modalità copia di tmux mostrano solo il viewport corrente, lo stesso di quando esegui qualsiasi applicazione fullscreen.195Le sessioni collegate si rendono sempre in [modalità fullscreen](/it/fullscreen), indipendentemente dalla tua impostazione `tui`, perché una sessione in background non ha scrollback del terminale a cui aggiungere. Scorri con `PgUp`, `PgDn`, o la rotella del mouse, e premi `Ctrl+O` per la modalità transcript. Lo scroll nativo del tuo terminale e la modalità copia di tmux mostrano solo il viewport corrente, lo stesso di quando esegui qualsiasi applicazione fullscreen.

192 196

193Premi `←` su un prompt vuoto per scollegar e tornare a agent view. Se una finestra di dialogo ha il focus e non risponde a `←`, premi `Ctrl+Z` per scollegar immediatamente.197Premi `←` su un prompt vuoto, o esegui `/exit`, per scollegar e tornare a agent view. A partire da v2.1.198 questo funziona allo stesso modo sia che tu abbia aperto la sessione da agent view o con `claude attach <id>` dalla tua shell.

198

199`Ctrl+Z` scollega anche ma torna a dove hai iniziato invece: agent view se ti sei collegato da lì, o la tua shell se hai eseguito `claude attach`. Usa `Ctrl+Z` quando una finestra di dialogo ha il focus e non risponde a `←`.

194 200

195`Ctrl+C` mantiene il suo comportamento di interruzione standard mentre collegato: annulla una risposta in esecuzione o un comando shell `!` piuttosto che scollegar. Premere `Ctrl+C` due volte su un prompt vuoto scollega, come in qualsiasi sessione.201`Ctrl+C` mantiene il suo comportamento di interruzione standard mentre collegato: annulla una risposta in esecuzione o un comando shell `!` piuttosto che scollegar. Premere `Ctrl+C` due volte su un prompt vuoto scollega, come in qualsiasi sessione.

196 202

291 297

292Un piccolo insieme di comandi viene eseguito in agent view stesso invece di essere inviato: `/exit` e `/quit` chiudono agent view, `/logout` ti disconnette, e `/model` imposta il [modello di dispatch](#set-the-model). Skills, i tuoi comandi personali, e built-in che espandono il prompt come `/init` vengono inviati a una nuova sessione in background come loro primo prompt. Gli altri comandi built-in mostrano un suggerimento `attach to a session to run it` invece.298Un piccolo insieme di comandi viene eseguito in agent view stesso invece di essere inviato:

299

300* `/exit` e `/quit` chiudono agent view

301* `/logout` ti disconnette

302* `/model` imposta il [modello di dispatch](#set-the-model)

303* {/* min-version: 2.1.198 */}A partire da v2.1.198, `/login` apre la finestra di dialogo di accesso in modo che tu possa accedere di nuovo senza collegarti a una sessione

304

305Skills, i tuoi comandi personali, e built-in che espandono il prompt come `/init` vengono inviati a una nuova sessione in background come loro primo prompt. Gli altri comandi built-in mostrano un suggerimento `attach to a session to run it` invece.

293 306

294Confezionare un compito ricorrente come una [skill](/it/skills) ti permette di avviare lo stesso workflow da agent view ripetutamente senza riscrivere il prompt.307Confezionare un compito ricorrente come una [skill](/it/skills) ti permette di avviare lo stesso workflow da agent view ripetutamente senza riscrivere il prompt.

295 308

313 326

314Esegui `/background` o il suo alias `/bg` per spostare la conversazione corrente in una sessione in background. Passa un prompt come `/bg run the test suite and fix any failures` per inviare un'istruzione in più prima. Se Claude sta rispondendo quando esegui `/bg`, la risposta continua nella sessione in background.327Esegui `/background` o il suo alias `/bg` per spostare la conversazione corrente in una sessione in background. Passa un prompt come `/bg run the test suite and fix any failures` per inviare un'istruzione in più prima. Se Claude sta rispondendo quando esegui `/bg`, la risposta continua nella sessione in background.

315 328

316Lo spostamento in background da una sessione interattiva avvia un nuovo processo che riprende dalla conversazione salvata, e il lavoro in corso si trasferisce ad esso: comandi shell in background in esecuzione, subagents in background, workflow dinamici, e compiti programmati che hai creato con [`/loop`](/it/scheduled-tasks) si trasferiscono alla sessione in background e continuano a girare lì. Un subagent si sposta insieme a tutto ciò che ha avviato, quindi si trasferisce solo quando tutto quel lavoro può trasferirsi anche, incluso su Windows. Per fermare il lavoro in corso invece di trasferirlo, imposta la variabile di ambiente [`CLAUDE_DISABLE_ADOPT=1`](/it/env-vars#variables); Claude Code ti chiede di confermare prima di metterla in background.329L'uscita da una sessione interattiva che ha ancora lavoro in background in esecuzione, come subagent, comandi shell in background, workflow, o [monitor](/it/tools-reference#monitor-tool), mostra una finestra di dialogo `Background work is running` invece di uscire immediatamente. {/* min-version: 2.1.198 */}A partire da v2.1.198 la finestra di dialogo offre `Move to background and exit` insieme a `Exit anyway` e `Stay`. Sceglierla sposta la sessione in background nello stesso modo in cui `/background` fa, quindi ti restituisce alla tua shell, in modo che il lavoro che può continuare rimane in esecuzione e la sessione appare in agent view. L'opzione non viene mostrata quando agent view è [disattivato](#turn-off-agent-view).

330

331Lo spostamento in background da una sessione interattiva avvia un nuovo processo che riprende dalla conversazione salvata, e il lavoro in corso si trasferisce ad esso: comandi shell in background in esecuzione, subagent in background, workflow dinamici, e compiti programmati che hai creato con [`/loop`](/it/scheduled-tasks) si trasferiscono alla sessione in background e continuano a girare lì. Un subagent si sposta insieme a tutto ciò che ha avviato, quindi si trasferisce solo quando tutto quel lavoro può trasferirsi anche, incluso su Windows. Per fermare il lavoro in corso invece di trasferirlo, imposta la variabile di ambiente [`CLAUDE_DISABLE_ADOPT=1`](/it/env-vars#variables); Claude Code ti chiede di confermare prima di metterla in background.

317 332

318Il lavoro che non può trasferirsi, come un [monitor](/it/tools-reference#monitor-tool) in esecuzione, viene fermato. Un subagent messo in background che possiede un monitor viene fermato insieme ad esso. Quando uno qualsiasi di essi è in esecuzione, Claude Code mostra una finestra di dialogo `Background this session?` in modo che tu possa confermare prima che sia fermato.333Il lavoro che non può trasferirsi, come un [monitor](/it/tools-reference#monitor-tool) in esecuzione, viene fermato. Un subagent messo in background che possiede un monitor viene fermato insieme ad esso. Quando uno qualsiasi di essi è in esecuzione, Claude Code mostra una finestra di dialogo `Background this session?` in modo che tu possa confermare prima che sia fermato.

319 334

320Una volta in background, la sessione può avviare nuovi subagents, monitor, e comandi in background, e questi continuano a essere eseguiti durante successivi distacchi e ricollegamenti.335Una volta in background, la sessione può avviare nuovi subagent, monitor, e comandi in background, e questi continuano a essere eseguiti durante successivi distacchi e ricollegamenti.

321 336

322I flag di configurazione dal lancio originale si trasferiscono alla sessione messa in background, quindi i suoi server MCP, le impostazioni e il modello di fallback rimangono in vigore:337I flag di configurazione dal lancio originale si trasferiscono alla sessione messa in background, quindi i suoi server MCP, le impostazioni e il modello di fallback rimangono in vigore:

323 338

342claude --bg "investigate the flaky SettingsChangeDetector test"357claude --bg "investigate the flaky SettingsChangeDetector test"

343```358```

344 359

360Il prompt è l'argomento posizionale, non un valore `-p`. {/* min-version: 2.1.198 */}A partire da v2.1.198, combinare `--bg` con `-p` o `--print` viene rifiutato con un errore prima che qualsiasi sessione sia creata, perché `--print` non avvia mai la sessione interattiva a cui `claude agents` si collega.

361

345Per eseguire un subagent specifico come agente principale della sessione, combina `--bg` con `--agent`:362Per eseguire un subagent specifico come agente principale della sessione, combina `--bg` con `--agent`:

346 363

347```bash theme={null}364```bash theme={null}

354claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"371claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"

355```372```

356 373

357Dopo aver messo in background, Claude stampa l'ID breve della sessione e i comandi per gestirla. Quando passi `--name`, il nome appare dopo l'ID breve:374Dopo aver messo in background, Claude stampa l'ID breve della sessione e i comandi per gestirla. Quando il servizio che ospita le sessioni in background non è già in esecuzione, `--bg` potrebbe prima stampare `Starting background service…` sopra questo output. Quando passi `--name`, il nome appare dopo l'ID breve:

358 375

359```text theme={null}376```text theme={null}

360backgrounded · 7c5dcf5d · flaky-test-fix377backgrounded · 7c5dcf5d · flaky-test-fix

414 431

415Un [subagent](/it/sub-agents) che la sessione in background genera eredita la directory di lavoro della sessione, quindi le sue modifiche ai file finiscono nel worktree della sessione piuttosto che nella tua copia di lavoro. Per dare a un subagent il suo proprio worktree separato, imposta [`isolation: worktree`](/it/sub-agents#supported-frontmatter-fields) nel suo frontmatter o passa `isolation: "worktree"` quando lo generi.432Un [subagent](/it/sub-agents) che la sessione in background genera eredita la directory di lavoro della sessione, quindi le sue modifiche ai file finiscono nel worktree della sessione piuttosto che nella tua copia di lavoro. Per dare a un subagent il suo proprio worktree separato, imposta [`isolation: worktree`](/it/sub-agents#supported-frontmatter-fields) nel suo frontmatter o passa `isolation: "worktree"` quando lo generi.

416 433

434A partire da v2.1.198, una sessione in background che ha isolato i suoi cambiamenti di codice in un worktree esegue anche il commit, spinge il suo ramo, e apre una bozza di pull request senza fermarsi a chiedere. L'etichetta [`#N`](#pull-request-status) appare sulla sua riga quando il pull request si apre. Non spinge mai a `main` o `master`, non fa mai force-push o merge, e salta il pull request quando gli hai detto di non aprirne uno o il repository non ha un remote.

435

436Una sessione che modifica un checkout che non ha isolato da sola chiede comunque prima di fare il commit o di cambiare rami. Questo si applica quando l'isolamento è impostato su `"none"`, quando lo spostamento del worktree è fallito, o quando la sessione è stata avviata all'interno di un worktree che già esisteva.

437

417<h3 id="set-the-model">438<h3 id="set-the-model">

418 Imposta il modello439 Imposta il modello

419</h3>440</h3>

529 550

530Una volta che una sessione finisce e rimane scollega per circa un'ora, il supervisor ferma il suo processo per liberare risorse. Una sessione che hai [fissato](#organize-the-list) con `Ctrl+T` è esente e mantiene il suo processo in esecuzione mentre inattivo. Il transcript e lo stato rimangono su disco comunque, e la prossima volta che ti colleghi, fai peek, o rispondi a una sessione fermata, il supervisor avvia un processo fresco da dove l'ha lasciato. Quando ogni sessione è finita e nessun terminale è collegato, il supervisor stesso esce e si avvia di nuovo la prossima volta che ne hai bisogno.551Una volta che una sessione finisce e rimane scollega per circa un'ora, il supervisor ferma il suo processo per liberare risorse. Una sessione che hai [fissato](#organize-the-list) con `Ctrl+T` è esente e mantiene il suo processo in esecuzione mentre inattivo. Il transcript e lo stato rimangono su disco comunque, e la prossima volta che ti colleghi, fai peek, o rispondi a una sessione fermata, il supervisor avvia un processo fresco da dove l'ha lasciato. Quando ogni sessione è finita e nessun terminale è collegato, il supervisor stesso esce e si avvia di nuovo la prossima volta che ne hai bisogno.

531 552

532I comandi shell in background e i workflow dinamici che la sessione ha avviato continuano a girare quando il suo processo è fermato, riavviato, o aggiornato, incluso su Windows. Il prossimo processo avviato per quella sessione li riprende, un comando shell che è finito nel frattempo viene segnalato come completato con il suo output, e un workflow riprende da dove l'ha lasciato. I comandi shell avviati da un subagent e i [monitor](/it/tools-reference#monitor-tool) in esecuzione si fermano comunque con il processo, e eliminare la sessione ferma tutto ciò che ha consegnato. Per fermare i comandi shell in background e i workflow con il processo anche, imposta la variabile di ambiente [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/it/env-vars#variables) su `1`.553Il lavoro in background che la sessione stessa ha avviato al livello superiore viene consegnato quando il suo processo viene fermato, riavviato, o aggiornato, incluso su Windows. Il prossimo processo avviato per quella sessione lo riprende:

554

555* Un comando shell in background che è finito nel frattempo viene segnalato come completato con il suo output

556* Un workflow dinamico riprende da dove l'ha lasciato

557* Un [subagente in background](/it/sub-agents#run-subagents-in-foreground-or-background) riprende dal suo proprio transcript

558

559{/* min-version: 2.1.198 */}A partire da v2.1.198 la consegna copre tutti e tre. Prima di v2.1.198 copriva solo i comandi shell e i workflow, quindi un subagente in background si fermava con il processo e veniva segnalato come fallito al prossimo risveglio.

560

561Il lavoro il cui stato vive solo all'interno del processo stesso si ferma con esso invece di essere consegnato. Questo riguarda i comandi shell che un subagente ha avviato, che il subagente ripreso può avviare di nuovo, e i [monitor](/it/tools-reference#monitor-tool) in esecuzione, il cui flusso di eventi non può essere spostato in un altro processo.

562

563L'eliminazione della sessione ferma tutto ciò che ha consegnato. Per fermare tutto il lavoro in background della sessione con il processo invece di consegnarlo, imposta la variabile di ambiente [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/it/env-vars#variables) su `1`.

533 564

534Se una sessione riavviata torna mostrando solo il suo prompt originale perché Claude Code ha frainteso il suo transcript come vuoto, il transcript della conversazione viene rinominato con un suffisso `.orphaned-` invece di essere eliminato, quindi rimane sulla tua macchina.565Se una sessione riavviata torna mostrando solo il suo prompt originale perché Claude Code ha frainteso il suo transcript come vuoto, il transcript della conversazione viene rinominato con un suffisso `.orphaned-` invece di essere eliminato, quindi rimane sulla tua macchina.

535 566

604 635

605Il sonno da solo non causa questo. Le sessioni vengono preservate durante il sonno e il supervisor si ricollega ad esse al risveglio.636Il sonno da solo non causa questo. Le sessioni vengono preservate durante il sonno e il supervisor si ricollega ad esse al risveglio.

606 637

638<h3 id="a-session-fails-before-starting-with-a-possibly-low-memory-note">

639 Una sessione non riesce a iniziare con una nota `possibly low memory`

640</h3>

641

642A partire dalla v2.1.199, quando il processo di una sessione in background esce prima di finire l'avvio e l'host ha poca memoria, lo stato della riga nomina l'uscita e aggiunge `possibly low memory — free some up and retry`. Le versioni precedenti mostravano solo il motivo dell'uscita nudo per questo errore.

643

644La nota è un'ipotesi, non una causa confermata. Claude Code la aggiunge solo quando il processo è uscito silenziosamente, senza scrivere un errore e senza essere fermato da un segnale, e l'host ha segnalato poca memoria in quel momento. Quando il processo ha scritto un errore prima di uscire, la riga mostra invece quell'errore.

645

646Libera memoria sulla macchina, quindi collegati, fai peek, o rispondi alla riga e il supervisor avvia un processo fresco per la sessione. Quando la memoria rimane bassa, il supervisor [ferma anche le sessioni inattive](#the-supervisor-process) per liberare risorse da solo.

647

607<h3 id="agent-view-says-the-background-service-did-not-respond">648<h3 id="agent-view-says-the-background-service-did-not-respond">

608 Agent view dice che il servizio in background non ha risposto649 Agent view dice che il servizio in background non ha risposto

609</h3>650</h3>

616 657

617Il nuovo supervisor si ricollega alle sessioni in esecuzione. Senza `--keep-workers`, il comando termina anche le sessioni in background. Il flag `--any` conferma che desideri fermare un supervisor che è stato avviato su richiesta piuttosto che come servizio installato, che è l'impostazione predefinita.658Il nuovo supervisor si ricollega alle sessioni in esecuzione. Senza `--keep-workers`, il comando termina anche le sessioni in background. Il flag `--any` conferma che desideri fermare un supervisor che è stato avviato su richiesta piuttosto che come servizio installato, che è l'impostazione predefinita.

618 659

660Un supervisor che si avvia ma non riesce ad accettare connessioni esce e rilascia il suo blocco da solo, quindi il prossimo `claude agents` avvia uno nuovo senza questo arresto manuale. I passaggi precedenti si applicano quando un supervisor in esecuzione subisce un blocco.

661

619Su Windows, se il supervisor non risponde alla richiesta di arresto, il comando stampa il suo ID di processo. Termina quel processo con `taskkill /PID <pid>` per completare il recupero. Le sessioni in background vengono comunque preservate quando hai passato `--keep-workers`.662Su Windows, se il supervisor non risponde alla richiesta di arresto, il comando stampa il suo ID di processo. Termina quel processo con `taskkill /PID <pid>` per completare il recupero. Le sessioni in background vengono comunque preservate quando hai passato `--keep-workers`.

620 663

621<h3 id="dispatch-fails-with-could-not-resolve-authentication-method">664<h3 id="dispatch-fails-with-could-not-resolve-authentication-method">

632 675

633Vedi il [riferimento degli errori](/it/errors#could-not-resolve-authentication-method) per l'elenco completo delle cause e delle correzioni.676Vedi il [riferimento degli errori](/it/errors#could-not-resolve-authentication-method) per l'elenco completo delle cause e delle correzioni.

634 677

635<h3 id="background-sessions-cannot-read-desktop-documents-or-downloads-on-macos">678<h3 id="background-sessions-can’t-read-desktop-documents-or-downloads-on-macos">

636 Le sessioni in background non riescono a leggere Desktop, Documents o Downloads su macOS679 Le sessioni in background non riescono a leggere Desktop, Documents o Downloads su macOS

637</h3>680</h3>

638 681

640 683

641Con il programma di installazione nativo, la voce appare come Claude Code e la concessione persiste tra gli aggiornamenti. Con altri metodi di installazione come Homebrew o npm, la voce mostra il percorso del binario e potrebbe dover essere concessa di nuovo dopo l'aggiornamento.684Con il programma di installazione nativo, la voce appare come Claude Code e la concessione persiste tra gli aggiornamenti. Con altri metodi di installazione come Homebrew o npm, la voce mostra il percorso del binario e potrebbe dover essere concessa di nuovo dopo l'aggiornamento.

642 685

686<h3 id="background-sessions-can’t-reach-local-network-hosts-on-macos">

687 Le sessioni in background non riescono a raggiungere host della rete locale su macOS

688</h3>

689

690Su macOS 15 e versioni successive, il sistema blocca un processo dal raggiungimento di dispositivi sulla tua rete locale finché non concedi il permesso di Rete Locale. Prima della v2.1.198 l'host della sessione in background non ha mai richiesto quel permesso, quindi i comandi che mirano a un indirizzo LAN non riuscivano con `connect: no route to host` anche se lo stesso comando funzionava in un terminale in primo piano. {/* min-version: 2.1.198 */}A partire dalla v2.1.198, il primo comando in una sessione in background che si connette a un indirizzo della rete locale attiva il prompt di permesso di Rete Locale di macOS per Claude Code. Concedilo una volta e quei comandi raggiungono gli host LAN nello stesso modo in cui lo fanno in un terminale in primo piano.

691

643<h3 id="a-session-is-slow-to-respond-after-attaching">692<h3 id="a-session-is-slow-to-respond-after-attaching">

644 Una sessione è lenta a rispondere dopo il collegamento693 Una sessione è lenta a rispondere dopo il collegamento

645</h3>694</h3>

679Agent view si è evoluto rapidamente durante l'anteprima di ricerca. Se sei su una versione più vecchia di Claude Code, alcuni comportamenti su questa pagina potrebbero differire; in particolare, `claude agents` rifiuta i flag che non supporta ancora con un errore di opzione sconosciuta. La tabella sottostante elenca quando ogni flag e comportamento è stato aggiunto.728Agent view si è evoluto rapidamente durante l'anteprima di ricerca. Se sei su una versione più vecchia di Claude Code, alcuni comportamenti su questa pagina potrebbero differire; in particolare, `claude agents` rifiuta i flag che non supporta ancora con un errore di opzione sconosciuta. La tabella sottostante elenca quando ogni flag e comportamento è stato aggiunto.

680 729

682| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |731| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

732| v2.1.199 | {/* min-version: 2.1.199 */}Una sessione in background il cui processo esce prima di finire l'avvio su un host con poca memoria mostra `possibly low memory — free some up and retry` nello stato della sua riga invece di solo il motivo dell'uscita nudo. Mettere in background una sessione con `←` o `/background` trasporta il suo `/color` alla nuova riga. |

733| v2.1.198 | {/* min-version: 2.1.198 */}Agent view invia una notifica attraverso `preferredNotifChannel` quando una sessione in background ha bisogno di input, finisce, o fallisce, e attiva l'hook `Notification` con il tipo `agent_needs_input` o `agent_completed`. `←` e `/exit` dentro `claude attach <id>` ritornano a agent view invece di uscire alla shell; `Ctrl+Z` ritorna alla shell. Una sessione in background che ha isolato il suo lavoro in un worktree esegue il commit, spinge il suo ramo isolato proprio, mai `main` o `master`, e apre una pull request in bozza quando finisce invece di chiedere prima. `/login` viene eseguito in agent view e apre la finestra di dialogo di accesso. La finestra di dialogo di uscita `Background work is running` offre `Move to background and exit`. Il trasferimento di uscita copre anche i subagent in background, che riprendono dal loro transcript al prossimo risveglio invece di essere segnalati come falliti. `claude --bg` combinato con `-p` o `--print` viene rifiutato con un errore. |

683| v2.1.196 | {/* min-version: 2.1.196 */}Una singola pressione di `←` mette in background una sessione in primo piano; le versioni precedenti richiedevano due pressioni, con un suggerimento nel footer e una conferma. `--dangerously-skip-permissions` passato a `claude agents` mostra il disclaimer di bypass invece di essere silenziosamente scartato. Le sessioni interattive che non hai mai nominato portano un nome predefinito come `my-app-3f` negli elenchi di sessioni e `claude agents --json`. I comandi shell in background e i workflow dinamici sopravvivono al processo della sessione che viene fermato, riavviato, o aggiornato, incluso su Windows; imposta `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` per disattivare il trasferimento. Un transcript frainteso come vuoto al riavvio viene rinominato con un suffisso `.orphaned-` invece di essere eliminato. |734| v2.1.196 | {/* min-version: 2.1.196 */}Una singola pressione di `←` mette in background una sessione in primo piano; le versioni precedenti richiedevano due pressioni, con un suggerimento nel footer e una conferma. `--dangerously-skip-permissions` passato a `claude agents` mostra il disclaimer di bypass invece di essere silenziosamente scartato. Le sessioni interattive che non hai mai nominato portano un nome predefinito come `my-app-3f` negli elenchi di sessioni e `claude agents --json`. I comandi shell in background e i workflow dinamici sopravvivono al processo della sessione che viene fermato, riavviato, o aggiornato, incluso su Windows; imposta `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` per disattivare il trasferimento. Un transcript frainteso come vuoto al riavvio viene rinominato con un suffisso `.orphaned-` invece di essere eliminato. |

684| v2.1.195 | {/* min-version: 2.1.195 */}Il lavoro in corso si trasferisce anche quando metti in background una sessione su Windows; imposta `CLAUDE_DISABLE_ADOPT=1` per fermarlo invece. Il gruppo `Completed` riempie lo spazio verticale rimanente e l'intestazione si compatta su terminali corti. Una versione più vecchia di Claude Code non scarta più i campi `state.json` delle sessioni più nuove o nasconde quelle sessioni da `claude agents`. Il collegamento a una sessione fermata passa immediatamente invece di mostrare una schermata vuota per fino a cinque secondi. Un supervisor che non riesce ad accettare connessioni esce e rilascia il suo blocco da solo. |735| v2.1.195 | {/* min-version: 2.1.195 */}Il lavoro in corso si trasferisce anche quando metti in background una sessione su Windows; imposta `CLAUDE_DISABLE_ADOPT=1` per fermarlo invece. Il gruppo `Completed` riempie lo spazio verticale rimanente e l'intestazione si compatta su terminali corti. Una versione più vecchia di Claude Code non scarta più i campi `state.json` delle sessioni più nuove o nasconde quelle sessioni da `claude agents`. Il collegamento a una sessione fermata passa immediatamente invece di mostrare una schermata vuota per fino a cinque secondi. Un supervisor che non riesce ad accettare connessioni esce e rilascia il suo blocco da solo. |

685| v2.1.174 | {/* min-version: 2.1.174 */}Le sessioni in background non ereditano più variabili di endpoint gateway come `ANTHROPIC_BASE_URL` dalla shell di avvio del supervisor; il supervisor fornisce uno snapshot di credenziali fresco ai worker pre-riscaldati, correggendo gli errori spurii di `Could not resolve authentication method`. |736| v2.1.174 | {/* min-version: 2.1.174 */}Le sessioni in background non ereditano più variabili di endpoint gateway come `ANTHROPIC_BASE_URL` dalla shell di avvio del supervisor; il supervisor fornisce uno snapshot di credenziali fresco ai worker pre-riscaldati, correggendo gli errori spurii di `Could not resolve authentication method`. |

agents.md +1 −1

Details

53Il comando per controllare il lavoro in esecuzione dipende da quale approccio hai utilizzato:53Il comando per controllare il lavoro in esecuzione dipende da quale approccio hai utilizzato:

54 54

55* Per le sessioni in background, `claude agents` apre [visualizzazione agenti](/it/agent-view): una schermata che mostra ogni sessione, il suo stato e quali hanno bisogno del tuo input.55* Per le sessioni in background, `claude agents` apre [visualizzazione agenti](/it/agent-view): una schermata che mostra ogni sessione, il suo stato e quali hanno bisogno del tuo input.

56* Per i subagenti nella sessione corrente, `/agents` apre un pannello con una scheda **Running** che elenca i subagenti attivi e una scheda **Library** dove [crei e modifichi subagenti personalizzati](/it/sub-agents#use-the-%2Fagents-command). Nonostante il nome simile, questo è separato da `claude agents`.56* Per i subagenti nella sessione corrente, i subagenti background denominati appaiono nella typeahead @-mention con il loro stato. {/* min-version: 2.1.198 */}A partire da v2.1.198, `/agents` non apre più un pannello; stampa un avviso che punta alle posizioni dei file dei subagenti. Per [creare e modificare subagenti personalizzati](/it/sub-agents#configure-subagents), chiedi a Claude o modifica i file direttamente. Nonostante il nome simile, `/agents` è separato da `claude agents`.

57* Per qualsiasi cosa in esecuzione in background della sessione corrente, `/tasks` elenca ogni elemento e ti consente di controllare, collegarti o interrompere.57* Per qualsiasi cosa in esecuzione in background della sessione corrente, `/tasks` elenca ogni elemento e ti consente di controllare, collegarti o interrompere.

58* Per i flussi di lavoro dinamici, `/workflows` elenca le esecuzioni in corso e completate, la fase in cui si trova ciascuna e quanti agenti hanno terminato.58* Per i flussi di lavoro dinamici, `/workflows` elenca le esecuzioni in corso e completate, la fase in cui si trova ciascuna e quanti agenti hanno terminato.

59 59

amazon-bedrock.md +1 −1

Details

184 184

185Queste due impostazioni hanno diverse condizioni di attivazione:185Queste due impostazioni hanno diverse condizioni di attivazione:

186 186

187* **`awsAuthRefresh`**: viene eseguito solo quando Claude Code rileva che le tue credenziali AWS sono scadute, sia localmente in base al loro timestamp che quando Bedrock restituisce un errore di credenziale, quindi ritenta la richiesta con credenziali aggiornate.187* **`awsAuthRefresh`**: viene eseguito solo quando Claude Code rileva che le tue credenziali AWS sono scadute, sia localmente in base al loro timestamp che quando l'API restituisce un errore di credenziale, quindi ritenta la richiesta con credenziali aggiornate.

188* **`awsCredentialExport`**: viene eseguito all'avvio della sessione e ad ogni ricaricamento delle credenziali, anche quando le credenziali nel tuo provider di credenziali predefinito di AWS sono ancora valide. Usa questo quando il tuo account Bedrock richiede credenziali tra account che differiscono da quelle che il provider predefinito risolverebbe.188* **`awsCredentialExport`**: viene eseguito all'avvio della sessione e ad ogni ricaricamento delle credenziali, anche quando le credenziali nel tuo provider di credenziali predefinito di AWS sono ancora valide. Usa questo quando il tuo account Bedrock richiede credenziali tra account che differiscono da quelle che il provider predefinito risolverebbe.

189 189

190<h5 id="example-configuration">190<h5 id="example-configuration">

auto-mode-config.md +18 −7

Details

54 54

55Per la maggior parte delle organizzazioni, `autoMode.environment` è l'unico campo che devi impostare. Comunica al classificatore quali repository, bucket e domini sono affidabili: il classificatore lo utilizza per decidere cosa significa "esterno", quindi qualsiasi destinazione non elencata è un potenziale bersaglio di esfiltrazione.55Per la maggior parte delle organizzazioni, `autoMode.environment` è l'unico campo che devi impostare. Comunica al classificatore quali repository, bucket e domini sono affidabili: il classificatore lo utilizza per decidere cosa significa "esterno", quindi qualsiasi destinazione non elencata è un potenziale bersaglio di esfiltrazione.

56 56

~~57A partire da Claude Code v2.1.195, `claude auto-mode defaults` stampa due tipi di voce di ambiente.~~57A partire da Claude Code v2.1.198, `claude auto-mode defaults` stampa tre tipi di voce di ambiente. Le versioni precedenti a v2.1.195 stampano solo i primi cinque slot di fiducia.

58 58

59* **Context slots**: descrivono la tua organizzazione, stack e postura di sicurezza in modo che il classificatore legga le altre regole nel tuo contesto. A differenza degli altri due tipi, gli slot di contesto non hanno regole proprie che li prendono di mira. Ognuno predefinito è `None configured` o all'assunzione conservativa denominata accanto ad esso:

60 * **Organization**

61 * **Primary use of Claude Code**: predefinito per lo sviluppo software

62 * **Cloud provider(s)**

63 * **Repository visibility**: un repository è assunto privato a meno che il suo host remoto e il nome non indichino diversamente

64 * **Internal sharing / snippet hosting**: i servizi di paste e gist pubblici sono trattati come esterni al confine di fiducia finché non ne nomini uno

65 * **Org-specific CLIs**

66 * **Secrets management**

67 * **Default / protected branches**: `main` e `master` sono trattati come protetti finché non nomini altri

68 * **CI/CD deploy targets**

69 * **Network posture**

70 * **Protected deployment namespaces / environments**: ricade all'euristica Sensitive remote targets finché non li nomini

71 * **Data retention / declassification**

59* **Trust slots**: denominano ciò che il classificatore tratta come interno al tuo confine. Gli slot sono Repository affidabile, Controllo del codice sorgente, Domini interni affidabili, Bucket cloud affidabili, Servizi interni chiave e Registro di pacchetti interno. Le voci di repository e controllo del codice sorgente predefinite sono il repository di lavoro e i suoi remote configurati. Ogni altro slot di fiducia predefinito è `None configured`, quindi nient'altro è affidabile finché non lo aggiungi.72* **Trust slots**: denominano ciò che il classificatore tratta come interno al tuo confine. Gli slot sono Repository affidabile, Controllo del codice sorgente, Domini interni affidabili, Bucket cloud affidabili, Servizi interni chiave e Registro di pacchetti interno. Le voci di repository e controllo del codice sorgente predefinite sono il repository di lavoro e i suoi remote configurati. Ogni altro slot di fiducia predefinito è `None configured`, quindi nient'altro è affidabile finché non lo aggiungi.

60* **Sensitivity slots**: denominano ciò che le regole protettive trattano come ad alto rischio. Gli slot sono Posizioni PII / dati regolamentati, Bersagli remoti sensibili e Ambiti IaC protetti. Ognuno predefinito è un'euristica ampia, come trattare qualsiasi host o namespace il cui nome contiene `prod` o `production` come bersaglio remoto sensibile, quindi le regole protettive sono attive prima di configurare qualsiasi cosa. Denominare bersagli concreti in uno slot di sensibilità fa sì che quelle regole si applichino ai bersagli denominati invece dell'euristica.73* **Sensitivity slots**: denominano ciò che le regole protettive trattano come ad alto rischio. Gli slot sono Sensitive data locations & audiences, Sensitive remote targets e Protected IaC scopes. Ognuno predefinito è un'euristica ampia, come trattare qualsiasi host o namespace il cui nome contiene `prod` o `production` come bersaglio remoto sensibile, quindi le regole protettive sono attive prima di configurare qualsiasi cosa. Denominare bersagli concreti in uno slot di sensibilità fa sì che quelle regole si applichino ai bersagli denominati invece dell'euristica.

~~62Le versioni precedenti a v2.1.195 stampano solo i primi cinque slot di fiducia.~~

63 74

64Per aggiungere le tue voci insieme ai valori predefiniti, includi la stringa letterale `"$defaults"` nell'array. Le voci predefinite vengono inserite in quella posizione, quindi le tue voci personalizzate possono andare prima o dopo di esse.75Per aggiungere le tue voci insieme ai valori predefiniti, includi la stringa letterale `"$defaults"` nell'array. Le voci predefinite vengono inserite in quella posizione, quindi le tue voci personalizzate possono andare prima o dopo di esse.

65 76

87* **Domini interni affidabili**: nomi host per API, dashboard e servizi all'interno della tua rete, come `*.internal.example.com`98* **Domini interni affidabili**: nomi host per API, dashboard e servizi all'interno della tua rete, come `*.internal.example.com`

88* **Servizi interni chiave**: CI, registri di artefatti, indici di pacchetti interni, strumenti di gestione degli incidenti99* **Servizi interni chiave**: CI, registri di artefatti, indici di pacchetti interni, strumenti di gestione degli incidenti

89* **Registro di pacchetti interno**: il registro npm, PyPI o altro privato attraverso il quale gli install dovrebbero instradare, in modo che gli install che lo bypassano per un registro pubblico vengano bloccati100* **Registro di pacchetti interno**: il registro npm, PyPI o altro privato attraverso il quale gli install dovrebbero instradare, in modo che gli install che lo bypassano per un registro pubblico vengano bloccati

90* **Posizioni PII / dati regolamentati**: i bucket, i database o i percorsi che contengono dati personali o regolamentati, in modo che il classificatore protegga quelle posizioni invece di indovinare dal contenuto101* **Sensitive data locations & audiences**: i bucket, i database o i percorsi che contengono dati personali, dati aziendali confidenziali, credenziali, dati regolamentati o materiale simile sensibile, e i destinatari con cui i dati in ogni posizione possono essere condivisi, in modo che il classificatore protegga quelle posizioni invece di indovinare dal contenuto. {/* min-version: 2.1.195 */}{/* max-version: 2.1.197 */}Claude Code v2.1.195 attraverso v2.1.197 denominano questa voce PII / regulated-data locations e coprono solo le posizioni che contengono dati personali o regolamentati, senza la dimensione del destinatario

91* **Bersagli remoti sensibili**: gli spazi dei nomi, gli host o i container che contano come produzione, in modo che i shell remoti e i port-forward in essi richiedano la tua approvazione esplicita102* **Bersagli remoti sensibili**: gli spazi dei nomi, gli host o i container che contano come produzione, in modo che i shell remoti e i port-forward in essi richiedano la tua approvazione esplicita

92* **Ambiti IaC protetti**: le risorse di infrastruttura il cui apply o destroy dovrebbe sempre richiedere di denominare il cambiamento103* **Ambiti IaC protetti**: le risorse di infrastruttura il cui apply o destroy dovrebbe sempre richiedere di denominare il cambiamento

93* **Contesto aggiuntivo**: vincoli del settore regolamentato, infrastruttura multi-tenant o requisiti di conformità che influiscono su ciò che il classificatore dovrebbe trattare come rischioso104* **Contesto aggiuntivo**: vincoli del settore regolamentato, infrastruttura multi-tenant o requisiti di conformità che influiscono su ciò che il classificatore dovrebbe trattare come rischioso

94 105

95Le voci Registro di pacchetti interno, Posizioni PII / dati regolamentati, Bersagli remoti sensibili e Ambiti IaC protetti richiedono Claude Code v2.1.195 o successivo. Le versioni precedenti le leggono ancora come contesto semplice ma non hanno le regole incorporate che le prendono di mira.106Le voci Internal package registry, Sensitive data locations & audiences, Sensitive remote targets e Protected IaC scopes richiedono Claude Code v2.1.195 o successivo. Le versioni precedenti le leggono ancora come contesto semplice ma non hanno le regole incorporate che le prendono di mira.

96 107

97Un modello di partenza utile: compila i campi tra parentesi e rimuovi le righe che non si applicano.108Un modello di partenza utile: compila i campi tra parentesi e rimuovi le righe che non si applicano.

98 109

chrome.md +15 −2

Details

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.

4 4

~~5# Usa Claude Code con Chrome (beta)~~5# Usa Claude Code con Chrome

6 6

7> Connetti Claude Code al tuo browser Chrome per testare app web, eseguire il debug con i log della console, automatizzare la compilazione di moduli ed estrarre dati dalle pagine web.7> Connetti Claude Code al tuo browser Chrome per testare app web, eseguire il debug con i log della console, automatizzare la compilazione di moduli ed estrarre dati dalle pagine web.

8 8

11Claude apre nuove schede per le attività del browser e condivide lo stato di accesso del tuo browser, quindi può accedere a qualsiasi sito in cui sei già connesso. Le azioni del browser vengono eseguite in una finestra Chrome visibile in tempo reale. Quando Claude incontra una pagina di accesso o un CAPTCHA, si ferma e ti chiede di gestirlo manualmente.11Claude apre nuove schede per le attività del browser e condivide lo stato di accesso del tuo browser, quindi può accedere a qualsiasi sito in cui sei già connesso. Le azioni del browser vengono eseguite in una finestra Chrome visibile in tempo reale. Quando Claude incontra una pagina di accesso o un CAPTCHA, si ferma e ti chiede di gestirlo manualmente.

12 12

13<Note>13<Note>

14 L'integrazione con Chrome è in beta e attualmente funziona con Google Chrome e Microsoft Edge. Non è ancora supportata su Brave, Arc o altri browser basati su Chromium. Anche WSL (Windows Subsystem for Linux) non è supportato.14 L'integrazione con Chrome funziona con Google Chrome e Microsoft Edge. Non è ancora supportata su Brave, Arc o altri browser basati su Chromium. Non è inoltre supportata in Windows Subsystem for Linux (WSL).

15</Note>15</Note>

16 16

17<h2 id="capabilities">17<h2 id="capabilities">

90 90

91Le autorizzazioni a livello di sito vengono ereditate dall'estensione Chrome. Gestisci le autorizzazioni nelle impostazioni dell'estensione Chrome per controllare quali siti Claude può navigare, fare clic e digitare.91Le autorizzazioni a livello di sito vengono ereditate dall'estensione Chrome. Gestisci le autorizzazioni nelle impostazioni dell'estensione Chrome per controllare quali siti Claude può navigare, fare clic e digitare.

92 92

93<h3 id="browser-tools-in-plan-mode">

94 Strumenti del browser in plan mode

95</h3>

97In [plan mode](/it/permission-modes#analyze-before-you-edit-with-plan-mode), le chiamate degli strumenti del browser che solo leggono la pagina o lo stato del browser vengono eseguite senza un prompt di autorizzazione, e le chiamate che cambiano lo stato richiedono l'approvazione.

99* **Chiamate di sola lettura**: `read_page`, `get_page_text`, `find`, lettura dei messaggi della console o delle richieste di rete, e acquisizione di uno screenshot

100* **Chiamate che cambiano lo stato**: clic, digitazione, navigazione, gestione delle schede e delle finestre, e registrazione di una GIF

101

102A partire dalla v2.1.199, una chiamata altrimenti di sola lettura che imposta un flag di input che cambia lo stato, come `createIfEmpty` su `tabs_context_mcp`, `clear` sui lettori della console e della rete, o `save_to_disk` su uno screenshot, richiede anche l'approvazione. Una chiamata `browser_batch` viene eseguita senza un prompt solo quando ogni azione al suo interno è di sola lettura.

103

93<h2 id="example-workflows">104<h2 id="example-workflows">

94 Flussi di lavoro di esempio105 Flussi di lavoro di esempio

95</h2>106</h2>

208 219

209La prima volta che abiliti l'integrazione con Chrome, Claude Code installa un file di configurazione dell'host di messaggistica nativa. Chrome legge questo file all'avvio, quindi se l'estensione non viene rilevata al primo tentativo, riavvia Chrome per raccogliere la nuova configurazione.220La prima volta che abiliti l'integrazione con Chrome, Claude Code installa un file di configurazione dell'host di messaggistica nativa. Chrome legge questo file all'avvio, quindi se l'estensione non viene rilevata al primo tentativo, riavvia Chrome per raccogliere la nuova configurazione.

210 221

222A partire dalla v2.1.199, Claude Code apre una scheda del browser che ti chiede di connettere l'estensione solo al primo install. Le sessioni successive che riscrivono il file di configurazione, ad esempio dopo il passaggio tra build di Claude Code o directory di configurazione, non lo riaprono.

223

211Se la connessione continua a non funzionare, verifica che il file di configurazione dell'host esista in:224Se la connessione continua a non funzionare, verifica che il file di configurazione dell'host esista in:

212 225

213Per Chrome:226Per Chrome:

claude-apps-gateway-config.md +63 −8

Details

4 4

5# Configurazione del gateway delle app Claude5# Configurazione del gateway delle app Claude

6 6

~~7> Riferimento per ogni opzione di gateway.yaml: listener e TLS, OIDC, sessione, archivio Postgres, upstream Bedrock/Agent Platform/Foundry, routing dei modelli, criteri gestiti e telemetria.~~7> Riferimento per ogni opzione di gateway.yaml: listener e TLS, OIDC, sessione, archivio Postgres, upstream Bedrock/Claude Platform su AWS/Agent Platform/Foundry, routing dei modelli, criteri gestiti e telemetria.

8 8

9Una distribuzione del gateway delle app Claude è configurata da un file YAML, convenzionalmente `gateway.yaml`. Il file definisce tutto ciò che il gateway fa: dove ascolta, come gli sviluppatori accedono, dove va l'inferenza e quali criteri e telemetria si applicano. Questa pagina è il riferimento per ogni opzione in quel file. Per scrivere il vostro primo file, iniziate dalla [guida rapida](/it/claude-apps-gateway#quickstart), che crea una configurazione minima funzionante e la esegue; una volta che avete una configurazione con cui siete soddisfatti, la [guida alla distribuzione](/it/claude-apps-gateway-deploy) copre la containerizzazione e l'hosting su Kubernetes, Cloud Run o la vostra piattaforma.9Una distribuzione del gateway delle app Claude è configurata da un file YAML, convenzionalmente `gateway.yaml`. Il file definisce tutto ciò che il gateway fa: dove ascolta, come gli sviluppatori accedono, dove va l'inferenza e quali criteri e telemetria si applicano. Questa pagina è il riferimento per ogni opzione in quel file.

11Per scrivere il vostro primo file, iniziate dalla [guida rapida](/it/claude-apps-gateway#quickstart), che crea una configurazione minima funzionante e la esegue. Una volta che avete una configurazione con cui siete soddisfatti, la [guida alla distribuzione](/it/claude-apps-gateway-deploy) copre la containerizzazione e l'hosting su Kubernetes, Cloud Run o la vostra piattaforma.

10 12

11Il gateway legge il file una volta, all'avvio, con `claude gateway --config /path/to/gateway.yaml`. Ogni opzione è convalidata rispetto a uno schema all'avvio, quindi una configurazione malformata non riesce all'inizio con un errore a livello di campo piuttosto che al primo utilizzo.13Il gateway legge il file una volta, all'avvio, con `claude gateway --config /path/to/gateway.yaml`. Ogni opzione è convalidata rispetto a uno schema all'avvio, quindi una configurazione malformata non riesce all'inizio con un errore a livello di campo piuttosto che al primo utilizzo.

12 14

24* [`oidc`](#oidc): il vostro provider di identità (IdP), inclusi emittente, client, mappatura dei claim e chi può accedere26* [`oidc`](#oidc): il vostro provider di identità (IdP), inclusi emittente, client, mappatura dei claim e chi può accedere

25* [`session`](#session): i token bearer che il gateway conia, con segreto e durata27* [`session`](#session): i token bearer che il gateway conia, con segreto e durata

26* [`store`](#store): PostgreSQL, per le concessioni dei dispositivi e i contatori dei limiti di velocità28* [`store`](#store): PostgreSQL, per le concessioni dei dispositivi e i contatori dei limiti di velocità

~~27* [`upstreams`](#upstreams): dove va l'inferenza, sia Anthropic, Bedrock, Agent Platform o Foundry~~29* [`upstreams`](#upstreams): dove va l'inferenza, sia Anthropic, Bedrock, Claude Platform su AWS, Agent Platform o Foundry

28 30

29**Sezioni facoltative:**31**Sezioni facoltative:**

30 32

68 `oidc`70 `oidc`

69</h3>71</h3>

70 72

71OpenID Connect (OIDC) è il protocollo SSO che il gateway utilizza con il vostro provider di identità; vedere [Configurazione del provider di identità](/it/claude-apps-gateway-deploy#identity-provider-setup) per ciò che registrare sul lato IdP. Il blocco `oidc` connette il gateway al vostro provider di identità e decide chi può accedere. Nomina l'emittente e il client OAuth, mappa i claim che portano email e gruppi e limita l'accesso per dominio email o gruppo.73Il blocco `oidc` connette il gateway al vostro provider di identità e decide chi può accedere. Nomina l'emittente e il client OAuth, mappa i claim che portano email e gruppi e limita l'accesso per dominio email o gruppo.

75OpenID Connect (OIDC) è il protocollo SSO che il gateway utilizza con il vostro provider di identità; vedere [Configurazione del provider di identità](/it/claude-apps-gateway-deploy#identity-provider-setup) per ciò che registrare sul lato IdP.

72 76

74| ------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |78| ------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

121 `upstreams`125 `upstreams`

122</h3>126</h3>

123 127

124`upstreams` è un elenco ordinato. Il gateway inoltra l'inferenza al primo upstream che risolve il modello richiesto. Su `5xx`, `429` o timeout esegue il failover al successivo; altri `4xx` no, perché questi errori sono attribuibili alla richiesta piuttosto che all'upstream. Più upstream dello stesso provider devono impostare un `name:` distinto.128`upstreams` è un elenco ordinato. Il gateway inoltra l'inferenza al primo upstream che risolve il modello richiesto. Su `5xx`, `429`, `401`, `403`, `404` o timeout esegue il failover al successivo; altri `4xx` no, perché questi errori sono attribuibili alla richiesta piuttosto che all'upstream. Un `401` o `403` significa che la credenziale del gateway stesso non ha funzionato contro quell'upstream, e un `404` significa che quell'upstream non serve il modello richiesto, quindi un upstream successivo nell'elenco può ancora servirlo.

129

130Il failover su `404` richiede gateway v2.1.198 o successivo. Le versioni precedenti hanno restituito il primo `404` al client anche quando un upstream successivo nell'elenco serviva il modello.

125 131

126I client Bedrock, Agent Platform e Foundry sono costruiti una volta all'avvio e i loro SDK aggiornano le credenziali internamente, quindi la rotazione delle credenziali cloud non richiede un riavvio. Le chiavi API Anthropic statiche e i bearer sono letti all'avvio; vedere [API Anthropic](#anthropic-api).132Più upstream dello stesso provider devono impostare un `name:` distinto.

133

134I client Bedrock, Claude Platform on AWS, Agent Platform e Foundry sono costruiti una volta all'avvio e i loro SDK aggiornano le credenziali internamente, quindi la rotazione delle credenziali cloud non richiede un riavvio. Le chiavi API Anthropic statiche e i bearer sono letti all'avvio; vedere [API Anthropic](#anthropic-api).

127 135

128<h4 id="anthropic-api">136<h4 id="anthropic-api">

129 API Anthropic137 API Anthropic

193| Altrove | Passate le credenziali tramite le variabili env `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` e `AWS_SESSION_TOKEN`, o impostatele esplicitamente in `auth:` con l'espansione `${VAR}` |201| Altrove | Passate le credenziali tramite le variabili env `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` e `AWS_SESSION_TOKEN`, o impostatele esplicitamente in `auth:` con l'espansione `${VAR}` |

194| Regione | `region:` è la regione dell'endpoint API. I profili di inferenza cross-region instradano attraverso la geo (US, EU, APAC) indipendentemente da quale scegliete. Per le regioni non-US o gli ARN di throughput provisioned, aggiungete un blocco [`models:`](#models) con gli ID per upstream corretti. |202| Regione | `region:` è la regione dell'endpoint API. I profili di inferenza cross-region instradano attraverso la geo (US, EU, APAC) indipendentemente da quale scegliete. Per le regioni non-US o gli ARN di throughput provisioned, aggiungete un blocco [`models:`](#models) con gli ID per upstream corretti. |

195 203

204<h4 id="claude-platform-on-aws">

205 Claude Platform on AWS

206</h4>

207

208Claude Platform on AWS serve l'API Anthropic di prima parte su infrastruttura AWS su `aws-external-anthropic.<region>.api.aws`. Utilizza ID modello di prima parte, onora gli header `anthropic-beta` come inviati e serve `count_tokens`, quindi nessuna della traduzione specifica di Bedrock si applica. Il provider `anthropicAws` richiede Claude Code v2.1.198 o successivo; le versioni precedenti del gateway lo rifiutano all'avvio.

209

210Per la distribuzione lato client della stessa piattaforma, vedere [Claude Code su Claude Platform on AWS](/it/claude-platform-on-aws). L'upstream lato gateway:

211

212```yaml theme={null}

213upstreams:

214 - provider: anthropicAws

215 region: us-east-1

216 workspace_id: wrkspc_...

217 auth:

218 api_key: ${ANTHROPIC_AWS_API_KEY} # sent as x-api-key

219 # OR SigV4 via the AWS default credential chain:

220 # auth: {}

221 # OR explicit SigV4 credentials:

222 # auth:

223 # aws_access_key_id: ${AWS_ACCESS_KEY_ID}

224 # aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}

225 # Override the derived endpoint:

226 # base_url: https://aws-external-anthropic.us-east-1.api.aws

227```

228

229La piattaforma viene eseguita in un account AWS separato da Amazon Bedrock e firma le richieste SigV4 per il suo nome di servizio, `aws-external-anthropic`, quindi un ruolo IAM limitato a Bedrock non lo autorizza. Una chiave API in `auth.api_key` ha la precedenza quando le credenziali SigV4 sono anche impostate. Un blocco `auth` vuoto usa la catena di credenziali predefinita dell'AWS SDK, la stessa catena che l'upstream [Amazon Bedrock](#amazon-bedrock) utilizza.

230

231| Campo | Obbligatorio | Descrizione |

232| ------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |

233| `region` | Sì | Regione AWS, lettere minuscole, cifre e trattini. Il gateway deriva l'endpoint da essa come `https://aws-external-anthropic.<region>.api.aws`. |

234| `workspace_id` | Sì | Inviato come header su ogni richiesta; la piattaforma lo richiede |

235| `auth.api_key` | No | Chiave API per la piattaforma, inviata come `x-api-key`. Non un token bearer: le due modalità di autenticazione sono una chiave API o SigV4. |

236| `auth.aws_access_key_id` / `auth.aws_secret_access_key` | No | Credenziali SigV4 esplicite. L'impostazione di una senza l'altra non riesce all'avvio. `auth.aws_session_token` è accettato insieme a loro. |

237| `base_url` | No | Override dell'endpoint derivato |

238

239Poiché la piattaforma risolve ID modello di prima parte, il catalogo integrato instrada ad essa senza un blocco [`models:`](#models). Quando curate un elenco `models:`, chiave l'entry `anthropicAws:` con l'ID di prima parte.

240

196<h4 id="google-cloud-agent-platform">241<h4 id="google-cloud-agent-platform">

197 Google Cloud Agent Platform242 Google Cloud Agent Platform

198</h4>243</h4>

255 300

256Lo stesso provider può apparire più di una volta con un `name:` distinto. Questo copre regioni diverse, account diversi tramite catene di credenziali diverse, throughput provisioned rispetto a on-demand e failover cross-provider.301Lo stesso provider può apparire più di una volta con un `name:` distinto. Questo copre regioni diverse, account diversi tramite catene di credenziali diverse, throughput provisioned rispetto a on-demand e failover cross-provider.

257 302

258Il gateway prova gli upstream in ordine. `5xx`, `429`, timeout e endpoint mancante (`501`) eseguono il failover; altri `4xx` no. `429` è capacità per upstream, quindi l'esaurimento del throughput provisioned (PT) esegue il failover a on-demand. Un upstream che non può risolvere il modello richiesto viene saltato senza un round-trip di rete.303Il gateway prova gli upstream in ordine. `5xx`, `429`, `401`, `403`, `404`, timeout e endpoint mancante (`501`) eseguono il failover; altri `4xx` no.

304

305`429` è capacità per upstream, quindi l'esaurimento del throughput provisioned (PT) esegue il failover a on-demand. `404` è disponibilità del modello per upstream, quindi un upstream che non ha abilitato un modello non blocca un upstream successivo che lo serve. Un upstream che non può risolvere il modello richiesto viene saltato senza un round-trip di rete.

259 306

260Questo esempio instrada un'allocazione Bedrock di throughput provisioned per primo, trabocca a on-demand e un secondo account e ricade all'API Anthropic per ultimo:307Questo esempio instrada un'allocazione Bedrock di throughput provisioned per primo, trabocca a on-demand e un secondo account e ricade all'API Anthropic per ultimo:

261 308

513* `sandbox.network.allowManagedDomainsOnly` e `sandbox.filesystem.allowManagedReadPathsOnly`: quando bloccate, gli allowlist corrispondenti vengono uniti tra le fonti560* `sandbox.network.allowManagedDomainsOnly` e `sandbox.filesystem.allowManagedReadPathsOnly`: quando bloccate, gli allowlist corrispondenti vengono uniti tra le fonti

514* [`allowAllClaudeAiMcps`](/it/settings#available-settings): override di allow-only per l'allowlist del server MCP claude.ai561* [`allowAllClaudeAiMcps`](/it/settings#available-settings): override di allow-only per l'allowlist del server MCP claude.ai

515* `sandbox.bwrapPath` e `sandbox.socatPath`: percorsi del file system ai binari helper [sandbox](/it/sandboxing)562* `sandbox.bwrapPath` e `sandbox.socatPath`: percorsi del file system ai binari helper [sandbox](/it/sandboxing)

563* [`forceRemoteSettingsRefresh`](/it/server-managed-settings): blocca l'avvio fino a quando le impostazioni gestite remote non vengono recuperate di recente, quindi una politica MDM o file che la imposta è onorata anche quando un payload remoto memorizzato nella cache che manca la chiave è la fonte con priorità più alta

516 564

517Ogni altra chiave, inclusi `allowManagedPermissionRulesOnly` e `disableBypassPermissionsMode`, proviene solo dalla fonte con priorità più alta. Vedere [Precedenza delle impostazioni](/it/settings#settings-precedence) per la stessa regola nella pagina delle impostazioni.565Ogni altra chiave, inclusi `allowManagedPermissionRulesOnly` e `disableBypassPermissionsMode`, proviene solo dalla fonte con priorità più alta. Vedere [Precedenza delle impostazioni](/it/settings#settings-precedence) per la stessa regola nella pagina delle impostazioni.

518 566

580| `limits` | `max_request_bytes` | 32 MiB | Corpo della richiesta in entrata massimo; le richieste di dimensioni eccessive ottengono `413` prima che il corpo sia bufferizzato. Aumentate per richieste di file o immagini di grandi dimensioni. |628| `limits` | `max_request_bytes` | 32 MiB | Corpo della richiesta in entrata massimo; le richieste di dimensioni eccessive ottengono `413` prima che il corpo sia bufferizzato. Aumentate per richieste di file o immagini di grandi dimensioni. |

583| `timeouts` | `upstream_ttfb_ms` | 120000 | Attesa massima per gli header di risposta dell'upstream (time to first byte). Il corpo della risposta quindi scorre senza un cap di wall-clock. Si applica al percorso upstream Anthropic diretto; Bedrock, Agent Platform e Foundry sono limitati dal timeout proprio dell'SDK del provider. |631| `timeouts` | `upstream_ttfb_ms` | 120000 | Attesa massima per gli header di risposta dell'upstream (time to first byte). Il corpo della risposta quindi scorre senza un cap di wall-clock. Si applica al percorso upstream Anthropic diretto; ogni altro provider è limitato dal timeout proprio dell'SDK del provider. |

584| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | Limite di velocità per IP sull'endpoint di autorizzazione del dispositivo non autenticato. Aumentate per una grande organizzazione dietro un IP di uscita condiviso o NAT. Questi limiti si applicano solo al flusso di accesso della concessione del dispositivo, non all'inferenza `/v1/messages`. Vedere [Resistenza al brute-force del codice utente](/it/claude-apps-gateway-deploy#user-code-brute-force-resistance). |632| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | Limite di velocità per IP sull'endpoint di autorizzazione del dispositivo non autenticato. Aumentate per una grande organizzazione dietro un IP di uscita condiviso o NAT. Questi limiti si applicano solo al flusso di accesso della concessione del dispositivo, non all'inferenza `/v1/messages`. Vedere [Resistenza al brute-force del codice utente](/it/claude-apps-gateway-deploy#user-code-brute-force-resistance). |

586 634

662 # region: us-east-1710 # region: us-east-1

663 # auth: {}711 # auth: {}

664 712

713 # - provider: anthropicAws

714 # region: us-east-1

715 # workspace_id: wrkspc_...

716 # auth:

717 # api_key: ${ANTHROPIC_AWS_API_KEY}

718

665 # - provider: vertex719 # - provider: vertex

666 # region: us-east5720 # region: us-east5

667 # project_id: example-prod721 # project_id: example-prod

678 upstream_model:732 upstream_model:

679 anthropic: claude-opus-4-8733 anthropic: claude-opus-4-8

680 # bedrock: us.anthropic.claude-opus-4-8734 # bedrock: us.anthropic.claude-opus-4-8

735 # anthropicAws: claude-opus-4-8

681 # vertex: claude-opus-4-8736 # vertex: claude-opus-4-8

682 # foundry: <your-opus-deployment-name>737 # foundry: <your-opus-deployment-name>

683 - id: claude-sonnet-4-6738 - id: claude-sonnet-4-6

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

Details

97<Note>97<Note>

98 **Workload identity**98 **Workload identity**

99 99

100 Preferisci l'identità del workload della piattaforma rispetto alle chiavi statiche: IRSA su EKS per Bedrock, Workload Identity su GKE per Agent Platform, e workload identity su AKS per Foundry. Imposta `auth: {}` nel blocco upstream, o `use_azure_ad: true` per Foundry, e il gateway raccoglie l'identità del pod attraverso la catena di credenziali predefinita di quel provider. Per un accoppiamento cross-cloud, come un upstream Bedrock su GKE, imposta credenziali esplicite nel blocco `auth` dell'upstream. Il [riferimento `upstreams`](/it/claude-apps-gateway-config#upstreams) ha dettagli di configurazione per piattaforma.100 Preferisci l'identità del workload della piattaforma rispetto alle chiavi statiche: IRSA su EKS per Bedrock e per Claude Platform su AWS, Workload Identity su GKE per Agent Platform, e workload identity su AKS per Foundry. Imposta `auth: {}` nel blocco upstream, o `use_azure_ad: true` per Foundry, e il gateway raccoglie l'identità del pod attraverso la catena di credenziali predefinita di quel provider. Per un accoppiamento cross-cloud, come un upstream Bedrock su GKE, imposta credenziali esplicite nel blocco `auth` dell'upstream. Il [riferimento `upstreams`](/it/claude-apps-gateway-config#upstreams) ha dettagli di configurazione per piattaforma.

101</Note>101</Note>

102 102

103<h3 id="cloud-run">103<h3 id="cloud-run">

claude-code-on-the-web.md +2 −2

Details

721Il teletrasporto verifica questi requisiti prima di riprendere una sessione. Se un requisito non è soddisfatto, vedrai un errore o ti verrà chiesto di risolvere il problema.721Il teletrasporto verifica questi requisiti prima di riprendere una sessione. Se un requisito non è soddisfatto, vedrai un errore o ti verrà chiesto di risolvere il problema.

722 722

724| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |724| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

725| Stato git pulito | La tua directory di lavoro non deve avere modifiche non sottoposte a commit. Il teletrasporto ti chiede di archiviare le modifiche se necessario. |725| Stato git pulito | La tua directory di lavoro non deve avere modifiche non sottoposte a commit. Il teletrasporto ti chiede di archiviare le modifiche se necessario. |

726| Repository corretto | Devi eseguire `--teleport` da un checkout dello stesso repository, non da un fork. |726| Repository corretto | Devi eseguire `--teleport` da un checkout dello stesso repository, non da un fork. {/* min-version: 2.1.199 */}A partire dalla v2.1.199, Claude Code accetta un checkout anche quando non riesce a analizzare il remoto in un nome host, come un alias host SSH come `git@work:owner/repo.git` o una forma breve riscritta con `insteadOf`. Mostra un prompt di conferma per primo, e solo quando il proprietario del remoto e il nome del repository corrispondono al repository della sessione. |

727| Ramo disponibile | Il ramo dalla sessione cloud deve essere stato inviato al remoto. Il teletrasporto lo recupera e lo controlla automaticamente. |727| Ramo disponibile | Il ramo dalla sessione cloud deve essere stato inviato al remoto. Il teletrasporto lo recupera e lo controlla automaticamente. |

729 729

claude-platform-on-aws.md +1 −1

Details

230 230

231Per CI e automazione, fornire al runner un ruolo IAM con autorizzazione per invocare il servizio Anthropic e impostare `AWS_REGION`. La catena di credenziali raccoglie il ruolo automaticamente.231Per CI e automazione, fornire al runner un ruolo IAM con autorizzazione per invocare il servizio Anthropic e impostare `AWS_REGION`. La catena di credenziali raccoglie il ruolo automaticamente.

232 232

233Se le credenziali SSO scadono durante la sessione, configurare [`awsAuthRefresh`](/it/amazon-bedrock#advanced-credential-configuration) in modo che Claude Code riesegua il comando di accesso e riprovi invece di fallire. Aggiungere il comando al file `settings.json`:233Se le credenziali SSO scadono durante la sessione, configurare [`awsAuthRefresh`](/it/amazon-bedrock#advanced-credential-configuration) in modo che Claude Code riesegua il comando di accesso e riprovi invece di fallire. L'aggiornamento automatico su Claude Platform on AWS richiede Claude Code v2.1.198 o successivo; le versioni precedenti si fermano con un prompt per eseguire `/login`, che non può aggiornare le credenziali AWS. Aggiungere il comando al file `settings.json`:

234 234

235```json theme={null}235```json theme={null}

236{236{

cli-reference.md +4 −2

Details

47 47

48Se digiti male un sottocomando, Claude Code suggerisce la corrispondenza più vicina e esce senza avviare una sessione. Ad esempio, `claude udpate` stampa `Did you mean claude update?`.48Se digiti male un sottocomando, Claude Code suggerisce la corrispondenza più vicina e esce senza avviare una sessione. Ad esempio, `claude udpate` stampa `Did you mean claude update?`.

49 49

50{/* min-version: 2.1.199 */}A partire da v2.1.199, `claude --dangerously-skip-permissions daemon <subcommand>` esegue il sottocomando `daemon`. Le versioni precedenti trattavano `daemon <subcommand>` come il prompt per una nuova sessione interattiva, quindi il sottocomando non veniva mai eseguito quando il flag veniva per primo, una configurazione comune quando `claude` è aliasato per includere il flag. Solo un `--dangerously-skip-permissions` o `--allow-dangerously-skip-permissions` iniziale instrada a `daemon` in questo modo; qualsiasi altro flag iniziale avvia comunque una sessione interattiva.

50<h2 id="cli-flags">52<h2 id="cli-flags">

51 Flag CLI53 Flag CLI

52</h2>54</h2>

66| `--ax-screen-reader` | {/* min-version: 2.1.181 */}Renderizza output compatibile con lettore di schermo: testo piatto senza bordi decorativi o animazioni. Forza il renderer classico, quindi l'impostazione [`tui`](/it/settings#available-settings) non ha effetto per la sessione. Ha la precedenza su [`CLAUDE_AX_SCREEN_READER`](/it/env-vars) e l'impostazione [`axScreenReader`](/it/settings#available-settings). Richiede Claude Code v2.1.181 o successivo | `claude --ax-screen-reader` |68| `--ax-screen-reader` | {/* min-version: 2.1.181 */}Renderizza output compatibile con lettore di schermo: testo piatto senza bordi decorativi o animazioni. Forza il renderer classico, quindi l'impostazione [`tui`](/it/settings#available-settings) non ha effetto per la sessione. Ha la precedenza su [`CLAUDE_AX_SCREEN_READER`](/it/env-vars) e l'impostazione [`axScreenReader`](/it/settings#available-settings). Richiede Claude Code v2.1.181 o successivo | `claude --ax-screen-reader` |

67| `--bare` | Modalità minima: salta l'auto-discovery di hooks, skills, plugins, server MCP, memoria automatica e CLAUDE.md in modo che le chiamate con script si avviino più velocemente. Claude ha accesso a strumenti Bash, lettura file e modifica file. Imposta [`CLAUDE_CODE_SIMPLE`](/it/env-vars). Vedi [modalità bare](/it/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |69| `--bare` | Modalità minima: salta l'auto-discovery di hooks, skills, plugins, server MCP, memoria automatica e CLAUDE.md in modo che le chiamate con script si avviino più velocemente. Claude ha accesso a strumenti Bash, lettura file e modifica file. Imposta [`CLAUDE_CODE_SIMPLE`](/it/env-vars). Vedi [modalità bare](/it/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |

69| `--bg`, `--background` | Avvia la sessione come un [agent in background](/it/agent-view) e ritorna immediatamente. Stampa l'ID della sessione e i comandi di gestione. Combina con `--exec` per eseguire un comando shell come un job in background invece di una sessione Claude, o con `--agent` per eseguire uno specifico subagent | `claude --bg "investigate the flaky test"` |71| `--bg`, `--background` | Avvia la sessione come un [agent in background](/it/agent-view) e ritorna immediatamente. Stampa l'ID della sessione e i comandi di gestione. Combina con `--exec` per eseguire un comando shell come un job in background invece di una sessione Claude, o con `--agent` per eseguire uno specifico subagent. {/* min-version: 2.1.198 */}Non può essere combinato con `-p`/`--print`; vedi il [riferimento degli errori](/it/errors#command-line-errors) | `claude --bg "investigate the flaky test"` |

70| `--channels` | (Anteprima di ricerca) Server MCP le cui notifiche di [channel](/it/channels) Claude dovrebbe ascoltare in questa sessione. Elenco separato da spazi di voci `plugin:<name>@<marketplace>`. Richiede autenticazione Claude.ai | `claude --channels plugin:my-notifier@my-marketplace` |72| `--channels` | (Anteprima di ricerca) Server MCP le cui notifiche di [channel](/it/channels) Claude dovrebbe ascoltare in questa sessione. Elenco separato da spazi di voci `plugin:<name>@<marketplace>`. Richiede autenticazione Claude.ai | `claude --channels plugin:my-notifier@my-marketplace` |

72| `--continue`, `-c` | Carica la conversazione più recente nella directory corrente. Include sessioni che hanno aggiunto questa directory con `/add-dir` | `claude --continue` |74| `--continue`, `-c` | Carica la conversazione più recente nella directory corrente. Include sessioni che hanno aggiunto questa directory con `/add-dir` | `claude --continue` |

100| `--no-session-persistence` | Disabilita la persistenza della sessione in modo che le sessioni non vengano salvate su disco e non possano essere riprese. Solo modalità print. La variabile di ambiente [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/it/env-vars) fa lo stesso in qualsiasi modalità | `claude -p --no-session-persistence "query"` |102| `--no-session-persistence` | Disabilita la persistenza della sessione in modo che le sessioni non vengano salvate su disco e non possano essere riprese. Solo modalità print. La variabile di ambiente [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/it/env-vars) fa lo stesso in qualsiasi modalità | `claude -p --no-session-persistence "query"` |

102| `--permission-mode` | Inizia in una [modalità di autorizzazione](/it/permission-modes) specificata. Accetta `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` o `bypassPermissions`. Sostituisce `defaultMode` dai file di impostazioni | `claude --permission-mode plan` |104| `--permission-mode` | Inizia in una [modalità di autorizzazione](/it/permission-modes) specificata. Accetta `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` o `bypassPermissions`. Sostituisce `defaultMode` dai file di impostazioni | `claude --permission-mode plan` |

103| `--permission-prompt-tool` | Specifica uno strumento MCP per gestire i prompt di autorizzazione in modalità non interattiva | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |105| `--permission-prompt-tool` | Specifica uno strumento MCP per gestire i prompt di autorizzazione in modalità non interattiva. {/* min-version: 2.1.199 */}A partire da v2.1.199, lo strumento di prompt non può approvare uno strumento MCP contrassegnato come [richiedente interazione dell'utente](/it/mcp#require-approval-for-a-specific-tool): un risultato `allow` per uno viene convertito in un deny | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

104| `--plugin-dir` | Carica un plugin da una directory o da un archivio `.zip` per questa sessione solo. Ogni flag accetta un percorso. Ripeti il flag per più plugin: `--plugin-dir A --plugin-dir B.zip` | `claude --plugin-dir ./my-plugin` |106| `--plugin-dir` | Carica un plugin da una directory o da un archivio `.zip` per questa sessione solo. Ogni flag accetta un percorso. Ripeti il flag per più plugin: `--plugin-dir A --plugin-dir B.zip` | `claude --plugin-dir ./my-plugin` |

105| `--plugin-url` | Recupera un archivio plugin `.zip` da un URL per questa sessione solo. Ripeti il flag per più plugin, o passa URL separati da spazi in un singolo valore tra virgolette | `claude --plugin-url https://example.com/plugin.zip` |107| `--plugin-url` | Recupera un archivio plugin `.zip` da un URL per questa sessione solo. Ripeti il flag per più plugin, o passa URL separati da spazi in un singolo valore tra virgolette | `claude --plugin-url https://example.com/plugin.zip` |

106| `--print`, `-p` | Stampa la risposta senza modalità interattiva (vedi [documentazione Agent SDK](/it/agent-sdk/overview) per i dettagli di utilizzo programmatico) | `claude -p "query"` |108| `--print`, `-p` | Stampa la risposta senza modalità interattiva (vedi [documentazione Agent SDK](/it/agent-sdk/overview) per i dettagli di utilizzo programmatico) | `claude -p "query"` |

commands.md +10 −9

Details

10 10

11Digita `/` per visualizzare ogni comando disponibile per te, oppure digita `/` seguito da lettere per filtrare.11Digita `/` per visualizzare ogni comando disponibile per te, oppure digita `/` seguito da lettere per filtrare.

12 12

~~13Un comando viene riconosciuto solo all'inizio del tuo messaggio. Il testo che segue il nome del comando viene passato ad esso come argomenti.~~13Un comando viene riconosciuto solo all'inizio del tuo messaggio. Il testo che segue il nome del comando viene passato ad esso come argomenti. {/* min-version: 2.1.199 */}A partire dalla v2.1.199, [skills](/it/skills#pass-arguments-to-skills) sono l'eccezione: un'invocazione di skill seguita da altre skill, come `/skill-a /skill-b do XYZ`, carica ogni skill denominata all'inizio e passa il testo finale a ciascuna come argomenti. È possibile concatenare fino a sei skill.

14 14

15<h2 id="commands-across-a-typical-workflow">15<h2 id="commands-across-a-typical-workflow">

16 Comandi durante un flusso di lavoro tipico16 Comandi durante un flusso di lavoro tipico

18 18

19La maggior parte dei comandi è utile in un momento specifico di una sessione, dalla configurazione di un progetto all'invio di una modifica.19La maggior parte dei comandi è utile in un momento specifico di una sessione, dalla configurazione di un progetto all'invio di una modifica.

20 20

21**Prima sessione in un repository.** Esegui `/init` per generare un `CLAUDE.md` iniziale, quindi `/memory` per perfezionarlo. Usa `/mcp` e `/agents` per configurare eventuali server o subagent di cui il progetto ha bisogno, e `/permissions` per impostare le regole di approvazione che desideri.21**Prima sessione in un repository.** Esegui `/init` per generare un `CLAUDE.md` iniziale, quindi `/memory` per perfezionarlo. Usa `/mcp` per configurare eventuali server di cui il progetto ha bisogno, chiedi a Claude di creare eventuali [subagent](/it/sub-agents) che desideri, ed esegui `/permissions` per impostare le regole di approvazione.

22 22

23**Durante un'attività.** `/plan` passa alla modalità plan prima di una modifica importante. `/model` e `/effort` regolano quanto ragionamento stai spendendo. Quando la conversazione diventa lunga, `/context` mostra dove sta andando la finestra e `/compact` la riassume; usa `/btw` per una rapida considerazione laterale che non dovrebbe gonfiare la cronologia.23**Durante un'attività.** `/plan` passa alla modalità plan prima di una modifica importante. `/model` e `/effort` regolano quale modello stai utilizzando e quanto ragionamento applica. Quando la conversazione diventa lunga, `/context` mostra cosa sta riempiendo la finestra e `/compact` la riassume per liberare spazio. Usa `/btw` per una rapida considerazione laterale che non dovrebbe aggiungersi alla cronologia della conversazione.

24 24

25**Esecuzione del lavoro in parallelo.** `/agents` apre il gestore per i [subagent](/it/sub-agents) a cui Claude può delegare attività secondarie, e `/tasks` elenca cosa è in esecuzione in background della sessione corrente. `/background` scollega l'intera sessione per continuare l'esecuzione come [agente in background](/it/agent-view) e libera il tuo terminale. Per una modifica importante che si estende su tutta la codebase, `/batch` la scompone in unità indipendenti ed esegue ciascuna nel suo proprio [worktree](/it/worktrees). Vedi [Esegui agenti in parallelo](/it/agents) per come questi approcci si relazionano.25**Esecuzione del lavoro in parallelo.** Claude delega attività secondarie ai [subagent](/it/sub-agents), e `/tasks` elenca cosa è in esecuzione in background della sessione corrente. `/background` scollega l'intera sessione per continuare l'esecuzione come [agente in background](/it/agent-view) e libera il tuo terminale. Per una modifica importante che si estende su tutta la codebase, `/batch` la scompone in unità indipendenti ed esegue ciascuna nel suo proprio [worktree](/it/worktrees). Vedi [Esegui agenti in parallelo](/it/agents) per come questi approcci si relazionano.

26 26

27**Prima di inviare.** `/diff` mostra cosa è cambiato, `/code-review` controlla il diff per bug di correttezza e pulizie e può applicare i risultati con `--fix`, `/review` esegue la stessa revisione in sola lettura su una pull request di GitHub, e `/security-review` fornisce una lettura più profonda in sola lettura. `/code-review ultra` esegue una revisione multi-agente nel cloud.27**Prima di inviare.** `/diff` mostra cosa è cambiato, `/code-review` controlla il diff per bug di correttezza e pulizie e può applicare i risultati con `--fix`, `/review` esegue la stessa revisione in sola lettura su una pull request di GitHub, e `/security-review` fornisce una lettura più profonda in sola lettura. `/code-review ultra` esegue una revisione multi-agente nel cloud.

28 28

51| :--------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |51| :--------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

52| `/add-dir <path>` | Aggiungi una directory di lavoro per l'accesso ai file durante la sessione corrente. La maggior parte della configurazione `.claude/` [non viene rilevata](/it/permissions#additional-directories-grant-file-access-not-configuration) dalla directory aggiunta. Puoi successivamente riprendere la sessione dalla directory aggiunta con `--continue` o `--resume` |52| `/add-dir <path>` | Aggiungi una directory di lavoro per l'accesso ai file durante la sessione corrente. La maggior parte della configurazione `.claude/` [non viene rilevata](/it/permissions#additional-directories-grant-file-access-not-configuration) dalla directory aggiunta. Puoi successivamente riprendere la sessione dalla directory aggiunta con `--continue` o `--resume` |

53| `/advisor [model\|off]` | {/* min-version: 2.1.98 */}Abilita o disabilita lo [strumento advisor](/it/advisor), che consulta un secondo modello per una guida nei momenti chiave durante un'attività. Accetta `opus`, `sonnet`, `fable` ({/* min-version: 2.1.170 */}v2.1.170+), o un ID modello completo. Senza un argomento, apre un selettore. Richiede Claude Code v2.1.98 o successivo |53| `/advisor [model\|off]` | {/* min-version: 2.1.98 */}Abilita o disabilita lo [strumento advisor](/it/advisor), che consulta un secondo modello per una guida nei momenti chiave durante un'attività. Accetta `opus`, `sonnet`, `fable` ({/* min-version: 2.1.170 */}v2.1.170+), o un ID modello completo. Senza un argomento, apre un selettore. Richiede Claude Code v2.1.98 o successivo |

54| `/agents` | Gestisci le configurazioni [agent](/it/sub-agents) |54| `/agents` | {/* min-version: 2.1.198 */}A partire da v2.1.198, eseguire `/agents` stampa un promemoria per chiedere a Claude di creare o gestire [subagent](/it/sub-agents), o di modificare direttamente `.claude/agents/` o `~/.claude/agents/`. {/* max-version: 2.1.197 */}Su v2.1.197 e versioni precedenti, apre un'interfaccia interattiva per creare e gestire le configurazioni dei subagent |

55| `/autofix-pr [prompt]` | Avvia una sessione [Claude Code sul web](/it/claude-code-on-the-web#auto-fix-pull-requests) che monitora il PR del ramo corrente e invia correzioni quando la CI fallisce o i revisori lasciano commenti. Rileva il PR aperto dal ramo in cui sei posizionato con `gh pr view`; per monitorare un PR diverso, prima controlla il suo ramo. Per impostazione predefinita, la sessione cloud viene istruita a correggere ogni fallimento della CI e commento di revisione; passa un prompt per darle istruzioni diverse, ad esempio `/autofix-pr only fix lint and type errors`. Richiede la CLI `gh` e l'accesso a [Claude Code sul web](/it/claude-code-on-the-web) |55| `/autofix-pr [prompt]` | Avvia una sessione [Claude Code sul web](/it/claude-code-on-the-web#auto-fix-pull-requests) che monitora il PR del ramo corrente e invia correzioni quando la CI fallisce o i revisori lasciano commenti. Rileva il PR aperto dal ramo in cui sei posizionato con `gh pr view`; per monitorare un PR diverso, prima controlla il suo ramo. Per impostazione predefinita, la sessione cloud viene istruita a correggere ogni fallimento della CI e commento di revisione; passa un prompt per darle istruzioni diverse, ad esempio `/autofix-pr only fix lint and type errors`. Richiede la CLI `gh` e l'accesso a [Claude Code sul web](/it/claude-code-on-the-web) |

56| `/background [prompt]` | Stacca la sessione corrente per eseguirla come un [agente in background](/it/agent-view) e libera questo terminale. Passa un prompt per inviare un'istruzione in più prima di staccarsi. Monitora la sessione con `claude agents`. Alias: `/bg` |56| `/background [prompt]` | Stacca la sessione corrente per eseguirla come un [agente in background](/it/agent-view) e libera questo terminale. Passa un prompt per inviare un'istruzione in più prima di staccarsi. Monitora la sessione con `claude agents`. Alias: `/bg` |

57| `/batch <instruction>` | **[Skill](/it/skills#bundled-skills).** Orchestra modifiche su larga scala in un codebase in parallelo. Ricerca il codebase, scompone il lavoro in 5-30 unità indipendenti e presenta un piano. Una volta approvato, avvia un [subagent in background](/it/sub-agents#run-subagents-in-foreground-or-background) per unità in un [git worktree](/it/worktrees) isolato. Ogni subagent implementa la sua unità, esegue i test e apre una pull request. Richiede un repository git. Esempio: `/batch migrate src/ from Solid to React` |57| `/batch <instruction>` | **[Skill](/it/skills#bundled-skills).** Orchestra modifiche su larga scala in un codebase in parallelo. Ricerca il codebase, scompone il lavoro in 5-30 unità indipendenti e presenta un piano. Una volta approvato, avvia un [subagent in background](/it/sub-agents#run-subagents-in-foreground-or-background) per unità in un [git worktree](/it/worktrees) isolato. Ogni subagent implementa la sua unità, esegue i test e apre una pull request. Richiede un repository git. Esempio: `/batch migrate src/ from Solid to React` |

68| `/context [all]` | Visualizza l'utilizzo del contesto corrente come una griglia colorata. Mostra suggerimenti di ottimizzazione per gli strumenti pesanti di contesto, gonfiore della memoria e avvisi di capacità. In [modalità a schermo intero](/it/fullscreen) la ripartizione per elemento è compressa per mantenere la griglia visibile. Passa `all` per espanderla |68| `/context [all]` | Visualizza l'utilizzo del contesto corrente come una griglia colorata. Mostra suggerimenti di ottimizzazione per gli strumenti pesanti di contesto, gonfiore della memoria e avvisi di capacità. In [modalità a schermo intero](/it/fullscreen) la ripartizione per elemento è compressa per mantenere la griglia visibile. Passa `all` per espanderla |

69| `/copy [N]` | Copia l'ultima risposta dell'assistente negli appunti. Passa un numero `N` per copiare la N-esima risposta più recente: `/copy 2` copia la penultima. Quando sono presenti blocchi di codice, mostra un selettore interattivo per selezionare singoli blocchi o la risposta completa. Premi `w` nel selettore per scrivere la selezione in un file invece che negli appunti, il che è utile tramite SSH |69| `/copy [N]` | Copia l'ultima risposta dell'assistente negli appunti. Passa un numero `N` per copiare la N-esima risposta più recente: `/copy 2` copia la penultima. Quando sono presenti blocchi di codice, mostra un selettore interattivo per selezionare singoli blocchi o la risposta completa. Premi `w` nel selettore per scrivere la selezione in un file invece che negli appunti, il che è utile tramite SSH |

71| `/dataviz [request]` | **[Skill](/it/skills#bundled-skills).** Guida alla progettazione per grafici, diagrammi e dashboard. Claude sceglie la forma del grafico per i dati, assegna il colore per ruolo, convalida la tavolozza per la sicurezza dei daltonici e il contrasto con uno script integrato, e applica regole di mark, interazione e accessibilità. Utilizza una tavolozza segnaposto neutrale dal punto di vista del marchio che sostituisci con la tua. {/* min-version: 2.1.198 */}Richiede Claude Code v2.1.198 o successivo |

71| `/debug [description]` | **[Skill](/it/skills#bundled-skills).** Abilita la registrazione del debug per la sessione corrente e risolvi i problemi leggendo il log di debug della sessione. La registrazione del debug è disattivata per impostazione predefinita a meno che tu non abbia avviato con `claude --debug`, quindi eseguire `/debug` a metà sessione inizia a catturare i log da quel momento in poi. Facoltativamente descrivi il problema per focalizzare l'analisi |72| `/debug [description]` | **[Skill](/it/skills#bundled-skills).** Abilita la registrazione del debug per la sessione corrente e risolvi i problemi leggendo il log di debug della sessione. La registrazione del debug è disattivata per impostazione predefinita a meno che tu non abbia avviato con `claude --debug`, quindi eseguire `/debug` a metà sessione inizia a catturare i log da quel momento in poi. Facoltativamente descrivi il problema per focalizzare l'analisi |

72| `/deep-research <question>` | **[Workflow](/it/workflows#bundled-workflows).** Espandi le ricerche web su una domanda, recupera e verifica incrociata le fonti e sintetizza un rapporto citato |73| `/deep-research <question>` | **[Workflow](/it/workflows#bundled-workflows).** Espandi le ricerche web su una domanda, recupera e verifica incrociata le fonti e sintetizza un rapporto citato |

74| `/design-sync [hint]` | **[Skill](/it/skills#bundled-skills).** Converti il sistema di design React del tuo repository e caricalo su [Claude Design](https://claude.ai/design), in modo che i design che produce utilizzino i tuoi componenti reali. Facoltativamente nomina il sistema di design, ad esempio `/design-sync Acme DS`. Una prima sincronizzazione verifica ogni componente e può richiedere alcune ore su un repository di grandi dimensioni. Disponibile sull'API Anthropic; su Amazon Bedrock, sulla piattaforma agenti di Google Cloud e su Microsoft Foundry lo strumento sottostante non può raggiungere claude.ai, quindi il comando non è disponibile |75| `/design-sync [hint]` | **[Skill](/it/skills#bundled-skills).** Converti il sistema di design React del tuo repository e caricalo su [Claude Design](https://claude.ai/design), in modo che i design che produce utilizzino i tuoi componenti reali. Facoltativamente nomina il sistema di design, ad esempio `/design-sync Acme DS`. Una prima sincronizzazione verifica ogni componente e può richiedere alcune ore su un repository di grandi dimensioni. Disponibile sull'API Anthropic; su Amazon Bedrock, sulla piattaforma agenti di Google Cloud e su Microsoft Foundry lo strumento sottostante non può raggiungere claude.ai, quindi il comando non è disponibile |

75| `/desktop` | Continua la sessione corrente nell'app Claude Code Desktop. Richiede macOS o Windows e un abbonamento Claude. Alias: `/app` |76| `/desktop` | Continua la sessione corrente nell'app Claude Code Desktop. Richiede macOS o Windows e un abbonamento Claude. Alias: `/app` |

76| `/diff` | Apri un visualizzatore diff interattivo che mostra le modifiche non sottoposte a commit e i diff per turno. Usa le frecce sinistra/destra per passare tra il diff git corrente e i singoli turni di Claude, e su/giù per sfogliare i file |77| `/diff` | Apri un visualizzatore diff interattivo che mostra le modifiche non sottoposte a commit e i diff per turno. Usa le frecce sinistra/destra per passare tra il diff git corrente e i singoli turni di Claude, e su/giù per sfogliare i file. {/* min-version: 2.1.198 */}A partire da v2.1.198, il visualizzatore aperto si aggiorna anche automaticamente quando lo stato git del repository cambia al di fuori della sessione, come un cambio di ramo o un commit in un altro terminale |

77| `/doctor` | Diagnostica e verifica l'installazione e le impostazioni di Claude Code. I risultati vengono visualizzati con icone di stato. Premi `f` per fare in modo che Claude corregga eventuali problemi segnalati |78| `/doctor` | Diagnostica e verifica l'installazione e le impostazioni di Claude Code. I risultati vengono visualizzati con icone di stato. Premi `f` per fare in modo che Claude corregga eventuali problemi segnalati |

78| `/effort [level\|auto]` | Imposta il [livello di sforzo](/it/model-config#adjust-effort-level) del modello. Accetta `low`, `medium`, `high`, `xhigh`, `max` o `ultracode`; i livelli disponibili dipendono dal modello e `max` e `ultracode` sono solo per la sessione. `ultracode` è un'impostazione di Claude Code che combina il ragionamento `xhigh` con l'orchestrazione automatica del [workflow](/it/workflows#let-claude-decide-with-ultracode). `auto` ripristina il valore predefinito del modello. Senza un argomento, apre un cursore interattivo; usa le frecce sinistra e destra per scegliere un livello e `Enter` per applicare. Ha effetto immediato senza aspettare il completamento della risposta corrente |79| `/effort [level\|auto]` | Imposta il [livello di sforzo](/it/model-config#adjust-effort-level) del modello. Accetta `low`, `medium`, `high`, `xhigh`, `max` o `ultracode`; i livelli disponibili dipendono dal modello e `max` e `ultracode` sono solo per la sessione. `ultracode` è un'impostazione di Claude Code che combina il ragionamento `xhigh` con l'orchestrazione automatica del [workflow](/it/workflows#let-claude-decide-with-ultracode). `auto` ripristina il valore predefinito del modello. Senza un argomento, apre un cursore interattivo; usa le frecce sinistra e destra per scegliere un livello e `Enter` per applicare. Ha effetto immediato senza aspettare il completamento della risposta corrente |

79| `/exit` | Esci dalla CLI. In una [sessione in background](/it/agent-view#attach-to-a-session) collegata, questo stacca e la sessione continua a funzionare. Alias: `/quit` |80| `/exit` | Esci dalla CLI. In una [sessione in background](/it/agent-view#attach-to-a-session) collegata, questo stacca e la sessione continua a funzionare. Alias: `/quit` |

81| `/fast [on\|off]` | Attiva o disattiva la [modalità veloce](/it/fast-mode) |82| `/fast [on\|off]` | Attiva o disattiva la [modalità veloce](/it/fast-mode) |

83| `/fewer-permission-prompts` | **[Skill](/it/skills#bundled-skills).** Scansiona i tuoi trascritti per le comuni chiamate Bash e MCP tool di sola lettura, quindi aggiungi una lista di autorizzazione prioritaria al progetto `.claude/settings.json` per ridurre i prompt di permesso |84| `/fewer-permission-prompts` | **[Skill](/it/skills#bundled-skills).** Scansiona i tuoi trascritti per le comuni chiamate Bash e MCP tool di sola lettura, quindi aggiungi una lista di autorizzazione prioritaria al progetto `.claude/settings.json` per ridurre i prompt di permesso |

84| `/focus` | Attiva/disattiva la vista focus, che mostra solo il tuo ultimo prompt, un riassunto di una riga della chiamata dello strumento con diffstat di modifica e la risposta finale. La selezione persiste tra le sessioni; imposta [`viewMode`](/it/settings#available-settings) nelle impostazioni per ignorarla. Disponibile solo nel [rendering a schermo intero](/it/fullscreen) |85| `/focus` | Attiva/disattiva la vista focus, che mostra solo il tuo ultimo prompt, un riassunto di una riga della chiamata dello strumento con diffstat di modifica e la risposta finale. {/* min-version: 2.1.198 */}A partire da v2.1.198, il riassunto della chiamata dello strumento conta anche i subagent lanciati nel turno e comprime le notifiche di attività in background completate in un singolo conteggio. La selezione persiste tra le sessioni; imposta [`viewMode`](/it/settings#available-settings) nelle impostazioni per ignorarla. Disponibile solo nel [rendering a schermo intero](/it/fullscreen) |

85| `/fork <directive>` | {/* min-version: 2.1.161 */}Avvia un [subagent con fork](/it/sub-agents#fork-the-current-conversation): un subagent in background che eredita la conversazione completa e lavora sulla direttiva mentre tu continui. Il suo risultato ritorna alla tua conversazione quando finisce. Per passare tu stesso a una copia della conversazione, usa `/branch`. Prima di v2.1.161, `/fork` è un alias per `/branch` |86| `/fork <directive>` | {/* min-version: 2.1.161 */}Avvia un [subagent con fork](/it/sub-agents#fork-the-current-conversation): un subagent in background che eredita la conversazione completa e lavora sulla direttiva mentre tu continui. Il suo risultato ritorna alla tua conversazione quando finisce. Per passare tu stesso a una copia della conversazione, usa `/branch`. Prima di v2.1.161, `/fork` è un alias per `/branch` |

86| `/goal [condition\|clear]` | Imposta un [obiettivo](/it/goal): Claude continua a lavorare tra i turni finché la condizione non è soddisfatta. Senza un argomento, mostra l'obiettivo corrente o raggiunto più di recente. `clear`, `stop`, `off`, `reset`, `none` o `cancel` rimuove un obiettivo attivo in anticipo |87| `/goal [condition\|clear]` | Imposta un [obiettivo](/it/goal): Claude continua a lavorare tra i turni finché la condizione non è soddisfatta. Senza un argomento, mostra l'obiettivo corrente o raggiunto più di recente. `clear`, `stop`, `off`, `reset`, `none` o `cancel` rimuove un obiettivo attivo in anticipo |

87| `/heapdump` | Scrivi uno snapshot dell'heap JavaScript e una ripartizione della memoria su `~/Desktop`, o la tua home directory su Linux senza una cartella Desktop, per diagnosticare l'utilizzo elevato della memoria. Vedi [risoluzione dei problemi](/it/troubleshooting#high-cpu-or-memory-usage) |88| `/heapdump` | Scrivi uno snapshot dell'heap JavaScript e una ripartizione della memoria su `~/Desktop`, o la tua home directory su Linux senza una cartella Desktop, per diagnosticare l'utilizzo elevato della memoria. Vedi [risoluzione dei problemi](/it/troubleshooting#high-cpu-or-memory-usage) |

127| `/setup-bedrock` | Configura l'autenticazione [Amazon Bedrock](/it/amazon-bedrock), la regione e i pin del modello attraverso una procedura guidata interattiva. Visibile solo quando `CLAUDE_CODE_USE_BEDROCK=1` è impostato. Gli utenti di Bedrock per la prima volta possono anche accedere a questa procedura guidata dalla schermata di accesso |128| `/setup-bedrock` | Configura l'autenticazione [Amazon Bedrock](/it/amazon-bedrock), la regione e i pin del modello attraverso una procedura guidata interattiva. Visibile solo quando `CLAUDE_CODE_USE_BEDROCK=1` è impostato. Gli utenti di Bedrock per la prima volta possono anche accedere a questa procedura guidata dalla schermata di accesso |

128| `/setup-vertex` | Configura l'autenticazione [Google Vertex AI](/it/google-vertex-ai), il progetto, la regione e i pin del modello attraverso una procedura guidata interattiva. Visibile solo quando `CLAUDE_CODE_USE_VERTEX=1` è impostato. Gli utenti di Vertex AI per la prima volta possono anche accedere a questa procedura guidata dalla schermata di accesso |129| `/setup-vertex` | Configura l'autenticazione [Google Vertex AI](/it/google-vertex-ai), il progetto, la regione e i pin del modello attraverso una procedura guidata interattiva. Visibile solo quando `CLAUDE_CODE_USE_VERTEX=1` è impostato. Gli utenti di Vertex AI per la prima volta possono anche accedere a questa procedura guidata dalla schermata di accesso |

129| `/simplify [target]` | {/* min-version: 2.1.154 */}**[Skill](/it/skills#bundled-skills).** Rivedi il codice modificato per opportunità di pulizia e applica le correzioni. Quattro [agenti](/it/sub-agents) di revisione vengono eseguiti in parallelo, coprendo il riutilizzo degli helper esistenti, la semplificazione, l'efficienza e se la modifica si trova al giusto livello di astrazione. Da v2.1.154, la revisione non cerca bug di correttezza. Usa `/code-review` per trovare i bug. Nelle versioni precedenti `/simplify` è equivalente a `/code-review --fix`. Passa un percorso o un riferimento PR per rivedere un target specifico |130| `/simplify [target]` | {/* min-version: 2.1.154 */}**[Skill](/it/skills#bundled-skills).** Rivedi il codice modificato per opportunità di pulizia e applica le correzioni. Quattro [agenti](/it/sub-agents) di revisione vengono eseguiti in parallelo, coprendo il riutilizzo degli helper esistenti, la semplificazione, l'efficienza e se la modifica si trova al giusto livello di astrazione. Da v2.1.154, la revisione non cerca bug di correttezza. Usa `/code-review` per trovare i bug. Nelle versioni precedenti `/simplify` è equivalente a `/code-review --fix`. Passa un percorso o un riferimento PR per rivedere un target specifico |

130| `/skills` | Elenca le [skills](/it/skills) disponibili. Premi `t` per ordinare per conteggio dei token. Premi `Space` per [nascondere una skill da Claude o dal menu `/`](/it/skills#override-skill-visibility-from-settings), quindi `Enter` per salvare |131| `/skills` | Elenca le [skills](/it/skills) disponibili. {/* min-version: 2.1.121 */}A partire da v2.1.121, digita per filtrare l'elenco per nome. Premi `t` per ordinare per conteggio dei token. Premi `Space` per [nascondere una skill da Claude o dal menu `/`](/it/skills#override-skill-visibility-from-settings), quindi `Enter` per salvare |

132| `/status` | Apri l'interfaccia Impostazioni (scheda Stato) che mostra versione, modello, account e connettività. Funziona mentre Claude sta rispondendo, senza aspettare il completamento della risposta corrente |133| `/status` | Apri l'interfaccia Impostazioni (scheda Stato) che mostra versione, modello, account e connettività. Funziona mentre Claude sta rispondendo |

133| `/statusline` | Configura la [linea di stato](/it/statusline) di Claude Code. Descrivi cosa desideri, oppure esegui senza argomenti per auto-configurare dal tuo prompt della shell |134| `/statusline` | Configura la [linea di stato](/it/statusline) di Claude Code. Descrivi cosa desideri, oppure esegui senza argomenti per auto-configurare dal tuo prompt della shell |

135| `/stop` | Ferma la [sessione in background](/it/agent-view) corrente. Disponibile solo quando collegato a una sessione in background; la trascrizione e qualsiasi worktree vengono conservati. Per staccarsi senza fermare, usa `/exit` o premi `←` |136| `/stop` | Ferma la [sessione in background](/it/agent-view) corrente. Disponibile solo quando collegato a una sessione in background; la trascrizione e qualsiasi worktree vengono conservati. Per staccarsi senza fermare, usa `/exit` o premi `←` |

context-window.md +1 −1

Details

1587 Cosa sopravvive alla compattazione1587 Cosa sopravvive alla compattazione

1588</h2>1588</h2>

1589 1589

1590Quando una sessione lunga si compatta, Claude Code riassume la cronologia della conversazione per adattarsi alla finestra di contesto. Cosa accade alle tue istruzioni dipende da come sono state caricate:1590Quando una sessione lunga si compatta, Claude Code riassume la cronologia della conversazione per adattarsi alla finestra di contesto. {/* min-version: 2.1.198 */}A partire dalla v2.1.198, la richiesta di riepilogo eredita la configurazione del [extended thinking](/it/model-config#extended-thinking) della tua sessione, quindi ragiona con il thinking abilitato quando la tua sessione lo ha abilitato e rimane disattivato altrimenti. Il thinking influisce solo su come viene prodotto il riepilogo; le impostazioni della tua sessione rimangono invariate in seguito. Cosa accade alle tue istruzioni dipende da come sono state caricate:

1591 1591

1592| Meccanismo | Dopo la compattazione |1592| Meccanismo | Dopo la compattazione |

1593| :-------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |1593| :-------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |

costs.md +3 −3

Details

107* **Cancella tra i compiti**: Utilizza `/clear` per ricominciare da capo quando passi a lavori non correlati. Il contesto obsoleto spreca token su ogni messaggio successivo. Utilizza `/rename` prima di cancellare in modo da poter trovare facilmente la sessione in seguito, quindi `/resume` per tornare ad essa.107* **Cancella tra i compiti**: Utilizza `/clear` per ricominciare da capo quando passi a lavori non correlati. Il contesto obsoleto spreca token su ogni messaggio successivo. Utilizza `/rename` prima di cancellare in modo da poter trovare facilmente la sessione in seguito, quindi `/resume` per tornare ad essa.

108* **Aggiungi istruzioni di compaction personalizzate**: `/compact Focus on code samples and API usage` dice a Claude cosa preservare durante la sintesi.108* **Aggiungi istruzioni di compaction personalizzate**: `/compact Focus on code samples and API usage` dice a Claude cosa preservare durante la sintesi.

109 109

110Puoi anche personalizzare il comportamento della compaction nel tuo CLAUDE.md:110Puoi anche personalizzare il comportamento della compaction nel tuo file CLAUDE.md nella radice del tuo progetto:

111 111

112```markdown theme={null}112```markdown theme={null}

113# Compact instructions113# Compact instructions

170 </Tab>170 </Tab>

171 171

172 <Tab title="filter-test-output.sh">172 <Tab title="filter-test-output.sh">

173 L'hook chiama questo script, che controlla se il comando è un test runner e lo modifica per mostrare solo i fallimenti:173 L'hook chiama questo script. Crea la cartella con `mkdir -p ~/.claude/hooks`, salva lo script sottostante come `~/.claude/hooks/filter-test-output.sh` e rendilo eseguibile con `chmod +x ~/.claude/hooks/filter-test-output.sh`. Controlla se il comando è un test runner e lo modifica per mostrare solo i fallimenti:

174 174

175 ```bash theme={null}175 ```bash theme={null}

176 #!/bin/bash176 #!/bin/bash

198 Regola il pensiero esteso198 Regola il pensiero esteso

199</h3>199</h3>

200 200

201Il pensiero esteso è abilitato per impostazione predefinita perché migliora significativamente le prestazioni su compiti complessi di pianificazione e ragionamento. I token di pensiero vengono fatturati come token di output, e il budget predefinito può essere decine di migliaia di token per richiesta a seconda del modello. Per compiti più semplici dove il ragionamento profondo non è necessario, puoi ridurre i costi abbassando il [livello di sforzo](/it/model-config#adjust-effort-level) con `/effort` o in `/model`, disabilitando il pensiero in `/config`, o, su modelli con un [budget di pensiero fisso](/it/model-config#adaptive-reasoning-and-fixed-thinking-budgets), abbassando il budget con `MAX_THINKING_TOKENS=8000`. I modelli di ragionamento adattivo ignorano i budget diversi da zero, quindi utilizza i livelli di sforzo lì. La disabilitazione del pensiero non è disponibile su Fable 5, che utilizza sempre il pensiero esteso.201Il pensiero esteso è abilitato per impostazione predefinita perché migliora significativamente le prestazioni su compiti complessi di pianificazione e ragionamento. I token di pensiero vengono fatturati come token di output, e il budget predefinito può essere decine di migliaia di token per richiesta a seconda del modello. Per compiti più semplici dove il ragionamento profondo non è necessario, puoi ridurre i costi abbassando il [livello di sforzo](/it/model-config#adjust-effort-level) con `/effort` o in `/model`, disabilitando il pensiero in `/config`, o, su modelli con un [budget di pensiero fisso](/it/model-config#adaptive-reasoning-and-fixed-thinking-budgets), abbassando il budget impostando la [variabile di ambiente](/it/env-vars) `MAX_THINKING_TOKENS`, ad esempio `MAX_THINKING_TOKENS=8000`. I modelli di ragionamento adattivo ignorano i budget diversi da zero, quindi utilizza i livelli di sforzo lì. La disabilitazione del pensiero non è disponibile su Fable 5, che utilizza sempre il pensiero esteso.

202 202

203<h3 id="delegate-verbose-operations-to-subagents">203<h3 id="delegate-verbose-operations-to-subagents">

204 Delega le operazioni dettagliate ai subagent204 Delega le operazioni dettagliate ai subagent

debug-your-config.md +1 −2

Details

14 Vedi cosa è stato caricato nel contesto14 Vedi cosa è stato caricato nel contesto

15</h2>15</h2>

16 16

17Il comando `/context` mostra tutto ciò che occupa la finestra di contesto per la sessione corrente, suddiviso per categoria: prompt di sistema, file di memoria, skills, strumenti MCP e messaggi di conversazione. Eseguilo per primo per confermare se i tuoi `CLAUDE.md`, regole o descrizioni di skill sono presenti.17Il comando `/context` mostra tutto ciò che occupa la finestra di contesto per la sessione corrente, suddiviso per categoria: prompt di sistema, file di memoria, skills, subagenti personalizzati con la fonte da cui ciascuno è stato caricato, strumenti MCP e messaggi di conversazione. Eseguilo per primo per confermare se i tuoi `CLAUDE.md`, regole o descrizioni di skill sono presenti.

18 18

19Per dettagli su una categoria specifica, segui con il comando dedicato:19Per dettagli su una categoria specifica, segui con il comando dedicato:

20 20

22| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |22| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

25| `/agents` | Subagenti configurati e le loro impostazioni |

27| `/mcp` | Server MCP connessi e il loro stato |26| `/mcp` | Server MCP connessi e il loro stato |

desktop.md +1 −1

Details

829* **Linux (beta)**: Computer Use non è ancora disponibile nell'app desktop Linux. Vedi [Claude Desktop su Linux](/it/desktop-linux).829* **Linux (beta)**: Computer Use non è ancora disponibile nell'app desktop Linux. Vedi [Claude Desktop su Linux](/it/desktop-linux).

830* **Suggerimenti di codice inline**: Desktop non fornisce suggerimenti in stile autocomplete. Funziona tramite prompt conversazionali e modifiche di codice esplicite.830* **Suggerimenti di codice inline**: Desktop non fornisce suggerimenti in stile autocomplete. Funziona tramite prompt conversazionali e modifiche di codice esplicite.

831* **Team di agent**: le sessioni parallele di Claude Code che si messaggiano tra loro sono disponibili nella [CLI](/it/agent-teams), non in Desktop. Per il lavoro multi-agent all'interno di una sessione, usa i [flussi di lavoro dinamici](/it/workflows), che vengono eseguiti in Desktop.831* **Team di agent**: le sessioni parallele di Claude Code che si messaggiano tra loro sono disponibili nella [CLI](/it/agent-teams), non in Desktop. Per il lavoro multi-agent all'interno di una sessione, usa i [flussi di lavoro dinamici](/it/workflows), che vengono eseguiti in Desktop.

832* **Comandi terminal-dialog**: i comandi integrati che aprono un pannello interattivo nel terminale, come `/permissions`, `/config`, `/agents` e `/doctor`, non sono disponibili nella scheda Code e rispondono con `isn't available in this environment`. Modifica direttamente i [file di impostazioni](/it/settings) per gestire le regole di autorizzazione e la configurazione, oppure esegui il comando dalla CLI standalone.832* **Comandi terminal-dialog**: i comandi integrati che aprono un pannello interattivo nel terminale, come `/permissions`, `/config` e `/doctor`, non sono disponibili nella scheda Code e rispondono con `isn't available in this environment`. Modifica direttamente i [file di impostazioni](/it/settings) per gestire le regole di autorizzazione e la configurazione, oppure esegui il comando dalla CLI standalone.

833 833

834<h2 id="troubleshooting">834<h2 id="troubleshooting">

835 Troubleshooting835 Troubleshooting

env-vars.md +9 −5

Details

145| `BASH_MAX_TIMEOUT_MS` | Timeout massimo che il modello può impostare per i comandi bash a lunga esecuzione (predefinito: 600000, o 10 minuti) |145| `BASH_MAX_TIMEOUT_MS` | Timeout massimo che il modello può impostare per i comandi bash a lunga esecuzione (predefinito: 600000, o 10 minuti) |

146| `CCR_FORCE_BUNDLE` | Imposta su `1` per forzare [`claude --remote`](/it/claude-code-on-the-web#send-local-repositories-without-github) a raggruppare e caricare il vostro repository locale anche quando l'accesso a GitHub è disponibile |146| `CCR_FORCE_BUNDLE` | Imposta su `1` per forzare [`claude --remote`](/it/claude-code-on-the-web#send-local-repositories-without-github) a raggruppare e caricare il vostro repository locale anche quando l'accesso a GitHub è disponibile |

147| `CLAUDECODE` | Imposta su `1` nei sottoprocessi che Claude Code genera (strumento Bash, sessioni tmux, comandi [hook](/it/hooks), comandi della [linea di stato](/it/statusline), sottoprocessi del server MCP [stdio](/it/mcp)). Le estensioni IDE impostano anche questo nei loro terminali integrati. Utilizza per rilevare quando uno script è in esecuzione all'interno di un sottoprocesso generato da Claude Code. Per verificare se il processo corrente è stato generato direttamente da una chiamata di strumento o hook, piuttosto che all'interno di un server MCP stdio che Claude Code ha avviato, utilizzate `CLAUDE_CODE_CHILD_SESSION` |147| `CLAUDECODE` | Imposta su `1` nei sottoprocessi che Claude Code genera (strumento Bash, sessioni tmux, comandi [hook](/it/hooks), comandi della [linea di stato](/it/statusline), sottoprocessi del server MCP [stdio](/it/mcp)). Le estensioni IDE impostano anche questo nei loro terminali integrati. Utilizza per rilevare quando uno script è in esecuzione all'interno di un sottoprocesso generato da Claude Code. Per verificare se il processo corrente è stato generato direttamente da una chiamata di strumento o hook, piuttosto che all'interno di un server MCP stdio che Claude Code ha avviato, utilizzate `CLAUDE_CODE_CHILD_SESSION` |

148| `CLAUDE_AFK_COUNTDOWN_MS` | {/* min-version: 2.1.198 */}Quanti millisecondi prima dell'auto-continuazione il conto alla rovescia sullo schermo appare su una finestra di dialogo `AskUserQuestion` senza risposta. Predefinito `20000` (20 secondi). Vedi `CLAUDE_AFK_TIMEOUT_MS`. Richiede Claude Code v2.1.198 o successivo |

149| `CLAUDE_AFK_TIMEOUT_MS` | {/* min-version: 2.1.198 */}Quanti millisecondi di tempo inattivo prima che una finestra di dialogo [`AskUserQuestion`](/it/tools-reference) senza risposta continui automaticamente senza di voi. Predefinito `60000` (60 secondi). Per mantenere le domande aperte mentre siete assenti, impostate un valore grande come `86400000` (24 ore). L'impostazione di `0` non disattiva il timeout; chiude la finestra di dialogo immediatamente. Richiede Claude Code v2.1.198 o successivo |

148| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | Imposta su `1` per disabilitare tutti i tipi di [subagent](/it/sub-agents) integrati come Explore e Plan. Si applica solo in modalità non interattiva (il flag `-p`). Utile per gli utenti SDK che desiderano una lavagna pulita |150| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | Imposta su `1` per disabilitare tutti i tipi di [subagent](/it/sub-agents) integrati come Explore e Plan. Si applica solo in modalità non interattiva (il flag `-p`). Utile per gli utenti SDK che desiderano una lavagna pulita |

149| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | Imposta su `1` per saltare il prefisso `mcp__<server>__` sui nomi degli strumenti dai server MCP creati da SDK. Gli strumenti utilizzano i loro nomi originali. Solo utilizzo SDK |151| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | Imposta su `1` per saltare il prefisso `mcp__<server>__` sui nomi degli strumenti dai server MCP creati da SDK. Gli strumenti utilizzano i loro nomi originali. Solo utilizzo SDK |

150| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Timeout di stallo in millisecondi per i subagent in background. Predefinito `600000` (10 minuti). Il timer si ripristina su ogni evento di progresso dello streaming; se nessun progresso arriva entro la finestra, il subagent viene interrotto e l'attività viene contrassegnata come non riuscita, mostrando qualsiasi risultato parziale al genitore |152| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Timeout di stallo in millisecondi per i subagent in background. Predefinito `600000` (10 minuti). Il timer si ripristina su ogni evento di progresso dello streaming; se nessun progresso arriva entro la finestra, il subagent viene interrotto e l'attività viene contrassegnata come non riuscita, mostrando qualsiasi risultato parziale al genitore |

162| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Imposta su `0` per omettere il blocco di attribuzione (versione client e impronta digitale del prompt) dall'inizio del prompt di sistema. Disabilitarlo migliora i tassi di hit della cache dei prompt quando si instrada attraverso un [gateway LLM](/it/llm-gateway). Il caching dell'API Anthropic non è interessato |164| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Imposta su `0` per omettere il blocco di attribuzione (versione client e impronta digitale del prompt) dall'inizio del prompt di sistema. Disabilitarlo migliora i tassi di hit della cache dei prompt quando si instrada attraverso un [gateway LLM](/it/llm-gateway). Il caching dell'API Anthropic non è interessato |

163| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Imposta la capacità del contesto in token utilizzata per i calcoli di compattazione automatica. Per impostazione predefinita, la finestra del contesto del modello: 200K per i modelli standard o 1M per i modelli con [contesto esteso](/it/model-config#extended-context), tranne su Sonnet 5, che ha la sua propria [soglia predefinita](/it/model-config#sonnet-5-context-window). Utilizzate un valore inferiore come `500000` su un modello 1M per trattare la finestra come 500K ai fini della compattazione. Il valore è limitato alla finestra del contesto effettiva del modello. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` viene applicato come percentuale di questo valore. L'impostazione di questa variabile disaccoppia la soglia di compattazione dalla `used_percentage` della linea di stato, che utilizza sempre la finestra del contesto completa del modello |165| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Imposta la capacità del contesto in token utilizzata per i calcoli di compattazione automatica. Per impostazione predefinita, la finestra del contesto del modello: 200K per i modelli standard o 1M per i modelli con [contesto esteso](/it/model-config#extended-context), tranne su Sonnet 5, che ha la sua propria [soglia predefinita](/it/model-config#sonnet-5-context-window). Utilizzate un valore inferiore come `500000` su un modello 1M per trattare la finestra come 500K ai fini della compattazione. Il valore è limitato alla finestra del contesto effettiva del modello. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` viene applicato come percentuale di questo valore. L'impostazione di questa variabile disaccoppia la soglia di compattazione dalla `used_percentage` della linea di stato, che utilizza sempre la finestra del contesto completa del modello |

164| `CLAUDE_CODE_AUTO_CONNECT_IDE` | Sovrascrivi la [connessione IDE](/it/vs-code) automatica. Per impostazione predefinita, Claude Code si connette automaticamente quando avviato all'interno del terminale integrato di un IDE supportato. Imposta su `false` per impedire questo. Imposta su `true` per forzare un tentativo di connessione quando l'auto-rilevamento fallisce, ad esempio quando tmux oscura il terminale padre. Ha la precedenza sull'impostazione globale [`autoConnectIde`](/it/settings#global-config-settings) |166| `CLAUDE_CODE_AUTO_CONNECT_IDE` | Sovrascrivi la [connessione IDE](/it/vs-code) automatica. Per impostazione predefinita, Claude Code si connette automaticamente quando avviato all'interno del terminale integrato di un IDE supportato. Imposta su `false` per impedire questo. Imposta su `true` per forzare un tentativo di connessione quando l'auto-rilevamento fallisce, ad esempio quando tmux oscura il terminale padre. Ha la precedenza sull'impostazione globale [`autoConnectIde`](/it/settings#global-config-settings) |

167| `CLAUDE_CODE_BRIDGE_SESSION_ID` | {/* min-version: 2.1.199 */}Impostato automaticamente nel sottoprocesso dello strumento Bash e nel [comando hook](/it/hooks) mentre la sessione ha una connessione [Remote Control](/it/remote-control) attiva, e rimosso quando la connessione termina. Il valore è l'ID della sessione in forma `session_`, lo stesso identificatore che appare nell'URL `claude.ai/code` della sessione, quindi uno script può collegarsi di nuovo alla sessione che lo ha eseguito. Richiede Claude Code v2.1.199 o successivo. Nelle [sessioni cloud](/it/claude-code-on-the-web), leggete `CLAUDE_CODE_REMOTE_SESSION_ID` |

165| `CLAUDE_CODE_CERT_STORE` | Elenco separato da virgole di fonti di certificati CA per le connessioni TLS. `bundled` è il set Mozilla CA fornito con Claude Code. `system` è l'archivio di fiducia del sistema operativo, di sola lettura su runtime con `tls.getCACertificates`: il binario nativo, o Node 22.15 o successivo per installazioni npm. Vedi [Archivio certificati CA](/it/network-config#ca-certificate-store). Per impostazione predefinita è `bundled,system` |168| `CLAUDE_CODE_CERT_STORE` | Elenco separato da virgole di fonti di certificati CA per le connessioni TLS. `bundled` è il set Mozilla CA fornito con Claude Code. `system` è l'archivio di fiducia del sistema operativo, di sola lettura su runtime con `tls.getCACertificates`: il binario nativo, o Node 22.15 o successivo per installazioni npm. Vedi [Archivio certificati CA](/it/network-config#ca-certificate-store). Per impostazione predefinita è `bundled,system` |

166| `CLAUDE_CODE_CHILD_SESSION` | {/* min-version: 2.1.172 */}Imposta su `1` nei sottoprocessi che Claude Code genera tramite gli strumenti Bash, PowerShell e Monitor, i comandi [hook](/it/hooks) e i comandi della [linea di stato](/it/statusline). Non impostato per i sottoprocessi del server MCP [stdio](/it/mcp), che sono di lunga durata e sopravvivono alla sessione che li ha generati. A differenza di `CLAUDECODE`, questo viene impostato solo da Claude Code stesso quando avvia un sottoprocesso e non dalle estensioni IDE, quindi distingue in modo affidabile una sessione annidata da un `claude` di livello superiore avviato in un terminale integrato IDE. Una TUI `claude` interattiva annidata avviata in questo modo viene automaticamente esclusa da `--resume`, `--continue`, dalla cronologia della freccia su e dall'elenco `claude agents`. Le sessioni non interattive `claude -p` persistono comunque. Impostare `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` per sostituire questa esclusione. Richiede Claude Code v2.1.172 o successivo |169| `CLAUDE_CODE_CHILD_SESSION` | {/* min-version: 2.1.172 */}Imposta su `1` nei sottoprocessi che Claude Code genera tramite gli strumenti Bash, PowerShell e Monitor, i comandi [hook](/it/hooks) e i comandi della [linea di stato](/it/statusline). Non impostato per i sottoprocessi del server MCP [stdio](/it/mcp), che sono di lunga durata e sopravvivono alla sessione che li ha generati. A differenza di `CLAUDECODE`, questo viene impostato solo da Claude Code stesso quando avvia un sottoprocesso e non dalle estensioni IDE, quindi distingue in modo affidabile una sessione annidata da un `claude` di livello superiore avviato in un terminale integrato IDE. Una TUI `claude` interattiva annidata avviata in questo modo viene automaticamente esclusa da `--resume`, `--continue`, dalla cronologia della freccia su e dall'elenco `claude agents`. Le sessioni non interattive `claude -p` persistono comunque. Impostare `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` per sostituire questa esclusione. Richiede Claude Code v2.1.172 o successivo |

172| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | Livello di log minimo scritto nel file di log di debug. Valori: `verbose`, `debug` (predefinito), `info`, `warn`, `error`. Imposta su `verbose` per includere diagnostica ad alto volume come l'output completo del comando della linea di stato, o aumenta a `error` per ridurre il rumore |175| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | Livello di log minimo scritto nel file di log di debug. Valori: `verbose`, `debug` (predefinito), `info`, `warn`, `error`. Imposta su `verbose` per includere diagnostica ad alto volume come l'output completo del comando della linea di stato, o aumenta a `error` per ridurre il rumore |

173| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Imposta su `1` per disabilitare il supporto della [finestra del contesto 1M](/it/model-config#extended-context). Se impostato, le varianti del modello 1M non sono disponibili nel selettore di modelli, e le sessioni [Sonnet 5](/it/model-config#sonnet-5-context-window) vengono trattate come aventi una finestra di 200K. Utile per ambienti aziendali con requisiti di conformità |176| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Imposta su `1` per disabilitare il supporto della [finestra del contesto 1M](/it/model-config#extended-context). Se impostato, le varianti del modello 1M non sono disponibili nel selettore di modelli, e le sessioni [Sonnet 5](/it/model-config#sonnet-5-context-window) vengono trattate come aventi una finestra di 200K. Utile per ambienti aziendali con requisiti di conformità |

174| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Imposta su `1` per disabilitare il [ragionamento adattivo](/it/model-config#adjust-effort-level) su Opus 4.6 e Sonnet 4.6 e tornare al budget di thinking fisso controllato da `MAX_THINKING_TOKENS`. {/* min-version: 2.1.111 */}Da v2.1.111, non ha effetto su Fable 5, Sonnet 5 o Opus 4.7 e versioni successive, che utilizzano sempre il ragionamento adattivo |177| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Imposta su `1` per disabilitare il [ragionamento adattivo](/it/model-config#adjust-effort-level) su Opus 4.6 e Sonnet 4.6 e tornare al budget di thinking fisso controllato da `MAX_THINKING_TOKENS`. {/* min-version: 2.1.111 */}Da v2.1.111, non ha effetto su Fable 5, Sonnet 5 o Opus 4.7 e versioni successive, che utilizzano sempre il ragionamento adattivo |

175| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | {/* min-version: 2.1.98 */}Imposta su `1` per disabilitare lo [strumento advisor](/it/advisor). Il comando `/advisor` e il flag `--advisor` diventano non disponibili e qualsiasi `advisorModel` configurato viene ignorato. Richiede Claude Code v2.1.98 o successivo |178| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | {/* min-version: 2.1.98 */}Imposta su `1` per disabilitare lo [strumento advisor](/it/advisor). Il comando `/advisor` diventa non disponibile, qualsiasi `advisorModel` configurato viene ignorato e il flag `--advisor` viene accettato ma non ha effetto, quindi gli script esistenti che lo passano continuano a funzionare senza errori. Richiede Claude Code v2.1.98 o successivo |

176| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | Imposta su `1` per disattivare gli [agenti in background e la visualizzazione degli agenti](/it/agent-view): `claude agents`, `--bg`, `/background` e il supervisore su richiesta. Equivalente all'impostazione [`disableAgentView`](/it/settings#available-settings) |179| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | Imposta su `1` per disattivare gli [agenti in background e la visualizzazione degli agenti](/it/agent-view): `claude agents`, `--bg`, `/background` e il supervisore su richiesta. Equivalente all'impostazione [`disableAgentView`](/it/settings#available-settings) |

177| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | Imposta su `1` per disabilitare il [rendering a schermo intero](/it/fullscreen) e utilizzare il renderer della schermata principale classica. La conversazione rimane nello scrollback nativo del vostro terminale in modo che `Cmd+f` e la modalità di copia di tmux funzionino come al solito. Ha la precedenza su `CLAUDE_CODE_NO_FLICKER` e sull'impostazione [`tui`](/it/settings#available-settings). Potete anche passare con `/tui default`. Non si applica alle sessioni in background aperte dalla [visualizzazione degli agenti](/it/agent-view), che utilizzano sempre il rendering a schermo intero |180| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | Imposta su `1` per disabilitare il [rendering a schermo intero](/it/fullscreen) e utilizzare il renderer della schermata principale classica. La conversazione rimane nello scrollback nativo del vostro terminale in modo che `Cmd+f` e la modalità di copia di tmux funzionino come al solito. Ha la precedenza su `CLAUDE_CODE_NO_FLICKER` e sull'impostazione [`tui`](/it/settings#available-settings). Potete anche passare con `/tui default`. Non si applica alle sessioni in background aperte dalla [visualizzazione degli agenti](/it/agent-view), che utilizzano sempre il rendering a schermo intero |

178| `CLAUDE_CODE_DISABLE_ARTIFACT` | Imposta su `1` per disabilitare lo strumento [Artifact](/it/artifacts), che pubblica l'output della sessione come pagina web privata su claude.ai. Equivalente all'impostazione [`disableArtifact`](/it/settings#available-settings) |181| `CLAUDE_CODE_DISABLE_ARTIFACT` | Imposta su `1` per disabilitare lo strumento [Artifact](/it/artifacts), che pubblica l'output della sessione come pagina web privata su claude.ai. Equivalente all'impostazione [`disableArtifact`](/it/settings#available-settings) |

179| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | Imposta su `1` per disabilitare l'elaborazione degli allegati. Le menzioni di file con la sintassi `@` vengono inviate come testo semplice invece di essere espanse nel contenuto del file |182| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | Imposta su `1` per disabilitare l'elaborazione degli allegati. Le menzioni di file con la sintassi `@` vengono inviate come testo semplice invece di essere espanse nel contenuto del file |

180| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Imposta su `1` per disabilitare la [memoria automatica](/it/memory#auto-memory). Imposta su `0` per forzare la memoria automatica anche quando la modalità `--bare` o [`autoMemoryEnabled: false`](/it/settings#available-settings) altrimenti la disabiliterebbe. Quando disabilitato, Claude non crea o carica i file di memoria automatica |183| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Imposta su `1` per disabilitare la [memoria automatica](/it/memory#auto-memory). Imposta su `0` per forzare la memoria automatica anche quando la modalità `--bare` o [`autoMemoryEnabled: false`](/it/settings#available-settings) altrimenti la disabiliterebbe. Quando disabilitato, Claude non crea o carica i file di memoria automatica |

181| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Imposta su `1` per disabilitare tutta la funzionalità di attività in background, incluso il parametro `run_in_background` su strumenti Bash e subagent, auto-backgrounding e la scorciatoia Ctrl+B |184| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Imposta su `1` per disabilitare tutta la funzionalità di attività in background, incluso il parametro `run_in_background` su strumenti Bash e subagent, auto-backgrounding e la scorciatoia Ctrl+B |

182| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | {/* min-version: 2.1.196 */}Imposta su `1` per interrompere i comandi shell in background in esecuzione e i workflow dinamici di una [sessione in background](/it/agent-view) quando il [supervisore](/it/agent-view#the-supervisor-process) si ferma, si riavvia o aggiorna il processo di quella sessione, invece di trasferirli al processo successivo della sessione. Influisce solo su quel trasferimento: mettere una sessione in background con `←` o [`/background`](/it/agent-view#from-inside-a-session) continua a portare il lavoro in volo, e `CLAUDE_DISABLE_ADOPT` disattiva entrambi. Richiede Claude Code v2.1.196 o successivo |185| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | {/* min-version: 2.1.196 */}Imposta su `1` per interrompere i comandi shell in background in esecuzione, i workflow dinamici e, a partire da v2.1.198, i subagent in background di una [sessione in background](/it/agent-view) quando il [supervisore](/it/agent-view#the-supervisor-process) si ferma, si riavvia o aggiorna il processo di quella sessione, invece di trasferirli al processo successivo della sessione. Influisce solo su quel trasferimento: mettere una sessione in background con `←` o [`/background`](/it/agent-view#from-inside-a-session) continua a portare il lavoro in volo, e `CLAUDE_DISABLE_ADOPT` disattiva entrambi. Richiede Claude Code v2.1.196 o successivo |

183| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | {/* min-version: 2.1.193 */}Imposta su `1` per impedire a Claude Code di terminare i [comandi shell in background](/it/interactive-mode#background-bash-commands) quando il sistema operativo segnala pressione di memoria. Per impostazione predefinita, su macOS e Linux, Claude Code termina un shell in background avviato nella sessione principale su un segnale di pressione di memoria una volta che la sessione è stata inattiva per 30 minuti e nessun turno o subagent è in esecuzione. Windows non ha un segnale di pressione di memoria, quindi questa variabile non ha effetto lì. Richiede Claude Code v2.1.193 o successivo |186| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | {/* min-version: 2.1.193 */}Imposta su `1` per impedire a Claude Code di terminare i [comandi shell in background](/it/interactive-mode#background-bash-commands) quando il sistema operativo segnala pressione di memoria. Per impostazione predefinita, su macOS e Linux, Claude Code termina un shell in background avviato nella sessione principale su un segnale di pressione di memoria una volta che la sessione è stata inattiva per 30 minuti e nessun turno o subagent è in esecuzione. Windows non ha un segnale di pressione di memoria, quindi questa variabile non ha effetto lì. Richiede Claude Code v2.1.193 o successivo |

184| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Imposta su `1` per disabilitare le [skill](/it/skills) e i workflow che vengono forniti con Claude Code: le skill raggruppate e i workflow vengono rimossi completamente, mentre i comandi slash integrati come `/init` rimangono digitabili ma sono nascosti dal modello. Le skill dai plugin, `.claude/skills/` e `.claude/commands/` non sono interessate. Equivalente all'impostazione [`disableBundledSkills`](/it/settings#available-settings); `0` non la sostituisce |187| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Imposta su `1` per disabilitare le [skill](/it/skills) e i workflow che vengono forniti con Claude Code: le skill raggruppate e i workflow vengono rimossi completamente, mentre i comandi slash integrati come `/init` rimangono digitabili ma sono nascosti dal modello. Le skill dai plugin, `.claude/skills/` e `.claude/commands/` non sono interessate. Equivalente all'impostazione [`disableBundledSkills`](/it/settings#available-settings); `0` non la sostituisce |

185| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | Imposta su `1` per impedire il caricamento di qualsiasi file di memoria CLAUDE.md nel contesto, inclusi i file di utente, progetto e memoria automatica |188| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | Imposta su `1` per impedire il caricamento di qualsiasi file di memoria CLAUDE.md nel contesto, inclusi i file di utente, progetto e memoria automatica |

186| `CLAUDE_CODE_DISABLE_CRON` | Imposta su `1` per disabilitare le [attività pianificate](/it/scheduled-tasks). La skill `/loop` e gli strumenti cron diventano non disponibili e tutte le attività già pianificate smettono di attivarsi, incluse le attività già in esecuzione a metà sessione |189| `CLAUDE_CODE_DISABLE_CRON` | Imposta su `1` per disabilitare le [attività pianificate](/it/scheduled-tasks). La skill `/loop` e gli strumenti cron diventano non disponibili e tutte le attività già pianificate smettono di attivarsi, incluse le attività già in esecuzione a metà sessione |

187| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Imposta su `1` per rimuovere le intestazioni di richiesta `anthropic-beta` specifiche di Anthropic e i campi dello schema degli strumenti beta (come `defer_loading` e `eager_input_streaming`) dalle richieste API. Utilizza questo quando un gateway proxy rifiuta le richieste con errori come "Unexpected value(s) for the `anthropic-beta` header" o "Extra inputs are not permitted". I campi standard (`name`, `description`, `input_schema`, `cache_control`) vengono preservati |190| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Imposta su `1` per rimuovere le intestazioni di richiesta `anthropic-beta` specifiche di Anthropic e i campi dello schema degli strumenti beta (come `defer_loading` e `eager_input_streaming`) dalle richieste API. Utilizza questo quando un gateway proxy rifiuta le richieste con errori come "Unexpected value(s) for the `anthropic-beta` header" o "Extra inputs are not permitted". I campi standard (`name`, `description`, `input_schema`, `cache_control`) vengono preservati |

191| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | {/* min-version: 2.1.198 */}Imposta su `1` per disabilitare i [subagent Explore e Plan integrati](/it/sub-agents#built-in-subagents). Claude esplora con i suoi strumenti di ricerca o il subagent di uso generale, e la [modalità plan](/it/permission-modes#analyze-before-you-edit-with-plan-mode) legge i file direttamente piuttosto che lanciare agenti Explore e Plan. I subagent personalizzati denominati `Explore` o `Plan` non sono interessati. Per rimuovere ogni tipo di subagent integrato in Agent SDK o modalità non interattiva, utilizza `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`. Richiede Claude Code v2.1.198 o successivo |

189| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Imposta su `1` per disabilitare i sondaggi sulla qualità della sessione "Come sta andando Claude?". I sondaggi sono anche disabilitati quando `DISABLE_TELEMETRY`, `DO_NOT_TRACK` o `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` è impostato, a meno che `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` non opti di nuovo. Per impostare una frequenza di campionamento invece di disabilitare completamente, utilizzate l'impostazione [`feedbackSurveyRate`](/it/settings#available-settings). Vedi [Sondaggi sulla qualità della sessione](/it/data-usage#session-quality-surveys) |193| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Imposta su `1` per disabilitare i sondaggi sulla qualità della sessione "Come sta andando Claude?". I sondaggi sono anche disabilitati quando `DISABLE_TELEMETRY`, `DO_NOT_TRACK` o `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` è impostato, a meno che `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` non opti di nuovo. Per impostare una frequenza di campionamento invece di disabilitare completamente, utilizzate l'impostazione [`feedbackSurveyRate`](/it/settings#available-settings). Vedi [Sondaggi sulla qualità della sessione](/it/data-usage#session-quality-surveys) |

190| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | Imposta su `1` per disabilitare il [checkpointing](/it/checkpointing) dei file. Il comando `/rewind` non sarà in grado di ripristinare le modifiche al codice |194| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | Imposta su `1` per disabilitare il [checkpointing](/it/checkpointing) dei file. Il comando `/rewind` non sarà in grado di ripristinare le modifiche al codice |

226| `CLAUDE_CODE_GLOB_TIMEOUT_SECONDS` | Timeout in secondi per la scoperta dei file dello strumento Glob. Per impostazione predefinita 20 secondi sulla maggior parte delle piattaforme e 60 secondi su WSL |230| `CLAUDE_CODE_GLOB_TIMEOUT_SECONDS` | Timeout in secondi per la scoperta dei file dello strumento Glob. Per impostazione predefinita 20 secondi sulla maggior parte delle piattaforme e 60 secondi su WSL |

227| `CLAUDE_CODE_HIDE_CWD` | Imposta su `1` per nascondere la directory di lavoro nel logo di avvio. Utile per screenshare o registrazioni in cui il percorso espone il vostro nome utente del sistema operativo |231| `CLAUDE_CODE_HIDE_CWD` | Imposta su `1` per nascondere la directory di lavoro nel logo di avvio. Utile per screenshare o registrazioni in cui il percorso espone il vostro nome utente del sistema operativo |

228| `CLAUDE_CODE_IDE_HOST_OVERRIDE` | Sovrascrivi l'indirizzo host utilizzato per connettersi all'estensione IDE. Per impostazione predefinita Claude Code rileva automaticamente l'indirizzo corretto, incluso il routing WSL-to-Windows |232| `CLAUDE_CODE_IDE_HOST_OVERRIDE` | Sovrascrivi l'indirizzo host utilizzato per connettersi all'estensione IDE. Per impostazione predefinita Claude Code rileva automaticamente l'indirizzo corretto, incluso il routing WSL-to-Windows |

229| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Salta l'installazione automatica delle estensioni IDE. Equivalente all'impostazione di [`autoInstallIdeExtension`](/it/settings#global-config-settings) su `false` |233| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Imposta su `1` per saltare l'installazione automatica delle estensioni IDE. Equivalente all'impostazione di [`autoInstallIdeExtension`](/it/settings#global-config-settings) su `false` |

230| `CLAUDE_CODE_IDE_SKIP_VALID_CHECK` | Imposta su `1` per saltare la convalida delle voci del file di blocco IDE durante la connessione. Utilizza quando l'auto-connessione non riesce a trovare il vostro IDE nonostante sia in esecuzione |234| `CLAUDE_CODE_IDE_SKIP_VALID_CHECK` | Imposta su `1` per saltare la convalida delle voci del file di blocco IDE durante la connessione. Utilizza quando l'auto-connessione non riesce a trovare il vostro IDE nonostante sia in esecuzione |

231| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Sovrascrivi la dimensione della finestra del contesto che Claude Code assume per il modello attivo. {/* min-version: 2.1.193 */}A partire da v2.1.193, applicato direttamente per i nomi di modelli che Claude Code non riconosce come modello Claude; per i modelli Claude riconosciuti ha effetto solo quando `DISABLE_COMPACT` è anche impostato. Utilizza questo quando instrada a un modello attraverso `ANTHROPIC_BASE_URL` la cui finestra del contesto non corrisponde alla dimensione integrata per il suo nome |235| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Sovrascrivi la dimensione della finestra del contesto che Claude Code assume per il modello attivo. {/* min-version: 2.1.193 */}A partire da v2.1.193, applicato direttamente per i nomi di modelli che Claude Code non riconosce come modello Claude; per i modelli Claude riconosciuti ha effetto solo quando `DISABLE_COMPACT` è anche impostato. Utilizza questo quando instrada a un modello attraverso `ANTHROPIC_BASE_URL` la cui finestra del contesto non corrisponde alla dimensione integrata per il suo nome |

232| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Imposta il numero massimo di token di output per la maggior parte delle richieste. I valori predefiniti e massimi variano in base al modello; vedi [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison). L'aumento di questo valore riduce la finestra del contesto effettiva disponibile prima che venga attivata la [compattazione automatica](/it/costs#reduce-token-usage) |236| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Imposta il numero massimo di token di output per la maggior parte delle richieste. I valori predefiniti e massimi variano in base al modello; vedi [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison). L'aumento di questo valore riduce la finestra del contesto effettiva disponibile prima che venga attivata la [compattazione automatica](/it/costs#reduce-token-usage) |

233| `CLAUDE_CODE_MAX_RETRIES` | Sovrascrivi il numero di volte per riprovare le richieste API non riuscite (predefinito: 10). {/* min-version: 2.1.186 */}Limitato a 15 a partire da v2.1.186. Per sessioni non presidiate che devono attendere attraverso interruzioni più lunghe, imposta `CLAUDE_CODE_RETRY_WATCHDOG` |237| `CLAUDE_CODE_MAX_RETRIES` | Sovrascrivi il numero di volte per riprovare le richieste API non riuscite (predefinito: 10). {/* min-version: 2.1.186 */}Limitato a 15 a partire da v2.1.186; {/* min-version: 2.1.199 */}a partire da v2.1.199, `CLAUDE_CODE_RETRY_WATCHDOG` aumenta il valore predefinito e rimuove il limite. Per sessioni non presidiate che devono attendere attraverso interruzioni più lunghe, imposta `CLAUDE_CODE_RETRY_WATCHDOG` |

234| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | Numero massimo di strumenti di sola lettura e subagent che possono essere eseguiti in parallelo (predefinito: 10). Valori più alti aumentano il parallelismo ma consumano più risorse |238| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | Numero massimo di strumenti di sola lettura e subagent che possono essere eseguiti in parallelo (predefinito: 10). Valori più alti aumentano il parallelismo ma consumano più risorse |

235| `CLAUDE_CODE_MAX_TURNS` | Limita il numero di turni agentici quando non viene passato un limite esplicito. Equivalente a passare [`--max-turns`](/it/cli-reference#cli-flags), che ha la precedenza quando entrambi sono impostati. Un valore che non è un intero positivo viene rifiutato all'avvio con un errore piuttosto che trattato come nessun limite |239| `CLAUDE_CODE_MAX_TURNS` | Limita il numero di turni agentici quando non viene passato un limite esplicito. Equivalente a passare [`--max-turns`](/it/cli-reference#cli-flags), che ha la precedenza quando entrambi sono impostati. Un valore che non è un intero positivo viene rifiutato all'avvio con un errore piuttosto che trattato come nessun limite |

236| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | Imposta su `1` per generare server MCP stdio con solo un ambiente di base sicuro più il `env` configurato del server, invece di ereditare l'ambiente della vostra shell |240| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | Imposta su `1` per generare server MCP stdio con solo un ambiente di base sicuro più il `env` configurato del server, invece di ereditare l'ambiente della vostra shell |

262| `CLAUDE_CODE_REMOTE_SESSION_ID` | Impostato automaticamente nelle [sessioni cloud](/it/claude-code-on-the-web) all'ID della sessione corrente. Leggete questo per costruire un collegamento alla trascrizione della sessione. Vedi [Collegare l'output alla sessione](/it/claude-code-on-the-web#link-output-back-to-the-session) |266| `CLAUDE_CODE_REMOTE_SESSION_ID` | Impostato automaticamente nelle [sessioni cloud](/it/claude-code-on-the-web) all'ID della sessione corrente. Leggete questo per costruire un collegamento alla trascrizione della sessione. Vedi [Collegare l'output alla sessione](/it/claude-code-on-the-web#link-output-back-to-the-session) |

263| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | Imposta su `1` per riprendere automaticamente se la sessione precedente è terminata a metà turno. Utilizzato in modalità SDK in modo che il modello continui senza richiedere all'SDK di reinviare il prompt |267| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | Imposta su `1` per riprendere automaticamente se la sessione precedente è terminata a metà turno. Utilizzato in modalità SDK in modo che il modello continui senza richiedere all'SDK di reinviare il prompt |

264| `CLAUDE_CODE_RESUME_PROMPT` | Sovrascrivi il messaggio di continuazione iniettato quando si riprende una sessione che è terminata a metà turno. Per impostazione predefinita `Continue from where you left off.`. Gli script di spawn per agenti a lunga esecuzione possono impostare questo su un messaggio di avvio più direttivo. Una stringa vuota utilizza il valore predefinito |268| `CLAUDE_CODE_RESUME_PROMPT` | Sovrascrivi il messaggio di continuazione iniettato quando si riprende una sessione che è terminata a metà turno. Per impostazione predefinita `Continue from where you left off.`. Gli script di spawn per agenti a lunga esecuzione possono impostare questo su un messaggio di avvio più direttivo. Una stringa vuota utilizza il valore predefinito |

265| `CLAUDE_CODE_RETRY_WATCHDOG` | {/* min-version: 2.1.186 */}Imposta su `1` per sessioni non presidiate come harness di valutazione, lavori CI o worker remoti. Ritenta gli errori di capacità `429` e `529` indefinitamente invece di fallire dopo i tentativi di `CLAUDE_CODE_MAX_RETRIES`. Il watchdog si ritira fino a 5 minuti tra i tentativi, o fino a quando il limite si ripristina quando la risposta porta un tempo di ripristino del limite di velocità, quindi una sessione che raggiunge un limite di utilizzo attende la finestra rimanente. Richiede Claude Code v2.1.186 o successivo |269| `CLAUDE_CODE_RETRY_WATCHDOG` | {/* min-version: 2.1.186 */}Imposta su `1` per sessioni non presidiate come harness di valutazione, lavori CI o worker remoti. Ritenta gli errori di capacità `429` e `529` indefinitamente invece di fallire dopo i tentativi di `CLAUDE_CODE_MAX_RETRIES`. Il watchdog si ritira fino a 5 minuti tra i tentativi, o fino a quando il limite si ripristina quando la risposta porta un tempo di ripristino del limite di velocità, quindi una sessione che raggiunge un limite di utilizzo attende la finestra rimanente. {/* min-version: 2.1.199 */}A partire da v2.1.199 aumenta anche il conteggio dei retry predefiniti per altri errori transitori, come errori del server, timeout e connessioni interrotte, a 300, approssimativamente tre ore di backoff, e rimuove il limite di 15 su `CLAUDE_CODE_MAX_RETRIES` se impostate esplicitamente quella variabile. Richiede Claude Code v2.1.186 o successivo |

266| `CLAUDE_CODE_SAFE_MODE` | Imposta su `1` per avviare in modalità sicura: CLAUDE.md, skill, plugin, hook, server MCP, comandi personalizzati e agenti, stili di output, workflow, temi personalizzati, scorciatoie da tastiera personalizzate, comandi della linea di stato e dei suggerimenti di file, server LSP e memoria automatica non vengono caricati, per la risoluzione dei problemi di una configurazione interrotta. La politica delle impostazioni gestite si applica comunque, inclusi hook, linea di stato e comandi dei suggerimenti di file configurati dalla politica; plugin gestiti, skill gestite, CLAUDE.md gestito e server MCP configurati dalla politica non lo fanno. Equivalente a passare [`--safe-mode`](/it/cli-reference#cli-flags). I processi figlio direttamente generati ereditano la variabile |270| `CLAUDE_CODE_SAFE_MODE` | Imposta su `1` per avviare in modalità sicura: CLAUDE.md, skill, plugin, hook, server MCP, comandi personalizzati e agenti, stili di output, workflow, temi personalizzati, scorciatoie da tastiera personalizzate, comandi della linea di stato e dei suggerimenti di file, server LSP e memoria automatica non vengono caricati, per la risoluzione dei problemi di una configurazione interrotta. La politica delle impostazioni gestite si applica comunque, inclusi hook, linea di stato e comandi dei suggerimenti di file configurati dalla politica; plugin gestiti, skill gestite, CLAUDE.md gestito e server MCP configurati dalla politica non lo fanno. Equivalente a passare [`--safe-mode`](/it/cli-reference#cli-flags). I processi figlio direttamente generati ereditano la variabile |

267| `CLAUDE_CODE_SCRIPT_CAPS` | Oggetto JSON che limita quante volte script specifici possono essere richiamati per sessione quando `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` è impostato. Le chiavi sono sottostringhe abbinate al testo del comando; i valori sono limiti di chiamate intere. Ad esempio, `{"deploy.sh": 2}` consente a `deploy.sh` di essere chiamato al massimo due volte. L'abbinamento è basato su sottostringhe quindi trucchi di espansione della shell come `./scripts/deploy.sh $(evil)` contano comunque rispetto al limite. Il fan-out di runtime tramite `xargs` o `find -exec` non viene rilevato; questo è un controllo di difesa in profondità |271| `CLAUDE_CODE_SCRIPT_CAPS` | Oggetto JSON che limita quante volte script specifici possono essere richiamati per sessione quando `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` è impostato. Le chiavi sono sottostringhe abbinate al testo del comando; i valori sono limiti di chiamate intere. Ad esempio, `{"deploy.sh": 2}` consente a `deploy.sh` di essere chiamato al massimo due volte. L'abbinamento è basato su sottostringhe quindi trucchi di espansione della shell come `./scripts/deploy.sh $(evil)` contano comunque rispetto al limite. Il fan-out di runtime tramite `xargs` o `find -exec` non viene rilevato; questo è un controllo di difesa in profondità |

268| `CLAUDE_CODE_SCROLL_SPEED` | Imposta il moltiplicatore di scorrimento della rotella del mouse nel [rendering a schermo intero](/it/fullscreen#mouse-wheel-scrolling). Accetta valori da 1 a 20 e valori frazionari inferiori a 1 come `0.5` per rallentare lo scorrimento accelerato del trackpad e della rotella nei terminali che già amplificano gli eventi della rotella. Imposta su `3` per corrispondere a `vim` se il vostro terminale invia un evento di rotella per tacca senza amplificazione. Ignorato nel terminale IDE JetBrains, dove Claude Code utilizza il proprio gestore di scorrimento |272| `CLAUDE_CODE_SCROLL_SPEED` | Imposta il moltiplicatore di scorrimento della rotella del mouse nel [rendering a schermo intero](/it/fullscreen#mouse-wheel-scrolling). Accetta valori da 1 a 20 e valori frazionari inferiori a 1 come `0.5` per rallentare lo scorrimento accelerato del trackpad e della rotella nei terminali che già amplificano gli eventi della rotella. Imposta su `3` per corrispondere a `vim` se il vostro terminale invia un evento di rotella per tacca senza amplificazione. Ignorato nel terminale IDE JetBrains, dove Claude Code utilizza il proprio gestore di scorrimento |

errors.md +148 −16

Details

27| `Request timed out` | [Errori del server](#request-timed-out), o [Rete](#unable-to-connect-to-api) se il messaggio menziona la tua connessione internet |27| `Request timed out` | [Errori del server](#request-timed-out), o [Rete](#unable-to-connect-to-api) se il messaggio menziona la tua connessione internet |

28| `Server error mid-response. The response above may be incomplete.` | [Errori del server](#the-response-above-may-be-incomplete) |

29| `Connection closed mid-response` / `Response stalled mid-stream` | [Errori del server](#the-response-above-may-be-incomplete) |

28| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [Errori del server](#auto-mode-cannot-determine-the-safety-of-an-action) |30| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [Errori del server](#auto-mode-cannot-determine-the-safety-of-an-action) |

29| `Auto mode could not evaluate this action and is blocking it for safety` | [Errori del server](#auto-mode-cannot-determine-the-safety-of-an-action) |31| `Auto mode could not evaluate this action and is blocking it for safety` | [Errori del server](#auto-mode-cannot-determine-the-safety-of-an-action) |

30| `Auto mode classifier transcript exceeded context window` | [Errori del server](#auto-mode-cannot-determine-the-safety-of-an-action) |32| `Auto mode classifier transcript exceeded context window` | [Errori del server](#auto-mode-cannot-determine-the-safety-of-an-action) |

33| `Agent terminated early due to an API error` | [Errori del server](#agent-terminated-early-due-to-an-api-error) |

31| `You've hit your session limit` / `You've hit your weekly limit` | [Limiti di utilizzo](#you%E2%80%99ve-hit-your-session-limit) |34| `You've hit your session limit` / `You've hit your weekly limit` | [Limiti di utilizzo](#you%E2%80%99ve-hit-your-session-limit) |

43| `Remote Control is only available when using Claude via api.anthropic.com` | [Autenticazione](#remote-control-requires-the-anthropic-api) |46| `Remote Control is only available when using Claude via api.anthropic.com` | [Autenticazione](#remote-control-requires-the-anthropic-api) |

49| `AWS credentials expired or invalid` | [Autenticazione](#aws-credentials-expired-or-invalid) |

50| `AWS authentication failed` | [Autenticazione](#aws-authentication-failed) |

47| `Waiting for API response · will retry in` | [Tentativi automatici](#automatic-retries), o [Rete](#unable-to-connect-to-api) se persiste |52| `Waiting for API response · will retry in` | [Tentativi automatici](#automatic-retries), o [Rete](#unable-to-connect-to-api) se persiste |

55| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [Rete](#host-not-allowed-in-a-cloud-session) |

63| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [Errori di richiesta](#usage-policy-refusal) |69| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [Errori di richiesta](#usage-policy-refusal) |

71| Responses seem lower quality than usual | [Qualità della risposta](#responses-seem-lower-quality-than-usual) |

65 72

66<h2 id="automatic-retries">73<h2 id="automatic-retries">

67 Tentativi automatici74 Tentativi automatici

68</h2>75</h2>

69 76

70Claude Code ritenta i guasti transitori prima di mostrarti un errore. Gli errori del server, le risposte sovraccariche, i timeout delle richieste, i throttle 429 temporanei e le connessioni interrotte vengono tutti ritentati fino a 10 volte con backoff esponenziale. Durante il tentativo, lo spinner mostra un countdown `Retrying in Ns · attempt x/y`.77Claude Code ritenta i guasti transitori prima di mostrarti un errore. Gli errori del server, le risposte sovraccariche, i timeout delle richieste, i throttle 429 temporanei e le connessioni interrotte vengono tutti ritentati fino a 10 volte con backoff esponenziale. {/* min-version: 2.1.198 */}A partire da v2.1.198, questo copre le connessioni che si interrompono nel mezzo di una risposta prima che qualsiasi output visibile sia stato trasmesso: Claude Code ri-emette la richiesta con lo stesso backoff e il turno continua invece di fermarsi con un errore di connessione. {/* min-version: 2.1.199 */}A partire da v2.1.199, i throttle 429 temporanei che non portano le intestazioni di quota del tuo piano vengono anche ritentati quando sei connesso con un abbonamento claude.ai; le versioni precedenti li ritentavano solo per le chiavi API e gli accessi Enterprise.

79Due classi di guasti non vengono ritentate, perché un tentativo non può avere successo:

81* {/* min-version: 2.1.199 */}A partire da v2.1.199, un guasto di convalida del certificato TLS, come un proxy che ispeziona TLS, un bundle `NODE_EXTRA_CA_CERTS` mancante, o un certificato scaduto, fallisce al primo tentativo in modo che la correzione appaia immediatamente invece che dopo il budget di tentativo completo. Vedi [Errori del certificato SSL](#ssl-certificate-errors). Le condizioni TLS transitorie come un timeout di handshake continuano a ritentare.

82* {/* min-version: 2.1.199 */}A partire da v2.1.199, un errore del server che arriva dopo che Claude ha già trasmesso output visibile mantiene la risposta parziale e aggiunge un [avviso di risposta incompleta](#the-response-above-may-be-incomplete) invece di ritentare, poiché ri-eseguire la richiesta potrebbe eseguire le stesse chiamate di strumento due volte. Le versioni precedenti scartavano l'output parziale e segnalano il turno come un errore.

84Durante il tentativo, lo spinner mostra un countdown `Retrying in Ns · attempt x/y` dopo un'etichetta di errore. L'etichetta nomina il motivo specifico dal primo tentativo per i guasti su cui puoi agire subito: la rete è inattiva, un handshake TLS non è riuscito, o hai raggiunto un limite di velocità. Per altri errori legge `API error` all'inizio. {/* min-version: 2.1.198 */}A partire da v2.1.198 passa al motivo specifico dal terzo tentativo, o al tentativo finale quando `CLAUDE_CODE_MAX_RETRIES` consente meno di tre; le versioni precedenti passano solo al tentativo finale.

86{/* min-version: 2.1.198 */}A partire da v2.1.198, il suggerimento dello spinner usuale è soppresso durante i tentativi. Una volta rivelato il motivo dell'errore, se il guasto è un sovraccarico 529 la riga sotto il countdown nomina anche dove controllare lo stato del servizio: `status.claude.com` sull'API Anthropic, o l'host del provider o gateway indicato nel messaggio su altre configurazioni.

71 87

72{/* min-version: 2.1.185 */}Se nessun dato arriva sul flusso di risposta per 20 secondi mentre una richiesta è ancora in sospeso, lo spinner mostra `Waiting for API response · will retry in … · check your network` prima che qualsiasi tentativo sia iniziato. La richiesta non è ancora fallita: il countdown viene eseguito fino al punto in cui Claude Code interrompe la connessione bloccata e ritenta, quindi il banner si cancella da solo una volta che i dati riprendono o il tentativo ha successo. A partire da v2.1.185 la soglia è di 20 secondi; le versioni precedenti mostrano il banner dopo 10 secondi con una formulazione diversa. Se riappare ad ogni tentativo, trattalo come un [problema di rete](#unable-to-connect-to-api).88{/* min-version: 2.1.185 */}Se nessun dato arriva sul flusso di risposta per 20 secondi mentre una richiesta è ancora in sospeso, lo spinner mostra `Waiting for API response · will retry in … · check your network` prima che qualsiasi tentativo sia iniziato. La richiesta non è ancora fallita: il countdown viene eseguito fino al punto in cui Claude Code interrompe la connessione bloccata e ritenta, quindi il banner si cancella da solo una volta che i dati riprendono o il tentativo ha successo. A partire da v2.1.185 la soglia è di 20 secondi; le versioni precedenti mostrano il banner dopo 10 secondi con una formulazione diversa. Se riappare ad ogni tentativo, trattalo come un [problema di rete](#unable-to-connect-to-api).

73 89

~~74Quando vedi uno degli errori in questa pagina, quei tentativi sono già stati esauriti. Puoi regolare il comportamento con queste variabili di ambiente:~~90Quando vedi uno degli errori in questa pagina, quei tentativi sono già stati esauriti, a meno che non appartenga a una classe che non viene ritentata, come un guasto di convalida del certificato. Puoi regolare il comportamento con queste variabili di ambiente:

75 91

77| :------------------------------------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |93| :------------------------------------------- | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

78| [`CLAUDE_CODE_MAX_RETRIES`](/it/env-vars) | 10 | Numero di tentativi di ripetizione. {/* min-version: 2.1.186 */}Limitato a 15 a partire da v2.1.186. Abbassalo per far emergere i guasti più velocemente negli script. |94| [`CLAUDE_CODE_MAX_RETRIES`](/it/env-vars) | 10 | Numero di tentativi di ripetizione. {/* min-version: 2.1.186 */}Limitato a 15 a partire da v2.1.186; {/* min-version: 2.1.199 */}a partire da v2.1.199 `CLAUDE_CODE_RETRY_WATCHDOG` aumenta il valore predefinito e rimuove il limite. Abbassalo per far emergere i guasti più velocemente negli script. |

79| [`CLAUDE_CODE_RETRY_WATCHDOG`](/it/env-vars) | non impostato | Impostalo su `1` in sessioni incustodite come i job CI per ritentare gli errori di capacità `429` e `529` indefinitamente invece di fallire dopo i tentativi di `CLAUDE_CODE_MAX_RETRIES`. |95| [`CLAUDE_CODE_RETRY_WATCHDOG`](/it/env-vars) | non impostato | Impostalo su `1` in sessioni incustodite come i job CI per ritentare gli errori di capacità `429` e `529` indefinitamente invece di fallire dopo i tentativi di `CLAUDE_CODE_MAX_RETRIES`. {/* min-version: 2.1.199 */}A partire da v2.1.199 aumenta anche il conteggio di tentativi predefinito per altri errori transitori, come errori del server, timeout e connessioni interrotte, a 300, approssimativamente tre ore di backoff, e rimuove il limite di 15 su `CLAUDE_CODE_MAX_RETRIES` se imposti esplicitamente quella variabile. |

80| [`API_TIMEOUT_MS`](/it/env-vars) | 600000 | Timeout per richiesta in millisecondi. Aumentalo per reti lente o proxy. |96| [`API_TIMEOUT_MS`](/it/env-vars) | 600000 | Timeout per richiesta in millisecondi. Aumentalo per reti lente o proxy. |

81 97

82<h2 id="server-errors">98<h2 id="server-errors">

115API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.131API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

116```132```

117 133

118La frase finale varia in base al provider nello stesso modo dell'errore 500 sopra. Un 529 non è il tuo limite di utilizzo e non conta rispetto alla tua quota.134La frase finale varia in base al provider nello stesso modo dell'errore 500 sopra.

135

136Un 529 non è il tuo limite di utilizzo e non conta rispetto alla tua quota.

119 137

120**Cosa fare:**138**Cosa fare:**

121 139

133Request timed out151Request timed out

134```152```

135 153

136Questo può accadere durante periodi di carico elevato o quando viene generata una risposta molto grande. Il timeout della richiesta predefinito è di 10 minuti.154Questo può accadere durante periodi di carico elevato o quando il modello sta generando una risposta molto grande. Il timeout della richiesta predefinito è di 10 minuti.

137 155

138**Cosa fare:**156**Cosa fare:**

139 157

142* Se una rete lenta o un proxy è la causa, aumenta `API_TIMEOUT_MS` come descritto in [Tentativi automatici](#automatic-retries)160* Se una rete lenta o un proxy è la causa, aumenta `API_TIMEOUT_MS` come descritto in [Tentativi automatici](#automatic-retries)

143* Se i timeout sono frequenti e la tua rete è altrimenti sana, vedi [Errori di rete e connessione](#network-and-connection-errors) sottostante161* Se i timeout sono frequenti e la tua rete è altrimenti sana, vedi [Errori di rete e connessione](#network-and-connection-errors) sottostante

144 162

163<h3 id="the-response-above-may-be-incomplete">

164 The response above may be incomplete

165</h3>

166

167Una risposta in streaming non è riuscita dopo che Claude aveva già prodotto output visibile. Ri-inviare la richiesta potrebbe eseguire le stesse chiamate di strumento due volte, quindi Claude Code mantiene ciò che è già stato trasmesso e aggiunge questo avviso invece di scartare il turno. Quale variante vedi nomina la causa:

168

169```text theme={null}

170API Error: Server error mid-response. The response above may be incomplete.

171API Error: Connection closed mid-response. The response above may be incomplete.

172API Error: Response stalled mid-stream. The response above may be incomplete.

173```

174

175* {/* min-version: 2.1.199 */}}`Server error mid-response`: un errore del server sovraccarico o 5xx a metà flusso. Questa variante richiede Claude Code v2.1.199 o successivo; prima di allora quel caso scartava l'output parziale e segnalava l'intero turno come un errore.

176* `Connection closed mid-response`: la connessione è stata interrotta.

177* `Response stalled mid-stream`: il flusso ha smesso di inviare dati.

178

179**Cosa fare:**

180

181* Leggi la risposta che è stata trasmessa. Nulla è stato perso, ma le frasi finali o le chiamate di strumento potrebbero mancare.

182* Rispondi con `continue` per far sì che Claude riprenda da dove si è fermato

183* Se lo stesso errore appare prima di qualsiasi output visibile, Claude Code ritenta la richiesta invece di finalizzarla. Vedi [Tentativi automatici](#automatic-retries).

184

145<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">185<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">

146 Auto mode cannot determine the safety of an action186 Auto mode cannot determine the safety of an action

147</h3>187</h3>

198* Approva o nega l'azione nel prompt che appare238* Approva o nega l'azione nel prompt che appare

199* Esegui `/compact` per ridurre la dimensione della conversazione in modo che le azioni successive si adattino di nuovo alla finestra del classificatore239* Esegui `/compact` per ridurre la dimensione della conversazione in modo che le azioni successive si adattino di nuovo alla finestra del classificatore

200 240

241<h3 id="agent-terminated-early-due-to-an-api-error">

242 Agent terminated early due to an API error

243</h3>

244

245{/* min-version: 2.1.199 */}La richiesta API di un [subagent](/it/sub-agents) non è riuscita terminalmente, ad esempio perché è stato raggiunto un limite di utilizzo o i tentativi per un errore del server sono esauriti, quindi il subagent si è fermato prima di completare il suo compito. Questo messaggio richiede Claude Code v2.1.199 o successivo; prima di allora il testo di errore dell'API veniva restituito a Claude come se fosse il risultato del subagent.

246

247```text theme={null}

248Agent terminated early due to an API error: <error detail>

249```

250

251**Cosa fare:**

252

253* Abbina il dettaglio dell'errore dopo i due punti alla sua sezione in questa pagina, come [Limiti di utilizzo](#usage-limits) o [Errori del server](#server-errors), e segui i passaggi di quella sezione

254* Una volta che l'errore sottostante si cancella, chiedi a Claude di ritentare il compito o [riprendere il subagent](/it/sub-agents#resume-subagents)

255

256Quando un limite di velocità, sovraccarico o errore del server interrompe un subagent in primo piano che ha già prodotto output, Claude riceve quell'output parziale contrassegnato come incompleto invece di questo errore. Vedi [Errori API nei subagent](/it/sub-agents#api-errors-in-subagents).

257

201<h2 id="usage-limits">258<h2 id="usage-limits">

202 Limiti di utilizzo259 Limiti di utilizzo

203</h2>260</h2>

258API Error: Server is temporarily limiting requests (not your usage limit)315API Error: Server is temporarily limiting requests (not your usage limit)

259```316```

260 317

261Questo viene [ritentato automaticamente](#automatic-retries) prima di essere mostrato.318Claude Code distingue questi dai tuoi limiti di piano dall'assenza delle intestazioni di quota unificate che una risposta di limite reale porta. {/* min-version: 2.1.199 */}A partire da v2.1.199 questo viene [ritentato automaticamente](#automatic-retries) con backoff prima di essere mostrato, indipendentemente da come ti autentichi. Nelle versioni precedenti, una sessione connessa con un abbonamento claude.ai non è riuscita al turno alla prima occorrenza; solo le chiavi API e gli accessi Enterprise lo ritentavano.

262 319

263**Cosa fare:**320**Cosa fare:**

264 321

321* Esegui `/login` per autenticarti con il tuo abbonamento Claude o account Console378* Esegui `/login` per autenticarti con il tuo abbonamento Claude o account Console

322* Se ti aspettavi che una variabile di ambiente ti autenticasse, conferma che `ANTHROPIC_API_KEY` è impostato ed esportato nella shell in cui hai lanciato `claude`379* Se ti aspettavi che una variabile di ambiente ti autenticasse, conferma che `ANTHROPIC_API_KEY` è impostato ed esportato nella shell in cui hai lanciato `claude`

323* Per CI o automazione in cui l'accesso interattivo non è possibile, configura uno script [`apiKeyHelper`](/it/settings#available-settings) che recupera una chiave all'avvio380* Per CI o automazione in cui l'accesso interattivo non è possibile, configura uno script [`apiKeyHelper`](/it/settings#available-settings) che recupera una chiave all'avvio

324* Vedi [Authentication precedence](/it/authentication#authentication-precedence) per capire quale credenziale vince quando sono presenti più credenziali381* Vedi [Authentication precedence](/it/authentication#authentication-precedence) per capire quale credenziale Claude Code utilizza quando sono presenti più credenziali

325 382

326Se ti viene chiesto di accedere ripetutamente, vedi [Not logged in or token expired](/it/troubleshoot-install#not-logged-in-or-token-expired) per le correzioni dell'orologio di sistema e del Keychain di macOS.383Se ti viene chiesto di accedere ripetutamente, vedi [Not logged in or token expired](/it/troubleshoot-install#not-logged-in-or-token-expired) per le correzioni dell'orologio di sistema e del Keychain di macOS.

327 384

414Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access471Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

415```472```

416 473

417Questa è un'impostazione organizzativa lato server, quindi non può essere sovrascritta dalle impostazioni locali, dalle variabili di ambiente o dai flag CLI. L'Agent SDK e la modalità non interattiva `-p` presentano questo come il codice di errore `oauth_org_not_allowed`.474Questa è un'impostazione organizzativa lato server, quindi non può essere sovrascritta dalle impostazioni locali, dalle variabili di ambiente o dai flag CLI.

475

476L'Agent SDK e la modalità non interattiva `-p` presentano questo come il codice di errore `oauth_org_not_allowed`.

418 477

419**Cosa fare:**478**Cosa fare:**

420 479

426 Routines are disabled by your organization's policy485 Routines are disabled by your organization's policy

427</h3>486</h3>

428 487

429L'amministratore del tuo Team o Enterprise ha disattivato le routine a livello organizzativo. L'errore appare quando tenti di creare o eseguire una routine, incluso da `/schedule` e dall'interfaccia utente [Routines](/it/routines) su claude.ai/code.488Un Owner nella tua organizzazione Team o Enterprise ha disattivato le routine a livello organizzativo. L'errore appare quando tenti di creare o eseguire una routine, incluso da `/schedule` e dall'interfaccia utente [Routines](/it/routines) su claude.ai/code.

430 489

431```text theme={null}490```text theme={null}

432Routines are disabled by your organization's policy.491Routines are disabled by your organization's policy.

436 495

437**Cosa fare:**496**Cosa fare:**

438 497

439* Chiedi al tuo amministratore di abilitare l'interruttore **Routines** su [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)498* Chiedi a un Owner nella tua organizzazione di abilitare l'interruttore **Routines** su [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)

440* Per lavori programmati una tantum che non richiedono routine a livello organizzativo, vedi [scheduled tasks](/it/scheduled-tasks)499* Per lavori programmati una tantum che non richiedono routine a livello organizzativo, vedi [scheduled tasks](/it/scheduled-tasks)

441 500

442<h3 id="remote-control-requires-the-anthropic-api">501<h3 id="remote-control-requires-the-anthropic-api">

489 548

490* Esegui `/login` per creare un nuovo token con gli ambiti attuali. Non è necessario effettuare il logout prima.549* Esegui `/login` per creare un nuovo token con gli ambiti attuali. Non è necessario effettuare il logout prima.

491 550

551<h3 id="aws-credentials-expired-or-invalid">

552 AWS credentials expired or invalid

553</h3>

554

555{/* min-version: 2.1.198 */}Questo messaggio richiede Claude Code v2.1.198 o successivo e appare solo quando [`awsAuthRefresh`](/it/amazon-bedrock#advanced-credential-configuration) è impostato nel tuo file di impostazioni. Il tuo token di sessione AWS è scaduto o è stato rifiutato, e l'aggiornamento automatico che Claude Code ha già eseguito non ha prodotto una credenziale che l'API accetta. Appare su un 401 da [Claude Platform on AWS](/it/claude-platform-on-aws) o dall'[endpoint Mantle](/it/amazon-bedrock#use-the-mantle-endpoint), che è come questi provider segnalano un token di sicurezza scaduto.

556

557L'hint di azione nel mezzo nomina il comando `awsAuthRefresh` dalle tue impostazioni, quindi varia. La parte stabile è il `AWS credentials expired or invalid` iniziale:

558

559```text theme={null}

560AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...

561```

562

563Senza `awsAuthRefresh` configurato, lo stesso 401 mostra il messaggio generico `Please run /login` invece, che non può aggiornare le credenziali AWS.

564

565**Cosa fare:**

566

567* Esegui il comando `awsAuthRefresh` indicato nel messaggio, come `aws sso login --profile myprofile`, in un altro terminale e completa l'accesso del browser, quindi ritenta

568* In una sessione interattiva, esegui `/login`, scegli **3rd-party platform**, quindi seleziona **Claude Platform on AWS · refresh credentials** sotto **Using 3rd-party platforms** per eseguire lo stesso comando senza riavviare Claude Code. Vedi [Configure AWS credentials](/it/claude-platform-on-aws#1-configure-aws-credentials)

569* Se l'errore si ripete dopo che il comando di aggiornamento ha successo, conferma che l'identità è valida al di fuori di Claude Code con `aws sts get-caller-identity` nella stessa shell e profilo

570

571<h3 id="aws-authentication-failed">

572 AWS authentication failed

573</h3>

574

575{/* min-version: 2.1.198 */}Questo messaggio richiede Claude Code v2.1.198 o successivo e appare solo quando [`awsAuthRefresh`](/it/amazon-bedrock#advanced-credential-configuration) è impostato nel tuo file di impostazioni. Il tuo provider AWS ha restituito un 403, o [Amazon Bedrock](/it/amazon-bedrock) ha restituito un 401.

576

577Claude Code non può dire quale causa hai colpito. Amazon Bedrock segnala un token di sicurezza scaduto come 403, ma un 403 è anche come segnala un rifiuto di autorizzazione, come un `AccessDeniedException` da un'autorizzazione IAM mancante o un modello che non è abilitato per il tuo account.

578

579Un 401 da Amazon Bedrock atterra anche qui piuttosto che sotto [AWS credentials expired or invalid](#aws-credentials-expired-or-invalid), perché Bedrock non segnala un token scaduto come 401. Un 401 da quell'endpoint di solito proviene da qualcos'altro nel percorso della richiesta, come un proxy aziendale.

580

581Un aggiornamento delle credenziali corregge un token scaduto e non può correggere le altre cause, quindi il messaggio offre entrambi:

582

583```text theme={null}

584AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...

585```

586

587L'hint di azione nel mezzo nomina il comando `awsAuthRefresh` dalle tue impostazioni, quindi varia. La parte stabile è il `AWS authentication failed` iniziale.

588

589**Cosa fare:**

590

591* Esegui il comando `awsAuthRefresh` indicato nel messaggio, o `aws sso login`, nel caso in cui una credenziale scaduta sia la causa

592* Se le tue credenziali sono attuali, conferma che le autorizzazioni IAM in [IAM configuration](/it/amazon-bedrock#iam-configuration) sono allegate all'identità che stai utilizzando e che il modello selezionato è abilitato per il tuo account e la tua regione

593* Esegui `aws sts get-caller-identity` per confermare quale identità le tue richieste utilizzano; un `AWS_PROFILE` obsoleto o un profilo predefinito è una causa comune di una mancata corrispondenza di autorizzazione

594

492<h2 id="network-and-connection-errors">595<h2 id="network-and-connection-errors">

493 Errori di rete e connessione596 Errori di rete e connessione

494</h2>597</h2>

537Unable to connect to API: Self-signed certificate detected640Unable to connect to API: Self-signed certificate detected

538```641```

539 642

643{/* min-version: 2.1.199 */}A partire da v2.1.199, un guasto di convalida del certificato non viene ritentato, quindi questo errore appare al primo tentativo invece che dopo il [budget di tentativo](#automatic-retries) completo. Le versioni precedenti spendevano alcuni minuti ritentando prima di mostrarlo. Le condizioni TLS transitorie, come un timeout di handshake, continuano a ritentare.

644

645Durante `/login` e il controllo di connettività di avvio, lo stesso guasto viene segnalato con il codice OpenSSL e la correzione inline:

646

647```text theme={null}

648SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run /doctor for details.

649```

650

540**Cosa fare:**651**Cosa fare:**

541 652

542* Esporta il bundle CA della tua organizzazione e punta Claude Code ad esso con `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`653* Esporta il bundle CA della tua organizzazione e punta Claude Code ad esso con `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem`

823* Se non riesci a identificare quale turno l'ha causato, esegui `/clear` per avviare una conversazione nuova nello stesso progetto. La tua conversazione precedente viene preservata su disco e rimane disponibile in `/resume`.934* Se non riesci a identificare quale turno l'ha causato, esegui `/clear` per avviare una conversazione nuova nello stesso progetto. La tua conversazione precedente viene preservata su disco e rimane disponibile in `/resume`.

824* In [modalità non interattiva](/it/headless) (`-p`), dove rewind non è disponibile, riprova con un prompt riformulato in una nuova sessione senza `--continue`. I controlli delle policy variano in base al modello, quindi passare a un modello diverso con `--model` potrebbe anche risolvere il rifiuto in alcuni casi.935* In [modalità non interattiva](/it/headless) (`-p`), dove rewind non è disponibile, riprova con un prompt riformulato in una nuova sessione senza `--continue`. I controlli delle policy variano in base al modello, quindi passare a un modello diverso con `--model` potrebbe anche risolvere il rifiuto in alcuni casi.

825 936

937<h2 id="command-line-errors">

938 Errori della riga di comando

939</h2>

940

941Questi errori provengono dalla convalida di Claude Code della riga di comando `claude`. Claude Code li stampa immediatamente, prima di creare una sessione o inviare qualsiasi richiesta API.

942

943<h3 id="conflict-between-bg-and-print">

944 Conflict between --bg and --print

945</h3>

946

947Questo messaggio richiede Claude Code v2.1.198 o successivo. Hai combinato `--bg` con `-p` o `--print` nella stessa invocazione `claude`. `--bg` avvia una [sessione in background](/it/agent-view#from-your-shell) che colleghi in seguito con `claude agents`, mentre `--print` esegue [non interattivamente](/it/headless) e non avvia mai la sessione interattiva a cui `claude agents` si collega. Prima di v2.1.198 questa combinazione creava silenziosamente un job in background che non poteva mai essere collegato.

948

949```text theme={null}

950--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.

951```

952

953**Cosa fare:**

954

955* Rilascia `-p` o `--print`. `--bg` prende il prompt come suo argomento posizionale, quindi `claude --bg "<task>"` è il comando completo. Vedi [Dispatch new agents from your shell](/it/agent-view#from-your-shell).

956* Per eseguire il prompt non interattivamente e stampare il risultato invece di creare una sessione in background, rilascia `--bg` ed esegui `claude -p "<task>"`

957

826<h2 id="responses-seem-lower-quality-than-usual">958<h2 id="responses-seem-lower-quality-than-usual">

827 Le risposte sembrano di qualità inferiore al solito959 Le risposte sembrano di qualità inferiore al solito

828</h2>960</h2>

850 Segnalare un errore982 Segnalare un errore

851</h2>983</h2>

852 984

853Questa pagina copre gli errori dall'API Claude. Per gli errori da altri componenti di Claude Code, vedi la guida rilevante:985Per gli errori da componenti che questa pagina non copre, vedi la guida rilevante:

854 986

855* Il server MCP non è riuscito a connettersi o autenticarsi: [MCP](/it/mcp)987* Il server MCP non è riuscito a connettersi o autenticarsi: [MCP](/it/mcp)

856* Lo script hook non è riuscito o ha bloccato uno strumento: [Debug hooks](/it/hooks#debug-hooks)988* Lo script hook non è riuscito o ha bloccato uno strumento: [Debug hooks](/it/hooks#debug-hooks)

857* Permesso negato o errori del filesystem durante l'installazione: [Troubleshooting dell'installazione e dell'accesso](/it/troubleshooting-install)989* Permesso negato o errori del filesystem durante l'installazione: [Troubleshooting dell'installazione e dell'accesso](/it/troubleshoot-install)

858 990

859Se un errore non è elencato qui o la correzione suggerita non aiuta:991Se un errore non è elencato qui o la correzione suggerita non aiuta:

860 992

fullscreen.md +2 −2

Details

58* **Fai clic su un suggerimento nel comando `/` o nell'elenco di file `@`** per accettarlo. Passare il mouse evidenzia la riga sotto il cursore.58* **Fai clic su un suggerimento nel comando `/` o nell'elenco di file `@`** per accettarlo. Passare il mouse evidenzia la riga sotto il cursore.

59* **Fai clic su un'opzione in un menu di selezione** per sceglierla. Questo copre i prompt di autorizzazione, `/model`, `/config` e altri dialoghi che mostrano un elenco di opzioni. Passare il mouse mostra un puntatore sulla riga sotto il cursore. Richiede Claude Code v2.1.187 o successivo.59* **Fai clic su un'opzione in un menu di selezione** per sceglierla. Questo copre i prompt di autorizzazione, `/model`, `/config` e altri dialoghi che mostrano un elenco di opzioni. Passare il mouse mostra un puntatore sulla riga sotto il cursore. Richiede Claude Code v2.1.187 o successivo.

60* **Fai clic su un risultato dello strumento compresso** per espanderlo e vedere l'output completo. Fai clic di nuovo per comprimerlo. La chiamata dello strumento e il suo risultato si espandono insieme. Solo i messaggi che hanno più da mostrare sono cliccabili.60* **Fai clic su un risultato dello strumento compresso** per espanderlo e vedere l'output completo. Fai clic di nuovo per comprimerlo. La chiamata dello strumento e il suo risultato si espandono insieme. Solo i messaggi che hanno più da mostrare sono cliccabili.

61* **Tieni premuto `Cmd` su macOS, o `Ctrl` su Linux e Windows, e fai clic su un URL o un percorso di file** per aprirlo. I percorsi di file nell'output dello strumento, come quelli stampati dopo un Edit o Write, si aprono nell'applicazione predefinita. Gli URL `http://` e `https://` semplici si aprono nel browser. A partire dalla v2.1.181, un semplice clic senza tenere premuto `Cmd` o `Ctrl` non apre più i link, corrispondendo al comportamento del terminale nativo. Nel terminale integrato di VS Code e nei terminali basati su xterm.js simili, Claude Code si rimette al gestore di link del terminale, che utilizza lo stesso gesto.61* **Tieni premuto `Cmd` su macOS, o `Ctrl` su Linux e Windows, e fai clic su un URL o un percorso di file** per aprirlo. I percorsi di file nell'output dello strumento, come quelli stampati dopo un Edit o Write, si aprono nell'applicazione predefinita. Gli URL `http://` e `https://` semplici si aprono nel browser. A partire dalla v2.1.181, un semplice clic senza tenere premuto `Cmd` o `Ctrl` non apre più i link, corrispondendo al comportamento del terminale nativo. Alcuni terminali macOS inoltrano `Cmd`+clic all'app in esecuzione invece di aprire il link stessi, e il protocollo del mouse del terminale non ha modo di codificare il tasto `Cmd`, quindi Claude Code lo riceve come un semplice clic. In Ghostty, e a partire dalla v2.1.198 in Warp su macOS, Claude Code rileva questo e consente a un semplice clic su un link di aprirlo, e tenere premuto `Cmd` funziona ancora. Nel terminale integrato di VS Code e nei terminali basati su xterm.js simili, Claude Code si rimette al gestore di link del terminale, che utilizza lo stesso gesto.

62* **Fai clic e trascinamento** per selezionare il testo in qualsiasi punto della conversazione. Il doppio clic seleziona una parola, corrispondendo ai confini delle parole di iTerm2 in modo che un percorso di file si selezioni come un'unità. Il triplo clic seleziona la riga.62* **Fai clic e trascinamento** per selezionare il testo in qualsiasi punto della conversazione. Il doppio clic seleziona una parola, corrispondendo ai confini delle parole di iTerm2 in modo che un percorso di file si selezioni come un'unità. A partire dalla v2.1.198, il doppio clic su un URL seleziona l'intero URL, incluso lo schema. Il triplo clic seleziona la riga.

63* **Scorri con la rotella del mouse** per muoverti attraverso la conversazione.63* **Scorri con la rotella del mouse** per muoverti attraverso la conversazione.

64 64

65Il testo selezionato viene copiato negli appunti automaticamente al rilascio del mouse. Per disattivarlo, attiva/disattiva Copia alla selezione in `/config`.65Il testo selezionato viene copiato negli appunti automaticamente al rilascio del mouse. Per disattivarlo, attiva/disattiva Copia alla selezione in `/config`.

gateways.md +1 −1

Details

44 Claude apps gateway44 Claude apps gateway

45</h3>45</h3>

46 46

47Claude apps gateway è il gateway auto-ospitato di Anthropic, incluso nel binario `claude`. Instrada ad Amazon Bedrock, Google Cloud, Microsoft Foundry o l'API Anthropic come upstream. Gli sviluppatori accedono con il tuo provider di identità aziendale attraverso `/login`, il gateway applica l'accesso ai modelli e le [impostazioni gestite](/it/permissions#managed-settings) per gruppo IdP, e emette metriche di utilizzo [OpenTelemetry Protocol (OTLP)](/it/monitoring-usage) al tuo stack di osservabilità.47Claude apps gateway è il gateway auto-ospitato di Anthropic, incluso nel binario `claude`. Instrada ad Amazon Bedrock, Claude Platform su AWS, Google Cloud, Microsoft Foundry o l'API Anthropic come upstream. Gli sviluppatori accedono con il tuo provider di identità aziendale attraverso `/login`, il gateway applica l'accesso ai modelli e le [impostazioni gestite](/it/permissions#managed-settings) per gruppo IdP, e emette metriche di utilizzo [OpenTelemetry Protocol (OTLP)](/it/monitoring-usage) al tuo stack di osservabilità.

48 48

49Poiché è costruito e testato insieme a ogni rilascio di Claude Code, inoltra le intestazioni e i campi di richiesta che Claude Code invia. Un gateway mantenuto separatamente ha bisogno che le sue [regole di inoltro vengano aggiornate](/it/llm-gateway-protocol#forward-as-open-lists) mentre quelle intestazioni e campi cambiano con ogni rilascio; Claude apps gateway viene rilasciato con la CLI, quindi non c'è alcun elenco da mantenere aggiornato. Vedi [Disponibilità e limitazioni](/it/claude-apps-gateway#availability-and-limitations) per il piccolo insieme di funzionalità che si comportano diversamente in una sessione gateway.49Poiché è costruito e testato insieme a ogni rilascio di Claude Code, inoltra le intestazioni e i campi di richiesta che Claude Code invia. Un gateway mantenuto separatamente ha bisogno che le sue [regole di inoltro vengano aggiornate](/it/llm-gateway-protocol#forward-as-open-lists) mentre quelle intestazioni e campi cambiano con ogni rilascio; Claude apps gateway viene rilasciato con la CLI, quindi non c'è alcun elenco da mantenere aggiornato. Vedi [Disponibilità e limitazioni](/it/claude-apps-gateway#availability-and-limitations) per il piccolo insieme di funzionalità che si comportano diversamente in una sessione gateway.

50 50

hooks.md +79 −45

Details

16 Ciclo di vita dei hook16 Ciclo di vita dei hook

17</h2>17</h2>

18 18

19Gli hook si attivano in punti specifici durante una sessione di Claude Code. Quando un evento si attiva e un matcher corrisponde, Claude Code passa il contesto JSON dell'evento al gestore del hook. Per i hook di comando, l'input arriva su stdin. Per i hook HTTP, arriva come corpo della richiesta POST. Il gestore può quindi ispezionare l'input, intraprendere un'azione e facoltativamente restituire una decisione. Gli eventi si dividono in tre cadenze: una volta per sessione (`SessionStart`, `SessionEnd`), una volta per turno (`UserPromptSubmit`, `Stop`, `StopFailure`) e ad ogni chiamata dello strumento all'interno del ciclo agentico (`PreToolUse`, `PostToolUse`):19Gli hook si attivano in punti specifici durante una sessione di Claude Code. Quando un evento si attiva e un matcher corrisponde, Claude Code passa il contesto JSON dell'evento al gestore del hook. Per i hook di comando, l'input arriva su stdin. Per i hook HTTP, arriva come corpo della richiesta POST. Il gestore può quindi ispezionare l'input, intraprendere un'azione e facoltativamente restituire una decisione.

21Gli eventi si dividono in tre cadenze:

23* una volta per sessione: `SessionStart` e `SessionEnd`

24* una volta per turno: `UserPromptSubmit`, `Stop` e `StopFailure`

25* ad ogni chiamata dello strumento all'interno del ciclo agentico: `PreToolUse` e `PostToolUse`

20 26

21<div style={{maxWidth: "500px", margin: "0 auto"}}>27<div style={{maxWidth: "500px", margin: "0 auto"}}>

22 <Frame>28 <Frame>

217| `Notification` | tipo di notifica | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response` |223| `Notification` | tipo di notifica | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed` |

317 323

318Tutti gli hook corrispondenti vengono eseguiti in parallelo e i gestori identici vengono automaticamente deduplicati. I command hook vengono deduplicati per stringa di comando e `args`, e gli HTTP hook vengono deduplicati per URL.324Tutti gli hook corrispondenti vengono eseguiti in parallelo e i gestori identici vengono automaticamente deduplicati. I command hook vengono deduplicati per stringa di comando e `args`, e gli HTTP hook vengono deduplicati per URL.

319 325

320I gestori vengono eseguiti nella directory corrente con l'ambiente di Claude Code. La variabile di ambiente `$CLAUDE_CODE_REMOTE` è impostata su `"true"` negli ambienti web remoti e non è impostata nella CLI locale.326I gestori vengono eseguiti nella directory corrente con l'ambiente di Claude Code. La variabile di ambiente `$CLAUDE_CODE_REMOTE` è impostata su `"true"` negli ambienti web remoti e non è impostata nella CLI locale. {/* min-version: 2.1.199 */}A partire da v2.1.199, [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/it/env-vars) è impostato sull'ID della sessione [Remote Control](/it/remote-control) mentre la sessione locale ha una connessione Remote Control attiva.

321 327

322<h4 id="common-fields">328<h4 id="common-fields">

323 Campi comuni329 Campi comuni

704Il codice di uscita 2 è il modo in cui un hook segnala "fermarsi, non farlo". L'effetto dipende dall'evento, perché alcuni eventi rappresentano azioni che possono essere bloccate (come una chiamata dello strumento che non è ancora accaduta) e altri rappresentano cose che sono già accadute o non possono essere prevenute.710Il codice di uscita 2 è il modo in cui un hook segnala "fermarsi, non farlo". L'effetto dipende dall'evento, perché alcuni eventi rappresentano azioni che possono essere bloccate (come una chiamata dello strumento che non è ancora accaduta) e altri rappresentano cose che sono già accadute o non possono essere prevenute.

705 711

707| :-------------------- | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |713| :-------------------- | :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

708| `PreToolUse` | Sì | Blocca la chiamata dello strumento |714| `PreToolUse` | Sì | Blocca la chiamata dello strumento |

709| `PermissionRequest` | Sì | Nega l'autorizzazione |715| `PermissionRequest` | Sì | Nega l'autorizzazione |

710| `UserPromptSubmit` | Sì | Blocca l'elaborazione del prompt e cancella il prompt |716| `UserPromptSubmit` | Sì | Blocca l'elaborazione del prompt e cancella il prompt |

711| `UserPromptExpansion` | Sì | Blocca l'espansione |717| `UserPromptExpansion` | Sì | Blocca l'espansione |

712| `Stop` | Sì | Impedisce a Claude di fermarsi, continua la conversazione |718| `Stop` | Sì | Impedisce a Claude di fermarsi, continua la conversazione |

713| `SubagentStop` | Sì | Impedisce al subagent di fermarsi |719| `SubagentStop` | Sì | Impedisce al subagent di fermarsi |

714| `TeammateIdle` | Sì | Impedisce al compagno di squadra di andare inattivo (il compagno di squadra continua a lavorare) |720| `TeammateIdle` | Sì | Impedisce al compagno di squadra di andare inattivo, quindi continua a lavorare |

715| `TaskCreated` | Sì | Annulla la creazione dell'attività |721| `TaskCreated` | Sì | Annulla la creazione dell'attività |

716| `TaskCompleted` | Sì | Impedisce che l'attività sia contrassegnata come completata |722| `TaskCompleted` | Sì | Impedisce che l'attività sia contrassegnata come completata |

717| `ConfigChange` | Sì | Blocca la modifica della configurazione dall'avere effetto (tranne `policy_settings`) |723| `ConfigChange` | Sì | Blocca la modifica della configurazione dall'avere effetto (tranne `policy_settings`) |

718| `StopFailure` | No | L'output e il codice di uscita vengono ignorati |724| `StopFailure` | No | L'output e il codice di uscita vengono ignorati |

719| `PostToolUse` | No | Mostra stderr a Claude (lo strumento è già stato eseguito) |725| `PostToolUse` | No | Mostra stderr a Claude; lo strumento è già stato eseguito |

720| `PostToolUseFailure` | No | Mostra stderr a Claude (lo strumento è già fallito) |726| `PostToolUseFailure` | No | Mostra stderr a Claude; lo strumento è già fallito |

721| `PostToolBatch` | Sì | Interrompe il loop agentico prima della prossima chiamata del modello |727| `PostToolBatch` | Sì | Interrompe il loop agentico prima della prossima chiamata del modello |

722| `PermissionDenied` | No | Il codice di uscita e stderr vengono ignorati (il rifiuto è già avvenuto). Utilizzare JSON `hookSpecificOutput.retry: true` per dire al modello che può riprovare |728| `PermissionDenied` | No | Il codice di uscita e stderr vengono ignorati perché il rifiuto è già avvenuto. Utilizzare JSON `hookSpecificOutput.retry: true` per dire al modello che può riprovare |

723| `Notification` | No | Mostra stderr solo all'utente |729| `Notification` | No | Mostra stderr solo all'utente |

724| `SubagentStart` | No | Mostra stderr solo all'utente |730| `SubagentStart` | No | Mostra stderr solo all'utente |

725| `SessionStart` | No | Mostra stderr solo all'utente |731| `SessionStart` | No | Mostra stderr solo all'utente |

736| `InstructionsLoaded` | No | Il codice di uscita viene ignorato |742| `InstructionsLoaded` | No | Il codice di uscita viene ignorato |

737| `MessageDisplay` | No | Il testo originale viene visualizzato |743| `MessageDisplay` | No | Il testo originale viene visualizzato |

738 744

745Per `SessionStart`, `Setup` e `SubagentStart`, lo stderr del codice di uscita 2 viene visualizzato nella trascrizione come un avviso `<hook name> hook error`, nello stesso modo di un [errore non bloccante](#exit-code-output). Claude non lo vede e la sessione o il subagent procede. Per `SubagentStart`, l'avviso appare nella trascrizione del subagent stesso, non nella conversazione padre.

746

747A partire da Claude Code v2.1.199, `SessionStart`, `Setup` e `SubagentStart` mostrano lo stderr del codice di uscita 2 nella trascrizione. Le versioni precedenti lo scrivevano solo nel log di debug.

748

739<h3 id="http-response-handling">749<h3 id="http-response-handling">

740 Gestione della risposta HTTP750 Gestione della risposta HTTP

741</h3>751</h3>

963 Input di SessionStart973 Input di SessionStart

964</h4>974</h4>

965 975

966Oltre ai [campi di input comuni](#common-input-fields), gli hook SessionStart ricevono `source` e facoltativamente `model`, `agent_type` e `session_title`. Il campo `source` indica come è iniziata la sessione: `"startup"` per le nuove sessioni, `"resume"` per le sessioni riprese, `"clear"` dopo `/clear` o `"compact"` dopo la compattazione. Il campo `model` contiene l'identificatore del modello attivo. Può essere omesso, ad esempio dopo `/clear` o quando una sessione viene ripristinata attraverso il recupero della conversazione, quindi controllare il campo prima di leggerlo. Se si avvia Claude Code con `claude --agent <name>`, un campo `agent_type` contiene il nome dell'agente. Il campo `session_title` contiene il titolo della sessione corrente se uno è già impostato, ad esempio tramite `--name` o `/rename`. Un hook che emette `sessionTitle` può controllare prima `session_title` per evitare di sovrascrivere un titolo impostato esplicitamente dall'utente.976Oltre ai [campi di input comuni](#common-input-fields), gli hook SessionStart ricevono `source` e facoltativamente `model`, `agent_type` e `session_title`:

977

978| Campo | Descrizione |

979| :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

980| `source` | Come è iniziata la sessione: `"startup"` per le nuove sessioni, `"resume"` per le sessioni riprese, `"clear"` dopo `/clear` o `"compact"` dopo la compattazione |

981| `model` | L'identificatore del modello attivo. Può essere omesso, ad esempio dopo `/clear` o quando una sessione viene ripristinata attraverso il recupero della conversazione, quindi controllare il campo prima di leggerlo |

982| `agent_type` | Il nome dell'agente, presente quando si avvia Claude Code con `claude --agent <name>` |

983| `session_title` | Il titolo della sessione corrente se uno è già impostato, ad esempio tramite `--name` o `/rename`. Un hook che emette `sessionTitle` può controllare prima `session_title` per evitare di sovrascrivere un titolo impostato esplicitamente dall'utente |

967 984

968```json theme={null}985```json theme={null}

969{986{

983Qualsiasi testo che lo script del hook stampa su stdout viene aggiunto come contesto per Claude. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, è possibile restituire questi campi specifici dell'evento:1000Qualsiasi testo che lo script del hook stampa su stdout viene aggiunto come contesto per Claude. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, è possibile restituire questi campi specifici dell'evento:

984 1001

985| Campo | Descrizione |1002| Campo | Descrizione |

986| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1003| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

989| `sessionTitle` | Imposta il titolo della sessione, con lo stesso effetto di `/rename`. Utilizzare per denominare automaticamente le sessioni dalla cartella di avvio, dal ramo git o dal nome del worktree. Si applica solo quando `source` è `"startup"` o `"resume"`; ignorato su `"clear"` e `"compact"` |1006| `sessionTitle` | Imposta il titolo della sessione, con lo stesso effetto di `/rename`. Utilizzare per denominare automaticamente le sessioni dalla cartella di avvio, dal ramo git o dal nome del worktree. Si applica solo quando `source` è `"startup"` o `"resume"`; ignorato su `"clear"` e `"compact"` |

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

991| `reloadSkills` | Booleano. Quando `true`, Claude Code esegue nuovamente la scansione delle directory [skill](/it/skills) e dei comandi dopo il completamento degli hook SessionStart, in modo che le skill installate dall'hook siano disponibili nella stessa sessione, a partire dal primo prompt |1008| `reloadSkills` | Booleano. Quando `true`, Claude Code esegue nuovamente la scansione delle directory [skill](/it/skills) e dei comandi dopo il completamento degli hook SessionStart, in modo che le skill installate dall'hook siano disponibili nella stessa sessione, a partire dal primo prompt |

1062 Setup1079 Setup

1063</h3>1080</h3>

1064 1081

1065Si attiva solo quando si avvia Claude Code con `--init-only`, o con `--init` o `--maintenance` in modalità stampa (`-p`). Non si attiva all'avvio normale. Utilizzarlo per l'installazione di dipendenze una tantum o la pulizia pianificata che si attiva esplicitamente da CI o script, separato dall'avvio della sessione normale. Per l'inizializzazione per sessione, utilizzare [SessionStart](#sessionstart) invece.1082Si attiva solo quando si avvia Claude Code con `--init-only`, o con `--init` o `--maintenance` in [modalità non interattiva](/it/headless) con il flag `-p`. Non si attiva all'avvio normale. Utilizzarlo per l'installazione di dipendenze una tantum o la pulizia pianificata che si attiva esplicitamente da CI o script, separato dall'avvio della sessione normale. Per l'inizializzazione per sessione, utilizzare [SessionStart](#sessionstart) invece.

1066 1083

1067Il valore del matcher corrisponde al flag CLI che ha attivato l'hook:1084Il valore del matcher corrisponde al flag CLI che ha attivato l'hook:

1068 1085

1073 1090

1074`--init-only` esegue gli hook Setup e gli hook SessionStart con il matcher `startup`, quindi esce senza avviare una conversazione. `--init` e `--maintenance` attivano gli hook Setup solo quando combinati con `-p` (modalità stampa); in una sessione interattiva questi due flag attualmente non attivano gli hook Setup.1091`--init-only` esegue gli hook Setup e gli hook SessionStart con il matcher `startup`, quindi esce senza avviare una conversazione. `--init` e `--maintenance` attivano gli hook Setup solo quando combinati con `-p`; in una sessione interattiva questi due flag attualmente non attivano gli hook Setup.

1075 1092

1076Poiché Setup non si attiva ad ogni avvio, un plugin che ha bisogno di una dipendenza installata non può fare affidamento solo su Setup. Il modello pratico è controllare la dipendenza al primo utilizzo e installare se assente, ad esempio un hook o una skill che testa per `${CLAUDE_PLUGIN_DATA}/node_modules` ed esegue `npm install` se assente. Consultare la [directory dei dati persistenti](/it/plugins-reference#persistent-data-directory) per dove archiviare le dipendenze installate.1093Poiché Setup non si attiva ad ogni avvio, un plugin che ha bisogno di una dipendenza installata non può fare affidamento solo su Setup. Il modello pratico è controllare la dipendenza al primo utilizzo e installare se assente, ad esempio un hook o una skill che testa per `${CLAUDE_PLUGIN_DATA}/node_modules` ed esegue `npm install` se assente. Consultare la [directory dei dati persistenti](/it/plugins-reference#persistent-data-directory) per dove archiviare le dipendenze installate.

1077 1094

1095 Controllo della decisione di Setup1112 Controllo della decisione di Setup

1096</h4>1113</h4>

1097 1114

1098Gli hook Setup non possono bloccare. Su exit code 2, stderr viene mostrato all'utente; su qualsiasi altro exit code non zero, stderr appare solo quando si avvia con `--verbose`. In entrambi i casi l'esecuzione continua. Per passare informazioni nel contesto di Claude, restituire `additionalContext` nell'output JSON; lo stdout semplice viene scritto solo nel log di debug. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, è possibile restituire questi campi specifici dell'evento:1115Gli hook Setup non possono bloccare. Su exit code 2, stderr viene mostrato all'utente come avviso `<hook name> hook error`; su qualsiasi altro exit code non zero, stderr appare solo quando si avvia con `--verbose`. In entrambi i casi l'esecuzione continua. Per passare informazioni nel contesto di Claude, restituire `additionalContext` nell'output JSON; lo stdout semplice viene scritto solo nel log di debug. Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, è possibile restituire questi campi specifici dell'evento:

1099 1116

1100| Campo | Descrizione |1117| Campo | Descrizione |

1101| :------------------ | :------------------------------------------------------------------------------- |1118| :------------------ | :------------------------------------------------------------------------------- |

1191* **Stdout di testo semplice**: qualsiasi testo non-JSON scritto su stdout viene aggiunto come contesto1208* **Stdout di testo semplice**: qualsiasi testo non-JSON scritto su stdout viene aggiunto come contesto

1192* **JSON con `additionalContext`**: utilizzare il formato JSON seguente per un controllo maggiore. Il campo `additionalContext` viene aggiunto come contesto1209* **JSON con `additionalContext`**: utilizzare il formato JSON seguente per un controllo maggiore. Il campo `additionalContext` viene aggiunto come contesto

1193 1210

1194Lo stdout semplice viene mostrato come output del hook nella trascrizione. Il campo `additionalContext` viene aggiunto più discretamente.1211Lo stdout semplice viene mostrato come output del hook nella trascrizione. Il valore `additionalContext` viene iniettato come un promemoria di sistema che Claude legge senza una voce di trascrizione visibile.

1195 1212

1196Per bloccare un prompt, restituire un oggetto JSON con `decision` impostato su `"block"`:1213Per bloccare un prompt, restituire un oggetto JSON con `decision` impostato su `"block"`:

1197 1214

1215}1232}

1216```1233```

1217 1234

1218<Note>

1219 Il formato JSON non è obbligatorio per i casi semplici. Per aggiungere contesto, è possibile stampare testo semplice su stdout con exit code 0. Utilizzare JSON quando è necessario bloccare i prompt o si desidera un controllo più strutturato.

1220</Note>

~~1221~~

1222<h3 id="userpromptexpansion">1235<h3 id="userpromptexpansion">

1223 UserPromptExpansion1236 UserPromptExpansion

1224</h3>1237</h3>

1545In `PostToolUse`, `tool_response` per una chiamata Agent completata contiene il testo finale del subagent insieme alla telemetria di utilizzo. Leggere questi campi per registrare il costo per subagent da un hook:1558In `PostToolUse`, `tool_response` per una chiamata Agent completata contiene il testo finale del subagent insieme alla telemetria di utilizzo. Leggere questi campi per registrare il costo per subagent da un hook:

1546 1559

1548| :------------------ | :----- | :---------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |1561| :------------------ | :----- | :---------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1549| `status` | string | `"completed"` | `"completed"` per le chiamate sincrone, `"async_launched"` per `run_in_background: true` |1562| `status` | string | `"completed"` | `"completed"` per le chiamate sincrone, `"async_launched"` per le chiamate in background. {/* min-version: 2.1.198 */}A partire da v2.1.198, i subagent vengono eseguiti in background per impostazione predefinita, quindi un `run_in_background` omesso produce anche `"async_launched"` |

1551| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | I blocchi di testo finali del subagent |1564| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | I blocchi di testo finali del subagent |

1552| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modello su cui è stato eseguito il subagent, che può differire dal modello richiesto. {/* min-version: 2.1.174 */}Richiede Claude Code v2.1.174 o successivo |1565| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modello su cui è stato eseguito il subagent, che può differire dal modello richiesto. {/* min-version: 2.1.174 */}Richiede Claude Code v2.1.174 o successivo |

1556| `usage` | object | `{"input_tokens": 8320, ...}` | Suddivisione dei token per tipo: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1569| `usage` | object | `{"input_tokens": 8320, ...}` | Suddivisione dei token per tipo: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |

1557 1570

1558Per le chiamate `run_in_background: true`, lo strumento ritorna immediatamente dopo il lancio del subagent, quindi `tool_response` non contiene campi di utilizzo. Ha `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel` invece.1571Per le chiamate in background, lo strumento ritorna immediatamente dopo il lancio del subagent, quindi `tool_response` non contiene campi di utilizzo. Ha `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel` invece.

1559 1572

1560Il campo `resolvedModel` nomina il modello su cui il subagent effettivamente viene eseguito, che può differire dal valore `model` in `tool_input`. Richiede Claude Code v2.1.174 o successivo.1573Il campo `resolvedModel` nomina il modello su cui il subagent effettivamente viene eseguito, che può differire dal valore `model` in `tool_input`, ad esempio quando `availableModels` o un altro override si applica. Richiede Claude Code v2.1.174 o successivo.

1561 1574

1562<a id="askuserquestion" />1575<a id="askuserquestion" />

1563 1576

1587In `PostToolUse`, `tool_response` è un oggetto con i campi `plan` e `filePath` che contengono il piano approvato, più flag di stato interni. Leggere `tool_response.plan` per il contenuto del piano piuttosto che rileggere il file da disco.1600In `PostToolUse`, `tool_response` è un oggetto con i campi `plan` e `filePath` che contengono il piano approvato, più flag di stato interni. Leggere `tool_response.plan` per il contenuto del piano piuttosto che rileggere il file da disco.

1588 1601

1589<h4 id="pretooluse-decision-control">1602<h4 id="pretooluse-decision-control">

1590 PreToolUse decision control1603 Controllo della decisione di PreToolUse

1591</h4>1604</h4>

1592 1605

1593Gli hook `PreToolUse` possono controllare se una chiamata dello strumento procede. A differenza di altri hook che utilizzano un campo `decision` di livello superiore, PreToolUse restituisce la sua decisione all'interno di un oggetto `hookSpecificOutput`. Ciò gli dà un controllo più ricco: quattro risultati (consentire, negare, chiedere o rinviare) più la capacità di modificare l'input dello strumento prima dell'esecuzione.1606Gli hook `PreToolUse` possono controllare se una chiamata dello strumento procede. A differenza di altri hook che utilizzano un campo `decision` di livello superiore, PreToolUse restituisce la sua decisione all'interno di un oggetto `hookSpecificOutput`. Ciò gli dà un controllo più ricco: quattro risultati (consentire, negare, chiedere o rinviare) più la capacità di modificare l'input dello strumento prima dell'esecuzione.

1594 1607

1595| Campo | Descrizione |1608| Campo | Descrizione |

1596| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1609| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1597| `permissionDecision` | `"allow"` bypassa il prompt di autorizzazione. `"deny"` impedisce la chiamata dello strumento. `"ask"` richiede all'utente di confermare. `"defer"` esce correttamente in modo che lo strumento possa essere ripreso in seguito. Le regole [Deny and ask](/it/permissions#manage-permissions) si applicano ancora indipendentemente da quello che l'hook restituisce |1610| `permissionDecision` | `"allow"` bypassa il prompt di autorizzazione, tranne per [strumenti che richiedono l'interazione dell'utente](#pretooluse-decision-control). `"deny"` impedisce la chiamata dello strumento. `"ask"` richiede all'utente di confermare. `"defer"` esce correttamente in modo che lo strumento possa essere ripreso in seguito. Le regole [Deny and ask](/it/permissions#manage-permissions) si applicano ancora indipendentemente da quello che l'hook restituisce |

1598| `permissionDecisionReason` | Per `"allow"` e `"ask"`, mostrato all'utente ma non a Claude. Per `"deny"`, mostrato a Claude. Per `"defer"`, ignorato |1611| `permissionDecisionReason` | Per `"allow"` e `"ask"`, mostrato all'utente ma non a Claude. Per `"deny"`, mostrato a Claude. Per `"defer"`, ignorato |

1599| `updatedInput` | Modifica i parametri di input dello strumento prima dell'esecuzione. Sostituisce l'intero oggetto di input, quindi includere i campi invariati insieme a quelli modificati. Combinare con `"allow"` per l'approvazione automatica o `"ask"` per mostrare l'input modificato all'utente. Per `"defer"`, ignorato |1612| `updatedInput` | Modifica i parametri di input dello strumento prima dell'esecuzione. Sostituisce l'intero oggetto di input, quindi includere i campi invariati insieme a quelli modificati. Combinare con `"allow"` per l'approvazione automatica o `"ask"` per mostrare l'input modificato all'utente. Per `"defer"`, ignorato |

1600| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Ignorato quando `permissionDecision` è `"defer"`. Consultare [Aggiungere contesto per Claude](#add-context-for-claude) |1613| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Ignorato quando `permissionDecision` è `"defer"`. Consultare [Aggiungere contesto per Claude](#add-context-for-claude) |

1619 1632

1620`AskUserQuestion` e `ExitPlanMode` richiedono l'interazione dell'utente e normalmente bloccano in [modalità non interattiva](/it/headless) con il flag `-p`. Restituire `permissionDecision: "allow"` insieme a `updatedInput` soddisfa quel requisito: l'hook legge l'input dello strumento da stdin, raccoglie la risposta attraverso la propria interfaccia utente e la restituisce in `updatedInput` in modo che lo strumento venga eseguito senza richiedere. Restituire `"allow"` da solo non è sufficiente per questi strumenti. Per `AskUserQuestion`, ripetere l'array `questions` originale e aggiungere un oggetto [`answers`](#askuserquestion) che mappa il testo di ogni domanda alla risposta scelta.1633`AskUserQuestion` e `ExitPlanMode` richiedono l'interazione dell'utente e normalmente bloccano in [modalità non interattiva](/it/headless) con il flag `-p`. Restituire `permissionDecision: "allow"` insieme a `updatedInput` soddisfa quel requisito: l'hook legge l'input dello strumento da stdin, raccoglie la risposta attraverso la propria interfaccia utente e la restituisce in `updatedInput` in modo che lo strumento venga eseguito senza richiedere. Restituire `"allow"` da solo non è sufficiente per questi strumenti. Per `AskUserQuestion`, ripetere l'array `questions` originale e aggiungere un oggetto [`answers`](#askuserquestion) che mappa il testo di ogni domanda alla risposta scelta.

1621 1634

1635A partire da v2.1.199, uno strumento MCP il cui server lo contrassegna con [`_meta["anthropic/requiresUserInteraction"]`](/it/mcp#require-approval-for-a-specific-tool) è più rigoroso: un hook non può saltare il suo prompt di approvazione con `"allow"`, con o senza `updatedInput`, perché Claude Code non può confermare che l'hook ha raccolto l'interazione di cui lo strumento ha bisogno.

1636

1622<Note>1637<Note>

1623 PreToolUse in precedenza utilizzava i campi `decision` e `reason` di livello superiore, ma questi sono deprecati per questo evento. Utilizzare invece `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason`. I valori deprecati `"approve"` e `"block"` si mappano a `"allow"` e `"deny"` rispettivamente. Gli altri eventi come PostToolUse e Stop continuano a utilizzare `decision` e `reason` di livello superiore come formato corrente.1638 PreToolUse in precedenza utilizzava i campi `decision` e `reason` di livello superiore, ma questi sono deprecati per questo evento. Utilizzare invece `hookSpecificOutput.permissionDecision` e `hookSpecificOutput.permissionDecisionReason`. I valori deprecati `"approve"` e `"block"` si mappano a `"allow"` e `"deny"` rispettivamente. Gli altri eventi come PostToolUse e Stop continuano a utilizzare `decision` e `reason` di livello superiore come formato corrente.

1624</Note>1639</Note>

2016 Notification2031 Notification

2017</h3>2032</h3>

2018 2033

2019Viene eseguito quando Claude Code invia notifiche. Corrisponde al tipo di notifica: `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`. Omettere il matcher per eseguire gli hook per tutti i tipi di notifica.2034Viene eseguito quando Claude Code invia notifiche. Corrisponde al tipo di notifica. Omettere il matcher per eseguire gli hook per tutti i tipi di notifica.

2035

2036| Matcher | Quando si attiva |

2037| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |

2038| `permission_prompt` | Claude ha bisogno dell'approvazione di uno strumento |

2039| `idle_prompt` | Claude è terminato e in attesa del prompt successivo |

2040| `auth_success` | L'autenticazione è completata |

2041| `elicitation_dialog` | Un server MCP apre un modulo di elicitazione |

2042| `elicitation_complete` | Un modulo di elicitazione MCP viene inviato o chiuso |

2043| `elicitation_response` | Una risposta di elicitazione MCP viene inviata al server |

2044| `agent_needs_input` | Una sessione in background inizia ad attendere l'input. Si attiva solo mentre la [vista agente](/it/agent-view) è aperta in un terminale |

2045| `agent_completed` | Una sessione in background termina o non riesce. Si attiva solo mentre la [vista agente](/it/agent-view) è aperta in un terminale |

2046

2047I tipi `agent_needs_input` e `agent_completed` richiedono Claude Code v2.1.198 o successivo.

2020 2048

2021Utilizzare matcher separati per eseguire gestori diversi a seconda del tipo di notifica. Questa configurazione attiva uno script di avviso specifico per l'autorizzazione quando Claude ha bisogno dell'approvazione dell'autorizzazione e una notifica diversa quando Claude è stato inattivo:2049Utilizzare matcher separati per eseguire gestori diversi a seconda del tipo di notifica. Questa configurazione attiva uno script di avviso specifico per l'autorizzazione quando Claude ha bisogno dell'approvazione dell'autorizzazione e una notifica diversa quando Claude è stato inattivo:

2022 2050

2079 Input di SubagentStart2107 Input di SubagentStart

2080</h4>2108</h4>

2081 2109

2082Oltre ai [campi di input comuni](#common-input-fields), gli hook SubagentStart ricevono `agent_id` con l'identificatore univoco per il subagent e `agent_type` con il nome dell'agente (agenti incorporati come `"general-purpose"`, `"Explore"`, `"Plan"` o nomi di agenti personalizzati).2110Oltre ai [campi di input comuni](#common-input-fields), gli hook SubagentStart ricevono `agent_id` con l'identificatore univoco per il subagent e `agent_type` con il nome dell'agente che il matcher filtra.

2083 2111

2084```json theme={null}2112```json theme={null}

2085{2113{

2559Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, gli hook CwdChanged possono restituire `watchPaths` per impostare dinamicamente quali percorsi di file [FileChanged](#filechanged) monitora:2587Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, gli hook CwdChanged possono restituire `watchPaths` per impostare dinamicamente quali percorsi di file [FileChanged](#filechanged) monitora:

2560 2588

2561| Campo | Descrizione |2589| Campo | Descrizione |

2562| :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2590| :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2563| `watchPaths` | Array di percorsi assoluti. Sostituisce l'elenco di monitoraggio dinamico corrente (i percorsi dalla configurazione del `matcher` vengono sempre monitorati). Restituire un array vuoto cancella l'elenco dinamico, che è tipico quando si entra in una nuova directory |2591| `watchPaths` | Array di percorsi assoluti. Sostituisce l'elenco di monitoraggio dinamico corrente. I percorsi dalla configurazione del `matcher` vengono sempre monitorati. Restituire un array vuoto cancella l'elenco dinamico, che è tipico quando si entra in una nuova directory |

2564 2592

2565Gli hook CwdChanged non hanno controllo della decisione. Non possono bloccare il cambio di directory.2593Gli hook CwdChanged non hanno controllo della decisione. Non possono bloccare il cambio di directory.

2566 2594

2584Oltre ai [campi di input comuni](#common-input-fields), gli hook FileChanged ricevono `file_path` e `event`.2612Oltre ai [campi di input comuni](#common-input-fields), gli hook FileChanged ricevono `file_path` e `event`.

2585 2613

2586| Campo | Descrizione |2614| Campo | Descrizione |

2587| :---------- | :------------------------------------------------------------------------------------------------- |2615| :---------- | :---------------------------------------------------------------------------------------------------------------- |

2590 2618

2591```json theme={null}2619```json theme={null}

2592{2620{

2606Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, gli hook FileChanged possono restituire `watchPaths` per aggiornare dinamicamente quali percorsi di file vengono monitorati:2634Oltre ai [campi di output JSON](#json-output) disponibili per tutti gli hook, gli hook FileChanged possono restituire `watchPaths` per aggiornare dinamicamente quali percorsi di file vengono monitorati:

2607 2635

2608| Campo | Descrizione |2636| Campo | Descrizione |

2609| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |2637| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2610| `watchPaths` | Array di percorsi assoluti. Sostituisce l'elenco di monitoraggio dinamico corrente (i percorsi dalla configurazione del `matcher` vengono sempre monitorati). Utilizzare questo quando lo script del hook scopre file aggiuntivi da monitorare in base al file modificato |2638| `watchPaths` | Array di percorsi assoluti. Sostituisce l'elenco di monitoraggio dinamico corrente. I percorsi dalla configurazione del `matcher` vengono sempre monitorati. Utilizzare questo quando lo script del hook scopre file aggiuntivi da monitorare in base al file modificato |

2611 2639

2612Gli hook FileChanged non hanno controllo della decisione. Non possono bloccare il cambio di file dall'occorrenza.2640Gli hook FileChanged non hanno controllo della decisione. Non possono bloccare il cambio di file dall'occorrenza.

2613 2641

2615 WorktreeCreate2643 WorktreeCreate

2616</h3>2644</h3>

2617 2645

2618Quando si esegue `claude --worktree` o un [subagent utilizza `isolation: "worktree"`](/it/sub-agents#choose-the-subagent-scope), Claude Code crea una copia di lavoro isolata utilizzando `git worktree`. Se si configura un hook WorktreeCreate, sostituisce il comportamento git predefinito, consentendo di utilizzare un sistema di controllo della versione diverso come SVN, Perforce o Mercurial.2646Viene eseguito quando un worktree sta per essere creato, sia da `claude --worktree` che da un [subagent che utilizza `isolation: "worktree"`](/it/sub-agents#choose-the-subagent-scope). Per impostazione predefinita Claude Code crea la copia di lavoro isolata con `git worktree`. Configurando un hook WorktreeCreate si sostituisce quel comportamento git predefinito, consentendo di utilizzare un sistema di controllo della versione diverso come SVN, Perforce o Mercurial.

2619 2647

2620Poiché l'hook sostituisce completamente il comportamento predefinito, [`.worktreeinclude`](/it/worktrees#copy-gitignored-files-into-worktrees) non viene elaborato. Se è necessario copiare i file di configurazione locali come `.env` nel nuovo worktree, farlo all'interno dello script del hook.2648Poiché l'hook sostituisce completamente il comportamento predefinito, [`.worktreeinclude`](/it/worktrees#copy-gitignored-files-into-worktrees) non viene elaborato. Se è necessario copiare i file di configurazione locali come `.env` nel nuovo worktree, farlo all'interno dello script del hook.

2621 2649

2646 Input di WorktreeCreate2674 Input di WorktreeCreate

2647</h4>2675</h4>

2648 2676

2649Oltre ai [campi di input comuni](#common-input-fields), gli hook WorktreeCreate ricevono il campo `name`. Questo è un identificatore slug per il nuovo worktree, specificato dall'utente o generato automaticamente (ad esempio, `bold-oak-a3f2`).2677Oltre ai [campi di input comuni](#common-input-fields), gli hook WorktreeCreate ricevono il campo `name`. Questo è un identificatore slug per il nuovo worktree, specificato dall'utente o generato automaticamente, ad esempio `bold-oak-a3f2`.

2650 2678

2651```json theme={null}2679```json theme={null}

2652{2680{

2673 WorktreeRemove2701 WorktreeRemove

2674</h3>2702</h3>

2675 2703

2676La controparte di pulizia di [WorktreeCreate](#worktreecreate). Questo hook si attiva quando un worktree viene rimosso, sia quando si esce da una sessione `--worktree` e si sceglie di rimuoverla, sia quando un subagent con `isolation: "worktree"` termina. Per i worktree basati su git, Claude gestisce la pulizia automaticamente con `git worktree remove`. Se si è configurato un hook WorktreeCreate per un sistema di controllo della versione non-git, accoppiarlo con un hook WorktreeRemove per gestire la pulizia. Senza uno, la directory del worktree viene lasciata su disco.2704Viene eseguito quando un worktree sta per essere rimosso, sia quando si esce da una sessione `--worktree` e si sceglie di rimuoverla, sia quando un subagent con `isolation: "worktree"` termina. Questa è la controparte di pulizia di [WorktreeCreate](#worktreecreate).

2705

2706Per i worktree basati su git, Claude Code gestisce la pulizia automaticamente con `git worktree remove`. Se si è configurato un hook WorktreeCreate per un sistema di controllo della versione non-git, accoppiarlo con un hook WorktreeRemove per gestire la pulizia. Senza uno, la directory del worktree viene lasciata su disco.

2677 2707

2678Claude Code passa il percorso restituito da WorktreeCreate come `worktree_path` nell'input del hook. Questo esempio legge quel percorso e rimuove la directory:2708Claude Code passa il percorso restituito da WorktreeCreate come `worktree_path` nell'input del hook. Questo esempio legge quel percorso e rimuove la directory:

2679 2709

3062 3092

3063Se hai bisogno di un controllo più fine su qualsiasi evento, utilizza un [hook di comando](#command-hook-fields) con i campi per evento descritti in [Controllo delle decisioni](#decision-control).3093Se hai bisogno di un controllo più fine su qualsiasi evento, utilizza un [hook di comando](#command-hook-fields) con i campi per evento descritti in [Controllo delle decisioni](#decision-control).

3064 3094

3065<h3 id="example-multi-criteria-stop-hook">3095<h3 id="check-multiple-conditions-before-stopping">

3066 Esempio: Hook Stop con criteri multipli3096 Controllare più condizioni prima di fermarsi

3067</h3>3097</h3>

3068 3098

3069Questo hook `Stop` utilizza un prompt dettagliato per controllare tre condizioni prima di consentire a Claude di fermarsi. Se `"ok"` è `false`, Claude continua a lavorare con il motivo fornito come sua prossima istruzione. Gli hook `SubagentStop` utilizzano lo stesso formato per valutare se un [subagent](/it/sub-agents) dovrebbe fermarsi:3099Questo hook `Stop` utilizza un prompt dettagliato per controllare tre condizioni prima di consentire a Claude di fermarsi. Gli hook `SubagentStop` utilizzano lo stesso formato per valutare se un [subagent](/it/sub-agents) dovrebbe fermarsi. Se `"ok"` è `false`, Claude continua a lavorare con il motivo fornito come sua prossima istruzione:

3070 3100

3071```json theme={null}3101```json theme={null}

3072{3102{

3190 3220

3191Le notifiche di completamento degli hook asincroni sono soppresse per impostazione predefinita. Per vederle, abilitare la modalità verbose con `Ctrl+O` o avviare Claude Code con `--verbose`.3221Le notifiche di completamento degli hook asincroni sono soppresse per impostazione predefinita. Per vederle, abilitare la modalità verbose con `Ctrl+O` o avviare Claude Code con `--verbose`.

3192 3222

3193<h3 id="example-run-tests-after-file-changes">3223<h3 id="run-tests-after-file-changes">

3194 Esempio: eseguire i test dopo le modifiche ai file3224 Eseguire i test dopo le modifiche ai file

3195</h3>3225</h3>

3196 3226

3197Questo hook avvia una suite di test in background ogni volta che Claude scrive un file, quindi segnala i risultati a Claude quando i test terminano. Salvare questo script in `.claude/hooks/run-tests-async.sh` nel progetto e renderlo eseguibile con `chmod +x`:3227Questo hook avvia una suite di test in background ogni volta che Claude scrive un file, quindi segnala i risultati a Claude quando i test terminano. Salvare questo script in `.claude/hooks/run-tests-async.sh` nel progetto e renderlo eseguibile con `chmod +x`:

3285 Strumento Windows PowerShell3315 Strumento Windows PowerShell

3286</h2>3316</h2>

3287 3317

3288Su Windows, è possibile eseguire singoli hook in PowerShell impostando `"shell": "powershell"` su un command hook. Gli hook generano PowerShell direttamente, quindi questo funziona indipendentemente dal fatto che `CLAUDE_CODE_USE_POWERSHELL_TOOL` sia impostato. Claude Code rileva automaticamente `pwsh.exe` (PowerShell 7+) con un fallback a `powershell.exe` (5.1).3318Su Windows, è possibile eseguire singoli hook in PowerShell impostando `"shell": "powershell"` su un command hook. Gli hook generano PowerShell direttamente, quindi questo funziona indipendentemente dal fatto che `CLAUDE_CODE_USE_POWERSHELL_TOOL` sia impostato. Claude Code rileva automaticamente `pwsh.exe`, l'eseguibile di PowerShell 7 e versioni successive, e ricade su `powershell.exe` per Windows PowerShell 5.1.

3289 3319

3290```json theme={null}3320```json theme={null}

3291{3321{

3306}3336}

3307```3337```

3308 3338

3309Per fare riferimento alla directory radice del progetto da un comando in forma shell di PowerShell, leggerla come variabile di ambiente con `$env:CLAUDE_PROJECT_DIR`. PowerShell tratta la forma nuda `${CLAUDE_PROJECT_DIR}` come una variabile locale, non come una ricerca di ambiente, e Claude Code sostituisce quel segnaposto in forma shell solo per [hook di plugin](#reference-scripts-by-path). Per un hook definito in `settings.json`, utilizzare la forma `$env:` oppure passare a [forma exec](#exec-form-and-shell-form), dove `${CLAUDE_PROJECT_DIR}` viene sostituito in ogni elemento `args` indipendentemente da dove l'hook è definito.3339Per fare riferimento alla directory radice del progetto da un comando in forma shell di PowerShell, scrivere `${CLAUDE_PROJECT_DIR}` o `$env:CLAUDE_PROJECT_DIR`. A partire dalla v2.1.198, Claude Code riscrive i segnaposti `${CLAUDE_PROJECT_DIR}`, `${CLAUDE_PLUGIN_ROOT}` e `${CLAUDE_PLUGIN_DATA}` in un comando in forma shell di PowerShell nella forma `${env:NAME}` di PowerShell, indipendentemente dal fatto che l'hook sia definito in `settings.json`, un plugin o una skill. PowerShell quindi risolve il valore dall'ambiente esportato dopo l'analisi, quindi il segnaposto funziona all'interno di stringhe tra virgolette doppie ma non all'interno di stringhe tra virgolette singole, dove PowerShell non espande mai le variabili.

3340

3341Prima della v2.1.198, questa riscrittura si applicava solo agli hook dei plugin. Nelle versioni precedenti, un hook `settings.json` necessita della forma `$env:` o della [forma exec](#exec-form-and-shell-form), dove `${CLAUDE_PROJECT_DIR}` viene sostituito in ogni elemento `args` indipendentemente da dove l'hook è definito.

3342

3343Non scrivere la forma nuda `$CLAUDE_PROJECT_DIR` in un hook di PowerShell. PowerShell la analizza come una variabile locale non definita e la risolve in `$null`, il che lascia il percorso dello script senza il prefisso della directory radice del progetto. Claude Code non riscrive quella forma; invece registra un avviso nel [log di debug](#debug-hooks).

3310 3344

3311L'esempio seguente mostra un hook `settings.json` che esegue uno script di progetto con la forma `$env:`:3345L'esempio seguente mostra un hook `settings.json` che esegue uno script di progetto con la forma `$env:`, che funziona su ogni versione:

3312 3346

3313```json theme={null}3347```json theme={null}

3314{3348{

hooks-guide.md +36 −32

Details

87 87

88Gli hooks vi permettono di eseguire codice in punti chiave del ciclo di vita di Claude Code: formattare file dopo le modifiche, bloccare comandi prima che si eseguano, inviare notifiche quando Claude ha bisogno di input, iniettare contesto all'inizio della sessione, e altro ancora. Per l'elenco completo degli eventi hook, consultate il [riferimento Hooks](/it/hooks#hook-lifecycle).88Gli hooks vi permettono di eseguire codice in punti chiave del ciclo di vita di Claude Code: formattare file dopo le modifiche, bloccare comandi prima che si eseguano, inviare notifiche quando Claude ha bisogno di input, iniettare contesto all'inizio della sessione, e altro ancora. Per l'elenco completo degli eventi hook, consultate il [riferimento Hooks](/it/hooks#hook-lifecycle).

89 89

~~90Ogni esempio include un blocco di configurazione pronto all'uso che aggiungete a un [file di impostazioni](#configure-hook-location). I modelli più comuni:~~90Ogni esempio include un blocco di configurazione pronto all'uso che aggiungete a un [file di impostazioni](#configure-hook-location).

~~92* [Ricevere una notifica quando Claude ha bisogno di input](#get-notified-when-claude-needs-input)~~

~~93* [Formattare automaticamente il codice dopo le modifiche](#auto-format-code-after-edits)~~

~~94* [Bloccare le modifiche ai file protetti](#block-edits-to-protected-files)~~

~~95* [Reiniettare il contesto dopo la compattazione](#re-inject-context-after-compaction)~~

~~96* [Controllare le modifiche di configurazione](#audit-configuration-changes)~~

~~97* [Ricaricare l'ambiente quando la directory o i file cambiano](#reload-environment-when-directory-or-files-change)~~

~~98* [Approvare automaticamente specifici prompt di autorizzazione](#auto-approve-specific-permission-prompts)~~

99 91

100Per un esempio di produzione di hooks che eseguono una revisione di un modello separato e reinseriscono i risultati nella sessione, consultate [come il plugin `security-guidance` si integra con Claude Code](/it/security-guidance#how-the-plugin-integrates-with-claude-code).92Per un esempio di produzione di hooks che eseguono una revisione di un modello separato e reinseriscono i risultati nella sessione, consultate [come il plugin `security-guidance` si integra con Claude Code](/it/security-guidance#how-the-plugin-integrates-with-claude-code).

101 93

182Il matcher vuoto si attiva su tutti i tipi di notifica. Per attivarsi solo su eventi specifici, impostatelo a uno di questi valori:174Il matcher vuoto si attiva su tutti i tipi di notifica. Per attivarsi solo su eventi specifici, impostatelo a uno di questi valori:

183 175

184| Matcher | Si attiva quando |176| Matcher | Si attiva quando |

185| :--------------------- | :---------------------------------------------------------- |177| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |

184| `agent_needs_input` | Una sessione in background inizia ad aspettare il vostro input. Si attiva solo mentre la [visualizzazione agente](/it/agent-view) è aperta |

185| `agent_completed` | Una sessione in background finisce o fallisce. Si attiva solo mentre la [visualizzazione agente](/it/agent-view) è aperta |

186

187I matcher `agent_needs_input` e `agent_completed` richiedono Claude Code v2.1.198 o successivo.

192 188

193Digitate `/hooks` e selezionate `Notification` per confermare che l'hook è registrato. Per lo schema completo dell'evento, consultate il [riferimento Notification](/it/hooks#notification).189Digitate `/hooks` e selezionate `Notification` per confermare che l'hook è registrato. Per lo schema completo dell'evento, consultate il [riferimento Notification](/it/hooks#notification).

194 190

198 194

199Eseguite automaticamente [Prettier](https://prettier.io/) su ogni file che Claude modifica, in modo che la formattazione rimanga coerente senza intervento manuale.195Eseguite automaticamente [Prettier](https://prettier.io/) su ogni file che Claude modifica, in modo che la formattazione rimanga coerente senza intervento manuale.

200 196

201Questo hook utilizza l'evento `PostToolUse` con un matcher `Edit|Write`, quindi si esegue solo dopo gli strumenti di modifica dei file. {/* min-version: 2.1.191 */}Su Claude Code v2.1.191 o successivo potete anche scrivere il matcher come `Edit,Write`, poiché `|` e `,` sono separatori di elenco intercambiabili per i matcher dei nomi degli strumenti su quelle versioni. Il comando estrae il percorso del file modificato con [`jq`](https://jqlang.github.io/jq/) e lo passa a Prettier. Aggiungete questo a `.claude/settings.json` nella radice del vostro progetto:197Questo hook utilizza l'evento `PostToolUse` con un matcher `Edit|Write`, quindi si esegue solo dopo gli strumenti di modifica dei file. Il comando estrae il percorso del file modificato con [`jq`](https://jqlang.github.io/jq/) e lo passa a Prettier. Aggiungete questo a `.claude/settings.json` nella radice del vostro progetto:

202 198

203```json theme={null}199```json theme={null}

204{200{

218}214}

219```215```

220 216

217Su Claude Code v2.1.191 o successivo potete anche scrivere il matcher come `Edit,Write`, poiché `|` e `,` sono separatori di elenco intercambiabili per i matcher dei nomi degli strumenti su quelle versioni.

218

221<Note>219<Note>

222 Gli esempi Bash in questa pagina utilizzano `jq` per l'analisi JSON. Installatelo con `brew install jq` (macOS), `apt-get install jq` (Debian/Ubuntu), o consultate i [download di `jq`](https://jqlang.github.io/jq/download/).220 Gli esempi Bash in questa pagina utilizzano `jq` per l'analisi JSON. Installatelo con `brew install jq` su macOS, `apt-get install jq` su Debian e Ubuntu, o consultate i [download di `jq`](https://jqlang.github.io/jq/download/).

223</Note>221</Note>

224 222

225<h3 id="block-edits-to-protected-files">223<h3 id="block-edits-to-protected-files">

254 ```252 ```

255 </Step>253 </Step>

256 254

257 <Step title="Rendere lo script eseguibile (macOS/Linux)">255 <Step title="Rendere lo script eseguibile su macOS e Linux">

258 Gli script degli hook devono essere eseguibili affinché Claude Code li esegua:256 Gli script degli hook devono essere eseguibili affinché Claude Code li esegua:

259 257

260 ```bash theme={null}258 ```bash theme={null}

378 376

379Eseguite `direnv allow` una volta in ogni directory che ha un `.envrc` in modo che direnv sia autorizzato a caricarlo. Se utilizzate devbox o nix invece di direnv, lo stesso modello funziona con `devbox shellenv` o `devbox global shellenv` al posto di `direnv export bash`.377Eseguite `direnv allow` una volta in ogni directory che ha un `.envrc` in modo che direnv sia autorizzato a caricarlo. Se utilizzate devbox o nix invece di direnv, lo stesso modello funziona con `devbox shellenv` o `devbox global shellenv` al posto di `direnv export bash`.

380 378

381Per reagire a file specifici invece di ogni cambio di directory, utilizzate `FileChanged` con un `matcher` che elenca i nomi dei file da guardare, separati da `|`. Per costruire l'elenco di osservazione, questo valore viene diviso in nomi di file letterali piuttosto che valutato come regex. Consultate [FileChanged](/it/hooks#filechanged) per come lo stesso valore filtra anche quali gruppi di hook si eseguono quando un file cambia. Questo esempio guarda `.envrc` e `.env` nella directory di lavoro:379Per reagire a file specifici invece di ogni cambio di directory, utilizzate `FileChanged` con un `matcher` che elenca i nomi dei file da guardare, separati da `|`. Quando costruite l'elenco di osservazione, Claude Code divide questo valore in nomi di file letterali piuttosto che valutarlo come regex. Consultate [FileChanged](/it/hooks#filechanged) per come lo stesso valore filtra anche quali gruppi di hook si eseguono quando un file cambia. Questo esempio guarda `.envrc` e `.env` nella directory di lavoro:

382 380

383```json theme={null}381```json theme={null}

384{382{

564 Output dell'hook562 Output dell'hook

565</h4>563</h4>

566 564

567Il vostro script dice a Claude Code cosa fare dopo scrivendo su stdout o stderr e uscendo con un codice specifico. Ad esempio, un hook `PreToolUse` che vuole bloccare un comando:565Il vostro script dice a Claude Code cosa fare dopo scrivendo su stdout o stderr e uscendo con un codice specifico. Il seguente hook `PreToolUse` blocca un comando:

568 566

569```bash theme={null}567```bash theme={null}

570#!/bin/bash568#!/bin/bash

619 617

620Altri eventi utilizzano modelli di decisione diversi. Ad esempio, gli hook `PostToolUse` e `Stop` utilizzano un campo `decision: "block"` di livello superiore, mentre `PermissionRequest` utilizza `hookSpecificOutput.decision.behavior`. Consultate la [tabella di riepilogo](/it/hooks#decision-control) nel riferimento per una suddivisione completa per evento.618Altri eventi utilizzano modelli di decisione diversi. Ad esempio, gli hook `PostToolUse` e `Stop` utilizzano un campo `decision: "block"` di livello superiore, mentre `PermissionRequest` utilizza `hookSpecificOutput.decision.behavior`. Consultate la [tabella di riepilogo](/it/hooks#decision-control) nel riferimento per una suddivisione completa per evento.

621 619

622Per gli hook `UserPromptSubmit`, utilizzate `additionalContext` invece per iniettare testo nel contesto di Claude. Gli hooks basati su prompt (`type: "prompt"`) gestiscono l'output diversamente: consultate [Prompt-based hooks](#prompt-based-hooks).620Per gli hook `UserPromptSubmit`, utilizzate `additionalContext` invece per iniettare testo nel contesto di Claude.

621

622Gli hooks con `type: "prompt"` gestiscono l'output diversamente: consultate [Prompt-based hooks](#prompt-based-hooks).

623 623

624<h3 id="filter-hooks-with-matchers">624<h3 id="filter-hooks-with-matchers">

625 Filtrare gli hooks con i matcher625 Filtrare gli hooks con i matcher

626</h3>626</h3>

627 627

628Senza un matcher, un hook si attiva su ogni occorrenza del suo evento. I matcher vi permettono di restringerlo. Ad esempio, se volete eseguire un formattatore solo dopo le modifiche ai file (non dopo ogni chiamata di strumento), aggiungete un matcher al vostro hook `PostToolUse`:628Senza un matcher, un hook si attiva su ogni occorrenza del suo evento. I matcher vi permettono di restringerlo. Ad esempio, se volete eseguire un formattatore solo dopo le modifiche ai file, non dopo ogni chiamata di strumento, aggiungete un matcher al vostro hook `PostToolUse`:

629 629

630```json theme={null}630```json theme={null}

631{631{

659| `Notification` | tipo di notifica | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response` |659| `Notification` | tipo di notifica | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed` |

670| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `MessageDisplay` | nessun supporto matcher | si attiva sempre su ogni occorrenza |670| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `MessageDisplay` | nessun supporto matcher | si attiva sempre su ogni occorrenza |

671 671

672Alcuni altri esempi che mostrano i matcher su diversi tipi di evento:672Le schede sottostanti mostrano alcuni altri matcher su diversi tipi di evento.

673 673

674<Tabs>674<Tabs>

675 <Tab title="Registrare ogni comando Bash">675 <Tab title="Registrare ogni comando Bash">

719 </Tab>719 </Tab>

720 720

721 <Tab title="Pulire alla fine della sessione">721 <Tab title="Pulire alla fine della sessione">

722 L'evento `SessionEnd` supporta i matcher sul motivo per cui la sessione è terminata. Questo hook si attiva solo su `clear` (quando eseguite `/clear`), non su uscite normali:722 L'evento `SessionEnd` supporta i matcher sul motivo per cui la sessione è terminata. Questo hook si attiva solo sul motivo `clear`, impostato quando eseguite `/clear`, non su uscite normali:

723 723

724 ```json theme={null}724 ```json theme={null}

725 {725 {

753 753

754Il campo `if` utilizza la [permission rule syntax](/it/permissions) per filtrare gli hooks per nome dello strumento e argomenti insieme, in modo che il processo dell'hook si generi solo quando la chiamata dello strumento corrisponde. Questo va oltre il `matcher`, che filtra a livello di gruppo per nome dello strumento solo.754Il campo `if` utilizza la [permission rule syntax](/it/permissions) per filtrare gli hooks per nome dello strumento e argomenti insieme, in modo che il processo dell'hook si generi solo quando la chiamata dello strumento corrisponde. Questo va oltre il `matcher`, che filtra a livello di gruppo per nome dello strumento solo.

755 755

756Ad esempio, per eseguire un hook solo quando Claude utilizza comandi `git` piuttosto che tutti i comandi Bash:756Ad esempio, questa configurazione esegue un hook solo quando Claude utilizza comandi `git` piuttosto che tutti i comandi Bash:

757 757

758```json theme={null}758```json theme={null}

759{759{

807 807

808Eseguite [`/hooks`](/it/hooks#the-%2Fhooks-menu) in Claude Code per sfogliare tutti gli hooks configurati raggruppati per evento. Per disabilitare gli hooks, impostate `"disableAllHooks": true` nel vostro file di impostazioni. Gli hooks configurati nelle impostazioni gestite si eseguono comunque a meno che `disableAllHooks` non sia impostato anche lì.808Eseguite [`/hooks`](/it/hooks#the-%2Fhooks-menu) in Claude Code per sfogliare tutti gli hooks configurati raggruppati per evento.

809

810Per disabilitare gli hooks, impostate `"disableAllHooks": true` nel vostro file di impostazioni. Gli hooks configurati nelle impostazioni gestite si eseguono comunque a meno che `disableAllHooks` non sia impostato anche lì.

809 811

810Se modificate i file di impostazioni direttamente mentre Claude Code è in esecuzione, il file watcher normalmente raccoglie i cambiamenti degli hook automaticamente.812Se modificate i file di impostazioni direttamente mentre Claude Code è in esecuzione, il file watcher normalmente raccoglie i cambiamenti degli hook automaticamente.

811 813

925 Limitazioni927 Limitazioni

926</h3>928</h3>

927 929

930Tenete presenti questi vincoli quando progettate gli hook:

931

928* Gli hook di comando comunicano solo attraverso stdout, stderr e codici di uscita. Non possono attivare comandi `/` o chiamate di strumenti. Il testo restituito tramite `additionalContext` viene iniettato come un promemoria di sistema che Claude legge come testo semplice. Gli HTTP hooks comunicano attraverso il corpo della risposta invece.932* Gli hook di comando comunicano solo attraverso stdout, stderr e codici di uscita. Non possono attivare comandi `/` o chiamate di strumenti. Il testo restituito tramite `additionalContext` viene iniettato come un promemoria di sistema che Claude legge come testo semplice. Gli HTTP hooks comunicano attraverso il corpo della risposta invece.

929* I timeout dell'hook variano in base al tipo. Sovrascrivete per hook con il campo `timeout` in secondi.933* I timeout dell'hook variano in base al tipo. Sovrascrivete per hook con il campo `timeout` in secondi.

930 * `command`, `http`, `mcp_tool`: 10 minuti. `UserPromptSubmit` riduce questi a 30 secondi, e `MessageDisplay` li riduce a 10 secondi.934 * `command`, `http`, `mcp_tool`: 10 minuti. `UserPromptSubmit` riduce questi a 30 secondi, e `MessageDisplay` li riduce a 10 secondi.

931 * `prompt`: 30 secondi.935 * `prompt`: 30 secondi.

932 * `agent`: 60 secondi.936 * `agent`: 60 secondi.

933* Gli hook `PostToolUse` non possono annullare le azioni poiché lo strumento è già stato eseguito.937* Gli hook `PostToolUse` non possono annullare le azioni poiché lo strumento è già stato eseguito.

934* Gli hook `PermissionRequest` non si attivano in [modalità non interattiva](/it/headless) (`-p`). Utilizzate gli hook `PreToolUse` per le decisioni di autorizzazione automatizzate.938* Gli hook `PermissionRequest` non si attivano in [modalità non interattiva](/it/headless) con il flag `-p`. Utilizzate gli hook `PreToolUse` per le decisioni di autorizzazione automatizzate.

935* Gli hook `Stop` si attivano ogni volta che Claude finisce di rispondere, non solo al completamento dell'attività. Non si attivano su interruzioni dell'utente. Gli errori API attivano [StopFailure](/it/hooks#stopfailure) invece.939* Gli hook `Stop` si attivano ogni volta che Claude finisce di rispondere, non solo al completamento dell'attività. Non si attivano su interruzioni dell'utente. Gli errori API attivano [StopFailure](/it/hooks#stopfailure) invece.

936* Quando più hook PreToolUse restituiscono [`updatedInput`](/it/hooks#pretooluse) per riscrivere gli argomenti di uno strumento, l'ultimo a terminare vince. Poiché gli hook si eseguono in parallelo, l'ordine è non deterministico. Evitate di avere più di un hook che modifica l'input dello stesso strumento.940* Quando più hook `PreToolUse` restituiscono [`updatedInput`](/it/hooks#pretooluse) per riscrivere gli argomenti di uno strumento, l'ultimo a terminare vince. Poiché gli hook si eseguono in parallelo, l'ordine è non deterministico. Evitate di avere più di un hook che modifica l'input dello stesso strumento.

937 941

938<h3 id="hooks-and-permission-modes">942<h3 id="hooks-and-permission-modes">

939 Hooks e modalità di autorizzazione943 Hooks e modalità di autorizzazione

940</h3>944</h3>

941 945

942Gli hook PreToolUse si attivano prima di qualsiasi controllo della modalità di autorizzazione. Un hook che restituisce `permissionDecision: "deny"` blocca lo strumento anche in modalità `bypassPermissions` o con `--dangerously-skip-permissions`. Questo vi permette di applicare una policy che gli utenti non possono aggirare cambiando la loro modalità di autorizzazione.946Gli hook `PreToolUse` si attivano prima di qualsiasi controllo della modalità di autorizzazione. Un hook che restituisce `permissionDecision: "deny"` blocca lo strumento anche in modalità `bypassPermissions` o con `--dangerously-skip-permissions`. Questo vi permette di applicare una policy che gli utenti non possono aggirare cambiando la loro modalità di autorizzazione.

943 947

944Il contrario non è vero: un hook che restituisce `"allow"` non aggira le regole di negazione dalle impostazioni. Gli hooks possono stringere le restrizioni ma non allentarle oltre quello che le regole di autorizzazione consentono.948Il contrario non è vero: un hook che restituisce `"allow"` non aggira le regole di negazione dalle impostazioni. Gli hook possono stringere le restrizioni ma non allentarle oltre quello che le regole di autorizzazione consentono.

945 949

946<h3 id="hook-not-firing">950<h3 id="hook-not-firing">

947 Hook non si attiva951 Hook non si attiva

950L'hook è configurato ma non si esegue mai.954L'hook è configurato ma non si esegue mai.

951 955

952* Eseguite `/hooks` e confermate che l'hook appare sotto l'evento corretto956* Eseguite `/hooks` e confermate che l'hook appare sotto l'evento corretto

953* Controllate che il modello del matcher corrisponda esattamente al nome dello strumento (i matcher sono sensibili alle maiuscole)957* Controllate che il modello del matcher corrisponda esattamente al nome dello strumento. I matcher sono sensibili alle maiuscole

954* Verificate che state attivando il tipo di evento corretto (ad esempio, `PreToolUse` si attiva prima dell'esecuzione dello strumento, `PostToolUse` si attiva dopo)958* Verificate che state attivando il tipo di evento corretto: `PreToolUse` si attiva prima dell'esecuzione dello strumento, `PostToolUse` si attiva dopo

955* Se utilizzate gli hook `PermissionRequest` in modalità non interattiva (`-p`), passate a `PreToolUse` invece959* Se utilizzate gli hook `PermissionRequest` in modalità non interattiva con il flag `-p`, passate a `PreToolUse` invece

956 960

957<h3 id="hook-error-in-output">961<h3 id="hook-error-in-output">

958 Errore dell'hook nell'output962 Errore dell'hook nell'output

976Avete modificato un file di impostazioni ma gli hooks non appaiono nel menu.980Avete modificato un file di impostazioni ma gli hooks non appaiono nel menu.

977 981

978* Le modifiche ai file vengono normalmente raccolte automaticamente. Se non sono apparse dopo alcuni secondi, il file watcher potrebbe aver perso il cambiamento: riavviate la vostra sessione per forzare un ricaricamento.982* Le modifiche ai file vengono normalmente raccolte automaticamente. Se non sono apparse dopo alcuni secondi, il file watcher potrebbe aver perso il cambiamento: riavviate la vostra sessione per forzare un ricaricamento.

979* Verificate che il vostro JSON sia valido (le virgole finali e i commenti non sono consentiti)983* Verificate che il vostro JSON sia valido: le virgole finali e i commenti non sono consentiti

980* Confermate che il file di impostazioni è nella posizione corretta: `.claude/settings.json` per gli hook del progetto, `~/.claude/settings.json` per gli hook globali984* Confermate che il file di impostazioni è nella posizione corretta: `.claude/settings.json` per gli hook del progetto, `~/.claude/settings.json` per gli hook globali

981 985

982<h3 id="stop-hook-hits-the-block-cap">986<h3 id="stop-hook-hits-the-block-cap">

985 989

986Claude continua a lavorare invece di fermarsi, quindi termina il turno con un avviso che l'hook Stop ha bloccato troppe volte consecutive.990Claude continua a lavorare invece di fermarsi, quindi termina il turno con un avviso che l'hook Stop ha bloccato troppe volte consecutive.

987 991

988Claude Code ignora un hook Stop dopo che ha bloccato 8 volte di fila senza progresso. Il vostro script di hook deve controllare se ha già attivato una continuazione. Analizzate il campo `stop_hook_active` dall'input JSON e uscite presto se è `true`:992Claude Code ignora un hook Stop dopo che ha bloccato otto volte di fila senza progresso. Il vostro script di hook deve controllare se ha già attivato una continuazione. Analizzate il campo `stop_hook_active` dall'input JSON e uscite presto se è `true`:

989 993

990```bash theme={null}994```bash theme={null}

991#!/bin/bash995#!/bin/bash

1004 1008

1005Claude Code mostra un errore di analisi JSON anche se il vostro script di hook produce JSON valido.1009Claude Code mostra un errore di analisi JSON anche se il vostro script di hook produce JSON valido.

1006 1010

1007Quando Claude Code esegue un hook di comando in forma shell (uno senza `args`), genera `sh -c` su macOS e Linux o Git Bash su Windows per impostazione predefinita. Questa shell è non interattiva, ma Git Bash e alcune configurazioni (come `BASH_ENV` che punta a `~/.bashrc`) comunque forniscono il vostro profilo. Se quel profilo contiene istruzioni `echo` incondizionate, l'output viene anteposto al vostro JSON dell'hook:1011Quando Claude Code esegue un hook di comando in forma shell (uno senza `args`), genera `sh -c` su macOS e Linux o Git Bash su Windows per impostazione predefinita. Questa shell è non interattiva, ma Git Bash e alcune configurazioni, come `BASH_ENV` che punta a `~/.bashrc`, comunque forniscono il vostro profilo. Se quel profilo contiene istruzioni `echo` incondizionate, l'output viene anteposto al vostro JSON dell'hook:

1008 1012

1009```text theme={null}1013```text theme={null}

1010Shell ready on arm641014Shell ready on arm64

how-claude-code-works.md +0 −1

Details

210I comandi integrati ti guidano anche attraverso la configurazione:210I comandi integrati ti guidano anche attraverso la configurazione:

211 211

212* `/init` ti guida attraverso la creazione di un CLAUDE.md per il tuo progetto212* `/init` ti guida attraverso la creazione di un CLAUDE.md per il tuo progetto

213* `/agents` ti aiuta a configurare subagents personalizzati

214* `/doctor` diagnostica i problemi comuni con la tua installazione213* `/doctor` diagnostica i problemi comuni con la tua installazione

215 214

216<h3 id="it’s-a-conversation">215<h3 id="it’s-a-conversation">

llm-gateway-protocol.md +9 −1

Details

106 Blocco di attribuzione del prompt di sistema106 Blocco di attribuzione del prompt di sistema

107</h2>107</h2>

108 108

109Claude Code antepone un breve blocco di attribuzione al prompt di sistema contenente la versione del client e un'impronta digitale derivata dalla conversazione. L'endpoint `api.anthropic.com` rimuove il blocco prima dell'elaborazione, quindi non influisce sul prompt caching di prima parte; qualsiasi altro upstream lo riceve come parte del prompt. Anthropic e gli endpoint Claude dei provider cloud lo leggono per l'attribuzione, quindi per ometterlo impostare [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/it/env-vars) piuttosto che rimuoverlo nel gateway.109Claude Code antepone un breve blocco di attribuzione al prompt di sistema contenente la versione del client e un'impronta digitale derivata dalla conversazione. L'endpoint `api.anthropic.com` rimuove il blocco prima dell'elaborazione quando arriva invariato come primo blocco di sistema, quindi non influisce sul prompt caching di prima parte. Qualsiasi altro upstream lo riceve come parte del prompt.

110

111La rimozione è posizionale, quindi funziona solo quando il gateway inoltra l'array `system` invariato. Per mantenere il blocco fuori dal prompt senza perdere altri contenuti di sistema:

112

113* Inoltrare l'array `system` esattamente come ricevuto, mantenendo il blocco per primo: anteporre un altro blocco di sistema, riordinare l'array o convertirlo in una singola stringa annulla la rimozione, e il blocco raggiunge quindi il modello e la chiave della cache del prompt.

114* Mantenere il blocco nella sua voce di array separata: l'endpoint tratta un blocco unito che inizia con l'intestazione di attribuzione come attribuzione nella sua interezza e scarta tutto ciò che vi è stato unito, incluso il resto del prompt di sistema.

115* Se il vostro gateway deve rimodellare il contenuto di sistema, impostare [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/it/env-vars) in modo che Claude Code ometta il blocco. Anthropic e gli endpoint Claude dei provider cloud leggono il blocco per l'attribuzione, quindi ometterlo nel client piuttosto che rimuoverlo o spostarlo nel gateway.

116

117Le richieste che raggiungono l'endpoint invariate non sono interessate.

110 118

111{/* min-version: 2.1.181 */}Da Claude Code v2.1.181, il blocco è stabile per la durata di una conversazione quando le richieste instradano attraverso un URL di base personalizzato, quindi una cache del prompt lato gateway basata sul corpo della richiesta completa funziona senza disabilitarla. Prima di v2.1.181 il blocco includeva un token per richiesta; su quelle versioni, impostare `CLAUDE_CODE_ATTRIBUTION_HEADER=0` se il vostro gateway implementa una tale cache.119{/* min-version: 2.1.181 */}Da Claude Code v2.1.181, il blocco è stabile per la durata di una conversazione quando le richieste instradano attraverso un URL di base personalizzato, quindi una cache del prompt lato gateway basata sul corpo della richiesta completa funziona senza disabilitarla. Prima di v2.1.181 il blocco includeva un token per richiesta; su quelle versioni, impostare `CLAUDE_CODE_ATTRIBUTION_HEADER=0` se il vostro gateway implementa una tale cache.

112 120

mcp.md +43 −0

Details

1041 Se incontrate frequentemente avvisi di output con server MCP specifici che non controllate, considerate di aumentare il limite `MAX_MCP_OUTPUT_TOKENS`. Potete anche chiedere all'autore del server di aggiungere l'annotazione `anthropic/maxResultSizeChars` o di impaginare le loro risposte. L'annotazione non ha effetto sugli strumenti che restituiscono contenuto di immagine; per quelli, aumentare `MAX_MCP_OUTPUT_TOKENS` è l'unica opzione.1041 Se incontrate frequentemente avvisi di output con server MCP specifici che non controllate, considerate di aumentare il limite `MAX_MCP_OUTPUT_TOKENS`. Potete anche chiedere all'autore del server di aggiungere l'annotazione `anthropic/maxResultSizeChars` o di impaginare le loro risposte. L'annotazione non ha effetto sugli strumenti che restituiscono contenuto di immagine; per quelli, aumentare `MAX_MCP_OUTPUT_TOKENS` è l'unica opzione.

1042</Warning>1042</Warning>

1043 1043

1044<h2 id="tool-input-schemas-with-a-root-level-combinator">

1045 Schemi di input degli strumenti con un combinatore a livello di radice

1046</h2>

1047

1048Alcuni server MCP dichiarano lo schema di input di uno strumento come un'unione JSON Schema, con `anyOf`, `oneOf`, o `allOf` al livello superiore dello schema. L'API Claude non accetta queste parole chiave alla radice dello schema. Accetta combinatori annidati all'interno di `properties`, che Claude Code invia senza modifiche.

1049

1050A partire da Claude Code v2.1.195, gli strumenti con un combinatore a livello di radice rimangono disponibili. Prima di inviare lo strumento all'API, Claude Code appiattisce lo schema in un singolo oggetto e antepone una frase alla descrizione dello strumento che dice a Claude quali gruppi di parametri appartengono insieme:

1051

1052* `allOf`: le proprietà di ogni ramo vengono unite, e l'elenco `required` di ogni ramo si applica ancora

1053* `anyOf` e `oneOf`: le proprietà di ogni ramo vengono unite, e l'elenco `required` di ogni ramo viene descritto nella descrizione dello strumento invece di essere applicato dallo schema

1054

1055Il tuo server riceve gli argomenti che Claude ha scelto, quindi continua a convalidare la combinazione lato server.

1056

1057Quando Claude Code non può produrre uno schema che l'API accetta, o su una distribuzione che non riceve la configurazione remota che abilita la riscrittura, come una macchina offline, salta quello strumento, registra il motivo nel log del server, e lascia gli altri strumenti del server disponibili. Le versioni precedenti a v2.1.195 saltano ogni strumento il cui schema di input ha un `anyOf`, `oneOf`, o `allOf` a livello di radice.

1058

1059<h2 id="require-approval-for-a-specific-tool">

1060 Richiedi approvazione per uno strumento specifico

1061</h2>

1062

1063Se stai costruendo un server MCP, puoi contrassegnare uno strumento come richiedente approvazione esplicita ad ogni chiamata impostando `_meta["anthropic/requiresUserInteraction"]` su `true` nella voce dello strumento nella risposta `tools/list`. Il valore deve essere il booleano JSON `true`; qualsiasi altro valore viene ignorato.

1064

1065Claude Code mostra il prompt di autorizzazione di quello strumento ad ogni chiamata, anche in modalità `acceptEdits`, `auto`, e `bypassPermissions` [permission modes](/it/permissions#permission-modes), e non offre un'opzione "non chiedere di nuovo" per esso. Le [regole di autorizzazione](/it/permissions#permission-rule-syntax) che corrispondono allo strumento non saltano il prompt neanche. In modalità `dontAsk`, che non chiede mai, Claude Code nega la chiamata invece.

1066

1067Il prompt deve raggiungere una persona. In modalità non interattiva con [`--permission-prompt-tool`](/it/cli-reference#cli-flags), un risultato `allow` dal prompt tool per uno strumento contrassegnato viene convertito in un deny con il messaggio `MCP tool requires user interaction; not supported via --permission-prompt-tool`. Il callback [`canUseTool`](/it/agent-sdk/permissions) dell'Agent SDK riceve queste chiamate e può approvarle, perché l'host SDK dovrebbe mostrarle a un utente.

1068

1069Utilizza questo per strumenti il cui prompt di autorizzazione è il punto stesso, come un passaggio di consenso o concessione di accesso dove l'approvazione automatica significherebbe che nessun umano ha mai accettato. Gli altri strumenti dello stesso server mantengono il loro comportamento di autorizzazione normale.

1070

1071La seguente voce `tools/list` contrassegna uno strumento come sempre richiedente approvazione.

1072

1073```json theme={null}

1074{

1075 "name": "grant_access",

1076 "description": "Requests access to a protected resource",

1077 "_meta": {

1078 "anthropic/requiresUserInteraction": true

1079 }

1080}

1081```

1082

1083L'annotazione `anthropic/requiresUserInteraction` richiede Claude Code v2.1.199 o successiva. Le versioni precedenti la ignorano e applicano il flusso di autorizzazione standard.

1084

1085Quando una sessione è connessa a [Remote Control](/it/remote-control) o a un host SDK, Claude Code contrassegna il prompt di autorizzazione come richiedente interazione dell'utente, in modo che il client mostri il prompt di autorizzazione dello strumento per te di rispondere invece di un'azione di approvazione con un tocco.

1086

1044<h2 id="respond-to-mcp-elicitation-requests">1087<h2 id="respond-to-mcp-elicitation-requests">

1045 Rispondi alle richieste di elicitazione MCP1088 Rispondi alle richieste di elicitazione MCP

1046</h2>1089</h2>

memory.md +1 −1

Details

235- Includi commenti di documentazione OpenAPI235- Includi commenti di documentazione OpenAPI

236```236```

237 237

238Le regole senza un campo `paths` vengono caricate incondizionatamente e si applicano a tutti i file. Le regole con ambito di percorso si attivano quando Claude legge file che corrispondono al modello, non ad ogni utilizzo dello strumento.238Le regole senza un campo `paths` vengono caricate incondizionatamente e si applicano a tutti i file. Le regole con ambito di percorso si attivano quando Claude legge file che corrispondono al modello, non ad ogni utilizzo dello strumento. A partire dalla v2.1.198, la corrispondenza funziona anche quando Claude raggiunge un file attraverso un percorso symlink alla directory del progetto, ad esempio in un checkout symlink.

239 239

240Usa modelli glob nel campo `paths` per abbinare i file per estensione, directory o qualsiasi combinazione:240Usa modelli glob nel campo `paths` per abbinare i file per estensione, directory o qualsiasi combinazione:

241 241

model-config.md +56 −10

Details

31 31

32| Alias del modello | Comportamento |32| Alias del modello | Comportamento |

33| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |33| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

34| **`default`** | Valore speciale che cancella qualsiasi override del modello e ripristina il modello consigliato per il tipo di account. Non è di per sé un alias del modello |34| **`default`** | Valore speciale che cancella qualsiasi override del modello e ripristina il modello consigliato per il tipo di account, o al [modello predefinito dell'organizzazione](#organization-default-model) quando un amministratore ne ha impostato uno. Non è di per sé un alias del modello |

84* `Enter`: cambia modello e salva come predefinito84* `Enter`: cambia modello e salva come predefinito

85* `s`: cambia modello solo per questa sessione85* `s`: cambia modello solo per questa sessione

86 86

~~87Digitare `/model <name>` direttamente si comporta come `Enter`. Le impostazioni del progetto e gestite hanno ancora la precedenza e si riapplicano al prossimo avvio.~~87Digitare `/model <name>` direttamente si comporta come `Enter`. Le impostazioni del progetto e gestite hanno ancora la precedenza e si riapplicano al prossimo avvio. {/* min-version: 2.1.196 */}Un [modello predefinito dell'organizzazione](#organization-default-model) che l'amministratore ha configurato per sovrascrivere la selezione dell'utente si riapplica anche al prossimo avvio.

88 88

89Nella v2.1.144 fino alla v2.1.152, `/model` si applicava solo alla sessione corrente e `d` nel selettore salvava un predefinito.89Nella v2.1.144 fino alla v2.1.152, `/model` si applicava solo alla sessione corrente e `d` nel selettore salvava un predefinito.

90 90

130* **Modello della sessione principale**: `/model`, il flag `--model`, la variabile di ambiente `ANTHROPIC_MODEL`, l'impostazione `model` e il modello ripristinato quando [si riprende una sessione](#setting-your-model)130* **Modello della sessione principale**: `/model`, il flag `--model`, la variabile di ambiente `ANTHROPIC_MODEL`, l'impostazione `model` e il modello ripristinato quando [si riprende una sessione](#setting-your-model)

131* **Risoluzione alias**: {/* min-version: 2.1.176 */}le variabili di ambiente `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL` e `ANTHROPIC_DEFAULT_FABLE_MODEL` non possono reindirizzare un alias consentito a un modello al di fuori dell'elenco131* **Risoluzione alias**: {/* min-version: 2.1.176 */}le variabili di ambiente `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL` e `ANTHROPIC_DEFAULT_FABLE_MODEL` non possono reindirizzare un alias consentito a un modello al di fuori dell'elenco

132* **Modalità veloce**: {/* min-version: 2.1.176 */}`/fast` rifiuta di attivare/disattivare quando comporterebbe un passaggio implicito a un modello Opus al di fuori dell'elenco, con il messaggio "is not in your organization's allowed models"132* **Modalità veloce**: {/* min-version: 2.1.176 */}`/fast` rifiuta di attivare/disattivare quando comporterebbe un passaggio implicito a un modello Opus al di fuori dell'elenco, con il messaggio "is not in your organization's allowed models"

133* **Modelli dei subagent**: il campo `model` nel [frontmatter del subagent](/it/sub-agents#choose-a-model), il parametro `model` dello strumento Agent, il selettore di modelli in `/agents` e `CLAUDE_CODE_SUBAGENT_MODEL`133* **Modelli dei subagent**: il campo `model` nel [frontmatter del subagent](/it/sub-agents#choose-a-model), il parametro `model` dello strumento Agent, `CLAUDE_CODE_SUBAGENT_MODEL`, e, su v2.1.197 e versioni precedenti, il selettore di modelli nella procedura guidata `/agents` {/* max-version: 2.1.197 */}

134* **Modelli di skill e comando**: il frontmatter `model` in [skill e comandi](/it/skills)134* **Modelli di skill e comando**: il frontmatter `model` in [skill e comandi](/it/skills)

135* **Modello Advisor**: l'impostazione [`advisorModel`](/it/advisor) configurata e il flag `--advisor`135* **Modello Advisor**: l'impostazione [`advisorModel`](/it/advisor) configurata e il flag `--advisor`

136* **Modello dell'agente di background**: il modello selezionato nel [selettore di dispatch](/it/agent-view)136* **Modello dell'agente di background**: il modello selezionato nel [selettore di dispatch](/it/agent-view)

137 137

138Il passaggio a un modello bloccato con `/model` viene rifiutato con un errore, mentre un flag `--model` bloccato, `ANTHROPIC_MODEL` o un valore dell'impostazione `model` viene sostituito all'avvio con un avviso che nomina sia i modelli richiesti che quelli sostituiti, e la sessione inizia sul modello predefinito. Un override di subagent, skill o comando bloccato ritorna al modello ereditato o predefinito piuttosto che non riuscire nella richiesta; un'impostazione `advisorModel` bloccata disabilita l'advisor per la sessione, mentre un valore del flag `--advisor` bloccato esce con un errore all'avvio. I modelli esclusi sono nascosti dal selettore `/model`.138Il passaggio a un modello bloccato con `/model` viene rifiutato con un errore, mentre un flag `--model` bloccato, `ANTHROPIC_MODEL` o un valore dell'impostazione `model` viene sostituito all'avvio con un avviso che nomina sia i modelli richiesti che quelli sostituiti, e la sessione inizia sul modello predefinito. Un override di subagent, skill o comando bloccato ritorna al modello ereditato o predefinito piuttosto che non riuscire nella richiesta; un'impostazione `advisorModel` bloccata disabilita l'advisor per la sessione, mentre un valore del flag `--advisor` bloccato esce con un errore all'avvio. I modelli esclusi sono nascosti dal selettore `/model`. {/* min-version: 2.1.199 */}A partire dalla v2.1.199, un ID modello completo nell'elenco che non ha una riga del selettore incorporata, come una versione precedente che l'elenco fissa, appare nel selettore `/model` come una propria riga etichettata. Nelle versioni precedenti tale ID è selezionabile solo digitando `/model <id>`.

139 139

140I cambiamenti automatici del modello vengono controllati allo stesso modo: gli elementi di una [catena di modelli di fallback](#fallback-model-chains) al di fuori dell'elenco di autorizzazione vengono eliminati, un aggiornamento in modalità plan come [`opusplan`](#opusplan-model-setting) a un modello escluso viene saltato in modo che la pianificazione continui sul modello della sessione, e un [fallback automatico del modello](#automatic-model-fallback) il cui target è escluso non viene eseguito, quindi la richiesta contrassegnata termina con un rifiuto. L'abilitazione della [modalità veloce](/it/fast-mode) viene rifiutata quando il modello su cui la sessione verrebbe eseguita in seguito è al di fuori dell'elenco di autorizzazione.140I cambiamenti automatici del modello vengono controllati allo stesso modo: gli elementi di una [catena di modelli di fallback](#fallback-model-chains) al di fuori dell'elenco di autorizzazione vengono eliminati, un aggiornamento in modalità plan come [`opusplan`](#opusplan-model-setting) a un modello escluso viene saltato in modo che la pianificazione continui sul modello della sessione, e un [fallback automatico del modello](#automatic-model-fallback) il cui target è escluso non viene eseguito, quindi la richiesta contrassegnata termina con un rifiuto. L'abilitazione della [modalità veloce](/it/fast-mode) viene rifiutata quando il modello su cui la sessione verrebbe eseguita in seguito è al di fuori dell'elenco di autorizzazione.

141 141

184}184}

185```185```

186 186

187Quando il modello predefinito per il tipo di account dell'utente non è nell'elenco di autorizzazione, l'opzione Predefinito si risolve invece nella prima voce `availableModels` che nomina un modello consentito e disponibile, e la riga Predefinito del selettore `/model` mostra quel modello. Questo si applica ovunque il valore predefinito viene raggiunto: avvio della sessione, selezione di Predefinito in `/model`, la parola chiave `"default"` nelle [catene di modelli di fallback](#fallback-model-chains) e il fallback utilizzato quando una selezione esclusa viene eliminata.187L'opzione Predefinito si risolve al valore predefinito del tipo di account, o al [modello predefinito dell'organizzazione](#organization-default-model) quando un amministratore ne ha impostato uno. Quando quel modello non è nell'elenco di autorizzazione, l'opzione Predefinito si risolve invece nella prima voce `availableModels` che nomina un modello consentito e disponibile, e la riga Predefinito del selettore `/model` mostra quel modello. Questo si applica ovunque il valore predefinito viene raggiunto: avvio della sessione, selezione di Predefinito in `/model`, la parola chiave `"default"` nelle [catene di modelli di fallback](#fallback-model-chains) e il fallback utilizzato quando una selezione esclusa viene eliminata.

188 188

189`enforceAvailableModels` non ha effetto quando `availableModels` non è impostato o è vuoto: con `availableModels: []`, il modello Predefinito per il tipo di account rimane utilizzabile, quindi l'impostazione non può bloccare gli utenti da ogni modello. Quando `availableModels` è non vuoto ma nessuna voce si risolve a un modello consentito e disponibile, l'applicazione si degrada e Predefinito ricade al valore predefinito del tipo di account, con un avviso visibile solo sotto `--debug`. Mantenere almeno una voce garantita disponibile nell'elenco per evitare questo.189`enforceAvailableModels` non ha effetto quando `availableModels` non è impostato o è vuoto: con `availableModels: []`, il modello Predefinito per il tipo di account rimane utilizzabile, quindi l'impostazione non può bloccare gli utenti da ogni modello. Quando `availableModels` è non vuoto ma nessuna voce si risolve a un modello consentito e disponibile, l'applicazione si degrada e Predefinito ricade al valore predefinito del tipo di account, con un avviso visibile solo sotto `--debug`. Mantenere almeno una voce garantita disponibile nell'elenco per evitare questo.

190 190

244 244

245Un modello limitato è nascosto dal selettore `/model`. Selezionarlo per nome con `--model`, la variabile di ambiente `ANTHROPIC_MODEL` o l'impostazione `model` mostra l'avviso `Model "<name>" is restricted by your organization's settings. Using <model> instead.` e la sessione inizia su un modello consentito. Digitare `/model <name>` per un modello limitato viene rifiutato con `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.` e la sessione mantiene il suo modello attuale.245Un modello limitato è nascosto dal selettore `/model`. Selezionarlo per nome con `--model`, la variabile di ambiente `ANTHROPIC_MODEL` o l'impostazione `model` mostra l'avviso `Model "<name>" is restricted by your organization's settings. Using <model> instead.` e la sessione inizia su un modello consentito. Digitare `/model <name>` per un modello limitato viene rifiutato con `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.` e la sessione mantiene il suo modello attuale.

246 246

247I due meccanismi si compongono: un modello è selezionabile solo quando è consentito da `availableModels` e non è limitato dall'organizzazione. Le restrizioni dell'organizzazione vengono consegnate alle sessioni sull'API Anthropic e alle distribuzioni [LLM gateway](/it/llm-gateway). Le sessioni su Bedrock, Vertex AI, Foundry e Claude Platform su AWS non le ricevono, quindi utilizzate `availableModels` su quei provider invece.247I due meccanismi si compongono: un modello è selezionabile solo quando è consentito da `availableModels` e non è limitato dall'organizzazione. Le restrizioni dell'organizzazione vengono consegnate alle sessioni sull'API Anthropic e alle distribuzioni [gateway LLM](/it/llm-gateway). Le sessioni su Bedrock, Vertex AI, Foundry e Claude Platform su AWS non le ricevono, quindi utilizzate `availableModels` su quei provider invece.

248

249<h2 id="organization-default-model">

250 Modello predefinito dell'organizzazione

251</h2>

252

253{/* plan-availability: feature=org-default-model plans=enterprise */}

254

255Gli amministratori dell'organizzazione sui piani Claude Enterprise possono impostare un modello predefinito per i membri di Claude Code dalla console di amministrazione claude.ai, per l'intera organizzazione o per ruolo personalizzato. Quando uno è impostato, l'opzione Predefinito si risolve a quel modello invece del [valore predefinito del tipo di account](#default-model-setting). Richiede Claude Code v2.1.196 o successivo.

256

257La riga Predefinito nel selettore `/model` mostra il nome del modello predefinito dell'organizzazione con l'etichetta Org default. L'etichetta legge Org default indipendentemente dal fatto che l'amministratore abbia impostato il valore predefinito per l'intera organizzazione o per il vostro ruolo. Un valore predefinito del ruolo copre i membri di quel ruolo personalizzato e ha la precedenza sul valore predefinito a livello di organizzazione; quando diversi vostri ruoli impostano valori predefiniti diversi, si applica il modello più capace.

258

259Il modello predefinito dell'organizzazione è un punto di partenza, non una restrizione, e qualsiasi altra selezione di modello ha la precedenza su di esso:

260

261* il flag `--model` e la variabile di ambiente `ANTHROPIC_MODEL`

262* un valore `model` nelle [impostazioni gestite](/it/settings#settings-files) o fornito tramite `--settings`

263* un valore `model` nelle impostazioni utente, progetto o locali, incluso un modello salvato con `/model`

264

265Gli amministratori possono anche configurare il modello predefinito dell'organizzazione per sovrascrivere la selezione dell'utente. Con l'override attivato, ha la precedenza sul valore `model` nelle impostazioni utente, progetto e locali, quindi un modello salvato con `/model` si applica per la sessione corrente e il modello predefinito dell'organizzazione ritorna al prossimo avvio. Quando la vostra selezione differisce, `/model` mostra `Your organization's default (<model>) applies on restart`. Il flag `--model`, `ANTHROPIC_MODEL`, le impostazioni gestite e `--settings` hanno ancora la precedenza anche con l'override attivato. L'override è disponibile per un set limitato di organizzazioni; chiedete al vostro team di account Anthropic riguardo alla disponibilità.

266

267Per limitare quali modelli i membri possono selezionare, utilizzare [restrizioni del modello dell'organizzazione](#organization-model-restrictions) o [`availableModels`](#restrict-model-selection) invece.

268

269Claude Code legge il modello predefinito dell'organizzazione una volta all'avvio, quindi un valore predefinito che l'amministratore cambia a metà sessione ha effetto al prossimo avvio.

270

271Quando il modello predefinito dell'organizzazione non sovrascrive la selezione dell'utente, il primo avvio interattivo dopo che l'amministratore lo cambia cancella la chiave `model` dalle impostazioni utente una volta, quindi il nuovo valore predefinito si applica. Non cambia nient'altro nel file, e un modello salvato con `/model` dopo quel lancio viene mantenuto.

272

273Il modello predefinito dell'organizzazione passa attraverso gli stessi controlli di restrizione di qualsiasi altro modello Predefinito prima di essere adottato:

274

275* [`availableModels`](#restrict-model-selection) da solo non vincola mai l'opzione Predefinito, quindi un modello predefinito dell'organizzazione al di fuori dell'elenco di autorizzazione si applica comunque. Quando [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) è anche impostato, un modello predefinito dell'organizzazione al di fuori dell'elenco di autorizzazione viene rimappato alla prima voce dell'elenco di autorizzazione, come qualsiasi altro Predefinito

276* un modello predefinito dell'organizzazione che [restrizioni del modello dell'organizzazione](#organization-model-restrictions) negano per il vostro account viene sostituito dal modello consentito più recente nella sua famiglia, o una famiglia a costo inferiore quando ogni versione di essa è limitata

277* un modello predefinito dell'organizzazione che non è disponibile per il vostro account affatto, come Fable 5 con [zero data retention](/it/zero-data-retention), viene saltato, e l'opzione Predefinito si risolve al valore predefinito del tipo di account

278

279A partire dalla v2.1.199, quando il modello predefinito dell'organizzazione è una famiglia di modelli diversa dal valore predefinito usuale del tipo di account, il selettore `/model` mantiene una riga separata per quella famiglia usuale, quindi potete comunque passare ad essa per una sessione. Nella v2.1.196 fino alla v2.1.198 quella riga manca dal selettore.

280

281Il modello predefinito dell'organizzazione viene consegnato alle sessioni autenticate con l'API Anthropic. Le sessioni su distribuzioni [gateway LLM](/it/llm-gateway), Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry e Claude Platform su AWS non lo ricevono. Per impostare un valore predefinito su quelle distribuzioni, utilizzare la chiave `model` nelle [impostazioni gestite](/it/settings#settings-files) invece.

282

283<h2 id="organization-effort-limits">

284 Limiti di sforzo dell'organizzazione

285</h2>

286

287{/* plan-availability: feature=org-effort-limits plans=enterprise */}

288

289Gli amministratori dell'organizzazione sui piani Claude Enterprise possono impostare un [livello di sforzo](#adjust-effort-level) massimo per modello per ogni ruolo personalizzato, insieme alle [restrizioni del modello dell'organizzazione](#organization-model-restrictions) a livello di ruolo. I livelli al di sopra del limite non vengono offerti nel selettore `/effort`, e nominare un livello più alto con `--effort` o `/effort` viene eseguito al limite invece. Nelle sessioni interattive e nelle esecuzioni di testo semplice `--print`, un avviso nomina i livelli richiesti e applicati; con output `json` o `stream-json` o negli agenti di background, il limite si applica silenziosamente. I limiti sono per modello, quindi il cambio di modelli può modificare quali livelli sono disponibili. Quando diversi vostri ruoli concedono lo stesso modello, si applica il limite meno restrittivo. Richiede Claude Code v2.1.195 o successivo.

290

291I limiti di sforzo vengono consegnati insieme alle [restrizioni del modello dell'organizzazione](#organization-model-restrictions) e seguono la stessa disponibilità del provider: le sessioni su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry e Claude Platform su AWS non le ricevono.

248 292

249<h2 id="special-model-behavior">293<h2 id="special-model-behavior">

250 Comportamento speciale del modello294 Comportamento speciale del modello

263 307

264Enterprise pay-as-you-go significa un'organizzazione Enterprise fatturata per utilizzo piuttosto che per posto di abbonamento.308Enterprise pay-as-you-go significa un'organizzazione Enterprise fatturata per utilizzo piuttosto che per posto di abbonamento.

265 309

266Quando le impostazioni gestite [applicano l'elenco consentito per il modello predefinito](#enforce-the-allowlist-for-the-default-model) e il valore predefinito del tipo di account non è in `availableModels`, `default` si risolve nel valore predefinito applicato invece del valore predefinito del tipo di account sopra.310Quando un amministratore ha impostato un [modello predefinito dell'organizzazione](#organization-default-model), `default` si risolve a quel modello invece del valore predefinito del tipo di account sopra. Richiede Claude Code v2.1.196 o successivo.

311

312Quando le impostazioni gestite [applicano l'elenco consentito per il modello predefinito](#enforce-the-allowlist-for-the-default-model) e il valore predefinito del tipo di account non è in `availableModels`, `default` si risolve nel valore predefinito applicato invece del valore predefinito del tipo di account sopra. Quando entrambi si applicano, il modello predefinito dell'organizzazione sostituisce il valore predefinito del tipo di account per primo e l'applicazione si applica quindi ad esso: un modello predefinito dell'organizzazione nell'elenco di autorizzazione viene mantenuto, mentre uno al di fuori dell'elenco si risolve nel Predefinito applicato.

267 313

268Fable 5 non è il modello predefinito su alcun tipo di account. Le sessioni utilizzano Fable 5 solo dopo che lo scegliete, con `/model fable`, un'impostazione `model`, o l'alias `best` dove Fable 5 è disponibile. Sceglierlo con `/model` lo salva come modello selezionato nelle impostazioni utente, quindi le sessioni successive iniziano su Fable 5 fino a quando non cambiate modello.314Fable 5 non è il modello predefinito su alcun tipo di account. Le sessioni utilizzano Fable 5 solo dopo che lo scegliete, con `/model fable`, un'impostazione `model`, o l'alias `best` dove Fable 5 è disponibile. Sceglierlo con `/model` lo salva come modello selezionato nelle impostazioni utente, quindi le sessioni successive iniziano su Fable 5 fino a quando non cambiate modello.

269 315

381 427

382Se impostate un livello che il modello attivo non supporta, Claude Code ricade al livello supportato più alto pari o inferiore a quello impostato. Ad esempio, `xhigh` viene eseguito come `high` su Opus 4.6.428Se impostate un livello che il modello attivo non supporta, Claude Code ricade al livello supportato più alto pari o inferiore a quello impostato. Ad esempio, `xhigh` viene eseguito come `high` su Opus 4.6. La vostra organizzazione può anche limitare quali livelli sono disponibili per un modello; vedere [Limiti di sforzo dell'organizzazione](#organization-effort-limits).

383 429

384Lo sforzo predefinito è `high` su Fable 5, Sonnet 5, Opus 4.8, Opus 4.6 e Sonnet 4.6, e `xhigh` su Opus 4.7.430Lo sforzo predefinito è `high` su Fable 5, Sonnet 5, Opus 4.8, Opus 4.6 e Sonnet 4.6, e `xhigh` su Opus 4.7.

385 431

520export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Custom deployment routed through the internal LLM gateway"566export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Custom deployment routed through the internal LLM gateway"

521```567```

522 568

523La voce personalizzata appare in fondo al selettore `/model`. `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` e `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` sono facoltativi. Se omessi, l'ID del modello viene utilizzato come nome e la descrizione per impostazione predefinita è `Custom model (<model-id>)`.569La voce personalizzato appare in fondo al selettore `/model`. `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` e `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` sono facoltativi. Se omessi, l'ID del modello viene utilizzato come nome e la descrizione per impostazione predefinita è `Custom model (<model-id>)`.

524 570

525Claude Code salta la convalida per l'ID del modello impostato in `ANTHROPIC_CUSTOM_MODEL_OPTION`, quindi è possibile utilizzare qualsiasi stringa che l'endpoint API accetta. Quando [`availableModels`](#restrict-model-selection) è impostato, includere l'ID del modello personalizzato anche nell'elenco di autorizzazione: la voce personalizzata viene filtrata dal selettore e una selezione `--model` di essa viene rifiutata come qualsiasi altro modello escluso. Un ID personalizzato che incorpora un nome di famiglia, come `my-gateway/claude-opus-4-8`, conta come una voce specifica per quella famiglia e disabilita il suo wildcard, quindi elencare anche le versioni che intendete mantenere selezionabili. Vedere [Merge behavior](#merge-behavior).571Claude Code salta la convalida per l'ID del modello impostato in `ANTHROPIC_CUSTOM_MODEL_OPTION`, quindi è possibile utilizzare qualsiasi stringa che l'endpoint API accetta. Quando [`availableModels`](#restrict-model-selection) è impostato, includere l'ID del modello personalizzato anche nell'elenco di autorizzazione: la voce personalizzata viene filtrata dal selettore e una selezione `--model` di essa viene rifiutata come qualsiasi altro modello escluso. Un ID personalizzato che incorpora un nome di famiglia, come `my-gateway/claude-opus-4-8`, conta come una voce specifica per quella famiglia e disabilita il suo wildcard, quindi elencare anche le versioni che intendete mantenere selezionabili. Vedere [Comportamento di unione](#merge-behavior).

526 572

527<h2 id="environment-variables">573<h2 id="environment-variables">

528 Variabili di ambiente574 Variabili di ambiente

monitoring-usage.md +1 −1

Details

1186 1186

1187Claude Code ritenta internamente le richieste API non riuscite ed emette un singolo evento `claude_code.api_error` solo dopo che rinuncia, quindi l'evento stesso è il segnale terminale per quella richiesta. I tentativi di ripetizione intermedi non vengono registrati come eventi separati.1187Claude Code ritenta internamente le richieste API non riuscite ed emette un singolo evento `claude_code.api_error` solo dopo che rinuncia, quindi l'evento stesso è il segnale terminale per quella richiesta. I tentativi di ripetizione intermedi non vengono registrati come eventi separati.

1188 1188

1189L'attributo `attempt` sull'evento registra quanti tentativi sono stati effettuati in totale. `CLAUDE_CODE_MAX_RETRIES` ha un valore predefinito di 10 ed è limitato a 15. Quando la richiesta esaurisce tutti i tentativi su un errore transitorio, `attempt` è uguale a uno più di quel limite effettivo: 11 per impostazione predefinita, e mai più di 16. Un valore inferiore indica un errore non ritentabile come una risposta `400`.1189L'attributo `attempt` sull'evento registra il numero totale di tentativi. `CLAUDE_CODE_MAX_RETRIES` ha un valore predefinito di 10 ed è limitato a 15; {/* min-version: 2.1.199 */}a partire da v2.1.199, `CLAUDE_CODE_RETRY_WATCHDOG` aumenta il valore predefinito e rimuove il limite. Quando la richiesta esaurisce tutti i tentativi su un errore transitorio, `attempt` è uguale a uno più di quel limite effettivo: 11 per impostazione predefinita, e mai più di 16 a meno che il watchdog non sia impostato. Un valore inferiore indica un errore non ritentabile come una risposta `400`.

1190 1190

1191Per distinguere una sessione che si è ripresa da una che si è bloccata, raggruppa gli eventi per `session.id` e verifica se esiste un evento `api_request` successivo dopo l'errore.1191Per distinguere una sessione che si è ripresa da una che si è bloccata, raggruppa gli eventi per `session.id` e verifica se esiste un evento `api_request` successivo dopo l'errore.

1192 1192

permission-modes.md +22 −7

Details

237* Force push o push diretto a `main`237* Force push o push diretto a `main`

238* {/* min-version: 2.1.182 */}`git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -fd`, `git stash drop`, o `git stash clear`, che il classificatore presume scarterebbero le modifiche non sottoposte a commit238* {/* min-version: 2.1.182 */}`git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -fd`, `git stash drop`, o `git stash clear`, che il classificatore presume scarterebbero le modifiche non sottoposte a commit

239* `git commit --amend` quando il commit in HEAD non è stato creato in questa sessione239* `git commit --amend` quando il commit in HEAD non è stato creato in questa sessione

240* {/* min-version: 2.1.198 */}}Da v2.1.198, `git commit --amend` quando il commit in HEAD è già stato sottoposto a push. Una riscrittura solo del messaggio non è bloccata: `--amend -m` senza nulla di nuovo in staging, su un commit che Claude ha creato durante questa sessione

240* `terraform destroy`, `pulumi destroy`, `cdk destroy`, o `terragrunt destroy`, e applicare un piano che distrugge risorse241* `terraform destroy`, `pulumi destroy`, `cdk destroy`, o `terragrunt destroy`, e applicare un piano che distrugge risorse

241 242

242Claude Code v2.1.195 e successivo bloccano più categorie per impostazione predefinita. Diversi dipendono da voci di [ambiente](/it/auto-mode-config#define-trusted-infrastructure), come target remoti sensibili e ambiti IaC protetti, che puoi restringere a nomi concreti.243Claude Code v2.1.195 e successivo bloccano più categorie per impostazione predefinita. Diversi dipendono da voci di [ambiente](/it/auto-mode-config#define-trusted-infrastructure), come target remoti sensibili e ambiti IaC protetti, che puoi restringere a nomi concreti.

251* Shell interattive o port-forward in un target remoto sensibile252* Shell interattive o port-forward in un target remoto sensibile

252* Apertura di un tunnel o reverse shell che rende un servizio locale raggiungibile da internet pubblico253* Apertura di un tunnel o reverse shell che rende un servizio locale raggiungibile da internet pubblico

253* Stampa di una credenziale o token live nella trascrizione o in un file254* Stampa di una credenziale o token live nella trascrizione o in un file

254* Accesso a una posizione PII o dati regolamentati, o copia di dati da una255* Accesso a una posizione elencata come posizione di dati sensibili nel tuo [ambiente](/it/auto-mode-config#define-trusted-infrastructure), o copia di dati da una. {/* min-version: 2.1.198 */}A partire da v2.1.198 questo blocca anche l'invio di dati da una a un pubblico che la voce esclude

255* Instradamento di un'installazione di pacchetto intorno al tuo registro di pacchetti interno a un registro pubblico256* Instradamento di un'installazione di pacchetto intorno al tuo registro di pacchetti interno a un registro pubblico. {/* min-version: 2.1.198 */}A partire da v2.1.198, questo si applica anche quando hai detto a Claude che un registro interno o mirror esiste nella conversazione, non solo quando uno è elencato nel tuo ambiente

256* Esecuzione di un comando con un flag che disarma una guardia di sicurezza, come `--insecure`257* Esecuzione di un comando con un flag che disarma una guardia di sicurezza, come `--insecure`

258* Avvio di un loop di agente autonomo che viene eseguito senza approvazione umana o sandbox, come uno avviato con `--dangerously-skip-permissions` o `--no-sandbox`. {/* min-version: 2.1.198 */}A partire da v2.1.198 questo copre anche l'esecuzione di un agente di terze parti o harness di valutazione con isolamento e approvazione per azione disabilitati, come un runner avviato con `--yes-always`

257* Azioni del browser [Claude in Chrome](/it/chrome) che potrebbero inviare contenuto della pagina, cookie o credenziali off-origin259* Azioni del browser [Claude in Chrome](/it/chrome) che potrebbero inviare contenuto della pagina, cookie o credenziali off-origin

258 260

261Claude Code v2.1.198 e successivo bloccano anche questi per impostazione predefinita:

262

263* Eliminazione di file in `/tmp`, `$TMPDIR`, o un'altra directory di scratch o cache condivisa per wildcard, glob, o filtro di età piuttosto che per un percorso specifico nominato

264* Inclusione di dettagli sensibili nel contenuto inviato, caricato, pubblicato, o scritto ad altre persone o sistemi condivisi, quando il tuo stesso messaggio non ha autorizzato quei dettagli per quel destinatario

265* Invio di pressioni di tasti al riquadro tmux di Claude Code stesso per guidare la sua stessa interfaccia, che il classificatore tratta come Claude che cambia le sue stesse autorizzazioni o supervisione

266

259**Consentito per impostazione predefinita**:267**Consentito per impostazione predefinita**:

260 268

261* Operazioni su file locali nella tua directory di lavoro269* Operazioni su file locali nella tua directory di lavoro

272* Invio di dati ai domini attendibili, bucket e servizi che elenchi in [`environment`](/it/auto-mode-config#define-trusted-infrastructure). Questo copre solo il flusso di dati, non operazioni distruttive o di credenziali sulla stessa infrastruttura280* Invio di dati ai domini attendibili, bucket e servizi che elenchi in [`environment`](/it/auto-mode-config#define-trusted-infrastructure). Questo copre solo il flusso di dati, non operazioni distruttive o di credenziali sulla stessa infrastruttura

273* Navigazione [Claude in Chrome](/it/chrome) a un dominio interno attendibile, localhost, o un URL che hai nominato281* Navigazione [Claude in Chrome](/it/chrome) a un dominio interno attendibile, localhost, o un URL che hai nominato

274 282

275Le richieste di accesso alla rete sandbox vengono instradate attraverso il classificatore piuttosto che essere consentite per impostazione predefinita. Esegui `claude auto-mode defaults` per vedere gli elenchi di regole completi. Se le azioni di routine vengono bloccate, un amministratore può aggiungere repo attendibili, bucket e servizi tramite l'impostazione `autoMode.environment`: vedi [Configura auto mode](/it/auto-mode-config).283Le richieste di accesso alla rete sandbox vengono instradate attraverso il classificatore piuttosto che essere consentite per impostazione predefinita. {/* min-version: 2.1.198 */}A partire da v2.1.198, il classificatore riutilizza il suo verdetto per un host e una porta di rete invece di rieseguire su ogni connessione:

284

285* Un allow viene riutilizzato fino a quando nuovo contenuto non entra nella conversazione, a quel punto quell'host viene controllato di nuovo

286* Nell'interfaccia CLI interattiva, un deny viene eliminato quando il turno termina

287* In [modalità non interattiva](/it/headless) e sessioni Agent SDK non c'è confine di turno, quindi un deny viene riutilizzato per il resto dell'esecuzione

288* Cambiare la tua modalità di autorizzazione o regole elimina tutti i verdetti memorizzati nella cache

289

290Esegui `claude auto-mode defaults` per vedere gli elenchi di regole completi. Se le azioni di routine vengono bloccate, un amministratore può aggiungere repo attendibili, bucket e servizi tramite l'impostazione `autoMode.environment`: vedi [Configura auto mode](/it/auto-mode-config).

276 291

277<h3 id="boundaries-you-state-in-conversation">292<h3 id="boundaries-you-state-in-conversation">

278 Confini che dichiari nella conversazione293 Confini che dichiari nella conversazione

300 315

301 1. Le azioni che corrispondono alle tue [regole allow o deny](/it/permissions#manage-permissions) si risolvono immediatamente, ad eccezione delle scritture su [percorsi protetti](#protected-paths), che vengono instradate al classificatore anche quando una regola allow corrisponde316 1. Le azioni che corrispondono alle tue [regole allow o deny](/it/permissions#manage-permissions) si risolvono immediatamente, ad eccezione delle scritture su [percorsi protetti](#protected-paths), che vengono instradate al classificatore anche quando una regola allow corrisponde

302 2. Le azioni di sola lettura e le modifiche ai file nella tua directory di lavoro vengono auto-approvate, ad eccezione delle scritture su [percorsi protetti](#protected-paths)317 2. Le azioni di sola lettura e le modifiche ai file nella tua directory di lavoro vengono auto-approvate, ad eccezione delle scritture su [percorsi protetti](#protected-paths)

303 3. Tutto il resto va al classificatore318 3. Tutto il resto va al classificatore. {/* min-version: 2.1.199 */}A partire da v2.1.199, uno strumento MCP contrassegnato con [`_meta["anthropic/requiresUserInteraction"]`](/it/mcp#require-approval-for-a-specific-tool) salta il classificatore e ti richiede direttamente, quindi un passaggio di consenso non viene mai auto-approvato per conto dell'autore dello strumento

304 4. Se il classificatore blocca, Claude riceve il motivo e tenta un'alternativa319 4. Se il classificatore blocca, Claude riceve il motivo e tenta un'alternativa

305 320

306 All'ingresso in auto mode, le regole allow ampie che concedono l'esecuzione arbitraria di codice vengono eliminate:321 All'ingresso in auto mode, le regole allow ampie che concedono l'esecuzione arbitraria di codice vengono eliminate:

326 </Accordion>341 </Accordion>

327 342

328 <Accordion title="Costo e latenza">343 <Accordion title="Costo e latenza">

329 Il classificatore viene eseguito su un modello configurato dal server che è indipendente dalla tua selezione `/model`, quindi il cambio di modelli non cambia la disponibilità del classificatore. Le chiamate del classificatore contano verso il tuo utilizzo di token. Ogni controllo invia una parte della trascrizione più l'azione in sospeso, aggiungendo un round-trip prima dell'esecuzione. Le letture e le modifiche della directory di lavoro al di fuori dei percorsi protetti saltano il classificatore, quindi l'overhead proviene principalmente da comandi shell e operazioni di rete.344 Il classificatore viene eseguito su un modello configurato dal server che è indipendente dalla tua selezione `/model`, quindi il cambio di modelli non cambia la disponibilità del classificatore. Le chiamate del classificatore contano verso il tuo utilizzo di token. Ogni controllo invia una parte della trascrizione più l'azione in sospeso, aggiungendo un round-trip prima dell'esecuzione. Le letture e le modifiche della directory di lavoro al di fuori dei percorsi protetti saltano il classificatore, quindi l'overhead proviene principalmente da comandi shell e operazioni di rete. {/* min-version: 2.1.198 */}A partire da v2.1.198, un verdetto di rete sandbox per un host e una porta viene riutilizzato invece di essere riclassificato su ogni connessione, quindi le connessioni ripetute allo stesso host non aggiungono ciascuna un controllo. [Cosa blocca il classificatore per impostazione predefinita](#what-the-classifier-blocks-by-default) descrive quanto a lungo un allow e un deny durano.

330 </Accordion>345 </Accordion>

331</AccordionGroup>346</AccordionGroup>

332 347

334 Consenti solo strumenti pre-approvati con la modalità dontAsk349 Consenti solo strumenti pre-approvati con la modalità dontAsk

335</h2>350</h2>

336 351

337La modalità `dontAsk` auto-nega ogni chiamata di strumento che altrimenti richiederebbe. Solo le azioni che corrispondono alle tue regole `permissions.allow` e ai [comandi Bash di sola lettura](/it/permissions#read-only-commands) possono essere eseguite; le regole [`ask` esplicite](/it/permissions#manage-permissions) vengono negate piuttosto che richiedere. Questo rende la modalità completamente non interattiva per pipeline CI o ambienti ristretti in cui pre-definisci esattamente cosa Claude può fare. Le sessioni cloud su [Claude Code sul web](/it/claude-code-on-the-web) ignorano `defaultMode: "dontAsk"`; vedi [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode) per i dettagli.352La modalità `dontAsk` auto-nega ogni chiamata di strumento che altrimenti richiederebbe. La barra di stato mostra `⏵⏵ don't ask on` mentre questa modalità è attiva. Solo le azioni che corrispondono alle tue regole `permissions.allow` e ai [comandi Bash di sola lettura](/it/permissions#read-only-commands) possono essere eseguite; le regole [`ask` esplicite](/it/permissions#manage-permissions) vengono negate piuttosto che richiedere. {/* min-version: 2.1.199 */}A partire dalla v2.1.199, uno strumento MCP contrassegnato con [`_meta["anthropic/requiresUserInteraction"]`](/it/mcp#require-approval-for-a-specific-tool) viene anche negato in questa modalità anche quando una regola di autorizzazione corrisponde, perché la sua scheda di approvazione necessita di una risposta che questa modalità non raccoglie mai. Questo rende la modalità completamente non interattiva per pipeline CI o ambienti ristretti in cui pre-definisci esattamente cosa Claude può fare. Le sessioni cloud su [Claude Code sul web](/it/claude-code-on-the-web) ignorano `defaultMode: "dontAsk"`; vedi [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode) per i dettagli.

338 353

339Impostala all'avvio con il flag:354Impostala all'avvio con il flag:

340 355

346 Salta tutti i controlli con la modalità bypassPermissions361 Salta tutti i controlli con la modalità bypassPermissions

347</h2>362</h2>

348 363

349La modalità `bypassPermissions` disabilita i prompt di autorizzazione e i controlli di sicurezza in modo che le chiamate di strumenti vengono eseguite immediatamente. A partire dalla v2.1.126 questo include le scritture su [percorsi protetti](#protected-paths), che le versioni precedenti ancora richiedevano. Le [regole ask](/it/permissions#manage-permissions) esplicite forzano comunque un prompt in questa modalità, e le rimozioni che interessano la radice del filesystem o la directory home, come `rm -rf /` e `rm -rf ~`, ancora richiedono un prompt come protezione contro gli errori del modello. Utilizza questa modalità solo in ambienti isolati come container, VM o dev container senza accesso a Internet, dove Claude Code non può danneggiare il tuo sistema host.364La modalità `bypassPermissions` disabilita i prompt di autorizzazione e i controlli di sicurezza in modo che le chiamate di strumenti vengono eseguite immediatamente. A partire dalla v2.1.126 questo include le scritture su [percorsi protetti](#protected-paths), che le versioni precedenti ancora richiedevano. Le [regole ask](/it/permissions#manage-permissions) esplicite forzano comunque un prompt in questa modalità, e le rimozioni che interessano la radice del filesystem o la directory home, come `rm -rf /` e `rm -rf ~`, ancora richiedono un prompt come protezione contro gli errori del modello. {/* min-version: 2.1.199 */}A partire dalla v2.1.199, gli strumenti MCP contrassegnati con [`_meta["anthropic/requiresUserInteraction"]`](/it/mcp#require-approval-for-a-specific-tool) ancora richiedono un prompt. Utilizza questa modalità solo in ambienti isolati come container, VM o dev container senza accesso a Internet, dove Claude Code non può danneggiare il tuo sistema host.

350 365

351Non puoi entrare in `bypassPermissions` da una sessione che è stata avviata senza uno dei flag di abilitazione; riavvia con uno per abilitarlo:366Non puoi entrare in `bypassPermissions` da una sessione che è stata avviata senza uno dei flag di abilitazione; riavvia con uno per abilitarlo:

352 367

permissions.md +11 −0

Details

282 Un modello come `/Users/alice/file` non è un percorso assoluto. È relativo alla radice del progetto. Utilizzate `//Users/alice/file` per i percorsi assoluti.282 Un modello come `/Users/alice/file` non è un percorso assoluto. È relativo alla radice del progetto. Utilizzate `//Users/alice/file` per i percorsi assoluti.

283</Warning>283</Warning>

284 284

285Un modello `/path` si ancora alla directory associata al file di impostazioni che lo definisce, quindi la stessa regola corrisponde a posizioni diverse a seconda di dove la mettete:

286

287| Regola definita in | `/path` si risolve a |

288| :-------------------------------------------------------------- | :------------------------- |

289| Impostazioni di progetto o locali, come `.claude/settings.json` | `<project root>/path` |

290| Impostazioni utente in `~/.claude/settings.json` | `~/.claude/path` |

291| Un file passato con `--settings <file>` | `<directory of file>/path` |

292| Flag CLI, `/permissions` o regole di sessione | `<original cwd>/path` |

293

294Una regola deny come `Read(/secrets/**)` nelle impostazioni utente blocca `~/.claude/secrets/**`, non una directory `secrets` nel vostro progetto. Per scrivere una regola nelle impostazioni utente che si applica all'interno di ogni progetto, utilizzate un percorso assoluto `//` o un percorso relativo alla home `~/` invece.

295

285Su Windows, i percorsi vengono normalizzati in forma POSIX prima della corrispondenza. `C:\Users\alice` diventa `/c/Users/alice`, quindi utilizzate `//c/**/.env` per corrispondere ai file `.env` in qualsiasi punto su quel drive. Per corrispondere su tutti i drive, utilizzate `//**/.env`.296Su Windows, i percorsi vengono normalizzati in forma POSIX prima della corrispondenza. `C:\Users\alice` diventa `/c/Users/alice`, quindi utilizzate `//c/**/.env` per corrispondere ai file `.env` in qualsiasi punto su quel drive. Per corrispondere su tutti i drive, utilizzate `//**/.env`.

286 297

287Esempi:298Esempi:

plugins.md +2 −2

Details

352Man mano che apporti modifiche al tuo plugin, esegui `/reload-plugins` per raccogliere gli aggiornamenti senza riavviare. Questo ricarica plugin, skills, agents, hooks, MCP servers del plugin e LSP servers del plugin. Testa i componenti del tuo plugin:352Man mano che apporti modifiche al tuo plugin, esegui `/reload-plugins` per raccogliere gli aggiornamenti senza riavviare. Questo ricarica plugin, skills, agents, hooks, MCP servers del plugin e LSP servers del plugin. Testa i componenti del tuo plugin:

353 353

354* Prova i tuoi skill con `/plugin-name:skill-name`354* Prova i tuoi skill con `/plugin-name:skill-name`

355* Verifica che gli agents appaiano in `/agents`355* Verifica che gli agents appaiano in `/context` sotto Custom Agents, o @-menziona uno per il suo nome con scope

356* Verifica che gli hooks funzionino come previsto356* Verifica che gli hooks funzionino come previsto

357 357

358<Tip>358<Tip>

502 claude --plugin-dir ./my-plugin502 claude --plugin-dir ./my-plugin

503 ```503 ```

504 504

505 Testa ogni componente: esegui i tuoi comandi, verifica che gli agents appaiano in `/agents` e verifica che gli hook si attivino correttamente.505 Testa ogni componente: esegui i tuoi comandi, verifica che gli agents appaiano in `/context`, e verifica che gli hook si attivino correttamente.

506 </Step>506 </Step>

507</Steps>507</Steps>

508 508

plugins-reference.md +1 −1

Details

79 79

80**Punti di integrazione**:80**Punti di integrazione**:

81 81

~~82* Gli agents appaiono nell'interfaccia `/agents`~~82* Gli agents appaiono nella typeahead [@-mention](/it/sub-agents#invoke-subagents-explicitly) con il loro nome con scope, come `my-plugin:code-reviewer`, una volta che il plugin è abilitato

83* Claude può invocare gli agents automaticamente in base al contesto dell'attività83* Claude può invocare gli agents automaticamente in base al contesto dell'attività

84* Gli agents possono essere invocati manualmente dagli utenti84* Gli agents possono essere invocati manualmente dagli utenti

85* I plugin agents funzionano insieme agli agents Claude integrati85* I plugin agents funzionano insieme agli agents Claude integrati

sandboxing.md +43 −5

Details

199 Protect credentials199 Protect credentials

200</h3>200</h3>

201 201

202L'impostazione `sandbox.credentials` dichiara file di credenziali e variabili di ambiente a cui i comandi sandboxati non devono accedere. I percorsi dei file elencati vengono negati per le letture all'interno della sandbox, lo stesso blocco che applica `filesystem.denyRead`, e le variabili di ambiente elencate vengono rimosse prima di ogni esecuzione di comando sandboxato. Il blocco dedicato `credentials` mantiene le regole delle credenziali raggruppate con la rimozione delle variabili di ambiente e separate dalle regole generali del filesystem. Richiede Claude Code v2.1.187 o successivo.202L'impostazione `sandbox.credentials` dichiara file di credenziali e variabili di ambiente da proteggere dai comandi sandboxati. Ogni voce nomina un percorso di file o una variabile di ambiente e una `mode`. Il blocco dedicato `credentials` mantiene le regole delle credenziali raggruppate insieme e separate dalle regole generali del filesystem. Richiede Claude Code v2.1.187 o successivo.

203

204Per le voci con `"mode": "deny"`, i percorsi dei file vengono negati per le letture all'interno della sandbox, la stessa restrizione che applica `filesystem.denyRead`, e le variabili di ambiente vengono rimosse prima di ogni esecuzione di comando sandboxato.

203 205

204L'esempio seguente blocca le letture del file delle credenziali AWS e della directory SSH e rimuove `GITHUB_TOKEN` e `NPM_TOKEN` dall'ambiente dei comandi sandboxati:206L'esempio seguente blocca le letture del file delle credenziali AWS e della directory SSH e rimuove `GITHUB_TOKEN` e `NPM_TOKEN` dall'ambiente dei comandi sandboxati:

205 207

221}223}

222```224```

223 225

224Ogni voce contiene `"mode": "deny"`, che è l'unico valore supportato. Il campo `mode` esplicito mantiene lo schema compatibile con le versioni future. I percorsi dei file seguono le stesse [regole di prefisso](/it/settings#sandbox-path-prefixes) delle impostazioni `sandbox.filesystem.*`, e le voci da ogni [ambito di impostazioni](/it/settings#settings-precedence) vengono unite. Poiché l'unica modalità è `deny`, qualsiasi ambito può aggiungere restrizioni ma nessuno può rimuoverle.226Le voci di file supportano solo `"mode": "deny"`. Le voci di variabili di ambiente accettano anche `"mode": "mask"`, descritto di seguito.

227

228I percorsi dei file seguono le stesse [regole di prefisso](/it/settings#sandbox-path-prefixes) delle impostazioni `sandbox.filesystem.*`, e le voci `deny` da ogni [ambito di impostazioni](/it/settings#settings-precedence) vengono unite. Una voce `deny` restringe solo l'accesso, quindi qualsiasi ambito può aggiungerne una, ma nessun ambito può rimuoverne una che un altro ambito ha aggiunto.

225 229

226Non esiste un elenco di negazione delle credenziali integrato, quindi solo i file e le variabili che elenchi sono limitati. L'impostazione influisce solo sui comandi Bash sandboxati. Per rimuovere le credenziali di Anthropic e dei provider cloud da tutti i sottoprocessi indipendentemente dal sandboxing, imposta [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/it/env-vars).230Non esiste un elenco di negazione delle credenziali integrato, quindi solo i file e le variabili che elenchi sono limitati. L'impostazione influisce solo sui comandi Bash sandboxati. Per rimuovere le credenziali di Anthropic e dei provider cloud da tutti i sottoprocessi indipendentemente dal sandboxing, imposta [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/it/env-vars).

227 231

232<h4 id="mask-environment-variables">

233 Mask environment variables

234</h4>

235

236`"mode": "mask"` protegge una credenziale mantenendo il funzionamento degli strumenti che si autenticano con essa. `deny` rimuove completamente la variabile, il che interrompe anche gli strumenti che ne hanno bisogno, come `gh` o `npm`. Richiede Claude Code v2.1.199 o successivo.

237

238Con `mask`, il comando sandboxato vede un valore sentinella per sessione invece di quello reale. Quando una richiesta esce dalla sandbox per uno degli `injectHosts` della credenziale, il [proxy della sandbox](#network-isolation) sostituisce il sentinella con il valore reale. Il comando e tutto ciò che registra non contengono mai la credenziale reale, ma le sue richieste si autenticano comunque.

239

240Il proxy sostituisce la credenziale all'interno dei contenuti della richiesta, quindi deve vederli. Imposta [`network.tlsTerminate`](/it/settings#sandbox-settings) in modo che il proxy termini HTTPS stesso. Senza di esso, il mascheramento fallisce in modo chiuso: il comando vede ancora solo il sentinella, ma il sentinella raggiunge il server invariato e l'autenticazione fallisce. Claude Code segnala questa configurazione errata all'avvio e in `/doctor`.

241

242L'esempio seguente maschera due token. `GH_TOKEN` viene sostituito solo sulle richieste a `api.github.com`, mentre `NPM_TOKEN` non ha `injectHosts` e viene sostituito sulle richieste a ogni host in `network.allowedDomains`. Ogni voce `injectHosts` deve essere coperta da `network.allowedDomains`.

243

244```json theme={null}

245{

246 "sandbox": {

247 "enabled": true,

248 "network": {

249 "tlsTerminate": {},

250 "allowedDomains": ["*.github.com", "registry.npmjs.org"]

251 },

252 "credentials": {

253 "envVars": [

254 { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },

255 { "name": "NPM_TOKEN", "mode": "mask" }

256 ]

257 }

258 }

259}

260```

261

262A differenza di `deny`, il mascheramento autorizza il proxy a inviare la tua credenziale reale agli host elencati, quindi viene rispettato solo dalle impostazioni che tu o il tuo amministratore controllate: impostazioni utente, impostazioni gestite e il flag CLI `--settings`. Le voci `mask`, `network.tlsTerminate` e [`credentials.allowPlaintextInject`](/it/settings#sandbox-settings) nel `.claude/settings.json` o `.claude/settings.local.json` di un repository vengono ignorate.

263

264Quando la stessa variabile è elencata con `deny` in qualsiasi ambito, `deny` ha la precedenza.

265

228<h2 id="how-sandboxing-works">266<h2 id="how-sandboxing-works">

229 Come funziona il sandboxing267 Come funziona il sandboxing

230</h2>268</h2>

255* **Copertura completa**: le restrizioni si applicano a tutti gli script, programmi e sottoprocessi generati dai comandi293* **Copertura completa**: le restrizioni si applicano a tutti gli script, programmi e sottoprocessi generati dai comandi

256 294

257<Note>295<Note>

258 Il proxy integrato applica l'allowlist in base al nome host richiesto e non termina o ispeziona il traffico TLS. Vedi [Limitazioni di sicurezza](#security-limitations) per le implicazioni di questo design, e [Configurazione proxy personalizzata](#custom-proxy-configuration) se il tuo modello di minaccia richiede l'ispezione TLS.296 Il proxy integrato applica l'allowlist in base al nome host richiesto e, per impostazione predefinita, non termina o ispeziona il traffico TLS. {/* min-version: 2.1.199 */}L'impostazione sperimentale [`network.tlsTerminate`](/it/settings#sandbox-settings), disponibile in Claude Code v2.1.199 e versioni successive, fa sì che il proxy integrato termini TLS stesso, che le voci di credenziali [`mask`](#protect-credentials) richiedono. Vedi [Limitazioni di sicurezza](#security-limitations) per le implicazioni dell'impostazione predefinita, e [Configurazione proxy personalizzata](#custom-proxy-configuration) se il tuo modello di minaccia richiede l'ispezione TLS.

259</Note>297</Note>

260 298

261<h3 id="os-level-enforcement">299<h3 id="os-level-enforcement">

412 Limitazioni di sicurezza450 Limitazioni di sicurezza

413</h3>451</h3>

414 452

415* **Filtraggio della rete**: il sistema di filtraggio della rete funziona limitando i domini a cui i processi possono connettersi. Il proxy integrato non termina o esegue l'ispezione TLS sul traffico in uscita, quindi i contenuti delle connessioni crittografate non vengono esaminati. Sei responsabile di assicurarti che solo i domini affidabili siano consentiti nella tua politica.453* **Filtraggio della rete**: il sandbox limita i domini a cui i processi possono connettersi. Per impostazione predefinita il proxy integrato non termina o ispeziona TLS sul traffico in uscita, quindi i contenuti delle connessioni crittografate non vengono esaminati. L'impostazione sperimentale [`network.tlsTerminate`](/it/settings#sandbox-settings) termina TLS al proxy per la [sostituzione delle credenziali `mask`](#protect-credentials) ma non aggiunge filtraggio dei contenuti. Sei responsabile di assicurarti che solo i domini affidabili siano consentiti nella tua politica.

416 454

417<Warning>455<Warning>

418 Consentire domini ampi come `github.com` può creare percorsi per l'esfiltrazione di dati. Poiché il proxy prende la sua decisione di consentimento dal nome host fornito dal client senza ispezionare TLS, il codice in esecuzione all'interno della sandbox potrebbe potenzialmente utilizzare [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) o tecniche simili per raggiungere host al di fuori dell'allowlist. Se il tuo modello di minaccia richiede garanzie più forti, configura un [proxy personalizzato](#custom-proxy-configuration) che termina TLS e ispeziona il traffico, e installa il suo certificato CA all'interno della sandbox. L'isolamento della rete più consapevole di TLS è un'area di sviluppo attiva.456 Consentire domini ampi come `github.com` può creare percorsi per l'esfiltrazione di dati. Poiché il proxy prende la sua decisione di consentimento dal nome host fornito dal client senza ispezionare TLS, il codice in esecuzione all'interno della sandbox potrebbe potenzialmente utilizzare [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) o tecniche simili per raggiungere host al di fuori dell'allowlist. Se il tuo modello di minaccia richiede garanzie più forti, configura un [proxy personalizzato](#custom-proxy-configuration) che termina TLS e ispeziona il traffico, e installa il suo certificato CA all'interno della sandbox. L'isolamento della rete più consapevole di TLS è un'area di sviluppo attiva.

440 478

441* **Strumenti di file integrati**: Read, Edit e Write utilizzano il sistema di autorizzazione direttamente piuttosto che eseguire attraverso la sandbox. Vedi [permissions](/it/permissions).479* **Strumenti di file integrati**: Read, Edit e Write utilizzano il sistema di autorizzazione direttamente piuttosto che eseguire attraverso la sandbox. Vedi [permissions](/it/permissions).

442* **Utilizzo del computer**: quando Claude apre app e controlla lo schermo, viene eseguito sul tuo desktop effettivo piuttosto che in un ambiente isolato. I prompt di autorizzazione per app gating ogni applicazione. Vedi [computer use nella CLI](/it/computer-use) o [computer use in Desktop](/it/desktop#let-claude-use-your-computer).480* **Utilizzo del computer**: quando Claude apre app e controlla lo schermo, viene eseguito sul tuo desktop effettivo piuttosto che in un ambiente isolato. I prompt di autorizzazione per app gating ogni applicazione. Vedi [computer use nella CLI](/it/computer-use) o [computer use in Desktop](/it/desktop#let-claude-use-your-computer).

443* **Variabili di ambiente**: i comandi Bash sandboxati ereditano l'ambiente del processo padre per impostazione predefinita, incluse le credenziali impostate lì. Usa [`sandbox.credentials`](#protect-credentials) per annullare variabili specifiche per i comandi sandboxati, o imposta [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/it/env-vars) per rimuovere le credenziali di Anthropic e del provider cloud dai sottoprocessi.481* **Variabili di ambiente**: i comandi Bash sandboxati ereditano l'ambiente del processo padre per impostazione predefinita, incluse le credenziali impostate lì. Usa [`sandbox.credentials`](#protect-credentials) per annullare o mascherare variabili specifiche per i comandi sandboxati, o imposta [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/it/env-vars) per rimuovere le credenziali di Anthropic e del provider cloud dai sottoprocessi.

444* **Subagenti**: i [subagenti](/it/sub-agents) vengono eseguiti nello stesso processo della sessione padre e utilizzano la stessa configurazione sandbox. I comandi Bash all'interno di un subagente vengono sandboxati quando il sandboxing è abilitato nella sessione padre.482* **Subagenti**: i [subagenti](/it/sub-agents) vengono eseguiti nello stesso processo della sessione padre e utilizzano la stessa configurazione sandbox. I comandi Bash all'interno di un subagente vengono sandboxati quando il sandboxing è abilitato nella sessione padre.

445 483

446<Warning>484<Warning>

server-managed-settings.md +24 −8

Details

153 153

154Le impostazioni gestite dal server e le [impostazioni gestite dall'endpoint](/it/settings#settings-files) occupano entrambe il livello più alto nella [gerarchia delle impostazioni](/it/settings#settings-precedence) di Claude Code. Nessun altro livello di impostazioni può sostituirle, inclusi gli argomenti della riga di comando.154Le impostazioni gestite dal server e le [impostazioni gestite dall'endpoint](/it/settings#settings-files) occupano entrambe il livello più alto nella [gerarchia delle impostazioni](/it/settings#settings-precedence) di Claude Code. Nessun altro livello di impostazioni può sostituirle, inclusi gli argomenti della riga di comando.

155 155

156All'interno del livello gestito, un [`policyHelper`](/it/settings#compute-managed-settings-with-a-policy-helper) configurato ha la precedenza su ogni altra fonte gestita, incluse le impostazioni gestite dal server: il suo output diventa l'unica configurazione gestita per l'esecuzione. Altrimenti, la prima fonte che fornisce una configurazione non vuota vince. Le impostazioni gestite dal server vengono controllate per prime, quindi le impostazioni gestite dall'endpoint. Le fonti non si uniscono: se le impostazioni gestite dal server forniscono qualsiasi chiave, le impostazioni gestite dall'endpoint vengono ignorate completamente. Si applica un'eccezione: un piccolo insieme di [chiavi di blocco tra fonti](/it/settings#settings-precedence), come i blocchi della lista di autorizzazione della sandbox, viene rispettato quando qualsiasi fonte gestita controllata dall'amministratore li imposta; il livello del registro HKCU scrivibile dall'utente è escluso. Se le impostazioni gestite dal server non forniscono nulla, le impostazioni gestite dall'endpoint si applicano.156All'interno del livello gestito, un [`policyHelper`](/it/settings#compute-managed-settings-with-a-policy-helper) configurato ha la precedenza su ogni altra fonte gestita, incluse le impostazioni gestite dal server: il suo output diventa l'unica configurazione gestita per l'esecuzione.

157

158Altrimenti, Claude Code utilizza la prima fonte che fornisce una configurazione non vuota. Le impostazioni gestite dal server vengono controllate per prime, quindi le impostazioni gestite dall'endpoint. Le fonti non si uniscono: se le impostazioni gestite dal server forniscono qualsiasi chiave, le altre impostazioni gestite dall'endpoint vengono ignorate. Se le impostazioni gestite dal server non forniscono nulla, le impostazioni gestite dall'endpoint si applicano.

159

160Si applica un'eccezione: un piccolo insieme di [chiavi di blocco tra fonti](/it/settings#settings-precedence), come i blocchi della lista di autorizzazione della sandbox, viene rispettato quando qualsiasi fonte gestita controllata dall'amministratore li imposta; il livello del registro HKCU scrivibile dall'utente è escluso.

157 161

158Se cancellate la configurazione gestita dal server nella console di amministrazione con l'intenzione di tornare a una plist gestita dall'endpoint o a una politica del registro, tenete presente che le [impostazioni memorizzate nella cache](#fetch-and-caching-behavior) persistono sulle macchine client fino al prossimo recupero riuscito. Eseguite `/status` per vedere quale fonte gestita è attiva.162Se cancellate la configurazione gestita dal server nella console di amministrazione con l'intenzione di tornare a una plist gestita dall'endpoint o a una politica del registro, tenete presente che le [impostazioni memorizzate nella cache](#fetch-and-caching-behavior) persistono sulle macchine client fino al prossimo recupero riuscito. Eseguite `/status` per vedere quale fonte gestita è attiva.

159 163

171 175

172**Avvii successivi con impostazioni memorizzate nella cache:**176**Avvii successivi con impostazioni memorizzate nella cache:**

173 177

174* Le impostazioni memorizzate nella cache si applicano immediatamente all'avvio178* Le impostazioni memorizzate nella cache si applicano immediatamente all'avvio, ad eccezione delle variabili di ambiente di trasporto, routing e autenticazione descritte di seguito

175* Claude Code recupera le impostazioni aggiornate in background179* Claude Code recupera le impostazioni aggiornate in background

176* Le impostazioni memorizzate nella cache persistono attraverso i guasti di rete180* Le impostazioni memorizzate nella cache persistono attraverso i guasti di rete. Le variabili di ambiente trattenute rimangono trattenute fino a quando un recupero non riesce

181

182A partire dalla v2.1.198, Claude Code trattiene tre categorie di variabili nel blocco `env` memorizzato nella cache fino a quando il server non conferma il payload per la sessione. Questo impedisce a un valore proxy, autorità di certificazione, endpoint o credenziale memorizzato nella cache di reindirizzare, intercettare o autenticare nuovamente il recupero delle impostazioni che conferma il payload. L'indurimento si applica solo alla cache delle impostazioni recuperate dal server: le [impostazioni gestite dall'endpoint](/it/settings#settings-files) distribuite tramite MDM o `managed-settings.json` non sono interessate. Le categorie trattenute sono:

183

184* Configurazione proxy e TLS, come `HTTPS_PROXY`, `NODE_EXTRA_CA_CERTS` e le variabili del certificato client mTLS `CLAUDE_CODE_CLIENT_CERT` e `CLAUDE_CODE_CLIENT_KEY`

185* Routing API e selezione del provider, inclusi `ANTHROPIC_BASE_URL`, le variabili di selezione del provider come `CLAUDE_CODE_USE_BEDROCK` e `CLAUDE_CODE_USE_VERTEX`, e gli URL dell'endpoint del provider come `ANTHROPIC_BEDROCK_BASE_URL`

186* Credenziali di autenticazione, come `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` e `CLAUDE_CODE_OAUTH_TOKEN`

187

188Ogni altra chiave nel blocco `env` memorizzato nella cache, come la telemetria e la configurazione di OpenTelemetry, si applica all'avvio come prima. Una volta che il recupero riesce, le variabili trattenute si applicano per il resto della sessione.

189

190Se la vostra organizzazione ha bisogno di un proxy per raggiungere `api.anthropic.com`, impostatelo nell'ambiente della shell o nelle [impostazioni utente](/it/settings#settings-files) piuttosto che solo nel blocco `env` gestito. Il primo avvio non ha cache, quindi quelle fonti erano già necessarie per il recupero iniziale.

177 191

178Claude Code applica gli aggiornamenti delle impostazioni automaticamente senza un riavvio, ad eccezione delle impostazioni avanzate come la configurazione di OpenTelemetry, che richiedono un riavvio completo per avere effetto.192Claude Code applica gli aggiornamenti delle impostazioni automaticamente senza un riavvio, ad eccezione delle impostazioni avanzate come la configurazione di OpenTelemetry, che richiedono un riavvio completo per avere effetto.

179 193

217 Finestre di dialogo di approvazione della sicurezza231 Finestre di dialogo di approvazione della sicurezza

218</h3>232</h3>

219 233

220Determinate impostazioni che potrebbero comportare rischi di sicurezza richiedono l'approvazione esplicita dell'utente prima di essere applicate:234Determinate impostazioni che potrebbero comportare rischi di sicurezza richiedono l'approvazione esplicita dell'utente prima che Claude Code le applichi:

221 235

222* **Impostazioni dei comandi shell**: impostazioni che eseguono comandi shell236* **Impostazioni dei comandi shell**: impostazioni che eseguono comandi shell

223* **Variabili di ambiente personalizzate**: variabili non nell'elenco di sicurezza noto237* **Variabili di ambiente personalizzate**: variabili non nell'elenco di sicurezza noto

234 Disponibilità della piattaforma248 Disponibilità della piattaforma

235</h2>249</h2>

236 250

237Le impostazioni gestite dal server richiedono una connessione diretta a `api.anthropic.com`, e la consegna richiede che la sessione si autentichi con un accesso OAuth dell'organizzazione o una chiave API configurata direttamente: le chiavi restituite da uno script [`apiKeyHelper`](/it/settings#available-settings) non attivano il recupero delle impostazioni. Le impostazioni gestite dal server non sono disponibili quando si utilizzano provider di modelli di terze parti:251Le impostazioni gestite dal server richiedono una connessione diretta a `api.anthropic.com`, e la consegna richiede che la sessione si autentichi con un accesso OAuth dell'organizzazione o una chiave API configurata direttamente. Le chiavi restituite da uno script [`apiKeyHelper`](/it/settings#available-settings) non attivano il recupero delle impostazioni.

252

253Le impostazioni gestite dal server non sono disponibili quando si utilizzano provider di modelli di terze parti:

238 254

239* Amazon Bedrock255* Amazon Bedrock

240* Google Vertex AI256* Google Vertex AI

259Le impostazioni gestite dal server forniscono l'applicazione centralizzata dei criteri, ma operano come un controllo lato client, non come un limite di sicurezza. Su dispositivi non gestiti, un utente non ha bisogno dell'accesso amministratore o sudo per aggirarli.275Le impostazioni gestite dal server forniscono l'applicazione centralizzata dei criteri, ma operano come un controllo lato client, non come un limite di sicurezza. Su dispositivi non gestiti, un utente non ha bisogno dell'accesso amministratore o sudo per aggirarli.

260 276

262| :--------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |278| :--------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

263| L'utente modifica il file di impostazioni memorizzato nella cache | Il file manomesso si applica all'avvio, ma le impostazioni corrette si ripristinano al prossimo recupero dal server |279| L'utente modifica il file di impostazioni memorizzato nella cache | Il file manomesso si applica all'avvio, ma le impostazioni corrette si ripristinano al prossimo recupero dal server. {/* min-version: 2.1.198 */}A partire dalla v2.1.198, le variabili di ambiente di trasporto, routing API e autenticazione nel blocco `env` sono [trattenute fino a quando il server non conferma il payload](#fetch-and-caching-behavior) |

264| L'utente elimina il file di impostazioni memorizzato nella cache | Si verifica il comportamento del primo avvio: le impostazioni vengono recuperate in modo asincrono con una breve finestra non applicata |280| L'utente elimina il file di impostazioni memorizzato nella cache | Si verifica il comportamento del primo avvio: le impostazioni vengono recuperate in modo asincrono con una breve finestra non applicata |

265| L'utente esegue un binario Claude Code modificato | Un utente che può eseguire un client modificato può aggirare qualsiasi controllo lato client |281| L'utente esegue un binario Claude Code modificato | Un utente che può eseguire un client modificato può aggirare qualsiasi controllo lato client |

266| L'utente esegue una versione precedente di Claude Code | Le versioni precedenti alle impostazioni gestite dal server non le recuperano o non le applicano |282| L'utente esegue una versione precedente di Claude Code | Le versioni precedenti alle impostazioni gestite dal server non le recuperano o non le applicano |

267| L'API non è disponibile | Le impostazioni memorizzate nella cache si applicano se disponibili, altrimenti le impostazioni gestite non vengono applicate fino al prossimo recupero riuscito. Con `forceRemoteSettingsRefresh: true`, la CLI esce invece di continuare, ad eccezione dei [`claude auth` subcomandi](#enforce-fail-closed-startup) |283| L'API non è disponibile | Le impostazioni memorizzate nella cache si applicano se disponibili, altrimenti le impostazioni gestite non vengono applicate fino al prossimo recupero riuscito. {/* min-version: 2.1.198 */}A partire dalla v2.1.198, le variabili di ambiente di trasporto, routing API e autenticazione nel blocco `env` memorizzato nella cache sono [trattenute in caso di errore di recupero](#fetch-and-caching-behavior); il resto della cache si applica comunque. Con `forceRemoteSettingsRefresh: true`, la CLI esce invece di continuare, ad eccezione dei [`claude auth` subcomandi](#enforce-fail-closed-startup) |

268| L'utente si autentica con un'organizzazione diversa | Le impostazioni non vengono consegnate per gli account al di fuori dell'organizzazione gestita |284| L'utente si autentica con un'organizzazione diversa | Le impostazioni non vengono consegnate per gli account al di fuori dell'organizzazione gestita |

269| L'utente configura un [provider di modelli di terze parti](#platform-availability) | Le impostazioni gestite dal server vengono ignorate. Questo include l'impostazione di `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_MANTLE`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, `CLAUDE_CODE_USE_ANTHROPIC_AWS`, o un `ANTHROPIC_BASE_URL` non predefinito |285| L'utente configura un [provider di modelli di terze parti](#platform-availability) | Le impostazioni gestite dal server vengono ignorate. Questo include l'impostazione di `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_MANTLE`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, `CLAUDE_CODE_USE_ANTHROPIC_AWS`, o un `ANTHROPIC_BASE_URL` non predefinito |

270| Il traffico di rete viene intercettato o reindirizzato | La convalida TLS disabilitata o il traffico intercettato può alterare le impostazioni che il client riceve |286| Il traffico di rete viene intercettato o reindirizzato | La convalida TLS disabilitata o il traffico intercettato può alterare le impostazioni che il client riceve |

sessions.md +2 −0

Details

97/branch try-streaming-approach97/branch try-streaming-approach

98```98```

99 99

100Se ometti il nome, Claude Code assegna un nome al nuovo ramo in base al primo prompt nella conversazione. A partire dalla v2.1.198 questo si applica anche dopo la [compattazione](/it/how-claude-code-works#when-context-fills-up); le versioni precedenti ricadevano nel nome letterale `Branched conversation` invece di guardare oltre il riepilogo della compattazione al prompt originale iniziale.

101

100Dalla riga di comando, combina `--continue` o `--resume` con `--fork-session`:102Dalla riga di comando, combina `--continue` o `--resume` con `--fork-session`:

101 103

102```bash theme={null}104```bash theme={null}

settings.md +17 −4

Details

398Configura il comportamento avanzato del sandboxing. Il sandboxing isola i comandi bash dal tuo filesystem e dalla rete. Vedi [Sandboxing](/it/sandboxing) per i dettagli.398Configura il comportamento avanzato del sandboxing. Il sandboxing isola i comandi bash dal tuo filesystem e dalla rete. Vedi [Sandboxing](/it/sandboxing) per i dettagli.

399 399

401| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------- |401| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

403| `failIfUnavailable` | Esci con un errore all'avvio se `sandbox.enabled` è true ma la sandbox non può avviarsi (dipendenze mancanti, piattaforma non supportata). Quando false (predefinito), viene mostrato un avviso e i comandi vengono eseguiti senza sandbox. Destinato alle distribuzioni di impostazioni gestite che richiedono il sandboxing come gate rigido | `true` |403| `failIfUnavailable` | Esci con un errore all'avvio se `sandbox.enabled` è true ma la sandbox non può avviarsi (dipendenze mancanti, piattaforma non supportata). Quando false (predefinito), viene mostrato un avviso e i comandi vengono eseguiti senza sandbox. Destinato alle distribuzioni di impostazioni gestite che richiedono il sandboxing come gate rigido | `true` |

409| `filesystem.denyRead` | Percorsi dove i comandi sandboxed non possono leggere. Gli array vengono uniti in tutti gli ambiti di impostazioni. Anche uniti con i percorsi dalle regole di permesso `Read(...)` deny. | `["~/.aws/credentials"]` |409| `filesystem.denyRead` | Percorsi dove i comandi sandboxed non possono leggere. Gli array vengono uniti in tutti gli ambiti di impostazioni. Anche uniti con i percorsi dalle regole di permesso `Read(...)` deny. | `["~/.aws/credentials"]` |

410| `filesystem.allowRead` | Percorsi per consentire nuovamente la lettura all'interno delle regioni `denyRead`. Ha la precedenza su `denyRead`. Gli array vengono uniti in tutti gli ambiti di impostazioni. Usa questo per creare modelli di accesso in lettura solo per l'area di lavoro. | `["."]` |410| `filesystem.allowRead` | Percorsi per consentire nuovamente la lettura all'interno delle regioni `denyRead`. Ha la precedenza su `denyRead`. Gli array vengono uniti in tutti gli ambiti di impostazioni. Usa questo per creare modelli di accesso in lettura solo per l'area di lavoro. | `["."]` |

411| `filesystem.allowManagedReadPathsOnly` | (Solo impostazioni gestite) Solo i percorsi `filesystem.allowRead` dalle impostazioni gestite sono rispettati. `denyRead` si unisce comunque da tutte le fonti. Predefinito: false | `true` |411| `filesystem.allowManagedReadPathsOnly` | (Solo impostazioni gestite) Solo i percorsi `filesystem.allowRead` dalle impostazioni gestite sono rispettati. `denyRead` si unisce comunque da tutte le fonti. Predefinito: false | `true` |

412| `credentials.files` | File o directory di credenziali che i comandi sandboxed non possono leggere. Applica lo stesso blocco di lettura di `filesystem.denyRead`; la chiave separata mantiene i percorsi delle credenziali raggruppati con `credentials.envVars` e separati dalle regole generali del filesystem. Ogni voce è `{ "path": "...", "mode": "deny" }`. I percorsi utilizzano gli stessi [prefissi](#sandbox-path-prefixes) di `filesystem.*` impostazioni. Gli array vengono uniti in tutti gli ambiti di impostazioni. Solo `deny` è supportato. Richiede Claude Code v2.1.187 o successivo. | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |412| `credentials.files` | {/* min-version: 2.1.187 */}File o directory di credenziali che i comandi sandboxed non possono leggere. Applica lo stesso blocco di lettura di `filesystem.denyRead`; la chiave separata mantiene i percorsi delle credenziali raggruppati con `credentials.envVars` e separati dalle regole generali del filesystem. Ogni voce è `{ "path": "...", "mode": "deny" }`, e `deny` è l'unica modalità supportata per i file. I percorsi utilizzano gli stessi [prefissi](#sandbox-path-prefixes) di `filesystem.*` impostazioni. Gli array vengono uniti in tutti gli ambiti di impostazioni. Richiede Claude Code v2.1.187 o successivo. | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |

413| `credentials.envVars` | Variabili di ambiente da annullare prima di eseguire i comandi sandboxed. Ogni voce è `{ "name": "...", "mode": "deny" }`. Gli array vengono uniti in tutti gli ambiti di impostazioni. Solo `deny` è supportato. Richiede Claude Code v2.1.187 o successivo. | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |413| `credentials.envVars` | {/* min-version: 2.1.187 */}Variabili di ambiente da [proteggere dai comandi sandboxed](/it/sandboxing#protect-credentials). Ogni voce ha un `name` e una `mode`; il nome deve iniziare con una lettera o un underscore e contenere solo lettere, cifre e underscore. `deny` rimuove la variabile dall'ambiente dei comandi sandboxed. Richiede Claude Code v2.1.187 o successivo. {/* min-version: 2.1.199 */}`mask` sostituisce la variabile con un valore sentinella per sessione all'interno della sandbox mentre il proxy della sandbox sostituisce il valore reale sulle richieste in uscita a `injectHosts` di quella voce; richiede `network.tlsTerminate` e Claude Code v2.1.199 o successivo. Le voci `mask` vengono onorate solo dalle impostazioni utente, gestite, o CLI `--settings`, non da `.claude/settings.json` o `.claude/settings.local.json`. Gli array vengono uniti in tutti gli ambiti di impostazioni, e `deny` ha la precedenza quando la stessa variabile appare con entrambe le modalità. | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |

414| `credentials.envVars[].injectHosts` | Host dove il proxy della sandbox sostituisce il valore reale di una voce `mask`. Ogni host deve essere coperto anche da `network.allowedDomains`, esattamente o da un carattere jolly. Quando non impostato, il proxy sostituisce il valore sulle richieste a ogni host in `network.allowedDomains`. Accettato ma ignorato quando `mode` è `deny`. Richiede Claude Code v2.1.199 o successivo. {/* min-version: 2.1.199 */} | `["api.github.com"]` |

415| `credentials.allowPlaintextInject` | Consenti la sostituzione `mask` anche sulle richieste HTTP semplici oltre a HTTPS con TLS terminato. Su HTTP semplice l'identità upstream non è verificata e la credenziale viaggia in chiaro, quindi lascia questo disattivato al di fuori delle reti di test attendibili. Onorato solo dalle impostazioni utente, gestite, o CLI `--settings`, non da `.claude/settings.json` o `.claude/settings.local.json`. Predefinito: false. Richiede Claude Code v2.1.199 o successivo. {/* min-version: 2.1.199 */} | `true` |

414| `network.allowUnixSockets` | (Solo macOS) Percorsi dei socket Unix accessibili nella sandbox. Ignorato su Linux e WSL2, dove il filtro seccomp non può ispezionare i percorsi dei socket; usa `allowAllUnixSockets` invece. | `["~/.ssh/agent-socket"]` |416| `network.allowUnixSockets` | (Solo macOS) Percorsi dei socket Unix accessibili nella sandbox. Ignorato su Linux e WSL2, dove il filtro seccomp non può ispezionare i percorsi dei socket; usa `allowAllUnixSockets` invece. | `["~/.ssh/agent-socket"]` |

415| `network.allowAllUnixSockets` | Consenti tutte le connessioni ai socket Unix nella sandbox. Su Linux e WSL2 questo è l'unico modo per consentire i socket Unix, poiché salta il filtro seccomp che altrimenti blocca le chiamate `socket(AF_UNIX, ...)`. Predefinito: false | `true` |417| `network.allowAllUnixSockets` | Consenti tutte le connessioni ai socket Unix nella sandbox. Su Linux e WSL2 questo è l'unico modo per consentire i socket Unix, poiché salta il filtro seccomp che altrimenti blocca le chiamate `socket(AF_UNIX, ...)`. Predefinito: false | `true` |

420| `network.allowManagedDomainsOnly` | (Solo impostazioni gestite) Solo `allowedDomains` e le regole allow `WebFetch(domain:...)` dalle impostazioni gestite sono rispettate. I domini dalle impostazioni utente, progetto e locale vengono ignorati. I domini non consentiti vengono bloccati automaticamente senza richiedere all'utente. I domini negati vengono comunque rispettati da tutte le fonti. Predefinito: false | `true` |422| `network.allowManagedDomainsOnly` | (Solo impostazioni gestite) Solo `allowedDomains` e le regole allow `WebFetch(domain:...)` dalle impostazioni gestite sono rispettate. I domini dalle impostazioni utente, progetto e locale vengono ignorati. I domini non consentiti vengono bloccati automaticamente senza richiedere all'utente. I domini negati vengono comunque rispettati da tutte le fonti. Predefinito: false | `true` |

421| `network.httpProxyPort` | Porta del proxy HTTP utilizzata se desideri portare il tuo proxy. Se non specificato, Claude eseguirà il suo proxy. | `8080` |423| `network.httpProxyPort` | Porta del proxy HTTP utilizzata se desideri portare il tuo proxy. Se non specificato, Claude eseguirà il suo proxy. | `8080` |

422| `network.socksProxyPort` | Porta del proxy SOCKS5 utilizzata se desideri portare il tuo proxy. Se non specificato, Claude eseguirà il suo proxy. | `8081` |424| `network.socksProxyPort` | Porta del proxy SOCKS5 utilizzata se desideri portare il tuo proxy. Se non specificato, Claude eseguirà il suo proxy. | `8081` |

425| `network.tlsTerminate` | Sperimentale. Termina TLS all'interno del proxy della sandbox in modo che possa leggere i contenuti delle richieste HTTPS. Richiesto per la [sostituzione delle credenziali](/it/sandboxing#protect-credentials) `mask`. Imposta `{}` per generare un'autorità di certificazione effimera per la sessione, o imposta `caCertPath` e `caKeyPath` per usare la tua. Onorato solo dalle impostazioni utente, gestite, o CLI `--settings`, non da `.claude/settings.json` o `.claude/settings.local.json`. Richiede Claude Code v2.1.199 o successivo. {/* min-version: 2.1.199 */} | `{}` |

423| `enableWeakerNestedSandbox` | Abilita una sandbox più debole per gli ambienti Docker senza privilegi (solo Linux e WSL2). **Riduce la sicurezza.** Predefinito: false | `true` |426| `enableWeakerNestedSandbox` | Abilita una sandbox più debole per gli ambienti Docker senza privilegi (solo Linux e WSL2). **Riduce la sicurezza.** Predefinito: false | `true` |

424| `enableWeakerNetworkIsolation` | (Solo macOS) Consenti l'accesso al servizio di fiducia TLS del sistema (`com.apple.trustd.agent`) nella sandbox. Richiesto affinché gli strumenti basati su Go come `gh`, `gcloud` e `terraform` verifichino i certificati TLS quando si utilizza `httpProxyPort` con un proxy MITM e una CA personalizzata. **Riduce la sicurezza** aprendo un potenziale percorso di esfiltrazione dei dati. Predefinito: false | `true` |427| `enableWeakerNetworkIsolation` | (Solo macOS) Consenti l'accesso al servizio di fiducia TLS del sistema (`com.apple.trustd.agent`) nella sandbox. Richiesto affinché gli strumenti basati su Go come `gh`, `gcloud` e `terraform` verifichino i certificati TLS quando si utilizza `httpProxyPort` con un proxy MITM e una CA personalizzata. **Riduce la sicurezza** aprendo un potenziale percorso di esfiltrazione dei dati. Predefinito: false | `true` |

425| `allowAppleEvents` | (Solo macOS) Consenti ai comandi sandboxed di inviare Apple Events. Richiesto per `open`, `osascript`, e strumenti che aprono URL in un browser, che altrimenti falliscono con errore `-600`. **Rimuove l'isolamento dell'esecuzione del codice.** I comandi sandboxed possono lanciare altre applicazioni senza sandbox senza prompt dell'utente; possono anche inviare comandi AppleScript alle applicazioni in esecuzione come Terminal, soggetto al prompt di consenso per-app macOS automation (TCC). Onorato solo dalle impostazioni utente, gestite, o CLI, non dalle impostazioni di progetto. Predefinito: false | `true` |428| `allowAppleEvents` | (Solo macOS) Consenti ai comandi sandboxed di inviare Apple Events. Richiesto per `open`, `osascript`, e strumenti che aprono URL in un browser, che altrimenti falliscono con errore `-600`. **Rimuove l'isolamento dell'esecuzione del codice.** I comandi sandboxed possono lanciare altre applicazioni senza sandbox senza prompt dell'utente; possono anche inviare comandi AppleScript alle applicazioni in esecuzione come Terminal, soggetto al prompt di consenso per-app macOS automation (TCC). Onorato solo dalle impostazioni utente, gestite, o CLI, non dalle impostazioni di progetto. Predefinito: false | `true` |

6601. **Impostazioni gestite** ([gestite dal server](/it/server-managed-settings), [politiche MDM/a livello di sistema operativo](#configuration-scopes), o [impostazioni gestite](/it/settings#settings-files))6631. **Impostazioni gestite** ([gestite dal server](/it/server-managed-settings), [politiche MDM/a livello di sistema operativo](#configuration-scopes), o [impostazioni gestite](/it/settings#settings-files))

661 * Politiche distribuite da IT tramite consegna dal server, profili di configurazione MDM, politiche di registro, o file di impostazioni gestite664 * Politiche distribuite da IT tramite consegna dal server, profili di configurazione MDM, politiche di registro, o file di impostazioni gestite

662 * Non possono essere ignorate da nessun altro livello, inclusi gli argomenti della riga di comando665 * Non possono essere ignorate da nessun altro livello, inclusi gli argomenti della riga di comando

663 * All'interno del livello gestito, la precedenza è: [`policyHelper`](#compute-managed-settings-with-a-policy-helper) output, che quando configurato è l'unica fonte gestita utilizzata > remoto (impostazioni gestite dal server di [claude.ai](/it/server-managed-settings) o [gateway di app Claude](/it/claude-apps-gateway)-consegnate) > politiche MDM/a livello di sistema operativo > basate su file (`managed-settings.d/*.json` + `managed-settings.json`) > registro HKCU (solo Windows). Viene utilizzata una sola fonte gestita; le fonti non si uniscono tra i livelli, con un'eccezione: le chiavi di blocco sandbox `sandbox.network.allowManagedDomainsOnly` e `sandbox.filesystem.allowManagedReadPathsOnly`, con i loro elenchi di autorizzazione associati, `allowAllClaudeAiMcps`, e i percorsi binari sandbox `sandbox.bwrapPath` e `sandbox.socatPath` vengono onorati quando qualsiasi fonte gestita controllata dall'amministratore li imposta; il livello HKCU scrivibile dall'utente è escluso. All'interno del livello basato su file, i file drop-in e il file base vengono uniti insieme.666 * All'interno del livello gestito, viene utilizzata una sola fonte gestita e le altre vengono ignorate piuttosto che unite. Precedenza, dal più alto al più basso:

667 * Output [`policyHelper`](#compute-managed-settings-with-a-policy-helper): quando configurato, questa è l'unica fonte gestita utilizzata

668 * Remoto (impostazioni gestite dal server di [claude.ai](/it/server-managed-settings) o [gateway di app Claude](/it/claude-apps-gateway)-consegnate)

669 * Politiche MDM/a livello di sistema operativo

670 * Basate su file (`managed-settings.d/*.json` e `managed-settings.json`, unite insieme)

671 * Registro HKCU (solo Windows)

672 * Alcuni tasti sono eccezioni, onorati quando qualsiasi fonte gestita controllata dall'amministratore li imposta piuttosto che solo la fonte vincente. La fonte del registro HKCU scrivibile dall'utente è esclusa. I tasti di eccezione sono:

673 * i tasti di blocco sandbox `sandbox.network.allowManagedDomainsOnly` e `sandbox.filesystem.allowManagedReadPathsOnly`, con i loro elenchi di autorizzazione associati

674 * `allowAllClaudeAiMcps`

675 * i percorsi binari sandbox `sandbox.bwrapPath` e `sandbox.socatPath`

676 * [`forceRemoteSettingsRefresh`](/it/server-managed-settings)

664 * Gli host di incorporamento come Claude Desktop possono fornire politica tramite l'opzione SDK `managedSettings`. Per impostazione predefinita, questo viene ignorato quando è presente una fonte gestita distribuita da un amministratore: impostazioni gestite dal server, una politica MDM o a livello di sistema operativo, o un file di impostazioni gestite. Il fallback del registro HKCU scrivibile dall'utente non conta come una fonte gestita distribuita da un amministratore. Gli amministratori possono acconsentire impostando [`parentSettingsBehavior`](#available-settings) a `"merge"`. I valori dell'embedder vengono filtrati in modo che possano stringere la politica gestita ma non allentarla.677 * Gli host di incorporamento come Claude Desktop possono fornire politica tramite l'opzione SDK `managedSettings`. Per impostazione predefinita, questo viene ignorato quando è presente una fonte gestita distribuita da un amministratore: impostazioni gestite dal server, una politica MDM o a livello di sistema operativo, o un file di impostazioni gestite. Il fallback del registro HKCU scrivibile dall'utente non conta come una fonte gestita distribuita da un amministratore. Gli amministratori possono acconsentire impostando [`parentSettingsBehavior`](#available-settings) a `"merge"`. I valori dell'embedder vengono filtrati in modo che possano stringere la politica gestita ma non allentarla.

665 678

6662. **Argomenti della riga di comando**6792. **Argomenti della riga di comando**

setup.md +1 −1

Details

453 Installare con npm453 Installare con npm

454</h3>454</h3>

455 455

456Potete anche installare Claude Code come pacchetto npm globale. Il pacchetto richiede [Node.js 18 o successivo](https://nodejs.org/en/download).456Potete anche installare Claude Code come pacchetto npm globale. A partire dalla v2.1.198, il pacchetto npm richiede [Node.js 22 o successivo](https://nodejs.org/en/download). Su una versione più vecchia di Node.js, npm stampa un avviso `EBADENGINE` durante l'installazione piuttosto che fallire; l'installazione si completa e `claude` continua a funzionare, poiché il pacchetto scarica un binario nativo che non utilizza il vostro Node.js al runtime.

457 457

458```bash theme={null}458```bash theme={null}

459npm install -g @anthropic-ai/claude-code459npm install -g @anthropic-ai/claude-code

skills.md +6 −0

Details

443 443

444Se invochi una skill con argomenti ma la skill non include `$ARGUMENTS`, Claude Code aggiunge `ARGUMENTS: <your input>` alla fine del contenuto della skill in modo che Claude veda comunque quello che hai digitato.444Se invochi una skill con argomenti ma la skill non include `$ARGUMENTS`, Claude Code aggiunge `ARGUMENTS: <your input>` alla fine del contenuto della skill in modo che Claude veda comunque quello che hai digitato.

445 445

446Puoi anche impilare diverse skills all'inizio di un messaggio. A partire da v2.1.199, digitando `/code-review /fix-issue 123` carica entrambe le skills e passa il testo finale `123` come `$ARGUMENTS` a ciascuna di esse. Nelle versioni precedenti, solo la prima skill si caricava e riceveva `/fix-issue 123` come testo di argomento letterale.

447

448Claude Code espande la prima skill più fino a cinque altre impilate dopo di essa. L'espansione si ferma al primo token che non è una skill invocabile inline dall'utente, quindi una skill che viene eseguita come [subagent con fork](#run-skills-in-a-subagent) o una i cui argomenti potrebbero essi stessi iniziare con un comando slash, come `/loop`, termina anche lì; quel token e tutto ciò che segue diventano il testo di argomento per ogni skill espansa.

449

446Per accedere agli argomenti individuali per posizione, usa `$ARGUMENTS[N]` o il più breve `$N`:450Per accedere agli argomenti individuali per posizione, usa `$ARGUMENTS[N]` o il più breve `$N`:

447 451

448```yaml theme={null}452```yaml theme={null}

624| `"user-invocable-only"` | Nascosto | Sì |628| `"user-invocable-only"` | Nascosto | Sì |

625| `"off"` | Nascosto | Nascosto |629| `"off"` | Nascosto | Nascosto |

626 630

631A partire dalla v2.1.199, `"off"` nasconde anche la skill dagli elenchi di comandi pubblicizzati ai client [Remote Control](/it/remote-control) e ai chiamanti [Agent SDK](/it/agent-sdk/slash-commands), non solo dal menu `/` del terminale. Invocare una skill nascosta per il suo nome completo restituisce comunque l'errore `skillOverrides` invece di eseguirla.

632

627Una skill assente da `skillOverrides` è trattata come `"on"`. L'esempio seguente comprime una skill al suo nome e disattiva completamente un'altra:633Una skill assente da `skillOverrides` è trattata come `"on"`. L'esempio seguente comprime una skill al suo nome e disattiva completamente un'altra:

628 634

629```json theme={null}635```json theme={null}

sub-agents.md +87 −67

Details

24 24

25Claude utilizza la descrizione di ogni subagent per decidere quando delegare le attività. Quando crea un subagent, scriva una descrizione chiara in modo che Claude sappia quando utilizzarlo.25Claude utilizza la descrizione di ogni subagent per decidere quando delegare le attività. Quando crea un subagent, scriva una descrizione chiara in modo che Claude sappia quando utilizzarlo.

26 26

~~27Claude Code include diversi subagent integrati come **Explore**, **Plan** e **general-purpose**. Può anche creare subagent personalizzati per gestire attività specifiche.~~27Claude Code include diversi subagent integrati come Explore, Plan e general-purpose. Può anche creare subagent personalizzati per gestire attività specifiche.

28 28

29<h2 id="built-in-subagents">29<h2 id="built-in-subagents">

30 Subagent integrati30 Subagent integrati

38 <Tab title="Explore">38 <Tab title="Explore">

39 Un agente veloce e di sola lettura ottimizzato per la ricerca e l'analisi delle basi di codice.39 Un agente veloce e di sola lettura ottimizzato per la ricerca e l'analisi delle basi di codice.

40 40

~~41 * **Model**: Haiku, che è veloce e a bassa latenza~~41 * **Model**: eredita dalla conversazione principale, limitato a Opus sull'API Claude, quindi Explore non viene mai eseguito su un modello più costoso di quello che avete già scelto per la sessione

42 * **Tools**: strumenti di sola lettura; Write e Edit sono negati42 * **Tools**: strumenti di sola lettura; Write e Edit sono negati

43 * **Purpose**: scoperta di file, ricerca di codice, esplorazione della base di codice43 * **Purpose**: scoperta di file, ricerca di codice, esplorazione della base di codice

44 44

45 {/* min-version: 2.1.198 */}A partire dalla v2.1.198, Explore eredita il modello della conversazione principale invece di essere sempre eseguito su Haiku. Sull'API Claude, il modello ereditato è limitato a Opus: una conversazione principale su un livello superiore esegue Explore su Opus, e una conversazione principale su Sonnet o Haiku esegue Explore su quello stesso modello. Su qualsiasi altro provider, come [Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, o Claude Platform su AWS](/it/third-party-integrations), Explore eredita direttamente il modello della conversazione principale.

47 Un [subagent utente o progetto](#choose-the-subagent-scope) denominato `Explore` sostituisce quello integrato e mantiene il proprio campo `model`, quindi definite uno con `model: haiku` per mantenere l'esplorazione su un modello a costo inferiore.

45 Claude delega a Explore quando ha bisogno di cercare o comprendere una base di codice senza apportare modifiche. Questo mantiene i risultati dell'esplorazione fuori dal contesto della sua conversazione principale.49 Claude delega a Explore quando ha bisogno di cercare o comprendere una base di codice senza apportare modifiche. Questo mantiene i risultati dell'esplorazione fuori dal contesto della sua conversazione principale.

46 50

47 Quando invoca Explore, Claude specifica un livello di accuratezza: **quick** per ricerche mirate, **medium** per esplorazione equilibrata, o **very thorough** per analisi completa.51 Quando invoca Explore, Claude specifica un livello di accuratezza: **quick** per ricerche mirate, **medium** per esplorazione equilibrata, o **very thorough** per analisi completa.

77 </Tab>81 </Tab>

78</Tabs>82</Tabs>

79 83

~~80I subagent integrati sono sempre registrati nelle sessioni interattive. Per limitarli:~~84I subagent integrati sono registrati per impostazione predefinita nelle sessioni interattive. Per limitarli:

81 85

82* Per bloccare un tipo integrato specifico, aggiungetelo a `permissions.deny` come mostrato in [Disabilitare subagent specifici](#disable-specific-subagents).86* Per bloccare un tipo integrato specifico, aggiungetelo a `permissions.deny` come mostrato in [Disabilitare subagent specifici](#disable-specific-subagents).

83* Per impedire a Claude di delegare a qualsiasi subagent, negate lo strumento `Agent` stesso con [`permissions.deny`](/it/permissions#tool-specific-permission-rules).87* Per impedire a Claude di delegare a qualsiasi subagent, negate lo strumento `Agent` stesso con [`permissions.deny`](/it/permissions#tool-specific-permission-rules).

88* {/* min-version: 2.1.198 */}Per rimuovere solo i subagent integrati `Explore` e `Plan`, impostate [`CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1`](/it/env-vars). Claude legge ed esplora i file direttamente invece di delegare a loro. Richiede Claude Code v2.1.198 o successivo.

84* In [modalità non interattiva](/it/headless) e in [Agent SDK](/it/agent-sdk/overview), impostate [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/it/env-vars) per rimuovere tutti i tipi integrati e fornire solo i vostri.89* In [modalità non interattiva](/it/headless) e in [Agent SDK](/it/agent-sdk/overview), impostate [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/it/env-vars) per rimuovere tutti i tipi integrati e fornire solo i vostri.

85 90

86Oltre a questi subagent integrati, potete creare i vostri con prompt personalizzati, restrizioni di strumenti, modalità di autorizzazione, hooks e skills. Le sezioni seguenti mostrano come iniziare e personalizzare i subagent.91Oltre a questi subagent integrati, potete creare i vostri con prompt personalizzati, restrizioni di strumenti, modalità di autorizzazione, hooks e skills. Le sezioni seguenti mostrano come iniziare e personalizzare i subagent.

89 Quickstart: crea il suo primo subagent94 Quickstart: crea il suo primo subagent

90</h2>95</h2>

91 96

~~92I subagent sono definiti in file Markdown con frontmatter YAML. Può [crearli manualmente](#write-subagent-files) o utilizzare il comando `/agents`.~~97I subagent sono file Markdown con frontmatter YAML. Per crearne uno, chieda a Claude di scriverlo per lei, oppure [scriva il file manualmente](#write-subagent-files).

99{/* min-version: 2.1.198 */}A partire dalla v2.1.198, il comando `/agents` non apre più la procedura guidata di creazione interattiva; eseguirlo stampa un promemoria per chiedere a Claude o modificare direttamente `.claude/agents/`. I file subagent, i campi frontmatter e le posizioni `.claude/agents/` e `~/.claude/agents/` rimangono invariati; solo la procedura guidata del terminale è stata rimossa.

93 100

~~94Questa procedura la guida attraverso la creazione di un subagent a livello utente con il comando `/agents`. Il subagent esamina il codice e suggerisce miglioramenti per la base di codice.~~101Questa procedura crea un subagent a livello utente che esamina il codice e suggerisce miglioramenti.

95 102

96<Steps>103<Steps>

~~97 <Step title="Apra l'interfaccia dei subagent">~~104 <Step title="Chieda a Claude di creare il subagent">

~~98 In Claude Code, esegua:~~105 In Claude Code, descriva il subagent che desidera e dove salvarlo:

99 106

100 ```text wrap theme={null}107 ```text wrap theme={null}

101 /agents108 Create a personal code-improver subagent in ~/.claude/agents/ that scans

109 files and suggests improvements for readability, performance, and best

110 practices. It should explain each issue, show the current code, and

111 provide an improved version. Make it read-only and have it use Sonnet.

102 ```112 ```

103 </Step>

104 113

105 <Step title="Scelga una posizione">114 Claude scrive il file con un `name`, una `description`, un elenco `tools`, un `model` e un prompt di sistema.

106 Selezioni la scheda **Library**, selezioni **Create new agent**, quindi scelga **Personal**. Questo salva il subagent in `~/.claude/agents/` in modo che sia disponibile in tutti i suoi progetti.

107 </Step>115 </Step>

108 116

109 <Step title="Generi con Claude">117 <Step title="Esamini il file">

110 Selezioni **Generate with Claude**. Quando richiesto, descriva il subagent:118 Apra `~/.claude/agents/code-improver.md` e confermi che il frontmatter corrisponda a quello che ha richiesto. Il risultato è simile a questo:

111 119

112 ```text wrap theme={null}120 ```markdown theme={null}

113 A code improvement agent that scans files and suggests improvements121 ---

114 for readability, performance, and best practices. It should explain122 name: code-improver

115 each issue, show the current code, and provide an improved version.123 description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.

124 tools: Read, Grep, Glob

125 model: sonnet

126 ---

127

128 You are a code improvement specialist. For each issue you find, explain

129 the problem, show the current code, and provide an improved version.

116 ```130 ```

117 131

118 Claude genera l'identificatore, la descrizione e il prompt di sistema per lei.132 Poiché il file si trova in `~/.claude/agents/`, il subagent è disponibile in ogni progetto sulla sua macchina. Per limitarlo a un solo progetto, lo sposti nella directory `.claude/agents/` di quel progetto. [Scelga l'ambito del subagent](#choose-the-subagent-scope) confronta i due.

119 </Step>

~~120~~

121 <Step title="Selezioni gli strumenti">

122 Per un revisore di sola lettura, deselezioni tutto tranne **Read-only tools**. Se mantiene tutti gli strumenti selezionati, il subagent eredita tutti gli strumenti disponibili per la conversazione principale.

123 </Step>

~~124~~

125 <Step title="Selezioni il modello">

126 Scelga quale modello utilizza il subagent. Per questo agente di esempio, selezioni **Sonnet**, che bilancia capacità e velocità per analizzare i modelli di codice.

127 </Step>

~~128~~

129 <Step title="Scelga un colore">

130 Scelga un colore di sfondo per il subagent. Questo la aiuta a identificare quale subagent è in esecuzione nell'interfaccia utente.

131 </Step>

~~132~~

133 <Step title="Configuri la memoria">

134 Selezioni **User scope** per dare al subagent una [directory di memoria persistente](#enable-persistent-memory) in `~/.claude/agent-memory/`. Il subagent utilizza questo per accumulare intuizioni tra le conversazioni, come modelli di base di codice e problemi ricorrenti. Selezioni **None** se non vuole che il subagent persista gli insegnamenti.

135 </Step>133 </Step>

136 134

137 <Step title="Salvi e provi">135 <Step title="Lo provi">

138 Esamini il riepilogo della configurazione. Prema `s` o `Enter` per salvare, oppure prema `e` per salvare e modificare il file nel suo editor. Il subagent è disponibile immediatamente. Lo provi:136 Chieda a Claude di delegare al nuovo subagent:

139 137

140 ```text wrap theme={null}138 ```text wrap theme={null}

141 Use the code-improver agent to suggest improvements in this project139 Use the code-improver agent to suggest improvements in this project

142 ```140 ```

143 141

144 Claude delega al suo nuovo subagent, che scansiona la base di codice e restituisce suggerimenti di miglioramento.142 Claude delega al suo nuovo subagent, che scansiona la base di codice e restituisce suggerimenti di miglioramento.

143

144 Se Claude non riesce a trovare il nuovo subagent, riavvii Claude Code e riprovi. Questo accade solo quando `~/.claude/agents/` non esisteva prima dell'inizio della sessione, perché una sessione in esecuzione non rileva una directory `agents` appena creata.

145 </Step>145 </Step>

146</Steps>146</Steps>

147 147

148Ora ha un subagent che può utilizzare in qualsiasi progetto sulla sua macchina per analizzare le basi di codice e suggerire miglioramenti.148Ora ha un subagent che può utilizzare in qualsiasi progetto sulla sua macchina per analizzare le basi di codice e suggerire miglioramenti.

149 149

150Può anche creare subagent manualmente come file Markdown, definirli tramite flag CLI, o distribuirli tramite plugin. Le sezioni seguenti coprono tutte le opzioni di configurazione.150Può anche scrivere file subagent manualmente, definirli tramite flag CLI, o distribuirli tramite plugin. Le sezioni seguenti coprono tutte le opzioni di configurazione.

151

152<Note>

153 Su Claude Code v2.1.197 e versioni precedenti, `/agents` apre una procedura guidata interattiva con una scheda **Running** che elenca i subagent attivi e una scheda **Library** per crearli, modificarli ed eliminarli. {/* max-version: 2.1.197 */}

154</Note>

151 155

152<h2 id="configure-subagents">156<h2 id="configure-subagents">

153 Configuri i subagent157 Configuri i subagent

154</h2>158</h2>

155 159

156<h3 id="use-the-/agents-command">160La posizione del file di un subagent determina chi ha accesso ad esso, e il suo frontmatter determina cosa può fare. Questa sezione copre dove vivono i file dei subagent e ogni campo che supportano.

157 Usi il comando /agents

158</h3>

~~159~~

160Il comando `/agents` apre un'interfaccia a schede per gestire i subagent. La scheda **Running** elenca i subagent live e quelli terminati di recente e le consente di aprirli o fermarli. La scheda **Library** le consente di:

~~161~~

162* Visualizzare tutti i subagent disponibili (integrati, utente, progetto e plugin)

163* Creare nuovi subagent con configurazione guidata o generazione Claude

164* Modificare la configurazione del subagent esistente e l'accesso agli strumenti

165* Eliminare subagent personalizzati

166* Vedere quali subagent sono attivi quando esistono duplicati

~~167~~

168Questo è il modo consigliato per creare e gestire i subagent. Per la creazione manuale o l'automazione, può anche aggiungere file subagent direttamente.

169 161

170<h3 id="choose-the-subagent-scope">162<h3 id="choose-the-subagent-scope">

171 Scelga l'ambito del subagent163 Scelga l'ambito del subagent

172</h3>164</h3>

173 165

174I subagent sono file Markdown con frontmatter YAML. Li archivi in posizioni diverse a seconda dell'ambito. Quando più subagent condividono lo stesso nome, Claude Code utilizza quello dalla posizione con priorità più alta.166Archivi i file dei subagent in posizioni diverse a seconda dell'ambito. Quando più subagent condividono lo stesso nome, Claude Code utilizza quello dalla posizione con priorità più alta.

175 167

177| :----------------------------- | :------------------------- | :---------- | :--------------------------------------------------- |169| :----------------------------- | :------------------------- | :---------- | :--------------------------------------------------- |

183 175

184I **subagent di progetto** (`.claude/agents/`) sono ideali per subagent specifici di una base di codice. Li archivi nel controllo della versione in modo che il suo team possa utilizzarli e migliorarli in modo collaborativo.176I **subagent di progetto** (`.claude/agents/`) sono ideali per subagent specifici di una base di codice. Li archivi nel controllo della versione in modo che il suo team possa utilizzarli e migliorarli in modo collaborativo.

239 231

240I **subagent gestiti** vengono distribuiti dagli amministratori dell'organizzazione. Posizioni file markdown in `.claude/agents/` all'interno della [directory managed settings](/it/settings#settings-files), utilizzando lo stesso formato frontmatter dei subagent di progetto e utente. Le definizioni gestite hanno la precedenza sui subagent di progetto e utente con lo stesso nome.232I **subagent gestiti** vengono distribuiti dagli amministratori dell'organizzazione. Posizioni file markdown in `.claude/agents/` all'interno della [directory managed settings](/it/settings#settings-files), utilizzando lo stesso formato frontmatter dei subagent di progetto e utente. Le definizioni gestite hanno la precedenza sui subagent di progetto e utente con lo stesso nome.

241 233

242I **subagent plugin** provengono da [plugins](/it/plugins) che ha installato. Appaiono in `/agents` insieme ai suoi subagent personalizzati. Consulti il [riferimento dei componenti plugin](/it/plugins-reference#agents) per i dettagli sulla creazione di subagent plugin.234I **subagent plugin** provengono da [plugins](/it/plugins) che ha installato. Si caricano insieme ai suoi subagent personalizzati e appaiono nella typeahead @-mention con il loro nome con ambito. Consulti il [riferimento dei componenti plugin](/it/plugins-reference#agents) per i dettagli sulla creazione di subagent plugin.

243 235

244<Note>236<Note>

245 Per motivi di sicurezza, i subagent plugin non supportano i campi frontmatter `hooks`, `mcpServers` o `permissionMode`. Questi campi vengono ignorati durante il caricamento degli agenti da un plugin. Se ne ha bisogno, copi il file dell'agente in `.claude/agents/` o `~/.claude/agents/`. Può anche aggiungere regole a [`permissions.allow`](/it/settings#permission-settings) in `settings.json` o `settings.local.json`, ma queste regole si applicano all'intera sessione, non solo al subagent plugin.237 Per motivi di sicurezza, i subagent plugin non supportano i campi frontmatter `hooks`, `mcpServers` o `permissionMode`. Questi campi vengono ignorati durante il caricamento degli agenti da un plugin. Se ne ha bisogno, copi il file dell'agente in `.claude/agents/` o `~/.claude/agents/`. Può anche aggiungere regole a [`permissions.allow`](/it/settings#permission-settings) in `settings.json` o `settings.local.json`, ma queste regole si applicano all'intera sessione, non solo al subagent plugin.

254I file subagent utilizzano frontmatter YAML per la configurazione, seguito dal prompt di sistema in Markdown:246I file subagent utilizzano frontmatter YAML per la configurazione, seguito dal prompt di sistema in Markdown:

255 247

256<Note>248<Note>

257 I subagent vengono caricati all'avvio della sessione. Se aggiunge o modifica un file subagent direttamente su disco, riavvii la sua sessione per caricarlo. I subagent creati tramite l'interfaccia `/agents` hanno effetto immediatamente senza un riavvio.249 Claude Code osserva `~/.claude/agents/` e `.claude/agents/`. Quando aggiunge o modifica un file subagent su disco, o chiede a Claude di scriverne uno per lei, Claude Code rileva il cambiamento entro pochi secondi e la prossima delega utilizza la definizione aggiornata, senza necessità di riavvio.

250

251 Due casi richiedono ancora un riavvio:

252

253 * L'osservatore copre solo le directory che esistevano quando la sessione è iniziata, quindi dopo aver creato il primo file agente di un ambito in una nuova directory `agents`, riavvii per caricarlo.

254 * Le sessioni avviate con `--disable-slash-commands` non osservano affatto queste directory.

258</Note>255</Note>

259 256

260```markdown theme={null}257```markdown theme={null}

292| `mcpServers` | No | [MCP servers](/it/mcp) disponibili per questo subagent. Ogni voce è un nome di server che fa riferimento a un server già configurato (ad esempio, `"slack"`) o una definizione inline con il nome del server come chiave e una [configurazione MCP server](/it/mcp#installing-mcp-servers) completa come valore. Ignorato per [subagent plugin](#choose-the-subagent-scope) |289| `mcpServers` | No | [MCP servers](/it/mcp) disponibili per questo subagent. Ogni voce è un nome di server che fa riferimento a un server già configurato (ad esempio, `"slack"`) o una definizione inline con il nome del server come chiave e una [configurazione MCP server](/it/mcp#installing-mcp-servers) completa come valore. Ignorato per [subagent plugin](#choose-the-subagent-scope) |

293| `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) limitati a questo subagent. Ignorato per [subagent plugin](#choose-the-subagent-scope) |290| `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) limitati a questo subagent. Ignorato per [subagent plugin](#choose-the-subagent-scope) |

294| `memory` | No | [Ambito di memoria persistente](#enable-persistent-memory): `user`, `project`, o `local`. Abilita l'apprendimento tra sessioni |291| `memory` | No | [Ambito di memoria persistente](#enable-persistent-memory): `user`, `project`, o `local`. Abilita l'apprendimento tra sessioni |

295| `background` | No | Imposta su `true` per eseguire sempre questo subagent come [background task](#run-subagents-in-foreground-or-background). Predefinito: `false` |292| `background` | No | Imposta su `true` per eseguire sempre questo subagent come [background task](#run-subagents-in-foreground-or-background), anche quando Claude ha bisogno del suo risultato subito. Quando non impostato, Claude sceglie, e {/* min-version: 2.1.198 */}a partire da v2.1.198 esegue i subagent in background per impostazione predefinita |

296| `effort` | No | Livello di sforzo quando questo subagent è attivo. Sostituisce il livello di sforzo della sessione. Predefinito: eredita dalla sessione. Opzioni: `low`, `medium`, `high`, `xhigh`, `max`; i livelli disponibili dipendono dal modello |293| `effort` | No | Livello di sforzo quando questo subagent è attivo. Sostituisce il livello di sforzo della sessione. Predefinito: eredita dalla sessione. Opzioni: `low`, `medium`, `high`, `xhigh`, `max`; i livelli disponibili dipendono dal modello |

297| `isolation` | No | Imposta su `worktree` per eseguire il subagent in un [git worktree](/it/worktrees) temporaneo, dandogli una copia isolata del repository diramata per impostazione predefinita dal suo [ramo predefinito](/it/worktrees#choose-the-base-branch) piuttosto che dall'`HEAD` della sessione principale. Il worktree viene automaticamente pulito se il subagent non apporta modifiche |294| `isolation` | No | Imposta su `worktree` per eseguire il subagent in un [git worktree](/it/worktrees) temporaneo, dandogli una copia isolata del repository diramata per impostazione predefinita dal suo [ramo predefinito](/it/worktrees#choose-the-base-branch) piuttosto che dall'`HEAD` della sessione principale. Il worktree viene automaticamente pulito se il subagent non apporta modifiche |

298| `color` | No | Colore di visualizzazione per il subagent nell'elenco attività e nella trascrizione. Accetta `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, o `cyan` |295| `color` | No | Colore di visualizzazione per il subagent nell'elenco attività e nella trascrizione. Accetta `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, o `cyan` |

318 315

319{/* min-version: 2.1.196 */}A partire da v2.1.196, impostare `CLAUDE_CODE_SUBAGENT_MODEL` su `inherit` è lo stesso che lasciarla non impostata: la risoluzione continua con il parametro `model` per invocazione, quindi il frontmatter. Nelle versioni precedenti, `inherit` forzava i subagent sul modello della conversazione principale e ignorava entrambe quelle fonti.316{/* min-version: 2.1.196 */}A partire da v2.1.196, impostare `CLAUDE_CODE_SUBAGENT_MODEL` su `inherit` è lo stesso che lasciarla non impostata: la risoluzione continua con il parametro `model` per invocazione, quindi il frontmatter. Nelle versioni precedenti, `inherit` forzava i subagent sul modello della conversazione principale e ignorava entrambe quelle fonti.

320 317

321La variabile di ambiente, il parametro per invocazione e i valori frontmatter vengono controllati rispetto alla lista di consentimento [`availableModels`](/it/model-config#restrict-model-selection) della sua organizzazione. Un valore che si risolve in un modello escluso non viene utilizzato e il subagent viene eseguito sul modello ereditato.318Claude Code controlla la variabile di ambiente, il parametro per invocazione e i valori frontmatter rispetto alla lista di consentimento [`availableModels`](/it/model-config#restrict-model-selection) della sua organizzazione. Un valore che si risolve in un modello escluso non viene utilizzato e il subagent viene eseguito sul modello ereditato.

319

320{/* min-version: 2.1.198 */}A partire da v2.1.198, i subagent ereditano anche la configurazione [extended thinking](/it/model-config#extended-thinking) della conversazione principale: se il thinking è attivo nella sua sessione, è attivo per il subagent, e se è spento, rimane spento. Non c'è un'impostazione di thinking per subagent. Prima di v2.1.198, i subagent venivano eseguiti con extended thinking disabilitato indipendentemente dall'impostazione della conversazione principale.

322 321

323<h3 id="control-subagent-capabilities">322<h3 id="control-subagent-capabilities">

324 Controlli le capacità del subagent323 Controlli le capacità del subagent

338* `ScheduleWakeup`337* `ScheduleWakeup`

339* `WaitForMcpServers`338* `WaitForMcpServers`

340 339

341Per limitare gli strumenti, usi il campo `tools` (allowlist) o il campo `disallowedTools` (denylist). Questo esempio usa `tools` per consentire esclusivamente Read, Grep, Glob e Bash. Il subagent non può modificare file, scrivere file o utilizzare alcuno strumento MCP:340Per limitare gli strumenti, usi il campo `tools` come allowlist o il campo `disallowedTools` come denylist. Questo esempio usa `tools` per consentire esclusivamente Read, Grep, Glob e Bash. Il subagent non può modificare file, scrivere file o utilizzare alcuno strumento MCP:

342 341

343```yaml theme={null}342```yaml theme={null}

344---343---

432Use the Playwright tools to navigate, screenshot, and interact with pages.431Use the Playwright tools to navigate, screenshot, and interact with pages.

433```432```

434 433

435Le definizioni inline utilizzano lo stesso schema delle voci del server `.mcp.json` (`stdio`, `http`, `sse`, `ws`), con chiave il nome del server.434Le definizioni inline utilizzano lo stesso schema delle voci del server `.mcp.json`, con chiave il nome del server, e supportano i tipi `stdio`, `http`, `sse` e `ws`.

436 435

437Per mantenere un server MCP fuori dalla conversazione principale e evitare che le descrizioni dei suoi strumenti consumino contesto lì, lo definisca inline qui piuttosto che in `.mcp.json`. Il subagent ottiene gli strumenti; la conversazione principale no.436Per mantenere un server MCP fuori dalla conversazione principale e evitare che le descrizioni dei suoi strumenti consumino contesto lì, lo definisca inline qui piuttosto che in `.mcp.json`. Il subagent ottiene gli strumenti; la conversazione principale no.

438 437

528 Suggerimenti per la memoria persistente527 Suggerimenti per la memoria persistente

529</h5>528</h5>

530 529

531* `project` è l'ambito predefinito consigliato. Lo rende condivisibile tramite controllo della versione. Usi `user` quando la conoscenza del subagent è ampiamente applicabile tra progetti, o `local` quando la conoscenza non dovrebbe essere archiviata nel controllo della versione.530* `project` è l'ambito predefinito consigliato. Lo rende condivisibile tramite controllo della versione.

532* Chieda al subagent di consultare la sua memoria prima di iniziare il lavoro: "Review this PR, and check your memory for patterns you've seen before."531* Chieda al subagent di consultare la sua memoria prima di iniziare il lavoro: "Review this PR, and check your memory for patterns you've seen before."

533* Chieda al subagent di aggiornare la sua memoria dopo aver completato un'attività: "Now that you're done, save what you learned to your memory." Nel tempo, questo costruisce una base di conoscenza che rende il subagent più efficace.532* Chieda al subagent di aggiornare la sua memoria dopo aver completato un'attività: "Now that you're done, save what you learned to your memory." Nel tempo, questo costruisce una base di conoscenza che rende il subagent più efficace.

534* Includa istruzioni di memoria direttamente nel file markdown del subagent in modo che mantenga proattivamente la sua stessa base di conoscenza:533* Includa istruzioni di memoria direttamente nel file markdown del subagent in modo che mantenga proattivamente la sua stessa base di conoscenza:

776* **Subagent in primo piano** bloccano la conversazione principale fino al completamento. I prompt di autorizzazione vengono passati a lei mentre si presentano.775* **Subagent in primo piano** bloccano la conversazione principale fino al completamento. I prompt di autorizzazione vengono passati a lei mentre si presentano.

777* **Subagent in background** vengono eseguiti contemporaneamente mentre continua a lavorare. {/* min-version: 2.1.186 */}A partire da v2.1.186, quando un subagent in background raggiunge una chiamata di strumento che necessita di autorizzazione, il prompt emerge nella sua sessione principale e nomina il subagent che sta chiedendo. Approvi per consentire al subagent di continuare, o premi Esc per negare quella singola chiamata di strumento senza fermare il subagent. Prima di v2.1.186, i subagent in background auto-negavano qualsiasi chiamata di strumento che avrebbe richiesto un prompt.776* **Subagent in background** vengono eseguiti contemporaneamente mentre continua a lavorare. {/* min-version: 2.1.186 */}A partire da v2.1.186, quando un subagent in background raggiunge una chiamata di strumento che necessita di autorizzazione, il prompt emerge nella sua sessione principale e nomina il subagent che sta chiedendo. Approvi per consentire al subagent di continuare, o premi Esc per negare quella singola chiamata di strumento senza fermare il subagent. Prima di v2.1.186, i subagent in background auto-negavano qualsiasi chiamata di strumento che avrebbe richiesto un prompt.

778 777

779Claude decide se eseguire i subagent in primo piano o in background in base all'attività. Può anche:778{/* min-version: 2.1.198 */}A partire da v2.1.198, i subagent vengono eseguiti in background per impostazione predefinita. Claude esegue un subagent in primo piano quando ha bisogno del risultato prima di continuare. L'impostazione predefinita cambia dove viene eseguito un subagent, non cosa gli è consentito fare: i subagent in background continuano a far emergere ogni prompt di autorizzazione nella sua sessione principale. Prima di v2.1.198, Claude sceglieva tra primo piano e background in base all'attività.

780 779

781* Chiedere a Claude di "run this in the background"780Può anche guidare questo lei stesso:

782* Premere **Ctrl+B** per mettere in background un'attività in esecuzione781

782* Chieda a Claude di eseguire un'attività in background o in primo piano

783* Premi **Ctrl+B** per mettere in background un'attività in esecuzione

783 784

784Per disabilitare tutta la funzionalità di background task, imposti la variabile di ambiente `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` su `1`. Consulti [Environment variables](/it/env-vars).785Per disabilitare tutta la funzionalità di background task, imposti la variabile di ambiente `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` su `1`. Consulti [Environment variables](/it/env-vars).

785 786

786Quando [`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation) è impostato su `1`, ogni spawn di subagent viene eseguito in background indipendentemente dal campo `background`. I prompt di autorizzazione da questi subagent in background emergono nella sua sessione principale come descritto sopra.787Quando [`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation) è impostato su `1`, ogni spawn di subagent viene eseguito in background e il campo frontmatter `background` non ha effetto, perché la modalità fork rimuove il parametro `run_in_background` dallo strumento Agent. `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` ha la precedenza sulla modalità fork e mantiene gli spawn di subagent in primo piano.

788

789<h3 id="api-errors-in-subagents">

790 Errori API nei subagent

791</h3>

792

793{/* min-version: 2.1.199 */}A partire da v2.1.199, un subagent la cui esecuzione termina con un errore API, come un limite di utilizzo o un errore server ripetuto, segnala quel fallimento a Claude invece di restituire il testo di errore come se fossero i risultati del subagent. Quello che Claude riceve dipende da dove è stato eseguito il subagent:

794

795* **Primo piano**: se un limite di velocità, un sovraccarico o un errore server interrompe un subagent che ha già prodotto output, lo strumento Agent restituisce quell'output parziale con una nota che il subagent è stato interrotto e non ha completato la sua attività. Altrimenti la chiamata dello strumento fallisce con [`Agent terminated early due to an API error`](/it/errors#agent-terminated-early-due-to-an-api-error), seguito dal dettaglio dell'errore.

796* **Background**: il subagent è contrassegnato come fallito, e il messaggio che Claude riceve quando termina nomina l'errore API e include l'ultimo output del subagent, quindi il lavoro parziale non viene perso.

797

798Una volta che l'errore API sottostante si risolve, chieda a Claude di riprovare l'attività o [riprendere il subagent](#resume-subagents).

787 799

788<h3 id="common-patterns">800<h3 id="common-patterns">

789 Modelli comuni801 Modelli comuni

854 866

855{/* min-version: 2.1.172 */}A partire da Claude Code v2.1.172, un subagent può generare i suoi propri subagent. Usi questo quando un'attività delegata si divide in sottoattività parallele, come un subagent revisore che invia un verificatore per ogni risultato, in modo che l'output intermedio non raggiunga mai la sua conversazione principale. Solo il riassunto del subagent di livello superiore ritorna a lei.867{/* min-version: 2.1.172 */}A partire da Claude Code v2.1.172, un subagent può generare i suoi propri subagent. Usi questo quando un'attività delegata si divide in sottoattività parallele, come un subagent revisore che invia un verificatore per ogni risultato, in modo che l'output intermedio non raggiunga mai la sua conversazione principale. Solo il riassunto del subagent di livello superiore ritorna a lei.

856 868

857Un subagent annidato è configurato nello stesso modo di uno di livello superiore e si risolve dagli stessi [ambiti](#choose-the-subagent-scope). Il pannello dei subagent sotto l'input del prompt mostra l'albero completo: ogni riga visualizza un conteggio `(+N)` di discendenti, e {/* min-version: 2.1.193 */}a partire da v2.1.193, aprire una riga mostra i fratelli e i figli diretti di quel subagent con un percorso di ritorno a `main`. La scheda Running in [`/agents`](#use-the-%2Fagents-command) elenca i subagent in esecuzione come un elenco piatto.869Un subagent annidato è configurato nello stesso modo di uno di livello superiore e si risolve dagli stessi [ambiti](#choose-the-subagent-scope). Il pannello dei subagent sotto l'input del prompt mostra l'albero completo: ogni riga visualizza un conteggio `(+N)` di discendenti, e {/* min-version: 2.1.193 */}a partire da v2.1.193, aprire una riga mostra i fratelli e i figli diretti di quel subagent con un percorso di ritorno a `main`.

858 870

859La profondità viene conteggiata come il numero di livelli di subagent sotto la conversazione principale, indipendentemente dal fatto che ogni livello venga eseguito in [primo piano o in background](#run-subagents-in-foreground-or-background). Un subagent a profondità cinque non riceve lo strumento Agent e non può generare ulteriormente. Il limite è fisso e non configurabile.871La profondità viene conteggiata come il numero di livelli di subagent sotto la conversazione principale, indipendentemente dal fatto che ogni livello venga eseguito in [primo piano o in background](#run-subagents-in-foreground-or-background). Un subagent a profondità cinque non riceve lo strumento Agent e non può generare ulteriormente. Il limite è fisso e non configurabile.

860 872

894 906

895I subagent ripresi mantengono la loro cronologia di conversazione completa, incluse tutte le precedenti chiamate di strumenti, risultati e ragionamento. Il subagent riprende esattamente da dove si era fermato piuttosto che ricominciare da zero.907I subagent ripresi mantengono la loro cronologia di conversazione completa, incluse tutte le precedenti chiamate di strumenti, risultati e ragionamento. Il subagent riprende esattamente da dove si era fermato piuttosto che ricominciare da zero.

896 908

897Quando un subagent completa, Claude riceve il suo ID agente. Gli agenti integrati Explore e Plan sono una tantum e non restituiscono alcun ID agente, quindi non possono essere ripresi; usi `general-purpose` o un subagent personalizzato quando ha bisogno di continuare il lavoro. Claude utilizza lo strumento `SendMessage` con l'ID dell'agente come campo `to` per riprendere. Lo strumento `SendMessage` è sempre disponibile per riprendere i subagent per ID agente o nome. I messaggi strutturati del protocollo di team come `shutdown_request` e `plan_approval_response` richiedono che [agent teams](/it/agent-teams) siano abilitati.909Quando un subagent completa, Claude riceve il suo ID agente. Gli agenti integrati Explore e Plan sono una tantum e non restituiscono alcun ID agente, quindi non possono essere ripresi; usi `general-purpose` o un subagent personalizzato quando ha bisogno di continuare il lavoro.

910

911Claude utilizza lo strumento `SendMessage` con l'ID dell'agente o il nome come campo `to` per riprendere. `SendMessage` non richiede che [agent teams](/it/agent-teams) siano abilitati; solo i messaggi strutturati del protocollo di team come `shutdown_request` e `plan_approval_response` lo fanno.

898 912

899Per riprendere un subagent, chieda a Claude di continuare il lavoro precedente:913Per riprendere un subagent, chieda a Claude di continuare il lavoro precedente:

900 914

908 922

909Se un subagent fermato riceve un `SendMessage`, si auto-riprende in background senza richiedere una nuova invocazione `Agent`.923Se un subagent fermato riceve un `SendMessage`, si auto-riprende in background senza richiedere una nuova invocazione `Agent`.

910 924

925{/* min-version: 2.1.199 */}A partire da v2.1.199, `SendMessage` verifica che un nome si riferisca ancora allo stesso agente che ha raggiunto in precedenza nella conversazione. Se un agente più recente ha preso il nome, come un agente in background ri-generato che lo ha riutilizzato, Claude Code rifiuta l'invio piuttosto che consegnarlo all'agente sbagliato, e l'errore segnala quale agente il nome raggiunge ora in modo che Claude possa reindirizzare. Per raggiungere l'agente precedente mentre è ancora in esecuzione, Claude lo indirizza per l'ID agente dal risultato di spawn. Il controllo è limitato alla conversazione attuale e si ripristina su `/clear`.

926

927{/* min-version: 2.1.198 */}A partire da v2.1.198, un subagent tratta i messaggi dall'agente che lo ha lanciato come direzione di attività normale, incluse le correzioni di corso a metà attività, e agisce su di essi all'interno delle sue impostazioni di autorizzazione. Due limiti continuano a valere indipendentemente da chi ha inviato il messaggio: nessun messaggio da alcun agente conta come la sua approvazione per un prompt di autorizzazione in sospeso, e nessun messaggio di agente può cambiare le impostazioni di autorizzazione, `CLAUDE.md` o configurazione di un subagent. Solo il sistema di autorizzazione o i suoi stessi messaggi possono concedere l'approvazione.

928

911Può anche chiedere a Claude l'ID agente se vuole fare riferimento ad esso esplicitamente, o trovare gli ID nei file di trascrizione in `~/.claude/projects/{project}/{sessionId}/subagents/`. Ogni trascrizione è archiviata come `agent-{agentId}.jsonl`.929Può anche chiedere a Claude l'ID agente se vuole fare riferimento ad esso esplicitamente, o trovare gli ID nei file di trascrizione in `~/.claude/projects/{project}/{sessionId}/subagents/`. Ogni trascrizione è archiviata come `agent-{agentId}.jsonl`.

912 930

913Le trascrizioni dei subagent persistono indipendentemente dalla conversazione principale:931Le trascrizioni dei subagent persistono indipendentemente dalla conversazione principale:

975| `x` | Chiuda un fork finito o fermi uno in esecuzione |993| `x` | Chiuda un fork finito o fermi uno in esecuzione |

976| `Esc` | Restituisca il focus all'input del prompt |994| `Esc` | Restituisca il focus all'input del prompt |

977 995

996Con la trascrizione di un fork o di un subagent aperta, i messaggi di follow-up e le [skills](/it/skills) vanno a quell'agente, ma i comandi incorporati continuano a essere eseguiti nella sua conversazione principale. {/* min-version: 2.1.199 */}A partire da v2.1.199, digitando `/model` o `/fast` in quella visualizzazione viene visualizzato un avviso che cambia il modello della conversazione principale o la modalità veloce, non quello dell'agente visualizzato, invece di eseguirlo silenziosamente.

997

978<h3 id="how-forks-differ-from-named-subagents">998<h3 id="how-forks-differ-from-named-subagents">

979 Come i fork differiscono dai subagent denominati999 Come i fork differiscono dai subagent denominati

980</h3>1000</h3>

1018 Revisore di codice1038 Revisore di codice

1019</h3>1039</h3>

1020 1040

1021Un subagent di sola lettura che esamina il codice senza modificarlo. Questo esempio mostra come progettare un subagent focalizzato con accesso limitato agli strumenti (nessun Edit o Write) e un prompt dettagliato che specifica esattamente cosa cercare e come formattare l'output.1041Un subagent di sola lettura che esamina il codice senza modificarlo. Questo esempio mostra come progettare un subagent focalizzato con accesso limitato agli strumenti che esclude Edit e Write, e un prompt dettagliato che specifica esattamente cosa cercare e come formattare l'output.

1022 1042

1023```markdown theme={null}1043```markdown theme={null}

1024---1044---

third-party-integrations.md +1 −1

Details

196 196

197* [Claude for Teams o Enterprise](/it/authentication#claude-for-teams-or-enterprise)197* [Claude for Teams o Enterprise](/it/authentication#claude-for-teams-or-enterprise)

198* [Anthropic Console](/it/authentication#claude-console-authentication)198* [Anthropic Console](/it/authentication#claude-console-authentication)

199* [Claude apps gateway](/it/claude-apps-gateway), un gateway self-hosted che aggiunge l'accesso IdP davanti ad Amazon Bedrock, Google Vertex AI, Microsoft Foundry o l'API Anthropic199* [Claude apps gateway](/it/claude-apps-gateway), un gateway self-hosted che aggiunge l'accesso IdP davanti ad Amazon Bedrock, Claude Platform on AWS, Google Vertex AI, Microsoft Foundry o l'API Anthropic

200* [Amazon Bedrock](/it/amazon-bedrock)200* [Amazon Bedrock](/it/amazon-bedrock)

201* [Claude Platform on AWS](/it/claude-platform-on-aws)201* [Claude Platform on AWS](/it/claude-platform-on-aws)

202* [Google Vertex AI](/it/google-vertex-ai)202* [Google Vertex AI](/it/google-vertex-ai)

tools-reference.md +21 −11

Details

11Per aggiungere strumenti personalizzati, connetti un [server MCP](/it/mcp). Per estendere Claude con flussi di lavoro basati su prompt riutilizzabili, scrivi una [skill](/it/skills), che viene eseguita attraverso lo strumento `Skill` esistente piuttosto che aggiungere una nuova voce di strumento.11Per aggiungere strumenti personalizzati, connetti un [server MCP](/it/mcp). Per estendere Claude con flussi di lavoro basati su prompt riutilizzabili, scrivi una [skill](/it/skills), che viene eseguita attraverso lo strumento `Skill` esistente piuttosto che aggiungere una nuova voce di strumento.

12 12

14| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------- |14| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------- |

15| `Agent` | Genera un [subagent](/it/sub-agents) con la propria finestra di contesto per gestire un'attività. Vedi [comportamento dello strumento Agent](#agent-tool-behavior) | No |15| `Agent` | Genera un [subagent](/it/sub-agents) con la propria finestra di contesto per gestire un'attività. Vedi [comportamento dello strumento Agent](#agent-tool-behavior) | No |

16| `Artifact` | Pubblica un file HTML o Markdown come [artifact](/it/artifacts): una pagina privata e interattiva su claude.ai. Sui piani Team ed Enterprise, puoi condividerlo all'interno della tua organizzazione. {/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}Richiede un piano Pro, Max, Team, o Enterprise e autenticazione `/login`; vedi [Disponibilità](/it/artifacts#availability) | Sì |16| `Artifact` | Pubblica un file HTML o Markdown come [artifact](/it/artifacts): una pagina privata e interattiva su claude.ai. Sui piani Team ed Enterprise, puoi condividerlo all'interno della tua organizzazione. {/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}Richiede un piano Pro, Max, Team, o Enterprise e autenticazione `/login`; vedi [Disponibilità](/it/artifacts#availability) | Sì |

17| `AskUserQuestion` | Pone domande a scelta multipla per raccogliere requisiti o chiarire ambiguità | No |17| `AskUserQuestion` | Pone domande a scelta multipla per raccogliere requisiti o chiarire ambiguità. {/* min-version: 2.1.198 */}A partire da v2.1.198, se non rispondi entro 60 secondi la finestra di dialogo si chiude automaticamente: invia tutte le opzioni che hai già selezionato e comunica a Claude che potresti essere lontano dalla tastiera, quindi Claude procede secondo il suo giudizio e può ripetere la domanda in seguito. Un conto alla rovescia appare negli ultimi 20 secondi. Qualsiasi pressione di tasto mantiene la finestra di dialogo aperta, così come una finestra focalizzata su terminali che segnalano il focus. Imposta la variabile di ambiente [`CLAUDE_AFK_TIMEOUT_MS`](/it/env-vars#variables) per modificare quanto tempo Claude Code attende, o a un valore grande come `86400000`, 24 ore, per mantenere le domande aperte mentre sei assente. Questo timeout si applica solo alle domande a scelta multipla di `AskUserQuestion`; i prompt di autorizzazione, inclusa l'approvazione del piano, non si risolvono mai automaticamente in caso di inattività | No |

18| `Bash` | Esegue comandi shell nel tuo ambiente. Vedi [comportamento dello strumento Bash](#bash-tool-behavior) | Sì |18| `Bash` | Esegue comandi shell nel tuo ambiente. Vedi [comportamento dello strumento Bash](#bash-tool-behavior) | Sì |

19| `CronCreate` | Pianifica un prompt ricorrente o una tantum all'interno della sessione corrente. Le attività hanno ambito di sessione e vengono ripristinate su `--resume` o `--continue` se non scadute. Vedi [attività pianificate](/it/scheduled-tasks) | No |19| `CronCreate` | Pianifica un prompt ricorrente o una tantum all'interno della sessione corrente. Le attività hanno ambito di sessione e vengono ripristinate su `--resume` o `--continue` se non scadute. Vedi [attività pianificate](/it/scheduled-tasks) | No |

20| `CronDelete` | Annulla un'attività pianificata per ID | No |20| `CronDelete` | Annulla un'attività pianificata per ID | No |

35| `Read` | Legge il contenuto dei file. Vedi [comportamento dello strumento Read](#read-tool-behavior) | No |35| `Read` | Legge il contenuto dei file. Vedi [comportamento dello strumento Read](#read-tool-behavior) | No |

36| `ReadMcpResourceTool` | Legge una risorsa MCP specifica per URI | No |36| `ReadMcpResourceTool` | Legge una risorsa MCP specifica per URI | No |

37| `RemoteTrigger` | Crea, aggiorna, esegue ed elenca [Routine](/it/routines) su claude.ai. Supporta il comando `/schedule`. {/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Le Routine vivono su claude.ai e richiedono un piano Pro, Max, Team, o Enterprise, quindi questo strumento non è accessibile da Amazon Bedrock, Google Vertex AI, o Microsoft Foundry | No |37| `RemoteTrigger` | Crea, aggiorna, esegue ed elenca [Routine](/it/routines) su claude.ai. Supporta il comando `/schedule`. {/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Le Routine vivono su claude.ai e richiedono un piano Pro, Max, Team, o Enterprise, quindi questo strumento non è accessibile da Amazon Bedrock, Google Vertex AI, o Microsoft Foundry | No |

38| `ReportFindings` | Segnala i risultati della revisione del codice come un elenco strutturato, con un file, un riepilogo e uno scenario di errore per ogni risultato, in modo che Claude Code possa renderli invece di stamparli come testo. Claude lo chiama quando le istruzioni di revisione del codice attive lo dicono. {/* min-version: 2.1.196 */}Richiede Claude Code v2.1.196 o successivo | No |38| `ReportFindings` | Segnala i risultati della revisione del codice come un elenco strutturato, con un file, un riepilogo e uno scenario di errore per ogni risultato, in modo che Claude Code possa renderli invece di stamparli come testo. Claude lo chiama quando le istruzioni di revisione del codice attive lo dicono. {/* min-version: 2.1.196 */}Richiede Claude Code v2.1.196 o successivo. {/* min-version: 2.1.199 */}A partire da v2.1.199, un risultato può anche portare uno slug `category` opzionale, come `correctness` o `test-coverage`, mostrato accanto alla posizione del file nell'elenco renderizzato | No |

39| `ScheduleWakeup` | Riprogramma l'iterazione successiva di un [`/loop` auto-paced](/it/scheduled-tasks#let-claude-choose-the-interval). Claude lo chiama alla fine di ogni iterazione per scegliere quando viene eseguita la successiva, tra un minuto e un'ora; non lo chiami direttamente. Il wakeup in sospeso appare in `session_crons` in [Stop hook input](/it/hooks#stop-input). {/* plan-availability: feature=loop-dynamic providers=anthropic */}Non disponibile su Amazon Bedrock, Google Vertex AI, o Microsoft Foundry, dove un prompt `/loop` senza intervallo viene eseguito secondo una pianificazione fissa | No |39| `ScheduleWakeup` | Riprogramma l'iterazione successiva di un [`/loop` auto-paced](/it/scheduled-tasks#let-claude-choose-the-interval). Claude lo chiama alla fine di ogni iterazione per scegliere quando viene eseguita la successiva, tra un minuto e un'ora; non lo chiami direttamente. Il wakeup in sospeso appare in `session_crons` in [Stop hook input](/it/hooks#stop-input). {/* plan-availability: feature=loop-dynamic providers=anthropic */}Non disponibile su Amazon Bedrock, Google Vertex AI, o Microsoft Foundry, dove un prompt `/loop` senza intervallo viene eseguito secondo una pianificazione fissa | No |

40| `SendMessage` | Invia un messaggio a un [team di agenti](/it/agent-teams) compagno, o [riprende un subagent](/it/sub-agents#resume-subagents) per il suo ID agente. I subagent interrotti si riprendono automaticamente in background. I messaggi del protocollo team strutturato richiedono team di agenti | No |40| `SendMessage` | Invia un messaggio a un [team di agenti](/it/agent-teams) compagno, o [riprende un subagent](/it/sub-agents#resume-subagents) per il suo ID agente o nome. I subagent interrotti si riprendono automaticamente in background. I messaggi del protocollo team strutturato richiedono team di agenti. Un ricevente non tratta mai un messaggio da un altro agente come il tuo consenso o approvazione. {/* min-version: 2.1.198 */}A partire da v2.1.198, un subagent tratta un messaggio dall'agente che lo ha lanciato come normale direzione di attività piuttosto che come richiesta tra pari. {/* min-version: 2.1.199 */}A partire da v2.1.199, un invio a un nome che ora si risolve in un agente diverso da quello precedente nella conversazione viene rifiutato invece di essere consegnato; vedi [Riprendi subagent](/it/sub-agents#resume-subagents) | No |

41| `SendUserFile` | Invia file dalla sessione a te con una didascalia opzionale, in modo che un report generato, un diagramma, uno screenshot, o un artefatto costruito raggiunga il tuo dispositivo invece di essere solo menzionato nella trascrizione. {/* min-version: 2.1.196 */}A partire da v2.1.196, l'input opzionale `display` controlla la presentazione: `render` apre il file inline nel client, `attach` mostra solo una scheda di download, e quando non impostato il client decide in base al tipo di file. Disponibile quando un client [Remote Control](/it/remote-control) è connesso o la sessione viene eseguita in un ambiente cloud gestito come [Claude Code sul web](/it/claude-code-on-the-web). La consegna viene eseguita attraverso l'infrastruttura ospitata da Anthropic, quindi lo strumento non è disponibile su Amazon Bedrock, Google Vertex AI, o Microsoft Foundry | No |41| `SendUserFile` | Invia file dalla sessione a te con una didascalia opzionale, in modo che un report generato, un diagramma, uno screenshot, o un artefatto costruito raggiunga il tuo dispositivo invece di essere solo menzionato nella trascrizione. {/* min-version: 2.1.196 */}A partire da v2.1.196, l'input opzionale `display` controlla la presentazione: `render` apre il file inline nel client, `attach` mostra solo una scheda di download, e quando non impostato il client decide in base al tipo di file. Disponibile quando un client [Remote Control](/it/remote-control) è connesso o la sessione viene eseguita in un ambiente cloud gestito come [Claude Code sul web](/it/claude-code-on-the-web). La consegna viene eseguita attraverso l'infrastruttura ospitata da Anthropic, quindi lo strumento non è disponibile su Amazon Bedrock, Google Vertex AI, o Microsoft Foundry | No |

42| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}Carica `ONBOARDING.md` e restituisce un link di condivisione che i compagni di team possono aprire in Claude Code. Chiamato da `/team-onboarding` dopo che la guida è stata scritta. Disponibile per gli abbonati di claude.ai su piani Pro, Max, Team, ed Enterprise | Sì |42| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}Carica `ONBOARDING.md` e restituisce un link di condivisione che i compagni di team possono aprire in Claude Code. Chiamato da `/team-onboarding` dopo che la guida è stata scritta. Disponibile per gli abbonati di claude.ai su piani Pro, Max, Team, ed Enterprise | Sì |

43| `Skill` | Esegue una [skill](/it/skills#control-who-invokes-a-skill) all'interno della conversazione principale | Sì |43| `Skill` | Esegue una [skill](/it/skills#control-who-invokes-a-skill) all'interno della conversazione principale | Sì |

45| `TaskGet` | Recupera i dettagli completi per un'attività specifica | No |45| `TaskGet` | Recupera i dettagli completi per un'attività specifica | No |

46| `TaskList` | Elenca tutte le attività con il loro stato attuale | No |46| `TaskList` | Elenca tutte le attività con il loro stato attuale | No |

47| `TaskOutput` | (Deprecato) Recupera l'output da un'attività in background. Preferisci `Read` sul percorso del file di output dell'attività | No |47| `TaskOutput` | (Deprecato) Recupera l'output da un'attività in background. Preferisci `Read` sul percorso del file di output dell'attività | No |

48| `TaskStop` | Termina un'attività in background in esecuzione per ID | No |48| `TaskStop` | Termina un'attività in background in esecuzione per ID. {/* min-version: 2.1.198 */}A partire da v2.1.198, accetta anche un [compagno di team di agenti](/it/agent-teams) o un agente background denominato per ID agente o nome | No |

49| `TaskUpdate` | Aggiorna lo stato dell'attività, le dipendenze, i dettagli, o elimina le attività | No |49| `TaskUpdate` | Aggiorna lo stato dell'attività, le dipendenze, i dettagli, o elimina le attività | No |

50| `TodoWrite` | {/* min-version: 2.1.142 */}Gestisce l'elenco di controllo delle attività della sessione. Disabilitato per impostazione predefinita a partire da v2.1.142 a favore di `TaskCreate`, `TaskGet`, `TaskList`, e `TaskUpdate`. Imposta `CLAUDE_CODE_ENABLE_TASKS=0` per riabilitare | No |50| `TodoWrite` | {/* min-version: 2.1.142 */}Gestisce l'elenco di controllo delle attività della sessione. Disabilitato per impostazione predefinita a partire da v2.1.142 a favore di `TaskCreate`, `TaskGet`, `TaskList`, e `TaskUpdate`. Imposta `CLAUDE_CODE_ENABLE_TASKS=0` per riabilitare | No |

51| `ToolSearch` | Cerca e carica strumenti differiti quando [tool search](/it/mcp#scale-with-mcp-tool-search) è abilitato | No |51| `ToolSearch` | Cerca e carica strumenti differiti quando [tool search](/it/mcp#scale-with-mcp-tool-search) è abilitato | No |

52| `WaitForMcpServers` | {/* min-version: 2.1.142 */}Attende uno o più [server MCP](/it/mcp) che sono ancora in fase di connessione in background, in modo che una richiesta possa utilizzare i loro strumenti senza riavviare la sessione. Claude lo chiama quando un server necessario non è ancora connesso. Appare solo quando [tool search](/it/mcp#scale-with-mcp-tool-search) è disabilitato, poiché `ToolSearch` gestisce l'attesa quando è abilitato | No |52| `WaitForMcpServers` | Attende uno o più [server MCP](/it/mcp) che sono ancora in fase di connessione in background, in modo che una richiesta possa utilizzare i loro strumenti senza riavviare la sessione. Claude lo chiama quando un server necessario non è ancora connesso. Appare solo quando [tool search](/it/mcp#scale-with-mcp-tool-search) è disabilitato, poiché `ToolSearch` gestisce l'attesa quando è abilitato | No |

53| `WebFetch` | Recupera il contenuto da un URL specificato. Vedi [comportamento dello strumento WebFetch](#webfetch-tool-behavior) | Sì |53| `WebFetch` | Recupera il contenuto da un URL specificato. Vedi [comportamento dello strumento WebFetch](#webfetch-tool-behavior) | Sì |

54| `WebSearch` | Esegue ricerche web. Vedi [comportamento dello strumento WebSearch](#websearch-tool-behavior) | Sì |54| `WebSearch` | Esegue ricerche web. Vedi [comportamento dello strumento WebSearch](#websearch-tool-behavior) | Sì |

55| `Workflow` | Esegue un [flusso di lavoro dinamico](/it/workflows): uno script che orchestra molti subagent in background e restituisce un risultato consolidato | Sì |55| `Workflow` | Esegue un [flusso di lavoro dinamico](/it/workflows): uno script che orchestra molti subagent in background e restituisce un risultato consolidato | Sì |

91 Comportamento dello strumento Agent91 Comportamento dello strumento Agent

92</h2>92</h2>

93 93

94Lo strumento Agent genera un subagent in una finestra di contesto separata. Il subagent lavora attraverso il suo compito autonomamente, quindi restituisce un singolo risultato di testo alla conversazione principale. Il genitore non vede le chiamate di strumento intermedie o gli output del subagent, solo quel risultato finale. Per limitare quanti turni un subagent esegue, imposta `maxTurns` nella [definizione del subagent](/it/sub-agents#supported-frontmatter-fields).94Lo strumento Agent genera un subagent in una finestra di contesto separata. Il subagent lavora attraverso il suo compito autonomamente, quindi restituisce un singolo risultato di testo alla conversazione principale. Il genitore non vede le chiamate di strumento intermedie o gli output del subagent, solo quel risultato finale.

96Per limitare quanti turni un subagent esegue, imposta `maxTurns` nella [definizione del subagent](/it/sub-agents#supported-frontmatter-fields).

95 97

96Lo stesso strumento Agent avvia anche [subagent biforcati](/it/sub-agents#fork-the-current-conversation) quando la modalità fork è abilitata. Un fork eredita la conversazione principale completa invece di iniziare da zero, viene sempre eseguito in background, e comunque fa emergere i prompt di autorizzazione nel tuo terminale. Il resto di questa sezione descrive i subagent denominati.98Lo stesso strumento Agent avvia anche [subagent biforcati](/it/sub-agents#fork-the-current-conversation) quando la modalità fork è abilitata. Un fork eredita la conversazione principale completa invece di iniziare da zero, viene sempre eseguito in background, e comunque fa emergere i prompt di autorizzazione nel tuo terminale. Il resto di questa sezione descrive i subagent denominati.

97 99

102* **Solo `disallowedTools`**: il subagent ottiene ogni strumento del genitore tranne quelli elencati.104* **Solo `disallowedTools`**: il subagent ottiene ogni strumento del genitore tranne quelli elencati.

103* **Entrambi impostati**: `disallowedTools` ha la precedenza. Uno strumento elencato in entrambi viene rimosso.105* **Entrambi impostati**: `disallowedTools` ha la precedenza. Uno strumento elencato in entrambi viene rimosso.

104 106

105L'avvio del subagent non richiede di per sé l'autorizzazione. Le chiamate di strumento del subagent vengono controllate rispetto alle tue regole di autorizzazione mentre viene eseguito:107L'avvio del subagent non richiede di per sé l'autorizzazione. Claude Code controlla le chiamate di strumento del subagent rispetto alle tue regole di autorizzazione mentre viene eseguito.

108

109{/* min-version: 2.1.198 */}A partire dalla v2.1.198, i subagent vengono eseguiti in background per impostazione predefinita; Claude ne esegue uno in primo piano quando ha bisogno del risultato prima di continuare.

106 110

107* **Subagent in primo piano** mostrano gli stessi prompt di autorizzazione che vedresti nella conversazione principale, nel momento in cui ogni chiamata di strumento accade.111* **Subagent in primo piano** mostrano gli stessi prompt di autorizzazione che vedresti nella conversazione principale, nel momento in cui ogni chiamata di strumento accade.

108* **Subagent in background** {/* min-version: 2.1.186 */}fanno emergere i prompt di autorizzazione nella tua sessione principale a partire dalla v2.1.186. Il prompt indica quale subagent sta chiedendo, e premere Esc nega quella singola chiamata di strumento senza fermare il subagent. Prima della v2.1.186, i subagent in background negavano automaticamente qualsiasi chiamata di strumento che altrimenti richiederebbe un prompt e continuavano senza quello strumento.112* **Subagent in background** {/* min-version: 2.1.186 */}fanno emergere i prompt di autorizzazione nella tua sessione principale a partire dalla v2.1.186. Il prompt indica quale subagent sta chiedendo, e premere Esc nega quella singola chiamata di strumento senza fermare il subagent. Prima della v2.1.186, i subagent in background negavano automaticamente qualsiasi chiamata di strumento che altrimenti richiederebbe un prompt e continuavano senza quello strumento.

266 Strumento PowerShell270 Strumento PowerShell

267</h2>271</h2>

268 272

269Lo strumento PowerShell consente a Claude di eseguire comandi PowerShell nativamente. Su Windows, questo significa che i comandi vengono eseguiti in PowerShell invece di essere instradati attraverso Git Bash. Su Windows senza Git Bash, lo strumento è abilitato automaticamente. Su Windows con Git Bash installato, lo strumento è in rollout progressivo. Su Linux, macOS e WSL, lo strumento è opt-in.273Lo strumento PowerShell consente a Claude di eseguire comandi PowerShell nativamente. Su Windows, questo significa che i comandi vengono eseguiti in PowerShell invece di essere instradati attraverso Git Bash. La disponibilità dello strumento dipende dalla tua piattaforma:

274

275* **Windows senza Git Bash**: lo strumento è abilitato automaticamente.

276* **Windows con Git Bash installato**: lo strumento è in rollout progressivo.

277* **Linux, macOS e WSL**: lo strumento è opt-in.

270 278

271<h3 id="enable-the-powershell-tool">279<h3 id="enable-the-powershell-tool">

272 Abilita lo strumento PowerShell280 Abilita lo strumento PowerShell

346 354

347Una regola esplicita `WebFetch(domain:...)` in `deny`, `ask`, o `allow` ha la precedenza rispetto all'insieme preapprovato, quindi puoi bloccare un dominio preapprovato o richiedere un prompt per esso.355Una regola esplicita `WebFetch(domain:...)` in `deny`, `ask`, o `allow` ha la precedenza rispetto all'insieme preapprovato, quindi puoi bloccare un dominio preapprovato o richiedere un prompt per esso.

348 356

349WebFetch imposta un'intestazione `User-Agent` che inizia con `Claude-User`, e un'intestazione `Accept` che preferisce Markdown a HTML in modo che i server che supportano la negoziazione dei contenuti possano restituire Markdown direttamente. [Sandbox](/it/sandboxing) Le regole di rete sono configurate separatamente, quindi un dominio che vuoi che un processo in sandbox raggiunga ha ancora bisogno di una regola di autorizzazione sandbox esplicita.357WebFetch imposta un'intestazione `User-Agent` che inizia con `Claude-User`, e un'intestazione `Accept` che preferisce Markdown a HTML in modo che i server che supportano la negoziazione dei contenuti possano restituire Markdown direttamente.

358

359Configuri le regole di rete [sandbox](/it/sandboxing) separatamente, quindi un dominio che vuoi che un processo in sandbox raggiunga ha ancora bisogno di una regola di autorizzazione sandbox esplicita.

350 360

351<h2 id="websearch-tool-behavior">361<h2 id="websearch-tool-behavior">

352 Comportamento dello strumento WebSearch362 Comportamento dello strumento WebSearch

361Le regole di autorizzazione WebSearch non accettano specifier. Una voce `WebSearch` nuda in `allow` o `deny` è l'unica forma.371Le regole di autorizzazione WebSearch non accettano specifier. Una voce `WebSearch` nuda in `allow` o `deny` è l'unica forma.

362 372

363<Note>373<Note>

364 WebSearch è disponibile sull'API Claude e su Microsoft Foundry. Su Google Cloud Vertex AI funziona con i modelli Claude 4 e versioni successive, inclusi Opus, Sonnet, e Haiku. Amazon Bedrock non espone lo strumento di web search lato server.374 WebSearch è disponibile sull'API Claude, [Claude Platform on AWS](/it/claude-platform-on-aws), e Microsoft Foundry. Su Google Cloud Vertex AI funziona con i modelli Claude 4 e versioni successive, inclusi Opus, Sonnet, e Haiku. Amazon Bedrock non espone lo strumento di web search lato server.

365</Note>375</Note>

366 376

367<h2 id="write-tool-behavior">377<h2 id="write-tool-behavior">

worktrees.md +2 −0

Details

36 36

37Potete anche chiedere a Claude di "lavorare in un worktree" durante una sessione, e creerà uno con lo strumento [`EnterWorktree`](/it/tools-reference). Una volta in un worktree, Claude può passare direttamente a un altro sotto `.claude/worktrees/` chiamando `EnterWorktree` con il percorso di destinazione. Il worktree precedente rimane su disco intatto.37Potete anche chiedere a Claude di "lavorare in un worktree" durante una sessione, e creerà uno con lo strumento [`EnterWorktree`](/it/tools-reference). Una volta in un worktree, Claude può passare direttamente a un altro sotto `.claude/worktrees/` chiamando `EnterWorktree` con il percorso di destinazione. Il worktree precedente rimane su disco intatto.

38 38

39{/* min-version: 2.1.198 */}A partire dalla v2.1.198, entrare o uscire da un worktree trasferisce anche la trascrizione della sessione nella memoria del progetto di quella directory, nello stesso modo in cui [`/cd`](/it/commands) lo fa, quindi `/desktop` e `--resume` trovano la sessione lì in seguito. I worktree creati da un hook [`WorktreeCreate`](#non-git-version-control) sono esclusi e mantengono la trascrizione nella directory di avvio.

39Prima di utilizzare `--worktree` in modo interattivo in una directory per la prima volta, accettate la finestra di dialogo di fiducia dell'area di lavoro eseguendo `claude` una volta in quella directory. Se la fiducia non è stata ancora accettata, `--worktree` esce con un errore e vi chiede di eseguire `claude` nella directory per primo. Le esecuzioni non interattive con `-p` saltano il [controllo di fiducia](/it/security), quindi `claude -p --worktree` procede senza di esso.41Prima di utilizzare `--worktree` in modo interattivo in una directory per la prima volta, accettate la finestra di dialogo di fiducia dell'area di lavoro eseguendo `claude` una volta in quella directory. Se la fiducia non è stata ancora accettata, `--worktree` esce con un errore e vi chiede di eseguire `claude` nella directory per primo. Le esecuzioni non interattive con `-p` saltano il [controllo di fiducia](/it/security), quindi `claude -p --worktree` procede senza di esso.

40 42

41<Tip>43<Tip>

Documentation 2026-07-02 23:59 UTC to 2026-07-03 23:00 UTC