Hooks
Hier ist das Problem, wenn du Claude in einer CLAUDE.md-Datei sagst, etwas zu tun: Es ist eine Bitte, keine Garantie. Du kannst schreiben „Formatiere immer nach dem Bearbeiten“, und Claude wird normalerweise zuhören. Normalerweise. Aber bei einem langen Lauf, den du nicht beobachtest, reicht „normalerweise“ nicht aus. Ein Hook behebt das. Ein Hook ist deterministischer Code, der an einem festen Punkt in der Schleife ausgeführt wird, sodass er Verhalten garantieren kann, statt darauf zu hoffen. Er verwandelt eine Regel von „Claude hört normalerweise zu“ in „Claude kann sie nicht überspringen.“
Das ist das ganze Versprechen. Schauen wir uns jetzt an, wie es tatsächlich funktioniert.
Die Hook-Events
Claude Code löst im Laufe einer Sitzung etwa 30 Hook-Events aus. Du musst nicht alle kennen, und die Hooks-Referenz(öffnet in neuem Tab) listet jedes einzelne auf. Es gibt eine kleine Handvoll, auf die du immer wieder zurückgreifen wirst, und sie entsprechen Punkten in der agentischen Schleife, an denen du eingreifen möchtest.
So fügen sie sich in die Schleife ein: Eine Sitzung beginnt, Prompts kommen herein, Tools werden aufgerufen, und der Turn endet schließlich. Für jeden dieser Momente gibt es einen Hook, an dem du Code anhängen kannst.
Die, die man kennen sollte:
- PreToolUse löst vor einem Tool-Aufruf aus. Das ist dein Durchsetzungs-Primitiv. Es ist dasjenige, das etwas stoppen kann, bevor es passiert.
- PostToolUse löst nach einem erfolgreichen Tool-Aufruf aus. Hier wird normalerweise automatische Formatierung oder ein Auto-Lint untergebracht.
- Stop löst aus, wenn Claude seinen Turn beenden möchte. Du kannst ablehnen und sagen „nein, du bist noch nicht fertig“, wenn eine Bedingung nicht erfüllt ist. Es gibt ein passendes SubagentStop für den Fall, dass ein Sub-Agent fertig ist.
- PreCompact und PostCompact lösen vor bzw. nach der Komprimierung aus.
- InstructionsLoaded löst aus, wenn eine CLAUDE.md- oder Regeldatei geladen wird. Nützlich, um zu überprüfen, was tatsächlich in den Kontext gelangt ist.
- SessionStart löst am Anfang aus und bereitet die Umgebung vor. Verwende die Quelle
startup, wenn du es nur bei einem frischen Start haben möchtest.
Ein Punkt, über den viele stolpern: Um nach der Komprimierung Kontext erneut einzuspeisen, verwende nicht PostCompact. Verwende SessionStart mit dem Matcher compact. Das ist derjenige, dessen Ausgabe tatsächlich wieder in die Konversation gelangt.
PreToolUse: Eine Entscheidung als JSON zurückgeben
In PreToolUse steckt die eigentliche Stärke, weil es einen Tool-Aufruf blockieren kann, bevor er ausgeführt wird. Du antwortest Claude, indem du JSON ausgibst und mit dem Exit-Code null beendest. Das Schlüsselfeld ist permissionDecision, und es nimmt einen von drei Werten an:
allow— den Aufruf durchlassendeny— den Aufruf stoppenask— die Entscheidung an den Benutzer zurückgeben
Es gibt technisch gesehen einen vierten Wert, defer, aber er gilt nur für nicht-interaktive -p-Läufe, bei denen ein aufrufender Prozess das Tool pausiert und später fortsetzt. Du wirst ihn nur selten brauchen.
So sieht die Struktur aus:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Don't push to main. Open a pull request instead."
}
}Statt einen Aufruf zu blockieren, kannst du ihn umschreiben. Gib allow oder ask mit updatedInput zurück. Bei ask siehst du den umgeschriebenen Aufruf und genehmigst ihn. Bei allow läuft er ohne Nachfrage:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "ask",
"updatedInput": {
"command": "..."
}
}
}So würdest du ein Geheimnis aus einem Bash-Befehl entfernen und ihn trotzdem ausführen lassen. Ein Haken dabei: updatedInput ersetzt das gesamte Input-Objekt, also musst du die Felder, die du nicht änderst, zurückgeben, sonst verlierst du sie.
Exit-Codes für Hooks, die kein JSON zurückgeben
Nicht jeder Hook muss JSON sprechen. Für einfachere Hooks erledigen Exit-Codes die Aufgabe. Es gibt drei Zahlen, auf die es ankommt.
- 0 bedeutet Erfolg. Wenn die Standardausgabe JSON ist, parst Claude sie. Klartext wird bei den meisten Events ignoriert, aber bei SessionStart, UserPromptSubmit und UserPromptExpansion wird Klartext dem Kontext hinzugefügt. Genau das ist es, was einen zustandserhaltenden Hook funktionieren lässt.
- 2 ist ein blockierender Fehler. Die Standardfehlerausgabe wird Claude als Kontext zurückgegeben. Das ist fast überall der blockierende Exit-Code.
- Alles andere ist nicht blockierend. Die Standardfehlerausgabe wird protokolliert, und Claude macht weiter.
Derjenige, bei dem die meisten stolpern, ist Exit-Code 1. Er fühlt sich wie ein Fehler an, blockiert aber nicht. Claude führt den Befehl trotzdem aus. Wenn du also etwas stoppen wolltest, verwende Exit 2, nicht 1.
Noch ein paar Besonderheiten. Exit 2 kann sogar Stop blockieren, und so teilst du Claude mit, dass es noch nicht fertig ist. Aber PostToolUse löst aus, nachdem das Tool bereits gelaufen ist, sodass eine Blockierung dort zu spät kommt, um den Aufruf zu stoppen – es kann aber trotzdem Text an Claude zurückgeben. Und ein paar Events ignorieren das Blockieren vollständig, wie Notification und SessionStart. SessionStart zeigt deine Standardfehlerausgabe nur dir selbst an, Notification ignoriert sie, und beide machen ungeachtet dessen weiter.
Ein echter Schutzmechanismus: Schwärzen statt Blockieren
Verbinden wir das Ganze mit etwas Praktischem. Angenommen, du möchtest einen PreToolUse-Schutzmechanismus für das Bash-Tool. Du registrierst einen Hook in einer Einstellungsdatei. Packe diesen hier in .claude/settings.json und committe ihn, dann kann dein Team ihn gemeinsam nutzen:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/redact-secrets.sh",
"args": []
}
]
}
]
}
}Der matcher wählt das zu überwachende Tool aus, und ein optionales if-Feld am Hook kann es auf einen bestimmten Befehl eingrenzen, etwa "if": "Bash(curl *)". Führe /hooks aus, um zu prüfen, dass der Hook registriert ist.
Der naheliegende Schritt ist, deny zurückzugeben und einen gefährlichen Aufruf zu stoppen. Das ist gut. Aber der weniger bekannte und interessantere Schritt ist, updatedInput zurückzugeben, um den Aufruf umzuschreiben. So entfernst du ein Geheimnis aus einem Befehl und lässt ihn trotzdem ausführen, statt ihn einfach abzulehnen.
So sieht das in der Praxis aus. Claude wird gebeten, einen Befehl auszuführen, der ein echt aussehendes Geheimnis enthält. Der Hook fängt ihn ab, erkennt das Muster sk_live_ und ersetzt es durch einen Platzhalter, bevor der Befehl überhaupt ausgeführt wird.
Hier ist das Skript, .claude/hooks/redact-secrets.sh. Es benötigt jq, und du machst es mit chmod +x ausführbar:
#!/bin/bash
# Ersetzt echt aussehende Keys, bevor der Befehl ausgeführt wird.
jq 'if (.tool_input.command // "" | test("sk_live_\\w+")) then {
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "ask",
permissionDecisionReason: "Replaced a live key with a placeholder",
updatedInput: (.tool_input | .command |= gsub("sk_live_\\w+"; "REDACTED"))
}
} else empty end'Es gibt ask zurück, sodass du den umgeschriebenen Befehl genehmigst. Würde man allow zurückgeben, würde diese Nachfrage für jeden Befehl, auf den das Muster passt, übersprungen. Sobald du zustimmst, läuft der Befehl ohne das Geheimnis. Das ist der Unterschied zwischen Blockieren und Schwärzen, und genau das kann ein Hook jedes einzelne Mal durchsetzen.
Zustand über eine Komprimierung hinweg bewahren
Noch ein Muster, das sich einzurichten lohnt. Wenn Claude eine lange Konversation komprimiert, gehen viele Details verloren. Ein SessionStart-Hook mit dem Matcher compact läuft direkt nach der Komprimierung. Lass ihn eine kurze Zusammenfassung der Dateien ausgeben, an denen du gearbeitet hast. Diese Zusammenfassung gelangt zurück in den Kontext, sodass Claude dort weitermacht, wo es aufgehört hat, statt kalt neu zu starten. Dieses Beispiel listet deine nicht committeten Änderungen auf:
{
"hooks": {
"SessionStart": [
{
"matcher": "compact",
"hooks": [{ "type": "command", "command": "git status --short" }]
}
]
}
}Zusammenfassung
Hooks verwandeln eine Regel, die Claude normalerweise befolgt, in eine, die es immer befolgt. Geh über automatische Formatierung hinaus: sichere Tools mit PreToolUse ab, kontrolliere den Turn mit Stop, und bewahre Zustand über eine Komprimierung hinweg. Die Einrichtung erfordert anfangs etwas Aufwand, aber sie zahlt sich schon beim ersten Mal aus, wenn sie etwas bei einem Lauf abfängt, den du nicht einmal beobachtet hast.