SSD Nodes Learn Hosting plans →
Anleitungen Matt ConnorVon Matt Connor

Claude Code Hooks: Ereignisse, Exit-Code 2 und Sicherheit

Erfahren Sie, wo Claude Code Hooks liegen, welche Ereignisse sie ausloesen und warum Exit-Code 2 einen Tool-Aufruf vor der Ausfuehrung stoppt.

Was ein Claude-Code-Hook ist

Claude-Code-Hooks sind Shell-Befehle, die Claude Code an festgelegten Punkten seines eigenen Lebenszyklus selbst ausführt. Das ist der gesamte Unterschied zwischen einem Hook und einer Regeldatei. Eine Anweisung in CLAUDE.md ist ein Hinweis, und das Modell wägt sie gegen alles andere in seinem Kontext ab. Ein Hook ist Code und wird ausgeführt, unabhängig davon, ob das Modell zustimmt. Wenn Ihr Agent den Formatter weiterhin überspringt, obwohl Sie ihn zweimal darauf hingewiesen haben, benötigen Sie keine deutlichere Anweisung. Sie benötigen einen Hook.

Der Mechanismus ist klein. Sie registrieren einen Befehl in einer Einstellungsdatei unter einem Ereignisnamen. Wenn dieses Ereignis ausgelöst wird, führt Claude Code Ihren Befehl aus und schreibt die Ereignisdaten als JSON (JavaScript Object Notation) in dessen Standardeingabe (stdin). Ihr Befehl liest diese Daten, führt seine Arbeit aus und antwortet mit einem Exit-Status. Exit 2 bei einem PreToolUse-Hook bricht den Tool-Aufruf ab, bevor er ausgeführt wird. Alles, was Ihr Skript in die Standardfehlerausgabe (stderr) schreibt, wird dem Modell als Begründung übergeben, sofern der Hook nicht zusätzlich JSON mit einer blockierenden Entscheidung ausgibt. Deren Begründung hat Vorrang.

Die Ereignisnamen und Feldnamen in diesem Abschnitt stammen aus der Hooks-Referenz von Claude Code, geprüft am 12. November 2026. Diese Schnittstelle ändert sich schnell. Prüfen Sie daher die Referenz für Ihre eigene Version, bevor Sie JSON aus einem Blogbeitrag, einschließlich dieses Beitrags, übernehmen. Geben Sie Ihre Version mit claude --version aus.

Wo die Hook-Konfiguration liegt

Ein Hook ist ein JSON-Block in einer Einstellungsdatei. Sechs Speicherorte können einen solchen Block enthalten. Der Geltungsbereich der Datei bestimmt den Geltungsbereich des Hooks.

  • ~/.claude/settings.json: jedes Projekt auf Ihrem Rechner, aber auf keinem anderen.
  • .claude/settings.json: ein einzelnes Projekt, in das Repository committet, sodass jeder, der es klont, den Hook erhält.
  • .claude/settings.local.json: ein einzelnes Projekt, nur auf Ihrem Rechner.
  • Verwaltete Richtlinieneinstellungen: organisationsweit und von einem Administrator festgelegt.
  • hooks/hooks.json innerhalb eines Plugins: aktiv, solange das Plugin aktiviert ist.
  • Frontmatter eines Skills oder Subagents. Die Hooks eines Skills bleiben nach dem Aufruf des Skills für den Rest der Sitzung aktiv. Die Hooks eines Subagents sind aktiv, solange dieser Subagent ausgeführt wird.

Hook-Einträge aus diesen Dateien werden zusammengeführt, statt sich gegenseitig zu überschreiben. Eine Projekteinstellungsdatei fügt ihre Hooks zu den Hooks in Ihren Benutzereinstellungen hinzu, statt sie zu ersetzen. Daher können mehrere Hooks aus mehreren Dateien auf dasselbe Ereignis reagieren. Mit "disableAllHooks": true werden sie deaktiviert. Eine Ausnahme bilden Hooks aus verwalteten Richtlinieneinstellungen. Sie laufen weiter, sofern diese Einstellung nicht ebenfalls in den verwalteten Einstellungen angewendet wird.

Führen Sie innerhalb einer Sitzung /hooks aus, um alle aktuell registrierten Hooks nach Ereignis gruppiert aufzulisten. Für jeden Hook werden die Quelldatei und der Matcher angezeigt. Das Menü ist schreibgeschützt. Sie ändern einen Hook, indem Sie die Einstellungsdatei bearbeiten. Der Dateiüberwachungsdienst erkennt die Änderung normalerweise ohne Neustart.

