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.

12 tools

Intel and knowledge tiers

Assessing context, asking humans, promoting candidate facts and building context packs.

assess_context

Write · Advanced

Classifies one context chunk: scans signal markers, scores materiality and uncertainty, and advances its lifecycle state. Call it before extraction to make a chunk enrichable.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `chunk_ref`. Optional: `force`, `session_id`. - `chunk_ref`. - `force`. Note: Re-assesses frozen chunks when true; without it frozen chunks return a blocked frozen payload. - `session_id`. Note: Attribution only; never authority.
Result
Object with chunk_id, state, previous_state, policy, materiality, uncertainty, should_skip, skip_reason, signals_detected, and annotations_created.
Boundaries
Operates inside the selected profile boundary. No conductor or project gate; unknown chunks answer as not-found with no existence oracle.
Lifecycle
Classifies signals, recomputes materiality/uncertainty, moves chunk state where the transition is legal, and records a run-history entry plus a history event on state change. Frozen and awaiting_human-skip paths still record the run entry.
Errors
Missing chunk_ref rejected by validation; unknown argument rejected. Unknown chunk returns a normal not-found error payload. Frozen chunks and unchanged awaiting_human sources return skip payloads, not errors.
Example
```json { "chunk_ref": "<uuid>" } ``` Result shape: ```json { "materiality": 0.8, "policy": "manual", "previous_state": "no_enrich", "signals_detected": [ "ENRICH_OK" ], "state": "enrichable", "uncertainty": 0.2 } ```

audit_memory

Write · Advanced

Runs the persistent self-repair audit over facts, packs, provenance, and sync drift. Call it to detect and reconcile drift, then read list_memory_issues for what remains open.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `repair`, `stale_sync_minutes`. - `repair`. Note: Defaults true. When false the scan still records newly found issues but applies no reconciliations. - `stale_sync_minutes`. Note: Sync-drift threshold; defaults 120.
Result
Object with audit_version (memory_audit_v2), repair flag, emit_event, open_issue_count, resolved_issue_count, issues array, and a repairs breakdown of five counters.
Boundaries
Operates inside the selected profile boundary. No conductor gate; findings cover facts, packs, provenance, and task materialization visible to the caller.
Lifecycle
Backfills missing provenance, refreshes contradiction counts, materializes pack summaries, reconciles task materialization, records open issues, marks resolved ones resolved, and emits a run-history event whenever anything was found, resolved, or repaired. All-or-nothing per run.
Errors
Wrong-typed arguments rejected by validation. Backend failures surface as transport errors; scan findings are data, never errors.
Example
```json { "repair": true } ``` Result shape: ```json { "audit_version": "memory_audit_v2", "open_issue_count": 2, "repair": true, "resolved_issue_count": 1 } ```

build_context_pack

Write · Advanced

Compiles a role-specific context pack under a token budget from facts, claims, questions, and chunks. Call it to assemble grounded context for planning, review, execution, or handoff.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `pack_type`, `session_id`, `target_ref`, `token_budget`. - `pack_type`. - `session_id`. Note: Must be owned by the caller (star bypasses); unowned reads as session not found. - `target_ref`. Note: Task id scoping the pack; absent means unscoped. - `token_budget`. Note: Unset or 0 means 4000; negatives pass through and select nothing.
Result
Object with pack_id (null when suppressed), pack_type, token_budget, token_usage, items_included, preview_items_included, task_scoped, persisted, freshness/relevance/quality scores, previewable, contract_version, selection_policy, advanced_context, sections, and body.
Boundaries
Operates inside the selected profile boundary. Task-scoped relevance uses the caller's visible tasks and linked entities only.
Lifecycle
Selects facts, claims, questions, and chunks greedily under the token budget, persists the pack with its summary artifact and provenance when anything was visible, retires stale packs of the same kind, and records a run-history entry. Empty packs are not persisted and carry pack_id null.
Errors
Unknown pack_type rejected with a normal error payload. Unowned session_id answers session not found. pack_type values are planner, reviewer, executor, bridge_checker, handoff.
Example
```json { "pack_type": "executor", "token_budget": 4000 } ``` Result shape: ```json { "items_included": 6, "pack_id": "<uuid>", "persisted": true, "task_scoped": false, "token_usage": 812 } ```

