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

​

Wie if-Muster Bash-Befehle abgleichen

​

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ü

​

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

• Erfolg: Ihr Hook wird mit 0 beendet. Claude Code wendet alle JSON-Ausgabe-Felder an, die Ihr Hook ausgegeben hat, und die Aktion wird fortgesetzt, sofern diese Felder sie nicht blockieren oder verweigern. Hooks, die einen Hintergrundprozess starten behandelt die Ausnahme.
• Blockierender Fehler: Ihr Hook wird mit 2 beendet. Bei Events, die blockieren können, stoppt Claude Code die Aktion.
• Nicht blockierender Fehler: Ihr Hook wird mit einem anderen Code beendet oder schlägt auf andere Weise fehl, etwa weil er nicht startet oder ungültiges JSON ausgibt. Die Aktion wird fortgesetzt, und bei Events wie PreToolUse sehen Sie einen <hook name> hook error-Hinweis im Transkript. Wenn ein fehlgeschlagener Hook die Aktion blockieren soll, setzen Sie onFailure: "block".

• WorktreeCreate: Jeder Exit-Code ungleich null lässt die Worktree-Erstellung fehlschlagen, unabhängig davon, was Ihr JSON sagt.
• WorktreeRemove: Jeder Exit-Code ungleich null lässt die Worktree-Entfernung fehlschlagen, wenn das Verzeichnis danach noch existiert.
• Stop, SubagentStop, TaskCompleted und der UserPromptSubmit-Hook eines Plugins: Wenn Ihr Hook mit 2 beendet wird, nichts auf stdout ausgibt und sein stderr meldet, dass eine Datei fehlt, etwa No such file or directory, behandelt Claude Code den Lauf als nicht blockierenden Fehler.
• Elicitation und ElicitationResult: Claude Code wendet Ihre hookSpecificOutput an, wenn Ihr Hook mit 0 beendet wird, und ignoriert sie bei jedem anderen Exit-Code.
• Events, die Hook-Ausgabe verwerfen, wie StopFailure: Claude Code ignoriert Ihr JSON bei jedem Exit-Code, abgesehen von Nebeneffekt-Feldern wie terminalSequence, die trotzdem ausgelöst werden.

​

Exit-Code 0

• Ein JSON-Objekt, auf einer oder mehreren Zeilen: wird als JSON-Ausgabe geparst.
• Ausgabe, die nicht mit { beginnt, oder die mit { beginnt und nicht mit } endet: einfacher Text. Ein JSON-Array und ein in Anführungszeichen gesetzter JSON-String sind nach dieser Regel einfacher Text.
• Zwei oder mehr Zeilen, die jeweils für sich als JSON geparst werden, wobei die erste mit { beginnt und die letzte mit } endet: einfacher Text, wenn keine Zeile ein JSON-Ausgabe-Objekt ist, das ein Feld setzt, und ein Parse-Fehler, wenn eine Zeile es ist.
• Alles andere, das mit { beginnt und mit } endet, aber kein gültiges JSON ist: ein Parse-Fehler.

​

Exit-Code 2

• JSON, das die Schemavalidierung besteht: Claude Code liest die JSON-Ausgabe-Felder trotzdem, aber sie können den Block nicht überschreiben. Selbst eine permissionDecision von "allow" lässt die Aktion nicht durch. Bei Elicitation und ElicitationResult wird die hookSpecificOutput eines Exit-2-Hooks ignoriert.
• JSON, das die Schemavalidierung nicht besteht: Der Hook blockiert trotzdem. Claude Code verwendet Ihren stderr als Blockierungsgrund und zeichnet den Validierungsfehler im Debug-Log auf.

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

PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/no-rm.sh]: Blocked: rm commands are not allowed

​

Andere Exit-Codes

Failed with non-blocking status code: something broke

​

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. Um den Aufruf zu blockieren, wenn ein command- oder http-Hook in ein Timeout läuft, setzen Sie onFailure: "block".
• Ein Agent SDK Callback Hook, der sein Timeout überschreitet, blockiert den Tool-Aufruf.

​

Hooks, die einen Hintergrundprozess starten

#!/bin/bash
"$CLAUDE_PROJECT_DIR"/.claude/hooks/policy-check.sh || exit $?
"$CLAUDE_PROJECT_DIR"/.claude/hooks/upload-metrics.sh >/dev/null 2>&1 &

• || exit $?: macht den Exit-Code der Prüfung zum eigenen Exit-Code des Hooks, sodass eine Prüfung, die zum Verweigern mit 2 beendet wird, trotzdem blockiert. Andernfalls wird der Hook mit dem Code der letzten Zeile beendet, also 0.
• >/dev/null 2>&1 &: führt upload-metrics.sh im Hintergrund mit umgeleiteter Ausgabe aus, sodass es die Ausgabe des Hooks nicht offen hält.

​

Die Aktion blockieren, wenn ein Hook fehlschlägt

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js"],
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

PreToolUse:Bash hook error: [node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js]: failed; blocking because onFailure is "block"
Error: Cannot find module '/path/to/project/.claude/hooks/check-command.js'

• Kann nicht starten: Ein Command Hook startet nicht, zum Beispiel weil das Skript oder die ausführbare Datei nicht existiert
• Exit-Code außer 0 oder 2: zählt bei einem Command Hook auch dann, wenn er JSON ausgegeben hat, das die Aktion erlaubt, etwa permissionDecision: "allow". Um eine JSON-Entscheidung zurückzugeben, beenden Sie mit 0
• HTTP-Fehler: Die Verbindung eines HTTP Hooks schlägt fehl, oder der Response-Status ist nicht 2xx
• Timeout: Der Hook erreicht sein timeout
• Ungültige Ausgabe: Die JSON-Ausgabe kann nicht geparst werden oder besteht die Schemavalidierung nicht. Bei einem HTTP Hook zählt auch ein 2xx-Body, der weder leer noch ein JSON-Objekt ist. Einfacher Text-stdout eines Command Hooks ist kein Fehlschlag

• Stop-, SubagentStop-, TaskCompleted- und TeammateIdle-Hooks: Exit-Code 2 schickt Claude bei diesen Events zurück an die Arbeit, und Claude kann einen Hook, der nicht läuft, nicht reparieren
• Hintergrund-Command-Hooks: Command Hooks, die async oder asyncRewake setzen

​

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, Deployment-Ziel 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-Events

​

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

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

​

Skills neu laden, die ein Hook installiert

#!/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 dauerhaft setzen

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

• Eine Leerzeile oder ein #-Kommentar
• Eine einzelne Zuweisung am Zeilenanfang, geschrieben als export NAME=value, declare -x NAME=value oder NAME=value, mit einem Wert, den Bash exakt so verwenden würde, wie er geschrieben ist, bestehend aus einer beliebigen Kombination dieser Bestandteile: Text ohne Anführungszeichen, der nur Buchstaben, Ziffern und die Zeichen _ @ % + = : , . / - verwendet, Text in einfachen Anführungszeichen und Text in doppelten Anführungszeichen, in dem jedes $, jeder Backtick und jedes " mit einem Backslash maskiert ist

​

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

​

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

​

UserPromptSubmit

• eine geplante Aufgabe ausgelöst wird, einschließlich einer /loop-Iteration
• ein Subagent im Hintergrund an die Sitzung zurückmeldet, die ihn gestartet hat
• eine andere Sitzung eine Nachricht an Ihre Hauptkonversation sendet

​

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

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

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

​

Was ein blockierter Prompt hinterlässt

​

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

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

​

MessageDisplay

• Markdown für eine minimalistische Anzeige zu entfernen
• den Text umzuwandeln, den eine Agent SDK-Anwendung ihren Benutzern anzeigt
• API-Schlüssel oder interne Hostnamen aus den Antworten von Claude zu schwärzen

​

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 laufen, sodass ein Hook, der auf Pfade matcht, nicht über ~ oder eine relative Schreibweise desselben Pfads umgangen werden kann
• Unter Windows kommt der Pfad mit Backslashes als Trennzeichen an, selbst wenn Ihr Hook unter Git Bash läuft, wo $PWD wie /c/project aussieht
• Ein Vergleich mit Schrägstrichen, etwa eine Prüfung auf /src/, trifft nie auf einen Pfad mit Backslashes zu, und der Tool-Aufruf wird fortgesetzt, als hätte der Hook nichts zu blockieren gehabt
• Normalisieren Sie die Trennzeichen vor dem Vergleich: FILE_PATH="${FILE_PATH//\\//}" in Bash oder file_path.replace("\\", "/") in Python, und matchen Sie dann auf ein Pfadsegment wie /src/, statt 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 behandelt Claude PowerShell überall dort, wo das PowerShell-Tool aktiviert ist, als primäre Shell und leitet Shell-Befehle darüber.
• Unter Windows ohne Git Bash wird das Tool automatisch aktiviert, und Claude Code registriert das Bash-Tool überhaupt nicht.
• Ein Hook, der nur auf Bash matcht, wird dort nie ausgelöst.

​

PreToolUse-Entscheidungssteuerung

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

​

Tools, die eine Benutzerinteraktion erfordern

1. Er liest die Eingabe des Tools von stdin
2. Er sammelt die Antwort über Ihre eigene Benutzeroberfläche
3. Er gibt permissionDecision: "allow" zusammen mit einem updatedInput zurück, das die Antwort enthält, sodass das Tool ohne Abfrage ausgeführt wird

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": {
      "questions": [
        {
          "question": "Which framework?",
          "header": "Framework",
          "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}],
          "multiSelect": false
        }
      ],
      "answers": {"Which framework?": "React"}
    }
  }
}

​

Einen Tool-Aufruf zurückstellen

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 der ausstehende Tool-Aufruf bleibt im Transkript erhalten.
3. Der aufrufende Prozess liest deferred_tool_use aus dem SDK-Ergebnis, zeigt die Frage in seiner eigenen Benutzeroberfläche an und wartet auf eine Antwort.
4. Der aufrufende Prozess führt claude -p --resume <session-id> mit demselben Berechtigungs-Host aus. Derselbe 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 fährt 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", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "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-Entscheidungssteuerung

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

​

Einträge zur Berechtigungsaktualisierung

​

PostToolUse

• Um einen Hook nach jedem erfolgreich abgeschlossenen Tool auszuführen, lassen Sie den matcher weg oder setzen Sie ihn auf "*". Ihr Hook kann dann selbst ermitteln, was sich geändert hat, etwa durch Ausführen von git status --porcelain, das auch nicht verfolgte Dateien auflistet, die git diff übersieht. Für fehlgeschlagene Tool-Aufrufe fügen Sie denselben Hook unter PostToolUseFailure hinzu.
• Um einen Hook auszuführen, wenn sich eine bestimmte Datei auf der Festplatte ändert, unabhängig davon, wer sie geschrieben hat, verwenden Sie FileChanged. Claude Code führt keinen PostToolUse-Hook mit dem Matcher Edit|Write aus, wenn ein Bash-Befehl oder ein Prozess außerhalb von Claude Code dieselbe Datei neu schreibt.