Im nicht-interaktiven Modus mit dem -p Flag bietet Claude Code AskUserQuestion und ExitPlanMode nur an, wenn der Lauf einen Berechtigungshost hat, um die Aufforderung zu empfangen, wie einen Agent SDK canUseTool Callback. Diese Tools erfordern Benutzerinteraktion. Das Zurückgeben von permissionDecision: "allow" zusammen mit updatedInput erfüllt diese Anforderung: Der Hook liest die Tool-Eingabe von stdin, sammelt die Antwort über Ihre eigene Benutzeroberfläche und gibt sie in updatedInput zurück, damit das Tool ohne Aufforderung ausgeführt wird. Das Zurückgeben von "allow" allein ist nicht ausreichend für diese Tools. Für AskUserQuestion geben Sie das ursprüngliche questions Array zurück und fügen ein answers Objekt hinzu, das jede Frage des Textes der gewählten Antwort zuordnet.

Ab v2.1.199 ist ein MCP-Tool, dessen Server es mit _meta["anthropic/requiresUserInteraction"] markiert, strenger: Ein Hook kann seine Genehmigungsaufforderung nicht mit "allow" überspringen, mit oder ohne updatedInput, da Claude Code nicht bestätigen kann, dass der Hook die Interaktion sammelte, die das Tool benötigt.

Einen Tool-Aufruf für später aufschieben

"defer" ist für Integrationen, die claude -p als Unterprozess ausführen und seine JSON-Ausgabe lesen, wie eine Agent SDK App oder eine benutzerdefinierte Benutzeroberfläche, die auf Claude Code aufgebaut ist. Es ermöglicht diesem aufrufenden Prozess, Claude bei einem Tool-Aufruf zu pausieren, Eingabe über seine eigene Schnittstelle zu sammeln und dort fortzufahren, wo er aufgehört hat. Claude Code berücksichtigt diesen Wert nur im nicht-interaktiven Modus mit dem -p Flag. In interaktiven Sitzungen protokolliert es eine Warnung und ignoriert das Hook-Ergebnis.

Das AskUserQuestion Tool ist der typische Fall: Claude möchte den Benutzer etwas fragen, aber es gibt kein Terminal zum Antworten. Ein -p Lauf bietet AskUserQuestion nur an, wenn er einen Berechtigungshost hat, wie ein MCP-Tool, das Sie mit --permission-prompt-tool übergeben, daher starten Sie den Lauf mit einem. Der Roundtrip funktioniert so:

1. Claude ruft AskUserQuestion auf. Der PreToolUse Hook wird ausgeführt.
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 Benutzeroberfläche 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 wird PreToolUse erneut ausgeführt.
5. Der Hook gibt permissionDecision: "allow" mit der Antwort in updatedInput zurück. Das Tool wird ausgeführt und Claude setzt fort.

Das deferred_tool_use Feld trägt die id, name und input des Tools. Die input sind die Parameter, die Claude für den Tool-Aufruf generiert hat, erfasst vor der Ausführung:

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

Es gibt kein Timeout oder Wiederholungslimit. Die Sitzung bleibt auf der Festplatte, bis Sie sie fortsetzen, unterliegt aber der cleanupPeriodDays Aufbewahrungssweep, die Sitzungsdateien nach 30 Tagen standardmäßig löscht, nach den Aufbewahrungssweep-Regeln. Wenn die Antwort nicht bereit ist, wenn Sie fortsetzen, kann der Hook "defer" erneut zurückgeben und der Prozess beendet sich auf die gleiche Weise. Der aufrufende Prozess steuert, wann die Schleife unterbrochen wird, indem er schließlich "allow" oder "deny" vom Hook zurückgibt.

"defer" funktioniert nur, wenn Claude einen einzelnen Tool-Aufruf im Zug macht. Wenn Claude mehrere Tool-Aufrufe gleichzeitig macht, wird "defer" mit einer Warnung ignoriert und das Tool wird durch den normalen Berechtigungsfluss fortgesetzt. Die Einschränkung existiert, weil Resume nur ein Tool erneut ausführen kann: Es gibt keine Möglichkeit, einen Aufruf aus einem Batch aufzuschieben, ohne die anderen ungelöst zu lassen.

Wenn das aufgeschobene Tool nicht mehr verfügbar ist, wenn Sie fortsetzen, beendet sich der Prozess mit stop_reason: "tool_deferred_unavailable" und is_error: true bevor der Hook ausgeführt wird. Dies geschieht, wenn ein MCP-Server, der das Tool bereitgestellt hat, für die fortgesetzte Sitzung nicht verbunden ist. Die deferred_tool_use Nutzlast ist immer noch enthalten, damit Sie identifizieren können, welches Tool fehlte.

PermissionRequest

Wird ausgeführt, wenn Claude Code Sie um Erlaubnis bitten möchte, ein Tool zu verwenden. In Sitzungen, die keine Aufforderung anzeigen können, wie Hintergrund-Subagenten im nicht-interaktiven Modus, führt Claude Code diese Hooks immer noch aus, und wenn kein Hook eine Entscheidung zurückgibt, verweigert es den Tool-Aufruf. Verwenden Sie PermissionRequest-Entscheidungskontrolle, um im Namen des Benutzers zu erlauben oder zu verweigern.

Verwenden Sie dieses Ereignis, wenn Sie ein Signal benötigen, in dem Moment, in dem Claude um Erlaubnis bittet, ein Tool zu verwenden. Claude Code führt einen Notification Hook mit dem permission_prompt Typ nur aus, nachdem die Aufforderung etwa sechs Sekunden gewartet hat.

Claude Code führt PermissionRequest-Hooks nicht für eine Sandbox-Anfrage eines Befehls aus Netzwerkanfrage. Um ein Signal für diese Aufforderung zu erhalten, verwenden Sie den permission_prompt Benachrichtigungstyp.

Gleicht Tool-Namen ab, gleiche Werte wie PreToolUse.

PermissionRequest-Eingabe

PermissionRequest-Hooks erhalten tool_name und tool_input Felder wie PreToolUse-Hooks, aber ohne tool_use_id. Für ein MCP-Tool erhalten sie auch das mcp_server Objekt. Ein optionales permission_suggestions Array enthält die Berechtigungsaktualisierungen, die Claude Code für diese Anfrage vorschlägt, wie das Hinzufügen einer Erlaubnisregel oder das Ändern des Berechtigungsmodus.

Das permission_suggestions Array ist keine genaue Liste der Optionen, die Sie sehen, da jeder Berechtigungsdialog seine eigenen Optionen erstellt. Einige Dialoge, wie der für Dateibearbeitungen, lesen das Array überhaupt nicht und leiten ihre Optionen aus der Anfrage selbst ab. Ein Dialog, der es liest, kann immer noch eine Option zurückhalten, deren Vorschlag im Array bleibt, z. B. wenn allowManagedPermissionRulesOnly Regel-Speicheroptionen verbirgt. Es kann auch Optionen anbieten, die keinen Vorschlagseintrag haben, wie Ja, und zum Auto-Modus wechseln, das den Berechtigungsmodus direkt ändert, anstatt durch eine Berechtigungsaktualisierung.

PreToolUse-Hooks werden vor jedem Tool-Aufruf ausgeführt, unabhängig davon, ob er Berechtigung benötigt. PermissionRequest-Hooks werden nur ausgeführt, wenn Claude Code Sie um Erlaubnis bitten möchte, oder wenn es sonst einen Aufruf automatisch verweigern würde, der nicht auffordern kann. Keines der Ereignisse wird für EndConversation ausgeführt.

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

PermissionRequest Hooks können Berechtigungsanfragen erlauben oder verweigern. Zusätzlich zu den JSON-Ausgabefeldern, die für alle Hooks verfügbar sind, kann Ihr Hook-Skript ein decision Objekt mit diesen ereignisspezifischen Feldern zurückgeben:

Ein Hook, der mit 2 beendet wird, ohne ein decision Objekt zu hinterlassen, lässt den Berechtigungsfluss unverändert, und sein stderr wird verworfen. Nur das decision Objekt kann die Anfrage gewähren oder verweigern.

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

Berechtigungsaktualisierungseinträge

Das updatedPermissions Ausgabefeld und das permission_suggestions Eingabefeld verwenden beide das gleiche Array von Einträgen. Jeder Eintrag hat einen type, der seine anderen Felder bestimmt, und ein destination, das steuert, wo die Änderung geschrieben wird.

Das destination Feld auf jedem Eintrag bestimmt, ob die Änderung im Speicher bleibt oder in einer Einstellungsdatei beibehalten wird.

Ein Hook kann eines der permission_suggestions widerspiegeln, die er als seine eigene updatedPermissions Ausgabe erhalten hat.

PostToolUse

Wird sofort nach erfolgreichem Abschluss eines Tools ausgeführt.

Gleicht Tool-Namen ab, gleiche Werte wie PreToolUse.

Gleichen Sie breiter ab, wenn der Tool-Name nicht der richtige Filter ist:

• 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 Tool-Aufrufe, die fehlschlagen, 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, wer sie schreibt, 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

PostToolUse Hooks werden ausgeführt, nachdem ein Tool bereits erfolgreich ausgeführt wurde. Die Eingabe umfasst sowohl tool_input, die an das Tool gesendeten Argumente, als auch tool_response, das Ergebnis, das es zurückgegeben hat. Das genaue Schema für beide hängt vom Tool ab. Datei-Tool-tool_input Pfade kommen im gleichen Format wie für PreToolUse an: immer absolut, mit den nativen Trennzeichen der Plattform, daher Backslashes unter Windows. Für ein MCP-Tool trägt die Eingabe auch das mcp_server Objekt.

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

PostToolUse Hooks können Claude nach der Tool-Ausführung Feedback geben. Zusätzlich zu den JSON-Ausgabefeldern, die für alle Hooks verfügbar sind, kann Ihr Hook-Skript diese ereignisspezifischen Felder zurückgeben:

Das Beispiel unten ersetzt die Ausgabe eines Bash Aufrufs. Der Ersatzwert entspricht der Ausgabeform des Bash Tools:

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

Ergebnis für den Auto-Modus Klassifizierer annotieren

Geben Sie classifierContext zurück, um eine kurze Notiz über das Ergebnis des Tool-Aufrufs an den Auto-Modus Klassifizierer statt an Claude zu senden. Der Klassifizierer empfängt niemals Tool-Ergebnisse selbst, daher ist dieses Feld die unterstützte Methode, um ihm etwas über das, was ein Aufruf zurückgegeben hat, zu sagen, bevor er spätere Aktionen überprüft. Das Feld erfordert Claude Code v2.1.236 oder später.

Das Beispiel unten sagt dem Klassifizierer, woher die Ausgabe einer Abfrage stammt:

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

Wie viel Gewicht der Klassifizierer der Notiz gibt, hängt davon ab, wo Sie den Hook konfiguriert haben:

• 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, von der Anwendung bereitgestellten 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 auch nicht heben könnte. Nach einer Sitzungsfortsetzung 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

Claude Code wendet diese Grenzen an, wenn die Notiz bereitgestellt wird:

• Länge: Claude Code begrenzt die Notizen für einen Tool-Aufruf auf 2.000 Zeichen und schneidet den Rest ab. 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 ausgeführt wird, da diese Antwort nach der Aufzeichnung des Tool-Ergebnisses ankommt
• 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öscht die Notiz, 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

