pi-delegation-policy 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 - 2026-08-25
+
+### Added
+
+- A keyboard-first `/delegate` selector for delegation intensity, model preference, exact Small, Medium, Large, and optional UI Design roles.
+- Global defaults and session-branch state that begin at `off` and survive reload, resume, and tree navigation.
+- Fail-closed validation for missing, unavailable, out-of-scope, or unauthenticated model roles.
+
+### Changed
+
+- Replaced the unpublished preset-based prototype with schema 2 global defaults and session-branch delegation state.
+- Removed project configuration, external skill loading, tool interception, enforcement, persisted thinking, and model fallbacks.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,24 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our standards
+
+Examples of behavior that contribute to a positive environment include:
+
+- showing empathy and kindness;
+- respecting differing opinions, viewpoints, and experiences;
+- accepting constructive criticism;
+- focusing on what is best for the community.
+
+Examples of unacceptable behavior include harassment, trolling, personal attacks, publishing private information without permission, and other conduct that would reasonably be considered inappropriate in a professional setting.
+
+## Enforcement
+
+Project maintainers may remove, edit, or reject comments, commits, code, issues, and other contributions that violate this Code of Conduct. They may temporarily or permanently restrict participation.
+
+Report abusive behavior through a private GitHub channel available to the repository maintainers. Do not use public issues for private reports.
+
+This project follows the Contributor Covenant, version 2.1: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

