Documentation — Spybara

agent-sdk/agent-loop.md +395 −0 created

Details

1> ## Documentation Index

2> 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.

5# Come funziona il ciclo dell'agente

7> Comprendere il ciclo di vita dei messaggi, l'esecuzione degli strumenti, la finestra di contesto e l'architettura che alimentano gli agenti SDK.

9L'Agent SDK consente di incorporare il ciclo dell'agente autonomo di Claude Code nelle proprie applicazioni. L'SDK è un pacchetto autonomo che fornisce il controllo programmatico su strumenti, autorizzazioni, limiti di costo e output. Non è necessario avere Claude Code CLI installato per utilizzarlo.

11Quando avviate un agente, l'SDK esegue lo stesso [ciclo di esecuzione che alimenta Claude Code](/it/how-claude-code-works#the-agentic-loop): Claude valuta il vostro prompt, chiama gli strumenti per agire, riceve i risultati e ripete fino al completamento dell'attività. Questa pagina spiega cosa accade all'interno di quel ciclo in modo che possiate costruire, eseguire il debug e ottimizzare i vostri agenti in modo efficace.

13## Il ciclo a colpo d'occhio

15Ogni sessione dell'agente segue lo stesso ciclo:

17<img src="https://mintcdn.com/claude-code/gvy2DIUELtNA8qD3/images/agent-loop-diagram.svg?fit=max&auto=format&n=gvy2DIUELtNA8qD3&q=85&s=192e1bd6c8a2950a16e5ee0b94e27e26" alt="Agent loop: prompt enters, Claude evaluates, branches to tool calls or final answer" width="680" height="150" data-path="images/agent-loop-diagram.svg" />

191. **Ricevere il prompt.** Claude riceve il vostro prompt, insieme al prompt di sistema, alle definizioni degli strumenti e alla cronologia della conversazione. L'SDK produce un [`SystemMessage`](#message-types) con sottotipo `"init"` contenente i metadati della sessione.

202. **Valutare e rispondere.** Claude valuta lo stato attuale e determina come procedere. Può rispondere con testo, richiedere una o più chiamate di strumenti, o entrambi. L'SDK produce un [`AssistantMessage`](#message-types) contenente il testo e le richieste di chiamate di strumenti.

213. **Eseguire gli strumenti.** L'SDK esegue ogni strumento richiesto e raccoglie i risultati. Ogni set di risultati degli strumenti viene restituito a Claude per la decisione successiva. Potete utilizzare [hooks](/it/agent-sdk/hooks) per intercettare, modificare o bloccare le chiamate di strumenti prima che vengano eseguite.

224. **Ripetere.** I passaggi 2 e 3 si ripetono come un ciclo. Ogni ciclo completo è un turno. Claude continua a chiamare gli strumenti ed elaborare i risultati fino a quando non produce una risposta senza chiamate di strumenti.

235. **Restituire il risultato.** L'SDK produce un [`AssistantMessage`](#message-types) finale con la risposta di testo (senza chiamate di strumenti), seguito da un [`ResultMessage`](#message-types) con il testo finale, l'utilizzo dei token, il costo e l'ID della sessione.

25Una domanda rapida ("quali file ci sono qui?") potrebbe richiedere uno o due turni di chiamata di `Glob` e risposta con i risultati. Un'attività complessa ("refactorizza il modulo di autenticazione e aggiorna i test") può concatenare dozzine di chiamate di strumenti su molti turni, leggendo file, modificando codice ed eseguendo test, con Claude che adatta il suo approccio in base a ogni risultato.

27## Turni e messaggi

29Un turno è un viaggio di andata e ritorno all'interno del ciclo: Claude produce output che include chiamate di strumenti, l'SDK esegue quegli strumenti e i risultati vengono restituiti a Claude automaticamente. Questo accade senza cedere il controllo al vostro codice. I turni continuano fino a quando Claude non produce output senza chiamate di strumenti, a quel punto il ciclo termina e il risultato finale viene consegnato.

31Considerate come potrebbe apparire una sessione completa per il prompt "Correggi i test falliti in auth.ts".

33Per prima cosa, l'SDK invia il vostro prompt a Claude e produce un [`SystemMessage`](#message-types) con i metadati della sessione. Poi il ciclo inizia:

351. **Turno 1:** Claude chiama `Bash` per eseguire `npm test`. L'SDK produce un [`AssistantMessage`](#message-types) con la chiamata dello strumento, esegue il comando, poi produce un [`UserMessage`](#message-types) con l'output (tre errori).

362. **Turno 2:** Claude chiama `Read` su `auth.ts` e `auth.test.ts`. L'SDK restituisce il contenuto dei file e produce un `AssistantMessage`.

373. **Turno 3:** Claude chiama `Edit` per correggere `auth.ts`, poi chiama `Bash` per rieseguire `npm test`. Tutti e tre i test passano. L'SDK produce un `AssistantMessage`.

384. **Turno finale:** Claude produce una risposta solo di testo senza chiamate di strumenti: "Corretto il bug di autenticazione, tutti e tre i test passano ora." L'SDK produce un `AssistantMessage` finale con questo testo, poi un [`ResultMessage`](#message-types) con lo stesso testo più costo e utilizzo.

40Erano quattro turni: tre con chiamate di strumenti, uno con risposta solo di testo finale.

42Potete limitare il ciclo con `max_turns` / `maxTurns`, che conta solo i turni di utilizzo degli strumenti. Ad esempio, `max_turns=2` nel ciclo precedente si sarebbe fermato prima del passaggio di modifica. Potete anche utilizzare `max_budget_usd` / `maxBudgetUsd` per limitare i turni in base a una soglia di spesa.

