pi-subagents 0.45.2 → 0.47.0

package/docs/workflows.md

@@ -0,0 +1,163 @@
+# Workflows and orchestration
+
+How to compose subagents: the recommended pattern, packaged prompt shortcuts, scripted workflows, direct commands, worktree isolation, and child-to-parent coordination.
+
+## Recommended orchestration pattern
+
+Use orchestration as parent-agent guidance, not as a runtime workflow mode. For implementation work, the recommended loop is:
+
+```text
+clarify → scout → worker → fresh reviewers → worker
+```
+
+Packaged `worker`, `oracle`, and `advisor` default to forked context when a launch omits `context`; pass `context: "fresh"` when you intentionally want a fresh child run.
+
+Child-safety boundaries are enforced at runtime:
+
+- Spawned child sessions do not receive the bundled `pi-subagents` skill.
+- Forked child context filtering removes parent-only subagent artifacts (including old hidden orchestration-instruction messages, slash/status/control messages, and prior parent `subagent` tool-call/tool-result history) while preserving ordinary prose and unrelated tool calls/results.
+- By default, children do not register the `subagent` tool and receive boundary instructions that they are not the parent orchestrator and must not propose or run subagents.
+- The explicit exception is an agent whose resolved builtin `tools` includes `subagent`; that child gets a child-safe `subagent` tool for the fanout work the parent assigned, still bounded by `maxSubagentDepth`.
+
+## Prompt shortcuts
+
+The package includes reusable prompt templates for common workflows. You do not need them, but they are handy when you want the same shape every time:
+
+| Prompt | Use it for |
+|--------|------------|
+| `/parallel-review` | Launch fresh-context reviewers with distinct angles, then synthesize what to fix. |
+| `/review-loop` | Run parent-controlled worker, reviewer, and fix-worker cycles until clean or capped. |
+| `/parallel-research` | Combine `researcher` and `scout` for external evidence, local code context, and practical tradeoffs. |
+| `/gather-context-and-clarify` | Scout/research first, then ask the user the clarification questions that matter. |
+| `/parallel-cleanup` | Run review-only cleanup passes after implementation. |
+
+Add `autofix` to `/parallel-review` or `/parallel-cleanup` to apply only the synthesized fixes worth doing now after reviewers return.
+
+## Scripted workflows (workflowScript)
+
+All model-facing subagent execution is expressed through `workflowScript` in the `subagent` tool. Use stable keys and ordinary JavaScript for one child, sequence, and parallelism. Scripts are ordinary JavaScript statement bodies. Use an explicit `return` for a useful result:
+
+```js
+subagent({ workflowScript: `
+  const scan = await runs.run("scan", { agent: "scout", task: "Scan the codebase" });
+  const reviews = await runs.all([
+    { key: "correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
+    { key: "tests", agent: "reviewer", task: "Review tests: " + scan.output }
+  ]);
+  return reviews.map(result => result.output);
+` });
+```
+
+For long task text with Markdown fences or shell blocks, use quoted lines instead of a raw template literal:
+
+````js
+const task = [
+  "Run this command:",
+  "```bash",
+  "npm test",
+  "```"
+].join("\n");
+return runs.run("test", { agent: "worker", task });
+````
+
+A plain workflow creates one enclosing mission by default. Its children do not create separate missions. The result exposes the id as `details.missionId`, and human-readable output ends with `Mission: <id> (<status>)`. Pass `mission:false` for an ephemeral workflow with no mission or durable `state` global.
+
+For watched same-repo workflows, pass `async:false` to show the live in-chat workflow card. `chatProgress` can force `off` or `live-card` when the automatic policy is not what you want. Foreground workflows default to a 30-minute timeout; async workflows have no default timeout. See the [tool reference](tool-reference.md) for the full parameter list.
+
+The legacy `/chain`, `/parallel`, and `/run-chain` commands are not registered.
+
+## Direct commands
+
+Use `/run <agent> [task] [--bg] [--fork]` for one child.
+
+## Worktree isolation
+
+Scripted workflows can give each writing child a separate managed git worktree by setting `worktree: true` on each `runs.run` / `runs.all` item:
+
+```javascript
+const [api, ui] = await runs.all([
+  { key: "api", agent: "worker", task: "Implement the API", worktree: true },
+  { key: "ui", agent: "worker", task: "Implement the UI", worktree: true }
+]);
+return { api: api.artifactPaths, ui: ui.artifactPaths };
+```
+
+Each child uses the existing worktree lifecycle: it branches from clean HEAD, journals ownership before launch, captures a patch and handoff manifest, then removes cleanly captured temporary worktrees and branches. The handoff manifest path remains available in the child's `artifactPaths`; return or emit it when the orchestrator needs to apply or inspect the patches. `runs.ref` stays concise and intentionally omits full paths.
+
+A top-level `{ workflowScript, worktree: true }` makes isolation the default for every workflow child. An individual child can override that default with `worktree: false`. Keep one writer when parallel writes are not intentionally isolated.
+
+Configure the worktree base directory and setup hook in [configuration.md](configuration.md).
+
+## Supervisor coordination (child asks parent)
+
+Child agents can talk back to the parent Pi session without installing `pi-intercom`. `pi-subagents` provides the child-facing `contact_supervisor` tool and the parent-facing `subagent_supervisor({ action: "reply" })` path natively. If no external `pi-intercom` tool owns the `intercom` name, the native channel also exposes `intercom` as a compatibility fallback.
+
+Use it for work where the child might need a decision instead of guessing:
+
+```text
+Run this implementation in the background. If the worker gets blocked or needs a product decision, have it ask me through intercom.
+```
+
+```text
+Ask oracle to review this plan. If it sees a decision I need to make, have it ask me instead of assuming.
+```
+
+The child uses one dedicated coordination tool, `contact_supervisor`, with a `reason`:
+
+- `need_decision` — blocking decisions or clarification
+- `interview_request` — structured input
+- `progress_update` — short non-blocking updates when a discovery changes the plan
+
+Children should not ask for clarification when the only conflict is review-only/no-edit versus progress-writing or artifact-writing instructions; no-edit wins.
+
+The parent replies with `subagent_supervisor({ action: "reply", replyTo, message })` or checks pending requests with `subagent_supervisor({ action: "pending" })`. Supervisor messages are scoped to the exact Pi session id that spawned the child. A second Pi session in the same repository does not receive those requests.
+
+Child-side routine completion handoffs are not expected. If a child appears stalled, needs-attention notices show up in the parent session with useful next actions, such as checking `subagent({ action: "status" })`, interrupting the run, or nudging the child.
+
+If messages do not show up, run `/subagents-doctor`. Advanced users can tune the bridge with `intercomBridge` in [configuration.md](configuration.md).
+
+## Recursion guard
+
+Subagents can call `subagent` only when their resolved builtin tools explicitly include `subagent`. That is meant for delegated fanout agents, not ordinary worker/reviewer children. A depth guard prevents unbounded nesting.
+
+By default, nesting is limited to two levels: main session → subagent → sub-subagent. Deeper calls are blocked with guidance to complete the current task directly. Nested runs appear in the parent status widget and `status` output as a tree, and `status`, `interrupt`, and `resume` can target a nested run by its id.
+
+Configure the limit with:
+
+1. `PI_SUBAGENT_MAX_DEPTH` before starting Pi
+2. `config.maxSubagentDepth`
+3. `maxSubagentDepth` in agent frontmatter, which can only tighten the inherited limit
+
+```bash
+export PI_SUBAGENT_MAX_DEPTH=3
+export PI_SUBAGENT_MAX_DEPTH=1
+export PI_SUBAGENT_MAX_DEPTH=0
+```
+
+`PI_SUBAGENT_DEPTH` is internal and propagated automatically. Do not set it manually.
+
+## Prompt-template integration
+
+`pi-subagents` includes a native prompt-workflow adapter for reusable subagent prompt templates, so you do not need `pi-prompt-template-model` for the common subagent workflow path.
+
+Create a prompt in `.pi/prompts/` or `~/.pi/agent/prompts/`:
+
+```md
+---
+description: Take a screenshot
+model: claude-sonnet-4-20250514
+subagent: browser-screenshoter
+cwd: /tmp/screenshots
+---
+Use url in the prompt to take screenshot: $@
+```
+
+Then run it through the native adapter:
+
+```text
+/prompt-workflow take-screenshot https://example.com
+```
+
+The adapter delegates to the named subagent, applies `model`, `skill`, `cwd`, and fork/fresh context metadata, and supports runtime overrides such as `--subagent reviewer`, `--fork`, `--fresh`, and `--bg`.
+
+Prompt templates with `chain:` frontmatter are translated into `workflowScript` and launched through `/prompt-workflow`; `/chain-prompts` is no longer registered.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.45.2",
+  "version": "0.47.0",
   "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -15,7 +15,8 @@
     "./control-channel": "./src/api/control-channel.ts",
     "./intercom-bridge": "./src/api/intercom-bridge.ts",
     "./pi-args": "./src/api/pi-args.ts",
-    "./shared-types": "./src/api/shared-types.ts"
+    "./shared-types": "./src/api/shared-types.ts",
+    "./project-panes": "./src/api/project-panes.ts"
   },
   "repository": {
     "type": "git",
@@ -44,6 +45,7 @@
     "agents/",
     "skills/**/*",
     "prompts/**/*",
+    "docs/**/*",
     "README.md",
     "CHANGELOG.md"
   ],

package/skills/pi-subagents/references/execution-controls.md

@@ -68,11 +68,11 @@ subagent({
 })
 ```
 
-Scripts run in a timed worker with only `runs.run`, `runs.all`, `runs.status`, `runs.ref/refs`, `emit`, captured `console`, and standard JavaScript. Mission-attached workflows also get `await state.get(key)` and `await state.set(key, value)` for durable JSON state shared across workflows on the same mission; `mission: false` workflows have no `state` global. Stable keys are required. Child launches follow ordinary single-agent execution controls. Give each child a distinct decision and output path when reports must outlive the workflow, then consume the aggregate workflow result before opening individual reports.
+Scripts run in a timed worker with only `runs.run`, `runs.all`, `runs.status`, `runs.ref/refs`, `prompts.render`, `emit`, captured `console`, and standard JavaScript. `await prompts.render("package:<name>" | "user:<name>" | "project:<name>", vars?)` reads a named Markdown fragment through the host resolver, applies simple scalar `{{name}}` interpolation, and returns plain task text. It does not give the script filesystem access. Pass the rendered text explicitly as `task` to `runs.run`. Mission-attached workflows also get `await state.get(key)` and `await state.set(key, value)` for durable JSON state shared across workflows on the same mission; `mission: false` workflows have no `state` global. Stable keys are required. Child launches follow ordinary single-agent execution controls. Give each child a distinct decision and output path when reports must outlive the workflow, then consume the aggregate workflow result before opening individual reports.
 
 For one host-run verification command, pass `gate: "npm test"` on a `runs.run`/`runs.all` item (or at the top level as a workflow default). It is shorthand for verified acceptance with that single command: the runtime executes it on the host, records the result as evidence, and memoizes it per tracked workspace state and effective environment. `gate` cannot be combined with `acceptance`; use explicit `acceptance.verify` for multiple commands or custom criteria.
 
-Completed workflow children from this parent session stay addressable as retained children. `subagent({ action: "children.list" })` lists up to the last 10 with run ids, and a later workflow continues one with `runs.run(key, { resume: "<run-id>", task: "follow-up" })`. `resume` and `agent` are mutually exclusive, the revived child keeps its stored agent/model/tool contract, and `gate` is rejected on retained resume items.
+Completed workflow children from this parent session stay addressable as retained children. `subagent({ action: "children.list" })` lists up to the last 10 with run ids, and a later workflow continues one with `runs.run(key, { resume: "<run-id>", task: "follow-up" })`. Inside `workflowScript`, awaiting that call waits for the revived child to finish and returns its completed output and new `runId`; top-level `{ action: "resume" }` remains detached. A follow-up loop can render each task with `await prompts.render(...)`. Assign each returned child result back to the loop variable because every resume can return a new retained `runId`; always resume the latest returned id. `resume` and `agent` are mutually exclusive, the revived child keeps its stored agent/model/tool contract, and `gate` is rejected on retained resume items.
 
 ### Async/background
 
@@ -158,7 +158,7 @@ A cooperating terminal runtime can register read-only external records through `
 
 ### Scheduled subagent runs
 
