taskgraph-execute-work

name	taskgraph-execute-work
description	Select, claim, execute, and report Taskgraph work through the MCP. Use when an agent needs the next ready item, a bounded execution context, claim lease handling, progress notes, completion, failure, or a blocker report.

Taskgraph Execute Work

Use the Taskgraph MCP as the work queue. Claim one ready action, gather its context, do the work, keep the claim alive when needed, and report the outcome.

Start a work cycle

1. Call tg_peek_next with the smallest useful scope and a few alternatives and blocked examples.
2. If a suitable item is selected, call tg_claim_next with the same scope, expected_candidate_id set to the selected ID, a lease, and a new idempotency_key.
3. If the candidate changed, peek again. Do not claim a different item silently.
4. Call tg_context_bundle for the claimed item. The current server accepts a direct ref; it also accepts source.item as a fallback.
5. Do the implementation or other work outside the MCP, within the user's allowed workspace.

Example claim:

{
  "scope": {"under": "project/compiler-rewrite"},
  "lease_seconds": 1800,
  "expected_candidate_id": "<id from tg_peek_next>",
  "idempotency_key": "claim-<stable attempt id>"
}

Reuse the same idempotency key when retrying the same claim call. Never reuse it for a new claim attempt.

Manage the lease

Keep the claim ID and token private. Before renew_after, call tg_manage_claim with action: "renew" and lease_seconds. When work ends or you cannot continue, call it with action: "release" when the claim should end without a status change.

If the agent may stop before the lease ends, release the claim. If the process fails, let the lease expire only when no safe release call is possible.

Record useful progress

Use tg_record_entry on the item for durable findings, decisions, notes, or comments. The current server accepts ref, entry_type, and body; valid entry types include note, finding, decision, comment, and completion_summary.

Record a short decision before a major change and a completion summary before reporting success. Do not paste claim tokens into entries.

Report the outcome

Before completion, fetch the current item. If acceptance criteria remain pending, use tg_patch_item with the current version to mark them met or waived with a reason.

Call tg_report_work with ref, status, and a clear reason:

• completed marks the item done and ends its active claim.
• failed marks it failed. Include the cause and what remains.
• unable leaves it open and ends the claim. State the exact blocker and next action.
• open leaves it open and can be used for a normal status report.
• done is accepted as a direct status value, but prefer completed for a work outcome.

Use a non-empty reason for failed, unable, skipped, cancelled, or acceptance exceptions. If a hard dependency blocks the item, call tg_explain_blocked and report the returned reason rather than guessing.

After reporting, fetch the item again and inspect any newly ready work. Parent containers may roll up to done when all children finish.

Recover from errors

• NO_READY_ITEM: inspect blocked_examples from tg_peek_next, then use tg_explain_blocked on a useful candidate.
• CANDIDATE_CHANGED: peek again and decide whether to claim the new candidate.
• CLAIM_CONFLICT: do not retry blindly; inspect the item and queue.
• AGENT_CLAIM_LIMIT: release or finish an existing claim first.
• VERSION_CONFLICT: fetch the item, review the new version, and apply only still-valid updates.
• ACCEPTANCE_INCOMPLETE: update or waive pending criteria with a reason before retrying completion.

If a strict MCP client rejects arguments for tg_patch_item or tg_record_entry, report that the current server advertises an empty input schema for that handler. Do not bypass the MCP with direct database writes.