@d3ara1n/pi-subagent 1.3.1 → 1.5.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`).
+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`.
 
 ## 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 with the configured model, tools, and system prompt
+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
 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,10 +54,19 @@ 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: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.
+
+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.
+
+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.
+
 ## Dependencies
 
 - [`@d3ara1n/pi-model-roles`](../pi-model-roles) — model role resolution
@@ -182,13 +191,14 @@ Three execution properties, kept separate:
 
 - **Foreground** (default): the call blocks until the run finishes and returns the final output directly. (Under the hood foreground and background share one async run engine — foreground is simply background-but-blocking.)
 - **Parallel**: multiple `subagent_delegate` calls in one turn run concurrently — foreground and background alike, no special flag.
-- **Background** (`background: true`): non-blocking — `subagent_delegate` returns immediately with a run id. Use it when you have your own work to do (or a discussion with the user to continue) while the run executes; three companion tools manage the outcome:
+- **Background** (`background: true`): non-blocking — `subagent_delegate` returns immediately with a run id. Use it when you have your own work to do (or a discussion with the user to continue) while the run executes; four companion tools manage the outcome:
 
 | Tool | Purpose | Returns to the model |
 |------|---------|---------------------|
 | `subagent_delegate(background: true)` | Start an async run | Just the id (`sub-N`) |
 | `subagent_wait(ids?, timeout_ms?)` | Block until **all** listed runs finish (omit `ids` for all current background runs) | Statuses only, one `id (role): finished/failed` line per run — never results; errors when the timeout hits with runs unfinished |
 | `subagent_check(id)` | One-shot snapshot of a single run | `queued` / `running` + current activity / the **full output** once finished / failure reason + partial output. Checking a terminal run **collects** it: the output is returned once and the run leaves the registry |
+| `subagent_steer(id, message)` | Queue a mid-run correction into one running run (typically right after a check revealed it heading down a wrong path) | Confirmation that the steer is queued — delivered after the child's current tool batch, before its next LLM call; the run keeps its progress |
 | `subagent_cancel(id, reason?)` | Kill one live (queued/running) run | Confirmation with the partial-output size — the run settles as `cancelled` (warning styling, same family as timeout/budget) with the reason in its error message; the partial output stays in the registry for `subagent_check` to collect |
 
 Typical flow:
@@ -220,6 +230,17 @@ Semantics worth knowing:
 - **Top-level only:** nested subagents cannot delegate in the background (a subagent process exits when its task finishes, which would orphan the run).
 - The run registry lives in the pi process: a `/reload` or restart orphans in-flight background runs (their ids stop resolving). `/subagent:status` lists every registered run (active + collected) and its current state.
 
+### Steering a running subagent
+
+Steering queues a correction into a running subagent without killing it — the middle ground between waiting it out and cancelling. The message is delivered after the child finishes its current tool batch, before its next LLM call, so the run keeps its progress and can change course. It is a suggestion injected between turns, not an interrupt: the child may comply immediately, finish what it was doing first, or ignore poor instructions entirely — to actually stop a run, cancel it.
+
+There are two channels into the same mechanism:
+
+- **The model** calls `subagent_steer(id, message)` — typically right after a `subagent_check` snapshot revealed the run heading down a wrong path (check → steer → check again later).
+- **The user** types into the input box of `/subagent:view`, targeting the focused run. Every accepted steer also appears in the run's activity feed as an `↩ steer:` entry, so whoever watches the view sees what was injected and when.
+
+Queued steers are visible in neither wait nor check results — they shape the run's subsequent behavior, not its transcript.
+
 ### Background TUI display
 
 Each tool row renders one aspect of the same decomposition the foreground row shows all at once (input · process · result · usage):
@@ -245,7 +266,7 @@ Hand the subagent precise context — selected code, a prior delegate's result,
 }
 ```
 
-The stored/displayed task stays as the original `task`. When small, `context` inlines as a `<context>` block; when large (over 8,000 chars) it spills to a temp file injected via `@file`, so a large context never drags a short task into a spill.
+The stored/displayed task stays as the original `task`. `context` is delivered as a `<context>` block ahead of the task in the child's initial prompt — the prompt travels over stdin, so size is not argv-bound and no spill file is involved.
 
 #### `files` (reference paths)
 
@@ -257,7 +278,7 @@ The stored/displayed task stays as the original `task`. When small, `context` in
 }
 ```
 
