pantheon-opencode 1.5.0-beta.16 → 1.5.0-beta.17

package/CHANGELOG.md

@@ -18,6 +18,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## ✅ Closed Issues
 
+## [v1.5.0-beta.17] - 2026-09-15
+
+<!-- Add new changes here. Running `node scripts/versioning.mjs apply` will
+     move this section to a versioned entry and reset the template below. -->
+
+## 🆕 What's New
+
+- **Delegação nativa no host:** o motor `pantheon_delegate` foi removido
+  (~3,9k linhas) junto com as tools `pantheon_delegate`,
+  `pantheon_delegation_read` e `pantheon_delegation_list`; a delegação agora usa
+  o **`task()` nativo** do host (child sessions). 16 arquivos de teste obsoletos
+  removidos.
+- **TUI — painel Delegations lê a sessão nativa:** o painel passa a derivar de
+  `session.children` + `session.status` + md (o arquivo de board deixou de ser
+  fonte). Mantidas as cores de status, retenção, ceiling, filtro de sessão e
+  guards.
+- **Camada fina preservada:** `task-result-guard` (verified completion de child
+  vazio), `native-task-status` e guards de enforcement.
+
+## 🐞 Fixed
+
+- **Read-only enforcement re-apontado para sessões nativas:** aplicado no
+  público via hook `chat.params` e `hashline_edit` bloqueado para `apollo`/`gaia`,
+  fechando o bypass aberto após a remoção do motor de delegação.
+- **Docs/comentários limpos:** referências aos módulos removidos atualizadas,
+  incluindo nits de comentário em `tests/pantheon/tui-delegations.test.ts` e
+  `src/pantheon/session-id.ts`.
+
 ## [v1.5.0-beta.16] - 2026-09-15
 
 <!-- Add new changes here. Running `node scripts/versioning.mjs apply` will

package/README.md

