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:

1. Berechtigungsmodi - Globale Berechtigungsverhalten-Einstellungen, die alle Tools betreffen
2. canUseTool-Callback - Laufzeit-Berechtigungshandler für Fälle, die nicht von anderen Regeln abgedeckt werden
3. Hooks - Feinabstimmung der Kontrolle über jede Tool-Ausführung mit benutzerdefinierter Logik
4. 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

%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D"}, "flowchart": {"edgeLabelMarginX": 12, "edgeLabelMarginY": 8}}}%%
flowchart TD
    Start([Tool-Anfrage]) --> PreHook(PreToolUse Hook)

    PreHook -->|  Erlauben  | Execute(Tool ausführen)
    PreHook -->|  Verweigern  | Denied(Verweigert)
    PreHook -->|  Fragen  | Callback(canUseTool Callback)
    PreHook -->|  Fortfahren  | Deny(Verweigerungs-Regeln prüfen)

    Deny -->|  Übereinstimmung  | Denied
    Deny -->|  Keine Übereinstimmung  | Allow(Erlaubnis-Regeln prüfen)

    Allow -->|  Übereinstimmung  | Execute
    Allow -->|  Keine Übereinstimmung  | Ask(Frage-Regeln prüfen)

    Ask -->|  Übereinstimmung  | Callback
    Ask -->|  Keine Übereinstimmung  | Mode{Berechtigungsmodus?}

    Mode -->|  bypassPermissions  | Execute
    Mode -->|  Andere Modi  | Callback

    Callback -->|  Erlauben  | Execute
    Callback -->|  Verweigern  | Denied

    Denied --> DeniedResponse([Rückmeldung an Agent])

    Execute --> PostHook(PostToolUse Hook)
    PostHook --> Done([Tool-Antwort])

    style Start fill:#F0F0EB,stroke:#D9D8D5,color:#191919

    style Denied fill:#BF4D43,color:#fff
    style DeniedResponse fill:#BF4D43,color:#fff
    style Execute fill:#DAAF91,color:#191919
    style Done fill:#DAAF91,color:#191919

    classDef hookClass fill:#CC785C,color:#fff
    class PreHook,PostHook hookClass

    classDef ruleClass fill:#EBDBBC,color:#191919
    class Deny,Allow,Ask ruleClass

    classDef modeClass fill:#A8DAEF,color:#191919
    class Mode modeClass

    classDef callbackClass fill:#D4A27F,color:#191919
    class Callback callbackClass

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:

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:

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);
}

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:

1. Hooks werden zuerst ausgeführt - Können erlauben, verweigern, fragen oder fortfahren
2. Verweigerungs-Regeln werden geprüft - Blockieren Tools unabhängig vom Modus
3. Erlaubnis-Regeln werden geprüft - Erlauben Tools bei Übereinstimmung
4. Frage-Regeln werden geprüft - Fordern Berechtigung bei Übereinstimmung
5. Berechtigungsmodus wird bewertet:
   • bypassPermissions-Modus - Wenn aktiv, erlaubt alle verbleibenden Tools
   • Andere Modi - Übertragen an canUseTool-Callback
6. 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

1. Verwenden Sie den Standard-Modus für kontrollierte Ausführung mit normalen Berechtigungsprüfungen
2. Verwenden Sie acceptEdits-Modus beim Arbeiten an isolierten Dateien oder Verzeichnissen
3. Vermeiden Sie bypassPermissions in der Produktion oder auf Systemen mit sensiblen Daten
4. Kombinieren Sie Modi mit Hooks für feinabgestimmte Kontrolle
5. 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:

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);
    }
  }
});

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