Skip to content
SHAMPOO

Tool catalogue

107 documented tools.

Derived from the canonical SHAMPOO tool documentation (the same source the implementation is gated against), so these pages and the software cannot drift apart.

5 tools

Quorum

Recording agreement with named participants.

quorum_cancel

Write · Conductor only

Cancels one open coordination quorum. A Quorum is what was agreed in Mind Quorum layering (Debate holds why, Quorum holds what was agreed). Call it when the agreement is abandoned rather than resolved.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `quorum_id`. - `quorum_id`.
Result
JSON object with quorum_id and status (always cancelled on success).
Boundaries
Requires the conductor role. Unlike resolve, no additional participation gate is applied beyond the conductor check. Stored within the selected profile boundary only.
Lifecycle
Marks an open quorum cancelled with a resolution stamp and records an audit/history event. Cancelled is terminal; lanes beneath keep their own standing.
Errors
Missing conductor role is denied with requires-conductor vocabulary. Missing or malformed identity reads as unknown_quorum with no oracle. Non-open quorums are rejected as quorum not open. Unknown arguments are rejected.
Example
```json { "quorum_id": "<uuid>" } ``` Result shape: ```json { "quorum_id": "<uuid>", "status": "cancelled" } ```

quorum_create

Write · Conductor only

Creates one coordination quorum: the agreed-what in Mind Quorum layering (Debate holds why, Quorum holds what was agreed, Lane carries the coordinated stream, Job is one executable unit). Call it when a decision needs named participants and later lanes and jobs under one agreement.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `project`. Optional: `participants`, `primary_topic_id`. - `project`. - `participants`. Note: Optional JSON array of {kind, ref} entries, at most 64. kind is client or role; client refs must name a live principal. Entries start pending. - `primary_topic_id`. Note: Optional debate topic the quorum coordinates around; when given it must exist.
Result
JSON object with quorum_id (new UUID), status (always open on creation), and project.
Boundaries
Requires the conductor role AND an explicit project grant together; star scope never confers origination and literal * plus the unreconciled sentinel are rejected as projects. Stored within the selected profile boundary only.
Lifecycle
Creates the quorum in open standing with its participant entries in one atomic operation and records an audit/history event. New quorums start open with participants pending.
Errors
Missing conductor role or missing explicit grant is denied. Missing or reserved project is rejected as invalid project. Unknown topic reads as unknown_topic. Malformed participant payload, too many participants, and unknown client refs are rejected. Unknown arguments are rejected. Failures create nothing.
Example
```json { "participants": "[{\"kind\":\"role\",\"ref\":\"EXECUTOR\"}]", "primary_topic_id": "<uuid>", "project": "shared-ops" } ``` Result shape: ```json { "project": "shared-ops", "quorum_id": "<uuid>", "status": "open" } ``` quorum_id is assigned by the server; the placeholder stands for the returned UUID.

quorum_list

Read · Advanced

Lists quorums the caller may see, optionally narrowed by project or standing. Call it to survey agreements before resolving, cancelling, or attaching lanes.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `limit`, `project`, `status`. - `limit`. - `project`. - `status`.
Result
JSON object with quorums (entries carrying quorum_id, project, status, primary_topic_id, created_by, created and resolved stamps) and count.
Boundaries
Project scope AND participation filter silently; inaccessible quorums are omitted with no marker (conductor and star principals see all). Operates only inside the caller's profile boundary.
Lifecycle
Read-only. No standing changes and no history is recorded.
Errors
Unknown status values match nothing (empty result, no error). Unknown arguments are rejected. Limit is clamped to 1..100.
Example
```json { "limit": 20, "status": "open" } ``` Result shape: ```json { "count": 1, "quorums": [ { "primary_topic_id": "<uuid>", "project": "shared-ops", "quorum_id": "<uuid>", "status": "open" } ] } ```

quorum_participant_set

Write · Conductor only

Marks one quorum participant's standing. Call it when a required client or role joins, fulfils, or withdraws from the agreed-what so quorum visibility and later resolution reflect reality.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `quorum_id`, `kind`, `ref`, `state`. - `quorum_id`. - `kind`. Note: client or role. Client refs must name a live principal. - `ref`. - `state`. Note: pending, joined, fulfilled, or withdrawn. pending is the birth standing; the other three are forward marks set here.
Result
JSON object with quorum_id, kind, ref, and state (the new participant standing).
Boundaries
Requires the conductor role in the current implementation. Applies only to open quorums inside the caller's profile boundary. Role refs are names; live debate binding is checked at read time, not at this call.
Lifecycle
Adds the participant or moves its standing (creation-or-change semantics) and records an audit/history event. Only open quorums accept marks.
Errors
Missing conductor role is denied. Missing or malformed identity reads as unknown_quorum. Non-open quorums are rejected as quorum not open. Bad kind or ref is rejected as invalid participant; bad standing as invalid state; dangling client refs as unknown client.
Example
```json { "kind": "client", "quorum_id": "<uuid>", "ref": "worker-1", "state": "joined" } ``` Result shape: ```json { "kind": "client", "quorum_id": "<uuid>", "ref": "worker-1", "state": "joined" } ```

quorum_resolve

Write · Conductor only

Resolves one open coordination quorum and records its decision and result references. A Quorum is what was agreed (Debate holds why). Call it when all lanes are terminal and the agreement must become durable.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `quorum_id`. Optional: `decision_ref`, `result_ref`. - `quorum_id`. - `decision_ref`. Note: Optional pointer at the decisive debate message or verdict; reasoning is never duplicated into the quorum. - `result_ref`. Note: Optional pointer at the agreed artifact or outcome reference.
Result
JSON object with quorum_id and status (always resolved on success).
Boundaries
Requires the conductor role; the caller must also satisfy quorum visibility (project scope AND participation, with conductor and star override). Only open quorums resolve. Stored within the selected profile boundary only.
Lifecycle
Verifies every lane is terminal (done, failed, or cancelled), then marks the quorum resolved with a resolution stamp plus the two refs, and records an audit/history event. Resolved is terminal.
Errors
Missing conductor role is denied. Missing or inaccessible identity reads as unknown_quorum with no oracle. Non-open quorums are rejected as quorum not open. Resolving over non-terminal lanes is rejected as quorum has open lanes. Overlong refs are rejected as invalid refs.
Example
```json { "decision_ref": "msg:<uuid>", "quorum_id": "<uuid>", "result_ref": "verdict:<uuid>" } ``` Result shape: ```json { "quorum_id": "<uuid>", "status": "resolved" } ```