@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

package/node_modules/@herbertgao/pi-cc-extensions/extensions/renderer/tool/grouping.ts

@@ -8,7 +8,7 @@ import {
 } from "@earendil-works/pi-tui";
 import { TOOL_LOADING_INTERVAL_MS, toolLoadingIcon } from "../../utils/tool-loading-icon.ts";
 import { sanitizeToolResultText } from "../../utils/tool-result-sanitize.ts";
-import { showMoreHintText } from "../show-more-hint.ts";
+import { isToolTuiFullscreen, showMoreHintText } from "../show-more-hint.ts";
 
 const PATCH_KEY = Symbol.for("pi.ccstyle.tool-grouping-patch");
 const PARENT_KEY = Symbol.for("pi.ccstyle.tool-grouping-parent");
@@ -274,6 +274,17 @@ function groupChildWidth(width: number): number {
 	return Math.max(1, panelInnerWidth(width));
 }
 
+type SettledGroupCache = {
+	width: number;
+	hover: boolean;
+	theme: unknown;
+	fullscreen: boolean;
+	children: readonly unknown[];
+	args: unknown[];
+	results: unknown[];
+	lines: string[];
+};
+
 export class ToolGroupComponent extends Container {
 	readonly toolCallId = `ccstyle-tool-group-${nextGroupId++}`;
 	readonly toolName = "Tool group";
@@ -284,6 +295,8 @@ export class ToolGroupComponent extends Container {
 	}
 	private hintHovered = false;
 	private readonly patch: Patch;
+	/** 仅缓存已完成且折叠的分组；pending / expanded 每帧现算。 */
+	private settledCache: SettledGroupCache | undefined;
 
 	constructor(patch: Patch) {
 		super();
@@ -292,11 +305,13 @@ export class ToolGroupComponent extends Container {
 	}
 
 	addTool(tool: any): void {
+		this.settledCache = undefined;
 		this.children.push(tool);
 		tool[PARENT_KEY] = this;
 	}
 
 	releaseTools(): any[] {
+		this.settledCache = undefined;
 		const tools = [...this.children];
 		this.children.length = 0;
 		this.patch.groups.delete(this);
@@ -304,18 +319,21 @@ export class ToolGroupComponent extends Container {
 	}
 
 	removeTool(tool: any): void {
+		this.settledCache = undefined;
 		const index = this.children.indexOf(tool);
 		if (index >= 0) this.children.splice(index, 1);
 		if (tool?.[PARENT_KEY] === this) delete tool[PARENT_KEY];
 	}
 
 	setExpanded(expanded: boolean): void {
+		if (this._expanded !== expanded) this.settledCache = undefined;
 		this._expanded = expanded;
 		for (const tool of this.children)
 			(tool as Component & { setExpanded?: (expanded: boolean) => void }).setExpanded?.(expanded);
 	}
 
 	setHintHovered(hovered: boolean): void {
+		if (this.hintHovered !== hovered) this.settledCache = undefined;
 		this.hintHovered = hovered;
 	}
 
@@ -344,10 +362,53 @@ export class ToolGroupComponent extends Container {
 	}
 
 	invalidate(): void {
+		this.settledCache = undefined;
 		for (const tool of this.children) tool.invalidate?.();
 	}
 
+	private settledCacheHit(width: number): string[] | undefined {
+		const cache = this.settledCache;
+		if (!cache || this._expanded) return;
+		if (
+			cache.width !== width ||
+			cache.hover !== this.hintHovered ||
+			cache.theme !== this.patch.theme ||
+			cache.fullscreen !== isToolTuiFullscreen()
+		) {
+			return;
+		}
+		const tools = this.children as any[];
+		if (cache.children.length !== tools.length) return;
+		for (let i = 0; i < tools.length; i++) {
+			const tool = tools[i];
+			if (
+				cache.children[i] !== tool ||
+				cache.args[i] !== tool?.args ||
+				cache.results[i] !== tool?.result ||
+				status(tool) === "pending"
+			) {
+				return;
+			}
+		}
+		return cache.lines;
+	}
+
+	private storeSettledCache(width: number, lines: string[]): void {
+		this.settledCache = {
+			width,
+			hover: this.hintHovered,
+			theme: this.patch.theme,
+			fullscreen: isToolTuiFullscreen(),
+			children: [...this.children],
+			args: (this.children as any[]).map((tool) => tool?.args),
+			results: (this.children as any[]).map((tool) => tool?.result),
+			lines,
+		};
+	}
+
 	render(width: number): string[] {
+		const cached = this.settledCacheHit(width);
+		if (cached) return cached;
 		const theme = this.patch.theme;
 		const fg = (color: string, text: string) => theme?.fg?.(color, text) ?? text;
 		const counts = { pending: 0, success: 0, error: 0 };
@@ -420,6 +481,8 @@ export class ToolGroupComponent extends Container {
 				lines.push(paddedBackgroundRow(theme, backgroundSlot, line, width));
 			}
 			lines.push(paddedBackgroundRow(theme, backgroundSlot, "", width));
+		} else if (counts.pending === 0) {
+			this.storeSettledCache(width, lines);
 		}
 		return lines;
 	}

package/node_modules/@herbertgao/pi-cc-extensions/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@herbertgao/pi-cc-extensions",
-	"version": "0.8.55",
+	"version": "0.8.56",
 	"license": "MIT",
 	"description": "A Pi productivity suite with Claude Code-style UI, context inspection, and agent/session references",
 	"type": "module",
@@ -69,8 +69,8 @@
 	},
 	"x-upstream": {
 		"package": "pi-cc-extensions",
-		"version": "0.8.60",
+		"version": "0.8.63",
 		"repository": "https://github.com/minuque/pi-cc-extensions",
-		"commit": "268e017acde0b2adb65cefef3c740e37b1aef202"
+		"commit": "6b7447eb9d82afa9ea26dd7433c59ff56663098e"
 	}
 }

package/node_modules/@herbertgao/pi-subagents/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.16.0
+
+### Minor Changes
+
+- [#90](https://github.com/HerbertGao/pi-extensions/pull/90) [`74b7bce`](https://github.com/HerbertGao/pi-extensions/commit/74b7bceac14c36961d25af9cbc6aecc502bdaf3b) Thanks [@HerbertGao](https://github.com/HerbertGao)! - Selectively sync pi-subagents with upstream 0.18.0, including worktree controls, background-by-default top-level agents, usage and cost reporting, programmatic activity tracking, child-session shutdown, and nested print-mode coverage.
+
 ## 0.15.5
 
 ### Patch Changes

package/node_modules/@herbertgao/pi-subagents/README.md

@@ -13,7 +13,7 @@ Spawn specialized agents that run in isolated sessions — each with its own too
 ## Features
 
 - **Claude Code look & feel** — same tool names, calling conventions, and UI patterns (`Agent`, `get_subagent_result`, `steer_subagent`) — feels native
-- **Parallel background agents** — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4) and smart group join (consolidated notifications)
+- **Parallel background agents** — top-level agents run detached by default, with automatic queuing (configurable concurrency limit, default 10) and smart group join; nested delegation still defaults to foreground
 - **Live widget UI** — persistent above-editor widget with animated spinners, live tool activity, token counts, and colored status icons. Configurable via `/agents → Settings → Widget`: `all` (every agent), `background` (default — hides foreground runs, which already render inline as the `Agent` tool result), or `off`
 - **FleetView** — Claude Code-style navigable list of `main` + every running subagent rendered below the editor (earliest-launched first). Press `↓` (or `←`) at an empty prompt to jump in, `↑`/`↓` to move the selection, `Enter` to open the selected agent's live, auto-updating conversation, `Esc` to return. Finished agents linger briefly before dropping out, and a viewer stays open through completion so you can read the final output. Toggle via `/agents → Settings → Fleet view`
 - **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). Steer a running agent inline by pressing `Enter` to open a composer, typing, then `Enter` to send (`Esc` or an empty submit returns) — the message appears as a user message and redirects the agent after its current tool. Stop a still-running agent by pressing `x` (then `x` again to confirm) — both work for background agents too
@@ -26,7 +26,8 @@ Spawn specialized agents that run in isolated sessions — each with its own too
 - **Fuzzy model selection** — specify models by name (`"haiku"`, `"sonnet"`) instead of full IDs, with automatic filtering to only available/configured models
 - **Context inheritance** — optionally fork the parent conversation into a sub-agent so it knows what's been discussed
 - **Persistent agent memory** — three scopes (project, local, user) with automatic read-only fallback for agents without write tools
