pi-herdr-agents 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -7,7 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
-## [v1.2.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.1.0...v1.2.0)
+## [v1.2.2](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.2.1...v1.2.2)
+
+### Commits
+
+- fix: hide completion tool from auto-exit children [`e4cad6b`](https://github.com/giuseppecrj/pi-herdr-agents/commit/e4cad6bdbe5d1952f5bb838640493c20ab332dbd)
+
+## [v1.2.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.2.0...v1.2.1) - 2026-08-13
+
+### Commits
+
+- docs: polish package readme and artwork [`908dd76`](https://github.com/giuseppecrj/pi-herdr-agents/commit/908dd76875c91871b8d91113e6d1633d5112d5b3)
+- chore: release v1.2.1 [`df87f12`](https://github.com/giuseppecrj/pi-herdr-agents/commit/df87f126ec5cad4735c441752471aa8bd724f2e9)
+
+## [v1.2.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.1.0...v1.2.0) - 2026-08-13
 
 ### Commits
 
@@ -17,6 +30,7 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - feat: simplify worktree command [`4dc88e0`](https://github.com/giuseppecrj/pi-herdr-agents/commit/4dc88e0a962625eec10240d57cf67548510e6a9a)
 - docs: add worktree handoff research [`00f95c6`](https://github.com/giuseppecrj/pi-herdr-agents/commit/00f95c65e0f050492259a0de625c35e4eef9aae8)
 - test: cover failed worktree handoff recovery [`dd27c0a`](https://github.com/giuseppecrj/pi-herdr-agents/commit/dd27c0a8f17e51cff635e5b77e18ff7f05896650)
+- chore: release v1.2.0 [`dba1ab5`](https://github.com/giuseppecrj/pi-herdr-agents/commit/dba1ab5564b9ef64ae1f0f57b6df4bb40502970c)
 - ci: upgrade release actions to node24 [`ec9158d`](https://github.com/giuseppecrj/pi-herdr-agents/commit/ec9158d838cb0fae914c94fc448a6677b4ab1696)
 
 ## [v1.1.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.0.0...v1.1.0) - 2026-08-11

package/README.md

@@ -1,84 +1,99 @@
 # Pi Herdr Agents
 
-Async subagents for [Pi](https://github.com/earendil-works/pi) running exclusively in [Herdr](https://herdr.dev). Spawn, orchestrate, and manage sub-agent sessions in dedicated herdr tabs or panes. **Fully non-blocking** — the main agent keeps working while subagents run in the background.
+![Pi Herdr Agents: parallel Pi agents running asynchronously in dedicated Herdr panes and managed worktrees.](https://raw.githubusercontent.com/giuseppecrj/pi-herdr-agents/main/docs/assets/pi-herdr-agents-gallery.png)
 
-Package: `pi-herdr-agents` · Repository: [`giuseppecrj/pi-herdr-agents`](https://github.com/giuseppecrj/pi-herdr-agents)
+Asynchronous subagents and approved review workflows for [Pi](https://github.com/earendil-works/pi), running exclusively in [Herdr](https://herdr.dev).
 
-## How It Works
+Delegate investigation, implementation, and review without blocking the parent session. Each child runs as a real Pi process in its own Herdr surface; results return automatically when the child finishes.
 
-Call `subagent()` and it **returns immediately**. The sub-agent runs in its own terminal pane. A live widget above the input shows all tracked agents with their projected state — for example `starting`, `active`, `waiting`, `blocked`, `interrupted`, `stalled`, `running`, or `finalizing`. The header summarizes **active** (processing) vs **open** (not processing). When every tracked subagent is open, the border switches to amber. When a sub-agent finishes, its result is **steered back** into the main session as an async notification — triggering a new turn so the agent can process it.
+## Features
 
-```
-╭─ Subagents ──────────────────── 1 active · 1 open ─╮
-│ 00:23  Scout: Auth (scout)        active · bash 7m │
-│ 00:45  Scout: DB (scout)                waiting 2m │
-╰────────────────────────────────────────────────────╯
-```
+- **Non-blocking delegation** — `subagent` acknowledges launch immediately while the parent keeps working.
+- **Parallel execution** — run independent scouts, workers, and reviewers at the same time.
+- **Live supervision** — track process and turn state in Pi's subagent widget; interrupt one child turn without destroying its session.
+- **Managed worktrees** — isolate writing agents in retained Herdr workspaces with explicit Git ownership and recovery details.
+- **Conversation handoff** — continue the active Pi conversation in a new worktree with `/worktree` while preserving the parent session.
+- **Approved review workflows** — prepare and run bounded, read-only multi-agent reviews with fresh evidence and one synthesized result.
+- **Reusable roles** — use bundled agents, project or global definitions, and installable role packs.
 
-For parallel execution, just call `subagent` multiple times — they all run concurrently:
+## Requirements
 
-```typescript
-subagent({ name: "Scout: Auth", agent: "scout", task: "Analyze auth module" });
-subagent({ name: "Scout: DB", agent: "scout", task: "Map database schema" });
-// Both return immediately, results steer back independently
-```
+- [Pi](https://github.com/earendil-works/pi) with package support
+- [Herdr](https://herdr.dev) and its CLI
+- `HERDR_ENV=1` — start Pi from inside Herdr
 
-Read-only agents can safely share the parent checkout. For parallel agents that write files, give each task a unique Herdr-managed worktree; see [Worktree subagents](docs/worktree-subagents.md).
+Other terminal multiplexers are not supported. Worktrees isolate Git checkouts, not processes or permissions; child agents and installed Pi packages run with your user account's access.
 
-## Development
+## Install
 
-Run unit tests and lint locally:
+Install from npm:
 
 ```bash
-npm test
-npm run lint
+pi install npm:pi-herdr-agents
 ```
 
-Run the required end-to-end suite from inside herdr:
+Install project-locally or try it for one run:
 
 ```bash
-npm run test:integration
+pi install -l npm:pi-herdr-agents
+pi -e npm:pi-herdr-agents
 ```
 
-It launches real Pi sessions, Herdr panes, worktrees, and the extension from the working tree, but routes model requests to a local deterministic fixture. It needs no provider credentials or network access.
-
-An optional live-provider smoke test remains available for Pi/provider compatibility; it is not a merge gate:
+Then start Pi inside Herdr:
 
 ```bash
-PI_TEST_MODEL="openai-codex/gpt-5.6-luna" PI_TEST_TIMEOUT=180000 \
-  npm run test:integration:live
+herdr
+pi
 ```
 
-`PI_TEST_MODEL` selects the parent and child runtime only in live mode.
+Restart or `/reload` Pi after installation. Review package source before installing any Pi package.
 
-## Install
+## Quick start
 
-Install the package globally from npm:
+Ask Pi to delegate naturally:
 
-```bash
-pi install npm:pi-herdr-agents
+```text
+Use two scouts in parallel to map the authentication flow, then summarize their findings.
 ```
 
-Use `pi install -l npm:pi-herdr-agents` for a project-local installation, or try it for one run without changing settings:
+Or launch a named role directly:
 
-```bash
-pi -e npm:pi-herdr-agents
+```text
+/subagent scout Analyze the authentication module and report relevant files and risks
 ```
 
-Pi packages execute with your user account's full system access. Review the package source before installation.
+For an isolated writing task:
 
-The documented `npm version` release step updates [CHANGELOG.md](CHANGELOG.md). Pushing that version change to `main` publishes to npm and creates the matching Git tag and GitHub Release. For bootstrap authentication, versioning, verification, and troubleshooting, see [RELEASING.md](RELEASING.md).
+```text
+/worktree auth-fix Implement the approved authentication fix and run the focused tests
+```
 
-Start herdr, then run pi inside it:
+Pi can also call the tool directly:
 
-```bash
-herdr
-pi
+```typescript
+subagent({ name: "Auth scout", agent: "scout", task: "Map the authentication flow" });
+subagent({ name: "DB scout", agent: "scout", task: "Map the session schema" });
+// Both return immediately; each result comes back independently.
 ```
 
-herdr is the only supported terminal environment. The extension requires `HERDR_ENV=1` and the `herdr` CLI to be available.
+Use ordinary panes for read-only agents. Give each independent writing agent a unique managed worktree; see [Worktree subagents](docs/worktree-subagents.md).
+
+## How it works
 
-### Troubleshooting completion delivery
+![Pi Herdr Agents lifecycle: spawn a child, run it in Herdr, supervise live state, and deliver one bounded result to the parent.](https://raw.githubusercontent.com/giuseppecrj/pi-herdr-agents/main/docs/assets/async-subagent-lifecycle.png)
+
+A `subagent` call creates a dedicated Herdr pane or worktree, launches a child Pi session, and returns `started`. The parent watcher combines Herdr process state with child activity details and projects the result into a live widget:
+
+```text
+╭─ Subagents ──────────────────── 1 active · 1 open ─╮
+│ 00:23  Scout: Auth (scout)        active · read 7m │
+│ 00:45  Reviewer (reviewer)              waiting 2m │
+╰────────────────────────────────────────────────────╯
+```
+
+When the child completes, the parent receives one bounded `subagent_result` message and starts a new turn with that result in context. Callers never need to poll, tail session files, or wait in a shell loop.
+
+## Troubleshooting completion delivery
 
 If a child finishes but the parent returns an empty or unrelated response, first verify that the result reached the parent session:
 
@@ -865,17 +880,31 @@ Every sub-agent session displays a compact tools widget showing available and de
 
 ---
 
-## Requirements
+## Development
 
-- [Pi](https://github.com/earendil-works/pi) — the coding agent
-- [herdr](https://herdr.dev) — the required terminal workspace
+Run local checks:
 
 ```bash
-herdr
-pi
+npm ci
+npm test
+npm run lint
+npm pack --dry-run
+```
+
+Run the required end-to-end suite from inside Herdr:
+
+```bash
+npm run test:integration
+```
+
+The deterministic suite launches real Pi sessions, Herdr panes, and worktrees without provider credentials. The optional live-provider smoke test is not a merge gate:
+
+```bash
+PI_TEST_MODEL="openai-codex/gpt-5.6-luna" PI_TEST_TIMEOUT=180000 \
+  npm run test:integration:live
 ```
 
-Other multiplexers and terminal backends are not supported. Worktrees provide Git checkout isolation only, not process or security isolation; child agents and installed Pi packages run with your user's filesystem and command permissions.
+See [RELEASING.md](RELEASING.md) for versioning, trusted publication, and release verification.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-agents",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Asynchronous Pi subagents and approved review workflows in Herdr, with optional isolated Git worktrees",
   "keywords": [
     "pi-package",
@@ -53,7 +53,8 @@
     ],
     "skills": [
       "./skills"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/giuseppecrj/pi-herdr-agents/main/docs/assets/pi-herdr-agents-gallery.png"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "^0.84.0",

package/pi-extension/subagents/index.ts

@@ -117,6 +117,7 @@ import {
 	persistWorktreeResult,
 	runSubagentScript,
 	writeWorktreeManifest,
+	buildSubagentToolAllowlist,
 	type WorktreeHandoff,
 	type WorktreeLaunch,
 } from "./launch.ts";
@@ -1404,32 +1405,6 @@ function updateWidget() {
  * first positional message so that /skill: args land in messages[1..] and arrive
  * as standalone prompts in the child session.
  */
-const SUBAGENT_CONTROL_TOOLS = ["caller_ping", "subagent_done"] as const;
-
-/**
- * Build the child --tools allowlist.
- *
- * Pi 0.70+ applies --tools to built-in, extension, and custom tools. If a
- * subagent definition restricts tools to e.g. "read,bash,write", the child
- * control tools from subagent-done.ts would otherwise be hidden, leaving a
- * manually resumed or user-touched subagent unable to call subagent_done.
- */
-function buildSubagentToolAllowlist(effectiveTools?: string): string | null {
-	const requested = (effectiveTools ?? "")
-		.split(",")
-		.map((tool) => tool.trim())
-		.filter(Boolean);
-
-	if (requested.length === 0) return null;
-
-	const allow = new Set(requested);
-	for (const tool of SUBAGENT_CONTROL_TOOLS) {
-		allow.add(tool);
-	}
-
-	return [...allow].join(",");
-}
-
 function buildPiPromptArgs(params: {
 	effectiveSkills?: string;
 	taskDelivery: "direct" | "artifact";

package/pi-extension/subagents/launch.ts

@@ -28,7 +28,6 @@ import {
 	type HerdrWorktreeSurface,
 } from "./terminal.ts";
 
-const SUBAGENT_CONTROL_TOOLS = ["caller_ping", "subagent_done"] as const;
 const SUBAGENTS_DIR = dirname(fileURLToPath(import.meta.url));
 
 type SubagentSessionMode = "standalone" | "lineage-only" | "fork";
@@ -550,7 +549,10 @@ function buildPiCommand(
 			shellQuote(artifacts.systemPromptFile),
 		);
 	}
-	const toolAllowlist = buildToolAllowlist(request.behavior.tools);
+	const toolAllowlist = buildSubagentToolAllowlist(
+		request.behavior.tools,
+		request.behavior.autoExit,
+	);
 	if (toolAllowlist) parts.push("--tools", shellQuote(toolAllowlist));
 	if (!request.handoff) {
 		for (const prompt of buildPromptArgs(
@@ -579,7 +581,9 @@ function buildPiCommand(
 		env.push(`PI_SUBAGENT_NAME=${shellQuote(request.name)}`);
 		if (request.agent)
 			env.push(`PI_SUBAGENT_AGENT=${shellQuote(request.agent)}`);
-		if (request.behavior.autoExit) env.push("PI_SUBAGENT_AUTO_EXIT=1");
+		env.push(
+			`PI_SUBAGENT_AUTO_EXIT=${request.behavior.autoExit ? "1" : "0"}`,
+		);
 		env.push(`PI_SUBAGENT_SESSION=${shellQuote(artifacts.sessionFile)}`);
 		env.push(`PI_SUBAGENT_ID=${shellQuote(resolved.id)}`);
 		env.push(`PI_SUBAGENT_ACTIVITY_FILE=${shellQuote(artifacts.activityFile)}`);
@@ -678,7 +682,7 @@ async function launchResumedPiSubagent(
 		`PI_SUBAGENT_SESSION=${shellQuote(request.sessionFile)}`,
 		`PI_SUBAGENT_ID=${shellQuote(id)}`,
 		`PI_SUBAGENT_ACTIVITY_FILE=${shellQuote(activityFile)}`,
-		...(autoExit ? ["PI_SUBAGENT_AUTO_EXIT=1"] : []),
+		`PI_SUBAGENT_AUTO_EXIT=${autoExit ? "1" : "0"}`,
 	];
 	const command = [
 		...env,
@@ -722,14 +726,19 @@ async function launchResumedPiSubagent(
 	};
 }
 
-function buildToolAllowlist(tools?: string): string | null {
+export function buildSubagentToolAllowlist(
+	tools?: string,
+	autoExit = false,
+): string | null {
 	const requested = (tools ?? "")
 		.split(",")
 		.map((tool) => tool.trim())
 		.filter(Boolean);
 	if (requested.length === 0) return null;
 	const allow = new Set(requested);
-	for (const tool of SUBAGENT_CONTROL_TOOLS) allow.add(tool);
+	allow.delete("subagent_done");
+	allow.add("caller_ping");
+	if (!autoExit) allow.add("subagent_done");
 	return [...allow].join(",");
 }
 

package/pi-extension/subagents/subagent-done.ts

@@ -1,7 +1,7 @@
 /**
  * Extension loaded into sub-agents.
  * - Shows agent identity + available tools as a styled widget above the editor (toggle with Ctrl+J)
- * - Provides a `subagent_done` tool for autonomous agents to self-terminate
+ * - Provides a `subagent_done` tool for interactive agents to self-terminate
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
@@ -302,6 +302,8 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
+  if (autoExit) return;
+
   pi.registerTool({
     name: "subagent_done",
     label: "Subagent Done",