Hooks-Referenz

​

Hook-Lebenszyklus

• pro Sitzung: SessionStart und SessionEnd
• pro Runde: UserPromptSubmit, Stop und StopFailure
• bei jedem Tool-Aufruf innerhalb der agentengesteuerten Schleife: PreToolUse und PostToolUse, außer EndConversation-Aufrufen, die beide überspringen

​

Wie ein Hook aufgelöst wird

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0  # no decision; normal permission flow applies
fi

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
            ]
          },
          {
            "type": "command",
            "if": "PowerShell(Remove-Item *)",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
            ]
          }
        ]
      }
    ]
  }
}

# .claude/hooks/block-rm.ps1
$callInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
$command = $callInput.tool_input.command

if ($command -match 'rm -rf|Remove-Item.*-Recurse') {
  @{
    hookSpecificOutput = @{
      hookEventName = "PreToolUse"
      permissionDecision = "deny"
      permissionDecisionReason = "Destructive command blocked by hook"
    }
  } | ConvertTo-Json
} else {
  exit 0  # no decision; normal permission flow applies
}

{ "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook"
  }
}

​

Konfiguration

1. Wählen Sie ein Hook-Ereignis aus, auf das reagiert werden soll, wie PreToolUse oder Stop
2. Fügen Sie eine Matcher-Gruppe hinzu, um zu filtern, wann es ausgelöst wird, z. B. „nur für das Bash-Tool”
3. Definieren Sie einen oder mehrere Hook-Handler, die ausgeführt werden, wenn eine Übereinstimmung gefunden wird

​

Hook-Speicherorte

• Ihre Benutzer-, Projekt-, lokalen und Plugin-Hooks werden blockiert. Hooks aus Plugins, die in verwalteten Einstellungen enabledPlugins erzwungen aktiviert sind, sind ausgenommen
• Claude Code schränkt auch Ihre statusLine, fileSuggestion und subagentStatusLine Einstellungen auf verwaltete Einstellungen ein
• Claude Code deaktiviert auch Plugins mit einer command-Quelle, einschließlich Plugins, die in verwalteten Einstellungen enabledPlugins erzwungen aktiviert sind, es sei denn, disableCommandPluginSources ist explizit auf false gesetzt. command-Quellen erfordern Claude Code v2.1.229 oder später
• Claude Code blockiert auch Marketplace-headersHelper-Befehle, es sei denn, disableCommandPluginSources ist explizit auf false gesetzt, außer für einen Marketplace, den verwaltete Einstellungen selbst deklarieren

• allowedHttpHookUrls: Wenn auf einer beliebigen Einstellungsebene definiert, führt Claude Code einen HTTP-Hook-Handler nur aus, wenn seine URL mit der zusammengeführten Allowlist übereinstimmt
• httpHookAllowedEnvVars: Wenn definiert, interpoliert Claude Code nur die Umgebungsvariablen auf dieser Liste in Hook-Header

​

Matcher-Muster

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

​

MCP-Tools abgleichen

• mcp__memory__create_entities: Entitäten-Tool des Memory-Servers erstellen
• mcp__filesystem__read_file: Datei-Lese-Tool des Filesystem-Servers
• mcp__github__search_repositories: Such-Tool des GitHub-Servers

• mcp__memory__.* passt auf alle Tools vom memory-Server
• mcp__brave-search__.* passt auf alle Tools von einem Server, dessen Name einen Bindestrich enthält
• mcp__.*__write.* passt auf jedes Tool, dessen Name mit write beginnt, von jedem Server

{
  "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"
          }
        ]
      }
    ]
  }
}

​

Hook-Handler-Felder

