@clanker-code/pi-subagents 0.10.5

package/docs/superpowers/specs/2026-06-19-recursive-subagent-widget-design.md

@@ -0,0 +1,189 @@
+# Recursive Subagent Widget Design
+
+## Goal
+
+Show the full recursive subagent delegation tree in the TUI widget, including grandchildren and deeper descendants, with a rich default view, automatic compact fallback, and a focused path view for subagent-local context.
+
+## Verified current behavior
+
+The current `AgentWidget` renders only `manager.listAgents()` from its own extension instance. It groups records by status (`finished`, `running`, `queued`) and renders them as flat sibling lines. It does not build a tree from `parentAgentId`/`depth`, and descendants spawned by recursive subagents are owned by child extension/manager instances rather than the root widget manager.
+
+Evidence from source inspection:
+
+- `src/ui/agent-widget.ts` calls `this.manager.listAgents()` and renders flat `finishedLines`, `runningLines`, and `queuedLine` arrays.
+- `src/agent-manager.ts` records already include `depth` and `parentAgentId` metadata.
+- `src/index.ts` emits recursive lifecycle events with `depth` and `parentAgentId`, but the widget does not consume those events into a recursive aggregate.
+
+## Settled visual direction
+
+The browser preview lives at:
+
+- `reviews/recursive-subagent-widget-preview.html`
+- `reviews/recursive-subagent-widget-preview-rev2.png`
+
+Approved direction:
+
+1. Rich tree is the default.
+2. The widget automatically falls back to compact rendering when the terminal width, line budget, or tree size makes rich rendering too noisy.
+3. Users can configure rendering mode in settings.
+4. A focused path view is used inside subagent-local UI context to show “where this subagent sits in the tree.”
+
+## Render modes
+
+### Rich mode
+
+Rich mode is the default root widget view.
+
+Example shape:
+
+```text
+● Agents 3 running · 1 queued · depth 3/4
+├─ ⠋ Plan opus split task
+│  ⎿ ↻3≤20 · 4 tools · 22.8k token (38%) · 1m 12s
+│  ├─ ⠹ Explore inspect widget data flow
+│  │  ⎿ reading agent-widget.ts · 14.2s
+│  │  └─ ⠼ general-purpose trace manager ownership
+│  │     ⎿ searching tests · 4.8s
+│  └─ ✓ auditor review plan · 31s
+├─ ◦ Explore queued after concurrency cap
+└─ ✗ Plan old attempt error: model unavailable
+```
+
+Node content:
+
+- Connector glyphs show parent/child relationships.
+- Status icon/spinner shows queued/running/success/error/stopped/aborted.
+- Agent type and optional model/tags are shown on the main line.
+- Description is shown on the main line.
+- Activity/stat detail line is shown for active agents.
+- Terminal/error line can include a short error or terminal status.
+
+### Compact mode
+
+Compact mode renders one line per agent using the same tree structure and ordering, but omits the active detail line.
+
+Example shape:
+
+```text
+● Agents
+├─ ⠋ Plan split task · ↻3 · 2 tools · 1m 12s
+│  ├─ ⠹ Explore inspect UI · reading…
+│  └─ ✓ auditor review paths · 42s
+└─ ⠼ general-purpose write tests · editing…
+```
+
+### Auto fallback
+
+Default behavior is `rich` with automatic fallback to compact when rich mode would exceed the widget budget.
+
+Fallback triggers:
+
+- Terminal width is too narrow for readable rich lines.
+- Rich tree would exceed the configured widget line cap after subtree overflow summaries are applied.
+- Tree density is high enough that compact mode communicates more useful information than rich mode.
+
+Exact thresholds should be conservative and test-covered; the first implementation should prefer readability and bounded output over displaying every detail.
+
+### Focused path view
+
+Focused path view is for a subagent-local widget or future selectable mode. It answers: “where is this subagent in the recursive delegation tree?”
+
+Example shape:
+
+```text
+● Agents 7 total · showing active branch
+├─ ⠋ Plan split task · 1m 12s
+│  └─ ⠹ Explore inspect UI · reading…
+│     └─ ⠼ general-purpose trace manager · searching…
+├─ +2 completed siblings hidden
+└─ +2 queued / stale descendants hidden
+```
+
+## Tree data model
+
+Create a tree model separate from rendering. The model should be built from agent records and/or lifecycle snapshots.
+
+Required fields per node:
+
+- `id`
+- `parentAgentId`
+- `depth`
+- `type`
+- `description`
+- `status`
+- `startedAt`
+- `completedAt`
+- `error`
+- `toolUses`
+- `invocation`
+- live activity state when available
+- usage/turn/compaction stats when available
+
+The tree builder should:
+
+- Key all records by id.
+- Link children to parents by `parentAgentId`.
+- Treat missing parent records as orphans under an `Other agents` group.
+- Sort parent before descendants.
+- Sort active nodes before queued before recently terminal siblings within a sibling set.
+- Preserve stable ordering between renders to avoid visual jitter.
+
+## Recursive visibility source
+
+The root widget needs a durable aggregate that includes descendants from child manager instances. The design should prefer using existing lifecycle events over tight manager coupling:
+
+- `subagents:started`
+- `subagents:completed`
+- `subagents:failed`
+- `subagents:compacted`
+- existing direct manager records for live activity and direct children
+
+If lifecycle events do not carry enough live detail for rich rendering, extend event payloads narrowly rather than exposing child managers directly.
+
+## Settings
+
+Add a widget display setting with these values:
+
+- `auto` — default: rich rendering with compact fallback.
+- `rich` — prefer rich rendering; still apply subtree overflow to remain bounded.
+- `compact` — always render compact tree.
+
+The settings UI should label this as something like “Subagent widget display” with choices “Auto”, “Rich tree”, and “Compact tree.”
+
+## Overflow and truncation
+
+The widget must remain bounded.
+
+Rules:
+
+- Keep the existing `MAX_WIDGET_LINES` style cap, but apply it to a tree-aware layout.
+- Collapse whole subtrees where possible instead of arbitrary middle lines.
+- Show summary lines such as `└─ +4 descendants hidden (2 running, 1 queued, 1 finished)`.
+- Prioritize visible active paths over completed siblings.
+- Preserve width safety using existing `truncateToWidth` behavior.
+
+## Testing requirements
+
+Add deterministic tests for:
+
+1. A parent → child → grandchild tree renders with proper indentation/connectors.
+2. Grandchildren appear in the root widget aggregate.
+3. Compact mode uses one line per node.
+4. Auto mode falls back to compact under constrained width/height.
+5. Overflow collapses subtrees and reports correct hidden counts.
+6. Orphan records render under `Other agents`.
+7. Status bar counts include descendants.
+8. Existing width-safety and status-bar truncation tests continue to pass.
+
+## Non-goals for first implementation
+
+- Interactive expand/collapse controls inside the widget.
+- Persisted historical trees beyond the existing short linger window.
+- New public API for external extensions unless required by implementation evidence.
+- Reworking core subagent scheduling or completion delivery.
+
+## Open implementation notes
+
+- Verify whether child lifecycle events already propagate to the root extension’s event bus in real recursive sessions. If they do, use them. If not, add a narrow bridge for descendant lifecycle snapshots.
+- Keep rendering logic isolated from data aggregation so the tree model can be tested without the TUI.
+- Avoid changing the current Agent tool result renderer as part of this feature unless a test proves shared behavior is required.

