@tintinweb/pi-subagents 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-03-11
+
+### Added
+- **XML-delimited prompt sections** — append-mode agents now wrap inherited content in `<inherited_system_prompt>`, `<sub_agent_context>`, and `<agent_instructions>` XML tags, giving the model explicit structure to distinguish inherited rules from sub-agent-specific instructions. Replace mode is unchanged.
+- **Token count in agent results** — foreground agent results, background completion notifications, and `get_subagent_result` now include the token count alongside tool uses and duration (e.g. `Agent completed in 4.2s (12 tool uses, 33.8k token)`).
+- **Widget overflow cap** — the running agents widget now caps at 12 lines. When exceeded, running agents are prioritized over finished ones and an overflow summary line shows hidden counts (e.g. `+3 more (1 running, 2 finished)`).
+
+### Changed - **changing behavior**
+- **General-purpose agent inherits parent prompt** — the default `general-purpose` agent now uses `promptMode: "append"` with an empty system prompt, making it a "parent twin" that inherits the full parent system prompt (including CLAUDE.md rules, project conventions, and safety guardrails). Previously it used a standalone prompt that duplicated a subset of the parent's rules. Explore and Plan are unchanged (standalone prompts). To customize: eject via `/agents` → select `general-purpose` → Eject, then edit the resulting `.md` file. Set `prompt_mode: replace` to go back to a standalone prompt, or keep `prompt_mode: append` and add extra instructions in the body.
+- **Append-mode agents receive parent system prompt** — `buildAgentPrompt` now accepts the parent's system prompt and threads it into append-mode agents (env header + parent prompt + sub-agent context bridge + optional custom instructions). Replace-mode agents are unchanged.
+- **Prompt pipeline simplified** — removed `systemPromptOverride`/`systemPromptAppend` from `SpawnOptions` and `RunOptions`. These were a separate code path where `index.ts` pre-resolved the prompt mode and passed raw strings into the runner, bypassing `buildAgentPrompt`. Now all prompt assembly flows through `buildAgentPrompt` using the agent's `promptMode` config — one code path, no special cases.
+
+### Removed
+- Deprecated backwards-compat aliases: `registerCustomAgents`, `getCustomAgentConfig`, `getCustomAgentNames` (use `registerAgents`, `getAgentConfig`, `getUserAgentNames`).
+- `resolveCustomPrompt()` helper in index.ts — no longer needed now that prompt routing is config-driven.
+
+## [0.3.1] - 2026-03-09
+
+### Added
+- **Live conversation viewer** — selecting a running (or completed) agent in `/agents` → "Running agents" now opens a scrollable overlay showing the agent's full conversation in real time. Auto-scrolls to follow new content; scroll up to pause, End to resume. Press Esc to close.
+
 ## [0.3.0] - 2026-03-08
 
 ### Added
@@ -134,7 +155,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - **Claude Code-style UI rendering** — `renderCall`/`renderResult`/`onUpdate` for live streaming progress
   - Live activity descriptions: "searching, reading 3 files…"
-  - Token count display: "33.8k tokens"
+  - Token count display: "33.8k token"
   - Per-agent tool use counter
   - Expandable completed results (ctrl+o)
   - Distinct states: running, background, completed, error, aborted
@@ -167,6 +188,8 @@ Initial release.
 - **Thinking level** — per-agent extended thinking control
 - **`/agent` and `/agents` commands**
 
+[0.4.0]: https://github.com/tintinweb/pi-subagents/compare/v0.3.1...v0.4.0
+[0.3.1]: https://github.com/tintinweb/pi-subagents/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/tintinweb/pi-subagents/compare/v0.2.7...v0.3.0
 [0.2.7]: https://github.com/tintinweb/pi-subagents/compare/v0.2.6...v0.2.7
 [0.2.6]: https://github.com/tintinweb/pi-subagents/compare/v0.2.5...v0.2.6

package/README.md

@@ -7,7 +7,7 @@ A [pi](https://pi.dev) extension that brings **Claude Code-style autonomous sub-
 <img width="600" alt="pi-subagents screenshot" src="https://github.com/tintinweb/pi-subagents/raw/master/media/screenshot.png" />
 
 
-https://github.com/user-attachments/assets/5d1331e8-6d02-420b-b30a-dcbf838b1660
+https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 
 
 ## Features
@@ -15,6 +15,7 @@ https://github.com/user-attachments/assets/5d1331e8-6d02-420b-b30a-dcbf838b1660
 - **Claude Code look & feel** — same tool names, calling conventions, and UI patterns (`Agent`, `get_subagent_result`, `steer_subagent`) — feels native
 - **Parallel background agents** — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4) and smart group join (consolidated notifications)
 - **Live widget UI** — persistent above-editor widget with animated spinners, live tool activity, token counts, and colored status icons
+- **Conversation viewer** — select any agent in `/agents` to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause)
 - **Custom agent types** — define agents in `.pi/agents/<name>.md` with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions
 - **Mid-run steering** — inject messages into running agents to redirect their work without restarting
 - **Session resume** — pick up where an agent left off, preserving full conversation context
@@ -56,9 +57,9 @@ The extension renders a persistent widget above the editor showing all active ag
 
 ```
 ● Agents
-├─ ⠹ Agent  Refactor auth module · 5 tool uses · 33.8k tokens · 12.3s
+├─ ⠹ Agent  Refactor auth module · 5 tool uses · 33.8k token · 12.3s
 │    ⎿  editing 2 files…
-├─ ⠹ Explore  Find auth files · 3 tool uses · 12.4k tokens · 4.1s
+├─ ⠹ Explore  Find auth files · 3 tool uses · 12.4k token · 4.1s
 │    ⎿  searching…
 └─ 2 queued
 ```
@@ -67,24 +68,26 @@ Individual agent results render Claude Code-style in the conversation:
 
 | State | Example |
 |-------|---------|
-| **Running** | `⠹ 3 tool uses · 12.4k tokens` / `⎿ searching, reading 3 files…` |
-| **Completed** | `✓ 5 tool uses · 33.8k tokens · 12.3s` / `⎿ Done` |
-| **Wrapped up** | `✓ 50 tool uses · 89.1k tokens · 45.2s` / `⎿ Wrapped up (turn limit)` |
-| **Stopped** | `■ 3 tool uses · 12.4k tokens` / `⎿ Stopped` |
-| **Error** | `✗ 3 tool uses · 12.4k tokens` / `⎿ Error: timeout` |
-| **Aborted** | `✗ 55 tool uses · 102.3k tokens` / `⎿ Aborted (max turns exceeded)` |
+| **Running** | `⠹ 3 tool uses · 12.4k token` / `⎿ searching, reading 3 files…` |
+| **Completed** | `✓ 5 tool uses · 33.8k token · 12.3s` / `⎿ Done` |
+| **Wrapped up** | `✓ 50 tool uses · 89.1k token · 45.2s` / `⎿ Wrapped up (turn limit)` |
+| **Stopped** | `■ 3 tool uses · 12.4k token` / `⎿ Stopped` |
+| **Error** | `✗ 3 tool uses · 12.4k token` / `⎿ Error: timeout` |
+| **Aborted** | `✗ 55 tool uses · 102.3k token` / `⎿ Aborted (max turns exceeded)` |
 
 Completed results can be expanded (ctrl+o in pi) to show the full agent output inline.
 
 ## Default Agent Types
 
-| Type | Tools | Model | Description |
-|------|-------|-------|-------------|
-| `general-purpose` | all 7 | inherit | Full read/write access for complex multi-step tasks |
-| `Explore` | read, bash, grep, find, ls | haiku (falls back to inherit) | Fast codebase exploration (read-only) |
-| `Plan` | read, bash, grep, find, ls | inherit | Software architect for implementation planning (read-only) |
+| Type | Tools | Model | Prompt Mode | Description |
+|------|-------|-------|-------------|-------------|
+| `general-purpose` | all 7 | inherit | `append` (parent twin) | Inherits the parent's full system prompt — same rules, CLAUDE.md, project conventions |
+| `Explore` | read, bash, grep, find, ls | haiku (falls back to inherit) | `replace` (standalone) | Fast codebase exploration (read-only) |
+| `Plan` | read, bash, grep, find, ls | inherit | `replace` (standalone) | Software architect for implementation planning (read-only) |
 
-Default agents can be **overridden** by creating a `.md` file with the same name (e.g. `.pi/agents/Explore.md`), or **disabled** per-project by creating a `.md` file with `enabled: false` frontmatter.
+The `general-purpose` agent is a **parent twin** — it receives the parent's entire system prompt plus a sub-agent context bridge, so it follows the same rules the parent does. Explore and Plan use standalone prompts tailored to their read-only roles.
+
+Default agents can be **ejected** (`/agents` → select agent → Eject) to export them as `.md` files for customization, **overridden** by creating a `.md` file with the same name (e.g. `.pi/agents/general-purpose.md`), or **disabled** per-project with `enabled: false` frontmatter.
 
 ## Custom Agents
 
@@ -139,7 +142,7 @@ All fields are optional — sensible defaults for everything.
 | `model` | inherit parent | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`) |
 | `thinking` | inherit | off, minimal, low, medium, high, xhigh |
 | `max_turns` | 50 | Max agentic turns before graceful shutdown |
-| `prompt_mode` | `replace` | `replace`: body is the full system prompt. `append`: body appended to default prompt |
+| `prompt_mode` | `replace` | `replace`: body is the full system prompt. `append`: body appended to parent's prompt (agent acts as a "parent twin" with optional extra instructions) |
 | `inherit_context` | `false` | Fork parent conversation into agent |
 | `run_in_background` | `false` | Run in background by default |
 | `isolated` | `false` | No extension/MCP tools, only built-in |
@@ -264,7 +267,8 @@ src/
   context.ts          # Parent conversation context for inherit_context
   env.ts              # Environment detection (git, platform)
   ui/
-    agent-widget.ts   # Persistent widget: spinners, activity, status icons, theming
+    agent-widget.ts       # Persistent widget: spinners, activity, status icons, theming
+    conversation-viewer.ts # Live conversation overlay for viewing agent sessions
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",

package/src/agent-manager.ts

@@ -33,8 +33,6 @@ interface SpawnOptions {
   isolated?: boolean;
   inheritContext?: boolean;
   thinkingLevel?: ThinkingLevel;
-  systemPromptOverride?: string;
-  systemPromptAppend?: string;
   isBackground?: boolean;
   /** Called on tool start/end with activity info (for streaming progress to UI). */
   onToolActivity?: (activity: ToolActivity) => void;
@@ -122,8 +120,6 @@ export class AgentManager {
       isolated: options.isolated,
       inheritContext: options.inheritContext,
       thinkingLevel: options.thinkingLevel,
-      systemPromptOverride: options.systemPromptOverride,
-      systemPromptAppend: options.systemPromptAppend,
       signal: record.abortController!.signal,
       onToolActivity: (activity) => {
         if (activity.type === "end") record.toolUses++;

package/src/agent-runner.ts

@@ -84,10 +84,6 @@ export interface RunOptions {
   isolated?: boolean;
   inheritContext?: boolean;
   thinkingLevel?: ThinkingLevel;
-  /** Override system prompt entirely (for custom agents with promptMode: "replace"). */
-  systemPromptOverride?: string;
-  /** Append to default system prompt (for custom agents with promptMode: "append"). */
-  systemPromptAppend?: string;
   /** Called on tool start/end with activity info. */
   onToolActivity?: (activity: ToolActivity) => void;
   /** Called on streaming text deltas from the assistant response. */
@@ -142,57 +138,27 @@ export async function runAgent(
   const agentConfig = getAgentConfig(type);
   const env = await detectEnv(options.pi, ctx.cwd);
 
-  // Build system prompt: custom override > custom append > config-driven
+  // Get parent system prompt for append-mode agents
+  const parentSystemPrompt = ctx.getSystemPrompt();
+
+  // Build system prompt from agent config
   let systemPrompt: string;
-  if (options.systemPromptOverride) {
-    systemPrompt = options.systemPromptOverride;
-  } else if (options.systemPromptAppend) {
-    // Build a default prompt and append to it
-    const defaultConfig = agentConfig ?? {
-      name: type,
-      description: "",
-      builtinToolNames: [],
-      extensions: true,
-      skills: true,
-      systemPrompt: "",
-      promptMode: "replace" as const,
-      inheritContext: false,
-      runInBackground: false,
-      isolated: false,
-    };
-    systemPrompt = buildAgentPrompt(defaultConfig, ctx.cwd, env) + "\n\n" + options.systemPromptAppend;
-  } else if (agentConfig) {
-    systemPrompt = buildAgentPrompt(agentConfig, ctx.cwd, env);
+  if (agentConfig) {
+    systemPrompt = buildAgentPrompt(agentConfig, ctx.cwd, env, parentSystemPrompt);
   } else {
-    // Unknown type — use a minimal general-purpose prompt
+    // Unknown type fallback: general-purpose (defensive — unreachable in practice
+    // since index.ts resolves unknown types to "general-purpose" before calling runAgent)
     systemPrompt = buildAgentPrompt({
       name: type,
       description: "General-purpose agent",
-      builtinToolNames: [],
+      systemPrompt: "",
+      promptMode: "append",
       extensions: true,
       skills: true,
-      systemPrompt: `# Role
-You are a general-purpose coding agent for complex, multi-step tasks.
-You have full access to read, write, edit files, and execute commands.
-Do what has been asked; nothing more, nothing less.
-
-# Tool Usage
-- Use the read tool instead of cat/head/tail
-- Use the edit tool instead of sed/awk
-- Use the write tool instead of echo/heredoc
-- Use the find tool instead of bash find/ls for file search
-- Use the grep tool instead of bash grep/rg for content search
-- Make independent tool calls in parallel
-
-# Output
-- Use absolute file paths
-- Do not use emojis
-- Be concise but complete`,
-      promptMode: "replace",
       inheritContext: false,
       runInBackground: false,
       isolated: false,
-    }, ctx.cwd, env);
+    }, ctx.cwd, env, parentSystemPrompt);
   }
 
   const tools = getToolsForType(type, ctx.cwd);

package/src/agent-types.ts

@@ -125,6 +125,7 @@ export function getConfig(type: string): {
   builtinToolNames: string[];
   extensions: true | string[] | false;
   skills: true | string[] | false;
+  promptMode: "replace" | "append";
 } {
   const key = resolveKey(type);
   const config = key ? agents.get(key) : undefined;
@@ -135,6 +136,7 @@ export function getConfig(type: string): {
       builtinToolNames: config.builtinToolNames ?? BUILTIN_TOOL_NAMES,
       extensions: config.extensions,
       skills: config.skills,
+      promptMode: config.promptMode,
     };
   }
 
@@ -147,6 +149,7 @@ export function getConfig(type: string): {
       builtinToolNames: gp.builtinToolNames ?? BUILTIN_TOOL_NAMES,
       extensions: gp.extensions,
       skills: gp.skills,
+      promptMode: gp.promptMode,
     };
   }
 
@@ -157,21 +160,7 @@ export function getConfig(type: string): {
     builtinToolNames: BUILTIN_TOOL_NAMES,
     extensions: true,
     skills: true,
+    promptMode: "append",
   };
 }
 
-// ---- Backwards-compatible aliases ----
-
-/** @deprecated Use registerAgents instead */
-export const registerCustomAgents = registerAgents;
-
-/** @deprecated Use getAgentConfig instead */
-export function getCustomAgentConfig(name: string): AgentConfig | undefined {
-  const key = resolveKey(name);
-  return key ? agents.get(key) : undefined;
-}
-
-/** @deprecated Use getUserAgentNames instead */
-export function getCustomAgentNames(): string[] {
-  return getUserAgentNames();
-}

package/src/default-agents.ts

@@ -18,42 +18,8 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
       // builtinToolNames omitted — means "all available tools" (resolved at lookup time)
       extensions: true,
       skills: true,
-      systemPrompt: `# Role
-You are a general-purpose coding agent for complex, multi-step tasks.
-You have full access to read, write, edit files, and execute commands.
-Do what has been asked; nothing more, nothing less.
-
-# Tool Usage
-- Use the read tool instead of cat/head/tail
-- Use the edit tool instead of sed/awk
-- Use the write tool instead of echo/heredoc
-- Use the find tool instead of bash find/ls for file search
-- Use the grep tool instead of bash grep/rg for content search
-- Make independent tool calls in parallel
-
-# File Operations
-- NEVER create files unless absolutely necessary
-- Prefer editing existing files over creating new ones
-- NEVER create documentation files unless explicitly requested
-
-# Git Safety
-- NEVER update git config
-- NEVER run destructive git commands (push --force, reset --hard, checkout ., restore ., clean -f, branch -D) without explicit request
-- NEVER skip hooks (--no-verify, --no-gpg-sign) unless explicitly asked
-- NEVER force push to main/master — warn the user if they request it
-- Always create NEW commits, never amend existing ones. When a pre-commit hook fails, the commit did NOT happen — so --amend would modify the PREVIOUS commit. Fix the issue, re-stage, and create a NEW commit
-- Stage specific files by name, not git add -A or git add .
-- NEVER commit changes unless the user explicitly asks
-- NEVER push unless the user explicitly asks
-- NEVER use git commands with the -i flag (like git rebase -i or git add -i) — they require interactive input
-- Do not use --no-edit with git rebase commands
-- Do not commit files that likely contain secrets (.env, credentials.json, etc); warn the user if they request it
-
-# Output
-- Use absolute file paths
-- Do not use emojis
-- Be concise but complete`,
-      promptMode: "replace",
+      systemPrompt: "",
+      promptMode: "append",
       inheritContext: false,
       runInBackground: false,
       isolated: false,

package/src/index.ts

@@ -30,6 +30,7 @@ import {
   formatMs,
   formatDuration,
   getDisplayName,
+  getPromptModeLabel,
   describeActivity,
   type AgentDetails,
   type AgentActivity,
@@ -120,20 +121,6 @@ function buildDetails(
   };
 }
 
-/** Resolve system prompt overrides from an agent config. */
-function resolveCustomPrompt(config: AgentConfig | undefined): {
-  systemPromptOverride?: string;
-  systemPromptAppend?: string;
-} {
-  if (!config?.systemPrompt) return {};
-  // Default agents use their systemPrompt via buildAgentPrompt in agent-runner,
-  // not via override/append. Only non-default agents use this path.
-  if (config.isDefault) return {};
-  if (config.promptMode === "append") return { systemPromptAppend: config.systemPrompt };
-  return { systemPromptOverride: config.systemPrompt };
-}
-
-
 export default function (pi: ExtensionAPI) {
   /** Reload agents from .pi/agents/*.md and merge with defaults (called on init and each Agent invocation). */
   const reloadCustomAgents = () => {
@@ -161,9 +148,11 @@ export default function (pi: ExtensionAPI) {
     agentActivity.delete(record.id);
     widget.markFinished(record.id);
 
+    const tokens = safeFormatTokens(record.session);
+    const toolStats = tokens ? `Tool uses: ${record.toolUses} | ${tokens}` : `Tool uses: ${record.toolUses}`;
     pi.sendUserMessage(
       `Background agent completed: ${displayName} (${record.description})\n` +
-      `Agent ID: ${record.id} | Status: ${status} | Tool uses: ${record.toolUses} | Duration: ${duration}\n\n` +
+      `Agent ID: ${record.id} | Status: ${status} | ${toolStats} | Duration: ${duration}\n\n` +
       resultPreview,
       { deliverAs: "followUp" },
     );
@@ -180,7 +169,9 @@ export default function (pi: ExtensionAPI) {
         ? record.result.slice(0, 300) + "\n...(truncated)"
         : record.result
       : "No output.";
-    return `- ${displayName} (${record.description})\n  ID: ${record.id} | Status: ${status} | Tools: ${record.toolUses} | Duration: ${duration}\n  ${resultPreview}`;
+    const tokens = safeFormatTokens(record.session);
+    const toolStats = tokens ? `Tools: ${record.toolUses} | ${tokens}` : `Tools: ${record.toolUses}`;
+    return `- ${displayName} (${record.description})\n  ID: ${record.id} | Status: ${status} | ${toolStats} | Duration: ${duration}\n  ${resultPreview}`;
   }
 
   // ---- Group join manager ----
@@ -539,8 +530,6 @@ Guidelines:
       const runInBackground = params.run_in_background ?? customConfig?.runInBackground ?? false;
       const isolated = params.isolated ?? customConfig?.isolated ?? false;
 
-      const { systemPromptOverride, systemPromptAppend } = resolveCustomPrompt(customConfig);
-
       // Build display tags for non-default config
       const parentModelId = ctx.model?.id;
       const effectiveModelId = model?.id;
@@ -548,6 +537,8 @@ Guidelines:
         ? (model?.name ?? effectiveModelId).replace(/^Claude\s+/i, "").toLowerCase()
         : undefined;
       const agentTags: string[] = [];
+      const modeLabel = getPromptModeLabel(subagentType);
+      if (modeLabel) agentTags.push(modeLabel);
       if (thinking) agentTags.push(`thinking: ${thinking}`);
       if (isolated) agentTags.push("isolated");
       // Shared base fields for all AgentDetails in this call
@@ -589,8 +580,6 @@ Guidelines:
           isolated,
           inheritContext,
           thinkingLevel: thinking,
-          systemPromptOverride,
-          systemPromptAppend,
           isBackground: true,
           ...bgCallbacks,
         });
@@ -680,8 +669,6 @@ Guidelines:
         isolated,
         inheritContext,
         thinkingLevel: thinking,
-        systemPromptOverride,
-        systemPromptAppend,
         ...fgCallbacks,
       });
 
@@ -707,8 +694,10 @@ Guidelines:
       }
 
       const durationMs = (record.completedAt ?? Date.now()) - record.startedAt;
+      const statsParts = [`${record.toolUses} tool uses`];
+      if (tokenText) statsParts.push(tokenText);
       return textResult(
-        `${fallbackNote}Agent completed in ${formatMs(durationMs)} (${record.toolUses} tool uses)${getStatusNote(record.status)}.\n\n` +
+        `${fallbackNote}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${getStatusNote(record.status)}.\n\n` +
         (record.result ?? "No output."),
         details,
       );
@@ -750,10 +739,12 @@ Guidelines:
 
       const displayName = getDisplayName(record.type);
       const duration = formatDuration(record.startedAt, record.completedAt);
+      const tokens = safeFormatTokens(record.session);
+      const toolStats = tokens ? `Tool uses: ${record.toolUses} | ${tokens}` : `Tool uses: ${record.toolUses}`;
 
       let output =
         `Agent: ${record.id}\n` +
-        `Type: ${displayName} | Status: ${record.status} | Tool uses: ${record.toolUses} | Duration: ${duration}\n` +
+        `Type: ${displayName} | Status: ${record.status} | ${toolStats} | Duration: ${duration}\n` +
         `Description: ${record.description}\n\n`;
 
       if (record.status === "running") {
@@ -951,14 +942,44 @@ Guidelines:
       return;
     }
 
-    // Show as a selectable list for potential future actions
     const options = agents.map(a => {
       const dn = getDisplayName(a.type);
       const dur = formatDuration(a.startedAt, a.completedAt);
       return `${dn} (${a.description}) · ${a.toolUses} tools · ${a.status} · ${dur}`;
     });
 
-    await ctx.ui.select("Running agents", options);
+    const choice = await ctx.ui.select("Running agents", options);
+    if (!choice) return;
+
+    // Find the selected agent by matching the option index
+    const idx = options.indexOf(choice);
+    if (idx < 0) return;
+    const record = agents[idx];
+
+    await viewAgentConversation(ctx, record);
+    // Back-navigation: re-show the list
+    await showRunningAgents(ctx);
+  }
+
+  async function viewAgentConversation(ctx: ExtensionCommandContext, record: AgentRecord) {
+    if (!record.session) {
+      ctx.ui.notify(`Agent is ${record.status === "queued" ? "queued" : "expired"} — no session available.`, "info");
+      return;
+    }
+
+    const { ConversationViewer } = await import("./ui/conversation-viewer.js");
+    const session = record.session;
+    const activity = agentActivity.get(record.id);
+
+    await ctx.ui.custom<undefined>(
+      (tui, theme, _keybindings, done) => {
+        return new ConversationViewer(tui, session, record, activity, theme, done);
+      },
+      {
+        overlay: true,
+        overlayOptions: { anchor: "center", width: "90%" },
+      },
+    );
   }
 
   async function showAgentDetail(ctx: ExtensionCommandContext, name: string) {

package/src/prompts.ts

@@ -7,42 +7,57 @@ import type { AgentConfig, EnvInfo } from "./types.js";
 /**
  * Build the system prompt for an agent from its config.
  *
- * - "replace" mode: common header + config.systemPrompt
- * - "append" mode: common header + generic base + config.systemPrompt
+ * - "replace" mode: env header + config.systemPrompt (full control, no parent identity)
+ * - "append" mode: env header + parent system prompt + sub-agent context + config.systemPrompt
+ * - "append" with empty systemPrompt: pure parent clone
+ *
+ * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
  */
-export function buildAgentPrompt(config: AgentConfig, cwd: string, env: EnvInfo): string {
-  const commonHeader = `You are a pi coding agent sub-agent.
-You have been invoked to handle a specific task autonomously.
-
-# Environment
+export function buildAgentPrompt(
+  config: AgentConfig,
+  cwd: string,
+  env: EnvInfo,
+  parentSystemPrompt?: string,
+): string {
+  const envBlock = `# Environment
 Working directory: ${cwd}
 ${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
 Platform: ${env.platform}`;
 
   if (config.promptMode === "append") {
-    const genericBase = `
+    const identity = parentSystemPrompt || genericBase;
 
-# Role
-You are a general-purpose coding agent for complex, multi-step tasks.
-You have full access to read, write, edit files, and execute commands.
-Do what has been asked; nothing more, nothing less.
-
-# Tool Usage
+    const bridge = `<sub_agent_context>
+You are operating as a sub-agent invoked to handle a specific task.
 - Use the read tool instead of cat/head/tail
 - Use the edit tool instead of sed/awk
 - Use the write tool instead of echo/heredoc
 - Use the find tool instead of bash find/ls for file search
 - Use the grep tool instead of bash grep/rg for content search
 - Make independent tool calls in parallel
-
-# Output
 - Use absolute file paths
 - Do not use emojis
-- Be concise but complete`;
+- Be concise but complete
+</sub_agent_context>`;
 
-    return commonHeader + genericBase + "\n\n" + config.systemPrompt;
+    const customSection = config.systemPrompt?.trim()
+      ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
+      : "";
+
+    return envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection;
   }
 
-  // "replace" mode — header + the config's full system prompt
-  return commonHeader + "\n\n" + config.systemPrompt;
+  // "replace" mode — env header + the config's full system prompt
+  const replaceHeader = `You are a pi coding agent sub-agent.
+You have been invoked to handle a specific task autonomously.
+
+${envBlock}`;
+
+  return replaceHeader + "\n\n" + config.systemPrompt;
 }
+
+/** Fallback base prompt when parent system prompt is unavailable in append mode. */
+const genericBase = `# Role
+You are a general-purpose coding agent for complex, multi-step tasks.
+You have full access to read, write, edit files, and execute commands.
+Do what has been asked; nothing more, nothing less.`;

package/src/ui/agent-widget.ts

@@ -12,6 +12,9 @@ import { getConfig } from "../agent-types.js";
 
 // ---- Constants ----
 
+/** Maximum number of rendered lines before overflow collapse kicks in. */
+const MAX_WIDGET_LINES = 12;
+
 /** Braille spinner frames for animated running indicator. */
 export const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
@@ -77,11 +80,11 @@ export interface AgentDetails {
 
 // ---- Formatting helpers ----
 
-/** Format a token count as "33.8k tokens" or "1.2M tokens". */
+/** Format a token count compactly: "33.8k token", "1.2M token". */
 export function formatTokens(count: number): string {
-  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M tokens`;
-  if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k tokens`;
-  return `${count} tokens`;
+  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M token`;
+  if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k token`;
+  return `${count} token`;
 }
 
 /** Format milliseconds as human-readable duration. */
@@ -100,6 +103,12 @@ export function getDisplayName(type: SubagentType): string {
   return getConfig(type).displayName;
 }
 
+/** Short label for prompt mode: "twin" for append, nothing for replace (the default). */
+export function getPromptModeLabel(type: SubagentType): string | undefined {
+  const config = getConfig(type);
+  return config.promptMode === "append" ? "twin" : undefined;
+}
+
 /** Truncate text to a single line, max `len` chars. */
 function truncateLine(text: string, len = 60): string {
   const line = text.split("\n").find(l => l.trim())?.trim() ?? "";
@@ -193,6 +202,7 @@ export class AgentWidget {
   /** Render a finished agent line. */
   private renderFinishedLine(a: { type: SubagentType; status: string; description: string; toolUses: number; startedAt: number; completedAt?: number; error?: string }, theme: Theme): string {
     const name = getDisplayName(a.type);
+    const modeLabel = getPromptModeLabel(a.type);
     const duration = formatMs((a.completedAt ?? Date.now()) - a.startedAt);
 
     let icon: string;
@@ -220,7 +230,8 @@ export class AgentWidget {
     if (a.toolUses > 0) parts.push(`${a.toolUses} tool use${a.toolUses === 1 ? "" : "s"}`);
     parts.push(duration);
 
-    return `${icon} ${theme.fg("dim", name)}  ${theme.fg("dim", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", parts.join(" · "))}${statusText}`;
+    const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
+    return `${icon} ${theme.fg("dim", name)}${modeTag}  ${theme.fg("dim", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", parts.join(" · "))}${statusText}`;
   }
 
   /** Force an immediate widget update. */
@@ -268,23 +279,20 @@ export class AgentWidget {
       const truncate = (line: string) => truncateToWidth(line, w);
       const headingColor = hasActive ? "accent" : "dim";
       const headingIcon = hasActive ? "●" : "○";
-      const lines: string[] = [truncate(theme.fg(headingColor, headingIcon) + " " + theme.fg(headingColor, "Agents"))];
 
-      // --- Finished agents (shown first, dimmed) ---
-      for (let i = 0; i < finished.length; i++) {
-        const a = finished[i];
-        const isLast = !hasActive && i === finished.length - 1;
-        const connector = isLast ? "└─" : "├─";
-        lines.push(truncate(theme.fg("dim", connector) + " " + this.renderFinishedLine(a, theme)));
+      // Build sections separately for overflow-aware assembly.
+      // Each running agent = 2 lines (header + activity), finished = 1 line, queued = 1 line.
+
+      const finishedLines: string[] = [];
+      for (const a of finished) {
+        finishedLines.push(truncate(theme.fg("dim", "├─") + " " + this.renderFinishedLine(a, theme)));
       }
 
-      // --- Running agents ---
-      const isLastSection = queued.length === 0;
-      for (let i = 0; i < running.length; i++) {
-        const a = running[i];
-        const isLast = isLastSection && i === running.length - 1;
-        const connector = isLast ? "└─" : "├─";
+      const runningLines: string[][] = []; // each entry is [header, activity]
+      for (const a of running) {
         const name = getDisplayName(a.type);
+        const modeLabel = getPromptModeLabel(a.type);
+        const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
         const elapsed = formatMs(Date.now() - a.startedAt);
 
         const bg = this.agentActivity.get(a.id);
@@ -302,14 +310,82 @@ export class AgentWidget {
 
         const activity = bg ? describeActivity(bg.activeTools, bg.responseText) : "thinking…";
 
-        lines.push(truncate(theme.fg("dim", connector) + ` ${theme.fg("accent", frame)} ${theme.bold(name)}  ${theme.fg("muted", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", statsText)}`));
-        const indent = isLast ? "   " : "│  ";
-        lines.push(truncate(theme.fg("dim", indent) + theme.fg("dim", `  ⎿  ${activity}`)));
+        runningLines.push([
+          truncate(theme.fg("dim", "├─") + ` ${theme.fg("accent", frame)} ${theme.bold(name)}${modeTag}  ${theme.fg("muted", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", statsText)}`),
+          truncate(theme.fg("dim", "│  ") + theme.fg("dim", `  ⎿  ${activity}`)),
+        ]);
       }
 
-      // --- Queued agents (collapsed) ---
-      if (queued.length > 0) {
-        lines.push(truncate(theme.fg("dim", "└─") + ` ${theme.fg("muted", "◦")} ${theme.fg("dim", `${queued.length} queued`)}`));
+      const queuedLine = queued.length > 0
+        ? truncate(theme.fg("dim", "├─") + ` ${theme.fg("muted", "◦")} ${theme.fg("dim", `${queued.length} queued`)}`)
+        : undefined;
+
+      // Assemble with overflow cap (heading + overflow indicator = 2 reserved lines).
+      const maxBody = MAX_WIDGET_LINES - 1; // heading takes 1 line
+      const totalBody = finishedLines.length + runningLines.length * 2 + (queuedLine ? 1 : 0);
+
+      const lines: string[] = [truncate(theme.fg(headingColor, headingIcon) + " " + theme.fg(headingColor, "Agents"))];
+
+      if (totalBody <= maxBody) {
+        // Everything fits — add all lines and fix up connectors for the last item.
+        lines.push(...finishedLines);
+        for (const pair of runningLines) lines.push(...pair);
+        if (queuedLine) lines.push(queuedLine);
+
+        // Fix last connector: swap ├─ → └─ and │ → space for activity lines.
+        if (lines.length > 1) {
+          const last = lines.length - 1;
+          lines[last] = lines[last].replace("├─", "└─");
+          // If last item is a running agent activity line, fix indent of that line
+          // and fix the header line above it.
+          if (runningLines.length > 0 && !queuedLine) {
+            // The last two lines are the last running agent's header + activity.
+            if (last >= 2) {
+              lines[last - 1] = lines[last - 1].replace("├─", "└─");
+              lines[last] = lines[last].replace("│  ", "   ");
+            }
+          }
+        }
+      } else {
+        // Overflow — prioritize: running > queued > finished.
+        // Reserve 1 line for overflow indicator.
+        let budget = maxBody - 1;
+        let hiddenRunning = 0;
+        let hiddenFinished = 0;
+
+        // 1. Running agents (2 lines each)
+        for (const pair of runningLines) {
+          if (budget >= 2) {
+            lines.push(...pair);
+            budget -= 2;
+          } else {
+            hiddenRunning++;
+          }
+        }
+
+        // 2. Queued line
+        if (queuedLine && budget >= 1) {
+          lines.push(queuedLine);
+          budget--;
+        }
+
+        // 3. Finished agents
+        for (const fl of finishedLines) {
+          if (budget >= 1) {
+            lines.push(fl);
+            budget--;
+          } else {
+            hiddenFinished++;
+          }
+        }
+
+        // Overflow summary
+        const overflowParts: string[] = [];
+        if (hiddenRunning > 0) overflowParts.push(`${hiddenRunning} running`);
+        if (hiddenFinished > 0) overflowParts.push(`${hiddenFinished} finished`);
+        const overflowText = overflowParts.join(", ");
+        lines.push(truncate(theme.fg("dim", "└─") + ` ${theme.fg("dim", `+${hiddenRunning + hiddenFinished} more (${overflowText})`)}`)
+        );
       }
 
       return { render: () => lines, invalidate: () => {} };

package/src/ui/conversation-viewer.ts

@@ -0,0 +1,243 @@
+/**
+ * conversation-viewer.ts — Live conversation overlay for viewing agent sessions.
+ *
+ * Displays a scrollable, live-updating view of an agent's conversation.
+ * Subscribes to session events for real-time streaming updates.
+ */
+
+import { matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component, type TUI } from "@mariozechner/pi-tui";
+import type { AgentSession } from "@mariozechner/pi-coding-agent";
+import type { Theme } from "./agent-widget.js";
+import { formatTokens, formatDuration, getDisplayName, getPromptModeLabel, describeActivity, type AgentActivity } from "./agent-widget.js";
+import type { AgentRecord } from "../types.js";
+import { extractText } from "../context.js";
+
+/** Lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
+const CHROME_LINES = 6;
+const MIN_VIEWPORT = 3;
+
+export class ConversationViewer implements Component {
+  private scrollOffset = 0;
+  private autoScroll = true;
+  private unsubscribe: (() => void) | undefined;
+  private lastInnerW = 0;
+  private closed = false;
+
+  constructor(
+    private tui: TUI,
+    private session: AgentSession,
+    private record: AgentRecord,
+    private activity: AgentActivity | undefined,
+    private theme: Theme,
+    private done: (result: undefined) => void,
+  ) {
+    this.unsubscribe = session.subscribe(() => {
+      if (this.closed) return;
+      this.tui.requestRender();
+    });
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape") || matchesKey(data, "q")) {
+      this.closed = true;
+      this.done(undefined);
+      return;
+    }
+
+    const totalLines = this.buildContentLines(this.lastInnerW).length;
+    const viewportHeight = this.viewportHeight();
+    const maxScroll = Math.max(0, totalLines - viewportHeight);
+
+    if (matchesKey(data, "up") || matchesKey(data, "k")) {
+      this.scrollOffset = Math.max(0, this.scrollOffset - 1);
+      this.autoScroll = this.scrollOffset >= maxScroll;
+    } else if (matchesKey(data, "down") || matchesKey(data, "j")) {
+      this.scrollOffset = Math.min(maxScroll, this.scrollOffset + 1);
+      this.autoScroll = this.scrollOffset >= maxScroll;
+    } else if (matchesKey(data, "pageUp")) {
+      this.scrollOffset = Math.max(0, this.scrollOffset - viewportHeight);
+      this.autoScroll = false;
+    } else if (matchesKey(data, "pageDown")) {
+      this.scrollOffset = Math.min(maxScroll, this.scrollOffset + viewportHeight);
+      this.autoScroll = this.scrollOffset >= maxScroll;
+    } else if (matchesKey(data, "home")) {
+      this.scrollOffset = 0;
+      this.autoScroll = false;
+    } else if (matchesKey(data, "end")) {
+      this.scrollOffset = maxScroll;
+      this.autoScroll = true;
+    }
+  }
+
+  render(width: number): string[] {
+    if (width < 6) return []; // too narrow for any meaningful rendering
+    const th = this.theme;
+    const innerW = width - 4; // border + padding
+    this.lastInnerW = innerW;
+    const lines: string[] = [];
+
+    const pad = (s: string, len: number) => {
+      const vis = visibleWidth(s);
+      return s + " ".repeat(Math.max(0, len - vis));
+    };
+    const row = (content: string) =>
+      th.fg("border", "│") + " " + truncateToWidth(pad(content, innerW), innerW) + " " + th.fg("border", "│");
+    const hrTop = th.fg("border", `╭${"─".repeat(width - 2)}╮`);
+    const hrBot = th.fg("border", `╰${"─".repeat(width - 2)}╯`);
+    const hrMid = row(th.fg("dim", "─".repeat(innerW)));
+
+    // Header
+    lines.push(hrTop);
+    const name = getDisplayName(this.record.type);
+    const modeLabel = getPromptModeLabel(this.record.type);
+    const modeTag = modeLabel ? ` ${th.fg("dim", `(${modeLabel})`)}` : "";
+    const statusIcon = this.record.status === "running"
+      ? th.fg("accent", "●")
+      : this.record.status === "completed"
+        ? th.fg("success", "✓")
+        : this.record.status === "error"
+          ? th.fg("error", "✗")
+          : th.fg("dim", "○");
+    const duration = formatDuration(this.record.startedAt, this.record.completedAt);
+
+    const headerParts: string[] = [duration];
+    const toolUses = this.activity?.toolUses ?? this.record.toolUses;
+    if (toolUses > 0) headerParts.unshift(`${toolUses} tool${toolUses === 1 ? "" : "s"}`);
+    if (this.activity?.session) {
+      try {
+        const tokens = this.activity.session.getSessionStats().tokens.total;
+        if (tokens > 0) headerParts.push(formatTokens(tokens));
+      } catch { /* */ }
+    }
+
+    lines.push(row(
+      `${statusIcon} ${th.bold(name)}${modeTag}  ${th.fg("muted", this.record.description)} ${th.fg("dim", "·")} ${th.fg("dim", headerParts.join(" · "))}`,
+    ));
+    lines.push(hrMid);
+
+    // Content area — rebuild every render (live data, no cache needed)
+    const contentLines = this.buildContentLines(innerW);
+    const viewportHeight = this.viewportHeight();
+    const maxScroll = Math.max(0, contentLines.length - viewportHeight);
+
+    if (this.autoScroll) {
+      this.scrollOffset = maxScroll;
+    }
+
+    const visibleStart = Math.min(this.scrollOffset, maxScroll);
+    const visible = contentLines.slice(visibleStart, visibleStart + viewportHeight);
+
+    for (let i = 0; i < viewportHeight; i++) {
+      lines.push(row(visible[i] ?? ""));
+    }
+
+    // Footer
+    lines.push(hrMid);
+    const scrollPct = contentLines.length <= viewportHeight
+      ? "100%"
+      : `${Math.round(((visibleStart + viewportHeight) / contentLines.length) * 100)}%`;
+    const footerLeft = th.fg("dim", `${contentLines.length} lines · ${scrollPct}`);
+    const footerRight = th.fg("dim", "↑↓ scroll · PgUp/PgDn · Esc close");
+    const footerGap = Math.max(1, innerW - visibleWidth(footerLeft) - visibleWidth(footerRight));
+    lines.push(row(footerLeft + " ".repeat(footerGap) + footerRight));
+    lines.push(hrBot);
+
+    return lines;
+  }
+
+  invalidate(): void { /* no cached state to clear */ }
+
+  dispose(): void {
+    this.closed = true;
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = undefined;
+    }
+  }
+
+  // ---- Private ----
+
+  private viewportHeight(): number {
+    return Math.max(MIN_VIEWPORT, this.tui.terminal.rows - CHROME_LINES);
+  }
+
+  private buildContentLines(width: number): string[] {
+    if (width <= 0) return [];
+
+    const th = this.theme;
+    const messages = this.session.messages;
+    const lines: string[] = [];
+
+    if (messages.length === 0) {
+      lines.push(th.fg("dim", "(waiting for first message...)"));
+      return lines;
+    }
+
+    let needsSeparator = false;
+    for (const msg of messages) {
+      if (msg.role === "user") {
+        const text = typeof msg.content === "string"
+          ? msg.content
+          : extractText(msg.content);
+        if (!text.trim()) continue;
+        if (needsSeparator) lines.push(th.fg("dim", "───"));
+        lines.push(th.fg("accent", "[User]"));
+        for (const line of wrapTextWithAnsi(text.trim(), width)) {
+          lines.push(line);
+        }
+      } else if (msg.role === "assistant") {
+        const textParts: string[] = [];
+        const toolCalls: string[] = [];
+        for (const c of msg.content) {
+          if (c.type === "text" && c.text) textParts.push(c.text);
+          else if (c.type === "toolCall") {
+            toolCalls.push((c as any).toolName ?? "unknown");
+          }
+        }
+        if (needsSeparator) lines.push(th.fg("dim", "───"));
+        lines.push(th.bold("[Assistant]"));
+        if (textParts.length > 0) {
+          for (const line of wrapTextWithAnsi(textParts.join("\n").trim(), width)) {
+            lines.push(line);
+          }
+        }
+        for (const name of toolCalls) {
+          lines.push(truncateToWidth(th.fg("muted", `  [Tool: ${name}]`), width));
+        }
+      } else if (msg.role === "toolResult") {
+        const text = extractText(msg.content);
+        const truncated = text.length > 500 ? text.slice(0, 500) + "... (truncated)" : text;
+        if (!truncated.trim()) continue;
+        if (needsSeparator) lines.push(th.fg("dim", "───"));
+        lines.push(th.fg("dim", "[Result]"));
+        for (const line of wrapTextWithAnsi(truncated.trim(), width)) {
+          lines.push(th.fg("dim", line));
+        }
+      } else if ((msg as any).role === "bashExecution") {
+        const bash = msg as any;
+        if (needsSeparator) lines.push(th.fg("dim", "───"));
+        lines.push(truncateToWidth(th.fg("muted", `  $ ${bash.command}`), width));
+        if (bash.output?.trim()) {
+          const out = bash.output.length > 500
+            ? bash.output.slice(0, 500) + "... (truncated)"
+            : bash.output;
+          for (const line of wrapTextWithAnsi(out.trim(), width)) {
+            lines.push(th.fg("dim", line));
+          }
+        }
+      } else {
+        continue;
+      }
+      needsSeparator = true;
+    }
+
+    // Streaming indicator for running agents
+    if (this.record.status === "running" && this.activity) {
+      const act = describeActivity(this.activity.activeTools, this.activity.responseText);
+      lines.push("");
+      lines.push(truncateToWidth(th.fg("accent", "▍ ") + th.fg("dim", act), width));
+    }
+
+    return lines;
+  }
+}