Skip to main content
Das Claude Agent SDK bietet Berechtigungskontrollen zur Verwaltung der Tool-Nutzung durch Claude. Verwenden Sie Berechtigungsmodi und Regeln, um automatisch zu definieren, was zulässig ist, und den canUseTool-Callback, um alles andere zur Laufzeit zu handhaben.

Wie Berechtigungen ausgewertet werden

Wenn Claude ein Tool anfordert, prüft das SDK Berechtigungen in dieser Reihenfolge:
1

Hooks

Führen Sie Hooks zuerst aus. Ein Hook kann den Aufruf direkt ablehnen oder ihn weitergeben. Ein Hook, der allow zurückgibt, überspringt nicht die Deny- und Ask-Regeln unten; diese werden unabhängig vom Hook-Ergebnis ausgewertet. Ein PreToolUse Hook allow kann auch keine rm oder rmdir Entfernung genehmigen, die auf einen kritischen Pfad abzielt.
2

Deny-Regeln

Prüfen Sie deny Regeln (aus disallowed_tools und settings.json). Wenn eine Deny-Regel zutrifft, wird das Tool blockiert, auch im bypassPermissions Modus. Bare-Name Deny-Regeln wie Bash entfernen das Tool aus Claudes Kontext, bevor diese Auswertung beginnt, daher werden nur scoped Regeln wie Bash(rm *) in diesem Schritt geprüft.
3

Ask-Regeln

Prüfen Sie ask Regeln aus settings.json. Wenn eine Ask-Regel zutrifft, fällt der Aufruf in Ihren canUseTool Callback zur Bestätigung, auch im bypassPermissions Modus.Tools, die Benutzerinteraktion erfordern, verhalten sich auf die gleiche Weise: AskUserQuestion und MCP-Tools, deren Server _meta["anthropic/requiresUserInteraction"] setzt, fallen immer in den Callback, auch wenn eine Allow-Regel zutrifft. Im dontAsk Modus werden beide Fälle stattdessen abgelehnt, da dieser Modus niemals auffordert. Die MCP-Anmerkung erfordert Claude Code v2.1.199 oder später.claude.ai Connector Tools, die Ihre Organisation auf ask gesetzt hat, verlassen den Fluss auch in diesem Schritt. Jeder Aufruf fällt in den Callback, auch im bypassPermissions Modus und auch wenn eine Allow-Regel zutrifft. Der Callback erhält den Grund Your organization requires approval for this tool. Im dontAsk Modus wird der Aufruf stattdessen abgelehnt, da dieser Modus niemals auffordert.
4

Berechtigungsmodus

Wenden Sie den aktiven Berechtigungsmodus an:
  • Im bypassPermissions Modus genehmigt Claude Code alles, das diesen Schritt erreicht, außer rm und rmdir Entfernungen, die auf einen kritischen Pfad abzielen, die stattdessen weitergeleitet werden.
  • Im acceptEdits Modus genehmigt Claude Code die unter Accept edits mode aufgelisteten Dateivorgänge.
  • Im plan Modus sendet Claude Code Datei-Edit- und Shell-Write-Tools an Ihren canUseTool Callback unabhängig von Allow-Regeln, damit Schreibvorgänge während der Planung nicht automatisch genehmigt werden können.
  • In anderen Modi fällt die Anfrage durch.
5

Allow-Regeln

Prüfen Sie allow Regeln (aus allowed_tools und settings.json). Wenn eine Regel zutrifft, wird das Tool genehmigt. Ein Aufruf, den das Tool selbst genehmigt, wird auch in diesem Schritt aufgelöst, ohne dass eine Regel erforderlich ist: zum Beispiel ein Dateilesezugriff in Ihren Arbeitsverzeichnissen oder ein schreibgeschützter Bash-Befehl. rm und rmdir Entfernungen, die auf einen kritischen Pfad abzielen, werden niemals durch eine Allow-Regel genehmigt: sie erreichen Ihren Callback in den Modi, die auffordern, gehen zum Klassifizierer im auto Modus auf Claude Code v2.1.218 oder später, und werden im dontAsk Modus abgelehnt.
6

canUseTool Callback

