pi-delegation-policy 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 0.6.0 - 2026-08-29
+
+### Added
+
+- Allow Small, Medium, and Large to be explicitly disabled independently while requiring one enabled ordinary role for an active policy.
+- Add schema 3 defaults and session state, with in-memory schema 2 migration and guarded session writes for safer downgrade behavior. Downgrading after saving schema 3 defaults or manually editing them requires `/delegate off` in each active branch and manual conversion of ordinary `null` values.
+
+### Changed
+
+- Select only enabled ordinary roles that can satisfy the task, leaving work with the main agent when none can; Small/Medium preferences are inactive when either role is disabled.
+
+## 0.5.0 - 2026-08-28
+
+### Added
+
+- Expanded the optional visual specialist to create assets and complete bounded presentation-layer changes when behavior and data contracts are already defined.
+
+### Changed
+
+- Renamed the user-facing UI Design role to Visual Design while preserving the `uiDesign` configuration key and `ui-design` status token.
+- Clarified routing boundaries for application behavior, accessibility, checks, integration, and final acceptance.
+
 ## 0.4.1 - 2026-08-28
 
 ### Fixed

package/README.md

@@ -1,23 +1,27 @@
 # pi-delegation-policy
 
-A local Pi extension that helps the main agent decide **when delegation is worth it** and which exact models to use for the Small, Medium, Large, and optional UI Design roles. It provides guidance; it is not a subagent runner.
+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.4.1** is the latest published package. The package requires Pi `>=0.84.3`; Pi `0.84.3` is the explicitly checked baseline (newer versions are not claimed as tested).
+> **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.
 >
 > **Docs:** [Read the documentation site](https://yivas.github.io/pi-delegation-policy/).
 
 ## Value and boundary
 
-- Choose `off`, `normal`, or `aggressive` delegation intensity globally or for the current session branch.
-- Configure exact provider/model references for Small, Medium, Large, and optionally UI Design.
+- Choose `off`, `normal`, or `aggressive` 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.
 
-## Install and start
+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.
+
+The policy considers only enabled ordinary roles, chooses the least costly role that can satisfy the task's acceptance criteria and evidence, and keeps work with the main agent when none can. It never invents a model or role. `efficient` and `intensive` are tie-breaks only when both Small and Medium are enabled; otherwise their bias is inactive.
 
-Install the published package in Pi's user settings, then reload Pi:
+Visual Design is an independent optional specialist for direction, assets, bounded presentation-layer implementation, and visual review. Use it only when behavior and data contracts are already defined and unchanged, the affected surface is bounded, and visual quality or user experience is the primary acceptance criterion. It does not count as an ordinary role or replace one. Route business logic, data, APIs, routes, application architecture, tooling, interaction behavior, and cross-system integration to an enabled ordinary role by task fit. The main agent retains final integration and acceptance.
+
+## Install and start
 
 ```bash
 pi install npm:pi-delegation-policy
@@ -25,12 +29,14 @@ pi install npm:pi-delegation-policy
 ```
 
 1. Open `/delegate` (or press `Alt+G` in Pi's TUI).
-2. Configure exact, authenticated Small, Medium, and Large provider/model references. UI Design is optional.
+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**.
-4. Run `/delegate status` and inspect the exact role references and their sources. `D:ERR` means an active required role is invalid; no policy is injected.
-5. The applied state affects the **next** agent run. An agent already running is not rewritten.
+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.
 
-See the [end-to-end getting-started guide](https://yivas.github.io/pi-delegation-policy/getting-started/) and [configuration reference](https://yivas.github.io/pi-delegation-policy/configuration/) for details.
+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.
+
+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/).
 
 ## Essential commands
 
@@ -43,13 +49,7 @@ See the [end-to-end getting-started guide](https://yivas.github.io/pi-delegation
 /delegate reset                   Reset this branch to off and other fields to global defaults
 ```
 
-The editor is a bounded, keyboard-first panel. It shows model ID first and `[provider]` last, fuzzy-searches provider, model ID, and display name, and shows at most 10 model rows. It also shows a compact effective-policy preview, field explanations, and public model metadata when Pi supplies it. Changes are drafts until **Apply changes**; saving effective configuration as defaults updates the global file without applying the draft, and closing a modified draft requires explicit discard.
-
-## Configuration and safety
-
-Global defaults are stored at `~/.pi/agent/delegation-policy.json` (schema version 2). The file stores optional intensity, preference, exact role references, and an optional UI Design reference; it never stores thinking. A valid active mode requires exact, available, in-scope, authenticated Small, Medium, and Large references. Before every delegated launch, the policy requires the selected role's exact `provider/model` base and a thinking level chosen for that task instead of relying on ambient defaults. With `pi-subagents`, the main agent passes both as `model: "provider/model:LEVEL"`; other launchers may expose a separate per-run thinking field. Invalid active configuration fails closed as `D:ERR` with no policy injection; `off` is always `D:OFF`.
-
-The extension stores only policy settings and provider/model identifiers in local defaults and session entries. Review local configuration before sharing diagnostics, and remove credentials, prompts, personal paths, session files, and unredacted logs from reports. See the [limits and privacy reference](https://yivas.github.io/pi-delegation-policy/limits-and-privacy/) and [security policy](https://github.com/Yivas/pi-delegation-policy/blob/main/SECURITY.md).
+The editor is a bounded, keyboard-first panel. Every model selector pins **Use global default** and **Disable for this session** before searchable models. It shows model ID first and `[provider]` last, fuzzy-searches provider, model ID, and display name, and shows at most 10 model rows. It also shows a compact effective-policy preview, field explanations, and public model metadata when Pi supplies it. Changes are drafts until **Apply changes**; saving effective configuration as defaults updates only the global file without applying the draft, and closing a modified draft requires explicit discard.
 
 ## Development
 
@@ -63,8 +63,8 @@ npm run build
 npm run pack:check
 ```
 
-Tests use local mocks and do not make paid model calls or network requests. See [CONTRIBUTING.md](https://github.com/Yivas/pi-delegation-policy/blob/main/CONTRIBUTING.md) for contribution guidance.
+Tests use local mocks and do not make paid model calls or network requests. See [CONTRIBUTING.md](https://github.com/Yivas/pi-delegation-policy/blob/main/CONTRIBUTING.md).
 
 ## License
 
-MIT. See [LICENSE](https://github.com/Yivas/pi-delegation-policy/blob/main/LICENSE).
+MIT. See [LICENSE](LICENSE).

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

package/examples/global.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "intensity": "normal",
   "preference": "standard",
   "small": {
@@ -10,10 +10,7 @@
     "provider": "example-provider",
     "model": "example-medium"
   },
-  "large": {
-    "provider": "example-provider",
-    "model": "example-large"
-  },
+  "large": null,
   "uiDesign": {
     "provider": "example-provider",
     "model": "example-ui-design"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-delegation-policy",
-  "version": "0.4.1",
+  "version": "0.6.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

@@ -5,12 +5,12 @@
   "type": "object",
   "required": ["schemaVersion"],
   "properties": {
-    "schemaVersion": { "const": 2 },
+    "schemaVersion": { "const": 3 },
     "intensity": { "enum": ["off", "normal", "aggressive"] },
     "preference": { "enum": ["efficient", "standard", "intensive"] },
-    "small": { "$ref": "#/$defs/modelRef" },
-    "medium": { "$ref": "#/$defs/modelRef" },
-    "large": { "$ref": "#/$defs/modelRef" },
+    "small": { "$ref": "#/$defs/ordinaryRole" },
+    "medium": { "$ref": "#/$defs/ordinaryRole" },
+    "large": { "$ref": "#/$defs/ordinaryRole" },
     "uiDesign": { "$ref": "#/$defs/modelRef" }
   },
   "$defs": {
@@ -22,6 +22,9 @@
         "model": { "type": "string", "minLength": 1 }
       },
       "additionalProperties": false
+    },
+    "ordinaryRole": {
+      "anyOf": [{ "$ref": "#/$defs/modelRef" }, { "type": "null" }]
     }
   },
   "additionalProperties": false

package/src/config.ts

@@ -2,12 +2,15 @@ import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import {
+  CURRENT_SCHEMA_VERSION,
   emptyGlobalDefaults,
   emptySessionState,
   type EffectiveDelegateState,
   type GlobalDefaults,
   type Intensity,
   type ModelRef,
+  type ModelRole,
+  type OrdinaryRoleSetting,
   type Preference,
   type SessionDelegateState,
   type ValueSource,
@@ -19,11 +22,23 @@ 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.";
+  "Global defaults use schema version 1. Configure schema version 3 with /delegate before activating delegation.";
 const INVALID_CONFIG_MESSAGE = "Global defaults are invalid. Configure them again with /delegate.";
+const INVALID_SESSION_MESSAGE =
+  "The latest delegation session state is invalid or unsupported. Delegation is off for safety.";
+const CONFIG_KEYS = [
+  "schemaVersion",
+  "intensity",
+  "preference",
+  "small",
+  "medium",
+  "large",
+  "uiDesign",
+] as const;
 
 export type ConfigDiagnostic = {
   message: string;
+  reportWhenOff?: boolean;
 };
 
 export type LoadedDefaults = {
@@ -31,6 +46,26 @@ export type LoadedDefaults = {
   diagnostics: ConfigDiagnostic[];
 };
 
+export type RestoredSessionState = {
+  session: SessionDelegateState;
+  diagnostics: ConfigDiagnostic[];
+};
+
+export type SessionEntryWriter = { appendEntry: (type: string, data?: unknown) => void };
+export type GuardedAppendResult = "success" | "guard-failed" | "state-failed";
+
+type Schema2GlobalDefaults = {
+  schemaVersion: 2;
+  intensity?: Intensity;
+  preference?: Preference;
+  small?: ModelRef;
+  medium?: ModelRef;
+  large?: ModelRef;
+  uiDesign?: ModelRef;
+};
+
+type Schema2SessionState = Omit<Schema2GlobalDefaults, "uiDesign"> & { uiDesign?: ModelRef | null };
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -60,33 +95,27 @@ function parseModelRef(value: unknown): ModelRef | undefined {
   return { provider: value.provider, model: value.model };
 }
 
-function copyModelRef(value: ModelRef | undefined): ModelRef | undefined {
-  return value ? { ...value } : undefined;
+function copyRoleSetting(value: OrdinaryRoleSetting | undefined): OrdinaryRoleSetting | undefined {
+  return value === null ? null : value ? { ...value } : undefined;
 }
 
-export function parseConfig(value: unknown): GlobalDefaults | undefined {
-  if (
-    !isRecord(value) ||
-    !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;
+function hasValidEnvelope(value: unknown, schemaVersion: 2 | 3): value is Record<string, unknown> {
+  return (
+    isRecord(value) &&
+    hasOnlyKeys(value, CONFIG_KEYS) &&
+    value.schemaVersion === schemaVersion &&
+    (value.intensity === undefined || isIntensity(value.intensity)) &&
+    (value.preference === undefined || isPreference(value.preference))
+  );
+}
 
+function parseSchema2Roles(
+  value: Record<string, unknown>,
+): Pick<Schema2GlobalDefaults, "small" | "medium" | "large" | "uiDesign"> | 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) ||
@@ -94,11 +123,7 @@ export function parseConfig(value: unknown): GlobalDefaults | undefined {
     (value.uiDesign !== undefined && !uiDesign)
   )
     return undefined;
-
   return {
-    schemaVersion: 2,
-    ...(value.intensity ? { intensity: value.intensity } : {}),
-    ...(value.preference ? { preference: value.preference } : {}),
     ...(small ? { small } : {}),
     ...(medium ? { medium } : {}),
     ...(large ? { large } : {}),
@@ -106,51 +131,139 @@ export function parseConfig(value: unknown): GlobalDefaults | undefined {
   };
 }
 
-export function parseSessionState(value: unknown): SessionDelegateState | undefined {
+export function parseSchema2Config(value: unknown): Schema2GlobalDefaults | undefined {
+  if (!hasValidEnvelope(value, 2)) return undefined;
+  const roles = parseSchema2Roles(value);
+  if (!roles) return undefined;
+  return {
+    schemaVersion: 2,
+    ...(value.intensity ? { intensity: value.intensity as Intensity } : {}),
+    ...(value.preference ? { preference: value.preference as Preference } : {}),
+    ...roles,
+  };
+}
+
+export function parseSchema3Config(value: unknown): GlobalDefaults | undefined {
+  if (!hasValidEnvelope(value, CURRENT_SCHEMA_VERSION)) return undefined;
+  const parseOrdinary = (setting: unknown): OrdinaryRoleSetting | undefined =>
+    setting === null ? null : parseModelRef(setting);
+  const small = value.small === undefined ? undefined : parseOrdinary(value.small);
+  const medium = value.medium === undefined ? undefined : parseOrdinary(value.medium);
+  const large = value.large === undefined ? undefined : parseOrdinary(value.large);
+  const uiDesign = value.uiDesign === undefined ? undefined : parseModelRef(value.uiDesign);
   if (
-    !isRecord(value) ||
-    !hasOnlyKeys(value, [
-      "schemaVersion",
-      "intensity",
-      "preference",
-      "small",
-      "medium",
-      "large",
-      "uiDesign",
-    ]) ||
-    value.schemaVersion !== 2 ||
-    (value.intensity !== undefined && !isIntensity(value.intensity)) ||
-    (value.preference !== undefined && !isPreference(value.preference))
+    (value.small !== undefined && small === undefined) ||
+    (value.medium !== undefined && medium === undefined) ||
+    (value.large !== undefined && large === undefined) ||
+    (value.uiDesign !== undefined && !uiDesign)
   )
     return undefined;
+  return {
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    ...(value.intensity ? { intensity: value.intensity as Intensity } : {}),
+    ...(value.preference ? { preference: value.preference as Preference } : {}),
+    ...(small !== undefined ? { small } : {}),
+    ...(medium !== undefined ? { medium } : {}),
+    ...(large !== undefined ? { large } : {}),
+    ...(uiDesign ? { uiDesign } : {}),
+  };
+}
 
-  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);
+function migrateSchema2Config(value: Schema2GlobalDefaults): GlobalDefaults {
+  return {
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    ...(value.intensity ? { intensity: value.intensity as Intensity } : {}),
+    ...(value.preference ? { preference: value.preference as Preference } : {}),
+    ...(value.small ? { small: { ...value.small } } : {}),
+    ...(value.medium ? { medium: { ...value.medium } } : {}),
+    ...(value.large ? { large: { ...value.large } } : {}),
+    ...(value.uiDesign ? { uiDesign: { ...value.uiDesign } } : {}),
+  };
+}
+
+export function parseConfig(value: unknown): GlobalDefaults | undefined {
+  return (
+    parseSchema3Config(value) ??
+    (() => {
+      const schema2 = parseSchema2Config(value);
+      return schema2 ? migrateSchema2Config(schema2) : undefined;
+    })()
+  );
+}
+
+function parseSchema2SessionState(value: unknown): Schema2SessionState | undefined {
+  if (!hasValidEnvelope(value, 2)) return undefined;
   const uiDesign =
     value.uiDesign === undefined || value.uiDesign === null
       ? value.uiDesign
       : parseModelRef(value.uiDesign);
+  const roles = parseSchema2Roles({ ...value, uiDesign: undefined });
+  if (!roles || (value.uiDesign !== undefined && value.uiDesign !== null && !uiDesign))
+    return undefined;
+  return {
+    schemaVersion: 2,
+    ...(value.intensity ? { intensity: value.intensity as Intensity } : {}),
+    ...(value.preference ? { preference: value.preference as Preference } : {}),
+    ...roles,
+    ...(uiDesign === null ? { uiDesign: null } : uiDesign ? { uiDesign } : {}),
+  };
+}
 
+function parseSchema3SessionState(value: unknown): SessionDelegateState | undefined {
+  if (!hasValidEnvelope(value, CURRENT_SCHEMA_VERSION)) return undefined;
+  const parseOrdinary = (setting: unknown): OrdinaryRoleSetting | undefined =>
+    setting === null ? null : parseModelRef(setting);
+  const small = value.small === undefined ? undefined : parseOrdinary(value.small);
+  const medium = value.medium === undefined ? undefined : parseOrdinary(value.medium);
+  const large = value.large === undefined ? undefined : parseOrdinary(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.small !== undefined && small === undefined) ||
+    (value.medium !== undefined && medium === undefined) ||
+    (value.large !== undefined && large === undefined) ||
     (value.uiDesign !== undefined && value.uiDesign !== null && !uiDesign)
   )
     return undefined;
-
   return {
-    schemaVersion: 2,
-    ...(value.intensity ? { intensity: value.intensity } : {}),
-    ...(value.preference ? { preference: value.preference } : {}),
-    ...(small ? { small } : {}),
-    ...(medium ? { medium } : {}),
-    ...(large ? { large } : {}),
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    ...(value.intensity ? { intensity: value.intensity as Intensity } : {}),
+    ...(value.preference ? { preference: value.preference as Preference } : {}),
+    ...(small !== undefined ? { small } : {}),
+    ...(medium !== undefined ? { medium } : {}),
+    ...(large !== undefined ? { large } : {}),
     ...(uiDesign === null ? { uiDesign: null } : uiDesign ? { uiDesign } : {}),
   };
 }
 
+function migrateSchema2SessionState(value: Schema2SessionState): SessionDelegateState {
+  return {
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    ...(value.intensity ? { intensity: value.intensity as Intensity } : {}),
+    ...(value.preference ? { preference: value.preference as Preference } : {}),
+    ...(value.small ? { small: { ...value.small } } : {}),
+    ...(value.medium ? { medium: { ...value.medium } } : {}),
+    ...(value.large ? { large: { ...value.large } } : {}),
+    ...(value.uiDesign === null
+      ? { uiDesign: null }
+      : value.uiDesign
+        ? { uiDesign: { ...value.uiDesign } }
+        : {}),
+  };
+}
+
+export function parseSessionState(value: unknown): SessionDelegateState | undefined {
+  return (
+    parseSchema3SessionState(value) ??
+    (() => {
+      const schema2 = parseSchema2SessionState(value);
+      return schema2 ? migrateSchema2SessionState(schema2) : undefined;
+    })()
+  );
+}
+
 function isLegacyConfig(value: unknown): boolean {
   return isRecord(value) && value.schemaVersion === 1;
 }
@@ -195,64 +308,111 @@ async function atomicWrite(path: string, value: unknown): Promise<void> {
 }
 
 export async function writeConfig(path: string, defaults: GlobalDefaults): Promise<void> {
-  const parsed = parseConfig(defaults);
+  const parsed = parseSchema3Config(defaults);
   if (!parsed) throw new Error("Refusing to write invalid delegation policy defaults.");
   await atomicWrite(path, parsed);
 }
 
-export function restoreSessionState(entries: unknown[]): SessionDelegateState {
+export function restoreSessionStateWithDiagnostics(entries: unknown[]): RestoredSessionState {
   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;
+    const session = parseSessionState(entry.data);
+    if (session) return { session, diagnostics: [] };
+    return {
+      session: { schemaVersion: CURRENT_SCHEMA_VERSION, intensity: "off" },
+      diagnostics: [{ message: INVALID_SESSION_MESSAGE, reportWhenOff: true }],
+    };
   }
-  return emptySessionState();
+  return { session: emptySessionState(), diagnostics: [] };
 }
 
-function sourceFor<T>(sessionValue: T | undefined, globalValue: T | undefined): ValueSource {
-  if (sessionValue !== undefined) return "session";
+export function restoreSessionState(entries: unknown[]): SessionDelegateState {
+  return restoreSessionStateWithDiagnostics(entries).session;
+}
+
+function sourceFor<T>(
+  session: Record<string, unknown>,
+  globalValue: T | undefined,
+  key: string,
+): ValueSource {
+  if (Object.hasOwn(session, key)) return "session";
   if (globalValue !== undefined) return "global";
   return "default";
 }
 
+function resolveRole(
+  globalValue: OrdinaryRoleSetting | undefined,
+  session: SessionDelegateState,
+  role: ModelRole,
+): OrdinaryRoleSetting | undefined {
+  return copyRoleSetting(Object.hasOwn(session, role) ? session[role] : globalValue);
+}
+
 export function resolveDelegateState(
   defaults: GlobalDefaults,
   session: SessionDelegateState,
 ): EffectiveDelegateState {
   const uiDesign =
     session.uiDesign === undefined
-      ? copyModelRef(defaults.uiDesign)
+      ? defaults.uiDesign
+        ? { ...defaults.uiDesign }
+        : undefined
       : session.uiDesign === null
         ? undefined
-        : copyModelRef(session.uiDesign);
+        : { ...session.uiDesign };
+  const small = resolveRole(defaults.small, session, "small");
+  const medium = resolveRole(defaults.medium, session, "medium");
+  const large = resolveRole(defaults.large, session, "large");
 
   return {
     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),
+    ...(small !== undefined ? { small } : {}),
+    ...(medium !== undefined ? { medium } : {}),
+    ...(large !== undefined ? { large } : {}),
     ...(uiDesign ? { uiDesign } : {}),
     source: {
-      intensity: sourceFor(session.intensity, defaults.intensity),
-      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),
+      intensity: sourceFor(session, defaults.intensity, "intensity"),
+      preference: sourceFor(session, defaults.preference, "preference"),
+      small: sourceFor(session, defaults.small, "small"),
+      medium: sourceFor(session, defaults.medium, "medium"),
+      large: sourceFor(session, defaults.large, "large"),
+      uiDesign: sourceFor(session, defaults.uiDesign, "uiDesign"),
     },
   };
 }
 
 export function defaultsFromEffectiveState(state: EffectiveDelegateState): GlobalDefaults {
+  const role = (setting: OrdinaryRoleSetting | undefined) =>
+    setting === undefined ? {} : setting === null ? { value: null } : { value: { ...setting } };
+  const small = role(state.small);
+  const medium = role(state.medium);
+  const large = role(state.large);
   return {
-    schemaVersion: 2,
+    schemaVersion: CURRENT_SCHEMA_VERSION,
     intensity: state.intensity,
     preference: state.preference,
-    ...(state.small ? { small: { ...state.small } } : {}),
-    ...(state.medium ? { medium: { ...state.medium } } : {}),
-    ...(state.large ? { large: { ...state.large } } : {}),
+    ...("value" in small ? { small: small.value } : {}),
+    ...("value" in medium ? { medium: medium.value } : {}),
+    ...("value" in large ? { large: large.value } : {}),
     ...(state.uiDesign ? { uiDesign: { ...state.uiDesign } } : {}),
   };
 }
+
+export function appendGuardedSessionState(
+  pi: SessionEntryWriter,
+  session: SessionDelegateState,
+): GuardedAppendResult {
+  try {
+    pi.appendEntry(SESSION_ENTRY_TYPE, { schemaVersion: 2, intensity: "off" });
+  } catch {
+    return "guard-failed";
+  }
+  try {
+    pi.appendEntry(SESSION_ENTRY_TYPE, session);
+    return "success";
+  } catch {
+    return "state-failed";
+  }
+}

package/src/delegate-panel.ts

@@ -16,6 +16,7 @@ import { buildPolicyPreview } from "./prompt.ts";
 import {
   INTENSITIES,
   PREFERENCES,
+  CURRENT_SCHEMA_VERSION,
   type GlobalDefaults,
   type Intensity,
   type ModelConfigKey,
@@ -73,7 +74,7 @@ const FIELD_LABELS: Record<DelegateField, string> = {
   small: "Small model",
   medium: "Medium model",
   large: "Large model",
-  uiDesign: "UI Design",
+  uiDesign: "Visual Design",
 };
 
 const FIELD_DESCRIPTIONS: Record<DelegateField, string> = {
@@ -82,7 +83,7 @@ const FIELD_DESCRIPTIONS: Record<DelegateField, string> = {
   small: "Bounded, planned, and verifiable execution.",
   medium: "Planning, ambiguity, synthesis, and coordination.",
   large: "Exceptional unblocker for persistent hard problems.",
-  uiDesign: "Visual direction and review only; never implementation.",
+  uiDesign: "Design, assets, and bounded presentation work; no app behavior.",
 };
 
 const ACTION_LABELS: Record<PanelAction, string> = {
@@ -260,7 +261,7 @@ export class DelegatePanel implements Component, Focusable {
     const safeWidth = Math.max(1, width);
     this.renderWidth = safeWidth;
     const rows = Math.max(1, this.tui.terminal.rows);
-    if (safeWidth < 24 || rows < 9) return this.renderCompact(safeWidth, rows);
+    if (safeWidth < 26 || rows < 9) return this.renderCompact(safeWidth, rows);
 
     const title = this.renderTitle(safeWidth);
     const footer = this.renderFooter(safeWidth);
@@ -281,7 +282,7 @@ export class DelegatePanel implements Component, Focusable {
   }
 
   private isCompact(): boolean {
-    return this.renderWidth < 24 || this.tui.terminal.rows < 9;
+    return this.renderWidth < 26 || this.tui.terminal.rows < 9;
   }
 
   private handleCompactInput(data: string): void {
@@ -400,7 +401,7 @@ export class DelegatePanel implements Component, Focusable {
               ? effective.uiDesign
                 ? modelText(effective.uiDesign)
                 : "disabled"
-              : modelText(effective[field]);
+              : rawModelText(effective[field], "not configured");
         const details = this.sourceDetails(field);
         if (width < 48) {
           return [
@@ -473,7 +474,7 @@ export class DelegatePanel implements Component, Focusable {
       ];
     }
     return [
-      "built-in —",
+      "built-in not configured",
       `global ${rawModelText(this.global[field], "—")}`,
       `session ${rawModelText(this.draft[field], "inherit")}`,
     ];
@@ -522,7 +523,7 @@ export class DelegatePanel implements Component, Focusable {
     const [input = ""] = this.searchInput.render(inputWidth);
     const inputText = input.startsWith("> ") ? input.slice(2) : input;
     const choices = this.modelChoices(mode.field, mode.query);
-    const pinnedCount = mode.field === "uiDesign" ? 2 : 1;
+    const pinnedCount = 2;
     const pinned = choices.slice(0, pinnedCount);
     const models = choices.slice(pinnedCount);
     const pinnedLines = pinned.map((choice, index) =>
@@ -544,8 +545,9 @@ export class DelegatePanel implements Component, Focusable {
             ),
           )
         : [];
-    const fixedRows = 2 + pinnedLines.length + dividerRows;
-    const availableDetailRows = Math.max(0, budget - fixedRows - 1);
+    const fixedRows = 1 + pinnedLines.length + dividerRows;
+    const reservedModelRows = models.length > 0 && budget > fixedRows ? 1 : 0;
+    const availableDetailRows = Math.max(0, budget - fixedRows - reservedModelRows - 1);
     const details = metadata.slice(0, availableDetailRows);
     const detailRows = details.length > 0 ? details.length + 1 : 0;
     const availableListRows = Math.max(0, budget - fixedRows - detailRows);
@@ -577,7 +579,6 @@ export class DelegatePanel implements Component, Focusable {
     }
     return [
       truncateToWidth(`Search: ${inputText}`, width, ""),
-      "",
       ...pinnedLines,
       ...(dividerRows ? [this.theme.fg("borderMuted", "─".repeat(width))] : []),
       ...modelLines,
@@ -656,7 +657,8 @@ export class DelegatePanel implements Component, Focusable {
     }
     if (item === "apply") void this.applyDraft();
     else if (item === "save-defaults") void this.saveDefaults();
-    else if (item === "reset") this.draft = { schemaVersion: 2, intensity: "off" };
+    else if (item === "reset")
+      this.draft = { schemaVersion: CURRENT_SCHEMA_VERSION, intensity: "off" };
     else this.requestClose();
   }
 
@@ -730,24 +732,28 @@ export class DelegatePanel implements Component, Focusable {
     if (!choice || this.mode.kind !== "model") return;
     const field = this.mode.field;
     if (choice.kind === "global") delete this.draft[field];
-    else if (choice.kind === "disabled" && field === "uiDesign") this.draft.uiDesign = null;
+    else if (choice.kind === "disabled") this.draft[field] = null;
     else if (choice.kind === "model") this.draft[field] = { ...choice.reference };
     this.mode = { kind: "settings" };
   }
 
   private modelChoices(field: ModelConfigKey, query: string): ModelChoice[] {
     const global = this.global[field];
+    const globalDescription =
+      field === "uiDesign"
+        ? global
+          ? modelText(global)
+          : "disabled"
+        : rawModelText(global, "not configured");
     const pinned: ModelChoice[] = [
       {
         kind: "global",
         key: "global",
         label: USE_GLOBAL_DEFAULT,
-        ...(global ? { description: modelText(global) } : {}),
+        description: globalDescription,
       },
+      { kind: "disabled", key: "disabled", label: DISABLE_FOR_SESSION },
     ];
-    if (field === "uiDesign") {
-      pinned.push({ kind: "disabled", key: "disabled", label: DISABLE_FOR_SESSION });
-    }
     const filtered = query
       ? fuzzyFilter(this.candidates, query, (model) =>
           `${model.provider} ${model.provider}/${model.id} ${model.provider} ${model.id} ${model.name ?? ""}`.trim(),

package/src/index.ts

@@ -5,16 +5,16 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import type { AutocompleteItem } from "@earendil-works/pi-tui";
 import { buildDelegationPolicy } from "./prompt.ts";
+import { appendGuardedSessionState, type GuardedAppendResult } from "./config.ts";
 import {
   formatModelRef,
   hasRuntimeError,
   loadRuntime,
-  sessionEntry,
   statusLabel,
   type RuntimeState,
 } from "./runtime.ts";
 import { openDelegateEditor } from "./ui.ts";
-import { INTENSITIES, type Intensity } from "./types.ts";
+import { CURRENT_SCHEMA_VERSION, INTENSITIES, type Intensity } from "./types.ts";
 
 const STATUS_KEY = "pi-delegation-policy";
 
@@ -42,17 +42,13 @@ export function getArgumentCompletions(prefix: string): AutocompleteItem[] | nul
   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)));
 }
 
 async function openEditor(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
   await openDelegateEditor(ctx, pi);
-  updateStatus(ctx, await refresh(ctx));
+  updateStatus(ctx, await loadRuntime(ctx));
 }
 
 export function statusText(state: RuntimeState): string {
@@ -63,34 +59,56 @@ export function statusText(state: RuntimeState): string {
     `small=${formatModelRef(effective.small)} (${effective.source.small})`,
     `medium=${formatModelRef(effective.medium)} (${effective.source.medium})`,
     `large=${formatModelRef(effective.large)} (${effective.source.large})`,
-    `ui-design=${formatModelRef(effective.uiDesign)} (${effective.source.uiDesign})`,
+    `ui-design=${effective.uiDesign ? formatModelRef(effective.uiDesign) : "disabled"} (${effective.source.uiDesign})`,
   ];
 
-  if (effective.intensity !== "off" && state.runtimeErrors.length > 0) {
-    details.push(`details=${state.runtimeErrors.join("; ")}`);
-  }
+  const diagnosticMessages = state.diagnostics.map(({ message }) => message);
+  const errorDetails =
+    effective.intensity === "off"
+      ? state.diagnostics.filter(({ reportWhenOff }) => reportWhenOff).map(({ message }) => message)
+      : [
+          ...diagnosticMessages,
+          ...state.runtimeErrors.filter((message) => !diagnosticMessages.includes(message)),
+        ];
+  if (errorDetails.length > 0) details.push(`details=${errorDetails.join("; ")}`);
   return details.join(" | ");
 }
 
+function notifyAppendFailure(ctx: ExtensionCommandContext, result: GuardedAppendResult): void {
+  ctx.ui.notify(
+    result === "guard-failed"
+      ? "Could not save session settings. No change was applied."
+      : "Could not save session settings. Delegation is off for safety.",
+    "error",
+  );
+}
+
 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);
+  const state = await loadRuntime(ctx);
+  const session = { ...state.session, schemaVersion: CURRENT_SCHEMA_VERSION, intensity };
+  const result = appendGuardedSessionState(pi, session);
+  const updated = await loadRuntime(ctx);
   updateStatus(ctx, updated);
+  if (result !== "success") {
+    notifyAppendFailure(ctx, result);
+    return;
+  }
   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);
+  const session = { schemaVersion: CURRENT_SCHEMA_VERSION, intensity: "off" as const };
+  const result = appendGuardedSessionState(pi, session);
+  const updated = await loadRuntime(ctx);
   updateStatus(ctx, updated);
+  if (result !== "success") {
+    notifyAppendFailure(ctx, result);
+    return;
+  }
   ctx.ui.notify("Session delegation settings reset to off.", "info");
 }
 
@@ -105,7 +123,7 @@ export default function piDelegationPolicy(pi: ExtensionAPI): void {
         return;
       }
       if (action.kind === "status") {
-        const state = await refresh(ctx);
+        const state = await loadRuntime(ctx);
         updateStatus(ctx, state);
         ctx.ui.notify(statusText(state), hasRuntimeError(state) ? "error" : "info");
         return;
@@ -128,13 +146,13 @@ export default function piDelegationPolicy(pi: ExtensionAPI): void {
   });
 
   pi.on("session_start", async (_event, ctx) => {
-    updateStatus(ctx, await refresh(ctx));
+    updateStatus(ctx, await loadRuntime(ctx));
   });
   pi.on("session_tree", async (_event, ctx) => {
-    updateStatus(ctx, await refresh(ctx));
+    updateStatus(ctx, await loadRuntime(ctx));
   });
   pi.on("before_agent_start", async (event, ctx) => {
-    const state = await refresh(ctx);
+    const state = await loadRuntime(ctx);
     updateStatus(ctx, state);
     const policy = buildDelegationPolicy(state);
     return policy ? { systemPrompt: `${event.systemPrompt}\n\n${policy}` } : undefined;

package/src/prompt.ts

@@ -1,5 +1,10 @@
-import { hasRuntimeError, type RuntimeState } from "./runtime.ts";
-import type { EffectiveDelegateState, ModelRef, Preference } from "./types.ts";
+import {
+  enabledOrdinaryRoles,
+  hasRuntimeError,
+  isRoleDisabled,
+  type RuntimeState,
+} from "./runtime.ts";
+import type { EffectiveDelegateState, ModelRef, ModelRole, Preference } from "./types.ts";
 
 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.";
@@ -11,19 +16,36 @@ const ROLE_SELECTION_POLICY = `Choose the role by task fit before considering mo
 - difficulty: clarity, ambiguity, dependencies, competing hypotheses, and risk;
 - quantity: files, modules, systems, sources, and context volume;
 - error and review cost: what can go wrong, how costly it is to detect, and what evidence is needed.
-No single factor decides the role. Select the smallest role that can satisfy the acceptance criteria and evidence requirements.
+No single factor decides the role. First remove disabled roles, then discard enabled roles that cannot satisfy the acceptance criteria and evidence requirements. Select the least costly remaining role that can satisfy them. Keep the work with the main agent if no enabled role can satisfy them.
 
 Use Small for bounded, planned, and verifiable execution: 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 task fit materially requires planning, reducing meaningful ambiguity, broad synthesis, tracing several modules, comparing sources or options, coordinating substantial context, or making difficult decisions. 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.
+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.
 
-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.
+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.`;
 
-function preferenceGuidance(preference: Preference): string {
+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;
+2. product behavior and data contracts are already defined and remain unchanged;
+3. the patch is bounded to an identifiable surface, component, or set of assets;
+4. it requires no business logic, data flow, APIs, routes, application architecture, tooling, or cross-system coordination.
+
+When eligible, Visual Design may design, create, implement, and review scoped presentation code and visual assets, including layout, styles, responsive presentation, typography, images, icons, logos, SVGs, diagrams, and documentation visuals. It may address visual accessibility such as contrast and focus visibility. It must run and report the relevant existing checks for its patch.
+
+Route interaction behavior, state, validation, semantic HTML changes, keyboard mechanics, ARIA behavior, authentication, permissions, persistence, test infrastructure, and behavior-test ownership to an enabled ordinary role that fits, or keep it with the main agent. If any eligibility condition fails, use an enabled ordinary role or split the visual portion from the broader task. The main agent retains cross-domain integration and final acceptance.`;
+
+function hasSmallMedium(enabled: readonly ModelRole[]): boolean {
+  return enabled.includes("small") && enabled.includes("medium");
+}
+
+function preferenceGuidance(preference: Preference, enabled: readonly ModelRole[]): string {
+  if (!hasSmallMedium(enabled)) {
+    return `${preference} is inactive because Small or Medium is disabled.`;
+  }
   if (preference === "efficient") {
     return "Use efficient only as a Small tie-break when Small and Medium are comparably credible. Do not choose Small when Medium is a materially better task fit.";
   }
@@ -33,7 +55,8 @@ function preferenceGuidance(preference: Preference): string {
   return "Standard adds no Small or Medium bias; follow task fit.";
 }
 
-function preferencePreview(preference: Preference): string {
+function preferencePreview(preference: Preference, enabled: readonly ModelRole[]): string {
+  if (!hasSmallMedium(enabled)) return `${preference} inactive (Small or Medium disabled)`;
   if (preference === "efficient") return "efficient breaks comparable fits toward Small";
   if (preference === "intensive") return "intensive breaks comparable fits toward Medium";
   return "standard has no extra bias";
@@ -58,18 +81,43 @@ function formatThinkingLaunchModel(reference: ModelRef): string {
   return promptString(`${reference.provider}/${reference.model}:LEVEL`);
 }
 
+function roleName(role: ModelRole): string {
+  return role[0]!.toUpperCase() + role.slice(1);
+}
+
+function rolesByState(effective: EffectiveDelegateState): {
+  enabled: ModelRole[];
+  disabled: ModelRole[];
+  unconfigured: ModelRole[];
+} {
+  return {
+    enabled: enabledOrdinaryRoles(effective),
+    disabled: (["small", "medium", "large"] as const).filter((role) =>
+      isRoleDisabled(effective[role]),
+    ),
+    unconfigured: (["small", "medium", "large"] as const).filter(
+      (role) => effective[role] === undefined,
+    ),
+  };
+}
+
 export function buildPolicyPreview(effective: EffectiveDelegateState): string[] {
   if (effective.intensity === "off") return ["off · no policy injected"];
 
-  const { small, medium, large } = effective;
-  if (!small) return ["active · Small not configured · no policy can be injected"];
-  if (!medium) return ["active · Medium not configured · no policy can be injected"];
-  if (!large) return ["active · Large not configured · no policy can be injected"];
+  const { enabled, disabled, unconfigured } = rolesByState(effective);
+  if (unconfigured.length > 0) {
+    return [`active · ${roleName(unconfigured[0]!)} not configured · no policy can be injected`];
+  }
+  if (enabled.length === 0)
+    return ["active · no ordinary role enabled · no policy can be injected"];
 
+  const references = enabled
+    .map((role) => `${roleName(role)} ${formatLaunchModel(effective[role] as ModelRef)}`)
+    .join(" · ");
   return [
-    `${effective.intensity} · task fit first · ${preferencePreview(effective.preference)}`,
-    `Small ${formatLaunchModel(small)} · Medium ${formatLaunchModel(medium)} · Large ${formatLaunchModel(large)}`,
-    "Every launch must include the exact model plus per-task thinking; neither uses an ambient default.",
+    `${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.`,
   ];
 }
 
@@ -77,12 +125,19 @@ 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 { enabled, disabled } = rolesByState(effective);
+  if (enabled.length === 0) return undefined;
 
   const intensityPolicy = effective.intensity === "normal" ? NORMAL_POLICY : AGGRESSIVE_POLICY;
   const uiDesign = effective.uiDesign
-    ? `\n- UI Design: ${formatReference(effective.uiDesign)}; exact model base: ${formatLaunchModel(effective.uiDesign)}; pi-subagents form: ${formatThinkingLaunchModel(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.`
+    ? `\n- Visual Design: ${formatReference(effective.uiDesign)}; exact model base: ${formatLaunchModel(effective.uiDesign)}; pi-subagents form: ${formatThinkingLaunchModel(effective.uiDesign)}`
     : "";
+  const roleLines = enabled
+    .map((role) => {
+      const reference = effective[role] as ModelRef;
+      return `- ${roleName(role)}: ${formatReference(reference)}; exact model base: ${formatLaunchModel(reference)}; pi-subagents form: ${formatThinkingLaunchModel(reference)}`;
+    })
+    .join("\n");
 
   return `<delegation_policy>
 Intensity: ${effective.intensity}.
@@ -90,15 +145,15 @@ ${intensityPolicy}
 
 ${ROLE_SELECTION_POLICY}
 
-Model preference: ${effective.preference}. ${preferenceGuidance(effective.preference)}
+Enabled ordinary roles: ${enabled.map(roleName).join(", ")}.${disabled.length ? `\nDisabled ordinary roles: ${disabled.map(roleName).join(", ")}.` : ""}
 
-Before every delegated launch, name the selected role and take its exact combined provider/model base below. Choose thinking dynamically for that run from task demand, difficulty, quantity, risk, review cost, and the selected model's capabilities. Then transmit both through the launcher's per-run mechanism without changing the provider/model base. When the launcher encodes thinking as a model suffix, replace LEVEL in the shown pi-subagents form and pass model: "provider/model:LEVEL". Do not omit the model or thinking choice, inherit an ambient launcher default for either, substitute another model, persist the thinking level, or invent a fallback model or role or an unsupported thinking level.
+Model preference: ${effective.preference}. ${preferenceGuidance(effective.preference, enabled)}
 
-Roles:
-- Small: ${formatReference(effective.small)}; exact model base: ${formatLaunchModel(effective.small)}; pi-subagents form: ${formatThinkingLaunchModel(effective.small)}
-- Medium: ${formatReference(effective.medium)}; exact model base: ${formatLaunchModel(effective.medium)}; pi-subagents form: ${formatThinkingLaunchModel(effective.medium)}
-- Large: ${formatReference(effective.large)}; exact model base: ${formatLaunchModel(effective.large)}; pi-subagents form: ${formatThinkingLaunchModel(effective.large)}${uiDesign}
+Before every delegated launch, name the selected role and take its exact combined provider/model base below. Choose thinking dynamically for that run from task demand, difficulty, quantity, risk, review cost, and the selected model's capabilities. Then transmit both through the launcher's per-run mechanism without changing the provider/model base. When the launcher encodes thinking as a model suffix, replace LEVEL in the shown pi-subagents form and pass model: "provider/model:LEVEL". Do not omit the model or thinking choice, inherit an ambient launcher default for either, substitute an unlisted model, persist the thinking level, launch a disabled or unconfigured role, invent a role, or use an unsupported thinking level.
 
+Roles:
+${roleLines}${uiDesign}
+${effective.uiDesign ? `\n${VISUAL_DESIGN_POLICY}\n` : ""}
 This is guidance for the main agent. It does not create, execute, route, supervise, or enforce delegated work.
 </delegation_policy>`;
 }

package/src/runtime.ts

@@ -3,9 +3,8 @@ import type { Api, Model } from "@earendil-works/pi-ai";
 import {
   getGlobalConfigPath,
   readConfig,
-  SESSION_ENTRY_TYPE,
   resolveDelegateState,
-  restoreSessionState,
+  restoreSessionStateWithDiagnostics,
   type ConfigDiagnostic,
 } from "./config.ts";
 import {
@@ -17,6 +16,7 @@ import {
   type ModelRef,
   type ModelRole,
   type ModelStatus,
+  type OrdinaryRoleSetting,
   type SessionDelegateState,
 } from "./types.ts";
 
@@ -29,6 +29,18 @@ export type RuntimeState = {
   runtimeErrors: string[];
 };
 
+export function isRoleEnabled(setting: OrdinaryRoleSetting | undefined): setting is ModelRef {
+  return setting !== undefined && setting !== null;
+}
+
+export function isRoleDisabled(setting: OrdinaryRoleSetting | undefined): setting is null {
+  return setting === null;
+}
+
+export function enabledOrdinaryRoles(effective: EffectiveDelegateState): ModelRole[] {
+  return MODEL_ROLES.filter((role) => isRoleEnabled(effective[role]));
+}
+
 function matchesReference(model: Model<Api>, reference: ModelRef): boolean {
   return model.provider === reference.provider && model.id === reference.model;
 }
@@ -88,17 +100,12 @@ function statusDetail(status: ModelStatus): string {
   }
 }
 
-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;
-  }
-
+function validateEnabledRole(
+  ctx: ExtensionContext,
+  state: RuntimeState,
+  role: ModelConfigKey,
+  reference: ModelRef,
+): void {
   const status = validateModelReference(ctx, reference);
   state.modelStatuses.set(role, status);
   if (status.kind !== "available") {
@@ -108,12 +115,12 @@ function validateRole(ctx: ExtensionContext, state: RuntimeState, role: ModelCon
 
 export async function loadRuntime(ctx: ExtensionContext): Promise<RuntimeState> {
   const loaded = await readConfig(getGlobalConfigPath());
-  const session = restoreSessionState(ctx.sessionManager.getBranch());
+  const restored = restoreSessionStateWithDiagnostics(ctx.sessionManager.getBranch());
   const state: RuntimeState = {
-    effective: resolveDelegateState(loaded.defaults, session),
+    effective: resolveDelegateState(loaded.defaults, restored.session),
     global: loaded.defaults,
-    session,
-    diagnostics: loaded.diagnostics,
+    session: restored.session,
+    diagnostics: [...loaded.diagnostics, ...restored.diagnostics],
     modelStatuses: new Map(),
     runtimeErrors: [],
   };
@@ -129,8 +136,21 @@ export function validateRuntime(ctx: ExtensionContext, state: RuntimeState): voi
   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");
+  for (const role of MODEL_ROLES) {
+    const setting = state.effective[role];
+    if (setting === undefined) {
+      state.runtimeErrors.push(
+        `${ROLE_LABELS[role]} model is not configured; configure it or explicitly disable it.`,
+      );
+    } else if (isRoleEnabled(setting)) {
+      validateEnabledRole(ctx, state, role, setting);
+    }
+  }
+  if (enabledOrdinaryRoles(state.effective).length === 0) {
+    state.runtimeErrors.push("At least one ordinary role must be enabled.");
+  }
+  if (state.effective.uiDesign)
+    validateEnabledRole(ctx, state, "uiDesign", state.effective.uiDesign);
 }
 
 export function hasRuntimeError(state: RuntimeState): boolean {
@@ -143,13 +163,7 @@ export function statusLabel(state: RuntimeState): string {
   return state.effective.intensity === "normal" ? "D:NORM" : "D:AGG";
 }
 
-export function formatModelRef(reference: ModelRef | undefined): string {
+export function formatModelRef(reference: ModelRef | null | undefined): string {
+  if (reference === null) return "disabled";
   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

@@ -1,5 +1,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 type Intensity = (typeof INTENSITIES)[number];
 
@@ -14,7 +16,7 @@ export const ROLE_LABELS: Record<ModelConfigKey, string> = {
   small: "Small",
   medium: "Medium",
   large: "Large",
-  uiDesign: "UI Design",
+  uiDesign: "Visual Design",
 };
 
 export type ModelRef = {
@@ -22,24 +24,27 @@ export type ModelRef = {
   model: string;
 };
 
+// Absent session properties inherit. Null explicitly disables an ordinary role.
+export type OrdinaryRoleSetting = ModelRef | null;
+
 export type GlobalDefaults = {
-  schemaVersion: 2;
+  schemaVersion: typeof CURRENT_SCHEMA_VERSION;
   intensity?: Intensity;
   preference?: Preference;
-  small?: ModelRef;
-  medium?: ModelRef;
-  large?: ModelRef;
+  small?: OrdinaryRoleSetting;
+  medium?: OrdinaryRoleSetting;
+  large?: OrdinaryRoleSetting;
   uiDesign?: ModelRef;
 };
 
 export type SessionDelegateState = {
-  schemaVersion: 2;
+  schemaVersion: typeof CURRENT_SCHEMA_VERSION;
   intensity?: Intensity;
   preference?: Preference;
-  small?: ModelRef;
-  medium?: ModelRef;
-  large?: ModelRef;
-  // Null explicitly disables a global UI Design role for this session branch.
+  small?: OrdinaryRoleSetting;
+  medium?: OrdinaryRoleSetting;
+  large?: OrdinaryRoleSetting;
+  // Null explicitly disables a global Visual Design role for this session branch.
   uiDesign?: ModelRef | null;
 };
 
@@ -48,9 +53,9 @@ export type ValueSource = "default" | "global" | "session";
 export type EffectiveDelegateState = {
   intensity: Intensity;
   preference: Preference;
-  small?: ModelRef;
-  medium?: ModelRef;
-  large?: ModelRef;
+  small?: OrdinaryRoleSetting;
+  medium?: OrdinaryRoleSetting;
+  large?: OrdinaryRoleSetting;
   uiDesign?: ModelRef;
   source: {
     intensity: ValueSource;
@@ -70,9 +75,9 @@ export type ModelStatus =
   | { kind: "no-credentials" };
 
 export function emptyGlobalDefaults(): GlobalDefaults {
-  return { schemaVersion: 2 };
+  return { schemaVersion: CURRENT_SCHEMA_VERSION };
 }
 
 export function emptySessionState(): SessionDelegateState {
-  return { schemaVersion: 2 };
+  return { schemaVersion: CURRENT_SCHEMA_VERSION };
 }

package/src/ui.ts

@@ -1,12 +1,13 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
+  appendGuardedSessionState,
   defaultsFromEffectiveState,
   getGlobalConfigPath,
   resolveDelegateState,
   writeConfig,
 } from "./config.ts";
 import { DelegatePanel, type DelegatePanelResult } from "./delegate-panel.ts";
-import { hasRuntimeError, loadRuntime, modelCandidates, sessionEntry } from "./runtime.ts";
+import { hasRuntimeError, loadRuntime, modelCandidates } from "./runtime.ts";
 
 export async function openDelegateEditor(ctx: ExtensionContext, pi: ExtensionAPI): Promise<void> {
   if (!ctx.hasUI) return;
@@ -29,13 +30,23 @@ export async function openDelegateEditor(ctx: ExtensionContext, pi: ExtensionAPI
         global: state.global,
         session: state.session,
         candidates,
-        diagnostics: state.runtimeErrors,
+        diagnostics:
+          state.effective.intensity === "off"
+            ? state.diagnostics
+                .filter(({ reportWhenOff }) => reportWhenOff)
+                .map(({ message }) => message)
+            : [...state.runtimeErrors],
         hasRuntimeError: hasRuntimeError(state),
         onApply: async (draft) => {
-          const session = structuredClone(draft);
-          sessionEntry(pi, { ...state, session });
-          state.session = session;
-          return true;
+          const result = appendGuardedSessionState(pi, structuredClone(draft));
+          const refreshed = await loadRuntime(ctx);
+          state.global = refreshed.global;
+          state.session = refreshed.session;
+          state.diagnostics = refreshed.diagnostics;
+          state.effective = refreshed.effective;
+          state.modelStatuses = refreshed.modelStatuses;
+          state.runtimeErrors = refreshed.runtimeErrors;
+          return result === "success";
         },
         onSaveDefaults: async (draft) => {
           try {