Im nicht interaktiven Modus mit dem Flag -p bietet Claude Code AskUserQuestion und ExitPlanMode nur an, wenn der Lauf einen Berechtigungs-Host hat, der die Abfrage entgegennimmt, etwa einen canUseTool-Callback des Agent SDK. Diese Tools erfordern Benutzerinteraktion. Die Rückgabe von permissionDecision: "allow" zusammen mit updatedInput erfüllt diese Anforderung: Der Hook liest die Eingabe des Tools von stdin, erfasst die Antwort über Ihre eigene Oberfläche und gibt sie in updatedInput zurück, sodass das Tool ohne Abfrage ausgeführt wird. Die Rückgabe von "allow" allein reicht für diese Tools nicht aus. Für AskUserQuestion geben Sie das ursprüngliche questions-Array zurück und fügen ein answers-Objekt hinzu, das den Text jeder Frage der gewählten Antwort zuordnet.

Ein MCP-Tool, das sein Server mit _meta["anthropic/requiresUserInteraction"] kennzeichnet, ist strenger: Ein Hook kann dessen Genehmigungsabfrage mit "allow" nicht überspringen, weder mit noch ohne updatedInput, da Claude Code nicht bestätigen kann, dass der Hook die vom Tool benötigte Interaktion erfasst hat.

Einen Tool-Aufruf für später zurückstellen

"defer" ist für Integrationen gedacht, die claude -p als Subprozess ausführen und dessen JSON-Ausgabe lesen, etwa eine Agent SDK-App oder eine auf Claude Code aufbauende benutzerdefinierte Oberfläche. Damit kann der aufrufende Prozess Claude bei einem Tool-Aufruf anhalten, Eingaben über seine eigene Oberfläche erfassen und dort weitermachen, wo er aufgehört hat. Claude Code berücksichtigt diesen Wert nur im nicht interaktiven Modus mit dem Flag -p. In interaktiven Sitzungen protokolliert es eine Warnung und ignoriert das Hook-Ergebnis.

Das Tool AskUserQuestion ist der typische Fall: Claude möchte dem Benutzer eine Frage stellen, aber es gibt kein Terminal, in dem geantwortet werden kann. Ein -p-Lauf bietet AskUserQuestion nur an, wenn er einen Berechtigungs-Host hat, etwa ein MCP-Tool, das Sie mit --permission-prompt-tool übergeben. Starten Sie den Lauf daher mit einem solchen. Der Ablauf funktioniert so:

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

Das Feld deferred_tool_use enthält id, name und input des Tools. input sind die Parameter, die Claude für den Tool-Aufruf erzeugt 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 weder einen Timeout noch ein Limit für Wiederholungsversuche. Die Sitzung bleibt auf der Festplatte, bis Sie sie fortsetzen, vorbehaltlich der Aufbewahrungsbereinigung durch cleanupPeriodDays, die Sitzungsdateien standardmäßig nach 30 Tagen löscht, gemäß den Regeln der Aufbewahrungsbereinigung. Wenn die Antwort beim Fortsetzen noch nicht bereit ist, kann der Hook erneut "defer" zurückgeben, und der Prozess wird auf dieselbe Weise beendet. Der aufrufende Prozess bestimmt, wann die Schleife endet, indem er schließlich "allow" oder "deny" aus dem Hook zurückgibt.

"defer" funktioniert nur, wenn Claude im Turn einen einzigen Tool-Aufruf durchführt. Wenn Claude mehrere Tool-Aufrufe gleichzeitig durchführt, wird "defer" mit einer Warnung ignoriert, und das Tool durchläuft den normalen Berechtigungsablauf. Diese Einschränkung besteht, weil beim Fortsetzen nur ein Tool erneut ausgeführt werden kann: Es gibt keine Möglichkeit, einen Aufruf aus einem Stapel zurückzustellen, ohne die anderen ungeklärt zu lassen.

Wenn das zurückgestellte Tool beim Fortsetzen nicht mehr verfügbar ist, wird der Prozess mit stop_reason: "tool_deferred_unavailable" und is_error: true beendet, bevor der Hook ausgelöst wird. Das passiert, wenn ein MCP-Server, der das Tool bereitgestellt hat, für die fortgesetzte Sitzung nicht verbunden ist. Die Payload deferred_tool_use ist trotzdem enthalten, sodass Sie erkennen können, welches Tool fehlt.

PermissionRequest

Wird ausgeführt, wenn Claude Code Sie gleich um Erlaubnis zur Verwendung eines Tools bitten wird. In Sitzungen, die keine Abfrage anzeigen können, etwa bei Subagenten im Hintergrund im nicht interaktiven Modus, führt Claude Code diese Hooks trotzdem aus, und wenn kein Hook eine Entscheidung zurückgibt, lehnt es den Tool-Aufruf ab. Bei einem Aufruf, der ein --permission-prompt-tool oder den canUseTool-Callback des Agent SDK erreicht, laufen die Hooks parallel zu Ihrem Host, und es gilt, wer zuerst entscheidet. Verwenden Sie die PermissionRequest-Entscheidungssteuerung, um im Namen des Benutzers zuzulassen oder abzulehnen.

Verwenden Sie dieses Ereignis, wenn Sie ein Signal in dem Moment benötigen, in dem Claude um Erlaubnis zur Verwendung eines Tools bittet. Claude Code führt einen Notification-Hook mit dem Typ permission_prompt erst aus, nachdem die Abfrage etwa sechs Sekunden gewartet hat.

Claude Code führt keine PermissionRequest-Hooks für die Netzwerkanfrage eines in einer Sandbox ausgeführten Befehls aus. Um für diese Abfrage ein Signal zu erhalten, verwenden Sie den Benachrichtigungstyp permission_prompt.

Matcht auf den Tool-Namen, mit denselben Werten wie PreToolUse.

PermissionRequest-Eingabe

PermissionRequest-Hooks erhalten wie PreToolUse-Hooks die Felder tool_name und tool_input, jedoch ohne tool_use_id. Bei einem MCP-Tool erhalten sie außerdem das Objekt mcp_server. Ein optionales Array permission_suggestions enthält die Berechtigungsaktualisierungen, die Claude Code für diese Anfrage vorschlägt, etwa das Hinzufügen einer allow-Regel oder das Ändern des Berechtigungsmodus.

Das Array permission_suggestions ist keine exakte Liste der angezeigten Optionen, da jeder Berechtigungsdialog seine eigenen Optionen aufbaut. Manche Dialoge, etwa der für Dateibearbeitungen, lesen das Array überhaupt nicht und leiten ihre Optionen aus der Anfrage selbst ab. Ein Dialog, der es liest, kann dennoch eine Option zurückhalten, deren Vorschlag im Array verbleibt, zum Beispiel wenn allowManagedPermissionRulesOnly Optionen zum Speichern von Regeln ausblendet. Er kann auch Optionen anbieten, für die es keinen Vorschlagseintrag gibt, etwa Yes, and switch to auto mode, das den Berechtigungsmodus direkt ändert statt über eine Berechtigungsaktualisierung.

PreToolUse-Hooks werden vor jedem Tool-Aufruf ausgeführt, unabhängig davon, ob er eine Berechtigung benötigt. PermissionRequest-Hooks werden nur ausgeführt, wenn Claude Code Sie gleich um Erlaubnis bitten wird oder wenn es andernfalls einen Aufruf, der keine Abfrage anzeigen kann, automatisch ablehnen würde. Keines der beiden Ereignisse wird für EndConversation ausgelöst.

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

PermissionRequest-Entscheidungssteuerung

PermissionRequest-Hooks können Berechtigungsanfragen zulassen oder ablehnen. Zusätzlich zu den JSON-Ausgabefeldern, die allen Hooks zur Verfügung stehen, kann Ihr Hook-Skript ein decision-Objekt mit diesen ereignisspezifischen Feldern zurückgeben:

Ein Hook, der ohne decision-Objekt mit 2 beendet wird, lässt den Berechtigungsablauf unverändert, und sein stderr wird verworfen. Nur das decision-Objekt kann die Anfrage genehmigen oder ablehnen.

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

Einträge für Berechtigungsaktualisierungen

Das Ausgabefeld updatedPermissions und das Eingabefeld permission_suggestions verwenden beide dasselbe Array von Eintragsobjekten. Jeder Eintrag hat einen type, der seine übrigen Felder bestimmt, und eine destination, die steuert, wohin die Änderung geschrieben wird.

Das Feld destination jedes Eintrags bestimmt, ob die Änderung nur im Arbeitsspeicher bleibt oder in eine Einstellungsdatei geschrieben wird.

Ein Hook kann einen der empfangenen permission_suggestions als eigene updatedPermissions-Ausgabe zurückgeben.

PostToolUse

Wird unmittelbar ausgeführt, nachdem ein Tool erfolgreich abgeschlossen wurde.

Matcht auf den Tool-Namen, mit denselben Werten wie PreToolUse.

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

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

PostToolUse-Eingabe

PostToolUse-Hooks werden ausgelöst, nachdem ein Tool bereits erfolgreich ausgeführt wurde. Die Eingabe enthält sowohl tool_input, die an das Tool gesendeten Argumente, als auch tool_response, das vom Tool zurückgegebene Ergebnis. Das genaue Schema beider Felder hängt vom Tool ab. Pfade in tool_input von Datei-Tools kommen im selben Format wie bei PreToolUse an: immer absolut, mit den nativen Trennzeichen der Plattform, unter Windows also mit Backslashes. Bei einem MCP-Tool enthält die Eingabe außerdem das Objekt mcp_server.

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

PostToolUse-Hooks können Claude nach der Tool-Ausführung Feedback geben. Zusätzlich zu den JSON-Ausgabefeldern, die allen Hooks zur Verfügung stehen, kann Ihr Hook-Skript diese ereignisspezifischen Felder zurückgeben:

Das folgende Beispiel ersetzt die Ausgabe eines Bash-Aufrufs. Der Ersatzwert entspricht der Ausgabestruktur des Bash-Tools:

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

Ein Ergebnis für den Klassifikator des Auto-Modus annotieren

Geben Sie classifierContext zurück, um eine kurze Notiz zum Ergebnis des Tool-Aufrufs an den Klassifikator des Auto-Modus statt an Claude zu senden. Der Klassifikator erhält niemals die Tool-Ergebnisse selbst, daher ist dieses Feld der unterstützte Weg, ihm etwas darüber mitzuteilen, was ein Aufruf zurückgegeben hat, bevor er spätere Aktionen prüft. Das Feld erfordert Claude Code v2.1.236 oder höher.

Das folgende Beispiel teilt dem Klassifikator mit, woher die Ausgabe einer Abfrage stammt:

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

Wie stark der Klassifikator die Notiz gewichtet, hängt davon ab, wo Sie den Hook konfiguriert haben:

• In Claude Code konfigurierte Hooks: Bei Hooks aus Einstellungsdateien, Plugins, Skills und Agenten-Frontmatter behandelt der Klassifikator die Notiz als nicht verifizierten, von der Anwendung bereitgestellten Kontext. Die Notiz begründet niemals eine Benutzerabsicht, und wenn sie behauptet, Sie hätten etwas genehmigt oder angefordert, prüft der Klassifikator diese Behauptung anhand Ihrer eigenen Nachrichten in der Konversation
• In-Process-Callbacks des Agent SDK: Wenn eine Anwendung, die Claude Code einbettet, den Hook als TypeScript-SDK-Callback registriert und die Notiz während der laufenden Sitzung zurückgibt, kann der Klassifikator eine in der Notiz weitergegebene Benutzeraussage als Benutzerabsicht werten. Eine solche Aussage kann eine Zustimmungsanforderung erfüllen, die der Klassifikator auch von einer von Ihnen gesendeten Nachricht akzeptieren würde, hebt aber niemals eine Blockierung auf, die auch Ihre eigene Nachricht nicht aufheben könnte. Nach dem Fortsetzen einer Sitzung behandelt Claude Code wiederhergestellte Notizen als nicht verifizierten Kontext. Wenn Hooks aus beiden Gruppen denselben Aufruf annotieren, behandelt der Klassifikator die kombinierte Notiz als nicht verifiziert

Claude Code wendet beim Zustellen der Notiz diese Grenzen an:

• Länge: Claude Code begrenzt die Notizen für einen Tool-Aufruf auf 2.000 Zeichen und schneidet den Rest ab. Die Grenze gilt gemeinsam für alle Hooks, die auf diesen Aufruf antworten
• Nur synchrone Antworten: Claude Code ignoriert das Feld in der Antwort eines Hooks, der im Hintergrund ausgeführt wird, da diese Antwort eintrifft, nachdem Claude Code das Tool-Ergebnis aufgezeichnet hat
• Aufrufe, die der Klassifikator nicht aufzeichnet: Das Transkript des Klassifikators lässt nur lesende Abfragen wie Dateilesevorgänge und Suchen aus. Claude Code verwirft eine Notiz, die an einen dieser Aufrufe angehängt ist
• Zusammenspiel mit Umschreibungen: Wenn die Notiz eine Ausgabe beschreibt, die Sie mit updatedToolOutput ersetzen, geben Sie beide Felder in derselben Hook-Antwort zurück. Claude Code verwirft die Notiz, wenn diese Umschreibung abgelehnt wird oder die Umschreibung eines anderen Hooks sie ersetzt. Eine Notiz, die Sie ohne Umschreibung zurückgeben, stellt Claude Code auch dann zu, wenn ein anderer Hook die Ausgabe umschreibt

PostToolUseFailure

Wird ausgeführt, wenn ein Tool, dessen Ausführung begonnen hat, fehlschlägt: Das Tool hat einen Fehler ausgelöst, oder ein MCP-Tool hat ein Fehlerergebnis zurückgegeben. Verwenden Sie dies, um Fehler zu protokollieren, Warnungen zu senden oder Claude korrigierendes Feedback zu geben.

Matcht auf den Tool-Namen, mit denselben Werten wie PreToolUse.

PostToolUseFailure-Eingabe

PostToolUseFailure-Hooks erhalten dieselben Felder tool_name und tool_input wie PostToolUse, zusammen mit Fehlerinformationen als Felder der obersten Ebene. Bei einem MCP-Tool erhalten sie außerdem das Objekt mcp_server. Ein fehlgeschlagener npm test-Befehl könnte beispielsweise Folgendes 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 Zeichenfolge error ist im Allgemeinen derselbe Text, den Claude als Ergebnis des fehlgeschlagenen Tools erhält. Ihr Format variiert je nach Tool und Fehler. Richten Sie Ihren Hook an tool_name, is_interrupt und der ersten Zeile Exit code N aus; behandeln Sie den Rest der Zeichenfolge als Anzeigetext, nicht als stabiles Format.

• Bei Bash und PowerShell erzeugt ein Befehl, der ausgeführt und beendet wurde, eine erste Zeile Exit code N, gefolgt von der gesamten Ausgabe des Befehls als ein Block, in dem stdout und stderr verschachtelt sind
• Eine Payload kann auch eine reine Fehlermeldung ohne Exit-Code-Zeile enthalten, wenn Claude Code den Shell-Prozess selbst nicht starten konnte
• Claude Code kürzt lange Zeichenfolgen in der Mitte um eine Markierung ... [N characters truncated] ... und kann eigene Zeilen einfügen, etwa Command timed out after 2m 0s

PostToolUseFailure-Entscheidungssteuerung

PostToolUseFailure-Hooks können Claude nach einem Tool-Fehler Kontext liefern. Zusätzlich zu den JSON-Ausgabefeldern, die allen Hooks zur Verfügung stehen, 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 alle Tool-Aufrufe in einem Batch abgeschlossen sind, bevor Claude Code die nächste Anfrage an das Modell sendet. PostToolUse wird einmal pro Tool ausgelöst, was bedeutet, dass es parallel ausgelöst wird, wenn Claude parallele Tool-Aufrufe durchführt. PostToolBatch wird genau einmal mit dem vollständigen Batch ausgelöst und ist daher der richtige Ort, um Kontext einzufügen, der von der Gesamtheit der ausgeführten Tools abhängt und nicht von einem einzelnen Tool. Für dieses Ereignis gibt es keinen Matcher.

PostToolBatch-Eingabe

Zusätzlich zu den gemeinsamen 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\n2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "1\tfrom __future__ import annotations\n2\t..."
    }
  ]
}

tool_response enthält denselben Inhalt, den das Modell im entsprechenden tool_result-Block erhält. Der Wert ist eine serialisierte Zeichenfolge oder ein Content-Block-Array, genau so, wie das Tool ihn ausgegeben hat. Für Read bedeutet das Text mit vorangestellten Zeilennummern statt des rohen Dateiinhalts. Antworten können groß sein, parsen Sie daher nur die Felder, die Sie benötigen.

PostToolBatch-Entscheidungssteuerung

PostToolBatch-Hooks können Kontext für Claude einfügen. Zusätzlich zu den JSON-Ausgabefeldern, die allen Hooks zur Verfügung stehen, 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."
  }
}

Die Rückgabe von decision: "block" oder continue: false stoppt die Agentenschleife vor dem nächsten Modellaufruf. Die Blockierungsmeldung stammt aus dem JSON-Feld reason oder stopReason oder bei Exit-Code 2 aus stderr. Sie sehen sie als Warnung im Transkript, und sie bleibt in der Konversation, sodass Claude sie sieht, wenn die Konversation fortgesetzt wird.

PermissionDenied

Wird ausgeführt, wenn der Auto-Modus einen Tool-Aufruf ablehnt, auch wenn er ohne Urteil des Klassifikators ablehnt, weil eine vom Auto-Modus unabhängige Sicherheitsprüfung die Anfrage des Klassifikators selbst abgelehnt hat oder seine Antwort nicht geparst werden konnte. Dieser Hook wird nur im Auto-Modus ausgelöst: Er wird nicht ausgeführt, wenn Sie einen Berechtigungsdialog manuell ablehnen, wenn ein PreToolUse-Hook einen Aufruf blockiert oder wenn eine deny-Regel zutrifft. Verwenden Sie ihn, um Ablehnungen zu protokollieren, die Konfiguration anzupassen oder dem Modell mitzuteilen, dass es den Tool-Aufruf erneut versuchen darf.

Matcht auf den Tool-Namen, mit denselben Werten wie PreToolUse.

PermissionDenied-Eingabe

Zusätzlich zu den gemeinsamen Eingabefeldern erhalten PermissionDenied-Hooks tool_name, tool_input, tool_use_id und reason. Bei einem MCP-Tool erhalten sie außerdem das Objekt mcp_server.

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

PermissionDenied-Hooks können dem Modell mitteilen, dass es den abgelehnten Tool-Aufruf erneut versuchen darf. Geben Sie ein JSON-Objekt zurück, in dem hookSpecificOutput.retry auf true gesetzt ist:

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

Wenn retry den Wert true hat, fügt Claude Code der Konversation eine Nachricht hinzu, die dem Modell mitteilt, dass es den Tool-Aufruf erneut versuchen darf. Claude Code hebt die Ablehnung selbst nicht auf. Wenn Ihr Hook kein JSON oder retry: false zurückgibt, bleibt die Ablehnung bestehen und das Modell erhält die ursprüngliche Ablehnungsnachricht.

Claude Code ignoriert retry: true, wenn der Klassifikator kein Urteil über die Aktion gefällt hat: Seine Antwort konnte nicht geparst werden, oder eine vom Auto-Modus unabhängige Sicherheitsprüfung hat die Anfrage des Klassifikators selbst abgelehnt. Bei diesen Ablehnungen teilt Claude Code dem Modell bereits in der Ablehnungsnachricht mit, ob es später erneut versuchen oder weitermachen soll.

Notification

Wird ausgeführt, wenn Claude Code Benachrichtigungen sendet. Matcht auf den Benachrichtigungstyp. Lassen Sie den Matcher weg, um Hooks für alle Benachrichtigungstypen auszuführen.

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

Die Typen quota_auto_resume_fired, quota_auto_resume_stale und quota_auto_resume_disabled erfordern Claude Code v2.1.234 oder höher.

In Terminal-Sitzungen erfordert permission_prompt für die Netzwerkanfrage eines in einer Sandbox ausgeführten Befehls Claude Code v2.1.246 oder höher.

agent_needs_input für die Frage eines Teammitglieds zur Terminal-Einrichtung erfordert Claude Code v2.1.248 oder höher.

Claude Code steuert das Timing von permission_prompt anders in Sitzungen, in denen es Berechtigungsanfragen an den canUseTool-Callback des Agent SDK sendet. Auf diese Weise hosten Claude Desktop und die VS Code-Erweiterung Claude Code:

• Rechnen Sie mit permission_prompt etwa sechs Sekunden, nachdem Claude um Erlaubnis bittet. Claude Code verzögert es nicht, während Sie tippen.
• 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 ausgelöst.

Verwenden Sie separate Matcher, um je nach Benachrichtigungstyp unterschiedliche Handler auszuführen. Diese Konfiguration löst ein berechtigungsspezifisches Warnskript aus, wenn Claude eine 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 gemeinsamen Eingabefeldern erhalten Notification-Hooks message mit dem Benachrichtigungstext, ein optionales title und notification_type, das angibt, welcher Typ ausgelöst 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 weder blockieren noch ändern. Claude Code verwirft ihre Felder systemMessage und continue, gibt aber weiterhin terminalSequence aus, worauf das Beispiel für Desktop-Benachrichtigungen beruht. Notification-Hooks sind für Nebeneffekte gedacht, etwa die Weiterleitung der Benachrichtigung an einen externen Dienst.

SubagentStart

Wird ausgeführt, wenn Claude mit dem Agent-Tool einen Subagenten startet, wenn Claude einen Subagenten fortsetzt und jedes Mal, wenn ein In-Process-Teammitglied eines Agent-Teams eine neue Nachricht verarbeitet. Unterstützt Matcher zum Filtern nach dem Namen des Agententyps. Bei integrierten Agenten ist dies der Agentenname wie general-purpose, Explore oder Plan. Bei benutzerdefinierten Subagenten ist dies das Feld name aus dem Frontmatter des Agenten, nicht der Dateiname.

Bei Subagenten, die von einem Plugin bereitgestellt werden, ist der Agententyp der plugin-bezogene Bezeichner wie my-plugin:reviewer, nicht der reine Frontmatter-Name. Der Doppelpunkt führt dazu, dass ein plugin-bezogener Name als regulärer Ausdruck ausgewertet wird. Verankern Sie den Matcher daher für eine exakte Übereinstimmung mit ^ und $: ^my-plugin:reviewer$.

SubagentStart-Eingabe

Zusätzlich zu den gemeinsamen Eingabefeldern erhalten SubagentStart-Hooks agent_id mit dem eindeutigen Bezeichner des Subagenten und agent_type mit dem Agentennamen, auf 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 eines Subagenten nicht blockieren, aber Kontext in den Subagenten einfügen. Zusätzlich zu den JSON-Ausgabefeldern, die allen Hooks zur Verfügung stehen, können Sie Folgendes zurückgeben:

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

Wenn der Hook für denselben Subagenten erneut ausgeführt wird, fügt Claude Code den zurückgegebenen Kontext nur ein, wenn der Kontext des Subagenten die Kopie aus einem früheren Durchlauf noch nicht enthält. Die beim Start eingefügte Kopie bleibt bestehen, sodass der Prompt-Cache des Subagenten intakt bleibt. Nachdem die automatische Komprimierung diese Kopie verworfen hat, fügt Claude Code den Kontext des nächsten Durchlaufs erneut ein.

