pi-delegation-policy 0.23.0 → 0.23.1

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 0.23.1 - 2026-10-29
+
+### Fixed
+
+- Advisor and ContextShunt reader launches no longer reject later `pi-subagents` releases solely
+  because their package version is not on an exact list. Both require a valid stable SemVer version
+  `>=0.76.1`, with no upper bound. Prereleases, invalid versions and non-string values are rejected;
+  build metadata does not affect precedence.
+- All other launch checks remain unchanged: contract and lifecycle version 3, definition projection
+  version 2, packaged profile and shadowing, exact model and thinking, tool and extension lists,
+  permission runtime, session identity and terminal digest binding. An incompatible preflight
+  still fails closed before a request is sent; a terminal mismatch still discards the reply.
+
+### Compatibility and verification
+
+- Pi `0.87.1` remains the package minimum. No dependency, configuration, schema, provider option or
+  permission change. Upgrade and reload; no configuration migration is needed.
+- The final loader was exercised against real `pi-subagents` `0.84.0` exports with a synthetic event
+  host on Pi `1.4.0`: Advisor fresh/fork and reader fresh completed with terminal binding. This
+  checks admission, not real child execution, provider transport or personal permission rules.
+  Version labels are not signatures or a guarantee of future compatibility.
+
 ## 0.23.0 - 2026-10-29
 
 ### 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.23.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.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.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.0
+pi install npm:pi-delegation-policy@0.23.1
 # restart Pi, or run /reload
 ```
 
@@ -77,10 +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, 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.
+  advisor in parallel through the public `pi-subagents` delegation API. It requires a stable SemVer
+  version `>=0.76.1`, with no upper bound; prereleases and invalid versions are rejected. Every
+  launch must still pass the strict contract and terminal-binding checks. 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
@@ -264,9 +264,11 @@ one bounded line or byte range. Errors, structured results, images, binaries, mi
 unknown tool contracts stay unchanged, and nothing is launched from a hook. The reader keys
 `readerEnabled`, `readerRole`, and `answerMaxBytes` control the optional
 `context_shunt_delegate`/`context_shunt_recover` pair, which needs `enforce`, an active delegation
-intensity, a valid configuration, and a compatible external executor. The only verified executor is
-`pi-subagents` `0.76.1` on Pi `1.1.0`; Pi `0.87.1`, the declared minimum, is not verified for the
-reader. Other executor builds, including `0.69.0`, fail closed with `reader-unavailable`. Since `0.19.0`,
+intensity, a valid configuration, and a compatible external executor. The reader requires stable
+`pi-subagents` SemVer `>=0.76.1`, with no upper bound, and the unchanged strict launch contract.
+Older, prerelease, invalid or contract-incompatible builds fail closed with `reader-unavailable`.
+The reader was verified with `0.76.1` on Pi `1.1.0`; Pi `0.87.1`, the declared minimum, is not
+verified for the reader. Since `0.19.0`,
 the reader also accepts the exact `@gotgenes/pi-permission-system` `33.0.3` runtime that a host adds for
 permission rules; the host owns those rules, and the reader never reads or changes them. Delegation
 `off` suspends the layer.

package/SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Scope
 
-This project is a local Pi extension. It stores delegation policy data, model identifiers, and any configured per-role thinking policy in global defaults and session entries; it does not store the thinking level chosen for an individual run. ContextShunt is off by default. When explicitly enforced, it may keep a known successful text result in a private, session-only temporary file to serve bounded recovery; the file has an opaque ID, quota, cancellation check, and an absolute 30-minute TTL from creation. Cleanup is scheduled while the process is active and runs at shutdown, but crashes or OS suspension can delay deletion. It does not store credentials and makes no network request of its own; when one of its explicit tools asks an external executor to answer a bounded question, that executor performs the call. The reader accepts only the verified `pi-subagents` 0.76.1 launch contract; any other build fails closed before a request is sent. From `0.19.0`, the reader also admits the exact `@gotgenes/pi-permission-system` `33.0.3` runtime when the host adds it to the reader's child. The host owns its permission rules; the reader never reads or changes them, and an unverified permission entry fails closed. That runtime is trusted host code, not authority granted to the model. The check is an exact compatibility check, not a support guarantee. Versions `0.18.0` and earlier reject the extra runtime. From `0.20.0`, an enabled Advisor may be launched by the main agent with a forked context while the session fits in half of the Advisor model's window; the host then sends the conversation so far, including file contents and command output, to the Advisor's provider. Turn the Advisor off for sessions that must not reach that provider. The limits and privacy page of the wiki describes the details.
+This project is a local Pi extension. It stores delegation policy data, model identifiers, and any configured per-role thinking policy in global defaults and session entries; it does not store the thinking level chosen for an individual run. ContextShunt is off by default. When explicitly enforced, it may keep a known successful text result in a private, session-only temporary file to serve bounded recovery; the file has an opaque ID, quota, cancellation check, and an absolute 30-minute TTL from creation. Cleanup is scheduled while the process is active and runs at shutdown, but crashes or OS suspension can delay deletion. It does not store credentials and makes no network request of its own; when one of its explicit tools asks an external executor to answer a bounded question, that executor performs the call. The reader requires a stable `pi-subagents` SemVer version `>=0.76.1`, with no upper bound; older versions, prereleases and invalid versions fail closed before a request is sent. Every launch must still pass the strict contract checks; the version floor is not a guarantee of future-build compatibility. From `0.19.0`, the reader also admits the exact `@gotgenes/pi-permission-system` `33.0.3` runtime when the host adds it to the reader's child. The host owns its permission rules; the reader never reads or changes them, and an unverified permission entry fails closed. That runtime is trusted host code, not authority granted to the model. The check is an exact compatibility check, not a support guarantee. Versions `0.18.0` and earlier reject the extra runtime. From `0.20.0`, an enabled Advisor may be launched by the main agent with a forked context while the session fits in half of the Advisor model's window; the host then sends the conversation so far, including file contents and command output, to the Advisor's provider. Turn the Advisor off for sessions that must not reach that provider. The limits and privacy page of the wiki describes the details.
 
 ContextShunt is not a sandbox or a worker bridge. It preserves permissions and backends, does not inspect files before tool authorization, and leaves errors, structured/mixed results, images, binaries, invalid inputs, and unknown contracts unchanged. One-time exceptions are user-authorized, short-lived, bound to one call and immutable input snapshot, and capped by declared lines plus real returned UTF-8 bytes. The policy guides the main agent. It cannot guarantee that another system will follow a configured role or thinking choice. Review local configuration before using it.
 
@@ -15,8 +15,9 @@ 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 admitted only for the exact `pi-subagents`
-builds whose contract was verified (`0.76.1` and `0.83.1`), exact models/thinking, the packaged
+The tool requires stable `pi-subagents` SemVer `>=0.76.1`, with no upper bound, rejecting
+prereleases and invalid versions. It retains strict public preflight and terminal binding,
+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
@@ -68,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.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.23.1` 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.0",
+  "version": "0.23.1",
   "private": false,
   "description": "A Pi extension for configurable delegation intensity and exact subagent role model references.",
   "type": "module",

