oira666_pi-subagent 0.1.2 → 0.1.4

package/README.md

@@ -1,326 +1,427 @@
 # Pi Subagent
 
-**Delegate tasks to specialized subagents with configurable context modes (`spawn` / `fork`).**
-
-There are many subagent extensions for pi, this one is mine.
-
-## Why Pi Subagent
-
-**Specialization** — Use tailored agents for specific tasks like refactoring, documentation, or research.
-
-**Context Control** — Choose `spawn` (fresh context) or `fork` (inherit current session context), depending on the task.
-
-**Parallel Execution** — Run multiple agents at once.
-
-**A Simpler Fork** — This extension intentionally keeps the surface area small and predictable compared to heavier implementations. It supports nested delegation with depth/cycle guards, but avoids broader scope-selection complexity. If you want the minimal, “just delegate” experience, this is it.
+Delegate tasks to specialized subagents with configurable context modes (`spawn` / `fork`).
 
 ## Install
 
-### Option 1: Install from npm (recommended)
-
 ```bash
 pi install npm:oira666_pi-subagent
 ```
 
-### Option 2: Install via git
+Or via git:
 
 ```bash
 pi install git:github.com/gee666/pi-subagent.git
 ```
 
-### Option 3: Manual Installation
-
-Clone this repository to your Pi extensions directory:
+## Remove
 
 ```bash
-cd ~/.pi/agent/extensions
-git clone https://github.com/gee666/pi-subagent.git
-cd pi-subagent
-npm install
+pi remove npm:oira666_pi-subagent
 ```
 
-## Configuration
-
-### Delegation Guards (Depth + Cycle Prevention)
+## How It Works
 
-By default, this extension enforces two runtime guards:
+Each subagent runs as a **separate `pi` process** — isolated memory, its own model/tool loop.
 
-1. **Depth guard** (`--subagent-max-depth`, default `3`)
-   - Main agent starts at depth `0`
-   - Delegation is allowed while `currentDepth < maxDepth`
-   - With default depth `3`: depth `0`, `1`, and `2` can delegate; depth `3` cannot
-2. **Cycle guard** (`--subagent-prevent-cycles`, default `true`)
-   - Blocks delegating to any agent name already present in the current delegation stack
-   - Prevents self-recursion (`writer -> writer`) and loops (`planner -> reviewer -> planner`)
+**`spawn` (default)** — Child receives only the task string. Best for isolated work, lower cost.
+**`fork`** — Child receives a snapshot of the current session context + task. Best for follow-up work.
 
-You can configure depth with either:
-
-- CLI flag: `--subagent-max-depth <n>`
-- Environment variable: `PI_SUBAGENT_MAX_DEPTH=<n>`
-
-`n` must be a non-negative integer.
-
-You can configure cycle prevention with either:
-
-- CLI flag: `--subagent-prevent-cycles` / `--no-subagent-prevent-cycles`
-- Environment variable: `PI_SUBAGENT_PREVENT_CYCLES=true|false`
-
-Internal env vars managed by the extension and propagated to child processes:
-
-- `PI_SUBAGENT_DEPTH`
-- `PI_SUBAGENT_MAX_DEPTH`
-- `PI_SUBAGENT_STACK` (JSON array of ancestor agent names, e.g. `["scout","planner"]`)
-- `PI_SUBAGENT_PREVENT_CYCLES`
-
-Examples:
-
-```bash
-# Default behavior: depth 3 + cycle prevention enabled
-pi
+The main agent receives only the **final text output** from subagents (no tool calls, no reasoning).
 
-# Restrict to one nested level (main -> child -> grandchild)
-pi --subagent-max-depth 2
-
-# Disable subagent delegation entirely
-pi --subagent-max-depth 0
-
-# Allow depth 3 but disable cycle prevention (not recommended)
-pi --subagent-max-depth 3 --no-subagent-prevent-cycles
-```
-
-### Tool Call Shape
-
-`subagent` always accepts a top-level `tasks` array:
-
-- One task = single-agent delegation
-- Multiple tasks = parallel delegation
-
-Single-task example:
+## Tool Call Shape
 
 ```json
-{ "tasks": [{ "agent": "code-writer", "task": "Implement the API change" }], "mode": "spawn" }
+{ "tasks": [{ "agent": "code-writer", "task": "Implement the API" }], "mode": "spawn" }
 ```
 
-Multi-task example:
+Multiple tasks run in parallel:
 
 ```json
-{ "tasks": [{ "agent": "code-writer", "task": "Draft the implementation" }, { "agent": "code-reviwer", "task": "Review the plan" }], "mode": "fork" }
+{
+  "tasks": [
+    { "agent": "code-writer", "task": "Draft the implementation" },
+    { "agent": "code-reviwer", "task": "Review the plan" }
+  ],
+  "mode": "fork"
+}
 ```
 