• Command-Hooks (type: "command"): Führen einen Shell-Befehl aus. Ihr Skript empfängt die JSON-Eingabe des Ereignisses auf stdin und kommuniziert Ergebnisse über Exit-Codes und stdout zurück.
• HTTP-Hooks (type: "http"): Senden Sie die JSON-Eingabe des Ereignisses als HTTP-POST-Anfrage an eine URL. Der Endpunkt kommuniziert Ergebnisse über den Antwortkörper mit dem gleichen JSON-Ausgabeformat wie Command-Hooks zurück.
• MCP-Tool-Hooks (type: "mcp_tool"): Rufen Sie ein Tool auf einem konfigurierten MCP-Server auf. Die Textausgabe des Tools wird wie Command-Hook-stdout behandelt.
• Prompt-Hooks (type: "prompt"): Senden Sie einen Prompt an ein Claude-Modell zur Einzelturn-Bewertung. Das Modell gibt seine Entscheidung als JSON zurück. Siehe Prompt-basierte Hooks.
• Agent-Hooks (type: "agent"): Spawnen Sie einen Subagent, der Tools wie Read, Grep und Glob verwenden kann, um Bedingungen zu überprüfen, bevor er eine Entscheidung zurückgibt. Agent-Hooks sind experimentell und können sich ändern. Siehe Agent-basierte Hooks.

​

Gemeinsame Felder

​

Command-Hook-Felder

{
  "type": "command",
  "command": "node",
  "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/format.js", "--fix"]
}

{
  "type": "command",
  "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.js --fix"
}

​

HTTP-Hook-Felder

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/pre-tool-use",
            "timeout": 30,
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

​

MCP-Tool-Hook-Felder

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "my_server",
            "tool": "security_scan",
            "input": { "file_path": "${tool_input.file_path}" }
          }
        ]
      }
    ]
  }
}

​

Prompt- und Agent-Hook-Felder

​

Skripte nach Pfad referenzieren

• ${CLAUDE_PROJECT_DIR}: das Projekt-Root, wo die Sitzung gestartet wurde. Claude Code setzt diese Variable auch in der Umgebung von stdio MCP-Servern und Plugin-LSP-Servern.
• ${CLAUDE_PLUGIN_ROOT}: das Plugin-Installationsverzeichnis für Skripte, die mit einem Plugin gebündelt sind. Siehe Plugin-Umgebungsvariablen für das Verhalten des Pfads über Updates hinweg.
• ${CLAUDE_PLUGIN_DATA}: das persistente Datenverzeichnis des Plugins für Abhängigkeiten und Status, die Plugin-Updates überstehen sollten.

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

{
  "description": "Automatic code formatting",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
            "args": [],
            "timeout": 30
          }
        ]
      }
    ]
  }
}

​

Hooks in Skills und Agents

• Subagent-Hooks: Claude Code führt sie nur aus, während dieser Subagent ausgeführt wird, und entfernt sie, wenn er fertig ist. Claude Code konvertiert einen Stop-Hook hier zu SubagentStop, dem Ereignis, das ausgelöst wird, wenn ein Subagent abgeschlossen ist.
• Skill-Hooks: Claude Code registriert sie, wenn Sie oder Claude den Skill aufrufen, und führt sie für den Rest der Sitzung aus, auf Turns nach dem eigenen Turn des Skills auch. Um Claude Code stattdessen einen Hook nach seiner ersten erfolgreichen Ausführung zu entfernen, setzen Sie once: true darauf.

---
name: secure-operations
description: Perform operations with security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

​

Das /hooks-Menü

• User Settings: aus ~/.claude/settings.json
• Project Settings: aus .claude/settings.json
• Local Settings: aus .claude/settings.local.json
• Plugin Hooks: aus der hooks/hooks.json eines Plugins
• Session Hooks: in der aktuellen Sitzung im Speicher registriert

​

Hooks deaktivieren oder entfernen

​

Hook-Eingabe und -Ausgabe

​

Allgemeine Eingabefelder

{
  "session_id": "abc123",
  "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "scratchpad_dir": "/tmp/claude-1000/-home-user-my-project/abc123/scratchpad",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite",
    "timeout": 120000,
    "run_in_background": false
  },
  "tool_use_id": "toolu_01ABC123..."
}

​

Exit-Code-Ausgabe

​

Exit-Code 0

• Beginnt mit { und endet mit }: Claude Code parst es als JSON. Wenn die Ausgabe zwei oder mehr Zeilen sind, die jeweils selbst als JSON geparst werden, und keine Zeile ein JSON-Ausgabe-Objekt ist, das ein Feld setzt, behandelt Claude Code die gesamte Ausgabe als einfachen Text. Wenn eine dieser Zeilen ein Feld setzt, ist die gesamte Ausgabe ein Parse-Fehler, der unten beschrieben wird.
• Beginnt mit { aber endet nicht mit }: Claude Code behandelt es als einfachen Text.
• Beginnt mit etwas anderem: Claude Code behandelt es als einfachen Text, ein JSON-Array oder einen zitierten JSON-String enthalten.

