When smart is not enough — Multi-agent AI orchestration defaults

Imagine a relay race where all four runners are Olympic-level athletes. Fast, technically perfect, experienced. Now imagine nobody told them the running order. The handoff protocol. Who holds the baton first.

What happens? Someone starts. Maybe the right person, maybe not. The baton gets passed in the wrong direction. Two runners reach the same point at the same time. The team is brilliant. The race is chaos.

This is the exact problem with multi-agent AI orchestration when you skip the config.

Website: https://stack.cardor.dev/ahk

The orchestration gap

The standard setup for a structured multi-agent workflow looks like this:

• Lead — decomposes the task, plans, delegates

• Explorer — reads and maps the codebase, never writes

• Builder — implements the plan

• Reviewer — verifies, approves, or blocks

Four specialized roles. Clean separation of concerns. The kind of structure that turns "fix this bug" into a systematic, auditable workflow with full history and no duplicated effort.

The problem: most setups define these roles in markdown files with descriptions like:

"Use this agent to orchestrate a full task. Invoke when starting a new work session."

That description tells the model what the lead is supposed to do. It does not tell the tool to start with lead by default. Those are two different things. And when your AI tool opens a project without an explicit default agent config, it either picks the first agent it finds alphabetically, falls back to its own built-in default, or just asks you — which defeats the point of having a structured workflow in the first place.

The relay baton is a config field, not an instruction

Here's what actually controls who goes first in each tool.

Claude Code uses the agent field in .claude/settings.json:

{
  "agent": "lead"
}

This is the official, documented field for setting which subagent runs as the main session thread. A common mistake — including one we caught in our own materializer — is putting default_agent: "lead" in .claude/mcp.json. That field doesn't exist in Claude Code's config spec. It gets ignored silently, and your session starts wherever Claude decides.

OpenCode uses default_agent in opencode.json:

{
  "default_agent": "lead",
  "compaction": { "auto": true, "prune": true, "reserved": 10000 }
}

This maps correctly. OpenCode also exposes compaction config for managing context window pressure during long orchestrated sessions — useful when lead, explorer, builder, and reviewer are all accumulating history in the same run.

Codex CLI has no direct default_agent field. Instead, Codex ships with a built-in agent named default. You override it by creating .codex/agents/default.toml with your lead agent's instructions and name = "default". Codex will use it as the entry point from that point on.

name = "default"
sandbox_mode = "read-only"

description = """
Use this agent to orchestrate a full task from the harness backlog: decompose it
into a plan, delegate to explorer, builder, and reviewer in sequence.
"""

developer_instructions = """
# Lead Agent

You are the lead agent. Your job is to orchestrate the workflow for one task at
a time. You coordinate — you do not implement.
...
"""

The second problem: roles without enforcement

Getting the starting agent right is half the battle. The other half is making sure each agent stays in its lane once the relay is running.

Instructions help. But instructions are text. A builder told "don't read source files outside src/" can still read them if nothing stops it. An explorer told "never write files" can still write if it decides that's the fastest path. One slightly off prompt, one edge case, and the contract breaks.

This is where per-role sandboxing does real work.

Claude Code exposes permissionMode as a frontmatter field on each agent .md file:

---
name: explorer
permissionMode: plan
---

plan mode puts the session into read-only planning mode — file writes and edits are blocked at the tool level. Not instruction. Enforcement.

For builder:

---
name: builder
permissionMode: acceptEdits
---

acceptEdits means file edits are auto-approved without a per-change confirmation prompt — the right tradeoff for an agent whose whole job is to implement.

Codex CLI uses sandbox_mode per agent TOML file:

# explorer.toml
name = "explorer"
sandbox_mode = "read-only"

# builder.toml
name = "builder"
sandbox_mode = "workspace-write"

The full matrix across our four roles:

Agent	Claude Code permissionMode	Codex sandbox_mode
lead	plan	read-only
explorer	plan	read-only
builder	acceptEdits	workspace-write
reviewer	plan	read-only

Why this saves tokens, not just sanity

There's an economic argument here that goes beyond correctness.

When orchestration defaults are wrong, you burn tokens at the start of every session re-establishing context. Lead has to re-introduce itself. The wrong agent hands off awkwardly. The model spends turns figuring out where it is in the workflow instead of doing the work. Then you re-prompt. Then you clarify. Then you maybe restart.

When defaults are right, the first turn is already positioned correctly. Lead picks up the task, decomposes it, passes the baton to explorer. Explorer maps the codebase, passes to builder. Builder implements, passes to reviewer. Clean chain. No re-orientation. The first session draft is the good one.

The model's intelligence is the same. The setup is what changes the output quality on the first try. More predictable behavior, fewer iterations, less token waste — not because the model got smarter, but because it didn't have to guess its starting position.

Provider comparison

Feature	Claude Code	OpenCode	Codex CLI
Agent files	.claude/agents/*.md	.opencode/agents/*.md	.codex/agents/*.toml
File format	Markdown + YAML frontmatter	Markdown + YAML frontmatter	TOML
Default agent field	agent in settings.json	default_agent in opencode.json	Override built-in via default.toml
Per-role permissions	permissionMode in frontmatter	— (global only)	sandbox_mode in TOML
MCP config file	.claude/mcp.json	opencode.json	.codex/config.toml
Compaction config	Not exposed	compaction.{auto,prune,reserved}	Not applicable

Putting it together

All of this is automated in agent-harness-kit. One command scaffolds the full structure — agents, MCP config, default agent wiring, sandbox settings — for whichever provider you choose:

npx ahk init --provider codex-cli
npx ahk init --provider claude-code
npx ahk init --provider opencode

The materializer knows which field to write to, in which file, in which format. You get correct defaults without cross-referencing three different docs pages — or discovering six months later that your default_agent key in mcp.json was doing nothing.

The relay metaphor holds

Back to the runners. The baton problem isn't about ability — it's about protocol. Define the protocol in config, not in prose. Each runner in their lane, with the right access, in the right order.

The relay runs itself. You just watch the race.

---

Built with github.com/enmanuelmag/agent-harness-kit — provider-agnostic scaffolding for structured multi-agent AI workflows.