-- **Git worktree isolation** — run agents in isolated repo copies; changes auto-committed to branches on completion
+- **Git worktree isolation** — run agents in isolated repo copies; `isolation: off` and the project-wide `worktreeIsolation` switch keep work in the current checkout, while preservation commits bypass interactive signing
+- **Usage and cost reporting** — optionally include subagent spend in the parent session's stats (`reportUsage`) and show estimated USD cost across subagent UI surfaces (`showCost`)
 - **Skill preloading** — inject named skills into agent system prompts, discovered from `.pi/skills/`, `.agents/skills/`, and global locations (Pi-standard `<name>/SKILL.md` directory layout supported)
 - **Tool denylist** — block specific tools via `disallowed_tools` frontmatter
 - **Styled completion notifications** — background agent results render as themed, compact notification boxes (icon, stats, result preview) instead of raw XML. Expandable to show full output. Group completions render each agent individually
@@ -60,7 +61,7 @@ Agent({
 })
 ```
 
-Foreground agents block until complete and return results inline. Background agents return an ID immediately and notify you on completion.
+Agents run in the background by default: calls return an ID immediately and notify on completion. Pass `run_in_background: false` to block and return the full result inline. Nested spawns keep the safer foreground default unless explicitly overridden.
 
 ### Scheduling
 
@@ -227,7 +228,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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `isolation`          | —                                               | Set to `worktree` to run in an isolated git worktree                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `isolation`          | —                                               | `worktree` runs in an isolated git worktree; `off` vetoes a caller-requested 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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `max_turns`          | unlimited                                       | Max agentic turns before graceful shutdown. `0` or omit for unlimited                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
@@ -237,7 +238,7 @@ All fields are optional — sensible defaults for everything.
 | `allowed_subagents`  | none                                            | Opt in to scoped nested `Agent`, `get_subagent_result`, and `steer_subagent` tools. Omitted / empty / `none` / `false` = no nesting; `all` (or `"*"` / `true`) = any enabled agent; comma-separated list = only those agent types                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `prompt_mode`        | `replace`                                       | `replace`: body is the full system prompt (no AGENTS.md / CLAUDE.md inheritance). `append`: body appended to parent's prompt (agent acts as a "parent twin" — inherits parent's AGENTS.md / CLAUDE.md)                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `inherit_context`    | `false`                                         | Fork parent conversation into agent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `run_in_background`  | `false`                                         | Run in background by default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `run_in_background`  | `backgroundByDefault`                           | Pin this agent to background (`true`) or foreground (`false`); omit to follow the project default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `isolated`           | `false`                                         | Hermetic specialist mode: forces `extensions: false` + `skills: false` + drops `ext:` selectors. Only built-in tools. Distinct from `isolation: worktree` (filesystem)                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `enabled`            | `true`                                          | Set to `false` to disable an agent (useful for hiding a default agent per-project)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 
@@ -298,6 +299,7 @@ A few rules the examples don't make obvious:
 - Any `ext:` entry flips extension tools to an explicit allowlist — unnamed extensions still load (handlers fire) but expose no tools. So `tools: "*, ext:mcp/search"` exposes only `search` from `mcp`, nothing from any other extension.
 - Extension names match case-insensitively (`[Mcp]` = `[mcp]`); tool names in `ext:foo/bar` stay case-sensitive.
 - Extensions that register tools **lazily** work too. MCP-backed extensions typically can't enumerate their tools until their servers connect, so they register from `session_start` or `before_agent_start` rather than at load. Subagent scoping is re-derived as tools appear, so these surface normally — including under `ext:` selectors, which keep narrowing correctly no matter when a tool shows up.
+- Extensions bound into a child session receive `session_shutdown` before disposal, including record eviction and root-session shutdown; release per-session timers, watchers, sockets, and temp resources there.
 - An installed **package** extension matches by its package short name (`@scope/pi-subagents` → `[pi-subagents]`), in addition to its path-derived name (a package whose entry is `src/index.ts` also answers to `[src]`). Prefer the package name — the path-derived one is incidental.
 - Plain `tools:` typos fail loudly: `tools: reed, grep` fires `tools-error:…` instead of silently producing an under-tooled agent.
 - `exclude_extensions:` wins over `extensions:` and over `ext:` selectors — an excluded extension never loads and a `tools: ext:` entry can't pull it back. Plain names only (no paths, no `*`); a name matching nothing fires an `extension-error:…` warning.
@@ -310,19 +312,19 @@ A few rules the examples don't make obvious:
 
 Launch a sub-agent.
 
-| Parameter           | Type         | Required | Description                                                                                                                                                      |
-| ------------------- | ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `prompt`            | string       | yes      | The task for the agent                                                                                                                                           |
-| `description`       | string       | yes      | Short 3-5 word summary (shown in UI)                                                                                                                             |
-| `subagent_type`     | string       | yes      | Agent type (built-in or custom)                                                                                                                                  |
-| `model`             | string       | no       | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`). Resolved tolerantly (`.`/`-` and a trailing date stamp interchangeable) with provider fallback |
-| `thinking`          | string       | no       | Thinking level: off, minimal, low, medium, high, xhigh, max (availability depends on pi version and model)                                                       |
-| `max_turns`         | number       | no       | Max agentic turns. Omit for unlimited (default)                                                                                                                  |
-| `run_in_background` | boolean      | no       | Run without blocking                                                                                                                                             |
-| `resume`            | string       | no       | Agent ID to resume a previous session                                                                                                                            |
-| `isolated`          | boolean      | no       | No extension/MCP tools                                                                                                                                           |
-| `isolation`         | `"worktree"` | no       | Run in an isolated git worktree                                                                                                                                  |
-| `inherit_context`   | boolean      | no       | Fork parent conversation into agent                                                                                                                              |
+| Parameter           | Type                    | Required | Description                                                                                                                                                      |
+| ------------------- | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prompt`            | string                  | yes      | The task for the agent                                                                                                                                           |
+| `description`       | string                  | yes      | Short 3-5 word summary (shown in UI)                                                                                                                             |
+| `subagent_type`     | string                  | yes      | Agent type (built-in or custom)                                                                                                                                  |
+| `model`             | string                  | no       | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`). Resolved tolerantly (`.`/`-` and a trailing date stamp interchangeable) with provider fallback |
+| `thinking`          | string                  | no       | Thinking level: off, minimal, low, medium, high, xhigh, max (availability depends on pi version and model)                                                       |
+| `max_turns`         | number                  | no       | Max agentic turns. Omit for unlimited (default)                                                                                                                  |
+| `run_in_background` | boolean                 | no       | Defaults to `true`; `false` blocks and returns the result inline                                                                                                 |
+| `resume`            | string                  | no       | Agent ID to resume a previous session                                                                                                                            |
+| `isolated`          | boolean                 | no       | No extension/MCP tools                                                                                                                                           |
+| `isolation`         | `"off"` \| `"worktree"` | no       | `worktree` isolates; `off` keeps the current checkout. Omitted when worktree isolation is disabled                                                               |
+| `inherit_context`   | boolean                 | no       | Fork parent conversation into agent                                                                                                                              |
 
 ### `get_subagent_result`
 