Wenn nicht durch einen der oben genannten Punkte aufgelöst, rufen Sie Ihren canUseTool Callback zur Entscheidung auf. Im dontAsk Modus wird dieser Schritt übersprungen und das Tool wird abgelehnt.Im TypeScript SDK, wenn Sie permissionPrompts: 'none' setzen, wird Ihr Callback in diesem Schritt nicht aufgerufen. Ein PermissionRequest Hook erhält immer noch eine Chance zu entscheiden, und wenn nicht, lehnt Claude Code den Aufruf ab. Die Option erfordert Claude Code v2.1.259 oder später.
Diagramm des sechsstufigen Berechtigungsauswertungsflusses, das den obigen Schritten entspricht: Eine Tool-Anfrage durchläuft Hooks, Deny-Regeln, Ask-Regeln, Berechtigungsmodus, Allow-Regeln und canUseTool. Hooks, Deny-Regeln und canUseTool können zu Blocked weiterleiten; Berechtigungsmodus Bypass, Allow-Regeln und canUseTool können zu Execute weiterleiten; Ask-Regeln leiten zu canUseTool weiter. Diagramm des sechsstufigen Berechtigungsauswertungsflusses, das den obigen Schritten entspricht: Eine Tool-Anfrage durchläuft Hooks, Deny-Regeln, Ask-Regeln, Berechtigungsmodus, Allow-Regeln und canUseTool. Hooks, Deny-Regeln und canUseTool können zu Blocked weiterleiten; Berechtigungsmodus Bypass, Allow-Regeln und canUseTool können zu Execute weiterleiten; Ask-Regeln leiten zu canUseTool weiter. Wenn Sie einen canUseTool Callback in einer Konfiguration übergeben, in der das TypeScript SDK erwartet, dass die Auswertungsreihenfolge Aufrufe automatisch genehmigt, bevor der Callback konsultiert wird, gibt das SDK eine Node.js-Prozesswarnung aus, wenn die Abfrage konstruiert wird. Der Code der Warnung ist CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. Zwei Konfigurationen lösen sie aus: Einträge mit einem Spezifizierer wie Bash(ls *) und der acceptEdits Modus lösen es nicht aus, und Allow-Regeln aus Einstellungsdateien sind für die Prüfung nicht sichtbar. Hören Sie mit process.on('warning', ...) zu und gleichen Sie den Code ab, um ihn zu protokollieren oder zu unterdrücken. Um jeden Tool-Aufruf unabhängig von Modus und Regeln zu steuern, verwenden Sie stattdessen einen PreToolUse Hook. Diese Seite konzentriert sich auf Allow- und Deny-Regeln und Berechtigungsmodi. Für die anderen Schritte:

Allow- und Deny-Regeln

