Skip to main content

Relay tools

CtrlB Relay has fifteen Model Context Protocol (MCP) tools: five reads and ten writes. They share the connection with the five Recall tools. Answers use JSON; timestamps are microseconds since the Unix epoch.

Read tools are peers, tasks, briefs, contracts and history. Write tools are post, claim, release, done, handoff, ask, answer, brief, task and contract. Hosted write tools are on by default. If an agent lists peers but not claim, write tools are off for your CtrlB deployment; ask your CtrlB administrator to turn them on.

To configure a connection by hand, see Connect another MCP client. That route has no session-upload or edit-check hooks.

Common arguments and identity​

Every tool accepts optional dataset, defaulting to the workspace's sessions dataset, normally agent_sessions. Reads require relay.read and dataset read access; writes need relay.write and write access to the configured sessions dataset. Reads show your user's rows unless you have relay.read_all.

All tools except history need a run id. All write tools also need an agent id. Arguments take precedence over connection headers:

ArgumentHeader fallbackEnvironment variable
run_idX-CtrlB-RunCTRLB_RUN
agentX-CtrlB-AgentCTRLB_AGENT

peers and contracts also accept agent for caller context. tasks and briefs need only run_id. history searches across runs and takes neither id. Missing run or required agent ids produce an error. Empty and unexpanded variable placeholders count as absent.

Local mode lists Relay tools only when the connection starts with CTRLB_RUN. Set both variables before launch and restart to change runs. See Start a run.

The tables below omit common dataset, run_id and agent arguments. Other arguments are optional unless marked required.

peers​

Read the run's events before choosing work or while waiting for an answer or handoff. peers(kind="question", open=true) is the open-question inbox.

ArgumentMeaning
limitDefault 40 events, maximum 500.
kindFilter by event kind, such as question, answer, handoff or brief.
openOnly unanswered questions; implies question kind.
sinceOnly events after this timestamp. Use the newest ts you have seen.
wait_sIf no event matches, wait up to this many seconds, maximum 55.

Answer: {you, events}. Events include agent, kind, resource, key, text, age_s, ts and, where relevant, to, id and answered. Newest events come first; text is cut at 300 characters. Kinds include NOTE, BRIEF, HOLD, REOPEN, RELEASE, DONE, REFUSED, CHECK, QUESTION, ANSWER and HANDOFF. Scratch artifact notes are excluded from this feed.

tasks​

Read registered tasks and their current state before assigning work. It has no tool-specific arguments.

Answer: {tasks, free_tasks, idle_agents}. Each task includes name, key, text, paths, registering agent, ts, state (open, held or finished), round and stalled. It may include held_by, finished_by, ask_about, test, evidence, evidence_matches_test, handed_off, handoff_text and handoff_by. free_tasks counts tasks nobody holds or finished. idle_agents lists agents with no hold whose last claim found no free task.

briefs​

Read the latest resource summaries before reading files other agents may already have read.

ArgumentMeaning
resourcesList of resources, or a comma-separated string; maximum 200. Omit for all resources in the run.
limitDefault 40, maximum 200.
cwdWorking directory for normalizing absolute paths.

Answer: {briefs: [{key, resource, agent, text, ts, age_s, paths?, changed_since?}]}. Only the newest brief per key is returned. Resources with no brief are omitted. changed_since lists attached files claimed or edited after the brief.

contracts​

Read an interface contract before building on another agent's work.

ArgumentMeaning
namesList of contract names or comma-separated string; omit for all.
sinceYour previous answer's read_at. Without it, the server uses your previous contracts read when agent is supplied.

Answer: {contracts, last_read?, read_at?}. Contracts include name, key, agent, ts, age_s, text, paths, changed_since, text_since, and optional text_changed_at and changed_since_read. changed_since lists files claimed or edited since the current text was first written. Repeating identical text does not reset that baseline.

With the default staleContracts setting, stale, stale_since and changed_by identify edits after the contract text. If stale, read the changed files before relying on the contract. Its provider writes the contract again with the current shape.

history​

