@maxiaochao/pi-toolkit 0.9.6 → 0.10.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2026-10-08 - v0.10.0
+
+- bundle herdr-subagents v0.2.0: replace Tiny Subagent with visible interactive Herdr agents and durable batch workflows
+- replace Tiny Subagent's hidden print/shell execution with Herdr Subagents: visible interactive Pi Agents, one exclusive on-demand pane per task, Fleet keyboard navigation, durable blocked/history continuation, parent-session cancellation, and focus-safe batch tab cleanup
+- fix Herdr Subagents Fleet state after blocked responses, preserve the active task widget while later background runs queue, and share ownership, pane-allocation, and status-reduction logic across recovery paths
+
 ## 2026-10-08 - v0.9.6
 
 - bundle codex-edit v0.1.9: install the pinned Pi runtime for clean-runner publication tests

package/README.md

@@ -25,7 +25,7 @@ The root package embeds the child-package source snapshots listed below. Install
 | [pi-todo](packages/todo/README.md) | Session plans, automatic task advancement, `/todos` | `pi install npm:@maxiaochao/pi-todo` | `pi update npm:@maxiaochao/pi-todo` |
 | [pi-cache-export](packages/cache-export/README.md) | Tau-aligned interactive cache dashboard for Pi sessions | `pi install npm:@maxiaochao/pi-cache-export` | `pi update npm:@maxiaochao/pi-cache-export` |
 | [pi-codex-edit](packages/codex-edit/README.md) | Codex-harness `apply_patch` routing for selected GPT models | `pi install npm:@maxiaochao/pi-codex-edit` | `pi update npm:@maxiaochao/pi-codex-edit` |
-| [pi-tiny-subagent](packages/tiny-subagent/README.md) | One focused task in a fresh child Pi context | `pi install npm:@maxiaochao/pi-tiny-subagent` | `pi update npm:@maxiaochao/pi-tiny-subagent` |
+| [pi-herdr-subagents](packages/herdr-subagents/README.md) | Interactive Herdr Pi Agents with bounded concurrency, direct navigation, and recovery | `pi install npm:@maxiaochao/pi-herdr-subagents` | `pi update npm:@maxiaochao/pi-herdr-subagents` |
 | [pi-worktree](packages/worktree/README.md) | Worktree CLI, completion, installer, and agent skill | `pi install npm:@maxiaochao/pi-worktree` | `pi update npm:@maxiaochao/pi-worktree` |
 
 Each child README owns its feature description, motivation or upstream alignment, examples, screenshots/demos, configuration, and test documentation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.9.6",
+  "version": "0.10.0",
   "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [
@@ -15,7 +15,7 @@
     "packages/todo",
     "packages/cache-export",
     "packages/codex-edit",
-    "packages/tiny-subagent",
+    "packages/herdr-subagents",
     "packages/worktree",
     "themes",
     "README.md",
@@ -34,7 +34,7 @@
       "./packages/cache-export/extensions/cache-export.ts",
       "./extensions/btw/index.ts",
       "./packages/codex-edit/extensions/codex-edit.ts",
