Codex hooks: hooks.json, PreToolUse allow/deny, exit code 2 and config.toml [hooks]

• ~/.codex/hooks.json or inline [hooks] tables in ~/.codex/config.toml (user).
• <repo>/.codex/hooks.json or <repo>/.codex/config.toml (project). Project hooks load only when that .codex/ layer is trusted.
• Enabled plugins, through hooks/hooks.json or a hooks entry in .codex-plugin/plugin.json.
• Managed hooks for an organization, through [hooks] in requirements.toml.
• Higher-precedence layers do not replace hooks from lower ones; they add to them. Hooks that are not managed must be reviewed and trusted before they run.
• Hooks are enabled by default. Turn them off with hooks = false under [features] in config.toml (codex_hooks is a deprecated alias).

• SessionStart: a session or subagent starts. The matcher filters on the source: startup, resume, clear, compact or fork.
• UserPromptSubmit: before your prompt is sent.
• PreToolUse: before a tool call, covering Bash, apply_patch, MCP tools and other local function tools.
• PermissionRequest: when Codex is about to ask you for approval.
• PostToolUse: after a supported tool produces output.
• PreCompact and PostCompact: before and after the conversation is compacted (matcher: manual or auto).
• SubagentStop, Stop, Interrupt (an active main-thread turn is interrupted) and SessionEnd (the main thread ends).

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .codex/hooks/check_bash.py",
            "timeout": 30,
            "statusMessage": "Checking command"
          }
        ]
      }
    ]
  }
}

The hook gets JSON on stdin with session_id, cwd, hook_event_name, model and, for tool events, tool_name and tool_input. To block, exit 2 and write the reason to stderr, or exit 0 and print a decision:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "git push is not allowed from Codex"
  }
}

• matcher is a regex. "*", an empty string or no matcher matches everything. It is ignored for UserPromptSubmit, Stop and Interrupt.
• For PreToolUse, PostToolUse and PermissionRequest the matcher is the tool name. For apply_patch you can also match Edit or Write.
• Handler types: command and mcp_tool (server, tool, input). prompt and agent handlers are parsed but skipped.
• commandWindows (command_windows in TOML) overrides the command on Windows. async: true runs the command in the background.
• timeout is in seconds and defaults to 600. SessionEnd and Interrupt default to 1 second and allow at most 3.
• additionalContextLimit caps the context a hook can add (default 2500 tokens; 0 passes the full context).

• Exit 0 with no output: success, Codex continues.
• Exit 2: blocks on events that support it, such as PreToolUse, UserPromptSubmit, Stop and SubagentStop, with the reason taken from stderr. On PostToolUse it sends feedback.
• PreToolUse: permissionDecision is allow or deny. ask is not supported yet. updatedInput rewrites the tool input and works only with allow.
• PermissionRequest: hookSpecificOutput.decision with behavior allow or deny (and a message). Deny wins over allow.
• UserPromptSubmit, PostToolUse, SubagentStop and Stop: top-level decision "block" with a reason. On Stop, block does not reject the turn.
• On every event: continue, stopReason and systemMessage. additionalContext in hookSpecificOutput is added as developer context.

• Compare: hooks in every AI coding agent
• Claude Code hooks: events, exit codes and JSON
• Codex config.toml
• Codex approval and sandbox modes