@bacnh85/pi-subagent 0.15.2 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.16.0 (2026-08-23)
+
+### Features
+
+- **Role-based model routing** — select models by *function* instead of fixed
+  per-agent chains, inspired by oh-my-pi's `modelRoles`. Roles (`@fast`,
+  `@coder`, `@smart`, or custom) map functions to ordered fallback chains via
+  `subagent.roles` in `~/.pi/agent/settings.json`; bundled agents now reference
+  roles instead of hardcoding chains. Without settings, defaults reproduce the
+  previous chains exactly.
+- `subagent.agentModels` per-agent overrides — remap a bundled agent's models
+  (e.g. `{ "reviewer": "@smart:high" }`) without editing its file. Repo
+  `.pi/settings.json` overlays the mapping for trusted projects (read-only).
+- `:thinking` suffix support on any role/model entry (`"@smart:high"`);
+  openrouter `:free` ids are preserved.
+- `/subagent roles` — interactive role editor (TUI panel via the shared
+  `@bacnh85/pi-config-panel` kernel, saves to global settings.json) or plain
+  text mapping in headless mode.
+- Bare `/subagent` now opens the roles view directly (the agent list moved to
+  `/subagent list`); `/subagent <role>` / `/subagent @role` shows a role's
+  chain, default, and the agents using it instead of erroring.
+- `/subagent <name>` and the system-prompt catalog now show each agent's
+  *resolved* chain (role → models → parent fallback) plus unresolved-role
+  warnings.
+
+## 0.15.3 (2026-08-20)
+ ### Improvements
+- Timeouts have been extracted as Environment Variables enabling overriding.
+- `PI_SUBAGENT_INACTIVITY_TIMEOUT_MINS` default : 3 Mins
+- `PI_SUBAGENT_HARD_TIMEOUT_MINS` default: 20 Mins
+
 ## 0.15.2 (2026-08-18)
 
 ### Improvements

package/README.md

@@ -2,6 +2,42 @@
 
 Isolated in-process subagents for Pi. The `subagent` tool supports single, parallel (8 tasks, 4 concurrent), and chained execution; `/agent` opens inspectable child threads. A live progress widget shows running tasks above the editor; `background: true` runs detached with follow-up-turn completion.
 
+## Role-based model routing
+
+Models are selected **by function**, not fixed per agent. A *role* maps a
+function (`fast`, `coder`, `smart`, or your own) to an ordered fallback chain
+in `~/.pi/agent/settings.json` under `subagent.roles`:
+
+```json
+{
+  "subagent": {
+    "roles": {
+      "fast": ["zai-coding-cn/glm-5-turbo", "nvidia/openai/gpt-oss-20b", "opencode-go/deepseek-v4-flash"],
+      "coder": "zai-coding-cn/glm-5.1, opencode-go/deepseek-v4-flash",
+      "smart": "*"
+    },
+    "agentModels": { "reviewer": "@smart:high" }
+  }
+}
+```
+
+- Bundled agents reference roles in frontmatter (`model: "@fast"`) — remap a
+  function once and every agent using it follows.
+- Role values: string (comma chain) or array. `*` / `@default` = parent model.
+- A trailing `:level` (`off|minimal|low|medium|high|xhigh|max`) on any entry
+  overrides the agent's thinking for that match (`"@smart:high"`); openrouter
+  `:free` ids are left intact.
+- `subagent.agentModels` overrides a single agent's models without editing its
+  file. Repo `.pi/settings.json` overlays the global mapping when the project
+  is trusted (read-only; saves go to the global file).
+- Without any settings, bundled defaults reproduce today's chains exactly.
+
+`/subagent` opens the interactive role editor (TUI panel via the shared
+`@bacnh85/pi-config-panel` kernel; prints the effective mapping headless).
+`/subagent list` lists agents, `/subagent <name>` shows an agent's resolved
+chain, and `/subagent @role` (or `/subagent fast`) shows a role's chain and
+the agents using it.
+
 ## Live progress widget
 
 When subagents run, a persistent widget appears above the editor showing each
@@ -45,14 +81,16 @@ Requires Node.js >= 20.18.
 
 ## Bundled roles
 
-| Role | Ordered model preferences | Thinking | Tools |
+| Role | Model role | Thinking | Tools |
 | --- | --- | --- | --- |
