@esso0428/pi-subagents 0.17.32 → 0.17.34

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.34] - 2026-10-05
+
+### Added
+- **Documented nested subagents**: README now carries the feature entry, the `allowed_subagents` frontmatter row, and a `### Nested subagents` section covering the allowlist as a privilege boundary, depth cap, ownership scoping, pool behaviour, transcript durability, and how this fork diverges from upstream by rendering children as a navigable subtree. Also records that the mechanism is hand-authored and deliberately absent from the tool description, so a model never grants itself delegation.
+
+## [0.17.33] - 2026-10-05
+
+### Fixed
+- **Nested children now honour `subagents.agentOverrides`**: the overrides were applied only to the global registry at load time, so a nested dispatch resolved the stock definition for a type whose top-level counterpart is overridden — most visibly, `Explore` kept its `anthropic/claude-haiku-4-5` pin and failed with `model_not_supported` no matter what `settings.json` said. The same overrides are now re-applied to the config-derived registry nested resolves against, which also lets an override introduce a type that did not exist as an agent file.
+
 ## [0.17.32] - 2026-10-04
 
 ### Added

package/README.md

@@ -17,6 +17,7 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 - **Agents panel UI** — persistent above-editor widget with animated spinners, live tool activity, token counts, colored status icons, and one focus-gated navigator. It shows every agent by default; press `↓` at an empty prompt to activate the panel, `↑`/`↓` to select, `Enter` to open a live or read-only history viewer, and `Esc` to return. Long rosters reserve a right-hand track/thumb scrollbar and show `↑ N more` or `↓ N more` at the clipped edge. Configure via `/agents → Settings → Widget`: `all`, `background`, or `off`
 - **Conversation viewer** — select any agent in `/agents` to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause). The main viewer reserves a right-hand scrollbar rail for the transcript and exposes a `[preview]` header action for the focused tool. Steer a running agent inline by pressing `e` to open a Pi-native composer, typing, then `Enter` to send (`Esc` or an empty submit returns); the follow-up appears as a muted/gray USER message and redirects the agent after its current tool. `Alt+Up` (`a-up`/`alt+up`) recalls submitted follow-up drafts. Read-only tool previews replace the viewer in place, use the larger viewport with the same right-hand track/thumb scrollbar and top/bottom hidden-line affordances, and return with `Esc`, `q`, or the close control. Stop a still-running agent by pressing `x` (then `x` again to confirm) — both work for background agents too
 - **Custom agent types** — define agents in `.pi/agents/<name>.md` or `.agents/agents/<name>.md` (project) or globally, with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions
+- **Nested subagents** — opt-in, default-off delegation: an agent whose frontmatter sets `allowed_subagents` gets its own ownership-scoped `Agent`, a blocking `wait_for_nested_agent`, and a scoped `steer_subagent`, depth-capped from the main session (default 2). Unlike upstream, nested children are **not** hidden — the agents roster renders them as an indented subtree you can navigate into. The allowlist is a privilege boundary, so it is set by hand in the agent file and never enabled automatically
 - **Mid-run steering** — inject messages into running agents to redirect their work without restarting
 - **Session resume** — pick up where an agent left off, preserving full conversation context
 - **Durable interruption recovery** — catchable shutdowns preserve running/queued metadata and partial transcripts so interrupted agents remain indexed after reload; abrupt `SIGKILL` termination cannot be checkpointed
