Put Your Personal Logic Contained in the Codex Agentic Loop

Your Mannequin’s MSE Is Mendacity to You III: Time Collection Diffusion

Everybody Is Promoting AI at You — Right here’s Easy methods to Hold Your Judgement

by means of prompts.

We are able to describe the duty, give directions, and inform Codex what sort of consequence we anticipate. This permits us to regulate how the agent approaches its work.

However generally, prompting shouldn’t be sufficient.

We might wish to additional customise the execution by operating our personal logic at totally different phases of a Codex session.

So, how can we try 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 research to show the idea.

1. Understanding Codex hooks

When Codex works on a activity, it goes by means of an agentic loop.

For a brand new session, the person varieties in a immediate, Codex analyzes the issue, calls instruments, and completes the duty. You’ll be able to consider this entire 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 permits 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 consequence.

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 some extent 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 truly care about. For instance, we may run the script solely when Codex is about to execute a shell command.

Due to this fact, 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 research: Including a top quality gate to deep analysis

On this case research, we construct a small deep analysis workflow with Codex.

Particularly, we’ll ask Codex to analysis latest traits in a given subject. Codex will conduct internet searches and establish three necessary traits from the previous 90 days. On the finish, it ought to return a structured analysis temporary.

To showcase the hook idea, we’ll add a top quality verify simply earlier than Codex finishes. It’ll confirm that the temporary incorporates sufficient sources and that these sources come from an inexpensive number of domains.

If the temporary passes, Codex can end. If it fails, the hook will ship the issues again to Codex, and Codex will proceed researching throughout the identical 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 printed from **{{WINDOW_START}}** by means of **{{WINDOW_END}}**,
inclusive. Establish the three most necessary traits in that interval and put together
a concise, source-backed temporary.

Return a concise, source-backed analysis temporary that follows the equipped schema.

To make sure structured output, we additionally put together a JSON schema:

{
  "kind": "object",
  "additionalProperties": false,
  "required": ["summary", "trends"],
  "properties": {
    "abstract": {
      "kind": "string"
    },
    "traits": {
      "kind": "array",
      "objects": {
        "kind": "object",
        "additionalProperties": false,
        "required": ["title", "summary", "sources"],
        "properties": {
          "title": {
            "kind": "string"
          },
          "abstract": {
            "kind": "string"
          },
          "sources": {
            "kind": "array",
            "objects": {
              "kind": "string"
            }
          }
        }
      }
    }
  }
}

We save this as schemas/research_brief.schema.json. Be aware that that is additionally the construction our hook expects.

2.2 Designing the High quality Gate

Subsequent, we outline what the hook ought to verify.

Right here, we verify three issues:

Every pattern ought to comprise not less than two sources.
The temporary ought to comprise not less than ten distinctive sources in whole.
These sources should come from not less than 5 distinctive domains.

We are able to solely apply the checks after Codex has completed getting ready it. Meaning 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)
temporary = json.hundreds(occasion["last_assistant_message"])

errors = []
all_urls = set()

for quantity, pattern in enumerate(temporary["trends"], 1):
    urls = set(pattern["sources"])
    all_urls.replace(urls)

    if len(urls) < MIN_PER_TREND:
        errors.append(f"Development {quantity} wants not less than {MIN_PER_TREND} sources.")

domains = {
    urlparse(url).netloc
    for url in all_urls
}

if len(all_urls) < MIN_SOURCES:
    errors.append(f"Add not less than {MIN_SOURCES} distinctive sources.")

if len(domains) < MIN_DOMAINS:
    errors.append(f"Use not less than {MIN_DOMAINS} supply domains.")

if errors:
    message = "Analysis temporary verify failed:n- " + "n- ".be part of(errors)
    consequence = {"choice": "block", "cause": message}
else:
    consequence = {}

print(json.dumps(consequence))

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 traits 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 verify fails, the script would return a block choice along with the errors:

{
  "choice": "block",
  "cause": "Analysis temporary verify failed:n- Add not less than 10 distinctive sources."
}

Be aware 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 temporary throughout the identical run.

Now we have to outline the hook to inform Codex when and learn how to 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 present doesn’t apply matchers to the Cease occasion. So we didn’t outline any within the configuration above.

2.3 Working a Concrete Analysis Process

As a check, I requested Codex to analysis latest traits in data-center infrastructure:

{
  "subject": "latest traits 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 mission listing and use /hooks to evaluate 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 price 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 supplies 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 check, I see that Codex first produced three traits supported by seven distinctive sources. Every pattern had greater than two sources, however the temporary didn’t meet our total requirement of ten.

Our Cease hook labored, as Codex obtained this suggestions:

The temporary wants broader corroboration. I’m including not less than three
impartial, in-window sources whereas preserving the identical three
evidence-supported traits.

After one other spherical, Codex lastly produced an up to date temporary with 12 distinctive sources from 10 domains.

The ultimate temporary recognized three main traits: 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 result is saved to outputs/research_brief.json.

3. When Hooks Are Helpful

In our case research, we confirmed learn how to use a Cease hook to validate a accomplished consequence. 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: