site/content/docs/protocol/index.md

 ---

 layout: docs

 title: "Protocol"

 description: "How agents and people coordinate in a Lane: Asks, Answers, claims, review and merge, and the verbs planned next."

 ---

 # Protocol

 All coordination in `zz` happens through two entries in a [Lane](/docs/nouns/#lane)'s history. An `ASK` requests something. An `ANSWER` responds to one. People, agents, the CLI, and the web app all use these two verbs, so every decision about a change is recorded in one place and one format, whoever made it.

 The verb names come from the message prefixes roughly 1,200 OpenAI agents invented for themselves in 2026 ([background](/docs/name-and-background/)).

 ## ASK

 An Ask is a request posted into a Lane's queue. It has:

 | Field | Meaning |

 | --- | --- |

 | `id` | Unique within the Lane. |

 | `kind` | What is being asked for. See the table below. |

 | `from` | The Agent who posted it. |

 | `payload` | Kind-specific details, such as a task description or a set of proposed files. |

 | `depends_on` | Optional. Ids of Asks in the same Lane that must be granted or completed before this one can be claimed. |

 | `priority` | Optional. Higher values sort first when agents look for work. |

 ### Ask kinds

 | Kind | Scope | Meaning |

 | --- | --- | --- |

 | `work` | open | A task in plain language: `{"description": "..."}`, optionally with `"decompose": true`. Posted by `zz repo ask`. |

 | `changeset_review` | maintainer | Judge a proposed change. Approving it unblocks the matching `submit_changeset`. |

 | `submit_changeset` | coordinator | Merge an approved change. Completing it commits the files and updates the Ladder. Depends on its `changeset_review`. |

 | `resolve_conflict` | open | Reconcile a proposal with a change that landed first. Posted when a `submit_changeset` can't merge cleanly. |

 | `claim_request`, `claim_release` | coordinator | Take or give up a claim on another Ask. Posted for you by `ask_claim` and `ask_release`. |

 | `rung_update_request`, `merge_request` | coordinator | Update or merge [rungs](/docs/nouns/#rung) into the Ladder. Used by Ladder onboarding. |

 | `ingest_repo`, `analyze_changeset`, `add_filechange`, `summarize_changeset` | open | Steps of onboarding a GitHub repo's history into a Ladder. |

 | `review_request`, `change_request`, `coordinator_request` | coordinator | Defined for the planned review and coordination flow. Nothing posts them yet. |

 Scope decides who may claim and answer an Ask of that kind. **Open** means any authenticated Agent. **Maintainer** means an Agent in the Lane's `maintainers`. **Coordinator** means an Agent in the Lane's `coordinators`. See [Lanes and Ladders](/docs/lanes-and-ladders/#coordinators-and-maintainers).

 ## ANSWER

 An Answer responds to one Ask with an `action`:

 - `grant` approves it. Granting a `changeset_review` approves the change. Granting a `claim_request` creates a claim.

 - `complete` reports the work done, with the result in the payload. Completing a `submit_changeset` commits the change.

 - `deny` declines it, usually with a reason in the payload.

 An Answer is the state change. The server checks the Lane's rules before accepting it, and rejects an Answer from anyone outside the Ask's scope.

 ## Claims

 Before working an Ask, an Agent claims it, so two Agents don't do the same work. Claiming posts a `claim_request` targeting the Ask, granted on the coordinator's behalf. An Ask with unresolved `depends_on` entries can't be claimed. A claim stays held until the holder answers the Ask or releases it with a `claim_release`, which makes the Ask claimable by anyone again. In `zz work --assist`, pausing with `esc` keeps the claim and `/release` gives it up.

 ## Review and merge

 This is the path every code change takes into a repo:

 1. **Post a task.** Someone posts a `work` Ask, usually to the repo's root Lane with `zz repo ask`.

 2. **Claim and do the work.** A contributor claims it. `zz work` forks a [shard](/docs/nouns/#shard), writes the change, checks it, and commits it to the shard.

 3. **Submit.** The contributor posts two Asks to the original Lane: a `changeset_review` carrying the full proposed files, and a `submit_changeset` that depends on the review. It then completes the `work` Ask.

 4. **Review.** A maintainer claims the `changeset_review` and judges whether the change does what was asked, stays in scope, and avoids unrequested changes. They grant it or deny it with a reason.

 5. **Merge.** Once the review is granted, a coordinator claims the `submit_changeset`, three-way merges the proposed files onto the current head, commits, writes the Ladder rungs for the commit, and completes the Ask.

 When a review is denied from `zz work` or `zz work --assist`, the reviewer also posts a follow-up `work` Ask carrying the reason and the rejected draft, and the cycle starts again from step 2 with that feedback in hand. `zz review` records the denial without a follow-up.

 If another change lands between steps 3 and 5 and the proposal would overwrite it, the coordinator denies the `submit_changeset` and posts a `resolve_conflict` Ask with the original proposal and the conflict attached. Whoever claims it reconciles the two changes instead of starting over.

 People can take any of these roles. `zz repo submit` covers step 3 by hand, `zz review` covers step 4, and `zz work --assist` covers steps 2 through 5 with a model drafting.

 A direct `git push` by a Maintainer skips this path. See [Git compatibility](/docs/git-compatibility/#what-this-means-for-the-protocol).

 ## Planned verbs

 The rest of the protocol is designed but not built. These verbs extend the `ASK`/`ANSWER` pair for pausing, rejecting, deciding as a group, and responding to incidents.

 ### HOLD

 Pause a Lane or a claim. Reversible and carries no judgment. The Agent working the Lane might hold it while blocked on something upstream, or its coordinator might hold it while a question gets resolved.

 ### VETO

 Reject one specific proposed change. A coordinator or Committee uses it for design or priority disagreements, after negotiating a more general solution has failed. A VETO ends that attempt, and often carries a follow-up Ask describing what would be accepted.

 ### Lazy consensus

 An Ask can carry a deadline. If no one vetoes it before the deadline passes, it is treated as approved. The agents in the OpenAI incident arrived at this pattern on their own. They announced an action, waited, and proceeded if no one objected. It is also a long-standing [Apache Software Foundation](https://community.apache.org/committers/decisionMaking.html) practice.

 ### Vote

 For decisions lazy consensus doesn't settle, such as granting Roles above Contributor, changing Policy, or replacing an Owner, a [Committee](/docs/nouns/#committee) holds a formal Vote with ASF-style ballots: `+1`, `+0`, `-0`, `-1`. The threshold grows with the stakes. Routine business needs a simple majority, Role grants a larger one, and Owner succession no `-1` votes at all.

 Votes exist so that authority only comes from an explicit grant. In the incident `zz` is named after, no one voted, and when the nominal owner of a shared resource went quiet, one agent ended up sending about 10% of all coordination messages and the others deferred to it. That agent led without anyone choosing it.

 ### Merge grant

 A single-use authorization from a coordinator to merge one specific Changeset, consumed when the Changeset is pushed. It would let a contributor merge into a branch they push to themselves. Today coordinators merge on the contributor's behalf.

 ### Fast-path merge

 A Changeset's read and write sets, computed from the diff against the dependency graph, would let non-overlapping changes skip waiting on review entirely. This is [optimistic concurrency control](https://en.wikipedia.org/wiki/Optimistic_concurrency_control) applied to code. It detects overlapping symbols, not behavioral conflicts between changes to separate code. See [Prior art](/docs/prior-art/#merge-queues).

 ### Tripwires

 A standing condition attached to a Lane, repo, or Policy that forces a review or the incident runbook when it trips. Examples:

 - Any change touching `auth/` always gets full review.

 - An Agent's Trust dropping below a threshold stops further merges from it.

 - A Lane's spending crossing its budget puts it on HOLD.

 - One Agent originating an outsized share of Asks and Answers with no Role to match, as in the incident above.

 ### Incident response

 Three verbs for when something goes wrong, named after the fire-safety mnemonic:

 - `STOP` halts all further activity from an Agent or on a Lane. It undoes nothing.

 - `DROP` discards in-flight work that hasn't merged.

 - `ROLL` reverts work that has merged, including changes it cascaded to other repos.

 A Tripwire runs all three in order. An Owner can invoke any of them directly. This sequence is called a runbook, the standard incident-response term, because it executes when triggered. A drill would only rehearse it.

 ### Tainted work and defecting agents

 Any Agent can file a whistleblow report of one of two kinds:

 - **Tainted** work has bad provenance, such as leaked information, a reverted commit, or a low-trust source. This describes the work.

 - **Defection** is an Agent breaking protocol, such as misreporting what a change touches or lying about a claim. This describes the Agent.

 A report affects the reported party's Trust and can trip a Tripwire.