Welche Claude-Code-Hook-Ereignisse gibt es?

Die Hooks-Referenz führt dreiunddreißig Ereignisse auf, von SessionStart bis SessionEnd. Sie decken Kompaktierung, Subagents, Worktrees und Konfigurationsdateien ab. Für Serveraufgaben werden einige davon verwendet.

  • PreToolUse: bevor ein Tool-Aufruf ausgeführt wird, außer bei EndConversation. Dieses Ereignis kann den Aufruf blockieren.
  • PostToolUse: nachdem ein Tool-Aufruf erfolgreich war, außer bei EndConversation. PostToolUseFailure wird stattdessen ausgelöst, wenn der Aufruf fehlschlägt. Ein Hook, der jedes Ergebnis erfassen muss, benötigt daher beide.
  • PermissionRequest: wenn für einen Tool-Aufruf eine Berechtigungsentscheidung erforderlich ist. In diesem Moment würde die Genehmigungsabfrage erscheinen.
  • UserPromptSubmit: wenn Sie eine Eingabe absenden, bevor Claude sie verarbeitet. Die Standardausgabe eines erfolgreichen Hooks wird als Klartext zum Kontext des Modells hinzugefügt.
  • SessionStart und SessionEnd: an jedem Ende einer Sitzung. SessionStart wird unter dem Matcher-Wert compact auch nach einer Kompaktierung ausgelöst.
  • Stop: wenn Claude die Antwort beendet. Das geschieht einmal pro Durchlauf, nicht einmal pro abgeschlossener Aufgabe.

Bei Ereignissen, die Matcher unterstützen, kann eine Gruppe einen matcher enthalten. Dieser legt fest, bei welchen Vorkommen der Hook ausgeführt wird. Bei den Tool-Ereignissen filtert er nach dem Toolnamen. "Edit|Write" wird daher bei Dateiänderungen ausgelöst, aber bei keinen anderen Vorgängen. Matcher unterscheiden zwischen Groß- und Kleinschreibung. Ein leerer Matcher wird bei jedem Vorkommen ausgelöst. Tools von einem MCP-Server (model context protocol) werden als mcp__<server>__<tool> bezeichnet. Ein Matcher mit dem Wert "mcp__github__.*" erfasst daher die Tools eines Servers und lässt die anderen unberücksichtigt.

Stop-Hooks enthalten eine Besonderheit, die Sie vor dem Schreiben eines Hooks kennen sollten. Ein blockierender Stop-Hook schickt das Modell zurück an die Arbeit. Standardmäßig überschreibt Claude Code den nächsten Block nach acht aufeinanderfolgenden Fortsetzungen. Der Zähler wird zurückgesetzt, sobald Claude ein Tool aufruft. Lesen Sie das Feld stop_hook_active aus der Hook-Eingabe aus und beenden Sie den Hook mit Exit-Code 0, wenn der Wert true ist. Andernfalls kann Ihr Hook Claude immer wieder zurück an die Arbeit schicken.

Was ein Hook über stdin empfängt

Wenn Claude kurz davor steht, npm test auszuführen, liest ein PreToolUse-Hook auf Bash dies über stdin:

{
  "session_id": "abc123",
  "cwd": "/home/deploy/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

Zu den allgemeinen Eingabefeldern gehören session_id, cwd, transcript_path und hook_event_name; permission_mode wird nicht bei jedem Ereignis gesendet. Die Tool-Ereignisse fügen tool_name, tool_input und tool_use_id hinzu. Andere Ereignisse enthalten ihre eigenen Felder: UserPromptSubmit erhält den prompt-Text und SessionStart erhält ein source aus startup, resume, clear, compact oder fork.

jq ist der übliche Weg, dies innerhalb eines Shell-Skripts zu lesen, und ein minimales Server-Image enthält es nicht. Installieren Sie es zuerst mit sudo apt install -y jq auf Ubuntu und Debian.

Auswirkungen des Exit-Status auf den laufenden Tool-Aufruf

Es gibt drei mögliche Ergebnisse.

  • Exit 0 bedeutet Erfolg. Alle gültigen JSON-Entscheidungsfelder bleiben wirksam, einschließlich einer Blockierung oder Ablehnung. Bei PreToolUse ist ein Exit 0 ohne Entscheidung keine Genehmigung; der normale Berechtigungsfluss wird weiterhin ausgeführt. Bei UserPromptSubmit, UserPromptExpansion, SessionStart und PostModelSwitch wird Klartext-stdout zum Kontext des Modells hinzugefügt. Bei den meisten anderen Ereignissen wird stdout nur in das Debug-Log geschrieben.
  • Exit 2 blockiert die Aktion bei Ereignissen, die blockiert werden können, darunter PreToolUse. stderr wird zur Nachricht, die mit der Blockierung einhergeht, sofern die JSON-Ausgabe keine blockierende Entscheidung enthält, deren Begründung Vorrang hat. Wer diese Nachricht liest, hängt vom Ereignis ab. Bei PreToolUse und Stop sieht das Modell sie als Begründung. Bei UserPromptSubmit und PreModelSwitch wird sie Ihnen angezeigt und nicht zum Kontext des Modells hinzugefügt. Bei PostToolUse und PostToolUseFailure, die nicht blockiert werden können, wird die Blockierung ignoriert, obwohl stderr das Modell weiterhin als Feedback erreicht. Bei den meisten anderen Ereignissen, die nicht blockiert werden können, wird stderr nur Ihnen angezeigt oder ignoriert. Bei Stop, SubagentStop, TaskCompleted und einem UserPromptSubmit-Hook eines Plugins wird ein Exit 2 mit leerem stdout und einem Fehler wegen fehlender Datei auf stderr als nicht blockierender Fehler behandelt.
  • Jeder andere Exit-Code mit Klartext- oder leerem stdout ist normalerweise ein nicht blockierender Fehler. Das Transkript zeigt einen Hinweis auf einen Hook-Fehler, der die erste Zeile von stderr nach dem Text Failed with non-blocking status code: enthält. Gültiges JSON kann bei Ereignissen wie PreToolUse weiterhin über das Ergebnis entscheiden, es sei denn, das Scheitern des Hooks blockiert die Aktion. WorktreeCreate schlägt bei jedem Exit-Code ungleich Null fehl, und WorktreeRemove schlägt bei einem Exit-Code ungleich Null fehl, wenn das Verzeichnis danach noch existiert.

Für alles, was über eine Blockierung oder Stille hinausgeht, verwenden Sie Exit 0 und geben Sie stattdessen ein JSON-Objekt an stdout aus. Ein PreToolUse-Hook entscheidet mit permissionDecision:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database drops go through a migration, not through the agent."
  }
}

"allow" überspringt die interaktive Abfrage, sofern Berechtigungsregeln und die Genehmigungsanforderungen des Tools dies zulassen, "deny" bricht den Aufruf ab und sendet den Grund an das Modell, und "ask" fordert eine Bestätigung an. Wählen Sie einen Stil pro Hook. Das Mischen von Exit 2 mit einer JSON-Entscheidung auf stdout behält die Blockierung bei, selbst wenn das JSON "allow" angibt.

Wenn mehrere Hooks auf ein Ereignis zutreffen, werden sie parallel ausgeführt, wobei Abfrage- und Agent-Hooks auf zwölf gleichzeitig laufende Prozesse begrenzt sind. Ein deny eines Hooks stoppt seine Geschwister-Hooks nicht; ein Logging-Hook schreibt also weiterhin seine Zeile, während ein Guardrail-Hook denselben Aufruf ablehnt. Für PreToolUse führt Claude Code die Antworten zusammen und behält die restriktivste bei, in der Reihenfolge: Ablehnen (deny), Zurückstellen (defer), Fragen (ask), Erlauben (allow).

Beispiel 1: Blockieren eines destruktiven Befehls vor der Ausführung

Speichern Sie dies als .claude/hooks/block-destructive.sh in Ihrem Projekt:

#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
  if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
    echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
    exit 2
  fi
done

exit 0

Machen Sie es ausführbar und registrieren Sie es dann auf PreToolUse in .claude/settings.json:

chmod +x .claude/hooks/block-destructive.sh
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
            "timeout": 10,
            "statusMessage": "Checking the command against policy"
          }
        ]
      }
    ]
  }
}

Testen Sie das Skript manuell, bevor Sie ihm vertrauen, da ein Hook, der bei seiner eigenen Eingabe abstürzt, normalerweise "fail-open" agiert, wenn onFailure nicht gesetzt ist. Unter Windows ohne Git Bash kann ein fehlschlagender Shell-Form-Hook für PreToolUse oder PermissionRequest stattdessen den Werkzeugaufruf blockieren:

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
  | .claude/hooks/block-destructive.sh
echo $?

