Skip to main content

Claims and edit checks

A claim records who holds a task, file or shared slot in a run. The agent works only after claim returns held: true. The edit hook checks supported edits against those holds. Claims are advisory unless the workspace selects enforce mode.

How a claim is decided​

CtrlB checks whether a task is finished before attempting a hold. To decide between competing claims, it writes first and then reads:

1. Check the key's state. Refuse a finished task unless reopen is requested.
2. Write a HOLD with a unique nonce, or REOPEN for a new round.
3. Wait for the configured claim interval, 20 ms by default.
4. Read live holds in time, agent and nonce order.
5. The first live hold wins. Withdraw a losing hold and record its refusal.

A live hold belongs to the current round, has not been released or finished, and has time left on its lease. Competing readers use the same ordering. Releases and finishes append rows; they do not erase the previous work.

The 20 ms interval is the default write-to-read wait. A refused claim does not wait in a queue for the holder to finish. Pick another free task or use peers to wait for an answer or handoff.

Resource keys​

Claims are decided on normalized keys, not the original resource text.

ResourceKey
File path containing / or a file extensionpath:<path>. Remove ./, resolve repeated slashes and .., and remove the cwd prefix. Case is kept.
Task or document namename:<name>, lower-cased with whitespace collapsed.
slot:<name>Shared non-file resource. The slot: prefix is case-sensitive.

./src//app.py and src/app.py are one key. /work/app/src/app.py with cwd set to /work/app is the same key. Use path:Makefile for a file with no extension; bare Makefile is treated as a name.

Register tasks before agents choose work. A task registration binds its exact name to files. A claim takes the task and those files together, or takes none. A claim of a registered task's file alone is refused with belongs_to_task. An unknown task name is refused with unknown_task. It includes suggestion only when there is one best match; otherwise the message lists registered names. This prevents two names for one task from becoming separate holds.

Leases and stalled holds​

The default lease is 600 seconds, or 10 minutes. The answer's lease_until is its expiry time. Claiming a key you already hold renews it. A crashed agent's hold expires unless another valid operation ends it first.

With holdRequired on, a checked edit of your file past half its lease renews the hold. A stalled hold can be taken over with takeover=true when its holder has made no progress on the key or attached files for stallAfterSeconds, 300 by default. Only another agent of that user can take it over. A successful takeover transfers the task and files in one write. Read its evidence, briefs and notes before continuing.

Finish and reopen tasks​

Call done on the task name after its test passes. Supply the command, exit code and a short result. It marks the task finished and releases its files. Later claims get finished_by until a claim uses reopen=true to start another round. Earlier rounds remain in the record.

Files and slots are never finished. release always returns them for later work. To return an unfinished task, use release with finished=false, or leave context with an open handoff.

Finishing a task through release(finished=true) is deprecated. Workspaces that require evidence refuse it. Use done.

Before an edit​

Claude Code checks Edit, Write, MultiEdit and NotebookEdit. Codex checks apply_patch, reading update, add, delete and move paths from the patch. The hook sends those paths to the run's check endpoint with the working directory.

ModeEffect when the check finds a conflict
offNo conflict action; the edit proceeds.
advisory (default)Add a note naming the holder and the claim to make; the edit proceeds.
enforceRefuse the edit with the reason and claim to make.

A refusal names one of these reasons. held applies in every enforce run. lapsed and unheld apply only when holdRequired is on, because edits then also require your own live hold:

ReasonMeaning and action
heldAnother agent holds the file. Pick other work.
lapsedYour lease expired. Claim again before editing.
unheldYou have no hold. Claim the file or its registered task.
stale_roundThe task was reopened after your earlier hold. Leave it to the current round's holder.

A file the agent holds itself is never a conflict. In advisory mode, the same reasons are notes.

The check gives up after two seconds. Errors allow the edit and go to ~/.ctrlb/hooks.log. Shell writes are outside the checked tools. Limits covers these boundaries.

Shared slots​

Claim a slot for a shared resource such as a local server, port, migration process or screenshot browser. Slots have a two-minute lease regardless of the normal lease setting. Renew before expiry if needed, then release the slot after use. Slot:devserver is a task name; use the lower-case slot: prefix.

For shared files such as REGISTRY.md, Claude Code automatically claims a slot with the file attached before an edit and releases it afterward. CTRLB_AUTO_SLOTS is a comma-separated list of relative paths, default REGISTRY.md; empty turns this off. A definite answer naming another holder refuses the edit. A failed slot request allows the edit.

Codex has no hook after a patch, so it does not manage these slots automatically. Its agent must claim the slot with the file in paths, edit, then release the slot in the same turn. Relay tools describes the arguments.

Workspace settings​

Read settings through GET /ai/relay/settings. Changes use PUT /ai/relay/settings, require a signed-in user with relay.manage and the dataset grant, and replace the settings. A Model Context Protocol (MCP) key can read settings but cannot change them. Ask your CtrlB administrator to make changes.

SettingDefaultPurpose
sessionsDatasetagent_sessionsSessions dataset; paired Relay rows use _ctrlb_relay_<sessionsDataset>.
waitMs20Milliseconds between a hold write and the deciding read; default allowed range 1 to 1,000.
leaseSeconds600Normal hold lifetime; default allowed range 60 to 86,400 seconds.
enforceadvisoryEdit check mode.
holdRequiredfalseRequire a hold for checked edits, with refusal in enforce mode.
silentAfterSeconds120Idle time before a live run's agent is marked silent; range 10 to 86,400 seconds.
stallAfterSeconds300No-progress interval for stalled holds and tasks; range 10 to 86,400 seconds.
questionAfterSeconds300Age before an open question is flagged unanswered; range 10 to 86,400 seconds.
evidenceRequiredfalseRequire a test on task registration and a command on task completion.
witnessRequiredfalseWith evidence required, also require a hook witness. Codex has no witness.
staleContractstrueReport contract files edited after their contract text.

CTRLB_ENFORCE=off skips edit checks on one machine. CTRLB_OFF=1 turns all hooks off there. These are local hook overrides, not changes to workspace settings.