pi-pstack-adapter 0.8.0 → 0.9.0

package/src/config.ts

@@ -7,6 +7,21 @@ import { expandHome } from "./paths.ts";
 import { MAX_PANEL_ENTRIES, isPanelRole } from "./registry.ts";
 import { DEFAULT_DELEGATION, DELEGATION_PROVIDERS, isDelegationProvider } from "./delegation.ts";
 import type { DelegationProvider, SourceSelection, Trust } from "./types.ts";
+import { type ModelFilter, parseModelFilter } from "./filter.ts";
+
+/**
+ * A role's model. A list is a pool of alternatives for an ordinary role: each delegation picks one
+ * eligible entry. A panel role keeps its space-separated string, one seat per entry.
+ */
+export type ModelValue = string | readonly string[];
+
+/** A pool holds this many alternatives at most, like a panel's seat limit. */
+export const MAX_POOL_ENTRIES = 8;
+
+/** The entries of a role value, one for a plain string. */
+export function poolEntries(value: ModelValue): readonly string[] {
+  return typeof value === "string" ? [value] : value;
+}
 
 export interface AdapterConfig {
   readonly namespace: string;
@@ -19,7 +34,9 @@ export interface AdapterConfig {
   readonly pinnedCommit?: string;
   readonly allowBootstrap: boolean;
   readonly cacheDir?: string;
-  readonly models: Readonly<Record<string, string>>;
+  readonly models: Readonly<Record<string, ModelValue>>;
+  /** The saved model filter and the layer it came from. A later layer replaces it whole. */
+  readonly modelFilter?: { readonly filter: ModelFilter; readonly source: string };
   /** The delegation backend tried first. The other one is the fallback. */
   readonly delegation: DelegationProvider;
   readonly sources: readonly string[];
@@ -34,7 +51,8 @@ export interface ConfigFile {
   pinnedCommit?: string;
   allowBootstrap?: boolean;
   cacheDir?: string;
-  models?: Record<string, string>;
+  models?: Record<string, ModelValue>;
+  modelFilter?: ModelFilter;
   delegation?: string;
 }
 
@@ -304,9 +322,64 @@ function invalidModelMessage(model: unknown): string {
   return `Invalid model value ${typeof model === "string" ? `(${model.length} characters)` : safeEcho(model)}. Use provider/model or provider/model:thinking with no spaces or markup characters, at most 128 characters.`;
 }
 
-/** `role=provider/model[:thinking],role2=provider/model2` */
-export function parseModelRoles(value: string): Record<string, string> {
-  const roles: Record<string, string> = {};
+export type PoolAssignment =
+  | { readonly kind: "assign"; readonly value: ModelValue }
+  | { readonly kind: "rejected"; readonly message: string };
+
+/**
+ * Validates a `set_model` pool for an ordinary role. `thinking` applies to each entry without its own
+ * `:level`. Every entry must be a registry model; one bad entry rejects the whole pool. A pool of one
+ * is written as a plain string, the format older adapters read.
+ */
+export function planPoolAssignment(
+  entries: readonly string[],
+  thinking: string | undefined,
+  available: readonly AvailableModel[],
+): PoolAssignment {
+  const requested = thinking?.trim().toLowerCase() || undefined;
+  if (requested !== undefined && !isThinkingLevel(requested)) {
+    return {
+      kind: "rejected",
+      message: `Unknown thinking level \`${safeEcho(thinking).replaceAll('"', "")}\`. Use one of ${THINKING_LEVELS.map((level) => `\`${level}\``).join(", ")}.`,
+    };
+  }
+  const trimmed = entries.map((entry) => (typeof entry === "string" ? entry.trim() : entry));
+  if (trimmed.length === 0 || trimmed.length > MAX_POOL_ENTRIES) {
+    return { kind: "rejected", message: `A pool takes 1 to ${MAX_POOL_ENTRIES} models. Pass \`inherit\` as a plain string to clear the role.` };
+  }
+  const written: string[] = [];
+  for (const entry of trimmed) {
+    if (typeof entry !== "string" || entry === "") return { kind: "rejected", message: "A pool entry must be a non-empty `provider/model` string." };
+    if (entry.toLowerCase() === INHERIT_ENTRY) {
+      return { kind: "rejected", message: "A pool lists models only. To make the role inherit, pass `model: \"inherit\"` as a plain string." };
+    }
+    const own = available.some((candidate) => candidate.id === entry) ? undefined : splitModelSpec(entry).thinking;
+    const plan = planModelAssignment(entry, own === undefined ? thinking : undefined, available);
+    if (plan.kind === "rejected") return { kind: "rejected", message: `Entry \`${safeEcho(entry).replaceAll('"', "")}\`: ${plan.message}` };
+    if (plan.kind === "assign") written.push(joinModelSpec(plan.spec));
+  }
+  return { kind: "assign", value: written.length === 1 ? (written[0] as string) : written };
+}
+
+function isValidPoolValue(value: unknown): value is readonly string[] {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.length <= MAX_POOL_ENTRIES &&
+    value.every((entry) => typeof entry === "string" && entry.toLowerCase() !== INHERIT_ENTRY && isValidModelSpec(entry))
+  );
+}
+
+function invalidPoolMessage(value: readonly unknown[]): string {
+  return `Invalid pool (${value.length} entries). Use a list of 1 to ${MAX_POOL_ENTRIES} entries, each \`provider/model\` or \`provider/model:thinking\`, with no \`inherit\` entry.`;
+}
+
+/**
+ * `role=provider/model[:thinking],role2=provider/model2`. An ordinary role takes a pool as
+ * `role=a/x|b/y`; `|` never appears in a model id. A panel keeps space-separated seats.
+ */
+export function parseModelRoles(value: string): Record<string, ModelValue> {
+  const roles: Record<string, ModelValue> = {};
   for (const pair of value.split(",")) {
     const trimmed = pair.trim();
     if (trimmed === "") continue;
@@ -321,6 +394,11 @@ export function parseModelRoles(value: string): Record<string, string> {
     if (model === "") continue;
     if (isPanelRole(role)) {
       if (!isValidPanelValue(model)) throw new Error(`Role ${safeEcho(role)}. ${invalidPanelMessage(model)}`);
+    } else if (model.includes("|")) {
+      const pool = model.split("|").map((entry) => entry.trim());
+      if (!isValidPoolValue(pool)) throw new Error(`Role ${safeEcho(role)}. ${invalidPoolMessage(pool)}`);
+      roles[role] = pool;
+      continue;
     } else if (!isValidModelSpec(model)) {
       throw new Error(invalidModelMessage(model));
     }
@@ -352,6 +430,7 @@ export function environmentLayer(env: NodeJS.ProcessEnv): ConfigLayer {
 export function mergeConfig(layers: readonly ConfigLayer[]): AdapterConfig {
   const merged: ConfigFile = {};
   const sources: string[] = [];
+  let filterSource = "";
   for (const layer of layers) {
     let contributed = false;
     for (const [key, value] of Object.entries(layer.values)) {
@@ -368,6 +447,11 @@ export function mergeConfig(layers: readonly ConfigLayer[]): AdapterConfig {
       }
       if (key === "models") {
         merged.models = { ...merged.models, ...validatedModels(value, layer.label) };
+      } else if (key === "modelFilter") {
+        const parsed = parseModelFilter(value);
+        if ("problem" in parsed) throw new Error(`${layer.label}: ${parsed.problem} Edit \`modelFilter\` in that file, then restart Pi.`);
+        merged.modelFilter = parsed.filter;
+        filterSource = layer.label;
       } else {
         (merged as Record<string, unknown>)[key] = value;
       }
@@ -390,17 +474,18 @@ export function mergeConfig(layers: readonly ConfigLayer[]): AdapterConfig {
     allowBootstrap: merged.allowBootstrap ?? false,
     cacheDir: merged.cacheDir,
     models: merged.models ?? {},
+    modelFilter: merged.modelFilter ? { filter: merged.modelFilter, source: filterSource } : undefined,
     delegation: validateDelegation(merged.delegation, layers),
     sources,
   };
 }
 
 /** A bad `models` entry fails with the layer that holds it, so status can still be reached after a fix. */
-function validatedModels(value: unknown, label: string): Record<string, string> {
+function validatedModels(value: unknown, label: string): Record<string, ModelValue> {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     throw new Error(`${label} sets \`models\` to something other than an object of role to provider/model.`);
   }
-  const models: Record<string, string> = {};
+  const models: Record<string, ModelValue> = {};
   for (const [role, model] of Object.entries(value)) {
     if (!isValidRole(role)) {
       throw new Error(`${label}: ${invalidRoleMessage(role)} Edit that key in \`models\` in the named file, then restart Pi.`);
@@ -410,10 +495,13 @@ function validatedModels(value: unknown, label: string): Record<string, string>
       if (typeof model !== "string" || !isValidPanelValue(model)) {
         throw new Error(`${label}: role ${safeEcho(role)}. ${invalidPanelMessage(model)}`);
       }
+    } else if (Array.isArray(model)) {
+      if (!isValidPoolValue(model)) throw new Error(`${label}: role ${safeEcho(role)}. ${invalidPoolMessage(model)}`);
     } else if (typeof model !== "string" || !isValidModelSpec(model)) {
       throw new Error(`${label}: role ${safeEcho(role)}. ${invalidModelMessage(model)}`);
     }
-    Object.defineProperty(models, role, { value: model, enumerable: true, writable: true, configurable: true });
+    const stored: ModelValue = Array.isArray(model) ? [...(model as string[])] : (model as string);
+    Object.defineProperty(models, role, { value: stored, enumerable: true, writable: true, configurable: true });
   }
   return models;
 }

package/src/filter.ts

@@ -0,0 +1,150 @@
+import { safeEcho } from "./echo.ts";
+import { splitModelSpec } from "./config.ts";
+
+/**
+ * Which models delegation may use. A pattern with a `/` matches the whole `provider/id`; a pattern
+ * without one matches the model id after the last `/`. `*` is the only wildcard. An empty or
+ * missing list does not restrict anything.
+ */
+export interface ModelFilter {
+  readonly include?: readonly string[];
+  readonly exclude?: readonly string[];
+}
+
+/** Where the filter in force came from, for the status report. */
+export type FilterOrigin =
+  | { readonly kind: "none" }
+  | { readonly kind: "session"; readonly filter: ModelFilter; readonly shadows?: string }
+  | { readonly kind: "saved"; readonly filter: ModelFilter; readonly source: string };
+
+export const FILTER_ENTRY_TYPE = "pistack-model-filter";
+
+const MAX_PATTERNS = 32;
+const MAX_PATTERN_LENGTH = 128;
+const PATTERN = /^[A-Za-z0-9._:/@~+*-]+$/;
+
+export function filterPatternProblem(pattern: unknown): string | undefined {
+  if (typeof pattern !== "string" || pattern === "") return `Filter pattern ${safeEcho(pattern)} is not a non-empty string.`;
+  if (pattern.length > MAX_PATTERN_LENGTH || !PATTERN.test(pattern)) {
+    return `Filter pattern ${pattern.length > MAX_PATTERN_LENGTH ? `(${pattern.length} characters)` : safeEcho(pattern)} is invalid. Use ASCII letters, digits, and \`. _ - : / @ ~ +\`, with \`*\` as the only wildcard, at most ${MAX_PATTERN_LENGTH} characters, for example \`gpt-*\` or \`openai/*\`.`;
+  }
+  return undefined;
+}
+
+/** Parses an untrusted filter value from a config file or a tool call. */
+export function parseModelFilter(value: unknown): { readonly filter: ModelFilter } | { readonly problem: string } {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { problem: "`modelFilter` must be an object with optional `include` and `exclude` lists of patterns." };
+  }
+  const keys = Object.keys(value);
+  const unknown = keys.filter((key) => key !== "include" && key !== "exclude");
+  if (unknown.length > 0) return { problem: `\`modelFilter\` takes only \`include\` and \`exclude\`, not ${unknown.map((key) => safeEcho(key)).join(", ")}.` };
+  const filter: { include?: string[]; exclude?: string[] } = {};
+  for (const key of ["include", "exclude"] as const) {
+    const list = (value as Record<string, unknown>)[key];
+    if (list === undefined) continue;
+    if (!Array.isArray(list) || list.length > MAX_PATTERNS) {
+      return { problem: `\`modelFilter.${key}\` must be a list of at most ${MAX_PATTERNS} patterns.` };
+    }
+    for (const pattern of list) {
+      const problem = filterPatternProblem(pattern);
+      if (problem) return { problem: `\`modelFilter.${key}\`: ${problem}` };
+    }
+    filter[key] = [...(list as string[])];
+  }
+  return { filter };
+}
+
+export function isRestricting(filter: ModelFilter | undefined): filter is ModelFilter {
+  return filter !== undefined && ((filter.include?.length ?? 0) > 0 || (filter.exclude?.length ?? 0) > 0);
+}
+
+function globMatches(pattern: string, value: string): boolean {
+  const glob = pattern.toLowerCase();
+  const text = value.toLowerCase();
+  let p = 0;
+  let v = 0;
+  let star = -1;
+  let retry = 0;
+  while (v < text.length) {
+    if (glob[p] === "*") {
+      star = p++;
+      retry = v;
+    } else if (glob[p] === text[v]) {
+      p++;
+      v++;
+    } else if (star !== -1) {
+      p = star + 1;
+      v = ++retry;
+    } else {
+      return false;
+    }
+  }
+  while (glob[p] === "*") p++;
+  return p === glob.length;
+}
+
+function patternMatches(pattern: string, model: string): boolean {
+  if (pattern.includes("/")) return globMatches(pattern, model);
+  return globMatches(pattern, model.slice(model.lastIndexOf("/") + 1));
+}
+
+/** `model` is `provider/id`, optionally with a thinking suffix, which is ignored. */
+export function modelAllowed(filter: ModelFilter | undefined, model: string): boolean {
+  if (!isRestricting(filter)) return true;
+  const bare = splitModelSpec(model).model;
+  const include = filter.include ?? [];
+  if (include.length > 0 && !include.some((pattern) => patternMatches(pattern, bare))) return false;
+  return !(filter.exclude ?? []).some((pattern) => patternMatches(pattern, bare));
+}
+
+export function describeFilter(filter: ModelFilter): string {
+  const list = (patterns: readonly string[] | undefined) =>
+    patterns && patterns.length > 0 ? patterns.map((pattern) => `\`${pattern}\``).join(", ") : "none";
+  return `include ${list(filter.include)}; exclude ${list(filter.exclude)}`;
+}
+
+/** The session's filter from the last entry on the active branch: a filter, or a clear. */
+export function sessionFilterFromEntries(entries: readonly unknown[]): ModelFilter | undefined {
+  let current: ModelFilter | undefined;
+  for (const candidate of entries) {
+    if (typeof candidate !== "object" || candidate === null) continue;
+    const entry = candidate as { type?: unknown; customType?: unknown; data?: unknown };
+    if (entry.type !== "custom" || entry.customType !== FILTER_ENTRY_TYPE) continue;
+    const data = entry.data as { cleared?: unknown; filter?: unknown } | undefined;
+    if (data?.cleared === true) {
+      current = undefined;
+      continue;
+    }
+    const parsed = parseModelFilter(data?.filter);
+    if ("filter" in parsed) current = parsed.filter;
+  }
+  return current;
+}
+
+/** The filter in force. An explicit session filter wins over the saved one, even an empty one. */
+export function activeFilter(session: ModelFilter | undefined, saved: { readonly filter: ModelFilter; readonly source: string } | undefined): FilterOrigin {
+  if (session !== undefined) return { kind: "session", filter: session, shadows: saved?.source };
+  if (saved !== undefined) return { kind: "saved", filter: saved.filter, source: saved.source };
+  return { kind: "none" };
+}
+
+export function filterOf(origin: FilterOrigin): ModelFilter | undefined {
+  return origin.kind === "none" ? undefined : origin.filter;
+}
+
+export function describeOrigin(origin: FilterOrigin): string {
+  switch (origin.kind) {
+    case "none":
+      return "none, every model is allowed";
+    case "session":
+      return `${isRestricting(origin.filter) ? describeFilter(origin.filter) : "unrestricted"} (this session${origin.shadows ? `, overriding the saved filter in ${origin.shadows}` : ""})`;
+    case "saved":
+      return `${isRestricting(origin.filter) ? describeFilter(origin.filter) : "unrestricted"} (saved in ${origin.source})`;
+  }
+}
+
+/** One line for each delegation brief, so a child knows the restriction its parent works under. */
+export function briefLine(filter: ModelFilter): string {
+  return `Model restriction for this task: use only models allowed by ${describeFilter(filter)}. A pattern with a \`/\` matches \`provider/model\`, one without matches the model id, and \`*\` matches anything. Give every agent you start an allowed model and this line, verbatim. If no allowed model fits, stop and report it.`;
+}

package/src/gate.ts

@@ -0,0 +1,139 @@
+import { splitModelSpec } from "./config.ts";
+import { SUBAGENT_TOOL, T3_DELEGATE_TOOL } from "./delegation.ts";
+import { type ModelFilter, describeFilter, isRestricting, modelAllowed } from "./filter.ts";
+
+export type GateDecision = { readonly kind: "allow" } | { readonly kind: "block"; readonly reason: string };
+
+export interface GateContext {
+  /** The filter in force. Undefined or empty lets every call through. */
+  readonly filter?: ModelFilter;
+  /** `provider/id` of the session's model, which a child with no model runs on. */
+  readonly parentModel?: string;
+  /** Maps a requested model to its registry `provider/id`, or undefined when Pi does not know it. */
+  readonly resolveModel: (model: string) => string | undefined;
+}
+
+const ALLOW: GateDecision = { kind: "allow" };
+
+/**
+ * pi-subagents actions that start or restart a child, or schedule one, outside the `model` the
+ * call names. The gate cannot see which model they run on, so it blocks them under a filter.
+ * Steering can also revive a child. Status, listing, and stopping do not launch children.
+ */
+const LAUNCHING_ACTIONS = new Set([
+  "resume", "append-step", "debug.run", "refine", "project.open", "watchdog.configure", "steer",
+  "schedule.create", "schedule.run", "schedule.run-due", "schedule.resume",
+]);
+
+/**
+ * Checks one delegation tool call against the session's model filter. Only `delegate_task` and
+ * `subagent` are checked, whoever starts the delegation. Every other tool passes.
+ */
+export function gateDelegation(toolName: string, input: unknown, context: GateContext): GateDecision {
+  if (!isRestricting(context.filter)) return ALLOW;
+  const args = typeof input === "object" && input !== null ? (input as Record<string, unknown>) : {};
+  if (toolName === T3_DELEGATE_TOOL) return gateT3(args, context);
+  if (toolName === SUBAGENT_TOOL) return gateSubagent(args, context);
+  return ALLOW;
+}
+
+function block(reason: string, filter: ModelFilter): GateDecision {
+  return {
+    kind: "block",
+    reason: `Blocked by the pstack adapter's model filter (${describeFilter(filter)}). ${reason} Report this failed call to the user. Keep the active filter unchanged unless the user requests a change. This call was not retried.`,
+  };
+}
+
+function checkModel(requested: unknown, where: string, context: GateContext & { filter: ModelFilter }): GateDecision {
+  if (typeof requested !== "string" || requested.trim() === "") {
+    return block(`${where} gives a model that is not a non-empty string.`, context.filter);
+  }
+  const resolved = context.resolveModel(splitModelSpec(requested.trim()).model);
+  if (resolved === undefined) {
+    return block(`${where} asks for \`${requested.trim()}\`, which this Pi installation does not know, so the filter cannot allow it.`, context.filter);
+  }
+  if (!modelAllowed(context.filter, resolved)) return block(`${where} asks for \`${resolved}\`, which the filter excludes.`, context.filter);
+  return ALLOW;
+}
+
+function checkParent(where: string, context: GateContext & { filter: ModelFilter }): GateDecision {
+  if (context.parentModel === undefined) {
+    return block(`${where} names no model, so it runs on the parent session's model, which Pi does not report. Name an allowed model.`, context.filter);
+  }
+  if (!modelAllowed(context.filter, context.parentModel)) {
+    return block(`${where} names no model, so it runs on the parent session's model \`${context.parentModel}\`, which the filter excludes. Name an allowed model.`, context.filter);
+  }
+  return ALLOW;
+}
+
+/**
+ * T3's `delegate_task` starts one child per call. No `target`, or a target without a model, runs on
+ * the parent's model. A provider other than Pi names models outside Pi's registry, so the filter
+ * cannot match them.
+ */
+function gateT3(args: Record<string, unknown>, context: GateContext): GateDecision {
+  const filter = context.filter as ModelFilter;
+  const scoped = { ...context, filter };
+  const target = args.target;
+  if (target === undefined || target === null) return checkParent("`delegate_task`", scoped);
+  if (typeof target !== "object" || Array.isArray(target)) return block("`delegate_task` has a `target` that is not an object.", filter);
+  const { model, providerInstanceId, driverKind, environmentId } = target as Record<string, unknown>;
+  if (environmentId !== undefined) {
+    return block("`delegate_task` targets a named environment, whose models this session cannot check. Omit `environmentId` to use the current environment.", filter);
+  }
+  const provider = [providerInstanceId, driverKind].find((value) => value !== undefined && value !== "pi");
+  if (provider !== undefined) {
+    return block(`\`delegate_task\` targets T3 provider \`${String(provider)}\`, whose models are not Pi registry ids, so the filter cannot check them. Use \`providerInstanceId: "pi"\`.`, filter);
+  }
+  if (model === undefined) return checkParent("`delegate_task`", scoped);
+  return checkModel(model, "`delegate_task`", scoped);
+}
+
+/**
+ * pi-subagents starts one child from `agent`, several from `tasks` or `chain`, or any number from a
+ * workflow script. An agent can carry its own default model, and an external runner or another
+ * machine picks its own, so under a filter every child must name an allowed model.
+ */
+function gateSubagent(args: Record<string, unknown>, context: GateContext): GateDecision {
+  const filter = context.filter as ModelFilter;
+  const scoped = { ...context, filter };
+  const options = typeof args.options === "object" && args.options !== null ? (args.options as Record<string, unknown>) : {};
+  const action = args.action;
+  if (typeof action === "string" && action.trim() !== "") {
+    if (LAUNCHING_ACTIONS.has(action.trim())) {
+      return block(`\`subagent\` action \`${action.trim()}\` can start a child on a model the adapter cannot see.`, filter);
+    }
+    return ALLOW;
+  }
+  if (args.workflow !== undefined || options.script !== undefined || args.workflowScript !== undefined) {
+    return block("A `subagent` workflow picks its children's models inside the script, where the adapter cannot check them. Start each child with `agent` and an allowed `model` instead.", filter);
+  }
+  const machine = args.machine ?? options.machine;
+  if (machine !== undefined && machine !== "local") {
+    return block("A `subagent` child on another machine picks its own model, which the adapter cannot check.", filter);
+  }
+  const children: Array<{ readonly where: string; readonly model: unknown }> = [];
+  if (args.agent !== undefined) children.push({ where: "`subagent`", model: args.model ?? options.model });
+  if (Array.isArray(args.tasks)) {
+    args.tasks.forEach((task, index) => children.push({ where: `\`subagent\` tasks[${index}]`, model: (task as { model?: unknown } | null)?.model }));
+  }
+  if (Array.isArray(args.chain)) {
+    args.chain.forEach((step, index) => {
+      const entry = (step ?? {}) as { model?: unknown; parallel?: unknown; agent?: unknown };
+      if (Array.isArray(entry.parallel)) {
+        entry.parallel.forEach((task, inner) =>
+          children.push({ where: `\`subagent\` chain[${index}].parallel[${inner}]`, model: (task as { model?: unknown } | null)?.model }),
+        );
+      }
+      if (entry.agent !== undefined || !Array.isArray(entry.parallel)) children.push({ where: `\`subagent\` chain[${index}]`, model: entry.model });
+    });
+  }
+  for (const child of children) {
+    if (child.model === undefined) {
+      return block(`${child.where} names no model, so it would run on its agent's default model or the parent's, which the adapter cannot check. Pass an allowed \`model\`.`, filter);
+    }
+    const decision = checkModel(child.model, child.where, scoped);
+    if (decision.kind === "block") return decision;
+  }
+  return ALLOW;
+}

package/src/generate.ts

@@ -472,6 +472,29 @@ const NESTED_DELEGATION_RULE = `Nested delegation: every agent that delegates, a
   \`pstack_adapter\` status report, using \`general\` when no role fits. Never let one inherit your
   model or thinking, except a panel seat from an \`inherit\` entry in that report's \`panel roles\` table, and never raise a role above its configured level."`;
 
+const MODEL_POLICY_SECTION = `Model pools and the model filter work the same on both backends.
+
+- A role whose \`model roles\` row reads "pool, pick one of" lists alternatives. For each
+  delegation, pick ONE model from it by fit, and pass that model and its thinking by the backend
+  rules below. A pool is not a retry list and not a panel: start one child per task, and when a
+  delegation fails, report the failure instead of trying another model from the pool.
+- A role whose row reads "BLOCKED" has no model the model filter allows. Do not delegate its work,
+  and do not move the work to \`general\` or to your own model. Tell the user which role is blocked
+  and why.
+- A panel seat that reads "BLOCKED" does not run. Run the other seats, and say in your reply which
+  seat did not run and why. A seat that reads "one of" runs once, on one model you pick from it.
+- When the \`model filter\` row of the status report names a filter, the adapter blocks any
+  \`delegate_task\` or \`subagent\` call in this session whose model the filter excludes, or whose
+  model it cannot tell. That covers a call with no model while your own model is excluded, a model
+  Pi does not know, a T3 provider other than \`pi\`, a \`subagent\` child without \`model\`, a
+  \`subagent\` workflow script, and a \`subagent\` action that starts, restarts, steers, or schedules
+  a child or configures a watchdog. A T3 target with a named environment is blocked too.
+  Report a blocked call instead of retrying it. Keep the active filter unchanged unless the user
+  requests a change. Wait for \`set_filter\` to finish before issuing delegation calls.
+- Children do not inherit a session filter. Put the brief line that the \`check\` report gives into
+  every brief, verbatim, so each child keeps to the same models when it starts agents of its own.
+  A saved filter applies in a child where the adapter loads the same config files.`;
+
 function delegationSection(namespace: string, preferred: DelegationProvider): string {
   const sections = delegationOrder(preferred).map((backend) => (backend.id === "t3" ? t3Section(namespace) : subagentSection(namespace)));
   const order = delegationOrder(preferred).map((backend) => `\`${backend.tool}\``).join(", then ");
@@ -483,6 +506,8 @@ first usable tool in the configured order, ${order}. The adapter rejects a tool
 extension registered under T3's name, or one that lacks the parameters below, even when it is in
 your tools. Use one backend for a whole workflow.
 
+${MODEL_POLICY_SECTION}
+
 ${sections.join("\n\n")}`;
 }
 
@@ -535,7 +560,8 @@ function subagentSection(namespace: string): string {
   table in the \`pstack_adapter\` \`status\` report names a level for the role, append it as
   \`provider/model:<level>\`. A role whose thinking reads "backend default" gets no suffix, so
   pi-subagents applies its own default. An unconfigured role uses the \`general\` role, and omits
-  \`model\` only when \`general\` is unconfigured too.
+  \`model\` only when \`general\` is unconfigured too. Under a model filter, always pass \`model\`,
+  using your own model for a role that inherits.
 - ${NESTED_DELEGATION_RULE}
 - Background: \`async: true\`.`;
 }
@@ -648,7 +674,7 @@ function adapterDescription(file: string, namespace: string): string {
     case "status.md":
       return `[${namespace}/native] Report the pstack adapter version, upstream version, configured ref, resolved commit, cache state, support tiers, and capability checks. Use for "${namespace} status" or before trusting a pstack workflow.`;
     case "setup.md":
-      return `[${namespace}/native] Configure which Pi model each pstack role uses, and which upstream pstack revision the adapter reads. Use for "/skill:${namespace}-setup", "configure pstack models", or selecting another pstack revision.`;
+      return `[${namespace}/native] Configure which Pi model or pool of models each pstack role uses, which models delegation may use, and which upstream pstack revision the adapter reads. Use for "/skill:${namespace}-setup", "configure pstack models", restricting delegation to some models such as GPT only, or selecting another pstack revision.`;
     default:
       return `[${namespace}/native] Adapter-owned pstack workflow.`;
   }

package/src/pools.ts

@@ -0,0 +1,104 @@
+import { type AdapterConfig, type ModelSpec, panelEntries, poolEntries, splitModelSpec } from "./config.ts";
+import { type ModelFilter, isRestricting, modelAllowed } from "./filter.ts";
+import { GENERAL_ROLE, PANEL_DEFAULT_ROLES } from "./registry.ts";
+
+/** What the model filter knows about the model of the agent that starts a delegation. */
+export interface ResolutionContext {
+  readonly filter?: ModelFilter;
+  /** `provider/id` of the parent session's model, when Pi reports one. */
+  readonly parentModel?: string;
+}
+
+export interface PoolChoice {
+  readonly spec: ModelSpec;
+  readonly eligible: boolean;
+}
+
+/**
+ * How a role resolves. `from` names the role whose value applies, which is `general` for an
+ * unset role when `general` is set. A configured pool whose choices are all excluded is blocked:
+ * it never falls back to `general` or the parent.
+ */
+export type RoleResolution =
+  | { readonly kind: "inherit"; readonly from: string }
+  | { readonly kind: "pool"; readonly from: string; readonly choices: readonly PoolChoice[] }
+  | { readonly kind: "blocked"; readonly from: string; readonly reason: string; readonly choices: readonly PoolChoice[] };
+
+/** Why the parent's model cannot run under the filter, or undefined when it can. */
+export function parentProblem(context: ResolutionContext): string | undefined {
+  if (!isRestricting(context.filter)) return undefined;
+  if (context.parentModel === undefined) return "the parent session's model is unknown, so the model filter cannot allow it";
+  if (!modelAllowed(context.filter, context.parentModel)) return `the parent session's model \`${context.parentModel}\` is excluded by the model filter`;
+  return undefined;
+}
+
+export function resolveRole(config: AdapterConfig, role: string, context: ResolutionContext): RoleResolution {
+  const own = config.models[role];
+  const from = own !== undefined ? role : config.models[GENERAL_ROLE] !== undefined ? GENERAL_ROLE : undefined;
+  if (from === undefined) {
+    const problem = parentProblem(context);
+    return problem ? { kind: "blocked", from: role, reason: `it inherits, and ${problem}`, choices: [] } : { kind: "inherit", from: role };
+  }
+  const value = config.models[from] ?? "";
+  const choices = poolEntries(value).map((entry) => {
+    const spec = splitModelSpec(entry);
+    return { spec, eligible: modelAllowed(context.filter, spec.model) };
+  });
+  if (choices.some((choice) => choice.eligible)) return { kind: "pool", from, choices };
+  return {
+    kind: "blocked",
+    from,
+    reason: `every model ${from === role ? "it lists" : `\`${from}\` lists`} is excluded by the model filter`,
+    choices,
+  };
+}
+
+/** One seat of a panel. Seats keep their meaning; a pool seat picks one eligible choice. */
+export type PanelSeat =
+  | { readonly kind: "model"; readonly spec: ModelSpec; readonly from?: string }
+  | { readonly kind: "parent"; readonly from?: string }
+  | { readonly kind: "choice"; readonly choices: readonly ModelSpec[]; readonly from: string }
+  | { readonly kind: "blocked"; readonly reason: string; readonly from?: string };
+
+export interface ResolvedPanel {
+  readonly role: string;
+  readonly configured: boolean;
+  readonly seats: readonly PanelSeat[];
+}
+
+export function resolvePanel(config: AdapterConfig, role: string, context: ResolutionContext = {}): ResolvedPanel {
+  const configured = config.models[role];
+  if (typeof configured === "string") {
+    return {
+      role,
+      configured: true,
+      seats: panelEntries(configured).map((entry): PanelSeat => {
+        if (entry.kind === "inherit") {
+          const problem = parentProblem(context);
+          return problem ? { kind: "blocked", reason: `this \`inherit\` seat is blocked, because ${problem}` } : { kind: "parent" };
+        }
+        return modelAllowed(context.filter, entry.spec.model)
+          ? { kind: "model", spec: entry.spec }
+          : { kind: "blocked", reason: `\`${entry.spec.model}\` is excluded by the model filter` };
+      }),
+    };
+  }
+  return { role, configured: false, seats: defaultSeats(config, context) };
+}
+
+/** The seats an unset panel gets, one per default role, each drawing one choice from that role's pool. */
+export function defaultSeats(config: AdapterConfig, context: ResolutionContext = {}): PanelSeat[] {
+  return PANEL_DEFAULT_ROLES.map((name): PanelSeat => {
+    const resolved = resolveRole(config, name, context);
+    switch (resolved.kind) {
+      case "inherit":
+        return { kind: "parent", from: name };
+      case "blocked":
+        return { kind: "blocked", reason: resolved.reason, from: resolved.from };
+      case "pool": {
+        const eligible = resolved.choices.filter((choice) => choice.eligible).map((choice) => choice.spec);
+        return eligible.length === 1 ? { kind: "model", spec: eligible[0] as ModelSpec, from: resolved.from } : { kind: "choice", choices: eligible, from: resolved.from };
+      }
+    }
+  });
+}