package/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Thanks for helping improve `pi-delegation-policy`.
+
+## Before opening an issue
+
+- Search existing issues.
+- Include the package version or commit, Pi version, operating system, and a minimal reproduction.
+- Remove credentials, session files, prompts, personal paths, model account identifiers, and unredacted logs.
+- Report security vulnerabilities through [`SECURITY.md`](SECURITY.md), not a public issue.
+
+## Pull requests
+
+Pull requests should:
+
+- explain the user-visible behavior and the reason for the change;
+- include focused tests for behavior changes;
+- keep the public package English-only;
+- use fictional examples and provider-agnostic documentation;
+- preserve exact role references and the absence of model fallbacks;
+- preserve the boundary: this package guides the main agent and does not create, launch, route, supervise, or block subagents;
+- avoid project configuration, credential handling, telemetry, and network requests;
+- run `npm run format:check`, `npm run lint`, `npm run typecheck`, `npm test`, and `npm run build`.
+
+Changes to schema 2, public commands, or the delegated-work policy need documentation and migration notes.
+
+## Code of conduct
+
+Participation follows [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yivas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# pi-delegation-policy
+
+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.0 is available from npm. Every new session starts at `off`.
+
+## 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.
+- 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.
+
+## What it does not do
+
+This package does not create, launch, route, supervise, or block subagents. It does not change Pi's main model or thinking level. It has no presets, project configuration, external skill loading, tool interception, model fallback, telemetry, credential storage, or network requests.
+
+## Install
+
+Install the package in your Pi user settings:
+
+```bash
+pi install npm:pi-delegation-policy
+```
+
+It supports Pi `0.84.1`. Restart Pi or run `/reload` after installation. To install a local checkout instead, use `pi install ./pi-delegation-policy`.
+
+## Commands
+
+```text
+/delegate                         Open the keyboard-first selector
+/delegate off                     Disable policy injection for this session branch
+/delegate normal                  Enable balanced delegation guidance
+/delegate aggressive              Enable delegation-first guidance
+/delegate status                  Show the effective session state
+/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.
+
+## Configuration
+
+Global defaults live at:
+
+```text
+~/.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.
+
+```json
+{
+  "schemaVersion": 2,
+  "preference": "standard",
+  "small": {
+    "provider": "example-provider",
+    "model": "example-small"
+  },
+  "medium": {
+    "provider": "example-provider",
+    "model": "example-medium"
+  },
+  "large": {
+    "provider": "example-provider",
+    "model": "example-large"
+  },
+  "uiDesign": {
+    "provider": "example-provider",
+    "model": "example-ui-design"
+  }
+}
+```
+
+See [`examples/global.json`](examples/global.json) and the bundled [JSON Schema](schema/delegation-policy.schema.json). The values are fictional.
+
+Schema version 1 is inactive and is not migrated automatically. Open `/delegate`, configure schema version 2, and save the effective configuration as defaults before using an active intensity.
+
+### 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.
+
+`/delegate reset` writes a session state with `off` and returns non-intensity fields to their global defaults.
+
+### 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.
+
+The main agent keeps global decisions, coordination, integration, and final review 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:
+
+- `efficient` favors Small.
+- `standard` uses Small for routine work, Medium for planning, ambiguity, or broad synthesis, and Large for exceptional blockers.
+- `intensive` favors Medium.
+
+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.
+
+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.
+
+Read [`SECURITY.md`](SECURITY.md) for reporting guidance.
+
+## Development
+
+```bash
+npm ci
+npm run format:check
+npm run lint
+npm run typecheck
+npm test
+npm run build
+npm run pack:check
+```
+
+The tests use local mocks and make no paid model calls or network requests.
+
+## Contributing
+
+Read [`CONTRIBUTING.md`](CONTRIBUTING.md). Contributions must preserve the boundary: this extension guides the main agent and does not become a subagent runner, tool interceptor, credential store, or telemetry client.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

package/SECURITY.md

@@ -0,0 +1,17 @@
+# Security Policy
+
+## Scope
+
+This project is a local Pi extension. It stores delegation policy data and model identifiers in global defaults and session entries. It does not store credentials, execute subagents, intercept tools, or make network requests.
+
+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.
+
+## Reporting
+
+Please use GitHub's private vulnerability reporting for this repository. Do not open a public issue for an undisclosed vulnerability. Remove credentials, session files, prompts, personal paths, and unredacted logs from reports.
+
+Include the affected version or commit, operating system, Pi version, reproduction steps, expected behavior, observed behavior, and a minimal sanitized configuration.
+
+## Supported versions
+
+Only the latest published version is supported. Version 0.1.0 is the first supported release.

package/examples/global.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 2,
+  "preference": "standard",
+  "small": {
+    "provider": "example-provider",
+    "model": "example-small"
+  },
+  "medium": {
+    "provider": "example-provider",
+    "model": "example-medium"
+  },
+  "large": {
+    "provider": "example-provider",
+    "model": "example-large"
+  },
+  "uiDesign": {
+    "provider": "example-provider",
+    "model": "example-ui-design"
+  }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "pi-delegation-policy",
+  "version": "0.1.0",
+  "private": false,
+  "description": "A Pi extension for configurable delegation intensity and exact subagent role model references.",
+  "type": "module",
+  "license": "MIT",
+  "repository": "https://github.com/Yivas/pi-delegation-policy",
+  "bugs": "https://github.com/Yivas/pi-delegation-policy/issues",
+  "homepage": "https://github.com/Yivas/pi-delegation-policy",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "delegation",
+    "subagents",
+    "model-selection"
+  ],
+  "files": [
+    "src",
+    "schema",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.84.1"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.84.1",
+    "@earendil-works/pi-coding-agent": "0.84.1",
+    "@earendil-works/pi-tui": "0.84.1",
+    "@eslint/js": "^9.39.5",
+    "@types/node": "^22.0.0",
+    "ajv": "^8.20.0",
+    "eslint": "^9.0.0",
+    "prettier": "^3.0.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.68.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/schema/delegation-policy.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Yivas/pi-delegation-policy/blob/main/schema/delegation-policy.schema.json",
+  "title": "Pi Delegation Policy global defaults",
+  "type": "object",
+  "required": ["schemaVersion"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "preference": { "enum": ["efficient", "standard", "intensive"] },
+    "small": { "$ref": "#/$defs/modelRef" },
+    "medium": { "$ref": "#/$defs/modelRef" },
+    "large": { "$ref": "#/$defs/modelRef" },
+    "uiDesign": { "$ref": "#/$defs/modelRef" }
+  },
+  "$defs": {
+    "modelRef": {
+      "type": "object",
+      "required": ["provider", "model"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1 },
+        "model": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/src/config.ts

@@ -0,0 +1,247 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import {
+  emptyGlobalDefaults,
+  emptySessionState,
+  type EffectiveDelegateState,
+  type GlobalDefaults,
+  type Intensity,
+  type ModelRef,
+  type Preference,
+  type SessionDelegateState,
+  type ValueSource,
+} from "./types.ts";
+
+export type { GlobalDefaults, SessionDelegateState } from "./types.ts";
+
+export const SESSION_ENTRY_TYPE = "pi-delegation-policy:session";
+export const GLOBAL_CONFIG_NAME = "delegation-policy.json";
+
+const LEGACY_SCHEMA_MESSAGE =
+  "Global defaults use schema version 1. Configure schema version 2 with /delegate before activating delegation.";
+const INVALID_CONFIG_MESSAGE = "Global defaults are invalid. Configure them again with /delegate.";
+
+export type ConfigDiagnostic = {
+  message: string;
+};
+
+export type LoadedDefaults = {
+  defaults: GlobalDefaults;
+  diagnostics: ConfigDiagnostic[];
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasOnlyKeys(value: Record<string, unknown>, allowedKeys: readonly string[]): boolean {
+  return Object.keys(value).every((key) => allowedKeys.includes(key));
+}
+
+function isIntensity(value: unknown): value is Intensity {
+  return value === "off" || value === "normal" || value === "aggressive";
+}
+
+function isPreference(value: unknown): value is Preference {
+  return value === "efficient" || value === "standard" || value === "intensive";
+}
+
+function parseModelRef(value: unknown): ModelRef | undefined {
+  if (
+    !isRecord(value) ||
+    !hasOnlyKeys(value, ["provider", "model"]) ||
+    typeof value.provider !== "string" ||
+    value.provider.length === 0 ||
+    typeof value.model !== "string" ||
+    value.model.length === 0
+  )
+    return undefined;
+  return { provider: value.provider, model: value.model };
+}
+
+function copyModelRef(value: ModelRef | undefined): ModelRef | undefined {
+  return value ? { ...value } : undefined;
+}
+
+export function parseConfig(value: unknown): GlobalDefaults | undefined {
+  if (
+    !isRecord(value) ||
+    !hasOnlyKeys(value, ["schemaVersion", "preference", "small", "medium", "large", "uiDesign"]) ||
+    value.schemaVersion !== 2 ||
+    (value.preference !== undefined && !isPreference(value.preference))
+  )
+    return undefined;
+
+  const small = value.small === undefined ? undefined : parseModelRef(value.small);
+  const medium = value.medium === undefined ? undefined : parseModelRef(value.medium);
+  const large = value.large === undefined ? undefined : parseModelRef(value.large);
+  const uiDesign = value.uiDesign === undefined ? undefined : parseModelRef(value.uiDesign);
+
+  if (
+    (value.small !== undefined && !small) ||
+    (value.medium !== undefined && !medium) ||
+    (value.large !== undefined && !large) ||
+    (value.uiDesign !== undefined && !uiDesign)
+  )
+    return undefined;
+
+  return {
+    schemaVersion: 2,
+    ...(value.preference ? { preference: value.preference } : {}),
+    ...(small ? { small } : {}),
+    ...(medium ? { medium } : {}),
+    ...(large ? { large } : {}),
+    ...(uiDesign ? { uiDesign } : {}),
+  };
+}
+
+export function parseSessionState(value: unknown): SessionDelegateState | undefined {
+  if (
+    !isRecord(value) ||
+    !hasOnlyKeys(value, [
+      "schemaVersion",
+      "intensity",
+      "preference",
+      "small",
+      "medium",
+      "large",
+      "uiDesign",
+    ]) ||
+    value.schemaVersion !== 2 ||
+    !isIntensity(value.intensity) ||
+    (value.preference !== undefined && !isPreference(value.preference))
+  )
+    return undefined;
+
+  const small = value.small === undefined ? undefined : parseModelRef(value.small);
+  const medium = value.medium === undefined ? undefined : parseModelRef(value.medium);
+  const large = value.large === undefined ? undefined : parseModelRef(value.large);
+  const uiDesign =
+    value.uiDesign === undefined || value.uiDesign === null
+      ? value.uiDesign
+      : parseModelRef(value.uiDesign);
+
+  if (
+    (value.small !== undefined && !small) ||
+    (value.medium !== undefined && !medium) ||
+    (value.large !== undefined && !large) ||
+    (value.uiDesign !== undefined && value.uiDesign !== null && !uiDesign)
+  )
+    return undefined;
+
+  return {
+    schemaVersion: 2,
+    intensity: value.intensity,
+    ...(value.preference ? { preference: value.preference } : {}),
+    ...(small ? { small } : {}),
+    ...(medium ? { medium } : {}),
+    ...(large ? { large } : {}),
+    ...(uiDesign === null ? { uiDesign: null } : uiDesign ? { uiDesign } : {}),
+  };
+}
+
+function isLegacyConfig(value: unknown): boolean {
+  return isRecord(value) && value.schemaVersion === 1;
+}
+
+export function getGlobalConfigPath(
+  agentDirectory = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"),
+): string {
+  return join(agentDirectory, GLOBAL_CONFIG_NAME);
+}
+
+export async function readConfig(path: string): Promise<LoadedDefaults> {
+  try {
+    const value = JSON.parse(await readFile(path, "utf8"));
+    const defaults = parseConfig(value);
+    if (defaults) return { defaults, diagnostics: [] };
+    return {
+      defaults: emptyGlobalDefaults(),
+      diagnostics: [
+        { message: isLegacyConfig(value) ? LEGACY_SCHEMA_MESSAGE : INVALID_CONFIG_MESSAGE },
+      ],
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { defaults: emptyGlobalDefaults(), diagnostics: [] };
+    }
+    return {
+      defaults: emptyGlobalDefaults(),
+      diagnostics: [{ message: INVALID_CONFIG_MESSAGE }],
+    };
+  }
+}
+
+async function atomicWrite(path: string, value: unknown): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    await rename(temporary, path);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+export async function writeConfig(path: string, defaults: GlobalDefaults): Promise<void> {
+  const parsed = parseConfig(defaults);
+  if (!parsed) throw new Error("Refusing to write invalid delegation policy defaults.");
+  await atomicWrite(path, parsed);
+}
+
+export function restoreSessionState(entries: unknown[]): SessionDelegateState {
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index] as Record<string, unknown> | undefined;
+    if (entry?.type !== "custom" || entry.customType !== SESSION_ENTRY_TYPE) continue;
+    const state = parseSessionState(entry.data);
+    if (state) return state;
+  }
+  return emptySessionState();
+}
+
+function sourceFor<T>(sessionValue: T | undefined, globalValue: T | undefined): ValueSource {
+  if (sessionValue !== undefined) return "session";
+  if (globalValue !== undefined) return "global";
+  return "default";
+}
+
+export function resolveDelegateState(
+  defaults: GlobalDefaults,
+  session: SessionDelegateState,
+): EffectiveDelegateState {
+  const uiDesign =
+    session.uiDesign === undefined
+      ? copyModelRef(defaults.uiDesign)
+      : session.uiDesign === null
+        ? undefined
+        : copyModelRef(session.uiDesign);
+
+  return {
+    intensity: session.intensity,
+    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",
+      preference: sourceFor(session.preference, defaults.preference),
+      small: sourceFor(session.small, defaults.small),
+      medium: sourceFor(session.medium, defaults.medium),
+      large: sourceFor(session.large, defaults.large),
+      uiDesign: sourceFor(session.uiDesign, defaults.uiDesign),
+    },
+  };
+}
+
+export function defaultsFromEffectiveState(state: EffectiveDelegateState): GlobalDefaults {
+  return {
+    schemaVersion: 2,
+    preference: state.preference,
+    ...(state.small ? { small: { ...state.small } } : {}),
+    ...(state.medium ? { medium: { ...state.medium } } : {}),
+    ...(state.large ? { large: { ...state.large } } : {}),
+    ...(state.uiDesign ? { uiDesign: { ...state.uiDesign } } : {}),
+  };
+}

package/src/index.ts

@@ -0,0 +1,143 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { buildDelegationPolicy } from "./prompt.ts";
+import {
+  hasRuntimeError,
+  loadRuntime,
+  sessionEntry,
+  statusLabel,
+  type RuntimeState,
+} from "./runtime.ts";
+import { openDelegateEditor } from "./ui.ts";
+import { INTENSITIES, type Intensity } from "./types.ts";
+
+const STATUS_KEY = "pi-delegation-policy";
+
+export type CommandAction =
+  | { kind: "open" }
+  | { kind: "intensity"; intensity: Intensity }
+  | { kind: "status" }
+  | { kind: "reset" }
+  | { kind: "invalid" };
+
+export function parseCommand(args: string): CommandAction {
+  const parts = args.trim().toLowerCase().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) return { kind: "open" };
+  if (parts[0] === "status" && parts.length === 1) return { kind: "status" };
+  if (parts[0] === "reset" && parts.length === 1) return { kind: "reset" };
+  if (parts.length === 1 && INTENSITIES.includes(parts[0] as Intensity)) {
+    return { kind: "intensity", intensity: parts[0] as Intensity };
+  }
+  return { kind: "invalid" };
+}
+
+export function getArgumentCompletions(prefix: string): AutocompleteItem[] | null {
+  const options = [...INTENSITIES, "status", "reset"];
+  const matches = options.filter((option) => option.startsWith(prefix.toLowerCase()));
+  return matches.length ? matches.map((value) => ({ value, label: value })) : null;
+}
+
+async function refresh(ctx: ExtensionContext): Promise<RuntimeState> {
+  return loadRuntime(ctx);
+}
+
+function updateStatus(ctx: ExtensionContext, state: RuntimeState): void {
+  ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg("dim", statusLabel(state)));
+}
+
+function configuredLabel(value: unknown): string {
+  return value ? "configured" : "unset";
+}
+
+function statusText(state: RuntimeState): string {
+  const { effective } = state;
+  const details = [
+    `${statusLabel(state)} intensity=${effective.intensity}`,
+    `preference=${effective.preference} (${effective.source.preference})`,
+    `small=${configuredLabel(effective.small)} (${effective.source.small})`,
+    `medium=${configuredLabel(effective.medium)} (${effective.source.medium})`,
+    `large=${configuredLabel(effective.large)} (${effective.source.large})`,
+    `ui-design=${configuredLabel(effective.uiDesign)} (${effective.source.uiDesign})`,
+  ];
+
+  if (effective.intensity !== "off" && state.runtimeErrors.length > 0) {
+    details.push(`details=${state.runtimeErrors.join("; ")}`);
+  }
+  return details.join(" | ");
+}
+
+async function setSessionIntensity(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  intensity: Intensity,
+): Promise<void> {
+  const state = await refresh(ctx);
+  state.session = { ...state.session, schemaVersion: 2, intensity };
+  sessionEntry(pi, state);
+  const updated = await refresh(ctx);
+  updateStatus(ctx, updated);
+  ctx.ui.notify(`Session delegation intensity: ${intensity}.`, "info");
+}
+
+async function resetSession(pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<void> {
+  const state = await refresh(ctx);
+  state.session = { schemaVersion: 2, intensity: "off" };
+  sessionEntry(pi, state);
+  const updated = await refresh(ctx);
+  updateStatus(ctx, updated);
+  ctx.ui.notify("Session delegation settings reset to off.", "info");
+}
+
+export default function piDelegationPolicy(pi: ExtensionAPI): void {
+  pi.registerCommand("delegate", {
+    description: "Configure delegation intensity and exact role model references",
+    getArgumentCompletions,
+    handler: async (args, ctx) => {
+      const action = parseCommand(args);
+      if (action.kind === "open") {
+        await openDelegateEditor(ctx, pi);
+        return;
+      }
+      if (action.kind === "status") {
+        const state = await refresh(ctx);
+        updateStatus(ctx, state);
+        ctx.ui.notify(statusText(state), hasRuntimeError(state) ? "error" : "info");
+        return;
+      }
+      if (action.kind === "reset") {
+        await resetSession(pi, ctx);
+        return;
+      }
+      if (action.kind === "intensity") {
+        await setSessionIntensity(pi, ctx, action.intensity);
+        return;
+      }
+      ctx.ui.notify("Usage: /delegate, /delegate off|normal|aggressive|status|reset", "error");
+    },
+  });
+
+  pi.registerShortcut("ctrl+shift+d", {
+    description: "Open delegation policy",
+    handler: async (ctx) => openDelegateEditor(ctx, pi),
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    updateStatus(ctx, await refresh(ctx));
+  });
+  pi.on("session_tree", async (_event, ctx) => {
+    updateStatus(ctx, await refresh(ctx));
+  });
+  pi.on("before_agent_start", async (event, ctx) => {
+    const state = await refresh(ctx);
+    updateStatus(ctx, state);
+    const policy = buildDelegationPolicy(state);
+    return policy ? { systemPrompt: `${event.systemPrompt}\n\n${policy}` } : undefined;
+  });
+  pi.on("session_shutdown", (_event, ctx) => {
+    ctx.ui.setStatus(STATUS_KEY, undefined);
+  });
+}

package/src/prompt.ts

@@ -0,0 +1,56 @@
+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.";
+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.";
+
+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.";
+  }
+  if (preference === "intensive") {
+    return "Favor Medium for substantial delegated work. Small and Large remain available when the task warrants them.";
+  }
+  return "Use Small for routine delegated work, Medium for planning, ambiguity, or broad synthesis, and Large only for exceptional blockers.";
+}
+
+function promptString(value: string): string {
+  return JSON.stringify(value)
+    .replaceAll("<", "\\u003c")
+    .replaceAll(">", "\\u003e")
+    .replaceAll("&", "\\u0026");
+}
+
+function formatReference(reference: ModelRef): string {
+  return `provider=${promptString(reference.provider)} model=${promptString(reference.model)}`;
+}
+
+export function buildDelegationPolicy(state: RuntimeState): string | undefined {
+  if (state.effective.intensity === "off" || hasRuntimeError(state)) return undefined;
+
+  const { effective } = state;
+  if (!effective.small || !effective.medium || !effective.large) return undefined;
+
+  const intensityPolicy = effective.intensity === "normal" ? NORMAL_POLICY : AGGRESSIVE_POLICY;
+  const uiDesign = effective.uiDesign
+    ? `\n- UI Design: ${formatReference(effective.uiDesign)}. Use this role only for visual design direction, exploration, or review. Never use it to implement an interface, write code, or run tests.`
+    : "";
+
+  return `<delegation_policy>
+Intensity: ${effective.intensity}.
+${intensityPolicy}
+
+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.
+
+Roles:
+- Small: ${formatReference(effective.small)}
+- Medium: ${formatReference(effective.medium)}
+- Large: ${formatReference(effective.large)}${uiDesign}
+
+This is guidance for the main agent. It does not create, execute, route, supervise, or enforce delegated work.
+</delegation_policy>`;
+}

