Was sind Hooks und wie schreibt man sie für Coding-Agenten?

Warum reicht eine Regel in der Regeldatei nicht?

Einem Coding-Agenten können Sie eine Regel auf zwei Wegen mitteilen. Der erste ist die Regeldatei: Sie schreiben in AGENTS.md, CLAUDE.md oder GEMINI.md „Frag mich, bevor du mergst“. Der zweite ist ein Hook: Sie machen aus derselben Regel ein kleines Skript, das der Agent an einer bestimmten Stelle von sich aus ausführt.

Am deutlichsten beschreibt die Dokumentation von Claude Code den Unterschied: “Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.” Die Regeldatei ist für den Agenten also nur eine Information, und er berücksichtigt sie nicht unbedingt jedes Mal. Wollen Sie einen Vorgang stoppen, ganz gleich, wie der Agent entscheidet, nehmen Sie einen Hook.

Stand 18. Oktober 2026 haben alle fünf Coding-Tools Hooks: Claude Code, Codex von OpenAI, Cursor, Gemini CLI von Google und GitHub Copilot (CLI und Cloud-Agent). Das Prinzip ist überall gleich: Ein Hook hängt an einem Ereignis, bekommt dessen Details als JSON und stoppt bei Bedarf einen Befehl, bevor er läuft.

Die Beispiele stammen aus dem Repository, in dem wir diffox jeden Tag weiterentwickeln. Dort nutzen wir Claude Code. Was wir beschreiben, ist keine Funktion des Produkts, sondern die Arbeitsweise des Teams.

Wo definiert man Hooks in den fünf Tools?

In jedem Tool stehen die Hooks in einer Einstellungsdatei; die Tools unterscheiden sich vor allem im Namen der Datei und des Ereignisses. Für Regeln nutzt man am häufigsten das Ereignis, das läuft, kurz bevor der Agent ein Werkzeug benutzt (etwa um einen Befehl auszuführen oder eine Datei zu bearbeiten):

Quelle: die Hook-Dokumentation des jeweiligen Tools, 18. Oktober 2026. Die Entscheidung per JSON gibt der Hook als Ausgabe auf stdout zurück. Codex liest dieselbe Einstellung auch aus config.toml. Bei Copilot gilt die Benutzerdatei nur in der CLI; der Cloud-Agent liest die Datei im Repository aus dem Standard-Branch.

Tritt das Ereignis ein, bekommt Ihr Hook die Details als JSON: welches Werkzeug mit welcher Eingabe aufgerufen wurde. In Claude Code sieht die Eingabe vor einem Bash-Befehl so aus:

Die Tools lesen auch die Dateien der anderen: Copilot liest zusätzlich die Datei .claude/settings.json im Repository, Cursor kann Hooks aus Claude Code laden, und Gemini CLI setzt die Variable CLAUDE_PROJECT_DIR, damit Skripte für Claude Code weiter funktionieren. Einen Hook einmal zu schreiben und in mehreren Tools zu nutzen, ist also möglich. Weil Ereignisnamen und Ausgabefelder verschieden sind, testen Sie den Hook trotzdem in jedem Tool einzeln.

Google hat Gemini CLI am 18. Juni 2026 für kostenlose Nutzer sowie für Abonnenten von Google AI Pro und Ultra eingestellt und sie auf Antigravity CLI verwiesen; mit einem kostenpflichtigen API-Schlüssel oder einer Firmenlizenz können Sie Gemini CLI weiter nutzen. Laut Googles Ankündigung hat auch Antigravity CLI Hooks; die Dokumentation haben wir am 28. Oktober 2026 gelesen. Hooks stehen für ein Projekt in .agents/hooks.json und für den Benutzer in ~/.gemini/config/hooks.json. Das Ereignis, das läuft, bevor ein Werkzeug benutzt wird, heißt wie in Claude Code PreToolUse. Um die Aktion zu stoppen, gibt der Hook im JSON decision: "deny" zurück. Der Timeout liegt standardmäßig bei 30 Sekunden; was die Exit-Codes bewirken, steht nicht in der Dokumentation.

Wie stoppt ein Hook einen Vorgang?

Ein Hook meldet seine Entscheidung auf zwei Wegen: über den Exit-Code oder über JSON, das er ausgibt. Endet der Hook mit Code 2, stoppt der Vorgang in allen fünf Tools, und die Erklärung, die der Hook in die Fehlerausgabe (stderr) schreibt, geht an den Agenten. Unterschiedlich verhalten sich die Tools, wenn der Hook mit einem anderen Fehlercode endet oder in einen Timeout läuft:

Quelle: die Hook-Dokumentation des jeweiligen Tools, 18. Oktober 2026. „Steht nicht in der Dokumentation“ heißt: Auf den Seiten, die wir an diesem Tag gelesen haben, fanden wir keinen Satz zu diesem Fall. Die Einstellung in Claude Code gibt es seit Version 2.1.295. Unter Windows ohne Git Bash kann ein PreToolUse-Befehls-Hook in Shell-Form, der fehlschlägt, den Vorgang auch ohne onFailure stoppen.

Sehen Sie sich zuerst die erste Spalte an. Unter Unix steht 1 üblicherweise für einen Fehler. Claude Code, Cursor und Gemini CLI werten diesen Code als Fehler, der den Vorgang nicht stoppt; Copilot dagegen stoppt bei demselben Code. Die Dokumentation von Claude Code rät deshalb, in Hooks, die eine Regel durchsetzen, exit 2 zu verwenden. Gemini CLI wiederum empfiehlt, selbst beim gewollten Stoppen mit 0 zu enden und JSON auszugeben. Gibt der Hook etwas anderes als JSON aus, lässt Gemini CLI den Vorgang zu.

Das Problem der zweiten Spalte fällt schwerer auf: Stimmt der Pfad zum Hook nicht oder bleibt das Skript hängen, ist es, als gäbe es die Regel gar nicht. Wo der Vorgang auf jeden Fall stoppen muss, schalten Sie in Claude Code onFailure ein, in Cursor failClosed.

Das Beispiel unten ist eine vereinfachte Fassung der Merge-Prüfung aus unserem Repository, für Claude Code. Zuerst die Einstellungsdatei:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/merge-gate.sh"
          }
        ]
      }
    ]
  }
}

Dann das Skript:

#!/bin/bash
# Die Eingabe kommt als JSON über stdin. Ist sie nicht lesbar, stoppt der Vorgang.
COMMAND=$(jq -r '.tool_input.command // empty') || {
  echo "Der Hook konnte die Eingabe nicht lesen, Vorgang gestoppt." >&2
  exit 2
}

case "$COMMAND" in
  *"MERGE_APPROVED=1 gh pr merge"*) exit 0 ;;  # Freigabe steht im Befehl
  *"gh pr merge"*)
    echo "Über den Merge entscheidet der Projektinhaber. Bitte zuerst fragen." >&2
    exit 2 ;;                                 # Vorgang stoppt
esac
exit 0                                        # kein Einwand

Endet das Skript mit 2, führt Claude Code den Befehl nicht aus und gibt den Satz aus der Fehlerausgabe an den Agenten weiter. Dieselbe Entscheidung können Sie auch treffen, indem Sie mit 0 enden und JSON ausgeben: Ins Feld permissionDecision kommt deny (ablehnen), ask (nachfragen) oder allow (erlauben). PreToolUse-Hooks laufen vor den Berechtigungseinstellungen; ein deny gilt sogar im Modus bypassPermissions, der alle Berechtigungsabfragen überspringt. Codex unterstützt den Wert ask noch nicht: Der Hook gilt dann als fehlgeschlagen, und der Vorgang läuft weiter.

Welche Hooks nutzen wir in unserem Repository?

In der Datei .claude/settings.json unseres Repositorys stehen 3 Hooks. Alle drei haben wir geschrieben, damit sich ein Fehler, der uns schon passiert war, nicht wiederholt.

Start der Sitzung. Beginnt eine Sitzung, meldet der SessionStart-Hook, auf welchem Branch sie steht, wie viele Dateien nicht committet sind und welche Worktrees offen sind. Dann fällt er ein Urteil: „Du kannst in diesem Verzeichnis arbeiten“ oder „Öffne zuerst einen eigenen Worktree“. Diese Regel stand schon in CLAUDE.md. Aber eine Sitzung las die Regel, wandte sie nicht auf ihre eigene Lage an und plante Änderungen in einem Verzeichnis, das in vierzig Minuten dreimal den Branch wechselte. Eine Regel, die davon abhängt, dass der Agent an sie denkt, schützt nicht. Der Hook stellt die Frage an seiner Stelle.

Merge-Prüfung. In unserem Repository wird kein Pull Request gemergt, bevor der Projektinhaber zugestimmt hat. Ein Agent kann aber nach grünen Tests als nächsten Schritt gh pr merge ausführen wollen. Der PreToolUse-Hook vor dem Bash-Werkzeug stoppt diesen Befehl mit Code 2 und sagt dem Agenten, er solle zuerst um Freigabe bitten. Kommt die Freigabe, wird der Befehl erneut ausgeführt, mit einer Umgebungsvariable davor. So steht die Freigabe im Sitzungsprotokoll direkt neben dem Merge. Kann der Hook die Eingabe nicht lesen, stoppt er ebenfalls: Seine erste Fassung ließ Befehle, die sie nicht lesen konnte, mit 0 durch.

