SpyBara
Go Premium

agent-sdk/permissions.md 2026-10-25 23:58 UTC to 2026-10-26 22:57 UTC

This page contains 48 additions and 19 deletions.

2026
Thu 1 23:59 Fri 9 23:02 Sat 10 23:01 Sat 17 23:57 Mon 19 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Mon 26 22:57 Tue 27 22:59 Fri 30 23:01

Berechtigungen konfigurieren

Kontrollieren Sie, wie Ihr Agent Tools mit Berechtigungsmodi, Hooks und deklarativen Allow/Deny-Regeln verwendet.

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

[!NOTE]

Wenn Sie ein Plugin laden, das einen Mod enthält, erfahren Sie unter wo sich die Entscheidungen eines Mods zwischen Regeln und Hooks einordnen mehr.

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, der allow zurückgibt, kann außerdem keinen rm- oder rmdir-Befehl genehmigen, dessen Ziel Claude Code als kritischen Pfad erkennt, etwa rm -rf ~. Was dieses allow im Plan-Modus bewirkt, erfahren Sie unter Hook-Genehmigungen im Plan-Modus.

2. Deny-Regeln

Wenn eine Deny-Regel aus disallowed_tools oder settings.json zutrifft, wird der Aufruf abgelehnt und canUseTool wird nicht aufgerufen, selbst im bypassPermissions Modus und selbst wenn ein Hook allow zurückgegeben hat.

Wenn Sie im TypeScript SDK die permission_policy eines benutzerdefinierten Tools auf always_deny setzen, wird ein Aufruf dieses Tools in diesem Schritt abgelehnt.

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.

Wenn Sie im TypeScript SDK die permission_policy eines benutzerdefinierten Tools auf always_ask setzen, genehmigt keine Allow-Regel dessen Aufrufe, nicht einmal ein allowedTools-Eintrag. Im dontAsk Modus lehnt Claude Code diese Aufrufe ab, und im auto, plan oder bypassPermissions Modus kann es sie genehmigen, bevor Ihr Callback ausgeführt wird.

4. Berechtigungsmodus

Wenden Sie den aktiven Berechtigungsmodus an:

  • Im bypassPermissions Modus genehmigt Claude Code alles, das diesen Schritt erreicht, außer erkannten Entfernungen kritischer Pfade und Bash-Befehlen, die mit Dangerous rm operation not ruled out markiert sind; diese werden stattdessen weitergeleitet.
  • Im acceptEdits Modus genehmigt Claude Code die unter Accept edits mode aufgelisteten Dateivorgänge.
  • Im plan Modus sendet Claude Code Tools zur Dateibearbeitung unabhängig von Allow-Regeln an Ihren canUseTool Callback.
  • 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 nur lesender Bash-Befehl.

Erkannte Entfernungen kritischer Pfade werden nicht durch eine Allow-Regel genehmigt, und mit Dangerous rm operation not ruled out markierte Befehle werden nicht durch eine Bash- oder Bash(*)-Regel genehmigt. Ob sie dann Ihren Callback erreichen, hängt vom Berechtigungsmodus ab: in einer Agent SDK Sitzung im auto Modus lehnt Claude Code sie beispielsweise standardmäßig ab, ohne ihn aufzurufen. Die Modustabelle für kritische Pfade listet auf, was jeder Modus mit ihnen tut.

Eine Allow-Regel genehmigt keinen Lesezugriff auf einen Netzwerkpfad.

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, wobei ein von Ihnen installierter Mod einige solcher Aufrufe dennoch genehmigen kann.

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.

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:

  • permissionMode: 'bypassPermissions': Der Warnungstext beginnt mit canUseTool will not be invoked: permissionMode 'bypassPermissions'. Tool-Aufrufe werden genehmigt, bevor canUseTool konsultiert wird, sodass Ihr Callback nur für wenige Aufrufe ausgeführt wird, etwa für die unter Bypass permissions mode aufgeführten Aufrufe. Um auch die genehmigten Aufrufe zu prüfen, verlagern Sie die Prüfungen Ihres Callbacks in einen PreToolUse Hook
  • Ein allowedTools-Eintrag, der nur aus einem Tool-Namen besteht, etwa "Read": Die Warnung listet jeden solchen Eintrag nach canUseTool will not be invoked for: auf. Aufrufe eines aufgeführten Tools werden genehmigt, bevor canUseTool konsultiert wird, abgesehen von den Aufrufen, die eine Allow-Regel nie genehmigt. Damit Ihr Callback für Aufrufe eines aufgeführten Tools ausgeführt wird, die eine Genehmigung benötigen, entfernen Sie den Eintrag dieses Tools aus allowedTools

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.

