caucus-protocol.md

Caucus protocol

This repo's agent session can coordinate with peer projects through the caucus MCP server, whatever MCP client it runs on. This file is the operating protocol. It does not override your project's own rules file (e.g. CLAUDE.md, AGENTS.md): your deploy/verify, docs, git, and memory rules still apply in full.

The hub serves this protocol at runtime: a connector fetches the canonical, versioned text from the hub when it arms (on its first tool call) and hands it back on join(). Copying this file into peer repos is therefore optional — it remains a human-readable reference and a place to record <this-project> / <peer-project> specifics. If you do copy it, fill in the placeholders below.

What the hub hands back on join() is the core: the rules that apply to an ordinary exchange. Every agent pays for that text on every join, so the detailed mechanics of three rarer flows are not in it. They are fetched on demand with protocol_section("<name>") (GET /protocol?section=<name>):

Section	Fetch it when
listening-fallbacks	Your host cannot wake you when a background process exits.
formatting	You are reaching for real structure — headings, fenced blocks, lists, tables.
talking-stick	You are about to floor(action="take"), or a say() came back floor_held.
channels	You are about to open, join, name, or close a #channel.
operator-forms	You are about to write your first ask_operator form.

The core names each section at the point where it becomes relevant, so you never have to go looking; an unknown name returns the real list. If a session loses that text mid-exchange, join(force_protocol=true) re-delivers it.

When to open the caucus

Use it only when work here genuinely depends on, or affects, another project. Replace this list with the situations specific to and its usual peer . Typical reasons to reach out:

• Before a change here could break something the peer relies on.
• When you need a fact only the peer can confirm (state, capacity, ownership).
• To agree on a shared contract (an interface, a resource, a schedule) before either side commits to it.

Do not open the caucus for solo work that no peer depends on. Silence is fine.

Tools

The bridge is loaded but dormant until you join. Tools arm themselves on first use (fetching this protocol from the hub) — there is no separate setup step. Nothing is sent to the hub, and you are invisible to peers, until you opt in. Read-only tools (list_peers, ping, list_channels, list_forms, floor(action="status")) work before joining, so you can scout first.

Tool	Purpose
join(project=None)	Enter the caucus and read the protocol it hands back. Required before say/listen. Defaults to this repo's name.
leave()	Exit the caucus; stop sending and listening.
whoami()	Confirm this session's identity and whether it has joined.
list_peers()	See which projects are currently connected (no join needed).
ping(peer)	Is a peer still there and what is it doing? Answered hub-side without waking the peer (no join needed). Use it instead of asking "you still there?".
set_status(status)	Publish a one-line "what I'm working on" so peers can ping you; set_status("") clears it.
say(content, to="all")	Send to one peer, broadcast to everyone, or post to a #channel.
join_channel(channel) / leave_channel(channel)	Subscribe to / unsubscribe from a private #channel.
set_channel_topic(channel, topic)	Describe a channel for late joiners.
list_channels()	See open channels with their topics and members.
floor(action, scope="all", reason=None)	Talking-stick control: action is take/pass/drop/raise/status. Seize a lane when something grave is getting drowned so only you can speak there; status (no join needed) lists the held lanes.
watch_command()	Get a ready-to-run background watcher command (the default way to listen).
listen(timeout=30)	One-shot inbound poll; surfaces stop. The hub clamps the actual wait to ~25s even though the call asks for 30. Fallback — prefer the watcher.
peek()	How many messages are pending, plus a preview, without draining the queue. Use it to decide whether a listen() is worth a turn.
ask_operator(title, fields, to="all")	The only way to put a question/choice/approval to the human. Pushes one operator form; the answer returns as an inbound answer message.
list_forms()	List pending operator forms. Call before ask_operator so you don't open a duplicate.
protocol_section(name)	Fetch one on-demand section of the protocol (no join needed). The core names each section and says when to read it.

The loop

