@cr1ms0n/pi-subagent 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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.
@@ -12,7 +21,15 @@
 The entries below are retained upstream history from @parke.dev/pi-subagent.
 
 
-## Unreleased
+## 0.8.2 — 2026-09-10
+
+### Background completion delivery
+
+- Automatic terminal notifications for `async: true` runs now use Pi's `steer`
+  delivery queue with `triggerTurn: true`, making completion messages available
+  before the parent's next LLM call. Foreground runs, explicit management
+  actions, message content, batching, persistence, and usage accounting are
+  unchanged.
 
 ### Machine-wide worktree GC
 

package/README.md

@@ -238,14 +238,29 @@ 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 accepts `off`, `minimal`, `low`, `medium`, `high`,
+or `xhigh`. 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 +334,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/docs/UI-OVERHAUL.md

@@ -5,9 +5,9 @@
 > the plan: the inline spinner uses a wall-clock frame (Pi's working indicator
 > drives repaints, so no timer is owned); the ledger command landed as
 > `/subagent-cost` via `ctx.ui.notify`. Phase 4 shipped as the background-only
-> ambient widget plus batched `followUp` completion notifications with
-> flush-time wait-suppression (see docs/UX.md). The `description` param is the
-> task label across all surfaces. This document is retained as design rationale.
+> ambient widget plus batched `steer` completion notifications with flush-time
+> wait-suppression (see docs/UX.md). The `description` param is the task label
+> across all surfaces. This document is retained as design rationale.
 
 Goal: remove the duplicated cost footer, make inline chat rendering clean and
 smooth, and align every surface with Pi's native conventions. Informed by a
@@ -137,7 +137,7 @@ Files: `src/extension.ts`, new `src/notifications.ts`.
   ```
 
   Cleared when no background runs. Config: `widget: "background" | "off"`.
-- **Completion notifications** via `pi.sendMessage(…, { deliverAs: "followUp",
+- **Completion notifications** via `pi.sendMessage(…, { deliverAs: "steer",
   triggerTurn: true })` + `registerMessageRenderer`: themed compact box for the
   human (state, stats, first-line preview, artifact/session pointers),
   structured payload for the model. Replaces the bare `ctx.ui.notify` toast.

package/docs/UX.md

@@ -66,11 +66,11 @@ Cleared when the last background run settles. Spinner and elapsed animate on
 a 250ms interval that exists only while background runs are live.
 
 ### Completion notifications (background runs only)
-When an async run reaches a terminal state, a `followUp` message (custom type
-`subagent-completion`) notifies the parent LLM so it reacts without polling.
-The human sees a themed compact box (state glyph, label, stats, one-line
-preview, artifact pointers); the LLM sees plain text with run ids and a
-`wait { id }` pointer.
+When an async run reaches a terminal state, a `steer` message (custom type
+`subagent-completion`) is queued for the parent LLM before its next LLM call,
+so it can react without polling. The human sees a themed compact box (state
+glyph, label, stats, one-line preview, artifact pointers); the LLM sees plain
+text with run ids and a `wait { id }` pointer.
 
 - Successes within a short window batch into one message (no fanout spam);
   failures bypass batching and flush immediately, carrying held successes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cr1ms0n/pi-subagent",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "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,9 @@ 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 (`off`, `minimal`, `low`, `medium`,
+`high`, or `xhigh`) 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];
@@ -83,7 +83,7 @@ export interface SubagentConfig {
    */
   widget: WidgetMode;
   /**
-   * Batched completion followUp messages for async runs. `"off"` disables the
+   * Batched completion messages for async runs. `"off"` disables the
    * CompletionBatcher so the parent is not notified on finish.
    */
   notifications: NotificationMode;
@@ -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,
       },
@@ -763,7 +763,7 @@ export default function registerSubagent(pi: ExtensionAPI): void {
     runtime.unsubscribeLedger = runtime.registry.subscribe((event) => {
       if (event.sessionKey === runtime.key) runtime.ledgerDirty = true;
     });
-    // Background-run completion notifications: batched followUp messages so
+    // Background-run completion notifications: batched steer messages so
     // the parent LLM reacts without polling. Foreground runs deliver inline.
     // `notifications: "off"` skips construction; subscribe still uses optional chain.
     if (runtime.config.notifications !== "off") {
@@ -806,7 +806,7 @@ export default function registerSubagent(pi: ExtensionAPI): void {
           ].join("\n"),
           display: true,
           details,
-        }, { deliverAs: "followUp", triggerTurn: true });
+        }, { deliverAs: "steer", triggerTurn: true });
       });
     }
 

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 { THINKING_LEVELS, 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 one of: ${THINKING_LEVELS.join(", ")}`);
+  }
+  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/notifications.ts

@@ -2,8 +2,8 @@
  * Background-run completion notifications.
  *
  * When an async run reaches a terminal state, the parent LLM is notified with
- * a followUp message (delivered when the agent is idle / between turns) so it
- * can react without polling status/wait. Matches the notification-as-delivery
+ * a steer message (queued for delivery before the next LLM call) so it can
+ * react without polling status/wait. Matches the notification-as-delivery
  * semantics of `wait`: whichever path delivers first wins via markDelivered.
  *
  * Batching: successes completing within a short window group into a single

package/src/policy.ts

@@ -199,6 +199,7 @@ 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;
   const label = item.description?.trim()
     ? item.description.trim().slice(0, 60)
     : agent
@@ -223,7 +224,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 +245,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

@@ -31,7 +31,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: "Reasoning effort for the child. 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,6 @@
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+export function isThinkingLevel(value: unknown): value is ThinkingLevel {
+  return typeof value === "string" && (THINKING_LEVELS as readonly string[]).includes(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;