@cr1ms0n/pi-subagent 0.8.2 → 0.8.4

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.8.4 — 2026-09-10
+
+### Pi-owned thinking levels
+
+- Treat route and task `thinking` values as opaque Pi strings instead of a
+  hard-coded local enum, preserving model-specific values such as `max` and
+  passing them to Pi unchanged. Pi remains responsible for model capability
+  validation and mapping.
+
+## 0.8.3 — 2026-09-10
+
+### Model-policy thinking defaults
+
+- Allow `modelPolicy.default` and named-agent routes in `~/.pi/subagent.json`
+  to specify an optional `thinking` default (`off`, `minimal`, `low`, `medium`,
+  `high`, or `xhigh`). Explicit task, agent, and profile defaults still win;
+  unsupported backends reject resolved thinking instead of silently ignoring it.
+
 ## 0.8.1 — @cr1ms0n community fork (2026-09-08)
 
 - Require an explicit model matching user-owned default/agent model policy.

package/README.md

@@ -238,14 +238,31 @@ fallback lists are ignored for model selection. The minimal template is:
 ```json
 {
   "modelPolicy": {
-    "default": { "model": "<provider/model-id>", "fallbackModels": [] },
+    "default": {
+      "model": "<provider/model-id>",
+      "fallbackModels": [],
+      "thinking": "medium"
+    },
     "agents": {
-      "<agent-name>": { "model": "<provider/model-id>", "fallbackModels": [] }
+      "<agent-name>": {
+        "model": "<provider/model-id>",
+        "fallbackModels": [],
+        "thinking": "high"
+      }
     }
   }
 }
 ```
 
+`thinking` is optional and is an opaque Pi thinking-level string. Common values
+include `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`, but the
+package does not remap or restrict model-specific values. Pi receives the value
+unchanged and decides whether the active model supports it. It is a route default,
+not a strict policy value. Resolution order is: explicit task `thinking` > agent
+frontmatter `thinking` > profile `taskDefaults.<profile>.thinking` > the selected
+`modelPolicy` route's `thinking` > the parent session's thinking level. Omitting it
+preserves the existing behavior.
+
 Every new `task`/`tasks[]` item must pass the exact mapped `model`. Omit
 `fallback_models` to use the configured list; when supplied it must match the
 configured order exactly. Management actions remain available when this file is
@@ -319,7 +336,8 @@ and file changes are picked up within seconds — no restart needed.
 `taskDefaults` in `~/.pi/subagent.json` remains available for non-model
 fields such as thinking, budgets, and retry counts. Its legacy `model` and
 `fallbackModels` fields are ignored; model routing belongs only to
-`modelPolicy`. Invalid fields are dropped field-by-field.
+`modelPolicy`. A profile `thinking` value overrides the selected route default.
+Invalid fields are dropped field-by-field.
 
 Notes on behavior:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cr1ms0n/pi-subagent",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Community fork of Luke Parke's pi-subagent with explicit model policy and model visibility for Pi",
   "type": "module",
   "license": "MIT",

package/skills/subagent/SKILL.md

@@ -97,7 +97,11 @@ Every new task must pass a `model` that exactly matches the current
 `taskDefaults.model`, and parent-session model inheritance are ignored. An
 agent route replaces the default route, and configured fallback order is
 immutable. Omit `fallback_models` to use the route; if supplied, it must match
-exactly. Management actions do not require model. The extension re-reads this
-policy on each dispatch and injects it into the parent prompt. If the policy is
-missing or invalid, management remains available but new spawns and synthesis
-are rejected.
+exactly. An optional route `thinking` value is an opaque Pi thinking-level
+string; common values include `off`, `minimal`, `low`, `medium`, `high`, `xhigh`,
+and `max`, but model-specific values are passed through unchanged. It is a
+default; explicit task, agent, and profile `taskDefaults.thinking` values
+override it. Management actions do not require model. The extension re-reads
+this policy on each dispatch and injects it into
+the parent prompt. If the policy is missing or invalid, management remains
+available but new spawns and synthesis are rejected.