-Schedules are durable project records under `.pi-subagents/schedules/`. They are enabled by default; set `{ "scheduledRuns": { "enabled": false } }` in `~/.pi/agent/extensions/subagent/config.json` to disable them. Only schedule explicit work the user asked for.
+Schedules are durable project records under `.pi/subagents/schedules/`. They are enabled by default; set `{ "scheduledRuns": { "enabled": false } }` in `~/.pi/agent/extensions/subagent/config.json` to disable them. Only schedule explicit work the user asked for.
 
 ```typescript
 // One-shot reviewer
@@ -235,7 +235,7 @@ The subagent watchdog is an **opt-in** adversarial change reviewer. It is not th
 
 When enabled, it reviews actual repo edits at safe `agent_end` boundaries only if
 the final worktree state changed during that turn. Unchanged or reverted diffs and
-generated `.pi-subagents/` / temp artifacts do not trigger review. Writing children
+generated `.pi/subagents/` / temp artifacts do not trigger review. Writing children
 can review their own worktree; the parent can still review the aggregate diff after
 child changes land. Enabled watchdogs also run changed-file TypeScript/JavaScript
 LSP diagnostics before the model pass when `typescript-language-server` is available.
@@ -298,7 +298,7 @@ Routing rule:
 - Several projects with independent work: one async `workflowScript` whose child keys include repo slugs and whose child calls set explicit `cwd`; keep publication and merge decisions serial per repo.
 - Different project, substantial or long-running work: open a project-owned Herdr pane rooted there when a separate visible project session is useful, then give that project Pi session a narrow mission/result contract. Do not model it as ordinary child nesting, and do not expect existing headless runs to move into the pane.
 
-Project panes run a separate Pi session from the target directory. Subagents launched inside that pane use that project's config, agents, skills, files, git state, and mission records. The pane binding lives under `<projectRoot>/.pi-subagents/project-panes/herdr.json`. For ordinary headless delegation to another repo, prefer explicit `cwd` first; reserve project panes for visible or persistent project ownership.
+Project panes run a separate Pi session from the target directory. Subagents launched inside that pane use that project's config, agents, skills, files, git state, and mission records. The pane binding lives under `<projectRoot>/.pi/subagents/project-panes/herdr.json`. For ordinary headless delegation to another repo, prefer explicit `cwd` first; reserve project panes for visible or persistent project ownership.
 
 ```typescript
 subagent({ action: "mission.create", mission: { title: "Ship auth refresh", objective: "Implement and validate refresh handling" } })