​

Exit-Code 2

#!/bin/bash
# Reads JSON input from stdin, checks the command
input=$(cat)
command=$(jq -r '.tool_input.command' <<<"$input")

if [[ "$command" == rm* ]]; then
  echo "Blocked: rm commands are not allowed" >&2
  exit 2  # Blocking error: tool call is prevented
fi

exit 0  # No decision: the normal permission flow applies

​

Andere Exit-Codes

• Mit einem geparsten Objekt, das die Schema-Validierung besteht, für Events, die das Standard-Entscheidungsmodell verwenden, ignoriert Claude Code den Exit-Code und das JSON allein entscheidet das Ergebnis:
  • Jedes Feld, das der Event unterstützt, wird berücksichtigt, einschließlich permissionDecision, additionalContext, updatedInput und systemMessage, und der Hook wird nicht als Fehler gemeldet.
  • Entscheidungskontrolle listet die Entscheidungsfelder pro Event auf; universelle Felder wie systemMessage folgen der JSON-Ausgabe-Tabelle.
• Mit einem geparsten Objekt, das die Schema-Validierung nicht besteht, für Events, die das Standard-Entscheidungsmodell verwenden, ist es der gleiche nicht blockierende Fehler wie bei Exit 0: die Aktion wird fortgesetzt, und der <Hook-Name> hook error-Hinweis trägt die Validierungsmeldung.
• Mit stdout, das Claude Code versucht als JSON zu parsen und kann nicht, meldet Claude Code den gleichen nicht blockierenden Fehler wie bei Exit 0 für Events, die das Standard-Entscheidungsmodell verwenden. Die Aktion wird fortgesetzt, und der Hinweis trägt die Parse-Meldung.
• Mit stdout, das Claude Code als einfachen Text behandelt, oder mit leerem stdout, ist es ein nicht blockierender Fehler für die meisten Hook-Events: die Aktion wird fortgesetzt, und das Transkript zeigt einen <Hook-Name> hook error-Hinweis gefolgt von der ersten Zeile von stderr, mit dem Präfix Failed with non-blocking status code:. Um den vollständigen stderr zu erfassen, aktivieren Sie Debug-Protokollierung.

​

Timeouts

• Ein abgelaufener command-, http- oder mcp_tool-Hook blockiert den Tool-Aufruf nicht. Der Aufruf wird durch den normalen Berechtigungsfluss fortgesetzt, verlassen Sie sich also nicht auf einen steckengebliebenen Hook, um als Gate zu fungieren.
• Ein Agent SDK Callback Hook, der sein Timeout überschreitet, blockiert den Tool-Aufruf.

​

Exit-Code-2-Verhalten pro Event

​

HTTP-Response-Handling

• 2xx mit leerem Body: Erfolg, äquivalent zu Exit-Code 0 ohne Ausgabe
• 2xx mit JSON-Objekt-Body: geparst mit dem gleichen JSON-Ausgabe-Schema wie Command Hooks. Ein Body, der die Schema-Validierung nicht besteht, ist ein nicht blockierender Fehler
• 2xx mit jedem anderen Body, wie einfacher Text: nicht blockierender Fehler, behandelt wie ein Nicht-2xx-Status. Claude Code fügt den Text nicht zu Claudes Kontext hinzu
• Nicht-2xx-Status: nicht blockierender Fehler, Ausführung wird fortgesetzt
• Verbindungsfehler: nicht blockierender Fehler, Ausführung wird fortgesetzt
• Timeout: der Hook wird abgebrochen, wie unter Timeouts beschrieben

​

JSON-Ausgabe