Wird ausgeführt, wenn ein Tool, das mit der Ausführung begonnen hat, fehlschlägt: Das Tool warf einen Fehler oder ein MCP-Tool gab ein Fehlerergebnis zurück. Verwenden Sie dies, um Fehler zu protokollieren, Warnungen zu senden oder korrektes Feedback an Claude zu geben.

Gleicht Tool-Namen ab, gleiche Werte wie PreToolUse.

PostToolUseFailure-Eingabe

PostToolUseFailure-Hooks erhalten die gleichen tool_name und tool_input Felder wie PostToolUse, zusammen mit Fehlerinformationen als Top-Level-Felder. Für ein MCP-Tool erhalten sie auch das mcp_server Objekt. Beispielsweise könnte ein fehlgeschlagener npm test Befehl liefern:

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

Die error Zeichenkette ist im Allgemeinen der gleiche Text, den Claude als Ergebnis des fehlgeschlagenen Tools empfängt. Sein Format variiert je nach Tool und Fehler. Schlüsseln Sie Ihren Hook auf tool_name, is_interrupt und die erste Zeile Exit code N; behandeln Sie den Rest der Zeichenkette als Anzeigetext, nicht als stabiles Format.

• 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 Fehlermeldung ohne Exit-Code-Zeile tragen, wenn Claude Code den Shell-Prozess selbst nicht starten konnte
• Claude Code schneidet lange Zeichenketten in der Mitte um einen ... [N characters truncated] ... Marker ab und kann Zeilen von sich selbst einfügen, wie Command timed out after 2m 0s

PostToolUseFailure-Entscheidungskontrolle

PostToolUseFailure Hooks können Claude nach einem Tool-Fehler Kontext geben. Zusätzlich zu den JSON-Ausgabefeldern, die für alle Hooks verfügbar sind, kann Ihr Hook-Skript diese ereignisspezifischen Felder zurückgeben:

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

PostToolBatch

Wird einmal ausgeführt, nachdem jeder Tool-Aufruf in einem Batch aufgelöst wurde, bevor Claude Code die nächste Anfrage an das Modell sendet. PostToolUse wird einmal pro Tool ausgeführt, was bedeutet, dass es gleichzeitig ausgeführt wird, wenn Claude parallele Tool-Aufrufe macht. PostToolBatch wird genau einmal mit dem vollständigen Batch ausgeführt, daher ist es der richtige Ort, um Kontext einzufügen, der vom Satz von Tools abhängt, die liefen, statt von einem einzelnen Tool. Es gibt keinen Matcher für dieses Ereignis.

PostToolBatch-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten PostToolBatch-Hooks tool_calls, ein Array, das jeden Tool-Aufruf im Batch beschreibt:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolBatch",
  "tool_calls": [
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/accounts.py"},
      "tool_use_id": "toolu_01...",
      "tool_response": "     1\tfrom __future__ import annotations\n     2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "     1\tfrom __future__ import annotations\n     2\t..."
    }
  ]
}

tool_response enthält den gleichen Inhalt, den das Modell im entsprechenden tool_result Block empfängt. Der Wert ist eine serialisierte Zeichenkette oder ein Content-Block-Array, genau wie das Tool es ausgegeben hat. Für Read bedeutet das Zeilennummern-Präfix-Text statt rohe Dateiinhalte. Antworten können groß sein, daher analysieren Sie nur die Felder, die Sie benötigen.

PostToolBatch-Entscheidungskontrolle

PostToolBatch Hooks können Kontext für Claude einfügen. Zusätzlich zu den JSON-Ausgabefeldern, die für alle Hooks verfügbar sind, kann Ihr Hook-Skript diese ereignisspezifischen Felder zurückgeben:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolBatch",
    "additionalContext": "These files are part of the ledger module. Run pytest before marking the task complete."
  }
}

Das Zurückgeben von decision: "block" oder continue: false stoppt die agentengesteuerte Schleife vor dem nächsten Modell-Aufruf. Die Blockierungsmeldung kommt aus dem JSON reason oder stopReason oder aus stderr bei Beendigung mit 2. Sie sehen sie als Warnung im Transkript, und sie bleibt im Gespräch, daher sieht Claude sie, wenn das Gespräch fortgesetzt wird.

PermissionDenied

Wird ausgeführt, wenn Auto-Modus einen Tool-Aufruf verweigert, einschließlich wenn er verweigert, ohne ein Klassifizierer-Urteil zu haben, weil eine Sicherheitsprüfung, die vom Auto-Modus getrennt ist, die Anfrage des Klassifizierers selbst verweigerte oder seine Antwort nicht analysiert wurde. Dieser Hook wird nur im Auto-Modus ausgeführt: Er wird nicht ausgeführt, wenn Sie einen Berechtigungsdialog manuell verweigern, wenn ein PreToolUse Hook einen Aufruf blockiert oder wenn eine deny Regel übereinstimmt. Verwenden Sie ihn, um Verweigerungen zu protokollieren, die Konfiguration anzupassen oder dem Modell zu sagen, dass es den Tool-Aufruf möglicherweise erneut versuchen kann.

Gleicht Tool-Namen ab, gleiche Werte wie PreToolUse.

PermissionDenied-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten PermissionDenied-Hooks tool_name, tool_input, tool_use_id und reason. Für ein MCP-Tool erhalten sie auch das mcp_server Objekt.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "auto",
  "hook_event_name": "PermissionDenied",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/build",
    "description": "Clean build directory"
  },
  "tool_use_id": "toolu_01ABC123...",
  "reason": "[Irreversible Local Destruction]"
}

PermissionDenied-Entscheidungskontrolle

PermissionDenied-Hooks können dem Modell sagen, dass es den verweigerten Tool-Aufruf möglicherweise erneut versuchen kann. Geben Sie ein JSON-Objekt mit hookSpecificOutput.retry auf true zurück:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionDenied",
    "retry": true
  }
}

Wenn retry true ist, fügt Claude Code eine Nachricht zum Gespräch hinzu, die dem Modell sagt, dass es den Tool-Aufruf möglicherweise erneut versuchen kann. Claude Code kehrt die Verweigerung selbst nicht um. Wenn Ihr Hook kein JSON zurückgibt oder retry: false zurückgibt, bleibt die Verweigerung bestehen und das Modell empfängt die ursprüngliche Ablehnungsmeldung.

Claude Code ignoriert retry: true, wenn der Klassifizierer kein Urteil über die Aktion erzeugt hat: Seine Antwort wurde nicht analysiert oder eine Sicherheitsprüfung, die vom Auto-Modus getrennt ist, verweigerte die Anfrage des Klassifizierers. Für diese Verweigerungen sagt Claude Code dem Modell in der Ablehnungsmeldung bereits, ob es später erneut versuchen oder weitermachen soll.

Notification

Wird ausgeführt, wenn Claude Code Benachrichtigungen sendet. Gleicht Benachrichtigungstyp ab. Weglassen Sie den Matcher, um Hooks für alle Benachrichtigungstypen auszuführen.

Sie erhalten diese Hook-Ereignisse auch mit ausgeschalteten Desktop-Benachrichtigungen: Die preferredNotifChannel Einstellung, einschließlich notifications_disabled, ändert nur, wie Sie benachrichtigt werden, nicht ob Ihr Hook ausgeführt wird.

Die agent_needs_input und agent_completed Typen erfordern Claude Code v2.1.198 oder später.

Die quota_auto_resume_fired, quota_auto_resume_stale und quota_auto_resume_disabled Typen erfordern Claude Code v2.1.234 oder später.

In Terminal-Sitzungen erfordert permission_prompt für eine Netzwerkanfrage eines Sandbox-Befehls Claude Code v2.1.246 oder später.

agent_needs_input für eine Teamkollegen-Terminal-Setup-Frage erfordert Claude Code v2.1.248 oder später.

Claude Code zeitlich permission_prompt unterschiedlich in Sitzungen, in denen es Berechtigungsanfragen an den Agent SDK canUseTool Callback sendet, was ist, wie Claude Desktop und die VS Code Erweiterung Claude Code hosten:

• Erwarten Sie permission_prompt etwa sechs Sekunden, nachdem Claude um Erlaubnis bittet. Claude Code verschiebt es nicht, während Sie eingeben.
• Wenn Sie oder ein PermissionRequest Hook früher antworten, führt Claude Code permission_prompt nicht aus.
• Setzen Sie CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS auf 1, um permission_prompt in diesen Sitzungen auszuschalten.

Vor v2.1.233 wurde permission_prompt in diesen Sitzungen nicht ausgeführt.

Verwenden Sie separate Matcher, um verschiedene Handler je nach Benachrichtigungstyp auszuführen. Diese Konfiguration löst ein Berechtigungs-spezifisches Warnungsskript aus, wenn Claude Berechtigungsgenehmigung benötigt, und eine andere Benachrichtigung, wenn Claude untätig war:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/permission-alert.sh"
          }
        ]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/idle-notification.sh"
          }
        ]
      }
    ]
  }
}

Notification-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten Notification-Hooks message mit dem Benachrichtigungstext, ein optionaler title und notification_type, das angibt, welcher Typ ausgeführt wurde.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

Notification-Hooks können Benachrichtigungen nicht blockieren oder ändern. Claude Code verwirft ihre systemMessage und continue Felder, gibt aber immer noch terminalSequence aus, auf das sich das Desktop-Benachrichtigungsbeispiel verlässt. Notification-Hooks sind für Nebenwirkungen wie das Weiterleiten der Benachrichtigung an einen externen Service gedacht.

SubagentStart

Wird ausgeführt, wenn Claude einen Subagenten mit dem Agent-Tool spawnt, wenn Claude einen Subagenten fortsetzt und jedes Mal, wenn ein In-Process Agent-Team Teamkollege eine neue Nachricht verarbeitet. Unterstützt Matcher zum Filtern nach Agent-Typ-Name. Für integrierte Agenten ist dies der Agent-Name wie general-purpose, Explore oder Plan. Für benutzerdefinierte Subagenten ist dies das name Feld aus dem Agent-Frontmatter, nicht der Dateiname.

Für Subagenten, die von einem Plugin versendet werden, ist der Agent-Typ der Plugin-scoped Identifikator wie my-plugin:reviewer, nicht der bloße Frontmatter-Name. Der Doppelpunkt platziert einen Plugin-scoped Namen auf dem regulären Ausdruckspfad, daher verankern Sie den Matcher mit ^ und $ für einen genauen Treffer: ^my-plugin:reviewer$.

SubagentStart-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten SubagentStart-Hooks agent_id mit dem eindeutigen Identifikator für den Subagenten und agent_type mit dem Agent-Namen, den der Matcher filtert.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SubagentStart",
  "agent_id": "agent-abc123",
  "agent_type": "Explore"
}

SubagentStart-Hooks können die Erstellung von Subagenten nicht blockieren, aber sie können Kontext in den Subagenten einfügen. Zusätzlich zu den JSON-Ausgabefeldern, die für alle Hooks verfügbar sind, können Sie zurückgeben:

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Follow security guidelines for this task"
  }
}

Wenn der Hook erneut für den gleichen Subagenten ausgeführt wird, injiziert Claude Code den zurückgegebenen Kontext nur, wenn der Kontext des Subagenten nicht bereits die Kopie aus einem früheren Lauf enthält. Die beim Start eingefügte Kopie bleibt bestehen, wobei der Prompt-Cache des Subagenten intakt bleibt. Nach Auto-Komprimierung verwirft diese Kopie, injiziert Claude Code den Kontext des nächsten Laufs erneut.

SubagentStop

Wird ausgeführt, wenn ein Claude Code Subagent mit dem Antworten fertig ist. Gleicht Agent-Typ ab, gleiche Werte wie SubagentStart.

SubagentStop-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten SubagentStop-Hooks stop_hook_active, agent_id, agent_type, agent_transcript_path und last_assistant_message. Das agent_type Feld ist der Wert, der zum Filtern des Matchers verwendet wird. Der transcript_path ist das Transkript der Hauptsitzung, während agent_transcript_path das eigene Transkript des Subagenten ist, das in einem verschachtelten subagents/ Ordner gespeichert ist. Das last_assistant_message Feld enthält den Textinhalt der letzten Antwort des Subagenten, daher können Hooks darauf zugreifen, ohne die Transkript-Datei zu analysieren.

Nicht jedes SubagentStop-Ereignis kommt von einem Subagenten, den Claude spawnt. Claude Code führt auch interne Agenten für einige seiner eigenen Funktionen aus, wie Eingabeaufforderungsvorschläge und /btw Seitenfragen, und SubagentStop wird ausgeführt, wenn einer davon fertig ist. Für diese Ereignisse ist agent_type der Agent-Name, den die Sitzung selbst ausführt, wie einer, der mit --agent oder der agent Einstellung gesetzt ist, und eine leere Zeichenkette, wenn die Sitzung ohne einen läuft.

Ein matcher, der Agent-Typen benennt, gleicht keine leere agent_type ab. Ein Hook, dessen Matcher weggelassen, "" oder "*" ist oder ein regulärer Ausdruck, der eine leere Zeichenkette abgleicht, wird auch für Ereignisse mit einer leeren agent_type ausgeführt.

Auf Claude Code v2.1.271 oder später liefert ein Subagent, der mit dem SubagentHandback Tool läuft, seinen Bericht durch dieses Tool, bevor er stoppt. Das last_assistant_message Feld enthält dann den Schließungstext des Subagenten, falls vorhanden, das ist nicht der gelieferte Bericht. Der Bericht ist die message Eingabe dieses Aufrufs, die ein PreToolUse oder PostToolUse Hook, der auf SubagentHandback abgleicht, als tool_input.message empfängt.

SubagentStop-Hooks erhalten auch die background_tasks und session_crons Arrays, die unter Stop-Eingabe beschrieben sind. Beide Arrays sind auf die Eltern-Sitzung scoped, nicht den Subagenten.

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../abc123.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SubagentStop",
  "stop_hook_active": false,
  "agent_id": "def456",
  "agent_type": "Explore",
  "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl",
  "last_assistant_message": "Analysis complete. Found 3 potential issues...",
  "background_tasks": [],
  "session_crons": []
}

SubagentStop-Hooks verwenden das gleiche Entscheidungskontrollformat wie Stop-Hooks, einschließlich hookSpecificOutput.additionalContext mit hookEventName auf "SubagentStop" gesetzt, für Fehler-freies Feedback, das den Subagenten laufen lässt. Das Zurückgeben von decision: "block" mit einem reason lässt den Subagenten laufen und liefert reason an den Subagenten als seine nächste Anweisung. Ein Hook, der durch Beendigung mit 2 blockiert, liefert seine stderr-Nachricht auf die gleiche Weise. Um Kontext in die Eltern-Sitzung einzufügen, nachdem ein Subagent zurückkommt, verwenden Sie stattdessen einen PostToolUse Hook auf dem Agent Tool.

TaskCreated

Wird ausgeführt, wenn eine Aufgabe über das TaskCreate Tool erstellt wird. Verwenden Sie dies, um Benennungskonventionen durchzusetzen, Aufgabenbeschreibungen zu erfordern oder zu verhindern, dass bestimmte Aufgaben erstellt werden. In einer Sitzung ohne die Task-Tools wird dieses Ereignis nicht ausgeführt.

TaskCreated-Hooks unterstützen keine Matcher und werden bei jedem Vorkommen ausgeführt.

TaskCreated-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten TaskCreated-Hooks task_id, task_subject und optional task_description, teammate_name und team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "TaskCreated",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

TaskCreated-Entscheidungskontrolle

Ein TaskCreated-Hook kann die Erstellung auf zwei Wegen blockieren. In beiden Fällen löscht Claude Code die Aufgabe und gibt Ihre Nachricht an Claude als Fehler des Tools zurück. Claude Code ignoriert continue: false aus diesem Ereignis und Claude arbeitet weiter.

• Exit-Code 2: Claude Code gibt den stderr-Text als die Nachricht zurück.
• JSON {"decision": "block", "reason": "..."}: Claude Code gibt reason als die Nachricht zurück.

Dieses Beispiel blockiert Aufgaben, deren Betreff nicht dem erforderlichen Format folgt:

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

if [[ ! "$TASK_SUBJECT" =~ ^\[TICKET-[0-9]+\] ]]; then
  echo "Task subject must start with a ticket number, e.g. '[TICKET-123] Add feature'" >&2
  exit 2
fi

exit 0

TaskCompleted

Wird ausgeführt, wenn eine Aufgabe als abgeschlossen markiert wird. Dies wird in zwei Situationen ausgeführt: wenn ein Agent eine Aufgabe explizit durch das TaskUpdate-Tool als abgeschlossen markiert oder wenn ein Agent-Team Teamkollege seinen Zug mit laufenden Aufgaben beendet. Verwenden Sie dies, um Abschluss-Kriterien wie bestandene Tests oder Lint-Überprüfungen durchzusetzen, bevor eine Aufgabe geschlossen werden kann.

TaskCompleted-Hooks unterstützen keine Matcher und werden bei jedem Vorkommen ausgeführt.

TaskCompleted-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten TaskCompleted-Hooks task_id, task_subject und optional task_description, teammate_name und team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TaskCompleted",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

TaskCompleted-Entscheidungskontrolle

TaskCompleted-Hooks unterstützen zwei Wege zur Steuerung des Aufgaben-Abschlusses:

• Exit-Code 2: Die Aufgabe wird nicht als abgeschlossen markiert und die stderr-Nachricht wird an das Modell als Feedback zurückgesendet.
• JSON {"continue": false, "stopReason": "..."}: Wenn ein Teamkollege, der seinen Zug beendet, das Ereignis ausgelöst hat, stoppt den Teamkollegen vollständig, was dem Stop Hook-Verhalten entspricht. Der stopReason wird dem Benutzer angezeigt. Wenn das TaskUpdate Tool das Ereignis ausgelöst hat, ignoriert Claude Code continue: false; Exit-Code 2 blockiert immer noch den Abschluss.

Dieses Beispiel führt Tests aus und blockiert den Aufgaben-Abschluss, wenn sie fehlschlagen:

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

# Run the test suite
if ! npm test 2>&1; then
  echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2
  exit 2
fi

exit 0

Stop

Wird ausgeführt, wenn der Haupt-Claude Code Agent mit dem Antworten fertig ist. Wird nicht ausgeführt, wenn der Stopp aufgrund einer Benutzerunterbrechung auftrat. API-Fehler führen stattdessen StopFailure aus.

Stop-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten Stop-Hooks stop_hook_active, last_assistant_message, background_tasks und session_crons. Das stop_hook_active Feld ist true, wenn Claude Code bereits als Ergebnis eines Stop-Hooks fortgesetzt wird. Überprüfen Sie diesen Wert oder verarbeiten Sie das Transkript, um zu vermeiden, auf einer Bedingung zu blockieren, die sich nie auflösen wird. Claude Code überschreibt den Hook und beendet den Zug nach 8 aufeinanderfolgenden Blockierungen.

Das last_assistant_message Feld enthält den Textinhalt von Claudes letzter Antwort, daher können Hooks darauf zugreifen, ohne die Transkript-Datei zu analysieren. Für Hooks, die auf dem gerade abgeschlossenen Zug handeln, wie Vorlesen oder Benachrichtigungs-Hooks, verwenden Sie dieses Feld statt transcript_path zu lesen: Die Transkript-Datei ist nicht garantiert, die letzte Nachricht bei Stop-Zeit auf allen Versionen einzuschließen.

Die background_tasks und session_crons Arrays ermöglichen es Hooks, "Sitzung ist fertig" von "Sitzung ist pausiert und wartet auf Hintergrund-Arbeit, um sie aufzuwecken" zu unterscheiden. Beide Arrays sind vorhanden, wenn die Task-Registry erreichbar ist und sind leer, wenn nichts in Flug oder geplant ist.

Jeder Eintrag in background_tasks beschreibt eine laufende Aufgabe und verwendet diese Felder:

Jeder Eintrag in session_crons beschreibt einen Sitzungs-scoped geplanten Aufweck, stammt von CronCreate, ScheduleWakeup und /loop:

Dieses Beispiel zeigt eine Stop-Eingabe mit einer laufenden Shell-Aufgabe und einem wiederkehrenden Cron:

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true,
  "last_assistant_message": "I've completed the refactoring. Here's a summary...",
  "background_tasks": [
    {
      "id": "task-001",
      "type": "shell",
      "status": "running",
      "description": "tail logs",
      "command": "tail -f /var/log/syslog"
    }
  ],
  "session_crons": [
    {
      "id": "cron-001",
      "schedule": "0 9 * * 1-5",
      "recurring": true,
      "prompt": "check the build"
    }
  ]
}

Stop-Entscheidungskontrolle

Stop und SubagentStop Hooks können steuern, ob Claude fortgesetzt wird. Zusätzlich zu den JSON-Ausgabefeldern, die für alle Hooks verfügbar sind, kann Ihr Hook-Skript diese ereignisspezifischen Felder zurückgeben:

Ein Hook, der durch Beendigung mit 2 blockiert, wird auf die gleiche Weise wie reason weitergeleitet: Claude empfängt die stderr-Nachricht als Erklärung, warum es fortgesetzt werden sollte.

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

Verwenden Sie additionalContext, wenn der Hook wie beabsichtigt funktioniert und Claude Anleitung gibt, wie "führe die Test-Suite vor dem Beenden aus". Es hält das Gespräch durch die gleichen Loop-Schutzmaßnahmen wie decision: "block" am Laufen, nämlich die stop_hook_active Eingabe und die 8-aufeinanderfolgende-Fortsetzungs-Kappe, aber das Transkript kennzeichnet es als Stop hook feedback und es wird keine Hook-Fehler-Benachrichtigung angezeigt:

{
  "hookSpecificOutput": {
    "hookEventName": "Stop",
    "additionalContext": "Please run the test suite before finishing"
  }
}

StopFailure

Wird statt Stop ausgeführt, wenn der Zug aufgrund eines API-Fehlers endet. Claude Code ignoriert die Ausgabe und den Exit-Code des Hooks, abgesehen von terminalSequence. Verwenden Sie dies, um Fehler zu protokollieren, Warnungen zu senden oder Wiederherstellungsmaßnahmen zu ergreifen, wenn Claude aufgrund von Ratenlimits, Authentifizierungsproblemen oder anderen API-Fehlern keine Antwort abschließen kann.

StopFailure-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten StopFailure-Hooks error, optional error_details und optional last_assistant_message. Das error Feld identifiziert den Fehlertyp und wird zum Filtern des Matchers verwendet.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "StopFailure",
  "error": "rate_limit",
  "error_details": "429 Too Many Requests",
  "last_assistant_message": "API Error: Rate limit reached"
}

