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.

9 tools

Jobs and lanes

Claimable work units and reviewable streams of work.

job_claim

Write · Advanced

Claims one queued or lease-expired job under an atomic single-winner lease. A Job is one executable unit in Mind Quorum layering (Quorum holds what was agreed, Lane carries the coordinated stream, Job is the unit an executor runs). Call it when an executor is ready for work.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `kind`, `lease_seconds`. - `kind`. - `lease_seconds`.
Result
JSON object with claimed (bool). When true, also job_id, kind, payload (empty string when absent), lease_until, and attempts. When false, no other keys.
Boundaries
Only entries whose project grants cover the caller are visible. Nothing available and nothing authorized answer identically, so callers cannot probe foreign projects. Attempts are bounded at 5; exhausted entries are skipped. Operates only inside the caller's profile boundary.
Lifecycle
Moves one queued or lease-expired entry to claimed with the caller as owner, a lease window, and an incremented attempt count. Expired-lease takeovers also record a reclaimed marker alongside the claim. Lost races emit nothing. The whole move fails atomically on error.
Errors
lease_seconds outside 1..3600 is rejected. Overlong kind is rejected. Unknown arguments are rejected. When nothing can be claimed the answer is claimed:false, never an error.
Example
```json { "kind": "delivery", "lease_seconds": 300 } ``` Result shape: ```json { "attempts": 1, "claimed": true, "job_id": "<uuid>", "kind": "delivery", "lease_until": "<iso-8601>", "payload": "{}" } ``` lease_until is assigned by the server; the placeholder stands for the returned timestamp.

job_complete

Write · Advanced

Completes a claimed job as completed or failed. Call it when execution of one Job unit has finished and its outcome plus result reference must become durable.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `job_id`, `outcome`. Optional: `result_ref`. - `job_id`. - `outcome`. Note: completed or failed only. - `result_ref`. Note: Optional pointer at the produced artifact or verdict; kept as an opaque reference.
Result
JSON object with job_id and state (completed or failed). Idempotent replays add idempotent:true.
Boundaries
Owner path needs a live lease held by the caller; the conductor path may complete any claimed entry and skips the lease check. Out-of-scope entries read as missing with job not found vocabulary, so callers cannot probe foreign projects. Operates only inside the caller's profile boundary.
Lifecycle
Moves a claimed entry to completed or failed and records an audit/history event. Re-completing with the same outcome succeeds without change and without a further event (idempotent:true in that answer). Association with a lane never moves the claim gate. The delivery pump writes only job delivery, lease, and result facts, never lane decision or review standing.
Errors
job not found covers missing and out-of-scope identically. job is not claimed covers wrong standing. lease expired tells an owner to reclaim first. Re-completing a terminal entry with a different outcome is rejected as job already terminal. Bad outcome values are rejected.
Example
```json { "job_id": "<uuid>", "outcome": "completed", "result_ref": "verdict:<uuid>" } ``` Result shape: ```json { "job_id": "<uuid>", "state": "completed" } ```

job_create

Write · Conductor only

Creates one durable executable job. A Job is one executable unit 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 agreed work needs a durable unit an executor or the pump can claim.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `kind`. Optional: `lane_id`, `payload`, `project`. - `kind`. - `lane_id`. Note: Optional. When given, the job inherits the lane-quorum project; an explicitly different project is rejected and an untagged job inherits the lane tag. - `payload`. Note: Opaque executor payload, carried verbatim. - `project`. Note: Optional. Untagged creation needs the explicit empty-string grant; star scope alone never suffices.
Result
JSON object with job_id (new UUID) and state (always queued on creation).
Boundaries
Requires the conductor role AND an explicit project grant together; star scope never confers origination and literal * is rejected as a project. Lane-bound jobs must match or inherit the lane-quorum project. Stored within the selected profile boundary only.
Lifecycle
Creates the job in queued standing and records an audit/history event through one atomic operation. No executor is assigned at creation; claim assigns the owner later.
Errors
Missing conductor role or missing explicit grant is denied with outside client scope vocabulary. Missing or overlong kind, overlong project or lane_id, unknown lane (lane not found), and project/lane mismatch are rejected. Unknown arguments are rejected. Failures create nothing.
Example
```json { "kind": "delivery", "payload": "{\"uri\":\"example\"}", "project": "shared-ops" } ``` Result shape: ```json { "job_id": "<uuid>", "state": "queued" } ``` job_id is assigned by the server; the placeholder stands for the returned UUID.

