pi-delegation-policy 0.23.1 → 0.23.2

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## Unreleased
 
+## 0.23.2 - 2026-10-31
+
+### Fixed
+
+- `consult_advisor` now tells the model what to do for the effective Advisor state instead of
+  suggesting a switch to tool mode. Off means no consultation; role mode redirects to one background
+  host subagent call with every valid Advisor's exact profile, model and thinking policy, and says
+  not to call this tool again. Unavailable entries report their existing diagnostics. Invalid saved
+  Advisor settings explicitly require informing the user to save them again in `/delegate`, without
+  retrying the tool; ordinary availability errors do not ask for configuration changes.
+- Busy, blank-question and missing-session replies now state the next action. ContextShunt recovery
+  errors also explain whether to use another range, obtain live evidence or continue without recovery.
+  The reader's JSON error contract is unchanged.
+
+### Compatibility and verification
+
+- No configuration, schema, dependency, profile, permission or Pi minimum change. Upgrade and reload;
+  no migration is needed. Tool definitions stay fixed across modes and requests. The tool description
+  changes once on upgrade, but no additional policy-block or tool-definition variation is introduced.
+- Registered-tool tests cover off, role, invalid and valid tool calls, exact thinking rules and stable
+  definitions. Saved-state guidance is tested at the message constructor without corrupt files; its
+  connection to the registered tool was reviewed. Policy output was independently checked byte for
+  byte against the previous release. These checks do not measure provider cache hits or establish
+  real-model behavior after an accidental role-mode tool call.
+
 ## 0.23.1 - 2026-10-29
 
 ### Fixed

package/README.md

