pi-delegation-policy 0.22.0 → 0.22.2

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.22.2 - 2026-10-28
+
+### Fixed
+
+- The Advisor no longer rejects a verified `pi-subagents` build. Each launch definition now declares
+  the exact list of package versions whose launch contract it was checked against: the Advisor admits
+  `0.76.1` and `0.83.1`, while the ContextShunt reader keeps its single verified `0.76.1`, so the
+  reader limit does not widen. Everything else in the launch check is unchanged: exact profile
+  projection and digest shape, exact model and thinking, host session binding, empty tools and
+  extensions, the pinned `@gotgenes/pi-permission-system` `33.0.3` runtime, and the terminal digest
+  binding. A build outside the list still fails closed before any request is sent.
+
+  The two contracts were compared from their real preflight payloads: they differ only in the package
+  version, the install path of the runtime extension and the digests derived from that path, and the
+  public fork wrapper is byte-identical. Admission and terminal binding were exercised in an isolated
+  host that answered with each contract's own digest. That does not cover provider transport, real
+  child execution or a real consultation, which remain unverified, and it does not explain the
+  Advisor failure reported on a forked session or the menu/status discrepancy; both stay open.
+
+## 0.22.1 - 2026-10-22
+
+### Fixed
+
+- The footer no longer keeps a stale `D:ERR` from session start when an ordinary model becomes
+  available only after this extension's `session_start` handler. Another extension may fill the model
+  catalog in its own start handler, and the host then emits `resources_discover`; a read-only runtime
+  refresh there repaints the footer with the existing validation. This adds one configuration/branch
+  read and footer refresh per session bind or reload, returns no resource paths, makes no network
+  call, and leaves the configuration-change notice reference alone, so a pending change is not lost.
+  A model that is genuinely missing or unusable still reports `D:ERR`. The fix relies on the public
+  post-start discovery order, verified in Pi `0.87.1` and `1.1.0`; availability changes after that
+  event still refresh on the next request or menu action.
+
 ## 0.22.0 - 2026-10-21
 
 ### Added

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.22.0** requires Pi `0.87.1` or later (`>=0.87.1`); it re-applies its marked policy block in the final provider payload.
+> Version **0.22.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.22.0
+pi install npm:pi-delegation-policy@0.22.2
 # restart Pi, or run /reload
 ```
 
@@ -77,8 +77,10 @@ same question. Weigh disagreements; agreement is not proof. The packaged no-tool
 - `role`: the main agent launches every valid advisor in one background subagent call, with exact
   models and thinking. The extension observes matching attempts but does not launch them.
 - `tool`: the always-registered `consult_advisor({ question, brief? })` launches one child per valid
-  advisor in parallel through the public `pi-subagents` delegation API, pinned to `0.76.1`. Otherwise
-  it returns unavailable text. No model, provider or executor fallback is added.
+  advisor in parallel through the public `pi-subagents` delegation API, admitted only for the exact
+  builds whose launch contract was verified (`0.76.1` and `0.83.1`). Any other build fails closed
+  before a request is sent. Otherwise it returns unavailable text. No model, provider or executor
+  fallback is added.
 
 Both modes ask for consultation after orientation before substantive work, when stuck, before changing
 approach, and before declaring a multi-step task done (ask for remaining risks, not approval). Short
@@ -190,6 +192,10 @@ example `advisor-mode=with-delegation (global); A:OFF` and `thinking-advisor=uns
 `D:OFF`, `D:NORM`, `D:AGG`, and `D:ORCH` describe delegation; `A:OFF`, `A:ON`, `A:PART`, and `A:ERR` describe
 Advisor. None of them proves that a launch happened or that another system followed the guidance.
 
+The footer also revalidates after all session-start handlers finish. If another extension makes a
+configured model available later in startup, the earlier `D:ERR` is replaced with the current status
+without waiting for a message or menu action. A model that remains invalid still reports `D:ERR`.
+
 ### Configuration change notice
 
 Available from `0.22.0`. The declared Pi peer remains

package/SECURITY.md

@@ -15,9 +15,10 @@ mode with an enabled valid advisor, never from hooks. Model input cannot choose
 path, tools or extensions. Fork sends the conversation to each advisor provider; fresh sends the
 question and brief. Disable Advisor when session content must not reach those providers.
 
-The tool reuses strict public preflight and terminal binding pinned to `pi-subagents` `0.76.1`, exact
-models/thinking, the packaged no-tools profile, replace prompt, no project resources, and the reader's
-prompt-only or pinned permission-runtime checks. Host rules remain host-owned. Forked conversation is
+The tool reuses strict public preflight and terminal binding admitted only for the exact `pi-subagents`
+builds whose contract was verified (`0.76.1` and `0.83.1`), exact models/thinking, the packaged
+no-tools profile, replace prompt, no project resources, and the reader's prompt-only or pinned
+permission-runtime checks. Host rules remain host-owned. Forked conversation is
 untrusted data, not authority. Preflight binds the tool session identity; the public REQUEST API cannot
 prove that the live executor session is the same. Terminal mismatch rejection happens only after
 context exposure. The executor/runtime is trusted host code; digests are not signatures or a sandbox.