package/src/runtime.ts

@@ -0,0 +1,155 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import {
+  getGlobalConfigPath,
+  readConfig,
+  SESSION_ENTRY_TYPE,
+  resolveDelegateState,
+  restoreSessionState,
+  type ConfigDiagnostic,
+} from "./config.ts";
+import {
+  MODEL_ROLES,
+  ROLE_LABELS,
+  type EffectiveDelegateState,
+  type GlobalDefaults,
+  type ModelConfigKey,
+  type ModelRef,
+  type ModelRole,
+  type ModelStatus,
+  type SessionDelegateState,
+} from "./types.ts";
+
+export type RuntimeState = {
+  effective: EffectiveDelegateState;
+  global: GlobalDefaults;
+  session: SessionDelegateState;
+  diagnostics: ConfigDiagnostic[];
+  modelStatuses: Map<ModelConfigKey, ModelStatus>;
+  runtimeErrors: string[];
+};
+
+function matchesReference(model: Model<Api>, reference: ModelRef): boolean {
+  return model.provider === reference.provider && model.id === reference.model;
+}
+
+function uniqueModels(models: readonly Model<Api>[]): Model<Api>[] {
+  const seen = new Set<string>();
+  return models.filter((model) => {
+    const key = `${model.provider}\u0000${model.id}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export function modelCandidates(ctx: ExtensionContext): Model<Api>[] {
+  const scopedModels = ctx.scopedModels ?? [];
+  const models = scopedModels.length
+    ? scopedModels.map(({ model }) => model)
+    : ctx.modelRegistry.getAvailable();
+  return uniqueModels(models).filter((model) => ctx.modelRegistry.hasConfiguredAuth(model));
+}
+
+export function validateModelReference(ctx: ExtensionContext, reference: ModelRef): ModelStatus {
+  const registered = ctx.modelRegistry.find(reference.provider, reference.model);
+  if (!registered) return { kind: "missing-model" };
+
+  const scopedModels = ctx.scopedModels ?? [];
+  if (scopedModels.length > 0) {
+    const scoped = scopedModels
+      .map(({ model }) => model)
+      .find((model) => matchesReference(model, reference));
+    if (!scoped) return { kind: "outside-scope" };
+    if (!ctx.modelRegistry.hasConfiguredAuth(scoped)) return { kind: "no-credentials" };
+    return { kind: "available", model: scoped };
+  }
+
+  const available = ctx.modelRegistry
+    .getAvailable()
+    .find((model) => matchesReference(model, reference));
+  if (!available) return { kind: "unavailable" };
+  if (!ctx.modelRegistry.hasConfiguredAuth(available)) return { kind: "no-credentials" };
+  return { kind: "available", model: available };
+}
+
+function statusDetail(status: ModelStatus): string {
+  switch (status.kind) {
+    case "missing-model":
+      return "is not registered in Pi";
+    case "outside-scope":
+      return "is outside the current model scope";
+    case "unavailable":
+      return "is not available";
+    case "no-credentials":
+      return "has no configured authentication";
+    case "available":
+      return "is available";
+  }
+}
+
+function referenceFor(state: RuntimeState, role: ModelRole): ModelRef | undefined {
+  return state.effective[role];
+}
+
+function validateRole(ctx: ExtensionContext, state: RuntimeState, role: ModelConfigKey): void {
+  const reference = role === "uiDesign" ? state.effective.uiDesign : referenceFor(state, role);
+  if (!reference) {
+    state.runtimeErrors.push(`${ROLE_LABELS[role]} model is not configured.`);
+    return;
+  }
+
+  const status = validateModelReference(ctx, reference);
+  state.modelStatuses.set(role, status);
+  if (status.kind !== "available") {
+    state.runtimeErrors.push(`${ROLE_LABELS[role]} model ${statusDetail(status)}.`);
+  }
+}
+
+export async function loadRuntime(ctx: ExtensionContext): Promise<RuntimeState> {
+  const loaded = await readConfig(getGlobalConfigPath());
+  const session = restoreSessionState(ctx.sessionManager.getBranch());
+  const state: RuntimeState = {
+    effective: resolveDelegateState(loaded.defaults, session),
+    global: loaded.defaults,
+    session,
+    diagnostics: loaded.diagnostics,
+    modelStatuses: new Map(),
+    runtimeErrors: [],
+  };
+  validateRuntime(ctx, state);
+  return state;
+}
+
+export function validateRuntime(ctx: ExtensionContext, state: RuntimeState): void {
+  state.effective = resolveDelegateState(state.global, state.session);
+  state.modelStatuses.clear();
+  state.runtimeErrors = [];
+
+  if (state.effective.intensity === "off") return;
+
+  for (const diagnostic of state.diagnostics) state.runtimeErrors.push(diagnostic.message);
+  for (const role of MODEL_ROLES) validateRole(ctx, state, role);
+  if (state.effective.uiDesign) validateRole(ctx, state, "uiDesign");
+}
+
+export function hasRuntimeError(state: RuntimeState): boolean {
+  return state.effective.intensity !== "off" && state.runtimeErrors.length > 0;
+}
+
+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";
+}
+
+export function formatModelRef(reference: ModelRef | undefined): string {
+  return reference ? `${reference.provider}/${reference.model}` : "not configured";
+}
+
+export function sessionEntry(
+  pi: { appendEntry: (type: string, data?: unknown) => void },
+  state: RuntimeState,
+): void {
+  pi.appendEntry(SESSION_ENTRY_TYPE, state.session);
+}

package/src/types.ts

@@ -0,0 +1,77 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+
+export const INTENSITIES = ["off", "normal", "aggressive"] as const;
+export type Intensity = (typeof INTENSITIES)[number];
+
+export const PREFERENCES = ["efficient", "standard", "intensive"] as const;
+export type Preference = (typeof PREFERENCES)[number];
+
+export const MODEL_ROLES = ["small", "medium", "large"] as const;
+export type ModelRole = (typeof MODEL_ROLES)[number];
+export type ModelConfigKey = ModelRole | "uiDesign";
+
+export const ROLE_LABELS: Record<ModelConfigKey, string> = {
+  small: "Small",
+  medium: "Medium",
+  large: "Large",
+  uiDesign: "UI Design",
+};
+
+export type ModelRef = {
+  provider: string;
+  model: string;
+};
+
+export type GlobalDefaults = {
+  schemaVersion: 2;
+  preference?: Preference;
+  small?: ModelRef;
+  medium?: ModelRef;
+  large?: ModelRef;
+  uiDesign?: ModelRef;
+};
+
+export type SessionDelegateState = {
+  schemaVersion: 2;
+  intensity: Intensity;
+  preference?: Preference;
+  small?: ModelRef;
+  medium?: ModelRef;
+  large?: ModelRef;
+  // Null explicitly disables a global UI Design role for this session branch.
+  uiDesign?: ModelRef | null;
+};
+
+export type ValueSource = "default" | "global" | "session";
+
+export type EffectiveDelegateState = {
+  intensity: Intensity;
+  preference: Preference;
+  small?: ModelRef;
+  medium?: ModelRef;
+  large?: ModelRef;
+  uiDesign?: ModelRef;
+  source: {
+    intensity: "session";
+    preference: ValueSource;
+    small: ValueSource;
+    medium: ValueSource;
+    large: ValueSource;
+    uiDesign: ValueSource;
+  };
+};
+
+export type ModelStatus =
+  | { kind: "available"; model: Model<Api> }
+  | { kind: "missing-model" }
+  | { kind: "outside-scope" }
+  | { kind: "unavailable" }
+  | { kind: "no-credentials" };
+
+export function emptyGlobalDefaults(): GlobalDefaults {
+  return { schemaVersion: 2 };
+}
+
+export function emptySessionState(): SessionDelegateState {
+  return { schemaVersion: 2, intensity: "off" };
+}

package/src/ui.ts

@@ -0,0 +1,209 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  defaultsFromEffectiveState,
+  getGlobalConfigPath,
+  resolveDelegateState,
+  writeConfig,
+} from "./config.ts";
+import {
+  formatModelRef,
+  loadRuntime,
+  modelCandidates,
+  sessionEntry,
+  type RuntimeState,
+} from "./runtime.ts";
+import {
+  emptySessionState,
+  INTENSITIES,
+  MODEL_ROLES,
+  PREFERENCES,
+  ROLE_LABELS,
+  type Intensity,
+  type ModelRef,
+  type ModelRole,
+  type Preference,
+  type SessionDelegateState,
+  type ValueSource,
+} from "./types.ts";
+
+const USE_GLOBAL_DEFAULT = "Use global default";
+const DISABLE_FOR_SESSION = "Disable for this session";
+const APPLY_TO_SESSION = "Apply changes to this session";
+const SAVE_AS_DEFAULTS = "Save effective configuration as defaults";
+const RESET_SESSION = "Reset session to off";
+const CANCEL = "Cancel";
+
+type ModelSelection =
+  { kind: "global" } | { kind: "disabled" } | { kind: "model"; reference: ModelRef } | undefined;
+
+function clone<T>(value: T): T {
+  return structuredClone(value);
+}
+
+function sourceLabel(source: ValueSource): string {
+  if (source === "session") return "session";
+  if (source === "global") return "global";
+  return "built-in";
+}
+
+function modelOption(reference: ModelRef): string {
+  return `${reference.provider}/${reference.model}`;
+}
+
+async function selectOrCancel(
+  ctx: ExtensionContext,
+  title: string,
+  options: string[],
+): Promise<string | undefined> {
+  if (!ctx.hasUI) return undefined;
+  return ctx.ui.select(title, options);
+}
+
+async function selectModel(
+  ctx: ExtensionContext,
+  title: string,
+  options: { includeDisable: boolean },
+): Promise<ModelSelection> {
+  const candidateOptions = new Map<string, ModelRef>();
+  for (const [index, model] of modelCandidates(ctx)
+    .sort((left, right) => {
+      const provider = left.provider.localeCompare(right.provider);
+      return provider === 0 ? left.id.localeCompare(right.id) : provider;
+    })
+    .entries()) {
+    const option = `${index + 1}. ${model.provider}/${model.id}${
+      model.name ? ` (${model.name})` : ""
+    }`;
+    candidateOptions.set(option, { provider: model.provider, model: model.id });
+  }
+
+  const selected = await selectOrCancel(ctx, title, [
+    USE_GLOBAL_DEFAULT,
+    ...(options.includeDisable ? [DISABLE_FOR_SESSION] : []),
+    ...candidateOptions.keys(),
+  ]);
+  if (!selected) return undefined;
+  if (selected === USE_GLOBAL_DEFAULT) return { kind: "global" };
+  if (selected === DISABLE_FOR_SESSION) return { kind: "disabled" };
+  const reference = candidateOptions.get(selected);
+  return reference ? { kind: "model", reference } : undefined;
+}
+
+async function selectRole(
+  ctx: ExtensionContext,
+  draft: SessionDelegateState,
+  role: ModelRole,
+): Promise<void> {
+  const selection = await selectModel(ctx, `${ROLE_LABELS[role]} model`, { includeDisable: false });
+  if (!selection) return;
+  if (selection.kind === "global") delete draft[role];
+  else if (selection.kind === "model") draft[role] = selection.reference;
+}
+
+async function selectUiDesign(ctx: ExtensionContext, draft: SessionDelegateState): Promise<void> {
+  const selection = await selectModel(ctx, "UI Design model", { includeDisable: true });
+  if (!selection) return;
+  if (selection.kind === "global") delete draft.uiDesign;
+  else if (selection.kind === "disabled") draft.uiDesign = null;
+  else draft.uiDesign = selection.reference;
+}
+
+async function selectIntensity(ctx: ExtensionContext, draft: SessionDelegateState): Promise<void> {
+  const selected = await selectOrCancel(ctx, "Delegation intensity", [...INTENSITIES]);
+  if (selected) draft.intensity = selected as Intensity;
+}
+
+async function selectPreference(ctx: ExtensionContext, draft: SessionDelegateState): Promise<void> {
+  const selected = await selectOrCancel(ctx, "Model preference", [
+    USE_GLOBAL_DEFAULT,
+    ...PREFERENCES,
+  ]);
+  if (!selected) return;
+  if (selected === USE_GLOBAL_DEFAULT) delete draft.preference;
+  else draft.preference = selected as Preference;
+}
+
+function menuOptions(state: RuntimeState, draft: SessionDelegateState): string[] {
+  const effective = resolveDelegateState(state.global, draft);
+  const options = [
+    `Intensity: ${effective.intensity} (${sourceLabel(effective.source.intensity)})`,
+    `Preference: ${effective.preference} (${sourceLabel(effective.source.preference)})`,
+    ...MODEL_ROLES.map(
+      (role) =>
+        `${ROLE_LABELS[role]}: ${formatModelRef(effective[role])} (${sourceLabel(
+          effective.source[role],
+        )})`,
+    ),
+    `UI Design: ${effective.uiDesign ? "on" : "off"} (${sourceLabel(effective.source.uiDesign)})`,
+  ];
+
+  if (effective.uiDesign) {
+    options.push(
+      `UI Design model: ${modelOption(effective.uiDesign)} (${sourceLabel(
+        effective.source.uiDesign,
+      )}; visual design only)`,
+    );
+  }
+
+  return [...options, APPLY_TO_SESSION, SAVE_AS_DEFAULTS, RESET_SESSION, CANCEL];
+}
+
+function startsWithOption(choice: string, name: string): boolean {
+  return choice.startsWith(`${name}:`);
+}
+
+export async function openDelegateEditor(ctx: ExtensionContext, pi: ExtensionAPI): Promise<void> {
+  if (!ctx.hasUI) return;
+
+  const state = await loadRuntime(ctx);
+  let draft = clone(state.session);
+
+  while (true) {
+    const effective = resolveDelegateState(state.global, draft);
+    const selected = await selectOrCancel(ctx, "Delegation policy", menuOptions(state, draft));
+    if (!selected || selected === CANCEL) return;
+
+    if (startsWithOption(selected, "Intensity")) {
+      await selectIntensity(ctx, draft);
+      continue;
+    }
+    if (startsWithOption(selected, "Preference")) {
+      await selectPreference(ctx, draft);
+      continue;
+    }
+    const role = MODEL_ROLES.find((candidate) =>
+      startsWithOption(selected, ROLE_LABELS[candidate]),
+    );
+    if (role) {
+      await selectRole(ctx, draft, role);
+      continue;
+    }
+    if (startsWithOption(selected, "UI Design model") || startsWithOption(selected, "UI Design")) {
+      await selectUiDesign(ctx, draft);
+      continue;
+    }
+    if (selected === APPLY_TO_SESSION) {
+      state.session = clone(draft);
+      sessionEntry(pi, state);
+      ctx.ui.notify("Saved delegation settings for this session branch.", "info");
+      return;
+    }
+    if (selected === SAVE_AS_DEFAULTS) {
+      try {
+        const defaults = defaultsFromEffectiveState(effective);
+        await writeConfig(getGlobalConfigPath(), defaults);
+        state.global = defaults;
+        state.diagnostics = [];
+        ctx.ui.notify("Saved effective role settings as global defaults.", "info");
+      } catch {
+        ctx.ui.notify(
+          "Could not save global defaults. Session settings were not changed.",
+          "error",
+        );
+      }
+    }
+    if (selected === RESET_SESSION) {
+      draft = emptySessionState();
+    }
+  }
+}