Hooks und Mods

Ein Hook ist ein Befehl, den Claude Code an einer festen Stelle der Sitzung selbst startet: vor einem Werkzeugaufruf, nach einer Dateiänderung, am Ende einer Antwort. Die Anleitung zu Hooks (externe Seite, code.claude.com) beschreibt sie als Shell-Befehle, die man selbst festlegt und die Claude Code an bestimmten Punkten seines Ablaufs ausführt. Seit Oktober 2026 gibt es dazu Mods. Ein Mod ist ein Plugin mit Funktionen in JavaScript oder TypeScript, die im Programm selbst laufen und ändern können, was Claude Code tut und zeichnet.

Warum eine Regel besser in einem Hook steht als in der Projektanweisung, in welchem Takt die Ereignisse kommen und wie ein Hook eine Handlung abweist, erklärt Vibe-Coding / Agentic Engineering, Kapitel 12 im Pfad zum Vibe Coding. Dieses Kapitel zeigt die Mechanik in Claude Code: wo ein Hook steht, welche Arten es gibt, wie man sie ansieht und abschaltet, und was ein Mod darüber hinaus kann.

Ein Hook in den Einstellungen

Hooks gibt es seit Version 1.0.38 vom 30.06.2025 (Versionsliste (externe Seite, code.claude.com)). Ein Hook entsteht in einer Einstellungsdatei, in einem Block hooks. Dieses Beispiel aus der Anleitung formatiert jede Datei, die Claude bearbeitet, mit Prettier:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Der Aufbau hat drei Stufen. Oben steht das Ereignis, hier PostToolUse, also der Moment nach einem Werkzeugaufruf. Darunter grenzt der matcher ein, bei welchen Werkzeugen der Hook läuft, hier nur bei Edit und Write. Ganz innen steht, was laufen soll. Claude Code übergibt dem Befehl die Daten des Ereignisses als JSON auf der Standardeingabe. Das Werkzeug jq holt daraus den Pfad der Datei, und Prettier formatiert sie. Gelingt der Hook, zeigt Claude Code im Gespräch nichts davon an.

Einen Hook muss man nicht von Hand schreiben. Man kann im Terminal beschreiben, was er tun soll, und Claude schreibt ihn.

Wo ein Hook steht, entscheidet, wo er gilt (Hook-Referenz (externe Seite, code.claude.com)):

• ~/.claude/settings.json: in allen eigenen Projekten, nicht teilbar
• .claude/settings.json: im Projekt, teilbar über das Repository
• .claude/settings.local.json: im Projekt, nicht teilbar
• verwaltete Einstellungen: in der ganzen Organisation, verteilt über die Admins
• hooks/hooks.json eines Plugins: solange das Plugin an ist, teilbar mit dem Plugin
• Kopf eines Skills: ab dem Aufruf bis zum Ende der Sitzung, teilbar mit dem Skill
• Kopf eines Subagents: solange der Subagent läuft, teilbar mit der Agentendatei

Quelle: Hook-Referenz (externe Seite, code.claude.com), Stand 21.10.2026. Welche Datei wann gilt, steht in Kapitel 15. Eine Sitzung in der Cloud liest die eigene ~/.claude/settings.json nicht.

Fünf Arten von Hooks

Die meisten Hooks starten einen Befehl in der Shell. Vier weitere Arten schicken das Ereignis woandershin (Anleitung zu Hooks (externe Seite, code.claude.com)):

• command startet einen Befehl oder ein Skript. Das ist der Normalfall.
• http schickt die Daten des Ereignisses per POST an eine Adresse, etwa an einen gemeinsamen Dienst, der für ein Team protokolliert.
• mcp_tool ruft ein Werkzeug auf einem eingebundenen MCP-Server auf.
• prompt schickt die Daten mit einem eigenen Prompt an ein Claude-Modell, das in einer einzigen Runde urteilt. Die Bauart kam mit Version 2.0.30 als Prüfung am Ende einer Antwort.
• agent startet einen Subagent, der Dateien lesen und Befehle ausführen kann, bevor er urteilt. Diese Art ist laut Doku experimentell und kann sich noch ändern.

Wie verlässlich ein Hook mit Modell urteilt, steht in Vibe-Coding / Agentic Engineering, Kapitel 12, wie man ihn einrichtet, auf der zweiten Ebene.

Was ein Hook zurückmeldet

Ein Befehl antwortet über seinen Rückgabewert und über das, was er ausgibt. Wie der Rückgabewert 2 eine Handlung anhält, warum der gewohnte Fehlercode 1 sie durchlässt und wie man das seit Version 2.1.295 mit onFailure ändert, steht in Vibe-Coding / Agentic Engineering, Kapitel 12 auf der zweiten Ebene.

Endet ein Hook vor einem Werkzeugaufruf mit 0 und ohne Ausgabe, hat er nichts einzuwenden, und der Aufruf geht durch die gewöhnliche Prüfung der Rechte. Die Referenz sagt es so: Der Hook kann den Aufruf ablehnen, sein Schweigen gibt ihn nicht frei. Wer mehr steuern will, endet mit 0 und gibt JSON aus, etwa um eine Rückfrage zu erzwingen oder Text für Claude beizusteuern.

Hooks ansehen und abschalten

Der Befehl /hooks öffnet eine Liste aller eingerichteten Hooks, nach Ereignis geordnet. Ändern lässt sich darin nichts, die Liste dient dem Nachsehen. Jeder Eintrag nennt seine Herkunft: Einstellungen des Nutzers, des Projekts, ein Plugin oder die laufende Sitzung. Wählt man einen aus, zeigt Claude Code den vollen Befehl und die Datei, in der er steht.

Ändert man eine Einstellungsdatei, während Claude Code läuft, übernimmt das Programm die Hooks in der Regel von selbst. Abschalten lassen sich alle Hooks auf einmal, mit "disableAllHooks": true in den Einstellungen. Hooks aus den verwalteten Einstellungen einer Organisation laufen dann weiter. Einzeln abschalten lässt sich ein Hook nicht. Wer ihn loswerden will, löscht seinen Eintrag.

Ein Repository bringt seine Hooks in .claude/settings.json mit. Im Terminal hält Claude Code deshalb alle Hooks aus Ein­stel­lungs­da­teien zurück, bis man dem Ordner vertraut hat, auch die eigenen. Mit -p gilt das nicht, mehr dazu auf der dritten Ebene.

Was ein Mod ist

Mods gibt es seit Version 2.1.287 vom 01.10.2026 (Versionsliste (externe Seite, code.claude.com)). Ein Mod ist ein Plugin, das ändert, wie Claude Code aussieht und sich verhält. Er besteht aus Funktionen in JavaScript oder TypeScript, die Claude Code bei einem Ereignis aufruft: bei einem Werkzeugaufruf, bei einem abgeschickten Prompt oder wenn ein Teil der Oberfläche gezeichnet wird (Doku zu Mods (externe Seite, code.claude.com)).

Auch diese Funktionen heißen in der Doku Hooks. Der Unterschied liegt im Ort. Ein Hook aus den Einstellungen ist ein Befehl, eine Anfrage über das Netz oder ein Prompt außerhalb des Programms. Die Hooks eines Mods laufen als Funktionen in Claude Code selbst. In diesem Kapitel heißt der erste deshalb einfach Hook, der zweite Hook eines Mods.

