@d3ara1n/pi-subagent 1.7.1 → 2.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 Role-based subagent orchestration for [pi](https://github.com/earendil-works/pi).
 
-Provides a `subagent_delegate` tool that lets the main model offload tasks to specialized pi child processes with configurable model roles, real-time TUI progress, and AI-generated summaries. Runs can be foreground (blocking) or background (asynchronous, collected later via `subagent_wait`/`subagent_check`, cancellable via `subagent_cancel`). A centered live view (`/subagent:view`) shows every run's activity feed as it happens, and mid-run corrections can be queued into a running subagent from the view's input box or via `subagent_steer`.
+Provides a `subagent_delegate` tool that lets the main model offload tasks to specialized pi child processes with configurable model roles, real-time TUI progress, and AI-generated summaries. Runs can be foreground (blocking) or background (asynchronous, collected later via `subagent_wait`/`subagent_check`, cancellable via `subagent_cancel`). A centered live view (`/subagent:view`) shows every run's activity feed as it happens, with a per-run brief page for inputs and stats; mid-run corrections can be queued into a running subagent from the view's steer editor or via `subagent_steer`.
 
 ## Design Philosophy
 
@@ -23,7 +23,7 @@ This means:
 
 1. Main model calls the `subagent_delegate` tool with a role and task description
 2. The extension resolves the role to a model via pi-model-roles
-3. Spawns an isolated pi child process in RPC mode (`--mode rpc`) with the configured model, tools, and system prompt — agent events stream back over stdout while stdin carries the initial prompt and mid-run steering commands
+3. Spawns an isolated pi child process in RPC mode (`--mode rpc`) with the configured model, tools, and system prompt — agent events stream back over stdout while stdin carries the initial prompt and mid-run steering commands. Children are headless: interactive extension dialogs (`ctx.ui.select/confirm/input`) are answered automatically with `cancelled` (standard "user declined" semantics), so an extension that asks never hangs the run
 4. **Real-time TUI progress** shows tool calls, turns, and elapsed time as the subagent runs
 5. After completion, an **AI-generated one-line summary** is produced for compact display
 6. Returns the result to the main model with usage statistics (turns, tokens, cost)
@@ -54,18 +54,20 @@ This means:
 
 | Command | Description |
 |---------|-------------|
-| `/subagent:view` | Open the live view: a tabbed overlay showing one run's full activity feed at a time, with an input box to steer the focused run |
+| `/subagent:view` | Open the live view: a tabbed overlay with a per-run activity feed and a brief detail page (inputs, files, stats), plus modal steer input for the focused run |
 | `/subagent:doctor` | Diagnose pi invocation, model-role resolution, configuration, and role references |
 | `/subagent:status` | List background runs (active + collected) and their current state |
 | `/subagent:cancel <id\|all> [reason]` | Cancel a live background run (or every live run); the optional reason is recorded with the run |
 
 ### Live view (`/subagent:view`)
 
-A centered overlay covering most of the screen. A tab row across the top lists every run (icon · id · role); `Tab` cycles the focused run, and the rest of the viewport belongs to it alone — its complete activity feed, tail-capped to the visible area with a `⋮ earlier activity` marker when older entries roll off.
+A centered overlay covering most of the screen. A tab row across the top lists every run (icon · id · role); `Tab` cycles the focused run, and the rest of the viewport belongs to it alone — showing one of two pages, toggled with `d`.
 
-The feed itself is a continuous, append-only list: each entry is static text with a state icon, and the only animated thing is the ellipsis on a running entry (`.` → `..` → `...`). Finishing freezes an entry in place — its position never changes, only the icon flips. Streamed assistant text grows in place as the run's last line and settles into plain terminal-colored text at the turn boundary. Both foreground and background runs appear here; a foreground run stays listed while its delegate call blocks the main agent.
+The **activity page** (default) is the run's live feed: a continuous, append-only list where each entry is static text with a state icon, and the only animated thing is the ellipsis on a running entry (`.` → `..` → `...`). Finishing freezes an entry in place — its position never changes, only the icon flips. Streamed assistant text grows in place as the run's last line and settles into plain terminal-colored text at the turn boundary. The feed is scrollable (`↑↓`, `PgUp/PgDn`, `Home`/`End`): the view pins to the end and auto-follows new entries; scrolling up unpins (a `⋮ N earlier` marker appears), and reaching the bottom again re-pins. Both foreground and background runs appear here; a foreground run stays listed while its delegate call blocks the main agent.
 
-Below the feed sits a steer input box: type a correction and press Enter to queue it into the focused run (only while it is running). The message appears immediately in the feed as an `↩ steer:` entry and is delivered to the child after its current tool batch, before its next LLM call — the run keeps its progress. `Esc` closes the overlay.
+The **brief page** shows the run's inputs and vitals at full width: the task and context verbatim (wrapped; head+tail elided beyond 20k chars), the reference file list annotated with `✓`/`·` for whether the child's tool calls actually touched each file, usage and time stats, the fallback trace, and a stderr tail on failures.
+
+Steer input is modal so keys never conflict with typing: in browse mode `s` opens the editor, `Enter` queues the message into the focused run (only while it is running) and returns to browse, `Esc` cancels and clears. The message appears immediately in the feed as an `↩ steer:` entry and is delivered to the child after its current tool batch, before its next LLM call — the run keeps its progress. `Esc` in browse mode closes the overlay.
 
 ## Dependencies
 
@@ -150,11 +152,18 @@ Override, disable, or add subagent roles via `agentOverrides`. Built-in and cust
 }
 ```
 
-**Required fields for custom roles:** `role`, `description`, `examples`, `decisionTrigger`, `systemPrompt`. `tools` is optional — absent means all tools, a list restricts to those exact tool names.
+**Required fields for custom roles:** `role`, `description`, `examples`, `decisionTrigger`, `systemPrompt`.
+
+**Tool policy (optional, pick exactly one):**
+
+- `tools` — exact-name allowlist: absent means all tools, a list restricts to exactly those tool names, an **empty array means zero tools**.
+- `excludeTools` — denylist: everything except the listed tool names (handy for e.g. withholding interactive tools from an otherwise full-access role). Absent or empty means no restriction.
+
+Configuring both on the same role is an error — the role is skipped with an error notification at session start.
 
 **Optional fields:** `subagentRoles` (roles this role can spawn via delegate), `timeout` (per-role active-time timeout in seconds; unset or `0` is unlimited, negative values normalize to `0`), `maxTurns` / `maxCost` (per-role budget overrides; unset uses the top-level `maxTurns` / `maxCost` setting, `0` is unlimited, negative values normalize to `0`), `fallbackRole` (backup pi-model-roles role the whole run is retried on after a provider error; unset means no retry — see [Fallback observability](#fallback-observability)).
 
-Invalid custom roles (missing required fields) are silently skipped with an error notification at session start.
+Invalid custom roles (missing required fields) are skipped with an error notification at session start.
 
 ## Usage (by the main model)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "1.7.1",
+  "version": "2.0.0",
   "type": "module",
   "description": "Role-based subagent orchestration for pi — delegates tasks to specialized pi child processes with configurable model roles",
   "main": "src/index.ts",

package/src/index.ts

@@ -203,6 +203,22 @@ export default function subagentExtension(pi: ExtensionAPI) {
     refreshAvailableRoles();
     applyAgentOverrides(availableRoles, config.agentOverrides);
 
+    // Tool policy is one-dimensional: `tools` is a closed allowlist,
+    // `excludeTools` an open denylist — carrying both is a contradiction
+    // (intent bug, e.g. "append to the allowlist" written as both fields),
+    // never a combination to resolve. Skip the role loudly; the surviving
+    // role set self-documents via guidelines, and delegate fast-fails on the
+    // missing name.
+    for (const [name, role] of Object.entries(availableRoles)) {
+      if (role.tools !== undefined && role.excludeTools !== undefined) {
+        delete availableRoles[name];
+        ctx.ui.notify(
+          `[pi-subagent] Role "${name}" skipped — "tools" and "excludeTools" are mutually exclusive; configure exactly one.`,
+          "error",
+        );
+      }
+    }
+
     // Validate custom roles (skip built-in roles — they already have all fields)
     // `tools` is optional — absent means the role gets all tools.
     const REQUIRED_FIELDS = [

package/src/run.ts

@@ -290,6 +290,7 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
         cwd: opts.cwd,
         thinking,
         tools: opts.roleDef.tools,
+        excludeTools: opts.roleDef.excludeTools,
         systemPrompt: opts.roleDef.systemPrompt,
         context: opts.context,
         contextFiles: opts.files,
@@ -325,6 +326,7 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
             cwd: opts.cwd,
             thinking: fallback.config.thinking,
             tools: opts.roleDef.tools,
+            excludeTools: opts.roleDef.excludeTools,
             systemPrompt: opts.roleDef.systemPrompt,
             context: opts.context,
             contextFiles: opts.files,

package/src/spawn.test.ts

@@ -9,7 +9,7 @@ import assert from "node:assert/strict";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { composeInitialMessage } from "./spawn.ts";
+import { buildChildArgs, composeInitialMessage } from "./spawn.ts";
 
 describe("composeInitialMessage", () => {
   test("wraps reference files in <file> blocks ahead of context and task", async () => {
@@ -47,3 +47,60 @@ describe("composeInitialMessage", () => {
     assert.equal(message, "<task>\nt\n</task>");
   });
 });
+
+describe("buildChildArgs", () => {
+  test("base invocation: rpc mode, no session, model, then env+policy prompt blocks", () => {
+    const tmpDir = "/tmp/pi-subagent-x";
+    const args = buildChildArgs("prov/model", {}, tmpDir);
+    assert.deepEqual(args.slice(0, 6), [
+      "--mode",
+      "rpc",
+      "--no-session",
+      "--model",
+      "prov/model",
+      "--append-system-prompt",
+    ]);
+    const joined = args.join(" ");
+    assert.ok(joined.includes(`<subagent_env>\nPI_SUBAGENT_TMPDIR=${tmpDir}`));
+    assert.ok(joined.includes("<subagent_policy>"));
+    assert.ok(!joined.includes("--tools"));
+    assert.ok(!joined.includes("--exclude-tools"));
+  });
+
+  test("tools list → exact allowlist flag", () => {
+    const args = buildChildArgs("m", { tools: ["read", "grep"] }, "/t");
+    assert.ok(args.includes("--tools"));
+    assert.equal(args[args.indexOf("--tools") + 1], "read,grep");
+  });
+
+  test("tools: [] → --no-tools (literally zero tools)", () => {
+    const args = buildChildArgs("m", { tools: [] }, "/t");
+    assert.ok(args.includes("--no-tools"));
+    assert.ok(!args.includes("--tools"));
+  });
+
+  test("excludeTools → denylist flag; empty ≡ absent (no flag)", () => {
+    const args = buildChildArgs("m", { excludeTools: ["ask_user"] }, "/t");
+    assert.equal(args[args.indexOf("--exclude-tools") + 1], "ask_user");
+    const empty = buildChildArgs("m", { excludeTools: [] }, "/t");
+    assert.ok(!empty.includes("--exclude-tools"));
+  });
+
+  test("tools wins over excludeTools (both set is rejected upstream; belt only)", () => {
+    const args = buildChildArgs("m", { tools: ["read"], excludeTools: ["bash"] }, "/t");
+    assert.equal(args[args.indexOf("--tools") + 1], "read");
+    assert.ok(!args.includes("--exclude-tools"));
+  });
+
+  test("thinking and role system prompt are wrapped in their blocks", () => {
+    const args = buildChildArgs(
+      "m",
+      { thinking: "high", systemPrompt: "  Be brief.  " },
+      "/t",
+    );
+    assert.equal(args[args.indexOf("--thinking") + 1], "high");
+    const roleIdx = args.findIndex((a) => a.startsWith("<subagent_role>"));
+    assert.ok(roleIdx > 0);
+    assert.equal(args[roleIdx], "<subagent_role>\nBe brief.\n</subagent_role>");
+  });
+});

package/src/spawn.ts

@@ -131,6 +131,88 @@ export function getPiInvocation(args: string[]): { command: string; args: string
   return { command: "pi", args };
 }
 
+/**
+ * Build the pi CLI args for one child run (RPC mode).
+ *
+ * Tool policy mirrors pi's CLI flags in three mutually exclusive states
+ * (tools + excludeTools together is rejected at role resolution):
+ *   - `tools` set      → exact allowlist (`--tools`; empty = `--no-tools`, literally zero tools)
+ *   - `excludeTools` set → denylist (`--exclude-tools`; empty ≡ absent — nothing excluded)
+ *   - neither          → all tools (no flag)
+ *
+ * @internal — exported for testing.
+ */
+export function buildChildArgs(
+  modelRef: string,
+  options: {
+    thinking?: string;
+    tools?: string[];
+    excludeTools?: string[];
+    systemPrompt?: string;
+  },
+  tmpDir: string,
+): string[] {
+  const args: string[] = ["--mode", "rpc", "--no-session", "--model", modelRef];
+
+  if (options.thinking) {
+    args.push("--thinking", options.thinking);
+  }
+
+  if (options.tools) {
+    if (options.tools.length > 0) {
+      args.push("--tools", options.tools.join(","));
+    } else {
+      args.push("--no-tools");
+    }
+  } else if (options.excludeTools && options.excludeTools.length > 0) {
+    args.push("--exclude-tools", options.excludeTools.join(","));
+  }
+
+  // System prompt channel: inline text via --append-system-prompt. pi's
+  // resolvePromptInput treats an existing path as a file to read and any
+  // non-path string as literal text, so structured blocks go directly — no
+  // temp file, zero disk I/O.
+  if (options.systemPrompt?.trim()) {
+    args.push(
+      "--append-system-prompt",
+      `<subagent_role>\n${options.systemPrompt.trim()}\n</subagent_role>`,
+    );
+  }
+  args.push(
+    "--append-system-prompt",
+    `<subagent_env>\nPI_SUBAGENT_TMPDIR=${tmpDir}\nAvailable as $PI_SUBAGENT_TMPDIR in bash. Use for git clone and scratch files.\n</subagent_env>`,
+  );
+  // Shared behavioral policy for EVERY subagent run — built-in roles and
+  // agentOverrides customs alike. Role prompts (roles.ts) shape WHAT a role
+  // does; this shapes HOW any subagent behaves when the task exceeds its
+  // actual capabilities: report the gap and stop instead of improvising
+  // workarounds until timeout.
+  args.push(
+    "--append-system-prompt",
+    [
+      "<subagent_policy>",
+      "Before attempting the task, check it against your actual capabilities in this",
+      "session — the tool list here is definitive.",
+      "- If the task needs a capability you do not have (web access, bash, file",
+      "  writes, ...) or material that is not present locally or in the provided",
+      "  context/files, it is out of scope for you. Do NOT improvise workarounds.",
+      '- "Cannot complete" means a capability or material gap — not "difficult" or',
+      '  "uncertain". If it is merely hard, keep working within your tools.',
+      "- When you hit a genuine gap, stop early and return:",
+      "  ## Cannot complete",
+      "  - Missing: the capability or material that is absent",
+      "  - Needed: what would complete the task",
+      "  - Found: partial findings so far (optional)",
+      "",
+      'An early "cannot complete" report is a successful outcome; grinding on',
+      "impossible workarounds until timeout is the failure.",
+      "</subagent_policy>",
+    ].join("\n"),
+  );
+
+  return args;
+}
+
 /**
  * Compose the initial RPC prompt message: reference files as <file> blocks,
  * then context and task as structured tags — the same shape the child saw in
@@ -177,6 +259,8 @@ export async function spawnSubagent(
     cwd?: string;
     /** Thinking level passed to the child pi process when the role defines one. */
     thinking?: string;
+    /** Extra tools withheld from the child (denylist); ignored when `tools` is set. */
+    excludeTools?: string[];
     tools?: string[];
     systemPrompt?: string;
     /** Extra context delivered as a separate channel from the task. */
@@ -232,64 +316,12 @@ export async function spawnSubagent(
   let tmpDir: string | null = null;
 
   try {
-    // Build CLI args. RPC mode (not json): stdin carries the initial prompt and
-    // mid-run steering commands; stdout streams the same agent events.
-    const args: string[] = ["--mode", "rpc", "--no-session", "--model", modelRef];
-
-    if (options.thinking) {
-      args.push("--thinking", options.thinking);
-    }
-
-    if (options.tools && options.tools.length > 0) {
-      args.push("--tools", options.tools.join(","));
-    }
-
     // Scratch dir handed to the child as PI_SUBAGENT_TMPDIR for its bash work
     // (e.g. git clone). The initial prompt goes over stdin, so there is no
     // argv length limit and no spill-to-tempfile channel anymore.
     tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-subagent-"));
 
-    // ── System prompt channel: inline text via --append-system-prompt ──
-    // pi's resolvePromptInput treats an existing path as a file to read and any
-    // non-path string as literal text, so we pass structured blocks directly —
-    // no temp file, zero disk I/O. Multiple flags are joined with "\n\n".
-    if (options.systemPrompt?.trim()) {
-      args.push(
-        "--append-system-prompt",
-        `<subagent_role>\n${options.systemPrompt.trim()}\n</subagent_role>`,
-      );
-    }
-    args.push(
-      "--append-system-prompt",
-      `<subagent_env>\nPI_SUBAGENT_TMPDIR=${tmpDir}\nAvailable as $PI_SUBAGENT_TMPDIR in bash. Use for git clone and scratch files.\n</subagent_env>`,
-    );
-    // Shared behavioral policy for EVERY subagent run — built-in roles and
-    // agentOverrides customs alike. Role prompts (roles.ts) shape WHAT a role
-    // does; this shapes HOW any subagent behaves when the task exceeds its
-    // actual capabilities: report the gap and stop instead of improvising
-    // workarounds until timeout.
-    args.push(
-      "--append-system-prompt",
-      [
-        "<subagent_policy>",
-        "Before attempting the task, check it against your actual capabilities in this",
-        "session — the tool list here is definitive.",
-        "- If the task needs a capability you do not have (web access, bash, file",
-        "  writes, ...) or material that is not present locally or in the provided",
-        "  context/files, it is out of scope for you. Do NOT improvise workarounds.",
-        '- "Cannot complete" means a capability or material gap — not "difficult" or',
-        '  "uncertain". If it is merely hard, keep working within your tools.',
-        "- When you hit a genuine gap, stop early and return:",
-        "  ## Cannot complete",
-        "  - Missing: the capability or material that is absent",
-        "  - Needed: what would complete the task",
-        "  - Found: partial findings so far (optional)",
-        "",
-        'An early "cannot complete" report is a successful outcome; grinding on',
-        "impossible workarounds until timeout is the failure.",
-        "</subagent_policy>",
-      ].join("\n"),
-    );
+    const args = buildChildArgs(modelRef, options, tmpDir);
 
     // ── Initial prompt channel: one RPC prompt command over stdin ──
     // RPC mode rejects @file argv, so reference files are inlined here as
@@ -367,6 +399,20 @@ export async function spawnSubagent(
       // RPC command acknowledgements ("response" lines) carry no agent state.
       if (event.type === "response") return;
 
+      // The child is a headless worker — nobody can answer its dialogs.
+      // RPC-mode ctx.ui.select/confirm/input emit extension_ui_request and
+      // park the child's extension on a promise that has NO default timeout;
+      // without a response the child hangs until the run timeout kills it.
+      // Answer immediately with cancelled:true — the standard "user declined"
+      // semantics (undefined/false) extensions already handle. Fire-and-forget
+      // methods (notify/setStatus/setWidget/setTitle) need no answer.
+      if (event.type === "extension_ui_request" && event.id) {
+        if (event.method === "select" || event.method === "confirm" || event.method === "input") {
+          sendCommand({ type: "extension_ui_response", id: event.id, cancelled: true });
+        }
+        return;
+      }
+
       // RPC mode is a resident server. agent_end only marks one low-level run
       // and may be followed by an automatic retry, compaction, or queued
       // continuation. agent_settled is the authoritative terminal event. We run

package/src/types.ts

@@ -55,10 +55,17 @@ export interface SubagentRole {
   /** System prompt for the subagent */
   systemPrompt: string;
   /**
-   * Tools available to this subagent. Empty or absent = all tools (no restriction).
-   * When set, only the listed tool names are exposed to the child (exact-name allowlist).
+   * Tools available to this subagent — exact-name allowlist mapped to pi's `--tools`.
+   * Absent = all tools (no restriction); empty array = literally zero tools (`--no-tools`).
+   * Mutually exclusive with `excludeTools`.
    */
   tools?: string[];
+  /**
+   * Tools withheld from this subagent — everything else stays available (mapped
+   * to pi's `--exclude-tools`). Absent or empty = no restriction.
+   * Mutually exclusive with `tools`.
+   */
+  excludeTools?: string[];
   /** If this role has `delegate`, restrict which roles it may spawn. undefined = no restriction. */
   subagentRoles?: string[];
   /** Per-role active-time timeout in seconds. `0` or unset means unlimited; negative values are normalized to `0`. */

package/src/utils.test.ts

@@ -42,6 +42,7 @@ import {
   terminalResultLine,
   buildDisplayItems,
   formatToolCall,
+  briefFilesUsed,
 } from "./utils.ts";
 import type { ActivityEntry, SubagentResult, SubagentRole } from "./types.ts";
 
@@ -749,3 +750,51 @@ describe("streamed-text activity entries", () => {
     );
   });
 });
+
+describe("briefFilesUsed", () => {
+  const call = (toolName: string, args: Record<string, any>): ActivityEntry => ({
+    kind: "toolCall",
+    id: `tc-${toolName}`,
+    status: "done",
+    toolName,
+    args,
+  });
+  const F1 = "/Users/x/proj/src/a.ts";
+  const F2 = "/Users/x/proj/docs/guide.md";
+
+  test("marks a file matched by an exact-path arg", () => {
+    const used = briefFilesUsed([F1, F2], [call("read", { file_path: F1 })]);
+    assert.equal(used.get(F1), true);
+    assert.equal(used.get(F2), false);
+  });
+
+  test("marks a file referenced inside a bash command", () => {
+    const used = briefFilesUsed([F1], [call("bash", { command: `cat ${F1} | head -5` })]);
+    assert.equal(used.get(F1), true);
+  });
+
+  test("marks a file the child addressed by relative path", () => {
+    const used = briefFilesUsed([F1], [call("edit", { file_path: "src/a.ts" })]);
+    assert.equal(used.get(F1), true);
+  });
+
+  test("ignores short separator-less values — no false positives", () => {
+    const used = briefFilesUsed([F1], [call("grep", { pattern: "a.ts" })]);
+    assert.equal(used.get(F1), false);
+  });
+
+  test("collects strings from nested args one level deep", () => {
+    const used = briefFilesUsed([F1], [
+      call("edit", { edits: [{ oldText: "x", path: F1 }] }),
+    ]);
+    assert.equal(used.get(F1), true);
+  });
+
+  test("skips non-toolCall entries and empty file lists", () => {
+    assert.equal(briefFilesUsed(undefined, [call("read", { file_path: F1 })]).size, 0);
+    const used = briefFilesUsed([F1], [
+      { kind: "text", id: "text-0", status: "done", text: "hi" },
+    ]);
+    assert.equal(used.get(F1), false);
+  });
+});

package/src/utils.ts

@@ -269,6 +269,56 @@ export function renderDisplayItems(
   return text.trimEnd();
 }
 
+// ── Brief page (subagent:view detail view) ─────────────────────
+
+/** Collect string values from a tool call's args, up to a small nesting depth. */
+function argStrings(args: Record<string, any> | undefined): string[] {
+  const out: string[] = [];
+  const walk = (v: unknown, depth: number): void => {
+    if (typeof v === "string") {
+      out.push(v);
+    } else if (depth > 0 && Array.isArray(v)) {
+      for (const item of v) walk(item, depth - 1);
+    } else if (depth > 0 && v && typeof v === "object") {
+      for (const item of Object.values(v)) walk(item, depth - 1);
+    }
+  };
+  walk(args, 3);
+  return out;
+}
+
+/** Arg values shorter than this (and without a separator) are ignored as path candidates. */
+const PATH_MATCH_MIN = 5;
+
+/**
+ * Cross-annotation for the brief page's file list: for each delegate
+ * reference file, did any tool call in the activity log touch it? Heuristic
+ * string match — a hit is either an arg containing the full path (absolute
+ * use, bash references) or the file path ending with the arg (the child
+ * using a relative form). Short separator-less values never match, so plain
+ * query strings cannot false-positive.
+ */
+export function briefFilesUsed(
+  files: string[] | undefined,
+  activityLog: ActivityEntry[],
+): Map<string, boolean> {
+  const used = new Map<string, boolean>((files ?? []).map((f) => [f, false]));
+  if (used.size === 0) return used;
+  for (const entry of activityLog) {
+    if (entry.kind !== "toolCall") continue;
+    for (const v of argStrings(entry.args)) {
+      if (v.length < PATH_MATCH_MIN) continue;
+      for (const [file, hit] of used) {
+        if (hit) continue;
+        if (v.includes(file) || (v.includes("/") && file.endsWith(v))) {
+          used.set(file, true);
+        }
+      }
+    }
+  }
+  return used;
+}
+
 // ── Shared result-view composition ─────────────────────────────
 // Used by the foreground delegate row (./render.ts) and the background
 // wait/check rows (./render-async.ts) so every view renders the same

package/src/view.ts

@@ -9,43 +9,71 @@
  * adjacent spinning lines. Streamed assistant text is the single growing
  * element: it renders as the run's last line and freezes at message_end.
  *
+ * The focused run has two full-width pages, toggled with `d`:
+ *  - activity (default): the live feed, scrollable with ↑/↓/PgUp/PgDn. The
+ *    view pins to the end and auto-follows new entries; scrolling up unpins
+ *    (a "⋮ N earlier" marker appears), reaching the bottom again (or End)
+ *    re-pins.
+ *  - brief: the run's inputs and vitals — task and context verbatim (wrapped;
+ *    head+tail elided when huge), the reference file list annotated with ✓/·
+ *    for whether the child's tool calls touched each file, usage and time
+ *    stats, the fallback trace, and a stderr tail on failures.
+ *
+ * Steer input is modal so keys never conflict with the editor: browse mode
+ * owns navigation; `s` opens the editor (Enter sends and returns to browse,
+ *    Esc cancels and clears). Esc in browse closes the overlay; Tab cycles
+ * the focused run and resets scrolls (activity re-pins, brief returns to
+ * the top).
+ *
  * Layout: a centered screen overlay (overlay:true) occupying most of the
  * terminal, framed with a thin border. An embedded Editor accepts steering
- * input for the focused run (Tab cycles targets); Enter queues the message
- * through the run's RPC stdin channel — delivered after the child's current
- * tool batch, before its next LLM call.
+ * input for the focused run; Enter queues the message through the run's RPC
+ * stdin channel — delivered after the child's current tool batch, before its
+ * next LLM call.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import {
+  decodeKittyPrintable,
   Editor,
   type Component,
   type EditorTheme,
   type Focusable,
   Key,
   matchesKey,
+  stripTerminalSequences,
   truncateToWidth,
   visibleWidth,
+  wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
 import type { RunHandle } from "./run.ts";
 import type { ActivityEntry } from "./types.ts";
 import {
+  briefFilesUsed,
+  formatFallback,
   formatThinking,
   formatTimePart,
   formatToolCall,
+  formatTokens,
   formatUsageStats,
   runIcon,
+  shortenPath,
   statusStyle,
   taskPreview,
 } from "./utils.ts";
 
-/** Max body lines kept visible; older entries roll off the top. */
+/** Max body lines kept visible; older lines scroll off behind a marker. */
 const VIEWPORT_LINES = 26;
 /** Animation tick for the running-entry ellipsis. */
 const ANIMATION_INTERVAL_MS = 150;
+/** Brief-page text (task/context) is elided to head+tail beyond this many
+ *  chars, so huge contexts stay cheap to re-wrap on every animation tick. */
+const BRIEF_TEXT_CAP = 20_000;
 
 type TuiLike = { requestRender(): void };
 type Fg = (color: string, text: string) => string;
+type Page = "activity" | "brief";
+type Mode = "browse" | "steer";
 
 /** Pad a string with trailing spaces to a visible width (left-justified). */
 function padRight(s: string, width: number): string {
@@ -58,6 +86,22 @@ function dots(): string {
   return ".".repeat(1 + (Math.floor(Date.now() / 300) % 3));
 }
 
+/** Normalize one keypress to its printable character (Kitty CSI-u aware). */
+function printableChar(data: string): string | undefined {
+  const kitty = decodeKittyPrintable(data);
+  if (kitty !== undefined) return kitty;
+  return data.length === 1 && data >= " " && data <= "~" ? data : undefined;
+}
+
+/** Elide oversized brief text to head + tail around an elision marker. */
+function capBriefText(text: string): string {
+  if (text.length <= BRIEF_TEXT_CAP) return text;
+  const head = text.slice(0, Math.floor(BRIEF_TEXT_CAP * 0.8));
+  const tail = text.slice(-Math.floor(BRIEF_TEXT_CAP * 0.2));
+  const elided = text.length - head.length - tail.length;
+  return `${head}\n… [${formatTokens(elided)} chars elided] …\n${tail}`;
+}
+
 /**
  * Build the display list of runs for the panel: running/queued first, then
  * finished, each group ordered by registry id.
@@ -75,8 +119,19 @@ export class SubagentViewPanel implements Component, Focusable {
   private tui: TuiLike;
   private close: () => void;
   private editor: Editor;
-  /** Focused run (Tab cycles); the whole viewport belongs to it. */
-  private focusIndex = 0;
+  /** Focused run id (Tab cycles); the whole viewport belongs to it. */
+  private focusId: string | null = null;
+  /** browse = navigation keys; steer = the editor owns input. */
+  private mode: Mode = "browse";
+  /** Focused run's visible page. */
+  private page: Page = "activity";
+  /** Activity scroll: null = pinned to the end (auto-follow), else the
+   *  index of the first visible entry line. */
+  private activityTop: number | null = null;
+  /** Brief scroll: index of the first visible line (clamped in render). */
+  private briefTop = 0;
+  /** Brief scroll ceiling, recomputed each render (content is static). */
+  private briefMax = 0;
   /** Transient feedback line ("steer sent to sub-N"), auto-clears. */
   private flash = "";
   private flashUntil = 0;
@@ -116,11 +171,38 @@ export class SubagentViewPanel implements Component, Focusable {
     }, ANIMATION_INTERVAL_MS);
   }
 
+  /** Resolve the focused run by id; stable across sort-order reshuffles
+   *  (e.g. a run finishing re-ranks the list). Scroll state resets only when
+   *  the focused run actually changes. */
   private focusedRun(): RunHandle | undefined {
     const runs = sortViewRuns(this.runsProvider());
-    if (runs.length === 0) return undefined;
-    if (this.focusIndex >= runs.length) this.focusIndex = 0;
-    return runs[this.focusIndex];
+    if (runs.length === 0) {
+      this.focusId = null;
+      return undefined;
+    }
+    let run = runs.find((r) => r.id === this.focusId);
+    if (!run) {
+      run = runs[0];
+      this.focusId = run.id;
+      this.resetScrolls();
+    }
+    return run;
+  }
+
+  private resetScrolls(): void {
+    this.activityTop = null;
+    this.briefTop = 0;
+  }
+
+  private cycleRun(): void {
+    const runs = sortViewRuns(this.runsProvider());
+    if (runs.length < 2) return;
+    const idx = runs.findIndex((r) => r.id === this.focusId);
+    const next = runs[((idx >= 0 ? idx : 0) + 1) % runs.length];
+    if (next.id === this.focusId) return;
+    this.focusId = next.id;
+    this.resetScrolls();
+    this.tui.requestRender();
   }
 
   private submitSteer(value: string): void {
@@ -134,6 +216,7 @@ export class SubagentViewPanel implements Component, Focusable {
     target.steer(text);
     this.editor.setText("");
     this.showFlash(`steer queued for ${target.id} (${target.role})`);
+    this.mode = "browse";
   }
 
   private showFlash(message: string): void {
@@ -142,19 +225,66 @@ export class SubagentViewPanel implements Component, Focusable {
   }
 
   handleInput(data: string): void {
+    if (this.mode === "steer") {
+      // Everything types into the editor; Esc cancels (never closes the panel).
+      if (matchesKey(data, Key.escape)) {
+        this.editor.setText("");
+        this.mode = "browse";
+        this.tui.requestRender();
+        return;
+      }
+      this.editor.handleInput(data);
+      this.tui.requestRender();
+      return;
+    }
+
     if (matchesKey(data, Key.escape)) {
       this.closePanel();
       return;
     }
     if (matchesKey(data, Key.tab)) {
-      const n = sortViewRuns(this.runsProvider()).length;
-      if (n > 1) {
-        this.focusIndex = (this.focusIndex + 1) % n;
-        this.tui.requestRender();
-      }
+      this.cycleRun();
+      return;
+    }
+    const ch = printableChar(data);
+    if (ch === "d") {
+      this.page = this.page === "activity" ? "brief" : "activity";
+      this.tui.requestRender();
       return;
     }
-    this.editor.handleInput(data);
+    if (ch === "s") {
+      this.mode = "steer";
+      this.tui.requestRender();
+      return;
+    }
+    const page = Math.max(3, this.browseBudget() - 1);
+    if (matchesKey(data, Key.up)) this.scrollBy(-1);
+    else if (matchesKey(data, Key.down)) this.scrollBy(1);
+    else if (matchesKey(data, Key.pageUp)) this.scrollBy(-page);
+    else if (matchesKey(data, Key.pageDown)) this.scrollBy(page);
+    else if (matchesKey(data, Key.home)) {
+      if (this.page === "activity") this.activityTop = 0;
+      else this.briefTop = 0;
+      this.tui.requestRender();
+    } else if (matchesKey(data, Key.end)) {
+      if (this.page === "activity") this.activityTop = null;
+      else this.briefTop = this.briefMax;
+      this.tui.requestRender();
+    }
+  }
+
+  /** Scroll the visible page by `delta` lines. Activity pins back to the end
+   *  once the bottom is reached (auto-follow resumes). */
+  private scrollBy(delta: number): void {
+    if (this.page === "activity") {
+      const n = this.focusedRun()?.snapshot.activityLog.length ?? 0;
+      const maxTop = Math.max(0, n - this.browseBudget());
+      const cur = this.activityTop ?? maxTop;
+      const next = Math.max(0, Math.min(maxTop, cur + delta));
+      this.activityTop = next >= maxTop ? null : next;
+    } else {
+      this.briefTop = Math.max(0, Math.min(this.briefMax, this.briefTop + delta));
+    }
     this.tui.requestRender();
   }
 
@@ -166,6 +296,11 @@ export class SubagentViewPanel implements Component, Focusable {
     this.close();
   }
 
+  /** Content line budget in browse mode (tab row + header + steer hint + key hint). */
+  private browseBudget(): number {
+    return Math.max(3, VIEWPORT_LINES - 4);
+  }
+
   /** Render one activity entry as a static line; running entries get the
    *  animated ellipsis suffix. */
   private renderEntry(e: ActivityEntry, width: number, fg: Fg): string {
@@ -197,6 +332,88 @@ export class SubagentViewPanel implements Component, Focusable {
     return truncateToWidth(indent + line, width);
   }
 
+  /** Render the brief page's full content (pre-scroll): task/context verbatim,
+   *  annotated file list, stats, fallback trace, failure stderr tail. */
+  private renderBriefLines(run: RunHandle, width: number, fg: Fg): string[] {
+    const snap = run.snapshot;
+    const lines: string[] = [];
+    const section = (title: string) => {
+      const label = `── ${title} `;
+      lines.push(fg("dim", label + "─".repeat(Math.max(0, width - visibleWidth(label)))));
+    };
+    const body = (text: string, color?: string) => {
+      for (const ln of wrapTextWithAnsi(capBriefText(text), width - 2)) {
+        lines.push(color ? `  ${fg(color, ln)}` : `  ${ln}`);
+      }
+    };
+
+    section("task");
+    body(run.task);
+
+    if (run.context) {
+      section(`context · ${formatTokens(run.context.length)} chars`);
+      body(run.context);
+    }
+
+    if (run.files && run.files.length > 0) {
+      section(`files · ${run.files.length}`);
+      const used = briefFilesUsed(run.files, snap.activityLog);
+      for (const f of run.files) {
+        lines.push(
+          used.get(f)
+            ? fg("success", `  ✓ ${shortenPath(f)}`)
+            : fg("muted", `  · ${shortenPath(f)}`),
+        );
+      }
+    }
+
+    section("stats");
+    const usage = formatUsageStats(snap.usage, snap.model);
+    lines.push(fg("dim", `  ${usage || "no usage yet"}`));
+    const time = formatTimePart({ ...snap, exitCode: run.state === "queued" ? -1 : snap.exitCode });
+    if (time) lines.push(fg("dim", `  ${time}`));
+    if (run.state === "finished" || run.state === "failed") {
+      lines.push(fg("dim", `  exit ${snap.exitCode}${snap.stopReason ? ` · ${snap.stopReason}` : ""}`));
+    }
+    if (snap.fallbackFrom) {
+      lines.push(fg("warning", `  ⚠ ${formatFallback(snap.fallbackFrom)}`));
+    }
+    if (run.state === "failed") {
+      if (snap.errorMessage) body(snap.errorMessage, "error");
+      const tail = stripTerminalSequences(snap.stderr)
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .slice(-6);
+      if (tail.length > 0) {
+        lines.push(fg("dim", "  stderr (tail):"));
+        for (const l of tail) lines.push(truncateToWidth(fg("muted", `  ${l}`), width));
+      }
+    }
+    return lines;
+  }
+
+  /** Push the focused run's current page (activity or brief) as framed rows. */
+  private renderPage(run: RunHandle, budget: number, innerW: number, fg: Fg, row: (s: string) => string): string[] {
+    const lines: string[] = [];
+    if (this.page === "activity") {
+      const entries = run.snapshot.activityLog.map((e) => this.renderEntry(e, innerW, fg));
+      const maxTop = Math.max(0, entries.length - budget);
+      const top = this.activityTop === null ? maxTop : Math.min(this.activityTop, maxTop);
+      if (top > 0) lines.push(row(fg("muted", `⋮ ${top} earlier`)));
+      for (const ln of entries.slice(top, top + budget - (top > 0 ? 1 : 0))) lines.push(row(ln));
+      return lines;
+    }
+    const all = this.renderBriefLines(run, innerW, fg);
+    this.briefMax = Math.max(0, all.length - budget);
+    this.briefTop = Math.min(this.briefTop, this.briefMax);
+    if (this.briefTop > 0) lines.push(row(fg("muted", `⋮ ${this.briefTop} earlier`)));
+    for (const ln of all.slice(this.briefTop, this.briefTop + budget - (this.briefTop > 0 ? 1 : 0))) {
+      lines.push(row(ln));
+    }
+    return lines;
+  }
+
   render(width: number): string[] {
     const th = this.theme;
     // Same adaptation render.ts uses: utils formatters take a loose Fg.
@@ -210,16 +427,16 @@ export class SubagentViewPanel implements Component, Focusable {
 
     const runs = sortViewRuns(this.runsProvider());
     const lines: string[] = [];
-
     const runningCount = runs.filter((r) => r.state === "running").length;
+    const focused = this.focusedRun();
 
     // ── Tab row: one cell per run; the focused one is highlighted. ──
     if (runs.length > 0) {
-      const cells = runs.map((r, i) => {
-        const focused = r === this.focusedRun();
+      const cells = runs.map((r) => {
+        const isFocused = r === focused;
         const label = `${runIcon(r.snapshot, fg)} ${r.id} ${r.role}`;
-        const styled = focused ? th.bg("selectedBg", fg("accent", label)) : fg("dim", label);
-        return focused ? styled : `[${styled}]`;
+        const styled = isFocused ? th.bg("selectedBg", fg("accent", label)) : fg("dim", label);
+        return isFocused ? styled : `[${styled}]`;
       });
       lines.push(
         row(
@@ -231,44 +448,52 @@ export class SubagentViewPanel implements Component, Focusable {
       lines.push(row(fg("muted", "subagents: no runs.")));
     }
 
-    // ── Focused run: full viewport, tail-capped entries. ──
-    // Reserve room for tab row (1) + steer bar (2) + hint (1).
-    const budget = Math.max(3, VIEWPORT_LINES - 4);
-    const run = this.focusedRun();
-    if (run) {
-      const snap = run.snapshot;
+    // ── Focused run: header line, then the current page. ──
+    if (focused) {
+      const snap = focused.snapshot;
       const icon = runIcon(snap, fg);
-      const time = formatTimePart({ ...snap, exitCode: run.state === "queued" ? -1 : snap.exitCode });
+      const time = formatTimePart({ ...snap, exitCode: focused.state === "queued" ? -1 : snap.exitCode });
+      const inputBits: string[] = [];
+      if (focused.files?.length) {
+        inputBits.push(`${focused.files.length} file${focused.files.length === 1 ? "" : "s"}`);
+      }
+      if (focused.context) inputBits.push(`context ${formatTokens(focused.context.length)}`);
       const parts = [
-        `${icon} ${fg("accent", th.bold(run.id))}`,
-        fg("text", run.role),
-        fg("dim", taskPreview(run.task)),
+        `${icon} ${fg("accent", th.bold(focused.id))}`,
+        fg("text", focused.role),
+        fg("dim", taskPreview(focused.task)),
+        ...(inputBits.length > 0 ? [fg("dim", inputBits.join(" · "))] : []),
         time ? fg("dim", time) : "",
         fg("dim", formatUsageStats(snap.usage, snap.model)),
       ].filter(Boolean);
       lines.push(row(parts.join(th.fg("dim", " · "))));
-      const entries = snap.activityLog.map((entry) => this.renderEntry(entry, innerW, fg));
-      if (entries.length > budget) {
-        entries.splice(0, entries.length - budget);
-        lines.push(row(fg("muted", "⋮ earlier activity")));
-      }
-      for (const ln of entries.slice(0, budget)) lines.push(row(ln));
-    }
 
-    // ── Steer bar ──
-    if (Date.now() < this.flashUntil) {
-      lines.push(row(fg("success", this.flash)));
-    } else {
-      const target = run && run.state === "running" ? `${run.id} (${run.role})` : null;
-      const label = target
-        ? fg("accent", target)
-        : fg("dim", run ? `${run.id} not running` : "no runs");
-      lines.push(row(fg("dim", `steer → ${label}`)));
-    }
-    for (const el of this.editor.render(innerW)) {
-      lines.push(row(el));
+      if (this.mode === "steer") {
+        const edLines = this.editor.render(innerW);
+        const budget = Math.max(3, VIEWPORT_LINES - 3 - edLines.length);
+        lines.push(...this.renderPage(focused, budget, innerW, fg, row));
+        const label =
+          focused.state === "running"
+            ? fg("accent", `${focused.id} (${focused.role})`)
+            : fg("dim", focused.state === "queued" ? `${focused.id} still queued` : `${focused.id} not running`);
+        lines.push(row(fg("dim", `steer → ${label}`)));
+        for (const el of edLines) lines.push(row(el));
+        lines.push(row(fg("dim", "Enter send · Esc cancel")));
+      } else {
+        lines.push(...this.renderPage(focused, this.browseBudget(), innerW, fg, row));
+        if (Date.now() < this.flashUntil) {
+          lines.push(row(fg("success", this.flash)));
+        } else {
+          const label =
+            focused.state === "running"
+              ? fg("accent", `${focused.id} (${focused.role})`)
+              : fg("dim", focused.state === "queued" ? `${focused.id} still queued` : `${focused.id} not running`);
+          lines.push(row(fg("dim", `steer → ${label} · press s`)));
+        }
+        const pageKey = this.page === "activity" ? "d brief" : "d activity";
+        lines.push(row(fg("dim", `↑↓ scroll · ${pageKey} · Tab run · s steer · Esc close`)));
+      }
     }
-    lines.push(row(fg("dim", "Enter steer · Tab switch run · Esc close")));
 
     // Frame.
     return [