Planner–executor

Read these first

• Choosing an architecture
• Planning

What you will know

• Separate planning from execution as distinct roles

  Use an explicit plan and execution contract so tool results, permissions, and failure states cross a controlled boundary rather than leaking through prompts.

• Re-plan when the executor fails rather than retrying

  A failed tool call can invalidate later steps, so blindly repeating it may compound side effects or preserve an impossible plan.

• Show a plan surviving an executor failure

  The demonstration should include updated remaining work and completed work, not merely a second attempt at the failed operation.

• Measure planner–executor latency and token cost against a fused loop on the same task set

  The planner call and recovery turns increase tail latency and context usage even when the executor itself is fast.

• Decide when planning and execution should stay fused

  Short, low-risk tasks usually benefit from one loop, while decomposition is justified by inspectability, tool complexity, or meaningful recovery needs.

Chapters

1. 1

   A plan step is a tool, its arguments and a postcondition

   When a planner emits free text — "look up the customer's plan and check whether they are eligible" — the executor re-derives intent and nobody can say afterwards whether the plan or the execution was at fault. Make each step a structured commitment instead, so a failure attributes to a wrong request or an unmet postcondition, and tool results, permissions and error states cross a controlled boundary.

   Read chapter
2. 2

   A failed step invalidates the steps that assumed it

   Step three updates a customer record archived overnight; the executor retries three times, moves on, and steps four to six run against a state that never came to exist. The run reports success. Retrying was never the defect — continuing was. Learn what the re-planning call must be handed for recovery to be safe: the work already completed and the work still remaining, not just the failed operation. Preconditions belong here too, as the mirror of the postcondition: checking before a step catches an assumption that went stale between planning and execution, but it costs something on every run to catch a rare case, it leaves a window between the check and the action, and a failed precondition still lands you in the same re-plan — so it changes when you find out rather than what you do.

   Read chapter
3. 3

   Idempotency decides whether a retry is safe, not the error

   A customer email times out after the request has left your process. Whether retrying is safe is a property of the operation rather than of the error: connection resets, gateway errors and ambiguous provider responses leave exactly the same uncertainty a timeout does. Put idempotency into the plan format itself so the decision is made once per tool instead of ad hoc during an incident.

   Read chapter
4. 4

   An unobservable effect needs a key, a status read or a compensation

   Knowing a step is not idempotent tells you not to retry, and the work still has to complete. Escalating to the planner does not help, because the planner cannot determine whether the email went out either — what is missing is a way to observe or deduplicate the effect, not a smarter decision-maker. Three things give you one: an idempotency key supplied by the caller so a repeat is collapsed at the far end, a status read that establishes whether the effect actually happened, and a compensating action for the cases where no such read exists. Where none is available, the honest move is to record the step's outcome as unknown in the run state so the re-planner reasons about it explicitly, and the plan format should require each tool to declare which of these it has.

   Read chapter
5. 5

   The split's cost lives in the tail, on the runs that re-plan

   Both designs complete 91% of a 300-task set and the split adds one planner call — except on the 12% of runs where re-planning fires, each paying another long-context planner call that lands entirely in the tail. Measure tokens and latency at p95 and p99 with recovery turns included. This chapter also weighs the claim that two smaller prompts are inherently more maintainable than one larger one.

   Read chapter
6. 6

   Inspectability does not require a planner to buy it

   Fetch a report, summarise it, post it to a channel: three low-risk steps that gain nothing from a planner call, a second prompt and a stateful boundary to recover across. If you want the readable trace, have the fused loop record its intended action and arguments before each call. And safety on a refund tool comes from approval gates, permissions and idempotency, all available to a single loop.

   Read chapter