@ryan_nookpi/pi-extension-subagent 0.3.3 → 0.4.0

package/README.md

@@ -1,55 +1,21 @@
 # subagent
 
-Asynchronous subagent delegation for [pi](https://github.com/earendil-works/pi). Run specialist agents in dedicated child sessions, optionally pass selected main-session context, and receive results as follow-up messages.
-
-The primary interface is **CLI-style**: one `subagent` tool accepts a command string with verbs, options, and a `--` task separator, such as `subagent run worker --isolated -- review this change`. This provides one consistent grammar for single runs, continuation, parallel batches, sequential chains, inspection, and cleanup. These strings are tool input, not shell commands.
+Asynchronous subagent delegation for [pi](https://github.com/earendil-works/pi). Run specialist agents in dedicated child sessions, share main-session context when needed, and receive results as follow-up messages.
 
 > [!WARNING]
-> Subagents run headlessly without approval prompts. Claude-runtime agents use permission bypass, and pi-runtime agents can use every tool listed in their agent definition. This extension is not a sandbox. Use it only in trusted repositories with trusted prompts and agent definitions.
-
-## Requirements
-
-- pi 0.80.6 or later (tested with 0.80.7)
-- For `runtime: claude` with the default `claudeRuntime: "sdk"`: supported Anthropic authentication such as `ANTHROPIC_API_KEY`; see the [official Claude Agent SDK documentation](https://platform.claude.com/docs/en/agent-sdk/overview)
-- For `runtime: claude` with `claudeRuntime: "cli"`: the `claude` executable on `PATH` and an authenticated Claude Code installation
+> Subagents run headlessly without approval prompts. Claude-runtime agents bypass permissions, and pi-runtime agents can use every tool declared by their agent definition. This extension is not a sandbox. Use trusted repositories, prompts, and agent definitions only.
 
 ## Install
 
+Requires pi 0.80.6 or later. Compatibility is tested with pi 0.80.7.
+
 ```bash
 pi install npm:@ryan_nookpi/pi-extension-subagent
 ```
 
 ## Quick start
 
-### 1. Discover or seed agents
-
-Run this from the interactive pi UI:
-
-```text
-/subagents
-```
-
-If no agent definitions exist in any discovery location, the extension offers an optional starter pack containing:
-
-- Nine portable English agents: `browser`, `challenger`, `code-cleaner`, `reviewer`, `searcher`, `security-auditor`, `simplifier`, `verifier`, and `worker`
-- The `stress-interview` and `self-healing` skills, written in English and validated against the [Agent Skills specification](https://agentskills.io/specification)
-- Missing global `subagent` settings: `defaultAgent: "worker"`, `claudeRuntime: "cli"`, and symbol mappings for searcher, challenger, and browser
-
-Seeded agents intentionally omit model IDs and inherit the user's Pi model. Existing files and configured setting values are never overwritten. If the offer is declined, nothing is recorded or written, so the extension asks again the next time the list is still empty.
-
-Agents and subagent settings are available immediately after installation. Run `/reload` or start a new Pi session to activate the two newly copied skills. Headless sessions never install automatically; they return instructions to run `/subagents` interactively.
-
-The same offer is available from either agent-list tool:
-
-```json
-{ "command": "subagent agents" }
-```
-
-The separate `list-agents` tool behaves the same way. The `subagent ...` examples in this README are **tool command strings**, not terminal commands. Do not run them in Bash.
-
-### 2. Or create an agent manually
-
-Agents are Markdown files with YAML frontmatter. Create `~/.pi/agent/agents/worker.md` for a global agent, or `.pi/agents/worker.md` inside one project:
+Create a global agent at `~/.pi/agent/agents/worker.md`, or a project agent at `.pi/agents/worker.md`:
 
 ```markdown
 ---
@@ -63,18 +29,7 @@ runtime: pi
 Implement the requested changes and verify them.
 ```
 
-`name` and `description` are required. Optional fields are:
-
-- `runtime`: `pi` (default) or `claude`
-- `model`: runtime-compatible model ID
-- `thinking`: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`
-- `tools`: comma-separated tool names
-
-Omitted model, thinking, and tools values use that runtime's defaults.
-
-### 3. Launch a run
-
-Interactive user command:
+Then launch it from pi:
 
 ```text
 /sub:isolate worker implement the requested change and run tests
@@ -86,36 +41,54 @@ Equivalent AI tool call:
 { "command": "subagent run worker --isolated -- implement the requested change and run tests" }
 ```
 
-Runs are asynchronous in interactive mode. Wait for the automatic completion or failure follow-up instead of immediately polling `status` or `detail`.
+Tool launches are asynchronous. Wait for the automatic completion or failure follow-up instead of polling immediately.
+
+## Agent definitions
+
+Agent files use YAML frontmatter followed by the system prompt. `name` and `description` are required.
 
-## Agent discovery
+| Field | Description |
+| --- | --- |
+| `runtime` | `pi` (default) or `claude` |
+| `model` | Runtime-compatible model ID |
+| `thinking` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` |
+| `tools` | Comma-separated tool names |
+
+Omitted optional fields use runtime defaults.
 
-Definitions are loaded from the following locations. Later sources override earlier agents with the same name:
+Agents are discovered in this order; later definitions override earlier agents with the same name:
 
 1. `$PI_CODING_AGENT_DIR/agents/*.md` (normally `~/.pi/agent/agents/*.md`)
 2. Nearest `.claude/agents/**/*.md`
 3. Nearest `.pi/agents/*.md`
 
-Project `.claude/agents` files are discovered recursively. Project `.pi/agents` files are discovered only in the selected directory.
+`.claude/agents` is searched recursively. `.pi/agents` is not.
+
+Run `/subagents`, `subagent agents`, or the `list-agents` tool to inspect discovered agents.
+
+### Optional starter pack
 
-## Context modes and lifecycle
+If no agents are found, `/subagents` can offer an optional, opinionated starter pack. It copies nine agent templates, two example workflow skills, and missing global `subagent` settings. Existing files and configured values are not overwritten.
 
-- `--isolated` starts a dedicated child session without copying the main conversation. It is the default for `subagent` tool launches.
-- `--main` adds selected main-session context to the child task.
-- `/sub:isolate` selects isolated context; `/sub:main` selects main context.
-- `>>` and `>` use main-session context.
-- Continuing a run preserves its original context mode and child session. Supplying `--main` or `--isolated` to `continue` does not retroactively change it.
+The starter pack is not required. Decline it if you prefer to define agents manually. It fills a missing `claudeRuntime` setting with `cli`; without that setting, the extension default is `sdk`.
 
-Pi replaces and invalidates extension runtimes during `/new`, `/resume`, `/fork`, and reload. Active child processes are therefore aborted during `session_shutdown`, and the old session records why they stopped. Wait for active runs before replacing the parent session. This follows pi's [official extension lifecycle guidance](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md#long-lived-resources-and-shutdown).
+## Context modes
 
-## CLI-style tool interface
+- `--isolated` starts without copying the main conversation. It is the default for tool launches.
+- `--main` passes selected main-session context to the child.
+- `/sub:isolate` and `/sub:main` provide the same choice for interactive commands.
+- Continuing a run preserves its original child session and context mode.
 
-Instead of registering a separate tool for every operation, the extension exposes a compact CLI-style grammar through one `subagent` tool. The model passes the full command as the tool's `command` parameter; it must not invoke `subagent` from Bash or another shell.
+Active child processes stop when pi replaces or reloads the parent extension runtime. This follows pi's [official extension lifecycle guidance](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md#long-lived-resources-and-shutdown).
 
-The extension registers two main-session tools:
+## Tool interface
 
-- `list-agents`: return discovered agent definitions and runtime settings
-- `subagent`: accept one CLI-style command string
+The extension registers two tools:
+
+- `list-agents` — list discovered agents and runtime settings
+- `subagent` — execute a CLI-style command string
+
+These strings are tool input, not shell commands. Do not run them in Bash.
 
 ```text
 subagent help
@@ -123,15 +96,15 @@ subagent agents
 subagent runs
 subagent run <agent> [--main|--isolated] -- <task>
 subagent continue <runId> [--agent <agent>] [--main|--isolated] -- <task>
-subagent batch [--main|--isolated] --agent <agent> --task <task> [--agent <agent> --task <task> ...]
-subagent chain [--main|--isolated] --agent <agent> --task <task> [--agent <agent> --task <task> ...]
+subagent batch [--main|--isolated] --agent <agent> --task <task> ...
+subagent chain [--main|--isolated] --agent <agent> --task <task> ...
 subagent status <runId>
 subagent detail <runId>
 subagent abort <runId|runId,runId|all>
 subagent remove <runId|runId,runId|all>
 ```
 
-`batch` runs independent tasks in parallel. Quote tasks containing spaces:
+`batch` runs independent tasks in parallel:
 
 ```json
 {
@@ -147,46 +120,51 @@ subagent remove <runId|runId,runId|all>
 }
 ```
 
-Use `status` and `detail` only for explicit, one-off inspection. Repeated polling is unnecessary because completion is delivered automatically.
+Use `status` and `detail` for one-off inspection, not polling loops.
 
-## Slash commands
+## Interactive commands
 
-- `/subagents` — list discovered agents and settings
-- `/sub:main [agent|alias|runId] <task>` — launch with main-session context or continue a run
-- `/sub:isolate [agent|alias|runId] <task>` — launch in isolated context or continue a run
-- `/sub:peek [runId]` — show the latest response; defaults to the latest run
-- `/sub:open [runId]` — open session replay; defaults to the latest run
-- `/sub:history` — show all run history, including removed runs
-- `/sub:rm [runId]` — remove a run; defaults to the latest and aborts it if necessary
-- `/sub:clear [all]` — clear finished runs, or every run with `all`
-- `/sub:abort [runId|all]` — abort the latest running run, one run, or all running runs
+| Command | Description |
+| --- | --- |
+| `/subagents` | List agents and offer the starter pack when none exist |
+| `/sub:main [agent\|runId] <task>` | Launch or continue with main-session context |
+| `/sub:isolate [agent\|runId] <task>` | Launch or continue with isolated context |
+| `/sub:peek [runId]` | Show the latest result |
+| `/sub:open [runId]` | Open the child session replay |
+| `/sub:history` | Show run history, including removed runs |
+| `/sub:abort [runId\|all]` | Abort running work |
+| `/sub:rm [runId]` | Remove a run, aborting it first if necessary |
+| `/sub:clear [all]` | Clear finished runs, or all runs |
 
 When an agent is omitted, launch commands use `defaultAgent`.
 
-## Interactive shortcuts
+### Shortcuts
 
-| Shortcut | Behavior |
+| Shortcut | Description |
 | --- | --- |
-| `>> [agent\|runId] <task>` | Visible run using main-session context |
-| `> [agent\|runId] <task>` | Hidden run using main-session context; interactive UI only |
+| `>> [agent\|runId] <task>` | Visible run with main-session context |
+| `> [agent\|runId] <task>` | Hidden run with main-session context |
 | `#<runId> <task>` | Continue a run |
-| `>><symbol> <task>` | Visible run using the agent mapped in `symbolMap` |
-| `><symbol> <task>` | Hidden run using the mapped agent |
-| `<>runId` | Compact form of `/sub:peek runId` |
-| `<< [runId\|runId,runId]` | Abort selected running runs or clear selected finished runs; without arguments, abort the latest running run |
-| `<<< [all]` | Clear finished runs; use `all` to clear every run |
+| `>><symbol> <task>` / `><symbol> <task>` | Run an agent from `symbolMap` |
+| `<>runId` | Peek at a result |
+| `<< [runId\|runId,runId]` | Abort running or clear finished runs |
+| `<<< [all]` | Clear finished runs, or all runs |
 
-Hidden runs do not add start or completion messages to the main transcript. Read their output with `/sub:peek`, `<>runId`, or `/sub:open`. A plain `>` shortcut requires a space before its task; configured symbol shortcuts do not.
+Hidden runs are available only in the interactive UI and do not add start or completion messages to the main transcript.
 
-## Escalation from pi-runtime agents
+### Prompt mentions
 
-Pi-runtime subagent sessions receive an `ask_master` tool. It lets a child report a decision that the parent must make, then immediately terminates that child run. The parent receives the escalation as a follow-up.
+Use `>agent-name` inside a prompt to reference a discovered agent. Exact names are highlighted and rewritten to `subagent:agent-name` before the main LLM receives the prompt; they do not launch a run directly. Unknown names remain unchanged.
 
-Use `ask_master` only when the child cannot safely proceed, such as before a destructive operation or an unresolved architecture decision. Claude-runtime agents do not receive this tool; they report blockers in their final text instead.
+```text
+Delegate implementation to >worker and review to >reviewer.
+```
+
+A mention has no space after `>`. Launch shortcuts remain separate, such as `> worker implement this`.
 
 ## Configuration
 
-Global configuration belongs under `subagent` in `$PI_CODING_AGENT_DIR/settings.json` (normally `~/.pi/agent/settings.json`):
+Global settings belong under `subagent` in `$PI_CODING_AGENT_DIR/settings.json`:
 
 ```json
 {
@@ -212,65 +190,44 @@ A nearest project `.pi/subagent.json` overrides global values:
 }
 ```
 
-- `claudeRuntime`: `sdk` (default) or `cli`; applies only to agents with `runtime: claude`
-- `defaultAgent`: agent used when a launch omits its agent; defaults to `worker` and must match a discovered definition
-- `symbolMap`: one-character shortcuts mapped to non-empty agent names; a valid project map replaces the global map as a whole, while a malformed project map falls back to the valid global map
+- `claudeRuntime`: `sdk` (default) or `cli`; applies only to `runtime: claude`
+- `defaultAgent`: used when an interactive launch omits the agent; defaults to `worker`
+- `symbolMap`: one-character shortcuts mapped to agent names; a valid project map replaces the global map
 
-### Context guard override
-
-`PI_SUBAGENT_CONTEXT_GUARD_TOKENS` overrides the proactive context limit for pi-runtime children. Set it to a positive integer to apply that ceiling to every pi model. Set it to `0` or an empty value to disable the proactive guard and rely on native compaction or provider overflow handling.
-
-## Troubleshooting
+Set `PI_SUBAGENT_CONTEXT_GUARD_TOKENS` to a positive integer to override the proactive context limit for pi-runtime children. Set it to `0` or an empty value to disable the guard.
 
-### `Configured defaultAgent "worker" was not found`
+## Claude runtime
 
-Create a `worker` definition from the quick start, choose an existing agent explicitly, or change `defaultAgent`. Run `/subagents` to verify discovery before launching.
+The default Claude runtime uses the Claude Agent SDK and requires supported Anthropic authentication such as `ANTHROPIC_API_KEY`; see the [official Claude Agent SDK documentation](https://platform.claude.com/docs/en/agent-sdk/overview).
 
-### Claude SDK authentication failure
+For `claudeRuntime: "cli"`, install the `claude` executable, ensure it is on `PATH`, and authenticate Claude Code.
 
-Confirm the environment used to start pi has valid Anthropic authentication, such as `ANTHROPIC_API_KEY`. The SDK runtime does not require the Claude Code CLI.
+## Escalation
 
-### `spawn claude ENOENT`
+Pi-runtime children receive an `ask_master` tool. Calling it reports a decision or blocker to the parent and immediately terminates the child run. Use it only when the child cannot proceed safely.
 
-`claudeRuntime` is set to `cli`, but the `claude` executable is not on `PATH`. Install and authenticate Claude Code, or switch back to `claudeRuntime: "sdk"`.
+Claude-runtime children do not receive `ask_master`; they report blockers in their final response.
 
-### Hidden shortcut produces no transcript message
-
-That is intentional. Hidden `>` runs are human-only UI jobs. Inspect them with `/sub:peek`, `<>runId`, or `/sub:open`.
-
-### Debug runner termination
-
-The extension records process lifecycle diagnostics as `subagent-runner-diagnostic` custom entries in the parent session JSONL. They include run/batch IDs, parent and child PID/PGID, abort reason, internal kill cause, `exit`/`close` code and signal, settle reason, shutdown reason, and process-error stacks. Custom entries are not sent to the LLM and remain hidden unless an entry renderer is registered, as documented by pi's [`appendEntry` API](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md#piappendentrycustomtype-data).
-
-Run `/session` to find the current session file, set `SESSION_FILE` to that path, then extract only the diagnostic entries:
-
-```bash
-jq -c 'select(.type == "custom" and .customType == "subagent-runner-diagnostic") | {timestamp, data}' "$SESSION_FILE"
-```
-
-For batch failures, compare entries by `batchId` and `runId`, then follow each run from `spawn` through `kill_intent`, `exit`, `close`, and `settled`. Share only the selected diagnostic lines—not the full session file, which may contain prompts or tool output.
-
-To report a reproducible extension bug, create `subagent-issue.md` with the pi and extension versions, OS and Node version, launch mode/command, reproduction steps, expected and actual behavior, and the sanitized diagnostic lines. Then submit it with:
+## Troubleshooting
 
-```bash
-gh issue create --repo Jonghakseo/pi-extension \
-  --title "subagent: unexpected child termination" \
-  --body-file subagent-issue.md
-```
+- **`Configured defaultAgent "worker" was not found`** — create a matching agent, choose another agent explicitly, or update `defaultAgent`.
+- **Claude SDK authentication failure** — confirm the environment that starts pi contains valid Anthropic authentication.
+- **`spawn claude ENOENT`** — install Claude Code or switch `claudeRuntime` to `sdk`.
+- **Hidden run shows no transcript message** — inspect it with `/sub:peek`, `<>runId`, or `/sub:open`.
 
-Without GitHub CLI, use the repository's [new issue page](https://github.com/Jonghakseo/pi-extension/issues/new). Remove secrets and sensitive paths before attaching diagnostics.
+When reporting a bug, include the pi and extension versions, OS and Node version, launch command, reproduction steps, and sanitized error output. Do not attach full session files because they may contain prompts, tool output, or secrets.
 
-## Security and trust boundary
+## Security
 
-- Claude SDK execution uses `permissionMode: "bypassPermissions"` with `allowDangerouslySkipPermissions`; Claude CLI execution uses `--dangerously-skip-permissions`.
-- Pi-runtime children are headless and have unrestricted access to the tools declared by their agent.
-- Project agent definitions are repository-controlled instructions. Review `.pi/agents` and `.claude/agents` before running this extension in an unfamiliar repository.
-- Restrict each agent's `tools` list to what it needs. Avoid broad shell or write access for read-only review agents.
-- `--isolated` separates conversation context; it does not provide filesystem, process, credential, or network isolation.
+- Claude SDK uses permission bypass; Claude CLI uses `--dangerously-skip-permissions`.
+- Pi-runtime children can use every tool declared by their agent.
+- Project agent definitions are repository-controlled instructions. Review `.pi/agents` and `.claude/agents` in unfamiliar repositories.
+- Restrict each agent's `tools` list to the minimum required.
+- `--isolated` separates conversation context, not filesystem, process, credential, or network access.
 
 ## Stability
 
-This is a `0.1.x` release. The commands, configuration keys, agent frontmatter, and behaviors documented here are the supported surface. Internal TypeScript modules included in the npm tarball are implementation details and may change during the `0.x` series. Compatibility is currently tested against pi 0.80.7.
+This package is pre-1.0. Documented commands, configuration, and agent frontmatter are the supported surface; internal TypeScript modules may change between releases.
 
 ## License
 

package/cli.ts

@@ -53,8 +53,9 @@ export const SUBAGENT_CLI_HELP_TEXT = [
 	"    subagent help",
 	"    subagent agents",
 	"    subagent runs",
-	"    subagent status <runId>",
-	"    subagent detail <runId>",
+	"    subagent status <runId|groupId>",
+	"    subagent detail <runId|groupId>",
+	"      (groupId = the b_.../p_... id returned by batch/chain launches; finished groups are retained briefly)",
 	"",
 	"  Execution:",
 	"    subagent run <agent> [--main|--isolated] -- <task>",
@@ -167,6 +168,11 @@ function parseInteger(raw: string): number | null {
 	return Number.isInteger(value) ? value : null;
 }
 
+/** Group IDs returned by batch (`b_...`) and chain (`p_...`) launches. */
+function isGroupId(raw: string): boolean {
+	return /^[bp]_/.test(raw);
+}
+
 function parseRunTarget(
 	raw: string,
 	knownRunIds: number[] | undefined,
@@ -462,33 +468,35 @@ export function parseSubagentToolCommand(
 			return { type: "params", params: { asyncAction: "list" } };
 
 		case "status": {
-			const runIdRaw = args[0];
-			if (!runIdRaw)
+			const idRaw = args[0];
+			if (!idRaw)
 				return {
 					type: "error",
-					message: `❌ status requires <runId>\n\n✓ Example: subagent status 22\n\nSee all runs with: subagent runs`,
+					message: `❌ status requires <runId|groupId>\n\n✓ Example: subagent status 22\n✓ Example: subagent status b_1712... (batch/chain)\n\nSee all runs with: subagent runs`,
 				};
-			const runId = parseInteger(runIdRaw);
+			if (isGroupId(idRaw)) return { type: "params", params: { asyncAction: "status", groupId: idRaw } };
+			const runId = parseInteger(idRaw);
 			if (runId === null)
 				return {
 					type: "error",
-					message: `❌ Invalid runId: "${runIdRaw}"\n\nThe runId must be a number. See all runs with: subagent runs`,
+					message: `❌ Invalid id: "${idRaw}"\n\nUse a numeric runId or a batch/chain groupId (b_.../p_...). See all runs with: subagent runs`,
 				};
 			return { type: "params", params: { asyncAction: "status", runId } };
 		}
 
 		case "detail": {
-			const runIdRaw = args[0];
-			if (!runIdRaw)
+			const idRaw = args[0];
+			if (!idRaw)
 				return {
 					type: "error",
-					message: `❌ detail requires <runId>\n\n✓ Example: subagent detail 22\n\nSee all runs with: subagent runs`,
+					message: `❌ detail requires <runId|groupId>\n\n✓ Example: subagent detail 22\n✓ Example: subagent detail b_1712... (batch/chain)\n\nSee all runs with: subagent runs`,
 				};
-			const runId = parseInteger(runIdRaw);
+			if (isGroupId(idRaw)) return { type: "params", params: { asyncAction: "detail", groupId: idRaw } };
+			const runId = parseInteger(idRaw);
 			if (runId === null)
 				return {
 					type: "error",
-					message: `❌ Invalid runId: "${runIdRaw}"\n\nThe runId must be a number. See all runs with: subagent runs`,
+					message: `❌ Invalid id: "${idRaw}"\n\nUse a numeric runId or a batch/chain groupId (b_.../p_...). See all runs with: subagent runs`,
 				};
 			return { type: "params", params: { asyncAction: "detail", runId } };
 		}

package/commands.ts

@@ -42,11 +42,16 @@ import {
 	upsertPendingGroupCompletion,
 } from "./group-pending.js";
 import { enqueueSubagentInvocation } from "./invocation-queue.js";
+import {
+	createAgentMentionAutocompleteProvider,
+	registerAgentMentionHighlighting,
+	replaceAgentMentions,
+} from "./mentions.js";
 import { appendDisplayTaskUpdate, getSessionFileSize } from "./persisted-session.js";
 import { SUBAGENT_COMMANDS, type SubagentCommandName } from "./registration-manifest.js";
 import { readSessionReplayItems, SubagentSessionReplayOverlay } from "./replay.js";
 import { invokeWithAutoRetry, MAX_SUBAGENT_AUTO_RETRIES } from "./retry.js";
-import { getLatestRun, removeRun, trimCommandRunHistory } from "./run-utils.js";
+import { evictStaleFinishedGroups, getLatestRun, removeRun, trimCommandRunHistory } from "./run-utils.js";
 import {
 	getFinalOutput,
 	getLastNonEmptyLine,
@@ -819,6 +824,7 @@ function restoreRunsFromSession(store: SubagentStore, ctx: any, pi?: ExtensionAP
 	}
 
 	evictStalePendingGroupCompletions(STALE_PENDING_COMPLETION_MS);
+	evictStaleFinishedGroups(store);
 
 	// Fallback: if this session has no subagent markers at all, but we recently
 	// had in-memory runs for the same session file, reuse that snapshot so
@@ -904,6 +910,17 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentReg
 		commandDefinitions.set(name, definition);
 	};
 
+	// Prompt mentions are references for the main LLM, not direct launch shortcuts.
+	// Register this transform before the legacy `>` handlers so `>worker` cannot
+	// be mistaken for a configured one-character symbol shortcut.
+	pi.on("input", (event, ctx) => {
+		if (event.source === "extension") return { action: "continue" as const };
+
+		const transformedText = replaceAgentMentions(event.text ?? "", discoverAgents(ctx.cwd).agents);
+		if (transformedText === event.text) return { action: "continue" as const };
+		return { action: "transform" as const, text: transformedText, images: event.images };
+	});
+
 	pi.registerTool({
 		name: "list-agents",
 		label: "List Agents",
@@ -2300,6 +2317,19 @@ export async function handleBeforeAgentStart(
 export function handleSessionStart(pi: ExtensionAPI, store: SubagentStore, ctx: ExtensionContext): void {
 	restoreRunsFromSession(store, ctx, pi);
 	registerTerminalInputRedirect(ctx);
+
+	let cachedAgents = discoverAgents(ctx.cwd).agents;
+	let discoveredAt = Date.now();
+	const getAgents = () => {
+		if (Date.now() - discoveredAt >= 1_000) {
+			cachedAgents = discoverAgents(ctx.cwd).agents;
+			discoveredAt = Date.now();
+		}
+		return cachedAgents;
+	};
+
+	ctx.ui.addAutocompleteProvider((current) => createAgentMentionAutocompleteProvider(current, getAgents));
+	registerAgentMentionHighlighting(ctx, getAgents);
 }
 
 /** session_shutdown handler; index.ts invokes this after shutting down runs. */

package/constants.ts

@@ -30,6 +30,12 @@ export const SUBAGENT_STRONG_WAIT_MESSAGE =
 /** Maximum age (ms) for pending cross-session completions before eviction. */
 export const STALE_PENDING_COMPLETION_MS = 30 * 60 * 1_000;
 
+/** Max number of finished batch/chain group snapshots retained for `status`/`detail` queries. */
+export const MAX_FINISHED_GROUPS = 20;
+
+/** Max age (ms) a finished group snapshot is retained before eviction. */
+export const FINISHED_GROUP_TTL_MS = 30 * 60 * 1_000;
+
 /** Short label shown in the widget when inside a child session. */
 export const PARENT_HINT = "↩ parent (><)";
 

package/lifecycle.ts

@@ -114,6 +114,7 @@ export function shutdownSubagentRuns(store: SubagentStore, pi: ExtensionAPI, rea
 	store.globalLiveRuns.clear();
 	store.batchGroups.clear();
 	store.pipelines.clear();
+	store.finishedGroups.clear();
 	store.recentLaunchTimestamps.clear();
 	store.commandRuns.clear();
 	store.commandWidgetCtx = null;

package/mentions.ts

@@ -0,0 +1,177 @@
+import { CustomEditor, type ExtensionContext, type KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import type {
+	AutocompleteProvider,
+	AutocompleteSuggestions,
+	EditorComponent,
+	EditorTheme,
+	TUI,
+} from "@earendil-works/pi-tui";
+import type { AgentConfig } from "./agents.js";
+import { COMMAND_COMPLETION_LIMIT } from "./constants.js";
+
+const MENTION_PREFIX_PATTERN = /(?:^|[\s([{])>(?!>)([^\s>]*)$/;
+const MENTION_LEADING_BOUNDARY = "[\\s([{]";
+const MENTION_TRAILING_BOUNDARY = "(?=$|[\\s.,!?;:)}\\]])";
+const MENTION_HIGHLIGHT_WRAPPED = Symbol.for("pi-extension-subagent.mentionHighlightWrapped");
+const ANSI_CYAN = "\x1b[36m";
+const ANSI_RESET_FOREGROUND = "\x1b[39m";
+
+type HighlightableEditor = EditorComponent & Record<PropertyKey, unknown>;
+type RichEditorTheme = EditorTheme & {
+	fg?: (color: string, text: string) => string;
+};
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function buildAgentMentionPattern(agents: AgentConfig[]): {
+	pattern: RegExp;
+	canonicalNames: Map<string, string>;
+} | null {
+	const canonicalNames = new Map(agents.map((agent) => [agent.name.toLowerCase(), agent.name]));
+	const names = Array.from(canonicalNames.values())
+		.filter((name) => name.length > 0 && !/\s/.test(name))
+		.sort((left, right) => right.length - left.length)
+		.map(escapeRegExp);
+	if (names.length === 0) return null;
+
+	return {
+		pattern: new RegExp(`(^|${MENTION_LEADING_BOUNDARY})>(${names.join("|")})${MENTION_TRAILING_BOUNDARY}`, "gim"),
+		canonicalNames,
+	};
+}
+
+function styleAgentMention(text: string, theme: EditorTheme): string {
+	const richTheme = theme as RichEditorTheme;
+	for (const color of ["subagentMention", "syntaxType", "toolTitle"]) {
+		try {
+			const styled = richTheme.fg?.(color, text);
+			if (styled && styled !== text) return styled;
+		} catch {
+			// Custom theme keys are optional.
+		}
+	}
+	return theme.selectList?.selectedText?.(text) ?? `${ANSI_CYAN}${text}${ANSI_RESET_FOREGROUND}`;
+}
+
+/** Return the incomplete agent name after a mention marker at the cursor. */
+export function extractAgentMentionQuery(textBeforeCursor: string): string | undefined {
+	return MENTION_PREFIX_PATTERN.exec(textBeforeCursor)?.[1];
+}
+
+/** Filter mention candidates by case-insensitive containment, preferring prefix matches. */
+export function filterAgentMentionCandidates(agents: AgentConfig[], query: string): AgentConfig[] {
+	const normalizedQuery = query.toLowerCase();
+	return agents
+		.filter((agent) => agent.name.toLowerCase().includes(normalizedQuery))
+		.sort((left, right) => {
+			const leftName = left.name.toLowerCase();
+			const rightName = right.name.toLowerCase();
+			const leftStartsWith = leftName.startsWith(normalizedQuery);
+			const rightStartsWith = rightName.startsWith(normalizedQuery);
+			if (leftStartsWith !== rightStartsWith) return leftStartsWith ? -1 : 1;
+			return leftName.localeCompare(rightName);
+		})
+		.slice(0, COMMAND_COMPLETION_LIMIT);
+}
+
+/** Replace exact, discovered `>agent` mentions with the main-LLM-friendly `subagent:agent` form. */
+export function replaceAgentMentions(text: string, agents: AgentConfig[]): string {
+	const mentionPattern = buildAgentMentionPattern(agents);
+	if (!mentionPattern) return text;
+
+	return text.replace(mentionPattern.pattern, (_match, boundary: string, name: string) => {
+		const canonicalName = mentionPattern.canonicalNames.get(name.toLowerCase()) ?? name;
+		return `${boundary}subagent:${canonicalName}`;
+	});
+}
+
+/** Highlight only exact mentions for agents that are currently discoverable. */
+export function highlightAgentMentions(
+	text: string,
+	agents: AgentConfig[],
+	style: (mention: string) => string,
+): string {
+	const mentionPattern = buildAgentMentionPattern(agents);
+	if (!mentionPattern) return text;
+
+	return text.replace(mentionPattern.pattern, (_match, boundary: string, name: string) => {
+		return `${boundary}${style(`>${name}`)}`;
+	});
+}
+
+export function createAgentMentionHighlightEditor(
+	baseEditor: EditorComponent,
+	getAgents: () => AgentConfig[],
+	theme: EditorTheme,
+): EditorComponent {
+	const highlightableEditor = baseEditor as HighlightableEditor;
+	if (highlightableEditor[MENTION_HIGHLIGHT_WRAPPED]) return baseEditor;
+
+	return new Proxy(highlightableEditor, {
+		get(target, property) {
+			if (property === MENTION_HIGHLIGHT_WRAPPED) return true;
+			if (property === "render") {
+				return (width: number) => {
+					const agents = getAgents();
+					return target
+						.render(width)
+						.map((line) => highlightAgentMentions(line, agents, (mention) => styleAgentMention(mention, theme)));
+				};
+			}
+
+			const value = Reflect.get(target, property, target);
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+		set(target, property, value) {
+			return Reflect.set(target, property, value, target);
+		},
+	}) as EditorComponent;
+}
+
+export function registerAgentMentionHighlighting(ctx: ExtensionContext, getAgents: () => AgentConfig[]): void {
+	if (ctx.mode !== "tui") return;
+
+	const previousEditorFactory = ctx.ui.getEditorComponent();
+	ctx.ui.setEditorComponent((tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) => {
+		const baseEditor = previousEditorFactory?.(tui, theme, keybindings) ?? new CustomEditor(tui, theme, keybindings);
+		return createAgentMentionHighlightEditor(baseEditor, getAgents, theme);
+	});
+}
+
+export function createAgentMentionAutocompleteProvider(
+	current: AutocompleteProvider,
+	getAgents: () => AgentConfig[],
+): AutocompleteProvider {
+	return {
+		triggerCharacters: Array.from(new Set([...(current.triggerCharacters ?? []), ">"])),
+		async getSuggestions(lines, cursorLine, cursorCol, options): Promise<AutocompleteSuggestions | null> {
+			const currentLine = lines[cursorLine] ?? "";
+			const query = extractAgentMentionQuery(currentLine.slice(0, cursorCol));
+			if (query === undefined) {
+				return current.getSuggestions(lines, cursorLine, cursorCol, options);
+			}
+
+			const candidates = filterAgentMentionCandidates(getAgents(), query);
+			if (options.signal.aborted || candidates.length === 0) return null;
+
+			return {
+				prefix: `>${query}`,
+				items: candidates.map((agent) => ({
+					value: `>${agent.name}`,
+					label: `>${agent.name}`,
+					description: agent.description,
+				})),
+			};
+		},
+
+		applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+			return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+		},
+
+		shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+			return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+		},
+	};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryan_nookpi/pi-extension-subagent",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Asynchronous subagent delegation for pi with run, batch, chain, and continuation workflows.",
   "license": "MIT",
   "repository": {
@@ -40,6 +40,7 @@
     "lifecycle.ts",
     "invocation-queue.ts",
     "live-preview.ts",
+    "mentions.ts",
     "persisted-session.ts",
     "replay.ts",
     "registration-manifest.ts",

package/run-utils.ts

@@ -7,8 +7,15 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { FINISHED_GROUP_TTL_MS, MAX_FINISHED_GROUPS, STATUS_OUTPUT_PREVIEW_MAX_CHARS } from "./constants.js";
 import type { SubagentStore } from "./store.js";
-import type { CommandRunState } from "./types.js";
+import type {
+	BatchGroupState,
+	CommandRunState,
+	FinishedGroupMember,
+	FinishedGroupSnapshot,
+	PipelineState,
+} from "./types.js";
 import { updateCommandRunsWidget, type WidgetRenderCtx } from "./widget.js";
 
 export interface RemoveRunOptions {
@@ -201,3 +208,115 @@ export function trimCommandRunHistory(
 
 	return removedRunIds;
 }
+
+// ── Finished-group retention ────────────────────────────────────────────────
+// Batch/chain groups are deleted from the live store once their completion is
+// delivered. To keep `subagent status/detail <groupId>` working for a short
+// window afterward, we retain an immutable snapshot per finished group.
+
+function memberOutput(run: CommandRunState, fallback?: string): string {
+	return run.lastOutput?.trim() || run.lastLine?.trim() || fallback?.trim() || "(no output)";
+}
+
+/** Build a finished-group snapshot from a completed batch group. */
+export function snapshotBatchGroup(
+	store: SubagentStore,
+	batch: BatchGroupState,
+	terminalStatus: FinishedGroupSnapshot["terminalStatus"],
+): FinishedGroupSnapshot {
+	let failed = 0;
+	const members: FinishedGroupMember[] = batch.runIds.map((runId) => {
+		const run = store.commandRuns.get(runId);
+		if (!run) {
+			if (batch.failedRunIds.has(runId)) failed++;
+			return {
+				summaryLine: `#${runId} [gone] (run no longer available)`,
+				output: batch.pendingResults.get(runId)?.trim() || "(no output)",
+			};
+		}
+		if (run.status === "error" || batch.failedRunIds.has(runId)) failed++;
+		return { summaryLine: formatCommandRunSummary(run), output: memberOutput(run, batch.pendingResults.get(runId)) };
+	});
+	return {
+		groupId: batch.batchId,
+		kind: "batch",
+		terminalStatus,
+		finishedAt: Date.now(),
+		total: batch.runIds.length,
+		failed,
+		members,
+	};
+}
+
+/** Build a finished-group snapshot from a completed pipeline. */
+export function snapshotPipeline(
+	pipeline: PipelineState,
+	terminalStatus: FinishedGroupSnapshot["terminalStatus"],
+): FinishedGroupSnapshot {
+	const members: FinishedGroupMember[] = pipeline.stepResults.map((step, index) => ({
+		summaryLine: `Step ${index + 1} · #${step.runId} ${step.agent} · ${step.status}`,
+		output: step.output?.trim() || "(no output)",
+		task: step.task,
+	}));
+	return {
+		groupId: pipeline.pipelineId,
+		kind: "chain",
+		terminalStatus,
+		finishedAt: Date.now(),
+		total: pipeline.stepResults.length,
+		failed: pipeline.stepResults.filter((step) => step.status === "error").length,
+		members,
+	};
+}
+
+/** Retain a finished-group snapshot, evicting the oldest entries past the cap. */
+export function retireFinishedGroup(store: SubagentStore, snapshot: FinishedGroupSnapshot): void {
+	// Re-insert to refresh insertion order (most-recent last).
+	store.finishedGroups.delete(snapshot.groupId);
+	store.finishedGroups.set(snapshot.groupId, snapshot);
+	while (store.finishedGroups.size > MAX_FINISHED_GROUPS) {
+		const oldest = store.finishedGroups.keys().next().value;
+		if (oldest === undefined) break;
+		store.finishedGroups.delete(oldest);
+	}
+}
+
+/** Evict finished-group snapshots older than the retention TTL. Returns count removed. */
+export function evictStaleFinishedGroups(store: SubagentStore, now = Date.now()): number {
+	let removed = 0;
+	for (const [groupId, snapshot] of store.finishedGroups) {
+		if (now - snapshot.finishedAt > FINISHED_GROUP_TTL_MS) {
+			store.finishedGroups.delete(groupId);
+			removed++;
+		}
+	}
+	return removed;
+}
+
+function formatFinishedAge(finishedAt: number, now = Date.now()): string {
+	const seconds = Math.max(0, Math.round((now - finishedAt) / 1000));
+	if (seconds < 60) return `${seconds}s ago`;
+	const minutes = Math.round(seconds / 60);
+	return `${minutes}m ago`;
+}
+
+/** Render a retained finished-group snapshot for `status` (summary) or `detail` (with output). */
+export function formatFinishedGroupStatus(snapshot: FinishedGroupSnapshot, detailed: boolean): string {
+	const label = snapshot.kind === "batch" ? "subagent-batch" : "subagent-chain";
+	const failedSuffix = snapshot.failed > 0 ? `, ${snapshot.failed} failed` : "";
+	const header = `[${label}#${snapshot.groupId}] ${snapshot.terminalStatus} · ${snapshot.total} ${
+		snapshot.kind === "batch" ? "runs" : "steps"
+	}${failedSuffix} · finished ${formatFinishedAge(snapshot.finishedAt)}`;
+	const body = snapshot.members
+		.map((member) => {
+			if (!detailed) return member.summaryLine;
+			const output =
+				member.output.length > STATUS_OUTPUT_PREVIEW_MAX_CHARS
+					? `${member.output.slice(0, STATUS_OUTPUT_PREVIEW_MAX_CHARS)}\n\n... [truncated]`
+					: member.output;
+			const taskLine = member.task ? `Task: ${member.task}\n` : "";
+			return `${member.summaryLine}\n${taskLine}${output}`;
+		})
+		.join(detailed ? "\n\n" : "\n");
+	return `${header}\n\n${body}`;
+}

package/store.ts

@@ -5,7 +5,14 @@
 import type { Message } from "@earendil-works/pi-ai";
 import { visibleWidth } from "@earendil-works/pi-tui";
 import { getDisplayItems, getFinalOutput, getLastNonEmptyLine, getLatestActivityPreview } from "./runner.js";
-import type { BatchGroupState, CommandRunState, GlobalRunEntry, PipelineState, SingleResult } from "./types.js";
+import type {
+	BatchGroupState,
+	CommandRunState,
+	FinishedGroupSnapshot,
+	GlobalRunEntry,
+	PipelineState,
+	SingleResult,
+} from "./types.js";
 import type { WidgetRenderCtx } from "./widget.js";
 
 export const COLLAPSED_ITEM_COUNT = 10;
@@ -40,6 +47,8 @@ export interface SubagentStore {
 	batchGroups: Map<string, BatchGroupState>;
 	/** In-memory sequential pipelines launched via the tool. */
 	pipelines: Map<string, PipelineState>;
+	/** Retained snapshots of finished batch/chain groups, keyed by groupId (insertion-ordered). */
+	finishedGroups: Map<string, FinishedGroupSnapshot>;
 }
 
 export function createStore(): SubagentStore {
@@ -59,6 +68,7 @@ export function createStore(): SubagentStore {
 		recentLaunchTimestamps: new Map(),
 		batchGroups: new Map(),
 		pipelines: new Map(),
+		finishedGroups: new Map(),
 	};
 }
 

package/tool-execute.ts

@@ -41,7 +41,17 @@ import {
 import { clearPendingGroupCompletion, upsertPendingGroupCompletion } from "./group-pending.js";
 import { enqueueSubagentInvocation } from "./invocation-queue.js";
 import { appendDisplayTaskUpdate, getSessionFileSize } from "./persisted-session.js";
-import { clearFinishedRuns, formatCommandRunSummary, removeRun, trimCommandRunHistory } from "./run-utils.js";
+import {
+	clearFinishedRuns,
+	evictStaleFinishedGroups,
+	formatCommandRunSummary,
+	formatFinishedGroupStatus,
+	removeRun,
+	retireFinishedGroup,
+	snapshotBatchGroup,
+	snapshotPipeline,
+	trimCommandRunHistory,
+} from "./run-utils.js";
 import { getFinalOutput, getLastNonEmptyLine, runSingleAgent } from "./runner.js";
 import {
 	buildMainContextText,
@@ -54,10 +64,12 @@ import {
 import { formatStarterPackNotice, offerStarterPackIfEmpty } from "./starter-pack.js";
 import { type SubagentStore, updateRunFromResult } from "./store.js";
 import type {
+	BatchGroupState,
 	BatchOrChainItem,
 	CommandRunState,
 	OnUpdateCallback,
 	PendingCompletion,
+	PipelineState,
 	PipelineStepResult,
 	SingleResult,
 	SubagentDetails,
@@ -583,6 +595,47 @@ function formatPipelineSummary(
 	return `[subagent-chain#${pipelineId}] ${terminalStatus}\n\n${steps}`;
 }
 
+function previewOutput(output: string): string {
+	const trimmed = output.trim() || "(no output yet)";
+	return trimmed.length > STATUS_OUTPUT_PREVIEW_MAX_CHARS
+		? `${trimmed.slice(0, STATUS_OUTPUT_PREVIEW_MAX_CHARS)}\n\n... [truncated]`
+		: trimmed;
+}
+
+function formatBatchGroupStatus(store: SubagentStore, batch: BatchGroupState, detailed: boolean): string {
+	const total = batch.runIds.length;
+	const done = batch.completedRunIds.size;
+	const failed = batch.failedRunIds.size;
+	const header = `[subagent-batch#${batch.batchId}] running · ${done}/${total} finished${
+		failed > 0 ? `, ${failed} failed` : ""
+	}`;
+	const body = batch.runIds
+		.map((runId) => {
+			const run = store.commandRuns.get(runId);
+			if (!run) return `#${runId} (unavailable)`;
+			const summary = formatCommandRunSummary(run);
+			if (!detailed) return summary;
+			return `${summary}\n${previewOutput(run.lastOutput ?? run.lastLine ?? "")}`;
+		})
+		.join(detailed ? "\n\n" : "\n");
+	return `${header}\n\n${body}`;
+}
+
+function formatPipelineGroupStatus(store: SubagentStore, pipeline: PipelineState, detailed: boolean): string {
+	const finishedCount = pipeline.stepResults.length;
+	const header = `[subagent-chain#${pipeline.pipelineId}] running · step ${pipeline.currentIndex + 1} (${finishedCount} finished)`;
+	const parts = pipeline.stepResults.map((step, index) => {
+		const line = `Step ${index + 1} · #${step.runId} ${step.agent} · ${step.status}`;
+		return detailed ? `${line}\nTask: ${step.task}\n${previewOutput(step.output)}` : line;
+	});
+	const runningRunId = pipeline.stepRunIds[finishedCount];
+	if (runningRunId !== undefined) {
+		const run = store.commandRuns.get(runningRunId);
+		if (run) parts.push(`Step ${finishedCount + 1} · ${formatCommandRunSummary(run)}`);
+	}
+	return `${header}\n\n${parts.join(detailed ? "\n\n" : "\n")}`;
+}
+
 function toLaunchSummary(
 	runState: Pick<CommandRunState, "agent" | "id" | "batchId" | "pipelineId" | "pipelineStepIndex">,
 	mode: SubagentLaunchSummary["mode"],
@@ -842,6 +895,43 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 			};
 		}
 
+		if ((asyncAction === "status" || asyncAction === "detail") && typeof cmdParams.groupId === "string") {
+			evictStaleFinishedGroups(store);
+			const groupId = cmdParams.groupId;
+			const detailed = asyncAction === "detail";
+			const finished = store.finishedGroups.get(groupId);
+			if (finished) {
+				return {
+					content: [{ type: "text", text: withIdleRunWarning(formatFinishedGroupStatus(finished, detailed)) }],
+					details: makeDetails("single"),
+				};
+			}
+			const batch = store.batchGroups.get(groupId);
+			if (batch) {
+				return {
+					content: [{ type: "text", text: withIdleRunWarning(formatBatchGroupStatus(store, batch, detailed)) }],
+					details: makeDetails("single"),
+				};
+			}
+			const pipeline = store.pipelines.get(groupId);
+			if (pipeline) {
+				return {
+					content: [{ type: "text", text: withIdleRunWarning(formatPipelineGroupStatus(store, pipeline, detailed)) }],
+					details: makeDetails("single"),
+				};
+			}
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Unknown subagent group "${groupId}". Finished groups are retained only briefly; use \`subagent runs\` to inspect individual runs.`,
+					},
+				],
+				details: makeDetails("single"),
+				isError: true,
+			};
+		}
+
 		const rawRunIds = Array.isArray(cmdParams.runIds) ? cmdParams.runIds : undefined;
 		const invalidRunIds = (rawRunIds ?? []).filter((value) => !Number.isInteger(value));
 		if (invalidRunIds.length > 0) {
@@ -1471,6 +1561,9 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 				const orderedRuns = runStates.map(({ runState }) => runState);
 				const hasError = finalizedRuns.some((finalized) => finalized.isError);
 				const content = formatBatchSummary(batchId, orderedRuns, hasError ? "error" : "completed");
+				const batchForSnapshot = store.batchGroups.get(batchId);
+				if (batchForSnapshot)
+					retireFinishedGroup(store, snapshotBatchGroup(store, batchForSnapshot, hasError ? "error" : "completed"));
 				for (const { runState } of runStates) cleanupRunAfterFinalDelivery(runState.id);
 				clearPendingGroupCompletion("batch", batchId);
 				store.batchGroups.delete(batchId);
@@ -1525,6 +1618,7 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 									runSummaries: orderedRuns.map((run) => buildRunAnalyticsSummary(run)),
 								},
 							};
+							retireFinishedGroup(store, snapshotBatchGroup(store, batch, batchTerminalStatus));
 							if (isInOriginSession(ctx, batch.originSessionFile)) {
 								pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
 								clearPendingGroupCompletion("batch", batchId);
@@ -1579,6 +1673,7 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 									runSummaries: orderedRuns.map((run) => buildRunAnalyticsSummary(run)),
 								},
 							};
+							retireFinishedGroup(store, snapshotBatchGroup(store, batch, "error"));
 							if (isInOriginSession(ctx, batch.originSessionFile)) {
 								pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
 								clearPendingGroupCompletion("batch", batchId);
@@ -1754,6 +1849,7 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 				const hasError = pipeline.stepResults.some((step) => step.status === "error");
 				if (terminalStatus === "completed" && hasError) terminalStatus = "error";
 				const content = formatPipelineSummary(pipelineId, pipeline.stepResults, terminalStatus);
+				retireFinishedGroup(store, snapshotPipeline(pipeline, terminalStatus));
 				for (const runId of pipeline.stepRunIds) cleanupRunAfterFinalDelivery(runId);
 				clearPendingGroupCompletion("chain", pipelineId);
 				store.pipelines.delete(pipelineId);
@@ -1892,6 +1988,7 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 								runSummaries: orderedRuns.map((run) => buildRunAnalyticsSummary(run)),
 							},
 						};
+						retireFinishedGroup(store, snapshotPipeline(pipeline, terminalStatus));
 						if (isInOriginSession(ctx, pipeline.originSessionFile)) {
 							pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
 							clearPendingGroupCompletion("chain", pipelineId);

package/types.ts

@@ -183,6 +183,30 @@ export interface PipelineState {
 	pendingCompletion?: PendingCompletion;
 }
 
+/** A single member (batch run or chain step) captured in a finished-group snapshot. */
+export interface FinishedGroupMember {
+	/** Pre-rendered one-line summary, frozen at retirement time. */
+	summaryLine: string;
+	/** Full member output, truncated only when rendered. */
+	output: string;
+	/** Chain step task (omitted for batch runs). */
+	task?: string;
+}
+
+/**
+ * Immutable snapshot of a completed batch/chain group, retained briefly so
+ * `subagent status/detail <groupId>` still works after the live group is gone.
+ */
+export interface FinishedGroupSnapshot {
+	groupId: string;
+	kind: "batch" | "chain";
+	terminalStatus: "completed" | "error" | "stopped";
+	finishedAt: number;
+	total: number;
+	failed: number;
+	members: FinishedGroupMember[];
+}
+
 export const ListAgentsParams = Type.Object({});
 
 export const SubagentParams = Type.Object({