Codex — Hooks
- File format
- JSON
- Discovery path
-
.codex/hooks.json - Global install path
-
~/.codex - Syllago install method
- Symlink
- Symlink support
- No
- Config file
-
.codex/hooks.json - Handler types
-
command
Hook events
Codex supports hooks, but syllago does not yet map its hook event names. Hook conversion to and from Codex is best-effort.
Features
How each feature converts to syllago's canonical format. See format conversion for what these statuses mean.
Fields
Native frontmatter or config fields this provider exposes. The first column is the provider's own field name; the canonical key column links to syllago's cross-provider equivalent.
| Provider field | Conversion | Canonical key | Summary |
|---|---|---|---|
async | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | — | Hook handlers run sync (blocking) or async (fire-and-forget) via the async flag on command handlers / HookExecutionMode. |
hookSpecificOutput.permissionDecision | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | — | PreToolUse output permissionDecision (allow/deny/ask) gives fine-grained tool permission control separate from the top-level decision. |
hookSpecificOutput.updatedInput | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | — | PreToolUse output updatedInput field replaces the tool's arguments before execution, allowing hooks to modify or sanitize input. |
matcher | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | — | Optional matcher string on PreToolUse/PostToolUse entries filters which tool calls trigger the hook (absent = all tools). |
systemMessage | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | — | Hook output systemMessage field injects extra context into the current turn's system message; available on all five event schemas. |
type | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | — | Each hook entry has a type: command (shell), prompt (LLM prompt), or agent (sub-agent delegation). |
suppressOutput | Dropped Conversion type: Dropped Can’t be meaningfully preserved. Removed from the output with a portability warning. Learn more → | — | Hook output suppressOutput boolean (default false) hides stdout/stderr from the user; available on all five event schemas. |
turn_id | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | — | PreToolUse/PostToolUse input payload includes a turn_id field (marked Codex extension) so hooks can correlate with model turns. |
Other features
Behaviors, conventions, and capabilities that aren't tied to a single named field — things like path-based activation, discovery rules, and lifecycle behavior.
| Feature | Conversion | Summary |
|---|---|---|
async_execution | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | hook_execution_mode: Codex supports async hook execution mode for fire-and-forget background hook runs |
context_injection | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | hook_system_message: Codex hooks can inject a system message into the agent's active session context |
decision_control | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | hook_result_abort: Codex hooks can abort (block) the triggering action; allow and modify sub-capabilities documented via hook result schema |
handler_types | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | hook_handler_types: Codex supports shell command and LLM prompt handler types; TypeScript extension type also documented |
| Hook Events | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | Five hook events: PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, Stop (PascalCase in config.toml, camelCase in TS protocol). |
| Hook Result Abort vs Continue | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | Tri-state hook outcome: Success, FailedContinue, FailedAbort; output JSON also supports continue and decision (approve/block) fields. |
hook_scopes | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | hook_scope: Codex hooks can be scoped to global/user or project configuration |
input_modification | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | hook_updated_input: Codex PreToolUse hooks return modified input arguments that replace the original tool input |
matcher_patterns | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | hook_matcher: Codex hooks support pattern matching to filter which tools or events trigger the hook |
permission_control | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | hook_permission_decision: Codex hooks can return permission decisions that grant or deny tool availability |
| Hook Scope (thread / turn) | Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | Hooks scoped to a thread (whole session) or a turn (one request/response cycle) via the HookScope value. |