-| `scout` | `zai-coding-cn/glm-5-turbo` → `nvidia/openai/gpt-oss-20b` → `opencode-go/deepseek-v4-flash` | off | read, grep, find, ls |
-| `tester` | `zai-coding-cn/glm-5-turbo` → `nvidia/openai/gpt-oss-20b` → `opencode-go/deepseek-v4-flash` | off | read, bash, grep, find, ls |
-| `worker` | `zai-coding-cn/glm-5.1` → `nvidia/mistralai/mistral-small-4-119b-2603` → `openrouter/nvidia/nemotron-3-super-120b-a12b:free` → `opencode-go/deepseek-v4-flash` | medium | **inherits all parent tools** |
-| `general-purpose` | `zai-coding-cn/glm-5.1` → `nvidia/mistralai/mistral-small-4-119b-2603` → `openrouter/nvidia/nemotron-3-super-120b-a12b:free` → `opencode-go/deepseek-v4-flash` | medium | **inherits all parent tools** |
-| `planner` | `zai-coding-cn/glm-5.2` → `openrouter/nvidia/nemotron-3-ultra-550b-a55b:free` → `opencode-go/deepseek-v4-pro` | high | read, grep, find, ls |
-| `reviewer` | `zai-coding-cn/glm-5.2` → `openrouter/nvidia/nemotron-3-ultra-550b-a55b:free` → `opencode-go/deepseek-v4-pro` | high | read, grep, find, ls |
+| `scout` | `@fast` | off | read, grep, find, ls |
+| `tester` | `@fast` | off | read, bash, grep, find, ls |
+| `worker` | `@coder` | medium | **inherits all parent tools** |
+| `general-purpose` | `@coder` | medium | **inherits all parent tools** |
+| `planner` | `@smart` | high | read, grep, find, ls |
+| `reviewer` | `@smart` | high | read, grep, find, ls |
+
+Default role chains (overridable via `subagent.roles` in settings.json — see above):
 
 Each role uses the first authenticated preference available through Pi's model registry, then falls back to the authenticated parent model. Chains are **free-first** to conserve the metered opencode-go budget: **zai-coding-cn** (free GLM, primary) → free **nvidia** NIM and **openrouter** `:free` models → **opencode-go** (paid DeepSeek, last resort — one per role: `deepseek-v4-flash` for fast/strong-coding, `deepseek-v4-pro` for deep reasoning). opencode-go's GLM models cost ~$1.40/$4.40 per M versus zai-coding-cn's free GLM, so GLM stays on zai-coding-cn. Fallback models were live-verified on 2026-07-24; `nvidia/moonshotai/kimi-k2.6` and `nvidia/z-ai/glm-5.2` return 404/timeout on the user's account and were removed — non-rate-limit failures kill the subagent instead of advancing the chain. User/project agent files remain stronger overrides and may set legacy `model`, ordered `models`, and `thinking`.
 
@@ -140,8 +178,8 @@ each writes into its own checkout.
 
 Every child execution receives a timeout:
 
-- **Default inactivity window:** 3 minutes (`DEFAULT_TIMEOUT_MS`); real SDK lifecycle activity resets it.
-- **Absolute cap:** 20 minutes for every child, even when active.
+- **Default inactivity window:** 3 minutes (`DEFAULT_TIMEOUT_MS`); real SDK lifecycle activity resets it.  Overridable with Environment Variable `PI_SUBAGENT_INACTIVITY_TIMEOUT_MINS` 
+- **Absolute cap:** Default 20 minutes for every child, even when active. Overridable with Environment variable `PI_SUBAGENT_HARD_TIMEOUT_MINS` 
 - **Maximum requested inactivity window:** 60 minutes (`MAX_TIMEOUT_MS`); values must be positive integers.
 - Timeout diagnostics distinguish `Idle timeout` from `Hard timeout` and parent cancellation.
 - 30-second progress heartbeats only keep the parent transport alive; they never reset inactivity.
@@ -211,7 +249,8 @@ The raw `stopReason` from the Pi SDK is preserved in the result.
 
 ## Timeout and cancellation
 
-- **Default timeout:** 10 minutes per child.
+- **Default inactivity window:** 3 minutes per child (`PI_SUBAGENT_INACTIVITY_TIMEOUT_MINS`, range 1–60).
+- **Absolute cap:** 20 minutes per child, even when active (`PI_SUBAGENT_HARD_TIMEOUT_MINS`, range 1–60). See *Timeouts* above.
 - **Per-task/step override:** Use `timeout` in task/step params.
 - **Parent cancellation:** Aborting the parent tool call cancels all children.
 - **Sibling cancellation:** In parallel mode with `abortOnFailure: true`, the first failed task cancels running siblings.
@@ -229,10 +268,10 @@ See [CHANGELOG.md](CHANGELOG.md) for release history.
 
 ## Compatibility
 
-- Requires `@earendil-works/pi-coding-agent >=0.80.0 <0.83.0`
-- Requires `@earendil-works/pi-ai >=0.80.0 <0.83.0`
-- Requires `@earendil-works/pi-agent-core >=0.80.0 <0.83.0`
-- Requires `@earendil-works/pi-tui >=0.80.0 <0.83.0`
+- Requires `@earendil-works/pi-coding-agent >=0.80.0 <0.85.0`
+- Requires `@earendil-works/pi-ai >=0.80.0 <0.85.0`
+- Requires `@earendil-works/pi-agent-core >=0.80.0 <0.85.0`
+- Requires `@earendil-works/pi-tui >=0.80.0 <0.85.0`
 - Requires `typebox >=1.3.0 <2.0.0`
 - Requires Node.js >= 20.18
 

