pi-subagents 0.37.1 → 0.38.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [0.38.0] - 2026-07-30
+
+### Added
+- Added `j`/`k` navigation aliases to the non-filterable `/subagents-stop` selector and clarify step list while preserving text input in editor and search modes. Thanks to @magoz for #686.
+- Added the optional versioned `fleetStatus` RPC capability with bounded, current-session child roles, goals, model/effort, split token usage, elapsed timestamps, stable opaque reconciliation keys, and explicit overflow counts. Thanks to @neumie for #682.
+
+### Fixed
+- Enabled the advertised `j`/`k` navigation aliases after activating the persistent FleetView while leaving printable editor input untouched before activation. Thanks to @magoz for #685.
+- Added opt-in `subagents.projectRootResolution: "git-root"` so monorepos and git worktrees can keep the default nearest-root behavior unless they choose to resolve project packages and `agentOverrides` from the git root. Thanks to @klajdo-f for #677.
+- Recognized structurally compatible custom editors in FleetView focus detection, restoring FleetView arrow-key activation and navigation when a custom editor has focus. Thanks to @magoz for #679.
+- Scoped foreground fleet records to their originating parent session and propagated resolved model, thinking effort, and split input/output usage through live foreground controls.
+- Matched fleet RPC filtering to the canonical session-file identity used by live async and foreground state.
+- Kept pi-intercom stable IDs from leaking into child sessions and used the current intercom runtime ID for unnamed supervisor targets.
+- Improved acceptance policy validation errors and tool-schema guidance for invalid evidence kinds. Thanks to @atimofeev for #672.
+- Tolerated temporary steering inbox scan failures so pending steer requests can be retried on the next poll. Thanks to @hughcars for #670.
+- Retried short, zero-activity child startup exits on the same model with bounded backoff, reducing concurrent subagent launch races without replaying model or tool work. Thanks to @felipeteodorocw for #671.
+- Bounded streamed subagent progress snapshots so a long or deeply nested fan-out no longer emits a `tool_execution_update` line above the child-stdout protocol cap and gets the child killed with `protocol_output_limit`. Streamed `onUpdate` snapshots now carry compact tool-call summaries instead of the full message transcript, cap `recentTools`, and truncate `recentOutput` line length; the returned result and detached-exit recovery keep the full transcript. Thanks to @shaharmor for #680/#681.
+
+## [0.37.2] - 2026-07-28
+
+### Changed
+- Reduced repeated scanning and file reads in live TUI rendering and skill loading.
+
+### Fixed
+- Passed `--no-context-files` to child Pi runs when an agent disables inherited project context, avoiding stale prompt-header parsing as Pi's context block format changes. Thanks to @KorenKrita for #667.
+
 ## [0.37.1] - 2026-07-27
 
 ### Added

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nico Bailon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -157,6 +157,18 @@ For a persistent override, edit settings. This example pins the reviewer everywh
 
 Use `~/.pi/agent/settings.json` for a user override or the project config settings file (`.pi/settings.json` in standard Pi) for a project override. `subagents.defaultModel` applies to builtin, package, user, and project agents that do not set `model` in frontmatter. Per-run model overrides and `agentOverrides.<name>.model` still win, and explicit agent frontmatter still wins over the global default. The same `agentOverrides` block can change `tools`, `skills`, inherited context, prompt text, or disable a builtin. Matching user and project agents also receive override fields that their frontmatter leaves unset, so a shared project config agent can keep the persona while local settings choose the model.
 
+By default, project settings resolve from the nearest parent directory that contains `.pi` or `.agents`, preserving existing nested-project behavior. In monorepos or git worktrees where an incidental nested `.pi` directory should not shadow the repository-level config, set this in the repository root `.pi/settings.json`:
+
+```json
+{
+  "subagents": {
+    "projectRootResolution": "git-root"
+  }
+}
+```
+
+`"git-root"` keeps package discovery, project agents, chains, and `agentOverrides` anchored to the git worktree root when that root also has Pi project config. A nested project can still opt back into nearest-root behavior by setting `"projectRootResolution": "nearest"` in its own `.pi/settings.json`.
+
 Set `subagents.defaultThinking` to give builtin, package, user, and project agents without a `thinking` value a shared thinking level, independent of the parent session's default. Project settings win over user settings. Explicit frontmatter, `agentOverrides.<name>.thinking`, and per-run thinking overrides still win; `thinking: false` remains an explicit opt-out:
 
 ```json
@@ -274,7 +286,7 @@ To keep subagents inside a budget or compliance profile, enforce a model scope.
 
 Foreground runs stream progress in the conversation while they run. They default to a generous 30-minute wall-clock timeout when neither the call nor the selected agent provides a timeout; explicit `timeoutMs`/`maxRuntimeMs` and agent defaults win.
 
-Background runs keep working after control returns to you. Inspect active runs with `subagent({ action: "status" })`, or a specific run with `subagent({ action: "status", id: "..." })`. In the TUI, a persistent FleetView below the editor by default shows `main` plus active children with task, elapsed time, and token totals. Set `fleetViewPlacement` to `"aboveEditor"` to move it above the editor. When the focused editor is empty, use `↑`/`↓` or `j`/`k` to select a child and `Enter` to inspect it; normal editor input is never intercepted.
+Background runs keep working after control returns to you. Inspect active runs with `subagent({ action: "status" })`, or a specific run with `subagent({ action: "status", id: "..." })`. In the TUI, a persistent FleetView below the editor by default shows `main` plus active children with task, elapsed time, and token totals. Set `fleetViewPlacement` to `"aboveEditor"` to move it above the editor. When the focused editor is empty, press `↓` or `←` to activate FleetView, then use `↑`/`↓` or `j`/`k` to select a child and `Enter` to inspect it; printable navigation keys are never intercepted before activation.
 
 `/subagents-fleet` opens the live, inspection-only fleet inspector with current-session foreground work, recent async children, structured Markdown/tool transcripts, and completed output/session paths. Use `↑`/`↓` or `j`/`k` to select a child, `Shift+K`/`Shift+J` to scroll one line, `PgUp`/`PgDn` to scroll one page, `x`/`Ctrl+O` to toggle tool details, `r` to refresh, and `Esc` to close. `Ctrl+Alt+F` opens the same inspector even while a foreground turn is active and slash input is queued. Without a TUI, `/subagents-fleet` retains the textual `subagent({ action: "status", view: "fleet" })` fallback. Mutations stay in explicit commands: run `/subagents-stop` and pick from the selector, or use `/subagents-stop <run-id>` / `subagent({ action: "stop", id: "..." })` when you already know the id. To inspect one background child in text, use `subagent({ action: "status", id: "...", view: "transcript" })`; add `index` for a specific child in a parallel or chain run.
 
@@ -310,7 +322,7 @@ pi.events.emit("subagents:rpc:v1:request", {
 });
 ```
 
-The v1 methods are `ping`, `status`, `spawn`, `steer`, `interrupt`, `stop`, and `resume`. `status`, `steer`, `interrupt`, and `resume` reuse the normal package-owned actions. `steer` requires an async run `id` (plus optional child `index`) and a non-empty `message`; its reply preserves the normal acknowledged-delivery result. RPC steering disables the direct tool's pause-and-revive recovery so an extension keeps authority over the exact child it spawned; `ping.capabilities.nonRecoveringSteer` advertises this guarantee. `resume` requires a run target and non-empty `message`; it delegates to the existing revival path, which validates current-session ownership, persisted session/recovery metadata, stopped/live state, capability ceilings, and the exclusive session lease before returning the new async run details. Callers may request a `file-only` output path for the revived result without overriding its model, tools, or budgets. `ping.capabilities.resume` advertises this seam. `spawn` is async-only: omit `async` or set `async: true`, omit `clarify` or set `clarify: false`, and do not pass management `action` values. It goes through the same executor as the `subagent` tool, so agent discovery, validation, session attribution, configured spawn caps, child-safety depth, artifacts, and async status all behave the same. `stop` targets current-session top-level async runs through the stop control channel and records a `stopped` lifecycle instead of reporting a timeout.
+The v1 methods are `ping`, `status`, `spawn`, `steer`, `interrupt`, `stop`, and `resume`. `status`, `steer`, `interrupt`, and `resume` reuse the normal package-owned actions. When `ping.capabilities.fleetStatus` is `{ version: 1 }`, successful `status` replies additionally include `data.fleet`: `{ version: 1, entries, totalActive, omitted }`. Entries are bounded, current-session public display records with an opaque reconciliation `key`, resolved `agent`, optional `role`, `model`, `effort`, caller-facing `goal`, safe `startedAt`, and `{ input, output, total }` tokens. `totalActive` and `omitted` preserve overflow information beyond the bounded entry window. The DTO intentionally never exposes run, async, or tool IDs; clients must ignore unknown fields and fall back to status text when the capability is absent. `steer` requires an async run `id` (plus optional child `index`) and a non-empty `message`; its reply preserves the normal acknowledged-delivery result. RPC steering disables the direct tool's pause-and-revive recovery so an extension keeps authority over the exact child it spawned; `ping.capabilities.nonRecoveringSteer` advertises this guarantee. `resume` requires a run target and non-empty `message`; it delegates to the existing revival path, which validates current-session ownership, persisted session/recovery metadata, stopped/live state, capability ceilings, and the exclusive session lease before returning the new async run details. Callers may request a `file-only` output path for the revived result without overriding its model, tools, or budgets. `ping.capabilities.resume` advertises this seam. `spawn` is async-only: omit `async` or set `async: true`, omit `clarify` or set `clarify: false`, and do not pass management `action` values. It goes through the same executor as the `subagent` tool, so agent discovery, validation, session attribution, configured spawn caps, child-safety depth, artifacts, and async status all behave the same. `stop` targets current-session top-level async runs through the stop control channel and records a `stopped` lifecycle instead of reporting a timeout.
 
 `pi.events` is in-process only. It does not reach separate Pi processes or child subagents; use the file lifecycle artifacts or `pi-intercom` for cross-process coordination.
 
@@ -644,7 +656,7 @@ Common clarify keys:
 
 - `Enter` runs in the foreground, or in the background if background is toggled on
 - `Esc` cancels or backs out
-- `↑↓` moves between steps or tasks
+- `↑↓` or `j`/`k` moves between steps or tasks
 - `e` edits the task/template
 - `m` selects a model
 - `t` selects thinking level
@@ -1429,7 +1441,7 @@ subagent({ action: "doctor" })
 
 `resume` revives a paused, completed, or failed async/foreground child by starting a new child from its stored session file; stopped runs remain non-resumable, and it does not interrupt a live top-level async child. Use `steer` for acknowledged live async guidance. Multi-child async runs and remembered foreground single, parallel, or chain runs can be revived by passing `index` to choose the child. Nested runs can be resumed by nested id when their live route or persisted nested session metadata is available. Revive starts a new child process from the old session context; it does not restart the same OS process, and it requires the chosen child to have a persisted `.jsonl` session file. Direct revival takes an exclusive cross-process lease on the canonical session file until the new child finishes. A concurrent attempt fails before Pi is spawned and identifies the owning revived run; dead-owner leases are reclaimed only when staleness can be proved.
 
-`stop` ends a current-session top-level async run. It is deliberately stronger than `interrupt`: it is not a resumable pause, stopped runs should be restarted as new runs, foreground and nested targets are rejected, direct id calls execute immediately, and `/subagents-stop` without an id opens a selector with confirmation when a TUI is available. In non-TUI contexts the slash command prints exact `subagent({ action: "stop", id })` and `/subagents-stop <id>` commands. Scheduled jobs can appear in the selector, but they are labeled as scheduled cancellations and route through `schedule-cancel`, not `stop`.
+`stop` ends a current-session top-level async run. It is deliberately stronger than `interrupt`: it is not a resumable pause, stopped runs should be restarted as new runs, foreground and nested targets are rejected, direct id calls execute immediately, and `/subagents-stop` without an id opens a selector with confirmation when a TUI is available. Use `↑`/`↓` or `j`/`k` to move through that selector. In non-TUI contexts the slash command prints exact `subagent({ action: "stop", id })` and `/subagents-stop <id>` commands. Scheduled jobs can appear in the selector, but they are labeled as scheduled cancellations and route through `schedule-cancel`, not `stop`.
 
 `steer` waits up to three seconds for a correlated child-Pi input acceptance and returns a request id with `delivered`, `scheduled`, `pending`, `partial`, `recovered`, or `failed` plus per-child states. Delivery means Pi accepted the user message, not model compliance. A pending indexed child returns `scheduled`. Only a top-level single run may interrupt after the acknowledgment deadline and recover after a further 15-second pause/revival bound; chain, parallel, and nested runs never auto-interrupt. Recovery launches a replacement only after the source is confirmed paused, a valid persisted session exists, and deadline, turn, and tool budgets remain. It preserves the original child contract and remaining limits; otherwise the source stays paused with an explicit failure. Late acceptance is recorded but cannot cancel committed recovery. The persisted `steering` ledger retains 20 requests and replaces the old `steerCount`/`lastSteerAt` fields.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.37.1",
+  "version": "0.38.0",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",

package/src/agents/agents.ts

@@ -152,6 +152,8 @@ export interface AgentConfig {
 	modelSource?: AgentModelSourceInfo;
 }
 
