Planner

The planner is how an AI handles work that needs more than a single turn but less than full delegation. Instead of stalling the conversation or fanning out a bunch of sidekicks, the AI writes a plan, commits to it, and works through it step by step.

You're the supervisor: pause, resume, cancel at any point.

Anatomy of a plan#

A plan has:

• A goal — one-sentence summary of what's being accomplished.
• A state: draft, running, paused, done, failed, cancelled.
• A mode: sequential (work steps one at a time, each builds on the previous) or parallel (fan out as sidekicks; merge results).
• An advance setting: auto (continue without your nudge, bounded by a budget) or manual (each step waits for you).
• A venue: main (runs in the current room) or sidekick (spawns a sidekick room and runs there; main chat stays clean).
• A list of steps, each with a 5-character id, text, status (pending, in_progress, done, failed, skipped), a result the AI fills in on completion, and an attempts counter.

The plan card#

When a plan is active, a plan card mounts above the chat timeline showing:

• State badge + goal.
• Each step with a glyph: ○ pending, ▶ in progress, ✓ done, ✗ failed, — skipped.
• The current step pointer (an underline marker).
• An auto-budget indicator (⚡N) when advance=auto — how many more steps the AI can do before pausing for your check-in.
• Pause / Resume / Cancel buttons. Always visible.

Per-step results expand on click; you can see exactly what the AI recorded for "step 3 done".

The lifecycle#

• draft — written but not started. Can be edited freely.
• running — the AI is working.
• paused — the AI is waiting. Reasons: supervisor pause, retry cap hit on a step, next='revise' on a step_failed call.
• done — all steps reached a terminal status; none failed.
• failed — all steps terminal; at least one failed.
• cancelled — supervisor stopped it.

Failure recovery#

If a tool call inside a step errors, the harness adds a nudge to the error result:

Plan harness: this is step 3/5, attempt 1/3. If the error suggests fallbacks above, try the one that best fits the user's intent. Reserve step_failed for when you've genuinely run out of angles.

Combined with plugin-side fallback hints (e.g. ScaiDrive errors suggest web_search), this prevents the "give up at the first 401" failure mode.

Each step gets up to 3 attempts before being forced-paused for your decision. The AI can also voluntarily call step_failed with one of four next actions:

The auto-step throttle#

When advance=auto, the AI continues through steps without your intervention. To prevent runaway behaviour:

• Counter consecutive_auto_steps increments after each automatic advance.
• When it hits max_consecutive_auto_steps (default 8), the harness forces a pause. You see the plan card in paused state.
• Any message you send resets the counter to 0.

Caps and invariants#

• At most one active plan per room. The AI can't start a second plan while one is running, paused, or in draft.
• Max 20 steps per plan. If the work genuinely needs more, the AI splits it.
• Plans don't survive room close. Cancelled when the room is closed. Archived rooms keep their plan history for audit.

When to use which#

• Single tool call answers a question → no plan. Just ask.
• Background research with independent subtasks → parallel mode (or a sidekick).
• Multi-step task with dependencies → sequential, default mode.
• Long-running task you don't want cluttering the chat → venue=sidekick.

Where to go next#

• Tutorial: Use the planner.
• Sidekicks — for purely delegated work.
• API: Plans.