package/src/agents.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { TaskProfile } from "./types.js";
-import type { ThinkingLevel } from "./config.js";
+import { isThinkingLevel, type ThinkingLevel } from "./thinking.js";
 import { isPlausibleSchema } from "./structured.js";
 
 /**
@@ -23,7 +23,6 @@ import { isPlausibleSchema } from "./structured.js";
  * model policy is the only source used for new spawns.
  */
 
-const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
 const PROFILES = ["explore", "review", "general"] as const;
 
 export interface AgentDefinition {
@@ -178,9 +177,7 @@ export function parseAgentFile(name: string, raw: string, source: string, scope:
     }
   }
 
-  const thinking = frontmatter.thinking && (THINKING_LEVELS as readonly string[]).includes(frontmatter.thinking)
-    ? (frontmatter.thinking as ThinkingLevel)
-    : undefined;
+  const thinking = isThinkingLevel(frontmatter.thinking) ? frontmatter.thinking : undefined;
   const profile = frontmatter.profile && (PROFILES as readonly string[]).includes(frontmatter.profile)
     ? (frontmatter.profile as TaskProfile)
     : undefined;

package/src/backend.ts

@@ -139,6 +139,9 @@ export function checkCapabilities(
       `backend '${backend}' cannot restrict the child's tools, so profile '${spec.profile ?? "explore"}' cannot be enforced; use profile:'general' with an explicitly writable backend, or the pi backend`,
     );
   }
+  if (spec.thinking !== undefined && !capabilities.thinking) {
+    problems.push(`backend '${backend}' does not support thinking level '${spec.thinking}'; omit thinking or use the pi backend`);
+  }
   if (spec.outputSchema && !capabilities.outputSchema) {
     problems.push(`backend '${backend}' does not support output_schema; drop it`);
   }

package/src/config.ts

@@ -3,9 +3,9 @@ import * as os from "node:os";
 import * as path from "node:path";
 import type { TaskProfile } from "./types.js";
 import { MODEL_POLICY_CONFIG_FILE, parseModelPolicy, type ModelPolicySnapshot } from "./model-policy.js";
+import { isThinkingLevel, type ThinkingLevel } from "./thinking.js";
 
-const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
-export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+export type { ThinkingLevel } from "./thinking.js";
 
 const WIDGET_MODES = ["background", "off"] as const;
 export type WidgetMode = (typeof WIDGET_MODES)[number];
