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.

10 tools

Reflection

Reviewing and consolidating accumulated memory as a reviewed pipeline.

reflect_apply

Write · Advanced

Applies accepted candidates from a completed run as conservative task mutations with snapshots. Call it after deciding; reruns are safe because applied candidates skip.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `run_id`. Optional: `applied_by`, `candidate_ids_csv`. - `run_id`: id of a run in `completed` status. Other statuses error. - `applied_by`: actor recorded on each snapshot row. Note: Actor recorded on each snapshot; defaults user. - `candidate_ids_csv`: optional comma-separated subset of candidate ids to apply. Empty string = apply all accepted.
Result
Object with run_id, considered and applied counts, skipped array (candidate_id plus reason), and failed array (candidate_id plus error).
Boundaries
Run must be completed and its input project granted (unfiltered runs are star-only; foreign runs read as not-found, never leaking status). Every task target re-checks caller scope before mutation; denied targets land in skipped as target_out_of_scope.
Lifecycle
Applies accepted candidates through the canonical task mutation path with before/after snapshots per candidate. Already-applied candidates skip idempotently as already_applied; entity targets skip (no archive primitive yet); vanished targets skip as target_not_found. All-or-nothing per call.
Errors
Unknown, discarded, or foreign runs read as not-found; non-completed runs fail as run_not_completed. Engine failures return normal error plus internal_error payloads, never transport errors.
Example
```json { "run_id": "<uuid>" } ``` Result shape: ```json { "applied": 2, "considered": 3, "failed": [], "run_id": "<uuid>", "skipped": [ { "candidate_id": "<uuid>", "reason": "already_applied" } ] } ```

reflect_archive

Write · Advanced

Archives a terminal run. Call it to retire completed, failed, or canceled runs from default history listings.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `run_id`. - `run_id`.
Result
Object with run_id, archived_at, and newly_archived flag.
Boundaries
Run access follows the input-project gate: foreign or unfiltered runs read as not-found for non-star callers.
Lifecycle
Stamps archived_at on a terminal run; history stays listed by default until include_archived filtering hides it. Idempotent: re-archiving reports newly_archived false with the same stamp.
Errors
Unknown, discarded, or foreign runs fail as run_not_found. Pending or running runs fail as cannot_archive_active_run. Shapes are normal invalid_state_transition payloads.
Example
```json { "run_id": "<uuid>" } ``` Result shape: ```json { "archived_at": "<iso-8601>", "newly_archived": true, "run_id": "<uuid>" } ```

reflect_audit

Read · Advanced

Finds consolidation candidates without mutating anything. Call it to preview duplicates, stale work, orphans, and hygiene gaps before starting a run.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `abandoned_inbox_days`, `format`, `limit_per_category`, `project`, `stale_days`. - `abandoned_inbox_days`: inbox items untouched this long are flagged (default 30) Note: Inbox items untouched this long are flagged; defaults 30. - `format`: "json" (default) or "markdown" (adds rendered report) Note: json or markdown; markdown adds a rendered report. - `limit_per_category`: cap candidates per category (default 20) Note: Cap per category; defaults 20. - `project`: filter to a single project (empty = all) Note: Single-project filter; empty means all but then requires star scope. - `stale_days`: due_date older than this many days counts as stale (default 60) Note: Overdue thresholds older than this many days count as stale; defaults 60.
Result
Object with version, summary (total_candidates, by_category, applied_filters), candidates per category, and markdown when requested.
Boundaries
An explicit project must be granted; an unfiltered global audit requires star scope. Scans additionally constrain to grants, so candidates only come from visible projects.
Lifecycle
Read-only dry run; persists nothing. Six deterministic categories: exact duplicate titles, stale overdue not_started tasks, empty-description notes, orphan parent links, abandoned inbox items, and entities without observations, each with a suggested action.
Errors
Out-of-scope project or non-star global request returns a normal error payload. Engine failures return a normal error payload, never a transport error.
Example
```json { "format": "json", "limit_per_category": 20 } ``` Result shape: ```json { "candidates": { "exact_duplicate_titles": [] }, "summary": { "by_category": { "exact_duplicate_titles": 0 }, "total_candidates": 0 }, "version": "reflect_audit_v0.5_dry_run" } ```

reflect_cancel

Write · Advanced

Cancels a pending or running run. Call it before discarding when a run should not proceed; terminal runs are rejected.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `run_id`. - `run_id`.
Result
Object with run_id and status (canceled).
Boundaries
Run access follows the input-project gate: foreign or unfiltered runs read as not-found for non-star callers.
Lifecycle
Moves a pending or running entry to canceled with an end stamp. Terminal entries are rejected, never rewritten.
Errors
Unknown, discarded, or foreign runs fail as run_not_found. Terminal runs fail as cannot_cancel_terminal_run. Shapes are normal invalid_state_transition payloads.
Example
```json { "run_id": "<uuid>" } ``` Result shape: ```json { "run_id": "<uuid>", "status": "canceled" } ```

reflect_decide

Write · Advanced

Records a human accept, reject, or defer decision on one candidate. Call it during review to gate what apply will change.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `candidate_id`, `decision`. Optional: `decided_by`. - `candidate_id`. - `decision`. Note: One of accept, reject, defer. - `decided_by`. Note: Actor recorded on the candidate; defaults user.
Result
Object with candidate_id, decision, and decided_by.
Boundaries
Unknown and out-of-scope candidates both read as candidate_not_found: run input project plus candidate evidence project must be granted (star bypasses).
Lifecycle
Stamps the candidate decision with decider and timestamp. Decisions are overwriteable by deciding again; only accept is picked up by apply.
Errors
Unknown decisions fail as invalid_argument. Unknown or foreign candidates fail as not_found. Validation rejects missing candidate_id/decision.
Example
```json { "candidate_id": "<uuid>", "decision": "accept" } ``` Result shape: ```json { "candidate_id": "<uuid>", "decided_by": "user", "decision": "accept" } ```

reflect_discard

Write · Advanced

Discards a terminal run as a lifecycle transition: it resolves as absent while its candidates are preserved. Call it to retire runs without losing review evidence.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `run_id`. - `run_id`.
Result
Object with run_id and rows_deleted (1 on success, kept for oracle wire shape).
Boundaries
Run access follows the input-project gate: foreign or unfiltered runs read as not-found for non-star callers.
Lifecycle
Lifecycle transition to discarded with timestamp, actor, and reason; inputs, candidates, and snapshots are preserved, so candidate-centric review and decide keep working while run-centric tools resolve the run as absent. The narrow sanctioned retirement path; nothing is physically removed.
Errors
Unknown, already-discarded, or foreign runs fail as not_found. Pending or running runs fail as cannot_discard_active_run: cancel first.
Example
```json { "run_id": "<uuid>" } ``` Result shape: ```json { "rows_deleted": 1, "run_id": "<uuid>" } ```

reflect_history

Read · Advanced

Paginated newest-first list of reflection runs. Call it to find past runs and their outcomes before drilling into status or review.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `include_archived`, `limit`, `offset`, `status_filter`. - `include_archived`. Note: Defaults false; hides archived runs unless true. - `limit`. Note: Defaults 20, clamped 1 to 100. - `offset`. Note: Pagination cursor; negative behaves as 0. - `status_filter`. Note: One of pending, running, completed, failed, canceled; anything else is an error.
Result
Object with runs array (run_id, version, status, model, instructions, error fields, usage, created_by, timestamps), total, limit, offset, include_archived, and status_filter.
Boundaries
Non-star callers see only runs whose input project is granted; discarded entries are always excluded.
Lifecycle
Pure read over persisted runs, newest first.
Errors
Unknown status_filter fails as unknown_status. Backend failures return normal internal_error payloads.
Example
```json { "limit": 20 } ``` Result shape: ```json { "limit": 20, "offset": 0, "runs": [ { "run_id": "<uuid>", "status": "completed" } ], "total": 1 } ```

reflect_review

Read · Advanced

Paginated, filterable candidate list for human review. Call it to triage a run's candidates before deciding and applying.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `run_id`. Optional: `candidate_type_filter`, `decision_filter`, `limit`, `offset`. - `run_id`: parent run id. - `candidate_type_filter`: optional category narrowing (e.g. 'stale_overdue_tasks'). Note: Narrows to one of the six audit categories. - `decision_filter`: empty | pending | accept | reject | defer. Note: Empty, pending, accept, reject, or defer; anything else is an error. - `limit`: max rows (clamped to 1000). Note: Defaults 100, clamped 1 to 1000. - `offset`: pagination cursor. Note: Pagination cursor; negative behaves as 0.
Result
Object with candidates array (candidate_id, run_id, type, suggested_action, target_kind, target_ref, evidence, confidence, decision fields, timestamps, already_applied), total, limit, offset, and the two filters.
Boundaries
Foreign runs read as the empty shape. Candidates additionally filter by evidence project, so pre-gate runs with cross-project candidates stay contained; scoped callers get the visible total.
Lifecycle
Pure read over persisted candidates with parsed evidence and an already_applied flag derived from apply snapshots.
Errors
Unknown decision_filter fails as unknown_decision_filter. Missing run_id rejected by validation. Backend failures return normal invalid_argument payloads.
Example
```json { "run_id": "<uuid>" } ``` Result shape: ```json { "candidates": [ { "already_applied": false, "candidate_id": "<uuid>", "candidate_type": "stale_overdue_tasks" } ], "limit": 100, "offset": 0, "total": 1 } ```

reflect_start

Write · Advanced

Creates a reflection run and executes the extract stage synchronously. Call it to turn an audit preview into reviewable persisted candidates.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `abandoned_inbox_days`, `created_by`, `instructions`, `limit_per_category`, `model`, `project`, `stale_days`, `version`. - `abandoned_inbox_days`. - `created_by`: actor recorded in reflection_runs.created_by. Note: Actor recorded on the run; defaults user. - `instructions`: free-form guidance text (max 4096 chars per C14/Dreams). Note: Free-form guidance, at most 4096 characters; longer fails as instructions_too_long. - `limit_per_category`. - `model`: optional model id for future LLM-based runs (Phase 2 uses). Note: Optional model id for future runs; recorded only. - `project`: optional project filter for the audit pass. - `stale_days`. - `version`: run schema version for forward-compat (default reflect_v1.0). Note: Run schema version; defaults reflect_v1.0.
Result
Object with run_id, status (completed, or failed on cap exhaustion), candidates_persisted, summary, and on failure error_type.
Boundaries
An explicit project must be granted; unfiltered runs are star-only since their candidates would span all projects. The audit scan constrains to grants.
Lifecycle
Creates a pending entry, records the filter input, marks it running, reuses the Phase 0.5 audit to persist one candidate per finding (capped at 10000, beyond which the run fails as candidate_limit_exceeded), then marks it completed. All-or-nothing per run.
Errors
Out-of-scope project or non-star global request fails as invalid_argument. Overlong instructions fail as instructions_too_long. Engine failures return normal internal_error payloads with a best-effort failed marking.
Example
```json { "instructions": "Prefer archiving stale drafts" } ``` Result shape: ```json { "candidates_persisted": 4, "run_id": "<uuid>", "status": "completed", "summary": { "by_category": { "stale_overdue_tasks": 4 }, "total_candidates": 4 } } ```

reflect_status

Read · Advanced

Returns one run's state, inputs, and decision counts. Call it to check progress before reviewing, deciding, or applying.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `run_id`. - `run_id`.
Result
Object with run (run_id, version, status, model, instructions, error fields, usage, created_by, timestamps), inputs array, and candidate_counts (pending, accept, reject, defer, total).
Boundaries
Unfiltered or foreign runs read as not-found for non-star callers; discarded entries read as absent exactly like missing ones.
Lifecycle
Pure read over the persisted run, its inputs, and live decision counts.
Errors
Unknown, discarded, or foreign runs fail as not_found. Missing run_id rejected by validation. Backend failures return normal internal_error payloads.
Example
```json { "run_id": "<uuid>" } ``` Result shape: ```json { "candidate_counts": { "accept": 1, "defer": 0, "pending": 2, "reject": 0, "total": 3 }, "inputs": [], "run": { "run_id": "<uuid>", "status": "completed" } } ```