200| :- | :- | :- | :- |200| :- | :- | :- | :- |
201| `title` | `string` | `undefined` | Titolo leggibile per lo strumento |201| `title` | `string` | `undefined` | Titolo leggibile per lo strumento |
202| `readOnlyHint` | `boolean` | `false` | Se `true`, lo strumento non modifica il suo ambiente |202| `readOnlyHint` | `boolean` | `false` | Se `true`, lo strumento non modifica il suo ambiente |
203| `destructiveHint` | `boolean` | `true` | Se `true`, lo strumento può eseguire aggiornamenti distruttivi (significativo solo quando `readOnlyHint` è `false`) |203| `destructiveHint` | `boolean` | `true` | Se `true`, lo strumento può eseguire aggiornamenti distruttivi. Imposta esplicitamente `destructiveHint: true` su qualsiasi strumento che contrassegni come [`always_ask`](#mcpservertoolpolicy), altrimenti il classificatore della modalità auto può approvare le chiamate a quello strumento al posto della tua callback `canUseTool`. Lasciare `destructiveHint` non impostato non basta, perché Claude Code tratta un `destructiveHint` non impostato come `false` quando gestisce le chiamate `always_ask`, anche se il valore predefinito della specifica MCP è `true` |
204| `idempotentHint` | `boolean` | `false` | Se `true`, le chiamate ripetute con gli stessi argomenti non hanno effetto aggiuntivo (significativo solo quando `readOnlyHint` è `false`) |204| `idempotentHint` | `boolean` | `false` | Se `true`, le chiamate ripetute con gli stessi argomenti non hanno effetto aggiuntivo (significativo solo quando `readOnlyHint` è `false`) |
205| `openWorldHint` | `boolean` | `true` | Se `true`, lo strumento interagisce con entità esterne (ad esempio, ricerca web). Se `false`, il dominio dello strumento è chiuso (ad esempio, uno strumento di memoria) |205| `openWorldHint` | `boolean` | `true` | Se `true`, lo strumento interagisce con entità esterne (ad esempio, ricerca web). Se `false`, il dominio dello strumento è chiuso (ad esempio, uno strumento di memoria) |
206 206
630 ): Promise<SDKControlReadFileResponse | null>;630 ): Promise<SDKControlReadFileResponse | null>;
631 reloadPlugins(options?: {631 reloadPlugins(options?: {
632 holdOnCacheImpact?: boolean;632 holdOnCacheImpact?: boolean;
633 addPlugins?: SdkPluginConfig[];
633 }): Promise<SDKControlReloadPluginsResponse>;634 }): Promise<SDKControlReloadPluginsResponse>;
634 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;635 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;
635 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;636 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;
669| `mcpServerStatus()` | Restituisce lo stato dei server MCP connessi come [`McpServerStatus`](#mcpserverstatus)`[]` |670| `mcpServerStatus()` | Restituisce lo stato dei server MCP connessi come [`McpServerStatus`](#mcpserverstatus)`[]` |
670| `getContextUsage(opts?)` | Restituisce un [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) che scompone l'utilizzo della finestra di contesto della sessione per categoria, skill e strumento. Con il `detail` predefinito, include i dati che `/context` mostra in una sessione interattiva, calcolati con richieste API di conteggio dei token che non compaiono nel flusso dei messaggi; consulta [come vengono gestite queste richieste](#sdkcontrolgetcontextusageresponse). L'[opzione `detail`](#sdkcontrolgetcontextusageresponse) richiede Agent SDK v0.3.257 o successivo |671| `getContextUsage(opts?)` | Restituisce un [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) che scompone l'utilizzo della finestra di contesto della sessione per categoria, skill e strumento. Con il `detail` predefinito, include i dati che `/context` mostra in una sessione interattiva, calcolati con richieste API di conteggio dei token che non compaiono nel flusso dei messaggi; consulta [come vengono gestite queste richieste](#sdkcontrolgetcontextusageresponse). L'[opzione `detail`](#sdkcontrolgetcontextusageresponse) richiede Agent SDK v0.3.257 o successivo |
671| `readFile(path, options?)` | Legge un file dal filesystem della sessione. Claude Code risolve il percorso rispetto a `cwd`; [Cosa può leggere `readFile()`](#what-readfile-can-read) elenca i file che fornisce. Passa `{ maxBytes }` per cambiare il limite di lettura (predefinito 1 MB, massimo 10 MB) e `{ encoding: 'base64' }` per i file binari come le immagini. Si risolve con un [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), oppure con `null` in caso di permesso negato, file mancante o errore di trasporto. Richiede TypeScript SDK v0.2.121 o successivo |672| `readFile(path, options?)` | Legge un file dal filesystem della sessione. Claude Code risolve il percorso rispetto a `cwd`; [Cosa può leggere `readFile()`](#what-readfile-can-read) elenca i file che fornisce. Passa `{ maxBytes }` per cambiare il limite di lettura (predefinito 1 MB, massimo 10 MB) e `{ encoding: 'base64' }` per i file binari come le immagini. Si risolve con un [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), oppure con `null` in caso di permesso negato, file mancante o errore di trasporto. Richiede TypeScript SDK v0.2.121 o successivo |
672| `reloadPlugins(options?)` | Ricarica i plugin dal disco, così che i plugin che installi o modifichi a metà sessione raggiungano la sessione in esecuzione. Si risolve con un [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) che elenca i comandi, i subagent, i plugin e lo stato dei server MCP della sessione. Richiede Agent SDK v0.2.85 o successivo. L'[opzione `holdOnCacheImpact`](#sdkcontrolreloadpluginsresponse) richiede Agent SDK v0.3.268 o successivo |673| `reloadPlugins(options?)` | Ricarica i plugin dal disco, in modo che i plugin che installi o modifichi a metà sessione raggiungano la sessione in esecuzione. Si risolve con un [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) che elenca i comandi, i subagent, i plugin e lo stato dei server MCP della sessione. Richiede Agent SDK v0.2.85 o successive. L'[opzione `holdOnCacheImpact`](#sdkcontrolreloadpluginsresponse) richiede Agent SDK v0.3.268 o successive. L'[opzione `addPlugins`](#load-more-plugin-folders-with-addplugins) richiede Agent SDK v0.3.301 o successive |
673| `reloadSkills()` | Ricarica le skill dal disco, così che le skill che aggiungi o modifichi a metà sessione diventino disponibili per la sessione in esecuzione. Si risolve con un [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) che elenca le skill disponibili dopo il ricaricamento. Richiede Agent SDK v0.3.163 o successivo |674| `reloadSkills()` | Ricarica le skill dal disco, così che le skill che aggiungi o modifichi a metà sessione diventino disponibili per la sessione in esecuzione. Si risolve con un [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) che elenca le skill disponibili dopo il ricaricamento. Richiede Agent SDK v0.3.163 o successivo |
674| `reloadOutputStyles()` | Rilegge gli [stili di output](https://code.claude.com/docs/it/output-styles.md) dal disco, così che un file di stile che aggiungi o modifichi a metà sessione diventi disponibile per la sessione in esecuzione. Si risolve con un [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) che elenca i nomi degli stili disponibili dopo il ricaricamento. Richiede Agent SDK v0.3.261 o successivo |675| `reloadOutputStyles()` | Rilegge gli [stili di output](https://code.claude.com/docs/it/output-styles.md) dal disco, così che un file di stile che aggiungi o modifichi a metà sessione diventi disponibile per la sessione in esecuzione. Si risolve con un [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) che elenca i nomi degli stili disponibili dopo il ricaricamento. Richiede Agent SDK v0.3.261 o successivo |
675| `seedReadState(path, mtime)` | Contrassegna un file come già letto in modo che un Edit successivo non fallisca con `File has not been read yet`. Consulta [`seedReadState()`](#seedreadstate). Richiede TypeScript SDK v0.2.83 o versioni successive |676| `seedReadState(path, mtime)` | Contrassegna un file come già letto in modo che un Edit successivo non fallisca con `File has not been read yet`. Consulta [`seedReadState()`](#seedreadstate). Richiede TypeScript SDK v0.2.83 o versioni successive |
1135 1136
1136`cache_impact` è presente solo insieme a `held: true`. `mcp_servers_added` e `mcp_servers_removed` indicano i server MCP dei plugin che il ricaricamento registrerebbe o eliminerebbe, con nomi con ambito `plugin:<plugin>:<server>`. I nomi sono definiti dagli autori dei plugin, quindi convalidali prima di mostrarli. `lsp_tool_change` indica se l'applicazione aggiungerebbe o rimuoverebbe lo strumento LSP, oppure `null` quando non farebbe nessuna delle due cose. Le forme `may-` indicano che il controllo non è riuscito a vedere completamente l'insieme dei plugin in sospeso.1137`cache_impact` è presente solo insieme a `held: true`. `mcp_servers_added` e `mcp_servers_removed` indicano i server MCP dei plugin che il ricaricamento registrerebbe o eliminerebbe, con nomi con ambito `plugin:<plugin>:<server>`. I nomi sono definiti dagli autori dei plugin, quindi convalidali prima di mostrarli. `lsp_tool_change` indica se l'applicazione aggiungerebbe o rimuoverebbe lo strumento LSP, oppure `null` quando non farebbe nessuna delle due cose. Le forme `may-` indicano che il controllo non è riuscito a vedere completamente l'insieme dei plugin in sospeso.
1137 1138
1139#### Caricare altre cartelle di plugin con `addPlugins`
1140
1141Per caricare cartelle di plugin che non erano nell'opzione [`plugins`](#options) all'avvio, passale a `reloadPlugins()` come `addPlugins`, un elenco di voci [`SdkPluginConfig`](#sdkpluginconfig) il cui `path` è assoluto. Claude Code carica le nuove cartelle e ricarica i plugin esistenti della sessione in un unico passaggio. Anche i server MCP di ogni plugin aggiunto si connettono, a meno che tu non imposti [`skipMcpDiscovery`](#sdkpluginconfig) nella voce di quella cartella. Richiede Agent SDK v0.3.301 o successiva e Claude Code v2.1.301 o successiva.
1142
1143Questo esempio aggiunge una cartella a una query `q` in esecuzione e stampa il percorso di installazione di ogni plugin caricato dalla sessione quando la chiamata restituisce:
1144
1145```typescript theme={null}
1146const result = await q.reloadPlugins({
1147 addPlugins: [{ type: "local", path: "/opt/my-app/plugins/reports" }]
1148});
1149
1150console.log(result.plugins.map((plugin) => plugin.path));
1151```
1152
1153Se la cartella è stata caricata, l'elenco stampato include `/opt/my-app/plugins/reports`, e i comandi e i subagent del plugin compaiono in `result.commands` e `result.agents`.
1154
1155Una cartella aggiunta rimane parte della sessione. Quando chiami di nuovo `reloadPlugins()`, Claude Code la ricarica insieme agli altri plugin e non devi passarla di nuovo in `addPlugins`.
1156
1157##### Quando `reloadPlugins()` non carica le cartelle di `addPlugins`
1158
1159Se `reloadPlugins()` viene rifiutata, nessuna delle cartelle di `addPlugins` viene aggiunta, quindi passale di nuovo in `addPlugins` quando riprovi. Quando il rifiuto ha una delle seguenti cause, la sessione mantiene i plugin che aveva già:
1160
1161* **Un `path` relativo o una voce malformata**: il messaggio di errore indica `add_plugins must be a list of { type: "local", path } entries with absolute paths`. Claude Code rifiuta l'intero elenco per una sola voce errata, quindi passa ogni voce come `{ type: "local", path }` con un `path` assoluto
1162* **Un amministratore ha attivato [`disableSideloadFlags`](https://code.claude.com/docs/it/settings-reference#disablesideloadflags) nelle tue impostazioni gestite**: il messaggio indica `reload_plugins add_plugins is disabled by managed settings (disableSideloadFlags)`. Per caricare la cartella, chiedi a quell'amministratore di rimuovere l'impostazione
1163* **Non è stato possibile ricostruire la [sandbox](https://code.claude.com/docs/it/sandboxing.md)**: con il [sandboxing](#sandboxsettings) attivo, Claude Code ricostruisce la configurazione della sandbox in modo che i comandi shell in sandbox non possano scrivere nelle cartelle che aggiungi. Il messaggio indica `the sandbox could not be rebuilt to keep shell commands out of this folder`. Verifica che le tue [impostazioni della sandbox](#sandboxsettings) formino ancora una configurazione valida
1164
1165Se passi `holdOnCacheImpact` e la chiamata si risolve con [`held: true`](#sdkcontrolreloadpluginsresponse), le cartelle di `addPlugins` non vengono aggiunte. Per aggiungerle comunque, chiama di nuovo `reloadPlugins()` con lo stesso elenco `addPlugins` e senza `holdOnCacheImpact`.
1166
1167Quando la chiamata si risolve senza `held: true` e una cartella manca ancora da `result.plugins`, inizia verificando queste cause:
1168
1169* **La cartella non esiste o il suo plugin non è stato caricato**: `result.error_count` è `1` o superiore. La cartella rimane comunque parte della sessione. Dopo aver corretto la cartella, chiama di nuovo `reloadPlugins()` per caricarla, questa volta senza elencarla in `addPlugins`
1170* **L'eseguibile di Claude Code è precedente alla v2.1.301**: un eseguibile precedente alla v2.1.301 ignora `addPlugins` e ricarica solo i plugin che la sessione aveva già. Controlla `claude_code_version` nel [messaggio init](#sdksystemmessage) ed esegui un eseguibile alla v2.1.301 o successiva
1171
1138### `SDKControlReloadSkillsResponse`1172### `SDKControlReloadSkillsResponse`
1139 1173
1140Tipo restituito da [`reloadSkills()`](#query-object).1174Tipo restituito da [`reloadSkills()`](#query-object).
1430 1464
1431#### `McpSdkServerConfigWithInstance`1465#### `McpSdkServerConfigWithInstance`
1432 1466
1467La configurazione per un server MCP in-process, creato da [`createSdkMcpServer()`](#createsdkmcpserver) ed eseguito all'interno del processo della tua applicazione. È l'oggetto restituito da `createSdkMcpServer()`, più un elenco `tools` facoltativo di voci [`McpServerToolPolicy`](#mcpservertoolpolicy) che aggiungi tu stesso. Per richiedere l'approvazione per le chiamate a uno degli strumenti del server, o per negarle, aggiungi una voce che indichi lo strumento.
1468
1433```typescript theme={null}1469```typescript theme={null}
1434type McpSdkServerConfigWithInstance = {1470type McpSdkServerConfigWithInstance = {
1435 type: "sdk";1471 type: "sdk";
1436 name: string;1472 name: string;
1437 timeout?: number;1473 timeout?: number;
1474 tools?: McpServerToolPolicy[];
1438 instance: McpServer;1475 instance: McpServer;
1439};1476};
1440```1477```
1441 1478
1479Per impostare una policy, espandi l'oggetto restituito da `createSdkMcpServer()` in un nuovo oggetto in `mcpServers` e aggiungi l'elenco `tools` a quel nuovo oggetto. L'opzione `tools` di `createSdkMcpServer()` stessa è un elenco diverso, che contiene le definizioni degli strumenti e non accetta voci di policy. L'elenco delle policy richiede Agent SDK v0.3.301 o successiva, e [`McpServerToolPolicy`](#mcpservertoolpolicy) descrive cosa fa ciascun valore di `permission_policy`.
1480
1481Questo esempio pre-approva ogni strumento del server `records` con un carattere jolly in `allowedTools`, quindi contrassegna `delete_record` come `always_ask` affinché le chiamate a esso vadano comunque a `canUseTool`. Con l'annotazione `destructiveHint: true`, la chiamata raggiunge comunque la callback se la sessione è in esecuzione in modalità `auto`, dove altrimenti il [classificatore](https://code.claude.com/docs/it/permission-modes.md#eliminate-prompts-with-auto-mode) della modalità auto potrebbe approvarla.
1482
1483```typescript theme={null}
1484import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
1485import { z } from "zod";
1486
1487const deleteRecord = tool(
1488 "delete_record",
1489 "Delete a customer record by ID",
1490 { id: z.string() },
1491 async ({ id }) => ({ content: [{ type: "text", text: `Deleted record ${id}` }] }),
1492 { annotations: { destructiveHint: true } }
1493);
1494
1495const records = createSdkMcpServer({ name: "records", tools: [deleteRecord] });
1496
1497for await (const message of query({
1498 prompt: "Delete customer record 42",
1499 options: {
1500 mcpServers: {
1501 // Spread the returned config and add the policy list beside it
1502 records: {
1503 ...records,
1504 tools: [{ name: "delete_record", permission_policy: "always_ask" as const }]
1505 }
1506 },
1507 allowedTools: ["mcp__records__*"],
1508 canUseTool: async (toolName, input) => {
1509 console.log(`Approval requested for ${toolName}`);
1510 return { behavior: "allow", updatedInput: input };
1511 }
1512 }
1513})) {
1514 if (message.type === "result" && message.subtype === "success") {
1515 console.log(message.result);
1516 }
1517}
1518```
1519
1520Quando Claude chiama lo strumento, lo script stampa `Approval requested for mcp__records__delete_record` prima che lo strumento `delete_record` venga eseguito, anche se la voce `allowedTools` avrebbe altrimenti approvato la chiamata.
1521
1522Per modificare o rimuovere la policy di uno strumento mentre la sessione è in esecuzione, passa la configurazione del server con un nuovo valore `tools` a [`setMcpServers()`](#mcpsetserversresult). Il valore `tools` che passi ha effetto dalla successiva chiamata di Claude agli strumenti di quel server:
1523
1524* **Un elenco con voci**: le voci sostituiscono le policy correnti
1525* **Un elenco vuoto**: ogni policy del server viene cancellata
1526* **Nessuna chiave `tools`**: le policy correnti restano
1527
1528Includi in quella chiamata gli altri tuoi server in-process e qualsiasi server aggiunto da una precedente chiamata a `setMcpServers()`, altrimenti la chiamata li disconnette.
1529
1530#### `McpServerToolPolicy`
1531
1532Una voce nell'elenco `tools` di un [`McpSdkServerConfigWithInstance`](#mcpsdkserverconfigwithinstance), che indica uno degli strumenti del server e imposta la policy dei permessi per le chiamate a quello strumento. L'elenco richiede Agent SDK v0.3.301 o successiva e Claude Code v2.1.301 o successiva. Un eseguibile di Claude Code precedente, come un eseguibile a cui punti con `pathToClaudeCodeExecutable`, ignora l'elenco. In quel caso `always_ask` e `always_deny` non vengono applicati, e ogni chiamata passa attraverso il [flusso dei permessi](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated).
1533
1534```typescript theme={null}
1535type McpServerToolPolicy = {
1536 name: string;
1537 permission_policy?: "always_allow" | "always_ask" | "always_deny";
1538 org_max_permission?: "allow" | "ask" | "blocked";
1539};
1540```
1541
1542| Campo | Tipo | Descrizione |
1543| :- | :- | :- |
1544| `name` | `string` | Il nome semplice dello strumento così come passato a [`tool()`](#tool), senza il prefisso `mcp__<server>__` |
1545| `permission_policy` | `'always_allow' \| 'always_ask' \| 'always_deny'` | La policy di approvazione per le chiamate allo strumento, [`always_ask` o `always_deny`](#permission-policy-values). `always_allow` viene ignorato su un server in-process: per pre-approvare uno strumento, elencalo invece in [`allowedTools`](#options) |
1546| `org_max_permission` | `'allow' \| 'ask' \| 'blocked'` | Un limite massimo per strumento impostato da un amministratore dell'organizzazione. Ignorato su un server in-process, quindi lascialo non impostato |
1547
1548##### Valori di `permission_policy`
1549
1550Scegli `always_ask` per approvare tu stesso ogni chiamata, oppure `always_deny` per bloccare completamente lo strumento:
1551
1552* **`always_ask`**: ogni chiamata allo strumento [richiede approvazione](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated), anche se una voce `allowedTools` o una regola allow la copre. La chiamata va alla tua callback `canUseTool` o allo strumento [`permissionPromptToolName`](#options), a meno che non venga risolta prima. Un [mod](https://code.claude.com/docs/it/plugins/mods/overview.md) in un plugin che carichi [può approvarla prima](https://code.claude.com/docs/it/permissions.md#precedence-among-rules-hooks-and-mods). Altrimenti, in modalità `dontAsk` viene negata, e nelle [modalità `auto`, `plan` e `bypassPermissions`](#permission-modes-that-can-approve-an-always_ask-call) può essere approvata prima di raggiungere la tua callback
1553* **`always_deny`**: una chiamata allo strumento [viene negata](https://code.claude.com/docs/it/agent-sdk/permissions.md#how-permissions-are-evaluated) in ogni modalità di permesso, incluso `bypassPermissions`, ma un mod in un plugin che carichi [può comunque approvarla](https://code.claude.com/docs/it/permissions.md#precedence-among-rules-hooks-and-mods)
1554
1555Se non passi né `canUseTool` né `permissionPromptToolName`, oppure imposti [`permissionPrompts`](#options) su `'none'`, una chiamata `always_ask` che non viene risolta prima viene negata, a meno che un [hook `PermissionRequest`](https://code.claude.com/docs/it/hooks#permissionrequest) non la consenta.
1556
1557##### Modalità di permesso che possono approvare una chiamata `always_ask`
1558
1559Nelle modalità `auto`, `plan` e `bypassPermissions`, una chiamata a uno strumento contrassegnato come [`always_ask`](#permission-policy-values) può essere approvata prima di raggiungere la tua callback `canUseTool`. Trova la modalità della tua sessione in questo elenco per vedere quando avviene tale approvazione e cosa impostare affinché la chiamata raggiunga comunque la tua callback:
1560
1561* **`auto`**: il [classificatore](https://code.claude.com/docs/it/permission-modes.md#eliminate-prompts-with-auto-mode) della modalità auto esamina la chiamata e può consentirla. Per fare in modo che ogni chiamata raggiunga la tua callback in modalità `auto`, imposta `destructiveHint: true` nelle [annotazioni](#toolannotations) dello strumento
1562* **`plan`**: finché la [modalità auto è disponibile](https://code.claude.com/docs/it/permission-modes.md#eliminate-prompts-with-auto-mode) per la sessione, le chiamate a uno strumento `always_ask` annotato con `readOnlyHint: true` vanno al classificatore della modalità auto, che può consentirle. Le chiamate ad altri strumenti `always_ask` raggiungono la tua callback. Per fare in modo che anche le chiamate di uno strumento di sola lettura raggiungano la tua callback, aggiungi `destructiveHint: true` alle annotazioni di quello strumento insieme a `readOnlyHint: true`. In alternativa, imposta [`useAutoModeDuringPlan`](https://code.claude.com/docs/it/settings-reference#useautomodeduringplan) su `false`, il che disattiva il classificatore durante la pianificazione
1563* **`bypassPermissions`**: quando la variabile d'ambiente [`CLAUDE_CODE_REMOTE`](https://code.claude.com/docs/it/env-vars#variables) è `true`, come avviene in una [sessione cloud](https://code.claude.com/docs/it/claude-code-on-the-web.md), la chiamata viene approvata senza la tua callback, indipendentemente dalle annotazioni dello strumento. In qualsiasi altro contesto la chiamata raggiunge la tua callback. Per fare in modo che raggiunga la tua callback anche in una sessione cloud, esegui invece la sessione in modalità `default` o `acceptEdits`
1564
1565Imposta esplicitamente `destructiveHint` su `true` nelle modalità `auto` e `plan`. Per le chiamate `always_ask`, Claude Code interpreta un `destructiveHint` non impostato come `false`, anche se il valore predefinito indicato in [`ToolAnnotations`](#toolannotations) è `true`.
1566
1442#### `McpClaudeAIProxyServerConfig`1567#### `McpClaudeAIProxyServerConfig`
1443 1568
1444```typescript theme={null}1569```typescript theme={null}
1464| Campo | Tipo | Descrizione |1589| Campo | Tipo | Descrizione |
1465| :- | :- | :- |1590| :- | :- | :- |
1466| `type` | `'local'` | Deve essere `'local'` (attualmente sono supportati solo i plugin locali) |1591| `type` | `'local'` | Deve essere `'local'` (attualmente sono supportati solo i plugin locali) |
1467| `path` | `string` | Percorso assoluto o relativo della directory del plugin |1592| `path` | `string` | Percorso della directory del plugin. Un percorso relativo viene risolto rispetto all'opzione [`cwd`](#options) all'avvio della sessione. Il percorso deve essere assoluto quando carichi il plugin a sessione in corso con [`addPlugins`](#load-more-plugin-folders-with-addplugins) |
1468| `skipMcpDiscovery` | `boolean` | Quando è `true`, l'SDK carica skill, hook, agenti e comandi da questo plugin ma non legge il suo `.mcp.json` né i `mcpServers` del manifest. Impostalo quando è la tua applicazione a gestire le connessioni MCP del plugin. |1593| `skipMcpDiscovery` | `boolean` | Quando è `true`, l'SDK carica skill, hook, agenti e comandi da questo plugin ma non legge il suo `.mcp.json` né i `mcpServers` del manifest. Impostalo quando è la tua applicazione a gestire le connessioni MCP del plugin. |
1469 1594
1470**Esempio:**1595**Esempio:**
5076};5201};
5077```5202```
5078 5203
5079`source` indica la provenienza della definizione del server, con gli stessi valori e la stessa regola di fiducia del `source` di [`McpServerProvenance`](#mcpserverprovenance). Il campo richiede Agent SDK v0.3.274 o versioni successive ed è assente nelle versioni precedenti.5204Usa `source` per decidere quanto fidarti di un server, e il `_meta` di ogni voce di `tools` per trovare una risorsa UI che il server ha associato a quello strumento:
5205
5206* **`source`**: la provenienza della definizione del server, con gli stessi valori del `source` di [`McpServerProvenance`](#mcpserverprovenance). Basa le decisioni di fiducia su `source` anziché su `name`, perché solo il tuo server in-process riporta `sdk`, qualunque sia il nome con cui è registrato qualsiasi altro server. Se non riconosci un valore di `source`, tratta quel server come tratti qualsiasi server il cui `source` non è `sdk`. Richiede Agent SDK v0.3.274 o versioni successive
5207* **`_meta`**: l'oggetto `ui` e la stringa `ui/resourceUri` del `_meta` che il server ha dichiarato per lo strumento. Claude Code trattiene ogni altra chiave di `_meta`. `ui/resourceUri` è una grafia di primo livello meno recente di `ui.resourceUri`. Quando il server associa allo strumento una [risorsa UI di MCP Apps](https://code.claude.com/docs/it/mcp.md#reference-mcp-resources), `ui.resourceUri` o `ui/resourceUri` contiene l'URI `ui://` della risorsa. Recupera quell'URI con [`readMcpResource()`](#query-object) e visualizza la risorsa nella tua applicazione. Richiede Agent SDK v0.3.280 o versioni successive
5208
5209Claude Code invia `_meta` solo quando l'array [`capabilities`](#sdksystemmessage) del messaggio `system` con sottotipo `init` elenca `mcp_tool_ui_meta_v1`. Non sei tu ad attivare `mcp_tool_ui_meta_v1`.
5210
5211#### Quando il `_meta.ui` di uno strumento contiene solo `visibility`
5212
5213Se il tuo server dichiara `ui.resourceUri` per uno strumento ma il `_meta.ui` che la tua applicazione riceve contiene solo `visibility`, l'oggetto `ui` inviato dal server non ha superato uno dei controlli di Claude Code. Claude Code controlla `ui` e `ui/resourceUri` separatamente, quindi una chiave può raggiungere la tua applicazione anche quando l'altra non supera i controlli. Confronta il `_meta` nella risposta `tools/list` del tuo server con i controlli per ciascuna chiave:
5214
5215* **`ui`**: raggiunge la tua applicazione invariato, inclusi eventuali membri diversi da `resourceUri` e `visibility`, se tutti e tre i controlli vengono superati:
5216
5217 * `resourceUri` è assente, oppure è una stringa che inizia con `ui://`
5218 * `visibility` è assente, oppure elenca solo `"model"` e `"app"`
5219 * L'intero oggetto è di al massimo 4.096 caratteri quando serializzato come JSON
5220
5221 Se uno qualsiasi dei controlli non viene superato, la tua applicazione riceve al massimo un `ui` il cui unico membro è un array `visibility` con le voci `"model"` e `"app"` elencate dal server.
5222* **`ui/resourceUri`**: raggiunge la tua applicazione se è una stringa che inizia con `ui://` ed è di al massimo 4.096 caratteri. Altrimenti Claude Code lo scarta
5080 5223
5081`_meta` in una voce di `tools` riporta i membri MCP Apps del `_meta` di quello strumento, in modo che la tua applicazione possa trovare la risorsa `ui://` da visualizzare con [`readMcpResource()`](#query-object). Claude Code inoltra l'oggetto `ui` e la stringa piatta deprecata `ui/resourceUri`, e trattiene ogni altra chiave. All'interno di `ui`, `resourceUri` è una stringa `ui://` e `visibility` un array di `"model"` e `"app"` quando il server li imposta, e qualsiasi altro membro viene inoltrato invariato. Claude Code scarta ciascuna delle due chiavi il cui valore sia malformato, e omette `_meta` da uno strumento che non dichiara nessuna delle due. Il campo è presente solo quando le [`capabilities`](#sdksystemmessage) del messaggio init includono `mcp_tool_ui_meta_v1`, e richiede TypeScript Agent SDK v0.3.280 o versioni successive.5224Quando a Claude Code non resta alcun membro `ui` né alcuna stringa `ui/resourceUri` da inviare, la voce di `tools` non ha alcun `_meta`.
5082 5225
5083### `McpServerStatusConfig`5226### `McpServerStatusConfig`
5084 5227
5313Quando chiami `setMcpServers()`, Claude Code applica queste regole:5456Quando chiami `setMcpServers()`, Claude Code applica queste regole:
5314 5457
5315* **Server non indicati dalla chiamata**: al di fuori di una [sessione cloud](https://code.claude.com/docs/it/claude-code-on-the-web.md), Claude Code disconnette i server aggiunti da una precedente chiamata `setMcpServers()` e i server SDK in-process, e li elenca in `removed`. Gli altri server continuano a funzionare e non sono elencati in `removed`, tra cui i server stdio, HTTP e SSE dell'opzione [`mcpServers`](#options), i server dei file di impostazioni e i server forniti dai plugin.5458* **Server non indicati dalla chiamata**: al di fuori di una [sessione cloud](https://code.claude.com/docs/it/claude-code-on-the-web.md), Claude Code disconnette i server aggiunti da una precedente chiamata `setMcpServers()` e i server SDK in-process, e li elenca in `removed`. Gli altri server continuano a funzionare e non sono elencati in `removed`, tra cui i server stdio, HTTP e SSE dell'opzione [`mcpServers`](#options), i server dei file di impostazioni e i server forniti dai plugin.
5316* **Server indicati dalla chiamata**: Claude Code sostituisce un server stdio, HTTP o SSE aggiunto da una precedente chiamata `setMcpServers()` solo quando la sua configurazione differisce da quella che hai passato. Un server SDK in-process già registrato con quel nome rimane invariato, quindi per sostituirne uno, omettilo in una chiamata e aggiungilo in quella successiva.5459* **Server stdio, HTTP e SSE aggiunti da una precedente chiamata `setMcpServers()`**: al di fuori di una sessione cloud, un server che indichi di nuovo con una configurazione identica mantiene la connessione e gli strumenti. Non compare né in `added` né in `removed`. Se passi una configurazione modificata, Claude Code riconnette il server usando quella configurazione e lo elenca in `added`, non in `removed`.
5460* **Server stdio, HTTP e SSE indicati dalla chiamata che nessuna chiamata precedente ha aggiunto**: al di fuori di una sessione cloud, Claude Code aggiunge il server e lo elenca in `added`, oppure in `errors` se rifiuta il server.
5461* **Server SDK in-process indicati dalla chiamata**: un server già registrato tramite `mcpServers` o una chiamata precedente mantiene la sua istanza in esecuzione e il suo timeout. Se passi un [elenco di policy `tools`](#mcpsdkserverconfigwithinstance) per esso, anche vuoto, ne sostituisci le policy; altrimenti restano invariate. Per eseguire una nuova istanza al di fuori di una sessione cloud, ometti il server in una chiamata e indicalo in quella successiva.
5317* **Server integrati avviati dalla CLI all'avvio**: se la chiamata ne indica uno, Claude Code scarta quella voce e la riporta in `errors`.5462* **Server integrati avviati dalla CLI all'avvio**: se la chiamata ne indica uno, Claude Code scarta quella voce e la riporta in `errors`.
5318* **Server stdio, HTTP o SSE che condividono il nome con un server di un ambito di installazione MCP come `.mcp.json`**: con quel nome la sessione usa gli strumenti del tuo server anziché quelli del [server dell'ambito di installazione](https://code.claude.com/docs/it/mcp.md#mcp-installation-scopes). Prima di Claude Code v2.1.305, Claude Code poteva disconnettere il tuo server e connettere il server dell'ambito di installazione quando la tua app [ricaricava i plugin](#query-object).5463* **Server stdio, HTTP o SSE che condividono il nome con un server di un ambito di installazione MCP come `.mcp.json`**: con quel nome la sessione usa gli strumenti del tuo server anziché quelli del [server dell'ambito di installazione](https://code.claude.com/docs/it/mcp.md#mcp-installation-scopes). Prima di Claude Code v2.1.305, Claude Code poteva disconnettere il tuo server e connettere il server dell'ambito di installazione quando la tua app [ricaricava i plugin](#query-object).
5319 5464
5800 5945
5801Le tipizzazioni pubblicate dell'SDK dichiarano `SDKConversationResetMessage` in Claude Code v2.1.203 e versioni successive. Prima della v2.1.203, `SDKMessage` faceva riferimento al tipo senza dichiararlo, quindi il restringimento su `type === "conversation_reset"` non superava il controllo dei tipi quando `skipLibCheck` era disabilitato.5946Le tipizzazioni pubblicate dell'SDK dichiarano `SDKConversationResetMessage` in Claude Code v2.1.203 e versioni successive. Prima della v2.1.203, `SDKMessage` faceva riferimento al tipo senza dichiararlo, quindi il restringimento su `type === "conversation_reset"` non superava il controllo dei tipi quando `skipLibCheck` era disabilitato.
5802 5947
5948### `BUILTIN_TOOL_NAMES` e `LEGACY_TOOL_NAME_ALIASES`
5949
5950Usa queste due costanti per verificare i nomi degli strumenti inseriti dagli utenti della tua applicazione. Entrambe scrivono ogni nome nel modo in cui lo scrivi nelle regole di permesso, nei matcher degli hook e nelle opzioni `tools` e `disallowedTools`. Importale da `@anthropic-ai/claude-agent-sdk` o da `@anthropic-ai/claude-agent-sdk/core`. Richiedono Agent SDK v0.3.301 o versioni successive e sono in fase alpha.
5951
5952Le dichiarazioni di tipo dell'SDK assegnano a `BUILTIN_TOOL_NAMES` un tipo tupla readonly e a `LEGACY_TOOL_NAME_ALIASES` un tipo record da stringa a stringa:
5953
5954```typescript theme={null}
5955const BUILTIN_TOOL_NAMES: readonly ["Agent", /* ...more names... */ "Write"];
5956const LEGACY_TOOL_NAME_ALIASES: Readonly<Record<string, string>>;
5957```
5958
5959* **`BUILTIN_TOOL_NAMES`**: i nomi degli strumenti integrati di Claude Code in ordine alfabetico, come `Agent`, `Bash` e `Read`. I nomi degli strumenti MCP non sono inclusi. Poiché il tipo è una tupla di letterali stringa, `(typeof BUILTIN_TOOL_NAMES)[number]` ti fornisce un tipo unione dei nomi
5960* **`LEGACY_TOOL_NAME_ALIASES`**: i nomi precedenti degli strumenti che le regole di permesso, i matcher degli hook e le opzioni `tools` e `disallowedTools` accettano ancora. Ogni chiave è un nome precedente e il suo valore è quello attuale: ad esempio, `Task` corrisponde ad `Agent`, e `KillShell` e `KillBash` corrispondono a `TaskStop`
5961
5962Puoi confermare un nome con uno dei due test: `BUILTIN_TOOL_NAMES` lo include, oppure `Object.hasOwn(LEGACY_TOOL_NAME_ALIASES, name)` restituisce `true`. Un nome che non supera nessuno dei due può comunque essere valido, perché `BUILTIN_TOOL_NAMES` esclude gli strumenti MCP e alcuni strumenti integrati. Se costruisci un elenco di esclusione a partire da `BUILTIN_TOOL_NAMES`, Claude può comunque usare gli strumenti che la costante esclude. Per negare ogni strumento, imposta invece [`disallowedTools: ["*"]`](https://code.claude.com/docs/it/agent-sdk/permissions#allow-and-deny-rules).
5963
5964Trovare un nome in `BUILTIN_TOOL_NAMES` non ti dice che la sessione dispone di quello strumento: `TodoWrite` è elencato anche se è [disabilitato per impostazione predefinita](https://code.claude.com/docs/it/tools-reference.md). Per vedere quali strumenti ha una sessione, leggi l'array `tools` del suo [`SDKSystemMessage`](#sdksystemmessage). Quell'array include gli strumenti MCP ed elenca lo strumento Agent come `Task`, quindi converti ogni nome tramite `LEGACY_TOOL_NAME_ALIASES` prima di confrontarlo con `BUILTIN_TOOL_NAMES`.
5965
5803### `AbortError`5966### `AbortError`
5804 5967
5805Classe di errore personalizzata per le operazioni di abort.5968Classe di errore personalizzata per le operazioni di abort.
