pantheon-opencode 1.3.2 → 1.3.3

package/README.md

@@ -183,6 +183,56 @@ export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
 opencode
 ```
 
+### Background Delegation
+
+Zeus (and other root sessions) can dispatch agents as **background child sessions**
+via three delegation tools, tracked on a persistent job board
+(`.pantheon/board/state.json`, 24h TTL) with reports written to
+`.pantheon/delegations/<parent>/<alias>.md`:
+
+| Tool | Signature | Behavior |
+|------|-----------|----------|
+| `pantheon_delegate` | `{prompt, agent, description?, read_only?}` | Creates a child session (parentID = caller), registers it on the job board, arms a 15-minute timeout, and fire-and-forgets `promptAsync` on the child. Returns the readable alias (e.g. `apo-1`). Only root sessions may delegate (sub-sessions are rejected by the depth guard). |
+| `pantheon_delegation_read` | `{id}` | Blocks (`waitForTerminal`, up to 15 min) until the delegation reaches a terminal state, returns the report markdown, and marks the job reconciled. Resolves by alias or task ID. |
+| `pantheon_delegation_list` | `{}` | Lists the current session's delegations with `[unread]` on finished, unreconciled jobs. |
+
+**Notification model — no polling, no client push.** When a job reaches a
+terminal state (completion observed via `session.idle`/`session.error` on the
+child), a self-contained `<task-notification>` block is queued in memory for
+the parent session and injected into the parent's **next** `chat.message` hook
+fire (prepended onto the first text part — the graceful-degradation channel the
+TUI toast workaround uses). If the parent never sends another message, the
+notification stays queued. The `<task-notification>` carries the task ID, alias,
+agent, state, description and a `Result:`-prefixed summary so the parent can act
+without an extra tool call.
+
+**Timeout:** `background_delegation.timeout_ms` (default `900000` = 15 min). A job
+that has not reached a terminal state is finalized as `error`/`timedOut`.
+
+**Read-only enforcement:** delegating with `read_only: true`, or delegating to an
+agent in `background_delegation.read_only_agents` (`apollo`, `gaia`), registers
+the child session as read-only — the `tool.execute.before` guard denies
+`edit`/`write`/`bash`/`task` inside that session.
+
+**Compaction carry-forward:** during context compaction, running and unread
+terminal delegations (capped at `background_delegation.max_compaction_items`,
+default 10) are carried into the compacted context so the parent doesn't lose
+track of in-flight work.
+
+**Env vars & config:**
+
+- `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` — required (see launch block above).
+- `PANTHEON_TOASTS` — TUI toast gate for the delegation lifecycle signals.
+  Default `{errors, delegations, council}`; `PANTHEON_TOASTS=off` disables all
+  TUI toasts (delegation signals then only surface via the chat.message
+  `<task-notification>`/`<system-reminder>` channel).
+- `background_delegation` section in `src/routing.yml` — `timeout_ms`,
+  `poll_ms`, `max_compaction_items`, `prune_ttl_ms`, `read_only_agents`,
+  `session_max`, `retry_count`.
+
+See `src/agents/zeus.md` for the agent-facing delegation protocol and
+`src/pantheon/delegation.ts` for the tool implementations.
+
 > **Modes:** Interactive TUI with checkbox selection (default TTY), or `--headless` for scripts/CI.
 > **Minimal:** `--headless --no-mcp` installs only agents (~2s).
 > **Full:** `--headless` also creates Python venv + MCP servers (memory, persistence, KV, vision).

package/opencode.json

@@ -29,7 +29,10 @@
     }
   },
   "instructions": ["AGENTS.md", "src/instructions/*.instructions.md"],
-  "plugin": ["/home/ils15/pantheon/src/plugins/pantheon-hooks.ts"],
+  "plugin": [
+    "/home/ils15/pantheon/src/plugin.ts",
+    "/home/ils15/pantheon/src/plugins/pantheon-hooks.ts"
+  ],
   "mcp": {
     "bifrost": {
       "type": "remote",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "publishConfig": {
     "access": "public",
@@ -31,6 +31,7 @@
     "hooks:update": "pre-commit autoupdate",
     "test:security": "npm run secret-scan && node tests/test_install_mcp_vision.mjs && node tests/test_doctor_layers.mjs",
     "test:node": "node --test tests/*.mjs",
+    "test:ts": "for f in tests/pantheon/*.test.ts; do npx tsx \"$f\" || exit 1; done",
     "test": "python3 -m pytest tests/ -q 2>&1 || echo \"No tests found\"",
     "test:ci": "python3 -m pytest tests/ -q --tb=short 2>&1 || true"
   },
@@ -66,7 +67,8 @@
     "src/skills/**"
   ],
   "dependencies": {
-    "js-yaml": "^4.3.0"
+    "js-yaml": "^4.3.0",
+    "zod": "4.1.8"
   },
   "devDependencies": {
     "@commitlint/cli": "^19.8.0",

package/scripts/cost.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * cost.mjs — read-only cost aggregation from opencode.db (Wave 4, PR #46).
+ *
+ * Fallback for the `pantheon_cost` tool when node:sqlite is unavailable in
+ * the plugin process (node < 22.5). Uses node:sqlite itself and prints a
+ * single JSON object to stdout:
+ *   { ok: true,  days, rows: [{agent, costUsd, tokensInput, tokensOutput}] }
+ *   { ok: false, error: "<message>" }          (exit code 1)
+ *
+ * NEVER writes to the database — opened read-only. Malformed rows are
+ * skipped; assistant messages carry the authoritative cost + tokens.
+ *
+ * Usage: node scripts/cost.mjs <dbPath> <days>
+ */
+import { existsSync } from 'node:fs'
+import { DatabaseSync } from 'node:sqlite'
+
+/**
+ * Fail via exitCode + natural process exit (NEVER process.exit right after
+ * stdout.write — the pipe is async and the write can be truncated).
+ */
+function fail(message) {
+  process.stderr.write(`cost.mjs: ${message}\n`)
+  process.stdout.write(JSON.stringify({ ok: false, error: message }))
+  process.exitCode = 1
+}
+
+function main() {
+  const [, , dbPath, daysArg] = process.argv
+  const days = Number(daysArg ?? '7')
+
+  if (!dbPath) return fail('missing <dbPath> argument')
+  if (!existsSync(dbPath)) return fail(`database not found: ${dbPath}`)
+
+  try {
+    const db = new DatabaseSync(dbPath, { readOnly: true })
+    const since = Date.now() - days * 86_400_000
+    const rows = db.prepare('SELECT data FROM message WHERE time_created >= ?').all(since)
+    db.close()
+
+    const byAgent = new Map()
+    for (const row of rows) {
+      try {
+        const outer = JSON.parse(String(row.data))
+        const info = typeof outer.data === 'string' ? JSON.parse(outer.data) : outer
+        if (info.role !== 'assistant') continue
+        const agent = typeof info.agent === 'string' && info.agent !== '' ? info.agent : null
+        if (!agent) continue
+        const costUsd = Number(info.cost) || 0
+        const tokensInput = Number(info.tokens?.input) || 0
+        const tokensOutput = Number(info.tokens?.output) || 0
+        const acc = byAgent.get(agent) ?? { agent, costUsd: 0, tokensInput: 0, tokensOutput: 0 }
+        acc.costUsd += costUsd
+        acc.tokensInput += tokensInput
+        acc.tokensOutput += tokensOutput
+        byAgent.set(agent, acc)
+      } catch {
+        // Skip malformed rows — a partial ledger never breaks the report.
+      }
+    }
+    const result = [...byAgent.values()].sort((a, b) => b.costUsd - a.costUsd)
+    process.stdout.write(JSON.stringify({ ok: true, days, rows: result }))
+  } catch (err) {
+    fail(err instanceof Error ? err.message : String(err))
+  }
+}
+
+main()

package/scripts/install/opencode.mjs

@@ -84,6 +84,28 @@ function mergeMissing(target, source) {
   return target
 }
 
+/**
+ * Resolve a plugin ref from the packaged opencode.json to a path INSIDE the
+ * installed package.
+ *
+ * The packaged config may reference plugins via developer-machine absolute
+ * paths (e.g. /home/<dev>/pantheon/src/plugin.ts). Copying those verbatim into
+ * the user's config would break every install on any other machine. This
+ * rewrites the entry to the plugin file inside the INSTALLED package (derived
+ * from ROOT — never hardcoded), so both dev and global installs resolve to a
+ * path that actually exists.
+ */
+export function resolveInstalledPlugin(plugin) {
+  // Map any ref whose path tail starts with `src/` to the matching file INSIDE
+  // the installed package. This preserves the ref's relative location, so both
+  // src/plugins/* (hooks) and the root-level src/plugin.ts (delegation plugin,
+  // PR #45) resolve correctly — nothing is forced into src/plugins/.
+  const srcIndex = plugin.indexOf('src/')
+  if (srcIndex === -1) return plugin
+  const packaged = join(ROOT, plugin.slice(srcIndex))
+  return existsSync(packaged) ? packaged : plugin
+}
+
 /**
  * Detect whether `target` is the user's global OpenCode installation directory
  * (~/.opencode or $XDG_CONFIG_HOME/opencode).
@@ -578,19 +600,15 @@ export async function installOpenCode(
   // --------------------------------------------------------------------
   // B.5.1 Hermetic plugin resolution (packaging fix)
   // --------------------------------------------------------------------
-  // The packaged opencode.json may reference the pantheon-hooks plugin via a
-  // developer-machine absolute path (e.g. /home/<dev>/pantheon/src/plugins/...).
-  // Copying that verbatim into the user's config would break every global
-  // install on any other machine. Option A: rewrite the entry to the plugin
+  // The packaged opencode.json may reference plugins via developer-machine
+  // absolute paths (e.g. /home/<dev>/pantheon/src/plugin.ts or
+  // /home/<dev>/pantheon/src/plugins/pantheon-hooks.ts). Copying those
+  // verbatim into the user's config would break every global install on any
+  // other machine. resolveInstalledPlugin() rewrites each entry to the plugin
   // file inside the INSTALLED package (derived from ROOT — never hardcoded),
   // so both dev and global installs resolve to a path that actually exists.
   // The source opencode.json keeps its dev path for local development; the
   // transform happens at install/sync time only.
-  function resolveInstalledPlugin(plugin) {
-    const file = basename(plugin)
-    const packaged = join(ROOT, 'src', 'plugins', file)
-    return existsSync(packaged) ? packaged : plugin
-  }
 
   if (!Array.isArray(config.plugin)) {
     config.plugin = []

package/src/agents/zeus.md

@@ -144,6 +144,30 @@ task_status(task_id="ses_xxx", wait=true)
   -> bloqueia ate completar: { state: "completed", task_result: "..." }
 ```
 
