Inside Codex's Multi-Agent Architecture: Independent Sessions, Context Handoff, and Async Coordination

01 | Why Split Tasks When One Agent Can Work?

When a single agent fixes an issue, it reads code, checks config, investigates test failures, verifies fixes, and checks for regressions — all in one session. Two problems arise:

Time : Some work is independent. During a review, one sub-agent can investigate test failures while another checks broken doc links — they can run in parallel.

Context : Code, config, test logs, and failed attempts accumulate in one session. The model faces growing context each turn. A dedicated test-investigation agent keeps its context focused on the test problem.

Finer splitting is not always better. The main agent must brief context, sub-agents must read materials and call models, and results must be integrated. Overhead may exceed actual work. Dependencies exist: modifying code before diagnosing test failure causes rework. Better: dispatch read-only investigation first, then modify, then verify. The main agent can handle independent work while waiting. Parallel and sequential steps coexist; splitting must consider information dependencies, not just agent count.

02 | Multi-Agent Collaboration Patterns: Which Does Codex Choose?

Fixed Workflow

Pre-define steps: requirements agent → coding agent → testing agent. Program routes outputs. Easy to debug and validate handoffs. But when tests fail, you need branches or developer intervention. Suits stable processes; more task variation means more branches to anticipate.

Orchestrator-Workers (Main Agent Scheduling)

Keep a main agent that decides needed help, dispatches sub-tasks, and aggregates results. The main agent reads the project, decides division, adds investigation if needed, runs independent tasks in parallel. User gives requirements to main agent; it coordinates helpers and returns final result. But the main agent's scheduling quality matters: wrong splits cause duplicate work; unclear briefs yield unmergeable results. It must also judge which conclusions are trustworthy.

Handoff (Relay)

Current agent transfers control to another. E.g., support agent detects refund need, hands off to refund agent, which continues and replies directly. The new agent focuses on its domain, but multiple handoffs require clean background and pending-item transfer. If results from several agents must be synthesized, an integrator is still needed.

These patterns can combine. "One writes, one reviews" describes division; both fixed workflow and dynamic scheduling can adopt it.

Codex's Choice

Codex implements dynamic orchestration by a main agent, where sub-agents can further spawn helpers. The root agent receives user requests and owns overall delivery. Main creates A → main is A's parent; A creates C → A is C's parent. C returns results to A, which decides usage.

Each sub-agent has its own task and context. Parent-child indicates creator and default result recipient. Agents can message peers directly (A tells B a discovery) without routing through parent.

Why this fits coding: programming tasks often need project exploration before knowing where help is needed. You might start checking one file, discover another module, or realize a test is needed after a fix. The main agent adjusts division dynamically, no need to pre-define all steps.

03 | What Exactly Does the Main Agent Dispatch?

Suppose the main agent wants a helper to investigate code. It asks Codex to create a sub-agent (call it A). Is this just a single model call returning analysis?

If so, when A wants to search directories, read files, then pursue leads based on findings — who executes those steps?

Codex creates an independent, runnable session.

A has its own conversation history and runtime state. Think of a session as a persistent work log: accepted requirements, read materials, formed conclusions — all recorded here.

Upon receiving the investigation task, A requests the model to decide where to look, calls tools to read code, feeds results back to the model for next steps. This "model decides → tool executes → continue based on result" loop is the agent loop.

From start to result return is one work round, possibly containing multiple model requests and tool calls. Later asking A to review an implementation starts a new round in the same session.

Does Codex need a new execution engine per sub-agent? No. It reuses the existing session engine, adding a shared management layer to organize these independent sessions.

The model decides next steps from visible info; Codex program executes tools, saves history, routes messages. This management layer is also implemented in Codex.

It handles session creation, parent-child recording, message routing, and execution resource coordination. If main creates B, main, A, B each have their own history; the management layer tracks which sessions belong to the team.

Each agent has a name/ID in the team. Sending a message, the management layer finds the target session by name and delivers.

If A needs further splitting, it can create its own sub-agents, forming multi-level hierarchies.

Note: "independent" primarily means session independence. A's tool results (file reads) don't automatically become B's history; main's new requirements don't auto-appear in all sub-agents via shared context. Main and sub-agents must sync via task briefs and message passing.

This lets each agent focus, but raises a direct problem: the sub-agent missed the earlier requirements discussion — how does it know what the user already decided?

04 | Sub-Agent Missed the Discussion: How Does It Catch the Task?

Example: user previously said "add a button to the page, reuse existing project styles, don't install new libraries." Main agent knows this. But if the sub-agent only receives "complete the button part," it might produce a working button using a new component library or custom styles — functional but violating user constraints.

This is the first multi-agent difficulty: when tasks split, background info splits too.

Too little info → sub-agent misses constraints or re-investigates what main already clarified. Too much → irrelevant discussions and execution noise get stuffed in.

Codex lets the dispatching agent choose how much history to inherit when creating a sub-agent.

Decide How Much Background to Hand Off

No inheritance : sub-agent starts fresh history. Still gets required instructions and environment, but prior user discussions must be re-briefed in the task dispatch.

Inherit all available parent history : Codex builds the sub-session from this history. Suits tasks tightly dependent on prior context. Default if no range specified.

Inherit only recent N rounds : e.g., earlier discussions covered unrelated features; only the last two rounds finalized this change's requirements. Inherit those two rounds. Counting by work rounds, not message count. A round = user request → agent searches/reads → conclusion. Inheriting two rounds brings those two work segments' context, not just the last two messages.

The dispatching agent judges how much prior context this task needs; Codex prepares the background per the chosen scope.

But choosing "inherit all available history" — does that copy the main agent's raw runtime state verbatim? Not quite; the parent task's execution process must be cleaned first.

Inherit Background, But Clean Parent's Execution Process

For regular history records, Codex keeps user messages, necessary instructions, and assistant final answers. It filters out parent's reasoning traces, non-final assistant messages, and regular tool calls with their results.

Example: main agent previously searched the whole project, generating many tool records, finally telling user: "project already has a button component, can reuse directly." For these regular records, the sub-agent inherits the requirement and the formed answer; the parent's search call process is filtered out.

Handoff goal: let the sub-agent understand task background, then act around its own task.

Won't facts from main's file reads and test runs be lost? No. Filtering tool calls doesn't erase all investigation conclusions. Conclusions written into final answers remain as regular history and can be passed to the sub-agent.

Another case: parent session was already compressed. As covered previously, when history grows too long, Codex compresses to key facts. E.g., ten file reads condensed to: "project has reusable button component." The compressed history for continued work is saved in a restore point. Creating a sub-agent may inherit this history. Restore points have their own cleaning rules — besides summaries, they may retain some tool records — so the regular-history filtering rules don't apply directly.

Distinguish raw tool process from saved background facts. Filtering regular tool calls doesn't mean all old investigation facts disappear.

Thus, even with "inherit all available history," the sub-agent receives cleaned handoff material, not raw execution logs.

Background Handed Off, Identity Must Be Rebriefed Too

An easily overlooked item: main agent originally owned overall delivery; the sub-agent might only check one file. If main's team-identity instructions are copied verbatim, the sub-agent may mistakenly think it must also arrange implementation, acceptance, and final reply.

So Codex cleans old team-identity and collaboration-mode instructions from inherited history, then tells the sub-agent: who you are, who your parent is, how to contact teammates, and that final answers go back to parent.

Old team messages already exchanged in the parent session are not copied into the new sub-agent's message log. Otherwise the sub-agent might treat old requests sent to main as new tasks for itself.

Now the sub-agent carries necessary background, knows its responsibility and contacts, and doesn't inherit the parent's identity.

With History, Do We Still Need a Proper Task Brief?

Absolutely. History explains what the project is doing, but not what this sub-agent should achieve this round.

E.g., you want the sub-agent to review code. "Check it" is too vague. Better: "Check files modified in this change, focus on omissions and errors; read-only, no file edits; return issue locations, causes, and needed additional verification."

This brief covers three key points: what to check, what actions are allowed, what to return.

Background fills the backstory; the task brief defines goal, scope, and deliverables. Inherited history reduces repeated explanation but cannot replace clear division of labor.

Note: "read-only" here is a task agreement. If write restriction must be enforced, execution permissions must guarantee it — don't treat a prompt as a sandbox.

05 | Everyone's Busy: How Do New Info and Results Get Back?

Simple example: a sub-agent reading code discovers a reusable utility function, while the main agent is preparing to reimplement the same functionality.

Can this discovery wait until the investigation ends? Better to tell main now — main is designing the implementation; later receipt means larger rework scope.

But main might be mid-model-call or waiting for a tool to finish reading config. Can the sub-agent inject this message directly into main's current model request? No. The model request is already sent with fixed input. New messages can't retroactively alter already-generated decisions.

Codex's approach: store the message first; when the receiver prepares its next model input, attach the new messages.

Where Do Messages Go First?

Each agent session has its own input queue. Messages from other agents are stored here until the receiver continues work, then fed to the model. Call this the "pending message queue."

Sent content includes sender, recipient, and payload. After a message enters main's pending queue, the sub-agent continues investigating without waiting for main's immediate reply.

E.g., main is waiting for a file read result; new message arrives → stored. When main next requests the model, Codex adds pending messages to the input. The model sees the utility function info and can decide on reuse.

So "send success" only means Codex received and delivered the message — not that main has read it and adjusted plans.

Like messaging a colleague: sent ≠ read ≠ acted upon. Agents need the same state distinctions.

Supplemental Info vs. Dispatching New Task: Same Thing?

Adding "also check the legacy config file" to an actively investigating sub-agent — a regular message suffices.

But if the sub-agent has already returned results and is idle, and main says "now review this modification" — different situation.

Former: supplementing an in-progress task. Latter: asking an idle agent to start a new work round.

Codex splits these into "send message" and "dispatch follow-up task." Send message only delivers info. Dispatch follow-up delivers info and explicitly requires the sub-agent to begin a work round.

Regular messages usually won't trigger an immediate model call from an already-idle agent. They sit in the pending queue until the receiver continues work. A follow-up task can start an idle sub-agent; if the target is still busy, the new request waits until it can accept new input.

This avoids auto-triggering execution on every supplemental note. When work should continue, explicitly dispatch a task.

Investigation Done: Must Results Be Sent Explicitly?

Handled automatically by Codex.

Sub-agent finishes investigation, writes findings and conclusions in its final answer. Codex packages this round's completion as a message and delivers it to the parent that created this sub-agent.

E.g., sub-agent read a dozen files, final answer: "issue is in config read order." Parent receives this final answer. Next time parent tasks the same sub-agent, the new round's completion uses the same return mechanism.

Auto-returned is the sub-agent's final output; the investigation process stays in the sub-agent's own session.

Parent doesn't need to stuff all dozen file-read processes into its own history; it mainly receives outputs useful for subsequent judgment. Whether conclusions are accurate and evidence sufficient — the model must judge; Codex doesn't auto-validate for the parent.

Late Results: Will They Drag an Already-Finished Task Back?

Overlooked scenario: main already has necessary investigation and verification results. One sub-agent is still checking a supplementary question. Main judges the supplement won't affect current delivery, gives final user reply, then the sub-agent's message arrives later.

If every sub-agent message forced main to run another reasoning round, delivered tasks could extend repeatedly. Especially when several sub-agents complete sequentially — user just saw an answer, system spins up again.

Codex distinguishes "still working" from "wrapping up this round." If main has entered the final-reply winding-down phase and has no other work pending, late regular collaboration messages just stay in the pending queue. Messages aren't lost, but they don't auto-trigger a new main round just because they arrived.

If user adds a new request, main starts a new round and gets a chance to process previously queued messages. If current round isn't over, user appends a request, or model still needs to call tools, Codex processes messages along the continuing-work flow.

Codex saves received messages but won't auto-restart a wrapping-up main agent just because a regular collaboration message arrived.

06 | Waiting for Results: How to Avoid Constant Polling Yet Adjust Tasks?

Messages can be queued, but how does main know new messages need handling?

Assume main waits for two sub-agents A and B. Naive approach: poll every few seconds. But each poll adds tool calls and may trigger repeated reasoning with no new info.

Codex provides a wait tool. Main continues independent work; when it reaches a point dependent on investigation results, it enters wait.

After main calls the wait tool, Codex listens for new collaboration messages or user input. Collaboration message arrives → wait ends. New user input → interrupts wait. Timeout → returns timeout.

Main doesn't poll the model every few seconds asking "check again." The wait tool blocks until new activity or timeout.

Wait Ends → Both Investigations Done?

No.

This wait is not "wait for A and B to both complete then return"; it's wait until main has a message or new input to process .

E.g., A sends "found a lead, still verifying" → wait ends, even though A's investigation isn't done. B returns final result → wait ends. User adds "don't modify files yet" → also interrupts wait.

The wait tool mainly reports why the wait ended; it doesn't directly return A and B's full reports. Reports and other messages become new model inputs via Codex. Main reads them, then knows who sent what and whether it can proceed.

