pi-advisor-flow 0.1.4 → 0.1.6

package/README.md

@@ -43,7 +43,17 @@ Once installed, the following commands are available inside the Pi terminal:
 Enables the Advisor flow. Switches the primary model to the configured Executor model and registers the `ask_advisor` tool.
 
 - _Example:_ `/advisor executor=anthropic/claude-sonnet-5 advisor=openai/gpt-5.6-sol`
-- _Context size:_ `/advisor contextMaxChars=30000` uses up to 30,000 characters of the reconstructed conversation for each consultation. The default is 15,000; the maximum is 1,000,000. Larger values increase request cost and can exceed the advisor model's context window.
+- _Context size:_ `/advisor contextMaxChars=30000` uses up to 30,000 characters of the reconstructed conversation for each consultation. `0` disables history; `Number.MAX_SAFE_INTEGER` represents the complete branch. Larger values increase request cost and can exceed the Advisor model's context window.
+
+### `/advisor-manual [focus]`
+
+Starts an Advisor consultation in parallel without interrupting the Executor's active tool work. An optional `focus` is passed to the Advisor; when it completes, the advice is delivered to the Executor before its next model call. This works while the Executor is mid-turn.
+
+### `/advisor-settings`
+
+Opens a single keyboard-navigable settings screen. It includes a Claude Code-style context slider with `0`, `10k`, `25k`, `100k`, `200k`, and `ALL`; `0` sends no reconstructed history and `ALL` sends the complete current branch, subject to the Advisor model's context limit.
+
+It also configures Advisor reasoning effort, whether long Advisor responses collapse to a short preview (`Ctrl+O` expands them), and each built-in invocation gate independently (consequential plans, repeated failures, and completion review). Response collapsing is off by default. You can add one custom natural-language invocation rule. Settings persist in `advisor.json`.
 
 ### `/advisor-models`
 
@@ -60,20 +70,36 @@ The Executor can call `ask_advisor` with an empty object for a general review of
 
 ### Context configuration
 
-The selected configuration is saved as `advisor.json` in the Pi agent directory (or an existing trusted project configuration). Set `contextMaxChars` there to increase the reconstructed conversation limit for all consultations:
+The selected configuration is saved as `advisor.json` in the Pi agent directory (or an existing trusted project configuration). `/advisor-models` and `/advisor-settings` share this file:
 
 ```json
 {
-  "contextMaxChars": 30000
+  "executor": "aikeys/claude-sonnet-5",
+  "advisor": "aikeys/claude-fable-5",
+  "executorEffort": "high",
+  "advisorEffort": "high",
+  "contextMaxChars": 25000,
+  "advisorPlanGate": true,
+  "advisorFailureGate": true,
+  "advisorCompletionGate": true,
+  "advisorCollapseResponses": false,
+  "advisorCustomInvocation": "before changing a production deployment"
 }
 ```
 
-`contextMaxChars` must be a positive integer up to 1,000,000. Its default is 15,000.
+All fields are optional. `executor`, `advisor`, and their effort settings are managed by `/advisor-models`. `/advisor-settings` manages `advisorEffort`, `contextMaxChars`, the three gate booleans, `advisorCollapseResponses`, and `advisorCustomInvocation`. `contextMaxChars` must be a non-negative safe integer: its default is 15,000, `0` omits history, and `9007199254740991` means ALL.
 
 ### `/advisor-off`
 
 Disables the Advisor flow, removing the `ask_advisor` tool from the active session.
 
+## Publishing releases
+
+Pushing a version tag (`vX.Y.Z`) runs the release workflow. It verifies that the tag matches `package.json`, type-checks, tests, then publishes:
+
+- `pi-advisor-flow` to [npm](https://www.npmjs.com/package/pi-advisor-flow)
+- `@philipbrembeck/pi-advisor-flow` to GitHub Packages, which makes the package appear in this repository’s **Packages** sidebar
+
 ## Local Development
 
 `pi-advisor` uses Bun for rapid testing and TypeScript. Standard commands apply:
@@ -97,5 +123,5 @@ Verify code-splitting correctness and registration logic:
 
 ```bash
 bun test            # Run unit tests
-npm run typecheck   # Perform strict TS checks
+bun run typecheck   # Perform strict TS checks
 ```

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "pi-advisor-flow",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/philipbrembeck/pi-advisor.git"
+    "url": "https://github.com/philipbrembeck/pi-advisor.git"
   },
   "homepage": "https://github.com/philipbrembeck/pi-advisor",
   "author": "Philip Brembeck",

package/src/commands.ts

