pi-advisor-flow 0.2.3 → 0.2.6

package/README.md

@@ -1,19 +1,18 @@
 # pi-advisor
 
 <div align="center">
-  <img src="https://raw.githubusercontent.com/philipbrembeck/pi-advisor/refs/heads/main/assets/screenshot.png" alt="Pi Advisor consultation in the terminal" width="760">
 
-A configurable second-opinion workflow for <a href="https://github.com/earendil-works/pi">Pi</a> coding agents.
+![Pi Advisor consultation in the terminal](https://raw.githubusercontent.com/philipbrembeck/pi-advisor/refs/heads/main/assets/screenshot.png)
 
-</div>
+A configurable second-opinion workflow for <a href="https://github.com/earendil-works/pi">Pi</a> coding agents, inspired by the ["Steering Black-Box LLMs with Advisor Models" paper](https://arxiv.org/abs/2510.02453) and Claude's [Advisor](https://code.claude.com/docs/en/advisor) feature.
 
-Keep the work to the executor model, while the advisor steers it.
+</div>
 
-This extension introduces a strategic "Executor/Advisor" workflow, inspired by Claudes [Advisor](https://code.claude.com/docs/en/advisor).
+This extension introduces a strategic "Executor/Advisor" workflow.
 
 `pi-advisor-flow` keeps one model focused on execution and makes a second, smarter model available for consequential decisions, stalled work, and final reviews. The Executor still owns the work. The Advisor provides a concise review, answers questions and can provide help; it does not take over planning or run tools.
 
-[Read more about Advisors here](https://philipbrembeck.com/writings/2026/07/only-as-much-intelligence-as-you-need).
+The concept is simple, keep implementation on a fast model, borrow frontier reasoning only when decisions actually matter. [Read more about Advisors here](https://philipbrembeck.com/writings/2026/07/only-as-much-intelligence-as-you-need).
 
 ## Install
 
@@ -36,7 +35,7 @@ Restart or reload Pi after installation, then run `/advisor` in a session.
 
 1. Run `/advisor` to enable the flow and register `ask_advisor`.
 2. Run `/advisor-models` to choose the Executor and Advisor models.
-3. Run `/advisor-settings` to set context, gates, privacy controls, and output limits.
+3. Run `/advisor-settings` to set Simple mode, persistent activation, context, gates, privacy controls, and output limits.
 
 Enable with models in one command when preferred:
 
@@ -58,11 +57,13 @@ Enable with models in one command when preferred:
 
 ### `ask_advisor`
 
-The Executor calls `ask_advisor({})` for a general review of the current task and reconstructed conversation. It can pass a `question` for a targeted review.
+The Executor calls `ask_advisor({})` for a general review of the current task and reconstructed conversation. It can pass a `question` for a targeted review, or a concise `draft` for plan and completion reviews. A draft should name proposed work, validation, and remaining risks; it is an unverified claim, not evidence.
+
+Successful calls return an opaque `adviceId`. When global outcome logging is enabled, the Executor may voluntarily call `record_advisor_outcome` once with that ID, an adoption value, and a final validation status.
 
 Use the Advisor after the Executor has investigated and formed a candidate direction. It is intended to challenge assumptions, expose risks, and confirm the next verification step—not to replace the Executor's work.
 
-Normal consultations preserve the provider's final Markdown. They do not parse a verdict or block execution.
+Normal consultations preserve the provider's final Markdown and never block execution. When the Advisor has no material concern or recommendation, it may begin with the exact first line `Verdict: sound`; Pi renders that response with the static `◆ ADVISOR · SOUND` header, for both `ask_advisor` results and `/advisor-manual`.
 
 ## Automatic loop gate
 
@@ -125,12 +126,18 @@ All fields are optional. This example shows the available settings and their nor
   "advisorBlockOnBlocked": true,
   "gateFailureMode": "block-session",
 
-  "advisorSessionSummary": true,
+  "advisorSessionSummary": false,
+  "advisorGitContext": "summary",
+  "advisorGitContextMaxChars": 20000,
+  "simpleMode": false,
+  "alwaysOn": false,
   "advisorHerdrIntegration": true,
   "advisorToolResultMaxLines": 2000,
   "advisorToolResultMaxBytes": 51200,
 
   "advisorRedactSecrets": false,
+  "advisorUntrackedContent": false,
+  "advisorOutcomeLogging": false,
   "advisorToolPolicies": {
     "bash": "summary",
     "deploy": "exclude"
@@ -138,6 +145,33 @@ All fields are optional. This example shows the available settings and their nor
 }
 ```
 
+### Simple mode and persistent activation
+
+- `simpleMode` defaults to `false`. When enabled, `ask_advisor` and `/advisor-manual` remain available for voluntary second opinions, while plan/failure/completion rules, loop gates, blocking, call budgets, and session summaries are disabled. Context limits, result caps, redaction, and tool disclosure policies still apply.
+- `alwaysOn` defaults to `false`. When enabled, Pi restores the configured Executor and activates `ask_advisor` for new, resumed, forked, and reloaded sessions. While the Advisor flow is active, an explicit `/model` selection becomes the persisted Executor for the next activation; a model restored with a session does not change the saved Executor. `/advisor-off` turns `alwaysOn` off so the flow stays disabled in later sessions.
+- In Simple mode, settings keeps the Context window/history slider alongside Simple mode and Always on; advanced values remain saved and take effect when Simple mode is disabled.
+
+### Repository context
+
+- `advisorGitContext` defaults to `summary`. It controls how much of the working tree reaches the Advisor:
+  - `off` sends no repository information.
+  - `summary` sends changed file names, change status, and line counts. It never sends file contents.
+  - `full` additionally sends the patch.
+- Changes are measured against the last commit and cover staged and unstaged work. Untracked files are always listed by name only; their contents are never sent by `gitContext: full`.
+- `advisorUntrackedContent` defaults to false. When enabled, `includeUntracked` can attach only exact named, repository-relative, untracked regular files. Files are redacted and capped before egress; sibling files remain withheld.
+- `advisorGitContextMaxChars` defaults to `20000`. Repository context may claim its own cap or half of `contextMaxChars`, whichever is smaller, so it cannot crowd out the conversation.
+- The Executor may pass `gitContext` to `ask_advisor` as `none`, `summary`, or `full`. `advisorGitContext` is the ceiling: a larger request is narrowed to the configured level and the Advisor is told that a fuller view was withheld, so it does not claim verification it could not perform.
+- `summary` deliberately excludes diff hunk headers. Git derives those from surrounding file content, so a hunk header can reproduce a line the change never touched, including a credential.
+- Redaction runs before the region is capped, and repository content is labelled as untrusted data in the request. Paths and patch text are escaped so a crafted path cannot close the region early and have the remainder read as instructions.
+- File names themselves can be sensitive. `summary` withholds file contents, not file names; use `off` when names must not leave the machine.
+- Collection shares a single overall time budget across its git commands and degrades to a stated failure rather than implying a clean tree.
+
+### Project preferences and outcomes
+
+In a trusted project only, `.pi/advisor-preferences.md` may provide a short local brief. It is never written by pi-advisor, is treated as lower-priority untrusted text, and is redacted/capped before egress. Symlinks, unreadable files, and paths outside the project are ignored.
+
+`advisorOutcomeLogging` defaults to false and is global-only: a project config cannot enable it. When enabled, `~/.pi/agent/advisor-outcomes.jsonl` stores bounded rotating JSONL records with only a version, timestamp, salted truncated advice digest, trigger, adoption, and validation status. It stores no prompt, advice, paths, tool output, repository data, session ID, or advice ID.
+
 ### Context and limits
 
 - `contextMaxChars` defaults to `15000`. It preserves complete semantic entries and adds an omission marker rather than splitting a message.
@@ -161,7 +195,7 @@ Redaction and output limits reduce accidental disclosure; they are not a data-cl
 
 ### Session summary and Herdr
 
-The optional Session Advisor Summary is local and in-memory only. It appears after a non-blocked settled run and is never persisted.
+The optional Session Advisor Summary defaults to off. When enabled, it is local and in-memory only, appears after a non-blocked settled run, and is never persisted.
 
 It distinguishes regular Markdown advice from gate decisions and records the trigger, model, usage/cost when available, failures, budget, and execution effect.
 

package/package.json

@@ -1,4 +1,12 @@
 {
+  "name": "pi-advisor-flow",
+  "version": "0.2.6",
+  "author": "Philip Brembeck",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/philipbrembeck/pi-advisor.git"
+  },
+  "main": "extensions/index.ts",
   "devDependencies": {
     "@biomejs/biome": "2.5.3",
     "@earendil-works/pi-ai": "^0.80.7",
@@ -12,37 +20,19 @@
     "typescript": "^5.3.3",
     "ultracite": "7.9.4"
   },
-  "name": "pi-advisor-flow",
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.80.7",
     "@earendil-works/pi-coding-agent": "^0.80.7",
     "@earendil-works/pi-tui": "^0.80.7",
     "typebox": "^1.1.38"
   },
-  "scripts": {
-    "test": "bun test",
-    "typecheck": "tsc --noEmit",
-    "format": "bunx ultracite fix --linter-enabled=false",
-    "lint": "bunx ultracite check",
-    "lint:fix": "bunx ultracite fix",
-    "package:check": "npm pack --dry-run --json >/dev/null",
-    "prepare": "husky"
-  },
-  "lint-staged": {
-    "*.{json,jsonc,ts}": "bun run lint:fix --"
-  },
-  "type": "module",
-  "version": "0.2.3",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/philipbrembeck/pi-advisor.git"
-  },
-  "homepage": "https://github.com/philipbrembeck/pi-advisor",
-  "author": "Philip Brembeck",
   "description": "Advanced Executor/Advisor flow for Pi, fully configurable and extendable.",
-  "main": "extensions/index.ts",
-  "types": "extensions/index.ts",
+  "files": [
+    "extensions",
+    "src",
+    "README.md"
+  ],
+  "homepage": "https://github.com/philipbrembeck/pi-advisor",
   "keywords": [
     "pi-package",
     "pi-extension",
@@ -51,15 +41,28 @@
     "pi-advisor",
     "herdr"
   ],
-  "files": [
-    "extensions",
-    "src",
-    "README.md"
-  ],
+  "license": "MIT",
+  "lint-staged": {
+    "*.{json,jsonc,ts}": "bun run lint:fix --"
+  },
+  "overrides": {
+    "brace-expansion": "5.0.8"
+  },
   "pi": {
     "extensions": [
       "./extensions/index.ts"
     ],
     "image": "https://raw.githubusercontent.com/philipbrembeck/pi-advisor/refs/heads/main/assets/hero.png"
-  }
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "format": "bunx ultracite fix --linter-enabled=false",
+    "lint": "bunx ultracite check",
+    "lint:fix": "bunx ultracite fix",
+    "package:check": "npm pack --dry-run --json >/dev/null",
+    "prepare": "husky"
+  },
+  "type": "module",
+  "types": "extensions/index.ts"
 }

package/src/commands.ts

@@ -8,12 +8,15 @@ import {
   advisorEffortRef,
   advisorMaxCallsPerSessionRef,
   advisorRef,
+  alwaysOnRef,
   executorEffortRef,
   executorRef,
   getAdvisorSettings,
+  isSimpleMode,
   loadConfig,
   parseArgs,
   saveConfig,
+  saveGlobalOutcomeLogging,
   setAdvisorAutoLoopGateRef,
   setAdvisorBlockOnBlockedRef,
   setAdvisorCollapseResponsesRef,
@@ -22,9 +25,12 @@ import {
   setAdvisorEffortRef,
   setAdvisorFailureGateRef,
   setAdvisorFailureModeRef,
+  setAdvisorGitContextMaxCharsRef,
+  setAdvisorGitContextRef,
   setAdvisorHerdrIntegrationRef,
   setAdvisorLoopThresholdRef,
   setAdvisorMaxCallsPerSessionRef,
+  setAdvisorOutcomeLoggingRef,
   setAdvisorPlanGateRef,
   setAdvisorRedactSecretsRef,
   setAdvisorRef,
@@ -32,9 +38,12 @@ import {
   setAdvisorToolPoliciesRef,
   setAdvisorToolResultMaxBytesRef,
   setAdvisorToolResultMaxLinesRef,
+  setAdvisorUntrackedContentRef,
+  setAlwaysOnRef,
   setContextMaxCharsRef,
   setExecutorEffortRef,
   setExecutorRef,
+  setSimpleModeRef,
   splitRef,
 } from "./config.js";
 import { herdrAdvisorActivity, notifyHerdrAdvisorFailure } from "./herdr.js";
@@ -42,7 +51,9 @@ import {
   adviceForDisplay,
   advisorSessionState,
   consultAdvisor,
+  hasSoundVerdict,
   renderAdvisorCallBox,
+  renderAdvisorResponseHeader,
   resolveAdvisorRequest,
 } from "./tools.js";
 import {
@@ -102,7 +113,12 @@ type ManualConsult = (
   ctx: ExtensionContext,
   question?: string,
   signal?: AbortSignal
-) => Promise<{ markdown: string; thinkingText: string }>;
+) => Promise<{
+  markdown: string;
+  thinkingText: string;
+  draftBytes?: number;
+  preferenceBytes?: number;
+}>;
 type ThinkingLevel = Parameters<ExtensionAPI["setThinkingLevel"]>[0];
 
 const notify = (
@@ -196,37 +212,65 @@ export const registerCommands = (
       });
   };
 
-  const activateAdvisor = async (args: string, ctx: ExtensionContext) => {
+  /** Resolves both models and their auth, or reports why activation cannot proceed. */
+  const resolveActivationModels = async (ctx: ExtensionContext) => {
+    const executor = findConfiguredModel(ctx, executorRef);
+    if (!executor) {
+      return { error: `Executor model not found: ${executorRef}` };
+    }
+    const advisor = findConfiguredModel(ctx, advisorRef);
+    if (!advisor) {
+      return { error: `Advisor model not found: ${advisorRef}` };
+    }
+    const advisorAuth = await ctx.modelRegistry.getApiKeyAndHeaders(advisor);
+    if (!(advisorAuth.ok && advisorAuth.apiKey)) {
+      return { error: `No API key for Advisor ${advisorRef}` };
+    }
+    if (!(await pi.setModel(executor))) {
+      return { error: `No API key for Executor ${executorRef}` };
+    }
+    return {};
+  };
+
+  const activateAdvisor = async (
+    args: string,
+    ctx: ExtensionContext,
+    announce = true
+  ) => {
     loadConfig(ctx);
     const argumentError = parseArgs(args);
     if (argumentError) {
       notify(ctx, argumentError, "error");
       return;
     }
-    const executor = findConfiguredModel(ctx, executorRef);
-    if (!executor) {
-      notify(ctx, `Executor model not found: ${executorRef}`, "error");
-      return;
-    }
-    if (!findConfiguredModel(ctx, advisorRef)) {
-      notify(ctx, `Advisor model not found: ${advisorRef}`, "error");
+    const { error } = await resolveActivationModels(ctx);
+    if (error) {
+      notify(ctx, error, "error");
       return;
     }
-    if (!(await pi.setModel(executor))) {
-      notify(ctx, `No API key for Executor ${executorRef}`, "error");
-      return;
+    // parseArgs only mutates in-memory refs, and every later loadConfig resets
+    // them from disk. Persist supplied arguments once they are known to resolve,
+    // so an unusable model reference is never written to the configuration.
+    if (args.trim()) {
+      saveConfig(ctx);
     }
     if (executorEffortRef) {
       pi.setThinkingLevel(executorEffortRef as ThinkingLevel);
     }
     if (!flowEnabled()) {
-      pi.setActiveTools([...pi.getActiveTools(), "ask_advisor"]);
+      pi.setActiveTools([
+        ...pi.getActiveTools(),
+        "ask_advisor",
+        "record_advisor_outcome",
+      ]);
+    }
+    if (announce) {
+      notify(
+        ctx,
+        `Advisor flow ready — Executor: ${executorRef} (thinking: ${executorEffortRef || "default"}) · Advisor: ${advisorRef} (thinking: ${advisorEffortRef || "default"})`,
+        "info"
+      );
     }
-    notify(
-      ctx,
-      `Advisor flow ready — Executor: ${executorRef} (thinking: ${executorEffortRef || "default"}) · Advisor: ${advisorRef} (thinking: ${advisorEffortRef || "default"})`,
-      "info"
-    );
   };
 
   pi.registerEntryRenderer?.(
@@ -244,17 +288,22 @@ export const registerCommands = (
         | { 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.)");
+      // Manual consultations must render exactly like an Executor ask_advisor call.
+      box.addChild(
+        new Text(
+          renderAdvisorResponseHeader(hasSoundVerdict(advice), theme),
+          0,
+          0
+        )
+      );
+      if (details?.advisor) {
+        box.addChild(new Text(theme.fg("dim", `  ${details.advisor}`), 0, 0));
+      }
       box.addChild(
         new Markdown(
           adviceForDisplay(advice, expanded),
@@ -267,6 +316,34 @@ export const registerCommands = (
     }
   );
 
+  pi.on("session_start", async (_event, ctx) => {
+    // A malformed advisor.json or a provider auth failure must not reject a
+    // lifecycle handler and break session startup.
+    try {
+      loadConfig(ctx);
+      if (alwaysOnRef) {
+        await activateAdvisor("", ctx, false);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      notify(ctx, `Advisor activation failed: ${message}`, "error");
+    }
+  });
+
+  pi.on("model_select", (event, ctx) => {
+    // Only an explicit user selection redefines the Executor. "restore" replays a
+    // stored session model and would otherwise overwrite saved configuration.
+    if (event.source !== "set" || !flowEnabled()) {
+      return;
+    }
+    const selected = `${event.model.provider}/${event.model.id}`;
+    if (selected === executorRef) {
+      return;
+    }
+    setExecutorRef(selected);
+    saveConfig(ctx);
+  });
+
   pi.on("session_shutdown", () => {
     for (const controller of manualConsultations) {
       controller.abort();
@@ -280,13 +357,20 @@ export const registerCommands = (
       "Consult the Advisor in parallel; accepts an optional focused question and fans its response out to the Executor",
     handler: (args, ctx) => {
       loadConfig(ctx);
-      if (!advisorSessionState.canConsult(advisorMaxCallsPerSessionRef)) {
+      if (
+        !(
+          isSimpleMode() ||
+          advisorSessionState.canConsult(advisorMaxCallsPerSessionRef)
+        )
+      ) {
         const message = "Advisor call budget exhausted for this session.";
         notify(ctx, message, "warning");
         notifyHerdrAdvisorFailure("Advisor budget exhausted", message);
         return Promise.resolve();
       }
-      advisorSessionState.consumeCall();
+      if (!isSimpleMode()) {
+        advisorSessionState.consumeCall();
+      }
       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.
@@ -389,6 +473,7 @@ export const registerCommands = (
 
   pi.registerCommand("advisor-settings", {
     description: "Configure Advisor context and reasoning effort",
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one settings form maps every persisted control.
     handler: async (_args, ctx) => {
       loadConfig(ctx);
       if (!ctx.hasUI) {
@@ -427,15 +512,27 @@ export const registerCommands = (
       setAdvisorAutoLoopGateRef(settings.autoLoopGate ?? true);
       setAdvisorLoopThresholdRef(settings.loopThreshold ?? 3);
       setAdvisorMaxCallsPerSessionRef(settings.maxCallsPerSession);
-      setAdvisorSessionSummaryRef(settings.sessionSummary ?? true);
+      setAdvisorSessionSummaryRef(settings.sessionSummary ?? false);
+      setSimpleModeRef(settings.simpleMode ?? false);
+      setAlwaysOnRef(settings.alwaysOn ?? false);
       setAdvisorFailureModeRef(settings.failureMode ?? "block-session");
       setAdvisorHerdrIntegrationRef(settings.herdrIntegration ?? true);
       setAdvisorToolResultMaxLinesRef(settings.toolResultMaxLines ?? 2000);
       setAdvisorToolResultMaxBytesRef(settings.toolResultMaxBytes ?? 50 * 1024);
       setAdvisorRedactSecretsRef(settings.redactSecrets ?? false);
+      setAdvisorGitContextRef(settings.gitContext ?? "summary");
+      setAdvisorGitContextMaxCharsRef(settings.gitContextMaxChars ?? 20_000);
       setAdvisorToolPoliciesRef(settings.toolPolicies ?? {});
+      setAdvisorUntrackedContentRef(settings.untrackedContent ?? false);
+      setAdvisorOutcomeLoggingRef(settings.outcomeLogging ?? false);
       const path = saveConfig(ctx);
-      ctx.ui.notify(`Saved Advisor settings to ${path}`, "info");
+      const globalPath = saveGlobalOutcomeLogging(
+        settings.outcomeLogging ?? false
+      );
+      ctx.ui.notify(
+        `Saved Advisor settings to ${path}; outcome logging globally to ${globalPath}`,
+        "info"
+      );
     },
   });
 
@@ -443,14 +540,24 @@ export const registerCommands = (
     description: "Disable on-demand Advisor calls; keep the current model",
     handler: (_args, ctx) => {
       pi.setActiveTools(
-        pi.getActiveTools().filter((name) => name !== "ask_advisor")
+        pi
+          .getActiveTools()
+          .filter(
+            (name) =>
+              name !== "ask_advisor" && name !== "record_advisor_outcome"
+          )
       );
-      if (ctx.hasUI) {
-        ctx.ui.notify(
-          "Advisor flow disabled. Current model unchanged.",
-          "info"
-        );
+      // Leaving alwaysOn set would silently reactivate the flow next session.
+      const wasAlwaysOn = alwaysOnRef;
+      if (wasAlwaysOn) {
+        setAlwaysOnRef(false);
+        saveConfig(ctx);
       }
+      notify(
+        ctx,
+        `Advisor flow disabled. Current model unchanged.${wasAlwaysOn ? " Always on turned off." : ""}`,
+        "info"
+      );
       return Promise.resolve();
     },
   });