​
SDK-Berechtigungen

Das Claude Code 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 Code 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

Verarbeitungsreihenfolge: PreToolUse Hook → Ask-Regeln → Deny-Regeln → Berechtigungsmodus-Prüfung → Allow-Regeln → 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:
ModusBeschreibungTool-Verhalten
defaultStandard-BerechtigungsverhaltenNormale Berechtigungsprüfungen gelten
planPlanungsmodus - keine AusführungClaude kann nur schreibgeschützte Tools verwenden; präsentiert einen Plan vor der Ausführung (Derzeit nicht im SDK unterstützt)
acceptEditsDatei-Bearbeitungen automatisch akzeptierenDatei-Bearbeitungen und Dateisystem-Operationen werden automatisch genehmigt
bypassPermissionsAlle Berechtigungsprüfungen umgehenAlle Tools laufen ohne Berechtigungsaufforderungen (mit Vorsicht verwenden)

​
Berechtigungsmodus festlegen

Sie können den Berechtigungsmodus auf zwei Arten festlegen:

​
1. Anfangskonfiguration

Setzen Sie den Modus beim Erstellen einer Abfrage: 
import { query } from "@anthropic-ai/claude-code";

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-code";

// Erstellen Sie einen asynchronen Generator für Streaming-Input
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

​
Accept Edits-Modus (acceptEdits)

Im Accept Edits-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, MultiEdit, Write-Tools)
  • Bash-Dateisystem-Befehle (mkdir, touch, rm, mv, cp)
  • Dateierstellung und -löschung

​
Bypass Permissions-Modus (bypassPermissions)

Im Bypass Permissions-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 jeden Modus überschreiben
  2. Deny-Regeln werden geprüft - Blockieren Tools unabhängig vom Modus
  3. bypassPermissions-Modus - Wenn aktiv, erlaubt alle verbleibenden Tools
  4. Allow-Regeln werden geprüft
  5. Andere Modi beeinflussen spezifische Tool-Verhaltensweisen
  6. canUseTool-Callback - Behandelt verbleibende Fälle
Das bedeutet:
  • Hooks können Tool-Verwendung immer blockieren, auch im bypassPermissions-Modus
  • Explizite Deny-Regeln überschreiben alle Berechtigungsmodi
  • bypassPermissions-Modus überschreibt Allow-Regeln und canUseTool

​
Best Practices

  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 einem Benutzer eine Berechtigungsaufforderung zeigen würde, z.B. Hooks und Berechtigungsregeln decken es nicht ab und es ist nicht im Autoaccept-Modus. Hier ist ein vollständiges Beispiel, das zeigt, wie interaktive Tool-Genehmigung implementiert wird: 
import { query } from "@anthropic-ai/claude-code";

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

​
Hooks für Tool-Kontrolle verwenden

Hooks bieten programmatische Kontrolle über Tool-Ausführung in verschiedenen Phasen. Hooks werden für jede Tool-Verwendung aufgerufen und geben Ihnen vollständige Kontrolle über die Berechtigungs-Pipeline.

​
Hook-Implementierung

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

const result = await query({
  prompt: "Hilf mir, diesen Code zu refaktorieren",
  options: {
    hooks: {
      PreToolUse: [{
        hooks: [async (input, toolUseId, { signal }) => {
          console.log(`Tool-Anfrage: ${input.tool_name}`);
          
          // Tool-Input selbst parsen und validieren
          if (input.tool_name === "Bash") {
            const command = input.tool_input.command;
            if (command.startsWith("rm -rf")) {
              return {
                decision: "block",
                reason: "Gefährlicher Befehl blockiert"
              };
            }
          }
          
          return { continue: true };
        }]
      }],
      PostToolUse: [{
        hooks: [async (input, toolUseId, { signal }) => {
          console.log(`Tool abgeschlossen: ${input.tool_name}`);
          // Tool-Ergebnisse protokollieren oder auditieren
          return { continue: true };
        }]
      }]
    }
  }
});

​
Hauptunterschiede zu canUseTool

  • Umfang: Hooks werden für alle Tool-Verwendungen aufgerufen; canUseTool behandelt Fälle, die nicht von Berechtigungsregeln abgedeckt werden
  • Kontrolle: Hooks erfordern das selbständige Parsen und Validieren von Eingaben
  • Ereignisse: Hooks unterstützen mehrere Ereignisse (PreToolUse, PostToolUse, etc.) für verschiedene Phasen

​
Berechtigungsregeln verwenden (settings.json)

Berechtigungsregeln in settings.json bieten deklarative Kontrolle mit eingebauter Bash-Befehl-Analyse. Diese Regeln werden vor dem Aufruf von canUseTool bewertet. Für weitere Details zur Einstellungskonfiguration siehe die Claude Code-Einstellungsdokumentation.

​
Konfigurationsstruktur

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./secrets/**)",
      "WebFetch"
    ],
    "ask": [
      "Bash(git push:*)",
      "Write(./production/**)"
    ]
  }
}

​
Regel-Syntax

Berechtigungsregeln folgen dem Muster: ToolName(pattern)
  • Bash-Regeln: Verwenden Präfix-Matching (nicht Regex). Beispiel: Bash(npm:*) passt zu jedem Befehl, der mit “npm” beginnt
  • Datei-Regeln: Unterstützen Glob-Muster. Beispiel: Read(./src/**/*.ts) passt zu TypeScript-Dateien in src
  • Nur-Tool-Regeln: Lassen Klammern weg, um ganze Tools zu kontrollieren. Beispiel: WebFetch blockiert alle Web-Fetches

​
Verwendung mit SDK

Während Regeln noch nicht programmatisch im SDK gesetzt werden können, werden sie aus der settings.json-Datei im Pfad gelesen, in dem das SDK geladen wird.

​
Berechtigungsauswertungsreihenfolge

  1. Deny-Regeln werden zuerst geprüft - wenn übereinstimmend, wird Tool-Verwendung blockiert
  2. Allow-Regeln werden als nächstes geprüft - wenn übereinstimmend, wird Tool-Verwendung erlaubt
  3. Ask-Regeln werden geprüft - wenn übereinstimmend, wird Benutzer aufgefordert
  4. canUseTool-Callback wird für alle verbleibenden Fälle aufgerufen

​
Bash-Befehl-Analyse

Das SDK enthält einen integrierten Bash-Parser, der Befehlsstruktur versteht:
  • Behandelt Pipes, Umleitungen und Befehlssubstitution
  • Erkennt gefährliche Muster wie rm -rf oder curl | sh
  • Unterstützt Wildcards und Präfix-Matching
Beispiel, wie Bash-Muster funktionieren:
  • Bash(git:*) - Passt zu jedem git-Befehl
  • Bash(npm run test) - Passt zu exaktem Befehl
  • Bash(npm run test:*) - Passt zu npm run test:unit, test:integration, etc.

​
Best Practices

  1. Beginnen Sie mit dem Standard-Modus für Standard-Berechtigungsprüfungen
  2. Verwenden Sie Berechtigungsregeln für statische Richtlinien, besonders Bash-Befehle (siehe Berechtigungseinstellungen)
  3. Verwenden Sie Hooks zum Protokollieren, Auditieren oder Transformieren aller Tool-Verwendungen (siehe Hook-Typen)
  4. Verwenden Sie canUseTool für dynamische Entscheidungen bei nicht abgedeckten Fällen (siehe CanUseTool-Typ)
  5. Schichten Sie Verteidigungen durch Kombination von Modi, Regeln, Hooks und Callbacks für kritische Anwendungen