pantheon-opencode 1.3.2 → 1.3.3

package/src/pantheon/todo-enforcer.ts

@@ -0,0 +1,369 @@
+/**
+ * TODO Enforcer (Wave 1) — keeps root/non-board sessions working on their
+ * todo list when the session goes idle.
+ *
+ * The plugin's `event` hook dispatches `session.idle`: board-child sessions go
+ * to the delegation finalize path (`handleDelegationEvent`), everything else
+ * (roots, non-board sessions) goes to `TodoEnforcer.onIdle`. The enforcer
+ * re-injects a continuation prompt when the session went idle with incomplete
+ * todos, so the agent keeps working on its task list instead of stopping.
+ *
+ * Guards (council-approved cut — latch/skipAgents/countdown-toast removed):
+ *   1. user-activity — a session whose user sent a message within
+ *      `userActivityQuietMs` is being driven interactively → skip;
+ *   2. board-running — a session with a running background job is skipped
+ *      (the parent is busy; the child session itself is never routed here);
+ *   3. native-children — opencode `task(background=true)` children are NOT on
+ *      our board, so `session.children()` is checked: an active child (its
+ *      `time.updated` newer than `childActiveMs`) means the parent is still
+ *      waiting on a native background task → skip. Throws fail open (log +
+ *      inject) so version-sensitive APIs never break the enforcer;
+ *   4. in-flight — one injection per idle, never concurrent;
+ *   5. cooldown — exponential per-session backoff `cooldownBaseMs *
+ *      2^min(failures, max)`, failures increment when an injection does not
+ *      clear todos (the next idle shows the same-or-worse incomplete count);
+ *   6. max-consecutive-failures — stop injecting after the cap; the failure
+ *      counter resets after a quiet period (`failureResetMs`) and when an
+ *      injection makes progress (streak semantics).
+ *
+ * DONE detection: all todos `completed`/`cancelled` (or no todos at all) →
+ * no injection this idle. The todo re-fetch is cheap, so no done-latch is
+ * needed.
+ *
+ * The enforcer NEVER touches the TUI (no toast — council cut: toasts are
+ * no-ops on opencode 1.18.13). It depends only on `session.todo`,
+ * `session.messages` (agent/model inheritance via the last assistant
+ * message) and `session.promptAsync`
+ * (injection).
+ *
+ * Pure TypeScript — zero runtime dependencies beyond the board types.
+ *
+ * @module todo-enforcer
+ */
+
+import type { BackgroundJobBoard } from './background-job-board.ts'
+
+// ─── Constants ─────────────────────────────────────────────────────────
+
+/**
+ * Version-controlled continuation text injected into the idle session.
+ * Exported for tests and so the routing.yml comment stays in sync.
+ */
+export const TODO_CONTINUATION_PROMPT =
+  'Incomplete tasks remain in your todo list. Continue working on them. Do not stop until all are done. If you believe all work is complete, critically re-examine whether the completion claim is verifiable.'
+
+/** Defaults matching routing.yml `todo_enforcer`. */
+export const TODO_ENFORCER_DEFAULTS = {
+  enabled: true,
+  cooldownBaseMs: 5000,
+  maxConsecutiveFailures: 5,
+  failureResetMs: 300000,
+  /** Skip injection this long after a user message in the session. */
+  userActivityQuietMs: 30000,
+  /** A native child whose `time.updated` is newer than this is still running. */
+  childActiveMs: 120000,
+} as const
+
+/**
+ * Runtime kill-switch: `PANTHEON_TODO_ENFORCER=off` disables the enforcer.
+ * Read at plugin construction — routing.yml is a doc mirror only, this env
+ * var is the real runtime switch (COMPACTION_MAX_ITEMS precedent).
+ */
+export function todoEnforcerEnabledFromEnv(
+  env: Record<string, string | undefined> = process.env,
+): boolean {
+  return (env.PANTHEON_TODO_ENFORCER ?? '').trim().toLowerCase() !== 'off'
+}
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Structural view of a session todo item (SDK Todo: status is a string). */
+export interface TodoLike {
+  content?: string
+  status: string
+  priority?: string
+  id?: string
+}
+
+/**
+ * Structural view of a child session from `session.children()` (SDK Session).
+ * Only `time.updated` is used — a running native background task keeps
+ * updating its session while streaming; a completed one freezes.
+ */
+export interface TodoEnforcerChild {
+  id: string
+  time?: { updated?: number }
+}
+
+/**
+ * Structural view of one message bundle from `session.messages()`. The SDK
+ * returns `{ info: Message, parts: Part[] }` — user messages carry `agent`
+ * on `info`, assistant messages carry `providerID`/`modelID` (or a `model`
+ * object).
+ */
+export interface TodoEnforcerMessage {
+  info?: {
+    role?: string
+    agent?: string
+    model?: { providerID?: string; modelID?: string }
+    providerID?: string
+    modelID?: string
+  }
+  parts?: Array<{ type?: string; text?: string }>
+}
+
+/** Structural client surface — the subset of the SDK the enforcer uses. */
+export interface TodoEnforcerClient {
+  session: {
+    todo(input: { path: { id: string } }): Promise<TodoLike[]>
+    messages(input: { path: { id: string } }): Promise<TodoEnforcerMessage[]>
+    children(input: { path: { id: string } }): Promise<TodoEnforcerChild[]>
+    promptAsync(input: {
+      path: { id: string }
+      body: {
+        agent?: string
+        model?: { providerID: string; modelID: string }
+        parts: Array<{ type: 'text'; text: string }>
+      }
+    }): Promise<unknown>
+  }
+}
+
+/** Tunables (all optional — see TODO_ENFORCER_DEFAULTS). */
+export interface TodoEnforcerOptions {
+  enabled?: boolean
+  /** Base cooldown after a failed injection; doubles per failure. */
+  cooldownBaseMs?: number
+  /** Stop injecting after this many consecutive failures. */
+  maxConsecutiveFailures?: number
+  /** Quiet period after which the failure counter resets. */
+  failureResetMs?: number
+  /** Skip injection while a user message is more recent than this. */
+  userActivityQuietMs?: number
+  /** Native child sessions newer than this are considered active/running. */
+  childActiveMs?: number
+  /** Injectable clock (testable), defaults to `Date.now`. */
+  now?: () => number
+}
+
+/** Dependencies threaded to the enforcer (structural board — list only). */
+export interface TodoEnforcerDeps {
+  client: TodoEnforcerClient
+  board: Pick<BackgroundJobBoard, 'list'>
+  options?: TodoEnforcerOptions
+  logger?: { warn: (message: string) => void }
+}
+
+type InheritedContext = {
+  agent?: string
+  model?: { providerID: string; modelID: string }
+}
+
+// ─── TodoEnforcer ──────────────────────────────────────────────────────
+
+/**
+ * Re-inject a continuation prompt into idle sessions that still have
+ * incomplete todos. Per-session state: last injection time, the incomplete
+ * count at injection, the pending outcome check, and the consecutive-failure
+ * counter. All guards are best-effort — `onIdle` never throws, so the event
+ * hook can never break the session.
+ */
+export class TodoEnforcer {
+  private readonly client: TodoEnforcerClient
+  private readonly board: Pick<BackgroundJobBoard, 'list'>
+  private readonly options: Required<TodoEnforcerOptions>
+  private readonly warn: (message: string) => void
+
+  /** Guard 2: sessions with an in-flight onIdle (reserved synchronously). */
+  private readonly inFlight = new Set<string>()
+  /** Last injection timestamp per session. */
+  private readonly lastInjectionAt = new Map<string, number>()
+  /** Incomplete-todo count recorded at the last injection per session. */
+  private readonly lastInjectedIncomplete = new Map<string, number>()
+  /** True when the last injection's outcome has NOT been evaluated yet. */
+  private readonly pendingCheck = new Map<string, boolean>()
+  /** Consecutive failures per session. */
+  private readonly failures = new Map<string, number>()
+  /** Last user-message timestamp per session (wired from chat.message). */
+  private readonly lastUserMessageAt = new Map<string, number>()
+
+  constructor(deps: TodoEnforcerDeps) {
+    this.client = deps.client
+    this.board = deps.board
+    const opts = deps.options ?? {}
+    this.options = {
+      enabled: opts.enabled ?? TODO_ENFORCER_DEFAULTS.enabled,
+      cooldownBaseMs: opts.cooldownBaseMs ?? TODO_ENFORCER_DEFAULTS.cooldownBaseMs,
+      maxConsecutiveFailures:
+        opts.maxConsecutiveFailures ?? TODO_ENFORCER_DEFAULTS.maxConsecutiveFailures,
+      failureResetMs: opts.failureResetMs ?? TODO_ENFORCER_DEFAULTS.failureResetMs,
+      userActivityQuietMs: opts.userActivityQuietMs ?? TODO_ENFORCER_DEFAULTS.userActivityQuietMs,
+      childActiveMs: opts.childActiveMs ?? TODO_ENFORCER_DEFAULTS.childActiveMs,
+      now: opts.now ?? Date.now,
+    }
+    this.warn =
+      deps.logger?.warn ?? ((message: string) => console.warn(`[pantheon-todo] ${message}`))
+  }
+
+  /**
+   * Record that the user just sent a message in `sessionID` (wired from the
+   * plugin `chat.message` hook). Suppresses injection for `userActivityQuietMs`
+   * — an interactive session is being driven by the user, don't nag it.
+   */
+  noteUserActivity(sessionID: string): void {
+    this.lastUserMessageAt.set(sessionID, this.options.now())
+  }
+
+  /**
+   * Handle a `session.idle` event for a non-board session. Evaluates the
+   * previous injection's outcome, applies the guards, and injects the
+   * continuation prompt when incomplete todos remain and the guards allow.
+   * Never throws — internal failures are logged and swallowed.
+   */
+  async onIdle(sessionID: string): Promise<void> {
+    if (!this.options.enabled) return
+    if (this.inFlight.has(sessionID)) return
+    this.inFlight.add(sessionID)
+    try {
+      await this.handleIdle(sessionID)
+    } catch (err: unknown) {
+      const reason = err instanceof Error ? err.message : String(err)
+      this.warn(`todo injection failed for session ${sessionID}: ${reason}`)
+    } finally {
+      this.inFlight.delete(sessionID)
+    }
+  }
+
+  private async handleIdle(sessionID: string): Promise<void> {
+    const now = this.options.now()
+
+    // Guard 1: user activity — a fresh user message means the session is being
+    // driven interactively; don't nag it.
+    const lastUser = this.lastUserMessageAt.get(sessionID)
+    if (lastUser !== undefined && now - lastUser < this.options.userActivityQuietMs) return
+
+    // Guard 2: a session with a running board job is busy — skip.
+    if (this.board.list(sessionID).some((job) => job.state === 'running')) return
+
+    // Guard 3: native background task() children are NOT on our board — an
+    // active child means the parent is still waiting on it, so skip.
+    if ((await this.activeChildren(sessionID, now)) > 0) return
+
+    const todos = await this.client.session.todo({ path: { id: sessionID } })
+    const incomplete = todos.filter(
+      (todo) => todo.status !== 'completed' && todo.status !== 'cancelled',
+    ).length
+
+    // DONE detection: nothing left to enforce. Drop any pending outcome check.
+    if (incomplete === 0) {
+      this.pendingCheck.delete(sessionID)
+      return
+    }
+
+    // Evaluate the previous injection: same-or-worse count → failure; making
+    // progress breaks the streak. Only one evaluation per injection.
+    if (this.pendingCheck.get(sessionID) === true) {
+      const before = this.lastInjectedIncomplete.get(sessionID)
+      if (before !== undefined && incomplete >= before) {
+        this.failures.set(sessionID, (this.failures.get(sessionID) ?? 0) + 1)
+      } else {
+        this.failures.set(sessionID, 0)
+      }
+      this.pendingCheck.delete(sessionID)
+    }
+
+    // Quiet-period reset: a long silence since the last injection clears the
+    // failure counter (prevents permanent lock-out).
+    const lastInjection = this.lastInjectionAt.get(sessionID)
+    if (
+      lastInjection !== undefined &&
+      (this.failures.get(sessionID) ?? 0) > 0 &&
+      now - lastInjection >= this.options.failureResetMs
+    ) {
+      this.failures.set(sessionID, 0)
+    }
+
+    const failures = this.failures.get(sessionID) ?? 0
+
+    // Guard 4: consecutive-failure cap reached → stop injecting.
+    if (failures >= this.options.maxConsecutiveFailures) return
+
+    // Guard 3: exponential cooldown since the last injection.
+    if (lastInjection !== undefined && now - lastInjection < this.cooldownMs(failures)) {
+      return
+    }
+
+    // Inject. The attempt timestamp is recorded BEFORE the call so a failed
+    // (throwing) injection still applies the cooldown — no hot retry loop.
+    this.lastInjectionAt.set(sessionID, now)
+    const inherited = await this.inheritAgentOrModel(sessionID)
+    await this.client.session.promptAsync({
+      path: { id: sessionID },
+      body: {
+        ...(inherited.agent !== undefined ? { agent: inherited.agent } : {}),
+        ...(inherited.model !== undefined ? { model: inherited.model } : {}),
+        parts: [{ type: 'text', text: TODO_CONTINUATION_PROMPT }],
+      },
+    })
+    this.lastInjectedIncomplete.set(sessionID, incomplete)
+    this.pendingCheck.set(sessionID, true)
+  }
+
+  /** Cooldown for a given failure count: base * 2^min(failures, cap). */
+  private cooldownMs(failures: number): number {
+    return (
+      this.options.cooldownBaseMs * 2 ** Math.min(failures, this.options.maxConsecutiveFailures)
+    )
+  }
+
+  /**
+   * Count active native child sessions. opencode `task(background=true)`
+   * children are NOT registered on our board, so the only way to see them is
+   * `session.children()`. A child is active while its `time.updated` is newer
+   * than `childActiveMs` — a running background task keeps updating its
+   * session while streaming; a completed one freezes. Fail-open: when the
+   * children API is unavailable (older opencode / permission), log and return
+   * 0 so the enforcer still works on version-sensitive runtimes.
+   */
+  private async activeChildren(sessionID: string, now: number): Promise<number> {
+    try {
+      const children = await this.client.session.children({ path: { id: sessionID } })
+      return children.filter((child) => {
+        const updated = child.time?.updated
+        return typeof updated === 'number' && now - updated < this.options.childActiveMs
+      }).length
+    } catch (err: unknown) {
+      const reason = err instanceof Error ? err.message : String(err)
+      this.warn(`todo children check failed for session ${sessionID}: ${reason}`)
+      return 0
+    }
+  }
+
+  /**
+   * Inherit the agent (or model) from the LAST assistant message so the
+   * continuation runs in the same context as the session's last turn. Returns
+   * an empty object when no assistant message carries usable context — the
+   * SDK then applies the session default.
+   */
+  private async inheritAgentOrModel(sessionID: string): Promise<InheritedContext> {
+    const messages = await this.client.session.messages({ path: { id: sessionID } })
+    for (const msg of [...messages].reverse()) {
+      const info = msg.info
+      if (info === undefined || info.role !== 'assistant') continue
+      if (typeof info.agent === 'string' && info.agent !== '') {
+        return { agent: info.agent }
+      }
+      const providerID = info.model?.providerID ?? info.providerID
+      const modelID = info.model?.modelID ?? info.modelID
+      if (
+        typeof providerID === 'string' &&
+        providerID !== '' &&
+        typeof modelID === 'string' &&
+        modelID !== ''
+      ) {
+        return { model: { providerID, modelID } }
+      }
+    }
+    return {}
+  }
+}

