​

SDK-Berechtigungen

​

Überblick

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

• 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

​

Berechtigungsmodi

​

Verfügbare Modi

​

Berechtigungsmodus festlegen

​

1. Anfangskonfiguration

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)

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)

• 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

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

​

Berechtigungen umgehen-Modus (bypassPermissions)

• 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

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

• 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

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

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

​

canUseTool

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