pi-code 1.0.56 → 1.0.57

package/extensions/subagent/render-result.ts

@@ -0,0 +1,306 @@
+/**
+ * How a subagent call and its results are drawn in the transcript: the collapsed and
+ * expanded forms for a single run, a chain and a parallel batch.
+ *
+ * Split from the extension body, which was the only place these lived, so the factory
+ * keeps the schema, the dispatch and the session hooks; nothing here touches process
+ * state, and these are the only users of the tui container and markdown widgets.
+ */
+
+import type { getMarkdownTheme, Theme } from '@earendil-works/pi-coding-agent'
+import { Container, Markdown, Spacer, Text } from '@earendil-works/pi-tui'
+
+import type { AgentScope } from './agents.js'
+import { type DisplayItem, formatToolCall, formatUsageStats, getDisplayItems, getFinalOutput } from './render.js'
+import type { SingleResult } from './types.js'
+
+const COLLAPSED_ITEM_COUNT = 10
+
+interface CallItem {
+  agent: string
+  task: string
+}
+
+export function renderChainCall(chain: CallItem[], scope: AgentScope | undefined, theme: Theme): Text {
+  let text = theme.fg('toolTitle', theme.bold('subagent ')) + theme.fg('accent', `chain (${chain.length} steps)`) + scopeTag(scope, theme)
+  for (let i = 0; i < Math.min(chain.length, 3); i++) {
+    const step = chain[i]
+    // Clean up {previous} placeholder for display
+    const cleanTask = step.task.replaceAll('{previous}', '').trim()
+    const preview = cleanTask.length > 40 ? `${cleanTask.slice(0, 40)}...` : cleanTask
+    const stepNumber = theme.fg('muted', `${i + 1}.`)
+    const stepLabel = theme.fg('accent', step.agent) + theme.fg('dim', ` ${preview}`)
+    text += `\n  ${stepNumber} ${stepLabel}`
+  }
+  if (chain.length > 3) {
+    const more = theme.fg('muted', `... +${chain.length - 3} more`)
+    text += `\n  ${more}`
+  }
+  return new Text(text, 0, 0)
+}
+
+export function renderParallelCall(tasks: CallItem[], scope: AgentScope | undefined, theme: Theme): Text {
+  let text = theme.fg('toolTitle', theme.bold('subagent ')) + theme.fg('accent', `parallel (${tasks.length} tasks)`) + scopeTag(scope, theme)
+  for (const t of tasks.slice(0, 3)) {
+    const preview = t.task.length > 40 ? `${t.task.slice(0, 40)}...` : t.task
+    const taskLabel = theme.fg('accent', t.agent) + theme.fg('dim', ` ${preview}`)
+    text += `\n  ${taskLabel}`
+  }
+  if (tasks.length > 3) {
+    const more = theme.fg('muted', `... +${tasks.length - 3} more`)
+    text += `\n  ${more}`
+  }
+  return new Text(text, 0, 0)
+}
+
+const scopeTag = (scope: AgentScope | undefined, theme: Theme): string => (scope ? theme.fg('muted', ` [${scope}]`) : '')
+
+export function renderSingleCall(agent: string | undefined, task: string | undefined, scope: AgentScope | undefined, theme: Theme): Text {
+  const agentName = agent || '...'
+  let preview = '...'
+  if (task) preview = task.length > 60 ? `${task.slice(0, 60)}...` : task
+  let text = theme.fg('toolTitle', theme.bold('subagent ')) + theme.fg('accent', agentName) + scopeTag(scope, theme)
+  text += `\n  ${theme.fg('dim', preview)}`
+  return new Text(text, 0, 0)
+}
+
+type MarkdownTheme = ReturnType<typeof getMarkdownTheme>
+
+function aggregateUsage(results: SingleResult[]) {
+  const total = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 }
+  for (const r of results) {
+    total.input += r.usage.input
+    total.output += r.usage.output
+    total.cacheRead += r.usage.cacheRead
+    total.cacheWrite += r.usage.cacheWrite
+    total.cost += r.usage.cost
+    total.turns += r.usage.turns
+  }
+  return total
+}
+
+function renderDisplayItems(items: DisplayItem[], expanded: boolean, theme: Theme, limit?: number): string {
+  const toShow = limit ? items.slice(-limit) : items
+  const skipped = limit && items.length > limit ? items.length - limit : 0
+  let text = ''
+  if (skipped > 0) text += theme.fg('muted', `... ${skipped} earlier items\n`)
+  for (const item of toShow) {
+    if (item.type === 'text') {
+      const preview = expanded ? item.text : item.text.split('\n').slice(0, 3).join('\n')
+      text += `${theme.fg('toolOutput', preview)}\n`
+    } else {
+      text += `${theme.fg('muted', '→ ') + formatToolCall(item.name, item.args, theme.fg.bind(theme))}\n`
+    }
+  }
+  return text.trimEnd()
+}
+
+function addToolCallNodes(container: Container, items: DisplayItem[], theme: Theme): void {
+  for (const item of items) {
+    if (item.type === 'toolCall') {
+      container.addChild(new Text(theme.fg('muted', '→ ') + formatToolCall(item.name, item.args, theme.fg.bind(theme)), 0, 0))
+    }
+  }
+}
+
+function addTotalUsage(container: Container, results: SingleResult[], theme: Theme): void {
+  const usageStr = formatUsageStats(aggregateUsage(results))
+  if (usageStr) {
+    container.addChild(new Spacer(1))
+    const totalLine = theme.fg('dim', `Total: ${usageStr}`)
+    container.addChild(new Text(totalLine, 0, 0))
+  }
+}
+
+function renderSingleExpanded(r: SingleResult, isError: boolean, icon: string, theme: Theme, mdTheme: MarkdownTheme): Container {
+  const container = new Container()
+  const source = theme.fg('muted', ` (${r.agentSource})`)
+  let header = `${icon} ${theme.fg('toolTitle', theme.bold(r.agent))}${source}`
+  if (isError && r.stopReason) {
+    const reason = theme.fg('error', `[${r.stopReason}]`)
+    header += ` ${reason}`
+  }
+  container.addChild(new Text(header, 0, 0))
+  if (isError && r.errorMessage) container.addChild(new Text(theme.fg('error', `Error: ${r.errorMessage}`), 0, 0))
+  container.addChild(new Spacer(1))
+  container.addChild(new Text(theme.fg('muted', '─── Task ───'), 0, 0))
+  container.addChild(new Text(theme.fg('dim', r.task), 0, 0))
+  container.addChild(new Spacer(1))
+  container.addChild(new Text(theme.fg('muted', '─── Output ───'), 0, 0))
+
+  const displayItems = getDisplayItems(r.messages)
+  const finalOutput = getFinalOutput(r.messages)
+  if (displayItems.length === 0 && !finalOutput) {
+    container.addChild(new Text(theme.fg('muted', '(no output)'), 0, 0))
+  } else {
+    addToolCallNodes(container, displayItems, theme)
+    if (finalOutput) {
+      container.addChild(new Spacer(1))
+      container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme))
+    }
+  }
+
+  const usageStr = formatUsageStats(r.usage, r.model)
+  if (usageStr) {
+    container.addChild(new Spacer(1))
+    container.addChild(new Text(theme.fg('dim', usageStr), 0, 0))
+  }
+  return container
+}
+
+function renderSingleCollapsed(r: SingleResult, isError: boolean, icon: string, theme: Theme, expanded: boolean): Text {
+  const displayItems = getDisplayItems(r.messages)
+  const source = theme.fg('muted', ` (${r.agentSource})`)
+  let text = `${icon} ${theme.fg('toolTitle', theme.bold(r.agent))}${source}`
+  if (isError && r.stopReason) {
+    const reason = theme.fg('error', `[${r.stopReason}]`)
+    text += ` ${reason}`
+  }
+  if (isError && r.errorMessage) {
+    const errorLine = theme.fg('error', `Error: ${r.errorMessage}`)
+    text += `\n${errorLine}`
+  } else if (displayItems.length === 0) text += `\n${theme.fg('muted', '(no output)')}`
+  else {
+    text += `\n${renderDisplayItems(displayItems, expanded, theme, COLLAPSED_ITEM_COUNT)}`
+    if (displayItems.length > COLLAPSED_ITEM_COUNT) text += `\n${theme.fg('muted', '(Ctrl+O to expand)')}`
+  }
+  const usageStr = formatUsageStats(r.usage, r.model)
+  if (usageStr) text += `\n${theme.fg('dim', usageStr)}`
+  return new Text(text, 0, 0)
+}
+
+export function renderSingleResult(r: SingleResult, expanded: boolean, theme: Theme, mdTheme: MarkdownTheme): Container | Text {
+  const isError = r.exitCode !== 0 || r.stopReason === 'error' || r.stopReason === 'aborted'
+  const icon = isError ? theme.fg('error', '✗') : theme.fg('success', '✓')
+  if (expanded) return renderSingleExpanded(r, isError, icon, theme, mdTheme)
+  return renderSingleCollapsed(r, isError, icon, theme, expanded)
+}
+
+function renderChainExpanded(results: SingleResult[], successCount: number, icon: string, theme: Theme, mdTheme: MarkdownTheme): Container {
+  const container = new Container()
+  const summary = theme.fg('accent', `${successCount}/${results.length} steps`)
+  container.addChild(new Text(`${icon} ${theme.fg('toolTitle', theme.bold('chain '))}${summary}`, 0, 0))
+
+  for (const r of results) {
+    const rIcon = r.exitCode === 0 ? theme.fg('success', '✓') : theme.fg('error', '✗')
+    const displayItems = getDisplayItems(r.messages)
+    const finalOutput = getFinalOutput(r.messages)
+
+    container.addChild(new Spacer(1))
+    const stepLabel = theme.fg('muted', `─── Step ${r.step}: `) + theme.fg('accent', r.agent)
+    container.addChild(new Text(`${stepLabel} ${rIcon}`, 0, 0))
+    container.addChild(new Text(theme.fg('muted', 'Task: ') + theme.fg('dim', r.task), 0, 0))
+
+    addToolCallNodes(container, displayItems, theme)
+
+    if (finalOutput) {
+      container.addChild(new Spacer(1))
+      container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme))
+    }
+
+    const stepUsage = formatUsageStats(r.usage, r.model)
+    if (stepUsage) container.addChild(new Text(theme.fg('dim', stepUsage), 0, 0))
+  }
+
+  addTotalUsage(container, results, theme)
+  return container
+}
+
+function renderChainCollapsed(results: SingleResult[], successCount: number, icon: string, theme: Theme, expanded: boolean): Text {
+  const summary = theme.fg('accent', `${successCount}/${results.length} steps`)
+  let text = `${icon} ${theme.fg('toolTitle', theme.bold('chain '))}${summary}`
+  for (const r of results) {
+    const rIcon = r.exitCode === 0 ? theme.fg('success', '✓') : theme.fg('error', '✗')
+    const displayItems = getDisplayItems(r.messages)
+    const stepLabel = theme.fg('muted', `─── Step ${r.step}: `)
+    text += `\n\n${stepLabel}${theme.fg('accent', r.agent)} ${rIcon}`
+    if (displayItems.length === 0) text += `\n${theme.fg('muted', '(no output)')}`
+    else text += `\n${renderDisplayItems(displayItems, expanded, theme, 5)}`
+  }
+  const usageStr = formatUsageStats(aggregateUsage(results))
+  if (usageStr) {
+    const totalLine = theme.fg('dim', `Total: ${usageStr}`)
+    text += `\n\n${totalLine}`
+  }
+  text += `\n${theme.fg('muted', '(Ctrl+O to expand)')}`
+  return new Text(text, 0, 0)
+}
+
+export function renderChainResult(results: SingleResult[], expanded: boolean, theme: Theme, mdTheme: MarkdownTheme): Container | Text {
+  const successCount = results.filter((r) => r.exitCode === 0).length
+  const icon = successCount === results.length ? theme.fg('success', '✓') : theme.fg('error', '✗')
+  if (expanded) return renderChainExpanded(results, successCount, icon, theme, mdTheme)
+  return renderChainCollapsed(results, successCount, icon, theme, expanded)
+}
+
+function renderParallelExpanded(results: SingleResult[], icon: string, status: string, theme: Theme, mdTheme: MarkdownTheme): Container {
+  const container = new Container()
+  const summary = theme.fg('accent', status)
+  container.addChild(new Text(`${icon} ${theme.fg('toolTitle', theme.bold('parallel '))}${summary}`, 0, 0))
+
+  for (const r of results) {
+    const rIcon = r.exitCode === 0 ? theme.fg('success', '✓') : theme.fg('error', '✗')
+    const displayItems = getDisplayItems(r.messages)
+    const finalOutput = getFinalOutput(r.messages)
+
+    container.addChild(new Spacer(1))
+    const agentLabel = theme.fg('muted', '─── ') + theme.fg('accent', r.agent)
+    container.addChild(new Text(`${agentLabel} ${rIcon}`, 0, 0))
+    container.addChild(new Text(theme.fg('muted', 'Task: ') + theme.fg('dim', r.task), 0, 0))
+
+    addToolCallNodes(container, displayItems, theme)
+
+    if (finalOutput) {
+      container.addChild(new Spacer(1))
+      container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme))
+    }
+
+    const taskUsage = formatUsageStats(r.usage, r.model)
+    if (taskUsage) container.addChild(new Text(theme.fg('dim', taskUsage), 0, 0))
+  }
+
+  addTotalUsage(container, results, theme)
+  return container
+}
+
+function renderParallelCollapsed(results: SingleResult[], icon: string, status: string, theme: Theme, expanded: boolean, isRunning: boolean): Text {
+  const summary = theme.fg('accent', status)
+  let text = `${icon} ${theme.fg('toolTitle', theme.bold('parallel '))}${summary}`
+  for (const r of results) {
+    let rIcon = theme.fg('error', '✗')
+    if (r.exitCode === -1) rIcon = theme.fg('warning', '⏳')
+    else if (r.exitCode === 0) rIcon = theme.fg('success', '✓')
+    const displayItems = getDisplayItems(r.messages)
+    text += `\n\n${theme.fg('muted', '─── ')}${theme.fg('accent', r.agent)} ${rIcon}`
+    if (displayItems.length === 0) {
+      const placeholder = r.exitCode === -1 ? '(running...)' : '(no output)'
+      text += `\n${theme.fg('muted', placeholder)}`
+    } else text += `\n${renderDisplayItems(displayItems, expanded, theme, 5)}`
+  }
+  if (!isRunning) {
+    const usageStr = formatUsageStats(aggregateUsage(results))
+    if (usageStr) {
+      const totalLine = theme.fg('dim', `Total: ${usageStr}`)
+      text += `\n\n${totalLine}`
+    }
+  }
+  if (!expanded) text += `\n${theme.fg('muted', '(Ctrl+O to expand)')}`
+  return new Text(text, 0, 0)
+}
+
+export function renderParallelResult(results: SingleResult[], expanded: boolean, theme: Theme, mdTheme: MarkdownTheme): Container | Text {
+  const running = results.filter((r) => r.exitCode === -1).length
+  const successCount = results.filter((r) => r.exitCode === 0).length
+  const failCount = results.filter((r) => r.exitCode > 0).length
+  const isRunning = running > 0
+
+  let icon = theme.fg('success', '✓')
+  if (isRunning) icon = theme.fg('warning', '⏳')
+  else if (failCount > 0) icon = theme.fg('warning', '◐')
+
+  let status = `${successCount}/${results.length} tasks`
+  if (isRunning) status = `${successCount + failCount}/${results.length} done, ${running} running`
+
+  if (expanded && !isRunning) return renderParallelExpanded(results, icon, status, theme, mdTheme)
+  return renderParallelCollapsed(results, icon, status, theme, expanded, isRunning)
+}