@@ -388,7 +390,7 @@ Instead of hard-aborting at the turn limit, agents get a graceful shutdown:
 
 ## Concurrency
 
-Background agents are subject to a configurable concurrency limit (default: 4). Excess agents are automatically queued and start as running agents complete. The widget shows queued agents as a collapsed count.
+Background agents are subject to a configurable concurrency limit (default: 10). Excess agents are automatically queued and start as running agents complete. The widget shows queued agents as a collapsed count.
 
 Foreground agents bypass the queue — they block the parent anyway.
 
@@ -432,12 +434,18 @@ When on, each subagent spawn's effective model is validated against pi's own `en
 
 ## Persistent Settings
 
-Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns, nested depth, fallback agent, default join mode, scheduling on/off, scope models on/off, strict agent files on/off, disable defaults on/off, output transcript on/off, tool description full/compact/custom, widget all/background/off) persist across pi restarts. Two files, merged on load:
+Runtime tuning values set via `/agents` → Settings (including background default, worktree isolation, usage reporting, and cost display) persist across pi restarts. Two files, merged on load:
 
 - **Global:** `~/.pi/agent/subagents.json` — your machine-wide defaults. Edit by hand; the `/agents` menu never writes here.
 - **Project:** `<cwd>/.pi/subagents.json` — per-project overrides. Written by `/agents` → Settings.
 
-**Precedence:** project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`, nested depth `2`, join mode `smart`, strict agent files disabled, defaults enabled).
+**Precedence:** project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency `10`, background by default enabled, default max turns unlimited, grace turns `5`, nested depth `2`, join mode `smart`, worktree isolation enabled, usage/cost reporting disabled, strict agent files disabled, defaults enabled).
+
+**Background by default** (`backgroundByDefault`, default `true`): unqualified top-level `Agent` calls run detached. Set `false` to restore foreground-by-default behavior. Explicit tool or agent-file `run_in_background` values win. Nested calls always default to foreground so a parent cannot finish and stop an uncollected child.
+
+**Worktree isolation** (`worktreeIsolation`, default `true`): set `false` to reject worktree creation on every spawn path and remove the `isolation` parameter and guidance on the next Pi session. `isolation: off` in agent frontmatter vetoes a caller's `worktree` request.
+
+**Usage and cost** (`reportUsage` and `showCost`, both default `false`): `reportUsage` attaches child usage to parent tool results so Pi session stats include delegated work; `showCost` renders Pi's estimated USD totals in subagent surfaces. They are independent.
 
 **Strict agent files** (`strictAgentFiles`, default `false`): fail extension startup when any discovered agent file is unreadable or malformed. Enable via `/agents → Settings → Strict agent files` or set `true` in `subagents.json`. Strictness applies only to startup; reloads before later Agent calls remain tolerant so a file edited incorrectly mid-session is skipped with a warning instead of aborting the call.
 
