pi-subagents/docs/superpowers/specs/2026-04-12-subagent-live-progress-design.md

# Subagent Live Progress Rendering Design

**Date:** 2026-04-12  
**Package:** `pi-subagents`

## Goal

Make a running subagent show what the child agent is actually doing instead of collapsing every live update to raw event names like `tool_call` and `tool_result`.

## Current state

Today `src/tool.ts` handles every child event with the same parent-facing update:

- `Running subagent: ${event.type}`

That loses the useful semantics already present in normalized events:

- assistant turns may already contain human-readable status text
- tool calls carry actionable args like file paths and commands
- tool results can tell whether a step finished or failed

`src/wrapper/render.mjs` already renders transcript lines, but its tool fallback is still JSON-shaped and the parent live UI does not reuse it. As a result, the live progress display is much less informative than the underlying event stream.

## Chosen approach

Use a **shared progress formatter**.

Behavior order:

1. prefer child `assistant_text` when it contains non-empty text
2. otherwise render humanized tool activity from normalized tool events
3. use concise completion/failure wording for tool results based on remembered tool context

Use the same formatter for:

- parent live progress updates in `src/tool.ts`
- transcript event rendering in `src/wrapper/render.mjs`

Keep the wrapper event protocol, runner behavior, artifacts, and `result.json` semantics unchanged.

## Scope

### Modify

- `src/tool.ts`
- `src/wrapper/render.mjs`
- new shared formatter module for normalized progress events
- `src/tool.test.ts`
- `src/wrapper/render.test.ts`

### Do not modify

- `index.ts`
- `src/process-runner.ts`
- `src/tmux-runner.ts`
- `src/wrapper/cli.mjs` event/result lifecycle
- `src/wrapper/normalize.mjs`
- artifact layout or `result.json` fields

## Design

### 1. Progress priority

When a normalized event is `assistant_text` and `text` is non-empty:

- show that text to the parent as the live status
- render that same text in the transcript as today
- do not replace it with a generic tool label

This matches the product goal best because the child assistant can express intent directly, for example:

- `I’m inspecting the auth flow now.`
- `I found the schema; next I’m checking validation.`

Blank assistant text should not generate a noisy no-op status line.

### 2. Tool activity fallback

When there is no usable assistant text, render normalized tool events into action text.

Examples of desired fallback wording:

- `read` -> `Reading src/auth.ts`
- `grep` -> `Searching code for auth`
- `find` -> `Scanning for *.test.ts`
- `ls` -> `Listing src/`
- `edit` -> `Editing src/tool.ts`
- `write` -> `Writing README.md`
- `bash` -> keep the shortened shell command, because the command already states the action
- unknown tool -> `Running <toolName>`

The formatter should use available arguments conservatively:

- prefer exact paths, patterns, and commands already present in the event
- do not invent missing detail
- if args are absent, fall back to a generic tool name message instead of guessing

### 3. Tool result wording

`tool_result` should not surface as bare `tool_result`.

Instead, it should render a concise completion/failure message tied to the most recent relevant tool context when available, for example:

- `Finished reading src/auth.ts`
- `Search finished`
- `Edit failed: src/tool.ts`

If no matching prior tool context is available, use a conservative generic result line such as:

- `read finished`
- `grep failed`

This keeps progress understandable without requiring protocol changes.

### 4. Shared rendering boundary

The new shared formatter module owns conversion from normalized child events to user-facing progress text.

Responsibilities:

- map known tools to humanized action strings
- preserve assistant text when present
- derive concise result wording from recent tool context
- keep unknown tools conservative

`src/tool.ts` should use this formatter for parent `onUpdate` messages.

`src/wrapper/render.mjs` should use the same formatter for transcript event lines so live UI and transcript do not drift.

The existing transcript header stays unchanged and generic.

### 5. Failure and noise handling

Keep behavior minimal and predictable:

- blank assistant text -> emit nothing
- unknown tool -> generic `Running <toolName>` / `<toolName> finished` / `<toolName> failed`
- no tool context for a result -> generic result wording
- artifact/result writing behavior stays unchanged
- no new event types, no wrapper protocol expansion

## Testing strategy

Follow TDD.

### First failing tests

1. `src/tool.test.ts`
   - assistant text is surfaced directly when present
   - fallback tool updates are humanized
   - parent progress no longer shows raw `tool_call` / `tool_result`

2. `src/wrapper/render.test.ts`
   - known tools render as action text instead of JSON-shaped fallback lines
   - result lines use completion/failure wording
   - bash still renders as shortened command text

### Verification after implementation

Run at least:

- targeted test files for touched units
- full package suite: `npm test`

## Non-goals

- changing child wrapper completion behavior
- changing normalized event schema
- adding runner-specific progress logic
- redesigning artifact files or transcript headers
- inventing semantic summaries beyond the data already present in events

## Expected outcome

After the change, a running subagent will show meaningful status like assistant intent text or readable tool activity instead of raw event-type labels. The parent live UI and saved transcript will use the same progress language while keeping runner behavior, wrapper semantics, and result artifacts stable.