-Each task item supports:
-
-- `agent` — subagent name
-- `task` — delegated task text
-- `cwd` — optional working directory override for that task
-
-### Parallel Execution Limits
-
-For multi-task calls, two environment variables control fan-out:
-
-- `PI_SUBAGENT_MAX_PARALLEL_TASKS` — maximum number of tasks allowed in one call (default: `16`)
-- `PI_SUBAGENT_MAX_CONCURRENCY` — maximum number of subagents running at the same time inside that call (default: `8`)
-
-`PI_SUBAGENT_MAX_CONCURRENCY` is effectively clamped to at least `1`.
-
-### Project-local Agent Confirmation
-
-Project-local agents from `.pi/agents/*.md` can be gated by `PI_SUBAGENT_CONFIRM_PROJECT_AGENTS`:
-
-- `true`, `ask`, or `once` (default) — prompt with **Yes once**, **Yes for this session**, or **No**
-- `false` or `never` — skip the prompt and allow project-local agents immediately
-- `session` — allow project-local agents for the rest of the current session without prompting
-
-If you choose **Yes for this session** in the UI, the choice is remembered and you will not be asked again in that session. In non-UI mode, `ask` blocks execution because the extension cannot prompt.
-
-### Context Mode (`spawn` vs `fork`)
+Each task supports `agent`, `task`, and optional `cwd`.
 
-`subagent` supports a top-level `mode` switch:
+## Bundled Agents
 
-- `spawn` (default) — Child receives only the task string (`Task: ...`). Best for isolated, reproducible work; typically lower token/cost and less context leakage.
-- `fork` — Child receives a forked snapshot of the current session context **plus** the task string. Best for follow-up work that depends on prior context; typically higher token/cost and may include sensitive context.
-
-Quick rule of thumb:
-
-- Start with `spawn` for one-off tasks.
-- Use `fork` when the delegated task depends on the current session's prior discussion, reads, or decisions.
-
-Examples:
-
-```json
-{ "tasks": [{ "agent": "code-writer", "task": "Implement the migration" }], "mode": "spawn" }
-```
-
-```json
-{ "tasks": [{ "agent": "code-reviwer", "task": "Double-check this migration" }], "mode": "fork" }
-```
-
-If omitted, mode defaults to `spawn`.
-
-### Subagent Definitions
-
-Subagents are defined as Markdown files with YAML frontmatter.
-
-**User Agents:** `~/.pi/agent/agents/*.md`
-**Project Agents:** `.pi/agents/*.md`
-**Bundled Fallback Agents:** `agents/code-writer.md`, `agents/code-reviwer.md`, `agents/code-architect.md`
-
-The extension always loads user and project agents first. If a project agent shares a name with a user agent, the project agent wins. The bundled fallback agents are only discovered when no user or project agents are found at all. If you have any user or project agents configured, the bundled defaults are hidden and not discoverable. When project agents are requested, Pi can prompt for confirmation before running them, depending on `PI_SUBAGENT_CONFIRM_PROJECT_AGENTS`.
-
-If nothing is configured yet, these fallback agents are available by default:
+Three fallback agents ship with the extension (used when no user/project agents are configured):
 
 - `code-writer` — implementation and refactoring
 - `code-reviwer` — code review and risk finding
 - `code-architect` — technical design and approach selection
 
-Example agent (`~/.pi/agent/agents/writer.md`):
+## Defining Agents
+
+Create Markdown files with YAML frontmatter:
+
+- **User agents:** `~/.pi/agent/agents/*.md`
+- **Project agents:** `.pi/agents/*.md` *(may prompt for confirmation — see `PI_SUBAGENT_CONFIRM_PROJECT_AGENTS`)*
 
 ```markdown
 ---
 name: writer
-description: Expert technical writer and editor
+description: Expert technical writer
 model: anthropic/claude-3-5-sonnet
-tools: read, write
+thinking: low
+tools: read,write
 ---
 
-You are an expert technical writer. Your task is to improve the clarity and conciseness of the provided text.
+You are an expert technical writer focused on clarity and conciseness.
 ```
 
-Note: this repository includes bundled fallback agents in `agents/code-writer.md`, `agents/code-reviwer.md`, and `agents/code-architect.md`.
-
 ### Frontmatter Fields
 