Also, wait timeout only stops main's waiting; sub-agents continue working and are not auto-cancelled.

So upon waking, main must judge if task dependencies are satisfied. If only A's intermediate finding, main can adjust design first, then wait for B; if both results are in, proceed to implementation.

Task Direction Changed: Need Fresh Batch of Agents?

No.

If A's investigation direction is no longer needed, main can ask Codex to interrupt A's current work. Interruption ends this execution round; A's session and history remain; file edits already written are not auto-rolled-back.

E.g., a sub-agent already read a module and completed structural investigation. After main modifies that module, it can re-ask the same sub-agent to review. Existing investigation records stay in the session — no need to spawn a new agent to re-read everything.

This forms a reusable work unit: accept task → execute → return result → idle → accept next task. vs. creating new sessions each time, reuse preserves investigation background, but new task goals and scope must still be briefed clearly.

Won't agents pile up and hog resources? Two resource types to manage.

Concurrent executing agents : before starting new work, Codex checks execution capacity; at limit, new launch requests may be rejected — can't infinitely increase concurrent tasks.

Sessions resident in memory : A may be idle but its session still occupies space — session residency. When space is low, Codex can save eligible idle sub-sessions and unload them from memory. Later, A can be restored with its identity, session, and history.

But sessions that are executing or have unprocessed messages cannot be unloaded just to free space. If no eligible idle sessions exist, space cannot be forcibly made.

One round's completion doesn't mean the agent's work log is deleted; saving the log doesn't mean the session must stay in memory. Separating these enables both background reuse and resource control.

07 | More Agents: How to Avoid Making More Mess?

Multiple agents can work independently and message each other. Does letting A and B both edit code guarantee faster completion?

One practical problem remains: files.

Sub-agents have independent session contexts, but the default collaboration environment shares the working directory and filesystem.

E.g., A edits page title, B edits same page's footer. If both read the old version first, then each overwrites the whole file with their changes, B's later write may overwrite A's new title. Independent model histories don't prevent file-level conflicts.

One approach: sub-agents do read-only investigation; main unifies modifications. When parallel edits are needed, clearly assign who owns which file ranges, and which files only one agent may integrate.

Can Codex auto-arrange all responsibilities to guarantee no duplicate work? Codex provides create-sub-agent, dispatch-task, and send-message capabilities, but "how to split tasks," "who owns what," and "which conclusion to trust when two conflict" still require the model to judge based on goals, instructions, and new information.

E.g., a sub-agent reports "tests passed." Main must still check which tests ran and whether they cover modified behaviors. Only validating happy paths while missing empty or error inputs leaves gaps.

When two review conclusions conflict, you must go back to the code and verification evidence to judge which is more reliable. Message delivery doesn't replace this judgment step.

Message return solves how information is delivered; correctness of conclusions still requires combining current code and verification results.

Multi-agent gains come from: can tasks advance independently? Is handoff info useful? Is final integration thorough? If the task is tiny or steps are tightly dependent, a single session may be simpler. What's worth learning is this collaboration mechanism and how to clarify each agent's responsibilities.

Final Thoughts

Multi-agent collaboration coordinates multiple independently running sessions.

Each session has its own history and execution state, yet must exchange information with others. Just providing a create-sub-agent entry isn't enough for sustained teamwork.

If you build your own multi-agent system, here are four designs worth borrowing from Codex:

Sub-agents must sustain investigation, not just answer once. Codex reuses the same agent engine, preserving independent context and runtime state for each participant.

Tasks are delegated, but background must not break. Handoff must prepare necessary background and concrete task, while cleaning parent's old identity and execution info to prevent sub-agent role confusion.

Agents progress at different paces; messages can't demand instant processing. Use pending message queues to buffer info; end wait on new messages; distinguish supplemental info, new task dispatch, and result return.

Tasks end, but collaboration may continue. Separate work-round completion from session retention so agents can accept further tasks and release memory when idle.

Codex's program ensures these handoff and coordination actions run reliably. Whether division is sensible and sub-agent conclusions are correct still relies on the model judging against task requirements, current evidence, and verification.

When studying this design, ask your own agent: after splitting, will background be lost? When messages arrive, can they be caught? After a task ends, can collaboration continue? These are the engineering supports multi-agent needs beyond model reasoning.

Code example

来源丨
经授权
转自
小林coding（ID：CodingLin）
作者
丨
小林coding