StopFailure-Hooks haben keine Entscheidungskontrolle. Sie werden nur zu Benachrichtigungs- und Protokollierungszwecken ausgeführt.

TeammateIdle

Wird ausgeführt, wenn ein Agent-Team Teamkollege nach Abschluss seines Zugs untätig wird. Verwenden Sie dies, um Qualitäts-Gates durchzusetzen, bevor ein Teamkollege die Arbeit einstellt, wie das Erfordern bestandener Lint-Überprüfungen oder das Überprüfen, dass Ausgabe-Dateien existieren.

TeammateIdle-Hooks unterstützen keine Matcher und werden bei jedem Vorkommen ausgeführt.

TeammateIdle-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten TeammateIdle-Hooks teammate_name und team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TeammateIdle",
  "teammate_name": "researcher",
  "team_name": "session-a1b2c3d4"
}

TeammateIdle-Entscheidungskontrolle

TeammateIdle-Hooks unterstützen zwei Wege zur Steuerung des Teamkollegen-Verhaltens:

• Exit-Code 2: Der Teamkollege empfängt die stderr-Nachricht als Feedback und arbeitet weiter, anstatt untätig zu werden.
• JSON {"continue": false, "stopReason": "..."}: Stoppt den Teamkollegen vollständig, was dem Stop Hook-Verhalten entspricht. Der stopReason wird dem Benutzer angezeigt.

Dieses Beispiel überprüft, dass ein Build-Artefakt existiert, bevor ein Teamkollege untätig wird:

#!/bin/bash

if [ ! -f "./dist/output.js" ]; then
  echo "Build artifact missing. Run the build before stopping." >&2
  exit 2
fi

exit 0

ConfigChange

Wird ausgeführt, wenn sich eine Konfigurationsdatei während einer Sitzung ändert. Verwenden Sie dies, um Einstellungs-Änderungen zu überprüfen, Sicherheitsrichtlinien durchzusetzen oder nicht autorisierte Änderungen an Konfigurationsdateien zu blockieren.

Claude Code führt ConfigChange-Hooks aus, wenn sich eine Einstellungsdatei, eine verwaltete Richtlinien-Datei oder eine Skill-Datei ändert. Für verwaltete Richtlinien wird es nur ausgeführt, wenn managed-settings.json oder eine Datei in managed-settings.d/ sich ändert. Es wendet Server-verwaltete Einstellungen und Änderungen an macOS verwalteten Einstellungen oder Windows Registry-Richtlinien ohne Ausführung an. Auf WSL mit wslInheritsWindowsSettings wendet es auch eine geänderte Windows-seitige verwaltete Einstellungsdatei bei seiner Richtlinien-Abfrage ohne Ausführung an.

Der Matcher filtert auf die Konfigurationsquelle:

Dieses Beispiel protokolliert alle Konfigurationsänderungen für Sicherheits-Audits:

{
  "hooks": {
    "ConfigChange": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-config-change.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

ConfigChange-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten ConfigChange-Hooks source und optional file_path. Das source Feld gibt an, welcher Konfigurationstyp sich geändert hat, und file_path stellt den Pfad zur spezifischen Datei bereit, die geändert wurde.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ConfigChange",
  "source": "project_settings",
  "file_path": "/Users/.../my-project/.claude/settings.json"
}

ConfigChange-Entscheidungskontrolle

ConfigChange-Hooks können Konfigurationsänderungen blockieren, damit sie nicht wirksam werden. Verwenden Sie Exit-Code 2 oder ein JSON decision, um die Änderung zu verhindern. Wenn blockiert, werden die neuen Einstellungen nicht auf die laufende Sitzung angewendet.

{
  "decision": "block",
  "reason": "Configuration changes to project settings require admin approval"
}

policy_settings Änderungen können nicht blockiert werden. Hooks werden immer noch für policy_settings Quellen ausgeführt, wenn sich eine verwaltete Einstellungsdatei auf der Maschine ändert, daher können Sie sie verwenden, um diese Bearbeitungen zu protokollieren, aber jede Blockierungs-Entscheidung wird ignoriert. Dies stellt sicher, dass unternehmens-verwaltete Einstellungen immer wirksam werden. Claude Code führt ConfigChange Hooks nicht aus, wenn Server-verwaltete Einstellungen ankommen oder aktualisiert werden.

Claude Code handelt die Blockierungs-Entscheidung aus der JSON-Ausgabe eines ConfigChange-Hooks und verwirft systemMessage und continue. Eine blockierte Änderung zeigt keine Nachricht für Sie oder Claude, ob Sie mit reason oder mit stderr bei Beendigung mit 2 blockieren. Claude Code schreibt nur eine Zeile in das Debug-Protokoll.

CwdChanged

Wird ausgeführt, wenn ein Shell-Befehl in der Hauptkonversation das Arbeitsverzeichnis ändert, z. B. wenn Claude einen cd Befehl ausführt. Verwenden Sie dies, um auf Verzeichniswechsel zu reagieren: Umgebungsvariablen neu laden, projektspezifische Toolchains aktivieren oder Setup-Skripte automatisch ausführen. Paart mit FileChanged für Tools wie direnv, die Pro-Verzeichnis-Umgebung verwalten.

CwdChanged-Hooks haben Zugriff auf CLAUDE_ENV_FILE. Variablen, die in diese Datei geschrieben werden, bleiben in nachfolgenden Bash-Befehlen bestehen, bis zum nächsten CwdChanged-Ereignis, wenn Claude Code sie löscht.

CwdChanged unterstützt keine Matcher und wird bei jedem Vorkommen ausgeführt.

CwdChanged-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten CwdChanged-Hooks old_cwd und new_cwd.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project/src",
  "hook_event_name": "CwdChanged",
  "old_cwd": "/Users/my-project",
  "new_cwd": "/Users/my-project/src"
}

CwdChanged-Ausgabe

Zusätzlich zu den JSON-Ausgabefeldern, die für alle Hooks verfügbar sind, können CwdChanged-Hooks watchPaths zurückgeben, um dynamisch zu setzen, welche Dateipfade FileChanged überwacht:

CwdChanged-Hooks haben keine Entscheidungskontrolle. Sie können den Verzeichniswechsel nicht blockieren.

Claude Code liest watchPaths und systemMessage aus ihrer JSON-Ausgabe und verwirft continue. In interaktiven Sitzungen zeigt es die systemMessage als kurze Terminal-Benachrichtigung. Die Nachricht erreicht nicht den SDK-Nachrichtenstrom.

DirectoryAdded

Wird ausgeführt, nachdem Sie ein Arbeitsverzeichnis während einer Sitzung mit dem /add-dir Befehl hinzufügen oder nachdem ein SDK-Client eines mit der register_repo_root Kontroll-Anfrage hinzufügt. Verwenden Sie dies, um ein neu hinzugefügtes Repository vorzubereiten, z. B. durch Installation seiner Abhängigkeiten.

Claude Code führt dieses Ereignis nicht aus, wenn:

• Sie ein Verzeichnis mit dem --add-dir Start-Flag übergeben; SessionStart deckt diese Verzeichnisse ab
• Sie ein Verzeichnis auf der /permissions Workspace-Registerkarte hinzufügen
• Sie ein Verzeichnis hinzufügen, das bereits ein Arbeitsverzeichnis ist oder in einem liegt

Claude Code führt DirectoryAdded aus, nachdem Sandbox- und Berechtigungsstatus aktualisiert wurden, daher sehen Sandbox-Tools das neue Verzeichnis bereits, wenn Ihr Hook ausgeführt wird. Hook-Befehle selbst werden unsandboxed ausgeführt.

Claude Code wartet nicht auf den Hook: Das Hinzufügen wird sofort abgeschlossen und der Hook wird im Hintergrund mit dem 600-Sekunden-Standard-Timeout ausgeführt.

Der Matcher filtert, wie das Verzeichnis hinzugefügt wurde:

DirectoryAdded-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten DirectoryAdded-Hooks directory und source.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "DirectoryAdded",
  "directory": "/Users/my-other-repo",
  "source": "slash_command"
}

DirectoryAdded-Hooks haben keine Entscheidungskontrolle. Sie können das Hinzufügen nicht blockieren, das bereits abgeschlossen ist, wenn der Hook ausgeführt wird. Claude Code verwirft das continue Feld aus ihrer JSON-Ausgabe und zeigt den Rest unterschiedlich pro Quelle:

• slash_command: Claude Code liefert den systemMessage des Hooks an Claude als Kontext beim nächsten Gesprächszug, anstatt ihn Ihnen zu zeigen. Eine Anzahl fehlgeschlagener Hooks erscheint im Transkript. Vollständige Fehlerausgabe geht zum Debug-Protokoll
• register_repo_root: Claude Code schreibt systemMessage Ausgabe und Fehlerausgabe nur zum Debug-Protokoll

FileChanged

Wird ausgeführt, wenn sich eine überwachte Datei auf der Festplatte ändert. Claude Code erkennt Änderungen mit einem Dateisystem-Watcher, nicht durch Überprüfung von Tool-Aufrufen, daher wird der Hook unabhängig davon ausgeführt, was die Datei geändert hat: ein Edit oder Write Tool-Aufruf, ein Skript, das Claude mit Bash ausführt, oder ein Prozess außerhalb von Claude Code. Ein häufiger Anwendungsfall ist das Neuladen von Umgebungsvariablen, wenn sich Projekt-Konfigurationsdateien ändern.

Der matcher für dieses Ereignis dient zwei Rollen:

• Erstelle die Überwachungsliste: Der Wert wird auf | aufgeteilt und jedes Segment wird als wörtlicher Dateiname im Arbeitsverzeichnis registriert, daher überwacht ".envrc|.env" genau diese zwei Dateien. Regex-Muster sind hier nicht nützlich: Ein Wert wie ^\.env würde eine Datei wörtlich namens ^\.env überwachen.
• Filtere, welche Hooks ausgeführt werden: Wenn sich eine überwachte Datei ändert, wird der gleiche Wert verwendet, um zu filtern, welche Hook-Gruppen mit den Standard-Matcher-Regeln gegen den Dateinamen der geänderten Datei ausgeführt werden.

Dieses Beispiel normalisiert Zeilenumbrüche in data.csv nach jeder Änderung, einschließlich eines Bash Befehls oder eines externen Skripts, das die Datei umschreibt:

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": "data.csv",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/normalize-line-endings.sh"
          }
        ]
      }
    ]
  }
}

Der Hook liest den geänderten Dateipfad aus dem file_path Feld der JSON-Eingabe von stdin. Seine grep Wache testet auf das gleiche, das perl entfernt, einen CR am Ende einer Zeile, daher wird der Lauf nach einer Normalisierung beendet, ohne die Datei zu berühren. Eine lockere Wache schleift für immer, weil perl -i die Datei umschreibt, auch wenn es nichts ersetzt und Claude Code den Hook nach jedem Umschreiben erneut ausführt. Speichern Sie dieses Skript unter /path/to/normalize-line-endings.sh und machen Sie es ausführbar:

#!/bin/bash
FILE=$(jq -r .file_path)
if grep -q $'\r$' "$FILE"; then
  perl -pi -e 's/\r$//' "$FILE"
fi

Um zu bestätigen, dass der Hook funktioniert, bitten Sie Claude, eine CRLF-Zeile mit einem Bash Befehl zu data.csv anzuhängen. Claude Code führt den Hook aus und die Datei endet mit LF-Umbrüchen.