@@ -1,15 +1,86 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getMarkdownTheme, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Box, Markdown, Text } from "@earendil-works/pi-tui";
 import {
+  advisorCollapseResponsesRef, advisorCompletionGateRef, advisorCustomInvocationRef, advisorFailureGateRef, advisorPlanGateRef,
   advisorRef, advisorEffortRef, executorRef, executorEffortRef,
-  setAdvisorRef, setAdvisorEffortRef, setExecutorRef, setExecutorEffortRef,
-  loadConfig, saveConfig, parseArgs, splitRef,
+  setAdvisorCollapseResponsesRef, setAdvisorCompletionGateRef, setAdvisorCustomInvocationRef, setAdvisorFailureGateRef, setAdvisorPlanGateRef,
+  setAdvisorRef, setAdvisorEffortRef, setContextMaxCharsRef, setExecutorRef, setExecutorEffortRef,
+  contextMaxCharsRef, loadConfig, saveConfig, parseArgs, splitRef,
 } from "./config.js";
-import { SearchableModelSelector } from "./ui.js";
+import { AdvisorSettingsSelector, SearchableModelSelector, type AdvisorSettings, type ContextPreset } from "./ui.js";
+import { adviceForDisplay, consult, renderAdvisorCallBox, resolveAdvisorRequest } from "./tools.js";
 
 const EFFORT_LEVELS = ["Default (Model Default)", "off", "minimal", "low", "medium", "high", "xhigh", "max"];
 
