title: MCP claim_task and complete_task — atomic lifecycle for agents
plan_slug: agent-coordination
status: ready
priority: P2
tenant_id: global
cursor_epic_id: null
updated_at: "2026-06-01"
---
# Epic objective
Add two MCP tools that give a coding agent a shaped lifecycle for a task: `claim_task` (status flip + open `agent_runs` row + return effective workflow prompt) and `complete_task` (status flip + close `agent_runs` row with outcome + tokens).
These replace the current freeform composition where an agent has to call `update_object` repeatedly and pray.
## In scope / out of scope
**In scope**
- New MCP tools `claim_task` and `complete_task` with zod schemas.
- Idempotency rules (don't double-claim).
- Integration with the `agent_runs` table from the previous epic.
**Out of scope**
- A long-running orchestrator (deferred epic).
- A `pause_task` / `resume_task` tool. Resist; you can model that with two `complete_task` calls (`cancelled` + a new claim) until evidence demands it.
- [x] An agent can call `claim_task({ workspace, backlogItemId })` and receive the effective workflow prompt + a `runId`.
- [x] An agent can call `complete_task({ runId, outcome, tokens, notes })` to finalize.
- [x] Double-claim of the same task by the same actor returns the existing open run; by a different actor returns an explicit `ALREADY_CLAIMED` error naming the existing actor and run id.
