claim_task
CLAIMS a task ATOMICALLY, so that no other agent of the queue takes it at the same time: it goes from "to do" to "in progress" in ONE conditional write, and the claim is signed (agentLabel, otherwise the name of your key; and the time). This is the action that replaces update_task({ status: "doing" }), which does not stop anyone from taking the same task. taskId omitted = the FIRST ready task of the queue (priority, then position) — if another agent takes it in the same second, you get the next one. Response: { claimed: true, task } — or { claimed: false, reason, message }; a refusal is never reported as a success. reason: not-found · already-claimed (with heldBy/heldAt when the claim was signed, null otherwise — a task set to "in progress" by hand has no holder) · done · archived · blocked ("blocked" status set by hand) · open-dependencies (with openDependencies) · arbitrage (an arbitration, a question to decide, is not work to claim: it follows its update_task.arbitrageAction cycle) · awaiting-validation / awaiting-approval (the task carries the LABEL a-valider / a-approuver: a human must validate or approve — it can neither be claimed nor reclaimed, EVEN if it is already "in progress"; these labels are not removed to claim the task: they are set and lifted by a human, and a status change through update_task does not count as a claim) · awaiting-triage (the task carries the LABEL etat-tri:a-trier: awaiting triage — neither claimable nor listed by executable; the triage, run according to the project flow (by the human or by the designated agent), replaces the label with etat-tri:trie; evaluated AFTER done and already-claimed, which keep their reason) · no-ready-task (without taskId: no ready task) · conflict (the row changed during the claim: a re-read, then a new attempt, settle it) · write-locked (agent writes are LOCKED on this block or on this project for this account: the message says what to unlock — without taskId, the tasks of a locked view are skipped). A refusal writes NOTHING. Claiming a CHILD task of an arbitration already DECIDED (step arbitre) STARTS it in your name — startedBy/startedAt, and startedArbitrages in the response, absent otherwise: carry out a decision through CHILD tasks of the arbitration, not through tasks that DEPEND on it (a dependent task cannot be claimed before its closure). update_task({ arbitrageAction: { type: "start" } }) remains allowed. A claimed task is no longer in list_tasks({ executable: true }). To hand a task back: update_task({ status }). A task marked executor: "human" is refused with human-task (evaluated AFTER done and already-claimed) and is left out of executable: an agent does not take a human's task. LEASE: a claim is a LEASE of 15 minutes. The response carries claimToken (a SECRET that identifies you as the holder and stays out of every written text), leaseUntil (the deadline) and leaseMinutes. Once the deadline has passed, another agent MAY take over the task: an "in progress" task whose lease has expired is RECLAIMABLE — claim_task takes it over (response claimed: true with reclaimed: { reason: "lease-expired", previousHolder, expiredAt }: this is a TAKEOVER, not a refusal) and list_tasks({ executable: true }) lists it. already-claimed then also carries leaseUntil. A task set to "in progress" by hand (without a signed claim) has no deadline. RENEW with renew_claim (at least once per lease, DECLARING your progress). During the lease, any agent write on the task (update_task, archive_task, unarchive_task) requires claimToken: without it CLAIM_HELD, with an expired token CLAIM_LOST. The token does NOT cover the tracking of the implementation plan (impl-2026-10-* tasks), which this tool never "claims": no claim, no token.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | No | The task to CLAIM. Omitted, the FIRST ready task of the queue is claimed (same definition as `list_tasks({ executable: true })`, by priority then position) — the "my next task" action. | |
| agentLabel | No | The label that SIGNS the claim ("agent-doc", "worker-2"…) — it is what another agent will read in the refusal "already claimed by …". Optional: omitted, the claim is signed with the NAME OF THE API KEY of the call (without a named key, in the chat for example, it stays without a label: `claimedBy: null`). Two agents of the same key therefore sign the same way: `agentLabel` serves to tell them apart as soon as several agents share a queue. | |
| expectedProjectId | No | UUID of the project targeted by THIS call. ACTUALLY targets this project instead of the session project. Refused without changing anything if access is not granted. |