pantheon-opencode 1.5.0-beta.3 → 1.5.0-beta.5

package/src/pantheon/task-result-guard.ts

@@ -0,0 +1,107 @@
+/**
+ * Task Result Guard — detects empty task() results from native opencode
+ * subagent calls and converts them to explicit errors.
+ *
+ * Bug context (reproduced 2026-09-10): task() native creates a child session
+ * that inherits the parent transcript. When the payload exceeds the provider's
+ * admission limit (e.g. free-tier max_outstanding_uncached_prefill_tokens=1000
+ * vs 57k incoming tokens), the stream errors with BackendAdmissionRejected.
+ * The error is NOT propagated — the child loop exits normally, the child
+ * session goes idle with zero assistant/tool output, and opencode marks the
+ * task as `completed` with empty content. The parent LLM receives an empty
+ * result and proceeds as if the task succeeded.
+ *
+ * The guard intercepts this in the `tool.execute.after` hook: when the tool
+ * is `task` and the output is empty/whitespace-only, it replaces the output
+ * with an explicit error message so the parent sees a failure, not silence.
+ *
+ * Pure TypeScript — zero runtime dependencies. Meant to be wired into the
+ * `combinedAfter` hook chain in plugin.ts alongside the sandbox and read
+ * enhancer handlers.
+ *
+ * @module task-result-guard
+ */
+
+import { createPantheonLogger } from './logger.ts'
+
+const log = createPantheonLogger({ module: 'pantheon-task-result-guard' })
+
+// ─── Types ─────────────────────────────────────────────────────────────
+
+/** Input shape of the opencode `tool.execute.after` hook. */
+export interface TaskGuardInput {
+  tool: string
+  sessionID: string
+  callID: string
+  args: unknown
+}
+
+/** Output shape of the opencode `tool.execute.after` hook (mutable). */
+export interface TaskGuardOutput {
+  title?: string
+  output: string
+  metadata?: Record<string, unknown>
+}
+
+/** The `tool.execute.after` handler shape. */
+export type TaskResultGuardHandler = (
+  input: TaskGuardInput,
+  output: TaskGuardOutput,
+) => Promise<void>
+
+export interface TaskResultGuardOptions {
+  /** Injectable logger (defaults to the Pantheon file log). */
+  logger?: { warn: (message: string) => void }
+}
+
+// ─── Constants ─────────────────────────────────────────────────────────
+
+/**
+ * The error message injected when a task() result is empty.
+ * Matches the existing delegation-finalize.ts contract:
+ * "Child session produced no assistant or tool output".
+ */
+export const EMPTY_TASK_ERROR =
+  'ERROR: task() returned empty output — child session produced no assistant or tool output. ' +
+  'This typically means the provider rejected the request (admission control / rate limit) ' +
+  'or the child session crashed before producing any response. ' +
+  'Consider using pantheon_delegate (clean context) instead of task() for large payloads.'
+
+// ─── Implementation ────────────────────────────────────────────────────
+
+/**
+ * Whether a result carries any text content (whitespace-only counts as empty).
+ */
+function isEmptyOutput(output: unknown): boolean {
+  if (output == null) return true
+  if (typeof output !== 'string') return true
+  return output.trim() === ''
+}
+
+/**
+ * Create a task result guard handler for the `tool.execute.after` hook.
+ *
+ * When the tool is `task` and the output is empty/whitespace-only, replaces
+ * the output with an explicit error message. All other tools pass through
+ * untouched.
+ *
+ * @returns A `ToolExecuteAfterHandler`-compatible async function.
+ */
+export function createTaskResultGuard(options?: TaskResultGuardOptions): TaskResultGuardHandler {
+  const warn = options?.logger?.warn ?? ((message: string) => log.warn(message))
+
+  return async (input: TaskGuardInput, output: TaskGuardOutput): Promise<void> => {
+    // Only intercept the `task` tool — all others pass through untouched.
+    if (input.tool !== 'task') return
+
+    // Only flag truly empty results — non-empty content is the happy path.
+    if (!isEmptyOutput(output.output)) return
+
+    warn(
+      `[task-result-guard] Empty task() result detected on session ${input.sessionID} ` +
+        `(callID=${input.callID}). Replacing with explicit error.`,
+    )
+
+    output.output = EMPTY_TASK_ERROR
+  }
+}

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). */
@@ -220,17 +227,10 @@ 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 and no
-   *   lexical query fallback was available;
-   * - `fallback-relative` — the absolute cutoff rejected every chunk, but a
-   *   query-matching lexical/relative ranking selected auditable low-score
-   *   chunks;
-   * - `nonsense` — a supplied query had no lexical overlap, so nothing is
-   *   injected.
+   * - `empty-input` — no chunks retrieved at all;
+   * - `all-dropped` — chunks existed but none survived cutoff/top-k.
    */