-Each path is injected as an independent `@file` attachment the subagent reads directly. **File contents stay out of your context window** — you pass only the paths. Prefer this over pasting file contents into `context`, since the child receives the content on its first turn without spending a tool call to read it.
+Each path is injected as an independent `<file name="...">` block in the child's initial prompt — the same wrap pi applies to `@file` arguments. **File contents stay out of your context window** — you pass only the paths; this process reads the bytes off disk and pipes them straight to the child. Prefer this over pasting file contents into `context`, since the child receives the content on its first turn without spending a tool call to read it.
 
 ### Budget enforcement
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "1.3.1",
+  "version": "1.5.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

@@ -45,6 +45,7 @@ import {
 import { startSubagentRun, type RunHandle } from "./run.ts";
 import { buildInboxReminder, injectReminder } from "./reminder.ts";
 import { renderDelegateCall, renderDelegateResult } from "./render.ts";
+import { createViewPanel } from "./view.ts";
 import {
   renderBackgroundDelegateCall,
   renderBackgroundDelegateResult,
@@ -634,6 +635,57 @@ export default function subagentExtension(pi: ExtensionAPI) {
     renderResult: renderCheckResult,
   });
 
+  pi.registerTool({
+    name: "subagent_steer",
+    label: "Steer a running background subagent",
+    description:
+      "Queue a mid-run correction into ONE running background subagent — typically right after subagent_check showed it heading down a wrong path. The message is delivered after the child finishes its current tool batch, before its next LLM call; the run keeps its progress (unlike cancel). Only running runs accept steering; queued runs reject it, and terminal runs are collected by check instead. Typical flow: check → steer → check again later.",
+    promptSnippet: "Send a mid-run correction to a background subagent",
+    parameters: Type.Object({
+      id: Type.String({ description: "Run id returned by a background delegate call" }),
+      message: Type.String({
+        description:
+          "The correction. Concise and imperative — it lands mid-run, between the child's turns.",
+      }),
+    }),
+
+    async execute(_toolCallId, params) {
+      const run = backgroundRuns.get(params.id);
+      if (!run) {
+        const collected = collectedRuns.get(params.id);
+        if (collected) {
+          throw new Error(
+            `${params.id} (${collected.role}) was already collected — nothing left to steer. Delegate a new run if a correction is still needed.`,
+          );
+        }
+        const active = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
+        throw new Error(
+          `Unknown subagent id: ${params.id}. Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
+        );
+      }
+      if (run.state === "queued") {
+        throw new Error(
+          `${params.id} (${run.role}) is still queued for a concurrency slot — steer once it is running.`,
+        );
+      }
+      if (run.state !== "running") {
+        throw new Error(
+          `${params.id} (${run.role}) is ${run.state} — only running runs can be steered. subagent_check(${params.id}) returns its result.`,
+        );
+      }
+      run.steer(params.message);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Steer queued for ${params.id} (${run.role}) — delivered after its current tool batch. Verify the effect with subagent_check later.`,
+          },
+        ],
+        details: { id: params.id, role: run.role },
+      };
+    },
+  });
+
   pi.registerTool({
     name: "subagent_cancel",
     label: "Cancel a background subagent",
@@ -696,6 +748,38 @@ export default function subagentExtension(pi: ExtensionAPI) {
     renderResult: renderCancelResult,
   });
 
+  pi.registerCommand("subagent:view", {
+    description: "Open the live subagent activity view (watch progress, steer runs)",
+    handler: async (_args, ctx) => {
+      // Union of every known run: background registry (until collected) plus
+      // live in-flight runs (foreground delegate calls included). Dedupe by id —
+      // background runs appear in both.
+      const runsProvider = () => {
+        const seen = new Set<string>();
+        const out: RunHandle[] = [];
+        for (const r of [...backgroundRuns.values(), ...liveRuns]) {
+          if (!seen.has(r.id)) {
+            seen.add(r.id);
+            out.push(r);
+          }
+        }
+        return out;
+      };
+      if (runsProvider().length === 0) {
+        ctx.ui.notify("No subagent runs yet.", "info");
+        return;
+      }
+      await ctx.ui.custom(
+        (tui, theme, _keybindings, done) =>
+          createViewPanel(runsProvider, tui, theme, () => done(undefined)),
+        {
+          overlay: true,
+          overlayOptions: { anchor: "center", width: "90%", maxHeight: "85%" },
+        },
+      );
+    },
+  });
+
   pi.registerCommand("subagent:doctor", {
     description: "Diagnose pi-subagent configuration and dependencies",
     handler: async (_args, ctx) => {

package/src/run.ts

@@ -24,6 +24,7 @@ import type {
   FallbackFrom,
   RunState,
   SubagentConfig,
+  SubagentControl,
   SubagentResult,
   SubagentRole,
 } from "./types.ts";
@@ -59,6 +60,8 @@ export interface RunHandle {
   readonly promise: Promise<SubagentResult>;
   /** Abort the run — no-op after settle. Tool-cancellation and session-shutdown reaping both funnel here. */
   abort(reason?: string): void;
+  /** Queue a steering message into the running child (RPC stdin). No-op when queued/settled. */
+  steer(message: string): void;
   /** Get notified on every frame change. Returns an unsubscribe function. */
   subscribe(fn: () => void): () => void;
 }
@@ -114,6 +117,8 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
   let result: SubagentResult | undefined;
   let thrown: Error | undefined;
   let settled = false;
+  /** Live stdin channel of the current spawn attempt (replaced on fallback retry). */
+  let control: SubagentControl | undefined;
   let abortReason: string | undefined;
   const controller = new AbortController();
   const onCallerAbort = () => controller.abort();
@@ -181,6 +186,10 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
       if (reason) abortReason = reason;
       controller.abort();
     },
+    steer(message: string) {
+      if (settled || currentState !== "running") return;
+      control?.steer(message);
+    },
     promise,
   };
 
@@ -291,6 +300,9 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
         depth: opts.depth,
         signal: controller.signal,
         onProgress: emitProgress,
+        onControl: (c) => {
+          control = c;
+        },
       });
 
       // Retry with fallback role on provider errors (quota, auth, timeout, etc.)