@@ -460,7 +468,7 @@ Launch an autonomous agent. Available types:
 Custom agents live in .pi/agents/ or {{agentDir}}/agents/.
 ```
 
-Placeholders: `{{typeList}}` (full per-agent descriptions), `{{compactTypeList}}` (first sentence each), `{{agentDir}}`, `{{scheduleGuideline}}` (expands with its own leading newline + `-` bullet when scheduling is on — place it directly after your last rule line; empty when scheduling is off). Unknown placeholders are left verbatim with a stderr warning; a missing or empty file falls back to `"full"` with a warning. Note the usual trust umbrella: a project-level file shapes the orchestrator's prompt, same as project agents and extensions do.
+Placeholders: `{{typeList}}` (full per-agent descriptions), `{{compactTypeList}}` (first sentence each), `{{agentDir}}`, `{{isolationGuideline}}` (empty when worktrees are disabled), `{{scheduleGuideline}}` (expands with its own leading newline + `-` bullet when scheduling is on — place it directly after your last rule line; empty when scheduling is off). Unknown placeholders are left verbatim with a stderr warning; a missing or empty file falls back to `"full"` with a warning. Note the usual trust umbrella: a project-level file shapes the orchestrator's prompt, same as project agents and extensions do.
 
 **Starting point:** copy [`examples/agent-tool-description.md`](examples/agent-tool-description.md) — it reproduces the default full description exactly (a CI test keeps it in sync), so you can trim from a known-good baseline instead of writing from scratch.
 

package/node_modules/@herbertgao/pi-subagents/examples/agent-tool-description.md

@@ -14,19 +14,19 @@ If the target is already known, use a direct tool — `read` for a known path, `
 ## Usage notes
 
 - Always include a short (3-5 word) description summarizing what the agent will do (shown in UI).
-- When you launch multiple agents for independent work, send them in a single message with multiple tool uses, with run_in_background: true on each, so they run concurrently. If the user specifies that they want agents run "in parallel", you MUST send a single message with multiple tool calls. Foreground calls run sequentially — only one executes at a time.
+- When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.
 - When the agent is done, it returns a single message back to you. The result is not visible to the user — to show the user, send a text message with a concise summary.
 - Trust but verify: an agent's summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting work as done.
-- Use run_in_background for work you don't need immediately. You will be notified when it completes — do NOT poll or sleep waiting for it. Continue with other work or respond to the user instead.
-- Foreground vs background: use foreground (default) when you need the agent's results before you can proceed. Use background when you have genuinely independent work to do in parallel.
+- Agents run in the background by default. You will be notified when one completes — do NOT poll or sleep waiting for it.
+- Pass `run_in_background: false` only when your very next action depends on the result and nothing else could usefully happen while it runs.
+- Never fabricate or predict a pending agent's results; if asked before completion, say it is still running.
 - Use resume with an agent ID to continue a previous agent's work. A new (non-resume) Agent call starts a fresh agent with no memory of prior runs, so the prompt must be self-contained.
 - Use steer_subagent to send mid-run messages to a running background agent.
 - Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, etc.), since it is not aware of the user's intent.
 - If an agent's description says it should be used proactively, try to use it without the user having to ask for it first.
 - Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
 - Use thinking to control extended thinking level.
