@esso0428/pi-subagents 0.17.31 → 0.17.32

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.32] - 2026-10-04
+
+### Added
+- **Nested subagents with a navigable agents roster**: an agent whose frontmatter sets `allowed_subagents` gets an ownership-scoped `Agent`, an always-blocking `wait_for_nested_agent`, and a scoped `steer_subagent`. The allowlist is a hard boundary — unknown, disabled, and out-of-list types are rejected rather than fallen back to — and `maxSubagentDepth` fails closed, so an agent at the cap receives no nested tools at all. Result, resume, and steer are ownership-checked. Nested children consume no concurrency slot, because their parent already holds one. Unlike upstream, which hides nested children from every surface, the agents roster renders them as an indented subtree: `↑`/`↓` move across all levels and `Enter` opens any level's conversation viewer.
+
+### Fixed
+- **Nested tools are no longer dropped from the active tool set**: the scoped nested `Agent` and `steer_subagent` deliberately share names with `EXCLUDED_TOOL_NAMES`, so the scope gate deleted them and `renarrow()` then dropped them from the active session while `beforeToolCall` rejected them. They are now re-admitted after the gate.
+- **A nested child's durable transcript holds its whole conversation**: streaming never received the transcript path, and the child id was captured after `onSessionCreated` had already fired, so nothing was wired on the detached path. The conversation now persists, and attaching is idempotent so the opening entry is not rewritten over it.
+- **A nested child survives cleanup, and the roster keeps its subtree after a reload**: the child had no `transcriptPath`, so `cleanup()` removed it outright; and checkpoints omitted `parentAgentId`/`depth`, so a reload rebuilt every agent as a root and flattened the tree. Both are now recorded, and an orphaned child keeps its indent and says its parent is gone.
+- **Nested dispatch no longer hard-rejects types the caller can already spawn top-level**: the nested registry is built from config files alone, so types registered at runtime were missing from it. Config-derived entries still win; the global registry only fills genuine gaps.
+
 ## [0.17.31] - 2026-10-04
 
 ### Changed

package/ROADMAP.md

@@ -1,87 +1,43 @@
-# v0.17.17 回退、v0.17.18 registry recovery 與 v0.17.19+ 恢復路線圖
+# pi-subagents 路線圖
 
-本文件是 v0.17.17 的回退邊界與後續恢復決策，不是 runtime 實作計畫，也不承諾任何日曆日期。v0.17.18 只因 npm 保留但未公開 v0.17.17 而重發相同 rollback runtime；v0.17.17 仍是 Git／文件里程碑，第一個未來功能恢復版本從 v0.17.19 開始。主要規格索引是 [`docs/post-0.17.6-feature-specs.md`](docs/post-0.17.6-feature-specs.md)；各階段都必須以該索引及其保存的原始 implementation、測試與 commit 證據為準。
+只記錄**尚未完成**的工作。完成的項目直接移除，不保留完成記錄；功能的完整歷史以 [`CHANGELOG.md`](CHANGELOG.md) 為準。最終狀態是空檔案。
 
-## 目標與不可變邊界
+上游 fork 為 `upstream` remote（`git show upstream/master:<path>`）。後續只做 feature port，不做 large upstream merge。
 
