pantheon-opencode 1.3.2 → 1.3.3

package/src/pantheon/delegation-notify.ts

@@ -0,0 +1,238 @@
+/**
+ * Delegation Notify (Phase 3) — completion notifications for background jobs.
+ *
+ * The spike refuted `promptAsync({noReply:true})` as a push mechanism — nothing
+ * is delivered to the parent session. The working channel is a QUEUE + flush:
+ *
+ *   1. When a board job reaches a terminal state (`board.onTerminal`), the
+ *      plugin calls `notifyParent(job)` → a `<task-notification>` block is
+ *      queued in-memory for `job.parentSessionID` (FIFO, bounded per parent).
+ *   2. The next `chat.message` hook fire for that parent session calls
+ *      `flushQueue(parentSessionID, output)`, which prepends the pending
+ *      notifications onto the first text part of the parent's user message —
+ *      the same graceful-degradation channel pantheon-hooks uses for its
+ *      <system-reminder> fallback buffer (TUI toasts are broken on 1.18.13).
+ *
+ * If the parent never sends another message the notification stays queued —
+ * the graceful-degradation path. There is deliberately NO client push.
+ *
+ * `handleDelegationEvent` wires the `event` hook: `session.idle`/`session.error`
+ * on a child session that is a board job → `finalizeDelegation` (Phase 2),
+ * which transitions the board and fires `onTerminal` → notify. That makes the
+ * onTerminal listener the SINGLE notification point — finalize never notifies
+ * directly, so there is no double-notify. Unknown sessions are ignored.
+ *
+ * Pure TypeScript — zero runtime dependencies beyond the board types.
+ *
+ * Follow-up (Themis review, Phase 5): `extractErrorMessage` handles the two
+ * observed `session.error` error shapes (string, { message }). The opencode SDK
+ * MAY expose other shapes (e.g. Error-like with non-string `message`) — if a
+ * real session.error ever carries one, the extraction degrades to the generic
+ * "session error" label. No code change: there is no evidence any other shape
+ * occurs in practice; revisit if a session.error shows an unexpected payload.
+ *
+ * @module delegation-notify
+ */
+
+import type { BackgroundJobRecord } from './background-job-board.ts'
+import type { FinalizeInput } from './delegation-finalize.ts'
+
+export type { FinalizeInput } from './delegation-finalize.ts'
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** One queued notification: text + enqueue timestamp. */
+export interface QueuedNotification {
+  text: string
+  at: number
+}
+
+/** Structural view of the event payload the `event` hook receives. */
+export interface DelegationEventLike {
+  type?: string
+  properties?: Record<string, unknown>
+}
+
+/** Dependencies threaded to handleDelegationEvent (board lookup + finalize). */
+export interface DelegationEventDeps {
+  /** Look up a board job by session ID (child session IDs are task IDs). */
+  board: { get(taskID: string): BackgroundJobRecord | undefined }
+  /** Bound Phase 2 finalize — clears the timeout timer + writes the report. */
+  finalize: (childSessionID: string, opts: FinalizeInput) => Promise<unknown>
+}
+
+// ─── Notification text ─────────────────────────────────────────────────
+
+/** Cap for description/summary text embedded in a notification. */
+const NOTIFICATION_TEXT_MAX = 120
+
+function truncate(text: string, max: number): string {
+  const trimmed = text.trim()
+  return trimmed.length > max ? `${trimmed.slice(0, max)}…` : trimmed
+}
+
+/**
+ * Build the self-contained `<task-notification>` block for a terminal job.
+ * Carries the task ID, alias, agent, state, timeout flag, description and
+ * result summary so the parent model can act on the completion without extra
+ * tool calls.
+ */
+export function buildTaskNotification(job: BackgroundJobRecord): string {
+  const stateLabel =
+    job.state === 'completed' ? 'completed' : job.state === 'error' ? 'failed' : job.state
+  const timeout = job.timedOut ? ' (timed out)' : ''
+  // The `Result:` marker makes the child output origin explicit in the parent
+  // context — the summary text came from the CHILD's output, not the parent's
+  // own context (Themis mitigation, Phase 5).
+  const summary = job.resultSummary
+    ? ` — Result: ${truncate(job.resultSummary, NOTIFICATION_TEXT_MAX)}`
+    : ''
+  return [
+    '<task-notification>',
+    `<task id="${job.taskID}" alias="${job.alias}" agent="${job.agent}" state="${job.state}">`,
+    `<summary>Delegation [${job.alias}] (${job.agent}) ${stateLabel}${timeout}: ${truncate(job.description, NOTIFICATION_TEXT_MAX)}${summary}</summary>`,
+    `<read>Read the full report with pantheon_delegation_read({ id: "${job.alias}" }).</read>`,
+    '</task>',
+    '</task-notification>',
+  ].join('\n')
+}
+
+// ─── Notifier (queue + flush) ──────────────────────────────────────────
+
+/** Per-parent queue bound — a full queue drops new entries, never grows unbounded. */
+const MAX_PER_PARENT = 10
+
+function isTextPartLike(value: unknown): value is { type: 'text'; text: string } {
+  if (!value || typeof value !== 'object') return false
+  const part = value as { type?: unknown; text?: unknown }
+  return part.type === 'text' && typeof part.text === 'string'
+}
+
+/**
+ * In-memory completion notification queue, keyed by parent session ID.
+ * FIFO per parent, bounded (MAX_PER_PARENT — anti-spam philosophy, matching
+ * pantheon-hooks' CHAT_REMINDER_MAX). Delivered by `flushQueue` into the
+ * parent's next chat.message; delivered notifications are marked sent.
+ */
+export class DelegationNotifier {
+  private readonly queue = new Map<string, QueuedNotification[]>()
+  private readonly sent = new Map<string, number>()
+  private readonly warn: (message: string) => void
+
+  /**
+   * @param logger Optional injected logger (testable). Defaults to
+   *   `console.warn` with the `[pantheon-delegation]` prefix, matching the
+   *   plugin's structured-log style.
+   */
+  constructor(logger?: { warn: (message: string) => void }) {
+    this.warn =
+      logger?.warn ?? ((message: string) => console.warn(`[pantheon-delegation] ${message}`))
+  }
+
+  /** Notifications awaiting delivery for a parent session. */
+  pendingCount(parentSessionID: string): number {
+    return this.queue.get(parentSessionID)?.length ?? 0
+  }
+
+  /** Whether any notifications await delivery for a parent session. */
+  hasPending(parentSessionID: string): boolean {
+    return this.pendingCount(parentSessionID) > 0
+  }
+
+  /** Notifications already injected into a parent's chat.message output. */
+  sentCount(parentSessionID: string): number {
+    return this.sent.get(parentSessionID) ?? 0
+  }
+
+  /**
+   * Queue a completion notification for a parent session. The channel: there
+   * is NO client push — the notification is delivered by the next
+   * `flushQueue` for that parent. Returns false when the queue is full.
+   */
+  queueNotification(parentSessionID: string, text: string): boolean {
+    const entries = this.queue.get(parentSessionID) ?? []
+    if (entries.length >= MAX_PER_PARENT) {
+      this.warn(
+        `notification dropped for parent session ${parentSessionID}: ` +
+          `queue full (${MAX_PER_PARENT} pending)`,
+      )
+      return false
+    }
+    entries.push({ text, at: Date.now() })
+    this.queue.set(parentSessionID, entries)
+    return true
+  }
+
+  /** Build + queue the notification for a terminal job. False when full. */
+  notifyParent(job: BackgroundJobRecord): boolean {
+    return this.queueNotification(job.parentSessionID, buildTaskNotification(job))
+  }
+
+  /**
+   * Inject all pending notifications for a parent into a `chat.message` output
+   * (prepend onto the first text part — matching the pantheon-hooks reminder
+   * injection pattern; with no text part the block is unshifted as a new one).
+   * Delivered entries are marked sent. Returns how many were delivered (0 when
+   * nothing was pending).
+   */
+  flushQueue(parentSessionID: string, output: { parts: unknown[] }): number {
+    const entries = this.queue.get(parentSessionID)
+    if (entries === undefined || entries.length === 0) return 0
+    this.queue.delete(parentSessionID)
+
+    const block = entries.map((entry) => entry.text).join('\n')
+    const firstText = output.parts.find(isTextPartLike)
+    if (firstText !== undefined) {
+      firstText.text = `${block}\n\n${firstText.text}`
+    } else {
+      output.parts.unshift({ type: 'text', text: block })
+    }
+    this.sent.set(parentSessionID, (this.sent.get(parentSessionID) ?? 0) + entries.length)
+    return entries.length
+  }
+}
+
+// ─── Event → finalize wiring ───────────────────────────────────────────
+
+function extractErrorMessage(error: unknown): string {
+  if (typeof error === 'string' && error.trim() !== '') return error
+  if (error && typeof error === 'object' && 'message' in error) {
+    const message = (error as { message: unknown }).message
+    if (typeof message === 'string' && message.trim() !== '') return message
+  }
+  return 'session error'
+}
+
+/**
+ * Handle a lifecycle event for background delegations:
+ *  - `session.idle` on a board job → finalize as completed;
+ *  - `session.error` on a board job → finalize as error (message extracted);
+ *  - any other event, a missing session ID, or an unknown session → no-op.
+ *
+ * Finalize transitions the board, which fires `onTerminal` — the single point
+ * that queues the completion notification (no double-notify). The board's
+ * same-terminal idempotency makes repeated idles harmless (finalize rewrites
+ * the report but never transitions a terminal job to a different state).
+ *
+ * @returns True when the event named a board job (handled).
+ */
+export async function handleDelegationEvent(
+  ev: DelegationEventLike,
+  deps: DelegationEventDeps,
+): Promise<boolean> {
+  const type = ev?.type
+  if (type !== 'session.idle' && type !== 'session.error') return false
+  const sessionID = ev.properties?.sessionID
+  if (typeof sessionID !== 'string' || sessionID === '') return false
+  if (deps.board.get(sessionID) === undefined) return false
+
+  if (type === 'session.idle') {
+    await deps.finalize(sessionID, { state: 'completed' })
+  } else {
+    await deps.finalize(sessionID, {
+      state: 'error',
+      error: extractErrorMessage(ev.properties?.error),
+    })
+  }
+  return true
+}

