pi-pstack-adapter 0.9.0 → 0.11.0

package/src/registry.ts

@@ -7,7 +7,7 @@ import type { CapabilityId, RegistryEntry, SupportTier } from "./types.ts";
  */
 export const SKILL_REGISTRY: Readonly<Record<string, RegistryEntry>> = {
   "architect": { tier: "dependency-gated", capabilities: ["delegation"], executables: [], note: "Phase B delegates to arena runners, so it cannot run without parallel subagents." },
-  "arena": { tier: "adapted", capabilities: ["delegation"], executables: ["git"], note: "The whole skill is spawning N candidate subagents plus a judge. Since pstack 0.15.36 the judge must come from a model family other than the parent's. The adapter maps the cross-judge pool to the `arena-cross-judge-pool` panel role, which uses `judgment`, then `general` while unset, so when the parent knows its model, the judge runs only when one of its entries is on another family. The status report and `check` warn when that pool is on one model. Otherwise arena skips the judge, picks the base alone, and says so. When the parent does not know its model, arena tries the pool in order anyway and says the family check did not run. Verified end to end in Pi on Linux at pstack 0.15.36 with pi-subagents: two candidates on the `judgment` and `general` roles, then a judge from the family other than the parent's, which scored them. The parent picked a base, took the fixes for two bugs from the other candidate, fixed a third that both shared, and finished with passing tests. It left the candidate worktrees for comparison." },
+  "arena": { tier: "adapted", capabilities: ["delegation"], executables: ["git"], note: "The whole skill is spawning N candidate subagents plus a judge. Since pstack 0.15.36 the judge must come from a model family other than the parent's, and since pstack 0.15.42 from another vendor, where Fable and the other Claude models are one vendor. Its default runners and pool are now one Fable, one Opus, and one Gemini model. The adapter maps the cross-judge pool to the `arena-cross-judge-pool` panel role, which uses `judgment`, then `general` while unset, so when the parent knows its model, the judge comes from the first pool entry from another vendor. When no entry qualifies, arena tries `judgment`, then `general`, and only when neither is from another vendor does it skip the judge, pick the base alone, and say so. The status report and `check` warn when that pool is on one model. When the parent does not know its model, arena tries the pool in order anyway and says the vendor check did not run. Verified end to end in Pi on Linux at pstack 0.15.36 with pi-subagents: two candidates on the `judgment` and `general` roles, then a judge from the family other than the parent's, which scored them. The parent picked a base, took the fixes for two bugs from the other candidate, fixed a third that both shared, and finished with passing tests. It left the candidate worktrees for comparison. The pstack 0.15.42 vendor rule has not run in Pi." },
   "automate-me": { tier: "experimental", capabilities: ["delegation", "structured-question"], executables: ["git", "gh"], note: "Its mining step reads this workspace's transcripts. The host mapping points it at this workspace's Pi session files, which use a different format. Verified end to end in Pi on Linux at pstack 0.15.36: it read only this workspace's sessions, told the parent chat from its subagents' files, found no stated preference there, and changed nothing. The built-in create-skill skill it drafts with has no Pi equivalent, and that step has not run in Pi." },
   "benchmark-checklist": { tier: "dependency-gated", capabilities: [], executables: ["uptime", "nproc"], note: "Its setup step checks load with `uptime` and cores with `nproc`. macOS has no `nproc` without GNU coreutils, and Git Bash on Windows has no `uptime`." },
   "blast-radius": { tier: "dependency-gated", capabilities: [], executables: ["git", "gh"], note: "Needs git and gh to read the diff, commits, and PR before any analysis." },
@@ -16,7 +16,7 @@ export const SKILL_REGISTRY: Readonly<Record<string, RegistryEntry>> = {
   "create-formal-verification-skill": { tier: "adapted", capabilities: [], executables: [], note: "Manual invocation only; no delegation. It installs or runs the verification tool it chooses and temporarily breaks product code to prove the check. Generated skills belong under `.pi/skills/` in Pi. Verified on a Windows Node finite-state fixture; other toolchains need their own prerequisites. Since pstack 0.15.32, a generated TLA+ check tells the next agent to read its results with statechart, which has its own prerequisites." },
   "create-verification-skill": { tier: "adapted", capabilities: [], executables: [], note: "Only the generated skill's output path needs remapping to Pi's skill directory." },
   "figure-it-out": { tier: "dependency-gated", capabilities: ["delegation"], executables: [], note: "Phase B fan-out and the architect/arena routing require parallel subagents." },
-  "how": { tier: "dependency-gated", capabilities: ["delegation"], executables: [], note: "Every path spawns explorer or explainer subagents; nothing runs inline." },
+  "how": { tier: "dependency-gated", capabilities: ["delegation"], executables: [], note: "Since pstack 0.15.42 it spawns one read-only subagent that explores and explains in one pass, and nothing runs inline. That path has not run in Pi." },
   "in-your-own-words": { tier: "native", capabilities: [], executables: [] },
   "interrogate": { tier: "adapted", capabilities: ["delegation"], executables: ["git"], note: "Multi-model adversarial review is entirely one subagent per configured model. Since pstack 0.15.36 it picks adversaries the way arena picks runners, from the `interrogate reviewers` line, and gives each one its own worktree with the scope's uncommitted changes. Each adversary must prove a finding with a run, and the skill keeps only findings whose command it reruns and sees fail. It reports findings and applies no fixes, but adversaries write and run repro commands, and the skill reruns them, all with your permissions. A worktree is not a sandbox, so read each repro before it reruns, especially on code you do not trust. The rubric, the lead's judgment, and the code-quality lens are gone. Verified end to end in Pi on Linux at pstack 0.15.36 with pi-subagents: two adversaries on the `judgment` and `general` roles, from two model families, each in its own worktree, proved the same two real bugs, and the skill reran both repros before it reported them. It left the adversary worktrees in the temporary folder and named the commands that remove them." },
   "ketchup": { tier: "adapted", capabilities: [], executables: [], note: "Read-only. Pi has no `/visualize` skill or image generation, so its visuals are Mermaid diagrams and screenshots that already exist. It checks PR and CI state only for work the chat touched." },
@@ -26,7 +26,7 @@ export const SKILL_REGISTRY: Readonly<Record<string, RegistryEntry>> = {
   "make-bot-ui": { tier: "unsupported", capabilities: [], executables: ["curl", "tailscale", "sudo"], note: "Built entirely on Cursor Automations webhook routines and the secret-request card." },
   "no-comments": { tier: "dependency-gated", capabilities: ["delegation"], executables: ["git"], note: "Step 1 must spawn the comment-sicko agent; the skill only triages its report." },
   "poteto-help": { tier: "experimental", capabilities: [], executables: [], note: "Its answers describe Cursor setup, the slash menu, and Custom Modes. A request for work runs poteto-mode, which is experimental. It asks a multiple-choice question only when the need is unclear. Its README and guide links resolve under the status report's plugin directory." },
-  "poteto-mode": { tier: "experimental", capabilities: ["delegation", "structured-question"], executables: ["git", "gh"], note: "Sticky-mode hosting plus references to Cursor built-in and plugin skills only partially map to Pi. Since pstack 0.15.36 the Orchestrate playbook calls no scripts, because the `orch` helpers are gone, and watches PRs through event subscriptions only when the harness has them. Pi has none. Its Project tracker and Project store, and forking a worker with its built state, have no Pi equivalent; the host mapping says what to do instead. Verified end to end in Pi on Linux at pstack 0.15.36 with pi-subagents and a question tool: Orchestrate ran a two-unit program in a linked worktree, with an owner per unit on its own branch and worktree, a verifier from another model family at the owner's head, and local merges. It kept the tracker and store in a folder it added to the exclude file Git resolved for the worktree, and handed state to new agents instead of messaging old ones. Its other playbooks and sticky mode were not rerun." },
+  "poteto-mode": { tier: "experimental", capabilities: ["delegation", "structured-question"], executables: ["git", "gh"], note: "Sticky-mode hosting plus references to Cursor built-in and plugin skills only partially map to Pi. Since pstack 0.15.36 the Orchestrate playbook calls no scripts, because the `orch` helpers are gone, and watches PRs through event subscriptions only when the harness has them. Pi standalone has none; a T3 Code host can provide them when it exposes `mcp__t3-code__watch_pull_request`. This is a host capability, not a guarantee of either delegation backend. Its Project tracker and Project store, and forking a worker with its built state, have no Pi equivalent; the host mapping says what to do instead. Verified end to end in Pi on Linux at pstack 0.15.36 with pi-subagents and a question tool: Orchestrate ran a two-unit program in a linked worktree, with an owner per unit on its own branch and worktree, a verifier from another model family at the owner's head, and local merges. It kept the tracker and store in a folder it added to the exclude file Git resolved for the worktree, and handed state to new agents instead of messaging old ones. Its other playbooks and sticky mode were not rerun. Since pstack 0.15.42 it tells the user to rerun setup when the model rule has no `# defaults: 2` line. The host mapping says that check does not apply to the adapter configuration." },
   "principle-attack-the-premise": { tier: "native", capabilities: [], executables: [] },
   "principle-boundary-discipline": { tier: "native", capabilities: [], executables: [] },
   "principle-build-the-lever": { tier: "native", capabilities: [], executables: [] },
@@ -51,19 +51,19 @@ export const SKILL_REGISTRY: Readonly<Record<string, RegistryEntry>> = {
   "principle-subtract-before-you-add": { tier: "native", capabilities: [], executables: [] },
   "principle-test-behavior-not-implementation": { tier: "native", capabilities: [], executables: [] },
   "principle-type-system-discipline": { tier: "native", capabilities: [], executables: [] },
-  "recall": { tier: "dependency-gated", capabilities: ["delegation"], executables: ["git", "gh"], note: "Its core corpus is Cursor's on-disk transcript JSONL. The host mapping points it at this workspace's Pi session files instead. Verified end to end in Pi on Linux at pstack 0.15.36: in a fresh session it found the two earlier chats in the folder that holds `$PI_SESSION_FILE`, read their user messages, checked their claims against git and the code, and rebuilt the threads, problems, and next move. With two chats to read, it read them itself, so it did not fan out to subagents, and that step has not run in Pi. A run before the host mapping said to start from `$PI_SESSION_FILE` looked in the default folder instead, which a custom `PI_CODING_AGENT_DIR` had moved, and found nothing." },
+  "recall": { tier: "dependency-gated", capabilities: ["delegation"], executables: ["git", "gh"], note: "Its core corpus is Cursor's on-disk transcript JSONL. The host mapping points it at this workspace's Pi session files instead. Verified end to end in Pi on Linux at pstack 0.15.36: in a fresh session it found the two earlier chats in the folder that holds `$PI_SESSION_FILE`, read their user messages, checked their claims against git and the code, and rebuilt the threads, problems, and next move. With two chats to read, it read them itself, so it did not fan out to subagents, and that step has not run in Pi. A run before the host mapping said to start from `$PI_SESSION_FILE` looked in the default folder instead, which a custom `PI_CODING_AGENT_DIR` had moved, and found nothing. Since pstack 0.15.42 its shared-record sweep spawns one investigator per source itself instead of reusing why's investigators, and that step has not run in Pi." },
   "reflect": { tier: "experimental", capabilities: ["delegation"], executables: [], note: "Its reviewers read the active transcript, and the host mapping points them at the current Pi session file. Verified end to end in Pi on Linux at pstack 0.15.36 with pi-subagents: three reviewers on two model families and a synthesizer read the session file, and the run found a regression the earlier review missed. When told to apply two edits, it copied the upstream skill from the plugin directory to a Pi skill location under a new name and edited only the copy. Its create-skill routing for a new skill is Cursor-specific and has not run in Pi. It never opens a PR or pushes." },
   "setup-pstack": { tier: "native", capabilities: [], executables: [], rename: "setup", replacement: "setup.md", note: "The upstream body only writes a Cursor .mdc rule, so the adapter replaces it with a Pi setup workflow." },
-  "sharpen": { tier: "native", capabilities: [], executables: [], note: "Verified end to end in Pi on Linux at pstack 0.15.36: it handed back four short sections and a rewritten prompt for a vague gateway task, left the decisions that were the user's open, and did not start the task. Since pstack 0.15.29 it hands back a rewritten prompt and does not do the task. Its body is prompt-only, with no tool, delegation, or executable, and it runs only when you type it." },
+  "sharpen": { tier: "native", capabilities: [], executables: [], note: "Verified end to end in Pi on Linux at pstack 0.15.36: it handed back four short sections and a rewritten prompt for a vague gateway task, left the decisions that were the user's open, and did not start the task. Since pstack 0.15.29 it hands back a rewritten prompt and does not do the task. Its body is prompt-only, with no tool, delegation, or executable, and it runs only when you type it. Since pstack 0.15.42 the rewritten prompt asks the agent to prototype any choice an experiment can settle and leaves only product or preference choices to the user. That wording has not been rerun in Pi." },
   "show-me-your-work": { tier: "adapted", capabilities: ["delegation"], executables: [], note: "The mandatory cross-model review of the trail requires spawning a different-family subagent. Verified end to end in Pi on Linux at pstack 0.15.36 with pi-subagents: it kept a decision log the repository ignores, and its reviewer on another model family read the parent's Pi session file and checked each row against it. Its own scripts ran unchanged." },
-  "statechart": { tier: "experimental", capabilities: [], executables: ["node", "sh", "dirname", "sed"], note: "Lowered from dependency-gated at pstack 0.15.34, because its new scripts crash on native Windows, a certified platform. There, the launcher starts `/bin/sh` by that path to stop TLC's process group, Node cannot start it even when `sh` is on PATH, and with no error handler the run exits 1 with `spawn /bin/sh ENOENT`. It writes no output and leaves an empty hidden staging folder beside the output folder and an empty `statechart-` folder in the temporary folder, so delete those by hand. `/pistack-check` still clears it there, because the gates are found. Use it from Linux, macOS, or WSL. Verified end to end on a Linux checkout fixture at pstack 0.15.34, and again at pstack 0.15.36, where it found the uncapped refill in a token bucket as the shortest path to a broken rule. The Windows end-to-end evidence from pstack 0.15.32 and 0.15.30 describes the scripts it replaced. Manual invocation only; no delegation or structured question. `scripts/statechart` is a POSIX `sh` launcher for TypeScript scripts, and it runs `dirname` and `sed` on every start. It runs the scripts under Node 22.18 to 22.x or Node 23.6 or later, then Bun 1.1.5 or later, then Deno 2.0 or later, and exits with code 127 when none is found. The prerequisite check gates on `node` but cannot check its version. The launcher does: with only an older Node on PATH, it names the versions it needs and exits 127. The command checks a TLA+ spec with TLC and writes `report.md` and TLC output to a new or empty `--out` folder, `SPEC-chart` beside the spec by default, and refuses a folder that is not empty. It also writes `chart.mmd`, except when TLC finds more than 500 states and no rule breaks. It stages its work in a hidden folder beside the output folder and in the system temporary folder, and deletes both. TLC runs from `TLA2TOOLS`, the path to a downloaded `tla2tools.jar`, with the binary in `JAVA` or `java` from PATH. Without `TLA2TOOLS`, it uses TLC 1.7.4 and Java temurin-25 from `mise`, and installs whichever is missing with `mise`, which needs the network. `JAVA` then changes only the binary that runs TLC, and does not skip the `mise` lookup or install of Java. Either `mise` or `TLA2TOOLS` with Java works, so neither is gated, and the script names what is missing when neither is set up. It imports the `--view` module as JavaScript with full process permissions, so review an existing view before you run it. Since pstack 0.15.34 the scripts render no images and do not run `npm`. For an image, the body has the agent install `pele@1.9.0` with `npm` once, outside the repository, which needs `npm` and the network, and render SVG with it. The body does not ask for `--ignore-scripts`, so pass it, and rendering still imports Pele with full process permissions. Run it in a scratch folder outside the repository. Git for Windows bundles `sh`, `dirname`, and `sed`, but not `node`, `mise`, or Java." },
+  "statechart": { tier: "experimental", capabilities: [], executables: ["node", "sh", "dirname", "sed"], note: "Lowered from dependency-gated at pstack 0.15.34, because its new scripts crash on native Windows, a certified platform. There, the launcher starts `/bin/sh` by that path to stop TLC's process group, Node cannot start it even when `sh` is on PATH, and with no error handler the run exits 1 with `spawn /bin/sh ENOENT`. It writes no output and leaves an empty hidden staging folder beside the output folder and an empty `statechart-` folder in the temporary folder, so delete those by hand. `/pistack-check` still clears it there, because the gates are found. Use it from Linux, macOS, or WSL. Verified end to end on a Linux checkout fixture at pstack 0.15.34, and again at pstack 0.15.36, where it found the uncapped refill in a token bucket as the shortest path to a broken rule. The Windows end-to-end evidence from pstack 0.15.32 and 0.15.30 describes the scripts it replaced. Manual invocation only; no delegation or structured question. `scripts/statechart` is a POSIX `sh` launcher for TypeScript scripts, and it runs `dirname` and `sed` on every start. It runs the scripts under Node 22.18 to 22.x or Node 23.6 or later, then Bun 1.1.5 or later, then Deno 2.0 or later, and exits with code 127 when none is found. The prerequisite check gates on `node` but cannot check its version. The launcher does: with only an older Node on PATH, it names the versions it needs and exits 127. The command checks a TLA+ spec with TLC and writes `report.md` and TLC output to a new or empty `--out` folder, `SPEC-chart` beside the spec by default, and refuses a folder that is not empty. It also writes `chart.mmd`, except when TLC finds more than 500 states and no rule breaks. It stages its work in a hidden folder beside the output folder and in the system temporary folder, and deletes both. TLC runs from `TLA2TOOLS`, the path to a downloaded `tla2tools.jar`, with the binary in `JAVA` or `java` from PATH. Without `TLA2TOOLS`, it uses TLC 1.7.4 and Java temurin-25 from `mise`, and installs whichever is missing with `mise`, which needs the network. `JAVA` then changes only the binary that runs TLC, and does not skip the `mise` lookup or install of Java. Either `mise` or `TLA2TOOLS` with Java works, so neither is gated, and the script names what is missing when neither is set up. It imports the `--view` module as JavaScript with full process permissions, so review an existing view before you run it. Since pstack 0.15.34 the scripts render no images and do not run `npm`. For an image, the body has the agent install `pele@1.9.0` with `npm` once, outside the repository, which needs `npm` and the network, and render SVG with it. The body does not ask for `--ignore-scripts`, so pass it, and rendering still imports Pele with full process permissions. Run it in a scratch folder outside the repository. Git for Windows bundles `sh`, `dirname`, and `sed`, but not `node`, `mise`, or Java. At pstack 0.15.42 the Mermaid backend can draw the edges into a nested state as one edge into its parent plus start edges inside it, and a SANY parse failure reruns SANY to print its errors. Those script changes add no executable, leave the `/bin/sh` launcher unchanged, and have not run in Pi." },
   "swarm": { tier: "experimental", capabilities: ["delegation"], executables: [], note: "Cloud background workers and cloud_base_branch have no Pi mapping; only local fan-out approximates it." },
   "tdd": { tier: "native", capabilities: [], executables: [] },
-  "teach": { tier: "dependency-gated", capabilities: ["delegation"], executables: [], note: "It runs the how and why skills, both of which need subagents." },
+  "teach": { tier: "dependency-gated", capabilities: ["delegation"], executables: [], note: "It runs the how skill, which needs a subagent, and the why skill, which since pstack 0.15.42 runs inline and needs git and gh. Check why's prerequisites too." },
   "technical-writing": { tier: "native", capabilities: [], executables: [] },
   "typescript-best-practices": { tier: "native", capabilities: [], executables: [] },
   "unslop": { tier: "native", capabilities: [], executables: [] },
-  "why": { tier: "dependency-gated", capabilities: ["delegation"], executables: ["git", "gh"], note: "Default posture spawns one investigator subagent per evidence category plus a synthesizer." },
+  "why": { tier: "dependency-gated", capabilities: [], executables: ["git", "gh"], note: "Since pstack 0.15.42 it spawns no subagents. It answers inline from the commits and PR discussions behind the target, and from other sources when that trail is thin, so it needs git, and gh for the PR discussions. The inline path has not run in Pi." },
 };
 
 /** Adapter-owned skills with no upstream counterpart. Keyed by unprefixed generated name. */
@@ -113,7 +113,7 @@ export const MODEL_ROLES: readonly string[] = [
 
 /**
  * Upstream's panel lines, such as `arena runners`, hold a list of models with one seat per entry.
- * Upstream defaults each to two model families. A panel left unset here uses the roles in
+ * Upstream defaults each to several model families from two vendors. A panel left unset here uses the roles in
  * `PANEL_DEFAULT_ROLES`, so it spans two families only when those roles do.
  */
 export const PANEL_ROLES: readonly string[] = [

package/src/route.ts

@@ -0,0 +1,318 @@
+import {
+  type AdapterConfig,
+  type ModelSpec,
+  type ThinkingLevel,
+  THINKING_LEVELS,
+  isThinkingLevel,
+  isValidModelSpec,
+  isValidRole,
+  joinModelSpec,
+  splitModelSpec,
+} from "./config.ts";
+import { SUBAGENT_TOOL, T3_DELEGATE_TOOL } from "./delegation.ts";
+import { safeEcho } from "./echo.ts";
+import type { ModelFilter } from "./filter.ts";
+import { resolveRole } from "./pools.ts";
+import { MODEL_ROLES, PANEL_DEFAULT_ROLES, isPanelRole } from "./registry.ts";
+
+/** A model string with this prefix names a pstack role, and the adapter picks the model. */
+export const ROLE_REFERENCE_PREFIX = "pstack:";
+
+/**
+ * A delegation's model string. `pstack:<role>` picks by the role's ranking, `pstack:<role>@<model>`
+ * overrides it, and either may end in `:<level>` to lower the thinking level. Any other string is a
+ * concrete model, which only the model filter checks.
+ */
+export type ModelRequest =
+  | { readonly kind: "concrete" }
+  | { readonly kind: "role"; readonly text: string; readonly role: string; readonly override?: string; readonly thinking?: ThinkingLevel }
+  | { readonly kind: "invalid"; readonly text: string; readonly problem: string };
+
+export type RoleReference = Extract<ModelRequest, { kind: "role" }>;
+
+export function parseModelRequest(value: unknown): ModelRequest {
+  if (typeof value !== "string") return { kind: "concrete" };
+  const text = value.trim();
+  if (!text.startsWith(ROLE_REFERENCE_PREFIX)) return { kind: "concrete" };
+  const { model: body, thinking } = splitModelSpec(text);
+  const rest = body.slice(ROLE_REFERENCE_PREFIX.length);
+  const at = rest.indexOf("@");
+  const role = at < 0 ? rest : rest.slice(0, at);
+  const override = at < 0 ? undefined : rest.slice(at + 1);
+  const shape = "Write `pstack:<role>`, optionally followed by `@<provider/model>` and then `:<level>`, for example `pstack:feature` or `pstack:feature@provider/model:high`.";
+  if (!isValidRole(role)) return { kind: "invalid", text, problem: `it names no valid role. ${shape}` };
+  if (override !== undefined && (override === "" || !isValidModelSpec(override) || splitModelSpec(override).thinking !== undefined)) {
+    return { kind: "invalid", text, problem: `its override after \`@\` is not one \`provider/model\` id. ${shape}` };
+  }
+  return { kind: "role", text, role, ...(override !== undefined ? { override } : {}), ...(thinking !== undefined ? { thinking } : {}) };
+}
+
+/**
+ * What a pick strategy sees. `choices` holds only the models the filter allows, in ranked order,
+ * and `task` is the text the child receives.
+ */
+export interface PickRequest {
+  readonly role: string;
+  readonly choices: readonly ModelSpec[];
+  readonly task: string;
+}
+
+/**
+ * The seam for choosing a pool model. It returns an index into `request.choices`; ranked takes the
+ * first. It may return a promise, so a strategy that asks a service can replace it.
+ */
+export function pickModel(_request: PickRequest): number | Promise<number> {
+  return 0;
+}
+
+/** The choice a pick returned, or undefined when the index is not one of the choices. */
+export function validatePick(index: number, choices: readonly ModelSpec[]): ModelSpec | undefined {
+  return Number.isInteger(index) && index >= 0 && index < choices.length ? choices[index] : undefined;
+}
+
+/**
+ * The thinking level a child runs at. A requested level can only lower the configured one, and an
+ * entry with no configured level keeps the backend default whatever was requested.
+ */
+export function effectiveThinking(requested: ThinkingLevel | undefined, configured: ThinkingLevel | undefined): ThinkingLevel | undefined {
+  if (configured === undefined) return undefined;
+  if (requested === undefined) return configured;
+  return lowest(requested, configured);
+}
+
+function lowest(a: ThinkingLevel | undefined, b: ThinkingLevel | undefined): ThinkingLevel | undefined {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  return THINKING_LEVELS.indexOf(a) <= THINKING_LEVELS.indexOf(b) ? a : b;
+}
+
+export interface RouteContext {
+  /** Undefined when the adapter did not start, so no role can be resolved. */
+  readonly config: AdapterConfig | undefined;
+  readonly filter?: ModelFilter;
+  /** `provider/id` of the session's model. */
+  readonly parentModel?: string;
+  /** The session's thinking level, which an inheriting `subagent` child keeps. */
+  readonly parentThinking?: ThinkingLevel;
+  /** Maps a model to its registry `provider/id`, or undefined when Pi does not know it. */
+  readonly resolveModel: (model: string) => string | undefined;
+}
+
+export type RouteDecision =
+  | { readonly kind: "unchanged" }
+  | { readonly kind: "rewrite"; readonly input: Record<string, unknown> }
+  | { readonly kind: "block"; readonly reason: string };
+
+type ChildRoute =
+  | { readonly kind: "model"; readonly spec: ModelSpec }
+  | { readonly kind: "inherit" }
+  | { readonly kind: "block"; readonly reason: string };
+
+const UNCHANGED: RouteDecision = { kind: "unchanged" };
+
+/**
+ * Replaces each role reference in a `delegate_task` or `subagent` call with the model and thinking
+ * the adapter picks. The result is a rewritten copy; concrete models and other tools are unchanged.
+ */
+export async function routeDelegation(toolName: string, input: unknown, context: RouteContext): Promise<RouteDecision> {
+  if (!isRecord(input)) return UNCHANGED;
+  if (toolName === T3_DELEGATE_TOOL) return routeT3(input, context);
+  if (toolName === SUBAGENT_TOOL) return routeSubagent(input, context);
+  return UNCHANGED;
+}
+
+/** Makes `target` hold exactly the keys of `source`, because Pi runs the tool on the object it passed. */
+export function applyRewrite(target: Record<string, unknown>, source: Readonly<Record<string, unknown>>): void {
+  for (const key of Object.keys(target)) if (!Object.hasOwn(source, key)) delete target[key];
+  Object.assign(target, source);
+}
+
+function blockReason(where: string, text: string, problem: string): string {
+  return `Blocked by the pstack adapter: ${where} asks for ${text}, but ${problem} This call was not retried.`;
+}
+
+/** A parsed reference holds only role and model-id characters; anything else is echoed safely. */
+function quoted(request: Exclude<ModelRequest, { kind: "concrete" }>): string {
+  return request.kind === "role" ? `\`${request.text}\`` : safeEcho(request.text);
+}
+
+async function routeReference(reference: RoleReference, where: string, requested: ThinkingLevel | undefined, task: string, context: RouteContext): Promise<ChildRoute> {
+  const { role } = reference;
+  const block = (problem: string): ChildRoute => ({ kind: "block", reason: blockReason(where, quoted(reference), problem) });
+  if (context.config === undefined) {
+    return block(`the adapter did not start, so it cannot resolve role \`${role}\`. Run \`pstack_adapter\` with \`action: "status"\` to see why, fix the problem, and reload.`);
+  }
+  if (isPanelRole(role)) {
+    return block(
+      `\`${role}\` is a panel role, which holds one seat per entry rather than one model. Start one child per seat as the \`panel roles\` table shows: an unset panel's seats are ${PANEL_DEFAULT_ROLES.map((seat) => `\`pstack:${seat}\``).join(" and ")}, and a configured seat names its own model.`,
+    );
+  }
+  if (!MODEL_ROLES.includes(role) && !Object.hasOwn(context.config.models, role)) {
+    return block(`\`${role}\` is not a pstack role. Use a role from the \`model roles\` table of the \`pstack_adapter\` status report, or \`pstack:general\` when no other role fits.`);
+  }
+  const resolution = resolveRole(context.config, role, { filter: context.filter, parentModel: context.parentModel });
+  switch (resolution.kind) {
+    case "blocked":
+      return block(`role \`${role}\` is blocked: ${resolution.reason}. Do not delegate this role's work, and do not move it to \`general\` or your own model. Tell the user which role is blocked and why.`);
+    case "inherit":
+      if (reference.override !== undefined) {
+        return block(`role \`${role}\` has no pool to override, because it inherits the parent's model. Pass \`pstack:${role}\` without \`@\`.`);
+      }
+      return { kind: "inherit" };
+    case "pool": {
+      const choices = resolution.choices.filter((choice) => choice.eligible).map((choice) => choice.spec);
+      let chosen: ModelSpec | undefined;
+      if (reference.override !== undefined) {
+        const allowed = `Its allowed entries are ${choices.map((choice) => `\`${choice.model}\``).join(", ")}. Override with one of them, or pass \`pstack:${role}\` for the ranked pick.`;
+        const wanted = context.resolveModel(reference.override);
+        if (wanted === undefined) return block(`this Pi installation does not know \`${reference.override}\`. ${allowed}`);
+        chosen = choices.find((choice) => (context.resolveModel(choice.model) ?? choice.model) === wanted);
+        if (chosen === undefined) return block(`\`${wanted}\` is not an entry of role \`${role}\`'s pool that the model filter allows. ${allowed}`);
+      } else {
+        const index = await pickModel({ role, choices, task });
+        chosen = validatePick(index, choices);
+        if (chosen === undefined) {
+          return block(`the adapter's model pick for role \`${role}\` returned index ${index}, which is not one of its ${choices.length} allowed models. This is an adapter bug; report it to the user.`);
+        }
+      }
+      const thinking = effectiveThinking(requested, chosen.thinking);
+      return { kind: "model", spec: { model: chosen.model, ...(thinking !== undefined ? { thinking } : {}) } };
+    }
+  }
+}
+
+/** A T3 target names a Pi model, so a role reference only works with the `pi` provider. */
+async function routeT3(args: Record<string, unknown>, context: RouteContext): Promise<RouteDecision> {
+  const target = args.target;
+  if (!isRecord(target)) return UNCHANGED;
+  const request = parseModelRequest(target.model);
+  if (request.kind === "concrete") return UNCHANGED;
+  const where = "`delegate_task` `target.model`";
+  if (request.kind === "invalid") return { kind: "block", reason: blockReason(where, quoted(request), request.problem) };
+  const provider = [target.providerInstanceId, target.driverKind].find((value) => value !== undefined && value !== "pi");
+  if (provider !== undefined) {
+    return {
+      kind: "block",
+      reason: blockReason(where, quoted(request), `the target names T3 provider ${safeEcho(provider)}, and a role reference names a Pi model. Use \`providerInstanceId: "pi"\`, or omit it.`),
+    };
+  }
+  const optionLevel = readThinkingOption(target.options);
+  if (optionLevel === "invalid") {
+    return {
+      kind: "block",
+      reason: blockReason(where, quoted(request), `\`target.options.thinking\` is not one of ${THINKING_LEVELS.map((level) => `\`${level}\``).join(", ")}. Lower the level with a \`:<level>\` suffix on the role reference instead.`),
+    };
+  }
+  const task = typeof args.task === "string" ? args.task : "";
+  const requested = lowest(request.thinking, optionLevel);
+  const route = await routeReference(request, where, requested, task, context);
+  if (route.kind === "block") return route;
+  const next = structuredClone(args);
+  const nextTarget = next.target as Record<string, unknown>;
+  if (route.kind === "inherit") {
+    // The provider selector goes too, because it would pick that instance's model instead of the
+    // parent's. Other fields stay for the filter gate to check. Omitted options inherit the parent's.
+    delete nextTarget.model;
+    delete nextTarget.providerInstanceId;
+    delete nextTarget.driverKind;
+    const lowered = requested !== undefined && context.parentThinking !== undefined ? lowest(requested, context.parentThinking) : undefined;
+    const options = writeThinkingOption(nextTarget.options, lowered);
+    if (options === undefined) delete nextTarget.options;
+    else nextTarget.options = options;
+    if (Object.keys(nextTarget).length === 0) delete next.target;
+    return { kind: "rewrite", input: next };
+  }
+  nextTarget.model = route.spec.model;
+  if (nextTarget.providerInstanceId === undefined) nextTarget.providerInstanceId = "pi";
+  // T3 merges given options over the inherited ones and reads empty options as clearing them, so a
+  // backend-default entry sends them empty rather than let the parent's thinking through.
+  nextTarget.options =
+    route.spec.thinking === undefined ? (Array.isArray(nextTarget.options) ? [] : {}) : writeThinkingOption(nextTarget.options, route.spec.thinking);
+  return { kind: "rewrite", input: next };
+}
+
+type OptionEntry = { readonly id?: unknown; readonly value?: unknown };
+
+/** T3 options are an object keyed by option id, or a list of `{ id, value }`. */
+function readThinkingOption(options: unknown): ThinkingLevel | undefined | "invalid" {
+  const value = Array.isArray(options)
+    ? (options as OptionEntry[]).find((entry) => isRecord(entry) && entry.id === "thinking")?.value
+    : isRecord(options)
+      ? options.thinking
+      : undefined;
+  if (value === undefined) return undefined;
+  return typeof value === "string" && isThinkingLevel(value) ? value : "invalid";
+}
+
+function writeThinkingOption(options: unknown, thinking: ThinkingLevel | undefined): unknown {
+  if (Array.isArray(options)) {
+    const rest = (options as OptionEntry[]).filter((entry) => !(isRecord(entry) && entry.id === "thinking"));
+    const next = thinking === undefined ? rest : [...rest, { id: "thinking", value: thinking }];
+    return next.length > 0 ? next : undefined;
+  }
+  const next: Record<string, unknown> = isRecord(options) ? { ...options } : {};
+  if (thinking === undefined) delete next.thinking;
+  else next.thinking = thinking;
+  return Object.keys(next).length > 0 ? next : undefined;
+}
+
+interface ModelSlot {
+  readonly where: string;
+  readonly holder: Record<string, unknown>;
+  readonly task: string;
+}
+
+/** Every place a `subagent` call names a child's model: one agent, a task list, or a chain. */
+function subagentSlots(args: Record<string, unknown>): ModelSlot[] {
+  const topTask = typeof args.task === "string" ? args.task : "";
+  const taskOf = (holder: Record<string, unknown>, fallback: string) => (typeof holder.task === "string" ? holder.task : fallback);
+  const slots: ModelSlot[] = [];
+  if (args.agent !== undefined) {
+    if (args.model !== undefined && args.model !== null) slots.push({ where: "`subagent` `model`", holder: args, task: topTask });
+    else if (isRecord(args.options) && args.options.model !== undefined) slots.push({ where: "`subagent` `options.model`", holder: args.options, task: topTask });
+  }
+  if (Array.isArray(args.tasks)) {
+    args.tasks.forEach((task, index) => {
+      if (isRecord(task)) slots.push({ where: `\`subagent\` tasks[${index}]`, holder: task, task: taskOf(task, topTask) });
+    });
+  }
+  if (Array.isArray(args.chain)) {
+    args.chain.forEach((step, index) => {
+      if (!isRecord(step)) return;
+      const stepTask = taskOf(step, topTask);
+      slots.push({ where: `\`subagent\` chain[${index}]`, holder: step, task: stepTask });
+      if (Array.isArray(step.parallel)) {
+        step.parallel.forEach((task, inner) => {
+          if (isRecord(task)) slots.push({ where: `\`subagent\` chain[${index}].parallel[${inner}]`, holder: task, task: taskOf(task, stepTask) });
+        });
+      }
+    });
+  }
+  return slots;
+}
+
+/** pi-subagents takes `provider/model:level` in each child's `model`. Other actions launch nothing named here. */
+async function routeSubagent(args: Record<string, unknown>, context: RouteContext): Promise<RouteDecision> {
+  if (typeof args.action === "string" && args.action.trim() !== "") return UNCHANGED;
+  const next = structuredClone(args);
+  let changed = false;
+  for (const slot of subagentSlots(next)) {
+    const request = parseModelRequest(slot.holder.model);
+    if (request.kind === "concrete") continue;
+    if (request.kind === "invalid") return { kind: "block", reason: blockReason(slot.where, quoted(request), request.problem) };
+    const route = await routeReference(request, slot.where, request.thinking, slot.task, context);
+    if (route.kind === "block") return route;
+    if (route.kind === "model") slot.holder.model = joinModelSpec(route.spec);
+    else if (context.parentModel !== undefined) {
+      const thinking = context.parentThinking === undefined ? undefined : lowest(request.thinking, context.parentThinking);
+      slot.holder.model = joinModelSpec({ model: context.parentModel, ...(thinking !== undefined ? { thinking } : {}) });
+    }
+    else delete slot.holder.model;
+    changed = true;
+  }
+  return changed ? { kind: "rewrite", input: next } : UNCHANGED;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/status.ts

@@ -176,7 +176,7 @@ function describeSeat(seat: PanelSeat): string {
     case "model":
       return `${describeSpec(seat.spec)}${origin}`;
     case "choice":
-      return `one of ${seat.choices.map(describeSpec).join(" or ")}, picked once for this seat${origin}`;
+      return `ranked ${seat.choices.map(describeSpec).join(", then ")}; as \`pstack:${seat.from}\` it runs once on the first, unless the delegating agent overrides the ranking${origin}`;
     case "blocked":
       return `BLOCKED, ${seat.reason}${origin}`;
   }
@@ -184,14 +184,19 @@ function describeSeat(seat: PanelSeat): string {
 
 const PARENT_MODEL = "the model of the agent that starts the panel";
 
-/** The model a seat runs on, when it is already determined. */
-function seatModel(seat: PanelSeat): string | undefined {
+/**
+ * The model a seat runs on, when it is already determined. A default seat runs as `pstack:<role>`,
+ * so with `ranked` its first choice counts; without it, a seat with several choices is open,
+ * because the delegating agent may override the ranking.
+ */
+function seatModel(seat: PanelSeat, ranked: boolean): string | undefined {
   switch (seat.kind) {
     case "parent":
       return PARENT_MODEL;
     case "model":
       return seat.spec.model;
     case "choice": {
+      if (ranked) return seat.choices[0]?.model;
       const models = new Set(seat.choices.map((choice) => choice.model));
       return models.size === 1 ? [...models][0] : undefined;
     }
@@ -200,10 +205,10 @@ function seatModel(seat: PanelSeat): string | undefined {
   }
 }
 
-function seatModels(seats: readonly PanelSeat[]): Set<string> | undefined {
+function seatModels(seats: readonly PanelSeat[], ranked: boolean): Set<string> | undefined {
   const models = new Set<string>();
   for (const seat of seats) {
-    const model = seatModel(seat);
+    const model = seatModel(seat, ranked);
     if (model !== undefined) models.add(model);
     else if (seat.kind === "choice") return undefined;
   }
@@ -211,13 +216,13 @@ function seatModels(seats: readonly PanelSeat[]): Set<string> | undefined {
 }
 
 /**
- * Upstream's default panels span two model families. A panel whose seats all land on one model
+ * Upstream's default panels span several model families and two vendors. A panel whose seats all land on one model
  * lost that because of configuration, not because no other model exists, so say so where the
  * agent reads it. Families are left to the agent, which knows them better than a prefix list.
  */
 export function panelWarning(panel: ResolvedPanel, config: AdapterConfig, context: ResolutionContext = {}): string | undefined {
   const usable = panel.seats.filter((seat) => seat.kind !== "blocked");
-  const models = seatModels(usable);
+  const models = seatModels(usable, true);
   const pool = panel.role === "arena-cross-judge-pool";
   // Upstream lets a panel line hold one entry on purpose, so only the judge pool warns at one seat.
   if (models === undefined || models.size !== 1 || (usable.length < 2 && !pool)) return undefined;
@@ -226,21 +231,23 @@ export function panelWarning(panel: ResolvedPanel, config: AdapterConfig, contex
   const cause = panel.configured
     ? `its configured entries all name ${named}`
     : `it is unset, and ${PANEL_DEFAULT_ROLES.map((role) => `\`${role}\``).join(" and ")} both resolve to ${named}`;
-  return `Every seat of \`${panel.role}\` runs on ${named}, because ${cause}, ${pool ? poolEffect(panel, config, model, context) : "so the panel has one model and no second family"}. This comes from the adapter configuration, not from which models are available. Run \`/skill:${config.namespace}-setup\` to put this panel on two model families, as upstream's defaults do.`;
+  const ranked = usable.some((seat) => seat.kind === "choice") ? " with the ranked picks, unless the delegating agent overrides the ranking," : ",";
+  return `Every seat of \`${panel.role}\` runs on ${named}${ranked} because ${cause}, ${pool ? poolEffect(panel, config, model, context) : "so the panel has one model and no second family"}. This comes from the adapter configuration, not from which models are available. Run \`/skill:${config.namespace}-setup\` to put this panel on models from two vendors, as upstream's defaults do.`;
 }
 
 /**
- * Arena's judge is never from the session's family. When no pool entry qualifies, upstream tries
+ * Arena's judge is never from the session's vendor, which since pstack 0.15.42 counts Fable and the
+ * other Claude models as one. When no pool entry qualifies, upstream tries
  * its default pool, which here is `judgment`, then `general`, before it skips the judge.
  */
 function poolEffect(panel: ResolvedPanel, config: AdapterConfig, model: string | undefined, context: ResolutionContext): string {
   const fallback = defaultSeats(config, context);
-  const fallbackModels = seatModels(fallback);
+  const fallbackModels = seatModels(fallback, false);
   const lead =
     model === PARENT_MODEL
       ? "and an `inherit` entry never judges, so arena"
-      : `so a session on the family of \`${model}\` gets no judge from the pool, and arena`;
-  const sameFallback = !panel.configured || (fallbackModels?.size === 1 && fallbackModels.has(model ?? PARENT_MODEL));
+      : `so a session on the vendor of \`${model}\` gets no judge from the pool, and arena`;
+  const sameFallback = fallbackModels?.size === 1 && fallbackModels.has(model ?? PARENT_MODEL);
   return sameFallback
     ? `${lead} skips the judge`
     : `${lead} tries its default pool, ${fallback.map(describeSeat).join("; ")}, before it skips the judge`;
@@ -273,7 +280,7 @@ function describeRole(resolution: RoleResolution, role: string): readonly [strin
       const eligible = resolution.choices.filter((choice) => choice.eligible).map((choice) => describeSpec(choice.spec));
       const excluded = resolution.choices.filter((choice) => !choice.eligible).map((choice) => describeSpec(choice.spec));
       const tail = excluded.length > 0 ? `; excluded by the model filter: ${excluded.join(", ")}` : "";
-      return [`pool, pick one of ${eligible.join(", ")}${tail}${via}`, `per choice${via}`];
+      return [`pool, ranked ${eligible.join(", then ")}${tail}${via}`, `per choice${via}`];
     }
   }
 }
@@ -297,7 +304,7 @@ export function renderModelPolicy(config: AdapterConfig, origin: FilterOrigin, p
   }
   if (pools.length > 0) {
     lines.push(
-      `Pools: ${pools.map(([role, resolution]) => `\`${role}\` picks one of ${describeRole(resolution, role)[0].replace(/^pool, pick one of /, "")}`).join("; ")}. For each delegation, pick ONE eligible model from the role's pool by fit. A pool is not a retry list and not a panel: do not start the same task on several of its models, and when a delegation fails, report the failure instead of trying another model.`,
+      `Pools: ${pools.map(([role, resolution]) => `\`${role}\` is ranked ${describeRole(resolution, role)[0].replace(/^pool, ranked /, "")}`).join("; ")}. Delegate a role as \`pstack:<role>\`, and the adapter runs it on the first eligible model in the role's ranking. As the delegating agent, you may override the ranking with \`pstack:<role>@<provider/model>\`, naming another eligible model from the pool when the task clearly fits it better; say which model you picked and why. A pool is not a retry list and not a panel: do not start the same task on several of its models, and when a delegation fails, report the failure instead of trying another model.`,
     );
   }
   if (blocked.length > 0) {

package/src/vocabulary.ts

@@ -33,8 +33,9 @@ export const CURSOR_TERMS: readonly CursorTerm[] = [
   { key: "`resume`", pattern: /`resume`/ },
   { key: "`file_attachments`", pattern: /file_attachments/ },
   { key: "`claude-opus-5-5-xhigh`", pattern: /\bclaude-[a-z]+-\d/ },
-  { key: "`grok-4.7-xhigh-fast`", pattern: /\bgrok-\d/ },
+  { key: "`grok-*`", pattern: /\bgrok-\d/ },
   { key: "`gpt-*`", pattern: /\bgpt-\d/ },
+  { key: "`gemini-4-carbon-high`", pattern: /\bgemini-\d/ },
   { key: "`inherit-parent`", pattern: /inherit-parent/ },
   { key: "`~/.cursor/rules/pstack-models.mdc`", pattern: /pstack-models\.mdc/ },
   { key: "`.cursor/skills/`", pattern: /\.cursor\/skills/ },
@@ -53,6 +54,7 @@ export const CURSOR_TERMS: readonly CursorTerm[] = [
   { key: "Cursor `/loop`", pattern: /(^|[\s(`])\/loop\b/ },
   { key: "a skill under `plugins/cache/`", pattern: /plugins\/cache\// },
   { key: "a Custom Mode", pattern: /Custom Mode/ },
+  { key: "`# defaults: 2`", pattern: /# defaults: \d/ },
 ];
 
 /** One upstream Markdown file, named by its skill and its path inside the skill directory. */