@@ -340,7 +340,7 @@ single-writer pattern instead.
 
 Git worktrees start from tracked files, so ignored or untracked build state
 such as `node_modules` may be absent. The clean-check ignores pi-subagents'
-own `.pi-subagents/` runtime state, including default mission records, but still
+own `.pi/subagents/` runtime state, including default mission records, but still
 rejects ordinary source/config changes. `pi-subagents` attempts to symlink the
 root checkout's `node_modules` into each managed worktree when it exists, but
 agents should still treat dependency setup as an explicit bootstrap step before

package/skills/pi-subagents/references/management-authoring-rpc.md

@@ -28,7 +28,7 @@ subagent({ action: "refine.show", agent: "reviewer" })
 subagent({ action: "refine.rollback", agent: "reviewer" })
 ```
 
-`refine` builds a bounded project-local guidance overlay for one agent from recent run evidence, using a fresh read-only proposal child; validated guidance is stored under `.pi-subagents/refinements/<agent>.md` with revision snapshots and is injected into that agent's child system prompt for this project. `refine.show` prints the current overlay and history; `refine.rollback` restores the previous revision. Guidance that tries to override safety, policy, tool, output, acceptance, developer, or system instructions is rejected. `/subagents-refine <agent>` is the slash equivalent.
+`refine` builds a bounded project-local guidance overlay for one agent from recent run evidence, using a fresh read-only proposal child; validated guidance is stored under `.pi/subagents/refinements/<agent>.md` with revision snapshots and is injected into that agent's child system prompt for this project. `refine.show` prints the current overlay and history; `refine.rollback` restores the previous revision. Guidance that tries to override safety, policy, tool, output, acceptance, developer, or system instructions is rejected. `/subagents-refine <agent>` is the slash equivalent.
 
 ### Create an agent
 

package/src/agents/agents.ts

@@ -659,16 +659,25 @@ function findConfiguredProjectRoot(cwd: string): string | null {
 	const nearestRoot = candidates[0];
 	if (!nearestRoot) return null;
 
-	const nearestMode = readProjectRootResolution(nearestRoot);
-	if (nearestMode === "nearest") return nearestRoot;
-
-	const gitRoot = findNearestGitRoot(cwd);
-	const gitProjectRoot = gitRoot ? candidates.find((candidate) => path.resolve(candidate) === path.resolve(gitRoot)) : undefined;
-	if (gitProjectRoot && (nearestMode === "git-root" || readProjectRootResolution(gitProjectRoot) === "git-root")) {
-		return gitProjectRoot;
+	let policyRoot: string | undefined;
+	let policyRootIndex = -1;
+	for (const [index, candidate] of candidates.entries()) {
+		const mode = readProjectRootResolution(candidate);
+		if (mode === "nearest") return nearestRoot;
+		if (mode === "git-root") {
+			policyRoot = candidate;
+			policyRootIndex = index;
+			break;
+		}
 	}
+	if (!policyRoot) return nearestRoot;
 
-	return nearestRoot;
+	const gitRoot = findNearestGitRoot(cwd);
+	const gitProjectRoot = gitRoot
+		? candidates.slice(policyRootIndex).find((candidate) => path.resolve(candidate) === path.resolve(gitRoot))
+		: undefined;
+	const configuredGitRoot = fs.existsSync(path.join(policyRoot, ".git")) ? policyRoot : undefined;
+	return gitProjectRoot ?? configuredGitRoot ?? nearestRoot;
 }
 
 function getUserAgentSettingsPath(): string {

package/src/agents/frontmatter.ts

@@ -83,12 +83,13 @@ export function parseFrontmatter(content: string): { frontmatter: Record<string,
 	let currentBlockLines: string[] | null = null;
 	let currentIndent: number | null = null;
 	let currentFolded = false;
+	let currentLiteral = false;
 
 	for (const line of lines) {
 		const indent = line.search(/\S|$/); // position of first non-whitespace char
 		const trimmed = line.trim();
 
-		if (currentKey !== null && currentBlockLines !== null && (indent > (currentIndent ?? 0) || (currentFolded && trimmed === ""))) {
+		if (currentKey !== null && currentBlockLines !== null && (indent > (currentIndent ?? 0) || ((currentFolded || currentLiteral) && trimmed === ""))) {
 			// This line is part of the current block value
 			currentBlockLines.push(line);
 			continue;
@@ -109,6 +110,7 @@ export function parseFrontmatter(content: string): { frontmatter: Record<string,
 			currentBlockLines = null;
 			currentIndent = null;
 			currentFolded = false;
+			currentLiteral = false;
 		}
 
 		const match = line.match(/^([\w-]+):\s*(.*)$/);
@@ -119,13 +121,15 @@ export function parseFrontmatter(content: string): { frontmatter: Record<string,
 			const isQuoted = (rawValue.startsWith('"') && rawValue.endsWith('"')) || (rawValue.startsWith("'") && rawValue.endsWith("'"));
 			const value = isQuoted ? rawValue.slice(1, -1) : rawValue;
 			const isFolded = !isQuoted && (rawValue === ">" || rawValue === ">-");
+			const isLiteral = !isQuoted && (rawValue === "|" || rawValue === "|-");
 
-			if (value === "" || isFolded) {
-				// Key with empty value or folded block indicator — defer storing until we see indent
+			if (value === "" || isFolded || isLiteral) {
+				// Key with empty value or block scalar indicator — defer storing until we see indent
 				currentKey = key;
 				currentBlockLines = [];
 				currentIndent = indent;
 				currentFolded = isFolded;
+				currentLiteral = isLiteral;
 			} else {
 				// Simple key: value
 				frontmatter[key] = value;

package/src/agents/skills.ts

@@ -6,6 +6,7 @@ import { execSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { parseFrontmatter } from "./frontmatter.ts";
 import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
 
 export type SkillSource =
@@ -395,15 +396,7 @@ function chooseHigherPrioritySkill(existing: CachedSkillEntry | undefined, candi
 }
 
 function parseSkillDescription(content: string): string | undefined {
-	const normalized = content.replace(/\r\n/g, "\n");
-	if (!normalized.startsWith("---")) return undefined;
-
-	const endIndex = normalized.indexOf("\n---", 3);
-	if (endIndex === -1) return undefined;
-
-	const frontmatter = normalized.slice(3, endIndex).trim();
-	const match = frontmatter.match(/^description:\s*(.+)$/m);
-	return match?.[1]?.trim().replace(/^['\"]|['\"]$/g, "");
+	return parseFrontmatter(content).frontmatter.description;
 }
 
 function maybeReadSkillDescription(filePath: string): string | undefined {

package/src/api/project-panes.ts

@@ -0,0 +1,30 @@
+/**
+ * Public project-owned Herdr pane lifecycle API for other Pi extensions.
+ *
+ * This is the supported extension-to-extension surface. Callers must not
+ * import `src/inspectors/herdr/*` directly.
+ */
+export {
+	PROJECT_PANES_API_VERSION,
+	PROJECT_PANE_TRUST_STATUS,
+	createProjectPaneManager,
+	openProjectPane,
+	getProjectPaneStatus,
+	closeProjectPane,
+	readProjectPaneBinding,
+	projectPaneBindingPath,
+	type ProjectPaneManager,
+	type ProjectPaneManagerOptions,
+	type ProjectPaneCommandClient,
+	type OpenProjectPaneOptions,
+	type GetProjectPaneStatusOptions,
+	type CloseProjectPaneOptions,
+	type OpenProjectPaneData,
+	type ProjectPaneStatusData,
+	type CloseProjectPaneData,
+	type ProjectPaneRuntime,
+	type ProjectPaneError,
+	type ProjectPaneErrorCode,
+	type ProjectPaneResult,
+	type HerdrProjectPaneBinding,
+} from "../inspectors/herdr/project-panes.ts";