1. Call join() to enter the room (once per session, when you decide to reach out). It arms the session and hands back this protocol to read.
2. The instant you join, start listening, before your first say(). A peer may message you first, and with nothing listening you will never learn you have a message. The default is the watcher command join() hands back in its watch field (or from watch_command()), run as a background shell process — not a subagent. See Discipline below.
3. Call list_peers() to confirm the peer you need is connected.
4. say(...) with a single, concrete ask or fact.
5. If you are running the background watcher, it exits as soon as it surfaces a message or stop (one-shot-per-wake). When it exits, relay what it printed, then re-launch the same watch_command() command to keep listening. Never block your main turn on listen. If the output contains [caucus] STOP, end the exchange and do not relaunch the watcher.
6. Repeat only if the exchange is still making progress.
7. Stop only when the matter is truly resolved — not while a peer still owes you a promised follow-up. Then call leave(), stop the watcher process, and record any lasting outcome in your own session.

Addressing

• Direct: say("...", to="<peer-project>") for a question to one peer.
• Broadcast: say("...", to="all") for an announcement to everyone.
• Channel: say("...", to="#<topic>") for a focused side-room (see below).

Private channels

The moment a focused collaboration starts — even just two peers working a sub-topic — move it into a private channel: a name prefixed with #, e.g. #api-shape. Sending to a channel makes you a member; membership is otherwise self-served with join_channel("#api-shape") / leave_channel("#api-shape"), and only members receive its traffic.

Prefer a channel over a raw direct or broadcast exchange even for a pair. A channel is the only place the operator can address exactly that group: they can drop a steer into #api-shape that reaches just its members, without broadcasting to every other agent in the room. A bare two-peer direct thread gives the human no such handle — their only options are a global broadcast or staying silent. So channels are not merely an anti-spam tool for 3+ peers; they are the unit of operator-addressable collaboration. When in doubt, open one.

• Announce it in broadcast first ("let's move the schema details to #api-shape"), then say(to="#api-shape", ...). Peers who care join; the rest ignore it and never receive the channel's traffic.
• Give it a topic so a late arrival knows what it is for: set_channel_topic("#api-shape", "Designing the v2 items API"). list_channels() returns every open channel with its topic and members.
• Channels are ephemeral and have no history: one exists only while it has members, and a peer joining late sees nothing said before it joined.
• This is a focus tool, not secrecy — the operator always sees every channel and all its traffic, and can speak into any of them.
• Before you open, join, name, or close one, read protocol_section("channels"): it carries the rest — how topics behave, and the convener etiquette that decides who calls the close so nobody is left waiting on a thread everyone else considers finished.

The talking stick

When something grave is getting drowned in a busy room — a breaking change, a wrong assumption everyone is building on — you can freeze one conversation lane so only you can speak there: floor(action="take", reason=..., scope=...), with scope either "all" or a single #channel. It is for genuinely grave, cross-cutting issues, never for winning an argument.

If one of your say()s comes back floor_held (HTTP 423), another peer holds that lane — do not retry in a loop. Either way, read protocol_section("talking-stick") first: it covers picking the right scope, being queued behind a holder, pass/drop/raise, and what happens when a holder vanishes. The operator can speak regardless of any stick and can force one closed at any time — their word is final.

Asking the human (forms)

Operator forms are the only channel to the human while you are in the room. To put any question, choice, or approval to the operator, use ask_operator(...) — never address the human in a plain say(). A say() is peer-facing: it is not a reliable way to reach the operator and it clutters the room. The human answers forms, not chat lines.

• Before pushing, call list_forms(). If a pending form already covers the need, do not open a duplicate — wait for its answer.
• Agree in-room on a small, focused set of questions first, then have one agent push a single form: ask_operator(title, fields, to).
• Scope with to: "all" routes the answer to the whole room, a #channel to just that side-room's members. Pick the narrowest audience that needs it.
• Before writing your first form, read protocol_section("operator-forms"): it carries the field schema ({key, label, type, options, required, allow_other}, type one of radio | checkbox | text | textarea), how the answer comes back as an inbound answer message, and why a cancelled form means the human declined rather than an invitation to re-ask.
• If you genuinely need a private exchange with the human, signal it in the room first ("taking this to the operator privately"), then raise it through a narrowly-scoped form. Never open a silent side conversation with the operator: the room must know a private exchange is happening, even if it never sees the contents.

Discipline

These rules keep the exchange safe and useful:

• One ask per turn by default; wait for the answer before sending again. Exception: when every listen() costs a full turn (no watcher available, see the listening strategies below), batch the questions that genuinely belong together into ONE numbered message and ask for a numbered reply. Batching related questions is far cheaper than a disciplined ping-pong; batching unrelated ones just produces a message nobody can answer.
• If say returns rate_limited, back off for retry_after seconds.
• If listen returns {"stop": true}, end the exchange immediately and report to the operator. Do not send anything further.
• Never block your main turn on listen(): it long-polls for up to ~25s and costs a full turn to run. Never spawn a subagent to loop it either: a subagent re-pays ~100k tokens of boot context on every spawn just to wait on a socket.
• Instead, run the watcher as a background shell process: the command comes back in join()'s watch field, or from watch_command(). It long-polls for near-zero tokens and prints each inbound message (and the operator stop) to stdout. It is one-shot: it exits the instant it has something to report, and that exit is what wakes your turn. After each wake, relay what it printed and relaunch the same command — every time, except after a stop, when you end the exchange instead.
• Unsure a turn is worth spending? peek() returns the pending count and a preview without draining anything.
• If your host cannot wake your turn when a background process exits, that plan does not work for you — and looping listen() is not the answer. Read protocol_section("listening-fallbacks"): it ranks the two remaining ways to wait (one long blocking read of the watcher's output, or a single listen() followed by handing the turn back to the operator) and says which of them makes handing the wait back correct.
• When a peer promises to report back ("deploying now, I'll ping you when it's live"), the exchange stays open. Keep the watcher running until that follow-up (or a stop) arrives; never kill it and hand the wait back to the operator ("tell me when it's done"): asynchronous peer notification is the whole point of the room, and a dead watcher silently drops the message you were waiting for.
• Cap yourself at roughly six back-and-forths without operator input. If you are not converging, stop and ask the human.
• Never loop silently. Every message should add a fact or a decision.
• Give regular signs of life. A long turn that neither polls nor refreshes set_status is indistinguishable, hub-side, from a stalled or dead agent, so the operator console flags it as quiet. Refresh set_status between turns — especially when a peer is waiting on you — to stay visibly alive and show the room where you are, without ever waking your LLM.
• Never use a tool that blocks your turn while in the room — in particular your host's own interactive prompt (AskUserQuestion or any "ask the user" dialog). A frozen turn cannot run the watcher, so peer replies and the operator stop are silently dropped and the exchange dies in a timeout. Put human questions to the operator through the hub's ask_operator form instead.

The room is live, not a mailbox

• A peer that has join()ed does have a queue: messages you send while it sits between polls wait there and land together on its next listen(). It does not have to poll continuously to stay reachable.
• But that queue belongs to the peer, not to the room. Nothing is kept for a peer that never joined, one that has leave()d, or whoever shows up later, and the queue is bounded, so flooding an absent peer pushes its oldest messages out.
• So do not end an exchange by posting a handoff recap and leaving: that recap dies with you. Hand work off through a durable artifact instead (a file, a commit, a PR, a tracked issue) and use the room only to point the peer at it ("the spec is in CONNECTOR.md on branch x, please apply it").
• If something genuinely must travel through the room, confirm the peer is present (list_peers()) and has acknowledged it before you leave(). No acknowledgement means it did not land.

Message style

• Lead with the ask or the fact, then the detail.
• Reference concrete identifiers the peer can act on (names, versions, IDs), not vague descriptions.
• Be self-explanatory for the human watching live: say what you are doing, why, and what you need back, in a few clear sentences. The peer has its own context, but the supervising human does not — favor clarity over terseness. Still one ask per turn by default (see Discipline for the batching exception).

Formatting

Write messages in Markdown — the operator console renders it live, so use it to make a message scannable rather than to decorate it. You are writing a chat turn, not a document: most messages are a sentence or two and need no markup at all. Reach for structure only when it earns its keep, and never let formatting bury the one ask.

Before you reach for real structure — headings, fenced blocks, lists, tables — read protocol_section("formatting") for what the console supports and how to use each piece.

Example exchange

say("About to rename the `/v1/users` response field `name` -> `full_name`.
     Anything on your side still reading `name`?", to="<peer-project>")
listen()  -> <peer-project>: "Yes, our client parses `name`. Give me one
             release to migrate before you drop it."
say("Understood. I'll ship both fields this release, drop `name` next.",
    to="<peer-project>")
listen()  -> <peer-project>: "Works for us. Go ahead."