allowed_tools und disallowed_tools (TypeScript: allowedTools / disallowedTools) fügen Einträge zu den Allow- und Deny-Regellisten im obigen Evaluierungsfluss hinzu. Wenn Sie eines der Task-Tracking-Tools in allowed_tools benennen, aktiviert Claude Code auch die Sitzung dafür. Jedes andere Tool, das nicht in allowed_tools aufgelistet ist, ist weiterhin für Claude verfügbar, und ein Aufruf, der Genehmigung benötigt, fällt durch zum Genehmigungsmodus. Deny-Regeln verhalten sich unterschiedlich, je nachdem, ob sie ein Tool benennen oder ein Muster innerhalb eines Tools eingrenzen. Allow-Regeln akzeptieren Tool-Name-Globs nur nach einem literalen mcp__<server>__-Präfix. Das Server-Segment muss glob-frei sein, damit die Regel einen bestimmten Server benennt, den Sie konfiguriert haben: mcp__puppeteer__* entspricht jedem Tool vom puppeteer-Server, und mcp__github__get_* entspricht seinen get_-Tools. Ein unverankter Eintrag wie allowed_tools=["*"] oder allowed_tools=["mcp__*"] wird mit einer Startwarnmeldung ignoriert und genehmigt nichts automatisch. Begrenzte Regeln für Read und Edit verwenden ein Pfadmuster. Edit(path)-Regeln regeln alle integrierten Tools, die Dateien schreiben, einschließlich Write und NotebookEdit; eine Write(path)-Regel wird niemals durch die Dateiberechtigungsprüfungen abgeglichen. Verwenden Sie //path für einen absoluten Dateisystempfad: eine Deny-Regel von Edit(//secrets/**) blockiert Schreibvorgänge überall unter /secrets auf der Festplatte. Mit einem einzelnen führenden Schrägstrich verankert Edit(/secrets/**) stattdessen an der Quelle der Regel. Für Regeln, die durch allowed_tools oder disallowed_tools übergeben werden, bedeutet das das Arbeitsverzeichnis der Sitzung, daher blockiert die Regel nicht /secrets auf der Festplatte. Siehe Read- und Edit-Regeln für die vier Ankerformen und wie Regeln aus Einstellungsdateien aufgelöst werden.
Automatisch genehmigte Tools erreichen canUseTool niemals. Ein Tool-Aufruf, der in einem früheren Schritt genehmigt wird, durch acceptEdits oder bypassPermissions oder durch eine Allow-Regel, überspringt Ihren canUseTool-Callback, daher werden Berechtigungsprüfungen, die Sie dort durchführen, für dieses Tool stillschweigend umgangen. AskUserQuestion, MCP-Tools, die mit _meta["anthropic/requiresUserInteraction"] gekennzeichnet sind, Connector-Tools die Ihre Organisation auf ask gesetzt hat, und rm- und rmdir-Entfernungen, die auf einen kritischen Pfad abzielen, erreichen immer noch den Callback, auch wenn eine Allow-Regel passt. Im auto-Modus gehen kritische-Pfad-Entfernungen zum Klassifizierer statt zum Callback, während die anderen hier aufgelisteten Aufrufe ihn immer noch erreichen; das Klassifizierer-Routing erfordert Claude Code v2.1.218 oder später. Im dontAsk-Modus werden diese Aufrufe stattdessen abgelehnt, ohne den Callback aufzurufen.Die Abdeckung hängt von der Form des Eintrags ab: ein bloßer Name wie Read oder mcp__github__get_issue genehmigt automatisch jeden Aufruf dieses Tools außer den oben genannten Ausnahmen, während eine begrenzte Regel wie Bash(npm test *) nur übereinstimmende Aufrufe automatisch genehmigt, und andere Bash-Aufrufe, die Genehmigung benötigen, fallen immer noch durch zum Callback. Für Prüfungen, die bei jedem Tool-Aufruf ausgeführt werden müssen, verwenden Sie einen PreToolUse-Hook: Hooks werden vor jedem anderen Schritt ausgeführt, und eine Hook-Ablehnung gilt auch im bypassPermissions-Modus.
Für einen abgesperrten Agent kombinieren Sie allowedTools mit permissionMode: "dontAsk":
Aufgelistete Tools werden genehmigt, außer den Aktionen, die kein Modus automatisch genehmigt, und jeder andere Aufruf, der sonst eine Aufforderung auslösen würde, wird stattdessen abgelehnt. Aufrufe, die im default-Modus keine Genehmigung benötigen, werden ausgeführt, unabhängig davon, ob Sie sie aufgelistet haben oder nicht, wie z. B. schreibgeschützte Bash-Befehle, Tools wie Agent, die vor dem Ausführen nicht fragen, und Dateileser in Ihren Arbeitsverzeichnissen. Um ein Tool vollständig außerhalb von Claudes Reichweite zu platzieren, fügen Sie seinen bloßen Namen zu disallowedTools hinzu.
allowed_tools schränkt bypassPermissions nicht ein. allowed_tools genehmigt die Tools, die Sie aufgelistet haben, im Voraus. Andere nicht aufgelistete Tools werden nicht durch eine Allow-Regel abgeglichen und fallen durch zum Genehmigungsmodus, wo bypassPermissions sie genehmigt. Das Setzen von allowed_tools=["Read"] zusammen mit permission_mode="bypassPermissions" genehmigt immer noch jedes Tool, einschließlich Bash, Write und Edit. Wenn Sie bypassPermissions benötigen, aber bestimmte Tools blockiert haben möchten, verwenden Sie disallowed_tools.
Sie können auch Allow-, Deny- und Ask-Regeln deklarativ in .claude/settings.json konfigurieren. Diese Regeln werden gelesen, wenn die project-Einstellungsquelle aktiviert ist, was sie für Standard-query()-Optionen ist. Wenn Sie setting_sources (TypeScript: settingSources) explizit setzen, schließen Sie "project" ein, damit sie angewendet werden. Siehe Berechtigungseinstellungen für die Regelsyntax.

Berechtigungsmodi

Berechtigungsmodi bieten globale Kontrolle darüber, wie Claude Tools nutzt. Sie können den Berechtigungsmodus beim Aufrufen von query() festlegen oder ihn während Streaming-Sitzungen dynamisch ändern.

Verfügbare Modi

Das SDK unterstützt diese Berechtigungsmodi:
Subagent-Vererbung: Ein Subagent wird im Berechtigungsmodus der übergeordneten Sitzung ausgeführt, es sei denn, Sie legen permissionMode auf seiner AgentDefinition fest und die übergeordnete Sitzung befindet sich im default-, dontAsk- oder plan-Modus. Auch dann wendet Claude Code nie einen "bypassPermissions"-Wert an. Ein Subagent wird nur dann im bypassPermissions-Modus ausgeführt, wenn die übergeordnete Sitzung selbst dies tut. Die bypassPermissions-Ausnahme erfordert Claude Code v2.1.267 oder später.Subagents können unterschiedliche Systemaufforderungen und weniger eingeschränktes Verhalten als Ihr Hauptagent haben, daher gewährt die Vererbung von bypassPermissions ihnen vollständigen, autonomen Systemzugriff. Die Aktionen, die kein Modus automatisch genehmigt, gelten weiterhin.

