Claude Code and Codex Orchestration: Handoff Contracts for AI Coding Teams

Claude Code and Codex orchestration breaks down when the plan lives in one session, the implementation happens somewhere else, and the proof never makes it across the boundary. That is the ordinary failure pattern now. Claude Code, Codex, Cursor, ChatGPT, and human reviewers can produce plans, diffs, and summaries faster than a team can preserve scope and evidence.

The fix is not picking a smarter coding agent. It is assigning each agent a jurisdiction, putting the handoff in durable project state, and verifying evidence before work moves to the next boundary.

Quick answer: use Claude Code for exploration, planning, review, and cross-file judgment. Use Codex for bounded implementation, local terminal work, background cloud tasks, and review loops when the task is self-contained. Keep the source of truth outside both agents in an MCP-connected project board. Every handoff should pass objective, scope, constraints, artifacts, tests, open questions, next action, owner, and verification status. Then a gate should check that evidence before the plan changes.

That answer is grounded in a broader pattern. MAST, a multi-agent system failure taxonomy, analyzed 1,642 annotated traces across seven frameworks and identified 14 failure modes grouped into system design issues, inter-agent misalignment, and task verification [1] [2]. The exact percentage claim in the older version of this article is gone because the verified source base supports the taxonomy, trace count, and categories, not that number.

This article turns that research into an operating model for AI coding teams: role boundaries, handoff contracts, durable state, and verification gates. If the bottleneck in your workflow is repeated context loading, pair this with optimising agentic workflow cost and speed. If the bottleneck is task decomposition, read work unit coordination patterns next.

The Coordination Problem In Multi-Agent Coding

The dominant failure in multi-agent coding is rarely one bad answer. It is the slow loss of authority across boundaries.

One agent writes the plan. Another agent edits the code. A third reviewer checks the output against a summary, not the original objective. Each step looks reasonable in isolation. The combined system drifts because no one preserved the contract between the steps.

MAST gives useful language for this. Its failure taxonomy does not reduce multi-agent failure to hallucination. It separates failures across system design, inter-agent misalignment, and task verification [1] [2]. Coding teams see those categories in three ordinary ways:

• Drift: output diverges from the original task after several agent passes.
• Context loss: a decision, constraint, or rationale from the planning session does not survive the handoff.
• Conflicting edits: parallel agents modify the same shared file or module without an ownership rule.

Practitioner language makes the pain easier to recognize: context loss, reread tax, handoff files, decision capture, shared state stores, fresh sessions, scope boundaries, and clean state before handoff. Treat those phrases as voice-of-customer language, not benchmark evidence. They still matter because they name the operational problem better than a generic "agent failed" label.

The important shift is this: coordination is a state problem. It is not enough for Claude Code to understand the repository or for Codex to execute a narrow change. The team needs a durable place where objective, scope, evidence, and next action can survive across sessions and tools.

How Should Teams Split Work Between Claude Code And Codex?

The old framing was "Claude Desktop plans, Codex CLI executes." That is too narrow now.

Claude Code is positioned by Anthropic as an agentic coding system that can read codebases, edit files, run tests, support parallel sessions, and keep humans in control of committed code [3]. Codex is a family of OpenAI coding surfaces, including CLI, IDE extension, desktop app, and Codex web/cloud [5] [6]. GitHub and VS Code also document third-party coding agents, including Claude and Codex, across local and cloud workflows [18] [19].

That does not make the tools interchangeable. It makes role boundaries more important.

The practical split is simple:

1. Claude Code owns ambiguity: exploration, decomposition, trade-off analysis, review, and plan revision.
2. Codex owns bounded work: implementation, terminal commands, background task execution, and evidence collection against explicit criteria.
3. Agiflow owns continuity: task state, work-unit scope, artifacts, comments, status, secrets boundaries, and workflow locks.

The first two decide how work gets done. The third decides whether the next agent can trust what happened.

Role Separation Patterns That Do Not Blur Authority

Role separation is not a naming exercise. It decides who is allowed to change the plan, who is allowed to change code, and who is allowed to accept evidence.

OpenAI's orchestration guidance distinguishes two patterns that matter here: handoffs and agents-as-tools. In a handoff, control transfers to a specialist. In an agents-as-tools pattern, the manager keeps control while calling a specialist for a bounded job [7] [8]. LangChain describes similar multi-agent patterns and notes that handoff implementations must preserve valid message state [9] [10]. Claude Agent SDK subagents add another useful constraint: separate agent instances can have focused subtasks, isolated context, specialized instructions, parallel work, and restricted tool access [4].

Those distinctions map cleanly into three coding patterns.

Pattern 1: Planner-Executor

Claude Code as planner: decomposes the task, writes the acceptance criteria, identifies files or modules in scope, and decides when the plan changes.

Codex as executor: implements only the scoped task, runs the specified checks, and returns evidence.

Boundary rule: the executor cannot expand scope or revise the plan. The planner cannot accept completion without artifact references and verification status.

This pattern works when the next step is clear enough to execute but risky enough to need an explicit contract. For deeper task decomposition, work units are the better unit than a long chat prompt.

Pattern 2: Critic-Actor

Codex as actor: produces a change against fixed acceptance criteria.

Claude Code as critic: reviews the diff, logs, and test output against the same criteria.

Boundary rule: the critic reviews evidence, not confidence. "Tests pass" is not evidence until the command, output, and relevant files are named.

This is the pattern to use when the implementation is cheap but a missed constraint would be expensive: auth behavior, data migrations, billing logic, secrets handling, generated code, or cross-package API changes.

Pattern 3: Specialist-Coordinator

Multiple specialists: each agent owns one isolated domain, such as API handler, UI copy, test fixture, or migration script.

Coordinator: Claude Code or a human reviewer integrates outputs, resolves cross-cutting conflicts, and updates the plan.

Boundary rule: shared files are coordinator-owned by default. If two specialists need the same file, the work is not parallel yet.

Specialist-coordinator is tempting because it looks fast. It only stays fast when ownership is explicit before execution begins. Otherwise, the team saves time during implementation and loses it during integration.

What Should A Multi-Agent Handoff Contract Include?

A handoff contract is not a transcript. It is not a chain-of-thought dump. It is not a polite summary of what the previous agent thinks happened.

It is a structured transfer of verifiable state.

The receiving agent should be able to answer five questions without guessing:

1. What objective am I continuing?
2. What scope am I allowed to touch?
3. What constraints must survive this handoff?
4. What evidence proves the previous step happened?
5. What is the next action, and who owns it?

OpenAI's handoff model and orchestration docs are useful here because they treat delegation as a control and responsibility boundary, not just a chat message [7] [8]. Google ADK's context engineering guidance points in the same direction: production systems need sessions, memory, artifacts, transformations, and scoped context, not larger context windows alone [11].

Summary-Based Handoff

"I updated the authentication flow. The tests pass. Next, work on the data layer."

That handoff creates work for the receiver. Which files changed? Which tests? What was deferred? What acceptance criteria were used? What is the exact next scope?

Evidence-Based Handoff

{
  "objective": "Implement OAuth session refresh behavior",
  "scope": ["src/auth/session.ts", "src/auth/session.test.ts"],
  "constraints": ["Do not change token storage format", "Preserve 24 hour session expiry"],
  "artifacts": [
    {
      "type": "diff",
      "ref": "artifact:auth-session-refresh.diff"
    },
    {
      "type": "test-output",
      "ref": "artifact:auth-session-test-output.txt"
    }
  ],
  "tests": ["pnpm nx test-unit auth-package -- session"],
  "decisions": ["Refresh token rotation deferred pending product decision"],
  "open_questions": ["Should mobile sessions share the same expiry policy?"],
  "next_action": "Review diff and resolve mobile expiry question",
  "owner": "claude-code-reviewer",
  "verification_status": "tests-run, review-pending"
}

Mapping The Contract To Agiflow State

The difference between a handoff file and a durable project board is queryability. A markdown file can work for one session. A board-backed MCP state layer lets multiple assistants read and update the same work record through scoped tools.

Agiflow's first-party project management domain covers projects, work units, tasks, comments, artifacts, vault secrets, real-time status updates, and distributed workflow locks [22]. Its artifact flow stores artifacts against projects, tasks, and work units, and exposes them through REST and MCP [24]. Its workflow lock flow scopes locks to project, work-unit, and task compositions so parallel work can return acquired or locked status [23].

Where Shared Agent State Should Live

Shared state should not live inside Claude Code, Codex, Cursor, ChatGPT, or a long chat transcript.

Those are working surfaces. The state boundary belongs outside them.

Google's ADK team frames context as a production engineering concern: sessions, memory, artifacts, explicit transformations, and scoped context are all part of how an agent receives the right view of the work [11]. Anthropic has also warned that MCP tool definitions and intermediate results can overload context and increase cost or latency when tool use scales [17]. More context is not the same as better context.

MCP is the useful connection layer here. The Model Context Protocol defines a way for LLM applications to integrate with external data sources and tools. Its specification describes hosts, clients, servers, and JSON-RPC communication [12]. The introduction describes MCP as a way to connect AI applications such as Claude and ChatGPT to data sources, tools, and workflows [13]. Anthropic's MCP connector lets Claude connect to remote MCP servers, and ChatGPT developer mode supports MCP read and write tools with explicit warnings about prompt injection, destructive write actions, and malicious MCPs [15] [16].

That last point matters. A project board should not become a giant prompt. It should give each assistant the smallest useful slice of state:

• the task it owns,
• the work unit it belongs to,
• the artifacts it must inspect,
• the comments that carry decisions,
• the vault boundary for secrets,
• the workflow lock that prevents collisions.

MCP tools can expose external capabilities to models, but the tools specification also recommends human-in-the-loop UI and confirmation for trust and safety [14]. In coding workflows, that means write tools should be scoped, confirmable, and auditable. Reading a task is different from changing a status. Uploading an artifact is different from acquiring a lock. Touching secrets needs an even narrower boundary.

That is why MCP project management tools and shared state for AI coding teams are not side quests. They are the operating layer that lets agents change while the work state remains stable.

See the Agiflow MCP project board pattern for keeping agent work state outside the chat: start with task and work-unit state, then add artifacts, comments, locks, and scoped MCP tools as the workflow matures.

Verification Gates Between Agents

Verification belongs between agents, not after the whole chain finishes.

If a Codex task drifts, and Claude Code revises the plan based on a summary of that drift, the system has already compounded the error. The gate has to catch it before the next boundary.

The gate model is simple:

Gate 1: Task Entry

No task enters an agent queue until the scope is bounded. For a coding task, that usually means named files, named modules, or a named work unit. If the task says "fix auth" without acceptance criteria, it is not ready for Codex.

Gate 2: Output

No output leaves an agent as "done" until references resolve. The diff exists. The test output exists. The screenshot exists. The command output exists. If an artifact reference cannot be opened, the handoff fails.

Gate 3: Integration

No parallel output merges without conflict detection. When two agents touched the same file, the coordinator owns the integration. Workflow locks make this explicit by giving a project, work-unit, or task composition an acquired or locked state [23].

Gate 4: Plan Revision

No plan changes without evidence. If a subtask reveals a new constraint, the revised plan should point to the artifact, comment, or decision that justifies the change.

For teams enforcing architecture rules as code, connect this gate model to MCP-backed architecture enforcement. Deterministic checks are not a replacement for review, but they catch drift before the reviewer starts reading prose.

Failure Mode Defenses

Even a disciplined system still fails. The goal is to make failures detectable early and cheap to correct.

Drift

What it looks like: the implementation is plausible but no longer matches the original objective. A subtask adds adjacent behavior, drops a constraint, or changes files outside the authorized scope.

Detection: compare the output against the task contract at Gate 2. Teams can define a drift policy using file count, function count, acceptance-criteria mismatch, or unauthorized module changes. Do not treat a sample threshold as a benchmark.

Mitigation: the canonical plan lives in durable state. Executors receive scoped task specs derived from that plan. Only the planner or coordinator can revise the plan, and revisions need artifact evidence.

Hallucinated Artifacts

What it looks like: a handoff references a file, test run, commit, screenshot, or log that does not exist.

Detection: resolve every artifact reference before accepting the handoff. If the reference cannot be opened, the output is not evidence.

Mitigation: artifacts are attached to task, work-unit, or project state instead of pasted into a summary. In Agiflow, artifacts are part of the project management domain and artifact flow, not decorative storage [22] [24].

Conflicting Edits

What it looks like: two agents each make a locally sensible change to the same shared module, configuration file, schema, or generated artifact.

Detection: compare modified file lists before integration. Treat shared files as coordinator-owned unless a lock says otherwise.

Mitigation: acquire a workflow lock for the project, work unit, or task composition before the work starts. If the lock is unavailable, the agent should wait, split the task differently, or hand it back to the coordinator [23].

FAQ

What should Claude Code own versus Codex?

Claude Code should own ambiguous, cross-file, and review-heavy work: exploration, planning, decomposition, critique, integration judgment, and plan revision. Codex should own bounded implementation and execution work when the objective, scope, constraints, and acceptance criteria are explicit. Codex web/cloud is a good fit for background tasks and PR-oriented work when the repository connection and task contract are clear [3] [5] [6].

What fields belong in a multi-agent handoff contract?

At minimum: objective, scope, constraints, artifacts, tests, decisions, open questions, next action, owner, and verification status. The contract should transfer responsibility with evidence. It should not transfer a transcript.

How does MCP help Claude Code, Codex, Cursor, and ChatGPT share project state?

MCP gives assistant clients a common way to reach external tools, data, and workflows through servers and tools [12] [13]. In a coding workflow, that means project state can live in a board or work system instead of each agent's chat history. Agiflow uses that pattern as a project board and MCP tool surface for external assistants [20] [21].

What verification gates catch drift and hallucinated artifacts?

The output gate catches drift by checking the agent's output against scope and acceptance criteria. The same gate catches hallucinated artifacts by resolving every referenced file, diff, log, screenshot, or test result before the next agent receives the work.

When is a single agent better than multi-agent orchestration?

Use a single agent when the task is small, the scope is local, the decision rights are obvious, and parallelism would create more coordination cost than speed. Multi-agent orchestration earns its keep when work can be split into bounded units with clear ownership, artifacts, and verification gates.

Building Multi-Agent Coding Systems That Stay Coherent

Claude Code and Codex orchestration is not a model contest. It is a coordination architecture.

Claude Code can reason across the repo. Codex can execute bounded work in local and cloud surfaces. MCP can connect assistants to project state. Agiflow can hold the durable board, artifacts, comments, statuses, vault boundaries, and workflow locks that let external assistants work from the same facts.

The stack is straightforward:

• role boundaries decide who owns planning, implementation, review, and integration,
• handoff contracts decide what state moves between agents,
• durable project state decides where the truth lives,
• verification gates decide when work is allowed to cross a boundary.

That is how teams keep AI coding work coherent when agents, sessions, and surfaces change. See the Agiflow MCP project board pattern for keeping agent work state outside the chat, then connect it to shared state, MCP project management, architecture gates, and workflow locks across machines.

References

[1] Why Do Multi-Agent LLM Systems Fail? MAST Taxonomy, arXiv (2025)

[2] MAST: Multi-Agent System Failure Taxonomy, Berkeley Sky Lab (2025)

[3] Claude Code, Anthropic (2026)

[4] Subagents, Claude Agent SDK docs (2026)

[5] Codex cloud, OpenAI Developers (2026)

[6] OpenAI Codex GitHub repository (2026)

[7] Orchestration and handoffs, OpenAI API docs (2026)

[8] Handoffs, OpenAI Agents SDK (2026)

[9] Multi-agent overview, LangChain docs (2026)

[10] Handoffs, LangChain docs (2026)

[11] Architecting efficient context-aware multi-agent framework for production, Google Developers Blog (2025)

[12] Model Context Protocol specification 2025-06-18

[13] MCP introduction, Model Context Protocol docs (2026)

[14] MCP tools specification 2025-06-18

[15] Developer mode and MCP tools, OpenAI API docs (2026)

[16] MCP connector, Anthropic docs (2026)

[17] Code execution with MCP, Anthropic Engineering (2026)

[18] About third-party coding agents, GitHub Docs (2026)

[19] Third-party agents, Visual Studio Code docs (2026)

[20] Agiflow product registry, docs/products.yaml (first-party source, verified 2026-07-05)

[21] Agiflow MCP integration domain, docs/architecture/agiflow/domains/mcp-integration.domain.yaml (first-party source, verified 2026-07-05)

[22] Agiflow project management domain, docs/architecture/agiflow/domains/project-management.domain.yaml (first-party source, verified 2026-07-05)

[23] Agiflow workflow lock flow, docs/architecture/agiflow/dataflows/project-management/workflow-lock-flow.flow.yaml (first-party source, verified 2026-07-05)

[24] Agiflow artifact flow, docs/architecture/agiflow/dataflows/project-management/project-artifact-management-flow.flow.yaml (first-party source, verified 2026-07-05)

[25] Agiflow MCP-only ADR, docs/architecture/agiflow/adrs/034-remove-agent-execution-implementation-code-from-codebase.adr.yaml (first-party source, verified 2026-07-05)