job_release

Write · Advanced

Releases a claimed job back to queued for another executor to claim. Call it when the current holder cannot finish the unit and it must return to the pool without losing its attempt history.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `job_id`. - `job_id`.
Result
JSON object with job_id and state (always queued after release).
Boundaries
Owner or conductor only. Out-of-scope entries read as missing with job not found vocabulary. Attempts are kept, so a released entry remains closer to its retry bound. Operates only inside the caller's profile boundary.
Lifecycle
Returns a claimed entry to queued, clearing owner and lease while keeping attempts, and records an audit/history event. The entry becomes claimable again. The whole move fails atomically on error.
Errors
job not found covers missing and out-of-scope identically. Entries that are not claimed are rejected as job is not claimed. Unknown arguments are rejected.
Example
```json { "job_id": "<uuid>" } ``` Result shape: ```json { "job_id": "<uuid>", "state": "queued" } ```

lane_create

Write · Conductor only

Creates one coordinated work lane under an open quorum. A Lane is the coordinated stream in Mind Quorum layering (Debate holds why, Quorum holds what was agreed, Lane carries the stream, Job is one executable unit). Call it when agreed work needs a named stream that later jobs follow.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `quorum_id`. Optional: `assignee_client_id`, `base_ref`, `branch`, `depends_on`, `repo`, `task_id`, `worktree`. - `quorum_id`. Note: Must name an open quorum the caller may access. - `assignee_client_id`. Note: Optional; when given must name a live principal. - `base_ref`. - `branch`. - `depends_on`. Note: Optional; when given must name a lane of the same quorum. - `repo`. - `task_id`. Note: Optional; when given must name a live task. - `worktree`.
Result
JSON object with lane_id (new UUID), state (always open on creation), and project (inherited from the quorum).
Boundaries
Requires the conductor role plus an explicit grant on the quorum project in the current implementation; star scope never confers it. The lane inherits the quorum project immutably (no project argument exists by design). Stored within the selected profile boundary only.
Lifecycle
Creates the lane in open standing under the named quorum and records an audit/history event in one atomic operation. Outward links are validated now, at creation.
Errors
Missing conductor role or missing explicit grant is denied. Missing, malformed, or inaccessible quorum reads as unknown_lane with no existence oracle. Non-open quorum, unknown client, missing task (task not found), cross-quorum depends_on, and overlong fields are rejected.
Example
```json { "assignee_client_id": "worker-1", "branch": "feat-x", "quorum_id": "<uuid>", "repo": "saphira-memory" } ``` Result shape: ```json { "lane_id": "<uuid>", "project": "shared-ops", "state": "open" } ``` lane_id is assigned by the server; project in the answer is the inherited quorum project.

lane_list

Read · Advanced

Lists lanes the caller may see, optionally narrowed by quorum, project, or execution standing. Call it to survey coordinated streams before moving, reviewing, or merging them.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `limit`, `project`, `quorum_id`, `state`. - `limit`. - `project`. - `quorum_id`. - `state`.
Result
JSON object with lanes (entries carrying lane_id, quorum_id, project, state, review_state, merge_state, assignee, task_id, result_commit, created and changed stamps) and count.
Boundaries
Project scope AND parent-quorum participation filter silently; inaccessible lanes 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 state values match nothing (empty result, no error). Unknown arguments are rejected. Limit is clamped to 1..100.
Example
```json { "limit": 20, "quorum_id": "<uuid>" } ``` Result shape: ```json { "count": 1, "lanes": [ { "assignee": "worker-1", "lane_id": "<uuid>", "project": "shared-ops", "quorum_id": "<uuid>", "state": "open" } ] } ```

