pi-pstack-adapter 0.4.0 → 0.5.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.5.0](https://github.com/elderfo/pi-pstack-adapter/compare/v0.4.0...v0.5.0) (2026-10-15)
+
+
+### Features
+
+* **models:** add a per-role thinking level ([#12](https://github.com/elderfo/pi-pstack-adapter/issues/12)) ([ae99d0c](https://github.com/elderfo/pi-pstack-adapter/commit/ae99d0cb9ab6c516a6847eb47ea44a0b5ec7c141))
+
 ## [0.4.0](https://github.com/elderfo/pi-pstack-adapter/compare/v0.3.0...v0.4.0) (2026-10-14)
 
 

package/README.md

@@ -150,6 +150,20 @@ In a noninteractive session, set roles with `PISTACK_MODELS`:
 PISTACK_MODELS='feature=provider/model,bug-fix=provider/other-model' pi
 ```
 
+Add a thinking level to a role with a `:level` suffix. The levels are `off`, `minimal`, `low`,
+`medium`, `high`, `xhigh`, and `max`:
+
+```bash
+PISTACK_MODELS='feature=provider/model:medium,judgment=provider/other-model:high' pi
+```
+
+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 you leave unset inherits the
+session model and the session thinking level, so a session at high thinking makes every
+inheriting delegate expensive. The `pstack_adapter` tool's `set_model` action takes the same
+level in its `thinking` parameter. A level the model does not offer is clamped by Pi at run time.
+
 ## Run Pi noninteractively
 
 A noninteractive session, such as `pi --print`, cannot answer the download question. To allow
@@ -188,7 +202,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` pairs. |
+| `PISTACK_MODELS` | Assigns models as comma-separated `role=provider/model[:thinking]` pairs. |
 | `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.4.0
+0.5.0

package/adapter-skills/setup.md

@@ -27,6 +27,13 @@ Roles used by pstack workflows.
 The status report lists the same roles, so read it back rather than trusting this table if the
 adapter has been upgraded.
 
+Each role also has a thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or
+`max`. Upstream pstack calls this a reasoning budget and encodes it in the model slug. A role with
+no thinking level passes none, so the delegation backend applies its own default. A role left on
+`inherit` uses the parent session's model and thinking level, so a parent at high thinking makes
+every inheriting child expensive. Model choice often affects cost more than thinking level does,
+so consider a cheaper model for the bulk roles as well.
+
 Steps.
 
 1. Call the adapter tool with `action: "models"` to list the provider and model ids this Pi
@@ -34,13 +41,40 @@ Steps.
 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.
-3. For each answered role, call the adapter tool with `action: "set_model"`, the role, and the
-   chosen `provider/model` id. Pass `scope: "project"` when the user wants the choice to apply
-   only to this repository.
-4. Read back `action: "status"` and show the user what was written.
+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
+   parent session's level. Ask one single-select question first. Put the whole choice in each option
+   title so the user can pick without opening anything else, for example "Balanced: code roles
+   medium, judgment high, strongest-judgment xhigh (suggested)".
+
+   | choice | code roles (`feature`, `refactoring`, `bug-fix`, `perf-issue`, `hillclimb`) | `judgment` | `strongest-judgment` |
+   | --- | --- | --- | --- |
+   | Balanced (suggest this first) | `medium` | `high` | `xhigh` |
+   | Low cost | `low` | `medium` | `high` |
+   | Maximum quality | `high` | `xhigh` | `max` |
+   | Backend default | none | none | none |
+   | Custom | ask once per column, as a single-select of level names | | |
+
+   These are starting points, not measurements. They keep the heaviest reasoning on the roles
+   that make the hardest calls. Offer Custom for a user who wants different levels. Ask once for
+   the code roles, once for `judgment`, and once for `strongest-judgment`. Ask a role on its own
+   only when the user says it should differ from its group. Backend default passes no level and
+   leaves the choice to the delegation backend. A Custom user who wants thinking disabled picks
+   `off`.
+   A model may not offer every level. A level it lacks is clamped when it runs, so say that
+   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.
+5. Read back `action: "status"` and show the user what was written, including the thinking
+   column.
 
 For a scripted environment, set `PISTACK_MODELS` instead, for example
-`PISTACK_MODELS=feature=anthropic/claude-sonnet-4-5,bug-fix=openai/gpt-5`. The environment wins
+`PISTACK_MODELS=feature=anthropic/claude-sonnet-4-5:medium,bug-fix=openai/gpt-5:high`. The
+optional `:level` suffix sets the thinking level. The environment wins
 over both config files, so CI never needs this dialog.
 
 ## Upstream source

package/index.ts

@@ -13,13 +13,20 @@ import {
   type AdapterConfig,
   type ConfigFile,
   type ConfigLayer,
+  THINKING_LEVELS,
   environmentLayer,
+  invalidRoleMessage,
+  isValidModelSpec,
+  isValidRole,
+  joinModelSpec,
   mergeConfig,
+  planModelAssignment,
   readConfigFile,
   trustWarning,
   updateConfigFile,
 } from "./src/config.ts";
 import { generate } from "./src/generate.ts";
+import { safeEcho } from "./src/echo.ts";
 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";
@@ -56,9 +63,8 @@ export default function (pi: ExtensionAPI) {
     startupError = undefined;
     modeActive = modeFromEntries(ctx.sessionManager.getBranch() as never[]);
 
-    const config = loadConfig(ctx);
     try {
-      state = await bringUpUpstream(config, ctx);
+      state = await bringUpUpstream(loadConfig(ctx), ctx);
     } catch (error) {
       startupError = error as Error;
       if (ctx.hasUI) ctx.ui.notify(`pstack adapter: ${(error as Error).message}`, "error");
@@ -135,6 +141,11 @@ 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({ description: "`provider/model` id, or `inherit` to clear the role" })),
+      thinking: Type.Optional(
+        Type.String({
+          description: `Thinking level for \`set_model\`: ${THINKING_LEVELS.join(", ")}. Omit to pass no level, which also clears a level set earlier.`,
+        }),
+      ),
       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`" })),
@@ -195,6 +206,7 @@ export default function (pi: ExtensionAPI) {
       skill?: string;
       role?: string;
       model?: string;
+      thinking?: string;
       repo?: string;
       ref?: string;
       localPath?: string;
@@ -234,7 +246,7 @@ export default function (pi: ExtensionAPI) {
       case "models":
         return renderModels(ctx);
       case "set_model":
-        return setModel(params.role, params.model, params.scope ?? "user", ctx);
+        return setModel(params.role, params.model, params.thinking, params.scope ?? "user", ctx);
       case "set_source":
         return setSource(params, params.scope ?? "user", ctx);
       default:
@@ -254,7 +266,7 @@ export default function (pi: ExtensionAPI) {
       (candidate) => candidate.generatedName === requested || candidate.generatedName === `${prefix}${bare}`,
     );
     if (!skill) {
-      return `No pstack skill named ${JSON.stringify(requested)}. Run the adapter tool with action "status" for the full list.`;
+      return `No pstack skill named ${safeEcho(requested)}. Run the adapter tool with action "status" for the full list.`;
     }
     const resolved = shellState(ctx, pi.getActiveTools());
     // An inactive bash tool or an unresolved shell is already a blocker, so do not spawn anything.
@@ -274,27 +286,36 @@ export default function (pi: ExtensionAPI) {
   function renderModels(ctx: ExtensionContext): string {
     const scoped = ctx.scopedModels ?? [];
     const models = scoped.length > 0 ? scoped.map((entry) => entry.model) : ctx.modelRegistry.getAvailable();
-    const ids = models.map((model) => `${model.provider}/${model.id}`).sort();
+    const ids = models.map((model) => `${model.provider}/${model.id}`).filter(isValidModelSpec).sort();
     if (ids.length === 0) return "No models are available in this Pi installation.";
     return `Available model ids.\n\n${ids.map((id) => `- \`${id}\``).join("\n")}`;
   }
 
-  function setModel(role: string | undefined, model: string | undefined, scope: "user" | "project", ctx: ExtensionContext): string {
+  function setModel(
+    role: string | undefined,
+    model: 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.";
-    const clearing = model.trim().toLowerCase() === "inherit";
-    if (!clearing && !ctx.modelRegistry.getAvailable().some((candidate) => `${candidate.provider}/${candidate.id}` === model)) {
-      return `No model \`${model}\` is available in this Pi installation. Call this tool with action "models" for real ids, or pass "inherit".`;
-    }
+    if (!isValidRole(role)) return invalidRoleMessage(role);
+    const available = ctx.modelRegistry
+      .getAvailable()
+      .map((candidate) => ({ id: `${candidate.provider}/${candidate.id}`, reasoning: candidate.reasoning }));
+    const plan = planModelAssignment(model, thinking, available);
+    if (plan.kind === "rejected") return plan.message;
     const path = configPath(scope, ctx);
