@herbertgao/pi-subagents 0.15.5 → 0.16.0

package/src/invocation-config.ts

@@ -1,3 +1,4 @@
+import { Type } from "@sinclair/typebox"
 import type {
   AgentConfig,
   IsolationMode,
@@ -5,6 +6,61 @@ import type {
   ThinkingLevel,
 } from "./types.js"
 
+/**
+ * The model-facing `isolation` parameter, shared by the `Agent` tool and the
+ * nested delegation tool so the two cannot drift.
+ *
+ * Shape matters more than wording here. As a single-value optional literal,
+ * models that fill every optional parameter — the transcript on #231 shows one
+ * emitting `resume: ""`, `schedule: ""` and `model: "default"` alongside it —
+ * had only `"worktree"` available to fill it with, and kept spawning worktrees
+ * across three turns while their own reasoning said to omit the field. Every
+ * other optional parameter has an inert filler; this one did not. `"off"` is
+ * listed first and described as the default so the harmless value is the
+ * obvious one to reach for.
+ *
+ * The wording tracks Claude Code's own `isolation` parameter, whose phrasing
+ * models have the most exposure to: one description on the union rather than
+ * per-value ones, opening "Isolation mode.", then a sentence per value in
+ * schema order, each with its caveats in a trailing parenthetical. Two clauses
+ * are ours, because our shape is not theirs — `"off"` has no counterpart there
+ * (their enum is `worktree | remote`, so both of their values do something),
+ * and neither does the uncommitted-work warning, which is the specific trap
+ * #231 fell into. Deliberately absent is any "only use a worktree when…"
+ * restriction: Claude Code's `Agent` tool states the capability and stops, and
+ * a second legal value is what lets a model decline one, not being told to.
+ */
+const isolationParamShape = {
+  isolation: Type.Optional(
+    Type.Union([Type.Literal("off"), Type.Literal("worktree")], {
+      description:
+        'Isolation mode. Default "off". "off" runs the agent in the current checkout, the same as omitting the field. "worktree" creates a temporary git worktree so the agent works on an isolated copy of the repo (a copy cannot see uncommitted or staged changes in the main checkout).',
+    }),
+  ),
+}
+
+/**
+ * Build the `isolation` parameter for a tool schema, or nothing when the
+ * project disabled worktrees (`worktreeIsolation: false`).
+ *
+ * Dropping the field beats accepting it and quietly downgrading. The setting is
+ * for a project whose model passes `"worktree"` on *every* call, so a
+ * per-result "isolation was disabled" note would be noise on every result and
+ * would keep raising the salience of a capability that isn't there. With no
+ * field there is nothing to pass, nothing to drop, and nothing to explain — the
+ * same trade `scheduleParam` makes for disabled scheduling, at zero LLM-context
+ * cost. The resolver gate and the `agent-manager` check still cover the paths a
+ * schema can't reach: agent files, the scheduler, and cross-extension RPC.
+ *
+ * Like `scheduleParam`, this is read once at tool registration — flipping the
+ * setting needs a new pi session for the schema to change.
+ */
+export function isolationParam(
+  enabled: boolean,
+): Partial<typeof isolationParamShape> {
+  return enabled ? isolationParamShape : {}
+}
+
 interface AgentInvocationParams {
   model?: string
   thinking?: string
@@ -12,12 +68,42 @@ interface AgentInvocationParams {
   run_in_background?: boolean
   inherit_context?: boolean
   isolated?: boolean
-  isolation?: IsolationMode
+  /**
+   * Untyped on purpose. Both tool schemas now build this field conditionally
+   * and spread it, which erases TypeBox's literal inference to `unknown` (the
+   * `schedule` param has the same shape). The resolver below narrows by
+   * comparison rather than trusting the declaration, which also makes it safe
+   * for the cross-extension RPC path, where options arrive unvalidated.
+   */
+  isolation?: unknown
+}
+
+interface ResolveOptions {
+  /**
+   * Whether worktree isolation is permitted at all. False when the project set
+   * `worktreeIsolation: false`, which drops a requested worktree rather than
+   * failing the call: the fail-loud precedent covers spawns that *cannot* work,
+   * while this one is the user opting out, and throwing would break exactly the
+   * calls the `"off"` value exists to tolerate. Defaults to allowed.
+   */
+  worktreeAllowed?: boolean
+  /**
+   * What an unqualified spawn means — neither the call nor the agent file said.
+   *
+   * Top-level callers pass the `backgroundByDefault` setting (default `true`,
+   * following Claude Code). Nested callers pass `false` unconditionally: a
+   * detached child is killed by `abortOwnedChildren` when its parent settles
+   * and has no notification path of its own, so backgrounding one loses its
+   * work. Both call sites pass it explicitly; the `false` fallback only covers
+   * a caller that supplies no options at all, which in-tree means tests.
+   */
+  defaultRunInBackground?: boolean
 }
 
 export function resolveAgentInvocationConfig(
   agentConfig: AgentConfig | undefined,
   params: AgentInvocationParams,
+  opts?: ResolveOptions,
 ): {
   modelInput?: string
   modelFromParams: boolean
@@ -28,6 +114,15 @@ export function resolveAgentInvocationConfig(
   isolated: boolean
   isolation?: IsolationMode
 } {
+  // Precedence first, collapse second — reversing these loses the veto, since
+  // an agent file's "off" only outranks a caller's "worktree" while it is still
+  // a value. Everything downstream then sees "worktree" or nothing at all.
+  const requested = agentConfig?.isolation ?? params.isolation
+  const isolation =
+    requested === "worktree" && opts?.worktreeAllowed !== false
+      ? "worktree"
+      : undefined
+
   return {
     modelInput: agentConfig?.model ?? params.model,
     modelFromParams: agentConfig?.model == null && params.model != null,
@@ -38,9 +133,12 @@ export function resolveAgentInvocationConfig(
     inheritContext:
       agentConfig?.inheritContext ?? params.inherit_context ?? false,
     runInBackground:
-      agentConfig?.runInBackground ?? params.run_in_background ?? false,
+      agentConfig?.runInBackground ??
+      params.run_in_background ??
+      opts?.defaultRunInBackground ??
+      false,
     isolated: agentConfig?.isolated ?? params.isolated ?? false,
-    isolation: agentConfig?.isolation ?? params.isolation,
+    isolation,
   }
 }
 

package/src/nested-tools.ts

@@ -16,7 +16,10 @@ import {
   resolveTypeIn,
 } from "./agent-types.js"
 import { loadCustomAgents } from "./custom-agents.js"
-import { resolveAgentInvocationConfig } from "./invocation-config.js"
+import {
+  isolationParam,
+  resolveAgentInvocationConfig,
+} from "./invocation-config.js"
 import { resolveModel } from "./model-resolver.js"
 import { checkModelScope } from "./model-scope.js"
 import {
@@ -38,6 +41,7 @@ import type {
   ThinkingLevel,
 } from "./types.js"
 import { addUsage } from "./usage.js"
+import { isWorktreeIsolationEnabled } from "./worktree.js"
 
 /**
  * Hard ceiling on nesting for every branch: main session = 0, its subagents = 1,
@@ -212,7 +216,12 @@ export function createNestedSubagentTools(
         Type.String({ description: "Optional thinking level." }),
       ),
       max_turns: Type.Optional(Type.Number({ minimum: 1 })),
-      run_in_background: Type.Optional(Type.Boolean()),
+      run_in_background: Type.Optional(
+        Type.Boolean({
+          description:
+            "Defaults to false for nested spawns — the call blocks and returns the child's result inline. Set true only for work you will collect later with get_subagent_result; a detached child is stopped when you finish.",
+        }),
+      ),
       resume: Type.Optional(
         Type.String({
           description: "Resume a nested agent owned by this parent.",
@@ -220,7 +229,7 @@ export function createNestedSubagentTools(
       ),
       isolated: Type.Optional(Type.Boolean()),
       inherit_context: Type.Optional(Type.Boolean()),
-      isolation: Type.Optional(Type.Literal("worktree")),
+      ...isolationParam(isWorktreeIsolationEnabled()),
     }),
     execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
       if (params.resume) {
@@ -277,7 +286,12 @@ export function createNestedSubagentTools(
       }
 
       const config = getAgentConfigIn(registry, resolvedType)
-      const invocation = resolveAgentInvocationConfig(config, params)
+      // Foreground regardless of `backgroundByDefault` — see the reasoning on
+      // ResolveOptions. An explicit `true` here still opts in.
+      const invocation = resolveAgentInvocationConfig(config, params, {
+        worktreeAllowed: isWorktreeIsolationEnabled(),
+        defaultRunInBackground: false,
+      })
       let model = ctx.model
       if (invocation.modelInput) {
         const resolvedModel = resolveModel(

package/src/settings.ts

@@ -18,6 +18,23 @@ export interface SubagentsSettings {
   defaultMaxTurns?: number
   graceTurns?: number
   defaultJoinMode?: JoinMode
+  /**
+   * Whether a top-level `Agent` spawn that doesn't say runs detached.
+   * Defaults to `true`, following Claude Code, where the agent backgrounds
+   * unless the caller passes `run_in_background: false`. Set `false` to restore
+   * the previous behaviour, where an unqualified spawn blocked the turn and
+   * returned its result inline.
+   *
+   * Top-level only. Nested spawns (a subagent spawning its own) always default
+   * to foreground regardless of this setting — see `nested-tools.ts`, where a
+   * detached child would be killed by `abortOwnedChildren` when its parent
+   * settles, with no notification path to deliver its result.
+   *
+   * An explicit `run_in_background` on the call, or in the agent file's
+   * frontmatter, overrides this in both directions; the setting only decides
+   * what "unspecified" means.
+   */
+  backgroundByDefault?: boolean
   /**
    * Master switch for the schedule subagent feature. Defaults to `true`.
    * When `false`: the `Agent` tool's `schedule` param + its guideline are
@@ -101,6 +118,29 @@ export interface SubagentsSettings {
    * (`isolation: worktree`), or memory files.
    */
   outputTranscript?: boolean
+  /**
+   * Whether `isolation: "worktree"` may create a worktree at all. Defaults to
+   * `true`. Set `false` on a repo where worktrees are too slow or too large to
+   * be worth it (#184): a requested worktree is then dropped and the agent runs
+   * in the main checkout.
+   *
+   * The drop is deliberately silent — there is no per-result note, because the
+   * setting exists for projects whose model asks for a worktree on every call,
+   * where a note would be noise on every result. What keeps the orchestrator
+   * from claiming a `pi-agent-*` branch anyway is that it is never told the
+   * capability exists: `isolationParam` (invocation-config.ts) drops the field
+   * from both tool schemas, and `isolationGuideline` (index.ts) drops the
+   * matching prose from the full and compact descriptions — a custom one opts
+   * in via the `{{isolationGuideline}}` placeholder. Anything that
+   * reintroduces the prose has to reintroduce a note with it.
+   *
+   * Deliberately a downgrade rather than an error. The fail-loud rule covers
+   * worktrees that *cannot* be created; this is the user declining one, and
+   * throwing would reject exactly the calls that the `isolation: "off"` value
+   * exists to tolerate. Enforced below the tool boundary, so it also covers the
+   * scheduler and the unvalidated cross-extension RPC path.
+   */
+  worktreeIsolation?: boolean
   /**
    * Hard ceiling on nested subagent delegation, counted from the main session:
    * main = 0, its subagents = 1, their children = 2. Defaults to `2`; `0` or `1`
@@ -123,6 +163,43 @@ export interface SubagentsSettings {
    * meaning one thing here and another in the resolver.
    */
   fallbackSubagent?: string
+  /**
+   * Whether this extension's tool results carry a `usage` field, so subagent
+   * spend reaches the parent session's own accounting. Defaults to `false`.
+   *
+   * Subagents run in their own pi sessions, so by default the parent's footer,
+   * statusline and `/cost` show only what the main model spent — a session that
+   * delegated most of its work reads as nearly free. Pi folds
+   * `toolResult.usage` into `getSessionStats()`, so attaching it makes those
+   * surfaces count subagents too, under `/cost`'s "Tools/summaries" bucket.
+   *
+   * Off by default because it changes numbers the user may already be tracking
+   * (a statusline reading session cost will step up), not because the numbers
+   * are wrong.
+   *
+   * Three properties of what gets reported:
+   *   - Tokens exclude `cacheRead`, for the reason in `usage.ts` — the parent's
+   *     token total therefore rises by billed tokens only.
+   *   - Cost is pi's own per-message `usage.cost.total`; we price nothing, and
+   *     a model pi has no rates for contributes 0.
+   *   - The context-window percentage is untouched. Pi derives it from assistant
+   *     messages alone (`getContextUsage`), so a delegating session's context
+   *     does not appear to fill up faster.
+   */
+  reportUsage?: boolean
+  /**
+   * Whether the subagent surfaces show an estimated dollar cost next to their
+   * token counts (widget, FleetView, conversation viewer, foreground results,
+   * completion notifications). Defaults to `false`. Applied live.
+   *
+   * Rendered as `~$0.0042` — the tilde marks it as pi's reported estimate
+   * rather than a billed figure, and it is omitted entirely when the model has
+   * no pricing data, so a local model shows tokens and no dollars.
+   *
+   * Independent of `reportUsage`: this one is what a human reads, that one is
+   * what the parent session counts.
+   */
+  showCost?: boolean
 }
 
 export type ToolDescriptionMode = "full" | "compact" | "custom"
@@ -133,6 +210,7 @@ export interface SettingsAppliers {
   setDefaultMaxTurns: (n: number) => void
   setGraceTurns: (n: number) => void
   setDefaultJoinMode: (mode: JoinMode) => void
+  setBackgroundByDefault: (b: boolean) => void
   setSchedulingEnabled: (b: boolean) => void
   setScopeModels: (enabled: boolean) => void
   setStrictAgentFiles: (b: boolean) => void
@@ -141,8 +219,11 @@ export interface SettingsAppliers {
   setFleetView: (b: boolean) => void
   setWidgetMode: (mode: WidgetMode) => void
   setOutputTranscript: (b: boolean) => void
+  setWorktreeIsolation: (b: boolean) => void
   setMaxSubagentDepth: (n: number) => void
   setFallbackSubagent: (v: string | undefined) => void
+  setReportUsage: (b: boolean) => void
+  setShowCost: (b: boolean) => void
 }
 
 /** Emit callback — a subset of `pi.events.emit` to keep helpers testable. */
@@ -208,6 +289,9 @@ function sanitize(raw: unknown): SubagentsSettings {
   ) {
     out.defaultJoinMode = r.defaultJoinMode as JoinMode
   }
+  if (typeof r.backgroundByDefault === "boolean") {
+    out.backgroundByDefault = r.backgroundByDefault
+  }
   if (typeof r.schedulingEnabled === "boolean") {
     out.schedulingEnabled = r.schedulingEnabled
   }
@@ -238,6 +322,15 @@ function sanitize(raw: unknown): SubagentsSettings {
   if (typeof r.outputTranscript === "boolean") {
     out.outputTranscript = r.outputTranscript
   }
+  if (typeof r.worktreeIsolation === "boolean") {
+    out.worktreeIsolation = r.worktreeIsolation
+  }
+  if (typeof r.reportUsage === "boolean") {
+    out.reportUsage = r.reportUsage
+  }
+  if (typeof r.showCost === "boolean") {
+    out.showCost = r.showCost
+  }
   if (r.fallbackSubagent === false) {
     // The only non-string spelling worth accepting: a boolean would otherwise be
     // dropped, silently leaving the PERMISSIVE default in place. Every string is
@@ -322,6 +415,8 @@ export function applySettings(
   if (typeof s.fallbackSubagent === "string")
     appliers.setFallbackSubagent(s.fallbackSubagent)
   if (s.defaultJoinMode) appliers.setDefaultJoinMode(s.defaultJoinMode)
+  if (typeof s.backgroundByDefault === "boolean")
+    appliers.setBackgroundByDefault(s.backgroundByDefault)
   if (typeof s.schedulingEnabled === "boolean")
     appliers.setSchedulingEnabled(s.schedulingEnabled)
   if (typeof s.scopeModels === "boolean") appliers.setScopeModels(s.scopeModels)
@@ -335,6 +430,10 @@ export function applySettings(
   if (s.widgetMode) appliers.setWidgetMode(s.widgetMode)
   if (typeof s.outputTranscript === "boolean")
     appliers.setOutputTranscript(s.outputTranscript)
+  if (typeof s.worktreeIsolation === "boolean")
+    appliers.setWorktreeIsolation(s.worktreeIsolation)
+  if (typeof s.reportUsage === "boolean") appliers.setReportUsage(s.reportUsage)
+  if (typeof s.showCost === "boolean") appliers.setShowCost(s.showCost)
 }
 
 /**

package/src/types.ts

@@ -21,8 +21,18 @@ export const DEFAULT_AGENT_NAMES = [
 /** Memory scope for persistent agent memory. */
 export type MemoryScope = "user" | "project" | "local"
 
-/** Isolation mode for agent execution. */
-export type IsolationMode = "worktree"
+/**
+ * Isolation mode for agent execution.
+ *
+ * `"off"` exists for the caller's benefit, not the runtime's: models that fill
+ * every optional parameter had no legal way to decline a single-value
+ * `isolation` field and kept spawning worktrees they had just reasoned their
+ * way out of (#231, #184). It is an input spelling only —
+ * `resolveAgentInvocationConfig` collapses it to `undefined`, so nothing
+ * downstream sees a value other than `"worktree"`. In an agent file it is a
+ * genuine veto, since agent config outranks tool-call params.
+ */
+export type IsolationMode = "worktree" | "off"
 
 /** Unified agent configuration — used for both default and user-defined agents. */
 export interface AgentConfig {
@@ -69,7 +79,10 @@ export interface AgentConfig {
   isolated?: boolean
   /** Persistent memory scope — agents with memory get a persistent directory and MEMORY.md */
   memory?: MemoryScope
-  /** Isolation mode — "worktree" runs the agent in a temporary git worktree */
+  /**
+   * Isolation mode — "worktree" runs the agent in a temporary git worktree,
+   * "off" refuses one even when the caller asks (frontmatter outranks params).
+   */
   isolation?: IsolationMode
   /** true = this is an embedded default agent (informational) */
   isDefault?: boolean
@@ -183,6 +196,12 @@ export interface NotificationDetails {
   turnCount: number
   maxTurns?: number
   totalTokens: number
+  /**
+   * Estimated cost in USD, from pi's per-message `usage.cost.total`. Always
+   * populated (0 when the model has no pricing); the renderer decides whether
+   * to show it, per the `showCost` setting.
+   */
+  totalCost?: number
   durationMs: number
   outputFile?: string
   error?: string

package/src/ui/agent-widget.ts

@@ -11,6 +11,7 @@ import type { AgentManager } from "../agent-manager.js"
 import { getConfig } from "../agent-types.js"
 import type { AgentInvocation, SubagentType, WidgetMode } from "../types.js"
 import {
+  getLifetimeCost,
   getLifetimeTotal,
   getSessionContextPercent,
   type LifetimeUsage,
@@ -75,8 +76,6 @@ export interface AgentActivity {
   turnCount: number
   /** Effective max turns for this agent (undefined = unlimited). */
   maxTurns?: number
-  /** Lifetime usage breakdown — see LifetimeUsage docs. */
-  lifetimeUsage: LifetimeUsage
 }
 
 /** Metadata attached to Agent tool results for custom rendering. */
@@ -108,6 +107,8 @@ export interface AgentDetails {
   turnCount?: number
   /** Effective max turns (undefined = unlimited). */
   maxTurns?: number
+  /** Estimated cost in USD; 0 when the model has no pricing data. */
+  cost?: number
   agentId?: string
   error?: string
 }
@@ -135,6 +136,31 @@ export function formatTokens(count: number): string {
   return `${count} token`
 }
 
+/**
+ * Format a cost as `~$0.0042`, or "" when there is nothing to show.
+ *
+ * The tilde is load-bearing: this is pi's own estimate from the model's listed
+ * rates, not a billed figure, and the surfaces that print it sit next to token
+ * counts that ARE exact.
+ *
+ * Nothing is printed for zero, which is also what a model with no pricing data
+ * reports: `$0.00` beside a local model's tokens would claim its cost was
+ * measured and found to be nothing, rather than never measured at all. For the
+ * same reason a real cost too small for four decimals reads `<$0.0001` — it was
+ * measured, and rounding it to `~$0.0000` would say the opposite.
+ */
+export function formatCost(cost: number): string {
+  if (!(cost > 0)) return "" // also catches NaN
+  if (cost < 0.0001) return "<$0.0001"
+  if (cost >= 1) return `~$${cost.toFixed(2)}`
+  // Under a dollar: cents at minimum, four decimals at most, nothing trailing.
+  // Most single runs land between a tenth of a cent and a dime, where rounding
+  // to cents would collapse a 4x difference in spend into the same figure.
+  const rounded = Number(cost.toFixed(4))
+  const decimals = (String(rounded).split(".")[1] ?? "").length
+  return `~$${rounded.toFixed(Math.max(2, decimals))}`
+}
+
 /**
  * Token count with optional context-fill % and compaction-count annotations.
  * Thresholds for percent: <70% dim, 70–85% warning, ≥85% error.
@@ -285,6 +311,12 @@ export class AgentWidget {
      * extension supplies one defaulting to `"background"`.
      */
     private mode: () => WidgetMode = () => "all",
+    /**
+     * Read live at render time, like `mode`. Whether running agents show an
+     * estimated cost beside their token count. Defaults to off — the extension
+     * supplies the user's `showCost` setting.
+     */
+    private showCost: () => boolean = () => false,
   ) {}
 
   /**
@@ -380,6 +412,7 @@ export class AgentWidget {
       startedAt: number
       completedAt?: number
       error?: string
+      lifetimeUsage?: LifetimeUsage
     },
     theme: Theme,
   ): string {
@@ -412,6 +445,13 @@ export class AgentWidget {
     if (activity) parts.push(formatTurns(activity.turnCount, activity.maxTurns))
     if (a.toolUses > 0)
       parts.push(`${a.toolUses} tool use${a.toolUses === 1 ? "" : "s"}`)
+    // From the record, not the activity tracker: that entry is deleted the
+    // moment an agent finishes, and "what did it cost" is a question asked
+    // about finished agents.
+    const costText = this.showCost()
+      ? formatCost(getLifetimeCost(a.lifetimeUsage))
+      : ""
+    if (costText) parts.push(costText)
     parts.push(duration)
 
     const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : ""
@@ -466,7 +506,11 @@ export class AgentWidget {
 
       const bg = this.agentActivity.get(a.id)
       const toolUses = bg?.toolUses ?? a.toolUses
-      const tokens = getLifetimeTotal(bg?.lifetimeUsage)
+      // Spend comes from the record, never from the activity tracker: the record
+      // is the one that survives the agent finishing, and the one nested-tools
+      // folds a hidden child's spend into. Reading the tracker while an agent
+      // runs and the record once it stops made the figure jump at completion.
+      const tokens = getLifetimeTotal(a.lifetimeUsage)
       const contextPercent = getSessionContextPercent(bg?.session)
       const tokenText =
         tokens > 0
@@ -477,12 +521,16 @@ export class AgentWidget {
               a.compactionCount,
             )
           : ""
+      const costText = this.showCost()
+        ? formatCost(getLifetimeCost(a.lifetimeUsage))
+        : ""
 
       const parts: string[] = []
       if (bg) parts.push(formatTurns(bg.turnCount, bg.maxTurns))
       if (toolUses > 0)
         parts.push(`${toolUses} tool use${toolUses === 1 ? "" : "s"}`)
       if (tokenText) parts.push(tokenText)
+      if (costText) parts.push(costText)
       parts.push(elapsed)
       const statsText = parts.join(" · ")
 

package/src/ui/conversation-viewer.ts

@@ -18,13 +18,18 @@ import {
 import { renderAgentName } from "../agent-color.js"
 import { extractText } from "../context.js"
 import type { AgentRecord } from "../types.js"
-import { getLifetimeTotal, getSessionContextPercent } from "../usage.js"
+import {
+  getLifetimeCost,
+  getLifetimeTotal,
+  getSessionContextPercent,
+} from "../usage.js"
 import type { Theme } from "./agent-widget.js"
 import {
   type AgentActivity,
   buildInvocationTags,
   describeActivity,
   fgPreservingNestedStyles,
+  formatCost,
   formatDuration,
   formatSessionTokens,
   getPromptModeLabel,
@@ -66,6 +71,12 @@ export class ConversationViewer implements Component {
     keybindings?: ViewerKeybindings,
     /** Send a steering message to the agent. Omitted → no compose affordance. */
     private onSteer?: (message: string) => void,
+    /**
+     * Whether the header shows an estimated cost after the token count. Read
+     * once, at construction: the overlay is opened from a menu, so the setting
+     * cannot change while it is on screen.
+     */
+    private showCost = false,
   ) {
     this.keys = createViewerKeys(keybindings)
     this.unsubscribe = session.subscribe(() => {
@@ -184,13 +195,20 @@ export class ConversationViewer implements Component {
     const toolUses = this.activity?.toolUses ?? this.record.toolUses
     if (toolUses > 0)
       headerParts.unshift(`${toolUses} tool${toolUses === 1 ? "" : "s"}`)
-    const tokens = getLifetimeTotal(this.activity?.lifetimeUsage)
+    // Spend from the record, context from the live session: the record is the
+    // only total that survives the agent finishing and the only one carrying a
+    // nested child's spend.
+    const tokens = getLifetimeTotal(this.record.lifetimeUsage)
     if (tokens > 0) {
       const percent = getSessionContextPercent(this.activity?.session)
       headerParts.push(
         formatSessionTokens(tokens, percent, th, this.record.compactionCount),
       )
     }
+    const cost = this.showCost
+      ? formatCost(getLifetimeCost(this.record.lifetimeUsage))
+      : ""
+    if (cost) headerParts.push(cost)
 
     lines.push(
       row(

package/src/ui/fleet-list.ts

@@ -22,8 +22,8 @@ import {
 import { hasAgentBadge, renderAgentName } from "../agent-color.js"
 import type { AgentManager } from "../agent-manager.js"
 import type { AgentRecord } from "../types.js"
-import { getLifetimeTotal } from "../usage.js"
-import { type AgentActivity, type Theme } from "./agent-widget.js"
+import { getLifetimeCost, getLifetimeTotal } from "../usage.js"
+import { type AgentActivity, formatCost, type Theme } from "./agent-widget.js"
 import {
   ConversationViewer,
   VIEWPORT_HEIGHT_PCT,
@@ -128,6 +128,12 @@ export class FleetList {
   constructor(
     private manager: AgentManager,
     private agentActivity: Map<string, AgentActivity>,
+    /**
+     * Read live at render time. Whether each row shows an estimated cost after
+     * its token count. Defaults to off — the extension supplies the user's
+     * `showCost` setting.
+     */
+    private showCost: () => boolean = () => false,
   ) {}
 
   // ---- Lifecycle ----
@@ -393,6 +399,7 @@ export class FleetList {
             },
             keybindings,
             (message: string) => this.manager.steer(record.id, message),
+            this.showCost(),
           )
         },
         {
@@ -476,6 +483,10 @@ export class FleetList {
     width: number,
     theme: Theme,
   ): string {
+    // The selected row renders in the theme's primary text color so it reads as
+    // one selection (#230). A configured badge survives — Claude Code's FleetView
+    // keeps the agent color on the selected row too and only bolds it — which also
+    // keeps the row's width fixed as the selection moves.
     const selected = rosterIndex === sel
     const name = renderAgentName(
       record.type,
@@ -488,11 +499,15 @@ export class FleetList {
       ? theme.fg("text", record.description)
       : record.description
     const left = `  ${this.bullet(rosterIndex, sel, theme)} ${name}  ${description}`
-    const tokens = getLifetimeTotal(
-      this.agentActivity.get(record.id)?.lifetimeUsage ?? record.lifetimeUsage,
-    )
+    // The record, not the activity tracker — see the note in AgentWidget's
+    // running line: only the record carries a nested child's spend, and only it
+    // outlives the agent.
+    const tokens = getLifetimeTotal(record.lifetimeUsage)
     const elapsedMs = (record.completedAt ?? Date.now()) - record.startedAt // freezes once finished
-    const stats = `${formatFleetElapsed(elapsedMs)} · ${formatFleetTokens(tokens)}`
+    const cost = this.showCost()
+      ? formatCost(getLifetimeCost(record.lifetimeUsage))
+      : ""
+    const stats = `${formatFleetElapsed(elapsedMs)} · ${formatFleetTokens(tokens)}${cost ? ` · ${cost}` : ""}`
     const right = selected ? theme.fg("text", stats) : theme.fg("dim", stats)
     return rightAlign(left, right, width)
   }