package/src/advisor-executor.ts

@@ -22,13 +22,6 @@ import {
   ANTHROPIC_ADVISOR_EXTENSION,
 } from "./advisor-anthropic-provider.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;
@@ -46,7 +39,6 @@ const DEFINITION: AgentLaunchDefinition<AdvisorRequest, string> = {
   agentPath: resolve(
     fileURLToPath(new URL("../agents/pi-delegation-policy.advisor.md", import.meta.url)),
   ),
-  admittedProtocolVersions: ADMITTED_SUBAGENTS_VERSIONS,
   allowFork: true,
   internalTools: [],
   buildTask: (request) =>

package/src/agent-launch.ts

@@ -16,6 +16,10 @@ const PACKAGE_MANIFEST_SEARCH_DEPTH = 3;
 /** `pi-subagents` 0.76.1 `src/api/preflight.ts` and `src/shared/launch-contract.ts`. */
 const LAUNCH_CONTRACT_VERSION = 3;
 const DEFINITION_PROJECTION_VERSION = 2;
+const MIN_SUBAGENTS_VERSION = [0n, 76n, 1n] as const;
+// Stable SemVer only: build metadata does not affect precedence; prereleases are not admitted.
+const STABLE_SEMVER =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 const SHA256_LOWER_HEX = /^[0-9a-f]{64}$/;
 const DIAGNOSTIC_SEVERITIES = new Set(["warning", "host-required"]);
 const DELEGATION_EVENTS = {
@@ -148,12 +152,6 @@ export type AgentLaunchDefinition<Request extends AgentLaunchRequest, Value> = R
   agentPath: string;
   /** Only the advisor may send a fork; reader requests remain fresh-only. */
   allowFork?: boolean;
-  /**
-   * 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
@@ -204,6 +202,19 @@ function exactStrings(value: unknown, expected: readonly string[]): boolean {
   );
 }
 
+function isSupportedSubagentsVersion(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  const match = STABLE_SEMVER.exec(value);
+  if (!match || match[0] !== value) return false;
+  for (const [index, minimum] of MIN_SUBAGENTS_VERSION.entries()) {
+    const digits = match[index + 1];
+    if (digits === undefined) return false;
+    const component = BigInt(digits);
+    if (component !== minimum) return component > minimum;
+  }
+  return true;
+}
+
 function isLowerHexDigest(value: unknown): value is string {
   return typeof value === "string" && SHA256_LOWER_HEX.test(value);
 }
@@ -422,8 +433,7 @@ function validateLaunchContract<Request extends AgentLaunchRequest, Value>(
       contract.version !== LAUNCH_CONTRACT_VERSION ||
       !isRecord(contract.protocol) ||
       contract.protocol.lifecycleArtifactVersion !== 3 ||
-      typeof contract.protocol.packageVersion !== "string" ||
-      !definition.admittedProtocolVersions.includes(contract.protocol.packageVersion) ||
+      !isSupportedSubagentsVersion(contract.protocol.packageVersion) ||
       contract.runId !== active.requestId ||
       !isLowerHexDigest(contract.digest)
     )

package/src/context-shunt-executor.ts

@@ -19,7 +19,6 @@ import type { SourceSnapshot } from "./context-shunt.ts";
 import type { ReaderAnswer, ReaderThinking } from "./context-shunt-reader.ts";
 
 export const CONTEXT_SHUNT_READER_AGENT_NAME = "pi-delegation-policy.context-shunt-inline-reader";
-export const CONTEXT_SHUNT_READER_PROTOCOL_VERSION = "0.76.1";
 export const READER_PREFLIGHT_TIMEOUT_MS = LAUNCH_PREFLIGHT_TIMEOUT_MS;
 export const READER_TERMINAL_TIMEOUT_MS = LAUNCH_TERMINAL_TIMEOUT_MS;
 
@@ -109,7 +108,6 @@ function isReaderAnswer(value: unknown): value is ReaderAnswer {
 const READER_LAUNCH = {
   agentName: CONTEXT_SHUNT_READER_AGENT_NAME,
   agentPath: CONTEXT_SHUNT_READER_AGENT_PATH,
-  admittedProtocolVersions: [CONTEXT_SHUNT_READER_PROTOCOL_VERSION],
   internalTools: ["structured_output"],
   buildTask: buildReaderTask,
   result: {