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

Multi-agent AI orchestration fails without proper configuration, comparing it to Olympic runners in a relay race who don't know the order or handoff protocol. It details how different tools like Claude Code, OpenCode, and Codex CLI require specific configuration fields (such as `agent` in `.claude/settings.json` or `default_agent` in `opencode.json`) to designate which agent starts first, and emphasizes that per-role sandboxing (like `permissionMode` or `sandbox_mode`) is necessary to enforce behavioral boundaries rather than relying solely on text instructions.

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 standard setup for a structured multi-agent workflow looks like this: 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. 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. ... """ 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: 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. 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. 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 agent-harness-kit — provider-agnostic scaffolding for structured multi-agent AI workflows.