+### Pantheon Delegation Tools (plugin) — 3-tool API
+
+O plugin Pantheon adiciona 3 tools de delegacao gerenciada pelo BackgroundJobBoard:
+
+```
+pantheon_delegate({prompt, agent, description?, read_only?})
+  -> cria sessao filha, registra no board, retorna alias: [apo-1]
+pantheon_delegation_read({id: "apo-1"})
+  -> BLOQUEIA ate o job terminar, retorna o report markdown, marca reconciled
+pantheon_delegation_list()
+  -> lista jobs da sessao, com [unread] para jobs terminados nao lidos
+```
+
+- **Read-only enforcement:** agentes read-only (apollo, gaia — `read_only_agents` no routing.yml) tem `edit`, `write`, `bash`, `task` NEGADOS dentro da sessao delegada (o guard de `tool.execute.before` THROW com mensagem acionavel). Use `read_only: true` no delegate para qualquer agente de investigacao.
+- **Depth-2 hard-enforced:** sessao read-only NAO cria subagentes (`task` bloqueado) — investigacao nunca vira arvore.
+- **Compactacao:** jobs em voo (running + unread terminal) sao injetados no contexto de compactacao via `experimental.session.compacting` — delegacao em andamento nao se perde ao compactar.
+
+### DELEGATION_RULES (plugin path)
+
+1. **NUNCA** polle `pantheon_delegation_list` para checar se um job terminou.
+2. Voce SERA notificado via `task-notification` injetado no chat quando um job atinge estado terminal.
+3. Use `pantheon_delegation_read({id})` APENAS para fan-in explicito / recuperacao de resultado sob demanda (bloqueia ate o fim).
+4. `pantheon_delegation_list` e para diagnostico, nao para polling.
+
 ### Background (sempre usar)
 - **Apollo, Hermes, Aphrodite, Demeter, Hephaestus, Prometheus**
 - Dispare em waves paralelas: ate 5 concorrentes