Sie sollten die Zeile Blocked by policy: auf stderr und einen Exit-Code von 2 sehen. Führen Sie einen harmlosen Befehl wie ls -la aus; Sie sollten keine Ausgabe und einen Exit-Code von 0 erhalten. In einer Sitzung erscheint der abgelehnte Aufruf im Transkript mit Ihrer Nachricht als Begründung, woraufhin das Modell diese Nachricht liest und sich anpasst.

Eine Eigenschaft macht dies sinnvoll: PreToolUse-Hooks werden vor der Prüfung des Berechtigungsmodus ausgelöst, und zwar in jedem Berechtigungsmodus, sodass eine Ablehnung selbst unter bypassPermissions Bestand hat. Genau das macht einen Hook nützlich in Verbindung mit Claude Code Auto-Modus und dessen Berechtigungseinstellungen, wo die Prompts zwar reduziert sind, der Hook aber weiterhin ausgelöst wird.

Seien Sie ehrlich, was dies betrifft. Das Pattern-Matching auf einem Befehls-String ist eine Schutzmaßnahme gegen einen unvorsichtigen Agenten; es ist keine Grenze gegen einen cleveren Agenten, da derselbe Befehl in einer Form geschrieben werden kann, die Ihr grep niemals sieht. Harte Regeln gehören in das Berechtigungssystem und in das Konto, unter dem der Prozess ausgeführt wird.

Beispiel 2: Formatierung und Linting nach jeder Bearbeitung

Ein PostToolUse mit einem Edit|Write-Matcher wird ausgeführt, nachdem eines dieser Werkzeuge zur Dateibearbeitung erfolgreich war. Speichern Sie dies als .claude/hooks/after-edit.sh:

#!/bin/bash
# Format the edited file, then report lint failures back to the model.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0

case "$FILE" in
  *.py)
    ruff format "$FILE" >/dev/null 2>&1
    if ! ruff check "$FILE" >&2; then
      exit 2
    fi
    ;;
  *.sh)
    if ! shellcheck "$FILE" >&2; then
      exit 2
    fi
    ;;
esac

exit 0
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Bitten Sie Claude, eine schlecht eingerückte Funktion in eine Python-Datei einzufügen, und öffnen Sie anschließend die Datei. Sie wird formatiert zurückgegeben. Dies ist Ihre Überprüfung, dass der Hook ausgeführt wurde, da ein erfolgreicher Hook im Dialog nichts anzeigt.

Der exit 2 macht hier nichts rückgängig. PostToolUse wird erst ausgelöst, nachdem das Werkzeug bereits ausgeführt wurde; die Bearbeitung befindet sich also in jedem Fall auf der Festplatte. Der Vorteil von exit 2 besteht darin, dass die ruff check-Ausgabe das Modell als Feedback erreicht, sodass es den gerade eingeführten Fehler korrigiert, anstatt fortzufahren. Das ist der Unterschied zwischen einem Lint-Fehler, den Sie erst beim Commit bemerken, und einem, den der Agent im selben Durchgang repariert.

Zwei Begrenzungen der Matcher sind hier wichtig. Edit|Write erkennt keine Dateien, die durch einen Shell-Befehl geändert wurden, und Claude schreibt Dateien oft genug über Bash, sodass diese Lücke relevant ist. Für eine Abdeckung pro Aufruf sollten Sie zusätzlich Bash matchen und das Skript die geänderten Dateien mit git status --porcelain auflisten lassen. Für eine Abdeckung pro Durchgang platzieren Sie den Scan stattdessen in einem Stop-Hook.

Beispiel 3: Jeden Tool-Aufruf für Audits protokollieren

Ein leerer Matcher unter PostToolUse wird bei jedem erfolgreichen Tool-Aufruf außer EndConversation ausgelöst. Wenn der Datensatz statt in eine Datei im Home-Verzeichnis in das Systemjournal geschrieben wird, ist er für die eigene Shell des Agenten nicht automatisch unzugänglich: Der Zugriff hängt von den Berechtigungen des Kontos ab. Benutzer können ihre privaten benutzerspezifischen Journale lesen. root und Mitglieder von systemd-journal, adm oder wheel können alle Journaldateien lesen:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{time: now|todate, session: .session_id, cwd: .cwd, tool: .tool_name, input: .tool_input}' | logger -t claude-code -p local0.info"
          }
        ]
      }
    ]
  }
}