package/src/plugin.ts

@@ -1,8 +1,23 @@
 import type { Plugin, PluginInput } from '@opencode-ai/plugin'
 import type { PluginConfig } from 'opencode'
 import { BackgroundJobBoard } from './pantheon/background-job-board.ts'
+import { createCostCommand } from './pantheon/cost-command.ts'
+import { createDelegationTools, type DelegationClient } from './pantheon/delegation.ts'
+import { buildCompactionContext } from './pantheon/delegation-compaction.ts'
+import { createEnforcementGuard, readOnlyRegistry } from './pantheon/delegation-enforce.ts'
+import { DelegationNotifier, handleDelegationEvent } from './pantheon/delegation-notify.ts'
 import { FilePersistenceAdapter } from './pantheon/file-persistence.ts'
+import { GOAL_LOOP_DEFAULTS, GoalLoop, GoalStore } from './pantheon/goal-loop.ts'
+import { createReadEnhancer } from './pantheon/hashline/read-enhancer.ts'
+import { createHashlineEditTool } from './pantheon/hashline/tool.ts'
+import { createIdleDispatcher } from './pantheon/idle-continuation.ts'
 import { applyActivePresetToConfig } from './pantheon/presets.mjs'
+import {
+  TODO_ENFORCER_DEFAULTS,
+  TodoEnforcer,
+  type TodoEnforcerClient,
+  todoEnforcerEnabledFromEnv,
+} from './pantheon/todo-enforcer.ts'
 import { activePresetCandidates, createVisionHandler } from './pantheon/vision.ts'
 
 // ─── Background Job Board Singleton ────────────────────────────────────