-    const current = readConfigFile(path)?.values.models ?? {};
-    const models = { ...current };
-    if (clearing) delete models[role];
-    else models[role] = model;
+    const stored = readConfigFile(path)?.values.models;
+    const models = typeof stored === "object" && stored !== null && !Array.isArray(stored) ? { ...stored } : {};
+    if (plan.kind === "inherit") delete models[role];
+    else models[role] = joinModelSpec(plan.spec);
     updateConfigFile(path, { models });
-    return clearing
-      ? `Role \`${role}\` now inherits the parent session model. Written to ${path}.`
-      : `Role \`${role}\` now uses \`${model}\`. Written to ${path}.`;
+    if (plan.kind === "inherit") return `Role \`${role}\` now inherits the parent session model and thinking. Written to ${path}.`;
+    return plan.spec.thinking === undefined
+      ? `Role \`${role}\` now uses \`${plan.spec.model}\` at the model's default thinking. Written to ${path}.`
+      : `Role \`${role}\` now uses \`${plan.spec.model}\` with thinking \`${plan.spec.thinking}\`. Written to ${path}.`;
   }
 
   async function setSource(

package/package.json

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

package/src/config.ts

@@ -1,6 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, resolve } from "node:path";
 import { CERTIFIED } from "./certified.ts";