-| Field         | Required | Default                          | Description                                                                                                                                                                |
-| ------------- | -------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`        | Yes      | —                                | Agent identifier used in tool calls (must match exactly)                                                                                                                   |
-| `description` | Yes      | —                                | What the agent does (shown to the main agent)                                                                                                                              |
-| `model`       | No       | Uses the default pi model        | Overrides the model for this agent. You can include a provider prefix (e.g. `anthropic/claude-3-5-sonnet` or `openrouter/claude-3.5-sonnet`) to force a specific provider. |
-| `thinking`    | No       | Uses Pi's default thinking level | Sets the thinking level (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`). Equivalent to `--thinking`.                                                                  |
-| `tools`       | No       | `read,bash,edit,write`           | Comma-separated list of **built-in** tools to enable for this agent. If omitted, defaults apply.                                                                           |
-
-Notes:
-
-- `model` accepts `provider/model` syntax — this is a Pi feature. Use it when multiple providers offer the same model ID.
-- `thinking` uses the same values as Pi's `--thinking` flag; it's recommended to set it explicitly since thinking support varies by model.
-- `tools` only controls built-in tools. Extension tools remain available unless extensions are disabled.
-- The Markdown body below the frontmatter becomes the agent's system prompt and is **appended** to Pi's default system prompt (it does **not** replace it).
+| Field         | Required | Default              | Description                                              |
+| ------------- | -------- | -------------------- | -------------------------------------------------------- |
+| `name`        | Yes      | —                    | Agent identifier used in tool calls                      |
+| `description` | Yes      | —                    | What the agent does (shown to the main agent)            |
+| `model`       | No       | Pi default           | Override model, e.g. `anthropic/claude-3-5-sonnet`       |
+| `thinking`    | No       | Pi default           | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`       |
+| `tools`       | No       | `read,bash,edit,write` | Comma-separated built-in tools                         |
 
-### Writing a Good Agent File
+Available tools: `read`, `bash`, `edit`, `write`.
 
-- **Description matters** — the main agent uses the `description` to decide which subagent to call, so be specific about what the agent is good at.
-- **Tool scope is optional but helpful** — reducing tools can keep the agent focused, but you can leave defaults if unsure.
-- **Model + thinking is the power combo** — selecting the right model and thinking level is often the biggest quality boost.
+The Markdown body becomes the agent's system prompt (appended to Pi's default, not replacing it).
 
-### Available Built-in Tools
+## Delegation Guards
 
-Available Tools (default: `read`, `bash`, `edit`, `write`):
+Depth and cycle guards prevent runaway recursive delegation.
 
-- `read` — Read file contents
-- `bash` — Execute bash commands
-- `edit` — Edit files with find/replace
-- `write` — Write files (creates/overwrites)
-- `grep` — Search file contents (read-only, off by default)
-- `find` — Find files by glob pattern (read-only, off by default)
-- `ls` — List directory contents (read-only, off by default)
+| Config                         | Default | Description                                      |
+| ------------------------------ | ------- | ------------------------------------------------ |
+| `--subagent-max-depth` / `PI_SUBAGENT_MAX_DEPTH` | `3` | Max delegation depth (0 disables delegation) |
+| `--subagent-prevent-cycles` / `PI_SUBAGENT_PREVENT_CYCLES` | `true` | Block same agent in delegation chain |
 
-Tip: for a read-only tool selection, use `read,find,ls,grep`. As soon as you include `edit`, `write`, or `bash`, the agent can practically go wild.
-
-## How Communication Works
+```bash
+pi --subagent-max-depth 2         # one nested level
+pi --subagent-max-depth 0         # disable delegation entirely
+pi --no-subagent-prevent-cycles   # allow cycles (not recommended)
+```
 
-### The Isolation Model
+## Parallel Limits
 
-Each subagent always runs in a **separate `pi` process**:
+| Env Var                          | Default | Description                              |
+| -------------------------------- | ------- | ---------------------------------------- |
+| `PI_SUBAGENT_MAX_PARALLEL_TASKS` | `16`    | Max tasks per single call                |
+| `PI_SUBAGENT_MAX_CONCURRENCY`    | `8`     | Max subagents running simultaneously     |
 
-- ❌ No shared memory/state with the parent process
-- ❌ No visibility into sibling subagents
-- ✅ Its own model/tool/runtime loop
-- ✅ Started with `PI_OFFLINE=1` to skip startup network operations and reduce spawn latency
+## CLI Argument Proxying
 
-What it can see depends on `mode`:
+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.
 
-- `spawn` (default)
-  - ✅ Receives: subagent system prompt + `Task: ...`
-  - ❌ Does **not** receive parent session history
-- `fork`
-  - ✅ Receives: forked snapshot of current parent session context + `Task: ...`
+**Always forwarded verbatim:**
 
-### What Gets Sent to Subagents
+| 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 |
 
-#### `spawn` mode (default)
+**Forwarded as fallback** (agent frontmatter overrides if set):
 
-`subagent({ tasks: [{ agent: "writer", task: "Document the API" }] })` sends:
+| Flag | Overridden by |
+| --- | --- |
+| `--model` | `model:` in agent frontmatter |
+| `--thinking` | `thinking:` in agent frontmatter |
+| `--tools` / `--no-tools` | `tools:` in agent frontmatter |
 
-```
-[System Prompt from ~/.pi/agent/agents/writer.md]
+**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`.
 
-User: Task: Document the API
-```
+---
 
