​

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

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

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

​

Bypass Permissions-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 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

• 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

// 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-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

​

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)

​

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

• 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

​

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

• Behandelt Pipes, Umleitungen und Befehlssubstitution
• Erkennt gefährliche Muster wie rm -rf oder curl | sh
• Unterstützt Wildcards und Präfix-Matching

• 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