Die Warnung blockiert keinen Aufruf und ändert keine Option. Wenn Ihr Callback bereits jeden Aufruf erhält, den Sie prüfen möchten, lassen Sie Ihre Konfiguration unverändert. Um die Warnung zu protokollieren, hören Sie mit process.on('warning', ...) zu und gleichen Sie den Code CLAUDE_SDK_CAN_USE_TOOL_SHADOWED ab.

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.

Option Auswirkung
allowed_tools=["Read", "Grep"] Read und Grep werden automatisch genehmigt, abgesehen von Lesezugriffen auf Netzwerkpfade. Andere Tools, die hier nicht aufgelistet sind, existieren weiterhin, und Aufrufe, die Genehmigung benötigen, fallen durch zum Berechtigungsmodus und canUseTool.
disallowed_tools=["Bash"] Die Bash-Tool-Definition wird aus der Anfrage entfernt. Claude sieht das Tool nicht und kann es nicht versuchen.
disallowed_tools=["Bash(rm *)"] Bash bleibt verfügbar. Aufrufe, die rm * wie geschrieben entsprechen, werden in jedem Genehmigungsmodus abgelehnt, einschließlich bypassPermissions. Andere Bash-Aufrufe, einschließlich /bin/rm, fallen durch zum Genehmigungsmodus.
disallowed_tools=["*"] Jede Tool-Definition wird aus der Anfrage entfernt. Tool-Name-Globs werden in Deny-Regeln unterstützt: "*" entspricht jedem Tool und "mcp__*" entspricht jedem MCP-Tool über alle Server hinweg.

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 unverankerter Eintrag wie allowed_tools=["*"] oder allowed_tools=["mcp__*"] wird 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.

[!WARNING]

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.

Wenn Aufrufe eines Tools in allowed_tools dennoch Ihren canUseTool-Callback erreichen oder im dontAsk-Modus abgelehnt werden, prüfen Sie, ob es sich um Lesezugriffe auf Netzwerkpfade oder um einen der folgenden Aufrufe handelt. Keine Allow-Regel genehmigt diese Aufrufe. Im dontAsk-Modus, der nie nachfragt, lehnt Claude Code sie ab, ohne canUseTool aufzurufen, und in den anderen Berechtigungsmodi behandeln Sie sie so, wie es der jeweilige Punkt beschreibt:

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":

const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk"
};

Die aufgelisteten Read-, Glob- und Grep-Aufrufe werden genehmigt, außer den Aktionen, die kein Modus automatisch genehmigt, und Lesezugriffen auf Netzwerkpfade. Jeder andere Aufruf, der sonst eine Berechtigungsabfrage auslösen würde, wird stattdessen abgelehnt, wobei ein von Ihnen installierter Mod einige dieser Aufrufe dennoch genehmigen kann.

Aufrufe, die im default-Modus keine Genehmigung benötigen, werden ausgeführt, unabhängig davon, ob Sie sie aufgelistet haben oder nicht. Dazu gehören nur lesende Bash-Befehle, Tools wie Agent, die vor dem Ausführen nicht fragen, und Dateilesevorgänge in Ihren Arbeitsverzeichnissen. Um ein integriertes Tool vollständig vor Claude zu verbergen, statt seine Aufrufe abzulehnen, fügen Sie seinen bloßen Namen zu disallowedTools hinzu.

[!WARNING]

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.

Ab Claude Code v2.1.302 startet Ihre App im default-Modus, sofern Sie keinen Berechtigungsmodus festlegen und sie keinen aus permissions.defaultMode in ihren Einstellungsdateien erhält. Im default-Modus lehnt Claude Code jeden Tool-Aufruf ab, der eine Genehmigung benötigt, es sei denn, Sie genehmigen ihn über eine Allow-Regel, einen Hook, einen canUseTool-Callback oder ein Berechtigungsabfrage-Tool. Wenn Tool-Aufrufe abgelehnt werden, siehe Tool-Aufrufe in claude -p- und Agent SDK-Ausführungen abgelehnt.

Verfügbare Modi

Das SDK unterstützt diese Berechtigungsmodi:

Modus Beschreibung Tool-Verhalten
default Standardberechtigungsverhalten Keine modusbasierten automatischen Genehmigungen; Aufrufe, die eine Genehmigung benötigen und keine Allow-Regel erfüllen, lösen Ihren canUseTool-Callback aus
dontAsk Ablehnung statt Nachfrage Jeder Aufruf, der sonst eine Nachfrage auslösen würde, wird abgelehnt, ohne canUseTool aufzurufen, wobei ein von Ihnen installierter Mod einige dieser Aufrufe dennoch genehmigen kann. Aufrufe, die von allowed_tools oder settings.json-Allow-Regeln genehmigt werden, werden ausgeführt, ebenso wie Aufrufe, die im default-Modus keine Genehmigung benötigen. Einige Aufrufe, wie Lesezugriffe auf Netzwerkpfade, werden abgelehnt, auch wenn allowed_tools oder eine Allow-Regel auf sie zutrifft. Die Liste finden Sie unter Nicht-Fragen-Modus
acceptEdits Dateibearbeitungen automatisch akzeptieren Dateibearbeitungen und Dateisystemoperationen (mkdir, rm, mv usw.) werden automatisch genehmigt
bypassPermissions Berechtigungsprüfungen umgehen Tools werden ohne Berechtigungsabfragen ausgeführt, außer für die Aktionen, die kein Modus automatisch genehmigt und, außerhalb einer Cloud-Sitzung, benutzerdefinierte Tools, die Ihre Anwendung als always_ask kennzeichnet. Mit Vorsicht verwenden
plan Planungsmodus Claude erkundet und plant, ohne Ihre Quelldateien zu bearbeiten; Dateibearbeitungen werden nie automatisch genehmigt und werden durch Ihren canUseTool-Callback abgefragt
auto Modellklassifizierte Genehmigungen Ein Modellklassifizierer überprüft Aktionen wie Shell-Befehle und Netzwerkanfragen und genehmigt oder blockiert jede überprüfte Aktion. Siehe Auto-Modus für Verfügbarkeit und die Entscheidungsreihenfolge

[!WARNING]

Subagent-Vererbung: Wenn sich Ihre Hauptsitzung im Plan-Modus befindet, wird ein Subagent, dessen AgentDefinition permissionMode: "acceptEdits" festlegt, dennoch im Plan-Modus ausgeführt. Die Edit- und Write-Aufrufe dieses Subagenten auf Ihre Quelldateien gehen weiterhin an Ihren canUseTool-Callback. Der Plan-Modus gilt auch für die von Ihnen definierten Subagenten, sodass das Übergeben von Arbeit an einen Subagenten die vorherige Überprüfung des Plans nicht umgeht.

Der Subagent erbt plan, acceptEdits, auto oder bypassPermissions von der Hauptsitzung, und unter einer Hauptsitzung im default- oder dontAsk-Modus wird er in dem von Ihnen festgelegten Modus ausgeführt. Auch dann wendet Claude Code nie einen "bypassPermissions"-Wert an und wendet einen "auto"-Wert nur dann an, wenn der Auto-Modus für diesen Subagenten verfügbar ist. 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.

Zum Abfragezeitpunkt

