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.
| Resource | Key |
|---|---|
File path containing / or a file extension | path:<path>. Remove ./, resolve repeated slashes and .., and remove the cwd prefix. Case is kept. |
| Task or document name | name:<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.
| Mode | Effect when the check finds a conflict |
|---|---|
off | No conflict action; the edit proceeds. |
advisory (default) | Add a note naming the holder and the claim to make; the edit proceeds. |
enforce | Refuse 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:
| Reason | Meaning and action |
|---|---|
held | Another agent holds the file. Pick other work. |
lapsed | Your lease expired. Claim again before editing. |
unheld | You have no hold. Claim the file or its registered task. |
stale_round | The 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.
| Setting | Default | Purpose |
|---|---|---|
sessionsDataset | agent_sessions | Sessions dataset; paired Relay rows use _ctrlb_relay_<sessionsDataset>. |
waitMs | 20 | Milliseconds between a hold write and the deciding read; default allowed range 1 to 1,000. |
leaseSeconds | 600 | Normal hold lifetime; default allowed range 60 to 86,400 seconds. |
enforce | advisory | Edit check mode. |
holdRequired | false | Require a hold for checked edits, with refusal in enforce mode. |
silentAfterSeconds | 120 | Idle time before a live run's agent is marked silent; range 10 to 86,400 seconds. |
stallAfterSeconds | 300 | No-progress interval for stalled holds and tasks; range 10 to 86,400 seconds. |
questionAfterSeconds | 300 | Age before an open question is flagged unanswered; range 10 to 86,400 seconds. |
evidenceRequired | false | Require a test on task registration and a command on task completion. |
witnessRequired | false | With evidence required, also require a hook witness. Codex has no witness. |
staleContracts | true | Report 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.