Um Dateien zu überwachen, die Sie nicht im Voraus benennen können, geben Sie watchPaths von einem Hook zurück, um die Überwachungsliste dynamisch zu aktualisieren. Claude Code startet den Watcher nur, wenn etwas eine Datei zum Überwachen benennt, daher seeden Sie die Liste mit einer FileChanged-Gruppe, deren Matcher mindestens eine Datei benennt, oder mit einem SessionStart oder CwdChanged Hook, der watchPaths zurückgibt. Der Matcher filtert immer noch, welche Hook-Gruppen ausgeführt werden, wenn sich eine überwachte Datei ändert, daher geben Sie der Gruppe, die dynamische Pfade verarbeitet, einen weggelassenen Matcher, der jede überwachte Datei abgleicht und nichts zur Überwachungsliste hinzufügt. Ein "*" Matcher gleicht auch jede Datei ab, aber Claude Code registriert ihn in der Überwachungsliste wie jeden anderen Wert, als wörtliche Datei namens *.

FileChanged-Hooks haben Zugriff auf CLAUDE_ENV_FILE. Variablen, die in diese Datei geschrieben werden, bleiben in nachfolgenden Bash-Befehlen bestehen, bis zum nächsten CwdChanged Ereignis, wenn Claude Code sie löscht.

FileChanged-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten FileChanged-Hooks file_path und event.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "FileChanged",
  "file_path": "/Users/my-project/.envrc",
  "event": "change"
}

FileChanged-Ausgabe

Zusätzlich zu den JSON-Ausgabefeldern, die für alle Hooks verfügbar sind, können FileChanged-Hooks watchPaths zurückgeben, um dynamisch zu aktualisieren, welche Dateipfade überwacht werden:

FileChanged-Hooks haben keine Entscheidungskontrolle. Sie können die Dateiänderung nicht blockieren.

Claude Code liest watchPaths und systemMessage aus ihrer JSON-Ausgabe und verwirft continue. In interaktiven Sitzungen zeigt es die systemMessage als kurze Terminal-Benachrichtigung. Die Nachricht erreicht nicht den SDK-Nachrichtenstrom.

WorktreeCreate

Wird ausgeführt, wenn ein Worktree erstellt wird, ob von claude --worktree, von einem Subagenten mit isolation: "worktree" oder für eine Hintergrund-Sitzung, die Claude Code in ihrem eigenen Worktree isoliert. Standardmäßig erstellt Claude Code die isolierte Arbeitskopie mit git worktree. Das Konfigurieren eines WorktreeCreate-Hooks ersetzt dieses Standard-Git-Verhalten, sodass Sie ein anderes Versionskontrollsystem wie SVN, Perforce oder Mercurial verwenden können.

Da der Hook das Standard-Verhalten vollständig ersetzt, wird .worktreeinclude nicht verarbeitet. Wenn Sie lokale Konfigurationsdateien wie .env in den neuen Worktree kopieren müssen, tun Sie dies in Ihrem Hook-Skript.

Der Hook muss den Pfad zum erstellten Worktree-Verzeichnis zurückgeben. Claude Code verwendet diesen Pfad als Arbeitsverzeichnis für die isolierte Sitzung. Siehe WorktreeCreate-Ausgabe, wie jeder Hook-Typ den Pfad zurückgibt.

Claude Code handelt den Erfolg des Hooks und den zurückgegebenen Pfad und verwirft systemMessage und continue.

Dieses Beispiel erstellt eine SVN-Arbeitskopie und druckt den Pfad für Claude Code zur Verwendung. Ersetzen Sie die Repository-URL durch Ihre eigene:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

Der Hook liest den Worktree name aus der JSON-Eingabe von stdin, checkt eine frische Kopie in ein neues Verzeichnis aus und druckt den Verzeichnispath. Das echo auf der letzten Zeile ist das, was Claude Code als Worktree-Pfad liest. Leiten Sie jede andere Ausgabe zu stderr um, damit sie nicht mit dem Pfad interferiert.

WorktreeCreate-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten WorktreeCreate-Hooks das name Feld. Dies ist ein Slug-Identifikator für den neuen Worktree, entweder vom Benutzer angegeben oder automatisch generiert, z. B. bold-oak-a3f2.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeCreate",
  "name": "feature-auth"
}

WorktreeCreate-Ausgabe

WorktreeCreate-Hooks verwenden nicht das Standard-Erlauben/Blockieren-Entscheidungsmodell. Stattdessen bestimmt der Erfolg oder Fehler des Hooks das Ergebnis. Der Hook muss den Pfad zum erstellten Worktree-Verzeichnis zurückgeben:

• Command-Hooks (type: "command"): Drucken Sie den Pfad als letzte nicht-leere Zeile von stdout. Claude Code entfernt ANSI-Escape-Codes, bevor diese Zeile gelesen wird, daher werden Shell-Start-Banner, die vor Ihrem echo gedruckt werden, ignoriert. Leiten Sie jede andere Hook-Ausgabe zu stderr um.
• HTTP-Hooks (type: "http"): Geben Sie { "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } } im Antwort-Body zurück.

Wenn der Hook fehlschlägt oder keinen Pfad erzeugt, schlägt die Worktree-Erstellung mit einem Fehler fehl.

Claude Code löst einen relativen Pfad gegen das Verzeichnis auf, in dem der Hook lief, und bricht alle . oder .. Segmente darin zusammen. Wenn der resultierende Pfad kein Verzeichnis ist, das Claude Code betreten kann, druckt die Sitzung einen Fehler, der den Pfad benennt, und beendet sich mit Code 1.

Claude Code lehnt einen absoluten Pfad ab, der . oder .. Segmente enthält, und jeden Pfad, der durch einen Symlink unterhalb der Repository-Root geht, da ein Symlink, der zum Repository committed ist, den Worktree außerhalb davon umleiten könnte. Der Fehler benennt die abgelehnte Komponente. Geben Sie einen normalisierten Pfad zurück, der nicht durch einen Symlink im Repository geht. Vor v2.1.216 folgte die Worktree-Erstellung dem Pfad des Hooks ohne diese Überprüfung.

WorktreeRemove

Wird ausgeführt, wenn ein Worktree entfernt wird. Dies ist das Bereinigungsgegenüber zu WorktreeCreate. Das Ereignis wird ausgeführt, wenn:

• Sie eine --worktree Sitzung beenden und wählen, sie zu entfernen
• Ein Subagent mit isolation: "worktree" beendet
• Sie eine Hintergrund-Sitzung löschen, deren Worktree der Hook erstellt hat

Für Git-basierte Worktrees verarbeitet Claude Code die Bereinigung automatisch mit git worktree remove. Wenn Sie einen WorktreeCreate-Hook für ein nicht-Git-Versionskontrollsystem konfiguriert haben, paaren Sie ihn mit einem WorktreeRemove-Hook, um die Bereinigung zu verarbeiten. Ohne einen wird das Worktree-Verzeichnis auf der Festplatte gelassen.

Claude Code verwirft die JSON-Ausgabefelder eines WorktreeRemove-Hooks, wie systemMessage und continue.

Für einen Hintergrund-Sitzungs-Löschung überprüft Claude Code den gespeicherten Worktree-Pfad, bevor der Hook ausgeführt wird, und lehnt einen Pfad ab, der ein Symlink ist oder durch einen unterhalb der Repository-Root geht. Der Hook wird für einen Worktree, der immer noch Dateien enthält, nur ausgeführt, wenn Sie den Löschvorgang in Agent-Ansicht bestätigen; für einen solchen Worktree behält claude rm die Sitzung und den Worktree statt. Vor v2.1.216 wurde der Hook auf dem gespeicherten Pfad ohne diese Überprüfungen ausgeführt.

Claude Code übergibt den von WorktreeCreate zurückgegebenen Pfad als worktree_path in der Hook-Eingabe. Dieses Beispiel liest diesen Pfad und entfernt das Verzeichnis:

{
  "hooks": {
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'"
          }
        ]
      }
    ]
  }
}

WorktreeRemove-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten WorktreeRemove-Hooks das worktree_path Feld, das der absolute Pfad zum entfernten Worktree ist.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeRemove",
  "worktree_path": "/Users/.../my-project/.claude/worktrees/feature-auth"
}

Der Exit-Code eines WorktreeRemove-Hooks entscheidet das Ergebnis. Wenn ein Hook mit nicht-Null beendet wird und das Verzeichnis bei worktree_path immer noch danach existiert, schlägt die Entfernung fehl:

• Der Worktree bleibt auf der Festplatte, und der Hook-Befehl und stderr gehen zum Debug-Protokoll.
• Wenn Sie eine Hintergrund-Sitzung löschten, bleibt die Sitzung auch. Die Verweigerungsmeldung in Agent-Ansicht meldet, wie der Hook endete, wie exited 1, zitiert den Anfang seines stderr und sagt, ob das Löschen der Sitzung erneut das Verzeichnis trotzdem entfernt.

PreCompact

Wird ausgeführt, bevor Claude Code einen Komprimierungsvorgang ausführen möchte.

Der Matcher-Wert gibt an, ob die Komprimierung manuell oder automatisch ausgelöst wurde:

Beenden Sie mit Code 2, um die Komprimierung zu blockieren. Für ein manuelles /compact wird die stderr-Nachricht dem Benutzer angezeigt. Sie können auch blockieren, indem Sie JSON mit "decision": "block" zurückgeben.

Das Blockieren der automatischen Komprimierung hat unterschiedliche Auswirkungen, je nachdem, wann es ausgeführt wird. Wenn die Komprimierung proaktiv ausgelöst wurde, bevor das Kontext-Limit erreicht wurde, überspringt Claude Code sie und das Gespräch wird unkomprimiert fortgesetzt. Wenn die Komprimierung ausgelöst wurde, um sich von einem Kontext-Limit-Fehler zu erholen, der bereits von der API zurückgegeben wurde, zeigt sich der zugrunde liegende Fehler und die aktuelle Anfrage schlägt fehl.

Claude Code verwirft die systemMessage und continue Felder eines PreCompact-Hooks.

PreCompact-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten PreCompact-Hooks trigger und custom_instructions. Für manual enthält custom_instructions das, was der Benutzer in /compact übergibt und ist null, wenn sie nichts übergeben. Für auto ist custom_instructions null.

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

PostCompact

Wird ausgeführt, nachdem Claude Code einen Komprimierungsvorgang abgeschlossen hat. Verwenden Sie dieses Ereignis, um auf den neuen komprimierten Zustand zu reagieren, z. B. um die generierte Zusammenfassung zu protokollieren oder externen Zustand zu aktualisieren. Claude Code verwirft die systemMessage und continue Felder eines PostCompact-Hooks.

Die gleichen Matcher-Werte gelten wie für PreCompact:

PostCompact-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten PostCompact-Hooks trigger und compact_summary. Das compact_summary Feld enthält die Gesprächs-Zusammenfassung, die vom Komprimierungsvorgang generiert wurde.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PostCompact",
  "trigger": "manual",
  "compact_summary": "Summary of the compacted conversation..."
}

PostCompact-Hooks haben keine Entscheidungskontrolle. Sie können das Komprimierungs-Ergebnis nicht beeinflussen, können aber Folge-Aufgaben ausführen.

PreModelSwitch

Wird ausgeführt, bevor Claude Code einen Modell-Wechsel anwendet, den Sie oder ein Client angefordert haben. Verwenden Sie ihn, um einen Wechsel zu blockieren, eine Bestätigung zu erfordern oder zu zeigen, was der Wechsel kostet, bevor er passiert.

