@maxiaochao/pi-toolkit 0.10.4 → 0.10.6

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2026-10-09 - v0.10.6
+
+- bundle herdr-subagents v0.4.3: add per-run status, neutral analyst persona, and tool-agnostic Agent Team protocol
+- Add per-run Herdr Subagents status queries so background review gates can inspect one run without polling the full history archive.
+- Make Agent Team a tool-agnostic concurrent review protocol, decouple models from rotating methodological roles, and add a neutral read-only analyst persona.
+- Remove Todo from the default toolkit bundle and loadout; users who want its progress UI can install `@maxiaochao/pi-todo` explicitly.
+
+## 2026-10-08 - v0.10.5
+
+- bundle herdr-subagents v0.4.2: add Alt+P and /parent controls to return from child Agents
 ## 2026-10-08 - v0.10.4
 
 - bundle herdr-subagents v0.4.1: targeted cancellation, live token polling, and idempotent tab cleanup

package/README.md

@@ -16,13 +16,21 @@ Update it:
 pi update npm:@maxiaochao/pi-toolkit
 ```
 
-The root package embeds the child-package source snapshots listed below. Install the complete toolkit or selected standalone children, not both.
+The root package embeds its enabled child-package source snapshots. Todo is intentionally excluded from the default toolkit and remains available as an opt-in standalone package.
+
+Existing toolkit users can pick up the change with:
+
+```bash
+pi update npm:@maxiaochao/pi-toolkit
+```
+
+Restart Pi after updating. The `todo` tool and widget will no longer load. `pi update --extensions` has the same effect when updating all installed packages. Explicitly versioned sources remain pinned and must be changed or reinstalled without the old version suffix.
 
 ## Child packages
 
 | Package | Capability | Install | Update |
 |---|---|---|---|
-| [pi-todo](packages/todo/README.md) | Branch-local execution plans, guarded advancement, `/todos` history | `pi install npm:@maxiaochao/pi-todo` | `pi update npm:@maxiaochao/pi-todo` |
+| [pi-todo](packages/todo/README.md) | Optional branch-local execution plan UI; not bundled with pi-toolkit | `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-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` |
@@ -30,7 +38,21 @@ The root package embeds the child-package source snapshots listed below. Install
 
 Each child README owns its feature description, motivation or upstream alignment, examples, screenshots/demos, configuration, and test documentation.
 
-Multiple standalone children may be installed together. Do not install a child alongside the complete toolkit because that exposes the same resource twice.
+Multiple standalone children may be installed together. `pi-todo` may also be installed alongside the complete toolkit because Todo is no longer bundled. Do not install another bundled child alongside the complete toolkit because that exposes the same resource twice.
+
+To keep Todo after updating the toolkit:
+
+```bash
+pi install npm:@maxiaochao/pi-todo
+```
+
+If Todo was already installed separately and should be removed completely:
+
+```bash
+pi remove npm:@maxiaochao/pi-todo
+```
+
+Use `--local` with install or remove when the package declaration belongs to a project's `.pi/settings.json` rather than personal settings.
 
 Root and child versions remain independent, but repository release tooling publishes a modified child and a new toolkit snapshot from the same commit. Run `pi update --extensions` to update all installed packages. Explicit version sources such as `npm:@maxiaochao/pi-toolkit@0.9.3` remain pinned.
 
@@ -64,7 +86,7 @@ bash scripts/install.sh
 | `html-artifact` | Build self-contained HTML explainers and diagrams |
 | `pdlog` | Decompress and inspect Pudu `.pdlog` files |
 | `herdr` | Control Herdr workspaces, tabs, panes, and agents |
-| `agent-team` | Run cross-vendor adversarial review through Herdr |
+| `agent-team` | Run tool-agnostic, cross-vendor adversarial review with independent concurrent agents |
 | `tapd` | Use the TAPD CLI for requirements, defects, tasks, and wikis |
 
 Package-specific skills, such as `pi-worktree`, are documented by their child package.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.10.4",
-  "description": "Personal pi coding agent toolkit: execution plans, /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
+  "version": "0.10.6",
+  "description": "Personal pi coding agent toolkit: /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [
     "packages/*"
@@ -12,7 +12,6 @@
   ],
   "files": [
     "extensions",
-    "packages/todo",
     "packages/cache-export",
     "packages/codex-edit",
     "packages/herdr-subagents",
@@ -30,7 +29,6 @@
   },
   "pi": {
     "extensions": [
-      "./packages/todo/extensions/todo.ts",
       "./packages/cache-export/extensions/cache-export.ts",
       "./extensions/btw/index.ts",
       "./packages/codex-edit/extensions/codex-edit.ts",
@@ -58,7 +56,7 @@
   },
   "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/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",
+    "load-test": "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

@@ -1,3 +1,14 @@
+## 2026-10-09 - v0.4.3
+
+- add per-run status, neutral analyst persona, and tool-agnostic Agent Team protocol
+- Add `herdr_subagents_control({ action: "status", runId })` for a compact snapshot of one queued, active, blocked, or settled run without loading the full history archive.
+- Add a neutral read-only `analyst` persona for tasks that assign models and methodological roles dynamically.
+
+## 2026-10-08 - v0.4.2
+
+- add Alt+P and /parent controls to return from child Agents
+- Add `/parent` and `Alt+P` inside child Agents to return focus to the exact parent Agent pane, with a visible child footer hint.
+
 ## 2026-10-08 - v0.4.1
 
 - targeted cancellation, live token polling, and idempotent tab cleanup

package/packages/herdr-subagents/README.md

@@ -66,6 +66,14 @@ herdr_subagents({
 
 `tasks` is always a non-empty array: one item is a single task and multiple items form a batch. Set `background: true` for either form 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.
 
+Background work normally relies on that terminal notification. When the user asks for progress or the parent must confirm a review gate before continuing, query only that run's compact snapshot:
+
+```text
+herdr_subagents_control({ action: "status", runId: "<run-id>" })
+```
+
+The snapshot reports the aggregate run state and every task's state, including a blocked question when present. It checks durable run state before queued state, never returns unrelated runs, and does not wait or trigger a parent turn. Do not poll full `history` for progress.
+
 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 control tool to continue the original session:
 
 ```text