Übergeben Sie permission_mode (Python) oder permissionMode (TypeScript) beim Erstellen einer Abfrage.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Help me refactor this code",
        options=ClaudeAgentOptions(
            permission_mode="default",  # Set the mode here
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

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

async function main() {
  for await (const message of query({
    prompt: "Help me refactor this code",
    options: {
      permissionMode: "default" // Set the mode here
    }
  })) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

Während des Streaming

Rufen Sie set_permission_mode() (Python) oder setPermissionMode() (TypeScript) auf, um den Modus während der Sitzung zu ändern. Der neue Modus wird sofort für alle nachfolgenden Tool-Anfragen wirksam. Dies ermöglicht es Ihnen, restriktiv zu beginnen und die Berechtigungen zu lockern, wenn Vertrauen aufgebaut wird, z. B. durch Wechsel zu acceptEdits nach Überprüfung von Claudes anfänglichem Ansatz.

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions


async def main():
    async with ClaudeSDKClient(
        options=ClaudeAgentOptions(
            permission_mode="default",  # Start in default mode
        )
    ) as client:
        await client.query("Help me refactor this code")

        # Change mode dynamically mid-session
        await client.set_permission_mode("acceptEdits")

        # Process messages with the new permission mode
        async for message in client.receive_response():
            if hasattr(message, "result"):
                print(message.result)


asyncio.run(main())

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

async function main() {
  const q = query({
    prompt: "Help me refactor this code",
    options: {
      permissionMode: "default" // Start in default mode
    }
  });

  // Change mode dynamically mid-session
  await q.setPermissionMode("acceptEdits");

  // Process messages with the new permission mode
  for await (const message of q) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

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 Pfad, den Claude Code als kritischen Pfad erkennt, mit rm oder rmdir löscht
  • touch beispielsweise mit einer Option, einem Glob oder einem Präfix wie timeout 5 oder LANG=C ausführt

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 Berechtigungsabfrage in eine Ablehnung, ohne canUseTool aufzurufen, wobei ein von Ihnen installierter Mod einige dieser Aufrufe dennoch genehmigen kann. Tools, die von allowed_tools, settings.json-Allow-Regeln oder einem Hook vorab genehmigt wurden, werden normal ausgeführt. Aufrufe, die im default-Modus keine Genehmigung benötigen, werden ebenfalls ausgeführt, wie Dateilesevorgänge in Ihren Arbeitsverzeichnissen und Aufrufe an Agent.

Diese Aufrufe werden abgelehnt, auch wenn eine Allow-Regel übereinstimmt:

Wenn Ihr PreToolUse-Hook allow für eine erkannte Löschung eines kritischen Pfads, einen Lesezugriff auf einen Netzwerkpfad oder einen Aufruf eines als always_ask gekennzeichneten Tools zurückgibt, wird der Aufruf dennoch abgelehnt. Die Prüfung, die diese Löschungen erkennt, kann einige Befehle übersehen.

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 Nachfrage, außer bei den Aktionen, die kein Modus automatisch genehmigt. Hooks werden weiterhin ausgeführt und können Vorgänge bei Bedarf blockieren. Auf Linux und macOS weigert sich Claude Code, in diesem Modus als Root oder unter sudo außerhalb einer erkannten Sandbox zu starten, und die Abfrage schlägt vor dem ersten Turn fehl.

[!WARNING]

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. Dateibearbeitungen werden im Plan-Modus nie automatisch genehmigt, auch wenn eine Allow-Regel übereinstimmt oder ein PreToolUse-Hook allow zurückgibt. Sie werden stattdessen durch Ihren canUseTool-Callback abgefragt.

Solange der Auto-Modus für die Sitzung verfügbar ist, erreichen Befehle, die Claude während der Planung ausführt, Ihren Callback standardmäßig nicht, da das Klassifikatormodell, das der Auto-Modus verwendet, sie stattdessen überprüft. Ist diese Überprüfung aktiv, kann der Klassifikator auch nur lesende Aufrufe genehmigen, die sonst Ihren Callback erreichen würden, etwa einen WebFetch-Aufruf ohne Allow-Regel.

[!NOTE]

Wenn Sie im TypeScript SDK allowDangerouslySkipPermissions: true zusammen mit permissionMode: 'plan' festlegen, erreichen Dateibearbeitungen weiterhin Ihren canUseTool-Callback. Um eine Sitzung, die im Plan-Modus startet, später mit setPermissionMode() auf bypassPermissions umzustellen, muss allowDangerouslySkipPermissions von Anfang an gesetzt sein.

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.

Auto-Modus (auto)

Ein Klassifikatormodell überprüft Aktionen wie Shell-Befehle und Netzwerkanfragen, bevor sie ausgeführt werden, und erlaubt oder blockiert jede überprüfte Aktion. Welche Modelle und Anbieter der Auto-Modus voraussetzt und in welcher Reihenfolge er Aktionen bewertet, erfahren Sie unter Berechtigungsabfragen mit dem Auto-Modus vermeiden.

Wenn Sie eine Sitzung im Auto-Modus mit set_model(), setModel() oder applyFlagSettings() auf ein Modell umstellen, das der Auto-Modus nicht unterstützt, wechselt die Sitzung in den default-Modus:

  • Was Sie sehen: eine system-Nachricht mit dem Subtyp status und permissionMode auf "default" gesetzt, die das TypeScript SDK als SDKStatusMessage typisiert. Ab diesem Zeitpunkt erreichen Aufrufe, die eine Genehmigung benötigen und keine Allow-Regel erfüllen, Ihren canUseTool-Callback.
  • Zurück zum Auto-Modus: Wechseln Sie zu einem unterstützten Modell und rufen Sie dann set_permission_mode("auto") oder setPermissionMode("auto") auf. Wenn Sie das Modell zurückwechseln, ohne diesen Aufruf auszuführen, bleibt die Sitzung im default-Modus. Solange das nicht unterstützte Modell aktiv ist, schlägt der Aufruf mit Cannot set permission mode to auto: auto mode unavailable for this model fehl.

Der Wechsel in den default-Modus nach einem Aufruf von set_model(), setModel() oder applyFlagSettings() erfordert Claude Code v2.1.299 oder später.

Verwandte Ressourcen

Für die anderen Schritte im Genehmigungsbewertungsfluss: