>>> codex cli hooks, explained Codex Hooks. Past The Review Screen

// Setup //

Hooks That Track What Codex Is Doing

These are the Codex events that matter for knowing what it's doing. Each hook gets JSON on stdin and runs in the pane's environment, so $TMUX_PANE says which tmux pane Codex lives in. Honest limit: there's no event for Codex's approval prompts, so a hook can see working, done and idle, but not "waiting for you". (RETRO TMUX catches that one anyway. More below.)

1. 01

   A script that writes the state

   Save as ~/bin/codex-state.sh. It sets a tmux pane option, @codex_state, that your status bar can show.

   #!/bin/sh
   # codex-state.sh <Event>: what is Codex doing in this tmux pane?
   [ -n "$TMUX_PANE" ] || exit 0
   cat >/dev/null      # the payload; this script only needs the event name
   case $1 in
     SessionStart) state=idle ;;
     UserPromptSubmit|PreToolUse) state=working ;;
     Stop) state=done ;;
     *) exit 0 ;;
   esac
   tmux set -p -t "$TMUX_PANE" @codex_state "$state"
   exit 0

   you@server: ~

   $ codex

   › add a test for the reconnect path

   [agents] 1:codex*codex: working

2. 02

   Declare the hooks

   Write ~/.codex/hooks.json. Keep each hook to type, command and timeout, with no matcher; you'll see why in a second.

   {
     "hooks": {
       "SessionStart":     [{ "hooks": [{ "type": "command", "command": "sh ~/bin/codex-state.sh SessionStart", "timeout": 5 }] }],
       "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "sh ~/bin/codex-state.sh UserPromptSubmit", "timeout": 5 }] }],
       "PreToolUse":       [{ "hooks": [{ "type": "command", "command": "sh ~/bin/codex-state.sh PreToolUse", "timeout": 5 }] }],
       "Stop":             [{ "hooks": [{ "type": "command", "command": "sh ~/bin/codex-state.sh Stop", "timeout": 5 }] }]
     }
   }

3. 03

   Start Codex. Meet the review screen

   Codex opens with Hooks need review. That's not a bug; it's Codex refusing to run code it hasn't been told to trust. Approve them there, or read on and do it once, properly.

// Hooks need review //

How Codex Decides To Trust A Hook

Codex runs a user hook only if ~/.codex/config.toml holds a trust entry whose hash matches that hook exactly as it is now. We read Codex's source to get the recipe right, and checked it against a live Codex (0.156). Here it is:

#!/usr/bin/env python3
# codex-trust.py: print the [hooks.state] entries Codex wants for your hooks.json
import hashlib, json, os, re
path = os.path.expanduser("~/.codex/hooks.json")
hooks = json.load(open(path)).get("hooks", {})
snake = lambda e: re.sub(r"(?<!^)([A-Z])", r"_\1", e).lower()   # PreToolUse -> pre_tool_use
for event, groups in hooks.items():
    for g, group in enumerate(groups):
        for h, hook in enumerate(group.get("hooks", [])):
            handler = {"type": "command", "command": hook["command"],
                       "timeout": int(hook.get("timeout", 600)), "async": False}
            identity = {"event_name": snake(event), "hooks": [handler]}
            blob = json.dumps(identity, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
            print(f'[hooks.state."{path}:{snake(event)}:{g}:{h}"]')
            print(f'trusted_hash = "sha256:{hashlib.sha256(blob.encode()).hexdigest()}"\n')

Trusting a hook means letting it run code every time Codex does. Only write entries for hooks you've read.