pantheon-opencode 1.4.1 → 1.4.3

package/README.md

@@ -2,7 +2,7 @@
 <h1 align="center">Pantheon</h1>
 
 <p align="center">
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-v1.4.1--candidate-blue" alt="Version"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-v1.4.2-blue" alt="Version"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
   <a href="docs/agents/README.md"><img src="https://img.shields.io/badge/agents-14-purple" alt="Agents"></a>
   <a href="src/skills/README.md"><img src="https://img.shields.io/badge/skills-21-orange" alt="Skills"></a>
@@ -218,97 +218,28 @@ incompatible schema.
 
 ### Background Delegation
 
-Zeus (and other root sessions) can dispatch agents as **background child sessions**
-via three delegation tools, tracked on a persistent job board
-(`.pantheon/board/state.json`, 24h TTL) with reports written to
-`.pantheon/delegations/<parent>/<alias>.md`:
-
-| Tool | Signature | Behavior |
-|------|-----------|----------|
-| `pantheon_delegate` | `{prompt, agent, description?, read_only?}` | Creates a child session (parentID = caller), registers it on the job board, arms a 15-minute timeout, and fire-and-forgets `promptAsync` on the child. Returns the readable alias (e.g. `apo-1`). Only root sessions may delegate (sub-sessions are rejected by the depth guard). |
-| `pantheon_delegation_read` | `{id}` | Blocks (`waitForTerminal`, up to 15 min) until the delegation reaches a terminal state, returns the report markdown, and marks the job reconciled. Resolves by alias or task ID. |
-| `pantheon_delegation_list` | `{}` | Lists the current session's delegations with `[unread]` on finished, unreconciled jobs. |
-
-**Agent activity visibility.** While `pantheon_delegation_read` blocks on a
-running job, it samples the child session's messages every ~2s and appends the
-collected lines to the report as a trailing `## Agent Activity` section (latest
-tool calls with truncated args, or user/assistant text, capped at ~200 chars per
-line) — so you can see what the agent is doing during the wait. Likewise,
-`pantheon_delegation_list` shows a `last activity:` line for running jobs.
-Fail-open: if the child session messages are unavailable (or empty), the read
-returns the report exactly as before — the activity sampling never breaks the
-delegation read.
+Zeus (and other root sessions) dispatch agents as **background child sessions**
+via OpenCode's native `task(background=true, ...)` API. The plugin layer keeps a
+persistent job board (`BackgroundJobBoard`, `.pantheon/board/state.json`, 24h
+TTL) that tracks in-flight work and carries it forward across context
+compaction, so a compacted session does not lose track of running delegations.
+
+The plugin no longer ships a delegate toolset (`pantheon_delegate`,
+`pantheon_delegation_read`, `pantheon_delegation_list` were removed in 1.4.3).
+Dispatch and result collection use the native `task()` / `task_status()` API.
 
 **Completion visibility — zero chat noise.** Delegation notifications are never
 injected into the chat transcript: neither `chat.message` nor any other chat
 hook or transcript marker is used as a delivery channel. When a job reaches a
-terminal state (completion observed via `session.idle`/`session.error` on the
-child, or the timeout finalize path), the plugin writes a file-only audit log
-line (echo opt-in via `PANTHEON_HOOKS_LOG`). Completion visibility lives in the
-legitimate channels: the board `[unread]` marker
-(`pantheon_delegation_list`), `pantheon_delegation_read`, TUI toasts
-(`PANTHEON_TOASTS` gate), and compaction carry-forward. Reconcile is an
-acknowledgment, not a completion — it never re-fires the terminal transition.
+terminal state, the plugin writes a file-only audit log line (echo opt-in via
+`PANTHEON_HOOKS_LOG`). Completion visibility lives in the legitimate channels:
+the board `[unread]` marker, TUI toasts (`PANTHEON_TOASTS` gate), and compaction
+carry-forward. Reconcile is an acknowledgment, not a completion — it never
+re-fires the terminal transition.
 
 **Timeout:** `background_delegation.timeout_ms` (default `900000` = 15 min). A job
 that has not reached a terminal state is finalized as `error`/`timedOut`.
 
-**Runtime delegation environment variables:**
-
-| Variable | Default | Scope and behavior |
-|---|---:|---|
-| `PANTHEON_ATHENA_APOLLO_BUDGET` | `5` dispatches | In-memory per `createDelegationTools()` factory/process instance and parent session, for the `athena → apollo` read-only exception. |
-| `PANTHEON_HERMES_APOLLO_BUDGET` | `5` dispatches | In-memory per `createDelegationTools()` factory/process instance and parent session, for the `hermes → apollo` read-only exception. |
-| `PANTHEON_DELEGATION_TIMEOUT_MS` | `900000` ms (15 min) | Per delegated child wall-clock timeout. The value is read when the plugin factory is created; unset or invalid values use the default. |
-
-Budgets are reserved before asynchronous child-session creation, so real
-concurrent calls cannot overshoot them. They reset when the factory/process
-restarts. If `ToolContext.agent` is missing, the default runtime matrix rejects
-the delegation (fail-closed); no caller identity or budget is inferred from the
-target, prompt, or session state. An explicitly legacy host using
-`enforceRuntimeMatrix: false` skips the budget because the caller cannot be
-identified and emits a warning. These budgets are separate from
-`background_delegation.max_concurrent_per_agent`: concurrency limits the number
-of currently running children, while an exception budget limits total dispatch
-reservations for that parent session during the factory lifetime.
-
-**Read-only enforcement:** delegating with `read_only: true`, or delegating to an
-agent in `background_delegation.read_only_agents` (`apollo`, `gaia`), registers
-the child session as read-only — the `tool.execute.before` guard denies
-`edit`/`write`/`bash`/`task` inside that session.
-
-**R1 — Per-error-type retry + provider cooldown (LiteLLM pattern):**
-`retry_policy` in `src/routing.yml` maps an error class (`auth`, `rate_limit`,
-`timeout`, `other`) to max retries before escalating — `auth` is never retried
-(0), `rate_limit` gets 3, `timeout` 2, `other` 1. Retries use exponential
-backoff (base 1s, doubling, capped 30s). `cooldown` (`allowed_fails`,
-`cooldown_time_seconds`) skips a provider for the configured window after that
-many consecutive failures; a success resets the counter. Enforcement lives in
-`RetryPolicyEngine` (`src/pantheon/retry-policy.ts`) and the R1 path of
-`zeusDelegateWithRetry` (`src/pantheon/zeus-delegate-with-retry.ts`) — pass
-`retryPolicy`/`cooldown`/`provider` to `createZeusRetryHelper`. In-memory only
-(no Redis).
-
-**R4 — Per-agent step caps:** `agents.<name>.max_steps` in `src/routing.yml`
-gives each agent a step budget (e.g. `apollo: 25`, `themis: 25`, `athena: 15`).
-When an agent reaches `max_steps` it is forced to summarize-and-stop: a
-delegation to an already-capped agent is skipped with a `[STEP CAP REACHED]`
-summary (no child session created), and a dispatch that hits the cap appends a
-stop instruction to the prompt. Enforcement: `StepCapTracker`
-(`src/pantheon/step-cap.ts`) wired into `pantheon_delegate`. The tracker is
-**permanent-per-process** — counters accumulate for the process lifetime and
-are intentionally not reset on success/session end (a per-session reset would
-let an agent exceed its process budget).
-
-**O5 — Permission globs for delegation:** `permission.task` in `src/routing.yml`
-controls which subagents an agent may invoke via glob patterns (last matching
-rule wins). A deny removes the agent from the delegate tool description
-entirely (not just blocks the call) — preventing circular delegation at the
-permission layer. Default `"*": allow` keeps the existing runtime matrix
-(zeus → anyone; athena/hermes → apollo only). Enforcement:
-`src/pantheon/permission-globs.ts` + the `permissionTask` option on
-`createDelegationTools` / `createEnforcementGuard`.
-
 **Compaction carry-forward:** during context compaction, running and unread
 terminal delegations (capped at `background_delegation.max_compaction_items`,
 default 10) are carried into the compacted context so the parent doesn't lose
@@ -337,8 +268,7 @@ logged warn and pass-through.
 
 **Post-compaction state re-assertion (1.3.4):** on `session.compacted`, fresh
 state — running/unread delegations from the board + active goals, capped at 10
-lines — remains available through compaction carry-forward and the board
-(`pantheon_delegation_list` / `pantheon_delegation_read`). A session with
+lines — remains available through compaction carry-forward. A session with
 nothing to assert is a silent skip; no chat transcript injection is performed.
 
 **Preemptive compaction check (1.3.4):** a pure threshold core
@@ -362,8 +292,8 @@ omits the child model.
 **Delegation log hygiene (1.3.4):** `delegations.log` now records the real
 `task_id` (omitted when empty, never `""`) and a **numeric** `duration_ms`
 (null when unset) so downstream aggregation works. Terminal events are
-file-only audit entries; completion is surfaced by TUI toast (when enabled),
-the board, and the list/read tools — never by chat delivery.
+file-only audit entries; completion is surfaced by TUI toast (when enabled)
+and the board — never by chat delivery.
 
 **Env vars & config:**
 
@@ -371,14 +301,13 @@ the board, and the list/read tools — never by chat delivery.
 - `PANTHEON_TOASTS` — TUI toast gate for the delegation lifecycle signals.
   Default `{errors, delegations, council}`; `PANTHEON_TOASTS=off` disables all
   TUI toasts (delegation signals then only surface via the board `[unread]`
-  marker, `pantheon_delegation_read` and the on-disk audit log — never via
-  chat.message injection from the plugin).
+  marker and the on-disk audit log — never via chat.message injection from the
+  plugin).
 - `background_delegation` section in `src/routing.yml` — `timeout_ms`,
-  `poll_ms`, `max_compaction_items`, `prune_ttl_ms`, `read_only_agents`,
-  `session_max`, `retry_count`.
+  `poll_ms`, `max_compaction_items`, `prune_ttl_ms`, `session_max`,
+  `retry_count`.
 
-See `src/agents/zeus.md` for the agent-facing delegation protocol and
-`src/pantheon/delegation.ts` for the tool implementations.
+See `src/agents/zeus.md` for the agent-facing delegation protocol.
 
 ### Real-time Delegations panel (1.3.4)
 
@@ -386,7 +315,7 @@ The TUI sidebar ships a live **Delegations** panel (open by default, above the
 collapsed Sessions list). Its primary source is `api.client.session.children`,
 so it shows **both** kinds of background work in one place:
 
-- **`pantheon_delegate` children** — rendered with their board alias tag
+- **Board-tracked children** — rendered with their board alias tag
   (`[apo-1]`) and enriched from the `.pantheon/delegations/` report.
 - **Native `task()` children** — rendered with a distinct `[task]` tag (info
   color) when no board report exists for the session.
