pi-pstack-adapter 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project are documented here. release-please writes new entries from Conventional Commit PR titles.
 
+## [0.9.0](https://github.com/elderfo/pi-pstack-adapter/compare/v0.8.0...v0.9.0) (2026-11-05)
+
+
+### Features
+
+* add role model pools and session delegation filters ([#30](https://github.com/elderfo/pi-pstack-adapter/issues/30)) ([b2bf25a](https://github.com/elderfo/pi-pstack-adapter/commit/b2bf25a577d9ae90b548894cf7f79bb128c30902))
+
 ## [0.8.0](https://github.com/elderfo/pi-pstack-adapter/compare/v0.7.0...v0.8.0) (2026-11-01)
 
 

package/README.md

@@ -173,6 +173,71 @@ Upstream pstack defaults each panel to two model families. A panel you leave uns
 `judgment`, then `general`, so it covers two families only when those roles do. The status
 report warns when a panel's seats all run on one model.
 
+### Give a role a pool of models
+
+An ordinary role can list several models instead of one. Each delegation for that role picks one
+model from the list. A pool is not a panel: a panel runs one seat per entry, but a pool starts one
+child per task. A pool is not a retry list either: when a delegation fails, the agent reports the
+failure and does not try the next model. In a config file a pool is a JSON list:
+
+```json
+{ "models": { "feature": ["provider/model-a:high", "provider/model-b:high", "provider/model-c"] } }
+```
+
+The `set_model` action takes the same list in `model`, and its `thinking` applies to each entry
+without its own `:level`. Every entry must be a model in your Pi installation, or nothing is
+written. In `PISTACK_MODELS`, separate a pool's entries with `|`:
+
+```bash
+PISTACK_MODELS='feature=provider/model-a:high|provider/model-b' pi
+```
+
+A panel keeps its string of seats. An unset panel's two default seats each pick one model from the
+`judgment` and `general` pools.
+
+### Restrict which models delegation uses
+
+A model filter limits delegation to some models without changing the role assignments, for
+example to run an experiment on one model family only. Ask the agent, or call the
+`pstack_adapter` tool's `set_filter` action:
+
+- `include: ["gpt-*"]` allows only models whose id starts with `gpt-`.
+- `exclude: ["*claude*"]` excludes model ids containing `claude`, including Bedrock-style ids.
+- `clear: true` removes the filter at that scope.
+
+A pattern with a `/` matches `provider/model`, and one without matches the model id after the
+provider. `*` is the only wildcard, and matching ignores case. A model must match an `include`
+pattern when there are any, and must match no `exclude` pattern.
+
+A filter applies to the current session by default and is not saved. Pass `scope: "user"` or
+`scope: "project"` to save it as `modelFilter` in that config file. A saved filter takes effect
+at once, and a filter set for the session wins over a saved one until you clear it. The
+`model filter` row of `/pistack-status` shows the filter in force and where it came from.
+A trusted project's filter replaces the user filter as a whole, including an empty filter.
+Empty lists set an unrestricted override; clearing the session filter restores the saved filter.
+Wait for `set_filter` to finish before starting delegations, rather than issuing them together.
+
+Under a filter, the status report and `/pistack-check` mark each pool entry as allowed or
+excluded. A role with no allowed entry is blocked: its work is not moved to `general` or to the
+session's model. A role that inherits is blocked when the filter excludes the session's model.
+A panel seat on an excluded model is blocked, and the other seats still run.
+
+The adapter also checks every `delegate_task` and `subagent` call in the session, including
+calls that no pstack workflow made, and blocks one whose model the filter excludes or that it
+cannot check. That includes a call with no model while the session's model is excluded, a model
+Pi does not know, a T3 provider other than Pi, a `subagent` child without a model, a `subagent`
+workflow script, and a `subagent` action that restarts, refines, steers, or schedules a child,
+opens a project session, or configures a watchdog. A T3 target with a named environment is also
+blocked because its registry may differ. A blocked call is not retried. These limits apply:
+
+- A child does not inherit a session filter, so the agent puts it into each brief as an
+  instruction. A saved filter applies in a child where the adapter loads the same config files.
+- Other tools that start agents or processes, such as T3 Code's thread tools or a shell command,
+  are not checked. The filter does not block a provider or a model inside Pi.
+- Changing models with `/model` is not affected.
+- The filter is a model-selection guard, not an access-control boundary. The agent can change it
+  through `set_filter`, but is instructed to keep it unchanged unless the user requests a change.
+
 Role names are lowercase letters, digits, and hyphens. A model value is printable ASCII with no spaces or markup characters, at most 128 characters. A config entry that breaks these rules stops the adapter at startup with an error that names the file, so fix the key there and restart Pi.
 
 A role without a level passes none, so the delegation backend applies its own default. A role's
@@ -220,7 +285,7 @@ settings to `.pi/pi-pstack-adapter.json`. Environment variables override both fi
 | `PISTACK_UPSTREAM_PLUGIN_PATH` | Selects the plugin directory inside the checkout. |
 | `PISTACK_ALLOW_BOOTSTRAP` | Allows a noninteractive first download. |
 | `PISTACK_CACHE_DIR` | Changes the cache directory. |
-| `PISTACK_MODELS` | Assigns models as comma-separated `role=provider/model[:thinking]` pairs. A panel role takes its entries separated by spaces. |
+| `PISTACK_MODELS` | Assigns models as comma-separated `role=provider/model[:thinking]` pairs. A pool separates its entries with `\|`. A panel role takes its entries separated by spaces. |
 | `PISTACK_DELEGATION` | Sets the delegation provider to try first: `t3` (default) or `pi-subagents`. The config file key is `delegation`. |
 
 ## Security and trust

package/VERSION

@@ -1 +1 @@
-0.8.0
+0.9.0

package/adapter-skills/setup.md

@@ -4,7 +4,8 @@ Upstream pstack ships a `setup-pstack` skill that writes `~/.cursor/rules/pstack
 a Cursor-only always-applied rule full of Cursor model slugs. Pi has neither that file nor
 those models, so this adapter replaces the body with the Pi equivalent.
 
-Three things are configurable. Model roles, the upstream source, and the delegation order.
+Four things are configurable. Model roles, the model filter, the upstream source, and the
+delegation order.
 
 ## Model roles
 
@@ -64,7 +65,9 @@ Steps.
    installation can actually reach. Do not invent ids.
 2. Ask the user which model each role should use. Offer the listed ids, and offer
    `inherit` for any role they do not care about. Use the structured question tool when it is
-   available; otherwise ask in plain text. Only ids from step 1 are accepted.
+   available; otherwise ask in plain text. Only ids from step 1 are accepted. A user who wants
+   alternatives for a role gets a pool: a list of models, of which each delegation picks one.
+   A pool is a set of choices, not a retry list and not a panel, so say that when you offer it.
 3. Ask for a thinking level. Do not assume the user wants none. Skip this step only when every
    role is on `inherit`. It applies to every role that got a model in step 2. A role on
    `inherit` cannot have a level, so tell the user that and say that those roles follow the
@@ -90,9 +93,12 @@ Steps.
    instead of asking again. The tool rejects any level other than `off` on a model that has no reasoning support.
    When it does, set that role with no level and tell the user which role has none.
 4. For each role, call the adapter tool with `action: "set_model"`, the role, the chosen
-   `provider/model` id, and `thinking` when step 3 picked a level. Pass `scope: "project"` when
-   the user wants the choice to apply only to this repository. Calling `set_model` for a role
-   again without `thinking` clears a level set earlier, so always pass it again.
+   `provider/model` id, and `thinking` when step 3 picked a level. For a pool, pass `model` as a
+   list of ids, for example `model: ["provider/model-a", "provider/model-b"]`. `thinking`
+   applies to each entry without its own `:level`, and one unknown entry rejects the whole pool.
+   Pass `scope: "project"` when the user wants the choice to apply only to this repository.
+   Calling `set_model` for a role again without `thinking` clears a level set earlier, so always
+   pass it again.
 5. Set the panels. Read the `panel roles` table of `action: "status"` and show the user each
    panel's seats. When a panel's seats share one model, or one family, say so and suggest two
    families from step 1, as upstream's defaults do. Never say a family is missing unless the
@@ -106,10 +112,35 @@ Steps.
 
 For a scripted environment, set `PISTACK_MODELS` instead, for example
 `PISTACK_MODELS=feature=anthropic/claude-sonnet-4-5:medium,bug-fix=openai/gpt-5:high`. The
-optional `:level` suffix sets the thinking level. A panel's entries are separated by spaces, as
+optional `:level` suffix sets the thinking level. A pool's entries are separated by `|`, as in
+`feature=anthropic/claude-sonnet-4-5:high|openai/gpt-5:high`. A panel's entries are separated by spaces, as
 in `PISTACK_MODELS='arena-runners=anthropic/claude-sonnet-4-5:high openai/gpt-5:high'`. The environment wins
 over both config files, so CI never needs this dialog.
 
+## Model filter
+
+A model filter restricts delegation to some models, such as one family for an experiment,
+without rewriting the roles. Call the adapter tool with `action: "set_filter"` and:
+
+- `include`, a list of patterns a model must match, such as `["gpt-*"]` for GPT only.
+- `exclude`, a list of patterns no model may match, such as `["*claude*"]` for no Claude, including Bedrock-style ids.
+- `clear: true` to remove the filter at that scope.
+
+A pattern with `/` matches `provider/model`; one without matches the model id. `*` is the only
+wildcard. The filter applies to this session only, unless the user asks to save it: then pass
+`scope: "user"` or `scope: "project"`. A session filter wins over a saved one until it is cleared.
+A trusted project's filter replaces the user filter as a whole. Empty lists set an unrestricted
+override; clearing the session filter restores the saved filter. Wait for `set_filter` to finish
+before issuing delegation calls. Keep the active filter unchanged unless the user requests a change.
+
+Read back `action: "status"`. Report the `model filter` row, and any role or panel seat the
+`model roles` or `panel roles` table marks BLOCKED, because a blocked role does not delegate.
+Tell the user the limits: the adapter blocks `delegate_task` and `subagent` calls in this session
+that the filter does not allow. A child does not inherit a session filter and follows it only as
+an instruction in its brief. A saved filter applies in a child where the adapter loads the same
+config files. Other tools that start agents are not checked. This is a model-selection guard,
+not an access-control boundary.
+
 ## Upstream source
 
 By default the adapter uses the pstack revision this release was tested against. Change it only
@@ -138,5 +169,6 @@ the next Pi start.
 
 ## Finish
 
-End by reporting, in your own words, which roles were set, which still inherit, the resolved
-upstream commit, and the trust level from the status output.
+End by reporting, in your own words, which roles were set, which still inherit, which have
+pools, the model filter in force, the resolved upstream commit, and the trust level from the
+status output.

package/index.ts

@@ -7,7 +7,17 @@ import { Type } from "typebox";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { registerDelegationActivation } from "./src/activation.ts";
 import { registerAgents, unregisteredAgentDiagnostics, type RuntimeRegistration } from "./src/agents.ts";
-import { DEFAULT_DELEGATION } from "./src/delegation.ts";
+import { DEFAULT_DELEGATION, SUBAGENT_TOOL, T3_DELEGATE_TOOL } from "./src/delegation.ts";
+import {
+  FILTER_ENTRY_TYPE,
+  type ModelFilter,
+  activeFilter,
+  describeOrigin,
+  filterOf,
+  parseModelFilter,
+  sessionFilterFromEntries,
+} from "./src/filter.ts";
+import { gateDelegation } from "./src/gate.ts";
 import { checkPrerequisites, detectCapabilities, type ToolDescriptor } from "./src/capabilities.ts";
 import {
   type AdapterConfig,
@@ -22,6 +32,7 @@ import {
   mergeConfig,
   planModelAssignment,
   planPanelAssignment,
+  planPoolAssignment,
   readConfigFile,
   trustWarning,
   updateConfigFile,
@@ -32,7 +43,15 @@ import { MODE_ENTRY_TYPE, modeFromEntries, modeInstruction } from "./src/mode.ts
 import { CONFIG_FILE_NAME, agentDir, cacheRoot } from "./src/paths.ts";
 import { bashToolContext, probeExecutables } from "./src/executables.ts";
 import { SKILL_PANELS, entryFor, isPanelRole } from "./src/registry.ts";
-import { platformSupport, renderCheck, renderPanels, renderStatus, shellDiagnostics, type ShellState } from "./src/status.ts";
+import {
+  platformSupport,
+  renderCheck,
+  renderModelPolicy,
+  renderPanels,
+  renderStatus,
+  shellDiagnostics,
+  type ShellState,
+} from "./src/status.ts";
 import { BootstrapRequiredError, resolveRefToCommit, resolveSource } from "./src/upstream.ts";
 import { normalizeRepo } from "./src/config.ts";
 import type { CapabilityStatus, Diagnostic, GeneratedAgent, GenerationResult, ResolvedSource } from "./src/types.ts";
@@ -56,6 +75,11 @@ export default function (pi: ExtensionAPI) {
   let agentDiagnostics: readonly Diagnostic[] = [];
   let unregisteredAgents: readonly GeneratedAgent[] = [];
   let modeActive = false;
+  /** This session's own model filter, restored from the active branch. It wins over a saved one. */
+  let sessionFilter: ModelFilter | undefined;
+  let savedFilter: AdapterConfig["modelFilter"];
+  /** Why the config files could not be read, so the saved filter is unknown. */
+  let configError: string | undefined;
   const commandNamespace = startupNamespace();
 
   pi.on("session_start", async (_event, ctx) => {
@@ -63,9 +87,27 @@ export default function (pi: ExtensionAPI) {
     state = undefined;
     startupError = undefined;
     modeActive = modeFromEntries(ctx.sessionManager.getBranch() as never[]);
+    sessionFilter = sessionFilterFromEntries(ctx.sessionManager.getBranch() as never[]);
+    savedFilter = undefined;
+    configError = undefined;
+
+    let config: AdapterConfig;
+    try {
+      config = loadConfig(ctx);
+    } catch (error) {
+      startupError = error as Error;
+      try {
+        savedFilter = loadConfig(ctx, true).modelFilter;
+      } catch (filterError) {
+        configError = (filterError as Error).message;
+      }
+      if (ctx.hasUI) ctx.ui.notify(`pstack adapter: ${(error as Error).message}`, "error");
+      return;
+    }
+    savedFilter = config.modelFilter;
 
     try {
-      state = await bringUpUpstream(loadConfig(ctx), ctx);
+      state = await bringUpUpstream(config, ctx);
     } catch (error) {
       startupError = error as Error;
       if (ctx.hasUI) ctx.ui.notify(`pstack adapter: ${(error as Error).message}`, "error");
@@ -102,6 +144,29 @@ export default function (pi: ExtensionAPI) {
     }
   });
 
+  // `/tree` moves the active branch, and with it the session filter that branch recorded.
+  pi.on("session_tree", async (_event, ctx) => {
+    sessionFilter = sessionFilterFromEntries(ctx.sessionManager.getBranch() as never[]);
+  });
+
+  // The model filter applies to every delegation in this session, pstack or not, because a
+  // delegation tool call names no pstack role. A blocked call fails; nothing retries it.
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName !== T3_DELEGATE_TOOL && event.toolName !== SUBAGENT_TOOL) return;
+    if (sessionFilter === undefined && configError !== undefined) {
+      return {
+        block: true,
+        reason: `Blocked by the pstack adapter: its config could not be read, so it cannot tell whether a saved model filter applies. ${configError} Fix the config and reload, or ask the user whether to set an explicit session filter with \`set_filter\`.`,
+      };
+    }
+    const decision = gateDelegation(event.toolName, event.input, {
+      filter: filterOf(activeFilter(sessionFilter, savedFilter)),
+      parentModel: parentModelOf(ctx),
+      resolveModel: (model) => resolveRegistryModel(ctx, model),
+    });
+    if (decision.kind === "block") return { block: true, reason: decision.reason };
+  });
+
   pi.on("resources_discover", async () => {
     if (!state) return {};
     return { skillPaths: [state.generation.skillsDir] };
@@ -127,7 +192,7 @@ export default function (pi: ExtensionAPI) {
     name: "pstack_adapter",
     label: "pstack adapter",
     description:
-      "Inspect and configure the pstack adapter. Use `status` for the full report, `check` before starting a pstack workflow, `models` to list real Pi model ids, `set_model` to assign a pstack role, and `set_source` to select another upstream revision.",
+      "Inspect and configure the pstack adapter. Use `status` for the full report, `check` before starting a pstack workflow, `models` to list real Pi model ids, `set_model` to assign a pstack role or a pool of models, `set_filter` to restrict which models delegation may use, and `set_source` to select another upstream revision.",
     parameters: Type.Object({
       action: Type.Union(
         [
@@ -135,6 +200,7 @@ export default function (pi: ExtensionAPI) {
           Type.Literal("check"),
           Type.Literal("models"),
           Type.Literal("set_model"),
+          Type.Literal("set_filter"),
           Type.Literal("set_source"),
         ],
         { description: "Operation to run" },
@@ -142,9 +208,9 @@ export default function (pi: ExtensionAPI) {
       skill: Type.Optional(Type.String({ description: "Skill name for `check`, with or without the namespace prefix" })),
       role: Type.Optional(Type.String({ description: "pstack model role for `set_model`" })),
       model: Type.Optional(
-        Type.String({
+        Type.Union([Type.String(), Type.Array(Type.String())], {
           description:
-            "`provider/model` id, or `inherit` to clear the role. For a panel role such as `arena-runners`, a list of entries separated by commas, one seat each.",
+            "`provider/model` id, or `inherit` to clear the role. A list of ids gives an ordinary role a pool: each delegation picks one. For a panel role such as `arena-runners`, a string of entries separated by commas, one seat each.",
         }),
       ),
       thinking: Type.Optional(
@@ -155,9 +221,16 @@ export default function (pi: ExtensionAPI) {
       repo: Type.Optional(Type.String({ description: "Upstream repository URL for `set_source`" })),
       ref: Type.Optional(Type.String({ description: "Branch, tag, or commit for `set_source`" })),
       localPath: Type.Optional(Type.String({ description: "Local pstack checkout for `set_source`" })),
+      include: Type.Optional(
+        Type.Array(Type.String(), {
+          description: "`set_filter`: patterns a delegation model must match, such as `gpt-*`. `*` is the only wildcard; a pattern with `/` matches `provider/model`.",
+        }),
+      ),
+      exclude: Type.Optional(Type.Array(Type.String(), { description: "`set_filter`: patterns no delegation model may match, such as `claude-*`. Exclude wins." })),
+      clear: Type.Optional(Type.Boolean({ description: "`set_filter`: remove the filter at `scope` instead of setting one." })),
       scope: Type.Optional(
-        Type.Union([Type.Literal("user"), Type.Literal("project")], {
-          description: "Config file to write. Defaults to user.",
+        Type.Union([Type.Literal("session"), Type.Literal("user"), Type.Literal("project")], {
+          description: "`set_filter` defaults to session, this session only. `set_model` and `set_source` write a config file: user (default) or project.",
         }),
       ),
     }),
@@ -211,15 +284,20 @@ export default function (pi: ExtensionAPI) {
       action: string;
       skill?: string;
       role?: string;
-      model?: string;
+      model?: string | string[];
       thinking?: string;
       repo?: string;
       ref?: string;
       localPath?: string;
-      scope?: "user" | "project";
+      include?: string[];
+      exclude?: string[];
+      clear?: boolean;
+      scope?: "session" | "user" | "project";
     },
     ctx: ExtensionContext,
   ): Promise<string> {
+    // A restriction must be settable even when the upstream checkout did not resolve.
+    if (params.action === "set_filter") return setFilter(params, params.scope ?? "session", ctx);
     if (startupError) return `The pstack adapter did not start: ${startupError.message}`;
     if (!state) return "The pstack adapter has not resolved its upstream checkout yet.";
 
@@ -239,6 +317,8 @@ export default function (pi: ExtensionAPI) {
           modeActive,
           cacheRoot: state.cacheRoot,
           bootstrapped: state.bootstrapped,
+          filter: activeFilter(sessionFilter, savedFilter),
+          parentModel: parentModelOf(ctx),
           runtimeDiagnostics: [
             ...agentDiagnostics,
             // Judged now, because T3's tools can connect after the agents were registered.
@@ -251,10 +331,14 @@ export default function (pi: ExtensionAPI) {
         return checkSkill(params.skill ?? "", ctx);
       case "models":
         return renderModels(ctx);
-      case "set_model":
+      case "set_model": {
+        if (params.scope === "session") return SESSION_SCOPE_ONLY_FILTER;
         return setModel(params.role, params.model, params.thinking, params.scope ?? "user", ctx);
-      case "set_source":
+      }
+      case "set_source": {
+        if (params.scope === "session") return SESSION_SCOPE_ONLY_FILTER;
         return setSource(params, params.scope ?? "user", ctx);
+      }
       default:
         return `Unknown action ${params.action}.`;
     }
@@ -282,12 +366,15 @@ export default function (pi: ExtensionAPI) {
     const shellProblems = shellDiagnostics(shell).map((diagnostic) => `${diagnostic.message} ${diagnostic.action ?? ""}`.trim());
     const current = capabilities();
     const panels = Object.hasOwn(SKILL_PANELS, skill.upstreamName) ? SKILL_PANELS[skill.upstreamName] : undefined;
+    const origin = activeFilter(sessionFilter, savedFilter);
+    const parentModel = parentModelOf(ctx);
     return renderCheck(
       skill,
       entryFor(skill.upstreamName, skill.generatedName.slice(prefix.length)),
       checkPrerequisites(skill.capabilities, current, skill.executables, executables.has, shellProblems),
       current.find((capability) => capability.id === "delegation"),
-      panels ? renderPanels(state.config, panels) : undefined,
+      panels ? renderPanels(state.config, panels, { filter: filterOf(origin), parentModel }) : undefined,
+      renderModelPolicy(state.config, origin, parentModel),
     );
   }
 
@@ -301,17 +388,23 @@ export default function (pi: ExtensionAPI) {
 
   function setModel(
     role: string | undefined,
-    model: string | undefined,
+    model: string | string[] | undefined,
     thinking: string | undefined,
     scope: "user" | "project",
     ctx: ExtensionContext,
   ): string {
     if (!role) return "set_model needs a `role`.";
-    if (!model) return "set_model needs a `model`, or `inherit` to clear the role.";
+    if (!model || model.length === 0) return "set_model needs a `model`, or `inherit` to clear the role.";
     if (!isValidRole(role)) return invalidRoleMessage(role);
     const available = ctx.modelRegistry
       .getAvailable()
       .map((candidate) => ({ id: `${candidate.provider}/${candidate.id}`, reasoning: candidate.reasoning }));
+    if (Array.isArray(model)) {
+      if (isPanelRole(role)) {
+        return `Panel \`${role}\` takes one string of entries separated by commas, one seat each, not a list. A list is a pool, which only ordinary roles have.`;
+      }
+      return setPool(role, model, thinking, available, scope, ctx);
+    }
     if (isPanelRole(role)) return setPanel(role, model, thinking, available, scope, ctx);
     const plan = planModelAssignment(model, thinking, available);
     if (plan.kind === "rejected") return plan.message;
@@ -339,13 +432,80 @@ export default function (pi: ExtensionAPI) {
         ? " This project is not trusted, so Pi ignores the file until you trust it, and the status report still shows the earlier value."
         : "";
     try {
-      if (state) state = { ...state, config: { ...state.config, models: loadConfig(ctx).models } };
+      const fresh = loadConfig(ctx);
+      savedFilter = fresh.modelFilter;
+      configError = undefined;
+      if (state) state = { ...state, config: { ...state.config, models: fresh.models, modelFilter: fresh.modelFilter } };
     } catch (error) {
-      return `${untrusted} The write succeeded, but the session view was not refreshed: ${(error as Error).message}`;
+      try {
+        savedFilter = loadConfig(ctx, true).modelFilter;
+        configError = undefined;
+      } catch (filterError) {
+        configError = (filterError as Error).message;
+      }
+      return `${untrusted} The write succeeded, but the model role view was not refreshed: ${(error as Error).message}`;
     }
     return untrusted;
   }
 
+  function setPool(
+    role: string,
+    entries: readonly string[],
+    thinking: string | undefined,
+    available: readonly { id: string; reasoning?: boolean }[],
+    scope: "user" | "project",
+    ctx: ExtensionContext,
+  ): string {
+    const plan = planPoolAssignment(entries, thinking, available);
+    if (plan.kind === "rejected") return plan.message;
+    const path = configPath(scope, ctx);
+    const stored = readConfigFile(path)?.values.models;
+    const models = typeof stored === "object" && stored !== null && !Array.isArray(stored) ? { ...stored } : {};
+    models[role] = plan.value;
+    updateConfigFile(path, { models });
+    const note = refreshModels(scope, ctx);
+    const listed = (typeof plan.value === "string" ? [plan.value] : plan.value).map((entry) => `\`${entry}\``).join(", ");
+    return typeof plan.value === "string"
+      ? `Role \`${role}\` now uses ${listed}. A pool of one is written as a plain model. Written to ${path}.${note}`
+      : `Role \`${role}\` now has a pool of ${plan.value.length} models: ${listed}. Each delegation picks one model the filter allows. Written to ${path}.${note}`;
+  }
+
+  function setFilter(
+    params: { include?: string[]; exclude?: string[]; clear?: boolean },
+    scope: "session" | "user" | "project",
+    ctx: ExtensionContext,
+  ): string {
+    const setting = params.include !== undefined || params.exclude !== undefined;
+    if (params.clear && setting) return "set_filter takes either `clear: true` or `include` and `exclude`, not both.";
+    if (!params.clear && !setting) {
+      return "set_filter needs `include`, `exclude`, or `clear: true`. Empty lists set an unrestricted filter at that scope.";
+    }
+    let filter: ModelFilter | undefined;
+    if (setting) {
+      const raw: Record<string, unknown> = {};
+      if (params.include !== undefined) raw.include = params.include;
+      if (params.exclude !== undefined) raw.exclude = params.exclude;
+      const parsed = parseModelFilter(raw);
+      if ("problem" in parsed) return parsed.problem;
+      filter = parsed.filter;
+    }
+    if (scope === "session") {
+      sessionFilter = filter;
+      pi.appendEntry(FILTER_ENTRY_TYPE, filter ? { filter } : { cleared: true });
+      const origin = activeFilter(sessionFilter, savedFilter);
+      return `${filter ? "This session's model filter is set" : "This session's model filter is cleared"}. Filter in force: ${describeOrigin(origin)}. It applies to every \`delegate_task\` and \`subagent\` call in this session, and is not saved to a config file.`;
+    }
+    const path = configPath(scope, ctx);
+    updateConfigFile(path, { modelFilter: filter });
+    const note = refreshModels(scope, ctx);
+    const origin = activeFilter(sessionFilter, savedFilter);
+    const shadowed =
+      sessionFilter !== undefined
+        ? " This session's own filter still wins over the saved one. Clear it with `set_filter`, `clear: true`, and `scope: \"session\"` to use the saved filter here."
+        : "";
+    return `${filter ? "Saved model filter" : "Removed the saved model filter"} in ${path}.${note}${shadowed} Filter in force: ${describeOrigin(origin)}.`;
+  }
+
   function setPanel(
     role: string,
     model: string,
@@ -442,7 +602,24 @@ function startupNamespace(): string {
   }
 }
 
-function loadConfig(ctx: ExtensionContext): AdapterConfig {
+const SESSION_SCOPE_ONLY_FILTER =
+  "Only `set_filter` takes `scope: \"session\"`. `set_model` and `set_source` write a config file, so pass `scope: \"user\"` or `scope: \"project\"`.";
+
+function parentModelOf(ctx: ExtensionContext): string | undefined {
+  return ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+}
+
+/** A requested model as its registry `provider/id`. A bare id counts only when exactly one model has it. */
+function resolveRegistryModel(ctx: ExtensionContext, model: string): string | undefined {
+  const ids = ctx.modelRegistry.getAvailable().map((candidate) => ({ full: `${candidate.provider}/${candidate.id}`, id: candidate.id }));
+  const exact = ids.find((candidate) => candidate.full === model);
+  if (exact) return exact.full;
+  if (model.includes("/")) return undefined;
+  const bare = ids.filter((candidate) => candidate.id === model);
+  return bare.length === 1 ? bare[0]?.full : undefined;
+}
+
+function loadConfig(ctx: ExtensionContext, filterOnly = false): AdapterConfig {
   const layers: ConfigLayer[] = [];
   const global = readConfigFile(userConfigPath());
   if (global) layers.push(global);
@@ -452,8 +629,8 @@ function loadConfig(ctx: ExtensionContext): AdapterConfig {
     // without desynchronizing `/<ns>-status` from the generated `<ns>-*` skills.
     if (project) layers.push({ ...project, values: { ...project.values, namespace: undefined } });
   }
-  layers.push(environmentLayer(process.env));
-  return mergeConfig(layers);
+  layers.push(environmentLayer(filterOnly ? { ...process.env, PISTACK_MODELS: undefined } : process.env));
+  return mergeConfig(filterOnly ? layers.map((layer) => ({ ...layer, values: { modelFilter: layer.values.modelFilter } })) : layers);
 }
 
 function configPath(scope: "user" | "project", ctx: ExtensionContext): string {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pstack-adapter",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Run Cursor's official pstack plugin inside Pi from an unmodified upstream checkout",
   "type": "module",
   "license": "MIT",