+type ProjectRootResolution = "nearest" | "git-root";
+
 interface SubagentSettings {
 	overrides: Record<string, BuiltinAgentOverrideConfig>;
 	defaultModel?: string;
@@ -422,7 +424,7 @@ function collectSettingsPackageRoots(settingsFile: string, baseDir: string): str
 
 function collectPackageSubagentPaths(cwd: string, options: { includeUser: boolean; includeProject: boolean } = { includeUser: true, includeProject: true }): PackageSubagentPaths {
 	const agentDir = getAgentDir();
-	const projectRoot = findNearestProjectRoot(cwd) ?? cwd;
+	const projectRoot = findConfiguredProjectRoot(cwd) ?? cwd;
 	const packageRoots = [
 		projectRoot,
 	];
@@ -551,12 +553,26 @@ function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentO
 	};
 }
 
-export function findNearestProjectRoot(cwd: string): string | null {
+function isProjectRootCandidate(dir: string): boolean {
+	return isDirectory(getProjectConfigDir(dir)) || isDirectory(path.join(dir, ".agents"));
+}
+
+function findProjectRootCandidates(cwd: string): string[] {
+	const roots: string[] = [];
 	let currentDir = cwd;
 	while (true) {
-		if (isDirectory(getProjectConfigDir(currentDir)) || isDirectory(path.join(currentDir, ".agents"))) {
-			return currentDir;
-		}
+		if (isProjectRootCandidate(currentDir)) roots.push(currentDir);
+
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return roots;
+		currentDir = parentDir;
+	}
+}
+
+function findNearestGitRoot(cwd: string): string | null {
+	let currentDir = cwd;
+	while (true) {
+		if (fs.existsSync(path.join(currentDir, ".git"))) return currentDir;
 
 		const parentDir = path.dirname(currentDir);
 		if (parentDir === currentDir) return null;
@@ -564,12 +580,46 @@ export function findNearestProjectRoot(cwd: string): string | null {
 	}
 }
 
+function readProjectRootResolution(projectRoot: string): ProjectRootResolution | undefined {
+	const settingsPath = path.join(getProjectConfigDir(projectRoot), "settings.json");
+	if (!fs.existsSync(settingsPath)) return undefined;
+	const settings = readSettingsFileStrict(settingsPath);
+	const subagents = settings.subagents;
+	if (!subagents || typeof subagents !== "object" || Array.isArray(subagents)) return undefined;
+
+	const value = (subagents as Record<string, unknown>).projectRootResolution;
+	if (value === undefined) return undefined;
+	if (value === "nearest" || value === "git-root") return value;
+	throw new Error(`Subagent settings in '${settingsPath}' have invalid 'projectRootResolution'; expected 'nearest' or 'git-root'.`);
+}
+
+export function findNearestProjectRoot(cwd: string): string | null {
+	return findProjectRootCandidates(cwd)[0] ?? null;
+}
+
+function findConfiguredProjectRoot(cwd: string): string | null {
+	const candidates = findProjectRootCandidates(cwd);
+	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;
+	}
+
+	return nearestRoot;
+}
+
 function getUserAgentSettingsPath(): string {
 	return path.join(getAgentDir(), "settings.json");
 }
 
 function getProjectAgentSettingsPath(cwd: string): string | null {
-	const projectRoot = findNearestProjectRoot(cwd);
+	const projectRoot = findConfiguredProjectRoot(cwd);
 	return projectRoot ? path.join(getProjectConfigDir(projectRoot), "settings.json") : null;
 }
 
@@ -1491,7 +1541,7 @@ function isDirectory(p: string): boolean {
 }
 
 function resolveNearestProjectAgentDirs(cwd: string): { readDirs: string[]; preferredDir: string | null } {
-	const projectRoot = findNearestProjectRoot(cwd);
+	const projectRoot = findConfiguredProjectRoot(cwd);
 	if (!projectRoot) return { readDirs: [], preferredDir: null };
 
 	const legacyDir = path.join(projectRoot, ".agents");
@@ -1507,7 +1557,7 @@ function resolveNearestProjectAgentDirs(cwd: string): { readDirs: string[]; pref
 }
 
 function resolveNearestProjectChainDirs(cwd: string): { readDirs: string[]; preferredDir: string | null } {
-	const projectRoot = findNearestProjectRoot(cwd);
+	const projectRoot = findConfiguredProjectRoot(cwd);
 	if (!projectRoot) return { readDirs: [], preferredDir: null };
 
 	const preferredDir = path.join(getProjectConfigDir(projectRoot), "chains");

package/src/agents/skills.ts

@@ -379,19 +379,21 @@ function chooseHigherPrioritySkill(existing: CachedSkillEntry | undefined, candi
 	return candidate.order < existing.order ? candidate : existing;
 }
 
-function maybeReadSkillDescription(filePath: string): string | undefined {
-	try {
-		const content = fs.readFileSync(filePath, "utf-8");
-		const normalized = content.replace(/\r\n/g, "\n");
-		if (!normalized.startsWith("---")) return undefined;
+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 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, "");
+}
 
-		const frontmatter = normalized.slice(3, endIndex).trim();
-		const match = frontmatter.match(/^description:\s*(.+)$/m);
-		if (!match) return undefined;
-		return match[1]?.trim().replace(/^['\"]|['\"]$/g, "");
+function maybeReadSkillDescription(filePath: string): string | undefined {
+	try {
+		return parseSkillDescription(fs.readFileSync(filePath, "utf-8"));
 	} catch {
 		// Description parsing is best-effort metadata extraction.
 		return undefined;
@@ -585,7 +587,7 @@ function readSkill(
 
 		const raw = fs.readFileSync(skillPath, "utf-8");
 		const content = stripSkillFrontmatter(raw);
-		const description = maybeReadSkillDescription(skillPath);
+		const description = parseSkillDescription(raw);
 		const skill: ResolvedSkill = {
 			name: skillName,
 			path: skillPath,

package/src/extension/index.ts

@@ -389,6 +389,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		events: pi.events,
 		getContext: () => state.lastUiContext,
 		execute: (id, params, signal, onUpdate, ctx) => executor.execute(id, params, signal, onUpdate, ctx),
+		state,
 	});
 
 	function effectiveParallelTaskCount(tasks: Array<{ count?: unknown }> | undefined): number {
@@ -557,6 +558,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		state.lastUiContext = ctx;
 		cleanupSessionArtifacts(ctx);
 		clearPendingForegroundControlNotices(state);
+		state.foregroundControls.clear();
+		state.lastForegroundControlId = null;
 		resetJobs(ctx);
 		restoreActiveJobs(ctx);
 		scheduledRunManager.bindSession(ctx);

package/src/extension/rpc.ts

@@ -8,7 +8,9 @@ import { reconcileAsyncRun } from "../runs/background/stale-run-reconciler.ts";
 import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
 import { resolveCurrentSessionId } from "../shared/session-identity.ts";
 import {
+	type AsyncJobStep,
 	type Details,
+	type SubagentState,
 	ASYNC_DIR,
 	RESULTS_DIR,
 	SUBAGENT_ASYNC_COMPLETE_EVENT,
@@ -70,6 +72,200 @@ interface EventBus {
 	emit(event: string, data: unknown): void;
 }
 
+export interface SubagentRpcFleetEntry {
+	/** Opaque key for client-side reconciliation; never a run or async identifier. */
+	key: string;
+	/** Resolved child agent/role name. */
+	agent: string;
+	role?: string;
+	model?: string;
+	effort?: string;
+	startedAt: number;
+	tokens: { input: number; output: number; total: number };
+	goal?: string;
+}
+
+export interface SubagentRpcFleetStatus {
+	version: 1;
+	entries: SubagentRpcFleetEntry[];
+	/** Total active children before the bounded entries window. */
+	totalActive: number;
+	omitted: number;
+}
+
+const MAX_FLEET_ENTRIES = 16;
+const MAX_FLEET_CANDIDATES = 256;
+const MAX_AGENT_LENGTH = 96;
+const MAX_GOAL_LENGTH = 512;
+const MAX_METADATA_LENGTH = 128;
+
+function displayText(value: unknown, maxLength: number): string | undefined {
+	if (typeof value !== "string") return undefined;
+	// Strip complete CSI/OSC/DCS/APC/PM strings and C1 controls before collapsing
+	// whitespace; never leave CSI parameters behind after removing ESC.
+	const normalized = value.slice(0, 4_096)
+		.replace(/\x1b\[[0-?]*[ -/]*[@-~]|\x9b[0-?]*[ -/]*[@-~]|\x1b][\s\S]*?(?:\x07|\x1b\\)|\x1b[PX^_][\s\S]*?\x1b\\|[\u0000-\u001f\u007f-\u009f]/g, " ")
+		.replace(/\s+/g, " ").trim();
+	return normalized ? normalized.slice(0, maxLength) : undefined;
+}
+
+function publicTokens(value: unknown): { input: number; output: number; total: number } {
+	const record = isRecord(value) ? value : {};
+	const count = (field: "input" | "output" | "total") => {
+		const raw = record[field];
+		return typeof raw === "number" && Number.isFinite(raw) && raw >= 0
+			? Math.min(Number.MAX_SAFE_INTEGER, Math.floor(raw))
+			: 0;
+	};
+	const input = count("input");
+	const output = count("output");
+	const sum = Math.min(Number.MAX_SAFE_INTEGER, input + output);
+	return { input, output, total: Math.max(sum, count("total")) };
+}
+
+function activeState(value: unknown): boolean {
+	return value === "running" || value === "queued" || value === "pending";
+}
+
+interface FleetKeyState {
+	sessionId: string | null;
+	next: number;
+	keys: Map<string, string>;
+}
+
+interface FleetCandidate {
+	internalKey: string;
+	agent: unknown;
+	role?: unknown;
+	model?: unknown;
+	effort?: unknown;
+	startedAt: unknown;
+	tokens?: unknown;
+	goal?: unknown;
+}
+
+function buildFleetStatus(
+	state: SubagentState | undefined,
+	keyState: FleetKeyState,
+	sessionId: string | null | undefined,
+): SubagentRpcFleetStatus {
+	const authoritativeSessionId = sessionId ?? null;
+	if (keyState.sessionId !== authoritativeSessionId) {
+		keyState.sessionId = authoritativeSessionId;
+		keyState.next = 0;
+		keyState.keys.clear();
+	}
+	if (!state || !authoritativeSessionId || state.currentSessionId !== authoritativeSessionId) {
+		keyState.keys.clear();
+		return { version: 1, entries: [], totalActive: 0, omitted: 0 };
+	}
+
+	let totalActive = 0;
+	const candidates: FleetCandidate[] = [];
+	const addCandidate = (candidate: FleetCandidate) => {
+		totalActive += 1;
+		if (candidates.length < MAX_FLEET_CANDIDATES) candidates.push(candidate);
+	};
+	for (const control of state.foregroundControls.values()) {
+		if (control.sessionId !== authoritativeSessionId) continue;
+		if (control.activeChildren?.size) {
+			for (const child of control.activeChildren.values()) addCandidate({
+				internalKey: `foreground:${control.runId}:${child.index}`,
+				agent: child.agent,
+				model: child.model,
+				effort: child.thinking,
+				startedAt: child.startedAt,
+				tokens: { input: child.inputTokens ?? 0, output: child.outputTokens ?? 0, total: child.tokens ?? 0 },
+				goal: child.description ?? control.description,
+			});
+		} else {
+			addCandidate({
+				internalKey: `foreground:${control.runId}:${control.currentIndex ?? 0}`,
+				agent: control.currentAgent ?? control.mode,
+				model: control.model,
+				effort: control.thinking,
+				startedAt: control.startedAt,
+				tokens: { input: control.inputTokens ?? 0, output: control.outputTokens ?? 0, total: control.tokens ?? 0 },
+				goal: control.description,
+			});
+		}
+	}
+	for (const job of state.asyncJobs.values()) {
+		if (job.sessionId !== authoritativeSessionId || !activeState(job.status)) continue;
+		const startedAt = job.startedAt ?? job.updatedAt;
+		const steps: AsyncJobStep[] | undefined = job.steps?.length
+			? job.steps
+			: job.agents?.map((agent, index) => ({
+				agent,
+				index,
+				status: job.status === "queued" ? "pending" : "running",
+			}));
+		if (!steps?.length) {
+			addCandidate({
+				internalKey: `async:${job.asyncId}`,
+				agent: job.mode ?? "subagent",
+				startedAt,
+				tokens: job.totalTokens,
+				goal: job.description,
+			});
+			continue;
+		}
+		for (const [offset, step] of steps.entries()) {
+			if (!activeState(step.status)) continue;
+			const index = step.index ?? offset;
+			if (step.status === "pending" && job.mode === "chain" && !job.activeParallelGroup && index !== (job.currentStep ?? 0)) continue;
+			addCandidate({
+				internalKey: `async:${job.asyncId}:${index}`,
+				agent: step.agent,
+				role: step.label,
+				model: step.model,
+				effort: step.thinking,
+				startedAt: step.startedAt ?? startedAt,
+				tokens: step.tokens ?? (steps.length === 1 ? job.totalTokens : undefined),
+				goal: job.description,
+			});
+		}
+	}
+
+	candidates.sort((left, right) => {
+		const leftStarted = typeof left.startedAt === "number" ? left.startedAt : Number.MAX_SAFE_INTEGER;
+		const rightStarted = typeof right.startedAt === "number" ? right.startedAt : Number.MAX_SAFE_INTEGER;
+		return leftStarted - rightStarted || left.internalKey.localeCompare(right.internalKey);
+	});
+	const activeKeys = new Set(candidates.map((candidate) => candidate.internalKey));
+	const entries: SubagentRpcFleetEntry[] = [];
+	for (const candidate of candidates) {
+		if (entries.length >= MAX_FLEET_ENTRIES) break;
+		const agent = displayText(candidate.agent, MAX_AGENT_LENGTH);
+		const startedAt = candidate.startedAt;
+		if (!agent || typeof startedAt !== "number" || !Number.isSafeInteger(startedAt) || startedAt < 0) continue;
+		let key = keyState.keys.get(candidate.internalKey);
+		if (!key) {
+			key = `fleet-${++keyState.next}`;
+			keyState.keys.set(candidate.internalKey, key);
+		}
+		const role = displayText(candidate.role, MAX_AGENT_LENGTH);
+		const model = displayText(candidate.model, MAX_METADATA_LENGTH);
+		const effort = displayText(candidate.effort, MAX_METADATA_LENGTH);
+		const goal = displayText(candidate.goal, MAX_GOAL_LENGTH);
+		entries.push({
+			key,
+			agent,
+			...(role ? { role } : {}),
+			...(model ? { model } : {}),
+			...(effort ? { effort } : {}),
+			startedAt,
+			tokens: publicTokens(candidate.tokens),
+			...(goal ? { goal } : {}),
+		});
+	}
+	for (const internalKey of keyState.keys.keys()) {
+		if (!activeKeys.has(internalKey)) keyState.keys.delete(internalKey);
+	}
+	const omitted = Math.max(0, totalActive - entries.length);
+	return { version: 1, entries, totalActive, omitted };
+}
+
 interface RegisterSubagentRpcBridgeOptions {
 	events: EventBus;
 	getContext: () => ExtensionContext | null;
@@ -84,6 +280,8 @@ interface RegisterSubagentRpcBridgeOptions {
 	resultsDir?: string;
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 	now?: () => number;
+	/** Native live state, projected into the optional public fleet-status capability. */
+	state?: SubagentState;
 }
 
 class SubagentRpcError extends Error {
@@ -141,7 +339,9 @@ function textFromToolResult(result: AgentToolResult<Details>): string {
 		.join("\n");
 }
 
-function dataFromToolResult(result: AgentToolResult<Details>): { text: string; details?: Details; isError?: boolean } {
+type ToolResultWithError = AgentToolResult<Details> & { isError?: boolean };
+
+function dataFromToolResult(result: ToolResultWithError): { text: string; details?: Details; isError?: boolean } {
 	return {
 		text: textFromToolResult(result),
 		...(result.details ? { details: result.details } : {}),
@@ -149,7 +349,7 @@ function dataFromToolResult(result: AgentToolResult<Details>): { text: string; d
 	};
 }
 
-function failIfToolError(result: AgentToolResult<Details>): void {
+function failIfToolError(result: ToolResultWithError): void {
 	if (!result.isError) return;
 	throw new SubagentRpcError("execution_failed", textFromToolResult(result) || "Subagent RPC execution failed.");
 }
@@ -179,6 +379,7 @@ function pingData(ctx: ExtensionContext | null) {
 		methods: [...SUBAGENT_RPC_METHODS],
 		capabilities: {
 			status: true,
+			fleetStatus: { version: 1 },
 			asyncSpawn: true,
 			steer: true,
 			nonRecoveringSteer: true,
@@ -324,6 +525,7 @@ function stopAsyncRun(
 async function handleRequest(
 	request: SubagentRpcRequestEnvelope,
 	options: RegisterSubagentRpcBridgeOptions,
+	fleetKeys: FleetKeyState,
 ): Promise<unknown> {
 	const ctx = options.getContext();
 	if (request.method === "ping") return pingData(ctx);
@@ -333,7 +535,21 @@ async function handleRequest(
 		return executeChecked(options, ctx, request.requestId, request.method, spawnParams(request.params));
 	}
 	if (request.method === "status") {
-		return executeChecked(options, ctx, request.requestId, request.method, { action: "status", ...normalizeTargetParams(request.params, "status") });
+		const status = await executeChecked(
+			options,
+			ctx,
+			request.requestId,
+			request.method,
+			{ action: "status", ...normalizeTargetParams(request.params, "status") },
+		);
+		return {
+			...status,
+			fleet: buildFleetStatus(
+				options.state,
+				fleetKeys,
+				resolveCurrentSessionId(ctx.sessionManager),
+			),
+		};
 	}
 	if (request.method === "steer") {
 		return executeChecked(options, ctx, request.requestId, request.method, steerParams(request.params));
@@ -400,11 +616,12 @@ export function registerSubagentRpcBridge(options: RegisterSubagentRpcBridgeOpti
 	emitReady: (ctx?: ExtensionContext | null) => void;
 	dispose: () => void;
 } {
+	const fleetKeys: FleetKeyState = { sessionId: null, next: 0, keys: new Map() };
 	const unsubscribe = options.events.on(SUBAGENT_RPC_REQUEST_EVENT, async (raw) => {
 		let request: SubagentRpcRequestEnvelope | undefined;
 		try {
 			request = parseRequest(raw);
-			const data = await handleRequest(request, options);
+			const data = await handleRequest(request, options, fleetKeys);
 			options.events.emit(subagentRpcReplyEvent(request.requestId), {
 				version: SUBAGENT_RPC_PROTOCOL_VERSION,
 				requestId: request.requestId,

package/src/extension/schemas.ts

@@ -65,6 +65,18 @@ const JsonSchemaObject = Type.Unsafe({
 	description: "JSON Schema object for strict structured output. Non-object roots are rejected.",
 });
 
+const AcceptanceEvidenceKinds = [
+	"changed-files",
+	"tests-added",
+	"commands-run",
+	"validation-output",
+	"residual-risks",
+	"no-staged-files",
+	"diff-summary",
+	"review-findings",
+	"manual-notes",
+];
+
 const AcceptanceOverride = Type.Unsafe({
 	anyOf: [
 		{ type: "string", enum: ["auto", "attested", "checked", "verified"] },
@@ -77,7 +89,7 @@ const AcceptanceOverride = Type.Unsafe({
 		{ type: "boolean", enum: [false] },
 		{ type: "object", additionalProperties: true },
 	],
-	description: "Optional acceptance policy. For reviewer/read-only calls, omit acceptance. Evidence levels end at verified; require independent review with acceptance.review.required. The value reviewed is an achieved status and is accepted by the schema only for actionable preflight recovery. In the current/default contract, omitted means auto-inferred. With agentContract.version=1, omitted means not requested and acceptance failures are reported separately from execution.",
+	description: `Optional acceptance policy. For reviewer/read-only calls, omit acceptance. Example: { level: "checked", evidence: ["commands-run", "changed-files"] }. Supported evidence kinds: ${AcceptanceEvidenceKinds.join(", ")}. Evidence levels end at verified; use acceptance.review.required for review. Omitted means auto-inferred unless agentContract.version=1.`,
 });
 
 const AgentContractOverride = Type.Object({

package/src/intercom/intercom-bridge.ts

@@ -16,6 +16,7 @@ function defaultSubagentConfigDir(agentDir = defaultAgentDir()): string {
 }
 
 const DEFAULT_INTERCOM_TARGET_PREFIX = "subagent-chat";
+export const PI_INTERCOM_SESSION_ID_ENV = "PI_INTERCOM_SESSION_ID";
 export const INTERCOM_BRIDGE_MARKER = "Intercom orchestration channel:";
 const DEFAULT_INTERCOM_BRIDGE_TEMPLATE = `The inherited thread is reference-only. Do not continue that conversation or send questions, status updates, or completion handoffs to the supervisor in normal assistant text.
 
@@ -56,10 +57,11 @@ interface ResolveIntercomBridgeInput {
 	agentDir?: string;
 }
 
-export function resolveIntercomSessionTarget(sessionName: string | undefined, sessionId: string): string {
+export function resolveIntercomSessionTarget(sessionName: string | undefined, sessionId: string, intercomSessionId = process.env[PI_INTERCOM_SESSION_ID_ENV]): string {
 	const trimmedName = sessionName?.trim();
 	if (trimmedName) return trimmedName;
-	const normalizedSessionId = sessionId.startsWith("session-") ? sessionId.slice("session-".length) : sessionId;
+	const fallbackSessionId = intercomSessionId?.trim() || sessionId;
+	const normalizedSessionId = fallbackSessionId.startsWith("session-") ? fallbackSessionId.slice("session-".length) : fallbackSessionId;
 	return `${DEFAULT_INTERCOM_TARGET_PREFIX}-${normalizedSessionId.slice(0, 8)}`;
 }