pi-advisor-flow 0.1.6 → 0.1.8

package/README.md

@@ -53,7 +53,7 @@ Starts an Advisor consultation in parallel without interrupting the Executor's a
 
 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`.
+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). It includes controls for critical-response blocking, the automatic loop gate and its repeat threshold, a per-session Advisor-call limit, and the local Session Advisor Summary. Response collapsing is off by default. You can add one custom natural-language invocation rule. Settings persist in `advisor.json`.
 
 ### `/advisor-models`
 
@@ -68,6 +68,14 @@ Saves and persists your configuration to `~/.pi/agent/advisor.json`.
 
 The Executor can call `ask_advisor` with an empty object for a general review of the current task and conversation, or provide `question` for targeted feedback. The Advisor is a brief second opinion: the Executor investigates and forms its own candidate direction first, then uses the Advisor to challenge assumptions and validate a consequential next step. It should not delegate the entire plan or task.
 
+Advisor responses use a structured verdict: `proceed`, `revise`, `insufficient-evidence`, or `blocked`. A `blocked` verdict is reserved for critical escalation. When critical blocking is enabled (the default), it aborts the active run and marks the Pi pane blocked in Herdr.
+
+### Automatic loop gate
+
+When enabled, the loop gate consults the Advisor after the configured number of consecutive equivalent tool calls (default: three). A `proceed` verdict resets the repetition counter and allows the call. `revise` and `insufficient-evidence` stop only the repeated call and deliver the Advisor guidance to the Executor. A critical `blocked` verdict, an Advisor failure, or an exhausted Advisor-call budget blocks the session and reports that state to Herdr.
+
+The maximum Advisor calls per session defaults to unlimited. When set to a finite value, the Executor receives the remaining-call count in its system instructions. The optional Session Advisor Summary is local, in-memory only, and appears after a non-blocked settled run; it is never persisted or sent to Herdr.
+
 ### Context configuration
 
 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:
@@ -83,11 +91,18 @@ The selected configuration is saved as `advisor.json` in the Pi agent directory
   "advisorFailureGate": true,
   "advisorCompletionGate": true,
   "advisorCollapseResponses": false,
-  "advisorCustomInvocation": "before changing a production deployment"
+  "advisorCustomInvocation": "before changing a production deployment",
+  "advisorBlockOnBlocked": true,
+  "advisorAutoLoopGate": true,
+  "advisorLoopThreshold": 3,
+  "advisorMaxCallsPerSession": 5,
+  "advisorSessionSummary": true
 }
 ```
 
-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.
+All fields are optional. `executor`, `advisor`, and their effort settings are managed by `/advisor-models`. `/advisor-settings` manages `advisorEffort`, `contextMaxChars`, the three invocation-gate booleans, `advisorCollapseResponses`, `advisorCustomInvocation`, `advisorBlockOnBlocked`, `advisorAutoLoopGate`, `advisorLoopThreshold`, `advisorMaxCallsPerSession`, and `advisorSessionSummary`.
+
+`contextMaxChars` must be a non-negative safe integer: its default is 15,000, `0` omits history, and `9007199254740991` means ALL. `advisorLoopThreshold` must be at least `2` and defaults to `3`. Omit `advisorMaxCallsPerSession` for an unlimited session budget; otherwise it must be a non-negative safe integer. Critical blocking, the automatic loop gate, and the Session Advisor Summary default to `true`.
 
 ### `/advisor-off`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-advisor-flow",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -8,7 +8,7 @@
   },
   "homepage": "https://github.com/philipbrembeck/pi-advisor",
   "author": "Philip Brembeck",
-  "description": "Executor/Advisor flow for autonomous pi coding agents",
+  "description": "Advanced Executor/Advisor flow for Pi, fully configurable and extendable.",
   "type": "module",
   "main": "extensions/index.ts",
   "types": "extensions/index.ts",
@@ -17,7 +17,8 @@
     "pi-extension",
     "pi-coding-agent",
     "advisor",
