Hooks-Referenz

​

Konfiguration

• ~/.claude/settings.json - Benutzereinstellungen
• .claude/settings.json - Projekteinstellungen
• .claude/settings.local.json - Lokale Projekteinstellungen (nicht committed)
• Von Unternehmen verwaltete Richtlinieneinstellungen

​

Struktur

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

• matcher: Muster zum Abgleich von Toolnamen, Groß-/Kleinschreibung beachtet (nur anwendbar für PreToolUse und PostToolUse)
  • Einfache Strings stimmen genau überein: Write stimmt nur mit dem Write-Tool überein
  • Unterstützt Regex: Edit|Write oder Notebook.*
  • Verwenden Sie *, um alle Tools abzugleichen. Sie können auch einen leeren String ("") verwenden oder matcher leer lassen.
• hooks: Array von Befehlen, die ausgeführt werden, wenn das Muster übereinstimmt
  • type: Derzeit wird nur "command" unterstützt
  • command: Der auszuführende Bash-Befehl (kann die Umgebungsvariable $CLAUDE_PROJECT_DIR verwenden)
  • timeout: (Optional) Wie lange ein Befehl ausgeführt werden soll, in Sekunden, bevor dieser spezifische Befehl abgebrochen wird.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/prompt-validator.py"
          }
        ]
      }
    ]
  }
}

​

Projektspezifische Hook-Skripte

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
          }
        ]
      }
    ]
  }
}

​

Plugin-Hooks

• Plugin-Hooks werden in der Datei hooks/hooks.json des Plugins oder in einer Datei definiert, die durch einen benutzerdefinierten Pfad zum Feld hooks angegeben wird.
• Wenn ein Plugin aktiviert ist, werden seine Hooks mit Benutzer- und Projekt-Hooks zusammengeführt
• Mehrere Hooks aus verschiedenen Quellen können auf dasselbe Ereignis reagieren
• Plugin-Hooks verwenden die Umgebungsvariable ${CLAUDE_PLUGIN_ROOT}, um auf Plugin-Dateien zu verweisen

{
  "description": "Automatische Code-Formatierung",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

• ${CLAUDE_PLUGIN_ROOT}: Absoluter Pfad zum Plugin-Verzeichnis
• ${CLAUDE_PROJECT_DIR}: Projektroot-Verzeichnis (gleich wie für Projekt-Hooks)
• Alle Standard-Umgebungsvariablen sind verfügbar

​

Hook-Ereignisse

​

PreToolUse

• Task - Subagent-Aufgaben (siehe Subagents-Dokumentation)
• Bash - Shell-Befehle
• Glob - Dateimuster-Matching
• Grep - Inhaltssuche
• Read - Dateilesevorgänge
• Edit - Dateibearbeitung
• Write - Dateischreiben
• WebFetch, WebSearch - Web-Operationen

​

PostToolUse

​

Notification

1. Claude Ihre Berechtigung zur Verwendung eines Tools benötigt. Beispiel: “Claude benötigt Ihre Berechtigung zur Verwendung von Bash”
2. Die Eingabeaufforderung mindestens 60 Sekunden lang untätig war. “Claude wartet auf Ihre Eingabe”

​

UserPromptSubmit

​

Stop

​

SubagentStop

​

PreCompact

• manual - Aufgerufen von /compact
• auto - Aufgerufen von Auto-Compact (aufgrund eines vollen Kontextfensters)

​

SessionStart

• startup - Aufgerufen beim Starten
• resume - Aufgerufen von --resume, --continue oder /resume
• clear - Aufgerufen von /clear
• compact - Aufgerufen von Auto- oder manuellem Compact.

​

Persistieren von Umgebungsvariablen

#!/bin/bash

if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export API_KEY=your-api-key' >> "$CLAUDE_ENV_FILE"
  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi

exit 0

#!/bin/bash

ENV_BEFORE=$(export -p | sort)

# Führen Sie Ihre Setup-Befehle aus, die die Umgebung ändern
source ~/.nvm/nvm.sh
nvm use 20

if [ -n "$CLAUDE_ENV_FILE" ]; then
  ENV_AFTER=$(export -p | sort)
  comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
fi

exit 0

​

SessionEnd

• clear - Sitzung mit dem Befehl /clear gelöscht
• logout - Benutzer hat sich abgemeldet
• prompt_input_exit - Benutzer hat beendet, während die Eingabeaufforderung sichtbar war
• other - Andere Beendigungsgründe

​

Hook-Eingabe

{
  // Gemeinsame Felder
  session_id: string
  transcript_path: string  // Pfad zur Gesprächs-JSON
  cwd: string              // Das aktuelle Arbeitsverzeichnis, wenn der Hook aufgerufen wird
  permission_mode: string  // Aktueller Berechtigungsmodus: "default", "plan", "acceptEdits" oder "bypassPermissions"

  // Ereignisspezifische Felder
  hook_event_name: string
  ...
}

​

PreToolUse-Eingabe

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  }
}