-- [x] 將 v0.17.17 定義為 intentional rollback：runtime/UI reset to v0.17.6 的 [`64bbbb0`](https://github.com/ESSO0428/pi-subagents/commit/64bbbb0)，而不是把後續功能當成已恢復功能。
-- [x] 保留 v0.17.6 的 ConversationViewer interaction baseline：scrollbar rail、`[preview]`/`[Esc]`、`w` focused-tool preview、in-place read-only Tool Output preview、keyboard/wheel scroll、focus 與 layout 行為。
-- [x] 在回退 runtime/UI 的同時保留 resource-policy metadata、資源規則與文件；特別是目前的 resource-safe local verification 政策（Vitest、E2E、build 需要明確授權，以及既有 worker/resource 限制）不得因功能恢復而被撤回。
-- [x] 保存 post-v0.17.6 規格與證據索引；文件保存不代表 v0.17.17 已重新提供該功能。
-- [ ] 後續任何恢復都必須先通過單一功能的證據與人工 UI latency acceptance，才可考慮與其他已驗證功能組合。
+## 仍成立的恢復規則
 
-## v0.17.17 回退內容
+- 一次只做一個功能邊界；功能與 UI 同時交付，不留看不見的中間狀態
+- 每項都要有對應的 archived spec 與上游 implementation/test/commit 證據
+- UI 功能必須有人工操作紀錄（terminal 尺寸、操作步驟、畫面結果、可見延遲）。不要把「測試通過」單獨當成 latency acceptance
+- v0.17.6 的 ConversationViewer baseline（scrollbar rail、`[preview]`/`[Esc]`、`w` preview、in-place read-only Tool Output、鍵盤與 wheel scroll）不可被改寫
+- 資源安全政策不因功能恢復而撤回：Vitest / E2E / build 在此裝置需明確授權
 
-- [x] runtime 與 UI 以 `64bbbb0`（v0.17.6）為基準；不得用 upstream viewer、FleetView 或 overlay 覆蓋既有 v0.17.6 viewer contract。
-- [x] 保留資源政策的文件與 metadata，不把 resource-policy rollback 混入功能 rollback；恢復功能也不得移除 `AGENTS.md`、CHANGELOG、package/Vitest 設定中對資源安全的約束。
-- [x] 本次交付只保存 Markdown 路線圖與既有規格索引；不修改 runtime source、package metadata，不 publish，也不在本路線圖階段執行 Vitest、E2E 或 build。
-- [ ] 將所有 post-v0.17.6 功能視為「待證據恢復」，而非在 v0.17.17 中隱式保留或半恢復。
+## 交付 B：Workflow
 
-## v0.17.17 暫時移除的功能與保存規格
+上游規模約 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 不同，不與其他交付合併。
 
-以下功能在 v0.17.17 runtime/UI 回到 v0.17.6 時暫時不提供；每項都保留可追溯的 archived spec。這些勾選項是恢復清單，不表示本次要在 runtime 中實作。
+- API：`agent()` / `parallel()` / `pipeline()` / `phase()` / `log()` / `args()`
+- `pipeline()` stage 之間無 barrier；`parallel()` 是 barrier
+- `agent({ gate: "npm test" })` 以執行指令驗證 child；`agent({ resume: "<label>" })` 接續 child
+- live card + `/agents → Workflows` 兩欄 inspector
+- workflow 自己擁有的 agents 不列於任何 top-level surface，由 run 負責回報
+- 若 `docs/workflows.md`（現有 30 KB）在交付時仍描述尚未實作的行為，需一併收斂
 
-- [ ] **Durable agent history、transcript 與重新開啟**：`.pi-subagents` JSONL、partial turns、GC 後的 read-only history 與安全 locator。保存於 [`docs/post-0.17.6-durable-history-spec.md`](docs/post-0.17.6-durable-history-spec.md)。
-- [ ] **Workflow、lifecycle events 與 cross-extension RPC**：ready/created/completed 等 lifecycle、RPC ownership/consume、deterministic Workflow host 與 journal。保存於 [`docs/post-0.17.6-workflow-rpc-lifecycle-spec.md`](docs/post-0.17.6-workflow-rpc-lifecycle-spec.md)。
-- [ ] **Nested agents**：child-safe tool context、parent ownership、depth cap、allowlist、foreground/background 與 recursive cleanup。保存於 [`docs/post-0.17.6-nested-agents-spec.md`](docs/post-0.17.6-nested-agents-spec.md)。
-- [ ] **Recovery、stop/abort 與 shutdown**：checkpoint、partial recovery、terminal record、abort/queue 喚醒、`session_shutdown` 順序與 bounded cleanup。保存於 [`docs/post-0.17.6-recovery-shutdown-spec.md`](docs/post-0.17.6-recovery-shutdown-spec.md)。
-- [ ] **Agents roster、history navigation 與 ConversationViewer 整合**：single AgentWidget roster、selector input ownership、history row、viewer reopen 與 nested row 語意。保存於 [`docs/post-0.17.6-agents-roster-viewer-spec.md`](docs/post-0.17.6-agents-roster-viewer-spec.md)。
-- [ ] **Render-cost 與 UI latency 修復**：ConversationTimeline bounded cache、render path 不讀檔、AgentWidget cache、單一 roster、短 terminal 的 editor budget 與 redraw 限制。保存於 [`docs/post-0.17.6-ui-latency-baseline-spec.md`](docs/post-0.17.6-ui-latency-baseline-spec.md)。
-- [x] **v0.17.6 baseline 本身不是待移除功能**：其 viewer rail/preview/read-only 行為是所有後續恢復的不可回退基線；完整索引仍見 [`docs/post-0.17.6-feature-specs.md`](docs/post-0.17.6-feature-specs.md)。
+### 引導機制（不可省略）
 
-## 恢復證據規則
+上游不靠被動技能，靠**工具描述中的選擇準則**。`SubagentWorkflow` 的 `promptGuidelines` 明寫「何時用 Workflow、何時用 Agent」以及「優先 `pipeline` 而非 `parallel`」。沒有這段引導，模型不會主動選工具。任何功能恢復都必須同時交付引導文字。
 
-- [ ] 每次恢復只選一個功能邊界，先從主索引找到對應 archived spec，再核對其中的原始 implementation files、tests、commit/tag 與既有錯誤語意。
-- [ ] 先建立 v0.17.6 baseline evidence：確認 viewer rail、preview、focus、keyboard/wheel scroll 與 read-only history 的行為沒有被待恢復變更改寫。
-- [ ] 對資料與安全邊界先取證：project-relative transcript/checkpoint、path traversal 拒絕、ownership、allowlist、depth cap、lifecycle 順序都要有可重現的證據。
-- [ ] 對 UI 功能另外保存人工操作紀錄：terminal 尺寸、操作步驟、畫面結果、可見延遲與任何回歸；不要把「測試通過」單獨當成 latency acceptance。
-- [ ] 若證據不足、行為與 archived spec 不一致，或人工操作出現可見卡頓，該功能停留在待恢復狀態，不與其他功能合併。
-- [ ] 本文件本身不執行 Vitest、E2E 或 build；恢復工作是否需要這些檢查，依當時授權與 `AGENTS.md` 的資源政策處理。
+## pi-tui 版本分裂（需使用者決策）
 
-## v0.17.19 的決策：只恢復 durable history 基礎層
+本 extension 宣告 peer `@earendil-works/pi-tui >=0.80.8`，但在 `~/.pi/agent/npm` 實際解析到 `0.74.2`，pi host 使用 `1.0.0`。後果是 `agent-widget.ts` 的 `focused instanceof Editor` 恆 false，roster `↑`/`↓` 在此環境 inert。
 
-- [ ] 將 v0.17.19 限定為第一個、可獨立驗證的 durable history/recovery data plane：先處理 transcript 格式、project-local path safety、checkpoint metadata 與 flush/attach seam。
-- [ ] 以 [`docs/post-0.17.6-durable-history-spec.md`](docs/post-0.17.6-durable-history-spec.md) 和 [`docs/post-0.17.6-recovery-shutdown-spec.md`](docs/post-0.17.6-recovery-shutdown-spec.md) 為證據邊界；不得順便恢復 nested agents、Workflow/RPC、FleetView 或整套 Agents UI。
-- [ ] 確保 `output_transcript: false` 不會關閉 `.pi-subagents` durable history，且 GC/session cleanup 不會刪除仍可讀的 terminal record；壞 locator、壞 JSON 或 traversal input 必須 fail safely。
-- [ ] 在接受 v0.17.19 前，人工確認既有 v0.17.6 viewer interaction 沒有 layout/focus/scroll regression；若此基礎層不改 UI，也仍要記錄 baseline 操作結果。
-- [ ] v0.17.19 不承諾任何日曆日期；版本成立條件是上述單一功能的證據完整，而不是時間到期或功能數量達標。
+阻擋者：`@nklisch/pi-mcp-adapter`（`^0.74.0`）與 `@aliou/pi-utils-ui`（`>=0.74.0 <1`）。inert 是刻意的安全失效——改用結構式探針會讓 widget 從其他擴充套件的對話框搶走方向鍵（曾發生，見 0.17.23/0.17.28）。根治需調整 host 端相依圖。
 
-## v0.17.19 之後的證據驅動順序
+## 未來：`/workflow` 使用者指令
 
-每一列都是獨立候選恢復項；「後續版本」只代表通過前一項 acceptance 後再決定的版本，不預設版本號或日期。
+讓使用者能主動要求 workflow，而非完全依賴模型自行判斷。設計前提未定：
 
-| 順序 | 單一恢復項 | 主要證據與邊界 |
-|---|---|---|
-| 1 | Durable history 的 history list、read-only reopen 與 reload | [`durable-history`](docs/post-0.17.6-durable-history-spec.md)：先完成 history row/viewer wiring，再接各 spawn path；不得執行 tool 或改寫 transcript。 |
-| 2 | Recovery 的 restore、stop/abort 與 child shutdown | [`recovery-shutdown`](docs/post-0.17.6-recovery-shutdown-spec.md)：先保留 checkpoint/flush，再加入 `restoreRecovered`、queue wake-up 與 `session_shutdown` ordering。 |
-| 3 | Single Agents roster 與 selector ownership | [`agents-roster-viewer`](docs/post-0.17.6-agents-roster-viewer-spec.md)：先 cache durable rows/selection，再處理 selector input；不得重新引入已移除的 duplicate FleetView。 |
-| 4 | ConversationViewer 與 roster 的 latency/render bounds | [`ui-latency-baseline`](docs/post-0.17.6-ui-latency-baseline-spec.md)：bounded cache、render 不讀檔、arrow 不重建 widget、單一 roster、短 terminal 保留 editor 空間。 |
-| 5 | Nested agent ownership 與 lifecycle | [`nested-agents`](docs/post-0.17.6-nested-agents-spec.md)：先恢復 child-safe context、ownership/depth/allowlist，再接 manager spawn/abort/history；foreground/background 與 print-mode 另行取證。 |
-| 6 | Lifecycle events 與 cross-extension RPC | [`workflow-rpc-lifecycle`](docs/post-0.17.6-workflow-rpc-lifecycle-spec.md)：先恢復 event/RPC protocol、scope 與 ownership/consume，再接非 top-level child 的 activity 顯示。 |
-| 7 | Workflow worker、journal、schema 與 UI | [`workflow-rpc-lifecycle`](docs/post-0.17.6-workflow-rpc-lifecycle-spec.md)：最後接 Workflow host/runtime/UI；Workflow child 必須保留自己的 durable transcript，不得冒充 top-level roster。 |
-
-- [ ] 每完成一列，先獨立取證並完成人工 UI latency acceptance，再開始下一列。
-- [ ] 若某列需要前列的 seam，仍只接入必要依賴，不把後列功能預先帶入；依賴關係不能成為一次恢復多個 user-facing feature 的理由。
-
-## 人工 UI latency acceptance 門檻
-
-- [ ] **Viewer baseline**：在短、一般與較長 terminal 高度下，檢查 transcript scrollbar rail、hidden content、sticky/focus/search、`[preview]`、`[Esc]`、`w`、鍵盤與 wheel scroll；Tool Output preview 必須仍是 parent-owned、read-only、in-place。
-- [ ] **History path**：從 running、completed、stopped、recovered record 開啟 viewer，關閉後回到原 selector；selected row/viewport 不應跳回第一列，GC 後仍能從 durable transcript 讀取。
-- [ ] **Roster path**：大量 agent activity、長 transcript、多行 activity 與短 terminal 下，只有一個 roster；selector 開啟時 background widget 不得搶 key，editor 必須保留最小空間。
-- [ ] **Render path**：人工觀察長歷史與頻繁事件時沒有隨歷史長度惡化的可見卡頓；同時以規格列出的 perf guards 驗證 render 不做 filesystem I/O，並記錄證據而非臆測數字門檻。
-- [ ] **失敗處理**：任何可見延遲、focus/layout 變化、重複 redraw、stale row 或 history 消失都代表該單一功能未接受；先隔離或回退該變更，不得進入組合 release。
-
-## 0.17.19 與後續 release 的組合決策
-
-- [ ] **v0.17.19**：只接受 durable history/recovery 基礎層；不把 Agents UI、nested、RPC 或 Workflow 當作同一 release 的附帶恢復。
-- [ ] **後續版本**：只有已在獨立變更中完成 spec、targeted evidence 與人工 UI latency acceptance 的功能，才可在後續 release 與另一個已接受功能組合。
-- [ ] 組合前要重新執行人工回歸矩陣，特別是 viewer baseline、selector input ownership、長 transcript render 與 resource-policy metadata；單項通過不等於組合後通過。
-- [ ] 若組合回歸失敗，拆回最後一個已接受的功能邊界；不得為了湊版本內容而放寬 acceptance 或重新引入 duplicate UI。
-- [ ] 版本號只在證據與 release gate 都成立後決定；本路線圖不指定未來日期、不 publish、不替使用者執行 release 操作。
-
-## 完成定義與範圍守則
-
-- [ ] 每個恢復項都有對應 archived spec、implementation/test/commit evidence、人工 UI latency 紀錄與明確的保留/回退決策。
-- [ ] 所有恢復都維持 `64bbbb0` 的 viewer baseline，並保留 resource-policy metadata、資源規則與文件。
-- [ ] 不以功能數量、日期或單次自動檢查取代逐項 acceptance；不可接受的功能留在文件化的待恢復狀態。
-- [x] 本次工作只新增本根目錄 `ROADMAP.md`；沒有 runtime edits、測試、build 或 publish。
+- 與 `Agent` 工具自動產生的 workflow 如何劃分責任
+- 已儲存腳本（上游 `examples/workflows/`）的存放位置與發現方式
+- 是否與 `/agents → Workflows` inspector 合併，或作為其快捷入口
+- 是否接受 inline 腳本，或只接受已儲存腳本

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esso0428/pi-subagents",
-  "version": "0.17.31",
+  "version": "0.17.32",
   "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/abortable.ts

@@ -0,0 +1,14 @@
+/** Reject a wait when its caller aborts without aborting the underlying work. */
+export function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(new DOMException("The operation was aborted", "AbortError"));
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(new DOMException("The operation was aborted", "AbortError"));
+    signal.addEventListener("abort", onAbort, { once: true });
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    promise.then(
+      value => { cleanup(); resolve(value); },
+      error => { cleanup(); reject(error); },
+    );
+  });
+}

