pantheon-opencode 1.6.0-beta.7 → 1.6.0-beta.8

package/AGENTS.md

@@ -38,9 +38,8 @@ Para validar a instalação global do pacote pantheon-opencode COMO UM USUÁRIO
 
 - Rodar: `bash ~/pantheon-sandbox/run-test.sh` (opencode mcp list 5/5 connected + doctor 0 erros + abre TUI isolado)
 - Regra para agentes: ao validar instalação global (npm pack, `init`, MCPs, hooks), usar o sandbox — NUNCA testar no ambiente de dev
-- Prepare/atualize com `bash scripts/test-opencode-v2-sandbox.sh --prepare`; isso gera `run-test.sh`, `start-pantheon.sh` e o README do sandbox
-- Descarte somente pelo reset com guardas: `bash scripts/test-opencode-v2-sandbox.sh --reset` (nunca use `rm -rf` manualmente)
-- Detalhes: ver `~/pantheon-sandbox/README.md` após o prepare
+- Descarte: `rm -rf ~/pantheon-sandbox`
+- Detalhes: ver `~/pantheon-sandbox/README.md`
 
 ## Conventions
 
@@ -65,7 +64,7 @@ are rendered into only the matching installed agent prompts.
 
 # Agent Return Format
 
-Implementation agents (Hermes, Aphrodite, Demeter, Hephaestus, Prometheus) return:
+All implementation agents (Hermes, Aphrodite, Demeter, Hephaestus, Prometheus) MUST return results to Zeus in this format:
 
 ## subtask_summary
 **files_changed:** [list of file paths, one per line]
@@ -76,13 +75,58 @@ Implementation agents (Hermes, Aphrodite, Demeter, Hephaestus, Prometheus) retur
 **status:** complete | partial (reason) | escalated (reason)
 **blockers:** [list any blockers or null]
 
-Investigation agents (Apollo, Athena) return structured findings with:
+For investigation agents (Apollo, Athena), return structured findings with:
 - Key findings as bullet points
 - File paths with line numbers
 - Relevant code snippets (max 3 lines each)
 
+## Council Specialist Response Format
+
+When responding to a `/pantheon` council synthesis invocation, specialists MUST return this structured format:
+
+```
+## specialist_response
+**position:** <clear one-sentence position answering the question>
+**reasoning:** <2-4 sentences with logical chain>
+**trade_offs:** <what's gained vs lost, specific>
+**risks:** <what could go wrong, max 3 items>
+**confidence:** High | Medium | Low
+**agreement_signals:** agree:@agent1 on <issue>, agree:@agent2 on <issue> | disagree:@agent3 on <issue>
+**specific_claims:** <count of specific factual claims in response>
+```
+
+### Field Rules
+
+| Field | Required | Validation |
+|-------|----------|------------|
+| position | ✅ | Single sentence, must directly answer the question |
+| reasoning | ✅ | 2-4 sentences with logical chain |
+| trade_offs | ✅ | At least one gain and one loss, specific to context |
+| risks | ✅ | Max 3 bullet points |
+| confidence | ✅ | One of: High, Medium, Low |
+| agreement_signals | Optional | Format: `agree:@agent on issue \| disagree:@agent on issue`. Use only when you can reference other specialists expected positions. |
+| specific_claims | ✅ | Integer count of verifiable factual statements in the response |
+
+### Confidence Guidelines
+
+- **High**: Position backed by 3+ specific claims with evidence or direct experience
+- **Medium**: Position backed by 1-2 specific claims
+- **Low**: Position is opinion-based or speculative
+
+### Example
+```
+## specialist_response
+**position:** The BackgroundJobBoard should be used for council crash recovery
+**reasoning:** The board already supports running→completed→reconciled state machine with persistence. Registering council dispatches there adds ~50ms overhead but prevents total session loss on context crash. The WAL pattern ensures no data loss on restart.
+**trade_offs:** Gain: crash recovery for multi-minute council sessions. Lose: ~50ms registration overhead per council.
+**risks:** Board persistence failure could block council start — implement with fire-and-forget error handling
+**confidence:** High
+**agreement_signals:** agree:@themis on persist-before-notify
+**specific_claims:** 3
+```
+
 ## Memory Context
-If this agent used `memory_recall` or `memory_search`, include the relevant memory entries used as context for the response.
+If memory affected the result, state the takeaway briefly; do not repeat the entry or task context.
 
 <!-- Source: src/instructions/memory-protocol.instructions.md -->
 ## Memory Protocol
@@ -94,18 +138,17 @@ These rules apply to all agents; each agent file may add domain-specific rules.
 
 ## Universal Rules
 
-### Task-start search
-**Before any file reads, call exactly once at task start:** `memory_search(query=task_prompt, top_k=2)`.
-- Reuse the same result for task context and delegation routing. A KV cache hit does not skip this search or trigger another task FTS search.
-- Council-precedent lookup is separate. Use domain-relevant context; do not issue another task-memory search for routing.
-- Agents have read-only memory access: only `memory_search()` is available.
+### Retrieval
+- Search only when prior project history could change the outcome; skip self-contained questions and bounded changes.
+- For delegated work, Zeus searches at most once and passes useful hits to the specialist. Reuse supplied results; search separately only if relevant history is needed but missing.
+- Use a targeted query (`top_k=2`); do not search the whole prompt by default. Missing or irrelevant results never block current work.
 
-### Summary persistence and WAL
-`memory_store()` is called automatically by Zeus when an agent returns a `subtask_summary`; include a clear `summary`. This is the only persistence path, for implementers and read-only agents alike.
-Before storing, Zeus writes `.pantheon/memory-wal/<agent>/<timestamp>.json` with `{agent, phase, summary, files_changed, status, timestamp}`. The WAL precedes storage, is recovered next session if storage fails, and expires after 7 days.
+### Persistence
+- `memory_store()` is manual, not automatic. Store at most one concise, reusable top-level result; never persist routine child summaries, phase updates, test logs, or temporary state.
+- Confirm the store succeeded before claiming persistence. There is no automatic memory WAL or recovery. Add ADRs to the memory bank only when explicitly requested.
 
 ### Relevance and permanent records
-Skip `memory_search()` results below 0.3 relevance. Delegate ADR-level architecture decisions, significant trade-offs, and pattern changes to @mnemosyne; routine summaries use auto-store.
+Ignore weak matches; routine summaries do not belong in durable memory.
 
 <!-- Source: src/instructions/yagni.instructions.md -->
 ## YAGNI Anti-overengineering

package/CHANGELOG.md

@@ -18,122 +18,59 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## ✅ Closed Issues
 
-## [v1.6.0-beta.7] - 2026-10-10
+## [v1.6.0-beta.8] - 2026-10-11
 
 <!-- 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
-
-- **Simpler agent dispatch:** answer no-change questions directly, send bounded
-  fixes to one specialist, load council instructions on demand, and remove
-  routine per-task KV/cache routing. No token, cost, or latency savings are
-  claimed without live measurements.
-- **V2 install and permissions:** use a versioned package-root plugin pin and
-  migrate V1 `task`/`write` permissions to V2 `subagent`/`edit`, retaining the
-  stricter effect when rules collide.
-- **Release and runtime hardening:** bounded in-process secret scanning,
-  fail-closed V2 registration, TUI timer disposal, truthful doctor reporting,
-  and guarded V2 sandbox prepare/reset.
-
 ## 🐞 Fixed
 
-- TUI usage polling now starts only after its optional slot registers and all
-  refresh timers are disposed on shutdown.
-- Doctor detects version drift in string and object V2 package pins, including
-  prerelease versions; checkout installs warn when their exact npm pin is not
-  published yet.
-- V2 permission migration maps `task → subagent` and `write → edit` and
-  preserves the stricter conflicting rule.
-
-## ⚠️ Known Issues
-
-- Live provider E2E is blocked by HTTP 403; an interactive model-backed V2 TUI
-  turn remains unverified.
-- The V2 tool canary targets OpenCode 2.0.22 while the installable CLI differs
-  (issue #216); V1 host end-to-end validation is also deferred.
-- The observed P0-4 tool-catalog oscillation has no reproduced cause; its
-  reproduction harness remains follow-up work.
-- V2 `init` from an unpublished source checkout writes a versioned npm pin that
-  cannot resolve until that version is published; the installer warns.
-## [v1.6.0] - 2026-10-10
+- **opencode-v2** — repair session lookup and beta sandbox reuse
+- **scripts** — isolate beta background service port
+## [v1.6.0-beta.7] - 2026-10-10
 
-This stable candidate consolidates the beta.1–beta.6 changes. The original beta
-entries remain below as historical records so release detail is not discarded.
+<!-- 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
 
-- **OpenCode V2 plugin and installer path:** generation detection, V2 plugin
-  registration, three functional V2 tools, read-only enforcement, and explicit
-  reporting of the smaller V2 feature surface. The V1 API path remains in the
-  package, but no V1 host has been exercised end-to-end in this release.
-- **Sandbox validation and release hardening:** fail-closed checks, V2 MCP and
-  hook probes, package/version inventory validation, and reproducible package
-  evidence. The sandbox now generates its runner, isolated TUI launcher, and
-  README during `--prepare`.
-- **Dependency and TUI maintenance:** synchronized release manifests, updated
-  dependency/security overrides, and TUI/runtime consistency checks.
-- **Simpler agent dispatch path:** no-change questions can be answered directly;
-  bounded fixes route to one specialist; council guidance is loaded on demand;
-  and default routing no longer makes per-task KV/cache lookups. Synthetic
-  timeout/session behavior unsupported by the host was removed. These changes
-  simplify the prompt and dispatch path; this release makes no measured token,
-  cost, or latency improvement claim.
+- **Permissões MCP nativas por agente no OpenCode V1 e V2.** O instalador
+  converte a allowlist `mcp_tools` de cada agente em regras nativas: nega por
+  padrão os servidores Pantheon omitidos, libera apenas as ferramentas
+  declaradas e preserva MCPs de terceiros. O V2 mantém os servidores
+  conectados; as regras limitam quais ferramentas cada agente vê.
+- **Guarda V2 de delegação alinhada ao contrato de permissões.** Os hooks de
+  permissão e de sessão aplicam as restrições de sessão somente-leitura e a
+  matriz caller→target sem conceder acesso além do configurado pelo host.
+- **Menos chamadas automáticas de memória e compressão.** A busca de contexto
+  do Zeus reutiliza o resultado de início de tarefa, e o protocolo de
+  compressão deixa de recomendar pipelines automáticos extensos.
+- **Prova de identidade da instalação do sandbox.** O teste global compara a
+  versão e arquivos do pacote instalado com este checkout e rejeita referências
+  npm antigas nas configurações ativas antes de validar o runtime.
+- O `--prepare` agora gera `start-pantheon.sh` para abrir o TUI interativo com o
+  beta instalado e HOME, configuração XDG, projeto e banco de dados isolados do
+  sandbox. O launcher fixa a porta do serviço gerenciado em `49376` e falha sem
+  parar serviços existentes se a porta dedicada já estiver ocupada.
 
 ## 🐞 Fixed
 
-- `PANTHEON_V2_MCP_LIST_TIMEOUT` now defaults to 15 seconds in both the harness
-  and generated `run-test.sh`, including under `set -u`; the default does not
-  depend on an exported environment variable.
-- `PANTHEON_REPO` is resolved consistently for prepare, generated tests, and
-  reset guards. Relative, dangling, missing, or non-Pantheon paths fail before
-  packaging; `.repo-dir` is atomically written and validated before use.
-- Sandbox prepare/reset reject roots overlapping a checkout or the user's
-  `HOME`. `PANTHEON_V2_PORT` defaults to 49376, is range-checked, and refuses an
-  occupied port without reusing or stopping the existing service.
-- Sandbox `tmp/` is not blanket-deleted: prepare only expires hash-named Node
-  compile-cache files owned by the current user and older than 30 days. Runtime
-  state, unknown entries, and handoff/evidence files remain untouched.
-- **V2 plugin registration is stable across install locations.** `init` now
-  writes the exact `pantheon-opencode@<version>` npm entry and the package root
-  exports the V2 plugin. This replaces absolute paths into a global prefix or
-  transient `npx` cache; `doctor` recognizes the pinned package and reports
-  version drift. A clean production-only package consumer test covers the root
-  export.
-- **V1-to-V2 permissions preserve their intended actions.** Migration maps
-  `task` to V2 `subagent` and `write` to the `edit` action that also governs
-  `write`/`patch`. If V1 `edit` and `write` rules collide on one resource, the
-  more restrictive effect wins. Tests cover global and nested agent rules.
-- **`doctor` distinguishes SQLite readiness from tool registration.** The
-  `node:sqlite` check now says it verifies only the backend prerequisite, not
-  whether `pantheon_cost` registered on the active host.
-- **Release documentation was reconciled with current code.** The V2 caller /
-  target matrix is enforced by `permission.evaluate`; the bridge export is an
-  importable utility but is not wired into production; the V2 event count and
-  package registration format are corrected in both READMEs and the install /
-  upgrade guides.
+- Referências versionadas/alias do pacote Pantheon que sobravam na lista
+  `plugins` agora são reconhecidas pelo instalador e substituídas pelo caminho
+  do plugin local correto, sem afetar plugins de terceiros com nomes parecidos.
+- A suíte CI foi separada do caminho crítico de instalação/empacotamento para
+  reduzir o tempo até o resultado das verificações do pacote.
+- O `run-test.sh` gerado agora define seu timeout do `mcp list` antes do uso
+  sob `set -u`; antes, a variável ausente interrompia o teste antes de chamar
+  o CLI. A saída do comando também fica disponível quando o gate falha.
 
 ## ⚠️ Known Issues
 
-- **V1 host canary is deferred.** The tested package dependency pair is
-  `@opencode-ai/plugin@1.18.33` + `@opencode-ai/sdk@1.18.33`; this is not an
-  end-to-end V1 host compatibility claim. No OpenCode `1.18.35` host support is
-  asserted.
-- **V2 support remains partial.** The tool canary was authored against
-  `opencode 2.0.22`; the installable CLI has drifted from that canary contract
-  (tracked in issue #216). See the README compatibility table for the measured
-  evidence and limitations.
-- **Release validation is not complete.** Live provider E2E returned HTTP 403,
-  the interactive V2 TUI/model-backed turn has not been verified, and the
-  previously observed within-session tool-catalog oscillation (P0-4) still has
-  no reproduced cause. This candidate must not be published until the host
-  validation gates are resolved or explicitly waived.
-- **V2 init from an unpublished source checkout cannot bootstrap its own npm
-  pin.** It writes the exact package version and emits a warning; OpenCode
-  cannot resolve that version until it is published. This is limited to
-  running the installer from the repository checkout. After publication, use
-  the npm-installed or `npx` installer for the supported consumer path.
-
+- **A delegação real ainda precisa de confirmação nesta beta.** O teste manual
+  anterior de `HERMES-PONG` foi negado com
+  `Pantheon delegation denied: authoritative caller session is unavailable`;
+  a correção de permissões e a instalação isolada precisam ser verificadas no
+  TUI OpenCode V2 antes de considerar a delegação validada.
 ## [v1.6.0-beta.6] - 2026-10-05
 
 &lt;!-- Add new changes here. Running `node scripts/versioning.mjs apply` will

package/README.md

@@ -54,6 +54,9 @@ project-local installation, or non-interactive setup, see the
 [installation guide](docs/INSTALLATION.md).
 The bundled Python MCP servers use the pinned MCP SDK 2.2.0 and standalone
 FastMCP 4.0.10 runtime; see the [MCP guide](docs/MCP.md).
+The installer also turns each agent's `mcp_tools` allowlist into native
+per-agent permissions for OpenCode V1 and V2; see the
+[agent MCP reference](docs/AGENT-MCP.md).
 
 ## A simple example
 
@@ -64,13 +67,6 @@ Once OpenCode is running, describe the outcome you want:
 ```
 
 Pantheon helps turn that request into a plan and a sequence of reviewed steps.
-For questions that do not require repository changes, Zeus answers directly;
-small, reversible fixes use one specialist dispatch. Discovery, planning,
-parallel work, and council review are reserved for tasks that benefit from them.
-
-For a tiny, bounded repair, invoke `@talos` directly (for example,
-`@talos fix this typo`). That skips the Zeus orchestration call; use `/pantheon`
-for planning, delegation, multi-file work, or quality gates.
 
 ## Who is it for?
 
@@ -87,12 +83,19 @@ clear handoff between stages of work.
 - Project memory that helps preserve relevant context between sessions.
 - Optional integrations for common development tasks.
 
+Memory is used selectively: the coordinator searches once only when project
+history could affect a task, then passes relevant results to specialists. Store
+one concise, reusable outcome at task completion when it will matter later;
+routine child summaries and phase updates stay in the current handoff. The
+session-checkpoint tools are separate, optional persistence APIs and are not
+called automatically by compaction hooks. See [Memory usage](docs/MEMORY.md).
+
 ## Status
 
-Candidate version: **1.6.0-beta.7**. The manifests in this checkout express a
-beta candidate, not a confirmed publication; beta publication happens only
-after the explicit Release workflow completes successfully. To check the
-published beta, consult the npm `beta` dist-tag. Pantheon is designed for OpenCode
+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
@@ -135,19 +138,18 @@ host is an unsupported mixed/wrong-generation configuration, not a supported mod
 
 ### What the OpenCode 2 path is — and is not
 
-**Not inert.** V2 registers the version-pinned npm package
-`pantheon-opencode@<version>` (pinned to the installed Pantheon version); its
-package-root export points to `src/plugin-v2.ts`.
-It registers real tools with `input`/`output` schemas via
-`ctx.tool.transform()`, five event subscriptions, session hooks, and tool/
-permission hooks for read-only enforcement and the Pantheon caller→target
-delegation matrix. For Pantheon-managed targets, Zeus may delegate to any
-registered agent; Athena and Hermes may target Apollo only; other Pantheon
-callers and unknown callers are denied. Child sessions cannot delegate to
-Pantheon agents. Native/custom targets remain under host permissions. V2 never
-adds an allow grant or overrides an explicit host deny; missing or mismatched
-identity fails closed for a Pantheon delegation. The three goal tools remain
-unsupported and are reported as `goal-tools`.
+**Not inert.** The V2 path (`src/plugin-v2`, registered as a directory because
+the V2 loader rejects bare file paths) registers real tools with real
+`input`/`output` schemas via `ctx.tool.transform()`, 5 event subscriptions,
+session hooks and tool/permission hooks that enforce read-only sessions and the
+caller→target delegation matrix. The matrix applies only to Pantheon-managed
+targets: Zeus may delegate to any registered agent; Athena and Hermes may target
+Apollo only; other Pantheon callers and unknown callers are denied. Child
+sessions cannot delegate to Pantheon agents. Calls between native/custom agents
+remain under host permissions. The V2 path never adds an allow grant or
+overrides an explicit host deny; missing or mismatched identity fails closed
+for the attempted Pantheon delegation. The 3 goal tools remain unsupported and
+are reported as `goal-tools`.
 
 **Not complete either, and the V2 support claim is currently narrowed.** Two
 facts, both recorded in this repository rather than smoothed over:
@@ -170,14 +172,14 @@ facts, both recorded in this repository rather than smoothed over:
 Treat the 1.6 line's OpenCode 2 support as **real but partial**, and do not read
 the 1.6.x row as "OpenCode 2 is finished".
 
-### Verified dependency and host evidence
+### Verified against which OpenCode versions
 
 | What | Verified against | How |
 |---|---|---|
-| V1 plugin API/generation checks | The dependency pair pinned by this release: `@opencode-ai/plugin@1.18.33` + `@opencode-ai/sdk@1.18.33` | `package.json`; generation-gate unit tests over injected host banners; installer end-to-end tests asserting the emitted `opencode.json` shape. This is not a claim that a V1 host was exercised end-to-end. |
+| V1 plugin + generation gate | The OpenCode 1.18.x line. This package pins `@opencode-ai/plugin` and `@opencode-ai/sdk` to `1.18.33`; the highest published `opencode-ai` host package (the one shipping the `opencode` binary) is `1.18.34` | Dependency pin (`package.json`); generation-gate unit tests over injected host banners; installer end-to-end tests asserting the emitted `opencode.json` shape |
 | V2 plugin tool surface | `opencode 2.0.22` (the host the canary was written against) | `tests/canary/plugin-v2-tool-canary.test.mjs`, driving `hashline_edit` through a real `opencode serve` |
 | V2 against the current installable CLI | **Not verified.** Canary fails 12/12; see issue #216 | — |
-| Exact 1.X host version exercised end-to-end | **Unverified; V1 host canary deferred.** The sandbox runner is V2-only and `--run v1` is rejected | — |
+| Exact 1.X host version the 1.6 line is exercised against end-to-end | **Unverified.** No V1 host leg exists: the sandbox runner is V2-only and `--run v1` is rejected | — |
 
 ## Delegation (native `task()`)
 
@@ -188,17 +190,27 @@ there is no Pantheon-specific delegation tool surface to configure. See
 [ADR-0011](.pantheon/memory-bank/adr/0011-delegation-engine-contract.md) for the
 historical engine contract.
 
-This 1.6.0-beta.7 candidate consolidates the final beta.6 follow-ups: safer
-V2 installation and permission migration, bounded in-process secret scanning,
-sandbox hardening, TUI lifecycle fixes, and a simpler agent dispatch path.
-Zeus answers no-change questions directly and routes bounded fixes once; the
-council procedure is loaded only for a council, without per-task KV/cache
-lookups. Runtime call counts and latency have not been measured. Live provider
-E2E and a model-backed interactive V2 TUI turn remain unverified.
-
-Transient delegation dispatch failures get at most one retry. A refusal or
-failed check is not repeated; after the retry fails, the configured fallback
-chain applies once or Zeus escalates.
+This beta.8 candidate combines native per-agent MCP permissions for OpenCode V1
+and V2, V2 delegation-permission alignment, simpler memory/compression
+instructions, and a sandbox check that proves the installed package matches
+this checkout instead of silently accepting stale npm-cached code. The isolated
+sandbox launcher also pins the OpenCode background service to its dedicated
+loopback port, rather than colliding with another OpenCode installation. The Zeus
+prompt reuses one task-start memory-search result for context and routing;
+runtime call counts and latency have not been measured. A beta.7 V2 dispatch
+failed because the permission hook passed a bare string to `ctx.session.get`
+instead of the V2 input object `{ sessionID }`; beta.8 corrects the call and
+adds contract tests for the success and failure cases. The user subsequently
+reported a successful Hermes liveness delegation in the active session, but
+freshly restarting and testing the beta.8 sandbox remains the end-to-end gate.
+The original report also included a separate `GET /api/session/{id}/permission`
+404; the session ID exists in the beta7-candidate database but not the default
+global database. Both OpenCode services were running, so the 404 in the global
+log may come from the other instance; this remains an end-to-end verification
+item.
+
+Delegated tasks get at most one retry after an initial timeout or failure. If
+that retry fails, the configured fallback or escalation chain applies.
 
 ## Cost tool backend
 
@@ -289,8 +301,8 @@ per installation; V1 and V2 Pantheon plugins must never be registered together.
 | | V1 | V2 |
 |---|---|---|
 | OpenCode config key | singular `plugin` | plural `plugins` |
-| Pantheon registration | `src/plugin.ts` plus `src/plugins/pantheon-hooks.ts` | Version-pinned npm package `pantheon-opencode@<version>` (root export loads V2) |
-| Runtime contract | Pantheon V1 plugin: 6 tools (`hashline_edit`, the 3 goal tools, `pantheon_cost`, `pantheon_model`), event/tool hooks and V1 compaction handling | V2 plugin: 3 Pantheon tools when required enforcement registers, 5 event subscriptions, session hooks (`prompt`, `context`), a read-only and secret-scanning `execute.before` hook, plus configuration transforms |
+| 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: 3 tools (`hashline_edit`, `pantheon_cost`, `pantheon_model`), 5 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 3 orchestration tools (`hashline_edit`, `pantheon_cost`,
@@ -328,41 +340,14 @@ every call. Unsupported V2 features are `legacy-hooks` (the V1-specific hook
 surface), `catalog-transform`, `integration-transform`, `skill-transform` and
 `goal-tools`.
 
-When `init --opencode-version v2` migrates a V1-shaped permission config, it
-translates `task` to the V2 `subagent` action and `write` to `edit` (which also
-covers host `write`/`patch`). If legacy `edit` and `write` rules collide on a
-resource, migration keeps the stricter effect. Hand-edited V2 configs should
-use the native top-level `permissions` array and action/resource/effect form.
-
-### Runtime secret-scanning limit
-
-V1 and V2 use the same in-process scanner on their tool `execute.before` paths.
-The scanner accepts up to **5 MiB (5,242,880 UTF-8 bytes) of serialized hook
-payload**. Larger or malformed payloads are denied fail-closed; the rejected
-payload is not written to the scanner log. This bound applies to the complete
-serialized hook payload, not just one argument field. Before calling
-`JSON.stringify`, the scanner iteratively preflights compact JSON byte size,
-including UTF-8 and JSON escapes, and stops as soon as the limit is exceeded.
-It rejects cycles, enumerable accessors and `toJSON` hooks, proxies, excessive
-nesting, and non-JSON values without serializing or logging them.
-
-V2 registers its required enforcement hook before registering Pantheon tools.
-If the host rejects that hook, startup reports `secret-scan-hook` and
-`pantheon-tools-disabled`, and Pantheon V2 tools are not registered. This does
-not disable or claim scanner coverage for native host built-in tools; those may
-remain available under the host's own policies. The opt-in timing harness is
-reproducible with `npx tsx scripts/bench-secret-scanner.ts`: it runs 3 warmups
-and 15 measured calls per size, reporting median timings for the current
-`scanSecretText` implementation on safe ASCII strings only. It excludes payload
-preflight/serialization and host-hook overhead, is not a historical or
-Bash-versus-TypeScript comparison, and makes no speedup claim. It does not print
-scan input.
-
-The package exposes both contracts as importable exports: the package root and
-`pantheon-opencode/plugin-v2` load V2; `pantheon-opencode/plugin` loads V1.
-`pantheon-opencode/v2-bridge` is currently an importable utility only:
-production setup does not wire it into the V2 plugin, so it does not provide
-runtime interoperability or restore V1 goal/board features.
+The package exposes both contracts as importable exports: `pantheon-opencode/plugin`
+(V1), `pantheon-opencode/plugin-v2` (V2) and `pantheon-opencode/v2-bridge`
+(optional interop), so a host can load either contract explicitly.
+
+The V1→V2 bridge (`src/pantheon/v2-bridge.ts`) enables optional interop:
+V1 infrastructure singletons (BackgroundJobBoard, GoalStore,
+TodoEnforcer, VisionHandler) are passed through V2 `ctx.options`. The bridge is
+optional — V2 works standalone with graceful degradation.
 
 Select the contract explicitly when installing:
 
@@ -379,8 +364,8 @@ the host in this order: an explicit `OPENCODE_VERSION=v1|v2` wins; otherwise an
 binary is asked for its `--version` and a major of 2 or more selects V2. Every
 other case — an unreadable probe, an unparseable banner, or a banner whose
 version-like tokens contradict each other with no tool name to break the tie —
-warns once and falls back to V1, because the V2-only package export is not a
-valid V1 runtime contract on an unknown 1.x host.
+warns once and falls back to V1, because a plural `plugins` directory entry on
+an unknown 1.x host loses the plugin entirely.
 
 The probe prefers the token that follows the tool name, so a runtime token
 ahead of it (`node v22.1.0 (opencode 1.18.33)`) or a trailing build date
@@ -444,9 +429,8 @@ Key order does not matter.
 One command keeps an existing installation current:
 
 ```bash
-# Without a global install, pin the intended npm dist-tag. The `latest` tag
-# reflects the most recently published stable release, not an unpublished
-# release candidate:
+# Without a global install, ALWAYS pin the dist-tag — plain `npx
+# pantheon-opencode` resolves `latest`, which is the stable release (1.4.3):
 npx pantheon-opencode@beta update            # npm beta channel + config refresh
 npx pantheon-opencode@beta update --stable   # stable channel instead
 
@@ -547,12 +531,15 @@ agent delegation. The gate is fail-closed: every required check must return an
 explicit PASS; timeouts, auth/network/provider failures and missing
 prerequisites block the run.
 
-The historical hook canary observed at least one callback on an OpenCode
-v2.0.18 host; the tool canary was written against v2.0.22. Those observations
-do not establish compatibility with the current installable `@opencode-ai/cli@beta`,
-an SDK contract for all of 2.x, or a V1 host. This release pins the V1 plugin
-dependency pair at `@opencode-ai/plugin@1.18.33` and `@opencode-ai/sdk@1.18.33`;
-the V1 host canary remains deferred.
+The runner defaults to the current stable `@opencode/cli` package and its
+`opencode2` alias; set `OPENCODE_V2_SPEC` only when a test needs a different
+host build. This keeps Pantheon beta testing separate from the OpenCode CLI
+release channel.
+
+"V2" here refers only to the hook canary observed against an OpenCode v2.0.18
+host, where at least one tested hook callback fired; it does not establish
+compatibility with the stable `@opencode/plugin@2.0.18` SDK or full 2.x
+contract. This branch still pins transitional `@opencode-ai/plugin@1.18.30`.
 On hosts where both `opencode` and `opencode2` exist, the latter is typically
 a shim that execs the same binary, so an older side-by-side comparison proved
 nothing about the binary itself. The project is V2-exclusive, so there is a
@@ -560,12 +547,13 @@ single leg.
 
 ```bash
 scripts/test-opencode-v2-sandbox.sh --prepare     # tarball + install + init in the sandbox
+~/pantheon-sandbox/start-pantheon.sh              # interactive TUI in that isolated beta sandbox
 scripts/test-opencode-v2-sandbox.sh --run v2      # base validation only
 scripts/test-opencode-v2-sandbox.sh --prompts     # base validation + prompt battery
 scripts/test-opencode-v2-sandbox.sh --rehydrate   # offline context rehydration/session-summary probe
 scripts/test-opencode-v2-sandbox.sh --hooks       # V2 hook callback canary
 scripts/test-opencode-v2-sandbox.sh --rehydrate --hooks # run both canaries
-scripts/test-opencode-v2-sandbox.sh --reset       # guarded reset of the sandbox root
+scripts/test-opencode-v2-sandbox.sh --reset       # wipe the sandbox root
 ```
 
 Modes are combinable (e.g. `--prepare --run v2 --prompts`). `--rehydrate` runs
@@ -578,20 +566,8 @@ rehydration fails, and the command returns a failing status afterward. These
 are test/sandbox canaries, not proof of Pantheon security enforcement. Binaries
 are resolved strictly inside the sandbox npm prefix — a non-prepared sandbox
 fails fast instead of silently testing the host installation. The sandbox is
-always built from the checkout this script lives in unless `PANTHEON_REPO` is
-set to an absolute path for an existing `pantheon-opencode` checkout. The same
-resolved checkout is used by prepare and the generated `run-test.sh`; dangling,
-relative, and non-Pantheon paths fail before packaging. `--prepare` generates
-`run-test.sh`, `start-pantheon.sh`, and a sandbox-local `README.md`.
-
-`PANTHEON_V2_PORT` selects the dedicated loopback port (default `49376`). The
-harness validates the port and refuses an occupied listener without reusing or
-stopping it. `PANTHEON_V2_HOST` defaults to `127.0.0.1` and rejects non-loopback
-addresses. `PANTHEON_V2_MCP_LIST_TIMEOUT` controls each `mcp list` call
-(default `15` seconds). On prepare, only hash-named Node compile-cache files
-owned by the current user and older than 30 days may expire under
-`tmp/node-compile-cache`; runtime state and unrecognized files (including
-handoff evidence) are preserved.
+always built from the checkout this script lives in; it never infers a
+repository from a sibling directory.
 
 This validates the prepared isolated sandbox only. A PASS is not proof of
 support for every real host or for host configurations that were not exercised.
@@ -610,7 +586,7 @@ Env overrides:
 |----------|---------|---------|
 | `PANTHEON_SANDBOX_ROOT` | `~/pantheon-sandbox` | Sandbox root (refused if unsafe for `--reset`) |
 | `OPENCODE_V1_SPEC` | `opencode-ai@1.18.18` | Configures the V1 plugin only; the V2-only sandbox runner does not consume or support it |
-| `OPENCODE_V2_SPEC` | `@opencode-ai/cli@beta` | npm spec providing the `opencode2` binary |
+| `OPENCODE_V2_SPEC` | `@opencode/cli@latest` | npm spec providing the `opencode2` binary |
 | `PANTHEON_SANDBOX_MODEL` | `opencode-go/mimo-v2.5` | Model used by init and prompts |
 | `PANTHEON_PROMPT_TIMEOUT` | `300` | Per-prompt timeout in seconds |