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 |
|---|
id | string | Auto-generated unique identifier |
title | string | Short name used for dependency references |
description | string | Detailed instructions for the agent |
assignTo | string | Agent name to execute this task |
dependsOn | string[] | Task titles that must complete first |
status | TaskStatus | Current lifecycle state |
phase | TaskPhase | Current execution phase |
priority | number | Execution priority (higher = first) |
deadline | string | ISO 8601 timestamp for this task |
expectations | object[] | Assessment criteria (see Assessment) |
metrics | object | Key-value pairs to track |
retries | number | Current retry count |
maxRetries | number | Maximum retry attempts |
maxDuration | number | Timeout in milliseconds |
retryPolicy | RetryPolicy | Escalation and fallback config |
result | object | Output produced by the agent |
expectedOutcomes | ExpectedOutcome[] | Declared output types |
outcomes | object[] | Actual outputs after execution |
sideEffects | boolean | 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 |
|---|
draft | Defined but mission not started |
pending | Waiting for dependencies to resolve |
assigned | Agent selected, waiting for sandbox |
in_progress | Agent is executing |
review | Assessment is running |
done | Passed assessment |
failed | Failed after all retries exhausted |
awaiting_approval | Blocked 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 |
|---|
execution | Agent is working on the task |
review | LLM reviewer is assessing the result |
fix | Agent is fixing issues based on review feedback |
clarification | Agent 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 |
|---|
escalateAfter | number | Retry count that triggers escalation |
fallbackAgent | string | Agent to reassign to after escalation |
escalateModel | string | 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 |
|---|
file | A file at a specific path |
text | Free-form text content |
url | A valid URL |
json | Structured JSON matching a schema |
media | An 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
}
Managing tasks
Tasks are defined in mission files inside .polpo/ and synced to the cloud via polpo deploy. You can also manage tasks via the REST API or the dashboard. 