44Senza limiti, il ciclo viene eseguito fino a quando Claude non termina da solo, il che va bene per attività ben definite ma può durare a lungo su prompt aperti ("migliora questo codebase"). Impostare un budget è una buona impostazione predefinita per gli agenti di produzione. Vedere [Turni e budget](#turns-and-budget) di seguito per il riferimento alle opzioni.

46## Tipi di messaggi

48Mentre il ciclo viene eseguito, l'SDK produce un flusso di messaggi. Ogni messaggio ha un tipo che vi dice da quale fase del ciclo proviene. I cinque tipi principali sono:

50* **`SystemMessage`:** eventi del ciclo di vita della sessione. Il campo `subtype` li distingue: `"init"` è il primo messaggio (metadati della sessione), e `"compact_boundary"` si attiva dopo la [compattazione](#automatic-compaction). In TypeScript, il confine di compattazione è il suo proprio tipo [`SDKCompactBoundaryMessage`](/it/agent-sdk/typescript#sdkcompactboundarymessage) piuttosto che un sottotipo di `SDKSystemMessage`.

51* **`AssistantMessage`:** emesso dopo ogni risposta di Claude, inclusa quella finale solo di testo. Contiene blocchi di contenuto di testo e blocchi di chiamate di strumenti da quel turno.

52* **`UserMessage`:** emesso dopo ogni esecuzione di strumento con il risultato dello strumento inviato di nuovo a Claude. Emesso anche per qualsiasi input dell'utente che trasmettete a metà ciclo.

53* **`StreamEvent`:** emesso solo quando i messaggi parziali sono abilitati. Contiene eventi di streaming API grezzi (delta di testo, chunk di input dello strumento). Vedere [Stream responses](/it/agent-sdk/streaming-output).

54* **`ResultMessage`:** segna la fine del ciclo dell'agente. Contiene il risultato di testo finale, l'utilizzo dei token, il costo e l'ID della sessione. Controllate il campo `subtype` per determinare se l'attività ha avuto successo o ha raggiunto un limite. Un piccolo numero di eventi di sistema finali, come `prompt_suggestion`, può arrivare dopo di esso, quindi iterate il flusso fino al completamento piuttosto che interrompere al risultato. Vedere [Gestire il risultato](#handle-the-result).

56Questi cinque tipi coprono l'intero ciclo di vita del ciclo dell'agente in entrambi gli SDK. L'SDK TypeScript produce anche eventi di osservabilità aggiuntivi (eventi di hook, progresso dello strumento, limiti di velocità, notifiche di attività) che forniscono dettagli extra ma non sono necessari per guidare il ciclo. Vedere il [riferimento ai tipi di messaggi Python](/it/agent-sdk/python#message-types) e il [riferimento ai tipi di messaggi TypeScript](/it/agent-sdk/typescript#message-types) per gli elenchi completi.

58### Gestire i messaggi

60Quali messaggi gestite dipende da ciò che state costruendo:

62* **Solo risultati finali:** gestite `ResultMessage` per ottenere l'output, il costo e se l'attività ha avuto successo o ha raggiunto un limite.

63* **Aggiornamenti di progresso:** gestite `AssistantMessage` per vedere cosa sta facendo Claude ad ogni turno, inclusi gli strumenti che ha chiamato.

64* **Streaming in tempo reale:** abilitate i messaggi parziali (`include_partial_messages` in Python, `includePartialMessages` in TypeScript) per ottenere messaggi `StreamEvent` in tempo reale. Vedere [Stream responses in real-time](/it/agent-sdk/streaming-output).

66Come controllate i tipi di messaggi dipende dall'SDK:

68* **Python:** controllate i tipi di messaggi con `isinstance()` rispetto alle classi importate da `claude_agent_sdk` (ad esempio, `isinstance(message, ResultMessage)`).

69* **TypeScript:** controllate il campo stringa `type` (ad esempio, `message.type === "result"`). `AssistantMessage` e `UserMessage` avvolgono il messaggio API grezzo in un campo `.message`, quindi i blocchi di contenuto si trovano in `message.message.content`, non in `message.content`.

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

72 <CodeGroup>

73 ```python Python theme={null}

74 from claude_agent_sdk import query, AssistantMessage, ResultMessage

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

77 if isinstance(message, AssistantMessage):

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

79 if isinstance(message, ResultMessage):

80 if message.subtype == "success":

81 print(message.result)

82 else:

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

84 ```

86 ```typescript TypeScript theme={null}

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

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

90 if (message.type === "assistant") {

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

92 }

93 if (message.type === "result") {

94 if (message.subtype === "success") {

95 console.log(message.result);

96 } else {

97 console.log(`Stopped: ${message.subtype}`);

98 }

99 }

100 }

101 ```

102 </CodeGroup>

103</Accordion>

104

105## Esecuzione degli strumenti

106

107Gli strumenti danno al vostro agente la capacità di agire. Senza strumenti, Claude può solo rispondere con testo. Con gli strumenti, Claude può leggere file, eseguire comandi, cercare codice e interagire con servizi esterni.

108

109### Strumenti integrati

110

111L'SDK include gli stessi strumenti che alimentano Claude Code:

112

113| Categoria | Strumenti | Cosa fanno |

114| :--------------------- | :----------------------------------------------- | :--------------------------------------------------------------------------------------- |

115| **Operazioni su file** | `Read`, `Edit`, `Write` | Leggere, modificare e creare file |

116| **Ricerca** | `Glob`, `Grep` | Trovare file per pattern, cercare contenuto con regex |

117| **Esecuzione** | `Bash` | Eseguire comandi shell, script, operazioni git |

118| **Web** | `WebSearch`, `WebFetch` | Cercare il web, recuperare e analizzare pagine |

119| **Scoperta** | `ToolSearch` | Trovare e caricare dinamicamente gli strumenti su richiesta invece di precaricarli tutti |

120| **Orchestrazione** | `Agent`, `Skill`, `AskUserQuestion`, `TodoWrite` | Generare subagenti, invocare skills, chiedere all'utente, tracciare attività |

121

122Oltre agli strumenti integrati, potete:

123

124* **Connettere servizi esterni** con [server MCP](/it/agent-sdk/mcp) (database, browser, API)

125* **Definire strumenti personalizzati** con [gestori di strumenti personalizzati](/it/agent-sdk/custom-tools)

126* **Caricare skills del progetto** tramite [setting sources](/it/agent-sdk/claude-code-features) per flussi di lavoro riutilizzabili

127

128### Autorizzazioni degli strumenti

129

130Claude determina quali strumenti chiamare in base all'attività, ma voi controllate se quelle chiamate sono autorizzate a essere eseguite. Potete approvare automaticamente strumenti specifici, bloccare altri completamente, o richiedere l'approvazione per tutto. Tre opzioni lavorano insieme per determinare cosa viene eseguito:

131

132* **`allowed_tools` / `allowedTools`** approva automaticamente gli strumenti elencati. Un agente di sola lettura con `["Read", "Glob", "Grep"]` nel suo elenco di strumenti consentiti esegue quegli strumenti senza chiedere. Gli strumenti non elencati sono ancora disponibili ma richiedono autorizzazione.

133* **`disallowed_tools` / `disallowedTools`** blocca gli strumenti elencati, indipendentemente da altre impostazioni. Vedere [Autorizzazioni](/it/agent-sdk/permissions) per l'ordine in cui le regole vengono controllate prima che uno strumento venga eseguito.

134* **`permission_mode` / `permissionMode`** controlla cosa accade agli strumenti che non sono coperti da regole di consentimento o negazione. Vedere [Modalità di autorizzazione](#permission-mode) per le modalità disponibili.

135

136Potete anche limitare gli strumenti individuali con regole come `"Bash(npm *)"` per consentire solo comandi specifici. Vedere [Autorizzazioni](/it/agent-sdk/permissions) per la sintassi completa delle regole.

137

138Quando uno strumento viene negato, Claude riceve un messaggio di rifiuto come risultato dello strumento e in genere tenta un approccio diverso o segnala che non potrebbe procedere.

139

140### Esecuzione parallela degli strumenti

141

142Quando Claude richiede più chiamate di strumenti in un singolo turno, entrambi gli SDK possono eseguirli contemporaneamente o sequenzialmente a seconda dello strumento. Gli strumenti di sola lettura (come `Read`, `Glob`, `Grep` e strumenti MCP contrassegnati come di sola lettura) possono essere eseguiti contemporaneamente. Gli strumenti che modificano lo stato (come `Edit`, `Write` e `Bash`) vengono eseguiti sequenzialmente per evitare conflitti.

143

144Gli strumenti personalizzati predefiniti per l'esecuzione sequenziale. Per abilitare l'esecuzione parallela per uno strumento personalizzato, impostare `readOnlyHint` nelle sue annotazioni. Sia l'SDK [TypeScript](/it/agent-sdk/typescript#tool) che [Python](/it/agent-sdk/python#tool) utilizzano questo nome di campo dall'SDK MCP.

145

146## Controllare come viene eseguito il ciclo

147

148Potete limitare quanti turni il ciclo prende, quanto costa, quanto profondamente Claude ragiona e se gli strumenti richiedono approvazione prima di essere eseguiti. Tutti questi sono campi su [`ClaudeAgentOptions`](/it/agent-sdk/python#claudeagentoptions) (Python) / [`Options`](/it/agent-sdk/typescript#options) (TypeScript).

149

150### Turni e budget

151

152| Opzione | Cosa controlla | Predefinito |

153| :--------------------------------------------- | :--------------------------------------------- | :------------ |

154| Max turni (`max_turns` / `maxTurns`) | Massimi round trip di utilizzo degli strumenti | Nessun limite |

155| Max budget (`max_budget_usd` / `maxBudgetUsd`) | Costo massimo prima di fermarsi | Nessun limite |

156

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

158

159### Livello di sforzo

160

161L'opzione `effort` controlla quanto ragionamento Claude applica. I livelli di sforzo inferiori utilizzano meno token per turno e riducono il costo. Non tutti i modelli supportano il parametro di sforzo. Vedere [Effort](https://platform.claude.com/docs/en/build-with-claude/effort) per quali modelli lo supportano.

162

163| Livello | Comportamento | Buono per |

164| :--------- | :----------------------------------- | :------------------------------------------------------ |

165| `"low"` | Ragionamento minimo, risposte veloci | Ricerche di file, elenco di directory |

166| `"medium"` | Ragionamento equilibrato | Modifiche di routine, attività standard |

167| `"high"` | Analisi approfondita | Refactoring, debug |

168| `"xhigh"` | Profondità di ragionamento estesa | Attività di codifica e agentic; consigliato su Opus 4.7 |

169| `"max"` | Profondità di ragionamento massima | Problemi multi-step che richiedono analisi profonda |

170

171Se non impostate `effort`, l'SDK Python lascia il parametro non impostato e rimanda al comportamento predefinito del modello. L'SDK TypeScript predefinisce a `"high"`.

172

173<Note>

174 `effort` scambia latenza e costo dei token per profondità di ragionamento all'interno di ogni risposta. [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) è una funzione separata che produce blocchi di catena di pensiero visibili nell'output. Sono indipendenti: potete impostare `effort: "low"` con extended thinking abilitato, o `effort: "max"` senza di esso.

175</Note>

176

177Utilizzate uno sforzo inferiore per gli agenti che eseguono attività semplici e ben definite (come elencare file o eseguire un singolo grep) per ridurre il costo e la latenza. Impostare `effort` nelle opzioni di livello superiore `query()` per l'intera sessione, o per subagente con il campo `effort` su [`AgentDefinition`](/it/agent-sdk/subagents#agentdefinition-configuration) per sovrascrivere il livello di sessione.

178

179### Modalità di autorizzazione

180

181L'opzione della modalità di autorizzazione (`permission_mode` in Python, `permissionMode` in TypeScript) controlla se l'agente chiede l'approvazione prima di utilizzare gli strumenti:

182

183| Modalità | Comportamento |

184| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

185| `"default"` | Gli strumenti non coperti da regole di consentimento attivano il vostro callback di approvazione; nessun callback significa negare |

186| `"acceptEdits"` | Approva automaticamente le modifiche ai file e i comandi comuni del filesystem (`mkdir`, `touch`, `mv`, `cp`, ecc.); altri comandi Bash seguono le regole predefinite |

187| `"plan"` | Gli strumenti di sola lettura vengono eseguiti; Claude esplora e produce un piano senza modificare i vostri file sorgente |

188| `"dontAsk"` | Non chiede mai. Gli strumenti pre-approvati da [regole di autorizzazione](/it/settings#permission-settings) vengono eseguiti, tutto il resto viene negato |

189| `"auto"` (solo TypeScript) | Utilizza un classificatore di modello per approvare o negare ogni chiamata di strumento. Vedere [Modalità Auto](/it/permission-modes#eliminate-prompts-with-auto-mode) per disponibilità e comportamento |

190| `"bypassPermissions"` | Esegue tutti gli strumenti consentiti senza chiedere. Non può essere utilizzato quando si esegue come root su Unix. Utilizzare solo in ambienti isolati dove le azioni dell'agente non possono influenzare i sistemi che vi interessano |

191

192Per le applicazioni interattive, utilizzate `"default"` con un callback di approvazione dello strumento per visualizzare i prompt di approvazione. Per gli agenti autonomi su una macchina di sviluppo, `"acceptEdits"` approva automaticamente le modifiche ai file e i comandi comuni del filesystem (`mkdir`, `touch`, `mv`, `cp`, ecc.) mentre ancora limita altri comandi `Bash` dietro le regole di consentimento. Riservate `"bypassPermissions"` per CI, container o altri ambienti isolati. Vedere [Autorizzazioni](/it/agent-sdk/permissions) per i dettagli completi.

193

194### Modello

195

196Se non impostate `model`, l'SDK utilizza il predefinito di Claude Code, che dipende dal vostro metodo di autenticazione e dall'abbonamento. Impostatelo esplicitamente (ad esempio, `model="claude-sonnet-4-6"`) per fissare un modello specifico o per utilizzare un modello più piccolo per agenti più veloci e economici. Vedere [models](https://platform.claude.com/docs/en/about-claude/models) per gli ID disponibili.

197

198## La finestra di contesto

199

200La finestra di contesto è la quantità totale di informazioni disponibili a Claude durante una sessione. Non si ripristina tra i turni all'interno di una sessione. Tutto si accumula: il prompt di sistema, le definizioni degli strumenti, la cronologia della conversazione, gli input degli strumenti e gli output degli strumenti. Il contenuto che rimane lo stesso tra i turni (prompt di sistema, definizioni degli strumenti, CLAUDE.md) viene automaticamente [prompt cached](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), il che riduce il costo e la latenza per i prefissi ripetuti.

201

202### Cosa consuma il contesto

203

204Ecco come ogni componente influisce sul contesto nell'SDK:

205

206| Fonte | Quando viene caricato | Impatto |

207| :--------------------------------- | :------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

208| **Prompt di sistema** | Ogni richiesta | Costo fisso piccolo, sempre presente |

209| **File CLAUDE.md** | Inizio della sessione, tramite [`settingSources`](/it/agent-sdk/claude-code-features) | Contenuto completo in ogni richiesta (ma prompt-cached, quindi solo la prima richiesta paga il costo completo) |

210| **Definizioni degli strumenti** | Ogni richiesta | Ogni strumento aggiunge il suo schema; utilizzare [ricerca di strumenti MCP](/it/agent-sdk/mcp#mcp-tool-search) per caricare gli strumenti su richiesta invece di tutti in una volta |

211| **Cronologia della conversazione** | Si accumula nel corso dei turni | Cresce con ogni turno: prompt, risposte, input degli strumenti, output degli strumenti |

212| **Descrizioni delle skills** | Inizio della sessione, tramite setting sources | Brevi riassunti; il contenuto completo viene caricato solo quando invocato |

213

214I grandi output degli strumenti consumano un contesto significativo. Leggere un file grande o eseguire un comando con output dettagliato può utilizzare migliaia di token in un singolo turno. Il contesto si accumula nel corso dei turni, quindi le sessioni più lunghe con molte chiamate di strumenti accumulano significativamente più contesto rispetto a quelle brevi.

215

216### Compattazione automatica

217

218Quando la finestra di contesto si avvicina al suo limite, l'SDK compatta automaticamente la conversazione: riassume la cronologia più vecchia per liberare spazio, mantenendo intatti gli scambi più recenti e le decisioni chiave. L'SDK emette un messaggio con `type: "system"` e `subtype: "compact_boundary"` nel flusso quando questo accade (in Python questo è un `SystemMessage`; in TypeScript è un tipo separato `SDKCompactBoundaryMessage`).

219

220La compattazione sostituisce i messaggi più vecchi con un riassunto, quindi le istruzioni specifiche dall'inizio della conversazione potrebbero non essere preservate. Le regole persistenti appartengono a CLAUDE.md (caricato tramite [`settingSources`](/it/agent-sdk/claude-code-features)) piuttosto che al prompt iniziale, perché il contenuto di CLAUDE.md viene reiniettato ad ogni richiesta.

221

222Potete personalizzare il comportamento della compattazione in diversi modi:

223

224* **Istruzioni di riassunto in CLAUDE.md:** Il compattatore legge il vostro CLAUDE.md come qualsiasi altro contesto, quindi potete includere una sezione che gli dice cosa preservare quando riassume. L'intestazione della sezione è libera (non una stringa magica); il compattatore corrisponde all'intento.

225* **Hook `PreCompact`:** Eseguire logica personalizzata prima che si verifichi la compattazione, ad esempio per archiviare la trascrizione completa. L'hook riceve un campo `trigger` (`manual` o `auto`). Vedere [hooks](/it/agent-sdk/hooks).

226* **Compattazione manuale:** Inviare `/compact` come stringa di prompt per attivare la compattazione su richiesta. (I comandi slash inviati in questo modo sono input SDK, non scorciatoie solo CLI. Vedere [slash commands nell'SDK](/it/agent-sdk/slash-commands).)

227

228<Accordion title="Esempio: Istruzioni di riassunto in CLAUDE.md">

229 Aggiungete una sezione al vostro CLAUDE.md del progetto dicendo al compattatore cosa preservare. Il nome dell'intestazione non è speciale; utilizzate qualsiasi etichetta chiara.

230

231 ```markdown CLAUDE.md theme={null}

232 # Summary instructions

233

234 When summarizing this conversation, always preserve:

235 - The current task objective and acceptance criteria

236 - File paths that have been read or modified

237 - Test results and error messages

238 - Decisions made and the reasoning behind them

239 ```

240</Accordion>

241

242### Mantenere il contesto efficiente

243

244Alcune strategie per gli agenti a lunga durata:

245

246* **Utilizzare subagenti per sottoattività.** Ogni subagente inizia con una conversazione fresca (nessuna cronologia di messaggi precedenti, anche se carica il suo prompt di sistema e il contesto a livello di progetto come CLAUDE.md). Non vede i turni del genitore e solo la sua risposta finale ritorna al genitore come risultato dello strumento. Il contesto dell'agente principale cresce per quel riassunto, non per la trascrizione completa della sottoattività. Vedere [Cosa ereditano i subagenti](/it/agent-sdk/subagents#what-subagents-inherit) per i dettagli.

247* **Essere selettivi con gli strumenti.** Ogni definizione di strumento occupa spazio di contesto. Utilizzate il campo `tools` su [`AgentDefinition`](/it/agent-sdk/subagents#agentdefinition-configuration) per limitare i subagenti al set minimo di cui hanno bisogno, e utilizzate [ricerca di strumenti MCP](/it/agent-sdk/mcp#mcp-tool-search) per caricare gli strumenti su richiesta invece di precaricarli tutti.

248* **Controllare i costi dei server MCP.** Ogni server MCP aggiunge tutti i suoi schemi di strumenti a ogni richiesta. Pochi server con molti strumenti possono consumare un contesto significativo prima che l'agente faccia qualsiasi lavoro. Lo strumento `ToolSearch` può aiutare caricando gli strumenti su richiesta invece di precaricarli tutti. Vedere [ricerca di strumenti MCP](/it/agent-sdk/mcp#mcp-tool-search) per la configurazione.

249* **Utilizzare uno sforzo inferiore per attività di routine.** Impostare [effort](#effort-level) a `"low"` per gli agenti che hanno solo bisogno di leggere file o elencare directory. Questo riduce l'utilizzo dei token e il costo.

250

251Per una ripartizione dettagliata dei costi di contesto per funzione, vedere [Comprendere i costi di contesto](/it/features-overview#understand-context-costs).

252

253## Sessioni e continuità

254

255Ogni interazione con l'SDK crea o continua una sessione. Catturate l'ID della sessione da `ResultMessage.session_id` (disponibile in entrambi gli SDK) per riprendere in seguito. L'SDK TypeScript lo espone anche come campo diretto sul `SystemMessage` init; in Python è annidato in `SystemMessage.data`.

256

257Quando riprendete, il contesto completo dai turni precedenti viene ripristinato: file che sono stati letti, analisi che è stata eseguita e azioni che sono state intraprese. Potete anche fare un fork di una sessione per diramarvisi in un approccio diverso senza modificare l'originale.

258

259Vedere [Gestione della sessione](/it/agent-sdk/sessions) per la guida completa sui pattern di ripresa, continuazione e fork.

260

261<Note>

262 In Python, `ClaudeSDKClient` gestisce gli ID di sessione automaticamente tra più chiamate. Vedere il [riferimento SDK Python](/it/agent-sdk/python#choosing-between-query-and-claudesdkclient) per i dettagli.

263</Note>

264

265## Gestire il risultato

266

267Quando il ciclo termina, il `ResultMessage` vi dice cosa è successo e vi fornisce l'output. Il campo `subtype` (disponibile in entrambi gli SDK) è il modo principale per controllare lo stato di terminazione.

268

269| Sottotipo del risultato | Cosa è successo | Campo `result` disponibile? |

270| :------------------------------------ | :-------------------------------------------------------------------------------------- | :-------------------------: |

271| `success` | Claude ha completato l'attività normalmente | Sì |

272| `error_max_turns` | Ha raggiunto il limite di `maxTurns` prima di terminare | No |

273| `error_max_budget_usd` | Ha raggiunto il limite di `maxBudgetUsd` prima di terminare | No |

274| `error_during_execution` | Un errore ha interrotto il ciclo (ad esempio, un errore API o una richiesta annullata) | No |

275| `error_max_structured_output_retries` | La convalida dell'output strutturato ha fallito dopo il limite di tentativi configurato | No |

276

277Il 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`.

278

279Il 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.

280

281## Hooks

282

283[Hooks](/it/agent-sdk/hooks) sono callback che si attivano in punti specifici del ciclo: prima che uno strumento venga eseguito, dopo che ritorna, quando l'agente termina e così via. Alcuni hook comunemente utilizzati sono:

284

285| Hook | Quando si attiva | Usi comuni |

286| :------------------------------- | :---------------------------------------------- | :--------------------------------------------------------- |

287| `PreToolUse` | Prima che uno strumento venga eseguito | Convalidare gli input, bloccare i comandi pericolosi |

288| `PostToolUse` | Dopo che uno strumento ritorna | Controllare gli output, attivare effetti collaterali |

289| `UserPromptSubmit` | Quando un prompt viene inviato | Iniettare contesto aggiuntivo nei prompt |

290| `Stop` | Quando l'agente termina | Convalidare il risultato, salvare lo stato della sessione |

291| `SubagentStart` / `SubagentStop` | Quando un subagente viene generato o completato | Tracciare e aggregare i risultati delle attività parallele |

292| `PreCompact` | Prima della compattazione del contesto | Archiviare la trascrizione completa prima di riassumere |

293

294Gli hook vengono eseguiti nel vostro processo di applicazione, non all'interno della finestra di contesto dell'agente, quindi non consumano contesto. Gli hook possono anche cortocircuitare il ciclo: un hook `PreToolUse` che rifiuta una chiamata di strumento impedisce che venga eseguita e Claude riceve il messaggio di rifiuto invece.

295

296Entrambi gli SDK supportano tutti gli eventi precedenti. L'SDK TypeScript include eventi aggiuntivi che Python non supporta ancora. Vedere [Controllare l'esecuzione con gli hooks](/it/agent-sdk/hooks) per l'elenco completo degli eventi, la disponibilità per SDK e l'API di callback completa.

297

298## Mettere tutto insieme

299

300Questo 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.

301

302<CodeGroup>

303 ```python Python theme={null}

304 import asyncio

305 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

306

307

308 async def run_agent():

309 session_id = None

310

311 async for message in query(

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

313 options=ClaudeAgentOptions(

314 allowed_tools=[

315 "Read",

316 "Edit",

317 "Bash",

318 "Glob",

319 "Grep",

320 ], # Listing tools here auto-approves them (no prompting)

321 setting_sources=[

322 "project"

323 ], # Load CLAUDE.md, skills, hooks from current directory

324 max_turns=30, # Prevent runaway sessions

325 effort="high", # Thorough reasoning for complex debugging

326 ),

327 ):

328 # Handle the final result

329 if isinstance(message, ResultMessage):

330 session_id = message.session_id # Save for potential resumption

331

332 if message.subtype == "success":

333 print(f"Done: {message.result}")

334 elif message.subtype == "error_max_turns":

335 # Agent ran out of turns. Resume with a higher limit.

336 print(f"Hit turn limit. Resume session {session_id} to continue.")

337 elif message.subtype == "error_max_budget_usd":

338 print("Hit budget limit.")

339 else:

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

341 if message.total_cost_usd is not None:

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

343

344

345 asyncio.run(run_agent())

346 ```

347

348 ```typescript TypeScript theme={null}

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

350

351 let sessionId: string | undefined;

352

353 for await (const message of query({

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

355 options: {

356 allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting)

357 settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory

358 maxTurns: 30, // Prevent runaway sessions

359 effort: "high" // Thorough reasoning for complex debugging

360 }

361 })) {

362 // Save the session ID to resume later if needed

363 if (message.type === "system" && message.subtype === "init") {

364 sessionId = message.session_id;

365 }

366

367 // Handle the final result

368 if (message.type === "result") {

369 if (message.subtype === "success") {

370 console.log(`Done: ${message.result}`);

371 } else if (message.subtype === "error_max_turns") {

372 // Agent ran out of turns. Resume with a higher limit.

373 console.log(`Hit turn limit. Resume session ${sessionId} to continue.`);

374 } else if (message.subtype === "error_max_budget_usd") {

375 console.log("Hit budget limit.");

376 } else {

377 console.log(`Stopped: ${message.subtype}`);

378 }

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

380 }

381 }

382 ```

383</CodeGroup>

384

385## Passaggi successivi

386

387Ora che comprendete il ciclo, ecco dove andare a seconda di ciò che state costruendo:

388

389* **Non avete ancora eseguito un agente?** Iniziate con la [quickstart](/it/agent-sdk/quickstart) per ottenere l'SDK installato e vedere un esempio completo in esecuzione da capo a fondo.

390* **Pronti a collegarvi al vostro progetto?** [Caricate CLAUDE.md, skills e filesystem hooks](/it/agent-sdk/claude-code-features) in modo che l'agente segua automaticamente le convenzioni del vostro progetto.

391* **State costruendo un'interfaccia utente interattiva?** Abilitate lo [streaming](/it/agent-sdk/streaming-output) per mostrare testo e chiamate di strumenti in tempo reale mentre il ciclo viene eseguito.

392* **Avete bisogno di un controllo più stretto su ciò che l'agente può fare?** Bloccate l'accesso agli strumenti con [autorizzazioni](/it/agent-sdk/permissions) e utilizzate [hooks](/it/agent-sdk/hooks) per controllare, bloccare o trasformare le chiamate di strumenti prima che vengano eseguite.

393* **State eseguendo attività lunghe o costose?** Delegate il lavoro isolato ai [subagenti](/it/agent-sdk/subagents) per mantenere il vostro contesto principale snello.

394

395Per il quadro concettuale più ampio del ciclo agentic (non specifico dell'SDK), vedere [Come funziona Claude Code](/it/how-claude-code-works).

agent-sdk/hooks.md +11 −11

Details

236Il vostro callback restituisce un oggetto con due categorie di campi:236Il vostro callback restituisce un oggetto con due categorie di campi:

237 237

238* **Campi di livello superiore** controllano la conversazione: `systemMessage` inietta un messaggio nella conversazione visibile al modello e `continue` (`continue_` in Python) determina se l'agente continua a funzionare dopo questo hook.238* **Campi di livello superiore** controllano la conversazione: `systemMessage` inietta un messaggio nella conversazione visibile al modello e `continue` (`continue_` in Python) determina se l'agente continua a funzionare dopo questo hook.

239* **`hookSpecificOutput`** controlla l'operazione corrente. I campi all'interno dipendono dal tipo di evento hook. Per gli hook `PreToolUse`, è qui che impostate `permissionDecision` (`"allow"`, `"deny"` o `"ask"`), `permissionDecisionReason` e `updatedInput`. Nell'SDK TypeScript, `permissionDecision` accetta anche `"defer"` per terminare la query e [riprendere in seguito](/it/hooks#defer-a-tool-call-for-later); questo valore non è disponibile nell'SDK Python. Per gli hook `PostToolUse`, potete impostare `additionalContext` per aggiungere informazioni al risultato dello strumento.239* **`hookSpecificOutput`** controlla l'operazione corrente. I campi all'interno dipendono dal tipo di evento hook. Per gli hook `PreToolUse`, è qui che impostate `permissionDecision` (`"allow"`, `"deny"` o `"ask"`), `permissionDecisionReason` e `updatedInput`. Nell'SDK TypeScript, `permissionDecision` accetta anche `"defer"` per terminare la query e [riprendere in seguito](/it/hooks#defer-a-tool-call-for-later); questo valore non è disponibile nell'SDK Python. Per gli hook `PostToolUse`, potete impostare `additionalContext` per aggiungere informazioni al risultato dello strumento, o `updatedToolOutput` per sostituire completamente l'output dello strumento prima che Claude lo veda.

240 240

241Restituite `{}` per consentire l'operazione senza modifiche. Gli hook di callback SDK utilizzano lo stesso formato di output JSON degli [hook dei comandi shell di Claude Code](/it/hooks#json-output), che documenta ogni campo e opzione specifica dell'evento. Per le definizioni di tipo SDK, consultate i riferimenti SDK [TypeScript](/it/agent-sdk/typescript#sync-hook-json-output) e [Python](/it/agent-sdk/python#sync-hook-json-output).241Restituite `{}` per consentire l'operazione senza modifiche. Gli hook di callback SDK utilizzano lo stesso formato di output JSON degli [hook dei comandi shell di Claude Code](/it/hooks#json-output), che documenta ogni campo e opzione specifica dell'evento. Per le definizioni di tipo SDK, consultate i riferimenti SDK [TypeScript](/it/agent-sdk/typescript#sync-hook-json-output) e [Python](/it/agent-sdk/python#sync-hook-json-output).

242 242

417 ```417 ```

418</CodeGroup>418</CodeGroup>

419 419

420### Concatenare più hook420### Registrare più hook

421 421

422Gli hooks vengono eseguiti nell'ordine in cui appaiono nell'array. Mantenete ogni hook focalizzato su una singola responsabilità e concatenate più hook per logica complessa:422Quando un evento si attiva, tutti gli hook corrispondenti vengono eseguiti in parallelo. Per le decisioni di autorizzazione, il risultato più restrittivo vince: un singolo `deny` blocca la chiamata dello strumento indipendentemente da ciò che gli altri hook restituiscono. Poiché l'ordine di completamento è non deterministico, scrivete ogni hook per agire in modo indipendente piuttosto che fare affidamento su un altro hook che sia stato eseguito per primo.

423

424L'esempio seguente registra tre controlli indipendenti per ogni chiamata a uno strumento:

423 425

424<CodeGroup>426<CodeGroup>

425 ```python Python theme={null}427 ```python Python theme={null}

426 options = ClaudeAgentOptions(428 options = ClaudeAgentOptions(

427 hooks={429 hooks={

428 "PreToolUse": [430 "PreToolUse": [

429 HookMatcher(hooks=[rate_limiter]), # First: check rate limits431 HookMatcher(hooks=[authorization_check]),

430 HookMatcher(hooks=[authorization_check]), # Second: verify permissions432 HookMatcher(hooks=[input_validator]),

431 HookMatcher(hooks=[input_sanitizer]), # Third: sanitize inputs433 HookMatcher(hooks=[audit_logger]),

432 HookMatcher(hooks=[audit_logger]), # Last: log the action

433 ]434 ]

434 }435 }

435 )436 )

439 const options = {440 const options = {

440 hooks: {441 hooks: {

441 PreToolUse: [442 PreToolUse: [

442 { hooks: [rateLimiter] }, // First: check rate limits443 { hooks: [authorizationCheck] },

443 { hooks: [authorizationCheck] }, // Second: verify permissions444 { hooks: [inputValidator] },

444 { hooks: [inputSanitizer] }, // Third: sanitize inputs445 { hooks: [auditLogger] }

445 { hooks: [auditLogger] } // Last: log the action

446 ]446 ]

447 }447 }

448 };448 };

agent-sdk/migration-guide.md +289 −0 created

Details

1> ## Documentation Index

2> 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.

5# Migrazione a Claude Agent SDK

7> Guida per la migrazione dei Claude Code SDK TypeScript e Python a Claude Agent SDK

9## Panoramica

11Claude Code SDK è stato rinominato in **Claude Agent SDK** e la sua documentazione è stata riorganizzata. Questo cambiamento riflette le capacità più ampie dell'SDK per la creazione di agenti AI oltre ai soli compiti di codifica.

13## Cosa è cambiato

15| Aspetto | Precedente | Nuovo |

16| :--------------------------------- | :-------------------------- | :------------------------------- |

17| **Nome del pacchetto (TS/JS)** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` |

18| **Pacchetto Python** | `claude-code-sdk` | `claude-agent-sdk` |

19| **Posizione della documentazione** | Documentazione Claude Code | API Guide → Sezione Agent SDK |

21<Note>

22 **Modifiche alla documentazione:** La documentazione di Agent SDK è stata spostata dalla documentazione di Claude Code alla API Guide in una sezione dedicata [Agent SDK](/it/agent-sdk/overview). La documentazione di Claude Code ora si concentra sullo strumento CLI e sulle funzionalità di automazione.

23</Note>

25## Passaggi di migrazione

27### Per progetti TypeScript/JavaScript

29**1. Disinstallare il pacchetto precedente:**

31```bash theme={null}

32npm uninstall @anthropic-ai/claude-code

33```

35**2. Installare il nuovo pacchetto:**

37```bash theme={null}

38npm install @anthropic-ai/claude-agent-sdk

39```

41**3. Aggiornare gli import:**

43Modificare tutti gli import da `@anthropic-ai/claude-code` a `@anthropic-ai/claude-agent-sdk`:

45```typescript theme={null}

46// Prima

47import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

49// Dopo

50import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

51```

53**4. Aggiornare le dipendenze in package.json:**

55Se il pacchetto è elencato nel vostro `package.json`, aggiornarlo:

57Prima:

59```json theme={null}

60{

61 "dependencies": {

62 "@anthropic-ai/claude-code": "^0.0.42"

63 }

64}

65```

67Dopo:

69```json theme={null}

70{

71 "dependencies": {

72 "@anthropic-ai/claude-agent-sdk": "^0.2.0"

73 }

74}

75```

77Questo è tutto! Non sono richieste altre modifiche al codice.

79### Per progetti Python

81**1. Disinstallare il pacchetto precedente:**

83```bash theme={null}

84pip uninstall claude-code-sdk

85```

87**2. Installare il nuovo pacchetto:**

89```bash theme={null}

90pip install claude-agent-sdk

91```

93**3. Aggiornare gli import:**

95Modificare tutti gli import da `claude_code_sdk` a `claude_agent_sdk`:

97```python theme={null}

98# Prima

99from claude_code_sdk import query, ClaudeCodeOptions

100

101# Dopo

102from claude_agent_sdk import query, ClaudeAgentOptions

103```

104

105**4. Aggiornare i nomi dei tipi:**

106

107Modificare `ClaudeCodeOptions` in `ClaudeAgentOptions`:

108

109```python theme={null}

110# Prima

111from claude_code_sdk import query, ClaudeCodeOptions

112

113options = ClaudeCodeOptions(model="claude-opus-4-7")

114

115# Dopo

116from claude_agent_sdk import query, ClaudeAgentOptions

117

118options = ClaudeAgentOptions(model="claude-opus-4-7")

119```

120

121**5. Rivedere i [cambiamenti significativi](#breaking-changes)**

122

123Apportare le modifiche al codice necessarie per completare la migrazione.

124

125## Cambiamenti significativi

126

127<Warning>

128 Per migliorare l'isolamento e la configurazione esplicita, Claude Agent SDK v0.1.0 introduce cambiamenti significativi per gli utenti che migrano da Claude Code SDK. Rivedere attentamente questa sezione prima di eseguire la migrazione.

129</Warning>

130

131### Python: ClaudeCodeOptions rinominato in ClaudeAgentOptions

132

133**Cosa è cambiato:** Il tipo Python SDK `ClaudeCodeOptions` è stato rinominato in `ClaudeAgentOptions`.

134

135**Migrazione:**

136

137```python theme={null}

138# PRIMA (claude-code-sdk)

139from claude_code_sdk import query, ClaudeCodeOptions

140

141options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

142

143# DOPO (claude-agent-sdk)

144from claude_agent_sdk import query, ClaudeAgentOptions

145

146options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

147```

148

149**Perché è cambiato:** Il nome del tipo ora corrisponde al branding "Claude Agent SDK" e fornisce coerenza nelle convenzioni di denominazione dell'SDK.

150

151### System prompt non è più predefinito

152

153**Cosa è cambiato:** L'SDK non utilizza più il system prompt di Claude Code per impostazione predefinita.

154

155**Migrazione:**

156

157<CodeGroup>

158 ```typescript TypeScript theme={null}

159 // PRIMA (v0.0.x) - Utilizzava il system prompt di Claude Code per impostazione predefinita

160 const result = query({ prompt: "Hello" });

161

162 // DOPO (v0.1.0) - Utilizza un system prompt minimo per impostazione predefinita

163 // Per ottenere il comportamento precedente, richiedere esplicitamente il preset di Claude Code:

164 const result = query({

165 prompt: "Hello",

166 options: {

167 systemPrompt: { type: "preset", preset: "claude_code" }

168 }

169 });

170

171 // Oppure utilizzare un system prompt personalizzato:

172 const result = query({

173 prompt: "Hello",

174 options: {

175 systemPrompt: "You are a helpful coding assistant"

176 }

177 });

178 ```

179

180 ```python Python theme={null}

181 # PRIMA (v0.0.x) - Utilizzava il system prompt di Claude Code per impostazione predefinita

182 async for message in query(prompt="Hello"):

183 print(message)

184

185 # DOPO (v0.1.0) - Utilizza un system prompt minimo per impostazione predefinita

186 # Per ottenere il comportamento precedente, richiedere esplicitamente il preset di Claude Code:

187 from claude_agent_sdk import query, ClaudeAgentOptions

188

189 async for message in query(

190 prompt="Hello",

191 options=ClaudeAgentOptions(

192 system_prompt={"type": "preset", "preset": "claude_code"} # Utilizzare il preset

193 ),

194 ):

195 print(message)

196

197 # Oppure utilizzare un system prompt personalizzato:

198 async for message in query(

199 prompt="Hello",

200 options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),

201 ):

202 print(message)

203 ```

204</CodeGroup>

205

206**Perché è cambiato:** Fornisce un migliore controllo e isolamento per le applicazioni SDK. Ora è possibile creare agenti con comportamento personalizzato senza ereditare le istruzioni focalizzate sulla CLI di Claude Code.

207

208### Impostazioni predefinite delle fonti

209

210Questo valore predefinito è stato brevemente modificato in v0.1.0 e successivamente ripristinato, quindi non è necessaria alcuna azione di migrazione.

211

212**Comportamento attuale:** Omettendo `settingSources` su `query()` vengono caricate le impostazioni dell'utente, del progetto e del file system locale, corrispondendo alla CLI. Questo include `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, file CLAUDE.md e comandi personalizzati.

213

214Per eseguire l'isolamento dalle impostazioni del file system, passare un array vuoto:

215

216<CodeGroup>

217 ```typescript TypeScript theme={null}

218 const result = query({

219 prompt: "Hello",

220 options: {

221 settingSources: [] // Nessuna impostazione del file system caricata

222 }

223 });

224

225 // Oppure caricare solo fonti specifiche:

226 const result = query({

227 prompt: "Hello",

228 options: {

229 settingSources: ["project"] // Solo impostazioni del progetto

230 }

231 });

232 ```

233

234 ```python Python theme={null}

235 from claude_agent_sdk import query, ClaudeAgentOptions

236

237 async for message in query(

238 prompt="Hello",

239 options=ClaudeAgentOptions(setting_sources=[]), # Nessuna impostazione del file system caricata

240 ):

241 print(message)

242

243 # Oppure caricare solo fonti specifiche:

244 async for message in query(

245 prompt="Hello",

246 options=ClaudeAgentOptions(

247 setting_sources=["project"] # Solo impostazioni del progetto

248 ),

249 ):

250 print(message)

251 ```

252</CodeGroup>

253

254L'isolamento è particolarmente importante per le pipeline CI/CD, le applicazioni distribuite, gli ambienti di test e i sistemi multi-tenant dove le personalizzazioni locali non dovrebbero infiltrarsi.

255

256<Note>

257 SDK v0.1.0 ha brevemente impostato per impostazione predefinita nessuna impostazione caricata; questo è stato ripristinato nelle versioni successive. Python SDK 0.1.59 e versioni precedenti hanno trattato un elenco vuoto come l'omissione dell'opzione, quindi eseguire l'aggiornamento prima di fare affidamento su `setting_sources=[]`. Vedere [Cosa settingSources non controlla](/it/agent-sdk/claude-code-features#what-settingsources-does-not-control) per gli input che vengono letti anche quando `settingSources` è `[]`.

258</Note>

259

260## Perché il cambio di nome?

261

262Claude Code SDK è stato originariamente progettato per compiti di codifica, ma si è evoluto in un framework potente per la creazione di tutti i tipi di agenti AI. Il nuovo nome "Claude Agent SDK" riflette meglio le sue capacità:

263

264* Creazione di agenti aziendali (assistenti legali, consulenti finanziari, supporto clienti)

265* Creazione di agenti di codifica specializzati (bot SRE, revisori di sicurezza, agenti di revisione del codice)

266* Sviluppo di agenti personalizzati per qualsiasi dominio con utilizzo di strumenti, integrazione MCP e altro ancora

267

268## Ottenere aiuto

269

270Se si incontrano problemi durante la migrazione:

271

272**Per TypeScript/JavaScript:**

273

2741. Verificare che tutti gli import siano aggiornati per utilizzare `@anthropic-ai/claude-agent-sdk`

2752. Verificare che il vostro package.json abbia il nuovo nome del pacchetto

2763. Eseguire `npm install` per assicurarsi che le dipendenze siano aggiornate

277

278**Per Python:**

279

2801. Verificare che tutti gli import siano aggiornati per utilizzare `claude_agent_sdk`

2812. Verificare che il vostro requirements.txt o pyproject.toml abbia il nuovo nome del pacchetto

2823. Eseguire `pip install claude-agent-sdk` per assicurarsi che il pacchetto sia installato

283

284## Passaggi successivi

285

286* Esplorare la [Panoramica di Agent SDK](/it/agent-sdk/overview) per conoscere le funzionalità disponibili

287* Consultare il [Riferimento SDK TypeScript](/it/agent-sdk/typescript) per la documentazione dettagliata dell'API

288* Rivedere il [Riferimento SDK Python](/it/agent-sdk/python) per la documentazione specifica di Python

289* Scopri di più su [Strumenti personalizzati](/it/agent-sdk/custom-tools) e [Integrazione MCP](/it/agent-sdk/mcp)

agent-sdk/permissions.md +242 −0 created

Details

1> ## Documentation Index

2> 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.

5# Configurare i permessi

7> Controlla come il tuo agente utilizza gli strumenti con modalità di permesso, hook e regole dichiarative di consentimento/negazione.

9Claude Agent SDK fornisce controlli di permesso per gestire come Claude utilizza gli strumenti. Utilizza modalità di permesso e regole per definire cosa è consentito automaticamente, e il callback [`canUseTool`](/it/agent-sdk/user-input) per gestire tutto il resto in fase di esecuzione.

11<Note>

12 Questa pagina copre le modalità di permesso e le regole. Per creare flussi di approvazione interattivi in cui gli utenti approvano o negano le richieste di strumenti in fase di esecuzione, vedi [Gestire approvazioni e input dell'utente](/it/agent-sdk/user-input).

13</Note>

15## Come vengono valutati i permessi

17Quando Claude richiede uno strumento, l'SDK controlla i permessi in questo ordine:

19<Steps>

20 <Step title="Hooks">

21 Esegui [hooks](/it/agent-sdk/hooks) per primo. Un hook può negare la chiamata completamente o trasmetterla. Un hook che restituisce `allow` non salta le regole di negazione e richiesta di seguito; quelle vengono valutate indipendentemente dal risultato dell'hook.

22 </Step>

24 <Step title="Regole di negazione">

25 Controlla le regole `deny` (da `disallowed_tools` e [settings.json](/it/settings#permission-settings)). Se una regola di negazione corrisponde, lo strumento viene bloccato, anche in modalità `bypassPermissions`.

26 </Step>

28 <Step title="Modalità di permesso">

29 Applica la [modalità di permesso](#permission-modes) attiva. `bypassPermissions` approva tutto ciò che raggiunge questo passaggio. `acceptEdits` approva le operazioni su file. Le altre modalità passano oltre.

30 </Step>

32 <Step title="Regole di consentimento">

33 Controlla le regole `allow` (da `allowed_tools` e settings.json). Se una regola corrisponde, lo strumento viene approvato.

34 </Step>

36 <Step title="Callback canUseTool">

37 Se non risolto da nessuno dei precedenti, chiama il tuo callback [`canUseTool`](/it/agent-sdk/user-input) per una decisione. In modalità `dontAsk`, questo passaggio viene saltato e lo strumento viene negato.

38 </Step>

39</Steps>

41<img src="https://mintcdn.com/claude-code/FEspvVUyRuaWjm0s/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=FEspvVUyRuaWjm0s&q=85&s=a1759b0cf4541281a9fdd8f5348228e8" alt="Diagramma del flusso di valutazione dei permessi" width="920" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

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

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

46* **Callback canUseTool:** richiedi agli utenti l'approvazione in fase di esecuzione. Vedi [Gestire approvazioni e input dell'utente](/it/agent-sdk/user-input).

48## Regole di consentimento e negazione

50`allowed_tools` e `disallowed_tools` (TypeScript: `allowedTools` / `disallowedTools`) aggiungono voci agli elenchi di regole di consentimento e negazione nel flusso di valutazione sopra. Controllano se una chiamata di strumento viene approvata, non se lo strumento è disponibile per Claude.

52| Opzione | Effetto |

53| :------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |

54| `allowed_tools=["Read", "Grep"]` | `Read` e `Grep` vengono approvati automaticamente. Gli strumenti non elencati qui esistono ancora e passano alla modalità di permesso e `canUseTool`. |

55| `disallowed_tools=["Bash"]` | `Bash` viene sempre negato. Le regole di negazione vengono controllate per prime e si mantengono in ogni modalità di permesso, inclusa `bypassPermissions`. |

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

59```typescript theme={null}

60const options = {

61 allowedTools: ["Read", "Glob", "Grep"],

62 permissionMode: "dontAsk"

63};

64```

66<Warning>

67 **`allowed_tools` non vincola `bypassPermissions`.** `allowed_tools` pre-approva solo gli strumenti che elenchi. Gli strumenti non elencati non vengono abbinati da alcuna regola di consentimento e passano alla modalità di permesso, dove `bypassPermissions` li approva. Impostare `allowed_tools=["Read"]` insieme a `permission_mode="bypassPermissions"` approva comunque ogni strumento, inclusi `Bash`, `Write` e `Edit`. Se hai bisogno di `bypassPermissions` ma vuoi bloccare strumenti specifici, usa `disallowed_tools`.

68</Warning>

70Puoi anche configurare regole di consentimento, negazione e richiesta in modo dichiarativo in `.claude/settings.json`. Queste regole vengono lette quando la fonte di impostazione `project` è abilitata, il che è il caso per le opzioni predefinite di `query()`. Se imposti `setting_sources` (TypeScript: `settingSources`) esplicitamente, includi `"project"` affinché si applichino. Vedi [Impostazioni di permesso](/it/settings#permission-settings) per la sintassi delle regole.

72## Modalità di permesso

74Le modalità di permesso forniscono un controllo globale su come Claude utilizza gli strumenti. Puoi impostare la modalità di permesso quando chiami `query()` o cambiarla dinamicamente durante le sessioni di streaming.

76### Modalità disponibili

78L'SDK supporta queste modalità di permesso:

80| Modalità | Descrizione | Comportamento dello strumento |

81| :----------------------- | :------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

82| `default` | Comportamento di permesso standard | Nessuna approvazione automatica; gli strumenti non abbinati attivano il tuo callback `canUseTool` |

83| `dontAsk` | Nega invece di richiedere | Qualsiasi cosa non pre-approvata da `allowed_tools` o regole viene negata; `canUseTool` non viene mai chiamato |

84| `acceptEdits` | Accetta automaticamente le modifiche ai file | Le modifiche ai file e le [operazioni del filesystem](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, ecc.) vengono approvate automaticamente |

85| `bypassPermissions` | Ignora tutti i controlli di permesso | Tutti gli strumenti vengono eseguiti senza richieste di permesso (usare con cautela) |

86| `plan` | Modalità di pianificazione | Gli strumenti di sola lettura vengono eseguiti; Claude analizza e pianifica senza modificare i tuoi file sorgente |

87| `auto` (solo TypeScript) | Approvazioni classificate dal modello | Un classificatore di modello approva o nega ogni chiamata di strumento. Vedi [Modalità Auto](/it/permission-modes#eliminate-prompts-with-auto-mode) per la disponibilità |

89<Warning>

90 **Eredità del subagente:** Quando il genitore utilizza `bypassPermissions`, `acceptEdits` o `auto`, tutti i subagenti ereditano quella modalità e non può essere sovrascritta per subagente. I subagenti possono avere prompt di sistema diversi e comportamento meno vincolato rispetto al tuo agente principale, quindi ereditare `bypassPermissions` concede loro accesso completo e autonomo al sistema senza alcuna richiesta di approvazione.

91</Warning>

93### Impostare la modalità di permesso

95Puoi impostare la modalità di permesso una volta all'inizio di una query, o cambiarla dinamicamente mentre la sessione è attiva.

97<Tabs>

98 <Tab title="Al momento della query">

99 Passa `permission_mode` (Python) o `permissionMode` (TypeScript) quando crei una query. Questa modalità si applica per l'intera sessione a meno che non venga modificata dinamicamente.

100

101 <CodeGroup>

102 ```python Python theme={null}

103 import asyncio

104 from claude_agent_sdk import query, ClaudeAgentOptions

105

106

107 async def main():

108 async for message in query(

109 prompt="Help me refactor this code",

110 options=ClaudeAgentOptions(

111 permission_mode="default", # Set the mode here

112 ),

113 ):

114 if hasattr(message, "result"):

115 print(message.result)

116

117

118 asyncio.run(main())

119 ```

120

121 ```typescript TypeScript theme={null}

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

123

124 async function main() {

125 for await (const message of query({

126 prompt: "Help me refactor this code",

127 options: {

128 permissionMode: "default" // Set the mode here

129 }

130 })) {

131 if ("result" in message) {

132 console.log(message.result);

133 }

134 }

135 }

136

137 main();

138 ```

139 </CodeGroup>

140 </Tab>

141

142 <Tab title="Durante lo streaming">

143 Chiama `set_permission_mode()` (Python) o `setPermissionMode()` (TypeScript) per cambiare la modalità a metà sessione. La nuova modalità ha effetto immediatamente per tutte le richieste di strumenti successive. Questo ti consente di iniziare in modo restrittivo e allentare i permessi man mano che la fiducia aumenta, ad esempio passando a `acceptEdits` dopo aver esaminato l'approccio iniziale di Claude.

144

145 <CodeGroup>

146 ```python Python theme={null}

147 import asyncio

148 from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

149

150

151 async def main():

152 async with ClaudeSDKClient(

153 options=ClaudeAgentOptions(

154 permission_mode="default", # Start in default mode

155 )

156 ) as client:

157 await client.query("Help me refactor this code")

158

159 # Change mode dynamically mid-session

160 await client.set_permission_mode("acceptEdits")

161

162 # Process messages with the new permission mode

163 async for message in client.receive_response():

164 if hasattr(message, "result"):

165 print(message.result)

166

167

168 asyncio.run(main())

169 ```

170

171 ```typescript TypeScript theme={null}

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

173

174 async function main() {

175 const q = query({

176 prompt: "Help me refactor this code",

177 options: {

178 permissionMode: "default" // Start in default mode

179 }

180 });

181

182 // Change mode dynamically mid-session

183 await q.setPermissionMode("acceptEdits");

184

185 // Process messages with the new permission mode

186 for await (const message of q) {

187 if ("result" in message) {

188 console.log(message.result);

189 }

190 }

191 }

192

193 main();

194 ```

195 </CodeGroup>

196 </Tab>

197</Tabs>

198

199### Dettagli della modalità

200

201#### Modalità accetta modifiche (`acceptEdits`)

202

203Approva automaticamente le operazioni su file in modo che Claude possa modificare il codice senza richiedere. Altri strumenti (come i comandi Bash che non sono operazioni del filesystem) richiedono comunque i permessi normali.

204

205**Operazioni approvate automaticamente:**

206

207* Modifiche ai file (strumenti Edit, Write)

208* Comandi del filesystem: `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, `sed`

209

210Entrambi si applicano solo ai percorsi all'interno della directory di lavoro o `additionalDirectories`. I percorsi al di fuori di tale ambito e le scritture su percorsi protetti richiedono comunque una richiesta.

211

212**Usare quando:** ti fidi delle modifiche di Claude e desideri un'iterazione più veloce, ad esempio durante la prototipazione o quando lavori in una directory isolata.

213

214#### Modalità non chiedere (`dontAsk`)

215

216Converte qualsiasi richiesta di permesso in una negazione. Gli strumenti pre-approvati da `allowed_tools`, regole di consentimento di `settings.json` o un hook vengono eseguiti normalmente. Tutto il resto viene negato senza chiamare `canUseTool`.

217

218**Usare quando:** desideri una superficie di strumenti fissa ed esplicita per un agente headless e preferisci una negazione definitiva rispetto a un affidamento silenzioso su `canUseTool` assente.

219

220#### Modalità ignora permessi (`bypassPermissions`)

221

222Approva automaticamente tutti gli usi degli strumenti senza richieste. Gli hook vengono comunque eseguiti e possono bloccare le operazioni se necessario.

223

224<Warning>

225 Usare con estrema cautela. Claude ha accesso completo al sistema in questa modalità. Usare solo in ambienti controllati in cui ti fidi di tutte le operazioni possibili.

226

227 `allowed_tools` non vincola questa modalità. Ogni strumento viene approvato, non solo quelli che hai elencato. Le regole di negazione (`disallowed_tools`), le regole esplicite `ask` e gli hook vengono valutati prima del controllo della modalità e possono comunque bloccare uno strumento.

228</Warning>

229

230#### Modalità piano (`plan`)

231

232Limita Claude agli strumenti di sola lettura. Claude può leggere file ed eseguire comandi shell di sola lettura per esplorare la base di codice ma non modifica i tuoi file sorgente. Claude può utilizzare `AskUserQuestion` per chiarire i requisiti prima di finalizzare il piano. Vedi [Gestire approvazioni e input dell'utente](/it/agent-sdk/user-input#handle-clarifying-questions) per gestire queste richieste.

233

234**Usare quando:** desideri che Claude proponga modifiche senza eseguirle, ad esempio durante la revisione del codice o quando hai bisogno di approvare le modifiche prima che vengano apportate.

235

236## Risorse correlate

237

238Per gli altri passaggi nel flusso di valutazione dei permessi:

239

240* [Gestire approvazioni e input dell'utente](/it/agent-sdk/user-input): richieste di approvazione interattive e domande di chiarimento

241* [Guida agli hook](/it/agent-sdk/hooks): esegui codice personalizzato nei punti chiave del ciclo di vita dell'agente

242* [Regole di permesso](/it/settings#permission-settings): regole dichiarative di consentimento/negazione in `settings.json`

agent-sdk/python.md +37 −35

Details

113#### Parametri113#### Parametri

114 114

116| :------------- | :----------------------------------------------- | :---------------------------------------------------------------------------------------------- |116| :------------- | :---------------------------------------------- | :---------------------------------------------------------------------------------------------- |

117| `name` | `str` | Identificatore univoco per lo strumento |117| `name` | `str` | Identificatore univoco per lo strumento |

118| `description` | `str` | Descrizione leggibile di cosa fa lo strumento |118| `description` | `str` | Descrizione leggibile di cosa fa lo strumento |

121 121

122#### Opzioni dello schema di input122#### Opzioni dello schema di input

123 123

269| `cwd` | `str \| None` | Directory di lavoro per la sessione |269| `cwd` | `str \| None` | Directory di lavoro per la sessione |

270| `tag` | `str \| None` | Tag della sessione impostato dall'utente (vedi [`tag_session()`](#tag-session)) |270| `tag` | `str \| None` | Tag della sessione impostato dall'utente (vedi [`tag_session()`](#tag_session)) |

272 272

273#### Esempio273#### Esempio

345 345

346Restituisce [`SDKSessionInfo`](#return-type-sdk-session-info), o `None` se la sessione non viene trovata.346Restituisce [`SDKSessionInfo`](#return-type-sdksessioninfo), o `None` se la sessione non viene trovata.

347 347

348#### Esempio348#### Esempio

349 349

381 381

382#### Esempio382#### Esempio

383 383

384Rinomina la sessione più recente in modo che sia più facile da trovare in seguito. Il nuovo titolo appare in [`SDKSessionInfo.custom_title`](#return-type-sdk-session-info) nelle letture successive.384Rinomina la sessione più recente in modo che sia più facile da trovare in seguito. Il nuovo titolo appare in [`SDKSessionInfo.custom_title`](#return-type-sdksessioninfo) nelle letture successive.

385 385

386```python theme={null}386```python theme={null}

387from claude_agent_sdk import list_sessions, rename_session387from claude_agent_sdk import list_sessions, rename_session

478| `rewind_files(user_message_id)` | Ripristina i file al loro stato al messaggio utente specificato. Richiede `enable_file_checkpointing=True`. Vedi [File checkpointing](/it/agent-sdk/file-checkpointing) |478| `rewind_files(user_message_id)` | Ripristina i file al loro stato al messaggio utente specificato. Richiede `enable_file_checkpointing=True`. Vedi [File checkpointing](/it/agent-sdk/file-checkpointing) |

479| `get_mcp_status()` | Ottieni lo stato di tutti i server MCP configurati. Restituisce [`McpStatusResponse`](#mcp-status-response) |479| `get_mcp_status()` | Ottieni lo stato di tutti i server MCP configurati. Restituisce [`McpStatusResponse`](#mcpstatusresponse) |

481| `toggle_mcp_server(server_name, enabled)` | Abilita o disabilita un server MCP a metà sessione. La disabilitazione rimuove i suoi strumenti |481| `toggle_mcp_server(server_name, enabled)` | Abilita o disabilita un server MCP a metà sessione. La disabilitazione rimuove i suoi strumenti |

482| `stop_task(task_id)` | Interrompi un'attività in background in esecuzione. Un [`TaskNotificationMessage`](#task-notification-message) con stato `"stopped"` segue nel flusso di messaggi |482| `stop_task(task_id)` | Interrompi un'attività in background in esecuzione. Un [`TaskNotificationMessage`](#tasknotificationmessage) con stato `"stopped"` segue nel flusso di messaggi |

485 485

791 effort: Literal["low", "medium", "high", "max"] | None = None791 effort: Literal["low", "medium", "high", "max"] | None = None

792 enable_file_checkpointing: bool = False792 enable_file_checkpointing: bool = False

793 session_store: SessionStore | None = None793 session_store: SessionStore | None = None

794 session_store_flush: SessionStoreFlushMode = "batched"

794```795```

795 796

797| :---------------------------- | :------------------------------------------------------------------------------------- | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |798| :---------------------------- | :------------------------------------------------------------------------------------ | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

798| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Configurazione degli strumenti. Usa `{"type": "preset", "preset": "claude_code"}` per gli strumenti predefiniti di Claude Code |799| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Configurazione degli strumenti. Usa `{"type": "preset", "preset": "claude_code"}` per gli strumenti predefiniti di Claude Code |

799| `allowed_tools` | `list[str]` | `[]` | Strumenti da approvare automaticamente senza chiedere. Questo non limita Claude a solo questi strumenti; gli strumenti non elencati ricadono in `permission_mode` e `can_use_tool`. Usa `disallowed_tools` per bloccare gli strumenti. Vedi [Autorizzazioni](/it/agent-sdk/permissions#allow-and-deny-rules) |800| `allowed_tools` | `list[str]` | `[]` | Strumenti da approvare automaticamente senza chiedere. Questo non limita Claude a solo questi strumenti; gli strumenti non elencati ricadono in `permission_mode` e `can_use_tool`. Usa `disallowed_tools` per bloccare gli strumenti. Vedi [Autorizzazioni](/it/agent-sdk/permissions#allow-and-deny-rules) |

800| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | Configurazione del prompt di sistema. Passa una stringa per un prompt personalizzato, o usa `{"type": "preset", "preset": "claude_code"}` per il prompt di sistema di Claude Code. Aggiungi `"append"` per estendere il preset |801| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | Configurazione del prompt di sistema. Passa una stringa per un prompt personalizzato, o usa `{"type": "preset", "preset": "claude_code"}` per il prompt di sistema di Claude Code. Aggiungi `"append"` per estendere il preset |

812| `output_format` | `dict[str, Any] \| None` | `None` | Formato di output per risposte strutturate (ad es. `{"type": "json_schema", "schema": {...}}`). Vedi [Output strutturati](/it/agent-sdk/structured-outputs) per i dettagli |813| `output_format` | `dict[str, Any] \| None` | `None` | Formato di output per risposte strutturate (ad es. `{"type": "json_schema", "schema": {...}}`). Vedi [Output strutturati](/it/agent-sdk/structured-outputs) per i dettagli |

814| `cwd` | `str \| Path \| None` | `None` | Directory di lavoro corrente |815| `cwd` | `str \| Path \| None` | `None` | Directory di lavoro corrente |

831| `setting_sources` | `list[SettingSource] \| None` | `None` (Impostazioni predefinite CLI: tutte le fonti) | Controlla quali impostazioni del filesystem caricare. Passa `[]` per disabilitare le impostazioni utente, progetto e locali. Le impostazioni della politica gestita vengono caricate indipendentemente. Vedi [Usa le funzionalità di Claude Code](/it/agent-sdk/claude-code-features#what-settingsources-does-not-control) |832| `setting_sources` | `list[SettingSource] \| None` | `None` (Impostazioni predefinite CLI: tutte le fonti) | Controlla quali impostazioni del filesystem caricare. Passa `[]` per disabilitare le impostazioni utente, progetto e locali. Le impostazioni della politica gestita vengono caricate indipendentemente. Vedi [Usa le funzionalità di Claude Code](/it/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

835| `session_store` | [`SessionStore`](/it/agent-sdk/session-storage#the-session-store-interface) ` \| None` | `None` | Specchia i trascritti di sessione in un backend esterno in modo che qualsiasi host possa riprenderli. Vedi [Persisti le sessioni nell'archiviazione esterna](/it/agent-sdk/session-storage) |836| `session_store` | [`SessionStore`](/it/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | Specchia i trascritti di sessione in un backend esterno in modo che qualsiasi host possa riprenderli. Vedi [Persisti le sessioni nell'archiviazione esterna](/it/agent-sdk/session-storage) |

837| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | Quando eseguire il flush delle voci di trascritto mirrorato a `session_store`. `"batched"` esegue il flush una volta per turno o quando il buffer si riempie; `"eager"` attiva un flush in background dopo ogni frame. Ignorato quando `session_store` è `None` |

836 838

837### `OutputFormat`839### `OutputFormat`

838 840

1031| `maxTurns` | No | Numero massimo di turni agentici prima che l'agente si fermi |1033| `maxTurns` | No | Numero massimo di turni agentici prima che l'agente si fermi |

1032| `background` | No | Esegui questo agente come attività in background non bloccante quando invocato |1034| `background` | No | Esegui questo agente come attività in background non bloccante quando invocato |

1033| `effort` | No | Livello di sforzo di ragionamento per questo agente. Accetta un livello denominato o un numero intero |1035| `effort` | No | Livello di sforzo di ragionamento per questo agente. Accetta un livello denominato o un numero intero |

1034| `permissionMode` | No | Modalità di autorizzazione per l'esecuzione dello strumento all'interno di questo agente. Vedi [`PermissionMode`](#permission-mode) |1036| `permissionMode` | No | Modalità di autorizzazione per l'esecuzione dello strumento all'interno di questo agente. Vedi [`PermissionMode`](#permissionmode) |

1035 1037

1036<Note>1038<Note>

1037 I nomi dei campi `AgentDefinition` usano camelCase, come `disallowedTools`, `permissionMode` e `maxTurns`. Questi nomi si mappano direttamente al formato wire condiviso con TypeScript SDK. Questo differisce da `ClaudeAgentOptions`, che usa Python snake\_case per i campi di livello superiore equivalenti come `disallowed_tools` e `permission_mode`. Poiché `AgentDefinition` è una dataclass, passare una parola chiave snake\_case genera un `TypeError` al momento della costruzione.1039 I nomi dei campi `AgentDefinition` usano camelCase, come `disallowedTools`, `permissionMode` e `maxTurns`. Questi nomi si mappano direttamente al formato wire condiviso con TypeScript SDK. Questo differisce da `ClaudeAgentOptions`, che usa Python snake\_case per i campi di livello superiore equivalenti come `disallowed_tools` e `permission_mode`. Poiché `AgentDefinition` è una dataclass, passare una parola chiave snake\_case genera un `TypeError` al momento della costruzione.

1045PermissionMode = Literal[1047PermissionMode = Literal[

1046 "default", # Standard permission behavior1048 "default", # Standard permission behavior

1047 "acceptEdits", # Auto-accept file edits1049 "acceptEdits", # Auto-accept file edits

1048 "plan", # Planning mode - no execution1050 "plan", # Planning mode - read-only tools only

1049 "dontAsk", # Deny anything not pre-approved instead of prompting1051 "dontAsk", # Deny anything not pre-approved instead of prompting

1050 "bypassPermissions", # Bypass all permission checks (use with caution)1052 "bypassPermissions", # Bypass all permission checks (use with caution)

1051]1053]

1081```1083```

1082 1084

1084| :------------ | :----------------------- | :----------------------------------------------------------- |1086| :------------ | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1086| `suggestions` | `list[PermissionUpdate]` | Suggerimenti di aggiornamento delle autorizzazioni dalla CLI |1088| `suggestions` | `list[PermissionUpdate]` | Suggerimenti di aggiornamento delle autorizzazioni dalla CLI. I prompt Bash includono un suggerimento con la destinazione `localSettings`, quindi restituirlo in `updated_permissions` scrive la regola in `.claude/settings.local.json` e persiste tra le sessioni. |

1087 1089

1088### `PermissionResult`1090### `PermissionResult`

1089 1091

1289 1291

1290### `McpServerStatusConfig`1292### `McpServerStatusConfig`

1291 1293

1292La configurazione di un server MCP come riportato da [`get_mcp_status()`](#methods). Questa è l'unione di tutte le varianti di trasporto [`McpServerConfig`](#mcp-server-config) più una variante di output-only `claudeai-proxy` per i server proxy attraverso claude.ai.1294La configurazione di un server MCP come riportato da [`get_mcp_status()`](#methods). Questa è l'unione di tutte le varianti di trasporto [`McpServerConfig`](#mcpserverconfig) più una variante di output-only `claudeai-proxy` per i server proxy attraverso claude.ai.

1293 1295

1294```python theme={null}1296```python theme={null}

1295McpServerStatusConfig = (1297McpServerStatusConfig = (

1301)1303)

1302```1304```

1303 1305

1304`McpSdkServerConfigStatus` è la forma serializzabile di [`McpSdkServerConfig`](#mcp-sdk-server-config) con solo i campi `type` (`"sdk"`) e `name` (`str`); l'`instance` in-process viene omesso. `McpClaudeAIProxyServerConfig` ha i campi `type` (`"claudeai-proxy"`), `url` (`str`), e `id` (`str`).1306`McpSdkServerConfigStatus` è la forma serializzabile di [`McpSdkServerConfig`](#mcpsdkserverconfig) con solo i campi `type` (`"sdk"`) e `name` (`str`); l'`instance` in-process viene omesso. `McpClaudeAIProxyServerConfig` ha i campi `type` (`"claudeai-proxy"`), `url` (`str`), e `id` (`str`).

1305 1307

1306### `McpStatusResponse`1308### `McpStatusResponse`

1307 1309

1314 1316

1315### `McpServerStatus`1317### `McpServerStatus`

1316 1318

1317Stato di un server MCP connesso, contenuto in [`McpStatusResponse`](#mcp-status-response).1319Stato di un server MCP connesso, contenuto in [`McpStatusResponse`](#mcpstatusresponse).

1318 1320

1319```python theme={null}1321```python theme={null}

1320class McpServerStatus(TypedDict):1322class McpServerStatus(TypedDict):

1328```1330```

1329 1331

1331| :----------- | :--------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1333| :----------- | :------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1332| `name` | `str` | Nome del server |1334| `name` | `str` | Nome del server |

1333| `status` | `str` | Uno di `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, o `"disabled"` |1335| `status` | `str` | Uno di `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, o `"disabled"` |

1334| `serverInfo` | `dict` (opzionale) | Nome e versione del server (`{"name": str, "version": str}`) |1336| `serverInfo` | `dict` (opzionale) | Nome e versione del server (`{"name": str, "version": str}`) |

1336| `config` | [`McpServerStatusConfig`](#mcp-server-status-config) (opzionale) | Configurazione del server. Stessa forma di [`McpServerConfig`](#mcp-server-config) (stdio, SSE, HTTP, o SDK), più una variante `claudeai-proxy` per i server connessi tramite claude.ai |1338| `config` | [`McpServerStatusConfig`](#mcpserverstatusconfig) (opzionale) | Configurazione del server. Stessa forma di [`McpServerConfig`](#mcpserverconfig) (stdio, SSE, HTTP, o SDK), più una variante `claudeai-proxy` per i server connessi tramite claude.ai |

1339 1341

1416```1418```

1417 1419

1419| :------------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------------------- |1421| :------------------- | :----------------------------------------------------------- | :------------------------------------------------------------------------------------------ |

1421| `model` | `str` | Modello che ha generato la risposta |1423| `model` | `str` | Modello che ha generato la risposta |

1426 1428

1427### `AssistantMessageError`1429### `AssistantMessageError`

1481| `cache_creation_input_tokens` | `int` | Token utilizzati per creare nuove voci di cache. |1483| `cache_creation_input_tokens` | `int` | Token utilizzati per creare nuove voci di cache. |

1482| `cache_read_input_tokens` | `int` | Token letti dalle voci di cache esistenti. |1484| `cache_read_input_tokens` | `int` | Token letti dalle voci di cache esistenti. |

1483 1485

1484Il dict `model_usage` mappa i nomi dei modelli all'utilizzo per modello. Le chiavi del dict interno usano camelCase perché il valore viene passato senza modifiche dal processo CLI sottostante, corrispondendo al tipo TypeScript [`ModelUsage`](/it/agent-sdk/typescript#model-usage):1486Il dict `model_usage` mappa i nomi dei modelli all'utilizzo per modello. Le chiavi del dict interno usano camelCase perché il valore viene passato senza modifiche dal processo CLI sottostante, corrispondendo al tipo TypeScript [`ModelUsage`](/it/agent-sdk/typescript#modelusage):

1485 1487

1487| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |1489| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1527```1529```

1528 1530

1530| :---------------- | :---------------------------------- | :------------------------------------ |1532| :---------------- | :-------------------------------- | :------------------------------------ |

1532| `uuid` | `str` | Identificatore di evento univoco |1534| `uuid` | `str` | Identificatore di evento univoco |

1533| `session_id` | `str` | Identificatore di sessione |1535| `session_id` | `str` | Identificatore di sessione |

1534 1536

1535### `RateLimitInfo`1537### `RateLimitInfo`

1536 1538

1537Stato del limite di velocità trasportato da [`RateLimitEvent`](#rate-limit-event).1539Stato del limite di velocità trasportato da [`RateLimitEvent`](#ratelimitevent).

1538 1540

1539```python theme={null}1541```python theme={null}

1540RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]1542RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]

1812 1814

1813Parametri:1815Parametri:

1814 1816

1815* `input`: Input hook fortemente tipizzato con unioni discriminate basate su `hook_event_name` (vedi [`HookInput`](#hook-input))1817* `input`: Input hook fortemente tipizzato con unioni discriminate basate su `hook_event_name` (vedi [`HookInput`](#hookinput))

1816* `tool_use_id`: Identificatore di utilizzo dello strumento opzionale (per hook correlati allo strumento)1818* `tool_use_id`: Identificatore di utilizzo dello strumento opzionale (per hook correlati allo strumento)

1817* `context`: Contesto hook con informazioni aggiuntive1819* `context`: Contesto hook con informazioni aggiuntive

1818 1820

1819Restituisce un [`HookJSONOutput`](#hook-json-output) che può contenere:1821Restituisce un [`HookJSONOutput`](#hookjsonoutput) che può contenere:

1820 1822

1821* `decision`: `"block"` per bloccare l'azione1823* `decision`: `"block"` per bloccare l'azione

1822* `systemMessage`: Messaggio di sistema da aggiungere al trascritto1824* `systemMessage`: Messaggio di sistema da aggiungere al trascritto

3109```3111```

3110 3112

3112| :-------------------------- | :------------------------------------------------------ | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |3114| :-------------------------- | :---------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

3115| `excludedCommands` | `list[str]` | `[]` | Comandi che sempre bypassano le restrizioni della sandbox (ad es. `["docker"]`). Questi vengono eseguiti senza sandbox automaticamente senza coinvolgimento del modello |3117| `excludedCommands` | `list[str]` | `[]` | Comandi che sempre bypassano le restrizioni della sandbox (ad es. `["docker"]`). Questi vengono eseguiti senza sandbox automaticamente senza coinvolgimento del modello |

3116| `allowUnsandboxedCommands` | `bool` | `True` | Consenti al modello di richiedere l'esecuzione di comandi al di fuori della sandbox. Quando `True`, il modello può impostare `dangerouslyDisableSandbox` nell'input dello strumento, che ricade nel [sistema di autorizzazioni](#permissions-fallback-for-unsandboxed-commands) |3118| `allowUnsandboxedCommands` | `bool` | `True` | Consenti al modello di richiedere l'esecuzione di comandi al di fuori della sandbox. Quando `True`, il modello può impostare `dangerouslyDisableSandbox` nell'input dello strumento, che ricade nel [sistema di autorizzazioni](#permissions-fallback-for-unsandboxed-commands) |

3120 3122

3121#### Utilizzo di esempio3123#### Utilizzo di esempio

agent-sdk/streaming-output.md +396 −0 created

Details

1> ## Documentation Index

2> 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.

5# Trasmettere risposte in tempo reale

7> Ricevere risposte in tempo reale dall'Agent SDK mentre il testo e le chiamate di strumenti vengono trasmessi

9Per impostazione predefinita, l'Agent SDK restituisce oggetti `AssistantMessage` completi dopo che Claude ha terminato di generare ogni risposta. Per ricevere aggiornamenti incrementali mentre il testo e le chiamate di strumenti vengono generati, abilita lo streaming di messaggi parziali impostando `include_partial_messages` (Python) o `includePartialMessages` (TypeScript) su `true` nelle tue opzioni.

11<Tip>

12 Questa pagina copre lo streaming di output (ricezione di token in tempo reale). Per le modalità di input (come invii messaggi), vedi [Inviare messaggi agli agenti](/it/agent-sdk/streaming-vs-single-mode). Puoi anche [trasmettere risposte utilizzando l'Agent SDK tramite la CLI](/it/headless).

13</Tip>

15## Abilita lo streaming di output

17Per abilitare lo streaming, imposta `include_partial_messages` (Python) o `includePartialMessages` (TypeScript) su `true` nelle tue opzioni. Questo fa sì che l'SDK restituisca messaggi `StreamEvent` contenenti eventi API grezzi mentre arrivano, oltre ai soliti `AssistantMessage` e `ResultMessage`.

19Il tuo codice deve quindi:

211. Controllare il tipo di ogni messaggio per distinguere `StreamEvent` da altri tipi di messaggio

222. Per `StreamEvent`, estrarre il campo `event` e controllare il suo `type`

233. Cercare eventi `content_block_delta` dove `delta.type` è `text_delta`, che contengono i veri frammenti di testo

25L'esempio seguente abilita lo streaming e stampa i frammenti di testo mentre arrivano. Nota i controlli di tipo annidati: prima per `StreamEvent`, poi per `content_block_delta`, poi per `text_delta`:

27<CodeGroup>

28 ```python Python theme={null}

29 from claude_agent_sdk import query, ClaudeAgentOptions

30 from claude_agent_sdk.types import StreamEvent

31 import asyncio

34 async def stream_response():

35 options = ClaudeAgentOptions(

36 include_partial_messages=True,

37 allowed_tools=["Bash", "Read"],

38 )

40 async for message in query(prompt="List the files in my project", options=options):

41 if isinstance(message, StreamEvent):

42 event = message.event

43 if event.get("type") == "content_block_delta":

44 delta = event.get("delta", {})

45 if delta.get("type") == "text_delta":

46 print(delta.get("text", ""), end="", flush=True)

49 asyncio.run(stream_response())

50 ```

52 ```typescript TypeScript theme={null}

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

55 for await (const message of query({

56 prompt: "List the files in my project",

57 options: {

58 includePartialMessages: true,

59 allowedTools: ["Bash", "Read"]

60 }

61 })) {

62 if (message.type === "stream_event") {

63 const event = message.event;

64 if (event.type === "content_block_delta") {

65 if (event.delta.type === "text_delta") {

66 process.stdout.write(event.delta.text);

67 }

68 }

69 }

70 }

71 ```

72</CodeGroup>

74## Riferimento StreamEvent

76Quando i messaggi parziali sono abilitati, ricevi eventi di streaming API Claude grezzi avvolti in un oggetto. Il tipo ha nomi diversi in ogni SDK:

78* **Python**: `StreamEvent` (importa da `claude_agent_sdk.types`)

79* **TypeScript**: `SDKPartialAssistantMessage` con `type: 'stream_event'`

81Entrambi contengono eventi API Claude grezzi, non testo accumulato. Devi estrarre e accumulare i delta di testo da solo. Ecco la struttura di ogni tipo:

83<CodeGroup>

84 ```python Python theme={null}

85 @dataclass

86 class StreamEvent:

87 uuid: str # Unique identifier for this event

88 session_id: str # Session identifier

89 event: dict[str, Any] # The raw Claude API stream event

90 parent_tool_use_id: str | None # Parent tool ID if from a subagent

91 ```

93 ```typescript TypeScript theme={null}

94 type SDKPartialAssistantMessage = {

95 type: "stream_event";

96 event: BetaRawMessageStreamEvent; // From Anthropic SDK

97 parent_tool_use_id: string | null;

98 uuid: UUID;

99 session_id: string;

100 };

101 ```

102</CodeGroup>

103

104Il campo `event` contiene l'evento di streaming grezzo dall'[API Claude](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types). I tipi di evento comuni includono:

105

106| Tipo di evento | Descrizione |

107| :-------------------- | :----------------------------------------------------------------- |

108| `message_start` | Inizio di un nuovo messaggio |

109| `content_block_start` | Inizio di un nuovo blocco di contenuto (testo o uso di strumento) |

110| `content_block_delta` | Aggiornamento incrementale al contenuto |

111| `content_block_stop` | Fine di un blocco di contenuto |

112| `message_delta` | Aggiornamenti a livello di messaggio (motivo di arresto, utilizzo) |

113| `message_stop` | Fine del messaggio |

114

115## Flusso di messaggi

116

117Con i messaggi parziali abilitati, ricevi messaggi in questo ordine:

118

119```text theme={null}

120StreamEvent (message_start)

121StreamEvent (content_block_start) - text block

122StreamEvent (content_block_delta) - text chunks...

123StreamEvent (content_block_stop)

124StreamEvent (content_block_start) - tool_use block

125StreamEvent (content_block_delta) - tool input chunks...

126StreamEvent (content_block_stop)

127StreamEvent (message_delta)

128StreamEvent (message_stop)

129AssistantMessage - complete message with all content

130... tool executes ...

131... more streaming events for next turn ...

132ResultMessage - final result

133```

134

135Senza i messaggi parziali abilitati (`include_partial_messages` in Python, `includePartialMessages` in TypeScript), ricevi tutti i tipi di messaggio tranne `StreamEvent`. I tipi comuni includono `SystemMessage` (inizializzazione della sessione), `AssistantMessage` (risposte complete), `ResultMessage` (risultato finale) e un messaggio di confine compatto che indica quando la cronologia della conversazione è stata compattata (`SDKCompactBoundaryMessage` in TypeScript; `SystemMessage` con sottotipo `"compact_boundary"` in Python).

136

137## Trasmettere risposte di testo

138

139Per visualizzare il testo mentre viene generato, cerca eventi `content_block_delta` dove `delta.type` è `text_delta`. Questi contengono i frammenti di testo incrementali. L'esempio seguente stampa ogni frammento mentre arriva:

140

141<CodeGroup>

142 ```python Python theme={null}

143 from claude_agent_sdk import query, ClaudeAgentOptions

144 from claude_agent_sdk.types import StreamEvent

145 import asyncio

146

147

148 async def stream_text():

149 options = ClaudeAgentOptions(include_partial_messages=True)

150

151 async for message in query(prompt="Explain how databases work", options=options):

152 if isinstance(message, StreamEvent):

153 event = message.event

154 if event.get("type") == "content_block_delta":

155 delta = event.get("delta", {})

156 if delta.get("type") == "text_delta":

157 # Print each text chunk as it arrives

158 print(delta.get("text", ""), end="", flush=True)

159

160 print() # Final newline

161

162

163 asyncio.run(stream_text())

164 ```

165

166 ```typescript TypeScript theme={null}

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

168

169 for await (const message of query({

170 prompt: "Explain how databases work",

171 options: { includePartialMessages: true }

172 })) {

173 if (message.type === "stream_event") {

174 const event = message.event;

175 if (event.type === "content_block_delta" && event.delta.type === "text_delta") {

176 process.stdout.write(event.delta.text);

177 }

178 }

179 }

180

181 console.log(); // Final newline

182 ```

183</CodeGroup>

184

185## Trasmettere chiamate di strumenti

186

187Le chiamate di strumenti vengono trasmesse anche in modo incrementale. Puoi tracciare quando gli strumenti iniziano, ricevere il loro input mentre viene generato e vedere quando si completano. L'esempio seguente traccia lo strumento attualmente chiamato e accumula l'input JSON mentre viene trasmesso. Utilizza tre tipi di evento:

188

189* `content_block_start`: lo strumento inizia

190* `content_block_delta` con `input_json_delta`: i frammenti di input arrivano

191* `content_block_stop`: la chiamata dello strumento è completa

192

193<CodeGroup>

194 ```python Python theme={null}

195 from claude_agent_sdk import query, ClaudeAgentOptions

196 from claude_agent_sdk.types import StreamEvent

197 import asyncio

198

199

200 async def stream_tool_calls():

201 options = ClaudeAgentOptions(

202 include_partial_messages=True,

203 allowed_tools=["Read", "Bash"],

204 )

205

206 # Track the current tool and accumulate its input JSON

207 current_tool = None

208 tool_input = ""

209

210 async for message in query(prompt="Read the README.md file", options=options):

211 if isinstance(message, StreamEvent):

212 event = message.event

213 event_type = event.get("type")

214

215 if event_type == "content_block_start":

216 # New tool call is starting

217 content_block = event.get("content_block", {})

218 if content_block.get("type") == "tool_use":

219 current_tool = content_block.get("name")

220 tool_input = ""

221 print(f"Starting tool: {current_tool}")

222

223 elif event_type == "content_block_delta":

224 delta = event.get("delta", {})

225 if delta.get("type") == "input_json_delta":

226 # Accumulate JSON input as it streams in

227 chunk = delta.get("partial_json", "")

228 tool_input += chunk

229 print(f" Input chunk: {chunk}")

230

231 elif event_type == "content_block_stop":

232 # Tool call complete - show final input

233 if current_tool:

234 print(f"Tool {current_tool} called with: {tool_input}")

235 current_tool = None

236

237

238 asyncio.run(stream_tool_calls())

239 ```

240

241 ```typescript TypeScript theme={null}

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

243

244 // Track the current tool and accumulate its input JSON

245 let currentTool: string | null = null;

246 let toolInput = "";

247

248 for await (const message of query({

249 prompt: "Read the README.md file",

250 options: {

251 includePartialMessages: true,

252 allowedTools: ["Read", "Bash"]

253 }

254 })) {

255 if (message.type === "stream_event") {

256 const event = message.event;

257

258 if (event.type === "content_block_start") {

259 // New tool call is starting

260 if (event.content_block.type === "tool_use") {

261 currentTool = event.content_block.name;

262 toolInput = "";

263 console.log(`Starting tool: ${currentTool}`);

264 }

265 } else if (event.type === "content_block_delta") {

266 if (event.delta.type === "input_json_delta") {

267 // Accumulate JSON input as it streams in

268 const chunk = event.delta.partial_json;

269 toolInput += chunk;

270 console.log(` Input chunk: ${chunk}`);

271 }

272 } else if (event.type === "content_block_stop") {

273 // Tool call complete - show final input

274 if (currentTool) {

275 console.log(`Tool ${currentTool} called with: ${toolInput}`);

276 currentTool = null;

277 }

278 }

279 }

280 }

281 ```

282</CodeGroup>

283

284## Costruire un'interfaccia utente di streaming

285

286Questo esempio combina il testo e lo streaming di strumenti in un'interfaccia utente coerente. Traccia se l'agente sta attualmente eseguendo uno strumento (utilizzando un flag `in_tool`) per mostrare indicatori di stato come `[Using Read...]` mentre gli strumenti vengono eseguiti. Il testo viene trasmesso normalmente quando non è in uno strumento e il completamento dello strumento attiva un messaggio "done". Questo modello è utile per le interfacce di chat che devono mostrare lo stato di avanzamento durante attività di agenti multi-step.

287

288<CodeGroup>

289 ```python Python theme={null}

290 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

291 from claude_agent_sdk.types import StreamEvent

292 import asyncio

293 import sys

294

295

296 async def streaming_ui():

297 options = ClaudeAgentOptions(

298 include_partial_messages=True,

299 allowed_tools=["Read", "Bash", "Grep"],

300 )

301

302 # Track whether we're currently in a tool call

303 in_tool = False

304

305 async for message in query(

306 prompt="Find all TODO comments in the codebase", options=options

307 ):

308 if isinstance(message, StreamEvent):

309 event = message.event

310 event_type = event.get("type")

311

312 if event_type == "content_block_start":

313 content_block = event.get("content_block", {})

314 if content_block.get("type") == "tool_use":

315 # Tool call is starting - show status indicator

316 tool_name = content_block.get("name")

317 print(f"\n[Using {tool_name}...]", end="", flush=True)

318 in_tool = True

319

320 elif event_type == "content_block_delta":

321 delta = event.get("delta", {})

322 # Only stream text when not executing a tool

323 if delta.get("type") == "text_delta" and not in_tool:

324 sys.stdout.write(delta.get("text", ""))

325 sys.stdout.flush()

326

327 elif event_type == "content_block_stop":

328 if in_tool:

329 # Tool call finished

330 print(" done", flush=True)

331 in_tool = False

332

333 elif isinstance(message, ResultMessage):

334 # Agent finished all work

335 print(f"\n\n--- Complete ---")

336

337

338 asyncio.run(streaming_ui())

339 ```

340

341 ```typescript TypeScript theme={null}

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

343

344 // Track whether we're currently in a tool call

345 let inTool = false;

346

347 for await (const message of query({

348 prompt: "Find all TODO comments in the codebase",

349 options: {

350 includePartialMessages: true,

351 allowedTools: ["Read", "Bash", "Grep"]

352 }

353 })) {

354 if (message.type === "stream_event") {

355 const event = message.event;

356

357 if (event.type === "content_block_start") {

358 if (event.content_block.type === "tool_use") {

359 // Tool call is starting - show status indicator

360 process.stdout.write(`\n[Using ${event.content_block.name}...]`);

361 inTool = true;

362 }

363 } else if (event.type === "content_block_delta") {

364 // Only stream text when not executing a tool

365 if (event.delta.type === "text_delta" && !inTool) {

366 process.stdout.write(event.delta.text);

367 }

368 } else if (event.type === "content_block_stop") {

369 if (inTool) {

370 // Tool call finished

371 console.log(" done");

372 inTool = false;

373 }

374 }

375 } else if (message.type === "result") {

376 // Agent finished all work

377 console.log("\n\n--- Complete ---");

378 }

379 }

380 ```

381</CodeGroup>

382

383## Limitazioni note

384

385Alcune funzionalità dell'SDK sono incompatibili con lo streaming:

386

387* **Extended thinking**: quando imposti esplicitamente `max_thinking_tokens` (Python) o `maxThinkingTokens` (TypeScript), i messaggi `StreamEvent` non vengono emessi. Riceverai solo messaggi completi dopo ogni turno. Nota che il thinking è disabilitato per impostazione predefinita nell'SDK, quindi lo streaming funziona a meno che non lo abiliti.

388* **Structured output**: il risultato JSON appare solo nel `ResultMessage.structured_output` finale, non come delta di streaming. Vedi [structured outputs](/it/agent-sdk/structured-outputs) per i dettagli.

389

390## Passaggi successivi

391

392Ora che puoi trasmettere testo e chiamate di strumenti in tempo reale, esplora questi argomenti correlati:

393

394* [Interactive vs one-shot queries](/it/agent-sdk/streaming-vs-single-mode): scegli tra le modalità di input per il tuo caso d'uso

395* [Structured outputs](/it/agent-sdk/structured-outputs): ottieni risposte JSON tipizzate dall'agente

396* [Permissions](/it/agent-sdk/permissions): controlla quali strumenti l'agente può utilizzare

agent-sdk/todo-tracking.md +189 −0 created

Details

1> ## Documentation Index

2> 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.

5# Elenchi Todo

7> Traccia e visualizza i todo utilizzando Claude Agent SDK per una gestione organizzata 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à.

11### Ciclo di vita dei Todo

13I todo seguono un ciclo di vita prevedibile:

151. **Creati** come `pending` quando le attività vengono identificate

162. **Attivati** a `in_progress` quando il lavoro inizia

173. **Completati** quando l'attività termina con successo

184. **Rimossi** quando tutte le attività in un gruppo sono completate

20### Quando vengono utilizzati i Todo

22L'SDK crea automaticamente todo per:

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

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

26* **Operazioni non banali** che traggono beneficio dal tracciamento dei progressi

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

29## Esempi

31### Monitoraggio dei cambiamenti dei Todo

33<CodeGroup>

34 ```typescript TypeScript theme={null}

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

37 for await (const message of query({

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

39 options: { maxTurns: 15 }

40 })) {

41 // Todo updates are reflected in the message stream

42 if (message.type === "assistant") {

43 for (const block of message.message.content) {

44 if (block.type === "tool_use" && block.name === "TodoWrite") {

45 const todos = block.input.todos;

47 console.log("Todo Status Update:");

48 todos.forEach((todo, index) => {

49 const status =

50 todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";

51 console.log(`${index + 1}. ${status} ${todo.content}`);

52 });

53 }

54 }

55 }

56 }

57 ```

59 ```python Python theme={null}

60 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

62 async for message in query(

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

64 options=ClaudeAgentOptions(max_turns=15),

65 ):

66 # Todo updates are reflected in the message stream

67 if isinstance(message, AssistantMessage):

68 for block in message.content:

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

70 todos = block.input["todos"]

72 print("Todo Status Update:")

73 for i, todo in enumerate(todos):

74 status = (

75 "✅"

76 if todo["status"] == "completed"

77 else "🔧"

78 if todo["status"] == "in_progress"

79 else "❌"

80 )

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

82 ```

83</CodeGroup>

85### Visualizzazione dei progressi in tempo reale

87<CodeGroup>

88 ```typescript TypeScript theme={null}

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

91 class TodoTracker {

92 private todos: any[] = [];

94 displayProgress() {

95 if (this.todos.length === 0) return;

97 const completed = this.todos.filter((t) => t.status === "completed").length;

98 const inProgress = this.todos.filter((t) => t.status === "in_progress").length;

99 const total = this.todos.length;

100

101 console.log(`\nProgress: ${completed}/${total} completed`);

102 console.log(`Currently working on: ${inProgress} task(s)\n`);

103

104 this.todos.forEach((todo, index) => {

105 const icon =

106 todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";

107 const text = todo.status === "in_progress" ? todo.activeForm : todo.content;

108 console.log(`${index + 1}. ${icon} ${text}`);

109 });

110 }

111

112 async trackQuery(prompt: string) {

113 for await (const message of query({

114 prompt,

115 options: { maxTurns: 20 }

116 })) {

117 if (message.type === "assistant") {

118 for (const block of message.message.content) {

119 if (block.type === "tool_use" && block.name === "TodoWrite") {

120 this.todos = block.input.todos;

121 this.displayProgress();

122 }

123 }

124 }

125 }

126 }

127 }

128

129 // Usage

130 const tracker = new TodoTracker();

131 await tracker.trackQuery("Build a complete authentication system with todos");

132 ```

133

134 ```python Python theme={null}

135 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

136 from typing import List, Dict

137

138

139 class TodoTracker:

140 def __init__(self):

141 self.todos: List[Dict] = []

142

143 def display_progress(self):

144 if not self.todos:

145 return

146

147 completed = len([t for t in self.todos if t["status"] == "completed"])

148 in_progress = len([t for t in self.todos if t["status"] == "in_progress"])

149 total = len(self.todos)

150

151 print(f"\nProgress: {completed}/{total} completed")

152 print(f"Currently working on: {in_progress} task(s)\n")

153

154 for i, todo in enumerate(self.todos):

155 icon = (

156 "✅"

157 if todo["status"] == "completed"

158 else "🔧"

159 if todo["status"] == "in_progress"

160 else "❌"

161 )

162 text = (

163 todo["activeForm"]

164 if todo["status"] == "in_progress"

165 else todo["content"]

166 )

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

168

169 async def track_query(self, prompt: str):

170 async for message in query(prompt=prompt, options=ClaudeAgentOptions(max_turns=20)):

171 if isinstance(message, AssistantMessage):

172 for block in message.content:

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

174 self.todos = block.input["todos"]

175 self.display_progress()

176

177

178 # Usage

179 tracker = TodoTracker()

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

181 ```

182</CodeGroup>

183

184## Documentazione correlata

185

186* [Riferimento TypeScript SDK](/it/agent-sdk/typescript)

187* [Riferimento Python SDK](/it/agent-sdk/python)

188* [Streaming vs Single Mode](/it/agent-sdk/streaming-vs-single-mode)

189* [Custom Tools](/it/agent-sdk/custom-tools)

agent-sdk/typescript.md +31 −31

Details

41#### Parametri41#### Parametri

42 42

~~44| :-------- | :---------------------------------------------------------------- | :------------------------------------------------------------------------------ |~~44| :-------- | :--------------------------------------------------------------- | :------------------------------------------------------------------------------ |

47 47

48#### Restituisce48#### Restituisce

49 49

~~50Restituisce un oggetto [`Query`](#query-object) che estende `AsyncGenerator<`[`SDKMessage`](#sdk-message)`, void>` con metodi aggiuntivi.~~50Restituisce un oggetto [`Query`](#query-object) che estende `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>` con metodi aggiuntivi.

51 51

52### `startup()`52### `startup()`

53 53

54Pre-riscalda il subprocess CLI generandolo e completando l'handshake di inizializzazione prima che un prompt sia disponibile. L'handle [`WarmQuery`](#warm-query) restituito accetta un prompt in seguito e lo scrive in un processo già pronto, quindi la prima chiamata `query()` si risolve senza pagare il costo di generazione e inizializzazione del subprocess inline.54Pre-riscalda il subprocess CLI generandolo e completando l'handshake di inizializzazione prima che un prompt sia disponibile. L'handle [`WarmQuery`](#warmquery) restituito accetta un prompt in seguito e lo scrive in un processo già pronto, quindi la prima chiamata `query()` si risolve senza pagare il costo di generazione e inizializzazione del subprocess inline.

55 55

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

57function startup(params?: {57function startup(params?: {

69 69

70#### Restituisce70#### Restituisce

71 71

~~72Restituisce una `Promise<`[`WarmQuery`](#warm-query)`>` che si risolve una volta che il subprocess è stato generato e ha completato il suo handshake di inizializzazione.~~72Restituisce una `Promise<`[`WarmQuery`](#warmquery)`>` che si risolve una volta che il subprocess è stato generato e ha completato il suo handshake di inizializzazione.

73 73

74#### Esempio74#### Esempio

75 75

104#### Parametri104#### Parametri

105 105

107| :------------ | :------------------------------------------------------------------ | :------------------------------------------------------------------------------------ |107| :------------ | :---------------------------------------------------------------- | :------------------------------------------------------------------------------------ |

112| `extras` | `{ annotations?: `[`ToolAnnotations`](#tool-annotations)` }` | Annotazioni MCP tool opzionali che forniscono suggerimenti comportamentali ai client |112| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)` }` | Annotazioni MCP tool opzionali che forniscono suggerimenti comportamentali ai client |

113 113

114#### `ToolAnnotations`114#### `ToolAnnotations`

115 115

191 191

192#### Esempio192#### Esempio

272 272

273Restituisce [`SDKSessionInfo`](#return-type-sdk-session-info), o `undefined` se la sessione non viene trovata.273Restituisce [`SDKSessionInfo`](#return-type-sdksessioninfo), o `undefined` se la sessione non viene trovata.

274 274

275### `renameSession()`275### `renameSession()`

276 276

328| `allowedTools` | `string[]` | `[]` | Tool da approvare automaticamente senza richiedere. Questo non limita Claude a solo questi tool; i tool non elencati ricadono in `permissionMode` e `canUseTool`. Usa `disallowedTools` per bloccare i tool. Vedi [Permessi](/it/agent-sdk/permissions#allow-and-deny-rules) |328| `allowedTools` | `string[]` | `[]` | Tool da approvare automaticamente senza richiedere. Questo non limita Claude a solo questi tool; i tool non elencati ricadono in `permissionMode` e `canUseTool`. Usa `disallowedTools` per bloccare i tool. Vedi [Permessi](/it/agent-sdk/permissions#allow-and-deny-rules) |

341| `extraArgs` | `Record<string, string \| null>` | `{}` | Argomenti aggiuntivi |341| `extraArgs` | `Record<string, string \| null>` | `{}` | Argomenti aggiuntivi |

344| `hooks` | `Partial<Record<`[`HookEvent`](#hook-event)`, `[`HookCallbackMatcher`](#hook-callback-matcher)`[]>>` | `{}` | Callback hook per gli eventi |344| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Callback hook per gli eventi |

346| `maxBudgetUsd` | `number` | `undefined` | Interrompi la query quando la stima del costo lato client raggiunge questo valore in USD. Confrontato con la stessa stima di `total_cost_usd`; vedi [Traccia costo e utilizzo](/it/agent-sdk/cost-tracking) per le avvertenze di accuratezza |346| `maxBudgetUsd` | `number` | `undefined` | Interrompi la query quando la stima del costo lato client raggiunge questo valore in USD. Confrontato con la stessa stima di `total_cost_usd`; vedi [Traccia costo e utilizzo](/it/agent-sdk/cost-tracking) per le avvertenze di accuratezza |

349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcp-server-config)>` | `{}` | Configurazioni del server MCP |349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurazioni del server MCP |

351| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Definisci il formato di output per i risultati dell'agente. Vedi [Output strutturati](/it/agent-sdk/structured-outputs) per i dettagli |351| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Definisci il formato di output per i risultati dell'agente. Vedi [Output strutturati](/it/agent-sdk/structured-outputs) per i dettagli |

352| `pathToClaudeCodeExecutable` | `string` | Auto-risolto dal binario nativo raggruppato | Percorso all'eseguibile Claude Code. Necessario solo se le dipendenze opzionali sono state saltate durante l'installazione o la tua piattaforma non è nel set supportato |352| `pathToClaudeCodeExecutable` | `string` | Auto-risolto dal binario nativo raggruppato | Percorso all'eseguibile Claude Code. Necessario solo se le dipendenze opzionali sono state saltate durante l'installazione o la tua piattaforma non è nel set supportato |

362| `sessionStore` | [`SessionStore`](/it/agent-sdk/session-storage#the-session-store-interface) | `undefined` | Specchia i trascritti della sessione in un backend esterno in modo che qualsiasi host possa riprenderli. Vedi [Persisti le sessioni nell'archiviazione esterna](/it/agent-sdk/session-storage) |362| `sessionStore` | [`SessionStore`](/it/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Specchia i trascritti della sessione in un backend esterno in modo che qualsiasi host possa riprenderli. Vedi [Persisti le sessioni nell'archiviazione esterna](/it/agent-sdk/session-storage) |

363| `settingSources` | [`SettingSource`](#setting-source)`[]` | Impostazioni predefinite CLI (tutte le fonti) | Controlla quali impostazioni del filesystem caricare. Passa `[]` per disabilitare le impostazioni utente, progetto e locali. Le impostazioni della politica gestita vengono caricate indipendentemente. Vedi [Usa le funzioni Claude Code](/it/agent-sdk/claude-code-features#what-settingsources-does-not-control) |363| `settingSources` | [`SettingSource`](#settingsource)`[]` | Impostazioni predefinite CLI (tutte le fonti) | Controlla quali impostazioni del filesystem caricare. Passa `[]` per disabilitare le impostazioni utente, progetto e locali. Le impostazioni della politica gestita vengono caricate indipendentemente. Vedi [Usa le funzioni Claude Code](/it/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

364| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Funzione personalizzata per generare il processo Claude Code. Usa per eseguire Claude Code in VM, container o ambienti remoti |364| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Funzione personalizzata per generare il processo Claude Code. Usa per eseguire Claude Code in VM, container o ambienti remoti |

367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (prompt minimo) | Configurazione del prompt di sistema. Passa una stringa per un prompt personalizzato, o `{ type: 'preset', preset: 'claude_code' }` per usare il prompt di sistema di Claude Code. Quando si usa la forma dell'oggetto preset, aggiungi `append` per estenderlo con istruzioni aggiuntive, e imposta `excludeDynamicSections: true` per spostare il contesto per sessione nel primo messaggio utente per un [migliore riutilizzo della cache dei prompt tra le macchine](/it/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (prompt minimo) | Configurazione del prompt di sistema. Passa una stringa per un prompt personalizzato, o `{ type: 'preset', preset: 'claude_code' }` per usare il prompt di sistema di Claude Code. Quando si usa la forma dell'oggetto preset, aggiungi `append` per estenderlo con istruzioni aggiuntive, e imposta `excludeDynamicSections: true` per spostare il contesto per sessione nel primo messaggio utente per un [migliore riutilizzo della cache dei prompt tra le macchine](/it/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

368| `thinking` | [`ThinkingConfig`](#thinking-config) | `{ type: 'adaptive' }` per i modelli supportati | Controlla il comportamento di pensiero/ragionamento di Claude. Vedi [`ThinkingConfig`](#thinking-config) per le opzioni |368| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` per i modelli supportati | Controlla il comportamento di pensiero/ragionamento di Claude. Vedi [`ThinkingConfig`](#thinkingconfig) per le opzioni |

370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configurazione dei tool. Passa un array di nomi di tool o usa il preset per ottenere i tool predefiniti di Claude Code |370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configurazione dei tool. Passa un array di nomi di tool o usa il preset per ottenere i tool predefiniti di Claude Code |

371 371

372### Oggetto `Query`372### Oggetto `Query`

410| `initializationResult()` | Restituisce il risultato di inizializzazione completo inclusi i comandi supportati, i modelli, le informazioni dell'account e la configurazione dello stile di output |410| `initializationResult()` | Restituisce il risultato di inizializzazione completo inclusi i comandi supportati, i modelli, le informazioni dell'account e la configurazione dello stile di output |

493| `background` | No | Esegui questo agente come un'attività di background non bloccante quando invocato |493| `background` | No | Esegui questo agente come un'attività di background non bloccante quando invocato |

494| `memory` | No | Fonte di memoria per questo agente: `'user'`, `'project'`, o `'local'` |494| `memory` | No | Fonte di memoria per questo agente: `'user'`, `'project'`, o `'local'` |

495| `effort` | No | Livello di sforzo di ragionamento per questo agente. Accetta un livello denominato o un numero intero |495| `effort` | No | Livello di sforzo di ragionamento per questo agente. Accetta un livello denominato o un numero intero |

496| `permissionMode` | No | Modalità di permesso per l'esecuzione dei tool all'interno di questo agente. Vedi [`PermissionMode`](#permission-mode) |496| `permissionMode` | No | Modalità di permesso per l'esecuzione dei tool all'interno di questo agente. Vedi [`PermissionMode`](#permissionmode) |

497| `criticalSystemReminder_EXPERIMENTAL` | No | Sperimentale: Promemoria critico aggiunto al prompt di sistema |497| `criticalSystemReminder_EXPERIMENTAL` | No | Sperimentale: Promemoria critico aggiunto al prompt di sistema |

498 498

499### `AgentMcpServerSpec`499### `AgentMcpServerSpec`

626 | "default" // Comportamento di permesso standard626 | "default" // Comportamento di permesso standard

627 | "acceptEdits" // Auto-accetta le modifiche ai file627 | "acceptEdits" // Auto-accetta le modifiche ai file

628 | "bypassPermissions" // Bypass di tutti i controlli di permesso628 | "bypassPermissions" // Bypass di tutti i controlli di permesso

629 | "plan" // Modalità di pianificazione - nessuna esecuzione629 | "plan" // Modalità di pianificazione - solo tool di sola lettura

630 | "dontAsk" // Non richiedere i permessi, nega se non pre-approvato630 | "dontAsk" // Non richiedere i permessi, nega se non pre-approvato

631 | "auto"; // Usa un classificatore di modello per approvare o negare ogni chiamata di tool631 | "auto"; // Usa un classificatore di modello per approvare o negare ogni chiamata di tool

632```632```

651```651```

652 652

654| :--------------- | :------------------------------------------- | :----------------------------------------------------------------------------------------------------- |654| :--------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

656| `suggestions` | [`PermissionUpdate`](#permission-update)`[]` | Aggiornamenti di permesso suggeriti in modo che l'utente non venga richiesto di nuovo per questo tool |656| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | Aggiornamenti di permesso suggeriti in modo che l'utente non venga richiesto di nuovo per questo tool. I prompt Bash includono un suggerimento con la destinazione [`localSettings`](#permissionupdatedestination), quindi restituirlo in `updatedPermissions` scrive la regola in `.claude/settings.local.json` e persiste tra le sessioni. |

2379 | McpClaudeAIProxyServerConfig;2379 | McpClaudeAIProxyServerConfig;

2380```2380```

2381 2381

2382Vedi [`McpServerConfig`](#mcp-server-config) per i dettagli su ogni tipo di trasporto.2382Vedi [`McpServerConfig`](#mcpserverconfig) per i dettagli su ogni tipo di trasporto.

2383 2383

2384### `AccountInfo`2384### `AccountInfo`

2385 2385

2825```2825```

2826 2826

2828| :-------------------------- | :------------------------------------------------------ | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2828| :-------------------------- | :---------------------------------------------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2831| `excludedCommands` | `string[]` | `[]` | Comandi che sempre bypassano le restrizioni della sandbox (ad esempio, `['docker']`). Questi vengono eseguiti senza sandbox automaticamente senza coinvolgimento del modello |2831| `excludedCommands` | `string[]` | `[]` | Comandi che sempre bypassano le restrizioni della sandbox (ad esempio, `['docker']`). Questi vengono eseguiti senza sandbox automaticamente senza coinvolgimento del modello |

2832| `allowUnsandboxedCommands` | `boolean` | `true` | Consenti al modello di richiedere l'esecuzione di comandi al di fuori della sandbox. Quando `true`, il modello può impostare `dangerouslyDisableSandbox` nell'input del tool, che ricade nel [sistema di permessi](#permissions-fallback-for-unsandboxed-commands) |2832| `allowUnsandboxedCommands` | `boolean` | `true` | Consenti al modello di richiedere l'esecuzione di comandi al di fuori della sandbox. Quando `true`, il modello può impostare `dangerouslyDisableSandbox` nell'input del tool, che ricade nel [sistema di permessi](#permissions-fallback-for-unsandboxed-commands) |

2835| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Mappa delle categorie di violazione ai pattern da ignorare (ad esempio, `{ file: ['/tmp/*'], network: ['localhost'] }`) |2835| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Mappa delle categorie di violazione ai pattern da ignorare (ad esempio, `{ file: ['/tmp/*'], network: ['localhost'] }`) |

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

data-usage.md +1 −1

Details

67 67

68Il diagramma sottostante mostra come Claude Code si connette ai servizi esterni durante l'installazione e il funzionamento normale. Le linee continue indicano connessioni richieste, mentre le linee tratteggiate rappresentano flussi di dati facoltativi o avviati dall'utente.68Il diagramma sottostante mostra come Claude Code si connette ai servizi esterni durante l'installazione e il funzionamento normale. Le linee continue indicano connessioni richieste, mentre le linee tratteggiate rappresentano flussi di dati facoltativi o avviati dall'utente.

69 69

70<img src="https://mintcdn.com/claude-code/YcBW2H7CArGcduPb/images/claude-code-data-flow.svg?fit=max&auto=format&n=YcBW2H7CArGcduPb&q=85&s=b600a89f84fc86f9ff7be00a466c0635" alt="Diagramma che mostra le connessioni esterne di Claude Code: install/update si connette al server di distribuzione e le richieste dell'utente si connettono ai servizi Anthropic inclusi Console auth, public-api e facoltativamente Statsig, Sentry e bug reporting" width="720" height="520" data-path="images/claude-code-data-flow.svg" />70<img src="https://mintcdn.com/claude-code/RcOyXc06Ja8cuvMZ/images/claude-code-data-flow.svg?fit=max&auto=format&n=RcOyXc06Ja8cuvMZ&q=85&s=b5be40abf333defe984993af89546c19" alt="Diagramma che mostra le connessioni esterne di Claude Code: install/update si connette al server di distribuzione e le richieste dell'utente si connettono ai servizi Anthropic inclusi Console auth, public-api e facoltativamente Statsig, Sentry e bug reporting" width="720" height="520" data-path="images/claude-code-data-flow.svg" />

71 71

72Claude Code viene eseguito localmente. Per interagire con l'LLM, Claude Code invia dati sulla rete. Questi dati includono tutti i prompt dell'utente e gli output del modello, crittografati in transito tramite TLS 1.2+. Claude Code è compatibile con la maggior parte dei VPN e dei proxy LLM più diffusi.72Claude Code viene eseguito localmente. Per interagire con l'LLM, Claude Code invia dati sulla rete. Questi dati includono tutti i prompt dell'utente e gli output del modello, crittografati in transito tramite TLS 1.2+. Claude Code è compatibile con la maggior parte dei VPN e dei proxy LLM più diffusi.

73 73

desktop.md +5 −3

Details

282 282

283### Lavora in parallelo con le sessioni283### Lavora in parallelo con le sessioni

284 284

285Fai clic su **+ New session** nella barra laterale, o premi **Cmd+N** su macOS o **Ctrl+N** su Windows, per lavorare su più compiti in parallelo. Premi **Ctrl+Tab** e **Ctrl+Shift+Tab** per scorrere le sessioni nella barra laterale. Per i repository Git, ogni sessione ottiene la sua copia isolata del tuo progetto usando [Git worktrees](/it/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), in modo che le modifiche in una sessione non influiscano su altre sessioni fino a quando non le esegui il commit.285Fai clic su **+ New session** nella barra laterale, o premi **Cmd+N** su macOS o **Ctrl+N** su Windows, per lavorare su più compiti in parallelo. Premi **Ctrl+Tab** e **Ctrl+Shift+Tab** per scorrere le sessioni nella barra laterale. Per i repository Git, ogni sessione ottiene la sua copia isolata del tuo progetto usando [Git worktrees](/it/worktrees), in modo che le modifiche in una sessione non influiscano su altre sessioni fino a quando non le esegui il commit.

286

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

286 288

287I worktree sono archiviati in `<project-root>/.claude/worktrees/` per impostazione predefinita. Puoi cambiare questo in una directory personalizzata in Impostazioni → Claude Code sotto "Worktree location". Puoi anche impostare un prefisso di ramo che viene anteposto a ogni nome di ramo worktree, il che è utile per mantenere organizzati i rami creati da Claude. Per rimuovere un worktree quando hai finito, passa il mouse sulla sessione nella barra laterale e fai clic sull'icona di archivio. Per avere sessioni che si archiviano automaticamente quando il loro pull request si unisce o si chiude, attiva **Auto-archive after PR merge or close** in Impostazioni → Claude Code. Auto-archive si applica solo alle sessioni locali che hanno finito di funzionare.289I worktree sono archiviati in `<project-root>/.claude/worktrees/` per impostazione predefinita. Puoi cambiare questo in una directory personalizzata in Impostazioni → Claude Code sotto "Worktree location". Puoi anche impostare un prefisso di ramo che viene anteposto a ogni nome di ramo worktree, il che è utile per mantenere organizzati i rami creati da Claude. Per rimuovere un worktree quando hai finito, passa il mouse sulla sessione nella barra laterale e fai clic sull'icona di archivio. Per avere sessioni che si archiviano automaticamente quando il loro pull request si unisce o si chiude, attiva **Auto-archive after PR merge or close** in Impostazioni → Claude Code. Auto-archive si applica solo alle sessioni locali che hanno finito di funzionare.

288 290

289Per includere file gitignored come `.env` nei nuovi worktree, crea un [file `.worktreeinclude`](/it/common-workflows#copy-gitignored-files-to-worktrees) nella radice del tuo progetto.291Per includere file gitignored come `.env` nei nuovi worktree, crea un [file `.worktreeinclude`](/it/worktrees#copy-gitignored-files-into-worktrees) nella radice del tuo progetto.

290 292

291<Note>293<Note>

292 L'isolamento della sessione richiede [Git](https://git-scm.com/downloads). La maggior parte dei Mac include Git per impostazione predefinita. Esegui `git --version` in Terminal per verificare. Su Windows, Git è richiesto affinché la scheda Code funzioni: [scarica Git per Windows](https://git-scm.com/downloads/win), installalo e riavvia l'app. Se riscontri errori Git, chiedi a Claude nella scheda [Cowork](https://claude.com/product/cowork) di aiutarti a risolvere i problemi della tua configurazione.294 L'isolamento della sessione richiede [Git](https://git-scm.com/downloads). La maggior parte dei Mac include Git per impostazione predefinita. Esegui `git --version` in Terminal per verificare. Su Windows, Git è richiesto affinché la scheda Code funzioni: [scarica Git per Windows](https://git-scm.com/downloads/win), installalo e riavvia l'app. Se riscontri errori Git, chiedi a Claude nella scheda [Cowork](https://claude.com/product/cowork) di aiutarti a risolvere i problemi della tua configurazione.

516 518

517Per impostare variabili di ambiente per le sessioni locali e i server di sviluppo su qualsiasi piattaforma, apri il menu a discesa dell'ambiente nella casella del prompt, passa il mouse su **Local** e fai clic sull'icona dell'ingranaggio per aprire l'editor di ambiente locale. Le variabili che salvi qui vengono archiviate crittografate sulla tua macchina e si applicano a ogni sessione locale e server di anteprima che avvii. Puoi anche aggiungere variabili alla chiave `env` nel tuo file `~/.claude/settings.json`, anche se queste raggiungono solo le sessioni Claude e non i server di sviluppo. Vedi [variabili di ambiente](/it/env-vars) per l'elenco completo delle variabili supportate.519Per impostare variabili di ambiente per le sessioni locali e i server di sviluppo su qualsiasi piattaforma, apri il menu a discesa dell'ambiente nella casella del prompt, passa il mouse su **Local** e fai clic sull'icona dell'ingranaggio per aprire l'editor di ambiente locale. Le variabili che salvi qui vengono archiviate crittografate sulla tua macchina e si applicano a ogni sessione locale e server di anteprima che avvii. Puoi anche aggiungere variabili alla chiave `env` nel tuo file `~/.claude/settings.json`, anche se queste raggiungono solo le sessioni Claude e non i server di sviluppo. Vedi [variabili di ambiente](/it/env-vars) per l'elenco completo delle variabili supportate.

518 520

519[Extended thinking](/it/common-workflows#use-extended-thinking-thinking-mode) è abilitato per impostazione predefinita, il che migliora le prestazioni su compiti di ragionamento complesso ma utilizza token aggiuntivi. Per disabilitare completamente il thinking, imposta `MAX_THINKING_TOKENS` a `0` nell'editor di ambiente locale. Su modelli con [ragionamento adattivo](/it/model-config#adjust-effort-level), qualsiasi altro valore `MAX_THINKING_TOKENS` viene ignorato perché il ragionamento adattivo controlla la profondità del thinking. Su Opus 4.6 e Sonnet 4.6, imposta `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` a `1` per usare un budget di thinking fisso; Opus 4.7 usa sempre il ragionamento adattivo e non ha una modalità di budget fisso.521[Extended thinking](/it/model-config#extended-thinking) è abilitato per impostazione predefinita, il che migliora le prestazioni su compiti di ragionamento complesso ma utilizza token aggiuntivi. Per disabilitare completamente il thinking, imposta `MAX_THINKING_TOKENS` a `0` nell'editor di ambiente locale. Su modelli con [ragionamento adattivo](/it/model-config#adjust-effort-level), qualsiasi altro valore `MAX_THINKING_TOKENS` viene ignorato perché il ragionamento adattivo controlla la profondità del thinking. Su Opus 4.6 e Sonnet 4.6, imposta `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` a `1` per usare un budget di thinking fisso; Opus 4.7 usa sempre il ragionamento adattivo e non ha una modalità di budget fisso.

520 522

521### Remote sessions523### Remote sessions

522 524

features-overview.md +51 −14

Details

12 Per informazioni su come funziona il ciclo agentico principale, consultate [How Claude Code works](/it/how-claude-code-works).12 Per informazioni su come funziona il ciclo agentico principale, consultate [How Claude Code works](/it/how-claude-code-works).

13</Note>13</Note>

14 14

~~15**Siete nuovi a Claude Code?** Iniziate con [CLAUDE.md](/it/memory) per le convenzioni del progetto. Aggiungete altre estensioni secondo le vostre necessità.~~15**Siete nuovi a Claude Code?** Iniziate con [CLAUDE.md](/it/memory) per le convenzioni del progetto, quindi aggiungete altre estensioni [quando emergono trigger specifici](#build-your-setup-over-time).

16 16

17## Panoramica17## Panoramica

18 18

23* **[MCP](/it/mcp)** collega Claude a servizi e strumenti esterni23* **[MCP](/it/mcp)** collega Claude a servizi e strumenti esterni

24* **[Subagents](/it/sub-agents)** eseguono i loro propri cicli in contesto isolato, restituendo riassunti24* **[Subagents](/it/sub-agents)** eseguono i loro propri cicli in contesto isolato, restituendo riassunti

25* **[Agent teams](/it/agent-teams)** coordinano più sessioni indipendenti con compiti condivisi e messaggistica peer-to-peer25* **[Agent teams](/it/agent-teams)** coordinano più sessioni indipendenti con compiti condivisi e messaggistica peer-to-peer

~~26* **[Hooks](/it/hooks)** vengono eseguiti completamente al di fuori del ciclo come script deterministici~~26* **[Hooks](/it/hooks-guide)** si attivano su eventi del ciclo di vita e possono eseguire uno script, una richiesta HTTP, un prompt o un subagent

27* **[Plugins](/it/plugins)** e **[marketplaces](/it/plugin-marketplaces)** confezionano e distribuiscono queste funzionalità27* **[Plugins](/it/plugins)** e **[marketplaces](/it/plugin-marketplaces)** confezionano e distribuiscono queste funzionalità

28 28

29[Skills](/it/skills) sono l'estensione più flessibile. Una skill è un file markdown contenente conoscenze, flussi di lavoro o istruzioni. Potete invocare skills con un comando come `/deploy`, oppure Claude può caricarle automaticamente quando rilevante. Le skills possono essere eseguite nella vostra conversazione attuale o in un contesto isolato tramite subagents.29[Skills](/it/skills) sono l'estensione più flessibile. Una skill è un file markdown contenente conoscenze, flussi di lavoro o istruzioni. Potete invocare skills con un comando come `/deploy`, oppure Claude può caricarle automaticamente quando rilevante. Le skills possono essere eseguite nella vostra conversazione attuale o in un contesto isolato tramite subagents.

40| **[Agent teams](/it/agent-teams)** | Coordinare più sessioni Claude Code indipendenti | Ricerca parallela, sviluppo di nuove funzionalità, debug con ipotesi concorrenti | Generare revisori per controllare sicurezza, prestazioni e test simultaneamente |40| **[Agent teams](/it/agent-teams)** | Coordinare più sessioni Claude Code indipendenti | Ricerca parallela, sviluppo di nuove funzionalità, debug con ipotesi concorrenti | Generare revisori per controllare sicurezza, prestazioni e test simultaneamente |

41| **MCP** | Collegamento a servizi esterni | Dati o azioni esterne | Interrogare il vostro database, inviare a Slack, controllare un browser |41| **MCP** | Collegamento a servizi esterni | Dati o azioni esterne | Interrogare il vostro database, inviare a Slack, controllare un browser |

43 43

44**[Plugins](/it/plugins)** sono il livello di confezionamento. Un plugin raggruppa skills, hooks, subagents e server MCP in una singola unità installabile. Le skills dei plugin hanno uno spazio dei nomi (come `/my-plugin:review`) in modo che più plugin possano coesistere. Utilizzate i plugin quando desiderate riutilizzare la stessa configurazione su più repository o distribuire ad altri tramite un **[marketplace](/it/plugin-marketplaces)**.44**[Plugins](/it/plugins)** sono il livello di confezionamento. Un plugin raggruppa skills, hooks, subagents e server MCP in una singola unità installabile. Le skills dei plugin hanno uno spazio dei nomi (come `/my-plugin:review`) in modo che più plugin possano coesistere. Utilizzate i plugin quando desiderate riutilizzare la stessa configurazione su più repository o distribuire ad altri tramite un **[marketplace](/it/plugin-marketplaces)**.

45 45

46### Costruite la vostra configurazione nel tempo

48Non è necessario configurare tutto in anticipo. Ogni funzionalità ha un trigger riconoscibile, e la maggior parte dei team le aggiunge approssimativamente in questo ordine:

50| Trigger | Aggiungete |

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

52| Claude sbaglia una convenzione o un comando due volte | Aggiungetelo a [CLAUDE.md](/it/memory) |

53| Continuate a digitare lo stesso prompt per avviare un compito | Salvatelo come [skill](/it/skills) invocabile dall'utente |

54| Incollate lo stesso playbook o procedura multi-step in chat per la terza volta | Catturatelo come [skill](/it/skills) |

55| Continuate a copiare dati da una scheda del browser che Claude non può vedere | Collegate quel sistema come [server MCP](/it/mcp) |

56| Un compito secondario inonda la vostra conversazione con output che non consulterete di nuovo | Indirizzatelo attraverso un [subagent](/it/sub-agents) |

57| Desiderate che qualcosa accada ogni volta senza chiedere | Scrivete un [hook](/it/hooks-guide) |

58| Un secondo repository ha bisogno della stessa configurazione | Confezionatelo come [plugin](/it/plugins) |

60Gli stessi trigger vi dicono quando aggiornare ciò che avete già. Un errore ripetuto o un commento di revisione ricorrente è una modifica di CLAUDE.md, non una correzione una tantum in chat. Un flusso di lavoro che continuate a modificare manualmente è una skill che ha bisogno di un'altra revisione.

46### Confrontate funzionalità simili62### Confrontate funzionalità simili

47 63

48Alcune funzionalità possono sembrare simili. Ecco come distinguerle.64Alcune funzionalità possono sembrare simili. Ecco come distinguerle.

55 * **Subagents** sono worker isolati che vengono eseguiti separatamente dalla vostra conversazione principale71 * **Subagents** sono worker isolati che vengono eseguiti separatamente dalla vostra conversazione principale

56 72

~~58 | ------------------------ | -------------------------------------------------------- | ----------------------------------------------------------------------------------- |~~74 | ------------------------------------------------------------ | -------------------------------------------------------- | ----------------------------------------------------------------------------------- |

77 | **Impatto della [finestra di contesto](/it/context-window)** | Si aggiunge alla vostra finestra principale | Utilizza una finestra separata con i suoi token di input e output |

62 79

63 **Le skills possono essere di riferimento o di azione.** Le skills di riferimento forniscono conoscenze che Claude utilizza durante la vostra sessione (come la vostra guida di stile API). Le skills di azione dicono a Claude di fare qualcosa di specifico (come `/deploy` che esegue il vostro flusso di lavoro di distribuzione).80 **Le skills possono essere di riferimento o di azione.** Le skills di riferimento forniscono conoscenze che Claude utilizza durante la vostra sessione (come la vostra guida di stile API). Le skills di azione dicono a Claude di fare qualcosa di specifico (come `/deploy` che esegue il vostro flusso di lavoro di distribuzione).

142 159

143 Esempio: Un server MCP collega Claude al vostro database. Una skill insegna a Claude il vostro modello di dati, i pattern di query comuni e quali tabelle utilizzare per diversi compiti.160 Esempio: Un server MCP collega Claude al vostro database. Una skill insegna a Claude il vostro modello di dati, i pattern di query comuni e quali tabelle utilizzare per diversi compiti.

144 </Tab>161 </Tab>

162

163 <Tab title="Hook vs Skill">

164 Un hook si attiva su un evento del ciclo di vita; una skill viene caricata nel contesto affinché Claude la applichi.

165

166 | Aspetto | Hook | Skill |

167 | ---------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |

168 | **Viene eseguito** | Un comando shell, una richiesta HTTP, un prompt LLM o un subagent | Istruzioni che Claude legge e segue |

169 | **Attivato da** | [Eventi del ciclo di vita](/it/hooks#hook-events) come `PostToolUse` o `SessionStart` | Voi digitate `/<name>`, o Claude abbina la descrizione al vostro compito |

170 | **Determinismo** | Si attiva sempre sul suo evento; il trigger è garantito | Claude interpreta le istruzioni; il risultato può variare |

171 | **Costo del contesto** | Zero a meno che l'hook non restituisca output | La descrizione si carica ogni sessione; il contenuto completo si carica quando utilizzato |

172 | **Migliore per** | Linting dopo le modifiche, blocco di comandi non sicuri, logging, notifiche | Flussi di lavoro che richiedono ragionamento, materiale di riferimento, compiti multi-step |

173

174 **Utilizzate un hook** quando l'azione deve accadere nello stesso modo ogni volta e non ha bisogno che Claude pensi. Ad esempio: formattazione al salvataggio, rifiuto di `rm -rf /`, invio di un messaggio Slack quando una sessione termina.

175

176 **Utilizzate una skill** quando Claude dovrebbe decidere come applicare i passaggi, o quando il contenuto è conoscenza piuttosto che uno script. Ad esempio: una checklist `/release`, la vostra guida di stile API, un playbook di debug.

177

178 **Mettete i guardrail negli hooks.** Un'istruzione come "non modificare mai `.env`" in CLAUDE.md o una skill è una richiesta, non una garanzia. Un hook `PreToolUse` che blocca la modifica è un'applicazione. Se una regola deve valere ogni volta, fatene un hook piuttosto che un'istruzione di prompt.

179

180 **L'output dell'hook entra nel contesto.** Un hook `PostToolUse` che esegue il vostro linter alimenta i risultati come testo che Claude legge; una skill `/fix-lint` dice a Claude come risolverli.

181 </Tab>

145</Tabs>182</Tabs>

146 183

147### Comprendete come le funzionalità si stratificano184### Comprendete come le funzionalità si stratificano

151* **I file CLAUDE.md** sono additivi: tutti i livelli contribuiscono contenuti al contesto di Claude simultaneamente. I file dalla vostra directory di lavoro e sopra si caricano all'avvio; le sottodirectory si caricano mentre lavorate in esse. Quando le istruzioni entrano in conflitto, Claude usa il giudizio per riconciliarle, con istruzioni più specifiche che tipicamente hanno la precedenza. Consultate [come i file CLAUDE.md si caricano](/it/memory#how-claudemd-files-load).188* **I file CLAUDE.md** sono additivi: tutti i livelli contribuiscono contenuti al contesto di Claude simultaneamente. I file dalla vostra directory di lavoro e sopra si caricano all'avvio; le sottodirectory si caricano mentre lavorate in esse. Quando le istruzioni entrano in conflitto, Claude usa il giudizio per riconciliarle, con istruzioni più specifiche che tipicamente hanno la precedenza. Consultate [come i file CLAUDE.md si caricano](/it/memory#how-claudemd-files-load).

152* **Skills e subagents** si sovrascrivono per nome: quando lo stesso nome esiste a più livelli, una definizione vince in base alla priorità (gestito > utente > progetto per skills; gestito > flag CLI > progetto > utente > plugin per subagents). Le skills dei plugin sono [con spazio dei nomi](/it/plugins#add-skills-to-your-plugin) per evitare conflitti. Consultate [scoperta delle skills](/it/skills#where-skills-live) e [ambito del subagent](/it/sub-agents#choose-the-subagent-scope).189* **Skills e subagents** si sovrascrivono per nome: quando lo stesso nome esiste a più livelli, una definizione vince in base alla priorità (gestito > utente > progetto per skills; gestito > flag CLI > progetto > utente > plugin per subagents). Le skills dei plugin sono [con spazio dei nomi](/it/plugins#add-skills-to-your-plugin) per evitare conflitti. Consultate [scoperta delle skills](/it/skills#where-skills-live) e [ambito del subagent](/it/sub-agents#choose-the-subagent-scope).

153* **I server MCP** si sovrascrivono per nome: locale > progetto > utente. Consultate [ambito MCP](/it/mcp#scope-hierarchy-and-precedence).190* **I server MCP** si sovrascrivono per nome: locale > progetto > utente. Consultate [ambito MCP](/it/mcp#scope-hierarchy-and-precedence).

154* **Hooks** si uniscono: tutti gli hooks registrati si attivano per i loro eventi corrispondenti indipendentemente dalla fonte. Consultate [hooks](/it/hooks).191* **Hooks** si uniscono: tutti gli hooks registrati si attivano per i loro eventi corrispondenti indipendentemente dalla fonte. Consultate [hooks](/it/hooks-guide).

155 192

156### Combinate le funzionalità193### Combinate le funzionalità

157 194

168 205

169## Comprendete i costi del contesto206## Comprendete i costi del contesto

170 207

171Ogni funzionalità che aggiungete consuma parte del contesto di Claude. Troppo può riempire la vostra finestra di contesto, ma può anche aggiungere rumore che rende Claude meno efficace; le skills potrebbero non attivarsi correttamente, o Claude potrebbe perdere traccia delle vostre convenzioni. Comprendere questi compromessi vi aiuta a costruire una configurazione efficace.208Ogni funzionalità che aggiungete consuma parte del contesto di Claude. Troppo può riempire la vostra finestra di contesto, ma può anche aggiungere rumore che rende Claude meno efficace; le skills potrebbero non attivarsi correttamente, o Claude potrebbe perdere traccia delle vostre convenzioni. Comprendere questi compromessi vi aiuta a costruire una configurazione efficace. Per una visualizzazione interattiva di come queste funzionalità si combinano in una sessione in esecuzione, consultate [Esplora la finestra di contesto](/it/context-window).

172 209

173### Costo del contesto per funzionalità210### Costo del contesto per funzionalità

174 211

178| -------------- | ----------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------- |215| -------------- | ----------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------- |

184 221

188 225

189Ogni funzionalità si carica in diversi punti della vostra sessione. Le schede seguenti spiegano quando ogni funzionalità si carica e cosa entra nel contesto.226Ogni funzionalità si carica in diversi punti della vostra sessione. Le schede seguenti spiegano quando ogni funzionalità si carica e cosa entra nel contesto.

190 227

191<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="Caricamento del contesto: CLAUDE.md e MCP si caricano all'inizio della sessione e rimangono in ogni richiesta. Le skills caricano descrizioni all'inizio, contenuto completo all'invocazione. I subagents ottengono contesto isolato. Gli hooks vengono eseguiti esternamente." width="720" height="410" data-path="images/context-loading.svg" />228<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="Caricamento del contesto: CLAUDE.md si carica all'inizio della sessione e rimane in ogni richiesta. I nomi degli strumenti MCP si caricano all'inizio con schemi completi rinviati fino all'uso. Le skills caricano descrizioni all'inizio, contenuto completo all'invocazione. I subagents ottengono contesto isolato. Gli hooks vengono eseguiti esternamente." width="720" height="410" data-path="images/context-loading.svg" />

192 229

193<Tabs>230<Tabs>

194 <Tab title="CLAUDE.md">231 <Tab title="CLAUDE.md">

202 </Tab>239 </Tab>

203 240

204 <Tab title="Skills">241 <Tab title="Skills">

205 Le skills sono capacità extra nel toolkit di Claude. Possono essere materiale di riferimento (come una guida di stile API) o flussi di lavoro invocabili che attivate con `/<name>` (come `/deploy`). Claude Code viene fornito con [skills raggruppate](/it/skills#bundled-skills) come `/simplify`, `/batch` e `/debug` che funzionano subito. Potete anche crearne di vostre. Claude utilizza le skills quando appropriato, oppure potete invocarne una direttamente.242 Le skills sono capacità extra nel toolkit di Claude. Possono essere materiale di riferimento (come una guida di stile API) o flussi di lavoro invocabili che attivate con `/<name>` (come `/deploy`). Claude Code include [skills raggruppate](/it/commands) come `/simplify`, `/batch` e `/debug` che funzionano subito. Potete anche crearne di vostre. Claude utilizza le skills quando appropriato, oppure potete invocarne una direttamente.

206 243

207 **Quando:** Dipende dalla configurazione della skill. Per impostazione predefinita, le descrizioni si caricano all'inizio della sessione e il contenuto completo si carica quando utilizzate. Per le skills solo utente (`disable-model-invocation: true`), niente si carica fino a quando non le invocate.244 **Quando:** Dipende dalla configurazione della skill. Per impostazione predefinita, le descrizioni si caricano all'inizio della sessione e il contenuto completo si carica quando utilizzate. Per le skills solo utente (`disable-model-invocation: true`), niente si carica fino a quando non le invocate.

208 245

212 249

213 **Costo del contesto:** Basso fino a quando non vengono utilizzate. Le skills solo utente hanno costo zero fino a quando non vengono invocate.250 **Costo del contesto:** Basso fino a quando non vengono utilizzate. Le skills solo utente hanno costo zero fino a quando non vengono invocate.

214 251

215 **Nei subagents:** Le skills funzionano diversamente nei subagents. Invece del caricamento su richiesta, le skills passate a un subagent vengono completamente precaricate nel suo contesto all'avvio. I subagents non ereditano le skills dalla sessione principale; dovete specificarle esplicitamente.252 **Nelle subagents:** Le skills funzionano diversamente nei subagents. Invece del caricamento su richiesta, le skills passate a un subagent vengono completamente precaricate nel suo contesto all'avvio. I subagents non ereditano le skills dalla sessione principale; dovete specificarle esplicitamente.

216 253

217 <Tip>Utilizzate `disable-model-invocation: true` per le skills con effetti collaterali. Questo risparmia contesto e assicura che solo voi le attiviate.</Tip>254 <Tip>Utilizzate `disable-model-invocation: true` per le skills con effetti collaterali. Questo risparmia contesto e assicura che solo voi le attiviate.</Tip>

218 </Tab>255 </Tab>

220 <Tab title="Server MCP">257 <Tab title="Server MCP">

221 **Quando:** Inizio della sessione.258 **Quando:** Inizio della sessione.

222 259

223 **Cosa si carica:** Tutte le definizioni degli strumenti e gli schemi JSON dai server connessi.260 **Cosa si carica:** Nomi degli strumenti dai server connessi. Gli schemi JSON completi rimangono rinviati fino a quando Claude non ha bisogno di uno strumento specifico.

224 261

225 **Costo del contesto:** [Ricerca degli strumenti](/it/mcp#scale-with-mcp-tool-search) (abilitata per impostazione predefinita) carica gli strumenti MCP fino al 10% del contesto e rinvia il resto fino a quando non è necessario.262 **Costo del contesto:** [Ricerca degli strumenti](/it/mcp#scale-with-mcp-tool-search) è abilitata per impostazione predefinita, quindi gli strumenti MCP inattivi consumano contesto minimo.

226 263

227 **Nota di affidabilità:** Le connessioni MCP possono fallire silenziosamente durante la sessione. Se un server si disconnette, i suoi strumenti scompaiono senza avviso. Claude potrebbe provare a utilizzare uno strumento che non esiste più. Se notate che Claude non riesce a utilizzare uno strumento MCP a cui poteva accedere in precedenza, controllate la connessione con `/mcp`.264 **Nota di affidabilità:** Le connessioni MCP possono fallire silenziosamente durante la sessione. Se un server si disconnette, i suoi strumenti scompaiono senza avviso. Claude potrebbe provare a utilizzare uno strumento che non esiste più. Se notate che Claude non riesce a utilizzare uno strumento MCP a cui poteva accedere in precedenza, controllate la connessione con `/mcp`.

228 265

245 </Tab>282 </Tab>

246 283

247 <Tab title="Hooks">284 <Tab title="Hooks">

248 **Quando:** Al trigger. Gli hooks si attivano su eventi del ciclo di vita specifici come esecuzione dello strumento, confini della sessione, invio del prompt, richieste di autorizzazione e compattazione. Consultate [Hooks](/it/hooks) per l'elenco completo.285 **Quando:** Al trigger. Gli hooks si attivano su eventi del ciclo di vita specifici come esecuzione dello strumento, confini della sessione, invio del prompt, richieste di autorizzazione e compattazione. Consultate [Hooks](/it/hooks-guide) per l'elenco completo.

249 286

250 **Cosa si carica:** Niente per impostazione predefinita. Gli hooks vengono eseguiti come script esterni.287 **Cosa si carica:** Niente per impostazione predefinita. Gli hooks vengono eseguiti al di fuori della conversazione principale.

251 288

252 **Costo del contesto:** Zero, a meno che l'hook non restituisca output che viene aggiunto come messaggi alla vostra conversazione.289 **Costo del contesto:** Zero, a meno che l'hook non restituisca output che viene aggiunto come messaggi alla vostra conversazione.

253 290

hooks.md +6 −6

Details

970Per bloccare un prompt, restituire un oggetto JSON con `decision` impostato su `"block"`:970Per bloccare un prompt, restituire un oggetto JSON con `decision` impostato su `"block"`:

971 971

972| Campo | Descrizione |972| Campo | Descrizione |

973| :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------- |973| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------- |

974| `decision` | `"block"` impedisce l'elaborazione del prompt e lo cancella dal contesto. Omettere per consentire al prompt di procedere |974| `decision` | `"block"` impedisce l'elaborazione del prompt e lo cancella dal contesto. Omettere per consentire al prompt di procedere |

976| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt inviato. Consultare [Aggiungere contesto per Claude](#add-context-for-claude) |976| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al prompt inviato. Consultare [Aggiungere contesto per Claude](#add-context-for-claude) |

977| `sessionTitle` | Imposta il titolo della sessione, stesso effetto di `/rename`. Utilizzare per denominare automaticamente le sessioni in base al contenuto del prompt |977| `sessionTitle` | Imposta il titolo della sessione. Utilizzare per denominare automaticamente le sessioni in base al contenuto del prompt |

978 978

979```json theme={null}979```json theme={null}

980{980{

1358 1358

1359| Campo | Descrizione |1359| Campo | Descrizione |

1360| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |1360| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1361| `decision` | `"block"` richiede a Claude con il `reason`. Omettere per consentire all'azione di procedere |1361| `decision` | `"block"` aggiunge il `reason` accanto al risultato dello strumento. Claude vede ancora l'output originale; per sostituirlo, utilizzare `updatedToolOutput` |

1363| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Consultare [Aggiungere contesto per Claude](#add-context-for-claude) |1363| `additionalContext` | Stringa aggiunta al contesto di Claude insieme al risultato dello strumento. Consultare [Aggiungere contesto per Claude](#add-context-for-claude) |

1364| `updatedToolOutput` | Sostituisce l'output dello strumento con il valore fornito prima che venga inviato a Claude. Il valore deve corrispondere alla forma di output dello strumento |1364| `updatedToolOutput` | Sostituisce l'output dello strumento con il valore fornito prima che venga inviato a Claude. Il valore deve corrispondere alla forma di output dello strumento |

2407```2407```

2408 2408

2409| Campo | Descrizione |2409| Campo | Descrizione |

2410| :------- | :------------------------------------------------------------ |2410| :------- | :-------------------------------------------------------------------------------------------- |

2411| `ok` | `true` consente l'azione, `false` la impedisce |2411| `ok` | `true` consente l'azione, `false` la impedisce. Vedere il comportamento per evento di seguito |

2413 2413

2414Ciò che accade con `ok: false` dipende dall'evento:2414Ciò che accade con `ok: false` dipende dall'evento:

2415 2415

permissions.md +4 −119

Details

36| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |36| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

38| `acceptEdits` | Accetta automaticamente le modifiche ai file e i comandi comuni del filesystem (`mkdir`, `touch`, `mv`, `cp`, ecc.) per i percorsi nella directory di lavoro o `additionalDirectories` |38| `acceptEdits` | Accetta automaticamente le modifiche ai file e i comandi comuni del filesystem (`mkdir`, `touch`, `mv`, `cp`, ecc.) per i percorsi nella directory di lavoro o `additionalDirectories` |

40| `auto` | Auto-approva le chiamate di strumento con controlli di sicurezza in background che verificano che le azioni si allineino con la Sua richiesta. Attualmente un'anteprima di ricerca |40| `auto` | Auto-approva le chiamate di strumento con controlli di sicurezza in background che verificano che le azioni si allineino con la Sua richiesta. Attualmente un'anteprima di ricerca |

41| `dontAsk` | Nega automaticamente gli strumenti a meno che non siano pre-approvati tramite `/permissions` o regole `permissions.allow` |41| `dontAsk` | Nega automaticamente gli strumenti a meno che non siano pre-approvati tramite `/permissions` o regole `permissions.allow` |

42| `bypassPermissions` | Salta i prompt di autorizzazione. Le rimozioni che hanno come destinazione la radice del filesystem o la directory home, come `rm -rf /` e `rm -rf ~`, richiedono comunque un prompt come interruttore di protezione contro gli errori del modello |42| `bypassPermissions` | Salta i prompt di autorizzazione. Le rimozioni che hanno come destinazione la radice del filesystem o la directory home, come `rm -rf /` e `rm -rf ~`, richiedono comunque un prompt come interruttore di protezione contro gli errori del modello |

296 296

297* Le regole deny di autorizzazione impediscono a Claude di tentare anche di accedere alle risorse limitate297* Le regole deny di autorizzazione impediscono a Claude di tentare anche di accedere alle risorse limitate

298* Le restrizioni sandbox impediscono ai comandi Bash di raggiungere risorse al di fuori dei confini definiti, anche se un'iniezione di prompt bypassa il processo decisionale di Claude298* Le restrizioni sandbox impediscono ai comandi Bash di raggiungere risorse al di fuori dei confini definiti, anche se un'iniezione di prompt bypassa il processo decisionale di Claude

299* Le restrizioni del filesystem nella sandbox utilizzano le regole deny di Read e Edit, non una configurazione sandbox separata299* Le restrizioni del filesystem nella sandbox combinano le impostazioni [`sandbox.filesystem`](/it/sandboxing) con le regole deny di Read e Edit; entrambe vengono unite nel confine sandbox finale

300* Le restrizioni di rete combinano le regole di autorizzazione WebFetch con gli elenchi `allowedDomains` e `deniedDomains` della sandbox300* Le restrizioni di rete combinano le regole di autorizzazione WebFetch con gli elenchi `allowedDomains` e `deniedDomains` della sandbox

301 301

302Quando il sandboxing è abilitato con `autoAllowBashIfSandboxed: true`, che è l'impostazione predefinita, i comandi Bash in sandbox vengono eseguiti senza richiedere un prompt anche se le vostre autorizzazioni includono `ask: Bash(*)`. Il confine della sandbox sostituisce il prompt per comando. Le regole deny esplicite si applicano ancora, e i comandi `rm` o `rmdir` che hanno come destinazione `/`, la vostra directory home o altri percorsi critici del sistema attivano comunque un prompt. Consultate [modalità sandbox](/it/sandboxing#sandbox-modes) per modificare questo comportamento.302Quando il sandboxing è abilitato con `autoAllowBashIfSandboxed: true`, che è l'impostazione predefinita, i comandi Bash in sandbox vengono eseguiti senza richiedere un prompt anche se le vostre autorizzazioni includono `ask: Bash(*)`. Il confine della sandbox sostituisce il prompt per comando. Le regole deny esplicite si applicano ancora, e i comandi `rm` o `rmdir` che hanno come destinazione `/`, la vostra directory home o altri percorsi critici del sistema attivano comunque un prompt. Consultate [modalità sandbox](/it/sandboxing#sandbox-modes) per modificare questo comportamento.

316| `allowManagedMcpServersOnly` | Quando `true`, solo `allowedMcpServers` dalle impostazioni gestite sono rispettati. `deniedMcpServers` si unisce comunque da tutte le fonti. Vedi [Configurazione MCP gestita](/it/mcp#managed-mcp-configuration) |316| `allowManagedMcpServersOnly` | Quando `true`, solo `allowedMcpServers` dalle impostazioni gestite sono rispettati. `deniedMcpServers` si unisce comunque da tutte le fonti. Vedi [Configurazione MCP gestita](/it/mcp#managed-mcp-configuration) |

317| `allowManagedPermissionRulesOnly` | Quando `true`, impedisce alle impostazioni utente e di progetto di definire regole di autorizzazione `allow`, `ask` o `deny`. Si applicano solo le regole nelle impostazioni gestite |317| `allowManagedPermissionRulesOnly` | Quando `true`, impedisce alle impostazioni utente e di progetto di definire regole di autorizzazione `allow`, `ask` o `deny`. Si applicano solo le regole nelle impostazioni gestite |

318| `blockedMarketplaces` | Elenco di blocco delle fonti del marketplace. Le fonti bloccate vengono controllate prima del download, quindi non toccano mai il filesystem. Vedi [restrizioni marketplace gestite](/it/plugin-marketplaces#managed-marketplace-restrictions) |318| `blockedMarketplaces` | Elenco di blocco delle fonti del marketplace. Le fonti bloccate vengono controllate prima del download, quindi non toccano mai il filesystem. Vedi [restrizioni marketplace gestite](/it/plugin-marketplaces#managed-marketplace-restrictions) |

319| `channelsEnabled` | Consenti [channels](/it/channels) per gli utenti Team e Enterprise. Non impostato o `false` blocca la consegna dei messaggi di canale indipendentemente da ciò che gli utenti passano a `--channels` |319| `channelsEnabled` | Consenti [channels](/it/channels) per l'organizzazione. Vedi [controlli aziendali](/it/channels#enterprise-controls) per l'impostazione predefinita su ogni piano |

320| `forceRemoteSettingsRefresh` | Quando `true`, blocca l'avvio della CLI fino a quando le impostazioni gestite remote non vengono recuperate di recente ed esce se il recupero non riesce. Vedi [applicazione fail-closed](/it/server-managed-settings#enforce-fail-closed-startup) |320| `forceRemoteSettingsRefresh` | Quando `true`, blocca l'avvio della CLI fino a quando le impostazioni gestite remote non vengono recuperate di recente ed esce se il recupero non riesce. Vedi [applicazione fail-closed](/it/server-managed-settings#enforce-fail-closed-startup) |

321| `pluginTrustMessage` | Messaggio personalizzato aggiunto all'avviso di fiducia del plugin mostrato prima dell'installazione |321| `pluginTrustMessage` | Messaggio personalizzato aggiunto all'avviso di fiducia del plugin mostrato prima dell'installazione |

322| `sandbox.filesystem.allowManagedReadPathsOnly` | Quando `true`, solo i percorsi `filesystem.allowRead` dalle impostazioni gestite sono rispettati. `denyRead` si unisce comunque da tutte le fonti |322| `sandbox.filesystem.allowManagedReadPathsOnly` | Quando `true`, solo i percorsi `filesystem.allowRead` dalle impostazioni gestite sono rispettati. `denyRead` si unisce comunque da tutte le fonti |

327`disableBypassPermissionsMode` è tipicamente posizionato nelle impostazioni gestite per applicare la politica organizzativa, ma funziona da qualsiasi ambito. Un utente può impostarlo nelle proprie impostazioni per bloccarsi dalla modalità bypass.327`disableBypassPermissionsMode` è tipicamente posizionato nelle impostazioni gestite per applicare la politica organizzativa, ma funziona da qualsiasi ambito. Un utente può impostarlo nelle proprie impostazioni per bloccarsi dalla modalità bypass.

328 328

329<Note>329<Note>

330 L'accesso a [Remote Control](/it/remote-control) e [sessioni web](/it/claude-code-on-the-web) non è controllato da una chiave di impostazioni gestite. Nei piani Team e Enterprise, un amministratore abilita o disabilita queste funzioni nelle [impostazioni di amministrazione di Claude Code](https://claude.ai/admin-settings/claude-code).330 Su piani Team e Enterprise, un amministratore abilita o disabilita [Remote Control](/it/remote-control) e [sessioni web](/it/claude-code-on-the-web) a livello organizzativo nelle [impostazioni di amministrazione di Claude Code](https://claude.ai/admin-settings/claude-code). Remote Control può inoltre essere disabilitato per dispositivo con l'impostazione gestita [`disableRemoteControl`](/it/settings#available-settings). Le sessioni web non hanno chiavi di impostazioni gestite per dispositivo.

331</Note>331</Note>

332 332

333## Esaminare i rifiuti della modalità auto

~~334~~

335Quando la [modalità auto](/it/permission-modes#eliminate-prompts-with-auto-mode) nega una chiamata di strumento, appare una notifica e l'azione negata viene registrata in `/permissions` nella scheda Recently denied. Premete `r` su un'azione negata per contrassegnarla per il retry: quando uscite dalla finestra di dialogo, Claude Code invia un messaggio dicendo al modello che può riprovare quella chiamata di strumento e riprende la conversazione.

~~336~~

337Per reagire ai rifiuti a livello di programmazione, utilizzate l'[hook `PermissionDenied`](/it/hooks#permissiondenied).

~~338~~

339## Configurare il classificatore della modalità auto

~~340~~

341La [modalità auto](/it/permission-modes#eliminate-prompts-with-auto-mode) utilizza un modello di classificazione per decidere se ogni azione è sicura da eseguire senza richiedere. Per impostazione predefinita, si fida solo della directory di lavoro e, se presente, dei remoti del repository corrente. Azioni come il push verso l'organizzazione di controllo del codice sorgente della vostra azienda o la scrittura in un bucket cloud del team verranno bloccate come potenziale esfiltrazione di dati.

~~342~~

343Per regolare ciò che il classificatore consente o blocca, aggiungete istruzioni al vostro file [CLAUDE.md](/it/memory). Il classificatore legge CLAUDE.md dalle directory affidabili insieme alla conversazione, quindi un'istruzione come "non forzare mai il push" guida sia Claude che il classificatore contemporaneamente. Iniziate qui per le convenzioni di progetto e le regole comportamentali.

~~344~~

345Per le regole che si applicano tra i progetti, come l'infrastruttura affidabile o le regole di negazione a livello organizzativo, utilizzate il blocco di impostazioni `autoMode`. Il classificatore legge `autoMode` dalle impostazioni utente, `.claude/settings.local.json` e impostazioni gestite. Non legge dalle impostazioni di progetto condivise in `.claude/settings.json`, perché un repository archiviato potrebbe altrimenti iniettare le sue proprie regole allow.

~~346~~

347| Ambito | File | Utilizzare per |

348| :---------------------------- | :---------------------------- | :----------------------------------------------------------- |

349| Un sviluppatore | `~/.claude/settings.json` | Infrastruttura affidabile personale |

350| Un progetto, uno sviluppatore | `.claude/settings.local.json` | Bucket o servizi affidabili per progetto, gitignored |

351| Organizzazione | Impostazioni gestite | Infrastruttura affidabile applicata a tutti gli sviluppatori |

~~352~~

353Le voci da ogni ambito vengono combinate. Uno sviluppatore può estendere `environment`, `allow` e `soft_deny` con voci personali ma non può rimuovere le voci fornite dalle impostazioni gestite. Poiché le regole allow agiscono come eccezioni alle regole di blocco all'interno del classificatore, una voce `allow` aggiunta da uno sviluppatore può ignorare una voce `soft_deny` dell'organizzazione: la combinazione è additiva, non un confine di criteri rigido. Se avete bisogno di una regola che gli sviluppatori non possono aggirare, utilizzate `permissions.deny` nelle impostazioni gestite, che blocca le azioni prima che il classificatore venga consultato.

~~354~~

355### Definire l'infrastruttura affidabile

~~356~~

357Per la maggior parte delle organizzazioni, `autoMode.environment` è l'unico campo che dovete impostare. Dice al classificatore quali repository, bucket e domini sono affidabili, senza toccare le regole di blocco e allow integrate. Il classificatore utilizza `environment` per decidere cosa significa "esterno": qualsiasi destinazione non elencata è un potenziale obiettivo di esfiltrazione.

~~358~~

359```json theme={null}

360{

361 "autoMode": {

362 "environment": [

363 "Source control: github.example.com/acme-corp and all repos under it",

364 "Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets",

365 "Trusted internal domains: *.corp.example.com, api.internal.example.com",

366 "Key internal services: Jenkins at ci.example.com, Artifactory at artifacts.example.com"

367 ]

368 }

369}

370```

~~371~~

372Le voci sono prosa, non regex o modelli di strumento. Il classificatore le legge come regole in linguaggio naturale. Scrivitele come descrivereste la vostra infrastruttura a un nuovo ingegnere. Una sezione environment approfondita copre:

~~373~~

374* **Organizzazione**: il nome della vostra azienda e per cosa Claude Code viene utilizzato principalmente, come sviluppo software, automazione dell'infrastruttura o ingegneria dei dati

375* **Controllo del codice sorgente**: ogni organizzazione GitHub, GitLab o Bitbucket a cui i vostri sviluppatori eseguono il push

376* **Provider cloud e bucket affidabili**: nomi di bucket o prefissi che Claude dovrebbe essere in grado di leggere e scrivere

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

378* **Servizi interni chiave**: CI, registri di artefatti, indici di pacchetti interni, strumenti di incidenti

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

~~380~~

381Un modello di partenza utile: compilate i campi tra parentesi e rimuovete le righe che non si applicano:

~~382~~

383```json theme={null}

384{

385 "autoMode": {

386 "environment": [

387 "Organization: {COMPANY_NAME}. Primary use: {PRIMARY_USE_CASE, e.g. software development, infrastructure automation}",

388 "Source control: {SOURCE_CONTROL, e.g. GitHub org github.example.com/acme-corp}",

389 "Cloud provider(s): {CLOUD_PROVIDERS, e.g. AWS, GCP, Azure}",

390 "Trusted cloud buckets: {TRUSTED_BUCKETS, e.g. s3://acme-builds, gs://acme-datasets}",

391 "Trusted internal domains: {TRUSTED_DOMAINS, e.g. *.internal.example.com, api.example.com}",

392 "Key internal services: {SERVICES, e.g. Jenkins at ci.example.com, Artifactory at artifacts.example.com}",

393 "Additional context: {EXTRA, e.g. regulated industry, multi-tenant infrastructure, compliance requirements}"

394 ]

395 }

396}

397```

~~398~~

399Più contesto specifico fornite, meglio il classificatore può distinguere le operazioni interne di routine dai tentativi di esfiltrazione.

~~400~~

401Non è necessario compilare tutto in una volta. Un rollout ragionevole: iniziate con i valori predefiniti e aggiungete la vostra organizzazione di controllo del codice sorgente e i servizi interni chiave, che risolvono i falsi positivi più comuni come il push nei vostri repository. Aggiungete i domini affidabili e i bucket cloud successivamente. Compilate il resto man mano che i blocchi si presentano.

~~402~~

403### Ignorare le regole di blocco e allow

~~404~~

405Due campi aggiuntivi vi consentono di sostituire gli elenchi di regole integrate del classificatore: `autoMode.soft_deny` controlla cosa viene bloccato e `autoMode.allow` controlla quali eccezioni si applicano. Ognuno è un array di descrizioni in prosa, lette come regole in linguaggio naturale.

~~406~~

407All'interno del classificatore, la precedenza è: le regole `soft_deny` bloccano per prime, quindi le regole `allow` ignorano come eccezioni, quindi l'intento esplicito dell'utente ignora entrambi. Se il messaggio dell'utente descrive direttamente e specificamente l'azione esatta che Claude sta per intraprendere, il classificatore la consente anche se una regola `soft_deny` corrisponde. Le richieste generali non contano: chiedere a Claude di "pulire il repository" non autorizza il force-push, ma chiedere a Claude di "force-push questo ramo" sì.

~~408~~

409Per allentare: rimuovete le regole da `soft_deny` quando i valori predefiniti bloccano qualcosa che la vostra pipeline già protegge con revisione PR, CI o ambienti di staging, o aggiungete a `allow` quando il classificatore contrassegna ripetutamente un modello di routine che le eccezioni predefinite non coprono. Per stringere: aggiungete a `soft_deny` per i rischi specifici del vostro ambiente che i valori predefiniti mancano, o rimuovete da `allow` per mantenere un'eccezione predefinita alle regole di blocco. In tutti i casi, eseguite `claude auto-mode defaults` per ottenere gli elenchi predefiniti completi, quindi copiate e modificate: non iniziate mai da un elenco vuoto.

~~410~~

411```json theme={null}

412{

413 "autoMode": {

414 "environment": [

415 "Source control: github.example.com/acme-corp and all repos under it"

416 ],

417 "allow": [

418 "Deploying to the staging namespace is allowed: staging is isolated from production and resets nightly",

419 "Writing to s3://acme-scratch/ is allowed: ephemeral bucket with a 7-day lifecycle policy"

420 ],

421 "soft_deny": [

422 "Never run database migrations outside the migrations CLI, even against dev databases",

423 "Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow",

424 "...copy full default soft_deny list here first, then add your rules..."

425 ]

426 }

427}

428```

~~429~~

430<Danger>

431 Impostare `allow` o `soft_deny` sostituisce l'intero elenco predefinito per quella sezione. Se impostate `soft_deny` con una singola voce, ogni regola di blocco integrata viene scartata: force push, esfiltrazione di dati, `curl | bash`, deploy di produzione e tutte le altre regole di blocco predefinite diventano consentite. Per personalizzare in modo sicuro, eseguite `claude auto-mode defaults` per stampare le regole integrate, copiatele nel vostro file di impostazioni, quindi rivedete ogni regola rispetto alla vostra pipeline e tolleranza al rischio. Rimuovete solo le regole per i rischi che la vostra infrastruttura già mitiga.

432</Danger>

~~433~~

434Le tre sezioni vengono valutate indipendentemente, quindi impostare solo `environment` lascia intatti gli elenchi predefiniti `allow` e `soft_deny`.

~~435~~

436### Ispezionare i valori predefiniti e la vostra configurazione effettiva

~~437~~

438Poiché impostare `allow` o `soft_deny` sostituisce i valori predefiniti, iniziate qualsiasi personalizzazione copiando gli elenchi predefiniti completi. Tre sottocomandi CLI vi aiutano a ispezionare e convalidare:

~~439~~

440```bash theme={null}

441claude auto-mode defaults # the built-in environment, allow, and soft_deny rules

442claude auto-mode config # what the classifier actually uses: your settings where set, defaults otherwise

443claude auto-mode critique # get AI feedback on your custom allow and soft_deny rules

444```

~~445~~

446Salvate l'output di `claude auto-mode defaults` in un file, modificate gli elenchi per corrispondere alla vostra politica e incollate il risultato nel vostro file di impostazioni. Dopo il salvataggio, eseguite `claude auto-mode config` per confermare che le regole effettive sono quelle che vi aspettate. Se avete scritto regole personalizzate, `claude auto-mode critique` le rivede e contrassegna le voci che sono ambigue, ridondanti o probabilmente causeranno falsi positivi.

~~447~~

448## Precedenza delle impostazioni333## Precedenza delle impostazioni

449 334

450Le regole di autorizzazione seguono la stessa [precedenza delle impostazioni](/it/settings#settings-precedence) di tutte le altre impostazioni di Claude Code:335Le regole di autorizzazione seguono la stessa [precedenza delle impostazioni](/it/settings#settings-precedence) di tutte le altre impostazioni di Claude Code:

platforms.md +7 −4

Details

4 4

5# Piattaforme e integrazioni5# Piattaforme e integrazioni

6 6

~~7> Scegli dove eseguire Claude Code e cosa collegare. Confronta CLI, Desktop, VS Code, JetBrains, web e integrazioni come Chrome, Slack e CI/CD.~~7> Scegli dove eseguire Claude Code e cosa collegare. Confronta CLI, Desktop, VS Code, JetBrains, web, mobile e integrazioni come Chrome, Slack e CI/CD.

8 8

9Claude Code esegue lo stesso motore sottostante ovunque, ma ogni superficie è ottimizzata per un modo diverso di lavorare. Questa pagina ti aiuta a scegliere la piattaforma giusta per il tuo flusso di lavoro e a collegare gli strumenti che già utilizzi.9Claude Code esegue lo stesso motore sottostante ovunque, ma ogni superficie è ottimizzata per un modo diverso di lavorare. Questa pagina ti aiuta a scegliere la piattaforma giusta per il tuo flusso di lavoro e a collegare gli strumenti che già utilizzi.

10 10

13Scegli una piattaforma in base a come preferisci lavorare e dove si trova il tuo progetto.13Scegli una piattaforma in base a come preferisci lavorare e dove si trova il tuo progetto.

14 14

16| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |16| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

17| [CLI](/it/quickstart) | Flussi di lavoro da terminale, scripting, server remoti | Set completo di funzionalità, [Agent SDK](/it/headless), provider di terze parti |17| [CLI](/it/quickstart) | Flussi di lavoro da terminale, scripting, server remoti | Set completo di funzionalità, [Agent SDK](/it/headless), [computer use](/it/computer-use) su macOS (Pro e Max), provider di terze parti |

18| [Desktop](/it/desktop) | Revisione visiva, sessioni parallele, configurazione gestita | Visualizzatore diff, anteprima app, [computer use](/it/desktop#let-claude-use-your-computer) e [Dispatch](/it/desktop#sessions-from-dispatch) su Pro e Max |18| [Desktop](/it/desktop) | Revisione visiva, sessioni parallele, configurazione gestita | Visualizzatore diff, anteprima app, [computer use](/it/desktop#let-claude-use-your-computer) e [Dispatch](/it/desktop#sessions-from-dispatch) su Pro e Max |

21| [Web](/it/claude-code-on-the-web) | Attività a lunga esecuzione che non richiedono molto controllo, o lavoro che dovrebbe continuare quando sei offline | Cloud gestito da Anthropic, continua dopo la disconnessione |21| [Web](/it/claude-code-on-the-web) | Attività a lunga esecuzione che non richiedono molto controllo, o lavoro che dovrebbe continuare quando sei offline | Cloud gestito da Anthropic, continua dopo la disconnessione |

22| Mobile | Avviare e monitorare attività mentre sei lontano dal tuo computer | Sessioni cloud dall'app Claude per iOS e Android, [Remote Control](/it/remote-control) per sessioni locali, [Dispatch](/it/desktop#sessions-from-dispatch) verso Desktop su Pro e Max |

22 23

23La CLI è la superficie più completa per il lavoro nativo da terminale: scripting, provider di terze parti e Agent SDK sono solo CLI. Desktop e le estensioni IDE scambiano alcune funzionalità solo CLI per revisione visiva e integrazione editor più stretta. Il web viene eseguito nel cloud di Anthropic, quindi le attività continuano dopo la disconnessione.24La CLI è la superficie più completa per il lavoro nativo da terminale: scripting e Agent SDK sono solo CLI. I provider di terze parti funzionano anche in [VS Code](/it/vs-code#use-third-party-providers). Le distribuzioni [Desktop](/it/desktop) aziendali supportano Vertex AI e provider gateway; per Bedrock o Foundry, usa invece la CLI o VS Code al posto di Desktop. Desktop e le estensioni IDE scambiano alcune funzionalità solo CLI per revisione visiva e integrazione editor più stretta. Il web viene eseguito nel cloud di Anthropic, quindi le attività continuano dopo la disconnessione. Mobile è un thin client nelle stesse sessioni cloud o in una sessione locale tramite Remote Control, e può inviare attività a Desktop con Dispatch.

24 25

25Puoi mescolare superfici sullo stesso progetto. La configurazione, la memoria del progetto e i server MCP sono condivisi tra le superfici locali.26Puoi mescolare superfici sullo stesso progetto. La configurazione, la memoria del progetto e i server MCP sono condivisi tra le superfici locali.

26 27

61* [VS Code](/it/vs-code): l'estensione Claude Code all'interno del tuo editor62* [VS Code](/it/vs-code): l'estensione Claude Code all'interno del tuo editor

62* [JetBrains](/it/jetbrains): l'estensione per IntelliJ, PyCharm e altri IDE JetBrains63* [JetBrains](/it/jetbrains): l'estensione per IntelliJ, PyCharm e altri IDE JetBrains

63* [Claude Code sul web](/it/claude-code-on-the-web): sessioni cloud che continuano a funzionare quando ti disconnetti64* [Claude Code sul web](/it/claude-code-on-the-web): sessioni cloud che continuano a funzionare quando ti disconnetti

65* Mobile: l'app Claude per [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) e [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) per avviare e monitorare attività mentre sei lontano dal tuo computer

64 66

65### Integrazioni67### Integrazioni

66 68

67* [Chrome](/it/chrome): automatizza attività del browser con le tue sessioni connesse69* [Chrome](/it/chrome): automatizza attività del browser con le tue sessioni connesse

70* [Computer use](/it/computer-use): consenti a Claude di aprire app e controllare il tuo schermo su macOS

68* [GitHub Actions](/it/github-actions): esegui Claude nella tua pipeline CI71* [GitHub Actions](/it/github-actions): esegui Claude nella tua pipeline CI

69* [GitLab CI/CD](/it/gitlab-ci-cd): lo stesso per GitLab72* [GitLab CI/CD](/it/gitlab-ci-cd): lo stesso per GitLab

70* [Code Review](/it/code-review): revisione automatica su ogni pull request73* [Code Review](/it/code-review): revisione automatica su ogni pull request

plugin-marketplaces.md +9 −7

Details

23 23

24## Procedura dettagliata: creare un marketplace locale24## Procedura dettagliata: creare un marketplace locale

25 25

26Questo esempio crea un marketplace con un plugin: una skill `/quality-review` per le revisioni del codice. Creerai la struttura delle directory, aggiungerai una skill, creerai il manifest del plugin e il catalogo del marketplace, quindi lo installerai e lo testerai.26Questo esempio crea un marketplace con un plugin: una skill `quality-review` per le revisioni del codice. Creerai la struttura delle directory, aggiungerai una skill, creerai il manifest del plugin e il catalogo del marketplace, quindi lo installerai e lo testerai.

27 27

28<Steps>28<Steps>

29 <Step title="Crea la struttura delle directory">29 <Step title="Crea la struttura delle directory">

35 </Step>35 </Step>

36 36

37 <Step title="Crea la skill">37 <Step title="Crea la skill">

~~38 Crea un file `SKILL.md` che definisce cosa fa la skill `/quality-review`.~~38 Crea un file `SKILL.md` che definisce cosa fa la skill `quality-review`.

39 39

40 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}40 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}

41 ---41 ---

59 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}59 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}

60 {60 {

61 "name": "quality-review-plugin",61 "name": "quality-review-plugin",

~~62 "description": "Aggiunge una skill /quality-review per revisioni rapide del codice",~~62 "description": "Aggiunge una skill quality-review per revisioni rapide del codice",

63 "version": "1.0.0"63 "version": "1.0.0"

64 }64 }

65 ```65 ```

82 {82 {

83 "name": "quality-review-plugin",83 "name": "quality-review-plugin",

84 "source": "./plugins/quality-review-plugin",84 "source": "./plugins/quality-review-plugin",

~~85 "description": "Aggiunge una skill /quality-review per revisioni rapide del codice"~~85 "description": "Aggiunge una skill quality-review per revisioni rapide del codice"

86 }86 }

87 ]87 ]

88 }88 }

99 </Step>99 </Step>

100 100

101 <Step title="Provalo">101 <Step title="Provalo">

102 Seleziona del codice nel tuo editor ed esegui la tua nuova skill.102 Seleziona del codice nel tuo editor ed esegui la tua nuova skill. Le skill dei plugin sono associate allo spazio dei nomi del nome del plugin.

103 103

104 ```shell theme={null}104 ```shell theme={null}

105 /quality-review105 /quality-review-plugin:quality-review

106 ```106 ```

107 </Step>107 </Step>

108</Steps>108</Steps>

693* Per le fonti `hostPattern`: l'host del marketplace viene confrontato con il modello regex693* Per le fonti `hostPattern`: l'host del marketplace viene confrontato con il modello regex

694* Per le fonti `pathPattern`: il percorso del filesystem del marketplace viene confrontato con il modello regex694* Per le fonti `pathPattern`: il percorso del filesystem del marketplace viene confrontato con il modello regex

695 695

696La corrispondenza esatta non normalizza gli URL: una barra finale, il suffisso `.git` o il modulo `ssh://` rispetto a `https://` vengono trattati come valori diversi. Se il marketplace della tua organizzazione può essere clonato da più di una forma di URL, preferisci una voce `hostPattern` rispetto a un URL letterale in modo che tutte le forme corrispondano.

697

696Poiché `strictKnownMarketplaces` è impostato nelle [impostazioni gestite](/it/settings#settings-files), le configurazioni individuali degli utenti e dei progetti non possono ignorare queste restrizioni.698Poiché `strictKnownMarketplaces` è impostato nelle [impostazioni gestite](/it/settings#settings-files), le configurazioni individuali degli utenti e dei progetti non possono ignorare queste restrizioni.

697 699

698Per i dettagli di configurazione completi inclusi tutti i tipi di fonte supportati e il confronto con `extraKnownMarketplaces`, vedi il [riferimento strictKnownMarketplaces](/it/settings#strictknownmarketplaces).700Per i dettagli di configurazione completi inclusi tutti i tipi di fonte supportati e il confronto con `extraKnownMarketplaces`, vedi il [riferimento strictKnownMarketplaces](/it/settings#strictknownmarketplaces).

720Per supportare i canali di rilascio "stable" e "latest" per i tuoi plugin, puoi configurare due marketplace che puntano a diversi ref o SHA dello stesso repo. Puoi quindi assegnare i due marketplace a diversi gruppi di utenti tramite [impostazioni gestite](/it/settings#settings-files).722Per supportare i canali di rilascio "stable" e "latest" per i tuoi plugin, puoi configurare due marketplace che puntano a diversi ref o SHA dello stesso repo. Puoi quindi assegnare i due marketplace a diversi gruppi di utenti tramite [impostazioni gestite](/it/settings#settings-files).

721 723

722<Warning>724<Warning>

723 Ogni canale deve risolversi a una versione diversa. Se usi versioni esplicite, `plugin.json` deve dichiarare una `version` diversa in ogni ref o SHA fissato. Se ometti `version`, gli SHA dei commit distinti già distinguono i canali. Se due ref si risolvono alla stessa stringa di versione, Claude Code li tratta come identici e salta l'aggiornamento.725 Ogni canale deve risolversi a una versione diversa. Se usi versioni esplicite, `plugin.json` deve dichiarare una `version` diversa in ogni ref fissato. Se ometti `version`, gli SHA dei commit distinti già distinguono i canali. Se due ref si risolvono alla stessa stringa di versione, Claude Code li tratta come identici e salta l'aggiornamento.

724</Warning>726</Warning>

725 727

726##### Esempio728##### Esempio

plugins-reference.md +7 −3

Details

262**Plugin LSP disponibili:**262**Plugin LSP disponibili:**

263 263

265| :--------------- | :------------------------- | :---------------------------------------------------------------------------------------------- |265| :------------------ | :------------------------- | :---------------------------------------------------------------------------------------------- |

269 269

270Installa il server di linguaggio per primo, quindi installa il plugin dal marketplace.270Installa il server di linguaggio per primo, quindi installa il plugin dal marketplace.

271 271

531 531

532Claude Code fornisce due variabili per fare riferimento ai percorsi del plugin. Entrambe vengono sostituite inline ovunque appaiano nel contenuto delle skills, nel contenuto degli agents, nei comandi degli hooks, nei comandi dei monitor e nelle configurazioni dei server MCP o LSP. Entrambe vengono anche esportate come variabili di ambiente ai processi degli hooks e ai sottoprocessi dei server MCP o LSP.532Claude Code fornisce due variabili per fare riferimento ai percorsi del plugin. Entrambe vengono sostituite inline ovunque appaiano nel contenuto delle skills, nel contenuto degli agents, nei comandi degli hooks, nei comandi dei monitor e nelle configurazioni dei server MCP o LSP. Entrambe vengono anche esportate come variabili di ambiente ai processi degli hooks e ai sottoprocessi dei server MCP o LSP.

533 533

534**`${CLAUDE_PLUGIN_ROOT}`**: il percorso assoluto della directory di installazione del tuo plugin. Usalo per fare riferimento a script, binari e file di configurazione forniti con il plugin. Questo percorso cambia quando il plugin viene aggiornato, quindi i file che scrivi qui non sopravvivono a un aggiornamento.534**`${CLAUDE_PLUGIN_ROOT}`**: il percorso assoluto della directory di installazione del tuo plugin. Usalo per fare riferimento a script, binari e file di configurazione forniti con il plugin. Questo percorso cambia quando il plugin viene aggiornato. La directory della versione precedente rimane su disco per circa sette giorni dopo un aggiornamento prima della pulizia, ma trattala come effimera e non scrivere stato qui.

535

536Quando un plugin viene aggiornato a metà sessione, i comandi degli hooks, i monitor, i server MCP e i server LSP continuano a utilizzare il percorso della versione precedente. Esegui `/reload-plugins` per passare gli hooks, i server MCP e i server LSP al nuovo percorso; i monitor richiedono un riavvio della sessione.

535 537

536**`${CLAUDE_PLUGIN_DATA}`**: una directory persistente per lo stato del plugin che sopravvive agli aggiornamenti. Usalo per le dipendenze installate come `node_modules` o ambienti virtuali Python, codice generato, cache e qualsiasi altro file che dovrebbe persistere tra le versioni del plugin. La directory viene creata automaticamente la prima volta che questa variabile viene referenziata.538**`${CLAUDE_PLUGIN_DATA}`**: una directory persistente per lo stato del plugin che sopravvive agli aggiornamenti. Usalo per le dipendenze installate come `node_modules` o ambienti virtuali Python, codice generato, cache e qualsiasi altro file che dovrebbe persistere tra le versioni del plugin. La directory viene creata automaticamente la prima volta che questa variabile viene referenziata.

537 539

677 La directory `.claude-plugin/` contiene il file `plugin.json`. Tutte le altre directory (commands/, agents/, skills/, output-styles/, themes/, monitors/, hooks/) devono essere nella radice del plugin, non all'interno di `.claude-plugin/`.679 La directory `.claude-plugin/` contiene il file `plugin.json`. Tutte le altre directory (commands/, agents/, skills/, output-styles/, themes/, monitors/, hooks/) devono essere nella radice del plugin, non all'interno di `.claude-plugin/`.

678</Warning>680</Warning>

679 681

682Un file `CLAUDE.md` nella radice del plugin non viene caricato come contesto del progetto. I plugin contribuiscono al contesto attraverso skills, agents e hooks piuttosto che tramite CLAUDE.md. Per fornire istruzioni che si carichino nel contesto di Claude, inseritele in uno [skill](#skills).

683

680### Riferimento delle posizioni dei file684### Riferimento delle posizioni dei file

681 685

security.md +1 −1

Details

27* **Strumento bash in sandbox**: [Sandbox](/it/sandboxing) comandi bash con isolamento del filesystem e della rete, riducendo i prompt di permesso mantenendo la sicurezza. Abilita con `/sandbox` per definire i confini dove Claude Code può lavorare autonomamente27* **Strumento bash in sandbox**: [Sandbox](/it/sandboxing) comandi bash con isolamento del filesystem e della rete, riducendo i prompt di permesso mantenendo la sicurezza. Abilita con `/sandbox` per definire i confini dove Claude Code può lavorare autonomamente

28* **Restrizione dell'accesso in scrittura**: Claude Code può scrivere solo nella cartella in cui è stato avviato e nelle sue sottocartelle, non può modificare file nelle directory padre senza autorizzazione esplicita. Mentre Claude Code può leggere file al di fuori della directory di lavoro (utile per accedere alle librerie di sistema e alle dipendenze), le operazioni di scrittura sono strettamente limitate all'ambito del progetto, creando un chiaro confine di sicurezza28* **Restrizione dell'accesso in scrittura**: Claude Code può scrivere solo nella cartella in cui è stato avviato e nelle sue sottocartelle, non può modificare file nelle directory padre senza autorizzazione esplicita. Mentre Claude Code può leggere file al di fuori della directory di lavoro (utile per accedere alle librerie di sistema e alle dipendenze), le operazioni di scrittura sono strettamente limitate all'ambito del progetto, creando un chiaro confine di sicurezza

29* **Mitigazione dell'affaticamento da prompt**: Supporto per l'allowlisting di comandi sicuri utilizzati frequentemente per utente, per codebase o per organizzazione29* **Mitigazione dell'affaticamento da prompt**: Supporto per l'allowlisting di comandi sicuri utilizzati frequentemente per utente, per codebase o per organizzazione

~~30* **Modalità Accept Edits**: Accetta in batch più modifiche mantenendo i prompt di permesso per i comandi con effetti collaterali~~30* **Modalità Accept Edits**: Approva automaticamente le modifiche ai file e un insieme fisso di comandi Bash del filesystem come `mkdir`, `touch`, `rm`, `mv`, `cp` e `sed` per i percorsi nella directory di lavoro. Gli altri comandi Bash e i percorsi fuori ambito richiedono comunque l'approvazione

31 31

32### Responsabilità dell'utente32### Responsabilità dell'utente

33 33

settings.md +26 −3

Details

73 73

74Su Windows, i percorsi mostrati come `~/.claude` si risolvono in `%USERPROFILE%\.claude`.

74***76***

75 77

76## File di impostazioni78## File di impostazioni

166| `apiKeyHelper` | Script personalizzato, da eseguire in `/bin/sh`, per generare un valore di autenticazione. Questo valore verrà inviato come intestazioni `X-Api-Key` e `Authorization: Bearer` per le richieste di modello | `/bin/generate_temp_api_key.sh` |168| `apiKeyHelper` | Script personalizzato, da eseguire in `/bin/sh`, per generare un valore di autenticazione. Questo valore verrà inviato come intestazioni `X-Api-Key` e `Authorization: Bearer` per le richieste di modello | `/bin/generate_temp_api_key.sh` |

167| `attribution` | Personalizza l'attribuzione per i commit git e le pull request. Vedi [Impostazioni di attribuzione](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |169| `attribution` | Personalizza l'attribuzione per i commit git e le pull request. Vedi [Impostazioni di attribuzione](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

168| `autoMemoryDirectory` | Directory personalizzata per l'archiviazione della [memoria automatica](/it/memory#storage-location). Accetta un percorso assoluto o un percorso con prefisso `~/`. Accettato dalle impostazioni di politica e utente, e dal flag `--settings`. Non accettato dalle impostazioni di progetto o locale, poiché un repository clonato potrebbe fornire uno dei due file per reindirizzare le scritture di memoria a posizioni sensibili | `"~/my-memory-dir"` |170| `autoMemoryDirectory` | Directory personalizzata per l'archiviazione della [memoria automatica](/it/memory#storage-location). Accetta un percorso assoluto o un percorso con prefisso `~/`. Accettato dalle impostazioni di politica e utente, e dal flag `--settings`. Non accettato dalle impostazioni di progetto o locale, poiché un repository clonato potrebbe fornire uno dei due file per reindirizzare le scritture di memoria a posizioni sensibili | `"~/my-memory-dir"` |

171| `autoMemoryEnabled` | Abilita la [memoria automatica](/it/memory#enable-or-disable-auto-memory). Quando `false`, Claude non legge da o scrive nella directory di memoria automatica. Predefinito: `true`. Puoi anche attivare/disattivare questo con `/memory` durante una sessione | `false` |

169| `autoMode` | Personalizza cosa il classificatore della [modalità auto](/it/permission-modes#eliminate-prompts-with-auto-mode) blocca e consente. Contiene array `environment`, `allow` e `soft_deny` di regole in prosa. Includi la stringa letterale `"$defaults"` in un array per ereditare le regole incorporate in quella posizione. Vedi [Configura la modalità auto](/it/auto-mode-config). Non letto dalle impostazioni di progetto condivise | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |172| `autoMode` | Personalizza cosa il classificatore della [modalità auto](/it/permission-modes#eliminate-prompts-with-auto-mode) blocca e consente. Contiene array `environment`, `allow` e `soft_deny` di regole in prosa. Includi la stringa letterale `"$defaults"` in un array per ereditare le regole incorporate in quella posizione. Vedi [Configura la modalità auto](/it/auto-mode-config). Non letto dalle impostazioni di progetto condivise | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

170| `autoScrollEnabled` | Nel [rendering fullscreen](/it/fullscreen), segui il nuovo output fino al fondo della conversazione. Predefinito: `true`. Appare in `/config` come **Auto-scroll**. I prompt di permesso scorrono comunque in vista quando questo è disattivato | `false` |173| `autoScrollEnabled` | Nel [rendering fullscreen](/it/fullscreen), segui il nuovo output fino al fondo della conversazione. Predefinito: `true`. Appare in `/config` come **Auto-scroll**. I prompt di permesso scorrono comunque in vista quando questo è disattivato | `false` |

171| `autoUpdatesChannel` | Canale di rilascio da seguire per gli aggiornamenti. Usa `"stable"` per una versione che è tipicamente circa una settimana vecchia e salta le versioni con regressioni importanti, o `"latest"` (predefinito) per il rilascio più recente | `"stable"` |174| `autoUpdatesChannel` | Canale di rilascio da seguire per gli aggiornamenti. Usa `"stable"` per una versione che è tipicamente circa una settimana vecchia e salta le versioni con regressioni importanti, o `"latest"` (predefinito) per il rilascio più recente | `"stable"` |

174| `awsAuthRefresh` | Script personalizzato che modifica la directory `.aws` (vedi [configurazione avanzata delle credenziali](/it/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |177| `awsAuthRefresh` | Script personalizzato che modifica la directory `.aws` (vedi [configurazione avanzata delle credenziali](/it/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |

175| `awsCredentialExport` | Script personalizzato che restituisce JSON con le credenziali AWS (vedi [configurazione avanzata delle credenziali](/it/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |178| `awsCredentialExport` | Script personalizzato che restituisce JSON con le credenziali AWS (vedi [configurazione avanzata delle credenziali](/it/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |

176| `blockedMarketplaces` | (Solo impostazioni gestite) Elenco di negazione delle fonti del marketplace. Applicato all'aggiunta del marketplace e all'installazione, aggiornamento, aggiornamento e auto-aggiornamento del plugin, quindi un marketplace aggiunto prima che la politica fosse impostata non può essere utilizzato per recuperare i plugin. Le fonti bloccate vengono controllate prima del download, quindi non toccano mai il filesystem. Vedi [Restrizioni del marketplace gestito](/it/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |179| `blockedMarketplaces` | (Solo impostazioni gestite) Elenco di negazione delle fonti del marketplace. Applicato all'aggiunta del marketplace e all'installazione, aggiornamento, aggiornamento e auto-aggiornamento del plugin, quindi un marketplace aggiunto prima che la politica fosse impostata non può essere utilizzato per recuperare i plugin. Le fonti bloccate vengono controllate prima del download, quindi non toccano mai il filesystem. Vedi [Restrizioni del marketplace gestito](/it/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

177| `channelsEnabled` | (Solo impostazioni gestite) Consenti [channels](/it/channels) per gli utenti Team e Enterprise. Non impostato o `false` blocca la consegna dei messaggi del canale indipendentemente da cosa gli utenti passano a `--channels` | `true` |180| `channelsEnabled` | (Solo impostazioni gestite) Consenti [channels](/it/channels) per l'organizzazione. Nei piani Team e Enterprise di claude.ai, i canali vengono bloccati quando questo non è impostato o è `false`. Per gli account [Anthropic Console](/it/authentication#claude-console-authentication) che utilizzano l'autenticazione con chiave API, i canali sono consentiti per impostazione predefinita a meno che la tua organizzazione non distribuisca impostazioni gestite, nel qual caso questa chiave deve essere impostata a `true` | `true` |

178| `cleanupPeriodDays` | I file di sessione più vecchi di questo periodo vengono eliminati all'avvio (predefinito: 30 giorni, minimo 1). L'impostazione a `0` viene rifiutata con un errore di convalida. Controlla anche il limite di età per la rimozione automatica dei [worktrees subagent orfani](/it/worktrees#clean-up-worktrees) all'avvio. Per disabilitare completamente le scritture di trascritti, imposta la variabile di ambiente [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/it/env-vars), o in modalità non interattiva (`-p`) usa il flag `--no-session-persistence` o l'opzione SDK `persistSession: false`. | `20` |181| `cleanupPeriodDays` | I file di sessione più vecchi di questo periodo vengono eliminati all'avvio (predefinito: 30 giorni, minimo 1). L'impostazione a `0` viene rifiutata con un errore di convalida. Controlla anche il limite di età per la rimozione automatica dei [worktrees subagent orfani](/it/worktrees#clean-up-worktrees) all'avvio. Per disabilitare completamente le scritture di trascritti, imposta la variabile di ambiente [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/it/env-vars), o in modalità non interattiva (`-p`) usa il flag `--no-session-persistence` o l'opzione SDK `persistSession: false`. | `20` |

179| `companyAnnouncements` | Annuncio da visualizzare agli utenti all'avvio. Se vengono forniti più annunci, verranno alternati casualmente. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |182| `companyAnnouncements` | Annuncio da visualizzare agli utenti all'avvio. Se vengono forniti più annunci, verranno alternati casualmente. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |

180| `defaultShell` | Shell predefinita per i comandi `!` della casella di input. Accetta `"bash"` (predefinito) o `"powershell"`. L'impostazione a `"powershell"` instrada i comandi `!` interattivi tramite PowerShell su Windows. Richiede `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. Vedi [Strumento PowerShell](/it/tools-reference#powershell-tool) | `"powershell"` |183| `defaultShell` | Shell predefinita per i comandi `!` della casella di input. Accetta `"bash"` (predefinito) o `"powershell"`. L'impostazione a `"powershell"` instrada i comandi `!` interattivi tramite PowerShell su Windows. Richiede `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. Vedi [Strumento PowerShell](/it/tools-reference#powershell-tool) | `"powershell"` |

183| `disableAutoMode` | Imposta a `"disable"` per prevenire l'attivazione della [modalità auto](/it/permission-modes#eliminate-prompts-with-auto-mode). Rimuove `auto` dal ciclo `Shift+Tab` e rifiuta `--permission-mode auto` all'avvio. Molto utile nelle [impostazioni gestite](/it/permissions#managed-settings) dove gli utenti non possono ignorarla | `"disable"` |186| `disableAutoMode` | Imposta a `"disable"` per prevenire l'attivazione della [modalità auto](/it/permission-modes#eliminate-prompts-with-auto-mode). Rimuove `auto` dal ciclo `Shift+Tab` e rifiuta `--permission-mode auto` all'avvio. Molto utile nelle [impostazioni gestite](/it/permissions#managed-settings) dove gli utenti non possono ignorarla | `"disable"` |

184| `disableDeepLinkRegistration` | Imposta a `"disable"` per prevenire che Claude Code registri il gestore del protocollo `claude-cli://` con il sistema operativo all'avvio. I [deep link](/it/deep-links) consentono agli strumenti esterni di aprire una sessione di Claude Code con un prompt pre-compilato. Utile negli ambienti in cui la registrazione del gestore del protocollo è limitata o gestita separatamente | `"disable"` |187| `disableDeepLinkRegistration` | Imposta a `"disable"` per prevenire che Claude Code registri il gestore del protocollo `claude-cli://` con il sistema operativo all'avvio. I [deep link](/it/deep-links) consentono agli strumenti esterni di aprire una sessione di Claude Code con un prompt pre-compilato. Utile negli ambienti in cui la registrazione del gestore del protocollo è limitata o gestita separatamente | `"disable"` |

189| `disableRemoteControl` | {/* min-version: 2.1.128 */}Disabilita il [Controllo remoto](/it/remote-control): blocca `claude remote-control`, il flag `--remote-control`, l'avvio automatico e l'interruttore in-sessione. Tipicamente posizionato nelle [impostazioni gestite](/it/permissions#managed-settings) per l'applicazione MDM per dispositivo, ma funziona da qualsiasi ambito. Richiede Claude Code v2.1.128 o successivo | `true` |

186| `disableSkillShellExecution` | Disabilita l'esecuzione inline della shell per i blocchi `` !`...` `` e ` ```! ` nei [skills](/it/skills) e nei comandi personalizzati da fonti utente, progetto, plugin o directory aggiuntive. I comandi vengono sostituiti con `[shell command execution disabled by policy]` invece di essere eseguiti. I skills bundled e gestiti non sono interessati. Molto utile nelle [impostazioni gestite](/it/permissions#managed-settings) dove gli utenti non possono ignorarla | `true` |190| `disableSkillShellExecution` | Disabilita l'esecuzione inline della shell per i blocchi `` !`...` `` e ` ```! ` nei [skills](/it/skills) e nei comandi personalizzati da fonti utente, progetto, plugin o directory aggiuntive. I comandi vengono sostituiti con `[shell command execution disabled by policy]` invece di essere eseguiti. I skills bundled e gestiti non sono interessati. Molto utile nelle [impostazioni gestite](/it/permissions#managed-settings) dove gli utenti non possono ignorarla | `true` |

187| `editorMode` | Modalità di scorciatoie da tastiera per il prompt di input: `"normal"` o `"vim"`. Predefinito: `"normal"`. Appare in `/config` come **Editor mode** | `"vim"` |191| `editorMode` | Modalità di scorciatoie da tastiera per il prompt di input: `"normal"` o `"vim"`. Predefinito: `"normal"`. Appare in `/config` come **Editor mode** | `"vim"` |

188| `effortLevel` | Persisti il [livello di sforzo](/it/model-config#adjust-effort-level) tra le sessioni. Accetta `"low"`, `"medium"`, `"high"`, o `"xhigh"`. Scritto automaticamente quando esegui `/effort` con uno di questi valori. Vedi [Regola il livello di sforzo](/it/model-config#adjust-effort-level) per i modelli supportati | `"xhigh"` |192| `effortLevel` | Persisti il [livello di sforzo](/it/model-config#adjust-effort-level) tra le sessioni. Accetta `"low"`, `"medium"`, `"high"`, o `"xhigh"`. Scritto automaticamente quando esegui `/effort` con uno di questi valori. Vedi [Regola il livello di sforzo](/it/model-config#adjust-effort-level) per i modelli supportati | `"xhigh"` |

550 },554 },

551 "extraKnownMarketplaces": {555 "extraKnownMarketplaces": {

552 "acme-tools": {556 "acme-tools": {

557 "source": {

553 "source": "github",558 "source": "github",

554 "repo": "acme-corp/claude-plugins"559 "repo": "acme-corp/claude-plugins"

555 }560 }

556 }561 }

562 }

557}563}

558```564```

559 565

568* **Impostazioni locali** (`.claude/settings.local.json`): Override per macchina (non committati)574* **Impostazioni locali** (`.claude/settings.local.json`): Override per macchina (non committati)

569* **Impostazioni gestite** (`managed-settings.json`): Override della politica a livello organizzativo che blocca l'installazione in tutti gli ambiti e nasconde il plugin dal marketplace575* **Impostazioni gestite** (`managed-settings.json`): Override della politica a livello organizzativo che blocca l'installazione in tutti gli ambiti e nasconde il plugin dal marketplace

570 576

577<Note>

578 Le impostazioni di progetto hanno la precedenza sulle impostazioni utente, quindi impostare un plugin su `false` in `~/.claude/settings.json` non disabilita un plugin che le impostazioni `.claude/settings.json` del progetto abilitano. Per rinunciare a un plugin abilitato dal progetto sulla tua macchina, impostalo su `false` in `.claude/settings.local.json` invece.

579

580 I plugin forzatamente abilitati dalle impostazioni gestite non possono essere disabilitati in questo modo, poiché le impostazioni gestite ignorano le impostazioni locali.

581</Note>

582

571**Esempio**:583**Esempio**:

572 584

573```json theme={null}585```json theme={null}

659* Disponibile solo nelle impostazioni gestite (`managed-settings.json`)671* Disponibile solo nelle impostazioni gestite (`managed-settings.json`)

660* Non può essere ignorato da impostazioni utente o di progetto (precedenza più alta)672* Non può essere ignorato da impostazioni utente o di progetto (precedenza più alta)

661* Applicato PRIMA delle operazioni di rete/filesystem (le fonti bloccate non vengono mai eseguite)673* Applicato PRIMA delle operazioni di rete/filesystem (le fonti bloccate non vengono mai eseguite)

662* Utilizza la corrispondenza esatta per le specifiche della fonte (incluso `ref`, `path` per le fonti git), tranne `hostPattern`, che utilizza la corrispondenza regex674* Utilizza la corrispondenza esatta per le specifiche della fonte (incluso `ref`, `path` per le fonti git), tranne `hostPattern` e `pathPattern`, che utilizzano la corrispondenza regex

663 675

664**Comportamento dell'elenco di autorizzazione**:676**Comportamento dell'elenco di autorizzazione**:

665 677

669 681

670**Tutti i tipi di fonte supportati**:682**Tutti i tipi di fonte supportati**:

671 683

672L'elenco di autorizzazione supporta più tipi di fonte del marketplace. La maggior parte delle fonti utilizza la corrispondenza esatta, mentre `hostPattern` utilizza la corrispondenza regex rispetto all'host del marketplace.684L'elenco di autorizzazione supporta più tipi di fonte del marketplace. La maggior parte delle fonti utilizza la corrispondenza esatta, mentre `hostPattern` e `pathPattern` utilizzano la corrispondenza regex rispetto all'host del marketplace e al percorso del filesystem rispettivamente.

673 685

6741. **Repository GitHub**:6861. **Repository GitHub**:

675 687

749* `url`: estrae il nome host dall'URL761* `url`: estrae il nome host dall'URL

750* `npm`, `file`, `directory`: non supportati per la corrispondenza del modello host762* `npm`, `file`, `directory`: non supportati per la corrispondenza del modello host

751 763

7648. **Corrispondenza del modello di percorso**:

765

766```json theme={null}

767{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }

768{ "source": "pathPattern", "pathPattern": ".*" }

769```

770

771Campi: `pathPattern` (obbligatorio: modello regex abbinato al campo `path` delle fonti `file` e `directory`)

772

773Utilizza la corrispondenza del modello di percorso per consentire marketplace basati su filesystem insieme alle restrizioni `hostPattern` per le fonti di rete. Imposta `".*"` per consentire tutti i percorsi locali, o un modello più ristretto per limitare a directory specifiche.

774

752**Esempi di configurazione**:775**Esempi di configurazione**:

753 776

754Esempio: consenti solo marketplace specifici:777Esempio: consenti solo marketplace specifici:

sub-agents.md +35 −10

Details

51 </Tab>51 </Tab>

52 52

53 <Tab title="Plan">53 <Tab title="Plan">

~~54 Un agente di ricerca utilizzato durante la [plan mode](/it/common-workflows#use-plan-mode-for-safe-code-analysis) per raccogliere contesto prima di presentare un piano.~~54 Un agente di ricerca utilizzato durante la [plan mode](/it/permission-modes#analyze-before-you-edit-with-plan-mode) per raccogliere contesto prima di presentare un piano.

55 55

56 * **Model**: Eredita dalla conversazione principale56 * **Model**: Eredita dalla conversazione principale

57 * **Tools**: Strumenti di sola lettura (accesso negato agli strumenti Write e Edit)57 * **Tools**: Strumenti di sola lettura (accesso negato agli strumenti Write e Edit)

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

80 </Tab>80 </Tab>

81</Tabs>81</Tabs>

82 82

180 180

181I **subagent definiti da CLI** vengono passati come JSON quando avvia Claude Code. Esistono solo per quella sessione e non vengono salvati su disco, rendendoli utili per test rapidi o script di automazione. Può definire più subagent in una singola chiamata `--agents`:181I **subagent definiti da CLI** vengono passati come JSON quando avvia Claude Code. Esistono solo per quella sessione e non vengono salvati su disco, rendendoli utili per test rapidi o script di automazione. Può definire più subagent in una singola chiamata `--agents`:

182 182

183```bash theme={null}183<Tabs>

184claude --agents '{184 <Tab title="macOS, Linux, WSL">

185 ```bash theme={null}

186 claude --agents '{

185 "code-reviewer": {187 "code-reviewer": {

186 "description": "Expert code reviewer. Use proactively after code changes.",188 "description": "Expert code reviewer. Use proactively after code changes.",

187 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",189 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",

192 "description": "Debugging specialist for errors and test failures.",194 "description": "Debugging specialist for errors and test failures.",

193 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."195 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."

194 }196 }

195}'197 }'

196```198 ```

199 </Tab>

200

201 <Tab title="Windows PowerShell">

202 ```powershell theme={null}

203 claude --agents @'

204 {

205 "code-reviewer": {

206 "description": "Expert code reviewer. Use proactively after code changes.",

207 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",

208 "tools": ["Read", "Grep", "Glob", "Bash"],

209 "model": "sonnet"

210 },

211 "debugger": {

212 "description": "Debugging specialist for errors and test failures.",

213 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."

214 }

215 }

216 '@

217 ```

218 </Tab>

219</Tabs>

197 220

198Il flag `--agents` accetta JSON con gli stessi campi [frontmatter](#supported-frontmatter-fields) dei subagent basati su file: `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `isolation` e `color`. Usi `prompt` per il prompt di sistema, equivalente al corpo markdown nei subagent basati su file.221Il flag `--agents` accetta JSON con gli stessi campi [frontmatter](#supported-frontmatter-fields) dei subagent basati su file: `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `isolation` e `color`. Usi `prompt` per il prompt di sistema, equivalente al corpo markdown nei subagent basati su file.

199 222

212I file subagent utilizzano frontmatter YAML per la configurazione, seguito dal prompt di sistema in Markdown:235I file subagent utilizzano frontmatter YAML per la configurazione, seguito dal prompt di sistema in Markdown:

213 236

214<Note>237<Note>

215 I subagent vengono caricati all'avvio della sessione. Se crea un subagent aggiungendo manualmente un file, riavvii la sua sessione o usi `/agents` per caricarlo immediatamente.238 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.

216</Note>239</Note>

217 240

218```markdown theme={null}241```markdown theme={null}

250| `memory` | No | [Ambito di memoria persistente](#enable-persistent-memory): `user`, `project`, o `local`. Abilita l'apprendimento tra sessioni |273| `memory` | No | [Ambito di memoria persistente](#enable-persistent-memory): `user`, `project`, o `local`. Abilita l'apprendimento tra sessioni |

251| `background` | No | Imposta su `true` per eseguire sempre questo subagent come [background task](#run-subagents-in-foreground-or-background). Predefinito: `false` |274| `background` | No | Imposta su `true` per eseguire sempre questo subagent come [background task](#run-subagents-in-foreground-or-background). Predefinito: `false` |

252| `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 |275| `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 |

253| `isolation` | No | Imposta su `worktree` per eseguire il subagent in un [git worktree](/it/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) temporaneo, dandogli una copia isolata del repository. Il worktree viene automaticamente pulito se il subagent non apporta modifiche |276| `isolation` | No | Imposta su `worktree` per eseguire il subagent in un [git worktree](/it/worktrees) temporaneo, dandogli una copia isolata del repository. Il worktree viene automaticamente pulito se il subagent non apporta modifiche |

254| `color` | No | Colore di visualizzazione per il subagent nell'elenco attività e nella trascrizione. Accetta `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, o `cyan` |277| `color` | No | Colore di visualizzazione per il subagent nell'elenco attività e nella trascrizione. Accetta `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, o `cyan` |

255| `initialPrompt` | No | Auto-inviato come primo turno utente quando questo agente viene eseguito come agente della sessione principale (tramite `--agent` o l'impostazione `agent`). [Commands](/it/commands) e [skills](/it/skills) vengono elaborati. Anteposto a qualsiasi prompt fornito dall'utente |278| `initialPrompt` | No | Auto-inviato come primo turno utente quando questo agente viene eseguito come agente della sessione principale (tramite `--agent` o l'impostazione `agent`). [Commands](/it/commands) e [skills](/it/skills) vengono elaborati. Anteposto a qualsiasi prompt fornito dall'utente |

256 279

484exit 0507exit 0

485```508```

486 509

487Consulti [Hook input](/it/hooks#pretooluse-input) per lo schema di input completo e [exit codes](/it/hooks#exit-code-output) per come i codici di uscita influenzano il comportamento.510Consulti [Hook input](/it/hooks#pretooluse-input) per lo schema di input completo e [exit codes](/it/hooks#exit-code-output) per come i codici di uscita influenzano il comportamento. Su Windows, scriva gli script dell'hook in PowerShell e aggiunga `shell: powershell` alla voce dell'hook come mostrato in [running hooks in PowerShell](/it/hooks#windows-powershell-tool).

488 511

489#### Disabiliti subagent specifici512#### Disabiliti subagent specifici

490 513

994exit 01017exit 0

995```1018```

996 1019

997Renda lo script eseguibile:1020Su macOS e Linux, renda lo script eseguibile:

998 1021

999```bash theme={null}1022```bash theme={null}

1000chmod +x ./scripts/validate-readonly-query.sh1023chmod +x ./scripts/validate-readonly-query.sh

1001```1024```

1002 1025

1026Su Windows, scriva lo script di convalida in PowerShell e aggiunga `shell: powershell` alla voce dell'hook. Consulti [esecuzione degli hook in PowerShell](/it/hooks#windows-powershell-tool).

1027

1003L'hook riceve JSON tramite stdin con il comando Bash in `tool_input.command`. Il codice di uscita 2 blocca l'operazione e alimenta il messaggio di errore a Claude. Consulti [Hooks](/it/hooks#exit-code-output) per i dettagli sui codici di uscita e [Hook input](/it/hooks#pretooluse-input) per lo schema di input completo.1028L'hook riceve JSON tramite stdin con il comando Bash in `tool_input.command`. Il codice di uscita 2 blocca l'operazione e alimenta il messaggio di errore a Claude. Consulti [Hooks](/it/hooks#exit-code-output) per i dettagli sui codici di uscita e [Hook input](/it/hooks#pretooluse-input) per lo schema di input completo.

1004 1029

1005## Passaggi successivi1030## Passaggi successivi

vs-code.md +13 −3

Details

95* **Modalità di permesso**: fai clic sull'indicatore di modalità in fondo alla casella dei prompt per cambiare modalità. In modalità normale, Claude chiede il permesso prima di ogni azione. In Plan Mode, Claude descrive cosa farà e attende l'approvazione prima di apportare modifiche. VS Code apre automaticamente il piano come documento markdown completo dove puoi aggiungere commenti inline per fornire feedback prima che Claude inizi. In modalità auto-accept, Claude apporta modifiche senza chiedere. Imposta il valore predefinito nelle impostazioni di VS Code in `claudeCode.initialPermissionMode`.95* **Modalità di permesso**: fai clic sull'indicatore di modalità in fondo alla casella dei prompt per cambiare modalità. In modalità normale, Claude chiede il permesso prima di ogni azione. In Plan Mode, Claude descrive cosa farà e attende l'approvazione prima di apportare modifiche. VS Code apre automaticamente il piano come documento markdown completo dove puoi aggiungere commenti inline per fornire feedback prima che Claude inizi. In modalità auto-accept, Claude apporta modifiche senza chiedere. Imposta il valore predefinito nelle impostazioni di VS Code in `claudeCode.initialPermissionMode`.

96* **Menu dei comandi**: fai clic su `/` o digita `/` per aprire il menu dei comandi. Le opzioni includono l'allegato di file, il cambio di modelli, l'attivazione del pensiero esteso, la visualizzazione dell'utilizzo del piano (`/usage`) e l'avvio di una sessione [Remote Control](/it/remote-control) (`/remote-control`). La sezione Personalizza fornisce accesso ai server MCP, hooks, memoria, autorizzazioni e plugin. Gli elementi con un'icona del terminale si aprono nel terminale integrato.96* **Menu dei comandi**: fai clic su `/` o digita `/` per aprire il menu dei comandi. Le opzioni includono l'allegato di file, il cambio di modelli, l'attivazione del pensiero esteso, la visualizzazione dell'utilizzo del piano (`/usage`) e l'avvio di una sessione [Remote Control](/it/remote-control) (`/remote-control`). La sezione Personalizza fornisce accesso ai server MCP, hooks, memoria, autorizzazioni e plugin. Gli elementi con un'icona del terminale si aprono nel terminale integrato.

97* **Indicatore di contesto**: la casella dei prompt mostra quanto della finestra di contesto di Claude stai utilizzando. Claude si compatta automaticamente quando necessario, oppure puoi eseguire `/compact` manualmente.97* **Indicatore di contesto**: la casella dei prompt mostra quanto della finestra di contesto di Claude stai utilizzando. Claude si compatta automaticamente quando necessario, oppure puoi eseguire `/compact` manualmente.

98* **Pensiero esteso**: consente a Claude di dedicare più tempo al ragionamento su problemi complessi. Attivalo tramite il menu dei comandi (`/`). Il ragionamento di Claude appare nella conversazione come blocchi compressi: fai clic su un blocco per leggerlo, oppure premi `Ctrl+O` per espandere o comprimere ogni blocco di pensiero nella sessione. Consulta [Pensiero esteso](/it/common-workflows#use-extended-thinking-thinking-mode) per i dettagli.98* **Pensiero esteso**: consente a Claude di dedicare più tempo al ragionamento su problemi complessi. Attivalo tramite il menu dei comandi (`/`). Il ragionamento di Claude appare nella conversazione come blocchi compressi: fai clic su un blocco per leggerlo, oppure premi `Ctrl+O` per espandere o comprimere ogni blocco di pensiero nella sessione. Consulta [Pensiero esteso](/it/model-config#extended-thinking) per i dettagli.

99* **Input multi-riga**: premi `Shift+Enter` per aggiungere una nuova riga senza inviare. Funziona anche nell'input di testo libero "Altro" dei dialoghi delle domande.99* **Input multi-riga**: premi `Shift+Enter` per aggiungere una nuova riga senza inviare. Funziona anche nell'input di testo libero "Altro" dei dialoghi delle domande.

100 100

101### Riferisci file e cartelle101### Riferisci file e cartelle

115 115

116### Riprendi conversazioni passate116### Riprendi conversazioni passate

117 117

118Fai clic sul pulsante **Cronologia sessioni** in cima al pannello Claude Code per accedere alla cronologia delle conversazioni. Puoi cercare per parola chiave o sfogliare per tempo (Oggi, Ieri, Ultimi 7 giorni, ecc.). Fai clic su qualsiasi conversazione per riprenderla con la cronologia completa dei messaggi. Le nuove sessioni ricevono titoli generati dall'IA in base al tuo primo messaggio. Passa il mouse su una sessione per rivelare le azioni di rinomina e rimozione: rinomina per darle un titolo descrittivo, o rimuovi per eliminarla dall'elenco. Per ulteriori informazioni sulla ripresa delle sessioni, consulta [Flussi di lavoro comuni](/it/common-workflows#resume-previous-conversations).118Fai clic sul pulsante **Cronologia sessioni** in cima al pannello Claude Code per accedere alla cronologia delle conversazioni. Puoi cercare per parola chiave o sfogliare per tempo (Oggi, Ieri, Ultimi 7 giorni, ecc.). Fai clic su qualsiasi conversazione per riprenderla con la cronologia completa dei messaggi. Le nuove sessioni ricevono titoli generati dall'IA in base al tuo primo messaggio. Passa il mouse su una sessione per rivelare le azioni di rinomina e rimozione: rinomina per darle un titolo descrittivo, o rimuovi per eliminarla dall'elenco. Per ulteriori informazioni sulla ripresa delle sessioni, consulta [Gestisci sessioni](/it/sessions).

119 119

120### Riprendi sessioni remote da Claude.ai120### Riprendi sessioni remote da Claude.ai

121 121

399claude --worktree feature-auth399claude --worktree feature-auth

400```400```

401 401

402Ogni worktree mantiene uno stato di file indipendente mentre condivide la cronologia di git. Ciò impedisce alle istanze di Claude di interferire l'una con l'altra quando lavorano su diversi compiti. Per ulteriori dettagli, consulta [Esegui sessioni parallele di Claude Code con Git worktrees](/it/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees).402Ogni worktree mantiene uno stato di file indipendente mentre condivide la cronologia di git. Ciò impedisce alle istanze di Claude di interferire l'una con l'altra quando lavorano su diversi compiti. Per ulteriori dettagli, consulta [Esegui sessioni parallele con Git worktrees](/it/worktrees).

403 403

404## Usa provider di terze parti404## Usa provider di terze parti

405 405

476 476

477In alternativa, fai clic su "✱ Claude Code" nella **Barra di stato** (angolo in basso a destra). Funziona anche senza un file aperto. Puoi anche usare la **Tavolozza dei comandi** (`Cmd+Shift+P` / `Ctrl+Shift+P`) e digitare "Claude Code".477In alternativa, fai clic su "✱ Claude Code" nella **Barra di stato** (angolo in basso a destra). Funziona anche senza un file aperto. Puoi anche usare la **Tavolozza dei comandi** (`Cmd+Shift+P` / `Ctrl+Shift+P`) e digitare "Claude Code".

478 478

479### Cmd+Esc non fa nulla su macOS

480

481Su macOS Tahoe e versioni successive, la scorciatoia di sistema Game Overlay è associata a `Cmd+Esc` per impostazione predefinita e intercetta la pressione del tasto prima che raggiunga VS Code. Per liberare la scorciatoia:

482

4831. Apri Impostazioni di sistema

4842. Vai a Tastiera, quindi Scorciatoie da tastiera, quindi Controller di gioco

4853. Deseleziona la casella di controllo Game Overlay

486

487In alternativa, riassegna l'estensione a un tasto diverso: apri l'editor [Scorciatoie da tastiera](https://code.visualstudio.com/docs/configure/keybindings) di VS Code (`Cmd+K Cmd+S`), cerca `Claude Code: Focus input` e assegna una nuova associazione.

488

479### Claude Code non risponde mai489### Claude Code non risponde mai

480 490

481Se Claude Code non risponde ai tuoi prompt:491Se Claude Code non risponde ai tuoi prompt:

Documentation 2026-05-04 22:58 UTC to 2026-05-05 23:00 UTC