pantheon-opencode 1.4.1 → 1.4.3

package/scripts/install/opencode.mjs

@@ -43,6 +43,7 @@ import {
   syncDir,
   writeIfChanged,
 } from './shared.mjs'
+
 import { setupVenv, venvPythonPath } from './venv.mjs'
 
 const COMPONENT_NAMES = [
@@ -59,6 +60,16 @@ function deepClone(value) {
   return JSON.parse(JSON.stringify(value))
 }
 
+function readJsonConfig(filePath) {
+  if (!existsSync(filePath)) return {}
+
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'))
+  } catch (cause) {
+    throw new Error(`Invalid JSON in ${filePath}`, { cause })
+  }
+}
+
 function mergeMissing(target, source) {
   if (!source || typeof source !== 'object' || Array.isArray(source)) return target
   if (!target || typeof target !== 'object' || Array.isArray(target)) return deepClone(source)
@@ -274,6 +285,11 @@ export async function installOpenCode(
     }
   }
 
+  const pantheonConfigPath = join(ROOT, 'opencode.json')
+  const targetConfigPath = join(target, 'opencode.json')
+  const config = readJsonConfig(targetConfigPath)
+  const pantheonConfig = readJsonConfig(pantheonConfigPath)
+
   // Determine layout based on install scope.
   // Global config dir (~/.opencode or ~/.config/opencode) uses a flat layout:
   //   agents/   skills/   commands/   plugins/
