tasks_claim
Atomically claim a task for a session, moving it to in_progress with a renewable lease. Prevents duplicate work; refused claims name the cause (already claimed, blocked, gated, or closed).
Instructions
Atomically claim a task for the current session, moving it to in_progress with a lease: 900 seconds unless lease_seconds sets another, at most 14400 seconds (4 hours). While its lease is live a claim keeps its session live: the idle reaper does not end a session that holds one, however long its work goes quiet. A refused claim names its cause: held by another live claim ('task already claimed'), waiting on unfinished dependencies ('task blocked', naming the blockers -- finish those first), waiting on people ('task gated': a task of kind gate is never claimed, and a step whose own gate is open waits until it is cleared), or already done/dropped ('task closed'). Re-claiming a task you already hold refreshes (heartbeats) the lease; a task whose lease has expired can be reclaimed, and a session that loses a claim that way, or by the owner's release, is told once, in its next Seamless tool result or prompt. Release it with tasks_release or by closing it (tasks_update done/dropped); session_end releases all of a session's claims.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"id": "<id>"
},
"name": "tasks_claim"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | task id to claim | |
| session | No | the acting agent's session: the cc/<id> or cx/<id> on your briefing's 'Seam session' line, another session name, or a session ULID. Defaults to this connection's session -- bound automatically for Claude Code and Codex agents -- then a sole active ambient. Pass it when a call reports the agent as ambiguous: the bare call then fails rather than guesses. | |
| session_id | No | the acting agent's session ULID; takes precedence over session and the bound session | |
| lease_seconds | No | lease duration in seconds before the claim lapses and the task becomes reclaimable (default 900, at most 14400) |