Diese Seite ist eine Übersetzung der englischen Dokumentation. Befehle, Bezeichner und Beispiele bleiben unverändert. Runtime 7.24.4 · SDK 2.6.7. Englische Fassung

Lebenszyklus-Hooks

Status: Aktiv
Umfang: aktueller Stand
Zuletzt geprüft: 2026-08-23 Verantwortlich: AX-Code-Laufzeit

Lebenszyklus-Hooks lassen Sie Shell-Befehle bei Agentenereignissen ausführen, ohne die Laufzeit neu zu bauen. Die Hooks ergänzen Berechtigungsregeln und die Isolations-Sandbox: Hooks sind deterministische Nebenwirkungen („immer formatieren“, „nie Force-Push“), während Prompts beratend bleiben.

Ereignisse

Die vier Lebenszyklusereignisse der Sitzung (SessionStart, SessionEnd, PostCompact, Interrupt) und PostToolUseFailure sind nur Beobachtung. Diese Ereignisse feuern und vergessen, blockieren den Lebenszykluspfad nie, und ihre Nutzlasten tragen nur IDs, Gründe und Zeitstempel — nie Gesprächstext, Zusammenfassungen oder Toolausgabe. Subagenten-Sitzungen lösen SessionStart nicht aus (sie erscheinen bereits über SubagentStop). SubagentStop feuert für Kinder, die sowohl von task als auch von task_parallel gestartet wurden.

PostToolUse-Feedback erreicht das Modell

Ein Hook PostToolUse kann Text an das Modell zurückgeben. Er wird innerhalb eines Blocks <hook_feedback event="PostToolUse"> an das Toolergebnis angehängt, nach der eigenen Ausgabe des Tools. Er ersetzt die Ausgabe nie und blockiert nie.

• Ältere Einträge (kein protocol): gekürztes stdout eines Hooks, der mit 0 endete.
• Einträge protocol: "claude-code": hookSpecificOutput.additionalContext, das reason eines Urteils {"decision": "block", "reason": "..."} oder stderr, wenn der Hook mit 2 endet. Andere Exits ungleich null tragen nichts bei.

Feedback ist auf 4.000 Zeichen je Hook und 8.000 Zeichen je Toolaufruf gedeckelt, damit ein lauter Hook den Kontext nicht überfluten kann. Das macht das Paket format-after-edit nützlich: Seine Erinnerung landet jetzt in der nächsten Runde des Modells statt nur im Protokoll.

Diese Namen entsprechen den internen Plugin-Auslösern von AX Code (tool.execute.before / tool.execute.after) plus Hooks auf Sitzungsebene für Prompt, Kompaktierung, Subagent und Stopp. Synthetische Fortsetzungsprompts (interne Prompts agentRouting: "preserve") lösen UserPromptSubmit nicht aus.

Pakete aktivieren

Projekthooks und Plugins führen repositorygesteuerten Code aus, daher sind .ax-code/hooks.json, .ax-code/plugin/ und projektkonfigurierte Plugins standardmäßig deaktiviert. Nach der Prüfung wählen Sie sie außerhalb des Repositorys, wenn Sie AX Code starten:

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

Erzeugen Sie dann .ax-code/hooks.json in Ihrem Projekt:

{
  "packs": ["format-after-edit", "block-force-push", "require-tests-on-stop", "protect-env-files", "log-bash-commands"]
}

Offizielle Pakete (≥5)

Eigene Hooks:

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "bash",
      "command": "echo running bash",
      "blockOnFailure": false
    }
  ]
}

Leitungsprotokoll von Claude Code (optional)

Wenn Sie bereits Hooks für Claude Code geschrieben haben, kann ein Eintrag mit "protocol": "claude-code" das Leitungsprotokoll von Claude Code wählen:

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "bash",
      "command": "my-claude-code-hook.sh",
      "protocol": "claude-code"
    }
  ]
}

Für die blockierbaren Ereignisse (PreToolUse, UserPromptSubmit) werden gewählte Einträge mit der Semantik von Claude Code dekodiert, anstelle der Prüfung blockOnFailure:

• Exit 2 blockiert die Aktion. stderr des Hooks wird als Grund angezeigt. Fehlerhaftes stdout blockiert weiterhin (ausfallsicher).
• Exit 0 mit stdout-JSON {"permissionDecision": "allow"|"deny"|"ask", "reason"?}: allow fährt fort. deny blockiert mit reason. ask pausiert den Toolaufruf an einer interaktiven Berechtigungsnachfrage hook, die den Grund zeigt (Standard "hook requested user confirmation"). Die Nachfrage ist nur interaktiv: Keine Regel always, keine Wildcard-Freigabe und keine autonome Selbstgenehmigung kann sie beantworten, und ein Headless-Lauf lehnt sie ab, was das Modell als gewöhnliche Berechtigungsablehnung sieht. Ein späterer Hook, der deny antwortet, gewinnt über ein früheres ask. UserPromptSubmit hat keinen Toolaufruf, an den eine Nachfrage gehängt werden kann, daher blockiert ask dort weiterhin. Die verschachtelte Form von Claude Code {"hookSpecificOutput": {"permissionDecision": "...", "permissionDecisionReason": "..."}} wird als Alias akzeptiert.
• Jeder andere Exit ist ein nicht blockierender Fehler (protokolliert, die Aktion fährt fort).

Nur beobachtende Ereignisse ignorieren den Dekodierer ganz — sie können nie blockieren. Einträge ohne das Feld protocol verhalten sich genau wie zuvor.

Umgebungsvariablen, die Hook-Befehlen zur Verfügung stehen:

• HOOK_EVENT — Ereignisse: PreToolUse, PostToolUse, PostToolUseFailure, Stop, UserPromptSubmit, PreCompact, SubagentStop, SessionStart, SessionEnd, PostCompact und Interrupt
• HOOK_TOOL — Tool-ID
• HOOK_SESSION_ID
• HOOK_ARGS_JSON — JSON-Toolargumente
• HOOK_ARGS_STDIN=1 — die vollständigen JSON-Argumente stehen immer auf stdin. HOOK_ARGS_JSON ist für Nutzlasten größer als 32 KiB leer
• HOOK_PACK — Paketname, soweit anwendbar

Kindprozesse von Hooks erben eine bereinigte Version der AX-Code-Umgebung. AX Code bewahrt gewöhnliche Plattform- und Werkzeugvariablen, entfernt aber geheimnisartige Namen, URLs mit Zugangsdaten, Zugangsdatenhilfen wie SSH_AUTH_SOCK und Variablen zur Prozesseinspeisung wie NODE_OPTIONS. Die Protokollvariablen HOOK_* oben werden nach der Bereinigung hinzugefügt und sind immer verfügbar.

Voll vertrauenswürdige ältere Hooks, die umgebende Zugangsdaten brauchen, können das frühere Verhalten außerhalb des Repositorys wiederherstellen:

AX_CODE_HOOKS_FULL_ENV=1 AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

Diese Notluke setzt jede Umgebungsvariable jedem aktivierten Hook aus. Ein Repository kann sie nicht über .ax-code/hooks.json anfordern. Verwenden Sie sie nur, nachdem Sie alle Hooks und Pakete geprüft haben.

Sicherheitshinweis: Die Bereinigung der Umgebung verringert die Exposition umgebender Zugangsdaten, sandboxiert Hook-Befehle aber nicht. Hooks bleiben beliebiger Shell-Code, der zugängliche Dateien lesen und das Hostnetz nutzen kann. Behandeln Sie sie als vertrauenswürdigen Code und prüfen Sie jeden aktivierten Hook und jedes Paket.

Verhältnis zur Isolation

Hooks ersetzen die Sandbox nicht. Verwenden Sie:

1. App-Isolation für portable Grenzen von Schreiben und Netz
2. Betriebssystemisolation (das Standard-Backend "auto") für kernelgestützte Bash-Sandbox, soweit verfügbar
3. Hooks für Richtlinien-Nebenwirkungen und harte Blockaden wie Force-Push

Siehe Sandbox-Modus und SECURITY.md.