package/agent-format.md

@@ -19,9 +19,9 @@ Project agents override user agents with the same name when `agentScope: "both"`
 name: my-agent          # Required. Unique identifier (kebab-case).
 description: ...        # Required. When to use this agent.
 tools: read, grep, ...    # Optional. Comma-separated tool names. Defaults to all.
-model: provider/model     # Optional explicit first choice (legacy compatible).
+model: "@fast"           # Optional. Role alias (quoted — @ is YAML-reserved) or provider/model.
 models:                   # Optional ordered fallbacks; comma form also accepted.
-  - provider/fast-model
+  - "@fast"
   - provider/backup-model
 thinking: low             # Optional: off|minimal|low|medium|high|xhigh|max.
 sandbox: read-only        # Optional: read-only | workspace-write | worktree. Auto-derives tool restrictions.
@@ -29,9 +29,18 @@ color: cyan               # Optional: red|blue|green|yellow|purple|orange|pink|c
 ---
 ```
 
+### Model roles
+
+`model`/`models` entries may reference *roles* instead of concrete models:
+`"@fast"`, `"@coder"`, `"@smart"`, or any role defined under
+`subagent.roles` in `~/.pi/agent/settings.json`. A role expands to an ordered
+fallback chain (string with commas, or array). `"*"` / `"@default"` mean
+"use the parent model". A trailing `:level` (`"@smart:high"`) overrides the
+agent's `thinking` for that match. See README → *Role-based model routing*.
+
 ### `sandbox`
 
-- `read-only`: Restricts tools to `read`, `grep`, `find`, `ls`. Overrides any `tools` field.
+- `read-only`: Restricts tools to the read-only allowlist (`read`, `grep`, `find`, `ls` plus read-only extension tools when inherited — `web_*`, `serena_*`, `munin_*`, `fff*`, …). Overrides any `tools` field.
 - `workspace-write` (default): Uses the agent's `tools` list or defaults to all tools.
 - `worktree`: Runs the agent in an isolated git worktree (`.pi-worktrees/<id>` under the repo root). All file mutations land in the worktree; the main checkout is untouched. On completion, a unified diff of the changes is returned in the result (visible in the thread viewer as a `🌿 worktree` badge) — the parent merges explicitly via `apply_patch`/cherry-pick; nothing is applied automatically. Falls back to in-process execution when the cwd is not a git repo (with a warning). Requires git.
 
@@ -60,9 +69,16 @@ The `subagent` tool is always rejected to prevent recursive delegation.
 Unknown or misspelled tool names produce a clear error.
 Duplicate names are deduplicated automatically.
 
-Custom/extension tools are NOT available to sub-agents by default (each runs in an isolated in-memory session with no extensions).
+**Tool inheritance:** an agent WITHOUT an explicit `tools:` line inherits every
+tool the parent session has (minus `subagent`), including extension tools like
+`web_search`, `serena_*`, `munin_*`, `obsidian`, and `notebooklm`, and runs with
+the parent's extensions loaded. An agent WITH an explicit `tools:` list is
+validated against built-ins ∪ the inherited set and, when the list contains
+only built-ins, runs in a lean loader with no extensions/skills loaded. To
+force an inheriting agent lean, set `tools: read, bash, edit, write, grep, find, ls`.
 
-Read-only service execution (used by `pi-review`) restricts tools to the read-only category.
+Read-only service execution (used by `pi-review`) restricts tools to the
+read-only allowlist (including read-only extension tools when inherited).
 
 ## Model Resolution
 
@@ -86,7 +102,7 @@ Children do not automatically load repository instructions. Callers may pass an
 Each sub-agent runs with:
 - **System prompt**: agent body only (~200-1K tokens typical)
 - **No AGENTS.md**: saves 500-5K tokens
-- **No extensions/skills loaded**: saves 200-1K tokens
+- **No extensions/skills loaded**: saves 200-1K tokens — but only for agents whose effective tool set is built-in only (explicit `tools:` line). Agents that inherit parent tools load the parent's extensions into the child (higher token cost, full toolset).
 - **Thinking per role**: defaults off; bundled scout/reviewer/worker choose low/high/medium
 - **No compaction**: avoids compaction token cost
 

package/agents/general-purpose.md

@@ -1,11 +1,7 @@
 ---
 name: general-purpose
 description: General-purpose sub-agent for any delegated task. Use when no specialized agent fits. Good for complex research, multi-step operations, and code modifications.
-models:
-  - zai-coding-cn/glm-5.1
-  - nvidia/mistralai/mistral-small-4-119b-2603
-  - openrouter/nvidia/nemotron-3-super-120b-a12b:free
-  - opencode-go/deepseek-v4-flash
+model: "@coder"
 thinking: medium
 color: yellow
 ---

package/agents/planner.md

@@ -2,10 +2,7 @@
 name: planner
 description: Read-only planning and architecture specialist. Use for consequential design, tradeoff analysis, and implementation plans.
 tools: read, grep, find, ls
-models:
-  - zai-coding-cn/glm-5.3
-  - openrouter/nvidia/nemotron-3-ultra-550b-a55b:free
-  - opencode-go/deepseek-v4-pro
+model: "@smart"
 thinking: high
 color: blue
 sandbox: read-only

package/agents/reviewer.md

@@ -2,10 +2,7 @@
 name: reviewer
 description: Code review specialist. Use for correctness, security, regression, and meaningful test-gap review.
 tools: read, grep, find, ls
-models:
-  - zai-coding-cn/glm-5.3
-  - openrouter/nvidia/nemotron-3-ultra-550b-a55b:free
-  - opencode-go/deepseek-v4-pro
+model: "@smart"
 thinking: high
 color: purple
 sandbox: read-only

package/agents/scout.md

@@ -2,10 +2,7 @@
 name: scout
 description: Fast codebase recon that returns compressed context for handoff. Use for finding files, understanding structure, locating symbols.
 tools: read, grep, find, ls
-models:
-  - zai-coding-cn/glm-5-turbo
-  - nvidia/openai/gpt-oss-20b
-  - opencode-go/deepseek-v4-flash
+model: "@fast"
 thinking: off
 color: cyan
 sandbox: read-only

package/agents/tester.md

@@ -2,10 +2,7 @@
 name: tester
 description: Focused verification agent. Use for cheap routine test, typecheck, lint, build, and regression checks without editing files.
 tools: read, bash, grep, find, ls
-models:
-  - zai-coding-cn/glm-5-turbo
-  - nvidia/openai/gpt-oss-20b
-  - opencode-go/deepseek-v4-flash
+model: "@fast"
 thinking: off
 color: orange
 ---

package/agents/worker.md

@@ -1,11 +1,7 @@
 ---
 name: worker
 description: General-purpose coding agent with full tool access. Use only when explicitly requested for isolated implementation.
-models:
-  - zai-coding-cn/glm-5.1
-  - nvidia/mistralai/mistral-small-4-119b-2603
-  - openrouter/nvidia/nemotron-3-super-120b-a12b:free
-  - opencode-go/deepseek-v4-flash
+model: "@coder"
 thinking: medium
 color: green
 ---

package/extensions/agents.ts

@@ -184,6 +184,8 @@ function loadAgentsFromDir(
     }
     for (const modelName of getModelCandidates({ model, models })) {
       if (modelName.includes("/")) continue;
+      // @role aliases and `*` (parent) are resolved at dispatch — not model ids.
+      if (modelName.startsWith("@") || modelName === "*") continue;
       diagnostics.push({
         filePath,
         issue: `Model "${modelName}" does not include a provider prefix (e.g., "anthropic/claude-sonnet-4-20250514"). Resolution may fail.`,

package/extensions/background.ts

@@ -166,6 +166,19 @@ export function startBackgroundTask(input: StartBackgroundInput): StartBackgroun
   };
   backgroundTasks.set(taskId, bgTask);
 
+  // Record a running entry so a crash mid-run shows as "interrupted" after
+  // restart (recordHistory at completion upserts by id and replaces it).
+  try {
+    appendHistory(join(deps.ctx.cwd, CONFIG_DIR_NAME), {
+      id: taskId,
+      agent,
+      task,
+      status: "running",
+      startedAt,
+      background: true,
+    });
+  } catch { /* history file not writable — non-fatal */ }
+
   // Run detached — the parent does NOT await this.
   void deps
     .runOne(

package/extensions/history.ts

@@ -89,12 +89,15 @@ export function findHistory(piDir: string, id: string): HistoryEntry | undefined
  * On session start, mark any `running` entries from a prior session as
  * `interrupted`. We cannot resume them (in-process SDK sessions don't survive
  * a restart). Honest about the architectural ceiling.
+ *
+ * `excludeIds` skips entries still live in this process (e.g. background tasks
+ * that keep running across a session reload — only shutdown aborts them).
  */
-export function markInterruptedOnRestart(piDir: string): number {
+export function markInterruptedOnRestart(piDir: string, excludeIds: ReadonlySet<string> = new Set()): number {
   const entries = readHistory(piDir);
   let changed = 0;
   for (const e of entries) {
-    if (e.status === "running") {
+    if (e.status === "running" && !excludeIds.has(e.id)) {
       e.status = "interrupted";
       changed++;
     }