Skip to content
SHAMPOO

Tool catalogue

148 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

Sessions and context

Saving, recalling and closing the working state of a session.

caller_context_set

Write · Ordinary

Annotate own caller instance with asserted runtime metadata (zero authority).

Full documentation →

Arguments, result and boundaries
Arguments
Required: `instance_id`. Optional: `model`, `variation`, `workspace`. - `instance_id`. Note: Caller instance id (required). - `model`. Note: Model label. - `variation`. Note: Variation label. - `workspace`. Note: Workspace path.
Result
JSON object with instance_id and updated 1.
Boundaries
Project-scoped reads; foreign projects read empty. Caller-owned rows only where applicable.
Lifecycle
Owned upsert through a transaction; foreign instances read as not found.
Errors
Bad types are rejected (strict validator). Failures move nothing (atomic).
Example
```json { "instance_id": "conn_x", "model": "m" } ``` Result shape: ```json { "instance_id": "conn_x", "updated": 1 } ```
See also
identitycontext

close_session

Write · Ordinary

Closes one of your own sessions. Call it for renewal hygiene when a session is no longer needed.

Full documentation →

Arguments, result and boundaries
Arguments
Required: `session_id`. - `session_id`.
Result
Object with closed (echoed session_id) and matched (1 closed, 0 untouched).
Boundaries
Only entries owned by the caller's own principal flip; foreign or unknown ids report matched 0 with no existence oracle. Operates inside the selected profile boundary.
Lifecycle
Moves one owned live session entry to ended. No history is removed; the entry stays as renewal hygiene evidence.
Errors
Missing session_id rejected by validation. Foreign or already-closed sessions are not errors: matched 0.
Example
```json { "session_id": "<uuid>" } ``` Result shape: ```json { "closed": "<uuid>", "matched": 1 } ```

context

Read · Ordinary

One-call orientation: pocket, caller, project, session, boundary, catch-up.

Full documentation →

Arguments, result and boundaries
Arguments
Takes no arguments.
Result
JSON object with server, client_id, role, session counts and caller binding.
Boundaries
Project-scoped reads; foreign projects read empty. Caller-owned rows only where applicable.
Lifecycle
Read-only; no rows written.
Errors
Bad types are rejected (strict validator). Failures move nothing (atomic).
Example
```json {} ``` Result shape: ```json { "server": { "name": "saphira-memory" } } ```

identity

Read · Ordinary

Caller identity: own scopes, projects, server (read-only).

Full documentation →

Arguments, result and boundaries
Arguments
Takes no arguments.
Result
JSON object with client_id, user, role, projects and server name/version.
Boundaries
Project-scoped reads; foreign projects read empty. Caller-owned rows only where applicable.
Lifecycle
Read-only; no rows written.
Errors
Bad types are rejected (strict validator). Failures move nothing (atomic).
Example
```json {} ``` Result shape: ```json { "client_id": "<uuid>", "role": "agent" } ```

my_sessions

Read · Ordinary

Own sessions, recency order (owner-scoped).

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `limit`. - `limit`. Note: Max rows (1-100, default 100).
Result
JSON object with own sessions array and count.
Boundaries
Project-scoped reads; foreign projects read empty. Caller-owned rows only where applicable.
Lifecycle
Read-only; no rows written.
Errors
Bad types are rejected (strict validator). Failures move nothing (atomic).
Example
```json {} ``` Result shape: ```json { "count": 0, "sessions": [] } ```

resume_context

Write · Ordinary

Session continuity bundle: handoff pack plus unresolved questions, chunks awaiting human input, and recently changed facts. Call it to resume work where the last session left off.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `include_open_questions`, `session_id`. - `include_open_questions`. Note: Defaults true; false skips the open-question scan. - `session_id`. Note: Malformed ids fail with the session_save vocabulary; unowned ids read as session not found with no owner oracle. Absent means a general handoff with no session data.
Result
Object with session_id (null when absent), open_questions (up to 20 with text, type, priority, chunk title), changed_facts_since_last_session (up to 20), chunks_awaiting_human (up to 10), pack (pack_id, token_usage, freshness_score, body), and a summary string.
Boundaries
A supplied session must be owned by the caller (star bypasses). Open questions, awaiting chunks, and recent facts are global scans inside the selected profile boundary.
Lifecycle
Builds and persists a handoff pack with a run-history entry, then reads the top 20 open questions, top 10 awaiting chunks, and facts changed in the last 7 days. Read-shaped but persisted through the pack, hence write access.
Errors
Malformed session_id returns a normal session-must-be-UUID error. Unowned sessions return session not found. Backend failures surface as transport errors.
Example
```json { "include_open_questions": true } ``` Result shape: ```json { "chunks_awaiting_human": [], "open_questions": [], "pack": { "body": "...", "freshness_score": 0.5, "pack_id": "<uuid>", "token_usage": 400 }, "summary": "Session resume: 0 open questions, 0 chunks awaiting human, 0 recently changed facts." } ```

session_recall

Read · Ordinary

Recalls recent session snapshots, newest first. The resume path: pick up project, summary, active files, and timestamps from earlier runs.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `last_n`. - `last_n`. Note: How many sessions to return (default 5). Integers, integral floats, and booleans are accepted; other types are rejected.
Result
JSON object with sessions (session_id, project, summary, active_files as a list or null, started_at, ended_at, each null where unset) and count. No visible scope returns sessions [] with count 0.
Boundaries
Only sessions inside the caller's project grants are returned, and callers without star scope see only sessions owned by their own principal. Anything else reads as an empty list, never a denial.
Lifecycle
Pure read; recalling changes nothing about the sessions returned.
Errors
Bad last_n types are rejected (strict validator). Unknown arguments are rejected.
Example
```json { "last_n": 5 } ``` Result shape: ```json { "count": 1, "sessions": [ { "active_files": null, "ended_at": "<iso-8601>", "project": "shared-ops", "session_id": "<uuid>", "started_at": "<iso-8601>", "summary": "Pack README drafted; left proofing for next run." } ] } ```

session_save

Write · Ordinary

Saves a session snapshot, creating it on first call and updating it on later calls with the same id. The durable handoff surface: project, summary, and active files persist beyond the current run.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `active_files`, `project`, `session_id`, `summary`. - `active_files`. Note: Empty, missing, or null stores as null; otherwise the file list is stored as JSON text. - `project`. Note: Supplied projects must be granted now. An omitted project on creation is an untagged write needing the untagged grant; on update, unmentioned fields are left untouched. - `session_id`. Note: Omit or blank for a fresh server-assigned UUID; a malformed explicit id is rejected. All forms the platform UUID parser accepts are honored. - `summary`.
Result
JSON object with action (created or updated) and session_id. Denied updates answer with an error object reading session not found rather than revealing the session.
Boundaries
A session's current project must be writable by the caller, and callers without star scope may only touch sessions owned by their own principal; anything else reads as session not found. Operates only inside the caller's profile boundary.
Lifecycle
Create-or-update by session id through one atomic unit, recording the write with the caller's identity. ended_at is always stamped to the current time on both paths; updates keep prior project, summary, and file values wherever the call supplies nothing.
Errors
Bad session_id, project, summary, or active_files types are rejected (strict validator). A malformed session_id answers session_id must be a UUID returned by session_save. Out-of-scope projects and foreign sessions deny generically. Failures persist nothing (atomic).
Example
```json { "project": "shared-ops", "summary": "Pack README drafted; left proofing for next run." } ``` Result shape: ```json { "action": "created", "session_id": "<uuid>" } ``` session_id is assigned by the server when omitted; the placeholder stands for the returned UUID.

sessions_list

Read · Ordinary

Recent sessions, optional project.

Full documentation →

Arguments, result and boundaries
Arguments
Optional: `limit`, `project`. - `limit`. Note: Max rows (1-100, default 100). - `project`. Note: Project filter; empty lists visible scope.
Result
JSON object with sessions array and count.
Boundaries
Project-scoped reads; foreign projects read empty. Caller-owned rows only where applicable.
Lifecycle
Read-only; no rows written.
Errors
Bad types are rejected (strict validator). Failures move nothing (atomic).
Example
```json { "project": "x" } ``` Result shape: ```json { "count": 0, "sessions": [] } ```