Lesen Sie die Einträge mit journalctl -t claude-code -o cat | tail -n 5 wieder aus. Wenn Sie Leseberechtigung für die Datensätze haben, sollte pro erfolgreichem Tool-Aufruf außer EndConversation eine JSON-Zeile erscheinen, wobei der neueste Eintrag zuletzt steht. Wenn nichts angezeigt wird, prüfen Sie sowohl den Journalzugriff als auch, ob der Hook ausgeführt wurde. Der Abschnitt zur Fehlerbehebung weiter unten behandelt den Hook.

Fügen Sie denselben Block unter PostToolUseFailure hinzu, um fehlgeschlagene Aufrufe zu erfassen. PostToolUse wird nur bei Erfolg ausgelöst, und ein fehlgeschlagener Befehl ist normalerweise der interessante Fall. Der Grund für logger statt für das Anhängen an eine Datei im Home-Verzeichnis ist der Besitz: Ein Hook läuft mit demselben Benutzer wie die Shell des Agenten. Alles, woran dieser Benutzer Daten anhängen kann, kann er auch leeren. Das Journal wird von systemd-journald geschrieben. Der Schutz vor dem Löschen hängt weiterhin von den Berechtigungen des Agentenkontos ab.

Wie lange ein Hook laufen darf

DiagrammDefault hook timeout in seconds, by hook type and event
Die Daten hinter diesem Diagramm
[
  {
    "label": "command, http or mcp_tool hook",
    "default_timeout_seconds": 600
  },
  {
    "label": "agent hook",
    "default_timeout_seconds": 60
  },
  {
    "label": "prompt hook",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on UserPromptSubmit, PreModelSwitch or PostModelSwitch",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on MessageDisplay",
    "default_timeout_seconds": 10
  },
  {
    "label": "any hook on SessionEnd",
    "default_timeout_seconds": 1.5
  }
]

Ein Command-Hook erhält standardmäßig 600 Sekunden. Das entspricht zehn Minuten. Einige Ereignisse verkürzen dieses Zeitfenster deutlich. SessionEnd-Hooks teilen sich ein Budget von 1.5 Sekunden. Die Bereinigung am Sitzungsende muss daher schnell abgeschlossen sein. Wenn Sie in Ihren Einstellungsdateien für einen Hook ein längeres timeout festlegen, wird dieses gemeinsame Budget entsprechend erhöht, bis maximal 60 Sekunden.

Ein synchroner Command-, HTTP- oder MCP-Tool-Hook, der sein Zeitlimit erreicht, wird abgebrochen und erzeugt normalerweise keine Entscheidung. Bei PreModelSwitch blockiert ein Timeout den Wechsel. Bei einer PreToolUse-Schutzregel läuft der Tool-Aufruf bei einem Timeout normalerweise mit dem regulären Berechtigungsablauf weiter. Davon ausgenommen ist unter Windows der oben genannte Fall, in dem onFailure nicht gesetzt ist. Halten Sie Schutzregelskripte deshalb klein. Seit Release 2.1.295 können Sie dieses Standardverhalten für einen command- oder http-Hook mit "onFailure": "block" umkehren. Dann führt ein Timeout, ein Absturz oder ein unerwarteter Exit-Code zu einer Blockierung. Dies wirkt sich jedoch nicht auf Stop, SubagentStop, TaskCompleted, TeammateIdle oder Hintergrund-Command-Hooks aus. Für langsame Aufgaben, auf deren Abschluss niemand wartet, etwa das Übertragen eines Logs an einen anderen Ort, setzen Sie "async": true. Der Hook läuft dann im Hintergrund, ohne den Tool-Aufruf aufzuhalten.

Hooks, Regeldateien, Skills und MCP-Server

Vier Dinge werden miteinander verwechselt, weil sie alle das Verhalten eines Agents ändern. Nur eines davon ist keine bloße Empfehlung.

Eine Regeldatei (CLAUDE.md oder eine Datei unter .claude/rules/) ist Text, der in den Kontext des Modells geladen wird. Sie beeinflusst das Verhalten, erzwingt aber nichts. In einer langen Unterhaltung, einem großen Diff und zusammen mit einer neuen Benutzeranfrage kann eine einzelne Zeile daraus untergehen. Das ist der übliche Grund dafür, dass Agents die von Ihnen notierten Anweisungen ignorieren.

Ein Skill ist ein Verzeichnis mit Anweisungen und Skripten, das das Modell lädt, wenn es den Skill für relevant hält. Diese Einschätzung ist der Zweck eines Skills und zugleich seine Grenze: Das Modell entscheidet weiterhin selbst. Beide Seiten zeigen sich an einem Skill wie Ponytail, das einen Agent dazu anhält, die kleinste funktionierende Änderung vorzunehmen, weil es die Herangehensweise an eine gesamte Aufgabe auf eine Weise prägt, die kein Hook leisten könnte, und nur dann, wenn das Modell den Skill lädt.