-    "pi-advisor"
+    "pi-advisor",
+    "herdr"
   ],
   "files": [
     "extensions",

package/src/commands.ts

@@ -1,14 +1,15 @@
-import { getMarkdownTheme, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getMarkdownTheme, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Box, Markdown, Text } from "@earendil-works/pi-tui";
 import {
-  advisorCollapseResponsesRef, advisorCompletionGateRef, advisorCustomInvocationRef, advisorFailureGateRef, advisorPlanGateRef,
+  advisorAutoLoopGateRef, advisorMaxCallsPerSessionRef, advisorBlockOnBlockedRef, advisorCollapseResponsesRef, advisorCompletionGateRef, advisorCustomInvocationRef, advisorFailureGateRef, advisorLoopThresholdRef, advisorPlanGateRef, advisorSessionSummaryRef,
   advisorRef, advisorEffortRef, executorRef, executorEffortRef,
-  setAdvisorCollapseResponsesRef, setAdvisorCompletionGateRef, setAdvisorCustomInvocationRef, setAdvisorFailureGateRef, setAdvisorPlanGateRef,
+  setAdvisorAutoLoopGateRef, setAdvisorMaxCallsPerSessionRef, setAdvisorBlockOnBlockedRef, setAdvisorCollapseResponsesRef, setAdvisorCompletionGateRef, setAdvisorCustomInvocationRef, setAdvisorFailureGateRef, setAdvisorLoopThresholdRef, setAdvisorPlanGateRef, setAdvisorSessionSummaryRef,
   setAdvisorRef, setAdvisorEffortRef, setContextMaxCharsRef, setExecutorRef, setExecutorEffortRef,
   contextMaxCharsRef, loadConfig, saveConfig, parseArgs, splitRef,
 } from "./config.js";
 import { AdvisorSettingsSelector, SearchableModelSelector, type AdvisorSettings, type ContextPreset } from "./ui.js";
-import { adviceForDisplay, consult, renderAdvisorCallBox, resolveAdvisorRequest } from "./tools.js";
+import { herdrAdvisorActivity } from "./herdr.js";
+import { adviceForDisplay, advisorSessionState, consult, renderAdvisorCallBox, resolveAdvisorRequest } from "./tools.js";
 
 const EFFORT_LEVELS = ["Default (Model Default)", "off", "minimal", "low", "medium", "high", "xhigh", "max"];
 
@@ -21,7 +22,9 @@ const CONTEXT_PRESETS: ContextPreset[] = [
   { 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 } = {}) => {
+type ManualConsult = (ctx: ExtensionContext, question?: string, signal?: AbortSignal) => Promise<{ advice: string; thinkingText: string }>;
+
+export const registerCommands = (pi: ExtensionAPI, dependencies: { consult?: ManualConsult } = {}) => {
   const flowEnabled = () => pi.getActiveTools().includes("ask_advisor");
   const requestAdvisor = dependencies.consult ?? consult;
   const manualConsultations = new Set<AbortController>();
@@ -44,11 +47,18 @@ export const registerCommands = (pi: ExtensionAPI, dependencies: { consult?: typ
   pi.on("session_shutdown", () => {
     for (const controller of manualConsultations) controller.abort();
     manualConsultations.clear();
+    herdrAdvisorActivity.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) => {
+      loadConfig(ctx);
+      if (!advisorSessionState.canUseAutomaticCall(advisorMaxCallsPerSessionRef)) {
+        if (ctx.hasUI) ctx.ui.notify("Advisor call budget exhausted for this session.", "warning");
+        return;
+      }
+      advisorSessionState.consumeAutomaticCall();
       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.
@@ -58,8 +68,10 @@ export const registerCommands = (pi: ExtensionAPI, dependencies: { consult?: typ
       manualConsultations.add(controller);
       pi.appendEntry?.("advisor-manual-call", { question });
 
+      herdrAdvisorActivity.start();
       void requestAdvisor(ctx, question, controller.signal)
         .then(({ advice }) => {
+          advisorSessionState.recordConsultation("manual");
           if (controller.signal.aborted) return;
           pi.sendMessage({
             customType: "advisor-manual-result",
@@ -78,7 +90,10 @@ export const registerCommands = (pi: ExtensionAPI, dependencies: { consult?: typ
           const message = error instanceof Error ? error.message : String(error);
           if (ctx.hasUI) ctx.ui.notify(`Advisor consultation failed: ${message}`, "error");
         })
-        .finally(() => manualConsultations.delete(controller));
+        .finally(() => {
+          manualConsultations.delete(controller);
+          herdrAdvisorActivity.finish();
+        });
     },
   });
 
@@ -149,6 +164,11 @@ export const registerCommands = (pi: ExtensionAPI, dependencies: { consult?: typ
         completionGate: advisorCompletionGateRef,
         collapseResponses: advisorCollapseResponsesRef,
         customRule: advisorCustomInvocationRef,
+        blockOnBlocked: advisorBlockOnBlockedRef,
+        autoLoopGate: advisorAutoLoopGateRef,
+        loopThreshold: advisorLoopThresholdRef,
+        maxCallsPerSession: advisorMaxCallsPerSessionRef,
+        sessionSummary: advisorSessionSummaryRef,
       };
       const settings = await ctx.ui.custom<AdvisorSettings | undefined>((tui, theme, _keybindings, done) =>
         new AdvisorSettingsSelector({
@@ -170,6 +190,11 @@ export const registerCommands = (pi: ExtensionAPI, dependencies: { consult?: typ
       setAdvisorCompletionGateRef(settings.completionGate);
       setAdvisorCollapseResponsesRef(settings.collapseResponses);
       setAdvisorCustomInvocationRef(settings.customRule);
+      setAdvisorBlockOnBlockedRef(settings.blockOnBlocked ?? true);
+      setAdvisorAutoLoopGateRef(settings.autoLoopGate ?? true);
+      setAdvisorLoopThresholdRef(settings.loopThreshold ?? 3);
+      setAdvisorMaxCallsPerSessionRef(settings.maxCallsPerSession);
+      setAdvisorSessionSummaryRef(settings.sessionSummary ?? true);
       const path = saveConfig(ctx);
       ctx.ui.notify(`Saved Advisor settings to ${path}`, "info");
     },

package/src/config.ts

@@ -18,6 +18,11 @@ export let advisorFailureGateRef = true;
 export let advisorCompletionGateRef = true;
 export let advisorCustomInvocationRef: string | undefined = undefined;
 export let advisorCollapseResponsesRef = false;
+export let advisorBlockOnBlockedRef = true;
+export let advisorAutoLoopGateRef = true;
+export let advisorLoopThresholdRef = 3;
+export let advisorMaxCallsPerSessionRef: number | undefined = undefined;
+export let advisorSessionSummaryRef = true;
 
 export const setExecutorRef = (ref: string) => { executorRef = ref; };
 export const setAdvisorRef = (ref: string) => { advisorRef = ref; };
@@ -31,6 +36,13 @@ export const setAdvisorFailureGateRef = (enabled: boolean) => { advisorFailureGa
 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 setAdvisorBlockOnBlockedRef = (enabled: boolean) => { advisorBlockOnBlockedRef = enabled; };
+export const setAdvisorAutoLoopGateRef = (enabled: boolean) => { advisorAutoLoopGateRef = enabled; };
+export const isValidLoopThreshold = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 2;
+export const setAdvisorLoopThresholdRef = (value: number) => { advisorLoopThresholdRef = value; };
+export const isValidMaxCallsPerSession = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+export const setAdvisorMaxCallsPerSessionRef = (value: number | undefined) => { advisorMaxCallsPerSessionRef = value; };
+export const setAdvisorSessionSummaryRef = (enabled: boolean) => { advisorSessionSummaryRef = enabled; };
 
 export const splitRef = (ref: string): [string, string] => {
   const i = ref.indexOf("/");
@@ -53,6 +65,11 @@ type AdvisorConfig = {
   advisorCompletionGate?: boolean;
   advisorCustomInvocation?: string;
   advisorCollapseResponses?: boolean;
+  advisorBlockOnBlocked?: boolean;
+  advisorAutoLoopGate?: boolean;
+  advisorLoopThreshold?: number;
+  advisorMaxCallsPerSession?: number;
+  advisorSessionSummary?: boolean;
 };
 
 const isValidConfig = (value: unknown): value is AdvisorConfig => {
@@ -67,7 +84,12 @@ const isValidConfig = (value: unknown): value is AdvisorConfig => {
     && (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");
+    && (config.advisorCollapseResponses === undefined || typeof config.advisorCollapseResponses === "boolean")
+    && (config.advisorBlockOnBlocked === undefined || typeof config.advisorBlockOnBlocked === "boolean")
+    && (config.advisorAutoLoopGate === undefined || typeof config.advisorAutoLoopGate === "boolean")
+    && (config.advisorLoopThreshold === undefined || isValidLoopThreshold(config.advisorLoopThreshold))
+    && (config.advisorMaxCallsPerSession === undefined || isValidMaxCallsPerSession(config.advisorMaxCallsPerSession))
+    && (config.advisorSessionSummary === undefined || typeof config.advisorSessionSummary === "boolean");
 };
 
 export const loadConfig = (ctx: ExtensionContext) => {
@@ -81,6 +103,11 @@ export const loadConfig = (ctx: ExtensionContext) => {
   advisorCompletionGateRef = true;
   advisorCustomInvocationRef = undefined;
   advisorCollapseResponsesRef = false;
+  advisorBlockOnBlockedRef = true;
+  advisorAutoLoopGateRef = true;
+  advisorLoopThresholdRef = 3;
+  advisorMaxCallsPerSessionRef = undefined;
+  advisorSessionSummaryRef = true;
   for (const path of configPaths(ctx)) {
     if (!path || !existsSync(path)) continue;
     try {
@@ -96,6 +123,11 @@ export const loadConfig = (ctx: ExtensionContext) => {
       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;
+      if (typeof config.advisorBlockOnBlocked === "boolean") advisorBlockOnBlockedRef = config.advisorBlockOnBlocked;
+      if (typeof config.advisorAutoLoopGate === "boolean") advisorAutoLoopGateRef = config.advisorAutoLoopGate;
+      if (isValidLoopThreshold(config.advisorLoopThreshold)) advisorLoopThresholdRef = config.advisorLoopThreshold;
+      if (isValidMaxCallsPerSession(config.advisorMaxCallsPerSession)) advisorMaxCallsPerSessionRef = config.advisorMaxCallsPerSession;
+      if (typeof config.advisorSessionSummary === "boolean") advisorSessionSummaryRef = config.advisorSessionSummary;
       return path;
     } catch {
       // Ignore malformed config and keep looking for a valid fallback.
@@ -127,6 +159,11 @@ export const saveConfig = (ctx: ExtensionContext) => {
     advisorCompletionGate: advisorCompletionGateRef,
     advisorCustomInvocation: advisorCustomInvocationRef,
     advisorCollapseResponses: advisorCollapseResponsesRef,
+    advisorBlockOnBlocked: advisorBlockOnBlockedRef,
+    advisorAutoLoopGate: advisorAutoLoopGateRef,
+    advisorLoopThreshold: advisorLoopThresholdRef,
+    ...(advisorMaxCallsPerSessionRef === undefined ? {} : { advisorMaxCallsPerSession: advisorMaxCallsPerSessionRef }),
+    advisorSessionSummary: advisorSessionSummaryRef,
   };
   writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`);
   return path;

package/src/herdr.ts

@@ -0,0 +1,126 @@
+import net from "node:net";
+
+const SOURCE = "pi-advisor:advisor-activity";
+const BLOCK_SOURCE = "pi-advisor:advisor-block";
+const HERDR_PI_SOURCE = "herdr:pi";
+let sequence = Date.now() * 1_000;
+
+const nextSequence = () => ++sequence;
+
+type HerdrRequest = {
+  id: string;
+  method: "pane.report_metadata";
+  params: {
+    pane_id: string;
+    source: string;
+    agent: "pi";
+    applies_to_source: string;
+    state_labels?: { working?: string; blocked?: string };
+    clear_state_labels?: true;
+    seq: number;
+  };
+};
+
+type Report = (request: HerdrRequest) => void;
+
+const sendToHerdr: Report = (request) => {
+  if (process.env.HERDR_ENV !== "1") return;
+  const paneId = process.env.HERDR_PANE_ID;
+  const socketPath = process.env.HERDR_SOCKET_PATH;
+  if (!paneId || !socketPath) return;
+
+  const endpoint = process.platform === "win32" ? `\\\\.\\pipe\\${socketPath}` : socketPath;
+  const socket = net.createConnection(endpoint);
+  const timeout = setTimeout(() => socket.destroy(), 500);
+  timeout.unref?.();
+  socket.once("connect", () => socket.write(`${JSON.stringify(request)}\n`));
+  socket.once("data", () => socket.destroy());
+  socket.once("error", () => socket.destroy());
+  socket.once("close", () => clearTimeout(timeout));
+};
+
+export class HerdrAdvisorActivity {
+  #activeConsultations = 0;
+
+  constructor(private readonly report: Report = sendToHerdr) {}
+
+  start() {
+    this.#activeConsultations += 1;
+    if (this.#activeConsultations === 1) this.safeReport(false);
+  }
+
+  finish() {
+    if (this.#activeConsultations === 0) return;
+    this.#activeConsultations -= 1;
+    if (this.#activeConsultations === 0) this.safeReport(true);
+  }
+
+  clear() {
+    if (this.#activeConsultations === 0) return;
+    this.#activeConsultations = 0;
+    this.safeReport(true);
+  }
+
+  private safeReport(clear: boolean) {
+    try {
+      this.report(this.request(clear));
+    } catch {
+      // Herdr is optional; an unavailable integration must never affect advice.
+    }
+  }
+
+  private request(clear: boolean): HerdrRequest {
+    return {
+      id: `${SOURCE}:${nextSequence()}`,
+      method: "pane.report_metadata",
+      params: {
+        pane_id: process.env.HERDR_PANE_ID ?? "",
+        source: SOURCE,
+        agent: "pi",
+        applies_to_source: HERDR_PI_SOURCE,
+        ...(clear ? { clear_state_labels: true } : { state_labels: { working: "seeking advice" } }),
+        seq: nextSequence(),
+      },
+    };
+  }
+}
+
+export class HerdrAdvisorBlock {
+  #blocked = false;
+
+  constructor(private readonly report: Report = sendToHerdr) {}
+
+  set(reason: string) {
+    this.#blocked = true;
+    this.safeReport({ blocked: reason });
+  }
+
+  clear() {
+    if (!this.#blocked) return;
+    this.#blocked = false;
+    try {
+      this.report({
+        id: `${BLOCK_SOURCE}:${nextSequence()}`,
+        method: "pane.report_metadata",
+        params: { pane_id: process.env.HERDR_PANE_ID ?? "", source: BLOCK_SOURCE, agent: "pi", applies_to_source: HERDR_PI_SOURCE, clear_state_labels: true, seq: nextSequence() },
+      });
+    } catch {
+      // Herdr remains optional.
+    }
+  }
+
+  private safeReport(labels: { blocked: string }) {
+    try {
+      this.report({
+        id: `${BLOCK_SOURCE}:${nextSequence()}`,
+        method: "pane.report_metadata",
+        params: { pane_id: process.env.HERDR_PANE_ID ?? "", source: BLOCK_SOURCE, agent: "pi", applies_to_source: HERDR_PI_SOURCE, state_labels: labels, seq: nextSequence() },
+      });
+    } catch {
+      // Herdr remains optional.
+    }
+  }
+}
+
+export const herdrAdvisorActivity = new HerdrAdvisorActivity();
+export const herdrAdvisorBlock = new HerdrAdvisorBlock();

package/src/session-state.ts

@@ -0,0 +1,76 @@
+export type AdvisorVerdict = "proceed" | "revise" | "blocked" | "insufficient-evidence";
+export type ConsultationOrigin = "executor" | "automatic" | "manual";
+
+type Consultation = { origin: ConsultationOrigin; verdict?: AdvisorVerdict };
+
+const stableJson = (value: unknown): string => {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  const record = value as Record<string, unknown>;
+  return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
+};
+
+export class AdvisorSessionState {
+  #previousSignature?: string;
+  #repetitions = 0;
+  #blockedReason?: string;
+  #consultations: Consultation[] = [];
+  #loopInterventions = 0;
+  #automaticCalls = 0;
+
+  resetTask() {
+    this.#previousSignature = undefined;
+    this.#repetitions = 0;
+    this.#blockedReason = undefined;
+    this.#consultations = [];
+    this.#loopInterventions = 0;
+    this.#automaticCalls = 0;
+  }
+
+  clearBlocked() { this.#blockedReason = undefined; }
+  resetRepetition() { this.#previousSignature = undefined; this.#repetitions = 0; }
+  get blocked() { return this.#blockedReason !== undefined; }
+  get blockedReason() { return this.#blockedReason; }
+  block(reason: string) { this.#blockedReason ??= reason; }
+
+  recordToolCall(toolName: string, input: unknown, threshold: number) {
+    if (toolName === "ask_advisor") return false;
+    const signature = `${toolName}:${stableJson(input)}`;
+    this.#repetitions = signature === this.#previousSignature ? this.#repetitions + 1 : 1;
+    this.#previousSignature = signature;
+    if (this.#repetitions < threshold) return false;
+    this.#loopInterventions += 1;
+    return true;
+  }
+
+  canUseAutomaticCall(limit: number | undefined) {
+    return limit === undefined || this.#automaticCalls < limit;
+  }
+
+  consumeAutomaticCall() { this.#automaticCalls += 1; }
+  remainingAutomaticCalls(limit: number | undefined) {
+    return limit === undefined ? undefined : Math.max(0, limit - this.#automaticCalls);
+  }
+
+  recordConsultation(origin: ConsultationOrigin, verdict?: AdvisorVerdict) {
+    this.#consultations.push({ origin, verdict });
+  }
+
+  summary(limit: number | undefined) {
+    if (this.#consultations.length === 0 && this.#loopInterventions === 0) return undefined;
+    const count = (origin: ConsultationOrigin) => this.#consultations.filter((item) => item.origin === origin).length;
+    const verdicts = (["proceed", "revise", "insufficient-evidence", "blocked"] as AdvisorVerdict[])
+      .map((verdict) => [verdict, this.#consultations.filter((item) => item.verdict === verdict).length] as const)
+      .filter(([, count]) => count > 0)
+      .map(([verdict, count]) => `${count} ${verdict}`)
+      .join(", ") || "none recorded";
+    const budget = limit === undefined ? "unlimited" : `${this.#automaticCalls} / ${limit} used`;
+    return [
+      "[Session Advisor Summary]",
+      `Consultations: ${this.#consultations.length} — ${count("executor")} Executor-requested, ${count("automatic")} automatic, ${count("manual")} manual`,
+      `Verdicts: ${verdicts}`,
+      `Loop interventions: ${this.#loopInterventions}`,
+      `Automatic budget: ${budget}`,
+    ].join("\n");
+  }
+}

package/src/tools.ts

@@ -3,10 +3,14 @@ import { getMarkdownTheme, type ExtensionAPI, type ExtensionContext } from "@ear
 import { Box, Markdown, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import {
-  advisorCollapseResponsesRef, advisorCompletionGateRef, advisorCustomInvocationRef, advisorFailureGateRef, advisorPlanGateRef,
+  advisorAutoLoopGateRef, advisorMaxCallsPerSessionRef, advisorBlockOnBlockedRef, advisorCollapseResponsesRef, advisorCompletionGateRef, advisorCustomInvocationRef, advisorFailureGateRef, advisorLoopThresholdRef, advisorPlanGateRef, advisorSessionSummaryRef,
   advisorRef, advisorEffortRef, contextMaxCharsRef, loadConfig, splitRef,
 } from "./config.js";
 import { recentConversation, textFrom } from "./conversation.js";
+import { herdrAdvisorActivity, herdrAdvisorBlock } from "./herdr.js";
+import { AdvisorSessionState, type AdvisorVerdict } from "./session-state.js";
+
+export const advisorSessionState = new AdvisorSessionState();
 
 export const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 export const resolveAdvisorRequest = (question?: string) => question?.trim() || undefined;
@@ -45,9 +49,30 @@ export const ADVISOR_SYSTEM = [
   "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.",
+  "You do not act or take over planning. Return only a JSON object with verdict (proceed, revise, insufficient-evidence, or blocked), criticalFindings (array of {severity, claim, evidence}), missingEvidence (string array), smallestNextStep (string), verificationRequired (string array), and escalationReason (string or null). Use blocked only for a critical issue requiring the user; never claim verification that the supplied evidence does not show.",
 ].join(" ");
 
+type Advice = { verdict: AdvisorVerdict; criticalFindings: Array<{ severity: string; claim: string; evidence: string }>; missingEvidence: string[]; smallestNextStep: string; verificationRequired: string[]; escalationReason: string | null };
+
+export const parseAdvice = (text: string): Advice => {
+  try {
+    const value = JSON.parse(text) as Partial<Advice>;
+    if (!["proceed", "revise", "blocked", "insufficient-evidence"].includes(value.verdict ?? "")) throw new Error("invalid verdict");
+    if (!Array.isArray(value.criticalFindings) || !Array.isArray(value.missingEvidence) || !Array.isArray(value.verificationRequired) || typeof value.smallestNextStep !== "string" || !value.missingEvidence.every((item) => typeof item === "string") || !value.verificationRequired.every((item) => typeof item === "string") || !value.criticalFindings.every((item) => item && typeof item === "object" && typeof (item as Record<string, unknown>).severity === "string" && typeof (item as Record<string, unknown>).claim === "string" && typeof (item as Record<string, unknown>).evidence === "string")) throw new Error("invalid shape");
+    return { verdict: value.verdict as AdvisorVerdict, criticalFindings: value.criticalFindings as Advice["criticalFindings"], missingEvidence: value.missingEvidence as string[], smallestNextStep: value.smallestNextStep, verificationRequired: value.verificationRequired as string[], escalationReason: typeof value.escalationReason === "string" ? value.escalationReason : null };
+  } catch {
+    return { verdict: "insufficient-evidence", criticalFindings: [{ severity: "medium", claim: "Advisor response was not structured", evidence: "The response could not be parsed as the required JSON." }], missingEvidence: [], smallestNextStep: "Request a structured Advisor review before relying on this advice.", verificationRequired: [], escalationReason: null };
+  }
+};
+
+const adviceForText = (advice: Advice) => [
+  `**Verdict: ${advice.verdict}**`,
+  ...advice.criticalFindings.map((finding) => `- **${finding.severity}:** ${finding.claim}${finding.evidence ? ` — ${finding.evidence}` : ""}`),
+  advice.missingEvidence.length ? `\n**Missing evidence**\n${advice.missingEvidence.map((item) => `- ${item}`).join("\n")}` : "",
+  `\n**Smallest next step**\n${advice.smallestNextStep}`,
+  advice.verificationRequired.length ? `\n**Required verification**\n${advice.verificationRequired.map((item) => `- ${item}`).join("\n")}` : "",
+].filter(Boolean).join("\n");
+
 export const consult = async (
   ctx: ExtensionContext,
   question?: string,
@@ -99,17 +124,102 @@ export const consult = async (
     .trim() || responseText;
 
   if (!advice) throw new Error("Advisor returned no advice.");
-  return { advice, thinkingText };
+  const structured = parseAdvice(advice);
+  return { advice: adviceForText(structured), thinkingText, structured };
 };
 
 export const registerAdvisorTool = (pi: ExtensionAPI) => {
+  const session = advisorSessionState;
+
+  pi.registerMessageRenderer?.("advisor-loop-call", (message, _options, theme) => {
+    const details = message.details as { question?: string } | undefined;
+    return renderAdvisorCallBox(details?.question, theme);
+  });
+
+  pi.on("session_start", () => {
+    session.resetTask();
+    herdrAdvisorBlock.clear();
+  });
+
   pi.on("before_agent_start", (_event, ctx) => {
     if (!pi.getActiveTools().includes("ask_advisor")) return;
     loadConfig(ctx);
     const guidelines = advisorInvocationGuidelines();
+    const budget = session.remainingAutomaticCalls(advisorMaxCallsPerSessionRef);
+    if (budget !== undefined) guidelines.push(`Advisor calls remaining this session: ${budget}.\nReserve calls for material decisions, repeated failures, or final review.`);
     return guidelines.length > 0 ? { systemPrompt: `${ctx.getSystemPrompt()}\n\nAdvisor invocation settings:\n${guidelines.map((rule) => `- ${rule}`).join("\n")}` } : undefined;
   });
 
+  pi.on("tool_call", async (event, ctx) => {
+    if (!pi.getActiveTools().includes("ask_advisor")) return;
+    loadConfig(ctx);
+    if (event.toolName === "ask_advisor" && !session.canUseAutomaticCall(advisorMaxCallsPerSessionRef)) {
+      return { block: true, reason: "Advisor call budget exhausted for this session." };
+    }
+    if (!advisorAutoLoopGateRef) return;
+    if (!session.recordToolCall(event.toolName, event.input, advisorLoopThresholdRef)) return;
+    let reason = `Advisor loop gate: ${event.toolName} repeated ${advisorLoopThresholdRef} times without a different tool action.`;
+    let blockSession = false;
+    if (session.canUseAutomaticCall(advisorMaxCallsPerSessionRef)) {
+      session.consumeAutomaticCall();
+      herdrAdvisorActivity.start();
+      pi.sendMessage({
+        customType: "advisor-loop-call",
+        content: "Automatic Advisor loop review",
+        display: true,
+        details: { question: `Loop gate: ${event.toolName} repeated ${advisorLoopThresholdRef} times` },
+      }, { deliverAs: "steer" });
+      try {
+        const { advice, structured } = await consult(ctx, `${reason} Review the repeated actions and recommend the smallest safe next step.`);
+        session.recordConsultation("automatic", structured.verdict);
+        pi.sendMessage({
+          customType: "advisor-manual-result",
+          content: `Automatic loop-gate Advisor review:\n\n${advice}`,
+          display: true,
+          details: { advisor: advisorRef, text: advice },
+        }, { deliverAs: "steer" });
+        if (structured.verdict === "proceed") {
+          session.resetRepetition();
+          return;
+        }
+        blockSession = structured.verdict === "blocked";
+        if (blockSession) {
+          const escalation = structured.escalationReason || structured.smallestNextStep;
+          session.block(escalation);
+          herdrAdvisorBlock.set(escalation);
+        } else {
+          reason = "Advisor loop review delivered. Follow its guidance before retrying this command.";
+        }
+      } catch (error) {
+        session.recordConsultation("automatic");
+        const message = error instanceof Error ? error.message : String(error);
+        reason = `${reason}\nAdvisor loop review failed: ${message}`;
+        session.block(reason);
+        herdrAdvisorBlock.set(reason);
+        blockSession = true;
+        if (ctx.hasUI) ctx.ui.notify(`Advisor loop review failed. Session is blocked: ${message}`, "error");
+      } finally {
+        herdrAdvisorActivity.finish();
+      }
+    } else {
+      reason = `${reason}\nAdvisor loop review was not run because the session call budget is exhausted.`;
+      session.block(reason);
+      herdrAdvisorBlock.set(reason);
+      blockSession = true;
+      if (ctx.hasUI) ctx.ui.notify("Advisor loop review was not run because the session call budget is exhausted. Session is blocked.", "error");
+    }
+    if (blockSession && advisorBlockOnBlockedRef) ctx.abort();
+    return { block: true, reason };
+  });
+
+  pi.on("agent_settled", (_event, ctx) => {
+    if (session.blocked || !advisorSessionSummaryRef) return;
+    const summary = session.summary(advisorMaxCallsPerSessionRef);
+    if (summary && ctx.hasUI) ctx.ui.notify(summary, "info");
+  });
+
+  pi.on("session_shutdown", () => herdrAdvisorBlock.clear());
+
   pi.registerTool({
     name: "ask_advisor",
     label: "Ask Advisor",
@@ -159,16 +269,29 @@ export const registerAdvisorTool = (pi: ExtensionAPI) => {
     },
     async execute(_id, params, signal, onUpdate, ctx) {
       const question = resolveAdvisorRequest(params.question);
-      const { advice, thinkingText } = await consult(ctx, question, signal, (t, tx) => {
-        onUpdate?.({
-          content: [{ type: "text", text: tx }],
-          details: { thinking: t, text: tx, advisor: advisorRef, question },
+      herdrAdvisorActivity.start();
+      try {
+        session.consumeAutomaticCall();
+        const { advice, thinkingText, structured } = await consult(ctx, question, signal, (t, tx) => {
+          onUpdate?.({
+            content: [{ type: "text", text: tx }],
+            details: { thinking: t, text: tx, advisor: advisorRef, question },
+          });
         });
-      });
-      return {
-        content: [{ type: "text", text: `Advisor (${advisorRef})\n\n${advice}` }],
-        details: { thinking: thinkingText, text: advice, advisor: advisorRef, question },
-      };
+        session.recordConsultation("executor", structured.verdict);
+        if (structured.verdict === "blocked") {
+          const reason = structured.escalationReason || structured.smallestNextStep;
+          session.block(reason);
+          herdrAdvisorBlock.set(reason);
+          if (advisorBlockOnBlockedRef) ctx.abort();
+        }
+        return {
+          content: [{ type: "text", text: `Advisor (${advisorRef})\n\n${advice}` }],
+          details: { thinking: thinkingText, text: advice, advisor: advisorRef, question, verdict: structured.verdict },
+        };
+      } finally {
+        herdrAdvisorActivity.finish();
+      }
     },
   });
 };

package/src/ui.ts

@@ -104,6 +104,11 @@ export type AdvisorSettings = {
   completionGate: boolean;
   collapseResponses: boolean;
   customRule?: string;
+  blockOnBlocked?: boolean;
+  autoLoopGate?: boolean;
+  loopThreshold?: number;
+  maxCallsPerSession?: number;
+  sessionSummary?: boolean;
 };
 
 export class AdvisorSettingsSelector implements Component, Focusable {
@@ -178,9 +183,14 @@ export class AdvisorSettingsSelector implements Component, Focusable {
       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),
+      this.row("Block on critical advice", onOff(this.settings.blockOnBlocked ?? true), 7),
+      this.row("Automatic loop gate", onOff(this.settings.autoLoopGate ?? true), 8),
+      this.row("Loop threshold", `After ${this.settings.loopThreshold ?? 3} repeats`, 9),
+      this.row("Max Advisor calls/session", this.settings.maxCallsPerSession === undefined ? "∞" : String(this.settings.maxCallsPerSession), 10),
+      this.row("Session Advisor Summary", onOff(this.settings.sessionSummary ?? true), 11),
     ];
     if (this.editingCustom) rows.push(`    ${this.customInput.render(Math.max(10, width - 6))[0] || ""}`);
-    rows.push(this.row("Save changes", "", 7));
+    rows.push(this.row("Save changes", "", 12));
     return [
       theme.fg("accent", theme.bold("  Advisor settings")),
       "",
@@ -203,7 +213,7 @@ export class AdvisorSettingsSelector implements Component, Focusable {
     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);
+      this.selectedRow = Math.min(12, this.selectedRow + 1);
     } else if (matchesKey(keyData, Key.left)) {
       this.adjust(-1);
     } else if (matchesKey(keyData, Key.right)) {
@@ -216,7 +226,7 @@ export class AdvisorSettingsSelector implements Component, Focusable {
         tui.requestRender();
         return;
       }
-      if (this.selectedRow === 7) return this.options.onSave({ ...this.settings, contextMaxChars: this.currentContext().value, effort: this.options.effortLevels[this.effortIndex] });
+      if (this.selectedRow === 12) 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();
@@ -232,6 +242,16 @@ export class AdvisorSettingsSelector implements Component, Focusable {
       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;
+      case 7: this.settings.blockOnBlocked = !(this.settings.blockOnBlocked ?? true); break;
+      case 8: this.settings.autoLoopGate = !(this.settings.autoLoopGate ?? true); break;
+      case 9: this.settings.loopThreshold = Math.max(2, (this.settings.loopThreshold ?? 3) + direction); break;
+      case 10: {
+        const values = [undefined, 0, 1, 2, 3, 5, 10, 25, 50];
+        const index = Math.max(0, values.indexOf(this.settings.maxCallsPerSession));
+        this.settings.maxCallsPerSession = values[Math.max(0, Math.min(values.length - 1, index + direction))];
+        break;
+      }
+      case 11: this.settings.sessionSummary = !(this.settings.sessionSummary ?? true); break;
     }
   }
 }