@@ -533,27 +549,6 @@ export async function installOpenCode(
   //    Reads TARGET's existing config first, then merges Pantheon settings
   //    on top. Preserves user's MCP, provider, plugin, compaction, theme.
   // -----------------------------------------------------------------------
-  const pantheonConfigPath = join(ROOT, 'opencode.json')
-  const targetConfigPath = join(target, 'opencode.json')
-
-  let config = {}
-  if (existsSync(targetConfigPath)) {
-    try {
-      config = JSON.parse(readFileSync(targetConfigPath, 'utf8'))
-    } catch {
-      config = {}
-    }
-  }
-
-  let pantheonConfig = {}
-  if (existsSync(pantheonConfigPath)) {
-    try {
-      pantheonConfig = JSON.parse(readFileSync(pantheonConfigPath, 'utf8'))
-    } catch {
-      pantheonConfig = {}
-    }
-  }
-
   // --------------------------------------------------------------------
   // A. Parse canonical agent config from agents/*.agent.md frontmatter
   //    and merge into opencode.json config.
@@ -622,61 +617,64 @@ export async function installOpenCode(
     'disable_model_invocation',
   ]
 
-  if (!config.agent) config.agent = {}
-
-  for (const [agentName, agentCfg] of Object.entries(canonicalAgentConfig)) {
-    if (!agentCfg || typeof agentCfg !== 'object') continue
+  if (config.agent === undefined) config.agent = {}
+
+  if (config.agent && typeof config.agent === 'object' && !Array.isArray(config.agent)) {
+    for (const [agentName, agentCfg] of Object.entries(canonicalAgentConfig)) {
+      if (!agentCfg || typeof agentCfg !== 'object') continue
+
+      if (Object.hasOwn(config.agent, agentName)) {
+        // ── Agent exists in target config ──
+        // Update framework-managed fields from canonical source
+        // Preserve user-customized fields (model, provider, mcp, etc.)
+        const existing = config.agent[agentName]
+        if (!existing || typeof existing !== 'object' || Array.isArray(existing)) continue
+        if (agentSources[agentName]) existing.source = agentSources[agentName]
+        for (const field of MANAGED_FIELDS) {
+          if (field in agentCfg) {
+            existing[field] = JSON.parse(JSON.stringify(agentCfg[field]))
+          }
+        }
+        // Remove stale fields that are no longer in canonical config
+        delete existing.model
+        delete existing.small_model
+      } else {
+        // ── New agent ──
+        const newAgent = {}
+        if (agentSources[agentName]) newAgent.source = agentSources[agentName]
+        if (agentCfg.description) newAgent.description = agentCfg.description
+
+        // Copy all framework-managed fields from canonical config
+        for (const field of MANAGED_FIELDS) {
+          if (field in agentCfg) {
+            newAgent[field] = JSON.parse(JSON.stringify(agentCfg[field]))
+          }
+        }
 
-    if (config.agent[agentName]) {
-      // ── Agent exists in target config ──
-      // Update framework-managed fields from canonical source
-      // Preserve user-customized fields (model, provider, mcp, etc.)
-      const existing = config.agent[agentName]
-      if (agentSources[agentName]) existing.source = agentSources[agentName]
-      for (const field of MANAGED_FIELDS) {
-        if (field in agentCfg) {
-          existing[field] = JSON.parse(JSON.stringify(agentCfg[field]))
+        // Ensure bash permission is set from canonical (default to deny if missing)
+        if (newAgent.permission === undefined) {
+          newAgent.permission = {}
         }
-      }
-      // Remove stale fields that are no longer in canonical config
-      delete existing.model
-      delete existing.small_model
-    } else {
-      // ── New agent ──
-      const newAgent = {}
-      if (agentSources[agentName]) newAgent.source = agentSources[agentName]
-      if (agentCfg.description) newAgent.description = agentCfg.description
-
-      // Copy all framework-managed fields from canonical config
-      for (const field of MANAGED_FIELDS) {
-        if (field in agentCfg) {
-          newAgent[field] = JSON.parse(JSON.stringify(agentCfg[field]))
+        if (newAgent.permission.bash === undefined && agentCfg.permission?.bash) {
+          newAgent.permission.bash = JSON.parse(JSON.stringify(agentCfg.permission.bash))
         }
-      }
 
-      // Ensure bash permission is set from canonical (default to deny if missing)
-      if (!newAgent.permission) {
-        newAgent.permission = {}
-      }
-      if (!newAgent.permission.bash && agentCfg.permission?.bash) {
-        newAgent.permission.bash = JSON.parse(JSON.stringify(agentCfg.permission.bash))
+        config.agent[agentName] = newAgent
       }
-
-      config.agent[agentName] = newAgent
     }
-  }
 
-  // Remove stale agents (exist in target config but not in canonical source)
-  // Only removes agents whose source is managed (starts with our prefix)
-  // so user-defined agents with different source paths are preserved.
-  const canonicalNames = new Set(Object.keys(canonicalAgentConfig))
-  for (const [agentName, agentCfg] of Object.entries(config.agent)) {
-    const source = agentCfg?.source || ''
-    if (source.startsWith(agentPrefix) && !canonicalNames.has(agentName)) {
-      delete config.agent[agentName]
+    // Remove stale agents (exist in target config but not in canonical source)
+    // Only removes agents whose source is managed (starts with our prefix)
+    // so user-defined agents with different source paths are preserved.
+    const canonicalNames = new Set(Object.keys(canonicalAgentConfig))
+    for (const [agentName, agentCfg] of Object.entries(config.agent)) {
+      const source = agentCfg?.source || ''
+      if (source.startsWith(agentPrefix) && !canonicalNames.has(agentName)) {
+        delete config.agent[agentName]
+      }
     }
+    if (Object.keys(config.agent).length === 0) delete config.agent
   }
-  if (Object.keys(config.agent).length === 0) delete config.agent
 
   // --------------------------------------------------------------------
   // B. Commands from .md frontmatter (commands.json removed)
@@ -687,19 +685,16 @@ export async function installOpenCode(
   // --------------------------------------------------------------------
   // B.5 Ensure critical top-level OpenCode config sections
   // --------------------------------------------------------------------
-  if (!config.default_agent && pantheonConfig.default_agent) {
+  if (config.default_agent === undefined && pantheonConfig.default_agent !== undefined) {
     config.default_agent = pantheonConfig.default_agent
   }
-  // Merge top-level model/small_model from the repo config when the target
-  // config has no top-level `model` (fresh sandbox installs have none). The
-  // repo's opencode.json carries the default pair
-  // (opencode-go/deepseek-v4-flash); a user-set model is never overwritten.
-  if (!config.model && pantheonConfig.model) {
-    config.model = pantheonConfig.model
-    if (!config.small_model && pantheonConfig.small_model) {
-      config.small_model = pantheonConfig.small_model
-    }
-  }
+  // Apply only explicit top-level model overrides. Existing values remain
+  // untouched and an install without either flag leaves both fields absent.
+  const modelFlag = typeof opts.model === 'string' && opts.model !== '' ? opts.model : undefined
+  const smallModelFlag =
+    typeof opts.smallModel === 'string' && opts.smallModel !== '' ? opts.smallModel : undefined
+  if (modelFlag !== undefined) config.model = modelFlag
+  if (smallModelFlag !== undefined) config.small_model = smallModelFlag
   // Merge subagent_depth HERE (the config merge always runs, including on a
   // fresh install) instead of a file-existence-gated block, so run #1 already
   // produces the final config — run #2 must be a byte-identical no-op (#19).
@@ -710,16 +705,24 @@ export async function installOpenCode(
   // experimental (preserving the user's choice) and default fresh installs to
   // experimental.subagent_depth = 2. V1 reads experimental.subagent_depth
   // too, so the V1-shape config stays valid under both versions.
-  if (config.experimental === undefined || typeof config.experimental !== 'object') {
+  if (config.experimental === undefined) {
     config.experimental = {}
   }
-  if (config.subagent_depth !== undefined) {
-    if (config.experimental.subagent_depth === undefined) {
-      config.experimental.subagent_depth = config.subagent_depth
+  if (
+    typeof config.experimental === 'object' &&
+    config.experimental !== null &&
+    !Array.isArray(config.experimental)
+  ) {
+    if (config.subagent_depth !== undefined) {
+      if (config.experimental.subagent_depth === undefined) {
+        config.experimental.subagent_depth = config.subagent_depth
+      }
+      delete config.subagent_depth
+    } else if (config.experimental.subagent_depth === undefined) {
+      config.experimental.subagent_depth = 2
     }
+  } else if (config.subagent_depth !== undefined) {
     delete config.subagent_depth
-  } else if (config.experimental.subagent_depth === undefined) {
-    config.experimental.subagent_depth = 2
   }
 
   // --------------------------------------------------------------------
@@ -735,74 +738,82 @@ export async function installOpenCode(
   // The source opencode.json keeps its dev path for local development; the
   // transform happens at install/sync time only.
 
-  if (!Array.isArray(config.plugin)) {
+  if (config.plugin === undefined) {
     config.plugin = []
   }
-  if (Array.isArray(pantheonConfig.plugin)) {
-    for (const plugin of pantheonConfig.plugin) {
-      const resolved = resolveInstalledPlugin(plugin)
+  if (Array.isArray(config.plugin)) {
+    if (Array.isArray(pantheonConfig.plugin)) {
+      for (const plugin of pantheonConfig.plugin) {
+        const resolved = resolveInstalledPlugin(plugin)
+        const file = basename(resolved)
+        // Replace any pre-existing entry for the same plugin file (e.g. a stale
+        // dev-machine path from an earlier install) so upgrades stay hermetic.
+        config.plugin = config.plugin.filter((p) => basename(p) !== file)
+        config.plugin.push(resolved)
+      }
+    }
+
+    // The two Pantheon plugins MUST always be registered, on fresh installs AND
+    // upgrades. The packaged opencode.json carries no `plugin` key (dev-machine
+    // paths removed in 3e552cc), so config.plugin would otherwise only contain
+    // whatever the user had — a fresh install would register NOTHING and lose
+    // delegation tools, GoalLoop, cost command, hashline and vision. Register
+    // both unconditionally, replacing any stale entry for the same file
+    // (basename-dedup) so installs and upgrades are idempotent and hermetic
+    // while preserving any user plugins.
+    const ensurePantheonPlugin = (ref) => {
+      const resolved = resolveInstalledPlugin(ref)
       const file = basename(resolved)
-      // Replace any pre-existing entry for the same plugin file (e.g. a stale
-      // dev-machine path from an earlier install) so upgrades stay hermetic.
       config.plugin = config.plugin.filter((p) => basename(p) !== file)
       config.plugin.push(resolved)
     }
+    // Root-level delegation plugin (PR #45): tools, GoalLoop, cost, hashline.
+    ensurePantheonPlugin('src/plugin.ts')
+    // Runtime hooks plugin: chat hooks, hook-runner, TUI wiring.
+    ensurePantheonPlugin('src/plugins/pantheon-hooks.ts')
   }
 
-  // The two Pantheon plugins MUST always be registered, on fresh installs AND
-  // upgrades. The packaged opencode.json carries no `plugin` key (dev-machine
-  // paths removed in 3e552cc), so config.plugin would otherwise only contain
-  // whatever the user had — a fresh install would register NOTHING and lose
-  // delegation tools, GoalLoop, cost command, hashline and vision. Register
-  // both unconditionally, replacing any stale entry for the same file
-  // (basename-dedup) so installs and upgrades are idempotent and hermetic
-  // while preserving any user plugins.
-  const ensurePantheonPlugin = (ref) => {
-    const resolved = resolveInstalledPlugin(ref)
-    const file = basename(resolved)
-    config.plugin = config.plugin.filter((p) => basename(p) !== file)
-    config.plugin.push(resolved)
-  }
-  // Root-level delegation plugin (PR #45): tools, GoalLoop, cost, hashline.
-  ensurePantheonPlugin('src/plugin.ts')
-  // Runtime hooks plugin: chat hooks, hook-runner, TUI wiring.
-  ensurePantheonPlugin('src/plugins/pantheon-hooks.ts')
-
-  if (!config.provider && pantheonConfig.provider) {
+  if (config.provider === undefined && pantheonConfig.provider !== undefined) {
     config.provider = deepClone(pantheonConfig.provider)
-  } else if (config.provider && pantheonConfig.provider) {
+  } else if (config.provider !== undefined && pantheonConfig.provider !== undefined) {
     mergeMissing(config.provider, pantheonConfig.provider)
   }
 
-  if (!config.compaction && pantheonConfig.compaction) {
+  if (config.compaction === undefined && pantheonConfig.compaction !== undefined) {
     config.compaction = deepClone(pantheonConfig.compaction)
-  } else if (config.compaction && pantheonConfig.compaction) {
+  } else if (config.compaction !== undefined && pantheonConfig.compaction !== undefined) {
     mergeMissing(config.compaction, pantheonConfig.compaction)
   }
 
   // --------------------------------------------------------------------
   // C. Merge permissions
   // --------------------------------------------------------------------
-  if (!config.permission) config.permission = {}
-  if (pantheonConfig.permission) {
+  if (config.permission === undefined) config.permission = {}
+  if (pantheonConfig.permission !== undefined) {
     mergeMissing(config.permission, pantheonConfig.permission)
   }
-  if (componentSet.has('skills')) {
-    config.permission.skill = { '*': 'allow' }
-  }
-  if (!config.permission.bash) {
-    config.permission.bash = {
-      'git *': 'allow',
-      'npm *': 'allow',
-      'npx *': 'allow',
-      'pytest *': 'allow',
-      'ruff *': 'allow',
-      'black *': 'allow',
-      'pip *': 'allow',
-      'docker *': 'allow',
-      'curl *': 'allow',
-      'gh *': 'allow',
-      'make *': 'allow',
+  if (
+    typeof config.permission === 'object' &&
+    config.permission !== null &&
+    !Array.isArray(config.permission)
+  ) {
+    if (componentSet.has('skills')) {
+      config.permission.skill = { '*': 'allow' }
+    }
+    if (config.permission.bash === undefined) {
+      config.permission.bash = {
+        'git *': 'allow',
+        'npm *': 'allow',
+        'npx *': 'allow',
+        'pytest *': 'allow',
+        'ruff *': 'allow',
+        'black *': 'allow',
+        'pip *': 'allow',
+        'docker *': 'allow',
+        'curl *': 'allow',
+        'gh *': 'allow',
+        'make *': 'allow',
+      }
     }
   }
 
@@ -816,9 +827,9 @@ export async function installOpenCode(
   // glob is no longer needed — keeping it would duplicate content under V1
   // and is ignored under V2 anyway. Only ensure AGENTS.md is present.
   const pantheonInstructions = ['AGENTS.md']
-  if (!config.instructions) {
+  if (config.instructions === undefined) {
     config.instructions = [...pantheonInstructions]
-  } else {
+  } else if (Array.isArray(config.instructions)) {
     // Strip stale per-file instruction globs from PREVIOUS installs
     // (e.g. `instructions/*.instructions.md` / `src/instructions/*.md`).
     // The merge is additive-only otherwise, so without this filter existing
@@ -838,7 +849,7 @@ export async function installOpenCode(
   // --------------------------------------------------------------------
   // E. Ensure $schema
   // --------------------------------------------------------------------
-  if (!config.$schema) {
+  if (config.$schema === undefined) {
     config.$schema = 'https://opencode.ai/config.json'
   }
 
@@ -1009,12 +1020,14 @@ export async function installOpenCode(
   }
 
   // -----------------------------------------------------------------------
-  // 5. Model preset selection (--components agents). Interactive picker runs
+  // 5. Model preset selection (--components agents). Interactive wizard runs
   //    unless autoYes (use defaults) or an explicit --preset was given.
+  //    Q1 default "herdar do chat" (inherit) writes no active-preset.json —
+  //    delegates inherit the parent chat model (native inheritance).
   // -----------------------------------------------------------------------
   if (interactive && !dryRun && !autoYes && !opts.preset) {
-    const { runModelPicker } = await import('./model-picker.mjs')
-    await runModelPicker({ presetDir: target, logger: console })
+    const { runInitWizard } = await import('./model-picker.mjs')
+    await runInitWizard({ presetDir: target, logger: console })
   }
 
   if (opts.preset && !dryRun) {

package/src/agents/zeus.md

@@ -144,33 +144,23 @@ task_status(task_id="ses_xxx", wait=true)
   -> bloqueia ate completar: { state: "completed", task_result: "..." }
 ```
 
-### Pantheon Delegation Tools (plugin) — 3-tool API
+### Pantheon Delegation — BackgroundJobBoard (plugin)
 
-O plugin Pantheon adiciona 3 tools de delegacao gerenciada pelo BackgroundJobBoard:
+O plugin Pantheon mantém um **BackgroundJobBoard** persistente
+(`.pantheon/board/state.json`) que rastreia trabalho em voo e o carrega para o
+contexto de compactação. O toolset de delegação do plugin
+(`pantheon_delegate`, `pantheon_delegation_read`, `pantheon_delegation_list`)
+foi **removido em 1.4.3** — dispatch e coleta usam a API nativa
+`task(background=true)` / `task_status(wait=true)`.
 
-```
-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)
+### DELEGATION_RULES (native task 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. **NUNCA** polle `task_status` para checar se um job terminou — use `wait=true` para fan-in explicito.
+2. Voce NAO recebe notificacao injetada no chat — politica do usuario: ZERO `task-notification` no transcript. Visibilidade de conclusao: marcador `[unread]` no board, toasts TUI (pantheon-hooks) e carry-forward de compactacao.
+3. Use `task_status({task_id, wait: true})` APENAS para fan-in explicito / recuperacao de resultado sob demanda (bloqueia ate o fim).
+4. `task_status` sem `wait` e para diagnostico, nao para polling.
 
 ### Background (sempre usar)
 - **Apollo, Hermes, Aphrodite, Demeter, Hephaestus, Prometheus**
@@ -324,9 +314,8 @@ out = await guard.maybeRetry(result, async () => { ...task() de novo... })
 Regra: retry 1x APENAS em `empty-mode1`/`empty-mode2`. Resultado com conteudo
 nunca redispara. Apos 1 retry vazio → escalate (mesma regra do TODO Enforcer).
 
-> **Waves DEVEM usar `zeusDelegateWithRetry`** (`src/pantheon/zeus-delegate-with-retry.ts`) — encapsula `delegate → waitForTerminal → classify → retry 1x → escalate` com cap duro 1; se ainda vazio throw `ZeusEscalationError` (escale: tente outro agente, simplifique, manual).
-> Uso alto-nível: `import { zeusDelegateWithRetry } from './pantheon/zeus-delegate-with-retry.ts'` → `await zeusDelegateWithRetry({ board, client, sessionID, agent, prompt })`.
-> Uso baixo-nível: `createZeusRetryHelper().executeWithRetry(first, () => secondRead())` — classifica empty e decide retry/escalate (mesmo cap 1).
+> **Waves DEVEM usar `dispatch-guard`** (`src/pantheon/dispatch-guard.ts`) — encapsula `task → classify → retry 1x → escalate` com cap duro 1; se ainda vazio throw `ZeusEscalationError` (escale: tente outro agente, simplifique, manual).
+> Uso alto-nível: `import { createDispatchGuard } from './pantheon/dispatch-guard.ts'` → `await guard.maybeRetry(result, () => task(...))`.
 
 ### /cost — pantheon_cost tool (WIRED no plugin)
 `pantheon_cost({ days?: number })` le o `opencode.db` READ-ONLY (node:sqlite;

package/src/pantheon/cost-command.ts

@@ -1,6 +1,6 @@
 /**
  * Cost Command (Wave 4, PR #46) — `pantheon_cost` structural tool: cost +
- * token visibility for delegation traffic, straight from opencode.db.
+ * token visibility by agent, straight from opencode.db.
  *
  * Reads the opencode session database READ-ONLY (sum cost + tokens by
  * agent over the last N days → markdown table). Zero new dependencies:
@@ -13,8 +13,8 @@
  * dbPath resolution: explicit option > env PANTHEON_COST_DB > the version-aware
  * default selected by PANTHEON_OPENCODE_VERSION (v1 or v2). An unset version
  * deliberately preserves V1 behavior. The tool is wired in
- * plugin.ts alongside the delegation toolset (usable by zeus and any agent
- * with tool access — no routing change needed).
+ * plugin.ts (usable by zeus and any agent with tool access — no routing change
+ * needed).
  *
  * @module cost-command
  */
@@ -25,7 +25,7 @@ import { join } from 'node:path'
 import { promisify } from 'node:util'
 import { z } from 'zod'
 
-import type { ToolContextLike } from './delegation.ts'
+import type { ToolContextLike } from './tool-context.ts'
 
 const execFileAsync = promisify(execFile)
 
@@ -44,7 +44,7 @@ export interface CostCommandOptions {
 
 export type OpenCodeVersion = 'v1' | 'v2'
 
-/** One cost tool: description + zod args shape + execute (delegation.ts shape). */
+/** One cost tool: description + zod args shape + execute. */
 export interface CostTool<Args extends z.ZodRawShape = typeof costArgs> {
   description: string
   args: Args
@@ -62,7 +62,7 @@ const costArgs = {
     .min(1)
     .max(365)
     .optional()
-    .describe('Number of days of delegation history to include (default 7).'),
+    .describe('Number of days of cost history to include (default 7).'),
 } satisfies z.ZodRawShape
 
 /** Return the safe, isolated state DB name for an OpenCode version. */
@@ -239,7 +239,7 @@ export function createCostCommand(options?: CostCommandOptions): CostCommand {
   return {
     pantheon_cost: {
       description:
-        'Report delegation cost + token usage by agent over the last N days, read from opencode.db (read-only, no writes).',
+        'Report cost + token usage by agent over the last N days, read from opencode.db (read-only, no writes).',
       args: costArgs,
       execute,
     },

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 (advisory `read_only: true` on the native
+ * `task` delegate, 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
@@ -18,11 +18,11 @@
  *   - `task` is blocked too, which hard-enforces depth-2: a read-only agent
  *     cannot spawn its own subagents.
  *
- * Unknown sessions are allowed for ordinary tools. Delegation tools are
- * fail-closed when the runtime matrix is wired: missing agent identity or
+ * Unknown sessions are allowed for ordinary tools. The runtime matrix is
+ * fail-closed when wired: missing agent identity or
  * target metadata is denied rather than inferred.
  *
- * The registry is populated by delegation.ts at delegate time: the CHILD
+ * The registry is populated at delegate time: the CHILD
  * session is registered when the delegate call is read-only.
  *
  * @module delegation-enforce
@@ -147,7 +147,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,7 +235,7 @@ export function zeusReadGuard(tool: string, args: unknown, agent: string | undef
 // ─── Registry ──────────────────────────────────────────────────────────
 
 /**
- * Read-only session registry. `createDelegationTools` registers child
+ * Read-only session registry. The plugin's delegate wiring registers child
  * sessions here; the plugin's `tool.execute.before` guard consults it.
  * Process-wide singleton for plugin wiring + factory for test isolation.
  */
@@ -291,19 +290,19 @@ 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 ?? '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 native task() delegate has the authoritative ToolContext.agent at
+    // execution time, so its matrix check lives in dispatch-guard.ts. The hook
+    // only has the session-scoped agent learned from chat.params.
     if (
       hook.tool === 'task' &&
       input.options?.isRootSession !== undefined &&
@@ -336,7 +335,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 the native task() tool 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.
@@ -103,7 +103,7 @@ const goalUpdateArgs = {
 
 const goalGetArgs = {} satisfies z.ZodRawShape
 
-/** One structural goal tool: description + zod args shape + execute (delegation.ts shape). */
+/** One structural goal tool: description + zod args shape + execute. */
 export type GoalTool<Args extends z.ZodRawShape> = {
   description: string
   args: Args

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 './tool-context.ts'
 
 export type GoalStatus = 'pending' | 'in_progress' | 'done'
 

package/src/pantheon/hashline/tool.ts

@@ -2,8 +2,8 @@
  * Hashline edit tool (Wave 2, PR #46) — structural `hashline_edit` tool that
  * anchors edits to stable sha256 content tags instead of fragile line numbers.
  *
- * Tool shape matches the delegation tools (`{description, args, execute}`,
- * zod-validated — same import pattern as delegation.ts).
+ * Tool shape follows the plugin tool convention (`{description, args, execute}`,
+ * zod-validated) used across the Pantheon toolset.
  *
  * Safety model (council-approved):
  *   1. ALL refs are validated against the ORIGINAL file snapshot BEFORE any