package/src/pantheon/delegation.ts

@@ -0,0 +1,388 @@
+/**
+ * Delegation Core (Phase 2) — the three background-delegation tools plus the
+ * finalize lifecycle hook, built on the BackgroundJobBoard.
+ *
+ * Tools (STRUCTURAL shape — matches what opencode expects: `{description,
+ * args (zod shape), execute(args, ctx)}`; zod is imported directly — the
+ * `@opencode-ai/plugin` package is a devDep and is NEVER runtime-imported):
+ *   - `pantheon_delegate({prompt, agent, description?})` — create a child
+ *     session (parentID = caller), register it on the board, arm a timeout,
+ *     and fire-and-forget `session.promptAsync` on the child (NO noReply —
+ *     the spike refuted noReply as a push mechanism). Completion is observed
+ *     via `session.idle` on the child and finalized through
+ *     `finalizeDelegation` (exposed on the toolset for the Phase 3 event hook).
+ *   - `pantheon_delegation_read({id})` — block via `board.waitForTerminal`,
+ *     return the report markdown, mark the job reconciled.
+ *   - `pantheon_delegation_list()` — job list with `[unread]` for terminal-
+ *     unreconciled jobs.
+ *
+ * Depth guard (root-session detection): the ToolContext carries NO parentID
+ * (spike), so root detection is configurable. Resolution order:
+ *   1. `options.isRootSession(sessionID)` custom predicate;
+ *   2. `options.rootSessions` explicit allowlist;
+ *   3. default: any session WE created via `session.create` is a sub-session;
+ *      everything else is treated as root. Phase 3 should pass the root
+ *      registry derived from `session.created` events (Session.parentID
+ *      undefined ⇒ root) for authoritative enforcement.
+ *
+ * Read-only enforcement is Phase 4 — `read_only` is exposed on the delegate
+ * args and the child session is registered in the read-only registry when the
+ * delegate is read-only (explicit flag or agent ∈ readOnlyAgents), which the
+ * plugin's `tool.execute.before` guard enforces.
+ *
+ * @module delegation
+ */
+
+import { z } from 'zod'
+
+import type { BackgroundJobBoard, BackgroundJobRecord } from './background-job-board.ts'
+import { readOnlyRegistry } from './delegation-enforce.ts'
+import {
+  DELEGATION_DEFAULTS,
+  type DelegationClient,
+  type DelegationDeps,
+  type DelegationOptions,
+  type FinalizeInput,
+  finalizeDelegation as finalizeDelegationReport,
+  readDelegationReport,
+} from './delegation-finalize.ts'
+import { resolveActivePreset } from './presets.mjs'
+
+export type {
+  DelegationClient,
+  DelegationClientSession,
+  DelegationMessageBundle,
+  DelegationOptions,
+  FinalizeInput,
+} from './delegation-finalize.ts'
+export { DELEGATION_DEFAULTS } from './delegation-finalize.ts'
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Structural view of the tool context opencode passes to execute(). */
+export interface ToolContextLike {
+  sessionID: string
+  directory?: string
+  worktree?: string
+  agent?: string
+}
+
+/** A delegation tool: description + zod args shape + execute. */
+export interface DelegationTool<Args extends z.ZodRawShape = z.ZodRawShape> {
+  description: string
+  args: Args
+  execute(args: z.infer<z.ZodObject<Args>>, ctx: ToolContextLike): Promise<string>
+}
+
+/** The full toolset returned by createDelegationTools(). */
+export interface DelegationToolset {
+  pantheon_delegate: DelegationTool<typeof delegateArgs>
+  pantheon_delegation_read: DelegationTool<typeof readArgs>
+  pantheon_delegation_list: DelegationTool<typeof listArgs>
+  /** Lifecycle hook for the Phase 3 event wiring (session.idle on the child). */
+  finalizeDelegation: (
+    childSessionID: string,
+    opts: FinalizeInput,
+  ) => Promise<BackgroundJobRecord | undefined>
+}
+
+/** Input for createDelegationTools(). */
+export interface CreateDelegationToolsInput {
+  board: BackgroundJobBoard
+  client: DelegationClient
+  options?: DelegationOptions
+}
+
+// ─── Args schemas ──────────────────────────────────────────────────────
+
+const delegateArgs = {
+  prompt: z.string().min(1).describe('Task prompt delivered to the background agent.'),
+  agent: z.string().min(1).describe('Agent name, e.g. "apollo" or "hermes".'),
+  description: z.string().optional().describe('Human-readable description shown on the job board.'),
+  read_only: z.boolean().optional().describe('Advisory flag for Phase 4 read-only enforcement.'),
+  model: z
+    .string()
+    .optional()
+    .describe(
+      'Explicit model for the child session (provider/model, e.g. "opencode/deepseek-v4-flash-free").',
+    ),
+} satisfies z.ZodRawShape
+
+const readArgs = {
+  id: z.string().min(1).describe('Job alias (e.g. "apo-1") or task ID to read.'),
+} satisfies z.ZodRawShape
+
+const listArgs = {} satisfies z.ZodRawShape
+
+// ─── State labels ──────────────────────────────────────────────────────
+
+function stateLabel(state: BackgroundJobRecord['state']): string {
+  switch (state) {
+    case 'running':
+      return 'RUNNING'
+    case 'completed':
+      return 'OK'
+    case 'error':
+      return 'ERR'
+    case 'cancelled':
+      return 'CANCELLED'
+    case 'reconciled':
+      return 'RECONCILED'
+  }
+}
+
+// ─── Model resolution ──────────────────────────────────────────────────
+
+/** Session model ref accepted by the opencode server's session.create. */
+export interface ChildSessionModelRef {
+  id: string
+  providerID: string
+}
+
+/**
+ * Split a `provider/model` model ID (e.g. `opencode/deepseek-v4-flash-free`)
+ * into the `{ id, providerID }` ref the session.create body expects.
+ * Returns undefined for malformed IDs (no slash, empty segments).
+ */
+function splitModelRef(model: string): ChildSessionModelRef | undefined {
+  const slash = model.indexOf('/')
+  if (slash <= 0 || slash === model.length - 1) return undefined
+  return { providerID: model.slice(0, slash), id: model.slice(slash + 1) }
+}
+
+/**
+ * Resolve the child session model with priority:
+ *   1. explicit `model` option passed to the delegate tool;
+ *   2. `options.agentModels[agent]` (routing.yml agent entry, case-insensitive);
+ *   3. the active preset's agent entry via resolveActivePreset();
+ *   4. fallback: undefined — the child is created without a model (the
+ *      caller warns) so opencode's default applies.
+ */
+function resolveChildModel(
+  options: DelegationOptions,
+  agent: string,
+  explicitModel?: string,
+): ChildSessionModelRef | undefined {
+  // (a) explicit model option on the delegate tool call
+  if (explicitModel !== undefined && explicitModel !== '') {
+    const ref = splitModelRef(explicitModel)
+    if (ref !== undefined) return ref
+  }
+  const key = agent.toLowerCase()
+  // (b) routing.yml agent entry wired through options.agentModels
+  const mapped = options.agentModels?.[key]
+  if (mapped !== undefined && mapped !== '') {
+    const ref = splitModelRef(mapped)
+    if (ref !== undefined) return ref
+  }
+  // (c) active preset agent entry (resolveActivePreset reads routing.yml
+  // presets + .pantheon/active-preset.json). Guarded — a broken routing.yml
+  // must never kill the delegate.
+  try {
+    const presetModel = resolveActivePreset({
+      ...(options.presetEnv !== undefined ? { env: options.presetEnv } : {}),
+      ...(options.logger !== undefined ? { logger: options.logger } : {}),
+    })?.agents?.[key]?.model
+    if (presetModel !== undefined && presetModel !== '') {
+      const ref = splitModelRef(presetModel)
+      if (ref !== undefined) return ref
+    }
+  } catch (err: unknown) {
+    const reason = err instanceof Error ? err.message : String(err)
+    options.logger?.warn?.(`[pantheon-delegate] active preset resolution failed: ${reason}`)
+  }
+  return undefined
+}
+
+// ─── Factory ───────────────────────────────────────────────────────────
+
+/**
+ * Build the delegation toolset. Keeps per-instance state: the set of child
+ * sessions WE created (depth-guard default) and the per-job timeout timers
+ * (cleared on finalize, `.unref()`'d so they never hold the process open).
+ */
+export function createDelegationTools(input: CreateDelegationToolsInput): DelegationToolset {
+  const { board, client } = input
+  const options: DelegationOptions = input.options ?? {}
+  const deps: DelegationDeps = { board, client, options }
+  const outputDir = options.outputDir ?? DELEGATION_DEFAULTS.outputDir
+  const timeoutMs = options.timeoutMs ?? DELEGATION_DEFAULTS.timeoutMs
+  const readTimeoutMs = options.readTimeoutMs ?? DELEGATION_DEFAULTS.readTimeoutMs
+
+  const knownChildren = new Set<string>()
+  const timers = new Map<string, NodeJS.Timeout>()
+
+  function isRootSession(sessionID: string): boolean {
+    if (options.isRootSession !== undefined) return options.isRootSession(sessionID)
+    if (options.rootSessions !== undefined) return options.rootSessions.has(sessionID)
+    return !knownChildren.has(sessionID)
+  }
+
+  function clearTimer(childSessionID: string): void {
+    const timer = timers.get(childSessionID)
+    if (timer !== undefined) {
+      clearTimeout(timer)
+      timers.delete(childSessionID)
+    }
+  }
+
+  /** Bound finalize: clear the job timer, then run the report + transition. */
+  async function finalize(
+    childSessionID: string,
+    opts: FinalizeInput,
+  ): Promise<BackgroundJobRecord | undefined> {
+    clearTimer(childSessionID)
+    return finalizeDelegationReport(deps, childSessionID, opts)
+  }
+
+  const pantheon_delegate: DelegationTool<typeof delegateArgs> = {
+    description:
+      'Dispatch a background agent as a child session and register it on the job board. ' +
+      'Returns the readable alias (e.g. "apo-1"); read the result with ' +
+      'pantheon_delegation_read. Only root sessions may delegate.',
+    args: delegateArgs,
+    execute: async (args, ctx) => {
+      if (!isRootSession(ctx.sessionID)) {
+        throw new Error(
+          `pantheon_delegate rejected: session ${ctx.sessionID} is a sub-session — only root sessions can delegate`,
+        )
+      }
+      if (!board.canDispatch(args.agent)) {
+        throw new Error(
+          `pantheon_delegate rejected: concurrency limit reached for agent "${args.agent}" ` +
+            `(${board.getRunningCount(args.agent)} running)`,
+        )
+      }
+
+      // session.create failure → return a clear error as TEXT (tools return
+      // errors as text, not thrown) and register NO job on the board — an
+      // unhandled rejection here would otherwise lose the failure entirely.
+      // The child model is resolved from (a) the explicit `model` option,
+      // (b) options.agentModels (routing.yml), (c) the active preset — else
+      // left unset so opencode's default applies (warned below).
+      const childModel = resolveChildModel(options, args.agent, args.model)
+      if (childModel === undefined) {
+        options.logger?.warn?.(
+          `[pantheon-delegate] no model resolved for agent "${args.agent}" — ` +
+            "child session will use opencode's default model (may require API keys)",
+        )
+      }
+      let created: { id: string }
+      try {
+        created = await client.session.create({
+          body: {
+            parentID: ctx.sessionID,
+            title: args.description ?? args.prompt.slice(0, 80),
+            ...(childModel !== undefined ? { model: childModel } : {}),
+          },
+        })
+      } catch (err: unknown) {
+        const reason = err instanceof Error ? err.message : String(err)
+        return `pantheon_delegate failed to create child session: ${reason}`
+      }
+      const childSessionID = created.id
+      knownChildren.add(childSessionID)
+
+      // Phase 4 read-only enforcement: register the child session in the
+      // read-only registry when the delegate is read-only — explicit
+      // `read_only: true` on the call, or the agent ∈ readOnlyAgents
+      // (case-insensitive). The plugin's tool.execute.before guard then
+      // denies edit/write/bash/task inside that session.
+      const readOnly =
+        args.read_only === true || (options.readOnlyAgents?.has(args.agent.toLowerCase()) ?? false)
+      if (readOnly) {
+        const entry: { agent: string; readOnlyFlag?: boolean } = { agent: args.agent }
+        if (args.read_only !== undefined) entry.readOnlyFlag = args.read_only
+        readOnlyRegistry.register(childSessionID, entry)
+      }
+
+      const job = await board.registerLaunch({
+        taskID: childSessionID,
+        parentSessionID: ctx.sessionID,
+        agent: args.agent,
+        description: args.description ?? args.prompt,
+        objective: args.prompt,
+      })
+
+      // Timeout manager: cleared on finalize, unref'd so the timer never
+      // keeps the process alive on its own.
+      const timer = setTimeout(() => {
+        timers.delete(childSessionID)
+        void finalize(childSessionID, {
+          state: 'error',
+          error: `Delegation [${job.alias}] timed out after ${timeoutMs}ms without reaching a terminal state`,
+          timedOut: true,
+        }).catch((err: unknown) =>
+          console.error('[pantheon-delegate] timeout finalize failed:', err),
+        )
+      }, timeoutMs)
+      timer.unref()
+      timers.set(childSessionID, timer)
+
+      // Fire-and-forget — completion is observed via session.idle on the
+      // child (spike: noReply does NOT deliver anything to the parent).
+      void client.session
+        .promptAsync({
+          path: { id: childSessionID },
+          body: { agent: args.agent, parts: [{ type: 'text', text: args.prompt }] },
+        })
+        .catch((err: unknown) => console.error('[pantheon-delegate] promptAsync failed:', err))
+
+      return (
+        `Delegated to ${args.agent}: [${job.alias}] (task ${childSessionID}).\n` +
+        `Read the result with pantheon_delegation_read({ id: "${job.alias}" }).`
+      )
+    },
+  }
+
+  const pantheon_delegation_read: DelegationTool<typeof readArgs> = {
+    description:
+      'Block until a background delegation finishes (completed/error/cancelled), then return its ' +
+      'report markdown and mark the job reconciled. Resolves by alias or task ID.',
+    args: readArgs,
+    execute: async (args, ctx) => {
+      const job = board.resolve(ctx.sessionID, args.id)
+      if (!job) {
+        return `Unknown delegation "${args.id}" for this session. Use pantheon_delegation_list to see active delegations.`
+      }
+
+      let terminal: BackgroundJobRecord
+      try {
+        terminal = await board.waitForTerminal(job.taskID, readTimeoutMs)
+      } catch {
+        return `Timed out after ${readTimeoutMs}ms waiting for delegation "${args.id}" ([${job.alias}]).`
+      }
+
+      const md = await readDelegationReport(outputDir, terminal)
+      if (md === undefined) {
+        return `Delegation [${terminal.alias}] reached state ${terminal.state} but no report file was found.`
+      }
+
+      await board.markReconciled(job.taskID)
+      return md
+    },
+  }
+
+  const pantheon_delegation_list: DelegationTool<typeof listArgs> = {
+    description:
+      'List background delegations for the current session, with [unread] for finished jobs.',
+    args: listArgs,
+    execute: async (_args, ctx) => {
+      const jobs = board.list(ctx.sessionID)
+      if (jobs.length === 0) return 'No background delegations for this session.'
+
+      const lines = jobs.map((j) => {
+        const unread = j.terminalUnreconciled ? ' [unread]' : ''
+        return `  [${j.alias}] ${j.agent} — ${j.description} — ${stateLabel(j.state)}${unread}`
+      })
+      return `Background Delegations (${jobs.length}):\n${lines.join('\n')}`
+    },
+  }
+
+  return {
+    pantheon_delegate,
+    pantheon_delegation_read,
+    pantheon_delegation_list,
+    finalizeDelegation: finalize,
+  }
+}