Berechtigungsmodus festlegen

Sie können den Berechtigungsmodus einmalig beim Starten einer Abfrage festlegen oder ihn dynamisch ändern, während die Sitzung aktiv ist.
Übergeben Sie permission_mode (Python) oder permissionMode (TypeScript) beim Erstellen einer Abfrage. Dieser Modus gilt für die gesamte Sitzung, es sei denn, er wird dynamisch geändert.

Modusdetails

Bearbeitungsmodus akzeptieren (acceptEdits)

Genehmigt Dateivorgänge automatisch, damit Claude Code bearbeiten kann, ohne zu fragen. Andere Tools (wie Bash-Befehle, die keine Dateisystemvorgänge sind) erfordern weiterhin normale Berechtigungen. Automatisch genehmigte Vorgänge:
  • Dateibearbeitungen (Edit-, Write-Tools)
  • Dateisystembefehle: mkdir, touch, rm, rmdir, mv, cp, sed
Beide gelten nur für Pfade innerhalb des Arbeitsverzeichnisses oder additionalDirectories. Im acceptEdits-Modus genehmigt Claude Code die Anfrage nicht automatisch, wenn Claude:
  • An einem Pfad außerhalb dieses Bereichs arbeitet
  • In einen geschützten Pfad schreibt
  • Einen kritischen Pfad mit rm oder rmdir löscht
Verwenden Sie, wenn: Sie Claudes Bearbeitungen vertrauen und schnellere Iteration wünschen, z. B. während der Prototypenerstellung oder beim Arbeiten in einem isolierten Verzeichnis.

Nicht-Fragen-Modus (dontAsk)

Konvertiert jede Berechtigungsaufforderung in eine Ablehnung, ohne canUseTool aufzurufen. Tools, die von allowed_tools, settings.json Allow-Regeln oder einem Hook vorab genehmigt wurden, werden normal ausgeführt, ebenso wie Aufrufe, die im default-Modus keine Genehmigung benötigen, wie Dateilesevorgänge in Ihren Arbeitsverzeichnissen und Aufrufe an Agent. Connector-Tools die Ihre Organisation auf ask gesetzt hat, Tools, die Benutzerinteraktion erfordern, und rm und rmdir Löschungen, die auf einen kritischen Pfad abzielen, werden abgelehnt, auch wenn eine Allow-Regel übereinstimmt. Ein PreToolUse-Hook-Allow hebt auch eine kritische Pfad-Löschung nicht auf. Verwenden Sie, wenn: Sie eine feste, explizite Tool-Oberfläche für einen Headless-Agent wünschen und eine harte Ablehnung gegenüber stiller Abhängigkeit von fehlender canUseTool bevorzugen.

Berechtigungen umgehen-Modus (bypassPermissions)

Genehmigt Tool-Nutzungen automatisch ohne Aufforderung, außer in den unten aufgeführten Fällen. Hooks werden weiterhin ausgeführt und können Vorgänge bei Bedarf blockieren.
Mit äußerster Vorsicht verwenden. Claude hat in diesem Modus vollständigen Systemzugriff. Verwenden Sie nur in kontrollierten Umgebungen, in denen Sie allen möglichen Vorgängen vertrauen.allowed_tools beschränkt diesen Modus nicht. Jedes Tool wird genehmigt, nicht nur die, die Sie aufgelistet haben. Diese Kontrollen gelten weiterhin:

Planungsmodus (plan)

Claude erkundet die Codebasis und erstellt einen Plan, ohne Ihre Quelldateien zu bearbeiten. Read-only-Tools werden wie im default-Berechtigungsmodus ausgeführt. Dateibearbeitungen werden im Planungsmodus nie automatisch genehmigt, auch wenn eine Allow-Regel übereinstimmt. Sie werden stattdessen durch Ihren canUseTool-Callback abgefragt. In Claude Code v2.1.212 oder später erreichen Shell-Befehle, die Dateien ändern, wie touch und rm, Ihren canUseTool-Callback auf die gleiche Weise. Claude kann AskUserQuestion verwenden, um Anforderungen zu klären, bevor der Plan abgeschlossen wird. Siehe Genehmigungen und Benutzereingaben verarbeiten für die Verarbeitung dieser Aufforderungen. Verwenden Sie, wenn: Sie möchten, dass Claude Änderungen vorschlägt, ohne sie auszuführen, z. B. während einer Code-Überprüfung oder wenn Sie Änderungen genehmigen müssen, bevor sie vorgenommen werden. Für die anderen Schritte im Genehmigungsbewertungsfluss: