pantheon-opencode 1.6.0-beta.1 → 1.6.0-beta.3

package/CHANGELOG.md

@@ -18,6 +18,138 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## ✅ Closed Issues
 
+## [v1.6.0-beta.3] - 2026-10-03
+
+<!-- Add new changes here. Running `node scripts/versioning.mjs apply` will
+     move this section to a versioned entry and reset the template below. -->
+
+## 🆕 What's New
+- **Três ferramentas V2 agora executam de verdade**: `hashline_edit`,
+  `pantheon_cost` e `pantheon_model` rodam no host `opencode v2.0.x`. Antes
+  eram placeholders que declaravam sucesso sem fazer nada.
+- **Enforcement de sessão read-only no caminho V2**: `apollo` e `gaia` voltam
+  a ter escrita bloqueada, com o guard registrado no próprio plugin V2 — sem
+  depender de uma ponte que a instalação V2 não monta.
+- **Varredura de segredos de alta confiança no caminho V2**: o único hard block
+  de segurança que a V1 tinha, e que estava inerte por viver num plugin que a
+  instalação V2 não carrega, passa a rodar.
+
+## 🐞 Fixed
+- **As 6 ferramentas de plugin do V2 falhavam em 100% das chamadas**:
+  `hashline_edit`, `pantheon_cost` e `pantheon_model` lançavam
+  `Tool result declared output without an output schema` em toda invocação. A
+  causa era assimetria local — `draft.add()` não declarava `output` enquanto o
+  `execute` resolvia `{ output: string }`. O host exige simetria nos dois
+  sentidos: resultado com `output` e nenhuma declaração lança, assim como
+  declaração sem `output` no resultado. `output` passou a ser **obrigatório** na
+  interface `V2ToolDef`, então o compilador exige a declaração daqui em diante.
+- **A suíte exigia o defeito**: `tests/pantheon/plugin-v2-contract.test.ts`
+  afirmava que o resultado carregava `.output` string — literalmente a condição
+  de falha, contra um mock que não reproduzia a exigência do host. O teste foi
+  reescrito para o invariante de simetria, contra um mock que constrói o
+  `outputSchema` a partir de `def.output` como o host faz
+  (`output: I.outputSchema ?? {}`), cobrindo as duas direções do bicondicional.
+- **A imposição read-only não existia na superfície V2**: `createEnforcementGuard`
+  só era instanciado em `src/plugin.ts`, que o `opencode.json` da release não
+  declara — V2 nunca carrega V1. Com `hashline_edit` funcional, uma sessão
+  somente-leitura podia escrever arquivos. O guard passou a ser registrado no
+  hook `execute.before` do V2, e `pantheon_model` — que escreve
+  `active-preset.json` em escopo project e global — foi acrescentado a
+  `DEFAULT_BLOCKED_TOOLS`, o que corrige também a V1. `pantheon_cost` ficou de
+  fora de propósito: só lê `opencode.db`.
+- **O único hard block de segurança da V1 estava inerte**: o scan de segredos de
+  alta confiança vivia em `src/plugins/pantheon-hooks.ts`, um plugin que a
+  instalação V2 não carrega — inerte por construção, não por má configuração.
+  Passou a rodar dentro do `execute.before` do V2
+  (`scripts/hooks/scan-secrets.sh`; exit 2 bloqueia, exit 1 é advisory e só
+  registra). O caminho do script foi verificado a partir do tarball instalado,
+  não só do repo.
+- **Cinco comentários afirmavam cobertura que não existe** ("wired through the
+  V1…"). Corrigidos — é o defeito "anunciado como vivo, morto no caminho", a
+  mesma classe do bug original, transferida do tool para o controle de segurança.
+
+## ⚠️ Known Issues
+- **A release entrega 3 ferramentas V2 funcionais, não 6**:
+  `pantheon_goal_create`, `pantheon_goal_get` e `pantheon_goal_update` foram
+  **removidos** da superfície V2. `GoalLoopDeps` exige `store`, `client` e
+  `board`, que não existem no `PluginContext` V2, e a bridge V1 resolve para
+  `null` fora da V1. Registrá-las como placeholders não funcionais seria pior
+  que a ausência: anunciá-las seria mentira silenciosa. Marcador `goal-tools`
+  em `V2_UNSUPPORTED_FEATURES`. **Breaking** para quem usava esses tools no
+  host V2 — o contrato V1 permanece disponível para o goal loop.
+- **A matriz de delegação nativa da V1 não é replicada na V2**: o guard V2 cobre
+  a lista de ferramentas bloqueadas, mas não a matriz caller→target nem a negação
+  de `task` em sessão filha. A matriz precisa de uma hierarquia de sessões
+  semeada a partir dos metadados de sessão, e o V2 não expõe esse caminho de
+  semeadura — `SessionHierarchyRegistry.isRoot` reporta `true` para sessões
+  desconhecidas enquanto não semeada, então semeá-la pela metade negaria todo
+  `task()`. O branch é pulado em vez de negado indiscriminadamente. Marcador
+  `delegation-matrix`. `task` continua negada em sessão somente-leitura pela
+  lista de ferramentas bloqueadas, então a profundidade 2 se sustenta; o que
+  não existe é a matriz. Coberto por `experimental.subagent_depth` nesta
+  configuração, mas a garantia do plugin não existe.
+- **O log do scan de segredos escreve só em `.pantheon/logs/hooks.log`**: o
+  `PluginContext` V2 não expõe `client` nem `directory`, então os canais de log
+  estruturado e de toast da V1 não existem nessa superfície. É menos
+  observabilidade, não menos bloqueio.
+- **Falha de infraestrutura do scanner é fail-open por decisão**: script ausente
+  ou timeout não bloqueiam. `runHook` nunca rejeita e um erro de infraestrutura
+  não deve negar chamadas não relacionadas. Ausência do script não bloqueia.
+
+## ✅ Closed Issues
+- **Drift de documentação no `README.pt-BR.md`**: a tabela de contrato de
+  runtime e o parágrafo de superfície listavam 6 ferramentas V2 e as 3 de goal,
+  que não estão registradas. Corrigido para 3 ferramentas, com a razão da
+  ausência e o ponto de imposição read-only.
+- **Cinco comentários de falsa cobertura** sobre a imposição read-only e o scan
+  de segredos.
+- **Shim do loader JSON do ajv elevado a bootstrap de módulo**: o patch de
+  `Module._extensions['.json']` era aplicado de dentro de `loadAjv()` e ficava
+  vivo durante todo o run, podendo vazar entre arquivos de teste e se manifestar
+  longe da causa. Agora instala, carrega e restaura em nível de módulo, antes de
+  qualquer corpo de teste, com `finally`.
+## [v1.6.0-beta.2] - 2026-10-02
+
+## 🆕 What's New
+- **`steps` não é mais definido pelo Pantheon**: removido dos 14 agentes em
+  `src/agents/`. No OpenCode 2 o campo é opcional e **sem default** — ausente
+  significa **sem teto nativo**. O host não impõe teto; o Pantheon estava
+  escrevendo um.
+- **Instalador v2 remove `steps` residual**: configs já instalados passam a ter
+  o `steps` apagado dos agentes gerenciados. Escopo restrito aos agentes que o
+  Pantheon gerencia — um agente definido pelo usuário nunca é tocado. O bloco V1
+  singular `agent` é deliberadamente intocado (V1 em retirada).
+- **Substitutos ao teto**: `task(background=true)` para trabalho fora da
+  foreground, `experimental.subagent_depth` para aninhamento de subagentes e
+  paralelismo entre delegações independentes.
+- **Limpeza**: `max_steps` e `max_compaction_items` removidos de
+  `src/routing.yml`. `loadRoutingMaxSteps` nunca teve um único import — 2
+  matches no repo (definição e typedef), ambos removidos.
+
+## 🐞 Fixed
+- **`migrateV1toV2` descartava campos gerenciados**: com os blocos `agent` (V1)
+  e `agents` (V2) coexistindo — o caso de qualquer config já instalado — o
+  spread raso fazia um substituir o outro por inteiro. Na ordem de chaves do
+  `opencode.json` real, o lado perdedor era o do usuário. Agora **mescla**: a
+  base é o bloco V2, os campos gerenciados do V1 sobrescrevem, e os campos do
+  usuário são preservados. Mesma semântica já usada em `install/opencode.mjs`.
+- **`docs/platforms/README.md` tinha tabela de step limits errada**: 14 linhas
+  listando limites por agente, **nenhum valor batendo** com `src/agents/`.
+  Tabela removida e a seção reescrita.
+
+## ⚠️ Known Issues
+- **Permissões de agente**: V1 usa `permission` e V2 usa `permissions`; ao mesclar esses blocos, a chave legada `permission` pode permanecer inerte ao lado de `permissions`.
+- **Migração — rode o init uma vez**: `npx pantheon-opencode init
+  --opencode-version=v2` **uma única vez** limpa o `steps` residual. Sem isso o
+  config instalado continua carregando o teto antigo.
+- **O `.md` de agente instalado é sobrescrito no próximo sync**: editar
+  `~/.config/opencode/agents/*.md` esperando persistência **não funciona**.
+  Comportamento **pré-existente**, não é regressão desta mudança — mas agora
+  está documentado para não ser reportado como uma.
+- **`steps` definido à mão num agente gerenciado é removido a cada install v2**:
+  o instalador não distingue um valor que ele escreveu de um valor que você
+  escreveu (mesma chave, mesmo valor). Workaround: definir no frontmatter do
+  agente — e lembrar que ele **também** é sobrescrito no próximo sync.
 ## [v1.6.0-beta.1] - 2026-09-30
 
 <!-- Add new changes here. Running `node scripts/versioning.mjs apply` will

package/README.md

@@ -78,11 +78,14 @@ clear handoff between stages of work.
 
 ## Status
 
-Operational checkout version: **v1.6.0-beta.1** (first beta compatible with
-OpenCode 2; publication is not asserted here). Pantheon is designed for OpenCode and depends on the
-availability and configuration of OpenCode and any optional services you choose
-to use. Check the [releases](https://github.com/ils15/pantheon-opencode/releases)
-and [changelog](CHANGELOG.md) for the latest published changes.
+Candidate version: the manifests in this checkout express the version being
+prepared, not a confirmed publication. A beta is published only after the
+Release workflow completes successfully. To check which version is actually
+published, consult the npm `beta` dist-tag. Pantheon is designed for OpenCode
+and depends on the availability and configuration of OpenCode and any optional
+services you choose to use. Check the
+[releases](https://github.com/ils15/pantheon-opencode/releases) and
+[changelog](CHANGELOG.md) for the latest published changes.
 
 ## Delegation (native `task()`)
 
@@ -183,16 +186,36 @@ per installation; V1 and V2 Pantheon plugins must never be registered together.
 |---|---|---|
 | OpenCode config key | singular `plugin` | plural `plugins` |
 | Pantheon registration | `src/plugin.ts` plus `src/plugins/pantheon-hooks.ts` | `<installed>/src/plugin-v2` directory (`index.ts` re-exports `src/plugin-v2.ts`) |
-| Runtime contract | Pantheon V1 plugin: 6 tools (`hashline_edit`, the 3 goal tools, `pantheon_cost`, `pantheon_model`), event/tool hooks and V1 compaction handling | Full V2 plugin: 6 orchestration tools, 4 event subscriptions, session hooks (`prompt`, `context`), tool hooks (`execute.before`/`after`), plus configuration transforms |
+| Runtime contract | Pantheon V1 plugin: 6 tools (`hashline_edit`, the 3 goal tools, `pantheon_cost`, `pantheon_model`), event/tool hooks and V1 compaction handling | Full V2 plugin: 3 tools (`hashline_edit`, `pantheon_cost`, `pantheon_model`), 4 event subscriptions, session hooks (`prompt`, `context`), a read-only-enforcing tool `execute.before` hook, plus configuration transforms |
 | V1 APIs | Registered | Own tool definitions via `ctx.tool.transform()` — not the V1 plugin path |
 
-The V2 plugin provides 6 orchestration tools (`hashline_edit`,
-`pantheon_goal_create`, `pantheon_goal_get`, `pantheon_goal_update`,
-`pantheon_cost`, `pantheon_model`), 4 event subscriptions (`session.created`,
-`session.idle`, `session.error`, `session.compacted`), session hooks (`prompt`,
-`context`), and tool hooks (`execute.before`, `execute.after`). Unsupported V2
-features are `legacy-hooks` (the V1-specific hook surface), `catalog-transform`,
-`integration-transform`, and `skill-transform`.
+The V2 plugin provides 3 orchestration tools (`hashline_edit`, `pantheon_cost`,
+`pantheon_model`), 4 event subscriptions (`session.created`, `session.idle`,
+`session.error`, `session.compacted`), session hooks (`prompt`, `context`),
+and a tool `execute.before` hook that enforces read-only sessions. The 3 goal
+tools are **not**
+registered on V2: the goal loop needs a `GoalStore`, a `GoalLoopClient` and a
+`BackgroundJobBoard`, none of which the V2 `PluginContext` exposes, so the gap
+is reported as the `goal-tools` unsupported-feature marker. Use the V1
+contract if you need the goal loop.
+
+The V2 `execute.before` hook is the read-only enforcement point for that
+surface: the host includes the active agent on the event, a read-only agent
+(`apollo`, `gaia`) registers its session, and the shared
+`createEnforcementGuard` throws to deny `edit`, `write`, `bash`, `task`,
+`hashline_edit` and `pantheon_model`. It does **not** rely on the V1
+`tool.execute.before` hook, which lives in `src/plugin.ts` and is not loaded
+when only `plugin-v2` is configured. The companion `execute.after` hook and the
+`permission.evaluate` hook are registration points with no V2-side behaviour,
+and the V1 caller/target delegation matrix for native `task()` is not enforced
+on V2.
+
+Every V2 tool declares an `output` schema. OpenCode 2.0.x requires the
+declaration and the resolved result to agree in both directions, so an
+undeclared tool — or one that returns `output` without declaring it — fails on
+every call. Unsupported V2 features are `legacy-hooks` (the V1-specific hook
+surface), `catalog-transform`, `integration-transform`, `skill-transform` and
+`goal-tools`.
 
 The package exposes both contracts as importable exports: `pantheon-opencode/plugin`
 (V1), `pantheon-opencode/plugin-v2` (V2) and `pantheon-opencode/v2-bridge`
@@ -231,6 +254,29 @@ The installer still writes the compatibility settings required by the selected
 OpenCode host, such as `experimental.subagent_depth`; this does not convert a
 V1 plugin into V2 or provide V2 with V1 hooks.
 
+Pantheon does not set a step ceiling on agents. On OpenCode 2 the `steps`
+field is optional and has no default: absent means the host applies no native
+limit. A config written before this change still carries the old value, and the
+V2 install path strips it from every agent Pantheon manages — an agent you
+define yourself is never touched, and the retiring V1 singular `agent` block
+is left alone. Run the installer once to clear a stale value from an existing
+config:
+
+```bash
+npx pantheon-opencode init --opencode-version=v2
+```
+
+Context control is not a Pantheon setting. Whatever budget an agent runs
+against comes from the compaction settings of the OpenCode host you are
+running, and Pantheon does not define them.
+
+When a V1 `agent` block and a V2 `agents` block are both present — which is
+what an installed `opencode.json` carries — the V1→V2 conversion merges them
+instead of letting one replace the other. The V2 block is the base, the
+framework-managed fields from the V1 block overwrite, and your own fields are
+preserved, matching the precedence the installer already applies elsewhere.
+Key order does not matter.
+
 ## Updating between releases (beta.5+)
 
 One command keeps an existing installation current:

package/README.pt-BR.md

@@ -122,16 +122,36 @@ registrados juntos.
 |---|---|---|
 | Chave de config do OpenCode | `plugin` singular | `plugins` plural |
 | Registro Pantheon | `src/plugin.ts` mais `src/plugins/pantheon-hooks.ts` | `pantheon-opencode/plugin-v2` (`src/plugin-v2.ts`) |
-| Contrato de runtime | Plugin Pantheon V1: 6 ferramentas (`hashline_edit`, as 3 ferramentas de goal, `pantheon_cost`, `pantheon_model`), hooks de evento/ferramenta e tratamento de compactação V1 | Plugin V2 completo: 6 ferramentas de orquestração, 4 assinaturas de eventos, session hooks (`prompt`, `context`), tool hooks (`execute.before`/`after`), além de transforms de configuração |
+| Contrato de runtime | Plugin Pantheon V1: 6 ferramentas (`hashline_edit`, as 3 ferramentas de goal, `pantheon_cost`, `pantheon_model`), hooks de evento/ferramenta e tratamento de compactação V1 | Plugin V2 completo: 3 ferramentas (`hashline_edit`, `pantheon_cost`, `pantheon_model`), 4 assinaturas de eventos, session hooks (`prompt`, `context`), um hook de ferramenta `execute.before` que impõe sessões somente-leitura, além de transforms de configuração |
 | APIs V1 | Registradas | Definições próprias de ferramentas via `ctx.tool.transform()` — não pelo caminho do plugin V1 |
 
-O plugin V2 fornece 6 ferramentas de orquestração (`hashline_edit`,
-`pantheon_goal_create`, `pantheon_goal_get`, `pantheon_goal_update`,
+O plugin V2 fornece 3 ferramentas de orquestração (`hashline_edit`,
 `pantheon_cost`, `pantheon_model`), 4 assinaturas de eventos (`session.created`,
 `session.idle`, `session.error`, `session.compacted`), session hooks (`prompt`,
-`context`) e tool hooks (`execute.before`, `execute.after`). Os recursos V2 sem
-suporte são `legacy-hooks` (a superfície de hooks específica do V1),
-`catalog-transform`, `integration-transform` e `skill-transform`.
+`context`) e um hook de ferramenta `execute.before` que impõe sessões
+somente-leitura. As 3 ferramentas de goal **não** são
+registradas no V2: o goal loop precisa de um `GoalStore`, de um
+`GoalLoopClient` e de um `BackgroundJobBoard`, nenhum dos quais o
+`PluginContext` do V2 expõe, então a lacuna é reportada como o marcador de
+recurso sem suporte `goal-tools`. Use o contrato V1 se precisar do goal loop.
+
+O hook `execute.before` do V2 é o ponto de imposição de sessões somente-leitura
+dessa superfície: o host inclui o agente ativo no evento, um agente somente-leitura
+(`apollo`, `gaia`) registra sua sessão, e o `createEnforcementGuard`
+compartilhado lança para negar `edit`, `write`, `bash`, `task`,
+`hashline_edit` e `pantheon_model`. Ele **não** depende do hook
+`tool.execute.before` do V1, que vive em `src/plugin.ts` e não é carregado
+quando apenas `plugin-v2` está configurado. Os hooks companheiros
+`execute.after` e `permission.evaluate` são pontos de registro sem comportamento
+do lado V2, e a matriz de delegação caller/target da V1 para o `task()` nativo
+não é imposta no V2.
+
+Toda ferramenta V2 declara um schema `output`. O OpenCode 2.0.x exige que a
+declaração e o resultado resolvido concordem nos dois sentidos, então uma
+ferramenta sem declaração — ou que retorne `output` sem declará-lo — falha em
+toda chamada. Os recursos V2 sem suporte são `legacy-hooks` (a superfície de
+hooks específica do V1), `catalog-transform`, `integration-transform`,
+`skill-transform` e `goal-tools`.
 
 O pacote expõe os dois contratos como exports importáveis:
 `pantheon-opencode/plugin` (V1), `pantheon-opencode/plugin-v2` (V2) e
@@ -171,6 +191,29 @@ O instalador continua gravando as configurações de compatibilidade exigidas
 pelo host OpenCode selecionado, como `experimental.subagent_depth`; isso não
 converte um plugin V1 em V2 nem dá hooks V1 ao V2.
 
+O Pantheon não define mais um teto de passos para os agentes. No OpenCode 2 o
+campo `steps` é opcional e não tem default: ausente significa que o host não
+aplica nenhum limite nativo. Uma config escrita antes dessa mudança ainda
+carrega o valor antigo, e o caminho de instalação v2 o remove de todos os
+agentes que o Pantheon gerencia — um agente definido por você nunca é tocado,
+e o bloco V1 singular `agent`, em retirada, é deixado intacto. Rode o
+instalador uma vez para limpar um valor antigo de uma config existente:
+
+```bash
+npx pantheon-opencode init --opencode-version=v2
+```
+
+O controle de contexto não é uma configuração do Pantheon. Qualquer orçamento
+que um agente terá vem das settings de compactação do próprio host OpenCode,
+e o Pantheon não as define.
+
+Quando um bloco V1 `agent` e um bloco V2 `agents` coexistem — o que acontece
+em qualquer `opencode.json` já instalado — a conversão V1→V2 mescla os dois em
+vez de deixar um substituir o outro. O bloco V2 é a base, os campos
+gerenciados que vêm do V1 sobrescrevem, e os seus próprios campos são
+preservados, com a mesma precedência que o instalador já aplica em outros
+pontos. A ordem das chaves não muda o resultado.
+
 ## Atualizando entre releases (beta.5+)
 
 Um comando mantém uma instalação existente em dia:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.6.0-beta.1",
+  "version": "1.6.0-beta.3",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "type": "module",
   "workspaces": [
@@ -105,6 +105,7 @@
     "@biomejs/biome": "2.5.13",
     "@commitlint/cli": "21.2.2",
     "@commitlint/config-conventional": "21.2.2",
+    "ajv": "8.20.0",
     "husky": "^9.1.7",
     "tsx": "4.23.13",
     "typescript": "6.0.3"

package/plugin.json

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

package/pyproject.toml

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

package/scripts/install/config-migration.mjs

@@ -304,6 +304,114 @@ const V2_TO_V1_RENAMES = Object.fromEntries(
   Object.entries(V1_TO_V2_RENAMES).map(([k, v]) => [v, k]),
 )
 
+/**
+ * Agent fields owned by the framework. Mirrors the exported MANAGED_FIELDS in
+ * install/opencode.mjs plus `source`, which the installer writes next to them.
+ * The migration runs before that merge, so it has to apply the same precedence
+ * itself when both `agent` and `agents` coexist: these come from the V1 block,
+ * every other field stays the user's.
+ *
+ * `permissions` is the V2 name — the converter renames the V1 `permission`
+ * block before the merge runs.
+ *
+ * `description` is deliberately absent, and this list is deliberately narrower
+ * than what the installer writes. The installer writes a description only when
+ * it creates an agent (install/opencode.mjs, the new-agent branch); on an agent
+ * that already exists it leaves the value alone, under its own comment "Existing
+ * agent fields belong to the user". So a description is framework-owned for a
+ * NEW agent and user-owned for an EXISTING one. Listing it here would make the
+ * migration stricter than the installer and would overwrite a description the
+ * installer deliberately preserves. mergeManagedAgents carries the value across
+ * instead, so it survives the merge without being treated as framework-owned.
+ *
+ * KNOWN DEBT: the installer still writes the V1 spelling `permission`, while V2
+ * reads `permissions`. An agent that goes through this merge can therefore end
+ * up carrying both keys, with `permission` left as dead weight that nothing
+ * reads. Tracked for the next slice; not fixed here, because picking a winner
+ * changes what an install writes.
+ */
+export const MANAGED_AGENT_FIELDS = Object.freeze([
+  'source',
+  'temperature',
+  'color',
+  'permissions',
+  'mode',
+  'hidden',
+  'disable_model_invocation',
+])
+
+/**
+ * Compare this module's managed-agent list against the installer's.
+ *
+ * The two merge paths have to agree: the migration reimplements the installer's
+ * merge because it runs before it. A field present on only one side is silent
+ * divergence — either the migration overwrites a field the installer leaves
+ * alone, or it stops mirroring one the installer now writes. Both directions
+ * matter, so the result is reported as a pair of differences rather than a
+ * boolean.
+ *
+ * Names are compared after the converter's renames, because that is the
+ * spelling the merge actually sees.
+ *
+ * @param {string[]} installerFields - MANAGED_FIELDS as exported by install/opencode.mjs
+ * @returns {{ onlyInMigration: string[], onlyInInstaller: string[] }}
+ */
+export function managedAgentFieldDrift(installerFields) {
+  const toV2Name = (field) => V1_TO_V2_RENAMES[field] ?? field
+  const migration = new Set(MANAGED_AGENT_FIELDS.map(toV2Name))
+  const installer = new Set(installerFields.map(toV2Name))
+  return {
+    onlyInMigration: [...migration].filter((f) => !installer.has(f)).sort(),
+    onlyInInstaller: [...installer].filter((f) => !migration.has(f)).sort(),
+  }
+}
+
+/** @returns {boolean} true for a plain name→config map (not null/array) */
+function isAgentMap(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Merge the converted V1 `agent` block into an existing V2 `agents` base.
+ *
+ * Agents present in both are merged field by field: the base is kept, keys the
+ * base does not have are filled in from the V1 block, and MANAGED_AGENT_FIELDS
+ * are overwritten by the V1 values. Agents present in only one block are taken
+ * as they are — a union, not a replacement.
+ *
+ * Filling the gaps matters, and it is not description-specific: any key present
+ * only in the V1 block used to vanish here — `model`, `provider` and `mcp` too.
+ * `description` is the visible case, because the installer never writes one for
+ * an existing agent, so the V1 block is the only place that value can come from
+ * and the agent lost it on every install, permanently. Filling gaps can never
+ * destroy a base value; on conflict the base still wins, as before.
+ *
+ * @param {object} base - existing V2 `agents` map
+ * @param {object} managed - converted V1 `agent` map
+ * @returns {object} merged map
+ */
+function mergeManagedAgents(base, managed) {
+  const merged = { ...base }
+
+  for (const [name, agentConfig] of Object.entries(managed)) {
+    const existing = merged[name]
+    if (!isAgentMap(existing) || !isAgentMap(agentConfig)) {
+      merged[name] = agentConfig
+      continue
+    }
+    const entry = { ...existing }
+    for (const [field, value] of Object.entries(agentConfig)) {
+      if (!(field in entry)) entry[field] = value
+    }
+    for (const field of MANAGED_AGENT_FIELDS) {
+      if (field in agentConfig) entry[field] = agentConfig[field]
+    }
+    merged[name] = entry
+  }
+
+  return merged
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -333,7 +441,20 @@ export function migrateV1toV2(config) {
         }
         agents[agentName] = ac
       }
-      result.agents = agents
+      // An `agents` (V2) block may already exist — the installed opencode.json
+      // carries both, in either key order. Renaming onto it with a plain
+      // replace dropped the whole managed merge, so merge instead.
+      const base = result.agents
+      result.agents = isAgentMap(base) ? mergeManagedAgents(base, agents) : agents
+    } else if (key === 'agents') {
+      // V2 block: it is the base. The singular `agent` key may already have
+      // been converted above, in which case merge the two.
+      const managed = result.agents
+      if (isAgentMap(value)) {
+        result.agents = isAgentMap(managed) ? mergeManagedAgents(value, managed) : value
+      } else if (!isAgentMap(managed)) {
+        result.agents = value
+      }
     } else if (key === 'provider' && typeof value === 'object' && value !== null) {
       const providers = {}
       for (const [provName, provConfig] of Object.entries(value)) {

package/scripts/install/opencode.mjs

@@ -61,6 +61,33 @@ const COMPONENT_NAMES = [
   'runtime',
 ]
 
+/**
+ * Per-agent fields owned by the framework: for an agent that already exists in
+ * the target config these are overwritten from the canonical source, and for a
+ * new agent they are the seed. Everything else on an existing entry is the
+ * user's and is left alone.
+ *
+ * `source` is written right next to these (for both new and existing agents) but
+ * is kept out of the loop so it can also be set independently — the migration in
+ * config-migration.mjs mirrors this list plus `source`, and tests assert the two
+ * stay equal as sets.
+ *
+ * KNOWN DEBT: `permission` is the V1 spelling. V2 reads `permissions`, so an
+ * agent can carry both keys after an install and the V1 one becomes dead weight.
+ * Tracked for the next slice; changing it here would change what an install
+ * writes.
+ *
+ * @type {readonly string[]}
+ */
+export const MANAGED_FIELDS = Object.freeze([
+  'temperature',
+  'color',
+  'permission',
+  'mode',
+  'hidden',
+  'disable_model_invocation',
+])
+
 function deepClone(value) {
   return JSON.parse(JSON.stringify(value))
 }
@@ -836,7 +863,6 @@ export async function installOpenCode(
       if (fm.mode) agent.mode = fm.mode
       if (fm.hidden) agent.hidden = fm.hidden
       if (fm.temperature !== undefined) agent.temperature = fm.temperature
-      if (fm.steps !== undefined) agent.steps = fm.steps
       // Support both hyphen (YAML) and underscore (JSON) key variants
       if (fm['disable-model-invocation'] !== undefined)
         agent.disable_model_invocation = fm['disable-model-invocation']
@@ -855,15 +881,6 @@ export async function installOpenCode(
 
   const canonicalAgentConfig = readAgentConfigFromCanonical()
   const agentSources = getAgentSources(agentPrefix)
-  const MANAGED_FIELDS = [
-    'steps',
-    'temperature',
-    'color',
-    'permission',
-    'mode',
-    'hidden',
-    'disable_model_invocation',
-  ]
 
   if (config.agent === undefined) config.agent = {}
 
@@ -1222,6 +1239,22 @@ export async function installOpenCode(
   if (version === 'v2') {
     info(S.v2Migrating)
     configToWrite = migrateV1toV2(config)
+
+    // Pantheon no longer sets a step ceiling. Any `steps` sitting on a managed
+    // agent was written by an earlier install and never chosen by the user —
+    // the merge above is additive by design (no delete path), so drop it here
+    // and let the host default apply. This runs after the migration because
+    // migrateV1toV2 copies the V1 `agent` block across verbatim (including any
+    // stale `steps`), which is exactly how the value reappears in V2.
+    // User-defined agents are out of scope and keep their value; the V1
+    // singular `agent` block is deliberately untouched (V1 is retiring).
+    const v2Agents = configToWrite.agents
+    if (v2Agents && typeof v2Agents === 'object' && !Array.isArray(v2Agents)) {
+      for (const name of Object.keys(canonicalAgentConfig)) {
+        const entry = v2Agents[name]
+        if (entry && typeof entry === 'object' && !Array.isArray(entry)) delete entry.steps
+      }
+    }
   }
 
   const configContent = `${JSON.stringify(configToWrite, null, 2)}\n`

package/skills-lock.json

@@ -1,7 +1,7 @@
 {
   "src/skills/agent-coordination/SKILL.md": "cfd040ef29e3dd0fd5e0e67773874facf7c06e3284898afe1fddba4456c3f1aa",
   "src/skills/artifact-management/SKILL.md": "c60e493666bedf46e9113d0dd20106489d5c5a73905e1370fcfc1c0d71c59185",
-  "src/skills/auto-continue/SKILL.md": "f6ff530b5537af9c8a0224a52eb0da6da7f9cf4ab4958ce2908c5c3a911b8879",
+  "src/skills/auto-continue/SKILL.md": "4fe256d44ee9828d622a0d8b63cfc6bb39a317189a9ccf19494a6efd4527a7a9",
   "src/skills/clonedeps/SKILL.md": "3e0b43cf96da98c83699dc48db3fd58fbfda84b9022bb70d3747875c81c3e124",
   "src/skills/code-review-checklist/SKILL.md": "0e59367c65ef4608db80a0674279f32cfc3f67dca7236f233b61a47fe506579f",
   "src/skills/codemap/SKILL.md": "87af5271e1576e154cadff313eab16264b726e43d094520736b7a5b03b409a4a",

package/src/agents/aphrodite.md

@@ -14,7 +14,6 @@ permission:
   task:
     "*": deny
 temperature: 0.3
-steps: 70
 skills:
   - tdd-with-agents
   - visual-review-pipeline

package/src/agents/apollo.md

@@ -17,7 +17,6 @@ permission:
   task:
     "*": deny
 temperature: 0.1
-steps: 30
 skills:
   - auto-continue
 mcp_tools:

package/src/agents/athena.md

@@ -6,7 +6,6 @@ description: Strategic planner & architect — research-first, plan-only, never
 mode: all
 reasoning_effort: high
 
-steps: 30
 mcp_tools:
   pantheon-resources: all
   pantheon-memory: [memory_search]

package/src/agents/demeter.md

@@ -12,7 +12,6 @@ permission:
   task:
     "*": deny
 temperature: 0.2
-steps: 60
 skills:
   - tdd-with-agents
   - incremental-implementation

package/src/agents/gaia.md

@@ -16,7 +16,6 @@ permission:
   task:
     "*": deny
 temperature: 0.2
-steps: 30
 skills:
   - auto-continue
 mcp_tools:

package/src/agents/hephaestus.md

@@ -12,7 +12,6 @@ permission:
   task:
     "*": deny
 temperature: 0.3
-steps: 60
 skills:
   - tdd-with-agents
   - auto-continue

package/src/agents/hermes.md

@@ -11,7 +11,6 @@ mcp_tools:
   pantheon-memory: [memory_search]
   pantheon-code-mode: [execute_code_script]
 temperature: 0.3
-steps: 70
 skills:
   - tdd-with-agents
   - file-prompts

package/src/agents/iris.md

@@ -14,7 +14,6 @@ permission:
   task:
     "*": deny
 temperature: 0.2
-steps: 25
 skills:
   - git-workflow-and-versioning
   - artifact-management

package/src/agents/mnemosyne.md

@@ -6,7 +6,6 @@ description: Memory bank quality owner — initializes .pantheon/memory-bank/, w
 mode: all
 reasoning_effort: low
 
-steps: 25
 mcp_tools:
   pantheon-resources: all
   pantheon-memory: