One mega-agent plans and executes with the same tool belt. The plan sounds careful. Then a write tool fires mid-thought because the model mixed brainstorming with action. Shared context without role boundaries is how quiet mutations happen in production.
Separate planner prompts from executor tools. The planner reasons with read-only tools. The executor receives a narrow plan and a write tool allowlist. Boundaries beat longer system prompts every time the stakes include real writes.
Give the planner a read-only belt
Planner tools should fetch docs, schemas, and status. No payments, no deletes, no outbound posts. If the planner needs a write, it must emit a plan object for a separate executor step. That object is the contract between roles. Version it.
Version those planner packs like APIs so behavior stays rollable, as in version prompt packs the same way you version APIs. Planner drift should be as visible as executor drift in review.
Bound the executor to the plan object
The executor should not invent new goals. It executes steps, reports results, and stops when the plan ends or a gate blocks. Tight schemas keep it honest: bound tool schemas tightly before agents call them.
Cap tool results before the next turn so executor noise cannot drown the planner on the handoff, following cap tool results before the next turn.
Trace both roles with the same fields
Log role, plan id, tool, and model pin on every span. Debug should show whether a write came from the executor path. Teams that log structured agent traces for cheaper debug work can add role without a second pipeline.
Eval harnesses should score planner quality and executor fidelity separately. A brilliant plan that the executor ignores is still a failure mode worth catching early via build eval harnesses for tool-calling agents.
Keep network policy per role
Planner egress can be wider for research hosts. Executor egress should stay default-deny with exact allowlists. Role-aware egress prevents a curious planner from becoming a writing agent by accident when tools are shared across roles.
Secrets remain out of both live packs unless a gated write needs vault injection after human approval and the expire clock is set.
Start with one workflow, then expand
Pick one ticket type: research then draft PR comment. Run planner read-only, executor write-gated. Expand only after traces show clean handoffs. Dual-role theater without metrics is just more folklore with nicer names.
Document the plan object schema in the repo and link it from the runbook. New agents should clone the contract, not invent a new chat dialect each sprint when someone is in a hurry and wants a shortcut.
FAQ
Why separate planner and executor?
To stop brainstorming steps from holding write tools that can mutate production state.
What tools can the planner use?
Read-only fetch and status tools. No payments, deletes, or public posts.
What is a plan object?
A versioned structure of steps the executor may run, with tool allowlists and stop conditions.
Can one model play both roles?
Yes, if the runtime still enforces separate tool belts and traces role on every span.
How do evals change?
Score planner quality and executor fidelity separately so failures are attributable.
Where do human gates sit?
On irreversible executor tools, after the plan is accepted and before the write fires.