opencode-goal-plugin 0.8.2 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.10.0 — 2026-09-06
+
+- Fix the plan-mode guard failing open on the first command of a session. OpenCode runs `command.execute.before` before any chat hook for the turn and its `Session` record carries no `agent` field, so the session-record fallback introduced in 0.9.0 could never learn the agent for a `/goal <objective>` sent as a fresh session's first turn: the goal started live and the routed text told the model to begin work. The routed turn itself carries the agent, so `chat.message` now re-evaluates the planning-only restriction for the goal that command created and, when the agent is restricted, holds the goal (`plan agent active`, budget preserved), rewrites the turn as a read-only control turn, and blocks tools for it. Reproduced, and verified fixed, against live OpenCode 1.18.25 and 1.18.29 over the HTTP `command` API with `agent: "plan"` and a `goal` command that does not pin an agent; the case where an earlier turn had already reported the agent was unaffected. Note that OpenCode runs a command under its configured `agent` when one is set (`cmd.agent ?? input.agent`), so with the README's `"agent": "build"` the `/goal` turn executes as `build` and a hold can only come from a previously reported planning-only agent; the README's plan-mode section now spells this out. Pinned by a new mutation-contract entry.
+- Fix the `sessionTitleStatus` indicator leaving a stale `▶` running line on the session after the goal completed. Completion archives the goal, and the title sync returned early with no live goal, so the last running render stayed until `/goal clear`. A completed goal now renders as `✅ <objective> · N turns · <elapsed> · <tokens>`; `/goal clear` still restores the captured original title. Reproduced against live OpenCode 1.18.25 and 1.18.29.
+- Treat a fenced ```` ```span``` ```` in `/goal` arguments as literal objective text: double-dash tokens inside it are no longer parsed as goal flags (previously `/goal run pytest --maxfail=1` rejected the command with `Unsupported flag: --maxfail`), a fence is never consumed as a flag value, and the backticks are stripped from the stored objective. Ported from [@NiklasTR](https://github.com/NiklasTR)'s fork.
+- Add a cost cap: the `maxCostUsd` plugin option and `--max-cost` per-goal flag pause a goal, with the usual final wrap-up prompt, once the cumulative API cost OpenCode reports for the session reaches the cap (`stopReason: max cost reached ($X.XX)`). `/goal status` shows `Cost budget: $spent/$cap`, the continuation `<progress_budget>` carries `cost_remaining_usd`, the near-limit warning fires within 10% of the cap, and the `goal_set`/`set_goal` tools accept `maxCostUsd`. An unknown provider cost never trips the cap and a single response may overshoot it; `/goal resume` opens a fresh window. Idea and first implementation by [@NiklasTR](https://github.com/NiklasTR).
+- Add `agentGoalAuthority`. The default `"full"` is unchanged; `"status"` keeps the agent-facing tools to reporting: `goal_set`/`set_goal` refuse to replace an active goal (returned as an `agent_authority` failure envelope on the canonical tool), `update_goal` refuses objective changes, and `clear_goal` refuses to clear, so a model can no longer rewrite the objective the user gave it. Completing, blocking, pausing, resuming, and creating a goal when none is live remain allowed. Prompted by [@felores](https://github.com/felores)'s fork, which removed those abilities outright.
+- Make the `simultaneous stale observers` lease test deterministic: attach its settle handler before the barriers so an early loser's rejection is never reported as unhandled, and never wait at a barrier for an acquirer that already settled. This was the known-flaky Windows CI test; it also failed locally under load.
+- Update the bundled `zod` dependency from 4.4.3 to 4.5.4 and the CodeQL action to v4.37.9 (supersedes dependabot #60 and #69).
+- Rewrite the install docs around how OpenCode actually loads plugins. `npm install` was never needed; the config entry is what installs the package. More importantly, OpenCode resolves an unpinned `"opencode-goal-plugin"` to `@latest` once, caches it under `~/.cache/opencode/packages/opencode-goal-plugin@latest/`, and never re-resolves while that directory exists, so users who followed the old instructions are frozen on whichever version they first installed. The README now pins the version, documents the upgrade path (bump the pin, or delete the cached directory), mentions `opencode plugin <name>@<version>`, and notes that a `file://` checkout needs its `node_modules`. `npx opencode-goal-plugin` (the bundled verify script) warns when OpenCode's unpinned cache lags the package. Also documents `ledgerFilePath` and adds an OpenCode 1.18.29 compatibility row from a deterministic-provider canary.
+
+## 0.9.0 — 2026-08-29
+
+- Add plan-mode safety: a goal set while a planning-only agent is active is recorded but held instead of starting, with stop reason `plan agent active`, its budget preserved, and a read-only control turn that tells the model not to begin work. Auto-continue already paused when the session switched to Plan; this closes the creation path, where the goal previously started and ran the loop before any idle occurred. The active agent is read from the host's execution context with a fallback to the session record, which matters because `command.execute.before` runs before `chat.message`/`chat.params` — without the fallback the restriction failed open on the first command in a session. Configurable via `restrictedAgents` (default `["plan"]`) and `allowGoalExecutionFromPlan` (default `false`); the default-on behavior is pinned by the mutation contract. Note the restriction stops the goal loop, not the single routed command turn, which OpenCode does not fully intercept.
+- Add an opt-in session-title status indicator (`sessionTitleStatus`), mirroring live goal status — state icon, objective, turns, elapsed, and tokens — into the OpenCode session title so unattended runs show a continuous heartbeat. The original title is captured before the first overwrite and restored by `/goal clear`; unchanged renders skip the API call, and update failures are logged at debug level without interrupting the goal loop. The indicator refreshes on commands and on idle/compaction/interruption events but never on the `message.updated` events that stream during a turn, keeping API round-trips out of the response path. Status lines written by a previous process are recognized as the plugin's own, so a restart followed by `/goal clear` cannot promote stale goal status to the session's permanent title.
+- Verify both features against a live OpenCode 1.18.25 TUI, not only unit and contract tests: a goal set under Plan records `stopped: true` with zero auto-continues, and the status indicator renders in the session title.
+- Document OpenCode 2 status explicitly: unsupported and untested, with the existing dual-shape session adapter noted and a concrete checklist of what a supported claim would require. Records that this plugin is server-only, so its configuration lives entirely in `opencode.json` on any OpenCode line.
+
 ## 0.8.2 — 2026-08-21
 
 - Harden the post-compaction goal continuation guard introduced in

package/README.md

@@ -31,13 +31,14 @@ This project is independently implemented for OpenCode. Product names used elsew
 | Operating systems | Filesystem-sensitive lifecycle tests run on Linux, macOS, and Windows |
 | Package entrypoint | Installed-tarball contracts verify both export paths, consumer TypeScript resolution, hooks, and all 11 tools |
 | Provider/backend quirks | Strict-template backends require the goal block to merge into the primary `system` message; covered by regression tests |
+| OpenCode 2 | Not supported and not yet tested; the peer/engine pin is `>=1.17.15 <2`. See the [OpenCode 2 section](docs/compatibility.md#opencode-2) |
 
 See the [compatibility policy](docs/compatibility.md) for the supported public
 surface and versioning expectations.
 
 ### OpenCode version compatibility
 
-Tested against real OpenCode 1.17.15 processes with live provider credentials and no mocked plugin hooks. State, ledger entries, and workspace files were checked independently of terminal or model prose:
+Tested against real OpenCode 1.17.15 and 1.18.25 processes with live provider credentials and no mocked plugin hooks. State, ledger entries, and workspace files were checked independently of terminal or model prose:
 
 | OpenCode Version | Provider Tested | `/goal status` | Auto-continue | Evidence-gated completion | Historical custom-command presentation (v0.6.6) |
 |---|---|---|---|---|---|
@@ -45,24 +46,24 @@ Tested against real OpenCode 1.17.15 processes with live provider credentials an
 | 1.17.15 | opencode-go (`qwen3.7-plus`) | ✅ | ✅ | ✅ Self-corrected after one rejection (bare `[goal:complete]` with no evidence), then completed cleanly | ⚠️ Not displayed |
 | 1.17.15 | opencode-go (`glm-5.2`) | ✅ | ✅ | ✅ Clean `[goal:evidence]` + `[goal:complete]` on the first attempt | ⚠️ Not displayed |
 | 1.17.15 | deepseek (`deepseek-chat`) | ✅ | ✅ | ✅ Clean `[goal:evidence]` + `[goal:complete]` on the first attempt; also verified end-to-end via the [demo](demo/) — autonomously fixed a real bug and reported evidence-backed completion | ⚠️ Not displayed |
+| 1.18.25 | opencode (`nemotron-3.5-lightning-free`) | ✅ | ✅ Held correctly under the Plan agent (`stopped: true`, zero auto-continues) | ✅ Clean `[goal:evidence]` + `[goal:complete]` | ⚠️ Not displayed; command text routed to model |
+| 1.18.29 | deterministic localhost OpenAI-compatible fixture (no live provider) | ✅ Control turn routed; all 11 tools in every request | ✅ Idle continuation → completion; blocker paused with its reason | ✅ `[goal:evidence]` + `[goal:complete]` archived | ⚠️ Not displayed; command text routed to model |
 
 `/goal status` and auto-continue are graded on **state correctness** (verified directly against persisted state: correct limits, turn/stop accounting, completion state, and file effects), not on terminal rendering. The `deepseek-v4-flash-free` canary suite additionally covers pause/resume across processes, blocker/restart, hard-process recovery, real host compaction, and stale-history clear enforcement. See [`docs/providers.md`](docs/providers.md) for the complete lifecycle matrix and session evidence.
 
 **Note:** The table records the v0.6.6 live-provider matrix. In that release, OpenCode 1.17.15 retained the original command-parts array, so assigning a new `output.parts` array did not replace the raw command argument sent to the model. The current implementation mutates that retained array in place, making the plugin-generated command result the prompt for the turn. OpenCode custom commands still run through the model rather than rendering hook output directly, so the visible response may summarize or paraphrase the result (see [Limitations](#limitations)). Re-test against the exact OpenCode build and provider/backend stack you rely on for unattended work, and see [`docs/providers.md`](docs/providers.md) for the full historical model matrix.
 
+The 1.18.29 row comes from a deterministic-provider canary against a real `opencode serve` process, graded on persisted state. That canary also reproduced the two defects fixed in 0.10.0 (a first-command Plan goal not being held; a stale running title after completion) on 1.18.25 and 1.18.29 alike.
+
 Separately, the lifecycle-feedback implementation included in v0.7.0 passed a real OpenCode 1.18.11 host canary covering create, status, pause, resume, edit, and default lifecycle logging with a deterministic localhost provider. That canary validates host integration, not another live-provider compatibility row.
 
 ## Install
 
-```sh
-npm install opencode-goal-plugin
-```
-
-Add the plugin and command to your OpenCode config:
+OpenCode installs npm plugins itself from your config, so there is nothing to `npm install`. Add the plugin **with a pinned version** and the `goal` command to `opencode.json` (the user config at `~/.config/opencode/opencode.json`, or a project-local `opencode.json`):
 
 ```json
 {
-  "plugin": ["opencode-goal-plugin"],
+  "plugin": ["opencode-goal-plugin@0.10.0"],
   "command": {
     "goal": {
       "description": "Set a session-scoped goal and auto-continue until complete.",
@@ -73,6 +74,20 @@ Add the plugin and command to your OpenCode config:
 }
 ```
 
+Or let the CLI add the plugin entry for you and then add the `command` block by hand:
+
+```sh
+opencode plugin opencode-goal-plugin@0.10.0 --global
+```
+
+Restart OpenCode after editing the config. The options form `["opencode-goal-plugin@0.10.0", { ... }]` (see [Options](#options)) pins the same way.
+
+### Upgrading
+
+**Pin the version.** OpenCode resolves an unpinned `"opencode-goal-plugin"` entry to `@latest` exactly once, installs it under its package cache (`~/.cache/opencode/packages/opencode-goal-plugin@latest/` by default; `opencode debug paths` prints the cache root), and never re-resolves `latest` while that directory exists. An unpinned entry therefore stays on whichever version was first installed, indefinitely, and new releases on npm are never picked up — a bug fixed months ago can still be running locally.
+
+To upgrade, bump the pin (for example to `opencode-goal-plugin@0.10.0`) and restart OpenCode; every pinned version gets its own cache directory. If you kept an unpinned entry, delete the `opencode-goal-plugin*` directories under the cache `packages/` folder and restart. `npx opencode-goal-plugin` runs the bundled verification script, which warns when the cached copy lags the package.
+
 ## Usage
 
 Set a goal:
@@ -84,7 +99,7 @@ Set a goal:
 Override limits for a single goal:
 
 ```
-/goal fix the failing tests --max-turns 20 --max-minutes 30 --max-tokens 400000
+/goal fix the failing tests --max-turns 20 --max-minutes 30 --max-tokens 400000 --max-cost 5
 ```
 
 Add success criteria, constraints / non-goals, and a mode:
@@ -97,6 +112,14 @@ Add success criteria, constraints / non-goals, and a mode:
 
 Flags accept either `--flag value` or `--flag=value`. If a flag is unknown, missing a value, given a non-positive integer, or (for `--mode`) an unrecognized mode, the plugin rejects the command with a helpful error instead of silently folding the bad flag into the goal text.
 
+To include literal command-line options in an objective, wrap them in a Markdown fenced code span. Double-dash tokens inside the fence are objective text and are not parsed as goal flags:
+
+````text
+/goal run ```pytest --maxfail=1 --disable-warnings``` and fix every failure
+````
+
+Multiline fences work as well. The backticks are removed from the stored objective, and a fence is never consumed as a flag's value.
+
 Check status:
 
 ```
@@ -229,6 +252,7 @@ Markers must appear on their own final line. The bracketed form is canonical, bu
 | Auto-continue turns | 10 |
 | Max duration | 15 minutes |
 | Context tokens | 200,000 |
+| API cost (USD) | off — set `maxCostUsd` or `--max-cost` |
 | Min delay between continues | 1.5 seconds |
 | No-progress pause | < 50 output tokens on a stalled turn (after a 2-turn grace window) |
 | Budget wrap-up threshold | 80% of context token budget |
@@ -238,6 +262,8 @@ Markers must appear on their own final line. The bracketed form is canonical, bu
 
 **Token budget.** The plugin tracks the session's context window size (`input + output + reasoning` tokens on the latest message). This matches the token count that OpenCode displays, so the numbers should be consistent. When the context window reaches the `--max-tokens` limit, the plugin sends a wrap-up prompt and stops. In high-context sessions (large codebases, long conversation history), the context can grow quickly — treat the budget as a safety brake.
 
+**Cost budget.** `maxCostUsd` (or `--max-cost 5` per goal) pauses the goal once the cumulative cost OpenCode reports for the session's assistant messages reaches the cap, with the same wrap-up prompt as the other limits; `/goal status` shows `Cost budget: $spent/$cap` and the continuation prompt carries `cost_remaining_usd`. Enforcement depends on the provider reporting cost — an unknown cost never trips the cap — and one response may overshoot it. `/goal resume` opens a fresh budget window.
+
 **No-progress heuristic.** A low-output turn does not pause immediately anymore. The plugin pauses only after `noProgressTurnsBeforePause` consecutive *stalled* low-output turns — repeated turns with very little output and no meaningful change in the latest assistant checkpoint.
 
 **No-tool-call heuristic.** Complementing the no-progress check, the plugin also watches for continuation turns that produce no tool calls at all (a "talk only" turn). Repeated talk-only turns usually mean the assistant is chatting to itself rather than doing work, so after `noToolCallTurnsBeforePause` consecutive tool-free continuation turns the plugin pauses. A turn that uses any tool (or delegates a subtask) resets the counter.
@@ -326,6 +352,7 @@ Pass options when registering the plugin to change the defaults for all goals. T
 
 Additional plugin-level options:
 
+- `maxCostUsd` — cumulative OpenCode-reported API cost, in US dollars, before a goal pauses (default `0`, disabled). See the cost budget note under [Safety limits](#safety-limits).
 - `maxRecentMessages` — how many recent session messages to scan when looking for the latest assistant turn before auto-continuing. Higher values make long, tool-heavy sessions less likely to lose the most recent assistant response.
 - `noProgressTurnsBeforePause` — grace window for low-output stalls. The plugin pauses only after this many consecutive stalled low-output turns rather than on the first one.
 - `noToolCallTurnsBeforePause` — grace window for tool-free continuation turns. The plugin pauses after this many consecutive continuation turns that produced no tool calls (anti self-chat loop). Default `2`; set the plugin option to `0` for legitimate tool-free writing/research workflows.
@@ -335,11 +362,13 @@ Additional plugin-level options:
 - `commandName` — the slash command the plugin owns (default `goal`). Set it to e.g. `objective` to drive the workflow with `/objective` instead of `/goal`; a leading slash is tolerated. Remember to register the matching command name in your OpenCode `command` config. User-facing hints (`/goal status`, `/goal resume`, …) follow the configured name.
 - `registerCommand` — whether the plugin installs its `command.execute.before` hook at all (default `true`). Set it to `false` if you only want the auto-continue/persistence behavior driven programmatically and don't want the plugin to own a slash command.
 - `registerTools` — whether the plugin registers the agent-facing goal tools (default `true`). Set to `false` to omit the programmatic tool surface entirely. See [Agent tools](#agent-tools).
+- `agentGoalAuthority` — `"full"` (default) or `"status"`. In `"status"` mode the agent tools can report on a goal but cannot replace, edit, or clear one; see [Agent tools](#agent-tools).
 - `registerAgents` — whether the config hook adds native `goal` and `goal-verify` agents (default `true`). Existing agents with those names are preserved unchanged; the plugin never changes your default agent.
 - `goalAgentName` / `verifierAgentName` — customize the registered native agent names (defaults `goal` and `goal-verify`). The verifier is a hidden subagent with a default-deny tool policy; only `read`, `glob`, and `grep` are allowed.
 - `sdkShape` — OpenCode session-client argument shape: `legacy` (the default generated `PluginInput` client using `{ path, body, query }`) or `flat` (clients using `{ sessionID, ... }`). Read-only `messages`/`get` calls may probe the alternate shape after an argument/schema `TypeError`; mutating calls are never replayed, so set this option correctly for embedded clients.
 - `persistState` — whether to persist active goals and recent goal results to disk.
 - `stateFilePath` — root path for the persisted session-shard namespace. Overrides the default project-local path and the `OPENCODE_GOAL_STATE_PATH` env var. Useful if you want a fixed or ephemeral location. When unset, the default root is `<cwd>/.opencode/goals/state.json`; shards are written below `<stateFilePath>.sessions/` (see the persistence section above).
+- `ledgerFilePath` — override where the lifecycle ledger is written. By default each session shard keeps its ledger next to its state file as `<state.json>.ledger.jsonl`.
 - `ledgerMaxBytes` / `ledgerRetentionFiles` — bound the lifecycle ledger to 2 MiB per generation and three rotated generations by default. Set retention to `0` to discard the active ledger when it reaches the size ceiling.
 - `resultRetentionMs` — how long a completed goal summary remains available through `/goal status` after the goal leaves active memory.
 - `maxStoredResults` — maximum number of completed-goal summaries retained in process memory before the oldest ones are evicted.
@@ -355,7 +384,7 @@ Registered tools:
 - `goal_status`, `goal_set`, `goal_pause`, `goal_resume`, `goal_block`, and `goal_complete` are the canonical narrow operations. They return compact versioned JSON envelopes so agents can branch reliably without parsing prose.
 - `get_goal`, `get_goal_history`, `set_goal`, `update_goal`, and `clear_goal` remain compatibility aliases with their existing text responses.
 
-`goal_set` and `set_goal` are explicitly constrained to user-requested goals. `goal_complete` accepts a structured claim: a required non-empty `summary`, plus optional criterion/evidence pairs, checks (`passed`, `failed`, or `not-run`), changed files, and known limitations. Failed checks and empty criterion evidence are rejected before archival; accepted claims are serialized deterministically for the configured completion auditor. The legacy `update_goal` tool retains its string `evidence` field for compatibility.
+`goal_set` and `set_goal` are explicitly constrained to user-requested goals by their descriptions. To enforce that in code, set `agentGoalAuthority: "status"`: agents may then complete, block, pause, or resume a goal and create one when none is live, but `goal_set`/`set_goal` refuse to replace an active goal, `update_goal` refuses objective changes, and `clear_goal` refuses to clear — only you, through `/goal`, `/goal add`, `/goal edit`, and `/goal clear`, can change what the goal *is*. The default `"full"` keeps the previous behavior, where a tool call can replace or rewrite the objective. `goal_complete` accepts a structured claim: a required non-empty `summary`, plus optional criterion/evidence pairs, checks (`passed`, `failed`, or `not-run`), changed files, and known limitations. Failed checks and empty criterion evidence are rejected before archival; accepted claims are serialized deterministically for the configured completion auditor. The legacy `update_goal` tool retains its string `evidence` field for compatibility.
 
 These operate on the same per-session multi-goal state as the command path: a tool-set goal persists, shows up in `/goal list`, and is driven by the idle auto-continue; completing a goal in an ordered sequence auto-promotes the next.
 
@@ -401,6 +430,64 @@ await GoalPlugin(
 
 `timeoutMs` caps how long the built-in child-session auditor waits for a verdict. `failurePolicy` defaults to `reject`: an unavailable API, missing child-session ID, provider error, or timeout rejects the audit and pauses the goal for review. Set it to `approve` only as an explicit compatibility escape hatch; an actual negative or malformed verifier verdict still rejects. `auditorOptions` is ignored when a custom `auditor` function is supplied.
 
+## Status indicator
+
+Unattended runs are easier to trust when you can see the goal is still alive. Set `sessionTitleStatus: true` and the plugin mirrors live goal status into the OpenCode session title, which the TUI renders persistently:
+
+```
+▶ ship the release · 3/10 · 2m · 45k/200k
+```
+
+Status icon, objective, auto-continues used / limit, elapsed time, and context tokens / budget. The icon distinguishes running (`▶`), paused (`⏸`), and blocked (`⛔`) — blocked outranks paused because it needs you, not just a resume. A paused goal freezes its elapsed clock rather than running on. When the goal completes, the title switches to `✅ ship the release · 3 turns · 2m · 45k` so a finished run is never mistaken for a running one; `/goal clear` restores your original title.
+
+```json
+{
+  "plugin": [
+    ["opencode-goal-plugin", { "sessionTitleStatus": true }]
+  ]
+}
+```
+
+The option is **off by default** because it overwrites a user-visible field. When enabled, the session's original title is captured before the first overwrite and restored by `/goal clear`. A render identical to the last one skips the API call, so `/goal status` and other read-only commands cost nothing. Title updates are cosmetic: a failure is logged at debug level and never interrupts the goal loop.
+
+The indicator refreshes on goal commands and on idle, compaction, and interruption events — **not** on the `message.updated` events that stream during an assistant turn. Streaming refreshes would put an API round-trip in the response path for a cosmetic update, and idle is the cadence a human actually reads the indicator at.
+
+The captured original title lives in memory only, so a hard process kill leaves the last status line on the session. The plugin recognizes its own status lines and will not mistake one for your title, so `/goal clear` after a restart leaves the host's title alone rather than restoring stale goal status — but it cannot recover the title the session had before the goal started. Rename the session if you want it back.
+
+This needs no TUI plugin entrypoint, no `@opentui` dependencies, and no build step.
+
+## Plan-mode safety
+
+A planning-only agent is never driven into execution by the goal loop. OpenCode's built-in `plan` agent is restricted by default:
+
+- A goal set while `plan` is active is **recorded but held**, with stop reason `plan agent active`. The objective and its budget survive, so nothing is lost — the goal simply does not start.
+- The routed confirmation text for a held goal **omits the "start working" instruction** and is sent as a read-only control turn. This matters because command text reaches the model as a normal turn on current OpenCode builds (see [Limitations](#limitations)).
+- Auto-continue stays suppressed on **every idle** while a restricted agent is active, so switching into `plan` mid-goal pauses the loop.
+- Continuations retain the agent that started the goal, so the loop cannot drift into a different agent.
+
+The active agent is read from the execution context the host reports for its turns. OpenCode runs `command.execute.before` before any `chat.message`/`chat.params` for the turn, and its session record carries no agent, so for the first command in a session the agent is unknown at creation time. The plugin therefore re-checks when the routed turn reaches `chat.message`, which does carry the agent, and holds the goal there — rewriting the turn into a read-only control turn and blocking tools for it — before the model is told to start.
+
+**Command configuration matters.** OpenCode runs a custom command under the agent named in its config (`command.goal.agent`) and only falls back to the agent selected in the session when the command sets none. With the install snippet's `"agent": "build"`, the `/goal` turn itself always executes as `build`, so a hold can only come from a *previously* reported planning-only agent (the case verified in the TUI, where you switched to Plan and then typed `/goal`). To have Plan mode hold a goal even on a session's very first turn, omit `agent` from the `goal` command config so the command runs under the selected agent.
+
+**What this does and does not prevent.** The restriction stops the *goal loop*: a held goal sends zero auto-continues, so no unattended work happens. It cannot stop a model from acting on the single routed command turn, because OpenCode's `command.execute.before` does not fully intercept command text (see [Limitations](#limitations)). A held goal's routed text explicitly tells the model not to begin work and is sent as a read-only control turn, but a non-compliant model may still act on that one turn. Verified against OpenCode 1.18.25: a goal set under Plan records `stopped: true`, `stopReason: plan agent active`, and `turnCount: 0`.
+
+Run `/goal resume` after switching back to an executing agent to start the work.
+
+| Option | Default | Controls |
+|---|---|---|
+| `restrictedAgents` | `["plan"]` | Agent names treated as planning-only (case-insensitive). Pass `[]` to release the restriction. |
+| `allowGoalExecutionFromPlan` | `false` | Set `true` to allow goal creation and auto-continue while a restricted agent is active. |
+
+```json
+{
+  "plugin": [
+    ["opencode-goal-plugin", { "restrictedAgents": ["plan", "review"] }]
+  ]
+}
+```
+
+The restriction being on by default is pinned by the mutation contract: hardcoding `allowGoalExecutionFromPlan` to `true` fails the suite.
+
 ## Prompt safety
 
 The goal text is wrapped in `<goal_objective>` tags and labeled as user-provided task data. The assistant is told to treat it as a task description, not as elevated instructions that can override system, developer, tool, or repository policies.
@@ -446,6 +533,8 @@ Point OpenCode at the source file directly for local testing:
 
 Keep test files outside OpenCode's auto-loaded plugin directory — OpenCode will attempt to load plugin-like files it finds there.
 
+A `file://` entry loads the source as-is, so the checkout needs its `node_modules` (`npm ci`) for the `zod` import to resolve; copying `src/goal-plugin.js` somewhere on its own will fail to load. Use the npm package for anything but development.
+
 ### Smoke-test checklist
 
 1. Run `npm run smoke` to verify the package export path and `/goal` command hook without a model call.

package/docs/compatibility.md

@@ -81,6 +81,56 @@ comes from the rewritten turn's escaped reporting frame, fail-closed tool
 blocking, and parent-correlated lifecycle suppression. The system transform
 remains registered as additional protection for hosts that support it.
 
+## OpenCode 2
+
+**Status: not supported, and not yet tested.**
+
+The package declares `engines.opencode` and the `@opencode-ai/plugin` peer as
+`>=1.17.15 <2`. That bound is deliberate: no claim in this repository is made
+without a verified run behind it, and the project has not yet exercised the
+plugin against an OpenCode 2 build. Treat OpenCode 2 as unverified rather than
+as known-broken.
+
+### What already exists in this direction
+
+- `createOpenCodeSessionApi` speaks both the legacy generated-client shape
+  (`{ path, body, query }`) and the flattened shape (`{ sessionID, ... }`),
+  selected per operation and remembered after the first success. The
+  `sdkShape: "flat"` option pins the flattened shape for embedded clients.
+- Only read-only operations are ever replayed against the alternate shape, so a
+  shape probe can never duplicate a mutating call. This invariant is pinned by
+  the mutation contract.
+
+### What a supported v2 claim would require
+
+Before the pin is widened, all of the following need to pass against a real
+OpenCode 2 build, not a mock:
+
+1. Plugin load and hook registration through the v2 plugin entrypoint.
+2. `command.execute.before`, `event`, `experimental.chat.system.transform`,
+   `experimental.session.compacting`, and `experimental.compaction.autocontinue`
+   firing with the shapes the plugin expects.
+3. The execution-context signals (`chat.message`, `chat.params`,
+   `session.updated`) still reporting the active agent, which the planning-only
+   restriction depends on.
+4. Session-API calls (`messages`, `promptAsync`, `create`, `get`, `update`,
+   `abort`) under whichever argument shape v2 ships.
+5. Goal-specific compaction context and recovery of running child sessions after
+   a plugin restart, which are the areas most likely to differ.
+
+### Configuration
+
+This plugin is **server-only**: `package.json` exports the root and
+`opencode-goal-plugin/server`, and there is no TUI plugin entrypoint. Its
+configuration therefore lives entirely in `opencode.json` (the `plugin` and
+`command` keys) on any OpenCode line.
+
+Plugins that *do* ship a TUI component are registered in a second file whose
+location differs between OpenCode lines, and those formats must not be mixed.
+That distinction does not apply here — including for the
+[status indicator](../README.md#status-indicator), which reaches the TUI through
+the session title rather than through a TUI plugin.
+
 ## Versioning
 
 Semantic-versioning intent is:

package/docs/releasing.md

@@ -7,7 +7,10 @@ artifact after all checks pass.
 ## Prepare
 
 1. Start from a clean branch based on `main`.
-2. Update the version in `package.json` and `package-lock.json` together.
+2. Update the version in `package.json` and `package-lock.json` together, and
+   the pinned `opencode-goal-plugin@X.Y.Z` in the README install section and
+   `examples/opencode.json` (OpenCode never refreshes an unpinned plugin, so
+   the docs must show a pin).
 3. Move relevant entries from `Unreleased` into a dated changelog section.
 4. Run `npm ci` followed by `npm run release:check`.
 5. Inspect `npm pack --json` and the generated tarball before publishing.

package/examples/opencode.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-goal-plugin"],
+  "plugin": ["opencode-goal-plugin@0.10.0"],
   "command": {
     "goal": {
       "description": "Set a session-scoped goal and auto-continue until complete.",

package/index.d.ts

@@ -133,6 +133,17 @@ export interface GoalPluginOptions {
    */
   maxTokens?: number
 
+  /**
+   * Maximum cumulative API cost, in US dollars, a goal may incur before it is
+   * paused for exceeding limits. Uses the cost OpenCode reports on assistant
+   * messages, so enforcement depends on provider cost metadata and one
+   * response may overshoot the cap; an unknown cost never trips it.
+   * `/goal resume` opens a fresh budget window. Overridable per-goal with
+   * `--max-cost`. `0` disables the cap.
+   * @default 0
+   */
+  maxCostUsd?: number
+
   /**
    * Minimum delay, in milliseconds, enforced between consecutive
    * auto-continue prompts. Overridable per-goal with `--cooldown-ms`.
@@ -308,9 +319,50 @@ export interface GoalPluginOptions {
    */
   registerTools?: boolean
 
+  /**
+   * How much control the agent-facing tools have over goals. `"full"` (the
+   * default) lets `goal_set`/`set_goal` replace an active goal, `update_goal`
+   * rewrite the objective, and `clear_goal` discard goals. `"status"` keeps
+   * agents to reporting: they may complete, block, pause, or resume a goal
+   * and create one when none is live, but only the user, through the slash
+   * command, can replace, edit, or clear a goal. Refusals are returned as tool
+   * results (an `agent_authority` failure envelope for `goal_set`).
+   * @default "full"
+   */
+  agentGoalAuthority?: "full" | "status"
+
   /** Register collision-safe native `goal` and `goal-verify` agents through OpenCode's config hook. */
   registerAgents?: boolean
 
+  /**
+   * Mirror live goal status into the OpenCode session title, which the TUI
+   * renders persistently (e.g. `▶ ship the release · 3/10 · 2m · 45k/200k`),
+   * giving unattended runs a continuous heartbeat without a TUI plugin.
+   *
+   * The session's original title is captured before the first overwrite and
+   * restored by `/goal clear`. A completed goal renders as `✅ … · N turns · …`
+   * until then. Title updates are cosmetic: a failure is logged at debug level
+   * and never interrupts the goal loop.
+   * @default false
+   */
+  sessionTitleStatus?: boolean
+
+  /**
+   * Agent names treated as planning-only. A goal created while one of these
+   * agents is active is recorded but held paused instead of starting, and
+   * auto-continue stays suppressed while one is active. Matching is
+   * case-insensitive. Pass `[]` to release the restriction entirely.
+   * @default ["plan"]
+   */
+  restrictedAgents?: string[]
+
+  /**
+   * Opt out of the planning-only restriction, allowing goals to be created and
+   * auto-continued while a {@link restrictedAgents} agent is active.
+   * @default false
+   */
+  allowGoalExecutionFromPlan?: boolean
+
   /** Name of the native primary goal agent. @default "goal" */
   goalAgentName?: string
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-plugin",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "description": "Durable, guarded goal workflows for OpenCode.",
   "type": "module",
   "main": "./src/goal-plugin.js",
@@ -75,6 +75,6 @@
     "typescript": "7.0.2"
   },
   "dependencies": {
-    "zod": "4.4.3"
+    "zod": "4.5.4"
   }
 }

package/scripts/verify.mjs

@@ -5,6 +5,10 @@
 // as scripts/smoke-command-hook.mjs.
 
 import assert from "node:assert/strict"
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
 
 const REQUIRED_HOOKS = [
   "config",
@@ -34,6 +38,8 @@ const EXPECTED_TOOLS = [
 
 const results = []
 
+class VerificationWarning extends Error {}
+
 function check(name, fn) {
   return Promise.resolve()
     .then(fn)
@@ -41,6 +47,12 @@ function check(name, fn) {
       results.push({ name, ok: true })
       console.log(`  ✅ ${name}`)
     })
+    .catch((error) => {
+      if (!(error instanceof VerificationWarning)) throw error
+      results.push({ name, ok: true, warning: error.message })
+      console.log(`  ⚠️  ${name}`)
+      console.log(`     ${error.message}`)
+    })
     .catch((error) => {
       results.push({ name, ok: false, error })
       console.log(`  ❌ ${name}`)
@@ -164,6 +176,68 @@ await check("lifecycle transitions are visible without leaking objective text",
   assert.ok(logCalls.every((entry) => !entry.body.message.includes("verify the installation")))
 })
 
+// OpenCode installs an unpinned plugin into its package cache once and never
+// re-resolves `latest` while that directory exists, so a user can run a stale
+// copy long after upgrading on npm. Warn (never fail) when the unpinned cache
+// entries lag the package this script came from.
+function installedPackageVersion() {
+  try {
+    let dir = dirname(createRequire(import.meta.url).resolve("opencode-goal-plugin"))
+    while (dir !== dirname(dir)) {
+      const pkg = join(dir, "package.json")
+      if (existsSync(pkg)) {
+        const json = JSON.parse(readFileSync(pkg, "utf8"))
+        if (json.name === "opencode-goal-plugin") return String(json.version || "")
+      }
+      dir = dirname(dir)
+    }
+  } catch {}
+  return ""
+}
+
+function versionBelow(a, b) {
+  const parse = (v) => String(v).split("-")[0].split(".").map((n) => Number(n) || 0)
+  const [x, y] = [parse(a), parse(b)]
+  for (let i = 0; i < 3; i += 1) {
+    if ((x[i] || 0) !== (y[i] || 0)) return (x[i] || 0) < (y[i] || 0)
+  }
+  return false
+}
+
+await check("OpenCode's cached copy of the plugin is not older than this package", () => {
+  const packageVersion = installedPackageVersion()
+  if (!packageVersion) return
+  const cacheRoots = [
+    process.env.XDG_CACHE_HOME ? join(process.env.XDG_CACHE_HOME, "opencode") : null,
+    join(homedir(), ".cache", "opencode"),
+    process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, "opencode") : null,
+  ].filter(Boolean)
+  const stale = []
+  for (const root of cacheRoots) {
+    const packages = join(root, "packages")
+    if (!existsSync(packages)) continue
+    for (const entry of readdirSync(packages)) {
+      // Only unpinned entries are affected; a pinned older version is a choice.
+      if (entry !== "opencode-goal-plugin" && entry !== "opencode-goal-plugin@latest") continue
+      const pkg = join(packages, entry, "node_modules", "opencode-goal-plugin", "package.json")
+      if (!existsSync(pkg)) continue
+      let cached = ""
+      try {
+        cached = String(JSON.parse(readFileSync(pkg, "utf8")).version || "")
+      } catch {
+        continue
+      }
+      if (cached && versionBelow(cached, packageVersion)) stale.push({ path: join(packages, entry), cached })
+    }
+  }
+  if (!stale.length) return
+  throw new VerificationWarning(
+    `OpenCode is running ${stale.map((s) => `${s.cached} from ${s.path}`).join(" and ")}, older than ${packageVersion}. ` +
+      `OpenCode never re-resolves an unpinned plugin: pin "opencode-goal-plugin@${packageVersion}" in opencode.json, ` +
+      "or delete that cache directory, then restart OpenCode.",
+  )
+})
+
 console.log()
 
 const failed = results.filter((r) => !r.ok)
@@ -172,4 +246,7 @@ if (failed.length > 0) {
   process.exit(1)
 }
 
-console.log(`All ${results.length} checks passed. opencode-goal-plugin is installed correctly.`)
+const warnings = results.filter((r) => r.warning).length
+console.log(
+  `All ${results.length} checks passed${warnings ? ` with ${warnings} warning(s)` : ""}. opencode-goal-plugin is installed correctly.`,
+)