# `advisor` tool reference The exact surface rpiv-advisor registers: the tool's schema, its result envelope, what gets sent to the reviewer, and the rules that decide when the tool is visible to the executor model. ## Signature ```ts advisor() // zero parameters ``` The parameter schema is an empty object. There is nothing for the executor model to pass — the conversation branch is read live from the session manager at call time and serialised automatically. ## What the reviewer receives Each call assembles the request in this order: 1. **Tool catalogue prefix** — one synthetic message listing every tool registered in the executor's session (Pi's `getAllTools()`, i.e. the full registry, not the active subset), as `name — first sentence of its description`. The advisor judges tool *choice* and never invokes an executor tool, so the JSON schemas are omitted: they were pure cost, and because this block is the first thing in every request, a schema edit in any installed extension used to invalidate the whole cached prefix. Cached and rebuilt only when names or descriptions change. 2. **The executor ledger** — the branch compiled per entry, read from the raw session rather than Pi's resolved LLM context (the ledger needs entry IDs for its card handles, and it recovers the user's pre-compaction words that Pi's builder replaces with a summary). - Every user message, verbatim. Images are referenced, never embedded: a tool-produced image is named by its card so the advisor can `read` that path, while a terminal paste (which has no path in Pi's `ImageContent`) is reported as unviewable. Nothing embedded could be evicted from the prefix later, so nothing is embedded. - Older tool rounds as one-line cards: `#id tool · argument · status · size · ✗ error`. - The newest `ledger.tailToolCalls` rounds verbatim, plus the executor reasoning for the step that triggered this consultation. - Compaction and branch summaries labelled as Pi's paraphrase, with the user's literal words from that span re-stated ahead of them. - Extension messages hidden from the user, and `!!` shell runs excluded from the executor's own context, are withheld from the advisor too. 3. **Past consultations** — each completed consultation contributes the executor's question and, as the only assistant turns in the request, the advice that answered it. A delivered [completion review](./configuration.md#review) contributes its answer the same way, under a review marker instead of a question. Failed, aborted and skipped consultations are omitted. The in-flight call's prose becomes the current question, and the request always ends on an instruction, never on a pending action. The answer opens with one verdict line — `Severity: none`, `nit`, `concern` or `blocker` — followed by the plan or correction. `none` is the expected answer when nothing material is wrong, so a check-in before declaring done can come back as one sentence instead of manufactured advice. Executor activity is always DATA inside a user-role ``; only the advisor's own past advice takes the assistant role. Replaying executor turns as assistant turns invited the reviewer to continue the transcript instead of answering it, and to narrate the executor's work as its own. Because each block is compiled from ONE entry, rendering a prefix of the branch yields a prefix of the full render: consecutive consultations share a byte-identical leading prefix, which is what provider prompt caching matches on. The verbatim tail is the only part whose shape changes between calls, and it sits last. The request uses `sessionId: "advisor:"` on both runtime and legacy dispatch paths, including retries. No cache retention setting is forced. Replayed over 1500 real consultations, this cut total prompt tokens by 89.5% (385.2M to 40.5M; median request 183.7k to 21.3k tokens), with every user message preserved and no request larger than the payload it replaced. ## Investigation tools The advisor is invoked with the advisor system prompt, its own read-only tool declarations, and the configured reasoning effort. Because older rounds arrive as cards, it can retrieve the evidence itself: | Tool | Answers | | --- | --- | | `advisor_expand({ids})` | what HAPPENED — the verbatim text behind a card | | `read` / `grep` / `find` / `ls` | what IS — the workspace's current state, including an image at a path | | `git_diff({path, patch, staged})` | the net change, `--stat` unless `patch: true` | Rounds are bounded by `tools.maxRounds` and priced against the same per-call and branch budgets as the first request. When the allowance runs out the declarations are left unchanged — withdrawing them would rewrite the head of the cached prefix — and the advisor is told in-band to answer with what it has. Investigation rounds are never replayed into later consultations; only the final advice enters the ledger. Paths must resolve inside the session cwd, and credential-shaped files are refused; see [tools](./configuration.md#tools). No mutating tool is ever declared, so the advisor cannot edit files, run commands, or write to your transcript — its answer comes back only as the tool result the executor reads. The default prompt guidelines direct the executor to restate the advisor's key guidance in its next visible reply, so the guidance is not left only in a collapsed tool card. While the call is in flight the executor streams `Consulting advisor (