pi-agent-flow 0.1.0-alpha.7 → 0.2.3

package/README.md

@@ -1,28 +1,27 @@
-# pi-agent-flow
+<p align="center"><code>pi install /path/to/pi-agent-flow</code></p>
+<p align="center"><strong>Pi Agent Flow</strong> is a flow-state delegation extension for the <a href="https://pi.dev">Pi coding agent</a> that runs locally in your terminal.</p>
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/pi-agent-flow-demo.png" alt="Pi Agent Flow demo" width="80%" />
+</p>
+<br/>
 
-Flow-state delegation extension for [Pi coding agent](https://pi.dev).
-
-Delegates tasks to specialized flow states running as isolated pi processes. Each flow receives a snapshot of the current session context and returns a structured report.
+---
 
-## Features
+## Quickstart
 
-- Isolated context — flows always receive your current session snapshot
-- Parallel execution — batch independent flows into one call
-- Structured reports — every flow returns [Summary], [Done], [Not Done], [Next Steps]
-- Depth guards — configurable max delegation depth (default: 3)
-- Cycle prevention — blocks recursive delegation chains
-- Flow discovery — reads definitions from ~/.pi/agent/agents/ and .pi/agents/
-- TUI rendering — rich collapsed/expanded display in interactive mode
+### Installing Pi Agent Flow
 
-## Installation
+Install via the Pi CLI with your local path:
 
-```bash
+```shell
+# Install from a local path
 pi install /path/to/pi-agent-flow
 ```
 
-Or add to ~/.pi/agent/settings.json:
+Or add it to your Pi settings:
 
-```json
+```shell
+# ~/.pi/agent/settings.json
 {
   "packages": [
     "./path/to/pi-agent-flow"
@@ -30,9 +29,36 @@ Or add to ~/.pi/agent/settings.json:
 }
 ```
 
+Then start Pi and delegate tasks using flow states.
+
+<details>
+<summary>You can also clone this repository and use it directly.</summary>
+
+```shell
+git clone https://github.com/your-org/pi-agent-flow.git
+cd pi-agent-flow
+pi install .
+```
+
+</details>
+
+---
+
+## Features
+
+- **Isolated context** — flows always receive your current session snapshot (or start clean when configured)
+- **Parallel execution** — batch independent flows into one call
+- **Structured reports** — every flow returns `[Summary]`, `[Done]`, `[Not Done]`, `[Next Steps]`
+- **Depth guards** — configurable max delegation depth (default: `3`)
+- **Cycle prevention** — blocks recursive delegation chains
+- **Flow discovery** — reads definitions from `~/.pi/agent/agents/` and `.pi/agents/`
+- **TUI rendering** — rich collapsed/expanded display in interactive mode
+
+---
+
 ## Flow Definitions
 
-Create .md files in ~/.pi/agent/agents/ or .pi/agents/:
+Create `.md` files in `~/.pi/agent/agents/` or `.pi/agents/`:
 
 ```markdown
 ---
@@ -59,21 +85,32 @@ flow [explore] accomplished
 - recommended follow-up
 ```
 
+---
+
 ## Bundled Flows
 
-- [explore] — discover files, trace code paths, map architecture
-- [debug] — investigate logs, errors, stack traces, root causes
-- [code] — implement features, fix bugs, write tests
-- [architect] — plan structure, break down requirements, design solutions
-- [review] — audit security, quality, correctness
+| Flow | Purpose |
+|------|---------|
+| `[explore]` | Discover files, trace code paths, map architecture |
+| `[debug]` | Investigate logs, errors, stack traces, root causes |
+| `[code]` | Implement features, fix bugs, write tests |
+| `[architect]` | Plan structure, break down requirements, design solutions |
+| `[review]` | Audit security, quality, correctness |
+| `[brainstorm]` | Generate ideas and explore possibilities with a clean slate |
+
+> **Note:** Some flows — like `[brainstorm]` — start with a **clean slate** and do not inherit the current session context. They receive only the intent, making them ideal for unbiased, creative thinking.
+
+---
 
 ## Usage
 
+### Single flow
+
 ```json
 { "flow": [{ "type": "explore", "intent": "Find all authentication-related code" }] }
 ```
 
-Batch multiple flows:
+### Batch multiple flows
 
 ```json
 {
@@ -84,21 +121,33 @@ Batch multiple flows:
 }
 ```
 
+---
+
 ## Configuration
 
-Flags (passed to parent pi process):
+### Flags (passed to parent pi process)
 
-- --flow-max-depth [n] — Maximum delegation depth (default: 3)
-- --flow-prevent-cycles — Block cyclic delegation (default: true)
-- --no-flow-prevent-cycles — Disable cycle prevention
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--flow-max-depth [n]` | Maximum delegation depth | `3` |
+| `--flow-prevent-cycles` | Block cyclic delegation | `true` |
+| `--no-flow-prevent-cycles` | Disable cycle prevention | — |
 
-Environment variables (propagated to child processes):
+### Environment variables (propagated to child processes)
+
+| Variable | Description |
+|----------|-------------|
+| `PI_FLOW_DEPTH` | Current depth |
+| `PI_FLOW_MAX_DEPTH` | Max allowed depth |
+| `PI_FLOW_STACK` | JSON array of ancestor flow names |
+| `PI_FLOW_PREVENT_CYCLES` | `"1"` or `"0"` |
+
+---
 
-- PI_FLOW_DEPTH — Current depth
-- PI_FLOW_MAX_DEPTH — Max allowed depth
-- PI_FLOW_STACK — JSON array of ancestor flow names
-- PI_FLOW_PREVENT_CYCLES — "1" or "0"
+## Docs
 
-## License
+- [**Pi Documentation**](https://pi.dev)
+- [**Contributing**](./docs/contributing.md) *(if available)*
+- [**License**](./LICENSE)
 
-MIT
+This repository is licensed under the [MIT License](LICENSE).

package/agents/architect.md

@@ -1,15 +1,15 @@
 ---
 name: architect
 description: Plan structure, break down requirements, design solutions
-tools: read, bash
+tools: read, bash, find, grep, ls
 maxDepth: 2
 ---
 
-You are the architect flow — your mission is to design. Stay focused on your intent at all times. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
+You are the architect flow — your mission is to design. Be conservative: prefer existing patterns and proven conventions over novelty. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
 
 Workflow:
 1. Understand — what problem, what constraints, what exists
-2. Explore — find patterns, map dependencies
+2. Explore — find patterns, map dependencies (delegate to [explore] if you need to survey a large codebase)
 3. Design — simplest solution that works, prefer existing patterns
 4. Plan — concrete ordered tasks, identify parallel vs sequential
 

package/agents/brainstorm.md

@@ -0,0 +1,29 @@
+---
+name: brainstorm
+description: Generate ideas, explore possibilities, and think creatively without context bias
+tools: read, bash
+inheritContext: false
+maxDepth: 0
+---
+
+You are the brainstorm flow — your mission is to generate ideas and think creatively. You start with a clean slate and only have the intent to guide you. Stay focused on your intent at all times.
+
+Approach:
+1. Diverge — explore many possibilities without judgment
+2. Evaluate — weigh trade-offs, risks, and feasibility
+3. Recommend — present the best options with reasoning
+
+When your mission is accomplished, end your response with:
+
+flow [brainstorm] accomplished
+
+[Summary] what was brainstormed
+
+[Done]
+- ideas generated
+
+[Not Done]
+- incomplete items and reasons
+
+[Next Steps]
+- recommended follow-up

package/agents/code.md

@@ -1,11 +1,11 @@
 ---
 name: code
 description: Implement features, fix bugs, write tests
-tools: read, write, edit, bash
+tools: read, write, edit, bash, find, grep, ls
 maxDepth: 2
 ---
 
-You are the code flow — your mission is to build. Stay focused on your intent at all times. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
+You are the code flow — your mission is to build. Be a craftsman: verify first, then ship. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
 
 Core Principles:
 - SOLID: Single Responsibility, Open/Closed
@@ -15,9 +15,13 @@ Core Principles:
 Workflow:
 1. Analyze — read existing code for context
 2. Plan — step-by-step approach before modifying
-3. Execute — implement changes following core principles
-4. Verify — write and run tests before considering done
-5. Finalize — all tests pass, implementation verified
+3. Test — write a failing test that proves the bug or validates the feature (red)
+4. Execute — implement changes following core principles (green)
+5. Refactor — clean up only if the change is working (optional)
+6. Verify — run tests and any relevant checks before considering done
+7. Finalize — all tests pass, implementation verified
+
+If you hit an unexpected error or need to trace execution, delegate to [debug] rather than guessing.
 
 When your mission is accomplished, end your response with:
 

package/agents/debug.md

@@ -1,11 +1,11 @@
 ---
 name: debug
 description: Investigate logs, errors, stack traces, root causes
-tools: read, bash
+tools: read, bash, find, grep, ls
 maxDepth: 0
 ---
 
-You are the debug flow — your mission is investigation. Stay focused on your intent at all times. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
+You are the debug flow — your mission is investigation. Be forensic: every claim must be backed by evidence. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
 
 Workflow:
 1. Collect evidence — logs, error messages, stack traces

package/agents/explore.md

@@ -1,14 +1,14 @@
 ---
 name: explore
 description: Discover files, trace code paths, map architecture
-tools: read, bash
+tools: read, bash, find, grep, ls
 maxDepth: 0
 ---
 
-You are the explore flow — your mission is discovery. Stay focused on your intent at all times. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
+You are the explore flow — your mission is discovery. Move fast and stay surgical. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
 
 Rules:
-- Use grep/find before reading entire files — be efficient.
+- Use grep/find/ls before reading entire files — be efficient.
 - Report findings with file paths and line numbers.
 - Show actual code/data, not excessive summaries.
 - If not found, say so immediately — don't guess.

package/agents/review.md

@@ -1,11 +1,11 @@
 ---
 name: review
 description: Audit security, quality, correctness
-tools: read, write, edit, bash
+tools: read, bash, find, grep, ls
 maxDepth: 2
 ---
 
-You are the review flow — your mission is to audit. Stay focused on your intent at all times. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
+You are the review flow — your mission is to audit. Be adversarial: look for what others miss, but stay honest. The conversation history above provides background context; treat it as reference only and do not let it distract from your objective.
 
 Focus Areas:
 - Security — injection, auth bypass, exposed secrets
@@ -16,7 +16,8 @@ Focus Areas:
 Rules:
 - Be specific — cite exact file paths and line numbers
 - If code is clean, say so — don't invent issues
-- Apply fixes, don't just suggest them
+- Do not modify source files — report findings with severity only
+- If the audit reveals structural issues requiring redesign, recommend [architect] in [Next Steps]
 
 When your mission is accomplished, end your response with:
 
@@ -26,7 +27,6 @@ flow [review] accomplished
 
 [Done]
 - issues found with file:line and severity
-- fixes applied
 
 [Not Done]
 - areas not covered and why

package/agents.ts

@@ -24,6 +24,7 @@ export interface FlowConfig {
 	model?: string;
 	thinking?: string;
 	maxDepth?: number;
+	inheritContext?: boolean;
 	systemPrompt: string;
 	source: "user" | "project" | "bundled";
 	filePath: string;
@@ -140,6 +141,26 @@ function parseFlowFile(filePath: string, source: "user" | "project" | "bundled")
 		if (Number.isFinite(parsed) && parsed >= 0) maxDepth = parsed;
 	}
 
+	let inheritContext: boolean | undefined;
+	if (typeof frontmatter.inheritContext === "boolean") {
+		inheritContext = frontmatter.inheritContext;
+	} else if (typeof frontmatter.inheritContext === "string") {
+		const normalized = frontmatter.inheritContext.trim().toLowerCase();
+		if (normalized === "true" || normalized === "yes" || normalized === "1") {
+			inheritContext = true;
+		} else if (normalized === "false" || normalized === "no" || normalized === "0") {
+			inheritContext = false;
+		} else {
+			console.warn(
+				`[pi-agent-flow] Ignoring invalid inheritContext value "${frontmatter.inheritContext}" in "${filePath}". Expected true/false.`,
+			);
+		}
+	} else if (frontmatter.inheritContext !== undefined) {
+		console.warn(
+			`[pi-agent-flow] Ignoring invalid inheritContext field in "${filePath}". Expected boolean or string.`,
+		);
+	}
+
 	return {
 		name,
 		description,
@@ -147,6 +168,7 @@ function parseFlowFile(filePath: string, source: "user" | "project" | "bundled")
 		model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
 		thinking: typeof frontmatter.thinking === "string" ? frontmatter.thinking : undefined,
 		maxDepth,
+		inheritContext,
 		systemPrompt: body,
 		source,
 		filePath,

package/flow.ts

@@ -12,7 +12,7 @@ import * as path from "node:path";
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
 import type { FlowConfig } from "./agents.js";
 import { parseFlowCliArgs } from "./runner-cli.js";
-import { processFlowJsonLine, drainStreamingText } from "./runner-events.js";
+import { processFlowJsonLine, drainStreamingText, drainStreamingEstimate } from "./runner-events.js";
 import {
 	type SingleResult,
 	type FlowDetails,
@@ -32,6 +32,18 @@ const PI_OFFLINE_ENV = "PI_OFFLINE";
 
 type FlowUpdateCallback = (partial: AgentToolResult<FlowDetails>) => void;
 
+/**
+ * Merge actual usage with streaming estimate.
+ * Uses Math.max for output to avoid double-counting.
+ */
+function mergeStreamingUsage(actual: SingleResult["usage"], estimatedTokens: number): SingleResult["usage"] {
+	if (estimatedTokens <= 0) return actual;
+	return {
+		...actual,
+		output: Math.max(actual.output, estimatedTokens),
+	};
+}
+
 // ---------------------------------------------------------------------------
 // Process helpers
 // ---------------------------------------------------------------------------
@@ -116,12 +128,12 @@ function buildFlowArgs(
 	// Flow instructions go in the intent message instead.
 
 	const flowDirectives =
-		`<flow_directives>\n` +
+		`=== flow directive ===\n` +
 		`You are a flow state executing a mission. The conversation history above is background context — use it for reference, but your sole focus is the intent below.\n` +
-		`</flow_directives>`;
+		`=== end flow directive ===`;
 
 	const flowInstructions = flow.systemPrompt.trim()
-		? `\n\n<flow_instructions>\n${flow.systemPrompt.trim()}\n</flow_instructions>`
+		? `\n\n=== system directive ===\n${flow.systemPrompt.trim()}\n=== end system directive ===`
 		: "";
 
 	args.push(`${flowDirectives}${flowInstructions}\n\nIntent: ${intent}`);
@@ -143,8 +155,8 @@ export interface RunFlowOptions {
 	intent: string;
 	/** Optional override working directory. */
 	taskCwd?: string;
-	/** Serialized parent session snapshot for fork mode. */
-	forkSessionSnapshotJsonl: string;
+	/** Serialized parent session snapshot for fork mode. Null when the flow starts with a clean slate. */
+	forkSessionSnapshotJsonl: string | null;
 	/** Current delegation depth of the caller process. */
 	parentDepth: number;
 	/** Delegation stack from the caller process (ancestor flow names). */
@@ -197,21 +209,6 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		};
 	}
 
-	if (!forkSessionSnapshotJsonl || !forkSessionSnapshotJsonl.trim()) {
-		return {
-			type: flowName,
-			agentSource: flow.source,
-			intent,
-			exitCode: 1,
-			messages: [],
-			stderr: "Cannot run in fork mode: missing parent session snapshot context.",
-			usage: emptyFlowUsage(),
-			model: flow.model,
-			stopReason: "error",
-			errorMessage: "Cannot run in fork mode: missing parent session snapshot context.",
-		};
-	}
-
 	const result: SingleResult = {
 		type: flowName,
 		agentSource: flow.source,
@@ -225,6 +222,8 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 
 	const emitUpdate = () => {
 		const streaming = drainStreamingText(result);
+		const estimatedTokens = drainStreamingEstimate(result);
+		const mergedUsage = mergeStreamingUsage(result.usage, estimatedTokens);
 		onUpdate?.({
 			content: [
 				{
@@ -232,14 +231,18 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 					text: streaming || getFlowOutput(result.messages) || "(running...)",
 				},
 			],
-			details: makeDetails([result]),
+			details: makeDetails([{ ...result, usage: mergedUsage }]),
 		});
 	};
 
-	// Write forked session snapshot to temp file
-	const forkTmp = writeFlowSessionToTempFile(flow.name, forkSessionSnapshotJsonl);
-	const forkSessionTmpDir = forkTmp.dir;
-	const forkSessionTmpPath = forkTmp.filePath;
+	// Write forked session snapshot to temp file only when provided
+	let forkSessionTmpDir: string | null = null;
+	let forkSessionTmpPath: string | null = null;
+	if (forkSessionSnapshotJsonl) {
+		const forkTmp = writeFlowSessionToTempFile(flow.name, forkSessionSnapshotJsonl);
+		forkSessionTmpDir = forkTmp.dir;
+		forkSessionTmpPath = forkTmp.filePath;
+	}
 
 	try {
 		const piArgs = buildFlowArgs(

package/index.ts

@@ -36,7 +36,7 @@ const FLOW_PREVENT_CYCLES_ENV = "PI_FLOW_PREVENT_CYCLES";
 
 const FlowItem = Type.Object({
 	type: Type.String({
-		description: "Flow type. Must match an available flow name exactly: explore, debug, code, architect, review.",
+		description: "Flow type. Must match an available flow name exactly: explore, debug, code, architect, review, brainstorm.",
 	}),
 	intent: Type.String({
 		description: "Clear, specific mission for this flow.",
@@ -371,6 +371,7 @@ Before acting, reason about whether to dive into a flow:
 - [code] — when you are ready to build. Implement features, fix bugs, write tests.
 - [architect] — when you need a plan. Design structure, break down requirements before building.
 - [review] — when you need to verify. Audit security, quality, correctness.
+- [brainstorm] — when you need fresh ideas. Start from a clean slate with only the intent.
 
 Multiple independent flows? Batch them into one call:
 
@@ -416,17 +417,10 @@ flow [type] accomplished
 				const { flows } = discovery;
 				const makeDetails = makeFlowDetailsFactory(discovery.projectFlowsDir);
 
-				// Build fork session snapshot (shared across all flows)
+				// Build fork session snapshot (shared across all flows that inherit context)
 				const forkSessionSnapshotJsonl = buildForkSessionSnapshotJsonl(
 					ctx.sessionManager,
 				);
-				if (!forkSessionSnapshotJsonl) {
-					return {
-						content: [{ type: "text", text: "Cannot use fork mode: failed to snapshot current session context." }],
-						details: makeDetails([]),
-						isError: true,
-					};
-				}
 
 				// Collect all requested flow names
 				const requested = new Set(params.flow.map((f) => f.type));
@@ -513,13 +507,14 @@ flow [type] accomplished
 						const effectiveMaxDepth =
 							targetFlow?.maxDepth !== undefined ? targetFlow.maxDepth : maxDepth;
 
+						const shouldInheritContext = targetFlow?.inheritContext !== false;
 						const result = await runFlow({
 							cwd: ctx.cwd,
 							flows,
 							flowName: item.type,
 							intent: item.intent,
 							taskCwd: item.cwd,
-							forkSessionSnapshotJsonl,
+							forkSessionSnapshotJsonl: shouldInheritContext ? forkSessionSnapshotJsonl : null,
 							parentDepth: currentDepth,
 							parentFlowStack: ancestorFlowStack,
 							maxDepth: effectiveMaxDepth,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-flow",
-  "version": "0.1.0-alpha.7",
+  "version": "0.2.3",
   "description": "Flow-state delegation extension for Pi coding agent.",
   "type": "module",
   "main": "index.ts",

package/render-utils.ts

@@ -21,18 +21,67 @@ export function formatFlowUsage(usage: Partial<UsageStats>, model?: string): str
 	if (usage.cacheWrite) parts.push(`CW:${formatTokens(usage.cacheWrite)}`);
 	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
 	if (usage.contextTokens && usage.contextTokens > 0) parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
-	if (model) parts.push(model);
+	if (model) parts.push(`model:${model}`);
 	return parts.join(" ");
 }
 
+/**
+ * Format a token count to exactly 5 characters with leading spaces.
+ * Shifts from k to M when value would exceed 5 chars.
+ * Examples: 500 → "  500", 1300 → " 1.3k", 32000 → "32.0k", 950500 → "0.95M"
+ */
+export function formatFixedTokens(count: number): string {
+	if (count < 1000) {
+		return count.toString().padStart(5);
+	}
+
+	const k = count / 1000;
+	if (k < 100) {
+		return (k.toFixed(1) + "k").padStart(5);
+	} else if (k < 1000) {
+		const m = count / 1000000;
+		return (m.toFixed(2) + "M").padStart(5);
+	} else {
+		const m = count / 1000000;
+		return (m.toFixed(2) + "M").padStart(5);
+	}
+}
+
+/**
+ * Format flow type name to fixed width (10 chars) in uppercase with dot padding.
+ * Examples: "debug" → "DEBUG.....", "architect" → "ARCHITECT.", "brainstorm" → "BRAINSTORM"
+ */
+export function formatFlowTypeName(type: string): string {
+	const upper = type.toUpperCase();
+	const targetWidth = 10;
+	if (upper.length >= targetWidth) return upper.slice(0, targetWidth);
+	return upper + ".".repeat(targetWidth - upper.length);
+}
+
 export function formatCompactStats(usage: Partial<UsageStats>, model?: string): string {
 	const parts: string[] = [];
-	parts.push(`↑${formatTokens(usage.input || 0)}`);
-	parts.push(`↓${formatTokens(usage.output || 0)}`);
-	if (usage.cacheRead) parts.push(`cr:${formatTokens(usage.cacheRead)}`);
-	if (usage.contextTokens && usage.contextTokens > 0) parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
-	if (model) parts.push(model);
-	return parts.join(" ");
+	parts.push(`${formatFixedTokens(usage.input || 0)}↑`);
+	parts.push(`${formatFixedTokens(usage.output || 0)}↓`);
+	if (usage.cacheRead) parts.push(`cr:${formatFixedTokens(usage.cacheRead)}`);
+	if (usage.contextTokens && usage.contextTokens > 0) parts.push(`ctx:${formatFixedTokens(usage.contextTokens)}`);
+	return `[ ${parts.join(" ")} ]${model ? ` ─ ${model}` : ""}`;
+}
+
+/**
+ * Format usage stats for expanded view with context tokens on separate line.
+ * Returns stats line and optional context tokens line.
+ * Example: { stats: "[12.4k↑ 2.1k↓ cr:85.0k] ─ mimo-v2.5-pro", contextTokens: "ctx: 32.0k" }
+ */
+export function formatExpandedStats(usage: Partial<UsageStats>, model?: string): { stats: string; contextTokens: string | null } {
+	const parts: string[] = [];
+	parts.push(`${formatFixedTokens(usage.input || 0)}↑`);
+	parts.push(`${formatFixedTokens(usage.output || 0)}↓`);
+	if (usage.cacheRead) parts.push(`cr:${formatFixedTokens(usage.cacheRead)}`);
+
+	const stats = `[${parts.join(" ")}]${model ? ` ─ ${model}` : ""}`;
+	const contextTokens = usage.contextTokens && usage.contextTokens > 0 ? `ctx:${formatFixedTokens(usage.contextTokens)}` : null;
+
+	return { stats, contextTokens };
 }
 
 export function truncateChars(text: string, max: number): string {

package/render.ts

@@ -17,10 +17,12 @@ import {
 	aggregateFlowUsage,
 	getFlowDisplayItems,
 	getFlowOutput,
+	getLastToolCall,
+	getLastAssistantText,
 	isFlowError,
 	isFlowSuccess,
 } from "./types.js";
-import { formatTokens, formatFlowUsage, formatCompactStats, truncateChars, tailText } from "./render-utils.js";
+import { formatTokens, formatFixedTokens, formatFlowUsage, formatCompactStats, formatExpandedStats, formatFlowTypeName, truncateChars, tailText } from "./render-utils.js";
 
 function shortenPath(p: string): string {
 	const home = os.homedir();
@@ -109,19 +111,11 @@ function flowStatusIcon(r: SingleResult, theme: { fg: ThemeFg }): string {
 // renderFlowCall — shown while the flow is being invoked
 // ---------------------------------------------------------------------------
 
-function truncateText(text: string): string {
-	const words = text.split(/\s+/);
-	if (words.length <= 12) return text;
-	return `${words.slice(0, 3).join(" ")} ... ${words.slice(-8).join(" ")}`;
-}
-
 export function renderFlowCall(args: Record<string, any>, theme: FlowTheme): Text {
 	const flows = args.flow as Array<{ type: string; intent: string }> | undefined;
 
 	// Minimal — renderFlowResult owns the full display
 	return new Text("", 0, 0);
-
-	return new Text(theme.fg("muted", "(empty flow call)"), 0, 0);
 }
 
 // ---------------------------------------------------------------------------
@@ -179,14 +173,24 @@ function renderFlowExpanded(
 	const mdTheme = getMarkdownTheme();
 	const container = new Container();
 
-	// Header
-	let header = `${icon} ${theme.fg("toolTitle", theme.bold(`[${r.type}]`))}${theme.fg("muted", ` (${r.agentSource})`)}`;
+	// Header: uppercase type name with dots, no icon, no source
+	const typeName = formatFlowTypeName(r.type);
+	let header = theme.fg("toolTitle", theme.bold(typeName));
 	if (error && r.stopReason) header += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
 	container.addChild(new Text(header, 0, 0));
 	if (error && r.errorMessage) {
 		container.addChild(new Text(theme.fg("error", `Error: ${r.errorMessage}`), 0, 0));
 	}
 
+	// Stats: all-in-one bracket format with context inline
+	const statsParts: string[] = [];
+	statsParts.push(`${formatFixedTokens(r.usage.input || 0)}↑`);
+	statsParts.push(`${formatFixedTokens(r.usage.output || 0)}↓`);
+	if (r.usage.cacheRead) statsParts.push(`cr:${formatFixedTokens(r.usage.cacheRead)}`);
+	if (r.usage.contextTokens > 0) statsParts.push(`ctx:${formatFixedTokens(r.usage.contextTokens)}`);
+	const inlineStats = `[ ${statsParts.join(" ")} ]${r.model ? ` ─ ${r.model}` : ""}`;
+	container.addChild(new Text(theme.fg("dim", inlineStats), 0, 0));
+
 	// Intent
 	container.addChild(new Spacer(1));
 	container.addChild(new Text(theme.fg("muted", "─── Intent ───"), 0, 0));
@@ -210,13 +214,6 @@ function renderFlowExpanded(
 		container.addChild(new Text(toolTraces, 0, 0));
 	}
 
-	// Usage
-	const usageStr = formatFlowUsage(r.usage, r.model);
-	if (usageStr) {
-		container.addChild(new Spacer(1));
-		container.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
-	}
-
 	return container;
 }
 
@@ -231,23 +228,31 @@ function renderFlowCollapsed(
 	streamingText?: string,
 ): Text {
 	const stats = formatCompactStats(r.usage, r.model);
-	let text = `${theme.bg("selectedBg", theme.fg("accent", theme.bold(r.type)))} ${theme.fg("dim", "─")} ${theme.fg("dim", stats)}`;
+	const typeName = formatFlowTypeName(r.type);
+	let text = `${theme.bg("selectedBg", theme.fg("accent", theme.bold(typeName)))} ${theme.fg("dim", "─")} ${theme.fg("dim", stats)}`;
 	if (error && r.stopReason) text += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
 
-	// Intent line
+	// DIR: line (intent/objective)
 	if (r.intent) {
-		text += `\n${theme.fg("dim", `├─ int:`)} ${theme.fg("dim", truncateChars(r.intent, 40))}`;
+		text += `\n${theme.fg("dim", "├─ DIR:")} ${theme.fg("dim", truncateChars(r.intent, 50))}`;
+	}
+
+	// EXE: line (last tool call)
+	const lastTool = getLastToolCall(r.messages);
+	if (lastTool) {
+		const exeStr = formatFlowToolCall(lastTool.name, lastTool.args, theme.fg.bind(theme));
+		text += `\n${theme.fg("dim", "├─ EXE:")} ${exeStr}`;
 	}
 
-	// Output line
+	// LOG: line (last assistant text or streaming)
 	if (flowOutput) {
-		text += `\n${theme.fg("dim", "└─ msg:")} ${renderFlowReport(truncateChars(flowOutput, 25), theme)}`;
+		text += `\n${theme.fg("dim", "└─ LOG:")} ${theme.fg("dim", truncateChars(flowOutput, 50))}`;
 	} else if (streamingText) {
-		text += `\n${theme.fg("dim", "└─ msg:")} ${theme.fg("dim", tailText(streamingText, 40))}`;
+		text += `\n${theme.fg("dim", "└─ LOG:")} ${theme.fg("dim", tailText(streamingText, 50))}`;
 	} else if (error && r.errorMessage) {
-		text += `\n${theme.fg("dim", "└─ msg:")} ${theme.fg("error", truncateChars(r.errorMessage, 25))}`;
+		text += `\n${theme.fg("dim", "└─ LOG:")} ${theme.fg("error", truncateChars(r.errorMessage, 50))}`;
 	} else {
-		text += `\n${theme.fg("dim", "└─ msg:")} ${theme.fg("dim", "[n/a]")}`;
+		text += `\n${theme.fg("dim", "└─ LOG:")} ${theme.fg("dim", "[n/a]")}`;
 	}
 
 	return new Text(text, 0, 0);
@@ -282,19 +287,32 @@ function renderMultiFlowExpanded(
 	const mdTheme = getMarkdownTheme();
 	const container = new Container();
 
+	// Summary: just show count, no icon
 	container.addChild(new Text(
-		`${icon} ${theme.fg("toolTitle", theme.bold("flow "))}${theme.fg("accent", `${successCount}/${results.length} flows`)}`,
+		theme.fg("accent", `${results.length} flows`),
 		0, 0,
 	));
 
 	for (const r of results) {
-		const rIcon = flowStatusIcon(r, theme);
 		const displayItems = getFlowDisplayItems(r.messages);
 		const flowOutput = getFlowOutput(r.messages);
+		const typeName = formatFlowTypeName(r.type);
 
 		container.addChild(new Spacer(1));
-		container.addChild(new Text(`${theme.fg("muted", "─── ")}${theme.fg("accent", `[${r.type}]`)} ${rIcon}`, 0, 0));
-		container.addChild(new Text(theme.fg("muted", "Intent: ") + theme.fg("dim", r.intent), 0, 0));
+		// Per-flow header: ─── EXPLORER (no icon)
+		container.addChild(new Text(`${theme.fg("muted", "─── ")}${theme.fg("accent", typeName)}`, 0, 0));
+
+		// Stats: all-in-one bracket format with context inline
+		const flowParts: string[] = [];
+		flowParts.push(`${formatFixedTokens(r.usage.input || 0)}↑`);
+		flowParts.push(`${formatFixedTokens(r.usage.output || 0)}↓`);
+		if (r.usage.cacheRead) flowParts.push(`cr:${formatFixedTokens(r.usage.cacheRead)}`);
+		if (r.usage.contextTokens > 0) flowParts.push(`ctx:${formatFixedTokens(r.usage.contextTokens)}`);
+		const flowStats = `[ ${flowParts.join(" ")} ]${r.model ? ` ─ ${r.model}` : ""}`;
+		container.addChild(new Text(theme.fg("dim", flowStats), 0, 0));
+
+		// Intent: just show text, no prefix
+		container.addChild(new Text(theme.fg("dim", r.intent), 0, 0));
 
 		if (flowOutput) {
 			container.addChild(new Spacer(1));
@@ -308,65 +326,83 @@ function renderMultiFlowExpanded(
 			container.addChild(new Text(theme.fg("muted", "─── Tool Calls ───"), 0, 0));
 			container.addChild(new Text(toolTraces, 0, 0));
 		}
-
-		const taskUsage = formatFlowUsage(r.usage, r.model);
-		if (taskUsage) container.addChild(new Text(theme.fg("dim", taskUsage), 0, 0));
 	}
 
-	const totalUsage = formatFlowUsage(aggregateFlowUsage(results));
-	if (totalUsage) {
-		container.addChild(new Spacer(1));
-		container.addChild(new Text(theme.fg("dim", `Total: ${totalUsage}`), 0, 0));
-	}
+	// Total stats: all-in-one bracket format with context inline
+	const totalUsage = aggregateFlowUsage(results);
+	const totalModel = results[0]?.model;
+	const totalParts: string[] = [];
+	totalParts.push(`${formatFixedTokens(totalUsage.input || 0)}↑`);
+	totalParts.push(`${formatFixedTokens(totalUsage.output || 0)}↓`);
+	if (totalUsage.cacheRead) totalParts.push(`cr:${formatFixedTokens(totalUsage.cacheRead)}`);
+	if (totalUsage.contextTokens > 0) totalParts.push(`ctx:${formatFixedTokens(totalUsage.contextTokens)}`);
+	const totalStats = `[ ${totalParts.join(" ")} ]${totalModel ? ` ─ ${totalModel}` : ""}`;
+	container.addChild(new Spacer(1));
+	container.addChild(new Text(theme.fg("dim", totalStats), 0, 0));
 
 	return container;
 }
 
-function renderMultiFlowCollapsed(
+function renderActivityPanel(
 	results: SingleResult[],
 	theme: FlowTheme,
-): Text {
-	let text = "";
+): Container {
+	const container = new Container();
 
 	for (let i = 0; i < results.length; i++) {
 		const r = results[i];
 		const isLast = i === results.length - 1;
-		const flowOutput = getFlowOutput(r.messages);
 		const stats = formatCompactStats(r.usage, r.model);
 		const error = isFlowError(r);
+		const typeName = formatFlowTypeName(r.type);
 
 		// Header line
 		const headerPrefix = isLast ? "└─" : "├─";
-		let line = `${theme.fg("dim", headerPrefix)} ${theme.bg("selectedBg", theme.fg("accent", theme.bold(r.type)))}`;
-		if (stats) {
-			line += ` ${theme.fg("dim", "─")} ${theme.fg("dim", stats)}`;
-		}
+		let headerLine = `${theme.fg("dim", headerPrefix)} ${theme.bg("selectedBg", theme.fg("accent", theme.bold(typeName)))} ${theme.fg("dim", "─")} ${theme.fg("dim", stats)}`;
 		if (error && r.stopReason) {
-			line += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
+			headerLine += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
 		}
-		if (i > 0) text += "\n";
-		text += line;
+		container.addChild(new Text(headerLine, 0, 0));
 
 		// Continuation indent for sub-lines
 		const indent = isLast ? "   " : "│  ";
 
-		// Intent line
+		// DIR: line (intent/objective)
 		if (r.intent) {
-			const intentPrefix = hasMsg ? "├─" : "└─";
-			text += `\n${theme.fg("dim", indent + intentPrefix + " int:")} ${theme.fg("dim", truncateChars(r.intent, 40))}`;
+			container.addChild(new Text(`${theme.fg("dim", indent + "├─ DIR:")} ${theme.fg("dim", truncateChars(r.intent, 50))}`, 0, 0));
 		}
 
-		// Output line
-		if (flowOutput) {
-			text += `\n${theme.fg("dim", indent + "└─ msg:")} ${renderFlowReport(truncateChars(flowOutput, 25), theme)}`;
+		// EXE: line (last tool call)
+		const lastTool = getLastToolCall(r.messages);
+		if (lastTool) {
+			const exeStr = formatFlowToolCall(lastTool.name, lastTool.args, theme.fg.bind(theme));
+			container.addChild(new Text(`${theme.fg("dim", indent + "├─ EXE:")} ${exeStr}`, 0, 0));
+		}
+
+		// LOG: line (last assistant text)
+		const lastText = getLastAssistantText(r.messages);
+		if (lastText) {
+			container.addChild(new Text(`${theme.fg("dim", indent + "└─ LOG:")} ${theme.fg("dim", truncateChars(lastText, 50))}`, 0, 0));
 		} else if (error && r.errorMessage) {
-			text += `\n${theme.fg("dim", indent + "└─ msg:")} ${theme.fg("error", truncateChars(r.errorMessage, 25))}`;
+			container.addChild(new Text(`${theme.fg("dim", indent + "└─ LOG:")} ${theme.fg("error", truncateChars(r.errorMessage, 50))}`, 0, 0));
 		} else {
-			text += `\n${theme.fg("dim", indent + "└─ msg:")} ${theme.fg("dim", "[n/a]")}`;
+			container.addChild(new Text(`${theme.fg("dim", indent + "└─ LOG:")} ${theme.fg("dim", "[n/a]")}`, 0, 0));
+		}
+
+		// Add blank line separator between flows (with continuation pipe)
+		if (!isLast) {
+			container.addChild(new Text(theme.fg("dim", "│"), 0, 0));
 		}
 	}
 
-	text += `\n${theme.fg("muted", "(Ctrl+O to expand tool traces)")}`;
+	container.addChild(new Text(theme.fg("muted", "(Ctrl+O to expand tool traces)"), 0, 0));
 
-	return new Text(text, 0, 0);
+	return container;
+}
+
+function renderMultiFlowCollapsed(
+	results: SingleResult[],
+	theme: FlowTheme,
+): Container {
+	return renderActivityPanel(results, theme);
 }

package/runner-events.js

@@ -44,6 +44,46 @@ export function drainStreamingText(result) {
   return buf;
 }
 
+// ---------------------------------------------------------------------------
+// Streaming token estimate
+// ---------------------------------------------------------------------------
+
+/** Chars per token heuristic for output estimation. */
+const CHARS_PER_TOKEN = 4;
+
+function getStreamingEstimate(result) {
+  if (!Object.prototype.hasOwnProperty.call(result, "__streamingEstimate")) {
+    Object.defineProperty(result, "__streamingEstimate", {
+      value: { chars: 0 },
+      enumerable: false,
+      configurable: false,
+      writable: true,
+    });
+  }
+  return result.__streamingEstimate;
+}
+
+/**
+ * Track streaming characters and estimate output tokens.
+ * Called on every streaming delta.
+ */
+function updateStreamingEstimate(result, deltaLength) {
+  if (deltaLength <= 0) return;
+  const est = getStreamingEstimate(result);
+  est.chars += deltaLength;
+}
+
+/**
+ * Drain the current streaming estimate and return estimated output tokens.
+ * Returns 0 when no streaming has occurred.
+ */
+export function drainStreamingEstimate(result) {
+  const est = getStreamingEstimate(result);
+  const tokens = Math.floor(est.chars / CHARS_PER_TOKEN);
+  est.chars = 0;
+  return tokens;
+}
+
 /**
  * Accumulate a text or thinking delta into the streaming buffer.
  * Returns true if the caller should emit an update.
@@ -52,6 +92,7 @@ function accumulateStreamingDelta(result, delta) {
   if (!delta) return false;
   const buf = getStreamingTextBuffer(result);
   result.__streamingTextBuffer = buf + delta;
+  updateStreamingEstimate(result, delta.length);
   if (result.__streamingTextBuffer.length - result.__lastEmittedWordCount >= 40) {
     result.__lastEmittedWordCount = result.__streamingTextBuffer.length;
     return true;
@@ -97,6 +138,10 @@ function addFlowAssistantMessage(result, message) {
 
   result.messages.push(message);
 
+  // Reset streaming estimate when actual usage arrives
+  const est = getStreamingEstimate(result);
+  est.chars = 0;
+
   result.usage.turns++;
   const usage = message.usage;
   if (usage) {

package/types.ts

@@ -140,10 +140,46 @@ export function getFlowDisplayItems(messages: Message[]): DisplayItem[] {
 				if (part.type === "text") {
 					items.push({ type: "text", text: part.text });
 				} else if (part.type === "toolCall") {
-					items.push({ type: "toolCall", name: part.name, args: part.arguments });
+					const name = part.name ?? part.toolName ?? "unknown";
+					const args = (part.arguments ?? part.input ?? {}) as Record<string, unknown>;
+					items.push({ type: "toolCall", name, args });
 				}
 			}
 		}
 	}
 	return items;
 }
+
+/** Extract the last tool call from message history. */
+export function getLastToolCall(messages: Message[]): DisplayItem | undefined {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role === "assistant") {
+			for (let j = msg.content.length - 1; j >= 0; j--) {
+				const part = msg.content[j];
+				if (part.type === "toolCall") {
+					const name = part.name ?? part.toolName ?? "unknown";
+					const args = (part.arguments ?? part.input ?? {}) as Record<string, unknown>;
+					return { type: "toolCall", name, args };
+				}
+			}
+		}
+	}
+	return undefined;
+}
+
+/** Extract the last assistant text from message history. */
+export function getLastAssistantText(messages: Message[]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role === "assistant") {
+			for (let j = msg.content.length - 1; j >= 0; j--) {
+				const part = msg.content[j];
+				if (part.type === "text" && part.text.trim()) {
+					return part.text.trim();
+				}
+			}
+		}
+	}
+	return "";
+}