pantheon-opencode 1.5.0-beta.1 → 1.5.0-beta.11

package/src/pantheon/token-opt.ts

@@ -35,6 +35,13 @@
 
 import type { ToonValue } from './toon-codec.ts'
 
+export {
+  type HostToolCeilingSource,
+  probeToolCeiling,
+  type ToolCeilingResult,
+  type ToolCeilingSnapshot,
+} from './tool-ceiling.ts'
+
 // ─── Deterministic token estimator (WS0 extension, tokens-only) ──────────
 
 /** Nominal chars-per-token ratio (fixed so measurements are comparable). */
@@ -173,7 +180,7 @@ export function applyGate(
 }
 
 /** Kill-switch: `PANTHEON_TOKEN_OPT=off` disables the whole WS3 layer. */
-export function isTokenOptEnabled(env: Record<string, string | undefined> = {}): boolean {
+export function isTokenOptEnabled(env: Readonly<Record<string, string | undefined>> = {}): boolean {
   return env.PANTHEON_TOKEN_OPT !== 'off'
 }
 
@@ -193,12 +200,24 @@ export interface C9Chunk {
   text: string
 }
 
+/** Immutable input batch for the safe C9 context-preparation contract. */
+export interface C9CandidateBatch {
+  query: string
+  candidates: readonly C9Chunk[]
+}
+
 /** Per-category override of top-k / cutoff. */
 export interface C9CategoryConfig {
   topK?: number
   cutoff?: number
 }
 
+/** Optional query used only to activate the explicit low-score fallback. */
+export interface C9FilterOptions {
+  perCategory?: Readonly<Record<string, C9CategoryConfig>>
+  query?: string
+}
+
 /** Result of C9 filtering with debited injection cost. */
 export interface C9FilterResult {
   selected: C9Chunk[]
@@ -208,10 +227,8 @@ export interface C9FilterResult {
   /**
    * Quality-floor signal (never silent on empty):
    * - `ok` — at least one chunk selected;
-   * - `empty-input` — no chunks retrieved at all (fallback: proceed without
-   *   injected context, caller should log `notice`);
-   * - `all-dropped` — chunks existed but none survived cutoff/top-k
-   *   (fallback: relax cutoff/top-k or proceed without context).
+   * - `empty-input` — no chunks retrieved at all;
+   * - `all-dropped` — chunks existed but none survived cutoff/top-k.
    */
   signal: 'ok' | 'empty-input' | 'all-dropped'
   /** Human-readable alert for the non-`ok` signals (null when `ok`). */
@@ -228,12 +245,21 @@ export interface C9FilterResult {
 
 /**
  * Filter scored chunks per category: drop below cutoff, keep top-k by
- * score desc. The injected context cost is debited (`injectedTokens`).
+ * score desc. Scores must come from retrieval; text is never used as a proxy.
+ * The injected context cost is debited (`injectedTokens`).
  */
 export function c9Filter(
-  chunks: C9Chunk[],
-  perCategory?: Record<string, C9CategoryConfig>,
+  chunks: readonly C9Chunk[],
+  perCategoryOrOptions?: Readonly<Record<string, C9CategoryConfig>> | C9FilterOptions | string,
+  _query?: string,
 ): C9FilterResult {
+  const isOptions = isC9FilterOptions(perCategoryOrOptions)
+  const perCategory =
+    typeof perCategoryOrOptions === 'string'
+      ? undefined
+      : isOptions
+        ? perCategoryOrOptions.perCategory
+        : perCategoryOrOptions
   const byCategory = new Map<string, C9Chunk[]>()
   for (const chunk of chunks) {
     const group = byCategory.get(chunk.category)
@@ -256,15 +282,16 @@ export function c9Filter(
     dropped.push(...group.filter((c) => c.score < cutoff))
     dropped.push(...eligible.slice(topK))
   }
-  const context = buildC9Context(selected)
   const signal: C9FilterResult['signal'] =
     chunks.length === 0 ? 'empty-input' : selected.length === 0 ? 'all-dropped' : 'ok'
   const notice =
     signal === 'empty-input'
-      ? 'C9: empty input — no chunks retrieved; fallback: proceed without injected context'
+      ? 'C9: empty input — no chunks retrieved; proceed without injected context'
       : signal === 'all-dropped'
-        ? 'C9: all chunks dropped by cutoff/top-k; fallback: relax cutoff/top-k or proceed without context'
+        ? 'C9: all chunks dropped by cutoff/top-k; no context was injected'
         : null
+
+  const context = buildC9Context(selected)
   return {
     selected,
     dropped,
@@ -276,8 +303,115 @@ export function c9Filter(
   }
 }
 
+/** Configuration for the pure C9 context-preparation boundary. */
+export interface C9ContextOptions {
+  env?: Readonly<Record<string, string | undefined>>
+  perCategory?: Readonly<Record<string, C9CategoryConfig>>
+}
+
+/** Metrics emitted by C9; deliberately contains no candidate or context text. */
+export interface C9Telemetry {
+  signal: C9FilterResult['signal'] | 'disabled' | 'empty-query'
+  counts: {
+    candidates: number
+    selected: number
+    dropped: number
+  }
+  recall: number
+  injectedChars: number
+  injectedTokens: number
+}
+
+/** C9 result with the kill-switch state available as a type discriminator. */
+export type C9ContextResult =
+  | {
+      enabled: true
+      context: string
+      telemetry: C9Telemetry
+    }
+  | {
+      enabled: false
+      context: ''
+      telemetry: C9Telemetry
+    }
+
+function telemetry(
+  signal: C9Telemetry['signal'],
+  candidates: number,
+  selected: number,
+  dropped: number,
+  recall: number,
+  context = '',
+): C9Telemetry {
+  return {
+    signal,
+    counts: { candidates, selected, dropped },
+    recall,
+    injectedChars: context.length,
+    injectedTokens: estimateTokens(context),
+  }
+}
+
+/**
+ * Prepare auditable context without performing retrieval or side effects.
+ *
+ * The caller supplies the query and candidates already retrieved. The
+ * kill-switch is read only from the supplied environment object, so this
+ * boundary remains deterministic and testable. C9 always receives the batch
+ * query explicitly; no option can replace it with an implicit query.
+ */
+export function prepareC9Context(
+  batch: C9CandidateBatch,
+  options: C9ContextOptions = {},
+): C9ContextResult {
+  const candidateCount = batch.candidates.length
+  if (!isTokenOptEnabled(options.env)) {
+    return {
+      enabled: false,
+      context: '',
+      telemetry: telemetry('disabled', candidateCount, 0, 0, 0),
+    }
+  }
+
+  const filtered = c9Filter(batch.candidates, options.perCategory, batch.query)
+  if (batch.query.trim().length === 0) {
+    return {
+      enabled: true,
+      context: '',
+      telemetry: telemetry(
+        'empty-query',
+        candidateCount,
+        0,
+        candidateCount,
+        candidateCount === 0 ? filtered.recall : 0,
+      ),
+    }
+  }
+
+  const context = buildC9Context(filtered.selected)
+  const signal = filtered.signal
+  const selectedCount = context.length === 0 ? 0 : filtered.selected.length
+  const droppedCount = context.length === 0 ? candidateCount : filtered.dropped.length
+  const recall = context.length === 0 && filtered.signal === 'ok' ? 0 : filtered.recall
+  return {
+    enabled: true,
+    context,
+    telemetry: telemetry(signal, candidateCount, selectedCount, droppedCount, recall, context),
+  }
+}
+
+function isC9FilterOptions(
+  value: Readonly<Record<string, C9CategoryConfig>> | C9FilterOptions | string | undefined,
+): value is C9FilterOptions {
+  return (
+    value !== undefined &&
+    typeof value !== 'string' &&
+    ('perCategory' in value || ('query' in value && typeof value.query === 'string'))
+  )
+}
+
 /** Build the injected context: only auditable chunks (id + score + text). */
-export function buildC9Context(selected: C9Chunk[]): string {
+export function buildC9Context(selected: readonly C9Chunk[]): string {
   return selected.map((c) => `[${c.category}:${c.id}|${c.score}] ${c.text}`).join('\n')
 }
 

package/src/pantheon/tool-ceiling.ts

@@ -0,0 +1,159 @@
+/** Host-real context ceiling probe for C9/tool filtering. */
+
+import type { PluginInput } from '@opencode-ai/plugin'
+import { createPantheonLogger, type PantheonLogger } from './logger.ts'
+import type { NativeTaskStatus } from './native-task-status.ts'
+
+export interface ToolCeilingSnapshot {
+  usage: { inputTokens: number; outputTokens: number }
+  limit: { contextTokens: number }
+  supportsToolFiltering: boolean
+}
+
+export type ToolCeilingResult =
+  | {
+      status: 'OK'
+      ceiling: number
+      usage: ToolCeilingSnapshot['usage']
+      limit: ToolCeilingSnapshot['limit']
+    }
+  | { status: Exclude<NativeTaskStatus, 'OK'>; detail: string }
+
+export type HostToolCeilingSource = () => unknown | Promise<unknown>
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isFiniteNonNegative(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0
+}
+
+function isSnapshot(value: unknown): value is ToolCeilingSnapshot {
+  if (!isRecord(value) || !isRecord(value.usage) || !isRecord(value.limit)) return false
+  return (
+    isFiniteNonNegative(value.usage.inputTokens) &&
+    isFiniteNonNegative(value.usage.outputTokens) &&
+    isFiniteNonNegative(value.limit.contextTokens) &&
+    typeof value.supportsToolFiltering === 'boolean'
+  )
+}
+
+/** Probe exact host usage/limit without estimation, fallback, or retry. */
+export async function probeToolCeiling(source?: HostToolCeilingSource): Promise<ToolCeilingResult> {
+  if (source === undefined)
+    return { status: 'UNSUPPORTED', detail: 'host SDK exposes no context probe' }
+
+  let raw: unknown
+  try {
+    raw = await source()
+  } catch (error: unknown) {
+    return { status: 'UNAVAILABLE', detail: error instanceof Error ? error.message : String(error) }
+  }
+  if (!isSnapshot(raw))
+    return { status: 'CORRUPT_DATA', detail: 'host context probe returned malformed data' }
+  if (raw.supportsToolFiltering === false) {
+    return { status: 'UNSUPPORTED', detail: 'host SDK does not filter tools' }
+  }
+  const used = raw.usage.inputTokens + raw.usage.outputTokens
+  if (used > raw.limit.contextTokens) {
+    return { status: 'CORRUPT_DATA', detail: 'host usage exceeds context limit' }
+  }
+  return {
+    status: 'OK',
+    ceiling: raw.limit.contextTokens - used,
+    usage: raw.usage,
+    limit: raw.limit,
+  }
+}
+
+/**
+ * Read a ceiling from the actual OpenCode SDK event and provider catalogue.
+ *
+ * `message.updated` is the SDK's runtime usage source (`info.tokens`). The
+ * provider catalogue supplies the selected model's context limit and its
+ * `capabilities.toolcall` flag. This adapter intentionally does not accept a
+ * caller-provided snapshot/callback, so tests cannot accidentally turn a
+ * fixture into a claimed host probe.
+ */
+export async function probeToolCeilingFromHost(
+  client: PluginInput['client'],
+  event: unknown,
+): Promise<ToolCeilingResult> {
+  if (!isRecord(event) || event.type !== 'message.updated' || !isRecord(event.properties)) {
+    return { status: 'UNSUPPORTED', detail: 'host SDK event has no message usage' }
+  }
+  const info = event.properties.info
+  if (
+    !isRecord(info) ||
+    typeof info.providerID !== 'string' ||
+    typeof info.modelID !== 'string' ||
+    !isRecord(info.tokens)
+  ) {
+    return { status: 'UNSUPPORTED', detail: 'host SDK message has no token usage' }
+  }
+  const providerID = info.providerID as string
+  const modelID = info.modelID as string
+  const tokens = info.tokens as Record<string, unknown>
+
+  let providersResult: unknown
+  try {
+    providersResult = await client.config.providers()
+  } catch (error: unknown) {
+    return { status: 'UNAVAILABLE', detail: error instanceof Error ? error.message : String(error) }
+  }
+  if (!isRecord(providersResult) || providersResult.error !== undefined) {
+    return { status: 'UNAVAILABLE', detail: 'host SDK provider catalogue unavailable' }
+  }
+  const data = providersResult.data
+  if (!isRecord(data) || !Array.isArray(data.providers)) {
+    return { status: 'CORRUPT_DATA', detail: 'host SDK provider catalogue malformed' }
+  }
+
+  const provider = data.providers.find(
+    (candidate) =>
+      isRecord(candidate) &&
+      candidate.id === providerID &&
+      isRecord(candidate.models) &&
+      isRecord(candidate.models[modelID]),
+  )
+  if (!isRecord(provider) || !isRecord(provider.models)) {
+    return { status: 'UNSUPPORTED', detail: 'host SDK model metadata unavailable' }
+  }
+  const model = provider.models[modelID]
+  if (!isRecord(model) || !isRecord(model.limit) || !isRecord(model.capabilities)) {
+    return { status: 'UNSUPPORTED', detail: 'host SDK model ceiling capability unavailable' }
+  }
+
+  return probeToolCeiling(() => ({
+    usage: { inputTokens: tokens.input, outputTokens: tokens.output },
+    limit: { contextTokens: (model.limit as Record<string, unknown>).context },
+    supportsToolFiltering: (model.capabilities as Record<string, unknown>).toolcall,
+  }))
+}
+
+const log = createPantheonLogger({ module: 'pantheon-tool-ceiling' })
+
+/**
+ * Handle the host usage event and retain the result for the compaction hook.
+ * Malformed SDK events are diagnostic-only: they must never break the event
+ * pipeline or create an entry under an invalid session identifier.
+ */
+export async function handleToolCeilingEvent(
+  client: PluginInput['client'],
+  event: unknown,
+  ceilings: Map<string, ToolCeilingResult>,
+  logger: Pick<PantheonLogger, 'warn'> = log,
+): Promise<ToolCeilingResult> {
+  const sessionID = (
+    event as { properties?: { info?: { sessionID?: unknown } } } | null | undefined
+  )?.properties?.info?.sessionID
+  if (typeof sessionID !== 'string' || sessionID.trim() === '') {
+    logger.warn('[Pantheon Plugin] message.updated event has no valid sessionID')
+    return { status: 'UNSUPPORTED', detail: 'host SDK event has no valid sessionID' }
+  }
+
+  const result = await probeToolCeilingFromHost(client, event)
+  ceilings.set(sessionID, result)
+  return result
+}

package/src/pantheon/v2-events.ts

@@ -94,13 +94,30 @@ export function createV2EventDispatcher(deps: V2EventDeps): V2EventDispatcher {
   return {
     handleEvent: async (event: V2SessionEvent): Promise<boolean> => {
       try {
-        // session.created → seed hierarchy
+        // session.created → seed hierarchy + board put-if-absent for native children
         if (event.type === 'session.created') {
           const info = event.properties?.info as SessionInfo | undefined
           if (info) {
             deps.registerSession?.(info)
             if (info.parentID === undefined) {
               deps.addRootSession?.(info.id)
+            } else {
+              // Native task(background=true) child: register on the board
+              // atomically (skip if V1 idle hook or re-dispatch already claimed it).
+              try {
+                await deps.board.registerLaunchIfAbsent({
+                  taskID: info.id,
+                  parentSessionID: info.parentID,
+                  agent: 'native',
+                  description: `native child ${info.id}`,
+                })
+              } catch (err) {
+                // The per-agent concurrency limit can refuse the launch. Do not
+                // abort the rest of the handler: this child is simply not
+                // mirrored on the board, while finalize/idle dispatch for every
+                // other event must still run.
+                log.warn(`[Pantheon V2] native child ${info.id} not mirrored on board:`, err)
+              }
             }
           }
         }

package/src/plugin-v2.ts

@@ -612,18 +612,6 @@ export interface V2ToolResult {
   output: string
 }
 
-/**
- * Wrap raw tool text into the object shape the V2 beta host requires.
- * Never throws (fail-open): non-string input degrades to String(input).
- */
-export function toV2ToolResult(text: unknown): V2ToolResult {
-  try {
-    return { output: typeof text === 'string' ? text : String(text) }
-  } catch {
-    return { output: '[pantheon] tool output unavailable' }
-  }
-}
-
 /**
  * A V2 tool definition ready for registration.
  */
@@ -698,9 +686,9 @@ function createV2ToolDefinitionsFromContext(_context: PluginContext): V2ToolDef[
     // costCommand/goalTools) once V1 infrastructure is resolvable in the V2
     // standalone context. The before/after factories in v2-hooks.ts:216-282
     // are likewise unwired. Until then, placeholders resolve to the object
-    // shape via toV2ToolResult so the beta host never sees a bare string.
+    // shape so the beta host never sees a bare string.
     execute: async (_input: Record<string, unknown>, _context: unknown): Promise<V2ToolResult> => {
-      return toV2ToolResult(`${name}: ${v2UnavailableMessage}`)
+      return { output: `${name}: ${v2UnavailableMessage}` }
     },
   }))
 }

package/src/plugin.ts

@@ -2,7 +2,6 @@ import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Plugin, PluginInput } from '@opencode-ai/plugin'
 import type { PluginConfig } from 'opencode'
-import { BackgroundJobBoard } from './pantheon/background-job-board.ts'
 import { createCommandNormalizer } from './pantheon/command-normalizer.ts'
 import {
   type ContextSandboxConfig,
@@ -12,11 +11,7 @@ import {
   DEFAULT_LIMITS as SANDBOX_DEFAULT_LIMITS,
 } from './pantheon/context-sandbox.ts'
 import { createCostCommand } from './pantheon/cost-command.ts'
-import {
-  buildPluginNativeDelegation,
-  resolveDelegateMode,
-  withDelegationKillSwitch,
-} from './pantheon/delegate-task-adapter.ts'
+import { buildPluginNativeDelegation, resolveDelegateMode } from './pantheon/delegate-manager.ts'
 import {
   collectRootSessionIDs,
   createDelegationTools,
@@ -34,7 +29,6 @@ import {
 } from './pantheon/delegation-enforce.ts'
 import { handleDelegationEvent } from './pantheon/delegation-notify.ts'
 import { showDelegationTerminalToast, type ToastClient } from './pantheon/delegation-toast.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'
@@ -49,7 +43,9 @@ import {
   loadRoutingPermissionTask,
 } from './pantheon/presets.mjs'
 import { safeSessionPath } from './pantheon/session-guard.ts'
+import { getSharedBoard } from './pantheon/shared-board.ts'
 import { StepCapTracker } from './pantheon/step-cap.ts'
+import { createTaskResultGuard } from './pantheon/task-result-guard.ts'
 import {
   TODO_ENFORCER_DEFAULTS,
   TodoEnforcer,
@@ -57,6 +53,7 @@ import {
   todoEnforcerEnabledFromEnv,
 } from './pantheon/todo-enforcer.ts'
 import { TodoPreserver } from './pantheon/todo-preserve.ts'
+import { handleToolCeilingEvent, type ToolCeilingResult } from './pantheon/tool-ceiling.ts'
 import { checkTuiVersionStaleness } from './pantheon/tui-version-check.ts'
 import { activePresetCandidates, createVisionHandler } from './pantheon/vision.ts'
 
@@ -79,12 +76,11 @@ const stepCapTracker = new StepCapTracker(loadRoutingMaxSteps({ logger: log }))
 // (fail-open → undefined = existing runtime matrix only).
 const routingPermissionTask = loadRoutingPermissionTask({ logger: log })
 
-const board = new BackgroundJobBoard({
-  maxConcurrentPerAgent: 3,
-  signalDir: '.pantheon/deepwork/board-signals',
-})
-const persistence = new FilePersistenceAdapter('.pantheon/board/state.json')
-board.setPersistence(persistence)
+// beta.5: the board is a PROCESS-wide singleton (getSharedBoard) shared with
+// src/plugins/pantheon-hooks.ts, whose native-task mirror registers children
+// here; the finalize path below (session.idle + idle scan) must observe the
+// SAME instance. globalThis anchoring dedupes the npm+repo double load.
+const board = getSharedBoard()
 let terminalToastClient: ToastClient = {}
 board
   .recoverRunningJobs()
@@ -169,6 +165,7 @@ const COMPACTION_MAX_ITEMS = 10
 const rootSessions = new Set<string>()
 const sessionHierarchy = new SessionHierarchyRegistry()
 const sessionAgents = new Map<string, string>()
+const sessionToolCeilings = new Map<string, ToolCeilingResult>()
 
 /**
  * Seed resumed root sessions without making OpenCode startup depend on the
@@ -375,8 +372,7 @@ const plugin: Plugin = async (input: PluginInput) => {
   // WS1 (PR #94): delegation backend gate. Default = legacy (the V1
   // fire-and-forget toolset, intact); PANTHEON_DELEGATE_MODE=native selects
   // the thin manager over native task() semantics. Kill-switch
-  // PANTHEON_DELEGATION=off covers BOTH modes (native guards internally;
-  // legacy via withDelegationKillSwitch). finalizeDelegation always stays on
+  // PANTHEON_DELEGATION=off covers the native manager; finalizeDelegation stays on
   // the legacy observer: it works on the shared board in both modes and must
   // never be kill-switched, so children never orphan. The idle hook below is
   // untouched.
@@ -428,7 +424,7 @@ const plugin: Plugin = async (input: PluginInput) => {
           ...(wallClockTimeoutMs !== undefined ? { wallClockTimeoutMs } : {}),
           finalizeDelegation: legacyDelegation.finalizeDelegation,
         })
-      : withDelegationKillSwitch(legacyDelegation)
+      : legacyDelegation
 
   // Proactive idle-child scan (Fix 2): finalize children that are idle on the
   // board but have no MD report on disk — eliminates the phantom "running"
@@ -509,13 +505,18 @@ const plugin: Plugin = async (input: PluginInput) => {
     },
   }
   const sandboxHandler = createContextSandbox(sandboxConfig)
+  // Task Result Guard (2026-09-10): detect empty task() results from native
+  // opencode subagent calls and convert to explicit errors. Runs FIRST in the
+  // chain so the error message is visible even if later handlers skip.
+  const taskResultGuard = createTaskResultGuard()
   const combinedAfter: typeof readEnhancer = async (input, output) => {
+    await taskResultGuard(input, output)
     await sandboxHandler(input, output)
     await readEnhancer(input, output)
   }
 
   // Wave 4 (PR #46): /cost — delegation cost + token visibility. Reads
-  // opencode.db read-only (node:sqlite, falls back to scripts/cost.mjs).
+  // opencode.db read-only via the single node:sqlite backend.
   // Fully wired (unlike dispatch-guard, which is manual-orchestration-only
   // because opencode 1.18.x cannot intercept task completion via hooks).
   const costCommand = createCostCommand()
@@ -620,6 +621,9 @@ const plugin: Plugin = async (input: PluginInput) => {
       if (ev.type === 'session.compacted') {
         await todoPreserver.onCompacted(ev.properties.sessionID)
       }
+      if (ev.type === 'message.updated') {
+        await handleToolCeilingEvent(input.client, ev, sessionToolCeilings)
+      }
       // Phase 3: observe completion on child sessions → finalizeDelegation.
       // The board transition fires onTerminal → the file-only audit log (no
       // chat delivery — see the onTerminal listener above). Unknown sessions
@@ -685,6 +689,13 @@ const plugin: Plugin = async (input: PluginInput) => {
             list: (sessionID: string) => todoEnforcer.listPendingTodos(sessionID),
           },
         })
+        const ceiling = sessionToolCeilings.get(_input.sessionID)
+        if (ceiling?.status === 'OK') {
+          output.context.push(
+            `<tool_ceiling remaining_context_tokens="${ceiling.ceiling}">` +
+              'Use the remaining host-reported context budget when selecting tools.</tool_ceiling>',
+          )
+        }
         if (blocks.length > 0) {
           output.context.push(...blocks)
         }

package/src/plugins/pantheon-hooks.ts

@@ -177,6 +177,7 @@ import { appendFile, mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { Plugin, PluginInput } from '@opencode-ai/plugin'
 import { pantheonPluginOnce } from '../pantheon/plugin-once.ts'
+import { getSharedBoard } from '../pantheon/shared-board.ts'
 import { type HookPayload, type HookResult, runHook } from './hook-runner.ts'
 
 /** Tools that represent a subagent delegation (opencode `task` tool etc.). */
@@ -775,6 +776,51 @@ function delegationAgent(tool: string, args?: unknown): string {
   return tool
 }
 
+/**
+ * beta.5: mirror a native background task dispatch onto the SHARED board
+ * (getSharedBoard) so the existing finalize path in plugin.ts (session.idle
+ * event + 30s idle scan) writes the terminal report and the TUI delegation
+ * panel tracks the child end-to-end. Fire-and-forget and silent: a mirror
+ * failure must never surface into the tool call or the transcript.
+ * registerLaunchIfAbsent keeps it idempotent against any other dispatcher
+ * (v2-events, plugin double-load, repeated after-hook firings).
+ */
+function mirrorNativeBackgroundDispatch(
+  input: { tool: string; sessionID: string },
+  args: unknown,
+  result: ToolExecuteAfterResult | null,
+): void {
+  const taskID = extractTaskId(result)
+  if (taskID === '' || typeof input.sessionID !== 'string' || input.sessionID === '') return
+  const description = trim(delegationDescription(args) ?? `native ${input.tool} dispatch`, 200)
+  try {
+    getSharedBoard()
+      .registerLaunchIfAbsent({
+        taskID,
+        parentSessionID: input.sessionID,
+        agent: delegationAgent(input.tool, args),
+        description,
+      })
+      .catch(() => {
+        // Mirror is best-effort — never surface into the tool call.
+      })
+  } catch {
+    // Never let the mirror take down the tool call.
+  }
+}
+
+/** Task description from task-tool args (description ?? prompt); undefined when absent. */
+function delegationDescription(args: unknown): string | undefined {
+  try {
+    const a = (args ?? {}) as Record<string, unknown>
+    const raw = a.description ?? a.prompt
+    if (typeof raw === 'string' && raw.trim() !== '') return raw
+  } catch {
+    // Malformed args — fall through to the generic description.
+  }
+  return undefined
+}
+
 /** 🚀 delegation-started toast (variant 'info', 2500ms), deduped per agent. */
 async function delegationStartedToast(ctx: HookContext, agent: string): Promise<void> {
   await throttledToast(ctx, {
@@ -1311,6 +1357,11 @@ const plugin: Plugin = async ({ client, directory }) => {
             // NOT a completion: do not mark the group done and do not fire ✅
             // — that would corrupt olympians aggregation. Real completion of
             // background tasks is unobservable on 1.18.13 (see header).
+            // beta.5: mirror the native background child onto the SHARED
+            // board so the existing finalize path (session.idle + idle scan
+            // in plugin.ts) writes the terminal report and the TUI
+            // delegation panel tracks the child end-to-end. Fire-and-forget.
+            mirrorNativeBackgroundDispatch(input, args, result)
           } else {
             const handledByOlympians = handleOlympiansCompletion(ctx, agent)
             if (!handledByOlympians) void delegationDoneToast(ctx, agent)

package/src/plugins/tui/dist/server.d.ts

@@ -14,4 +14,4 @@
 declare function server(): {};
 //#endregion
 export { server as default };
-//# sourceMappingURL=server.d.ts.map
+//# sourceMappingURL=server.d.ts.map

package/src/plugins/tui/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","names":[],"sources":["../src/server.ts"],"mappings":";;;;;;;;;;;;;iBAYwB"}
+{"version":3,"file":"server.d.ts","names":[],"sources":["../src/server.ts"],"mappings":";;;;;;;;;;;;;iBAYwB"}

package/src/plugins/tui/dist/server.js

@@ -17,4 +17,4 @@ function server() {
 //#endregion
 export { server as default };
 
-//# sourceMappingURL=server.js.map
+//# sourceMappingURL=server.js.map

package/src/plugins/tui/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","names":[],"sources":["../src/server.ts"],"sourcesContent":["/**\n * No-op server stub for the opencode plugin loader.\n *\n * The opencode plugin host requires every plugin (TUI included) to expose a\n * `server()` entry via `exports[\"./server\"]` (or package.json `main`). When\n * that entry is missing the host fails to attach the plugin's server half and\n * the TUI runtime never wires the reactive channel — the initial JSX mounts\n * but effects/refresh/events stay dead (the \"mudo panel\" symptom).\n *\n * This stub satisfies the loader contract; pantheon-tui is TUI-only and has\n * no background server work of its own.\n */\nexport default function server() {\n  return {}\n}\n"],"mappings":";;;;;;;;;;;;;AAYA,SAAwB,SAAS;CAC/B,OAAO,CAAC;AACV"}
+{"version":3,"file":"server.js","names":[],"sources":["../src/server.ts"],"sourcesContent":["/**\n * No-op server stub for the opencode plugin loader.\n *\n * The opencode plugin host requires every plugin (TUI included) to expose a\n * `server()` entry via `exports[\"./server\"]` (or package.json `main`). When\n * that entry is missing the host fails to attach the plugin's server half and\n * the TUI runtime never wires the reactive channel — the initial JSX mounts\n * but effects/refresh/events stay dead (the \"mudo panel\" symptom).\n *\n * This stub satisfies the loader contract; pantheon-tui is TUI-only and has\n * no background server work of its own.\n */\nexport default function server() {\n  return {}\n}\n"],"mappings":";;;;;;;;;;;;;AAYA,SAAwB,SAAS;CAC/B,OAAO,CAAC;AACV"}