​

PostToolUse-Eingabe

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  }
}

​

Notification-Eingabe

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "Notification",
  "message": "Task completed successfully"
}

​

UserPromptSubmit-Eingabe

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Write a function to calculate the factorial of a number"
}

​

Stop- und SubagentStop-Eingabe

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true
}

​

PreCompact-Eingabe

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": ""
}

​

SessionStart-Eingabe

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "hook_event_name": "SessionStart",
  "source": "startup"
}

​

SessionEnd-Eingabe

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SessionEnd",
  "reason": "exit"
}

​

Hook-Ausgabe

​

Einfach: Exit-Code

• Exit-Code 0: Erfolg. stdout wird dem Benutzer im Transkriptmodus angezeigt (STRG+R), außer für UserPromptSubmit und SessionStart, wobei stdout zum Kontext hinzugefügt wird.
• Exit-Code 2: Blockierender Fehler. stderr wird an Claude zurückgegeben, um automatisch verarbeitet zu werden. Siehe das Verhalten pro Hook-Ereignis unten.
• Andere Exit-Codes: Nicht blockierender Fehler. stderr wird dem Benutzer angezeigt und die Ausführung wird fortgesetzt.

​

Exit-Code-2-Verhalten

​

Erweitert: JSON-Ausgabe

​

Gemeinsame JSON-Felder

{
  "continue": true, // Ob Claude nach der Hook-Ausführung fortfahren soll (Standard: true)
  "stopReason": "string", // Nachricht, die angezeigt wird, wenn continue false ist

  "suppressOutput": true, // Stdout aus dem Transkriptmodus ausblenden (Standard: false)
  "systemMessage": "string" // Optionale Warnmeldung, die dem Benutzer angezeigt wird
}

• Für PreToolUse unterscheidet sich dies von "permissionDecision": "deny", das nur einen bestimmten Tool-Aufruf blockiert und automatisches Feedback an Claude bietet.
• Für PostToolUse unterscheidet sich dies von "decision": "block", das automatisiertes Feedback an Claude bietet.
• Für UserPromptSubmit verhindert dies die Verarbeitung der Eingabeaufforderung.
• Für Stop und SubagentStop hat dies Vorrang vor jeder "decision": "block"-Ausgabe.
• In allen Fällen hat "continue" = false Vorrang vor jeder "decision": "block"-Ausgabe.

​

PreToolUse-Entscheidungskontrolle

• "allow" umgeht das Berechtigungssystem. permissionDecisionReason wird dem Benutzer angezeigt, aber nicht Claude.
• "deny" verhindert die Ausführung des Tool-Aufrufs. permissionDecisionReason wird Claude angezeigt.
• "ask" fordert den Benutzer auf, den Tool-Aufruf in der Benutzeroberfläche zu bestätigen. permissionDecisionReason wird dem Benutzer angezeigt, aber nicht Claude.

• updatedInput ermöglicht es Ihnen, die Eingabeparameter des Tools vor der Ausführung zu ändern. Dies ist ein Record<string, unknown>-Objekt, das die Felder enthält, die Sie ändern oder hinzufügen möchten.
• Dies ist am nützlichsten mit "permissionDecision": "allow", um Tool-Aufrufe zu ändern und zu genehmigen.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow"
    "permissionDecisionReason": "My reason here",
    "updatedInput": {
      "field_to_modify": "new value"
    }
  }
}

​

PostToolUse-Entscheidungskontrolle

• "block" fordert Claude automatisch mit reason auf.
• undefined tut nichts. reason wird ignoriert.
• "hookSpecificOutput.additionalContext" fügt Kontext hinzu, den Claude berücksichtigen soll.

{
  "decision": "block" | undefined,
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude"
  }
}

​

UserPromptSubmit-Entscheidungskontrolle

• "block" verhindert die Verarbeitung der Eingabeaufforderung. Die eingereichte Eingabeaufforderung wird aus dem Kontext gelöscht. "reason" wird dem Benutzer angezeigt, aber nicht zum Kontext hinzugefügt.
• undefined ermöglicht der Eingabeaufforderung, normal fortzufahren. "reason" wird ignoriert.
• "hookSpecificOutput.additionalContext" fügt den String zum Kontext hinzu, wenn nicht blockiert.

{
  "decision": "block" | undefined,
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here"
  }
}

​

Stop/SubagentStop-Entscheidungskontrolle

• "block" verhindert, dass Claude stoppt. Sie müssen reason ausfüllen, damit Claude weiß, wie es fortfahren soll.
• undefined ermöglicht Claude zu stoppen. reason wird ignoriert.

