agent-ops-patterns / gallery / OpenAI Codex map / how it decides
How OpenAI Codex decides
The main model picks each next step and plain code carries it out, and a turn can end when the model's reply holds no tool call and nothing else asks for a follow-up, unless a Stop hook you configured sends it on. When the conversation grows too long, local compaction replaces older history with a model's summary, and remote compaction uses an opaque item from the backend.
How it decides it is done
-
Is this turn finished?
Decided by an AI model The model decides by what it emits. If a step has no tool call, the server asks for no follow-up and no input is pending, the loop runs the Stop hooks, and the turn ends unless a hook continues it.
turn.rs:636· decision G1 in the full map -
Do the user's Stop hooks accept that the agent is done?
Decided by plain code Hook commands the user configured run with the last assistant message. If any asks to stop, the turn ends; otherwise a hook that blocks with a continuation prompt normally sends the turn on, with that prompt recorded.
hook_runtime.rs:449· decision G2 in the full map -
Has the thread's goal been achieved, or is it blocked?
Decided by an AI model The model decides by calling update_goal. Code accepts complete, blocked or paused, charges final usage and stops automatic continuation.
tool.rs:252-260· decision G5 in the full map
Limits and memory
-
After exec_command starts a process, how long does the tool wait before answering?
Decided by plain code The model's wait time, 10 seconds by default, is held between 250 ms and 30 s, with a 10 s floor on Windows. If the process is still running at the deadline, the tool returns the output so far and the process keeps running.
mod.rs:206-213· decision E2 in the full map -
How much of a command's captured output does the model read?
Decided by plain code The budget starts from the smaller of the model's max_output_tokens, 10,000 by default, and the model catalog's truncation policy. Text over it is cut from the middle under a warning header, then trimmed again to fit.
context.rs:527-534· decision E4 in the full map -
In a local compaction, what does the summary say?
Decided by an AI model A language model is sent the history plus a compaction prompt, and its last message becomes the summary in the replacement history.
compact.rs:125-135· decision F3 in the full map -
What does a remote compaction keep?
Decided by plain code The backend returns one opaque compaction item. Client code then picks which visible items stay beside it, within a budget of 64,000 tokens.
compact_remote_v2.rs:464· decision F6 in the full map -
Should the running turn stop now?
Decided by a person The person at the terminal interface, or an app-server client, sends an interrupt, and the session aborts the active task and its tools.
handlers.rs:514· decision F14 in the full map
Other judgments
-
What does the agent do next: which tool to call, or what to say?
Decided by an AI model The main model answers it in a streamed response at each step; code handles what comes back.
turn.rs:2833· decision C1 in the full map -
In multi-agent V1, should part of this work go to a sub-agent?
Decided by an AI model The model decides by calling spawn_agent; code checks the arguments and starts a child thread.
spawn.rs:65· decision H1 in the full map
Three problems in the code
-
1. A long AGENTS.md near the root can crowd out the ones nearer your work
Codex shares one budget, 32 KiB by default, across a project's AGENTS.md files, reading from the project root down to your working directory. So a long file near the root can use it up. When the budget is used up, later files, nearer your work, are not read; a file larger than what remains is cut. A pull request merged on 2026-11-04, after the commit this card read, adds warnings for files cut or skipped this way; the cut is still there.
Already tracked upstream (#37956), checked 2026-11-15.
Where:
agents_md.rs:145-180,agents_md.rs:68. How we checked: the code was re-read at the source version named above; the sentences were checked by an independent AI reviewer from another company (OpenAI Codex, read-only) on 2026-11-08, in three rounds; each sentence it questioned was narrowed, removed or kept with the reason recorded. -
2. An interrupted command's output can be missing from the model's result
If you interrupt and a running exec_command call is aborted, its result for the model holds the elapsed time and 'aborted by user', with no command output. An open report in Codex's tracker describes output visible on screen but missing from the tool result returned to the model.
Already tracked upstream (#35735), checked 2026-11-15.
Where:
parallel.rs:481-501,parallel.rs:378-385. How we checked: the code was re-read at the source version named above; the sentences were checked by an independent AI reviewer from another company (OpenAI Codex, read-only) on 2026-11-08, in three rounds; each sentence it questioned was narrowed, removed or kept with the reason recorded. -
3. A /review reply that cannot be parsed comes back with no structured findings
Code tries to parse the review model's reply as JSON, whole and then from its first { to its last }. If both fail, the whole reply becomes the overall explanation, with zero findings and an empty correctness verdict. Codex tests this fallback on purpose. An open issue reports a /review that returned "continue?" instead of a review; a comment there names this fallback as a plausible cause, not a confirmed one.
Already tracked upstream (#24109), checked 2026-11-15.
Where:
review.rs:193-208. How we checked: the code was re-read at the source version named above; the sentences were checked by an independent AI reviewer from another company (OpenAI Codex, read-only) on 2026-11-08, in three rounds; each sentence it questioned was narrowed, removed or kept with the reason recorded.