SubagentStop

Wird ausgeführt, wenn ein Claude Code-Subagent seine Antwort beendet hat. Matcht auf den Agententyp, mit denselben Werten wie SubagentStart.

SubagentStop-Eingabe

Zusätzlich zu den gemeinsamen Eingabefeldern erhalten SubagentStop-Hooks stop_hook_active, agent_id, agent_type, agent_transcript_path und last_assistant_message. Das Feld agent_type ist der Wert, der für die Matcher-Filterung verwendet wird. transcript_path ist das Transkript der Hauptsitzung, während agent_transcript_path das eigene Transkript des Subagenten ist, das in einem verschachtelten Ordner subagents/ gespeichert wird. Das Feld last_assistant_message enthält den Textinhalt der letzten Antwort des Subagenten, sodass Hooks darauf zugreifen können, ohne die Transkriptdatei zu parsen.

Nicht jedes SubagentStop-Ereignis stammt von einem Subagenten, den Claude gestartet hat. Claude Code führt für einige seiner eigenen Funktionen auch interne Agenten aus, etwa für Prompt-Vorschläge und /btw-Nebenfragen, und SubagentStop wird auch ausgelöst, wenn einer davon beendet wird. Bei diesen Ereignissen ist agent_type der Agentenname, unter dem die Sitzung selbst läuft, etwa einer, der mit --agent oder der Einstellung agent festgelegt wurde, und eine leere Zeichenfolge, wenn die Sitzung ohne einen solchen läuft.

Ein matcher, der Agententypen benennt, matcht keinen leeren agent_type. Ein Hook, dessen Matcher weggelassen, "" oder "*" ist oder ein regulärer Ausdruck ist, der eine leere Zeichenfolge matcht, wird auch für Ereignisse mit leerem agent_type ausgeführt.

Ab Claude Code v2.1.271 übermittelt ein Subagent, der mit dem Tool SubagentHandback läuft, seinen Bericht über dieses Tool, bevor er stoppt. Das Feld last_assistant_message enthält dann den abschließenden Text des Subagenten, falls vorhanden, der nicht der übermittelte Bericht ist. Der Bericht ist die message-Eingabe dieses Aufrufs, die ein PreToolUse- oder PostToolUse-Hook mit dem Matcher SubagentHandback als tool_input.message erhält.

SubagentStop-Hooks erhalten außerdem die Arrays background_tasks und session_crons, die unter Stop-Eingabe beschrieben sind. Beide Arrays beziehen sich auf die übergeordnete Sitzung, nicht auf 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 dasselbe Format zur Entscheidungssteuerung wie Stop-Hooks, einschließlich hookSpecificOutput.additionalContext mit hookEventName auf "SubagentStop" gesetzt, für Feedback ohne Fehlercharakter, das den Subagenten weiterlaufen lässt. Die Rückgabe von decision: "block" mit einem reason lässt den Subagenten weiterlaufen und übermittelt reason an den Subagenten als seine nächste Anweisung. Ein Hook, der durch Exit-Code 2 blockiert, übermittelt seine stderr-Meldung auf dieselbe Weise. Um Kontext in die übergeordnete Sitzung einzufügen, nachdem ein Subagent zurückgekehrt ist, verwenden Sie stattdessen einen PostToolUse-Hook für das Agent-Tool.

TaskCreated

Wird ausgeführt, wenn eine Aufgabe über das Tool TaskCreate erstellt wird. Verwenden Sie dies, um Namenskonventionen durchzusetzen, Aufgabenbeschreibungen zu verlangen oder die Erstellung bestimmter Aufgaben zu verhindern. In einer Sitzung ohne die Task-Tools wird dieses Ereignis nicht ausgelöst.

TaskCreated-Hooks unterstützen keine Matcher und werden bei jedem Vorkommen ausgelöst.

TaskCreated-Eingabe

Zusätzlich zu den gemeinsamen 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-Entscheidungssteuerung

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

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

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

#!/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 ausgelöst: wenn ein beliebiger Agent eine Aufgabe über das Tool TaskUpdate ausdrücklich als abgeschlossen markiert oder wenn ein Teammitglied eines Agent-Teams seinen Turn mit laufenden Aufgaben beendet. Verwenden Sie dies, um Abschlusskriterien wie bestandene Tests oder Lint-Prüfungen durchzusetzen, bevor eine Aufgabe geschlossen werden kann.

TaskCompleted-Hooks unterstützen keine Matcher und werden bei jedem Vorkommen ausgelöst.

TaskCompleted-Eingabe

Zusätzlich zu den gemeinsamen 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-Entscheidungssteuerung

TaskCompleted-Hooks unterstützen zwei Möglichkeiten, den Aufgabenabschluss zu steuern:

• Exit-Code 2: Die Aufgabe wird nicht als abgeschlossen markiert, und die stderr-Meldung wird dem Modell als Feedback zurückgegeben.
• JSON {"continue": false, "stopReason": "..."}: Wenn ein Teammitglied, das seinen Turn beendet, das Ereignis ausgelöst hat, wird das Teammitglied vollständig gestoppt, entsprechend dem Verhalten des Stop-Hooks. Der stopReason wird dem Benutzer angezeigt. Wenn das Tool TaskUpdate das Ereignis ausgelöst hat, ignoriert Claude Code continue: false; Exit-Code 2 blockiert den Abschluss weiterhin.

Dieses Beispiel führt Tests aus und blockiert den Aufgabenabschluss, 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-Agent von Claude Code seine Antwort beendet hat. Wird nicht ausgeführt, wenn das Stoppen durch eine Unterbrechung des Benutzers verursacht wurde. API-Fehler lösen stattdessen StopFailure aus.

Stop-Eingabe

Zusätzlich zu den gemeinsamen Eingabefeldern erhalten Stop-Hooks stop_hook_active, last_assistant_message, background_tasks und session_crons. Das Feld stop_hook_active ist true, wenn Claude Code bereits aufgrund eines Stop-Hooks weiterarbeitet. Prüfen Sie diesen Wert oder verarbeiten Sie das Transkript, um zu vermeiden, dass auf eine Bedingung blockiert wird, die sich nie auflöst. Claude Code wendet eine Obergrenze von 8 aufeinanderfolgenden Fortsetzungen an: Nachdem Stop-Hooks den Turn achtmal in Folge fortgesetzt haben, überschreibt Claude Code die nächste Blockierung und beendet den Turn. Um die Obergrenze anzuheben, setzen Sie CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

Das Feld last_assistant_message enthält den Textinhalt von Claudes letzter Antwort, sodass Hooks darauf zugreifen können, ohne die Transkriptdatei zu parsen. Für Hooks, die auf den gerade abgeschlossenen Turn reagieren, etwa Vorlese- oder Benachrichtigungs-Hooks, verwenden Sie dieses Feld, anstatt transcript_path zu lesen: Es ist nicht in allen Versionen garantiert, dass die Transkriptdatei zum Stop-Zeitpunkt die letzte Nachricht enthält.

Mit den Arrays background_tasks und session_crons können Hooks unterscheiden zwischen „Sitzung ist beendet" und „Sitzung ist pausiert und wartet darauf, dass Hintergrundarbeit sie wieder aufweckt". Beide Arrays sind vorhanden, wenn die Aufgabenregistrierung erreichbar ist, und leer, wenn nichts läuft oder geplant ist.

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

Jeder Eintrag in session_crons beschreibt ein sitzungsbezogenes geplantes Aufwecken, das aus CronCreate, ScheduleWakeup und /loop stammt:

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

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

Stop- und SubagentStop-Hooks können steuern, ob Claude fortfährt. Zusätzlich zu den JSON-Ausgabefeldern, die allen Hooks zur Verfügung stehen, kann Ihr Hook-Skript diese ereignisspezifischen Felder zurückgeben:

Ein Hook, der durch Exit-Code 2 blockiert, wird genauso weitergeleitet wie reason: Claude erhält die stderr-Meldung als Erklärung, warum es fortfahren soll.

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

Verwenden Sie additionalContext, wenn der Hook wie vorgesehen funktioniert und Claude Orientierung gibt, etwa „führe die Testsuite vor dem Abschluss aus". Es hält die Konversation über dieselben Schleifenschutzmechanismen wie decision: "block" am Laufen, nämlich die Eingabe stop_hook_active und die Obergrenze von 8 aufeinanderfolgenden Fortsetzungen, aber das Transkript kennzeichnet es als Stop hook feedback, und es wird keine Hook-Fehlerbenachrichtigung angezeigt:

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

StopFailure

Wird anstelle von Stop ausgeführt, wenn der Turn 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 eine Antwort aufgrund von Rate-Limits, Authentifizierungsproblemen oder anderen API-Fehlern nicht abschließen kann.

StopFailure-Eingabe

Zusätzlich zu den gemeinsamen Eingabefeldern erhalten StopFailure-Hooks error, optional error_details und optional last_assistant_message. Das Feld error gibt den Fehlertyp an und wird für die Matcher-Filterung 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 Entscheidungssteuerung. Sie dienen ausschließlich Benachrichtigungs- und Protokollierungszwecken.

TeammateIdle

Wird ausgeführt, wenn ein Teammitglied eines Agent-Teams nach dem Beenden seines Turns kurz davor ist, untätig zu werden. Verwenden Sie dies, um Qualitätsschranken durchzusetzen, bevor ein Teammitglied die Arbeit einstellt, etwa durch das Verlangen bestandener Lint-Prüfungen oder die Überprüfung, ob Ausgabedateien existieren.

TeammateIdle-Hooks unterstützen keine Matcher und werden bei jedem Vorkommen ausgelöst.

TeammateIdle-Eingabe

Zusätzlich zu den gemeinsamen 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-Entscheidungssteuerung

TeammateIdle-Hooks unterstützen zwei Möglichkeiten, das Verhalten von Teammitgliedern zu steuern:

• Exit-Code 2: Das Teammitglied erhält die stderr-Meldung als Feedback und arbeitet weiter, anstatt untätig zu werden.
• JSON {"continue": false, "stopReason": "..."}: Stoppt das Teammitglied vollständig, entsprechend dem Verhalten des Stop-Hooks. Der stopReason wird dem Benutzer angezeigt.

Dieses Beispiel prüft, ob ein Build-Artefakt existiert, bevor ein Teammitglied untätig werden darf:

#!/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 während einer Sitzung eine Konfigurationsdatei ändert. Verwenden Sie dies, um Einstellungsänderungen zu prüfen, Sicherheitsrichtlinien durchzusetzen oder nicht autorisierte Änderungen an Konfigurationsdateien zu blockieren.

Claude Code führt ConfigChange-Hooks aus, wenn sich eine Einstellungsdatei, eine Datei mit verwalteten Richtlinien oder eine Skill-Datei ändert. Bei verwalteten Richtlinien führt es sie nur aus, wenn sich managed-settings.json oder eine Datei in managed-settings.d/ ändert. Serververwaltete Einstellungen sowie Änderungen an verwalteten macOS-Einstellungen oder Windows-Registrierungsrichtlinien wendet es an, ohne die Hooks auszuführen. Unter WSL mit wslInheritsWindowsSettings wendet es bei seiner Richtlinienabfrage auch eine geänderte Windows-seitige Datei mit verwalteten Einstellungen an, ohne die Hooks auszuführen.

Der Matcher filtert nach der Konfigurationsquelle:

Dieses Beispiel protokolliert alle Konfigurationsänderungen für Sicherheitsaudits:

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

ConfigChange-Eingabe

Zusätzlich zu den gemeinsamen Eingabefeldern erhalten ConfigChange-Hooks source und optional file_path. Das Feld source gibt an, welcher Konfigurationstyp sich geändert hat, und file_path liefert den Pfad zur konkret geänderten Datei.

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

ConfigChange-Hooks können verhindern, dass Konfigurationsänderungen wirksam werden. Verwenden Sie Exit-Code 2 oder ein JSON-decision, um die Änderung zu verhindern. Bei einer Blockierung werden die neuen Einstellungen nicht auf die laufende Sitzung angewendet.

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

Änderungen an policy_settings können nicht blockiert werden. Hooks werden für policy_settings-Quellen weiterhin ausgelöst, wenn sich eine Datei mit verwalteten Einstellungen auf dem Rechner ändert, sodass Sie sie zum Protokollieren dieser Änderungen verwenden können, aber jede Blockierungsentscheidung wird ignoriert. Dadurch wird sichergestellt, dass unternehmensweit verwaltete Einstellungen immer wirksam werden. Claude Code führt keine ConfigChange-Hooks aus, wenn serververwaltete Einstellungen eintreffen oder aktualisiert werden.

Claude Code berücksichtigt die Blockierungsentscheidung aus der JSON-Ausgabe eines ConfigChange-Hooks und verwirft systemMessage und continue. Eine blockierte Änderung zeigt weder Ihnen noch Claude eine Nachricht an, unabhängig davon, ob Sie mit reason oder mit stderr bei Exit-Code 2 blockieren. Claude Code schreibt lediglich eine Zeile in das Debug-Log.

CwdChanged

Wird ausgeführt, wenn ein Shell-Befehl in der Hauptkonversation das Arbeitsverzeichnis ändert, beispielsweise wenn Claude einen cd-Befehl ausführt. Verwenden Sie dies, um auf Verzeichniswechsel zu reagieren: Umgebungsvariablen neu laden, projektspezifische Toolchains aktivieren oder Einrichtungsskripte automatisch ausführen. Lässt sich mit FileChanged kombinieren für Tools wie direnv, die verzeichnisspezifische Umgebungen verwalten.

CwdChanged-Hooks haben Zugriff auf CLAUDE_ENV_FILE. In diese Datei geschriebene Variablen bleiben für nachfolgende Bash-Befehle bis zum nächsten CwdChanged-Ereignis erhalten, bei dem Claude Code sie löscht.

CwdChanged unterstützt keine Matcher und wird bei jedem Vorkommen ausgelöst.

CwdChanged-Eingabe

Zusätzlich zu den gemeinsamen 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 allen Hooks zur Verfügung stehen, können CwdChanged-Hooks watchPaths zurückgeben, um dynamisch festzulegen, welche Dateipfade FileChanged überwacht:

CwdChanged-Hooks haben keine Entscheidungssteuerung. 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 an. Die Nachricht erreicht den SDK-Nachrichtenstrom nicht.

DirectoryAdded

Wird ausgeführt, nachdem Sie während einer Sitzung mit dem Befehl /add-dir ein Arbeitsverzeichnis hinzugefügt haben oder nachdem ein SDK-Client eines mit der Steuerungsanfrage register_repo_root hinzugefügt hat. Verwenden Sie dies, um ein neu hinzugefügtes Repository vorzubereiten, beispielsweise durch Installieren seiner Abhängigkeiten.

Claude Code löst dieses Ereignis nicht aus, wenn:

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

Claude Code löst DirectoryAdded aus, nachdem der Sandbox- und Berechtigungsstatus aktualisiert wurde, sodass in einer Sandbox ausgeführte Tools das neue Verzeichnis bereits sehen, wenn Ihr Hook ausgeführt wird. Hook-Befehle selbst werden außerhalb der Sandbox ausgeführt.

Claude Code wartet nicht auf den Hook: Das Hinzufügen wird sofort abgeschlossen, und der Hook läuft im Hintergrund mit dem Standard-Timeout von 600 Sekunden.

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

DirectoryAdded-Eingabe

Zusätzlich zu den gemeinsamen 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 Entscheidungssteuerung. Sie können das Hinzufügen nicht blockieren, da es bereits abgeschlossen ist, wenn der Hook ausgeführt wird. Claude Code verwirft das Feld continue aus ihrer JSON-Ausgabe und behandelt den Rest je nach Quelle unterschiedlich:

• slash_command: Claude Code übermittelt die systemMessage des Hooks im nächsten Konversations-Turn als Kontext an Claude, anstatt sie Ihnen anzuzeigen. Die Anzahl fehlgeschlagener Hooks erscheint im Transkript. Die vollständige Fehlerausgabe geht in das Debug-Log
• register_repo_root: Claude Code schreibt die systemMessage-Ausgabe und die Fehlerausgabe nur in das Debug-Log

FileChanged

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

Der matcher für dieses Ereignis erfüllt zwei Aufgaben:

• Überwachungsliste aufbauen: Der Wert wird an | aufgeteilt, und jedes Segment wird als literaler Dateiname im Arbeitsverzeichnis registriert, sodass ".envrc|.env" genau diese beiden Dateien überwacht. Regex-Muster sind hier nicht sinnvoll: Ein Wert wie ^\.env würde eine Datei überwachen, die buchstäblich ^\.env heißt.
• Filtern, welche Hooks ausgeführt werden: Wenn sich eine überwachte Datei ändert, filtert derselbe Wert anhand der Standard-Matcher-Regeln gegen den Basisnamen der geänderten Datei, welche Hook-Gruppen ausgeführt werden.

Dieses Beispiel normalisiert die Zeilenenden in data.csv nach jeder Änderung, auch wenn ein Bash-Befehl oder ein externes Skript die Datei neu schreibt:

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

Der Hook liest den absoluten Pfad der geänderten Datei aus dem Feld file_path der JSON-Eingabe auf stdin. Seine grep-Prüfung testet auf dasselbe, was perl entfernt, nämlich ein CR am Zeilenende, sodass der Durchlauf nach einer Normalisierung beendet wird, ohne die Datei anzurühren. Eine lockerere Prüfung führt zu einer Endlosschleife, weil perl -i die Datei auch dann neu schreibt, wenn es nichts ersetzt, und Claude Code den Hook nach jedem Neuschreiben 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, mit einem Bash-Befehl eine CRLF-Zeile an data.csv anzuhängen. Claude Code führt den Hook aus, und die Datei hat anschließend LF-Zeilenenden.

Um Dateien zu überwachen, die Sie nicht im Voraus benennen können, geben Sie aus einem Hook watchPaths zurück, um die Überwachungsliste dynamisch zu aktualisieren. Claude Code startet den Watcher nur, wenn etwas eine zu überwachende Datei benennt. Befüllen Sie die Liste daher mit einer FileChanged-Gruppe, deren Matcher mindestens eine Datei benennt, oder mit einem SessionStart- oder CwdChanged-Hook, der watchPaths zurückgibt. Der Matcher filtert weiterhin, welche Hook-Gruppen ausgeführt werden, wenn sich eine überwachte Datei ändert. Lassen Sie daher bei der Gruppe, die dynamische Pfade verarbeitet, den Matcher weg; ein weggelassener Matcher matcht jede überwachte Datei und fügt der Überwachungsliste nichts hinzu. Ein "*"-Matcher matcht ebenfalls jede Datei, aber Claude Code registriert ihn wie jeden anderen Wert in der Überwachungsliste, als literale Datei namens *.

FileChanged-Hooks haben Zugriff auf CLAUDE_ENV_FILE. In diese Datei geschriebene Variablen bleiben für nachfolgende Bash-Befehle bis zum nächsten CwdChanged-Ereignis erhalten, bei dem Claude Code sie löscht.

FileChanged-Eingabe

Zusätzlich zu den gemeinsamen 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 allen Hooks zur Verfügung stehen, können FileChanged-Hooks watchPaths zurückgeben, um dynamisch zu aktualisieren, welche Dateipfade überwacht werden:

FileChanged-Hooks haben keine Entscheidungssteuerung. Sie können die Dateiänderung nicht verhindern.

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

WorktreeCreate

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

Da der Hook das Standardverhalten 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 dazu, wie jeder Hook-Typ den Pfad zurückgibt.

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

Dieses Beispiel erstellt eine SVN-Arbeitskopie und gibt den Pfad aus, den Claude Code verwenden soll. 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 auf stdin, checkt eine neue Kopie in ein neues Verzeichnis aus und gibt den Verzeichnispfad aus. Das echo in der letzten Zeile ist das, was Claude Code als Worktree-Pfad liest. Leiten Sie jede andere Ausgabe nach stderr um, damit sie den Pfad nicht beeinträchtigt.

WorktreeCreate-Eingabe

Zusätzlich zu den gemeinsamen Eingabefeldern erhalten WorktreeCreate-Hooks das Feld name. Dies ist ein Slug-Bezeichner für den neuen Worktree, entweder vom Benutzer angegeben oder automatisch generiert, zum Beispiel 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 übliche Entscheidungsmodell aus Zulassen und Blockieren. Stattdessen bestimmt der Erfolg oder Misserfolg des Hooks das Ergebnis. Der Hook muss den Pfad zum erstellten Worktree-Verzeichnis zurückgeben:

• Befehls-Hooks (type: "command"): Geben Sie den Pfad als letzte nicht leere Zeile auf stdout aus. Claude Code entfernt ANSI-Escape-Codes, bevor es diese Zeile liest, sodass Shell-Startbanner, die vor Ihrem echo ausgegeben werden, ignoriert werden. Leiten Sie jede andere Ausgabe des Hooks nach stderr um.
• HTTP-Hooks (type: "http"): Geben Sie { "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } } im Response-Body zurück.

Wenn der Hook fehlschlägt oder keinen Pfad liefert, schlägt die Erstellung des Worktrees mit einem Fehler fehl.

Claude Code löst einen relativen Pfad relativ zu dem Verzeichnis auf, in dem der Hook ausgeführt wurde, und löst dabei alle .- oder ..-Segmente auf. Wenn der resultierende Pfad kein Verzeichnis ist, das Claude Code betreten kann, gibt die Sitzung einen Fehler mit dem Pfad aus und wird mit Exit-Code 1 beendet.

Claude Code lehnt einen absoluten Pfad ab, der .- oder ..-Segmente enthält, sowie jeden Pfad, der unterhalb des Repository-Stammverzeichnisses durch einen Symlink führt, da ein im Repository committeter Symlink den Worktree aus dem Repository heraus umleiten könnte. Die Fehlermeldung nennt die abgelehnte Komponente. Geben Sie einen normalisierten Pfad zurück, der nicht durch einen Symlink innerhalb des Repositorys führt. Vor v2.1.216 folgte die Worktree-Erstellung dem Pfad des Hooks ohne diese Prüfung.

WorktreeRemove

Wird ausgeführt, wenn ein Worktree entfernt wird. Dies ist das Gegenstück zu WorktreeCreate für die Bereinigung. Das Ereignis wird ausgelöst, wenn:

• Sie eine --worktree-Sitzung beenden und sich für das Entfernen entscheiden
• ein Subagent mit isolation: "worktree" fertig ist
• Sie eine Hintergrundsitzung löschen, deren Worktree der Hook erstellt hat

Bei Git-basierten Worktrees übernimmt Claude Code die Bereinigung automatisch mit git worktree remove. Wenn Sie einen WorktreeCreate-Hook konfiguriert haben, kombinieren Sie ihn mit einem WorktreeRemove-Hook, um die Bereinigung der von ihm erstellten Worktrees zu steuern:

• Kein WorktreeRemove-Hook: Wenn Sie eine --worktree-Sitzung beenden und das Entfernen wählen, greift Claude Code ersatzweise auf git worktree remove --force für den Pfad zurück, den Ihr WorktreeCreate-Hook zurückgegeben hat, sodass ein Worktree, den Git erkennt, entfernt wird. Ein Worktree, den Git nicht erkennt, etwa einer, den Ihr Hook mit einem anderen Versionskontrollsystem als Git erstellt hat, bleibt auf der Festplatte. Was beim Löschen einer Hintergrundsitzung mit einem vom Hook erstellten Worktree geschieht, erfahren Sie in den Löschregeln der Agentenansicht.
• Hook endet mit 0: Der Worktree gilt als entfernt. Claude Code liest nichts weiter vom Hook, stellen Sie also sicher, dass Ihr Hook das Verzeichnis gelöscht hat.
• Hook endet mit einem Wert ungleich 0: Das Entfernen schlägt fehl, wenn das Verzeichnis unter worktree_path danach noch existiert, und der Worktree bleibt ohne Git-Fallback auf der Festplatte. Ein Hook, der das Verzeichnis gelöscht hat, bevor er mit einem Wert ungleich 0 endet, gilt als entfernt. Wie der Fehler gemeldet wird, erfahren Sie unter WorktreeRemove-Eingabe.

Claude Code löscht niemals einen Branch, der zu einem vom Hook erstellten Worktree gehört, da es nur den Pfad kennt, den Ihr WorktreeCreate-Hook zurückgegeben hat. Wenn Ihr WorktreeCreate-Hook einen Branch erstellt, löschen Sie ihn in Ihrem WorktreeRemove-Hook.

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

Beim Löschen einer Hintergrundsitzung überprüft Claude Code den gespeicherten Worktree-Pfad, bevor der Hook ausgeführt wird, und lehnt einen Pfad ab, der ein Symlink ist oder unterhalb des Repository-Stammverzeichnisses durch einen Symlink führt. Für einen Worktree, der noch Dateien enthält, wird der Hook nur ausgeführt, wenn Sie das Löschen in der Agentenansicht bestätigen; für einen solchen Worktree behält claude rm stattdessen die Sitzung und den Worktree bei. Vor v2.1.216 wurde der Hook ohne diese Prüfungen für den gespeicherten Pfad 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 gemeinsamen Eingabefeldern erhalten WorktreeRemove-Hooks das Feld worktree_path, das den absoluten Pfad zum zu entfernenden Worktree enthält.

{
  "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 bestimmt das Ergebnis. Wenn ein Hook mit einem Wert ungleich 0 endet und das Verzeichnis unter worktree_path danach noch existiert, schlägt das Entfernen fehl:

• Der Worktree bleibt auf der Festplatte, und der Befehl sowie stderr des Hooks werden in das Debug-Log geschrieben.
• Wenn Sie eine Hintergrundsitzung gelöscht haben, bleibt auch die Sitzung bestehen. Die Ablehnungsmeldung in der Agentenansicht gibt an, wie der Hook beendet wurde, etwa exited 1, zitiert den Anfang seiner stderr-Ausgabe und gibt an, ob ein erneutes Löschen der Sitzung das Verzeichnis trotzdem entfernt.

PreCompact

Wird ausgeführt, bevor Claude Code einen Komprimierungsvorgang startet.

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

Beenden Sie mit Exit-Code 2, um die Komprimierung zu blockieren. Bei einem manuellen /compact wird die stderr-Meldung dem Benutzer angezeigt. Sie können auch blockieren, indem Sie JSON mit "decision": "block" zurückgeben.

Das Blockieren der automatischen Komprimierung hat je nach Zeitpunkt unterschiedliche Auswirkungen. Wurde die Komprimierung vorsorglich vor dem Kontextlimit ausgelöst, überspringt Claude Code sie, und die Konversation wird unkomprimiert fortgesetzt. Wurde die Komprimierung ausgelöst, um sich von einem bereits von der API zurückgegebenen Kontextlimit-Fehler zu erholen, tritt der zugrunde liegende Fehler zutage, und die aktuelle Anfrage schlägt fehl.

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

PreCompact-Eingabe

Zusätzlich zu den gemeinsamen Eingabefeldern erhalten PreCompact-Hooks trigger und custom_instructions. Bei manual enthält custom_instructions das, was der Benutzer an /compact übergibt, und ist null, wenn nichts übergeben wird. Bei 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, etwa um die generierte Zusammenfassung zu protokollieren oder externen Zustand zu aktualisieren. Claude Code verwirft die Felder systemMessage und continue eines PostCompact-Hooks.

Es gelten dieselben Matcher-Werte wie für PreCompact:

PostCompact-Eingabe

Zusätzlich zu den gemeinsamen Eingabefeldern erhalten PostCompact-Hooks trigger und compact_summary. Das Feld compact_summary enthält die vom Komprimierungsvorgang generierte Zusammenfassung der Konversation.

{
  "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 Entscheidungssteuerung. Sie können das Ergebnis der Komprimierung nicht beeinflussen, aber Folgeaufgaben ausführen.

PreModelSwitch

Wird ausgeführt, bevor Claude Code einen Modellwechsel anwendet, den Sie oder ein Client angefordert haben. Verwenden Sie es, um einen Wechsel zu blockieren, eine Bestätigung zu verlangen oder anzuzeigen, was der Wechsel kosten wird, bevor er erfolgt.

PreModelSwitch erfordert Claude Code v2.1.251 oder höher. Claude Code führt es für diese Anfragen aus:

• /model <name> und die /model-Auswahl
• Die Modellauswahl über Option+P oder Alt+P
• Die Einstellung „Model“ in /config
• Das Einschalten des Fast-Modus, wenn dadurch das Modell der Sitzung geändert wird
• Eine set_model-Anfrage oder eine Modelländerung in einer apply_flag_settings-Anfrage von einem Agent SDK-Host oder über Remote Control

Claude Code führt PreModelSwitch-Hooks nicht für Wechsel aus, die es selbst vornimmt, etwa einen automatischen Modell-Fallback oder das Wiederherstellen des Modells beim Fortsetzen einer Sitzung. Diese Änderungen erreichen nur PostModelSwitch.

Claude Code vergleicht den Matcher mit dem kanonischen Namen des Modells, zu dem die Sitzung wechselt, und ignoriert dabei ein etwaiges [1m]-Suffix. Ein Alias wie opus, eine datierte Modell-ID und eine anbieterspezifische ID wie eine Amazon-Bedrock-Modell-ID stimmen alle mit dem einen kanonischen Namen überein, in den sie aufgelöst werden, sodass claude-opus-5 jede Schreibweise von Opus 5 abdeckt.

Wenn Claude Code keinen kanonischen Namen für das Ziel ermitteln kann, etwa bei einer benutzerdefinierten Modell-ID, die nur Ihr LLM-Gateway kennt, führt es jeden PreModelSwitch-Hook unabhängig vom Matcher aus. Ein blockierender Hook sollte daher to_model aus seiner Eingabe prüfen, statt sich allein auf den Matcher zu verlassen.

Schreiben Sie den Matcher als exakten Namen, als durch | getrennte Liste wie claude-opus-4-6|claude-opus-5 oder als regulären Ausdruck wie .*opus.*. Dieses Beispiel verwendet einen Matcher mit exaktem Namen und prüft zusätzlich to_model aus der Hook-Eingabe, sodass es einen Wechsel zu Opus 4.6 durch Beenden mit Exit-Code 2 ablehnt und jedes andere Ziel durchlässt:

{
"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 prüfen, ob der Hook funktioniert, führen Sie /model claude-opus-4-6 in einer Sitzung aus, die ein anderes Modell verwendet. Claude Code behält das aktuelle Modell bei und meldet, dass ein PreModelSwitch-Hook den Wechsel blockiert hat, mit Ihrer Meldung als Grund.

PreModelSwitch-Eingabe

Zusätzlich zu den gemeinsamen Eingabefeldern erhalten PreModelSwitch-Hooks die Felder in dieser Tabelle. Die letzten fünf beschreiben, was das erneute Senden der Konversation an das neue Modell kostet, sodass ein Hook diesen Wert vor dem Wechsel anzeigen kann.

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

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

PreModelSwitch-Hooks können den Wechsel abbrechen, den Benutzer um Bestätigung bitten oder ihn fortfahren lassen. Exit-Code 2 oder ein decision: "block" auf oberster Ebene bricht den Wechsel ab.

Für eine feinere Steuerung geben Sie permissionDecision und permissionDecisionReason in einem hookSpecificOutput-Objekt zurück, wie bei PreToolUse. PreModelSwitch akzeptiert "allow", "deny" und "ask". Es akzeptiert weder "defer" noch updatedInput oder additionalContext. Die folgende Tabelle beschreibt beide Felder:

Nur /model in einer interaktiven Sitzung kann die "ask"-Abfrage anzeigen. Auf allen anderen Oberflächen, einschließlich des nicht interaktiven Modus mit dem Flag -p, /config und set_model-Anfragen, behandelt Claude Code "ask" als Ablehnung.

Dieses Beispiel bittet den Benutzer um Bestätigung und nennt 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, gilt die Rangfolge deny > ask > allow.

Claude Code zeigt dem Benutzer jede systemMessage an, die Ihr Hook zurückgibt, unabhängig von der Entscheidung, sodass ein Hook zur Kostenanzeige {"systemMessage": "..."} zurückgeben und mit 0 enden kann.

Ein PreModelSwitch-Hook, der nicht vor Ablauf seines Timeouts antwortet, blockiert den Wechsel. Bei PreToolUse hingegen lässt ein Befehls-Hook mit Zeitüberschreitung den Tool-Aufruf fortfahren. Der Standard-Timeout für dieses Ereignis beträgt 30 Sekunden. PreModelSwitch führt nur command-, http- und mcp_tool-Hooks aus, daher gelten die Standardwerte für prompt und agent nicht.

Ein Hook, der mit einem anderen Code als 0 oder 2 endet und keine JSON-Entscheidung ausgibt, blockiert nicht: Claude Code zeigt seine stderr-Ausgabe an 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 modellspezifische Hinweise zu geben, ohne jede CLAUDE.md zu bearbeiten, etwa eine organisationsweite Anweisung, die für bestimmte Modelle gilt.

PostModelSwitch erfordert Claude Code v2.1.251 oder höher. 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 automatischer Modell-Fallback, der 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-Modellkette einen Turn bedient, da diese Ersetzung nur einen Turn dauert und das Modell der Sitzung unverändert lässt.

Der Matcher folgt denselben Regeln wie bei PreModelSwitch: Claude Code vergleicht ihn mit dem kanonischen Namen des Modells, zu dem die Sitzung gewechselt ist.

Dieses Beispiel fügt Hinweise hinzu, sobald das Modell der Sitzung zu einem beliebigen Opus-Modell wechselt:

{
  "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 prüfen, ob der Hook funktioniert, wechseln Sie in einer Sitzung mit einem anderen Modell zu einem Opus-Modell, führen Sie beispielsweise /model opus in einer Sonnet-Sitzung aus, und fragen Sie Claude dann, welche Hinweise es zum aktuellen Modell hat.

PostModelSwitch-Eingabe

PostModelSwitch-Hooks erhalten dieselben Felder wie PreModelSwitch, wobei hook_event_name auf "PostModelSwitch" gesetzt ist und es zwei weitere source-Werte gibt: "auto" für einen automatischen Fallback oder eine andere Änderung, die Claude Code selbst vorgenommen hat, und "resume" für das Modell, das beim Fortsetzen einer Sitzung wiederhergestellt wurde.

requested_model ist null, wenn source den Wert "auto" hat. Wenn source den Wert "resume" hat, ist es die gespeicherte Modelleinstellung, die Claude Code wiederhergestellt hat.

PostModelSwitch-Entscheidungssteuerung

Claude Code übernimmt die Klartext-Ausgabe auf stdout Ihres Hooks bei Exit-Code 0 oder additionalContext aus der JSON-Ausgabe und übermittelt sie Claude mit der nächsten Anfrage nach dem Wechsel. Zusätzlich zu den JSON-Ausgabefeldern, die allen Hooks zur Verfügung stehen, können Sie Folgendes zurückgeben:

Wenn der Hook nicht innerhalb von fünf Sekunden nach dem Senden des nächsten Prompts fertig ist, sendet Claude Code diese Anfrage ohne die Ausgabe und hängt sie stattdessen an die darauffolgende Anfrage an. Wenn sich das Modell vor der nächsten Anfrage mehrmals ändert, übermittelt Claude Code nur die Ausgabe für das Zielmodell des letzten Wechsels.

SessionEnd

Wird ausgeführt, wenn eine Claude-Code-Sitzung endet. Nützlich für Bereinigungsaufgaben, das Protokollieren von Sitzungsstatistiken oder das Speichern des Sitzungszustands. Unterstützt Matcher, um nach dem Beendigungsgrund zu filtern.

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

SessionEnd-Eingabe

Zusätzlich zu den gemeinsamen Eingabefeldern erhalten SessionEnd-Hooks ein Feld reason, das angibt, warum die Sitzung beendet wurde. Alle Werte finden Sie in der Tabelle der Gründe oben.

{
  "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 Entscheidungssteuerung. Sie können das Beenden der Sitzung nicht blockieren, aber Bereinigungsaufgaben ausführen. Claude Code verwirft ihre JSON-Ausgabefelder, etwa systemMessage.

SessionEnd-Hooks haben einen Standard-Timeout von 1,5 Sekunden. Er gilt, wenn Sie beenden, /clear ausführen oder mit dem interaktiven /resume die Sitzung wechseln. Sie können einem Hook auf zwei Arten mehr Zeit geben:

• timeout pro Hook: Setzen Sie timeout in der Konfiguration des jeweiligen Hooks. Das Gesamtbudget steigt automatisch auf den höchsten timeout-Wert pro Hook in Ihren Einstellungsdateien, bis zu 60 Sekunden. Wenn Sie das Budget auf diese Weise erhöhen, behält ein Hook ohne eigenen timeout weiterhin den Standardwert. Timeouts, die für von Plugins bereitgestellte Hooks festgelegt 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 von Ihnen festgelegte Wert wird außerdem zum Timeout für jeden Hook ohne eigenen 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 Gesamtbudget, und ein Hook ohne eigenen timeout wurde weiterhin nach 1,5 Sekunden abgebrochen.

Elicitation

Wird ausgeführt, wenn ein MCP-Server während einer Aufgabe Benutzereingaben anfordert. Standardmäßig zeigt Claude Code einen interaktiven Dialog an, in dem der Benutzer antworten kann. Hooks können diese Anfrage abfangen und programmatisch beantworten, wodurch der Dialog vollständig übersprungen wird.

Das Matcher-Feld wird mit dem Namen des MCP-Servers abgeglichen.

Elicitation-Eingabe

Zusätzlich zu den gemeinsamen Eingabefeldern erhalten Elicitation-Hooks die Felder mcp_server_name und message sowie die optionalen Felder mode, url, elicitation_id und requested_schema.

Für eine Elicitation im Formularmodus, den häufigsten 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 eine Elicitation im URL-Modus, die für browserbasierte Authentifizierung verwendet wird:

{
  "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 zu antworten, ohne den Dialog anzuzeigen, geben Sie ein JSON-Objekt mit hookSpecificOutput zurück:

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

Exit-Code 2 lehnt die Elicitation ab. Claude Code zeigt Ihre stderr-Meldung nirgends an.

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

ElicitationResult

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

Das Matcher-Feld wird mit dem Namen des MCP-Servers abgeglichen.

ElicitationResult-Eingabe

Zusätzlich zu den gemeinsamen Eingabefeldern erhalten ElicitationResult-Hooks die Felder mcp_server_name und action sowie die optionalen Felder mode, elicitation_id und content.

{
  "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 in decline. Claude Code zeigt Ihre stderr-Meldung nirgends an.

Claude Code verarbeitet 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 das Modell, das Claude Code für Hintergrundfunktionalität verwendet
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. Claude Code schreibt 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 einem 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.

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:

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