• Umfang: Claude Code misst jeden String für sich, auch wenn mehrere Hooks für den gleichen Event ausgeführt werden. Für JSON-Ausgabe wird jedes Feld separat gemessen; einfacher stdout wird als Ganzes gemessen.
• Über dem Limit: Claude Code speichert die Ausgabe in einer Datei im Session-Verzeichnis und ersetzt sie durch den Dateipfad und eine Vorschau von bis zu den ersten 2.000 Zeichen. Ein großes gültiges Bash-Ergebnis wird auf die gleiche Weise behandelt, beschrieben unter Ausgabelimits. Im Gegensatz zu dieser Bash-Obergrenze hat diese Obergrenze keine Einstellung oder Umgebungsvariable, um sie zu erhöhen.
• Datei lesen: Claude Code bittet Claude nicht, die Datei zu lesen, daher halten Sie alles, das Claude immer sehen muss, innerhalb der Obergrenze.

• Universelle Felder wie continue sind in der folgenden Tabelle aufgelistet. Jeder Event akzeptiert sie, aber einige Events verwerfen sie oder liefern systemMessage an anderer Stelle als dem Transkript. Jeder Event-Abschnitt sagt so. terminalSequence funktioniert auch auf diesen Events, mit den Ausnahmen, die unter Terminal-Benachrichtigungen ausgeben aufgelistet sind.
• Top-Level decision und reason werden von einigen Events verwendet, um zu blockieren oder Feedback zu geben.
• hookSpecificOutput ist ein verschachteltes Objekt für Events, die reichere Kontrolle benötigen. Es erfordert ein hookEventName-Feld, das auf den Event-Namen gesetzt ist.

{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }

​

Terminal-Benachrichtigungen ausgeben

• OSC 0, 1, 2: Fenster- und Icon-Titel
• OSC 9: iTerm2, ConEmu, Windows Terminal und WezTerm-Benachrichtigungen, einschließlich 9;4 Taskleisten-Fortschritt
• OSC 99: Kitty-Benachrichtigungen
• OSC 777: urxvt, Ghostty und Warp-Benachrichtigungen
• Bare BEL

• Claude Code schreibt die Sequenz nur in einer interaktiven Session und nur, während seine Schnittstelle auf dem Bildschirm ist. Im nicht-interaktiven Modus mit dem -p-Flag und im Agent SDK ignoriert es das Feld.
• Ein WorktreeCreate-Command-Hook kann kein JSON zurückgeben, da Claude Code seinen stdout als Worktree-Pfad liest. Ein HTTP-WorktreeCreate-Hook gibt JSON zurück und kann das Feld enthalten.

#!/bin/bash
# Notification hook: ping the desktop when Claude Code needs attention.
input=$(cat)
title="Claude Code"
body=$(jq -r '.message // "Needs your attention"' <<<"$input")
seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

​

Kontext für Claude hinzufügen

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "This file is generated. Edit src/schema.ts and run `bun generate` instead."
  }
}

• SessionStart und SubagentStart: am Anfang der Konversation, vor dem ersten Prompt
• UserPromptSubmit und UserPromptExpansion: neben dem eingereichten Prompt
• PreToolUse, PostToolUse, PostToolUseFailure und PostToolBatch: neben dem Tool-Ergebnis
• Stop und SubagentStop: am Ende des Turns. Die Konversation wird fortgesetzt, sodass Claude auf das Feedback reagieren kann. Siehe Stop-Entscheidungskontrolle
• PostModelSwitch: mit der nächsten Anfrage nach dem Wechsel. Siehe PostModelSwitch-Entscheidungskontrolle für Timing

• Umgebungszustand: der aktuelle Branch, Bereitstellungsziel oder aktive Feature-Flags
• Bedingte Projektregeln: welcher Test-Befehl für die gerade bearbeitete Datei gilt, welche Verzeichnisse in diesem Worktree schreibgeschützt sind
• Externe Daten: offene Issues, die Ihnen zugewiesen sind, aktuelle CI-Ergebnisse, Inhalte, die von einem internen Service abgerufen wurden

​

Entscheidungskontrolle

• PreToolUse: updatedInput direkt unter hookSpecificOutput ersetzt die Argumente eines Tools, bevor es ausgeführt wird. Siehe PreToolUse-Entscheidungskontrolle
• PermissionRequest: updatedInput innerhalb des decision-Objekts. Siehe PermissionRequest-Entscheidungskontrolle
• PostToolUse: updatedToolOutput ersetzt das Tool-Ergebnis. Siehe PostToolUse-Entscheidungskontrolle
• UserPromptSubmit: kann den Prompt nicht ersetzen; es injiziert nur additionalContext daneben