@@ -6,7 +6,7 @@ general subagent runner. Only explicit tools can request reader work or Advisor
 the authorized host executor; hooks never launch children.
 
 > **Docs:** [yivas.github.io/pi-delegation-policy](https://yivas.github.io/pi-delegation-policy/).
-> Version **0.23.1** requires Pi `0.87.1` or later (`>=0.87.1`); it re-applies its marked policy block in the final provider payload.
+> Version **0.23.2** requires Pi `0.87.1` or later (`>=0.87.1`); it re-applies its marked policy block in the final provider payload.
 > Version `0.14.1` supports Pi `0.84.3` or later (`>=0.84.3`).
 >
 > Independent Advisor mode and its companion file are available from version `0.17.0`.
@@ -15,7 +15,7 @@ the authorized host executor; hooks never launch children.
 ## Install
 
 ```bash
-pi install npm:pi-delegation-policy@0.23.1
+pi install npm:pi-delegation-policy@0.23.2
 # restart Pi, or run /reload
 ```
 

package/SECURITY.md

@@ -69,4 +69,4 @@ Include the affected version or commit, operating system, Pi version, reproducti
 
 ## Supported versions
 
-Only the latest published version is supported. Version `0.23.1` requires Pi `0.87.1` or later; version `0.14.1` requires Pi `0.84.3` or later.
+Only the latest published version is supported. Version `0.23.2` requires Pi `0.87.1` or later; version `0.14.1` requires Pi `0.84.3` or later.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-delegation-policy",
-  "version": "0.23.1",
+  "version": "0.23.2",
   "private": false,
   "description": "A Pi extension for configurable delegation intensity and exact subagent role model references.",
   "type": "module",

package/src/context-shunt-adapter.ts

@@ -132,7 +132,8 @@ export class ContextShuntAdapter {
   ): Promise<{ text?: string; error?: string; range?: string }> {
     if (settings.mode !== "enforce") {
       return {
-        error: "ContextShunt recovery is unavailable while enforcement is off.",
+        error:
+          "ContextShunt recovery is unavailable while enforcement is off. Continue without recovery; do not ask the user to enable enforcement unless they raise it.",
       };
     }
     const result = await this.artifacts.recover(request, settings.limits.targetedReadBytes);

package/src/context-shunt.ts

@@ -393,19 +393,26 @@ export class ArtifactStore {
 
   async recover(request: RecoveryRequest, maxRangeBytes: number): Promise<RecoveryResult> {
     return this.withLock(async () => {
-      if (this.closed) return { error: "Recovery artifact is unavailable or expired." };
+      const unavailable = {
+        error:
+          "Recovery artifact is unavailable or expired. Do not retry this artifact ID; use a new live artifact from an authorized bounded read if the evidence is still needed.",
+      };
+      if (this.closed) return unavailable;
       const hasLines = request.lineOffset !== undefined || request.lineLimit !== undefined;
       const hasBytes = request.byteOffset !== undefined || request.maxBytes !== undefined;
-      if (hasLines === hasBytes) return { error: "Choose either a line range or a byte range." };
+      if (hasLines === hasBytes)
+        return {
+          error:
+            "Choose either a line range or a byte range. Call again with lineOffset/lineLimit or byteOffset/maxBytes, not both.",
+        };
 
       await this.purgeUnlocked();
       const artifact = this.artifacts.get(request.artifactId);
-      if (!artifact) return { error: "Recovery artifact is unavailable or expired." };
+      if (!artifact) return unavailable;
       if (artifact.kind === "derived") {
         if (!artifact.sourceId || !(await this.readSourceUnlocked(artifact.sourceId)))
-          return { error: "Recovery artifact is unavailable or expired." };
-        if (!this.artifacts.has(request.artifactId))
-          return { error: "Recovery artifact is unavailable or expired." };
+          return unavailable;
+        if (!this.artifacts.has(request.artifactId)) return unavailable;
       }
 
       let source: Buffer;
@@ -413,11 +420,11 @@ export class ArtifactStore {
         source = await readFile(artifact.path);
       } catch {
         await this.remove(request.artifactId, artifact);
-        return { error: "Recovery artifact is unavailable or expired." };
+        return unavailable;
       }
       if (digest(source) !== artifact.digest) {
         await this.remove(request.artifactId, artifact);
-        return { error: "Recovery artifact is unavailable or expired." };
+        return unavailable;
       }
 
       if (hasBytes) {
@@ -431,11 +438,16 @@ export class ArtifactStore {
           offset > source.length ||
           offset > Number.MAX_SAFE_INTEGER - length
         ) {
-          return { error: "Invalid byte range." };
+          return {
+            error: `Invalid byte range. Call again with a nonnegative integer byteOffset within the artifact and positive integer maxBytes no greater than ${maxRangeBytes}.`,
+          };
         }
         const end = Math.min(source.length, offset + length);
         if (!isUtf8Boundary(source, offset) || !isUtf8Boundary(source, end)) {
-          return { error: "Byte ranges must start and end at UTF-8 character boundaries." };
+          return {
+            error:
+              "Byte ranges must start and end at UTF-8 character boundaries. Call again with adjusted byte boundaries or use a bounded line range.",
+          };
         }
         return {
           text: source.subarray(offset, end).toString("utf8"),
@@ -446,10 +458,16 @@ export class ArtifactStore {
       const offset = request.lineOffset ?? 0;
       const limit = request.lineLimit ?? 1;
       if (!Number.isSafeInteger(offset) || offset < 0 || !positiveInteger(limit) || limit > 250) {
-        return { error: "Invalid line range." };
+        return {
+          error:
+            "Invalid line range. Call again with a nonnegative integer lineOffset and an integer lineLimit from 1 to 250.",
+        };
       }
       const lines = splitLines(source.toString("utf8"));
-      if (offset >= lines.length) return { error: "Invalid line range." };
+      if (offset >= lines.length)
+        return {
+          error: `Invalid line range. Call again with lineOffset less than ${lines.length}.`,
+        };
       const text = lines.slice(offset, offset + limit).join("");
       if (Buffer.byteLength(text, "utf8") > maxRangeBytes) {
         return { error: "Requested line range exceeds the byte budget; use byte recovery." };

package/src/index.ts

@@ -39,7 +39,12 @@ import {
   readerToolError,
   type ReaderThinking,
 } from "./context-shunt-reader.ts";
-import { type AdvisorContext, buildDelegationPolicy, selectAdvisorContext } from "./prompt.ts";
+import {
+  type AdvisorContext,
+  advisorRoleLines,
+  buildDelegationPolicy,
+  selectAdvisorContext,
+} from "./prompt.ts";
 import { updateProviderPolicy } from "./provider-policy.ts";
 import {
   advisorStatusLabel,
@@ -310,6 +315,20 @@ export function statusText(state: RuntimeState): string {
   if (errors.length) details.push(`details=${errors.join("; ")}`);
   return details.join(" | ");
 }
+export function advisorUnavailableText(state: RuntimeState): string {
+  const entryErrors = state.advisorEntries?.flatMap((entry) => entry.errors) ?? [];
+  const diagnostics = [
+    ...(state.advisorErrors ?? []).filter((error) => !entryErrors.includes(error)),
+    ...(state.advisorEntries ?? []).flatMap((entry) =>
+      entry.errors.map((error) => `Advisor ${entry.index + 1}: ${error}`),
+    ),
+  ];
+  const action = state.diagnostics.some((diagnostic) => diagnostic.scope === "advisor")
+    ? "Continue without Advisor consultation. Tell the user that the saved Advisor configuration is invalid and must be saved again in /delegate. Do not retry this tool."
+    : "Continue without Advisor consultation. Do not retry with the same settings or ask the user to change them unless they raise it.";
+  return `Advisor unavailable: no valid Advisors.\n${diagnostics.join("\n")}\n${action}`;
+}
+
 function notifyAppendFailure(ctx: ExtensionCommandContext, result: GuardedAppendResult): void {
   ctx.ui.notify(
     result === "guard-failed"
@@ -525,7 +544,7 @@ export function createPiDelegationPolicy(options: PiDelegationPolicyOptions = {}
       name: "consult_advisor",
       label: "Consult Advisor",
       description:
-        "Consult the configured advisors after orientation before substantive work, when stuck, before changing approach, and before declaring a multi-step task done (ask for remaining risks, not approval). Skip short reactive steps and mechanics within a settled approach. Supply a self-contained brief for fresh context or a rejected fork. Advice only; may send the conversation to each provider and incur cost.",
+        "Use only when advisor-launch=tool; in role mode launch Advisor with the host subagent tool instead. Consult the configured advisors after orientation before substantive work, when stuck, before changing approach, and before declaring a multi-step task done (ask for remaining risks, not approval). Skip short reactive steps and mechanics within a settled approach. Supply a self-contained brief for fresh context or a rejected fork. Advice only; may send the conversation to each provider and incur cost.",
       parameters: Type.Object(
         {
           question: Type.String({ minLength: 1 }),
@@ -540,22 +559,33 @@ export function createPiDelegationPolicy(options: PiDelegationPolicyOptions = {}
         });
         const state = await refreshRuntime(ctx);
         const advisors = validAdvisors(state);
-        if (state.effective.advisorLaunch !== "tool" || !advisors.length)
+        if (!isAdvisorEnabled(state.effective))
           return text(
-            "Advisor unavailable: select tool launch and enable at least one valid Advisor in /delegate.",
+            "Advisor is off in /delegate for this session. Do not consult it and do not ask the user to enable it unless they raise it.",
+          );
+        if (!advisors.length) return text(advisorUnavailableText(state));
+        if (state.effective.advisorLaunch === "role")
+          return text(
+            `Advisor launch is "role": this tool is not used in role mode; do not call this tool again. Launch every listed Advisor with the host subagent tool, using each exact agent profile and model below, in the background, all listed Advisors with the same question in one call, as the delegation policy describes. Replace LEVEL with a supported thinking level chosen per run under that Advisor's thinking policy; a fixed level must not change.\n${advisorRoleLines(state)}`,
           );
         if (advisorExecutor.busy)
           return text(
-            "Advisor busy: one consultation group is already in flight for this session.",
+            "Advisor busy: one consultation group is already in flight for this session. Wait for its result before starting another consultation; do not duplicate the pending group.",
+          );
+        if (!input.question.trim())
+          return text(
+            "Advisor error: question must not be blank. Call again with a specific question.",
           );
-        if (!input.question.trim()) return text("Advisor error: question must not be blank.");
         const context = resolveAdvisorContext(ctx, state);
         if (context === "fresh" && !input.brief?.trim())
           return text(
             "Advisor error: fresh context requires brief. Supply a short self-contained objective, constraints, relevant facts, options, and uncertainty.",
           );
         const sessionId = currentSessionId(ctx);
-        if (!sessionId) return text("Advisor unavailable: host session identity is missing.");
+        if (!sessionId)
+          return text(
+            "Advisor unavailable: host session identity is missing. Continue without Advisor consultation; do not retry until the host supplies a session identity.",
+          );
         const results = await advisorExecutor.execute(
           advisors.map((entry) => ({
             question: input.question,
@@ -717,7 +747,8 @@ export function createPiDelegationPolicy(options: PiDelegationPolicyOptions = {}
         const result = latestRuntime
           ? await shunt.recover(input, latestRuntime.effective.contextShunt)
           : {
-              error: "ContextShunt recovery is unavailable until session state is initialized.",
+              error:
+                "ContextShunt recovery is unavailable until session state is initialized. Continue without recovery; retry only after the host initializes the session.",
             };
         return {
           content: [

package/src/prompt.ts

@@ -261,14 +261,10 @@ export function buildPolicyPreview(
   ];
 }
 
-export function buildDelegationPolicy(
-  state: RuntimeState,
-  advisorContext: AdvisorContext = "fresh",
-): string | undefined {
+/** Shared with role-mode tool redirection so launch models and thinking stay identical. */
+export function advisorRoleLines(state: RuntimeState): string {
   const { effective } = state;
-  const advisorEnabled = isAdvisorEnabled(effective) && !hasAdvisorError(state);
-  const advisors = advisorEnabled ? validAdvisors(state) : [];
-  const advisorRoleLine = advisors
+  return validAdvisors(state)
     .map(({ index, setting }) => {
       const thinking = roleThinking(setting.thinking);
       const label =
@@ -277,6 +273,16 @@ export function buildDelegationPolicy(
 - ${label}: ${formatReference(setting)}; exact model base: ${formatLaunchModel(setting)}; pi-subagents form: ${formatThinkingLaunchModel(setting, thinking)}; thinking policy: ${thinkingPolicyText(thinking)}; agent profile: ${promptString(advisorAgentName(setting))}${setting.providerExtension ? "; provider extension explicitly enabled: normal configuration, startup hook and account diagnostic command are trusted host code, not model tools. Never invoke the diagnostic automatically." : ""}`;
     })
     .join("");
+}
+
+export function buildDelegationPolicy(
+  state: RuntimeState,
+  advisorContext: AdvisorContext = "fresh",
+): string | undefined {
+  const { effective } = state;
+  const advisorEnabled = isAdvisorEnabled(effective) && !hasAdvisorError(state);
+  const advisors = advisorEnabled ? validAdvisors(state) : [];
+  const advisorRoleLine = advisorEnabled ? advisorRoleLines(state) : "";
   if (effective.intensity === "off" || hasRuntimeError(state)) {
     if (!advisorRoleLine) return undefined;
     return `<delegation_policy>