-export const registerCommands = (pi: ExtensionAPI) => {
+const CONTEXT_PRESETS: ContextPreset[] = [
+  { label: "0", value: 0, description: "No conversation history. The Advisor receives only its standing instructions." },
+  { label: "10k", value: 10_000, description: "The most recent 10,000 characters of the current branch." },
+  { label: "25k", value: 25_000, description: "The most recent 25,000 characters of the current branch." },
+  { label: "100k", value: 100_000, description: "The most recent 100,000 characters of the current branch." },
+  { label: "200k", value: 200_000, description: "The most recent 200,000 characters of the current branch." },
+  { label: "ALL", value: Number.MAX_SAFE_INTEGER, description: "The complete reconstructed conversation branch. Cost and model context limits apply." },
+];
+
+export const registerCommands = (pi: ExtensionAPI, dependencies: { consult?: typeof consult } = {}) => {
   const flowEnabled = () => pi.getActiveTools().includes("ask_advisor");
+  const requestAdvisor = dependencies.consult ?? consult;
+  const manualConsultations = new Set<AbortController>();
+
+  pi.registerEntryRenderer?.("advisor-manual-call", (entry, _options, theme) => {
+    const { question } = (entry.data ?? {}) as { question?: string };
+    return renderAdvisorCallBox(question, theme);
+  });
+
+  pi.registerMessageRenderer?.("advisor-manual-result", (message, { expanded }, theme) => {
+    const details = message.details as { advisor?: string; text?: string } | undefined;
+    const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+    box.addChild(new Text(theme.fg("warning", theme.bold("◆ ADVISOR RESPONSE")), 0, 0));
+    if (details?.advisor) box.addChild(new Text(theme.fg("dim", `  ${details.advisor}`), 0, 0));
+    const advice = details?.text ?? (typeof message.content === "string" ? message.content : "(Advisor returned no advice.)");
+    box.addChild(new Markdown(adviceForDisplay(advice, expanded), 0, 0, getMarkdownTheme()));
+    return box;
+  });
+
+  pi.on("session_shutdown", () => {
+    for (const controller of manualConsultations) controller.abort();
+    manualConsultations.clear();
+  });
+
+  pi.registerCommand("advisor-manual", {
+    description: "Consult the Advisor in parallel; accepts an optional focused question and fans its response out to the Executor",
+    handler: async (args, ctx) => {
+      const question = resolveAdvisorRequest(args);
+      // A single visible progress surface avoids competing consultations overwriting
+      // each other's streamed state. A newer manual request replaces the previous one.
+      for (const pending of manualConsultations) pending.abort();
+      manualConsultations.clear();
+      const controller = new AbortController();
+      manualConsultations.add(controller);
+      pi.appendEntry?.("advisor-manual-call", { question });
+
+      void requestAdvisor(ctx, question, controller.signal)
+        .then(({ advice }) => {
+          if (controller.signal.aborted) return;
+          pi.sendMessage({
+            customType: "advisor-manual-result",
+            content: `Manual Advisor consultation${question ? ` (${question})` : ""}:\n\n${advice}`,
+            display: true,
+            details: { advisor: advisorRef, question, text: advice },
+          }, {
+            // Steer lets the current turn finish its active work; the Executor sees
+            // the result before its next model call rather than being interrupted.
+            deliverAs: "steer",
+            triggerTurn: true,
+          });
+        })
+        .catch((error: unknown) => {
+          if (controller.signal.aborted) return;
+          const message = error instanceof Error ? error.message : String(error);
+          if (ctx.hasUI) ctx.ui.notify(`Advisor consultation failed: ${message}`, "error");
+        })
+        .finally(() => manualConsultations.delete(controller));
+    },
+  });
 
   pi.registerCommand("advisor", {
     description: "Enable the Executor/Advisor flow and switch to the configured Executor model; accepts contextMaxChars=N",
@@ -64,6 +135,46 @@ export const registerCommands = (pi: ExtensionAPI) => {
     },
   });
 
+  pi.registerCommand("advisor-settings", {
+    description: "Configure Advisor context and reasoning effort",
+    handler: async (_args, ctx) => {
+      loadConfig(ctx);
+      if (!ctx.hasUI) return;
+
+      const initial: AdvisorSettings = {
+        contextMaxChars: contextMaxCharsRef,
+        effort: advisorEffortRef,
+        planGate: advisorPlanGateRef,
+        failureGate: advisorFailureGateRef,
+        completionGate: advisorCompletionGateRef,
+        collapseResponses: advisorCollapseResponsesRef,
+        customRule: advisorCustomInvocationRef,
+      };
+      const settings = await ctx.ui.custom<AdvisorSettings | undefined>((tui, theme, _keybindings, done) =>
+        new AdvisorSettingsSelector({
+          tui,
+          theme,
+          presets: CONTEXT_PRESETS,
+          effortLevels: EFFORT_LEVELS,
+          initial,
+          onSave: done,
+          onCancel: () => done(undefined),
+        })
+      );
+      if (!settings) return;
+
+      setAdvisorEffortRef(settings.effort === "Default (Model Default)" ? undefined : settings.effort);
+      setContextMaxCharsRef(settings.contextMaxChars);
+      setAdvisorPlanGateRef(settings.planGate);
+      setAdvisorFailureGateRef(settings.failureGate);
+      setAdvisorCompletionGateRef(settings.completionGate);
+      setAdvisorCollapseResponsesRef(settings.collapseResponses);
+      setAdvisorCustomInvocationRef(settings.customRule);
+      const path = saveConfig(ctx);
+      ctx.ui.notify(`Saved Advisor settings to ${path}`, "info");
+    },
+  });
+
   pi.registerCommand("advisor-off", {
     description: "Disable on-demand Advisor calls; keep the current model",
     handler: async (_args, ctx) => {

package/src/config.ts

@@ -5,21 +5,32 @@ import { CONFIG_DIR_NAME, type ExtensionContext, getAgentDir } from "@earendil-w
 export const FALLBACK_EXECUTOR = "aikeys/claude-sonnet-5";
 export const FALLBACK_ADVISOR = "aikeys/claude-fable-5";
 export const DEFAULT_CONTEXT_MAX_CHARS = 15_000;
-export const MAX_CONTEXT_MAX_CHARS = 1_000_000;
+// MAX_SAFE_INTEGER represents the complete reconstructed branch (the ALL preset).
+export const MAX_CONTEXT_MAX_CHARS = Number.MAX_SAFE_INTEGER;
 
 export let executorRef = FALLBACK_EXECUTOR;
 export let advisorRef = FALLBACK_ADVISOR;
 export let executorEffortRef: string | undefined = undefined;
 export let advisorEffortRef: string | undefined = undefined;
 export let contextMaxCharsRef = DEFAULT_CONTEXT_MAX_CHARS;
+export let advisorPlanGateRef = true;
+export let advisorFailureGateRef = true;
+export let advisorCompletionGateRef = true;
+export let advisorCustomInvocationRef: string | undefined = undefined;
+export let advisorCollapseResponsesRef = false;
 
 export const setExecutorRef = (ref: string) => { executorRef = ref; };
 export const setAdvisorRef = (ref: string) => { advisorRef = ref; };
 export const setExecutorEffortRef = (effort: string | undefined) => { executorEffortRef = effort; };
 export const setAdvisorEffortRef = (effort: string | undefined) => { advisorEffortRef = effort; };
 export const isValidContextMaxChars = (value: unknown): value is number =>
-  typeof value === "number" && Number.isSafeInteger(value) && value > 0 && value <= MAX_CONTEXT_MAX_CHARS;
+  typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= MAX_CONTEXT_MAX_CHARS;
 export const setContextMaxCharsRef = (value: number) => { contextMaxCharsRef = value; };
+export const setAdvisorPlanGateRef = (enabled: boolean) => { advisorPlanGateRef = enabled; };
+export const setAdvisorFailureGateRef = (enabled: boolean) => { advisorFailureGateRef = enabled; };
+export const setAdvisorCompletionGateRef = (enabled: boolean) => { advisorCompletionGateRef = enabled; };
+export const setAdvisorCustomInvocationRef = (rule: string | undefined) => { advisorCustomInvocationRef = rule?.trim() || undefined; };
+export const setAdvisorCollapseResponsesRef = (enabled: boolean) => { advisorCollapseResponsesRef = enabled; };
 
 export const splitRef = (ref: string): [string, string] => {
   const i = ref.indexOf("/");
@@ -31,27 +42,60 @@ export const configPaths = (ctx: ExtensionContext) => [
   join(getAgentDir(), "advisor.json"),
 ];
 
+type AdvisorConfig = {
+  executor?: string;
+  advisor?: string;
+  executorEffort?: string;
+  advisorEffort?: string;
+  contextMaxChars?: number;
+  advisorPlanGate?: boolean;
+  advisorFailureGate?: boolean;
+  advisorCompletionGate?: boolean;
+  advisorCustomInvocation?: string;
+  advisorCollapseResponses?: boolean;
+};
+
+const isValidConfig = (value: unknown): value is AdvisorConfig => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const config = value as Record<string, unknown>;
+  return (config.executor === undefined || typeof config.executor === "string")
+    && (config.advisor === undefined || typeof config.advisor === "string")
+    && (config.executorEffort === undefined || typeof config.executorEffort === "string")
+    && (config.advisorEffort === undefined || typeof config.advisorEffort === "string")
+    && (config.contextMaxChars === undefined || isValidContextMaxChars(config.contextMaxChars))
+    && (config.advisorPlanGate === undefined || typeof config.advisorPlanGate === "boolean")
+    && (config.advisorFailureGate === undefined || typeof config.advisorFailureGate === "boolean")
+    && (config.advisorCompletionGate === undefined || typeof config.advisorCompletionGate === "boolean")
+    && (config.advisorCustomInvocation === undefined || typeof config.advisorCustomInvocation === "string")
+    && (config.advisorCollapseResponses === undefined || typeof config.advisorCollapseResponses === "boolean");
+};
+
 export const loadConfig = (ctx: ExtensionContext) => {
   executorRef = FALLBACK_EXECUTOR;
   advisorRef = FALLBACK_ADVISOR;
   executorEffortRef = undefined;
   advisorEffortRef = undefined;
   contextMaxCharsRef = DEFAULT_CONTEXT_MAX_CHARS;
+  advisorPlanGateRef = true;
+  advisorFailureGateRef = true;
+  advisorCompletionGateRef = true;
+  advisorCustomInvocationRef = undefined;
+  advisorCollapseResponsesRef = false;
   for (const path of configPaths(ctx)) {
     if (!path || !existsSync(path)) continue;
     try {
-      const config = JSON.parse(readFileSync(path, "utf8")) as {
-        executor?: string;
-        advisor?: string;
-        executorEffort?: string;
-        advisorEffort?: string;
-        contextMaxChars?: number;
-      };
+      const config = JSON.parse(readFileSync(path, "utf8"));
+      if (!isValidConfig(config)) throw new TypeError("Invalid advisor configuration");
       if (config.executor) executorRef = config.executor;
       if (config.advisor) advisorRef = config.advisor;
       if (config.executorEffort) executorEffortRef = config.executorEffort;
       if (config.advisorEffort) advisorEffortRef = config.advisorEffort;
       if (isValidContextMaxChars(config.contextMaxChars)) contextMaxCharsRef = config.contextMaxChars;
+      if (typeof config.advisorPlanGate === "boolean") advisorPlanGateRef = config.advisorPlanGate;
+      if (typeof config.advisorFailureGate === "boolean") advisorFailureGateRef = config.advisorFailureGate;
+      if (typeof config.advisorCompletionGate === "boolean") advisorCompletionGateRef = config.advisorCompletionGate;
+      if (typeof config.advisorCustomInvocation === "string") advisorCustomInvocationRef = config.advisorCustomInvocation || undefined;
+      if (typeof config.advisorCollapseResponses === "boolean") advisorCollapseResponsesRef = config.advisorCollapseResponses;
       return path;
     } catch {
       // Ignore malformed config and keep looking for a valid fallback.
@@ -63,12 +107,26 @@ export const loadConfig = (ctx: ExtensionContext) => {
 export const saveConfig = (ctx: ExtensionContext) => {
   const project = join(ctx.cwd, CONFIG_DIR_NAME, "advisor.json");
   const path = ctx.isProjectTrusted() && existsSync(project) ? project : join(getAgentDir(), "advisor.json");
+  // Preserve settings owned by future versions or other tools that share this file.
+  let existing: Record<string, unknown> = {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) existing = parsed as Record<string, unknown>;
+  } catch {
+    // A missing or malformed file is safely replaced with the current settings.
+  }
   const data = {
+    ...existing,
     executor: executorRef,
     advisor: advisorRef,
     executorEffort: executorEffortRef,
     advisorEffort: advisorEffortRef,
     contextMaxChars: contextMaxCharsRef,
+    advisorPlanGate: advisorPlanGateRef,
+    advisorFailureGate: advisorFailureGateRef,
+    advisorCompletionGate: advisorCompletionGateRef,
+    advisorCustomInvocation: advisorCustomInvocationRef,
+    advisorCollapseResponses: advisorCollapseResponsesRef,
   };
   writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`);
   return path;
@@ -86,7 +144,7 @@ export const parseArgs = (args: string): string | undefined => {
     if (key === "contextMaxChars") {
       const parsed = Number(value);
       if (!isValidContextMaxChars(parsed)) {
-        return `contextMaxChars must be a positive integer no greater than ${MAX_CONTEXT_MAX_CHARS}.`;
+        return `contextMaxChars must be a non-negative integer no greater than ${MAX_CONTEXT_MAX_CHARS}.`;
       }
       nextContextMaxChars = parsed;
     }

package/src/conversation.ts

@@ -14,6 +14,7 @@ export const textFrom = (content: unknown): string => {
 };
 
 export const recentConversation = (ctx: ExtensionContext, maxChars = 15000): string => {
+  if (maxChars === 0) return "";
   const entries: string[] = [];
   for (const entry of ctx.sessionManager.getBranch()) {
     if (entry.type === "message") {

package/src/tools.ts

@@ -2,23 +2,55 @@ import { stream, type Message, type AssistantMessage } from "@earendil-works/pi-
 import { getMarkdownTheme, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Box, Markdown, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { advisorRef, advisorEffortRef, contextMaxCharsRef, loadConfig, splitRef } from "./config.js";
+import {
+  advisorCollapseResponsesRef, advisorCompletionGateRef, advisorCustomInvocationRef, advisorFailureGateRef, advisorPlanGateRef,
+  advisorRef, advisorEffortRef, contextMaxCharsRef, loadConfig, splitRef,
+} from "./config.js";
 import { recentConversation, textFrom } from "./conversation.js";
 
 export const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-export const DEFAULT_ADVISOR_REQUEST = "Review the current task and conversation context. Identify the highest-risk assumption, the smallest correct next step, and any important validation.";
+export const resolveAdvisorRequest = (question?: string) => question?.trim() || undefined;
+export const advisorMessageText = (conversation: string, question?: string) =>
+  `${conversation ? `<conversation>\n${conversation}\n</conversation>` : ""}${question ? `\n\nTargeted focus:\n${question}` : ""}`;
 
-export const resolveAdvisorRequest = (question?: string) => question?.trim() || DEFAULT_ADVISOR_REQUEST;
+export const renderAdvisorCallBox = (question: string | undefined, theme: any) => {
+  const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+  const label = theme.fg("customMessageLabel", theme.bold("[advisor]"));
+  const title = theme.fg("customMessageText", "Executor → Advisor");
+  box.addChild(new Text(question ? `${label} ${title}\n${theme.fg("dim", `  ${question}`)}` : `${label} ${title}`, 0, 0));
+  return box;
+};
+
+const COLLAPSED_ADVICE_LINES = 12;
+
+export const adviceForDisplay = (advice: string, expanded: boolean) => {
+  if (!advisorCollapseResponsesRef || expanded) return advice;
+  const lines = advice.split("\n");
+  if (lines.length <= COLLAPSED_ADVICE_LINES) return advice;
+  return `${lines.slice(0, COLLAPSED_ADVICE_LINES).join("\n")}\n\n… (${lines.length - COLLAPSED_ADVICE_LINES} more lines, Ctrl+O to expand)`;
+};
+
+export const advisorInvocationGuidelines = () => {
+  const guidelines: string[] = [];
+  if (advisorPlanGateRef) guidelines.push("Before committing to a materially consequential plan, use ask_advisor after investigating and forming your own candidate direction. Use it to stress-test consequential architectural, security, data-loss, compatibility, or difficult-to-reverse decisions. Do not delegate the entire plan or task.");
+  if (advisorFailureGateRef) guidelines.push("Use ask_advisor after two consecutive materially equivalent failed attempts, when a fix recreates an earlier failure, or after two actions produce no measurable progress. Do not make another materially equivalent attempt before consulting.");
+  if (advisorCompletionGateRef) guidelines.push("Before declaring success, use ask_advisor to review the goal, changed files, key decisions, tests, results, and remaining risks. Skip this only for demonstrably trivial, low-risk work.");
+  if (advisorCustomInvocationRef) guidelines.push(`Also use ask_advisor when: ${advisorCustomInvocationRef}`);
+  if (guidelines.length > 0) guidelines.push("Call ask_advisor with an empty object by default. Do not invent a question merely to request a review: the Advisor already receives context. Include question only for a genuinely specific assumption or trade-off.");
+  return guidelines;
+};
 
 export const ADVISOR_SYSTEM = [
   "You are the Advisor: a senior engineer giving a brief second opinion to an autonomous coding agent.",
-  "You do not act or take over planning. Help the Executor validate its own proposed direction:",
-  "identify risks, challenge assumptions, and recommend the smallest correct next step. No preamble.",
+  "You already have the relevant reconstructed conversation context. No question or other input from the Executor is needed for a general review.",
+  "When no targeted focus is supplied, proactively review the task, risks, proposed direction, and validation from the context. Do not ask the Executor for a question, clarification, more input, or confirmation.",
+  "The context may be truncated, so state any material uncertainty and make the best recommendation you can from what is present.",
+  "You do not act or take over planning. Identify risks, challenge assumptions, and recommend the smallest correct next step. No preamble.",
 ].join(" ");
 
 export const consult = async (
   ctx: ExtensionContext,
-  question: string,
+  question?: string,
   signal?: AbortSignal,
   onChunk?: (thinking: string, text: string) => void,
 ) => {
@@ -33,7 +65,7 @@ export const consult = async (
   const conversation = recentConversation(ctx, contextMaxCharsRef);
   const messages: Message[] = [{
     role: "user",
-    content: [{ type: "text", text: `${conversation ? `<conversation>\n${conversation}\n</conversation>\n\n` : ""}Request from the Executor:\n${question}` }],
+    content: [{ type: "text", text: advisorMessageText(conversation, question) }],
     timestamp: Date.now(),
   }];
 
@@ -71,32 +103,27 @@ export const consult = async (
 };
 
 export const registerAdvisorTool = (pi: ExtensionAPI) => {
+  pi.on("before_agent_start", (_event, ctx) => {
+    if (!pi.getActiveTools().includes("ask_advisor")) return;
+    loadConfig(ctx);
+    const guidelines = advisorInvocationGuidelines();
+    return guidelines.length > 0 ? { systemPrompt: `${ctx.getSystemPrompt()}\n\nAdvisor invocation settings:\n${guidelines.map((rule) => `- ${rule}`).join("\n")}` } : undefined;
+  });
+
   pi.registerTool({
     name: "ask_advisor",
     label: "Ask Advisor",
-    description: "Consult the on-demand Advisor model for strategic guidance. Call with no arguments for a general review of the current task and conversation, or provide question for targeted advice.",
-    promptSnippet: "Consult the Advisor for targeted advice, or call with no arguments for a general task and conversation review",
+    description: "Consult the on-demand Advisor model for strategic guidance. Call with an empty object for a context-aware review; add question only for a genuinely targeted focus.",
+    promptSnippet: "Consult the Advisor using its existing context; omit question unless a specific focus is necessary",
     promptGuidelines: [
-      "You MUST call `ask_advisor` in each of these scenarios:",
-      "1. PLAN GATE: Before committing to a materially consequential plan, first investigate and form your own candidate direction. Then call `ask_advisor` to stress-test the decision when multiple approaches exist, requirements are ambiguous, or the decision has architectural, security, data-loss, compatibility, or difficult-to-reverse consequences. Do not delegate the whole plan or task to the Advisor.",
-      "2. FAILURE GATE: You MUST call `ask_advisor` after two consecutive materially equivalent failed attempts, when an attempted fix recreates an earlier failure, or when two consecutive actions produce no measurable progress. Do NOT attempt another materially equivalent fix before consulting.",
-      "3. COMPLETION GATE: You MUST call `ask_advisor` with the goal, changed files, key decisions, tests performed, results, and remaining risks BEFORE declaring success or calling `goal_complete`. You MAY skip this only for demonstrably trivial, low-risk work with no meaningful trade-offs or failures.",
-      "Call `ask_advisor` with an empty object for a general review of the current task and conversation. Provide `question` when you want the Advisor to assess a specific assumption, trade-off, or proposed next step.",
-      "Do NOT use `ask_advisor` for routine decisions outside these three gates.",
+      "Call ask_advisor with an empty object by default. Do not invent a question merely to request a review: the Advisor already receives the context. Include question only for a genuinely specific assumption or trade-off.",
     ],
-    parameters: Type.Object({ question: Type.Optional(Type.String({ description: "The specific question or decision to get advice on. Omit for a general contextual review." })) }),
+    parameters: Type.Object({ question: Type.Optional(Type.String({ description: "The specific question or decision to get advice on. Omit this for normal reviews: the Advisor already has the conversation context." })) }),
     renderShell: "self",
-    renderCall(args, theme, context) {
-      const box = context.lastComponent instanceof Box ? context.lastComponent : new Box(1, 1, (text) => theme.bg("customMessageBg", text));
-      box.setBgFn((text) => theme.bg("customMessageBg", text));
-      box.clear();
-      const request = args.question?.trim();
-      const label = theme.fg("customMessageLabel", theme.bold("[advisor]"));
-      const title = theme.fg("customMessageText", "Executor → Advisor");
-      box.addChild(new Text(request ? `${label} ${title}\n${theme.fg("dim", `  ${request}`)}` : `${label} ${title}`, 0, 0));
-      return box;
+    renderCall(args, theme, _context) {
+      return renderAdvisorCallBox(args.question?.trim(), theme);
     },
-    renderResult(result, { isPartial }, theme, context) {
+    renderResult(result, { isPartial, expanded }, theme, context) {
       const box = context.lastComponent instanceof Box ? context.lastComponent : new Box(1, 1, (text) => theme.bg("customMessageBg", text));
       box.setBgFn((text) => theme.bg("customMessageBg", text));
       box.clear();
@@ -112,7 +139,7 @@ export const registerAdvisorTool = (pi: ExtensionAPI) => {
           lines.push(theme.fg("thinkingText", `  💭 ${snippet.replace(/\n/g, " ")}`));
         }
         box.addChild(new Text(lines.join("\n"), 0, 0));
-        if (d?.text) box.addChild(new Markdown(d.text, 0, 0, getMarkdownTheme()));
+        if (d?.text) box.addChild(new Markdown(adviceForDisplay(d.text, Boolean(expanded)), 0, 0, getMarkdownTheme()));
       } else {
         if (context.state.timerId) {
           clearInterval(context.state.timerId);
@@ -126,7 +153,7 @@ export const registerAdvisorTool = (pi: ExtensionAPI) => {
         }
         const advice = d?.text || textFrom(result.content) || "(Advisor returned no advice.)";
         box.addChild(new Text(lines.join("\n"), 0, 0));
-        box.addChild(new Markdown(advice, 0, 0, getMarkdownTheme()));
+        box.addChild(new Markdown(adviceForDisplay(advice, Boolean(expanded)), 0, 0, getMarkdownTheme()));
       }
       return box;
     },

package/src/ui.ts

@@ -1,4 +1,4 @@
-import { Input, fuzzyFilter, type Component, type Focusable } from "@earendil-works/pi-tui";
+import { Input, Key, matchesKey, fuzzyFilter, truncateToWidth, type Component, type Focusable } from "@earendil-works/pi-tui";
 import { Box, Text } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 
@@ -93,3 +93,145 @@ export class SearchableModelSelector implements Component, Focusable {
     }
   }
 }
+
+export type ContextPreset = { label: string; value: number; description: string };
+
+export type AdvisorSettings = {
+  contextMaxChars: number;
+  effort?: string;
+  planGate: boolean;
+  failureGate: boolean;
+  completionGate: boolean;
+  collapseResponses: boolean;
+  customRule?: string;
+};
+
+export class AdvisorSettingsSelector implements Component, Focusable {
+  private selectedRow = 0;
+  private contextIndex: number;
+  private effortIndex: number;
+  private settings: AdvisorSettings;
+  private customInput = new Input();
+  private editingCustom = false;
+  private _focused = false;
+
+  public get focused() { return this._focused; }
+  public set focused(value: boolean) {
+    this._focused = value;
+    this.customInput.focused = value && this.editingCustom;
+  }
+
+  constructor(private options: {
+    tui: any;
+    theme: Theme;
+    presets: ContextPreset[];
+    effortLevels: string[];
+    initial: AdvisorSettings;
+    onSave: (settings: AdvisorSettings) => void;
+    onCancel: () => void;
+  }) {
+    this.settings = { ...options.initial };
+    this.contextIndex = Math.max(0, options.presets.findIndex((preset) => preset.value === this.settings.contextMaxChars));
+    this.effortIndex = Math.max(0, options.effortLevels.indexOf(this.settings.effort || "Default (Model Default)"));
+    this.customInput.onSubmit = (value) => {
+      this.settings.customRule = value.trim() || undefined;
+      this.editingCustom = false;
+      this.customInput.focused = false;
+      this.options.tui.requestRender();
+    };
+    this.customInput.onEscape = () => {
+      this.editingCustom = false;
+      this.customInput.focused = false;
+      this.options.tui.requestRender();
+    };
+  }
+
+  invalidate(): void { this.options.tui.requestRender(); }
+
+  private currentContext() { return this.options.presets[this.contextIndex]; }
+  private row(label: string, value: string, index: number) {
+    const { theme } = this.options;
+    const prefix = index === this.selectedRow ? theme.fg("accent", "›") : " ";
+    const text = `${prefix} ${label.padEnd(28)} ${value}`;
+    return index === this.selectedRow ? theme.fg("accent", theme.bold(text)) : theme.fg("text", text);
+  }
+
+  render(width: number): string[] {
+    const { theme, presets } = this.options;
+    const trackWidth = Math.max(24, Math.min(60, width - 4));
+    const positions = presets.map((_, index) => Math.round(index * (trackWidth - 1) / (presets.length - 1)));
+    const track = Array.from({ length: trackWidth }, () => "─");
+    track[positions[this.contextIndex]] = "▲";
+    const labels = Array.from({ length: trackWidth }, () => " ");
+    for (let index = 0; index < presets.length; index++) {
+      const label = presets[index].label;
+      const start = Math.max(0, Math.min(trackWidth - label.length, positions[index] - Math.floor(label.length / 2)));
+      for (let char = 0; char < label.length; char++) labels[start + char] = label[char];
+    }
+    const heading = `Recent history${" ".repeat(Math.max(1, trackWidth - "Recent history".length - "Full branch".length))}Full branch`;
+    const onOff = (value: boolean) => value ? "On" : "Off";
+    const rows = [
+      this.row("Context window", this.currentContext().label, 0),
+      this.row("Advisor reasoning", this.options.effortLevels[this.effortIndex], 1),
+      this.row("Plan gate", onOff(this.settings.planGate), 2),
+      this.row("Failure gate", onOff(this.settings.failureGate), 3),
+      this.row("Completion gate", onOff(this.settings.completionGate), 4),
+      this.row("Collapse long responses", onOff(this.settings.collapseResponses), 5),
+      this.row("Custom invocation", this.settings.customRule || "None", 6),
+    ];
+    if (this.editingCustom) rows.push(`    ${this.customInput.render(Math.max(10, width - 6))[0] || ""}`);
+    rows.push(this.row("Save changes", "", 7));
+    return [
+      theme.fg("accent", theme.bold("  Advisor settings")),
+      "",
+      `  ${theme.fg("muted", heading)}`,
+      `  ${theme.fg("muted", track.join(""))}`,
+      `  ${theme.fg("text", labels.join(""))}`,
+      "",
+      ...rows.map((line) => `  ${line}`),
+      "",
+      `  ${theme.fg("muted", "↑/↓ select · ←/→ adjust · Enter edits or saves · Esc cancels")}`,
+    ].map((line) => truncateToWidth(line, width));
+  }
+
+  handleInput(keyData: string): void {
+    const { tui } = this.options;
+    if (this.editingCustom) {
+      this.customInput.handleInput(keyData);
+      return;
+    }
+    if (matchesKey(keyData, Key.up)) {
+      this.selectedRow = Math.max(0, this.selectedRow - 1);
+    } else if (matchesKey(keyData, Key.down)) {
+      this.selectedRow = Math.min(7, this.selectedRow + 1);
+    } else if (matchesKey(keyData, Key.left)) {
+      this.adjust(-1);
+    } else if (matchesKey(keyData, Key.right)) {
+      this.adjust(1);
+    } else if (matchesKey(keyData, Key.enter)) {
+      if (this.selectedRow === 6) {
+        this.editingCustom = true;
+        this.customInput.setValue(this.settings.customRule || "");
+        this.customInput.focused = this.focused;
+        tui.requestRender();
+        return;
+      }
+      if (this.selectedRow === 7) return this.options.onSave({ ...this.settings, contextMaxChars: this.currentContext().value, effort: this.options.effortLevels[this.effortIndex] });
+      this.adjust(1);
+    } else if (matchesKey(keyData, Key.escape)) {
+      return this.options.onCancel();
+    } else return;
+    tui.requestRender();
+  }
+
+  private adjust(direction: number) {
+    switch (this.selectedRow) {
+      case 0: this.contextIndex = Math.max(0, Math.min(this.options.presets.length - 1, this.contextIndex + direction)); break;
+      case 1: this.effortIndex = Math.max(0, Math.min(this.options.effortLevels.length - 1, this.effortIndex + direction)); break;
+      case 2: this.settings.planGate = !this.settings.planGate; break;
+      case 3: this.settings.failureGate = !this.settings.failureGate; break;
+      case 4: this.settings.completionGate = !this.settings.completionGate; break;
+      case 5: this.settings.collapseResponses = !this.settings.collapseResponses; break;
+    }
+  }
+}