@@ -52,4 +53,4 @@ Include the affected version or commit, operating system, Pi version, reproducti
 
 ## Supported versions
 
-Only the latest published version is supported. Version `0.21.0` 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.22.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.22.0",
+  "version": "0.22.2",
   "private": false,
   "description": "A Pi extension for configurable delegation intensity and exact subagent role model references.",
   "type": "module",

package/src/advisor-executor.ts

@@ -18,6 +18,13 @@ import type { AdvisorContext } from "./prompt.ts";
 import type { AdvisorSetting, ThinkingLevelName } from "./types.ts";
 import type { ConsultationAttempt } from "./advisor-log.ts";
 
+/**
+ * `pi-subagents` builds whose launch contract was checked against this profile: the original pin and
+ * the build that only changed its own package version (same contract version, profile projection,
+ * tool plan, runtime lists and fork wrapper). A different build is rejected before any request.
+ */
+const ADMITTED_SUBAGENTS_VERSIONS: readonly string[] = ["0.76.1", "0.83.1"];
+
 export const ADVISOR_AGENT_NAME = "pi-delegation-policy.advisor";
 export type AdvisorRequest = AgentLaunchRequest & {
   question: string;
@@ -34,7 +41,7 @@ const DEFINITION: AgentLaunchDefinition<AdvisorRequest, string> = {
   agentPath: resolve(
     fileURLToPath(new URL("../agents/pi-delegation-policy.advisor.md", import.meta.url)),
   ),
-  protocolVersion: "0.76.1",
+  admittedProtocolVersions: ADMITTED_SUBAGENTS_VERSIONS,
   allowFork: true,
   internalTools: [],
   buildTask: (request) =>
@@ -84,9 +91,9 @@ function hostStatusText(status: AgentLaunchTerminalStatus | undefined): string {
     case "tool_budget_exhausted":
       return "The host ended the Advisor run at its tool limit before answering. Retry once with a narrower question.";
     case "structured_output_failed":
-      return "The host ended the Advisor run while collecting its structured result. Retry once; if it repeats, inspect host diagnostics and check the compatibility of the installed pi-delegation-policy and pi-subagents 0.76.1 build.";
+      return "The host ended the Advisor run while collecting its structured result. Retry once; if it repeats, inspect host diagnostics and check that the installed pi-delegation-policy and pi-subagents builds are compatible.";
     case "acceptance_failed":
-      return "The host ended the Advisor run at its acceptance check. Retry once; if it repeats, inspect host diagnostics and check the compatibility of the installed pi-delegation-policy and pi-subagents 0.76.1 build.";
+      return "The host ended the Advisor run at its acceptance check. Retry once; if it repeats, inspect host diagnostics and check that the installed pi-delegation-policy and pi-subagents builds are compatible.";
     case "failed":
       return "The host ended the Advisor run with status failed and supplied no safe detail. Retry once; if it repeats, check the installed pi-subagents version.";
     default:
@@ -98,11 +105,11 @@ function unavailableFailureText(reason: AgentLaunchFailure | undefined): string
   const preflightSeconds = LAUNCH_PREFLIGHT_TIMEOUT_MS / 1000;
   switch (reason?.code) {
     case "fork-task-normalizer-unavailable":
-      return "Fork launch is unavailable: the installed pi-subagents does not export wrapForkTask, so a fork task cannot be bound to the child. Retrying or supplying a brief will not switch this session to fresh; install the compatible pi-subagents 0.76.1 build and reload the session.";
+      return "Fork launch is unavailable: the installed pi-subagents does not export wrapForkTask, so a fork task cannot be bound to the child. Retrying or supplying a brief will not switch this session to fresh; install an admitted pi-subagents build and reload the session.";
     case "modules-unavailable":
-      return "Advisor launch is unavailable: the pi-subagents 0.76.1 exports this extension requires were not found. Install the compatible pi-subagents 0.76.1 build, then reload the session.";
+      return "Advisor launch is unavailable: the pi-subagents exports this extension requires were not found. Install an admitted pi-subagents build, then reload the session.";
     case "preflight-unavailable":
-      return "Advisor preflight returned no launch contract. Retry once; if it repeats, check the compatible pi-subagents 0.76.1 build and the packaged Advisor profile.";
+      return "Advisor preflight returned no launch contract. Retry once; if it repeats, check the installed pi-subagents build and the packaged Advisor profile.";
     case "preflight-timeout":
       return `Advisor preflight did not finish within ${preflightSeconds} seconds. Retry once; if it repeats, check the installed pi-subagents version.`;
     case "contract-rejected":
@@ -110,7 +117,7 @@ function unavailableFailureText(reason: AgentLaunchFailure | undefined): string
     case "request-start-timeout":
       return `The host did not start the Advisor within ${preflightSeconds} seconds. Retry once; if it repeats, check the installed pi-subagents version.`;
     case "request-emit-failed":
-      return "The host could not set up or send the Advisor launch event. Reload the session, then retry; if it repeats, check the installed extension against the compatible pi-subagents 0.76.1 build.";
+      return "The host could not set up or send the Advisor launch event. Reload the session, then retry; if it repeats, check the installed extension against an admitted pi-subagents build.";
     case "host-session-missing":
       return "Advisor unavailable: the host supplied no session identity.";
     case "fork-not-allowed":
@@ -131,7 +138,7 @@ function failedFailureText(reason: AgentLaunchFailure | undefined): string {
     case "terminal-metadata-mismatch":
       return `The host returned an Advisor reply whose ${terminalFieldText(reason.field)} did not match the preflight contract, so the reply was discarded. Retry once; if it repeats, report the mismatch.`;
     case "terminal-result-invalid":
-      return "The host reported completion without a usable text answer, so the result was discarded. Retry once; if it repeats, inspect host diagnostics and check the compatibility of the extension with the installed pi-subagents 0.76.1 build.";
+      return "The host reported completion without a usable text answer, so the result was discarded. Retry once; if it repeats, inspect host diagnostics and check the compatibility of the extension with the installed pi-subagents build.";
     case "host-terminal-status":
       return hostStatusText(reason.status);
     case "host-status-unrecognized":

package/src/agent-launch.ts

@@ -148,7 +148,12 @@ export type AgentLaunchDefinition<Request extends AgentLaunchRequest, Value> = R
   agentPath: string;
   /** Only the advisor may send a fork; reader requests remain fresh-only. */
   allowFork?: boolean;
-  protocolVersion: string;
+  /**
+   * The `pi-subagents` package versions whose launch contract this profile was verified against.
+   * An exact, per-profile list: no range, wildcard or fallback, so a new build is rejected until
+   * its contract is checked.
+   */
+  admittedProtocolVersions: readonly string[];
   /**
    * Builtin tools the child must expose. A profile that declares no tools and no
    * extensions exposes exactly these, so the contract must report the same list
@@ -415,7 +420,8 @@ function validateLaunchContract<Request extends AgentLaunchRequest, Value>(
       contract.version !== LAUNCH_CONTRACT_VERSION ||
       !isRecord(contract.protocol) ||
       contract.protocol.lifecycleArtifactVersion !== 3 ||
-      contract.protocol.packageVersion !== definition.protocolVersion ||
+      typeof contract.protocol.packageVersion !== "string" ||
+      !definition.admittedProtocolVersions.includes(contract.protocol.packageVersion) ||
       contract.runId !== active.requestId ||
       !isLowerHexDigest(contract.digest)
     )

package/src/context-shunt-executor.ts

@@ -109,7 +109,7 @@ function isReaderAnswer(value: unknown): value is ReaderAnswer {
 const READER_LAUNCH = {
   agentName: CONTEXT_SHUNT_READER_AGENT_NAME,
   agentPath: CONTEXT_SHUNT_READER_AGENT_PATH,
-  protocolVersion: CONTEXT_SHUNT_READER_PROTOCOL_VERSION,
+  admittedProtocolVersions: [CONTEXT_SHUNT_READER_PROTOCOL_VERSION],
   internalTools: ["structured_output"],
   buildTask: buildReaderTask,
   result: {

package/src/index.ts

@@ -896,6 +896,14 @@ export function createPiDelegationPolicy(options: PiDelegationPolicyOptions = {}
       advisorContext = undefined;
       startConfigBaseline(await refreshRuntime(ctx));
     });
+    // The host emits this after every `session_start` handler has run, so a model catalog another
+    // extension fills during its own start handler is visible here and the footer stops reporting an
+    // error that no longer applies. It only re-reads the runtime and repaints: no resource paths, no
+    // network, no new validation rules, and the notice reference stays as the start left it, so a pending
+    // change is not lost.
+    pi.on("resources_discover", async (_event, ctx) => {
+      await refreshRuntime(ctx);
+    });
     pi.on("input", async (event) => {
       // The host emits this for every submitted input immediately before the prompt it belongs to,
       // and `before_agent_start` follows only for a fresh prompt. Attribution therefore depends on