7> Referenz für Claude Code Hook-Ereignisse, Konfigurationsschema, JSON-Ein-/Ausgabeformate, Exit-Codes, asynchrone Hooks, HTTP-Hooks, Prompt-Hooks und MCP-Tool-Hooks.7> Referenz für Claude Code Hook-Ereignisse, Konfigurationsschema, JSON-Ein-/Ausgabeformate, Exit-Codes, asynchrone Hooks, HTTP-Hooks, Prompt-Hooks und MCP-Tool-Hooks.
8 8
9<Tip>9<Tip>
10 Eine Schnellstartanleitung mit Beispielen finden Sie unter [Workflows mit Hooks automatisieren](/docs/de/hooks-guide).10 Eine Schnellstartanleitung mit Beispielen finden Sie unter [Hooks automatisieren](/docs/de/hooks-guide).
11</Tip>11</Tip>
12 12
13Hooks sind benutzerdefinierte Shell-Befehle, HTTP-Endpunkte oder LLM-Prompts, die automatisch an bestimmten Punkten im Lebenszyklus von Claude Code ausgeführt werden. Verwenden Sie diese Referenz, um Ereignisschemas, Konfigurationsoptionen, JSON-Ein-/Ausgabeformate und erweiterte Funktionen wie asynchrone Hooks, HTTP-Hooks und MCP-Tool-Hooks nachzuschlagen. Wenn Sie Hooks zum ersten Mal einrichten, beginnen Sie stattdessen mit der [Anleitung](/docs/de/hooks-guide).13Hooks sind benutzerdefinierte Shell-Befehle, HTTP-Endpunkte, MCP-Tool-Aufrufe, LLM-Prompts oder Subagenten, die automatisch an bestimmten Punkten im Lebenszyklus von Claude Code ausgeführt werden. Claude Code löst die gleichen Hook-Ereignisse überall aus, wo es läuft: Sitzungen im Terminal, IDE-Erweiterungen, die [Desktop-App](/docs/de/desktop-quickstart) und [Cloud-Sitzungen](/docs/de/claude-code-on-the-web). Verwenden Sie diese Referenz, um Ereignisschemas, Konfigurationsoptionen, JSON-Ein-/Ausgabeformate und erweiterte Funktionen wie asynchrone Hooks, HTTP-Hooks und MCP-Tool-Hooks nachzuschlagen.
14 14
15<h2 id="hook-lifecycle">15<h2 id="hook-lifecycle">
16 Hook-Lebenszyklus16 Hook-Lebenszyklus
17</h2>17</h2>
18 18
19Hooks werden an bestimmten Punkten während einer Claude Code-Sitzung ausgelöst. Wenn ein Ereignis ausgelöst wird und ein Matcher passt, übergibt Claude Code JSON-Kontext über das Ereignis an Ihren Hook-Handler. Für Command-Hooks kommt die Eingabe über stdin an. Für HTTP-Hooks kommt sie als POST-Request-Body an. Ihr Handler kann dann die Eingabe überprüfen, Maßnahmen ergreifen und optional eine Entscheidung zurückgeben.19Claude Code führt Hooks an bestimmten Punkten während einer Sitzung aus. Wenn ein Ereignis ausgelöst wird und ein Matcher passt, übergibt Claude Code JSON-Kontext über das Ereignis an Ihren Hook-Handler. Für Command-Hooks kommt die Eingabe über stdin an. Für HTTP-Hooks kommt sie als POST-Request-Body an. Ihr Handler kann dann die Eingabe überprüfen, Maßnahmen ergreifen und optional eine Entscheidung zurückgeben.
20 20
21Ereignisse fallen in drei Rhythmen:21Ereignisse fallen in drei Rhythmen:
22 22
23* einmal pro Sitzung: `SessionStart` und `SessionEnd`23* pro Sitzung: `SessionStart` und `SessionEnd`
24* einmal pro Runde: `UserPromptSubmit`, `Stop` und `StopFailure`24* pro Runde: `UserPromptSubmit`, `Stop` und `StopFailure`
25* bei jedem Tool-Aufruf innerhalb der agentengesteuerten Schleife: `PreToolUse` und `PostToolUse`25* bei jedem Tool-Aufruf innerhalb der agentengesteuerten Schleife: `PreToolUse` und `PostToolUse`, außer [`EndConversation`](/docs/de/tools-reference#endconversation-tool-behavior)-Aufrufen, die beide überspringen
26 26
27<div style={{maxWidth: "500px", margin: "0 auto"}}>27<div style={{maxWidth: "500px", margin: "0 auto"}}>
28 <Frame>28 <Frame>
29 <img src="https://mintcdn.com/claude-code/x7pO8l4XcvAXCoVc/images/hooks-lifecycle.svg?fit=max&auto=format&n=x7pO8l4XcvAXCoVc&q=85&s=81b9256c1bbe8832553485f5d9e9c746" alt="Hook-Lebenszyklus-Diagramm, das optionales Setup zeigt, das in SessionStart führt, dann eine Pro-Runde-Schleife mit UserPromptSubmit, UserPromptExpansion für Slash-Befehle, die verschachtelte agentengesteuerte Schleife (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PostToolBatch, SubagentStart/Stop, TaskCreated, TaskCompleted) und Stop oder StopFailure, gefolgt von TeammateIdle, PreCompact, PostCompact und SessionEnd, mit Elicitation und ElicitationResult verschachtelt in MCP-Tool-Ausführung, PermissionDenied als Seitenzweig von PermissionRequest für Auto-Mode-Ablehnungen, WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged und FileChanged als eigenständige asynchrone Ereignisse, und MessageDisplay als reines Anzeigereignis, das während des Streamings von Assistenten-Nachrichtentexten ausgeführt wird" width="520" height="1336" data-path="images/hooks-lifecycle.svg" />29 <img src="https://mintcdn.com/claude-code/x7pO8l4XcvAXCoVc/images/hooks-lifecycle.svg?fit=max&auto=format&n=x7pO8l4XcvAXCoVc&q=85&s=81b9256c1bbe8832553485f5d9e9c746" className="dark:hidden" alt="Hook-Lebenszyklus-Diagramm, das optionales Setup zeigt, das in SessionStart führt, dann eine Pro-Runde-Schleife mit UserPromptSubmit, UserPromptExpansion für Slash-Befehle, die verschachtelte agentengesteuerte Schleife (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PostToolBatch, SubagentStart/Stop, TaskCreated, TaskCompleted) und Stop oder StopFailure, gefolgt von TeammateIdle, PreCompact, PostCompact und SessionEnd, mit Elicitation und ElicitationResult verschachtelt in MCP-Tool-Ausführung, PermissionDenied als Seitenzweig von PermissionRequest für Auto-Mode-Ablehnungen, WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, FileChanged und DirectoryAdded als eigenständige asynchrone Ereignisse, PreModelSwitch als eigenständiges sequenzielles Ereignis, das vor einem angeforderten Modellwechsel ausgeführt wird, PostModelSwitch als eigenständiges asynchrones Ereignis, das nach dem Modellwechsel der Sitzung ausgeführt wird, und MessageDisplay als reines Anzeigereignis, das während des Streamings von Assistenten-Nachrichtentexten ausgeführt wird" width="520" height="1336" data-path="images/hooks-lifecycle.svg" />
30
31 <img src="https://mintcdn.com/claude-code/x7pO8l4XcvAXCoVc/images/hooks-lifecycle-dark.svg?fit=max&auto=format&n=x7pO8l4XcvAXCoVc&q=85&s=c9b3d88487335f58cce0b52e2f9e7531" className="hidden dark:block" alt="Hook-Lebenszyklus-Diagramm, das optionales Setup zeigt, das in SessionStart führt, dann eine Pro-Runde-Schleife mit UserPromptSubmit, UserPromptExpansion für Slash-Befehle, die verschachtelte agentengesteuerte Schleife (PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PostToolBatch, SubagentStart/Stop, TaskCreated, TaskCompleted) und Stop oder StopFailure, gefolgt von TeammateIdle, PreCompact, PostCompact und SessionEnd, mit Elicitation und ElicitationResult verschachtelt in MCP-Tool-Ausführung, PermissionDenied als Seitenzweig von PermissionRequest für Auto-Mode-Ablehnungen, WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, FileChanged und DirectoryAdded als eigenständige asynchrone Ereignisse, PreModelSwitch als eigenständiges sequenzielles Ereignis, das vor einem angeforderten Modellwechsel ausgeführt wird, PostModelSwitch als eigenständiges asynchrones Ereignis, das nach dem Modellwechsel der Sitzung ausgeführt wird, und MessageDisplay als reines Anzeigereignis, das während des Streamings von Assistenten-Nachrichtentexten ausgeführt wird" width="520" height="1336" data-path="images/hooks-lifecycle-dark.svg" />
30 </Frame>32 </Frame>
31</div>33</div>
32 34
33Die folgende Tabelle fasst zusammen, wann jedes Ereignis ausgelöst wird. Der Abschnitt [Hook-Ereignisse](#hook-events) dokumentiert das vollständige Eingabeschema und die Optionen zur Entscheidungskontrolle für jedes Ereignis.35Die folgende Tabelle fasst zusammen, wann jedes Ereignis ausgelöst wird. Der Abschnitt [Hook-Ereignisse](#hook-events) dokumentiert das vollständige Eingabeschema und die Optionen zur Entscheidungskontrolle für jedes Ereignis.
34 36
35| Event | When it fires |37| Ereignis | Wann es ausgelöst wird |
36| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |38| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
37| `SessionStart` | When a session begins or resumes |39| `SessionStart` | Wenn eine Sitzung beginnt oder fortgesetzt wird |
38| `Setup` | When you start Claude Code with `--init-only`, or with `--init` or `--maintenance` in `-p` mode. For one-time preparation in CI or scripts |40| `Setup` | Wenn Sie Claude Code mit `--init-only` starten oder mit `--init` oder `--maintenance` im `-p`-Modus. Für einmalige Vorbereitung in CI oder Skripten |
39| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |41| `UserPromptSubmit` | Wenn Sie eine Eingabeaufforderung absenden, bevor Claude sie verarbeitet |
40| `UserPromptExpansion` | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion |42| `UserPromptExpansion` | Wenn ein von Ihnen eingegebener Befehl in eine Eingabeaufforderung erweitert wird, bevor sie Claude erreicht. Kann die Erweiterung blockieren |
41| `PreToolUse` | Before a tool call executes. Can block it |43| `PreToolUse` | Bevor ein Werkzeugaufruf ausgeführt wird. Kann ihn blockieren |
42| `PermissionRequest` | When a tool call needs a permission decision |44| `PermissionRequest` | Wenn ein Werkzeugaufruf eine Genehmigungsentscheidung benötigt |
43| `PermissionDenied` | When auto mode denies a tool call, including denials without a classifier verdict. Use JSON `hookSpecificOutput.retry: true` to tell the model it may retry the denied tool call. Claude Code ignores `retry` when the classifier produced no verdict |45| `PermissionDenied` | Wenn der automatische Modus einen Werkzeugaufruf ablehnt, einschließlich Ablehnungen ohne Klassifizierer-Urteil. Verwenden Sie JSON `hookSpecificOutput.retry: true`, um dem Modell mitzuteilen, dass es den abgelehnten Werkzeugaufruf möglicherweise erneut versuchen kann. Claude Code ignoriert `retry`, wenn der Klassifizierer kein Urteil gefällt hat |
44| `PostToolUse` | After a tool call succeeds |46| `PostToolUse` | Nach erfolgreichem Werkzeugaufruf |
45| `PostToolUseFailure` | After a tool call fails |47| `PostToolUseFailure` | Nach fehlgeschlagenem Werkzeugaufruf |
46| `PostToolBatch` | After a full batch of parallel tool calls resolves, before the next model call |48| `PostToolBatch` | Nach Auflösung eines vollständigen Satzes paralleler Werkzeugaufrufe, bevor der nächste Modellaufruf erfolgt |
47| `Notification` | When Claude Code sends a notification |49| `Notification` | Wenn Claude Code eine Benachrichtigung sendet |
48| `MessageDisplay` | While assistant message text is displayed |50| `MessageDisplay` | Während der Text der Assistentnachricht angezeigt wird |
49| `SubagentStart` | When a subagent is spawned |51| `SubagentStart` | Wenn ein Subagent erzeugt wird |
50| `SubagentStop` | When a subagent finishes |52| `SubagentStop` | Wenn ein Subagent beendet wird |
51| `TaskCreated` | When a task is being created via `TaskCreate` |53| `TaskCreated` | Wenn eine Aufgabe über `TaskCreate` erstellt wird |
52| `TaskCompleted` | When a task is being marked as completed |54| `TaskCompleted` | Wenn eine Aufgabe als abgeschlossen markiert wird |
53| `Stop` | When Claude finishes responding |55| `Stop` | Wenn Claude die Antwort beendet |
54| `StopFailure` | When the turn ends due to an API error |56| `StopFailure` | Wenn die Runde aufgrund eines API-Fehlers endet |
55| `TeammateIdle` | When an [agent team](/docs/en/agent-teams) teammate is about to go idle |57| `TeammateIdle` | Wenn ein [Agent-Team](/docs/de/agent-teams)-Teamkollege im Begriff ist, untätig zu werden |
56| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |58| `InstructionsLoaded` | Wenn eine CLAUDE.md- oder `.claude/rules/*.md`-Datei in den Kontext geladen wird. Wird beim Sitzungsstart und beim verzögerten Laden von Dateien während einer Sitzung ausgelöst |
57| `ConfigChange` | When a configuration file changes during a session |59| `ConfigChange` | Wenn sich eine Konfigurationsdatei während einer Sitzung ändert |
58| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |60| `CwdChanged` | Wenn sich das Arbeitsverzeichnis ändert, z. B. wenn Claude einen `cd`-Befehl ausführt. Nützlich für reaktive Umgebungsverwaltung mit Tools wie direnv |
59| `DirectoryAdded` | When a working directory is added mid-session via `/add-dir` or the SDK `register_repo_root` control request |61| `DirectoryAdded` | Wenn ein Arbeitsverzeichnis während einer Sitzung über `/add-dir` oder die SDK-Steueranforderung `register_repo_root` hinzugefügt wird |
60| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |62| `FileChanged` | Wenn sich eine überwachte Datei auf der Festplatte ändert. Das Feld `matcher` gibt an, welche Dateinamen überwacht werden sollen |
61| `WorktreeCreate` | When a worktree is being created via `--worktree`, `isolation: "worktree"`, or for a background session. Replaces default git behavior |63| `WorktreeCreate` | Wenn ein Worktree über `--worktree`, `isolation: "worktree"` oder für eine Hintergrundsitzung erstellt wird. Ersetzt das Standard-Git-Verhalten |
62| `WorktreeRemove` | When a worktree is being removed at session exit, when a subagent finishes, or when you delete a background session |64| `WorktreeRemove` | Wenn ein Worktree beim Sitzungsende, beim Beenden eines Subagenten oder beim Löschen einer Hintergrundsitzung entfernt wird |
63| `PreCompact` | Before context compaction |65| `PreCompact` | Vor Kontextkomprimierung |
64| `PostCompact` | After context compaction completes |66| `PostCompact` | Nach Abschluss der Kontextkomprimierung |
65| `PreModelSwitch` | Before Claude Code applies a model switch that you or a client requested. Can block the switch |67| `PreModelSwitch` | Bevor Claude Code einen Modellwechsel anwendet, den Sie oder ein Client angefordert haben. Kann den Wechsel blockieren |
66| `PostModelSwitch` | After the session's model changes, including changes Claude Code makes on its own, such as restoring the model when you resume a session |68| `PostModelSwitch` | Nach Änderung des Modells der Sitzung, einschließlich Änderungen, die Claude Code selbst vornimmt, z. B. Wiederherstellung des Modells beim Fortsetzen einer Sitzung |
67| `Elicitation` | When an MCP server requests user input during a tool call |69| `Elicitation` | Wenn ein MCP-Server während eines Werkzeugaufrufs Benutzereingaben anfordert |
68| `ElicitationResult` | After a user responds to an MCP elicitation, before the response is sent back to the server |70| `ElicitationResult` | Nachdem ein Benutzer auf eine MCP-Abfrage antwortet, bevor die Antwort an den Server zurückgesendet wird |
69| `SessionEnd` | When a session terminates |71| `SessionEnd` | Wenn eine Sitzung beendet wird |
70 72
71<h3 id="how-a-hook-resolves">73<h3 id="how-a-hook-resolves">
72 Wie ein Hook aufgelöst wird74 Wie ein Hook aufgelöst wird
73</h3>75</h3>
74 76
75Um zu sehen, wie diese Teile zusammenpassen, betrachten Sie diesen `PreToolUse`-Hook, der destruktive Shell-Befehle blockiert. Der `matcher` grenzt auf Bash-Tool-Aufrufe ein und die `if`-Bedingung grenzt weiter auf Bash-Unterbefehle ein, die mit `rm *` übereinstimmen, daher wird `block-rm.sh` nur ausgeführt, wenn beide Filter passen:77Um zu sehen, wie das Ereignis, der Matcher und der Handler zusammenpassen, betrachten Sie diesen `PreToolUse`-Hook, der destruktive Shell-Befehle blockiert.
76 78
77```json theme={null}79<Tabs>
78{80 <Tab title="macOS/Linux">
81 Der `matcher` grenzt auf Bash-Tool-Aufrufe ein und die `if`-Bedingung grenzt weiter auf Bash-Unterbefehle ein, die mit `rm *` übereinstimmen, daher wird `block-rm.sh` nur ausgeführt, wenn beide Filter passen:
82
83 ```json theme={null}
84 {
79 "hooks": {85 "hooks": {
80 "PreToolUse": [86 "PreToolUse": [
81 {87 {
91 }97 }
92 ]98 ]
93 }99 }
94}100 }
95```101 ```
96 102
97Das Skript liest die JSON-Eingabe von stdin, extrahiert den Befehl und gibt eine `permissionDecision` von `"deny"` zurück, wenn es `rm -rf` enthält:103 Das Skript liest die JSON-Eingabe von stdin, extrahiert den Befehl und gibt eine `permissionDecision` von `"deny"` zurück, wenn es `rm -rf` enthält. Speichern Sie es unter `.claude/hooks/block-rm.sh` in Ihrem Projekt und machen Sie es mit `chmod +x .claude/hooks/block-rm.sh` ausführbar, damit Claude Code es ausführen kann:
98 104
99```bash theme={null}105 ```bash theme={null}
100#!/bin/bash106 #!/bin/bash
101# .claude/hooks/block-rm.sh107 # .claude/hooks/block-rm.sh
102COMMAND=$(jq -r '.tool_input.command')108 COMMAND=$(jq -r '.tool_input.command')
103 109
104if echo "$COMMAND" | grep -q 'rm -rf'; then110 if echo "$COMMAND" | grep -q 'rm -rf'; then
105 jq -n '{111 jq -n '{
106 hookSpecificOutput: {112 hookSpecificOutput: {
107 hookEventName: "PreToolUse",113 hookEventName: "PreToolUse",
109 permissionDecisionReason: "Destructive command blocked by hook"115 permissionDecisionReason: "Destructive command blocked by hook"
110 }116 }
111 }'117 }'
112else118 else
113 exit 0 # no decision; normal permission flow applies119 exit 0 # no decision; normal permission flow applies
114fi120 fi
115```121 ```
122
123 Dieses Skript verwendet wie die anderen Bash-Beispiele auf dieser Seite, die JSON-Eingabe analysieren, `jq`, daher installieren Sie `jq` und stellen Sie sicher, dass es sich in Ihrem `PATH` befindet, bevor Sie sie versuchen.
124 </Tab>
125
126 <Tab title="Windows (PowerShell)">
127 Der Matcher `Bash|PowerShell` deckt das [PowerShell-Tool](#powershell) sowie Bash ab. Eine einzelne `if`-Regel passt nur zu den Aufrufen eines Tools, daher erhält jedes Tool seinen eigenen Handler: der erste grenzt auf Bash-Unterbefehle ein, die mit `rm *` übereinstimmen, der zweite auf PowerShell-Befehle, die mit `Remove-Item *` übereinstimmen. Beide führen das gleiche Skript über `powershell.exe` aus:
128
129 ```json theme={null}
130 {
131 "hooks": {
132 "PreToolUse": [
133 {
134 "matcher": "Bash|PowerShell",
135 "hooks": [
136 {
137 "type": "command",
138 "if": "Bash(rm *)",
139 "command": "powershell.exe",
140 "args": [
141 "-NoProfile",
142 "-ExecutionPolicy",
143 "Bypass",
144 "-File",
145 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
146 ]
147 },
148 {
149 "type": "command",
150 "if": "PowerShell(Remove-Item *)",
151 "command": "powershell.exe",
152 "args": [
153 "-NoProfile",
154 "-ExecutionPolicy",
155 "Bypass",
156 "-File",
157 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
158 ]
159 }
160 ]
161 }
162 ]
163 }
164 }
165 ```
166
167 Das Flag `-NoProfile` überspringt das Laden Ihres PowerShell-Profils, damit der Hook schnell startet, und `-ExecutionPolicy Bypass` ermöglicht PowerShell, die lokale Skriptdatei auszuführen.
168
169 Das Skript liest die JSON-Eingabe von stdin, extrahiert den Befehl und gibt eine `permissionDecision` von `"deny"` zurück, wenn es `rm -rf` oder `Remove-Item` gefolgt von `-Recurse` enthält. Speichern Sie es unter `.claude/hooks/block-rm.ps1` in Ihrem Projekt:
116 170
117Angenommen, Claude Code entscheidet sich, `Bash "rm -rf /tmp/build"` auszuführen. Hier ist, was passiert:171 ```powershell theme={null}
172 # .claude/hooks/block-rm.ps1
173 $callInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
174 $command = $callInput.tool_input.command
175
176 if ($command -match 'rm -rf|Remove-Item.*-Recurse') {
177 @{
178 hookSpecificOutput = @{
179 hookEventName = "PreToolUse"
180 permissionDecision = "deny"
181 permissionDecisionReason = "Destructive command blocked by hook"
182 }
183 } | ConvertTo-Json
184 } else {
185 exit 0 # no decision; normal permission flow applies
186 }
187 ```
188 </Tab>
189</Tabs>
190
191Angenommen, Claude Code entscheidet sich, `Bash "rm -rf /tmp/build"` gegen die macOS/Linux-Konfiguration auszuführen. Hier ist, was passiert:
118 192
119<Frame>193<Frame>
120 <img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/hook-resolution.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=be0bf3053550c26de5f54cd64674c197" alt="Diagramm der Hook-Auflösung: PreToolUse wird ausgelöst, der Matcher prüft auf eine Bash-Übereinstimmung, dann prüft die if-Bedingung auf eine Bash(rm *)-Übereinstimmung. Wenn beide passen, wird der Hook-Befehl ausgeführt und gibt permissionDecision deny zurück, daher wird der Tool-Aufruf blockiert und Claude Code wird fortgesetzt. Wenn eine der Prüfungen nicht passt, wird der Hook übersprungen und der Tool-Aufruf darf fortgesetzt werden." width="930" height="270" data-path="images/hook-resolution.svg" />194 <img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/hook-resolution.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=be0bf3053550c26de5f54cd64674c197" className="dark:hidden" alt="Diagramm der Hook-Auflösung: PreToolUse wird ausgelöst, der Matcher prüft auf eine Bash-Übereinstimmung, dann prüft die if-Bedingung auf eine Bash(rm *)-Übereinstimmung. Wenn beide passen, wird der Hook-Befehl ausgeführt und gibt permissionDecision deny zurück, daher wird der Tool-Aufruf blockiert und Claude Code wird fortgesetzt. Wenn eine der Prüfungen nicht passt, wird der Hook übersprungen und der Tool-Aufruf darf fortgesetzt werden." width="930" height="270" data-path="images/hook-resolution.svg" />
195
196 <img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/hook-resolution-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=e80af91f8507cee6bd51ac3c2dd92f63" className="hidden dark:block" alt="Diagramm der Hook-Auflösung: PreToolUse wird ausgelöst, der Matcher prüft auf eine Bash-Übereinstimmung, dann prüft die if-Bedingung auf eine Bash(rm *)-Übereinstimmung. Wenn beide passen, wird der Hook-Befehl ausgeführt und gibt permissionDecision deny zurück, daher wird der Tool-Aufruf blockiert und Claude Code wird fortgesetzt. Wenn eine der Prüfungen nicht passt, wird der Hook übersprungen und der Tool-Aufruf darf fortgesetzt werden." width="930" height="270" data-path="images/hook-resolution-dark.svg" />
121</Frame>197</Frame>
122 198
123<Steps>199<Steps>
183Der Ort, an dem Sie einen Hook definieren, bestimmt seinen Umfang:259Der Ort, an dem Sie einen Hook definieren, bestimmt seinen Umfang:
184 260
185| Speicherort | Umfang | Freigegeben |261| Speicherort | Umfang | Freigegeben |
186| :----------------------------------------------------------- | :------------------------------- | :--------------------------------------------- |262| :--------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ |
187| `~/.claude/settings.json` | Alle Ihre Projekte | Nein, lokal auf Ihrem Computer |263| `~/.claude/settings.json` | Alle Ihre Projekte | Nein, lokal auf Ihrem Computer |
188| `.claude/settings.json` | Einzelnes Projekt | Ja, kann im Repo committed werden |264| `.claude/settings.json` | Einzelnes Projekt | Ja, kann im Repo committed werden |
189| `.claude/settings.local.json` | Einzelnes Projekt | Nein, gitignored, wenn Claude Code es erstellt |265| `.claude/settings.local.json` | Einzelnes Projekt | Nein, gitignored, wenn Claude Code eine Einstellung darin speichert |
190| Verwaltete Richtlinieneinstellungen | Organisationsweit | Ja, von Admin kontrolliert |266| Verwaltete Richtlinieneinstellungen | Organisationsweit | Ja, von Admin kontrolliert |
191| [Plugin](/docs/de/plugins) `hooks/hooks.json` | Wenn Plugin aktiviert ist | Ja, mit dem Plugin gebündelt |267| [Plugin](/docs/de/plugins) `hooks/hooks.json` | Wenn Plugin aktiviert ist | Ja, mit dem Plugin gebündelt |
192| [Skill](/docs/de/skills) oder [Agent](/docs/de/sub-agents) Frontmatter | Während die Komponente aktiv ist | Ja, in der Komponentendatei definiert |268| [Skill](/docs/de/skills) Frontmatter | Der Rest der Sitzung, sobald der Skill aufgerufen wird. Siehe [Hooks in Skills und Agents](#hooks-in-skills-and-agents) | Ja, in der Skill-Datei definiert |
269| [Subagent](/docs/de/sub-agents) Frontmatter | Während dieser Subagent läuft | Ja, in der Subagent-Datei definiert |
193 270
194Weitere Informationen zur Auflösung von Einstellungsdateien finden Sie unter [Einstellungen](/docs/de/settings). Enterprise-Administratoren können `allowManagedHooksOnly` verwenden, um Benutzer-, Projekt- und Plugin-Hooks zu blockieren. Hooks von Plugins, die in verwalteten Einstellungen `enabledPlugins` erzwungen aktiviert sind, sind ausgenommen, daher können Administratoren überprüfte Hooks über einen Organisations-Marketplace verteilen. Siehe [Hook-Konfiguration](/docs/de/settings#hook-configuration).271[Cloud-Sitzungen](/docs/de/claude-code-on-the-web) lesen Ihre lokale `~/.claude/settings.json` nicht; Hooks dort stammen aus dem Repo, was bedeutet, dass seine `.claude/settings.json` in einer Sitzung mit einem Repository und die Plugins, die es deklariert, in jeder Sitzung, und aus den von Ihrem Server verwalteten Einstellungen Ihrer Organisation. In einer [selbstgehosteten Umgebung](/docs/de/self-hosted-environments-configuration#permissions-and-tool-approval) führt Claude Code auch die Hooks aus, die der Operator vom Host `~/.claude/` des Runners seeded hat, und es führt die Hooks in der verwalteten Einstellungsdatei des Runner-Images aus, wenn diese Datei unter den [verwalteten Quellen liegt, die Claude Code anwendet](/docs/de/managed-settings#how-claude-code-combines-managed-sources), was standardmäßig bedeutet, nur wenn weder Server-verwaltete Einstellungen noch eine von MDM bereitgestellte Claude Code-Richtlinie die verwaltete Ebene bereitstellen. Siehe [was von Ihrem Setup übertragen wird](/docs/de/cloud-environments#what-carries-over-from-your-setup), um zu erfahren, welche Dateien eine Cloud-Sitzung erreichen.
272
273Weitere Informationen zur Auflösung von Einstellungsdateien finden Sie unter [Einstellungen](/docs/de/settings).
274
275Hooks aus Einstellungsdateien, verwalteten Richtlinieneinstellungen und Plugins werden auch in [Subagenten](/docs/de/sub-agents) ausgeführt. Wenn ein Subagent ein Tool aufruft, werden Tool-Ereignisse wie `PreToolUse` und `PostToolUse` die gleichen konfigurierten Hooks wie in der Hauptkonversation ausgelöst, und die Eingabe enthält die [gemeinsamen Eingabefelder](#common-input-fields) `agent_id` und `agent_type`, die den Subagenten identifizieren.
276
277Enterprise-Administratoren können `allowManagedHooksOnly` verwenden, um einzuschränken, welche Hooks ausgeführt werden:
278
279* Ihre Benutzer-, Projekt-, lokalen und Plugin-Hooks werden blockiert. Hooks von Plugins, die in verwalteten Einstellungen `enabledPlugins` erzwungen aktiviert sind, sind ausgenommen
280* Claude Code schränkt auch Ihre [`statusLine`](/docs/de/statusline), [`fileSuggestion`](/docs/de/settings-reference#filesuggestion) und [`subagentStatusLine`](/docs/de/statusline#subagent-status-lines) Einstellungen auf verwaltete Einstellungen ein
281* Claude Code deaktiviert auch Plugins mit einer [`command`-Quelle](/docs/de/plugin-marketplaces#command-sources), einschließlich Plugins, die in verwalteten Einstellungen `enabledPlugins` erzwungen aktiviert sind, es sei denn, [`disableCommandPluginSources`](/docs/de/settings-reference#disablecommandpluginsources) ist explizit auf `false` gesetzt. `command`-Quellen erfordern Claude Code v2.1.229 oder später
282* Claude Code blockiert auch Marketplace-[`headersHelper`-Befehle](/docs/de/plugin-marketplaces#authenticate-archive-downloads), es sei denn, [`disableCommandPluginSources`](/docs/de/settings-reference#disablecommandpluginsources) ist explizit auf `false` gesetzt, außer für einen Marketplace, den verwaltete Einstellungen selbst deklarieren
283
284Siehe [was unter `allowManagedHooksOnly` läuft](/docs/de/settings-reference#what-runs-under-allowmanagedhooksonly).
285
286Hook-Einträge werden über Einstellungsebenen hinweg zusammengeführt, anstatt sich gegenseitig zu ersetzen: Benutzer-, Projekt- und lokale Einstellungen fügen ihre eigenen Hooks hinzu, ohne verwaltete zu entfernen, und die Einstellung [`disableAllHooks`](#disable-or-remove-hooks) kann verwaltete Hooks von außerhalb verwalteter Einstellungen nicht deaktivieren.
287
288Die [HTTP-Hook-Allowlists](/docs/de/settings-reference#hook-and-skill-settings) gelten für Hooks aus jeder Quelle, einschließlich verwalteter Richtlinieneinstellungen:
289
290* `allowedHttpHookUrls`: Wenn auf einer beliebigen Einstellungsebene definiert, führt Claude Code einen HTTP-Hook-Handler nur aus, wenn seine URL mit der zusammengeführten Allowlist übereinstimmt
291* `httpHookAllowedEnvVars`: Wenn definiert, interpoliert Claude Code nur die Umgebungsvariablen auf dieser Liste in Hook-Header
195 292
196<h3 id="matcher-patterns">293<h3 id="matcher-patterns">
197 Matcher-Muster294 Matcher-Muster
218Jeder Ereignistyp passt auf ein anderes Feld:315Jeder Ereignistyp passt auf ein anderes Feld:
219 316
220| Ereignis | Worauf der Matcher filtert | Beispiel-Matcher-Werte |317| Ereignis | Worauf der Matcher filtert | Beispiel-Matcher-Werte |
221| :------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |318| :------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
222| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | Tool-Name | `Bash`, `Edit\|Write`, `mcp__.*` |319| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | Tool-Name | `Bash`, `Edit\|Write`, `mcp__.*` |
223| `SessionStart` | Wie die Sitzung gestartet wurde | `startup`, `resume`, `clear`, `compact` |320| `SessionStart` | Wie die Sitzung gestartet wurde | `startup`, `resume`, `clear`, `compact`, `fork` |
224| `Setup` | Welches CLI-Flag das Setup ausgelöst hat | `init`, `maintenance` |321| `Setup` | Welches CLI-Flag das Setup ausgelöst hat | `init`, `maintenance` |
225| `SessionEnd` | Warum die Sitzung endete | `clear`, `resume`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `other` |322| `SessionEnd` | Warum die Sitzung endete | `clear`, `resume`, `logout`, `prompt_input_exit`, `other` |
226| `Notification` | Benachrichtigungstyp | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed` |323| `Notification` | Benachrichtigungstyp | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed`, `quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled` |
227| `SubagentStart` | Agent-Typ | `general-purpose`, `Explore`, `Plan`, benutzerdefinierte Agent-Namen oder Plugin-bezogene Namen wie `^my-plugin:reviewer$` |324| `SubagentStart` | Agent-Typ | `general-purpose`, `Explore`, `Plan`, benutzerdefinierte Agent-Namen oder Plugin-bezogene Namen wie `^my-plugin:reviewer$` |
228| `PreCompact`, `PostCompact` | Was die Komprimierung ausgelöst hat | `manual`, `auto` |325| `PreCompact`, `PostCompact` | Was die Komprimierung ausgelöst hat | `manual`, `auto` |
326| `PreModelSwitch`, `PostModelSwitch` | Kanonischer Name des Modells, zu dem die Sitzung wechselt, wie unter [PreModelSwitch](#premodelswitch) beschrieben | `claude-opus-5`, `claude-opus-4-6\|claude-opus-5`, `.*opus.*` |
229| `SubagentStop` | Agent-Typ | gleiche Werte wie `SubagentStart` |327| `SubagentStop` | Agent-Typ | gleiche Werte wie `SubagentStart` |
230| `ConfigChange` | Konfigurationsquelle | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` |328| `ConfigChange` | Konfigurationsquelle | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` |
231| `CwdChanged` | Keine Matcher-Unterstützung | wird immer bei jedem Verzeichniswechsel ausgelöst |329| `CwdChanged` | Keine Matcher-Unterstützung | wird immer bei jedem Verzeichniswechsel ausgelöst |
330| `DirectoryAdded` | Wie das Verzeichnis hinzugefügt wurde | `slash_command`, `register_repo_root` |
232| `FileChanged` | Dateinamen zum Überwachen (siehe [FileChanged](#filechanged)) | `.envrc\|.env` |331| `FileChanged` | Dateinamen zum Überwachen (siehe [FileChanged](#filechanged)) | `.envrc\|.env` |
233| `StopFailure` | Fehlertyp | `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `unknown` |332| `StopFailure` | Fehlertyp | `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, `unknown` |
234| `InstructionsLoaded` | Ladegrund | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` |333| `InstructionsLoaded` | Ladegrund | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` |
235| `UserPromptExpansion` | Befehlsname | Ihre Skill- oder Befehlsnamen |334| `UserPromptExpansion` | Befehlsname | Ihre Skill- oder Befehlsnamen |
236| `Elicitation` | MCP-Server-Name | Ihre konfigurierten MCP-Server-Namen |335| `Elicitation` | MCP-Server-Name | Ihre konfigurierten MCP-Server-Namen |
237| `ElicitationResult` | MCP-Server-Name | gleiche Werte wie `Elicitation` |336| `ElicitationResult` | MCP-Server-Name | gleiche Werte wie `Elicitation` |
238| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `MessageDisplay` | Keine Matcher-Unterstützung | wird immer bei jedem Auftreten ausgelöst |337| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `MessageDisplay` | Keine Matcher-Unterstützung | wird immer bei jedem Auftreten ausgelöst |
239 338
240Der Matcher wird gegen ein Feld aus der [JSON-Eingabe](#hook-input-and-output) ausgeführt, die Claude Code an Ihren Hook über stdin sendet. Für Tool-Ereignisse ist dieses Feld `tool_name`. Jeder Abschnitt [Hook-Ereignis](#hook-events) listet den vollständigen Satz von Matcher-Werten und das Eingabeschema für dieses Ereignis auf.339Das Abgleichen von `StopFailure` auf `cloud_credential_error` erfordert Claude Code v2.1.267 oder später, die erste Version, die Fehler beim Laden von Anmeldedaten unter diesem Wert statt unter `server_error` oder `unknown` meldet.
340
341Für die meisten Ereignisse wertet Claude Code den Matcher gegen ein Feld aus der [JSON-Eingabe](#hook-input-and-output) aus, die es an Ihren Hook über stdin sendet. Für Tool-Ereignisse ist dieses Feld `tool_name`. Für `PreModelSwitch` und `PostModelSwitch` wertet Claude Code den Matcher gegen den kanonischen Namen aus, den es aus `to_model` ableitet, wie unter [PreModelSwitch](#premodelswitch) beschrieben. Jeder Abschnitt [Hook-Ereignis](#hook-events) listet den vollständigen Satz von Matcher-Werten und das Eingabeschema für dieses Ereignis auf.
241 342
242Dieses Beispiel führt ein Linting-Skript nur aus, wenn Claude eine Datei schreibt oder bearbeitet:343Dieses Beispiel führt ein Linting-Skript nur aus, wenn Claude eine Datei schreibt oder bearbeitet:
243 344
259}360}
260```361```
261 362
262`UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `MessageDisplay` und `CwdChanged` unterstützen keine Matcher und werden immer bei jedem Auftreten ausgelöst. Wenn Sie ein `matcher`-Feld zu diesen Ereignissen hinzufügen, wird es stillschweigend ignoriert.363Wenn Sie ein `matcher`-Feld zu einem Ereignis ohne Matcher-Unterstützung hinzufügen, wird es stillschweigend ignoriert.
263 364
264Für Tool-Ereignisse können Sie enger filtern, indem Sie das Feld [`if`](#common-fields) auf einzelnen Hook-Handlern setzen. `if` verwendet [Berechtigungsregel-Syntax](/docs/de/permissions), um gegen den Tool-Namen und die Argumente zusammen zu passen, daher wird `"Bash(git *)"` ausgeführt, wenn ein Bash-Befehl mit `git *` übereinstimmt und `"Edit(*.ts)"` wird nur für TypeScript-Dateien ausgeführt.365Für Tool-Ereignisse können Sie enger filtern, indem Sie das Feld [`if`](#common-fields) auf einzelnen Hook-Handlern setzen. `if` verwendet [Berechtigungsregel-Syntax](/docs/de/permissions), um gegen den Tool-Namen und die Argumente zusammen zu passen, daher wird `"Bash(git *)"` ausgeführt, wenn ein Bash-Befehl mit `git *` übereinstimmt und `"Edit(*.ts)"` wird nur für TypeScript-Dateien ausgeführt.
265 366
323* **[Command-Hooks](#command-hook-fields)** (`type: "command"`): führen einen Shell-Befehl aus. Ihr Skript erhält die [JSON-Eingabe](#hook-input-and-output) des Ereignisses über stdin und kommuniziert Ergebnisse über Exit-Codes und stdout zurück.424* **[Command-Hooks](#command-hook-fields)** (`type: "command"`): führen einen Shell-Befehl aus. Ihr Skript erhält die [JSON-Eingabe](#hook-input-and-output) des Ereignisses über stdin und kommuniziert Ergebnisse über Exit-Codes und stdout zurück.
324* **[HTTP-Hooks](#http-hook-fields)** (`type: "http"`): senden die [JSON-Eingabe](#hook-input-and-output) des Ereignisses als HTTP-POST-Request an eine URL. Der Endpunkt kommuniziert Ergebnisse über den Response-Body mit dem gleichen [JSON-Ausgabeformat](#json-output) wie Command-Hooks zurück.425* **[HTTP-Hooks](#http-hook-fields)** (`type: "http"`): senden die [JSON-Eingabe](#hook-input-and-output) des Ereignisses als HTTP-POST-Request an eine URL. Der Endpunkt kommuniziert Ergebnisse über den Response-Body mit dem gleichen [JSON-Ausgabeformat](#json-output) wie Command-Hooks zurück.
325* **[MCP-Tool-Hooks](#mcp-tool-hook-fields)** (`type: "mcp_tool"`): rufen ein Tool auf einem bereits verbundenen [MCP-Server](/docs/de/mcp) auf. Die Textausgabe des Tools wird wie Command-Hook-stdout behandelt.426* **[MCP-Tool-Hooks](#mcp-tool-hook-fields)** (`type: "mcp_tool"`): rufen ein Tool auf einem bereits verbundenen [MCP-Server](/docs/de/mcp) auf. Die Textausgabe des Tools wird wie Command-Hook-stdout behandelt.
326* **[Prompt-Hooks](#prompt-and-agent-hook-fields)** (`type: "prompt"`): senden einen Prompt an ein Claude-Modell für eine Single-Turn-Evaluierung. Das Modell gibt eine Ja/Nein-Entscheidung als JSON zurück. Siehe [Prompt-basierte Hooks](#prompt-based-hooks).427* **[Prompt-Hooks](#prompt-and-agent-hook-fields)** (`type: "prompt"`): senden einen Prompt an ein Claude-Modell für eine Single-Turn-Evaluierung. Das Modell gibt seine Entscheidung als JSON zurück. Siehe [Prompt-basierte Hooks](#prompt-based-hooks).
327* **[Agent-Hooks](#prompt-and-agent-hook-fields)** (`type: "agent"`): spawnen einen Subagenten, der Tools wie Read, Grep und Glob verwenden kann, um Bedingungen zu überprüfen, bevor eine Entscheidung zurückgegeben wird. Agent-Hooks sind experimentell und können sich ändern. Siehe [Agent-basierte Hooks](#agent-based-hooks).428* **[Agent-Hooks](#prompt-and-agent-hook-fields)** (`type: "agent"`): spawnen einen Subagenten, der Tools wie Read, Grep und Glob verwenden kann, um Bedingungen zu überprüfen, bevor eine Entscheidung zurückgegeben wird. Agent-Hooks sind experimentell und können sich ändern. Siehe [Agent-basierte Hooks](#agent-based-hooks).
328 429
329Alle passenden Hooks werden parallel ausgeführt, und identische Handler werden automatisch dedupliziert. Command-Hooks werden nach Befehlszeichenkette und `args` dedupliziert, und HTTP-Hooks werden nach URL dedupliziert.430Alle passenden Hooks werden parallel ausgeführt. Wenn Sie denselben Handler in mehr als einer Einstellungsdatei definieren, wird er einmal ausgeführt. Eine Kopie desselben Handlers von einem Plugin oder Skill bleibt separat.
431
432Handler werden im aktuellen Verzeichnis mit der Umgebung von Claude Code ausgeführt. Wenn das aktuelle Verzeichnis nicht mehr existiert, zum Beispiel ein Worktree oder temporäres Verzeichnis, das eine andere Shell während der Sitzung gelöscht hat, führt Claude Code Command-Hooks aus dem ersten dieser Verzeichnisse aus, das noch existiert: das Verzeichnis, in dem die Sitzung gestartet wurde, das Projekt-Root, Ihr Home-Verzeichnis oder das System-Temp-Verzeichnis. Claude Code zeichnet eine Warnung auf, die das Fallback-Verzeichnis im [Debug-Log](#debug-hooks) benennt.
330 433
331Handler werden im aktuellen Verzeichnis mit der Umgebung von Claude Code ausgeführt. Die Umgebungsvariable `$CLAUDE_CODE_REMOTE` wird in Remote-Web-Umgebungen auf `"true"` gesetzt und ist in der lokalen CLI nicht gesetzt. Ab v2.1.199 wird [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/de/env-vars) auf die [Remote Control](/docs/de/remote-control) Sitzungs-ID gesetzt, während die lokale Sitzung eine aktive Remote Control-Verbindung hat.434Die Umgebungsvariable `$CLAUDE_CODE_REMOTE` ist `"true"` in Remote-Web-Umgebungen und nicht in der lokalen CLI gesetzt. Claude Code v2.1.199 und später setzt [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/de/env-vars) auf die [Remote Control](/docs/de/remote-control) Sitzungs-ID, während die lokale Sitzung eine aktive Remote Control-Verbindung hat.
332 435
333<h4 id="common-fields">436<h4 id="common-fields">
334 Gemeinsame Felder437 Gemeinsame Felder
337Diese Felder gelten für alle Hook-Typen:440Diese Felder gelten für alle Hook-Typen:
338 441
339| Feld | Erforderlich | Beschreibung |442| Feld | Erforderlich | Beschreibung |
340| :-------------- | :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |443| :-------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
341| `type` | ja | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` oder `"agent"` |444| `type` | ja | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` oder `"agent"` |
342| `if` | nein | Berechtigungsregel-Syntax zum Filtern, wann dieser Hook ausgeführt wird, wie `"Bash(git *)"` oder `"Edit(*.ts)"`. Der Hook wird nur ausgeführt, wenn der Tool-Aufruf dem Muster entspricht. Siehe die [Bash-Matching-Tabelle](#bash-if-matching) unten, um zu sehen, wie Bash-Muster gegen Unterbefehle, `$()` und Backticks evaluiert werden. Wird nur auf Tool-Ereignisse evaluiert: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` und `PermissionDenied`. Bei anderen Ereignissen wird ein Hook mit `if` gesetzt nie ausgeführt. Verwendet die gleiche Syntax wie [Berechtigungsregeln](/docs/de/permissions) |445| `if` | nein | Berechtigungsregel-Syntax zum Filtern, wann dieser Hook ausgeführt wird, wie `"Bash(git *)"` oder `"Edit(*.ts)"`. Der Hook wird nur ausgeführt, wenn der Tool-Aufruf dem Muster entspricht. Siehe die [Bash-Matching-Tabelle](#bash-if-matching) unten, um zu sehen, wie Bash-Muster gegen Unterbefehle, `$()` und Backticks evaluiert werden. Wird nur auf Tool-Ereignisse evaluiert: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` und `PermissionDenied`. Bei anderen Ereignissen wird ein Hook mit `if` gesetzt nie ausgeführt. Verwendet die gleiche Syntax wie [Berechtigungsregeln](/docs/de/permissions) |
343| `timeout` | nein | Sekunden vor dem Abbruch. Standardwerte: 600 für `command`, `http` und `mcp_tool`; 30 für `prompt`; 60 für `agent`. [`UserPromptSubmit`](#userpromptsubmit) senkt den Standardwert für `command`, `http` und `mcp_tool` auf 30, und [`MessageDisplay`](#messagedisplay) senkt ihn auf 10 |446| `timeout` | nein | Sekunden vor dem Abbruch. Claude Code erzwingt es nicht auf einem Command-Hook, den Sie mit [`async: true`](#run-hooks-in-the-background) ausführen. Standardwerte: 600 für `command`, `http` und `mcp_tool`; 30 für `prompt`; 60 für `agent`. Claude Code senkt den Standardwert für `command`, `http` und `mcp_tool` auf 30 bei [`UserPromptSubmit`](#userpromptsubmit), [`PreModelSwitch`](#premodelswitch) und [`PostModelSwitch`](#postmodelswitch), und auf 10 bei [`MessageDisplay`](#messagedisplay). [`SessionEnd`](#sessionend) Hooks teilen sich ein Budget von 1,5 Sekunden; wenn Ihre Einstellungen einen längeren Pro-Hook-`timeout` setzen, erhöht Claude Code das Budget, um zu passen, bis zu 60 Sekunden |
344| `statusMessage` | nein | Benutzerdefinierte Spinner-Nachricht, die angezeigt wird, während der Hook ausgeführt wird |447| `statusMessage` | nein | Benutzerdefinierte Spinner-Nachricht, die angezeigt wird, während der Hook ausgeführt wird |
345| `once` | nein | Wenn `true`, wird nur einmal pro Sitzung ausgeführt und dann entfernt. Nur für Hooks, die in [Skill-Frontmatter](#hooks-in-skills-and-agents) deklariert sind; wird in Einstellungsdateien und Agent-Frontmatter ignoriert |448| `once` | nein | Wenn `true`, entfernt Claude Code den Hook nach seiner ersten erfolgreichen Ausführung. Eine Ausführung, die fehlschlägt, mit Exit-Code 2 blockiert oder Timeout hat, lässt den Hook an Ort und Stelle, daher wird er beim nächsten passenden Ereignis erneut ausgeführt. Wird nur für Hooks berücksichtigt, die in [Skill-Frontmatter](#hooks-in-skills-and-agents) deklariert sind; wird in Einstellungsdateien und Agent-Frontmatter ignoriert |
346 449
347Das Feld `if` enthält genau eine Berechtigungsregel. Es gibt keine `&&`-, `||`- oder List-Syntax zum Kombinieren von Regeln; um mehrere Bedingungen anzuwenden, definieren Sie einen separaten Hook-Handler für jeden.450Das Feld `if` enthält genau eine Berechtigungsregel. Es gibt keine `&&`-, `||`- oder List-Syntax zum Kombinieren von Regeln; um mehrere Bedingungen anzuwenden, definieren Sie einen separaten Hook-Handler für jeden.
348 451
452In einer `if`-Bedingung für ein Datei-Tool passt ein Single-Segment-Verzeichnismuster wie `"Edit(src/**)"` nur zum `src`-Verzeichnis im Arbeitsverzeichnis und den Dateien darunter. Um ein Verzeichnis namens `src` in beliebiger Tiefe zu treffen, schreiben Sie `"Edit(**/src/**)"`. Vor v2.1.214 passte `"Edit(src/**)"` zu einem Verzeichnis namens `src` in beliebiger Tiefe unter dem Arbeitsverzeichnis.
453
349<span id="bash-if-matching" />Für Bash-Muster hängt davon ab, ob Ihr Hook-Befehl ausgeführt wird, von der Form des Musters und dem Bash-Befehl, den Claude aufruft. Führende `VAR=value`-Zuweisungen werden vor dem Abgleich entfernt.454<span id="bash-if-matching" />Für Bash-Muster hängt davon ab, ob Ihr Hook-Befehl ausgeführt wird, von der Form des Musters und dem Bash-Befehl, den Claude aufruft. Führende `VAR=value`-Zuweisungen werden vor dem Abgleich entfernt.
350 455
351| `if`-Muster | Bash-Befehl | Hook wird ausgeführt? | Warum |456| `if`-Muster | Bash-Befehl | Hook wird ausgeführt? | Warum |
352| :----------------- | :--------------------- | :-------------------- | :----------------------------------------------------------------------------------------------------------- |457| :----------------- | :-------------------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
353| `Bash(git *)` | `FOO=bar git push` | ja | führende Zuweisungen werden entfernt; `git push` passt |458| `Bash(git *)` | `FOO=bar git push` | ja | führende Zuweisungen werden entfernt; `git push` passt |
354| `Bash(git *)` | `npm test && git push` | ja | jeder Unterbefehl wird überprüft; `git push` passt |459| `Bash(git *)` | `npm test && git push` | ja | jeder Unterbefehl wird überprüft; `git push` passt |
355| `Bash(rm *)` | `echo $(rm -rf /)` | ja | Befehle in `$()` und Backticks werden überprüft; `rm -rf /` passt |460| `Bash(rm *)` | `echo $(rm -rf /)` | ja | Befehle in `$()` und Backticks werden überprüft; `rm -rf /` passt |
356| `Bash(rm *)` | `echo $(date)` | nein | kein Unterbefehl passt zu `rm *` |461| `Bash(rm *)` | `echo $(date)` | nein | kein Unterbefehl passt zu `rm *` |
462| `Bash(cat *)` | `echo before $(date) after` | nein | eine Substitution kann an jeder Argumentposition sitzen, daher werden der vollständige Befehl und `date` beide überprüft; keiner passt zu `cat *` |
463| `Bash(git *)` | `$TOOL git push` | ja | Claude Code kann nicht sagen, zu was sich der Befehlsname erweitert, daher wird der Hook ausgeführt |
357| `Bash(git push *)` | `echo $(date)` | ja | Muster, die mehr als den Befehlsnamen angeben, führen den Hook trotzdem bei `$()`, Backticks oder `$VAR` aus |464| `Bash(git push *)` | `echo $(date)` | ja | Muster, die mehr als den Befehlsnamen angeben, führen den Hook trotzdem bei `$()`, Backticks oder `$VAR` aus |
358 465
359Der Filter schlägt auch offen fehl und führt Ihren Hook unabhängig vom Muster aus, wenn der Bash-Befehl nicht geparst werden kann. Da der `if`-Filter Best-Effort ist, verwenden Sie das [Berechtigungssystem](/docs/de/permissions) statt eines Hooks, um ein hartes Zulassen oder Verweigern durchzusetzen.466Wenn Claude Code nicht bestimmen kann, welche Befehle die Bash-Eingabe ausführt, wird Ihr Hook unabhängig vom Muster ausgeführt. Da der `if`-Filter Best-Effort ist, verwenden Sie das [Berechtigungssystem](/docs/de/permissions) statt eines Hooks, um ein hartes Zulassen oder Verweigern durchzusetzen.
360 467
361<h4 id="command-hook-fields">468<h4 id="command-hook-fields">
362 Command-Hook-Felder469 Command-Hook-Felder
369| `command` | ja | Shell-Befehl zum Ausführen. Mit `args` die ausführbare Datei zum direkten Spawnen. Siehe [Exec-Form und Shell-Form](#exec-form-and-shell-form) |476| `command` | ja | Shell-Befehl zum Ausführen. Mit `args` die ausführbare Datei zum direkten Spawnen. Siehe [Exec-Form und Shell-Form](#exec-form-and-shell-form) |
370| `args` | nein | Argumentliste. Wenn vorhanden, wird `command` als ausführbare Datei aufgelöst und direkt mit `args` als Argumentvektor gespawnt, ohne Shell. Siehe [Exec-Form und Shell-Form](#exec-form-and-shell-form) |477| `args` | nein | Argumentliste. Wenn vorhanden, wird `command` als ausführbare Datei aufgelöst und direkt mit `args` als Argumentvektor gespawnt, ohne Shell. Siehe [Exec-Form und Shell-Form](#exec-form-and-shell-form) |
371| `async` | nein | Wenn `true`, wird im Hintergrund ausgeführt, ohne zu blockieren. Siehe [Hooks im Hintergrund ausführen](#run-hooks-in-the-background) |478| `async` | nein | Wenn `true`, wird im Hintergrund ausgeführt, ohne zu blockieren. Siehe [Hooks im Hintergrund ausführen](#run-hooks-in-the-background) |
372| `asyncRewake` | nein | Wenn `true`, wird im Hintergrund ausgeführt und weckt Claude bei Exit-Code 2 auf. Impliziert `async`. Der stderr des Hooks oder stdout, wenn stderr leer ist, wird Claude als Systemerinnerung angezeigt, damit es auf einen lang laufenden Hintergrund-Fehler reagieren kann |479| `asyncRewake` | nein | Wenn `true`, wird im Hintergrund ausgeführt und weckt Claude bei Exit-Code 2 auf. Der stderr des Hooks oder stdout, wenn stderr leer ist, wird Claude als Systemerinnerung angezeigt, damit es auf einen lang laufenden Hintergrund-Fehler reagieren kann |
373| `shell` | nein | Shell zum Verwenden für diesen Hook. Akzeptiert `"bash"` oder `"powershell"`. Standardwert ist `"bash"` oder `"powershell"` unter Windows, wenn Git Bash nicht installiert ist. Das Setzen von `"powershell"` führt den Befehl über PowerShell unter Windows aus. Erfordert nicht `CLAUDE_CODE_USE_POWERSHELL_TOOL`, da Hooks PowerShell direkt spawnen. Wird ignoriert, wenn `args` gesetzt ist |480| `shell` | nein | Shell zum Verwenden für diesen Hook. Akzeptiert `"bash"` oder `"powershell"`. Standardwert ist `"bash"` oder `"powershell"` unter Windows, wenn Git Bash nicht installiert ist. Das Setzen von `"powershell"` führt den Befehl über PowerShell unter Windows aus. Erfordert nicht `CLAUDE_CODE_USE_POWERSHELL_TOOL`, da Hooks PowerShell direkt spawnen. Wird ignoriert, wenn `args` gesetzt ist |
374 481
375<a id="exec-form-and-shell-form" />482<a id="exec-form-and-shell-form" />
431 538
432Claude Code sendet die [JSON-Eingabe](#hook-input-and-output) des Hooks als POST-Request-Body mit `Content-Type: application/json`. Der Response-Body verwendet das gleiche [JSON-Ausgabeformat](#json-output) wie Command-Hooks.539Claude Code sendet die [JSON-Eingabe](#hook-input-and-output) des Hooks als POST-Request-Body mit `Content-Type: application/json`. Der Response-Body verwendet das gleiche [JSON-Ausgabeformat](#json-output) wie Command-Hooks.
433 540
434Die Fehlerbehandlung unterscheidet sich von Command-Hooks: Nicht-2xx-Antworten, Verbindungsfehler und Timeouts führen alle zu nicht-blockierenden Fehlern, die die Ausführung fortsetzen lassen. Um einen Tool-Aufruf zu blockieren oder eine Berechtigung zu verweigern, geben Sie eine 2xx-Antwort mit einem JSON-Body zurück, der `decision: "block"` oder ein `hookSpecificOutput` mit `permissionDecision: "deny"` enthält.541Die Fehlerbehandlung unterscheidet sich von Command-Hooks; siehe [HTTP-Response-Behandlung](#http-response-handling).
435 542
436Dieses Beispiel sendet `PreToolUse`-Ereignisse an einen lokalen Validierungsdienst und authentifiziert sich mit einem Token aus der `MY_TOKEN`-Umgebungsvariable:543Dieses Beispiel sendet `PreToolUse`-Ereignisse an einen lokalen Validierungsdienst und authentifiziert sich mit einem Token aus der `MY_TOKEN`-Umgebungsvariable:
437 544
470| `tool` | ja | Name des Tools, das auf diesem Server aufgerufen werden soll |577| `tool` | ja | Name des Tools, das auf diesem Server aufgerufen werden soll |
471| `input` | nein | Argumente, die an das Tool übergeben werden. String-Werte unterstützen `${path}`-Substitution aus der [JSON-Eingabe](#hook-input-and-output) des Hooks, wie `"${tool_input.file_path}"` |578| `input` | nein | Argumente, die an das Tool übergeben werden. String-Werte unterstützen `${path}`-Substitution aus der [JSON-Eingabe](#hook-input-and-output) des Hooks, wie `"${tool_input.file_path}"` |
472 579
473Die Textausgabe des Tools wird wie Command-Hook-stdout behandelt: Wenn sie als gültige [JSON-Ausgabe](#json-output) geparst wird, wird sie als Entscheidung verarbeitet, andernfalls wird sie als Klartext angezeigt. Wenn der benannte Server nicht verbunden ist oder das Tool `isError: true` zurückgibt, erzeugt der Hook einen nicht-blockierenden Fehler und die Ausführung wird fortgesetzt.580Claude Code liest die Textausgabe des Tools auf die gleiche Weise wie Command-Hook-stdout, nach der [Parsing-Regel unter Exit-Code 0](#exit-code-0). Wenn der benannte Server nicht verbunden ist oder das Tool `isError: true` zurückgibt, erzeugt der Hook einen nicht-blockierenden Fehler und die Ausführung wird fortgesetzt.
474
475MCP-Tool-Hooks sind auf jedem Hook-Ereignis verfügbar, sobald Claude Code sich mit Ihren MCP-Servern verbunden hat. `SessionStart` und `Setup` werden normalerweise ausgelöst, bevor Server die Verbindung beenden, daher sollten Hooks auf diesen Ereignissen beim ersten Ausführen den Fehler „nicht verbunden" erwarten.
476 581
477Dieses Beispiel ruft das Tool `security_scan` auf dem MCP-Server `my_server` nach jedem `Write` oder `Edit` auf und übergibt den Pfad der bearbeiteten Datei:582Dieses Beispiel ruft das Tool `security_scan` auf dem MCP-Server `my_server` nach jedem `Write` oder `Edit` auf und übergibt den Pfad der bearbeiteten Datei:
478 583
496}601}
497```602```
498 603
604Ein `mcp_tool`-Hook kann nur ausgeführt werden, sobald Claude Code die MCP-Server der Sitzung für Hooks verfügbar gemacht hat. `SessionStart` und `Setup` können vor diesem Punkt ausgelöst werden:
605
606* **Beim Start**: `SessionStart` wird ausgelöst, bevor die Server verfügbar sind, auch wenn Sie mit `--continue` oder `--resume` starten. Claude Code überspringt die `mcp_tool`-Hooks des Ereignisses, ohne ihre Tools aufzurufen, und das [Debug-Log](#debug-hooks) zeichnet `mcp_tool hooks are not available for the 'SessionStart' hook event (no MCP client context)` auf.
607* **Später in einer laufenden Sitzung**: nach `/clear` oder einer Komprimierung wird `SessionStart` erneut ausgelöst, wobei die Server bereits verfügbar sind, und seine `mcp_tool`-Hooks werden ausgeführt.
608* **Bei `Setup`**: `Setup` wird immer ausgelöst, bevor die Server verfügbar sind, daher überspringt Claude Code seine `mcp_tool`-Hooks jedes Mal und zeichnet die gleiche Nachricht auf, die `Setup` benennt.
609
610Zum Beispiel ruft diese Konfiguration das Tool `load_context` auf dem MCP-Server `my_server` aus einem `SessionStart`-Hook ohne Matcher auf, daher gilt es für jede `SessionStart`-Quelle:
611
612```json theme={null}
613{
614 "hooks": {
615 "SessionStart": [
616 {
617 "hooks": [
618 {
619 "type": "mcp_tool",
620 "server": "my_server",
621 "tool": "load_context"
622 }
623 ]
624 }
625 ]
626 }
627}
628```
629
630Wenn Sie `claude` ausführen, überspringt Claude Code diesen Hook, ruft `load_context` nie auf und schreibt die Nachricht `no MCP client context` in das Debug-Log. Führen Sie `/clear` in dieser gleichen Sitzung aus und der Hook wird ausgeführt und ruft `load_context` auf. Ein `type: "command"`-Hook auf `SessionStart` wird beim Start ausgeführt, daher verwenden Sie einen für alles, das die Sitzung von ihrer ersten Runde benötigt.
631
499<h4 id="prompt-and-agent-hook-fields">632<h4 id="prompt-and-agent-hook-fields">
500 Prompt- und Agent-Hook-Felder633 Prompt- und Agent-Hook-Felder
501</h4>634</h4>
513 646
514Verwenden Sie diese Platzhalter, um Hook-Skripte relativ zum Projekt- oder Plugin-Root zu referenzieren, unabhängig vom Arbeitsverzeichnis, wenn der Hook ausgeführt wird:647Verwenden Sie diese Platzhalter, um Hook-Skripte relativ zum Projekt- oder Plugin-Root zu referenzieren, unabhängig vom Arbeitsverzeichnis, wenn der Hook ausgeführt wird:
515 648
516* `${CLAUDE_PROJECT_DIR}`: das Projekt-Root. Claude Code setzt diese Variable auch in der Umgebung von [stdio MCP-Servern](/docs/de/mcp#option-3-add-a-local-stdio-server) und Plugin-LSP-Servern.649* `${CLAUDE_PROJECT_DIR}`: das Projekt-Root, wo die Sitzung gestartet wurde. Claude Code setzt diese Variable auch in der Umgebung von [stdio MCP-Servern](/docs/de/mcp#option-3-add-a-local-stdio-server) und Plugin-LSP-Servern.
517* `${CLAUDE_PLUGIN_ROOT}`: das Installationsverzeichnis des Plugins, für Skripte, die mit einem [Plugin](/docs/de/plugins) gebündelt sind. Ändert sich bei jedem Plugin-Update.650* `${CLAUDE_PLUGIN_ROOT}`: das Installationsverzeichnis des Plugins, für Skripte, die mit einem [Plugin](/docs/de/plugins) gebündelt sind. Siehe [Plugin-Umgebungsvariablen](/docs/de/plugins-reference#environment-variables), um zu erfahren, wie sich der Pfad über Updates verhält.
518* `${CLAUDE_PLUGIN_DATA}`: das [persistente Datenverzeichnis](/docs/de/plugins-reference#persistent-data-directory) des Plugins, für Abhängigkeiten und Zustand, die Plugin-Updates überstehen sollten.651* `${CLAUDE_PLUGIN_DATA}`: das [persistente Datenverzeichnis](/docs/de/plugins-reference#persistent-data-directory) des Plugins, für Abhängigkeiten und Zustand, die Plugin-Updates überstehen sollten.
519 652
520Bevorzugen Sie [Exec-Form](#exec-form-and-shell-form) für jeden Hook, der auf einen Pfad-Platzhalter verweist. Exec-Form übergibt jedes `args`-Element als ein Argument ohne Shell-Tokenisierung, daher benötigen Pfade mit Leerzeichen oder Sonderzeichen keine Anführungszeichen. In Shell-Form wickeln Sie jeden Platzhalter in doppelte Anführungszeichen ein.653<Note>
654 **Worktrees sind anders.** Wenn Claude während der Sitzung einen [Worktree](/docs/de/worktrees) betritt, behält Claude Code `${CLAUDE_PROJECT_DIR}` dort, wo es war, und übergibt den Worktree-Pfad an Ihre Hooks auf andere Weise:
655
656 * **`${CLAUDE_PROJECT_DIR}` bleibt stehen**: Es zeigt immer noch auf das Projekt-Root, wo die Sitzung gestartet wurde, daher führt ein Befehl wie `${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh` das Skript immer noch im Haupt-Checkout aus.
657 * **`cwd` folgt Claude**: Das Feld `cwd` in der Hook-[Eingabe JSON](#common-input-fields) ist das Worktree-Root, nachdem Claude einen Worktree betritt, und das neue Verzeichnis, nachdem Claude `cd` ausführt. Lesen Sie es, wenn ein Hook wissen muss, in welchem Verzeichnis Claude arbeitet.
658</Note>
659
660Bevorzugen Sie [Exec-Form](#exec-form-and-shell-form) für jeden Hook, der auf einen Pfad-Platzhalter verweist. In Shell-Form wickeln Sie jeden Platzhalter in doppelte Anführungszeichen ein.
521 661
522<Tabs>662<Tabs>
523 <Tab title="Projekt-Skripte">663 <Tab title="Projekt-Skripte">
577 Hooks in Skills und Agents717 Hooks in Skills und Agents
578</h3>718</h3>
579 719
580Zusätzlich zu Einstellungsdateien und Plugins können Hooks direkt in [Skills](/docs/de/skills) und [Subagenten](/docs/de/sub-agents) mit Frontmatter definiert werden. Diese Hooks sind auf den Lebenszyklus der Komponente beschränkt und werden nur ausgeführt, wenn diese Komponente aktiv ist.720Zusätzlich zu Einstellungsdateien und Plugins können Hooks direkt in [Skills](/docs/de/skills) und [Subagenten](/docs/de/sub-agents) mit Frontmatter definiert werden, im gleichen Konfigurationsformat wie einstellungsbasierte Hooks. Wie lange Claude Code sie registriert hält, hängt von der Komponente ab:
581
582Alle Hook-Ereignisse werden unterstützt. Für Subagenten werden `Stop`-Hooks automatisch in `SubagentStop` konvertiert, da dies das Ereignis ist, das ausgelöst wird, wenn ein Subagent fertig ist.
583 721
584Hooks verwenden das gleiche Konfigurationsformat wie einstellungsbasierte Hooks, sind aber auf die Lebensdauer der Komponente beschränkt und werden bereinigt, wenn sie fertig ist.722* **Subagent-Hooks**: Claude Code führt sie nur aus, während dieser Subagent läuft, und entfernt sie, wenn er fertig ist. Claude Code konvertiert einen `Stop`-Hook hier zu `SubagentStop`, das Ereignis, das ausgelöst wird, wenn ein Subagent fertig ist.
723* **Skill-Hooks**: Claude Code registriert sie, wenn Sie oder Claude den Skill aufrufen, und führt sie für den Rest der Sitzung aus, auf Runden nach der eigenen Runde des Skills auch. Um Claude Code stattdessen einen Hook nach seiner ersten erfolgreichen Ausführung zu entfernen, setzen Sie [`once: true`](#common-fields) darauf.
585 724
586Dieser Skill definiert einen `PreToolUse`-Hook, der ein Sicherheitsvalidierungsskript vor jedem `Bash`-Befehl ausführt:725Dieser Skill definiert einen `PreToolUse`-Hook, der ein Sicherheitsvalidierungsskript vor jedem `Bash`-Befehl ausführt:
587 726
598---737---
599```738```
600 739
601Agents verwenden das gleiche Format in ihrem YAML-Frontmatter.740Subagenten verwenden das gleiche Format in ihrem YAML-Frontmatter.
741
742Frontmatter-Hooks in einem Projekt-Skill folgen der gleichen [Workspace-Trust-Regel wie Hooks in Einstellungsdateien](#workspace-trust). Claude Code registriert sie, wenn Sie oder Claude den Skill aufrufen, auch in einer `-p`-Ausführung in einem Ordner, dem Sie nicht vertraut haben.
743
744Frontmatter-Hooks in einem Projekt-Subagent werden nur ausgeführt, nachdem Sie den [Workspace-Trust-Dialog](/docs/de/permissions#project-allow-rules-and-workspace-trust) für den Ordner akzeptiert haben, aus dem die Agent-Datei stammt. Eine `-p`-Sitzung zählt nicht als Akzeptanz. [Was läuft, bevor Sie einem Ordner vertrauen](/docs/de/permissions#what-runs-before-you-trust-a-folder) vergleicht dies mit der Einstellungsdatei-Regel, und die Subagenten-Seite listet auf, [welche Scopes ausgenommen sind](/docs/de/sub-agents#hooks-in-subagent-frontmatter). Vor v2.1.218 konnten diese Hooks aus Ordnern ausgeführt werden, denen Sie nicht vertraut haben.
602 745
603<h3 id="the-/hooks-menu">746<h3 id="the-/hooks-menu">
604 Das Menü `/hooks`747 Das Menü `/hooks`
608 751
609Das Menü zeigt alle fünf Hook-Typen an: `command`, `prompt`, `agent`, `http` und `mcp_tool`. Jeder Hook ist mit einem `[type]`-Präfix und einer Quelle gekennzeichnet, die angibt, wo er definiert wurde:752Das Menü zeigt alle fünf Hook-Typen an: `command`, `prompt`, `agent`, `http` und `mcp_tool`. Jeder Hook ist mit einem `[type]`-Präfix und einer Quelle gekennzeichnet, die angibt, wo er definiert wurde:
610 753
611* `User`: aus `~/.claude/settings.json`754* `User Settings`: aus `~/.claude/settings.json`
612* `Project`: aus `.claude/settings.json`755* `Project Settings`: aus `.claude/settings.json`
613* `Local`: aus `.claude/settings.local.json`756* `Local Settings`: aus `.claude/settings.local.json`
614* `Plugin`: aus `hooks/hooks.json` eines Plugins757* `Plugin Hooks`: aus `hooks/hooks.json` eines Plugins
615* `Session`: in Speicher für die aktuelle Sitzung registriert758* `Session Hooks`: in Speicher für die aktuelle Sitzung registriert
616* `Built-in`: intern von Claude Code registriert
617 759
618Wenn Sie einen Hook auswählen, wird eine Detailansicht geöffnet, die sein Ereignis, Matcher, Typ, Quelldatei und den vollständigen Befehl, Prompt oder URL zeigt. Das Menü ist schreibgeschützt: Um Hooks hinzuzufügen, zu ändern oder zu entfernen, bearbeiten Sie die Einstellungs-JSON direkt oder bitten Sie Claude, die Änderung vorzunehmen.760Wenn Sie einen Hook auswählen, wird eine Detailansicht geöffnet, die sein Ereignis, Matcher, Typ, Quelldatei und den vollständigen Befehl, Prompt oder URL zeigt. Das Menü ist schreibgeschützt: Um Hooks hinzuzufügen, zu ändern oder zu entfernen, bearbeiten Sie die Einstellungs-JSON direkt oder bitten Sie Claude, die Änderung vorzunehmen.
619 761
623 765
624Um einen Hook zu entfernen, löschen Sie seinen Eintrag aus der Einstellungs-JSON-Datei.766Um einen Hook zu entfernen, löschen Sie seinen Eintrag aus der Einstellungs-JSON-Datei.
625 767
626Um alle Hooks vorübergehend zu deaktivieren, ohne sie zu entfernen, setzen Sie `"disableAllHooks": true` in Ihrer Einstellungsdatei. Es gibt keine Möglichkeit, einen einzelnen Hook zu deaktivieren, während er in der Konfiguration bleibt.768Um alle Hooks vorübergehend zu deaktivieren, ohne sie zu entfernen, setzen Sie `"disableAllHooks": true` in Ihrer Einstellungsdatei. Claude Code liest den Wert, der nach [Einstellungs-Vorrang](/docs/de/settings#settings-precedence) bleibt, daher überschreibt ein `"disableAllHooks": false` in der `.claude/settings.json` eines Projekts ein `true` in Ihren Benutzereinstellungen. Um Hooks für einen Durchlauf auszuschalten, egal was die Einstellungen des Projekts sagen, übergeben Sie `--settings '{"disableAllHooks": true}'`, was Vorrang vor Projekt- und lokalen Einstellungen hat. Es gibt keine Möglichkeit, einen einzelnen Hook zu deaktivieren, während er in der Konfiguration bleibt.
627 769
628Die Einstellung `disableAllHooks` respektiert die Hierarchie der verwalteten Einstellungen. Wenn ein Administrator Hooks durch verwaltete Richtlinieneinstellungen konfiguriert hat, kann `disableAllHooks`, das in Benutzer-, Projekt- oder lokalen Einstellungen gesetzt ist, diese verwalteten Hooks nicht deaktivieren. Nur `disableAllHooks`, das auf der Ebene der verwalteten Einstellungen gesetzt ist, kann verwaltete Hooks deaktivieren.770Die Einstellung `disableAllHooks` respektiert die Hierarchie der verwalteten Einstellungen. Wenn ein Administrator Hooks durch verwaltete Richtlinieneinstellungen konfiguriert hat, kann `disableAllHooks`, das in Benutzer-, Projekt- oder lokalen Einstellungen gesetzt ist, diese verwalteten Hooks nicht deaktivieren. Nur `disableAllHooks`, das auf der Ebene der verwalteten Einstellungen gesetzt ist, kann verwaltete Hooks deaktivieren. Für die vollständige Reichweite jeder Ebene siehe [`disableAllHooks`](/docs/de/settings-reference#disableallhooks).
629 771
630Direkte Bearbeitungen von Hooks in Einstellungsdateien werden normalerweise automatisch vom Datei-Watcher aufgegriffen.772Direkte Bearbeitungen von Hooks in Einstellungsdateien werden normalerweise automatisch vom Datei-Watcher aufgegriffen.
631 773
635 777
636Command-Hooks erhalten JSON-Daten über stdin und kommunizieren Ergebnisse über Exit-Codes, stdout und stderr. HTTP-Hooks erhalten die gleiche JSON als POST-Request-Body und kommunizieren Ergebnisse über den HTTP-Response-Body. Dieser Abschnitt behandelt Felder und Verhalten, die allen Ereignissen gemeinsam sind. Jeder Abschnitt eines Ereignisses unter [Hook-Ereignisse](#hook-events) enthält sein spezifisches Eingabeschema und Optionen zur Entscheidungskontrolle.778Command-Hooks erhalten JSON-Daten über stdin und kommunizieren Ergebnisse über Exit-Codes, stdout und stderr. HTTP-Hooks erhalten die gleiche JSON als POST-Request-Body und kommunizieren Ergebnisse über den HTTP-Response-Body. Dieser Abschnitt behandelt Felder und Verhalten, die allen Ereignissen gemeinsam sind. Jeder Abschnitt eines Ereignisses unter [Hook-Ereignisse](#hook-events) enthält sein spezifisches Eingabeschema und Optionen zur Entscheidungskontrolle.
637 779
638Auf macOS und Linux werden Command-Hooks seit v2.1.139 in ihrer eigenen Sitzung ohne steuerndes Terminal ausgeführt. Der Hook-Prozess und alle untergeordneten Prozesse können `/dev/tty` nicht öffnen oder Escape-Sequenzen direkt an die Claude Code-Benutzeroberfläche senden. Windows hat kein `/dev/tty`. Um eine Nachricht dem Benutzer auf jeder Plattform anzuzeigen, geben Sie [`systemMessage`](#json-output) in der JSON-Ausgabe zurück. Um eine Desktop-Benachrichtigung auszulösen, einen Fenstertitel zu setzen oder die Glocke zu läuten, geben Sie stattdessen [`terminalSequence`](#emit-terminal-notifications) zurück.780Auf macOS und Linux werden Command-Hooks in ihrer eigenen Sitzung ohne steuerndes Terminal ausgeführt. Der Hook-Prozess und alle untergeordneten Prozesse können `/dev/tty` nicht öffnen oder Escape-Sequenzen direkt an die Claude Code-Benutzeroberfläche senden. Windows hat kein `/dev/tty`.
781
782Um eine Nachricht dem Benutzer auf jeder Plattform anzuzeigen, geben Sie [`systemMessage`](#json-output) in der JSON-Ausgabe zurück. Einige Ereignisse verwerfen sie oder liefern sie an anderer Stelle, und jeder [Abschnitt eines Ereignisses](#hook-events) sagt, wo. Um eine Desktop-Benachrichtigung auszulösen, einen Fenstertitel zu setzen oder die Glocke zu läuten, geben Sie stattdessen [`terminalSequence`](#emit-terminal-notifications) zurück.
639 783
640<h3 id="common-input-fields">784<h3 id="common-input-fields">
641 Gemeinsame Eingabefelder785 Gemeinsame Eingabefelder
644Hook-Ereignisse erhalten diese Felder als JSON, zusätzlich zu ereignisspezifischen Feldern, die in jedem Abschnitt [Hook-Ereignis](#hook-events) dokumentiert sind. Für Command-Hooks kommt diese JSON über stdin an. Für HTTP-Hooks kommt sie als POST-Request-Body an.788Hook-Ereignisse erhalten diese Felder als JSON, zusätzlich zu ereignisspezifischen Feldern, die in jedem Abschnitt [Hook-Ereignis](#hook-events) dokumentiert sind. Für Command-Hooks kommt diese JSON über stdin an. Für HTTP-Hooks kommt sie als POST-Request-Body an.
645 789
646| Feld | Beschreibung |790| Feld | Beschreibung |
647| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |791| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
648| `session_id` | Aktuelle Sitzungs-ID |792| `session_id` | Aktuelle Sitzungs-ID |
649| `prompt_id` | UUID, die die aktuell verarbeitete Benutzereingabeaufforderung identifiziert. Entspricht dem [`prompt.id`-Attribut bei OpenTelemetry-Ereignissen](/docs/de/monitoring-usage#event-correlation-attributes), sodass Sie Hook-Ausgabe mit Telemetrie für eine einzelne Eingabeaufforderung korrelieren können. Nicht vorhanden, bis zur ersten Benutzereingabe. Erfordert Claude Code v2.1.196 oder später |793| `prompt_id` | UUID, die die aktuell verarbeitete Benutzereingabeaufforderung identifiziert. Entspricht dem [`prompt.id`-Attribut bei OpenTelemetry-Ereignissen](/docs/de/monitoring-usage#event-correlation-attributes), sodass Sie Hook-Ausgabe mit Telemetrie für eine einzelne Eingabeaufforderung korrelieren können. Nicht vorhanden, bis zur ersten Benutzereingabe. Erfordert Claude Code v2.1.196 oder später |
650| `transcript_path` | Pfad zur Gesprächs-JSON. Die Transkriptdatei wird asynchron geschrieben und kann der In-Memory-Konversation hinterherhinken, sodass sie möglicherweise noch nicht die neuesten Nachrichten des aktuellen Zugs enthält, wenn ein Hook ausgelöst wird. Hooks, die den endgültigen Assistententext des aktuellen Zugs benötigen, sollten `last_assistant_message` auf [Stop](#stop) und [SubagentStop](#subagentstop) verwenden, anstatt das Transkript zu lesen |794| `transcript_path` | Pfad zur Gesprächs-JSON. Die Transkriptdatei wird asynchron geschrieben und kann der In-Memory-Konversation hinterherhinken, sodass sie möglicherweise noch nicht die neuesten Nachrichten des aktuellen Zugs enthält, wenn ein Hook ausgelöst wird. Hooks, die den endgültigen Assistententext des aktuellen Zugs benötigen, sollten `last_assistant_message` auf [Stop](#stop) und [SubagentStop](#subagentstop) verwenden, anstatt das Transkript zu lesen |
651| `cwd` | Aktuelles Arbeitsverzeichnis, wenn der Hook aufgerufen wird |795| `cwd` | Aktuelles Arbeitsverzeichnis, wenn der Hook aufgerufen wird |
796| `scratchpad_dir` | Pfad zum Scratchpad-Verzeichnis der Sitzung, in dem Claude temporäre Arbeitsdateien speichert. Nicht vorhanden, wenn die Sitzung kein Scratchpad hat oder das Temp-Verzeichnis nicht verfügbar ist. Erfordert Claude Code v2.1.257 oder später |
652| `permission_mode` | Aktueller [Berechtigungsmodus](/docs/de/permissions#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` oder `"bypassPermissions"`. Der als **Manuell** bezeichnete Modus kommt als `"default"` an, nie als `"manual"`, sodass Skripte, die `"default"` abgleichen, weiterhin funktionieren. Nicht alle Ereignisse erhalten dieses Feld. Überprüfen Sie das JSON-Beispiel in jedem Abschnitt [Hook-Ereignis](#hook-events) |797| `permission_mode` | Aktueller [Berechtigungsmodus](/docs/de/permissions#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` oder `"bypassPermissions"`. Der als **Manuell** bezeichnete Modus kommt als `"default"` an, nie als `"manual"`, sodass Skripte, die `"default"` abgleichen, weiterhin funktionieren. Nicht alle Ereignisse erhalten dieses Feld. Überprüfen Sie das JSON-Beispiel in jedem Abschnitt [Hook-Ereignis](#hook-events) |
653| `effort` | Objekt mit einem `level`-Feld, das die aktive [Anstrengungsstufe](/docs/de/model-config#adjust-effort-level) für den Zug enthält: `"low"`, `"medium"`, `"high"`, `"xhigh"` oder `"max"`. Wenn die angeforderte Modell-Anstrengung das überschreitet, was das aktuelle Modell unterstützt, ist dies die herabgestufte Stufe, die das Modell tatsächlich verwendet hat. Ultracode ist keine separate Stufe und wird als `"xhigh"` gemeldet. Das Objekt entspricht dem [Statuszeilen](/docs/de/statusline#available-data)-Feld `effort`. Vorhanden für Ereignisse, die innerhalb eines Tool-Use-Kontexts ausgelöst werden, wie `PreToolUse`, `PostToolUse`, `Stop` und `SubagentStop`, wenn das aktuelle Modell den Anstrengungsparameter unterstützt. Die Stufe ist auch für Hook-Befehle und das Bash-Tool als die Umgebungsvariable `$CLAUDE_EFFORT` verfügbar. |798| `effort` | Objekt mit einem `level`-Feld, das die [Anstrengungsstufe](/docs/de/model-config#adjust-effort-level) enthält, die beim Ausführen des Hooks aktiv ist: `"low"`, `"medium"`, `"high"`, `"xhigh"` oder `"max"`. Wenn Sie eine Stufe setzen, die das aktive Modell nicht unterstützt, meldet `level` die Stufe, die Claude Code stattdessen ausgeführt hat; [Anstrengungsstufe anpassen](/docs/de/model-config#adjust-effort-level) sagt, wie es diese Stufe auswählt. Ultracode ist keine separate Stufe und wird als `"xhigh"` gemeldet. Das Objekt entspricht dem [Statuszeilen](/docs/de/statusline#available-data)-Feld `effort`. Vorhanden für Ereignisse, die innerhalb eines Tool-Use-Kontexts ausgelöst werden, wie `PreToolUse`, `PostToolUse`, `Stop` und `SubagentStop`, wenn das aktuelle Modell den Anstrengungsparameter unterstützt. Die Stufe ist auch für Hook-Befehle und das Bash-Tool als die Umgebungsvariable `$CLAUDE_EFFORT` verfügbar. |
654| `hook_event_name` | Name des ausgelösten Ereignisses |799| `hook_event_name` | Name des ausgelösten Ereignisses |
655 800
656Wenn mit `--agent` oder innerhalb eines Subagenten ausgeführt, sind zwei zusätzliche Felder enthalten:801Wenn mit `--agent` oder innerhalb eines Subagenten ausgeführt, sind zwei zusätzliche Felder enthalten:
657 802
658| Feld | Beschreibung |803| Feld | Beschreibung |
659| :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |804| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
660| `agent_id` | Eindeutige Kennung für den Subagenten. Nur vorhanden, wenn der Hook innerhalb eines Subagenten-Aufrufs ausgelöst wird. Verwenden Sie dies, um Subagenten-Hook-Aufrufe von Main-Thread-Aufrufen zu unterscheiden. |805| `agent_id` | Eindeutige Kennung für den Subagenten. Nur vorhanden, wenn der Hook innerhalb eines Subagenten-Aufrufs ausgelöst wird. Verwenden Sie dies, um Subagenten-Hook-Aufrufe von Main-Thread-Aufrufen zu unterscheiden. |
661| `agent_type` | Agent-Name (zum Beispiel `"Explore"` oder `"security-reviewer"`). Vorhanden, wenn die Sitzung `--agent` verwendet oder der Hook innerhalb eines Subagenten ausgelöst wird. Für Subagenten hat der Typ des Subagenten Vorrang vor dem `--agent`-Wert der Sitzung. Für [benutzerdefinierte Subagenten](/docs/de/sub-agents) ist dies das `name`-Feld aus dem Frontmatter des Agenten, nicht der Dateiname. Für Subagenten, die von einem [Plugin](/docs/de/plugins) bereitgestellt werden, ist dies die Plugin-bezogene Kennung wie `my-plugin:reviewer`, nicht der bloße Frontmatter-Name. Siehe [SubagentStart](#subagentstart), um zu erfahren, wie Sie einen Matcher gegen einen Plugin-bezogenen Namen schreiben. |806| `agent_type` | Agent-Name (zum Beispiel `"Explore"` oder `"security-reviewer"`). Vorhanden, wenn die Sitzung `--agent` verwendet oder der Hook innerhalb eines Subagenten ausgelöst wird. Für Subagenten hat der Typ des Subagenten Vorrang vor dem `--agent`-Wert der Sitzung. Siehe [SubagentStart](#subagentstart) für die Werte, die benutzerdefinierte und Plugin-Subagenten melden, und wie Sie einen Matcher gegen einen Plugin-bezogenen Namen schreiben. |
807
808Nur [`SessionStart`](#sessionstart)-Hooks können ein `model`-Feld erhalten, und Claude Code schließt es nicht immer ein. [`PreModelSwitch`](#premodelswitch) und [`PostModelSwitch`](#postmodelswitch)-Hooks erhalten stattdessen `from_model` und `to_model`, verwenden Sie also einen PostModelSwitch-Hook, um das Modell zu verfolgen, während es sich während einer Sitzung ändert.
662 809
663Nur [`SessionStart`](#sessionstart)-Hooks können ein `model`-Feld erhalten, und es ist nicht garantiert, dass es vorhanden ist. Es gibt keine `$CLAUDE_MODEL`-Umgebungsvariable. Ein Hook-Prozess erbt die übergeordnete Umgebung, sodass er `$ANTHROPIC_MODEL` lesen kann, wenn Sie sie in Ihrer Shell setzen, aber dieser Wert ändert sich nicht, wenn Sie während einer Sitzung mit `/model` Modelle wechseln. Ein Satz von Variablen wird nicht vererbt: Claude Code [entfernt `OTEL_*`-Exportervariablen aus jedem Unterprozess, den es spawnt](/docs/de/monitoring-usage#administrator-configuration), einschließlich Hooks.810Es gibt keine `$CLAUDE_MODEL`-Umgebungsvariable. Der Hook kann `$ANTHROPIC_MODEL` lesen, wenn Sie es in Ihrer Shell setzen, aber dieser Wert ändert sich nicht, wenn Sie während einer Sitzung mit `/model` Modelle wechseln.
811
812Ein Hook-Prozess erbt die übergeordnete Umgebung, abgesehen von den `OTEL_*`-Exportervariablen, die Claude Code [aus jedem Unterprozess entfernt, den es spawnt](/docs/de/monitoring-usage#administrator-configuration), und wenn [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/de/env-vars#variables) auf `1` gesetzt ist, die Variablen, die es entfernt.
664 813
665Zum Beispiel erhält ein `PreToolUse`-Hook für einen Bash-Befehl dies über stdin:814Zum Beispiel erhält ein `PreToolUse`-Hook für einen Bash-Befehl dies über stdin:
666 815
670 "prompt_id": "550e8400-e29b-41d4-a716-446655440000",819 "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
671 "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",820 "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
672 "cwd": "/home/user/my-project",821 "cwd": "/home/user/my-project",
822 "scratchpad_dir": "/tmp/claude-1000/-home-user-my-project/abc123/scratchpad",
673 "permission_mode": "default",823 "permission_mode": "default",
674 "hook_event_name": "PreToolUse",824 "hook_event_name": "PreToolUse",
675 "tool_name": "Bash",825 "tool_name": "Bash",
676 "tool_input": {826 "tool_input": {
677 "command": "npm test"827 "command": "npm test",
678 }828 "description": "Run test suite",
829 "timeout": 120000,
830 "run_in_background": false
831 },
832 "tool_use_id": "toolu_01ABC123..."
679}833}
680```834```
681 835
682Die Felder `tool_name` und `tool_input` sind ereignisspezifisch. Jeder Abschnitt [Hook-Ereignis](#hook-events) dokumentiert die zusätzlichen Felder für dieses Ereignis.836Die Felder `tool_name`, `tool_input` und `tool_use_id` sind ereignisspezifisch. Jeder Abschnitt [Hook-Ereignis](#hook-events) dokumentiert die zusätzlichen Felder für dieses Ereignis.
683 837
684<h3 id="exit-code-output">838<h3 id="exit-code-output">
685 Exit-Code-Ausgabe839 Exit-Code-Ausgabe
686</h3>840</h3>
687 841
688Der Exit-Code aus Ihrem Hook-Befehl teilt Claude Code mit, ob die Aktion fortgesetzt, blockiert oder ignoriert werden soll.842Der Exit-Code aus Ihrem Hook-Befehl teilt Claude Code mit, ob die Aktion fortgesetzt, blockiert oder ignoriert werden soll. Der Exit-Code wirkt nicht allein. Claude Code liest [JSON-Ausgabefelder](#json-output) von stdout bei jedem Exit-Code, nicht nur 0, und für Ereignisse, die das Standard-Entscheidungsmodell verwenden, wirkt ein analysiertes Objekt, das die Schema-Validierung besteht, neben dem Code. Exit 2's Blockierung ist das einzige Ergebnis, das JSON nicht überschreiben kann.
843
844Zwei Tabellen besitzen die ereignisspezifischen Ausnahmen: [Exit-Code-2-Verhalten pro Ereignis](#exit-code-2-behavior-per-event) sagt, was Exit-Codes für jedes Ereignis tun, und [Entscheidungskontrolle](#decision-control) sagt, welche Entscheidungsfelder jedes Ereignis berücksichtigt. Universelle Felder wie `systemMessage` funktionieren über die meisten Ereignisse hinweg und sind in der Tabelle [JSON-Ausgabe](#json-output) aufgelistet.
845
846<h4 id="exit-code-0">
847 Exit-Code 0
848</h4>
849
850Exit 0 bedeutet Erfolg und ist der beabsichtigte Exit-Code, wenn Sie JSON für strukturierte Kontrolle ausgeben.
851
852Für die meisten Ereignisse schreibt Claude Code stdout in das Debug-Log und zeigt es nicht im Transkript an. Die Ausnahmen sind `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart` und `PostModelSwitch`, wo Claude Code Plain-Text-stdout als Kontext hinzufügt, den Claude sehen und darauf reagieren kann.
689 853
690**Exit 0** bedeutet Erfolg. Claude Code analysiert stdout auf [JSON-Ausgabefelder](#json-output). JSON-Ausgabe wird nur bei Exit 0 verarbeitet. Für die meisten Ereignisse wird stdout in das Debug-Log geschrieben, aber nicht im Transkript angezeigt. Die Ausnahmen sind `UserPromptSubmit`, `UserPromptExpansion` und `SessionStart`, wo stdout als Kontext hinzugefügt wird, den Claude sehen und darauf reagieren kann.854Ob Claude Code Ihren stdout als [JSON-Ausgabe](#json-output) oder als Plain-Text liest, hängt davon ab, wie er beginnt und endet, wobei umgebender Whitespace ignoriert wird:
691 855
692**Exit 2** bedeutet ein blockierender Fehler. Claude Code ignoriert stdout und jede JSON darin. Stattdessen wird der stderr-Text an Claude als Fehlermeldung zurückgegeben. Die Auswirkung hängt vom Ereignis ab: `PreToolUse` blockiert den Tool-Aufruf, `UserPromptSubmit` lehnt den Prompt ab, und so weiter. Siehe [Exit-Code-2-Verhalten pro Ereignis](#exit-code-2-behavior-per-event) für die vollständige Liste.856* **Beginnt mit `{` und endet mit `}`**: Claude Code analysiert es als JSON. Wenn die Ausgabe zwei oder mehr Zeilen sind, die jeweils selbst als JSON analysiert werden, und keine Zeile ein [JSON-Ausgabe](#json-output)-Objekt ist, das ein Feld setzt, behandelt Claude Code die gesamte Ausgabe als Plain-Text. Wenn eine dieser Zeilen ein Feld setzt, ist die gesamte Ausgabe ein Parse-Fehler, der unten beschrieben wird.
857* **Beginnt mit `{` aber endet nicht mit `}`**: Claude Code behandelt es als Plain-Text.
858* **Beginnt mit etwas anderem**: Claude Code behandelt es als Plain-Text, ein JSON-Array oder eine zitierte JSON-Zeichenkette enthalten.
693 859
694**Jeder andere Exit-Code** ist ein nicht-blockierender Fehler für die meisten Hook-Ereignisse. Das Transkript zeigt eine `<hook name> hook error`-Benachrichtigung gefolgt von der ersten Zeile von stderr, damit Sie die Ursache ohne `--debug` identifizieren können. Die Ausführung wird fortgesetzt und der vollständige stderr wird in das Debug-Log geschrieben.860Für Ereignisse, die das Standard-Entscheidungsmodell verwenden, ist Exit 0 mit einem analysierten Objekt, das die Schema-Validierung nicht besteht, ein nicht-blockierender Fehler: die Aktion wird fortgesetzt, und das Transkript zeigt eine `<hook name> hook error`-Benachrichtigung mit der Validierungsmeldung. Das gleiche passiert bei jedem Exit-Code außer 2, während [Exit 2 immer noch blockiert](#exit-code-2).
695 861
696Zum Beispiel ein Hook-Befehlsskript, das gefährliche Bash-Befehle blockiert:862Für Ereignisse, die das Standard-Entscheidungsmodell verwenden, wenn Claude Code versucht, Ihren stdout als JSON zu analysieren und kann nicht, meldet es einen nicht-blockierenden Fehler bei jedem Exit-Code außer 2. Das Transkript zeigt eine `<hook name> hook error`-Benachrichtigung mit der Parse-Meldung. Bei den Ereignissen, die Plain-Text-stdout als Kontext hinzufügen, fügt Claude Code den Text nicht hinzu. Vor v2.1.248 behandelte Claude Code diesen stdout als Plain-Text.
863
864Stderr von einem Hook, der mit 0 beendet wird, geht nur in das Debug-Log, nie in das Transkript, und Claude sieht es nie. Um es selbst zu lesen, aktivieren Sie [Debug-Protokollierung](#debug-hooks). Um eine Warnung an Claude von einem `PostToolUse` oder `PostToolUseFailure`-Hook zu übermitteln, beenden Sie stattdessen mit 2, damit [Claude den stderr sieht](#exit-code-2-behavior-per-event), obwohl das Tool bereits ausgeführt wurde.
865
866<h4 id="exit-code-2">
867 Exit-Code 2
868</h4>
869
870Exit 2 bedeutet ein blockierender Fehler. Bei [Ereignissen, die blockieren können](#exit-code-2-behavior-per-event), blockiert Exit 2, unabhängig davon, ob Sie JSON ausgeben: selbst ein JSON `permissionDecision` von `"allow"` kann es nicht überschreiben. Claude Code liest immer noch alle gültigen [JSON-Ausgabe](#json-output) auf stdout. Bei `Elicitation` und `ElicitationResult` wird die `hookSpecificOutput` eines Exit-2-Hooks ignoriert.
871
872Die Blockierungsmeldung ist der Grund aus der Blockierungsentscheidung Ihres JSON, wenn es eine macht, und Ihr stderr-Text ansonsten. Was die Blockierung tut, variiert je nach Ereignis: `PreToolUse` blockiert den Tool-Aufruf, `UserPromptSubmit` lehnt den Prompt ab, und so weiter. [Exit-Code-2-Verhalten pro Ereignis](#exit-code-2-behavior-per-event) listet die Auswirkung für jedes Ereignis auf, und jeder Abschnitt eines Ereignisses sagt, wo die Meldung hingeht.
873
874Ein Hook, der mit 2 beendet wird, während er JSON ausgibt, das die [JSON-Ausgabe](#json-output)-Schema-Validierung nicht besteht, blockiert immer noch: Claude Code verwendet stderr als Blockierungsgrund und zeichnet den Validierungsfehler im Debug-Log auf. Vor v2.1.214 behandelte Claude Code diese Kombination als nicht-blockierenden Fehler und die Aktion wurde fortgesetzt.
875
876Dieses Skript blockiert `rm`-Befehle durch Beendigung mit 2 und lässt jeden anderen Befehl zum normalen Berechtigungsfluss:
697 877
698```bash theme={null}878```bash theme={null}
699#!/bin/bash879#!/bin/bash
700# Liest JSON-Eingabe von stdin, prüft den Befehl880# Liest JSON-Eingabe von stdin, prüft den Befehl
701command=$(jq -r '.tool_input.command' < /dev/stdin)881input=$(cat)
882command=$(jq -r '.tool_input.command' <<<"$input")
702 883
703if [[ "$command" == rm* ]]; then884if [[ "$command" == rm* ]]; then
704 echo "Blocked: rm commands are not allowed" >&2885 echo "Blocked: rm commands are not allowed" >&2
708exit 0 # Keine Entscheidung: der normale Berechtigungsfluss gilt889exit 0 # Keine Entscheidung: der normale Berechtigungsfluss gilt
709```890```
710 891
892<h4 id="other-exit-codes">
893 Andere Exit-Codes
894</h4>
895
896Jeder andere Exit-Code blockiert nicht allein für die meisten Hook-Ereignisse. Was passiert, hängt von Ihrem stdout ab:
897
898* Mit einem analysierten Objekt, das die Schema-Validierung besteht, für Ereignisse, die das Standard-Entscheidungsmodell verwenden, ignoriert Claude Code den Exit-Code und das JSON allein entscheidet das Ergebnis:
899 * Jedes Feld, das das Ereignis unterstützt, wird berücksichtigt, einschließlich `permissionDecision`, `additionalContext`, `updatedInput` und `systemMessage`, und der Hook wird nicht als Fehler gemeldet.
900 * [Entscheidungskontrolle](#decision-control) listet die Entscheidungsfelder pro Ereignis auf; universelle Felder wie `systemMessage` folgen der Tabelle [JSON-Ausgabe](#json-output).
901* Mit einem analysierten Objekt, das die Schema-Validierung nicht besteht, für Ereignisse, die das Standard-Entscheidungsmodell verwenden, ist es der gleiche nicht-blockierende Fehler wie [bei Exit 0](#exit-code-0): die Aktion wird fortgesetzt, und die `<hook name> hook error`-Benachrichtigung trägt die Validierungsmeldung.
902* Mit stdout, das Claude Code [versucht als JSON zu analysieren](#exit-code-0) und kann nicht, meldet Claude Code den gleichen nicht-blockierenden Fehler wie bei Exit 0 für Ereignisse, die das Standard-Entscheidungsmodell verwenden. Die Aktion wird fortgesetzt, und die Benachrichtigung trägt die Parse-Meldung.
903* Mit stdout, das Claude Code [als Plain-Text behandelt](#exit-code-0), oder mit leerem stdout, ist es ein nicht-blockierender Fehler für die meisten Hook-Ereignisse: die Aktion wird fortgesetzt, und das Transkript zeigt eine `<hook name> hook error`-Benachrichtigung gefolgt von der ersten Zeile von stderr, mit dem Präfix `Failed with non-blocking status code:`. Um den vollständigen stderr zu erfassen, aktivieren Sie [Debug-Protokollierung](#debug-hooks).
904
905Ereignisse außerhalb des Standard-Entscheidungsmodells behalten ihre eigenen Zeilen in der [ereignisspezifischen Tabelle](#exit-code-2-behavior-per-event): `WorktreeCreate` schlägt die Erstellung bei jedem Nicht-Null-Exit fehl, egal was Ihr JSON sagt, und Ereignisse, die Hook-Ausgabe vollständig verwerfen, wie `StopFailure`, ignorieren Ihr JSON bei jedem Exit-Code, abgesehen von Nebenwirkungsfeldern wie `terminalSequence`, die immer noch ausgelöst werden.
906
907Ein Hook, der nicht starten kann, landet im gleichen nicht-blockierenden Bucket. Wenn der Skriptpfad nicht existiert oder nicht ausführbar ist, beendet die Shell mit einem Code wie 127 und Sie sehen die gleiche Benachrichtigung mit der Meldung des Interpreters, zum Beispiel `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`. Für die meisten Hook-Ereignisse wird die Aktion fortgesetzt. Wenn Sie einen Policy-Hook einrichten, achten Sie auf diese Benachrichtigung bei seiner ersten Ausführung: ein Tippfehler im Pfad in `settings.json` lässt das Gate stillschweigend deaktiviert.
908
711<Warning>909<Warning>
712 Für die meisten Hook-Ereignisse blockiert nur Exit-Code 2 die Aktion. Claude Code behandelt Exit-Code 1 als nicht-blockierenden Fehler und setzt die Aktion fort, obwohl 1 der konventionelle Unix-Fehlercode ist. Wenn Ihr Hook eine Richtlinie durchsetzen soll, verwenden Sie `exit 2`. Die Ausnahme ist `WorktreeCreate`, wo jeder Nicht-Null-Exit-Code die Worktree-Erstellung abbricht.910 Für die meisten Hook-Ereignisse ist Exit-Code 2 der einzige Exit-Code, der allein durch den Code blockiert. Ohne gültiges JSON auf stdout behandelt Claude Code Exit-Code 1 als nicht-blockierenden Fehler und setzt die Aktion fort, obwohl 1 der konventionelle Unix-Fehlercode ist. Wenn Ihr Hook eine Richtlinie durchsetzen soll, verwenden Sie `exit 2`. Die Worktree-Ereignisse unterscheiden sich: jeder Nicht-Null-Exit-Code von `WorktreeCreate` bricht die Worktree-Erstellung ab, und jeder Nicht-Null-Exit-Code von `WorktreeRemove` lässt die Worktree-Entfernung fehlschlagen, wenn das Verzeichnis danach noch existiert.
713</Warning>911</Warning>
714 912
913<h4 id="timeouts">
914 Timeouts
915</h4>
916
917Abgesehen von einem Command-Hook, den Sie mit [`async: true`](#run-hooks-in-the-background) ausführen, bricht Claude Code einen `command`, `http` oder `mcp_tool`-Hook ab, der sein [`timeout`](#common-fields) erreicht, verwirft die Ausgabe des Hooks, sodass bei den meisten Ereignissen ein abgelaufener Hook keine Entscheidung rendert.
918
919Bei [`PreModelSwitch`](#premodelswitch) blockiert ein Hook, der bei seinem Timeout abgebrochen wird, den Modellwechsel. Bei `PreToolUse` unterscheiden sich die beiden Hook-Familien:
920
921* Ein abgelaufener `command`, `http` oder `mcp_tool`-Hook blockiert den Tool-Aufruf nicht. Der Aufruf wird durch den normalen [Berechtigungsfluss](/docs/de/permissions) fortgesetzt, verlassen Sie sich also nicht auf einen steckengebliebenen Hook, um als Gate zu fungieren.
922* Ein [Agent SDK-Callback-Hook](/docs/de/agent-sdk/hooks), der sein Timeout überschreitet, [blockiert den Tool-Aufruf](#pretooluse).
923
715<h4 id="exit-code-2-behavior-per-event">924<h4 id="exit-code-2-behavior-per-event">
716 Exit-Code-2-Verhalten pro Ereignis925 Exit-Code-2-Verhalten pro Ereignis
717</h4>926</h4>
719Exit-Code 2 ist die Art, wie ein Hook signalisiert „Stopp, mach das nicht." Die Auswirkung hängt vom Ereignis ab, da einige Ereignisse Aktionen darstellen, die blockiert werden können (wie ein Tool-Aufruf, der noch nicht stattgefunden hat), und andere Dinge darstellen, die bereits passiert sind oder nicht verhindert werden können.928Exit-Code 2 ist die Art, wie ein Hook signalisiert „Stopp, mach das nicht." Die Auswirkung hängt vom Ereignis ab, da einige Ereignisse Aktionen darstellen, die blockiert werden können (wie ein Tool-Aufruf, der noch nicht stattgefunden hat), und andere Dinge darstellen, die bereits passiert sind oder nicht verhindert werden können.
720 929
721| Hook-Ereignis | Kann blockiert werden? | Was passiert bei Exit 2 |930| Hook-Ereignis | Kann blockiert werden? | Was passiert bei Exit 2 |
722| :-------------------- | :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |931| :-------------------- | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
723| `PreToolUse` | Ja | Blockiert den Tool-Aufruf |932| `PreToolUse` | Ja | Blockiert den Tool-Aufruf |
724| `PermissionRequest` | Ja | Verweigert die Berechtigung |933| `PermissionRequest` | Nein | Exit-Code 2 wird für dieses Ereignis nicht berücksichtigt und der Berechtigungsfluss wird unverändert fortgesetzt. Verweigern Sie stattdessen durch das [`decision`-Objekt](#permissionrequest-decision-control) |
725| `UserPromptSubmit` | Ja | Blockiert die Prompt-Verarbeitung und löscht den Prompt |934| `UserPromptSubmit` | Ja | Blockiert die Prompt-Verarbeitung und löscht den Prompt |
726| `UserPromptExpansion` | Ja | Blockiert die Erweiterung |935| `UserPromptExpansion` | Ja | Blockiert die Erweiterung |
727| `Stop` | Ja | Verhindert, dass Claude stoppt, setzt das Gespräch fort |936| `Stop` | Ja | Verhindert, dass Claude stoppt, setzt das Gespräch fort |
730| `TaskCreated` | Ja | Rollback der Aufgabenerstellung |939| `TaskCreated` | Ja | Rollback der Aufgabenerstellung |
731| `TaskCompleted` | Ja | Verhindert, dass die Aufgabe als abgeschlossen markiert wird |940| `TaskCompleted` | Ja | Verhindert, dass die Aufgabe als abgeschlossen markiert wird |
732| `ConfigChange` | Ja | Blockiert die Konfigurationsänderung von der Anwendung (außer `policy_settings`) |941| `ConfigChange` | Ja | Blockiert die Konfigurationsänderung von der Anwendung (außer `policy_settings`) |
733| `StopFailure` | Nein | Ausgabe und Exit-Code werden ignoriert |942| `StopFailure` | Nein | Ausgabe und Exit-Code werden ignoriert, außer `terminalSequence` |
734| `PostToolUse` | Nein | Zeigt stderr Claude an; das Tool wurde bereits ausgeführt |943| `PostToolUse` | Nein | Zeigt stderr Claude an; das Tool wurde bereits ausgeführt |
735| `PostToolUseFailure` | Nein | Zeigt stderr Claude an; das Tool ist bereits fehlgeschlagen |944| `PostToolUseFailure` | Nein | Zeigt stderr Claude an; das Tool ist bereits fehlgeschlagen |
736| `PostToolBatch` | Ja | Stoppt die agentengesteuerte Schleife vor dem nächsten Modellaufruf |945| `PostToolBatch` | Ja | Stoppt die agentengesteuerte Schleife vor dem nächsten Modellaufruf |
737| `PermissionDenied` | Nein | Exit-Code und stderr werden ignoriert, da die Ablehnung bereits erfolgt ist. Verwenden Sie JSON `hookSpecificOutput.retry: true`, um dem Modell zu sagen, dass es möglicherweise erneut versuchen kann |946| `PermissionDenied` | Nein | Exit-Code und stderr werden ignoriert, da die Ablehnung bereits erfolgt ist. Verwenden Sie JSON `hookSpecificOutput.retry: true`, um dem Modell zu sagen, dass es möglicherweise erneut versuchen kann; Claude Code ignoriert `retry: true` für [Ablehnungen ohne Urteil](#permissiondenied-decision-control) |
738| `Notification` | Nein | Zeigt stderr nur dem Benutzer an |947| `Notification` | Nein | Exit-Code und stderr werden ignoriert |
739| `SubagentStart` | Nein | Zeigt stderr nur dem Benutzer an |948| `SubagentStart` | Nein | Zeigt stderr nur dem Benutzer an |
740| `SessionStart` | Nein | Zeigt stderr nur dem Benutzer an |949| `SessionStart` | Nein | Zeigt stderr nur dem Benutzer an |
741| `Setup` | Nein | Zeigt stderr nur dem Benutzer an |950| `Setup` | Nein | Exit-Code und stderr werden ignoriert |
742| `SessionEnd` | Nein | Zeigt stderr nur dem Benutzer an |951| `SessionEnd` | Nein | Zeigt stderr nur dem Benutzer an |
743| `CwdChanged` | Nein | Zeigt stderr nur dem Benutzer an |952| `CwdChanged` | Nein | Zeigt stderr nur dem Benutzer an |
953| `DirectoryAdded` | Nein | Stderr geht in das Debug-Log; das Verzeichnis ist bereits hinzugefügt |
744| `FileChanged` | Nein | Zeigt stderr nur dem Benutzer an |954| `FileChanged` | Nein | Zeigt stderr nur dem Benutzer an |
745| `PreCompact` | Ja | Blockiert die Komprimierung |955| `PreCompact` | Ja | Blockiert die Komprimierung |
746| `PostCompact` | Nein | Zeigt stderr nur dem Benutzer an |956| `PostCompact` | Nein | Zeigt stderr nur dem Benutzer an |
957| `PreModelSwitch` | Ja | Blockiert den Modellwechsel und zeigt stderr dem Benutzer an |
958| `PostModelSwitch` | Nein | Zeigt stderr nur dem Benutzer an; das Modell hat bereits gewechselt |
747| `Elicitation` | Ja | Verweigert die Elicitation |959| `Elicitation` | Ja | Verweigert die Elicitation |
748| `ElicitationResult` | Ja | Blockiert die Antwort (Aktion wird Ablehnung) |960| `ElicitationResult` | Ja | Blockiert die Antwort (Aktion wird Ablehnung) |
749| `WorktreeCreate` | Ja | Jeder Nicht-Null-Exit-Code führt zu Fehler bei der Worktree-Erstellung |961| `WorktreeCreate` | Ja | Jeder Nicht-Null-Exit-Code führt zu Fehler bei der Worktree-Erstellung |
750| `WorktreeRemove` | Nein | Fehler werden nur im Debug-Modus protokolliert |962| `WorktreeRemove` | Ja | Jeder Nicht-Null-Exit-Code lässt die Worktree-Entfernung fehlschlagen, wenn das Verzeichnis danach noch existiert. Siehe [WorktreeRemove](#worktreeremove) für das, was mit dem Verzeichnis passiert |
751| `InstructionsLoaded` | Nein | Exit-Code wird ignoriert |963| `InstructionsLoaded` | Nein | Exit-Code wird ignoriert |
752| `MessageDisplay` | Nein | Der ursprüngliche Text wird angezeigt |964| `MessageDisplay` | Nein | Der ursprüngliche Text wird angezeigt |
753 965
754Für `SessionStart`, `Setup` und `SubagentStart` wird der Exit-Code-2-stderr im Transkript als `<hook name> hook error`-Benachrichtigung dargestellt, auf die gleiche Weise wie ein [nicht-blockierender Fehler](#exit-code-output). Claude sieht ihn nicht, und die Sitzung oder der Subagent wird fortgesetzt. Für `SubagentStart` wird die Benachrichtigung im eigenen Transkript des Subagenten angezeigt, nicht im übergeordneten Gespräch.966Für `SessionStart`, `SubagentStart` und `PostModelSwitch` rendert Claude Code den Exit-Code-2-stderr im Transkript als `<hook name> hook error`-Benachrichtigung, auf die gleiche Weise wie es einen [nicht-blockierenden Fehler](#exit-code-output) rendert. Claude sieht es nicht, und die Sitzung oder der Subagent wird fortgesetzt. Für `SubagentStart` wird die Benachrichtigung im eigenen Transkript des Subagenten angezeigt, nicht im übergeordneten Gespräch.
755
756Ab Claude Code v2.1.199 zeigen `SessionStart`, `Setup` und `SubagentStart` Exit-Code-2-stderr im Transkript an. Frühere Versionen schrieben es nur in das Debug-Log.
757 967
758<h3 id="http-response-handling">968<h3 id="http-response-handling">
759 HTTP-Response-Behandlung969 HTTP-Response-Behandlung
760</h3>970</h3>
761 971
762HTTP-Hooks verwenden HTTP-Statuscodes und Response-Bodies anstelle von Exit-Codes und stdout:972HTTP-Hooks verwenden HTTP-Statuscodes und Response-Bodies anstelle von Exit-Codes und stdout. Die Ergebnisse unten gelten für die meisten Ereignisse; ein Ereignis mit seinem eigenen Fehlervertrag in der [ereignisspezifischen Tabelle](#exit-code-2-behavior-per-event), wie `WorktreeCreate`, wendet diesen Vertrag auch auf einen fehlgeschlagenen HTTP-Hook an:
763 973
764* **2xx mit leerem Body**: Erfolg, äquivalent zu Exit-Code 0 ohne Ausgabe974* **2xx mit leerem Body**: Erfolg, äquivalent zu Exit-Code 0 ohne Ausgabe
765* **2xx mit Plain-Text-Body**: Erfolg, der Text wird als Kontext hinzugefügt975* **2xx mit JSON-Objekt-Body**: analysiert mit dem gleichen [JSON-Ausgabe](#json-output)-Schema wie Command-Hooks. Ein Body, der die Schema-Validierung nicht besteht, ist ein nicht-blockierender Fehler
766* **2xx mit JSON-Body**: Erfolg, analysiert mit dem gleichen [JSON-Ausgabe](#json-output)-Schema wie Command-Hooks976* **2xx mit jedem anderen Body, wie Plain-Text**: nicht-blockierender Fehler, behandelt wie ein Nicht-2xx-Status. Claude Code fügt den Text nicht zu Claudes Kontext hinzu
767* **Nicht-2xx-Status**: Nicht-blockierender Fehler, Ausführung wird fortgesetzt977* **Nicht-2xx-Status**: nicht-blockierender Fehler, Ausführung wird fortgesetzt
768* **Verbindungsfehler oder Timeout**: Nicht-blockierender Fehler, Ausführung wird fortgesetzt978* **Verbindungsfehler**: nicht-blockierender Fehler, Ausführung wird fortgesetzt
979* **Timeout**: der Hook wird abgebrochen, wie unter [Timeouts](#timeouts) beschrieben
769 980
770Im Gegensatz zu Command-Hooks können HTTP-Hooks nicht allein durch Statuscodes einen blockierenden Fehler signalisieren. Um einen Tool-Aufruf zu blockieren oder eine Berechtigung zu verweigern, geben Sie eine 2xx-Antwort mit einem JSON-Body zurück, der die entsprechenden Entscheidungsfelder enthält.981Im Gegensatz zu Command-Hooks können HTTP-Hooks nicht allein durch Statuscodes einen blockierenden Fehler signalisieren. Um einen Tool-Aufruf zu blockieren oder eine Berechtigung zu verweigern, geben Sie eine 2xx-Antwort mit einem JSON-Body zurück, der die entsprechenden Entscheidungsfelder enthält.
771 982
773 JSON-Ausgabe984 JSON-Ausgabe
774</h3>985</h3>
775 986
776Exit-Codes ermöglichen es Ihnen, zuzulassen oder zu blockieren, aber JSON-Ausgabe gibt Ihnen eine feinere Kontrolle. Anstatt mit Code 2 zu beenden, um zu blockieren, beenden Sie mit 0 und geben Sie ein JSON-Objekt auf stdout aus. Claude Code liest spezifische Felder aus diesem JSON, um das Verhalten zu steuern, einschließlich [Entscheidungskontrolle](#decision-control) zum Blockieren, Zulassen oder Eskalieren an den Benutzer.987Exit-Codes ermöglichen es Ihnen nur zu blockieren oder stillschweigend zu sein, aber JSON-Ausgabe gibt Ihnen eine feinere Kontrolle. Anstatt mit Code 2 zu beenden, um zu blockieren, beenden Sie mit 0 und geben Sie ein JSON-Objekt auf stdout aus. Claude Code liest spezifische Felder aus diesem JSON, um das Verhalten zu steuern, einschließlich [Entscheidungskontrolle](#decision-control) zum Blockieren, Zulassen oder Eskalieren an den Benutzer.
777 988
778<Note>989<Note>
779 Sie müssen einen Ansatz pro Hook wählen, nicht beide: Verwenden Sie entweder Exit-Codes allein zum Signalisieren, oder beenden Sie mit 0 und geben Sie JSON für strukturierte Kontrolle aus. Claude Code verarbeitet JSON nur bei Exit 0. Wenn Sie mit 2 beenden, wird jede JSON ignoriert.990 Wählen Sie einen Ansatz pro Hook: verwenden Sie entweder Exit-Codes allein zum Signalisieren, oder beenden Sie mit 0 und geben Sie JSON für strukturierte Kontrolle aus. Wenn Sie sie mischen, behält Exit 2 seine [Blockierungsauswirkung](#exit-code-2-behavior-per-event), und Claude Code liest immer noch die JSON-Felder, mit der einen Elicitation-Ausnahme, die unter [Exit-Code 2](#exit-code-2) vermerkt ist.
780</Note>991</Note>
781 992
782Die stdout Ihres Hooks darf nur das JSON-Objekt enthalten. Wenn Ihr Shell-Profil beim Start Text ausgibt, kann dies die JSON-Analyse beeinträchtigen. Siehe [JSON-Validierung fehlgeschlagen](/docs/de/hooks-guide#json-validation-failed) in der Fehlerbehebungsanleitung.993Der stdout Ihres Hooks darf nur das JSON-Objekt enthalten. Wenn Ihr Shell-Profil beim Start Text ausgibt, kann dies die JSON-Analyse beeinträchtigen. Siehe [Hook-JSON hat keine Auswirkung](/docs/de/hooks-guide#hook-json-has-no-effect) in der Fehlerbehebungsanleitung.
994
995Die Strings `additionalContext`, `systemMessage` und `initialUserMessage` eines Hooks sowie sein Plain-stdout sind auf 10.000 Zeichen begrenzt:
783 996
784Hook-Ausgabe-Strings, einschließlich `additionalContext`, `systemMessage` und Plain-stdout, sind auf 10.000 Zeichen begrenzt. Ausgabe, die dieses Limit überschreitet, wird in einer Datei gespeichert und durch eine Vorschau und einen Dateipfad ersetzt, auf die gleiche Weise wie große Tool-Ergebnisse behandelt werden.997* **Umfang**: Claude Code misst jeden String für sich allein, auch wenn mehrere Hooks für das gleiche Ereignis ausgeführt werden. Für JSON-Ausgabe wird jedes Feld separat gemessen; Plain-stdout wird als Ganzes gemessen.
998* **Über dem Limit**: Claude Code speichert die Ausgabe in einer Datei im Sitzungsverzeichnis und ersetzt sie durch den Dateipfad und eine Vorschau von bis zu den ersten 2.000 Zeichen. Ein großes gültiges Bash-Ergebnis wird auf die gleiche Weise behandelt, wie unter [Ausgabelimits](/docs/de/tools-reference#output-limits) beschrieben. Im Gegensatz zu dieser Bash-Obergrenze hat diese Obergrenze keine Einstellung oder Umgebungsvariable, um sie zu erhöhen.
999* **Datei lesen**: Claude Code fordert Claude nicht auf, die Datei zu lesen, daher halten Sie alles, das Claude immer sehen muss, innerhalb der Obergrenze.
785 1000
786Das JSON-Objekt unterstützt drei Arten von Feldern:1001Das JSON-Objekt unterstützt drei Arten von Feldern:
787 1002
788* **Universelle Felder** wie `continue` funktionieren über alle Ereignisse hinweg. Diese sind in der Tabelle unten aufgelistet.1003* **Universelle Felder** wie `continue` sind in der Tabelle unten aufgelistet. Jedes Ereignis akzeptiert sie, aber einige Ereignisse verwerfen sie oder liefern `systemMessage` an anderer Stelle als dem Transkript. Jeder Abschnitt eines Ereignisses sagt so. `terminalSequence` funktioniert auch auf diesen Ereignissen, mit den Ausnahmen, die unter [Terminal-Benachrichtigungen ausgeben](#emit-terminal-notifications) aufgelistet sind.
789* **Top-Level `decision` und `reason`** werden von einigen Ereignissen verwendet, um zu blockieren oder Feedback zu geben.1004* **Top-Level `decision` und `reason`** werden von einigen Ereignissen verwendet, um zu blockieren oder Feedback zu geben.
790* **`hookSpecificOutput`** ist ein verschachteltes Objekt für Ereignisse, die reichere Kontrolle benötigen. Es erfordert ein `hookEventName`-Feld, das auf den Ereignisnamen gesetzt ist.1005* **`hookSpecificOutput`** ist ein verschachteltes Objekt für Ereignisse, die reichere Kontrolle benötigen. Es erfordert ein `hookEventName`-Feld, das auf den Ereignisnamen gesetzt ist.
791 1006
792| Feld | Standard | Beschreibung |1007| Feld | Standard | Beschreibung |
793| :----------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1008| :----------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
794| `continue` | `true` | Wenn `false`, stoppt Claude die Verarbeitung vollständig, nachdem der Hook ausgeführt wurde. Hat Vorrang vor allen ereignisspezifischen Entscheidungsfeldern |1009| `continue` | `true` | Wenn `false`, stoppt Claude die Verarbeitung vollständig, nachdem der Hook ausgeführt wurde. Hat Vorrang vor allen ereignisspezifischen Entscheidungsfeldern |
795| `stopReason` | keine | Nachricht, die dem Benutzer angezeigt wird, wenn `continue` `false` ist. Wird Claude nicht angezeigt |1010| `stopReason` | keine | Nachricht, die dem Benutzer angezeigt wird, wenn `continue` `false` ist. Sie bleibt in der Konversation, sodass Claude sie sieht, wenn die Konversation fortgesetzt wird |
796| `suppressOutput` | `false` | Wenn `true`, verbirgt stdout aus dem Transkript. Stdout wird weiterhin im Debug-Log angezeigt |1011| `suppressOutput` | `false` | Hat keine Auswirkung: Claude Code akzeptiert das Feld, aber handelt nicht danach. Der stdout eines erfolgreichen Hooks wird nie im Transkript angezeigt und wird im Debug-Log aufgezeichnet |
797| `systemMessage` | keine | Warnmeldung, die dem Benutzer angezeigt wird |1012| `systemMessage` | keine | Warnmeldung, die dem Benutzer angezeigt wird. In [Agent SDK](/docs/de/agent-sdk/overview) und [`--output-format stream-json`](/docs/de/headless)-Ausgabe kann es als [`SDKInformationalMessage`](/docs/de/agent-sdk/typescript#sdkinformationalmessage) ankommen |
798| `terminalSequence` | keine | Eine Terminal-Escape-Sequenz, die Claude Code in Ihrem Namen ausgeben soll, wie eine Desktop-Benachrichtigung, ein Fenstertitel oder eine Glocke. Beschränkt auf OSC `0`/`1`/`2`/`9`/`99`/`777` und BEL. Wenn der Wert etwas außerhalb der Zulassungsliste enthält, wird das Feld ignoriert. Verwenden Sie dies anstelle des Schreibens zu `/dev/tty`, das für Hooks nicht verfügbar ist |1013| `terminalSequence` | keine | Eine Terminal-Escape-Sequenz, die Claude Code in Ihrem Namen ausgeben soll, wie eine Desktop-Benachrichtigung, ein Fenstertitel oder eine Glocke. Beschränkt auf OSC `0`/`1`/`2`/`9`/`99`/`777` und BEL. Wenn der Wert etwas außerhalb der Zulassungsliste enthält, wird das Feld ignoriert. Verwenden Sie dies anstelle des Schreibens zu `/dev/tty`, das für Hooks nicht verfügbar ist |
799 1014
800Um Claude unabhängig vom Ereignistyp vollständig zu stoppen:1015Um Claude vollständig zu stoppen:
801 1016
802```json theme={null}1017```json theme={null}
803{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }1018{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }
804```1019```
805 1020
1021Für `PreToolUse` und `PostToolUse`-Hooks gilt der Stopp auch, wenn der Tool-Aufruf fehlschlägt oder abgeschlossen wird, während Claude immer noch eine Antwort streamt.
1022
806<h4 id="emit-terminal-notifications">1023<h4 id="emit-terminal-notifications">
807 Terminal-Benachrichtigungen ausgeben1024 Terminal-Benachrichtigungen ausgeben
808</h4>1025</h4>
809 1026
810Das Feld `terminalSequence` erfordert Claude Code v2.1.141 oder später.
811
812Hooks werden ohne steuerndes Terminal ausgeführt, daher schlägt das direkte Schreiben von Escape-Sequenzen zu `/dev/tty` fehl. Geben Sie stattdessen die Escape-Sequenz im Feld `terminalSequence` zurück und Claude Code gibt sie für Sie über seinen eigenen Terminal-Schreibpfad aus. Dies ist race-frei, funktioniert innerhalb von tmux und GNU screen und funktioniert unter Windows, wo es kein `/dev/tty` gibt.1027Hooks werden ohne steuerndes Terminal ausgeführt, daher schlägt das direkte Schreiben von Escape-Sequenzen zu `/dev/tty` fehl. Geben Sie stattdessen die Escape-Sequenz im Feld `terminalSequence` zurück und Claude Code gibt sie für Sie über seinen eigenen Terminal-Schreibpfad aus. Dies ist race-frei, funktioniert innerhalb von tmux und GNU screen und funktioniert unter Windows, wo es kein `/dev/tty` gibt.
813 1028
814Das Feld akzeptiert einen String aus einer oder mehreren zugelassenen Escape-Sequenzen:1029Das Feld akzeptiert einen String aus einer oder mehreren zugelassenen Escape-Sequenzen:
821 1036
822Sequenzen können mit BEL oder mit ST beendet werden. Alles außerhalb der Zulassungsliste, einschließlich CSI-Cursor- und Farbsequenzen, OSC-Palettensequenzen, OSC-8-Hyperlinks, OSC-52-Zwischenablage-Schreibvorgänge und OSC-1337, wird abgelehnt und das Feld wird ignoriert.1037Sequenzen können mit BEL oder mit ST beendet werden. Alles außerhalb der Zulassungsliste, einschließlich CSI-Cursor- und Farbsequenzen, OSC-Palettensequenzen, OSC-8-Hyperlinks, OSC-52-Zwischenablage-Schreibvorgänge und OSC-1337, wird abgelehnt und das Feld wird ignoriert.
823 1038
824Das folgende Beispiel löst eine Desktop-Benachrichtigung aus einem `Notification`-Hook aus. Die Escape-Sequenz wird mit `printf`-Oktalescapes erstellt, sodass die Steuerbytes niemals auf der Shell-Befehlszeile erscheinen, und `jq -n --arg` erstellt die JSON-Ausgabe, sodass Anführungszeichen, Backslashes und Zeilenumbrüche in der Benachrichtigungsmeldung korrekt escaped werden:1039Claude Code gibt die Sequenz selbst aus, wenn es die Ausgabe Ihres Hooks verarbeitet, sodass das Feld bei Ereignissen funktioniert, die `systemMessage` und `continue` verwerfen, wie `Notification` und `StopFailure`. Es hat zwei Limits:
1040
1041* Claude Code gibt die Sequenz nur in einer interaktiven Sitzung aus, und nur während seine Benutzeroberfläche auf dem Bildschirm ist. Im nicht-interaktiven Modus mit dem `-p`-Flag und im Agent SDK ignoriert es das Feld.
1042* Ein `WorktreeCreate`-Command-Hook kann kein JSON zurückgeben, da Claude Code seinen stdout als Worktree-Pfad liest. Ein HTTP-`WorktreeCreate`-Hook gibt JSON zurück und kann das Feld enthalten.
1043
1044Das Beispiel unten löst eine Desktop-Benachrichtigung von einem `Notification`-Hook aus. Die Escape-Sequenz wird mit `printf`-Oktalescapes erstellt, sodass die Steuerbytes nie auf der Shell-Befehlszeile erscheinen, und `jq -n --arg` erstellt die JSON-Ausgabe, sodass Anführungszeichen, Backslashes und Zeilenumbrüche in der Benachrichtigungsmeldung korrekt escaped werden:
825 1045
826```bash theme={null}1046```bash theme={null}
827#!/bin/bash1047#!/bin/bash
828# Notification-Hook: Ping des Desktops, wenn Claude Code Aufmerksamkeit benötigt.1048# Notification-Hook: Ping des Desktops, wenn Claude Code Aufmerksamkeit benötigt.
829input=$(cat)1049input=$(cat)
830title="Claude Code'1050title="Claude Code"
831body=$(jq -r '.message // 'Needs your attention"' <<<"$input")1051body=$(jq -r '.message // "Needs your attention"' <<<"$input")
832seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")1052seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
833jq -nc --arg seq "$seq" '{terminalSequence: $seq}'1053jq -nc --arg seq "$seq" '{terminalSequence: $seq}'
834```1054```
835 1055
836Die Form `{ "terminalSequence": "..." }` ist die gleiche aus jeder Shell oder Sprache. Unter Windows erstellen Sie die Escape-Zeichenkette in PowerShell oder einem Skript und geben das gleiche JSON-Objekt aus.1056Die Form `{ "terminalSequence": "..." }` ist die gleiche aus jeder Shell oder Sprache.
837
838<Note>
839 `terminalSequence` ist der unterstützte Ersatz für Hooks, die zuvor Escape-Sequenzen direkt zu `/dev/tty` schrieben. Die Zulassungsliste ist auf Sequenzen beschränkt, die den Cursor nicht bewegen oder Farben ändern können, sodass ein Hook niemals eine On-Screen-Eingabeaufforderung beschädigen kann.
840</Note>
841 1057
842<h4 id="add-context-for-claude">1058<h4 id="add-context-for-claude">
843 Kontext für Claude hinzufügen1059 Kontext für Claude hinzufügen
858 1074
859Wo die Erinnerung angezeigt wird, hängt vom Ereignis ab:1075Wo die Erinnerung angezeigt wird, hängt vom Ereignis ab:
860 1076
861* [SessionStart](#sessionstart), [Setup](#setup) und [SubagentStart](#subagentstart): am Anfang des Gesprächs, vor der ersten Eingabeaufforderung1077* [SessionStart](#sessionstart) und [SubagentStart](#subagentstart): am Anfang der Konversation, vor der ersten Eingabeaufforderung
862* [UserPromptSubmit](#userpromptsubmit) und [UserPromptExpansion](#userpromptexpansion): neben der eingereichten Eingabeaufforderung1078* [UserPromptSubmit](#userpromptsubmit) und [UserPromptExpansion](#userpromptexpansion): neben der eingereichten Eingabeaufforderung
863* [PreToolUse](#pretooluse), [PostToolUse](#posttooluse), [PostToolUseFailure](#posttoolusefailure) und [PostToolBatch](#posttoolbatch): neben dem Tool-Ergebnis1079* [PreToolUse](#pretooluse), [PostToolUse](#posttooluse), [PostToolUseFailure](#posttoolusefailure) und [PostToolBatch](#posttoolbatch): neben dem Tool-Ergebnis
864* [Stop](#stop) und [SubagentStop](#subagentstop): am Ende des Zugs. Das Gespräch wird fortgesetzt, sodass Claude auf das Feedback reagieren kann. Siehe [Stop-Entscheidungskontrolle](#stop-decision-control)1080* [Stop](#stop) und [SubagentStop](#subagentstop): am Ende des Zugs. Die Konversation wird fortgesetzt, sodass Claude auf das Feedback reagieren kann. Siehe [Stop-Entscheidungskontrolle](#stop-decision-control)
1081* [PostModelSwitch](#postmodelswitch): mit der nächsten Anfrage nach dem Wechsel. Siehe [PostModelSwitch-Entscheidungskontrolle](#postmodelswitch-decision-control) für Timing
865 1082
866Wenn mehrere Hooks `additionalContext` für das gleiche Ereignis zurückgeben, erhält Claude alle Werte. Wenn ein Wert 10.000 Zeichen überschreitet, schreibt Claude Code den vollständigen Text in eine Datei im Sitzungsverzeichnis und übergibt Claude stattdessen den Dateipfad mit einer kurzen Vorschau.1083Wenn mehrere Hooks `additionalContext` für das gleiche Ereignis zurückgeben, erhält Claude alle Werte.
1084
1085Wenn ein Wert 10.000 Zeichen überschreitet, schreibt Claude Code den Text in eine Datei im Sitzungsverzeichnis und übergibt Claude stattdessen den Dateipfad mit einer Vorschau von bis zu den ersten 2.000 Zeichen. Claude kann die Datei lesen, aber Claude Code fordert es nicht auf.
867 1086
868Verwenden Sie `additionalContext` für Informationen, die Claude über den aktuellen Zustand Ihrer Umgebung oder die gerade ausgeführte Operation wissen sollte:1087Verwenden Sie `additionalContext` für Informationen, die Claude über den aktuellen Zustand Ihrer Umgebung oder die gerade ausgeführte Operation wissen sollte:
869 1088
875 1094
876Schreiben Sie den Text als sachliche Aussagen statt als imperative Systembefehle. Formulierungen wie „Das Bereitstellungsziel ist Produktion" oder „Dieses Repo verwendet `bun test`" werden als Projektinformationen gelesen. Text, der als Out-of-Band-Systembefehle formuliert ist, kann Claudes Prompt-Injection-Abwehr auslösen, was dazu führt, dass Claude den Text an Sie zurückgibt, anstatt ihn als Kontext zu behandeln.1095Schreiben Sie den Text als sachliche Aussagen statt als imperative Systembefehle. Formulierungen wie „Das Bereitstellungsziel ist Produktion" oder „Dieses Repo verwendet `bun test`" werden als Projektinformationen gelesen. Text, der als Out-of-Band-Systembefehle formuliert ist, kann Claudes Prompt-Injection-Abwehr auslösen, was dazu führt, dass Claude den Text an Sie zurückgibt, anstatt ihn als Kontext zu behandeln.
877 1096
878Nach der Injektion wird der Text im Sitzungstranskript gespeichert. Für Mid-Session-Ereignisse wie `PostToolUse` oder `UserPromptSubmit` wird beim Fortsetzen mit `--continue` oder `--resume` der gespeicherte Text erneut abgespielt, anstatt den Hook für vergangene Umdrehungen erneut auszuführen, sodass Werte wie Zeitstempel oder Commit-SHAs beim Fortsetzen veraltet werden. `SessionStart`-Hooks werden beim Fortsetzen mit `source` auf `"resume"` gesetzt erneut ausgeführt, sodass sie ihren Kontext aktualisieren können.1097Claude Code speichert den eingespritzt Text im Sitzungstranskript. Für Mid-Session-Ereignisse wie `PostToolUse` oder `UserPromptSubmit` wird beim Fortsetzen mit `--continue` oder `--resume` der gespeicherte Text erneut abgespielt, anstatt den Hook für vergangene Umdrehungen erneut auszuführen, sodass Werte wie Zeitstempel oder Commit-SHAs beim Fortsetzen veraltet werden. `SessionStart`-Hooks werden beim Fortsetzen mit `source` auf `"resume"` gesetzt erneut ausgeführt, oder `"fork"` wenn Sie `--fork-session` hinzugefügt haben, sodass sie ihren Kontext aktualisieren können.
879 1098
880<h4 id="decision-control">1099<h4 id="decision-control">
881 Entscheidungskontrolle1100 Entscheidungskontrolle
884Nicht jedes Ereignis unterstützt das Blockieren oder Steuern des Verhaltens durch JSON. Die Ereignisse, die dies tun, verwenden jeweils einen anderen Satz von Feldern, um diese Entscheidung auszudrücken. Verwenden Sie diese Tabelle als schnelle Referenz, bevor Sie einen Hook schreiben:1103Nicht jedes Ereignis unterstützt das Blockieren oder Steuern des Verhaltens durch JSON. Die Ereignisse, die dies tun, verwenden jeweils einen anderen Satz von Feldern, um diese Entscheidung auszudrücken. Verwenden Sie diese Tabelle als schnelle Referenz, bevor Sie einen Hook schreiben:
885 1104
886| Ereignisse | Entscheidungsmuster | Schlüsselfelder |1105| Ereignisse | Entscheidungsmuster | Schlüsselfelder |
887| :---------------------------------------------------------------------------------------------------------------------------------- | :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1106| :---------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
888| UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, SubagentStop, ConfigChange, PreCompact | Top-Level `decision` | `decision: "block"`, `reason`. Stop und SubagentStop akzeptieren auch `hookSpecificOutput.additionalContext` für [nicht-fehlerhafte Rückmeldung, die das Gespräch fortsetzt](#stop-decision-control) |1107| UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, SubagentStop, ConfigChange, PreCompact | Top-Level `decision` | `decision: "block"`, `reason`. Stop und SubagentStop akzeptieren auch `hookSpecificOutput.additionalContext` für [nicht-fehlerhafte Rückmeldung, die die Konversation fortsetzt](#stop-decision-control) |
889| TeammateIdle, TaskCreated, TaskCompleted | Exit-Code oder `continue: false` | Exit-Code 2 blockiert die Aktion mit stderr-Feedback. JSON `{"continue": false, "stopReason": "..."}` stoppt auch den Teammate vollständig, was dem `Stop`-Hook-Verhalten entspricht |1108| TeammateIdle, TaskCompleted | Exit-Code oder `continue: false` | Exit-Code 2 blockiert die Aktion mit stderr-Feedback. JSON `{"continue": false, "stopReason": "..."}` stoppt auch den Teammate vollständig, was dem `Stop`-Hook-Verhalten entspricht; [TaskCompleted ignoriert es, wenn das `TaskUpdate`-Tool das Ereignis ausgelöst hat](#taskcompleted-decision-control) |
1109| TaskCreated | Exit-Code oder Top-Level `decision` | Exit-Code 2 oder `decision: "block"` [bricht die Aufgabe ab](#taskcreated-decision-control) und gibt die Nachricht an Claude zurück. `continue: false` wird ignoriert |
890| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask/defer), `permissionDecisionReason` |1110| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask/defer), `permissionDecisionReason` |
1111| PreModelSwitch | `hookSpecificOutput` oder Top-Level `decision` | `permissionDecision` (allow/deny/ask), `permissionDecisionReason`. `decision: "block"` [bricht auch den Wechsel ab](#premodelswitch-decision-control) |
891| PermissionRequest | `hookSpecificOutput` | `decision.behavior` (allow/deny) |1112| PermissionRequest | `hookSpecificOutput` | `decision.behavior` (allow/deny) |
892| PermissionDenied | `hookSpecificOutput` | `retry: true` teilt dem Modell mit, dass es möglicherweise den verweigerten Tool-Aufruf erneut versuchen kann |1113| PermissionDenied | `hookSpecificOutput` | `retry: true` teilt dem Modell mit, dass es möglicherweise den verweigerten Tool-Aufruf erneut versuchen kann; Claude Code ignoriert es für [Ablehnungen ohne Urteil](#permissiondenied-decision-control) |
893| WorktreeCreate | Pfad-Rückgabe | Command-Hook gibt Pfad auf stdout aus; HTTP-Hook gibt `hookSpecificOutput.worktreePath` zurück. Hook-Fehler oder fehlender Pfad schlägt die Erstellung fehl |1114| WorktreeCreate | Pfad-Rückgabe | Command-Hook gibt Pfad auf stdout aus; HTTP-Hook gibt `hookSpecificOutput.worktreePath` zurück. Hook-Fehler oder fehlender Pfad schlägt die Erstellung fehl |
1115| WorktreeRemove | Exit-Code | Jeder Nicht-Null-Exit-Code lässt die Entfernung fehlschlagen, wenn das Verzeichnis danach noch existiert. Siehe [WorktreeRemove](#worktreeremove) für das, was mit dem Verzeichnis passiert |
894| Elicitation | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (Formularfeldwerte für accept) |1116| Elicitation | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (Formularfeldwerte für accept) |
895| ElicitationResult | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (Formularfeldwerte überschreiben) |1117| ElicitationResult | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (Formularfeldwerte überschreiben) |
896| MessageDisplay | `hookSpecificOutput` | `displayContent` ersetzt den angezeigten Text auf dem Bildschirm. Nur Anzeige: das Transkript und das, was Claude sieht, behalten das Original |1118| MessageDisplay | `hookSpecificOutput` | `displayContent` ersetzt den angezeigten Text auf dem Bildschirm. Nur Anzeige: das Transkript und das, was Claude sieht, behalten das Original |
897| SessionStart, Setup, SubagentStart | Nur Kontext | `hookSpecificOutput.additionalContext` fügt Kontext für Claude hinzu. SessionStart akzeptiert auch [`initialUserMessage`, `watchPaths`, `sessionTitle` und `reloadSkills`](#sessionstart-decision-control). Keine Blockierung oder Entscheidungskontrolle |1119| SessionStart, SubagentStart, PostModelSwitch | Nur Kontext | `hookSpecificOutput.additionalContext` fügt Kontext für Claude hinzu. SessionStart akzeptiert auch [`initialUserMessage`, `watchPaths`, `sessionTitle` und `reloadSkills`](#sessionstart-decision-control). Keine Blockierung oder Entscheidungskontrolle |
898| WorktreeRemove, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, FileChanged | Keine | Keine Entscheidungskontrolle. Wird für Nebenwirkungen wie Protokollierung oder Bereinigung verwendet |1120| Setup, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, DirectoryAdded, FileChanged | Keine | Keine Entscheidungskontrolle. Wird für Nebenwirkungen wie Protokollierung oder Bereinigung verwendet |
899 1121
900Einige Ereignisse können auch Inhalte umschreiben, anstatt nur zuzulassen oder zu blockieren:1122Einige Ereignisse können auch Inhalte umschreiben, anstatt nur zuzulassen oder zu blockieren:
901 1123
902* `PreToolUse`: `updatedInput` direkt unter `hookSpecificOutput` ersetzt die Argumente eines Tools, bevor es ausgeführt wird. Siehe [PreToolUse-Entscheidungskontrolle](#pretooluse-decision-control)1124* `PreToolUse`: `updatedInput` direkt unter `hookSpecificOutput` ersetzt die Argumente eines Tools, bevor es ausgeführt wird. Siehe [PreToolUse-Entscheidungskontrolle](#pretooluse-decision-control)
903* `PermissionRequest`: `updatedInput` innerhalb des `decision`-Objekts. Siehe [PermissionRequest-Entscheidungskontrolle](#permissionrequest-decision-control)1125* `PermissionRequest`: `updatedInput` innerhalb des `decision`-Objekts. Siehe [PermissionRequest-Entscheidungskontrolle](#permissionrequest-decision-control)
904* `PostToolUse`: `updatedToolOutput` ersetzt das Ergebnis des Tools. Siehe [PostToolUse-Entscheidungskontrolle](#posttooluse-decision-control)1126* `PostToolUse`: `updatedToolOutput` ersetzt das Ergebnis des Tools. Siehe [PostToolUse-Entscheidungskontrolle](#posttooluse-decision-control)
905* `UserPromptSubmit`: kann den Prompt nicht ersetzen; injiziert nur `additionalContext` daneben1127* `UserPromptSubmit`: kann die Eingabeaufforderung nicht ersetzen; injiziert nur `additionalContext` daneben
906 1128
907Für Redaktions- oder Transformationsfälle, fangen Sie bei `PreToolUse` für ausgehende Tool-Eingaben und `PostToolUse` für eingehende Tool-Ergebnisse ab.1129Für Redaktions- oder Transformationsfälle fangen Sie bei `PreToolUse` für ausgehende Tool-Eingaben und `PostToolUse` für eingehende Tool-Ergebnisse ab.
908 1130
909Hier sind Beispiele für jedes Muster in Aktion:1131Hier sind Beispiele für jedes Muster in Aktion:
910 1132
911<Tabs>1133<Tabs>
912 <Tab title="Top-Level-Entscheidung">1134 <Tab title="Top-Level-Entscheidung">
913 Wird von `UserPromptSubmit`, `UserPromptExpansion`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`, `Stop`, `SubagentStop`, `ConfigChange` und `PreCompact` verwendet. Der einzige Wert ist `"block"`. Um die Aktion fortzusetzen, lassen Sie `decision` aus Ihrem JSON weg, oder beenden Sie mit 0 ohne jede JSON:1135 Der einzige Wert für `decision` ist `"block"`. Um die Aktion fortzusetzen, lassen Sie `decision` aus Ihrem JSON weg, oder beenden Sie mit 0 ohne jede JSON:
914 1136
915 ```json theme={null}1137 ```json theme={null}
916 {1138 {
967 1189
968Wird ausgeführt, wenn Claude Code eine neue Sitzung startet oder eine vorhandene Sitzung fortsetzt. Nützlich zum Laden von Entwicklungskontext wie vorhandenen Problemen oder kürzlichen Änderungen an Ihrer Codebasis oder zum Einrichten von Umgebungsvariablen. Für statischen Kontext, der kein Skript erfordert, verwenden Sie stattdessen [CLAUDE.md](/docs/de/memory).1190Wird ausgeführt, wenn Claude Code eine neue Sitzung startet oder eine vorhandene Sitzung fortsetzt. Nützlich zum Laden von Entwicklungskontext wie vorhandenen Problemen oder kürzlichen Änderungen an Ihrer Codebasis oder zum Einrichten von Umgebungsvariablen. Für statischen Kontext, der kein Skript erfordert, verwenden Sie stattdessen [CLAUDE.md](/docs/de/memory).
969 1191
970SessionStart wird bei jeder Sitzung ausgeführt, daher halten Sie diese Hooks schnell. Nur `type: "command"` und `type: "mcp_tool"` Hooks werden unterstützt.1192SessionStart wird bei jeder Sitzung ausgeführt, daher halten Sie diese Hooks schnell. Nur `type: "command"` und `type: "mcp_tool"` Hooks werden unterstützt. Siehe [MCP-Tool-Hook-Felder](#mcp-tool-hook-fields) für den Zeitpunkt, an dem `mcp_tool` Hooks ausgeführt werden.
971 1193
972Der Matcher-Wert entspricht der Art, wie die Sitzung initiiert wurde:1194Der Matcher-Wert entspricht der Art, wie die Sitzung initiiert wurde:
973 1195
974| Matcher | Wann es ausgelöst wird |1196| Matcher | Wann es ausgelöst wird |
975| :-------- | :-------------------------------------- |1197| :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
976| `startup` | Neue Sitzung |1198| `startup` | Neue Sitzung |
977| `resume` | `--resume`, `--continue` oder `/resume` |1199| `resume` | `--resume`, `--continue` oder `/resume` |
978| `clear` | `/clear` |1200| `clear` | `/clear` |
979| `compact` | Auto- oder manuelle Komprimierung |1201| `compact` | Auto- oder manuelle Komprimierung |
1202| `fork` | Eine neue Sitzung, die von einer vorhandenen abgezweigt ist: `--fork-session` mit `--resume` oder `--continue`, die `/fork` Hintergrund-Kopie oder `/branch` |
1203
1204Vor v2.1.214 meldeten abgezweigte Sitzungen die Quelle `"resume"`.
1205
1206Wenn Sie eine interaktive Sitzung starten, ein Gespräch beim Start mit `--continue` oder `--resume` fortsetzen oder `/clear` ausführen, werden SessionStart-Hooks im Hintergrund ausgeführt. Sie können sofort tippen, und ein Gespräch, das Sie fortgesetzt haben, wird angezeigt, ohne auf die Hooks zu warten. Claudes erste Antwort wartet immer noch darauf, dass die Hooks fertig sind, damit ihr Kontext Claude erreicht.
1207
1208Wenn Sie Gespräche mit `/resume` innerhalb einer Sitzung wechseln, wartet der Wechsel darauf, dass die Hooks fertig sind. Wenn Sie `/clear` ausführen oder zu einem anderen Gespräch wechseln, während Hintergrund-Hooks noch laufen, gilt nichts, was sie zurückgeben, für die Sitzung.
1209
1210Das gleiche Warten gilt beim Start, einschließlich einer fortgesetzten Sitzung: Ein Prompt, den Sie senden, während SessionStart-Hooks noch laufen, erreicht Claude nicht, bis sie fertig sind.
1211
1212Während des Wartens drücken Sie `Esc`, um den Prompt zurück in die Eingabe zu nehmen, ohne ihn zu senden. Die Hooks laufen weiter.
980 1213
981<h4 id="sessionstart-input">1214<h4 id="sessionstart-input">
982 SessionStart-Eingabe1215 SessionStart-Eingabe
986 1219
987| Feld | Beschreibung |1220| Feld | Beschreibung |
988| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1221| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
989| `source` | Wie die Sitzung gestartet wurde: `"startup"` für neue Sitzungen, `"resume"` für fortgesetzte Sitzungen, `"clear"` nach `/clear` oder `"compact"` nach Komprimierung |1222| `source` | Wie die Sitzung gestartet wurde: `"startup"` für neue Sitzungen, `"resume"` für fortgesetzte Sitzungen, `"clear"` nach `/clear`, `"compact"` nach Komprimierung oder `"fork"` für eine neue Sitzung, die von einer vorhandenen abgezweigt ist |
990| `model` | Die aktive Modell-ID. Sie kann weggelassen werden, zum Beispiel nach `/clear` oder wenn eine Sitzung durch Gesprächswiederherstellung wiederhergestellt wird, daher überprüfen Sie das Feld, bevor Sie es lesen |1223| `model` | Die aktive Modell-ID. Sie kann weggelassen werden, zum Beispiel nach `/clear` oder wenn eine Sitzung durch Gesprächswiederherstellung wiederhergestellt wird, daher überprüfen Sie das Feld, bevor Sie es lesen |
991| `agent_type` | Der Agent-Name, vorhanden, wenn Sie Claude Code mit `claude --agent <name>` starten |1224| `agent_type` | Der Agent-Name, vorhanden, wenn Sie Claude Code mit `claude --agent <name>` starten |
992| `session_title` | Der aktuelle Sitzungstitel, falls bereits einer gesetzt ist, zum Beispiel über `--name` oder `/rename`. Ein Hook, der `sessionTitle` ausgibt, kann `session_title` zuerst überprüfen, um zu vermeiden, dass ein Titel überschrieben wird, den der Benutzer explizit gesetzt hat |1225| `session_title` | Der aktuelle Sitzungstitel, falls bereits einer gesetzt ist, zum Beispiel über `--name` oder `/rename`. Ein Hook, der `sessionTitle` ausgibt, kann `session_title` zuerst überprüfen, um zu vermeiden, dass ein Titel überschrieben wird, den der Benutzer explizit gesetzt hat |
993 1226
1227Wenn `source` `"resume"` oder `"fork"` ist und das Transkript mindestens eine Antwort von Claude enthält, erhalten SessionStart-Hooks auch die vier Felder unten. Ihr Hook kann sie verwenden, um zu melden, was das Fortsetzen eines veralteten Gesprächs kostet, bevor die erste Anfrage erfolgt, zum Beispiel in einer [`systemMessage`](#json-output). Diese Felder erfordern Claude Code v2.1.251 oder später.
1228
1229| Feld | Beschreibung |
1230| :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1231| `seconds_since_last_response` | Wanduhr-Sekunden seit der letzten Antwort im fortgesetzten Transkript |
1232| `context_tokens` | Tokens, die die erste Anfrage der fortgesetzten Sitzung als ihren Prompt erneut sendet |
1233| `prompt_cache_likely_expired` | `true`, wenn die letzte Antwort älter ist als die [Prompt-Cache-Lebensdauer](/docs/de/prompt-caching#cache-lifetime) der Sitzung oder eine spätere Komprimierung das zwischengespeicherte Gespräch ersetzt hat |
1234| `estimated_cache_write_usd` | Geschätzte Kosten in US-Dollar zum Schreiben von `context_tokens` in den Prompt-Cache auf dem Modell der Sitzung, ohne die Antwort |
1235
1236Dieses Beispiel zeigt die Eingabe für eine Sitzung, die 90 Minuten nach ihrer letzten Antwort fortgesetzt wurde:
1237
994```json theme={null}1238```json theme={null}
995{1239{
996 "session_id": "abc123",1240 "session_id": "abc123",
997 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",1241 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
998 "cwd": "/Users/...",1242 "cwd": "/Users/...",
999 "hook_event_name": "SessionStart",1243 "hook_event_name": "SessionStart",
1000 "source": "startup",1244 "source": "resume",
1001 "model": "claude-sonnet-5"1245 "model": "claude-opus-5",
1246 "seconds_since_last_response": 5400,
1247 "context_tokens": 182340,
1248 "prompt_cache_likely_expired": true,
1249 "estimated_cache_write_usd": 1.1396
1002}1250}
1003```1251```
1004 1252
1006 SessionStart-Entscheidungskontrolle1254 SessionStart-Entscheidungskontrolle
1007</h4>1255</h4>
1008 1256
1009Jeder Text, den Ihr Hook-Skript auf stdout ausgibt, wird als Kontext für Claude hinzugefügt. Zusätzlich zu den [JSON-Ausgabefeldern](#json-output), die für alle Hooks verfügbar sind, können Sie diese ereignisspezifischen Felder zurückgeben:1257Claude Code fügt stdout, das es [als Klartext behandelt](#exit-code-0), zu Claudes Kontext hinzu. Zusätzlich zu den [JSON-Ausgabefeldern](#json-output), die für alle Hooks verfügbar sind, können Sie diese ereignisspezifischen Felder zurückgeben:
1010 1258
1011| Feld | Beschreibung |1259| Feld | Beschreibung |
1012| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1260| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1013| `additionalContext` | Zeichenkette, die zu Claudes Kontext am Anfang des Gesprächs hinzugefügt wird, vor dem ersten Prompt. Siehe [Kontext für Claude hinzufügen](#add-context-for-claude), um zu erfahren, wie der Text bereitgestellt wird und was Sie darin einfügen sollten |1261| `additionalContext` | Zeichenkette, die zu Claudes Kontext am Anfang des Gesprächs hinzugefügt wird, vor dem ersten Prompt. Siehe [Kontext für Claude hinzufügen](#add-context-for-claude), um zu erfahren, wie der Text bereitgestellt wird und was Sie darin einfügen sollten |
1014| `initialUserMessage` | Zeichenkette, die als erste Benutzernachricht der Sitzung verwendet wird. Gilt im [nicht-interaktiven Modus](/docs/de/headless) mit dem `-p`-Flag, wo sie zur ersten Runde wird, auch wenn kein Prompt bereitgestellt wird. Wenn ein Prompt bereitgestellt wird, folgt er als nächste Runde. Im Gegensatz zu `additionalContext`, das an eine vorhandene Runde angehängt wird, erstellt dies die Runde |1262| `initialUserMessage` | Zeichenkette, die als erste Benutzernachricht der Sitzung verwendet wird. Gilt im [nicht-interaktiven Modus](/docs/de/headless) mit dem `-p`-Flag, wo sie zur ersten Runde wird, auch wenn kein Prompt bereitgestellt wird. Wenn ein Prompt bereitgestellt wird, folgt er als nächste Runde. Im Gegensatz zu `additionalContext`, das an eine vorhandene Runde angehängt wird, erstellt dies die Runde |
1015| `sessionTitle` | Setzt den Sitzungstitel, mit der gleichen Auswirkung wie `/rename`. Verwenden Sie, um Sitzungen automatisch aus dem Start-Ordner, Git-Branch oder Worktree-Namen zu benennen. Gilt nur, wenn `source` `"startup"` oder `"resume"` ist; wird bei `"clear"` und `"compact"` ignoriert |1263| `sessionTitle` | Setzt den Sitzungstitel, mit der gleichen Auswirkung wie `/rename`. Verwenden Sie, um Sitzungen automatisch aus dem Start-Ordner, Git-Branch oder Worktree-Namen zu benennen. Gilt, wenn `source` `"startup"`, `"resume"` oder `"fork"` ist; wird bei `"clear"` und `"compact"` ignoriert |
1016| `watchPaths` | Array von absoluten Pfaden zum Überwachen von [FileChanged](#filechanged)-Ereignissen während dieser Sitzung |1264| `watchPaths` | Array von absoluten Pfaden zum Überwachen von [FileChanged](#filechanged)-Ereignissen während dieser Sitzung |
1017| `reloadSkills` | Boolesch. Wenn `true`, scannt Claude Code die [Skill](/docs/de/skills)- und Befehlsverzeichnisse erneut, nachdem die SessionStart-Hooks abgeschlossen sind, damit Skills, die der Hook installiert hat, in der gleichen Sitzung verfügbar sind, beginnend mit dem ersten Prompt |1265| `reloadSkills` | Boolesch. Wenn `true`, scannt Claude Code die [Skill](/docs/de/skills)- und Befehlsverzeichnisse erneut, nachdem die SessionStart-Hooks abgeschlossen sind, damit Skills, die der Hook installiert hat, in der gleichen Sitzung verfügbar sind, beginnend mit dem ersten Prompt |
1018 1266
1026}1274}
1027```1275```
1028 1276
1029Da einfacher stdout bereits Claude für dieses Ereignis erreicht, kann ein Hook, der nur Kontext lädt, direkt auf stdout drucken, ohne JSON zu erstellen. Verwenden Sie die JSON-Form, wenn Sie Kontext mit anderen Feldern wie `suppressOutput` oder `sessionTitle` kombinieren müssen.1277Da einfacher stdout bereits Claude für dieses Ereignis erreicht, kann ein Hook, der nur Kontext lädt, direkt auf stdout drucken, ohne JSON zu erstellen. Verwenden Sie die JSON-Form, wenn Sie Kontext mit anderen Feldern wie `sessionTitle` kombinieren müssen.
1030 1278
1031Verwenden Sie `reloadSkills`, wenn ein SessionStart-Hook Skills installiert oder aktualisiert. Die Skill-Erkennung wird normalerweise ausgeführt, bevor SessionStart-Hooks fertig sind, daher würden Dateien, die der Hook in `~/.claude/skills/` oder `.claude/skills/` schreibt, sonst erst in der nächsten Sitzung erscheinen. Dieses Beispiel synchronisiert ein gemeinsames Skills-Repository und fordert die Neuscan an:1279Verwenden Sie `reloadSkills`, wenn ein SessionStart-Hook Skills installiert oder aktualisiert. Die Skill-Erkennung wird normalerweise ausgeführt, bevor SessionStart-Hooks fertig sind, daher würden Dateien, die der Hook in `~/.claude/skills/` oder `.claude/skills/` schreibt, sonst erst in der nächsten Sitzung erscheinen. Dieses Beispiel synchronisiert ein gemeinsames Skills-Repository und fordert die Neuscan an:
1032 1280
1039echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1287echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1040```1288```
1041 1289
1290Die Repository-URL ist ein Platzhalter; ersetzen Sie sie durch Ihr eigenes Skills-Repository. Mit dem Platzhalter schlägt der Clone fehl und gibt eine `fatal:`-Nachricht zu stderr aus. Stderr von einem SessionStart-Hook, der mit 0 beendet wird, ist nur informativ, daher gilt die `reloadSkills`-Anfrage immer noch.
1291
1042<h4 id="persist-environment-variables">1292<h4 id="persist-environment-variables">
1043 Umgebungsvariablen beibehalten1293 Umgebungsvariablen beibehalten
1044</h4>1294</h4>
1078exit 01328exit 0
1079```1329```
1080 1330
1081Alle Variablen, die in diese Datei geschrieben werden, sind in allen nachfolgenden Bash-Befehlen verfügbar, die Claude Code während der Sitzung ausführt.
1082
1083<Note>1331<Note>
1084 `CLAUDE_ENV_FILE` ist für SessionStart-, [Setup](#setup)-, [CwdChanged](#cwdchanged)- und [FileChanged](#filechanged)-Hooks verfügbar. Andere Hook-Typen haben keinen Zugriff auf diese Variable.1332 `CLAUDE_ENV_FILE` ist für SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged) und [FileChanged](#filechanged) Hooks verfügbar. Andere Hook-Typen haben keinen Zugriff auf diese Variable.
1085</Note>1333</Note>
1086 1334
1087<h3 id="setup">1335<h3 id="setup">
1097| `init` | `claude --init-only` oder `claude -p --init` |1345| `init` | `claude --init-only` oder `claude -p --init` |
1098| `maintenance` | `claude -p --maintenance` |1346| `maintenance` | `claude -p --maintenance` |
1099 1347
1100`--init-only` führt Setup-Hooks und SessionStart-Hooks mit dem `startup`-Matcher aus und beendet sich dann, ohne ein Gespräch zu starten. `--init` und `--maintenance` lösen Setup-Hooks nur aus, wenn sie mit `-p` kombiniert werden; in einer interaktiven Sitzung lösen diese beiden Flags derzeit keine Setup-Hooks aus.1348Wenn Sie `claude --init-only` ausführen, führt Claude Code Setup-Hooks und `SessionStart`-Hooks mit dem `startup`-Matcher aus und beendet sich dann, ohne ein Gespräch zu starten.
1349
1350Wenn Sie ein Gespräch mit `-p` starten oder fortsetzen, müssen Sie auch einen Prompt bereitstellen, entweder als Argument oder über stdin. Sie können den Prompt überspringen, wenn ein `SessionStart`-Hook [`initialUserMessage`](#sessionstart-decision-control) bereitstellt oder wenn Sie eine Sitzung mit einem [verschobenen Tool-Aufruf](#defer-a-tool-call-for-later) fortsetzen.
1101 1351
1102Da Setup nicht bei jedem Start ausgelöst wird, kann ein Plugin, das eine Abhängigkeit installiert benötigt, sich nicht allein auf Setup verlassen. Das praktische Muster ist, die Abhängigkeit bei der ersten Verwendung zu überprüfen und bei Fehlen zu installieren, zum Beispiel ein Hook oder eine Skill, die auf `${CLAUDE_PLUGIN_DATA}/node_modules` testet und `npm install` ausführt, wenn es fehlt. Siehe das [Verzeichnis für persistente Daten](/docs/de/plugins-reference#persistent-data-directory), um zu erfahren, wo Sie installierte Abhängigkeiten speichern können.1352Bei Erfolg gibt `--init-only` nichts auf dem Terminal aus. Um zu bestätigen, dass die Hooks ausgeführt wurden, starten Sie mit `claude --debug-file <path> --init-only`, ersetzen Sie `<path>` durch einen Protokolldateispeicherort, und überprüfen Sie das Protokoll auf die Setup- und SessionStart-Hook-Einträge.
1353
1354Da Setup nicht bei jedem Start ausgelöst wird, kann ein Plugin, das eine Abhängigkeit installiert benötigt, sich nicht allein auf Setup verlassen. Das praktische Muster ist, die Abhängigkeit bei der ersten Verwendung zu überprüfen und bei Fehlen zu installieren, zum Beispiel ein Hook oder eine Skill, die auf `${CLAUDE_PLUGIN_DATA}/node_modules` testet und `npm install` ausführt, wenn es fehlt. Siehe das [Verzeichnis für persistente Daten](/docs/de/plugins-reference#persistent-data-directory), um zu erfahren, wo Sie installierte Abhängigkeiten speichern können. Wenn Sie Ihr Plugin über einen Marketplace verteilen, benötigen Sie möglicherweise dieses Muster nicht: Claude Code [installiert automatisch berechtigte Node.js-Paketabhängigkeiten](/docs/de/plugins-reference#node-js-package-dependencies), wenn es das Plugin zwischenspeichert.
1103 1355
1104<h4 id="setup-input">1356<h4 id="setup-input">
1105 Setup-Eingabe1357 Setup-Eingabe
1121 Setup-Entscheidungskontrolle1373 Setup-Entscheidungskontrolle
1122</h4>1374</h4>
1123 1375
1124Setup-Hooks können nicht blockieren. Jeder Nicht-Null-Exit-Code, einschließlich 2, zeigt stderr dem Benutzer als `<hook name> hook error`-Hinweis an, und die Ausführung wird fortgesetzt. Im [nicht-interaktiven Modus](/docs/de/headless) wird Hook-Ausgabe nur angezeigt, wenn Sie mit `--verbose` starten.1376Setup-Hooks können nicht blockieren; die Ausführung wird bei jedem Exit-Code fortgesetzt. Bei jedem Exit-Code verwirft Claude Code die [JSON-Ausgabefelder](#json-output) eines Setup-Hooks, wie `systemMessage`, `continue` und `hookSpecificOutput.additionalContext`. Mit `-p` werden stdout, stderr und Exit-Code eines Setup-Hooks in der Ausgabe des Laufs nur als [`hook_response`-Ereignisse](/docs/de/headless#read-session-metadata) angezeigt, wenn Sie mit `--output-format stream-json --verbose` starten.
1125
1126Um Informationen in Claudes Kontext zu übergeben, geben Sie `additionalContext` in der JSON-Ausgabe zurück; einfacher stdout wird nur in das Debug-Protokoll geschrieben. Zusätzlich zu den [JSON-Ausgabefeldern](#json-output), die für alle Hooks verfügbar sind, können Sie diese ereignisspezifischen Felder zurückgeben:
1127
1128| Feld | Beschreibung |
1129| :------------------ | :------------------------------------------------------------------------------------------- |
1130| `additionalContext` | Zeichenkette, die zu Claudes Kontext hinzugefügt wird. Werte mehrerer Hooks werden verkettet |
1131
1132```json theme={null}
1133{
1134 "hookSpecificOutput": {
1135 "hookEventName": "Setup",
1136 "additionalContext": "Dependencies installed: node_modules, .venv"
1137 }
1138}
1139```
1140 1377
1141Setup-Hooks haben Zugriff auf `CLAUDE_ENV_FILE`. Variablen, die in diese Datei geschrieben werden, bleiben in nachfolgenden Bash-Befehlen für die Sitzung erhalten, genau wie in [SessionStart-Hooks](#persist-environment-variables). Nur `type: "command"` und `type: "mcp_tool"` Hooks werden unterstützt.1378Setup-Hooks haben Zugriff auf `CLAUDE_ENV_FILE`. Variablen, die in diese Datei geschrieben werden, bleiben in nachfolgenden Bash-Befehlen für die Sitzung erhalten, genau wie in [SessionStart-Hooks](#persist-environment-variables). Nur `type: "command"` Hooks werden auf `Setup` ausgeführt. Ein `type: "mcp_tool"` Hook auf `Setup` wird immer übersprungen, wie unter [MCP-Tool-Hook-Felder](#mcp-tool-hook-fields) beschrieben.
1142 1379
1143<h3 id="instructionsloaded">1380<h3 id="instructionsloaded">
1144 InstructionsLoaded1381 InstructionsLoaded
1146 1383
1147Wird ausgelöst, wenn eine `CLAUDE.md`- oder `.claude/rules/*.md`-Datei in den Kontext geladen wird. Dieses Ereignis wird beim Sitzungsstart für eifrig geladene Dateien ausgelöst und später erneut, wenn Dateien träge geladen werden, zum Beispiel wenn Claude auf ein Unterverzeichnis zugreift, das eine verschachtelte `CLAUDE.md` enthält, oder wenn bedingte Regeln mit `paths:`-Frontmatter passen. Der Hook unterstützt keine Blockierung oder Entscheidungskontrolle. Er wird asynchron zu Beobachtungszwecken ausgeführt.1384Wird ausgelöst, wenn eine `CLAUDE.md`- oder `.claude/rules/*.md`-Datei in den Kontext geladen wird. Dieses Ereignis wird beim Sitzungsstart für eifrig geladene Dateien ausgelöst und später erneut, wenn Dateien träge geladen werden, zum Beispiel wenn Claude auf ein Unterverzeichnis zugreift, das eine verschachtelte `CLAUDE.md` enthält, oder wenn bedingte Regeln mit `paths:`-Frontmatter passen. Der Hook unterstützt keine Blockierung oder Entscheidungskontrolle. Er wird asynchron zu Beobachtungszwecken ausgeführt.
1148 1385
1386Dieses Ereignis wird nicht ausgelöst, wenn Claude [AGENTS.md direkt](/docs/de/memory#agents-md) über die Einstellung **Projektanweisungen** liest. Es wird ausgelöst, wenn eine `CLAUDE.md` Ihre `AGENTS.md` importiert, mit `load_reason` auf `include` gesetzt wie für jede andere importierte Datei, und wenn `CLAUDE.md` ein Symlink zu ihr ist, als normales `CLAUDE.md`-Laden.
1387
1149Der Matcher wird gegen `load_reason` ausgeführt. Verwenden Sie zum Beispiel `"matcher": "session_start"`, um nur für Dateien zu feuern, die beim Sitzungsstart geladen werden, oder `"matcher": "path_glob_match|nested_traversal"`, um nur für träge Ladevorgänge zu feuern.1388Der Matcher wird gegen `load_reason` ausgeführt. Verwenden Sie zum Beispiel `"matcher": "session_start"`, um nur für Dateien zu feuern, die beim Sitzungsstart geladen werden, oder `"matcher": "path_glob_match|nested_traversal"`, um nur für träge Ladevorgänge zu feuern.
1150 1389
1151<h4 id="instructionsloaded-input">1390<h4 id="instructionsloaded-input">
1179 InstructionsLoaded-Entscheidungskontrolle1418 InstructionsLoaded-Entscheidungskontrolle
1180</h4>1419</h4>
1181 1420
1182InstructionsLoaded-Hooks haben keine Entscheidungskontrolle. Sie können das Laden von Anweisungen nicht blockieren oder ändern. Verwenden Sie dieses Ereignis für Audit-Protokollierung, Compliance-Tracking oder Beobachtbarkeit.1421InstructionsLoaded-Hooks haben keine Entscheidungskontrolle. Sie können das Laden von Anweisungen nicht blockieren oder ändern. Claude Code verwirft ihre [JSON-Ausgabefelder](#json-output), wie `systemMessage` und `continue`. Verwenden Sie dieses Ereignis für Audit-Protokollierung, Compliance-Tracking oder Beobachtbarkeit.
1183 1422
1184<h3 id="userpromptsubmit">1423<h3 id="userpromptsubmit">
1185 UserPromptSubmit1424 UserPromptSubmit
1189 1428
1190`UserPromptSubmit`-Hooks haben ein Standard-Timeout von 30 Sekunden für `command`-, `http`- und `mcp_tool`-Typen, kürzer als das 600-Sekunden-Standard für diese Typen bei anderen Ereignissen. Da dieser Hook vor jedem Prompt ausgeführt wird und die Modellverarbeitung blockiert, bis er abgeschlossen ist, stellt ein feststeckender Hook die Sitzung still. Wenn Ihr Hook mehr Zeit benötigt, setzen Sie das Feld `timeout` im Hook-Eintrag.1429`UserPromptSubmit`-Hooks haben ein Standard-Timeout von 30 Sekunden für `command`-, `http`- und `mcp_tool`-Typen, kürzer als das 600-Sekunden-Standard für diese Typen bei anderen Ereignissen. Da dieser Hook vor jedem Prompt ausgeführt wird und die Modellverarbeitung blockiert, bis er abgeschlossen ist, stellt ein feststeckender Hook die Sitzung still. Wenn Ihr Hook mehr Zeit benötigt, setzen Sie das Feld `timeout` im Hook-Eintrag.
1191 1430
1192Ein `UserPromptSubmit`-Hook, der sein Timeout erreicht, wird abgebrochen und seine Ausgabe, einschließlich aller `additionalContext`, wird verworfen. Der Prompt erreicht Claude immer noch ohne diesen Kontext. Ab v2.1.196 zeigt das Transkript einen Hinweis, der den Hook, das ausgelöste Timeout und dass die Ausgabe verworfen wurde, benennt. Frühere Versionen brechen den Hook ohne Hinweis ab.
1193
1194Ein [Agent SDK-Callback-Hook](/docs/de/agent-sdk/hooks) auf `UserPromptSubmit`, der sein Timeout erreicht, blockiert den Prompt mit einer Nachricht, die den Hook und das Timeout benennt, da ein Callback dort als Richtlinien-Gate fungieren kann, das nicht offen fehlschlagen darf. Die Sitzung wird fortgesetzt. Vor v2.1.208 endete ein Callback-Timeout bei diesem Ereignis die Runde mit einem Ausführungsfehler.1431Ein [Agent SDK-Callback-Hook](/docs/de/agent-sdk/hooks) auf `UserPromptSubmit`, der sein Timeout erreicht, blockiert den Prompt mit einer Nachricht, die den Hook und das Timeout benennt, da ein Callback dort als Richtlinien-Gate fungieren kann, das nicht offen fehlschlagen darf. Die Sitzung wird fortgesetzt. Vor v2.1.208 endete ein Callback-Timeout bei diesem Ereignis die Runde mit einem Ausführungsfehler.
1195 1432
1196<h4 id="userpromptsubmit-input">1433<h4 id="userpromptsubmit-input">
1218 1455
1219Es gibt zwei Möglichkeiten, Kontext zum Gespräch bei Exit-Code 0 hinzuzufügen:1456Es gibt zwei Möglichkeiten, Kontext zum Gespräch bei Exit-Code 0 hinzuzufügen:
1220 1457
1221* **Plain-Text-stdout**: Jeder Nicht-JSON-Text, der auf stdout geschrieben wird, wird als Kontext hinzugefügt1458* **Plain-Text-stdout**: Claude Code fügt stdout, das es [als Klartext behandelt](#exit-code-0), zu Claudes Kontext hinzu
1222* **JSON mit `additionalContext`**: Verwenden Sie das JSON-Format unten für mehr Kontrolle. Das Feld `additionalContext` wird als Kontext hinzugefügt1459* **JSON mit `additionalContext`**: Verwenden Sie das JSON-Format unten für mehr Kontrolle. Das Feld `additionalContext` wird als Kontext hinzugefügt
1223 1460
1224Plain-stdout wird als Hook-Ausgabe im Transkript angezeigt. Das Feld `additionalContext` wird als Systemerinnerung eingefügt, die Claude ohne sichtbaren Transkript-Eintrag liest.1461Weder Kanal erzeugt einen sichtbaren Transkript-Eintrag. Plain-stdout und der `additionalContext`-Wert werden jeweils als Systemerinnerung eingefügt, die mit dem Namen des Hooks beginnt; Claude liest beide. Um die Lieferung zu bestätigen, überprüfen Sie das [Debug-Protokoll](#debug-hooks).
1225 1462
1226Um einen Prompt zu blockieren, geben Sie ein JSON-Objekt mit `decision` auf `"block"` zurück:1463Um einen Prompt zu blockieren, geben Sie ein JSON-Objekt mit `decision` auf `"block"` zurück:
1227 1464
1228| Feld | Beschreibung |1465| Feld | Beschreibung |
1229| :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |1466| :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
1230| `decision` | `"block"` verhindert die Verarbeitung des Prompts und löscht ihn aus dem Kontext. Weglassen, um den Prompt fortzusetzen |1467| `decision` | `"block"` verhindert die Verarbeitung des Prompts und löscht ihn aus dem Kontext. Weglassen, um den Prompt fortzusetzen |
1231| `reason` | Wird dem Benutzer angezeigt, wenn `decision` `"block"` ist. Wird nicht zum Kontext hinzugefügt |1468| `reason` | Wird dem Benutzer angezeigt, wenn `decision` `"block"` ist. Wird nicht zum Kontext hinzugefügt |
1232| `additionalContext` | Zeichenkette, die zu Claudes Kontext hinzugefügt wird, zusammen mit dem eingereichten Prompt. Siehe [Kontext für Claude hinzufügen](#add-context-for-claude) |1469| `additionalContext` | Zeichenkette, die zu Claudes Kontext zusammen mit dem eingereichten Prompt hinzugefügt wird. Siehe [Kontext für Claude hinzufügen](#add-context-for-claude) |
1233| `sessionTitle` | Setzt den Sitzungstitel. Verwenden Sie, um Sitzungen automatisch basierend auf dem Prompt-Inhalt zu benennen |1470| `sessionTitle` | Setzt den Sitzungstitel. Verwenden Sie, um Sitzungen automatisch basierend auf dem Prompt-Inhalt zu benennen |
1234| `suppressOriginalPrompt` | Wenn `true`, wenn `decision` `"block"` ist, lässt den ursprünglichen Prompt-Text aus der Blockierungsmeldung aus, die dem Benutzer angezeigt wird |1471| `suppressOriginalPrompt` | Wenn `true`, wenn `decision` `"block"` ist, lässt den ursprünglichen Prompt-Text aus der Blockierungsmeldung aus, die dem Benutzer angezeigt wird |
1235 1472
1473Ein Hook, der durch Beenden mit 2 blockiert, wird auf die gleiche Weise wie `reason` weitergeleitet: Die Blockierungsmeldung zeigt dem Benutzer den stderr-Text an, und er wird nicht zum Kontext hinzugefügt.
1474
1236```json theme={null}1475```json theme={null}
1237{1476{
1238 "decision": "block",1477 "decision": "block",
1288| `reason` | Wird dem Benutzer angezeigt, wenn `decision` `"block"` ist |1527| `reason` | Wird dem Benutzer angezeigt, wenn `decision` `"block"` ist |
1289| `additionalContext` | Zeichenkette, die zu Claudes Kontext zusammen mit dem erweiterten Prompt hinzugefügt wird. Siehe [Kontext für Claude hinzufügen](#add-context-for-claude) |1528| `additionalContext` | Zeichenkette, die zu Claudes Kontext zusammen mit dem erweiterten Prompt hinzugefügt wird. Siehe [Kontext für Claude hinzufügen](#add-context-for-claude) |
1290 1529
1530Ein Hook, der durch Beenden mit 2 blockiert, wird auf die gleiche Weise wie `reason` weitergeleitet: Die Blockierungsmeldung zeigt dem Benutzer den stderr-Text an.
1531
1291```json theme={null}1532```json theme={null}
1292{1533{
1293 "decision": "block",1534 "decision": "block",
1357| :--------------- | :--------------------------------------------------------------------------------- |1598| :--------------- | :--------------------------------------------------------------------------------- |
1358| `displayContent` | Text, der anstelle des Delta angezeigt wird. Weglassen, um das Original anzuzeigen |1599| `displayContent` | Text, der anstelle des Delta angezeigt wird. Weglassen, um das Original anzuzeigen |
1359 1600
1360MessageDisplay-Hooks haben keine Entscheidungskontrolle. Sie können die Nachricht nicht blockieren oder ändern, was im Transkript gespeichert oder an Claude gesendet wird.1601MessageDisplay-Hooks haben keine Entscheidungskontrolle. Sie können die Nachricht nicht blockieren oder ändern, was im Transkript gespeichert oder an Claude gesendet wird. Claude Code handelt auf `displayContent` aus ihrer JSON-Ausgabe und verwirft `systemMessage` und `continue`.
1361 1602
1362Dieses Beispiel entfernt Markdown-Formatierung aus Claudes Antworten für eine Nur-Text-Anzeige. Das Skript liest jeden Batch von stdin, entfernt Fettdruck-Marker und Inline-Code-Backticks aus `delta` und gibt das Ergebnis als `displayContent` zurück.1603Dieses Beispiel entfernt Markdown-Formatierung aus Claudes Antworten für eine Nur-Text-Anzeige. Das Skript liest jeden Batch von stdin, entfernt Fettdruck-Marker und Inline-Code-Backticks aus `delta` und gibt das Ergebnis als `displayContent` zurück.
1363 1604
1389 #!/bin/bash1630 #!/bin/bash
1390 jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'1631 jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'
1391 ```1632 ```
1392
1393 Das Skript benötigt `jq` auf Ihrem `PATH`.
1394 </Tab>1633 </Tab>
1395 1634
1396 <Tab title="Windows (PowerShell)">1635 <Tab title="Windows (PowerShell)">
1443 PreToolUse1682 PreToolUse
1444</h3>1683</h3>
1445 1684
1446Wird ausgeführt, nachdem Claude Tool-Parameter erstellt hat und bevor der Tool-Aufruf verarbeitet wird. Passt auf Tool-Namen: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `ExitPlanMode` und alle [MCP-Tool-Namen](#match-mcp-tools).1685Wird ausgeführt, nachdem Claude Tool-Parameter erstellt hat und bevor der Tool-Aufruf verarbeitet wird. Passt auf jeden Tool-Namen außer `EndConversation`: eingebaute Tools wie `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion` und `ExitPlanMode`, und alle [MCP-Tool-Namen](#match-mcp-tools).
1686
1687Um einen Hook auszuführen, wenn sich eine bestimmte Datei auf der Festplatte ändert, egal was sie geschrieben hat, verwenden Sie [FileChanged](#filechanged) statt PreToolUse-Matching-Datei-Bearbeitungs-Tools nach Name. Im Gegensatz zu PreToolUse führt Claude Code FileChanged-Hooks nach der Änderung aus, und sie haben keine Entscheidungskontrolle, daher können sie den Schreibvorgang nicht blockieren.
1447 1688
1448<Warning>1689<Warning>
1449 PreToolUse wird nur ausgeführt, wenn Claude ein Tool aufruft. Dateien, die Sie [mit `@` in Ihrem Prompt referenzieren](/docs/de/common-workflows#reference-files-and-directories), werden ohne Tool-Aufruf hinzugefügt: Claude Code fügt ihre Inhalte beim Erstellen des Prompts ein, daher wird kein PreToolUse-Hook für sie ausgelöst, einschließlich Hooks, die `Read` passen. Um bestimmte Pfade von `@`-Referenzen zu blockieren, verwenden Sie stattdessen eine [`Read`-Deny-Regel](/docs/de/permissions#read-and-edit).1690 PreToolUse wird nur ausgeführt, wenn Claude ein Tool aufruft. Dateien, die Sie [mit `@` in Ihrem Prompt referenzieren](/docs/de/common-workflows#reference-files-and-directories), werden ohne Tool-Aufruf hinzugefügt: Claude Code fügt ihre Inhalte beim Erstellen des Prompts ein, daher wird kein PreToolUse-Hook für sie ausgelöst, einschließlich Hooks, die `Read` passen. Um bestimmte Pfade von `@`-Referenzen zu blockieren, verwenden Sie stattdessen eine [`Read`-Deny-Regel](/docs/de/permissions#read-and-edit).
1691
1692 PreToolUse wird auch nicht für [`EndConversation`](/docs/de/tools-reference#endconversation-tool-behavior) ausgelöst.
1450</Warning>1693</Warning>
1451 1694
1452Verwenden Sie [PreToolUse-Entscheidungskontrolle](#pretooluse-decision-control), um die Verwendung des Tools zuzulassen, zu verweigern, um Berechtigung zu bitten oder zu verschieben.1695Verwenden Sie [PreToolUse-Entscheidungskontrolle](#pretooluse-decision-control), um die Verwendung des Tools zuzulassen, zu verweigern, um Berechtigung zu bitten oder zu verschieben.
1453 1696
1697Ein [Agent SDK-Callback-Hook](/docs/de/agent-sdk/hooks) auf `PreToolUse`, der sein Timeout überschreitet, blockiert den Tool-Aufruf, und Claude erhält ein Fehlerergebnis, das das Timeout benennt. Eine explizite Verweigerung, die von einem anderen Hook zurückgegeben wird, hat immer noch Vorrang.
1698
1454<h4 id="pretooluse-input">1699<h4 id="pretooluse-input">
1455 PreToolUse-Eingabe1700 PreToolUse-Eingabe
1456</h4>1701</h4>
1457 1702
1458Zusätzlich zu den [gemeinsamen Eingabefeldern](#common-input-fields) erhalten PreToolUse-Hooks `tool_name`, `tool_input` und `tool_use_id`. Die Felder `tool_input` hängen vom Tool ab:1703Zusätzlich zu den [gemeinsamen Eingabefeldern](#common-input-fields) erhalten PreToolUse-Hooks `tool_name`, `tool_input` und `tool_use_id`.
1704
1705Für ein [MCP-Tool](#match-mcp-tools) trägt die Eingabe auch `mcp_server`, ein Objekt mit dem Namen des Servers und einer `source`, die angibt, woher die Definition des Servers kam. Die `source`-Werte umfassen `plugin`, `sdk` und Konfigurationsumfänge wie `user` und `project`. [`McpServerProvenance`](/docs/de/agent-sdk/typescript#mcpserverprovenance) in der Agent SDK-Referenz listet sie alle auf und sagt, wie man eine behandelt, die man nicht erkennt. Treffen Sie Vertrauensentscheidungen auf Basis von `source` statt auf `name` oder dem `mcp__<server>__`-Tool-Namen-Präfix. Das Feld `mcp_server` erfordert Claude Code v2.1.274 oder später.
1706
1707Für die Datei-Tools `Write`, `Edit` und `Read` ist `tool_input.file_path` immer absolut:
1708
1709* Claude Code erweitert `~` und relative Pfade, bevor Hooks ausgeführt werden, daher kann ein Hook, der auf Pfade passt, nicht durch `~` oder eine relative Schreibweise des gleichen Pfads umgangen werden
1710* Unter Windows kommt der Pfad mit Backslash-Trennzeichen an, auch wenn Ihr Hook unter Git Bash läuft, wo `$PWD` wie `/c/project` aussieht
1711* Ein Vergleich, der mit Schrägstrichen geschrieben ist, wie ein `/src/`-Check, passt niemals auf einen Backslash-Pfad, und der Tool-Aufruf wird fortgesetzt, als hätte der Hook nichts zu blockieren
1712* Normalisieren Sie Trennzeichen vor dem Vergleich: `FILE_PATH="${FILE_PATH//\\//}"` in Bash oder `file_path.replace("\\", "/")` in Python, dann passen Sie auf ein Pfad-Segment wie `/src/` statt auf Anker mit `^`, da der Pfad absolut ist
1713
1714Ein `Write`-Aufruf unter Windows liefert:
1715
1716```json theme={null}
1717{
1718 "hook_event_name": "PreToolUse",
1719 "tool_name": "Write",
1720 "tool_input": {
1721 "file_path": "C:\\project\\src\\index.ts",
1722 "content": "..."
1723 },
1724 ...
1725}
1726```
1727
1728Die `tool_input`-Felder hängen vom Tool ab:
1729
1730<a id="bash" />
1459 1731
1460<h5 id="bash">1732<h5 id="bash">
1461 Bash1733 Bash
1470| `timeout` | Zahl | `120000` | Optionales Timeout in Millisekunden. Werte über dem [Maximum](/docs/de/tools-reference#bash-tool-behavior) werden auf das Maximum reduziert, anstatt abgelehnt zu werden |1742| `timeout` | Zahl | `120000` | Optionales Timeout in Millisekunden. Werte über dem [Maximum](/docs/de/tools-reference#bash-tool-behavior) werden auf das Maximum reduziert, anstatt abgelehnt zu werden |
1471| `run_in_background` | Boolesch | `false` | Ob der Befehl im Hintergrund ausgeführt werden soll |1743| `run_in_background` | Boolesch | `false` | Ob der Befehl im Hintergrund ausgeführt werden soll |
1472 1744
1745Wenn ein Bash-Befehl Dateien in einem Git-Repository ändert, kann Claude Code aufzeichnen, was sich geändert hat. Es zeichnet die Änderungen in jedem Berechtigungsmodus auf, wenn die [`bashEditDiffEnabled`](/docs/de/settings-reference#basheditdiffenabled)-Einstellung die Aufzeichnung einschaltet; der Eintrag dieser Einstellung sagt, welche Dateien sie setzen können. Andernfalls zeichnet es sie nur im Auto-Modus und `bypassPermissions`-Modus auf, und nur wenn Claude Code Claude anweist, Dateien durch Bash zu bearbeiten. Setzen Sie `bashEditDiffEnabled` auf `false`, um die Aufzeichnung auszuschalten. Hintergrund-Befehle und schreibgeschützte Befehle tragen keinen Diff.
1746
1747Ihr [PostToolUse-Hook](#posttooluse) erhält dann die geänderten Dateien in `tool_response.bashEditDiff`. Die Liste deckt ab, was sich im Repository geändert hat, während der Befehl lief. Dateien, die Git ignoriert, und Dateien in Submodulen werden nicht aufgelistet. Erfordert Claude Code v2.1.269 oder später.
1748
1749<Note>
1750 Die Liste ist Best-Effort und in öffentlicher Beta. Claude Code kann eine Änderung verpassen, eine Datei einbeziehen, die ein anderer Prozess gleichzeitig geändert hat, oder bei seinen Größenlimits stoppen. Die Feldform kann sich ändern. Verwenden Sie die Liste, um zu finden, was zu überprüfen ist, nicht um eine Richtlinie durchzusetzen.
1751</Note>
1752
1753`changedFiles` und `files` listen auf, was der Befehl geändert hat; die verbleibenden Felder sagen, wie vollständig und wie zuverlässig diese Liste ist.
1754
1755| Feld | Typ | Beispiel | Beschreibung |
1756| :------------- | :------- | :------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1757| `changedFiles` | Array | `["/path/to/src/app.ts"]` | Absolute Pfade der Dateien, die der Befehl geändert hat, höchstens 200. Vorhanden, wenn `files` einen Diff hält oder `moreFiles` über Null liegt |
1758| `files` | Array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | Diffs von bis zu 5 geänderten Dateien zur Anzeige. `created` oder `deleted` ist `true` für eine Datei, die der Befehl hinzugefügt oder entfernt hat |
1759| `moreFiles` | Zahl | `2` | Anzahl der geänderten Dateien ohne Diff in `files` |
1760| `unavailable` | Boolesch | `true` | Gesetzt, wenn der Diff unvollständig ist oder nicht genommen werden konnte |
1761| `skipped` | Boolesch | `true` | Gesetzt für einen Git-Befehl, der den Arbeitsbaum bewegt, wie `git checkout` oder `git stash`, daher nimmt Claude Code keinen Diff |
1762| `shared` | Boolesch | `true` | Gesetzt, wenn ein anderer Bash-Tool-Aufruf, wie der eines Subagenten, im gleichen Repository zur gleichen Zeit lief, daher können einige aufgelistete Änderungen von diesem Befehl sein |
1763
1764<a id="powershell" />
1765
1766<h5 id="powershell">
1767 PowerShell
1768</h5>
1769
1770Führt PowerShell-Befehle aus. Siehe das [PowerShell-Tool](/docs/de/tools-reference#powershell-tool) für Verfügbarkeit nach Plattform.
1771
1772Die Felder entsprechen dem Bash-Tool, mit der Befehlszeichenkette in `command`:
1773
1774| Feld | Typ | Beispiel | Beschreibung |
1775| :------------------ | :----------- | :------------------------- | :-------------------------------------------------- |
1776| `command` | Zeichenkette | `"Get-ChildItem -Recurse"` | Der auszuführende PowerShell-Befehl |
1777| `description` | Zeichenkette | `"List files recursively"` | Optionale Beschreibung, was der Befehl tut |
1778| `timeout` | Zahl | `120000` | Optionales Timeout in Millisekunden |
1779| `run_in_background` | Boolesch | `false` | Ob der Befehl im Hintergrund ausgeführt werden soll |
1780
1781Passen Sie `Bash|PowerShell` in Hooks an, die Shell-Befehle inspizieren, damit sie beide Tools abdecken:
1782
1783* Unter Windows, wo das PowerShell-Tool aktiviert ist, behandelt Claude PowerShell als die primäre Shell und leitet Shell-Befehle durch sie.
1784* Unter Windows ohne Git Bash ist das Tool automatisch aktiviert und Claude Code registriert das Bash-Tool überhaupt nicht.
1785* Ein Hook, der nur `Bash` passt, wird dort nie ausgelöst.
1786
1473<h5 id="write">1787<h5 id="write">
1474 Write1788 Write
1475</h5>1789</h5>
1568| `subagent_type` | Zeichenkette | `"Explore"` | Typ des zu verwendenden spezialisierten Agenten |1882| `subagent_type` | Zeichenkette | `"Explore"` | Typ des zu verwendenden spezialisierten Agenten |
1569| `model` | Zeichenkette | `"sonnet"` | Optionaler Modell-Alias zum Überschreiben des Standards |1883| `model` | Zeichenkette | `"sonnet"` | Optionaler Modell-Alias zum Überschreiben des Standards |
1570 1884
1571In `PostToolUse` trägt `tool_response` für einen abgeschlossenen Agent-Aufruf den abschließenden Text des Subagenten zusammen mit Nutzungstelemetrie. Lesen Sie diese Felder, um Pro-Subagent-Kosten aus einem Hook zu erfassen:1885Wenn ein Vordergrund-Agent-Aufruf abgeschlossen ist, erhält Ihr [PostToolUse-Hook](#posttooluse) das Ergebnis des Subagenten und die Lauftelemetrie in `tool_response`. Lesen Sie diese Felder, um das Laufen zu inspizieren; für Token- und Kosten-Rollups über Subagenten verwenden Sie die [Token- und Kosten-Zähler](/docs/de/monitoring-usage#token-counter), die auf `query_source` `"subagent"` gefiltert sind, da `totalTokens` und `usage` nur die letzte Anfrage abdecken:
1572 1886
1573| Feld | Typ | Beispiel | Beschreibung |1887| Feld | Typ | Beispiel | Beschreibung |
1574| :------------------ | :----------- | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1888| :------------------ | :----------- | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1575| `status` | Zeichenkette | `"completed"` | `"completed"` für Vordergrund-Subagenten, `"async_launched"` für Hintergrund-Subagenten. Ab v2.1.198 werden Subagenten standardmäßig im Hintergrund ausgeführt, daher erzeugt ein weggelassenes `run_in_background` auch `"async_launched"` |1889| `status` | Zeichenkette | `"completed"` | `"completed"` für Vordergrund-Subagenten, `"async_launched"` für Hintergrund-Subagenten. Ab v2.1.198 werden Subagenten standardmäßig im Hintergrund ausgeführt, daher erzeugt ein weggelassenes `run_in_background` auch `"async_launched"` |
1576| `agentId` | Zeichenkette | `"a4d2c8f1e0b3a297"` | Kennung für die Subagenten-Ausführung |1890| `agentId` | Zeichenkette | `"a4d2c8f1e0b3a297"` | Kennung für die Subagenten-Ausführung |
1577| `content` | Array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Die abschließenden Textblöcke des Subagenten |1891| `content` | Array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Die abschließenden Textblöcke des Subagenten oder, für einen Subagenten, dessen Bericht durch `SubagentHandback` geht, eine kurze Notiz über diesen Handback an ihrer Stelle |
1578| `resolvedModel` | Zeichenkette | `"claude-sonnet-4-5"` | Modell, auf dem der Subagent ausgeführt wurde, das sich vom angeforderten Modell unterscheiden kann. Erfordert Claude Code v2.1.174 oder später |1892| `resolvedModel` | Zeichenkette | `"claude-sonnet-4-5"` | Modell, auf dem der Subagent gestartet wurde, das sich vom angeforderten Modell unterscheiden kann |
1579| `totalTokens` | Zahl | `12450` | Gesamttokens, die über die Runden des Subagenten abgerechnet werden |1893| `modelsUsed` | Array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelle, die in Reihenfolge verwendet wurden, mit aufeinanderfolgenden Wiederholungen zusammengefasst; wird nur gesetzt, wenn das Modell während des Laufs gewechselt wurde. Erfordert Claude Code v2.1.212 oder später |
1894| `totalTokens` | Zahl | `12450` | Token-Anzahl aus der letzten API-Anfrage des Subagenten: Input-, Output- und Cache-Tokens kombiniert. Dies ist keine Gesamtsumme über den ganzen Lauf |
1580| `totalDurationMs` | Zahl | `48211` | Wanduhr-Dauer der Subagenten-Ausführung |1895| `totalDurationMs` | Zahl | `48211` | Wanduhr-Dauer der Subagenten-Ausführung |
1581| `totalToolUseCount` | Zahl | `7` | Anzahl der Tool-Aufrufe, die der Subagent gemacht hat |1896| `totalToolUseCount` | Zahl | `7` | Anzahl der Tool-Aufrufe, die der Subagent gemacht hat |
1582| `usage` | Objekt | `{"input_tokens": 8320, ...}` | Pro-Typ-Token-Aufschlüsselung: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1897| `usage` | Objekt | `{"input_tokens": 8320, ...}` | Pro-Typ-Token-Aufschlüsselung der letzten API-Anfrage: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |
1583 1898
1584Für Hintergrund-Subagenten gibt das Tool sofort nach dem Starten des Subagenten zurück, daher trägt `tool_response` keine Nutzungsfelder. Es hat stattdessen `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` und `resolvedModel`.1899Auf Claude Code v2.1.271 oder später liefert ein Subagent, der mit dem [`SubagentHandback`](/docs/de/tools-reference)-Tool läuft, das Claude Code im [Auto-Modus](/docs/de/permission-modes#eliminate-prompts-with-auto-mode) bereitstellt, seinen Bericht durch dieses Tool statt ihn als Text zurückzugeben. Das Feld `content` seines `completed`-Ergebnisses trägt dann eine kurze Notiz über diesen Handback statt des Berichts selbst. Um den Bericht zu lesen, passen Sie einen `PreToolUse`- oder `PostToolUse`-Hook auf `SubagentHandback` an und lesen Sie `tool_input.message`.
1585 1900
1586Das Feld `resolvedModel` nennt das Modell, auf dem der Subagent tatsächlich ausgeführt wird, das sich vom Wert `model` in `tool_input` unterscheiden kann. Es erfordert Claude Code v2.1.174 oder später.1901Für Hintergrund-Subagenten gibt das Tool zurück, wenn die Aufgabe in den Hintergrund geht, daher trägt `tool_response` keine Nutzungsfelder: Ein Hintergrund-Start gibt sofort zurück, und eine Vordergrund-Aufgabe, die Claude Code während des Laufs in den Hintergrund stellt, gibt bei diesem Übergang zurück. Es hat `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` und `resolvedModel`.
1902
1903Bei einem `completed`-Ergebnis benennt `resolvedModel` das Modell, auf dem der Subagent gestartet wurde, das sich vom `model`-Wert in `tool_input` unterscheiden kann, wie wenn `availableModels` oder eine andere Überschreibung gilt. Bei einem `async_launched`-Ergebnis benennt `resolvedModel` das Modell, das in Gebrauch ist, wenn der Agent in den Hintergrund geht, daher wird ein Wechsel, der vor dem Backgrounding stattfand, dort widergespiegelt. `modelsUsed` und das Backgrounding-Zeit-`resolvedModel`-Verhalten erfordern Claude Code v2.1.212 oder später.
1587 1904
1588<a id="askuserquestion" />1905<a id="askuserquestion" />
1589 1906
1602 ExitPlanMode1919 ExitPlanMode
1603</h5>1920</h5>
1604 1921
1605Präsentiert einen Plan und fordert den Benutzer auf, ihn zu genehmigen, bevor Claude den [Plan-Modus](/docs/de/permission-modes#analyze-before-you-edit-with-plan-mode) verlässt. Claude schreibt den Plan vor dem Aufruf des Tools in eine Datei auf der Festplatte, daher trägt die wörtliche `tool_input` vom Modell nur `allowedPrompts`. Claude Code injiziert den Plan-Inhalt und den Dateipfad, bevor die Eingabe an Hooks übergeben wird.1922Präsentiert einen Plan und fordert den Benutzer auf, ihn zu genehmigen, bevor Claude den [Plan-Modus](/docs/de/permission-modes#analyze-before-you-edit-with-plan-mode) verlässt. Claude schreibt den Plan vor dem Aufruf des Tools in eine Datei auf der Festplatte, daher trägt die wörtliche `tool_input` vom Modell typischerweise nur `allowedPrompts`. Claude Code injiziert den Plan-Inhalt und den Dateipfad, bevor die Eingabe an Hooks übergeben wird.
1606 1923
1607| Feld | Typ | Beispiel | Beschreibung |1924| Feld | Typ | Beispiel | Beschreibung |
1608| :--------------- | :----------- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1925| :--------------- | :----------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1609| `plan` | Zeichenkette | `"## Refactor auth\n1. Extract..."` | Plan-Inhalt in Markdown. Injiziert aus der Plan-Datei auf der Festplatte |1926| `plan` | Zeichenkette | `"## Refactor auth\n1. Extract..."` | Plan-Inhalt in Markdown. Injiziert aus der Plan-Datei auf der Festplatte |
1610| `planFilePath` | Zeichenkette | `"/Users/.../plans/refactor-auth.md"` | Pfad zur Plan-Datei. Injiziert |1927| `planFilePath` | Zeichenkette | `"/Users/.../plans/refactor-auth.md"` | Pfad zur Plan-Datei. Injiziert |
1611| `allowedPrompts` | Array | `[{"tool": "Bash", "prompt": "run tests"}]` | Optional. Prompt-basierte Berechtigungen, die Claude anfordert, um den Plan zu implementieren, jeweils mit einem `tool`-Namen und einem `prompt`, der die Kategorie der Aktion beschreibt |1928| `allowedPrompts` | Array | `[{"tool": "Bash", "prompt": "run tests"}]` | Veraltet. Claude Code akzeptiert das Feld, ignoriert es aber. Vor v2.1.205 trug es Prompt-basierte Berechtigungen, die Claude anfordert, um den Plan zu implementieren |
1612 1929
1613In `PostToolUse` ist `tool_response` ein Objekt mit `plan`- und `filePath`-Feldern, die den genehmigten Plan enthalten, plus interne Status-Flags. Lesen Sie `tool_response.plan` für den Plan-Inhalt, anstatt die Datei von der Festplatte neu zu lesen.1930In `PostToolUse` ist `tool_response` ein Objekt mit `plan`- und `filePath`-Feldern, die den genehmigten Plan enthalten, plus interne Status-Flags. Lesen Sie `tool_response.plan` für den Plan-Inhalt, anstatt die Datei von der Festplatte neu zu lesen.
1614 1931
1619`PreToolUse`-Hooks können steuern, ob ein Tool-Aufruf fortgesetzt wird. Im Gegensatz zu anderen Hooks, die ein Top-Level-Feld `decision` verwenden, gibt PreToolUse seine Entscheidung in einem `hookSpecificOutput`-Objekt zurück. Dies gibt ihm reichere Kontrolle: vier Ergebnisse (zulassen, verweigern, fragen oder verschieben) plus die Möglichkeit, die Tool-Eingabe vor der Ausführung zu ändern.1936`PreToolUse`-Hooks können steuern, ob ein Tool-Aufruf fortgesetzt wird. Im Gegensatz zu anderen Hooks, die ein Top-Level-Feld `decision` verwenden, gibt PreToolUse seine Entscheidung in einem `hookSpecificOutput`-Objekt zurück. Dies gibt ihm reichere Kontrolle: vier Ergebnisse (zulassen, verweigern, fragen oder verschieben) plus die Möglichkeit, die Tool-Eingabe vor der Ausführung zu ändern.
1620 1937
1621| Feld | Beschreibung |1938| Feld | Beschreibung |
1622| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1939| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1623| `permissionDecision` | `"allow"` umgeht die Berechtigungsaufforderung, außer für [Tools, die Benutzerinteraktion erfordern](#pretooluse-decision-control) und Connector-Tools [die Ihre Organisation auf `ask` gesetzt hat](/docs/de/mcp#organization-controls-on-connector-tools). `"deny"` verhindert den Tool-Aufruf. `"ask"` fordert den Benutzer zur Bestätigung auf. `"defer"` beendet den Hook elegant, damit das Tool später fortgesetzt werden kann. [Deny- und Ask-Regeln](/docs/de/permissions#manage-permissions) gelten weiterhin, wenn ein Hook `"allow"` zurückgibt |1940| `permissionDecision` | `"allow"` umgeht die Berechtigungsaufforderung, außer für die [Aktionen, die kein Modus automatisch genehmigt](/docs/de/permission-modes#actions-no-mode-auto-approves) und für `AskUserQuestion` und `ExitPlanMode`, die [`updatedInput` gepaart mit ihm](#allow-with-updatedinput) benötigen. `"deny"` verhindert den Tool-Aufruf. `"ask"` fordert den Benutzer zur Bestätigung auf. `"defer"` beendet elegant, damit das Tool später fortgesetzt werden kann. [Deny- und Ask-Regeln](/docs/de/permissions#manage-permissions) gelten weiterhin, wenn ein Hook `"allow"` zurückgibt |
1624| `permissionDecisionReason` | Für `"allow"` und `"ask"`, dem Benutzer angezeigt, aber nicht Claude. Für `"deny"`, Claude angezeigt. Für `"defer"`, ignoriert |1941| `permissionDecisionReason` | Für `"allow"` und `"ask"`, dem Benutzer angezeigt, aber nicht Claude. Für `"deny"`, Claude angezeigt. Für `"defer"`, ignoriert |
1625| `updatedInput` | Ändert die Tool-Eingabeparameter vor der Ausführung. Ersetzt das gesamte Eingabeobjekt, daher müssen Sie unveränderte Felder zusammen mit geänderten einbeziehen. Kombinieren Sie mit `"allow"`, um automatisch zu genehmigen, oder mit `"ask"`, um die geänderte Eingabe dem Benutzer zu zeigen. Für `"defer"`, ignoriert |1942| `updatedInput` | Ändert die Tool-Eingabeparameter vor der Ausführung. Ersetzt das gesamte Eingabeobjekt, daher müssen Sie unveränderte Felder zusammen mit geänderten einbeziehen. Claude Code evaluiert Berechtigungsregeln und die [Auto-Background-Berechtigung](/docs/de/tools-reference#background-commands) eines Bash-Befehls gegen die Eingabe, die Ihr Hook zurückgibt, nicht die Eingabe, die Claude gesendet hat. Kombinieren Sie mit `"allow"`, um automatisch zu genehmigen, oder mit `"ask"`, um die geänderte Eingabe dem Benutzer zu zeigen. Für `"defer"`, ignoriert |
1626| `additionalContext` | Zeichenkette, die zu Claudes Kontext vor der Tool-Ausführung hinzugefügt wird. Für `"defer"`, ignoriert. Siehe [Kontext für Claude hinzufügen](#add-context-for-claude) |1943| `additionalContext` | Zeichenkette, die zu Claudes Kontext zusammen mit dem Tool-Ergebnis hinzugefügt wird. Ignoriert, wenn `permissionDecision` `"defer"` ist. Siehe [Kontext für Claude hinzufügen](#add-context-for-claude) |
1627 1944
1628Wenn mehrere PreToolUse-Hooks unterschiedliche Entscheidungen zurückgeben, ist die Priorität `deny` > `defer` > `ask` > `allow`.1945Wenn mehrere PreToolUse-Hooks unterschiedliche Entscheidungen zurückgeben, ist die Priorität `deny` > `defer` > `ask` > `allow`.
1629 1946
1630Wenn ein Hook `"ask"` zurückgibt, enthält der dem Benutzer angezeigte Berechtigungsprompt ein Label, das angibt, woher der Hook stammt: zum Beispiel `[User]`, `[Project]`, `[Plugin]` oder `[Local]`. Dies hilft Benutzern zu verstehen, welche Konfigurationsquelle eine Bestätigung anfordert.1947Ein Hook, der durch Beenden mit 2 blockiert, wird auf die gleiche Weise wie `"deny"` weitergeleitet: Claude sieht die stderr-Nachricht als Verweigerungsgrund.
1948
1949Wenn ein Hook `"ask"` zurückgibt, enthält der dem Benutzer angezeigte Berechtigungsprompt ein Label, das angibt, woher der Hook stammt: `[settings]` für einen Hook aus einer beliebigen Einstellungsdatei oder aus Agent-Frontmatter, `[plugin:<name>]` für einen Hook eines Plugins oder `[skill]` für einen Hook aus Skill-Frontmatter. Dies hilft Benutzern zu verstehen, welche Konfigurationsquelle eine Bestätigung anfordert.
1950
1951Ein Hook-`"ask"` erzwingt auch einen Berechtigungsprompt im [Auto-Modus](/docs/de/permission-modes#eliminate-prompts-with-auto-mode): Der Klassifizierer kann den Tool-Aufruf immer noch verweigern, kann ihn aber nicht stillschweigend genehmigen. Vor v2.1.211 konnte der Klassifizierer einen Bash-Befehl, der außerhalb der [Sandbox](/docs/de/sandboxing) läuft, ohne den Prompt zu zeigen, den der Hook anfordert, genehmigen; der Klassifizierer wendete immer noch seine eigenen Sicherheitsregeln auf diesen Befehl an, und ein Hook `"deny"` wurde immer respektiert.
1631 1952
1632```json theme={null}1953```json theme={null}
1633{1954{
1643}1964}
1644```1965```
1645 1966
1646`AskUserQuestion` und `ExitPlanMode` erfordern Benutzerinteraktion und blockieren normalerweise im [nicht-interaktiven Modus](/docs/de/headless) mit dem `-p`-Flag. Das Zurückgeben von `permissionDecision: "allow"` zusammen mit `updatedInput` erfüllt diese Anforderung: Der Hook liest die Tool-Eingabe von stdin, erfasst die Antwort über Ihre eigene Benutzeroberfläche und gibt sie in `updatedInput` zurück, damit das Tool ohne Aufforderung ausgeführt wird. Das Zurückgeben von `"allow"` allein ist nicht ausreichend für diese Tools. Für `AskUserQuestion` geben Sie das ursprüngliche `questions`-Array zurück und fügen Sie ein [`answers`](#askuserquestion)-Objekt hinzu, das jede Frage auf die gewählte Antwort abbildet.1967<span id="allow-with-updatedinput" />
1647 1968
1648Connector-Tools [die Ihre Organisation auf `ask` gesetzt hat](/docs/de/mcp#organization-controls-on-connector-tools) fordern auch dann auf, wenn ein Hook `"allow"` zurückgibt.1969Im [nicht-interaktiven Modus](/docs/de/headless) mit dem `-p`-Flag bietet Claude Code `AskUserQuestion` und `ExitPlanMode` nur an, wenn der Lauf einen [Berechtigungs-Host](/docs/de/headless#turn-off-permission-prompts-in-unattended-runs) hat, um den Prompt zu empfangen, wie einen Agent SDK `canUseTool`-Callback. Diese Tools erfordern Benutzerinteraktion. Das Zurückgeben von `permissionDecision: "allow"` zusammen mit `updatedInput` erfüllt diese Anforderung: Der Hook liest die Tool-Eingabe von stdin, erfasst die Antwort durch Ihre eigene Benutzeroberfläche und gibt sie in `updatedInput` zurück, damit das Tool ohne Aufforderung ausgeführt wird. Das Zurückgeben von `"allow"` allein ist nicht ausreichend für diese Tools. Für `AskUserQuestion` geben Sie das ursprüngliche `questions`-Array zurück und fügen Sie ein [`answers`](#askuserquestion)-Objekt hinzu, das jede Frage auf die gewählte Antwort abbildet.
1649 1970
1650Ab v2.1.199 ist ein MCP-Tool, dessen Server es mit [`_meta["anthropic/requiresUserInteraction"]`](/docs/de/mcp#require-approval-for-a-specific-tool) markiert, strenger: Ein Hook kann seine Genehmigungsaufforderung nicht mit `"allow"` überspringen, mit oder ohne `updatedInput`, da Claude Code nicht bestätigen kann, dass der Hook die Interaktion erfasst hat, die das Tool benötigt.1971Ab v2.1.199 ist ein MCP-Tool, dessen Server es mit [`_meta["anthropic/requiresUserInteraction"]`](/docs/de/mcp#require-approval-for-a-specific-tool) markiert, strenger: Ein Hook kann seine Genehmigungsaufforderung nicht mit `"allow"` überspringen, mit oder ohne `updatedInput`, da Claude Code nicht bestätigen kann, dass der Hook die Interaktion erfasst hat, die das Tool benötigt.
1651 1972
1659 1980
1660`"defer"` ist für Integrationen, die `claude -p` als Subprozess ausführen und seine JSON-Ausgabe lesen, wie eine Agent SDK-App oder eine benutzerdefinierte Benutzeroberfläche, die auf Claude Code aufgebaut ist. Es ermöglicht diesem aufrufenden Prozess, Claude bei einem Tool-Aufruf zu pausieren, Eingaben über seine eigene Schnittstelle zu erfassen und dort fortzufahren, wo er aufgehört hat. Claude Code respektiert diesen Wert nur im [nicht-interaktiven Modus](/docs/de/headless) mit dem `-p`-Flag. In interaktiven Sitzungen protokolliert es eine Warnung und ignoriert das Hook-Ergebnis.1981`"defer"` ist für Integrationen, die `claude -p` als Subprozess ausführen und seine JSON-Ausgabe lesen, wie eine Agent SDK-App oder eine benutzerdefinierte Benutzeroberfläche, die auf Claude Code aufgebaut ist. Es ermöglicht diesem aufrufenden Prozess, Claude bei einem Tool-Aufruf zu pausieren, Eingaben über seine eigene Schnittstelle zu erfassen und dort fortzufahren, wo er aufgehört hat. Claude Code respektiert diesen Wert nur im [nicht-interaktiven Modus](/docs/de/headless) mit dem `-p`-Flag. In interaktiven Sitzungen protokolliert es eine Warnung und ignoriert das Hook-Ergebnis.
1661 1982
1662Das Tool `AskUserQuestion` ist der typische Fall: Claude möchte den Benutzer etwas fragen, aber es gibt kein Terminal zum Antworten. Der Roundtrip funktioniert so:1983Das Tool `AskUserQuestion` ist der typische Fall: Claude möchte den Benutzer etwas fragen, aber es gibt kein Terminal zum Antworten. Ein Lauf mit einem [Berechtigungs-Host](/docs/de/headless#turn-off-permission-prompts-in-unattended-runs) bietet `AskUserQuestion` an, daher starten Sie den Lauf mit einem. Der Roundtrip funktioniert so:
1663 1984
16641. Claude ruft `AskUserQuestion` auf. Der `PreToolUse`-Hook wird ausgelöst.19851. Claude ruft `AskUserQuestion` auf. Der `PreToolUse`-Hook wird ausgelöst.
16652. Der Hook gibt `permissionDecision: "defer"` zurück. Das Tool wird nicht ausgeführt. Der Prozess beendet sich mit `stop_reason: "tool_deferred"` und dem ausstehenden Tool-Aufruf, der im Transkript erhalten bleibt.19862. Der Hook gibt `permissionDecision: "defer"` zurück. Das Tool wird nicht ausgeführt. Der Prozess beendet sich mit `stop_reason: "tool_deferred"` und dem ausstehenden Tool-Aufruf, der im Transkript erhalten bleibt.
1683}2004}
1684```2005```
1685 2006
1686Es gibt kein Timeout oder Wiederholungslimit. Die Sitzung bleibt auf der Festplatte, bis Sie sie fortsetzen, unterliegt aber der [`cleanupPeriodDays`](/docs/de/settings#available-settings)-Aufbewahrungssweep, die Sitzungsdateien nach 30 Tagen standardmäßig löscht. Wenn die Antwort nicht bereit ist, wenn Sie fortsetzen, kann der Hook erneut `"defer"` zurückgeben und der Prozess beendet sich auf die gleiche Weise. Der aufrufende Prozess steuert, wann die Schleife unterbrochen wird, indem er schließlich `"allow"` oder `"deny"` vom Hook zurückgibt.2007Es gibt kein Timeout oder Wiederholungslimit. Die Sitzung bleibt auf der Festplatte, bis Sie sie fortsetzen, unterliegt aber der [`cleanupPeriodDays`](/docs/de/settings-reference#cleanupperioddays)-Aufbewahrungssweep, die Sitzungsdateien nach 30 Tagen standardmäßig löscht, nach den [Aufbewahrungssweep-Regeln](/docs/de/claude-directory#cleaned-up-automatically). Wenn die Antwort nicht bereit ist, wenn Sie fortsetzen, kann der Hook erneut `"defer"` zurückgeben und der Prozess beendet sich auf die gleiche Weise. Der aufrufende Prozess steuert, wann die Schleife unterbrochen wird, indem er schließlich `"allow"` oder `"deny"` vom Hook zurückgibt.
1687 2008
1688`"defer"` funktioniert nur, wenn Claude einen einzelnen Tool-Aufruf in der Runde macht. Wenn Claude mehrere Tool-Aufrufe gleichzeitig macht, wird `"defer"` mit einer Warnung ignoriert und das Tool wird durch den normalen Berechtigungsfluss fortgesetzt. Die Einschränkung existiert, weil Resume nur einen Tool-Aufruf erneut ausführen kann: Es gibt keine Möglichkeit, einen Aufruf aus einem Batch zu verschieben, ohne die anderen ungelöst zu lassen.2009`"defer"` funktioniert nur, wenn Claude einen einzelnen Tool-Aufruf in der Runde macht. Wenn Claude mehrere Tool-Aufrufe gleichzeitig macht, wird `"defer"` mit einer Warnung ignoriert und das Tool wird durch den normalen Berechtigungsfluss fortgesetzt. Die Einschränkung existiert, weil Resume nur einen Tool-Aufruf erneut ausführen kann: Es gibt keine Möglichkeit, einen Aufruf aus einem Batch zu verschieben, ohne die anderen ungelöst zu lassen.
1689 2010
1690Wenn das verschobene Tool nicht mehr verfügbar ist, wenn Sie fortsetzen, beendet sich der Prozess mit `stop_reason: "tool_deferred_unavailable"` und `is_error: true` bevor der Hook ausgelöst wird. Dies geschieht, wenn ein MCP-Server, der das Tool bereitgestellt hat, für die fortgesetzte Sitzung nicht verbunden ist. Die Nutzlast `deferred_tool_use` ist immer noch enthalten, damit Sie identifizieren können, welches Tool fehlte.2011Wenn das verschobene Tool nicht mehr verfügbar ist, wenn Sie fortsetzen, beendet sich der Prozess mit `stop_reason: "tool_deferred_unavailable"` und `is_error: true` bevor der Hook ausgelöst wird. Dies geschieht, wenn ein MCP-Server, der das Tool bereitgestellt hat, für die fortgesetzte Sitzung nicht verbunden ist. Die Nutzlast `deferred_tool_use` ist immer noch enthalten, damit Sie identifizieren können, welches Tool fehlte.
1691 2012
1692<Note>2013<Note>
1693 `--resume` stellt den Berechtigungsmodus wieder her, der aktiv war, als das Tool verschoben wurde, daher müssen Sie `--permission-mode` nicht erneut übergeben. Die Ausnahmen sind `plan` und `bypassPermissions`, die niemals übertragen werden. Das explizite Übergeben von `--permission-mode` bei der Wiederaufnahme überschreibt den wiederhergestellten Wert.2014 Um eine verschobene Sitzung im Plan-Modus fortzusetzen, übergeben Sie [`--permission-prompt-tool`](/docs/de/cli-reference#cli-flags) zusammen mit `--resume`, damit Claude Code den Plan zur Genehmigung präsentieren kann. Ohne es stellt Claude Code den Plan-Modus nicht wieder her. Erfordert Claude Code v2.1.246 oder später.
2015
2016 Wenn Sie mit `-p` fortsetzen, stellt Claude Code keinen anderen gespeicherten Berechtigungsmodus wieder her. Es startet den Lauf im Berechtigungsmodus, den ein neuer `claude -p`-Lauf starten würde, daher übergeben Sie `--permission-mode` oder `--dangerously-skip-permissions` erneut, wenn die verschobene Sitzung einen verwendet hat. Wenn Sie mit `claude --resume <session-id>` ohne `-p` fortsetzen, stellt Claude Code den gespeicherten Berechtigungsmodus wieder her, mit den Ausnahmen, die in [Berechtigungsmodus bei Wiederaufnahme](/docs/de/sessions#permission-mode-on-resume) aufgelistet sind.
1694</Note>2017</Note>
1695 2018
1696<h3 id="permissionrequest">2019<h3 id="permissionrequest">
1697 PermissionRequest2020 PermissionRequest
1698</h3>2021</h3>
1699 2022
1700Wird ausgeführt, wenn dem Benutzer ein Berechtigungsdialog angezeigt wird.2023Wird ausgeführt, wenn Claude Code Sie um Genehmigung für die Verwendung eines Tools bitten soll. In Sitzungen, die keinen Prompt anzeigen können, wie Hintergrund-Subagenten im [nicht-interaktiven Modus](/docs/de/headless), führt Claude Code diese Hooks immer noch aus, und wenn kein Hook eine Entscheidung zurückgibt, verweigert es den Tool-Aufruf.
1701Verwenden Sie [PermissionRequest-Entscheidungskontrolle](#permissionrequest-decision-control), um im Namen des Benutzers zuzulassen oder zu verweigern.2024Verwenden Sie [PermissionRequest-Entscheidungskontrolle](#permissionrequest-decision-control), um im Namen des Benutzers zuzulassen oder zu verweigern.
1702 2025
2026Verwenden Sie dieses Ereignis, wenn Sie ein Signal benötigen, in dem Moment, in dem Claude um Genehmigung zur Verwendung eines Tools bittet. Claude Code führt einen [Notification](#notification)-Hook mit dem Typ `permission_prompt` nur aus, nachdem der Prompt etwa sechs Sekunden gewartet hat.
2027
2028Claude Code führt PermissionRequest-Hooks nicht für eine Sandbox-Befehl-[Netzwerkanfrage](/docs/de/sandboxing#network-isolation) aus. Um ein Signal für diesen Prompt zu erhalten, verwenden Sie den Benachrichtigungstyp `permission_prompt`.
2029
1703Passt auf Tool-Namen, gleiche Werte wie PreToolUse.2030Passt auf Tool-Namen, gleiche Werte wie PreToolUse.
1704 2031
1705<h4 id="permissionrequest-input">2032<h4 id="permissionrequest-input">
1706 PermissionRequest-Eingabe2033 PermissionRequest-Eingabe
1707</h4>2034</h4>
1708 2035
1709PermissionRequest-Hooks erhalten `tool_name`- und `tool_input`-Felder wie PreToolUse-Hooks, aber ohne `tool_use_id`. Ein optionales Array `permission_suggestions` enthält die Optionen „Immer zulassen", die der Benutzer normalerweise im Berechtigungsdialog sehen würde. Der Unterschied liegt darin, wann der Hook ausgelöst wird: PermissionRequest-Hooks werden ausgeführt, wenn ein Berechtigungsdialog dem Benutzer angezeigt werden soll, während PreToolUse-Hooks vor der Tool-Ausführung unabhängig vom Berechtigungsstatus ausgeführt werden.2036PermissionRequest-Hooks erhalten `tool_name`- und `tool_input`-Felder wie PreToolUse-Hooks, aber ohne `tool_use_id`. Für ein MCP-Tool erhalten sie auch das [`mcp_server`](#pretooluse-input)-Objekt. Ein optionales Array `permission_suggestions` enthält die [Berechtigungsupdates](#permission-update-entries), die Claude Code für diese Anfrage vorschlägt, wie das Hinzufügen einer Allow-Regel oder das Ändern des Berechtigungsmodus.
2037
2038Das Array `permission_suggestions` ist keine genaue Liste der Optionen, die Sie sehen, da jeder Berechtigungsdialog seine eigenen Optionen erstellt. Einige Dialoge, wie der für Datei-Bearbeitungen, lesen das Array überhaupt nicht und leiten ihre Optionen aus der Anfrage selbst ab. Ein Dialog, der es liest, kann immer noch eine Option zurückhalten, deren Vorschlag im Array bleibt, zum Beispiel wenn [`allowManagedPermissionRulesOnly`](/docs/de/settings-reference#allowmanagedpermissionrulesonly) Regel-Speicher-Optionen verbirgt. Es kann auch Optionen anbieten, die keinen Vorschlag-Eintrag haben, wie [**Ja, und zum Auto-Modus wechseln**](/docs/de/permission-modes#switch-permission-modes), das den Berechtigungsmodus direkt ändert, anstatt durch ein Berechtigungsupdate.
2039
2040PreToolUse-Hooks werden vor jedem Tool-Aufruf ausgeführt, ob er Genehmigung benötigt oder nicht. PermissionRequest-Hooks werden nur ausgeführt, wenn Claude Code Sie um Genehmigung bitten soll, oder wenn es sonst einen Aufruf automatisch verweigern würde, der nicht auffordern kann. Keines der Ereignisse wird für [`EndConversation`](/docs/de/tools-reference#endconversation-tool-behavior) ausgelöst.
1710 2041
1711```json theme={null}2042```json theme={null}
1712{2043{
1745| `message` | Nur für `"deny"`: teilt Claude mit, warum die Berechtigung verweigert wurde |2076| `message` | Nur für `"deny"`: teilt Claude mit, warum die Berechtigung verweigert wurde |
1746| `interrupt` | Nur für `"deny"`: wenn `true`, stoppt Claude |2077| `interrupt` | Nur für `"deny"`: wenn `true`, stoppt Claude |
1747 2078
2079Ein Hook, der mit 2 beendet wird, ohne ein `decision`-Objekt zu hinterlassen, lässt den Berechtigungsfluss unverändert, und sein stderr wird verworfen. Nur das `decision`-Objekt kann die Anfrage gewähren oder verweigern.
2080
1748```json theme={null}2081```json theme={null}
1749{2082{
1750 "hookSpecificOutput": {2083 "hookSpecificOutput": {
1775| `removeDirectories` | `directories`, `destination` | Entfernt Arbeitsverzeichnisse |2108| `removeDirectories` | `directories`, `destination` | Entfernt Arbeitsverzeichnisse |
1776 2109
1777<Note>2110<Note>
1778 `setMode` mit `bypassPermissions` nimmt nur Auswirkungen an, wenn die Sitzung mit Bypass-Modus bereits verfügbar gestartet wurde: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` oder `permissions.defaultMode: "bypassPermissions"` in Einstellungen, und der Modus ist nicht durch [`permissions.disableBypassPermissionsMode`](/docs/de/permissions#managed-settings) deaktiviert. Andernfalls ist das Update ein No-Op. `bypassPermissions` wird niemals als `defaultMode` persistiert, unabhängig von `destination`.2111 `setMode` mit `bypassPermissions` nimmt nur Auswirkungen an, wenn Sie die Sitzung mit Bypass-Modus bereits verfügbar gestartet haben: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` oder `permissions.defaultMode: "bypassPermissions"` in [Benutzer-, `--settings`- oder verwalteten Einstellungen](/docs/de/settings-reference#permissions-defaultmode). Andernfalls ist das Update ein No-Op. Das Update ist auch ein No-Op, wenn [`permissions.disableBypassPermissionsMode`](/docs/de/permissions#managed-settings) den Modus deaktiviert oder wenn die Sitzung im [eingeschränkten Modus](/docs/de/cli-reference#cli-flags) startet.
2112
2113 `bypassPermissions` wird niemals als `defaultMode` persistiert, unabhängig von `destination`.
1779</Note>2114</Note>
1780 2115
1781Das Feld `destination` auf jedem Eintrag bestimmt, ob die Änderung im Speicher bleibt oder in einer Einstellungsdatei persistiert wird.2116Das Feld `destination` auf jedem Eintrag bestimmt, ob die Änderung im Speicher bleibt oder in einer Einstellungsdatei persistiert wird.
1787| `projectSettings` | `.claude/settings.json` |2122| `projectSettings` | `.claude/settings.json` |
1788| `userSettings` | `~/.claude/settings.json` |2123| `userSettings` | `~/.claude/settings.json` |
1789 2124
1790Ein Hook kann eines der `permission_suggestions` widerspiegeln, die er als seine eigene `updatedPermissions`-Ausgabe erhalten hat, was gleichbedeutend mit der Auswahl dieser Option „Immer zulassen" durch den Benutzer im Dialog ist.2125Ein Hook kann eines der `permission_suggestions` widerspiegeln, die er als seine eigene `updatedPermissions`-Ausgabe erhalten hat.
1791 2126
1792<h3 id="posttooluse">2127<h3 id="posttooluse">
1793 PostToolUse2128 PostToolUse
1797 2132
1798Passt auf Tool-Namen, gleiche Werte wie PreToolUse.2133Passt auf Tool-Namen, gleiche Werte wie PreToolUse.
1799 2134
2135Passen Sie breiter an, wenn der Tool-Name nicht der richtige Filter ist:
2136
2137* Um einen Hook nach jedem erfolgreichen Tool-Abschluss auszuführen, lassen Sie den `matcher` weg oder setzen Sie ihn auf `"*"`. Ihr Hook kann dann selbst entdecken, was sich geändert hat, zum Beispiel durch Ausführung von `git status --porcelain`, das auch unverfolgten Dateien auflistet, die `git diff` vermisst. Für fehlgeschlagene Tool-Aufrufe fügen Sie den gleichen Hook unter [PostToolUseFailure](#posttoolusefailure) hinzu.
2138* Um einen Hook auszuführen, wenn sich eine bestimmte Datei auf der Festplatte ändert, egal was sie geschrieben hat, verwenden Sie [FileChanged](#filechanged). Claude Code führt keinen `PostToolUse`-Hook aus, der `Edit|Write` passt, wenn ein `Bash`-Befehl oder ein Prozess außerhalb von Claude Code die gleiche Datei umschreibt.
2139
1800<h4 id="posttooluse-input">2140<h4 id="posttooluse-input">
1801 PostToolUse-Eingabe2141 PostToolUse-Eingabe
1802</h4>2142</h4>
1803 2143
1804`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 Ergebnis, das es zurückgegeben hat. Das genaue Schema für beide hängt vom Tool ab.2144`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 Ergebnis, das es zurückgegeben hat. Das genaue Schema für beide hängt vom Tool ab. Datei-Tool-`tool_input`-Pfade kommen im gleichen Format wie für [PreToolUse](#pretooluse-input) an: immer absolut, mit den nativen Trennzeichen der Plattform, daher Backslashes unter Windows. Für ein MCP-Tool trägt die Eingabe auch das [`mcp_server`](#pretooluse-input)-Objekt.
1805 2145
1806```json theme={null}2146```json theme={null}
1807{2147{
1817 },2157 },
1818 "tool_response": {2158 "tool_response": {
1819 "filePath": "/path/to/file.txt",2159 "filePath": "/path/to/file.txt",
1820 "success": true2160 "type": "create"
1821 },2161 },
1822 "tool_use_id": "toolu_01ABC123...",2162 "tool_use_id": "toolu_01ABC123...",
1823 "duration_ms": 122163 "duration_ms": 12
1835`PostToolUse`-Hooks können Claude nach der Tool-Ausführung Feedback geben. Zusätzlich zu den [JSON-Ausgabefeldern](#json-output), die für alle Hooks verfügbar sind, kann Ihr Hook-Skript diese ereignisspezifischen Felder zurückgeben:2175`PostToolUse`-Hooks können Claude nach der Tool-Ausführung Feedback geben. Zusätzlich zu den [JSON-Ausgabefeldern](#json-output), die für alle Hooks verfügbar sind, kann Ihr Hook-Skript diese ereignisspezifischen Felder zurückgeben:
1836 2176
1837| Feld | Beschreibung |2177| Feld | Beschreibung |
1838| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |2178| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1839| `decision` | `"block"` fügt den `reason` neben dem Tool-Ergebnis hinzu. Claude sieht immer noch die ursprüngliche Ausgabe; um sie zu ersetzen, verwenden Sie `updatedToolOutput` |2179| `decision` | `"block"` fügt den `reason` neben dem Tool-Ergebnis hinzu. Claude sieht immer noch die ursprüngliche Ausgabe; um sie zu ersetzen, verwenden Sie `updatedToolOutput` |
1840| `reason` | Erklärung, die Claude angezeigt wird, wenn `decision` `"block"` ist |2180| `reason` | Erklärung, die Claude angezeigt wird, wenn `decision` `"block"` ist |
1841| `additionalContext` | Zeichenkette, die zu Claudes Kontext zusammen mit dem Tool-Ergebnis hinzugefügt wird. Siehe [Kontext für Claude hinzufügen](#add-context-for-claude) |2181| `additionalContext` | Zeichenkette, die zu Claudes Kontext zusammen mit dem Tool-Ergebnis hinzugefügt wird. Siehe [Kontext für Claude hinzufügen](#add-context-for-claude) |
2182| `classifierContext` | Kurze Notiz über das Ergebnis dieses Aufrufs für den [Auto-Modus](/docs/de/permission-modes#eliminate-prompts-with-auto-mode)-Klassifizierer statt für Claude. Siehe [Annotieren Sie ein Ergebnis für den Auto-Modus-Klassifizierer](#annotate-a-result-for-the-auto-mode-classifier). Erfordert Claude Code v2.1.236 oder später |
1842| `updatedToolOutput` | Ersetzt die Ausgabe des Tools durch den bereitgestellten Wert vor dem Senden an Claude. Der Wert muss der Ausgabeform des Tools entsprechen |2183| `updatedToolOutput` | Ersetzt die Ausgabe des Tools durch den bereitgestellten Wert vor dem Senden an Claude. Der Wert muss der Ausgabeform des Tools entsprechen |
1843| `updatedMCPToolOutput` | Ersetzt die Ausgabe nur für [MCP-Tools](#match-mcp-tools). Bevorzugen Sie `updatedToolOutput`, das für alle Tools funktioniert |2184| `updatedMCPToolOutput` | Ersetzt die Ausgabe nur für [MCP-Tools](#match-mcp-tools). Bevorzugen Sie `updatedToolOutput`, das für alle Tools funktioniert |
1844 2185
1865 Der Ersatzwert muss der Ausgabeform des Tools entsprechen. Eingebaute Tools geben strukturierte Objekte anstelle von einfachen Zeichenketten zurück. Zum Beispiel gibt `Bash` ein Objekt mit `stdout`-, `stderr`-, `interrupted`- und `isImage`-Feldern zurück. Für eingebaute Tools wird ein Wert, der nicht dem Ausgabeschema des Tools entspricht, ignoriert und die ursprüngliche Ausgabe wird verwendet. MCP-Tool-Ausgabe wird ohne Schema-Validierung durchgeleitet. Das Entfernen von Fehlerdetails, die Claude benötigt, kann dazu führen, dass er bei einer falschen Annahme fortfährt.2206 Der Ersatzwert muss der Ausgabeform des Tools entsprechen. Eingebaute Tools geben strukturierte Objekte anstelle von einfachen Zeichenketten zurück. Zum Beispiel gibt `Bash` ein Objekt mit `stdout`-, `stderr`-, `interrupted`- und `isImage`-Feldern zurück. Für eingebaute Tools wird ein Wert, der nicht dem Ausgabeschema des Tools entspricht, ignoriert und die ursprüngliche Ausgabe wird verwendet. MCP-Tool-Ausgabe wird ohne Schema-Validierung durchgeleitet. Das Entfernen von Fehlerdetails, die Claude benötigt, kann dazu führen, dass er bei einer falschen Annahme fortfährt.
1866</Warning>2207</Warning>
1867 2208
2209<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2210 Annotieren Sie ein Ergebnis für den Auto-Modus-Klassifizierer
2211</h4>
2212
2213Geben Sie `classifierContext` zurück, um eine kurze Notiz über das Ergebnis des Tool-Aufrufs an den [Auto-Modus](/docs/de/permission-modes#eliminate-prompts-with-auto-mode)-Klassifizierer statt an Claude zu senden. Der Klassifizierer [erhält niemals Tool-Ergebnisse selbst](/docs/de/permission-modes#how-the-classifier-evaluates-actions), daher ist dieses Feld die unterstützte Methode, um ihm etwas über das, was ein Aufruf zurückgegeben hat, zu sagen, bevor es später Aktionen überprüft. Das Feld erfordert Claude Code v2.1.236 oder später.
2214
2215Das Beispiel unten teilt dem Klassifizierer mit, woher die Ausgabe einer Abfrage kam:
2216
2217```json theme={null}
2218{
2219 "hookSpecificOutput": {
2220 "hookEventName": "PostToolUse",
2221 "classifierContext": "This query ran against the staging database, not production."
2222 }
2223}
2224```
2225
2226Wie viel Gewicht der Klassifizierer der Notiz gibt, hängt davon ab, wo Sie den Hook konfiguriert haben:
2227
2228* **Hooks, die in Claude Code konfiguriert sind**: Für Hooks aus Einstellungsdateien, Plugins, Skills und Agent-Frontmatter behandelt der Klassifizierer die Notiz als nicht überprüften, von der Anwendung bereitgestellten Kontext. Die Notiz stellt niemals Benutzerabsicht fest, und wenn sie behauptet, Sie hätten etwas genehmigt oder angefordert, überprüft der Klassifizierer diese Behauptung gegen Ihre eigenen Nachrichten in der Konversation
2229* **In-Process Agent SDK-Callbacks**: Wenn eine Anwendung, die Claude Code einbettet, den Hook als [TypeScript SDK-Callback](/docs/de/agent-sdk/hooks) registriert und die Notiz während der Live-Sitzung zurückgibt, kann der Klassifizierer eine Benutzeraussage, die in der Notiz weitergeleitet wird, als Benutzerabsicht gewichten. Eine solche Aussage kann eine Zustimmungsanforderung erfüllen, die der Klassifizierer von einer Nachricht akzeptieren würde, die Sie senden, aber sie hebt niemals einen Block auf, den Ihre eigene Nachricht nicht heben könnte. Nach einer Sitzungswiederaufnahme behandelt Claude Code wiederhergestellte Notizen als nicht überprüften Kontext. Wenn Hooks aus beiden Gruppen den gleichen Aufruf annotieren, behandelt der Klassifizierer die kombinierte Notiz als nicht überprüft
2230
2231Claude Code wendet diese Grenzen an, wenn die Notiz bereitgestellt wird:
2232
2233* **Länge**: Claude Code begrenzt die Notizen für einen Tool-Aufruf auf 2.000 Zeichen und schneidet den Rest ab. Die Obergrenze wird über jeden Hook geteilt, der auf diesen Aufruf antwortet
2234* **Nur synchrone Antworten**: Claude Code ignoriert das Feld in der Antwort eines Hooks, der [im Hintergrund läuft](#run-hooks-in-the-background), da diese Antwort ankommt, nachdem Claude Code das Tool-Ergebnis aufgezeichnet hat
2235* **Aufrufe, die der Klassifizierer nicht aufzeichnet**: Das Klassifizierer-Transkript lässt schreibgeschützte Lookups wie Datei-Lesevorgänge und Suchen weg. Claude Code verwirft eine Notiz, die an einen dieser Aufrufe angehängt ist
2236* **Interaktion mit Umschreibungen**: Wenn die Notiz Ausgabe beschreibt, die Sie mit `updatedToolOutput` ersetzen, geben Sie beide Felder in der gleichen Hook-Antwort zurück. Claude Code lässt die Notiz fallen, wenn diese Umschreibung abgelehnt wird oder eine andere Hook-Umschreibung sie ersetzt. Claude Code liefert eine Notiz, die Sie ohne Umschreibung zurückgeben, auch wenn ein anderer Hook die Ausgabe umschreibt
2237
2238<Warning>
2239 Der Klassifizierer liest Inhalte, die Sie in `classifierContext` einfügen, als Informationen vom Anwendungs-Host der Sitzung, daher kopieren Sie nicht unvertrauenswürdige Tool-Ausgabe oder Text von Drittanbietern hinein. Halten Sie die Notiz auf eine kurze Aussage über diesen einen Aufruf, wie eine Tatsache über seinen Ursprung oder eine Benutzeraussage darüber; verwenden Sie das Feld nicht, um unabhängige Nachrichten oder einen Strom von Ereignissen zu liefern.
2240</Warning>
2241
1868<h3 id="posttoolusefailure">2242<h3 id="posttoolusefailure">
1869 PostToolUseFailure2243 PostToolUseFailure
1870</h3>2244</h3>
1881 PostToolUseFailure-Eingabe2255 PostToolUseFailure-Eingabe
1882</h4>2256</h4>
1883 2257
1884PostToolUseFailure-Hooks erhalten die gleichen `tool_name`- und `tool_input`-Felder wie PostToolUse, zusammen mit Fehlerinformationen als Top-Level-Felder:2258PostToolUseFailure-Hooks erhalten die gleichen `tool_name`- und `tool_input`-Felder wie PostToolUse, zusammen mit Fehlerinformationen als Top-Level-Felder. Für ein MCP-Tool erhalten sie auch das [`mcp_server`](#pretooluse-input)-Objekt. Zum Beispiel könnte ein fehlgeschlagener `npm test`-Befehl liefern:
1885 2259
1886```json theme={null}2260```json theme={null}
1887{2261{
1896 "description": "Run test suite"2270 "description": "Run test suite"
1897 },2271 },
1898 "tool_use_id": "toolu_01ABC123...",2272 "tool_use_id": "toolu_01ABC123...",
1899 "error": "Command exited with non-zero status code 1",2273 "error": "Exit code 1\nError: Cannot find module 'express'",
1900 "is_interrupt": false,2274 "is_interrupt": false,
1901 "duration_ms": 41872275 "duration_ms": 4187
1902}2276}
1903```2277```
1904 2278
1905| Feld | Beschreibung |2279| Feld | Beschreibung |
1906| :------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |2280| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1907| `error` | Zeichenkette, die beschreibt, was schief gelaufen ist |2281| `error` | Zeichenkette, die beschreibt, was schief gelaufen ist. Das Format hängt vom Tool ab, das fehlgeschlagen ist |
1908| `is_interrupt` | Optionaler Boolesch, der angibt, ob der Fehler durch Benutzerunterbrechung verursacht wurde |2282| `is_interrupt` | Optionaler Boolesch. True, wenn der Fehler Claude Code als Abbruch erreichte, anstatt als Fehler, den das Tool meldete. Das Abbrechen eines laufenden Tools löst diesen Hook nicht aus; das Tool-Ergebnis trägt die Abbruch-Nachricht statt |
1909| `duration_ms` | Optional. Tool-Ausführungszeit in Millisekunden. Schließt Zeit aus, die in Berechtigungsaufforderungen und PreToolUse-Hooks verbracht wird |2283| `duration_ms` | Optional. Tool-Ausführungszeit in Millisekunden. Schließt Zeit aus, die in Berechtigungsaufforderungen und PreToolUse-Hooks verbracht wird |
1910 2284
2285Die `error`-Zeichenkette ist im Allgemeinen der gleiche Text, den Claude als Ergebnis des fehlgeschlagenen Tools erhält. Sein Format variiert je nach Tool und Fehler. Schlüsseln Sie Ihren Hook auf `tool_name`, `is_interrupt` und die erste Zeile `Exit code N`; behandeln Sie den Rest der Zeichenkette als Anzeigetext, nicht als stabiles Format.
2286
2287* Für Bash und PowerShell erzeugt ein Befehl, der ausgeführt wurde und beendet wurde, eine erste Zeile `Exit code N`, dann jede Ausgabe, die der Befehl als einen Block mit stdout und stderr vermischt erzeugte
2288* Eine Nutzlast kann auch eine bloße Fehlermeldung ohne Exit-Code-Zeile tragen, wenn Claude Code den Shell-Prozess selbst nicht starten konnte
2289* Claude Code schneidet lange Zeichenketten in der Mitte um einen `... [N characters truncated] ...`-Marker ab und kann Zeilen einfügen, wie `Command timed out after 2m 0s`
2290
1911<h4 id="posttoolusefailure-decision-control">2291<h4 id="posttoolusefailure-decision-control">
1912 PostToolUseFailure-Entscheidungskontrolle2292 PostToolUseFailure-Entscheidungskontrolle
1913</h4>2293</h4>
1966`tool_response` enthält den gleichen Inhalt, den das Modell im entsprechenden `tool_result`-Block erhält. Der Wert ist eine serialisierte Zeichenkette oder ein Content-Block-Array, genau wie das Tool es ausgegeben hat. Für `Read` bedeutet das Zeilennummern-Präfix-Text anstelle von rohen Dateiinhalten. Antworten können groß sein, daher analysieren Sie nur die Felder, die Sie benötigen.2346`tool_response` enthält den gleichen Inhalt, den das Modell im entsprechenden `tool_result`-Block erhält. Der Wert ist eine serialisierte Zeichenkette oder ein Content-Block-Array, genau wie das Tool es ausgegeben hat. Für `Read` bedeutet das Zeilennummern-Präfix-Text anstelle von rohen Dateiinhalten. Antworten können groß sein, daher analysieren Sie nur die Felder, die Sie benötigen.
1967 2347
1968<Note>2348<Note>
1969 Die Form von `tool_response` unterscheidet sich von der von `PostToolUse`. `PostToolUse` übergibt das strukturierte `Output`-Objekt des Tools, wie `{filePath: "...", success: true}` für `Write`; `PostToolBatch` übergibt den serialisierten `tool_result`-Inhalt, den das Modell sieht.2349 Die Form von `tool_response` unterscheidet sich von der von `PostToolUse`. `PostToolUse` übergibt das strukturierte `Output`-Objekt des Tools, wie `{filePath: "...", type: "create"}` für `Write`; `PostToolBatch` übergibt den serialisierten `tool_result`-Inhalt, den das Modell sieht.
1970</Note>2350</Note>
1971 2351
1972<h4 id="posttoolbatch-decision-control">2352<h4 id="posttoolbatch-decision-control">
1988}2368}
1989```2369```
1990 2370
1991Das Zurückgeben von `decision: "block"` oder `continue: false` stoppt die agentengesteuerte Schleife vor dem nächsten Modell-Aufruf.2371Das Zurückgeben von `decision: "block"` oder `continue: false` stoppt die agentengesteuerte Schleife vor dem nächsten Modell-Aufruf. Die Blockierungsmeldung kommt aus dem JSON `reason` oder `stopReason` oder aus stderr bei Beendigung mit 2. Sie sehen sie als Warnung im Transkript, und sie bleibt in der Konversation, daher sieht Claude sie, wenn die Konversation fortgesetzt wird.
1992 2372
1993<h3 id="permissiondenied">2373<h3 id="permissiondenied">
1994 PermissionDenied2374 PermissionDenied
1995</h3>2375</h3>
1996 2376
1997Wird ausgeführt, wenn der [Auto-Mode](/docs/de/permission-modes#eliminate-prompts-with-auto-mode)-Klassifizierer einen Tool-Aufruf verweigert. Dieser Hook wird nur im Auto-Mode ausgelöst: Er wird nicht ausgeführt, wenn Sie einen Berechtigungsdialog manuell verweigern, wenn ein `PreToolUse`-Hook einen Aufruf blockiert oder wenn eine `deny`-Regel passt. Verwenden Sie ihn, um Klassifizierer-Ablehnungen zu protokollieren, die Konfiguration anzupassen oder dem Modell zu sagen, dass es den Tool-Aufruf möglicherweise erneut versuchen kann.2377Wird ausgeführt, wenn der [Auto-Modus](/docs/de/permission-modes#eliminate-prompts-with-auto-mode)-Klassifizierer einen Tool-Aufruf verweigert, einschließlich wenn er verweigert, ohne ein Klassifizierer-Urteil zu haben, weil [eine Sicherheitsprüfung, die von Auto-Modus getrennt ist, die Anfrage des Klassifizierers selbst verweigerte](/docs/de/errors#auto-mode-cannot-determine-the-safety-of-an-action) oder seine Antwort nicht geparst wurde. Dieser Hook wird nur im Auto-Modus ausgelöst: Er wird nicht ausgeführt, wenn Sie einen Berechtigungsdialog manuell verweigern, wenn ein `PreToolUse`-Hook einen Aufruf blockiert oder wenn eine `deny`-Regel passt. Verwenden Sie ihn, um Klassifizierer-Ablehnungen zu protokollieren, die Konfiguration anzupassen oder dem Modell zu sagen, dass es den Tool-Aufruf möglicherweise erneut versuchen kann.
1998 2378
1999Passt auf Tool-Namen, gleiche Werte wie PreToolUse.2379Passt auf Tool-Namen, gleiche Werte wie PreToolUse.
2000 2380
2002 PermissionDenied-Eingabe2382 PermissionDenied-Eingabe
2003</h4>2383</h4>
2004 2384
2005Zusätzlich zu den [gemeinsamen Eingabefeldern](#common-input-fields) erhalten PermissionDenied-Hooks `tool_name`, `tool_input`, `tool_use_id` und `reason`.2385Zusätzlich zu den [gemeinsamen Eingabefeldern](#common-input-fields) erhalten PermissionDenied-Hooks `tool_name`, `tool_input`, `tool_use_id` und `reason`. Für ein MCP-Tool erhalten sie auch das [`mcp_server`](#pretooluse-input)-Objekt.
2006 2386
2007```json theme={null}2387```json theme={null}
2008{2388{
2017 "description": "Clean build directory"2397 "description": "Clean build directory"
2018 },2398 },
2019 "tool_use_id": "toolu_01ABC123...",2399 "tool_use_id": "toolu_01ABC123...",
2020 "reason": "Auto mode denied: command targets a path outside the project"2400 "reason": "[Irreversible Local Destruction]"
2021}2401}
2022```2402```
2023 2403
2024| Feld | Beschreibung |2404| Feld | Beschreibung |
2025| :------- | :------------------------------------------------------------------------ |2405| :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2026| `reason` | Die Erklärung des Klassifizierers, warum der Tool-Aufruf verweigert wurde |2406| `reason` | Der Verweigerungsgrund. Für ein Klassifizierer-Urteil benennt es in den meisten Sitzungen die passende Regel in Klammern, wie `[Data Exfiltration]`; siehe [Verweigerungen überprüfen](/docs/de/auto-mode-config#review-denials) für die anderen Formen. Für eine [Verweigerung ohne Urteil](#permissiondenied-decision-control) beginnt es mit `Auto mode could not evaluate this action and is blocking it for safety`. Für eine Verweigerung, weil das Klassifizierer-Modell nicht verfügbar war, ist es der feste Text `Classifier unavailable` |
2027 2407
2028<h4 id="permissiondenied-decision-control">2408<h4 id="permissiondenied-decision-control">
2029 PermissionDenied-Entscheidungskontrolle2409 PermissionDenied-Entscheidungskontrolle
2042 2422
2043Wenn `retry` `true` ist, fügt Claude Code eine Nachricht zum Gespräch hinzu, die dem Modell mitteilt, dass es den Tool-Aufruf möglicherweise erneut versuchen kann. Die Ablehnung selbst wird nicht rückgängig gemacht. Wenn Ihr Hook keine JSON zurückgibt oder `retry: false` zurückgibt, bleibt die Ablehnung bestehen und das Modell erhält die ursprüngliche Ablehnungsmeldung.2423Wenn `retry` `true` ist, fügt Claude Code eine Nachricht zum Gespräch hinzu, die dem Modell mitteilt, dass es den Tool-Aufruf möglicherweise erneut versuchen kann. Die Ablehnung selbst wird nicht rückgängig gemacht. Wenn Ihr Hook keine JSON zurückgibt oder `retry: false` zurückgibt, bleibt die Ablehnung bestehen und das Modell erhält die ursprüngliche Ablehnungsmeldung.
2044 2424
2425Claude Code ignoriert `retry: true`, wenn der Klassifizierer [kein Urteil über die Aktion erzeugt hat](/docs/de/errors#auto-mode-cannot-determine-the-safety-of-an-action): Seine Antwort hat nicht geparst oder eine Sicherheitsprüfung, die von Auto-Modus getrennt ist, verweigerte die Anfrage des Klassifizierers selbst. Für diese Verweigerungen teilt Claude Code dem Modell in der Ablehnungsmeldung bereits mit, ob es später erneut versuchen soll oder weitermachen soll.
2426
2045<h3 id="notification">2427<h3 id="notification">
2046 Notification2428 Notification
2047</h3>2429</h3>
2048 2430
2049Wird ausgeführt, wenn Claude Code Benachrichtigungen sendet. Passt auf Benachrichtigungstyp. Matcher weglassen, um Hooks für alle Benachrichtigungstypen auszuführen.2431Wird ausgeführt, wenn Claude Code Benachrichtigungen sendet. Passt auf Benachrichtigungstyp. Matcher weglassen, um Hooks für alle Benachrichtigungstypen auszuführen.
2050 2432
2433Sie erhalten diese Hook-Ereignisse auch mit ausgeschalteten Desktop-Benachrichtigungen: Die `preferredNotifChannel`-Einstellung, einschließlich `notifications_disabled`, ändert nur, wie Sie benachrichtigt werden, nicht ob Ihr Hook ausgeführt wird.
2434
2051| Matcher | Wann es ausgelöst wird |2435| Matcher | Wann es ausgelöst wird |
2052| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |2436| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2053| `permission_prompt` | Claude benötigt Ihre Genehmigung für einen Tool-Aufruf |2437| `permission_prompt` | Claude benötigt Ihre Genehmigung für einen Tool-Aufruf oder eine Sandbox-Befehl-[Netzwerkanfrage](/docs/de/sandboxing#network-isolation), und der Prompt hat etwa sechs Sekunden gewartet |
2054| `idle_prompt` | Claude ist fertig und wartet auf Ihren nächsten Prompt |2438| `idle_prompt` | Claude ist vor etwa 60 Sekunden fertig und Sie haben nicht seitdem getippt |
2055| `auth_success` | Authentifizierung ist abgeschlossen |2439| `auth_success` | Authentifizierung ist abgeschlossen |
2056| `elicitation_dialog` | Ein MCP-Server öffnet ein Elicitation-Formular |2440| `elicitation_dialog` | Ein MCP-Server öffnet ein Elicitation-Formular und Sie haben nicht seitdem getippt |
2057| `elicitation_complete` | Ein MCP-Elicitation-Formular wird eingereicht oder verworfen |2441| `elicitation_url_dialog` | Ein MCP-Server fordert Sie auf, eine Browser-URL zu öffnen und Sie haben nicht seitdem getippt |
2442| `elicitation_complete` | Ein MCP-Server meldet, dass eine [URL-Mode-Elicitation](#elicitation-input) abgeschlossen ist |
2058| `elicitation_response` | Eine MCP-Elicitation-Antwort wird an den Server zurückgesendet |2443| `elicitation_response` | Eine MCP-Elicitation-Antwort wird an den Server zurückgesendet |
2059| `agent_needs_input` | Eine Hintergrund-Sitzung beginnt, auf Ihre Eingabe zu warten. Wird nur ausgelöst, während [Agent-Ansicht](/docs/de/agent-view) in einem Terminal offen ist |2444| `agent_needs_input` | Eine Hintergrund-Sitzung beginnt, auf Ihre Eingabe zu warten, während [Agent-Ansicht](/docs/de/agent-view) in einem Terminal offen ist, oder die aktuelle Sitzung stellt eine [Agent-Team-Teammate-Terminal-Setup-Frage](/docs/de/agent-teams#choose-a-display-mode) und Sie haben nicht seitdem getippt |
2060| `agent_completed` | Eine Hintergrund-Sitzung wird fertig oder schlägt fehl. Wird nur ausgelöst, während [Agent-Ansicht](/docs/de/agent-view) in einem Terminal offen ist |2445| `agent_completed` | Eine Hintergrund-Sitzung wird fertig oder schlägt fehl. Wird nur ausgelöst, während [Agent-Ansicht](/docs/de/agent-view) in einem Terminal offen ist |
2446| `quota_auto_resume_fired` | Claude Code setzt Ihre Aufgabe fort, nachdem ein claude.ai-Nutzungslimit sie pausiert hat: beim Reset oder früher, wenn etwas, das Sie in Claude Code tun, wie das Hinzufügen von Nutzungsguthaben, das Upgrade Ihres Plans oder das Wechseln von Modellen, Nutzung wieder verfügbar macht, mit der [Modell-Einstellung-Ausnahme](/docs/de/interactive-mode#wait-for-a-usage-limit-to-reset) |
2447| `quota_auto_resume_stale` | Ein claude.ai-Nutzungslimit wurde zurückgesetzt, während Ihr Computer für mehr als etwa 30 Minuten schlief. Claude Code wartet darauf, dass Sie `Enter` drücken, statt fortzufahren. Nach einem kürzeren Schlaf wird fortgesetzt und `quota_auto_resume_fired` statt |
2448| `quota_auto_resume_disabled` | Claude Code beendet sein Warten auf ein claude.ai-Nutzungslimit, ohne Ihre Aufgabe fortzusetzen: [`autoContinueAtUsageLimit`](/docs/de/settings-reference#autocontinueatusagelimit) wurde ausgeschaltet oder der Reset rückte während eines Wartens, das Claude Code selbst gestartet hat, mehr als 24 Stunden in die Zukunft, die fortgesetzte Aufgabe traf weiterhin das Limit oder die Fortsetzung wurde blockiert, bevor sie das Modell erreichte. Wird nicht ausgelöst, wenn Sie `Esc` oder `Ctrl+C` drücken oder **Nicht automatisch fortsetzen** wählen |
2061 2449
2062Die Typen `agent_needs_input` und `agent_completed` erfordern Claude Code v2.1.198 oder später.2450Die Typen `agent_needs_input` und `agent_completed` erfordern Claude Code v2.1.198 oder später.
2063 2451
2452Die Typen `quota_auto_resume_fired`, `quota_auto_resume_stale` und `quota_auto_resume_disabled` erfordern Claude Code v2.1.234 oder später.
2453
2454In Terminal-Sitzungen erfordert `permission_prompt` für eine Sandbox-Befehl-Netzwerkanfrage Claude Code v2.1.246 oder später.
2455
2456`agent_needs_input` für eine Teammate-Terminal-Setup-Frage erfordert Claude Code v2.1.248 oder später.
2457
2458<Note>
2459 Die Typen `permission_prompt`, `idle_prompt`, `elicitation_dialog` und `elicitation_url_dialog` teilen ihr Timing mit Desktop-Benachrichtigungen, daher sehen Sie sie in Terminal-Sitzungen nur, wenn Sie vom Terminal weg zu sein scheinen:
2460
2461 * Erwarten Sie `permission_prompt`, sobald Sie etwa sechs Sekunden nicht getippt haben. Der Timer startet, wenn der Berechtigungsprompt erscheint, und jeder Tastendruck verschiebt ihn. Um einen Hook sofort auszuführen, wenn Claude um Genehmigung zur Verwendung eines Tools bittet, verwenden Sie stattdessen [PermissionRequest](#permissionrequest).
2462 * Erwarten Sie `idle_prompt` etwa 60 Sekunden, nachdem Claude fertig ist, und nur wenn Sie seitdem nicht getippt haben. Claude Code sendet `idle_prompt` nicht, während es auf ein claude.ai-Nutzungslimit wartet. Wenn das Warten auf eigene Faust endet, wird stattdessen einer der `quota_auto_resume_*`-Typen ausgelöst.
2463 * Erwarten Sie `elicitation_dialog` für ein Elicitation-Formular oder `elicitation_url_dialog` für eine Browser-URL-Anfrage, sobald Sie etwa sechs Sekunden nicht getippt haben. Beide teilen das gleiche Sechs-Sekunden-Gate wie `permission_prompt`: Der Timer startet, wenn der Dialog erscheint, und jeder Tastendruck verschiebt ihn.
2464
2465 Eine Berechtigungsanfrage oder Elicitation, die ankommt, während ein anderer Dialog auf dem Bildschirm ist, behält das gleiche Sechs-Sekunden-Gate, zeitlich von wenn die Anfrage ankommt. Seine Benachrichtigung kann Sie erreichen, während die Anfrage immer noch hinter dem offenen Dialog wartet.
2466</Note>
2467
2468Claude Code zeitlich `permission_prompt` anders in Sitzungen, in denen es Berechtigungsanfragen an den Agent SDK [`canUseTool`-Callback](/docs/de/agent-sdk/user-input) sendet, was ist, wie Claude Desktop und die VS Code-Erweiterung Claude Code hosten:
2469
2470* Erwarten Sie `permission_prompt` etwa sechs Sekunden, nachdem Claude um Genehmigung bittet. Claude Code verschiebt es nicht, während Sie tippen.
2471* Wenn Sie oder ein [PermissionRequest](#permissionrequest)-Hook früher antworten, führt Claude Code `permission_prompt` nicht aus.
2472* Setzen Sie [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/de/env-vars) auf `1`, um `permission_prompt` in diesen Sitzungen auszuschalten.
2473
2474Vor v2.1.233 wurde `permission_prompt` in diesen Sitzungen nicht ausgelöst.
2475
2064Verwenden Sie separate Matcher, um verschiedene Handler je nach Benachrichtigungstyp auszuführen. Diese Konfiguration löst ein berechtigungsspezifisches Warnungsskript aus, wenn Claude Genehmigung benötigt, und eine andere Benachrichtigung, wenn Claude untätig war:2476Verwenden Sie separate Matcher, um verschiedene Handler je nach Benachrichtigungstyp auszuführen. Diese Konfiguration löst ein berechtigungsspezifisches Warnungsskript aus, wenn Claude Genehmigung benötigt, und eine andere Benachrichtigung, wenn Claude untätig war:
2065 2477
2066```json theme={null}2478```json theme={null}
2108}2520}
2109```2521```
2110 2522
2111Notification-Hooks können Benachrichtigungen nicht blockieren oder ändern. Sie sind für Nebenwirkungen wie das Weiterleiten der Benachrichtigung an einen externen Service vorgesehen. Die [gemeinsamen JSON-Ausgabefelder](#json-output) wie `systemMessage` gelten.2523Notification-Hooks können Benachrichtigungen nicht blockieren oder ändern. Claude Code verwirft ihre `systemMessage` und `continue`-Felder, aber gibt immer noch [`terminalSequence`](#emit-terminal-notifications) aus, auf das sich das Desktop-Benachrichtigungs-Beispiel verlässt. Notification-Hooks sind für Nebenwirkungen wie das Weiterleiten der Benachrichtigung an einen externen Service vorgesehen.
2112 2524
2113<h3 id="subagentstart">2525<h3 id="subagentstart">
2114 SubagentStart2526 SubagentStart
2115</h3>2527</h3>
2116 2528
2117Wird ausgeführt, wenn ein Claude Code-Subagent über das Agent-Tool spawnt wird. Unterstützt Matcher zum Filtern nach Agent-Typname. Für eingebaute Agents ist dies der Agent-Name wie `general-purpose`, `Explore` oder `Plan`. Für [benutzerdefinierte Subagenten](/docs/de/sub-agents) ist dies das Feld `name` aus dem Frontmatter des Agenten, nicht der Dateiname.2529Wird ausgeführt, wenn Claude einen Subagenten mit dem Agent-Tool spawnt, wenn Claude [einen Subagenten fortsetzt](/docs/de/sub-agents#resume-subagents) und jedes Mal, wenn ein In-Process-[Agent-Team](/docs/de/agent-teams)-Teammate eine neue Nachricht handhabt. Unterstützt Matcher zum Filtern nach Agent-Typname. Für eingebaute Agents ist dies der Agent-Name wie `general-purpose`, `Explore` oder `Plan`. Für [benutzerdefinierte Subagenten](/docs/de/sub-agents) ist dies das Feld `name` aus dem Frontmatter des Agenten, nicht der Dateiname.
2118 2530
2119Für Subagenten, die von einem [Plugin](/docs/de/plugins) bereitgestellt werden, ist der Agent-Typ die Plugin-spezifische Kennung wie `my-plugin:reviewer`, nicht der bloße Frontmatter-Name. Der Doppelpunkt platziert einen Plugin-spezifischen Namen auf dem regulären Ausdruckspfad, daher verankern Sie den Matcher mit `^` und `$` für eine genaue Übereinstimmung: `^my-plugin:reviewer$`.2531Für Subagenten, die von einem [Plugin](/docs/de/plugins) bereit gestellt werden, ist der Agent-Typ die Plugin-spezifische Kennung wie `my-plugin:reviewer`, nicht der bloße Frontmatter-Name. Der Doppelpunkt platziert einen Plugin-spezifischen Namen auf dem regulären Ausdruckspfad, daher verankern Sie den Matcher mit `^` und `$` für eine genaue Übereinstimmung: `^my-plugin:reviewer$`.
2120 2532
2121<h4 id="subagentstart-input">2533<h4 id="subagentstart-input">
2122 SubagentStart-Eingabe2534 SubagentStart-Eingabe
2150}2562}
2151```2563```
2152 2564
2565Wenn der Hook erneut für den gleichen Subagenten ausgeführt wird, injiziert Claude Code den zurückgegebenen Kontext nur, wenn der Kontext des Subagenten nicht bereits die Kopie aus einem früheren Lauf hält. Die Kopie, die beim Start injiziert wurde, bleibt an Ort und Stelle, wobei der [Prompt-Cache](/docs/de/prompt-caching#subagents-and-the-cache) des Subagenten intakt bleibt. Nach [Auto-Komprimierung](/docs/de/sub-agents#auto-compaction), die diese Kopie verwirft, injiziert Claude Code den Kontext des nächsten Laufs erneut.
2566
2153<h3 id="subagentstop">2567<h3 id="subagentstop">
2154 SubagentStop2568 SubagentStop
2155</h3>2569</h3>
2162 2576
2163Zusätzlich zu den [gemeinsamen Eingabefeldern](#common-input-fields) 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 zum Filtern von Matchern verwendet wird. Der `transcript_path` ist das Transkript der Hauptsitzung, während `agent_transcript_path` das eigene Transkript des Subagenten ist, das in einem verschachtelten `subagents/`-Ordner gespeichert ist. Das Feld `last_assistant_message` enthält den Textinhalt der letzten Antwort des Subagenten, daher können Hooks darauf zugreifen, ohne die Transkript-Datei zu analysieren.2577Zusätzlich zu den [gemeinsamen Eingabefeldern](#common-input-fields) 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 zum Filtern von Matchern verwendet wird. Der `transcript_path` ist das Transkript der Hauptsitzung, während `agent_transcript_path` das eigene Transkript des Subagenten ist, das in einem verschachtelten `subagents/`-Ordner gespeichert ist. Das Feld `last_assistant_message` enthält den Textinhalt der letzten Antwort des Subagenten, daher können Hooks darauf zugreifen, ohne die Transkript-Datei zu analysieren.
2164 2578
2165SubagentStop-Hooks erhalten auch die Arrays `background_tasks` und `session_crons`, die unter [Stop-Eingabe](#stop-input) beschrieben sind, verfügbar in Claude Code v2.1.145 oder später. Beide Arrays sind auf die übergeordnete Sitzung beschränkt, nicht auf den Subagenten.2579Auf Claude Code v2.1.271 oder später liefert ein Subagent, der mit dem [`SubagentHandback`](/docs/de/tools-reference)-Tool läuft, seinen Bericht durch dieses Tool, bevor er stoppt. Das Feld `last_assistant_message` hält dann den Schließtext des Subagenten, falls vorhanden, das ist nicht der gelieferte Bericht. Der Bericht ist die `message`-Eingabe dieses Aufrufs, die ein `PreToolUse`- oder `PostToolUse`-Hook, der auf `SubagentHandback` passt, als `tool_input.message` erhält.
2580
2581SubagentStop-Hooks erhalten auch die Arrays `background_tasks` und `session_crons`, die unter [Stop-Eingabe](#stop-input) beschrieben sind. Beide Arrays sind auf die übergeordnete Sitzung beschränkt, nicht auf den Subagenten.
2166 2582
2167```json theme={null}2583```json theme={null}
2168{2584{
2181}2597}
2182```2598```
2183 2599
2184SubagentStop-Hooks verwenden das gleiche Entscheidungskontrollformat wie [Stop-Hooks](#stop-decision-control), einschließlich `hookSpecificOutput.additionalContext` mit `hookEventName` auf `"SubagentStop"` gesetzt, für Nicht-Fehler-Feedback, das den Subagenten am Laufen hält. Das Zurückgeben von `decision: "block"` mit einem `reason` hält den Subagenten am Laufen und liefert `reason` an den Subagenten als nächste Anweisung. Um Kontext in die übergeordnete Sitzung nach der Rückkehr eines Subagenten einzufügen, verwenden Sie stattdessen einen [`PostToolUse`](#posttooluse)-Hook auf dem `Agent`-Tool.2600SubagentStop-Hooks verwenden das gleiche Entscheidungskontrollformat wie [Stop-Hooks](#stop-decision-control), einschließlich `hookSpecificOutput.additionalContext` mit `hookEventName` auf `"SubagentStop"` gesetzt, für Nicht-Fehler-Feedback, das den Subagenten am Laufen hält. Das Zurückgeben von `decision: "block"` mit einem `reason` hält den Subagenten am Laufen und liefert `reason` an den Subagenten als nächste Anweisung. Ein Hook, der durch Beenden mit 2 blockiert, liefert seine stderr-Nachricht auf die gleiche Weise. Um Kontext in die übergeordnete Sitzung nach der Rückkehr eines Subagenten einzufügen, verwenden Sie stattdessen einen [`PostToolUse`](#posttooluse)-Hook auf dem `Agent`-Tool.
2185 2601
2186<h3 id="taskcreated">2602<h3 id="taskcreated">
2187 TaskCreated2603 TaskCreated
2188</h3>2604</h3>
2189 2605
2190Wird ausgeführt, wenn eine Aufgabe über das `TaskCreate`-Tool erstellt wird. Verwenden Sie dies, um Benennungskonventionen durchzusetzen, Aufgabenbeschreibungen zu erfordern oder zu verhindern, dass bestimmte Aufgaben erstellt werden.2606Wird ausgeführt, wenn eine Aufgabe über das `TaskCreate`-Tool erstellt wird. Verwenden Sie dies, um Benennungskonventionen durchzusetzen, Aufgabenbeschreibungen zu erfordern oder zu verhindern, dass bestimmte Aufgaben erstellt werden. In einer [Sitzung ohne die Task-Tools](/docs/de/tools-reference#task-tool-availability) wird dieses Ereignis nicht ausgelöst.
2191 2607
2192Wenn ein `TaskCreated`-Hook mit Code 2 beendet wird, wird die Aufgabe nicht erstellt und die stderr-Nachricht wird dem Modell als Feedback zurückgegeben. Um den Teammate stattdessen vollständig zu stoppen, geben Sie JSON mit `{"continue": false, "stopReason": "..."}` zurück. TaskCreated-Hooks unterstützen keine Matcher und werden bei jedem Auftreten ausgelöst.2608TaskCreated-Hooks unterstützen keine Matcher und werden bei jedem Auftreten ausgelöst.
2193 2609
2194<h4 id="taskcreated-input">2610<h4 id="taskcreated-input">
2195 TaskCreated-Eingabe2611 TaskCreated-Eingabe
2202 "session_id": "abc123",2618 "session_id": "abc123",
2203 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",2619 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
2204 "cwd": "/Users/...",2620 "cwd": "/Users/...",
2205 "permission_mode": "default",
2206 "hook_event_name": "TaskCreated",2621 "hook_event_name": "TaskCreated",
2207 "task_id": "task-001",2622 "task_id": "task-001",
2208 "task_subject": "Implement user authentication",2623 "task_subject": "Implement user authentication",
2224 TaskCreated-Entscheidungskontrolle2639 TaskCreated-Entscheidungskontrolle
2225</h4>2640</h4>
2226 2641
2227TaskCreated-Hooks unterstützen zwei Möglichkeiten, die Aufgabenerstellung zu steuern:2642Ein TaskCreated-Hook kann die Erstellung auf zwei Wegen blockieren. Auf beide Wegen löscht Claude Code die Aufgabe und gibt Ihre Nachricht an Claude als Fehler des Tools zurück. Claude Code ignoriert `continue: false` aus diesem Ereignis und Claude arbeitet weiter.
2228 2643
2229* **Exit-Code 2**: Die Aufgabe wird nicht erstellt und die stderr-Nachricht wird dem Modell als Feedback zurückgegeben.2644* **Exit-Code 2**: Claude Code gibt den stderr-Text als Nachricht zurück.
2230* **JSON `{"continue": false, "stopReason": "..."}`**: Stoppt den Teammate vollständig, was dem `Stop`-Hook-Verhalten entspricht. Der `stopReason` wird dem Benutzer angezeigt.2645* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code gibt `reason` als Nachricht zurück.
2231 2646
2232Dieses Beispiel blockiert Aufgaben, deren Betreff nicht dem erforderlichen Format entspricht:2647Dieses Beispiel blockiert Aufgaben, deren Betreff nicht dem erforderlichen Format entspricht:
2233 2648
2248 TaskCompleted2663 TaskCompleted
2249</h3>2664</h3>
2250 2665
2251Wird ausgeführt, wenn eine Aufgabe als abgeschlossen markiert wird. Dies wird in zwei Situationen ausgelöst: wenn ein Agent eine Aufgabe explizit über das TaskUpdate-Tool als abgeschlossen markiert, oder wenn ein [Agent-Team](/docs/de/agent-teams)-Teammate seine Runde mit laufenden Aufgaben beendet. Verwenden Sie dies, um Abschluss-Kriterien wie bestandene Tests oder Lint-Checks durchzusetzen, bevor eine Aufgabe geschlossen werden kann.2666Wird ausgeführt, wenn eine Aufgabe als abgeschlossen markiert wird. Dies wird in zwei Situationen ausgelöst: wenn ein Agent eine Aufgabe explizit über das TaskUpdate-Tool als abgeschlossen markiert oder wenn ein [Agent-Team](/docs/de/agent-teams)-Teammate seine Runde mit laufenden Aufgaben beendet. Verwenden Sie dies, um Abschluss-Kriterien wie bestandene Tests oder Lint-Checks durchzusetzen, bevor eine Aufgabe geschlossen werden kann.
2252 2667
2253Wenn ein `TaskCompleted`-Hook mit Code 2 beendet wird, wird die Aufgabe nicht als abgeschlossen markiert und die stderr-Nachricht wird dem Modell als Feedback zurückgegeben. Um den Teammate stattdessen vollständig zu stoppen, geben Sie JSON mit `{"continue": false, "stopReason": "..."}` zurück. TaskCompleted-Hooks unterstützen keine Matcher und werden bei jedem Auftreten ausgelöst.2668TaskCompleted-Hooks unterstützen keine Matcher und werden bei jedem Auftreten ausgelöst.
2254 2669
2255<h4 id="taskcompleted-input">2670<h4 id="taskcompleted-input">
2256 TaskCompleted-Eingabe2671 TaskCompleted-Eingabe
2285 TaskCompleted-Entscheidungskontrolle2700 TaskCompleted-Entscheidungskontrolle
2286</h4>2701</h4>
2287 2702
2288TaskCompleted-Hooks unterstützen zwei Möglichkeiten, den Aufgabenabschluss zu steuern:2703TaskCompleted-Hooks unterstützen zwei Wege zur Steuerung des Aufgabenabschlusses:
2289 2704
2290* **Exit-Code 2**: Die Aufgabe wird nicht als abgeschlossen markiert und die stderr-Nachricht wird dem Modell als Feedback zurückgegeben.2705* **Exit-Code 2**: Die Aufgabe wird nicht als abgeschlossen markiert und die stderr-Nachricht wird dem Modell als Feedback zurückgegeben.
2291* **JSON `{"continue": false, "stopReason": "..."}`**: Stoppt den Teammate vollständig, was dem `Stop`-Hook-Verhalten entspricht. Der `stopReason` wird dem Benutzer angezeigt.2706* **JSON `{"continue": false, "stopReason": "..."}`**: Wenn ein Teammate, das seine Runde beendet, das Ereignis ausgelöst hat, stoppt den Teammate vollständig, was dem `Stop`-Hook-Verhalten entspricht. Der `stopReason` wird dem Benutzer angezeigt. Wenn das `TaskUpdate`-Tool das Ereignis ausgelöst hat, ignoriert Claude Code `continue: false`; Exit-Code 2 blockiert immer noch den Abschluss.
2292 2707
2293Dieses Beispiel führt Tests aus und blockiert den Aufgabenabschluss, wenn sie fehlschlagen:2708Dieses Beispiel führt Tests aus und blockiert den Aufgabenabschluss, wenn sie fehlschlagen:
2294 2709
2322 2737
2323Zusätzlich zu den [gemeinsamen Eingabefeldern](#common-input-fields) 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 als Ergebnis eines Stop-Hooks fortgesetzt wird. Überprüfen Sie diesen Wert oder verarbeiten Sie das Transkript, um zu verhindern, dass Claude Code unbegrenzt läuft. Claude Code überschreibt den Hook und beendet die Runde nach 8 aufeinanderfolgenden Blockierungen.2738Zusätzlich zu den [gemeinsamen Eingabefeldern](#common-input-fields) 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 als Ergebnis eines Stop-Hooks fortgesetzt wird. Überprüfen Sie diesen Wert oder verarbeiten Sie das Transkript, um zu verhindern, dass Claude Code unbegrenzt läuft. Claude Code überschreibt den Hook und beendet die Runde nach 8 aufeinanderfolgenden Blockierungen.
2324 2739
2325Das Feld `last_assistant_message` enthält den Textinhalt von Claudes letzter Antwort, daher können Hooks darauf zugreifen, ohne die Transkript-Datei zu analysieren.2740Das Feld `last_assistant_message` enthält den Textinhalt von Claudes letzter Antwort, daher können Hooks darauf zugreifen, ohne die Transkript-Datei zu analysieren. Für Hooks, die auf die gerade abgeschlossene Runde reagieren, wie Read-Aloud- oder Benachrichtigungs-Hooks, verwenden Sie dieses Feld statt `transcript_path` zu lesen: Die Transkript-Datei ist nicht garantiert, die letzte Nachricht zur Stop-Zeit auf allen Versionen einzubeziehen.
2326 2741
2327Die Arrays `background_tasks` und `session_crons`, verfügbar in Claude Code v2.1.145 oder später, ermöglichen es Hooks, zwischen „Sitzung ist fertig" und „Sitzung ist pausiert und wartet auf Hintergrundarbeit, um sie wieder zu aktivieren" zu unterscheiden. Beide Arrays sind vorhanden, wenn die Task-Registry erreichbar ist, und sind leer, wenn nichts läuft oder geplant ist.2742Die Arrays `background_tasks` und `session_crons` ermöglichen es Hooks, zwischen „Sitzung ist fertig" und „Sitzung ist pausiert und wartet auf Hintergrundarbeit, um sie wieder zu aktivieren" zu unterscheiden. Beide Arrays sind vorhanden, wenn die Task-Registry erreichbar ist, und sind leer, wenn nichts läuft oder geplant ist.
2328 2743
2329Jeder Eintrag in `background_tasks` beschreibt eine laufende Aufgabe und verwendet diese Felder:2744Jeder Eintrag in `background_tasks` beschreibt eine laufende Aufgabe und verwendet diese Felder:
2330 2745
2392| `reason` | Erforderlich, wenn `decision` `"block"` ist. Teilt Claude mit, warum es fortgesetzt werden sollte |2807| `reason` | Erforderlich, wenn `decision` `"block"` ist. Teilt Claude mit, warum es fortgesetzt werden sollte |
2393| `hookSpecificOutput.additionalContext` | Nicht-Fehler-Feedback für Claude. Das Gespräch wird fortgesetzt, damit Claude darauf reagieren kann, aber im Gegensatz zu `decision: "block"` wird es im Transkript als Hook-Feedback statt als Hook-Fehler angezeigt |2808| `hookSpecificOutput.additionalContext` | Nicht-Fehler-Feedback für Claude. Das Gespräch wird fortgesetzt, damit Claude darauf reagieren kann, aber im Gegensatz zu `decision: "block"` wird es im Transkript als Hook-Feedback statt als Hook-Fehler angezeigt |
2394 2809
2810Ein Hook, der durch Beenden mit 2 blockiert, wird auf die gleiche Weise wie `reason` weitergeleitet: Claude erhält die stderr-Nachricht als Erklärung, warum es fortgesetzt werden sollte.
2811
2395```json theme={null}2812```json theme={null}
2396{2813{
2397 "decision": "block",2814 "decision": "block",
2414 StopFailure2831 StopFailure
2415</h3>2832</h3>
2416 2833
2417Wird stattdessen von [Stop](#stop) ausgeführt, wenn die Runde aufgrund eines API-Fehlers endet. Ausgabe und Exit-Code werden ignoriert. Verwenden Sie dies, um Fehler zu protokollieren, Warnungen zu senden oder Wiederherstellungsmaßnahmen zu ergreifen, wenn Claude aufgrund von Ratenlimits, Authentifizierungsproblemen oder anderen API-Fehlern keine Antwort abschließen kann.2834Wird stattdessen von [Stop](#stop) ausgeführt, wenn die Runde aufgrund eines API-Fehlers endet. Claude Code ignoriert die Ausgabe und den Exit-Code des Hooks, außer [`terminalSequence`](#emit-terminal-notifications). Verwenden Sie dies, um Fehler zu protokollieren, Warnungen zu senden oder Wiederherstellungsmaßnahmen zu ergreifen, wenn Claude aufgrund von Ratenlimits, Authentifizierungsproblemen oder anderen API-Fehlern keine Antwort abschließen kann.
2418 2835
2419<h4 id="stopfailure-input">2836<h4 id="stopfailure-input">
2420 StopFailure-Eingabe2837 StopFailure-Eingabe
2424 2841
2425| Feld | Beschreibung |2842| Feld | Beschreibung |
2426| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2843| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2427| `error` | Fehlertyp: `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens` oder `unknown` |2844| `error` | Fehlertyp: `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error` oder `unknown` |
2428| `error_details` | Zusätzliche Details zum Fehler, falls verfügbar |2845| `error_details` | Zusätzliche Details zum Fehler, falls verfügbar |
2429| `last_assistant_message` | Der gerenderte Fehlertext, der in der Konversation angezeigt wird. Im Gegensatz zu `Stop` und `SubagentStop`, wo dieses Feld Claudes Gesprächsausgabe enthält, enthält es für `StopFailure` die API-Fehlerzeichenkette selbst, wie `"API Error: Rate limit reached"` |2846| `last_assistant_message` | Der gerenderte Fehlertext, der in der Konversation angezeigt wird. Im Gegensatz zu `Stop` und `SubagentStop`, wo dieses Feld Claudes Gesprächsausgabe enthält, enthält es für `StopFailure` die API-Fehlerzeichenkette selbst, wie `"API Error: Rate limit reached"` |
2430 2847
2448 2865
2449Wird ausgeführt, wenn ein [Agent-Team](/docs/de/agent-teams)-Teammate nach Abschluss seiner Runde untätig werden soll. Verwenden Sie dies, um Qualitätsgates vor dem Stoppen eines Teammates durchzusetzen, wie das Erfordern von bestandenen Lint-Checks oder das Überprüfen, dass Ausgabedateien vorhanden sind.2866Wird ausgeführt, wenn ein [Agent-Team](/docs/de/agent-teams)-Teammate nach Abschluss seiner Runde untätig werden soll. Verwenden Sie dies, um Qualitätsgates vor dem Stoppen eines Teammates durchzusetzen, wie das Erfordern von bestandenen Lint-Checks oder das Überprüfen, dass Ausgabedateien vorhanden sind.
2450 2867
2451Wenn ein `TeammateIdle`-Hook mit Code 2 beendet wird, erhält der Teammate die stderr-Nachricht als Feedback und arbeitet weiter, anstatt untätig zu werden. Um den Teammate stattdessen vollständig zu stoppen, geben Sie JSON mit `{"continue": false, "stopReason": "..."}` zurück. TeammateIdle-Hooks unterstützen keine Matcher und werden bei jedem Auftreten ausgelöst.2868TeammateIdle-Hooks unterstützen keine Matcher und werden bei jedem Auftreten ausgelöst.
2452 2869
2453<h4 id="teammateidle-input">2870<h4 id="teammateidle-input">
2454 TeammateIdle-Eingabe2871 TeammateIdle-Eingabe
2477 TeammateIdle-Entscheidungskontrolle2894 TeammateIdle-Entscheidungskontrolle
2478</h4>2895</h4>
2479 2896
2480TeammateIdle-Hooks unterstützen zwei Möglichkeiten, das Teammate-Verhalten zu steuern:2897TeammateIdle-Hooks unterstützen zwei Wege zur Steuerung des Teammate-Verhaltens:
2481 2898
2482* **Exit-Code 2**: Der Teammate erhält die stderr-Nachricht als Feedback und arbeitet weiter, anstatt untätig zu werden.2899* **Exit-Code 2**: Der Teammate erhält die stderr-Nachricht als Feedback und arbeitet weiter, anstatt untätig zu werden.
2483* **JSON `{"continue": false, "stopReason": "..."}`**: Stoppt den Teammate vollständig, was dem `Stop`-Hook-Verhalten entspricht. Der `stopReason` wird dem Benutzer angezeigt.2900* **JSON `{"continue": false, "stopReason": "..."}`**: Stoppt den Teammate vollständig, was dem `Stop`-Hook-Verhalten entspricht. Der `stopReason` wird dem Benutzer angezeigt.
2501 2918
2502Wird ausgeführt, wenn sich eine Konfigurationsdatei während einer Sitzung ändert. Verwenden Sie dies, um Einstellungsänderungen zu überprüfen, Sicherheitsrichtlinien durchzusetzen oder nicht autorisierte Änderungen an Konfigurationsdateien zu blockieren.2919Wird ausgeführt, wenn sich eine Konfigurationsdatei während einer Sitzung ändert. Verwenden Sie dies, um Einstellungsänderungen zu überprüfen, Sicherheitsrichtlinien durchzusetzen oder nicht autorisierte Änderungen an Konfigurationsdateien zu blockieren.
2503 2920
2504ConfigChange-Hooks werden für Änderungen an Einstellungsdateien, verwalteten Richtlinieneinstellungen und Skill-Dateien ausgelöst. Das Feld `source` in der Eingabe teilt Ihnen mit, welche Art von Konfiguration sich geändert hat, und das optionale Feld `file_path` gibt den Pfad zur geänderten Datei an.2921Claude Code führt ConfigChange-Hooks aus, wenn sich eine Einstellungsdatei, eine verwaltete Richtlinieneinstellung oder eine Skill-Datei ändert. Für verwaltete Richtlinien wird es nur ausgelöst, wenn `managed-settings.json` oder eine Datei in `managed-settings.d/` sich ändert. Es wendet [Server-verwaltete Einstellungen](/docs/de/server-managed-settings) und Änderungen an macOS-verwalteten Einstellungen oder Windows-Registrierungs-Richtlinien an, ohne sie auszuführen. Auf WSL mit [`wslInheritsWindowsSettings`](/docs/de/settings-reference#wslinheritswindowssettings) wendet es auch eine geänderte Windows-seitige verwaltete Einstellungsdatei bei seiner Richtlinien-Abfrage an, ohne sie auszuführen.
2505 2922
2506Der Matcher filtert auf die Konfigurationsquelle:2923Der Matcher filtert auf die Konfigurationsquelle:
2507 2924
2508| Matcher | Wann es ausgelöst wird |2925| Matcher | Wann es ausgelöst wird |
2509| :----------------- | :------------------------------------------------ |2926| :----------------- | :--------------------------------------------------------------------------- |
2510| `user_settings` | `~/.claude/settings.json` ändert sich |2927| `user_settings` | `~/.claude/settings.json` ändert sich |
2511| `project_settings` | `.claude/settings.json` ändert sich |2928| `project_settings` | `.claude/settings.json` ändert sich |
2512| `local_settings` | `.claude/settings.local.json` ändert sich |2929| `local_settings` | `.claude/settings.local.json` ändert sich |
2513| `policy_settings` | Verwaltete Richtlinieneinstellungen ändern sich |2930| `policy_settings` | `managed-settings.json` oder eine Datei in `managed-settings.d/` ändert sich |
2514| `skills` | Eine Skill-Datei in `.claude/skills/` ändert sich |2931| `skills` | Eine Skill-Datei in `.claude/skills/` ändert sich |
2515 2932
2516Dieses Beispiel protokolliert alle Konfigurationsänderungen für Sicherheitsaudits:2933Dieses Beispiel protokolliert alle Konfigurationsänderungen für Sicherheitsaudits:
2568}2985}
2569```2986```
2570 2987
2571`policy_settings`-Änderungen können nicht blockiert werden. Hooks werden immer noch für `policy_settings`-Quellen ausgelöst, daher können Sie sie für Audit-Protokollierung verwenden, aber jede Blockierungsentscheidung wird ignoriert. Dies stellt sicher, dass von Unternehmen verwaltete Einstellungen immer wirksam werden.2988`policy_settings`-Änderungen können nicht blockiert werden. Hooks werden immer noch für `policy_settings`-Quellen ausgelöst, wenn sich eine verwaltete Einstellungsdatei auf der Maschine ändert, daher können Sie sie für Audit-Protokollierung verwenden, aber jede Blockierungsentscheidung wird ignoriert. Dies stellt sicher, dass von Unternehmen verwaltete Einstellungen immer wirksam werden. Claude Code führt `ConfigChange`-Hooks nicht aus, wenn [Server-verwaltete Einstellungen](/docs/de/server-managed-settings) ankommen oder aktualisiert werden.
2989
2990Claude Code handelt auf die Blockierungsentscheidung aus der JSON-Ausgabe eines ConfigChange-Hooks und verwirft `systemMessage` und `continue`. Eine blockierte Änderung zeigt keine Nachricht für Sie oder Claude, ob Sie mit `reason` oder mit stderr bei Beendigung mit 2 blockieren. Claude Code schreibt nur eine Zeile in das Debug-Protokoll.
2572 2991
2573<h3 id="cwdchanged">2992<h3 id="cwdchanged">
2574 CwdChanged2993 CwdChanged
2575</h3>2994</h3>
2576 2995
2577Wird ausgeführt, wenn das Arbeitsverzeichnis während einer Sitzung wechselt, zum Beispiel wenn Claude einen `cd`-Befehl ausführt. Verwenden Sie dies, um auf Verzeichniswechsel zu reagieren: Laden Sie Umgebungsvariablen neu, aktivieren Sie projektspezifische Toolchains oder führen Sie Setup-Skripte automatisch aus. Paare mit [FileChanged](#filechanged) für Tools wie [direnv](https://direnv.net/), die verzeichnisspezifische Umgebungen verwalten.2996Wird ausgeführt, wenn ein Shell-Befehl in der Hauptkonversation das Arbeitsverzeichnis ändert, zum Beispiel wenn Claude einen `cd`-Befehl ausführt. Verwenden Sie dies, um auf Verzeichniswechsel zu reagieren: Laden Sie Umgebungsvariablen neu, aktivieren Sie projektspezifische Toolchains oder führen Sie Setup-Skripte automatisch aus. Paare mit [FileChanged](#filechanged) für Tools wie [direnv](https://direnv.net/), die verzeichnisspezifische Umgebungen verwalten.
2578 2997
2579CwdChanged-Hooks haben Zugriff auf `CLAUDE_ENV_FILE`. Variablen, die in diese Datei geschrieben werden, bleiben in nachfolgenden Bash-Befehlen für die Sitzung erhalten, genau wie in [SessionStart-Hooks](#persist-environment-variables).2998CwdChanged-Hooks haben Zugriff auf [`CLAUDE_ENV_FILE`](#persist-environment-variables). Variablen, die in diese Datei geschrieben werden, bleiben in nachfolgenden Bash-Befehlen bis zum nächsten CwdChanged-Ereignis erhalten, wenn Claude Code sie löscht.
2580 2999
2581CwdChanged unterstützt keine Matcher und wird bei jedem Verzeichniswechsel ausgelöst.3000CwdChanged unterstützt keine Matcher und wird bei jedem Auftreten ausgelöst.
2582 3001
2583<h4 id="cwdchanged-input">3002<h4 id="cwdchanged-input">
2584 CwdChanged-Eingabe3003 CwdChanged-Eingabe
2609 3028
2610CwdChanged-Hooks haben keine Entscheidungskontrolle. Sie können den Verzeichniswechsel nicht blockieren.3029CwdChanged-Hooks haben keine Entscheidungskontrolle. Sie können den Verzeichniswechsel nicht blockieren.
2611 3030
3031Claude Code liest `watchPaths` und `systemMessage` aus ihrer JSON-Ausgabe und verwirft `continue`. In interaktiven Sitzungen zeigt es die `systemMessage` als kurze Terminal-Benachrichtigung. Die Nachricht erreicht nicht den SDK-Nachrichtenstrom.
3032
3033<h3 id="directoryadded">
3034 DirectoryAdded
3035</h3>
3036
3037Wird ausgeführt, nachdem Sie ein Arbeitsverzeichnis während einer Sitzung mit dem `/add-dir`-Befehl hinzufügen oder nachdem ein SDK-Client eines mit der `register_repo_root`-Steueranfrage hinzufügt. Verwenden Sie dies, um ein neu hinzugefügtes Repository vorzubereiten, zum Beispiel durch Installation seiner Abhängigkeiten.
3038
3039Claude Code führt dieses Ereignis nicht aus, wenn:
3040
3041* Sie ein Verzeichnis mit dem `--add-dir`-Startup-Flag übergeben; [SessionStart](#sessionstart) deckt diese Verzeichnisse ab
3042* Sie ein Verzeichnis auf der `/permissions`-Workspace-Registerkarte hinzufügen
3043* Sie ein Verzeichnis hinzufügen, das bereits ein Arbeitsverzeichnis ist oder sich in einem befindet
3044
3045Claude Code führt DirectoryAdded aus, nachdem die Sandbox- und Berechtigungsstatus aktualisiert wurden, daher sehen Sandbox-Tools das neue Verzeichnis bereits, wenn Ihr Hook läuft. Hook-Befehle selbst laufen unsandboxed.
3046
3047Claude Code wartet nicht auf den Hook: Das Hinzufügen wird sofort abgeschlossen und der Hook läuft im Hintergrund mit dem 600-Sekunden-Standard-Timeout.
3048
3049Der Matcher filtert auf wie das Verzeichnis hinzugefügt wurde:
3050
3051| Matcher | Wann es ausgelöst wird |
3052| :------------------- | :----------------------------------------------------------------------------------- |
3053| `slash_command` | Sie fügen ein Verzeichnis mit `/add-dir` hinzu |
3054| `register_repo_root` | Ein SDK-Client fügt ein Verzeichnis mit der `register_repo_root`-Steueranfrage hinzu |
3055
3056<h4 id="directoryadded-input">
3057 DirectoryAdded-Eingabe
3058</h4>
3059
3060Zusätzlich zu den [gemeinsamen Eingabefeldern](#common-input-fields) erhalten DirectoryAdded-Hooks `directory` und `source`.
3061
3062| Feld | Beschreibung |
3063| :---------- | :---------------------------------------------------------------------------------------------------------------------------- |
3064| `directory` | Absoluter Pfad des Verzeichnisses, das hinzugefügt wurde |
3065| `source` | Wie das Verzeichnis hinzugefügt wurde, `"slash_command"` für `/add-dir` oder `"register_repo_root"` für die SDK-Steueranfrage |
3066
3067```json theme={null}
3068{
3069 "session_id": "abc123",
3070 "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
3071 "cwd": "/Users/my-project",
3072 "hook_event_name": "DirectoryAdded",
3073 "directory": "/Users/my-other-repo",
3074 "source": "slash_command"
3075}
3076```
3077
3078DirectoryAdded-Hooks haben keine Entscheidungskontrolle. Sie können das Hinzufügen nicht blockieren, das bereits abgeschlossen ist, wenn der Hook läuft. Claude Code verwirft das `continue`-Feld aus ihrer JSON-Ausgabe und zeigt den Rest je nach Quelle unterschiedlich an:
3079
3080* `slash_command`: Claude Code liefert die `systemMessage` des Hooks an Claude als Kontext bei der nächsten Konversationsrunde, statt sie Ihnen zu zeigen. Eine Anzahl fehlgeschlagener Hooks erscheint im Transkript. Vollständige Fehlerausgabe geht in das Debug-Protokoll
3081* `register_repo_root`: Claude Code schreibt `systemMessage`-Ausgabe und Fehlerausgabe nur in das Debug-Protokoll
3082
2612<h3 id="filechanged">3083<h3 id="filechanged">
2613 FileChanged3084 FileChanged
2614</h3>3085</h3>
2615 3086
2616Wird ausgeführt, wenn sich eine überwachte Datei auf der Festplatte ändert. Nützlich zum Neuladen von Umgebungsvariablen, wenn Projekt-Konfigurationsdateien geändert werden.3087Wird ausgeführt, wenn sich eine überwachte Datei auf der Festplatte ändert. Claude Code erkennt Änderungen mit einem Dateisystem-Watcher, nicht durch Inspizieren von Tool-Aufrufen, daher wird der Hook ausgelöst, egal was die Datei geändert hat: ein `Edit`- oder `Write`-Tool-Aufruf, ein Skript, das Claude mit `Bash` ausführt, oder ein Prozess außerhalb von Claude Code. Ein häufiger Anwendungsfall ist das Neuladen von Umgebungsvariablen, wenn sich Projekt-Konfigurationsdateien ändern.
2617 3088
2618Das Feld `matcher` für dieses Ereignis dient zwei Zwecken:3089Das Feld `matcher` für dieses Ereignis dient zwei Rollen:
2619 3090
2620* **Erstellen Sie die Überwachungsliste**: Der Wert wird auf `|` aufgeteilt und jedes Segment wird als Dateiname im Arbeitsverzeichnis registriert, daher überwacht `".envrc|.env"` genau diese zwei Dateien. Regex-Muster sind hier nicht nützlich: Ein Wert wie `^\.env` würde eine Datei überwachen, die buchstäblich `^\.env` heißt.3091* **Erstellen Sie die Überwachungsliste**: Der Wert wird auf `|` aufgeteilt und jedes Segment wird als Dateiname im Arbeitsverzeichnis registriert, daher überwacht `".envrc|.env"` genau diese zwei Dateien. Regex-Muster sind hier nicht nützlich: Ein Wert wie `^\.env` würde eine Datei überwachen, die buchstäblich `^\.env` heißt.
2621* **Filtern Sie, welche Hooks ausgeführt werden**: Wenn sich eine überwachte Datei ändert, wird der gleiche Wert verwendet, um zu filtern, welche Hook-Gruppen ausgeführt werden, wobei die Standard-[Matcher-Regeln](#matcher-patterns) gegen den Basename der geänderten Datei verwendet werden.3092* **Filtern Sie, welche Hooks ausgeführt werden**: Wenn sich eine überwachte Datei ändert, wird der gleiche Wert verwendet, um zu filtern, welche Hook-Gruppen ausgeführt werden, wobei die Standard-[Matcher-Regeln](#matcher-patterns) gegen den Basename der geänderten Datei verwendet werden.
2622 3093
2623FileChanged-Hooks haben Zugriff auf `CLAUDE_ENV_FILE`. Variablen, die in diese Datei geschrieben werden, bleiben in nachfolgenden Bash-Befehlen für die Sitzung erhalten, genau wie in [SessionStart-Hooks](#persist-environment-variables).3094Dieses Beispiel normalisiert Zeilenumbrüche in `data.csv` nach jeder Änderung, einschließlich eines `Bash`-Befehls oder eines externen Skripts, das die Datei umschreibt:
3095
3096```json theme={null}
3097{
3098 "hooks": {
3099 "FileChanged": [
3100 {
3101 "matcher": "data.csv",
3102 "hooks": [
3103 {
3104 "type": "command",
3105 "command": "/path/to/normalize-line-endings.sh"
3106 }
3107 ]
3108 }
3109 ]
3110 }
3111}
3112```
3113
3114Der Hook liest den Pfad der geänderten Datei aus dem Feld `file_path` der [JSON-Eingabe](#filechanged-input) auf stdin. Sein `grep`-Guard testet auf das gleiche, das `perl` entfernt, einen CR am Ende einer Zeile, daher beendet der Lauf nach einer Normalisierung, ohne die Datei zu berühren. Ein lockerer Guard schleift für immer, weil `perl -i` die Datei umschreibt, auch wenn es nichts ersetzt, und Claude Code führt den Hook nach jedem Umschreiben erneut aus. Speichern Sie dieses Skript unter `/path/to/normalize-line-endings.sh` und machen Sie es ausführbar:
3115
3116```bash theme={null}
3117#!/bin/bash
3118FILE=$(jq -r .file_path)
3119if grep -q $'\r$' "$FILE"; then
3120 perl -pi -e 's/\r$//' "$FILE"
3121fi
3122```
3123
3124Um zu bestätigen, dass der Hook funktioniert, bitten Sie Claude, eine CRLF-Zeile zu `data.csv` mit einem `Bash`-Befehl anzuhängen. Claude Code führt den Hook aus und die Datei endet mit LF-Umbrüchen.
3125
3126Um Dateien zu überwachen, die Sie nicht im Voraus benennen können, geben Sie [`watchPaths`](#filechanged-output) von einem Hook zurück, um die Überwachungsliste dynamisch zu aktualisieren. Claude Code startet den Watcher nur, wenn etwas eine Datei zum Überwachen benennt, daher seeden Sie die Liste mit einer FileChanged-Gruppe, deren Matcher mindestens eine Datei benennt, oder mit einem [SessionStart](#sessionstart-decision-control)- oder [CwdChanged](#cwdchanged)-Hook, der `watchPaths` zurückgibt. Der Matcher filtert immer noch, welche Hook-Gruppen ausgelöst werden, wenn sich eine überwachte Datei ändert, daher geben Sie der Gruppe, die dynamische Pfade handhabt, einen weggelassenen Matcher, der jede überwachte Datei passt und nichts zur Überwachungsliste hinzufügt. Ein `"*"`-Matcher passt auch auf jede Datei, aber Claude Code registriert ihn in der Überwachungsliste wie jeden anderen Wert, als eine Datei, die buchstäblich `*` heißt.
3127
3128FileChanged-Hooks haben Zugriff auf [`CLAUDE_ENV_FILE`](#persist-environment-variables). Variablen, die in diese Datei geschrieben werden, bleiben in nachfolgenden Bash-Befehlen bis zum nächsten [CwdChanged](#cwdchanged)-Ereignis erhalten, wenn Claude Code sie löscht.
2624 3129
2625<h4 id="filechanged-input">3130<h4 id="filechanged-input">
2626 FileChanged-Eingabe3131 FileChanged-Eingabe
2656 3161
2657FileChanged-Hooks haben keine Entscheidungskontrolle. Sie können die Dateiänderung nicht blockieren.3162FileChanged-Hooks haben keine Entscheidungskontrolle. Sie können die Dateiänderung nicht blockieren.
2658 3163
3164Claude Code liest `watchPaths` und `systemMessage` aus ihrer JSON-Ausgabe und verwirft `continue`. In interaktiven Sitzungen zeigt es die `systemMessage` als kurze Terminal-Benachrichtigung. Die Nachricht erreicht nicht den SDK-Nachrichtenstrom.
3165
2659<h3 id="worktreecreate">3166<h3 id="worktreecreate">
2660 WorktreeCreate3167 WorktreeCreate
2661</h3>3168</h3>
2662 3169
2663Wird ausgeführt, wenn ein Worktree erstellt wird, entweder von `claude --worktree` oder von einem [Subagent mit `isolation: "worktree"`](/docs/de/sub-agents#choose-the-subagent-scope). Standardmäßig erstellt Claude Code die isolierte Arbeitskopie mit `git worktree`. Wenn Sie einen WorktreeCreate-Hook konfigurieren, ersetzt er das Standard-Git-Verhalten und ermöglicht es Ihnen, ein anderes Versionskontrollsystem wie SVN, Perforce oder Mercurial zu verwenden.3170Wird ausgeführt, wenn ein Worktree erstellt wird, entweder von `claude --worktree`, von einem [Subagent mit `isolation: "worktree"`](/docs/de/sub-agents#choose-the-subagent-scope) oder für eine [Hintergrund-Sitzung](/docs/de/agent-view#how-file-edits-are-isolated), die Claude Code in ihrem eigenen Worktree isoliert. Standardmäßig erstellt Claude Code die isolierte Arbeitskopie mit `git worktree`. Wenn Sie einen WorktreeCreate-Hook konfigurieren, ersetzt er das Standard-Git-Verhalten und ermöglicht es Ihnen, ein anderes Versionskontrollsystem wie SVN, Perforce oder Mercurial zu verwenden.
2664 3171
2665Da der Hook das Standard-Verhalten vollständig ersetzt, wird [`.worktreeinclude`](/docs/de/worktrees#copy-gitignored-files-into-worktrees) nicht verarbeitet. Wenn Sie lokale Konfigurationsdateien wie `.env` in den neuen Worktree kopieren müssen, tun Sie dies in Ihrem Hook-Skript.3172Da der Hook das Standard-Verhalten vollständig ersetzt, wird [`.worktreeinclude`](/docs/de/worktrees#copy-gitignored-files-into-worktrees) nicht verarbeitet. Wenn Sie lokale Konfigurationsdateien wie `.env` in den neuen Worktree kopieren müssen, tun Sie dies in Ihrem Hook-Skript.
2666 3173
2667Der Hook muss den absoluten Pfad zum erstellten Worktree-Verzeichnis zurückgeben. Claude Code verwendet diesen Pfad als Arbeitsverzeichnis für die isolierte Sitzung. Siehe [WorktreeCreate-Ausgabe](#worktreecreate-output) für wie jeder Hook-Typ den Pfad zurückgibt.3174Der 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](#worktreecreate-output) für wie jeder Hook-Typ den Pfad zurückgibt.
3175
3176Claude Code handelt auf den Erfolg des Hooks und den zurückgegebenen Pfad und verwirft `systemMessage` und `continue`.
2668 3177
2669Dieses Beispiel erstellt eine SVN-Arbeitskopie und gibt den Pfad aus, damit Claude Code ihn verwenden kann. Ersetzen Sie die Repository-URL durch Ihre eigene:3178Dieses Beispiel erstellt eine SVN-Arbeitskopie und gibt den Pfad aus, damit Claude Code ihn verwenden kann. Ersetzen Sie die Repository-URL durch Ihre eigene:
2670 3179
2714 3223
2715Wenn der Hook fehlschlägt oder keinen Pfad erzeugt, schlägt die Worktree-Erstellung mit einem Fehler fehl.3224Wenn der Hook fehlschlägt oder keinen Pfad erzeugt, schlägt die Worktree-Erstellung mit einem Fehler fehl.
2716 3225
2717Claude Code löst einen relativen Pfad gegen das Verzeichnis auf, in dem der Hook ausgeführt wurde. Wenn der resultierende Pfad kein Verzeichnis ist, das Claude Code betreten kann, druckt die Sitzung einen Fehler, der den Pfad benennt, und beendet sich mit Code 1. Vor v2.1.205 stürzte ein relativer Pfad oder ein Pfad, der nicht auf der Festplatte existierte, die Sitzung beim Start ab, und mit `-p` stagnierte es etwa 30 Sekunden, bevor es mit Code 0 beendet wurde.3226Claude Code löst einen relativen Pfad gegen das Verzeichnis auf, in dem der Hook ausgeführt wurde, und bricht alle `.` oder `..`-Segmente zusammen. Wenn der resultierende Pfad kein Verzeichnis ist, das Claude Code betreten kann, druckt die Sitzung einen Fehler, der den Pfad benennt, und beendet sich mit Code 1.
3227
3228Claude Code verweigert einen absoluten Pfad, der `.` oder `..`-Segmente enthält, und jeden Pfad, der durch einen Symlink unterhalb der Repository-Root geht, da ein Symlink, der zum Repository committed ist, den Worktree außerhalb davon umleiten könnte. Der Fehler benennt die abgelehnte Komponente. Geben Sie einen normalisierten Pfad zurück, der nicht durch einen Symlink innerhalb des Repository geht. Vor v2.1.216 folgte die Worktree-Erstellung dem Hook-Pfad ohne dieses Screening.
2718 3229
2719<h3 id="worktreeremove">3230<h3 id="worktreeremove">
2720 WorktreeRemove3231 WorktreeRemove
2721</h3>3232</h3>
2722 3233
2723Wird ausgeführt, wenn ein Worktree entfernt wird, entweder wenn Sie eine `--worktree`-Sitzung beenden und wählen, sie zu entfernen, oder wenn ein Subagent mit `isolation: "worktree"` fertig ist. Dies ist das Bereinigungspendant zu [WorktreeCreate](#worktreecreate).3234Wird ausgeführt, wenn ein Worktree entfernt wird. Dies ist das Bereinigungspendant zu [WorktreeCreate](#worktreecreate). Das Ereignis wird ausgelöst, wenn:
3235
3236* Sie eine `--worktree`-Sitzung beenden und wählen, sie zu entfernen
3237* Ein Subagent mit `isolation: "worktree"` fertig ist
3238* Sie eine [Hintergrund-Sitzung](/docs/de/agent-view#what-deleting-a-session-removes) löschen, deren Worktree der Hook erstellt hat
2724 3239
2725Für Git-basierte Worktrees handhabt Claude Code die Bereinigung automatisch mit `git worktree remove`. Wenn Sie einen WorktreeCreate-Hook für ein nicht-Git-Versionskontrollsystem konfiguriert haben, koppeln Sie ihn mit einem WorktreeRemove-Hook, um die Bereinigung zu handhaben. Ohne einen wird das Worktree-Verzeichnis auf der Festplatte belassen.3240Für Git-basierte Worktrees handhabt Claude Code die Bereinigung automatisch mit `git worktree remove`. Wenn Sie einen WorktreeCreate-Hook für ein nicht-Git-Versionskontrollsystem konfiguriert haben, koppeln Sie ihn mit einem WorktreeRemove-Hook, um die Bereinigung zu handhaben. Ohne einen wird das Worktree-Verzeichnis auf der Festplatte belassen.
2726 3241
3242Claude Code verwirft die [JSON-Ausgabefelder](#json-output) eines WorktreeRemove-Hooks, wie `systemMessage` und `continue`.
3243
3244Für einen Hintergrund-Sitzungs-Delete überprüft Claude Code den gespeicherten Worktree-Pfad, bevor der Hook ausgelöst wird, und verweigert einen Pfad, der ein Symlink ist oder durch einen unterhalb der Repository-Root geht. Der Hook wird für einen Worktree ausgelöst, der immer noch Dateien enthält, nur wenn Sie den Delete in [Agent-Ansicht](/docs/de/agent-view#what-deleting-a-session-removes) bestätigen; für einen solchen Worktree behält [`claude rm`](/docs/de/agent-view#manage-sessions-from-the-shell) die Sitzung und den Worktree statt. Vor v2.1.216 wurde der Hook auf dem gespeicherten Pfad ohne diese Überprüfungen ausgelöst.
3245
2727Claude Code übergibt den Pfad, den WorktreeCreate zurückgegeben hat, als `worktree_path` in der Hook-Eingabe. Dieses Beispiel liest diesen Pfad und entfernt das Verzeichnis:3246Claude Code übergibt den Pfad, den WorktreeCreate zurückgegeben hat, als `worktree_path` in der Hook-Eingabe. Dieses Beispiel liest diesen Pfad und entfernt das Verzeichnis:
2728 3247
2729```json theme={null}3248```json theme={null}
2759}3278}
2760```3279```
2761 3280
2762WorktreeRemove-Hooks haben keine Entscheidungskontrolle. Sie können die Worktree-Entfernung nicht blockieren, können aber Bereinigungsaufgaben wie das Entfernen von Versionskontrollstatus oder das Archivieren von Änderungen durchführen. Hook-Fehler werden nur im Debug-Modus protokolliert.3281Ein WorktreeRemove-Hook-Exit-Code entscheidet das Ergebnis. Wenn ein Hook mit Nicht-Null beendet wird und das Verzeichnis unter `worktree_path` immer noch danach existiert, schlägt die Entfernung fehl:
3282
3283* Der Worktree bleibt auf der Festplatte, und der Hook-Befehl und stderr gehen in das [Debug-Protokoll](#debug-hooks).
3284* Wenn Sie eine Hintergrund-Sitzung löschen, bleibt die Sitzung auch. Die Verweigerungsmeldung in [Agent-Ansicht](/docs/de/agent-view#what-deleting-a-session-removes) meldet, wie der Hook endete, wie `exited 1`, zitiert den Anfang seines stderr und sagt, ob das Löschen der Sitzung erneut das Verzeichnis entfernt.
2763 3285
2764<h3 id="precompact">3286<h3 id="precompact">
2765 PreCompact3287 PreCompact
2770Der Matcher-Wert gibt an, ob die Komprimierung manuell oder automatisch ausgelöst wurde:3292Der Matcher-Wert gibt an, ob die Komprimierung manuell oder automatisch ausgelöst wurde:
2771 3293
2772| Matcher | Wann es ausgelöst wird |3294| Matcher | Wann es ausgelöst wird |
2773| :------- | :--------------------------------------------------- |3295| :------- | :---------------------------------------------------------------------------------------------------------------------- |
2774| `manual` | `/compact` |3296| `manual` | `/compact` |
2775| `auto` | Auto-Komprimierung, wenn das Kontextfenster voll ist |3297| `auto` | Auto-Komprimierung, wenn das Gespräch das [Auto-Compact-Fenster](/docs/de/model-config#set-the-auto-compact-window) erreicht |
2776 3298
2777Exit mit Code 2, um die Komprimierung zu blockieren. Für ein manuelles `/compact` wird die stderr-Nachricht dem Benutzer angezeigt. Sie können auch blockieren, indem Sie JSON mit `"decision": "block"` zurückgeben.3299Exit mit Code 2, um die Komprimierung zu blockieren. Für ein manuelles `/compact` wird die stderr-Nachricht dem Benutzer angezeigt. Sie können auch blockieren, indem Sie JSON mit `"decision": "block"` zurückgeben.
2778 3300
2779Das Blockieren der automatischen Komprimierung hat unterschiedliche Auswirkungen, je nachdem, wann es ausgelöst wird. Wenn die Komprimierung proaktiv ausgelöst wurde, bevor das Kontextlimit erreicht wurde, überspringt Claude Code sie und das Gespräch wird unkomprimiert fortgesetzt. Wenn die Komprimierung ausgelöst wurde, um sich von einem Kontextlimit-Fehler zu erholen, der bereits von der API zurückgegeben wurde, wird der zugrunde liegende Fehler angezeigt und die aktuelle Anfrage schlägt fehl.3301Das Blockieren der automatischen Komprimierung hat unterschiedliche Auswirkungen, je nachdem, wann es ausgelöst wird. Wenn die Komprimierung proaktiv ausgelöst wurde, bevor das Kontextlimit erreicht wurde, überspringt Claude Code sie und das Gespräch wird unkomprimiert fortgesetzt. Wenn die Komprimierung ausgelöst wurde, um sich von einem Kontextlimit-Fehler zu erholen, der bereits von der API zurückgegeben wurde, wird der zugrunde liegende Fehler angezeigt und die aktuelle Anfrage schlägt fehl.
2780 3302
3303Claude Code verwirft die `systemMessage` und `continue`-Felder eines PreCompact-Hooks.
3304
2781<h4 id="precompact-input">3305<h4 id="precompact-input">
2782 PreCompact-Eingabe3306 PreCompact-Eingabe
2783</h4>3307</h4>
2784 3308
2785Zusätzlich zu den [gemeinsamen Eingabefeldern](#common-input-fields) erhalten PreCompact-Hooks `trigger` und `custom_instructions`. Für `manual` enthält `custom_instructions` das, was der Benutzer in `/compact` übergibt. Für `auto` ist `custom_instructions` leer.3309Zusätzlich zu den [gemeinsamen Eingabefeldern](#common-input-fields) erhalten PreCompact-Hooks `trigger` und `custom_instructions`. Für `manual` enthält `custom_instructions` das, was der Benutzer in `/compact` übergibt und ist `null`, wenn sie nichts übergeben. Für `auto` ist `custom_instructions` `null`.
2786 3310
2787```json theme={null}3311```json theme={null}
2788{3312{
2791 "cwd": "/Users/...",3315 "cwd": "/Users/...",
2792 "hook_event_name": "PreCompact",3316 "hook_event_name": "PreCompact",
2793 "trigger": "manual",3317 "trigger": "manual",
2794 "custom_instructions": ""3318 "custom_instructions": null
2795}3319}
2796```3320```
2797 3321
2799 PostCompact3323 PostCompact
2800</h3>3324</h3>
2801 3325
2802Wird ausgeführt, nachdem Claude Code einen Komprimierungsvorgang abgeschlossen hat. Verwenden Sie dieses Ereignis, um auf den neuen komprimierten Zustand zu reagieren, zum Beispiel um die generierte Zusammenfassung zu protokollieren oder den externen Zustand zu aktualisieren.3326Wird ausgeführt, nachdem Claude Code einen Komprimierungsvorgang abgeschlossen hat. Verwenden Sie dieses Ereignis, um auf den neuen komprimierten Zustand zu reagieren, zum Beispiel um die generierte Zusammenfassung zu protokollieren oder den externen Zustand zu aktualisieren. Claude Code verwirft die `systemMessage` und `continue`-Felder eines PostCompact-Hooks.
2803 3327
2804Die gleichen Matcher-Werte gelten wie für `PreCompact`:3328Die gleichen Matcher-Werte gelten wie für `PreCompact`:
2805 3329
2806| Matcher | Wann es ausgelöst wird |3330| Matcher | Wann es ausgelöst wird |
2807| :------- | :-------------------------------------------------------- |3331| :------- | :--------------------------------------------------------------------------------------------------------------------------- |
2808| `manual` | Nach `/compact` |3332| `manual` | Nach `/compact` |
2809| `auto` | Nach Auto-Komprimierung, wenn das Kontextfenster voll ist |3333| `auto` | Nach Auto-Komprimierung, wenn das Gespräch das [Auto-Compact-Fenster](/docs/de/model-config#set-the-auto-compact-window) erreicht |
2810 3334
2811<h4 id="postcompact-input">3335<h4 id="postcompact-input">
2812 PostCompact-Eingabe3336 PostCompact-Eingabe
2827 3351
2828PostCompact-Hooks haben keine Entscheidungskontrolle. Sie können das Komprimierungsergebnis nicht beeinflussen, können aber Folgaufgaben durchführen.3352PostCompact-Hooks haben keine Entscheidungskontrolle. Sie können das Komprimierungsergebnis nicht beeinflussen, können aber Folgaufgaben durchführen.
2829 3353
3354<h3 id="premodelswitch">
3355 PreModelSwitch
3356</h3>
3357
3358Wird ausgeführt, bevor Claude Code einen Modellwechsel anwendet, den Sie oder ein Client angefordert haben. Verwenden Sie ihn, um einen Wechsel zu blockieren, eine Bestätigung zu erfordern oder zu zeigen, was der Wechsel kostet, bevor er passiert.
3359
3360PreModelSwitch erfordert Claude Code v2.1.251 oder später. Claude Code führt ihn für diese Anfragen aus:
3361
3362* `/model <name>` und der `/model`-Picker
3363* Der `Option+P`- oder `Alt+P`-Modell-Picker
3364* Die Modell-Einstellung in `/config`
3365* Das Einschalten des [Fast-Modus](/docs/de/fast-mode), wenn das das Modell der Sitzung ändert
3366* Eine `set_model`-Anfrage oder eine Modell-Änderung in einer `apply_flag_settings`-Anfrage von einem [Agent SDK](/docs/de/agent-sdk/typescript#query-object)-Host oder [Remote Control](/docs/de/remote-control)
3367
3368Claude Code führt PreModelSwitch-Hooks nicht für Wechsel aus, die es selbst macht, wie ein [automatisches Modell-Fallback](/docs/de/model-config#automatic-model-fallback) oder das Wiederherstellen des Modells, wenn Sie eine Sitzung fortsetzen. Diese Änderungen erreichen nur [PostModelSwitch](#postmodelswitch).
3369
3370Claude Code vergleicht den Matcher gegen den kanonischen Namen des Modells, zu dem die Sitzung wechselt, und ignoriert jeden `[1m]`-Suffix. Ein Alias wie `opus`, eine datierte Modell-ID und eine Provider-spezifische ID wie eine Amazon Bedrock-Modell-ID passen alle auf den einen kanonischen Namen, zu dem sie sich auflösen, daher deckt `claude-opus-5` jede Schreibweise von Opus 5 ab.
3371
3372Wenn Claude Code einen kanonischen Namen für das Ziel nicht bestimmen kann, zum Beispiel eine benutzerdefinierte Modell-ID, die nur Ihr [LLM-Gateway](/docs/de/llm-gateway) kennt, führt es jeden PreModelSwitch-Hook aus, unabhängig vom Matcher. Ein Hook, der blockiert, sollte daher `to_model` aus seiner Eingabe überprüfen, statt sich allein auf den Matcher zu verlassen.
3373
3374Schreiben Sie den Matcher als genauen Namen, eine `|`-getrennte Liste wie `claude-opus-4-6|claude-opus-5` oder einen regulären Ausdruck wie `.*opus.*`. Dieses Beispiel verwendet einen genauen Namen-Matcher und überprüft auch `to_model` aus der Hook-Eingabe, daher verweigert es einen Wechsel zu Opus 4.6 durch Beendigung mit Code 2 und lässt jedes andere Ziel durch:
3375
3376<Tabs>
3377 <Tab title="macOS/Linux">
3378 Der Befehl überprüft `to_model` mit `jq`:
3379
3380 ```json theme={null}
3381 {
3382 "hooks": {
3383 "PreModelSwitch": [
3384 {
3385 "matcher": "claude-opus-4-6",
3386 "hooks": [
3387 {
3388 "type": "command",
3389 "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"
3390 }
3391 ]
3392 }
3393 ]
3394 }
3395 }
3396 ```
3397 </Tab>
3398
3399 <Tab title="Windows (PowerShell)">
3400 Registrieren Sie einen Command-Hook, der ein Skript durch PowerShell ausführt:
3401
3402 ```json theme={null}
3403 {
3404 "hooks": {
3405 "PreModelSwitch": [
3406 {
3407 "matcher": "claude-opus-4-6",
3408 "hooks": [
3409 {
3410 "type": "command",
3411 "command": "powershell.exe",
3412 "args": [
3413 "-NoProfile",
3414 "-ExecutionPolicy",
3415 "Bypass",
3416 "-File",
3417 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1"
3418 ]
3419 }
3420 ]
3421 }
3422 ]
3423 }
3424 }
3425 ```
3426
3427 Speichern Sie dieses Skript unter `.claude/hooks/block-opus-46.ps1` in Ihrem Projekt:
3428
3429 ```powershell theme={null}
3430 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
3431 if ($hookInput.to_model -match 'opus-4-6') {
3432 [Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.')
3433 exit 2
3434 }
3435 exit 0
3436 ```
3437 </Tab>
3438</Tabs>
3439
3440Um zu bestätigen, dass der Hook funktioniert, führen Sie `/model claude-opus-4-6` aus einer Sitzung aus, die ein anderes Modell ausführt. Claude Code behält das aktuelle Modell und meldet, dass ein PreModelSwitch-Hook den Wechsel blockiert hat, mit Ihrer Nachricht als Grund.
3441
3442<h4 id="premodelswitch-input">
3443 PreModelSwitch-Eingabe
3444</h4>
3445
3446Zusätzlich zu den [gemeinsamen Eingabefeldern](#common-input-fields) erhalten PreModelSwitch-Hooks die Felder in dieser Tabelle. Die letzten fünf beschreiben, was das Erneut-Senden des Gesprächs zum neuen Modell kostet, daher kann ein Hook diese Zahl zeigen, bevor der Wechsel passiert.
3447
3448| Feld | Typ | Beschreibung |
3449| :-------------------------- | :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3450| `from_model` | Zeichenkette | Modell-ID, zu der der Wechsel ändert |
3451| `to_model` | Zeichenkette | Modell-ID, zu der der Wechsel ändert. Der Matcher vergleicht gegen den kanonischen Namen dieses Modells |
3452| `requested_model` | Zeichenkette oder `null` | Das Modell, das die Anfrage benannt hat: ein Alias wie `opus`, eine vollständige Modell-ID oder `null`, wenn die Anfrage für das Standard-Modell war |
3453| `source` | Zeichenkette | Woher die Anfrage kam: `"command"` für `/model <name>`, die Modell-Einstellung in `/config` oder das Einschalten des Fast-Modus; `"picker"` für einen Modell-Picker; `"sdk"` für eine `set_model`-Anfrage oder eine Modell-Änderung in einer `apply_flag_settings`-Anfrage von einem Agent SDK-Host oder Remote Control |
3454| `context_tokens` | Zahl | Tokens, die die nächste Anfrage als ihren Prompt erneut sendet: die Input-, Cache-Read-, Cache-Creation- und Output-Tokens der letzten Antwort in der Hauptkonversation, kombiniert. `0` vor der ersten Antwort |
3455| `prompt_cache_warm` | Boolesch | Ob der Prompt-Cache des aktuellen Modells wahrscheinlich noch warm ist, was bedeutet, dass der Wechsel ihn aufgibt |
3456| `cache_ttl` | Zeichenkette | [Prompt-Cache-Lebensdauer](/docs/de/prompt-caching#cache-lifetime), die Claude Code für diese Sitzung anfordert: `"5m"` oder `"1h"` |
3457| `estimated_cache_write_usd` | Zahl | Geschätzte Kosten in US-Dollar zum Schreiben von `context_tokens` in den Prompt-Cache auf `to_model` bei der `cache_ttl`-Rate, ohne die nächste Antwort. Der Server muss möglicherweise nicht den ganzen Kontext erneut zwischenspeichern, daher behandeln Sie es als Schätzung |
3458| `pricing` | Zeichenkette | Wie Claude Code `estimated_cache_write_usd` bepreist: `"configured"` bei Ihren Organisations-eigenen Sätzen, wenn sie konfiguriert hat, `"catalog"` bei Listenpreis oder `"default"`, wenn `to_model` keinen bekannten Preis hat und Claude Code einen Standard-Satz annahm |
3459
3460Dieses Beispiel zeigt die Eingabe für `/model opus` in einer Sitzung, die Sonnet 5 ausführt:
3461
3462```json theme={null}
3463{
3464 "session_id": "abc123",
3465 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
3466 "cwd": "/Users/...",
3467 "hook_event_name": "PreModelSwitch",
3468 "from_model": "claude-sonnet-5",
3469 "to_model": "claude-opus-5",
3470 "requested_model": "opus",
3471 "source": "command",
3472 "context_tokens": 182340,
3473 "prompt_cache_warm": true,
3474 "cache_ttl": "5m",
3475 "estimated_cache_write_usd": 1.1396,
3476 "pricing": "catalog"
3477}
3478```
3479
3480<h4 id="premodelswitch-decision-control">
3481 PreModelSwitch-Entscheidungskontrolle
3482</h4>
3483
3484`PreModelSwitch`-Hooks können den Wechsel abbrechen, den Benutzer zur Bestätigung auffordern oder ihn fortgesetzt lassen. Exit-Code 2 oder ein Top-Level-`decision: "block"` bricht den Wechsel ab.
3485
3486Für feinere Kontrolle geben Sie `permissionDecision` und `permissionDecisionReason` in einem `hookSpecificOutput`-Objekt zurück, wie auf [PreToolUse](#pretooluse-decision-control). `PreModelSwitch` akzeptiert `"allow"`, `"deny"` und `"ask"`. Es akzeptiert nicht `"defer"`, `updatedInput` oder `additionalContext`. Die Tabelle unten beschreibt beide Felder:
3487
3488| Feld | Beschreibung |
3489| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3490| `permissionDecision` | `"allow"` wird fortgesetzt und überspringt die [Bestätigung, die Claude Code zeigt, während der Prompt-Cache warm ist](/docs/de/prompt-caching#switching-models). `"deny"` bricht den Wechsel ab. `"ask"` fordert den Benutzer zur Bestätigung auf |
3491| `permissionDecisionReason` | Für `"deny"`, dem Benutzer als Grund angezeigt, warum der Wechsel blockiert wurde, oder als Fehler für eine `set_model`-Anfrage zurückgegeben. Für `"ask"`, im Bestätigungsprompt angezeigt. Ignoriert für `"allow"` |
3492
3493Nur `/model` in einer interaktiven Sitzung kann den `"ask"`-Prompt zeigen. Auf jeder anderen Oberfläche, einschließlich nicht-interaktivem Modus mit dem `-p`-Flag, `/config` und `set_model`-Anfragen, behandelt Claude Code `"ask"` als Verweigerung.
3494
3495Dieses Beispiel fordert den Benutzer zur Bestätigung auf und zitiert die Token-Anzahl aus `context_tokens`:
3496
3497```json theme={null}
3498{
3499 "hookSpecificOutput": {
3500 "hookEventName": "PreModelSwitch",
3501 "permissionDecision": "ask",
3502 "permissionDecisionReason": "Switching now re-sends about 180k tokens to the new model. Continue?"
3503 }
3504}
3505```
3506
3507Wenn mehrere PreModelSwitch-Hooks unterschiedliche Entscheidungen zurückgeben, ist die Priorität `deny` > `ask` > `allow`.
3508
3509Claude Code zeigt jede `systemMessage`, die Ihr Hook zurückgibt, unabhängig von der Entscheidung, daher kann ein Kosten-Bericht-Hook `{"systemMessage": "..."}` zurückgeben und mit 0 beenden.
3510
3511Ein PreModelSwitch-Hook, der nicht vor seinem Timeout antwortet, blockiert den Wechsel. Auf [PreToolUse](#timeouts) lässt ein Timeout-Command-Hook den Tool-Aufruf im Gegensatz dazu fortgesetzt. Das Standard-Timeout für dieses Ereignis beträgt 30 Sekunden. `PreModelSwitch` führt nur `command`-, `http`- und `mcp_tool`-Hooks aus, daher gelten die `prompt`- und `agent`-Standard nicht.
3512
3513Ein Hook, der mit einem Code anderen als 0 oder 2 beendet und keine JSON-Entscheidung druckt, blockiert nicht: Claude Code zeigt seinen stderr und wendet den Wechsel an, wie unter [Andere Exit-Codes](#other-exit-codes) beschrieben.
3514
3515<h3 id="postmodelswitch">
3516 PostModelSwitch
3517</h3>
3518
3519Wird ausgeführt, nachdem sich das Modell der Sitzung ändert. Verwenden Sie ihn, um Claude modellspezifische Anleitung zu geben, ohne jede CLAUDE.md zu bearbeiten, zum Beispiel eine organisations-weite Anweisung, die auf bestimmten Modellen gilt.
3520
3521PostModelSwitch erfordert Claude Code v2.1.251 oder später. Es kann nicht blockieren, da sich das Modell bereits geändert hat. Claude Code führt PostModelSwitch-Hooks nach jedem dieser Änderungen aus:
3522
3523* Ein Wechsel, den Sie oder ein Client angefordert haben
3524* Ein [automatisches Modell-Fallback](/docs/de/model-config#automatic-model-fallback), das das Modell der Sitzung ändert
3525* Eine Einstellung wie [`opusplan`](/docs/de/model-config#opusplan-model-setting), die den Plan-Modus betritt oder verlässt
3526* Claude Code, das das Modell wiederherstellt, wenn Sie eine Sitzung fortsetzen
3527
3528Claude Code führt PostModelSwitch-Hooks nicht aus, wenn ein Modell aus einer [Fallback-Modell-Kette](/docs/de/model-config#fallback-model-chains) eine Runde bedient, da diese Substitution eine Runde dauert und das Modell der Sitzung unverändert lässt.
3529
3530Der Matcher folgt den gleichen Regeln wie [PreModelSwitch](#premodelswitch): Claude Code vergleicht ihn gegen den kanonischen Namen des Modells, zu dem die Sitzung wechselt.
3531
3532Dieses Beispiel fügt Anleitung hinzu, wenn sich das Modell der Sitzung zu einem Opus-Modell ändert:
3533
3534```json theme={null}
3535{
3536 "hooks": {
3537 "PostModelSwitch": [
3538 {
3539 "matcher": ".*opus.*",
3540 "hooks": [
3541 {
3542 "type": "command",
3543 "command": "echo 'On Opus, delegate implementation work to subagents and keep this conversation for planning and review.'"
3544 }
3545 ]
3546 }
3547 ]
3548 }
3549}
3550```
3551
3552Um zu bestätigen, dass der Hook funktioniert, wechseln Sie zu einem Opus-Modell aus einer Sitzung, die ein anderes Modell ausführt, zum Beispiel führen Sie `/model opus` aus einer Sonnet-Sitzung aus, und fragen Sie Claude dann, welche Anleitung es zum aktuellen Modell hat.
3553
3554<h4 id="postmodelswitch-input">
3555 PostModelSwitch-Eingabe
3556</h4>
3557
3558PostModelSwitch-Hooks erhalten die gleichen Felder wie [PreModelSwitch](#premodelswitch-input), mit `hook_event_name` auf `"PostModelSwitch"` gesetzt und zwei weitere `source`-Werte: `"auto"` für ein automatisches Fallback oder eine andere Änderung, die Claude Code selbst gemacht hat, und `"resume"` für das Modell, das wiederhergestellt wurde, wenn Sie eine Sitzung fortsetzen.
3559
3560`requested_model` ist `null`, wenn `source` `"auto"` ist. Wenn `source` `"resume"` ist, ist es die gespeicherte Modell-Einstellung, die Claude Code wiederhergestellt hat.
3561
3562<h4 id="postmodelswitch-decision-control">
3563 PostModelSwitch-Entscheidungskontrolle
3564</h4>
3565
3566Claude Code nimmt Ihren Hook-[Plain-Text-stdout](#exit-code-0) bei Beendigung mit 0 oder `additionalContext` aus JSON-Ausgabe und liefert es an Claude mit der nächsten Anfrage nach dem Wechsel. Zusätzlich zu den [JSON-Ausgabefeldern](#json-output), die für alle Hooks verfügbar sind, können Sie zurückgeben:
3567
3568| Feld | Beschreibung |
3569| :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------- |
3570| `additionalContext` | Zeichenkette, die zu Claudes Kontext mit der nächsten Anfrage hinzugefügt wird. Siehe [Kontext für Claude hinzufügen](#add-context-for-claude) |
3571
3572Wenn der Hook nicht innerhalb von fünf Sekunden nach dem Senden der nächsten Anfrage fertig ist, sendet Claude Code diese Anfrage ohne die Ausgabe und hängt sie statt der nächsten Anfrage an. Wenn sich das Modell mehrmals ändert, bevor die nächste Anfrage erfolgt, liefert Claude Code nur die Ausgabe für den letzten Wechsel-Zielmodell.
3573
2830<h3 id="sessionend">3574<h3 id="sessionend">
2831 SessionEnd3575 SessionEnd
2832</h3>3576</h3>
2836Das Feld `reason` in der Hook-Eingabe gibt an, warum die Sitzung endete:3580Das Feld `reason` in der Hook-Eingabe gibt an, warum die Sitzung endete:
2837 3581
2838| Grund | Beschreibung |3582| Grund | Beschreibung |
2839| :---------------------------- | :------------------------------------------------------------ |3583| :---------------------------- | :------------------------------------------------------------------------------------------------------ |
2840| `clear` | Sitzung mit `/clear`-Befehl gelöscht |3584| `clear` | Sitzung mit `/clear`-Befehl gelöscht |
2841| `resume` | Sitzung über interaktives `/resume` gewechselt |3585| `resume` | Sitzung über interaktives `/resume` gewechselt |
2842| `logout` | Benutzer hat sich abgemeldet |3586| `logout` | Benutzer hat sich abgemeldet |
2843| `prompt_input_exit` | Benutzer hat beendet, während die Prompt-Eingabe sichtbar war |3587| `prompt_input_exit` | Benutzer hat beendet, während die Prompt-Eingabe sichtbar war |
2844| `bypass_permissions_disabled` | Bypass-Berechtigungsmodus wurde deaktiviert |
2845| `other` | Andere Ausstiegsgründe |3588| `other` | Andere Ausstiegsgründe |
3589| `bypass_permissions_disabled` | Entfernt in v2.1.234; Claude Code sendet es nicht. Lassen Sie es aus Ihren `SessionEnd`-Matchern fallen |
2846 3590
2847<h4 id="sessionend-input">3591<h4 id="sessionend-input">
2848 SessionEnd-Eingabe3592 SessionEnd-Eingabe
2862 3606
2863SessionEnd-Hooks haben keine Entscheidungskontrolle. Sie können die Sitzungsbeendigung nicht blockieren, können aber Bereinigungsaufgaben durchführen.3607SessionEnd-Hooks haben keine Entscheidungskontrolle. Sie können die Sitzungsbeendigung nicht blockieren, können aber Bereinigungsaufgaben durchführen.
2864 3608
2865SessionEnd-Hooks haben ein Standard-Timeout von 1,5 Sekunden. Dies gilt sowohl für den Sitzungsausstieg als auch für `/clear` und das Wechseln von Sitzungen über interaktives `/resume`. Wenn ein Hook mehr Zeit benötigt, setzen Sie eine Pro-Hook-`timeout` in der Hook-Konfiguration. Das Gesamtbudget wird automatisch auf das höchste Pro-Hook-Timeout erhöht, das in Einstellungsdateien konfiguriert ist, bis zu 60 Sekunden. Timeouts, die auf Plugin-bereitgestellten Hooks gesetzt sind, erhöhen das Budget nicht. Um das Budget explizit zu überschreiben, setzen Sie die Umgebungsvariable `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` in Millisekunden.3609SessionEnd-Hooks haben ein Standard-Timeout von 1,5 Sekunden. Es gilt, wenn Sie beenden, `/clear` ausführen oder Sitzungen mit interaktivem `/resume` wechseln. Wenn ein Hook mehr Zeit benötigt, setzen Sie `timeout` in dieser Hook-Konfiguration. Das Gesamtbudget wird automatisch auf das höchste Pro-Hook-`timeout` erhöht, das in Ihren Einstellungsdateien konfiguriert ist, bis zu 60 Sekunden. Timeouts, die auf Plugin-bereitgestellten Hooks gesetzt sind, erhöhen das Budget nicht. Um das Budget explizit zu überschreiben, setzen Sie die Umgebungsvariable `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` in Millisekunden.
2866 3610
2867```bash theme={null}3611```bash theme={null}
2868CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude3612CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude
2869```3613```
2870 3614
3615Vor v2.1.268 erhöhte `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` nur das Gesamtbudget, und ein Hook ohne sein eigenes `timeout` wurde immer noch nach 1,5 Sekunden abgebrochen.
3616
2871<h3 id="elicitation">3617<h3 id="elicitation">
2872 Elicitation3618 Elicitation
2873</h3>3619</h3>
2889 "session_id": "abc123",3635 "session_id": "abc123",
2890 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",3636 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
2891 "cwd": "/Users/...",3637 "cwd": "/Users/...",
2892 "permission_mode": "default",
2893 "hook_event_name": "Elicitation",3638 "hook_event_name": "Elicitation",
2894 "mcp_server_name": "my-mcp-server",3639 "mcp_server_name": "my-mcp-server",
2895 "message": "Please provide your credentials",3640 "message": "Please provide your credentials",
2910 "session_id": "abc123",3655 "session_id": "abc123",
2911 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",3656 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
2912 "cwd": "/Users/...",3657 "cwd": "/Users/...",
2913 "permission_mode": "default",
2914 "hook_event_name": "Elicitation",3658 "hook_event_name": "Elicitation",
2915 "mcp_server_name": "my-mcp-server",3659 "mcp_server_name": "my-mcp-server",
2916 "message": "Please authenticate",3660 "message": "Please authenticate",
2942| `action` | `accept`, `decline`, `cancel` | Ob die Anfrage akzeptiert, abgelehnt oder abgebrochen werden soll |3686| `action` | `accept`, `decline`, `cancel` | Ob die Anfrage akzeptiert, abgelehnt oder abgebrochen werden soll |
2943| `content` | Objekt | Formularfeldwerte zum Einreichen. Wird nur verwendet, wenn `action` `accept` ist |3687| `content` | Objekt | Formularfeldwerte zum Einreichen. Wird nur verwendet, wenn `action` `accept` ist |
2944 3688
2945Exit-Code 2 verweigert die Elicitation und zeigt stderr dem Benutzer an.3689Exit-Code 2 verweigert die Elicitation. Claude Code zeigt Ihre stderr-Nachricht nicht irgendwo an.
3690
3691Claude Code handelt auf `hookSpecificOutput` aus einer Elicitation-Hook-JSON-Ausgabe und verwirft `systemMessage` und `continue`.
2946 3692
2947<h3 id="elicitationresult">3693<h3 id="elicitationresult">
2948 ElicitationResult3694 ElicitationResult
2963 "session_id": "abc123",3709 "session_id": "abc123",
2964 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",3710 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
2965 "cwd": "/Users/...",3711 "cwd": "/Users/...",
2966 "permission_mode": "default",
2967 "hook_event_name": "ElicitationResult",3712 "hook_event_name": "ElicitationResult",
2968 "mcp_server_name": "my-mcp-server",3713 "mcp_server_name": "my-mcp-server",
2969 "action": "accept",3714 "action": "accept",
2994| `action` | `accept`, `decline`, `cancel` | Überschreibt die Aktion des Benutzers |3739| `action` | `accept`, `decline`, `cancel` | Überschreibt die Aktion des Benutzers |
2995| `content` | Objekt | Überschreibt Formularfeldwerte. Nur aussagekräftig, wenn `action` `accept` ist |3740| `content` | Objekt | Überschreibt Formularfeldwerte. Nur aussagekräftig, wenn `action` `accept` ist |
2996 3741
2997Exit-Code 2 blockiert die Antwort, wodurch die effektive Aktion zu `decline` wird.3742Exit-Code 2 blockiert die Antwort, wodurch die effektive Aktion zu `decline` wird. Claude Code zeigt Ihre stderr-Nachricht nicht irgendwo an.
3743
3744Claude Code handelt auf `hookSpecificOutput` aus einer ElicitationResult-Hook-JSON-Ausgabe und verwirft `systemMessage` und `continue`.
2998 3745
2999<h2 id="prompt-based-hooks">3746<h2 id="prompt-based-hooks">
3000 Prompt-basierte Hooks3747 Prompt-basierte Hooks
3022 3769
3023* `ConfigChange`3770* `ConfigChange`
3024* `CwdChanged`3771* `CwdChanged`
3772* `DirectoryAdded`
3025* `Elicitation`3773* `Elicitation`
3026* `ElicitationResult`3774* `ElicitationResult`
3027* `FileChanged`3775* `FileChanged`
3028* `InstructionsLoaded`3776* `InstructionsLoaded`
3777* `MessageDisplay`
3029* `Notification`3778* `Notification`
3030* `PostCompact`3779* `PostCompact`
3780* `PostModelSwitch`
3031* `PreCompact`3781* `PreCompact`
3782* `PreModelSwitch`
3032* `SessionEnd`3783* `SessionEnd`
3033* `StopFailure`3784* `StopFailure`
3034* `SubagentStart`3785* `SubagentStart`
3035* `WorktreeCreate`3786* `WorktreeCreate`
3036* `WorktreeRemove`3787* `WorktreeRemove`
3037 3788
3038`SessionStart` und `Setup` unterstützen `command` und `mcp_tool` Hooks. Sie unterstützen keine `http`, `prompt` oder `agent` Hooks.3789`SessionStart` und `Setup` unterstützen `command` und `mcp_tool` Hooks, und [MCP-Tool-Hook-Felder](#mcp-tool-hook-fields) beschreibt, wann ihre `mcp_tool` Hooks ausgeführt werden. Sie unterstützen keine `http`, `prompt` oder `agent` Hooks.
3039 3790
3040<h3 id="how-prompt-based-hooks-work">3791<h3 id="how-prompt-based-hooks-work">
3041 Wie Prompt-basierte Hooks funktionieren3792 Wie Prompt-basierte Hooks funktionieren
3051 Prompt-Hook-Konfiguration3802 Prompt-Hook-Konfiguration
3052</h3>3803</h3>
3053 3804
3054Setzen 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. Claude Code sendet den kombinierten Prompt und die Eingabe an ein schnelles Claude-Modell, das eine JSON-Entscheidung zurückgibt.3805Setzen 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.
3055 3806
3056Dieser `Stop`-Hook fragt das LLM, ob Claude stoppen sollte, bevor Claude beendet wird:3807Dieser `Stop`-Hook fragt das LLM, ob Claude stoppen sollte, bevor Claude beendet wird:
3057 3808
3073```3824```
3074 3825
3075| Feld | Erforderlich | Beschreibung |3826| Feld | Erforderlich | Beschreibung |
3076| :---------------- | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3827| :---------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
3077| `type` | ja | Muss `"prompt"` sein |3828| `type` | ja | Muss `"prompt"` sein |
3078| `prompt` | ja | Der Prompt-Text zum Senden an das LLM. Verwenden Sie `$ARGUMENTS` als Platzhalter für die Hook-Eingabe JSON. Wenn `$ARGUMENTS` nicht vorhanden ist, wird die Eingabe JSON an den Prompt angehängt |3829| `prompt` | ja | Der Prompt-Text zum Senden an das LLM. Verwenden Sie `$ARGUMENTS` als Platzhalter für die Hook-Eingabe JSON. Wenn `$ARGUMENTS` nicht vorhanden ist, wird die Eingabe JSON an den Prompt angehängt |
3079| `model` | nein | Modell zur Verwendung für die Evaluierung. Standardwert ist ein schnelles Modell |3830| `model` | nein | Modell zur Verwendung für die Evaluierung. Standardwert ist ein schnelles Modell |
3080| `timeout` | nein | Timeout in Sekunden. Standard: 30 |3831| `timeout` | nein | Timeout in Sekunden. Standard: 30 |
3081| `continueOnBlock` | nein | Wenn der Prompt `ok: false` zurückgibt, wird der Grund an Claude zurückgegeben und der Turn wird fortgesetzt, anstatt zu stoppen. Standard: `false`. Implementiert als `continue: true` auf der resultierenden `decision: "block"`. Siehe [Response-Schema](#response-schema) für ereignisspezifisches Verhalten |3832| `continueOnBlock` | nein | Bei den Ereignissen, auf die es zutrifft, speist `true` einen `ok: false` Grund an Claude zurück und setzt den Turn fort, anstatt ihn zu beenden. Standard: `false`. Siehe [Response-Schema](#response-schema) für ereignisspezifisches Verhalten |
3082 3833
3083<h3 id="response-schema">3834<h3 id="response-schema">
3084 Response-Schema3835 Response-Schema
3089```json theme={null}3840```json theme={null}
3090{3841{
3091 "ok": true | false,3842 "ok": true | false,
3092 "reason": "Explanation for the decision"3843 "reason": "Explanation for the decision",
3844 "impossible": true | false
3093}3845}
3094```3846```
3095 3847
3096| Feld | Beschreibung |3848| Feld | Beschreibung |
3097| :------- | :----------------------------------------------------------------------------------------------------------------- |3849| :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3098| `ok` | `true` erlaubt die Aktion. `false` erzeugt eine `decision: "block"`. Siehe das ereignisspezifische Verhalten unten |3850| `ok` | `true` erlaubt die Aktion. Bei `false` siehe das ereignisspezifische Verhalten unten |
3099| `reason` | Erforderlich, wenn `ok` `false` ist. Wird als Blockierungsgrund verwendet |3851| `reason` | Erforderlich, wenn `ok` `false` ist |
3852| `impossible` | Optional. Das Modell gibt es mit `ok: false` zurück, wenn es beurteilt, dass die Bedingung niemals erfüllt werden kann. Bei `Stop` und `SubagentStop` lässt Claude Code dann den Turn enden, anstatt den Grund zurückzugeben. Agent-Hooks und andere Ereignisse ignorieren es |
3100 3853
3101Was bei `ok: false` passiert, hängt vom Ereignis ab:3854Was bei `ok: false` passiert, hängt vom Ereignis ab:
3102 3855
3103* `Stop` und `SubagentStop`: der Grund wird an Claude als nächste Anweisung zurückgegeben und der Turn wird fortgesetzt3856* `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
3104* `PreToolUse`: der Tool-Aufruf wird verweigert und der Grund wird an Claude als Tool-Fehler zurückgegeben, gleichbedeutend mit einem Command-Hook mit `permissionDecision: "deny"`3857* `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
3105* `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 fortzusetzen3858* `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
3106* `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`3859* `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`
3107* `PostToolUseFailure`, `TaskCreated` und `TaskCompleted`: der Grund wird an Claude als Tool-Fehler zurückgegeben, ähnlich wie `PreToolUse`3860* `PostToolUseFailure` und `TaskCreated`: der Grund wird an Claude als Tool-Fehler zurückgegeben und der Turn wird fortgesetzt, unabhängig von `continueOnBlock`
3861* `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
3108* `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 lassen3862* `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
3109* `PermissionRequest`: `ok: false` hat keine Auswirkung. Um eine Genehmigung von einem Hook zu verweigern, verwenden Sie einen [Command-Hook](#command-hook-fields) mit `hookSpecificOutput.decision.behavior: "deny"`3863* `PermissionRequest`: `ok: false` hat keine Auswirkung. Um eine Genehmigung von einem Hook zu verweigern, verwenden Sie einen [Command-Hook](#command-hook-fields) mit `hookSpecificOutput.decision.behavior: "deny"`
3110* `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](#command-hook-fields), um `retry` zurückzugeben3864* `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](#command-hook-fields), um `retry` zurückzugeben
3111 3865
3112Wenn Sie eine feinere Kontrolle bei einem Ereignis benötigen, verwenden Sie einen [Command-Hook](#command-hook-fields) mit den ereignisspezifischen Feldern, die in [Entscheidungskontrolle](#decision-control) beschrieben sind.3866Wenn Sie eine feinere Kontrolle bei einem Ereignis benötigen, verwenden Sie einen [Command-Hook](#command-hook-fields) mit den ereignisspezifischen Feldern, die in [Entscheidungskontrolle](#decision-control) beschrieben sind.
3113 3867
3115 Mehrere Bedingungen vor dem Stoppen überprüfen3869 Mehrere Bedingungen vor dem Stoppen überprüfen
3116</h3>3870</h3>
3117 3871
3118Dieser `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](/docs/de/sub-agents) stoppen sollte. Wenn `"ok"` `false` ist, setzt Claude die Arbeit mit dem bereitgestellten Grund als nächste Anweisung fort:3872Dieser `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](/docs/de/sub-agents) 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:
3119 3873
3120```json theme={null}3874```json theme={null}
3121{3875{
3151 3905
3152Wenn ein Agent-Hook ausgelöst wird:3906Wenn ein Agent-Hook ausgelöst wird:
3153 3907
31541. Claude Code spawnt einen Subagenten mit Ihrem Prompt und der Hook-Eingabe39081. Claude Code spawnt einen Subagenten mit Ihrem Prompt und der Hook-Eingabe JSON
31552. Der Subagent kann Tools wie Read, Grep und Glob verwenden, um zu untersuchen39092. Der Subagent kann Tools wie Read, Grep und Glob verwenden, um zu untersuchen
31563. Nach bis zu 50 Turns gibt der Subagent eine strukturierte `{ "ok": true/false }`-Entscheidung zurück39103. Nach bis zu 50 Turns gibt der Subagent eine strukturierte `{ "ok": true/false }`-Entscheidung zurück
31574. Claude Code verarbeitet die Entscheidung auf die gleiche Weise wie ein Prompt-Hook39114. 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](#response-schema) aufgelistet
3158 3912
3159Agent-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.3913Agent-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.
3160 3914
3162 Agent-Hook-Konfiguration3916 Agent-Hook-Konfiguration
3163</h3>3917</h3>
3164 3918
3165Setzen Sie `type` auf `"agent"` und geben Sie eine `prompt`-Zeichenkette an. Die Konfigurationsfelder sind die gleichen wie [Prompt-Hooks](#prompt-hook-configuration), mit einem längeren Standard-Timeout:3919Setzen 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](#prompt-hook-configuration), mit der Ausnahme, dass Agent-Hooks ein längeres Standard-Timeout von 60 Sekunden haben und kein `continueOnBlock`-Feld haben.
3166
3167| Feld | Erforderlich | Beschreibung |
3168| :-------- | :----------- | :------------------------------------------------------------------------------------------------------------------ |
3169| `type` | ja | Muss `"agent"` sein |
3170| `prompt` | ja | Prompt, der beschreibt, was zu überprüfen ist. Verwenden Sie `$ARGUMENTS` als Platzhalter für die Hook-Eingabe JSON |
3171| `model` | nein | Modell zur Verwendung. Standardwert ist ein schnelles Modell |
3172| `timeout` | nein | Timeout in Sekunden. Standard: 60 |
3173 3920
3174Das Response-Schema ist das gleiche wie Prompt-Hooks: `{ "ok": true }` zum Zulassen oder `{ "ok": false, "reason": "..." }` zum Blockieren.3921Das 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`](#response-schema) bei demselben Ereignis; Agent-Hooks haben kein `continueOnBlock`-Feld und unterstützen nicht das Prompt-Hook-Feld `impossible`.
3175 3922
3176Dieser `Stop`-Hook überprüft, dass alle Unit-Tests bestanden sind, bevor Claude fertig ist:3923Dieser `Stop`-Hook überprüft, dass alle Unit-Tests bestanden sind, bevor Claude fertig ist:
3177 3924
3205 3952
3206Fü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.3953Fü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.
3207 3954
3208Dieser Hook führt ein Test-Skript nach jedem `Write`-Tool-Aufruf aus. Claude arbeitet sofort weiter, während `run-tests.sh` bis zu 120 Sekunden ausgeführt wird. Wenn das Skript fertig ist, wird seine Ausgabe beim nächsten Gesprächsturn geliefert:3955Dieser 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:
3209 3956
3210```json theme={null}3957```json theme={null}
3211{3958{
3217 {3964 {
3218 "type": "command",3965 "type": "command",
3219 "command": "/path/to/run-tests.sh",3966 "command": "/path/to/run-tests.sh",
3220 "async": true,3967 "async": true
3221 "timeout": 120
3222 }3968 }
3223 ]3969 ]
3224 }3970 }
3227}3973}
3228```3974```
3229 3975
3230Das Feld `timeout` setzt die maximale Zeit in Sekunden für den Hintergrund-Prozess. Wenn nicht angegeben, verwenden asynchrone Hooks das gleiche 10-Minuten-Standard wie synchrone Hooks.3976Sobald 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.
3977
3978Claude Code liefert die Ergebnisse eines asynchronen Hooks nur während der Sitzung:
3979
3980* Im [nicht-interaktiven Modus](/docs/de/headless) mit dem Flag `-p` beendet Claude Code jeden noch laufenden asynchronen Hook beim Herunterfahren und finalisiert ihn mit dem Ergebnis `cancelled`
3981* Wenn die Arbeit Ihres Hooks eine `claude -p`-Sitzung überdauern muss, starten Sie einen vollständig abgelösten Prozess davon
3231 3982
3232<h3 id="how-async-hooks-execute">3983<h3 id="how-async-hooks-execute">
3233 Wie asynchrone Hooks ausgeführt werden3984 Wie asynchrone Hooks ausgeführt werden
3235 3986
3236Wenn 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.3987Wenn 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.
3237 3988
3238Nachdem der Hintergrund-Prozess beendet ist, wenn der Hook eine JSON-Response mit einem `additionalContext`-Feld erzeugt hat, wird dieser Inhalt Claude beim nächsten Gesprächsturn als Kontext geliefert. Ein `systemMessage`-Feld wird Ihnen angezeigt, nicht Claude.3989Nachdem 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.
3239 3990
3240Claude Code validiert diese JSON-Response gegen das gleiche [Ausgabeschema](#json-output) 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.3991Claude Code validiert diese JSON-Response gegen das gleiche [Ausgabeschema](#json-output) 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.
3241 3992
3285 "type": "command",4036 "type": "command",
3286 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",4037 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",
3287 "args": [],4038 "args": [],
3288 "async": true,4039 "async": true
3289 "timeout": 300
3290 }4040 }
3291 ]4041 ]
3292 }4042 }
3299 Einschränkungen4049 Einschränkungen
3300</h3>4050</h3>
3301 4051
3302Asynchrone Hooks haben mehrere Einschränkungen im Vergleich zu synchronen Hooks:4052Asynchrone Hooks haben zusätzliche Einschränkungen im Vergleich zu synchronen Hooks:
3303 4053
3304* Nur `type: "command"`-Hooks unterstützen `async`. Prompt-basierte Hooks können nicht asynchron ausgeführt werden.
3305* Asynchrone Hooks können nicht blockieren oder Entscheidungen zurückgeben. Zu dem Zeitpunkt, an dem der Hook abgeschlossen ist, hat die auslösende Aktion bereits stattgefunden.
3306* 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.4054* 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.
3307* Jede Ausführung erstellt einen separaten Hintergrund-Prozess. Es gibt keine Deduplizierung über mehrere Auslösungen des gleichen asynchronen Hooks.4055* Jede Ausführung erstellt einen separaten Hintergrund-Prozess. Es gibt keine Deduplizierung über mehrere Auslösungen des gleichen asynchronen Hooks.
3308 4056
3314 Haftungsausschluss4062 Haftungsausschluss
3315</h3>4063</h3>
3316 4064
3317Command-Hooks werden mit den vollständigen Berechtigungen Ihres System-Benutzers ausgeführt.
3318
3319<Warning>4065<Warning>
3320 Command-Hooks führen Shell-Befehle mit Ihren vollständigen Benutzerberechtigungen aus. Sie können alle Dateien ändern, löschen oder zugreifen, auf die Ihr Benutzerkonto zugreifen kann. Überprüfen und testen Sie alle Hook-Befehle, bevor Sie sie zu Ihrer Konfiguration hinzufügen.4066 Command-Hooks führen Shell-Befehle mit Ihren vollständigen Benutzerberechtigungen aus. Sie können alle Dateien ändern, löschen oder zugreifen, auf die Ihr Benutzerkonto zugreifen kann. Überprüfen und testen Sie alle Hook-Befehle, bevor Sie sie zu Ihrer Konfiguration hinzufügen.
3321</Warning>4067</Warning>
3322 4068
4069<h3 id="workspace-trust">
4070 Workspace-Vertrauen
4071</h3>
4072
4073Claude 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:
4074
4075* **Interaktive Sitzung**: Claude Code hält Hooks aus jeder Einstellungsdatei zurück, einschließlich Ihrer eigenen `~/.claude/settings.json`, bis Sie den [Workspace-Vertrauensdialog](/docs/de/permissions#project-allow-rules-and-workspace-trust) für den Ordner oder für ein übergeordnetes Verzeichnis, dessen Vertrauen sich darauf erstreckt, akzeptieren
4076* **`-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
4077
4078Bevor Sie `claude -p` über ein Repository ausführen, das Sie nicht geschrieben haben, überprüfen Sie seine `.claude/`-Einstellungsdateien, starten Sie mit [`--bare`](/docs/de/headless#start-faster-with-bare-mode), oder [deaktivieren Sie Hooks für diesen Durchlauf](#disable-or-remove-hooks) 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](/docs/de/permissions#what-runs-before-you-trust-a-folder) listet jede Art von Repository-Inhalt nach Sitzungstyp auf.
4079
3323<h3 id="security-best-practices">4080<h3 id="security-best-practices">
3324 Best Practices für Sicherheit4081 Best Practices für Sicherheit
3325</h3>4082</h3>
3336 Windows PowerShell-Tool4093 Windows PowerShell-Tool
3337</h2>4094</h2>
3338 4095
3339Unter Windows können Sie einzelne Hooks in PowerShell ausführen, indem Sie `"shell": "powershell"` auf einem Command-Hook setzen. Hooks spawnen PowerShell direkt, daher funktioniert dies unabhängig davon, ob `CLAUDE_CODE_USE_POWERSHELL_TOOL` gesetzt ist. 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.4096Unter 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.
3340 4097
3341```json theme={null}4098```json theme={null}
3342{4099{
3377 Debug-Hooks4134 Debug-Hooks
3378</h2>4135</h2>
3379 4136
3380Hook-Ausführungsdetails, einschließlich welche Hooks passten, ihre Exit-Codes und vollständige stdout und stderr, 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.4137Hook-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.
4138
4139Beispielsweise erzeugt ein `PostToolUse`-Hook auf `Write`, dessen Befehl `hook-ran` ausgibt, Einträge wie:
3381 4140
3382```text theme={null}4141```text theme={null}
3383[DEBUG] Executing hooks for PostToolUse:Write41422026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text
3384[DEBUG] Found 1 hook commands to execute41432026-07-19T02:03:24.382Z [DEBUG] "Hook PostToolUse:Write (PostToolUse) success:\nhook-ran"
3385[DEBUG] Executing hook command: <Your command> with timeout 600000ms
3386[DEBUG] Hook command completed with status 0: <Your stdout>
3387```4144```
3388 4145
3389Fü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.4146Fü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.