{
  "decision": "block" | undefined,
  "reason": "Must be provided when Claude is blocked from stopping"
}

​

SessionStart-Entscheidungskontrolle

• "hookSpecificOutput.additionalContext" fügt den String zum Kontext hinzu.
• Mehrere additionalContext-Werte von Hooks werden verkettet.

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "My additional context here"
  }
}

​

SessionEnd-Entscheidungskontrolle

​

Exit-Code-Beispiel: Bash-Befehl-Validierung

#!/usr/bin/env python3
import json
import re
import sys

# Definieren Sie Validierungsregeln als Liste von (Regex-Muster, Nachricht)-Tupeln
VALIDATION_RULES = [
    (
        r"\bgrep\b(?!.*\|)",
        "Use 'rg' (ripgrep) instead of 'grep' for better performance and features",
    ),
    (
        r"\bfind\s+\S+\s+-name\b",
        "Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance",
    ),
]


def validate_command(command: str) -> list[str]:
    issues = []
    for pattern, message in VALIDATION_RULES:
        if re.search(pattern, command):
            issues.append(message)
    return issues


try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})
command = tool_input.get("command", "")

if tool_name != "Bash" or not command:
    sys.exit(1)

# Validieren Sie den Befehl
issues = validate_command(command)

if issues:
    for message in issues:
        print(f"• {message}", file=sys.stderr)
    # Exit-Code 2 blockiert Tool-Aufruf und zeigt stderr Claude an
    sys.exit(2)

​

JSON-Ausgabe-Beispiel: UserPromptSubmit zum Hinzufügen von Kontext und Validierung

#!/usr/bin/env python3
import json
import sys
import re
import datetime

# Laden Sie die Eingabe von stdin
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

prompt = input_data.get("prompt", "")

# Überprüfen Sie auf sensible Muster
sensitive_patterns = [
    (r"(?i)\b(password|secret|key|token)\s*[:=]", "Prompt contains potential secrets"),
]

for pattern, message in sensitive_patterns:
    if re.search(pattern, prompt):
        # Verwenden Sie JSON-Ausgabe, um mit einem bestimmten Grund zu blockieren
        output = {
            "decision": "block",
            "reason": f"Security policy violation: {message}. Please rephrase your request without sensitive information."
        }
        print(json.dumps(output))
        sys.exit(0)

# Fügen Sie die aktuelle Zeit zum Kontext hinzu
context = f"Current time: {datetime.datetime.now()}"
print(context)

"""
Das Folgende ist auch gleichwertig:
print(json.dumps({
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": context,
  },
}))
"""

# Ermöglichen Sie der Eingabeaufforderung, mit dem zusätzlichen Kontext fortzufahren
sys.exit(0)

​

JSON-Ausgabe-Beispiel: PreToolUse mit Genehmigung

#!/usr/bin/env python3
import json
import sys

# Laden Sie die Eingabe von stdin
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})

# Beispiel: Automatische Genehmigung von Dateilesevorgängen für Dokumentationsdateien
if tool_name == "Read":
    file_path = tool_input.get("file_path", "")
    if file_path.endswith((".md", ".mdx", ".txt", ".json")):
        # Verwenden Sie JSON-Ausgabe, um den Tool-Aufruf automatisch zu genehmigen
        output = {
            "decision": "approve",
            "reason": "Documentation file auto-approved",
            "suppressOutput": True  # Nicht im Transkriptmodus anzeigen
        }
        print(json.dumps(output))
        sys.exit(0)

# Für andere Fälle den normalen Berechtigungsfluss fortfahren lassen
sys.exit(0)

​

Arbeiten mit MCP-Tools

​

MCP-Tool-Benennung

• mcp__memory__create_entities - Memory-Server-Tool zum Erstellen von Entitäten
• mcp__filesystem__read_file - Filesystem-Server-Tool zum Lesen von Dateien
• mcp__github__search_repositories - GitHub-Server-Suchtool

​

Konfigurieren von Hooks für MCP-Tools

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}

​

Beispiele

​

Sicherheitsüberlegungen

​

Haftungsausschluss

• Sie allein verantwortlich für die von Ihnen konfigurierten Befehle sind
• Hooks alle Dateien ändern, löschen oder darauf zugreifen können, auf die Ihr Benutzerkonto zugreifen kann
• Bösartige oder schlecht geschriebene Hooks können zu Datenverlust oder Systemschäden führen
• Anthropic bietet keine Garantie und übernimmt keine Haftung für Schäden, die sich aus der Verwendung von Hooks ergeben
• Sie sollten Hooks in einer sicheren Umgebung gründlich testen, bevor Sie sie in der Produktion verwenden

​

Best Practices für Sicherheit