+import { safeEcho } from "./echo.ts";
 import { DEFAULT_NAMESPACE, validateNamespace } from "./namespace.ts";
 import { expandHome } from "./paths.ts";
 import { DEFAULT_DELEGATION, DELEGATION_PROVIDERS, isDelegationProvider } from "./delegation.ts";
@@ -66,8 +67,9 @@ export function readConfigFile(path: string): ConfigLayer | undefined {
   let parsed: unknown;
   try {
     parsed = JSON.parse(raw);
-  } catch (error) {
-    throw new Error(`${path} is not valid JSON: ${(error as Error).message}`);
+  } catch {
+    // The parser's message quotes raw file text, which can reach the agent. Say only where to look.
+    throw new Error(`${path} is not valid JSON. Fix the syntax in that file and restart Pi.`);
   }
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
     throw new Error(`${path} must contain a JSON object.`);
@@ -87,7 +89,139 @@ export function updateConfigFile(path: string, patch: ConfigFile): ConfigFile {
   return next;
 }
 
-/** `role=provider/model,role2=provider/model2` */
+/** Thinking levels Pi accepts as a `:level` suffix on a model id. */
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+export function isThinkingLevel(value: string): value is ThinkingLevel {
+  return (THINKING_LEVELS as readonly string[]).includes(value);
+}
+
+export interface ModelSpec {
+  readonly model: string;
+  readonly thinking?: ThinkingLevel;
+}
+
+/**
+ * Splits `provider/model[:thinking]`. Only a known level is a suffix, so a model id that
+ * itself contains a colon, such as `ollama/qwen:7b`, stays whole. Pi parses ids the same way.
+ */
+export function splitModelSpec(spec: string): ModelSpec {
+  const separator = spec.lastIndexOf(":");
+  if (separator > 0) {
+    const suffix = spec.slice(separator + 1).toLowerCase();
+    if (isThinkingLevel(suffix)) return { model: spec.slice(0, separator), thinking: suffix };
+  }
+  return { model: spec };
+}
+
+export function joinModelSpec(spec: ModelSpec): string {
+  return spec.thinking === undefined ? spec.model : `${spec.model}:${spec.thinking}`;
+}
+
+export interface AvailableModel {
+  readonly id: string;
+  readonly reasoning?: boolean;
+}
+
+export type ModelAssignment =
+  | { readonly kind: "inherit" }
+  | { readonly kind: "assign"; readonly spec: ModelSpec }
+  | { readonly kind: "rejected"; readonly message: string };
+
+/** Validates a `set_model` request. `available` holds `provider/id` entries from the registry. */
+export function planModelAssignment(
+  model: string,
+  thinking: string | undefined,
+  available: readonly AvailableModel[],
+): ModelAssignment {
+  if (model.trim().toLowerCase() === "inherit") {
+    if (thinking?.trim()) {
+      return {
+        kind: "rejected",
+        message:
+          "A role that inherits the parent session has no thinking level of its own. Pass a `provider/model` with `thinking`, or drop `thinking`.",
+      };
+    }
+    return { kind: "inherit" };
+  }
+  const whole = model.trim();
+  // A registry id that itself ends in a level word, such as `x/model:low`, wins over a split.
+  const exact = available.some((candidate) => candidate.id === whole);
+  const spec = exact ? { model: whole } : splitModelSpec(whole);
+  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(", ")}.`,
+    };
+  }
+  if (requested !== undefined && spec.thinking !== undefined && spec.thinking !== requested) {
+    return {
+      kind: "rejected",
+      message: `\`model\` names thinking \`${spec.thinking}\` but \`thinking\` says \`${requested}\`. Pass one of them.`,
+    };
+  }
+  const level = requested !== undefined && isThinkingLevel(requested) ? requested : spec.thinking;
+  if (!isValidModelSpec(spec.model)) return { kind: "rejected", message: invalidModelMessage(spec.model) };
+  if (exact && requested === undefined && splitModelSpec(whole).thinking !== undefined) {
+    // Stored whole, `x/model:low` would read back as model `x/model` at thinking `low`.
+    return {
+      kind: "rejected",
+      message: `Model \`${whole}\` ends in a thinking-level word, so a plain assignment would be misread. Pass \`thinking\` explicitly, for example \`high\`.`,
+    };
+  }
+  const known = available.find((candidate) => candidate.id === spec.model);
+  if (!known) {
+    return {
+      kind: "rejected",
+      message: `No model \`${spec.model}\` is available in this Pi installation. Call this tool with action "models" for real ids, or pass "inherit".`,
+    };
+  }
+  if (level !== undefined && level !== "off" && known.reasoning === false) {
+    return {
+      kind: "rejected",
+      message: `Model \`${spec.model}\` does not support thinking. Drop \`thinking\`, or pick a reasoning model.`,
+    };
+  }
+  const assigned: ModelSpec = { model: spec.model, thinking: level };
+  if (!isValidModelSpec(joinModelSpec(assigned))) return { kind: "rejected", message: invalidModelMessage(joinModelSpec(assigned)) };
+  return { kind: "assign", spec: assigned };
+}
+
+/** Role names reach generated markdown and status tables, so they stay plain kebab-case. */
+const ROLE_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+/**
+ * A model spec is also rendered into markdown the agent reads, so it is printable ASCII with the
+ * markup characters removed. An allow-list of ASCII keeps invisible text (tag characters, zero-width
+ * and bidi controls) out; catalogue ids such as OpenRouter's `~anthropic/...` aliases are ASCII.
+ * A trailing colon is never a valid id or level.
+ */
+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(":");
+  if (model.length > MAX_MODEL_SPEC_LENGTH || !plain(model)) return false;
+  // `x/model::high` splits to `x/model:`, which is no model id.
+  return plain(splitModelSpec(model).model);
+}
+
+export function isValidRole(role: string): boolean {
+  return ROLE_PATTERN.test(role);
+}
+
+export function invalidRoleMessage(role: string): string {
+  return `Invalid role name ${safeEcho(role)}. Use lowercase letters, digits, and hyphens, starting with a letter, for example "bug-fix".`;
+}
+
+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> = {};
   for (const pair of value.split(",")) {
@@ -95,9 +229,15 @@ export function parseModelRoles(value: string): Record<string, string> {
     if (trimmed === "") continue;
     const separator = trimmed.indexOf("=");
     if (separator <= 0) {
-      throw new Error(`Invalid model role assignment ${JSON.stringify(trimmed)}. Use role=provider/model.`);
+      throw new Error(`Invalid model role assignment ${safeEcho(trimmed)}. Use role=provider/model or role=provider/model:thinking.`);
     }
-    roles[trimmed.slice(0, separator).trim()] = trimmed.slice(separator + 1).trim();
+    const role = trimmed.slice(0, separator).trim();
+    const model = trimmed.slice(separator + 1).trim();
+    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));
+    roles[role] = model;
   }
   return roles;
 }
