oira666_pi-subagent 0.1.3 → 0.1.4

package/README.md

@@ -112,6 +112,309 @@ pi --no-subagent-prevent-cycles   # allow cycles (not recommended)
 | `PI_SUBAGENT_MAX_PARALLEL_TASKS` | `16`    | Max tasks per single call                |
 | `PI_SUBAGENT_MAX_CONCURRENCY`    | `8`     | Max subagents running simultaneously     |
 
+## CLI Argument Proxying
+
+All flags passed to the parent `pi` process are forwarded to subagent child processes, so they
+inherit the same provider, API key, model, and other runtime settings. Flags the extension manages
+itself are blocked from being forwarded.
+
+**Always forwarded verbatim:**
+
+| Flag(s) | Purpose |
+| --- | --- |
+| `--provider` | AI provider |
+| `--api-key` | API key |
+| `--system-prompt` | Base system prompt override |
+| `--session-dir` | Session storage directory |
+| `--models` | Model cycling list |
+| `--skill`, `--no-skills`/`-ns` | Skill loading |
+| `--prompt-template`, `--no-prompt-templates`/`-np` | Prompt templates |
+| `--theme`, `--no-themes` | Themes |
+| `--verbose` | Verbose startup output |
+| Unknown/custom flags | Forwarded with heuristic value detection |
+
+**Forwarded as fallback** (agent frontmatter overrides if set):
+
+| Flag | Overridden by |
+| --- | --- |
+| `--model` | `model:` in agent frontmatter |
+| `--thinking` | `thinking:` in agent frontmatter |
+| `--tools` / `--no-tools` | `tools:` in agent frontmatter |
+
+**Never forwarded** (managed by the extension itself):
+`--mode`, `-p`/`--print`, `--session`/`--no-session`, `--continue`, `--resume`,
+`--append-system-prompt`, `--offline`, `--extension`/`-e`, `--no-extensions`/`-ne`,
+`--subagent-max-depth`, `--subagent-prevent-cycles`, `--export`, `--list-models`,
+`--help`, `--version`.
+
+---
+
+## Programmatic Usage (JSON RPC)
+
+When running `pi` programmatically with `--mode rpc` (or `--mode json`), the stream contains
+`tool_result_end` events whenever the agent completes a `subagent` tool call. The `details` field
+of these events carries the full stats for that delegation — including recursive usage and tool
+call counts from all subagents in the tree.
+
+### Stream event shape
+
+```
+tool_result_end
+└── message
+    ├── role:        "toolResult"
+    ├── toolName:    "subagent"
+    ├── toolCallId:  string
+    ├── isError:     boolean
+    ├── content:     [{ type: "text", text: "<final output>" }]
+    └── details:     SubagentDetails
+```
+
+### `SubagentDetails` object
+
+```ts
+interface SubagentDetails {
+  // Execution metadata
+  mode: "single" | "parallel";          // one task vs multiple parallel tasks
+  delegationMode: "spawn" | "fork";     // context mode used
+  projectAgentsDir: string | null;      // path to .pi/agents/ dir if used
+
+  // Individual agent results (one per task)
+  results: SingleResult[];
+
+  // ── Stats summary (own + all descendants, recursively) ──────────────────
+  aggregatedUsage: UsageStats;          // token counts and cost, full tree
+  aggregatedToolCalls: ToolCallCounts;  // { toolName: callCount }, full tree
+
+  // ── Per-agent breakdown ──────────────────────────────────────────────────
+  usageTree: UsageTreeNode[];           // one root node per result
+}
+
+interface SingleResult {
+  agent: string;                        // agent name
+  agentSource: "user" | "project" | "builtin" | "unknown";
+  task: string;                         // task string passed to this agent
+  exitCode: number;                     // 0 = success, >0 = error, -1 = still running
+  messages: Message[];                  // full conversation history of the subagent
+  stderr: string;
+  usage: UsageStats;                    // this agent's OWN token usage only
+  toolCalls: ToolCallCounts;            // this agent's OWN tool calls only
+  model?: string;
+  stopReason?: string;                  // "end_turn" | "error" | "aborted" | ...
+  errorMessage?: string;
+}
+
+interface UsageStats {
+  input: number;                        // input tokens
+  output: number;                       // output tokens
+  cacheRead: number;                    // cache read tokens
+  cacheWrite: number;                   // cache write tokens
+  cost: number;                         // total cost in USD
+  contextTokens: number;                // snapshot: last context window size (not summed in aggregates)
+  turns: number;                        // number of assistant turns
+}
+
+// toolName → call count, e.g. { "bash": 5, "read": 3, "subagent": 1 }
+type ToolCallCounts = Record<string, number>;
+
+interface UsageTreeNode {
+  agent: string;
+  task: string;
+  ownUsage: UsageStats;                 // only this agent's turns
+  ownToolCalls: ToolCallCounts;         // only this agent's tool calls
+  aggregatedUsage: UsageStats;          // ownUsage + all children recursively
+  aggregatedToolCalls: ToolCallCounts;  // ownToolCalls + all children recursively
+  children: UsageTreeNode[];            // one node per nested subagent invocation
+}
+```
+
+### Important notes on stats
+
+- **`SingleResult.usage`** and **`SingleResult.toolCalls`** cover **only that one agent's own work** —
+  not its children. Children run in separate processes; their tokens never appear in the parent's usage.
+- **`aggregatedUsage`** / **`aggregatedToolCalls`** on `SubagentDetails` (and on each `UsageTreeNode`)
+  are the correct totals to use when you want the cost or tool call count for an entire delegation
+  subtree.
+- **`contextTokens`** is a point-in-time snapshot of the context window size at the last turn of that
+  agent. It is **not** summed in aggregated stats (it would be meaningless as a cross-process sum).
+- **`toolCalls`** includes **all** tool calls an agent made, including the `"subagent"` call itself.
+  You can use the `"subagent"` count to see how many nested delegations an agent spawned.
+
+### Annotated example JSON
+
+The scenario below: main agent delegates to `code-writer`, which does some file work and then
+delegates to `code-reviwer` before finishing.
+
+```json
+{
+  "type": "tool_result_end",
+  "message": {
+    "role": "toolResult",
+    "toolName": "subagent",
+    "toolCallId": "toolu_01XYZ",
+    "isError": false,
+    "content": [
+      {
+        "type": "text",
+        "text": "Feature implemented and reviewed. Added validation logic in auth.ts and updated the test suite."
+      }
+    ],
+    "details": {
+      "mode": "single",
+      "delegationMode": "spawn",
+      "projectAgentsDir": null,
+
+      "aggregatedUsage": {
+        "input": 2180,
+        "output": 615,
+        "cacheRead": 940,
+        "cacheWrite": 120,
+        "cost": 0.0079,
+        "contextTokens": 0,
+        "turns": 3
+      },
+      "aggregatedToolCalls": {
+        "read":     3,
+        "bash":     2,
+        "edit":     1,
+        "subagent": 1
+      },
+
+      "usageTree": [
+        {
+          "agent": "code-writer",
+          "task": "Implement the auth feature and have it reviewed",
+          "ownUsage": {
+            "input": 1380,
+            "output": 365,
+            "cacheRead": 540,
+            "cacheWrite": 120,
+            "cost": 0.0058,
+            "contextTokens": 2840,
+            "turns": 2
+          },
+          "ownToolCalls": {
+            "read":     1,
+            "bash":     1,
+            "edit":     1,
+            "subagent": 1
+          },
+          "aggregatedUsage": {
+            "input": 2180,
+            "output": 615,
+            "cacheRead": 940,
+            "cacheWrite": 120,
+            "cost": 0.0079,
+            "contextTokens": 0,
+            "turns": 3
+          },
+          "aggregatedToolCalls": {
+            "read":     3,
+            "bash":     2,
+            "edit":     1,
+            "subagent": 1
+          },
+          "children": [
+            {
+              "agent": "code-reviwer",
+              "task": "Review the auth implementation in auth.ts",
+              "ownUsage": {
+                "input": 800,
+                "output": 250,
+                "cacheRead": 400,
+                "cacheWrite": 0,
+                "cost": 0.0021,
+                "contextTokens": 1450,
+                "turns": 1
+              },
+              "ownToolCalls": {
+                "read": 2,
+                "bash": 1
+              },
+              "aggregatedUsage": {
+                "input": 800,
+                "output": 250,
+                "cacheRead": 400,
+                "cacheWrite": 0,
+                "cost": 0.0021,
+                "contextTokens": 0,
+                "turns": 1
+              },
+              "aggregatedToolCalls": {
+                "read": 2,
+                "bash": 1
+              },
+              "children": []
+            }
+          ]
+        }
+      ],
+
+      "results": [
+        {
+          "agent": "code-writer",
+          "agentSource": "builtin",
+          "task": "Implement the auth feature and have it reviewed",
+          "exitCode": 0,
+          "stopReason": "end_turn",
+          "model": "claude-opus-4-5",
+          "stderr": "",
+          "usage": {
+            "input": 1380,
+            "output": 365,
+            "cacheRead": 540,
+            "cacheWrite": 120,
+            "cost": 0.0058,
+            "contextTokens": 2840,
+            "turns": 2
+          },
+          "toolCalls": {
+            "read":     1,
+            "bash":     1,
+            "edit":     1,
+            "subagent": 1
+          },
+          "messages": [
+            "... full conversation history of code-writer (includes the nested subagent tool_result) ..."
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+### Collecting stats across an entire session
+
+If you are consuming the JSON stream programmatically and want to track the total cost and tool
+usage across all subagent work in a session, listen for every `tool_result_end` event where
+`message.toolName === "subagent"` and sum `message.details.aggregatedUsage` across them.
+
+```js
+let totalCost = 0;
+const totalToolCalls = {};
+
+for await (const line of jsonLines) {
+  const event = JSON.parse(line);
+  if (
+    event.type === "tool_result_end" &&
+    event.message?.toolName === "subagent" &&
+    event.message?.details
+  ) {
+    const { aggregatedUsage, aggregatedToolCalls } = event.message.details;
+    totalCost += aggregatedUsage.cost;
+    for (const [tool, count] of Object.entries(aggregatedToolCalls)) {
+      totalToolCalls[tool] = (totalToolCalls[tool] ?? 0) + count;
+    }
+  }
+}
+```
+
+Note: if you also track the main agent's own usage from `message_end` events, make sure **not** to
+double-count the subagent costs there — the main agent's own token usage (from its own `message_end`
+events) does not include subagent work; they are always separate processes.
+
+---
+
 ## create-subagent Skill
 
 If you want the agent to **create new subagent definition files** for itself, install the [`create-subagent` skill](https://github.com/gee666/pi-subagent/tree/main/create-subagent). Once installed, the agent will know how to scaffold new `.md` agent files in the right location with correct frontmatter.

package/index.ts

@@ -23,6 +23,7 @@ import {
   type SingleResult,
   type SubagentDetails,
   DEFAULT_DELEGATION_MODE,
+  buildSubagentDetails,
   emptyUsage,
   getFinalOutput,
   isResultError,
@@ -332,12 +333,8 @@ function makeDetailsFactory(
   delegationMode: DelegationMode,
 ) {
   return (mode: "single" | "parallel") =>
-    (results: SingleResult[]): SubagentDetails => ({
-      mode,
-      delegationMode,
-      projectAgentsDir,
-      results,
-    });
+    (results: SingleResult[]): SubagentDetails =>
+      buildSubagentDetails(mode, delegationMode, projectAgentsDir, results);
 }
 
 function formatAgentNames(agents: AgentConfig[]): string {
@@ -785,6 +782,7 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
       messages: [],
       stderr: "",
       usage: emptyUsage(),
+      toolCalls: {},
     }));
 
     const emitProgress = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oira666_pi-subagent",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Subagent extension for Pi coding agent. Delegate tasks to specialized agents.",
   "type": "module",
   "main": "index.ts",

package/render.ts

@@ -271,7 +271,11 @@ function renderTreeLines(
 }
 
 function topLevelSummary(details: SubagentDetails, counts: TreeCounts): string {
-	const totalUsage = formatUsage(aggregateUsage(details.results));
+	// aggregatedUsage includes own agents + all their nested descendants;
+	// fall back to summing only direct results for old serialised data lacking the field.
+	const totalUsage = formatUsage(
+		details.aggregatedUsage ?? aggregateUsage(details.results),
+	);
 	const parts = [
 		`${counts.running} running`,
 		`${counts.finished}/${counts.total} finished`,

package/runner.ts

@@ -16,6 +16,7 @@ import {
   type SingleResult,
   type SubagentDetails,
   emptyUsage,
+  extractToolCalls,
   getFinalOutput,
   getNestedSubagentErrorSummary,
 } from "./types.js";
@@ -74,32 +75,168 @@ function resolveExtensionArg(value: string): string {
   return fs.existsSync(resolved) ? resolved : value;
 }
 
-function getInheritedExtensionArgs(argv: string[]): string[] {
-  const args: string[] = [];
-  for (let i = 2; i < argv.length; i++) {
-    const arg = argv[i];
+interface InheritedCliArgs {
+  /** --extension/-e and --no-extensions/-ne args (with path resolution) */
+  extensionArgs: string[];
+  /** All other non-blocked flags to forward verbatim to every child */
+  alwaysProxy: string[];
+  /** Parent --model value; used only when agent config doesn't specify model */
+  fallbackModel: string | undefined;
+  /** Parent --thinking value; used only when agent config doesn't specify thinking */
+  fallbackThinking: string | undefined;
+  /** Parent --tools value; used only when agent config doesn't specify tools */
+  fallbackTools: string | undefined;
+  /** Parent passed --no-tools; used only when agent config doesn't specify tools */
+  fallbackNoTools: boolean;
+}
+
+/**
+ * Parse process.argv into categorised groups for child-process arg construction.
+ *
+ * Categories:
+ *  - BLOCKED       : flags the extension manages itself — never forwarded
+ *  - extensionArgs : --extension/-e and --no-extensions/-ne (with path resolution)
+ *  - alwaysProxy   : all other non-blocked flags forwarded verbatim
+ *  - fallback*     : flags the agent config may override
+ *
+ * Handles both "--flag value" and "--flag=value" forms.
+ * Unknown flags use a heuristic: if the next token doesn't start with "-",
+ * it is treated as the flag's value.
+ */
+function parseInheritedCliArgs(argv: string[]): InheritedCliArgs {
+  const extensionArgs: string[] = [];
+  const alwaysProxy: string[] = [];
+  let fallbackModel: string | undefined;
+  let fallbackThinking: string | undefined;
+  let fallbackTools: string | undefined;
+  let fallbackNoTools = false;
+
+  let i = 2; // skip "node" and "pi"
+  while (i < argv.length) {
+    const raw = argv[i];
+    // Positional args (prompt text, @file refs) — skip, not proxied to children
+    if (!raw.startsWith("-")) { i++; continue; }
+
+    // Normalise: detect --flag=value inline form
+    const eqIdx = raw.indexOf("=");
+    const flagName = eqIdx !== -1 ? raw.slice(0, eqIdx) : raw;
+    const inlineValue: string | undefined = eqIdx !== -1 ? raw.slice(eqIdx + 1) : undefined;
+
+    const nextToken = argv[i + 1];
+    const nextIsValue = nextToken !== undefined && !nextToken.startsWith("-");
+
+    // Returns [resolvedValue | undefined, tokensToConsume]
+    const getVal = (): [string | undefined, number] => {
+      if (inlineValue !== undefined) return [inlineValue, 1];
+      if (nextIsValue) return [nextToken, 2];
+      return [undefined, 1];
+    };
+
+    // ── BLOCKED: value flags ─────────────────────────────────────────────────
+    // Extension manages these; consume flag + value, never proxy.
+    if ([
+      "--mode", "--session", "--append-system-prompt",
+      "--export", "--subagent-max-depth",
+    ].includes(flagName)) {
+      const [, skip] = getVal();
+      i += skip; continue;
+    }
 
-    if (arg === "--no-extensions" || arg === "-ne") {
-      args.push("--no-extensions");
+    // --subagent-prevent-cycles takes an optional value
+    if (flagName === "--subagent-prevent-cycles") {
+      if (inlineValue !== undefined || nextIsValue) { i += inlineValue !== undefined ? 1 : 2; }
+      else { i++; }
       continue;
     }
 
-    if (arg === "--extension" || arg === "-e") {
-      const value = argv[i + 1];
-      if (value !== undefined) {
-        args.push("--extension", resolveExtensionArg(value));
-        i++;
-      }
+    // --list-models has an optional search term
+    if (flagName === "--list-models") {
+      if (inlineValue !== undefined || nextIsValue) { i += inlineValue !== undefined ? 1 : 2; }
+      else { i++; }
       continue;
     }
 
-    if (arg.startsWith("--extension=")) {
-      args.push("--extension", resolveExtensionArg(arg.slice("--extension=".length)));
+    // ── BLOCKED: boolean flags ────────────────────────────────────────────────
+    if ([
+      "--print", "-p", "--no-session",
+      "--continue", "-c", "--resume", "-r",
+      "--offline", "--help", "-h", "--version", "-v",
+      "--no-subagent-prevent-cycles",
+    ].includes(flagName)) {
+      i++; continue;
+    }
+
+    // ── EXTENSION FLAGS: handled separately with path resolution ─────────────
+    if (flagName === "--no-extensions" || flagName === "-ne") {
+      extensionArgs.push(flagName);
+      i++; continue;
+    }
+    if (flagName === "--extension" || flagName === "-e") {
+      const [value, skip] = getVal();
+      if (value !== undefined) extensionArgs.push(flagName, resolveExtensionArg(value));
+      i += skip; continue;
+    }
+
+    // ── ALWAYS-PROXY: known value flags ──────────────────────────────────────
+    if ([
+      "--provider", "--api-key", "--system-prompt", "--session-dir",
+      "--models", "--skill", "--prompt-template", "--theme",
+    ].includes(flagName)) {
+      const [value, skip] = getVal();
+      if (value !== undefined) alwaysProxy.push(flagName, value);
+      i += skip; continue;
+    }
+
+    // ── ALWAYS-PROXY: known boolean flags ────────────────────────────────────
+    if ([
+      "--no-skills", "-ns", "--no-prompt-templates", "-np",
+      "--no-themes", "--verbose",
+    ].includes(flagName)) {
+      alwaysProxy.push(flagName);
+      i++; continue;
     }
+
+    // ── FALLBACK: agent config may override ───────────────────────────────────
+    if (flagName === "--model") {
+      const [value, skip] = getVal();
+      if (value !== undefined) fallbackModel = value;
+      i += skip; continue;
+    }
+    if (flagName === "--thinking") {
+      const [value, skip] = getVal();
+      if (value !== undefined) fallbackThinking = value;
+      i += skip; continue;
+    }
+    if (flagName === "--tools") {
+      const [value, skip] = getVal();
+      if (value !== undefined) fallbackTools = value;
+      i += skip; continue;
+    }
+    if (flagName === "--no-tools") {
+      fallbackNoTools = true;
+      i++; continue;
+    }
+
+    // ── UNKNOWN: heuristic passthrough ───────────────────────────────────────
+    // Likely a custom extension flag. Forward with value if next token looks like one.
+    if (inlineValue !== undefined) {
+      alwaysProxy.push(flagName, inlineValue);
+      i++; continue;
+    }
+    if (nextIsValue) {
+      alwaysProxy.push(flagName, nextToken);
+      i += 2; continue;
+    }
+    alwaysProxy.push(flagName);
+    i++;
   }
-  return args;
+
+  return { extensionArgs, alwaysProxy, fallbackModel, fallbackThinking, fallbackTools, fallbackNoTools };
 }
 
+/** Cached once — process.argv is immutable at runtime */
+const _inheritedCliArgs = parseInheritedCliArgs(process.argv);
+
 // ---------------------------------------------------------------------------
 // JSON-line stream processing
 // ---------------------------------------------------------------------------
@@ -158,7 +295,8 @@ function buildPiArgs(
   const args: string[] = [
     "--mode",
     "json",
-    ...getInheritedExtensionArgs(process.argv),
+    ..._inheritedCliArgs.extensionArgs,
+    ..._inheritedCliArgs.alwaysProxy,
     "-p",
   ];
 
@@ -168,10 +306,25 @@ function buildPiArgs(
     args.push("--session", forkSessionPath);
   }
 
-  if (agent.model) args.push("--model", agent.model);
-  if (agent.thinking) args.push("--thinking", agent.thinking);
-  if (agent.tools && agent.tools.length > 0)
+  // Agent config takes priority; fall back to parent CLI value
+  const model = agent.model ?? _inheritedCliArgs.fallbackModel;
+  if (model) args.push("--model", model);
+
+  const thinking = agent.thinking ?? _inheritedCliArgs.fallbackThinking;
+  if (thinking) args.push("--thinking", thinking);
+
+  // agent.tools is set only when the agent file specifies tools (length > 0)
+  if (agent.tools && agent.tools.length > 0) {
     args.push("--tools", agent.tools.join(","));
+  } else if (agent.tools === undefined) {
+    // Agent didn't restrict tools — inherit parent's preference
+    if (_inheritedCliArgs.fallbackTools !== undefined) {
+      args.push("--tools", _inheritedCliArgs.fallbackTools);
+    } else if (_inheritedCliArgs.fallbackNoTools) {
+      args.push("--no-tools");
+    }
+  }
+
   if (systemPromptPath) args.push("--append-system-prompt", systemPromptPath);
   args.push(`Task: ${task}`);
   return args;
@@ -246,6 +399,7 @@ export async function runAgent(opts: RunAgentOptions): Promise<SingleResult> {
       messages: [],
       stderr: `Unknown agent: "${agentName}". Available agents: ${available}.`,
       usage: emptyUsage(),
+      toolCalls: {},
     };
   }
 
@@ -262,6 +416,7 @@ export async function runAgent(opts: RunAgentOptions): Promise<SingleResult> {
       stderr:
         "Cannot run in fork mode: missing parent session snapshot context.",
       usage: emptyUsage(),
+      toolCalls: {},
       model: agent.model,
       stopReason: "error",
       errorMessage:
@@ -277,6 +432,7 @@ export async function runAgent(opts: RunAgentOptions): Promise<SingleResult> {
     messages: [],
     stderr: "",
     usage: emptyUsage(),
+    toolCalls: {},
     model: agent.model,
   };
 
@@ -379,6 +535,7 @@ export async function runAgent(opts: RunAgentOptions): Promise<SingleResult> {
     });
 
     result.exitCode = exitCode;
+    result.toolCalls = extractToolCalls(result.messages); // populate from parsed messages
     if (wasAborted) {
       result.exitCode = 130;
       result.stopReason = "aborted";

package/types.ts

@@ -21,6 +21,9 @@ export interface UsageStats {
 	turns: number;
 }
 
+/** Tool calls made by an agent: toolName → call count */
+export type ToolCallCounts = Record<string, number>;
+
 /** Result of a single subagent invocation. */
 export interface SingleResult {
 	agent: string;
@@ -30,17 +33,40 @@ export interface SingleResult {
 	messages: Message[];
 	stderr: string;
 	usage: UsageStats;
+	toolCalls: ToolCallCounts;
 	model?: string;
 	stopReason?: string;
 	errorMessage?: string;
 }
 
+/** A node in the per-subagent usage tree (own stats + recursive children) */
+export interface UsageTreeNode {
+  agent: string;
+  task: string;
+  /** Token/cost usage for this agent's own turns only */
+  ownUsage: UsageStats;
+  /** Tool calls this agent made directly (all tools, including "subagent") */
+  ownToolCalls: ToolCallCounts;
+  /** ownUsage summed with all descendants recursively */
+  aggregatedUsage: UsageStats;
+  /** ownToolCalls merged with all descendants recursively */
+  aggregatedToolCalls: ToolCallCounts;
+  /** Nested subagent invocations, recursively populated */
+  children: UsageTreeNode[];
+}
+
 /** Metadata attached to every tool result for rendering. */
 export interface SubagentDetails {
 	mode: "single" | "parallel";
 	delegationMode: DelegationMode;
 	projectAgentsDir: string | null;
 	results: SingleResult[];
+  /** Usage summed across all results and all their nested descendants */
+  aggregatedUsage: UsageStats;
+  /** Tool calls merged across all results and all their nested descendants */
+  aggregatedToolCalls: ToolCallCounts;
+  /** Per-agent recursive usage breakdown */
+  usageTree: UsageTreeNode[];
 }
 
 /** Nested subagent tool result captured from a delegated run. */
@@ -74,6 +100,97 @@ export function aggregateUsage(results: SingleResult[]): UsageStats {
 	return total;
 }
 
+/** Add delta into total in-place (contextTokens is a snapshot—not summed, left as-is in total) */
+export function addUsage(total: UsageStats, delta: UsageStats): void {
+  total.input      += delta.input;
+  total.output     += delta.output;
+  total.cacheRead  += delta.cacheRead;
+  total.cacheWrite += delta.cacheWrite;
+  total.cost       += delta.cost;
+  total.turns      += delta.turns;
+}
+
+/** Merge tool call counts from `source` into `target` in-place */
+export function mergeToolCalls(target: ToolCallCounts, source: ToolCallCounts): void {
+  for (const [name, count] of Object.entries(source)) {
+    target[name] = (target[name] ?? 0) + count;
+  }
+}
+
+/** Extract all tool calls made by assistant turns in a message list */
+export function extractToolCalls(messages: Message[]): ToolCallCounts {
+  const counts: ToolCallCounts = {};
+  for (const msg of messages) {
+    if (msg.role !== "assistant") continue;
+    for (const part of (msg.content as any[]) ?? []) {
+      if ((part as any)?.type !== "toolCall") continue;
+      const name: string = typeof (part as any).name === "string" ? (part as any).name : "unknown";
+      counts[name] = (counts[name] ?? 0) + 1;
+    }
+  }
+  return counts;
+}
+
+/** Build a UsageTreeNode for one result, recursing into nested subagent tool results */
+function buildUsageTreeNode(result: SingleResult): UsageTreeNode {
+  const children: UsageTreeNode[] = [];
+  for (const nested of getNestedSubagentResults(result.messages)) {
+    for (const nestedResult of nested.details.results) {
+      children.push(buildUsageTreeNode(nestedResult));
+    }
+  }
+
+  const ownUsage = result.usage;
+  const ownToolCalls: ToolCallCounts = result.toolCalls ?? extractToolCalls(result.messages);
+
+  const aggregatedUsage = emptyUsage();
+  addUsage(aggregatedUsage, ownUsage);
+  for (const child of children) addUsage(aggregatedUsage, child.aggregatedUsage);
+
+  const aggregatedToolCalls: ToolCallCounts = { ...ownToolCalls };
+  for (const child of children) mergeToolCalls(aggregatedToolCalls, child.aggregatedToolCalls);
+
+  return {
+    agent: result.agent,
+    task: result.task,
+    ownUsage,
+    ownToolCalls,
+    aggregatedUsage,
+    aggregatedToolCalls,
+    children,
+  };
+}
+
+/**
+ * Construct a complete SubagentDetails with aggregated stats.
+ * This replaces the plain object literal previously used by makeDetailsFactory.
+ */
+export function buildSubagentDetails(
+  mode: "single" | "parallel",
+  delegationMode: DelegationMode,
+  projectAgentsDir: string | null,
+  results: SingleResult[],
+): SubagentDetails {
+  const usageTree = results.map(buildUsageTreeNode);
+
+  const aggregatedUsage = emptyUsage();
+  const aggregatedToolCalls: ToolCallCounts = {};
+  for (const node of usageTree) {
+    addUsage(aggregatedUsage, node.aggregatedUsage);
+    mergeToolCalls(aggregatedToolCalls, node.aggregatedToolCalls);
+  }
+
+  return {
+    mode,
+    delegationMode,
+    projectAgentsDir,
+    results,
+    aggregatedUsage,
+    aggregatedToolCalls,
+    usageTree,
+  };
+}
+
 /** Whether a result represents an error. */
 export function isResultError(r: SingleResult): boolean {
 	return r.exitCode > 0 || r.stopReason === "error" || r.stopReason === "aborted";