Ein MCP-Server (Model Context Protocol) stellt dem Modell neue Tools zur Verfügung. Dadurch erweitert sich der Bereich, auf den der Agent zugreifen kann. Das Modell wird dadurch jedoch nicht dazu veranlasst, diese Tools zu verwenden. Außerdem handelt es sich um einen separaten Prozess, den Sie selbst betreiben müssen. Das ist eine eigene Aufgabe: siehe MCP-Server auf einem VPS betreiben.

Ein Hook ist das einzige der vier Elemente, das ausgeführt wird, ohne dass das Modell dies auswählt. Verwenden Sie eine Regeldatei für eine Präferenz und einen Skill für ein Verfahren, das das Modell bei passenden Aufgaben befolgen soll. Verwenden Sie einen Hook für den Schritt, der jedes Mal ausgeführt werden muss, oder für etwas, das niemals geschehen darf. Der ausführlichere Vergleich, einschließlich der Fälle, in denen ein Skill besser geeignet ist als eine Regeldatei, steht unter der Gegenüberstellung von Skills, MCP und Regeldateien.

Ein Plugin ist eine Verpackungsform und kein fünfter Mechanismus. Es bündelt Hooks und Skills zu einer installierbaren Einheit. So kann ein Team dieselbe Schutzmaßnahme auf allen Maschinen bereitstellen: siehe Funktionsweise von Claude-Code-Plugins.

Die Sicherheitsentscheidung auf einem gemeinsam genutzten VPS

Ein Hook ist Code, den der Agent auslöst. Er läuft als der Benutzer, der Claude Code gestartet hat. Er übernimmt die Dateiberechtigungen und die Umgebung dieses Benutzers. Auf einem Laptop ist das eine Frage des Workflows. Auf einem VPS, auf dem ein Agent unbeaufsichtigt läuft, ist es eine Sicherheitsfrage mit vier praktischen Aspekten.

Ein Hook in einem Repository ist Code, den Sie nicht selbst geschrieben haben. .claude/settings.json wird versioniert. Wenn Sie ein Repository klonen und darin eine Sitzung starten, können dadurch Hooks registriert werden, die mit dem Repository ausgeliefert wurden. In einer interaktiven Sitzung stellt Claude Code Projekt-Hooks hinter den Dialog zur Vertrauenswürdigkeit des Arbeitsbereichs für diesen Ordner. Das bedeutet: Mit dem Akzeptieren des Vertrauens entscheiden Sie, die Hooks auszuführen. Lesen Sie zuerst den Block hooks. Eine claude -p- oder SDK-Sitzung, wie sie ein unbeaufsichtigter Agent normalerweise verwendet, zeigt diesen Dialog nie und behandelt den Ordner als vertrauenswürdig. Die Hooks des Repositorys werden daher ohne Nachfrage ausgeführt. Prüfen Sie dessen .claude/-Dateien, bevor Sie darauf aufbauende Skripte erstellen, oder führen Sie Claude Code mit --settings '{"disableAllHooks": true}' aus.

Ein Hook sieht die vollständige Tool-Eingabe. Ein Audit-Hook, der tool_input protokolliert, schreibt jedes Argument jedes Befehls in ein Log. Dazu gehört auch jedes Token, das zufällig in einer Befehlszeile stand. Dieses Log benötigt dann denselben Schutz wie das Geheimnis selbst. Das ist Teil des umfassenderen Problems, Geheimnisse außerhalb der Reichweite eines KI-Agenten zu halten.

Ein Hook kann in den Kontext des Modells schreiben. Text in der Standardausgabe eines erfolgreichen SessionStart- oder UserPromptSubmit-Hooks wird zur Unterhaltung hinzugefügt. Ein Hook, der Text aus einer externen Quelle, einem Issue-Tracker oder einer Logdatei weiterleitet, übergibt dem Modell nicht vertrauenswürdigen Text, als hätten Sie ihn selbst eingegeben. Ein Hook, der eine Notiz aus einer anderen Claude-Code-Sitzung auf demselben VPS weiterleitet, tut dasselbe. Die Ausgabe eines Agenten ist nicht vertrauenswürdiger als die des Issue-Trackers. Behandeln Sie diese Standardausgabe als Eingabe und nicht als Ausgabe.

Berechtigungen sind die eigentliche Kontrolle. Lassen Sie den Agenten als dedizierten, unprivilegierten Benutzer mit nur den benötigten sudo-Regeln laufen. Eine PreToolUse-Verweigerung ist sinnvoll. Sie ist absichtlich nur eine Maßnahme nach dem Best-Effort-Prinzip: Das sagt die Referenz auch über den if-Filter und verweist für eine verbindliche Verweigerung auf das Berechtigungssystem. Die Berechtigungsregeln und das Konto, unter dem der Prozess läuft, sind die Komponenten, die auch unter Druck Bestand haben.

Eine Eigenschaft gilt in jedem Berechtigungsmodus. PreToolUse-Hooks werden in jedem Berechtigungsmodus vor der Prüfung des Berechtigungsmodus ausgelöst. Ein Hook, der deny zurückgibt, blockiert das Tool daher auch unter bypassPermissions. Hooks können die von den Berechtigungsregeln erlaubten Aktionen weiter einschränken. Sie können diese Regeln nicht lockern. Die Ausnahme ist ein Mod. Auf einem System ohne verwaltete Einstellungen und ohne managed-mcp.json-Datei kann ein installierter Mod, der tool.check verarbeitet, einen Aufruf genehmigen, den Ihr PreToolUse-Hook blockiert hat. Das gilt, wenn die Sitzung nicht über /login bei einem Team- oder Enterprise-Plan angemeldet ist. Bei verwalteten Einstellungen, einer managed-mcp.json-Datei oder einem /login eines Team- oder Enterprise-Plans als Anmeldeinformation der Sitzung bleibt ein Aufruf, den ein PreToolUse-Hook blockiert hat, standardmäßig blockiert. Das gilt unabhängig davon, aus welcher Einstellungsdatei der Hook stammt. Eine Sitzung, die mit einem API-Schlüssel oder einem langlebigen CLAUDE_CODE_OAUTH_TOKEN läuft, wie es bei vielen Servern der Fall ist, gilt als nicht angemeldet, selbst wenn eine Anmeldung gespeichert ist. Prüfen Sie, was Claude-Code-Mods ändern können, bevor Sie einen solchen Mod auf einem Server installieren.

Warum wird mein Hook nicht ausgelöst?

