@ian-pascoe/pi-minimal-subagents 0.6.5 → 0.7.0

package/README.md

@@ -29,7 +29,7 @@ filter in `~/.pi/agent/settings.json` using the repository-relative path:
 ```
 
 From this package checkout, load the source directly with
-`pi -e ./src/index.ts`. Requires Node `>=22.19.0` and Pi `>=0.84.1`.
+`pi -e ./src/index.ts`. Requires Node `>=22.19.0` and Pi `>=0.85.1`.
 
 ## Configuration
 
@@ -251,14 +251,38 @@ source file; it never substitutes the source session's newer head.
 
 ## Status and TUI
 
-In TUI mode, `/subagents status` opens a live read-only hierarchy. Rows begin
-collapsed; use Up/Down to select, Enter to expand Recent Activity, the configured
-tool-expansion key to reveal tool output, page keys to scroll, and Escape to
-close. Expanded activity uses Pi's transcript components, updates once per
-second, remains bounded, and omits images. The header reports the effective
-access source, authored settings, direct running/idle counts, and actual
-Coordinator Tool activation. Partial external activation is reported as
-`N/6 active`; status does not repair it.
+In TUI mode, `/subagents` or `/subagents status` opens a large, centered,
+framed overlay. Up/Down selects a Child Agent; Enter opens its Child Session
+Transcript. Escape returns to the tree, then Escape closes the overlay. The
+viewer is read-only: Root Agent input and ongoing agent work remain intact.
+
+Two consecutive Left Arrow presses within 500 ms open the same viewer when
+the main editor is focused and completely empty. Drafts (including whitespace),
+dialogs, and other overlays retain normal navigation. Explicit key-repeat
+reports are ignored; legacy terminals cannot distinguish holding Left from
+two presses.
+
+The viewer and compact widget prioritize sibling subtrees containing running
+Child Agents. Idle ancestors move with active descendants, parents stay above
+their children, and equally active siblings retain their original order. Viewer
+selection follows the Child Agent's identity through live reordering.
+
+The transcript includes inherited context, earlier turns, pre-compaction
+messages, and live output on the selected saved branch. Abandoned branches and
+internal bookkeeping are excluded. Saved history can be inspected without
+restoring a runtime; missing or unverified sessions report an explanation rather
+than substituting another branch. Model-facing Recent Activity remains bounded.
+
+Transcripts open at the latest output and refresh once per second. Up/Down
+scrolls by line, Page Up/Page Down by page. Scrolling up pauses following; End
+returns to live output. Reading position is retained through resize and tool
+expansion. Reasoning is visible, tool output starts collapsed, and Pi's configured
+tool-expansion key (normally Ctrl+O) reveals it. Images appear as explicit text
+placeholders rather than inline images.
+
+The tree header reports the effective access source, authored settings, direct
+running/idle counts, and actual Coordinator Tool activation. Partial external
+activation is reported as `N/6 active`; status does not repair it.
 
 RPC mode receives a concise status notification. JSON and print modes produce
 no observer-only output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [

package/src/minimal-subagents-config.ts

@@ -1,4 +1,3 @@
-import type { JsonValue } from "@earendil-works/pi-ai";
 import type { SettingsManager } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
@@ -7,16 +6,18 @@ import { DEFAULT_MAX_SUBAGENT_DEPTH, THINKING_LEVELS } from "./minimal-subagents
 const MODEL_ROLE_NAME_MAX_LENGTH = 64;
 const MODEL_ROLE_HINT_MAX_LENGTH = 500;
 
-const JsonValueSchema = Type.Unsafe<JsonValue>({});
 const SettingsDocumentSchema = Type.Object({
-  minimalSubagents: Type.Optional(JsonValueSchema),
+  minimalSubagents: Type.Optional(Type.Unknown()),
 });
 const MinimalSubagentsSettingsSchema = Type.Object({
-  enabled: Type.Optional(JsonValueSchema),
-  maxSubagentDepth: Type.Optional(JsonValueSchema),
-  modelRoles: Type.Optional(JsonValueSchema),
+  enabled: Type.Optional(Type.Unknown()),
+  maxSubagentDepth: Type.Optional(Type.Unknown()),
+  modelRoles: Type.Optional(Type.Unknown()),
+});
+const ModelRoleObjectSchema = Type.Object({
+  model: Type.Optional(Type.Unknown()),
+  hint: Type.Optional(Type.Unknown()),
 });
-const JsonObjectSchema = Type.Record(Type.String(), JsonValueSchema);
 const EnabledSettingSchema = Type.Boolean();
 const PositiveSafeIntegerSchema = Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
 const MaxSubagentDepthSettingSchema = Type.Union([PositiveSafeIntegerSchema, Type.Null()]);
@@ -28,7 +29,7 @@ const ExpandedModelRoleSchema = Type.Object(
   },
   { additionalProperties: false },
 );
-const ModelRoleEntriesSchema = Type.Record(Type.String(), JsonValueSchema);
+const ModelRoleEntriesSchema = Type.Record(Type.String(), Type.Unknown());
 const ModelRolesSettingSchema = Type.Union([ModelRoleEntriesSchema, Type.Null()]);
 
 type ModelRoleThinkingLevel = (typeof THINKING_LEVELS)[number];
@@ -61,7 +62,7 @@ export interface ResolvedMinimalSubagentsConfig {
 }
 
 interface MinimalSubagentsSettingsDocument {
-  minimalSubagents?: JsonValue;
+  minimalSubagents?: unknown;
 }
 
 interface MinimalSubagentsConfigInput {
@@ -102,7 +103,7 @@ type ModelRoleWireValue =
   | { kind: "delete" }
   | { kind: "shorthand"; model: string }
   | { kind: "expanded"; fields: Static<typeof ExpandedModelRoleSchema> }
-  | { kind: "malformed-expanded"; fields: Record<string, JsonValue> }
+  | { kind: "malformed-expanded"; fields: Static<typeof ModelRoleObjectSchema> }
   | { kind: "invalid" };
 
 type ModelRolesWireValue =
@@ -110,15 +111,17 @@ type ModelRolesWireValue =
   | { kind: "entries"; entries: ReadonlyMap<string, ModelRoleWireValue> }
   | { kind: "invalid" };
 
-function parseMaxSubagentDepthWireValue(value: JsonValue): MaxSubagentDepthWireValue {
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- Authored settings remain unparsed until the depth schema below validates their value.
+function parseMaxSubagentDepthWireValue(value: unknown): MaxSubagentDepthWireValue {
   if (!Value.Check(MaxSubagentDepthSettingSchema, value)) return { kind: "invalid" };
   return value === null ? { kind: "reset" } : { kind: "depth", value };
 }
 
-function parseModelRoleWireValue(value: JsonValue): ModelRoleWireValue {
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- Role entries may contain arbitrary settings data; schemas classify them before model/hint validation.
+function parseModelRoleWireValue(value: unknown): ModelRoleWireValue {
   if (value === null) return { kind: "delete" };
   if (Value.Check(ShorthandModelRoleSchema, value)) return { kind: "shorthand", model: value };
-  if (Value.Check(JsonObjectSchema, value)) {
+  if (Value.Check(ModelRoleObjectSchema, value)) {
     return Value.Check(ExpandedModelRoleSchema, value)
       ? { kind: "expanded", fields: value }
       : { kind: "malformed-expanded", fields: value };
@@ -132,7 +135,8 @@ function isExpandedModelRoleWireValue(
   return value.kind === "expanded" || value.kind === "malformed-expanded";
 }
 
-function parseModelRolesWireValue(value: JsonValue): ModelRolesWireValue {
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- Validate the authored role collection before parsing each untrusted entry.
+function parseModelRolesWireValue(value: unknown): ModelRolesWireValue {
   if (!Value.Check(ModelRolesSettingSchema, value)) return { kind: "invalid" };
   if (value === null) return { kind: "reset" };
   return {

package/src/minimal-subagents-context.ts

@@ -8,8 +8,6 @@ import type {
 } from "./minimal-subagents-types.js";
 
 const RECENT_AGENT_ACTIVITY_LIMIT = 12;
-const CHILD_AGENT_TRANSCRIPT_MESSAGE_LIMIT = 24;
-const CHILD_AGENT_TRANSCRIPT_PAIR_WINDOW = CHILD_AGENT_TRANSCRIPT_MESSAGE_LIMIT * 2;
 const RECENT_AGENT_ACTIVITY_MAX_LINES = 20;
 const RECENT_AGENT_ACTIVITY_MAX_BYTES = 2 * 1024;
 
@@ -47,110 +45,45 @@ function visibleMessageContent(content: string | readonly (TextContent | ImageCo
   return contentText(content, "\n\n") || "(no text content)";
 }
 
-function omitAgentMessageImages(message: AgentMessage): AgentMessage {
+function replaceAgentMessageImages(message: AgentMessage): AgentMessage {
   if (message.role === "user" || message.role === "custom") {
     return {
       ...structuredClone(message),
       content: Array.isArray(message.content)
-        ? message.content
-            .filter((content) => content.type !== "image")
-            .map((content) => structuredClone(content))
+        ? message.content.map((content) =>
+            content.type === "image"
+              ? { type: "text" as const, text: `[Image: ${content.mimeType}]` }
+              : structuredClone(content),
+          )
         : message.content,
     };
   }
   if (message.role === "toolResult") {
     return {
       ...structuredClone(message),
-      content: message.content
-        .filter((content) => content.type !== "image")
-        .map((content) => structuredClone(content)),
+      content: message.content.map((content) =>
+        content.type === "image"
+          ? { type: "text" as const, text: `[Image: ${content.mimeType}]` }
+          : structuredClone(content),
+      ),
     };
   }
   return structuredClone(message);
 }
 
-interface IndexedTranscriptMessage {
-  message: AgentMessage;
-  originalIndex: number;
-  streaming: boolean;
-}
-
-/** Select at most 48 recent raw messages, retaining cross-cutoff tool pairs and omitting images. */
+/** Clone the complete visible UI transcript, replacing images without bounding conversation history. */
 export function selectChildAgentTranscript(
   messages: readonly AgentMessage[],
   streamingAssistantMessage?: AgentMessage,
 ): ChildAgentTranscriptSnapshot {
-  const pairWindow = messages.slice(-CHILD_AGENT_TRANSCRIPT_PAIR_WINDOW);
-  const firstWindowIndex = messages.length - pairWindow.length;
-  const indexed: IndexedTranscriptMessage[] = [
-    ...pairWindow.map((message, windowIndex) => ({
-      message,
-      originalIndex: firstWindowIndex + windowIndex,
-      streaming: false,
-    })),
-    ...(streamingAssistantMessage
-      ? [
-          {
-            message: streamingAssistantMessage,
-            originalIndex: messages.length,
-            streaming: true,
-          },
-        ]
-      : []),
-  ];
-  const tail = indexed.slice(-CHILD_AGENT_TRANSCRIPT_MESSAGE_LIMIT).map((item) => ({
-    ...item,
-    message: omitAgentMessageImages(item.message),
-  }));
-  const selectedIndexes = new Set(tail.map(({ originalIndex }) => originalIndex));
-  const calls = new Map<
-    string,
-    { originalIndex: number; assistant: Extract<AgentMessage, { role: "assistant" }> }
-  >();
-  for (const item of indexed) {
-    if (item.message.role !== "assistant") continue;
-    for (const content of item.message.content) {
-      if (content.type === "toolCall") {
-        calls.set(content.id, { originalIndex: item.originalIndex, assistant: item.message });
-      }
-    }
-  }
-
-  const retained = tail.filter(
-    (item) => item.message.role !== "toolResult" || calls.has(item.message.toolCallId),
-  );
-  const missingCalls = new Map<
-    number,
-    { assistant: Extract<AgentMessage, { role: "assistant" }>; callIds: Set<string> }
-  >();
-  for (const item of retained) {
-    if (item.message.role !== "toolResult") continue;
-    const call = calls.get(item.message.toolCallId);
-    if (!call || selectedIndexes.has(call.originalIndex)) continue;
-    const missing = missingCalls.get(call.originalIndex) ?? {
-      assistant: call.assistant,
-      callIds: new Set<string>(),
-    };
-    missing.callIds.add(item.message.toolCallId);
-    missingCalls.set(call.originalIndex, missing);
-  }
-  const prefixes: IndexedTranscriptMessage[] = [...missingCalls.entries()]
-    .sort(([left], [right]) => left - right)
-    .map(([originalIndex, missing]) => ({
-      message: {
-        ...structuredClone(missing.assistant),
-        content: missing.assistant.content
-          .filter((content) => content.type === "toolCall" && missing.callIds.has(content.id))
-          .map((content) => structuredClone(content)),
-      },
-      originalIndex,
-      streaming: false,
-    }));
-  const selected = [...prefixes, ...retained];
-  const streamingAssistantIndex = selected.findIndex(({ streaming }) => streaming);
+  const visible = messages.filter((message) => message.role !== "custom" || message.display);
+  const streaming = streamingAssistantMessage && !messages.includes(streamingAssistantMessage);
   return {
-    messages: selected.map(({ message }) => message),
-    streamingAssistantIndex: streamingAssistantIndex >= 0 ? streamingAssistantIndex : undefined,
+    messages: [
+      ...visible.map(replaceAgentMessageImages),
+      ...(streaming ? [replaceAgentMessageImages(streamingAssistantMessage)] : []),
+    ],
+    streamingAssistantIndex: streaming ? visible.length : undefined,
     toolDefinitions: [],
   };
 }

package/src/minimal-subagents-coordinator.ts

@@ -452,14 +452,22 @@ export class MinimalSubagentsCoordinator {
     };
   }
 
-  /** Lazily inspect one Child Agent's bounded process-local transcript for trusted UI. */
+  /** Lazily inspect one Child Session Transcript without restoring a missing runtime. */
   inspectTranscript(agentId: string): ChildAgentTranscriptSnapshot {
     const agent = this.requireAgent(agentId);
     const runtime = this.runtimes.get(agentId);
     const liveSnapshot = runtime?.snapshotActivityTranscript?.();
     if (liveSnapshot) return liveSnapshot;
     if (runtime) return selectChildAgentTranscript(runtime.snapshotActivityMessages());
+    let historyError: string | undefined;
+    try {
+      const saved = this.dependencies.sessions.readTranscript?.(agent);
+      if (saved) return saved;
+    } catch (error) {
+      historyError = error instanceof Error ? error.message : String(error);
+    }
     const fallback =
+      historyError ||
       agent.unavailable_reason ||
       agent.latest_result?.error ||
       agent.latest_result?.output ||

package/src/minimal-subagents-extension.ts

@@ -2,6 +2,7 @@ import { fileURLToPath } from "node:url";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import {
   buildSessionContext,
+  CustomEditor,
   getAgentDir,
   SessionManager,
   SettingsManager,
@@ -9,6 +10,7 @@ import {
   type ExtensionCommandContext,
   type ExtensionContext,
   type ExtensionFactory,
+  type ExtensionUIContext,
   type MessageEndEvent,
   type SessionBeforeForkEvent,
   type SessionEntry,
@@ -16,6 +18,7 @@ import {
   type SessionStartEvent,
   type SessionTreeEvent,
 } from "@earendil-works/pi-coding-agent";
+import { isKeyRelease, isKeyRepeat, matchesKey } from "@earendil-works/pi-tui";
 import {
   createSubagentAccessBranchRecord,
   reconcileCoordinatorToolAccess,
@@ -393,6 +396,80 @@ const productionLifecycleEffects: MinimalSubagentsLifecycleEffects = {
   createSessionFactory: (options) => new PiAgentSessionFactory(options),
 };
 
+/** Compose a focus-local key sequence without taking over the editor's other behavior. */
+function installViewerShortcut(ui: ExtensionUIContext, open: () => void) {
+  const previous = ui.getEditorComponent();
+  let active = true;
+  let previousLeftAt: number | undefined;
+  const reset = () => {
+    previousLeftAt = undefined;
+  };
+  const factory: NonNullable<ReturnType<ExtensionUIContext["getEditorComponent"]>> = (
+    tui,
+    theme,
+    keybindings,
+  ) => {
+    reset();
+    const editor =
+      previous?.(tui, theme, keybindings) ??
+      new CustomEditor(tui, theme, keybindings, { embedWorkingStatus: true });
+    let focused = false;
+    const handleInput = (data: string) => {
+      if (isKeyRelease(data)) {
+        editor.handleInput(data);
+        return;
+      }
+      if (
+        active &&
+        focused &&
+        editor.getText() === "" &&
+        matchesKey(data, "left") &&
+        !isKeyRepeat(data)
+      ) {
+        const now = performance.now();
+        if (previousLeftAt !== undefined && now - previousLeftAt <= 500) {
+          reset();
+          open();
+          return;
+        }
+        previousLeftAt = now;
+      } else {
+        reset();
+      }
+      editor.handleInput(data);
+    };
+    // Forward the editor's complete interface, including app handlers and custom methods.
+    // Binding to the original instance also preserves private fields in custom editors.
+    return new Proxy(editor, {
+      has: (target, property) => property === "focused" || Reflect.has(target, property),
+      get(target, property) {
+        if (property === "focused") return focused;
+        if (property === "handleInput") return handleInput;
+        // oxlint-disable-next-line anti-slop/no-reflect-get -- SAFETY: Forward the SDK editor's open interface, including other extensions' methods, without replacing their receiver.
+        const value = Reflect.get(target, property, target);
+        // oxlint-disable-next-line anti-slop/no-runtime-typeof -- SAFETY: Proxy forwarding binds callable members; this is not parsing external input.
+        return typeof value === "function" ? value.bind(target) : value;
+      },
+      set(target, property, value) {
+        if (property === "focused") {
+          focused = value;
+          if (!focused) reset();
+        }
+        return Reflect.set(target, property, value, target);
+      },
+    });
+  };
+  ui.setEditorComponent(factory);
+  return {
+    reset,
+    dispose() {
+      active = false;
+      reset();
+      if (ui.getEditorComponent() === factory) ui.setEditorComponent(previous);
+    },
+  };
+}
+
 /** Own coordinator, UI, and prepared-fork state for one root Pi session lifecycle. */
 export class MinimalSubagentsLifecycleController {
   private coordinator: MinimalSubagentsCoordinator | undefined;
@@ -407,6 +484,7 @@ export class MinimalSubagentsLifecycleController {
   };
   private uiController: MinimalSubagentsUiController | undefined;
   private statusPanelController: MinimalSubagentsStatusPanelController | undefined;
+  private viewerShortcut: ReturnType<typeof installViewerShortcut> | undefined;
   private accessSession: ActiveSubagentAccessSession | undefined;
   private preparedFork:
     | { sourceSessionFile: string; selectedBranchSnapshot: RegistrySnapshot }
@@ -619,6 +697,14 @@ export class MinimalSubagentsLifecycleController {
       () => this.currentSubagentStatusAccess(),
     );
 
+    this.viewerShortcut?.dispose();
+    this.viewerShortcut =
+      context.mode === "tui"
+        ? installViewerShortcut(context.ui, () => {
+            void this.statusPanelController?.open();
+          })
+        : undefined;
+
     if (hasHistoricalChildIdentity(context.sessionManager.getBranch())) {
       context.ui.notify(
         "Opened a former subagent session directly. It is now an independent root; former descendants and parent messaging were not restored. Concurrent ownership by its original root is unsupported.",
@@ -666,6 +752,7 @@ export class MinimalSubagentsLifecycleController {
     _event: SessionTreeEvent,
     context: ExtensionContext,
   ): Promise<void> {
+    this.viewerShortcut?.reset();
     if (!this.coordinator) return;
     const snapshot = replayRegistryEntries(
       context.sessionManager.getBranch(),
@@ -805,6 +892,8 @@ export class MinimalSubagentsLifecycleController {
     event: SessionShutdownEvent,
     context: ExtensionContext,
   ): Promise<void> {
+    this.viewerShortcut?.dispose();
+    this.viewerShortcut = undefined;
     this.statusPanelController?.dispose();
     this.statusPanelController = undefined;
     if (this.coordinator) {

package/src/minimal-subagents-fork-lifecycle.ts

@@ -2,7 +2,7 @@ import type { ForkSnapshot } from "./minimal-subagents-types.js";
 import { canonicalPath } from "./minimal-subagents-paths.js";
 
 declare global {
-  // eslint-disable-next-line no-var -- A process-global handoff must be visible to replacement extension instances.
+  // A process-global handoff must be visible to replacement extension instances.
   var minimalSubagentsForkSnapshots: Map<string, ForkSnapshot> | undefined;
 }
 

package/src/minimal-subagents-registry-wire.ts

@@ -1,9 +1,5 @@
-import type { JsonValue } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
 
-/** Establishes Pi's recursive JSON owner type before Registry envelope parsing. */
-export const RegistryJsonValueWireSchema = Type.Unsafe<JsonValue>({});
-
 const NonnegativeNumberSchema = Type.Number({ minimum: 0 });
 const NonEmptyStringSchema = Type.String({ minLength: 1 });
 const TurnStatusSchema = Type.Union([

package/src/minimal-subagents-registry.ts

@@ -28,7 +28,6 @@ import {
   RegistryDeliveryTurnEventWireSchema,
   RegistryEnvelopeWireSchema,
   RegistryEventDiscriminantWireSchema,
-  RegistryJsonValueWireSchema,
   RegistryLooseEnvelopeWireSchema,
   RegistryMessageRecordedEventWireSchema,
   RegistryRootProbeWireSchema,
@@ -846,7 +845,8 @@ function validParsedEvent(event: RegistryEventV2): ParsedRegistryEvent {
 type RegistryParseInput = JsonValue | RegistryEventV2;
 
 function parseRegistryEventRecord(
-  value: RegistryParseInput,
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Registry entry data is unparsed; ownership is checked first, then envelope and event schemas validate every consumed field.
+  value: unknown,
   rootSessionId: string,
 ): ParsedRegistryEvent {
   if (Value.Check(RegistryRootProbeWireSchema, value) && value.root_session_id !== rootSessionId) {
@@ -1191,10 +1191,6 @@ export function replayRegistryEntries(
   const diagnostics: RegistryReplayDiagnostic[] = [];
   entries.forEach((entry, entryIndex) => {
     if (entry.type !== "custom" || entry.customType !== REGISTRY_ENTRY_TYPE) return;
-    if (!Value.Check(RegistryJsonValueWireSchema, entry.data)) {
-      reportDiagnostic(diagnostics, entryIndex, "invalid-envelope", "record must be JSON");
-      return;
-    }
     const parsed = parseRegistryEventRecord(entry.data, rootSessionId);
     if (parsed.kind === "foreign-root") return;
     if (parsed.kind === "event") {

package/src/minimal-subagents-render-contract.ts

@@ -1,8 +1,4 @@
-import type {
-  AgentToolResult,
-  MessageRenderer,
-  ToolDefinition,
-} from "@earendil-works/pi-coding-agent";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 import { Value } from "typebox/value";
 import { COORDINATOR_TOOL_NAMES } from "./minimal-subagents-capabilities.js";
@@ -339,8 +335,6 @@ export type RenderStatusAgent = Static<typeof RenderStatusAgentSchema>;
 /** Raw tool arguments supplied by Pi's tool-rendering interface. */
 export type CoordinatorToolCallInput = Parameters<NonNullable<ToolDefinition["renderCall"]>>[0];
 
-type CoordinatorMessageInput = Parameters<MessageRenderer>[0];
-
 /** Parsed tool-call arguments tagged by their coordinator tool name. */
 export type ParsedCoordinatorToolCall =
   | { toolName: "subagent"; args: SpawnCallArguments }
@@ -383,7 +377,8 @@ export function parseCoordinatorToolCall(
 /** Parse one historical tool result exactly once at the transcript rendering boundary. */
 export function parseCoordinatorToolResult(
   toolName: CoordinatorToolName,
-  details: AgentToolResult<unknown>["details"],
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Historical tool details are unparsed until the selected per-tool schema checks them below.
+  details: unknown,
 ): ParsedCoordinatorToolResult | undefined {
   switch (toolName) {
     case "subagent":
@@ -417,7 +412,8 @@ export type CoordinatorMessageRenderDetails = Static<typeof CoordinatorMessageRe
 
 /** Parse optional custom-message details while tolerating legacy field names. */
 export function parseCoordinatorMessageDetails(
-  details: CoordinatorMessageInput["details"],
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Historical custom-message metadata is validated by its owning schema below.
+  details: unknown,
 ): CoordinatorMessageRenderDetails | undefined {
   return Value.Check(CoordinatorMessageRenderDetailsSchema, details) ? details : undefined;
 }

package/src/minimal-subagents-rendering.ts

@@ -39,6 +39,7 @@ import {
   type WaitRenderDetails,
 } from "./minimal-subagents-render-contract.js";
 import { stripCoordinatorMessageEnvelope } from "./minimal-subagents-message-envelope.js";
+import type { AgentSummary } from "./minimal-subagents-types.js";
 
 export type { CoordinatorToolName } from "./minimal-subagents-render-contract.js";
 
@@ -98,6 +99,23 @@ function toolResultText(result: AgentToolResult<unknown>): string {
   return text?.type === "text" ? text.text : "";
 }
 
+/** Copy the hierarchy with active subtrees first, preserving sibling ties and ancestry. */
+export function orderActiveAgentSubtrees(agents: readonly AgentSummary[]): AgentSummary[] {
+  const orderSiblings = (
+    siblings: readonly AgentSummary[],
+  ): { agent: AgentSummary; active: boolean }[] =>
+    siblings
+      .map((agent) => {
+        const children = orderSiblings(agent.children);
+        return {
+          agent: { ...agent, children: children.map((child) => child.agent) },
+          active: agent.state === "running" || children.some((child) => child.active),
+        };
+      })
+      .sort((left, right) => Number(right.active) - Number(left.active));
+  return orderSiblings(agents).map(({ agent }) => agent);
+}
+
 /** Shared unavailable → running → latest-turn → idle status ladder for one subagent. */
 export function subagentStatusLadder(agent: {
   readonly availability?: string;