Kurz zusammengefasst:
- AGENTS.md / Skills / Systemanweisungen sind Vorschläge: Das Modell liest sie, kann sie aber vergessen oder umgehen.
- Hooks sind Skripte, die der Harness ausführt: Sie laufen zu festen Zeitpunkten – vor und nach Werkzeugaufrufen – unabhängig davon, ob das Modell die Regeln „im Kopf behält".
- Alle drei Clients können Werkzeugaufrufe abfangen: Claude Code / Codex verwenden
PreToolUse; Cursor verwendetpreToolUse(oder das engerebeforeShellExecution). Zum Blockieren wird typischerweise exit code 2 oder ein JSON-denyverwendet. - Standard ist meist fail-open: Wenn ein Skript abstürzt, das Timeout überschreitet oder mit einem anderen Code als 0/2 beendet wird, wird der Werkzeugaufruf in der Regel trotzdem fortgesetzt. Sicherheitsrelevante Hooks müssen explizit auf fail-closed umgestellt werden (Claude Code:
onFailure: "block"; Cursor:failClosed: true). Laut Codex-Dokumentation wird bei einem Hook-Fehler ein „hook failure" gemeldet; ein Fehler wird standardmäßig nicht als hartes Blockieren gewertet. - Wir haben Claude Code getestet: Ein Bash-Befehl, der
rm -rf /tmp/hooks-deny-meenthält, wurde von PreToolUse blockiert (exit 2);echo hooks-allow-okwurde normal durchgelassen. Cursor konnte in der vorliegenden headless-Umgebung nicht gleichwertig getestet werden; die Cursor-Konfiguration basiert auf der offiziellen Dokumentation.
Laut SwiftLee / Antoine van der Lee vom 02.11.2026 und dem Repost von @peterfriese auf X sind Hooks deutlich zuverlässiger als Regeln in AGENTS.md. Der folgende Artikel richtet sich nach der offiziellen Dokumentation der jeweiligen Anbieter; bei Abweichungen zu Drittquellen gilt die offizielle Dokumentation als maßgeblich.
Verwandte Themen: Plugins können unbemerkt SessionStart-Hooks registrieren (siehe Postman-Plugin prüfen und entfernen); AGENTS.md kann durch den Verzeichniskontext beeinflusst werden (siehe Downloads-Verzeichnis-Hijacking). Hooks ersetzen nicht die Regel „keinen Agent im Downloads-Ordner starten", können aber harte Regeln durchsetzen, die Markdown nicht erzwingen kann. MCP und Berechtigungsgrenzen werden in der Codex Playwright MCP Security Guide behandelt; die Aufgabenteilung zwischen Skills und Hooks in Skills in AI Agents einsetzen.
Vergleichstabelle auf einen Blick
| Eigenschaft | Claude Code | Codex | Cursor |
|---|---|---|---|
| Benutzerkonfiguration | ~/.claude/settings.json | ~/.codex/hooks.json oder config.toml | ~/.cursor/hooks.json |
| Projektkonfiguration | .claude/settings.json | .codex/hooks.json oder config.toml | .cursor/hooks.json (Workspace muss vertrauenswürdig sein) |
| Vor Werkzeugaufruf | PreToolUse | PreToolUse | preToolUse; für Shell-Befehle auch beforeShellExecution |
| Nach Werkzeugaufruf | PostToolUse | PostToolUse | postToolUse / afterFileEdit u. a. |
| Shell-Werkzeugname (Matcher) | Bash | Bash | Shell (beforeShellExecution matcht direkt auf Befehlstext) |
| Blockieren | exit 2 oder JSON permissionDecision: "deny" | exit 2 oder JSON permissionDecision: "deny" / älteres decision: "block" | exit 2 oder JSON permission: "deny" |
| Hook-Fehler (Standard) | Meiste Ereignisse laufen weiter (fail-open); onFailure: "block" möglich | Meldet hook failure; Fehler gilt nicht als hartes Blockieren (laut offizieller Hooks-Seite) | Standard fail-open; failClosed: true möglich |
| Vertrauen / Prüfung | Workspace-Vertrauen beeinflusst Projekt-Hooks | Nicht verwaltete Hooks müssen über /hooks geprüft und als vertrauenswürdig markiert werden; --dangerously-bypass-hook-trust für einmalige Nutzung | Projekt-Hooks werden nur in vertrauenswürdigen Workspaces geladen |
Offizielle Quellen: Claude Code Hooks · Codex Hooks · Cursor Hooks
Warum AGENTS.md allein nicht ausreicht
Laut SwiftLees Erfahrungsbericht: Nachdem er „xcodebuild-Ausgabe filtern" in die globalen Anweisungen geschrieben hatte, schob der Agent weiterhin häufig Rohprotokolle in den Kontext. Anweisungstexte fließen in den Prompt ein – das Modell entscheidet selbst, ob es sie befolgt. Hooks laufen auf Harness-Ebene; das Modell hat kein Vetorecht darüber, ob ein Hook ausgeführt wird.
Empfohlene Aufgabenteilung:
- Anweisungen und Präferenzen → AGENTS.md / Skills (Intent, Stil, Prozesse beschreiben)
- Regeln, die immer gelten müssen → Hooks (gefährliche Befehle abfangen, Build-Befehle umschreiben, Auditing, Session-Ende protokollieren)
- Hooks nicht als einzige Sicherheitsebene betrachten → Manche Pfade umgehen Hooks (die Codex-Dokumentation hält fest: beim
write_stdin-Polling eines bereits per PreToolUse freigegebenen Befehls wird PreToolUse nicht erneut ausgeführt)
Minimalskript: einen gefährlichen Bash-Befehl abfangen (fail-open)
Das folgende Skript funktioniert für alle drei Clients: Es liest JSON von stdin, extrahiert den Befehl, blockiert bei Treffer, lässt andernfalls durch und beendet sich mit exit 0, wenn das Parsen fehlschlägt (fail-open). Als ausführbare Datei speichern, z. B. unter ~/.agents/hooks/block-rm-demo.sh.
#!/bin/bash
# fail-open: jq fehlt oder JSON ungültig → exit 0, Arbeit wird nicht blockiert
input=$(cat || true)
command=$(printf '%s' "$input" | jq -r '.tool_input.command // .command // empty' 2>/dev/null || true)
if [[ -z "$command" ]]; then
exit 0
fi
if [[ "$command" == *"rm -rf /tmp/hooks-deny-me"* ]]; then
# Cursor: JSON-deny verwenden, wenn cursor_version-Feld vorhanden (laut Cursor Hooks-Doku + SwiftLee)
if printf '%s' "$input" | jq -e 'has("cursor_version")' >/dev/null 2>&1; then
jq -n '{permission:"deny", agent_message:"Blocked by PreToolUse-style hook: refusing rm -rf /tmp/hooks-deny-me"}'
exit 0
fi
# Claude Code / Codex: stderr + exit 2
echo "Blocked by PreToolUse hook: refusing rm -rf /tmp/hooks-deny-me" >&2
exit 2
fi
exit 0
Vor der Registrierung chmod +x ausführen.
Registrierung in Claude Code
In ~/.claude/settings.json oder projektbezogen in .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm-demo.sh",
"timeout": 5
}
]
}
]
}
}
Für die Benutzerkonfiguration absoluten Pfad verwenden. Sicherheitsrelevante Hooks sollten "onFailure": "block" erhalten (ab neueren Versionen verfügbar, siehe Hooks-Referenz), damit eine falsch eingetragene Skriptpfad nicht die gesamte Richtlinie lautlos deaktiviert.
Registrierung in Codex
Die Struktur ähnelt Claude Code; Datei ist ~/.codex/hooks.json oder projektbezogen .codex/hooks.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "/usr/bin/bash /absolute/path/to/block-rm-demo.sh",
"timeout": 5,
"statusMessage": "Checking Bash command"
}
]
}
]
}
}
Hinweis: Codex verlangt, dass nicht verwaltete Hooks zuerst im CLI über /hooks geprüft und als vertrauenswürdig markiert werden. Projekt-Hooks erfordern zusätzlich, dass das Verzeichnis .codex/ des Projekts als vertrauenswürdig gilt. Für einmalige Automatisierung steht laut offizieller Dokumentation --dangerously-bypass-hook-trust zur Verfügung. Mit [features] hooks = false können Hooks global deaktiviert werden.
Registrierung in Cursor
Cursors hooks.json ist flacher aufgebaut und erfordert ein version-Feld:
{
"version": 1,
"hooks": {
"preToolUse": [
{
"command": "~/.agents/hooks/block-rm-demo.sh",
"matcher": "Shell",
"timeout": 5
}
]
}
}
Projektbezogene Pfade sind relativ zum Repository-Stamm, z. B. .cursor/hooks/block-rm-demo.sh. Sicherheitsrelevante Hooks sollten "failClosed": true erhalten. Alternativ kann beforeShellExecution verwendet werden; dort matcht der Matcher direkt auf den Befehlstext (z. B. rm\\s+-rf).
Test: Claude Code PreToolUse (mit aicodewith-Key)
Umgebung: Claude Code CLI 2.1.319, projektbezogenes .claude/settings.json mit dem obigen fail-open-Skript, Ausführung über das aicodewith-kompatible Interface im nicht-interaktiven -p-Modus.
- Erlaubt-Pfad: Modell wird gebeten,
echo hooks-allow-okauszuführen → Ausgabehooks-allow-ok, ca. 8 Sekunden. - Blockiert-Pfad: Modell wird gebeten,
rm -rf /tmp/hooks-deny-meauszuführen → PreToolUse-Hook-Fehler, Befehl wurde nicht ausgeführt, ca. 9 Sekunden. Fehlermeldung (Auszug):
PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh]:
Blocked by PreToolUse hook: refusing rm -rf /tmp/hooks-deny-me
- fail-open auf Einheitenebene: Ungültiges JSON an stdin → Skript beendet sich mit exit 0 (nachfolgende Ausführung wird nicht blockiert).
Cursor wurde in der vorliegenden headless-Umgebung nicht gleichwertig getestet; die Cursor-Spalte in der obigen Tabelle basiert auf der offiziellen Cursor-Hooks-Dokumentation. Die Codex-Konfiguration wurde anhand der offiziellen Dokumentation überprüft; der Integrationstest für diesen Artikel wurde auf einem einzigen Claude Code-Pfad durchgeführt, um übermäßigen Verbrauch zu vermeiden.
Wer Codex verwendet, hängt dasselbe Skript an PreToolUse mit Matcher Bash, führt /hooks trust aus und lässt dann einen passenden und einen nicht-passenden Befehl ausführen – das reicht als Selbsttest.
fail-open oder fail-closed?
| Szenario | Empfehlung | Konfiguration |
|---|---|---|
| Komfort (Build-Protokolle filtern, automatisch formatieren) | fail-open | Standard genügt; Skript beendet sich bei Parse-Fehler auch mit exit 0 |
| Sicherheit / Compliance (Löschen, externe Übertragung, Schlüsseldatei-Änderungen verbieten) | fail-closed | Claude Code: onFailure: "block"; Cursor: failClosed: true; testen, ob das Werkzeug blockiert wird, wenn das Skript entfernt wird |
| Verwaltete Codex-Richtlinien | Gemäß requirements.toml / managed hooks des Unternehmens | Siehe offizielle Managed Hooks-Dokumentation; lokale Benutzer-Hooks blockieren bei Fehler standardmäßig nicht hart |
Laut SwiftLee: Komfort-Hooks sollten fail-open sein, damit ein defekter Hook nicht die Arbeit blockiert; nur Hooks, die gefährliche Operationen verhindern, sollten fail-closed sein.
Konfigurationshinweise (alle drei Clients)
- Vor dem Aktivieren lesen: Hooks aus Repositories oder Plugins sind lokale Skripte mit denselben Rechten wie der Benutzer selbst. Plugins wie Postman haben bereits automatisch SessionStart-Hooks installiert – vor der Installation prüfen, was registriert wird.
- Timeout kurz halten: Der Agent wartet auf den Hook; für Komfort-Hooks auf Benutzerebene sind 5 Sekunden üblich.
- Stop-Schleifen begrenzen: Cursor begrenzt
stop/subagentStopmitloop_limit(Standard: 5); „nach dem Ende noch einen Satz anhängen" darf nicht endlos wiederholt werden. - Matcher-Namen nicht verwechseln: Das Shell-Werkzeug heißt in Claude Code / Codex
Bash; in Cursor lautet der allgemeine MatcherShell. - Hooks ≠ Skills: Skills sind benannte Fähigkeitspakete, die auf Anfrage aufgerufen werden; Hooks werden durch Ereignisse ausgelöst und laufen unabhängig davon, ob jemand sie explizit anfordert.
aicodewith-Key für Claude Code / Codex verwenden (optional)
Das Testen von Hooks ist nicht an einen bestimmten Modellanbieter gebunden. Wer Modelle über aicodewith nutzt:
- Claude Code: Base-URL und Key gemäß der Sitedokumentation als kompatible Endpunkte eintragen.
- Codex: In
~/.codex/config.tomlglobalexperimental_bearer_tokenverwenden,name = "aicodewith",base_url = "https://api.aicodewith.ai/chatgpt/v1"(Hinweis:/chatgpt/v1, nicht das nackte/v1).
Häufige Fragen
Was ist der Unterschied zwischen Hooks und AGENTS.md?
AGENTS.md fließt in den Kontext ein; das Modell kann den Inhalt ignorieren. Hooks werden von Claude Code / Codex / Cursor direkt bei Lebenszyklusereignissen ausgeführt. Intent gehört ins Markdown, harte Einschränkungen gehören in Hooks.
exit code 2 oder JSON-deny?
Beide Varianten blockieren. Claude Code / Codex verwenden typischerweise stderr + exit 2; JSON wird eingesetzt, wenn strukturierte Begründungen oder eine Umschreibung der Eingabe (updatedInput) benötigt werden. Cursor bevorzugt bei Permission-Hooks das permission-Feld in stdout-JSON; exit 2 ist dort ebenfalls äquivalent zu deny.
Warum werden meine Projekt-Hooks nicht ausgeführt?
Prüfen: Ist der Workspace / das Projekt als vertrauenswürdig markiert? Hat Codex /hooks trust erhalten? Stimmt der Pfad (Cursor-Projekt-Hooks sind relativ zum Repository-Stamm)? Ist der Matcher auf den richtigen Werkzeugnamen gesetzt? In Claude Code zeigt das /hooks-Menü alle registrierten Hooks mit ihrer Quelle an.
Ersetzen Hooks vollständig eine Sicherheitsrichtlinie?
Nein. Die offizielle Dokumentation räumt ein, dass bestimmte Pfade Hooks umgehen können; Plugins und SessionStart-Skripte sind selbst potenzielle Angriffsflächen. Hooks sind eine deterministische Schutzschicht und müssen zusammen mit Berechtigungsmodellen, Schlüsselverwaltung und der Wahl des Arbeitsverzeichnisses eingesetzt werden.
Ist ask in Cursors preToolUse zuverlässig?
Laut offizieller Cursor-Dokumentation wird "ask" in der Ausgabe von preToolUse derzeit nicht erzwungen. Um eine Operation zu blockieren, "deny" oder exit 2 verwenden. Ereignisse wie beforeShellExecution unterstützen allow / deny / ask.
Zusammenfassung
Regeln, die das Modell „sich merken" soll, in Hooks überführen, die der Harness bei jedem Lauf ausführt. Am besten mit einem einzigen PreToolUse / preToolUse-Minimalskript beginnen: Matcher auf Bash oder Shell setzen, bei Treffer exit 2 / deny, Standard fail-open, für sicherheitsrelevante Fälle fail-closed. Konfigurationsdateien und Ereignisnamen unterscheiden sich zwischen Claude Code, Codex und Cursor – das Schema Ereignis → Matcher → Skript → Entscheidung ist jedoch bei allen drei Clients gleich.
API-Key erstellen → · Modelle und Integrationsdokumentation →