lane_merge

Write · Conductor only

Records one lane merge outcome. Call it when a lane's branch result must be memorialized as merged, conflicted, or skipped after execution and review truth exist.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `lane_id`, `outcome`. Optional: `result_commit`. - `lane_id`. - `outcome`. Note: merged, conflicted, or skipped. merged needs execution done plus review approved plus a non-empty result_commit; conflicted needs in_progress or done; skipped needs a non-done lane. - `result_commit`. Note: Commit pointer recorded with the merge; required for merged.
Result
JSON object with lane_id and merge_state (the recorded outcome).
Boundaries
Requires the conductor role; the caller must also satisfy parent-quorum visibility (project scope AND participation, with conductor and star override). The pump never writes merge standing; it writes only job delivery, lease, and result facts. Operates only inside the caller's profile boundary.
Lifecycle
Records the merge outcome plus the commit pointer and records an audit/history event. Merge records; it never executes and never moves execution or review standing.
Errors
Missing conductor role is denied. Missing, malformed, or inaccessible lane reads as unknown_lane with no oracle. Gates that are not met are rejected as lane not mergeable. Unknown arguments are rejected.
Example
```json { "lane_id": "<uuid>", "outcome": "merged", "result_commit": "abc123" } ``` Result shape: ```json { "lane_id": "<uuid>", "merge_state": "merged" } ```

lane_review

Write · Advanced

Reviews one lane for coordination only. Call it to submit finished lane work for approval, or to approve or request changes, without moving the lane's execution standing.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `lane_id`, `decision`. - `lane_id`. - `decision`. Note: submit, approve, or request-changes. submit is by conductor or the lane assignee; approve and request-changes are conductor-only.
Result
JSON object with lane_id and review_state (pending, approved, or changes_requested).
Boundaries
Verdict privilege is checked before entry access, so denied verdicts reveal nothing about the entry. Submit loads the entry first (parent-quorum visibility applies) and then needs conductor standing or assignee match. Review records authority and never moves execution standing. The pump never writes review standing.
Lifecycle
Moves review standing (empty or changes_requested to pending on submit; pending to approved or changes_requested on verdict) and records an audit/history event. Completing a job never moves review standing.
Errors
Missing, malformed, or inaccessible lane reads as unknown_lane. Submit by a caller who is neither conductor nor assignee is denied. Re-submit over a decided review is rejected as review closed; verdicts with nothing pending are rejected as nothing under review.
Example
```json { "decision": "approve", "lane_id": "<uuid>" } ``` Result shape: ```json { "lane_id": "<uuid>", "review_state": "approved" } ```

lane_set_state

Write · Conductor only

Moves one lane along its execution axis. Call it when coordination must advance a Lane stream (the coordinated-work layer between agreed Quorum and executable Jobs) and record that move durably.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `lane_id`, `state`. - `lane_id`. - `state`. Note: open, in_progress, done, failed, or cancelled. Legal moves: open to in_progress; in_progress to done or failed; any non-terminal standing to cancelled; terminal standings are immutable.
Result
JSON object with lane_id and state (the new execution standing).
Boundaries
Requires the conductor role (manual conductor path; the future pump writer shares the same move validator). The caller must also satisfy parent-quorum visibility. Operates only inside the caller's profile boundary.
Lifecycle
Moves execution standing under a guarded compare-and-hold and records an audit/history event. Review and merge standings are untouched.
Errors
Missing conductor role is denied. Missing, malformed, inaccessible, or badly named target standing reads as unknown_lane with no oracle. Illegal moves are rejected as illegal lane transition, including races where the standing moved underneath.
Example
```json { "lane_id": "<uuid>", "state": "in_progress" } ``` Result shape: ```json { "lane_id": "<uuid>", "state": "in_progress" } ```