pi-pstack-adapter 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project are documented here. release-please writes new entries from Conventional Commit PR titles.
 
+## [0.6.0](https://github.com/elderfo/pi-pstack-adapter/compare/v0.5.0...v0.6.0) (2026-10-17)
+
+
+### Features
+
+* **pstack:** certify pstack 0.15.25 with sharpen ([#15](https://github.com/elderfo/pi-pstack-adapter/issues/15)) ([bb09bbb](https://github.com/elderfo/pi-pstack-adapter/commit/bb09bbb963c528666c79176072da002957a93827))
+
+## [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.6.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/docs/compatibility.md

@@ -4,7 +4,7 @@ The compatibility registry in `src/registry.ts` assigns one support tier to ever
 certified pstack revision. Generation reads it, the wrapper frontmatter publishes it, and
 `/pistack-status` reports it.
 
-Certified revision: pstack `0.15.23` at `dbf49813a39c1a5389c5e28cb8e4c1c2379e2454` in
+Certified revision: pstack `0.15.25` at `101b274dd991f694e1f7024be2157e5f3adf07de` in
 `https://github.com/cursor/plugins`.
 
 ## Platforms
@@ -21,8 +21,9 @@ executables in the shell the skills run in, with Pi's `shellCommandPrefix` appli
 that matters most, because Git Bash adds `/usr/bin` and `/mingw64/bin` to the `PATH` Pi
 started with. A shell that is missing, inactive, or cannot run a command blocks every workflow.
 
-Windows evidence at the certified revision, pstack `0.15.23`, on Windows 11 with Git for
-Windows 2.53, Node 22, Bun 1.3, and Pi 1.2.0:
+Windows evidence was last gathered at pstack `0.15.23`, on Windows 11 with Git for Windows 2.53,
+Node 22, Bun 1.3, and Pi 1.2.0. CI runs the unit suite on Windows at `0.15.25`; the rest of this
+list has not been rerun there:
 
 - The unit suite and the type check pass. `npm run test:isolated` passes from Git Bash: Pi
   registers all 54 skills, and a later run reuses the cache without the network. CI runs the
@@ -41,6 +42,10 @@ Windows 2.53, Node 22, Bun 1.3, and Pi 1.2.0:
   `check-plan.mjs` ran on Node. Upstream's helper suite passed 61 of 63 tests under Bun. The two
   failures fake the Graphite `gt` CLI with a shell script, which Bun cannot spawn on Windows.
   Both fail at `0.15.9` too, and the adapter does not gate on `gt`.
+- At `0.15.25`, `orch.ts` resolves the stack frontier through `gh`, or `origin` with
+  `--forge origin`, instead of `gt`. `poteto-mode` already requires `gh`. `worktree-audit.sh`
+  reads PR state through `origin` when it is installed, otherwise `gh`, and reports no PR state
+  when neither works. Neither helper has run on Windows at `0.15.25`.
 - At pstack `0.15.9`, `show-me-your-work/scripts/log.sh`, `watch-pr`, and `orch.ts` also ran
   in Git Bash. None of them changed in a way that adds an executable or a path assumption.
 - Git for Windows bundles `git`, `curl`, `nproc`, and the POSIX tools the skill bodies call,
@@ -143,7 +148,7 @@ Lowering a tier needs one reproduction of the failure and a note saying what bro
 | `teach` | `/skill:pistack-teach` | `delegation` | - | It runs the how and why skills, both of which need subagents. |
 | `why` | `/skill:pistack-why` | `delegation` | `git`, `gh` | Default posture spawns one investigator subagent per evidence category plus a synthesizer. |
 
-### experimental (6)
+### experimental (7)
 
 | upstream skill | Pi skill | capabilities | executables | why |
 | --- | --- | --- | --- | --- |
@@ -152,6 +157,7 @@ Lowering a tier needs one reproduction of the failure and a note saying what bro
 | `poteto-mode` | `/skill:pistack-poteto-mode` | `delegation`, `structured-question` | `git`, `gh` | Sticky-mode hosting plus references to Cursor built-in and plugin skills only partially map to Pi. |
 | `recall` | `/skill:pistack-recall` | `delegation` | `git`, `gh` | Core corpus is Cursor's on-disk transcript JSONL, so only the git/gh and shared-record half survives. |
 | `reflect` | `/skill:pistack-reflect` | `delegation` | - | Transcript mining and create-skill routing are Cursor-specific, though the digest fallback partly works. |
+| `sharpen` | `/skill:pistack-sharpen` | - | - | New in pstack 0.15.25 and not yet run end to end in Pi. Its body is prompt-only, with no tool, delegation, or executable, and it runs only when you type it. |
 | `swarm` | `/skill:pistack-swarm` | `delegation` | - | Cloud background workers and cloud_base_branch have no Pi mapping; only local fan-out approximates it. |
 
 ### unsupported (1)

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.6.0",
   "description": "Run Cursor's official pstack plugin inside Pi from an unmodified upstream checkout",
   "type": "module",
   "license": "MIT",

package/src/certified.ts

@@ -5,9 +5,9 @@
 export const CERTIFIED = {
   repo: "https://github.com/cursor/plugins",
   ref: "main",
-  commit: "dbf49813a39c1a5389c5e28cb8e4c1c2379e2454",
+  commit: "101b274dd991f694e1f7024be2157e5f3adf07de",
   pluginPath: "pstack",
-  pstackVersion: "0.15.23",
-  skillCount: 53,
+  pstackVersion: "0.15.25",
+  skillCount: 54,
   agentCount: 2,
 } as const;

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,8 @@ 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\`. |
+| "pick each subagent's reasoning level and fast or standard speed", a role's starting level from the \`/setup-pstack\` budget | the thinking column of the \`model roles\` table is a role's starting level. When it names a level, you may move it along \`off\`, \`minimal\`, \`low\`, \`medium\`, \`high\`, \`xhigh\`, \`max\` as the body asks, then pass it by the backend rules in [Delegation](#delegation). A role whose thinking reads "backend default", and an unconfigured role, keep their setting, because they have no level to move. Fast or standard speed has no Pi equivalent, so leave it out. If the backend rejects the moved level, use the role's configured level and say so. |
 | 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/registry.ts

@@ -51,6 +51,7 @@ export const SKILL_REGISTRY: Readonly<Record<string, RegistryEntry>> = {
   "recall": { tier: "experimental", capabilities: ["delegation"], executables: ["git", "gh"], note: "Core corpus is Cursor's on-disk transcript JSONL, so only the git/gh and shared-record half survives." },
   "reflect": { tier: "experimental", capabilities: ["delegation"], executables: [], note: "Transcript mining and create-skill routing are Cursor-specific, though the digest fallback partly works." },
   "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: "experimental", capabilities: [], executables: [], note: "New in pstack 0.15.25 and not yet run end to end in Pi. Its body is prompt-only, with no tool, delegation, or executable, and it runs only when you type it." },
   "show-me-your-work": { tier: "dependency-gated", capabilities: ["delegation"], executables: [], note: "The mandatory cross-model review of the trail requires spawning a different-family subagent." },
   "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: [] },

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("");