Claude Code Hooks: Wo das Verhalten deines Agenten wirklich sitzt

Jeder, der Claude Code länger als eine Woche nutzt, kennt diesen Moment. Du fügst eine Zeile in deine CLAUDE.md ein, die besagt, dass keine neuen Dateien ohne Aufforderung erstellt werden sollen. Der Agent hält sich wunderbar daran. Doch nach vierzig Minuten in einer langen Session erstellt er plötzlich vier Dateien, nach denen du nie gefragt hast.

Der erste Reflex ist, die Regel noch nachdrücklicher zu formulieren. Fett gedruckt. Ganz nach oben gestellt. In GROSSBUCHSTABEN. Dieser Reflex ist falsch. Zu verstehen, warum das so ist, ist der eigentliche Sinn von Hooks.

Was sind Claude Code Hooks?

Claude Code Hooks sind Skripte, die die Laufzeitumgebung automatisch an bestimmten Punkten einer Session ausführt, zum Beispiel vor dem Aufruf eines Tools, beim Absenden eines Prompts oder wenn der Agent stoppen möchte. Claude Code übergibt dem Hook eine JSON-Beschreibung des Events über stdin, führt ihn aus und liest den Exit-Code sowie stdout aus. Das Modell wird dabei nicht gefragt.

Dieser letzte Satz macht den gesamten Wert aus. Alles, was du in eine Markdown-Datei schreibst, ist Kontext, der im Kontextfenster mit allem anderen um die Aufmerksamkeit des Modells konkurriert. Alles, was du in einen Hook packst, ist ein Programm. Das Modell kann deine CLAUDE.md überfliegen. Einen Exit-Code kann es nicht überfliegen.

Eine Regel ist eine Bitte. Ein Hook ist die Durchsetzung.

Beide gehören zu einem gesunden Setup und erfüllen unterschiedliche Aufgaben. CLAUDE.md erklärt Absichten, Vorlieben und Dinge, die Fingerspitzengefühl erfordern. Ein Hook transportiert jede Regel, die ausnahmslos immer gelten muss, egal wie lange die Session schon läuft oder wie sicher sich das Modell fühlt. Stelle dir bei jeder Regel eine Frage: Was passiert, wenn der Agent sie ein einziges Mal ignoriert?

Wenn die Antwort „ein etwas schlechterer Commit“ lautet, lass sie in Markdown. Wenn die Antwort „er löscht eine Tabelle“ oder „er schreibt vierhundert Zeilen, bevor ich überhaupt sagen konnte, was ich wollte“ lautet, gehört diese Regel nicht in Fließtext. Sie gehört in Code.

Ein Hook antwortet auf eine von zwei Arten. Er beendet sich mit einem Code, wobei 2 das blockierende Signal ist und Claude Code dein stderr als Begründung an das Modell zurückgibt. Oder er beendet sich mit 0 und gibt JSON aus, worüber du eine echte Berechtigungsentscheidung wie „allow“, „deny“ oder „ask“ zurückgibst. Die Falle, in die viele tappen: Exit-Code 1, der klassische Unix-Fehlercode, blockiert überhaupt nichts.

Die acht Events und was wir mit ihnen verknüpft haben

Claude Code löst Hooks während des gesamten Lifecycles einer Session aus, nicht nur bei Tool-Aufrufen. kitstarter liefert acht Skripte für acht dieser Events aus. Das ist die Tabelle, die unser Installer in deine settings.json schreibt, und es ist die ehrlichste Antwort, die wir auf die Frage „Was fängt man mit Hooks eigentlich an?“ geben können.

Zwei dieser Zeilen verdienen einen genaueren Blick, da sie gegensätzlich sind. Der Unterschied zwischen ihnen macht die gesamte Designphilosophie aus.

Die eine Stelle, an der wir strikt blockieren, und die eine, an der wir uns weigern

Der Clarity-Hook blockiert. Bei jedem Edit, Write, MultiEdit oder NotebookEdit gibt er die Berechtigungsentscheidung „deny“ zurück, bis du bestätigt hast, was du eigentlich willst. Erst dann wird die Sperre aufgehoben. Das ist eine echte Sperre, kein bloßer Schubs. Der Agent kann keine einzige Datei schreiben, bevor das Ziel nicht vereinbart ist.

Die Schutzfunktion weigert sich zu blockieren. Sie liegt auf Bash, erkennt destruktive Befehle und warnt lediglich. Die Begründung steht in der Datei selbst: Ein Kit, das deine Befehle strikt blockiert, wird deinstalliert. Mit der Warnung vor einem gefährlichen Befehl recht zu haben, bringt gar nichts, wenn der Nutzer das ganze Tool eine Woche später wieder herunterschmeißt.

Das ist die Regel, die man sich abschauen sollte. Blockiere dort, wo die Kosten eines Fehlers hoch und die Hürde für eine Nachfrage niedrig sind. Warne überall sonst. Ein Hook, der zu viel blockiert, wird gelöscht. Und ein gelöschter Hook setzt gar nichts durch.

Beide nutzen das Prinzip „Fail Open“. Tritt im Hook ein Fehler auf, bleibt er stumm und lässt dich weiterarbeiten. Ein Coaching-Feature ist es niemals wert, eine Session zu unterbrechen.