-      "./packages/tiny-subagent/extensions/tiny-subagent.ts"
+      "./packages/herdr-subagents/extensions/herdr-subagents.ts"
     ],
     "skills": [
       "./skills",
@@ -57,8 +57,8 @@
     "ws": "^8.19.0"
   },
   "scripts": {
-    "test": "node tests/package-layout.mjs && npm --prefix packages/todo test && npm --prefix packages/cache-export test && npm --prefix packages/codex-edit test && npm --prefix packages/tiny-subagent test && npm --prefix packages/worktree test && node --experimental-strip-types extensions/btw/tests/history.mjs",
-    "load-test": "pi -ne -e ./packages/todo/extensions/todo.ts && pi -ne -e ./packages/cache-export/extensions/cache-export.ts && pi -ne -e ./extensions/btw/index.ts && pi -ne -e ./packages/codex-edit/extensions/codex-edit.ts && pi -ne -e ./packages/tiny-subagent/extensions/tiny-subagent.ts",
+    "test": "node tests/package-layout.mjs && npm --prefix packages/todo test && npm --prefix packages/cache-export test && npm --prefix packages/codex-edit test && npm --prefix packages/herdr-subagents test && npm --prefix packages/worktree test && node --experimental-strip-types extensions/btw/tests/history.mjs",
+    "load-test": "pi -ne -e ./packages/todo/extensions/todo.ts && pi -ne -e ./packages/cache-export/extensions/cache-export.ts && pi -ne -e ./extensions/btw/index.ts && pi -ne -e ./packages/codex-edit/extensions/codex-edit.ts && pi -ne -e ./packages/herdr-subagents/extensions/herdr-subagents.ts",
     "eval:agents": "node evaluations/agents-md/run.mjs",
     "eval:agents:test": "node evaluations/agents-md/tests/run-tests.mjs",
     "postinstall": "node scripts/install-agents.mjs"

package/packages/herdr-subagents/CHANGELOG.md

@@ -0,0 +1,41 @@
+## 2026-10-08 - v0.2.0
+
+- replace Tiny Subagent with visible interactive Herdr agents and durable batch workflows
+- Skip tool and command registration outside a Herdr workspace so unavailable Subagent capabilities do not enter the model context.
+- Preserve newly allocated panes when blocked runs resume, stop blindly retrying Herdr resource-creating commands after uncertain failures, and prevent concurrent historical resumes from writing the same Pi session.
+- Isolate malformed queue/history entries so healthy active runs and durable history remain recoverable, and share durable attempt settlement plus task projection contracts across execution modes.
+- Retain blocked Fleet and dispatcher ownership after stateless response errors, and include public test entrypoints in the published package.
+- Preserve every pending stale-tab cleanup across repeated pane migrations, retry all of them during startup reconciliation, and surface allocator cleanup failures through batch updates.
+- Keep persisted reports authoritative even when Herdr transport fails after submission, persist failure reports for historical follow-ups, reject resume attempts against active or cleanup-pending runs, recover terminal deferred cleanup on startup, preserve cancelled ownership on shutdown, keep recovered Agent attempts aligned with durable turns, archive malformed turns, remove rejected background queue entries, support Pi enhanced keyboard sequences and authoritative status rendering, centralize lifecycle metadata, surface control-plane and cleanup failures, merge deferred cleanup against current durable state, and force-close focused tabs when parent shutdown is already active.
+- Share strict report parsing across live and recovered paths, validate durable task ordering, surface unreadable queue/history records, reconcile prior sessions even within one Pi process, keep settled Fleet rows navigable, preserve surviving sibling panes during dead-pane recovery, and retain cleanup diagnostics.
+- Keep queued and blocked siblings alive when one blocked response fails, centralize authoritative run-status transitions, and bind focus-deferred tab cleanup to parent-session shutdown.
+- Retain dispatcher and Fleet ownership while a batch is blocked, centralize task/turn transitions, surface transient pane lookup failures, and notify deferred single-task cleanup failures.
+- Fail reconciliation when task records are unreadable, archive malformed child reports before replacing them with valid failure records, and keep durable history and saved-session follow-up usable.
+- Keep startup reconciliation moving past truncated child reports, resume dispatch after recovery errors, clear stale blocked fields after authoritative follow-ups, and surface deferred cleanup failures.
+- Stream Fleet row and pane updates while a blocked answer resumes work and releases queued siblings.
+- Keep the active Fleet widget stable when another background run is queued, refresh rows and pane navigation after blocked responses, and cover the public extension UI/input wiring with injectable dependencies.
+- Centralize parent ownership, run-status aggregation, and serialized pane allocation across initial, continued, recovered, and historical runs.
+- Run every initial task, blocked response, recovered task, and historical follow-up as a visible interactive Pi Agent through Herdr Agent start/prompt; remove print mode, pane shell injection, completion markers, and marker polling.
+- Give every started task a new on-demand pane, retain completed panes until the batch settles, and then close the whole tab with focus-safe cleanup.
+- Add a flat fully described tool schema with runtime mode validation and a Fleet-style task list with direct keyboard pane navigation.
+- Continue historical sessions as durable turns of the same logical task, and cancel/archive unfinished work when the parent Pi session closes.
+- Persist and reconcile queued/running work across parent shutdown, avoid retrying uncertain startup operations, preserve post-submit failures, warn without timing out stalled children, and atomically replace state snapshots.
+- Add compact project-local history, saved-session follow-ups in new Herdr tabs, explicit per-run cleanup, unlimited retention, and generated-state Git exclusion.
+- Support structured `needs-input` reports, preserve blocked panes and sessions, and resume the original child with `action: respond`.
+- Queue background batches behind one active run, return stable IDs immediately, keep progress visible, and send one compact run-level parent notification.
+- Show active run counts in a persistent widget, expose compact `/herdr-subagents active` and pane focus navigation, update progress labels, and defer cleanup while a completed tab is focused.
+- Execute ordered read-only batches with FIFO bounded concurrency, stable result order, and sibling failure isolation; force write-capable runs to serial execution.
+- Add built-in worker, explorer, and reviewer personas with project/global/package discovery precedence.
+- Add merged global and project model, thinking, skill, and concurrency settings plus `/herdr-subagents` discovery commands.
+- Run one synchronous subagent in a dedicated, unfocused Herdr tab and close it after completion.
+- Require a structured child report and return only its summary and document paths to the parent.
+- Persist run/task metadata, the full result, and the child Pi session under `.pi/herdr-subagents/runs`.
+
+## 2026-09-30 - v0.1.1
+
+- Add standalone testing documentation and production-runner screenshot/demo media.
+- Align the package manifest and root bundle with the shared workspace source.
+
+## 2026-09-01 - v0.1.0
+
+- initial release

package/packages/herdr-subagents/README.md

@@ -0,0 +1,155 @@
+# @maxiaochao/pi-herdr-subagents
+
+A Pi extension that runs focused foreground or background work as normal interactive Pi Agents in visible Herdr panes. Full answers and sessions stay in project-local records while the parent receives only concise summaries and document paths.
+
+![Herdr Subagents production runner screenshot](docs/screenshot.png)
+
+## Demo
+
+![Herdr Subagents demo](docs/demo.gif)
+
+## Requirements and install
+
+Run Pi inside Herdr, then install the package:
+
+```bash
+pi install npm:@maxiaochao/pi-herdr-subagents
+```
+
+Update an existing standalone installation with:
+
+```bash
+pi update npm:@maxiaochao/pi-herdr-subagents
+```
+
+The full `@maxiaochao/pi-toolkit` package also bundles this extension. Install the full toolkit or this standalone child package, not both.
+
+Inside a Herdr workspace, the package registers `herdr_subagents` and `/herdr-subagents`. Outside Herdr (or without a workspace ID), the extension registers neither, so the tool is absent from the model context. Start Pi inside Herdr or reload the extension there to enable them.
+
+The design replaces hidden print-mode subprocesses with ordinary interactive Pi Agents managed through Herdr, so delegated work stays visible, inspectable, resumable, and durably recorded.
+
+## Usage
+
+Discover the effective personas first:
+
+```text
+herdr_subagents({ action: "list" })
+```
+
+Then run one self-contained task:
+
+```text
+herdr_subagents({
+  agent: "worker",
+  label: "auth-review",
+  prompt: "Inspect the authentication flow and summarize the risks"
+})
+```
+
+Or submit an ordered foreground batch:
+
+```text
+herdr_subagents({
+  label: "security-review",
+  concurrency: 3,
+  tasks: [
+    { name: "auth", agent: "reviewer", prompt: "Review authentication" },
+    { name: "sessions", agent: "explorer", prompt: "Trace session storage" }
+  ]
+})
+```
+
+Set `background: true` to return a stable run ID immediately while the queue continues. One run is dispatched at a time by an extension instance; later runs remain queued and start FIFO. Each background run sends one compact parent notification only when the whole run completes, partially fails, fails, or blocks. Individual successful tasks do not wake the parent model.
+
+A child missing required information reports `needs-input` with an exact question. The run becomes blocked, keeps its Herdr tab, pane, partial report, and Pi session, and returns control to the parent. Answer through the same tool to continue the original session:
+
+```text
+herdr_subagents({ action: "respond", runId: "<run-id>", answer: "Use the main branch." })
+```
+
+While a batch is active, its task rows stay below the editor. With an empty editor, press `↓` to enter the list, `↑`/`↓` to choose a task, `Enter` to focus its exact pane, and `Esc` to return. `/herdr-subagents focus <task-number>` remains available as a fallback.
+
+## History
+
+Run `/herdr-subagents history` or `herdr_subagents({ action: "history" })` to list compact project-local run and task reports after Herdr tabs close. Full results, described documents, artifacts, and persistent Pi sessions remain separate on disk and are not loaded into parent context.
+
+Continue a saved conversation in a new Herdr tab with `herdr_subagents({ action: "resume", runId: "<run-id>", task: 1, prompt: "Follow up..." })`. Remove only a selected archive with `herdr_subagents({ action: "cleanup", runId: "<run-id>" })`. History has no automatic count-based eviction. The extension adds the runtime path to local Git excludes when available (and otherwise uses `.pi/.gitignore`) without overwriting unrelated rules.
+
+Read-only tasks start FIFO up to the configured concurrency limit. A pane is created only when its task starts, belongs exclusively to that task, and is never reused. Completed panes remain inspectable while another task in the batch is unsettled. Results remain in input order, and one failed task does not cancel its siblings. Any batch containing a write-capable persona is forced to concurrency one.
+
+The widget shows one row per queued, running, blocked, failed, or completed task. Answering a blocked task refreshes rows and pane IDs as that task resumes and queued siblings start. Completed rows remain selectable until the whole batch settles. `/herdr-subagents active` shows the same compact state. Native labels stay short: `SA · <batch>` for the tab and `<order> · <task>` for each pane. When all tasks settle, the tab closes immediately if unfocused or after the user leaves it; a deferred close failure is persisted and shown as a warning.
+
+Foreground calls block until all children report completion, failure, or a request for input. Every child is started with Herdr's Agent lifecycle as a normal Pi TUI and prompted with wait semantics; no print-mode command or completion marker is injected into the pane.
+
+## Reports and records
+
+The child must finish through the package's structured `subagent_report` tool. The parent receives only:
+
+- completion or failure status
+- a concise summary
+- paths to useful documents
+- the task-record location
+
+The complete result is not copied into the parent model context. Each run is retained under:
+
+```text
+.pi/herdr-subagents/runs/<run>/tasks/<task>/
+```
+
+The task directory contains the full result, structured report, task metadata, system prompt, and persistent Pi session. Run-level metadata is stored in the parent run directory.
+
+## Personas
+
+The package includes `worker` (write access), `explorer` (read access), and `reviewer` (read access). Persona definitions are discovered in this order, with the first available higher-precedence definition replacing the lower one:
+
+1. `.pi/herdr-subagents/agents/*.md` in the project
+2. `~/.pi/agent/herdr-subagents/agents/*.md` globally
+3. this package's `agents/*.md`
+
+A custom persona without `access` is treated as write-capable. Definitions may set `access`, `model`, `thinking`, `tools`, and `skills` in frontmatter.
+
+The default `agents/worker.md` uses this format:
+
+```md
+---
+name: worker
+description: General-purpose worker for one focused task
+tools: read, bash, edit, write, grep, find, ls
+---
+
+You are a focused worker subagent.
+```
+
+Supported frontmatter:
+
+- `name` and `description` are required.
+- `model` optionally selects a child model. A call-level `model` overrides it; otherwise the current session model is inherited.
+- `tools` optionally restricts built-in tools. `subagent_report` is always added so the child can settle the task.
+- `access` is `read` or `write`; omitted custom values default to `write`.
+- `thinking` and `skills` provide persona defaults.
+
+Global settings live at `~/.pi/agent/herdr-subagents.json`; project overrides live at `.pi/herdr-subagents.json`. Both support `defaultConcurrency`, `maxConcurrency`, `stalledWarningSeconds`, `defaultModel`, and a `personas` object whose entries can override `model`, `thinking`, and `skills`.
+
+```json
+{
+  "defaultModel": "provider/model",
+  "maxConcurrency": 3,
+  "personas": {
+    "reviewer": { "thinking": "high", "skills": ["code-review"] }
+  }
+}
+```
+
+Project values override global values recursively. Model resolution is: task override, project persona setting, global persona setting, persona frontmatter, global/project default model, then parent model. Run `/herdr-subagents agents`, `/herdr-subagents models`, or `/herdr-subagents settings` to inspect effective values and their sources.
+
+## Recovery and failures
+
+Queued background submissions are persisted before dispatch. Closing the parent Pi session cancels queued, running, and blocked work, records `cancelled`, and closes the owned run tab. On the next Pi start, stale active records and queued submissions from a prior parent session are reconciled to a terminal state, including when Pi reused the same process, and leaked tabs are cleaned up when possible. Missing, truncated, or structurally invalid child reports become explicit failures or cancellation diagnostics; recovery errors are reported without leaving new submissions paused.
+
+Tab, pane, and child startup commands are not automatically retried: an error may arrive after Herdr already created the resource. A failure after prompt submission is preserved and never automatically rerun. Historical follow-ups exclude concurrent resumes of the same run with an atomic `.resume.lock` directory; if Pi crashes without releasing it, confirm no Agent is still using that run before removing the lock manually. `stalledWarningSeconds` emits a warning without killing long-running work. Run/task/report snapshots use atomic replacement so interruption cannot expose half-written JSON.
+
+The child does not inherit parent extensions, parent conversation, or unconfigured skills, but normal project context files still apply. It uses the same Pi installation, provider configuration, model catalog, and credentials as the parent.
+
+## Development and tests
+
+See [TESTING.md](TESTING.md) for deterministic tests, extension loading, packaging, and real Herdr smoke requirements.

package/packages/herdr-subagents/TESTING.md

@@ -0,0 +1,24 @@
+# Herdr Subagents test strategy
+
+## Flow
+
+1. `npm --prefix packages/herdr-subagents test` runs deterministic scheduler, recovery, and persona tests.
+2. `pi -ne -ns --no-session -e ./packages/herdr-subagents/extensions/herdr-subagents.ts` verifies extension loading.
+3. `npm pack ./packages/herdr-subagents --dry-run` verifies package contents.
+4. Verify the README example and the production-runner media `docs/screenshot.png` and `docs/demo.gif` are present in the tarball.
+
+## Cases
+
+- Resolve package, global, and project personas and validate frontmatter/configuration.
+- Run foreground tasks and FIFO bounded-concurrency batches through an injectable Herdr boundary.
+- Verify all paths use interactive Agent start/prompt without print mode, shell injection, markers, or pane reuse.
+- Force write-capable batches to serial execution while allowing bounded read-only parallelism.
+- Preserve compact reports, full results, Pi sessions, blocked questions, and historical follow-ups.
+- Recover queued/running work after interruption without retrying post-prompt side effects, including truncated reports and recovery errors.
+- Verify the flat public contract and injectable extension wiring, including conditional registration only inside Herdr, Fleet rendering, editor focus ownership, terminal-input passthrough, exact-pane navigation, and stable display while another background run queues.
+- Verify blocked-response live Fleet updates, authoritative stale-field replacement, parent-shutdown cancellation, cleanup notifications, atomic state replacement, non-retried uncertain startup operations, and stalled warnings.
+- Verify resumed batches retain newly allocated pane IDs and historical follow-ups exclude simultaneous session writers.
+
+## Latest baseline
+
+All 133 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, and persona cases must pass. Release validation also requires extension loading and a real Herdr read-only batch smoke with distinct task panes and final tab cleanup. The latest smoke completed two concurrent tasks, retained its focused run tab through settlement, and closed it automatically after focus moved away.

package/packages/herdr-subagents/agents/explorer.md

@@ -0,0 +1,8 @@
+---
+name: explorer
+description: Read-only explorer for fast codebase investigation
+access: read
+tools: read, bash, grep, find, ls
+---
+
+Investigate the assigned question without modifying files. Report concrete evidence and useful paths.

package/packages/herdr-subagents/agents/reviewer.md

@@ -0,0 +1,8 @@
+---
+name: reviewer
+description: Read-only reviewer for correctness and maintainability risks
+access: read
+tools: read, bash, grep, find, ls
+---
+
+Review the assigned work without modifying files. Report actionable findings with concrete evidence.

package/packages/{tiny-subagent → herdr-subagents}/agents/worker.md

@@ -1,6 +1,7 @@
 ---
 name: worker
 description: General-purpose worker for one focused task
+access: write
 tools: read, bash, edit, write, grep, find, ls
 ---
 

package/packages/herdr-subagents/extensions/herdr-subagents.ts

@@ -0,0 +1,258 @@
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import type { AgentToolResult, ExtensionAPI, ExtensionCommandContext, Theme, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Container, Editor, Spacer, Text } from "@earendil-works/pi-tui";
+import { loadSubagentConfiguration } from "../src/config.ts";
+import { CliHerdrAutomation, type HerdrAutomation } from "../src/herdr.ts";
+import { activeRunText } from "../src/monitor.ts";
+import { RunDispatcher } from "../src/dispatcher.ts";
+import { historyText, listSubagentHistory } from "../src/history.ts";
+import { cancelQueuedRuns, loadQueuedRuns, persistQueuedRun, removeQueuedRun } from "../src/queued-runs.ts";
+import { cancelActiveSubagentRuns, reconcileSubagentRuns } from "../src/reconcile.ts";
+import { executeHerdrSubagents, type HerdrSubagentsBatchDetails, type HerdrSubagentsDetails, type HerdrSubagentsToolParams } from "../src/tool.ts";
+import { HerdrSubagentsParams } from "../src/parameters.ts";
+import { HERDR_ACTIONS } from "../src/validation.ts";
+import { FleetController } from "../src/fleet-controller.ts";
+import { isSettledRunStatus } from "../src/records.ts";
+
+const packageAgentsDir = fileURLToPath(new URL("../agents/", import.meta.url));
+
+function statusVisual(status: string): { color: "success" | "warning" | "error" | "accent"; glyph: string } {
+	if (status === "completed") return { color: "success", glyph: "✓" };
+	if (status === "blocked") return { color: "warning", glyph: "?" };
+	if (status === "cancelled" || status === "partial") return { color: "warning", glyph: "−" };
+	if (status === "starting" || status === "queued" || status === "running") return { color: "accent", glyph: "·" };
+	return { color: "error", glyph: "✗" };
+}
+
+function renderToolCall(args: HerdrSubagentsToolParams, theme: Theme): Text {
+	if (args.action) {
+		const action = HERDR_ACTIONS[args.action];
+		const runId = action.includeRunId ? ` ${theme.fg("muted", String(args.runId ?? ""))}` : "";
+		return new Text(`${theme.fg("toolTitle", theme.bold(`herdr_subagents ${args.action}`))}${runId}`, 0, 0);
+	}
+	if (args.tasks) return new Text(`${theme.fg("toolTitle", theme.bold("herdr_subagents"))} ${theme.fg("accent", `${args.tasks.length} tasks`)}${theme.fg("muted", ` · concurrency ${args.concurrency ?? "default"}`)}`, 0, 0);
+	const agent = args.agent || "worker";
+	const label = args.label ? ` · ${String(args.label)}` : "";
+	const prompt = args.prompt ? String(args.prompt).replace(/\s+/g, " ") : "...";
+	const preview = prompt.length > 80 ? `${prompt.slice(0, 80)}...` : prompt;
+	return new Text(`${theme.fg("toolTitle", theme.bold("herdr_subagents"))} ${theme.fg("accent", agent)}${theme.fg("muted", label)}\n  ${theme.fg("dim", preview)}`, 0, 0);
+}
+
+function renderToolResult(result: AgentToolResult<unknown>, _options: ToolRenderResultOptions, theme: Theme): Container | Text {
+	const batch = result.details as HerdrSubagentsBatchDetails | undefined;
+	if (batch?.tasks && "effectiveConcurrency" in batch) {
+		const container = new Container();
+		const visual = statusVisual(batch.status);
+		container.addChild(new Text(`${theme.fg("toolTitle", theme.bold(batch.label))} ${theme.fg(visual.color, batch.status)} · ${batch.tasks.length} settled · concurrency ${batch.effectiveConcurrency}`, 0, 0));
+		for (const task of batch.tasks) container.addChild(new Text(`${statusVisual(task.status).glyph} ${task.name}: ${task.summary}`, 0, 0));
+		return container;
+	}
+	const details = result.details as HerdrSubagentsDetails | undefined;
+	if (!details?.agent) {
+		const content = result.content[0];
+		return new Text(content?.type === "text" ? content.text : "(no output)", 0, 0);
+	}
+	const container = new Container();
+	container.addChild(new Text(`${theme.fg("toolTitle", theme.bold(details.agent))} ${theme.fg(statusVisual(details.status).color, details.status)}`, 0, 0));
+	container.addChild(new Text(details.summary, 0, 0));
+	if (details.documents.length > 0) {
+		container.addChild(new Spacer(1));
+		for (const document of details.documents) container.addChild(new Text(theme.fg("muted", `${document.description}: ${document.path}`), 0, 0));
+	}
+	if (details.recordDirectory) container.addChild(new Text(theme.fg("dim", `Record: ${details.recordDirectory}`), 0, 0));
+	if (details.errorMessage) container.addChild(new Text(theme.fg("error", `Error: ${details.errorMessage}`), 0, 0));
+	return container;
+}
+
+async function handleHerdrCommand(args: string, ctx: ExtensionCommandContext, fleet: FleetController): Promise<void> {
+	const section = args.trim() || "active";
+	if (section === "active") {
+		ctx.ui.notify(fleet.active ? activeRunText(fleet.active) : "No active Subagent run.", "info");
+		return;
+	}
+	if (section === "history") {
+		ctx.ui.notify(historyText(await listSubagentHistory(ctx.cwd)), "info");
+		return;
+	}
+	if (section.startsWith("focus ")) {
+		if (!await fleet.focus(Number(section.slice(6).trim()))) ctx.ui.notify("That task is not active in a Herdr pane.", "warning");
+		return;
+	}
+	if (section === "models") {
+		await ctx.modelRegistry.refresh();
+		const lines = ctx.modelRegistry.getAvailable().map((model) => `${model.provider}/${model.id}`).sort();
+		ctx.ui.notify(lines.length ? `Available Pi models:\n${lines.join("\n")}` : "No authenticated Pi models are available.", "info");
+		return;
+	}
+	const configuration = loadSubagentConfiguration(ctx.cwd, packageAgentsDir, ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined);
+	if (section === "agents") {
+		ctx.ui.notify(configuration.personas.map((persona) => `${persona.name}: ${persona.source}, ${persona.access}, model=${persona.model ?? "unresolved"} (${persona.modelSource}), thinking=${persona.thinking ?? "default"}, tools=${persona.tools?.join(",") ?? "default"}, skills=${persona.skills.join(",") || "none"}`).join("\n"), "info");
+		return;
+	}
+	if (section === "settings") {
+		const settings = configuration.settings;
+		const values: Record<string, string | number | undefined> = { defaultConcurrency: settings.defaultConcurrency, maxConcurrency: settings.maxConcurrency, stalledWarningSeconds: settings.stalledWarningSeconds, defaultModel: settings.defaultModel };
+		const lines = Object.entries(values).map(([key, value]) => `${key}=${String(value ?? "unset")} (${configuration.settingSources[key] ?? "built-in"})`);
+		if (configuration.diagnostics.length) lines.push("Diagnostics:", ...configuration.diagnostics);
+		ctx.ui.notify(lines.join("\n"), "info");
+		return;
+	}
+	ctx.ui.notify("Usage: /herdr-subagents active|history|focus <task-number>|agents|models|settings", "warning");
+}
+
+export interface HerdrSubagentsExtensionDependencies {
+	herdr?: HerdrAutomation;
+	execute?: typeof executeHerdrSubagents;
+	isEditor?: (value: unknown) => boolean;
+	createFleetWidget?: (lines: string[]) => Container;
+}
+
+async function recoverParentSession(cwd: string, herdr: HerdrAutomation, owner: { sessionId?: string; processId: number }, notify: (message: string) => void): Promise<void> {
+	try {
+		const queued = await loadQueuedRuns(cwd, notify);
+		await cancelQueuedRuns(cwd, queued.map((run) => run.runId), { reason: "Owning parent Pi session is no longer active.", owner, onlyOrphaned: true, onError: notify });
+	}
+	catch (error) { notify(`Subagent queue recovery failed: ${error instanceof Error ? error.message : String(error)}`); }
+	try {
+		const reconciliation = await reconcileSubagentRuns(cwd, herdr, owner);
+		for (const message of reconciliation.cleanupErrors) notify(message);
+	}
+	catch (error) { notify(`Subagent recovery could not inspect active runs: ${error instanceof Error ? error.message : String(error)}`); }
+}
+
+async function shutdownParentSession(options: { cwd: string; herdr: HerdrAutomation; owner: { sessionId?: string; processId: number }; dispatcher: RunDispatcher; fleet: FleetController; sessionController: AbortController; runControllers: Map<string, AbortController>; inFlight: Set<Promise<unknown>>; notify: (message: string) => void }): Promise<void> {
+	options.dispatcher.pause();
+	options.sessionController.abort(new Error("Parent Pi session closed."));
+	const queuedRunIds = options.dispatcher.cancelQueued(new Error("Parent Pi session closed."));
+	await cancelQueuedRuns(options.cwd, queuedRunIds, { reason: "Parent Pi session closed.", owner: options.owner });
+	for (const controller of options.runControllers.values()) controller.abort(new Error("Parent Pi session closed."));
+	options.fleet.shutdown();
+	await Promise.allSettled([...options.inFlight]);
+	const cancellation = await cancelActiveSubagentRuns(options.cwd, options.herdr, { reason: "Parent Pi session closed.", owner: options.owner });
+	const retainedRunId = options.dispatcher.snapshot().activeRunId;
+	if (retainedRunId) options.dispatcher.release(retainedRunId);
+	for (const message of cancellation.cleanupErrors) options.notify(message);
+}
+
+export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSubagentsExtensionDependencies = {}) {
+	if (process.env.PI_HERDR_SUBAGENTS_CHILD === "1" || process.env.HERDR_ENV !== "1" || !process.env.HERDR_WORKSPACE_ID) return;
+	const herdr = dependencies.herdr ?? new CliHerdrAutomation();
+	const execute = dependencies.execute ?? executeHerdrSubagents;
+	const isEditorComponent = dependencies.isEditor ?? ((value: unknown) => value instanceof Editor);
+	const dispatcher = new RunDispatcher();
+	const fleet = new FleetController(herdr, isEditorComponent, dependencies.createFleetWidget);
+	const runControllers = new Map<string, AbortController>();
+	const inFlight = new Set<Promise<unknown>>();
+	let sessionController = new AbortController();
+	let ownerSessionId: string | undefined;
+	let sessionGeneration = 0;
+	const notifyRun = (runId: string, result: { details: unknown; content?: Array<{ type: string; text?: string }> }) => {
+		const details = result.details as Partial<HerdrSubagentsBatchDetails> & { errorMessage?: string };
+		if (!details.tasks || !details.documents || !details.status) {
+			const error = details.errorMessage ?? result.content?.find((item) => item.type === "text")?.text ?? "Unknown Subagent failure.";
+			pi.sendMessage({ customType: "herdr-subagents-run", content: `Subagent run ${runId} failed: ${error}`, display: true, details: { runId, status: "failed" } }, { triggerTurn: true, deliverAs: "followUp" });
+			return;
+		}
+		const lines = [`Subagent run ${runId} ${details.status}: ${details.summary}`, ...details.tasks.map((task) => `- ${task.name}: ${task.summary}`)];
+		if (details.documents.length) lines.push("Documents:", ...details.documents.map((document) => `- ${document.description}: ${document.path}`));
+		pi.sendMessage({ customType: "herdr-subagents-run", content: lines.join("\n"), display: true, details: { runId, status: details.status } }, { triggerTurn: true, deliverAs: "followUp" });
+	};
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		sessionGeneration += 1;
+		await shutdownParentSession({ cwd: ctx.cwd, herdr, owner: { sessionId: ownerSessionId, processId: process.pid }, dispatcher, fleet, sessionController, runControllers, inFlight, notify: (message) => ctx.ui.notify(message, "error") });
+	});
+	pi.on("session_start", async (_event, ctx) => {
+		sessionGeneration += 1;
+		sessionController.abort(new Error("Parent Pi session changed."));
+		sessionController = new AbortController();
+		ownerSessionId = `${ctx.sessionManager.getSessionId()}:${randomUUID()}`;
+		fleet.bind(ctx.ui, ctx.mode === "tui");
+		dispatcher.pause();
+		try { await recoverParentSession(ctx.cwd, herdr, { sessionId: ownerSessionId, processId: process.pid }, (message) => ctx.ui.notify(message, "error")); }
+		finally { dispatcher.resume(); }
+	});
+
+	pi.registerTool({
+		name: "herdr_subagents",
+		label: "Herdr Subagents",
+		description: "Run one focused task or an ordered bounded-concurrency batch in visible interactive Herdr Pi Agents. Foreground calls block while workers run concurrently; background batches return a run ID immediately and publish completion later. Complete results and Pi sessions stay in project-local records.",
+		promptSnippet: "Run focused work in visible Herdr subagents",
+		promptGuidelines: ["Call action=list once before the first execution. Submit one prompt or an ordered tasks list; use concurrency only for independent read-only tasks. Foreground calls block until the run settles; background calls return a run ID immediately."],
+		parameters: HerdrSubagentsParams,
+
+		async execute(_toolCallId, params: HerdrSubagentsToolParams, signal, onUpdate, ctx) {
+			const generation = sessionGeneration;
+			const runId = params.tasks ? randomUUID() : undefined;
+			const executionId = runId ?? params.runId ?? randomUUID();
+			const controller = new AbortController();
+			runControllers.set(executionId, controller);
+			const runSignal = AbortSignal.any([controller.signal, sessionController.signal, ...(!params.background && signal ? [signal] : [])]);
+			const executeRun = async () => {
+				const result = await execute(params, runSignal, (update) => {
+				const details = update.details as HerdrSubagentsBatchDetails | undefined;
+				if (details?.activity) fleet.sync(details);
+				const updateText = update.content.find((item) => item.type === "text")?.text;
+				const updateDetails = update.details as { warning?: string };
+				if (updateDetails.warning || updateText?.includes("cleanup failed") || (params.background && updateText?.includes("appears stalled"))) ctx.ui.notify(updateDetails.warning ?? updateText ?? "Subagent warning", "warning");
+				if (!params.background) onUpdate?.(update);
+				}, ctx, { agentsDirectory: packageAgentsDir, owner: { sessionId: ownerSessionId, processId: process.pid }, runId });
+				fleet.sync(result.details);
+				return result;
+			};
+			if (!params.tasks) {
+				const promise = executeRun();
+				inFlight.add(promise);
+				const result = await promise.finally(() => { inFlight.delete(promise); runControllers.delete(executionId); });
+				if (params.action === "respond") {
+					const details = result.details as { runId?: string; status?: string };
+					if (details.status === "blocked") fleet.sync(result.details);
+					else if (isSettledRunStatus(details.status)) {
+						fleet.clearRun(params.runId);
+						if (params.runId) dispatcher.release(params.runId);
+					}
+				}
+				return result;
+			}
+			if (!runId) throw new Error("Batch run ID was not allocated.");
+			if (params.background) await persistQueuedRun(ctx.cwd, runId, params, { sessionId: ownerSessionId, processId: process.pid });
+			const promise = dispatcher.submit(runId, async () => {
+				const result = await executeRun().finally(async () => { if (params.background) await removeQueuedRun(ctx.cwd, runId); });
+					const details = result.details as HerdrSubagentsBatchDetails;
+					fleet.setActive(details.status === "blocked" ? details : undefined);
+					if (fleet.active) {
+						dispatcher.retain(runId);
+				}
+				return result;
+			});
+			inFlight.add(promise);
+			void promise.finally(() => { inFlight.delete(promise); runControllers.delete(executionId); }).catch(() => undefined);
+			if (params.background) {
+				void promise.then((result) => {
+					if (generation !== sessionGeneration) return;
+					notifyRun(runId, result);
+					if (!fleet.active && !dispatcher.snapshot().activeRunId && dispatcher.snapshot().queuedRunIds.length === 0) fleet.render();
+				}).catch((error) => {
+					if (generation !== sessionGeneration) return;
+					pi.sendMessage({ customType: "herdr-subagents-run", content: `Subagent run ${runId} failed: ${error instanceof Error ? error.message : String(error)}`, display: true, details: { runId, status: "failed" } }, { triggerTurn: true, deliverAs: "followUp" });
+				});
+				return { content: [{ type: "text" as const, text: `Subagent run queued: ${runId}` }], details: { runId, status: "queued", background: true } };
+			}
+			const result = await promise;
+			if (!fleet.active && !dispatcher.snapshot().activeRunId && dispatcher.snapshot().queuedRunIds.length === 0) fleet.resetSelection();
+			return result;
+		},
+
+		renderCall: renderToolCall,
+		renderResult: renderToolResult,
+	});
+
+	pi.registerCommand("herdr-subagents", {
+		description: "Inspect effective subagent agents, models, and settings",
+		getArgumentCompletions: (prefix) => ["active", "history", "agents", "models", "settings", "focus "].filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value })),
+		handler: (args, ctx) => handleHerdrCommand(args, ctx, fleet),
+	});
+}
+
+export default registerHerdrSubagents;