-No parent conversation history is included. In `spawn`, include all required context in `task`.
+## Programmatic Usage (JSON RPC)
 
-#### `fork` mode
+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.
 
-`subagent({ tasks: [{ agent: "writer", task: "Document the API" }], mode: "fork" })` sends:
+### Stream event shape
 
 ```
-[Forked snapshot of current session context]
-[System Prompt from ~/.pi/agent/agents/writer.md]
-
-User: Task: Document the API
+tool_result_end
+└── message
+    ├── role:        "toolResult"
+    ├── toolName:    "subagent"
+    ├── toolCallId:  string
+    ├── isError:     boolean
+    ├── content:     [{ type: "text", text: "<final output>" }]
+    └── details:     SubagentDetails
 ```
 
-Note: `fork` copies session context, not transient runtime-only prompt mutations from the parent process.
-
-### What Comes Back to the Main Agent
-
-| Data                        | Main Agent Sees          | TUI Shows              |
-| --------------------------- | ------------------------ | ---------------------- |
-| Final text output           | ✅ Yes — full, unbounded | ✅ Yes                 |
-| Tool calls made by subagent | ❌ No                    | ✅ Yes (expanded view) |
-| Token usage / cost          | ❌ No                    | ✅ Yes                 |
-| Reasoning/thinking steps    | ❌ No                    | ❌ No                  |
-| Error messages              | ✅ Yes (on failure)      | ✅ Yes                 |
+### `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
+}
+```
 
-**Key point:** The main agent receives **only the final assistant text** from each subagent. Not the tool calls, not the reasoning, not the intermediate steps. This prevents context pollution while still giving you the results.
+### Important notes on stats
 
-### Parallel Mode Behavior
+- **`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.
 
-When running multiple agents in parallel:
+### Annotated example JSON
 
-- Subagents run concurrently up to `PI_SUBAGENT_MAX_CONCURRENCY` (default `8`)
-- The top-level `mode` applies to all tasks in that call
-- Main agent receives a combined result after all finish:
+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) ..."
+          ]
+        }
+      ]
+    }
+  }
+}
 ```
-Parallel: 3/3 succeeded
 
-[writer] completed: Full output text here...
-[tester] completed: Full output text here...
-[reviewer] completed: Full output text here...
+### 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;
+    }
+  }
+}
 ```
 
-## Features
+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.
 
-- **Auto-Discovery** — Agents are found at startup and their descriptions are injected into the main agent's system prompt.
-- **Context Mode Switch** — `spawn` (fresh context) and `fork` (session snapshot + task) per call.
-- **Depth + Cycle Guards** — Depth limiting and ancestry-cycle checks prevent runaway recursive delegation by default.
-- **Streaming Updates** — Watch subagent progress in real-time as tool calls and outputs stream in.
-- **Nested Delegation** — Subagents can call `subagent` again, subject to depth and cycle guards.
-- **Rich TUI Rendering** — Collapsed/expanded views with usage stats, nested delegation trees, tool call previews, and markdown output.
-- **Security Confirmation** — Project-local agents can require explicit user approval, with one-time and session-wide approval options.
+---
 
-## Project Structure
+## create-subagent Skill
 
-```
-index.ts    — Extension entry point: lifecycle hooks, tool registration, mode orchestration
-agents.ts   — Agent discovery: reads and parses .md files from user/project directories
-runner.ts   — Process runner: starts `pi` subprocesses in spawn/fork context modes and streams JSON events
-render.ts   — TUI rendering: renderCall and renderResult for the subagent tool
-types.ts    — Shared types and pure helper functions
-```
+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.
 
 ## Attribution
 
-Inspired by implementations from [vaayne/agent-kit](https://github.com/vaayne/agent-kit) and [mariozechner/pi-mono](https://github.com/badlogic/pi-mono).
+Inspired by [vaayne/agent-kit](https://github.com/vaayne/agent-kit) and [mariozechner/pi-mono](https://github.com/badlogic/pi-mono).
 
 ## License
 

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.2",
+  "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";