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. It has two layers — a counted execution ledger (the To-do) and an optional strategy context (update_plan metadata).
Checklist: the counted execution 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 context: update_plan metadata
update_plan carries optional high-level strategy — it is not a second checklist. 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 — two competing progress surfaces would only create ambiguity.
Continuity: one state, many surfaces
The same work state feeds several surfaces: the sidebar's To-do area renders it live; /relay has the model write the To-do snapshot and the update_plan strategy metadata into a handoff artifact for the next thread; and a forked (fork_context) sub-agent receives a structured state block in its prefix whose Work section is this To-do snapshot — the child continues from the parent's real progress position instead of a paraphrased summary.
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
Three model-facing paths are implemented and covered by tests: the work_update tool itself, which is active in the model catalog; the forked sub-agent's structured state block (the Work section inside <codewhale:fork_state>, pinned by an engine test); and /relay output, which injects the same To-do snapshot and strategy metadata into the handoff instruction. The sidebar rendering is a visual presentation — it informs the operator and is not injected into model context.
One capability is deliberately not claimed: injecting the current Work state into a normal parent turn's model context (parent-turn grounding). That depends on the runtime test tracked in issue #3983; until it lands, this page describes only proven behavior.
Source documents: docs/TOOL_SURFACE.md, docs/TOOL_LIFECYCLE.md · Update docs-map.ts when changing.