@tduyng/pi-subagent 0.0.0-stage → 0.0.2

package/src/subagent/index.ts

@@ -0,0 +1,853 @@
+import { execFileSync } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { appendFileSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs'
+import { mkdir } from 'node:fs/promises'
+import * as path from 'node:path'
+
+import type { JsonValue, Model } from '@earendil-works/pi-ai'
+import {
+    DEFAULT_MAX_BYTES,
+    DEFAULT_MAX_LINES,
+    DefaultResourceLoader,
+    getAgentDir,
+    truncateHead,
+    type ExtensionAPI,
+    type ExtensionContext
+} from '@earendil-works/pi-coding-agent'
+import { Text, isKeyRelease, matchesKey } from '@earendil-works/pi-tui'
+import { type Infer, type JSONSchema, Validator } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+
+import { createChildModelRuntime } from '../lib/child-runtime.js'
+import { loadAgents, parseModelName, toThinking } from './agent.js'
+import { drivePrompt } from './drive.js'
+import { claimRun, findRunForTask, saveRun, syncRecord, type DurableRun, type DurableTask } from './durable.js'
+import { recoverRuns, resumeTask } from './recover.js'
+import { createChildSession } from './session.js'
+import { normalizeJsonSchema } from './structured.js'
+import {
+    acquirePermit,
+    changedPaths,
+    createWorktree,
+    findDuplicateTask,
+    gitStatus,
+    failureReason,
+    releasePermit,
+    resolveMaxTurns,
+    resolveTimeoutMs,
+    salvageFromMessages,
+    salvageOutput,
+    validateCwd,
+    worktreeBranch,
+    MIN_TIMEOUT_MS
+} from './helpers.js'
+import {
+    countByStatus,
+    extractForkText,
+    findLastAssistant,
+    formatDuration,
+    partialText,
+    resultText,
+    statusIcon,
+    taskHeadline,
+    toLabel
+} from './format.js'
+import { dismissTask, liveSessions, nextExpiryAt, registry, roster } from './state.js'
+import {
+    DEFAULT_THINKING,
+    EMIT_INTERVAL_MS,
+    MAX_CONCURRENT,
+    MAX_TASKS,
+    RUNS_DIR,
+    WIDGET_KEY,
+    type RunDetails,
+    type RunStatus,
+    type TaskDetails,
+    type TaskSpec,
+    type ThinkingLevel
+} from './types.js'
+import { SubagentViewer, widgetLines } from './viewer.js'
+
+export { parseFrontmatter, loadAgentsFrom, parseModelName } from './agent.js'
+
+const MAX_FORK_CONTEXT_CHARS = 120_000
+const RUN_SAVE_INTERVAL_MS = 5_000
+const RUN_RETENTION_MS = 7 * 24 * 60 * 60 * 1000
+
+/** The child bills to the parent's session, and `/cost` reads this line to say so. */
+function recordOverhead(
+    sessionId: string,
+    purpose: string,
+    usage: { input: number; output: number; cost: number }
+): void {
+    try {
+        appendFileSync(
+            path.join(getAgentDir(), 'overhead.jsonl'),
+            `${JSON.stringify({
+                at: Date.now(),
+                extension: 'subagent',
+                sessionId,
+                purpose,
+                input: usage.input,
+                output: usage.output,
+                costUsd: usage.cost
+            })}\n`,
+            'utf8'
+        )
+    } catch {}
+}
+
+function removeWorktree(worktree: string): void {
+    try {
+        const repo = path.dirname(
+            execFileSync('git', ['-C', worktree, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
+                encoding: 'utf8'
+            }).trim()
+        )
+        execFileSync('git', ['-C', repo, 'worktree', 'remove', '--force', worktree], { stdio: 'ignore' })
+        execFileSync('git', ['-C', repo, 'branch', '-d', worktreeBranch(worktree)], { stdio: 'ignore' })
+    } catch {
+        rmSync(worktree, { recursive: true, force: true })
+    }
+}
+
+function removeStaleRunDirectories(currentSessionId: string): void {
+    const root = path.join(getAgentDir(), RUNS_DIR)
+    let sessions: string[]
+    try {
+        sessions = readdirSync(root)
+    } catch {
+        return
+    }
+    const now = Date.now()
+    for (const sessionId of sessions) {
+        if (sessionId === currentSessionId) continue
+        const sessionDir = path.join(root, sessionId)
+        try {
+            if (now - statSync(sessionDir).mtimeMs <= RUN_RETENTION_MS) continue
+            for (const task of readdirSync(sessionDir)) {
+                const worktree = path.join(sessionDir, task, 'worktree')
+                if (statSync(worktree, { throwIfNoEntry: false })) removeWorktree(worktree)
+            }
+            rmSync(sessionDir, { recursive: true, force: true })
+        } catch {}
+    }
+}
+
+export interface ChildConfig {
+    model?: string
+    thinking?: ThinkingLevel
+}
+
+const ChildConfigFile = t.object({ model: t.optional(t.string()), thinking: t.optional(t.string()) })
+const isChildConfigFile = new Validator(ChildConfigFile).isValidObject
+
+function readChildConfig(file: string): ChildConfig {
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'))
+        if (!isChildConfigFile(parsed)) return {}
+        return { model: parsed.model?.trim() || undefined, thinking: toThinking(parsed.thinking) }
+    } catch {
+        return {}
+    }
+}
+
+export function defaultChildConfig(agentDir = getAgentDir(), projectDir = process.cwd()): ChildConfig {
+    const agent = readChildConfig(path.join(agentDir, 'subagent.json'))
+    const project = readChildConfig(path.join(projectDir, '.pi', 'subagent.json'))
+    return { model: project.model ?? agent.model, thinking: project.thinking ?? agent.thinking }
+}
+
+export function resolveChildThinking(
+    requested: ThinkingLevel | undefined,
+    profile: ThinkingLevel | undefined,
+    configured: ThinkingLevel | undefined
+): ThinkingLevel {
+    return requested ?? profile ?? configured ?? DEFAULT_THINKING
+}
+
+export function resolveChildModelName(
+    requested: string | undefined,
+    profile: string | undefined,
+    configured: string | undefined
+): string | undefined {
+    return profile || configured || requested?.trim() || undefined
+}
+export { toLabel, extractForkText } from './format.js'
+export {
+    changedPaths,
+    createWorktree,
+    failureReason,
+    resolveMaxTurns,
+    resolveTimeoutMs,
+    worktreeBranch,
+    wrapUpMessage
+} from './helpers.js'
+
+export type { AgentProfile, TaskDetails, RunDetails, ThinkingLevel } from './types.js'
+
+export type LoaderOptions = ConstructorParameters<typeof DefaultResourceLoader>[0]
+
+const TASK_FIELDS = {
+    task: t.string({ description: 'Instructions.' }),
+    agent: t.optional(t.string({ description: 'Profile; omit for scout.' })),
+    cwd: t.optional(t.string()),
+    isolation: t.optional(t.string({ enum: ['worktree'] })),
+    schema: t.optional({
+        ...t.union([t.string(), t.object({}, { additionalProperties: true })]),
+        description: 'Final JSON Schema; call structured_output once.'
+    }),
+    context: t.optional(t.string({ enum: ['fork'] })),
+    resume: t.optional(t.string({ description: 'Resume task id or all.' }))
+}
+
+function undescribed<T extends JSONSchema>(schema: T): T {
+    const clone = Object.defineProperties({}, Object.getOwnPropertyDescriptors(schema))
+    delete (clone as { description?: string }).description
+    return clone as T
+}
+
+export const TASK_ITEM_FIELDS = Object.fromEntries(
+    Object.entries(TASK_FIELDS).map(([name, schema]) => [name, undescribed(schema)])
+) as typeof TASK_FIELDS
+
+const subagentParams = t.object({
+    ...TASK_FIELDS,
+    task: t.optional(TASK_FIELDS.task),
+    tasks: t.optional(
+        t.array(t.object(TASK_ITEM_FIELDS), {
+            description: `Run up to ${MAX_TASKS} children; same fields.`
+        })
+    )
+})
+type SubagentParams = Infer<typeof subagentParams>
+
+export default function subagentExtension(pi: ExtensionAPI): void {
+    let mountedCtx: ExtensionContext | undefined
+    let unregisterInput: (() => void) | undefined
+    let highlightIndex: number | null = null
+    let viewerOpen = false
+    let sweepTimer: ReturnType<typeof setTimeout> | undefined
+
+    function scheduleSweep(): void {
+        if (sweepTimer) clearTimeout(sweepTimer)
+        sweepTimer = undefined
+        const due = nextExpiryAt()
+        if (due === undefined) return
+        sweepTimer = setTimeout(
+            () => {
+                sweepTimer = undefined
+                syncWidget()
+            },
+            Math.max(1_000, due - Date.now())
+        )
+        sweepTimer.unref()
+    }
+
+    function syncWidget(): void {
+        const ctx = mountedCtx
+        if (!ctx?.hasUI) return
+        const items = roster()
+        if (highlightIndex !== null)
+            highlightIndex = items.length === 0 ? null : Math.min(highlightIndex, items.length - 1)
+        ctx.ui.setWidget(WIDGET_KEY, items.length === 0 ? undefined : widgetLines(ctx.ui.theme, highlightIndex))
+        scheduleSweep()
+    }
+
+    async function openViewer(ctx: ExtensionContext, task: TaskDetails): Promise<void> {
+        const session = liveSessions.get(task.id)
+        if (!session) {
+            ctx.ui.notify('That agent session is no longer available.', 'warning')
+            return
+        }
+        viewerOpen = true
+        try {
+            await ctx.ui.custom<void>((tui, theme, _kb, done) => new SubagentViewer(tui, theme, session, task, done))
+        } catch (error) {
+            try {
+                ctx.ui.notify(error instanceof Error ? error.message : String(error), 'error')
+            } catch {}
+        } finally {
+            viewerOpen = false
+        }
+    }
+
+    function createNavHandler(ctx: ExtensionContext) {
+        return (data: string): { consume: boolean } | undefined => {
+            if (isKeyRelease(data) || viewerOpen) return undefined
+            const items = roster()
+
+            if (highlightIndex === null) {
+                if (matchesKey(data, 'down') && items.length > 0 && ctx.ui.getEditorText() === '') {
+                    highlightIndex = 0
+                    syncWidget()
+                    return { consume: true }
+                }
+                return undefined
+            }
+
+            if (matchesKey(data, 'down')) {
+                highlightIndex = Math.min(highlightIndex + 1, items.length - 1)
+                syncWidget()
+                return { consume: true }
+            }
+            if (matchesKey(data, 'up')) {
+                highlightIndex = Math.max(highlightIndex - 1, 0)
+                syncWidget()
+                return { consume: true }
+            }
+            if (matchesKey(data, 'escape')) {
+                highlightIndex = null
+                syncWidget()
+                return { consume: true }
+            }
+            if (matchesKey(data, 'd') || matchesKey(data, 'x')) {
+                const task = items[highlightIndex]
+                if (task) dismissTask(task.id)
+                syncWidget()
+                return { consume: true }
+            }
+            if (matchesKey(data, 'enter')) {
+                const task = items[highlightIndex]
+                highlightIndex = null
+                syncWidget()
+                if (task) void openViewer(ctx, task)
+                return { consume: true }
+            }
+            highlightIndex = null
+            syncWidget()
+            return undefined
+        }
+    }
+
+    pi.on('session_start', async (_event, ctx) => {
+        setTimeout(() => removeStaleRunDirectories(ctx.sessionManager.getSessionId()), 0).unref?.()
+        if (ctx.hasUI) {
+            mountedCtx = ctx
+            unregisterInput ??= ctx.ui.onTerminalInput(createNavHandler(ctx))
+            syncWidget()
+        }
+        void recoverRuns({ pi, ctx, onEmit: syncWidget }).catch(() => {})
+    })
+
+    pi.on('session_shutdown', async () => {
+        if (sweepTimer) clearTimeout(sweepTimer)
+        sweepTimer = undefined
+        unregisterInput?.()
+        unregisterInput = undefined
+        mountedCtx?.ui.setWidget(WIDGET_KEY, undefined)
+        mountedCtx = undefined
+        for (const session of liveSessions.values()) session.dispose()
+        liveSessions.clear()
+        registry.length = 0
+    })
+
+    pi.registerTool({
+        name: 'subagent',
+        label: 'Subagent',
+        description:
+            'Delegate read-only analysis to a child Pi session, on a cheap model: search, reading code and docs, research. ' +
+            'Keep implementation, debugging, builds and lint in the parent. ' +
+            'No profile has web access, so run web_search and web_fetch yourself in the parent; hand a scout text already saved to disk. ' +
+            'Use `schema` for structured output, `resume` for failed children, including ones kept from a crashed session. ' +
+            `Up to ${MAX_TASKS} tasks, ${MAX_CONCURRENT} concurrent.`,
+        promptSnippet: 'delegate bulk reads, parallel or worktree-isolated work to a child session',
+        exposure: 'direct',
+        namespace: {
+            name: 'subagent',
+            description: 'Delegation to a child Pi session, by profile, with worktree isolation.'
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        executionMode: 'parallel',
+        parameters: subagentParams,
+
+        async execute(_toolCallId, params: SubagentParams, signal, onUpdate, ctx) {
+            const resumeKey = (params.resume as string | undefined)?.trim() || undefined
+            const inputs = resumeKey
+                ? []
+                : params.tasks?.length
+                  ? params.tasks
+                  : params.task
+                    ? [{ ...params, task: params.task }]
+                    : []
+            if (inputs.length === 0 && !resumeKey) throw new Error('Pass "task", "tasks", or "resume".')
+            if (!resumeKey && inputs.length > MAX_TASKS)
+                throw new Error(`At most ${MAX_TASKS} tasks per subagent call.`)
+            const duplicate = findDuplicateTask(inputs.map((input) => input.task))
+            if (duplicate) {
+                throw new Error(
+                    `Tasks ${duplicate.first + 1} and ${duplicate.second + 1} are the same request. Drop one, or give each a distinct part of the job.`
+                )
+            }
+
+            if (!ctx.model)
+                throw new Error('No model is active in this session, so there is nothing to run children with.')
+            const activeModel = ctx.model
+
+            const agents = loadAgents(ctx.cwd)
+
+            const runId = randomUUID()
+            const runDir = path.join(getAgentDir(), RUNS_DIR, ctx.sessionManager.getSessionId(), runId)
+            const startedAt = Date.now()
+
+            const config = defaultChildConfig()
+            const specs: TaskSpec[] = inputs.map((raw, index) => {
+                const input = raw as typeof raw & {
+                    label?: string
+                    thinking?: ThinkingLevel
+                    maxTurns?: number
+                    model?: string
+                    timeoutMs?: number
+                }
+                if (!input.task.trim()) throw new Error(`Task ${index + 1} must not be empty.`)
+                const agentName = input.agent?.trim() || 'scout'
+                const agent = agents.get(agentName)
+                if (!agent) {
+                    throw new Error(`Unknown agent "${agentName}". Known: ${[...agents.keys()].join(', ') || 'none'}`)
+                }
+                const thinking = resolveChildThinking(input.thinking, agent?.thinking, config.thinking)
+                let childModel: Model<any> | undefined
+                const modelName = resolveChildModelName(input.model, agent?.model, config.model)
+                if (modelName) {
+                    const parsed = parseModelName(modelName)
+                    if (!parsed) throw new Error(`Invalid model "${modelName}"; use provider/model-id.`)
+                    childModel = ctx.modelRegistry.find(parsed.provider, parsed.id)
+                    if (!childModel)
+                        throw new Error(`Model not found: ${modelName}. Check /model for registered providers.`)
+                }
+                const timeoutMs =
+                    resolveTimeoutMs(input.timeoutMs) ?? resolveTimeoutMs(agent?.maxExecutionTimeMs) ?? MIN_TIMEOUT_MS
+                return {
+                    index,
+                    id: `${runId}:${index}`,
+                    label: input.label?.trim()
+                        ? toLabel(input.label, index)
+                        : toLabel(agent?.name ?? input.task, index),
+                    task: input.task,
+                    agent,
+                    cwd: path.resolve(ctx.cwd, input.cwd?.trim() || '.'),
+                    isolation: input.isolation === 'worktree' ? 'worktree' : undefined,
+                    dir: path.join(runDir, `task-${index + 1}`),
+                    thinking,
+                    model: childModel,
+                    timeoutMs,
+                    maxTurns: resolveMaxTurns(input.maxTurns as number | undefined, agent?.maxTurns),
+                    forkContext: input.context === 'fork',
+                    schema: normalizeJsonSchema(input.schema)
+                }
+            })
+
+            const writers = specs.filter((spec) =>
+                spec.agent?.tools.some((tool) => tool === 'write' || tool === 'edit')
+            )
+            if (writers.length > 1) {
+                throw new Error('Parallel write-capable subagents are disabled. Run one writer at a time.')
+            }
+
+            const tasks: TaskDetails[] = specs.map((spec) => ({
+                id: spec.id,
+                index: spec.index,
+                label: spec.label,
+                agent: spec.agent?.name,
+                status: 'queued',
+                cwd: spec.cwd,
+                provider: (spec.model ?? activeModel).provider,
+                model: (spec.model ?? activeModel).id,
+                thinking: spec.thinking,
+                color: spec.agent?.color,
+                forkContext: spec.forkContext,
+                hasSchema: spec.schema !== undefined,
+                maxTurns: spec.maxTurns,
+                partial: undefined,
+                structured: undefined
+            }))
+            registry.push(...tasks)
+
+            const snapshot = (status: RunStatus, finishedAt?: number): RunDetails => ({
+                status,
+                runId,
+                startedAt,
+                finishedAt,
+                tasks: tasks.map((task) => ({ ...task }))
+            })
+
+            let durableRun: DurableRun | undefined
+            let lastRunSave = 0
+            let lastEmit = 0
+            const emit = (force = false): void => {
+                const now = Date.now()
+                if (!force && now - lastEmit < EMIT_INTERVAL_MS) return
+                lastEmit = now
+                if (durableRun && now - lastRunSave >= RUN_SAVE_INTERVAL_MS) {
+                    lastRunSave = now
+                    saveRun(durableRun)
+                }
+                onUpdate?.({
+                    content: [{ type: 'text', text: partialText(snapshot('running')) }],
+                    details: snapshot('running')
+                })
+                syncWidget()
+            }
+
+            for (const spec of specs) await validateCwd(spec.cwd)
+            emit(true)
+
+            const modelRuntime = await createChildModelRuntime(ctx)
+
+            const runTask = async (spec: TaskSpec, detail: TaskDetails, record: DurableTask): Promise<void> => {
+                let acquired = false
+                try {
+                    await acquirePermit(signal)
+                    acquired = true
+                    await mkdir(spec.dir, { recursive: true, mode: 0o700 })
+
+                    if (spec.isolation === 'worktree') {
+                        const worktree = path.join(spec.dir, 'worktree')
+                        await createWorktree(spec.cwd, worktree)
+                        spec.cwd = worktree
+                        detail.worktree = worktree
+                        detail.cwd = worktree
+                        record.worktree = worktree
+                        record.cwd = worktree
+                        saveRun(run)
+                        emit(true)
+                    }
+
+                    const session = await createChildSession({
+                        cwd: spec.cwd,
+                        sessionDir: path.join(spec.dir, 'session'),
+                        model: spec.model ?? activeModel,
+                        modelRuntime,
+                        thinking: spec.thinking,
+                        parentSystemPrompt: ctx.getSystemPrompt(),
+                        allTools: pi.getAllTools().map((tool) => tool.name),
+                        agent: spec.agent,
+                        schema: spec.schema,
+                        onStructured: (value) => {
+                            detail.structured = value
+                        }
+                    })
+                    liveSessions.set(spec.id, session)
+                    record.sessionFile = session.sessionFile
+                    saveRun(run)
+
+                    detail.status = 'running'
+                    detail.startedAt = Date.now()
+                    emit(true)
+
+                    if (spec.forkContext) {
+                        const parentEntries = ctx.sessionManager.getEntries()
+                        let forkChars = 0
+                        for (const entry of parentEntries) {
+                            if (forkChars >= MAX_FORK_CONTEXT_CHARS) break
+                            if (signal?.aborted) break
+                            if (entry.type !== 'message') continue
+                            const msg = entry.message as { role?: string; content?: JsonValue }
+                            if (msg.role !== 'user' && msg.role !== 'assistant') continue
+                            const text = extractForkText(msg.content)
+                            if (text) {
+                                const remaining = MAX_FORK_CONTEXT_CHARS - forkChars
+                                const clipped =
+                                    text.length > remaining
+                                        ? `${text.slice(0, remaining)}\n[fork context truncated]`
+                                        : text
+                                forkChars += clipped.length
+                                await session.sendCustomMessage(
+                                    {
+                                        customType: `fork-${msg.role}`,
+                                        content: [{ type: 'text', text: clipped }],
+                                        display: true
+                                    },
+                                    { triggerTurn: false }
+                                )
+                                if (forkChars >= MAX_FORK_CONTEXT_CHARS) break
+                            }
+                        }
+                    }
+
+                    const {
+                        output: rawOutput,
+                        assistant,
+                        turnCount,
+                        timedOut,
+                        touched: newTouched,
+                        schemaFallback
+                    } = await drivePrompt({
+                        session,
+                        prompt: spec.task,
+                        maxTurns: spec.maxTurns,
+                        schema: spec.schema,
+                        cwd: spec.cwd,
+                        timeoutMs: spec.timeoutMs,
+                        abortSignal: signal,
+                        onEmit: emit,
+                        detail
+                    })
+                    const assistantMsg = assistant ?? findLastAssistant(session.messages)
+                    detail.output = rawOutput || undefined
+                    if (newTouched.length > 0) detail.touched = newTouched
+                    if (detail.worktree) detail.changes = changedPaths(await gitStatus(detail.worktree))
+                    detail.sessionFile = session.sessionFile
+                    detail.finishedAt = Date.now()
+                    if (!detail.output || timedOut) {
+                        const salvaged = salvageOutput(assistantMsg) ?? salvageFromMessages(session.messages)
+                        if (salvaged && !detail.output) {
+                            detail.output = salvaged
+                            detail.partial = true
+                        }
+                    }
+                    detail.hasSchema = spec.schema !== undefined && !schemaFallback
+                    if (detail.hasSchema && detail.structured === undefined) detail.partial = true
+                    const reason = failureReason({
+                        hasAssistant: assistantMsg !== undefined,
+                        timedOut,
+                        duration: formatDuration(detail.startedAt),
+                        hitTurnLimit: turnCount >= spec.maxTurns,
+                        maxTurns: spec.maxTurns,
+                        aborted: signal?.aborted === true,
+                        hasSchema: spec.schema !== undefined && !schemaFallback,
+                        hasStructured: detail.structured !== undefined,
+                        output: detail.output ?? '',
+                        stopReason: assistantMsg?.stopReason,
+                        errorMessage: assistantMsg?.errorMessage
+                    })
+                    if (reason) {
+                        detail.status = 'failed'
+                        detail.error = reason
+                    } else {
+                        detail.status = 'completed'
+                    }
+                } catch (error) {
+                    detail.status = 'failed'
+                    detail.error = error instanceof Error ? error.message : String(error)
+                    detail.finishedAt ??= Date.now()
+                } finally {
+                    if (detail.status === 'queued' || detail.status === 'running') {
+                        detail.status = 'failed'
+                        detail.error ??= 'Subagent aborted.'
+                        detail.finishedAt ??= Date.now()
+                    }
+                    syncRecord(record, detail)
+                    if (detail.usage !== undefined) {
+                        recordOverhead(ctx.sessionManager.getSessionId(), spec.agent?.name ?? 'scout', detail.usage)
+                    }
+                    saveRun(run)
+                    if (acquired) releasePermit()
+                    emit(true)
+                }
+            }
+
+            const resumeModelRuntime = resumeKey ? await createChildModelRuntime(ctx) : undefined
+
+            const resumeKnownTask = async (task: TaskDetails): Promise<void> => {
+                const sessionId = ctx.sessionManager.getSessionId()
+                const run = findRunForTask(sessionId, task.id)
+                const record = run?.tasks.find((candidate) => candidate.id === task.id)
+                if (!run || !record) throw new Error(`No durable record for "${task.label}"; start the task again.`)
+                const knobs = params as { maxTurns?: number; timeoutMs?: number }
+                await resumeTask({
+                    pi,
+                    ctx,
+                    run,
+                    record,
+                    task,
+                    signal,
+                    followUp: (params.task as string | undefined)?.trim() || undefined,
+                    maxTurns: knobs.maxTurns,
+                    timeoutMs: knobs.timeoutMs,
+                    modelRuntime: resumeModelRuntime,
+                    onEmit: emit
+                })
+            }
+
+            if (resumeKey) {
+                if (resumeKey === 'all') {
+                    const failed = registry.filter((run) => run.status === 'failed')
+                    if (!failed.length)
+                        return {
+                            content: [{ type: 'text', text: 'No failed tasks to resume.' }],
+                            details: snapshot('completed', Date.now())
+                        }
+                    await Promise.allSettled(failed.map((task) => resumeKnownTask(task)))
+                    if (signal?.aborted) throw new Error('Subagent aborted.')
+                    const details: RunDetails = {
+                        status: 'completed',
+                        runId,
+                        startedAt,
+                        finishedAt: Date.now(),
+                        tasks: failed.map((task) => ({ ...task }))
+                    }
+                    return { content: [{ type: 'text', text: resultText(details) }], details }
+                }
+                const task = registry.find((run) => run.id === resumeKey || run.label === resumeKey)
+                if (!task)
+                    throw new Error(
+                        `Task "${resumeKey}" not found. Failed ids: ${
+                            registry
+                                .filter((run) => run.status === 'failed')
+                                .map((run) => run.id)
+                                .join(', ') || 'none'
+                        }.`
+                    )
+                if (task.status !== 'failed')
+                    throw new Error(
+                        `Task "${task.label}" is ${task.status}, not failed, so there is nothing to resume.`
+                    )
+                await resumeKnownTask(task)
+                const details: RunDetails = {
+                    status: task.status === 'failed' ? 'failed' : 'completed',
+                    runId,
+                    startedAt,
+                    finishedAt: Date.now(),
+                    tasks: [{ ...task }]
+                }
+                return { content: [{ type: 'text', text: resultText(details) }], details }
+            }
+
+            const run: DurableRun = {
+                version: 1,
+                runId,
+                sessionId: ctx.sessionManager.getSessionId(),
+                toolCallId: _toolCallId,
+                startedAt,
+                tasks: specs.map((spec) => ({
+                    id: spec.id,
+                    index: spec.index,
+                    label: spec.label,
+                    task: spec.task,
+                    cwd: spec.cwd,
+                    provider: (spec.model ?? activeModel).provider,
+                    model: (spec.model ?? activeModel).id,
+                    thinking: spec.thinking,
+                    maxTurns: spec.maxTurns,
+                    timeoutMs: spec.timeoutMs,
+                    isolation: spec.isolation,
+                    forkContext: spec.forkContext === true,
+                    sessionDir: path.join(spec.dir, 'session'),
+                    agent: spec.agent?.name,
+                    schema: spec.schema,
+                    status: 'queued'
+                }))
+            }
+            durableRun = run
+            claimRun(run.sessionId, run.runId)
+            saveRun(run)
+
+            pi.events.emit('subagent:started', { runId, count: tasks.length })
+            await Promise.allSettled(
+                specs.map((spec, index) => runTask(spec, tasks[index] as TaskDetails, run.tasks[index] as DurableTask))
+            )
+            if (signal?.aborted) throw new Error('Subagent aborted.')
+
+            for (const task of tasks) {
+                if (!task.output) continue
+                const truncated = truncateHead(task.output, {
+                    maxBytes: Math.floor(DEFAULT_MAX_BYTES / tasks.length),
+                    maxLines: Math.floor(DEFAULT_MAX_LINES / tasks.length)
+                })
+                task.output = truncated.truncated
+                    ? `${truncated.content}\n\n[Output truncated. Full output is in the child session file.]`
+                    : truncated.content
+            }
+
+            run.finishedAt = Date.now()
+            for (const [index, task] of tasks.entries()) {
+                const record = run.tasks[index]
+                if (record) syncRecord(record, task)
+            }
+            saveRun(run)
+
+            const failed = tasks.filter((task) => task.status === 'failed')
+            pi.events.emit('subagent:completed', { runId, failed: failed.length })
+            const details = snapshot(failed.length === tasks.length ? 'failed' : 'completed', Date.now())
+            return { content: [{ type: 'text', text: resultText(details) }], details }
+        },
+
+        renderCall(args, theme) {
+            const inputs = args.tasks?.length ? args.tasks : [args]
+            let text = theme.fg('toolTitle', theme.bold('subagent '))
+            text += theme.fg('muted', inputs.length > 1 ? `${inputs.length} tasks` : '')
+            for (const input of inputs) {
+                const first = (input.task ?? '').split('\n', 1)[0]?.trim() ?? ''
+                const preview = first.length > 90 ? `${first.slice(0, 90)}…` : first || '...'
+                const forkTag = input.context === 'fork' ? theme.fg('accent', ' fork') : ''
+                const schemaTag = input.schema !== undefined ? theme.fg('accent', ' structured') : ''
+                text += `\n  ${theme.fg('accent', input.agent ?? 'default')} ${theme.fg('dim', preview)}${forkTag}${schemaTag}`
+                const thinking = (input as { thinking?: string }).thinking
+                if (thinking !== undefined) text += `\n    ${theme.fg('muted', thinking)}`
+            }
+            return new Text(text, 0, 0)
+        },
+
+        renderResult(result, { expanded, isPartial }, theme) {
+            const details = result.details as RunDetails | undefined
+            if (!details) {
+                const content = result.content.find((part) => part.type === 'text')
+                return new Text(content?.type === 'text' ? content.text : '(no output)', 0, 0)
+            }
+
+            const running = isPartial || details.status === 'queued' || details.status === 'running'
+            const duration = formatDuration(details.startedAt, details.finishedAt)
+            let text = theme.fg('toolTitle', theme.bold('subagent'))
+            text += theme.fg('muted', ` · ${countByStatus(details.tasks)}${duration ? ` · ${duration}` : ''}`)
+
+            for (const task of details.tasks) {
+                text += `\n\n${statusIcon(task.status, theme)} ${theme.fg('dim', taskHeadline(task))}`
+                if (task.error) text += `\n  ${theme.fg('error', task.error.split('\n', 1)[0] ?? '')}`
+                if (task.sessionFile && !running) text += `\n  ${theme.fg('dim', task.sessionFile)}`
+                if (task.worktree && !running)
+                    text += `\n  ${theme.fg('dim', task.changes?.length ? `${task.changes.length} changed file(s), branch ${worktreeBranch(task.worktree)}` : 'clean worktree')}`
+
+                if (task.structured !== undefined && !running) {
+                    text += `\n  ${theme.fg('accent', 'structured:')} ${theme.fg('toolOutput', JSON.stringify(task.structured))}`
+                }
+
+                const body = task.status === 'completed' || task.status === 'failed' ? task.output : undefined
+                if (!body) continue
+                const lines = body.split('\n')
+                const visible = expanded ? lines : lines.slice(0, 8)
+                text += `\n${visible.map((line) => theme.fg('toolOutput', line)).join('\n')}`
+                if (!expanded && lines.length > visible.length) text += `\n${theme.fg('muted', '(Ctrl+O to expand)')}`
+            }
+            return new Text(text, 0, 0)
+        }
+    })
+
+    pi.registerCommand('agents', {
+        description: 'List agent profiles (tools, model, limits). Useful after adding or editing profile files.',
+        handler: async (_args, ctx) => {
+            const agents = [...loadAgents(ctx.cwd).values()]
+            const lines =
+                agents.length === 0
+                    ? [
+                          'No agent profiles found. Add markdown files with YAML frontmatter under ~/.pi/agent/agents/ or .pi/agents/.'
+                      ]
+                    : [
+                          `${agents.length} agent profile${agents.length !== 1 ? 's' : ''}:`,
+                          ...agents.map(profileLines).flat()
+                      ]
+            ctx.ui.notify(lines.join('\n'), 'info')
+        }
+    })
+}
+
+function profileLines(a: {
+    name: string
+    description: string
+    model?: string
+    tools: string[]
+    disallowedTools: string[]
+    maxTurns?: number
+    maxExecutionTimeMs?: number
+    thinking?: string
+}): string[] {
+    const bits = [`- ${a.name}: ${a.description}`]
+    if (a.model) bits.push(`  model: ${a.model}`)
+    if (a.tools.length) bits.push(`  tools: ${a.tools.join(', ')}`)
+    if (a.disallowedTools.length) bits.push(`  blocked: ${a.disallowedTools.join(', ')}`)
+    if (a.maxTurns) bits.push(`  maxTurns: ${a.maxTurns}`)
+    if (a.maxExecutionTimeMs) bits.push(`  timeout: ${a.maxExecutionTimeMs}ms`)
+    if (a.thinking) bits.push(`  thinking: ${a.thinking}`)
+    return bits
+}