@narumitw/pi-subagents 0.13.0 → 0.14.0

package/README.md

@@ -2,21 +2,26 @@
 
 [![npm](https://img.shields.io/npm/v/@narumitw/pi-subagents)](https://www.npmjs.com/package/@narumitw/pi-subagents) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
-`@narumitw/pi-subagents` is a native [Pi coding agent](https://pi.dev) extension that adds a `subagent` tool for delegating work to specialized agents running in isolated Pi subprocesses.
+`@narumitw/pi-subagents` is a native [Pi coding agent](https://pi.dev) extension for delegating work to specialized agents. The batch `subagent` tool keeps isolated Pi subprocesses, while addressable lifecycle tools can run reusable agents either as subprocess-backed logical sessions or as public-SDK in-process child sessions.
 
-Use it to split research, planning, implementation, and review work across focused workers while keeping each subprocess context, tools, and prompt boundary separate from the main conversation.
+Use it to split independent research, planning, implementation, and review work across focused workers. Background delegation is intended for sidecar work the main agent can overlap with useful local work—not for handing off one critical-path task and waiting.
 
 ## ✨ Features
 
 - Registers a `subagent` tool for single-agent, parallel, fan-in, and chained delegation.
-- Runs workers as isolated `pi --mode json -p --no-session` subprocesses.
+- Keeps batch workers isolated in `pi --mode json -p --no-session` subprocesses.
+- Registers detached stateful lifecycle tools by default; spawn returns immediately and completion is delivered asynchronously without starting a new root turn.
+- Supports an opt-in public-SDK `in-process` stateful transport with one reusable child `AgentSession` per `agentId`.
 - Supports built-in `scout`, `planner`, `reviewer`, and `worker` agents.
 - Loads custom user agents from `~/.pi/agent/agents/*.md`.
 - Optionally loads project agents from `.pi/agents/*.md` with confirmation.
 - Provides `/subagents:config` to persist per-agent tool allow-lists.
 - Supports per-task `cwd`, hard subprocess `timeoutMs`, `thinkingLevel`, abort propagation, and streaming progress.
+- Bounds JSON lines, captured messages, stderr, final output, chain substitution, and fan-in context.
+- Enforces a recursion-depth guard and deterministic process-group termination.
+- Provides addressable stateful agents with follow-up, wait, list, interrupt, close, context selection, and persistence.
 - Publishes transient runtime status through Pi's generic extension status API while subagents are running.
-- Returns complete worker output in tool details and a concise result for the main agent.
+- Returns complete bounded worker output in tool details and a concise result for the main agent.
 
 ## 📦 Install
 
@@ -38,9 +43,18 @@ pi -e ./extensions/pi-subagents
 
 ## 🛠️ Pi tool
 
-`pi-subagents` registers one tool:
+`pi-subagents` registers a primary batch tool plus the stateful lifecycle tools documented below:
 
-- `subagent` — delegate work to one or more specialized agents.
+- `subagent` — delegate blocking single, parallel, fan-in, or chained batch work.
+- `subagent_spawn` and related lifecycle tools — start reusable detached work, return immediately, and receive bounded completion messages automatically.
+
+Choose the API by lifecycle:
+
+| Need | Use |
+| --- | --- |
+| One or more independent, one-shot results needed before the root responds | One blocking `subagent` call (`tasks` for parallel work) |
+| Reusable history, follow-ups, mailboxes, or work that overlaps useful root work | `subagent_spawn` and lifecycle tools |
+| One simple or critical-path action the root can perform directly | No subagent |
 
 Execution modes:
 
@@ -64,8 +78,12 @@ Count-selection guidance:
 
 - Use **no subagent** for simple answers, quick targeted edits, latency-sensitive one-step work, or
   tasks that need frequent user back-and-forth.
-- Use **one subagent** for isolated research, high-volume command output, planning, or independent
-  review/verification after implementation.
+- A single `subagent` call is blocking. Use one only when context isolation, high-volume output
+  isolation, or independent review is worth waiting for; otherwise the main agent should do the work.
+- Do not delegate ordinary critical-path work merely to wait for it. Use detached `subagent_spawn`
+  only when parallel work, bounded context/output, independent review, a distinct model/tool profile,
+  or workspace isolation provides concrete value. Continue useful non-overlapping work when available;
+  otherwise call `subagent_wait` and synthesize the result before finishing.
 - Prefer **2–4 parallel read-only subagents** when a broad task naturally splits into independent
   branches that can each return a concise summary.
 - Exceed 4 tasks only when the branches are clearly distinct and worth the extra cost, while staying
@@ -128,6 +146,8 @@ Run one read-only reconnaissance agent:
 }
 ```
 
+For genuinely random values, specify the range, duplicate policy, and a system randomness source instead of relying on model sampling, for example: `Use Python secrets to return 10 integers from 0 through 999; duplicates are allowed.`
+
 Run multiple agents in parallel with a shared thinking level and one per-task override:
 
 ```json
@@ -178,6 +198,92 @@ Run a chain where each step receives the previous output:
 }
 ```
 
+## 🔁 Stateful agents
+
+Stateful lifecycle tools are available by default. `subagent_spawn` is detached: it schedules work, returns immediately with an opaque `agentId`, and later injects one bounded `pi-subagent-completion` message per settled turn. The message uses `deliverAs: "steer"` with `triggerTurn: false`, so an active root turn can consume it naturally.
+
+Detached work has a root-coordination invariant: the main agent should continue useful non-overlapping work when available, or call `subagent_wait` when coordination is the only useful next action. If it yields while current delegated work is still live or awaiting synthesis, the extension schedules one idle-gated recovery continuation for that orchestration revision. A completion, close, interruption, new root turn, session replacement, or shutdown revises or clears that ephemeral state. Recovery is bounded and does not internally wait forever or persist across sessions.
+
+A single detached agent is justified only by a concrete isolation or specialization benefit such as independent review, bounded context/output, a distinct model/tool profile, or workspace isolation. Simple work that the main agent can perform directly should not be delegated.
+
+When `subagent_wait` starts while a turn is running, that wait consumes the turn's completion: the terminal output is returned by the tool and is not also injected as a duplicate asynchronous completion. Multiple active waiters may all receive the terminal result. A timed-out or aborted wait does not consume it, so later settlement still delivers the normal asynchronous completion. If a turn has already settled and queued its completion before a wait starts, the queued message cannot be retracted safely.
+
+The default `subprocess` transport preserves compatibility: each turn starts a fresh isolated `pi --mode json -p --no-session` child and receives sanitized, bounded history. Set `transport` to `in-process` to retain one public Pi SDK `AgentSession` per stateful `agentId`, avoiding repeated process startup while preserving native child history in memory.
+
+Configure the runtime in `~/.pi/agent/pi-subagents-config.json`, then reload Pi:
+
+```json
+{
+  "stateful": {
+    "transport": "in-process",
+    "maxAgents": 16,
+    "maxActiveTurns": 4,
+    "maxDepth": 3,
+    "maxChildrenPerAgent": 8,
+    "maxMailboxMessages": 100,
+    "maxMailboxMessageBytes": 16384,
+    "idleTtlMs": 3600000,
+    "retentionDays": 30,
+    "maxStoredAgents": 50
+  }
+}
+```
+
+Set `"enabled": false` to remove all stateful lifecycle tools. Otherwise, the extension registers:
+
+| Tool | Purpose |
+| --- | --- |
+| `subagent_spawn` | Start detached work, return an opaque `agentId` immediately, and deliver completion asynchronously. |
+| `subagent_send` | Send follow-up work to a reusable agent; shared-workspace write conflicts are guarded unless explicitly overridden. |
+| `subagent_message` | Queue a bounded mailbox message without starting a turn; sender IDs must be `root` or an agent in the same tree. |
+| `subagent_messages` | Read and optionally acknowledge unread mailbox messages. |
+| `subagent_wait` | Wait when coordination is the useful next action; timeout does not terminate the agent, and parent abort/user steering cancels only the wait. Already-terminal agents return immediately. |
+| `subagent_list` | List retained agents and lifecycle states. |
+| `subagent_interrupt` | Abort the current turn while retaining its identity and history. |
+| `subagent_close` | Abort if necessary, close the agent, and remove it from retained persistence. |
+
+Use `/subagents:agents list` to inspect the indented agent tree, lifecycle state, unread count, and available actions. Use `/subagents:agents clear` to close and delete all retained agents for the session. Active turns are FIFO-limited by `maxActiveTurns`; excess retained work remains in `starting` state until a slot is available. `maxAgents` separately bounds running, queued, and idle records. `parentId` creates a bounded child relationship; subtree interrupt and close operate child-first.
+
+`subagent_spawn.context` accepts:
+
+- `"none"` (default) — no parent conversation.
+- `"all"` — bounded user/assistant text from the active branch.
+- `"summary"` — a bounded earlier-context checkpoint plus recent messages verbatim.
+- A positive number — the most recent N user turns and related assistant text.
+
+Use `contextEntryIds` to select exact session entries. Supplying IDs without `context` implies `context: "all"`; an explicit `context: "none"` still disables parent context. Stable source IDs are retained so repeated follow-ups do not need to duplicate parent context.
+
+Reasoning, tool results, custom transport messages, and non-text parts are excluded. Text inside `<private>...</private>` and lines containing `[subagent-private]` are omitted before context, mailbox content, or history is persisted.
+
+Stateful execution uses a transport boundary:
+
+- `subprocess` is the default compatibility and rollback path.
+- `in-process` uses only public Pi SDK APIs: `createAgentSession()`, `SessionManager.inMemory()`, `DefaultResourceLoader`, and normal session lifecycle methods. It isolates conversation/tool selection, not memory or crashes; child failures share the parent Node.js process.
+- Child resource loading sets `noExtensions: true`, preventing recursive `pi-subagents` loading and duplicate extension side effects while retaining normal context/skill resources and the selected agent prompt.
+- Agent model, thinking level, and built-in tool allow-list overrides are applied when the child is created. Parent model/thinking changes are snapshotted for subsequently created children; an existing child keeps its own session configuration.
+- Extension/custom tool names are rejected in-process with an actionable recommendation to use `subprocess`; permissions are never silently widened.
+- Timeout, parent abort, close, expiry, and session shutdown abort/dispose owned child sessions. A child that does not settle after abort grace is discarded rather than reused.
+- In-process startup failures do not silently retry through subprocesses, preventing duplicate side effects.
+
+No private Pi imports, runtime casts, or `ExtensionAPI` monkey-patching are used. Approval policy, sandbox profile, provider-header hooks, extension state, global scheduling, and parent/child transcript switching are not inherited or provided by the in-process transport.
+
+Write-capable agents share the workspace by default. Concurrent write-capable starts in the same cwd are rejected unless `allowConcurrentWrites` is explicitly set. Classification is intentionally conservative: an agent with `bash`, `write`, or `edit` is write-capable even when its task prompt says “read only,” because prompt wording is not a filesystem sandbox. For independent one-shot work, use batch parallel mode. Otherwise wait for or close the active agent, explicitly accept safe overlap with `allowConcurrentWrites`, or use an isolated worktree when repository isolation is actually needed.
+
+Set `workspaceMode: "worktree"` to opt into a disposable detached Git worktree; this requires a clean repository and the worktree is removed on close or session shutdown. Isolated worktree agents are intentionally not restored after shutdown.
+
+## 📜 Compatibility and failure contract
+
+Existing `subagent` requests remain unchanged:
+
+| Mode | Ordering | Failure behavior |
+| --- | --- | --- |
+| Single | One result. | A failed/aborted/timed-out worker is marked as a tool error while preserving bounded details. |
+| Chain | Input order. | Stops at the first failed step; completed steps remain in details. |
+| Parallel | Input order, with at most four active children. | Collects all task results; partial worker failure is reported in summaries but does not discard successful results. |
+| Parallel + aggregator | Source input order, then aggregator. | The aggregator runs with both successful outputs and failure descriptions; aggregator failure marks the tool result as an error. |
+
+Timeout precedence remains: task/step/aggregator → call → agent setting → `PI_SUBAGENT_TIMEOUT_MS` → 600000 ms. Thinking precedence remains: task/step/aggregator → call → agent setting → child default. Project-agent resolution and confirmation behavior is unchanged.
+
 ## 🤖 Built-in agents
 
 Built-in agents are available without setup and can be overridden by user or project agents with the same name.
@@ -241,7 +347,15 @@ Set `thinkingLevel` to pass Pi's `--thinking <level>` to a subprocess. Supported
 
 Thinking-level precedence is: task/chain step/aggregator `thinkingLevel` → top-level `thinkingLevel` → agent default from config or frontmatter → Pi subprocess default. Omit `thinkingLevel` to preserve existing behavior. Pi still owns model capability clamping, so unsupported thinking levels are handled by the spawned Pi process.
 
-On timeout, the extension sends `SIGTERM`, escalates to `SIGKILL` after a short grace period, and returns any partial messages or stderr collected so far.
+On timeout, the extension sends process-group `SIGTERM`, escalates to `SIGKILL` after a five-second grace period if the process has not actually closed, and returns partial bounded messages or stderr collected so far. Parent abort uses the same cleanup path and preserves a structured result.
+
+The child event protocol limits each JSON line to 256 KiB. Captured output uses these defaults:
+
+- final output and fan-in/chain context: 50 KiB;
+- stderr: 16 KiB;
+- captured messages: 200.
+
+Truncated text includes a `truncated by pi-subagents` marker and details expose `truncated: true`. `PI_SUBAGENT_MAX_DEPTH` controls nested delegation depth and defaults to 1; child processes receive `PI_SUBAGENT_DEPTH` automatically.
 
 ## 📡 Runtime status
 
@@ -249,21 +363,32 @@ While the `subagent` tool is running, `pi-subagents` publishes compact activity
 
 ## 🔒 Safety notes
 
-Subagents are separate Pi processes and may use the tools allowed by their agent definition. Treat project-local agent prompts like executable project configuration: only enable them in trusted repositories.
+Subagents have separate processes and context windows, but they are **not security sandboxes**. They run as the same OS user, share the host filesystem and network access, and may conflict if they edit the same files. Tool allow-lists reduce available Pi tools but do not reduce operating-system permissions.
+
+The runner explicitly reports policy continuity in result details:
+
+- inherited: process environment;
+- overridden when selected: cwd, model, thinking level, and tool list;
+- unsupported guarantees: parent approval policy, sandbox profile, and provider headers.
+
+Treat project-local agent prompts like executable project configuration: only enable them in trusted repositories. Stateful project agents require Pi's project trust; interactive use also keeps confirmation enabled by default.
+
+Stateful records are stored as versioned mode-0600 JSON under `~/.pi/agent/pi-subagents-state/` (or the configured Pi agent directory). Records contain sanitized logical history, never process IDs or credentials. Corrupt or unsupported state is quarantined, restored agents are always inert `idle` records, and no prior side effect is automatically resumed. Retention and count limits are configurable. Downgrading is safe: older extension versions ignore this separate state directory; use `/subagents:agents clear` before downgrade if the histories should be removed.
 
 ## 🗂️ Package layout
 
 ```txt
 extensions/pi-subagents/
 ├── src/
-│   └── subagents.ts
+│   ├── subagents.ts  # Pi entrypoint and tool schema
+│   └── *.ts          # Package-local discovery, execution, rendering, and config modules
 ├── README.md
 ├── LICENSE
 ├── tsconfig.json
 └── package.json
 ```
 
-The package exposes its Pi extension through `package.json`:
+Only `subagents.ts` is a Pi entrypoint; the other source modules are internal. The package exposes its Pi extension through `package.json`:
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "0.13.0",
+	"version": "0.14.0",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",
@@ -38,8 +38,8 @@
 		"@earendil-works/pi-tui": "*"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.5.2",
-		"@earendil-works/pi-agent-core": "0.80.3",
+		"@biomejs/biome": "2.5.3",
+		"@earendil-works/pi-agent-core": "0.80.6",
 		"@earendil-works/pi-ai": "0.80.3",
 		"@earendil-works/pi-coding-agent": "0.80.3",
 		"@earendil-works/pi-tui": "0.80.3",

package/src/agents.ts

@@ -38,8 +38,25 @@ export interface SubagentAgentConfig {
 	timeoutMs?: number | null;
 }
 
+export type SubagentTransportKind = "subprocess" | "in-process";
+
+export interface SubagentRuntimeSettings {
+	enabled?: boolean;
+	transport?: SubagentTransportKind;
+	maxAgents?: number;
+	maxActiveTurns?: number;
+	maxDepth?: number;
+	maxChildrenPerAgent?: number;
+	maxMailboxMessages?: number;
+	maxMailboxMessageBytes?: number;
+	idleTtlMs?: number;
+	retentionDays?: number;
+	maxStoredAgents?: number;
+}
+
 export interface SubagentSettings {
 	agents?: Record<string, SubagentAgentConfig>;
+	stateful?: SubagentRuntimeSettings;
 }
 
 const BUILT_IN_AGENTS: AgentConfig[] = [

package/src/config-ui.ts

@@ -0,0 +1,271 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import {
+	Container,
+	Key,
+	matchesKey,
+	SelectList,
+	type SelectItem,
+	Spacer,
+	Text,
+	truncateToWidth,
+} from "@earendil-works/pi-tui";
+import { discoverAgents, type SubagentSettings } from "./agents.js";
+import {
+	hasAnyAgentOverride,
+	hasOwn,
+	readSubagentSettings,
+	sameToolSet,
+	saveSubagentConfig,
+	uniqueToolNames,
+} from "./settings.js";
+
+class ToolToggleList {
+	private items: { name: string; selected: boolean }[];
+	private cursor = 0;
+	private cachedWidth?: number;
+	private cachedLines?: string[];
+	onDone?: (selected: string[]) => void;
+	onCancel?: () => void;
+
+	constructor(tools: string[], selected: Set<string>) {
+		this.items = tools.map((name) => ({ name, selected: selected.has(name) }));
+	}
+
+	private getSelectedNames(): string[] {
+		return this.items.filter((i) => i.selected).map((i) => i.name);
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, Key.escape)) {
+			this.onCancel?.();
+			return;
+		}
+		if (data === "s" || data === "S") {
+			this.onDone?.(this.getSelectedNames());
+			return;
+		}
+		if (this.items.length === 0) return;
+
+		if (matchesKey(data, Key.up) && this.cursor > 0) {
+			this.cursor--;
+			this.invalidate();
+		} else if (matchesKey(data, Key.down) && this.cursor < this.items.length - 1) {
+			this.cursor++;
+			this.invalidate();
+		} else if (matchesKey(data, Key.enter) || matchesKey(data, Key.space)) {
+			this.items[this.cursor].selected = !this.items[this.cursor].selected;
+			this.invalidate();
+		}
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
+		this.cachedWidth = width;
+		this.cachedLines = this.items.map((item, i) => {
+			const pointer = i === this.cursor ? ">" : " ";
+			const check = item.selected ? "✓" : "○";
+			return truncateToWidth(`${pointer} ${check} ${item.name}`, width);
+		});
+		return this.cachedLines;
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+}
+
+export function registerSubagentConfigCommand(pi: ExtensionAPI) {
+	pi.registerCommand("subagents:config", {
+		description: "Configure which tools each subagent can use",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) {
+				return;
+			}
+
+			// Get current settings
+			const currentSettings = readSubagentSettings() ?? {};
+			const currentAgents = currentSettings.agents ?? {};
+
+			// Discover agents to show which ones are available
+			const discovery = discoverAgents(ctx.cwd, "user", currentSettings);
+			const agents = discovery.agents;
+
+			if (agents.length === 0) {
+				ctx.ui.notify("No agents found", "warning");
+				return;
+			}
+
+			// Loop: agent selection → tool toggle (Esc in tools returns here)
+			while (true) {
+				// Step 1: pick an agent to configure
+				const agentItems: SelectItem[] = agents.map((a) => {
+					const cfg = currentAgents[a.name];
+					const hasToolsOverride = cfg ? hasOwn(cfg, "tools") : false;
+					const toolSummary = hasToolsOverride
+						? cfg?.tools && cfg.tools.length > 0
+							? cfg.tools.join(", ")
+							: "none"
+						: "defaults";
+					return {
+						value: a.name,
+						label: a.name,
+						description: `${a.source} · tools: ${toolSummary}`,
+					};
+				});
+
+				const agentName = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+					const container = new Container();
+					container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+					container.addChild(
+						new Text(theme.fg("accent", theme.bold("Subagent Tool Configuration")), 1, 0),
+					);
+					container.addChild(new Spacer(1));
+					container.addChild(
+						new Text(theme.fg("muted", "Select an agent to configure its allowed tools:"), 1, 0),
+					);
+					container.addChild(new Spacer(1));
+					const selectList = new SelectList(agentItems, Math.min(agentItems.length + 2, 15), {
+						selectedPrefix: (t: string) => theme.fg("accent", t),
+						selectedText: (t: string) => theme.fg("accent", t),
+						description: (t: string) => theme.fg("muted", t),
+						scrollInfo: (t: string) => theme.fg("dim", t),
+						noMatch: (t: string) => theme.fg("warning", t),
+					});
+					selectList.onSelect = (item) => done(item.value);
+					selectList.onCancel = () => done(null);
+					container.addChild(selectList);
+					container.addChild(
+						new Text(theme.fg("dim", "↑↓ navigate · enter select · esc cancel"), 1, 0),
+					);
+					container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+					return {
+						render: (w: number) => container.render(w),
+						invalidate: () => container.invalidate(),
+						handleInput: (data: string) => {
+							selectList.handleInput(data);
+							tui.requestRender();
+						},
+					};
+				});
+
+				if (!agentName) return;
+
+				const agent = agents.find((a) => a.name === agentName);
+				if (!agent) return;
+
+				// Step 2: toggle tools for the selected agent
+				// Discover without overrides to get original built-in/frontmatter defaults.
+				// The main discovery above applies saved overrides, so agent.tools is already
+				// overridden — using it for the reset-to-default comparison would match the
+				// override against itself and silently delete it on a no-op save.
+				const defaultDiscovery = discoverAgents(ctx.cwd, "user");
+				const defaultTools = defaultDiscovery.agents.find((a) => a.name === agentName)?.tools;
+				const currentAgentSettings = currentAgents[agentName];
+				const configuredTools =
+					currentAgentSettings && hasOwn(currentAgentSettings, "tools")
+						? (currentAgentSettings.tools ?? [])
+						: undefined;
+
+				// Get all available tools from pi's registry
+				const allTools = uniqueToolNames(pi.getAllTools().map((t) => t.name)).sort((a, b) =>
+					a.localeCompare(b),
+				);
+				const currentTools = uniqueToolNames(configuredTools ?? defaultTools ?? allTools);
+				// Sort: currently selected tools first, then rest alphabetically. Preserve
+				// unavailable configured tools so saving does not silently drop them.
+				const currentSet = new Set(currentTools);
+				const selectedFirst = [...currentTools, ...allTools.filter((t) => !currentSet.has(t))];
+
+				const selectedTools = await ctx.ui.custom<string[] | null>((tui, theme, _kb, done) => {
+					const toggleList = new ToolToggleList(selectedFirst, currentSet);
+
+					const container = new Container();
+					container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+					container.addChild(
+						new Text(
+							theme.fg("accent", theme.bold(`${agentName} tools`)) +
+								theme.fg("muted", ` (${agent.source})`),
+							1,
+							0,
+						),
+					);
+					container.addChild(new Spacer(1));
+					container.addChild(
+						new Text(theme.fg("muted", "Toggle tools with Enter/Space. S to save, Esc to cancel."), 1, 0),
+					);
+					container.addChild(new Spacer(1));
+
+					const listContainer = new Container();
+					listContainer.addChild({
+						render: (w: number) => toggleList.render(w),
+						invalidate: () => toggleList.invalidate(),
+					});
+					container.addChild(listContainer);
+
+					container.addChild(new Spacer(1));
+					container.addChild(
+						new Text(theme.fg("dim", "↑↓ navigate · enter/space toggle · S save · esc cancel"), 1, 0),
+					);
+					container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+					toggleList.onDone = (tools) => done(tools);
+					toggleList.onCancel = () => done(null);
+
+					return {
+						render: (w: number) => container.render(w),
+						invalidate: () => container.invalidate(),
+						handleInput: (data: string) => {
+							toggleList.handleInput(data);
+							tui.requestRender();
+						},
+					};
+				});
+
+				// null means user cancelled — loop back to agent selection
+				if (selectedTools === null) continue;
+
+				// Save to global settings
+				const updatedAgents = { ...currentAgents };
+				let restoredDefaults = false;
+
+				const isSameAsDefault =
+					defaultTools === undefined
+						? sameToolSet(selectedTools, allTools)
+						: sameToolSet(selectedTools, defaultTools);
+
+				if (isSameAsDefault) {
+					// Tools match defaults — remove only the tools override.
+					// Keep other settings (model, timeoutMs) if present.
+					const existing = updatedAgents[agentName];
+					if (existing) {
+						const nextConfig = { ...existing };
+						delete nextConfig.tools;
+						if (hasAnyAgentOverride(nextConfig)) updatedAgents[agentName] = nextConfig;
+						else delete updatedAgents[agentName];
+					}
+					restoredDefaults = true;
+				} else {
+					updatedAgents[agentName] = {
+						...updatedAgents[agentName],
+						tools: selectedTools,
+					};
+				}
+
+				const newSettings: SubagentSettings = {
+					...currentSettings,
+					agents: Object.keys(updatedAgents).length > 0 ? updatedAgents : undefined,
+				};
+
+				saveSubagentConfig(newSettings);
+				const message = restoredDefaults
+					? `${agentName}: defaults restored`
+					: `${agentName}: ${selectedTools.length} tool${selectedTools.length !== 1 ? "s" : ""} configured`;
+				ctx.ui.notify(message, "info");
+				// Saved — exit the loop
+				break;
+			}
+		},
+	});
+}

package/src/context.ts

@@ -0,0 +1,129 @@
+import { createHash } from "node:crypto";
+import {
+	DEFAULT_MAX_CONTEXT_BYTES,
+	truncateUtf8,
+	truncateUtf8Tail,
+} from "./limits.js";
+
+export type ContextMode = "none" | "all" | "summary" | number;
+
+export interface ContextSnapshot {
+	text: string;
+	turns: number;
+	truncated: boolean;
+	sourceIds: string[];
+}
+
+function textParts(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter((part): part is { type: "text"; text: string } =>
+			Boolean(
+				part &&
+					typeof part === "object" &&
+					(part as { type?: unknown }).type === "text" &&
+					typeof (part as { text?: unknown }).text === "string",
+			),
+		)
+		.map((part) => part.text)
+		.join("\n");
+}
+
+export function redactPrivateText(text: string): string {
+	const tagPattern = /<\/?private>/gi;
+	let redacted = "";
+	let cursor = 0;
+	let depth = 0;
+	for (const match of text.matchAll(tagPattern)) {
+		const tag = match[0].toLowerCase();
+		const index = match.index ?? cursor;
+		if (depth === 0) redacted += text.slice(cursor, index);
+		if (tag === "<private>") {
+			if (depth === 0) redacted += "[private content omitted]";
+			depth++;
+		} else if (depth > 0) {
+			depth--;
+		} else {
+			redacted += match[0];
+		}
+		cursor = index + match[0].length;
+	}
+	if (depth === 0) redacted += text.slice(cursor);
+	return redacted
+		.split("\n")
+		.filter((line) => !line.includes("[subagent-private]"))
+		.join("\n");
+}
+
+export function buildContextSnapshot(
+	entries: readonly unknown[],
+	mode: ContextMode,
+	maxBytes = DEFAULT_MAX_CONTEXT_BYTES,
+	selectedSourceIds?: readonly string[],
+): ContextSnapshot {
+	if (mode === "none") return { text: "", turns: 0, truncated: false, sourceIds: [] };
+	const messages: Array<{ role: "user" | "assistant"; text: string; sourceId: string }> = [];
+	for (const entry of entries) {
+		if (!entry || typeof entry !== "object") continue;
+		const candidate = entry as {
+			id?: string;
+			type?: string;
+			role?: string;
+			content?: unknown;
+			message?: { role?: string; content?: unknown };
+		};
+		const message: { role?: string; content?: unknown } | undefined =
+			candidate.type === "message" ? candidate.message : candidate;
+		if (message?.role !== "user" && message?.role !== "assistant") continue;
+		const text = redactPrivateText(textParts(message.content));
+		if (text.trim()) {
+			const sourceId =
+				candidate.id ??
+				createHash("sha256").update(`${message.role}\0${text}`).digest("hex").slice(0, 16);
+			messages.push({ role: message.role, text, sourceId });
+		}
+	}
+	const seenSourceIds = new Set<string>();
+	const uniqueMessages = messages.filter((message) => {
+		if (seenSourceIds.has(message.sourceId)) return false;
+		seenSourceIds.add(message.sourceId);
+		return true;
+	});
+	const selectedSet = selectedSourceIds ? new Set(selectedSourceIds) : undefined;
+	const eligible = selectedSet
+		? uniqueMessages.filter((message) => selectedSet.has(message.sourceId))
+		: uniqueMessages;
+	const turnLimit =
+		typeof mode === "number" ? Math.max(1, Math.floor(mode)) : Number.POSITIVE_INFINITY;
+	let userTurns = 0;
+	let start = eligible.length;
+	for (let index = eligible.length - 1; index >= 0; index--) {
+		if (eligible[index].role === "user") userTurns++;
+		if (userTurns > turnLimit) break;
+		start = index;
+	}
+	const selected = eligible.slice(start);
+	const raw =
+		mode === "summary" && selected.length > 4
+			? [
+					`## Earlier context checkpoint\n${truncateUtf8(
+						selected
+							.slice(0, -4)
+							.map((message) => `${message.role}: ${message.text}`)
+							.join("\n"),
+						Math.floor(maxBytes / 3),
+					).text}`,
+					...selected
+						.slice(-4)
+						.map((message) => `## ${message.role}\n${message.text}`),
+				].join("\n\n")
+			: selected.map((message) => `## ${message.role}\n${message.text}`).join("\n\n");
+	const bounded = mode === "summary" ? truncateUtf8Tail(raw, maxBytes) : truncateUtf8(raw, maxBytes);
+	return {
+		text: bounded.text,
+		turns: selected.filter((message) => message.role === "user").length,
+		truncated: bounded.truncated,
+		sourceIds: selected.map((message) => message.sourceId),
+	};
+}