Tasks

This page defines the current contract for managed task execution: lifecycle, terminal re-entry, and supervision surfaces.

Last verified: 2026-05-25 against src/types.rs TaskRecord, TaskStatus, TaskKind, TaskHandle, TaskWaitPolicy, and the tool implementations in src/tool/tools/{exec_command,task_list,task_status, task_output,task_input,task_stop,spawn_agent}.rs.

Source RFCs

Task kinds

`TaskKind`	Description
`CommandTask`	Shell command execution via `ExecCommand`
`ChildAgentTask`	Parent-supervised delegated child agent via `SpawnAgent`
`SleepJob`	Internal sleep timer (not model-visible)
`SubagentTask`	Legacy child agent kind (migrating to `ChildAgentTask`)
`WorktreeSubagentTask`	Legacy worktree-isolated child agent (migrating)

Task lifecycle

              ExecCommand / SpawnAgent
                       │
                       ▼
                 ┌──────────┐
                 │  Queued  │
                 └────┬─────┘
                      │
                      ▼
                 ┌──────────┐     TaskStop
                 │ Running  │──────────────┐
                 └────┬─────┘              │
                      │                    ▼
          ┌───────────┼───────────┐  ┌────────────┐
          ▼           ▼           ▼  │ Cancelling │
    ┌──────────┐ ┌──────────┐ ┌────┴─┴─────┐      │
    │Completed │ │  Failed  │ │Interrupted│      ▼
    └──────────┘ └──────────┘ └───────────┘┌──────────┐
                                           │Cancelled │
                                           └──────────┘

Terminal states: Completed, Failed, Cancelled, Interrupted. Non-terminal states: Queued, Running, Cancelling.

Wait policy

Each task carries a wait policy for task-list and task-status compatibility:

`TaskWaitPolicy`	Behavior
`Background`	Task runs independently; agent can continue turns while task is active

All current task kinds report Background. Historical task detail payloads may still contain wait_policy: "blocking", but the runtime ignores that value for scheduler blocking decisions.

Key contract:

For background tasks, use WaitFor(wake=task_result, resource=<task_id>) to wait for the terminal TaskResult instead of polling TaskOutput.
The terminal TaskResult event re-enters the agent as continuation context; the runtime wakes the agent automatically.
TaskOutput(block=true) is for explicit current-turn synchronous waiting, not the default waiting strategy.

Supervision tools

Tool	Purpose
`TaskList`	Compact active-task digest (non-terminal tasks only)
`TaskStatus`	Single-task lifecycle snapshot with metadata
`TaskOutput`	Bounded output preview with optional `block=true`
`TaskInput`	Send stdin/follow-up input to an interactive task
`TaskStop`	Stop a running task (may transition through `Cancelling`)

Key contract:

TaskList excludes terminal tasks; use TaskStatus for historical detail.
TaskOutput returns a bounded output_preview plus artifact refs for full output; it is for inspection, not polling.
TaskInput accepts input only for tasks created with interactive continuation enabled (accepts_input=true).
TaskStop sends a stop request; the task may first enter Cancelling before reaching Cancelled.

Distinction from WorkItems and waiting

Tasks are execution handles, not planning objects:

A Task represents a running or queued execution unit.
A WorkItem represents a durable objective the agent is working toward.
Waiting represents why a WorkItem or agent cannot proceed.

Tasks often serve WorkItem objectives (running commands, delegating to child agents), but task lifecycle is independent of WorkItem lifecycle.

Resolved gaps

Issue #1382 removed the unused Blocking task wait policy from the public/runtime contract. Waiting is expressed with WaitFor(wake=task_result) plus terminal task re-entry, or with a bounded TaskOutput(block=true) call inside the current turn.