@@ -76,11 +84,11 @@ Cancel one active or queued run with `herdr_subagents_control({ action: "cancel"
 
 While a batch is active, a compact Fleet monitor stays below the editor. Its divider/title row summarizes the run, and each task row shows a hollow or filled status circle, the real persona and task name, status, live active duration, and cumulative child Pi token usage in one compact shared metrics column after the longest row rather than at the terminal edge. Running work uses Pi's warning/yellow semantic color and completed work uses success/green. Token totals use the child session's persisted assistant, tool-result, standalone usage, compaction, and branch-summary usage; they are never estimated. Queued tasks show neither fabricated time nor tokens. The monitor follows Pi theme semantics, truncates by visible terminal columns, and refreshes session usage from both file events and the running one-second timer.
 
-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.
+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. Inside every child Agent, press `Alt+P` or run `/parent` to return to the exact parent Agent pane; the shortcut is also shown in the child footer.
 
 ## History
 
-Run `/herdr-subagents history` or `herdr_subagents_control({ 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.
+Run `/herdr-subagents history` or `herdr_subagents_control({ action: "history" })` to list the full compact project-local run and task archive after Herdr tabs close. History does not accept a run ID and is not a status interface. 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_control({ action: "resume", runId: "<run-id>", task: 1, prompt: "Follow up..." })`. Remove only a selected archive with `herdr_subagents_control({ 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.
 
@@ -192,6 +200,9 @@ The package includes these personas:
 | `worker` | write | `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls` | Focused implementation work |
 | `explorer` | read | `read`, `bash`, `grep`, `find`, `ls` | Fast codebase investigation |
 | `reviewer` | read | `read`, `bash`, `grep`, `find`, `ls` | Correctness and maintainability review |
+| `analyst` | read | `read`, `bash`, `grep`, `find`, `ls` | Neutral analysis with the method and role supplied by each task |
+
+`analyst` deliberately does not bind a model or review method. Use the task-level `model` field when independent tasks need different models, and put roles such as auditor, replicator, or adversary in each task prompt.
 
 Persona definitions use Markdown frontmatter followed by the child system prompt. For example, save this as `.pi/herdr-subagents/agents/security-reviewer.md`:
 

package/packages/herdr-subagents/TESTING.md

@@ -10,18 +10,19 @@
 
 ## Cases
 
-- Resolve package, global, and project personas and validate frontmatter/configuration.
+- Resolve package, global, and project personas and validate frontmatter/configuration, including the neutral read-only `analyst` persona.
 - 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.
+- Force write-capable batches to serial execution while allowing bounded read-only parallelism, including three concurrent `analyst` tasks with independent task-level models.
 - 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 split public contracts (`herdr_subagents` with required `tasks`, plus `herdr_subagents_control` with required `action`) 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 the split public contracts (`herdr_subagents` with required `tasks`, plus `herdr_subagents_control` with required `action`) and injectable extension wiring, including conditional registration only inside Herdr, Fleet rendering, editor focus ownership, terminal-input passthrough, exact-pane navigation, child `/parent` and `Alt+P` return controls, and stable display while another background run queues.
 - Verify Fleet divider/row formatting, warning/yellow running indicators, success/green completed indicators, persona and task projections, cumulative active duration across blocking/resume, exact Pi usage aggregation from assistant messages, tool results, standalone usage, compaction, and branch summaries, malformed/truncated JSONL tolerance, queued metric omission, and visible-column bounds at narrow widths.
 - Verify live token updates are file-event driven and polled on each running one-second tick, elapsed repainting exists only while work runs, and widget disposal closes watchers and timers.
 - Verify selected active/queued run cancellation, blocked-response live Fleet updates, authoritative stale-field replacement, parent-shutdown cancellation, idempotent missing-tab cleanup, cleanup notifications, atomic state replacement, non-retried uncertain startup operations, and stalled warnings.
+- Verify `status(runId)` isolates one run, projects queue-only state, prefers durable state over a stale queue record, exposes blocked questions, marks terminal states settled, rejects unknown IDs, and leaves full `history` semantics unchanged.
 - Verify resumed batches retain newly allocated pane IDs and historical follow-ups exclude simultaneous session writers.
 
 ## Latest baseline
 
-All 168 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, metrics, responsive-formatting, 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.
+All 179 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, metrics, responsive-formatting, 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/analyst.md

@@ -0,0 +1,8 @@
+---
+name: analyst
+description: Neutral read-only analyst for dynamically assigned roles
+access: read
+tools: read, bash, grep, find, ls
+---
+
+Act as an independent analyst and follow the role and evaluation method in the task prompt. Do not modify project files. Separate direct evidence, inference, and unknowns, and report concrete evidence with useful paths.

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

@@ -259,7 +259,7 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 	pi.registerTool({
 		name: "herdr_subagents_control",
 		label: "Herdr Subagents Control",
-		description: "Inspect Herdr personas and run history, cancel active or queued work, answer a blocked task, resume a saved task, or remove a selected archived run. Use herdr_subagents to start new work.",
+		description: "Inspect Herdr personas, query one run by ID, list run history, cancel active or queued work, answer a blocked task, resume a saved task, or remove a selected archived run. Use status for one run and history only for the full archive. Use herdr_subagents to start new work.",
 		promptSnippet: "Inspect and control Herdr subagent runs",
 		parameters: HerdrSubagentsControlParams,
 

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

@@ -4,6 +4,21 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { resultPathForAttempt } from "../src/result-path.ts";
+import { PARENT_PANE_ENV } from "../src/live-agent.ts";
+
+const RETURN_SHORTCUT = "alt+p";
+
+async function returnToParent(pi: ExtensionAPI, ctx: { ui: { notify(message: string, type?: "info" | "warning" | "error"): void } }): Promise<void> {
+	const parentPaneId = process.env[PARENT_PANE_ENV]?.trim();
+	if (!parentPaneId) {
+		ctx.ui.notify("Parent Agent pane is unavailable for this Subagent session.", "error");
+		return;
+	}
+	const result = await pi.exec("herdr", ["agent", "focus", parentPaneId]);
+	if (result.code !== 0) {
+		ctx.ui.notify(`Could not return to the parent Agent: ${result.stderr.trim() || result.stdout.trim() || `Herdr exited ${result.code}`}`, "error");
+	}
+}
 
 const ReportParams = Type.Object({
 	status: StringEnum(["completed", "needs-input", "failed"] as const, { description: "Current outcome for this task." }),
@@ -24,6 +39,17 @@ function writeAtomic(path: string, content: string): void {
 }
 
 export default function (pi: ExtensionAPI) {
+	pi.registerCommand("parent", {
+		description: "Return focus to the parent Agent pane",
+		async handler(_args, ctx) { await returnToParent(pi, ctx); },
+	});
+	pi.registerShortcut(RETURN_SHORTCUT, {
+		description: "Return to parent Agent",
+		async handler(ctx) { await returnToParent(pi, ctx); },
+	});
+	pi.on("session_start", async (_event, ctx) => {
+		if (process.env[PARENT_PANE_ENV]?.trim()) ctx.ui.setStatus("herdr-subagents-parent", `${RETURN_SHORTCUT} parent`);
+	});
 	pi.registerTool({
 		name: "subagent_report",
 		label: "Subagent Report",

package/packages/herdr-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-herdr-subagents",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [

package/packages/herdr-subagents/src/history.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { appendFile, mkdir, readFile, rm, rmdir } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 import { CliHerdrAutomation, type HerdrAutomation } from "./herdr.ts";
-import { liveAgentName, promptLiveAgent } from "./live-agent.ts";
+import { childEnvironment, liveAgentName, promptLiveAgent } from "./live-agent.ts";
 import { writeJsonAtomic, writeTextAtomic } from "./state.ts";
 import { cleanupRunTab } from "./tab-cleanup.ts";
 import type { OwnerIdentity } from "./ownership.ts";
@@ -144,7 +144,7 @@ async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber
 		let report: PersistedReport;
 		let status: "blocked" | "completed" | "failed";
 		try {
-			const env = { PI_HERDR_SUBAGENTS_CHILD: "1", PI_HERDR_SUBAGENTS_TASK_DIR: historical.recordDirectory };
+			const env = childEnvironment(historical.recordDirectory);
 			tab = await herdr.createTab({ workspaceId: process.env.HERDR_WORKSPACE_ID ?? "", cwd, label: `SA · ${run.label}`, env, focus: false, signal: options.signal });
 			const paneLabel = `${String(historical.order).padStart(2, "0")} · ${historical.name}`;
 			await herdr.renamePane(tab.paneId, paneLabel, options.signal);

package/packages/herdr-subagents/src/live-agent.ts

@@ -17,6 +17,17 @@ export interface LiveTaskRecord {
 	skills?: string[];
 }
 
+export const PARENT_PANE_ENV = "PI_HERDR_SUBAGENTS_PARENT_PANE_ID";
+
+export function childEnvironment(taskDirectory: string, environment: NodeJS.ProcessEnv = process.env): Record<string, string> {
+	const parentPaneId = environment.HERDR_PANE_ID?.trim();
+	return {
+		PI_HERDR_SUBAGENTS_CHILD: "1",
+		PI_HERDR_SUBAGENTS_TASK_DIR: taskDirectory,
+		...(parentPaneId ? { [PARENT_PANE_ENV]: parentPaneId } : {}),
+	};
+}
+
 export function childPiArgs(task: LiveTaskRecord, systemPromptFile: string): string[] {
 	const args = [
 		"--approve",

package/packages/herdr-subagents/src/parameters.ts

@@ -16,8 +16,8 @@ export const HerdrSubagentsParams = Type.Object({
 }, { additionalProperties: false });
 
 export const HerdrSubagentsControlParams = Type.Object({
-	action: StringEnum(["list", "respond", "history", "resume", "cancel", "cleanup"] as const, { description: "Control operation to perform." }),
-	runId: Type.Optional(Type.String({ minLength: 1, description: "Durable run ID used by respond, resume, cancel, or cleanup." })),
+	action: StringEnum(["list", "status", "respond", "history", "resume", "cancel", "cleanup"] as const, { description: "Control operation to perform." }),
+	runId: Type.Optional(Type.String({ minLength: 1, description: "Durable run ID used by status, respond, resume, cancel, or cleanup." })),
 	answer: Type.Optional(Type.String({ minLength: 1, description: "Answer sent to a blocked task when action is respond." })),
 	task: Type.Optional(Type.Integer({ minimum: 1, description: "One-based task number selected for respond or resume." })),
 	prompt: Type.Optional(Type.String({ minLength: 1, description: "Follow-up prompt used by resume." })),

package/packages/herdr-subagents/src/run-pane-allocator.ts

@@ -3,6 +3,7 @@ import { writeJsonAtomic } from "./state.ts";
 import type { RunRecord } from "./records.ts";
 import { applyRunStatus } from "./run-status.ts";
 import { cleanupRunTab } from "./tab-cleanup.ts";
+import { childEnvironment } from "./live-agent.ts";
 
 interface RunPaneAllocatorOptions {
 	herdr: HerdrAutomation;
@@ -31,7 +32,7 @@ export class RunPaneAllocator {
 		let paneId = "";
 		this.allocation = this.allocation.then(async () => {
 			const { herdr, run, runFile, signal } = this.options;
-			const env = { PI_HERDR_SUBAGENTS_CHILD: "1", PI_HERDR_SUBAGENTS_TASK_DIR: taskDirectory };
+			const env = childEnvironment(taskDirectory);
 			let anchorExists = Boolean(run.tabId && this.lastPaneId);
 			if (anchorExists && this.options.validateExistingPane) {
 				const survivingPaneIds: string[] = [];

package/packages/herdr-subagents/src/runner.ts

@@ -3,7 +3,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { CliHerdrAutomation, type HerdrAutomation } from "./herdr.ts";
 import { ensureRuntimeIgnored } from "./history.ts";
-import { liveAgentName, promptLiveAgent } from "./live-agent.ts";
+import { childEnvironment, liveAgentName, promptLiveAgent } from "./live-agent.ts";
 import { writeJsonAtomic } from "./state.ts";
 import { cleanupRunTab } from "./tab-cleanup.ts";
 import type { OwnerIdentity } from "./ownership.ts";
@@ -13,9 +13,6 @@ import { reportProtocolPrompt } from "./protocol.ts";
 import { applyRunStatus } from "./run-status.ts";
 import { isAbortError } from "./errors.ts";
 
-const CHILD_ENV = "PI_HERDR_SUBAGENTS_CHILD";
-const TASK_DIRECTORY_ENV = "PI_HERDR_SUBAGENTS_TASK_DIR";
-
 export type HerdrSubagentsDocument = PersistedDocument;
 export type HerdrSubagentsReport = PersistedReport;
 
@@ -168,10 +165,7 @@ export async function runHerdrSubagents(prompt: string, options: HerdrSubagentsO
 			workspaceId: process.env.HERDR_WORKSPACE_ID,
 			cwd,
 			label: `SA · ${label}`,
-			env: {
-				[CHILD_ENV]: "1",
-				[TASK_DIRECTORY_ENV]: taskDirectory,
-			},
+			env: childEnvironment(taskDirectory),
 			focus: false,
 			signal: options.signal,
 		});

package/packages/herdr-subagents/src/status.ts

@@ -0,0 +1,95 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { loadQueuedRuns } from "./queued-runs.ts";
+import { isSettledRunStatus, readReport, readRunRecord, readTaskRecord, type RunStatus, type TaskStatus } from "./records.ts";
+import { findRunDirectory } from "./run-locator.ts";
+
+export interface RunStatusTask {
+	order: number;
+	name: string;
+	agent: string;
+	status: TaskStatus;
+	summary?: string;
+	question?: string;
+	error?: string;
+}
+
+export interface RunStatusSnapshot {
+	runId: string;
+	label: string;
+	status: RunStatus;
+	settled: boolean;
+	source: "run" | "queue";
+	queuedAt?: string;
+	startedAt?: string;
+	updatedAt?: string;
+	completedAt?: string;
+	question?: string;
+	error?: string;
+	tasks: RunStatusTask[];
+}
+
+async function loadDurableStatus(cwd: string, runId: string): Promise<RunStatusSnapshot | undefined> {
+	const runsDirectory = join(cwd, ".pi", "herdr-subagents", "runs");
+	const runDirectory = await findRunDirectory(runsDirectory, runId);
+	if (!runDirectory) return undefined;
+	const run = await readRunRecord(join(runDirectory, "run.json"));
+	const tasksDirectory = join(runDirectory, "tasks");
+	const tasks: RunStatusTask[] = [];
+	if (existsSync(tasksDirectory)) for (const entry of readdirSync(tasksDirectory).sort()) {
+		const taskDirectory = join(tasksDirectory, entry);
+		const task = await readTaskRecord(join(taskDirectory, "task.json"));
+		const reportFile = join(taskDirectory, "report.json");
+		const reportIsCurrent = task.status === "blocked" || isSettledRunStatus(task.status);
+		const report = reportIsCurrent && existsSync(reportFile) ? await readReport(reportFile) : undefined;
+		const question = report?.question ?? task.question;
+		const error = report?.error ?? task.error;
+		tasks.push({
+			order: task.order,
+			name: task.name ?? task.agent ?? `Task ${task.order}`,
+			agent: task.agent ?? "worker",
+			status: task.status,
+			...(report?.summary ? { summary: report.summary } : {}),
+			...(question ? { question } : {}),
+			...(error ? { error } : {}),
+		});
+	}
+	return {
+		runId: run.id,
+		label: run.label,
+		status: run.status,
+		settled: isSettledRunStatus(run.status),
+		source: "run",
+		...(run.startedAt ? { startedAt: run.startedAt } : {}),
+		...(run.updatedAt ? { updatedAt: run.updatedAt } : {}),
+		...(run.completedAt ? { completedAt: run.completedAt } : {}),
+		...(run.question ? { question: run.question } : {}),
+		...(run.error ? { error: run.error } : {}),
+		tasks: tasks.sort((left, right) => left.order - right.order),
+	};
+}
+
+export async function getSubagentRunStatus(cwd: string, runId: string): Promise<RunStatusSnapshot | undefined> {
+	const durable = await loadDurableStatus(cwd, runId);
+	if (durable) return durable;
+	const queued = (await loadQueuedRuns(cwd)).find((candidate) => candidate.runId === runId);
+	if (!queued) return undefined;
+	return {
+		runId: queued.runId,
+		label: queued.params.label ?? "batch",
+		status: "queued",
+		settled: false,
+		source: "queue",
+		queuedAt: queued.queuedAt,
+		tasks: queued.params.tasks.map((task, index) => ({ order: index + 1, name: task.name, agent: task.agent ?? "worker", status: "queued" })),
+	};
+}
+
+export function runStatusText(status: RunStatusSnapshot): string {
+	const lines = [`${status.runId} · ${status.label} · ${status.status} · ${status.tasks.length} tasks`];
+	for (const task of status.tasks) {
+		const detail = task.question ? ` — ${task.question}` : task.summary ? ` — ${task.summary}` : task.error ? ` — ${task.error}` : "";
+		lines.push(`  ${task.order}. ${task.name}: ${task.status}${detail}`);
+	}
+	return lines.join("\n");
+}

package/packages/herdr-subagents/src/tool.ts

@@ -8,6 +8,7 @@ import { HERDR_ACTIONS, validateControlParams, validateRunParams } from "./valid
 import type { OwnerIdentity } from "./ownership.ts";
 import { cancelActiveSubagentRuns } from "./reconcile.ts";
 import { cancelQueuedRuns, loadQueuedRuns } from "./queued-runs.ts";
+import { getSubagentRunStatus, runStatusText } from "./status.ts";
 
 export interface HerdrSubagentsTaskParams { name: string; prompt: string; agent?: string; model?: string; }
 
@@ -19,7 +20,7 @@ export interface HerdrSubagentsRunParams {
 }
 
 export interface HerdrSubagentsControlToolParams {
-	action: "list" | "respond" | "history" | "resume" | "cancel" | "cleanup";
+	action: "list" | "status" | "respond" | "history" | "resume" | "cancel" | "cleanup";
 	runId?: string;
 	answer?: string;
 	task?: number;
@@ -28,7 +29,7 @@ export interface HerdrSubagentsControlToolParams {
 
 /** Internal superset used by shared execution helpers. */
 export interface HerdrSubagentsToolParams {
-	action?: "list" | "respond" | "history" | "resume" | "cancel" | "cleanup";
+	action?: "list" | "status" | "respond" | "history" | "resume" | "cancel" | "cleanup";
 	prompt?: string;
 	agent?: string;
 	label?: string;
@@ -114,6 +115,16 @@ const errorResponse = (text: string, details: Record<string, unknown> = {}): Too
 });
 
 const actionHandlers = {
+	async status({ params, ctx }: ToolExecutionContext) {
+		try {
+			const runId = (params.runId as string).trim();
+			const status = await getSubagentRunStatus(ctx.cwd, runId);
+			if (!status) return errorResponse(`Unknown Subagent run '${runId}'.`, { action: "status", runId });
+			return { content: [{ type: "text", text: runStatusText(status) }], details: { action: "status", ...status } };
+		} catch (error) {
+			return errorResponse(error instanceof Error ? error.message : String(error), { action: "status", runId: params.runId });
+		}
+	},
 	async history({ ctx }: ToolExecutionContext) {
 		const history = await listSubagentHistory(ctx.cwd);
 		return { content: [{ type: "text", text: historyText(history) }], details: { action: "history", runs: history } };

package/packages/herdr-subagents/src/validation.ts

@@ -3,6 +3,7 @@ import type { HerdrSubagentsControlToolParams, HerdrSubagentsRunParams } from ".
 export const HERDR_ACTIONS = {
 	list: { allowed: ["action"], includeRunId: false },
 	history: { allowed: ["action"], includeRunId: false },
+	status: { allowed: ["action", "runId"], includeRunId: true },
 	cancel: { allowed: ["action", "runId"], includeRunId: true },
 	cleanup: { allowed: ["action", "runId"], includeRunId: true },
 	respond: { allowed: ["action", "runId", "answer", "task"], includeRunId: true },
@@ -19,7 +20,7 @@ export function validateControlParams(params: HerdrSubagentsControlToolParams):
 	if (!allowed) return "Provide a valid control action.";
 	const extra = Object.keys(params).find((key) => !allowed.includes(key as keyof HerdrSubagentsControlToolParams));
 	if (extra) return `Field '${extra}' is not valid with action '${params.action}'.`;
-	if ((params.action === "cancel" || params.action === "cleanup") && !params.runId?.trim()) return `runId is required for action '${params.action}'.`;
+	if ((params.action === "status" || params.action === "cancel" || params.action === "cleanup") && !params.runId?.trim()) return `runId is required for action '${params.action}'.`;
 	if (params.action === "respond" && (!params.runId?.trim() || !params.answer?.trim())) return "runId and answer are required for action 'respond'.";
 	if (params.action === "resume" && (!params.runId?.trim() || !params.task || !params.prompt?.trim())) return "runId, task, and prompt are required for action 'resume'.";
 	return undefined;

package/packages/herdr-subagents/tests/extension-contract.ts

@@ -251,6 +251,10 @@ export default function (_pi: ExtensionAPI) {
 		if (!controlSchema.properties?.[name]?.description) throw new Error(`control schema property '${name}' is missing or undocumented`);
 	}
 	if (!controlSchema.required?.includes("action")) throw new Error("herdr_subagents_control action must be required");
+	const controlActions = controlSchema.properties.action.enum ?? controlSchema.properties.action.anyOf?.map((entry: Record<string, unknown>) => entry.const);
+	if (!controlActions?.includes("status")) throw new Error("herdr_subagents_control action enum must include status");
+	if (!/status/.test(controlSchema.properties.runId.description)) throw new Error("control runId description must document status");
+	if (!/Use status for one run/.test(controlTool.description)) throw new Error("control tool description must distinguish status from history");
 	if (!/Foreground calls block/.test(tool.description) || !/background calls return a run ID immediately/.test(tool.description)) {
 		throw new Error("tool description does not distinguish foreground and background execution");
 	}