-  signal: 'ok' | 'empty-input' | 'all-dropped' | 'fallback-relative' | 'nonsense'
+  signal: 'ok' | 'empty-input' | 'all-dropped'
   /** Human-readable alert for the non-`ok` signals (null when `ok`). */
   notice: string | null
   /**
@@ -245,13 +245,13 @@ export interface C9FilterResult {
 
 /**
  * Filter scored chunks per category: drop below cutoff, keep top-k by
- * score desc. An optional query enables only the explicit low-score fallback.
+ * 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: readonly C9Chunk[],
   perCategoryOrOptions?: Readonly<Record<string, C9CategoryConfig>> | C9FilterOptions | string,
-  query?: string,
+  _query?: string,
 ): C9FilterResult {
   const isOptions = isC9FilterOptions(perCategoryOrOptions)
   const perCategory =
@@ -260,12 +260,6 @@ export function c9Filter(
       : isOptions
         ? perCategoryOrOptions.perCategory
         : perCategoryOrOptions
-  const filterQuery =
-    typeof perCategoryOrOptions === 'string'
-      ? (query ?? perCategoryOrOptions)
-      : isOptions
-        ? (query ?? perCategoryOrOptions.query)
-        : query
   const byCategory = new Map<string, C9Chunk[]>()
   for (const chunk of chunks) {
     const group = byCategory.get(chunk.category)
@@ -288,41 +282,15 @@ export function c9Filter(
     dropped.push(...group.filter((c) => c.score < cutoff))
     dropped.push(...eligible.slice(topK))
   }
-  let signal: C9FilterResult['signal'] =
+  const signal: C9FilterResult['signal'] =
     chunks.length === 0 ? 'empty-input' : selected.length === 0 ? 'all-dropped' : 'ok'
-  let notice =
+  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
 
-  // Keep the absolute cutoff intact. This fallback is deliberately entered
-  // only after it rejects every chunk, and only lexical overlap can authorize
-  // injecting one of those low-score chunks.
-  if (chunks.length > 0 && selected.length === 0 && filterQuery !== undefined) {
-    const queryTerms = lexicalTerms(filterQuery)
-    const fallbackSelected =
-      queryTerms.length > 0 ? relativeLexicalSelection(byCategory, perCategory, queryTerms) : []
-    if (fallbackSelected.length > 0) {
-      selected.push(...fallbackSelected)
-      signal = 'fallback-relative'
-      notice =
-        `C9: absolute cutoff ${C9_DEFAULT_CUTOFF} yielded no eligible chunks; ` +
-        `lexical/relative fallback selected ${fallbackSelected.length} auditable ` +
-        `low-score chunk(s) (${queryTerms.length} query term(s)); selected scores remain below cutoff`
-    } else if (filterQuery.trim().length > 0) {
-      signal = 'nonsense'
-      notice =
-        'C9: query has no lexical overlap with low-score chunks; fallback returned zero and no context was injected'
-    }
-  }
-
-  if (selected.length > 0 && signal === 'fallback-relative') {
-    const selectedSet = new Set(selected)
-    dropped.length = 0
-    dropped.push(...chunks.filter((chunk) => !selectedSet.has(chunk)))
-  }
   const context = buildC9Context(selected)
   return {
     selected,
@@ -384,15 +352,6 @@ function telemetry(
   }
 }
 
-function hasLexicalOverlap(query: string, chunks: readonly C9Chunk[]): boolean {
-  const queryTerms = lexicalTerms(query)
-  if (queryTerms.length === 0) return false
-  return chunks.some((chunk) => {
-    const chunkTerms = new Set(lexicalTerms(chunk.text))
-    return queryTerms.some((term) => chunkTerms.has(term))
-  })
-}
-
 /**
  * Prepare auditable context without performing retrieval or side effects.
  *
@@ -429,13 +388,8 @@ export function prepareC9Context(
     }
   }
 
-  const context =
-    filtered.signal === 'nonsense' ||
-    (filtered.signal === 'ok' && !hasLexicalOverlap(batch.query, filtered.selected))
-      ? ''
-      : buildC9Context(filtered.selected)
-  const signal =
-    context.length === 0 && filtered.signal === 'ok' ? ('nonsense' as const) : filtered.signal
+  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
@@ -446,52 +400,6 @@ export function prepareC9Context(
   }
 }
 
-/** Normalize query/text terms without introducing a semantic or runtime dependency. */
-function lexicalTerms(value: string): string[] {
-  return [
-    ...new Set(
-      value
-        .normalize('NFKD')
-        .replace(/\p{M}/gu, '')
-        .toLowerCase()
-        .match(/[\p{L}\p{N}]+/gu)
-        ?.filter((term) => term.length > 1) ?? [],
-    ),
-  ]
-}
-
-/** Select only query-matching low-score chunks, ranked lexically then relatively. */
-function relativeLexicalSelection(
-  byCategory: Map<string, C9Chunk[]>,
-  perCategory: Readonly<Record<string, C9CategoryConfig>> | undefined,
-  queryTerms: string[],
-): C9Chunk[] {
-  const selected: C9Chunk[] = []
-  for (const [category, group] of byCategory) {
-    const config = perCategory?.[category]
-    const topK = config?.topK ?? C9_DEFAULT_TOP_K
-    const maxScore = Math.max(...group.map((chunk) => chunk.score), 0)
-    const ranked = group
-      .map((chunk, index) => {
-        const textSet = new Set(lexicalTerms(chunk.text))
-        const overlap = queryTerms.filter((term) => textSet.has(term)).length
-        const lexicalScore = overlap / queryTerms.length
-        const relativeScore = maxScore > 0 ? chunk.score / maxScore : 0
-        return { chunk, index, lexicalScore, relativeScore }
-      })
-      .filter((entry) => entry.lexicalScore > 0)
-      .sort(
-        (left, right) =>
-          right.lexicalScore - left.lexicalScore ||
-          right.relativeScore - left.relativeScore ||
-          right.chunk.score - left.chunk.score ||
-          left.index - right.index,
-      )
-    selected.push(...ranked.slice(0, topK).map((entry) => entry.chunk))
-  }
-  return selected
-}
-
 function isC9FilterOptions(
   value: Readonly<Record<string, C9CategoryConfig>> | C9FilterOptions | string | undefined,
 ): value is C9FilterOptions {

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,22 @@ 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).
+              await deps.board.registerLaunchIfAbsent({
+                taskID: info.id,
+                parentSessionID: info.parentID,
+                agent: 'native',
+                description: `native child ${info.id}`,
+              })
             }
           }
         }

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,
@@ -30,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'
@@ -45,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,
@@ -53,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'
 
@@ -75,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()
@@ -165,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
@@ -504,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()
@@ -615,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
@@ -680,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