Ein Hook eines Mods steht zwischen dem Ereignis und dem, was Claude Code damit tun würde. Er kann auf drei Arten damit umgehen (Doku zu Ereignissen (externe Seite, code.claude.com)).

• Beobachten: zählen, mitschreiben, und das Ereignis unverändert weiterreichen.
• Umschreiben: das Ereignis ändern, bevor es weiterläuft, etwa einen Prompt ergänzen oder eine Anzeige erweitern.
• Selbst beantworten: das Ereignis erledigen, sodass das gewohnte Verhalten ausbleibt, etwa einen Befehl ablehnen.

Ein kleines Beispiel nach der Doku zählt die Werkzeugaufrufe und schreibt die Zahl hinter das Wort neben dem Ladesymbol:

// hooks/register.js
let calls = 0

export function register(on) {
  // before each tool call: count it and redraw
  on('tool.call', async ($, e, next) => {
    calls += 1
    $.ui.invalidate('ui.render')
    return next(e)
  })
  // whenever the spinner is drawn: add the count
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    return next({
      ...e,
      props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' },
    })
  })
}

Beide Funktionen teilen sich die Variable calls. Ein Hook mit Befehl startet dagegen bei jedem Aufruf als neuer Prozess und behält nichts im Speicher. Ein Mod kann außerdem eigene Bereiche neben dem Verlauf zeichnen, Teile der Oberfläche ersetzen und Befehle anlegen, die sofort laufen, ohne dass Claude dafür antworten muss.

Einen Mod muss man ebenfalls nicht selbst schreiben. Beschreibt man in einer Sitzung, was er tun soll, schreibt Claude ihn mit Hilfe eines mitgelieferten Skills, und Claude Code fragt, ob es ihn laden soll (Anleitung zum ersten Mod (externe Seite, code.claude.com)). Mods laufen im Terminal ab Version 2.1.287 und im Reiter Code der Desktop-App ab Version 2.1.286, in der Voreinstellung eingeschaltet. Warum Anthropic Mods neben die Hooks gestellt hat, erzählt die dritte Ebene.

Was ein Mod darf

Ein Mod läuft mit denselben Rechten wie Claude Code selbst (Doku zu Mods (externe Seite, code.claude.com)). Er liest und schreibt Dateien, startet Programme und schickt Anfragen ins Netz. Er liest Umge­bungs­va­ria­blen und damit auch einen API-Schlüssel, der dort liegt. Er sieht jeden Prompt und jeden Werkzeugaufruf und kann ein Modell aufrufen, auf Kosten des eigenen Tarifs.

Eine Sandbox umschließt ihn nicht. Ist die Sandbox eingeschaltet, schließt sie die Befehle ein, die Claude in der Shell startet. Ein Prozess, den ein Mod startet, läuft außerhalb davon. Was die Sandbox umschließt, steht in Kapitel 16.

Ein Mod kann auch über Werkzeugaufrufe entscheiden, bevor die Rückfrage erscheint. Auf einem Rechner mit verwalteten Einstellungen oder bei einer Anmeldung mit Team oder Enterprise kommt seine Freigabe in der Voreinstellung an Rückfrageregeln und eigenen Hooks nicht vorbei. Ohne beides kann er einen Aufruf freigeben, den eine Rückfrageregel vorlegen würde oder den ein eigener Hook vor dem Aufruf abgewiesen hat. Wann er auch ein Verbot übergeht, steht in Kapitel 16 auf der dritten Ebene. Die Rückfrage selbst kann ein Mod nicht umgestalten, er kann also nicht ändern, was sie anzeigt.

Die Doku rät deshalb, Mods nur von Autoren und Marktplätzen zu installieren, denen man vertraut. Vorher lässt sich nachsehen, was ein Mod tut, ohne ihn zu starten: claude plugin validate auf dem Ordner des Plugins listet die Ereignisse, an denen er hängt, und die Aufrufe, mit denen er Dateien, Prozesse oder das Netz erreicht. Wie Plugins installiert werden, steht in Kapitel 19. Ein Mod kommt auf demselben Weg.

Mitgelieferte Mods

Einige Funktionen von Claude Code sind selbst Mods. In /plugin stehen sie auf dem Reiter Installed unter Built-in. Aktualisieren oder deinstallieren lassen sie sich nicht, abschalten meist schon (Doku zu Mods (externe Seite, code.claude.com)). Dazu gehören cc-plugin-diff für den Befehl /diff, cc-plugin-agents-md, das eine AGENTS.md als Projektanweisung lädt (Kapitel 14), der Skill, mit dem Claude Mods schreibt, und cc-plugin-telemetry für die Nutzungsdaten. cc-plugin-sec-default schützt, was eine Organisation verwaltet, vor den Mods eines Nutzers und lässt sich nicht abschalten.

Der sechste, cc-plugin-you-should-know, lässt bei längeren Aufgaben einen zweiten Agenten mitlesen. Findet er etwas, das man übersehen könnte, zeigt er einen Hinweis über dem Eingabefeld. Er ist in der Voreinstellung aus.

Der Hinweis im Terminal erscheint, solange man You should know weder ein- noch ausgeschaltet hat. Einschalten lässt sich der Mod laut Versionsliste seit Version 2.1.287 in Sitzungen direkt bei Anthropic mit eingeschalteten Nutzungsdaten. In /plugin steht er wie die anderen mitgelieferten Mods auf dem Reiter Installed unter Built-in und lässt sich dort abschalten. Die Schalter, die installierte Mods anhalten, etwa disableAllHooks oder --safe-mode, halten die mitgelieferten nicht an.

Wann was passt

Hook, Mod, Skill und MCP-Server überschneiden sich. Für einen festen Befehl oder Pfad braucht es keinen Code. Dafür genügt eine Rechteregel wie Bash(npm test). Ein Hook passt, wenn man mit einem vorhandenen Skript abweisen, freigeben oder mitschreiben will. Ein Mod passt, wenn man einen eigenen Bereich, einen eigenen Befehl oder ein umgeschriebenes Ereignis braucht (Doku zu Mods (externe Seite, code.claude.com)). Skills stehen in Kapitel 17, MCP-Server in Kapitel 19. Die Gegenüberstellung aller vier steht auf der zweiten Ebene.

Dort folgen auch die Ereignisse, Filter, Fristen und der Bau eines Mods. Die dritte Ebene erzählt, wie die Hooks seit Juni 2025 gewachsen sind, warum Mods dazukamen und was Codex anders löst.

Diese Ebene geht die Einzelheiten durch. Zuerst kommen die Hooks in den Einstellungen, danach der Bau eines Mods, die Kette der Mods und was eine Organisation festlegt.

Die Ereignisse im Überblick

Die Hook-Referenz (externe Seite, code.claude.com) führt am 21.10.2026 33 Ereignisse. Sieben davon bilden die drei Takte aus Vibe-Coding / Agentic Engineering, Kapitel 12: Start und Ende der Sitzung, Eingabe und Ende einer Antwort, vor und nach jedem Werkzeugaufruf. Die übrigen hängen an einem einzelnen Anlass. Nach Gruppen geordnet:

• Sitzung: SessionStart, SessionEnd und Setup. Setup läuft nur mit --init-only, oder mit --init oder --maintenance zusammen mit -p, und ist für die einmalige Vorbereitung in CI und Skripten gedacht. Installiert ein Hook auf SessionStart Skills, meldet er dazu reloadSkills. Sonst fehlen sie beim ersten Prompt, denn Claude Code sucht die Skills meist, bevor die Hooks fertig sind (Hooks-Doku (externe Seite, code.claude.com)).
• Eingabe: UserPromptSubmit vor der Bearbeitung eines Prompts, UserPromptExpansion, wenn ein getippter Befehl zu einem Prompt wird. Seit Version 2.1.299 läuft UserPromptSubmit vor dieser Umwandlung. Weist der Hook den Prompt ab, laufen auch die Shell-Befehle im Skill oder Befehl nicht mehr. Ein abgewiesener Prompt erreicht Claude nicht. Sein Text steht aber am Ende der Meldung, die der Hook auslöst, und Claude Code schreibt sie ins Transkript der Sitzung auf der Platte. suppressOriginalPrompt nimmt ihn aus der Meldung. Im Transkript und im Verlauf der Eingaben kann er weiter stehen, ein blockierender Hook hält ein Geheimnis also nicht von der Platte fern.
• Werkzeuge: PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure und PostToolBatch nach einer ganzen Gruppe gleichzeitiger Aufrufe.
• Ende der Antwort: Stop, und StopFailure, wenn die Antwort an einem Fehler der API endet.
• Subagents und Teams: SubagentStart, SubagentStop, TaskCreated, TaskCompleted und TeammateIdle.
• Kontext: InstructionsLoaded, wenn eine CLAUDE.md oder eine Regel geladen wird, dazu PreCompact und PostCompact rund ums Verdichten.
• Umgebung: ConfigChange, CwdChanged, DirectoryAdded, FileChanged, WorktreeCreate und WorktreeRemove.
• Modell: PreModelSwitch kann einen Modellwechsel anhalten, PostModelSwitch meldet ihn.
• Anzeige: Notification, wenn Claude Code eine Benachrichtigung schickt, und MessageDisplay, während Text einer Antwort angezeigt wird.
• MCP: Elicitation und ElicitationResult, wenn ein Server während eines Aufrufs eine Eingabe verlangt.

Quelle: Hook-Referenz (externe Seite, code.claude.com), Stand 21.10.2026. Nicht jedes Ereignis kann etwas entscheiden. Welche nur beobachten und welche Falle das beim Verdichten stellt, steht in Vibe-Coding / Agentic Engineering, Kapitel 12 auf der dritten Ebene. Wie InstructionsLoaded beim Nachsehen hilft, welche Anweisungen geladen sind, zeigt Kapitel 14.

Filter mit matcher und if

Ohne matcher läuft ein Hook bei jedem Auftreten seines Ereignisses. Was der matcher prüft, hängt am Ereignis (Anleitung zu Hooks (externe Seite, code.claude.com)). Bei den Werk­zeug­er­eig­nissen ist es der Name des Werkzeugs. Bei SessionStart ist es die Art des Starts (startup, resume, clear, compact, fork), bei Notification die Art der Meldung, bei StopFailure die Art des Fehlers.

Zehn Ereignisse kennen keinen matcher, darunter UserPromptSubmit und Stop. Groß- und Kleinschreibung zählen. Mehrere Werkzeuge trennt ein senkrechter Strich, Edit|Write. Werkzeuge eines MCP-Servers heißen mcp__<server>__<werkzeug>, also trifft mcp__github__.* alle Werkzeuge des Servers github. Wie die Namen der Werkzeuge lauten, steht in Kapitel 04 auf der dritten Ebene.

Seit Version 2.1.85 grenzt das Feld if einen einzelnen Hook weiter ein, in der Schreibweise der Rechteregeln, etwa Bash(git *) (Versionsliste (externe Seite, code.claude.com)). Der Prozess startet dann nur, wenn der Aufruf passt. Bei einem Befehl wie npm test && git push prüft Claude Code jeden Teilbefehl einzeln, auch Befehle in $(). Das Feld wirkt nur bei den fünf Werk­zeug­er­eig­nissen. An jedem anderen Ereignis verhindert es, dass der Hook überhaupt läuft. Warum if nur nach bestem Bemühen filtert, steht in Vibe-Coding / Agentic Engineering, Kapitel 12.

Ein Filter auf Edit|Write sieht nur die Dateiwerkzeuge. Claude kann Dateien auch über Befehle in der Shell anlegen und ändern. Wer jede Änderung sehen muss, etwa für ein Protokoll, nimmt einen Hook auf Stop, der einmal je Antwort den Arbeitsbaum prüft, oder FileChanged für eine bestimmte Datei, gleich wer sie schreibt.

Mehrere Hooks an einem Ereignis

Passen mehrere Hooks auf dasselbe Ereignis, startet Claude Code sie gleichzeitig und wartet, bis jeder fertig ist. Von den Hooks mit Prompt oder Agent laufen dabei höchstens zwölf auf einmal, die übrigen starten, sobald einer fertig ist (Hook-Referenz (externe Seite, code.claude.com)). Die Frist eines wartenden Hooks beginnt erst mit seinem Start. Ein Hook, der ablehnt, hält die anderen nicht auf. Ein Hook, der jeden Befehl ins Protokoll schreibt, schreibt also auch den Befehl, den ein zweiter Hook gleich darauf abweist. Von den Entscheidungen vor einem Werkzeugaufruf gilt die strengste, in der Folge deny, defer, ask, allow. Den Text für Claude aus additionalContext behält Claude Code von allen Hooks.

Hooks aus verschiedenen Ein­stel­lungs­da­teien ersetzen einander nicht. Nutzer, Projekt und lokale Datei fügen ihre Hooks zu denen der Organisation hinzu (Hook-Referenz (externe Seite, code.claude.com)). Auch disableAllHooks folgt dem Vorrang der Einstellungen. Ein Wert im Projekt geht dem in den eigenen Einstellungen vor.

Eingaben umschreiben und Kontext beisteuern

Ein Hook kann mehr als abweisen. Seit Version 2.0.10 darf ein Hook auf PreToolUse die Eingaben eines Werkzeugs ändern, über das Feld updatedInput in seiner JSON-Ausgabe. Seit Version 2.1.300 prüft Claude Code die geänderten Eingaben aus PreToolUse und PermissionRequest wie Claudes eigene. Unbekannte Felder fallen weg, und lehnt das Werkzeug die Eingabe ab, scheitert der Aufruf. Ein Hook auf PostToolUse ersetzt seit Version 2.1.121 das Ergebnis jedes Werkzeugs, vorher ging das nur bei MCP-Werkzeugen. Ändern zwei Hooks die Eingaben desselben Aufrufs, gilt der, der zuletzt fertig wird. Weil sie gleichzeitig laufen, ist die Reihenfolge Zufall. Die Anleitung rät deshalb, nur einen Hook je Werkzeug die Eingaben ändern zu lassen.