@@ -139,9 +139,7 @@ function prune<T extends object>(value: Partial<T>): Partial<T> {
 function sanitizeTaskDefaults(raw: unknown): TaskDefaults | undefined {
   if (!raw || typeof raw !== "object") return undefined;
   const value = raw as Record<string, unknown>;
-  const thinking = typeof value.thinking === "string" && (THINKING_LEVELS as readonly string[]).includes(value.thinking)
-    ? (value.thinking as ThinkingLevel)
-    : undefined;
+  const thinking = isThinkingLevel(value.thinking) ? value.thinking : undefined;
   const fallbackModels = Array.isArray(value.fallbackModels)
     ? value.fallbackModels.map(nonEmptyString).filter((model): model is string => !!model)
     : undefined;

package/src/extension.ts

@@ -566,7 +566,7 @@ async function runSynthesis(
         tools: ["read"],
         model: approved.route.model,
         fallbackModels: [...approved.route.fallbackModels],
-        thinking: "low",
+        thinking: approved.route.thinking ?? "low",
         timeoutMs: Math.min(runtime.config.defaultTimeoutMs, 5 * 60_000),
         maxTurns: 8,
       },

package/src/model-policy.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
+import { isThinkingLevel, type ThinkingLevel } from "./thinking.js";
 
 export const MODEL_POLICY_CONFIG_FILE = path.join(os.homedir(), ".pi", "subagent.json");
 
@@ -8,6 +9,8 @@ export interface ModelRoute {
   model: string;
   /** Immutable order owned by the user configuration. */
   fallbackModels: readonly string[];
+  /** Optional route default; callers may override it with task/agent/profile settings. */
+  thinking?: ThinkingLevel;
 }
 
 export interface ModelPolicySnapshot {
@@ -42,7 +45,7 @@ function route(value: unknown, pathName: string, source: string): ModelRoute {
     invalid(source, `${pathName} must be an object`);
   }
   const record = value as Record<string, unknown>;
-  const unknown = Object.keys(record).filter((key) => key !== "model" && key !== "fallbackModels");
+  const unknown = Object.keys(record).filter((key) => key !== "model" && key !== "fallbackModels" && key !== "thinking");
   if (unknown.length) invalid(source, `${pathName} has unknown field(s): ${unknown.join(", ")}`);
   const model = modelId(record.model, pathName, source);
   const rawFallbacks = record.fallbackModels === undefined ? [] : record.fallbackModels;
@@ -50,7 +53,15 @@ function route(value: unknown, pathName: string, source: string): ModelRoute {
   const fallbackModels = rawFallbacks.map((value, index) => modelId(value, `${pathName}.fallbackModels[${index}]`, source));
   if (new Set(fallbackModels).size !== fallbackModels.length) invalid(source, `${pathName}.fallbackModels must not contain duplicates`);
   if (fallbackModels.includes(model)) invalid(source, `${pathName}.fallbackModels must not repeat the primary model`);
-  return Object.freeze({ model, fallbackModels: Object.freeze([...fallbackModels]) });
+  const thinking = record.thinking;
+  if (thinking !== undefined && !isThinkingLevel(thinking)) {
+    invalid(source, `${pathName}.thinking must be a non-empty Pi thinking level string without whitespace or control characters`);
+  }
+  return Object.freeze({
+    model,
+    fallbackModels: Object.freeze([...fallbackModels]),
+    ...(thinking === undefined ? {} : { thinking }),
+  });
 }
 
 /** Parse only the modelPolicy subtree; no provider catalog or credentials are read. */
@@ -131,14 +142,15 @@ export function formatModelPolicyPrompt(policy: ModelPolicySnapshot | undefined,
   const lines = [
     "## Subagent model policy",
     "Every new task/tasks[] spawn must pass model explicitly and it must exactly match this mapping. Management actions do not need model.",
-    `default (agentless and unmapped agents): model=${policy.default.model}; fallback_models=[${policy.default.fallbackModels.join(", ")}]`,
+    `default (agentless and unmapped agents): model=${policy.default.model}; fallback_models=[${policy.default.fallbackModels.join(", ")}]; thinking=${policy.default.thinking ?? "(unset)"}`,
   ];
   for (const [agent, route] of [...policy.agents.entries()].sort(([a], [b]) => a.localeCompare(b))) {
-    lines.push(`agent:${agent}: model=${route.model}; fallback_models=[${route.fallbackModels.join(", ")}]`);
+    lines.push(`agent:${agent}: model=${route.model}; fallback_models=[${route.fallbackModels.join(", ")}]; thinking=${route.thinking ?? "(unset)"}`);
   }
   lines.push(
     "If fallback_models is omitted, the configured list is used. If it is supplied, it must match the configured list exactly, including order.",
-    "Do not use model/fallback_models from agent frontmatter, taskDefaults, or the parent session; those legacy fields are ignored.",
+    "thinking is a route default: explicit task thinking, agent thinking, and profile taskDefaults.thinking override it; parent thinking is used only when the route is unset.",
+    "Do not use model/fallback_models from agent frontmatter, taskDefaults, or the parent session; those legacy model fields are ignored.",
   );
   return lines.join("\n");
 }
@@ -146,8 +158,8 @@ export function formatModelPolicyPrompt(policy: ModelPolicySnapshot | undefined,
 export function modelPolicyTemplate(): string {
   return JSON.stringify({
     modelPolicy: {
-      default: { model: "<provider/model-id>", fallbackModels: [] },
-      agents: { "<agent-name>": { model: "<provider/model-id>", fallbackModels: [] } },
+      default: { model: "<provider/model-id>", fallbackModels: [], thinking: "medium" },
+      agents: { "<agent-name>": { model: "<provider/model-id>", fallbackModels: [], thinking: "high" } },
     },
   }, null, 2);
 }

package/src/persistence.ts

@@ -1,7 +1,8 @@
 import { Buffer } from "node:buffer";
 import type { SubagentConfig } from "./config.js";
-import type { ChildProcessIdentity, RunMode, RunSnapshot, RunState, TaskProfile, TimeoutPhase, UsageStats } from "./types.js";
+import type { ChildProcessIdentity, RunMode, RunSnapshot, RunState, TaskProfile, TaskSpec, TimeoutPhase, UsageStats } from "./types.js";
 import { emptyUsage } from "./types.js";
+import { isThinkingLevel } from "./thinking.js";
 
 export const RUN_ENTRY_TYPE = "subagent-run-v1";
 
@@ -23,7 +24,7 @@ export interface PersistedResult {
   errorMessage?: string;
   usage: UsageStats;
   model?: string;
-  thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+  thinking?: TaskSpec["thinking"];
   profile?: TaskProfile;
   canWrite?: boolean;
   outputFile?: string;
@@ -141,7 +142,7 @@ function normalizeResult(value: unknown): PersistedResult | undefined {
     errorMessage: typeof r.errorMessage === "string" ? utf8Prefix(r.errorMessage, 2_000) : undefined,
     usage: normalizeUsage(r.usage),
     model: typeof r.model === "string" ? r.model : undefined,
-    thinking: ["off", "minimal", "low", "medium", "high", "xhigh"].includes(String(r.thinking)) ? r.thinking : undefined,
+    thinking: isThinkingLevel(r.thinking) ? r.thinking : undefined,
     profile: ["explore", "review", "general"].includes(String(r.profile)) ? r.profile : undefined,
     canWrite: typeof r.canWrite === "boolean" ? r.canWrite : undefined,
     outputFile: typeof r.outputFile === "string" ? r.outputFile : undefined,

package/src/policy.ts

@@ -8,6 +8,7 @@ import type { ParallelTaskInput, SubagentParams } from "./schema.js";
 import { BACKEND_NAMES, checkCapabilities, type BackendName } from "./backend.js";
 import { resolveBackend } from "./backends/index.js";
 import { validateModelRequest, type ModelPolicySnapshot } from "./model-policy.js";
+import { isThinkingLevel } from "./thinking.js";
 
 export const DEPTH_ENV_VAR = "PI_SUBAGENT_DEPTH";
 export const SPAWNS_ENV_VAR = "PI_SUBAGENT_SPAWNS";
@@ -199,6 +200,10 @@ function normalizeTask(
   // file > per-profile config defaults > parent inheritance. Model routing was
   // validated above and is exclusively owned by modelPolicy.
   const profileDefaults: TaskDefaults = defaults.taskDefaults?.[profile] ?? {};
+  const effectiveThinking = item.thinking ?? agent?.thinking ?? profileDefaults.thinking ?? modelRoute.thinking ?? parent.thinking;
+  if (effectiveThinking !== undefined && !isThinkingLevel(effectiveThinking)) {
+    return { error: `Task ${index + 1}: thinking must be a non-empty Pi thinking level string without whitespace or control characters` };
+  }
   const label = item.description?.trim()
     ? item.description.trim().slice(0, 60)
     : agent
@@ -223,7 +228,7 @@ function normalizeTask(
       // restricts: profile 'general' inherits the parent set and does not
       // promise a read-only sandbox.
       tools: profile === "general" ? undefined : resolved.tools,
-      thinking: item.thinking ?? agent?.thinking,
+      thinking: effectiveThinking,
       outputSchema: item.output_schema ?? agent?.outputSchema,
       profile,
       canWrite: resolved.canWrite,
@@ -244,7 +249,7 @@ function normalizeTask(
       // Model routing is exclusively owned by modelPolicy. Legacy agent,
       // taskDefaults, and parent-session model fields never participate.
       model: item.model!.trim(),
-      thinking: item.thinking ?? agent?.thinking ?? profileDefaults.thinking ?? parent.thinking,
+      thinking: effectiveThinking,
       tools: resolved.tools,
       profile,
       cwd,

package/src/schema.ts

@@ -1,13 +1,10 @@
 import { Type, type Static } from "typebox";
 
-const ThinkingLevel = Type.Union([
-  Type.Literal("off"),
-  Type.Literal("minimal"),
-  Type.Literal("low"),
-  Type.Literal("medium"),
-  Type.Literal("high"),
-  Type.Literal("xhigh"),
-]);
+const ThinkingLevel = Type.String({
+  minLength: 1,
+  maxLength: 64,
+  description: "Opaque Pi thinking level passed through unchanged. Pi/model-specific values such as max are allowed; the active Pi process decides support.",
+});
 
 const OutputMode = Type.Union([Type.Literal("inline"), Type.Literal("file-only")]);
 const Profile = Type.Union([Type.Literal("explore"), Type.Literal("review"), Type.Literal("general")]);
@@ -31,7 +28,7 @@ export const TaskFields = {
   description: Type.Optional(Type.String({ description: "Short human label (3-5 words) shown in UIs and result indexes." })),
   system_prompt: Type.Optional(Type.String({ description: "Extra system prompt appended to the child's prompt (does not replace it)." })),
   model: Type.Optional(Type.String({ description: "**REQUIRED for every spawn call (task/tasks).** Exact model id from modelPolicy, in provider/model-id form. Calls without an explicit model are rejected; agent-file model, taskDefaults, and parent-session inheritance are ignored. Management actions (status/wait/cancel/steer/diff/apply/discard) do not need it." })),
-  thinking: Type.Optional({ ...ThinkingLevel, description: "Reasoning effort for the child. Defaults to profile config default, then the parent's level." }),
+  thinking: Type.Optional({ ...ThinkingLevel, description: "Opaque Pi thinking level for the child. Values such as max are passed through unchanged; Pi/model support decides validity. Defaults to agent thinking, profile taskDefaults.thinking, modelPolicy route thinking, then the parent's level." }),
   tools: Type.Optional(Type.Array(Type.String(), { description: "Optional tool allowlist. explore/review profiles reject write-capable tools." })),
   profile: Type.Optional({ ...Profile, description: "Capability profile: explore/review are strictly read-only; general inherits the parent's active tools and may write." }),
   cwd: Type.Optional(Type.String({ description: "Working directory for the child process." })),

package/src/thinking.ts

@@ -0,0 +1,18 @@
+/**
+ * Opaque thinking-level value understood by the active Pi/model.
+ *
+ * Pi owns the vocabulary and model-specific mappings (for example `max` may
+ * be supported by one model while another exposes a different set). The
+ * subagent package must therefore validate only the transport-safe shape and
+ * pass the value through unchanged.
+ */
+export type ThinkingLevel = string;
+
+const MAX_THINKING_LEVEL_LENGTH = 64;
+
+export function isThinkingLevel(value: unknown): value is ThinkingLevel {
+  return typeof value === "string"
+    && value.length > 0
+    && value.length <= MAX_THINKING_LEVEL_LENGTH
+    && !/[\s\u0000-\u001f\u007f]/u.test(value);
+}

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { Message } from "@earendil-works/pi-ai";
+import type { ThinkingLevel } from "./thinking.js";
 
 export type RunMode = "single" | "parallel";
 export type RunState = "queued" | "running" | "completed" | "partial" | "failed" | "cancelled" | "lost" | "timeout";
@@ -44,7 +45,7 @@ export interface TaskSpec {
   label?: string;
   systemPrompt?: string;
   model?: string;
-  thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+  thinking?: ThinkingLevel;
   tools?: string[];
   profile: TaskProfile;
   canWrite?: boolean;