@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

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

@@ -1377,7 +1377,8 @@ function displayConfigCacheKey(config: ToolDisplayConfig): string {
 		config.diffViewMode,
 		config.diffIndicatorMode,
 		String(config.diffSplitMinWidth),
-		String(config.diffCollapsedLines),
+		String(config.editDiffCollapsedLines),
+		String(config.writeDiffCollapsedLines),
 		config.diffWordWrap ? "1" : "0",
 		String(config.expandedPreviewMaxLines),
 	].join(":");
@@ -2232,10 +2233,22 @@ function resolveDiffDisplayLimit(
 		: DEFAULT_TOOL_DISPLAY_CONFIG.expandedPreviewMaxLines;
 	const collapsedLimit = Number.isFinite(maxCollapsedLines)
 		? maxCollapsedLines
-		: DEFAULT_TOOL_DISPLAY_CONFIG.diffCollapsedLines;
+		: DEFAULT_TOOL_DISPLAY_CONFIG.editDiffCollapsedLines;
 	return expanded ? Math.max(0, expandedLimit) : Math.max(1, collapsedLimit);
 }
 
+/** Write collapsed body limit. Missing/NaN falls back to edit's limit. */
+function resolveWriteCollapsedLimit(config: ToolDisplayConfig): number {
+	const value = config.writeDiffCollapsedLines;
+	if (Number.isFinite(value)) {
+		return Math.max(0, value);
+	}
+	const fallback = Number.isFinite(config.editDiffCollapsedLines)
+		? config.editDiffCollapsedLines
+		: DEFAULT_TOOL_DISPLAY_CONFIG.writeDiffCollapsedLines;
+	return Math.max(0, fallback);
+}
+
 /**
  * How many source rows/entries to fully highlight+render before applyLineLimit.
  * Extra headroom covers word-wrap expansion so the display limit can still fill.
@@ -2602,7 +2615,7 @@ export function renderEditDiffResult(
 			const headerRows = renderHeaderRows(parsed.stats, mode, safeWidth, theme);
 			const displayLimit = resolveDiffDisplayLimit(
 				options.expanded,
-				live.diffCollapsedLines,
+				live.editDiffCollapsedLines,
 				live.expandedPreviewMaxLines,
 			);
 			const processBudget = resolveDiffProcessBudget(displayLimit, wordWrap);
@@ -2636,7 +2649,7 @@ export function renderEditDiffResult(
 				bodyRows,
 				safeWidth,
 				options.expanded,
-				live.diffCollapsedLines,
+				live.editDiffCollapsedLines,
 				live.expandedPreviewMaxLines,
 				parsed.stats.hunks,
 				theme,
@@ -2901,6 +2914,41 @@ function renderWriteOverwriteGuardRows(
 	return renderSingleDiffRow(buildWriteOverwriteGuardText(guard, width), "warning", width, theme);
 }
 
+/** Folded write with a zero body limit: `↳ created • click to show more`. */
+function renderWriteCollapsedHintLine(
+	wasOverwrite: boolean,
+	width: number,
+	theme: DiffTheme,
+	hovered: boolean,
+	headerLabel?: string,
+): string[] {
+	const safeWidth = normalizeDiffRenderWidth(width);
+	if (safeWidth === 0) {
+		return [""];
+	}
+	const actionLabel = headerLabel?.trim() || (wasOverwrite ? "overwritten" : "created");
+	const clickLabel = showMoreHintText();
+	const candidates = [`↳ ${actionLabel} • ${clickLabel}`, `↳ ${actionLabel}`, actionLabel, "…"];
+	let text = candidates[candidates.length - 1] ?? "…";
+	for (const candidate of candidates) {
+		if (visibleWidth(candidate) <= safeWidth) {
+			text = candidate;
+			break;
+		}
+	}
+	if (visibleWidth(text) > safeWidth) {
+		text = truncateToWidth(text, safeWidth, "");
+	}
+	const clickIndex = text.lastIndexOf(clickLabel);
+	const styled =
+		hovered && clickIndex >= 0
+			? theme.fg("muted", text.slice(0, clickIndex)) +
+				theme.fg("text", clickLabel) +
+				theme.fg("muted", text.slice(clickIndex + clickLabel.length))
+			: theme.fg("muted", text);
+	return [clampDiffLineToWidth(styled, safeWidth)];
+}
+
 export function renderWriteDiffResult(
 	content: string | undefined,
 	options: DiffRenderOptions,
@@ -2977,6 +3025,27 @@ export function renderWriteDiffResult(
 				return cached;
 			}
 
+			const writeCollapsedLimit = resolveWriteCollapsedLimit(live);
+			if (!options.expanded && writeCollapsedLimit === 0) {
+				return cache.set(
+					safeWidth,
+					options.expanded,
+					mode,
+					configKey,
+					hovered,
+					clampDiffLinesToWidth(
+						renderWriteCollapsedHintLine(
+							options.fileExistedBeforeWrite === true,
+							safeWidth,
+							theme,
+							hovered,
+							options.headerLabel,
+						),
+						safeWidth,
+					),
+				);
+			}
+
 			const header = renderWriteHeader(
 				options.fileExistedBeforeWrite === true,
 				safeWidth,
@@ -3027,7 +3096,7 @@ export function renderWriteDiffResult(
 			const data = getDetailedData();
 			const displayLimit = resolveDiffDisplayLimit(
 				options.expanded,
-				live.diffCollapsedLines,
+				writeCollapsedLimit,
 				live.expandedPreviewMaxLines,
 			);
 			const processBudget = resolveDiffProcessBudget(displayLimit, wordWrap);
@@ -3065,7 +3134,7 @@ export function renderWriteDiffResult(
 				bodyRows,
 				safeWidth,
 				options.expanded,
-				live.diffCollapsedLines,
+				writeCollapsedLimit,
 				live.expandedPreviewMaxLines,
 				data.hunkCount,
 				theme,

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

@@ -5,7 +5,9 @@ export interface ToolDisplayConfig {
 	diffViewMode: DiffViewMode;
 	diffIndicatorMode: DiffIndicatorMode;
 	diffSplitMinWidth: number;
-	diffCollapsedLines: number;
+	editDiffCollapsedLines: number;
+	/** Write-only collapsed body lines. 0 = `↳ created • click to show more`. */
+	writeDiffCollapsedLines: number;
 	diffWordWrap: boolean;
 	expandedPreviewMaxLines: number;
 }
@@ -14,8 +16,10 @@ export const DEFAULT_TOOL_DISPLAY_CONFIG: ToolDisplayConfig = {
 	diffViewMode: "auto",
 	diffIndicatorMode: "bars",
 	diffSplitMinWidth: 120,
-	/** Collapsed tool/diff body: ~half a typical terminal after chrome. */
-	diffCollapsedLines: 24,
+	/** Collapsed edit/diff body: ~half a typical terminal after chrome. */
+	editDiffCollapsedLines: 24,
+	/** Write create/overwrite collapsed body; 0 shows only the expand hint. */
+	writeDiffCollapsedLines: 0,
 	diffWordWrap: true,
 	/**
 	 * Expanded tool/diff body cap. 40 ≈ one screen of content after title,

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.57",
 	"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.64",
 		"repository": "https://github.com/minuque/pi-cc-extensions",
-		"commit": "268e017acde0b2adb65cefef3c740e37b1aef202"
+		"commit": "4709081a28255b8bdfe610620a2a9ee8951013d6"
 	}
 }

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}`)