pantheon-opencode 1.6.0-beta.9 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.global.md +118 -0
- package/AGENTS.md +18 -168
- package/CHANGELOG.md +126 -376
- package/README.md +83 -610
- package/README.pt-BR.md +120 -345
- package/bin/pantheon-init.mjs +366 -132
- package/commands/pantheon-deepwork.md +14 -3
- package/commands/pantheon-vision.md +61 -12
- package/package.json +19 -11
- package/plugin.json +1 -1
- package/pyproject.toml +6 -2
- package/scripts/_pantheon_paths.py +24 -0
- package/scripts/build-agents-md.mjs +368 -69
- package/scripts/changelog-merge.mjs +161 -0
- package/scripts/check-plugin-v2-coverage.mjs +11 -8
- package/scripts/docs-check-changelog.mjs +204 -0
- package/scripts/docs-link-check.mjs +314 -0
- package/scripts/docs-media.mjs +157 -0
- package/scripts/doctor.mjs +828 -40
- package/scripts/install/agents-md.mjs +2 -2
- package/scripts/install/backup.mjs +648 -0
- package/scripts/install/cli-ui.mjs +303 -72
- package/scripts/install/component-selection.mjs +61 -0
- package/scripts/install/config-migration.mjs +583 -27
- package/scripts/install/exit-codes.mjs +26 -0
- package/scripts/install/file-inventory.mjs +555 -0
- package/scripts/install/health-check.mjs +31 -25
- package/scripts/install/interactive.mjs +78 -383
- package/scripts/install/migrate.mjs +49 -25
- package/scripts/install/model-picker.mjs +218 -250
- package/scripts/install/opencode-version.mjs +83 -21
- package/scripts/install/opencode.mjs +1413 -154
- package/scripts/install/plan-artifact.mjs +517 -0
- package/scripts/install/plan.mjs +475 -0
- package/scripts/install/plugin.mjs +214 -27
- package/scripts/install/prompt-result.mjs +2 -0
- package/scripts/install/shared.mjs +256 -99
- package/scripts/install/state.mjs +63 -8
- package/scripts/install/strings.mjs +60 -4
- package/scripts/install/venv.mjs +90 -47
- package/scripts/install/verify.mjs +128 -0
- package/scripts/install/vision-prompt.mjs +173 -0
- package/scripts/install-mcp.mjs +2 -2
- package/scripts/manifest-inventory.mjs +49 -3
- package/scripts/mcp_persistence.py +1535 -1050
- package/scripts/memory_mcp.py +12 -843
- package/scripts/node-engine-policy.mjs +85 -0
- package/scripts/package-evidence.mjs +10 -2
- package/scripts/postinstall.mjs +26 -26
- package/scripts/probe-pantheon-cost.mjs +118 -19
- package/scripts/prune.mjs +9 -3
- package/scripts/reconcile.mjs +325 -0
- package/scripts/release-gates.mjs +682 -0
- package/scripts/restore.mjs +222 -0
- package/scripts/run-node-tests.mjs +24 -8
- package/scripts/sync-artifacts.mjs +19 -7
- package/scripts/sync-tui.mjs +5 -1
- package/scripts/test-opencode-v2-sandbox.sh +36 -123
- package/scripts/uninstall.mjs +369 -34
- package/scripts/update.mjs +164 -0
- package/scripts/validate-node-engine-policy.mjs +13 -0
- package/scripts/version-check.mjs +34 -1
- package/scripts/versioning.mjs +23 -3
- package/scripts/vision-status.mjs +682 -0
- package/skills-lock.json +8 -8
- package/src/agents/aphrodite.md +13 -10
- package/src/agents/apollo.md +4 -5
- package/src/agents/athena.md +74 -46
- package/src/agents/demeter.md +10 -7
- package/src/agents/gaia.md +0 -1
- package/src/agents/hephaestus.md +4 -3
- package/src/agents/hermes.md +10 -9
- package/src/agents/iris.md +6 -1
- package/src/agents/mnemosyne.md +10 -4
- package/src/agents/nyx.md +4 -4
- package/src/agents/prometheus.md +12 -11
- package/src/agents/talos.md +6 -0
- package/src/agents/zeus.md +84 -56
- package/src/instructions/agent-return-format.instructions.md +12 -41
- package/src/instructions/memory-protocol.instructions.md +5 -11
- package/src/instructions/test-economy.instructions.md +12 -0
- package/src/instructions/yagni.instructions.md +6 -15
- package/src/instructions/zeus-anti-stall.instructions.md +6 -6
- package/src/instructions/zeus-communication-rules.instructions.md +6 -6
- package/src/instructions/zeus-council-synthesis.instructions.md +11 -12
- package/src/instructions/zeus-memory-operations.instructions.md +13 -7
- package/src/instructions/zeus-timeout-retry.instructions.md +36 -10
- package/src/mcp/_pantheon_paths.py +24 -0
- package/src/mcp/mcp_codemap_module.py +86 -18
- package/src/mcp/mcp_persistence.py +1535 -1050
- package/src/mcp/memory_mcp.py +444 -94
- package/src/mcp/pantheon_vision.py +285 -41
- package/src/mcp/requirements-mcp.txt +5 -0
- package/src/pantheon/context-pruner.ts +541 -0
- package/src/pantheon/cost-command.ts +814 -60
- package/src/pantheon/goal-loop.ts +11 -8
- package/src/pantheon/memory-context.ts +1017 -0
- package/src/pantheon/model-agents.ts +19 -0
- package/src/pantheon/model-command.ts +218 -56
- package/src/pantheon/model-pricing.ts +536 -0
- package/src/pantheon/presets.mjs +2 -0
- package/src/pantheon/task-result-guard.ts +50 -14
- package/src/pantheon/v2-bounded-read.ts +640 -0
- package/src/pantheon/v2-delegation-enforce.ts +133 -6
- package/src/pantheon/v2-execute-after.ts +135 -24
- package/src/pantheon/v2-model-overrides.ts +275 -0
- package/src/pantheon/v2-tools.ts +89 -35
- package/src/pantheon/v2-unsupported.mjs +2 -3
- package/src/pantheon/v2-vision.ts +622 -0
- package/src/pantheon/vision-local.ts +531 -0
- package/src/pantheon/vision.ts +1160 -115
- package/src/plugin-v2.ts +654 -162
- package/src/plugin.ts +15 -11
- package/src/plugins/tui/dist/tui-v2.d.ts +1029 -2
- package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
- package/src/plugins/tui/dist/tui-v2.js +3742 -85
- package/src/plugins/tui/dist/tui.js +1 -1
- package/src/plugins/tui/package-lock.json +6 -6
- package/src/plugins/tui/package.json +5 -4
- package/src/plugins/tui/src/index-v2.tsx +4314 -50
- package/src/plugins/tui/tsconfig.typecheck.json +5 -0
- package/src/routing.yml +50 -5
- package/src/skills/agent-coordination/SKILL.md +7 -2
- package/src/skills/artifact-management/SKILL.md +5 -1
- package/src/skills/auto-continue/SKILL.md +14 -6
- package/src/skills/codemap/SKILL.md +1 -1
- package/src/skills/memory-bank/SKILL.md +21 -13
- package/src/skills/session-goal/SKILL.md +12 -22
- package/src/skills/spec-driven-development/SKILL.md +3 -1
- package/src/skills/worktrees/SKILL.md +30 -11
- package/scripts/probe-context-rehydrate.mjs +0 -263
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
**A clearer way to work with OpenCode on real software projects.** Pantheon
|
|
4
4
|
brings planning, implementation, review, and documentation into one guided
|
|
5
|
-
experience. It is an OpenCode plugin and installer for
|
|
5
|
+
experience. It is an OpenCode plugin and installer for developers and teams who
|
|
6
6
|
want useful structure without giving up control of their code.
|
|
7
7
|
|
|
8
8
|
[Português (Brasil)](README.pt-BR.md) ·
|
|
@@ -14,9 +14,10 @@ want useful structure without giving up control of their code.
|
|
|
14
14
|
|
|
15
15
|
## What is it?
|
|
16
16
|
|
|
17
|
-
Pantheon is a companion for [OpenCode](https://opencode.ai/) that helps you
|
|
18
|
-
|
|
19
|
-
|
|
17
|
+
Pantheon is a companion for [OpenCode](https://opencode.ai/) that helps you move
|
|
18
|
+
from an idea to a reviewed change. Fourteen specialized agents share one
|
|
19
|
+
workflow: plan, implement, check, review, and record what mattered. You stay in
|
|
20
|
+
charge of every decision and every merge.
|
|
20
21
|
|
|
21
22
|
## Why use it?
|
|
22
23
|
|
|
@@ -25,22 +26,18 @@ way to plan work, make progress, check results, and keep useful project context.
|
|
|
25
26
|
finished.
|
|
26
27
|
- **A repeatable starting point:** use the same setup across projects and
|
|
27
28
|
collaborators.
|
|
28
|
-
- **You stay in charge:** Pantheon supports your
|
|
29
|
-
|
|
29
|
+
- **You stay in charge:** Pantheon supports your judgment; it does not replace
|
|
30
|
+
it.
|
|
31
|
+
- **Right-sized coordination:** bounded work goes to one specialist; planning,
|
|
32
|
+
discovery, parallel work, and review are added when scope and risk call for
|
|
33
|
+
them. `/pantheon-deepwork` remains the checkpointed workflow for heavy
|
|
34
|
+
multi-phase work.
|
|
30
35
|
|
|
31
36
|
## Start in 2 minutes
|
|
32
37
|
|
|
33
|
-
Requirements: [OpenCode
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
[Compatibility and support policy](#compatibility-and-support-policy).
|
|
37
|
-
|
|
38
|
-
Pantheon declares `engines.node` as `^22.22.2 || ^24.15.0 || >=26.0.0`. The
|
|
39
|
-
floor reflects what the dependency tree actually needs — the transitive
|
|
40
|
-
`ini@7` rejects earlier 22.x/24.x builds with `EBADENGINE` — and odd-numbered
|
|
41
|
-
Node releases (23, 25) are out of range. The `pantheon_cost` tool also needs
|
|
42
|
-
`node:sqlite`, which requires Node >= 22.5; `doctor` warns when the running
|
|
43
|
-
runtime cannot load it.
|
|
38
|
+
Requirements: [OpenCode](https://opencode.ai/docs/) **1.19.x** (V1) or **OpenCode
|
|
39
|
+
2.x** (V2), and Node.js **>=26.4.0** for the CLI and tooling. **OpenCode 2.0.22
|
|
40
|
+
is known broken**; see [Compatibility](docs/COMPATIBILITY.md).
|
|
44
41
|
|
|
45
42
|
From the project where you want to use Pantheon:
|
|
46
43
|
|
|
@@ -49,635 +46,111 @@ npx pantheon-opencode init
|
|
|
49
46
|
opencode
|
|
50
47
|
```
|
|
51
48
|
|
|
52
|
-
|
|
53
|
-
project-local installation, or non-interactive setup, see the
|
|
54
|
-
[installation guide](docs/INSTALLATION.md).
|
|
55
|
-
The bundled Python MCP servers use the pinned MCP SDK 2.2.0 and standalone
|
|
56
|
-
FastMCP 4.0.10 runtime; see the [MCP guide](docs/MCP.md).
|
|
57
|
-
The installer also turns each agent's `mcp_tools` allowlist into native
|
|
58
|
-
per-agent permissions for OpenCode V1 and V2; see the
|
|
59
|
-
[agent MCP reference](docs/AGENT-MCP.md).
|
|
60
|
-
|
|
61
|
-
## A simple example
|
|
62
|
-
|
|
63
|
-
Once OpenCode is running, describe the outcome you want:
|
|
49
|
+
Then describe the outcome you want:
|
|
64
50
|
|
|
65
51
|
```text
|
|
66
52
|
/pantheon Add CSV export to the reports page, including tests and a review.
|
|
67
53
|
```
|
|
68
54
|
|
|
69
|
-
|
|
55
|
+
When you ask for a plan, Athena returns it to Zeus, who displays it in the main
|
|
56
|
+
conversation before asking for approval — never as a plan hidden in a child
|
|
57
|
+
agent's conversation.
|
|
70
58
|
|
|
71
|
-
|
|
59
|
+
Restart OpenCode after installing or changing the plugin generation. The
|
|
60
|
+
installer selects one generation per installation; V1 and V2 plugins are never
|
|
61
|
+
registered together.
|
|
72
62
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
63
|
+
Installer flags, exit codes, saved plans, backup and restore, uninstall,
|
|
64
|
+
reconcile, and MCP pins are in the [installation guide](docs/INSTALLATION.md).
|
|
65
|
+
For the first ten minutes only — `init` → restart → `/dispatch` → first result —
|
|
66
|
+
see [Quick Start](docs/QUICKSTART.md).
|
|
77
67
|
|
|
78
|
-
## What
|
|
68
|
+
## What's included?
|
|
79
69
|
|
|
80
|
-
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
-
|
|
70
|
+
- **14 specialized agents** with one orchestrator, implementation specialists,
|
|
71
|
+
a quality gate, and supporting roles.
|
|
72
|
+
- **20 skills** and reusable instructions for planning, building, reviewing,
|
|
73
|
+
and documenting work.
|
|
74
|
+
- **5 local MCP servers** for project memory, persistence, resources, confined
|
|
75
|
+
script execution, and vision.
|
|
76
|
+
- **An optional TUI** with a dispatch sidebar block and a full-width
|
|
77
|
+
`/dispatch` panel.
|
|
85
78
|
|
|
86
79
|
Memory is used selectively: the coordinator searches once only when project
|
|
87
80
|
history could affect a task, then passes relevant results to specialists. Store
|
|
88
81
|
one concise, reusable outcome at task completion when it will matter later;
|
|
89
|
-
routine child summaries
|
|
90
|
-
session-checkpoint tools are separate, optional persistence APIs and are not
|
|
91
|
-
called automatically by compaction hooks. See [Memory usage](docs/MEMORY.md).
|
|
92
|
-
|
|
93
|
-
## Status
|
|
94
|
-
|
|
95
|
-
Candidate version: the manifests in this checkout express the version being
|
|
96
|
-
prepared, not a confirmed publication. A beta is published only after the
|
|
97
|
-
Release workflow completes successfully. To check which version is actually
|
|
98
|
-
published, consult the npm `beta` dist-tag. Pantheon is designed for OpenCode
|
|
99
|
-
and depends on the availability and configuration of OpenCode and any optional
|
|
100
|
-
services you choose to use. Check the
|
|
101
|
-
[releases](https://github.com/ils15/pantheon-opencode/releases) and
|
|
102
|
-
[changelog](CHANGELOG.md) for the latest published changes.
|
|
103
|
-
|
|
104
|
-
## Compatibility and support policy
|
|
105
|
-
|
|
106
|
-
> ### ⚠️ 1.6.x is the LAST line that supports OpenCode 1.X
|
|
107
|
-
>
|
|
108
|
-
> **OpenCode 1.X support ends after the 1.6 line.** From **1.7 onward, every
|
|
109
|
-
> release is a breaking change targeting OpenCode 2.** A 1.6.x install is the
|
|
110
|
-
> last one that runs on an OpenCode 1.X host; do not plan an upgrade across the
|
|
111
|
-
> 1.6 → 1.7 boundary while your host is still on OpenCode 1.X.
|
|
112
|
-
|
|
113
|
-
| Pantheon line | OpenCode 1.X host | OpenCode 2 host |
|
|
114
|
-
|---|---|---|
|
|
115
|
-
| **1.6.x** (current line) | **Supported.** V1 plugin contract | Supported, reduced surface — V2 contract |
|
|
116
|
-
| **1.7 and later** | **Not supported.** Breaking change | Target of the 1.7+ work |
|
|
117
|
-
|
|
118
|
-
Both columns of the 1.6.x row are real, and they are not the same claim. Read
|
|
119
|
-
[the plugin contract](#opencode-v1v2--dual-version-160-beta1) for what each
|
|
120
|
-
generation actually registers.
|
|
121
|
-
|
|
122
|
-
### What "supported on OpenCode 1.X" concretely means
|
|
123
|
-
|
|
124
|
-
On the 1.6 line, an OpenCode 1.X host gets the **V1 plugin**:
|
|
125
|
-
`src/plugin.ts` plus `src/plugins/pantheon-hooks.ts`, registered under the
|
|
126
|
-
singular `plugin` config key. That surface registers 6 tools
|
|
127
|
-
(`hashline_edit`, the 3 `pantheon_goal_*` tools, `pantheon_cost`,
|
|
128
|
-
`pantheon_model`), the BackgroundJobBoard lifecycle, the V1 event/tool hooks and
|
|
129
|
-
the V1 compaction path. It is selected automatically: the generation gate
|
|
130
|
-
(`--opencode-version`, else `OPENCODE_VERSION`, else a `OPENCODE_BIN` basename of
|
|
131
|
-
`opencode2`, else a `--version` probe where major ≥ 2 selects V2) resolves a 1.X
|
|
132
|
-
host to V1.
|
|
133
|
-
|
|
134
|
-
The two generations are exclusive. The installer strips Pantheon references from
|
|
135
|
-
both config shapes and registers only the selected one, so a 1.X host never
|
|
136
|
-
loads the V2 plugin and a V2 host never loads the V1 plugin. Forcing V2 on a 1.X
|
|
137
|
-
host is an unsupported mixed/wrong-generation configuration, not a supported mode.
|
|
138
|
-
|
|
139
|
-
### What the OpenCode 2 path is — and is not
|
|
140
|
-
|
|
141
|
-
**Not inert.** The V2 path (`src/plugin-v2`, registered as a directory because
|
|
142
|
-
the V2 loader rejects bare file paths) registers real tools with real
|
|
143
|
-
`input`/`output` schemas via `ctx.tool.transform()`, 5 event subscriptions,
|
|
144
|
-
session hooks and tool/permission hooks that enforce read-only sessions and the
|
|
145
|
-
caller→target delegation matrix. The matrix applies only to Pantheon-managed
|
|
146
|
-
targets: Zeus may delegate to any registered agent; Athena and Hermes may target
|
|
147
|
-
Apollo only; other Pantheon callers and unknown callers are denied. Child
|
|
148
|
-
sessions cannot delegate to Pantheon agents. Calls between native/custom agents
|
|
149
|
-
remain under host permissions. The V2 path never adds an allow grant or
|
|
150
|
-
overrides an explicit host deny; missing or mismatched identity fails closed
|
|
151
|
-
for the attempted Pantheon delegation. The 3 goal tools remain unsupported and
|
|
152
|
-
are reported as `goal-tools`.
|
|
153
|
-
|
|
154
|
-
**Not complete either, and the V2 support claim is currently narrowed.** Two
|
|
155
|
-
facts, both recorded in this repository rather than smoothed over:
|
|
156
|
-
|
|
157
|
-
- **The host-backed V2 gate is red on the installable OpenCode CLI.** The V2 tool
|
|
158
|
-
canary (`tests/canary/plugin-v2-tool-canary.test.mjs`) was written against
|
|
159
|
-
`opencode 2.0.22`, which no npm channel publishes. Against the installable
|
|
160
|
-
`@opencode-ai/cli` host, `/api/experimental/session/{id}/wait` has been
|
|
161
|
-
promoted to `/api/session/{id}/wait` (the old path 404s) and `ctx.tool.list`
|
|
162
|
-
is absent, so the canary fails 12/12 there. That is a canary/host-generation
|
|
163
|
-
mismatch, not a measured plugin regression — with only the route renamed, 10/12
|
|
164
|
-
pass on the same host, including the edit being applied and the mutant still
|
|
165
|
-
caught. Tracked as [issue
|
|
166
|
-
#216](https://github.com/ils15/pantheon-opencode/issues/216); the fail-closed
|
|
167
|
-
CI change is [PR #213](https://github.com/ils15/pantheon-opencode/pull/213).
|
|
168
|
-
- **The 2.x host claims in `src/plugin-v2.ts` are measured against `2.0.22`
|
|
169
|
-
specifically**, not against the current installable CLI. Re-measurement
|
|
170
|
-
against the current host is outstanding and is tracked in the same issue.
|
|
171
|
-
|
|
172
|
-
Treat the 1.6 line's OpenCode 2 support as **real but partial**, and do not read
|
|
173
|
-
the 1.6.x row as "OpenCode 2 is finished".
|
|
174
|
-
|
|
175
|
-
### Verified against which OpenCode versions
|
|
176
|
-
|
|
177
|
-
| What | Verified against | How |
|
|
178
|
-
|---|---|---|
|
|
179
|
-
| 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 |
|
|
180
|
-
| 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` |
|
|
181
|
-
| V2 against the current installable CLI | **Not verified.** Canary fails 12/12; see issue #216 | — |
|
|
182
|
-
| 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 | — |
|
|
183
|
-
|
|
184
|
-
## Delegation (native `task()`)
|
|
185
|
-
|
|
186
|
-
Pantheon delegates exclusively through OpenCode's native `task()` child-session
|
|
187
|
-
engine. The former custom `pantheon_delegate` tool and the V1 delegation engine
|
|
188
|
-
(`delegation.ts`, `delegate-manager.ts` and supporting modules) were removed;
|
|
189
|
-
there is no Pantheon-specific delegation tool surface to configure. See
|
|
190
|
-
[ADR-0011](.pantheon/memory-bank/adr/0011-delegation-engine-contract.md) for the
|
|
191
|
-
historical engine contract.
|
|
192
|
-
|
|
193
|
-
This beta.8 candidate combines native per-agent MCP permissions for OpenCode V1
|
|
194
|
-
and V2, V2 delegation-permission alignment, simpler memory/compression
|
|
195
|
-
instructions, and a sandbox check that proves the installed package matches
|
|
196
|
-
this checkout instead of silently accepting stale npm-cached code. The isolated
|
|
197
|
-
sandbox launcher also pins the OpenCode background service to its dedicated
|
|
198
|
-
loopback port, rather than colliding with another OpenCode installation. The Zeus
|
|
199
|
-
prompt reuses one task-start memory-search result for context and routing;
|
|
200
|
-
runtime call counts and latency have not been measured. A beta.7 V2 dispatch
|
|
201
|
-
failed because the permission hook passed a bare string to `ctx.session.get`
|
|
202
|
-
instead of the V2 input object `{ sessionID }`; beta.8 corrects the call and
|
|
203
|
-
adds contract tests for the success and failure cases. The user subsequently
|
|
204
|
-
reported a successful Hermes liveness delegation in the active session, but
|
|
205
|
-
freshly restarting and testing the beta.8 sandbox remains the end-to-end gate.
|
|
206
|
-
The original report also included a separate `GET /api/session/{id}/permission`
|
|
207
|
-
404; the session ID exists in the beta7-candidate database but not the default
|
|
208
|
-
global database. Both OpenCode services were running, so the 404 in the global
|
|
209
|
-
log may come from the other instance; this remains an end-to-end verification
|
|
210
|
-
item.
|
|
211
|
-
|
|
212
|
-
Delegated tasks get at most one retry after an initial timeout or failure. If
|
|
213
|
-
that retry fails, the configured fallback or escalation chain applies.
|
|
214
|
-
|
|
215
|
-
## Cost tool backend
|
|
216
|
-
|
|
217
|
-
`pantheon_cost` prefers a read-only `node:sqlite` backend against the selected
|
|
218
|
-
`opencode.db`. When `node:sqlite` is unavailable in the host runtime (for
|
|
219
|
-
example under Bun), the tool falls back to spawning `node scripts/cost.mjs` as
|
|
220
|
-
a read-only subprocess. The fallback resolves a real Node.js binary —
|
|
221
|
-
`PANTHEON_NODE` first, then `node` on `PATH` — verifies it supports
|
|
222
|
-
`node:sqlite` (Node.js >= 22.5), and runs the script with an argument array,
|
|
223
|
-
never a shell. If neither source resolves, the tool returns `status:
|
|
224
|
-
UNSUPPORTED`. Database failures return a contract status such as `UNAVAILABLE`
|
|
225
|
-
or `CORRUPT_DATA` and include diagnostic detail, including captured stderr when
|
|
226
|
-
available.
|
|
227
|
-
|
|
228
|
-
| Variable | Default | Purpose |
|
|
229
|
-
|----------|---------|---------|
|
|
230
|
-
| `PANTHEON_NODE` | `node` from `PATH` | Path to a Node.js >= 22.5 binary used by the CLI fallback; an explicit path must exist and be executable, otherwise the tool fails fast instead of ignoring the override |
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
## Code-mode execution (explicit opt-in)
|
|
234
|
-
|
|
235
|
-
Scripts run through the `pantheon-code-mode` MCP server (`execute_code_script`)
|
|
236
|
-
only when they are explicitly approved. Approval is recorded in
|
|
237
|
-
`.pantheon/code-mode/manifest.json` with the SHA-256 of each script:
|
|
238
|
-
|
|
239
|
-
```json
|
|
240
|
-
{
|
|
241
|
-
"version": 1,
|
|
242
|
-
"scripts": {
|
|
243
|
-
"example-sync.sh": "<sha256>"
|
|
244
|
-
}
|
|
245
|
-
}
|
|
246
|
-
```
|
|
247
|
-
|
|
248
|
-
- **No manifest → nothing executes.** A missing manifest returns
|
|
249
|
-
`INVALID_STATE`; scripts are never run implicitly.
|
|
250
|
-
- **Not listed → `CONFLICT`.** The script must be approved first.
|
|
251
|
-
- **Hash mismatch → `CORRUPT_DATA`.** The SHA-256 of the file on disk must
|
|
252
|
-
match the manifest entry, so edits after approval are detected.
|
|
253
|
-
|
|
254
|
-
Session persistence is provided by the persistence MCP server. The bundled
|
|
255
|
-
code-mode payload contains execution helpers only and does not export or back
|
|
256
|
-
up a database.
|
|
257
|
-
|
|
258
|
-
Approve or re-approve a script with the `approve_code_script` MCP tool:
|
|
259
|
-
|
|
260
|
-
```
|
|
261
|
-
approve_code_script("checkpoint-session.sh")
|
|
262
|
-
```
|
|
263
|
-
|
|
264
|
-
The installer seeds the manifest with the SHA-256 of every bundled script, so
|
|
265
|
-
shipped scripts stay approved across installs. Re-run `approve_code_script`
|
|
266
|
-
after intentionally editing a script. Status codes follow the shared nine-code
|
|
267
|
-
contract (`OK`, `UNSUPPORTED`, `UNAVAILABLE`, `INVALID_INPUT`, `INVALID_STATE`,
|
|
268
|
-
`CONFLICT`, `CORRUPT_DATA`, `TIMEOUT`, `ESCALATE`); with `json_output=true`,
|
|
269
|
-
results carry a `status` field.
|
|
270
|
-
|
|
271
|
-
Code-mode resolves project-first: `.opencode/.pantheon/code-mode` is preferred,
|
|
272
|
-
then `.pantheon/code-mode`. `PANTHEON_PROJECT` overrides the working directory,
|
|
273
|
-
and the installed MCP uses `cwd: "."` so OpenCode supplies the workspace. A
|
|
274
|
-
global directory is used only when no usable project directory is available;
|
|
275
|
-
once a project directory is selected, a missing or corrupt manifest fails
|
|
276
|
-
closed instead of falling back. `doctor` validates the manifest and every
|
|
277
|
-
script's SHA-256 without regenerating it.
|
|
278
|
-
|
|
279
|
-
The local `.pantheon/code-mode/eval-*.py` helpers and any Promptfoo/evaluation
|
|
280
|
-
assets are development-only inputs and are excluded from the npm tarball and
|
|
281
|
-
from the runtime manifest. `src/mcp/eval_store.py` is different: it is a
|
|
282
|
-
shipped runtime dependency of the MCP resources server, not an evaluation
|
|
283
|
-
asset, so it remains packaged.
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
## What's new in 1.6.0-beta.1
|
|
287
|
-
|
|
288
|
-
- First beta compatible with the OpenCode 2 plugin contract.
|
|
289
|
-
- Removed the legacy vector-memory pipeline while preserving SQLite FTS5/BM25
|
|
290
|
-
keyword search and the `code_*` codemap tools.
|
|
291
|
-
- CI and release validation are fail-closed; `doctor` checks and the V2-only
|
|
292
|
-
sandbox validator cover the OpenCode 2 installation path.
|
|
293
|
-
|
|
294
|
-
## OpenCode V1/V2 — Dual Version (1.6.0-beta.1)
|
|
295
|
-
|
|
296
|
-
This is the first beta compatible with OpenCode 2. Pantheon has two **exclusive** OpenCode
|
|
297
|
-
plugin contracts. Ordinary OpenCode
|
|
298
|
-
configuration may be shared, but the Pantheon plugin registration is selected
|
|
299
|
-
per installation; V1 and V2 Pantheon plugins must never be registered together.
|
|
300
|
-
|
|
301
|
-
| | V1 | V2 |
|
|
302
|
-
|---|---|---|
|
|
303
|
-
| OpenCode config key | singular `plugin` | plural `plugins` |
|
|
304
|
-
| Pantheon registration | `src/plugin.ts` plus `src/plugins/pantheon-hooks.ts` | `<installed>/src/plugin-v2` directory (`index.ts` re-exports `src/plugin-v2.ts`) |
|
|
305
|
-
| 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 |
|
|
306
|
-
| V1 APIs | Registered | Own tool definitions via `ctx.tool.transform()` — not the V1 plugin path |
|
|
307
|
-
|
|
308
|
-
The V2 plugin provides 3 orchestration tools (`hashline_edit`, `pantheon_cost`,
|
|
309
|
-
`pantheon_model`), 5 event subscriptions (`session.created`, `session.idle`,
|
|
310
|
-
`session.deleted`, `session.error`, `session.compacted`), session hooks
|
|
311
|
-
(`prompt`, `context`),
|
|
312
|
-
and a tool `execute.before` hook that enforces read-only sessions. The 3 goal
|
|
313
|
-
tools are **not**
|
|
314
|
-
registered on V2: the goal loop needs a `GoalStore`, a `GoalLoopClient` and a
|
|
315
|
-
`BackgroundJobBoard`, none of which the V2 `PluginContext` exposes, so the gap
|
|
316
|
-
is reported as the `goal-tools` unsupported-feature marker. Use the V1
|
|
317
|
-
contract if you need the goal loop.
|
|
318
|
-
|
|
319
|
-
The V2 `execute.before` hook is the read-only enforcement point for that
|
|
320
|
-
surface: the host includes the active agent on the event, a read-only agent
|
|
321
|
-
(`apollo`, `gaia`) registers its session, and the shared
|
|
322
|
-
`createEnforcementGuard` throws to deny `edit`, `write`, `bash`, `task`,
|
|
323
|
-
`hashline_edit` and `pantheon_model`. It does **not** rely on the V1
|
|
324
|
-
`tool.execute.before` hook, which lives in `src/plugin.ts` and is not loaded
|
|
325
|
-
when only `plugin-v2` is configured. The `permission.evaluate` hook enforces
|
|
326
|
-
the V2 caller/target matrix for Pantheon-managed targets across every entry in
|
|
327
|
-
the host's `resources` array. Native-only resources pass through unchanged to
|
|
328
|
-
OpenCode's permission policy; mixed native/Pantheon requests and multi-target
|
|
329
|
-
requests are denied unless every Pantheon target is explicitly allowed for the
|
|
330
|
-
authoritative caller. Explicit host denies remain final, and missing or
|
|
331
|
-
unknown resource data fails closed. If a denied evaluation has no mutable host
|
|
332
|
-
output argument, the hook throws to fail closed rather than silently omitting
|
|
333
|
-
the denial. V2 `execute.after` runs the completed-result chain:
|
|
334
|
-
`task-result-guard` → `context-sandbox` → `read-enhancer`.
|
|
335
|
-
|
|
336
|
-
Every V2 tool declares an `output` schema. OpenCode 2.0.x requires the
|
|
337
|
-
declaration and the resolved result to agree in both directions, so an
|
|
338
|
-
undeclared tool — or one that returns `output` without declaring it — fails on
|
|
339
|
-
every call. Unsupported V2 features are `legacy-hooks` (the V1-specific hook
|
|
340
|
-
surface), `catalog-transform`, `integration-transform`, `skill-transform` and
|
|
341
|
-
`goal-tools`.
|
|
342
|
-
|
|
343
|
-
The package exposes both contracts as importable exports: `pantheon-opencode/plugin`
|
|
344
|
-
(V1), `pantheon-opencode/plugin-v2` (V2) and `pantheon-opencode/v2-bridge`
|
|
345
|
-
(optional interop), so a host can load either contract explicitly.
|
|
346
|
-
|
|
347
|
-
The V1→V2 bridge (`src/pantheon/v2-bridge.ts`) enables optional interop:
|
|
348
|
-
V1 infrastructure singletons (BackgroundJobBoard, GoalStore,
|
|
349
|
-
TodoEnforcer, VisionHandler) are passed through V2 `ctx.options`. The bridge is
|
|
350
|
-
optional — V2 works standalone with graceful degradation.
|
|
351
|
-
|
|
352
|
-
Select the contract explicitly when installing:
|
|
353
|
-
|
|
354
|
-
```bash
|
|
355
|
-
npx pantheon-opencode init --opencode-version v1
|
|
356
|
-
npx pantheon-opencode init --opencode-version v2
|
|
357
|
-
npx pantheon-opencode init --opencode-version auto
|
|
358
|
-
```
|
|
359
|
-
|
|
360
|
-
`auto` is the default. `--version v1|v2|auto` is accepted as the older
|
|
361
|
-
selector spelling when used after `init`. `auto` resolves the generation from
|
|
362
|
-
the host in this order: an explicit `OPENCODE_VERSION=v1|v2` wins; otherwise an
|
|
363
|
-
`OPENCODE_BIN` path ending in `opencode2` selects V2; otherwise the host
|
|
364
|
-
binary is asked for its `--version` and a major of 2 or more selects V2. Every
|
|
365
|
-
other case — an unreadable probe, an unparseable banner, or a banner whose
|
|
366
|
-
version-like tokens contradict each other with no tool name to break the tie —
|
|
367
|
-
warns once and falls back to V1, because a plural `plugins` directory entry on
|
|
368
|
-
an unknown 1.x host loses the plugin entirely.
|
|
369
|
-
|
|
370
|
-
The probe prefers the token that follows the tool name, so a runtime token
|
|
371
|
-
ahead of it (`node v22.1.0 (opencode 1.18.33)`) or a trailing build date
|
|
372
|
-
(`opencode v1.18.33 built 2026.10.04`) cannot flip the generation. The
|
|
373
|
-
installer removes Pantheon references from both config shapes before writing
|
|
374
|
-
only the selected Pantheon registration. Third-party entries are not converted
|
|
375
|
-
or claimed by this rule.
|
|
376
|
-
|
|
377
|
-
The `pantheon_cost` report resolves its database by PATH, in this order: an
|
|
378
|
-
explicit `dbPath` supplied by the tool caller, then
|
|
379
|
-
`PANTHEON_COST_DB=/absolute/path/to/opencode.db`, then `OPENCODE_DB`, then the
|
|
380
|
-
XDG default `opencode.db`. There is no per-version filename in that chain:
|
|
381
|
-
`opencode-v2.db` is not a host 2.x database — it is the name a sandbox gives
|
|
382
|
-
its own state database through `OPENCODE_DB`.
|
|
383
|
-
|
|
384
|
-
The v1/v2 distinction is the DETECTED SCHEMA, not the file name. The report
|
|
385
|
-
looks for the `message` and `session_message` tables and reads whichever the
|
|
386
|
-
open database actually holds, because a migrated database carries both
|
|
387
|
-
families at once. `PANTHEON_OPENCODE_VERSION=v1|v2` selects no file: it only
|
|
388
|
-
narrows an already-detected set to one table family, and fails fast when the
|
|
389
|
-
value is neither `v1` nor `v2` or when the requested family is not there. Left
|
|
390
|
-
unset, every detected family is read. A database carrying neither table comes
|
|
391
|
-
back as an actionable error (`CORRUPT_DATA`), and a ledger that exists but
|
|
392
|
-
yields no readable tokens as `UNSUPPORTED` — never as a successful empty
|
|
393
|
-
report.
|
|
394
|
-
|
|
395
|
-
The installer still writes the compatibility settings required by the selected
|
|
396
|
-
OpenCode host, such as `experimental.subagent_depth`; this does not convert a
|
|
397
|
-
V1 plugin into V2 or provide V2 with V1 hooks.
|
|
398
|
-
|
|
399
|
-
Pantheon does not set a step ceiling on agents. On OpenCode 2 the `steps`
|
|
400
|
-
field is optional and has no default: absent means the host applies no native
|
|
401
|
-
limit. A config written before this change still carries the old value, and the
|
|
402
|
-
V2 install path strips it from every agent Pantheon manages — an agent you
|
|
403
|
-
define yourself is never touched, and the retiring V1 singular `agent` block
|
|
404
|
-
is left alone. Run the installer once to clear a stale value from an existing
|
|
405
|
-
config:
|
|
82
|
+
routine child summaries stay in the handoff. See [Memory](docs/MEMORY.md).
|
|
406
83
|
|
|
407
|
-
|
|
408
|
-
npx pantheon-opencode init --opencode-version=v2
|
|
409
|
-
```
|
|
410
|
-
|
|
411
|
-
Context control is not a Pantheon setting. Whatever budget an agent runs
|
|
412
|
-
against comes from the compaction settings of the OpenCode host you are
|
|
413
|
-
running, and Pantheon does not define them.
|
|
84
|
+
## Compatibility
|
|
414
85
|
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
framework-managed fields from the V1 block overwrite, and your own fields are
|
|
419
|
-
preserved, matching the precedence the installer already applies elsewhere.
|
|
420
|
-
Key order does not matter.
|
|
86
|
+
OpenCode **1.19.x** (V1 plugin) and **OpenCode 2.x** (V2 plugin) are supported.
|
|
87
|
+
**OpenCode 2.0.22 is known broken.** From 1.7 onward the line drops the V1
|
|
88
|
+
contract and targets OpenCode 2 only.
|
|
421
89
|
|
|
422
|
-
|
|
90
|
+
The support policy, the known-broken exception, and the verified-version
|
|
91
|
+
evidence have exactly one home: [Compatibility](docs/COMPATIBILITY.md).
|
|
423
92
|
|
|
424
|
-
|
|
425
|
-
> before upgrading across a line boundary.** 1.6.x is the last line that
|
|
426
|
-
> supports an OpenCode 1.X host; 1.7+ is breaking-change territory targeting
|
|
427
|
-
> OpenCode 2. Within the 1.6 line, `update` is the supported path.
|
|
93
|
+
## Delegation
|
|
428
94
|
|
|
429
|
-
|
|
95
|
+
Pantheon delegates through the host's native child-session engine: `subagent`
|
|
96
|
+
in the user-reported root runtime, referred to as `task()` in host/API
|
|
97
|
+
documentation. Tool availability, background support, and completion
|
|
98
|
+
observability are runtime-dependent; when completion is not observable, use
|
|
99
|
+
synchronous dispatch or wait for a host notification.
|
|
430
100
|
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
101
|
+
Every root dispatch carries a concise handoff brief — objective, bounded scope,
|
|
102
|
+
relevant inputs, constraints, expected return format, and verification. Work is
|
|
103
|
+
routed qualitatively — uncertainty, domain expertise, dependencies, risk, and
|
|
104
|
+
verification — not by fixed file or line thresholds. Return
|
|
105
|
+
contracts are role-specific: implementation uses `## subtask_summary`,
|
|
106
|
+
investigation returns structured findings, Athena returns the complete plan,
|
|
107
|
+
and council responses use `## specialist_response`. Delegated work gets at most
|
|
108
|
+
one retry after a transient failure, and Pantheon never claims deterministic
|
|
109
|
+
fan-in or job recovery without an exposed mechanism.
|
|
440
110
|
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
Two freshness guarantees back it up:
|
|
445
|
-
|
|
446
|
-
- **Postinstall artifact sync** — after any `npm install`, copy-only artifacts
|
|
447
|
-
(agents, skills, AGENTS.md, commands, MCP scripts, code-mode payload) are
|
|
448
|
-
refreshed into the existing config dir automatically; you never have to
|
|
449
|
-
re-run `init` just for file copies.
|
|
450
|
-
- **Drift detection** — the installer stamps the installed version in
|
|
451
|
-
`.pantheon/install-state.json` and `doctor` warns when the package is newer
|
|
452
|
-
than the last sync, pointing at `update`. `doctor` also detects **plugin
|
|
453
|
-
version drift** (issue #158): when `opencode.json` registers a plugin path
|
|
454
|
-
inside a `node_modules/pantheon-opencode` copy whose `package.json` version
|
|
455
|
-
differs from the running package, it warns that the registered tool surface
|
|
456
|
-
is stale. Re-running `init`/`update` realigns the registration onto the
|
|
457
|
-
current package.
|
|
458
|
-
|
|
459
|
-
`init` also gained `--components agents,skills,...` (narrow install),
|
|
460
|
-
`--clean` (alias of `--force`), `--opencode-version auto`, atomic config
|
|
461
|
-
writes with an `opencode.json.bak` backup, preflight checks for python3/npm
|
|
462
|
-
before any file is written, and a non-fatal Python runtime: if the venv fails,
|
|
463
|
-
the install completes but MCP entries are omitted (with a warning) instead of
|
|
464
|
-
pointing at a broken interpreter. Installer messages auto-detect pt-BR via
|
|
465
|
-
`LANG`/`LC_ALL`.
|
|
466
|
-
|
|
467
|
-
## Migrating to 1.5.x (from 1.4.x)
|
|
468
|
-
|
|
469
|
-
1.5.0 removed the custom `pantheon_delegate` tool (and the V1 delegation
|
|
470
|
-
engine) in favor of OpenCode's native `task()`; see
|
|
471
|
-
[Delegation (native `task()`)](#delegation-native-task). Two things change on
|
|
472
|
-
an existing install:
|
|
473
|
-
|
|
474
|
-
1. **The tool disappears from the plugin surface.** `pantheon_delegate` is no
|
|
475
|
-
longer registered by `src/plugin.ts` or `src/plugin-v2.ts`. Agents now
|
|
476
|
-
delegate through `task()` only — no configuration is needed.
|
|
477
|
-
2. **A lockfile-pinned copy can keep the old tool alive.** `npm install` is
|
|
478
|
-
lockfile-authoritative: a `package-lock.json` pinned to `1.4.1` (which
|
|
479
|
-
satisfies `^1.4.1`) is never re-resolved, so a project's
|
|
480
|
-
`node_modules/pantheon-opencode` can stay on 1.4.x while the published
|
|
481
|
-
package moved on. The plugin path your `opencode.json` registers keeps
|
|
482
|
-
pointing at that stale copy, and you keep running the obsolete tool surface
|
|
483
|
-
— including `pantheon_delegate` — with no warning.
|
|
484
|
-
|
|
485
|
-
The fix is a realignment + a detector:
|
|
111
|
+
The delegation model, caller/target matrix, and approval gates are documented
|
|
112
|
+
in [Architecture](docs/ARCHITECTURE.md) and
|
|
113
|
+
[Permissions, Gates & Delegation](docs/PERMISSIONS-QUALITY-DELEGATION.md).
|
|
486
114
|
|
|
487
|
-
|
|
488
|
-
# Realign the registered plugin path onto the current package (rewrites any
|
|
489
|
-
# node_modules/pantheon-opencode reference in opencode.json):
|
|
490
|
-
npx pantheon-opencode@latest init --yes --headless
|
|
491
|
-
# or, with a global install:
|
|
492
|
-
pantheon-opencode update
|
|
493
|
-
|
|
494
|
-
# Then verify no drift remains:
|
|
495
|
-
npx pantheon-opencode@latest doctor
|
|
496
|
-
```
|
|
497
|
-
|
|
498
|
-
`doctor` now reports a **Plugin Version Drift** warning (section H3) when the
|
|
499
|
-
registered plugin points into an installed copy whose version differs from the
|
|
500
|
-
running package, naming both versions and the removal (`pantheon_delegate` in
|
|
501
|
-
1.5.0). A healthy install reports no warning.
|
|
502
|
-
|
|
503
|
-
## Releases
|
|
504
|
-
|
|
505
|
-
Publication is authorized **only** by an explicit `workflow_dispatch` of the
|
|
506
|
-
`Release` workflow (`release_channel` input selects beta or stable). PR labels,
|
|
507
|
-
pushes, merges, and tags never publish anything, and every validation gate is
|
|
508
|
-
fail-closed: only an explicit PASS authorizes release evidence. See
|
|
509
|
-
[docs/RELEASING.md](docs/RELEASING.md) for validation and recovery details.
|
|
510
|
-
|
|
511
|
-
Release validation keeps each manifest with its lockfile: the root
|
|
512
|
-
`package.json` + `package-lock.json` and the TUI
|
|
513
|
-
`src/plugins/tui/package.json` + `src/plugins/tui/package-lock.json`. Both use
|
|
514
|
-
`npm ci --ignore-scripts`; an `npm ci` failure blocks the run and there is no
|
|
515
|
-
`npm install` fallback. A release carries one `.tgz` tarball, computes the
|
|
516
|
-
SHA-256 of that same artifact, and binds the tarball and GitHub release to the
|
|
517
|
-
full `TARGET_SHA`; a second pack is not interchangeable.
|
|
518
|
-
|
|
519
|
-
CI also rebuilds the TUI with `npm run build --prefix src/plugins/tui` and
|
|
520
|
-
checks every packaged `dist` artifact byte-for-byte against its checked-in
|
|
521
|
-
version, including final newlines. The build includes separate V1 and native
|
|
522
|
-
OpenCode V2 TUI entrypoints; `init` selects the entrypoint and sidebar slot API
|
|
523
|
-
for the host generation in use.
|
|
524
|
-
|
|
525
|
-
## Sandbox validation (V2)
|
|
526
|
-
|
|
527
|
-
`scripts/test-opencode-v2-sandbox.sh` validates the globally installed
|
|
528
|
-
package as a real user inside an isolated sandbox (own `HOME`, npm prefix and
|
|
529
|
-
venv) — never the dev environment. It checks the OpenCode V2 leg: the binary,
|
|
530
|
-
MCP connectivity, `doctor`, and — with `--prompts` — a prompt battery covering
|
|
531
|
-
the `pantheon://agents` resource, memory store/recall, filesystem writes and
|
|
532
|
-
agent delegation. The gate is fail-closed: every required check must return an
|
|
533
|
-
explicit PASS; timeouts, auth/network/provider failures and missing
|
|
534
|
-
prerequisites block the run.
|
|
535
|
-
|
|
536
|
-
The runner defaults to the current stable `@opencode/cli` package and its
|
|
537
|
-
`opencode2` alias; set `OPENCODE_V2_SPEC` only when a test needs a different
|
|
538
|
-
host build. This keeps Pantheon beta testing separate from the OpenCode CLI
|
|
539
|
-
release channel.
|
|
540
|
-
|
|
541
|
-
"V2" here refers only to the hook canary observed against an OpenCode v2.0.18
|
|
542
|
-
host, where at least one tested hook callback fired; it does not establish
|
|
543
|
-
compatibility with the stable `@opencode/plugin@2.0.18` SDK or full 2.x
|
|
544
|
-
contract. This branch still pins transitional `@opencode-ai/plugin@1.18.30`.
|
|
545
|
-
On hosts where both `opencode` and `opencode2` exist, the latter is typically
|
|
546
|
-
a shim that execs the same binary, so an older side-by-side comparison proved
|
|
547
|
-
nothing about the binary itself. The project is V2-exclusive, so there is a
|
|
548
|
-
single leg.
|
|
549
|
-
|
|
550
|
-
```bash
|
|
551
|
-
scripts/test-opencode-v2-sandbox.sh --prepare # tarball + install + init in the sandbox
|
|
552
|
-
~/pantheon-sandbox/start-pantheon.sh # interactive TUI in that isolated beta sandbox
|
|
553
|
-
scripts/test-opencode-v2-sandbox.sh --run v2 # base validation only
|
|
554
|
-
scripts/test-opencode-v2-sandbox.sh --prompts # base validation + prompt battery
|
|
555
|
-
scripts/test-opencode-v2-sandbox.sh --rehydrate # offline context rehydration/session-summary probe
|
|
556
|
-
scripts/test-opencode-v2-sandbox.sh --hooks # V2 hook callback canary
|
|
557
|
-
scripts/test-opencode-v2-sandbox.sh --rehydrate --hooks # run both canaries
|
|
558
|
-
scripts/test-opencode-v2-sandbox.sh --reset # wipe the sandbox root
|
|
559
|
-
```
|
|
560
|
-
|
|
561
|
-
Modes are combinable (e.g. `--prepare --run v2 --prompts`). `--rehydrate` runs
|
|
562
|
-
offline `context_rehydrate` and `context_session_summary` probes. `--hooks` runs
|
|
563
|
-
a V2 hook canary against the sandbox binary to check that hook callbacks fire;
|
|
564
|
-
it does not test transform callback effects or prove Pantheon's
|
|
565
|
-
`execute.before` security enforcement. With the probe-only `--rehydrate --hooks`
|
|
566
|
-
pair (without `--run`, `--prompts`, or `--cost`), the hooks canary still runs if
|
|
567
|
-
rehydration fails, and the command returns a failing status afterward. These
|
|
568
|
-
are test/sandbox canaries, not proof of Pantheon security enforcement. Binaries
|
|
569
|
-
are resolved strictly inside the sandbox npm prefix — a non-prepared sandbox
|
|
570
|
-
fails fast instead of silently testing the host installation. The sandbox is
|
|
571
|
-
always built from the checkout this script lives in; it never infers a
|
|
572
|
-
repository from a sibling directory.
|
|
573
|
-
|
|
574
|
-
This validates the prepared isolated sandbox only. A PASS is not proof of
|
|
575
|
-
support for every real host or for host configurations that were not exercised.
|
|
576
|
-
|
|
577
|
-
## Plugin V2 TypeScript coverage
|
|
578
|
-
|
|
579
|
-
`npm run coverage:plugin-v2` runs the `tests/pantheon/*.test.ts` suite with
|
|
580
|
-
Node's source-mapped native coverage and enforces an 80% line-coverage minimum
|
|
581
|
-
for `src/plugin-v2.ts` only. It requires Node `v24.15.0`; branch and function
|
|
582
|
-
coverage are reported but are not gates. This is not a repository-wide coverage
|
|
583
|
-
claim.
|
|
584
|
-
|
|
585
|
-
Env overrides:
|
|
586
|
-
|
|
587
|
-
| Variable | Default | Purpose |
|
|
588
|
-
|----------|---------|---------|
|
|
589
|
-
| `PANTHEON_SANDBOX_ROOT` | `~/pantheon-sandbox` | Sandbox root (refused if unsafe for `--reset`) |
|
|
590
|
-
| `OPENCODE_V1_SPEC` | `opencode-ai@1.18.18` | Configures the V1 plugin only; the V2-only sandbox runner does not consume or support it |
|
|
591
|
-
| `OPENCODE_V2_SPEC` | `@opencode/cli@latest` | npm spec providing the `opencode2` binary |
|
|
592
|
-
| `PANTHEON_SANDBOX_MODEL` | `opencode-go/mimo-v2.5` | Model used by init and prompts |
|
|
593
|
-
| `PANTHEON_PROMPT_TIMEOUT` | `300` | Per-prompt timeout in seconds |
|
|
594
|
-
|
|
595
|
-
Exit codes: `0` no real failures · `1` real failure (see `prompts-report.md`
|
|
596
|
-
in the sandbox root) · `2` usage error · `3` sandbox not prepared.
|
|
597
|
-
|
|
598
|
-
### Intentional memory MCP divergence
|
|
599
|
-
|
|
600
|
-
`scripts/memory_mcp.py` and `src/mcp/memory_mcp.py` are
|
|
601
|
-
intentionally different. The standalone `scripts/` copy keeps the lightweight
|
|
602
|
-
`memory_*` contract; the installed `src/mcp/` copy additionally exposes the
|
|
603
|
-
optional codemap schema and `code_index`, `code_query`, and `code_neighbors`.
|
|
604
|
-
The other shared MCP copies remain identical. Do not overwrite one memory copy
|
|
605
|
-
with the other.
|
|
606
|
-
|
|
607
|
-
### Task-result guard
|
|
608
|
-
|
|
609
|
-
A `task-result-guard` intercepts calls to the native `task()` tool where the
|
|
610
|
-
child session returns an empty or missing result. Instead of surfacing a silent
|
|
611
|
-
`completed` with no payload (which confuses the orchestrator), the guard now
|
|
612
|
-
raises an explicit error. This catches the common free-tier failure mode where a
|
|
613
|
-
child session exceeds the uncached-prefill token budget (`BackendAdmissionRejected`)
|
|
614
|
-
and returns nothing. Prefer `background=true` dispatches with an explicit
|
|
615
|
-
`task_status(wait=true)` fan-in so large payloads are collected deterministically.
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
## Configuration (environment variables)
|
|
619
|
-
|
|
620
|
-
The `pantheon-memory` MCP server needs no configuration: search is SQLite FTS5
|
|
621
|
-
(BM25) only, all stdlib, with no embedding model, no vector index, and no
|
|
622
|
-
`sqlite-vec`/`fastembed` dependency. Other environment variables are documented
|
|
623
|
-
in the sections above.
|
|
115
|
+
## Documentation
|
|
624
116
|
|
|
117
|
+
| Start here | Go deeper |
|
|
118
|
+
|---|---|
|
|
119
|
+
| [Installation](docs/INSTALLATION.md) | [Architecture](docs/ARCHITECTURE.md) |
|
|
120
|
+
| [Quick Start](docs/QUICKSTART.md) | [MCP](docs/MCP.md) · [MCP tools](docs/mcp-tools.md) |
|
|
121
|
+
| [Upgrading](docs/UPGRADING.md) | [Memory](docs/MEMORY.md) |
|
|
122
|
+
| [Compatibility](docs/COMPATIBILITY.md) | [OpenCode V2](docs/opencode-v2.md) |
|
|
123
|
+
| [Agents & Skills](docs/agents/README.md) | [Platforms](docs/PLATFORMS.md) |
|
|
124
|
+
| [Release Process](docs/RELEASING.md) | [Branch Protection](docs/BRANCH-PROTECTION.md) |
|
|
125
|
+
| [Model Routing](docs/reference/model-routing.md) | [Env Vars](docs/reference/env-vars.md) · [Code Mode](docs/reference/code-mode.md) |
|
|
126
|
+
| [Contributing](CONTRIBUTING.md) | [Roadmap](ROADMAP.md) · [Changelog](CHANGELOG.md) |
|
|
625
127
|
|
|
626
|
-
##
|
|
128
|
+
## Status
|
|
627
129
|
|
|
628
|
-
|
|
130
|
+
The manifests in this checkout express the version being prepared, not a
|
|
131
|
+
confirmed publication. Check the npm `beta` dist-tag for what is actually
|
|
132
|
+
published. See [Compatibility](docs/COMPATIBILITY.md) for the supported hosts
|
|
133
|
+
and [releases](https://github.com/ils15/pantheon-opencode/releases) for the
|
|
134
|
+
latest published changes.
|
|
629
135
|
|
|
630
|
-
|
|
631
|
-
`evals/promptfoo/`, which is gitignored and excluded from npm packaging,
|
|
632
|
-
package evidence, CI tests, coverage, and release gates. Publish reviewed
|
|
633
|
-
findings as documentation, not the local harness, datasets, outputs, or
|
|
634
|
-
credentials.
|
|
136
|
+
## What's new
|
|
635
137
|
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
- [Platforms](docs/PLATFORMS.md) · [Upgrading](docs/UPGRADING.md)
|
|
639
|
-
- [Agent reference](docs/agents/README.md) · [Skills reference](src/skills/README.md)
|
|
640
|
-
- [Release process](docs/RELEASING.md) · [Contributing](CONTRIBUTING.md)
|
|
641
|
-
- [Changelog](CHANGELOG.md)
|
|
138
|
+
See the [GitHub release](https://github.com/ils15/pantheon-opencode/releases)
|
|
139
|
+
and [CHANGELOG.md](CHANGELOG.md) for the changes in 1.6.0.
|
|
642
140
|
|
|
643
141
|
## Contribute
|
|
644
142
|
|
|
645
143
|
Ideas, bug reports, documentation improvements, and code contributions are
|
|
646
|
-
welcome.
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
### Reproducible benchmark evidence
|
|
650
|
-
|
|
651
|
-
The beta2 benchmark records reported token usage separately from its
|
|
652
|
-
character-based fallback estimate; source bytes and logical line counts remain
|
|
653
|
-
provenance data and are never converted into tokens. Cross-report comparisons
|
|
654
|
-
require matching model/config provenance and reported OpenCode usage. Offline
|
|
655
|
-
fixture responses are mocked: their reported values are labeled separately,
|
|
656
|
-
excluded from `actual` usage, and blocked from comparative metrics and GEPA.
|
|
657
|
-
Fixture quality outcomes test the offline contract; they are not evaluation
|
|
658
|
-
evidence.
|
|
659
|
-
Reproduce the
|
|
660
|
-
checked-in AGENTS.md history manifest with
|
|
661
|
-
`python3 -m benchmarks.beta2.provenance --output benchmarks/beta2/fixtures/agent-baseline-provenance.json`.
|
|
662
|
-
For OpenCode benchmark runs, provide `--model` and `--config-sha256` so reports
|
|
663
|
-
can be compared safely.
|
|
664
|
-
|
|
665
|
-
### Project-level `opencode.json`
|
|
666
|
-
|
|
667
|
-
The published package carries no `opencode.json` template. `init` still writes
|
|
668
|
-
your project's `opencode.json` itself, and the few product defaults an install
|
|
669
|
-
seeds — `default_agent: zeus` and `permission.skill` — come from the installer
|
|
670
|
-
code, not from a packaged file. Contributors who keep a project-level
|
|
671
|
-
`opencode.json` for their own OpenCode sessions should leave it untracked —
|
|
672
|
-
`.git/info/exclude` per clone, or a shared `.gitignore` decision — rather than
|
|
673
|
-
versioning it.
|
|
144
|
+
welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull
|
|
145
|
+
request. That file also defines the documentation rule: one home per fact, with
|
|
146
|
+
a short list of facts that must not be duplicated.
|
|
674
147
|
|
|
675
148
|
## Citation and DOI
|
|
676
149
|
|
|
677
150
|
Pantheon is released under the [MIT License](LICENSE). Cite the
|
|
678
151
|
[Zenodo concept DOI](https://doi.org/10.5281/zenodo.22650136), which always
|
|
679
152
|
resolves to the latest archived release; each release also has its own version
|
|
680
|
-
DOI. Citation metadata is
|
|
153
|
+
DOI. Citation metadata is in [CITATION.cff](CITATION.cff).
|
|
681
154
|
|
|
682
155
|
Canonical repository: <https://github.com/ils15/pantheon-opencode>
|
|
683
156
|
|