{
  "decision": "block",
  "reason": "Test suite must pass before proceeding"
}

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes are not allowed"
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

​

Hook-Ereignisse

​

SessionStart

​

SessionStart-Eingabe

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SessionStart",
  "source": "resume",
  "model": "claude-opus-5",
  "seconds_since_last_response": 5400,
  "context_tokens": 182340,
  "prompt_cache_likely_expired": true,
  "estimated_cache_write_usd": 1.1396
}

​

SessionStart-Entscheidungskontrolle

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Current branch: feat/auth-refactor\nUncommitted changes: src/auth.ts, src/login.tsx\nActive issue: #4211 Migrate to OAuth2",
    "sessionTitle": "auth-refactor"
  }
}

#!/bin/bash

git -C ~/.claude/skills/team-skills pull --quiet 2>/dev/null || \
  git clone --quiet https://git.example.com/your-org/team-skills.git ~/.claude/skills/team-skills

echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'

​

Umgebungsvariablen beibehalten

#!/bin/bash

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

exit 0

#!/bin/bash

ENV_BEFORE=$(export -p | sort)

# Run your setup commands that modify the environment
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

​

Setup

​

Setup-Eingabe

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Setup",
  "trigger": "init"
}

​

Setup-Entscheidungskontrolle

​

InstructionsLoaded

​

InstructionsLoaded-Eingabe

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "InstructionsLoaded",
  "file_path": "/Users/my-project/CLAUDE.md",
  "memory_type": "Project",
  "load_reason": "session_start"
}

​

InstructionsLoaded-Entscheidungskontrolle

​

UserPromptSubmit

​

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"
}

​

UserPromptSubmit-Entscheidungskontrolle

• Klartext-stdout: Claude Code fügt stdout, das es als Klartext behandelt, zu Claudes Kontext hinzu
• JSON mit additionalContext: Verwenden Sie das JSON-Format unten für mehr Kontrolle. Das additionalContext Feld wird als Kontext hinzugefügt

{
  "decision": "block",
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here",
    "sessionTitle": "My session title"
  }
}

​

UserPromptExpansion

​

UserPromptExpansion-Eingabe

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../00893aaf.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptExpansion",
  "expansion_type": "slash_command",
  "command_name": "example-skill",
  "command_args": "arg1 arg2",
  "command_source": "plugin",
  "prompt": "/example-skill arg1 arg2"
}

​

UserPromptExpansion-Entscheidungskontrolle

{
  "decision": "block",
  "reason": "This slash command is not available",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptExpansion",
    "additionalContext": "Additional context for this expansion"
  }
}

​

MessageDisplay

• Markdown für eine minimale Anzeige entfernen
• Den Text transformieren, den eine Agent SDK Anwendung ihren Benutzern zeigt
• API-Schlüssel oder interne Hostnamen aus Claudes Antworten redigieren

​

MessageDisplay-Eingabe

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "MessageDisplay",
  "turn_id": "0c9e6a2f-7d41-4f4e-9a15-3f4f7c2b8d10",
  "message_id": "5b2a9c8e-1f63-4d8a-b7c4-9e0d2a6f1c3b",
  "index": 0,
  "final": false,
  "delta": "Here is the plan:\n"
}

​

MessageDisplay-Ausgabe

{
  "hooks": {
    "MessageDisplay": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

#!/bin/bash
jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'

{
  "hooks": {
    "MessageDisplay": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.ps1"
            ]
          }
        ]
      }
    ]
  }
}

$batch = [Console]::In.ReadToEnd() | ConvertFrom-Json
$text = $batch.delta -replace '\*\*', '' -replace '`', ''
@{
  hookSpecificOutput = @{
    hookEventName = "MessageDisplay"
    displayContent = $text
  }
} | ConvertTo-Json

​

PreToolUse

​

PreToolUse-Eingabe

• Claude Code erweitert ~ und relative Pfade, bevor Hooks ausgeführt werden, daher kann ein Hook, der auf Pfaden abgleicht, nicht durch ~ oder eine relative Schreibweise des gleichen Pfads umgangen werden
• Unter Windows kommt der Pfad mit Backslash-Trennzeichen an, auch wenn Ihr Hook unter Git Bash läuft, wo $PWD wie /c/project aussieht
• Ein Vergleich mit Schrägstrichen, wie eine /src/ Überprüfung, gleicht niemals einen Backslash-Pfad ab, und der Tool-Aufruf wird fortgesetzt, als hätte der Hook nichts zu blockieren
• Normalisieren Sie Trennzeichen vor dem Vergleich: FILE_PATH="${FILE_PATH//\\//}" in Bash oder file_path.replace("\\", "/") in Python, dann gleichen Sie ein Pfad-Segment wie /src/ ab, anstatt mit ^ zu verankern, da der Pfad absolut ist

{
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "C:\\project\\src\\index.ts",
    "content": "..."
  },
  ...
}

• Unter Windows, überall dort, wo das PowerShell-Tool aktiviert ist, behandelt Claude PowerShell als die primäre Shell und leitet Shell-Befehle durch sie.
• Unter Windows ohne Git Bash ist das Tool automatisch aktiviert und Claude Code registriert das Bash-Tool überhaupt nicht.
• Ein Hook, der nur Bash abgleicht, wird dort nie ausgelöst.

​

PreToolUse-Entscheidungskontrolle

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "My reason here",
    "updatedInput": {
      "field_to_modify": "new value"
    },
    "additionalContext": "Current environment: production. Proceed with caution."
  }
}

​

Tool-Aufruf für später aufschieben

1. Claude ruft AskUserQuestion auf. Der PreToolUse Hook wird ausgelöst.
2. Der Hook gibt permissionDecision: "defer" zurück. Das Tool wird nicht ausgeführt. Der Prozess beendet sich mit stop_reason: "tool_deferred" und dem ausstehenden Tool-Aufruf, der im Transkript erhalten bleibt.
3. Der aufrufende Prozess liest deferred_tool_use aus dem SDK-Ergebnis, zeigt die Frage in seiner eigenen UI an und wartet auf eine Antwort.
4. Der aufrufende Prozess führt claude -p --resume <session-id> mit dem gleichen Berechtigungshost aus. Der gleiche Tool-Aufruf löst PreToolUse erneut aus.
5. Der Hook gibt permissionDecision: "allow" mit der Antwort in updatedInput zurück. Das Tool wird ausgeführt und Claude setzt fort.

{
  "type": "result",
  "subtype": "success",
  "stop_reason": "tool_deferred",
  "session_id": "abc123",
  "deferred_tool_use": {
    "id": "toolu_01abc",
    "name": "AskUserQuestion",
    "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React"}, {"label": "Vue"}], "multiSelect": false }] }
  }
}

​

PermissionRequest

​

PermissionRequest-Eingabe

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PermissionRequest",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "description": "Remove node_modules directory"
  },
  "permission_suggestions": [
    {
      "type": "addRules",
      "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],
      "behavior": "allow",
      "destination": "localSettings"
    }
  ]
}

​

PermissionRequest-Entscheidungskontrolle

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

​

Berechtigungsaktualisierungseinträge

​

PostToolUse

• Um einen Hook nach jedem erfolgreichen Tool-Abschluss auszuführen, weglassen Sie den matcher oder setzen Sie ihn auf "*". Ihr Hook kann dann selbst entdecken, was sich geändert hat, z. B. durch Ausführung von git status --porcelain, das auch nicht verfolgte Dateien auflistet, die git diff verpasst. Für fehlgeschlagene Tool-Aufrufe fügen Sie den gleichen Hook unter PostToolUseFailure hinzu.
• Um einen Hook auszuführen, wenn sich eine bestimmte Datei auf der Festplatte ändert, unabhängig davon, was sie geschrieben hat, verwenden Sie FileChanged. Claude Code führt keinen PostToolUse Hook aus, der Edit|Write abgleicht, wenn ein Bash Befehl oder ein Prozess außerhalb von Claude Code die gleiche Datei umschreibt.

​

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",
    "type": "create"
  },
  "tool_use_id": "toolu_01ABC123...",
  "duration_ms": 12
}