@@ -256,3 +280,55 @@ Wave: dispare N, colete com tolerancia a falha
     catch:
       r = retry(agente, prompt_alternativo)
 ```
+
+### Plugin Enforcer (auto — session.idle hook)
+O plugin re-injeta "Incomplete tasks remain..." em sessões root/não-board que
+vão a idle com todos incompletos. Guards (todos no `src/pantheon/todo-enforcer.ts`):
+- **User-activity (30s)** — após uma mensagem do usuário (`chat.message` hook),
+  a injeção é suprimida por `user_activity_quiet_ms: 30000`.
+- **Board-running** — sessão com job background do nosso board em running → skip.
+- **Native-children (2 min)** — children de `task(background=true)` do opencode
+  NÃO estão no nosso board; o enforcer consulta `session.children()` e pula se
+  algum child tiver `time.updated` mais novo que `child_active_ms: 120000`
+  (background task nativo ainda rodando). API indisponível → fail-open (log + injeta).
+- **Kill-switch**: `PANTHEON_TODO_ENFORCER=off` desativa o enforcer por completo
+  (lido na construção do plugin). routing.yml é espelho de documentação — o env
+  var é o switch real (precedente COMPACTION_MAX_ITEMS).
+
+## Wave 4 (PR #46): Empty-Result Retry + /cost + Themis Tier
+
+### Empty-Result Retry (dispatch-guard — MANUAL orchestration)
+OpenCode 1.18.x NAO permite interceptar a conclusao de `task()` via hooks,
+entao o `src/pantheon/dispatch-guard.ts` e uma lib pura usada POR VOCE na
+orquestracao (NAO esta wired no plugin):
+
+```
+import { createDispatchGuard } from '.../src/pantheon/dispatch-guard.ts'  # via code-mode ou subagente
+
+guard = createDispatchGuard({ retryOnEmpty: true, logger: { warn: console.warn } })
+
+# classificar resultado de task_status/wait:
+#   'content'      → tem texto, pronto
+#   'empty-mode1'  → SEM texto E SEM tokens (nada voltou)      → RETRY 1x
+#   'empty-mode2'  → SEM texto, MAS tokens (raciocinou, perdeu a parte de texto;
+#                    assinatura da falha themis Wave-2)         → RETRY 1x
+
+out = await guard.maybeRetry(result, async () => { ...task() de novo... })
+# out.retried=true se redisparou; CAP DURO de 1 retry — nunca 2x.
+# Se o retry voltar vazio, `out.retried=false` — NAO tente de novo: escale.
+```
+Regra: retry 1x APENAS em `empty-mode1`/`empty-mode2`. Resultado com conteudo
+nunca redispara. Apos 1 retry vazio → escalate (mesma regra do TODO Enforcer).
+
+### /cost — pantheon_cost tool (WIRED no plugin)
+`pantheon_cost({ days?: number })` le o `opencode.db` READ-ONLY (node:sqlite;
+fallback `scripts/cost.mjs`) e devolve tabela markdown de custo + tokens por
+agente nos ultimos N dias (default 7). Uso: quando Nyx pedir visibilidade de
+custo, ou antes de escalar tier — decida se o batch valeu o preco.
+
+### Themis Tier Policy (routing.yml go-deepseek)
+Revisoes de FASE do themis rodam em `opencode/deepseek-v4-flash`
+(review rapido, barato — evita a assinatura empty-mode2 de retorno vazio).
+O tier PRO (`deepseek-v4-pro`) fica RESERVADO para o FINAL GATE (auditoria
+final apos tudo aprovado) — override manual na hora. Athena NAO muda:
+planner continua em pro.

package/src/pantheon/background-job-board.ts

@@ -129,6 +129,13 @@ export interface PersistenceAdapter {
   deleteJob(taskID: string): Promise<void>
 }
 
+/** A pending `waitForTerminal()` registration for a taskID. */
+interface TerminalWaiter {
+  resolve: (job: BackgroundJobRecord) => void
+  reject: (err: Error) => void
+  timer: NodeJS.Timeout
+}
+
 // ─── Agent Prefix Mapping ──────────────────────────────────────────────
 
 const AGENT_PREFIXES: Record<string, string> = {
@@ -171,6 +178,7 @@ export class BackgroundJobBoard {
    */
   private readonly aliasCounters: Map<string, Map<string, number>> = new Map()
   private readonly terminalListeners: Set<(taskID: string) => void> = new Set()
+  private readonly terminalWaiters: Map<string, TerminalWaiter[]> = new Map()
   private readonly options: Required<BoardOptions>
   private persistence: PersistenceAdapter | null = null
 
@@ -460,6 +468,65 @@ export class BackgroundJobBoard {
     this.terminalListeners.delete(listener)
   }
 
+  /**
+   * Resolve with the job record once the job reaches a terminal state
+   * (`completed`, `error`, `cancelled`, or `reconciled`), or reject with a
+   * timeout error if `timeoutMs` elapses first.
+   *
+   * Resolves immediately when the job is already terminal at call time.
+   * Multiple concurrent waiters for the same taskID all resolve.
+   */
+  waitForTerminal(taskID: string, timeoutMs: number): Promise<BackgroundJobRecord> {
+    const existing = this.jobs.get(taskID)
+    if (existing && (TERMINAL_STATES.has(existing.state) || existing.state === 'reconciled')) {
+      return Promise.resolve(existing)
+    }
+
+    return new Promise<BackgroundJobRecord>((resolve, reject) => {
+      const waiter: TerminalWaiter = {
+        resolve,
+        reject,
+        timer: setTimeout(() => {
+          this.removeTerminalWaiter(taskID, waiter)
+          reject(
+            new Error(
+              `Timed out after ${timeoutMs}ms waiting for job ${taskID} to reach a terminal state`,
+            ),
+          )
+        }, timeoutMs),
+      }
+      const waiters = this.terminalWaiters.get(taskID) ?? []
+      waiters.push(waiter)
+      this.terminalWaiters.set(taskID, waiters)
+    })
+  }
+
+  private removeTerminalWaiter(taskID: string, waiter: TerminalWaiter): void {
+    const waiters = this.terminalWaiters.get(taskID)
+    if (!waiters) return
+    const idx = waiters.indexOf(waiter)
+    if (idx < 0) return
+    waiters.splice(idx, 1)
+    if (waiters.length === 0) {
+      this.terminalWaiters.delete(taskID)
+    }
+  }
+
+  private resolveTerminalWaiters(taskID: string): void {
+    const waiters = this.terminalWaiters.get(taskID)
+    if (!waiters) return
+    this.terminalWaiters.delete(taskID)
+    const job = this.jobs.get(taskID)
+    for (const waiter of waiters) {
+      clearTimeout(waiter.timer)
+      if (job) {
+        waiter.resolve(job)
+      } else {
+        waiter.reject(new Error(`Job ${taskID} was removed before reaching a terminal state`))
+      }
+    }
+  }
+
   // ─── Prompt Integration ──────────────────────────────────────────────
 
   /**
@@ -491,16 +558,25 @@ export class BackgroundJobBoard {
   // ─── Cleanup ─────────────────────────────────────────────────────────
 
   /**
-   * Remove jobs whose `updatedAt` is older than `ttlMs` milliseconds
-   * from the current time.
+   * Remove jobs whose `updatedAt` is older than `ttlMs` milliseconds.
+   *
+   * Only TERMINAL (completed/error/cancelled) and reconciled jobs are pruned —
+   * running jobs are never pruned. Each pruned job is also removed from the
+   * persistence adapter so it doesn't resurface after a restart.
    */
-  pruneExpired(ttlMs: number): void {
+  async pruneExpired(ttlMs: number): Promise<void> {
     const now = Date.now()
-    for (const [taskID, job] of this.jobs) {
-      if (now - job.updatedAt > ttlMs) {
-        this.jobs.delete(taskID)
+    const expired: BackgroundJobRecord[] = []
+    for (const job of this.jobs.values()) {
+      const isDone = TERMINAL_STATES.has(job.state) || job.state === 'reconciled'
+      if (isDone && now - job.updatedAt > ttlMs) {
+        expired.push(job)
       }
     }
+    for (const job of expired) {
+      this.jobs.delete(job.taskID)
+      await this.deletePersisted(job.taskID)
+    }
   }
 
   /** Remove all jobs belonging to a parent session. */
@@ -526,6 +602,18 @@ export class BackgroundJobBoard {
     }
   }
 
+  private async deletePersisted(taskID: string): Promise<void> {
+    if (!this.persistence) return
+    try {
+      await this.persistence.deleteJob(taskID)
+    } catch (err) {
+      console.error(
+        `[BackgroundJobBoard] Failed to delete persisted job ${taskID}:`,
+        err,
+      )
+    }
+  }
+
   private notifyTerminal(taskID: string): void {
     for (const listener of this.terminalListeners) {
       try {
@@ -537,6 +625,7 @@ export class BackgroundJobBoard {
         )
       }
     }
+    this.resolveTerminalWaiters(taskID)
   }
 
   private async writeSignal(record: BackgroundJobRecord): Promise<void> {

package/src/pantheon/cost-command.ts

@@ -0,0 +1,208 @@
+/**
+ * Cost Command (Wave 4, PR #46) — `pantheon_cost` structural tool: cost +
+ * token visibility for delegation traffic, straight from opencode.db.
+ *
+ * Reads the opencode session database READ-ONLY (sum cost + tokens by
+ * agent over the last N days → markdown table). Zero new dependencies:
+ *   - primary path: node:sqlite (DatabaseSync, readOnly) — node ≥ 22.5;
+ *   - fallback: spawn scripts/cost.mjs (node:sqlite, prints JSON) when the
+ *     direct import is unavailable;
+ *   - missing/unreadable db → FRIENDLY error string, never a crash (tools
+ *     return errors as TEXT).
+ *
+ * dbPath resolution: explicit option > env PANTHEON_COST_DB > XDG data
+ * home > ~/.local/share/opencode/opencode.db. The tool is wired in
+ * plugin.ts alongside the delegation toolset (usable by zeus and any agent
+ * with tool access — no routing change needed).
+ *
+ * @module cost-command
+ */
+import { execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+import { z } from 'zod'
+
+import type { ToolContextLike } from './delegation.ts'
+
+const execFileAsync = promisify(execFile)
+
+/** One aggregated cost row (per agent). */
+export interface CostRow {
+  agent: string
+  costUsd: number
+  tokensInput: number
+  tokensOutput: number
+}
+
+export interface CostCommandOptions {
+  /** Explicit db path (testability / unusual installs). Default: resolved candidates. */
+  dbPath?: string
+}
+
+/** One cost tool: description + zod args shape + execute (delegation.ts shape). */
+export interface CostTool<Args extends z.ZodRawShape = typeof costArgs> {
+  description: string
+  args: Args
+  execute(args: z.infer<z.ZodObject<Args>>, ctx: ToolContextLike): Promise<string>
+}
+
+export interface CostCommand {
+  pantheon_cost: CostTool
+}
+
+const costArgs = {
+  days: z
+    .number()
+    .int()
+    .min(1)
+    .max(365)
+    .optional()
+    .describe('Number of days of delegation history to include (default 7).'),
+} satisfies z.ZodRawShape
+
+/** Resolve candidate db paths in priority order (env override first). */
+function dbCandidates(): string[] {
+  const candidates: string[] = []
+  const env = process.env.PANTHEON_COST_DB
+  if (env !== undefined && env !== '') candidates.push(env)
+  const xdg = process.env.XDG_DATA_HOME
+  const dataHome = xdg !== undefined && xdg !== '' ? xdg : join(homedir(), '.local', 'share')
+  candidates.push(join(dataHome, 'opencode', 'opencode.db'))
+  return candidates
+}
+
+/**
+ * First existing db path, or undefined. An EXPLICIT override shadows the
+ * candidate list entirely (testability: a fake path must not fall through
+ * to the real opencode.db).
+ */
+function findExistingDb(override?: string): string | undefined {
+  const candidates = override !== undefined && override !== '' ? [override] : dbCandidates()
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate
+  }
+  return undefined
+}
+
+/** Aggregate cost + tokens by agent via node:sqlite (read-only). */
+async function queryWithNodeSqlite(dbPath: string, days: number): Promise<CostRow[]> {
+  const sqlite = await import('node:sqlite')
+  const db = new sqlite.DatabaseSync(dbPath, { readOnly: true })
+  try {
+    const since = Date.now() - days * 86_400_000
+    const rows = db.prepare('SELECT data FROM message WHERE time_created >= ?').all(since)
+    return aggregateMessages(rows.map((row) => String(row.data)))
+  } finally {
+    db.close()
+  }
+}
+
+/** Fallback: delegate the same aggregation to scripts/cost.mjs (node:sqlite). */
+async function queryWithScript(
+  scriptPath: string,
+  dbPath: string,
+  days: number,
+): Promise<CostRow[]> {
+  const { stdout } = await execFileAsync(process.execPath, [scriptPath, dbPath, String(days)], {
+    timeout: 15_000,
+    encoding: 'utf8',
+  })
+  const parsed = JSON.parse(stdout) as { ok: boolean; rows?: CostRow[]; error?: string }
+  if (!parsed.ok) throw new Error(parsed.error ?? 'cost.mjs failed')
+  return parsed.rows ?? []
+}
+
+/** Parse message.data JSON rows and aggregate cost + tokens by assistant agent. */
+function aggregateMessages(dataValues: readonly string[]): CostRow[] {
+  const byAgent = new Map<string, CostRow>()
+  for (const value of dataValues) {
+    try {
+      const outer = JSON.parse(value) as Record<string, unknown>
+      // The message row wraps the payload in a nested JSON string; when it
+      // is not a string, the row IS the payload (either way: flat info).
+      const info =
+        typeof outer.data === 'string' ? (JSON.parse(outer.data) as Record<string, unknown>) : outer
+      if (info.role !== 'assistant') continue
+      const agent = typeof info.agent === 'string' && info.agent !== '' ? info.agent : null
+      if (agent === null) continue
+      const costUsd = Number(info.cost) || 0
+      const tokens = (info.tokens ?? {}) as Record<string, unknown>
+      const tokensInput = Number(tokens.input) || 0
+      const tokensOutput = Number(tokens.output) || 0
+      const acc = byAgent.get(agent) ?? { agent, costUsd: 0, tokensInput: 0, tokensOutput: 0 }
+      acc.costUsd += costUsd
+      acc.tokensInput += tokensInput
+      acc.tokensOutput += tokensOutput
+      byAgent.set(agent, acc)
+    } catch {
+      // Skip malformed rows — a partial ledger never breaks the report.
+    }
+  }
+  return [...byAgent.values()].sort((a, b) => b.costUsd - a.costUsd)
+}
+
+/** Render the aggregate as a markdown table with a total row. */
+function renderMarkdown(rows: readonly CostRow[], days: number): string {
+  if (rows.length === 0) {
+    return `## Cost by agent (last ${days} days)\n\nNo cost records in the last ${days} days.`
+  }
+  const total = rows.reduce(
+    (acc, r) => {
+      acc.costUsd += r.costUsd
+      acc.tokensInput += r.tokensInput
+      acc.tokensOutput += r.tokensOutput
+      return acc
+    },
+    { costUsd: 0, tokensInput: 0, tokensOutput: 0 },
+  )
+  const lines = [
+    `## Cost by agent (last ${days} days)`,
+    '',
+    '| Agent | Cost (USD) | Tokens In | Tokens Out |',
+    '|-------|-----------:|----------:|-----------:|',
+    ...rows.map(
+      (r) => `| ${r.agent} | $${r.costUsd.toFixed(6)} | ${r.tokensInput} | ${r.tokensOutput} |`,
+    ),
+    `| **Total** | **$${total.costUsd.toFixed(6)}** | **${total.tokensInput}** | **${total.tokensOutput}** |`,
+    '',
+    `Source: opencode.db (read-only)`,
+  ]
+  return lines.join('\n')
+}
+
+export function createCostCommand(options?: CostCommandOptions): CostCommand {
+  const scriptPath = new URL('../../scripts/cost.mjs', import.meta.url).pathname
+
+  const execute = async (args: { days?: number }, _ctx: ToolContextLike): Promise<string> => {
+    const days = args.days ?? 7
+    try {
+      const dbPath = findExistingDb(options?.dbPath)
+      if (dbPath === undefined) {
+        const expected =
+          options?.dbPath ?? process.env.PANTHEON_COST_DB ?? '~/.local/share/opencode/opencode.db'
+        return (
+          `pantheon_cost failed: opencode.db not found (expected at ${expected}). ` +
+          `No cost history is available until opencode has stored session data.`
+        )
+      }
+      const rows = await queryWithNodeSqlite(dbPath, days).catch(async () =>
+        queryWithScript(scriptPath, dbPath, days),
+      )
+      return renderMarkdown(rows, days)
+    } catch (err: unknown) {
+      const reason = err instanceof Error ? err.message : String(err)
+      return `pantheon_cost failed: ${reason}`
+    }
+  }
+
+  return {
+    pantheon_cost: {
+      description:
+        'Report delegation cost + token usage by agent over the last N days, read from opencode.db (read-only, no writes).',
+      args: costArgs,
+      execute,
+    },
+  }
+}