A walkthrough of Codex hooks, a mechanism for attaching custom logic to lifecycle events like SessionStart, PreToolUse, PostToolUse, Stop, and SessionEnd during an agentic session. Hooks are configured with an event, a matcher, and a handler. A case study demonstrates using a Stop hook to enforce a quality gate on a deep-research task built with Codex, validating that a generated research brief contains enough sources and domain variety before the agent is allowed to finish, using a Python validation script and a hooks.json configuration.
Table of contents
1. Understanding Codex hooks2. Case study: Adding a quality gate to deep research3. When Hooks Are UsefulQuestions this post answers
How do I add a quality check that runs before Codex finishes a task?
Use a Stop hook, which runs after Codex prepares its final response but before it finishes. The hook receives the last_assistant_message as input, can run a validation script, and return a decision of block with a reason if checks fail, which sends feedback back to Codex to continue working within the same run rather than terminating it. Developers wiring quality gates into agent workflows can track Codex hook patterns like this on daily.dev.
What are the different hook events available in Codex and when do they fire?
Codex emits five lifecycle events: SessionStart (session begins), PreToolUse (before a tool call), PostToolUse (after a tool finishes), Stop (when Codex is ready to finish its response), and SessionEnd (session ends). Each hook is configured with three components: the event, a matcher specifying conditions, and a handler defining the action to run. daily.dev helps developers building Codex agent workflows keep up with hook and lifecycle event patterns.
Does Codex support matchers for the Stop event when configuring hooks?
No, Codex currently does not apply matchers to the Stop event, so a Stop hook configuration in hooks.json omits the matcher field entirely and simply defines the command to run whenever the Stop event fires. Teams customizing Codex hook configs can compare implementation quirks like this on daily.dev.