pi-delegation-policy 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## 0.2.0 - 2026-08-26
+
+### Added
+
+- Added optional global intensity with session-branch overrides and a built-in `off` fallback.
+- Added **Use global default** to the intensity selector.
+
+### Fixed
+
+- Replaced the terminal-ambiguous `Ctrl+Shift+D` shortcut with `Ctrl+Alt+D`.
+
+## 0.1.2 - 2026-08-26
+
+### Fixed
+
+- Restored the canonical role-selection guidance for bounded execution, planning and ambiguity, repetitive volume, and exceptional blockers.
+- Made the `normal` and `aggressive` thresholds and the three Small/Medium preference biases operational at their boundaries.
+- Corrected session-branch guidance: a session without policy state starts at `off`, while a fork inherits the latest valid entry in its active history.
+
 ## 0.1.1 - 2026-08-26
 
 ### Added

package/README.md

@@ -2,14 +2,14 @@
 
 A local Pi extension that lets you choose delegation intensity and exact model references for Small, Medium, Large, and an optional UI Design role. It guides the main agent; it does not run, route, or enforce delegated work.
 
-> **Status:** Version 0.1.1 is available from npm. Every new session starts at `off`.
+> **Status:** Version 0.2.0 is available from npm.
 >
 > **Documentation:** Read the [documentation site](https://yivas.github.io/pi-delegation-policy/).
 
 ## What it does
 
-- Sets delegation intensity to `off`, `normal`, or `aggressive` for the current session branch.
-- Keeps global defaults for model references, preference, and the optional UI Design role.
+- Sets delegation intensity to `off`, `normal`, or `aggressive` globally or for the current session branch.
+- Keeps global defaults for intensity, model references, preference, and the optional UI Design role.
 - Stores session changes in Pi's session branch, so they survive reload, resume, and tree navigation.
 - Uses Pi's scoped models when configured, otherwise its available authenticated models.
 - Injects one policy block through Pi's public `before_agent_start` event when the active configuration is valid.
@@ -39,7 +39,9 @@ It supports Pi `0.84.1`. Restart Pi or run `/reload` after installation. To inst
 /delegate reset                   Reset this session branch to off
 ```
 
-`Ctrl+Shift+D` opens the selector when the shortcut is available. The footer shows `D:OFF`, `D:NORM`, `D:AGG`, or `D:ERR` without replacing Pi's own status.
+`Ctrl+Alt+D` opens the selector when the shortcut is available. There is no separate off shortcut; use `/delegate off` or choose `off` in the selector. Changes apply to the next agent run. An agent already running keeps the system prompt it started with.
+
+The footer shows `D:OFF`, `D:NORM`, `D:AGG`, or `D:ERR` without replacing Pi's own status.
 
 ## Configuration
 
@@ -49,11 +51,12 @@ Global defaults live at:
 ~/.pi/agent/delegation-policy.json
 ```
 
-They use schema version 2. The file stores model references, preference, and an optional UI Design model. It never stores intensity or thinking.
+They use schema version 2. The file stores optional intensity, model references, preference, and an optional UI Design model. It never stores thinking.
 
 ```json
 {
   "schemaVersion": 2,
+  "intensity": "normal",
   "preference": "standard",
   "small": {
     "provider": "example-provider",
@@ -80,35 +83,42 @@ Schema version 1 is inactive and is not migrated automatically. Open `/delegate`
 
 ### Global defaults and session branches
 
-A new session or branch always starts at `off`. It inherits global model references and preference until `/delegate` changes a field in that branch. Session fields override only their matching global values. Selecting **Save effective configuration as defaults** copies the current roles, preference, and UI Design setting to the global file without copying intensity.
+A session branch inherits global intensity, model references, preference, and UI Design until it records matching overrides. If global intensity is absent, the built-in default is `off`. A fork restores the latest valid delegation entry in its active history. The intensity selector can return a branch to **Use global default**.
 
-`/delegate reset` writes a session state with `off` and returns non-intensity fields to their global defaults.
+Selecting **Save effective configuration as defaults** copies the complete effective configuration, including intensity, to the global file. `/delegate reset` remains an explicit safety action: it writes a branch state with `off` and returns every other field to its global default.
 
 ### Intensity
 
-- `off` injects nothing. Invalid or incomplete defaults still show `D:OFF`.
-- `normal` delegates substantial, bounded, independent work when doing so saves effort without losing essential context.
-- `aggressive` favors delegating that work when its objective and acceptance criteria are clear.
+- `off` injects nothing into the next agent run. Pi rebuilds the system prompt for each run, so a policy injected into an earlier run is absent; an agent already running is not rewritten. Invalid or incomplete defaults still show `D:OFF`.
+- `normal` delegates substantial, separable work only when the expected benefit clearly outweighs briefing, supervision, review, and integration. It keeps borderline work with the main agent.
+- `aggressive` delegates substantial, separable, independently checkable work by default when it has a clear objective and acceptance criteria. A plausible benefit can be enough, but tightly coupled work or clearly prohibitive overhead stays with the main agent.
 
-The main agent keeps global decisions, coordination, integration, and final review in every mode.
+The main agent keeps global strategy, coordination, integration, final review, and work whose essential context is too costly or risky to transfer in every mode.
 
 ### Model roles and preference
 
 Active modes require exact `provider` and `model` references for Small, Medium, and Large. Pi must expose each reference in the current scope or available model catalog, and its provider must be authenticated. A missing, out-of-scope, unavailable, or unauthenticated role produces `D:ERR` and injects no policy. The extension never substitutes another model or role.
 
-The preference only changes the policy's selection bias:
+The policy chooses a role and thinking together from task demand, difficulty, and quantity. No single factor decides the role:
+
+- Small is habitual for bounded, planned, and verifiable execution. Difficult but well-defined work can remain Small with higher thinking.
+- Medium can be selected directly when the combined demands materially require planning, ambiguity reduction, broad synthesis, several-module tracing, comparison, context coordination, or difficult decisions. Small does not need to fail first.
+- Large is exceptional and only unblocks genuinely stuck work, such as persistent failures, severe framework conflicts, or contradictory hypotheses. Reliable prior evidence can justify it without ceremonial failed attempts.
+- Large quantities of repetitive, independent work favor multiple Small delegations. Agent type does not determine the model role.
+
+Preference shifts credible Small/Medium choices; a clearly better task fit overrides it:
 
-- `efficient` favors Small.
-- `standard` uses Small for routine work, Medium for planning, ambiguity, or broad synthesis, and Large for exceptional blockers.
-- `intensive` favors Medium.
+- `efficient` favors Small more strongly and uses Medium when it provides a material advantage.
+- `standard` reproduces the canonical policy and chooses Small on a genuine Small/Medium tie.
+- `intensive` normally favors Medium for non-trivial bounded work when both roles are credible, while retaining Small for clearly narrow, routine, mechanical, or especially clear Small work.
 
-All three ordinary roles remain available in every preference. The main agent chooses thinking for each delegated task from the task, difficulty, volume, and model capabilities. Thinking is not configured or persisted by this extension.
+All three ordinary roles remain available in every preference. The main agent chooses thinking for each delegated task from task demand, difficulty, quantity, and model capabilities. Thinking is not configured or persisted by this extension.
 
 UI Design is optional. When configured, it is limited to visual design direction, exploration, and review. It must not implement an interface, write code, or run tests. When it is off, ordinary roles handle design-related work.
 
 ## Security and privacy
 
-The extension stores provider and model identifiers in local configuration and session entries. It does not store credentials, send telemetry, or make network requests. Review configuration before using it and remove credentials, prompts, personal paths, session files, and unredacted logs from reports.
+The extension stores intensity, preference, and provider/model identifiers in local configuration and session entries. It does not store credentials, send telemetry, or make network requests. Review configuration before using it and remove credentials, prompts, personal paths, session files, and unredacted logs from reports.
 
 Read [`SECURITY.md`](SECURITY.md) for reporting guidance.
 

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.1.1 is the current supported release.
+Only the latest published version is supported. Version 0.2.0 is the current supported release.

package/examples/global.json

@@ -1,5 +1,6 @@
 {
   "schemaVersion": 2,
+  "intensity": "normal",
   "preference": "standard",
   "small": {
     "provider": "example-provider",

package/package.json

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

package/schema/delegation-policy.schema.json

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

package/src/config.ts

@@ -67,8 +67,17 @@ function copyModelRef(value: ModelRef | undefined): ModelRef | undefined {
 export function parseConfig(value: unknown): GlobalDefaults | undefined {
   if (
     !isRecord(value) ||
-    !hasOnlyKeys(value, ["schemaVersion", "preference", "small", "medium", "large", "uiDesign"]) ||
+    !hasOnlyKeys(value, [
+      "schemaVersion",
+      "intensity",
+      "preference",
+      "small",
+      "medium",
+      "large",
+      "uiDesign",
+    ]) ||
     value.schemaVersion !== 2 ||
+    (value.intensity !== undefined && !isIntensity(value.intensity)) ||
     (value.preference !== undefined && !isPreference(value.preference))
   )
     return undefined;
@@ -88,6 +97,7 @@ export function parseConfig(value: unknown): GlobalDefaults | undefined {
 
   return {
     schemaVersion: 2,
+    ...(value.intensity ? { intensity: value.intensity } : {}),
     ...(value.preference ? { preference: value.preference } : {}),
     ...(small ? { small } : {}),
     ...(medium ? { medium } : {}),
@@ -109,7 +119,7 @@ export function parseSessionState(value: unknown): SessionDelegateState | undefi
       "uiDesign",
     ]) ||
     value.schemaVersion !== 2 ||
-    !isIntensity(value.intensity) ||
+    (value.intensity !== undefined && !isIntensity(value.intensity)) ||
     (value.preference !== undefined && !isPreference(value.preference))
   )
     return undefined;
@@ -132,7 +142,7 @@ export function parseSessionState(value: unknown): SessionDelegateState | undefi
 
   return {
     schemaVersion: 2,
-    intensity: value.intensity,
+    ...(value.intensity ? { intensity: value.intensity } : {}),
     ...(value.preference ? { preference: value.preference } : {}),
     ...(small ? { small } : {}),
     ...(medium ? { medium } : {}),
@@ -218,14 +228,14 @@ export function resolveDelegateState(
         : copyModelRef(session.uiDesign);
 
   return {
-    intensity: session.intensity,
+    intensity: session.intensity ?? defaults.intensity ?? "off",
     preference: session.preference ?? defaults.preference ?? "standard",
     small: copyModelRef(session.small ?? defaults.small),
     medium: copyModelRef(session.medium ?? defaults.medium),
     large: copyModelRef(session.large ?? defaults.large),
     ...(uiDesign ? { uiDesign } : {}),
     source: {
-      intensity: "session",
+      intensity: sourceFor(session.intensity, defaults.intensity),
       preference: sourceFor(session.preference, defaults.preference),
       small: sourceFor(session.small, defaults.small),
       medium: sourceFor(session.medium, defaults.medium),
@@ -238,6 +248,7 @@ export function resolveDelegateState(
 export function defaultsFromEffectiveState(state: EffectiveDelegateState): GlobalDefaults {
   return {
     schemaVersion: 2,
+    intensity: state.intensity,
     preference: state.preference,
     ...(state.small ? { small: { ...state.small } } : {}),
     ...(state.medium ? { medium: { ...state.medium } } : {}),

package/src/index.ts

@@ -49,14 +49,19 @@ function updateStatus(ctx: ExtensionContext, state: RuntimeState): void {
   ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg("dim", statusLabel(state)));
 }
 
+async function openEditor(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+  await openDelegateEditor(ctx, pi);
+  updateStatus(ctx, await refresh(ctx));
+}
+
 function configuredLabel(value: unknown): string {
   return value ? "configured" : "unset";
 }
 
-function statusText(state: RuntimeState): string {
+export function statusText(state: RuntimeState): string {
   const { effective } = state;
   const details = [
-    `${statusLabel(state)} intensity=${effective.intensity}`,
+    `${statusLabel(state)} intensity=${effective.intensity} (${effective.source.intensity})`,
     `preference=${effective.preference} (${effective.source.preference})`,
     `small=${configuredLabel(effective.small)} (${effective.source.small})`,
     `medium=${configuredLabel(effective.medium)} (${effective.source.medium})`,
@@ -99,7 +104,7 @@ export default function piDelegationPolicy(pi: ExtensionAPI): void {
     handler: async (args, ctx) => {
       const action = parseCommand(args);
       if (action.kind === "open") {
-        await openDelegateEditor(ctx, pi);
+        await openEditor(pi, ctx);
         return;
       }
       if (action.kind === "status") {
@@ -120,9 +125,9 @@ export default function piDelegationPolicy(pi: ExtensionAPI): void {
     },
   });
 
-  pi.registerShortcut("ctrl+shift+d", {
+  pi.registerShortcut("ctrl+alt+d", {
     description: "Open delegation policy",
-    handler: async (ctx) => openDelegateEditor(ctx, pi),
+    handler: async (ctx) => openEditor(pi, ctx),
   });
 
   pi.on("session_start", async (_event, ctx) => {

package/src/prompt.ts

@@ -2,18 +2,34 @@ import { hasRuntimeError, type RuntimeState } from "./runtime.ts";
 import type { ModelRef, Preference } from "./types.ts";
 
 const NORMAL_POLICY =
-  "Delegate substantial, bounded, and independent work when doing so reduces effort without losing essential context. Keep architecture, global strategy, coordination, integration, final review, and work whose context is costly or risky to transfer in the main agent.";
+  "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 work with a clear objective and acceptance criteria. Keep global decisions, coordination, integration, final review, and work whose context is costly or risky to transfer in the main agent.";
+  "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 ROLE_SELECTION_POLICY = `Choose the role and thinking together from the combination of:
+- task demand: execute, search, plan, decide, or unblock;
+- difficulty: clarity, ambiguity, dependencies, risk, and competing hypotheses;
+- quantity: files, modules, systems, sources, and context volume.
+No single factor decides the role.
+
+Use Small habitually for bounded, planned, and verifiable work: concrete searches, scoped exploration, defined implementation, focused documentation, tests, reviews, mechanical changes, evident bugs, and bounded UI implementation whose design and stack are decided. Difficult but well-defined execution can remain Small with higher thinking.
+
+Use Medium directly when the combined demands materially require defining a plan, reducing meaningful ambiguity, broad synthesis, tracing several modules, comparing sources or options, coordinating substantial context, or making difficult decisions. These are evidence, not automatic triggers. Small does not need to fail first.
+
+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.
+
+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. A clearly better task fit overrides preference; preference only shifts credible Small/Medium choices.
+
+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.`;
 
 function preferenceGuidance(preference: Preference): string {
   if (preference === "efficient") {
-    return "Favor Small for routine delegated work. Medium and Large remain available when the task warrants them.";
+    return "Favor Small more strongly than standard. When Small can safely satisfy the acceptance criteria, choose it unless Medium provides a material advantage.";
   }
   if (preference === "intensive") {
-    return "Favor Medium for substantial delegated work. Small and Large remain available when the task warrants them.";
+    return "When Small and Medium are both credible, normally prefer Medium. Keep Small for work that is clearly narrow, routine, mechanical, or an especially clear Small fit.";
   }
-  return "Use Small for routine delegated work, Medium for planning, ambiguity, or broad synthesis, and Large only for exceptional blockers.";
+  return "Choose Small on a genuine Small/Medium tie; otherwise follow the role-selection policy above.";
 }
 
 function promptString(value: string): string {
@@ -42,9 +58,11 @@ export function buildDelegationPolicy(state: RuntimeState): string | undefined {
 Intensity: ${effective.intensity}.
 ${intensityPolicy}
 
+${ROLE_SELECTION_POLICY}
+
 Model preference: ${effective.preference}. ${preferenceGuidance(effective.preference)}
 
-Use the exact provider and model for the selected role. The references below use JSON string syntax; interpret escaped characters as JSON before use. Do not invent a fallback model or role. Choose thinking dynamically for each delegation from the task, difficulty, volume, and the selected model's capabilities. Do not treat thinking as persisted configuration.
+Use the exact provider and model for the selected role. The references below use JSON string syntax; interpret escaped characters as JSON before use. Do not invent a fallback model or role. Choose thinking dynamically for each delegation from task demand, difficulty, quantity, and the selected model's capabilities. Do not treat thinking as persisted configuration.
 
 Roles:
 - Small: ${formatReference(effective.small)}

package/src/types.ts

@@ -24,6 +24,7 @@ export type ModelRef = {
 
 export type GlobalDefaults = {
   schemaVersion: 2;
+  intensity?: Intensity;
   preference?: Preference;
   small?: ModelRef;
   medium?: ModelRef;
@@ -33,7 +34,7 @@ export type GlobalDefaults = {
 
 export type SessionDelegateState = {
   schemaVersion: 2;
-  intensity: Intensity;
+  intensity?: Intensity;
   preference?: Preference;
   small?: ModelRef;
   medium?: ModelRef;
@@ -52,7 +53,7 @@ export type EffectiveDelegateState = {
   large?: ModelRef;
   uiDesign?: ModelRef;
   source: {
-    intensity: "session";
+    intensity: ValueSource;
     preference: ValueSource;
     small: ValueSource;
     medium: ValueSource;
@@ -73,5 +74,5 @@ export function emptyGlobalDefaults(): GlobalDefaults {
 }
 
 export function emptySessionState(): SessionDelegateState {
-  return { schemaVersion: 2, intensity: "off" };
+  return { schemaVersion: 2 };
 }

package/src/ui.ts

@@ -13,7 +13,6 @@ import {
   type RuntimeState,
 } from "./runtime.ts";
 import {
-  emptySessionState,
   INTENSITIES,
   MODEL_ROLES,
   PREFERENCES,
@@ -109,8 +108,13 @@ async function selectUiDesign(ctx: ExtensionContext, draft: SessionDelegateState
 }
 
 async function selectIntensity(ctx: ExtensionContext, draft: SessionDelegateState): Promise<void> {
-  const selected = await selectOrCancel(ctx, "Delegation intensity", [...INTENSITIES]);
-  if (selected) draft.intensity = selected as Intensity;
+  const selected = await selectOrCancel(ctx, "Delegation intensity", [
+    USE_GLOBAL_DEFAULT,
+    ...INTENSITIES,
+  ]);
+  if (!selected) return;
+  if (selected === USE_GLOBAL_DEFAULT) delete draft.intensity;
+  else draft.intensity = selected as Intensity;
 }
 
 async function selectPreference(ctx: ExtensionContext, draft: SessionDelegateState): Promise<void> {
@@ -194,7 +198,7 @@ export async function openDelegateEditor(ctx: ExtensionContext, pi: ExtensionAPI
         await writeConfig(getGlobalConfigPath(), defaults);
         state.global = defaults;
         state.diagnostics = [];
-        ctx.ui.notify("Saved effective role settings as global defaults.", "info");
+        ctx.ui.notify("Saved effective delegation settings as global defaults.", "info");
       } catch {
         ctx.ui.notify(
           "Could not save global defaults. Session settings were not changed.",
@@ -203,7 +207,7 @@ export async function openDelegateEditor(ctx: ExtensionContext, pi: ExtensionAPI
       }
     }
     if (selected === RESET_SESSION) {
-      draft = emptySessionState();
+      draft = { schemaVersion: 2, intensity: "off" };
     }
   }
 }