@@ -246,6 +247,7 @@ All fields are optional — sensible defaults for everything.
 | `skills` | `true` | Inherit skills from parent. Can be a comma-separated list of skill names to preload (see [Skill Preloading](#skill-preloading) for discovery locations) |
 | `memory` | — | Persistent agent memory scope: `project`, `local`, or `user`. Auto-detects read-only agents |
 | `disallowed_tools` | — | Comma-separated tools to deny even if extensions provide them |
+| `allowed_subagents` | none | Opt in to scoped nested `Agent`, `wait_for_nested_agent`, and `steer_subagent` tools. Omitted / empty / `none` / `false` = no nesting; `all` (or `"*"` / `true`) = any enabled agent; comma-separated list = only those agent types |
 | `isolation` | — | Set to `worktree` to run in an isolated git worktree |
 | `model` | inherit parent | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`). Resolved tolerantly (`.`/`-` and a trailing date stamp are interchangeable) and falls back to the same model under another provider if the named one doesn't have it |
 | `thinking` | inherit | off, minimal, low, medium, high, xhigh, max — actual availability depends on your pi version and model; pi clamps unsupported levels down |
@@ -300,6 +302,69 @@ A few rules the examples don't make obvious:
 - `exclude_extensions:` is **not a sandbox**: excluded extensions' factory code still executes once during loading. Exclusion suppresses their tools and their bound lifecycle hooks (`pi.on` handlers like `session_start` only fire for extensions bound to the session), but not other load-time side effects — a factory that subscribes directly to the shared `pi.events` bus stays live. Don't rely on it to contain an untrusted extension.
 - Array and string forms are equivalent: `[a, b]` == `"a, b"`.
 
+### Nested subagents
+
+Nested delegation is default-off and hand-authored. An agent that owns a real
+fan-out responsibility opts in by setting `allowed_subagents` in its own
+frontmatter:
+
+```yaml
+# .pi/agents/support-coordinator.md
+---
+name: support-coordinator
+description: Coordinates support-triage work across several areas
+allowed_subagents: support-file-finder, support-callsite-tracer
+tools: read, grep, find, ls
+---
+```
+
+Omitted, empty, `none`, or `false` means no nested tools are injected at all.
+`all` (or `"*"` / `true`) allows any enabled agent; a comma-separated list
+restricts nesting to exactly those types. Unknown, disabled, and out-of-list
+types are **rejected**, never fallen back to — a configured fallback agent
+cannot hand a nested caller something outside its allowlist.
+
+**The allowlist is a privilege boundary.** A nested child runs with its own tool
+set, so choose it as carefully as you would `tools:`. It is set by hand in the
+agent file and is never enabled automatically; no skill or tool description
+teaches a model to grant itself delegation.
+
+A nested child receives an ownership-scoped `Agent`, a `wait_for_nested_agent`
+that always blocks until that child finishes, and a `steer_subagent` scoped to
+its own children. Result, resume, and steer are ownership-checked, so a parent
+cannot read, steer, or resume a foreign child. `maxSubagentDepth` caps how deep
+nesting goes (default 2: main session 0, its subagents 1, nested children 2);
+an agent already at the cap receives no nested tools at all — not even
+`wait_for_nested_agent` — since it can never own a child. Change it project-wide
+via `maxSubagentDepth` in `subagents.json` or `/agents` → Settings → Nested
+depth. Nested children occupy no concurrency slot: their parent already holds
+one, and queueing a child behind its own parent would deadlock.
+
+Nested children consume **no** concurrency slot and are never reported to the
+main session as top-level agents — their completion surfaces inside the parent,
+and their token usage folds into every ancestor's total. Each still writes its
+own durable transcript.
+
+### How nested children are shown
+
+Upstream hides nested children from every surface. This fork keeps the same
+reporting semantics but makes the hierarchy visible: the agents roster renders
+children as an indented subtree, each with its own spinner and activity line,
+token counts marked `(in parent)` so totals are not double-counted, and a
+`nested blocked: …` note when the allowlist or depth cap refuses a dispatch.
+`↑`/`↓` move across every visible row regardless of depth and `Enter` opens that
+level's conversation viewer. Because the lookup is case-insensitive, an override
+named `Explore` also changes what a lowercase `explore` request resolves to.
+
+The `parentAgentId` and `depth` of a nested child are recorded in its recovery
+checkpoint, so a reload rebuilds the same subtree rather than flattening it. If
+a parent record is ever removed before its child, the child keeps its indent and
+says its parent is gone.
+
+`subagents.agentOverrides` applies to nested dispatch exactly as it does at
+top level, including the project-over-global precedence described in
+[Priority Chain](#priority-chain).
+
 ## `npm:pi-subagents`-Style JSON Agent Overrides
 
 This fork adds the ability to configure — and even create — agents entirely through JSON,

package/ROADMAP.md

@@ -12,6 +12,18 @@
 - v0.17.6 的 ConversationViewer baseline（scrollbar rail、`[preview]`/`[Esc]`、`w` preview、in-place read-only Tool Output、鍵盤與 wheel scroll）不可被改寫
 - 資源安全政策不因功能恢復而撤回：Vitest / E2E / build 在此裝置需明確授權
 
+## 未來：讓模型知道 nested 怎麼用
+
+`allowed_subagents` 目前只能由人手寫進 agent 檔案。上游刻意如此 — 它的 `Agent` 工具描述、`promptGuidelines`、`skills/`、範例 agent 檔全都沒有提 nested，所以模型不會自己開自己的權限。這是對的安全立場，不是缺陷。
+
+若要改善可用性，安全作法是**只教模型怎麼「建議」**，不給它自己開的權限：
+
+- 在建立/編輯 agent 檔案的流程裡提示 `allowed_subagents` 的存在與語意（`all` / 逗號清單 / 省略 = 不開）
+- 明確標示這是授權邊界，該由人確認，不接受模型自行套用
+- 不在 `Agent` 工具描述或 `promptGuidelines` 中指示模型對既有 agent 開啟巢狀
+
+設計前提未定：這段提示該放哪（工具描述、skill、`/agents` 建立精靈的表單、還是 agent 檔的模板註解），以及如何避免模型把「建議」當成「已授權」。
+
 ## 交付 B：Workflow
 
 上游規模約 6,200 行：`src/workflow/**` 11 檔約 4,458 行（`runtime.ts` 1,219 + `worker-source.ts` 781 為骨幹）、`ui/workflow-*.ts` 3 檔約 1,778 行（`workflow-dialog.ts` 1,115 最大）。含 `node:vm` sandbox、worker thread、journal，是新的執行模型而非 UI，風險等級與 nested 不同，不與其他交付合併。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esso0428/pi-subagents",
-  "version": "0.17.32",
+  "version": "0.17.34",
   "description": "A pi extension that brings smart Claude Code-style autonomous sub-agents to pi, with npm:pi-subagents-style JSON agent overrides.",
   "author": "ESSO0428",
   "repository": {

package/src/nested-tools.ts

@@ -22,6 +22,7 @@ import { loadCustomAgents } from "./custom-agents.js";
 import { resolveAgentInvocationConfig } from "./invocation-config.js";
 import { resolveModel } from "./model-resolver.js";
 import { checkModelScope } from "./model-scope.js";
+import { applyNicoOverridesToMap, readNicoAgentOverrides } from "./nico-overrides.js";
 import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./output-file.js";
 import { getStatusNote } from "./status-note.js";
 import type { AgentConfig, AgentInvocation, AgentRecord, IsolationMode, ThinkingLevel } from "./types.js";
@@ -119,6 +120,12 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
       const config = getAgentConfig(name);
       if (config) registry.set(name, config);
     }
+    // `applyNicoOverrides()` runs against the global registry at load, so
+    // `subagents.agentOverrides` in settings.json is not visible here. Apply the
+    // same overrides to this map or a nested child would ignore configuration
+    // that governs the very same agent type one level up.
+    const { overrides, defaultModel } = readNicoAgentOverrides(context.configCwd);
+    applyNicoOverridesToMap(registry, overrides, defaultModel);
     return registry;
   };
   const allowedTypesIn = (registry: Map<string, AgentConfig>): Set<string> | undefined =>