pi-pstack-adapter 0.7.0 → 0.9.0

package/src/config.ts

@@ -4,8 +4,24 @@ import { CERTIFIED } from "./certified.ts";
 import { safeEcho } from "./echo.ts";
 import { DEFAULT_NAMESPACE, validateNamespace } from "./namespace.ts";
 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;
@@ -18,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[];
@@ -33,7 +51,8 @@ export interface ConfigFile {
   pinnedCommit?: string;
   allowBootstrap?: boolean;
   cacheDir?: string;
-  models?: Record<string, string>;
+  models?: Record<string, ModelValue>;
+  modelFilter?: ModelFilter;
   delegation?: string;
 }
 
@@ -189,6 +208,89 @@ export function planModelAssignment(
   return { kind: "assign", spec: assigned };
 }
 
+const MAX_MODEL_SPEC_LENGTH = 128;
+
+/** A panel entry that runs on the parent session's model, like upstream's `inherit-parent`. */
+export const INHERIT_ENTRY = "inherit";
+
+export type PanelEntry = { readonly kind: "inherit" } | { readonly kind: "model"; readonly spec: ModelSpec };
+
+/** Splits a panel value. Entries are separated by ASCII spaces, because a model id has none. */
+export function splitPanelValue(value: string): string[] {
+  return value.split(/ +/).filter((entry) => entry !== "");
+}
+
+/** The longest value `set_model` can write: every entry at its limit, one space apart. */
+const MAX_PANEL_VALUE_LENGTH = MAX_PANEL_ENTRIES * (MAX_MODEL_SPEC_LENGTH + 1) - 1;
+
+export function panelEntries(value: string): PanelEntry[] {
+  return splitPanelValue(value).map((entry) =>
+    entry === INHERIT_ENTRY ? { kind: "inherit" } : { kind: "model", spec: splitModelSpec(entry) },
+  );
+}
+
+export function isValidPanelValue(value: string): boolean {
+  if (value.length > MAX_PANEL_VALUE_LENGTH) return false;
+  const entries = splitPanelValue(value);
+  return (
+    entries.length > 0 &&
+    entries.length <= MAX_PANEL_ENTRIES &&
+    entries.every((entry) => entry === INHERIT_ENTRY || isValidModelSpec(entry))
+  );
+}
+
+function invalidPanelMessage(value: unknown): string {
+  return `Invalid panel value ${typeof value === "string" ? `(${value.length} characters)` : safeEcho(value)}. Use 1 to ${MAX_PANEL_ENTRIES} entries separated by spaces, each \`provider/model\`, \`provider/model:thinking\`, or \`${INHERIT_ENTRY}\`.`;
+}
+
+export type PanelAssignment =
+  | { readonly kind: "inherit" }
+  | { readonly kind: "assign"; readonly value: string }
+  | { readonly kind: "rejected"; readonly message: string };
+
+/**
+ * Validates a `set_model` request for a panel role. The value lists entries separated by commas or
+ * spaces. `thinking` applies to each model entry that has no `:level` suffix of its own. A value of
+ * just `inherit` clears the panel, so it falls back to its default roles.
+ */
+export function planPanelAssignment(
+  value: string,
+  thinking: string | undefined,
+  available: readonly AvailableModel[],
+): PanelAssignment {
+  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 entries = value.split(/[\s,]+/).filter((entry) => entry !== "");
+  const onlyInherit = entries.every((entry) => entry.toLowerCase() === INHERIT_ENTRY);
+  if (entries.length > 0 && onlyInherit && thinking?.trim()) {
+    return {
+      kind: "rejected",
+      message: "An `inherit` entry runs at the parent session's thinking, so `thinking` has nothing to apply to. Drop `thinking`, or add a `provider/model` entry.",
+    };
+  }
+  if (entries.length === 1 && entries[0]?.toLowerCase() === INHERIT_ENTRY) return { kind: "inherit" };
+  if (entries.length === 0 || entries.length > MAX_PANEL_ENTRIES) {
+    return { kind: "rejected", message: `A panel takes 1 to ${MAX_PANEL_ENTRIES} entries, one seat each, separated by commas or spaces.` };
+  }
+  const written: string[] = [];
+  for (const entry of entries) {
+    if (entry.toLowerCase() === INHERIT_ENTRY) {
+      written.push(INHERIT_ENTRY);
+      continue;
+    }
+    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.join(" ") };
+}
+
 /** Role names reach generated markdown and status tables, so they stay plain kebab-case. */
 const ROLE_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
 /**
@@ -200,7 +302,6 @@ const ROLE_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
 const PRINTABLE_ASCII = /^[\x21-\x7e]+$/;
 const MARKUP_CHARACTERS = /[`|<>[\]()\\*]/;
 
-const MAX_MODEL_SPEC_LENGTH = 128;
 
 export function isValidModelSpec(model: string): boolean {
   const plain = (value: string) => PRINTABLE_ASCII.test(value) && !MARKUP_CHARACTERS.test(value) && !value.endsWith(":");
@@ -221,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;
@@ -236,7 +392,16 @@ export function parseModelRoles(value: string): Record<string, string> {
     if (!isValidRole(role)) throw new Error(invalidRoleMessage(role));
     // An empty value is an unset variable that expanded to nothing, not a model.
     if (model === "") continue;
-    if (!isValidModelSpec(model)) throw new Error(invalidModelMessage(model));
+    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));
+    }
     roles[role] = model;
   }
   return roles;
@@ -265,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)) {
@@ -281,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;
       }
@@ -303,26 +474,34 @@ 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.`);
     }
     if (model === "") continue;
-    if (typeof model !== "string" || !isValidModelSpec(model)) {
+    if (isPanelRole(role)) {
+      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;
+}