package/src/extension/config.ts

@@ -1,13 +1,14 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import type { ArtifactDirPreference, ExtensionConfig } from "../shared/types.ts";
+import { FLEET_KEYBINDING_ACTIONS, type ArtifactDirPreference, type ExtensionConfig } from "../shared/types.ts";
 import { validateMissionStoreConfig } from "../missions/store.ts";
 import { validateAuthorityPolicy } from "../policy/authority.ts";
 import { getAgentDir } from "../shared/utils.ts";
 import { validatePermissionConfig } from "../runs/shared/permissions.ts";
 
 const ARTIFACT_DIR_PREFERENCES = new Set<ArtifactDirPreference>(["project", "session", "temp"]);
+const FLEET_KEYBINDING_ACTION_SET = new Set<string>(FLEET_KEYBINDING_ACTIONS);
 
 export function resolveScheduledStoreRoot(value: string): string {
 	const expanded = value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
@@ -24,14 +25,30 @@ function validateScheduledRunsConfig(value: unknown): void {
 	resolveScheduledStoreRoot(storeRoot);
 }
 
+function validateFleetKeybindingsConfig(value: unknown): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.fleetKeybindings must be a JSON object");
+	for (const [action, bindings] of Object.entries(value)) {
+		if (!FLEET_KEYBINDING_ACTION_SET.has(action)) throw new Error(`config.fleetKeybindings.${action} is not a supported Fleet action`);
+		if (!Array.isArray(bindings) || bindings.length === 0) throw new Error(`config.fleetKeybindings.${action} must be a non-empty array of strings`);
+		for (const binding of bindings) {
+			if (typeof binding !== "string" || !binding.trim()) throw new Error(`config.fleetKeybindings.${action} entries must be non-empty strings`);
+		}
+	}
+}
+
 function validateConfig(config: Record<string, unknown>): void {
 	if (config.artifactDir !== undefined && !ARTIFACT_DIR_PREFERENCES.has(config.artifactDir as ArtifactDirPreference)) {
 		throw new Error(`config.artifactDir must be "project", "session", or "temp"`);
 	}
+	if (config.legacyChainControls !== undefined && typeof config.legacyChainControls !== "boolean") {
+		throw new Error("config.legacyChainControls must be a boolean");
+	}
 	validateMissionStoreConfig(config.missions);
 	validateAuthorityPolicy(config.authorityPolicy);
 	validatePermissionConfig(config.permissions);
 	validateScheduledRunsConfig(config.scheduledRuns);
+	validateFleetKeybindingsConfig(config.fleetKeybindings);
 }
 
 export function getConfigPath(): string {

package/src/extension/fanout-child.ts

@@ -10,7 +10,7 @@ import { SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV } from "../runs/shared/pi
 import { readNestedControlRequests, resolveNestedRouteFromEnv, type NestedRoute, writeNestedControlResult } from "../runs/shared/nested-events.ts";
 import { deliverSubagentIntercomMessageEvent } from "../intercom/result-intercom.ts";
 import { resolveSubagentIntercomTarget } from "../intercom/intercom-bridge.ts";
-import { SubagentParams } from "./schemas.ts";
+import { createSubagentParamsSchema } from "./schemas.ts";
 import { loadConfig, resolveAsyncByDefault } from "./config.ts";
 import { type Details, type SubagentState } from "../shared/types.ts";
 
@@ -171,15 +171,16 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
 		allowMutatingManagementActions: false,
 	});
 
