Task Lifecycle
Everything about how tasks move from Claude to you and back. Status flows, replies, attachments, and how the agent picks up where it left off.
The Full Lifecycle
The agent sets notstarted → ongoing when it starts work, then transitions to completed or rejected based on your response. For human-assigned tasks, you control the status transitions from the dashboard.
Status Reference
task create. The task is queued and visible in the
dashboard. The agent should immediately call task updateStatus with "status": "ongoing" when it starts working
on it.
task updateStatus with "status": "completed". For human-assigned
tasks, the human marks it complete from the dashboard. The task moves to the completed
section.
"status": "rejected" with task updateStatus if it can't
complete the work. A task reply explaining why is good
practice.
Creating Tasks (from Claude)
Claude calls task create whenever it needs human input.
A well-formed task includes:
task {"action": "create", "payload": {
"title": "Approve: Delete stale user sessions older than 90 days",
"body": "I'm about to run this migration:\nDELETE FROM user_sessions WHERE created_at < NOW() - INTERVAL '90 days';\n\nEstimated rows affected: ~14,000\nThis is irreversible. Approve to proceed?",
"assignee": "human"
}}
Run help {"action": "task.create"} for every field
task create accepts. Plugins and gateways installed before the
action tools may call createTask instead; the server
still accepts the old names. See the MCP tools reference.
Replying to Tasks
From the dashboard, type your reply and hit send. Your message is instantly pushed to Claude
via the notification channel. Claude receives it as a <channel> message in its context — no polling
needed.
Updating schema to use UUID pk + expires_at index...
The agent can also send replies back to a task thread using task reply — useful for progress updates,
confirmations, or follow-up questions.
Attachments
Both Claude and humans can attach files to tasks. This is useful for sharing diffs, screenshots, logs, or config files.
Claude passes base64-encoded file data
to task create or task reply in the attachments field of the payload.
task {"action": "reply", "payload": {
"taskId": "...",
"text": "Here's the diff",
"attachments": [{
"id": "att_001",
"filename": "schema.diff",
"mimeType": "text/plain",
"data": "<base64>"
}]
}}When you attach a file in the
dashboard, Claude receives the attachment ID and its link in the channel message. It calls task getAttachment to fetch it.
task {"action": "getAttachment", "payload": {
"attachmentId": "att_xyz",
"taskId": "0ZRgCquBZ7R",
"format": "base64"
}}
// format "url" (the default) returns the link instead
// returns: { filename, mimeType, data }Reading Task History
Claude can fetch the full message history of any task by calling task get with "includeConversation": true. This is useful when resuming a
long-running task or re-reading instructions after a context reset.
task {"action": "get", "payload": {
"taskId": "0ZRgCquBZ7R",
"includeConversation": true,
"limit": 20,
"cursor": 0 // paginate with the cursor from the previous call
}}
// Returns the task, plus its conversation:
{
id: "0ZRgCquBZ7R",
title: "...",
messages: [
{ role: "agent", text: "I'm about to delete 14k rows...", ts: "..." },
{ role: "human", text: "Approved, but use UUID...", ts: "..." }
],
total: 2,
cursor: null // null = no more pages
}