@ian-pascoe/pi-minimal-subagents 0.15.0 → 0.17.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.99.0`.
+`pi -e ./src/index.ts`. Requires Node `>=22.19.0` and Pi `>=1.1.0`.
 
 ## Typical workflow
 
@@ -276,10 +276,10 @@ creation; reloading does not silently broaden them. The default maximum depth
 is two levels beneath the interactive Root Agent.
 
 The extension registers six coordinator tools for the Root Agent and fanout
-children: `subagent`, `agent_message`, `subagent_wait`, `subagent_status`,
-`subagent_cancel`, and `subagent_delete`. Ordinary non-fanout children receive
-only the three adjacent-coordination tools: `agent_message`, `subagent_wait`,
-and `subagent_status`.
+children below the depth cap: `subagent`, `agent_message`, `subagent_wait`, `subagent_status`,
+`subagent_cancel`, and `subagent_delete`. Children that cannot spawn (delegation
+`none`, or fanout at the depth cap) have no children to wait on or inspect, so they
+receive only `agent_message`.
 
 A running child's `latest_activity_at` advances with the timestamps of its latest
 messages and tool results. Targeted `subagent_status` includes `recent_activity`, a bounded tail of message
@@ -288,7 +288,9 @@ assistant message but omits image data. Timeout Wait Events carry only a compact
 progress snapshot. Children target only direct children; the Root Agent
 may inspect any descendant. Model-facing status reports a `child_count` but no
 nested `children` summaries. Reported `usage` always includes `cacheWrite1h`
-and `reasoning`, as `0` when the provider reports none. `subagent_cancel`
+and `reasoning`, as `0` when the provider reports none. Tool-result text and
+`structuredContent` round every `usage.cost` field to six decimal places of USD;
+exact values stay in session data. `subagent_cancel`
 lists in `affected_agent_ids` only agents whose active turns it cancelled.
 
 `session_context` defaults to `omit`: the child starts with only its system
@@ -435,7 +437,7 @@ with Pi's tool-expansion hint (normally Ctrl+O), which reveals the rest and the
 full detail. Automatic agent results and messages preview the same way.
 
 In TUI mode, `/subagents` or `/subagents status` opens a large, centered,
-framed overlay. Up/Down selects a Child Agent; Enter opens its Child Session
+overlay in Pi's selector frame. 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [
@@ -31,14 +31,14 @@
     "provenance": true
   },
   "dependencies": {
-    "@ian-pascoe/pi-utils": "^0.3.1",
+    "@ian-pascoe/pi-utils": "^0.5.0",
     "minimatch": "^10.2.6"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.99.0",
-    "@earendil-works/pi-ai": ">=0.99.0",
-    "@earendil-works/pi-coding-agent": ">=0.99.0",
-    "@earendil-works/pi-tui": ">=0.99.0",
+    "@earendil-works/pi-agent-core": ">=1.1.0",
+    "@earendil-works/pi-ai": ">=1.1.0",
+    "@earendil-works/pi-coding-agent": ">=1.1.0",
+    "@earendil-works/pi-tui": ">=1.1.0",
     "typebox": "*"
   },
   "engines": {

package/src/minimal-subagents-config.ts

@@ -1,4 +1,8 @@
 import type { SettingsManager } from "@earendil-works/pi-coding-agent";
+import {
+  type LayeredSettingScope,
+  resolveLayeredOptions,
+} from "@ian-pascoe/pi-utils/layered-settings";
 import { Minimatch } from "minimatch";
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
@@ -224,29 +228,28 @@ function readMinimalSubagentsSettings(
   return {};
 }
 
+/** Merge one scope's model roles into those of lower scopes, entry by entry. */
 function mergeModelRoleEntries(
-  globalValue: ModelRolesWireValue | undefined,
-  projectValue: ModelRolesWireValue | undefined,
+  current: ReadonlyMap<string, ScopedSettingValue>,
+  value: ModelRolesWireValue,
+  source: LayeredSettingScope,
   warnings: string[],
 ): Map<string, ScopedSettingValue> {
-  const entries = new Map<string, ScopedSettingValue>();
-  if (globalValue?.kind === "entries") {
-    for (const [name, value] of globalValue.entries) {
-      entries.set(name, { scope: "global", value });
-    }
-  } else if (globalValue?.kind === "invalid") {
-    warnings.push("global minimalSubagents.modelRoles: expected an object or null");
+  if (value.kind === "reset") return new Map();
+  if (value.kind === "invalid") {
+    warnings.push(`${source} minimalSubagents.modelRoles: expected an object or null`);
+    return new Map(current);
   }
-  if (projectValue?.kind === "reset") return new Map();
-  if (projectValue === undefined) return entries;
-  if (projectValue.kind === "invalid") {
-    warnings.push("project minimalSubagents.modelRoles: expected an object or null");
+  const entries = new Map(current);
+  if (source === "global") {
+    for (const [name, roleValue] of value.entries) {
+      entries.set(name, { scope: "global", value: roleValue });
+    }
     return entries;
   }
-  if (projectValue.kind !== "entries") return entries;
 
-  for (const [name, value] of projectValue.entries) {
-    if (value.kind === "delete") {
+  for (const [name, roleValue] of value.entries) {
+    if (roleValue.kind === "delete") {
       entries.delete(name);
       continue;
     }
@@ -254,9 +257,9 @@ function mergeModelRoleEntries(
     const mergedValue =
       inherited !== undefined &&
       isExpandedModelRoleWireValue(inherited) &&
-      isExpandedModelRoleWireValue(value)
-        ? parseModelRoleWireValue({ ...inherited.fields, ...value.fields })
-        : value;
+      isExpandedModelRoleWireValue(roleValue)
+        ? parseModelRoleWireValue({ ...inherited.fields, ...roleValue.fields })
+        : roleValue;
     entries.set(name, { scope: "project", value: mergedValue });
   }
   return entries;
@@ -380,26 +383,24 @@ function resolveSubagentAccessSettings(
   };
 }
 
-function resolveMaxSubagentDepth(
-  globalValue: MaxSubagentDepthWireValue | undefined,
-  projectValue: MaxSubagentDepthWireValue | undefined,
+function mergeMaxSubagentDepth(
+  current: number,
+  value: MaxSubagentDepthWireValue,
+  source: LayeredSettingScope,
   warnings: string[],
 ): number {
-  let resolvedDepth = DEFAULT_MAX_SUBAGENT_DEPTH;
-  if (globalValue?.kind === "depth") {
-    resolvedDepth = globalValue.value;
-  } else if (globalValue?.kind === "invalid") {
-    warnings.push(
-      "global minimalSubagents.maxSubagentDepth: expected a positive safe integer or null",
-    );
-  }
-  if (projectValue === undefined) return resolvedDepth;
-  if (projectValue.kind === "reset") return DEFAULT_MAX_SUBAGENT_DEPTH;
-  if (projectValue.kind === "depth") return projectValue.value;
+  if (value.kind === "reset") return DEFAULT_MAX_SUBAGENT_DEPTH;
+  if (value.kind === "depth") return value.value;
   warnings.push(
-    "project minimalSubagents.maxSubagentDepth: expected a positive safe integer or null",
+    `${source} minimalSubagents.maxSubagentDepth: expected a positive safe integer or null`,
   );
-  return resolvedDepth;
+  return current;
+}
+
+/** Settings resolved across scopes, before model role references are checked. */
+interface MergedMinimalSubagentsSettings extends MinimalSubagentsToolsets {
+  maxSubagentDepth: number;
+  modelRoles: Map<string, ScopedSettingValue>;
 }
 
 /** Resolve trusted global and project settings into validated subagent guidance and limits. */
@@ -412,28 +413,39 @@ export function resolveMinimalSubagentsConfig(
     input.projectTrusted === false
       ? {}
       : readMinimalSubagentsSettings(input.projectSettings, "project", warnings);
-  const maxSubagentDepth = resolveMaxSubagentDepth(
-    globalConfig.maxSubagentDepth,
-    projectConfig.maxSubagentDepth,
-    warnings,
-  );
-  const modelRoleEntries = mergeModelRoleEntries(
-    globalConfig.modelRoles,
-    projectConfig.modelRoles,
-    warnings,
-  );
+  const { settings } = resolveLayeredOptions<
+    ParsedMinimalSubagentsSettings,
+    MergedMinimalSubagentsSettings
+  >({
+    defaults: {
+      maxSubagentDepth: DEFAULT_MAX_SUBAGENT_DEPTH,
+      modelRoles: new Map(),
+      baseToolset: [...DEFAULT_TOOLSETS.baseToolset],
+      readToolset: [...DEFAULT_TOOLSETS.readToolset],
+      modifyToolset: [...DEFAULT_TOOLSETS.modifyToolset],
+    },
+    // Depth warnings precede model role warnings, as each key merges across scopes in turn.
+    optionKeys: ["maxSubagentDepth", "modelRoles", "baseToolset", "readToolset", "modifyToolset"],
+    layers: [
+      ["global", globalConfig],
+      ["project", projectConfig],
+    ],
+    merge: {
+      maxSubagentDepth: (current, value, source) =>
+        mergeMaxSubagentDepth(current, value, source, warnings),
+      modelRoles: (current, value, source) =>
+        mergeModelRoleEntries(current, value, source, warnings),
+    },
+  });
 
   return {
-    maxSubagentDepth,
+    maxSubagentDepth: settings.maxSubagentDepth,
     subagentAccess: resolveSubagentAccessSettings(globalConfig.enabled, projectConfig.enabled),
-    modelRoles: parseModelRoles(modelRoleEntries, input.eligibleModelIds, warnings),
+    modelRoles: parseModelRoles(settings.modelRoles, input.eligibleModelIds, warnings),
     toolsets: {
-      baseToolset: projectConfig.baseToolset ??
-        globalConfig.baseToolset ?? [...DEFAULT_TOOLSETS.baseToolset],
-      readToolset: projectConfig.readToolset ??
-        globalConfig.readToolset ?? [...DEFAULT_TOOLSETS.readToolset],
-      modifyToolset: projectConfig.modifyToolset ??
-        globalConfig.modifyToolset ?? [...DEFAULT_TOOLSETS.modifyToolset],
+      baseToolset: settings.baseToolset,
+      readToolset: settings.readToolset,
+      modifyToolset: settings.modifyToolset,
     },
     warnings,
   };

package/src/minimal-subagents-context.ts

@@ -353,7 +353,7 @@ export function buildSubagentSystemPrompt(
 ): string {
   const coordinatorBoundary = options.canSpawn
     ? "Coordinator tools support subagent, agent_message, subagent_wait, subagent_status, subagent_cancel, and subagent_delete. Wait, status, cancel, and delete target direct children only; recursive cancel and delete may affect a child's subtree."
-    : "Coordinator tools support agent_message, subagent_wait, and subagent_status; wait and status target direct children only.";
+    : "Coordinator tools support only agent_message; you have no children to wait on or inspect.";
   const delegationBoundary = options.canSpawn
     ? [
         "You have explicit fanout responsibility for this assigned task.",

package/src/minimal-subagents-coordinator.ts

@@ -370,7 +370,7 @@ export class MinimalSubagentsCoordinator {
       this.dependencies.notify?.({
         type: "tool-warning",
         agentId,
-        message: `Minimal subagents tool warnings for ${agentId}:\n- ${warnings.join("\n- ")}`,
+        message: `Tool warnings for ${agentId}:\n- ${warnings.join("\n- ")}`,
       });
     }
     this.dependencies.notify?.({

package/src/minimal-subagents-extension.ts

@@ -20,6 +20,7 @@ import {
   type TurnEndEvent,
 } from "@earendil-works/pi-coding-agent";
 import { isKeyRelease, isKeyRepeat, matchesKey } from "@earendil-works/pi-tui";
+import { expandMessageOnClick, noticeText } from "@ian-pascoe/pi-utils/ui";
 import {
   createSubagentAccessBranchRecord,
   reconcileCoordinatorToolAccess,
@@ -247,7 +248,10 @@ function reportInvalidRegistryRecords(
       .map(({ entry_index: entryIndex, code }) => `entry ${entryIndex}: ${code}`)
       .join(", ");
     context.ui.notify(
-      `Minimal subagents Registry ignored ${diagnostics.length} invalid active-branch record${diagnostics.length === 1 ? "" : "s"} (${summaries}${diagnostics.length > 3 ? ", …" : ""}).`,
+      noticeText(
+        "Subagents",
+        `Registry ignored ${diagnostics.length} invalid active-branch record${diagnostics.length === 1 ? "" : "s"} (${summaries}${diagnostics.length > 3 ? ", ..." : ""}).`,
+      ),
       "warning",
     );
   };
@@ -342,7 +346,10 @@ async function rebindForkAgents(
       const message = error instanceof Error ? error.message : String(error);
       failedSubtrees.add(agent.agent_id);
       agents.push(unavailableForkAgent(agent, message));
-      context.ui.notify(`${options.notifyLabel} for ${agent.agent_id}: ${message}`, "error");
+      context.ui.notify(
+        noticeText("Subagents", `${options.notifyLabel} for ${agent.agent_id}: ${message}`),
+        "error",
+      );
     }
   }
   return agents;
@@ -410,7 +417,10 @@ function reportInvalidSubagentAccessRecords(
 ): (diagnostics: SubagentAccessReplayDiagnostic[]) => void {
   return (diagnostics) => {
     context.ui.notify(
-      `Minimal subagents ignored ${diagnostics.length} invalid Subagent Access branch record${diagnostics.length === 1 ? "" : "s"}.`,
+      noticeText(
+        "Subagents",
+        `Ignored ${diagnostics.length} invalid Subagent Access branch record${diagnostics.length === 1 ? "" : "s"}.`,
+      ),
       "warning",
     );
   };
@@ -545,11 +555,18 @@ export class MinimalSubagentsLifecycleController {
       schemas: createCoordinatorToolSchemas([]),
       captureCaller: (context) => rootCallerSnapshot(this.pi, context),
       onActivity: () => this.uiController?.refresh(),
-      onAttention: (message) => this.accessSession?.context.ui.notify(message, "error"),
+      onAttention: (message) =>
+        this.accessSession?.context.ui.notify(noticeText("Subagents", message), "error"),
     });
     for (const tool of rootTools) this.pi.registerTool(tool);
-    this.pi.registerMessageRenderer("minimal-subagents.message", renderMinimalSubagentsMessage);
-    this.pi.registerMessageRenderer("minimal-subagents.result", renderMinimalSubagentsResult);
+    this.pi.registerMessageRenderer(
+      "minimal-subagents.message",
+      expandMessageOnClick(renderMinimalSubagentsMessage),
+    );
+    this.pi.registerMessageRenderer(
+      "minimal-subagents.result",
+      expandMessageOnClick(renderMinimalSubagentsResult),
+    );
     this.pi.registerCommand("subagents", {
       description: "Control Subagent Access and inspect Child Agents",
       getArgumentCompletions: completeSubagentsCommandArguments,
@@ -587,7 +604,10 @@ export class MinimalSubagentsLifecycleController {
     ).override;
     if (minimalSubagentsConfig.warnings.length > 0) {
       context.ui.notify(
-        `Minimal subagents configuration warnings:\n- ${minimalSubagentsConfig.warnings.join("\n- ")}`,
+        noticeText(
+          "Subagents",
+          `Configuration warnings:\n- ${minimalSubagentsConfig.warnings.join("\n- ")}`,
+        ),
         "warning",
       );
     }
@@ -648,7 +668,7 @@ export class MinimalSubagentsLifecycleController {
               callerId,
               childContext.sessionManager.getLeafId() ?? callerId,
             ),
-          onAttention: (message) => context.ui.notify(message, "error"),
+          onAttention: (message) => context.ui.notify(noticeText("Subagents", message), "error"),
         });
       },
     });
@@ -665,7 +685,11 @@ export class MinimalSubagentsLifecycleController {
       notify: (notification) => {
         this.uiController?.refresh();
         if (shouldSurfaceNotification(notification)) {
-          context.ui.notify(notification.message, notificationLevel(notification));
+          const level = notificationLevel(notification);
+          context.ui.notify(
+            level === "info" ? notification.message : noticeText("Subagents", notification.message),
+            level,
+          );
         }
       },
     });
@@ -679,7 +703,10 @@ export class MinimalSubagentsLifecycleController {
       if (forkSnapshot?.source_root_session_id !== sourceRootSessionId) {
         if (forkSnapshot) {
           context.ui.notify(
-            "Minimal subagents fork handoff rejected because its source root identity did not match.",
+            noticeText(
+              "Subagents",
+              "Fork handoff rejected because its source root identity did not match.",
+            ),
             "error",
           );
         }
@@ -705,7 +732,10 @@ export class MinimalSubagentsLifecycleController {
           );
         } else {
           context.ui.notify(
-            "Minimal subagents fork recovery skipped because the destination selected branch could not be proven from parentSession provenance.",
+            noticeText(
+              "Subagents",
+              "Fork recovery skipped because the destination selected branch could not be proven from parentSession provenance.",
+            ),
             "warning",
           );
         }
@@ -733,7 +763,7 @@ export class MinimalSubagentsLifecycleController {
       schemas,
       captureCaller: (toolContext) => rootCallerSnapshot(this.pi, toolContext),
       onActivity: () => this.uiController?.refresh(),
-      onAttention: (message) => context.ui.notify(message, "error"),
+      onAttention: (message) => context.ui.notify(noticeText("Subagents", message), "error"),
     });
     for (const tool of rootTools) this.pi.registerTool(tool);
     this.accessSession = {
@@ -760,7 +790,10 @@ export class MinimalSubagentsLifecycleController {
 
     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.",
+        noticeText(
+          "Subagents",
+          "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.",
+        ),
         "warning",
       );
     }
@@ -828,11 +861,11 @@ export class MinimalSubagentsLifecycleController {
   private async runSubagentsCommand(args: string, context: ExtensionCommandContext): Promise<void> {
     const parsed = parseSubagentsCommandArguments(args);
     if (!parsed.ok) {
-      context.ui.notify(parsed.message, "error");
+      context.ui.notify(noticeText("Subagents", parsed.message), "error");
       return;
     }
     if (!this.accessSession || !this.coordinator) {
-      context.ui.notify("Minimal subagents is not active for this session.", "error");
+      context.ui.notify(noticeText("Subagents", "Not active for this session."), "error");
       return;
     }
     if (parsed.command.action === "status") {
@@ -861,7 +894,10 @@ export class MinimalSubagentsLifecycleController {
           command.action === "reset" ? undefined : command.action === "enable",
         );
       } catch (error) {
-        context.ui.notify(error instanceof Error ? error.message : String(error), "error");
+        context.ui.notify(
+          noticeText("Subagents", error instanceof Error ? error.message : String(error)),
+          "error",
+        );
         return;
       }
       persistedScope = command.scope;
@@ -885,9 +921,12 @@ export class MinimalSubagentsLifecycleController {
     } catch (error) {
       const detail = error instanceof Error ? error.message : String(error);
       context.ui.notify(
-        persistedScope
-          ? `Minimal subagents ${persistedScope} default changed, but the current session did not: ${detail}`
-          : `Minimal subagents could not change the current session: ${detail}`,
+        noticeText(
+          "Subagents",
+          persistedScope
+            ? `${persistedScope} default changed, but the current session did not: ${detail}`
+            : `Could not change the current session: ${detail}`,
+        ),
         "error",
       );
       return;

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

@@ -272,7 +272,10 @@ const CoordinatorWaitSourceOutputSchema = {
   source_turn_id: Type.String(),
 };
 
-/** Final details schemas exposed to CodeMode for the six coordinator tools. */
+/**
+ * Final details schemas exposed to CodeMode for the six coordinator tools. `structuredContent`
+ * matches them with every `usage.cost` field rounded for presentation.
+ */
 export const CoordinatorToolOutputSchemas = {
   subagent: Type.Object({
     agent_id: Type.String(),