PreModelSwitch erfordert Claude Code v2.1.251 oder später. Claude Code führt ihn für diese Anfragen aus:

• /model <name> und der /model Picker
• Der Option+P oder Alt+P Modell-Picker
• Die Modell-Einstellung in /config
• Das Aktivieren des Fast-Modus, wenn das das Modell der Sitzung ändert
• Eine set_model Anfrage oder eine Modell-Änderung in einer apply_flag_settings Anfrage von einem Agent SDK Host oder Remote Control

Claude Code führt PreModelSwitch-Hooks nicht für Wechsel aus, die es selbst macht, wie ein automatisches Modell-Fallback oder das Wiederherstellen des Modells, wenn Sie eine Sitzung fortsetzen. Diese Änderungen erreichen PostModelSwitch nur.

Claude Code vergleicht den Matcher gegen den kanonischen Namen des Modells, zu dem die Sitzung wechselt, und ignoriert jeden [1m] Suffix. Ein Alias wie opus, eine datierte Modell-ID und eine Provider-spezifische ID wie eine Amazon Bedrock Modell-ID gleichen alle den einen kanonischen Namen ab, den sie auflösen, daher deckt claude-opus-5 jede Schreibweise von Opus 5 ab.

Wenn Claude Code einen kanonischen Namen für das Ziel nicht bestimmen kann, z. B. eine benutzerdefinierte Modell-ID, die nur Ihr LLM-Gateway kennt, führt es jeden PreModelSwitch-Hook unabhängig vom Matcher aus. Ein Hook, der blockiert, sollte daher to_model aus seiner Eingabe überprüfen, anstatt sich nur auf den Matcher zu verlassen.

Schreiben Sie den Matcher als genauen Namen, eine |-getrennte Liste wie claude-opus-4-6|claude-opus-5 oder einen regulären Ausdruck wie .*opus.*. Dieses Beispiel verwendet einen genauen Namen-Matcher und überprüft auch to_model aus der Hook-Eingabe, daher verweigert es einen Wechsel zu Opus 4.6 durch Beendigung mit Code 2 und lässt jedes andere Ziel durch:

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "jq -e '.to_model | test(\"opus-4-6\")' > /dev/null && { echo 'Opus 4.6 is retired for this project. Use a newer model.' >&2; exit 2; }; exit 0"
}
]
}
]
}
}

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "powershell.exe",
"args": [
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
"${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1"
]
}
]
}
]
}
}

$hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
if ($hookInput.to_model -match 'opus-4-6') {
[Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.')
exit 2
}
exit 0

Um zu bestätigen, dass der Hook funktioniert, führen Sie /model claude-opus-4-6 aus einer Sitzung aus, die ein anderes Modell ausführt. Claude Code behält das aktuelle Modell und meldet, dass ein PreModelSwitch-Hook den Wechsel blockiert hat, mit Ihrer Nachricht als Grund.

PreModelSwitch-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten PreModelSwitch-Hooks die Felder in dieser Tabelle. Die letzten fünf beschreiben, was das Erneut-Senden des Gesprächs zum neuen Modell kostet, daher kann ein Hook diese Zahl zeigen, bevor der Wechsel passiert.

Dieses Beispiel zeigt die Eingabe für /model opus in einer Sitzung, die Sonnet 5 ausführt:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreModelSwitch",
  "from_model": "claude-sonnet-5",
  "to_model": "claude-opus-5",
  "requested_model": "opus",
  "source": "command",
  "context_tokens": 182340,
  "prompt_cache_warm": true,
  "cache_ttl": "5m",
  "estimated_cache_write_usd": 1.1396,
  "pricing": "catalog"
}

PreModelSwitch-Entscheidungskontrolle

PreModelSwitch Hooks können den Wechsel abbrechen, den Benutzer zur Bestätigung auffordern oder ihn fortgesetzt lassen. Exit-Code 2 oder ein Top-Level-decision: "block" bricht den Wechsel ab.

Für feinere Kontrolle geben Sie permissionDecision und permissionDecisionReason in einem hookSpecificOutput Objekt zurück, wie auf PreToolUse. PreModelSwitch akzeptiert "allow", "deny" und "ask". Es akzeptiert nicht "defer", updatedInput oder additionalContext. Die Tabelle unten beschreibt beide Felder:

Nur /model in einer interaktiven Sitzung kann die "ask" Aufforderung anzeigen. Auf jeder anderen Oberfläche, einschließlich nicht-interaktivem Modus mit dem -p Flag, /config und set_model Anfragen, behandelt Claude Code "ask" als Verweigerung.

Dieses Beispiel fordert den Benutzer zur Bestätigung auf und zitiert die Token-Anzahl aus context_tokens:

{
  "hookSpecificOutput": {
    "hookEventName": "PreModelSwitch",
    "permissionDecision": "ask",
    "permissionDecisionReason": "Switching now re-sends about 180k tokens to the new model. Continue?"
  }
}

Wenn mehrere PreModelSwitch-Hooks unterschiedliche Entscheidungen zurückgeben, ist die Priorität deny > ask > allow.

Claude Code zeigt dem Benutzer jede systemMessage, die Ihr Hook zurückgibt, unabhängig von der Entscheidung, daher kann ein Kosten-Bericht-Hook {"systemMessage": "..."} zurückgeben und mit 0 beenden.

Ein PreModelSwitch-Hook, der nicht vor seinem Timeout antwortet, blockiert den Wechsel. Bei PreToolUse lässt ein Timeout-Command-Hook den Tool-Aufruf dagegen fortgesetzt. Das Standard-Timeout für dieses Ereignis beträgt 30 Sekunden. PreModelSwitch führt nur command, http und mcp_tool Hooks aus, daher gelten die prompt und agent Standards nicht.

Ein Hook, der mit einem Code anderen als 0 oder 2 beendet und keine JSON-Entscheidung druckt, blockiert nicht: Claude Code zeigt sein stderr und wendet den Wechsel an, wie unter Andere Exit-Codes beschrieben.

PostModelSwitch

Wird ausgeführt, nachdem sich das Modell der Sitzung geändert hat. Verwenden Sie es, um Claude modell-spezifische Anleitung zu geben, ohne jede CLAUDE.md zu bearbeiten, z. B. eine organisations-weite Anweisung, die auf bestimmten Modellen gilt.

PostModelSwitch erfordert Claude Code v2.1.251 oder später. Es kann nicht blockieren, da sich das Modell bereits geändert hat. Claude Code führt PostModelSwitch-Hooks nach jeder dieser Änderungen aus:

• Ein Wechsel, den Sie oder ein Client angefordert haben
• Ein automatisches Modell-Fallback, das das Modell der Sitzung ändert
• Eine Einstellung wie opusplan, die den Plan-Modus betritt oder verlässt
• Claude Code stellt das Modell wieder her, wenn Sie eine Sitzung fortsetzen

Claude Code führt PostModelSwitch-Hooks nicht aus, wenn ein Modell aus einer Fallback-Modell-Kette einen Zug bedient, da diese Substitution einen Zug dauert und das Modell der Sitzung unverändert lässt.

Der Matcher folgt den gleichen Regeln wie PreModelSwitch: Claude Code vergleicht ihn gegen den kanonischen Namen des Modells, zu dem die Sitzung wechselt.

Dieses Beispiel fügt Anleitung hinzu, wenn sich das Modell der Sitzung zu einem Opus-Modell ändert:

{
  "hooks": {
    "PostModelSwitch": [
      {
        "matcher": ".*opus.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'On Opus, delegate implementation work to subagents and keep this conversation for planning and review.'"
          }
        ]
      }
    ]
  }
}

Um zu bestätigen, dass der Hook funktioniert, wechseln Sie zu einem Opus-Modell aus einer Sitzung, die ein anderes Modell ausführt, z. B. führen Sie /model opus aus einer Sonnet-Sitzung aus, und fragen Sie Claude dann, welche Anleitung es zum aktuellen Modell hat.

PostModelSwitch-Eingabe

PostModelSwitch-Hooks erhalten die gleichen Felder wie PreModelSwitch, mit hook_event_name auf "PostModelSwitch" gesetzt und zwei weitere source Werte: "auto" für ein automatisches Fallback oder eine andere Änderung, die Claude Code selbst gemacht hat, und "resume" für das Modell, das wiederhergestellt wird, wenn Sie eine Sitzung fortsetzen.

requested_model ist null, wenn source "auto" ist. Wenn source "resume" ist, ist es die gespeicherte Modell-Einstellung, die Claude Code wiederhergestellt hat.

PostModelSwitch-Entscheidungskontrolle

Claude Code nimmt Ihren Hook-Klartext-stdout bei Beendigung mit 0 oder additionalContext aus JSON-Ausgabe und liefert es an Claude mit der nächsten Anfrage nach dem Wechsel. Zusätzlich zu den JSON-Ausgabefeldern, die für alle Hooks verfügbar sind, können Sie zurückgeben:

Wenn der Hook nicht innerhalb von fünf Sekunden nach dem Senden der nächsten Eingabeaufforderung fertig ist, sendet Claude Code diese Anfrage ohne die Ausgabe und hängt sie stattdessen an die folgende Anfrage an. Wenn sich das Modell mehrmals ändert, bevor die nächste Anfrage erfolgt, liefert Claude Code nur die Ausgabe für den letzten Wechsel zum Ziel-Modell.

SessionEnd

Wird ausgeführt, wenn eine Claude Code Sitzung endet. Nützlich für Bereinigungsaufgaben, Protokollierung von Sitzungs-Statistiken oder Speicherung des Sitzungs-Zustands. Unterstützt Matcher zum Filtern nach Exit-Grund.

Das reason Feld in der Hook-Eingabe gibt an, warum die Sitzung endete:

SessionEnd-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten SessionEnd-Hooks ein reason Feld, das angibt, warum die Sitzung endete. Siehe die Grund-Tabelle oben für alle Werte.

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

SessionEnd-Hooks haben keine Entscheidungskontrolle. Sie können die Sitzungs-Beendigung nicht blockieren, können aber Bereinigungsaufgaben ausführen. Claude Code verwirft ihre JSON-Ausgabefelder, wie systemMessage.

SessionEnd-Hooks haben ein Standard-Timeout von 1,5 Sekunden. Es gilt, wenn Sie beenden, /clear ausführen oder mit interaktivem /resume zu Sitzungen wechseln. Sie können einem Hook auf zwei Wegen mehr Zeit geben:

• Pro-Hook timeout: Setzen Sie timeout in der Konfiguration dieses Hooks. Das Gesamt-Budget steigt automatisch, um das höchste Pro-Hook-timeout in Ihren Einstellungsdateien zu entsprechen, bis zu 60 Sekunden. Wenn Sie das Budget auf diese Weise erhöhen, behält ein Hook ohne sein eigenes timeout immer noch den Standard. Timeouts, die auf Plugin-bereitgestellten Hooks gesetzt sind, erhöhen das Budget nicht.
• CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS: Setzen Sie diese Umgebungsvariable in Millisekunden, um das Budget explizit zu überschreiben. Der Wert, den Sie setzen, wird auch zum Timeout für jeden Hook ohne sein eigenes timeout.

Dieses Beispiel setzt das Budget auf 5 Sekunden:

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

Vor v2.1.268 erhöhte CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS nur das Gesamt-Budget, und ein Hook ohne sein eigenes timeout wurde immer noch nach 1,5 Sekunden abgebrochen.