package/src/agent-manager.ts

@@ -20,6 +20,7 @@ import {
   writeAgentRecoveryCheckpoint,
 } from "./agent-recovery.js";
 import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
+import type { NestedSpawnOptions } from "./nested-tools.js";
 import type { AgentInvocation, AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
 import { addUsage } from "./usage.js";
 import { cleanupWorktree, createWorktree, pruneWorktrees, } from "./worktree.js";
@@ -157,7 +158,7 @@ interface SpawnArgs {
   options: SpawnOptions;
 }
 
-interface SpawnOptions {
+export interface SpawnOptions extends Partial<Omit<NestedSpawnOptions, "description" | "signal" | "onAssistantUsage" | "onSessionCreated">> {
   description: string;
   model?: Model<any>;
   maxTurns?: number;
@@ -198,6 +199,8 @@ interface SpawnOptions {
   onTurnEnd?: (turnCount: number) => void;
   /** Called once per assistant message_end with that message's usage delta. */
   onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
+  /** Called when nested delegation is refused, for observability. */
+  onNestedIssue?: (issue: string) => void;
   /** Called when the session successfully compacts. */
   onCompaction?: (info: CompactionInfo) => void;
   /** Called synchronously after the record exists, before it is queued or started. */
@@ -277,6 +280,10 @@ export class AgentManager {
       ...(record.error !== undefined && { error: record.error }),
       ...(record.transcriptPath !== undefined && { transcriptPath: record.transcriptPath }),
       ...(record.invocation !== undefined && { invocation: cloneInvocation(record.invocation) }),
+      // Without these a reload rebuilds every agent as a root and the roster
+      // flattens, because nothing on disk records the nesting.
+      ...(record.parentAgentId !== undefined && { parentAgentId: record.parentAgentId }),
+      ...(record.depth !== undefined && { depth: record.depth }),
     };
     return checkpoint;
   }
@@ -379,6 +386,18 @@ export class AgentManager {
       isBackground: options.isBackground,
       invocation: options.invocation,
       waitGroupId: options.waitGroupId,
+      depth: options.depth ?? 1,
+      parentAgentId: options.parentAgentId,
+      parentDescription: options.parentAgentId ? this.agents.get(options.parentAgentId)?.description : undefined,
+      maxSubagentDepth: options.maxSubagentDepth,
+      rootSessionId: options.rootSessionId ?? ctx.sessionManager?.getSessionId?.(),
+      liveActivity: {
+        activeTools: new Map(),
+        responseText: "",
+        turnCount: 0,
+        maxTurns: options.maxTurns,
+        session: undefined,
+      },
     };
     this.agents.set(id, record);
     this.recoveryCwds.set(id, ctx.cwd);
@@ -397,7 +416,9 @@ export class AgentManager {
 
     const args: SpawnArgs = { pi, ctx, type, prompt, options };
 
-    if (options.isBackground && !options.bypassQueue && this.runningBackground >= this.maxConcurrent) {
+    // Nested children never consume or wait for a top-level concurrency slot;
+    // queueing behind the parent would deadlock an inline nested spawn.
+    if (options.isBackground && !options.parentAgentId && !options.bypassQueue && this.runningBackground >= this.maxConcurrent) {
       // Queue it — will be started when a running agent completes
       this.queue.push({ id, args });
       return id;
@@ -453,7 +474,7 @@ export class AgentManager {
     record.status = "running";
     record.startedAt = Date.now();
     this.checkpoint(record);
-    if (options.isBackground) {
+    if (options.isBackground && !options.parentAgentId) {
       this.runningBackground++;
       this.runningBackgroundIds.add(id);
     }
@@ -485,11 +506,27 @@ export class AgentManager {
       configCwd: customCwd !== undefined ? ctx.cwd : undefined,
       signal: record.abortController!.signal,
       onToolActivity: (activity) => {
+        const live = record.liveActivity;
+        if (live) {
+          if (activity.type === "start") {
+            live.activeTools.set(`${activity.toolName}:${Date.now()}:${live.activeTools.size}`, activity.toolName);
+          } else {
+            for (const [key, name] of live.activeTools) {
+              if (name === activity.toolName) { live.activeTools.delete(key); break; }
+            }
+          }
+        }
         if (activity.type === "end") record.toolUses++;
         options.onToolActivity?.(activity);
       },
-      onTurnEnd: options.onTurnEnd,
-      onTextDelta: options.onTextDelta,
+      onTurnEnd: (turnCount) => {
+        if (record.liveActivity) record.liveActivity.turnCount = turnCount;
+        options.onTurnEnd?.(turnCount);
+      },
+      onTextDelta: (delta, fullText) => {
+        if (record.liveActivity) record.liveActivity.responseText = fullText;
+        options.onTextDelta?.(delta, fullText);
+      },
       onAssistantUsage: (usage) => {
         addUsage(record.lifetimeUsage, usage);
         options.onAssistantUsage?.(usage);
@@ -499,8 +536,20 @@ export class AgentManager {
         this.onCompact?.(record, info);
         options.onCompaction?.(info);
       },
+      onNestedIssue: (issue) => {
+        record.nestedIssue = issue;
+        options.onNestedIssue?.(issue);
+      },
+      nestedRuntime: {
+        manager: this,
+        parentAgentId: id,
+        depth: record.depth ?? 1,
+        maxSubagentDepth: options.maxSubagentDepth,
+      },
+      nestedSession: options.parentAgentId !== undefined,
       onSessionCreated: (session) => {
         record.session = session;
+        if (record.liveActivity) record.liveActivity.session = session;
         const model = session.model;
         record.invocation = {
           ...(record.invocation ?? {}),
@@ -760,6 +809,8 @@ export class AgentManager {
     transcriptPath?: string;
     invocation?: AgentInvocation;
     compactionCount?: number;
+    parentAgentId?: string;
+    depth?: number;
   }): AgentRecord {
     return {
       id: record.id,
@@ -777,9 +828,36 @@ export class AgentManager {
         ? { ...record.lifetimeUsage }
         : { input: 0, output: 0, cacheWrite: 0 },
       compactionCount: record.compactionCount ?? 0,
+      parentAgentId: record.parentAgentId,
+      depth: record.depth,
     };
   }
 
+  /** Record a nested refusal so the widget and viewer retain the explanation. */
+  reportNestedIssue(parentAgentId: string, issue: string): void {
+    const record = this.agents.get(parentAgentId);
+    if (record) record.nestedIssue = issue;
+  }
+
+  /** Run one nested child inline without charging either concurrency pool. */
+  async spawnAndWait(
+    pi: ExtensionAPI,
+    ctx: ExtensionContext,
+    type: string,
+    prompt: string,
+    options: Omit<SpawnOptions, "isBackground">,
+    onSpawned?: (id: string) => void,
+  ): Promise<{ id: string; record: AgentRecord }> {
+    const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false, onSpawned });
+    const record = this.agents.get(id);
+    if (!record) throw new Error(`Nested agent "${id}" disappeared during startup.`);
+    if (record.promise) await record.promise;
+    return { id, record };
+  }
+
+  /** Current manager starts synchronously; retained for the nested tool contract. */
+  async awaitStartup(_id: string): Promise<void> {}
+
   abort(id: string): boolean {
     const record = this.agents.get(id);
     if (!record) return false;

package/src/agent-recovery.ts

@@ -32,6 +32,10 @@ export interface AgentRecoveryCheckpoint {
   compactionCount: number;
   transcriptPath?: string;
   invocation?: AgentInvocation;
+  /** Owning agent for a nested child. Survives reload so the roster keeps its tree. */
+  parentAgentId?: string;
+  /** Nesting depth of a nested child; absent on top-level agents. */
+  depth?: number;
 }
 
 function isSafeString(value: unknown, maxLength: number): value is string {
@@ -99,6 +103,9 @@ export function isAgentRecoveryCheckpoint(value: unknown): value is AgentRecover
     || !Number.isInteger(checkpoint.compactionCount)
     || (checkpoint.compactionCount as number) < 0) return false;
 
+  if (checkpoint.parentAgentId !== undefined && !isSafeString(checkpoint.parentAgentId, 256)) return false;
+  if (checkpoint.depth !== undefined && (!Number.isInteger(checkpoint.depth) || (checkpoint.depth as number) < 0)) return false;
+
   const status = checkpoint.status as AgentRecoveryStatus;
   if (!isActiveStatus(status) && !isTerminalStatus(status)) return false;
   if (checkpoint.completedAt !== undefined && !isFiniteTimestamp(checkpoint.completedAt)) return false;

package/src/agent-runner.ts

@@ -18,10 +18,12 @@ import {
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
+import { runInChildSessionContext } from "./child-context.js";
 import { buildParentContext, extractText } from "./context.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";
 import { detectEnv } from "./env.js";
 import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
+import { createNestedSubagentTools, getMaxSubagentDepth, type NestedAgentManager } from "./nested-tools.js";
 import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
 import { preloadSkills } from "./skill-loader.js";
 import type { SubagentType, ThinkingLevel } from "./types.js";
@@ -232,9 +234,18 @@ export function installExtensionToolScope(
     disallowedSet: Set<string> | undefined;
     extNames: Set<string>;
     narrowing: Map<string, Set<string>>;
+    /**
+     * Injected `customTools` that must survive the scope gate. They are deleted
+     * below along with `EXCLUDED_TOOL_NAMES` — the scoped nested `Agent` and
+     * `steer_subagent` deliberately share those names — so they have to be
+     * re-admitted or `renarrow` drops them from the active set and
+     * `beforeToolCall` rejects them. Already filtered against `disallowed_tools`
+     * by the caller, which is the only place that knows what may be taken back.
+     */
+    readmitToolNames: Set<string>;
   },
 ): void {
-  const { loader, toolNames, disallowedSet, extNames, narrowing } = ctx;
+  const { loader, toolNames, disallowedSet, extNames, narrowing, readmitToolNames } = ctx;
 
   // The names allowed right now. Mirrors the `ext:` opt-in flip: when any `ext:`
   // selector is present, extension tools become an explicit allowlist — a loaded
@@ -256,6 +267,7 @@ export function installExtensionToolScope(
       }
     }
     for (const name of EXCLUDED_TOOL_NAMES) keep.delete(name);
+    for (const name of readmitToolNames) keep.add(name);
     return keep;
   };
 
@@ -394,6 +406,17 @@ export interface RunOptions {
    * pre-compaction context size estimate. Aborted compactions don't fire.
    */
   onCompaction?: (info: { reason: "manual" | "threshold" | "overflow"; tokensBefore: number }) => void;
+  /** Called when nested delegation is unavailable or refused. */
+  onNestedIssue?: (issue: string) => void;
+  /** Runtime bridge for ownership-scoped nested delegation. */
+  nestedRuntime?: {
+    manager: NestedAgentManager;
+    parentAgentId: string;
+    depth: number;
+    maxSubagentDepth?: number;
+  };
+  /** True only for an agent spawned by another agent, not a top-level owner. */
+  nestedSession?: boolean;
 }
 
 export interface RunResult {
@@ -647,7 +670,7 @@ export async function runAgent(
     systemPromptOverride: () => systemPrompt,
     appendSystemPromptOverride: () => [],
   });
-  await loader.reload();
+  await runInChildSessionContext(() => loader.reload());
 
   // Plain entries in `tools:` are expected to be built-in names (extension tools
   // go through `ext:`), so an unknown name there is unambiguously a typo. Previously
@@ -730,6 +753,29 @@ export async function runAgent(
     ? new Set(agentConfig.disallowedTools)
     : undefined;
 
+  // Nested tools are built for this session and injected directly. Nested child
+  // sessions deliberately do not bind the pi-subagents extension again: doing
+  // so would register a second global manager and expose unscoped tools.
+  const effectiveMaxDepth = options.nestedRuntime?.maxSubagentDepth ?? getMaxSubagentDepth();
+  const nestedRuntime = options.nestedRuntime && options.nestedRuntime.depth < effectiveMaxDepth
+    ? options.nestedRuntime
+    : undefined;
+  if (options.nestedRuntime && options.nestedRuntime.depth >= effectiveMaxDepth && agentConfig?.allowedSubagents) {
+    options.onNestedIssue?.(`depth cap: nested delegation unavailable at depth ${options.nestedRuntime.depth} (max ${effectiveMaxDepth})`);
+  }
+  const nestedTools = agentConfig?.allowedSubagents && nestedRuntime && !options.isolated
+    ? createNestedSubagentTools({
+        manager: nestedRuntime.manager,
+        pi: options.pi,
+        parentAgentId: nestedRuntime.parentAgentId,
+        depth: nestedRuntime.depth,
+        maxSubagentDepth: effectiveMaxDepth,
+        allowedSubagents: agentConfig.allowedSubagents,
+        configCwd,
+      })
+    : [];
+  const nestedToolNames = new Set(nestedTools.map(tool => tool.name));
+
   // ─── Tool scoping ───────────────────────────────────────────────────────
   //
   // Some extensions register their tools ASYNCHRONOUSLY, long after the
@@ -762,11 +808,12 @@ export async function runAgent(
   let sessionTools: string[] | undefined;
   let sessionExcludeTools: string[] | undefined;
   if (noExtensions) {
-    sessionTools = toolNames.filter(
-      (t) => !EXCLUDED_TOOL_NAMES.includes(t) && !disallowedSet?.has(t),
-    );
+    sessionTools = [
+      ...toolNames.filter((t) => !EXCLUDED_TOOL_NAMES.includes(t) && !disallowedSet?.has(t)),
+      ...[...nestedToolNames].filter(t => !disallowedSet?.has(t)),
+    ];
   } else {
-    const denyTools = new Set<string>(EXCLUDED_TOOL_NAMES);
+    const denyTools = new Set<string>(EXCLUDED_TOOL_NAMES.filter(name => !nestedToolNames.has(name)));
     // Keep only the built-ins the agent asked for — deny the rest.
     for (const name of BUILTIN_TOOL_NAMES) {
       if (!builtinToolNameSet.has(name)) denyTools.add(name);
@@ -793,6 +840,7 @@ export async function runAgent(
   // modelRuntime, but ExtensionContext still exposes only the registry facade.
   // Pass both so the full supported Pi range retains the parent's providers.
   const parentModelRuntime = (ctx.modelRegistry as unknown as { runtime?: ModelRuntime | null }).runtime ?? undefined;
+  const customTools = [...nestedTools, ...(trackedWriteTool ? [trackedWriteTool as any] : [])];
   const sessionOpts: Parameters<typeof createAgentSession>[0] & {
     modelRegistry: ExtensionContext["modelRegistry"];
     modelRuntime?: ModelRuntime;
@@ -810,7 +858,7 @@ export async function runAgent(
     // fresh interactive app startup. Mark their extension lifecycle as a fork so
     // startup-only UI/theme extensions do not clear or rewrite the parent TUI.
     sessionStartEvent: { type: "session_start", reason: "fork" },
-    ...(trackedWriteTool && { customTools: [trackedWriteTool as any] }),
+    ...(customTools.length > 0 && { customTools }),
   };
   if (sessionExcludeTools) {
     sessionOpts.excludeTools = sessionExcludeTools;
@@ -819,7 +867,8 @@ export async function runAgent(
     sessionOpts.thinkingLevel = thinkingLevel;
   }
 
-  const { session } = await createAgentSession(sessionOpts);
+  const { session } = await runInChildSessionContext(() => createAgentSession(sessionOpts));
+
 
   const baseSessionName = agentConfig?.name ?? type;
   session.setSessionName(
@@ -830,14 +879,16 @@ export async function runAgent(
   // (e.g. loading credentials, setting up state). Tool gating already happened
   // at session construction via the `tools:` allowlist above — no separate
   // post-bind filter is needed. All ExtensionBindings fields are optional.
-  await session.bindExtensions({
-    onError: (err) => {
-      options.onToolActivity?.({
-        type: "end",
-        toolName: `extension-error:${err.extensionPath}`,
-      });
-    },
-  });
+  if (!options.nestedSession) {
+    await session.bindExtensions({
+      onError: (err) => {
+        options.onToolActivity?.({
+          type: "end",
+          toolName: `extension-error:${err.extensionPath}`,
+        });
+      },
+    });
+  }
 
   // With `allowedToolNames` unset, the registry is scoped by `excludeTools` but
   // the ACTIVE set still needs managing: pi activates only its four default
@@ -845,13 +896,14 @@ export async function runAgent(
   // (we can't deny the name of a tool that hasn't registered yet). Both are
   // handled below by re-deriving scope from the loader's live extension maps —
   // `registerTool` writes into those same maps, so late arrivals are judged too.
-  if (!noExtensions) {
+  if (!noExtensions && !options.nestedSession) {
     installExtensionToolScope(session, {
       loader,
       toolNames,
       disallowedSet,
       extNames,
       narrowing,
+      readmitToolNames: new Set([...nestedToolNames].filter((name) => !disallowedSet?.has(name))),
     });
   }