Find the guidance you need.

The Work surface

The TUI sidebar has a Work area that shows live state for the current job. It is more than a visual to-do list: the same work state is maintained by model-visible tools, session relay, and sub-agent handoff. Codewhale has exactly one Work surface — the counted To-do execution ledger. update_plan is conversational reasoning, not a second progress surface.

To-do: the sole canonical ledger

The To-do is the progress ledger for concrete work: a list of items with status (pending / in_progress / completed / cancelled), a completion percentage, and the item currently in progress. The model replaces this projection for the active thread or durable task through the canonical work_update tool — the model-visible progress surface. The legacy checklist_* and todo_* names remain hidden compatibility aliases: they stay dispatchable against the same To-do state so old transcripts replay, but they are not advertised to the model catalog.

Strategy is conversational reasoning: update_plan

update_plan carries optional high-level strategy — it is not a second ledger. Its fields serve phase-level understanding: title, objective, context summary, explanation, sources, critical files, constraints, recommended approach, verification plan, risks and unknowns, a handoff packet, and a list of steps. It helps a parent session or a later worker understand the approach; concrete execution progress always belongs to the To-do ledger. The sidebar deliberately does not render strategy state as a second progress list, and model-facing Work grounding excludes it entirely — plan state with an empty To-do produces no Work state at all.

Continuity: one state, many surfaces

The same work state feeds several surfaces through one renderer: a transient <codewhale:work_state> block is appended to each parent turn-loop and sub-agent step request; a forked (fork_context) sub-agent receives the same body inside its structured state block; and /relay writes the same body into the handoff instruction. The To-do body is byte-identical in all three, so a child agent and the next thread continue from the parent's real progress position instead of a paraphrased summary. The sidebar renders that same state live.

Terminal capture (faithful text)

This text block reproduces the sidebar Work area line-for-line from the rendering logic in crates/tui/src/tui/sidebar.rs: the goal row with its ◆ icon, elapsed time, and token budget bar, then the settled counter and the numbered status items.

To-do
◆ Goal: Land the v0.9.2 website docs cluster
elapsed: 18m
[█████████░░░░░░░░░░░] 45%
50% settled (2/4)
[✓] #1 Read docs-map.ts and the Modes page pattern
[✓] #2 Draft the Fleet and Sandbox pages
[~] #3 Write the Work surface page
[ ] #4 Run check:docs, tests, and the build

The item prefixes map to the four statuses: [ ] pending, [~] in progress, [✓] completed, [-] cancelled. When space runs out, the sidebar windows around the in-progress item and marks the omission with “+N more To-do items”.

What is model-facing vs. visual-only

Five model-facing paths are implemented and covered by tests: the work_update tool itself, which is active in the model catalog; the <codewhale:work_state> block appended to each parent turn-loop request (#3983); the same block on each sub-agent step request, rendered from that agent's own list; the forked sub-agent's structured state block (the Work section inside <codewhale:fork_state>, resolved at the moment of the fork); and /relay output. The sidebar rendering is a visual presentation — it informs the operator and is not injected into model context.

The boundaries are worth stating: the block is transient — it belongs to a single request, is never written to session history, and never enters the stable system prefix, so the stable system-and-tool prefix remains eligible for prefix caching; each provider's treatment of the latest user message still depends on its wire protocol. It is rebuilt before each parent turn-loop and sub-agent step request from the authoritative state (the work graph's staged projection where one exists, not the not-yet-published legacy view), so a work_update made mid tool-loop appears on the following step. The parent turn-loop context preflight is charged for the exact tail that will be sent, so it cannot approve a request that goes over-limit only once the block is appended; offline counts stay conservative. Item count and character count are both hard-bounded, the in-progress item is preserved preferentially, and elided content is marked. An empty To-do emits no block at all. The renderer guarantees exactly three things — wrapper framing cannot be closed early, control characters cannot forge the line format, and the bounds hold. It does not vet what item text says, so arbitrary To-do content is not thereby made safe to follow as instructions.