A Working Model of Codex's Control Plane

For openai/codex, the useful question is not merely what the model can say or which tools exist. It is which component owns each transition from a request to a possible action. This chapter connects the turn loop, bounded context, thread state, and tool surface into one working model. The result is a practical test: you should be able to trace what the model sees, what Codex records, what the runtime dispatches, and why a proposed tool action is still only a proposal until it crosses a separate authority boundary.

The model is easiest to understand through a small repair task. A user asks Codex to investigate a failing test and make the necessary change. The client submits the request to a thread. The runtime captures a turn-specific view of history, settings, environment, and tools. The model proposes a command or patch. Codex records that proposal, routes it to a tool runtime, and waits for a result that can be fed back into the next model step. The sequence is familiar from the preceding discussion, but its meaning becomes clearer when each state has an owner.

classDiagram class Thread { durable history thread settings } class Turn { active execution } class StepContext { frozen prompt and tool state } class ToolRuntime { dispatches calls } class Client { receives events answers requests } Thread *-- Turn : contains Turn *-- StepContext : uses StepContext --> ToolRuntime : advertises calls to ToolRuntime --> Turn : returns results to Client --> Thread : submits input Thread --> Client : emits events

This is not a class inventory of the repository. It is an ownership map. A thread retains durable identity and settings. A turn owns active execution. A step context freezes the prompt and tool view used for one sampling request. The tool runtime dispatches a call and returns a result. The client observes events and answers requests, but it does not become the owner of the agent's internal state.

The same request crosses several boundaries

The first connection is temporal. A user request is accepted by the thread, but it does not immediately become a model call. Codex first constructs a step context, then derives the prompt from the context. That prompt may include selected conversation items, base instructions, model-visible tool specifications, output constraints, and environment-related information. The model is therefore acting on a prepared view, not on an unexamined stream of everything stored in the thread.

The second connection is between that view and the tool router. The router is part of the step context because the model's available actions must match the runtime's dispatch plan. If the repair task exposes shell execution, the model can request that capability. If a capability is deferred, nested, or hidden, it is not simply interchangeable with a directly advertised tool. The distinction is not about naming.