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
createTask. The task is queued and visible in the dashboard. The agent should immediately call updateTaskStatus("ongoing") when it starts working on it.
updateTaskStatus("completed"). For human-assigned tasks, the human marks it complete from the dashboard. The task moves to the completed section.
updateTaskStatus("rejected") if it can't complete the work. A reply explaining why is good practice.
Creating Tasks (from Claude)
Claude calls createTask whenever it needs human input. A well-formed task includes:
createTask({
title: "Approve: Delete stale user sessions older than 90 days",
body: `I'm about to run this migration:
DELETE FROM user_sessions WHERE created_at < NOW() - INTERVAL '90 days';
Estimated rows affected: ~14,000
This is irreversible. Approve to proceed?`,
assignee: "human"
})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 the reply MCP tool — 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 createTask or reply via the attachments parameter.
reply({
chat_id: "...",
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 in the channel message. It calls downloadAttachment to fetch it.
downloadAttachment({
attachment_id: "att_xyz"
})
// returns: { data, filename, mimeType }Reading Task History
Claude can fetch the full message history of any task using getTaskMessages. This is useful when resuming a long-running task or re-reading instructions after a context reset.
getTaskMessages({
task_id: "0ZRgCquBZ7R",
limit: 20,
cursor: null // paginate with cursor from previous call
})
// Returns:
{
messages: [
{ role: "agent", text: "I'm about to delete 14k rows...", ts: "..." },
{ role: "human", text: "Approved, but use UUID...", ts: "..." }
],
nextCursor: null // null = no more pages
}