Warnung bei Branch-Wechsel. Das Urteil beim Start der Sitzung beschreibt den Zustand in diesem Moment und kann veralten: Arbeiten zwei Sitzungen auf demselben Branch und wechselt eine davon auf einen neuen Branch, ändert sich der Ort, an dem die andere arbeitet. Ein zweiter PreToolUse-Hook läuft vor den Werkzeugen, die Dateien bearbeiten. Vor jeder Änderung vergleicht er Branch und Commit mit dem, was der Sitzung zuletzt gesagt wurde. Gibt es einen Unterschied, schickt er dem Agenten eine Notiz, die mit dieser Zeile beginnt: “drift: this checkout MOVED since the session was last told what it is”. Den Vorgang stoppt er nicht; er übergibt die Notiz im Feld additionalContext und endet mit 0.

Ein Git-Hook ist etwas anderes. Im selben Repository gibt es außerdem einen pre-push-Hook: Er verhindert direkte Pushes auf geschützte Branches. Ihn führt nicht der Coding-Agent aus, sondern Git. Deshalb gilt er für jeden, der aus diesem Klon pusht, auch für Agenten, ganz gleich, welches Tool sie nutzen. Beide Arten laufen nur auf Ihrem Rechner: Mit --no-verify lässt sich pre-push überspringen, er ersetzt also keine Prüfung auf dem Server.

Was unterscheidet Hook, Skill und Regeldatei?

Alle drei bestimmen, wie sich der Agent verhält, greifen aber zu unterschiedlichen Zeitpunkten. Der Vergleich in der Dokumentation von Claude Code sieht so aus:

Quelle: Dokumentation von Claude Code, Seite “Extend Claude Code”, 18. Oktober 2026.

Kurz gesagt: Soll der Agent entscheiden, wie er die Schritte umsetzt, nehmen Sie einen Skill. Soll ein Vorgang jedes Mal gleich ablaufen, nehmen Sie einen Hook. Die Checkliste für ein Release ist ein Skill; jede gespeicherte Datei zu formatieren, ist ein Hook. Wie dieselbe Seite sagt, ist eine Anweisung in der Regeldatei oder in einem Skill eine Bitte, keine Garantie. Regeln, deren Bruch sich nicht rückgängig machen lässt (ein Push auf den falschen Branch, ein zu früher Merge), überlassen Sie nicht allein einer Anweisung.

Hooks stehen nicht nur in der Einstellungsdatei; auch Skills und Subagenten können in ihrer Definition Hooks mitbringen. In Claude Code gilt der Hook eines Subagenten nur, solange dieser Subagent läuft. Der Hook eines Skills läuft dagegen nach dem ersten Aufruf des Skills weiter, bis die Sitzung endet. In Copilot läuft der Hook eines benutzerdefinierten Agenten nur, solange dieser Agent ausgewählt ist.

Nicht jede Regel gehört in einen Hook

Ein Hook läuft jedes Mal. Ein falsch geschriebener Hook läuft also auch jedes Mal falsch. Prüfen Sie vor dem Schreiben diese Punkte:

• Was sich nicht ändert, gehört in die Regeldatei. Die Dokumentation von Claude Code empfiehlt CLAUDE.md für feste Informationen. Ein Hook eignet sich besser, um den aktuellen Zustand weiterzugeben (auf welchem Branch Sie sind, wie das letzte CI-Ergebnis lautet).
• Überlassen Sie Entscheidungen, die Abwägung brauchen, keinem Hook. Die Frage „Braucht diese Änderung einen Test?“ kann eine einfache Textprüfung nicht beantworten; so ein Schritt gehört in einen Skill.
• Stoppen Sie nicht ohne Grund. Zwei unserer drei Hooks geben nur Informationen weiter und stoppen nichts. Ein Hook, der die Arbeit zu Unrecht stoppt, wird schnell abgeschaltet statt repariert.
• Ein Hook, der nach Text sucht, ist keine Sicherheitsmaßnahme. Unsere Merge-Prüfung erkennt keinen Merge-Befehl, der in einer Variable oder in eval steckt. Sie stoppt einen Agenten, der das Fragen vergisst, aber keinen, der die Regel absichtlich umgehen will. Auch die Dokumentation von Codex nennt Hooks “a useful guardrail, not a complete enforcement boundary”. Für feste Erlaubnisse und Verbote empfiehlt die Dokumentation von Claude Code die Berechtigungsregeln.
• Prüfen Sie fremde Hooks wie Code. Befehls-Hooks laufen mit Ihren Benutzerrechten. Codex führt einen Hook aus dem Repository erst aus, wenn Sie ihn geprüft und freigegeben haben. Cursor führt Projekt-Hooks nur in Arbeitsbereichen aus, denen Sie vertrauen. Und Gemini CLI behandelt einen geänderten Hook als neuen Hook, dem es nicht vertraut.

Hooks laufen auf Ihrem Rechner, bevor etwas passiert; ob der geschriebene Code richtig ist, prüfen sie nicht. Das ist die Aufgabe des Code-Reviews: Wenn diffox einen Pull Request prüft, liest es auch die verbindlichen Regeln aus der Regeldatei des Repositorys (AGENTS.md, sonst CLAUDE.md) als Review-Regeln.