-- Use inherit_context if the agent needs the parent conversation history.
-- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications). The worktree is automatically cleaned up if the agent makes no changes; otherwise the path and branch are returned in the result.{{scheduleGuideline}}
+- Use inherit_context if the agent needs the parent conversation history.{{isolationGuideline}}{{scheduleGuideline}}
 
 ## Writing the prompt
 

package/node_modules/@herbertgao/pi-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herbertgao/pi-subagents",
-  "version": "0.15.5",
+  "version": "0.16.0",
   "description": "Claude Code-style autonomous subagents for Pi, with HerbertGao-maintained UI extensions.",
   "keywords": [
     "agent",
@@ -46,15 +46,15 @@
   "dependencies": {
     "@sinclair/typebox": "^0.34.49",
     "croner": "^10.0.1",
-    "nanoid": "^5.0.0"
+    "nanoid": "^5.1.16"
   },
   "devDependencies": {
     "@vitest/coverage-istanbul": "^4.1.10"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.80.0",
-    "@earendil-works/pi-coding-agent": ">=0.80.0",
-    "@earendil-works/pi-tui": ">=0.80.0"
+    "@earendil-works/pi-ai": ">=0.81.0",
+    "@earendil-works/pi-coding-agent": ">=0.81.0",
+    "@earendil-works/pi-tui": ">=0.81.0"
   },
   "engines": {
     "node": ">=22.19.0"
@@ -68,8 +68,8 @@
   },
   "x-upstream": {
     "package": "@tintinweb/pi-subagents",
-    "version": "0.16.1",
+    "version": "0.18.0",
     "repository": "https://github.com/tintinweb/pi-subagents",
-    "commit": "bb47763"
+    "commit": "3f9d35cd078d18a141eb5a6d8f4fc5010d756280"
   }
 }

package/node_modules/@herbertgao/pi-subagents/src/agent-file-toggle.ts