@@ -641,112 +570,211 @@ on demand to perform specialized tasks. Skills are organized into domains:
 ## Model Tiers & Presets
 
 Pantheon agents declare abstract model tiers (`fast` / `default` / `coding` / `premium`) rather than
-hardcoded model names. The actual model resolved for each tier depends on your platform
-subscription (OpenCode Go, Copilot Pro, Claude Pro, etc.).
+hardcoded model names. The actual model resolved for each tier depends on your chosen **preset**
+and is pinned to concrete `provider/model` IDs in [src/routing.yml](src/routing.yml).
 
-| Tier | Purpose | Agents | Typical Models |
+| Tier | Purpose | Agents | Typical Models (2026) |
 |------|---------|--------|----------------|
-| `premium` | Deep reasoning, critical | Zeus, Athena, Themis | DeepSeek V4 Pro, Claude Opus, o3 |
-| `default` | Balanced quality/speed | Hermes, Aphrodite, Demeter, Prometheus, Hephaestus, Gaia | Kimi K2.6, Claude Sonnet, GPT-4o |
-| `coding` | Heavy coding tasks | Hermes, Aphrodite, Demeter, Prometheus, Hephaestus, Talos | DeepSeek V4 Flash, Claude Sonnet |
-| `fast` | Quick, cheap ops | Apollo, Iris, Mnemosyne, Talos, Nyx | DeepSeek V4 Flash, MiniMax M2.7, Gemini Flash |
+| `premium` | Deep reasoning, critical | Zeus, Athena, Themis | gpt-5.6-sol, qwen3.8-max, deepseek-v4-pro |
+| `default` | Balanced quality/speed | Hermes, Aphrodite, Demeter, Prometheus, Hephaestus, Gaia | gpt-5.6-terra, kimi-k3, deepseek-v4-flash |
+| `coding` | Heavy coding tasks | Hermes, Aphrodite, Demeter, Prometheus, Hephaestus, Talos | gpt-5.6-terra, deepseek-v4-flash, mimo-v2.5 |
+| `fast` | Quick, cheap ops | Apollo, Iris, Mnemosyne, Talos, Nyx | gpt-5.6-luna-fast, mimo-v2.5-free, gpt-5.6-luna |
 
 ---
 
 ## Model Routing Presets
 
-The abstract tiers above are pinned to concrete `provider/model` IDs by **6 built-in model presets**. Each preset maps all 14 agents to a specific model plus a reasoning effort per role (planners/reviewers, implementers, scouts). **Zero-mutation default**: without an active preset, agents run on OpenCode's default model — behavior is unchanged.
+The abstract tiers above are pinned to concrete `provider/model` IDs by **4 built-in model presets**.
+Cada preset mapeia os 14 agentes para um modelo específico + `reasoning_effort` por papel (planners/reviewers, implementers, scouts).
+
+> **Default = herdar do chat (sem `active-preset.json`)** — sem preset ativo, os delegates **herdam nativamente** o modelo do chat pai. O instalador **não grava** `active-preset.json` quando você escolhe `0`/`inherit` no wizard (ou não seleciona preset via `--preset`). A resolução do modelo delegado segue: modelo do agente-alvo no preset ativo > modelo atual da sessão pai > herança nativa (sem `model`, sem `small_model`). `small_model` nunca é usado para delegates.
+
+Tabelas abaixo são **geradas a partir de [src/routing.yml](src/routing.yml)** — rode `node scripts/generate-preset-docs.mjs` para regenerar. Nenhum segredo é hardcoded: apenas nomes de env vars (`PANTHEON_OPENCODE_API_KEY`, `OPENAI_API_KEY`) e `baseURL`s.
+
+<!-- Generated from src/routing.yml — run: node scripts/generate-preset-docs.mjs -->
+### Presets — resumo (provider / baseURL / key / pricing / vision)
+
+| Preset | Provider / BaseURL | Key env (nome) | Pricing 2026 | Vision (fallback) | Papéis / Modelos |
+|---|---|---|---|---|---|
+| `go-free` | `opencode` `https://opencode.ai/zen/v1` (env: `PANTHEON_OPENCODE_API_KEY`) | `PANTHEON_OPENCODE_API_KEY` | Gratuito — Zen free, sem custo, quota limitada, só modelos `-free` | `opencode/mimo-v2.5-free` [low] 👁️ vision | zeus: `opencode/big-pickle` [medium]<br>athena: `opencode/nemotron-3-super-free` [high]<br>themis: `opencode/qwen3.6-plus-free` [high]<br>hermes,aphrodite,demeter,prometheus,hephaestus: `opencode/deepseek-v4-flash-free` [medium]<br>apollo,nyx,gaia,iris,mnemosyne,talos: `opencode/mimo-v2.5-free` [low] |
+| `go-fast` | `opencode-go` `https://opencode.ai/zen/go/v1` (env: `PANTHEON_OPENCODE_API_KEY`) | `PANTHEON_OPENCODE_API_KEY` | Baixo custo — Go gateway, baixa latência (kimi-k2.7-code / glm-5.3-flash) | `opencode-go/mimo-v2.5` [low] 👁️ vision | athena: `opencode-go/kimi-k2.7-code` [high]<br>themis: `opencode-go/glm-5.3-flash` [high]<br>zeus: `opencode-go/kimi-k2.7-code` [medium]<br>hermes,prometheus: `opencode-go/deepseek-v4-flash` [medium]<br>aphrodite,hephaestus: `opencode-go/mimo-v2.5` [low]<br>demeter: `opencode-go/gpt-5.6-luna` [low]<br>apollo,nyx,gaia,iris,mnemosyne,talos: `opencode-go/gpt-5.6-luna-fast` [low] |
+| `go-premium` | `opencode-go` `https://opencode.ai/zen/go/v1` (env: `PANTHEON_OPENCODE_API_KEY`) | `PANTHEON_OPENCODE_API_KEY` | Premium — Go gateway, melhor qualidade (gpt-5.6-sol / qwen3.8-max / deepseek-v4-pro) | `opencode-go/gpt-5.6-sol` [high] 👁️ vision | zeus: `opencode-go/gpt-5.6-sol` [medium]<br>athena: `opencode-go/deepseek-v4-pro` [high]<br>themis: `opencode-go/qwen3.8-max` [high]<br>hermes,demeter,hephaestus: `opencode-go/gpt-5.6-terra` [medium]<br>aphrodite,prometheus: `opencode-go/kimi-k3` [medium]<br>apollo,nyx,gaia,iris,mnemosyne,talos: `opencode-go/gpt-5.6-luna` [low] |
+| `openai` | `openai` `https://api.openai.com/v1` (env: `OPENAI_API_KEY`) | `OPENAI_API_KEY` | Pago (OpenAI) — Direto OpenAI, `gpt-5.6` family | `openai/gpt-5.6-sol` [high] 👁️ vision | athena,themis,zeus: `openai/gpt-5.6-sol` [high]<br>hermes,aphrodite,demeter,prometheus,hephaestus: `openai/gpt-5.6-luna` [high]<br>apollo,nyx,gaia,iris,mnemosyne,talos: `openai/gpt-5.6-luna-fast` [low] |
+
+> **Pricing 2026 verificado** via `scripts/install/model-picker.mjs` (`PRESET_PRICE`) e `routing.yml` descrições. `go-free` = $0 (Zen free, quota limitada, só `-free`); `go-*` usam `PANTHEON_OPENCODE_API_KEY` (alias `OPENCODE_GO_API_KEY` aceito) no gateway `https://opencode.ai/zen/go/v1`; `openai` usa `OPENAI_API_KEY` em `https://api.openai.com/v1`. Custos reais dependem de conta/assinatura.
+
+### 14 agentes × 4 presets — modelo + effort + vision
 