Elicitation

Wird ausgeführt, wenn ein MCP-Server Benutzereingabe während einer Aufgabe anfordert. Standardmäßig zeigt Claude Code einen interaktiven Dialog für den Benutzer zum Antworten. Hooks können diese Anfrage abfangen und programmatisch antworten, wobei der Dialog vollständig übersprungen wird.

Das Matcher-Feld gleicht gegen den MCP-Server-Namen ab.

Elicitation-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten Elicitation-Hooks mcp_server_name, message und optionale mode, url, elicitation_id und requested_schema Felder.

Für Form-Modus-Elicitierung, der häufigste Fall:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please provide your credentials",
  "mode": "form",
  "requested_schema": {
    "type": "object",
    "properties": {
      "username": { "type": "string", "title": "Username" }
    }
  }
}

Für URL-Modus-Elicitierung, verwendet für Browser-basierte Authentifizierung:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please authenticate",
  "mode": "url",
  "url": "https://auth.example.com/login"
}

Elicitation-Ausgabe

Um programmatisch ohne Anzeige des Dialogs zu antworten, geben Sie ein JSON-Objekt mit hookSpecificOutput zurück:

{
  "hookSpecificOutput": {
    "hookEventName": "Elicitation",
    "action": "accept",
    "content": {
      "username": "alice"
    }
  }
}

Exit-Code 2 verweigert die Elicitierung. Claude Code zeigt Ihre stderr-Nachricht nirgendwo an.

Claude Code handelt hookSpecificOutput aus der JSON-Ausgabe eines Elicitation-Hooks und verwirft systemMessage und continue.

ElicitationResult

Wird ausgeführt, nachdem ein Benutzer auf eine MCP-Elicitierung antwortet. Hooks können die Antwort beobachten, ändern oder blockieren, bevor sie an den MCP-Server zurückgesendet wird.

Das Matcher-Feld gleicht gegen den MCP-Server-Namen ab.

ElicitationResult-Eingabe

Zusätzlich zu den allgemeinen Eingabefeldern erhalten ElicitationResult-Hooks mcp_server_name, action und optionale mode, elicitation_id und content Felder.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ElicitationResult",
  "mcp_server_name": "my-mcp-server",
  "action": "accept",
  "content": { "username": "alice" },
  "mode": "form",
  "elicitation_id": "elicit-123"
}

ElicitationResult-Ausgabe

Um die Antwort des Benutzers zu überschreiben, geben Sie ein JSON-Objekt mit hookSpecificOutput zurück:

{
  "hookSpecificOutput": {
    "hookEventName": "ElicitationResult",
    "action": "decline",
    "content": {}
  }
}

Exit-Code 2 blockiert die Antwort und ändert die effektive Aktion zu decline. Claude Code zeigt Ihre stderr-Nachricht nirgendwo an.

Claude Code handelt hookSpecificOutput aus der JSON-Ausgabe eines ElicitationResult-Hooks und verwirft systemMessage und continue.

Prompt-basierte Hooks

Zusätzlich zu Command-, HTTP- und MCP-Tool-Hooks unterstützt Claude Code Prompt-basierte Hooks (type: "prompt"), die ein LLM verwenden, um zu evaluieren, ob eine Aktion zuzulassen oder zu blockieren ist, und Agent-Hooks (type: "agent"), die einen agentengesteuerten Verifizierer mit Tool-Zugriff spawnen. Nicht alle Ereignisse unterstützen jeden Hook-Typ.

Ereignisse, die alle fünf Hook-Typen unterstützen (command, http, mcp_tool, prompt und agent):

• PermissionDenied
• PostToolBatch
• PostToolUse
• PostToolUseFailure
• PreToolUse
• Stop
• SubagentStop
• TaskCompleted
• TaskCreated
• TeammateIdle
• UserPromptExpansion
• UserPromptSubmit

PermissionRequest unterstützt command, http, mcp_tool und prompt Hooks, aber keine agent Hooks. Wenn Sie einen Agent-Hook bei diesem Ereignis konfigurieren, überspringt Claude Code ihn und der Genehmigungsfluss wird unverändert fortgesetzt. Um von einem Hook aus zuzulassen oder zu verweigern, geben Sie das Entscheidungsobjekt von einem Command- oder HTTP-Hook zurück.

Ereignisse, die command, http und mcp_tool Hooks unterstützen, aber nicht prompt oder agent:

• ConfigChange
• CwdChanged
• DirectoryAdded
• Elicitation
• ElicitationResult
• FileChanged
• InstructionsLoaded
• MessageDisplay
• Notification
• PostCompact
• PostModelSwitch
• PreCompact
• PreModelSwitch
• SessionEnd
• StopFailure
• SubagentStart
• WorktreeCreate
• WorktreeRemove

SessionStart und Setup unterstützen command und mcp_tool Hooks, und MCP-Tool-Hook-Felder beschreibt, wann ihre mcp_tool Hooks ausgeführt werden. Sie unterstützen keine http, prompt oder agent Hooks.

Wie Prompt-basierte Hooks funktionieren

Anstatt einen Bash-Befehl auszuführen, Prompt-basierte Hooks:

1. Senden die Hook-Eingabe und Ihren Prompt an ein Claude-Modell, standardmäßig Haiku
2. Das LLM antwortet mit strukturiertem JSON, das eine Entscheidung enthält
3. Claude Code verarbeitet die Entscheidung automatisch

Prompt-Hook-Konfiguration

Setzen Sie type auf "prompt" und geben Sie eine prompt-Zeichenkette anstelle eines command an. Verwenden Sie den Platzhalter $ARGUMENTS, um die Hook-Eingabedaten in Ihren Prompt-Text einzufügen.

Dieser Stop-Hook fragt das LLM, ob Claude stoppen sollte, bevor Claude beendet wird:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."
          }
        ]
      }
    ]
  }
}

Response-Schema

Das LLM muss mit JSON antworten, das Folgendes enthält:

{
  "ok": true | false,
  "reason": "Explanation for the decision",
  "impossible": true | false
}

Was bei ok: false passiert, hängt vom Ereignis ab:

• Stop und SubagentStop: der Grund wird an Claude als nächste Anweisung zurückgegeben und der Turn wird fortgesetzt, es sei denn, die Antwort setzt auch impossible: true, in welchem Fall Claude Code den Stop zulässt und der Turn endet
• PreToolUse: der Tool-Aufruf wird verweigert; standardmäßig endet der Turn und der Verweigerungsgrund wird im Chat als Warnzeile angezeigt. Setzen Sie continueOnBlock: true, um den Grund stattdessen an Claude als Tool-Fehler zurückzugeben, damit es anpassen und fortfahren kann, äquivalent zu einem Command-Hook mit permissionDecision: "deny". Vor v2.1.210 wurde der Verweigerungsgrund an Claude als Tool-Fehler zurückgegeben und der Turn wurde fortgesetzt
• PostToolUse: standardmäßig endet der Turn und der Grund wird im Chat als Warnzeile angezeigt. Setzen Sie continueOnBlock: true, um den Grund an Claude zurückzugeben und den Turn stattdessen fortzusetzen
• PostToolBatch, UserPromptSubmit und UserPromptExpansion: der Turn endet und der Grund wird als Warnzeile angezeigt. Diese Ereignisse beenden den Turn bei decision: "block" unabhängig von continue
• PostToolUseFailure und TaskCreated: der Grund wird an Claude als Tool-Fehler zurückgegeben und der Turn wird fortgesetzt, unabhängig von continueOnBlock
• TaskCompleted: wenn es ausgelöst wird, weil eine Aufgabe während eines Turns als abgeschlossen markiert wird, wird der Grund an Claude als Tool-Fehler zurückgegeben und der Turn wird fortgesetzt, unabhängig von continueOnBlock. Wenn es ausgelöst wird, weil ein Teammate stoppt, verhält es sich wie TeammateIdle und stoppt den Teammate standardmäßig
• TeammateIdle: standardmäßig stoppt der Teammate und der Grund wird als Warnzeile angezeigt. Setzen Sie continueOnBlock: true, um den Grund an den Teammate zurückzugeben und ihn stattdessen weiterarbeiten zu lassen
• PermissionRequest: ok: false hat keine Auswirkung. Um eine Genehmigung von einem Hook zu verweigern, verwenden Sie einen Command-Hook mit hookSpecificOutput.decision.behavior: "deny"
• PermissionDenied: ok: false hat keine Auswirkung, da die Verweigerung bereits erfolgt ist. Die einzige Ausgabe, die dieses Ereignis liest, ist hookSpecificOutput.retry, die Prompt- und Agent-Hooks nicht setzen können. Sie werden bei diesem Ereignis ausgeführt, aber ihre Ausgabe wird verworfen. Verwenden Sie einen Command-Hook, um retry zurückzugeben

Wenn Sie eine feinere Kontrolle bei einem Ereignis benötigen, verwenden Sie einen Command-Hook mit den ereignisspezifischen Feldern, die in Entscheidungskontrolle beschrieben sind.

Mehrere Bedingungen vor dem Stoppen überprüfen

Dieser Stop-Hook verwendet einen detaillierten Prompt, um drei Bedingungen zu überprüfen, bevor Claude stoppen darf. SubagentStop-Hooks verwenden das gleiche Format, um zu evaluieren, ob ein Subagent stoppen sollte. Wenn das Modell "ok": false zurückgibt, weil die Bedingung noch nicht erfüllt ist, setzt Claude die Arbeit mit dem bereitgestellten Grund als nächste Anweisung fort:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Agent-basierte Hooks

Agent-basierte Hooks (type: "agent") sind wie Prompt-basierte Hooks, aber mit Multi-Turn-Tool-Zugriff. Anstelle eines einzelnen LLM-Aufrufs spawnt ein Agent-Hook einen Subagenten, der Dateien lesen, Code durchsuchen und die Codebasis überprüfen kann, um Bedingungen zu überprüfen. Agent-Hooks unterstützen die gleichen Ereignisse wie Prompt-basierte Hooks, mit Ausnahme von PermissionRequest.

Wie Agent-Hooks funktionieren

Wenn ein Agent-Hook ausgelöst wird:

1. Claude Code spawnt einen Subagenten mit Ihrem Prompt und der Hook-Eingabe JSON
2. Der Subagent kann Tools wie Read, Grep und Glob verwenden, um zu untersuchen
3. Nach bis zu 50 Turns gibt der Subagent eine strukturierte { "ok": true/false }-Entscheidung zurück
4. Claude Code erlaubt die Aktion, wenn ok true ist. Wenn ok false ist, verarbeitet Claude Code die Blockierung auf die gleiche Weise wie ein Prompt-Hook mit continueOnBlock: true bei diesem Ereignis, wie unter Response-Schema aufgelistet

Agent-Hooks sind nützlich, wenn die Überprüfung das Überprüfen tatsächlicher Dateien oder Test-Ausgabe erfordert, nicht nur die Evaluierung der Hook-Eingabedaten allein.

Agent-Hook-Konfiguration

Setzen Sie type auf "agent" und geben Sie eine prompt-Zeichenkette an, wobei Sie $ARGUMENTS als Platzhalter für die Hook-Eingabe JSON verwenden. Die Konfigurationsfelder sind die gleichen wie Prompt-Hooks, mit der Ausnahme, dass Agent-Hooks ein längeres Standard-Timeout von 60 Sekunden haben und kein continueOnBlock-Feld haben.

