A task is a unit of work assigned to an agent. Tasks are the building blocks of missions — each task has a clear deliverable, an assigned agent, and an automated assessment cycle.
Task fields Field Type Description idstring Auto-generated unique identifier titlestring Short name used for dependency references descriptionstring Detailed instructions for the agent assignTostring Agent name to execute this task dependsOnstring[] Task titles that must complete first statusTaskStatus Current lifecycle state phaseTaskPhase Current execution phase prioritynumber Execution priority (higher = first) deadlinestring ISO 8601 timestamp for this task expectationsobject[] Assessment criteria (see Assessment ) metricsobject Key-value pairs to track retriesnumber Current retry count maxRetriesnumber Maximum retry attempts maxDurationnumber Timeout in milliseconds retryPolicyRetryPolicy Escalation and fallback config resultobject Output produced by the agent expectedOutcomesExpectedOutcome[] Declared output types outcomesobject[] Actual outputs after execution sideEffectsboolean Whether the task modifies external state
Status state machine Tasks follow a strict lifecycle:
draft → pending → assigned → in_progress → review → done → failed → awaiting_approval
Status Meaning draftDefined but mission not started pendingWaiting for dependencies to resolve assignedAgent selected, waiting for sandbox in_progressAgent is executing reviewAssessment is running donePassed assessment failedFailed after all retries exhausted awaiting_approvalBlocked on human approval (side effects)
Transitions
draft to pending
Mission starts. Tasks with no dependsOn move immediately to pending.
pending to assigned
All dependencies resolved. The scheduler assigns the task to its agent.
assigned to in_progress
Agent sandbox is ready. Execution begins.
in_progress to review
Agent produces a result. Assessment runs automatically.
review to done
Assessment score meets the quality threshold.
review to failed
Score below threshold and all retries (including fix attempts) exhausted.
in_progress to awaiting_approval
Task has sideEffects: true. Pauses for human approval before proceeding.
Task phase The phase field tracks where the agent is within a single execution attempt:
Phase Description executionAgent is working on the task reviewLLM reviewer is assessing the result fixAgent is fixing issues based on review feedback clarificationAgent is requesting clarification
Retry policy When a task fails assessment, the retry policy controls escalation:
{ "retryPolicy" : { "escalateAfter" : 2 , "fallbackAgent" : "senior-dev" , "escalateModel" : "anthropic:claude-sonnet-4-5" } }
Field Type Description escalateAfternumber Retry count that triggers escalation fallbackAgentstring Agent to reassign to after escalation escalateModelstring Upgrade to a more capable model on retry
Escalation happens after escalateAfter failed retries. The task is reassigned to fallbackAgent (if set) or the same agent with escalateModel (if set). Both can be combined.
Expected outcomes Declare what the task should produce so assessment can verify outputs:
Type Description fileA file at a specific path textFree-form text content urlA valid URL jsonStructured JSON matching a schema mediaAn image, video, or audio file
{ "expectedOutcomes" : [ { "type" : "file" , "path" : "report.md" }, { "type" : "json" , "schema" : { "type" : "object" , "required" : [ "summary" ] } } ] }
Side effects When sideEffects is true, the task will pause at awaiting_approval before completion. Auto-retry is disabled — a human must approve each attempt. Use this for tasks that modify external systems (deploy, send email, update database).
{ "title" : "Deploy to production" , "assignTo" : "deploy-agent" , "sideEffects" : true }
CLI Add a task to a mission
List tasks
Show task details
Retry a failed task
polpo task add --mission weekly-report --title "Gather PR data" --assign data-collector