-### Presets
+| Agente | `go-free` | `go-fast` | `go-premium` | `openai` |
+|---|---|---|---|---|
+| `zeus` | `opencode/big-pickle` [medium] · | `opencode-go/kimi-k2.7-code` [medium] · | `opencode-go/gpt-5.6-sol` [medium] 👁️ | `openai/gpt-5.6-sol` [high] 👁️ |
+| `athena` | `opencode/nemotron-3-super-free` [high] · | `opencode-go/kimi-k2.7-code` [high] · | `opencode-go/deepseek-v4-pro` [high] · | `openai/gpt-5.6-sol` [high] 👁️ |
+| `themis` | `opencode/qwen3.6-plus-free` [high] · | `opencode-go/glm-5.3-flash` [high] · | `opencode-go/qwen3.8-max` [high] · | `openai/gpt-5.6-sol` [high] 👁️ |
+| `hermes` | `opencode/deepseek-v4-flash-free` [medium] · | `opencode-go/deepseek-v4-flash` [medium] · | `opencode-go/gpt-5.6-terra` [medium] 👁️ | `openai/gpt-5.6-luna` [high] 👁️ |
+| `aphrodite` | `opencode/deepseek-v4-flash-free` [medium] · | `opencode-go/mimo-v2.5` [low] 👁️ | `opencode-go/kimi-k3` [medium] · | `openai/gpt-5.6-luna` [high] 👁️ |
+| `demeter` | `opencode/deepseek-v4-flash-free` [medium] · | `opencode-go/gpt-5.6-luna` [low] 👁️ | `opencode-go/gpt-5.6-terra` [medium] 👁️ | `openai/gpt-5.6-luna` [high] 👁️ |
+| `prometheus` | `opencode/deepseek-v4-flash-free` [medium] · | `opencode-go/deepseek-v4-flash` [medium] · | `opencode-go/kimi-k3` [medium] · | `openai/gpt-5.6-luna` [high] 👁️ |
+| `hephaestus` | `opencode/deepseek-v4-flash-free` [medium] · | `opencode-go/mimo-v2.5` [low] 👁️ | `opencode-go/gpt-5.6-terra` [medium] 👁️ | `openai/gpt-5.6-luna` [high] 👁️ |
+| `apollo` | `opencode/mimo-v2.5-free` [low] 👁️ | `opencode-go/gpt-5.6-luna-fast` [low] 👁️ | `opencode-go/gpt-5.6-luna` [low] 👁️ | `openai/gpt-5.6-luna-fast` [low] 👁️ |
+| `nyx` | `opencode/mimo-v2.5-free` [low] 👁️ | `opencode-go/gpt-5.6-luna-fast` [low] 👁️ | `opencode-go/gpt-5.6-luna` [low] 👁️ | `openai/gpt-5.6-luna-fast` [low] 👁️ |
+| `gaia` | `opencode/mimo-v2.5-free` [low] 👁️ | `opencode-go/gpt-5.6-luna-fast` [low] 👁️ | `opencode-go/gpt-5.6-luna` [low] 👁️ | `openai/gpt-5.6-luna-fast` [low] 👁️ |
+| `iris` | `opencode/mimo-v2.5-free` [low] 👁️ | `opencode-go/gpt-5.6-luna-fast` [low] 👁️ | `opencode-go/gpt-5.6-luna` [low] 👁️ | `openai/gpt-5.6-luna-fast` [low] 👁️ |
+| `mnemosyne` | `opencode/mimo-v2.5-free` [low] 👁️ | `opencode-go/gpt-5.6-luna-fast` [low] 👁️ | `opencode-go/gpt-5.6-luna` [low] 👁️ | `openai/gpt-5.6-luna-fast` [low] 👁️ |
+| `talos` | `opencode/mimo-v2.5-free` [low] 👁️ | `opencode-go/gpt-5.6-luna-fast` [low] 👁️ | `opencode-go/gpt-5.6-luna` [low] 👁️ | `openai/gpt-5.6-luna-fast` [low] 👁️ |
 
