pantheon-opencode 1.4.0 → 1.4.2

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.3.6--beta-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>
@@ -225,7 +225,7 @@ via three delegation tools, tracked on a persistent job board
 
 | 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_delegate` | `{prompt, agent, description?, read_only?, model?}` | Creates a child session (parentID = caller), registers it on the job board, arms a 15-minute timeout, and sends `promptAsync` to the child. `model` is optional and uses `provider/model-id`. 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. |
 
@@ -239,17 +239,16 @@ 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.
 
-**Completion visibility — no chat injection.** User policy: ZERO delegation
-notifications in the chat transcript — no `<task-notification>` block is ever
-injected into a `chat.message` output (the old queue + flush channel was
-removed). 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-hooks, `PANTHEON_TOASTS` gate) and compaction carry-forward. Reconcile
-is an acknowledgment, not a completion — it never re-fires the terminal
-transition.
+**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.
 
 **Timeout:** `background_delegation.timeout_ms` (default `900000` = 15 min). A job
 that has not reached a terminal state is finalized as `error`/`timedOut`.
@@ -278,6 +277,22 @@ 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.
 
+**Delegated model resolution:** the optional child model is resolved in this
+order: (1) explicit `model` on `pantheon_delegate`; (2) the target agent's
+model in the active preset; (3) the current model of the parent session; (4)
+no model, allowing OpenCode's native inheritance. `small_model` is never used
+for delegates. When a model resolves, the same `provider/model-id` is sent as
+`{providerID, id}` to both `session.create` and `promptAsync`, including the
+single safe bootstrap retry; the retry does not select a different model. If
+the resolution lookup yields no model, the model field is omitted and the
+delegation continues with native inheritance.
+
+Model availability is not inferred from the string. The provider must exist in
+OpenCode and the referenced model must be available through that provider's
+account, subscription, or configured endpoint; otherwise the child host may
+reject startup. An active preset supplies provider configuration and model
+mappings, but does not make an unavailable provider or model available.
+
 **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
@@ -338,10 +353,9 @@ 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 — is re-injected as a `<system-reminder>` into the session's next
-message via the shared chat-reminder buffer (`chat-reminders.ts`, the same P0
-messageID guard that protects subagent fires). A session with nothing to
-assert is a silent skip.
+lines — remains available through compaction carry-forward and the board
+(`pantheon_delegation_list` / `pantheon_delegation_read`). 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
 (`preemptive-compact.ts`) warns the model before the context fills: at 78%
@@ -350,36 +364,22 @@ dormant / ready-to-wire — opencode 1.18.x exposes no runtime context-usage
 percentage, so nothing observes it yet; when a source appears, the caller
 wires it in (the enqueue callback is injected).
 
-**Model API-key validation (1.3.4):** `pantheon_delegate` gates the resolved
-child model's provider before dispatching (single source of truth:
-`routing.yml` preset definitions' `apiKeyEnv` — the same check `applyPreset`
-enforces at startup). If an **auto-resolved** model (`options.agentModels` or
-the active preset) points to a provider that requires an API key
-(`apiKeyEnv`) and the env var is unset, the delegate falls back to
-`opencode-go/deepseek-v4-flash` (validated the same way). If the fallback is
-also unusable, the tool returns a clear error **text** (never throws) naming
-the missing env var — and registers **no job** on the board. An **explicit**
-`model` passed by the caller is always respected (warned, not overridden).
-Setting `PANTHEON_MODEL_PRESET` to a preset whose providers have keys, or
-filling the required `PANTHEON_*_API_KEY` env var for the preset's provider,
-resolves the fallback path. If nothing resolves at all (no model, no preset),
-the child keeps using opencode's default model (warned).
-
-**agentModels wiring (1.3.4):** the delegate now also resolves the child model
-via `routing.yml` — `loadRoutingAgentModels` extracts the per-agent models of
-the FIRST-listed preset (the static default, `go-deepseek` today) and passes
-them as `options.agentModels`, branch (b) of the resolve precedence: explicit
-`model` > `options.agentModels` > active preset > opencode default. Delegation
-no longer depends exclusively on the active preset — a delegated child gets a
-sane per-agent model even when no preset is active. Fail-open: a missing or
-unparseable routing.yml yields `{}` (previous behavior, warned).
+**Model selection (1.4.1):** the child session inherits the parent session's
+model through OpenCode. A model override is supplied only when the active
+routing profile defines one; no model API-key validation is performed here.
+
+**agentModels wiring (1.3.4):** `loadRoutingAgentModels` extracts only the
+per-agent models from the explicitly active routing profile and passes them as
+`options.agentModels`. No active profile, missing profile entry, or profile
+without `model` produces an empty map; there is no implicit first-preset or
+DeepSeek fallback. A missing or unparseable `routing.yml` is fail-open and
+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. The idle-flush log entry is
-deduplicated: the flush logs a summary (count + aggregated line count) and the
-reminder content is logged exactly once, at `chat.message` delivery — no more
-duplicate lines for the same notification.
+(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.
 
 **Env vars & config:**
 
@@ -657,112 +657,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 ([herança nativa](src/pantheon/delegation.ts)). 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: `explicit model` em `pantheon_delegate` > 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:
 
@@ -794,6 +893,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 |
 
 ---
@@ -1040,11 +1140,17 @@ 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 (chat.message reminders):** on OpenCode 1.18.13 the TUI drops `tui.toast.show` events, so delegation signals are injected into the next user message as a single `<system-reminder>` text part (oh-my-openagent fallback pattern). Ask something that dispatches subagents (e.g. *"dispare 2 subagentes apollo em paralelo para listar arquivos e comparar resultados"*) and expect:
+**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
+that dispatches subagents (e.g. *"dispare 2 subagentes apollo em paralelo para
+listar arquivos e comparar resultados"*) and expect:
 
-- A `<system-reminder>` in the chat with `🚀 apollo em execução` / `✅ apollo concluiu` (or the aggregate `✅ N agentes concluídos (...)` for 3+ agents completing within 6s)
+- 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
 - 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/reminders at all
+- With `export PANTHEON_TOASTS=off` before starting OpenCode: no toasts; board/list/read 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/opencode.json

@@ -14,8 +14,6 @@
   "experimental": {
     "subagent_depth": 2
   },
-  "model": "opencode-go/deepseek-v4-flash",
-  "small_model": "opencode-go/deepseek-v4-flash",
   "permission": {
     "skill": {
       "*": "allow"

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "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",