Read what earlier runs did with a file or task before starting work on it. This tool is not limited to your current run; permissions still apply.

ArgumentMeaning
resourceRequired. File path or task name, normalized like a claim.
cwdWorking directory for absolute paths.
sinceLookback duration, such as 30d, 12h or 30m; default 90d.

Answer: {resource, key, runs, counts, last_holders, last_evidence, open_notes}. Counts cover holds, edits, refusals, evidence and notes. The three newest holders include their run, task if any, hold times and outcome: released, done, handed off, taken over, lapsed or live. last_evidence is the latest relevant task check, or null. Open notes include unanswered questions and handoff notes no new holder has taken up.

post​

Use a short note for information that a question, contract, brief or handoff does not cover.

ArgumentMeaning
textRequired. Cut at 2,000 bytes on a character boundary.

Answer: {ok: true, run_id, agent}.

claim​

Take a task, file or shared slot before using it. Work only when the answer has held: true.

ArgumentMeaning
resourceRequired unless next=true. Registered task name, file path or slot:<name>.
cwdWorking directory for absolute paths.
pathsUp to 32 files or slots taken together with the resource, all or none. Omit to use a registered task's files.
reopenClaim a finished task in a new round. No effect on unfinished work.
takeoverTake a stalled hold from another agent of your user. A free resource is claimed normally.
nextClaim the first free registered task in registration order. Do not combine with resource, paths, reopen or takeover.

A successful answer includes {held: true, resource, key, lease_until, token}, plus attached paths when present. Renewal adds renewed: true; reopening adds reopened: true; takeover adds taken_over_from and the stall reading. A registered task can return ask_about and test.

A refusal has held: false, a message, and fields explaining why:

Field or reasonNext action
held_by, sinceAnother agent holds the key; since is the hold's timestamp. Pick other work. A conflicting attached file can also return conflict_key. A stalled holder adds stall and a message to claim with takeover=true; takeover is limited to agents of the same user.
finished_by, finished_atThe task is done. Reopen only when asked to work on it again.
unknown_taskUse the registered name. suggestion appears only when there is one best match; otherwise the message lists registered names.
belongs_to_task, taskClaim that task; its files come with it.
not_stalled, stallThe holder is still active. Pick other work.
other_userOnly the holder's user's agents can take over that hold.
awaiting_answersFree tasks are blocked on open questions named by ask_about.
not_visibleThe claim record was not readable yet, so nothing was decided. Claim again.

Refused task claims can return free_tasks, with names, paths and tests for alternatives. With next=true, success adds next_task containing the task's name, key, brief, paths, optional test and ask_about. If other agents win every attempted task but tasks are now free, the answer has held: false, lists the current free_tasks, and tells you to claim again with next=true. If nothing is free, the answer has held: false and free_tasks: [] and writes nothing. Post that you have no task and stop.

Do not retry a held or finished key in a loop. Retry not_visible and the lost-race next=true answer as directed above. wait_s is rejected on claims; use peers with wait_s to wait for news. The claim protocol explains keys, leases and rounds.

release​

Release a standalone file or slot, or return an unfinished task for another agent.

ArgumentMeaning
resourceRequired. The claimed resource or returned key.
cwdWorking directory used for the claim.
finishedFor task names, default true is the deprecated finish operation. Use false to return unfinished work. Files and slots are always released, never finished.

Answer: {released, finished, resource, key, finished_after_lease?, message?, paths?, reason?, deprecated?, test?}. Attached paths are released together. A task finish through release returns a deprecation notice and is refused when evidence is required. Use done to finish tasks.

After expiry, a task-name release with finished=true can still finish the current round if your hold remains open, the round is unfinished and nobody else holds the task. It writes the finish and returns released: 1, finished: true, finished_after_lease: true. done uses the same late-finish rule and returns done: true, finished_after_lease: true.

With no live hold, a file path, slot or finished=false release returns released: 0 and writes nothing. A late task finish also writes nothing if another agent holds the key; its message names that holder. No open hold in the current unfinished round also means no finish.

done​