@@ -323,6 +335,9 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
             depth: opts.depth,
             signal: controller.signal,
             onProgress: emitProgress,
+            onControl: (c) => {
+              control = c;
+            },
           });
           runResult.fallbackFrom = fallbackFrom;
         }

package/src/spawn.test.ts

@@ -0,0 +1,49 @@
+/**
+ * Unit tests for spawn-side pure logic.
+ *
+ *   node --test packages/pi-subagent/src/spawn.test.ts
+ */
+
+import { test, describe } from "node:test";
+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";
+
+describe("composeInitialMessage", () => {
+  test("wraps reference files in <file> blocks ahead of context and task", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-sub-test-"));
+    try {
+      const fileA = path.join(dir, "a.md");
+      fs.writeFileSync(fileA, "alpha content");
+      const message = await composeInitialMessage([fileA], "some ctx", "do the thing");
+      assert.equal(
+        message,
+        `<file name="${fileA}">\nalpha content\n</file>\n\n<context>\nsome ctx\n</context>\n\n<task>\ndo the thing\n</task>`,
+      );
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("omits absent channels and preserves relative block order", async () => {
+    const message = await composeInitialMessage(undefined, undefined, "only a task");
+    assert.equal(message, "<task>\nonly a task\n</task>");
+    const ctxOnly = await composeInitialMessage(undefined, "ctx body", "");
+    assert.equal(ctxOnly, "<context>\nctx body\n</context>");
+  });
+
+  test("unreadable files degrade to a placeholder instead of failing the run", async () => {
+    const missing = path.join(os.tmpdir(), "pi-sub-test-does-not-exist.md");
+    const message = await composeInitialMessage([missing], undefined, "t");
+    assert.match(message, /^\[?<file name="/);
+    assert.match(message, /failed to read file/);
+    assert.match(message, /\n\n<task>\nt\n<\/task>$/);
+  });
+
+  test("blank (whitespace-only) context is dropped", async () => {
+    const message = await composeInitialMessage(undefined, "   \n\t", "t");
+    assert.equal(message, "<task>\nt\n</task>");
+  });
+});

package/src/spawn.ts

@@ -1,10 +1,11 @@
 /**
  * Spawn a pi child process and collect structured output with real-time progress.
  *
- * Uses pi's --mode json to get a JSON event stream. Fires onProgress on each
- * event for streaming TUI updates; the message stream is parsed for
- * usage/output extraction, with thinking blocks and tool calls mirrored into
- * the activity log for rendering.
+ * Uses pi's --mode rpc: the child streams agent events on stdout and accepts
+ * JSON commands on stdin (initial prompt, mid-run steering). Fires onProgress
+ * on each event for streaming TUI updates; the message stream is parsed for
+ * usage/output extraction, with thinking blocks, tool calls, and streamed
+ * assistant text mirrored into the activity log for rendering.
  */
 
 import { spawn, type ChildProcess } from "node:child_process";
@@ -12,10 +13,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import type { SubagentMessage, SubagentResult } from "./types.ts";
-
-/** Max chars for an inline channel block (context or task) before it spills to a temp @file. */
-const INLINE_LIMIT = 8000;
+import type { SubagentControl, SubagentMessage, SubagentResult } from "./types.ts";
 
 const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
 
@@ -133,6 +131,36 @@ export function getPiInvocation(args: string[]): { command: string; args: string
   return { command: "pi", 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
+ * json mode (@file arguments wrapped by pi's processFileArguments, followed by
+ * the inline message body).
+ *
+ * @internal — exported for testing.
+ */
+export async function composeInitialMessage(
+  files: string[] | undefined,
+  context: string | undefined,
+  task: string,
+): Promise<string> {
+  const parts: string[] = [];
+  if (files) {
+    for (const f of files) {
+      let content: string;
+      try {
+        content = await fs.promises.readFile(f, "utf-8");
+      } catch {
+        content = `(failed to read file: ${f})`;
+      }
+      parts.push(`<file name="${f}">\n${content}\n</file>`);
+    }
+  }
+  if (context?.trim()) parts.push(`<context>\n${context}\n</context>`);
+  if (task.trim()) parts.push(`<task>\n${task}\n</task>`);
+  return parts.join("\n\n");
+}
+
 /**
  * Spawn a pi child process with the given model and configuration.
  * Fires onProgress on each JSON event for streaming TUI updates.
@@ -153,7 +181,7 @@ export async function spawnSubagent(
     systemPrompt?: string;
     /** Extra context delivered as a separate channel from the task. */
     context?: string;
-    /** Reference file paths injected as independent @file args (child reads them directly). */
+    /** Reference files injected as <file> blocks in the initial prompt (child reads them directly). */
     contextFiles?: string[];
     subagentRoles?: string[];
     timeoutMs?: number;
@@ -164,6 +192,8 @@ export async function spawnSubagent(
     maxCost?: number;
     signal?: AbortSignal;
     onProgress?: (update: Partial<SubagentResult>) => void;
+    /** Called once the child process exists — exposes the stdin steering channel. */
+    onControl?: (control: SubagentControl) => void;
   },
 ): Promise<SubagentResult> {
   const result: SubagentResult = {
@@ -202,8 +232,9 @@ export async function spawnSubagent(
   let tmpDir: string | null = null;
 
   try {
-    // Build CLI args
-    const args: string[] = ["--mode", "json", "--no-session", "--model", modelRef];
+    // 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);
@@ -213,8 +244,9 @@ export async function spawnSubagent(
       args.push("--tools", options.tools.join(","));
     }
 
-    // Temp dir for: large-context/task spill files, and as PI_SUBAGENT_TMPDIR
-    // for subagent bash work (e.g. git clone).
+    // 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 ──
@@ -259,52 +291,13 @@ export async function spawnSubagent(
       ].join("\n"),
     );
 
-    // ── Context channel: independent size gate ──
-    // Large context spills to @ctx.md (pi auto-wraps in <file>); small context
-    // inlines as a structured <context> tag. Decoupled from the task gate so a
-    // large context never drags a short task into a spill file.
-    let contextInline = false;
-    if (options.context && options.context.trim()) {
-      if (options.context.length > INLINE_LIMIT) {
-        const ctxPath = path.join(tmpDir, "context.md");
-        await fs.promises.writeFile(ctxPath, options.context, { encoding: "utf-8", mode: 0o600 });
-        args.push(`@${ctxPath}`);
-      } else {
-        contextInline = true;
-      }
-    }
-
-    // ── Reference files channel: each as an independent @ argument ──
-    // pi reads each and wraps in <file name="...">. Content never enters the
-    // parent model's context — the child reads it directly.
-    if (options.contextFiles) {
-      for (const f of options.contextFiles) {
-        args.push(`@${f}`);
-      }
-    }
-
-    // ── Task channel: always inline, always the final block ──
-    // The task is an instruction, not reference material — it stays inline so the
-    // child sees it as the primary directive. A pathologically long task spills.
-    let taskInline = true;
-    if (task.length > INLINE_LIMIT) {
-      const taskPath = path.join(tmpDir, "task.md");
-      await fs.promises.writeFile(taskPath, task, { encoding: "utf-8", mode: 0o600 });
-      args.push(`@${taskPath}`);
-      taskInline = false;
-    }
-
-    // ── Compose the message body (inline context + task) ──
-    // @file args are injected by pi BEFORE this message (buildInitialMessage),
-    // so the final shape the child sees is:
-    //   [<file>...spilled context / reference files...</file>]
-    //   [<context>...inline context...</context>]
-    //   [<task>...task...</task>]
-    const messageParts: string[] = [];
-    if (contextInline) messageParts.push(`<context>\n${options.context}\n</context>`);
-    if (taskInline) messageParts.push(`<task>\n${task}\n</task>`);
-    const message = messageParts.join("\n\n");
-    if (message) args.push(message);
+    // ── Initial prompt channel: one RPC prompt command over stdin ──
+    // RPC mode rejects @file argv, so reference files are inlined here as
+    // <file name="..."> blocks — the same wrap pi applies to @file arguments
+    // (processFileArguments). Content still never enters the parent model's
+    // context; this process reads the bytes off disk and pipes them straight
+    // to the child.
+    const initialMessage = await composeInitialMessage(options.contextFiles, options.context, task);
 
     // Spawn process
     const invocation = getPiInvocation(args);
@@ -313,6 +306,15 @@ export async function spawnSubagent(
     let wasTimeout = false;
     let buffer = "";
 
+    /** Serialize one JSONL command frame for the child's stdin. */
+    const sendCommand = (command: Record<string, unknown>): void => {
+      try {
+        proc?.stdin?.write(`${JSON.stringify(command)}\n`);
+      } catch {
+        /* child gone — nothing to steer */
+      }
+    };
+
     const emitProgress = () => {
       options.onProgress?.({
         output: result.output,
@@ -326,9 +328,18 @@ export async function spawnSubagent(
     };
 
     let thinkingCounter = 0;
+    let textCounter = 0;
     // O(1) lookup from toolCallId → activityLog index.
     const toolCallIndex = new Map<string, number>();
 
+    // Streamed text deltas bypass the per-event emitProgress (copying the whole
+    // activityLog per token is quadratic); a time gate keeps live frames fresh
+    // enough for the :view overlay without flooding the frame pipeline.
+    let lastDeltaEmit = 0;
+    const DELTA_EMIT_INTERVAL_MS = 200;
+
+    let steerCounter = 0;
+
     // Normalized turn/cost budgets (0 = unlimited). Role overrides can arrive
     // raw from settings.json, so negatives/non-finites normalize here.
     const maxTurns = Number.isFinite(options.maxTurns) ? Math.max(0, options.maxTurns ?? 0) : 0;
@@ -353,6 +364,21 @@ export async function spawnSubagent(
         return;
       }
 
+      // RPC command acknowledgements ("response" lines) carry no agent state.
+      if (event.type === "response") return;
+
+      // RPC mode is a resident server: after the task completes (agent_end) the
+      // process would idle forever waiting for more stdin commands. We run one
+      // prompt per child, so ending our stdin side triggers its graceful
+      // shutdown (onInputEnd → runtime dispose → exit).
+      if (event.type === "agent_end") {
+        try {
+          proc?.stdin?.end();
+        } catch {
+          /* already gone */
+        }
+      }
+
       if (event.type === "message_end" && event.message) {
         const msg = event.message as SubagentMessage;
 
@@ -385,6 +411,7 @@ export async function spawnSubagent(
           checkBudget();
         }
 
+        freezeRunningTextEntries();
         emitProgress();
       }
 
@@ -444,6 +471,38 @@ export async function spawnSubagent(
             }
           }
           emitProgress();
+        } else if (aev.type === "text_start") {
+          result.activityLog.push({
+            kind: "text",
+            id: `text-${textCounter++}`,
+            status: "running",
+            text: "",
+          });
+          emitProgress();
+        } else if (aev.type === "text_delta" && aev.delta) {
+          // Append to the still-running text entry; skip the frame copy per token.
+          for (let i = result.activityLog.length - 1; i >= 0; i--) {
+            const entry = result.activityLog[i];
+            if (entry.kind === "text" && entry.status === "running") {
+              entry.text = (entry.text ?? "") + aev.delta;
+              break;
+            }
+            if (entry.kind === "text") break;
+          }
+          const now = Date.now();
+          if (now - lastDeltaEmit >= DELTA_EMIT_INTERVAL_MS) {
+            lastDeltaEmit = now;
+            emitProgress();
+          }
+        }
+      }
+    };
+
+    /** Freeze every still-running text entry — called on message_end (turn boundary). */
+    const freezeRunningTextEntries = () => {
+      for (const entry of result.activityLog) {
+        if (entry.kind === "text" && entry.status === "running") {
+          entry.status = "done";
         }
       }
     };
@@ -555,12 +614,34 @@ export async function spawnSubagent(
         cwd: options.cwd,
         env: childEnv,
         shell: false,
-        stdio: ["ignore", "pipe", "pipe"],
+        stdio: ["pipe", "pipe", "pipe"],
       });
       proc = p;
       liveChildren.add(p);
       reapChildrenOnExit();
 
+      // Expose the stdin control channel (steering) to the owner. Writes are
+      // fire-and-forget: once the child is gone the try/catch in sendCommand
+      // swallows EPIPE.
+      options.onControl?.({
+        steer(message: string) {
+          if (processExited || terminationRequested) return;
+          sendCommand({ type: "steer", message });
+          // Mirror the steer into the activity feed so the :view overlay shows
+          // what was injected and when.
+          result.activityLog.push({
+            kind: "steer",
+            id: `steer-${steerCounter++}`,
+            status: "done",
+            text: message,
+          });
+          emitProgress();
+        },
+      });
+
+      // Kick off the run: RPC mode starts idle and waits for a prompt command.
+      sendCommand({ id: "init", type: "prompt", message: initialMessage });
+
       p.stdout.on("data", (data: Buffer) => {
         buffer += data.toString();
         const lines = buffer.split("\n");

package/src/types.ts

@@ -74,15 +74,23 @@ export interface SubagentRole {
 /** Status of an individual tool call within a subagent run. */
 export type ToolStatus = "running" | "done" | "failed";
 
-/** A single entry in the real-time activity log (thinking block or tool call). */
+/** A single entry in the real-time activity log (thinking block, tool call, streamed assistant text, or a user steer). */
 export interface ActivityEntry {
-  kind: "thinking" | "toolCall";
-  /** Synthetic id (thinking-N) or the toolCallId from the event stream. */
+  kind: "thinking" | "toolCall" | "text" | "steer";
+  /** Synthetic id (thinking-N / text-N / steer-N) or the toolCallId from the event stream. */
   id: string;
   status: ToolStatus;
   /** Tool name + args (toolCall only). */
   toolName?: string;
   args?: Record<string, any>;
+  /** Accumulated streamed assistant text or the injected steer message (kinds "text"/"steer"). Grows in place until message_end freezes text entries. */
+  text?: string;
+}
+
+/** Live control channel into a spawned child process (wired to the RPC stdin). */
+export interface SubagentControl {
+  /** Queue a steering message — delivered after the child's current tool batch, before its next LLM call. No-op after the process exits. */
+  steer(message: string): void;
 }
 
 /** Usage statistics from a subagent execution. */

package/src/utils.test.ts

@@ -40,8 +40,9 @@ import {
   freezeFrame,
   createThrottler,
   terminalResultLine,
+  buildDisplayItems,
 } from "./utils.ts";
-import type { SubagentResult, SubagentRole } from "./types.ts";
+import type { ActivityEntry, SubagentResult, SubagentRole } from "./types.ts";
 
 /** Shared SubagentResult fixture. */
 const baseResult = (overrides: Partial<SubagentResult> = {}): SubagentResult => ({
@@ -693,3 +694,38 @@ describe("background run helpers", () => {
     assert.ok(frozen.graceMs! >= 3000 && frozen.graceMs! <= 3010, `graceMs ~3000, got ${frozen.graceMs}`);
   });
 });
+
+describe("streamed-text activity entries", () => {
+  const textEntry = (status: ActivityEntry["status"], text?: string): ActivityEntry => ({
+    kind: "text",
+    id: "text-0",
+    status,
+    ...(text !== undefined ? { text } : {}),
+  });
+
+  test("buildDisplayItems excludes text entries (view-only content)", () => {
+    const log: ActivityEntry[] = [
+      { kind: "thinking", id: "thinking-0", status: "done" },
+      { kind: "toolCall", id: "call-1", status: "done", toolName: "bash", args: { command: "ls" } },
+      textEntry("done", "partial answer"),
+    ];
+    const items = buildDisplayItems(log);
+    assert.equal(items.length, 2);
+    assert.deepEqual(items.map((i) => i.type), ["thinking", "toolCall"]);
+  });
+
+  test("buildDisplayItems returns empty for a text-only log", () => {
+    assert.deepEqual(buildDisplayItems([textEntry("running", "streaming...")]), []);
+  });
+
+  test("describeCurrentActivity reports responding for a running text entry", () => {
+    assert.equal(
+      describeCurrentActivity({ activityLog: [textEntry("running", "hello")] }),
+      "responding",
+    );
+    assert.equal(
+      describeCurrentActivity({ activityLog: [textEntry("done", "hello")] }),
+      "responded",
+    );
+  });
+});

package/src/utils.ts

@@ -113,13 +113,19 @@ export type DisplayItem =
   | { type: "toolCall"; name: string; args: Record<string, any>; status?: ToolStatus }
   | { type: "thinking"; status?: ToolStatus };
 
-/** Map the real-time activity log into renderable display items (in order). */
+/**
+ * Map the real-time activity log into renderable display items (in order).
+ * Streamed-text entries are excluded — they are the :view overlay's exclusive
+ * content; the inline tool rows stay as they were.
+ */
 export function buildDisplayItems(activityLog: ActivityEntry[]): DisplayItem[] {
-  return activityLog.map((a) =>
-    a.kind === "thinking"
-      ? { type: "thinking", status: a.status }
-      : { type: "toolCall", name: a.toolName ?? "?", args: a.args ?? {}, status: a.status },
-  );
+  return activityLog
+    .filter((a) => a.kind === "thinking" || a.kind === "toolCall")
+    .map((a) =>
+      a.kind === "thinking"
+        ? { type: "thinking", status: a.status }
+        : { type: "toolCall", name: a.toolName ?? "?", args: a.args ?? {}, status: a.status },
+    );
 }
 
 export function shortenPath(p: string): string {
@@ -483,6 +489,8 @@ export function describeCurrentActivity(r: { activityLog: ActivityEntry[] }): st
   const last = r.activityLog[r.activityLog.length - 1];
   if (!last) return "waiting for first event";
   if (last.kind === "thinking") return last.status === "running" ? "thinking" : "thought";
+  if (last.kind === "text") return last.status === "running" ? "responding" : "responded";
+  if (last.kind === "steer") return "steered — awaiting next turn";
   return formatToolCall(last.toolName ?? "?", last.args ?? {}, (_color, text) => text);
 }
 

package/src/view.ts

@@ -0,0 +1,292 @@
+/**
+ * /subagent:view — live activity overlay for subagent runs.
+ *
+ * Design: a continuous, append-only list. Every entry is static text plus a
+ * state bit; the only animated thing is the ellipsis on a running entry's
+ * suffix ("." → ".." → "..."). Finishing freezes an entry in place — its
+ * position never changes, only the icon flips. Multiple runs stack: one
+ * header line per run, entries flowing beneath it; concurrent tool calls are
+ * adjacent spinning lines. Streamed assistant text is the single growing
+ * element: it renders as the run's last line and freezes at message_end.
+ *
+ * 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.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+  Editor,
+  type Component,
+  type EditorTheme,
+  type Focusable,
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
+import type { RunHandle } from "./run.ts";
+import type { ActivityEntry } from "./types.ts";
+import {
+  formatThinking,
+  formatTimePart,
+  formatToolCall,
+  formatUsageStats,
+  runIcon,
+  statusStyle,
+  taskPreview,
+} from "./utils.ts";
+
+/** Max body lines kept visible; older entries roll off the top. */
+const VIEWPORT_LINES = 26;
+/** Animation tick for the running-entry ellipsis. */
+const ANIMATION_INTERVAL_MS = 150;
+
+type TuiLike = { requestRender(): void };
+type Fg = (color: string, text: string) => string;
+
+/** Pad a string with trailing spaces to a visible width (left-justified). */
+function padRight(s: string, width: number): string {
+  const v = visibleWidth(s);
+  return v >= width ? s : s + " ".repeat(width - v);
+}
+
+/** Animated ellipsis suffix for running entries: ".", "..", "..." cycling. */
+function dots(): string {
+  return ".".repeat(1 + (Math.floor(Date.now() / 300) % 3));
+}
+
+/**
+ * Build the display list of runs for the panel: running/queued first, then
+ * finished, each group ordered by registry id.
+ */
+export function sortViewRuns(runs: RunHandle[]): RunHandle[] {
+  const rank = (r: RunHandle) => (r.state === "running" || r.state === "queued" ? 0 : 1);
+  return [...runs].sort((a, b) => rank(a) - rank(b) || a.id.localeCompare(b.id));
+}
+
+export class SubagentViewPanel implements Component, Focusable {
+  focused = true;
+
+  private runsProvider: () => RunHandle[];
+  private theme: Theme;
+  private tui: TuiLike;
+  private close: () => void;
+  private editor: Editor;
+  /** Focused run (Tab cycles); the whole viewport belongs to it. */
+  private focusIndex = 0;
+  /** Transient feedback line ("steer sent to sub-N"), auto-clears. */
+  private flash = "";
+  private flashUntil = 0;
+  private timer?: ReturnType<typeof setInterval>;
+
+  constructor(
+    runsProvider: () => RunHandle[],
+    tui: TuiLike,
+    theme: Theme,
+    onClose: () => void,
+  ) {
+    this.runsProvider = runsProvider;
+    this.tui = tui;
+    this.theme = theme;
+    this.close = onClose;
+
+    const editorTheme: EditorTheme = {
+      borderColor: (s) => theme.fg("accent", s),
+      selectList: {
+        selectedPrefix: (t) => theme.fg("accent", t),
+        selectedText: (t) => theme.fg("accent", t),
+        description: (t) => theme.fg("muted", t),
+        scrollInfo: (t) => theme.fg("dim", t),
+        noMatch: (t) => theme.fg("warning", t),
+      },
+    };
+    this.editor = new Editor(tui as never, editorTheme);
+    this.editor.onSubmit = (value) => this.submitSteer(value);
+
+    // Drive the ellipsis animation while the panel is open.
+    this.timer = setInterval(() => {
+      try {
+        this.tui.requestRender();
+      } catch {
+        /* ignore */
+      }
+    }, ANIMATION_INTERVAL_MS);
+  }
+
+  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];
+  }
+
+  private submitSteer(value: string): void {
+    const text = value.trim();
+    if (!text) return;
+    const target = this.focusedRun();
+    if (!target || target.state !== "running") {
+      this.showFlash("focused run is not running — nothing to steer");
+      return;
+    }
+    target.steer(text);
+    this.editor.setText("");
+    this.showFlash(`steer queued for ${target.id} (${target.role})`);
+  }
+
+  private showFlash(message: string): void {
+    this.flash = message;
+    this.flashUntil = Date.now() + 3000;
+  }
+
+  handleInput(data: string): void {
+    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();
+      }
+      return;
+    }
+    this.editor.handleInput(data);
+    this.tui.requestRender();
+  }
+
+  private closePanel(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+    this.close();
+  }
+
+  /** Render one activity entry as a static line; running entries get the
+   *  animated ellipsis suffix. */
+  private renderEntry(e: ActivityEntry, width: number, fg: Fg): string {
+    const indent = "  ";
+    if (e.kind === "thinking") {
+      if (e.status === "running") {
+        return truncateToWidth(indent + fg("accent", `◇ thinking${dots()}`), width);
+      }
+      return truncateToWidth(indent + formatThinking(e.status, fg), width);
+    }
+    if (e.kind === "steer") {
+      const firstLine = (e.text ?? "").trimEnd().split("\n")[0] || "";
+      return truncateToWidth(indent + fg("accent", `↩ steer: ${firstLine}`), width);
+    }
+    if (e.kind === "text") {
+      const buffer = e.text ?? "";
+      const lastLine = buffer.trimEnd().split("\n").pop() ?? "";
+      const body = lastLine || "…";
+      if (e.status === "running") {
+        return truncateToWidth(indent + fg("accent", `¶ ${body}${dots()}`), width);
+      }
+      // Frozen: no ANSI at all — same plain terminal foreground as the main
+      // UI's output text (theme "text" is a grey var, not the default fg).
+      return truncateToWidth(indent + `¶ ${body}`, width);
+    }
+    const { prefix, color } = statusStyle(e.status, fg);
+    const suffix = e.status === "running" ? fg("accent", ` ${dots()}`) : "";
+    const line = prefix + formatToolCall(e.toolName ?? "?", e.args ?? {}, color) + suffix;
+    return truncateToWidth(indent + line, width);
+  }
+
+  render(width: number): string[] {
+    const th = this.theme;
+    // Same adaptation render.ts uses: utils formatters take a loose Fg.
+    const fg = th.fg.bind(th) as unknown as Fg;
+    // Border frame: inner content lives at width-2.
+    const innerW = Math.max(20, width - 2);
+    const row = (content: string) => {
+      const fitted = truncateToWidth(content, innerW);
+      return th.fg("border", "│") + padRight(fitted, innerW) + th.fg("border", "│");
+    };
+
+    const runs = sortViewRuns(this.runsProvider());
+    const lines: string[] = [];
+
+    const runningCount = runs.filter((r) => r.state === "running").length;
+
+    // ── 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 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}]`;
+      });
+      lines.push(
+        row(
+          `${fg("accent", th.bold("subagents"))} ${th.fg("dim", `${runningCount} running · ${runs.length} total · Tab switch`)}  ` +
+            cells.join(th.fg("dim", " ")),
+        ),
+      );
+    } else {
+      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;
+      const icon = runIcon(snap, fg);
+      const time = formatTimePart({ ...snap, exitCode: run.state === "queued" ? -1 : snap.exitCode });
+      const parts = [
+        `${icon} ${fg("accent", th.bold(run.id))}`,
+        fg("text", run.role),
+        fg("dim", taskPreview(run.task)),
+        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));
+    }
+    lines.push(row(fg("dim", "Enter steer · Tab switch run · Esc close")));
+
+    // Frame.
+    return [
+      th.fg("border", `╭${"─".repeat(innerW)}╮`),
+      ...lines,
+      th.fg("border", `╰${"─".repeat(innerW)}╯`),
+    ];
+  }
+
+  invalidate(): void {}
+}
+
+/** Wire the panel to the overlay lifecycle: the animation timer dies with the panel. */
+export function createViewPanel(
+  runsProvider: () => RunHandle[],
+  tui: TuiLike,
+  theme: Theme,
+  onClose: () => void,
+): SubagentViewPanel {
+  return new SubagentViewPanel(runsProvider, tui, theme, onClose);
+}