​

PostToolUse-Entscheidungskontrolle

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude",
    "updatedToolOutput": {
      "stdout": "[redacted]",
      "stderr": "",
      "interrupted": false,
      "isImage": false
    }
  }
}

​

Ergebnis für den Auto-Modus Klassifizierer annotieren

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "classifierContext": "This query ran against the staging database, not production."
  }
}

• Hooks, die in Claude Code konfiguriert sind: Für Hooks aus Einstellungsdateien, Plugins, Skills und Agent-Frontmatter behandelt der Klassifizierer die Notiz als nicht verifizierten, anwendungsbereitgestellten Kontext. Die Notiz stellt niemals Benutzerabsicht fest, und wenn sie behauptet, Sie hätten etwas genehmigt oder angefordert, überprüft der Klassifizierer diese Behauptung gegen Ihre eigenen Nachrichten im Gespräch
• In-Process Agent SDK Callbacks: Wenn eine Anwendung, die Claude Code einbettet, den Hook als TypeScript SDK Callback registriert und die Notiz während der Live-Sitzung zurückgibt, kann der Klassifizierer eine Benutzeraussage, die in der Notiz weitergeleitet wird, als Benutzerabsicht gewichten. Eine solche Aussage kann eine Zustimmungsanforderung erfüllen, die der Klassifizierer von einer Nachricht akzeptieren würde, die Sie senden, aber sie hebt niemals einen Block auf, den Ihre eigene Nachricht nicht heben könnte. Nach einer Sitzungswiederaufnahme behandelt Claude Code wiederhergestellte Notizen als nicht verifizierten Kontext. Wenn Hooks aus beiden Gruppen den gleichen Aufruf annotieren, behandelt der Klassifizierer die kombinierte Notiz als nicht verifizierten Kontext

• Länge: Claude Code begrenzt die Notizen für einen Tool-Aufruf auf 2.000 Zeichen und kürzt den Rest. Die Grenze wird über jeden Hook geteilt, der auf diesen Aufruf antwortet
• Nur synchrone Antworten: Claude Code ignoriert das Feld in der Antwort eines Hooks, der im Hintergrund läuft, da diese Antwort ankommt, nachdem Claude Code das Tool-Ergebnis aufzeichnet
• Aufrufe, die der Klassifizierer nicht aufzeichnet: Das Transkript des Klassifizierers lässt schreibgeschützte Lookups wie Dateilesevorgänge und Suchen aus. Claude Code verwirft eine Notiz, die an einen dieser Aufrufe angehängt ist
• Interaktion mit Umschreibungen: Wenn die Notiz Ausgabe beschreibt, die Sie mit updatedToolOutput ersetzen, geben Sie beide Felder in der gleichen Hook-Antwort zurück. Claude Code lässt die Notiz fallen, wenn diese Umschreibung abgelehnt wird oder eine andere Hook-Umschreibung sie ersetzt. Claude Code liefert eine Notiz, die Sie ohne Umschreibung zurückgeben, auch wenn ein anderer Hook die Ausgabe umschreibt

​

PostToolUseFailure

​

PostToolUseFailure-Eingabe

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUseFailure",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "tool_use_id": "toolu_01ABC123...",
  "error": "Exit code 1\nError: Cannot find module 'express'",
  "is_interrupt": false,
  "duration_ms": 4187
}

• Für Bash und PowerShell erzeugt ein Befehl, der lief und beendet wurde, eine erste Zeile Exit code N, dann jede Ausgabe, die der Befehl als einen Block mit stdout und stderr vermischt erzeugte
• Eine Nutzlast kann auch eine bloße Fehlernachricht ohne Exit-Code-Zeile tragen, wenn Claude Code den Shell-Prozess selbst nicht starten konnte
• Claude Code kürzt lange Zeichenketten in der Mitte um einen ... [N characters truncated] ... Marker und kann Zeilen einfügen, wie Command timed out after 2m 0s

​

PostToolUseFailure-Entscheidungskontrolle

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUseFailure",
    "additionalContext": "Additional information about the failure for Claude"
  }
}

​

PostToolBatch

​

PostToolBatch-Eingabe