@@ -76,25 +76,14 @@ availability and configuration of OpenCode and any optional services you choose
 to use. Check the [releases](https://github.com/ils15/pantheon-opencode/releases)
 and [changelog](CHANGELOG.md) for the latest published changes.
 
-## Delegation engines (legacy default, native opt-in)
+## Delegation (native `task()`)
 
-Pantheon exposes two delegation engines behind one tool surface:
-
-- **Legacy (default)** — `pantheon_delegate`, the original engine registered by
-  the V1 plugin. No configuration is required.
-- **Native (opt-in, experimental)** — OpenCode's native `task()` child-session
-  engine, selected with `PANTHEON_DELEGATE_MODE=native`. Native is strict: it
-  does not use foreground fallback, model failover, or retry; it performs a
-  lazy capability probe on the first dispatch and includes the resulting
-  status in the delegation receipt.
-
-Legacy stays the default for v1.5.x; native is not promoted to default until
-v1.6. See [ADR-0011](.pantheon/memory-bank/adr/0011-delegation-engine-contract.md)
-(Proposed) for the engine contract, rationale, and migration prerequisites.
-
-**Kill-switch:** set `PANTHEON_DELEGATION=off` (case-insensitive) to disable
-delegation entirely. The switch covers **both** engines — the legacy
-`pantheon_delegate`/read/list tools throw, and the native manager throws too.
+Pantheon delegates exclusively through OpenCode's native `task()` child-session
+engine. The former custom `pantheon_delegate` tool and the V1 delegation engine
+(`delegation.ts`, `delegate-manager.ts` and supporting modules) were removed;
+there is no Pantheon-specific delegation tool surface to configure. See
+[ADR-0011](.pantheon/memory-bank/adr/0011-delegation-engine-contract.md) for the
+historical engine contract.
 
 ## Cost tool backend
 
@@ -185,23 +174,22 @@ per installation; V1 and V2 Pantheon plugins must never be registered together.
 |---|---|---|
 | OpenCode config key | singular `plugin` | plural `plugins` |
 | Pantheon registration | `src/plugin.ts` plus `src/plugins/pantheon-hooks.ts` | `<installed>/src/plugin-v2` directory (`index.ts` re-exports `src/plugin-v2.ts`) |
-| Runtime contract | Legacy Pantheon plugin, including `pantheon_delegate`, read/list tools, event/tool hooks and V1 compaction handling | Full V2 plugin: 9 orchestration tools, 4 event subscriptions, session hooks (`prompt`, `context`), tool hooks (`execute.before`/`after`), plus configuration transforms |
+| Runtime contract | Pantheon V1 plugin: 6 tools (`hashline_edit`, the 3 goal tools, `pantheon_cost`, `pantheon_model`), event/tool hooks and V1 compaction handling | Full V2 plugin: 6 orchestration tools, 4 event subscriptions, session hooks (`prompt`, `context`), tool hooks (`execute.before`/`after`), plus configuration transforms |
 | V1 APIs | Registered | Own tool definitions via `ctx.tool.transform()` — not the V1 plugin path |
 
-The V2 plugin provides 9 orchestration tools (`pantheon_delegate`,
-`pantheon_delegation_read`, `pantheon_delegation_list`, `hashline_edit`,
+The V2 plugin provides 6 orchestration tools (`hashline_edit`,
 `pantheon_goal_create`, `pantheon_goal_get`, `pantheon_goal_update`,
 `pantheon_cost`, `pantheon_model`), 4 event subscriptions (`session.created`,
 `session.idle`, `session.error`, `session.compacted`), session hooks (`prompt`,
 `context`), and tool hooks (`execute.before`, `execute.after`). The only
-unsupported V2 feature is `legacy-hooks` (the V1-specific delegate API surface).
+unsupported V2 feature is `legacy-hooks` (the V1-specific hook surface).
 
 The package exposes both contracts as importable exports: `pantheon-opencode/plugin`
 (V1), `pantheon-opencode/plugin-v2` (V2) and `pantheon-opencode/v2-bridge`
 (optional interop), so a host can load either contract explicitly.
 
 The V1→V2 bridge (`src/pantheon/v2-bridge.ts`) enables optional interop:
-V1 infrastructure singletons (BackgroundJobBoard, DelegationClient, GoalStore,
+V1 infrastructure singletons (BackgroundJobBoard, GoalStore,
 TodoEnforcer, VisionHandler) are passed through V2 `ctx.options`. The bridge is
 optional — V2 works standalone with graceful degradation.
 
@@ -339,8 +327,8 @@ child session returns an empty or missing result. Instead of surfacing a silent
 `completed` with no payload (which confuses the orchestrator), the guard now
 raises an explicit error. This catches the common free-tier failure mode where a
 child session exceeds the uncached-prefill token budget (`BackendAdmissionRejected`)
-and returns nothing. For large payloads, prefer `pantheon_delegate` over native
-`task()` — the delegation layer has better timeout and error handling.
+and returns nothing. Prefer `background=true` dispatches with an explicit
+`task_status(wait=true)` fan-in so large payloads are collected deterministically.
 
 
 ## Documentation

package/README.pt-BR.md

@@ -130,16 +130,15 @@ registrados juntos.
 |---|---|---|
 | Chave de config do OpenCode | `plugin` singular | `plugins` plural |
 | Registro Pantheon | `src/plugin.ts` mais `src/plugins/pantheon-hooks.ts` | `pantheon-opencode/plugin-v2` (`src/plugin-v2.ts`) |
-| Contrato de runtime | Plugin Pantheon legado, incluindo `pantheon_delegate`, ferramentas read/list, hooks de evento/ferramenta e tratamento de compactação V1 | Plugin V2 completo: 9 ferramentas de orquestração, 4 assinaturas de eventos, session hooks (`prompt`, `context`), tool hooks (`execute.before`/`after`), além de transforms de configuração |
+| Contrato de runtime | Plugin Pantheon V1: 6 ferramentas (`hashline_edit`, as 3 ferramentas de goal, `pantheon_cost`, `pantheon_model`), hooks de evento/ferramenta e tratamento de compactação V1 | Plugin V2 completo: 6 ferramentas de orquestração, 4 assinaturas de eventos, session hooks (`prompt`, `context`), tool hooks (`execute.before`/`after`), além de transforms de configuração |
 | APIs V1 | Registradas | Definições próprias de ferramentas via `ctx.tool.transform()` — não pelo caminho do plugin V1 |
 
-O plugin V2 fornece 9 ferramentas de orquestração (`pantheon_delegate`,
-`pantheon_delegation_read`, `pantheon_delegation_list`, `hashline_edit`,
+O plugin V2 fornece 6 ferramentas de orquestração (`hashline_edit`,
 `pantheon_goal_create`, `pantheon_goal_get`, `pantheon_goal_update`,
 `pantheon_cost`, `pantheon_model`), 4 assinaturas de eventos (`session.created`,
 `session.idle`, `session.error`, `session.compacted`), session hooks (`prompt`,
 `context`) e tool hooks (`execute.before`, `execute.after`). O único recurso V2
-sem suporte é `legacy-hooks` (a superfície de API de delegate específica do V1).
+sem suporte é `legacy-hooks` (a superfície de hooks específica do V1).
 
 O pacote expõe os dois contratos como exports importáveis:
 `pantheon-opencode/plugin` (V1), `pantheon-opencode/plugin-v2` (V2) e
@@ -147,7 +146,7 @@ O pacote expõe os dois contratos como exports importáveis:
 explicitamente o contrato desejado.
 
 A ponte V1→V2 (`src/pantheon/v2-bridge.ts`) habilita interop opcional:
-singletons de infraestrutura V1 (BackgroundJobBoard, DelegationClient,
+singletons de infraestrutura V1 (BackgroundJobBoard,
 GoalStore, TodoEnforcer, VisionHandler) são repassados via `ctx.options` do V2.
 A ponte é opcional — o V2 funciona standalone com degradação graciosa.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.5.0-beta.16",
+  "version": "1.5.0-beta.17",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "type": "module",
   "publishConfig": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pantheon",
   "publisher": "ils15",
-  "version": "1.5.0-beta.16",
+  "version": "1.5.0-beta.17",
   "displayName": "Pantheon",
   "description": "Conductor-Delegate orchestration platform with 14 specialized agents, 21 skills, and OpenCode support.",
   "agents": "./src/agents",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.backends._legacy:_Backend"
 
 [project]
 name = "pantheon"
-version = "1.5.0-beta.16"
+version = "1.5.0-beta.17"
 description = "Multi-agent orchestration framework"
 requires-python = ">=3.11"
 dependencies = []

package/scripts/mcp_persistence_server.py

@@ -1323,7 +1323,7 @@ def build_rehydration_blocks(checkpoint: dict) -> list[str] | None:
     """Build deterministic rehydration blocks from a checkpoint dict.
 
     Pure string templating — no LLM, no embeddings. Mirrors the
-    ``<mission_context>`` convention of delegation-compaction.ts: only a
+    ``<mission_context>`` convention of the compaction-context builder: only a
     non-done goal is re-emitted. Returns None when nothing critical remains.
     """
     if not isinstance(checkpoint, dict) or not checkpoint:

package/src/agents/apollo.md

@@ -12,6 +12,7 @@ permission:
   glob: allow
   webfetch: allow
   edit: deny
+  hashline_edit: deny
   bash: deny
   task:
     "*": deny

package/src/agents/gaia.md

@@ -11,6 +11,7 @@ permission:
   grep: allow
   webfetch: allow
   edit: deny
+  hashline_edit: deny
   bash: deny
   task:
     "*": deny

package/src/agents/zeus.md

@@ -144,33 +144,11 @@ task_status(task_id="ses_xxx", wait=true)
   -> bloqueia ate completar: { state: "completed", task_result: "..." }
 ```
 
-### Pantheon Delegation Tools (plugin) — 3-tool API
+### DELEGATION_RULES (native task API)
 
-O plugin Pantheon adiciona 3 tools de delegacao gerenciada pelo BackgroundJobBoard:
-
-```
-pantheon_delegate({prompt, agent, description?, read_only?})
-  -> cria sessao filha, registra no board, retorna alias: [apo-1]
-pantheon_delegation_read({id: "apo-1"})
-  -> BLOQUEIA ate o job terminar, retorna o report markdown, marca reconciled
-  -> durante a espera, mostra o que o agente esta fazendo: seccao final "## Agent Activity"
-     (amostra as messages do child a cada ~2s; tool calls + args truncados / texto)
-pantheon_delegation_list()
-  -> lista jobs da sessao, com [unread] para jobs terminados nao lidos
-  -> jobs RUNNING mostram "last activity:" (ultima acao visivel do child)
-  -> fail-open: sem suporte a messages, formato atual inalterado
-```
-
-- **Read-only enforcement:** agentes read-only (apollo, gaia — `read_only_agents` no routing.yml) tem `edit`, `write`, `bash`, `task` NEGADOS dentro da sessao delegada (o guard de `tool.execute.before` THROW com mensagem acionavel). Use `read_only: true` no delegate para qualquer agente de investigacao.
-- **Depth-2 hard-enforced:** sessao read-only NAO cria subagentes (`task` bloqueado) — investigacao nunca vira arvore.
-- **Compactacao:** jobs em voo (running + unread terminal) sao injetados no contexto de compactacao via `experimental.session.compacting` — delegacao em andamento nao se perde ao compactar.
-
-### DELEGATION_RULES (plugin path)
-
-1. **NUNCA** polle `pantheon_delegation_list` para checar se um job terminou.
-2. Voce NAO recebe notificacao injetada no chat — politica do usuario: ZERO `task-notification` no transcript. Visibilidade de conclusao: marcador `[unread]` em `pantheon_delegation_list`, `pantheon_delegation_read({id})`, toasts TUI (pantheon-hooks) e carry-forward de compactacao.
-3. Use `pantheon_delegation_read({id})` APENAS para fan-in explicito / recuperacao de resultado sob demanda (bloqueia ate o fim).
-4. `pantheon_delegation_list` e para diagnostico, nao para polling.
+1. Todo dispatch usa `task(background=true, subagent_type=..., prompt=...)`.
+2. Recolha com `task_status(task_id=..., wait=true)` — bloqueia ate o fim, sem polling.
+3. Use `task_status(wait=true)` apenas para fan-in explicito / recuperacao sob demanda.
 
 ### Background (sempre usar)
 - **Apollo, Hermes, Aphrodite, Demeter, Hephaestus, Prometheus**
@@ -302,9 +280,10 @@ vão a idle com todos incompletos. Guards (todos no `src/pantheon/todo-enforcer.
 ## Wave 4 (PR #46): Empty-Result Retry + /cost + Themis Tier
 
 ### Empty-Result Retry (runtime — automatic)
-Empty-response detection (`empty-mode1` / `empty-mode2`) and stuck-agent
-classification are wired at runtime in `delegation-classifier.ts` (consumed by
-`delegation.ts`). No manual retry helper is required.
+Empty-response detection for native `task()` subagent calls is wired at runtime
+in `task-result-guard.ts` (plugin `tool.execute.after` chain): an
+empty/whitespace-only result is converted into an explicit error so a silent
+child failure is never mistaken for success. No manual retry helper is required.
 
 ### /cost — pantheon_cost tool (WIRED no plugin)
 `pantheon_cost({ days?: number })` le o `opencode.db` READ-ONLY usando o backend

package/src/mcp/mcp_persistence_server.py

@@ -1323,7 +1323,7 @@ def build_rehydration_blocks(checkpoint: dict) -> list[str] | None:
     """Build deterministic rehydration blocks from a checkpoint dict.
 
     Pure string templating — no LLM, no embeddings. Mirrors the
-    ``<mission_context>`` convention of delegation-compaction.ts: only a
+    ``<mission_context>`` convention of the compaction-context builder: only a
     non-done goal is re-emitted. Returns None when nothing critical remains.
     """
     if not isinstance(checkpoint, dict) or not checkpoint:

package/src/pantheon/{delegation-compaction.ts → compaction-context.ts}

@@ -1,8 +1,8 @@
 /**
- * Compaction Context (Phase 4 + release-134 Phase 2) — build the context
- * blocks injected by the `experimental.session.compacting` hook so a
- * compacted session does not lose its working state: in-flight background
- * delegations, active goals and pending todos.
+ * Compaction Context (Phase 4 + release-134 Phase 2, slimmed in Fase 2 of the
+ * delegate removal) — build the context blocks injected by the
+ * `experimental.session.compacting` hook so a compacted session does not lose
+ * its working state: active goals and pending todos.
  *
  * Returns a Promise<string[]> (empty when there is nothing to preserve).
  * Section order is stable:
@@ -17,23 +17,10 @@
  *     `opts.todos`: "  [id] description — status". Omitted when the todo
  *     source is absent, disabled, unscoped (no sessionID), fails, or has
  *     no pending todos.
- *   - "Background Delegations (running):" — every running job launched by
- *     the session (active work is never capped): alias, agent, started ISO,
- *     truncated prompt.
- *   - "Background Delegations (finished, unread):" — terminal-unreconciled
- *     jobs, newest first, capped at `maxItems` (default 10, matching
- *     routing.yml background_delegation.max_compaction_items).
  *
- * Reconciled jobs are excluded — they have been read already.
- *
- * The block style mirrors board.formatForPrompt ("  [alias] description —
- * STATUS") so compaction context reads consistently with the system prompt,
- * but with the extra id/agent/started detail the compaction hook needs.
- *
- * @module delegation-compaction
+ * @module compaction-context
  */
 
-import type { BackgroundJobBoard, BackgroundJobRecord } from './background-job-board.ts'
 import type { Goal } from './goal-store.ts'
 import { createPantheonLogger } from './logger.ts'
 import type { TodoLike } from './todo-enforcer.ts'
@@ -72,56 +59,14 @@ export interface CompactionTodoSource {
 }
 
 export interface CompactionContextOptions {
-  /** Scope to jobs launched by this session; omit for all jobs. */
+  /** Scope to this session; omit to skip the per-session sections. */
   sessionID?: string
-  /** Cap on unread terminal jobs kept (default 10). */
-  maxItems?: number
   /** Goal source for <mission_context> (optional — omitted when absent). */
   goals?: CompactionGoalSource
   /** Todo source for <todo_context> (optional — omitted when absent). */
   todos?: CompactionTodoSource
 }
 
-/** Prompt truncation length for a context line. */
-const PROMPT_MAX_LEN = 100
-
-// ─── Formatting ────────────────────────────────────────────────────────
-
-/** Collapse whitespace and truncate a prompt to PROMPT_MAX_LEN chars. */
-function truncatePrompt(text: string): string {
-  const flat = text.trim().replace(/\s+/g, ' ')
-  if (flat.length <= PROMPT_MAX_LEN) return flat
-  return `${flat.slice(0, PROMPT_MAX_LEN)}…`
-}
-
-/** One-line terminal status label, mirroring formatForPrompt. */
-function terminalLabel(state: BackgroundJobRecord['state']): string {
-  switch (state) {
-    case 'completed':
-      return 'OK'
-    case 'error':
-      return 'ERR'
-    case 'cancelled':
-      return 'CAN'
-    default:
-      return state.toUpperCase()
-  }
-}
-
-function runningLine(job: BackgroundJobRecord): string {
-  return (
-    `  [${job.alias}] ${job.agent} — ${truncatePrompt(job.description)} — ` +
-    `RUNNING since ${new Date(job.launchedAt).toISOString()}`
-  )
-}
-
-function unreadTerminalLine(job: BackgroundJobRecord): string {
-  return (
-    `  [${job.alias}] ${job.agent} — ${truncatePrompt(job.description)} — ` +
-    `${terminalLabel(job.state)} ${new Date(job.updatedAt).toISOString()} [unread]`
-  )
-}
-
 // ─── Sections ──────────────────────────────────────────────────────────
 
 /**
@@ -180,58 +125,23 @@ async function todoContextBlock(opts: CompactionContextOptions): Promise<string
   return `<todo_context>\n${lines.join('\n')}`
 }
 
-/**
- * `<delegation_context>` — the existing delegation blocks, byte-for-byte
- * unchanged from Phase 4 (running, then unread terminal ≤ maxItems).
- */
-function delegationBlocks(board: BackgroundJobBoard, opts: CompactionContextOptions): string[] {
-  const maxItems = opts.maxItems ?? 10
-  const jobs = opts.sessionID !== undefined ? board.list(opts.sessionID) : board.list()
-
-  const running = jobs
-    .filter((j) => j.state === 'running')
-    .sort((a, b) => a.launchedAt - b.launchedAt)
-  const unreadTerminal = jobs
-    .filter((j) => j.terminalUnreconciled)
-    .sort((a, b) => b.updatedAt - a.updatedAt)
-    .slice(0, maxItems)
-
-  const blocks: string[] = []
-  if (running.length > 0) {
-    blocks.push(`Background Delegations (running):\n${running.map(runningLine).join('\n')}`)
-  }
-  if (unreadTerminal.length > 0) {
-    blocks.push(
-      `Background Delegations (finished, unread):\n${unreadTerminal
-        .map(unreadTerminalLine)
-        .join('\n')}`,
-    )
-  }
-  return blocks
-}
-
 // ─── Build ─────────────────────────────────────────────────────────────
 
 /**
  * Build the compaction context blocks for a session: preservation
- * directive, active goals, pending todos, and in-flight background
- * delegations. Returns an empty array when there is nothing to preserve
- * (caller skips the hook injection entirely).
+ * directive, active goals, and pending todos. Returns an empty array when
+ * there is nothing to preserve (caller skips the hook injection entirely).
  */
 export async function buildCompactionContext(
-  board: BackgroundJobBoard,
   opts: CompactionContextOptions = {},
 ): Promise<string[]> {
   const [mission, todo] = await Promise.all([missionContextBlock(opts), todoContextBlock(opts)])
-  const delegation = delegationBlocks(board, opts)
 
   // Totally-empty state → nothing to preserve; a lone directive is noise.
-  if (mission === undefined && todo === undefined && delegation.length === 0) return []
+  if (mission === undefined && todo === undefined) return []
 
-  const blocks: string[] = []
-  blocks.push(`<pantheon-context directive>\n${PANTHEON_COMPACTION_DIRECTIVE}`)
+  const blocks: string[] = [`<pantheon-context directive>\n${PANTHEON_COMPACTION_DIRECTIVE}`]
   if (mission !== undefined) blocks.push(mission)
   if (todo !== undefined) blocks.push(todo)
-  blocks.push(...delegation)
   return blocks
 }

package/src/pantheon/cost-command.ts

@@ -21,9 +21,8 @@ import { homedir } from 'node:os'
 import { delimiter, dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { z } from 'zod'
-
-import type { ToolContextLike } from './delegation.ts'
 import type { NativeTaskStatus } from './native-task-status.ts'
+import type { ToolContextLike } from './tool-context.ts'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)

package/src/pantheon/delegation-enforce.ts

@@ -1,7 +1,7 @@
 /**
  * Read-Only Enforcement (Phase 4) — deny mutating tools inside sessions that
- * were delegated as read-only (advisory `read_only: true` on
- * pantheon_delegate, or the agent ∈ `readOnlyAgents` from routing.yml).
+ * were delegated as read-only (an explicit read-only flag, or the agent ∈
+ * `readOnlyAgents` from routing.yml).
  *
  * OpenCode hook: `tool.execute.before`. The hook shape is
  * `(input, output) => Promise<void>`; THROWING from the hook denies the tool
@@ -22,8 +22,10 @@
  * fail-closed when the runtime matrix is wired: missing agent identity or
  * target metadata is denied rather than inferred.
  *
- * The registry is populated by delegation.ts at delegate time: the CHILD
- * session is registered when the delegate call is read-only.
+ * The registry is populated by the plugin's `chat.params` hook — the only
+ * place the SDK exposes the active agent: when the session's agent is
+ * read-only (apollo, gaia — routing.yml `background_delegation.read_only_agents`),
+ * the session is registered; `session.deleted` unregisters it.
  *
  * @module delegation-enforce
  */
@@ -147,7 +149,6 @@ export function isDelegationAllowed(
 function targetFromTool(tool: string, args: unknown): string | undefined {
   if (args === null || typeof args !== 'object') return undefined
   const record = args as Record<string, unknown>
-  if (tool === 'pantheon_delegate') return normalizeDelegationAgent(record.agent)
   if (tool === 'task') {
     return normalizeDelegationAgent(record.subagent_type ?? record.subagentType)
   }
@@ -236,9 +237,10 @@ export function zeusReadGuard(tool: string, args: unknown, agent: string | undef
 // ─── Registry ──────────────────────────────────────────────────────────
 
 /**
- * Read-only session registry. `createDelegationTools` registers child
- * sessions here; the plugin's `tool.execute.before` guard consults it.
- * Process-wide singleton for plugin wiring + factory for test isolation.
+ * Read-only session registry. The plugin's `chat.params` hook registers
+ * sessions whose active agent is read-only (see {@link syncReadOnlySession});
+ * the `tool.execute.before` guard consults it. Process-wide singleton for
+ * plugin wiring + factory for test isolation.
  */
 export class ReadOnlySessionRegistry {
   private readonly sessions = new Map<string, ReadOnlyEntry>()
@@ -279,6 +281,50 @@ export class ReadOnlySessionRegistry {
 /** Process-wide registry wired into the plugin. */
 export const readOnlyRegistry = new ReadOnlySessionRegistry()
 
+// ─── Read-Only Agent Policy ────────────────────────────────────────────
+
+/**
+ * Agents that must stay investigation-only. Mirrors
+ * `background_delegation.read_only_agents` in routing.yml — the parity is
+ * enforced by tests/pantheon/delegation-enforce.test.ts so the two cannot
+ * drift silently.
+ */
+export const READ_ONLY_AGENTS: ReadonlySet<string> = new Set(['apollo', 'gaia'])
+
+/**
+ * Whether an agent identity belongs to the read-only set. Identity is never
+ * inferred from prompts or tool names — only the normalized agent name counts.
+ */
+export function isReadOnlyAgent(
+  agent: unknown,
+  readOnlyAgents: ReadonlySet<string> = READ_ONLY_AGENTS,
+): boolean {
+  const normalized = normalizeDelegationAgent(agent)
+  return normalized !== undefined && readOnlyAgents.has(normalized)
+}
+
+/**
+ * Sync the read-only registry with a session's active agent. Called from the
+ * plugin's `chat.params` hook: a read-only agent registers the session;
+ * anything else (unknown/absent/non-read-only) unregisters it, which also
+ * covers an in-session agent switch. Returns whether the session is now
+ * registered.
+ */
+export function syncReadOnlySession(
+  registry: ReadOnlySessionRegistry,
+  sessionID: string,
+  agent: unknown,
+  readOnlyAgents: ReadonlySet<string> = READ_ONLY_AGENTS,
+): boolean {
+  const normalized = normalizeDelegationAgent(agent)
+  if (normalized === undefined || !readOnlyAgents.has(normalized)) {
+    registry.unregister(sessionID)
+    return false
+  }
+  registry.register(sessionID, { agent: normalized })
+  return true
+}
+
 // ─── Guard ─────────────────────────────────────────────────────────────
 
 /**
@@ -291,19 +337,18 @@ export function createEnforcementGuard(input: {
   options?: EnforcementGuardOptions
 }): ToolExecuteBeforeHandler {
   const blockedTools = input.options?.blockedTools ?? DEFAULT_BLOCKED_TOOLS
-  const prefix = input.options?.messagePrefix ?? 'pantheon_delegate guard'
+  const prefix = input.options?.messagePrefix ?? 'pantheon delegation guard'
 
   return async (hook: ToolExecuteBeforeInput, output?: ToolExecuteBeforeOutput): Promise<void> => {
-    const isDelegationTool = hook.tool === 'task' || hook.tool === 'pantheon_delegate'
+    const isDelegationTool = hook.tool === 'task'
     if (isDelegationTool && input.options?.isChildSession?.(hook.sessionID) === true) {
       throw new Error(
         `${prefix}: session ${hook.sessionID} is a child session — delegation tools are denied ` +
           'to prevent nested delegation',
       )
     }
-    // pantheon_delegate has the authoritative ToolContext.agent at execution
-    // time, so its matrix check lives in delegation.ts. The hook only has the
-    // session-scoped agent learned from chat.params for native task().
+    // The hook only has the session-scoped agent learned from chat.params,
+    // so the runtime matrix check for native task() lives here.
     if (
       hook.tool === 'task' &&
       input.options?.isRootSession !== undefined &&
@@ -336,7 +381,7 @@ export function createEnforcementGuard(input: {
         `This session was delegated for investigation only (read-only agent); it cannot ` +
         `modify files, run commands, or spawn subagents. ` +
         `If a write result is needed, dispatch a write-capable agent ` +
-        `(e.g. hermes, aphrodite) with pantheon_delegate instead.`,
+        `(e.g. hermes, aphrodite) with native task() instead.`,
     )
   }
 }

package/src/pantheon/goal-loop.ts

@@ -17,11 +17,11 @@
 import { z } from 'zod'
 
 import type { BackgroundJobBoard } from './background-job-board.ts'
-import type { ToolContextLike } from './delegation.ts'
 import { GoalStore } from './goal-store.ts'
 import { createPantheonLogger } from './logger.ts'
 import { safeSessionPath } from './session-guard.ts'
 import type { TodoEnforcerMessage } from './todo-enforcer.ts'
+import type { ToolContextLike } from './tool-context.ts'
 
 // Silence-by-default TUI policy (pantheon-hooks L42-58): warn → hooks.log,
 // console echo opt-in via PANTHEON_HOOKS_LOG=1. `deps.logger` stays for tests.

package/src/pantheon/goal-store.ts

@@ -15,7 +15,7 @@
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
-import { assertSafeParentSessionID } from './delegation-finalize.ts'
+import { assertSafeParentSessionID } from './session-id.ts'
 
 export type GoalStatus = 'pending' | 'in_progress' | 'done'
 

package/src/pantheon/idle-continuation.ts

@@ -5,9 +5,8 @@
  * Priority: an ACTIVE GOAL owns the idle — `GoalLoop.onIdle` continues the
  * goal. Without an active goal, the TODO enforcer gets the idle (it
  * self-guards on its own enabled flag + guards). Board-child sessions never
- * reach the dispatcher — the plugin's event hook routes those to the
- * delegation finalize path first (`handleDelegationEvent` returns true) and
- * only calls the dispatcher on the `!delegated` branch.
+ * reach the dispatcher — the plugin's event hook owns board transitions and
+ * only calls the dispatcher for non-board sessions.
  *
  * Independently testable — the loop and enforcer are structural interfaces;
  * the real GoalLoop/TodoEnforcer satisfy them.
@@ -34,9 +33,8 @@ export interface IdleDispatcher {
 }
 
 /**
- * Build the idle router. The plugin event hook calls this only on the
- * `!delegated` branch of `handleDelegationEvent`, so board children never
- * arrive here.
+ * Build the idle router. The plugin event hook calls this only for non-board
+ * sessions, so board children never arrive here.
  */
 export function createIdleDispatcher(deps: {
   goalLoop: GoalLoopLike

package/src/pantheon/model-command.ts

@@ -23,8 +23,6 @@ import { lstat, mkdir, open, rename, unlink } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { basename, dirname, join, resolve } from 'node:path'
 import { z } from 'zod'
-
-import type { ToolContextLike } from './delegation.ts'
 import {
   capabilityEntry,
   hasVision,
@@ -32,6 +30,7 @@ import {
   normalizeCapability,
   resolveActivePreset,
 } from './presets.mjs'
+import type { ToolContextLike } from './tool-context.ts'
 
 export type ModelScope = 'project' | 'global'
 export type ModelAction = 'status' | 'show' | 'set' | 'reset'

package/src/pantheon/native-task-status.ts

@@ -2,8 +2,8 @@
  * Native Task Status — classifies BackgroundJobRecord results from native
  * task() delegation into actionable status codes.
  *
- * Pure module — zero external dependencies. Consumed by native-probe.ts
- * and the delegation manager to decide retry/skip/escalate strategy.
+ * Pure module — zero external dependencies. Consumed by the tool-ceiling and
+ * cost layers to decide retry/skip/escalate strategy.
  *
  * @module native-task-status
  */