Worum es geht
Ein Hook ist ein selbst definierter Befehl — ein Shell-Skript, ein HTTP-Endpunkt oder sogar eine kurze LLM-Abfrage —, den Claude Code automatisch an bestimmten Punkten seines Lebenszyklus ausführt. Vor einem Tool-Aufruf, danach, wenn Claude fertig antwortet, wenn eine Sitzung startet, und an einem guten Dutzend weiterer Stellen.
Der Punkt ist die Deterministik. Ein Prompt-Wunsch („formatiere den Code, bevor du fertig bist") wird befolgt, wenn das Modell daran denkt. Ein Hook feuert jedes Mal, unabhängig vom Modell, von der Stimmung, von der Kontextlänge. Regeln, die immer gelten, gehören in Hooks — nicht in den Prompt.
In einem Satz: Hooks verschieben Verhalten aus dem „hoffentlich" des Modells in das „garantiert" deiner Konfiguration.
Die Ereignisse, die du wirklich brauchst
Claude Code feuert Hooks an über zwei Dutzend Punkten. Für den Alltag zählen vor allem diese:
| Ereignis | Feuert — und kann |
|---|---|
| PreToolUse | Vor jedem Tool-Aufruf — kann ihn blockieren oder die Eingabe umschreiben |
| PostToolUse | Nach erfolgreichem Tool-Aufruf — ideal zum Formatieren, Linten, Testen |
| UserPromptSubmit | Wenn du absendest — kann den Prompt ablehnen oder Kontext ergänzen |
| Stop | Wenn Claude fertig ist — kann das Stoppen verhindern („mach erst X") |
| SessionStart | Bei Sitzungsbeginn — Kontext laden, Umgebung prüfen |
Ein Matcher grenzt ein, wann ein Hook läuft: Bash nur bei Shell-Befehlen, Edit|Write nur bei Dateiänderungen, mcp__memory__.* für alle Tools eines MCP-Servers.
Wie ein Hook blockt
Ein Hook bekommt die Details des Tool-Aufrufs als JSON über stdin und entscheidet auf zwei Wegen. Der einfache: Exit-Code.
- Exit 0 — alles gut, weiter im normalen Ablauf
- Exit 2 — blockieren. Bei
PreToolUsewird der Tool-Aufruf verhindert, die Fehlermeldung (stderr) geht zurück an Claude - Jeder andere Code — nicht-blockierender Fehler, wird nur im Transcript vermerkt
Der feinere Weg ist JSON auf stdout bei Exit 0. Damit trifft ein PreToolUse-Hook eine saubere Entscheidung:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Destruktiver Befehl blockiert"
}
} permissionDecision kennt allow, deny, ask. Mit updatedInput lässt sich der Befehl sogar umschreiben, statt ihn nur zu verbieten.
Der rm-rf-Blocker, zum Kopieren
So sieht die Konfiguration aus, die vor jedem Bash-Aufruf ein Prüfskript feuert. Sie liegt in .claude/settings.json (pro Projekt) oder ~/.claude/settings.json (global):
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
}
]
}
]
}
}
Das Skript liest den Befehl aus dem stdin-JSON, prüft ihn gegen ein Muster (rm -rf, git push --force, was du willst) und gibt bei Treffer die deny-Entscheidung zurück. Beide Skripte — Blocker und Auto-Formatierer nach jedem Edit — liegen fertig im Guardrail-Kit.
Die ehrliche Grenze — und sie steht in der Doku
Das ist der Teil, den die Werbe-Artikel weglassen. Die offizielle Doku schreibt es selbst hin: Der Muster-Filter eines Hooks ist „best-effort". Wenn ein Befehl so verschachtelt ist, dass die Bash-Mustererkennung ihn nicht sauber parst, kann der Filter „fail open" — also durchlassen, was er blocken sollte.
Konsequenz: Ein Hook ist eine Leitplanke, keine Mauer. Für harte Sicherheit — „dieser Ordner darf niemals angefasst werden" — verweist die Doku ausdrücklich auf das Berechtigungssystem, nicht auf Hooks. Nutze Hooks für Bequemlichkeit und Frühwarnung, nicht als einzige Verteidigungslinie gegen einen entschlossenen Fehler.
Drei weitere Stolpersteine aus der Praxis:
- Hooks laufen mit deinen Rechten. Ein Hook ist Code, dem du vertraust — ein kopiertes Skript aus dem Netz führt auf deinem Rechner aus, was drinsteht. Vorher lesen.
- JSON-Ausgabe ist bei 10.000 Zeichen gedeckelt. Größere Ausgabe landet in einer Datei, der Hook bekommt nur einen Vorschau-Pfad.
- Kein Terminal-Zugriff mehr (seit v2.1.139): Hooks haben kein
/dev/tty. Für Hinweise nutzt mansystemMessagestattecho.
Mein Fazit
Hooks sind der Schritt, an dem Claude Code von „beeindruckendes Spielzeug" zu „Werkzeug, dem ich echte Arbeit anvertraue" wird. Nicht weil sie den Agenten klüger machen, sondern weil sie dir Kontrolle geben, die nicht vom Wohlwollen des Modells abhängt.
Wenn du heute nur eine Sache mitnimmst: Leg den rm-rf-Blocker aus dem Kit in deine globale settings.json. Fünf Minuten, und ein ganzer Fehlertyp kann dir nicht mehr passieren.
Ein ehrliches Wort zum Schluss: Behandle Hooks als das, was sie sind — Komfort und Frühwarnung, keine Festung. Die harte Linie ziehst du im Berechtigungssystem. Wer das verwechselt, fühlt sich sicherer, als er ist.
Zum Einsetzen
Hooks Guardrail-Kit
Fertiger rm-rf-Blocker, Auto-Formatierer nach jedem Edit, die passende settings.json und eine Übersicht aller Ereignisse plus Exit-Codes.
HerunterladenQuelle: code.claude.com/docs/en/hooks
Das war Issue 9 der Velo-Wissen-Reihe. Jeden Sonntag um 15 Uhr eine Empfehlung — ein Tool, eine Bibliothek, ein Workflow oder ein Skill, das ich selbst getestet habe und für nützlich halte.