1. Validieren und bereinigen Sie Eingaben - Vertrauen Sie Eingabedaten nie blind
2. Zitieren Sie Shell-Variablen immer - Verwenden Sie "$VAR" nicht $VAR
3. Blockieren Sie Pfadtraversal - Überprüfen Sie auf .. in Dateipfaden
4. Verwenden Sie absolute Pfade - Geben Sie vollständige Pfade für Skripte an (verwenden Sie “$CLAUDE_PROJECT_DIR” für den Projektpfad)
5. Überspringen Sie sensible Dateien - Vermeiden Sie .env, .git/, Schlüssel usw.

​

Konfigurationssicherheit

1. Erfasst einen Snapshot von Hooks beim Start
2. Verwendet diesen Snapshot während der gesamten Sitzung
3. Warnt, wenn Hooks extern geändert werden
4. Erfordert eine Überprüfung im Menü /hooks, damit Änderungen wirksam werden

​

Hook-Ausführungsdetails

• Timeout: 60-Sekunden-Ausführungslimit standardmäßig, konfigurierbar pro Befehl.
  • Ein Timeout für einen einzelnen Befehl beeinträchtigt nicht die anderen Befehle.
• Parallelisierung: Alle übereinstimmenden Hooks werden parallel ausgeführt
• Deduplizierung: Mehrere identische Hook-Befehle werden automatisch dedupliziert
• Umgebung: Wird im aktuellen Verzeichnis mit der Umgebung von Claude Code ausgeführt
  • Die Umgebungsvariable CLAUDE_PROJECT_DIR ist verfügbar und enthält den absoluten Pfad zum Projektroot-Verzeichnis (wo Claude Code gestartet wurde)
  • Die Umgebungsvariable CLAUDE_CODE_REMOTE gibt an, ob der Hook in einer Remote- (Web-) Umgebung ("true") oder einer lokalen CLI-Umgebung (nicht gesetzt oder leer) ausgeführt wird. Verwenden Sie dies, um unterschiedliche Logik basierend auf dem Ausführungskontext auszuführen.
• Eingabe: JSON über stdin
• Ausgabe:
  • PreToolUse/PostToolUse/Stop/SubagentStop: Fortschritt im Transkript angezeigt (Strg+R)
  • Notification/SessionEnd: Nur in Debug protokolliert (--debug)
  • UserPromptSubmit/SessionStart: stdout als Kontext für Claude hinzugefügt

​

Debugging

​

Grundlegende Fehlerbehebung

1. Überprüfen Sie die Konfiguration - Führen Sie /hooks aus, um zu sehen, ob Ihr Hook registriert ist
2. Überprüfen Sie die Syntax - Stellen Sie sicher, dass Ihre JSON-Einstellungen gültig sind
3. Testen Sie Befehle - Führen Sie Hook-Befehle zuerst manuell aus
4. Überprüfen Sie Berechtigungen - Stellen Sie sicher, dass Skripte ausführbar sind
5. Überprüfen Sie Protokolle - Verwenden Sie claude --debug, um Hook-Ausführungsdetails anzuzeigen

• Nicht entgangene Anführungszeichen - Verwenden Sie \" in JSON-Strings
• Falscher Matcher - Überprüfen Sie, ob Toolnamen genau übereinstimmen (Groß-/Kleinschreibung beachtet)
• Befehl nicht gefunden - Verwenden Sie vollständige Pfade für Skripte

​

Erweitertes Debugging

1. Überprüfen Sie die Hook-Ausführung - Verwenden Sie claude --debug, um detaillierte Hook- Ausführung anzuzeigen
2. Validieren Sie JSON-Schemas - Testen Sie Hook-Eingabe/Ausgabe mit externen Tools
3. Überprüfen Sie Umgebungsvariablen - Überprüfen Sie, ob die Umgebung von Claude Code korrekt ist
4. Testen Sie Grenzfälle - Versuchen Sie Hooks mit ungewöhnlichen Dateipfaden oder Eingaben
5. Überwachen Sie Systemressourcen - Überprüfen Sie auf Ressourcenerschöpfung während der Hook- Ausführung
6. Verwenden Sie strukturiertes Logging - Implementieren Sie Protokollierung in Ihren Hook-Skripten

​

Debug-Ausgabe-Beispiel

[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Getting matching hook commands for PostToolUse with query: Write
[DEBUG] Found 1 hook matchers in settings
[DEBUG] Matched 1 hooks for query "Write"
[DEBUG] Found 1 hook commands to execute
[DEBUG] Executing hook command: <Your command> with timeout 60000ms
[DEBUG] Hook command completed with status 0: <Your stdout>

• Welcher Hook ausgeführt wird
• Befehl wird ausgeführt
• Erfolgs-/Fehlerstatus
• Ausgabe- oder Fehlermeldungen