Gehen Sie diese Schritte der Reihe nach durch. Jeder Schritt benennt das Symptom, das Sie tatsächlich sehen werden.

  • Führen Sie /hooks aus und prüfen Sie, ob der Hook unter dem erwarteten Ereignis erscheint. Ein im Menü fehlender Hook deutet meist auf einen JSON-Syntaxfehler in der Einstellungsdatei hin, da nachgestellte Kommas und Kommentare nicht zulässig sind oder die Datei sich nicht an einem der sechs oben genannten Speicherorte befindet.
  • Vergleichen Sie den Matcher exakt mit dem Tool-Namen. Matcher unterscheiden zwischen Groß- und Kleinschreibung, daher passt "bash" niemals auf das Tool Bash.
  • Führen Sie das Skript manuell mit einer Beispiel-Eingabe aus, wie in Beispiel 1 oben gezeigt. Ein unerwarteter Exit-Code ist ein Fehler in Ihrem Skript; prüfen Sie auch dessen stdout, da gültiges JSON dennoch eine Entscheidung bei Ereignissen wie PreToolUse liefern kann.
  • Ein Hinweis mit dem Text jq: command not found bedeutet, dass jq auf diesem Rechner fehlt. Ein command not found für Ihr eigenes Skript bedeutet, dass der Pfad nicht aufgelöst werden konnte; verwenden Sie daher ${CLAUDE_PROJECT_DIR} oder einen absoluten Pfad. Wenn das Skript überhaupt nicht startet, ist es wahrscheinlich nicht ausführbar.
  • Der Hook gibt gültiges JSON aus, aber es passiert nichts. Unter macOS und Linux wird ein Hook in Shell-Form über sh -c in einer nicht-interaktiven Shell ausgeführt, aber manche Konfigurationen laden dennoch Ihr Profil, etwa wenn BASH_ENV auf ~/.bashrc verweist. Wenn dieses Profil ein Banner ausgibt, wird das Banner Ihrem JSON vorangestellt. Stdout beginnt dann nicht mehr mit {, weshalb Claude Code den gesamten Inhalt als reinen Text liest und die Entscheidung ignoriert. Da der Hook mit 0 beendet wurde, zeigt das Transkript keinen Fehler an. Bei den meisten Ereignissen landet dieser Text nur im Debug-Log, während er bei UserPromptSubmit, UserPromptExpansion, SessionStart und PostModelSwitch inklusive Banner zum Kontext des Modells hinzugefügt wird. Kapseln Sie alle echo in Ihrem Profil so, dass sie nur in interaktiven Shells ausgeführt werden.
  • Immer noch nicht weiter: Starten Sie die Sitzung mit claude --debug-file /tmp/claude.log und führen Sie tail -f /tmp/claude.log in einem zweiten Terminal aus. Das Debug-Log zeichnet auf, welche Hooks übereinstimmten, welchen Exit-Code jeder einzelne zurückgab und alles, was sie nach stdout und stderr geschrieben haben.

FAQ

Was ist der Unterschied zwischen einem Claude Code Hook und einer CLAUDE.md-Anweisung?

Eine CLAUDE.md-Anweisung ist Text im Kontext des Modells. Sie konkurriert daher mit der Konversation und der aktuellen Anfrage um Aufmerksamkeit, und das Modell kann sie gegen diese abwägen. Ein Hook ist ein Shell-Befehl, den Claude Code an einem festgelegten Punkt seines Lebenszyklus ausführt. Er wird bei jedem Eintreten des Ereignisses ausgeführt, unabhängig davon, was das Modell entschieden hat. Verwenden Sie eine Anweisung für eine Präferenz. Verwenden Sie einen Hook für einen Schritt, der immer erfolgen muss, oder eine Aktion, die niemals erfolgen darf.

Wie verhindere ich, dass Claude Code einen bestimmten Shell-Befehl ausführt?

Registrieren Sie einen PreToolUse-Hook mit einem Bash-Matcher, der den Befehl aus .tool_input.command liest, einen Grund nach stderr schreibt und mit dem Exit-Code 2 beendet. Claude Code bricht den Aufruf ab und zeigt dem Modell Ihren Grund an. Dies geschieht vor der Prüfung des Berechtigungsmodus, sodass die Ablehnung auch im bypassPermissions-Modus Bestand hat. Das Pattern-Matching auf einem Befehls-String ist eher eine Leitplanke als eine Sicherheitsgrenze, da derselbe Befehl in einer Form geschrieben werden kann, die das Muster nicht erkennt. Sichern Sie dies daher mit Berechtigungsregeln und einem privilegierten Konto ab.

Mein Hook gibt gültiges JSON aus, aber es passiert nichts. Warum?

Überprüfen Sie Ihr Shell-Profil auf Text, der vor dem JSON ausgegeben wird. Unter macOS und Linux läuft ein Hook ohne args-Feld über sh -c. In Setups, die weiterhin Ihr Profil laden, wie etwa BASH_ENV, das auf ~/.bashrc verweist, schreibt ein Profil, das ein Banner ausgibt, dieses vor Ihrem JSON auf stdout. Da die Ausgabe nun nicht mehr mit { beginnt, behandelt Claude Code alles als reinen Text und ignoriert die Entscheidung. Da der Hook mit 0 beendet wurde, zeigt das Transkript keinen Fehler an. Schützen Sie jedes echo in Ihrem Profil mit einem Test auf eine interaktive Shell und bestätigen Sie die Korrektur anschließend durch Lesen des Debug-Logs aus claude --debug-file /tmp/claude.log.

Ist es sicher, Claude Code Hooks auf einem gemeinsam genutzten Server auszuführen?

Hooks werden als der Benutzer ausgeführt, der Claude Code gestartet hat, und zwar mit dessen Dateiberechtigungen. Ein Hook kann also alles tun, was dieses Konto tun kann. Zwei Gewohnheiten decken den Großteil des Risikos ab: Führen Sie den Agenten als dediziertes, unprivilegiertes Konto mit einer restriktiven sudo-Richtlinie aus und lesen Sie den hooks-Block eines jeden Repositorys, bevor Sie dessen Arbeitsbereichs-Vertrauensdialog akzeptieren oder claude -p darin ausführen. Projekt-Hooks werden innerhalb von .claude/settings.json ausgeliefert, und der -p-Modus zeigt diesen Dialog niemals an. Setzen Sie "disableAllHooks": true in Ihrer Einstellungsdatei, um Hooks zu deaktivieren, mit Ausnahme von verwalteten Hooks, die die Einstellung auf verwalteter Ebene erfordern; eine Projekteinstellung von false kann eine Benutzereinstellung von true überschreiben.

War dieser Artikel hilfreich?