by way of prompts.
We will describe the duty, give directions, and inform Codex what sort of outcome we count on. This enables us to regulate how the agent approaches its work.
However generally, prompting just isn’t sufficient.
We could wish to additional customise the execution by operating our personal logic at totally different phases of a Codex session.
So, how can we do this?
The reply is Codex hooks.
On this publish, we’ll discover the idea of hooks and perceive the place they match into the agentic loop. Then, we’ll undergo a concrete case examine to show the idea.
1. Understanding Codex hooks
When Codex works on a activity, it goes by way of an agentic loop.
For a brand new session, the person sorts in a immediate, Codex analyzes the issue, calls instruments, and completes the duty. You may consider this complete problem-solving trajectory as a lifecycle, and at totally different factors on this lifecycle, Codex emits occasions with totally different occasion names:
SessionStart: emitted when a session begins;
PreToolUse: emitted when Codex is about to name a device;
PostToolUse: emitted after the device finishes;
Cease: emitted when Codex is able to end its response;
SessionEnd: emitted when the Codex session ends.
A Hook is the mechanism that enables us to connect our personal logic to those occasions.
For instance, we may use SessionStart hook to load further context, or PreToolUse hook to examine a command earlier than it runs, or Cease hook to validate a outcome.
So, what does it imply to connect logic to an occasion?
Suppose we configure a hook for PreToolUse. Each time Codex is about to name a device, the hook runs a script. Codex passes details about that device name to the script as a part of the context.
Selecting PreToolUse solely identifies a degree within the lifecycle. Many various device calls can happen at that time. Because of this, we’d additionally want an identical rule to allow us to choose those we really care about. For instance, we may run the script solely when Codex is about to execute a shell command.
Subsequently, there are three fundamental decisions when configuring a hook:
At which level within the lifecycle ought to it run?
Below what situations ought to it run at that time?
What motion ought to it execute?
In Codex, these correspond to the occasion, matcher, and handler. And that is the essential sample behind Codex hooks.
2. Case examine: Including a high quality gate to deep analysis
On this case examine, we construct a small deep analysis workflow with Codex.
Particularly, we’ll ask Codex to analysis latest tendencies in a given subject. Codex will conduct internet searches and determine three essential tendencies from the previous 90 days. On the finish, it ought to return a structured analysis transient.
To showcase the hook idea, we’ll add a high quality examine simply earlier than Codex finishes. It’ll confirm that the transient accommodates sufficient sources and that these sources come from an affordable number of domains.
If the transient passes, Codex can end. If it fails, the hook will ship the issues again to Codex, and Codex will proceed researching inside the similar run till it satisfies our checks.
2.1 Making ready the Analysis Process
We’ll begin by getting ready a immediate template:
# Deep analysis activity
Analysis **{{TOPIC}}**.
Use sources revealed from **{{WINDOW_START}}** by way of **{{WINDOW_END}}**,
inclusive. Establish the three most essential tendencies in that interval and put together
a concise, source-backed transient.
Return a concise, source-backed analysis transient that follows the provided schema.
To make sure structured output, we additionally put together a JSON schema:
{
“kind”: “object”,
“additionalProperties”: false,
“required”: [“summary”, “trends”],
“properties”: {
“abstract”: {
“kind”: “string”
},
“tendencies”: {
“kind”: “array”,
“gadgets”: {
“kind”: “object”,
“additionalProperties”: false,
“required”: [“title”, “summary”, “sources”],
“properties”: {
“title”: {
“kind”: “string”
},
“abstract”: {
“kind”: “string”
},
“sources”: {
“kind”: “array”,
“gadgets”: {
“kind”: “string”
}
}
}
}
}
}
}
We save this as schemas/research_brief.schema.json. Word that that is additionally the construction our hook expects.
2.2 Designing the High quality Gate
Subsequent, we outline what the hook ought to examine.
Right here, we examine three issues:
Every development ought to include at the very least two sources.
The transient ought to include at the very least ten distinctive sources in whole.
These sources should come from at the very least 5 distinctive domains.
We will solely apply the checks after Codex has completed getting ready it. Which means a Cease hook is appropriate right here.
We first create the validation script in .codex/hooks/validate_research.py:
import json
import sys
from urllib.parse import urlparse
MIN_PER_TREND = 2
MIN_SOURCES = 10
MIN_DOMAINS = 5
occasion = json.load(sys.stdin)
transient = json.hundreds(occasion[“last_assistant_message”])
errors = []
all_urls = set()
for quantity, development in enumerate(transient[“trends”], 1):
urls = set(development[“sources”])
all_urls.replace(urls)
if len(urls) < MIN_PER_TREND:
errors.append(f”Pattern {quantity} wants at the very least {MIN_PER_TREND} sources.”)
domains = {
urlparse(url).netloc
for url in all_urls
}
if len(all_urls) < MIN_SOURCES:
errors.append(f”Add at the very least {MIN_SOURCES} distinctive sources.”)
if len(domains) < MIN_DOMAINS:
errors.append(f”Use at the very least {MIN_DOMAINS} supply domains.”)
if errors:
message = “Analysis transient examine failed:n- ” + “n- “.be a part of(errors)
outcome = {“resolution”: “block”, “motive”: message}
else:
outcome = {}
print(json.dumps(outcome))
When the Cease occasion is emitted, Codex passes in last_assistant_message, which follows the schema we outlined earlier. Our script can then parse this response right into a Python dictionary and iterate over the tendencies and gather their sources in a set.
Subsequent, we use urlparse to extract the area from every distinctive URL. After that, we are able to apply our checks.
If any examine fails, the script would return a block resolution along with the errors:
{
“resolution”: “block”,
“motive”: “Analysis transient examine failed:n- Add at the very least 10 distinctive sources.”
}
Word that for the Cease occasion, block doesn’t terminate the run; it simply prevents Codex from ending. Codex can use the suggestions to enhance the transient inside the similar run.
Now we have to outline the hook to inform Codex when and execute it. We do that in .codex/hooks.json:
{
“hooks”: {
“Cease”: [
{
“hooks”: [
{
“type”: “command”,
“command”: “python3 .codex/hooks/validate_research.py”,
“commandWindows”: “python .codexhooksvalidate_research.py”
}
]
}
]
}
}
Codex at the moment doesn’t apply matchers to the Cease occasion. So we didn’t outline any within the configuration above.
2.3 Operating a Concrete Analysis Process
As a take a look at, I requested Codex to analysis latest tendencies in data-center infrastructure:
{
“subject”: “latest tendencies in data-center infrastructure”,
“as_of”: “2026-08-01”,
“lookback_days”: 90
}
After inserting these values into our immediate template, we save the rendered immediate to outputs/research_prompt.md.
Earlier than the primary run, you’ll be able to open Codex within the undertaking listing and use /hooks to assessment the hook.
On this case, we’ll run the duty in headless mode with exec:
codex –search exec
–model gpt-5.6-sol
–json
–output-schema schemas/research_brief.schema.json
-o outputs/research_brief.json
–
< outputs/research_prompt.md
> outputs/run.jsonl
A few issues value mentioning:
exec: runs Codex non-interactively.
–search: provides the agent entry to internet search.
–model: selects the mannequin used for the run.
–output-schema: that is the place we provide our pre-defined schema to constrain the agent output.
-o: this implies we save the agent’s response to the goal location.
–json: this makes Codex emit its execution occasions as JSONL. We redirect this occasion stream to outputs/run.jsonl, which provides us a hint of the run.
-: tells Codex to learn the immediate from customary enter.
<: This operator provides outputs/research_prompt.md as that enter.
Throughout my take a look at, I see that Codex first produced three tendencies supported by seven distinctive sources. Every development had greater than two sources, however the transient didn’t meet our total requirement of ten.
Our Cease hook labored, as Codex acquired this suggestions:
The transient wants broader corroboration. I’m including at the very least three
impartial, in-window sources whereas preserving the identical three
evidence-supported tendencies.
After one other spherical, Codex lastly produced an up to date transient with 12 distinctive sources from 10 domains.
The ultimate transient recognized three main tendencies: the rise of gigawatt-scale AI campuses, energy entry and allowing as infrastructure constraints, and the shift towards liquid cooling.
The hook ran once more, however this time it allowed Codex to complete. The end result is saved to outputs/research_brief.json.
3. When Hooks Are Helpful
In our case examine, we confirmed use a Cease hook to validate a accomplished outcome. The identical design course of additionally applies to different lifecycle occasions.
For SessionStart hook, it’s helpful when we have to load context when a session begins. If we have to examine an operation earlier than it occurs, we are able to use PreToolUse hook. If we wish to course of the results of a device name, we are able to use PostToolUse hook.
When designing a hook, ask your self three questions:
At which level within the lifecycle ought to it run?
Below what situations ought to it run at that time?
What motion ought to it execute?
That is how one can add deterministic logic across the Codex execution.