-| Preset | Provider | Planners/Reviewers | Implementers | Scouts |
-|--------|----------|--------------------|--------------|--------|
-| `go-deepseek` | opencode (Zen) | `opencode/deepseek-v4-pro` | `opencode/deepseek-v4-flash` | `opencode/deepseek-v4-flash-free` |
-| `go-fast` | opencode-go | `opencode-go/deepseek-v4-flash` — all 14 agents, effort `low` | | |
-| `go-claude` | anthropic | `anthropic/claude-opus-4-8` | `anthropic/claude-sonnet-5` | `anthropic/claude-haiku-4-5` |
-| `go-openai` | openai | `openai/gpt-5.6-sol` | `openai/gpt-5.6-terra` | `openai/gpt-5.6-luna-fast` |
-| `go-premium` | opencode-go | GLM-5.1 (zeus), DeepSeek V4 Pro (athena), Qwen3.7 Max (themis) | MiniMax M2.7 (hermes, hephaestus), Kimi K2.6 (aphrodite), Qwen3.7 Plus (demeter), GLM-5.2 (prometheus) | DeepSeek V4 Flash (scouts) |
-| `go-free` | opencode (Zen free, $0) | Big Pickle (zeus), Nemotron 3 Ultra Free (athena) | DeepSeek V4 Flash Free | North Mini Code Free (scouts) |
+`·` = text-only, `👁️` = vision (image-input) per `CAPABILITY_TABLE` em [src/pantheon/presets.mjs](src/pantheon/presets.mjs) — ex.: `mimo-v2.5`/`mimo-v2.5-free` e `gpt-5.6-*` são multimodais; `deepseek-v4-pro/flash`, `kimi-k2.7-code`, `glm-5.3-flash`, `qwen3.6-plus-free`, `big-pickle`, `nemotron-3-super-free` são text-only.
 
-The exact per-agent mapping (model + reasoning effort + fallbacks) lives in the `presets:` block of [src/routing.yml](src/routing.yml).
+O mapeamento exato por agente (modelo + `reasoning_effort` + `vision` fallback) vive no bloco `presets:` de [src/routing.yml](src/routing.yml) e é validado por `validatePresetDefs` + `capabilityEntry` / `hasVision`.
 
 ### Requirements
 