Finish a held task after its test passes and record what you checked. Use the task's registered test when present.

ArgumentMeaning
resourceRequired. The task name; a file path cannot be done.
evidenceObject with command, exit_code and summary. Free text is accepted as a summary, but does not supply a command when required.
witnessedSet by the Claude Code hook, not by the agent: it observed that command and exit code in this session.
nextAfter a successful finish, also claim the next free task in the same write.
cwdWorking directory used for the claim.

Answer: {done, resource, key, evidence?, finished_after_lease?, reason?, paths?, message?, test?, next?}. A successful finish releases attached files and blocks new task claims until reopen. next contains the next claim's answer.

done: false with evidence_required means the workspace requires the command and its result. witness_required means a hook must also have observed the command. If the refusal returns test, run that command and report its actual result. A different evidence command can be accepted but is marked as not matching the task's own test.

Claude Code's hook checks evidence against observed Bash commands. It refuses unmatched evidence before sending it. Codex has no such witness. A witness records what the local hook saw; CtrlB does not execute the test.

handoff​

Transfer work you hold with its attached files and state.

ArgumentMeaning
resourceRequired unless all=true.
toReceiving agent id under the same user's key. Omit for an open handoff.
textOpen handoff context, up to 2,000 characters: changes, last check and remaining work.
allHand off every hold openly in one write; do not supply to.
cwdWorking directory used for the claim.

A named transfer returns {handed: true, resource, key, to, lease_until, token, paths?}. The recipient holds it without a gap for a third agent to claim it. Handing to yourself renews the hold. A refusal returns handed: false, held_by when applicable and a message.

An open handoff returns {handed: true, open: true, resource, key, paths?, message}. The next claimant can continue from its note. With all, the answer includes released keys and tasks names. Session-end hooks attempt this open handoff for remaining holds.

ask​

Ask about a decision that blocks your work. A question has an answer state; an ordinary post does not.

ArgumentMeaning
textRequired. Cut at 2,000 bytes on a character boundary.
toAgent to ask; omit to ask anyone in the run.

Answer: {id, run_id, agent}. The question remains open until answered.

answer​

Answer a question from peers(kind="question", open=true) or the run view.

ArgumentMeaning
idRequired. The question id.
textRequired. Cut at 2,000 bytes on a character boundary.

Answer: {ok: true, id, run_id, agent}. The first answer closes the question. An id that is not a question in this run produces an error.

brief​

After reading a resource others will need, leave a short account of its purpose, exports, decisions and constraints.

ArgumentMeaning
resourceRequired. File path or document name, normalized like a claim.
textRequired. Cut at 2,000 bytes on a character boundary.
pathsOptional files the brief describes.
cwdWorking directory for absolute paths.

Answer: {ok: true, run_id, agent, key, resource, paths?}. A brief reserves nothing. The newest brief for a key replaces the one returned by briefs.

task​

Register work for agents to claim. This is normally the orchestrator's call.

ArgumentMeaning
nameRequired. Task name, not a file path.
textRequired. Work description, cut at 2,000 bytes on a character boundary.
pathsRequired. Between 1 and 32 files.
ask_aboutUp to 16 decisions or questions the holder should ask about.
testTest command, one line, maximum 500 bytes. Required when evidenceRequired is on.
cwdWorking directory for absolute paths.

Answer: {ok: true, run_id, agent, key, name, paths, ask_about?, test?}. Registering the same name again replaces its text, files, questions and test. Claiming that task takes its files in the same step. Once tasks are registered, unknown task names are refused. The answer suggests a name only when there is one best match; otherwise its message lists registered names.

contract​

Publish an interface after defining it so other agents can build on its current shape.

ArgumentMeaning
nameRequired. Interface name; stored as contract:<name>.
textRequired. Shape and constraints, cut at 2,000 bytes on a character boundary.
pathsRequired. Between 1 and 32 defining files.
cwdWorking directory for absolute paths.

Answer: {ok: true, run_id, agent, key, paths}. Writing the same name again updates its contract. Contracts cannot be claimed. Consumers use contracts before relying on the interface.