@juicesharp/rpiv-advisor 2.0.0 → 2.2.0

package/README.md

@@ -1,78 +1,127 @@
-# rpiv-advisor
+# @juicesharp/rpiv-advisor
+
+[![npm version](https://img.shields.io/npm/v/@juicesharp/rpiv-advisor.svg)](https://www.npmjs.com/package/@juicesharp/rpiv-advisor)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 <div align="center">
   <a href="https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-advisor">
     <picture>
-      <img src="https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-advisor/docs/cover.png" alt="rpiv-advisor cover" width="50%">
+      <img src="https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-advisor/docs/cover.png" alt="rpiv-advisor cover: an executor model calling advisor() and a stronger reviewer answering with a plan, a correction, or a stop signal" width="50%">
     </picture>
   </a>
 </div>
 
-Let the model ask a stronger model for a second opinion before it acts. `rpiv-advisor` adds the `advisor` tool and `/advisor` slash command to [Pi Agent](https://github.com/badlogic/pi-mono) - the working model can hand the full conversation to a reviewer (e.g. Opus) and resume with its plan, correction, or stop signal.
-
-![Advisor model selector](https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-advisor/docs/advisor.jpg)
-
-## Features
-
-- **Reviewer model selector** - `/advisor` opens a picker over any model in Pi's registry, plus a reasoning-effort picker for reasoning-capable models. Start typing to fuzzy-filter the list by model name or `provider/id`.
-- **Persisted across sessions** - selection saved at `~/.config/rpiv-advisor/advisor.json` (chmod 0600).
-- **Off by default** - the `advisor` tool is excluded until you pick a model; choose "No advisor" to disable.
-- **Per-executor blocklist** - list executor models in `disabledForModels` (in `advisor.json`) to strip the `advisor` tool when those models drive the session. Entries can be plain strings (block at any effort) or `{ "model": "<provider:id>", "minEffort": "<level>" }` to block only when the executor's effort meets or exceeds the threshold. Available levels, lowest to highest: `minimal`, `low`, `medium`, `high`, `xhigh`.
-- **Zero-parameter handoff** - calling `advisor` forwards the full serialized conversation branch; no manual prompt needed.
+Let the model you're working with hand its whole conversation to a second, stronger model and get back a plan, a correction, or a stop signal — then keep going. `rpiv-advisor` adds the zero-parameter `advisor` tool and the `/advisor` picker to [Pi Agent](https://github.com/badlogic/pi-mono), so you can drive a session with a fast model and keep a stronger reviewer one call away.
 
 ## Install
 
-```bash
+```sh
 pi install npm:@juicesharp/rpiv-advisor
 ```
 
-Then restart your Pi session.
+Restart your Pi session.
+
+## Quick start
+
+Nothing happens until you pick a reviewer. Run:
 
-## Usage
+```
+/advisor
+```
 
-Configure an advisor model with `/advisor` - the command opens a selector for
-any model registered with Pi's model registry, plus a reasoning-effort picker
-for reasoning-capable models. Selection persists across sessions at
-`~/.config/rpiv-advisor/advisor.json` (chmod 0600).
+You get a picker over every model Pi already has credentials for — start typing
+to filter it by model name, provider, or `provider/id`. Pick one, and if it
+supports reasoning you get a second picker for its effort level (`high` is
+recommended). Pi confirms with `Advisor: <model>, <effort>`, and the `advisor`
+tool goes live for this and every future session.
+
+If the model you want isn't in the list, its provider isn't authenticated yet —
+run Pi's `/login` for that provider, then re-run `/advisor`.
+
+![The /advisor picker: a bordered panel titled "Advisor Tool" above a scrollable list of the models Pi has credentials for, with the current selection highlighted](https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-advisor/docs/advisor.jpg)
+
+From there the executor model calls `advisor()` on its own when it needs stronger
+judgment. To turn it back off, run `/advisor` and choose **No advisor**.
+
+## What you get
+
+- **A second opinion without leaving the session** — the executor calls
+  `advisor()` mid-turn, reads the reviewer's answer as the tool result, and
+  resumes. Nothing is injected into your transcript, and the default prompt
+  guidelines tell the executor to restate the advisor's key guidance in its
+  next visible reply, so you are not left with only a collapsed tool card.
+- **Nothing to type or paste** — the tool takes zero parameters. The whole
+  conversation branch is serialised and forwarded automatically: the task, every
+  tool call made, every result seen. That whole branch is billed against the
+  reviewer model on every call, so escalations are not free.
+- **The reviewer sees what survived compaction** — the branch is built from Pi's
+  resolved LLM context, so compaction and branch summaries are forwarded instead
+  of a stale raw replay.
+- **Any model can be the reviewer** — every model you're authenticated for is in
+  the `/advisor` picker, found by fuzzy-typing. No provider is privileged.
+- **Pick once, it stays picked** — model and effort persist to `advisor.json`
+  and are re-applied at every session start.
+- **Skip it when you're already on a strong model** — list executor models in
+  `disabledForModels` to strip the tool for them, optionally only at or above a
+  reasoning-effort threshold. It strips and re-adds live as you switch model or
+  effort mid-session.
+- **Off costs nothing** — with no model selected the tool is stripped from the
+  active set, so its prompt text never enters the system prompt at all.
+
+## Configuration
+
+Settings live in `~/.config/rpiv-advisor/advisor.json` (or
+`$XDG_CONFIG_HOME/rpiv-advisor/advisor.json` when that variable is set to an
+absolute path). `/advisor` creates the file and chmods it to `0600`; a failed
+write leaves your previous selection untouched and tells you so.
+
+| Key | What it does | Default |
+| --- | --- | --- |
+| `modelKey` | The reviewer model, as `"provider/modelId"`. Written by `/advisor`. | absent — advisor off |
+| `effort` | Reasoning effort for the reviewer: `minimal`, `low`, `medium`, `high`, `xhigh`. Written by `/advisor`. | absent — no reasoning sent |
+| `disabledForModels` | Executor models the advisor is stripped for. Plain strings block at any effort; `{ "model": "…", "minEffort": "…" }` blocks only at or above that effort. | `[]` |
+
+```json
+{
+  "modelKey": "anthropic/claude-opus-4-5",
+  "effort": "high",
+  "disabledForModels": [
+    "anthropic/claude-opus-4-5",
+    { "model": "openai/gpt-5.2", "minEffort": "high" }
+  ]
+}
+```
 
-The `advisor` tool is registered at load but excluded from active tools by
-default; selecting a model via `/advisor` enables it. Choose "No advisor" to
-disable.
+`/advisor` only rewrites `modelKey` and `effort`, so hand-edited keys —
+`disabledForModels` and the `guidance` overrides — survive every save.
 
-`advisor` takes zero parameters - calling it forwards the full serialized
-conversation branch to the advisor model, which returns guidance (plan,
-correction, or stop signal) that the executor consumes.
+## Reference
 
-## Tool
+- [Configuration](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-advisor/docs/configuration.md) — config file resolution, every key, blocklist matching rules, guidance overrides, and the full notification catalogue.
+- [`advisor` tool reference](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-advisor/docs/tool-reference.md) — schema, result envelope, failure paths, what gets sent to the reviewer, lifecycle hooks, and picker keys.
 
-- **`advisor`** - escalate the current conversation branch to the configured reviewer model. Inactive until a model is selected via `/advisor`.
+## Requirements
 
-### Schema
+- A [Pi Agent](https://github.com/badlogic/pi-mono) host — the extension loads
+  through Pi's extension manifest. No native dependencies.
+- An authenticated provider for the **reviewer** model, resolved through Pi's
+  model registry.
+- An interactive terminal for `/advisor`.
 
-```ts
-advisor() // zero parameters
-```
+## Troubleshooting
 
-The full conversation branch is auto-serialized from `ctx.sessionManager` - the LLM does not (and cannot) pass it explicitly.
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| The `/advisor` picker offers only **No advisor** | No provider is authenticated in Pi | Run Pi's `/login` for a provider, then re-run `/advisor` |
+| `Advisor (<model>) has no API key available.` comes back as the tool result | Credentials for the reviewer's provider no longer resolve | Re-authenticate that provider with `/login` |
+| `/advisor requires interactive mode` | Running under `pi --print …` or RPC | Run Pi interactively |
 
-Returns:
+## Related
 
-```ts
-{
-  content: [{ type: "text", text: string }], // reviewer's guidance, or error message
-  details: {
-    advisorModel?: string,        // "<provider>:<modelId>"
-    effort?: ThinkingLevel,       // reasoning effort, when applicable
-    usage?: Usage,                // token usage from the side-call
-    stopReason?: StopReason,      // pi-ai stop reason
-    errorMessage?: string,        // populated on auth/abort/error/empty paths
-  }
-}
-```
+- [`@juicesharp/rpiv-pi`](https://www.npmjs.com/package/@juicesharp/rpiv-pi) —
+  the umbrella package; its `code-review` skill calls `advisor()` when this
+  package is installed.
 
 ## License
 
-[![npm version](https://img.shields.io/npm/v/@juicesharp/rpiv-advisor.svg)](https://www.npmjs.com/package/@juicesharp/rpiv-advisor)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-MIT
+MIT — see [LICENSE](https://github.com/juicesharp/rpiv-mono/blob/main/packages/rpiv-advisor/LICENSE).

package/advisor/execute.ts

@@ -6,7 +6,7 @@
  * buildAdvisorResult so the envelope is built in exactly one place.
  */
 
-import type { Message, StopReason, ThinkingLevel, Usage } from "@earendil-works/pi-ai";
+import type { AssistantMessage, Message, StopReason, TextContent, ThinkingLevel, Usage } from "@earendil-works/pi-ai";
 import {
 	type AgentToolResult,
 	type AgentToolUpdateCallback,
@@ -31,7 +31,7 @@ import {
 	errNoApiKeyDetail,
 	msgConsulting,
 } from "./messages.js";
-import { loadCompleteSimple } from "./pi-compat.js";
+import { getRuntimeCompleteSimple, loadCompleteSimple } from "./pi-compat.js";
 import { ADVISOR_SYSTEM_PROMPT } from "./prompt.js";
 import { getAdvisorEffort, getAdvisorModel } from "./state.js";
 
@@ -43,6 +43,18 @@ interface AdvisorDetails {
 	errorMessage?: string;
 }
 
+// Extract the advisor's text content from a completeSimple response: concatenate
+// every text part, trim. Thinking/toolCall parts are ignored. Returns "" when the
+// model returned no text content — the empty-response class R6.4 retries once
+// before surfacing. Pure so both attempts share one extraction path.
+function advisorTextFromResponse(response: AssistantMessage): string {
+	return response.content
+		.filter((c): c is TextContent => c.type === "text")
+		.map((c) => c.text)
+		.join("\n")
+		.trim();
+}
+
 // Single result-envelope builder — every executeAdvisor branch and the pre-call
 // error paths funnel through here. `effort` is snapshotted once at executeAdvisor
 // entry and threaded through every call so the returned details.effort always
@@ -117,52 +129,83 @@ export async function executeAdvisor(
 	});
 
 	try {
-		const completeSimple = await loadCompleteSimple();
-		const response = await completeSimple(
-			advisor,
-			// `tools: []` reaffirms the "never calls tools" contract even when
-			// `messages` contains prior toolCall/toolResult blocks (btw.ts:235).
-			{ systemPrompt: ADVISOR_SYSTEM_PROMPT, messages, tools: [] },
-			{ apiKey: auth.apiKey, headers: auth.headers, signal, reasoning: effort },
-		);
-
-		if (response.stopReason === "aborted") {
-			return buildAdvisorResult({
-				text: ERR_CALL_ABORTED,
-				effort,
-				advisorLabel,
-				usage: response.usage,
-				stopReason: response.stopReason,
-				errorMessage: response.errorMessage ?? ERR_ABORTED_DETAIL,
-			});
-		}
+		// Prefer Pi's auth-aware runtime facade. Unlike the global compatibility
+		// function, it runs request preparation and applies credential-derived
+		// fields such as GitHub Copilot's OAuth-specific baseUrl. Do not pass the
+		// preflight key/headers to this path: explicit overrides would bypass that
+		// resolution and reintroduce the endpoint mismatch.
+		const runtimeCompleteSimple = getRuntimeCompleteSimple(ctx.modelRegistry);
+		const completeSimple = runtimeCompleteSimple ?? (await loadCompleteSimple());
+		const requestOptions = runtimeCompleteSimple
+			? { signal, reasoning: effort }
+			: { apiKey: auth.apiKey, headers: auth.headers, signal, reasoning: effort };
 
-		if (response.stopReason === "error") {
-			return buildAdvisorResult({
-				text: errCallFailed(response.errorMessage),
-				effort,
-				advisorLabel,
-				usage: response.usage,
-				stopReason: response.stopReason,
-				errorMessage: response.errorMessage,
-			});
-		}
+		// Single dispatch point — both attempts reuse the SAME `messages` and
+		// `requestOptions`, so the retry cannot diverge from attempt 1. `tools: []`
+		// reaffirms the "never calls tools" contract even when `messages` contains
+		// prior toolCall/toolResult blocks (btw.ts:235).
+		const callAdvisor = (): Promise<AssistantMessage> =>
+			completeSimple(advisor, { systemPrompt: ADVISOR_SYSTEM_PROMPT, messages, tools: [] }, requestOptions);
+
+		// Build the terminal envelope for an aborted/error stopReason, or return
+		// undefined when the attempt produced a normal stop whose text (or lack of
+		// text) the caller must still resolve. Aborted/error short-circuit and are
+		// NEVER retried — they are not the empty-response class R6.4 targets.
+		const stopReasonEnvelope = (r: AssistantMessage): AgentToolResult<AdvisorDetails> | undefined => {
+			if (r.stopReason === "aborted") {
+				return buildAdvisorResult({
+					text: ERR_CALL_ABORTED,
+					effort,
+					advisorLabel,
+					usage: r.usage,
+					stopReason: r.stopReason,
+					errorMessage: r.errorMessage ?? ERR_ABORTED_DETAIL,
+				});
+			}
+			if (r.stopReason === "error") {
+				return buildAdvisorResult({
+					text: errCallFailed(r.errorMessage),
+					effort,
+					advisorLabel,
+					usage: r.usage,
+					stopReason: r.stopReason,
+					errorMessage: r.errorMessage,
+				});
+			}
+			return undefined;
+		};
 
-		const advisorText = response.content
-			.filter((c): c is { type: "text"; text: string } => c.type === "text")
-			.map((c) => c.text)
-			.join("\n")
-			.trim();
+		let response = await callAdvisor();
 
+		// Aborted/error short-circuit on the first attempt — no retry.
+		const firstTerminal = stopReasonEnvelope(response);
+		if (firstTerminal) return firstTerminal;
+
+		let advisorText = advisorTextFromResponse(response);
+
+		// R6.4: a transient empty advisor response (normal stop, no text) gets
+		// exactly ONE retry with identical inputs before surfacing as a terminal
+		// error. Bounded to a single second call — never a `while`/loop — so a
+		// persistent-empty provider cannot hot-loop. The retry reuses the SAME
+		// pre-computed `messages`/`requestOptions` (no re-derivation that could
+		// diverge from attempt 1), then applies the same three-way route.
 		if (!advisorText) {
-			return buildAdvisorResult({
-				text: ERR_EMPTY_RESPONSE,
-				effort,
-				advisorLabel,
-				usage: response.usage,
-				stopReason: response.stopReason,
-				errorMessage: ERR_EMPTY_RESPONSE_DETAIL,
-			});
+			response = await callAdvisor();
+
+			const retryTerminal = stopReasonEnvelope(response);
+			if (retryTerminal) return retryTerminal;
+
+			advisorText = advisorTextFromResponse(response);
+			if (!advisorText) {
+				return buildAdvisorResult({
+					text: ERR_EMPTY_RESPONSE,
+					effort,
+					advisorLabel,
+					usage: response.usage,
+					stopReason: response.stopReason,
+					errorMessage: ERR_EMPTY_RESPONSE_DETAIL,
+				});
+			}
 		}
 
 		return buildAdvisorResult({

package/advisor/pi-compat.test.ts

@@ -9,6 +9,30 @@
  */
 
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { getRuntimeCompleteSimple } from "./pi-compat.js";
+
+describe("getRuntimeCompleteSimple", () => {
+	it("returns a method bound to the host runtime", async () => {
+		const runtime = {
+			completeSimple: vi.fn(function (this: unknown) {
+				expect(this).toBe(runtime);
+				return Promise.resolve(undefined as never);
+			}),
+		};
+		const completeSimple = getRuntimeCompleteSimple({ runtime });
+
+		expect(completeSimple).toBeTypeOf("function");
+		if (!completeSimple) throw new Error("expected runtime completion facade");
+		await completeSimple(undefined as never, undefined as never);
+		expect(runtime.completeSimple).toHaveBeenCalledOnce();
+	});
+
+	it("returns undefined for missing or malformed runtime facades", () => {
+		expect(getRuntimeCompleteSimple(undefined)).toBeUndefined();
+		expect(getRuntimeCompleteSimple({ runtime: null })).toBeUndefined();
+		expect(getRuntimeCompleteSimple({ runtime: { completeSimple: "not-a-function" } })).toBeUndefined();
+	});
+});
 
 describe("loadCompleteSimple", () => {
 	afterEach(() => {

package/advisor/pi-compat.ts

@@ -18,6 +18,32 @@
 
 type CompleteSimpleFn = typeof import("@earendil-works/pi-ai/compat").completeSimple;
 
+/**
+ * Resolve Pi's auth-aware completion facade when the host exposes one.
+ *
+ * Current Pi hosts keep the canonical `ModelRuntime` behind the extension
+ * `ModelRegistry`'s runtime-private `runtime` slot. This structural bridge is
+ * intentionally isolated here: calling that facade is what lets Pi apply
+ * credential-derived request fields such as GitHub Copilot's OAuth-specific
+ * `baseUrl`. Older hosts, and future hosts that move the slot, simply fall
+ * through to the legacy global completion path below.
+ *
+ * The returned method is bound because `ModelRuntime.completeSimple()` calls
+ * other runtime methods through `this`.
+ */
+export function getRuntimeCompleteSimple(modelRegistry: unknown): CompleteSimpleFn | undefined {
+	try {
+		if (modelRegistry === null || typeof modelRegistry !== "object") return undefined;
+		const runtime = (modelRegistry as { runtime?: unknown }).runtime;
+		if (runtime === null || typeof runtime !== "object") return undefined;
+		const completeSimple = (runtime as { completeSimple?: unknown }).completeSimple;
+		return typeof completeSimple === "function" ? (completeSimple.bind(runtime) as CompleteSimpleFn) : undefined;
+	} catch {
+		// A malformed/private host shape should retain the version-tolerant fallback.
+		return undefined;
+	}
+}
+
 /**
  * Error codes meaning "the /compat entrypoint is not resolvable on this host":
  *   - `ERR_PACKAGE_PATH_NOT_EXPORTED` — Node's ESM resolver when the installed

package/advisor/register.ts

@@ -31,6 +31,7 @@ export const DEFAULT_PROMPT_GUIDELINES: string[] = [
 	"On tasks longer than a few steps, call `advisor` at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes.",
 	"Give the advisor's advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim, adapt — a passing self-test is not evidence the advice is wrong, it's evidence your test doesn't check what the advice is checking.",
 	"If you've already retrieved data pointing one way and the advisor points another, don't silently switch — surface the conflict in one more `advisor` call (\"I found X, you suggest Y, which constraint breaks the tie?\"). A reconcile call is cheaper than committing to the wrong branch.",
+	"After each `advisor` result, put the advisor's key guidance into your next visible reply to the user before continuing — quote or paraphrase the plan, correction, or stop signal. The user often cannot see collapsed tool results; do not keep the advisor's words only in silent tool context.",
 ];
 
 export function registerAdvisorTool(pi: ExtensionAPI): void {

package/docs/configuration.md

@@ -0,0 +1,142 @@
+# rpiv-advisor configuration
+
+Complete reference for `advisor.json` — where it lives, every key it accepts, and how the per-executor blocklist is evaluated.
+
+## Where the file lives
+
+`advisor.json` resolves under the XDG config directory:
+
+| `XDG_CONFIG_HOME` | Resolved path |
+| --- | --- |
+| unset, empty, or whitespace-only | `~/.config/rpiv-advisor/advisor.json` |
+| absolute path | `$XDG_CONFIG_HOME/rpiv-advisor/advisor.json` |
+| `~` or `~/…` | tilde expanded, then used as the config dir |
+| relative path | ignored → `~/.config/rpiv-advisor/advisor.json` |
+| `~user/…` | not expanded → `~/.config/rpiv-advisor/advisor.json` |
+
+`XDG_CONFIG_HOME` is the only environment variable this package reads.
+
+**Legacy read fallback.** If nothing exists at the XDG-resolved path, reads fall
+back once to `~/.config/rpiv-advisor/advisor.json` (always `~/.config`, ignoring
+`XDG_CONFIG_HOME`). If the XDG path *does* exist, it wins — even when it is
+malformed. **Writes always go to the XDG-resolved path only**; there is no
+migration or copy of the legacy file.
+
+A missing or malformed file is treated as `{}` — malformed JSON logs a warning
+and never crashes the extension.
+
+## File permissions
+
+`/advisor` writes the file with `JSON.stringify(config, null, 2)` plus a
+trailing newline, creating parent directories as needed, then chmods it to
+`0600` on a best-effort basis. A failed chmod does not fail the save; on Windows
+the chmod is a no-op.
+
+Saving happens **before** any in-memory state changes. If the write fails you
+get `Failed to save advisor selection — selection not persisted` and both the
+previous selection and the active tool list are left untouched.
+
+## Keys
+
+| Key | Type | Default | Written by |
+| --- | --- | --- | --- |
+| `modelKey` | `string` — `"provider/modelId"` | absent (advisor off) | `/advisor` |
+| `effort` | `"minimal" \| "low" \| "medium" \| "high" \| "xhigh"` | absent (no `reasoning` sent) | `/advisor` effort picker |
+| `disabledForModels` | `(string \| { model, minEffort? })[]` | `[]` | hand-edited |
+| `guidance.promptSnippet` | `string` | built-in snippet | hand-edited |
+| `guidance.promptGuidelines` | `string[]` | six built-in guidelines | hand-edited |
+
+`/advisor` only ever writes `modelKey` and `effort`; `guidance` and
+`disabledForModels` are preserved across saves, so hand-edits survive.
+
+### `modelKey`
+
+The canonical persisted form is slash-separated — `anthropic/claude-opus-4-5`.
+Reads also accept the legacy colon form (`anthropic:claude-opus-4-5`); when both
+forms are present the slash form wins. A colon-form key is rewritten to slash
+form the next time you save through `/advisor`.
+
+### `effort`
+
+Offered only for models whose registry entry reports reasoning support. The
+picker lists `off`, `minimal`, `low`, `medium`, `high`, and adds `xhigh` when
+the picked model supports it. `high` is marked `(recommended)`. Choosing `off`
+deletes the key, and no `reasoning` parameter is sent with the advisor call.
+
+`EFFORT_ORDINAL`, lowest to highest, is `minimal`, `low`, `medium`, `high`,
+`xhigh`. This ordering is what `minEffort` compares against.
+
+### `disabledForModels`
+
+A list of **executor** models for which the advisor tool should be stripped —
+useful when you are already driving a top-tier model and do not want to pay for
+a second opinion. Two entry forms:
+
+```json
+{
+  "modelKey": "anthropic/claude-opus-4-5",
+  "effort": "high",
+  "disabledForModels": [
+    "anthropic/claude-opus-4-5",
+    { "model": "openai/gpt-5.2", "minEffort": "high" }
+  ]
+}
+```
+
+- **String entry** — blocks at any reasoning effort.
+- **Object entry without `minEffort`** — blocks at any reasoning effort.
+- **Object entry with `minEffort`** — blocks when the executor's current effort
+  is at or above the threshold in `EFFORT_ORDINAL`. Ties block.
+- An executor effort of `off` or unset never matches a `minEffort` entry.
+
+Entry keys are canonicalised to slash form before comparison, so a legacy
+`"anthropic:claude-opus-4-5"` entry still blocks without a re-save.
+
+**Validation.** A non-array value becomes `[]`. Empty strings are dropped.
+Object entries need a non-empty string `model`; an unrecognised `minEffort`
+drops the entry. `null`, numbers, booleans and `undefined` are dropped. The
+order of surviving entries is preserved.
+
+**Live re-evaluation.** The blocklist is re-applied on `session_start`, on every
+turn, whenever you switch executor model, and whenever you change reasoning
+effort — so the tool strips and re-adds mid-session as you move around. You see
+`Advisor disabled for <provider/model>` when it strips and
+`Advisor restored: <label>[, <effort>]` when it comes back.
+
+### `guidance`
+
+Overrides what the executor model is told about *when* to escalate, without
+forking the package.
+
+- `guidance.promptSnippet` — a non-empty string replacing the one-line snippet
+  that appears in the system prompt.
+- `guidance.promptGuidelines` — a non-empty array of non-empty strings replacing
+  the six built-in guidelines.
+
+Either field falls back to its built-in default when absent, empty, or the wrong
+type. Both are read once at extension load, so restart your Pi session after
+editing them.
+
+The built-in guidelines tell the model to call `advisor` before substantive
+work, again when it believes the task is complete (after making the deliverable
+durable), and when it is stuck or considering a change of approach; to weight
+the advice seriously unless empirically contradicted; and to reconcile
+conflicting evidence with one more `advisor` call rather than silently switching.
+
+## Notifications
+
+| String | When |
+| --- | --- |
+| `Advisor: <label>[, <effort>]` | you selected a model with `/advisor` |
+| `Advisor: <label>[, <effort>] (inactive for current executor)` | selected, but blocked by `disabledForModels` |
+| `Advisor restored: <label>[, <effort>]` | re-applied at session start, or unblocked mid-session |
+| `Advisor restored: <label>[, <effort>] (inactive for current executor)` | restored while blocked |
+| `Advisor disabled` | you chose **No advisor** |
+| `Advisor disabled for <provider/model>` | you switched to a blocklisted executor model or effort |
+| `Advisor selection not found: <choice>` | the model you picked was no longer in the available-model list when `/advisor` resolved the choice |
+| `Previously configured advisor model <key> is no longer available` | the saved model left Pi's registry |
+| `Failed to save advisor selection — selection not persisted` | the write to `advisor.json` failed |
+| `/advisor requires interactive mode` | `/advisor` ran without a TTY |
+
+The `Advisor restored: …` announcement fires at most once per process, so
+programmatic session spawns (workflow stages, subagents) do not repeat it.

package/docs/tool-reference.md

@@ -0,0 +1,140 @@
+# `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 inventory 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), so the reviewer knows what the executor can
+   do. It is cached and only rebuilt when the registered tool-name set changes;
+   the JSON is key-sorted so identical inventories serialise byte-identically
+   and stay prompt-cache friendly.
+2. **The conversation branch** — built from Pi's resolved LLM context, not a raw
+   replay of history. Compaction summaries and branch summaries are forwarded as
+   the model actually sees them, so a compacted session sends the summary rather
+   than the pre-compaction detail.
+3. **Tail massaging** — the in-flight `advisor()` tool call is stripped from the
+   tail, and a user-role message is guaranteed at the end (falling back to
+   `Please advise on the executor's situation above.`) so providers that reject
+   non-user tails accept the payload.
+
+The reviewer is invoked with the advisor system prompt, `tools: []`, and the
+configured reasoning effort. It never calls tools and never writes 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 (<label>[, <effort>])…`.
+
+## Result envelope
+
+```ts
+{
+  content: [{ type: "text", text: string }], // reviewer's guidance, or an error message
+  details: {
+    advisorModel?: string,   // "<provider>:<modelId>" — colon-joined
+    effort?: ThinkingLevel,  // the reasoning level actually sent
+    usage?: Usage,           // token usage from the side-call
+    stopReason?: StopReason, // pi-ai stop reason
+    errorMessage?: string,   // populated on the no-model/auth/abort/error/empty paths
+  }
+}
+```
+
+`details.effort` is snapshotted once at entry, so it always matches the
+`reasoning` value sent to the provider even if the selection changes mid-call.
+
+Note that `details.advisorModel` uses the **colon** form (`provider:modelId`),
+unlike the slash-form `modelKey` persisted in `advisor.json`.
+
+## Failure paths
+
+Every failure returns a normal tool result — the executor reads the text and
+keeps going rather than crashing the turn.
+
+| `content` text | `details.errorMessage` |
+| --- | --- |
+| `No advisor model is configured. The user can enable one with the /advisor command.` | `no advisor model selected` |
+| `Advisor (<label>) is misconfigured: <err>` | the registry's auth error |
+| `Advisor (<label>) has no API key available.` | `no API key for <provider>` |
+| `Advisor call was cancelled before it completed.` | the provider's error message, or `aborted` |
+| `Advisor call failed: <err>` | the provider's error message |
+| `Advisor returned no text content.` | `empty response` |
+| `Advisor call threw: <msg>` | the thrown message |
+
+## When the tool is active
+
+The tool is always **registered** — but it is stripped from the *active* tool
+set, meaning the executor model cannot see it and its `promptSnippet` /
+`promptGuidelines` drop out of the system prompt, whenever any of:
+
+1. No advisor model is selected.
+2. `modelKey` is absent, unparseable, or names a model that is no longer in Pi's
+   registry at restore time. The stale in-memory selection is cleared too.
+3. The current **executor** model matches a `disabledForModels` entry — see
+   [configuration.md](./configuration.md#disabledformodels).
+
+This is what "off costs nothing" means: with no model configured, none of the
+advisor's prompt text ever enters the system prompt.
+
+## Lifecycle hooks
+
+| Event | What happens |
+| --- | --- |
+| `session_start` | Reload `advisor.json`, re-apply model / effort / blocklist, activate or strip, announce once per process. |
+| `before_agent_start` | Per-turn reconcile: blocked when no model is selected or the executor is blocklisted. |
+| `model_select` | Re-reconcile on executor model change. Skipped for `source === "restore"` to avoid a duplicate notification. |
+| `thinking_level_select` | Re-reconcile on reasoning-effort change. |
+
+The three mid-session hooks route through a shared strip-or-add hub
+(`reconcileAdvisorTool`). `session_start` uses that hub for the strip path and
+adds the tool directly on the restore path.
+
+## `/advisor` picker keys
+
+Both pickers (model, then reasoning level) show up to 10 rows and share the hint
+`type to filter • ↑↓ navigate • enter select • esc cancel`.
+
+| Key | Effect |
+| --- | --- |
+| any printable character | appends to the fuzzy filter and rebuilds the list |
+| Backspace | deletes one character from the filter |
+| ↑ / ↓ | navigate; ↑ from the first row wraps to the last |
+| Enter | select |
+| Esc | cancel — the command exits without changing anything |
+
+The filter scores against both the visible label (`Name  (provider)`) and the
+underlying `provider/modelId` value, ranking contiguous runs and word-boundary
+matches higher — so `op4` and `anthropic` both narrow the list.
+
+`/advisor` requires an interactive TTY. Without one it notifies
+`/advisor requires interactive mode` and returns.
+
+## Host compatibility
+
+The reviewer call uses pi-ai's `completeSimple`, which moved between
+entrypoints across host versions: Pi ≥ 0.80.1 exports it from
+`@earendil-works/pi-ai/compat`, and ≤ 0.79.x from the package root. Because
+pi-ai resolves against the *host's* copy at runtime, the loader tries `/compat`
+first and falls back to the root **only** on a module-resolution failure
+(`ERR_PACKAGE_PATH_NOT_EXPORTED`, `ERR_MODULE_NOT_FOUND`, `MODULE_NOT_FOUND`,
+walked through the `cause` chain). Any other `/compat` error is rethrown so the
+real failure surfaces instead of being masked.
+
+If neither entrypoint exposes it, the call throws
+`pi-ai does not expose completeSimple on /compat or the package root — unsupported host pi-ai version`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@juicesharp/rpiv-advisor",
-	"version": "2.0.0",
+	"version": "2.2.0",
 	"description": "Pi extension. A second opinion the model can request from a stronger reviewer model before it acts.",
 	"keywords": [
 		"pi-package",
@@ -32,6 +32,10 @@
 		"advisor-ui.ts",
 		"fuzzy.ts",
 		"prompts/",
+		"docs/",
+		"!docs/*.png",
+		"!docs/*.jpg",
+		"!docs/*.svg",
 		"README.md",
 		"LICENSE"
 	],
@@ -41,7 +45,7 @@
 		]
 	},
 	"dependencies": {
-		"@juicesharp/rpiv-config": "^2.0.0",
+		"@juicesharp/rpiv-config": "^2.2.0",
 		"typebox": "^1.1.24"
 	},
 	"peerDependencies": {