200| :- | :- | :- | :- |200| :- | :- | :- | :- |
201| `title` | `string` | `undefined` | Benutzerfreundlicher Titel für das Tool |201| `title` | `string` | `undefined` | Benutzerfreundlicher Titel für das Tool |
202| `readOnlyHint` | `boolean` | `false` | Wenn `true`, ändert das Tool seine Umgebung nicht |202| `readOnlyHint` | `boolean` | `false` | Wenn `true`, ändert das Tool seine Umgebung nicht |
203| `destructiveHint` | `boolean` | `true` | Wenn `true`, kann das Tool destruktive Aktualisierungen durchführen (nur sinnvoll, wenn `readOnlyHint` `false` ist) |203| `destructiveHint` | `boolean` | `true` | Wenn `true`, kann das Tool destruktive Aktualisierungen durchführen. Setzen Sie `destructiveHint: true` explizit für jedes Tool, das Sie als [`always_ask`](#mcpservertoolpolicy) markieren, da sonst der Klassifikator des Auto-Modus die Aufrufe dieses Tools anstelle Ihres `canUseTool`-Callbacks genehmigen kann. Es reicht nicht aus, `destructiveHint` ungesetzt zu lassen, da Claude Code ein nicht gesetztes `destructiveHint` bei der Verarbeitung von `always_ask`-Aufrufen als `false` behandelt, obwohl der Standardwert der MCP-Spezifikation `true` ist |
204| `idempotentHint` | `boolean` | `false` | Wenn `true`, haben wiederholte Aufrufe mit denselben Argumenten keine zusätzliche Auswirkung (nur sinnvoll, wenn `readOnlyHint` `false` ist) |204| `idempotentHint` | `boolean` | `false` | Wenn `true`, haben wiederholte Aufrufe mit denselben Argumenten keine zusätzliche Auswirkung (nur sinnvoll, wenn `readOnlyHint` `false` ist) |
205| `openWorldHint` | `boolean` | `true` | Wenn `true`, interagiert das Tool mit externen Entitäten (beispielsweise Websuche). Wenn `false`, ist die Domäne des Tools geschlossen (beispielsweise ein Memory-Tool) |205| `openWorldHint` | `boolean` | `true` | Wenn `true`, interagiert das Tool mit externen Entitäten (beispielsweise Websuche). Wenn `false`, ist die Domäne des Tools geschlossen (beispielsweise ein Memory-Tool) |
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()` | Gibt den Status verbundener MCP-Server als [`McpServerStatus`](#mcpserverstatus)`[]` zurück |670| `mcpServerStatus()` | Gibt den Status verbundener MCP-Server als [`McpServerStatus`](#mcpserverstatus)`[]` zurück |
670| `getContextUsage(opts?)` | Gibt eine [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) zurück, die die Nutzung des Kontextfensters der Sitzung nach Kategorie, Skill und Tool aufschlüsselt. Mit dem Standardwert von `detail` enthält sie die Daten, die `/context` in einer interaktiven Sitzung anzeigt, berechnet mit Token-Counting-API-Anfragen, die nicht im Nachrichtenstream erscheinen; siehe [wie diese Anfragen behandelt werden](#sdkcontrolgetcontextusageresponse). Die [Option `detail`](#sdkcontrolgetcontextusageresponse) erfordert Agent SDK v0.3.257 oder höher |671| `getContextUsage(opts?)` | Gibt eine [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) zurück, die die Nutzung des Kontextfensters der Sitzung nach Kategorie, Skill und Tool aufschlüsselt. Mit dem Standardwert von `detail` enthält sie die Daten, die `/context` in einer interaktiven Sitzung anzeigt, berechnet mit Token-Counting-API-Anfragen, die nicht im Nachrichtenstream erscheinen; siehe [wie diese Anfragen behandelt werden](#sdkcontrolgetcontextusageresponse). Die [Option `detail`](#sdkcontrolgetcontextusageresponse) erfordert Agent SDK v0.3.257 oder höher |
671| `readFile(path, options?)` | Liest eine Datei aus dem Dateisystem der Sitzung. Claude Code löst den Pfad relativ zu `cwd` auf; [Was `readFile()` lesen kann](#what-readfile-can-read) listet die Dateien auf, die bereitgestellt werden. Übergeben Sie `{ maxBytes }`, um die Leseobergrenze zu ändern (Standard 1 MB, Maximum 10 MB), und `{ encoding: 'base64' }` für Binärdateien wie Bilder. Wird mit einer [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) aufgelöst oder bei verweigerter Berechtigung, fehlender Datei oder Transportfehler mit `null`. Erfordert TypeScript SDK v0.2.121 oder höher |672| `readFile(path, options?)` | Liest eine Datei aus dem Dateisystem der Sitzung. Claude Code löst den Pfad relativ zu `cwd` auf; [Was `readFile()` lesen kann](#what-readfile-can-read) listet die Dateien auf, die bereitgestellt werden. Übergeben Sie `{ maxBytes }`, um die Leseobergrenze zu ändern (Standard 1 MB, Maximum 10 MB), und `{ encoding: 'base64' }` für Binärdateien wie Bilder. Wird mit einer [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) aufgelöst oder bei verweigerter Berechtigung, fehlender Datei oder Transportfehler mit `null`. Erfordert TypeScript SDK v0.2.121 oder höher |
672| `reloadPlugins(options?)` | Lädt Plugins von der Festplatte neu, sodass Plugins, die Sie während der Sitzung installieren oder bearbeiten, die laufende Sitzung erreichen. Wird mit einer [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) aufgelöst, die die Befehle, Subagenten, Plugins und den MCP-Server-Status der Sitzung auflistet. Erfordert Agent SDK v0.2.85 oder höher. Die [Option `holdOnCacheImpact`](#sdkcontrolreloadpluginsresponse) erfordert Agent SDK v0.3.268 oder höher |673| `reloadPlugins(options?)` | Lädt Plugins neu von der Festplatte, sodass Plugins, die Sie während der Sitzung installieren oder bearbeiten, die laufende Sitzung erreichen. Wird mit einer [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) aufgelöst, die die Befehle, Subagenten, Plugins und den MCP-Server-Status der Sitzung auflistet. Erfordert Agent SDK v0.2.85 oder höher. Die [Option `holdOnCacheImpact`](#sdkcontrolreloadpluginsresponse) erfordert Agent SDK v0.3.268 oder höher. Die [Option `addPlugins`](#load-more-plugin-folders-with-addplugins) erfordert Agent SDK v0.3.301 oder höher |
673| `reloadSkills()` | Lädt Skills von der Festplatte neu, sodass Skills, die Sie während der Sitzung hinzufügen oder bearbeiten, in der laufenden Sitzung verfügbar werden. Wird mit einer [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) aufgelöst, die die nach dem Neuladen verfügbaren Skills auflistet. Erfordert Agent SDK v0.3.163 oder höher |674| `reloadSkills()` | Lädt Skills von der Festplatte neu, sodass Skills, die Sie während der Sitzung hinzufügen oder bearbeiten, in der laufenden Sitzung verfügbar werden. Wird mit einer [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) aufgelöst, die die nach dem Neuladen verfügbaren Skills auflistet. Erfordert Agent SDK v0.3.163 oder höher |
674| `reloadOutputStyles()` | Liest [Ausgabestile](https://code.claude.com/docs/de/output-styles.md) erneut von der Festplatte, sodass eine Stildatei, die Sie während der Sitzung hinzufügen oder bearbeiten, in der laufenden Sitzung verfügbar wird. Wird mit einer [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) aufgelöst, die die nach dem Neuladen verfügbaren Stilnamen auflistet. Erfordert Agent SDK v0.3.261 oder höher |675| `reloadOutputStyles()` | Liest [Ausgabestile](https://code.claude.com/docs/de/output-styles.md) erneut von der Festplatte, sodass eine Stildatei, die Sie während der Sitzung hinzufügen oder bearbeiten, in der laufenden Sitzung verfügbar wird. Wird mit einer [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) aufgelöst, die die nach dem Neuladen verfügbaren Stilnamen auflistet. Erfordert Agent SDK v0.3.261 oder höher |
675| `seedReadState(path, mtime)` | Markiert eine Datei als bereits gelesen, damit ein späteres Edit nicht mit `File has not been read yet` fehlschlägt. Siehe [`seedReadState()`](#seedreadstate). Erfordert TypeScript SDK v0.2.83 oder höher |676| `seedReadState(path, mtime)` | Markiert eine Datei als bereits gelesen, damit ein späteres Edit nicht mit `File has not been read yet` fehlschlägt. Siehe [`seedReadState()`](#seedreadstate). Erfordert TypeScript SDK v0.2.83 oder höher |
1135 1136
1136`cache_impact` ist nur zusammen mit `held: true` vorhanden. `mcp_servers_added` und `mcp_servers_removed` nennen die Plugin-MCP-Server, die das Neuladen registrieren oder entfernen würde, als eingeschränkte Namen der Form `plugin:<plugin>:<server>`. Die Namen stammen von Plugin-Autoren; validieren Sie sie daher, bevor Sie sie anzeigen. `lsp_tool_change` gibt an, ob das Anwenden das LSP-Tool hinzufügen oder entfernen würde, oder ist `null`, wenn beides nicht zutrifft. Die `may-`-Formen bedeuten, dass die Prüfung die ausstehende Plugin-Menge nicht vollständig einsehen konnte.1137`cache_impact` ist nur zusammen mit `held: true` vorhanden. `mcp_servers_added` und `mcp_servers_removed` nennen die Plugin-MCP-Server, die das Neuladen registrieren oder entfernen würde, als eingeschränkte Namen der Form `plugin:<plugin>:<server>`. Die Namen stammen von Plugin-Autoren; validieren Sie sie daher, bevor Sie sie anzeigen. `lsp_tool_change` gibt an, ob das Anwenden das LSP-Tool hinzufügen oder entfernen würde, oder ist `null`, wenn beides nicht zutrifft. Die `may-`-Formen bedeuten, dass die Prüfung die ausstehende Plugin-Menge nicht vollständig einsehen konnte.
1137 1138
1139#### Weitere Plugin-Ordner mit `addPlugins` laden
1140
1141Um Plugin-Ordner zu laden, die beim Start nicht in der Option [`plugins`](#options) enthalten waren, übergeben Sie sie an `reloadPlugins()` als `addPlugins`, eine Liste von [`SdkPluginConfig`](#sdkpluginconfig)-Einträgen, deren `path` absolut ist. Claude Code lädt die neuen Ordner und lädt die vorhandenen Plugins der Sitzung in einem Durchgang neu. Die MCP-Server jedes hinzugefügten Plugins werden ebenfalls verbunden, sofern Sie nicht [`skipMcpDiscovery`](#sdkpluginconfig) im Eintrag dieses Ordners setzen. Erfordert Agent SDK v0.3.301 oder höher und Claude Code v2.1.301 oder höher.
1142
1143Dieses Beispiel fügt einer laufenden Abfrage `q` einen Ordner hinzu und gibt den Installationspfad jedes Plugins aus, das die Sitzung geladen hat, wenn der Aufruf zurückkehrt:
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
1153Wenn der Ordner geladen wurde, enthält die ausgegebene Liste `/opt/my-app/plugins/reports`, und die Befehle und Subagenten des Plugins erscheinen in `result.commands` und `result.agents`.
1154
1155Ein hinzugefügter Ordner bleibt Teil der Sitzung. Wenn Sie `reloadPlugins()` erneut aufrufen, lädt Claude Code ihn zusammen mit den anderen Plugins neu, und Sie übergeben ihn nicht erneut in `addPlugins`.
1156
1157##### Wenn `reloadPlugins()` die `addPlugins`-Ordner nicht lädt
1158
1159Wenn `reloadPlugins()` mit einem Fehler abgelehnt wird, wird keiner der `addPlugins`-Ordner hinzugefügt; übergeben Sie sie daher bei einem erneuten Versuch wieder in `addPlugins`. Wenn die Ablehnung eine der folgenden Ursachen hat, behält die Sitzung die Plugins, die sie bereits hatte:
1160
1161* **Ein relativer `path` oder ein fehlerhafter Eintrag**: Die Fehlermeldung lautet `add_plugins must be a list of { type: "local", path } entries with absolute paths`. Claude Code lehnt wegen eines einzigen fehlerhaften Eintrags die gesamte Liste ab, übergeben Sie daher jeden Eintrag als `{ type: "local", path }` mit einem absoluten `path`
1162* **Ein Administrator hat [`disableSideloadFlags`](https://code.claude.com/docs/de/settings-reference#disablesideloadflags) in Ihren verwalteten Einstellungen aktiviert**: Die Meldung lautet `reload_plugins add_plugins is disabled by managed settings (disableSideloadFlags)`. Um den Ordner zu laden, bitten Sie diesen Administrator, die Einstellung zu entfernen
1163* **Die [Sandbox](https://code.claude.com/docs/de/sandboxing.md) konnte nicht neu aufgebaut werden**: Bei aktiviertem [Sandboxing](#sandboxsettings) baut Claude Code die Sandbox-Konfiguration neu auf, damit in der Sandbox ausgeführte Shell-Befehle nicht in die von Ihnen hinzugefügten Ordner schreiben können. Die Meldung lautet `the sandbox could not be rebuilt to keep shell commands out of this folder`. Prüfen Sie, ob Ihre [Sandbox-Einstellungen](#sandboxsettings) weiterhin eine gültige Konfiguration ergeben
1164
1165Wenn Sie `holdOnCacheImpact` übergeben und der Aufruf mit [`held: true`](#sdkcontrolreloadpluginsresponse) aufgelöst wird, werden die `addPlugins`-Ordner nicht hinzugefügt. Um sie trotzdem hinzuzufügen, rufen Sie `reloadPlugins()` erneut mit derselben `addPlugins`-Liste und ohne `holdOnCacheImpact` auf.
1166
1167Wenn der Aufruf ohne `held: true` aufgelöst wird und ein Ordner dennoch in `result.plugins` fehlt, prüfen Sie zunächst diese Ursachen:
1168
1169* **Der Ordner existiert nicht oder sein Plugin konnte nicht geladen werden**: `result.error_count` ist `1` oder höher. Der Ordner bleibt trotzdem Teil der Sitzung. Nachdem Sie den Ordner korrigiert haben, rufen Sie `reloadPlugins()` erneut auf, um ihn zu laden, diesmal ohne ihn in `addPlugins` aufzuführen
1170* **Die Claude Code-Programmdatei ist älter als v2.1.301**: Eine Programmdatei älter als v2.1.301 ignoriert `addPlugins` und lädt nur die Plugins neu, die die Sitzung bereits hatte. Prüfen Sie `claude_code_version` in der [Init-Nachricht](#sdksystemmessage), und verwenden Sie eine Programmdatei ab v2.1.301
1171
1138### `SDKControlReloadSkillsResponse`1172### `SDKControlReloadSkillsResponse`
1139 1173
1140Rückgabetyp von [`reloadSkills()`](#query-object).1174Rückgabetyp von [`reloadSkills()`](#query-object).
1430 1464
1431#### `McpSdkServerConfigWithInstance`1465#### `McpSdkServerConfigWithInstance`
1432 1466
1467Die Konfiguration für einen In-Process-MCP-Server, also einen, den [`createSdkMcpServer()`](#createsdkmcpserver) erstellt und der innerhalb des Prozesses Ihrer Anwendung läuft. Sie ist das Objekt, das `createSdkMcpServer()` zurückgibt, plus eine optionale `tools`-Liste mit [`McpServerToolPolicy`](#mcpservertoolpolicy)-Einträgen, die Sie selbst hinzufügen. Um für Aufrufe eines der Tools des Servers eine Genehmigung zu verlangen oder sie zu verweigern, fügen Sie einen Eintrag hinzu, der das Tool benennt.
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
1479Um eine Richtlinie festzulegen, übernehmen Sie das von `createSdkMcpServer()` zurückgegebene Objekt per Spread in ein neues Objekt in `mcpServers` und fügen diesem neuen Objekt die `tools`-Liste hinzu. Die Option `tools` von `createSdkMcpServer()` selbst ist eine andere Liste, die die Tool-Definitionen enthält und keine Richtlinieneinträge akzeptiert. Die Richtlinienliste erfordert Agent SDK v0.3.301 oder höher, und [`McpServerToolPolicy`](#mcpservertoolpolicy) beschreibt, was jeder `permission_policy`-Wert bewirkt.
1480
1481Dieses Beispiel genehmigt alle Tools auf dem Server `records` vorab mit einem `allowedTools`-Platzhalter und markiert dann `delete_record` als `always_ask`, sodass Aufrufe dieses Tools trotzdem an `canUseTool` gehen. Mit der Annotation `destructiveHint: true` erreicht der Aufruf den Callback auch dann, wenn die Sitzung im `auto`-Modus läuft, in dem der [Klassifikator](https://code.claude.com/docs/de/permission-modes.md#eliminate-prompts-with-auto-mode) des Auto-Modus ihn andernfalls genehmigen könnte.
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
1520Wenn Claude das Tool aufruft, gibt das Skript `Approval requested for mcp__records__delete_record` aus, bevor das Tool `delete_record` ausgeführt wird, obwohl der `allowedTools`-Eintrag den Aufruf andernfalls genehmigt hätte.
1521
1522Um die Richtlinie eines Tools während der laufenden Sitzung zu ändern oder aufzuheben, übergeben Sie die Konfiguration des Servers mit einem neuen `tools`-Wert an [`setMcpServers()`](#mcpsetserversresult). Der übergebene `tools`-Wert gilt ab Claudes nächstem Aufruf der Tools dieses Servers:
1523
1524* **Eine Liste mit Einträgen**: Die Einträge ersetzen die aktuellen Richtlinien
1525* **Eine leere Liste**: Alle Richtlinien des Servers werden gelöscht
1526* **Kein `tools`-Schlüssel**: Die aktuellen Richtlinien bleiben bestehen
1527
1528Nehmen Sie in diesen Aufruf Ihre anderen In-Process-Server und alle Server auf, die ein früherer `setMcpServers()`-Aufruf hinzugefügt hat, sonst trennt der Aufruf deren Verbindung.
1529
1530#### `McpServerToolPolicy`
1531
1532Ein Eintrag in der `tools`-Liste einer [`McpSdkServerConfigWithInstance`](#mcpsdkserverconfigwithinstance), der eines der Tools des Servers benennt und die Berechtigungsrichtlinie für Aufrufe dieses Tools festlegt. Die Liste erfordert Agent SDK v0.3.301 oder höher und Claude Code v2.1.301 oder höher. Eine ältere Claude Code-Programmdatei, etwa eine, auf die Sie `pathToClaudeCodeExecutable` verweisen, ignoriert die Liste. Dann werden `always_ask` und `always_deny` nicht durchgesetzt, und jeder Aufruf durchläuft den [Berechtigungsablauf](https://code.claude.com/docs/de/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| Feld | Typ | Beschreibung |
1543| :- | :- | :- |
1544| `name` | `string` | Der reine Name des Tools, wie er an [`tool()`](#tool) übergeben wird, ohne das Präfix `mcp__<server>__` |
1545| `permission_policy` | `'always_allow' \| 'always_ask' \| 'always_deny'` | Die Genehmigungsrichtlinie für die Aufrufe des Tools, [`always_ask` oder `always_deny`](#permission-policy-values). `always_allow` wird auf einem In-Process-Server ignoriert: Um ein Tool vorab zu genehmigen, führen Sie es stattdessen in [`allowedTools`](#options) auf |
1546| `org_max_permission` | `'allow' \| 'ask' \| 'blocked'` | Eine Obergrenze pro Tool, die ein Organisations-Admin festlegt. Wird auf einem In-Process-Server ignoriert, lassen Sie das Feld daher ungesetzt |
1547
1548##### `permission_policy`-Werte
1549
1550Wählen Sie `always_ask`, um jeden Aufruf selbst zu genehmigen, oder `always_deny`, um das Tool vollständig zu blockieren:
1551
1552* **`always_ask`**: Jeder Aufruf des Tools [erfordert eine Genehmigung](https://code.claude.com/docs/de/agent-sdk/permissions.md#how-permissions-are-evaluated), auch wenn ein `allowedTools`-Eintrag oder eine Allow-Regel ihn abdeckt. Der Aufruf geht an Ihren `canUseTool`-Callback oder Ihr [`permissionPromptToolName`](#options)-Tool, sofern er nicht vorher entschieden wird. Ein [Mod](https://code.claude.com/docs/de/plugins/mods/overview.md) in einem von Ihnen geladenen Plugin [kann ihn vorher genehmigen](https://code.claude.com/docs/de/permissions.md#precedence-among-rules-hooks-and-mods). Andernfalls wird er im `dontAsk`-Modus verweigert, und im [`auto`-, `plan`- und `bypassPermissions`-Modus](#permission-modes-that-can-approve-an-always_ask-call) kann er genehmigt werden, bevor er Ihren Callback erreicht
1553* **`always_deny`**: Ein Aufruf des Tools [wird in jedem Berechtigungsmodus verweigert](https://code.claude.com/docs/de/agent-sdk/permissions.md#how-permissions-are-evaluated), einschließlich `bypassPermissions`, aber ein Mod in einem von Ihnen geladenen Plugin [kann ihn dennoch genehmigen](https://code.claude.com/docs/de/permissions.md#precedence-among-rules-hooks-and-mods)
1554
1555Wenn Sie weder `canUseTool` noch `permissionPromptToolName` übergeben oder [`permissionPrompts`](#options) auf `'none'` setzen, wird ein `always_ask`-Aufruf, der nicht vorher entschieden wird, verweigert, sofern kein [`PermissionRequest`-Hook](https://code.claude.com/docs/de/hooks#permissionrequest) ihn erlaubt.
1556
1557##### Berechtigungsmodi, die einen `always_ask`-Aufruf genehmigen können
1558
1559Im `auto`-, `plan`- und `bypassPermissions`-Modus kann ein Aufruf eines mit [`always_ask`](#permission-policy-values) markierten Tools genehmigt werden, bevor er Ihren `canUseTool`-Callback erreicht. Suchen Sie den Modus Ihrer Sitzung in dieser Liste, um zu sehen, wann diese Genehmigung erfolgt und was Sie festlegen müssen, damit der Aufruf Ihren Callback trotzdem erreicht:
1560
1561* **`auto`**: Der [Klassifikator](https://code.claude.com/docs/de/permission-modes.md#eliminate-prompts-with-auto-mode) des Auto-Modus prüft den Aufruf und kann ihn erlauben. Damit im `auto`-Modus jeder Aufruf Ihren Callback erreicht, setzen Sie `destructiveHint: true` in den [Annotationen](#toolannotations) des Tools
1562* **`plan`**: Solange der [Auto-Modus](https://code.claude.com/docs/de/permission-modes.md#eliminate-prompts-with-auto-mode) für die Sitzung verfügbar ist, gehen Aufrufe eines `always_ask`-Tools mit der Annotation `readOnlyHint: true` an den Klassifikator des Auto-Modus, der sie erlauben kann. Aufrufe anderer `always_ask`-Tools erreichen Ihren Callback. Damit auch die Aufrufe eines nur lesenden Tools Ihren Callback erreichen, fügen Sie den Annotationen dieses Tools zusätzlich zu `readOnlyHint: true` auch `destructiveHint: true` hinzu. Alternativ setzen Sie [`useAutoModeDuringPlan`](https://code.claude.com/docs/de/settings-reference#useautomodeduringplan) auf `false`, wodurch der Klassifikator während der Planung ausgeschaltet wird
1563* **`bypassPermissions`**: Wenn die [`CLAUDE_CODE_REMOTE`](https://code.claude.com/docs/de/env-vars#variables)-Umgebungsvariable `true` ist, wie in einer [Cloud-Sitzung](https://code.claude.com/docs/de/claude-code-on-the-web.md), wird der Aufruf ohne Ihren Callback genehmigt, unabhängig von den Annotationen des Tools. Überall sonst erreicht der Aufruf Ihren Callback. Damit er auch in einer Cloud-Sitzung Ihren Callback erreicht, führen Sie die Sitzung stattdessen im `default`- oder `acceptEdits`-Modus aus
1564
1565Setzen Sie `destructiveHint` im `auto`- und `plan`-Modus explizit auf `true`. Bei `always_ask`-Aufrufen wertet Claude Code ein nicht gesetztes `destructiveHint` als `false`, obwohl der unter [`ToolAnnotations`](#toolannotations) aufgeführte Standardwert `true` ist.
1566
1442#### `McpClaudeAIProxyServerConfig`1567#### `McpClaudeAIProxyServerConfig`
1443 1568
1444```typescript theme={null}1569```typescript theme={null}
1464| Feld | Typ | Beschreibung |1589| Feld | Typ | Beschreibung |
1465| :- | :- | :- |1590| :- | :- | :- |
1466| `type` | `'local'` | Muss `'local'` sein (derzeit werden nur lokale Plugins unterstützt) |1591| `type` | `'local'` | Muss `'local'` sein (derzeit werden nur lokale Plugins unterstützt) |
1467| `path` | `string` | Absoluter oder relativer Pfad zum Plugin-Verzeichnis |1592| `path` | `string` | Pfad zum Plugin-Verzeichnis. Ein relativer Pfad wird beim Start der Sitzung relativ zur Option [`cwd`](#options) aufgelöst. Der Pfad muss absolut sein, wenn Sie das Plugin während der Sitzung mit [`addPlugins`](#load-more-plugin-folders-with-addplugins) laden |
1468| `skipMcpDiscovery` | `boolean` | Bei `true` lädt das SDK Skills, Hooks, Agenten und Befehle aus diesem Plugin, liest aber weder dessen `.mcp.json` noch die `mcpServers` des Manifests. Setzen Sie dies, wenn Ihre Anwendung die MCP-Verbindungen des Plugins selbst verwaltet. |1593| `skipMcpDiscovery` | `boolean` | Bei `true` lädt das SDK Skills, Hooks, Agenten und Befehle aus diesem Plugin, liest aber weder dessen `.mcp.json` noch die `mcpServers` des Manifests. Setzen Sie dies, wenn Ihre Anwendung die MCP-Verbindungen des Plugins selbst verwaltet. |
1469 1594
1470**Beispiel:**1595**Beispiel:**
5074};5199};
5075```5200```
5076 5201
5077`source` sagt, woher die Definition des Servers kam, mit den gleichen Werten und Vertrauensregel wie [`McpServerProvenance`](#mcpserverprovenance)'s `source`. Das Feld erfordert Agent SDK v0.3.274 oder später und fehlt in früheren Versionen.5202Verwenden Sie `source`, um zu entscheiden, wie weit Sie einem Server vertrauen, und das `_meta` in jedem `tools`-Eintrag, um eine UI-Ressource zu finden, die der Server an dieses Tool angehängt hat:
5203
5204* **`source`**: woher die Definition des Servers kam, mit denselben Werten wie `source` in [`McpServerProvenance`](#mcpserverprovenance). Basieren Sie Vertrauensentscheidungen auf `source` statt auf `name`, weil nur Ihr eigener In-Process-Server `sdk` meldet, unabhängig davon, unter welchem Namen ein anderer Server registriert ist. Wenn Sie einen `source`-Wert nicht erkennen, behandeln Sie diesen Server so wie jeden Server, dessen `source` nicht `sdk` ist. Erfordert Agent SDK v0.3.274 oder später
5205* **`_meta`**: das `ui`-Objekt und die `ui/resourceUri`-Zeichenkette aus dem `_meta`, das der Server für das Tool deklariert hat. Claude Code behält jeden anderen `_meta`-Schlüssel zurück. `ui/resourceUri` ist eine ältere Top-Level-Schreibweise von `ui.resourceUri`. Wenn der Server eine [MCP-Apps-UI-Ressource](https://code.claude.com/docs/de/mcp.md#reference-mcp-resources) an das Tool anhängt, enthält `ui.resourceUri` oder `ui/resourceUri` den `ui://`-URI der Ressource. Rufen Sie diesen URI mit [`readMcpResource()`](#query-object) ab und rendern Sie die Ressource in Ihrer Anwendung. Erfordert Agent SDK v0.3.280 oder später
5206
5207Claude Code sendet `_meta` nur, wenn das [`capabilities`](#sdksystemmessage)-Array der `system`-Nachricht mit dem Subtyp `init` `mcp_tool_ui_meta_v1` enthält. Sie aktivieren `mcp_tool_ui_meta_v1` nicht selbst.
5208
5209#### Wenn `_meta.ui` eines Tools nur `visibility` enthält
5210
5211Wenn Ihr Server `ui.resourceUri` für ein Tool deklariert, das `_meta.ui`, das Ihre Anwendung empfängt, aber nur `visibility` enthält, hat das vom Server gesendete `ui`-Objekt eine der Prüfungen von Claude Code nicht bestanden. Claude Code prüft `ui` und `ui/resourceUri` getrennt, sodass ein Schlüssel Ihre Anwendung erreichen kann, wenn der andere die Prüfung nicht besteht. Vergleichen Sie das `_meta` in der `tools/list`-Antwort Ihres Servers mit den Prüfungen für jeden Schlüssel:
5212
5213* **`ui`**: erreicht Ihre Anwendung unverändert, einschließlich aller Mitglieder außer `resourceUri` und `visibility`, wenn alle drei Prüfungen bestanden werden:
5214
5215 * `resourceUri` fehlt oder ist eine Zeichenkette, die mit `ui://` beginnt
5216 * `visibility` fehlt oder listet nur `"model"` und `"app"` auf
5217 * Das gesamte Objekt umfasst als JSON serialisiert höchstens 4.096 Zeichen
5218
5219 Wenn eine der Prüfungen fehlschlägt, empfängt Ihre Anwendung höchstens ein `ui`, dessen einziges Mitglied ein `visibility`-Array mit den vom Server aufgelisteten Einträgen `"model"` und `"app"` ist.
5220* **`ui/resourceUri`**: erreicht Ihre Anwendung, wenn es eine Zeichenkette ist, die mit `ui://` beginnt und höchstens 4.096 Zeichen lang ist. Andernfalls verwirft Claude Code es
5078 5221
5079`_meta` auf einem `tools`-Eintrag trägt die MCP-Apps-Mitglieder des `_meta` dieses Tools, sodass Ihre Anwendung die `ui://`-Ressource finden kann, um sie mit [`readMcpResource()`](#query-object) zu rendern. Claude Code leitet das `ui`-Objekt und die veraltete flache `ui/resourceUri`-Zeichenkette durch und behält jeden anderen Schlüssel zurück. Innerhalb von `ui` ist `resourceUri` eine `ui://`-Zeichenkette und `visibility` ein Array von `"model"` und `"app"`, wenn der Server sie setzt, und jedes andere Mitglied wird unverändert durchgeleitet. Claude Code verwirft jeden Schlüssel, wenn der Wert fehlerhaft ist, und lässt `_meta` von einem Tool weg, das weder deklariert. Das Feld ist nur vorhanden, wenn die [`capabilities`](#sdksystemmessage) der Init-Nachricht `mcp_tool_ui_meta_v1` enthalten, und erfordert TypeScript Agent SDK v0.3.280 oder später.5222Wenn Claude Code weder ein `ui`-Mitglied noch eine `ui/resourceUri`-Zeichenkette zum Senden übrig bleibt, hat der `tools`-Eintrag überhaupt kein `_meta`.
5080 5223
5081### `McpServerStatusConfig`5224### `McpServerStatusConfig`
5082 5225
5311Wenn Sie `setMcpServers()` aufrufen, wendet Claude Code diese Regeln an:5454Wenn Sie `setMcpServers()` aufrufen, wendet Claude Code diese Regeln an:
5312 5455
5313* **Server, die der Aufruf nicht benennt**: Außerhalb einer [Cloud-Sitzung](https://code.claude.com/docs/de/claude-code-on-the-web.md) trennt Claude Code die Server, die ein früherer `setMcpServers()`-Aufruf hinzugefügt hat, sowie die In-Process-SDK-Server und listet sie in `removed` auf. Andere Server laufen weiter und werden nicht in `removed` aufgeführt, darunter die Stdio-, HTTP- und SSE-Server aus der [`mcpServers`](#options)-Option, Server aus Einstellungsdateien und von Plugins bereitgestellte Server.5456* **Server, die der Aufruf nicht benennt**: Außerhalb einer [Cloud-Sitzung](https://code.claude.com/docs/de/claude-code-on-the-web.md) trennt Claude Code die Server, die ein früherer `setMcpServers()`-Aufruf hinzugefügt hat, sowie die In-Process-SDK-Server und listet sie in `removed` auf. Andere Server laufen weiter und werden nicht in `removed` aufgeführt, darunter die Stdio-, HTTP- und SSE-Server aus der [`mcpServers`](#options)-Option, Server aus Einstellungsdateien und von Plugins bereitgestellte Server.
5314* **Server, die der Aufruf benennt**: Claude Code ersetzt einen Stdio-, HTTP- oder SSE-Server, den ein früherer `setMcpServers()`-Aufruf hinzugefügt hat, nur, wenn sich seine Konfiguration von der unterscheidet, die Sie übergeben haben. Ein In-Process-SDK-Server, der bereits unter diesem Namen registriert ist, bleibt unverändert; um einen auszutauschen, lassen Sie ihn in einem Aufruf weg und fügen Sie ihn im nächsten hinzu.5457* **Stdio-, HTTP- und SSE-Server, die ein früherer `setMcpServers()`-Aufruf hinzugefügt hat**: Außerhalb einer Cloud-Sitzung behält ein Server, den Sie erneut mit identischer Konfiguration benennen, seine Verbindung und seine Tools. Er erscheint weder in `added` noch in `removed`. Wenn Sie eine geänderte Konfiguration übergeben, verbindet Claude Code den Server mit dieser Konfiguration neu und listet ihn in `added` auf, nicht in `removed`.
5458* **Stdio-, HTTP- und SSE-Server, die der Aufruf benennt und die kein früherer Aufruf hinzugefügt hat**: Außerhalb einer Cloud-Sitzung fügt Claude Code den Server hinzu und listet ihn in `added` auf, oder in `errors`, wenn es den Server ablehnt.
5459* **In-Process-SDK-Server, die der Aufruf benennt**: Ein Server, der bereits über `mcpServers` oder einen früheren Aufruf registriert ist, behält seine laufende Instanz und seinen Timeout. Wenn Sie eine [`tools`-Richtlinienliste](#mcpsdkserverconfigwithinstance) für ihn übergeben, auch eine leere, ersetzen Sie seine Richtlinien; andernfalls bleiben sie erhalten. Um außerhalb einer Cloud-Sitzung eine neue Instanz auszuführen, lassen Sie den Server in einem Aufruf weg und benennen Sie ihn im nächsten.
5315* **Integrierte Server, die die CLI beim Start gestartet hat**: Wenn der Aufruf einen benennt, verwirft Claude Code diesen Eintrag und meldet ihn in `errors`.5460* **Integrierte Server, die die CLI beim Start gestartet hat**: Wenn der Aufruf einen benennt, verwirft Claude Code diesen Eintrag und meldet ihn in `errors`.
5316* **Stdio-, HTTP- oder SSE-Server, die ihren Namen mit einem Server aus einem MCP-Installations-Geltungsbereich wie `.mcp.json` teilen**: Unter diesem Namen verwendet die Sitzung die Tools Ihres Servers statt die des [Servers aus dem Installations-Geltungsbereich](https://code.claude.com/docs/de/mcp.md#mcp-installation-scopes). Vor Claude Code v2.1.305 konnte Claude Code Ihren Server trennen und den Server aus dem Installations-Geltungsbereich verbinden, wenn Ihre App [Plugins neu lud](#query-object).5461* **Stdio-, HTTP- oder SSE-Server, die ihren Namen mit einem Server aus einem MCP-Installations-Geltungsbereich wie `.mcp.json` teilen**: Unter diesem Namen verwendet die Sitzung die Tools Ihres Servers statt die des [Servers aus dem Installations-Geltungsbereich](https://code.claude.com/docs/de/mcp.md#mcp-installation-scopes). Vor Claude Code v2.1.305 konnte Claude Code Ihren Server trennen und den Server aus dem Installations-Geltungsbereich verbinden, wenn Ihre App [Plugins neu lud](#query-object).
5317 5462
5798 5943
5799Die veröffentlichten Typings des SDK deklarieren `SDKConversationResetMessage` in Claude Code v2.1.203 und später. Vor v2.1.203 referenzierte `SDKMessage` den Typ, ohne ihn zu deklarieren, daher schlug die Eingrenzung auf `type === "conversation_reset"` bei der Typprüfung fehl, wenn `skipLibCheck` deaktiviert war.5944Die veröffentlichten Typings des SDK deklarieren `SDKConversationResetMessage` in Claude Code v2.1.203 und später. Vor v2.1.203 referenzierte `SDKMessage` den Typ, ohne ihn zu deklarieren, daher schlug die Eingrenzung auf `type === "conversation_reset"` bei der Typprüfung fehl, wenn `skipLibCheck` deaktiviert war.
5800 5945
5946### `BUILTIN_TOOL_NAMES` und `LEGACY_TOOL_NAME_ALIASES`
5947
5948Verwenden Sie diese beiden Konstanten, um Tool-Namen zu prüfen, die die Benutzer Ihrer Anwendung eingeben. Beide schreiben jeden Namen so, wie Sie ihn in Berechtigungsregeln, Hook-Matchern und den Optionen `tools` und `disallowedTools` schreiben. Importieren Sie sie aus `@anthropic-ai/claude-agent-sdk` oder aus `@anthropic-ai/claude-agent-sdk/core`. Sie erfordern Agent SDK v0.3.301 oder später und befinden sich im Alpha-Stadium.
5949
5950Die Typdeklarationen des SDK geben `BUILTIN_TOOL_NAMES` einen schreibgeschützten Tupeltyp und `LEGACY_TOOL_NAME_ALIASES` einen Record-Typ von Zeichenkette zu Zeichenkette:
5951
5952```typescript theme={null}
5953const BUILTIN_TOOL_NAMES: readonly ["Agent", /* ...more names... */ "Write"];
5954const LEGACY_TOOL_NAME_ALIASES: Readonly<Record<string, string>>;
5955```
5956
5957* **`BUILTIN_TOOL_NAMES`**: Namen der integrierten Tools von Claude Code in alphabetischer Reihenfolge, z. B. `Agent`, `Bash` und `Read`. MCP-Tool-Namen sind nicht enthalten. Da der Typ ein Tupel von String-Literalen ist, liefert Ihnen `(typeof BUILTIN_TOOL_NAMES)[number]` einen Union-Typ der Namen
5958* **`LEGACY_TOOL_NAME_ALIASES`**: frühere Tool-Namen, die Berechtigungsregeln, Hook-Matcher und die Optionen `tools` und `disallowedTools` weiterhin akzeptieren. Jeder Schlüssel ist ein früherer Name und sein Wert der aktuelle: Beispielsweise wird `Task` auf `Agent` abgebildet, und `KillShell` und `KillBash` werden auf `TaskStop` abgebildet
5959
5960Sie können einen Namen mit einem von zwei Tests bestätigen: `BUILTIN_TOOL_NAMES` enthält ihn, oder `Object.hasOwn(LEGACY_TOOL_NAME_ALIASES, name)` gibt `true` zurück. Ein Name, der beide Tests nicht besteht, kann trotzdem gültig sein, weil `BUILTIN_TOOL_NAMES` MCP-Tools und einige integrierte Tools auslässt. Wenn Sie eine Sperrliste aus `BUILTIN_TOOL_NAMES` erstellen, kann Claude die Tools, die die Konstante auslässt, weiterhin verwenden. Um jedes Tool zu sperren, setzen Sie stattdessen [`disallowedTools: ["*"]`](https://code.claude.com/docs/de/agent-sdk/permissions#allow-and-deny-rules).
5961
5962Dass ein Name in `BUILTIN_TOOL_NAMES` vorkommt, sagt Ihnen nicht, dass die Sitzung dieses Tool hat: `TodoWrite` ist aufgeführt, obwohl es [standardmäßig deaktiviert](https://code.claude.com/docs/de/tools-reference.md) ist. Um zu sehen, welche Tools eine Sitzung hat, lesen Sie das `tools`-Array ihrer [`SDKSystemMessage`](#sdksystemmessage). Dieses Array enthält MCP-Tools und führt das Agent-Tool als `Task` auf; bilden Sie daher jeden Namen über `LEGACY_TOOL_NAME_ALIASES` ab, bevor Sie ihn mit `BUILTIN_TOOL_NAMES` vergleichen.
5963
5801### `AbortError`5964### `AbortError`
5802 5965
5803Benutzerdefinierte Fehlerklasse für Abbruchoperationen.5966Benutzerdefinierte Fehlerklasse für Abbruchoperationen.
