Work items

This page defines the current contract for WorkItem runtime behavior: lifecycle, focus, readiness, planning, blocking, and completion semantics.

Last verified: 2026-05-26 against src/types.rs WorkItemRecord, WorkItemState, WorkItemPlanStatus, WorkItemReadiness, WorkItemSchedulingState, and the tool implementations in src/tool/tools/{create,update,pick,list,get,complete}_work_item.rs and src/tool/tools/wait_for.rs.

Source RFCs

• Work Item Runtime Model
• Work Item Centered Agent Runtime
• Objective, Delta, and Acceptance Boundary
• Long-Lived Context Memory
• Turn-Local Context Compaction

Core model

A WorkItem is a durable objective record owned by an agent. It tracks:

The Rust enum WorkItemPlanStatus uses PascalCase variants (Draft, Ready, NeedsInput), but all tool input/output uses snake_case (draft, ready, needs_input).

Lifecycle states

                    CreateWorkItem
                          │
                          ▼
                    ┌──────────┐
                    │   Open   │
                    └────┬─────┘
                         │
            ┌────────────┼────────────┐
            ▼            ▼            ▼
       plan_status    plan_status   plan_status
        = Draft       = Ready       = NeedsInput
            │            │               │
            └────────────┼───────────────┘
                         │
                    CompleteWorkItem
                         │
                         ▼
                    ┌───────────┐
                    │ Completed │
                    └───────────┘

Key contract:

• state is the hard lifecycle boundary: Open or Completed.
• plan_status is the planning/coordination posture: whether the plan is still being drafted, ready for execution, or waiting for operator input.
• plan_status=NeedsInput makes the WorkItem non-runnable and means the scheduler must wait for operator input.
• WaitFor is the agent-facing way to mark a WorkItem waiting on operator input, a task result, or an external resource. It sets blocked_by for display and records the structured active wait.

Readiness and scheduling

WorkItem readiness is derived from state, plan_status, blocked_by, and active wait state:

WorkItemReadiness is the reduced view used by scheduler and user display:

Key contract:

• Readiness is derived, not stored. is_runnable() and is_waiting_for_operator() are computed from current state.
• WaitFor(wake=operator_input) is the explicit wait signal when operator input blocks the current WorkItem.
• Older blocked WorkItems with recheck_at carry a fallback deadline; the scheduler may re-evaluate them after that time.
• Current focus is separate from readiness. A blocked WorkItem can still be the current focus for inspection, while queued and blocked list filters are derived views over focus plus scheduler readiness.

Focus and current work

An agent has at most one current WorkItem (current_work_item_id). The current WorkItem is the focus for the current turn:

• PickWorkItem sets the current focus from an existing open WorkItem.
• The scheduler may auto-pick a runnable WorkItem when the agent wakes.
• Current focus persists across turns until explicitly changed or completed.
• Only runnable WorkItems are eligible for scheduler auto-resume.

Tool surface

Key contract:

• CreateWorkItem should only be used for genuinely separate objectives with independent lifecycles. Use UpdateWorkItem to refine the current WorkItem instead of creating a new one for the same task.
• UpdateWorkItem.todo_list replaces the full checklist snapshot; it is not an append operation.
• WaitFor replaces direct blocker mutation for new waits. It attaches to the current open WorkItem; pick another WorkItem first if that is the one that should wait.
• CompleteWorkItem promotion: the operator-facing completion report must be written as assistant text in the same round. After the tool succeeds, the runtime promotes that text as the canonical completion report and terminal user-facing delivery for the turn.
• A promoted completion report writes exactly one result brief for that WorkItem. The turn-final result brief is suppressed so the same completion is not delivered twice.
• Additional runnable WorkItems after completion resume through scheduler-owned work-queue SystemTick messages, not through another provider round in the completed WorkItem's turn.
• Plan body changes go through direct file edits to plan_artifact.path, not through UpdateWorkItem.

Plan artifact

Each WorkItem has an optional plan_artifact pointing to a plan.md file in the agent's home directory (work-items/<id>/plan.md). The plan artifact:

• Is not stored inline in the WorkItem record.
• Is read by GetWorkItem (bounded preview) and editable via ApplyPatch/file tools.
• Contains the durable prose plan; todo_list is the progress checklist.

Known gaps

• WorkItemSchedulingState and WorkItemReadiness overlap; WorkItemReadiness collapses five waiting states into "Blocked", which loses scheduling granularity at the display layer.
• Plan artifact path resolution depends on agent home workspace; cross-agent WorkItem reads may need explicit workspace routing.
• Older ledger snapshots that contain inline plan text are migrated into the AgentHome plan artifact when the WorkItem is refreshed. Current snapshots do not serialize inline plan body state.