Randall Stillwell b2aff2045b feat(mcp): claim_task tool + register claim/complete pair

Pairs with the parallel complete_task commit. claim_task opens an
agent_runs row, flips status to in_progress only when it's safe
(ready/draft → in_progress, never overwriting a deliberate
blocked/done/in_progress), and returns the resolved workflow prompt
+ source level. Idempotent re-claim by the same actor returns the
existing run with reused=true and refreshes notes only — started_at
is sacred. Different-actor re-claim errors with ALREADY_CLAIMED
naming the existing actor and run id.

Tenancy fence: if the backlog item exists but in a different workspace
than the resolved handle, we refuse with "doesn't belong to workspace"
rather than 404. Prevents cross-tenant existence fishing.

All three writes (run insert + status flip + audit insert) happen in
one db.transaction() so a partial claim is unreachable.

tools/index.ts now registers both claim_task and complete_task.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-06-02 22:23:05 -05:00

1.9 KiB

Raw Blame History

kind	slug	title	plan_slug	status	priority	tenant_id	cursor_epic_id	updated_at
epic	mcp-claim-complete	MCP claim_task and complete_task — atomic lifecycle for agents	agent-coordination	ready	P2	global	null	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.

Task	Link
MCP claim_task tool	`./Task-mcp-claim-task-tool.md`
MCP complete_task tool	`./Task-mcp-complete-task-tool.md`

Dependencies

Depends on: Epic-task-as-runnable-unit (needs workflow_prompt and agent_runs).

Acceptance criteria

An agent can call claim_task({ workspace, backlogItemId }) and receive the effective workflow prompt + a runId.
An agent can call complete_task({ runId, outcome, tokens, notes }) to finalize.
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.

Proposed timeline

Phase	Window	Notes
claim_task	Day 1	Tool + idempotency.
complete_task	Day 2	Tool + run finalization.

1.9 KiB Raw Blame History