Text für Claude kommt auf zwei Wegen in den Kontext. Bei UserPromptSubmit, UserPromptExpansion, SessionStart und PostModelSwitch nimmt Claude Code einfachen Text von der Standardausgabe auf. Bei den übrigen geht es über das Feld additionalContext, wo ein Ereignis es kennt. Es muss innerhalb von hookSpecificOutput stehen. Steht es eine Ebene höher, übergeht Claude Code es ohne Meldung. Seit Version 2.1.163 können auch Stop und SubagentStop so Rückmeldung geben und Claude weiterarbeiten lassen, ohne dass Claude Code das als Fehler des Hooks anzeigt.

Wie ein Hook auf SessionStart mit dem matcher compact Regeln nach dem Verdichten zurückbringt, steht in Vibe-Coding / Agentic Engineering, Kapitel 12 auf der dritten Ebene.

Rückfragen beantworten lassen

Seit Version 2.0.45 läuft ein Hook auf PermissionRequest, wenn Claude Code gleich um eine Erlaubnis fragen würde (Versionsliste (externe Seite, code.claude.com)). Gibt er "behavior": "allow" zurück, beantwortet Claude Code die Rückfrage in eigenem Namen. Das Beispiel der Anleitung gibt so ExitPlanMode frei, also das Werkzeug, mit dem Claude nach einem Plan um den Start bittet. Der Plan-Modus endet dann ohne Dialog, und Claude Code kehrt zum vorigen Modus zurück. Den matcher hält man dabei so eng wie möglich. Ein leerer matcher gäbe jede Rückfrage frei, auch zum Schreiben von Dateien und zu Befehlen in der Shell.

Seit Version 2.1.89 meldet PermissionDenied, dass der Klassifikator im Auto-Modus einen Aufruf abgelehnt hat. Mit retry: true sagt der Hook dem Modell, dass es den Aufruf noch einmal versuchen darf. Was der Klassifikator prüft, steht in Kapitel 16.

Ein Hook auf PreToolUse läuft in jedem Modus, auch in bypassPermissions, und seine Ablehnung hält dort. Hooks aus Einstellungen und Plugins können die Regeln nur verschärfen. Im Plan-Modus bleibt das allow eines Hooks bei einer Dateiänderung ohne Wirkung. Sie bekommt dieselbe Rückfrage, Sperre oder Freigabe wie ohne den Hook. Diese Grenze fällt, sobald man den Plan freigibt oder den Modus wechselt. Die Reihenfolge aller Stationen steht in Kapitel 16, mit den Mods auf der dritten Ebene dieses Kapitels.

Hooks mit Modell

Ein Hook der Art prompt schickt seinen Prompt und die Daten des Ereignisses an ein Claude-Modell. Der Platzhalter $ARGUMENTS setzt die Daten an eine feste Stelle. Ohne model nimmt Claude Code das Modell, das es für Arbeiten im Hintergrund nutzt. Das Modell antwortet nur mit einer Entscheidung als JSON, ok und reason. Ein Beispiel aus der Referenz am Ende einer Antwort:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."
          }
        ]
      }
    ]
  }
}

Was bei "ok": false geschieht, hängt am Ereignis (Hook-Referenz (externe Seite, code.claude.com)). Bei Stop und SubagentStop bekommt Claude die Begründung als nächste Anweisung und arbeitet weiter. Hält das Modell die Bedingung für unerfüllbar, setzt es impossible: true, und Claude hört doch auf. Bei PreToolUse lehnt der Hook den Aufruf ab, und die Antwort endet in der Voreinstellung mit einem Warnhinweis. Mit continueOnBlock: true geht die Begründung stattdessen an Claude, das sich anpassen und weiterarbeiten kann.

Ein Hook der Art agent startet einen Subagent mit Werkzeugen. Er kann Dateien lesen und Befehle ausführen, bevor er urteilt, mit einer Frist von 60 Sekunden und bis zu 50 Runden mit Werkzeugen. Für den Betrieb rät die Anleitung noch zu Hooks mit Befehl. Als Faustregel nennt sie: prompt, wenn die Daten des Ereignisses für das Urteil reichen, agent, wenn der Zustand des Codes geprüft werden muss.

/goal ist genau so ein Hook auf Stop mit Prompt, eingerichtet nur für die laufende Sitzung (Doku zu /goal (externe Seite, code.claude.com)). Wann sich das lohnt, steht in Kapitel 28.

Hooks über das Netz und über MCP

Ein Hook der Art http schickt per POST an eine Adresse, was ein Befehl auf der Standardeingabe bekäme. Die Antwort liest Claude Code im selben Format. Antwortet der Dienst nicht mit einem Status 2xx oder scheitert die Anfrage, meldet Claude Code einen Fehler und lässt die Handlung weiterlaufen. Kopfzeilen dürfen Umge­bungs­va­ria­blen enthalten, aber nur die, die im Feld allowedEnvVars stehen. Die Einstellung allowedHttpHookUrls legt fest, an welche Adressen Hooks überhaupt senden dürfen, auch Hooks aus den verwalteten Einstellungen (Hook-Referenz (externe Seite, code.claude.com)).

Ein Hook der Art mcp_tool ruft ein Werkzeug auf einem eingebundenen MCP-Server auf. Er nennt server und tool und gibt im Feld input Argumente mit, in die Claude Code Werte aus dem Ereignis einsetzt, etwa ${tool_input.file_path}. An Ereignissen, die etwas entscheiden, wartet Claude Code auf einen Server, der noch verbindet. Eine Anmeldung startet der Hook nie, dafür ist /mcp da. Beim Start der Sitzung und bei Setup sind die Server noch nicht da. Dort überspringt Claude Code solche Hooks, ohne das Werkzeug aufzurufen. Was beim Start da sein muss, gehört in einen Hook mit Befehl. Wie MCP-Server eingebunden werden, steht in Kapitel 19.

Fristen und Hooks im Hintergrund

Jede Art hat eine eigene Frist, die das Feld timeout in Sekunden ändert (Anleitung zu Hooks (externe Seite, code.claude.com)):

• command, http, mcp_tool: 10 Minuten. Bei UserPromptSubmit und den beiden Ereignissen zum Modellwechsel 30 Sekunden, bei MessageDisplay 10 Sekunden.
• prompt: 30 Sekunden.
• agent: 60 Sekunden.
• SessionEnd: Alle Hooks dieses Ereignisses teilen sich 1,5 Sekunden. Eine längere Frist im Hook hebt die Grenze mit, höchstens auf 60 Sekunden.

In der Voreinstellung wartet Claude mit der Arbeit, bis ein Hook fertig ist. Mit "async": true läuft ein Hook mit Befehl im Hintergrund weiter, etwa für eine Testsuite nach jeder Änderung. Er kann dann nichts mehr entscheiden, denn die Handlung ist schon geschehen. Was er an Kontext zurückgibt, bekommt Claude in der nächsten Runde. Ruht die Sitzung gerade, wartet die Rückgabe bis zur nächsten Eingabe. Nur ein Hook mit asyncRewake, der mit Code 2 endet, weckt Claude sofort, auch in einer ruhenden Sitzung.

Was ein Hook tut, der seine Frist überschreitet oder nicht startet, und wie "onFailure": "block" daraus seit Version 2.1.295 eine Abweisung macht, steht in Vibe-Coding / Agentic Engineering, Kapitel 12. Zwei Einzelheiten ergänzt die Referenz. Bei PermissionRequest lehnt ein gescheiterter Hook mit dieser Einstellung die Erlaubnis ab. Für Hooks im Hintergrund gilt die Einstellung nicht.