-	const tool: ToolDefinition<typeof SubagentParams, Details> = {
+	const params = createSubagentParamsSchema(config);
+	const tool: ToolDefinition<typeof params, Details> = {
 		name: "subagent",
 		label: "Subagent",
 		description: [
 			"Delegate to subagents from child-safe fanout mode.",
-			"Allowed management/control actions: list, get, status, interrupt, resume, steer, append-step, doctor.",
+			`Allowed management/control actions: list, get, status, interrupt, resume, steer${config.legacyChainControls === true ? ", append-step" : ""}, doctor.`,
 			"Mutating management actions (create, update, delete, eject, disable, enable, reset, grant-spawn-budget) are blocked in this mode.",
 		].join("\n"),
-		parameters: SubagentParams,
+		parameters: params,
 		execute(id, params, signal, onUpdate, ctx) {
 			return executor.executePublic(id, params as SubagentParamsLike, signal ?? new AbortController().signal, onUpdate, ctx);
 		},

package/src/extension/index.ts

@@ -27,7 +27,7 @@ import { cleanupOldChainDirs } from "../shared/settings.ts";
 import { clearLegacyResultAnimationTimer, renderSubagentResult, renderSubagentSummary } from "../tui/render.ts";
 import { openSubagentFleet } from "../tui/fleet.ts";
 import { SubagentFleetStatus, resolveFleetViewPlacement } from "../tui/fleet-status.ts";
-import { SubagentParams } from "./schemas.ts";
+import { createSubagentParamsSchema } from "./schemas.ts";
 import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
 import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
 import { createResultWatcher } from "../runs/background/result-watcher.ts";
@@ -37,7 +37,7 @@ import { registerPromptTemplateDelegationBridge } from "../slash/prompt-template
 import { registerMainWatchdog } from "../watchdog/register-main.ts";
 import { registerSlashSubagentBridge } from "../slash/slash-bridge.ts";
 import { createNativeSupervisorChannel } from "../intercom/native-supervisor-channel.ts";
-import { registerHerdrStatusBridge } from "../integrations/herdr-status.ts";
+import { registerHerdrStatusBridge, type HerdrStatusRun } from "../integrations/herdr-status.ts";
 import { registerSubagentRpcBridge } from "./rpc.ts";
 import { clearSlashSnapshots, getSlashRenderableSnapshot, resolveSlashMessageDetails, restoreSlashFinalSnapshots, type SlashMessageDetails } from "../slash/slash-live-state.ts";
 import { inspectSubagentStatus } from "../runs/background/run-status.ts";
@@ -53,7 +53,7 @@ import { formatDuration, shortenPath } from "../shared/formatters.ts";
 import { loadConfig, resolveAsyncByDefault, resolveScheduledStoreRoot } from "./config.ts";
 import { buildSubagentToolDescription } from "./tool-description.ts";
 import { collectGoalContinuationNotices } from "../missions/goal-driver.ts";
-import { syncMissionFromAsyncCompletion } from "../missions/lifecycle.ts";
+import { restoreForegroundRunHistory } from "../runs/foreground/foreground-history.ts";
 import { resolveMissionStoreLocation } from "../missions/store.ts";
 import { listRetainedChildren } from "../runs/background/retained-children.ts";
 import {
@@ -309,6 +309,36 @@ class SubagentControlNoticeComponent implements Component {
 	}
 }
 
+export function projectActiveHerdrRuns(state: SubagentState): HerdrStatusRun[] {
+	const active = (status: string) => status === "queued" || status === "running";
+	const foregroundChildrenByWorkflow = new Map<string, Array<{ agent: string; needsAttention: boolean }>>();
+	for (const control of state.foregroundControls.values()) {
+		if (!control.parentWorkflowRunId) continue;
+		const children = control.activeChildren?.size
+			? [...control.activeChildren.values()].map((child) => ({
+				agent: child.agent,
+				needsAttention: child.currentActivityState === "needs_attention",
+			}))
+			: control.currentAgent
+				? [{ agent: control.currentAgent, needsAttention: control.currentActivityState === "needs_attention" }]
+				: [];
+		if (children.length === 0) continue;
+		const existing = foregroundChildrenByWorkflow.get(control.parentWorkflowRunId) ?? [];
+		existing.push(...children);
+		foregroundChildrenByWorkflow.set(control.parentWorkflowRunId, existing);
+	}
+	return [...state.asyncJobs.values()]
+		.filter((job) => active(job.status))
+		.map((job) => {
+			const children = job.mode === "workflow" ? foregroundChildrenByWorkflow.get(job.asyncId) : undefined;
+			return {
+				id: job.asyncId,
+				agents: children?.length ? children.map((child) => child.agent) : job.agents,
+				needsAttention: job.activityState === "needs_attention" || children?.some((child) => child.needsAttention),
+			};
+		});
+}
+
 export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	if (process.env[SUBAGENT_CHILD_ENV] === "1") {
 		return;
@@ -362,6 +392,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		lastUiContext: null,
 		poller: null,
 		completionSeen: new Map(),
+		widgetsSuspended: false,
 		watcher: null,
 		watcherRestartTimer: null,
 		resultFileCoalescer: {
@@ -378,7 +409,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		? new SubagentFleetStatus(state, async (itemKey) => {
 			const ctx = state.lastUiContext;
 			if (!ctx?.hasUI) return;
-			await openSubagentFleet(ctx, state, { initialKey: itemKey, asyncDirRoot: DIRS.async, resultsDir: DIRS.results });
+			await openSubagentFleet(ctx, state, { initialKey: itemKey, asyncDirRoot: DIRS.async, resultsDir: DIRS.results, fleetKeybindings: config.fleetKeybindings });
 		}, { placement: fleetViewPlacement })
 		: undefined;
 	let executorScheduled: ((id: string, params: SubagentParamsLike, signal: AbortSignal, ctx: ExtensionContext) => Promise<AgentToolResult<Details>>) | undefined;
@@ -536,11 +567,12 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	});
 
 
-	const tool: ToolDefinition<typeof SubagentParams, Details> = {
+	const parameters = createSubagentParamsSchema(config);
+	const tool: ToolDefinition<typeof parameters, Details> = {
 		name: "subagent",
 		label: "Subagent",
 		description: buildSubagentToolDescription(config),
-		parameters: SubagentParams,
+		parameters,
 
 		execute(id, params, signal, onUpdate, ctx) {
 			return executeSubagentCollapsed(id, params as SubagentParamsLike, signal ?? new AbortController().signal, onUpdate, ctx);
@@ -603,7 +635,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		}
 	});
 
-	registerSlashCommands(pi, state);
+	registerSlashCommands(pi, state, { fleetKeybindings: config.fleetKeybindings });
 
 	const eventUnsubscribeStoreKey = "__piSubagentEventUnsubscribes";
 	const controlNoticeSeenStoreKey = "__piSubagentVisibleControlNotices";
@@ -621,13 +653,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const existingVisibleControlNotices = globalStore[controlNoticeSeenStoreKey];
 	const visibleControlNotices = existingVisibleControlNotices instanceof Set ? existingVisibleControlNotices as Set<string> : new Set<string>();
 	globalStore[controlNoticeSeenStoreKey] = visibleControlNotices;
-	const activeHerdrRuns = () => [...state.asyncJobs.values()]
-		.filter((job) => job.status === "queued" || job.status === "running")
-		.map((job) => ({
-			id: job.asyncId,
-			agents: job.agents,
-			needsAttention: job.activityState === "needs_attention",
-		}));
+	const activeHerdrRuns = () => projectActiveHerdrRuns(state);
 	const herdrStatusBridge = registerHerdrStatusBridge({
 		events: pi.events,
 		getRuns: activeHerdrRuns,
@@ -653,11 +679,6 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const asyncCompleteHandler = (payload: unknown) => {
 		handleComplete(payload);
 		scheduledRunManager.handleAsyncCompletion(payload);
-		try {
-			syncMissionFromAsyncCompletion(payload);
-		} catch (error) {
-			console.error("Failed to update mission from async completion:", error);
-		}
 		fleetStatus?.refresh();
 	};
 	const eventUnsubscribes = [
@@ -694,7 +715,22 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		}
 	};
 
+	const suspendWidgetsForCompaction = () => {
+		if (state.widgetsSuspended) return;
+		state.widgetsSuspended = true;
+		if (state.lastUiContext?.hasUI) state.lastUiContext.ui.setWidget(WIDGET_KEY, undefined);
+		fleetStatus?.refresh();
+	};
+	const resumeWidgetsAfterCompaction = () => {
+		if (!state.widgetsSuspended) return;
+		state.widgetsSuspended = false;
+		const ctx = state.lastUiContext;
+		if (ctx?.hasUI) refreshWidget(ctx);
+		fleetStatus?.refresh();
+	};
+
 	const resetSessionState = (ctx: ExtensionContext, recovering: boolean) => {
+		state.widgetsSuspended = false;
 		state.baseCwd = ctx.cwd;
 		goalTurnId = 0;
 		state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
@@ -722,6 +758,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		state.foregroundControls.clear();
 		state.lastForegroundControlId = null;
 		resetJobs(ctx);
+		restoreForegroundRunHistory(state, { resultsDir: DIRS.results });
 		restoreActiveJobs(ctx);
 		scheduledRunManager.bindSession(ctx);
 		restoreSlashFinalSnapshots(ctx.sessionManager.getEntries());
@@ -732,9 +769,18 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	};
 
 	pi.on("agent_start", () => {
+		resumeWidgetsAfterCompaction();
 		herdrStatusBridge.agentStarted();
 	});
 
+	pi.on("agent_settled", () => {
+		resumeWidgetsAfterCompaction();
+	});
+
+	pi.on("session_before_compact", (event) => {
+		if (event.reason !== "manual") suspendWidgetsForCompaction();
+	});
+
 	pi.on("session_compact", () => {
 		const hasActiveAsyncWork = [...state.asyncJobs.values()].some((job) => job.status === "queued" || job.status === "running");
 		if (!hasActiveAsyncWork || state.lastUiContext?.hasUI !== true) return;
@@ -760,6 +806,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	});
 
 	pi.on("session_shutdown", async () => {
+		state.widgetsSuspended = false;
 		stopResultWatcher();
 		state.currentSessionId = null;
 		state.parentSessionFile = null;