Claim an issue
claim_issueClaim one specific issue by id (instead of letting next_issue pick). Fails if it's already held (active lease), blocked, non-work (work:false — tracking containers aren't claimable), or in a status that isn't todo, doing or review. A review IS claimable, and claiming one is how a reviewer takes the work (RTSC-257): the issue stays in review, and accepting it later with save_issue status:"done" is REFUSED unless you hold that lease (CLAIM_REQUIRED). You cannot claim the review of work you submitted yourself (AUTHOR_CANNOT_REVIEW). Returns a claim_token. ALSO THE RESUME DOOR: if you were restarted or /resume'd, your client may have started a NEW session, in which case the server sees a different session holding your issue and done fails with CLAIM_MISMATCH. You don't have to wait out the lease or give the work back — call this with the claimToken you were given before the restart and the lease moves onto your new session (a fresh token, rebound: true, status and progress untouched; if THIS session already held it, nothing moves, the same token comes back with renewedOnly: true, and it costs a heartbeat). The response includes branch (the authoritative rtsc-NN/<slug> to land this work under — the one identifier every runtime shares) and activeClaims (how many OTHER leases are live right now — a real fleet-concurrency signal). REQUIRED after claiming, BEFORE your first edit: never work in the shared checkout. Create an isolated git worktree for branch and work ONLY there — e.g. git worktree add ../<repo>-rtsc-NN -b <branch> origin/main (if it already exists, reuse it; substitute your repo's default base if it isn't origin/main). Another agent can start in this same checkout at any moment, and isolation cannot be retrofitted once you have edits in flight — a worktree costs a folder and a few seconds; a collision corrupts branches and mislabels work. Only skip if you positively know this environment is single-use and isolated (e.g. an ephemeral per-task container) — and even then a worktree is harmless. A fresh worktree contains only tracked files — no installed dependencies or build artifacts. Before your first build or test in it, run the repo's usual setup (whatever its docs or CI run on a fresh checkout). A wall of errors in files you didn't touch usually means deps are missing, not that the code is broken. Your claim is a LEASE, not a permanent assignment: it expires 30 minutes after you take it behind the retasc mcp-proxy and 2 hours after with no proxy (the response carries the exact claimExpiresAt). Behind the retasc mcp-proxy, ONLY heartbeat and checkpoint renew it — nothing else does, not comments, not status updates, not reading the issue. With NO proxy, if your client echoes the Mcp-Session-Id we hand you at initialize, your own calls renew instead (RTSC-858): every call renews every claim THIS session took, a read as much as a write. Each renewal is a FULL reset to the lease's length from that moment, so one call is enough however little was left. Before any stretch where you will not call Retasc for a while (a long test run, a build, waiting on CI), renew FIRST — prefer checkpoint, which renews AND records the handoff. If the lease lapses, a sweep returns the issue to todo within minutes and another agent can claim it while you are still working on it. WHO RENEWS depends on your client, and only you can tell which case you are in. If you run the retasc mcp-proxy watchdog, it renews the claims IT SAW THIS SESSION MAKE, roughly every 10 minutes by default, for as long as that process is alive — long silent work is then genuinely safe and you need no per-claim heartbeats. Nothing renews a claim the proxy did not see (made in another terminal, over direct HTTP MCP, or by a previous proxy before a restart), and nothing renews once the proxy stops: those run on their bare TTL and are yours to renew. With no watchdog and no session id echoed, every renewal is yours. With no watchdog but a session id, your own calls carry it, right up until your client RECONNECTS, which starts a new session and stops renewal for claims taken under the old one; claim_issue with your claimToken moves them onto the new session and renewal resumes. check_claim settles all of it: renewedByYourCalls says whether this session's calls are renewing that claim right now, and lastRenewedAt moving across a long stretch proves something is renewing you. If this call is refused for billing (BILLING_INACTIVE or MONTHLY_CAP_REACHED), the response carries tellHuman, a ready-to-relay sentence: PASS IT TO YOUR HUMAN. You cannot fix it yourself — only an owner can — so do NOT absorb the refusal and continue with read-only work as if the session were healthy; every value-bearing write will keep failing until they act.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| claimToken | No | ONLY to resume your own claim after a restart: the claim_token from before, which moves that live lease onto this session. Omit when claiming new work. It proves you are the same agent continuing — a session that never held the issue doesn't have it, and it can never move a claim to a different agent. | |
| identifier | Yes | e.g. XEN-12 |