pantheon-opencode 1.3.2 → 1.3.4

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,
+    },
+  }
+}

package/src/pantheon/cost-tracker.ts

@@ -0,0 +1,108 @@
+/**
+ * Cost Tracker (Wave 4, PR #46) — JSONL cost ledger for background
+ * delegations. Every delegation that finishes (or times out) records one
+ * line; the ledger lives at `.pantheon/costs/delegations.jsonl` and gives
+ * Nyx / the /cost command a durable, human-readable cost history.
+ *
+ * record() APPENDS (appendFile + parent dir auto-create), never rewrites.
+ * A missing ledger is an EMPTY ledger — list() → [], summary() → zeros,
+ * no crash. Injectable clock not needed: timestamp is caller-provided
+ * (ISO 8601), matching the delegation toolset's timestamping style.
+ *
+ * @module cost-tracker
+ */
+import { appendFile, mkdir, readFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+/** One delegation cost event. */
+export interface CostRecord {
+  /** Board task ID (e.g. "ses_child_1" or the job alias "apo-1"). */
+  taskId: string
+  /** Session that owns the delegation — list(sessionID?) filters on this. */
+  sessionID?: string
+  /** Delegated agent name (e.g. "hermes"). */
+  agent: string
+  /** Model ID actually used (e.g. "opencode/deepseek-v4-flash"). */
+  model: string
+  tokensInput: number
+  tokensOutput: number
+  /** Cost in USD (already computed by the caller). */
+  costUsd: number
+  /** ISO 8601 timestamp of the record. */
+  timestamp: string
+}
+
+/** Aggregate across the whole ledger. */
+export interface CostSummary {
+  count: number
+  totalCostUsd: number
+  totalTokensInput: number
+  totalTokensOutput: number
+}
+
+export interface CostTrackerOptions {
+  /** Ledger path. Default: ".pantheon/costs/delegations.jsonl". */
+  filePath?: string
+}
+
+export interface CostTracker {
+  /** Append one record to the ledger (creates the parent dir on first write). */
+  record(entry: CostRecord): Promise<void>
+  /** All records, optionally filtered by sessionID. Missing file → []. */
+  list(sessionID?: string): Promise<CostRecord[]>
+  /** Aggregate totals across the whole ledger. Missing file → zeros. */
+  summary(): Promise<CostSummary>
+}
+
+/** Parse the ledger file; missing file → empty array (never throws). */
+async function readLedger(filePath: string): Promise<CostRecord[]> {
+  let raw: string
+  try {
+    raw = await readFile(filePath, 'utf8')
+  } catch {
+    return []
+  }
+  const records: CostRecord[] = []
+  for (const line of raw.split('\n')) {
+    if (line.trim() === '') continue
+    try {
+      records.push(JSON.parse(line) as CostRecord)
+    } catch {
+      // Skip malformed lines — a partial ledger never breaks the reader.
+    }
+  }
+  return records
+}
+
+export function createCostTracker(options?: CostTrackerOptions): CostTracker {
+  const filePath = options?.filePath ?? '.pantheon/costs/delegations.jsonl'
+
+  return {
+    async record(entry: CostRecord): Promise<void> {
+      await mkdir(dirname(filePath), { recursive: true })
+      await appendFile(filePath, `${JSON.stringify(entry)}\n`, 'utf8')
+    },
+
+    async list(sessionID?: string): Promise<CostRecord[]> {
+      const records = await readLedger(filePath)
+      if (sessionID === undefined) return records
+      return records.filter((r) => r.sessionID === sessionID)
+    },
+
+    async summary(): Promise<CostSummary> {
+      const records = await readLedger(filePath)
+      const summary: CostSummary = {
+        count: records.length,
+        totalCostUsd: 0,
+        totalTokensInput: 0,
+        totalTokensOutput: 0,
+      }
+      for (const r of records) {
+        summary.totalCostUsd += r.costUsd
+        summary.totalTokensInput += r.tokensInput
+        summary.totalTokensOutput += r.tokensOutput
+      }
+      return summary
+    },
+  }
+}

package/src/pantheon/delegation-compaction.ts

@@ -0,0 +1,237 @@
+/**
+ * Compaction Context (Phase 4 + release-134 Phase 2) — build the context
+ * blocks injected by the `experimental.session.compacting` hook so a
+ * compacted session does not lose its working state: in-flight background
+ * delegations, active goals and pending todos.
+ *
+ * Returns a Promise<string[]> (empty when there is nothing to preserve).
+ * Section order is stable:
+ *   - "<pantheon-context directive>" — preservation directive (prefix,
+ *     PANTHEON_COMPACTION_DIRECTIVE). Emitted whenever at least one other
+ *     section follows; a totally-empty state returns [] (an orphan
+ *     directive is noise).
+ *   - "<mission_context>" — active (non-done) goals from `opts.goals`:
+ *     "  [id] objective — status". Omitted when the goal source is absent,
+ *     disabled, unscoped (no sessionID), fails, or has no active goals.
+ *   - "<todo_context>" — pending (not completed/cancelled) todos from
+ *     `opts.todos`: "  [id] description — status". Omitted when the todo
+ *     source is absent, disabled, unscoped (no sessionID), fails, or has
+ *     no pending todos.
+ *   - "Background Delegations (running):" — every running job launched by
+ *     the session (active work is never capped): alias, agent, started ISO,
+ *     truncated prompt.
+ *   - "Background Delegations (finished, unread):" — terminal-unreconciled
+ *     jobs, newest first, capped at `maxItems` (default 10, matching
+ *     routing.yml background_delegation.max_compaction_items).
+ *
+ * Reconciled jobs are excluded — they have been read already.
+ *
+ * The block style mirrors board.formatForPrompt ("  [alias] description —
+ * STATUS") so compaction context reads consistently with the system prompt,
+ * but with the extra id/agent/started detail the compaction hook needs.
+ *
+ * @module delegation-compaction
+ */
+
+import type { BackgroundJobBoard, BackgroundJobRecord } from './background-job-board.ts'
+import type { Goal } from './goal-store.ts'
+import { createPantheonLogger } from './logger.ts'
+import type { TodoLike } from './todo-enforcer.ts'
+
+// Silence-by-default TUI policy (pantheon-hooks L42-58): the default warn
+// fallback logs to .pantheon/logs/hooks.log; console echo is opt-in via
+// PANTHEON_HOOKS_LOG=1. `deps.logger` injection stays for tests.
+const log = createPantheonLogger({ module: 'pantheon-compaction' })
+
+// ─── Constants ─────────────────────────────────────────────────────────
+
+/**
+ * Preservation directive (release-134 Phase 2): the native compaction
+ * prompt keeps every pushed section, so this prefix asks the model to keep
+ * the pantheon sections verbatim — not paraphrased, merged, or dropped.
+ */
+export const PANTHEON_COMPACTION_DIRECTIVE =
+  'preserve these sections verbatim in the summarized context'
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Source for the <mission_context> section (active goals). */
+export interface CompactionGoalSource {
+  /** True when the goal loop is enabled; false/undefined → section omitted. */
+  enabled: boolean
+  /** List the session's goals (any status; the builder keeps non-done). */
+  list(sessionID: string): Promise<Goal[]>
+}
+
+/** Source for the <todo_context> section (pending todos). */
+export interface CompactionTodoSource {
+  /** True when the todo enforcer is enabled; false/undefined → section omitted. */
+  enabled: boolean
+  /** List the session's todos (any status; the builder keeps pending). */
+  list(sessionID: string): Promise<TodoLike[]>
+}
+
+export interface CompactionContextOptions {
+  /** Scope to jobs launched by this session; omit for all jobs. */
+  sessionID?: string
+  /** Cap on unread terminal jobs kept (default 10). */
+  maxItems?: number
+  /** Goal source for <mission_context> (optional — omitted when absent). */
+  goals?: CompactionGoalSource
+  /** Todo source for <todo_context> (optional — omitted when absent). */
+  todos?: CompactionTodoSource
+}
+
+/** Prompt truncation length for a context line. */
+const PROMPT_MAX_LEN = 100
+
+// ─── Formatting ────────────────────────────────────────────────────────
+
+/** Collapse whitespace and truncate a prompt to PROMPT_MAX_LEN chars. */
+function truncatePrompt(text: string): string {
+  const flat = text.trim().replace(/\s+/g, ' ')
+  if (flat.length <= PROMPT_MAX_LEN) return flat
+  return `${flat.slice(0, PROMPT_MAX_LEN)}…`
+}
+
+/** One-line terminal status label, mirroring formatForPrompt. */
+function terminalLabel(state: BackgroundJobRecord['state']): string {
+  switch (state) {
+    case 'completed':
+      return 'OK'
+    case 'error':
+      return 'ERR'
+    case 'cancelled':
+      return 'CAN'
+    default:
+      return state.toUpperCase()
+  }
+}
+
+function runningLine(job: BackgroundJobRecord): string {
+  return (
+    `  [${job.alias}] ${job.agent} — ${truncatePrompt(job.description)} — ` +
+    `RUNNING since ${new Date(job.launchedAt).toISOString()}`
+  )
+}
+
+function unreadTerminalLine(job: BackgroundJobRecord): string {
+  return (
+    `  [${job.alias}] ${job.agent} — ${truncatePrompt(job.description)} — ` +
+    `${terminalLabel(job.state)} ${new Date(job.updatedAt).toISOString()} [unread]`
+  )
+}
+
+// ─── Sections ──────────────────────────────────────────────────────────
+
+/**
+ * `<mission_context>` — active (non-done) goals for the session.
+ * Returns undefined when the section must be omitted: no goal source, the
+ * goal loop is disabled, no sessionID (per-session data cannot be scoped),
+ * the source throws (logged, fail-open), or no active goals remain.
+ */
+async function missionContextBlock(opts: CompactionContextOptions): Promise<string | undefined> {
+  const source = opts.goals
+  if (opts.sessionID === undefined || source === undefined || !source.enabled) return undefined
+
+  let goals: Goal[]
+  try {
+    goals = await source.list(opts.sessionID)
+  } catch (err: unknown) {
+    const reason = err instanceof Error ? err.message : String(err)
+    log.warn(`compaction goal context failed for session ${opts.sessionID}: ${reason}`)
+    return undefined
+  }
+
+  const active = goals.filter((goal) => goal.status !== 'done')
+  if (active.length === 0) return undefined
+
+  const lines = active.map((goal) => `  [${goal.id}] ${goal.objective} — ${goal.status}`)
+  return `<mission_context>\n${lines.join('\n')}`
+}
+
+/**
+ * `<todo_context>` — pending (not completed/cancelled) todos for the
+ * session. Returns undefined when the section must be omitted: no todo
+ * source, the enforcer is disabled, no sessionID, the source throws
+ * (logged, fail-open), or no pending todos remain.
+ */
+async function todoContextBlock(opts: CompactionContextOptions): Promise<string | undefined> {
+  const source = opts.todos
+  if (opts.sessionID === undefined || source === undefined || !source.enabled) return undefined
+
+  let todos: TodoLike[]
+  try {
+    todos = await source.list(opts.sessionID)
+  } catch (err: unknown) {
+    const reason = err instanceof Error ? err.message : String(err)
+    log.warn(`compaction todo context failed for session ${opts.sessionID}: ${reason}`)
+    return undefined
+  }
+
+  const pending = todos.filter((todo) => todo.status !== 'completed' && todo.status !== 'cancelled')
+  if (pending.length === 0) return undefined
+
+  const lines = pending.map((todo) => {
+    const label = todo.content?.trim() || todo.id || '(no description)'
+    const id = todo.id !== undefined && todo.id !== '' ? `[${todo.id}] ` : ''
+    return `  ${id}${label} — ${todo.status}`
+  })
+  return `<todo_context>\n${lines.join('\n')}`
+}
+
+/**
+ * `<delegation_context>` — the existing delegation blocks, byte-for-byte
+ * unchanged from Phase 4 (running, then unread terminal ≤ maxItems).
+ */
+function delegationBlocks(board: BackgroundJobBoard, opts: CompactionContextOptions): string[] {
+  const maxItems = opts.maxItems ?? 10
+  const jobs = opts.sessionID !== undefined ? board.list(opts.sessionID) : board.list()
+
+  const running = jobs
+    .filter((j) => j.state === 'running')
+    .sort((a, b) => a.launchedAt - b.launchedAt)
+  const unreadTerminal = jobs
+    .filter((j) => j.terminalUnreconciled)
+    .sort((a, b) => b.updatedAt - a.updatedAt)
+    .slice(0, maxItems)
+
+  const blocks: string[] = []
+  if (running.length > 0) {
+    blocks.push(`Background Delegations (running):\n${running.map(runningLine).join('\n')}`)
+  }
+  if (unreadTerminal.length > 0) {
+    blocks.push(
+      `Background Delegations (finished, unread):\n${unreadTerminal
+        .map(unreadTerminalLine)
+        .join('\n')}`,
+    )
+  }
+  return blocks
+}
+
+// ─── Build ─────────────────────────────────────────────────────────────
+
+/**
+ * Build the compaction context blocks for a session: preservation
+ * directive, active goals, pending todos, and in-flight background
+ * delegations. Returns an empty array when there is nothing to preserve
+ * (caller skips the hook injection entirely).
+ */
+export async function buildCompactionContext(
+  board: BackgroundJobBoard,
+  opts: CompactionContextOptions = {},
+): Promise<string[]> {
+  const [mission, todo] = await Promise.all([missionContextBlock(opts), todoContextBlock(opts)])
+  const delegation = delegationBlocks(board, opts)
+
+  // Totally-empty state → nothing to preserve; a lone directive is noise.
+  if (mission === undefined && todo === undefined && delegation.length === 0) return []
+
+  const blocks: string[] = []
+  blocks.push(`<pantheon-context directive>\n${PANTHEON_COMPACTION_DIRECTIVE}`)
+  if (mission !== undefined) blocks.push(mission)
+  if (todo !== undefined) blocks.push(todo)
+  blocks.push(...delegation)
+  return blocks
+}

package/src/pantheon/delegation-enforce.ts

@@ -0,0 +1,144 @@
+/**
+ * Read-Only Enforcement (Phase 4) — deny mutating tools inside sessions that
+ * were delegated as read-only (advisory `read_only: true` on
+ * pantheon_delegate, or the agent ∈ `readOnlyAgents` from routing.yml).
+ *
+ * OpenCode hook: `tool.execute.before`. The hook shape is
+ * `(input, output) => Promise<void>`; THROWING from the hook denies the tool
+ * call and the caller (the subagent session) sees the thrown message. This
+ * module never needs the opencode SDK — the handler is a structural closure
+ * wired from plugin.ts.
+ *
+ * Blocked tools (edit, write, bash, task, hashline_edit):
+ *   - edit/write/bash are the mutating surface — read-only agents (apollo,
+ *     gaia) must stay investigation-only.
+ *   - `hashline_edit` is the Wave 2 (PR #46) tag-anchored edit tool — it is a
+ *     write surface too, so read-only agents must not bypass enforcement via
+ *     it.
+ *   - `task` is blocked too, which hard-enforces depth-2: a read-only agent
+ *     cannot spawn its own subagents.
+ *
+ * Unknown sessions are ALLOWED by default — the guard only denies sessions
+ * that are explicitly registered, so normal (non-delegated) agent work is
+ * never blocked.
+ *
+ * The registry is populated by delegation.ts at delegate time: the CHILD
+ * session is registered when the delegate call is read-only.
+ *
+ * @module delegation-enforce
+ */
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Why a session is read-only. */
+export interface ReadOnlyEntry {
+  /** Agent name the session was delegated to (e.g. "apollo"). */
+  agent: string
+  /** Whether read_only was set explicitly on the delegate call. */
+  readOnlyFlag?: boolean
+  /** Epoch ms when the session was registered. */
+  registeredAt: number
+}
+
+/** Input the opencode `tool.execute.before` hook passes. */
+export interface ToolExecuteBeforeInput {
+  tool: string
+  sessionID: string
+  callID: string
+}
+
+/** The `tool.execute.before` handler shape (throw ⇒ deny). */
+export type ToolExecuteBeforeHandler = (input: ToolExecuteBeforeInput) => Promise<void>
+
+/** Options for createEnforcementGuard(). */
+export interface EnforcementGuardOptions {
+  /** Tools denied in read-only sessions (default: DEFAULT_BLOCKED_TOOLS). */
+  blockedTools?: ReadonlySet<string>
+  /** Prefix for the denial message. */
+  messagePrefix?: string
+}
+
+// ─── Defaults ──────────────────────────────────────────────────────────
+
+/** Mutating tools denied in read-only sessions. `task` ⇒ depth-2 guard. */
+export const DEFAULT_BLOCKED_TOOLS: ReadonlySet<string> = new Set([
+  'edit',
+  'write',
+  'bash',
+  'task',
+  'hashline_edit',
+])
+
+// ─── Registry ──────────────────────────────────────────────────────────
+
+/**
+ * Read-only session registry. `createDelegationTools` registers child
+ * sessions here; the plugin's `tool.execute.before` guard consults it.
+ * Process-wide singleton for plugin wiring + factory for test isolation.
+ */
+export class ReadOnlySessionRegistry {
+  private readonly sessions = new Map<string, ReadOnlyEntry>()
+
+  /** Register a session as read-only. Idempotent (re-registration updates). */
+  register(sessionID: string, entry: { agent: string; readOnlyFlag?: boolean }): void {
+    const record: ReadOnlyEntry = { agent: entry.agent, registeredAt: Date.now() }
+    if (entry.readOnlyFlag !== undefined) record.readOnlyFlag = entry.readOnlyFlag
+    this.sessions.set(sessionID, record)
+  }
+
+  /** Remove a session from the read-only set (dynamic revocation). */
+  unregister(sessionID: string): void {
+    this.sessions.delete(sessionID)
+  }
+
+  /** Whether the session is registered as read-only. */
+  has(sessionID: string): boolean {
+    return this.sessions.has(sessionID)
+  }
+
+  /** Snapshot of the registered entry, or undefined. */
+  get(sessionID: string): ReadOnlyEntry | undefined {
+    return this.sessions.get(sessionID)
+  }
+
+  /** Snapshot of all read-only session IDs (guards read a stable copy). */
+  sessionIDs(): ReadonlySet<string> {
+    return new Set(this.sessions.keys())
+  }
+
+  /** Remove every registration (test hygiene / plugin teardown). */
+  clear(): void {
+    this.sessions.clear()
+  }
+}
+
+/** Process-wide registry wired into the plugin. */
+export const readOnlyRegistry = new ReadOnlySessionRegistry()
+
+// ─── Guard ─────────────────────────────────────────────────────────────
+
+/**
+ * Build the `tool.execute.before` handler. Throws with an actionable message
+ * when a blocked tool is invoked from a registered read-only session; any
+ * other session (or tool) passes through untouched.
+ */
+export function createEnforcementGuard(input: {
+  getReadOnlySessions: () => ReadonlySet<string>
+  options?: EnforcementGuardOptions
+}): ToolExecuteBeforeHandler {
+  const blockedTools = input.options?.blockedTools ?? DEFAULT_BLOCKED_TOOLS
+  const prefix = input.options?.messagePrefix ?? 'pantheon_delegate guard'
+
+  return async (hook: ToolExecuteBeforeInput): Promise<void> => {
+    if (!blockedTools.has(hook.tool)) return
+    if (!input.getReadOnlySessions().has(hook.sessionID)) return
+
+    throw new Error(
+      `${prefix}: session ${hook.sessionID} is READ-ONLY — tool "${hook.tool}" is denied. ` +
+        `This session was delegated for investigation only (read-only agent); it cannot ` +
+        `modify files, run commands, or spawn subagents. ` +
+        `If a write result is needed, dispatch a write-capable agent ` +
+        `(e.g. hermes, aphrodite) with pantheon_delegate instead.`,
+    )
+  }
+}