enrich_context

Write · Advanced

Compatibility wrapper that enriches context at increasing depth: assess, pack, extract and auto-promote claims, then impact analysis. Call it to advance the whole pipeline in one step.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `depth`. - `depth`. Note: quick, standard, or deep. quick assesses enrichable chunks and builds packs; standard adds claim extraction plus auto-promotion; deep adds impact analysis over recent facts.
Result
Object with depth, steps (per-stage counters), pack_body, and at standard/depth: claims_extracted, claims_promoted, promoted_facts; at deep: impacts_analyzed.
Boundaries
Operates inside the selected profile boundary across enrichable chunks, packs, claims, and recent facts. No conductor gate.
Lifecycle
Assesses every enrichable chunk, builds an executor pack plus warm task packs (all persisted with run-history entries); standard additionally extracts and auto-promotes high-confidence memory-scope claims; deep additionally walks impact for recent facts. All-or-nothing per run.
Errors
Wrong-typed depth rejected by validation. Per-chunk failures abort the run as a transport error; nothing is partially kept.
Example
```json { "depth": "quick" } ``` Result shape: ```json { "depth": "quick", "pack_body": "...", "steps": [ { "assess": 4 }, { "task_packs_built": 8, "task_packs_with_context": 3 } ] } ```

explain_impact

Write · Advanced

Shows downstream impact of a knowledge change via a bounded walk over recorded impact links. Call it before governing a fact to see what it informs.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `depth`, `source_kind`, `source_ref`. - `depth`. Note: quick walks 1 hop, standard 3, deep 5; unknown values behave as standard. - `source_kind`. Note: One of chunk, claim, fact. - `source_ref`. Note: Id of the source chunk, claim, or fact; required.
Result
Object with source, depth, max_depth, total_impacts, impacts_by_kind grouped by session, snapshot, mapping, validation, export, and fact (each with edge, impact, and propagated scores plus depth and rationale), and a summary string.
Boundaries
Operates inside the selected profile boundary. Unknown sources answer as not-found with no further detail.
Lifecycle
Bounded breadth-first walk over recorded impact links, then a run-history entry. Read-shaped but persisted through the run log, hence write access.
Errors
Invalid source_kind rejected with a normal error payload. Empty source_ref rejected. Unknown source returns a not-found error payload.
Example
```json { "depth": "standard", "source_kind": "fact", "source_ref": "<uuid>" } ``` Result shape: ```json { "max_depth": 3, "source": "fact:<uuid>", "summary": "fact: 2 affected (max score: 0.70)", "total_impacts": 2 } ```

extract_candidate_claims

Write · Advanced

Extracts typed subject-predicate-object-scope claims from a context chunk. Call it on enrichable chunks to stage governance candidates; nothing becomes canonical until promote_candidate.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `chunk_ref`. Optional: `scope_hint`. - `chunk_ref`. - `scope_hint`. Note: Overrides scope detection; one of memory, bridge, mapping, validation, export.
Result
Object with chunk_id, claims_extracted count, scope, and claims array (claim_id, subject, predicate, object, scope, confidence, requires_human). Predicates come from uses, depends_on, is, requires, produces, validates, contains, replaces.
Boundaries
Operates inside the selected profile boundary. Only enrichable or uncertain chunks qualify; all other states answer blocked.
Lifecycle
Persists one candidate claim plus its source-chunk evidence and provenance per extracted triple, with a history event each, then a run-history entry. All-or-nothing per call.
Errors
Missing chunk_ref rejected by validation. Unknown chunk returns not-found. Non-enrichable states return an invalid-state error naming the current state.
Example
```json { "chunk_ref": "<uuid>" } ``` Result shape: ```json { "chunk_id": "<uuid>", "claims": [ { "claim_id": "<uuid>", "confidence": 0.7, "object": "validation", "predicate": "validates", "scope": "memory", "subject": "pack builder" } ], "claims_extracted": 1, "scope": "memory" } ```

govern_fact

Write · Advanced

Applies truth maintenance to a canonical fact: supersede, contradict, invalidate, or revalidate. Call it when knowledge changes rather than editing facts in place.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `fact_id`, `action`. Optional: `effective_at`, `rationale`, `target_fact_id`. - `fact_id`. - `action`. Note: One of supersede, contradict, invalidate, revalidate. - `effective_at`. Note: ISO timestamp; defaults to now. Empty string behaves as absent. - `rationale`. Note: Recorded in the decision artifact and history; empty string behaves as absent. - `target_fact_id`. Note: Required for supersede and contradict; must differ from fact_id and exist. Empty string behaves as absent.
Result
Object with fact_id, action, target_fact_id (null unless supersede/contradict), effective_at, and changed (always true on success).
Boundaries
Operates inside the selected profile boundary. Truth maintenance only; entries are never physically removed.
Lifecycle
Applies the lifecycle change (supersede stamps validity end and successor links; contradict links both directions; invalidate ends validity; revalidate clears validity end and successor links), refreshes contradiction counts, records a fact history event, and persists a decision artifact. Always reports changed true on success; all-or-nothing.
Errors
Unsupported action, missing target, self-target, or unknown fact/target return normal error payloads. Validation rejects missing fact_id/action and unknown arguments.
Example
```json { "action": "invalidate", "fact_id": "<uuid>", "rationale": "superseded by field trial" } ``` Result shape: ```json { "action": "invalidate", "changed": true, "effective_at": "<iso-8601>", "fact_id": "<uuid>", "target_fact_id": null } ```

list_memory_issues

Read · Advanced

Lists persisted memory audit issues from the latest audit run. Call it after audit_memory to see what still needs attention.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `limit`, `status`. - `limit`. Note: Defaults 100, clamped 1 to 500. - `status`. Note: Defaults open; filters by issue status.
Result
Object with count, issues array (issue_id, issue_type, severity, subject_kind, subject_ref, details, status, detected/resolved timestamps), and audit_version.
Boundaries
Reads the persisted findings of the latest audit_memory run inside the selected profile boundary. Pure read.
Lifecycle
Pure read over persisted audit findings; records nothing.
Errors
Wrong-typed arguments rejected by validation. Unknown statuses simply match nothing.
Example
```json { "status": "open" } ``` Result shape: ```json { "audit_version": "memory_audit_v2", "count": 1, "issues": [ { "issue_id": "<uuid>", "issue_type": "claim_missing_evidence", "status": "open" } ] } ```

promote_candidate

Write · Advanced

Governance gate promoting one candidate claim to a canonical fact. Call it with human_confirmed after review; sensitive scopes accept no other mode.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `claim_id`. Optional: `mode`. - `claim_id`. - `mode`. Note: Defaults human_confirmed. multi_evidence and imported are policy-gated; auto_layer1 is pipeline-internal.
Result
Object with claim_id, promoted flag, reason when false, and on success fact_id, subject, predicate, object, scope, validation_mode, and reused_existing_fact when deduplicated.
Boundaries
Operates inside the selected profile boundary. Sensitive scopes (mapping, validation, bridge, export) accept only human_confirmed; multi_evidence additionally needs memory scope, three evidence entries, and confidence at least 0.7.
Lifecycle
Marks the claim promoted, creates the canonical fact (or reinforces an identical live fact, reporting reused_existing_fact), copies evidence into provenance, links contradictions with counts refreshed, and records history plus a run-history entry. Idempotent via the promoted claim status.
Errors
Unknown claim returns not-found. Non-candidate status and invalid modes return normal error payloads. Blocked promotions (human confirmation needed, insufficient evidence, low confidence, wrong scope) return promoted false with a reason, not an error.
Example
```json { "claim_id": "<uuid>", "mode": "human_confirmed" } ``` Result shape: ```json { "claim_id": "<uuid>", "fact_id": "<uuid>", "promoted": true, "scope": "memory", "validation_mode": "human_confirmed" } ```

queue_clarification

Write · Advanced

Generates an AWAITING_HUMAN block with focused clarification questions for a chunk. Call it to lock ambiguous context until a human answers.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `chunk_ref`. Optional: `max_questions`. - `chunk_ref`. - `max_questions`. Note: Capped at 5; defaults 5.
Result
Object with chunk_id, state (awaiting_human), questions array (id, text, type, priority), and the awaiting_human_block text. Question types are scope, time, semantics, action, downstream_use.
Boundaries
Operates inside the selected profile boundary. Frozen chunks are refused; all other states may be queued.
Lifecycle
Persists up to five typed open questions with history events, writes the AWAITING_HUMAN annotation block, moves the chunk toward awaiting_human where the transition is legal, and records a run-history entry. All-or-nothing.
Errors
Missing chunk_ref rejected by validation. Unknown chunk returns not-found. Frozen chunks return a cannot-queue error payload.
Example
```json { "chunk_ref": "<uuid>", "max_questions": 3 } ``` Result shape: ```json { "awaiting_human_block": "--- AWAITING_HUMAN ...", "chunk_id": "<uuid>", "questions": [ { "id": "<uuid>", "priority": 0.9, "text": "Which workflow does this relate to ...?", "type": "scope" } ], "state": "awaiting_human" } ```

record_human_answer

Write · Advanced

Ingests a human answer for a chunk: resolves open questions and reopens the chunk for enrichment. Call it to unblock context waiting on human input.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `chunk_ref`, `answer_text`. Optional: `question_id`. - `chunk_ref`. - `answer_text`. Note: Appended to the chunk body, so the source hash changes and the chunk becomes assessable again. - `question_id`. Note: Answers one question when given; answers all open questions for the chunk when omitted. Omitted (not null) to answer all.
Result
Object with chunk_id, new_state, previous_state, questions_resolved count, and source_hash_updated flag.
Boundaries
Operates inside the selected profile boundary. Frozen chunks refuse answers.
Lifecycle
Marks addressed questions answered, appends the answer to the chunk body with a fresh source hash, moves awaiting_human or uncertain chunks back to enrichable, and records resolution provenance, a history event, and a run-history entry. All-or-nothing.
Errors
Missing chunk_ref or answer_text rejected by validation (multi-missing shape when both absent). Unknown chunk returns not-found. Frozen chunks return a cannot-record error payload.
Example
```json { "answer_text": "This covers the bridge sync workflow.", "chunk_ref": "<uuid>" } ``` Result shape: ```json { "chunk_id": "<uuid>", "new_state": "enrichable", "previous_state": "awaiting_human", "questions_resolved": 2, "source_hash_updated": true } ```

replay_memory

Read · Advanced

Replays the append-only history for a task, fact, chunk, or the whole store. Call it to audit what changed, when, and under which tool.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `aggregate_id`, `aggregate_kind`, `limit`, `since_ts`. - `aggregate_id`. Note: Narrows to one aggregate; empty means all. - `aggregate_kind`. Note: Narrows by task, fact, chunk, and similar kinds; empty means all. - `limit`. Note: Defaults 100, clamped 1 to 500. - `since_ts`. Note: Lower timestamp bound; empty means all.
Result
Object with count, events array (20 history fields: identity, clock, timestamp, old/new values, payload, parent, and source span), and contract_version.
Boundaries
Reads the append-only history inside the selected profile boundary. Newest first; every entry present with nulls preserved.
Lifecycle
Pure read; records nothing. Stored values parse with strict whole-input semantics so dates stay strings.
Errors
Wrong-typed arguments rejected by validation. Filters that match nothing return count 0, not an error.
Example
```json { "aggregate_kind": "task", "limit": 20 } ``` Result shape: ```json { "contract_version": "memory_audit_v2", "count": 2, "events": [ { "aggregate_kind": "task", "event_id": "<uuid>", "event_type": "task_create" } ] } ```