@@ -111,7 +251,13 @@ export function environmentLayer(env: NodeJS.ProcessEnv): ConfigLayer {
   if (env[ENV.pluginPath]) values.pluginPath = env[ENV.pluginPath];
   if (env[ENV.cacheDir]) values.cacheDir = env[ENV.cacheDir];
   if (env[ENV.allowBootstrap]) values.allowBootstrap = !NEGATIVE.has((env[ENV.allowBootstrap] as string).trim().toLowerCase());
-  if (env[ENV.models]) values.models = parseModelRoles(env[ENV.models] as string);
+  if (env[ENV.models]) {
+    try {
+      values.models = parseModelRoles(env[ENV.models] as string);
+    } catch (error) {
+      throw new Error(`${ENV.models}: ${(error as Error).message}`);
+    }
+  }
   if (env[ENV.delegation]) values.delegation = (env[ENV.delegation] as string).trim().toLowerCase();
   return { label: "environment", values };
 }
@@ -134,7 +280,7 @@ export function mergeConfig(layers: readonly ConfigLayer[]): AdapterConfig {
         merged.ref = undefined;
       }
       if (key === "models") {
-        merged.models = { ...merged.models, ...(value as Record<string, string>) };
+        merged.models = { ...merged.models, ...validatedModels(value, layer.label) };
       } else {
         (merged as Record<string, unknown>)[key] = value;
       }
