SDK-Berechtigungen

Das Claude Agent SDK bietet leistungsstarke Berechtigungskontrollen, mit denen Sie verwalten können, wie Claude Tools in Ihrer Anwendung verwendet.

Dieser Leitfaden behandelt die Implementierung von Berechtigungssystemen mit dem canUseTool-Callback, Hooks und settings.json-Berechtigungsregeln. Für die vollständige API-Dokumentation siehe die TypeScript SDK-Referenz.

Überblick

Das Claude Agent SDK bietet vier ergänzende Möglichkeiten zur Kontrolle der Tool-Nutzung:

Berechtigungsmodi - Globale Berechtigungsverhalten-Einstellungen, die alle Tools betreffen
canUseTool-Callback - Laufzeit-Berechtigungshandler für Fälle, die nicht von anderen Regeln abgedeckt werden
Hooks - Feinabstimmung der Kontrolle über jede Tool-Ausführung mit benutzerdefinierter Logik
Berechtigungsregeln (settings.json) - Deklarative Erlauben/Verweigern-Regeln mit integrierter Bash-Befehl-Analyse

Anwendungsfälle für jeden Ansatz:

Berechtigungsmodi - Gesamtverhalten der Berechtigungen festlegen (Planung, automatisches Akzeptieren von Bearbeitungen, Umgehung von Prüfungen)
canUseTool - Dynamische Genehmigung für nicht abgedeckte Fälle, fordert Benutzer zur Berechtigung auf
Hooks - Programmatische Kontrolle über alle Tool-Ausführungen
Berechtigungsregeln - Statische Richtlinien mit intelligenter Bash-Befehl-Analyse

Berechtigungsfluss-Diagramm

Verarbeitungsreihenfolge: PreToolUse Hook → Verweigerungs-Regeln → Erlaubnis-Regeln → Frage-Regeln → Berechtigungsmodus-Prüfung → canUseTool Callback → PostToolUse Hook

Berechtigungsmodi

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

Verfügbare Modi

Das SDK unterstützt vier Berechtigungsmodi, jeder mit unterschiedlichem Verhalten:

Modus	Beschreibung	Tool-Verhalten
`default`	Standard-Berechtigungsverhalten	Normale Berechtigungsprüfungen gelten
`plan`	Planungsmodus - keine Ausführung	Claude kann nur schreibgeschützte Tools verwenden; präsentiert einen Plan vor der Ausführung (Derzeit nicht im SDK unterstützt)
`acceptEdits`	Datei-Bearbeitungen automatisch akzeptieren	Datei-Bearbeitungen und Dateisystem-Operationen werden automatisch genehmigt
`bypassPermissions`	Alle Berechtigungsprüfungen umgehen	Alle Tools laufen ohne Berechtigungsaufforderungen (mit Vorsicht verwenden)

Berechtigungsmodus festlegen

Sie können den Berechtigungsmodus auf zwei Arten festlegen:

1. Anfangskonfiguration

Legen Sie den Modus beim Erstellen einer Abfrage fest:

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

const result = await query({
  prompt: "Hilf mir, diesen Code zu refaktorieren",
  options: {
    permissionMode: 'default'  // Standard-Berechtigungsmodus
  }
});

2. Dynamische Modusänderungen (nur Streaming)

Ändern Sie den Modus während einer Streaming-Sitzung:

Modus-spezifische Verhaltensweisen

Bearbeitungen akzeptieren-Modus (`acceptEdits`)

Im Bearbeitungen akzeptieren-Modus:

Alle Datei-Bearbeitungen werden automatisch genehmigt
Dateisystem-Operationen (mkdir, touch, rm, etc.) werden automatisch genehmigt
Andere Tools erfordern noch normale Berechtigungen
Beschleunigt die Entwicklung, wenn Sie Claudes Bearbeitungen vertrauen
Nützlich für schnelle Prototypenerstellung und Iterationen

Automatisch genehmigte Operationen:

Datei-Bearbeitungen (Edit, Write Tools)
Bash-Dateisystem-Befehle (mkdir, touch, rm, mv, cp)
Dateierstellung und -löschung

Berechtigungen umgehen-Modus (`bypassPermissions`)

Im Berechtigungen umgehen-Modus:

ALLE Tool-Verwendungen werden automatisch genehmigt
Keine Berechtigungsaufforderungen erscheinen
Hooks werden noch ausgeführt (können Operationen noch blockieren)
Mit äußerster Vorsicht verwenden - Claude hat vollen Systemzugriff
Nur für kontrollierte Umgebungen empfohlen

Modus-Priorität im Berechtigungsfluss

Berechtigungsmodi werden an einem bestimmten Punkt im Berechtigungsfluss bewertet:

Hooks werden zuerst ausgeführt - Können erlauben, verweigern, fragen oder fortfahren
Verweigerungs-Regeln werden geprüft - Blockieren Tools unabhängig vom Modus
Erlaubnis-Regeln werden geprüft - Erlauben Tools bei Übereinstimmung
Frage-Regeln werden geprüft - Fordern Berechtigung bei Übereinstimmung
Berechtigungsmodus wird bewertet:
- bypassPermissions-Modus - Wenn aktiv, erlaubt alle verbleibenden Tools
- Andere Modi - Übertragen an canUseTool-Callback
canUseTool-Callback - Behandelt verbleibende Fälle

Das bedeutet:

Hooks können die Tool-Verwendung immer kontrollieren, auch im bypassPermissions-Modus
Explizite Verweigerungs-Regeln überschreiben alle Berechtigungsmodi
Frage-Regeln werden vor Berechtigungsmodi bewertet
bypassPermissions-Modus überschreibt den canUseTool-Callback für nicht übereinstimmende Tools

Bewährte Praktiken

Verwenden Sie den Standard-Modus für kontrollierte Ausführung mit normalen Berechtigungsprüfungen
Verwenden Sie acceptEdits-Modus beim Arbeiten an isolierten Dateien oder Verzeichnissen
Vermeiden Sie bypassPermissions in der Produktion oder auf Systemen mit sensiblen Daten
Kombinieren Sie Modi mit Hooks für feinabgestimmte Kontrolle
Wechseln Sie Modi dynamisch basierend auf Aufgabenfortschritt und Vertrauen

Beispiel für Modus-Progression:

// Im Standard-Modus für kontrollierte Ausführung beginnen
permissionMode: 'default'

// Zu acceptEdits für schnelle Iteration wechseln
await q.setPermissionMode('acceptEdits')

canUseTool

Der canUseTool-Callback wird als Option beim Aufruf der query-Funktion übergeben. Er erhält den Tool-Namen und Eingabeparameter und muss eine Entscheidung zurückgeben - entweder erlauben oder verweigern.

canUseTool wird ausgelöst, wann immer Claude Code eine Berechtigungsaufforderung an einen Benutzer zeigen würde, z.B. Hooks und Berechtigungsregeln decken es nicht ab und es ist nicht im acceptEdits-Modus.

Hier ist ein vollständiges Beispiel, das zeigt, wie interaktive Tool-Genehmigung implementiert wird:

Verwandte Ressourcen

Hooks-Leitfaden - Lernen Sie, wie Sie Hooks für feinabgestimmte Kontrolle über Tool-Ausführung implementieren
Einstellungen: Berechtigungsregeln - Konfigurieren Sie deklarative Erlauben/Verweigern-Regeln mit Bash-Befehl-Analyse

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

// Erstellen Sie einen asynchronen Generator für Streaming-Eingabe
async function* streamInput() {
  yield { 
    type: 'user',
    message: { 
      role: 'user', 
      content: "Lass uns mit Standard-Berechtigungen beginnen" 
    }
  };
  
  // Später im Gespräch...
  yield {
    type: 'user',
    message: {
      role: 'user',
      content: "Jetzt lass uns die Entwicklung beschleunigen"
    }
  };
}

const q = query({
  prompt: streamInput(),
  options: {
    permissionMode: 'default'  // Im Standard-Modus beginnen
  }
});

// Modus dynamisch ändern
await q.setPermissionMode('acceptEdits');

// Nachrichten verarbeiten
for await (const message of q) {
  console.log(message);
}

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

async function promptForToolApproval(toolName: string, input: any) {
  console.log("\n🔧 Tool-Anfrage:");
  console.log(`   Tool: ${toolName}`);
  
  // Tool-Parameter anzeigen
  if (input && Object.keys(input).length > 0) {
    console.log("   Parameter:");
    for (const [key, value] of Object.entries(input)) {
      let displayValue = value;
      if (typeof value === 'string' && value.length > 100) {
        displayValue = value.substring(0, 100) + "...";
      } else if (typeof value === 'object') {
        displayValue = JSON.stringify(value, null, 2);
      }
      console.log(`     ${key}: ${displayValue}`);
    }
  }
  
  // Benutzer-Genehmigung einholen (ersetzen Sie durch Ihre UI-Logik)
  const approved = await getUserApproval();
  
  if (approved) {
    console.log("   ✅ Genehmigt\n");
    return {
      behavior: "allow",
      updatedInput: input
    };
  } else {
    console.log("   ❌ Verweigert\n");
    return {
      behavior: "deny",
      message: "Benutzer hat die Berechtigung für dieses Tool verweigert"
    };
  }
}

// Den Berechtigungs-Callback verwenden
const result = await query({
  prompt: "Hilf mir, diese Codebasis zu analysieren",
  options: {
    canUseTool: async (toolName, input) => {
      return promptForToolApproval(toolName, input);
    }
  }
});

Berechtigungen verwalten

Berechtigungen verwalten

SDK-Berechtigungen

Überblick

Berechtigungsfluss-Diagramm

Berechtigungsmodi

Verfügbare Modi

Berechtigungsmodus festlegen

1. Anfangskonfiguration

2. Dynamische Modusänderungen (nur Streaming)

Modus-spezifische Verhaltensweisen

Bearbeitungen akzeptieren-Modus (`acceptEdits`)

Berechtigungen umgehen-Modus (`bypassPermissions`)

Modus-Priorität im Berechtigungsfluss

Bewährte Praktiken

canUseTool

Verwandte Ressourcen

SDK-Berechtigungen

Überblick

Berechtigungsfluss-Diagramm

Berechtigungsmodi

Verfügbare Modi

Berechtigungsmodus festlegen

1. Anfangskonfiguration

2. Dynamische Modusänderungen (nur Streaming)

Modus-spezifische Verhaltensweisen

Bearbeitungen akzeptieren-Modus (acceptEdits)

Berechtigungen umgehen-Modus (bypassPermissions)

Modus-Priorität im Berechtigungsfluss

Bewährte Praktiken

canUseTool

Verwandte Ressourcen

Bearbeitungen akzeptieren-Modus (`acceptEdits`)

Berechtigungen umgehen-Modus (`bypassPermissions`)