Plan, Goal, and Todo

Conclusion: Plan, Goal, and Todo Are Not Three Names for One “Planning State”

Entering Plan therefore does not create a Goal, creating a Goal does not synthesize Todos, and several in_progress Todo items do not make the Todo tool itself execute concurrently. All three can coexist, but none is a hidden database or scheduler for the others.

1. Three State Machines: Authority, Lifetime, and Driver

All three gain replayability from SessionEvent, but “durable event” does not mean “equally long-lived presentation.” Plan and Goal fold current state across Turns. Todo events are durable too, while the product projection deliberately interprets the list as standing only until the next Turn.

2. Plan Has Two States: Logged Mode and Pending Selection

plan/mode is a log-only, non-Surface, last-write-wins boolean event; the default without one is false. A committed value survives Session resume, Fork, and full-log replay. The controller also owns a Session-keyed WeakMap containing the target mode that has not reached its commit boundary and whether the switch should be narrated to the model. PLANSTATE-PLAN-STATE

3. Plan Changes Guidance, Not Permission or the Tool Catalog

While active, plan:policy renders the deployment-provided section at system-prompt order 50; while inactive, it contributes empty text. The shipped policy asks the model to explore first, restrict itself to non-mutating investigation, submit a decision-complete plan, and explicitly avoid using Todo as a substitute for the reviewed plan. PLANSTATE-PLAN-ASSEMBLYPLANSTATE-SHIPPED-PLAN-POLICY

This keeps the tool schema and Code Mode SDK prefix stable, but an application cannot interpret a lit Plan chip as proof that mutation is rejected at execution. A deployment needing hard read-only behavior must configure that separately.

4. Three Plan Control Surfaces: Command Entry, Tool Review, and Direct Service

The exit tool requires trimmed input beginning with a level-one # heading. Consent requires exactly one plan-review answer, exactly one selected Approve, and no custom text. Keep planning, free-form feedback, duplicate answers, and missing answers all become failed tool results so the model revises. Approval records only a silent pending exit: the current assistant tool batch remains under Plan, and the next accepted pre-Step commits the switch. PLANSTATE-PLAN-CONTROLS

5. Plan’s Web View, Projection, and Crash Recovery Are Not Equivalent

The plan projection folds both command/run(name="plan") and plan/mode. The command derives a wanted target; the mode event commits active and clears wanted. It can therefore recover { active, pending } from a cold log and distribute it through history baselines and session/projection frames to multiple browsers. PLANSTATE-PLAN-PROJECTION

The Web renders a Plan × chip only while the effective target is Plan; clicking it executes /plan off through the command Remote. The same projection selects the composer placeholder. A dedicated review panel presents Approve, Keep planning, and discuss/dismiss; providers that do not understand the intent can still render generic options. PLANSTATE-PLAN-UIPLANSTATE-PLAN-REVIEW-UI

There is no independent plan.get/plan.set business API family. The Web uses generic command Remote plus projection, the model uses the stable exit tool, and host plugins use the service.

6. Goal Is a Complete State Machine with Compare-and-Set Revisions

A Goal identity remains stable across revisions, while GoalRef { id, revision } identifies one exact version. Every snapshot carries objective, phase, and maxGoalRounds; the blocked phase additionally—and only—carries { code, message }. The four phases are active, paused, blocked, and complete. PLANSTATE-GOAL-TYPES

create → active(r1)
active → edit → active(r+1)
active → pause → paused(r+1)
active → block → blocked(r+1)
active|paused|blocked → complete(r+1)
active|paused|blocked --resume, capacity remains→ active(r+1)
any current → clear tombstone(r+1)
complete → create a fresh id at r1

7. Durable Phase and Process-Local Activation Are Separate Axes

Activation is never logged. A fresh cache, every agent/session-start, driver hot-load, and uncertain failure disarm it; resume writes a new revision and arms it. Resume, Fork, and process restart can therefore restore objective, phase, revision, and round count without silently restoring autonomous execution authority. PLANSTATE-GOAL-SERVICEPLANSTATE-GOAL-COMMIT

GoalService also requires the exact live object in AgentRegistry, not merely the same id. After creation, edit, pause, resume, complete, block, and clear all compare the current GoalRef. When browser tabs, model tools, and human commands race, the first commit advances revision and later stale refs fail explicitly instead of overwriting it.

8. Goal Continuation Driver: Same Session, One Reservation, Per-Round Durability

goal/change arms or revises goal
→ driver coalesces wakeups per exact Agent
→ wait until Agent idle and no competing queued human work
→ flush pending durable prefix
→ reserve {goalId, revision, roundsStarted + 1}
→ Agent.followup(<goal_round>...)
→ pre-step validates full message + live revision before and after downstream hooks
→ admitted user/message increments roundsStarted
→ whole Agent returns idle
→ flush the settled round before reserving the next one

Each Agent's driver state permits one queued, claimed, or admitted attempt. The prompt writes the JSON-quoted objective, round/maxGoalRounds, and instructions to verify progress against current workspace, tool results, and durable state as an ordinary user message. It neither creates a new Agent nor copies the Session. PLANSTATE-GOAL-DRIVER

The round cap counts admitted rounds, not tokens, cost, or time. At capacity the driver writes durable blocked with code round-limit. Test source requires exactly rounds 1 through N and no extra dispatch. PLANSTATE-GOAL-DRIVER-TEST

9. Goal Tool Authority Is Stricter Than GoalService

Tool authority is derived from actual committed user/message.source inside the open Turn, not from model arguments. A goal round must match the current id, revision, and roundsStarted; an autonomous round may not edit, pause, or resume. PLANSTATE-GOAL-AUTHORITYPLANSTATE-GOAL-TOOLS

10. Goal Commands, Remote/API, and Web UI Expose Different Operation Sets

/goal executes directly in the command plane without opening a model Turn. The Web also projects durable command/run into a right-aligned command-input bubble. GoalBar reads the latest projected CAS ref for every click and combines a synchronous ref with React pending for single-flight behavior; after clear succeeds it locally suppresses that id until the null projection catches up. PLANSTATE-GOAL-COMMANDPLANSTATE-GOAL-COMMAND-UIPLANSTATE-GOAL-COMMAND-VIEWPLANSTATE-GOAL-UIPLANSTATE-GOAL-UI-REMOTE

The Host mutation façade reuses a live Agent or cold-resumes an ordinary Session and rejects identities still owned by subagent routing. It does not reuse the model tool's “direct human Turn” rule; it is a trusted control-plane mutation of the domain. GoalError currently maps to wire internal, with the stable domain code under details.goalCode, so clients must inspect details to distinguish stale revision and other business failures. PLANSTATE-GOAL-APIPLANSTATE-GOAL-API-ROUTINGPLANSTATE-GOAL-API-ERRORS

11. Goal Failure, Cancellation, and Concurrency Recovery

The driver serializes work with one attempt and a coalesced run promise per Agent; Goal mutations serialize conflicting control planes through revision CAS. These solve different concurrency problems. If an external LLM-retry plugin recovers successfully within the same Step, the original reservation can settle; the driver itself never converts an unclassified failure into a new round. PLANSTATE-GOAL-DRIVERPLANSTATE-GOAL-DURABILITY-TEST

12. Todo Is Whole-Value Replacement, Not a Task Database

todo_write({ todos }) must send the complete list on every call. Success synchronously appends one todo/write, and current value is the last snapshot. Each item contains only normalized non-empty content and one of pending, in_progress, or completed. There is no id, priority, dependency, nesting, patch, delete-one operation, or read-back operation. An empty array is a valid explicit empty list. PLANSTATE-TODO-TOOL

allowParallelInProgress is a required deployment choice. true changes both model instructions and validation to allow several active items; false rejects more than one. The shipped base profile selects true. The durable invariant deliberately does not reapply the current active-count policy, so a log written under a permissive deployment still replays after policy is tightened. PLANSTATE-SHIPPED-TODO-POLICYPLANSTATE-TODO-INVARIANT

13. Todo Events Persist; the Standing Projection Lasts Only Until the Next Turn

Turn N: todo_write(snapshot A)
        todo_write(snapshot B)   → projection = B
        turn/end                 → projection still B
Turn N+1: turn/start             → projection = null
        ... old todo/write events remain in the Session log

The todos projection is null before the first write, replaces its whole value on every write, and clears on every turn/start. It does not clear at turn/end, so a completed checklist remains visible after Agent idle until another human or automatic goal round actually opens a Turn. Cold reads, resume, and Fork replay the same full-log fold. PLANSTATE-TODO-PROJECTION

The Web TodoPanel reads only that projection, showing a collapsible card with status counts and all items. A separate todo_write tool row derives “done/total + first active + extra-active count” from durable call arguments. The first is the product's currently standing list; the second is historical tool-call presentation. Their lifetimes differ. PLANSTATE-TODO-UIPLANSTATE-TODO-ROW

14. “Todo Allows Parallel Work” Means the Todo Tool Itself Is Exclusive

ToolRuntime classifies a call as parallel only when its definition supplies isConcurrencySafe(args) and returns exact true. Omission, exceptions, hidden tools, and invalid definitions all fail closed to exclusive. Plan exit, all three Goal tools, and todo_write do not opt in, so each is an ordering barrier. PLANSTATE-TOOL-EXCLUSIVE

Two consecutive todo_write calls in one model batch therefore execute in order, and the second deterministically replaces the first. Multiple in_progress items mean the Agent may genuinely advance work through subagents, background commands, or workflows at the same time. They are not permission for concurrent snapshot writes and do not create a shared swarm task registry. PLANSTATE-TOOL-SCHEDULER

15. Event, Surface, Projection, and Replay Matrix

Compaction rewrites model Surface; it does not delete these log-only domain facts. Plan active and Goal lifecycle do not depend on a summary remembering them. Todo projection also remains reconstructable from the complete log, although its next-Turn clearing rule still applies. Goal-round prompts, tool calls, and results are Surface content, so a later model may know their semantics only through a checkpoint after compaction.

16. Three Confirmed Documentation Drifts

These findings compare production source and tests at the pinned commit; they are not inferences from prose alone. The core Plan and Todo READMEs broadly match their current control flow within this chapter's scope. Goal evolved across more packages and shows visible synchronization lag. PLANSTATE-DOC-GOAL-TOOLPLANSTATE-DOC-GOAL-UIPLANSTATE-DOC-GOAL-COMMAND

17. Confirmed Constraints, Gaps, and Deliberate Tradeoffs

18. Design Assessment and Verification Status