opencode-goal-plugin 0.6.6 → 0.6.8

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.6.8 — 2026-08-02
+
+- Serialize fresh-namespace migration-marker publication across concurrent processes so Windows does not reject competing first-start renames with `EPERM`.
+- Keep a second OpenCode process usable when it opens a session whose goal-state shard is already leased: ordinary chat and unrelated tools remain available, while goal commands and tools fail safely without reading, changing, or prompting from that session's goal state. After the owner exits, the next explicit goal command or tool retries ownership and reloads any active goal paused. Lease contention is now typed and owner metadata is sanitized; unrelated filesystem failures still fail closed.
+- Harden the single-writer lease with immutable per-owner claims so delayed publication, simultaneous stale reclaim, and concurrent release cannot remove a replacement owner's lease. A complete compatibility guard is published atomically with no replacement, preventing old/current startup races; legacy, incomplete, tampered, or unsupported lease layouts fail closed for explicit manual recovery. Owner reads remain bounded and symlink-safe, slow passive command guards keep blocking tools until an authenticated new boundary, delayed control errors cannot pause a newer goal run, takeover retains Plan/model execution context, and advisory host logging cannot stall loading or disposal.
+
+## 0.6.7 — 2026-08-01
+
+- Fix `/goal` routing on OpenCode 1.17.15 and 1.18.10 by replacing the host-retained prompt parts in place, authenticating each resolved command turn (including host-expanded file attachments), framing control results with direct reporting instructions, blocking tools during those reporting turns, and excluding control responses from goal completion and progress analysis. Unreadable command attachments now become read-only error reports and pause safely without losing command provenance.
+- Register all 11 agent-facing goal tools in a standard clean install through the package's direct Zod dependency; a separate optional `@opencode-ai/plugin` install is no longer required.
+
 ## 0.6.6 — 2026-07-29
 
 - Shard persisted goal state and lifecycle ledgers by hashed OpenCode session ID so independent sessions can run concurrently in one project. Keep same-session single-writer leases, lazy session loading, crash recovery, and safe migration of aggregate, legacy, and XDG state.

package/CONTRIBUTING.md

@@ -37,7 +37,7 @@ This plugin depends on OpenCode plugin hooks, including experimental hooks. When
 3. Test against a real OpenCode install when possible.
 4. Update the README compatibility snapshot if the tested surface changes.
 
-`npm run smoke` verifies the package export path and `/goal` command hook without invoking a model. The packed-host and packed-tool checks install the npm artifact in isolated consumer projects and verify the public hook and complete optional-peer tool contracts. `npm run type:check` compiles installed-package consumers with NodeNext and Bundler resolution. `npm run benchmark:behavior` covers deterministic autonomy and token-efficiency scenarios. None replaces a real OpenCode smoke test after hook, SDK, or command behavior changes.
+`npm run smoke` verifies the package export path and `/goal` command hook without invoking a model. The packed-host and packed-tool checks install the npm artifact in isolated consumer projects and verify the public hooks and clean-install default tool contracts. `npm run type:check` compiles installed-package consumers with NodeNext and Bundler resolution. `npm run benchmark:behavior` covers deterministic autonomy and token-efficiency scenarios. None replaces a real OpenCode smoke test after hook, SDK, or command behavior changes.
 
 ## Release checklist
 

package/README.md

@@ -38,7 +38,7 @@ surface and versioning expectations.
 
 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:
 
-| OpenCode Version | Provider Tested | `/goal status` | Auto-continue | Evidence-gated completion | Hook Output Display |
+| OpenCode Version | Provider Tested | `/goal status` | Auto-continue | Evidence-gated completion | v0.6.6 Hook Output Display |
 |---|---|---|---|---|---|
 | 1.17.15 | opencode (`deepseek-v4-flash-free`) | ✅ Canonical tool | ✅ Checkpoint + idle continuation | ✅ Structured `goal_complete` claim | ⚠️ Command text routed to model; mutation guard verified |
 | 1.17.15 | opencode-go (`qwen3.7-plus`) | ✅ | ✅ | ✅ Self-corrected after one rejection (bare `[goal:complete]` with no evidence), then completed cleanly | ⚠️ Not displayed |
@@ -47,7 +47,7 @@ Tested against real OpenCode 1.17.15 processes with live provider credentials an
 
 `/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:** Hook output display depends on OpenCode version — on 1.17.15, `command.execute.before`'s `output.parts` text is not rendered in the TUI for any provider tested; the raw command argument is instead routed to the model as a normal chat turn (see [Limitations](#limitations)). State mutations always work regardless of display: goal creation, flag parsing, auto-continue, limit enforcement, and evidence-gated completion detection were all verified correct via the persisted state file in every combination above. Re-test against your own OpenCode build before relying on unattended runs, and see [`docs/providers.md`](docs/providers.md) for the full per-model marker-compliance notes.
+**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.
 
 ## Install
 
@@ -193,8 +193,8 @@ An ordered sequence, run as a strict pipeline:
 
 ## How it works
 
-1. When you set a goal, the plugin stores it in session memory and injects it into the system prompt so the assistant keeps it in view on every turn.
-2. Each time the session goes idle, the plugin sends a continuation prompt containing the goal, the remaining budget, and a completion audit asking the assistant to verify the current state before declaring done. Continuations retain the agent, provider/model, and variant that initiated the goal. Before sending after a cooldown, the plugin re-checks that the session is still idle and no human message, newer assistant turn, Plan-agent switch, rejected permission, abort, or provider error has superseded the request.
+1. When you set a goal, the plugin stores it in per-session state and replaces the custom-command turn with a plugin-generated work instruction containing that objective. On hosts that invoke `experimental.chat.system.transform`, it also reinforces the active goal in the system prompt; command correctness does not rely on that experimental hook.
+2. Each time the session goes idle, the plugin sends a continuation prompt containing the remaining budget and completion audit while the original goal remains in conversation history. Continuations retain the agent, provider/model, and variant that initiated the goal. Before sending after a cooldown, the plugin re-checks that the session is still idle and no human message, newer assistant turn, Plan-agent switch, rejected permission, abort, or provider error has superseded the request.
 3. The plugin stops auto-continuing when the assistant ends a response with a substantiated `[goal:complete]` or `[goal:blocked]`, or when a safety limit is reached. A `[goal:complete]` is only honored when it is preceded by a `[goal:evidence]` line; a `[goal:blocked]` is only honored when a concrete blocker is stated. Unsubstantiated claims are rejected and the plugin re-prompts for the missing evidence or blocker.
 4. If OpenCode compacts the session, the plugin injects a deterministic summary into the compaction context so the goal survives the compaction and the assistant keeps the thread. The summary — objective, status, budget usage, recent checkpoints, and recent lifecycle events — is reconstructed from the plugin's persisted goal record rather than from chat memory, so it is stable and reproducible. While a goal is active, the plugin also disables OpenCode's generic post-compaction auto-continue so it does not race the plugin's own continuation.
 5. If you send a message of your own while the goal is running, the plugin treats it as the latest instruction, pauses auto-continue, and asks OpenCode to abort an already accepted continuation so it does not talk over you. The plugin's own continuation prompts are ignored for this check (they are not "your" messages). A durable claim on the source assistant turn also prevents different idle event IDs from sending the same continuation twice. Run `/goal resume` to hand control back to the goal loop.
@@ -255,6 +255,10 @@ Alongside each session shard the plugin keeps an **append-only lifecycle ledger*
 
 Recovered active goals are loaded in a **paused** state with a recovery note, so unattended auto-continue does not resume blindly after a restart. Set `"persistState": false` to keep purely in-memory behavior (this also disables the ledger).
 
+Only one OpenCode process may own a given session shard at a time. If the same session is opened in a second process, that process enters **passive goal mode** instead of failing the whole session: ordinary chat and unrelated tools continue to work, but `/goal` commands and goal tools report that another process owns the workflow. Canonical goal tools return the stable envelope code `error: "session_owned_elsewhere"`. The passive process does not read, mutate, persist, or auto-continue that session's goal state. After the owner exits, retry an explicit goal command or goal tool; the process will acquire the shard and load any recovered active goal paused. To work concurrently without waiting, create a new session with `opencode --continue --fork` (or `opencode --session <id> --fork`).
+
+Lease ownership uses immutable per-process claim files so a delayed stale-lock cleanup or duplicate release cannot delete a newer owner's lease. The plugin publishes a complete regular-file compatibility guard atomically at `<shard>/state.json.lock`, then elects the current owner from claims in the sibling `<shard>/state.json.lock.claims-v2/` directory. That no-replace publication makes startup safe against older releases: either the older lock directory wins and the current plugin stays passive, or the guard file wins and the older release cannot reclaim it. Automatic ownership handoff requires the current release. Legacy, incomplete, tampered, or unsupported lease layouts fail closed instead of being rewritten online; filesystems must support regular-file hard links and preserve the guard's future timestamp. After confirming that every process using the session is closed and upgraded, either fork or remove only the affected shard's adjacent `.lock` file or legacy directory **and** `.lock.claims-v2` directory; keep its state and ledger.
+
 `/goal resume` continues the same objective with a fresh local budget window. This lets you continue after pause, blocker, no-progress pause, rate-limit failures, or a limit stop without retyping the objective.
 
 ### Per-goal flags
@@ -323,7 +327,7 @@ Additional plugin-level options:
 - `warnTurnsRemaining` / `warnDurationMsRemaining` / `warnTokensRemaining` — thresholds at which the auto-continue prompt appends a "limits are near" warning (default `3` turns, `60000` ms, `25000` context tokens). Lower them to warn closer to the limit, or raise them to warn earlier.
 - `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`). Requires the optional `@opencode-ai/plugin` peer dependency to be present; when it is absent, tool registration is skipped and the command/event hooks still work. Set to `false` to omit the programmatic tool surface entirely. See [Agent tools](#agent-tools-optional).
+- `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).
 - `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.
@@ -333,9 +337,9 @@ Additional plugin-level options:
 - `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.
 
-## Agent tools (optional)
+## Agent tools
 
-In addition to the `/goal` command, the plugin can expose the same workflow to the model as callable tools, so the agent can inspect and manage the goal itself. This requires the optional `@opencode-ai/plugin` peer dependency (it provides the `tool` helper and schema). When that package isn't installed the tools are simply not registered and everything else keeps working. Disable them explicitly with `registerTools: false`.
+In addition to the `/goal` command, the plugin registers the same workflow as callable model tools by default, so the agent can inspect and manage the goal itself. A normal `opencode-goal-plugin` install includes the schema dependency needed for these definitions; no separate OpenCode helper package is required. Disable the tool surface explicitly with `registerTools: false`.
 
 Registered tools:
 
@@ -346,7 +350,7 @@ Registered tools:
 
 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.
 
-> Integration note: the tool execute-context shape (`ctx.sessionID`) and the `tool.schema` surface follow the OpenCode plugin docs. The tool **logic** is unit-tested independently, but the live registration should be confirmed against a real OpenCode run (see the smoke-test checklist).
+> Integration note: the tool execute-context shape (`ctx.sessionID`) and Zod argument definitions follow the OpenCode plugin docs. The tool **logic** is unit-tested independently, but live registration should still be confirmed against the exact OpenCode host used in production (see the smoke-test checklist).
 
 ## Audit messages
 
@@ -385,11 +389,15 @@ The goal text is wrapped in `<goal_objective>` tags and labeled as user-provided
 
 The assistant still signals candidate outcomes with `[goal:complete]` or `[goal:blocked]`. Completion can additionally be checked by a custom `auditor` callback or the built-in child-session auditor before the goal becomes terminal. Marker quality therefore remains model-dependent when auditing is disabled, and audit quality depends on the configured verifier model and evidence available in the session. The built-in verifier performs static inspection with `read`, `glob`, and `grep`; it cannot execute shell commands.
 
-OpenCode's current `command.execute.before` hook does not fully intercept command text. The plugin can update in-memory goal state as a side effect, but the goal text may still be routed into the normal assistant conversation alongside the state update. The plugin therefore guards `/goal status`, `/goal history`, `/goal list`, `/goal pause`, and `/goal clear` (including its aliases) with `tool.execute.before`: inspection tools remain available, while mutation-capable tools are rejected for that routed command turn. Paused goals also inject a system guard that omits the objective and requires an explicit resume before goal work continues.
+OpenCode custom commands are prompts, not direct plugin-rendered TUI responses. After `command.execute.before` runs, OpenCode sends its retained command-parts array through a normal model turn. The plugin mutates that array in place so the model receives the deterministic plugin-generated result instead of the raw `/goal` argument. The model still produces the visible response and may summarize or paraphrase that result.
+
+Objective-bearing commands preserve file attachments. OpenCode may expand those files into synthetic Read/MCP text and file parts before `chat.message`; the plugin accepts that expansion only when it matches the one-shot command correlation, retained-file count, and generated message/session identity. Other mixed text is treated as a new human instruction and pauses an active loop. If OpenCode reports an attachment-read error during that expansion, the goal pauses with `attachment resolution error` while retaining the correct command provenance.
+
+For `/goal status`, `/goal history`, `/goal list`, `/goal pause`, and `/goal clear` (including aliases), the rewritten user turn carries an escaped control-result envelope with direct instructions to report the supplied data without treating it as new work. `tool.execute.before` rejects every tool call for that reporting turn, and the parent-correlated assistant response is excluded from checkpoint, completion, blocker, and stall analysis. These protections do not depend on the model following the reporting instruction.
 
-The plugin depends on `experimental.chat.system.transform` and other OpenCode plugin hooks that may change between OpenCode versions.
+The plugin still registers `experimental.chat.system.transform` as defense in depth for hosts that invoke it. Real OpenCode 1.17.15 and 1.18.10 do not call that hook, so the command-control protections above are deliberately self-contained. Other OpenCode plugin hooks may change between versions.
 
-Distinct OpenCode sessions may own shards under the same `stateFilePath` concurrently. A second process using the same session shard is still rejected with the owning PID/host instead of risking last-writer-wins state loss; use the original session or wait for its owner to dispose.
+Distinct OpenCode sessions may own shards under the same `stateFilePath` concurrently. A second process using the same session shard remains usable in passive goal mode, but goal commands and tools are denied until it can acquire that shard. The passive process never falls back to an unpersisted copy of the same goal workflow, which avoids divergent state and last-writer-wins data loss. Use the owner, wait and retry an explicit goal control after it exits, or fork to a new session. A no-replace compatibility guard prevents an older release and the current release from both acquiring during startup; current immutable claims protect takeover and release among upgraded processes. Older processes cannot take over a guarded shard, so all processes participating in automatic same-session handoff must run the current release.
 
 ## Diagnostics and recovery
 
@@ -399,9 +407,10 @@ If a goal does not continue:
 
 1. Check for a deliberate pause: user intervention, a hard limit, repeated tool-free/no-progress turns, prompt failures, or a rejected completion audit all stop unattended work by design.
 2. Run `/goal resume` only after resolving the reported reason. Resume creates a fresh local budget window; it does not erase the objective or history.
-3. Check OpenCode's structured logs for persistence, SDK-shape, prompt, or auditor errors.
-4. Confirm the configured project directory and state-path precedence described under [Safety limits](#safety-limits). A daemon started elsewhere can otherwise make a manually configured relative path surprising.
-5. Run `npm run verify`, `npm run smoke`, and `npm run smoke:packed-host` against the installed source when diagnosing registration or packaging problems. Maintainers can run `npm run release:check` for the complete artifact and quality gate. `npm run benchmark:behavior` exercises completion, false-completion, loop, interruption, compaction, and restart behavior without a provider call.
+3. If a goal control reports that another process owns the session, close that owner and retry the control, or fork to a new session. If it instead reports an older, incomplete, tampered, or unsupported lease, close every process that could own the session and upgrade them first; if the report persists, remove only the affected shard's adjacent `.lock` file or legacy directory and `.lock.claims-v2` directory, or fork. Keep the state and ledger. Do not point two copies of the same session at different state paths: that creates divergent goal histories.
+4. Check OpenCode's structured logs for persistence, SDK-shape, prompt, or auditor errors.
+5. Confirm the configured project directory and state-path precedence described under [Safety limits](#safety-limits). A daemon started elsewhere can otherwise make a manually configured relative path surprising.
+6. Run `npm run verify`, `npm run smoke`, and `npm run smoke:packed-host` against the installed source when diagnosing registration or packaging problems. Maintainers can run `npm run release:check` for the complete artifact and quality gate. `npm run benchmark:behavior` exercises completion, false-completion, loop, interruption, compaction, and restart behavior without a provider call.
 
 Do not paste `state.json`, its ledger, or verbose logs into a public issue without reviewing them first: they can contain goal text, assistant checkpoints, blockers, local paths, and command evidence. Prefer the bounded status/history output and redact project-specific content. There is intentionally no broad "dump diagnostics" tool: exposing process-wide session state or persistence paths to the model would add more privacy risk than troubleshooting value.
 

package/docs/compatibility.md

@@ -11,17 +11,47 @@ The latest published release is the supported line. Public compatibility covers:
 - the six canonical goal tools and five legacy tool aliases
 - persisted-state recovery from versions documented in the changelog
 - concurrent persistence for distinct OpenCode sessions in one project, with
-  single-writer protection retained per session
+  single-writer protection retained per session and passive goal behavior for
+  a same-session process that does not own the lease
 
 The package requires Node.js 18 or newer and OpenCode 1.17.15 through the latest
 compatible 1.x release. CI runs the complete unit suite on Node 18, 20, 22, and
 24. Installed-package contracts compile TypeScript consumers using both NodeNext
-and Bundler resolution and load the npm tarball with and without the optional
-`@opencode-ai/plugin` peer.
+and Bundler resolution and require a clean npm-tarball install to expose the
+default agent-tool surface without a separately installed OpenCode helper package.
 
 Filesystem-sensitive lifecycle tests run on Linux, macOS, and Windows. POSIX file
 mode and symbolic-link protections are applied where the operating system supports
 them; the plugin does not claim that Windows provides equivalent POSIX semantics.
+The Windows job also runs the installed-package type, host, and tool contracts
+so their portable npm launcher path is exercised in CI.
+
+When two processes open the same OpenCode session, only the lease owner may read
+or change that session's goal workflow. The contender keeps ordinary chat and
+unrelated tools available, but goal controls are denied and ambient hooks do not
+attempt a takeover. Canonical goal tools return the stable envelope code
+`session_owned_elsewhere`; a `/goal` slash command instead produces a
+human-readable denial through its normal model-rendered command turn. Once the
+owner exits, an explicit goal command or tool may acquire the shard; recovered
+active goals load paused and require an explicit resume. Forking creates a
+distinct session shard and remains the supported way to work concurrently from
+the same conversation.
+
+The immutable-claim lease protocol atomically hard-links a complete regular-file
+compatibility guard at `<shard>/state.json.lock`; active owners publish unique
+claims in the sibling `<shard>/state.json.lock.claims-v2/` directory. Publication
+is no-replace: an older lock directory and the current guard cannot both win the
+same startup race. Older releases treat the future-dated guard as non-reclaimable,
+while current releases determine ownership only from immutable claims. Automatic
+takeover requires all participating processes to run the current release.
+Legacy, incomplete, tampered, or unsupported lease layouts fail closed rather
+than being rewritten online. If that condition persists, first close every
+OpenCode process that could own the session and upgrade them; then either fork
+the session or manually remove only the affected shard's adjacent `.lock` file
+or legacy directory and `.lock.claims-v2` directory. Do not remove its state or
+lifecycle ledger. The local filesystem must support regular-file hard links
+and preserve the guard's future timestamp; the plugin does not fall back to a
+weaker publication protocol.
 
 ## OpenCode host compatibility
 
@@ -31,6 +61,26 @@ generated-client shape, but a real-host smoke test remains required when hook or
 SDK behavior changes. The current manual provider matrix is maintained in
 [providers.md](providers.md).
 
+OpenCode custom commands still become model turns. The plugin handles `/goal`
+arguments in `command.execute.before` and mutates the host-retained parts array
+in place so the turn contains the plugin-generated command result rather than
+raw command text. This makes command routing deterministic, but does not turn the
+hook into a direct-render API: the selected model remains responsible for the
+visible response.
+
+For objective-bearing commands, retained file attachments may be expanded by
+OpenCode into synthetic Read/MCP text and file parts before `chat.message`. The
+plugin correlates that host-resolved shape to the exact one-shot command and
+generated message/session before treating it as plugin-owned. Each retained
+file must yield at least one resolved companion part; a host-reported read error
+pauses the goal without reclassifying the command as human intervention.
+
+OpenCode 1.17.15 and 1.18.10 do not invoke
+`experimental.chat.system.transform`. Control-command correctness therefore
+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.
+
 ## Versioning
 
 Semantic-versioning intent is:

package/docs/providers.md

@@ -12,20 +12,23 @@ vary by provider and model:
    real safety net, not just documentation: a model that initially skips the
    evidence line gets one automatic correction cycle before hitting its
    turn/time/token budget.
-2. **Hook output display** — whether the plugin's own response text (e.g.
-   `No active goal. Set one with...`) is rendered in the OpenCode TUI, or
-   whether the raw command argument is instead routed to the model as a
-   normal chat turn. This is an OpenCode-host behavior, not model-specific,
-   but is included here since it's most visible while testing a new model.
-   See the [OpenCode version compatibility table](../README.md#opencode-version-compatibility)
-   in the README for the current findings.
+2. **Custom-command presentation** — OpenCode sends custom commands through a
+   normal model turn rather than directly rendering plugin-hook output. The
+   plugin now mutates OpenCode's retained command-parts array in place, so that
+   turn contains the deterministic plugin-generated result instead of raw
+   `$ARGUMENTS`. Control results include an escaped reporting frame, backed by
+   tool blocking and lifecycle suppression; the model may still summarize or
+   paraphrase the supplied data.
+   This is primarily host behavior, but it remains worth checking with each
+   provider/backend. See the [OpenCode version compatibility table](../README.md#opencode-version-compatibility)
+   for the historical v0.6.6 findings.
 
 All rows below were verified against real OpenCode processes with live
-provider credentials and no mocked plugin hooks on OpenCode 1.17.15, driving
-the plugin through `/goal status`, `/goal <condition> --max-turns N`, and
-inspecting the plugin's persisted state file to confirm state mutations
-(limit parsing, turn/stop accounting, evidence-gated completion detection)
-independent of what was rendered in the terminal.
+provider credentials and no mocked plugin hooks on OpenCode 1.17.15 before the
+in-place command-parts change. They drove the plugin through `/goal status`,
+`/goal <condition> --max-turns N`, and inspected the persisted state file to
+confirm state mutations (limit parsing, turn/stop accounting, evidence-gated
+completion detection) independent of what was rendered in the terminal.
 
 ## Tested models
 
@@ -64,9 +67,11 @@ Some backends (notably certain Qwen deployments on vLLM, and several
 Llama.cpp/Mistral chat templates) reject a `system` role message that isn't
 the very first message in the conversation, with an error like `"System
 message must be at the beginning."` opencode-goal-plugin's
-`experimental.chat.system.transform` hook merges the goal continuation block
-into the primary system entry instead of appending a separate one, which
-avoids this. This is covered by regression tests in
+`experimental.chat.system.transform` hook, on hosts that invoke it, merges the
+goal continuation block into the primary system entry instead of appending a
+separate one, which avoids this. OpenCode 1.17.15 and 1.18.10 do not invoke that
+experimental hook; command control on those releases uses the self-contained
+reporting frame described above. The merge behavior is covered by regression tests in
 [`test/goal-plugin.test.js`](../test/goal-plugin.test.js) and does not
 require any provider-specific configuration.
 
@@ -91,9 +96,10 @@ specific provider/model:
    before `[goal:complete]`. If not, confirm the plugin rejects it and
    re-prompts with `<evidence_required>` — then check whether the model
    self-corrects within its remaining turn budget, or exhausts it.
-5. Run `/goal status` and check whether the plugin's text (e.g. `No active
-   goal...` or `Active goal: ...`) is rendered directly, or whether the
-   command text was instead routed to the model as a chat turn.
+5. Run `/goal status` and confirm the model turn reports the plugin-generated
+   status rather than interpreting the raw word `status` as a new request.
+   The final wording may be summarized or paraphrased because OpenCode custom
+   commands still run through the selected model.
 6. Cross-check state mutations directly against the persisted state file
    (`.opencode/goals/state.json`, project-local by default) to confirm the
    goal's `options` reflect the flags you passed and `state`/`stopReason`

package/docs/releasing.md

@@ -14,7 +14,7 @@ artifact after all checks pass.
 
 `release:check` runs the unit and coverage suites, consumer type compilation,
 critical mutation contract, behavior benchmark, source and installed-artifact
-smoke tests, full optional-peer tool registration, and package-content check.
+smoke tests, clean-install default tool registration, and package-content check.
 
 ## Publish
 

package/index.d.ts

@@ -282,9 +282,9 @@ export interface GoalPluginOptions {
    * (canonical `goal_status`, `goal_set`, `goal_pause`, `goal_resume`,
    * `goal_block`, `goal_complete`, plus legacy `get_goal`,
    * `get_goal_history`, `set_goal`, `update_goal`, `clear_goal`).
-   * Canonical tools return versioned JSON envelopes. Requires the optional `@opencode-ai/plugin` peer
-   * dependency; when it is absent, tool registration is silently skipped
-   * and the command/event hooks still work.
+   * Canonical tools return versioned JSON envelopes. The tools are registered
+   * by default from dependencies included with this package; set this to
+   * `false` to omit the tool surface.
    * @default true
    */
   registerTools?: boolean
@@ -348,9 +348,19 @@ export interface GoalPluginOptions {
 export interface GoalPluginHooks {
   /** Registers collision-safe native goal and verifier agents. */
   config: (config: unknown) => Promise<void>
-  /** Omitted entirely when {@link GoalPluginOptions.registerCommand} is `false`. */
+  /** Remembers the initiating agent, model, and variant for later continuation turns. */
+  "chat.params": (input: unknown) => Promise<void>
+  /** Distinguishes real user input from plugin-generated command and continuation messages. */
+  "chat.message": (input: unknown, output: unknown) => Promise<void>
+  /**
+   * Handles the configured OpenCode custom command by replacing its retained
+   * prompt parts in place. OpenCode still submits those parts as a model turn
+   * rather than rendering the hook result directly; handled control results
+   * include a self-contained reporting frame. Omitted entirely when
+   * {@link GoalPluginOptions.registerCommand} is `false`.
+   */
   "command.execute.before"?: (input: unknown, output: unknown) => Promise<void>
-  /** Enforces read-only tool behavior when inspection, pause, or clear command text is routed to the model. */
+  /** Blocks tool execution while an already-handled control-command result is being reported. */
   "tool.execute.before": (input: unknown, output: unknown) => Promise<void>
   event: (input: unknown) => Promise<void>
   "experimental.chat.system.transform": (input: unknown, output: unknown) => Promise<void>
@@ -358,8 +368,7 @@ export interface GoalPluginHooks {
   "experimental.session.compacting": (input: unknown, output: unknown) => Promise<void>
   /**
    * Agent-facing tool definitions, present only when
-   * {@link GoalPluginOptions.registerTools} is enabled (default) and the
-   * optional `@opencode-ai/plugin` peer dependency is installed.
+   * {@link GoalPluginOptions.registerTools} is enabled (default).
    */
   tool?: Record<string, unknown>
   /** Cancels pending continuation work and releases this plugin instance. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-plugin",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "Durable, guarded goal workflows for OpenCode.",
   "type": "module",
   "main": "./src/goal-plugin.js",
@@ -55,14 +55,6 @@
     "agent",
     "goal"
   ],
-  "peerDependencies": {
-    "@opencode-ai/plugin": ">=1.17.15 <2"
-  },
-  "peerDependenciesMeta": {
-    "@opencode-ai/plugin": {
-      "optional": true
-    }
-  },
   "license": "MIT",
   "engines": {
     "node": ">=18",
@@ -80,7 +72,9 @@
     "name": "willytop8"
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "1.17.18",
     "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "zod": "4.1.8"
   }
 }

package/scripts/verify.mjs

@@ -8,6 +8,8 @@ import assert from "node:assert/strict"
 
 const REQUIRED_HOOKS = [
   "config",
+  "chat.params",
+  "chat.message",
   "command.execute.before",
   "tool.execute.before",
   "event",
@@ -16,6 +18,20 @@ const REQUIRED_HOOKS = [
   "experimental.session.compacting",
 ]
 
+const EXPECTED_TOOLS = [
+  "clear_goal",
+  "get_goal",
+  "get_goal_history",
+  "goal_block",
+  "goal_complete",
+  "goal_pause",
+  "goal_resume",
+  "goal_set",
+  "goal_status",
+  "set_goal",
+  "update_goal",
+]
+
 const results = []
 
 function check(name, fn) {
@@ -70,11 +86,9 @@ const client = {
 }
 
 let hooks
+let commandMessageCounter = 0
 
 await check(`plugin initializes and registers all ${REQUIRED_HOOKS.length} required hooks`, async () => {
-  // registerTools defaults to true but silently no-ops without the optional
-  // @opencode-ai/plugin peer dependency, so it is not asserted here — the
-  // These hooks are always present regardless of that peer dependency.
   hooks = await GoalPlugin({ client }, { minDelayMs: 1, persistState: false })
   for (const hookName of REQUIRED_HOOKS) {
     assert.equal(
@@ -83,16 +97,42 @@ await check(`plugin initializes and registers all ${REQUIRED_HOOKS.length} requi
       `missing or non-function hook: ${hookName}`,
     )
   }
+  assert.deepEqual(Object.keys(hooks.tool ?? {}).sort(), EXPECTED_TOOLS)
+  for (const name of EXPECTED_TOOLS) {
+    assert.equal(typeof hooks.tool[name].execute, "function", `${name} must be executable`)
+  }
 })
 
 async function runGoalCommand(args) {
-  const output = { parts: [] }
+  // Match OpenCode's host contract: it retains this exact array after the hook
+  // returns, so replacing output.parts would leave the raw command untouched.
+  const hostParts = [{ type: "text", text: args }]
+  commandMessageCounter += 1
+  const messageID = `verify-command-${commandMessageCounter}`
+  const output = {
+    message: { id: messageID, role: "user", sessionID },
+    parts: hostParts,
+  }
   await hooks["command.execute.before"](
     { command: "goal", sessionID, arguments: args },
     output,
   )
-  assert.equal(output.parts.length, 1)
-  assert.equal(output.parts[0].type, "text")
+  assert.strictEqual(output.parts, hostParts)
+  assert.equal(hostParts.length, 1)
+  assert.equal(hostParts[0].type, "text")
+  assert.equal(hostParts[0].synthetic, true)
+  assert.equal(hostParts[0].metadata?.["opencode-goal-plugin"]?.kind, "command")
+  assert.match(hostParts[0].metadata?.["opencode-goal-plugin"]?.id, /^[0-9a-f-]{36}$/)
+  output.parts = hostParts.map((part, index) => ({
+    ...part,
+    id: `verify-command-part-${commandMessageCounter}-${index}`,
+    messageID,
+    sessionID,
+  }))
+  await hooks["chat.message"](
+    { sessionID, messageID, agent: "build", model: { providerID: "test", modelID: "test" } },
+    output,
+  )
   return output.parts[0].text
 }
 
@@ -106,6 +146,7 @@ await check("/goal set works", async () => {
   assert.match(text, /New active goal: verify the installation/)
   const statusText = await runGoalCommand("status")
   assert.match(statusText, /Active goal: verify the installation/)
+  assert.doesNotMatch(statusText, /State: Paused/)
 })
 
 await check("no model calls were made during verification", () => {