Hooks im Kopf von Skills und Subagents

Seit Version 2.1.0 vom 07.01.2026 können Skills und Subagents eigene Hooks in ihren Kopfdaten mitbringen, im selben Format wie in den Einstellungen (Versionsliste (externe Seite, code.claude.com)). Sie gelten verschieden lange (Hook-Referenz (externe Seite, code.claude.com)):

• Im Kopf eines Subagents laufen sie nur, solange dieser Subagent arbeitet. Einen Hook auf Stop macht Claude Code dort zu SubagentStop.
• Im Kopf eines Skills gelten sie ab dem Aufruf bis zum Ende der Sitzung, auch in späteren Runden. Mit once: true entfernt Claude Code einen solchen Hook nach seinem ersten erfolgreichen Lauf.

---
name: secure-operations
description: Perform operations with security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

Die Hooks eines Skills aus dem Projekt folgen derselben Regel zum Vertrauen in den Ordner wie die Hooks aus Ein­stel­lungs­da­teien. Ob ein Skill beim Aufruf um Zustimmung fragt, steht in Kapitel 17. Die Hooks eines Subagents aus dem Projekt laufen erst, wenn man dem Ordner der Agentendatei vertraut hat. Vor Version 2.1.218 liefen sie auch aus Ordnern ohne dieses Vertrauen. Was sonst im Kopf eines Subagents steht, erklärt Kapitel 20.

Einen Hook prüfen

In der Erweiterung für VS Code gibt es seit Version 2.1.269 neben /hooks einen Dialog, in dem man Hooks in den Einstellungen des Nutzers, des Projekts und den lokalen auch anlegt, ändert und löscht. Hooks aus verwalteten Einstellungen, aus Plugins und aus der Sitzung bleiben dort schreibgeschützt.

Ob ein Hook gelaufen ist, zeigt seine Wirkung, etwa eine neu formatierte Datei, oder die Ansicht des Verlaufs mit Ctrl+O. Für die Einzelheiten schreibt Claude Code mit claude --debug-file /tmp/claude.log ein Protokoll mit Rückgabewerten und Ausgaben jedes Hooks. In einer laufenden Sitzung schaltet /debug es ein (Anleitung zu Hooks (externe Seite, code.claude.com)).

Ein Skript lässt sich auch ohne Claude Code prüfen, indem man ihm passendes JSON auf die Standardeingabe gibt:

echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
echo $?

