{"slug": "when-smart-is-not-enough-multi-agent-ai-orchestration-defaults", "title": "When smart is not enough — Multi-agent AI orchestration defaults", "summary": "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.", "body_md": "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.\nWhat 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.\nThis is the exact problem with multi-agent AI orchestration when you skip the config.\nWebsite: https://stack.cardor.dev/ahk\nThe standard setup for a structured multi-agent workflow looks like this:\nFour 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.\nThe problem: most setups define these roles in markdown files with descriptions like:\n\"Use this agent to orchestrate a full task. Invoke when starting a new work session.\"\nThat 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.\nHere's what actually controls who goes first in each tool.\nClaude Code uses the agent\nfield in .claude/settings.json\n:\n{\n\"agent\": \"lead\"\n}\nThis 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\"\nin .claude/mcp.json\n. That field doesn't exist in Claude Code's config spec. It gets ignored silently, and your session starts wherever Claude decides.\nOpenCode uses default_agent\nin opencode.json\n:\n{\n\"default_agent\": \"lead\",\n\"compaction\": { \"auto\": true, \"prune\": true, \"reserved\": 10000 }\n}\nThis 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.\nCodex CLI has no direct default_agent\nfield. Instead, Codex ships with a built-in agent named default\n. You override it by creating .codex/agents/default.toml\nwith your lead agent's instructions and name = \"default\"\n. Codex will use it as the entry point from that point on.\nname = \"default\"\nsandbox_mode = \"read-only\"\ndescription = \"\"\"\nUse this agent to orchestrate a full task from the harness backlog: decompose it\ninto a plan, delegate to explorer, builder, and reviewer in sequence.\n\"\"\"\ndeveloper_instructions = \"\"\"\n# Lead Agent\nYou are the lead agent. Your job is to orchestrate the workflow for one task at\na time. You coordinate — you do not implement.\n...\n\"\"\"\nGetting 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.\nInstructions 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.\nThis is where per-role sandboxing does real work.\nClaude Code exposes permissionMode\nas a frontmatter field on each agent .md\nfile:\n---\nname: explorer\npermissionMode: plan\n---\nplan\nmode puts the session into read-only planning mode — file writes and edits are blocked at the tool level. Not instruction. Enforcement.\nFor builder:\n---\nname: builder\npermissionMode: acceptEdits\n---\nacceptEdits\nmeans file edits are auto-approved without a per-change confirmation prompt — the right tradeoff for an agent whose whole job is to implement.\nCodex CLI uses sandbox_mode\nper agent TOML file:\n# explorer.toml\nname = \"explorer\"\nsandbox_mode = \"read-only\"\n# builder.toml\nname = \"builder\"\nsandbox_mode = \"workspace-write\"\nThe full matrix across our four roles:\nThere's an economic argument here that goes beyond correctness.\nWhen 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.\nWhen 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.\nThe 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.\nAll 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:\nnpx ahk init --provider codex-cli\nnpx ahk init --provider claude-code\nnpx ahk init --provider opencode\nThe 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\nkey in mcp.json was doing nothing.\nBack 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.\nThe relay runs itself. You just watch the race.\nBuilt with agent-harness-kit — provider-agnostic scaffolding for structured multi-agent AI workflows.", "url": "https://wpnews.pro/news/when-smart-is-not-enough-multi-agent-ai-orchestration-defaults", "canonical_source": "https://dev.to/enmanuelmag/when-smart-is-not-enough-multi-agent-ai-orchestration-defaults-4okg", "published_at": "2026-05-20 14:00:00+00:00", "updated_at": "2026-05-20 14:03:30.298319+00:00", "lang": "en", "topics": ["artificial-intelligence", "developer-tools", "enterprise-software"], "entities": ["Claude Code"], "alternates": {"html": "https://wpnews.pro/news/when-smart-is-not-enough-multi-agent-ai-orchestration-defaults", "markdown": "https://wpnews.pro/news/when-smart-is-not-enough-multi-agent-ai-orchestration-defaults.md", "text": "https://wpnews.pro/news/when-smart-is-not-enough-multi-agent-ai-orchestration-defaults.txt", "jsonld": "https://wpnews.pro/news/when-smart-is-not-enough-multi-agent-ai-orchestration-defaults.jsonld"}}