@clanker-code/pi-subagents 0.10.5 → 0.10.7

package/src/notifications.ts

@@ -30,12 +30,14 @@ export function formatTaskNotification(record: AgentRecord, resultMaxLen: number
 
   const resultPreview = record.result
     ? record.result.length > resultMaxLen
-      ? record.result.slice(0, resultMaxLen) + "\n...(truncated, use get_subagent_result for full output)"
+      ? record.result.slice(0, resultMaxLen) + (record.outputFile
+        ? "\n...(truncated, use get_subagent_result for a bounded preview or inspect the transcript file)"
+        : "\n...(truncated, use get_subagent_result for a bounded preview)")
       : record.result
     : "No output.";
   const fullOutputInstruction = record.outputFile
-    ? `Read the full output/log with get_subagent_result for agent ${record.id}, or inspect the transcript file: ${record.outputFile}`
-    : `Read the full output/log with get_subagent_result for agent ${record.id}.`;
+    ? `Read a bounded preview with get_subagent_result for agent ${record.id}, or inspect the full transcript file: ${record.outputFile}`
+    : `Read a bounded preview with get_subagent_result for agent ${record.id}.`;
 
   return [
     `<task-notification>`,
@@ -106,8 +108,8 @@ export function registerSubagentNotificationRenderer(pi: ExtensionAPI): void {
         }
 
         const fullOutputHint = d.outputFile
-          ? `full output: get_subagent_result ${d.id} or transcript: ${d.outputFile}`
-          : `full output: get_subagent_result ${d.id}`;
+          ? `bounded preview: get_subagent_result ${d.id}; full transcript: ${d.outputFile}`
+          : `bounded preview: get_subagent_result ${d.id}`;
         line += "\n  " + theme.fg("muted", fullOutputHint);
 
         return line;

package/src/peek.ts

@@ -15,6 +15,7 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
+import { clampPeekLines, formatOutputFileHint, limitText, MAX_PEEK_CHARS, MAX_PEEK_LINES } from "./bounded-output.js";
 import type { AgentRecord } from "./types.js";
 
 export interface PeekOptions {
@@ -35,9 +36,6 @@ export interface PeekResult {
   source: "outputFile" | "result";
 }
 
-/** Default number of tail lines when neither `after` nor `lines` is given. */
-const DEFAULT_LINES = 20;
-
 /**
  * Produce a peek view of an agent's output. Returns null when there is no
  * source content at all (the caller renders a "no output yet" message).
@@ -48,27 +46,39 @@ export function peekAgentOutput(record: AgentRecord, opts: PeekOptions = {}): Pe
 
   const regex = opts.regex ? compileRegex(opts.regex) : undefined;
   const after = typeof opts.after === "number" ? opts.after : -1;
-  const tail = typeof opts.lines === "number" && opts.lines >= 1 ? opts.lines : DEFAULT_LINES;
+  const tail = clampPeekLines(opts.lines);
 
   // Index each source line with its original position (1-based for display).
   const indexed = lines.map((text, i) => ({ no: i + 1, text }));
 
   // Filter-then-select.
   const filtered = regex ? indexed.filter((l) => regex.test(l.text)) : indexed;
-  const selected =
-    after >= 0
-      ? filtered.filter((l) => l.no > after)
-      : filtered.slice(-tail);
+  const matching = after >= 0 ? filtered.filter((l) => l.no > after) : filtered;
+  const selected = after >= 0 ? matching.slice(0, MAX_PEEK_LINES) : matching.slice(-tail);
+  const lineLimited = matching.length > selected.length;
 
   const totalLines = lines.length;
   const isRunning = record.status === "running" || record.status === "queued";
   const source: PeekResult["source"] =
     isRunning && record.outputFile && existsSync(record.outputFile) ? "outputFile" : "result";
 
-  const header = buildHeader(opts, selected.length, totalLines, source);
+  const header = buildHeader(opts, selected.length, totalLines, source, tail, lineLimited, matching.length);
   const body = selected.map((l) => `[${l.no}] ${l.text}`).join("\n");
+  const limited = limitText(body, MAX_PEEK_CHARS);
+  const lastLine = selected.at(-1)?.no;
+  const notices: string[] = [];
+  if (lineLimited && lastLine !== undefined) {
+    notices.push(`Peek limited to ${MAX_PEEK_LINES} lines from ${matching.length} matching lines. Use peek.after: ${lastLine} to continue.`);
+  }
+  if (limited.truncated) {
+    notices.push(`Peek output truncated by ${limited.omittedChars} chars. Use a smaller lines value or regex filter.${formatOutputFileHint(record.outputFile)}`);
+  }
 
-  return { text: `${header}\n\n${body}`, totalLines, source };
+  return {
+    text: `${header}\n\n${limited.text}${notices.length ? `\n\n---\n${notices.join("\n")}` : ""}`,
+    totalLines,
+    source,
+  };
 }
 
 /** Read the most useful text lines from the agent's output. */
@@ -141,13 +151,16 @@ function buildHeader(
   shown: number,
   total: number,
   source: PeekResult["source"],
+  tail: number,
+  lineLimited: boolean,
+  matching: number,
 ): string {
   const parts: string[] = [];
   if (typeof opts.after === "number") {
     parts.push(`after line number ${opts.after}`);
+    if (lineLimited) parts.push(`limited to ${MAX_PEEK_LINES} lines from ${matching} matching lines`);
   } else {
-    const n = typeof opts.lines === "number" && opts.lines >= 1 ? opts.lines : DEFAULT_LINES;
-    parts.push(`last ${n} lines`);
+    parts.push(`last ${tail} lines`);
   }
   if (opts.regex) parts.push(`filtered by regex /${opts.regex}/`);
   parts.push(`of ${total} total (${source === "outputFile" ? "live output file" : "result"})`);

package/.plans/PLAN-next-changes.md

@@ -1,183 +0,0 @@
-# Plan: Next pi-subagents improvements
-
-This plan covers four coordinated changes:
-1. **Abort-detach + interruptible/timeout wait** for `get_subagent_result wait:true` (Escape no longer wedges the turn; default 4.5 min timeout).
-2. Configurable `waitTimeoutSeconds` setting (default 270s) exposed in `/agents → Settings`.
-3. `get_subagent_result` peek/tail capability with line numbers, regex filter, and `after` line offset.
-4. Description polish for `inherit_context` and `isolation: "worktree"`.
-
-All changes are scoped to keep diffs minimal and upstream-merge-friendly.
-
-### Key finding (abort-detach)
-Background spawns already do NOT pass the parent abort signal to `manager.spawn()` — only the now-dead foreground path did. So background subagents are already detached from Escape. The Escape-wedge symptom comes from `get_subagent_result wait:true`, which awaits `record.promise` and ignores the parent `signal`. Fix: race the wait against (a) the parent abort `signal` and (b) the configurable timeout, returning current status on either WITHOUT aborting the subagent.
-
----
-
-## 1. Settings foundation: configurable `waitTimeoutSeconds`
-
-### Motivation
-Users want to avoid typical 5-minute LLM cache expiry; 4.5 minutes is a safe default. We also want this exposed in `/agents → Settings` so it is discoverable and adjustable per project.
-
-### Files touched
-- `src/types.ts` — add `waitTimeoutSeconds` to `AgentRecord`? No, this is runtime/config, not per-agent. Keep it in settings only.
-- `src/settings.ts`:
-  - Add `waitTimeoutSeconds?: number` to `SubagentsSettings`.
-  - Add `setWaitTimeoutSeconds: (seconds: number) => void` to `SettingsAppliers`.
-  - Add sanitize rule: integer, min 30, max 3600 (30s–1h). Default 270 (4.5m) when absent.
-  - Add `applySettings` wiring.
-- `src/index.ts`:
-  - Add `let waitTimeoutSeconds = 270` and getter/setter.
-  - Add to `snapshotSettings()`.
-  - Add `/agents → Settings` item with id `waitTimeoutSeconds`.
-  - Wire `applyValue` for `waitTimeoutSeconds` (numeric prompt, 30–3600).
-  - Add to `applyAndEmitLoaded` appliers object.
-  - Pass timeout value into `get_subagent_result` execute closure.
-
-### Return value / UI impact
-- `get_subagent_result` `wait` description: mention current configured timeout.
-- On timeout, return message:
-  ```
-  Agent is still running after 4 minutes 30 seconds.
-  This wait timed out to avoid blocking the parent session longer than the configured limit.
-  Call get_subagent_result with wait: true again to keep waiting, or omit wait to check status.
-  ```
-
-### Tests
-- `test/settings.test.ts` (if exists) or new assertions in `test/settings.test.ts`: sanitize boundaries.
-- New/updated test for `get_subagent_result` timeout behavior using a mocked promise and fake timers.
-
----
-
-## 2. `get_subagent_result` peek parameter
-
-### Motivation
-Agents should be able to cheaply check recent output / logs without fetching the full result or conversation.
-
-### Proposed schema
-```ts
-peek: Type.Optional(
-  Type.Object({
-    lines: Type.Optional(Type.Number({ minimum: 1, description: "Number of trailing lines to return. Default: 20." })),
-    regex: Type.Optional(Type.String({ description: "Optional regex filter. Only lines matching this regex are included." })),
-    after: Type.Optional(Type.Number({ minimum: 0, description: "Return all lines after this 0-based line index. Overrides lines when set." })),
-  }, {
-    description: "Return a peek (tail/filter/update) of the agent result or streaming output file. Ignored when verbose is true.",
-  }),
-),
-```
-
-### Behavior
-- `peek` is ignored when `verbose: true`.
-- If `after` is set, return all lines with index > `after` (or >= `after+1`). Include line numbers.
-- Else, return the last `lines` lines (default 20). Include line numbers.
-- If `regex` is provided, filter matching lines **first**, then apply tail/after semantics. Include line numbers of the original source.
-- Source precedence:
-  1. If agent is running and `record.outputFile` exists, read from the streaming output file. Parse JSONL and extract assistant/toolResult text (most useful live content).
-  2. Else if `record.result` exists, split it into lines.
-  3. Else return: "No output yet."
-
-### Return format
-```
-Showing last 20 lines of agent output (line numbers from full output):
-
-[42] some line
-[43] another line
-...
-
----
-Use verbose: true for the full conversation, or omit peek for the complete result.
-```
-
-If `regex` is used, add: `(filtered by regex: /.../)`.
-If `after` is used, add: `(lines after index N)`.
-
-### Implementation notes
-- Add helper `peekAgentOutput(record, peek)` in a new file or in `src/index.ts` near `get_subagent_result`.
-- For output-file JSONL parsing, reuse/extract from `output-file.ts` or read the file line-by-line.
-- Handle regex parse errors gracefully — return a clear error message.
-- Avoid reading the whole file into memory if possible; for now `readFileSync` is acceptable because output files are bounded by session length and the tail case is common.
-
-### Tests
-- New test file `test/get-subagent-result-peek.test.ts` or extend existing `status-note-wiring.test.ts`:
-  - Peek tail of result.
-  - Peek with regex.
-  - Peek `after` offset.
-  - Peek ignored when verbose true.
-  - Peek on running agent with output file.
-  - Regex parse error handling.
-
----
-
-## 3. Description polish
-
-### `inherit_context`
-Current:
-> "If true, fork parent conversation into the agent. Default: false (fresh context)."
-
-New:
-> "If true, fork the parent conversation into the agent so it sees the chat history. Recommended for questions or requests that require current context. Default: false (fresh context)."
-
-Also update the eject template line in `src/index.ts`.
-
-### `isolation: "worktree"`
-Current:
-> "Set to 'worktree' to run the agent in a temporary git worktree (isolated copy of the repo). Changes are saved to a branch on completion."
-
-New:
-> "Set to 'worktree' to run the agent in a temporary git worktree that is automatically created from the current repo state at HEAD and removed on completion. Changes are saved to a branch. Requires the working directory to be a git repo with at least one commit."
-
-Also update README.md and `examples/agent-tool-description.md` to match.
-
----
-
-## 4. Coordination / cross-cutting concerns
-
-- `get_subagent_result` description must mention the configurable timeout, e.g.:
-  > "If true, wait for the agent to complete before returning. Blocks up to the configured wait timeout (default 4.5 minutes). If the agent is still running when the timeout is reached, returns current status with instructions to call again. Default: false."
-
-- The settings UI should present `waitTimeoutSeconds` as "Wait timeout (30–3600s, default 270 = 4m30s)".
-
-- Tests for the timeout should use Vitest fake timers so they run fast and deterministically.
-
-- Peek should not duplicate verbose. Keep the contract: `verbose` = full conversation, `peek` = lightweight tail/filter.
-
----
-
-## 5. Things to consider removing / avoiding
-
-Before jumping in, review whether any existing code becomes dead weight:
-
-- The foreground execution path in `src/index.ts` is now dead code after the background-by-default change. We currently left it in place but unreachable. Consider whether to remove it in a separate cleanup pass (it complicates future changes).
-- `run_in_background` param is deprecated but still in the schema. Keep it for prompt compatibility; do not remove.
-- `AgentConfig.runInBackground` frontmatter default is still consulted by `resolveAgentInvocationConfig`. Since `index.ts` now forces `runInBackground = true`, the frontmatter field is effectively ignored. Consider whether to deprecate it in docs or leave it as a no-op.
-
----
-
-## 6. Acceptance criteria
-
-- [ ] `get_subagent_result wait:true` times out after the configured number of seconds and returns a clear message.
-- [ ] Timeout duration is configurable via `/agents → Settings` and persists to `.pi/subagents.json`.
-- [ ] `get_subagent_result` supports `peek` with `lines`, `regex`, and `after`.
-- [ ] `peek` returns line numbers and respects `verbose: true` (is ignored).
-- [ ] `inherit_context` and `isolation` descriptions are updated in tool schema, eject template, README, and example template.
-- [ ] All existing tests pass; new tests cover timeout + peek.
-- [ ] `npm run typecheck` and `npm run lint` clean.
-
----
-
-## 7. Implementation order
-
-1. Add `waitTimeoutSeconds` setting (settings.ts + index.ts wiring).
-2. Implement wait timeout in `get_subagent_result` execute.
-3. Add `peek` parameter + helper.
-4. Update descriptions for `inherit_context` and `isolation`.
-5. Update README + example template.
-6. Write tests.
-7. Run full test/typecheck/lint.
-
---- SUMMARY ---
-
-- Add a configurable `waitTimeoutSeconds` setting (default 270s) wired into `/agents → Settings` and `get_subagent_result wait:true`.
-- Add a `peek` object param to `get_subagent_result` for tail/filter/offset access to result/output-file with line numbers, ignored when `verbose` is true.
-- Polish `inherit_context` and `isolation: "worktree"` descriptions across schema, template, README, and example.
-- Tests, typecheck, lint.

package/.plans/README.md

@@ -1,14 +0,0 @@
-# `.plans/` — local planning scratch
-
-This directory holds ad-hoc plans, notes, and design sketches for this fork. It is gitignored so it does not pollute upstream diffs.
-
-## Conventions
-
-- One plan per file: `PLAN-<short-name>.md`.
-- Plans should include: motivation, files touched, behavior changes, UI/message changes, tests, acceptance criteria, implementation order, and a summary.
-- When a plan graduates to implementation, update the plan file with progress or archive it.
-- Delete obsolete plans to avoid stale guidance.
-
-## Active plans
-
-- `PLAN-next-changes.md` — configurable `get_subagent_result` wait timeout, peek/tail/regex/after parameter, and description polish for `inherit_context` / `isolation: "worktree"`.

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

@@ -1,135 +0,0 @@
-# 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

@@ -1,137 +0,0 @@
-<!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>