package/examples/agent-tool-description.md

@@ -0,0 +1,45 @@
+Launch a new agent to handle complex, multi-step tasks autonomously. Each agent type has specific capabilities and tools available to it.
+
+Available agent types and the tools they have access to:
+{{typeList}}
+
+Custom agents can be defined in .pi/agents/<name>.md (project) or {{agentDir}}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.
+
+When using the Agent tool, specify a subagent_type parameter to select which agent type to use.
+
+## When not to use
+
+If the target is already known, use a direct tool — `read` for a known path, `grep`/`find` for a specific symbol or string. Reserve this tool for open-ended questions that span the codebase, or tasks that match an available agent type.
+
+## Usage notes
+
+- Always include a short (3-5 word) description summarizing what the agent will do (shown in UI).
+- When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently. If the user specifies that they want agents run "in parallel", you MUST send a single message with multiple tool calls.
+- When the agent is done, it returns a single message back to you. The result is not visible to the user — to show the user, send a text message with a concise summary.
+- Trust but verify: an agent's summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting work as done.
+- Agents always run in the background. You will be notified when each completes — do NOT poll or sleep waiting for it. Continue with other work or respond to the user instead.
+- Background by default: when useful independent work exists, launch it and keep going. Doing nothing while an agent runs is worse than using background capacity.
+- {{recursiveGuideline}}
+- Use get_subagent_result if you need to retrieve a result before the completion notification arrives, but do not poll or sleep waiting for it.
+- Use resume with an agent ID to continue a previous agent's work. A new (non-resume) Agent call starts a fresh agent with no memory of prior runs, so the prompt must be self-contained.
+- Use list_models to enumerate the model registry the `model:` param accepts before passing a model name explicitly.
+- Use steer_subagent to send mid-run messages to a running background agent.
+- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, etc.), since it is not aware of the user's intent.
+- If an agent's description says it should be used proactively, try to use it without the user having to ask for it first.
+- Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
+- Use thinking to control extended thinking level.
+- Use inherit_context if the agent needs the parent conversation history.
+- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications). The worktree is automatically cleaned up if the agent makes no changes; otherwise the path and branch are returned in the result.{{scheduleGuideline}}
+
+## Writing the prompt
+
+Provide clear, detailed prompts so the agent can work autonomously. Brief it like a smart colleague who just walked into the room — it hasn't seen this conversation, doesn't know what you've tried, doesn't understand why this task matters.
+- Explain what you're trying to accomplish and why.
+- Describe what you've already learned or ruled out.
+- Give enough context about the surrounding problem that the agent can make judgment calls rather than just following a narrow instruction.
+- If you need a short response, say so ("report in under 200 words").
+- Lookups: hand over the exact command. Investigations: hand over the question — prescribed steps become dead weight when the premise is wrong.
+
+Terse command-style prompts produce shallow, generic work.
+
+**Never delegate understanding.** Don't write "based on your findings, fix the bug" or "based on the research, implement it." Those phrases push synthesis onto the agent instead of doing it yourself. Write prompts that prove you understood: include file paths, line numbers, what specifically to change.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@clanker-code/pi-subagents",
+  "version": "0.10.5",
+  "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
+  "author": "clankercode",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/clankercode/pi-subagents.git"
+  },
+  "homepage": "https://github.com/clankercode/pi-subagents#readme",
+  "bugs": {
+    "url": "https://github.com/clankercode/pi-subagents/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "subagent",
+    "agent",
+    "autonomous"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.74.0",
+    "@earendil-works/pi-coding-agent": ">=0.74.0",
+    "@earendil-works/pi-tui": ">=0.74.0"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.49",
+    "croner": "^10.0.1",
+    "nanoid": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "vitest run e2e --reporter=verbose",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/ test/",
+    "lint:fix": "biome check --fix src/ test/"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.0",
+    "vitest": "^4.0.18"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "video": "https://github.com/clankercode/pi-subagents/raw/master/media/demo.mp4",
+    "image": "https://github.com/clankercode/pi-subagents/raw/master/media/screenshot.png"
+  }
+}

package/reviews/proposal-structured-output-schema.md

@@ -0,0 +1,135 @@
+# Proposal: Structured JSON Output for Subagents
+
+**Date:** 2026-06-19  
+**Status:** Proposal / draft  
+**Related:** `reviews/subagent-features-comparison.md`
+
+## Problem
+
+Today, subagents return free-form text. The parent model must parse the text to extract lists, file paths, decisions, or any other structured data before it can feed results into the next tool or agent. This is slow, unreliable, and becomes a bottleneck when chaining multiple agents together.
+
+## Goal
+
+Add an optional `output_schema` parameter to the `Agent` tool. When supplied, the agent must return JSON matching the schema. The extension validates the output and surfaces either the parsed object or a clear validation error.
+
+The feature must be strictly opt-in: the default is free-form text, and agents should only use structured output when the caller explicitly needs it.
+
+## Design
+
+### Tool parameter
+
+Add to the `Agent` tool schema:
+
+```ts
+output_schema: Type.Optional(
+  Type.Union([Type.String(), Type.Object({})], {
+    description:
+      'Optional JSON Schema the agent\'s final answer must match. "": free-form text (recommended default; only use this when the consumer needs structured data).',
+  })
+),
+```
+
+- Accepts either a JSON Schema object or a JSON-stringified schema.
+- Default is `undefined` / `""` → free-form text, no validation.
+- The schema type is JSON Schema, the same standard already used for tool-call schemas in pi.
+
+### Frontmatter support
+
+Optionally allow agent `.md` files to pin a default schema:
+
+```yaml
+---
+output_schema:
+  type: object
+  properties:
+    files:
+      type: array
+      items:
+        type: object
+        properties:
+          path: { type: string }
+          reason: { type: string }
+        required: [path, reason]
+  required: [files]
+---
+```
+
+The caller-supplied `output_schema` overrides the frontmatter value. This lets custom agent types advertise a structured contract without every caller repeating it.
+
+### Prompt injection
+
+When `output_schema` is non-empty, append a concise instruction to the agent system prompt:
+
+> Your final answer must be a single JSON object matching the provided JSON Schema. Do not wrap the JSON in markdown fences, do not add commentary outside the JSON, and do not emit any text after the JSON object.
+
+### Validation
+
+On agent completion:
+
+1. Extract the last JSON object from the final assistant message.
+2. If the output is wrapped in markdown fences, strip them.
+3. Validate the parsed object against the JSON Schema using a lightweight validator (e.g. `ajv` or TypeBox's `Value.Check`).
+4. If validation fails:
+   - Mark the agent status as `failed`.
+   - Return an error message containing the schema validation errors and a snippet of the raw output.
+5. If validation passes:
+   - Include the parsed object in the result under a `structured` field.
+   - Keep the normal textual result preview so the notification UI stays readable.
+
+### Result shape
+
+For a structured agent, the result should expose:
+
+```json
+{
+  "ok": true,
+  "data": { "files": [...] },
+  "preview": "Found 5 auth-related files..."
+}
+```
+
+For failures:
+
+```json
+{
+  "ok": false,
+  "error": "Output did not match the provided JSON Schema",
+  "validationErrors": [...],
+  "rawPreview": "..."
+}
+```
+
+### Notification and join modes
+
+Structured output does not change the notification path. Background agents still send steering-style notifications. The XML payload can include a `<structured-output>` block with the serialized JSON so the parent model can reason about it directly.
+
+### Interaction with existing features
+
+- **Worktree isolation:** unchanged; the structured result is still returned through the normal completion path.
+- **Scheduling:** scheduled agents may use `output_schema` so recurring jobs produce machine-readable results.
+- **Resume:** resuming a structured agent does not re-validate old output; only the final completion is validated.
+- **Cross-extension RPC:** `output_schema` is serializable JSON and can be passed through the RPC spawn envelope.
+
+## Acceptance criteria
+
+- [ ] `Agent` tool accepts optional `output_schema` as JSON Schema object or string.
+- [ ] Default behavior remains free-form text; no validation when omitted.
+- [ ] Frontmatter supports optional `output_schema`.
+- [ ] System prompt instructs the agent to emit only matching JSON.
+- [ ] Output is parsed and validated strictly on completion.
+- [ ] Validation failures produce a clear error with the raw output snippet.
+- [ ] Validation successes expose parsed data in result notifications and RPC responses.
+- [ ] Tests cover valid schema, invalid schema, fenced JSON, and missing schema cases.
+- [ ] `npm run typecheck` and `npm run lint` pass.
+
+## Open questions
+
+1. Should we add a small built-in helper agent type that demonstrates structured output (e.g. `json-explorer`)?
+2. Should `output_schema` be surfaced in `/agents` agent-type descriptions so the orchestrator knows which agents return structured data?
+3. Should failed validation trigger automatic retry with a steering message, or fail fast?
+
+## Rationale
+
+JSON Schema was chosen because it is the same standard already used for pi tool definitions. Agents and users do not need to learn a new format, and existing tooling (TypeBox, `ajv`) integrates cleanly.
+
+Strict validation keeps the contract trustworthy. If a consumer asks for structured output, receiving invalid data is worse than receiving no data, because the consumer is likely to feed it into code that assumes correctness.

package/reviews/recursive-subagent-widget-preview.html

@@ -0,0 +1,137 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Recursive Subagents Widget Preview</title>
+  <style>
+    :root {
+      color-scheme: dark;
+      --bg: #0b1020;
+      --panel: #121a2d;
+      --terminal: #070b13;
+      --line: #29364f;
+      --text: #dbe7ff;
+      --muted: #7f8daa;
+      --dim: #566176;
+      --accent: #82aaff;
+      --green: #8bdc9f;
+      --yellow: #ffd479;
+      --red: #ff7f8f;
+      --cyan: #7ee7f5;
+      --purple: #c099ff;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      background: radial-gradient(circle at 20% 0%, #1b2b50 0, transparent 35%), var(--bg);
+      color: var(--text);
+      font: 14px/1.45 ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }
+    main { max-width: 1220px; margin: 0 auto; padding: 32px; }
+    h1 { font-size: 28px; margin: 0 0 8px; }
+    h2 { font-size: 18px; margin: 28px 0 12px; color: #f0f5ff; }
+    h3 { font-size: 14px; margin: 0 0 10px; color: var(--accent); text-transform: uppercase; letter-spacing: .08em; }
+    p { color: #b9c6df; margin: 0 0 14px; }
+    .grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 18px; align-items: start; }
+    .card { background: color-mix(in srgb, var(--panel) 92%, white 8%); border: 1px solid var(--line); border-radius: 16px; padding: 18px; box-shadow: 0 12px 40px rgba(0,0,0,.25); }
+    .recommended { border-color: color-mix(in srgb, var(--accent) 70%, white 10%); box-shadow: 0 0 0 1px rgba(130,170,255,.15), 0 18px 55px rgba(22,41,82,.5); }
+    .terminal { background: var(--terminal); border: 1px solid #1e2a3e; border-radius: 12px; padding: 12px 14px; font: 13px/1.35 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; white-space: pre; overflow: hidden; min-height: 260px; }
+    .term-title { display: flex; gap: 6px; align-items: center; margin-bottom: 10px; color: var(--muted); font: 12px ui-monospace, monospace; }
+    .dot { width: 9px; height: 9px; border-radius: 999px; display: inline-block; }
+    .green { color: var(--green); } .yellow { color: var(--yellow); } .red { color: var(--red); } .cyan { color: var(--cyan); } .purple { color: var(--purple); }
+    .muted { color: var(--muted); } .dim { color: var(--dim); } .accent { color: var(--accent); }
+    .legend { display: flex; flex-wrap: wrap; gap: 10px; margin-top: 10px; color: var(--muted); font-size: 12px; }
+    .plan { display: grid; grid-template-columns: 1.2fr .8fr; gap: 18px; }
+    ol, ul { margin: 0; padding-left: 20px; color: #c4cee2; }
+    li { margin: 6px 0; }
+    .pill { display: inline-flex; align-items: center; gap: 6px; padding: 3px 8px; border-radius: 999px; background: #1b2740; border: 1px solid #344260; color: #cfd9ef; font-size: 12px; }
+    .wide { grid-column: 1 / -1; }
+    @media (max-width: 980px) { .grid, .plan { grid-template-columns: 1fr; } }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>Recursive Subagents Widget — Plan + Visual Preview</h1>
+    <p>Verified issue: the current widget is flat and bound to one manager instance. It does not assemble a durable parent → child → grandchild tree from recursive agent metadata.</p>
+
+    <section class="plan">
+      <div class="card">
+        <h2>Implementation plan, once design is approved</h2>
+        <ol>
+          <li>Create a small tree model layer: records keyed by id, linked by <code>parentAgentId</code>, sorted by start time/status.</li>
+          <li>Teach lifecycle events / shared manager state to surface descendants to the root widget, not only direct children.</li>
+          <li>Add configurable widget modes: <code>compact</code> (Option A), <code>rich</code> (Option B), and <code>auto</code>.</li>
+          <li>Use the focused path view (Option C) when rendering from inside a subagent, or as an optional display mode later.</li>
+          <li>Add deterministic tests for parent → child → grandchild rendering, overflow, width truncation, completed/error linger, and mode switching.</li>
+          <li>Keep status bar compact: aggregate running/queued counts across the full tree.</li>
+        </ol>
+      </div>
+      <div class="card">
+        <h2>Acceptance criteria</h2>
+        <ul>
+          <li>Grandchildren and deeper descendants are visible.</li>
+          <li>Users can choose compact vs rich rendering in settings.</li>
+          <li>Subagents can see their location in the larger recursive tree.</li>
+          <li>Width/height bounded; no TUI overflow.</li>
+          <li>Running activity remains live and readable.</li>
+          <li>Completed/error states linger briefly in context.</li>
+        </ul>
+      </div>
+    </section>
+
+    <h2>Design options</h2>
+    <div class="grid">
+      <article class="card">
+        <h3>Mode: Compact tree</h3>
+        <div class="terminal"><div class="term-title"><span class="dot" style="background:#ff5f57"></span><span class="dot" style="background:#ffbd2e"></span><span class="dot" style="background:#28c840"></span><span>Agents widget</span></div><span class="accent">● Agents</span>
+├─ <span class="green">⠋</span> <b>Plan</b>  split task <span class="dim">· ↻3 · 2 tools · 1m 12s</span>
+│  ├─ <span class="green">⠹</span> <b>Explore</b>  inspect UI <span class="dim">· reading…</span>
+│  └─ <span class="yellow">✓</span> <b>auditor</b>  review paths <span class="dim">· 42s</span>
+└─ <span class="green">⠼</span> <b>general-purpose</b>  write tests <span class="dim">· editing…</span></div>
+        <p><b>Use as:</b> configurable mode <code>compact</code>. <b>Pros:</b> dense, low-risk, close to current widget. <b>Cons:</b> less rich for deep trees.</p>
+      </article>
+
+      <article class="card recommended">
+        <h3>Mode: Rich tree (default)</h3>
+        <div class="terminal"><div class="term-title"><span class="dot" style="background:#ff5f57"></span><span class="dot" style="background:#ffbd2e"></span><span class="dot" style="background:#28c840"></span><span>Agents widget</span></div><span class="accent">● Agents</span> <span class="muted">3 running · 1 queued · depth 3/4</span>
+├─ <span class="green">⠋</span> <b>Plan</b> <span class="purple">opus</span> <span class="muted">split task</span>
+│  <span class="dim">⎿ ↻3≤20 · 4 tools · 22.8k token (38%) · 1m 12s</span>
+│  ├─ <span class="green">⠹</span> <b>Explore</b> <span class="muted">inspect widget data flow</span>
+│  │  <span class="dim">⎿ reading agent-widget.ts · 14.2s</span>
+│  │  └─ <span class="green">⠼</span> <b>general-purpose</b> <span class="muted">trace manager ownership</span>
+│  │     <span class="dim">⎿ searching tests · 4.8s</span>
+│  └─ <span class="yellow">✓</span> <b>auditor</b> <span class="muted">review plan</span> <span class="dim">· 31s</span>
+├─ <span class="cyan">◦</span> <b>Explore</b> <span class="muted">queued after concurrency cap</span>
+└─ <span class="red">✗</span> <b>Plan</b> <span class="muted">old attempt</span> <span class="red">error: model unavailable</span></div>
+        <p><b>Use as:</b> configurable mode <code>rich</code>, recommended default. <b>Pros:</b> best visibility; activity/stats are readable; relationships are obvious. <b>Cons:</b> needs careful overflow rules.</p>
+      </article>
+
+      <article class="card">
+        <h3>Focused subagent location view</h3>
+        <div class="terminal"><div class="term-title"><span class="dot" style="background:#ff5f57"></span><span class="dot" style="background:#ffbd2e"></span><span class="dot" style="background:#28c840"></span><span>Agents widget</span></div><span class="accent">● Agents</span> <span class="muted">7 total · showing active branch</span>
+├─ <span class="green">⠋</span> <b>Plan</b>  split task <span class="dim">· 1m 12s</span>
+│  └─ <span class="green">⠹</span> <b>Explore</b>  inspect UI <span class="dim">· reading…</span>
+│     └─ <span class="green">⠼</span> <b>general-purpose</b>  trace manager <span class="dim">· searching…</span>
+├─ <span class="dim">+2 completed siblings hidden</span>
+└─ <span class="dim">+2 queued / stale descendants hidden</span></div>
+        <p><b>Use as:</b> view shown inside a subagent session to answer “where am I in the tree?” It can also become a selectable mode later. <b>Pros:</b> very compact under load.</p>
+      </article>
+    </div>
+
+    <section class="card wide" style="margin-top:18px;">
+      <h2>Settled direction so far</h2>
+      <p><span class="pill">rich default</span> <span class="pill">compact setting</span> <span class="pill">focused subagent view</span></p>
+      <p>Build one recursive tree model, then render it through multiple views. The root TUI widget can use <code>rich</code>, <code>compact</code>, or <code>auto</code>. A subagent-local widget can render the focused path view so the agent/operator sees the current subagent’s location in the whole delegation tree.</p>
+      <ul>
+        <li><b>Header:</b> aggregate full-tree counts and max observed depth.</li>
+        <li><b>Rich node:</b> connector + status icon/spinner + agent type + model/tag chips + description, plus detail line.</li>
+        <li><b>Compact node:</b> same tree structure, one line per agent, fewer stats.</li>
+        <li><b>Focused node:</b> ancestor path + current active branch + hidden sibling summaries.</li>
+        <li><b>Overflow:</b> collapse by subtree: <code>└─ +4 descendants hidden (2 running, 1 queued, 1 finished)</code>.</li>
+        <li><b>Fallback:</b> orphan records render under <code>Other agents</code> with a dim warning marker.</li>
+      </ul>
+    </section>
+  </main>
+</body>
+</html>