@@ -162,6 +308,25 @@ export function mergeConfig(layers: readonly ConfigLayer[]): AdapterConfig {
   };
 }
 
+/** 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> {
+  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> = {};
+  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)) {
+      throw new Error(`${label}: role ${safeEcho(role)}. ${invalidModelMessage(model)}`);
+    }
+    Object.defineProperty(models, role, { value: model, enumerable: true, writable: true, configurable: true });
+  }
+  return models;
+}
+
 /**
  * The certified commit is the default, not a floor. Naming a ref or a repository without a
  * commit means the user asked for that ref, so the pin must get out of the way and trust
@@ -179,7 +344,7 @@ function validateDelegation(value: string | undefined, layers: readonly ConfigLa
   if (isDelegationProvider(value)) return value;
   const owner = [...layers].reverse().find((layer) => layer.values.delegation === value);
   throw new Error(
-    `${owner?.label ?? "config"} sets \`delegation\` to ${JSON.stringify(value)}. Use one of ${DELEGATION_PROVIDERS.map((id) => `"${id}"`).join(", ")}, or remove it to prefer "${DEFAULT_DELEGATION}".`,
+    `${owner?.label ?? "config"} sets \`delegation\` to ${safeEcho(value)}. Use one of ${DELEGATION_PROVIDERS.map((id) => `"${id}"`).join(", ")}, or remove it to prefer "${DEFAULT_DELEGATION}".`,
   );
 }
 

package/src/echo.ts

@@ -0,0 +1,9 @@
+/**
+ * Rejected input is attacker-shaped text that can reach the agent through an error message, so echo
+ * only a short, plain, quoted form of it. Non-strings are reported by type alone.
+ */
+export function safeEcho(value: unknown): string {
+  if (typeof value !== "string") return `(a value of type ${value === null ? "null" : typeof value})`;
+  const cleaned = value.slice(0, 24).replace(/[^A-Za-z0-9._/:~@+-]/g, "?");
+  return `"${cleaned}${value.length > 24 ? "..." : ""}"`;
+}