Drei Fehler beschreibt die Anleitung genauer. Die ersten beiden bleiben ohne Meldung. Erstens liest die Shell unter Git Bash und in manchen Einrichtungen, etwa wenn BASH_ENV auf die ~/.bashrc zeigt, doch das Profil. Ein echo darin landet vor dem JSON des Hooks. Dann beginnt die Ausgabe nicht mit {, Claude Code liest sie als Text und übergeht die Entscheidung. Zweitens steht ein Feld auf der falschen Ebene, etwa permissionDecision außerhalb von hookSpecificOutput. Drittens stößt ein Hook auf Stop, der bei jeder Antwort abweist, an die Grenze aus Vibe-Coding / Agentic Engineering, Kapitel 12. Er sollte das Feld stop_hook_active lesen und dann aufhören.

Einen Mod bauen

Am schnellsten entsteht ein Mod im Gespräch. Claude schreibt ihn mit dem mitgelieferten Skill plugin-authoring in einen eigenen Ordner der Sitzung, ~/.claude/dev-mods/<sitzung>/<name>/ (Anleitung zum ersten Mod (externe Seite, code.claude.com)). Weil ~/.claude ein geschützter Pfad ist, fragt Claude Code in den Modi default und acceptEdits vor jeder Datei. Bei der ersten Datei fragt es außerdem, ob es die Mods dieser Sitzung laden und nach jeder Änderung neu laden soll. Wer zustimmt, sieht jede Änderung am Ende der Antwort wirken.

Ein so geschriebener Mod lädt nur in der Sitzung, die ihn geschrieben hat. Wer ihn behalten will, kopiert den Ordner an einen eigenen Ort und startet Claude Code mit --plugin-dir und diesem Pfad, oder legt ihn in einen Marktplatz. In drei Fällen lädt er gar nicht:

• Niemand kann zustimmen, etwa bei claude -p oder im Modus dontAsk.
• Man hat dem Ordner noch nicht vertraut.
• Mods sind abgeschaltet, durch --safe-mode, --bare, disableAllHooks oder die Organisation.

Von Hand besteht ein kleiner Mod aus drei Dateien (Doku zu Mods (externe Seite, code.claude.com)): plugin.json als Manifest, hooks/hooks.json, die auf den Code zeigt, und register.js mit den Funktionen. Einen Mod, dessen Aufrufe claude plugin validate nicht lesen kann, lädt Claude Code nicht. Für automatische Tests ohne Sitzung gibt es claude plugin test.

Die Kette der Mods

Alle Hooks von Mods an einem Ereignis bilden eine Kette (Doku zu Ereignissen (externe Seite, code.claude.com)). Jeder Hook bekommt drei Werte: die Schnittstelle der Mods als $, das Ereignis als e und den nächsten Schritt als next. Ruft er next(e) auf, kommt der nächste Mod an die Reihe, am Ende Claude Code selbst. Ruft er es nicht auf, beantwortet er das Ereignis allein.

Der erste Mod in der Kette sieht das Ereignis vor allen anderen und das Ergebnis nach ihnen. Er entscheidet, ob die anderen überhaupt laufen. Überspringt ein früher laufendes Plugin einen Hook des eigenen Mods, steht seit Version 2.1.304 eine Zeile im Verlauf. Sie nennt das Ereignis und das Plugin. Die Reihenfolge legt Claude Code nach der Herkunft fest:

1. der Wächter sec-default, wo er lädt, und die Mods der Organisation
2. die Mods, die man selbst installiert
3. Mods der Organisation, die ausdrücklich hinten stehen sollen
4. die übrigen mitgelieferten Mods

Hooks auf PreToolUse aus den verwalteten Einstellungen laufen vor dem ersten Mod. Weist einer davon den Aufruf ab, läuft für ihn kein Hook eines Mods auf tool.call. Wo die übrigen Hooks und das Ereignis tool.check stehen, zeigt die dritte Ebene.

Ein Hook eines Mods, der einen Fehler wirft oder seine Frist von 10 Sekunden überschreitet, bringt die Sitzung nicht zu Fall (Referenz zu Mods (externe Seite, code.claude.com)). Hatte er next noch nicht aufgerufen, überspringt Claude Code ihn. Für einen Mod, der Aufrufe sperren soll, heißt das: Im Fehlerfall läuft der Aufruf weiter. Die Doku rät deshalb zu einem eigenen Fehlerzweig mit .catch, der an seiner Stelle ablehnt. Seit Version 2.1.301 springt dieser Zweig nur ein, wenn der Hook einen Fehler wirft oder seine Frist überschreitet. Seit Version 2.1.290 zeigt claude plugin validate für jeden Hook, der eine Handlung sperren kann, an, ob er einen Fehlerzweig hat (Anleitung zum ersten Mod (externe Seite, code.claude.com)).

Anders liegt der Fall, wenn Claude Code einen Hook aus einem Plugin gar nicht erst erreicht. Manchmal kann es ihm eine Handlung, die er sperren könnte, nicht übergeben. Oder es bekommt seine Antwort nicht zurück. Dann lehnt Claude Code die Handlung seit Version 2.1.299 ab. Ist ein Werkzeug dann schon gelaufen, hält Claude Code sein Ergebnis zurück.

Wo Mods laufen

Die Hooks eines Mods laufen in jeder Art von Sitzung, die das Plugin lädt. Zeichnen kann ein Mod im Terminal, in der Desktop-App und in der Erweiterung für VS Code (Doku zu Mods (externe Seite, code.claude.com)):

Quelle: Doku zu Mods (externe Seite, code.claude.com), Stand 21.10.2026. Ein Mod, der zeichnet, kann nachsehen, wo er läuft, und dort, wo nichts erscheint, eine Zeile in den Verlauf schreiben. Welche Oberflächen es gibt, steht in Kapitel 30.

Hook, Mod, Skill oder MCP-Server

Die Doku zu Mods (externe Seite, code.claude.com) stellt die vier nebeneinander:

Quelle: Doku zu Mods (externe Seite, code.claude.com), Stand 21.10.2026. Ein Plugin kann alle vier enthalten, ein Mod kann also im selben Plugin wie ein Skill und ein MCP-Server kommen.

Was eine Organisation festlegt

Ohne eigene Einstellungen sind Mods an (Doku zur Verwaltung von Mods (externe Seite, code.claude.com)). Ein Nutzer kann einen Mod aus jedem Marktplatz installieren, den die Regeln für Plugins zulassen, oder ihn mit --plugin-dir aus einem Ordner laden. Vor allen Mods des Nutzers lädt der mitgelieferte Wächter sec-default, sobald der Rechner verwaltete Einstellungen hat oder man mit Team oder Enterprise angemeldet ist. Wer mit API-Schlüssel, über Amazon Bedrock, Google Cloud oder Microsoft Foundry arbeitet, bekommt ihn nur auf einem Rechner mit verwalteten Einstellungen. Eine Sitzung mit einem dauerhaften CLAUDE_CODE_OAUTH_TOKEN zählt dabei nicht als Anmeldung.

Der Wächter schützt, was die Organisation verwaltet: ihre Hooks, den Systemprompt, ihre Anweisungen, die Einstellungen, die ein Mod liest, und ihre MCP-Server. Wo er lädt, kann ein Mod des Nutzers in der Voreinstellung keinen Aufruf freigeben, den ein Verbot ablehnt oder eine Rückfrageregel vorlegt. Dabei zählt nicht, aus welcher Einstellungsdatei die Regel kommt. Dasselbe gilt für einen Aufruf, den ein Hook auf PreToolUse abgewiesen hat. Darüber hinaus handelt ein Mod mit den Rechten des Nutzers. Verbote und Hooks gelten dabei nur für die Werkzeugaufrufe von Claude. Ist Read(.env) verboten, kann ein Mod die Datei trotzdem mit seinen eigenen Aufrufen lesen.

Seit Version 2.1.304 bekommt ein Hook eines Mods auf settings.read jede Einstellungsebene einzeln und kann die zusammengeführten Einstellungen umschreiben. Ein Mod der Organisation macht so eine ihrer Einstellungen zur Obergrenze (Versionsliste (externe Seite, code.claude.com)). Was eine Organisation damit festlegt, steht in Kapitel 15.

Drei Schalter in den verwalteten Einstellungen gehen weiter:

• allowManagedModsOnly in der Konfiguration des Wächters lässt nur die Mods der Organisation laufen. Mods aus Plugins des Nutzers, aus --plugin-dir und die, die Claude in einer Sitzung schreibt, laufen nicht. Die Hooks des Nutzers in seinen Einstellungen laufen weiter.
• allowModsToOverrideDenyRules erlaubt Mods ausdrücklich, Verbote zu übergehen.
• allowManagedHooksOnly gilt für die Hooks in Einstellungen. Hooks des Nutzers, des Projekts, der lokalen Datei und aus Plugins laufen dann nicht. Ausgenommen sind Plugins, die die Organisation selbst einschaltet.

Keiner dieser Schalter schließt einen Mod in eine Sandbox ein. Hooks in Einstellungen und in der Hook-Datei eines Plugins laufen neben den Mods wie bisher weiter. Wer in der frühen Testphase Mods mit der Variablen CLAUDE_CODE_ENABLE_FUNCTION_HOOKS abgeschaltet hat, muss umstellen: Ab Version 2.1.287 übergeht Claude Code sie, auch mit dem Wert 0. Welche Einstellungen eine Organisation sonst festlegt, steht in Kapitel 15, was sie bei Plugins sperrt, in Kapitel 19.

Hooks sind in gut fünfzehn Monaten von einer Zusatzfunktion zu einer eigenen Schnittstelle geworden, mit 33 Ereignissen und fünf Arten. Diese Ebene zeigt zuerst, wie sie gewachsen sind und wie ein Hook einem anderen Programm einen Aufruf übergibt. Danach geht es um den Schritt zu den Mods, um die Reihenfolge der Entscheidungen bei einem Werkzeugaufruf und um das Vertrauen in fremde Hooks. Zum Schluss stehen der Vergleich mit Codex und die Stellen, an denen die Mechanik aufhört.

Wie die Hooks wuchsen

Hooks kamen mit Version 1.0.38 am 30.06.2025. Die Versionsliste dankt dabei ausdrücklich für Anregungen aus der Gemeinschaft der Nutzer (Versionsliste (externe Seite, code.claude.com)). Seitdem kam fast jeden Monat etwas dazu. Eine Auswahl:

Quelle: Versionsliste (externe Seite, code.claude.com), Stand 21.10.2026. Die Liste zeigt eine Richtung. Zuerst kamen Ereignisse rund um die Arbeit des Agenten: Werkzeuge, Antworten, Sitzung, Verdichten. Ab Juli 2025 durfte ein Hook mehr als abweisen. Er konnte Kontext beisteuern, ab Oktober Eingaben ändern, ab November Rückfragen beantworten und ab April 2026 das Ergebnis jedes Werkzeugs ersetzen. Seit 2026 hängen Hooks auch an Vorgängen außerhalb des Gesprächs: an Worktrees, an geänderten Dateien, an einem Wechsel des Modells. Mit if in 2.1.85 und onFailure in 2.1.295 wurden Hooks außerdem genauer und strenger. Das zweite schließt die Lücke, die Vibe-Coding / Agentic Engineering, Kapitel 12 beschreibt: einen Hook, der mit falschem Pfad alles durchlässt.

Ein Aufruf, der wartet

Zwei Ereignisse dieser Liste sind für Programme gedacht, die Claude Code steuern. Setup läuft beim Start mit --init-only, oder mit --init oder --maintenance zusammen mit -p, und bereitet ein Repository einmalig vor, etwa in CI. Die Entscheidung defer aus Version 2.1.89 geht weiter (Hook-Referenz (externe Seite, code.claude.com)). Ein Programm, das claude -p als Unterprozess startet, kann damit Claude an einem Werkzeugaufruf anhalten, selbst eine Eingabe einholen und dann weitermachen.

Der typische Fall ist eine Rückfrage von Claude ohne Terminal, in dem jemand antworten könnte. Der Hook auf PreToolUse gibt defer zurück. Der Prozess endet und hält den offenen Aufruf im Verlauf fest. Das steuernde Programm zeigt die Frage in seiner eigenen Oberfläche und startet später claude -p --resume mit derselben Sitzung. Der Hook läuft dann erneut und gibt den Aufruf mit der Antwort frei. Eine Frist gibt es dabei nicht.

Zwei Grenzen nennt die Referenz. Claude Code beachtet defer nur ohne Terminal, mit -p. Und es klappt nur, wenn Claude in der Runde einen einzigen Aufruf macht. Bei mehreren gleichzeitigen Aufrufen übergeht Claude Code die Entscheidung mit einer Warnung, weil sich beim Fortsetzen nur ein Aufruf wiederholen lässt. Wie Claude Code in Skripten und im Agent SDK läuft, steht in Kapitel 29.

Von Hooks zu Mods

Mods kamen am 01.10.2026 mit Version 2.1.287. Die Ankündigung (externe Seite, claude.com) nennt den Anlass. Hooks hatten den Nutzern schon einen Teil der Kontrolle gegeben, die sie sich wünschten. Ein Ereignis umschreiben, eine neue Oberfläche zeichnen oder eine Funktion ersetzen konnten sie nicht. Den Entwurf hatte Anthropic vorab auf GitHub zur Diskussion gestellt.

Der Unterschied liegt in der Bauart. Ein Hook aus den Einstellungen ist ein Befehl, eine Anfrage oder ein Prompt außerhalb des Programms. Er bekommt ein Ereignis als JSON, antwortet und ist danach vergessen. Ein Mod ist ein Modul im Prozess von Claude Code. Seine Hooks hängen in einer Kette vor dem eingebauten Verhalten und teilen sich Variablen. Dateien, Prozesse und das Netz erreichen sie über eine Schnittstelle, deren Aufrufe claude plugin validate vorab auflistet. Auch die Ereignisse der Einstellungs-Hooks sieht ein Mod, unter Namen wie classic.Stop.

Anthropic baut eigene Funktionen inzwischen selbst als Mods. /diff ist einer, und man kann ihn abschalten oder durch eine eigene Fassung ersetzen. Laut Ankündigung sollen mit der Zeit weitere eingebaute Funktionen folgen. Dann könne man Claude Code auf einen kleinen Kern zurückschneiden und nur dazunehmen, was man will.

Die Schnittstelle wächst schnell. In den drei Wochen nach der Einführung kam fast mit jeder Version etwas dazu. Eine Auswahl bis Version 2.1.306 vom 21.10.2026 (Versionsliste (externe Seite, code.claude.com)):

• 2.1.288: $.ui.selection(), der zuletzt markierte Text im Vollbild.
• 2.1.289: das Ereignis agent.spawn auch für Teammates.
• 2.1.290: ceiling im Ereignis tool.check, also die Freigabe, die eine Organisation für ein Werkzeug verlangt.
• 2.1.292: prompt.autocomplete für eigene Vorschläge im Eingabefeld, Prompt Caching für Aufrufe eines Modells aus einem Mod.
• 2.1.293: eine Einstellung, mit der das Schema eines eigenen Werkzeugs von Anfang an im Prompt steht.
• 2.1.295: $.ui.notify für Benach­rich­ti­gungen des Systems.
• 2.1.299: turn.start meldet auch den Beginn jeder Antwort eines Subagents oder Teammates. Unterscheiden lassen sie sich am Feld e.agentId.
• 2.1.300: agent.spawn kann Prompt und Modell eines Workflow-Agenten umschreiben, vorher konnte es ihn nur ablehnen. Dazu kam prompt.change für Änderungen im Eingabefeld, die niemand getippt hat, etwa ein Eintrag aus dem Verlauf.
• 2.1.301: Der Fehlerzweig .catch springt nur noch bei einem Fehler oder einer überschrittenen Frist ein.
• 2.1.304: e.isReadOnly im Ereignis tool.check für Aufrufe, die nur lesen, und decider: "person" für Rückfragen, die nur ein Mensch beantworten darf. Hooks auf settings.read sehen jede Einstellungsebene einzeln, mehr dazu auf der zweiten Ebene.

Eine Änderung betrifft Organisationen. Vor Version 2.1.288 hielt die Variable CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC jede Anfrage ins Netz an, die ein Mod über seine Schnittstelle stellte. Seither hält sie nur noch die mitgelieferten Mods an, und Anfragen, die die Zugangsdaten der Sitzung bei Anthropic mitschicken.

Wer bei einem Aufruf zuerst entscheidet

In welcher Folge Hook, Regeln, Modus und Klassifikator über einen Aufruf entscheiden, erklärt Kapitel 16. Dort steht auf der dritten Ebene auch, wann ein Mod an tool.check Regeln und Hooks übergehen kann. Mit den Mods kommen zwei Plätze dazu. Die ganze Folge für einen Werkzeugaufruf, nach der Doku zu Ereignissen (externe Seite, code.claude.com):

1. Hooks auf PreToolUse aus den verwalteten Einstellungen. Weist einer ab, läuft kein Hook eines Mods auf tool.call.
2. Die Hooks der Mods auf tool.call, in der Reihenfolge der Kette.
3. Die übrigen Hooks auf PreToolUse, aus Einstellungen und Plugins.
4. Die Rechteregeln und der Modus.
5. Die Hooks der Mods auf tool.check, die das bisherige Ergebnis sehen und ersetzen können. Mit verwalteten Einstellungen oder einer Anmeldung mit Team oder Enterprise bleiben dabei Verbote, Rückfrageregeln und die Antworten der Hooks in der Voreinstellung stehen (Doku zu den Rechten (externe Seite, code.claude.com)). Im Plan-Modus geben sie nur Aufrufe frei, die bloß lesen. Ob ein Aufruf nur liest, meldet das Werkzeug seit Version 2.1.304 selbst im Feld e.isReadOnly (Referenz zu Mods (externe Seite, code.claude.com)).
6. Was dann noch offen ist, entscheidet der Mensch, im Auto-Modus der Klassifikator. In dontAsk lehnt Claude Code ab. Einen Aufruf, den nur dieser Modus ablehnen würde, kann ein Mod in Schritt 5 freigeben. Seit Version 2.1.304 kann ein Mod eine Rückfrage mit decider: "person" an einen Menschen binden. Dann gibt nur der Rückfragedialog oder der Callback eines Hosts wie des Agent SDK den Aufruf frei. Wo niemand gefragt werden kann, lehnt Claude Code ihn mit der Begründung des Mods ab (Versionsliste (externe Seite, code.claude.com)).

Die Folge erklärt zwei Stellen, die auf den ersten Blick widersprüchlich wirken. Ein Mod, der einen Aufruf selbst beantwortet, verhindert die Hooks aus Schritt 3, denn die laufen erst, wenn er weiterreicht. Die Hooks aus Schritt 1 umgeht er damit nicht. Schreibt ein Mod einen Aufruf um, laufen die Hooks der Organisation auf dem umgeschriebenen Aufruf noch einmal. Wer eine Grenze für alle durchsetzen will, legt sie deshalb in die verwalteten Einstellungen. Ohne sie und ohne Anmeldung mit Team oder Enterprise kann ein selbst installierter Mod die Abweisung eines Hooks aus der eigenen settings.json aufheben.

Fremde Hooks im eigenen Ordner

Ein Hook führt einen Befehl mit allen Rechten des eigenen Kontos aus. Die Referenz rät, jeden Befehl zu lesen und zu prüfen, bevor man ihn einträgt (Hook-Referenz (externe Seite, code.claude.com)). Das gilt besonders für Hooks, die man nicht selbst eingetragen hat. Drei Wege bringen sie auf den Rechner:

• Ein Repository bringt sie in .claude/settings.json mit. Im Terminal warten sie, bis man dem Ordner vertraut. Mit -p und im Agent SDK laufen sie in einem Ordner, dem man nie vertraut hat. Vor einem Skript über ein fremdes Repository rät die Referenz, dessen Einstellungen zu lesen, mit --bare zu starten oder die Hooks für diesen Lauf abzuschalten. Seit Version 2.1.281 fragt auch claude --bg erst nach dem Vertrauen, bevor es die Hooks eines Projekts startet.
• Ein Plugin bringt sie in hooks/hooks.json mit. Die Ansicht vor der Installation zeigt nur, dass es Hooks gibt, und nicht, was sie ausführen (Doku zur Sicherheit von Plugins (externe Seite, code.claude.com)). Wer es wissen will, liest die Datei.
• Ein Mod lädt in einem Ordner ohne Vertrauen gar nicht, solange die Frage im Terminal offen ist. Was er tut, zeigt claude plugin validate. Ist er geladen, läuft er ohne Sandbox.

Die Referenz nennt dazu einige Regeln für das Schreiben eigener Hooks: Eingaben prüfen, Variablen der Shell in Anführungszeichen setzen, .. in Pfaden abweisen, absolute Pfade benutzen und Dateien wie .env oder .git/ auslassen. Seit Version 2.1.139 startet ein Hook mit dem Feld args sein Programm direkt, ohne Shell dazwischen. Platzhalter für Pfade braucht man dann nicht mehr in Anführungszeichen zu setzen.

Was Codex anders löst

Codex von OpenAI hat Hooks mit derselben Gliederung: Ereignis, eine Gruppe mit matcher, darin die Handler (Doku zu Hooks in Codex (externe Seite, learn.chatgpt.com)). Elf seiner zwölf Ereignisse heißen wie in Claude Code, von PreToolUse bis SessionEnd. Das zwölfte, Interrupt, läuft, wenn man eine laufende Antwort abbricht. Unter den 33 Ereignissen der Hook-Referenz von Claude Code steht keines für diesen Fall. Für Plugins setzt Codex sogar CLAUDE_PLUGIN_ROOT, laut Doku der Verträglichkeit mit vorhandenen Hooks aus Plugins wegen.

Beim Vertrauen geht Codex einen genaueren Weg. Es merkt sich die Zustimmung zu jedem einzelnen Hook, den keine Organisation verwaltet, über einen Hashwert seiner Definition. Ein neuer oder geänderter Hook bleibt aus, bis man ihn geprüft hat. Der Befehl /hooks in Codex dient dazu: Hooks prüfen, freigeben und einzeln abschalten. Claude Code knüpft das Vertrauen an den Ordner. Eine Freigabe einzelner Hooks über einen Hashwert beschreibt seine Hook-Referenz nicht, und einzeln abschalten lässt sich dort keiner. Bei Plugins gilt derselbe Unterschied. Codex überspringt ihre Hooks, bis man sie geprüft hat, auch wenn das Plugin schon eingeschaltet ist.

Bei den Arten bietet Claude Code mehr. Codex führt Hooks mit Befehl und mit MCP-Werkzeug aus. Hooks mit Prompt und mit Agent liest es zwar ein, führt sie aber nicht aus. Die Grenze seiner Hooks nennt Codex selbst. Gehostete Werkzeuge wie die Websuche erreichen sie gar nicht, und einige besondere Wege eines Werkzeugs laufen an ihnen vorbei. Die Doku nennt Hooks auf Werkzeuge deshalb eine nützliche Schutzvorrichtung, die zur vollständigen Durchsetzung von Regeln nicht reicht. Für Claude Code steht derselbe Rat in Vibe-Coding / Agentic Engineering, Kapitel 12: Eine harte Grenze gehört ins Rechtesystem.

Wo die Mechanik aufhört

Ein Hook sieht nur das Ereignis. Stop läuft jedes Mal, wenn Claude eine Antwort beendet, auch mitten in einer Aufgabe. Bricht man selbst ab, läuft er nicht. Ein Hook, der am Ende der Antwort prüft, ob die Aufgabe fertig ist, prüft also oft einen Zwischenstand.

Was geschehen ist, bleibt geschehen. Ein Hook auf PostToolUse kann eine Handlung nicht zurücknehmen, das Werkzeug ist schon gelaufen. Er kann Claude nur eine Rückmeldung geben oder das Ergebnis ersetzen, das Claude zu sehen bekommt.

Ein Hook mit Befehl kann nicht selbst handeln. Er spricht mit Claude Code nur über Ausgaben und Rückgabewert. Einen Befehl mit Schrägstrich oder einen Werkzeugaufruf kann er nicht auslösen. Ein Mod kann mehr. Er kann etwa einen Prompt abschicken. Ein Werkzeug auf einem MCP-Server ruft er unter den Rechteregeln der Sitzung auf.

Ein Muster im Text ist eine Erinnerung. Das gilt auch für Mods. Das Beispiel der Doku, das git push auf main sperrt, liest den Text des Befehls. Die Doku nennt so einen Hook deshalb eine Erinnerung für Claude und rät, den Branch beim Anbieter des Repositorys zu schützen. Ein git -C . push oder ein Skript, das pusht, sieht anders aus als das Muster.

Ein Mod ist Code mit vollen Rechten. Rechteregeln gelten für die Werkzeugaufrufe von Claude. Die eigenen Aufrufe eines Mods erreichen Dateien, Programme und das Netz mit dem Zugang des Nutzers, auch unter den Schaltern einer Organisation aus der zweiten Ebene.

Was offen bleibt

• Wie weit der Umbau geht. Anthropic will weitere eingebaute Funktionen in Mods verlegen. Welche, sagt die Ankündigung nicht. Jede davon wäre dann abschaltbar und ersetzbar, auch für eine Organisation.
• Ein Name für zwei Arten. Die Doku nennt beides Hook und hilft sich auf den Seiten zu Mods mit dem Wort „settings hook“ für den älteren. Wer in der Doku sucht, muss jedes Mal klären, welcher gemeint ist.
• Wie schnell sich das ändert. Die Schnittstelle der Mods ist drei Wochen alt und bekam in dieser Zeit fast mit jeder Version neue Ereignisse und Methoden. Was hier über Mods steht, gilt für den Stand vom 21.10.2026.

Mehr zu Plugins, in denen Mods ausgeliefert werden, steht in Kapitel 19. Wie Hooks und Skills sich die Arbeit teilen, steht in Vibe-Coding / Agentic Engineering, Kapitel 12 und Kapitel 17.