package/extensions/subagent/run.ts

@@ -0,0 +1,375 @@
+/**
+ * Running one child agent: spawn a `pi` process, parse its JSON event stream back
+ * into messages and usage, and tear the child down on abort or a maxTurns cap.
+ *
+ * The only place in the subagent extension that owns a process, a temp file or a
+ * worktree; everything about how the child was configured lives in child.ts.
+ */
+
+import { spawn } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+
+import type { AgentToolResult } from '@earendil-works/pi-agent-core'
+import type { Message } from '@earendil-works/pi-ai'
+import { withFileMutationQueue } from '@earendil-works/pi-coding-agent'
+
+import { runSubagentStartHooks } from '../internal/subagent-hooks.js'
+import { type AgentConfig, resolveModelAlias } from './agents.js'
+import { agentHooksEnv, agentInvocationArgs, agentMemoryPromptSection, childPromptBody, taskWithStartContext, unresolvedToolsError, withMemoryTools } from './child.js'
+import { getFinalOutput } from './render.js'
+import type { SingleResult, SubagentDetails } from './types.js'
+import { type AgentWorktree, cleanupAgentWorktree, createAgentWorktree } from './worktree.js'
+export async function writePromptToTempFile(agentName: string, prompt: string): Promise<{ dir: string; filePath: string }> {
+  const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'pi-subagent-'))
+  const safeName = agentName.replace(/[^\w.-]+/g, '_')
+  const filePath = path.join(tmpDir, `prompt-${safeName}.md`)
+  await withFileMutationQueue(filePath, async () => {
+    await fs.promises.writeFile(filePath, prompt, { encoding: 'utf-8', mode: 0o600 })
+  })
+  return { dir: tmpDir, filePath }
+}
+
+/** Exported as a test seam: the fallbacks only fire in packaged distributions
+ * (bun single-file, compiled binary), which no CI run reaches naturally. */
+export function getPiInvocation(args: string[]): { command: string; args: string[] } {
+  const currentScript = process.argv[1]
+  const isBunVirtualScript = currentScript?.startsWith('/$bunfs/root/')
+  if (currentScript && !isBunVirtualScript && fs.existsSync(currentScript)) {
+    return { command: process.execPath, args: [currentScript, ...args] }
+  }
+
+  const execName = path.basename(process.execPath).toLowerCase()
+  const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName)
+  if (!isGenericRuntime) {
+    return { command: process.execPath, args }
+  }
+
+  return { command: 'pi', args }
+}
+
+export type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void
+
+type AssistantMessage = Extract<Message, { role: 'assistant' }>
+
+function accumulateAssistantMessage(result: SingleResult, msg: AssistantMessage): void {
+  result.usage.turns++
+  const usage = msg.usage
+  if (usage) {
+    result.usage.input += usage.input || 0
+    result.usage.output += usage.output || 0
+    result.usage.cacheRead += usage.cacheRead || 0
+    result.usage.cacheWrite += usage.cacheWrite || 0
+    result.usage.cost += usage.cost?.total || 0
+    result.usage.contextTokens = usage.totalTokens || 0
+  }
+  if (!result.model && msg.model) result.model = msg.model
+  if (msg.stopReason) result.stopReason = msg.stopReason
+  if (msg.errorMessage) result.errorMessage = msg.errorMessage
+}
+
+export interface RunAgentOptions {
+  defaultCwd: string
+  agents: AgentConfig[]
+  agentName: string
+  task: string
+  cwd?: string
+  step?: number
+  signal?: AbortSignal
+  onUpdate?: OnUpdateCallback
+  makeDetails: (results: SingleResult[]) => SubagentDetails
+  onPhase?: SubagentPhaseSink
+  /** The child's run id, set by the wrapper so the spawn env can carry it. */
+  agentId?: string
+  /** SubagentStart hook context, injected ahead of the child's first prompt. */
+  startContexts?: string[]
+  /** Skill directories to preload from, resolved where project trust is known. */
+  skillRoots?: string[]
+  /** Models this user can actually run, for resolving a tier alias. */
+  availableModels?: ReadonlyArray<{ id: string }>
+  /** Whether repo-controlled config (a project/local agent memory store) may be read. */
+  projectApproved?: boolean
+}
+
+/** Publishes a child run's start/stop for the hooks extension's SubagentStart/Stop.
+ * The stop carries the run's final assistant text, which Claude's SubagentStop
+ * delivers as last_assistant_message. */
+export type SubagentPhaseSink = (phase: 'start' | 'stop', agentType: string, agentId: string, lastAssistantMessage?: string) => void
+
+/** Append a note to the final assistant message so it rides the run's normal
+ * output; stderr when there is none. */
+function appendResultNote(result: SingleResult, note: string): void {
+  for (let i = result.messages.length - 1; i >= 0; i--) {
+    const msg = result.messages[i]
+    if (msg.role === 'assistant') {
+      msg.content.push({ type: 'text', text: note })
+      return
+    }
+  }
+  result.stderr = result.stderr ? `${result.stderr}\n${note}` : note
+}
+
+/** Tell the parent where a kept worktree lives. */
+function appendWorktreeNote(result: SingleResult, worktree: AgentWorktree): void {
+  appendResultNote(result, `[isolation: worktree kept at ${worktree.dir} (branch ${worktree.branch}); the agent's changes live there]`)
+}
+
+/** Claude marks a maxTurns-capped run's output as partial; the note rides the
+ * final assistant message like the worktree note, so the parent model sees it
+ * with the output. A no-op for uncapped runs. */
+function appendPartialNote(result: SingleResult): void {
+  if (result.partial) appendResultNote(result, '[Output is partial: the subagent stopped at its maxTurns limit.]')
+}
+
+export async function runSingleAgent(options: RunAgentOptions): Promise<SingleResult> {
+  const agent = options.agents.find((a) => a.name === options.agentName)
+  if (!agent) return runSingleAgentInner(options)
+  // A refused launch (Claude's zero-tools error) never starts, so no
+  // SubagentStart/Stop pair fires for it.
+  const toolsError = unresolvedToolsError(agent)
+  if (toolsError) {
+    return {
+      agent: agent.name,
+      agentSource: agent.source,
+      task: options.task,
+      exitCode: 1,
+      messages: [],
+      stderr: toolsError,
+      usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+      step: options.step,
+    }
+  }
+  const agentId = `fg-${randomUUID().slice(0, 8)}`
+  // SubagentStart hooks run pre-spawn through the seam so their additionalContext
+  // reaches the child before its first prompt.
+  const startContexts = await runSubagentStartHooks(agent.name, agentId)
+  options.onPhase?.('start', agent.name, agentId)
+  let result: SingleResult | undefined
+  try {
+    result = await runSingleAgentInner({ ...options, agentId, startContexts })
+    return result
+  } finally {
+    options.onPhase?.('stop', agent.name, agentId, result ? getFinalOutput(result.messages) || undefined : undefined)
+  }
+}
+
+async function runSingleAgentInner(options: RunAgentOptions): Promise<SingleResult> {
+  const { defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails } = options
+  const agent = agents.find((a) => a.name === agentName)
+
+  if (!agent) {
+    const available = agents.map((a) => `"${a.name}"`).join(', ') || 'none'
+    return {
+      agent: agentName,
+      agentSource: 'unknown',
+      task,
+      exitCode: 1,
+      messages: [],
+      stderr: `Unknown agent: "${agentName}". Available agents: ${available}.`,
+      usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+      step,
+    }
+  }
+
+  const runCwd = cwd ?? defaultCwd
+  // Claude's isolation: worktree gives the child an isolated copy of the repository.
+  // A boundary that cannot be created fails the run: running against the real
+  // checkout would silently drop the isolation the agent declared.
+  let worktree: AgentWorktree | undefined
+  if (agent.isolation === 'worktree') {
+    const created = await createAgentWorktree(runCwd, agent.name)
+    if ('error' in created) {
+      return {
+        agent: agentName,
+        agentSource: agent.source,
+        task,
+        exitCode: 1,
+        messages: [],
+        stderr: `isolation: worktree could not be created: ${created.error}`,
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+        step,
+      }
+    }
+    worktree = created
+  }
+  // Project/local memory is anchored at the SESSION project (defaultCwd), not the
+  // model-supplied runCwd: projectApproved gates the session's repo, so anchoring the
+  // store on a different (possibly unapproved) cwd would inject that repo's memory as
+  // trusted. User-scope memory ignores cwd, so this is safe for it too.
+  const memorySection = agentMemoryPromptSection(agent, defaultCwd, options.projectApproved ?? false)
+  // A memory-enabled child must be able to manage its store files even when the
+  // agent pins a tools allowlist.
+  const invocationAgent = memorySection ? { ...agent, tools: withMemoryTools(agent.tools) } : agent
+  const args = agentInvocationArgs(invocationAgent, resolveModelAlias(agent.modelAlias, options.availableModels ?? []))
+
+  let tmpPromptDir: string | null = null
+  let tmpPromptPath: string | null = null
+
+  const currentResult: SingleResult = {
+    agent: agentName,
+    agentSource: agent.source,
+    task,
+    exitCode: 0,
+    messages: [],
+    stderr: '',
+    usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+    model: agent.model,
+    step,
+  }
+
+  const emitUpdate = () => {
+    if (onUpdate) {
+      onUpdate({
+        content: [{ type: 'text', text: getFinalOutput(currentResult.messages) || '(running...)' }],
+        details: makeDetails([currentResult]),
+      })
+    }
+  }
+
+  try {
+    const promptBody = childPromptBody(agent, options.skillRoots ?? [], memorySection)
+    if (promptBody.trim()) {
+      const tmp = await writePromptToTempFile(agent.name, promptBody)
+      tmpPromptDir = tmp.dir
+      tmpPromptPath = tmp.filePath
+      // Claude: the agent body IS the subagent's system prompt, replacing the
+      // default, not an addition to it (--system-prompt reads a file path too).
+      args.push('--system-prompt', tmpPromptPath)
+    }
+
+    args.push(taskWithStartContext(task, options.startContexts ?? []))
+    let wasAborted = false
+
+    const exitCode = await new Promise<number>((resolve) => {
+      const invocation = getPiInvocation(args)
+      const proc = spawn(invocation.command, invocation.args, {
+        cwd: worktree?.dir ?? runCwd,
+        shell: false,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        // Its own group, so an abort reaches grandchildren too: killing only the
+        // direct child orphans a build or dev server the agent started.
+        detached: true,
+        // The marker lets the child's subagent tool refuse to nest further.
+        env: { ...process.env, PI_CODE_SUBAGENT: '1', ...agentHooksEnv(agent, options.agentId ?? '') },
+      })
+      let buffer = ''
+      let assistantTurns = 0
+
+      const processLine = (line: string) => {
+        if (!line.trim()) return
+        let event: { type?: string; message?: unknown }
+        try {
+          event = JSON.parse(line)
+        } catch {
+          return
+        }
+
+        if (!event.message) return
+
+        if (event.type === 'message_end') {
+          const msg = event.message as Message
+          currentResult.messages.push(msg)
+          if (msg.role === 'assistant') {
+            accumulateAssistantMessage(currentResult, msg)
+            assistantTurns++
+            // Claude's maxTurns cap: end the child at the turn boundary once it has
+            // produced its Nth turn, so the collected output is kept and no turn is
+            // cut; the returned output is marked partial, as Claude documents.
+            if (agent.maxTurns && assistantTurns >= agent.maxTurns) {
+              currentResult.partial = true
+              killGroup('SIGTERM')
+            }
+          }
+          emitUpdate()
+        } else if (event.type === 'tool_result_end') {
+          currentResult.messages.push(event.message as Message)
+          emitUpdate()
+        }
+      }
+
+      let killTimer: ReturnType<typeof setTimeout> | undefined
+      let onAbort: (() => void) | undefined
+      const cleanup = () => {
+        if (killTimer) clearTimeout(killTimer)
+        if (onAbort && signal) signal.removeEventListener('abort', onAbort)
+      }
+
+      proc.stdout.on('data', (data) => {
+        buffer += data.toString()
+        const lines = buffer.split('\n')
+        buffer = lines.pop() || ''
+        for (const line of lines) processLine(line)
+      })
+      proc.stdout.on('error', () => {})
+
+      proc.stderr.on('data', (data) => {
+        currentResult.stderr += data.toString()
+      })
+      proc.stderr.on('error', () => {})
+
+      proc.on('close', (code) => {
+        cleanup()
+        if (buffer.trim()) processLine(buffer)
+        resolve(code ?? 0)
+      })
+
+      proc.on('error', (error: Error) => {
+        cleanup()
+        // A child that never started leaves no stdout and no stderr, so this message is the
+        // only diagnostic; without it the failure reads as "(no output)".
+        if (!currentResult.stderr) currentResult.stderr = error.message
+        resolve(1)
+      })
+
+      const killGroup = (sig: NodeJS.Signals): void => {
+        try {
+          // A child that never spawned has no pid and no group; the direct kill is all there is.
+          if (proc.pid) process.kill(-proc.pid, sig)
+          else proc.kill(sig)
+        } catch {
+          try {
+            proc.kill(sig)
+          } catch {
+            /* already gone */
+          }
+        }
+      }
+      if (signal) {
+        onAbort = () => {
+          wasAborted = true
+          killGroup('SIGTERM')
+          // proc.killed only reports that the signal was sent, not that the child died. Escalate
+          // on a timer that the 'close' handler clears once the child has actually exited.
+          killTimer = setTimeout(() => killGroup('SIGKILL'), 5000)
+        }
+        if (signal.aborted) onAbort()
+        else signal.addEventListener('abort', onAbort, { once: true })
+      }
+    })
+
+    currentResult.exitCode = exitCode
+    if (wasAborted) throw new Error('Subagent was aborted')
+    appendPartialNote(currentResult)
+    return currentResult
+  } finally {
+    // Cleanup runs on abort too: it only removes a pristine worktree, so an
+    // interrupted agent's changes always survive.
+    if (worktree && (await cleanupAgentWorktree(runCwd, worktree)) === 'kept') {
+      appendWorktreeNote(currentResult, worktree)
+    }
+    if (tmpPromptPath)
+      try {
+        fs.unlinkSync(tmpPromptPath)
+      } catch {
+        /* ignore */
+      }
+    if (tmpPromptDir)
+      try {
+        fs.rmdirSync(tmpPromptDir)
+      } catch {
+        /* ignore */
+      }
+  }
+}