pi-delegation-policy 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.7.0 - 2026-09-06
+
+### Added
+
+- Add the `orchestrator` intensity with `/delegate orchestrator` and `D:ORCH`. It delegates transferable research, detailed planning, implementation, testing, writing, review, and integration mechanics while keeping objectives, critical decisions, coordination, evidence, and final acceptance with the main agent.
+- Add orchestrator guidance for batching small work, concise briefs and results with file references, and avoiding duplicate inspection without a concrete gap or risk.
+
 ## 0.6.0 - 2026-08-29
 
 ### Added

package/README.md

@@ -2,18 +2,18 @@
 
 A local Pi extension that helps the main agent decide **when delegation is worth it** and which exact models to use for Small, Medium, Large, and optional Visual Design. It provides guidance; it is not a subagent runner.
 
-> **Status:** Version **0.6.0** is the latest published package. The package requires Pi `>=0.84.3`; Pi `0.84.3` is the explicitly checked baseline.
+> **Status:** Version **0.7.0** is the latest published package and supports `off`, `normal`, `aggressive`, and `orchestrator`. The package requires Pi `>=0.84.3`; Pi `0.84.3` is the explicitly checked baseline.
 >
 > **Docs:** [Read the documentation site](https://yivas.github.io/pi-delegation-policy/).
 
 ## Value and boundary
 
-- Choose `off`, `normal`, or `aggressive` globally or for the current session branch.
+- Choose `off`, `normal`, `aggressive`, or `orchestrator` globally or for the current session branch.
 - Configure an exact provider/model reference or explicitly disable each ordinary role.
 - Keep global defaults and session-branch overrides across reload, resume, and tree navigation.
 - Validate active configurations before injecting one policy block through Pi's public `before_agent_start` event.
 
-The extension guides the main agent. It never creates, launches, routes, supervises, or blocks subagents; changes Pi's main model or thinking; stores credentials; intercepts tools; or makes its own network requests. It has no model fallback, telemetry, project configuration, presets, or external skill loading.
+The extension guides the main agent. It never creates, launches, routes, supervises, or blocks subagents; changes Pi's main model or thinking; stores credentials; intercepts tools; or makes its own network requests. `orchestrator` delegates transferable execution detail and batches small work while the main agent retains objectives, critical decisions, coordination, integration responsibility, requested evidence, and final acceptance. It has no model fallback, telemetry, project configuration, presets, or external skill loading.
 
 A valid active policy requires an explicit decision for Small, Medium, and Large: an exact model reference or disabled. At least one ordinary role must remain enabled. A disabled role is not validated. An absent role, an invalid enabled reference, or no enabled ordinary role produces `D:ERR` and injects no policy. `off` always produces `D:OFF` without injection.
 
@@ -30,11 +30,13 @@ pi install npm:pi-delegation-policy
 
 1. Open `/delegate` (or press `Alt+G` in Pi's TUI).
 2. For Small, Medium, and Large, select an exact authenticated provider/model or **Disable for this session**. Keep at least one enabled.
-3. Select `normal` or `aggressive`, then choose **Apply changes**.
+3. Select `normal`, `aggressive`, or `orchestrator`, then choose **Apply changes**.
 4. Run `/delegate status`. `disabled`, `not configured`, and exact references remain distinct. `D:ERR` means no policy is injected.
 5. The applied state affects the **next** agent run.
 
-Global defaults are stored at `~/.pi/agent/delegation-policy.json` and use schema version 3. Schema 2 defaults and session entries are read and normalized in memory; they are not rewritten on read. Schema 3 stores `null` for an explicitly disabled ordinary role. Session changes write a schema 2 `off` guard before the schema 3 state so older versions restore off. Saving global defaults is global-only: before downgrading after that action or manually writing schema 3, run `/delegate off` in every active branch, restore schema 2 references manually, then install the older package.
+Global defaults are stored at `~/.pi/agent/delegation-policy.json` and use schema version 3. Schema 2 defaults and session entries are read and normalized in memory without rewriting them. Schema 3 stores `null` for an explicitly disabled ordinary role. Session changes write a schema 2 `off` guard before the schema 3 state; saving defaults changes only the global file.
+
+Before downgrading to `0.6.0`, change the global intensity to `off`, `normal`, or `aggressive` and run `/delegate off` in every active branch. For `<=0.5.0`, also convert global defaults to schema 2 and replace ordinary `null` values with exact model references. Schema 2 never accepts `orchestrator`. See the configuration reference for details.
 
 See the [getting-started guide](https://yivas.github.io/pi-delegation-policy/getting-started/) and [configuration reference](https://yivas.github.io/pi-delegation-policy/configuration/).
 
@@ -45,6 +47,7 @@ See the [getting-started guide](https://yivas.github.io/pi-delegation-policy/get
 /delegate off                     Disable policy for this session branch
 /delegate normal                  Enable balanced delegation guidance
 /delegate aggressive              Enable delegation-first guidance
+/delegate orchestrator             Minimize main-agent execution and narration
 /delegate status                  Show effective session state
 /delegate reset                   Reset this branch to off and other fields to global defaults
 ```

package/SECURITY.md

@@ -14,4 +14,4 @@ Include the affected version or commit, operating system, Pi version, reproducti
 
 ## Supported versions
 
-Only the latest published version is supported. Version 0.6.0 is the current supported release.
+Only the latest published version is supported. Version 0.7.0 is the current supported release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-delegation-policy",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "private": false,
   "description": "A Pi extension for configurable delegation intensity and exact subagent role model references.",
   "type": "module",
@@ -44,10 +44,10 @@
     "@earendil-works/pi-ai": "0.84.3",
     "@earendil-works/pi-coding-agent": "0.84.3",
     "@earendil-works/pi-tui": "0.84.3",
-    "@eslint/js": "^9.39.5",
-    "@types/node": "^22.0.0",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.2.0",
     "ajv": "^8.20.0",
-    "eslint": "^9.0.0",
+    "eslint": "^10.9.1",
     "prettier": "^3.0.0",
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.68.0"

package/schema/delegation-policy.schema.json

@@ -6,7 +6,7 @@
   "required": ["schemaVersion"],
   "properties": {
     "schemaVersion": { "const": 3 },
-    "intensity": { "enum": ["off", "normal", "aggressive"] },
+    "intensity": { "enum": ["off", "normal", "aggressive", "orchestrator"] },
     "preference": { "enum": ["efficient", "standard", "intensive"] },
     "small": { "$ref": "#/$defs/ordinaryRole" },
     "medium": { "$ref": "#/$defs/ordinaryRole" },

package/src/config.ts

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import {
   CURRENT_SCHEMA_VERSION,
+  INTENSITIES,
   emptyGlobalDefaults,
   emptySessionState,
   type EffectiveDelegateState,
@@ -56,7 +57,7 @@ export type GuardedAppendResult = "success" | "guard-failed" | "state-failed";
 
 type Schema2GlobalDefaults = {
   schemaVersion: 2;
-  intensity?: Intensity;
+  intensity?: LegacyIntensity;
   preference?: Preference;
   small?: ModelRef;
   medium?: ModelRef;
@@ -75,7 +76,14 @@ function hasOnlyKeys(value: Record<string, unknown>, allowedKeys: readonly strin
 }
 
 function isIntensity(value: unknown): value is Intensity {
-  return value === "off" || value === "normal" || value === "aggressive";
+  return INTENSITIES.some((intensity) => intensity === value);
+}
+
+const LEGACY_INTENSITIES = ["off", "normal", "aggressive"] as const;
+type LegacyIntensity = (typeof LEGACY_INTENSITIES)[number];
+
+function isLegacyIntensity(value: unknown): value is LegacyIntensity {
+  return LEGACY_INTENSITIES.some((intensity) => intensity === value);
 }
 
 function isPreference(value: unknown): value is Preference {
@@ -99,12 +107,16 @@ function copyRoleSetting(value: OrdinaryRoleSetting | undefined): OrdinaryRoleSe
   return value === null ? null : value ? { ...value } : undefined;
 }
 
-function hasValidEnvelope(value: unknown, schemaVersion: 2 | 3): value is Record<string, unknown> {
+function hasValidEnvelope(
+  value: unknown,
+  schemaVersion: 2 | 3,
+  intensityValidator: (value: unknown) => boolean = isIntensity,
+): value is Record<string, unknown> {
   return (
     isRecord(value) &&
     hasOnlyKeys(value, CONFIG_KEYS) &&
     value.schemaVersion === schemaVersion &&
-    (value.intensity === undefined || isIntensity(value.intensity)) &&
+    (value.intensity === undefined || intensityValidator(value.intensity)) &&
     (value.preference === undefined || isPreference(value.preference))
   );
 }
@@ -132,12 +144,14 @@ function parseSchema2Roles(
 }
 
 export function parseSchema2Config(value: unknown): Schema2GlobalDefaults | undefined {
-  if (!hasValidEnvelope(value, 2)) return undefined;
+  if (!hasValidEnvelope(value, 2, isLegacyIntensity)) return undefined;
+  const intensity = value.intensity;
+  if (intensity !== undefined && !isLegacyIntensity(intensity)) return undefined;
   const roles = parseSchema2Roles(value);
   if (!roles) return undefined;
   return {
     schemaVersion: 2,
-    ...(value.intensity ? { intensity: value.intensity as Intensity } : {}),
+    ...(intensity ? { intensity } : {}),
     ...(value.preference ? { preference: value.preference as Preference } : {}),
     ...roles,
   };
@@ -145,6 +159,8 @@ export function parseSchema2Config(value: unknown): Schema2GlobalDefaults | unde
 
 export function parseSchema3Config(value: unknown): GlobalDefaults | undefined {
   if (!hasValidEnvelope(value, CURRENT_SCHEMA_VERSION)) return undefined;
+  const intensity = value.intensity;
+  if (intensity !== undefined && !isIntensity(intensity)) return undefined;
   const parseOrdinary = (setting: unknown): OrdinaryRoleSetting | undefined =>
     setting === null ? null : parseModelRef(setting);
   const small = value.small === undefined ? undefined : parseOrdinary(value.small);
@@ -160,7 +176,7 @@ export function parseSchema3Config(value: unknown): GlobalDefaults | undefined {
     return undefined;
   return {
     schemaVersion: CURRENT_SCHEMA_VERSION,
-    ...(value.intensity ? { intensity: value.intensity as Intensity } : {}),
+    ...(intensity ? { intensity } : {}),
     ...(value.preference ? { preference: value.preference as Preference } : {}),
     ...(small !== undefined ? { small } : {}),
     ...(medium !== undefined ? { medium } : {}),
@@ -172,7 +188,7 @@ export function parseSchema3Config(value: unknown): GlobalDefaults | undefined {
 function migrateSchema2Config(value: Schema2GlobalDefaults): GlobalDefaults {
   return {
     schemaVersion: CURRENT_SCHEMA_VERSION,
-    ...(value.intensity ? { intensity: value.intensity as Intensity } : {}),
+    ...(value.intensity ? { intensity: value.intensity } : {}),
     ...(value.preference ? { preference: value.preference as Preference } : {}),
     ...(value.small ? { small: { ...value.small } } : {}),
     ...(value.medium ? { medium: { ...value.medium } } : {}),
@@ -192,7 +208,9 @@ export function parseConfig(value: unknown): GlobalDefaults | undefined {
 }
 
 function parseSchema2SessionState(value: unknown): Schema2SessionState | undefined {
-  if (!hasValidEnvelope(value, 2)) return undefined;
+  if (!hasValidEnvelope(value, 2, isLegacyIntensity)) return undefined;
+  const intensity = value.intensity;
+  if (intensity !== undefined && !isLegacyIntensity(intensity)) return undefined;
   const uiDesign =
     value.uiDesign === undefined || value.uiDesign === null
       ? value.uiDesign
@@ -202,7 +220,7 @@ function parseSchema2SessionState(value: unknown): Schema2SessionState | undefin
     return undefined;
   return {
     schemaVersion: 2,
-    ...(value.intensity ? { intensity: value.intensity as Intensity } : {}),
+    ...(intensity ? { intensity } : {}),
     ...(value.preference ? { preference: value.preference as Preference } : {}),
     ...roles,
     ...(uiDesign === null ? { uiDesign: null } : uiDesign ? { uiDesign } : {}),
@@ -211,6 +229,8 @@ function parseSchema2SessionState(value: unknown): Schema2SessionState | undefin
 
 function parseSchema3SessionState(value: unknown): SessionDelegateState | undefined {
   if (!hasValidEnvelope(value, CURRENT_SCHEMA_VERSION)) return undefined;
+  const intensity = value.intensity;
+  if (intensity !== undefined && !isIntensity(intensity)) return undefined;
   const parseOrdinary = (setting: unknown): OrdinaryRoleSetting | undefined =>
     setting === null ? null : parseModelRef(setting);
   const small = value.small === undefined ? undefined : parseOrdinary(value.small);
@@ -229,7 +249,7 @@ function parseSchema3SessionState(value: unknown): SessionDelegateState | undefi
     return undefined;
   return {
     schemaVersion: CURRENT_SCHEMA_VERSION,
-    ...(value.intensity ? { intensity: value.intensity as Intensity } : {}),
+    ...(intensity ? { intensity } : {}),
     ...(value.preference ? { preference: value.preference as Preference } : {}),
     ...(small !== undefined ? { small } : {}),
     ...(medium !== undefined ? { medium } : {}),
@@ -241,7 +261,7 @@ function parseSchema3SessionState(value: unknown): SessionDelegateState | undefi
 function migrateSchema2SessionState(value: Schema2SessionState): SessionDelegateState {
   return {
     schemaVersion: CURRENT_SCHEMA_VERSION,
-    ...(value.intensity ? { intensity: value.intensity as Intensity } : {}),
+    ...(value.intensity ? { intensity: value.intensity } : {}),
     ...(value.preference ? { preference: value.preference as Preference } : {}),
     ...(value.small ? { small: { ...value.small } } : {}),
     ...(value.medium ? { medium: { ...value.medium } } : {}),

package/src/delegate-panel.ts

@@ -445,7 +445,8 @@ export class DelegatePanel implements Component, Focusable {
       effective.intensity !== "off" && this.hasRuntimeError
         ? ["D:ERR · policy unavailable; fix the reported role diagnostics"]
         : buildPolicyPreview(effective);
-    const maximum = width >= 60 && budget >= 8 ? 4 : 2;
+    const maximum =
+      width >= 60 && budget >= 8 ? (effective.intensity === "orchestrator" ? 5 : 4) : 2;
     return ["Effective policy preview", ...lines]
       .slice(0, maximum)
       .map((line) => truncateToWidth(this.theme.fg("dim", line), width, ""));
@@ -492,6 +493,7 @@ export class DelegatePanel implements Component, Focusable {
             off: "No policy is injected.",
             normal: "Delegate when the expected benefit clearly outweighs overhead.",
             aggressive: "Delegate suitable substantial work by default.",
+            orchestrator: "Delegate transferable detail and keep ownership with the main agent.",
           }
         : {
             efficient: "Tie-break comparable fits toward Small.",

package/src/index.ts

@@ -136,7 +136,10 @@ export default function piDelegationPolicy(pi: ExtensionAPI): void {
         await setSessionIntensity(pi, ctx, action.intensity);
         return;
       }
-      ctx.ui.notify("Usage: /delegate, /delegate off|normal|aggressive|status|reset", "error");
+      ctx.ui.notify(
+        "Usage: /delegate, /delegate off|normal|aggressive|orchestrator|status|reset",
+        "error",
+      );
     },
   });
 

package/src/prompt.ts

@@ -10,6 +10,8 @@ const NORMAL_POLICY =
   "Delegate substantial, separable work only when the expected benefit clearly outweighs briefing, supervision, review, and integration cost. Count parallelism as a benefit only when valuable work can advance now or elapsed time matters. A merely possible fresh perspective is not enough by itself. Keep borderline work with the main agent.";
 const AGGRESSIVE_POLICY =
   "Default to delegating substantial, separable, independently checkable work with a clear objective and acceptance criteria. Delegate when the benefit is plausible even if not proven, including a useful independent perspective. Keep work with the main agent when it is poorly bounded, tightly coupled, dominated by integration or final accountability, or has clearly prohibitive delegation overhead.";
+const ORCHESTRATOR_POLICY =
+  "Minimize the main agent's execution and generated narration without surrendering ownership. Delegate research, detailed planning, implementation, testing, detailed writing, review, and integration mechanics when the work is transferable and a capable enabled role can satisfy the objective, acceptance, and evidence. Batch small independent work when doing so reduces launches and duplicated context, request minimal briefs and results with file references and evidence, and do not duplicate inspection unless there is a concrete gap, risk, or contradiction. Keep objectives, critical decisions, coordination, integration responsibility, requested detail, safety, and final acceptance with the main agent. Delegate detailed review and integration mechanics when transferable; final acceptance does not require the main agent to execute every detail. Keep narration and final text concise, but never omit risks, evidence, safety, or requested detail. Do not promise savings or force recursive fanout. Do work directly, regardless of size, when it is not transferable, no enabled role can satisfy it, or transfer and context costs exceed doing it here.";
 
 const ROLE_SELECTION_POLICY = `Choose the role by task fit before considering model preference:
 - demand: execute, search, plan, decide, coordinate, or unblock;
@@ -24,9 +26,12 @@ Use Medium directly when the combined task fit materially requires planning, red
 
 When Small and Medium are enabled alternatives, use Large only to unblock genuinely stuck work: persistent failures, severe framework conflicts, contradictory hypotheses, or reliable prior evidence that ordinary roles have not produced a trustworthy answer. Do not require ceremonial failed attempts. Large remains exceptional in a complete ordinary-role configuration.
 
-A more capable enabled role may cover work normally suited to a disabled role only when it can satisfy the same acceptance and evidence. Never choose a less capable role merely because it is the only enabled role. Large quantities of repetitive, independent work favor multiple Small delegations; volume alone does not justify Medium or Large. Agent type does not determine the model role. Apply preference only when Small and Medium are comparably credible fits. That tie-break applies only when both are enabled.
+A more capable enabled role may cover work normally suited to a disabled role only when it can satisfy the same acceptance and evidence. Never choose a less capable role merely because it is the only enabled role. Large quantities of repetitive, independent work favor multiple Small delegations; volume alone does not justify Medium or Large. Agent type does not determine the model role. Apply preference only when Small and Medium are comparably credible fits. That tie-break applies only when both are enabled.`;
 
-In every intensity, keep global strategy, coordination, integration, final review, and work whose essential context is too costly or risky to transfer with the main agent.`;
+const LEGACY_OWNERSHIP_POLICY =
+  "In every intensity, keep global strategy, coordination, integration, final review, and work whose essential context is too costly or risky to transfer with the main agent.";
+const ORCHESTRATOR_OWNERSHIP_POLICY =
+  "In orchestrator, keep global strategy, objectives, critical decisions, coordination, integration responsibility, requested evidence, safety, and final acceptance with the main agent. Detailed review and integration mechanics may be delegated when transferable; retaining final responsibility does not require executing every detail.";
 
 const VISUAL_DESIGN_POLICY = `Visual Design is an optional specialist role. Use it only when all four conditions hold:
 1. the primary acceptance criterion is a visual or user-experience result;
@@ -118,6 +123,9 @@ export function buildPolicyPreview(effective: EffectiveDelegateState): string[]
     `${effective.intensity} · task fit first · ${preferencePreview(effective.preference, enabled)}`,
     `Enabled: ${enabled.map(roleName).join(", ")}${disabled.length ? ` · Disabled: ${disabled.map(roleName).join(", ")}` : ""}`,
     `${references} · exact model plus per-task thinking required; neither uses an ambient default.`,
+    ...(effective.intensity === "orchestrator"
+      ? ["Batch transferable detail; main agent keeps ownership and final acceptance."]
+      : []),
   ];
 }
 
@@ -128,7 +136,16 @@ export function buildDelegationPolicy(state: RuntimeState): string | undefined {
   const { enabled, disabled } = rolesByState(effective);
   if (enabled.length === 0) return undefined;
 
-  const intensityPolicy = effective.intensity === "normal" ? NORMAL_POLICY : AGGRESSIVE_POLICY;
+  const intensityPolicy =
+    effective.intensity === "normal"
+      ? NORMAL_POLICY
+      : effective.intensity === "aggressive"
+        ? AGGRESSIVE_POLICY
+        : ORCHESTRATOR_POLICY;
+  const ownershipPolicy =
+    effective.intensity === "orchestrator"
+      ? ORCHESTRATOR_OWNERSHIP_POLICY
+      : LEGACY_OWNERSHIP_POLICY;
   const uiDesign = effective.uiDesign
     ? `\n- Visual Design: ${formatReference(effective.uiDesign)}; exact model base: ${formatLaunchModel(effective.uiDesign)}; pi-subagents form: ${formatThinkingLaunchModel(effective.uiDesign)}`
     : "";
@@ -145,6 +162,8 @@ ${intensityPolicy}
 
 ${ROLE_SELECTION_POLICY}
 
+${ownershipPolicy}
+
 Enabled ordinary roles: ${enabled.map(roleName).join(", ")}.${disabled.length ? `\nDisabled ordinary roles: ${disabled.map(roleName).join(", ")}.` : ""}
 
 Model preference: ${effective.preference}. ${preferenceGuidance(effective.preference, enabled)}

package/src/runtime.ts

@@ -160,7 +160,12 @@ export function hasRuntimeError(state: RuntimeState): boolean {
 export function statusLabel(state: RuntimeState): string {
   if (state.effective.intensity === "off") return "D:OFF";
   if (hasRuntimeError(state)) return "D:ERR";
-  return state.effective.intensity === "normal" ? "D:NORM" : "D:AGG";
+  const labels = {
+    normal: "D:NORM",
+    aggressive: "D:AGG",
+    orchestrator: "D:ORCH",
+  } as const;
+  return labels[state.effective.intensity];
 }
 
 export function formatModelRef(reference: ModelRef | null | undefined): string {

package/src/types.ts

@@ -2,7 +2,7 @@ import type { Api, Model } from "@earendil-works/pi-ai";
 
 export const CURRENT_SCHEMA_VERSION = 3 as const;
 
-export const INTENSITIES = ["off", "normal", "aggressive"] as const;
+export const INTENSITIES = ["off", "normal", "aggressive", "orchestrator"] as const;
 export type Intensity = (typeof INTENSITIES)[number];
 
 export const PREFERENCES = ["efficient", "standard", "intensive"] as const;

package/src/ui.ts

@@ -13,7 +13,7 @@ export async function openDelegateEditor(ctx: ExtensionContext, pi: ExtensionAPI
   if (!ctx.hasUI) return;
   if (ctx.mode !== "tui") {
     ctx.ui.notify(
-      "The delegation editor requires TUI mode. Use /delegate off, normal, aggressive, status, or reset here.",
+      "The delegation editor requires TUI mode. Use /delegate off, normal, aggressive, orchestrator, status, or reset here.",
       "warning",
     );
     return;