Was Hooks tatsächlich verändert haben: die Messwerte

Jede andere Seite über Claude Code Hooks erklärt die API. Fast keine sagt dir, was sich ändert, wenn die Hooks tatsächlich laufen, denn dafür müsste man sie in der Praxis testen und messen. Wir haben eine Testreihe unter Laborbedingungen durchgeführt: dasselbe Modell, dieselben geskripteten vibe coding-Gespräche, eine frische Sandbox pro Testgruppe, eine Gruppe mit Hooks und eine ohne.

Die letzten beiden Zeilen sind wichtiger als die ersten vier. Hooks gibt es nicht umsonst. Bei einer Aufgabe, die ohnehin eindeutig war, sorgt die Clarity-Engine für reinen Overhead: Sie stellt eine Frage, die niemand brauchte, und du zahlst für die Token. Das ist der ehrliche Preis für eine solide Untergrenze, und genau an diesem offenen Produktproblem feilen wir gerade.

Wie man mit Claude Code Hooks startet

Du brauchst keine acht. Fang mit einem an und wähle ihn aus, indem du dich fragst, welcher Fehler dich diesen Monat am meisten Zeit gekostet hat.

Wenn dein Agent baut, bevor du mit dem Erklären fertig bist, lege eine Sperre auf Edit und Write. Wenn er Befehle ausführt, die dir Angst machen, richte eine Warnung für Bash ein. Wenn er ohne Überprüfung „fertig“ meldet, nutze Stop, um diese Behauptung von der Laufzeitumgebung verifizieren zu lassen. Wenn du Subagents startest und merkst, dass sie Regeln ignorieren, an die sich der Haupt-Agent hält, speise sie bei SubagentStart neu ein. Und wenn du einfach nur sehen willst, was passiert, kostet eine Statuszeile nichts und zahlt sich sofort aus.

Schreib ihn, logge zuerst, blockiere später. Führe es schrittweise ein: Protokolliere das Event, ohne zu blockieren, warne dann bei erkannten Mustern und blockiere erst die Dinge, die wirklich Schaden angerichtet haben. Ein Hook, dem du vertraust, ist wertvoller als zehn deaktivierte.

Nichts davon erfordert ein Kit. Hooks sind ein Feature von Claude Code und die Dokumentation ist gut. Was dir ein Kit abnimmt, ist der Teil, für den wir Monate gebraucht haben: zu wissen, welche Events sich zu verknüpfen lohnen, welche Regeln eine harte Durchsetzung statt bloßem Fließtext verdienen und wo Blockieren nach hinten losgeht. Wenn du das lieber nicht selbst zusammenbauen willst, haben wir unseres fertig bereitgestellt, und du kannst genau nachlesen, was es tut, bevor du es installierst.

Ob sich dieser Tausch lohnt, hängt davon ab, welcher Fehler dich Zeit kostet. Sieh dir die drei Zielgruppen an, die das kaufen, samt dem gemessenen Vorher-Nachher für jede von ihnen.

Häufige Fragen

Was sind Claude Code Hooks? Claude Code Hooks sind Skripte, die Claude Code automatisch an bestimmten Punkten einer Session ausführt, beispielsweise vor einem Tool-Aufruf oder beim Absenden eines Prompts. Claude Code übergibt das Event als JSON über stdin und liest den Exit-Code sowie stdout aus. Da die Laufzeitumgebung sie ausführt, sind Hooks deterministisch: Sie werden ausgeführt, unabhängig davon, ob das Modell kooperiert oder nicht.

Was ist der Unterschied zwischen CLAUDE.md und einem Hook? CLAUDE.md ist Kontext, den das Modell liest und eventuell überfliegt. Eine dort geschriebene Regel ist also eine Bitte. Ein Hook ist Code, den die Laufzeitumgebung ausführt, also eine Durchsetzung. Nutze CLAUDE.md, um Absichten zu erklären, und einen Hook für jede Regel, die ausnahmslos immer gelten muss, wie das Verweigern des Schreibens von Dateien, bevor das Ziel bestätigt ist.

Kann ein Claude Code Hook den Agent blockieren? Ja. Ein PreToolUse-Hook kann sich mit dem Code 2 beenden, was den Tool-Aufruf blockiert und dein stderr an das Modell zurückgibt. Oder er beendet sich mit 0 und gibt JSON aus, wobei hookSpecificOutput.permissionDecision auf „allow“, „deny“ oder „ask“ gesetzt ist. Blockieren ist mächtig, also hebe es dir für Fälle auf, in denen Fehler teuer sind und die Hürde für eine Nachfrage niedrig ist.

Verlangsamen Claude Code Hooks den Agent? Sie kosten etwas. In unserem Benchmark unter Laborbedingungen war das Kit mit Hooks bei drei von fünf Aufgaben schneller und günstiger, weil das vorherige Nachfragen Nacharbeit verhinderte. Bei einer ohnehin klaren Aufgabe war es jedoch etwa doppelt so langsam und rund 75 Prozent teurer, bei durchschnittlich 25 Prozent Mehrkosten durch Hook-Kontext-Token.