@@ -245,7 +245,13 @@ export function serializeAgentFile(cfg: AgentConfig): string {
   if (cfg.disallowedTools?.length)
     fmFields.push(`disallowed_tools: ${cfg.disallowedTools.join(", ")}`)
   if (cfg.inheritContext) fmFields.push("inherit_context: true")
-  if (cfg.runInBackground) fmFields.push("run_in_background: true")
+  // Both cases, not just `true`: with `backgroundByDefault` on, omitting the
+  // field means background, so `false` is the only way to pin an agent file to
+  // foreground and is no longer interchangeable with absence. No caller can
+  // reach it yet — Eject only handles built-in defaults, which omit the field —
+  // so this keeps the writer symmetric with the loader, nothing more.
+  if (cfg.runInBackground !== undefined)
+    fmFields.push(`run_in_background: ${cfg.runInBackground}`)
   if (cfg.outputTranscript === false) fmFields.push("output_transcript: false")
   if (cfg.isolated) fmFields.push("isolated: true")
   if (cfg.memory) fmFields.push(`memory: ${cfg.memory}`)

package/node_modules/@herbertgao/pi-subagents/src/agent-manager.ts

@@ -24,19 +24,25 @@ import type {
   SubagentType,
   ThinkingLevel,
 } from "./types.js"
-import { addUsage } from "./usage.js"
-import { cleanupWorktree, createWorktree, pruneWorktrees } from "./worktree.js"
+import { addUsage, type LifetimeUsage } from "./usage.js"
+import {
+  cleanupWorktree,
+  createWorktree,
+  isWorktreeIsolationEnabled,
+  pruneWorktrees,
+} from "./worktree.js"
 
 export type OnAgentComplete = (record: AgentRecord) => void
 export type OnAgentStart = (record: AgentRecord) => void
 export type OnAgentCompact = (record: AgentRecord, info: CompactionInfo) => void
+export type OnAgentUsage = (record: AgentRecord, usage: LifetimeUsage) => void
 export type CompactionInfo = {
   reason: "manual" | "threshold" | "overflow"
   tokensBefore: number
 }
 
 /** Default max concurrent background agents. */
-const DEFAULT_MAX_CONCURRENT = 4
+const DEFAULT_MAX_CONCURRENT = 10
 
 /**
  * Validate a caller-supplied SpawnOptions.cwd. `undefined`/`null` mean "unset"
@@ -125,11 +131,7 @@ interface SpawnOptions {
   /** Called at the end of each agentic turn with the cumulative count. */
   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
+  onAssistantUsage?: (usage: LifetimeUsage) => void
   /** Called when the session successfully compacts. */
   onCompaction?: (info: CompactionInfo) => void
   /** Nesting depth: top-level subagent = 1. */
@@ -158,11 +160,7 @@ interface ResumeOptions {
   /** Called at the end of each resumed agentic turn with the cumulative count. */
   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
+  onAssistantUsage?: (usage: LifetimeUsage) => void
   /** Called when the session successfully compacts. */
   onCompaction?: (info: CompactionInfo) => void
   /**
@@ -176,12 +174,38 @@ interface ResumeOptions {
   onStarted?: () => void
 }
 
+const CHILD_SHUTDOWN_TIMEOUT_MS = 3_000
+
+async function shutdownChildSession(
+  session: AgentSession | undefined,
+): Promise<void> {
+  try {
+    const runner = session?.extensionRunner
+    if (runner?.hasHandlers?.("session_shutdown")) {
+      await Promise.race([
+        runner.emit({ type: "session_shutdown", reason: "quit" }),
+        new Promise<void>((resolve) =>
+          setTimeout(resolve, CHILD_SHUTDOWN_TIMEOUT_MS).unref(),
+        ),
+      ])
+    }
+  } catch {
+    /* best-effort lifecycle cleanup */
+  }
+  try {
+    session?.dispose?.()
+  } catch {
+    /* ignore */
+  }
+}
+
 export class AgentManager {
   private agents = new Map<string, AgentRecord>()
   private cleanupInterval: ReturnType<typeof setInterval>
   private onComplete?: OnAgentComplete
   private onStart?: OnAgentStart
   private onCompact?: OnAgentCompact
+  private onUsage?: OnAgentUsage
   private maxConcurrent: number
   /** Base repos worktrees were created from — so dispose() can prune them all,
    *  not just the parent repo (caller-supplied cwd can target other repos). */
@@ -197,10 +221,12 @@ export class AgentManager {
     maxConcurrent = DEFAULT_MAX_CONCURRENT,
     onStart?: OnAgentStart,
     onCompact?: OnAgentCompact,
+    onUsage?: OnAgentUsage,
   ) {
     this.onComplete = onComplete
     this.onStart = onStart
     this.onCompact = onCompact
+    this.onUsage = onUsage
     this.maxConcurrent = maxConcurrent
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
     this.cleanupInterval = setInterval(() => this.cleanup(), 60_000)
@@ -302,7 +328,7 @@ export class AgentManager {
     // fail loud if not possible (no silent fallback to main tree). Done
     // BEFORE state mutation so a throw doesn't leave the record half-running.
     let worktreeCwd: string | undefined
-    if (options.isolation === "worktree") {
+    if (options.isolation === "worktree" && isWorktreeIsolationEnabled()) {
       const wt = createWorktree(baseCwd, id)
       if (!wt) {
         throw new Error(
@@ -365,6 +391,7 @@ export class AgentManager {
       onTextDelta: options.onTextDelta,
       onAssistantUsage: (usage) => {
         addUsage(record.lifetimeUsage, usage)
+        this.onUsage?.(record, usage)
         options.onAssistantUsage?.(usage)
       },
       onCompaction: (info) => {
@@ -662,6 +689,7 @@ export class AgentManager {
         onTurnEnd: options?.onTurnEnd,
         onAssistantUsage: (usage) => {
           addUsage(record.lifetimeUsage, usage)
+          this.onUsage?.(record, usage)
           options?.onAssistantUsage?.(usage)
         },
         onCompaction: (info) => {
@@ -766,6 +794,7 @@ export class AgentManager {
       onTurnEnd: options.onTurnEnd,
       onAssistantUsage: (usage) => {
         addUsage(record.lifetimeUsage, usage)
+        this.onUsage?.(record, usage)
         options.onAssistantUsage?.(usage)
       },
       onCompaction: (info) => {
@@ -851,9 +880,10 @@ export class AgentManager {
 
   /** Dispose a record's session and remove it from the map. */
   private removeRecord(id: string, record: AgentRecord): void {
-    record.session?.dispose?.()
+    const session = record.session
     record.session = undefined
     this.agents.delete(id)
+    void shutdownChildSession(session)
   }
 
   private cleanup() {
@@ -926,14 +956,13 @@ export class AgentManager {
     }
   }
 
-  dispose() {
+  async dispose(): Promise<void> {
     clearInterval(this.cleanupInterval)
     // Clear queue
     this.queue = []
-    for (const record of this.agents.values()) {
-      record.session?.dispose()
-    }
+    const sessions = [...this.agents.values()].map((record) => record.session)
     this.agents.clear()
+    await Promise.all(sessions.map((session) => shutdownChildSession(session)))
     // Prune any orphaned git worktrees (crash recovery)
     try {
       pruneWorktrees(process.cwd())

package/node_modules/@herbertgao/pi-subagents/src/agent-runner.ts

@@ -41,6 +41,7 @@ import {
 import { buildAgentPrompt, type PromptExtras } from "./prompts.js"
 import { preloadSkills } from "./skill-loader.js"
 import type { SubagentType, ThinkingLevel } from "./types.js"
+import type { LifetimeUsage } from "./usage.js"
 
 /**
  * Tool names registered by THIS extension. Single source of truth so the
@@ -349,6 +350,15 @@ export function setDefaultMaxTurns(n: number | undefined): void {
   defaultMaxTurns = normalizeMaxTurns(n)
 }
 
+export function resolveEffectiveMaxTurns(
+  type: string,
+  explicit?: number,
+): number | undefined {
+  return normalizeMaxTurns(
+    explicit ?? getAgentConfig(type)?.maxTurns ?? defaultMaxTurns,
+  )
+}
+
 /** Additional turns allowed after the soft limit steer message. */
 let graceTurns = 5
 
@@ -442,11 +452,7 @@ export interface RunOptions {
    * Lets callers maintain a lifetime accumulator that survives compaction
    * (which replaces session.state.messages and resets stats-derived sums).
    */
-  onAssistantUsage?: (usage: {
-    input: number
-    output: number
-    cacheWrite: number
-  }) => void
+  onAssistantUsage?: (usage: LifetimeUsage) => void
   /**
    * Called when the session successfully compacts. `tokensBefore` is upstream's
    * pre-compaction context size estimate. Aborted compactions don't fire.
@@ -1030,9 +1036,7 @@ export async function runAgent(
 
   // Track turns for graceful max_turns enforcement
   let turnCount = 0
-  const maxTurns = normalizeMaxTurns(
-    options.maxTurns ?? agentConfig?.maxTurns ?? defaultMaxTurns,
-  )
+  const maxTurns = resolveEffectiveMaxTurns(type, options.maxTurns)
   let softLimitReached = false
   let aborted = false
 
@@ -1079,6 +1083,8 @@ export async function runAgent(
           input: u.input ?? 0,
           output: u.output ?? 0,
           cacheWrite: u.cacheWrite ?? 0,
+          cacheRead: u.cacheRead ?? 0,
+          cost: u.cost?.total ?? 0,
         })
     }
     if (event.type === "compaction_end" && !event.aborted && event.result) {
@@ -1133,11 +1139,7 @@ export async function resumeAgent(
     onToolActivity?: (activity: ToolActivity) => void
     /** Called at the end of each resumed agentic turn with the 1-based count. */
     onTurnEnd?: (turnCount: number) => void
-    onAssistantUsage?: (usage: {
-      input: number
-      output: number
-      cacheWrite: number
-    }) => void
+    onAssistantUsage?: (usage: LifetimeUsage) => void
     onCompaction?: (info: {
       reason: "manual" | "threshold" | "overflow"
       tokensBefore: number
@@ -1180,6 +1182,8 @@ export async function resumeAgent(
                 input: u.input ?? 0,
                 output: u.output ?? 0,
                 cacheWrite: u.cacheWrite ?? 0,
+                cacheRead: u.cacheRead ?? 0,
+                cost: u.cost?.total ?? 0,
               })
           }
           if (