pantheon-opencode 1.3.7 → 1.4.1

package/src/pantheon/command-normalizer.ts

@@ -0,0 +1,101 @@
+/**
+ * Command Normalizer (Fase 1) — deterministic `python` → `python3` rewrite.
+ *
+ * Ubuntu 20.04+ ships only `python3` (PEP 394); the bare `python` command does
+ * not exist. Agents frequently emit `python` instead of `python3`, so every
+ * `bash` command is normalized BEFORE execution via the `tool.execute.before`
+ * hook. Unlike the read-only enforcement guard (which THROWS to deny), this
+ * guard REWRITES the command in place and lets it run.
+ *
+ * The rewrite is anchored to the regex below — it only matches `python` as a
+ * standalone command token (start of line or after a shell delimiter), never
+ * as a substring. This is what keeps `pip install python-dateutil` intact.
+ *
+ * @module command-normalizer
+ */
+
+// Matches `python` as a command token: at the start of the command or after a
+// shell delimiter (`;`, `&`, `|`, `(`, `)`, or a quote), followed by
+// whitespace or end. Quotes are included so `bash -c "python foo"` (a common
+// bypass) is normalized too. Deliberately NOT `\bpython\b` — that would
+// corrupt `python-dateutil` in `pip install python-dateutil` (the `-` is a
+// word boundary).
+const PYTHON_NORMALIZE_RE = /(^|[\s;&|()"'])python([\s]|$)/g
+
+/** Result of normalizing a command string. */
+export interface NormalizeResult {
+  /** The command with `python` → `python3` applied (unchanged if no match). */
+  normalized: string
+  /** Whether any rewrite actually happened. */
+  wasRewritten: boolean
+}
+
+/** Whether the command invokes `python -c` (arbitrary eval — flagged as risk). */
+const PYTHON_C_RE = /(^|[\s;&|()"'])python([\s]+)-c([\s]|$)/
+
+/**
+ * Normalize a bash command string, rewriting standalone `python` tokens to
+ * `python3`. Pure function — no side effects, safe to unit test directly.
+ */
+export function normalizePythonCommand(command: string): NormalizeResult {
+  // Reset lastIndex first — the regex is global and `.test()` advances it.
+  PYTHON_NORMALIZE_RE.lastIndex = 0
+  const wasRewritten = PYTHON_NORMALIZE_RE.test(command)
+  PYTHON_NORMALIZE_RE.lastIndex = 0
+  const normalized = command.replace(PYTHON_NORMALIZE_RE, '$1python3$2')
+  return { normalized, wasRewritten }
+}
+
+/** Whether the command contains a `python -c` invocation (arbitrary eval). */
+export function isPythonCEval(command: string): boolean {
+  PYTHON_C_RE.lastIndex = 0
+  return PYTHON_C_RE.test(command)
+}
+
+/** Minimal logger surface the guard needs (matches plugin logger shape). */
+export interface NormalizerLogger {
+  warn(message: string): void
+}
+
+/** Options for createCommandNormalizer(). */
+export interface CommandNormalizerOptions {
+  /** Audit sink for rewrites and `python -c` warnings. */
+  logger?: NormalizerLogger
+}
+
+/**
+ * Build the `tool.execute.before` handler that rewrites `bash` commands.
+ * Only the `bash` tool is touched; every other tool passes through untouched.
+ * The rewrite mutates `output.args.command` so the normalized command is what
+ * actually executes. Never throws — normalization must not break a session.
+ */
+export function createCommandNormalizer(
+  options: CommandNormalizerOptions = {},
+): (input: { tool: string; sessionID: string }, output?: { args?: unknown }) => Promise<void> {
+  const logger = options.logger
+
+  return async (input, output): Promise<void> => {
+    if (input.tool !== 'bash') return
+    if (output?.args === null || typeof output?.args !== 'object') return
+
+    const args = output.args as Record<string, unknown>
+    const command = args.command
+    if (typeof command !== 'string' || command.trim() === '') return
+
+    const { normalized, wasRewritten } = normalizePythonCommand(command)
+
+    if (isPythonCEval(command)) {
+      logger?.warn(
+        `[command-normalizer] WARNING python -c detected: session=${input.sessionID} command="${command}"`,
+      )
+    }
+
+    if (wasRewritten) {
+      args.command = normalized
+      logger?.warn(
+        `[command-normalizer] python→python3 rewritten: session=${input.sessionID} ` +
+          `original="${command}" normalized="${normalized}"`,
+      )
+    }
+  }
+}

package/src/pantheon/compaction-assert.ts

@@ -1,37 +1,31 @@
 /**
- * Compaction Re-Assert (release-134 Phase 4) — re-inject fresh state after
- * compaction.
+ * Compaction Re-Assert (release-134 Phase 4) — detect fresh state after
+ * compaction without writing to the chat transcript.
  *
  * WHY: after a session is compacted, the system state may have changed since
  * the summary was built (new background delegations launched, results
  * delivered, goals updated). The compacted session's context is frozen at
  * summary time — the model would operate on stale state.
  *
- * HOW: the `session.compacted` event hook calls `reassertAfterCompaction`,
- * which builds a COMPACT fresh-state block (running + unread delegations from
- * the board, active goals from the GoalStore — same gating as Phase 2) and
- * enqueues it into the SHARED chat-reminder buffer (chat-reminders.ts). The
- * existing pantheon-hooks `chat.message` hook delivers it as a
- * <system-reminder> into the session's next message — zero new delivery
- * code, and the P0 messageID guard already protects subagent fires.
+ * HOW: the compaction lifecycle keeps the board and goal stores authoritative;
+ * the `experimental.session.compacting` hook builds the context that is
+ * consumed by the compaction itself. Chat is never used as a delivery channel.
  *
  * Deliberately NOT `session.promptAsync({noReply:true})`: the sprint 4+7
  * spike refuted noReply as a push mechanism on this opencode build (nothing
  * is delivered to the parent).
  *
- * FAIL-OPEN: every source (board list, goals list, enqueue) is wrapped —
+ * FAIL-OPEN: every source (board list and goals list) is wrapped —
  * a failure logs a warn via the silence-by-default logger and the hook never
  * throws. A session with NO fresh state (nothing running/unread/goals) is a
- * SILENT skip (no warn, no reminder). The block is capped at
+ * SILENT skip (no warn). The block is capped at
  * REASSERT_MAX_LINES item lines (1 header) so it stays compact.
  *
- * Pure TypeScript — zero runtime deps beyond the board/goal types and the
- * shared reminder buffer.
+ * Pure TypeScript — zero runtime deps beyond the board/goal types.
  *
  * @module compaction-assert
  */
 import type { BackgroundJobBoard } from './background-job-board.ts'
-import { enqueueChatReminder } from './chat-reminders.ts'
 import type { CompactionGoalSource } from './delegation-compaction.ts'
 import { createPantheonLogger } from './logger.ts'
 
@@ -51,16 +45,16 @@ export const REASSERT_HEADER = 'State re-assertion after compaction — the summ
 
 /** Dependencies threaded to reassertAfterCompaction (wired from plugin.ts). */
 export interface CompactionAssertDeps {
-  /** The compacted session whose next message receives the reminder. */
+  /** The session whose compaction context is being prepared. */
   sessionID: string
   /** Board query surface — `list` is all the re-assertion needs. */
   board: Pick<BackgroundJobBoard, 'list'>
   /** Goal source for the goals block (optional — same gating as Phase 2). */
   goals?: CompactionGoalSource
-  /** Injectable enqueue (testable). Defaults to the shared chat buffer. */
-  enqueue?: (text: string) => void
   /** Injectable warn logger (testable). Defaults to silence-by-default. */
   logger?: { warn: (message: string) => void }
+  /** Non-chat delivery sink (for example a pending `output.context` block). */
+  deliverContext?: (context: string[]) => void | Promise<void>
 }
 
 // ─── Formatting ────────────────────────────────────────────────────────
@@ -135,26 +129,32 @@ async function buildStateLines(
 }
 
 /**
- * Re-assert fresh state for a compacted session: build the compact block and
- * enqueue it as a chat reminder (delivered on the session's next message).
+ * Re-assert fresh state for a compacted session and return the context block
+ * to the non-chat caller. The caller can hand this array to OpenCode's
+ * `output.context` or persist it through the board; constructing it here and
+ * throwing it away would make the hook a no-op.
  *
- * Returns true when a reminder was enqueued; false when there was nothing to
- * assert (silent skip) or a source failed (warned). NEVER throws — the event
- * hook must never break the session.
+ * Returns the fresh-state context when found, or undefined when there was
+ * nothing to assert (silent skip) or a source failed (warned). NEVER throws —
+ * the event hook must never break the session.
  */
-export async function reassertAfterCompaction(deps: CompactionAssertDeps): Promise<boolean> {
+export async function reassertAfterCompaction(
+  deps: CompactionAssertDeps,
+): Promise<string[] | undefined> {
   // Silence-by-default logger: file-only warn, console echo opt-in via
   // PANTHEON_HOOKS_LOG=1 (TUI pollution policy, pantheon-hooks L42-58).
   const warn = deps.logger?.warn ?? ((message: string) => log.warn(message))
   try {
     const lines = await buildStateLines(deps, warn)
-    if (lines === undefined) return false
-    const enqueue = deps.enqueue ?? enqueueChatReminder
-    enqueue(`${REASSERT_HEADER}\n${lines.join('\n')}`)
-    return true
+    if (lines === undefined) return undefined
+    // This is a context return value, not a chat message. The caller owns the
+    // supported delivery path (output.context or persisted board state).
+    const context = [REASSERT_HEADER, ...lines]
+    await deps.deliverContext?.(context)
+    return context
   } catch (err: unknown) {
     const reason = err instanceof Error ? err.message : String(err)
     warn(`compaction re-assert failed for session ${deps.sessionID}: ${reason}`)
-    return false
+    return undefined
   }
 }

package/src/pantheon/context-sandbox.ts

@@ -0,0 +1,273 @@
+/**
+ * Tool Output Sandboxing — Context Window Optimization (v2 P0)
+ *
+ * Truncates oversized tool outputs before they flood the context window.
+ * Pure truncation with metadata — no tiktoken, no LLM summarization (YAGNI).
+ *
+ * Hook: tool.execute.after — intercepts read/grep/glob/webfetch outputs.
+ *
+ * @module pantheon/context-sandbox
+ */
+
+export interface ToolExecuteAfterInput {
+  tool: string
+  sessionID: string
+  callID: string
+  args?: unknown
+}
+
+export interface ToolExecuteAfterOutput {
+  title?: string
+  output: string
+  metadata?: Record<string, unknown>
+}
+
+export type ToolExecuteAfterHandler = (
+  input: ToolExecuteAfterInput,
+  output: ToolExecuteAfterOutput,
+) => Promise<void>
+
+export interface SandboxToolLimits {
+  read: { maxLines: number; keepHead: number; keepTail: number }
+  grep: { maxResults: number; keepTop: number }
+  glob: { maxFiles: number; keepTop: number }
+  webfetch: { maxChars: number; keepHead: number }
+}
+
+export interface ContextSandboxConfig {
+  enabled: boolean
+  limits: SandboxToolLimits
+}
+
+/** Default limits — sensatos, cobrem 80% do problema com ~30 LOC. */
+export const DEFAULT_LIMITS: SandboxToolLimits = {
+  read: { maxLines: 200, keepHead: 50, keepTail: 10 },
+  grep: { maxResults: 20, keepTop: 10 },
+  glob: { maxFiles: 50, keepTop: 20 },
+  webfetch: { maxChars: 5000, keepHead: 2000 },
+}
+
+export const DEFAULT_CONFIG: ContextSandboxConfig = {
+  enabled: true,
+  limits: DEFAULT_LIMITS,
+}
+
+// ─── Pure sandbox functions ──────────────────────────────────────────────
+
+/**
+ * Sandbox truncation for `read` tool output.
+ * Input is expected to be line-numbered read output (e.g. "1: foo").
+ * If lines > maxLines, keep head + marker + tail.
+ */
+export function sandboxRead(output: string, limits = DEFAULT_LIMITS.read): string {
+  const lines = output.split('\n')
+  // trailing empty after final newline is not a real line — drop it for counting
+  const effectiveCount =
+    lines.length > 0 && lines[lines.length - 1] === '' ? lines.length - 1 : lines.length
+  if (effectiveCount <= limits.maxLines) return output
+
+  const head = lines.slice(0, limits.keepHead)
+  const tail =
+    limits.keepTail > 0
+      ? lines.slice(Math.max(limits.keepHead, effectiveCount - limits.keepTail), effectiveCount)
+      : []
+  const hidden = effectiveCount - head.length - tail.length
+  const marker = `[TRUNCATED: ${hidden} lines hidden — showing ${head.length} head + ${tail.length} tail of ${effectiveCount} total lines]`
+
+  // Preserve trailing newline semantics of original if present
+  const hadTrailingNewline = output.endsWith('\n')
+  const parts = [...head, marker, ...tail]
+  let result = parts.join('\n')
+  if (hadTrailingNewline) result += '\n'
+  return result
+}
+
+/**
+ * Sandbox truncation for `grep` tool output.
+ * Each non-empty line is considered a match. Keeps top N, drops tail.
+ */
+export function sandboxGrep(output: string, limits = DEFAULT_LIMITS.grep): string {
+  const lines = output.split('\n')
+  const effectiveCount =
+    lines.length > 0 && lines[lines.length - 1] === '' ? lines.length - 1 : lines.length
+  // Count non-empty? spec says 20 results — treat every line as result for simplicity,
+  // but filter obvious empties: if effective count includes empty trailing, already handled.
+  // Use effectiveCount as result count.
+  if (effectiveCount <= limits.maxResults) return output
+
+  const head = lines.slice(0, limits.keepTop)
+  const hidden = effectiveCount - head.length
+  const marker = `[TRUNCATED: Showing ${head.length} of ${effectiveCount} matches — ${hidden} more hidden. Use more specific pattern.]`
+  const hadTrailingNewline = output.endsWith('\n')
+  let result = [...head, marker].join('\n')
+  if (hadTrailingNewline) result += '\n'
+  return result
+}
+
+/**
+ * Sandbox truncation for `glob` tool output.
+ * Each line is a file path. Keeps top N.
+ */
+export function sandboxGlob(output: string, limits = DEFAULT_LIMITS.glob): string {
+  const lines = output.split('\n')
+  const effectiveCount =
+    lines.length > 0 && lines[lines.length - 1] === '' ? lines.length - 1 : lines.length
+  if (effectiveCount <= limits.maxFiles) return output
+
+  const head = lines.slice(0, limits.keepTop)
+  const hidden = effectiveCount - head.length
+  const marker = `[TRUNCATED: showing ${head.length} of ${effectiveCount} files — ${hidden} more hidden]`
+  const hadTrailingNewline = output.endsWith('\n')
+  let result = [...head, marker].join('\n')
+  if (hadTrailingNewline) result += '\n'
+  return result
+}
+
+/**
+ * Sandbox truncation for `webfetch` tool output.
+ * Character-based: keep head chars, drop rest.
+ */
+export function sandboxWebfetch(output: string, limits = DEFAULT_LIMITS.webfetch): string {
+  if (output.length <= limits.maxChars) return output
+  const head = output.slice(0, limits.keepHead)
+  const hidden = output.length - head.length
+  const marker = `\n[TRUNCATED: Content truncated — showing first ${head.length} of ${output.length} chars, ${hidden} chars hidden]\n`
+  return head + marker
+}
+
+/**
+ * Dispatch sandbox truncation by tool name. Pure function — no I/O.
+ * Unknown tools pass through unchanged.
+ */
+export function sandboxOutput(
+  tool: string,
+  output: string,
+  limits: SandboxToolLimits = DEFAULT_LIMITS,
+): string {
+  if (typeof output !== 'string' || output.length === 0) return output
+  const normalized = tool.trim().toLowerCase()
+  switch (normalized) {
+    case 'read':
+      return sandboxRead(output, limits.read)
+    case 'grep':
+      return sandboxGrep(output, limits.grep)
+    case 'glob':
+      return sandboxGlob(output, limits.glob)
+    case 'webfetch':
+    case 'fetch':
+    case 'web_fetch':
+      return sandboxWebfetch(output, limits.webfetch)
+    default:
+      return output
+  }
+}
+
+// ─── Plugin hook factory ───────────────────────────────────────────────
+
+/**
+ * Resolve sandbox config from opencode.json `context_sandbox` block.
+ * Fail-open: any missing/invalid field falls back to defaults.
+ */
+export function resolveSandboxConfig(raw?: unknown): ContextSandboxConfig {
+  if (raw === null || raw === undefined || typeof raw !== 'object')
+    return { ...DEFAULT_CONFIG, limits: { ...DEFAULT_LIMITS } }
+  const obj = raw as Record<string, unknown>
+  const enabled = typeof obj.enabled === 'boolean' ? obj.enabled : true
+  const limitsRaw = obj.limits as Record<string, unknown> | undefined
+
+  const limits: SandboxToolLimits = {
+    read: {
+      maxLines:
+        typeof limitsRaw?.read === 'object' &&
+        limitsRaw.read !== null &&
+        typeof (limitsRaw.read as Record<string, unknown>).maxLines === 'number'
+          ? ((limitsRaw.read as Record<string, unknown>).maxLines as number)
+          : DEFAULT_LIMITS.read.maxLines,
+      keepHead:
+        typeof limitsRaw?.read === 'object' &&
+        limitsRaw.read !== null &&
+        typeof (limitsRaw.read as Record<string, unknown>).keepHead === 'number'
+          ? ((limitsRaw.read as Record<string, unknown>).keepHead as number)
+          : DEFAULT_LIMITS.read.keepHead,
+      keepTail:
+        typeof limitsRaw?.read === 'object' &&
+        limitsRaw.read !== null &&
+        typeof (limitsRaw.read as Record<string, unknown>).keepTail === 'number'
+          ? ((limitsRaw.read as Record<string, unknown>).keepTail as number)
+          : DEFAULT_LIMITS.read.keepTail,
+    },
+    grep: {
+      maxResults:
+        typeof limitsRaw?.grep === 'object' &&
+        limitsRaw.grep !== null &&
+        typeof (limitsRaw.grep as Record<string, unknown>).maxResults === 'number'
+          ? ((limitsRaw.grep as Record<string, unknown>).maxResults as number)
+          : DEFAULT_LIMITS.grep.maxResults,
+      keepTop:
+        typeof limitsRaw?.grep === 'object' &&
+        limitsRaw.grep !== null &&
+        typeof (limitsRaw.grep as Record<string, unknown>).keepTop === 'number'
+          ? ((limitsRaw.grep as Record<string, unknown>).keepTop as number)
+          : DEFAULT_LIMITS.grep.keepTop,
+    },
+    glob: {
+      maxFiles:
+        typeof limitsRaw?.glob === 'object' &&
+        limitsRaw.glob !== null &&
+        typeof (limitsRaw.glob as Record<string, unknown>).maxFiles === 'number'
+          ? ((limitsRaw.glob as Record<string, unknown>).maxFiles as number)
+          : DEFAULT_LIMITS.glob.maxFiles,
+      keepTop:
+        typeof limitsRaw?.glob === 'object' &&
+        limitsRaw.glob !== null &&
+        typeof (limitsRaw.glob as Record<string, unknown>).keepTop === 'number'
+          ? ((limitsRaw.glob as Record<string, unknown>).keepTop as number)
+          : DEFAULT_LIMITS.glob.keepTop,
+    },
+    webfetch: {
+      maxChars:
+        typeof limitsRaw?.webfetch === 'object' &&
+        limitsRaw.webfetch !== null &&
+        typeof (limitsRaw.webfetch as Record<string, unknown>).maxChars === 'number'
+          ? ((limitsRaw.webfetch as Record<string, unknown>).maxChars as number)
+          : DEFAULT_LIMITS.webfetch.maxChars,
+      keepHead:
+        typeof limitsRaw?.webfetch === 'object' &&
+        limitsRaw.webfetch !== null &&
+        typeof (limitsRaw.webfetch as Record<string, unknown>).keepHead === 'number'
+          ? ((limitsRaw.webfetch as Record<string, unknown>).keepHead as number)
+          : DEFAULT_LIMITS.webfetch.keepHead,
+    },
+  }
+  return { enabled, limits }
+}
+
+/**
+ * Create the `tool.execute.after` handler that sandboxes oversized outputs.
+ * The handler mutates `output.output` in-place and tags metadata when truncated.
+ * Fail-open: never throws.
+ */
+export function createContextSandbox(
+  config: ContextSandboxConfig = DEFAULT_CONFIG,
+): ToolExecuteAfterHandler {
+  // Capture mutable reference — caller (plugin config hook) may update limits live
+  const cfgRef = config
+  return async (input: ToolExecuteAfterInput, output: ToolExecuteAfterOutput): Promise<void> => {
+    try {
+      if (!cfgRef.enabled) return
+      if (typeof output.output !== 'string') return
+      const before = output.output
+      const after = sandboxOutput(input.tool, before, cfgRef.limits)
+      if (after !== before) {
+        output.output = after
+        output.metadata = {
+          ...(output.metadata ?? {}),
+          truncated: true,
+          sandbox: input.tool.toLowerCase(),
+        }
+      }
+    } catch {
+      // never break the tool result
+    }
+  }
+}

package/src/pantheon/delegation-finalize.ts

@@ -172,24 +172,48 @@ export const DELEGATION_DEFAULTS = {
 
 // ─── Output pulling ────────────────────────────────────────────────────
 
-/** Concatenate every non-empty text part across the child's messages. */
-async function pullOutput(client: DelegationClient, childSessionID: string): Promise<string> {
+interface PulledOutput {
+  text: string
+  /** True only when the child produced an assistant message or tool activity. */
+  hasWork: boolean
+}
+
+/** Pull visible text and structurally identify real child work. */
+async function pullOutput(client: DelegationClient, childSessionID: string): Promise<PulledOutput> {
   if (typeof client.session.messages !== 'function')
-    return '(child session messages API unavailable)'
+    return { text: '(child session messages API unavailable)', hasWork: false }
   try {
     const bundles = await client.session.messages({ path: { id: childSessionID } })
     const lines: string[] = []
+    let hasWork = false
     for (const bundle of bundles) {
+      const hasToolPart = (bundle.parts ?? []).some((part) => part.type === 'tool')
+      const hasTextPart = (bundle.parts ?? []).some(
+        (part) => part.type === 'text' && typeof part.text === 'string' && part.text.trim() !== '',
+      )
+      if (
+        bundle.info?.role === 'assistant' &&
+        bundle.info.error === undefined &&
+        (hasToolPart || hasTextPart)
+      ) {
+        hasWork = true
+      }
       for (const part of bundle.parts ?? []) {
+        if (
+          part.type === 'tool' &&
+          bundle.info?.role === 'assistant' &&
+          bundle.info.error === undefined
+        )
+          hasWork = true
         if (part.type === 'text' && typeof part.text === 'string' && part.text.trim() !== '') {
           lines.push(part.text)
         }
       }
     }
-    return lines.join('\n\n')
+    return { text: lines.join('\n\n'), hasWork }
   } catch (err: unknown) {
     const reason = err instanceof Error ? err.message : String(err)
-    return `(failed to pull child session output: ${reason})`
+    return { text: `(failed to pull child session output: ${reason})`, hasWork: false }
   }
 }
 
@@ -311,9 +335,18 @@ export async function finalizeDelegation(
   const job = deps.board.get(childSessionID)
   if (!job) return undefined
 
-  const output = await pullOutput(deps.client, childSessionID)
+  const pulled = await pullOutput(deps.client, childSessionID)
+  const output = pulled.text
+  const effectiveOpts: FinalizeInput =
+    opts.state === 'completed' && !pulled.hasWork
+      ? {
+          state: 'error',
+          error: opts.error ?? 'Child session produced no assistant or tool output',
+          ...(opts.timedOut !== undefined ? { timedOut: opts.timedOut } : {}),
+        }
+      : opts
   const outputDir = deps.options.outputDir ?? DELEGATION_DEFAULTS.outputDir
-  await writeDelegationReport(outputDir, job, renderDelegationMarkdown(job, output, opts))
+  await writeDelegationReport(outputDir, job, renderDelegationMarkdown(job, output, effectiveOpts))
 
   const status: {
     taskID: string
@@ -323,15 +356,15 @@ export async function finalizeDelegation(
     resultSummary?: string
   } = {
     taskID: childSessionID,
-    state: opts.state,
+    state: effectiveOpts.state,
     resultSummary: summarizeOutput(output),
   }
-  if (opts.error !== undefined) status.error = opts.error
-  if (opts.timedOut !== undefined) status.timedOut = opts.timedOut
+  if (effectiveOpts.error !== undefined) status.error = effectiveOpts.error
+  if (effectiveOpts.timedOut !== undefined) status.timedOut = effectiveOpts.timedOut
 
   const current = deps.board.get(childSessionID)
   if (current !== undefined) {
-    if (current.state === 'running' || current.state === opts.state) {
+    if (current.state === 'running' || current.state === effectiveOpts.state) {
       await deps.board.updateStatus(status)
     }
     // Terminal in a DIFFERENT state (e.g. timeout already recorded) — the

package/src/pantheon/delegation-toast.ts

@@ -0,0 +1,73 @@
+import type { BackgroundJobRecord } from './background-job-board.ts'
+
+type ToastCategory = 'errors' | 'delegations' | 'council'
+
+const toastMode = (process.env.PANTHEON_TOASTS ?? '').trim().toLowerCase()
+const enabledToastCategories: ReadonlySet<ToastCategory> = (() => {
+  switch (toastMode) {
+    case 'off':
+      return new Set()
+    case 'errors':
+      return new Set(['errors'])
+    case 'council':
+      return new Set(['errors', 'council'])
+    case 'all':
+      return new Set(['errors', 'delegations', 'council'])
+    default:
+      return new Set(['errors', 'delegations', 'council'])
+  }
+})()
+const terminalToastsShown = new Set<string>()
+const terminalStates = new Set(['completed', 'error', 'cancelled'])
+
+/** Match the lifecycle toast gate used by pantheon-hooks. */
+export function delegationToastEnabled(): boolean {
+  return enabledToastCategories.has('delegations')
+}
+
+export type ToastClient = {
+  tui?: {
+    showToast?: (input: {
+      body: {
+        title?: string
+        message: string
+        variant: 'info' | 'success' | 'warning' | 'error'
+        duration: number
+      }
+    }) => Promise<unknown>
+  }
+}
+
+/** Best-effort visual completion signal; never affects board finalization. */
+export async function showDelegationTerminalToast(
+  client: ToastClient,
+  job: Pick<BackgroundJobRecord, 'taskID' | 'alias' | 'agent' | 'state' | 'timedOut'>,
+): Promise<void> {
+  try {
+    if (!delegationToastEnabled()) return
+    const isTerminal = job.timedOut || terminalStates.has(job.state)
+    if (isTerminal) {
+      if (terminalToastsShown.has(job.taskID)) return
+      terminalToastsShown.add(job.taskID)
+    }
+    const showToast = client.tui?.showToast
+    if (typeof showToast !== 'function') return
+    const state = job.timedOut ? 'timeout' : job.state
+    const variant =
+      state === 'completed'
+        ? 'success'
+        : state === 'error' || state === 'timeout'
+          ? 'error'
+          : 'warning'
+    await showToast({
+      body: {
+        title: 'Delegação concluída',
+        message: `${job.alias} (${job.agent}) — ${state}`,
+        variant,
+        duration: 4000,
+      },
+    })
+  } catch {
+    // TUI is optional (and may disappear during shutdown); completion is durable.
+  }
+}