Implementation tools

The local implementation lifecycle

Read research and evidence, inspect your local project, and agree on a plan before claiming work. A task holds an immutable source snapshot; each claim creates a run with its own accepted plan and attempt number.

list_implementation_tasks and get_implementation_task require tasks:read. Starting, reporting, and releasing require implementation:write and a current owner, admin, or editor role.

Examples use illustrative IDs. Replace them with IDs returned by your workspace.

list_implementation_tasks

{"researchId":"11111111-1111-4111-8111-111111111111","limit":10}

Returns {items, nextCursor}. First it lists saved tasks, then unclaimed recommendations from the latest Action Backlog reports. Saved task entries have id; recommendations have candidate. Do not assume every item has a task ID.

{
  "items": [{
    "candidate": {
      "researchId":"11111111-1111-4111-8111-111111111111",
      "artifactId":"artifact-example",
      "version":3,
      "opportunityId":"opportunity-example",
      "actionIndex":0
    },
    "sourceKind":"REPORT_RECOMMENDATION",
    "sourceVersion":3,
    "status":"AVAILABLE",
    "snapshot": {
      "title":"Make team invitations easier to discover",
      "problem":"Teams struggle to find invitation setup",
      "objective":"Make team invitations easier to discover",
      "rationale":"A recurring barrier appears in setup feedback",
      "changePlan":["Make team invitations easier to discover"],
      "acceptanceCriteria":["Verify the linked research problem is addressed"],
      "tests":["Run relevant implementation tests"],
      "nonGoals":["Do not treat client-reported results as independently verified"],
      "sources":[{
        "kind":"MEANING_UNIT",
        "sourceId":"meaning-unit-example",
        "researchId":"11111111-1111-4111-8111-111111111111",
        "provenance":"REAL",
        "excerpt":"I could not find where to invite my team."
      }]
    }
  }],
  "nextCursor":null
}

Snapshots contain title, problem, objective, rationale, changePlan, acceptanceCriteria, tests, nonGoals, and sources. Report-generated snapshots include up to 49 supporting quotes plus an artifact source. Use get_evidence with the opportunity ID for the complete paginated source set.

An eligible recommendation must still match the current report version and have traceable evidence. The list has no status filter: inspect each item's status. Follow cursors until null, including when a page is empty.

get_implementation_task

Required argument: taskId, a UUID. Only saved tasks have IDs; a candidate becomes a saved task when claimed.

{"taskId":"33333333-3333-4333-8333-333333333333"}

Returns id, researchId (nullable), sourceKind (REPORT_RECOMMENDATION or ASKCLAW), sourceVersion, status, snapshot, createdAt, and updatedAt.

The following abbreviated response uses the snapshot fields shown in the list example:

{
  "id":"33333333-3333-4333-8333-333333333333",
  "researchId":"11111111-1111-4111-8111-111111111111",
  "sourceKind":"REPORT_RECOMMENDATION",
  "sourceVersion":3,
  "status":"AVAILABLE",
  "snapshot":{"title":"Make team invitations easier to discover"},
  "createdAt":"2026-10-12T10:00:00.000Z",
  "updatedAt":"2026-10-12T10:00:00.000Z"
}

Task statuses are AVAILABLE, IN_PROGRESS, COMPLETED_REPORTED, BLOCKED, and CANCELLED. The ASKCLAW source kind supports future producer integration; there is no public MCP publishing tool.

start_implementation

The candidate reference requires a research UUID, artifact ID and opportunity ID (each 1–200 characters), positive integer version, and zero-based integer actionIndex from 0–999. Pass exactly one of taskId or candidate.

Claim a saved task:

{
  "taskId":"33333333-3333-4333-8333-333333333333",
  "expectedVersion":3,
  "plan":["Inspect invitation navigation","Implement the agreed entry point","Run relevant tests"],
  "requestId":"44444444-4444-4444-8444-444444444444",
  "localTargetLabel":"Local web project"
}

To claim a report recommendation, replace taskId with its candidate object and use the returned sourceVersion as expectedVersion.

{
  "candidate":{
    "researchId":"11111111-1111-4111-8111-111111111111",
    "artifactId":"artifact-example",
    "version":3,
    "opportunityId":"opportunity-example",
    "actionIndex":0
  },
  "expectedVersion":3,
  "plan":["Inspect the local project, implement the agreed change, and run relevant tests"],
  "requestId":"77777777-7777-4777-8777-777777777777"
}

Both claim forms return a run:

{
  "id":"55555555-5555-4555-8555-555555555555",
  "taskId":"33333333-3333-4333-8333-333333333333",
  "researchId":"11111111-1111-4111-8111-111111111111",
  "title":"Make team invitations easier to discover",
  "status":"IN_PROGRESS",
  "attempt":1,
  "localTargetLabel":"Local web project",
  "plan":["Inspect invitation navigation","Implement the agreed entry point","Run relevant tests"],
  "result":{"status":"IN_PROGRESS","summary":"Implementation started","tests":[],"verification":"CLIENT_REPORTED"},
  "verification":"CLIENT_REPORTED",
  "createdAt":"2026-10-12T10:00:00.000Z",
  "updatedAt":"2026-10-12T10:00:00.000Z"
}

Save the returned id as your runId. The accepted plan remains separate from later reported results. Claiming records local work; it does not launch a coding agent or create a branch.

Only an AVAILABLE task can be claimed. Report-backed claims must still match the latest source report. Concurrent claims are exclusive. Retrying the same requestId, identical payload, user, and grant returns the existing run. Changing the payload or actor under that ID is a 409 conflict. Generate a new request ID for a new attempt.

report_implementation

{
  "runId":"55555555-5555-4555-8555-555555555555",
  "eventId":"66666666-6666-4666-8666-666666666666",
  "status":"COMPLETED_REPORTED",
  "summary":"Added the agreed invitation entry point.",
  "tests":["Invitation navigation tests: 4 passed"],
  "branch":"feat/invitation-entry",
  "commit":"abcdef1",
  "pullRequestUrl":"https://github.com/example/product/pull/42"
}

{
  "status":"COMPLETED_REPORTED",
  "summary":"Added the agreed invitation entry point.",
  "tests":["Invitation navigation tests: 4 passed"],
  "branch":"feat/invitation-entry",
  "commit":"abcdef1",
  "pullRequestUrl":"https://github.com/example/product/pull/42",
  "verification":"CLIENT_REPORTED"
}

The result echoes the report payload without runId or eventId and adds verification. Report only tests you actually ran; use an empty array and explain limitations when none ran. Optional branch, commit, and PR fields are supplied by the client.

Only the original claiming user and grant can report. Reauthenticating creates a new grant and does not transfer the claim. Each new report needs a new eventId; retry the same event with identical content after an ambiguous network failure. A changed payload under a reused ID conflicts. Identical accepted events can be replayed even after the run becomes terminal, while authorization remains valid.

IN_PROGRESS keeps the claim active. Other statuses end reporting for that attempt. COMPLETED_REPORTED completes the task as reported; BLOCKED blocks it; FAILED makes the run failed and the task blocked. A further new event against a terminal or released run is rejected.

release_implementation

{
  "runId":"55555555-5555-4555-8555-555555555555",
  "reason":"The previous client stopped; release before another agent retries."
}

Returns the same run-view shape as start_implementation, with status: "CANCELLED" and a client-reported cancellation result containing your reason. The task returns to AVAILABLE.

Abbreviated response:

{
  "id":"55555555-5555-4555-8555-555555555555",
  "taskId":"33333333-3333-4333-8333-333333333333",
  "status":"CANCELLED",
  "attempt":1,
  "result":{
    "status":"CANCELLED",
    "summary":"The previous client stopped; release before another agent retries.",
    "tests":[],
    "verification":"CLIENT_REPORTED"
  },
  "verification":"CLIENT_REPORTED"
}

A currently authorized owner, admin, or editor with write scope may release another client's claim, including a claim held by a revoked grant. Only the latest run for that task can be released, and only when its status is IN_PROGRESS, BLOCKED, or FAILED. Completed, already cancelled, and superseded runs cannot be released.

Release is an explicit takeover mechanism, not a timed lease. The server does not automatically expire an abandoned task claim. Release is not an idempotent write: repeating it after success returns a conflict. Stop or coordinate with the old local process before taking over; release changes Askdepth state but cannot terminate that process.

Fencing and safe recovery

“Fencing” means the old run can no longer accept new reports after release or a terminal result. A new claim gets a new run ID and a higher attempt number. The old client's token does not let it write into the new run.

Keep the accepted claim payload, request ID, and report event payloads until acknowledgments arrive. Retry identical start or report requests with the same IDs. On a source-version conflict, re-read the task and latest evidence before making a new plan. On an abandoned or revoked claim, explicitly release the latest eligible run and then claim the available task with a new request ID.

See errors and recovery for transport failures and limits.