-- **Env vars** — checked fail-fast (CLI and plugin) when the selected preset uses the provider:
-  - `PANTHEON_OPENCODE_API_KEY` — `opencode` + `opencode-go` providers (`go-deepseek`, `go-fast`, `go-premium`, `go-free`)
-  - `PANTHEON_ANTHROPIC_API_KEY` — `anthropic` provider (`go-claude`)
-  - `PANTHEON_OPENAI_API_KEY` — `openai` provider (`go-openai`)
-- **OpenCode Go subscription** required for `go-fast` / `go-premium`.
-- **OpenCode Zen free tier** for `go-free` — note `nemotron-3-ultra-free` has known intermittent failures ([opencode#38028](https://github.com/opencode/opencode/issues/38028)); fall back to `go-fast` if flaky.
+- **Env vars** — checadas fail-fast (CLI e plugin) quando o preset usa o provider (sem hardcodar valores):
+  - `PANTHEON_OPENCODE_API_KEY` — `opencode` + `opencode-go` (`go-free`, `go-fast`, `go-premium`) — alias `OPENCODE_GO_API_KEY` também aceito (wizard Q2)
+  - `OPENAI_API_KEY` — `openai` provider (`openai` puro)
+- **OpenCode Go subscription** para `go-fast` / `go-premium` (gateway `https://opencode.ai/zen/go/v1`).
+- **OpenCode Zen free tier** para `go-free` (`https://opencode.ai/zen/v1`, só modelos `-free`, quota limitada).
+- **Sem preset (default)**: zero-mutação — nenhum `.pantheon/active-preset.json` gravado, herança nativa do chat pai.
 
-### Commands
+### Wizard — instalação interativa (3 perguntas)
 
-```bash
-# Install + activate a preset
-npx pantheon-opencode init --preset go-fast
+Durante `npx pantheon-opencode init` (TTY, sem `--preset`/`--headless`/`-y`):
 
-# Switch preset (global config; --project for project-local; --dry-run to preview)
-pantheon-opencode set-tier go-deepseek
-pantheon-opencode set-tier go-fast --project
-pantheon-opencode set-tier go-fast --dry-run
+1. **Perfil (Q1)** — `0` = herdar do chat (**default**, não grava `active-preset.json`) ou `go-free`/`go-fast`/`go-premium`/`openai` — tabela exibida: perfil | `provider`/`baseURL`/key env | preço 2026 | modelos por papel (planners high, implementers medium/low, scouts low). `askQuestions` quando disponível, fallback `readline` TTY.
+2. **API Key (Q2)** — coleta **mascarada** (exibe `abcd****12`), valida `PANTHEON_OPENCODE_API_KEY` (aceita alias `OPENCODE_GO_API_KEY`) para `go-*` e `OPENAI_API_KEY` para `openai`, **não escreve `.env`** — só seta `env` da sessão e loga `maskKey`. Se já configurada no ambiente, apenas loga mascarada e segue.
+3. **Escopo (Q3)** — `project` (`./.pantheon/active-preset.json`, seguro, default) ou `global` (`~/.config/opencode/.pantheon/active-preset.json`). Gravação **atômica** (`tmp`+`rename`) com backup `.bak` + health-check (lê JSON e valida `preset`).
 
-# Clear preset — back to the zero-mutation default
-pantheon-opencode set-tier none
+Headless / CI: use `npx pantheon-opencode init --headless` ou `--preset <name>` (pula wizard). Veja [docs/INSTALLATION.md](docs/INSTALLATION.md) para `headless` + troubleshooting de chaves.
 
-# No name → lists available presets (none, go-deepseek, go-fast, go-claude, go-openai, go-premium, go-free)
-pantheon-opencode set-tier
+### Comandos
+
+```bash
+# Instalação interativa (wizard 3 perguntas — Q1 default = herdar do chat)
+npx pantheon-opencode init
+npx pantheon-opencode init --project      # escopo project-local
+npx pantheon-opencode init --preset go-fast  # pula wizard, ativa direto
+
+# Alternar preset depois (global por padrão; --project para projeto; --dry-run para preview)
+npx pantheon-opencode set-tier go-free
+npx pantheon-opencode set-tier go-premium --project
+npx pantheon-opencode set-tier openai --dry-run
+
+# Limpar preset — volta ao default (herança nativa)
+npx pantheon-opencode set-tier none
+
+# Sem nome → lista presets (none, go-free, go-fast, go-premium, openai)
+npx pantheon-opencode set-tier
+
+# Per-agent customization (novo — sem top-level model/small_model)
+# Lista 14 agentes com modelo/effort/origem (preset|override|env|none), sem segredos
+/pantheon-model status         # alias: show
+/pantheon-model                # sem args → wizard interativo (agente → modelo → effort → scope via askQuestions)
+/pantheon-model set --agent hermes --model opencode-go/gpt-5.6-terra --effort medium --scope project
+/pantheon-model set --agent apollo --model opencode/mimo-v2.5-free --effort low
+/pantheon-model reset --agent hermes --scope project
 ```
 
-**Env override (CI/headless)** — wins over the file:
+**Env override (CI/headless)** — vence o arquivo:
 
 ```bash
-export PANTHEON_MODEL_PRESET=go-deepseek
+export PANTHEON_MODEL_PRESET=go-fast      # ou go-free / go-premium / openai / none
+export PANTHEON_OPENCODE_API_KEY=...      # para go-* (ou OPENCODE_GO_API_KEY como alias)
+export OPENAI_API_KEY=...                 # para openai puro
 ```
 
 ### How it works
 
-- The active selection is persisted to `.pantheon/active-preset.json` — `{version, preset, source, updated_at}` — written atomically (tmp file + rename) with a `.bak` backup of the previous file. It applies on the next OpenCode startup (no hot-swap); the plugin's `hooks.config` injects it.
-- **Resolution precedence**: `PANTHEON_MODEL_PRESET` env → first existing `.pantheon/active-preset.json` (project → `~/.config/opencode` → `~/.opencode`) → **none** (defaults).
-- **Partial semantics**: a preset overrides only the agents it lists; unlisted agents inherit the invoking primary agent's model.
-- Interactive picker during `init`: one prompt listing the 6 presets (select by number or name, blank to skip). It never touches your `opencode.json` — the choice is injected at startup instead. The file format also supports an optional `overrides` block (per-agent `model`/`variant`, per-provider `baseURL`/`apiKeyEnv`) merged over the preset definition.
-- **Capability normalization**: requested reasoning effort is clamped to each model family's ceiling (`deepseek-v4-flash` max `medium`; claude models strip the variant entirely — Anthropic uses thinking).
-- **fallback_models**: per-agent ordered fallback list where configured (e.g. `go-deepseek` sets `[opencode/mimo-v2.5]` for every agent).
+- A seleção ativa é persistida (se não for `inherit`) em `.pantheon/active-preset.json` — `{version, preset, source, updated_at, overrides?}` — escrita atômica (`tmp`+`rename`) com backup `.bak`. Só aplica no próximo startup do OpenCode (sem hot-swap); o plugin em `hooks.config` injeta `provider`/`baseURL`/`apiKeyEnv`.
+- **Precedência**: `PANTHEON_MODEL_PRESET` env → primeiro `.pantheon/active-preset.json` existente (project → `~/.config/opencode` → `~/.opencode`) → **none = herança nativa** (sem `active-preset.json`).
+- **Herança nativa de delegates** (1.4.2): `src/pantheon/delegation.ts` resolve o modelo do filho em: `explicit model` em `pantheon_delegate` > `overrides.agents[agent].model` em `active-preset.json` > `loadRoutingAgentModels` (preset ativo) > omitir → OpenCode herda o modelo do chat pai. `small_model` nunca é enviado. Validação `provider/model-id` com `MODEL_REF_PATTERN`.
+- **Partial & overrides**: um preset sobrescreve só os agentes listados; agentes não listados herdam do pai. O bloco `overrides.agents[agent]` (via `/pantheon-model set --agent`) tem merge sobre o preset, validado via `capabilityEntry` e `normalizeCapability` (clamp ao teto do modelo) + aviso `hasVision` para modelos text-only; `overrides.providers` permite `baseURL`/`apiKeyEnv` custom. Escrita atômica com lock por path + `.bak`.
+- **Capability normalization**: `requested effort` é clamped ao teto da família em `CAPABILITY_TABLE` (`deepseek-v4-flash/-free` max `medium`; `gop-5.6-luna*`/`mimo-v2.5*` max `low`; `claude` strip; `qwen3.6-plus-free`/`big-pickle` etc. text-only).
+- **Interactive picker / wizard**: `scripts/install/model-picker.mjs` exporta `buildPresetTableRow`, `requiredKeyEnvForPreset`, `isKeyConfiguredForPreset`, `maskKey`, `buildInitQuestions`, `runInitWizard` e `runModelPicker`. Nunca toca `opencode.json`; também expõe helper `maskKey` para logs.
 
 ### Quick smoke test
 
 ```bash
+# 1) default (herança nativa) — sem preset
+npx pantheon-opencode init --headless   # escolha 0 no wizard interativo = inherit
+opencode run "hello" 2>&1 | grep "Pantheon"
+# sem log de preset → herança nativa
+
+# 2) com preset
 export PANTHEON_OPENCODE_API_KEY=...
-pantheon-opencode set-tier go-fast --project
+npx pantheon-opencode set-tier go-fast --project
 opencode run "hello" 2>&1 | grep "Pantheon"
 # expect: [Pantheon Plugin] Model preset active: go-fast (source: file)
+
+# 3) override per-agent
+# no chat OpenCode:
+/pantheon-model status
+/pantheon-model set --agent hermes --model openai/gpt-5.6-luna --effort high --scope project
+# persiste em .pantheon/active-preset.json overrides.agents.hermes
 ```
 
+
 ---
 
 ## Quick Start
 
 ### 1. Install Pantheon
 
-Pantheon runs on **OpenCode**. Install it globally:
+Pantheon runs on **OpenCode**. Instalação global com **wizard 3 perguntas** (default = herdar do chat):
 
 ```bash
 npx pantheon-opencode init
+# Q1: perfil — 0=herdar do chat [default] (sem active-preset.json), ou go-free / go-fast / go-premium / openai
+#      tabela exibida: perfil | provider/baseURL/key | preço 2026 | modelos por papel
+# Q2: API key — coleta mascarada (PANTHEON_OPENCODE_API_KEY alias OPENCODE_GO_API_KEY, ou OPENAI_API_KEY), não escreve .env
+# Q3: escopo — project (./.pantheon/active-preset.json, default) ou global (~/.config/opencode/.pantheon/active-preset.json)
+#      gravação atômica tmp+rename com .bak + health-check
+```
+
+Atalhos:
+
+```bash
+npx pantheon-opencode init --preset go-fast --headless  # pula wizard
+npx pantheon-opencode init --project                    # escopo project-local
+npx pantheon-opencode init --headless --no-mcp          # minimal sem Python
 ```
 
-For MCP servers (memory, persistence):
+MCP servers (memory, persistence) — opcional via:
 
 ```bash
 npm run setup
 ```
 
+Ou já incluído no wizard se escolher instalação completa.
+
 ### 2. Launch OpenCode
 
 ```bash
 export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
 opencode
+# ou
+npm run start
 ```
 
-### 3. Run your first feature
+Dica: após instalar preset, `opencode run "hello" 2>&1 | grep "Pantheon"` deve mostrar `[Pantheon Plugin] Model preset active: <preset> (source: file)`; sem preset, fica em herança nativa (sem log de preset).
+
+### 3. Customize per-agent (opcional)
+
+No chat OpenCode:
+
+```
+# lista 14 agentes com modelo/effort/origem
+/pantheon-model status
+
+# wizard interativo (agente → modelo → effort → scope)
+/pantheon-model
+
+# override explícito por agente (validado via CAPABILITY_TABLE, clamp, hasVision)
+/pantheon-model set --agent hermes --model opencode-go/gpt-5.6-terra --effort medium --scope project
+/pantheon-model reset --agent hermes --scope project
+```
+
+Overrides vivem em `.pantheon/active-preset.json` em `overrides.agents[agent]` — sem `model`/`small_model` top-level e sem `.env`.
+
+### 4. Run your first feature
 
 Once agents are loaded, invoke the orchestrator:
 
@@ -778,6 +806,7 @@ Type these in the OpenCode chat:
 | `/pantheon-remember` | Store in memory |
 | `/pantheon-search` | Search memory |
 | `/pantheon-status` | System health and agent status |
+| `/pantheon-model` (wizard) / `status\|show\|set --agent\|reset --agent` | Herança nativa default; `status` lista 14 agentes (model/effort/origem); `set --agent X --model provider/model-id [--effort low|medium|high] [--scope project|global]` com validação CAPABILITY_TABLE + clamp + hasVision; `reset --agent X`; default scope `project`; global exige `confirm`+`authorize_global`; nunca escreve `.env` nem top-level `model`; persistência atômica `.bak` + health-check |
 | `/pantheon-verify` | Hash edit verification |
 
 ---
@@ -1025,16 +1054,15 @@ Use the isolated sandbox (`~/pantheon-sandbox/`) — **never** the dev environme
 **Happy path (clean edit):** any normal tool call (exit 0) is **silent** — no console output by design, even though the audit hooks append their log files (`sessions.log`, `delegations.log`). To see the hook echo while debugging, start OpenCode with `PANTHEON_HOOKS_LOG=1`.
 
 **Delegation path (zero chat noise):** delegation signals are surfaced through
-TUI toasts (when enabled), the board's `[unread]` marker, and the
-`pantheon_delegation_list` / `pantheon_delegation_read` tools. Ask something
+TUI toasts (when enabled) and the board's `[unread]` marker. Ask something
 that dispatches subagents (e.g. *"dispare 2 subagentes apollo em paralelo para
 listar arquivos e comparar resultados"*) and expect:
 
 - A TUI toast with `🚀 apollo em execução` / `✅ apollo concluiu` when
   `PANTHEON_TOASTS` permits it
-- `[unread]` in `pantheon_delegation_list` until the terminal result is read
+- `[unread]` on the board until the terminal result is read
 - An honest append to `logs/agent-sessions/delegations.log`: the **real agent name** (extracted from `tool_input.subagent_type`, never `unknown` when present) and a **non-fabricated status** — `success` only on explicit completion evidence, `failure` for refusals/errors, `unknown` otherwise
-- With `export PANTHEON_TOASTS=off` before starting OpenCode: no toasts; board/list/read and audit-log visibility remain available
+- With `export PANTHEON_TOASTS=off` before starting OpenCode: no toasts; board and audit-log visibility remain available
 
 ### Pre-commit hooks (local secret gate)
 

package/bin/pantheon-init.mjs

@@ -190,6 +190,11 @@ async function main() {
     const autoYes = args.includes('--yes') || args.includes('-y')
     const presetIndex = args.indexOf('--preset')
     const presetOpt = presetIndex >= 0 ? (args[presetIndex + 1] ?? null) : null
+    // Explicit top-level model overrides for the generated config.
+    const modelIndex = args.indexOf('--model')
+    const modelOpt = modelIndex >= 0 ? (args[modelIndex + 1] ?? null) : null
+    const smallModelIndex = args.indexOf('--small-model')
+    const smallModelOpt = smallModelIndex >= 0 ? (args[smallModelIndex + 1] ?? null) : null
     // --version v1|v2 labels the install target (informational; the config is
     // shared and V1-shaped under both versions). Invalid values fail fast.
     const versionIndex = args.indexOf('--version')
@@ -218,6 +223,8 @@ async function main() {
         interactive: forceInteractive,
         headless: forceHeadless,
         yes: autoYes,
+        model: modelOpt,
+        smallModel: smallModelOpt,
         preset: presetOpt,
         version: versionOpt ?? 'v1',
       })

package/commands/pantheon-model.md

@@ -0,0 +1,34 @@
+---
+description: "Inspect or change per-agent model overrides in active-preset.json"
+agent: zeus
+---
+# /pantheon-model — Per-agent model overrides
+
+Use the deterministic `pantheon_model` tool for this command. Operates exclusively
+on `active-preset.json` `overrides.agents[agent]` (project or global). Never
+writes `.env` and never injects top-level `model`/`small_model` into `opencode.json`.
+
+## Usage
+
+- `/pantheon-model status` or `/pantheon-model show` — list 14 canonical agents
+  (`zeus`, `athena`, `apollo`, `hermes`, `aphrodite`, `demeter`, `themis`,
+  `prometheus`, `hephaestus`, `nyx`, `gaia`, `iris`, `mnemosyne`, `talos`)
+  with effective `model`, `effort`, and origin (`preset` | `override` | `env` | `none`)
+  and the active preset, without showing secrets.
+- `/pantheon-model` (no args) — interactive wizard via `askQuestions`:
+  agente → modelo (`provider/model-id`) → effort (`low`/`medium`/`high`) → scope.
+
+- `/pantheon-model set --agent <name> --model <provider/model-id> [--effort low|medium|high] [--scope project|global]`
+  — set per-agent override. Validates agent is one of the 14, `provider/model-id`
+  format, `CAPABILITY_TABLE` entry via `capabilityEntry()` and clamps effort via
+  `normalizeCapability()`; warns via `hasVision` for text-only models. Persists
+  atomically with `.bak` backup and per-path lock. Default scope is `project`.
+
+- `/pantheon-model reset --agent <name> [--scope project|global]` — remove the
+  per-agent override from `overrides.agents[agent]`.
+
+`--scope project|global` is supported by `set` and `reset`. Global changes require
+explicit `confirm` and `authorize_global`. Values must use `provider/model-id`.
+Changes are backed up (`.bak`) and written atomically; restart OpenCode after a
+successful change. The tool never writes `.env` and never injects `model`/`small_model`
+global keys — delegate inheritance is native (no model → inherits chat/preset model).

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "postinstall": "node scripts/postinstall.mjs",
+    "postinstall": "node scripts/postinstall.mjs && node scripts/sync-tui.mjs",
     "prepare": "husky",
     "setup": "node bin/pantheon-init.mjs init",
     "build:agents-md": "node scripts/build-agents-md.mjs",