@@ -16,15 +31,146 @@ board.setPersistence(persistence)
 board
   .recoverRunningJobs()
   .catch((err) => console.error('[Pantheon Plugin] Failed to recover running jobs:', err))
+// ─── Phase 3: Completion Notifications ────────────────────────────────
+
+// The notifier is the completion channel: the spike refuted client push
+// (noReply delivers nothing to the parent), so terminal-job notifications are
+// QUEUED here and injected into the parent's next chat.message by the flush in
+// the 'chat.message' hook below (graceful-degradation path). Gated by the same
+// env as pantheon-hooks toasts: PANTHEON_TOASTS=off disables queueing.
+const notifier = new DelegationNotifier()
+const notificationsEnabled = (process.env.PANTHEON_TOASTS ?? '').trim().toLowerCase() !== 'off'
+
 board.onTerminal((taskID: string) => {
   const job = board.get(taskID)
-  if (job) {
-    console.log(
-      `[Pantheon Plugin] Board terminal: [${job.alias}] ${job.description} → ${job.state}${job.resultSummary ? ` — ${job.resultSummary}` : ''}`,
-    )
+  if (!job) return
+  console.log(
+    `[Pantheon Plugin] Board terminal: [${job.alias}] ${job.description} → ${job.state}${job.resultSummary ? ` — ${job.resultSummary}` : ''}`,
+  )
+  // Queue the completion notification for the job's parent session. The
+  // onTerminal listener is the SINGLE notification point — the timeout path
+  // (timeout finalize → updateStatus) and the event path (session.idle →
+  // finalizeDelegation → updateStatus) both transition the board and fire
+  // here, so every terminal job (incl. timedOut) gets exactly one notification.
+  if (notificationsEnabled) {
+    notifier.notifyParent(job)
   }
 })
 
+// Periodically prune terminal/reconciled jobs (24h TTL, every 30 min).
+// pruneExpired is async and internally swallows persistence errors, so the
+// void-catch here is purely defensive. .unref() ensures the timer never
+// keeps the process alive on its own.
+setInterval(
+  () => {
+    void board
+      .pruneExpired(86_400_000)
+      .catch((err: unknown) =>
+        console.error('[Pantheon Plugin] Background board prune failed:', err),
+      )
+  },
+  30 * 60 * 1000,
+).unref()
+
+// ─── Phase 4: Read-Only Enforcement + Compaction Context ───────────────
+
+// The read-only registry is populated by createDelegationTools (delegation.ts)
+// when a delegate is read-only (explicit flag or agent ∈ readOnlyAgents).
+// The guard denies edit/write/bash/task inside those sessions by throwing
+// from tool.execute.before; unknown sessions are allowed (safe default).
+const enforcementGuard = createEnforcementGuard({
+  getReadOnlySessions: () => readOnlyRegistry.sessionIDs(),
+})
+
+// Mirrors routing.yml background_delegation.max_compaction_items.
+const COMPACTION_MAX_ITEMS = 10
+
+// Root-session registry for the delegation depth guard: sessions created
+// without a parentID are roots. Populated from `session.created` events in the
+// event hook — the authoritative complement to the knownChildren default
+// ("any session WE created is a sub-session") in delegation.ts.
+const rootSessions = new Set<string>()
+
+/** Extract the SDK error message ({name, data: {message}}) or a fallback. */
+function sdkErrorMessage(error: { data?: { message?: string } } | null | undefined): string {
+  const message = error?.data?.message
+  return typeof message === 'string' && message.trim() !== '' ? message : 'request failed'
+}
+
+/**
+ * Adapt the opencode SDK client to the structural DelegationClient the
+ * delegation toolset expects: the SDK wraps every call in a
+ * `{data, error, request, response}` result while delegation.ts uses direct
+ * returns. Errors surface as throws so the toolset's own error handling
+ * (tool errors returned as TEXT) keeps working.
+ */
+function adaptDelegationClient(client: PluginInput['client']): DelegationClient {
+  return {
+    session: {
+      create: async (input) => {
+        const body: {
+          parentID?: string
+          title?: string
+          model?: { id: string; providerID: string }
+        } = { parentID: input.body.parentID }
+        if (input.body.title !== undefined) body.title = input.body.title
+        // Forward the routed child model (E2E fix): without it the child
+        // falls back to the key-gated default model and dies at startup.
+        if (input.body.model !== undefined) body.model = input.body.model
+        const result = await client.session.create({ body })
+        if (result.error) throw new Error(sdkErrorMessage(result.error))
+        return { id: result.data.id }
+      },
+      promptAsync: async (input) => {
+        const result = await client.session.promptAsync({
+          path: input.path,
+          body: { agent: input.body.agent, parts: input.body.parts },
+        })
+        if (result.error) throw new Error(sdkErrorMessage(result.error))
+        return result.data
+      },
+      messages: async (input) => {
+        const result = await client.session.messages({ path: input.path })
+        if (result.error) throw new Error(sdkErrorMessage(result.error))
+        return result.data
+      },
+    },
+  }
+}
+
+/**
+ * Adapt the opencode SDK client to the structural TodoEnforcerClient the
+ * todo enforcer expects: unwraps the SDK `{data, error, request, response}`
+ * result and surfaces errors as throws (the enforcer swallows + logs them,
+ * so the event hook can never break the session).
+ */
+function adaptTodoEnforcerClient(client: PluginInput['client']): TodoEnforcerClient {
+  return {
+    session: {
+      todo: async (input) => {
+        const result = await client.session.todo({ path: input.path })
+        if (result.error) throw new Error(sdkErrorMessage(result.error))
+        return result.data
+      },
+      messages: async (input) => {
+        const result = await client.session.messages({ path: input.path })
+        if (result.error) throw new Error(sdkErrorMessage(result.error))
+        return result.data
+      },
+      children: async (input) => {
+        const result = await client.session.children({ path: input.path })
+        if (result.error) throw new Error(sdkErrorMessage(result.error))
+        return result.data
+      },
+      promptAsync: async (input) => {
+        const result = await client.session.promptAsync({ path: input.path, body: input.body })
+        if (result.error) throw new Error(sdkErrorMessage(result.error))
+        return result.data
+      },
+    },
+  }
+}
+
 /**
  * Pantheon plugin for OpenCode. Pasted images are intercepted via the
  * `chat.message` hook (proven to fire in opencode 1.18.11). When a provider
@@ -53,6 +199,55 @@ board.onTerminal((taskID: string) => {
  */
 const plugin: Plugin = async (input: PluginInput) => {
   const vision = createVisionHandler(input)
+  // Phase 2/3: background delegation toolset + the bound finalize lifecycle
+  // hook. Completion is observed through the event hook below
+  // (session.idle / session.error on a child) → finalizeDelegation.
+  const delegation = createDelegationTools({
+    board,
+    client: adaptDelegationClient(input.client),
+    options: { rootSessions, readOnlyAgents: new Set(['apollo', 'gaia']) },
+  })
+
+  // Wave 1 (PR #46): TODO continuation enforcer for root/non-board sessions.
+  // Mirrors routing.yml `todo_enforcer` (plugin scope has no routing.yml
+  // access — COMPACTION_MAX_ITEMS pattern). The event hook routes non-board
+  // session.idle events here; board-child idles go to finalizeDelegation.
+  // Runtime kill-switch: PANTHEON_TODO_ENFORCER=off (routing.yml is a doc
+  // mirror only — the env var is the real switch, PANTHEON_TOASTS pattern).
+  const todoEnforcer = new TodoEnforcer({
+    client: adaptTodoEnforcerClient(input.client),
+    board,
+    options: { ...TODO_ENFORCER_DEFAULTS, enabled: todoEnforcerEnabledFromEnv() },
+  })
+
+  // Wave 3 (PR #46): full-auto goal loop — opt-in (`full_auto.enabled:
+  // false` default, mirrored by GOAL_LOOP_DEFAULTS). File-based GoalStore
+  // (`.pantheon/goals/<sessionID>.json` — the plugin layer cannot reach MCP
+  // KV). Idle routing: an active goal owns the idle (goal loop); otherwise
+  // the todo enforcer gets it (see idle-continuation.ts).
+  const goalStore = new GoalStore({ dir: '.pantheon/goals' })
+  const goalLoop = new GoalLoop({
+    store: goalStore,
+    client: adaptTodoEnforcerClient(input.client),
+    board,
+    options: GOAL_LOOP_DEFAULTS,
+  })
+  const goalTools = goalLoop.tools()
+  const idleDispatcher = createIdleDispatcher({ goalLoop, todoEnforcer })
+
+  // Wave 2 (PR #46): hashline — tag-anchored edits. The read enhancer
+  // (tool.execute.after) augments `read` output with per-line sha256 tags
+  // (`12#XJ|content`); hashline_edit anchors edits to those refs. Additive —
+  // the plugin has no tool.execute.after yet, and pantheon-hooks.ts (a
+  // separate plugin instance) keeps its own. Mirrors routing.yml `hashline`.
+  const hashlineEdit = createHashlineEditTool()
+  const readEnhancer = createReadEnhancer()
+
+  // Wave 4 (PR #46): /cost — delegation cost + token visibility. Reads
+  // opencode.db read-only (node:sqlite, falls back to scripts/cost.mjs).
+  // Fully wired (unlike dispatch-guard, which is manual-orchestration-only
+  // because opencode 1.18.x cannot intercept task completion via hooks).
+  const costCommand = createCostCommand()
 
   return {
     config: async (config: PluginConfig) => {
@@ -92,9 +287,80 @@ const plugin: Plugin = async (input: PluginInput) => {
         console.warn('[plugin] preset application failed (see logs for details)')
       }
     },
-    'chat.message': vision.chatMessage,
+    // Phase 2: background delegation tools (structural — matches the `tool`
+    // hook field shape; read_only sessions feed the Phase 4 registry).
+    tool: {
+      pantheon_delegate: delegation.pantheon_delegate,
+      pantheon_delegation_read: delegation.pantheon_delegation_read,
+      pantheon_delegation_list: delegation.pantheon_delegation_list,
+      hashline_edit: hashlineEdit,
+      // Wave 3 (PR #46): full-auto goal tools (single active goal/session).
+      pantheon_goal_create: goalTools.pantheon_goal_create,
+      pantheon_goal_update: goalTools.pantheon_goal_update,
+      pantheon_goal_get: goalTools.pantheon_goal_get,
+      // Wave 4 (PR #46): /cost — delegation cost report from opencode.db.
+      pantheon_cost: costCommand.pantheon_cost,
+    },
+    'chat.message': async (hookInput, output) => {
+      await vision.chatMessage(hookInput, output)
+      // Phase 3: deliver queued completion notifications into the parent's
+      // context (prepended onto the first text part). No-op when the queue is
+      // empty or the parent session has no pending notifications.
+      notifier.flushQueue(hookInput.sessionID, output)
+      // Wave 1: a user message is activity — the todo enforcer's
+      // user-activity gate skips injection for userActivityQuietMs afterwards.
+      todoEnforcer.noteUserActivity(hookInput.sessionID)
+    },
     'experimental.chat.messages.transform': vision.messagesTransform,
-    event: vision.event,
+    event: async ({ event: ev }) => {
+      // Phase 3: sessions created without a parent are roots for the depth guard.
+      if (ev.type === 'session.created') {
+        const info = ev.properties.info
+        if (info && info.parentID === undefined) rootSessions.add(info.id)
+      }
+      // Phase 3: observe completion on child sessions → finalizeDelegation.
+      // The board transition fires onTerminal → notifier.notifyParent (the
+      // single notification point). Unknown sessions are a no-op.
+      try {
+        const delegated = await handleDelegationEvent(ev, {
+          board,
+          finalize: (childSessionID, opts) => delegation.finalizeDelegation(childSessionID, opts),
+        })
+        // Wave 1/3: non-board idle → idle dispatcher. Board children are
+        // handled by handleDelegationEvent above; everything else (roots,
+        // non-board sessions) is routed by priority: an active goal owns the
+        // idle (goal loop), otherwise the todo enforcer re-injects. Neither
+        // onIdle ever throws (internal failures are logged + swallowed), so
+        // the session is safe.
+        if (!delegated && ev.type === 'session.idle') {
+          await idleDispatcher.onIdle(ev.properties.sessionID)
+        }
+      } catch (err) {
+        // The event hook must never break the session.
+        console.error('[Pantheon Plugin] Delegation event handling failed:', err)
+      }
+      await vision.event({ event: ev })
+    },
+    // Phase 4: deny mutating tools in read-only delegated sessions. Additive
+    // key — does not touch Phase 3's tools/event/onTerminal/chat.message.
+    'tool.execute.before': enforcementGuard,
+    // Wave 2 (PR #46): augment `read` output with hashline tags. Additive —
+    // pantheon-hooks.ts (a separate plugin instance) owns its own
+    // tool.execute.after, so there is no key collision. Non-read tools pass
+    // through untouched.
+    'tool.execute.after': readEnhancer,
+    // Phase 4: keep in-flight background delegations visible across
+    // compaction (running + unread terminal jobs). Guarded: only pushes when
+    // there is something to preserve.
+    'experimental.session.compacting': async (_input, output) => {
+      const blocks = buildCompactionContext(board, {
+        sessionID: _input.sessionID,
+        maxItems: COMPACTION_MAX_ITEMS,
+      })
+      if (blocks.length > 0) {
+        output.context.push(...blocks)
+      }
+    },
   }
 }