From 3.21.0, build-item can claim each story before it starts it, so two agents on two machines never build the same one. Claims live in DevStride or behind your own commands. Without a claims block nothing is claimed and nothing changes.

Key Value Default What it does
claims null, { "provider": "devstride" }, or { "commands": { "claim", "heartbeat", "release", "get"?, "list"? } }; both forms take an optional expiryMinutes absent: no claims provider: "devstride" uses the agent's own DevStride MCP connection; its user needs the MANAGE_AGENT_CLAIMS permission (API Keys group of its role). commands runs your own claim store: each command gets <kind> <key> and its options (claim: --purpose, --phase, --expiry, --takeover; heartbeat: --phase; release: --outcome; list: --kind), the session's identity in CLAIM_HOLDER (never on the command line), and answers with a verdict on stdout's first line (WON, LOST, OK, NOT HOLDER, ABSENT, FORBIDDEN, UNREACHABLE, ERROR) and exit 0 won or ok, 2 lost, 4 not the holder, 1 anything else. Giving both forms, an unknown provider or a missing command is a config error.
claims.expiryMinutes { "<kind>": minutes }, e.g. { "story": 240 } story 240, release-train 30; any other kind, the server's default How long a claim lives without a heartbeat. A value outside 1 to 1440 is a warning and the default stands. The release permit's own claim is not set here: it lasts release.clearance.staleMinutes.

How the loop uses them:

  • Selection. The chosen story is claimed before it moves to In Progress. A story another live agent holds is skipped for the next candidate, and the loop says who holds it. A story you named, or the one a session resumes, stops instead, naming the holder's machine and session and since when. An expired claim is taken over. Your own earlier session (after a restart or /clear) counts as another holder: wait out the expiry, or the owner releases the claim.
  • While building. Each step and build phase renews the claim. A phase longer than the expiry lets the claim lapse, unless the repository's presence command renews it while the session is active; the next renewal claims it again if it is free. If another agent took the story after it lapsed, the loop stops and names that agent.
  • Finishing. Completion, whether the story is Done or has landed on an integration branch or the train, releases the claim with outcome done. A stop releases nothing itself: the claim expires, or a presence command releases it when the session ends, so a person can resume the story without a takeover.
  • The record. From 3.43.0 every claim names its machine and session the same way: the machine is DEVSTRIDE_MACHINE_NAME when your machine setup sets it, else the host name without .local, lower-cased with other characters turned to hyphens; the session name is Claude Code's own name for the session, else DEVSTRIDE_SESSION. Release clearance and session presence use the same machine name.
  • When claims are unavailable — the server has no claim tools yet, the key lacks the permission, or DevStride cannot be reached — the loop carries on without claims and says so once per session. A claims outage never stops delivery.
  • Hotfixes never claim, and a claim is a speed bump, not a lock: a person or an older plugin that never claims can still move the item.

The full contract is skills/build-item/references/story-claims.md in the plugin repository.