Das Response-Schema ist { "ok": true } zum Zulassen oder { "ok": false, "reason": "..." } zum Blockieren. Bei ok: false verarbeitet Claude Code einen Agent-Hook auf die gleiche Weise wie einen Prompt-Hook mit continueOnBlock: true bei demselben Ereignis; Agent-Hooks haben kein continueOnBlock-Feld und unterstützen nicht das Prompt-Hook-Feld impossible.

Dieser Stop-Hook überprüft, dass alle Unit-Tests bestanden sind, bevor Claude fertig ist:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Hooks im Hintergrund ausführen

Standardmäßig blockieren Hooks die Ausführung von Claude, bis sie abgeschlossen sind. Für lang laufende Aufgaben wie Bereitstellungen, Test-Suites oder externe API-Aufrufe setzen Sie "async": true, um den Hook im Hintergrund auszuführen, während Claude weiterarbeitet. Asynchrone Hooks können nicht blockieren oder das Verhalten von Claude steuern: Response-Felder wie decision, permissionDecision und continue haben keine Auswirkung, da die Aktion, die sie steuern würden, bereits abgeschlossen ist.

Konfigurieren Sie einen asynchronen Hook

Fügen Sie "async": true zur Konfiguration eines Command-Hooks hinzu, um ihn im Hintergrund auszuführen, ohne Claude zu blockieren. Dieses Feld ist nur auf type: "command"-Hooks verfügbar.

Dieser Hook führt ein Test-Skript nach jedem Write-Tool-Aufruf aus. Claude arbeitet sofort weiter, während run-tests.sh ausgeführt wird. Wenn das Skript fertig ist, wird seine Ausgabe beim nächsten Gesprächsturn geliefert:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/run-tests.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

Sobald ein asynchroner Hook im Hintergrund ausgeführt wird, erzwingt Claude Code kein timeout darauf. Claude Code erzwingt immer noch timeout auf einem Hook, den Sie mit asyncRewake ausführen.

Claude Code liefert die Ergebnisse eines asynchronen Hooks nur während der Sitzung:

• Im nicht-interaktiven Modus mit dem Flag -p beendet Claude Code jeden noch laufenden asynchronen Hook beim Herunterfahren und finalisiert ihn mit dem Ergebnis cancelled
• Wenn die Arbeit Ihres Hooks eine claude -p-Sitzung überdauern muss, starten Sie einen vollständig abgelösten Prozess davon

Wie asynchrone Hooks ausgeführt werden

Wenn ein asynchroner Hook ausgelöst wird, startet Claude Code den Hook-Prozess und setzt sofort fort, ohne auf den Abschluss zu warten. Der Hook erhält die gleiche JSON-Eingabe über stdin wie ein synchroner Hook.

Nachdem der Hintergrund-Prozess beendet ist, liefert Claude Code die Felder additionalContext und systemMessage aus der JSON-Response des Hooks Claude beim nächsten Gesprächsturn. Im Gegensatz zu einem synchronen Hook's systemMessage wird keines dieser Felder Ihnen angezeigt.

Claude Code validiert diese JSON-Response gegen das gleiche Ausgabeschema wie synchrone Hooks und verwirft jedes Feld, dessen Wert den falschen Typ hat, wie z. B. eine systemMessage, die keine Zeichenkette ist, anstatt es zu liefern. Führen Sie mit --debug aus, um eine Warnung zu sehen, die jedes verworfene Feld benennt. Vor v2.1.202 konnte fehlerhafte JSON-Ausgabe von einem asynchronen Hook die Sitzung zum Absturz bringen, und der Absturz trat jedes Mal auf, wenn die Sitzung fortgesetzt wurde.

Benachrichtigungen über den Abschluss asynchroner Hooks werden standardmäßig unterdrückt. Um sie zu sehen, aktivieren Sie den ausführlichen Modus mit Ctrl+O oder starten Sie Claude Code mit --verbose.

Tests nach Dateiänderungen ausführen

Dieser Hook startet eine Test-Suite im Hintergrund, wenn Claude eine Datei schreibt, und meldet die Ergebnisse Claude, wenn die Tests fertig sind. Speichern Sie dieses Skript unter .claude/hooks/run-tests-async.sh in Ihrem Projekt und machen Sie es mit chmod +x ausführbar:

#!/bin/bash
# run-tests-async.sh

# Hook-Eingabe von stdin lesen
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Tests nur für Quelldateien ausführen
if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
  exit 0
fi

# Tests ausführen und Ergebnisse über additionalContext an Claude melden
RESULT=$(npm test 2>&1)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  MSG="Tests passed after editing $FILE_PATH"
else
  MSG="Tests failed after editing $FILE_PATH: $RESULT"
fi
jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'

Fügen Sie dann diese Konfiguration zu .claude/settings.json im Projekt-Root hinzu. Das Flag async: true ermöglicht es Claude, weiterarbeiten zu können, während Tests ausgeführt werden:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",
            "args": [],
            "async": true
          }
        ]
      }
    ]
  }
}

Einschränkungen

Asynchrone Hooks haben zusätzliche Einschränkungen im Vergleich zu synchronen Hooks:

• Hook-Ausgabe wird beim nächsten Gesprächsturn geliefert. Wenn die Sitzung untätig ist, wartet die Response, bis die nächste Benutzerinteraktion erfolgt. Ausnahme: Ein asyncRewake-Hook, der mit Code 2 beendet wird, weckt Claude sofort auf, auch wenn die Sitzung untätig ist.
• Jede Ausführung erstellt einen separaten Hintergrund-Prozess. Es gibt keine Deduplizierung über mehrere Auslösungen des gleichen asynchronen Hooks.

Sicherheitsüberlegungen

Haftungsausschluss

Workspace-Vertrauen

Claude Code überprüft das Workspace-Vertrauen, bevor es einen Hook aus einer Einstellungsdatei ausführt. Was als vertrauenswürdig gilt, hängt vom Sitzungstyp ab:

• Interaktive Sitzung: Claude Code hält Hooks aus jeder Einstellungsdatei zurück, einschließlich Ihrer eigenen ~/.claude/settings.json, bis Sie den Workspace-Vertrauensdialog für den Ordner oder für ein übergeordnetes Verzeichnis, dessen Vertrauen sich darauf erstreckt, akzeptieren
• -p oder SDK-Sitzung: Claude Code zeigt den Dialog nie an und behandelt den Ordner als vertrauenswürdig, sodass Hooks, die in der .claude/settings.json eines Repositorys committed sind, in einem Ordner ausgeführt werden, dem Sie nie vertraut haben

Bevor Sie claude -p über ein Repository ausführen, das Sie nicht geschrieben haben, überprüfen Sie seine .claude/-Einstellungsdateien, starten Sie mit --bare, oder deaktivieren Sie Hooks für diesen Durchlauf mit --settings '{"disableAllHooks": true}'. Frontmatter-Hooks in einem Projekt-Subagent folgen einer strengeren Regel als Einstellungsdatei-Hooks. Was vor dem Vertrauen eines Ordners ausgeführt wird listet jede Art von Repository-Inhalt nach Sitzungstyp auf.

Best Practices für Sicherheit

Beachten Sie diese Praktiken beim Schreiben von Hooks:

• Validieren und bereinigen Sie Eingaben: Vertrauen Sie niemals blind auf Eingabedaten
• Zitieren Sie immer Shell-Variablen: Verwenden Sie "$VAR" nicht $VAR
• Blockieren Sie Pfad-Traversal: Prüfen Sie auf .. in Dateipfaden
• Verwenden Sie absolute Pfade: Geben Sie vollständige Pfade für Skripte an. In der Exec-Form verwenden Sie ${CLAUDE_PROJECT_DIR} und der Pfad benötigt keine Anführungszeichen. In der Shell-Form wickeln Sie ihn in doppelte Anführungszeichen ein
• Überspringen Sie sensible Dateien: Vermeiden Sie .env, .git/, Schlüssel, etc.

Windows PowerShell-Tool

Unter Windows können Sie einzelne Hooks in PowerShell ausführen, indem Sie "shell": "powershell" auf einem Command-Hook setzen. Claude Code erkennt automatisch pwsh.exe, die PowerShell 7 und später ausführbare Datei, und fällt auf powershell.exe für Windows PowerShell 5.1 zurück.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "Write-Host 'File written'"
          }
        ]
      }
    ]
  }
}

Um auf das Projektverzeichnis aus einem PowerShell-Shell-Form-Befehl zu verweisen, schreiben Sie ${CLAUDE_PROJECT_DIR} oder $env:CLAUDE_PROJECT_DIR. Ab v2.1.198 schreibt Claude Code die Platzhalter ${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_ROOT} und ${CLAUDE_PLUGIN_DATA} in einem PowerShell-Shell-Form-Befehl in die PowerShell-Form ${env:NAME} um, unabhängig davon, ob der Hook in settings.json, einem Plugin oder einer Skill definiert ist. PowerShell löst dann den Wert aus der exportierten Umgebung nach dem Parsing auf, daher funktioniert der Platzhalter in doppelt angeführten Zeichenketten, aber nicht in einfach angeführten Zeichenketten, wo PowerShell niemals Variablen erweitert.

Vor v2.1.198 galt dieses Umschreiben nur für Plugin-Hooks. In früheren Versionen benötigt ein settings.json-Hook die Form $env: oder Exec-Form, wobei ${CLAUDE_PROJECT_DIR} in jedem args-Element ersetzt wird, unabhängig davon, wo der Hook definiert ist.

Schreiben Sie nicht die bloße Schreibweise $CLAUDE_PROJECT_DIR in einem PowerShell-Hook. PowerShell analysiert sie als undefinierte lokale Variable und löst sie zu $null auf, was den Skriptpfad ohne sein Projektverzeichnis-Präfix hinterlässt. Claude Code schreibt diese Form nicht um; stattdessen protokolliert es eine Warnung im Debug-Log.

Das folgende Beispiel zeigt einen settings.json-Hook, der ein Projektskript mit der Form $env: ausführt, die auf jeder Version funktioniert:

{
  "type": "command",
  "shell": "powershell",
  "command": "& \"$env:CLAUDE_PROJECT_DIR\\.claude\\hooks\\check.ps1\""
}

Debug-Hooks

Hook-Ausführungsdetails werden in die Debug-Log-Datei geschrieben. Starten Sie Claude Code mit claude --debug-file <path>, um das Log in einen bekannten Speicherort zu schreiben, oder führen Sie claude --debug aus und lesen Sie das Log unter ~/.claude/debug/<session-id>.txt. Das Flag --debug gibt nicht auf dem Terminal aus.

Beispielsweise erzeugt ein PostToolUse-Hook auf Write, dessen Befehl hook-ran ausgibt, Einträge wie:

2026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text
2026-07-19T02:03:24.382Z [DEBUG] "Hook PostToolUse:Write (PostToolUse) success:\nhook-ran"

Für granularere Hook-Matching-Details setzen Sie CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose, um zusätzliche Log-Zeilen wie Hook-Matcher-Zählungen und Query-Matching zu sehen.

Zur Fehlerbehebung häufiger Probleme wie Hooks, die nicht ausgelöst werden, Stop-Hooks, die weiterhin blockieren, oder Konfigurationsfehler, siehe Einschränkungen und Fehlerbehebung in der Anleitung. Für eine umfassendere diagnostische Anleitung, die /context, /doctor und Einstellungspriorität abdeckt, siehe Debug your config.