package/src/generate.ts

@@ -483,9 +483,18 @@ function t3Section(namespace: string): string {
   path of \`agents/${namespace}-poteto-agent.md\` beside this file. The \`agent prompts\` row of
   the status report gives that directory.
 - Model: a role configured as \`provider/model\` becomes
-  \`target: { providerInstanceId: "pi", model: "provider/model" }\`. An unconfigured role omits
-  \`target\`, so the child inherits the parent. For a different model family, call
-  \`${T3_CAPABILITIES_TOOL}\` and use a provider and model it lists.
+  \`target: { providerInstanceId: "pi", model: "provider/model" }\`. Read the thinking column of
+  the \`model roles\` table in the \`pstack_adapter\` \`status\` report. When it names a level, add it to
+  \`target.options\` under the option id that \`${T3_CAPABILITIES_TOOL}\` lists for that model's
+  thinking setting. For Pi models the id is \`thinking\`, as in \`options: { thinking: "<level>" }\`.
+  A role whose thinking reads "backend default" omits \`options\`, so the backend applies its own
+  default. An unconfigured role omits \`target\`, so the child inherits the parent model and
+  thinking.
+- If the model does not list the level, use the highest level it lists that is below the requested
+  one, and tell the user. If it lists none below the requested level, or lists no thinking option,
+  omit \`options\` and tell the user. If the level is \`off\` and the model does not list \`off\`, omit
+  \`options\` and tell the user, because the closest listed level would turn thinking on.
+  For a different model family, call \`${T3_CAPABILITIES_TOOL}\` and use a provider and model it lists.
 - Background: \`mode: "async"\`. A finished child wakes this thread, so end the turn instead of
   polling. Call \`${T3_STATUS_TOOL}\` only when you need a result mid-turn.
 - Call \`${T3_CAPABILITIES_TOOL}\` or \`${T3_STATUS_TOOL}\` only when the \`check\` report allows it.
@@ -508,7 +517,10 @@ function subagentSection(namespace: string): string {
 
 - Agent names are namespaced, for example \`${namespace}-poteto-agent\`. Call
   \`${SUBAGENT_TOOL}({ action: "list" })\` to see them.
-- Model: pass a role's \`provider/model\` as \`model\`. An unconfigured role omits \`model\`.
+- Model: pass a role's \`provider/model\` as \`model\`. When the thinking column of the \`model roles\`
+  table in the \`pstack_adapter\` \`status\` report names a level for the role, append it as
+  \`provider/model:<level>\`. A role whose thinking reads "backend default" gets no suffix, so
+  pi-subagents applies its own default. An unconfigured role omits \`model\`.
 - Background: \`async: true\`.`;
 }
 
@@ -524,7 +536,7 @@ that names a Cursor tool, path, or model.
 | \`run_in_background: true\` | \`mode: "async"\` on \`delegate_task\`, or \`async: true\` on \`subagent\`. |
 | \`AskUserQuestion\`, \`AskQuestion\` | the \`ask_user\` tool. |
 | \`TodoWrite\`, \`TaskCreate\`, \`TaskUpdate\` | no Pi equivalent. Keep an uncommitted \`todo.md\` checklist instead. |
-| \`claude-opus-5-5-xhigh\`, \`grok-4.7-xhigh-fast\`, other Cursor model slugs | the role models configured by \`/skill:${namespace}-setup\`. Call the \`pstack_adapter\` tool with \`action: "status"\` to read the current role table. An unconfigured role inherits the parent model, so omit \`target\` or \`model\`. |
+| \`claude-opus-5-5-xhigh\`, \`grok-4.7-xhigh-fast\`, other Cursor model slugs | the role models configured by \`/skill:${namespace}-setup\`. Call the \`pstack_adapter\` tool with \`action: "status"\` to read the current role table. An effort word in a slug, such as \`-xhigh\` or \`-max\`, is not a model id. The role table's thinking column carries that level, and \`-fast\` has no equivalent. An unconfigured role inherits the parent model and thinking, so omit \`target\` or \`model\`. |
 | a role line valued \`auto\` or \`inherit-parent\` | an unconfigured role. Omit \`target\` or \`model\` so the child runs on the parent model. |
 | \`~/.cursor/rules/pstack-models.mdc\` | adapter configuration written by \`/skill:${namespace}-setup\`. |
 | role lines \`feature, refactoring\`, \`bug-fix\`, \`perf-issue\`, \`hillclimb\`, \`judgment and prose\`, \`hardest tasks\` | adapter roles \`feature\` or \`refactoring\`, \`bug-fix\`, \`perf-issue\`, \`hillclimb\`, \`judgment\`, and \`strongest-judgment\`. |

package/src/namespace.ts

@@ -1,3 +1,5 @@
+import { safeEcho } from "./echo.ts";
+
 export const DEFAULT_NAMESPACE = "pistack";
 
 const NAMESPACE_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
@@ -5,7 +7,7 @@ const NAMESPACE_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 export function validateNamespace(value: string): string {
   if (!NAMESPACE_PATTERN.test(value)) {
     throw new Error(
-      `Invalid pstack adapter namespace ${JSON.stringify(value)}. Use lowercase letters, digits, and single hyphens.`,
+      `Invalid pstack adapter namespace ${safeEcho(value)}. Use lowercase letters, digits, and single hyphens.`,
     );
   }
   return value;

package/src/status.ts

@@ -1,7 +1,7 @@
 import { CERTIFIED } from "./certified.ts";
 import { CAPABILITY_LABELS, MODEL_ROLES, TIER_ORDER } from "./registry.ts";
 import type { AdapterConfig } from "./config.ts";
-import { trustWarning } from "./config.ts";
+import { splitModelSpec, trustWarning } from "./config.ts";
 import { DELEGATION_BACKENDS, delegationOrder } from "./delegation.ts";
 import type { PrerequisiteReport } from "./capabilities.ts";
 import type {
@@ -88,14 +88,17 @@ export function renderStatus(input: StatusInput): string {
 
   lines.push(`## Model roles`);
   lines.push("");
-  lines.push(`| role | model |`);
-  lines.push(`| --- | --- |`);
-  for (const role of MODEL_ROLES) {
-    lines.push(`| ${role} | ${config.models[role] ?? "inherit (parent session model)"} |`);
-  }
+  lines.push(`| role | model | thinking |`);
+  lines.push(`| --- | --- | --- |`);
   const extra = Object.keys(config.models).filter((role) => !MODEL_ROLES.includes(role)).sort();
-  for (const role of extra) {
-    lines.push(`| ${role} | ${config.models[role]} |`);
+  for (const role of [...MODEL_ROLES, ...extra]) {
+    const configured = config.models[role];
+    if (configured === undefined) {
+      lines.push(`| ${role} | inherit (parent session model) | inherit (parent session thinking) |`);
+      continue;
+    }
+    const spec = splitModelSpec(configured);
+    lines.push(`| ${role} | ${spec.model} | ${spec.thinking ?? "backend default"} |`);
   }
   lines.push("");