Claude Code-Hooks: deterministische Kontrolle über die Aktionen des Agenten

Aufbau eines Hooks

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

Drei Bestandteile: das Ereignis, ein Matcher (ein regulärer Ausdruck für den Tool-Namen bei Tool-Ereignissen; weglassen, um alles zu erfassen) und ein oder mehrere Befehle. Der Befehl erhält über stdin ein JSON-Objekt, das das Ereignis beschreibt — bei Tool-Ereignissen enthält es tool_name und tool_input, wodurch das obige Beispiel die gerade bearbeitete Datei findet. Legen Sie es in .claude/settings.json ab, um es mit dem Repository zu teilen, in ~/.claude/settings.json für sich selbst, oder führen Sie /hooks aus und lassen Sie Claude Code es schreiben.

Die Ereignisse

• PreToolUse — bevor ein Tool ausgeführt wird. Das einzige Ereignis, das blockierenkann: Exit-Code 2 bricht den Aufruf ab, und Claude liest Ihre stderr-Ausgabe als Begründung.
• PostToolUse — nachdem ein Tool erfolgreich ausgeführt wurde. Formatierer, Linter und Typprüfungen für die bearbeitete Datei.
• UserPromptSubmit — wenn Sie einen Prompt senden; kann Kontext hinzufügen oder den Prompt ablehnen.
• Stop / SubagentStop — wenn der Agent (oder ein Subagent) kurz vor dem Abschluss steht. Exit-Code 2 bedeutet hier „noch nicht fertig“ — der klassische Anwendungsfall ist, das Beenden zu verweigern, solange Tests fehlschlagen.
• PreCompact — vor /compact; speichern Sie alles, was Sie aus dem vollständigen Gesprächsprotokoll benötigen.
• SessionStart — wenn eine Sitzung beginnt oder fortgesetzt wird; Umgebung laden, Erinnerungen ausgeben.
• Notification — wenn Claude Code Ihre Aufmerksamkeit benötigt (Berechtigungsabfrage, Leerlauf); verbinden Sie dies mit einer Desktop- oder Slack-Benachrichtigung.

Gefährliche Befehle blockieren

#!/usr/bin/env bash
# .claude/hooks/guard.sh  -- PreToolUse, matcher: Bash
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -Eq 'rm -rf|git push --force|DROP TABLE|--no-verify'; then
  echo "blocked by guard.sh: $cmd" >&2
  exit 2
fi
exit 0

Exit-Code 2 legt das Verhalten fest: Der Tool-Aufruf findet nicht statt, und alles, was der Hook auf stderr ausgegeben hat, wird Claude als Erklärung angezeigt. So kann es einen anderen Ansatz wählen, statt denselben Versuch zu wiederholen. Jeder andere Exit-Code ungleich null wird protokolliert, blockiert aber nicht.

„Nicht beenden, bevor die Tests bestanden sind“

#!/usr/bin/env bash
# Stop hook: refuse to finish while the suite is red
if ! npm test --silent >/tmp/claude-test.log 2>&1; then
  echo "Tests are failing; fix them before finishing:" >&2
  tail -n 40 /tmp/claude-test.log >&2
  exit 2
fi

Kombinieren Sie dies mit einer --max-turns Begrenzung bei Ausführungen ohne Benutzeroberfläche, damit ein tatsächlich nicht behebbarer Fehler nicht zu einer Endlosschleife führt.

Hooks vs. CLAUDE.md vs. Berechtigungen

CLAUDE.md enthält Hinweise, die das Modell liest; /permissions ist eine Liste dessen, was es ohne Nachfrage tun darf; Hooks sind Code, der unabhängig davon ausgeführt wird. Verwenden Sie CLAUDE.md für Stil und Kontext, Berechtigungen für die Grenze zwischen erlaubten Aktionen und Rückfragen und Hooks für alles, was jedes Mal gewährleistet sein muss — Formatierung, Suche nach Geheimnissen, verpflichtende Tests, Audit-Protokolle. Sie wirken zusammen: Eine Berechtigung erlaubt die Ausführung von Bash(git *) , ein PreToolUse-Hook blockiert weiterhin git push --force.

Hooks und das Gateway

Hooks laufen lokal und greifen nie auf die API zu. Daher ändert sich nichts, wenn Claude Code auf ANTHROPIC_BASE_URL=https://aiprimetech.ioverweist. Eine nützliche Kombination: ein Stop Hook, der /cost-artige Nutzungsdaten aus Ihren eigenen Protokollen ausgibt, sodass ein Team mit nutzungsbasiert abgerechnetem Guthaben am Ende jeder Sitzung deren Preis sieht.

export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key

Häufig gestellte Fragen

AI Prime Tech ist ein unabhängiges API-Gateway und ist weder mit Anthropic verbunden noch wird es von Anthropic unterstützt oder gesponsert. „Claude“ und „Claude Code“ sind Marken von Anthropic. Die hier beschriebenen Funktionen von Claude Code entsprechen der öffentlichen Dokumentation von Anthropic zum Zeitpunkt der Erstellung und ändern sich häufig; Preise und Modelllisten auf dieser Seite werden aus den aktuellen Einstellungen dieses Gateways ausgelesen.