Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Hooks

Skripte oder MCP-Tools während des Codex-Lebenszyklus ausführen

Mit Hooks kannst du Codex erweitern. Sie führen Skripte oder MCP-Tools aus, während der Agent eine Aufgabe bearbeitet. So kannst du zum Beispiel:

  • Den Chat zur Protokollierung oder Analyse an ein eigenes System senden
  • Die Prompts deines Teams prüfen und das Absenden versehentlich eingefügter API-Schlüssel verhindern
  • Chats zusammenfassen, um automatisch dauerhafte Erinnerungen anzulegen
  • Am Ende einer Chatrunde mit einer eigenen Prüfung Standards durchsetzen
  • Prompts an das aktuelle Verzeichnis anpassen

Für die Ausführung von Hooks gilt:

  • Sind in mehreren Dateien passende Hooks definiert, werden alle ausgeführt.
  • Treffen mehrere Befehls-Hooks auf dasselbe Ereignis zu, startet Codex sie parallel. Ein Hook kann also den Start eines anderen passenden Hooks nicht verhindern.
  • Nicht verwaltete Hooks musst du vor der Ausführung prüfen und als vertrauenswürdig einstufen.

Hooks werden zu unterschiedlichen Zeitpunkten in einer Unterhaltung ausgeführt:

Zeitpunkt Hooks
Während einer Chatrunde PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, UserPromptSubmit, SubagentStop, Stop
Bei jedem Versuch, eine Modellanfrage zu stellen PreModelRequest, PostModelRequest
Wenn du eine laufende Chatrunde unterbrichst Interrupt (wird für Subagenten nicht ausgeführt)
Beim Start einer Sitzung oder eines Subagenten SessionStart, SubagentStart
Am Ende des Haupt-Threads SessionEnd (wird für Subagenten nicht ausgeführt)

Wo Codex nach Hooks sucht

Codex sucht bei jeder aktiven Konfigurationsebene nach Hooks in diesen beiden Formen:

  • hooks.json
  • Inline-Tabellen unter [hooks] in config.toml

Installierte Plugins können ihre Lebenszykluskonfiguration im Plugin-Manifest oder in der Standarddatei hooks/hooks.json mitliefern. Die Regeln für das Paketformat findest du in Plugins entwickeln.

In der Praxis sind vor allem diese vier Speicherorte relevant:

  • ~/.codex/hooks.json
  • ~/.codex/config.toml
  • <repo>/.codex/hooks.json
  • <repo>/.codex/config.toml

Gibt es mehrere Hook-Quellen, lädt Codex alle passenden Hooks. Hooks aus Konfigurationsebenen mit höherer Priorität ersetzen die Hooks aus Ebenen mit niedrigerer Priorität nicht. Enthält eine Ebene sowohl hooks.json als auch Inline-Tabellen unter [hooks], führt Codex die Definitionen zusammen und gibt beim Start eine Warnung aus. Verwende möglichst nur eine der beiden Formen pro Ebene.

Codex erkennt auch Hooks, die aktivierte Plugins mitliefern. Es lädt sie zusammen mit Hooks aus anderen Quellen. Für die Vertrauensprüfung gelten dieselben Regeln wie für andere nicht verwaltete Hooks.

Codex lädt projektlokale Hooks nur, wenn die Konfigurationsebene .codex/ des Projekts als vertrauenswürdig gilt. Bei nicht vertrauenswürdigen Projekten lädt Codex weiterhin die Hooks aus den aktiven Konfigurationsebenen für das Benutzerkonto und das System.

Hooks prüfen und als vertrauenswürdig einstufen

Codex listet die konfigurierten Hooks auf, bevor es entscheidet, welche davon ausgeführt werden dürfen. Bevor ein nicht verwalteter Hook ausgeführt werden kann, musst du seine genaue Definition prüfen und als vertrauenswürdig einstufen. Codex speichert diese Einstufung zusammen mit dem aktuellen Hash des Hooks. Neue oder geänderte Hooks markiert Codex zur Prüfung und überspringt sie, bis du ihnen vertraust.

Mit /hooks in der CLI kannst du Hook-Quellen einsehen, neue oder geänderte Hooks prüfen, Hooks als vertrauenswürdig einstufen oder einzelne nicht verwaltete Hooks deaktivieren. Steht beim Start eine Prüfung aus, fordert dich Codex mit einer Warnung auf, /hooks zu öffnen.

Hooks aus dem System, der MDM-Verwaltung, der Cloud oder requirements.toml sind als verwaltet gekennzeichnet. Sie gelten gemäß Richtlinie als vertrauenswürdig und lassen sich in der persönlichen Hook-Übersicht nicht deaktivieren.

Wenn du bei einer einmaligen Automatisierung die Hook-Quellen bereits außerhalb von Codex prüfst, kannst du --dangerously-bypass-hook-trust übergeben. Für diesen Aufruf führt Codex aktivierte Hooks auch ohne gespeicherte Vertrauenseinstufung aus.

Aufbau der Konfiguration

Die Hook-Konfiguration hat drei Ebenen:

  • Ein Hook-Ereignis wie PreToolUse, PostToolUse, PreCompact, SubagentStart oder Stop
  • Eine Matcher-Gruppe, die festlegt, unter welchen Bedingungen das Ereignis zutrifft
  • Ein oder mehrere Hook-Handler, die ausgeführt werden, wenn die Bedingungen der Matcher-Gruppe erfüllt sind
{
  "description": "Optional lifecycle hooks for this workspace.",
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/session_start.py",
            "statusMessage": "Loading session notes",
            "additionalContextLimit": 5000
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/session_end.py",
            "timeout": 3
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py\"",
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/permission_request.py\"",
            "statusMessage": "Checking approval request"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_review.py\"",
            "statusMessage": "Reviewing Bash output"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/user_prompt_submit_data_flywheel.py\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/stop_continue.py\"",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Hinweise:

  • description ist ein optionales Metadatenfeld auf der obersten Ebene einer hooks.json-Datei. Es hat keinen Einfluss darauf, welche Hooks ausgeführt werden.
  • timeout wird in Sekunden angegeben.
  • Ohne timeout verwendet Codex für die meisten Hooks 600 Sekunden.
    • Für SessionEnd und Interrupt gilt standardmäßig 1 Sekunde. Zulässig sind bis zu 3 Sekunden.
  • statusMessage ist optional.
  • additionalContextLimit legt fest, wie viel additionalContext ein Befehls-Hook direkt an das Modell senden kann. Bei längeren Ausgaben speichert Codex den vollständigen Text auf dem Datenträger und sendet eine kürzere Vorschau. Siehe Umfangreiche Hook-Ausgaben.
  • Mit commandWindows kannst du optional einen abweichenden Befehl nur für Windows angeben. In TOML kannst du command_windows oder commandWindows verwenden.
  • Setze async auf true, um einen Befehls-Hook im Hintergrund auszuführen.
  • Codex unterstützt Handler vom Typ command und mcp_tool. Handler vom Typ prompt und agent liest Codex ein, überspringt sie aber bei der Ausführung.
  • Befehle verwenden das cwd der Sitzung als Arbeitsverzeichnis.
  • Löse Pfade für Hooks im Repository möglichst relativ zum Git-Stammverzeichnis auf. Bei einem relativen Pfad wie .codex/hooks/... hängt der Speicherort davon ab, in welchem Verzeichnis du Codex startest. Ein vom Git-Stammverzeichnis ausgehender Pfad funktioniert auch beim Start in einem Unterverzeichnis.

Entsprechende Inline-Konfiguration in TOML für config.toml:

[[hooks.SessionStart]]
matcher = "^compact$"

[[hooks.SessionStart.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/session_start.py"'
additionalContextLimit = 5000

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

[[hooks.PostToolUse]]
matcher = "^Bash$"

[[hooks.PostToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_review.py"'
timeout = 30
statusMessage = "Reviewing Bash output"

Hooks für MCP-Tools

Mit einem MCP-Tool-Hook kann ein Lebenszyklusereignis ein Tool auf einem bereits verbundenen MCP-Server aufrufen. Der Hook sendet strukturierte Argumente direkt an das Tool. Für die Vertrauensprüfung und das Ausgabeformat gelten dieselben Regeln wie bei einem Befehls-Hook.

Einen MCP-Tool-Hook konfigurieren

Dieser Hook lässt den MCP-Server scanner jeden Patch prüfen, nachdem Codex Dateien geschrieben oder bearbeitet hat:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "scanner",
            "tool": "scan_patch",
            "input": { "patch": "${tool_input.command}" },
            "timeout": 30,
            "statusMessage": "Scanning edited files"
          }
        ]
      }
    ]
  }
}
Feld Bedeutung
type Muss mcp_tool sein.
server Name eines bereits verbundenen MCP-Servers (Pflichtfeld).
tool Name eines Tools, das dieser Server bereitstellt (Pflichtfeld).
input Optionales JSON-Objekt mit Vorlagen für die Argumente. Standardwert ist {}.
timeout Optionales Zeitlimit für die aktive Ausführung in Sekunden. Standardwert ist 600.
statusMessage Optionale Meldung, die während der Ausführung des Hooks erscheint.

Argumente mit Werten aus dem Hook-Ereignis füllen

Mit ${field.nested} liest du ein verschachteltes Feld aus dem Hook-Ereignis über einen durch Punkte getrennten Pfad aus. Steht ein Platzhalter für den gesamten Wert, bleibt dessen JSON-Typ erhalten. Innerhalb einer längeren Zeichenfolge wird der Wert als Text eingefügt. Codex ersetzt Platzhalter in Objekten und Arrays rekursiv.

Enthält ein Ereignis {"tool_input":{"file_path":"src/main.rs","count":3}}, wird aus dieser Argumentvorlage:

{
  "path": "${tool_input.file_path}",
  "count": "${tool_input.count}",
  "message": "Scanning ${tool_input.file_path}"
}

folgendes JSON-Objekt:

{
  "path": "src/main.rs",
  "count": 3,
  "message": "Scanning src/main.rs"
}

Ausführung und Lebenszyklus

  • Hooks verwenden eine bestehende MCP-Verbindung. Sie starten keine Server und stellen unterbrochene Verbindungen nicht wieder her.
  • Ein Hook kann einen Vorgang blockieren, wenn das Tool eine entsprechende Entscheidung zurückgibt. Fehler, fehlende Server und nicht verfügbare Tools blockieren den Vorgang nicht.
  • MCP-Tool-Hooks laufen synchron. Sie fordern keine Genehmigung für das Tool an und lösen keine weiteren Hooks aus.
  • Es gilt das kürzere der beiden Zeitlimits für Hook und Server. Die Wartezeit auf eine Antwort bei einer MCP-Elizitation zählt nicht mit.
  • SessionStart-Hooks können ausgeführt werden, bevor ein MCP-Server bereit ist. In diesem Fall blockieren sie die Sitzung nicht.
  • SessionEnd unterstützt keine MCP-Tool-Hooks.

Hooks deaktivieren

Hooks sind standardmäßig aktiviert. Um sie zu deaktivieren, trage Folgendes in config.toml ein:

[features]
hooks = false

Verwende hooks als Konfigurationsschlüssel für die Funktion. Der veraltete Alias codex_hooks funktioniert weiterhin. Admins können Hooks auf dieselbe Weise verbindlich deaktivieren, indem sie in requirements.toml den Eintrag [features].hooks = false setzen.

Verwaltete Hooks aus requirements.toml

Wähle die Hooks passend zu der Umgebung, die die Aufgabe koordiniert.

Hooks bei der Orchestrierung in der Cloud

Sind in einem Workspace verwaltete Richtlinien und Remote-Hooks aktiviert, können Work Cloud mit Zugriff auf den lokalen Computer und dots bei unterstützten Aufgaben- und Tool-Ereignissen einen MCP-Dienst aufrufen. Diese Aufrufe verwenden die mcp_tool-Handler, die dein Workspace-Admin in Agent Security konfiguriert. Work Cloud ohne Zugriff auf den lokalen Computer und persönliche Konten verwenden diese Enterprise-Hooks nicht.

Die Orchestrierung in der Cloud unterstützt ausschließlich globale MCP-Hooks, auch wenn ein Tool auf einem verbundenen Computer ausgeführt wird. Sie unterstützt weder Befehls-, Prompt- oder Agenten-Handler noch Hooks aus der lokalen Konfiguration, aus Plugins oder aus lokalen Verzeichnissen. Auch umgebungsspezifische Hooks und MCP-Hooks für SessionEnd werden nicht unterstützt. Erfolgen sowohl die Orchestrierung als auch die Ausführung lokal, unterstützen rein lokale Threads von Work und Codex weiterhin ihre bisherigen Hooks.

Ein unterstützter Hook kann eine Aktion blockieren, indem er sie ausdrücklich ablehnt. Tritt bei PreToolUse ein Fehler oder eine Zeitüberschreitung auf oder ist die Antwort fehlerhaft formatiert, kann das Tool trotzdem ausgeführt werden. MCP-Hooks erfassen nur einen Teil der Ereignisse für das Auditprotokoll. Welche Prüfungen beim Rollout anstehen und was das Auditprotokoll abdeckt, erfährst du in Hooks und Netzwerkkompatibilität prüfen.

Verwaltete Hooks bei lokaler Ausführung von Codex

Definiere lokale Codex-Hooks unter [hooks] in requirements.toml. Damit verwaltete Hooks auch dann ausgeführt werden, wenn jemand Hooks lokal deaktiviert hat, gib [features].hooks = true in requirements.toml zusammen mit [hooks] verbindlich vor. Mit allow_managed_hooks_only = true ignoriert Codex Hooks aus Benutzerkonten, Projekten, Sitzungen und Plugins und lässt weiterhin von Admins verwaltete Hooks zu.

allow_managed_hooks_only = true

[features]
hooks = true

[hooks]
managed_dir = "/enterprise/hooks"
windows_managed_dir = 'C:\enterprise\hooks'

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 /enterprise/hooks/pre_tool_use_policy.py"
command_windows = 'py -3 C:\enterprise\hooks\pre_tool_use_policy.py'
timeout = 30
statusMessage = "Checking managed Bash command"

Hinweise zu verwalteten Hooks:

  • managed_dir gilt für macOS und Linux.
  • windows_managed_dir gilt für Windows.
  • Codex verteilt die Skripte in managed_dir nicht. Installiere und aktualisiere sie separat mit den Verwaltungstools deines Unternehmens.
  • Befehle für verwaltete Hooks sollten absolute Pfade zu Skripten im konfigurierten verwalteten Verzeichnis verwenden.
  • Mit allow_managed_hooks_only = true überspringt Codex Hooks aus Benutzerkonten, Projekten, Sitzungen und Plugins. Verwaltete Hooks aus requirements.toml und anderen verwalteten Konfigurationsebenen lädt Codex weiterhin.

Mit Plugins ausgelieferte Hooks

Wenn ein Plugin aktiviert ist, kann Codex dessen Lebenszyklus-Hooks zusammen mit persönlichen, projektlokalen und verwalteten Hooks laden.

Standardmäßig sucht Codex im Stammverzeichnis des Plugins nach hooks/hooks.json. Das Plugin-Manifest kann diese Vorgabe mit einem hooks-Eintrag in .codex-plugin/plugin.json überschreiben. Der Eintrag kann einen mit ./ beginnenden Pfad, ein Array von mit ./ beginnenden Pfaden, ein direkt eingebettetes Hook-Objekt oder ein Array solcher Objekte enthalten.

{
  "name": "repo-policy",
  "hooks": "./hooks/hooks.json"
}

Codex löst die Hook-Pfade im Manifest relativ zum Stammverzeichnis des Plugins auf. Sie müssen innerhalb dieses Verzeichnisses liegen. Definiert das Manifest hooks, verwendet Codex die Einträge aus dem Manifest anstelle der Standarddatei hooks/hooks.json.

Befehle für Plugin-Hooks erhalten folgende Umgebungsvariablen:

  • PLUGIN_ROOT ist eine Codex-spezifische Erweiterung und verweist auf das Stammverzeichnis des installierten Plugins.
  • PLUGIN_DATA ist eine Codex-spezifische Erweiterung und verweist auf das beschreibbare Datenverzeichnis des Plugins.
  • Aus Kompatibilitätsgründen setzt Codex für bestehende Plugin-Hooks auch CLAUDE_PLUGIN_ROOT und CLAUDE_PLUGIN_DATA.

Plugin-Hooks verwenden dasselbe Ereignisschema wie andere Hooks. Prüfe sie vor der Ausführung und stufe sie als vertrauenswürdig ein. Öffne dazu in der CLI /hooks. Wähle in der Desktop-App im Editor Hooks überprüfen oder öffne Einstellungen > Hooks. Ändert ein Plugin-Update ein mitgeliefertes Skript, verlangt Codex eine erneute Prüfung, auch wenn die Hook-Definition gleich bleibt.

Matcher-Muster

Das Feld matcher enthält einen regulären Ausdruck, der festlegt, wann ein Hook ausgelöst wird. Mit "*" oder "" oder ganz ohne matcher erfasst der Hook jedes Auftreten eines unterstützten Ereignisses.

Derzeit berücksichtigen nur einige Codex-Ereignisse den matcher:

Ereignis Filterkriterium für matcher Hinweise
PermissionRequest Tool-Name Unterstützt werden unter anderem Bash, apply_patch* und MCP-Tool-Namen
PostToolUse Tool-Name Siehe Unterstützte Tools
PostCompact Auslöser der Kontextverdichtung Mögliche Werte sind manual und auto
PreModelRequest, PostModelRequest Nicht unterstützt Beide Ereignisse werden bei jedem Versuch ausgelöst, eine Modellanfrage zu stellen.
PreCompact Auslöser der Kontextverdichtung Mögliche Werte sind manual und auto
PreToolUse Tool-Name Siehe Unterstützte Tools
SessionEnd Grund für das Sitzungsende Derzeit nur other
SessionStart Art des Sitzungsstarts Mögliche Werte sind startup, resume, clear, compact und fork
SubagentStart Typ des Subagenten Der Wert hängt davon ab, welcher Subagent startet
SubagentStop Typ des Subagenten Der Wert hängt davon ab, welcher Subagent seine Ausführung beendet
UserPromptSubmit Nicht unterstützt Codex ignoriert den konfigurierten matcher für dieses Ereignis
Stop Nicht unterstützt Codex ignoriert den konfigurierten matcher für dieses Ereignis
Interrupt Nicht unterstützt Codex ignoriert den konfigurierten matcher für dieses Ereignis

*Für apply_patch sind als matcher auch die Werte Edit und Write möglich.

Beispiele:

  • Bash
  • ^apply_patch$
  • Edit|Write
  • mcp__filesystem__read_file
  • mcp__filesystem__.*
  • startup|resume|clear|compact|fork
  • manual|auto

Unterstützte Tools

PreToolUse und PostToolUse können neben Shell- und MCP-Aufrufen weitere Tool-Aufrufe erfassen. Die meisten lokalen Funktionstools verwenden denselben Ausführungspfad für Hooks. Du kannst daher nach ihrem Tool-Namen filtern, ihre JSON-Argumente prüfen und mit PreToolUse den Aufruf blockieren oder umschreiben.

Art des Tool-Aufrufs PreToolUse PostToolUse Hinweise
Shell-Befehle Ja Ja Verwende Bash als Matcher.
Einheitliche Befehlsausführung (exec_command) Ja Ja Verwende Bash als Matcher. Eine spätere Statusabfrage mit write_stdin kann das PostToolUse-Ereignis des ursprünglichen Befehls liefern, sobald dieser beendet ist.
apply_patch Ja Ja Verwende apply_patch, Edit oder Write als Matcher.
MCP-Tools Ja Ja Filtere nach dem Namen des MCP-Tools, etwa mcp__filesystem__read_file.
Andere lokale Funktionstools Ja Ja Filtere nach dem Namen des Funktionstools, etwa update_plan. Für spawn_agent passt auch Agent.
Gehostete Tools wie WebSearch Nein Nein Diese Tools verwenden den Hook-Ausführungspfad für lokale Funktionstools nicht.

write_stdin überträgt Daten für eine bestehende Sitzung der einheitlichen Befehlsausführung. Es löst PreToolUse nicht erneut aus, wenn es Eingaben an einen Befehl sendet oder den Status eines Befehls abfragt, der PreToolUse bereits durchlaufen hat.

Einige spezialisierte Tools können vom üblichen Hook-Ausführungspfad abweichen. Tool-Hooks bieten zusätzlichen Schutz, können Richtlinien aber nicht lückenlos durchsetzen.

Gemeinsame Eingabefelder

Jeder Befehls-Hook erhält über stdin genau ein JSON-Objekt.

Diese gemeinsamen Felder brauchst du in der Regel:

Feld Typ Bedeutung
session_id string ID der aktuellen Codex-Sitzung. Hooks für Subagenten verwenden die ID der übergeordneten Sitzung.
transcript_path string | null Pfad zur Datei mit dem Sitzungsprotokoll, sofern vorhanden
cwd string Arbeitsverzeichnis der Sitzung
hook_event_name string Name des aktuellen Hook-Ereignisses
model string Codex-spezifische Erweiterung. Slug des aktiven Modells

Bei Hooks, die zu einer Chatrunde gehören, ist turn_id in der jeweiligen Ereignistabelle als Codex-spezifische Erweiterung aufgeführt.

SessionStart, PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, SubagentStart, SubagentStop, Stop und Interrupt enthalten außerdem permission_mode. Dieses Feld gibt den aktuellen Berechtigungsmodus an: default, acceptEdits, plan, dontAsk oder bypassPermissions.

Über transcript_path kannst du auf das Chatprotokoll zugreifen. Das Protokollformat ist jedoch keine stabile Schnittstelle für Hooks und kann sich ändern.

Das vollständige Übertragungsformat findest du unter Schemas.

Gemeinsame Ausgabefelder

SessionStart, PreCompact, PostCompact, UserPromptSubmit, SubagentStop und Stop unterstützen die folgenden gemeinsamen JSON-Felder. SubagentStart akzeptiert dasselbe Format für systemMessage und den Hook-spezifischen Kontext. Allerdings hält continue: false den Subagenten nicht an.

{
  "continue": true,
  "stopReason": "optional",
  "systemMessage": "optional",
  "suppressOutput": false
}
Feld Wirkung
continue Bei false kennzeichnet Codex diesen Hook-Lauf als gestoppt
stopReason Codex protokolliert den Wert als Grund für den Stopp
systemMessage Erscheint als Warnung in der Benutzeroberfläche oder im Ereignisstream
suppressOutput Codex liest das Feld ein. Die Funktion ist noch nicht implementiert

Exit-Code 0 ohne Ausgabe gilt als Erfolg. Codex fährt fort.

PreToolUse und PermissionRequest unterstützen systemMessage. Für diese Ereignisse sind continue, stopReason und suppressOutput derzeit nicht verfügbar. Gibt ein PreToolUse-Hook eines dieser nicht unterstützten Felder zurück, kennzeichnet Codex den Hook-Lauf als fehlgeschlagen, meldet den Fehler und setzt den Tool-Aufruf fort.

PostToolUse unterstützt systemMessage, continue: false und stopReason. Codex liest suppressOutput ein, unterstützt das Feld für dieses Ereignis aber noch nicht.

Umfangreiche Hook-Ausgaben

Standardmäßig begrenzt Codex jede Hook-Ausgabenachricht, die das Modell erhält, auf etwa 2.500 Token. Gibt ein Hook mehr zurück, speichert Codex den vollständigen Text unter <temp_dir>/hook_outputs/<session_id>/<uuid>.txt. Das Modell erhält eine Vorschau mit Anfang und Ende des Textes sowie dem Dateipfad. Dieses Verfahren heißt Auslagern: Codex speichert überlange Ausgaben auf dem Datenträger und gibt dem Modell eine kürzere Vorschau. Lässt sich die Datei nicht schreiben, erhält das Modell trotzdem eine gekürzte Vorschau.

Halte den Kontext aus Hooks und Plugins knapp. Der Kontext aus mehreren Quellen summiert sich und kann die Modellleistung beeinträchtigen. Ein höherer Wert für additionalContextLimit erhöht dieses Risiko. Setze das Limit nur auf 0, wenn der Hook selbst seine Ausgabe strikt begrenzt. Andernfalls kann ein einzelner Hook das gesamte Kontextfenster füllen.

Für jeden Befehls-Hook, der additionalContext zurückgibt, kannst du am Handler mit additionalContextLimit einen eigenen ungefähren Schwellenwert in Token festlegen:

{
  "type": "command",
  "command": "python3 ~/.codex/hooks/session_start.py",
  "additionalContextLimit": 5000
}

Ohne additionalContextLimit gilt der Standardschwellenwert von 2500 Token. Gib eine positive ganze Zahl für einen anderen Schwellenwert an oder 0, um den gesamten zusätzlichen Kontext des Handlers direkt an das Modell zu übergeben. Codex wertet jeden passenden Handler einzeln aus. Bei Ereignissen, die keinen zusätzlichen Kontext liefern können, ignoriert Codex additionalContextLimit und gibt eine Konfigurationswarnung aus.

Die Einstellung gilt nur für additionalContext. Für Tool-Rückmeldungen und Prompts zur Fortsetzung gilt weiterhin das Standardlimit.

Da Codex überlange Ausgaben auf dem Datenträger speichern kann, sollten Hook-Ausgaben keine Geheimnisse oder anderen sensiblen Daten enthalten.

Hooks im Hintergrund ausführen

Standardmäßig wartet Codex, bis ein Befehls-Hook beendet ist, bevor es den auslösenden Vorgang fortsetzt. Setze async auf true, damit der Befehls-Hook im Hintergrund läuft und Codex währenddessen fortfährt.

Einen Hintergrund-Hook konfigurieren

Füge "async": true zum Befehls-Handler in hooks.json hinzu:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/post_tool_use.py",
            "async": true,
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Für einen Inline-Hook in config.toml setzt du async = true:

[[hooks.PostToolUse]]
matcher = "Bash"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/post_tool_use.py"
async = true
timeout = 120

Für Hintergrund-Hooks gelten dieselben Regeln für Eingaben, Matcher, Vertrauensprüfung, Zeitlimits und den Umgang mit umfangreichen Ausgaben wie für synchrone Befehls-Hooks. Wie bei anderen Befehls-Hooks wird timeout in Sekunden angegeben. Der Standardwert ist 600. Für Interrupt-Hooks gilt standardmäßig eine Sekunde, maximal sind drei Sekunden zulässig. Das gilt auch im Hintergrund.

So laufen Hintergrund-Hooks ab

Sobald ein Hintergrund-Hook beendet ist, stellt Codex unterstützte informative Ausgaben zum nächsten sicheren Zeitpunkt in der Unterhaltung bereit:

  • Läuft gerade eine Chatrunde, wartet Codex, bis die aktuelle Modellanfrage und die Tool-Aufrufe abgeschlossen sind. Die Ausgabe steht dann bei der nächsten Modellanfrage derselben Runde zur Verfügung.
  • Läuft keine Chatrunde, wartet Codex bis zu deiner nächsten Eingabe. Der Abschluss eines Hintergrund-Hooks startet keine neue Runde.

Verwende dasselbe ereignisspezifische JSON-Ausgabeformat wie bei einem synchronen Hook. Codex ergänzt den Modellkontext um additionalContext und zeigt systemMessage als Warnung an.

Hintergrund-Hooks können den auslösenden Vorgang weder blockieren noch genehmigen, umschreiben oder anderweitig steuern. Verwende synchrone Hooks, um Tool-Richtlinien durchzusetzen, über Berechtigungen zu entscheiden, Prompts abzulehnen oder eine Chatrunde fortzusetzen.

Einschränkungen

  • Codex führt pro Sitzung bis zu acht Hintergrund-Hooks gleichzeitig aus. Weitere Hooks warten, bis ein laufender Hook beendet ist.
  • Jeder passende Aufruf läuft unabhängig. Hintergrund-Hooks können in einer anderen Reihenfolge enden, als sie gestartet wurden.
  • Am Sitzungsende bricht Codex noch laufende Hintergrund-Hooks ab und verwirft Ausgaben, die es noch nicht übermittelt hat.
  • SessionEnd-Hooks laufen immer synchron.

Hooks

SessionStart

Bei diesem Ereignis prüft matcher das Feld source.

Zusätzlich zu den gemeinsamen Eingabefeldern gibt es folgendes Feld:

Feld Typ Bedeutung
source string Art des Sitzungsstarts: startup, resume, clear, compact oder fork

Ein geforkter Thread verwendet source: "fork". Wenn du einen Thread mit einem mitgegebenen Verlauf fortsetzt, gilt weiterhin source: "resume".

Codex fügt Klartext auf stdout als zusätzlichen Entwicklerkontext hinzu.

Für JSON auf stdout kannst du die gemeinsamen Ausgabefelder und das folgende Hook-spezifische Format verwenden:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Load the workspace conventions before editing."
  }
}

Codex fügt den Text aus additionalContext als zusätzlichen Entwicklerkontext hinzu.

Nachdem Codex den Kontext der Hauptsitzung verdichtet hat, führt es vor der nächsten Modellanfrage die SessionStart-Hooks aus, die auf source: "compact" passen. Das gilt auch bei einer automatischen Kontextverdichtung mitten in einer Chatrunde. Codex stellt den zusätzlichen Hook-Kontext direkt für die Fortsetzung bereit, ohne auf eine spätere Eingabe zu warten. Gibt der Hook continue: false zurück, beendet Codex die Runde ohne weitere Modellanfrage.

SessionEnd

Mit SessionEnd kannst du am Sitzungsende einen Befehl ausführen, etwa um abschließende Notizen zu speichern oder Dateien aufzuräumen. Der Hook läuft für den Haupt-Thread, wenn du eine noch geöffnete Unterhaltung archivierst oder löschst, wenn Codex regulär beendet wird oder wenn eine Unterhaltung 30 Minuten lang inaktiv und in keinem verbundenen Client geöffnet war. Für Subagenten läuft er nicht.

Wenn du zu einer anderen Unterhaltung wechselst oder thread/unsubscribe aufrufst, endet die Sitzung nicht sofort. Deshalb wird SessionEnd auch nicht sofort ausgelöst. Während der Ausführung kann dein Hook das Sitzungsprotokoll weiterhin lesen.

matcher filtert bei diesem Ereignis nach reason. Derzeit hat reason immer den Wert other. Lass matcher weg oder verwende other, damit der Hook bei jedem SessionEnd-Ereignis läuft.

Zusätzlich zu den gemeinsamen Eingabefeldern gibt es folgendes Feld:

Feld Typ Bedeutung
reason string Grund für das Sitzungsende: other

Ein SessionEnd-Befehl erhält zum Beispiel:

{
  "session_id": "thr_123",
  "transcript_path": "/workspace/.codex/rollout.jsonl",
  "cwd": "/workspace",
  "hook_event_name": "SessionEnd",
  "reason": "other"
}

SessionEnd-Hooks laufen immer synchron, auch wenn async auf true steht. Ihre Ausgabe dient nur zur Information. Sie steuert Codex nicht und hält den Thread nicht offen. Überschreitet ein Befehl das Zeitlimit oder endet er mit einem Fehler, meldet Codex den Hook als fehlgeschlagen.

SubagentStart

Bei diesem Ereignis prüft matcher das Feld agent_type.

Zusätzlich zu den gemeinsamen Eingabefeldern gibt es folgende Felder:

Feld Typ Bedeutung
turn_id string Codex-spezifische Erweiterung. ID der aktuellen Chatrunde in Codex
agent_id string Kennung des Subagenten
agent_type string Typ oder Profil des Subagenten
permission_mode string Aktueller Berechtigungsmodus

Codex fügt Klartext auf stdout als zusätzlichen Entwicklerkontext für den Subagenten hinzu.

Für JSON auf stdout kannst du systemMessage und das folgende Hook-spezifische Format verwenden:

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Review the repository test conventions first."
  }
}

Codex fügt den Text aus additionalContext als zusätzlichen Entwicklerkontext für den Subagenten hinzu. Aus Kompatibilitätsgründen liest Codex continue: false ein. Der Subagent startet trotzdem.

PreToolUse

PreToolUse kann Bash-Aufrufe, Dateiänderungen mit apply_patch, MCP-Tool-Aufrufe und Aufrufe anderer lokaler Funktionstools abfangen. Welche Aufrufe unterstützt werden und welche Ausnahmen gelten, erfährst du unter Unterstützte Tools.

matcher prüft tool_name und die zugehörigen Aliasse. Bei Dateiänderungen mit apply_patch kannst du als matcher die Werte apply_patch, Edit oder Write verwenden. Die Hook-Eingabe enthält weiterhin tool_name: "apply_patch".

Zusätzlich zu den gemeinsamen Eingabefeldern gibt es folgende Felder:

Feld Typ Bedeutung
turn_id string Codex-spezifische Erweiterung. ID der aktuellen Chatrunde in Codex
tool_name string Kanonischer Tool-Name für den Hook, etwa Bash, apply_patch oder ein MCP-Name wie mcp__fs__read
tool_use_id string ID dieses Tool-Aufrufs
tool_input JSON value Tool-spezifische Eingabe. Bash und apply_patch verwenden tool_input.command. MCP-Tools und andere lokale Funktionstools senden ihre Argumente.

Codex ignoriert Klartext auf stdout.

JSON auf stdout kann systemMessage enthalten. Um einen unterstützten Tool-Aufruf abzulehnen, gib eine Antwort in diesem Hook-spezifischen Format zurück:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook."
  }
}

Codex akzeptiert auch dieses ältere Format zum Blockieren:

{
  "decision": "block",
  "reason": "Destructive command blocked by hook."
}

Du kannst auch den Exit-Code 2 verwenden und den Grund für die Blockierung auf stderr ausgeben.

Um dem Modell zusätzlichen Kontext zu geben, ohne den Aufruf zu blockieren, gib hookSpecificOutput.additionalContext zurück:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "additionalContext": "The pending command touches generated files."
  }
}

Um einen unterstützten Tool-Aufruf umzuschreiben, ohne ihn zu blockieren, gib permissionDecision: "allow" zusammen mit updatedInput zurück:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": {
      "command": "echo rewritten"
    }
  }
}

Bei Bash-Befehlen und apply_patch muss updatedInput das Feld command mit einer Zeichenfolge enthalten. Bei MCP-Tools und anderen lokalen Funktionstools ersetzt updatedInput das ursprüngliche Argumentobjekt. Gib updatedInput nur zusammen mit permissionDecision: "allow" zurück. Andere Formen von updatedInput meldet Codex als Fehler.

Codex liest permissionDecision: "ask", das ältere decision: "approve", continue: false, stopReason und suppressOutput ein, unterstützt sie aber noch nicht. Codex kennzeichnet den Hook-Lauf als fehlgeschlagen, meldet den Fehler und setzt den Tool-Aufruf fort.

PermissionRequest

PermissionRequest läuft, wenn Codex eine Genehmigung anfordern will, etwa für erweiterte Shell-Berechtigungen oder den Zugriff auf ein verwaltetes Netzwerk. Der Hook kann die Anfrage genehmigen, sie ablehnen oder die Entscheidung offenlassen. Im letzten Fall zeigt Codex die übliche Genehmigungsanfrage an. Für Befehle ohne Genehmigungspflicht wird der Hook nicht ausgeführt.

matcher prüft tool_name und die zugehörigen Aliasse. Zu den aktuellen kanonischen Werten gehören Bash, apply_patch und MCP-Tool-Namen wie mcp__server__tool. Für apply_patch passen auch Edit und Write.

Zusätzlich zu den gemeinsamen Eingabefeldern gibt es folgende Felder:

Feld Typ Bedeutung
turn_id string Codex-spezifische Erweiterung. ID der aktuellen Chatrunde in Codex
tool_name string Kanonischer Tool-Name für den Hook, etwa Bash, apply_patch oder ein MCP-Name wie mcp__fs__read
tool_input JSON value Tool-spezifische Eingabe. Bash und apply_patch verwenden tool_input.command. MCP-Tools senden alle Argumente.
tool_input.description string | null Lesbare Begründung für die Genehmigungsanfrage, sofern sie Codex vorliegt

Codex ignoriert Klartext auf stdout.

Manche Tool-Eingaben enthalten eine lesbare Beschreibung. Du kannst aber nicht bei jedem Tool mit dem Feld tool_input.description rechnen.

Um die Anfrage zu genehmigen, gib Folgendes zurück:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow"
    }
  }
}

Um die Anfrage abzulehnen, gib Folgendes zurück:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "deny",
      "message": "Blocked by repository policy."
    }
  }
}

Geben mehrere passende Hooks eine Entscheidung zurück, hat jedes deny Vorrang. Andernfalls genügt ein allow, damit die Anfrage ohne Genehmigungsdialog fortgesetzt wird. Trifft keiner der passenden Hooks eine Entscheidung, verwendet Codex das normale Genehmigungsverfahren.

Gib für die Felder updatedInput, updatedPermissions oder interrupt bei PermissionRequest keine Werte zurück. Diese Felder sind für künftige Funktionen reserviert. Derzeit führen sie dazu, dass die Anfrage aus Sicherheitsgründen nicht freigegeben wird.

PostToolUse

PostToolUse läuft, nachdem ein unterstütztes Tool eine Ausgabe erzeugt hat. Das gilt für Bash, apply_patch, MCP-Tool-Aufrufe und andere lokale Funktionstools. Bei Bash läuft der Hook auch nach Befehlen mit einem Exit-Code ungleich null. Die Auswirkungen eines bereits ausgeführten Tools kann er nicht rückgängig machen. Welche Aufrufe unterstützt werden und welche Ausnahmen gelten, erfährst du unter Unterstützte Tools.

matcher prüft tool_name und die zugehörigen Aliasse. Bei Dateiänderungen mit apply_patch kannst du als matcher die Werte apply_patch, Edit oder Write verwenden. Die Hook-Eingabe enthält weiterhin tool_name: "apply_patch".

Zusätzlich zu den gemeinsamen Eingabefeldern gibt es folgende Felder:

Feld Typ Bedeutung
turn_id string Codex-spezifische Erweiterung. ID der aktuellen Chatrunde in Codex
tool_name string Kanonischer Tool-Name für den Hook, etwa Bash, apply_patch oder ein MCP-Name wie mcp__fs__read
tool_use_id string ID dieses Tool-Aufrufs
tool_input JSON value Tool-spezifische Eingabe. Bash und apply_patch verwenden tool_input.command. MCP-Tools und andere lokale Funktionstools senden ihre Argumente.
tool_response JSON value Tool-spezifische Ausgabe. MCP-Tools senden das Ergebnis des MCP-Aufrufs. Andere lokale Funktionstools senden in der Regel die für das Modell bestimmte Ausgabe.

Codex ignoriert Klartext auf stdout.

JSON auf stdout kann systemMessage enthalten und das folgende Hook-spezifische Format verwenden:

{
  "decision": "block",
  "reason": "The Bash output needs review before continuing.",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "The command updated generated files."
  }
}

Codex fügt den Text aus additionalContext als zusätzlichen Entwicklerkontext hinzu.

Bei diesem Ereignis macht decision: "block" den abgeschlossenen Bash-Befehl nicht rückgängig. Codex protokolliert die Rückmeldung, ersetzt das Tool-Ergebnis durch diese Rückmeldung und lässt das Modell mit der Nachricht des Hooks weiterarbeiten.

Du kannst auch den Exit-Code 2 verwenden und die Begründung für die Rückmeldung auf stderr ausgeben.

Um die reguläre Verarbeitung des ursprünglichen Tool-Ergebnisses nach der Ausführung des Befehls anzuhalten, gib continue: false zurück. Codex ersetzt das Tool-Ergebnis durch deine Rückmeldung oder den Text zum Stopp und fährt damit fort.

Codex liest updatedMCPToolOutput und suppressOutput ein, unterstützt sie aber noch nicht. Codex kennzeichnet den Hook-Lauf als fehlgeschlagen, meldet den Fehler und verarbeitet das Tool-Ergebnis wie gewohnt weiter.

Tool-Aufrufe aus dem Codemodus

Wenn ein Modell im Codemodus ein Tool aus JavaScript aufruft, gelten die Hook-Entscheidungen für diesen verschachtelten Aufruf. PreToolUse kann die Ausführung des Tools verhindern oder dessen Eingabe umschreiben. Ein blockierender PostToolUse-Hook kann die Auswirkungen des Tools nicht rückgängig machen. Er kann aber verhindern, dass das laufende Skript das ursprüngliche Ergebnis erhält.

Hook-Ergebnis Verhalten im Codemodus
PreToolUse blockiert den Aufruf Das Promise des Tool-Aufrufs wird abgelehnt, bevor das Tool läuft.
PreToolUse gibt updatedInput zurück Das Tool läuft mit der geänderten Eingabe. Das Promise wird mit dem entsprechenden Ergebnis erfüllt.
PostToolUse gibt decision: "block" zurück oder endet mit Exit-Code 2 Das Tool läuft. Anschließend wird das Promise mit der vom Hook angegebenen Begründung abgelehnt.
PostToolUse gibt continue: false zurück Codex verwendet die Hook-Rückmeldung als Ergebnis für das Modell. Das Promise des verschachtelten Tool-Aufrufs wird dabei nicht abgelehnt.

PreModelRequest und PostModelRequest

Mit diesen Hooks protokollierst du Modellanfragen einschließlich aller Wiederholungsversuche innerhalb derselben Chatrunde. PreModelRequest läuft vor jedem Versuch. PostModelRequest meldet das Ergebnis des jeweiligen Versuchs. Beide Hooks erhalten das Modell und turn_id sowie, falls verfügbar, agent_id und agent_type. Die Hook-Ausgabe dient ausschließlich der Diagnose. Sie kann weder den Modellkontext ändern noch eine Anfrage blockieren.

PostModelRequest enthält drei zusätzliche Felder:

Feld Bedeutung
status completed, failed oder cancelled.
error Fehlermeldung, sofern verfügbar, andernfalls null.
token_usage Token-Anzahlen für diesen Versuch, sofern verfügbar, andernfalls null.

PreCompact

PreCompact läuft, bevor Codex den Chatkontext verdichtet. matcher prüft das Feld trigger, dessen mögliche Werte manual und auto sind.

Zusätzlich zu den gemeinsamen Eingabefeldern gibt es folgende Felder:

Feld Typ Bedeutung
turn_id string Codex-spezifische Erweiterung. ID der aktuellen Chatrunde in Codex
trigger string Auslöser der Kontextverdichtung: manual oder auto

Codex ignoriert Klartext auf stdout.

Für JSON auf stdout kannst du die gemeinsamen Ausgabefelder verwenden. Gibt ein passender PreCompact-Hook continue: false zurück, hält Codex vor der Kontextverdichtung an.

PostCompact

PostCompact läuft, nachdem Codex den Chatkontext verdichtet hat. matcher prüft das Feld trigger, dessen mögliche Werte manual und auto sind.

Zusätzlich zu den gemeinsamen Eingabefeldern gibt es folgende Felder:

Feld Typ Bedeutung
turn_id string Codex-spezifische Erweiterung. ID der aktuellen Chatrunde in Codex
trigger string Auslöser der Kontextverdichtung: manual oder auto

Codex ignoriert Klartext auf stdout.

Für JSON auf stdout kannst du die gemeinsamen Ausgabefelder verwenden. Gibt ein passender PostCompact-Hook continue: false zurück, hält Codex nach der Kontextverdichtung an.

UserPromptSubmit

matcher wird für dieses Ereignis derzeit nicht verwendet.

Zusätzlich zu den gemeinsamen Eingabefeldern gibt es folgende Felder:

Feld Typ Bedeutung
turn_id string Codex-spezifische Erweiterung. ID der aktuellen Chatrunde in Codex
prompt string Prompt, der gleich gesendet wird

Codex fügt Klartext auf stdout als zusätzlichen Entwicklerkontext hinzu.

Für JSON auf stdout kannst du die gemeinsamen Ausgabefelder und das folgende Hook-spezifische Format verwenden:

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Ask for a clearer reproduction before editing files."
  }
}

Codex fügt den Text aus additionalContext als zusätzlichen Entwicklerkontext hinzu.

Um den Prompt zu blockieren, gib Folgendes zurück:

{
  "decision": "block",
  "reason": "Ask for confirmation before doing that."
}

Du kannst auch den Exit-Code 2 verwenden und den Grund für die Blockierung auf stderr ausgeben.

SubagentStop

Bei diesem Ereignis prüft matcher das Feld agent_type.

Zusätzlich zu den gemeinsamen Eingabefeldern gibt es folgende Felder:

Feld Typ Bedeutung
turn_id string Codex-spezifische Erweiterung. ID der aktuellen Chatrunde in Codex
agent_id string Kennung des Subagenten
agent_type string Typ oder Profil des Subagenten
agent_transcript_path string | null Pfad zur Protokolldatei des Subagenten, sofern vorhanden
stop_hook_active boolean Gibt an, ob der Subagent seine Arbeit bereits fortgesetzt hat
last_assistant_message string | null Letzte Assistentennachricht des Subagenten, sofern vorhanden

SubagentStop erwartet JSON auf stdout, wenn der Hook mit dem Exit-Code 0 endet. Klartext ist für dieses Ereignis ungültig.

Für JSON auf stdout kannst du die gemeinsamen Ausgabefelder verwenden. Damit Codex den Subagenten weiterarbeiten lässt, gib Folgendes zurück:

{
  "decision": "block",
  "reason": "Run one more focused pass inside the subagent."
}

Du kannst auch den Exit-Code 2 verwenden und den Grund für die Fortsetzung auf stderr ausgeben.

Gibt ein passender SubagentStop-Hook continue: false zurück, hat das Vorrang vor den Entscheidungen anderer passender SubagentStop-Hooks, die eine Fortsetzung anfordern.

Stop

matcher wird für dieses Ereignis derzeit nicht verwendet.

Zusätzlich zu den gemeinsamen Eingabefeldern gibt es folgende Felder:

Feld Typ Bedeutung
turn_id string Codex-spezifische Erweiterung. ID der aktuellen Chatrunde in Codex
stop_hook_active boolean Gibt an, ob Stop diese Chatrunde bereits fortgesetzt hat
last_assistant_message string | null Text der letzten Assistentennachricht, sofern vorhanden

Stop erwartet JSON auf stdout, wenn der Hook mit dem Exit-Code 0 endet. Klartext ist für dieses Ereignis ungültig.

Für JSON auf stdout kannst du die gemeinsamen Ausgabefelder verwenden. Damit Codex weiterarbeitet, gib Folgendes zurück:

{
  "decision": "block",
  "reason": "Run one more pass over the failing tests."
}

Du kannst auch den Exit-Code 2 verwenden und den Grund für die Fortsetzung auf stderr ausgeben.

Bei diesem Ereignis führt decision: "block" nicht dazu, dass Codex die Chatrunde ablehnt. Codex arbeitet weiter und erzeugt automatisch einen Prompt zur Fortsetzung, den es wie einen neuen Prompt von dir behandelt. Als Prompt-Text verwendet es den Wert von reason.

Gibt ein passender Stop-Hook continue: false zurück, hat das Vorrang vor den Entscheidungen anderer passender Stop-Hooks, die eine Fortsetzung anfordern.

Interrupt

Interrupt läuft, wenn du eine aktive Chatrunde im Haupt-Thread unterbrichst. Damit kannst du die Unterbrechung protokollieren oder nach einem Hook aufräumen, der bereits Arbeit angestoßen hat. Für inaktive Threads und Subagenten läuft der Hook nicht. Einen konfigurierten matcher ignoriert Codex.

Zusätzlich zu den gemeinsamen Eingabefeldern enthält das Ereignis turn_id, die ID der unterbrochenen Chatrunde, und permission_mode.

Für Befehls-Hooks gilt bei diesem Ereignis standardmäßig ein Zeitlimit von einer Sekunde. Du kannst ein Zeitlimit von einer bis drei Sekunden konfigurieren. Die Hook-Ausgabe kann die Unterbrechung nicht verhindern und die Chatrunde nicht neu starten. Beende den Hook mit Exit-Code 0 ohne Ausgabe oder gib JSON mit einer optionalen systemMessage zurück, um eine Warnung anzuzeigen. Klartext ist für dieses Ereignis ungültig.

{ "systemMessage": "Saved the interrupted turn to the local audit log." }

Schemas

Die verlinkten Schemas aus dem Branch main können Hook-Felder enthalten, die in der aktuellen Version noch fehlen. Für das Verhalten der veröffentlichten Version ist die Beschreibung auf dieser Seite maßgeblich.

Das genaue aktuelle Übertragungsformat findest du in den generierten Schemas im GitHub-Repository von Codex.