opencode-goal-plugin 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.6.2 — 2026-07-11
+
+- Keep paused, blocked, and crash-recovered goals inert in model turns with a stopped-goal system guard, and enforce status/history/list/pause/clear control turns as read-only through the host's tool-execution hook so routed command text cannot mutate or resurrect work.
+- Add installed-package TypeScript and full tool-surface contracts, critical mutation testing, generated lifecycle-model testing, Linux/macOS/Windows filesystem CI, CodeQL, dependency updates, and a verified release workflow.
+- Preserve multi-goal creation order when a paused goal resumes; execution epochs rotate through `runId` while the public `goalId` remains stable.
+- Document the supported compatibility surface, release integrity process, and private vulnerability reporting path.
+
 ## 0.6.1 — 2026-07-10
 
 - Default-deny verifier tools except read/glob/grep, and fail closed unless the owned verifier agent registers successfully.
@@ -9,7 +16,7 @@
 - Prevent mutating SDK shape retries, validate child-session ancestry, and make auditor timeout independent of a hanging abort.
 - Move context-budget reset to the successful `session.compacted` event and prevent ordered goals from reusing a prior goal's completion message.
 - Drain accepted persistence writes before disposal, suppress late disposed-instance writes, and re-check goal identity after asynchronous audits/announcements.
-- Harden persistence recovery with bounded hostile-state parsing, cross-session-safe ledger identities, multi-goal snapshots, archive restoration, corrupt-state quarantine, stale malformed-lock recovery, symlink-safe ledger appends, and exclusive one-project legacy migration with preserved backups.
+- Improve persistence recovery with bounded hostile-state parsing, cross-session-safe ledger identities, multi-goal snapshots, archive restoration, corrupt-state quarantine, stale malformed-lock recovery, symlink-safe ledger appends, and exclusive one-project legacy migration with preserved backups.
 - Fail closed when neither terminal state nor ledger can be persisted; keep the goal paused instead of claiming archival.
 - Preserve paused time for queued/backgrounded goals, expose an opt-out for the tool-free heuristic, honor host `tokens.total`, and improve multi-step usage/cost availability accounting.
 - Add conditional TypeScript export mappings, an OpenCode engine range, honest auditor/visibility documentation, and cache-safe near-limit continuation warnings.
@@ -122,7 +129,7 @@
 
 ## 0.4.0 — 2026-06-21
 
-- **Expose agent-facing goal tools (`get_goal`, `get_goal_history`, `set_goal`, `update_goal`, `clear_goal`)** when the host provides `@opencode-ai/plugin` (a new *optional* peer dependency, loaded via a cached dynamic import so the zero-runtime-dependency posture is preserved). `set_goal` is constrained by its description to explicit user requests (so the agent does not set goals on its own); it accepts optional `maxTurns` / `maxTokens` / `maxDurationMs` overrides plus `successCriteria` / `constraints` / `mode`. `update_goal` supports objective edits and `complete` / `blocked` / `paused` / `resumed` transitions (with `evidence` / `blocker`). Tools create, replace, and clear goals through the **multi-goal registry** (the same `buildGoalState` → `registerSessionGoal` → `focusGoal` path the `/goal` command uses), so tool-created goals persist, appear in `/goal list`, and are driven by the idle handler; `complete` archives with evidence and auto-promotes the next goal in an ordered (sisyphus) sequence. Registration is skipped gracefully when the package is absent or with `registerTools: false`. New `buildAgentToolHandlers` / `buildAgentTools` / `agentToolSessionID` helpers. Implements megalist items 7.1 and 7.2. _(This is the work the 0.3.0 changelog mistakenly listed as already shipped; it is now actually implemented and adapted to the current multi-goal architecture.)_
+- **Expose agent-facing goal tools (`get_goal`, `get_goal_history`, `set_goal`, `update_goal`, `clear_goal`)** when the host provides `@opencode-ai/plugin` (a new *optional* peer dependency, loaded via a cached dynamic import so the zero-runtime-dependency posture is preserved). `set_goal` is constrained by its description to explicit user requests (so the agent does not set goals on its own); it accepts optional `maxTurns` / `maxTokens` / `maxDurationMs` overrides plus `successCriteria` / `constraints` / `mode`. `update_goal` supports objective edits and `complete` / `blocked` / `paused` / `resumed` transitions (with `evidence` / `blocker`). Tools create, replace, and clear goals through the **multi-goal registry** (the same `buildGoalState` → `registerSessionGoal` → `focusGoal` path the `/goal` command uses), so tool-created goals persist, appear in `/goal list`, and are driven by the idle handler; `complete` archives with evidence and auto-promotes the next goal in an ordered (sisyphus) sequence. Registration is skipped gracefully when the package is absent or with `registerTools: false`. New `buildAgentToolHandlers` / `buildAgentTools` / `agentToolSessionID` helpers. _(This is the work the 0.3.0 changelog mistakenly listed as already shipped; it is now actually implemented and adapted to the current multi-goal architecture.)_
 - **Fix a goal-registry leak when resuming.** `resetGoalBudget` rotates a goal's `goalId`, but the multi-goal registry is keyed by `goalId`, so resuming and then clearing/replacing left a stale entry behind (visible in `/goal list` and persisted). Both the `/goal resume` command path and the agent `update_goal {status:"resumed"}` path now re-key the registry to the new id (the focused pointer holds the same object). Regression test added for the command path.
 
 ## 0.3.0 — 2026-06-14
@@ -131,35 +138,35 @@
 
 ### Completion integrity & audit
 
-- **Require evidence to complete a goal and a concrete blocker to block one.** A `[goal:complete]` marker is now only honored when the assistant also supplies a non-empty `[goal:evidence] <summary>` line (on or before the completion marker); a `[goal:blocked]` is only honored when a concrete blocker is stated on the line before it. An unsubstantiated `[goal:complete]` or `[goal:blocked]` is rejected (not recorded / does not stop the goal) and the plugin sends a corrective continuation prompt demanding the missing evidence or blocker. The accepted evidence is stored on the result and shown in `/goal status` / `/goal history`. New `extractCompletionEvidence` helper, an `<evidence_required>` structural tag (added to the injection-escaping set), and continuation/system/compaction/creation prompts all updated to instruct the evidence requirement. Implements megalist item 2.1.
-- **Add an optional separate completion auditor that verifies before archival.** When a completion auditor is configured, a `[goal:complete]` (with evidence) is verified before the goal is archived: on approval it archives as achieved, on rejection the goal is *restored* (paused with stop reason `audit rejected` and the reason surfaced) rather than archived. Enable the built-in auditor — which spawns an independent OpenCode child session that replies `[audit:approved]`/`[audit:rejected]` — with `completionAudit: true`, or supply a custom `auditor({ goal, sessionID, latestText }) => { approved, reason }` (takes precedence). The built-in child-session auditor fails open if the session API is unavailable; a custom auditor that throws is treated as a rejection (fail closed). New `parseAuditVerdict` / `buildAuditPrompt` / `createChildSessionAuditor` helpers. Off by default. Implements megalist item 2.2.
-- **Announce completion/blocker audits with visible messages instead of silent background work.** When the assistant marks a goal complete or blocked, the plugin emits an audit-start and an audit-result message (e.g. "Auditing goal completion…" → "Audit result: completion accepted — goal archived"). Delivery defaults to OpenCode's structured log (`client.app.log`) and is pluggable via an `auditMessenger(sessionID, text)` option or disable-able with `auditMessages: false`. New `defaultAuditMessenger` helper. Implements megalist item 2.4.
+- **Require evidence to complete a goal and a concrete blocker to block one.** A `[goal:complete]` marker is now only honored when the assistant also supplies a non-empty `[goal:evidence] <summary>` line (on or before the completion marker); a `[goal:blocked]` is only honored when a concrete blocker is stated on the line before it. An unsubstantiated `[goal:complete]` or `[goal:blocked]` is rejected (not recorded / does not stop the goal) and the plugin sends a corrective continuation prompt demanding the missing evidence or blocker. The accepted evidence is stored on the result and shown in `/goal status` / `/goal history`. New `extractCompletionEvidence` helper, an `<evidence_required>` structural tag (added to the injection-escaping set), and continuation/system/compaction/creation prompts all updated to instruct the evidence requirement.
+- **Add an optional separate completion auditor that verifies before archival.** When a completion auditor is configured, a `[goal:complete]` (with evidence) is verified before the goal is archived: on approval it archives as achieved, on rejection the goal is *restored* (paused with stop reason `audit rejected` and the reason surfaced) rather than archived. Enable the built-in auditor — which spawns an independent OpenCode child session that replies `[audit:approved]`/`[audit:rejected]` — with `completionAudit: true`, or supply a custom `auditor({ goal, sessionID, latestText }) => { approved, reason }` (takes precedence). In this release, the built-in child-session auditor approved when the session API was unavailable; later releases changed operational failures to reject by default. A custom auditor that throws is treated as a rejection. New `parseAuditVerdict` / `buildAuditPrompt` / `createChildSessionAuditor` helpers. Off by default.
+- **Announce completion/blocker audits with visible messages instead of silent background work.** When the assistant marks a goal complete or blocked, the plugin emits an audit-start and an audit-result message (e.g. "Auditing goal completion…" → "Audit result: completion accepted — goal archived"). Delivery defaults to OpenCode's structured log (`client.app.log`) and is pluggable via an `auditMessenger(sessionID, text)` option or disable-able with `auditMessages: false`. New `defaultAuditMessenger` helper.
 
 ### Durability
 
-- **Add an append-only JSONL lifecycle ledger with state reconstruction, and fail-closed terminal-state persistence.** Every lifecycle event (`pushHistory`) is also appended as one JSON line to `<stateFile>.ledger.jsonl` (synchronous, owner-only `0600`). Because in-memory history is capped, the ledger is the durable record: when the main state file is missing on startup, the plugin reconstructs still-active (non-`completed`/`cleared`) goals from the ledger and reloads them paused (new `reconstructed` load status). Terminal events are written to the ledger before the main state write, so a goal's terminal outcome survives a failed state write (fail-closed); `persistState` now returns success/failure and a failed terminal persist is logged at error level. Tied to `persistState`. New `appendLedgerLine` / `readLedgerEntries` / `reconstructGoalsFromLedger` helpers. Implements megalist items 2.3 and 2.5.
-- **Build the compaction summary deterministically from the persisted goal record.** `buildCompactionContext` folds in a reproducible progress summary — recent checkpoints and lifecycle events — derived from the goal's persisted `checkpoints`/`history` (new `buildCompactionProgressSummary` helper) rather than chat memory, and labels it as such. Implements megalist item 6.3.
+- **Add an append-only JSONL lifecycle ledger with state reconstruction, and fail-closed terminal-state persistence.** Every lifecycle event (`pushHistory`) is also appended as one JSON line to `<stateFile>.ledger.jsonl` (synchronous, owner-only `0600`). Because in-memory history is capped, the ledger is the durable record: when the main state file is missing on startup, the plugin reconstructs still-active (non-`completed`/`cleared`) goals from the ledger and reloads them paused (new `reconstructed` load status). Terminal events are written to the ledger before the main state write, so a goal's terminal outcome survives a failed state write (fail-closed); `persistState` now returns success/failure and a failed terminal persist is logged at error level. Tied to `persistState`. New `appendLedgerLine` / `readLedgerEntries` / `reconstructGoalsFromLedger` helpers.
+- **Build the compaction summary deterministically from the persisted goal record.** `buildCompactionContext` folds in a reproducible progress summary — recent checkpoints and lifecycle events — derived from the goal's persisted `checkpoints`/`history` (new `buildCompactionProgressSummary` helper) rather than chat memory, and labels it as such.
 
 ### Auto-continue guardrails
 
-- **Pause auto-continue on repeated tool-free continuation turns (no-tool-call gate).** Complementing the low-output no-progress check, the plugin tracks continuation turns whose assistant message has no tool calls (OpenCode `tool` / `subtask` parts) and, after `noToolCallTurnsBeforePause` consecutive such turns (default `2`), pauses with stop reason `no tool calls` to guard against self-chat loops. A tool-using turn resets the counter. Configurable via the `noToolCallTurnsBeforePause` option and `--no-tool-turns <n>` flag. New `messageHasToolCall` helper. Implements megalist item 5.1.
-- **Pause auto-continue when a real user message arrives ("latest instruction wins").** The idle handler detects a genuine human message that arrived after the plugin's most recent continuation and pauses the goal (stop reason `user intervention`) instead of talking over the user; `/goal resume` hands control back. Plugin-generated continuation prompts (user-role messages framed in `<goal_continuation>`) are ignored, and detection requires `turnCount > 0` plus a visible plugin continuation so the first idle and scrolled-out sessions are never misread. New `isPluginContinuationMessage` / `userInterventionDetected` helpers. Implements megalist items 5.2 and 5.3.
+- **Pause auto-continue on repeated tool-free continuation turns (no-tool-call gate).** Complementing the low-output no-progress check, the plugin tracks continuation turns whose assistant message has no tool calls (OpenCode `tool` / `subtask` parts) and, after `noToolCallTurnsBeforePause` consecutive such turns (default `2`), pauses with stop reason `no tool calls` to guard against self-chat loops. A tool-using turn resets the counter. Configurable via the `noToolCallTurnsBeforePause` option and `--no-tool-turns <n>` flag. New `messageHasToolCall` helper.
+- **Pause auto-continue when a real user message arrives ("latest instruction wins").** The idle handler detects a genuine human message that arrived after the plugin's most recent continuation and pauses the goal (stop reason `user intervention`) instead of talking over the user; `/goal resume` hands control back. Plugin-generated continuation prompts (user-role messages framed in `<goal_continuation>`) are ignored, and detection requires `turnCount > 0` plus a visible plugin continuation so the first idle and scrolled-out sessions are never misread. New `isPluginContinuationMessage` / `userInterventionDetected` helpers.
 
 ### Multiple goals
 
-- **Support multiple goals per session with `/goal add`, `/goal list`, and `/goal focus`.** A session can hold several live goals via a new `sessionGoals` registry; `goalStates` continues to track the single *focused* goal the idle handler drives. `/goal <condition>` replaces the focused goal; `/goal add <condition>` backgrounds the current goal and focuses a new one (only the focused goal auto-continues). `/goal list` shows numbered live goals plus a per-session archive of completed/cleared goals, and `/goal focus <number|id>` switches the active goal (numeric refs are index-only). Focus is tracked per session and persisted (state files gain a per-goal `focused` flag and an `archives` array; older single-goal files load with their goal focused). New `buildGoalState` / `formatGoalList` / session-registry helpers. Implements megalist items 3.1, 3.2, and 3.3.
-- **Add `/goal sisyphus` ordered goal sequences.** `/goal sisyphus <obj 1>; <obj 2>; …` sets up a strict execution sequence: the first objective is focused and the rest queued, and when the focused goal completes the plugin auto-promotes the next until the sequence is exhausted. The ordered flag is tracked per session, shown in `/goal list`, persisted (`orderedSessions`), and cleared by `/goal clear`. New `promoteNextOrderedGoal` helper. Implements megalist item 3.4.
+- **Support multiple goals per session with `/goal add`, `/goal list`, and `/goal focus`.** A session can hold several live goals via a new `sessionGoals` registry; `goalStates` continues to track the single *focused* goal the idle handler drives. `/goal <condition>` replaces the focused goal; `/goal add <condition>` backgrounds the current goal and focuses a new one (only the focused goal auto-continues). `/goal list` shows numbered live goals plus a per-session archive of completed/cleared goals, and `/goal focus <number|id>` switches the active goal (numeric refs are index-only). Focus is tracked per session and persisted (state files gain a per-goal `focused` flag and an `archives` array; older single-goal files load with their goal focused). New `buildGoalState` / `formatGoalList` / session-registry helpers.
+- **Add `/goal sisyphus` ordered goal sequences.** `/goal sisyphus <obj 1>; <obj 2>; …` sets up a strict execution sequence: the first objective is focused and the rest queued, and when the focused goal completes the plugin auto-promotes the next until the sequence is exhausted. The ordered flag is tracked per session, shown in `/goal list`, persisted (`orderedSessions`), and cleared by `/goal clear`. New `promoteNextOrderedGoal` helper.
 
 ### Schema & command UX
 
-- **Add success-criteria, constraints/non-goals, and mode to the goal schema.** A goal can carry `successCriteria` (`--success`), `constraints` (`--constraints` / `--non-goals`), and a `mode` of `normal` or `ordered` (`--mode`, `sisyphus` alias). These thread through state, persistence, the injected goal block (escaped, new `success_criteria` / `constraints` structural tags), creation output, and `/goal status`. New `normalizeMode` helper. Implements megalist items 4.1, 4.2, and 4.3.
-- **Add an inline `--budget <n>` flag** on the create command — a shorthand for the context-token limit accepting a plain integer or `k`/`m` suffix (e.g. `--budget 100k`). New `parseTokenBudget` helper. Implements megalist item 8.1.
-- **Make the slash command configurable (`commandName`) and optional (`registerCommand`).** `commandName` (default `goal`, leading slash tolerated) lets the plugin own e.g. `/objective`, with all user-facing hints following the configured name; `registerCommand: false` skips installing the command hook entirely. New `normalizeCommandOptions` helper. Implements megalist item 8.2.
+- **Add success-criteria, constraints/non-goals, and mode to the goal schema.** A goal can carry `successCriteria` (`--success`), `constraints` (`--constraints` / `--non-goals`), and a `mode` of `normal` or `ordered` (`--mode`, `sisyphus` alias). These thread through state, persistence, the injected goal block (escaped, new `success_criteria` / `constraints` structural tags), creation output, and `/goal status`. New `normalizeMode` helper.
+- **Add an inline `--budget <n>` flag** on the create command — a shorthand for the context-token limit accepting a plain integer or `k`/`m` suffix (e.g. `--budget 100k`). New `parseTokenBudget` helper.
+- **Make the slash command configurable (`commandName`) and optional (`registerCommand`).** `commandName` (default `goal`, leading slash tolerated) lets the plugin own e.g. `/objective`, with all user-facing hints following the configured name; `registerCommand: false` skips installing the command hook entirely. New `normalizeCommandOptions` helper.
 
 ### Storage, tools & packaging
 
-- **Default goal state to a project-local path, with an env override and migration fallbacks.** State resolves as `stateFilePath` option → `OPENCODE_GOAL_STATE_PATH` env var → project-local `<cwd>/.opencode/goals/state.json` (previously `~/.opencode-goal-plugin/state.json`). When the default path is empty, the plugin migrates forward on first load from the legacy home path and the XDG path, then writes project-local. Explicit option/env paths are literal with no fallback; a present-but-corrupt primary is preserved. New `resolveStateFilePath` / `xdgStateFilePath` / `legacyStateFilePaths` helpers. Home-based fallback paths resolve from an injectable `env.HOME` (falling back to `os.homedir()`), making path resolution deterministic across platforms — `os.homedir()` ignores `$HOME` on macOS. Implements megalist items 6.1 and 6.2.
-- _**Correction (2026-06-21):** an earlier version of this entry claimed agent-facing goal tools shipped in 0.3.0. They did not — the work was on an unmerged branch (`wr/agent-tools`) and was never included in the 0.3.0 release. The feature now actually ships; see the **0.6.0** section above. Megalist items 7.1 and 7.2._
+- **Default goal state to a project-local path, with an env override and migration fallbacks.** State resolves as `stateFilePath` option → `OPENCODE_GOAL_STATE_PATH` env var → project-local `<cwd>/.opencode/goals/state.json` (previously `~/.opencode-goal-plugin/state.json`). When the default path is empty, the plugin migrates forward on first load from the legacy home path and the XDG path, then writes project-local. Explicit option/env paths are literal with no fallback; a present-but-corrupt primary is preserved. New `resolveStateFilePath` / `xdgStateFilePath` / `legacyStateFilePaths` helpers. Home-based fallback paths resolve from an injectable `env.HOME` (falling back to `os.homedir()`), making path resolution deterministic across platforms — `os.homedir()` ignores `$HOME` on macOS.
+- _**Correction (2026-06-21):** an earlier version of this entry claimed agent-facing goal tools shipped in 0.3.0. They did not — the work was on an unmerged branch (`wr/agent-tools`) and was never included in the 0.3.0 release. The feature now ships; see the **0.4.0** section above._
 - **Release automation note.** Development included a proposed npm Trusted Publishing workflow, but `.github/workflows/publish.yml` was not part of the final release history and is not present in the current repository. Releases therefore remain manual unless a separately reviewed publishing workflow is added. No package is published solely by the CI workflow documented in this repository.
 
 ## 0.2.0 — 2026-06-14

package/CONTRIBUTING.md

@@ -15,8 +15,11 @@ Run the local checks before submitting changes:
 ```sh
 npm test
 npm run test:coverage
+npm run type:check
+npm run test:mutation
 npm run smoke
 npm run smoke:packed-host
+npm run smoke:packed-tools
 npm run benchmark:behavior
 npm run verify
 npm run check
@@ -30,25 +33,19 @@ For behavior changes, add or update tests in `test/goal-plugin.test.js`.
 This plugin depends on OpenCode plugin hooks, including experimental hooks. When changing hook usage, command behavior, or system-prompt transforms:
 
 1. Check the current OpenCode plugin and command documentation.
-2. Run `npm run smoke` and `npm run smoke:packed-host` to verify the source and installed-tarball host contracts.
+2. Run `npm run smoke`, `npm run smoke:packed-host`, `npm run smoke:packed-tools`, and `npm run type:check` to verify the source and installed-tarball contracts.
 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. `npm run smoke:packed-host` installs the packed artifact in an isolated directory and checks the public hook/tool contract. `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 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.
 
 ## Release checklist
 
-Before publishing or tagging a release:
-
-- update `CHANGELOG.md`
-- run `npm test`
-- run `npm run test:coverage`
-- run `npm run smoke`
-- run `npm run smoke:packed-host`
-- run `npm run benchmark:behavior`
-- run `npm run verify`
-- run `npm run check`
-- run `npm run pack:check`
+Before publishing or tagging a release, follow [the release process](docs/releasing.md). The required automated gate is:
+
+- run `npm ci`
+- update `CHANGELOG.md` and both package-version files
+- run `npm run release:check`
 - perform at least one manual OpenCode smoke test if hook behavior changed
 - refresh compatibility notes if the tested OpenCode surface changed
 

package/README.md

@@ -3,10 +3,10 @@
 [![npm version](https://img.shields.io/npm/v/opencode-goal-plugin)](https://www.npmjs.com/package/opencode-goal-plugin)
 [![npm downloads](https://img.shields.io/npm/dm/opencode-goal-plugin)](https://www.npmjs.com/package/opencode-goal-plugin)
 [![CI](https://github.com/willytop8/OpenCode-goal-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/willytop8/OpenCode-goal-plugin/actions/workflows/ci.yml)
-[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](test/)
+[![CodeQL](https://github.com/willytop8/OpenCode-goal-plugin/actions/workflows/codeql.yml/badge.svg)](https://github.com/willytop8/OpenCode-goal-plugin/actions/workflows/codeql.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-An experimental session-scoped `/goal` command for [OpenCode](https://opencode.ai/).
+A session-scoped `/goal` workflow for [OpenCode](https://opencode.ai/).
 
 Set a goal and the plugin keeps it in context, auto-continues the session whenever the assistant goes idle, and stops when the goal is marked complete, a blocker is reported, or a safety limit is reached.
 
@@ -27,9 +27,13 @@ This project is independently implemented for OpenCode. Product names used elsew
 | Surface | Status |
 |---|---|
 | Node.js | Declared support: `>=18`; CI covers Node 18, 20, 22, and 24 |
-| Package entrypoint | `npm run smoke` verifies the package export path plus `/goal` command-hook behavior from a local install without invoking a model |
+| 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 |
 
+See the [compatibility policy](docs/compatibility.md) for the supported public
+surface and versioning expectations.
+
 ### OpenCode version compatibility
 
 Manually tested via the OpenCode TUI (`tmux` + real provider credentials, no mocks), verified against the plugin's own persisted state rather than terminal display alone:
@@ -380,7 +384,7 @@ 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.
+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.
 
 The plugin depends on `experimental.chat.system.transform` and other OpenCode plugin hooks that may change between OpenCode versions.
 
@@ -396,7 +400,7 @@ If a goal does not continue:
 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. `npm run benchmark:behavior` exercises completion, false-completion, loop, interruption, compaction, and restart behavior without a provider call.
+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.
 
 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.
 
@@ -427,12 +431,16 @@ Keep test files outside OpenCode's auto-loaded plugin directory — OpenCode wil
 ```sh
 npm test                # run the test suite
 npm run test:coverage   # run tests with coverage
+npm run type:check      # compile installed-package consumers
+npm run test:mutation   # prove critical regressions are detected
 npm run smoke           # verify package export + command hook without a model call
 npm run smoke:packed-host # install the packed tarball and exercise the host contract
+npm run smoke:packed-tools # verify all tools from an installed tarball
 npm run benchmark:behavior # deterministic autonomy + token-efficiency scenarios
 npm run verify          # verify the installed plugin hook surface
 npm run check           # syntax check + tests
 npm run pack:check      # verify package contents before publishing
+npm run release:check   # run the complete release gate
 ```
 
 ## License

package/SECURITY.md

@@ -2,18 +2,16 @@
 
 ## Supported Versions
 
-This project is experimental. Security fixes are provided for the latest published version only.
+Security fixes are provided for the latest published version only. Users should
+upgrade to the newest patch release before reporting a vulnerability.
 
 ## Reporting a Vulnerability
 
-GitHub private vulnerability reporting may not always be enabled for this repository.
-
-Until a dedicated private reporting channel is documented here, do **not** open a public issue with exploit details, credentials, local paths, or reproduction steps that could expose user data or local system access.
-
-Instead:
-
-1. open a minimal public issue asking for a private contact path, or
-2. contact the maintainer through their GitHub profile and request a private handoff.
+Use [GitHub's private vulnerability report](https://github.com/willytop8/OpenCode-goal-plugin/security/advisories/new).
+Do **not** open a public issue with exploit details, credentials, local paths, or
+reproduction steps that could expose user data or local system access. If private
+reporting is temporarily unavailable, contact the maintainer through their GitHub
+profile and request a private handoff.
 
 ## Scope
 

package/docs/compatibility.md

@@ -0,0 +1,41 @@
+# Compatibility policy
+
+## Supported package surface
+
+The latest published release is the supported line. Public compatibility covers:
+
+- the package root and `opencode-goal-plugin/server` ESM exports
+- the declarations exported by `index.d.ts`
+- the documented `GoalPluginOptions` fields
+- the documented OpenCode hook names
+- the six canonical goal tools and five legacy tool aliases
+- persisted-state recovery from versions documented in the changelog
+
+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.
+
+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.
+
+## OpenCode host compatibility
+
+OpenCode's experimental hooks and SDK request shapes may change within the 1.x
+line. Automated tests cover both current flattened session inputs and the legacy
+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).
+
+## Versioning
+
+Semantic-versioning intent is:
+
+- patch: compatible fixes, documentation, and stronger verification
+- minor: backward-compatible options, hooks, commands, or tools
+- major: removal or incompatible change to a documented public surface
+
+`testInternals` is exported for diagnostics and the project's own tests; it is not
+part of the semantic-version compatibility guarantee.

package/docs/providers.md

@@ -20,9 +20,9 @@ vary by provider and model:
    See the [OpenCode version compatibility table](../README.md#opencode-version-compatibility)
    in the README for the current findings.
 
-All rows below were verified manually against the real OpenCode TUI (`tmux`
-+ live provider credentials, no mocks) on OpenCode 1.17.15, driving the
-plugin through `/goal status`, `/goal <condition> --max-turns N`, and
+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.
@@ -31,10 +31,29 @@ independent of what was rendered in the terminal.
 
 | Provider | Model | Marker compliance | Notes |
 |---|---|---|---|
+| `opencode` | `deepseek-v4-flash-free` | ✅ Canonical tools | OpenCode 1.17.15, isolated HOME/XDG/project, loading the exact 0.6.2 branch source by file URL. In a real interactive PTY, the model fixed an intentionally failing two-test project, ran the tests to 2/2 passing, and completed through `goal_complete`. A second goal checkpointed after writing `step-1`; the plugin ledger then recorded `auto-continue 1/2`, after which the model wrote and verified `step-2` and completed. Sessions: `ses_0b021d93affeCsNvWkmJWwZzF2` and `ses_0b01f3767ffej4Mn6DMSWft0aX`. `/goal status` text was routed to the model by this host version, which then called `goal_status`; the persisted ledger remained authoritative. |
 | `opencode-go` | `qwen3.7-plus` | ✅ Self-corrects | First attempt emitted bare `[goal:complete]` with no evidence line and was correctly rejected by the plugin. On the very next turn it read the `<evidence_required>` re-prompt, added a `[goal:evidence]` line, and completed cleanly — a good demonstration of the evidence gate actually improving behavior rather than just failing closed. |
 | `opencode-go` | `glm-5.2` | ✅ Clean | Emitted a correct `[goal:evidence] ... [goal:complete]` pair on the first attempt. (An earlier plugin version without the evidence requirement showed GLM-5.2 sometimes trailing extra text after a bare marker — the more structured `<completion_audit>` prompt this plugin version sends appears to help.) |
 | `deepseek` | `deepseek-chat` | ✅ Clean | Emitted a correct `[goal:evidence] ... [goal:complete]` pair on the first attempt, both in a short synthetic goal and in the full [demo](../demo/) (autonomously located and fixed a real bug, then reported evidence-backed completion). Correctly parses per-goal flags (`--max-turns`, etc.) out of the condition text. |
 
+## OpenCode 1.17.15 lifecycle canaries
+
+The `opencode/deepseek-v4-flash-free` row was also exercised through an
+isolated project, HOME, and XDG directories while loading the exact 0.6.2
+source by `file://` URL. Persisted state, ledger entries, and file contents
+were checked independently of the model's prose.
+
+| Scenario | Result | Evidence |
+|---|---|---|
+| Normal completion | ✅ Pass | `ses_0b021d93affeCsNvWkmJWwZzF2`: fixed an intentionally failing project, reran 2/2 tests, and completed with structured evidence. |
+| Idle auto-continuation | ✅ Pass | `ses_0b01f3767ffej4Mn6DMSWft0aX`: checkpointed `step-1`, ledger recorded auto-continue 1/2, then verified `step-2` and completed. |
+| Pause and explicit resume across processes | ✅ Pass | `ses_0b01470c1ffeug0LX69fageiVm`: remained paused between OpenCode invocations; explicit resume released it and completion was archived. |
+| Concrete blocker and restart | ✅ Pass | `ses_0b013a903ffeg3I6tGbArE2b5E`: stopped with the missing approval-file reason and did not auto-continue after a fresh process loaded it. |
+| Hard process interruption and recovery | ✅ Pass | `ses_0b00b37a8ffeDrBshGDutFTqUm`: a running process was terminated during a shell wait; restart recovered paused, status blocked a stale `goal_resume`, the file stayed unchanged, and a later explicit resume completed. |
+| Real host compaction | ✅ Pass | `ses_0b00958e3ffekLLH5ztkkvHIPL`: the documented session summarize endpoint returned `true`; exported session data contained a real compaction part plus injected goal/checkpoint context, token accounting reset, and the paused goal resumed cleanly. |
+| Clear with stale conversation history | ✅ Pass | `ses_0affb9235ffeWl5LuZxXmvhSfM`: after command-side clearing, the routed model turn attempted `clear_goal` and `goal_resume`; the tool hook rejected all attempts, the file remained `before-clear`, and no goal survived in state. |
+| Interactive Esc during a running shell tool | ⚠️ Not established | Esc sent through the automated PTY did not interrupt OpenCode's shell tool. Hard-process recovery is verified above and host-abort hooks have deterministic tests, but this specific TUI input path is not claimed as passed. |
+
 Untested at time of writing: `deepseek-reasoner`, `mistral/*`, `openrouter/*`,
 and any `nvidia`/`google` provider — add rows here as they're verified. See
 [Testing a new model](#testing-a-new-model) below.

package/docs/releasing.md

@@ -0,0 +1,41 @@
+# Release process
+
+Releases are deliberately verified before they are published. GitHub Actions does
+not publish to npm automatically; the maintainer reviews and publishes the exact
+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.
+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.
+
+`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.
+
+## Publish
+
+After the commit is reviewed and CI is green, create and push an annotated
+`vX.Y.Z` tag at the same commit. The release workflow rejects a tag whose version
+does not match `package.json`, reruns the complete release gate, and retains the
+verified npm tarball as a workflow artifact.
+
+Download that artifact, inspect it, and publish the tarball itself:
+
+```sh
+npm publish opencode-goal-plugin-X.Y.Z.tgz --access public
+```
+
+Confirm the registry digest and unpacked contents match the locally reviewed
+artifact before drafting the GitHub release notes. Never rebuild or edit an
+artifact after it has been published; prepare a new patch release instead.
+
+## Trusted publishing
+
+For a future fully automated publish, configure npm Trusted Publishing for this
+repository and a narrowly scoped GitHub Actions workflow, keep `id-token: write`
+only on the publish job, require the release environment, and publish with
+provenance. Do not add a long-lived npm token to repository secrets.

package/index.d.ts

@@ -17,10 +17,58 @@ export interface CompletionAuditVerdict {
   reason?: string
 }
 
+/** A timestamped lifecycle entry retained with an active or archived goal. */
+export interface GoalHistoryEntry {
+  type: string
+  detail: string
+  timestamp: number
+}
+
+/** A bounded progress checkpoint retained with a goal. */
+export interface GoalCheckpoint {
+  summary: string
+  timestamp: number
+}
+
+/** Normalized token and cost usage accumulated for the current goal run. */
+export interface GoalUsage {
+  input: number
+  output: number
+  reasoning: number
+  cacheRead: number
+  cacheWrite: number
+  cost: number
+  costKnown: boolean
+}
+
+/** Read-only goal snapshot passed to custom completion auditors. */
+export interface GoalAuditSnapshot {
+  goalId: string
+  runId: string
+  condition: string
+  successCriteria: string
+  constraints: string
+  mode: "normal" | "sisyphus"
+  sessionID: string
+  turnCount: number
+  startedAt: number
+  pausedAt: number
+  totalTokens: number
+  usage: Readonly<GoalUsage>
+  options: Readonly<GoalPluginOptions>
+  lastStatus: string
+  blockedReason: string
+  stopped: boolean
+  stopReason: string
+  history: readonly Readonly<GoalHistoryEntry>[]
+  checkpoints: readonly Readonly<GoalCheckpoint>[]
+  lastCheckpoint: Readonly<GoalCheckpoint> | null
+}
+
 /** Arguments passed to a custom {@link GoalPluginOptions.auditor} function. */
 export interface CompletionAuditContext {
   /** The goal being audited (objective, budget usage, checkpoints, etc.). */
-  goal: unknown
+  goal: Readonly<GoalAuditSnapshot>
   /** The OpenCode session ID the goal belongs to. */
   sessionID: string
   /** The assistant's latest response text, containing the `[goal:evidence]`/`[goal:complete]` claim. */
@@ -283,10 +331,10 @@ export interface GoalPluginOptions {
 
   /**
    * Custom sink for audit announcements. Defaults to routing through
-   * OpenCode's structured log (`client.app.log`). Provide this to route
-   * audit messages elsewhere, e.g. into the live conversation.
+   * OpenCode's structured log (`client.app.log`) and TUI toast when those
+   * host APIs are available. Provide this to route audit messages elsewhere.
    */
-  auditMessenger?: (sessionID: string, text: string) => Promise<void>
+  auditMessenger?: (sessionID: string, text: string) => Promise<void> | void
 }
 
 /**
@@ -300,6 +348,8 @@ export interface GoalPluginHooks {
   config: (config: unknown) => Promise<void>
   /** 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. */
+  "tool.execute.before": (input: unknown, output: unknown) => Promise<void>
   event: (input: unknown) => Promise<void>
   "experimental.chat.system.transform": (input: unknown, output: unknown) => Promise<void>
   "experimental.compaction.autocontinue": (input: unknown, output: unknown) => Promise<void>
@@ -312,7 +362,6 @@ export interface GoalPluginHooks {
   tool?: Record<string, unknown>
   /** Cancels pending continuation work and releases this plugin instance. */
   dispose: () => Promise<void>
-  [hook: string]: unknown
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-plugin",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Durable, guarded goal workflows for OpenCode.",
   "type": "module",
   "main": "./src/goal-plugin.js",
@@ -22,7 +22,7 @@
   },
   "files": [
     "src",
-    "scripts",
+    "scripts/verify.mjs",
     "examples",
     "demo",
     "docs",
@@ -36,13 +36,18 @@
   ],
   "scripts": {
     "test": "node --test test/*.test.js",
+    "test:model": "node --test test/lifecycle-model.test.js",
+    "test:mutation": "node scripts/mutation-contract.mjs",
     "test:coverage": "node --test --experimental-test-coverage test/*.test.js",
+    "type:check": "node scripts/type-contract.mjs",
     "smoke": "node scripts/smoke-command-hook.mjs",
     "smoke:packed-host": "node scripts/packed-host-contract.mjs",
+    "smoke:packed-tools": "node scripts/packed-tool-contract.mjs",
     "benchmark:behavior": "node scripts/behavior-benchmark.mjs",
     "verify": "node scripts/verify.mjs",
     "check": "node -c src/goal-plugin.js && npm test",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "release:check": "npm run check && npm run test:coverage && npm run type:check && npm run test:mutation && npm run benchmark:behavior && npm run smoke && npm run smoke:packed-host && npm run smoke:packed-tools && npm run verify && npm audit --omit=dev --audit-level=high && npm run pack:check"
   },
   "keywords": [
     "opencode",
@@ -73,5 +78,9 @@
   "homepage": "https://github.com/willytop8/OpenCode-goal-plugin#readme",
   "author": {
     "name": "willytop8"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.17.18",
+    "typescript": "5.9.3"
   }
 }

package/scripts/verify.mjs

@@ -9,6 +9,7 @@ import assert from "node:assert/strict"
 const REQUIRED_HOOKS = [
   "config",
   "command.execute.before",
+  "tool.execute.before",
   "event",
   "experimental.chat.system.transform",
   "experimental.compaction.autocontinue",

package/src/goal-plugin.js

@@ -88,6 +88,7 @@ function createRuntimeState() {
     activeContinues: new Map(),
     continuationControllers: new Map(),
     seenIdleEventIDs: new Set(),
+    readOnlyCommandGuards: new Set(),
     ledgerSink: null,
     persistenceLease: null,
     migrationLease: null,
@@ -143,6 +144,7 @@ const seenOutputTokens = runtimeCollection("seenOutputTokens")
 const activeContinues = runtimeCollection("activeContinues")
 const CLEAR_COMMANDS = new Set(["clear", "stop", "off", "reset", "none", "cancel"])
 const PAUSE_COMMANDS = new Set(["pause"])
+const READ_ONLY_COMMAND_TOOLS = new Set(["goal_status", "get_goal", "get_goal_history", "read", "glob", "grep"])
 const GOAL_FLAG_SPECS = {
   "--max-turns": {
     optionKey: "maxTurns",
@@ -206,7 +208,7 @@ function messageHasToolCall(message) {
 
 const GOAL_MODES = new Set(["normal", "ordered"])
 
-// Goal "mode" field (item 4.3): normal vs ordered (a.k.a. sisyphus). `ordered`
+// Goal mode: normal vs ordered (a.k.a. sisyphus). `ordered`
 // signals a strict execution sequence; `sisyphus` is accepted as an alias.
 // Returns the canonical mode or null when unrecognized.
 function normalizeMode(value) {
@@ -289,12 +291,12 @@ function makeHistoryEntry(type, detail, timestamp = Date.now()) {
   }
 }
 
-// Append-only lifecycle ledger (item 2.3). pushHistory emits every lifecycle
+// Append-only lifecycle ledger. pushHistory emits every lifecycle
 // event to this sink, which a configured plugin instance points at a JSONL
 // file. Because the in-memory history is truncated to MAX_HISTORY_ENTRIES, the
 // ledger is the durable record used to reconstruct state if the main state file
 // is lost or corrupted, and it captures terminal events even when the main
-// state write fails (fail-closed, item 2.5).
+// state write fails (fail closed).
 function setLedgerSink(sink) {
   currentRuntime().ledgerSink = typeof sink === "function" ? sink : null
 }
@@ -705,6 +707,7 @@ function clearRuntimeState() {
   activeContinues.clear()
   runtime.continuationControllers.clear()
   runtime.seenIdleEventIDs.clear()
+  runtime.readOnlyCommandGuards.clear()
 }
 
 function pruneGoalResults(options) {
@@ -1001,7 +1004,7 @@ async function assertSafeProjectPersistencePath({ stateFilePath, projectRoot, en
   }
 }
 
-// Command surface options (item 8.2): `commandName` lets the plugin own a
+// Command surface options: `commandName` lets the plugin own a
 // different slash command (e.g. /objective) and `registerCommand: false` makes
 // the plugin skip the command hook entirely (agent/programmatic use only). A
 // leading slash in commandName is tolerated and stripped.
@@ -1418,7 +1421,7 @@ async function loadPersistedState(persistenceOptions, client) {
 
 // Last-resort recovery: when the main state file is absent, rebuild still-active
 // goals from the append-only ledger so a lost/rotated state file does not drop
-// in-flight goals (item 2.3). Recovered goals are paused (via deserializeGoal).
+// in-flight goals. Recovered goals are paused (via deserializeGoal).
 async function reconstructFromLedger(persistenceOptions, client) {
   const entries = await readLedgerEntries(persistenceOptions.ledgerFilePath, {
     maxBytes: persistenceOptions.ledgerMaxBytes,
@@ -1788,7 +1791,7 @@ function buildContinueMessage(
 
 // Deterministic progress summary built from the plugin's persisted goal record
 // (checkpoints + lifecycle history) rather than from chat memory, so it is
-// stable and reproducible across a compaction (item 6.3).
+// stable and reproducible across a compaction.
 function buildCompactionProgressSummary(goal, { maxCheckpoints = 3, maxEvents = 6 } = {}) {
   const lines = []
   const checkpoints = Array.isArray(goal.checkpoints) ? goal.checkpoints.slice(-maxCheckpoints) : []
@@ -2069,7 +2072,7 @@ function isPluginContinuationMessage(message) {
 
 // "Latest instruction wins": detect a real (human) user message that arrived
 // after the plugin's most recent continuation prompt. Plugin-generated
-// continuation/audit messages are ignored (item 5.2). Detection requires the
+// continuation/audit messages are ignored. Detection requires the
 // loop to be running (turnCount > 0) and a plugin continuation to be visible in
 // the recent window, so the first idle after /goal set and sessions where the
 // continuations have scrolled out of view are never misread as intervention.
@@ -2139,7 +2142,7 @@ function buildGoalState(sessionID, condition, options, meta = {}, lastStatus = "
 const AGENT_UPDATE_STATUSES = new Set(["complete", "blocked", "paused", "resumed"])
 
 // Programmatic equivalents of the /goal command, exposed to the agent as tools
-// (megalist items 7.1 / 7.2). Each handler operates on a session id and mutates
+// Each handler operates on a session id and mutates
 // the same in-memory state the command path uses, persisting through the
 // provided `persist` callback, and returns a human-readable string for the tool
 // result. Goal creation/replacement routes through the multi-goal registry
@@ -2356,12 +2359,9 @@ function buildAgentToolHandlers({ defaultGoalOptions, persist, persistTerminalSt
       } else if (status === "resumed") {
         if (!goal.stopped)
           return "Goal is already running. Pause or stop it first if you want to reset the budget window."
-        const previousGoalId = goal.goalId
         resetGoalBudget(goal)
-        // resetGoalBudget always rotates goalId via randomUUID; unconditionally
-        // re-key the registry so the goal stays findable by its new id.
-        removeSessionGoal(sessionID, previousGoalId)
-        registerSessionGoal(goal)
+        // goalId is stable across budget windows; runId is the execution epoch.
+        // Keeping the existing registry entry also preserves multi-goal order.
         focusGoal(sessionID, goal)
         goal.stopped = false
         goal.stopReason = ""
@@ -2594,7 +2594,7 @@ function formatGoalList(sessionID, commandName = "goal") {
   return lines.join("\n")
 }
 
-// Visible audit messages (item 2.4): when the plugin audits a completion or
+// Visible audit messages: when the plugin audits a completion or
 // blocker it announces the audit and its result instead of doing the work
 // silently. Delivery is via this default messenger (structured app log, the
 // channel OpenCode surfaces to the user) or a caller-supplied `auditMessenger`
@@ -2623,7 +2623,7 @@ async function defaultAuditMessenger(client, sessionID, text) {
   }
 }
 
-// Completion auditor (item 2.2). When an auditor is configured, a [goal:complete]
+// Completion auditor. When an auditor is configured, a [goal:complete]
 // is verified before the goal is archived: an approved verdict archives it, a
 // rejected verdict restores the goal (pauses it with the reason) instead of
 // archiving. The auditor is a function `({ goal, sessionID, latestText }) =>
@@ -2783,7 +2783,7 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
   }
   runtime.drainPersistence = () => persistChain.catch(() => false)
 
-  // Fail-closed (item 2.5): when persisting a terminal state (complete/blocked)
+  // Fail closed when persisting a terminal state (complete/blocked)
   // fails, surface it loudly. The terminal event is already in the append-only
   // ledger, so it stays recoverable across a restart even though the main state
   // file write did not land.
@@ -2810,7 +2810,7 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
     setLedgerSink(null)
   }
 
-  // Visible audit announcements (item 2.4).
+  // Visible audit announcements.
   const auditMessagesEnabled = pluginOptions.auditMessages !== false
   const auditMessenger =
     typeof pluginOptions.auditMessenger === "function"
@@ -2885,6 +2885,14 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
       })
       if (pluginOptions.completionAudit) verifierRegistrationReady = true
     },
+    "tool.execute.before": async (input) => {
+      const sessionID = input?.sessionID
+      if (!sessionID || !currentRuntime().readOnlyCommandGuards.has(sessionID)) return
+      if (READ_ONLY_COMMAND_TOOLS.has(input?.tool)) return
+      throw new Error(
+        `This /${commandName} control command is read-only for the routed model turn. Tool "${input?.tool || "unknown"}" was blocked. Wait for a separate user turn; do not modify work or goal state now.`,
+      )
+    },
     "command.execute.before": async (input, output) => {
       if (!input || input.command !== commandName || !output) return
 
@@ -2898,10 +2906,12 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
       }
       const args = input.arguments.trim()
       const sessionID = input.sessionID
+      currentRuntime().readOnlyCommandGuards.delete(sessionID)
       pruneGoalResults(defaultGoalOptions)
 
       if (!args || args === "status") {
         const goal = goalStates.get(sessionID)
+        currentRuntime().readOnlyCommandGuards.add(sessionID)
         const lastResult = lastGoalResults.get(sessionID)
         output.parts = [
           makeTextPart(
@@ -2917,6 +2927,7 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
 
       if (args === "history") {
         const goal = goalStates.get(sessionID)
+        currentRuntime().readOnlyCommandGuards.add(sessionID)
         const lastResult = lastGoalResults.get(sessionID)
         output.parts = [
           makeTextPart(
@@ -2943,6 +2954,7 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
       }
 
       if (CLEAR_COMMANDS.has(args)) {
+        currentRuntime().readOnlyCommandGuards.add(sessionID)
         // Record the clear in the ledger before cleanupGoal removes the goal
         // object, so reconstructFromLedger can identify cleared goals and skip
         // them rather than reconstructing them after a missing state file.
@@ -2962,6 +2974,7 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
       }
 
       if (PAUSE_COMMANDS.has(args)) {
+        currentRuntime().readOnlyCommandGuards.add(sessionID)
         const goal = goalStates.get(sessionID)
         if (!goal) {
           output.parts = [makeTextPart(`No active goal. Set one with \`/${commandName} <condition>\`.`)]
@@ -2987,12 +3000,9 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
           return
         }
 
-        const previousGoalId = goal.goalId
         resetGoalBudget(goal)
-        // resetGoalBudget always rotates goalId via randomUUID; unconditionally
-        // re-key the registry so a later clear/replace removes the right entry.
-        removeSessionGoal(sessionID, previousGoalId)
-        registerSessionGoal(goal)
+        // goalId is stable across budget windows; runId is the execution epoch.
+        // Keeping the existing registry entry also preserves multi-goal order.
         focusGoal(sessionID, goal)
         goal.stopped = false
         goal.stopReason = ""
@@ -3052,6 +3062,7 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
       }
 
       if (args === "list") {
+        currentRuntime().readOnlyCommandGuards.add(sessionID)
         output.parts = [makeTextPart(formatGoalList(sessionID, commandName))]
         return
       }
@@ -3394,6 +3405,7 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
       if (!isIdleEvent(event)) return
 
       const sessionID = getSessionID(event)
+      currentRuntime().readOnlyCommandGuards.delete(sessionID)
       const eventID = typeof event?.id === "string" ? event.id : ""
       const seenIdleEventIDs = currentRuntime().seenIdleEventIDs
       if (eventID && seenIdleEventIDs.has(eventID)) return
@@ -3478,7 +3490,7 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
             // bail out without archiving — archiving a cleared goal would resurrect
             // it in memory and potentially in the persisted state.
             if (!activeGoal(sessionID, goalID, runID)) return
-            // Optional independent auditor (item 2.2): an approved verdict
+            // Optional independent auditor: an approved verdict
             // archives; a rejected verdict restores (pauses) the goal instead.
             if (completionAuditor) {
               let verdict
@@ -3867,7 +3879,6 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
 
       const goal = goalStates.get(input.sessionID)
       if (!goal) return
-      if (goal.stopped) return
       const systemBlocks = Array.isArray(output.system) ? [...output.system] : []
       if (systemBlocks.some((block) => systemBlockContainsGoal(block, goal.goalId))) return
 
@@ -3880,14 +3891,23 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
       // on every continuation turn via buildContinueMessage (buildLimitWarning
       // and <progress_budget>), which is sufficient — the model doesn't need
       // them in the system prompt mid-turn.
-      const goalBlock = [
-        `<opencode_goal_plugin id="${goal.goalId}">`,
-        buildGoalBlock(goal),
-        "Keep working until the goal is fully satisfied.",
-        "When fully satisfied, put a `[goal:evidence]` line summarizing what you verified immediately before `[goal:complete]`. A `[goal:complete]` without evidence is rejected.",
-        "If user input is required, explain the concrete blocker in the line immediately before `[goal:blocked]`. A `[goal:blocked]` without a concrete blocker is rejected.",
-        "</opencode_goal_plugin>",
-      ].join("\n")
+      const goalBlock = goal.stopped
+        ? [
+            `<opencode_goal_plugin id="${goal.goalId}">`,
+            "<goal_state>paused</goal_state>",
+            "A goal exists for this session, but it is paused. Do not continue or modify work toward it, and do not call completion or blocker tools, unless the current user message explicitly asks to resume it.",
+            "For status or history requests, only report the goal state; do not change files or goal state.",
+            `To continue, the user can run /${commandName} resume or explicitly ask you to call goal_resume before doing any goal work.`,
+            "</opencode_goal_plugin>",
+          ].join("\n")
+        : [
+            `<opencode_goal_plugin id="${goal.goalId}">`,
+            buildGoalBlock(goal),
+            "Keep working until the goal is fully satisfied.",
+            "When fully satisfied, put a `[goal:evidence]` line summarizing what you verified immediately before `[goal:complete]`. A `[goal:complete]` without evidence is rejected.",
+            "If user input is required, explain the concrete blocker in the line immediately before `[goal:blocked]`. A `[goal:blocked]` without a concrete blocker is rejected.",
+            "</opencode_goal_plugin>",
+          ].join("\n")
 
       if (systemBlocks.length === 0) {
         output.system = [goalBlock]
@@ -3930,13 +3950,13 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
     },
   }
 
-  // register_command toggle (item 8.2): when disabled, the plugin does not own
+  // register_command toggle: when disabled, the plugin does not own
   // a slash command and only the event/transform/compaction hooks remain.
   if (!registerCommand) {
     delete hooks["command.execute.before"]
   }
 
-  // Register agent-facing tools (megalist 7.1 / 7.2) when @opencode-ai/plugin is
+  // Register agent-facing tools when @opencode-ai/plugin is
   // available (it provides the `tool` helper and zod-style schema). Disabled via
   // `registerTools: false`. When the helper is absent the command/event hooks
   // still work; only the programmatic tool surface is omitted, preserving the

package/scripts/behavior-benchmark.mjs

@@ -1,272 +0,0 @@
-#!/usr/bin/env node
-
-import assert from "node:assert/strict"
-import { promises as fs } from "node:fs"
-import { tmpdir } from "node:os"
-import { join } from "node:path"
-import { GoalPlugin } from "../src/goal-plugin.js"
-
-const startedAt = performance.now()
-const temporaryDirectories = []
-
-function assistantMessage(sessionID, text, id = `assistant-${sessionID}`) {
-  return {
-    info: {
-      id,
-      role: "assistant",
-      sessionID,
-      tokens: { input: 20, output: 120, reasoning: 0 },
-    },
-    parts: [{ type: "text", text }],
-  }
-}
-
-function createHost(messageForSession = () => "Working with tools.") {
-  const prompts = []
-  const notices = []
-  return {
-    prompts,
-    notices,
-    client: {
-      app: { log: async () => {} },
-      session: {
-        messages: async ({ path }) => ({
-          data: [assistantMessage(path.id, messageForSession(path.id))],
-        }),
-        promptAsync: async (input) => {
-          prompts.push(input)
-          return {}
-        },
-      },
-    },
-  }
-}
-
-function promptCharacters(prompts) {
-  return prompts.reduce(
-    (total, prompt) => total + (prompt?.body?.parts || []).reduce(
-      (partTotal, part) => partTotal + (typeof part?.text === "string" ? part.text.length : 0),
-      0,
-    ),
-    0,
-  )
-}
-
-async function makeDirectory(label) {
-  const directory = await fs.mkdtemp(join(tmpdir(), `goal-benchmark-${label}-`))
-  temporaryDirectories.push(directory)
-  return directory
-}
-
-async function createHooks(host, options = {}) {
-  return GoalPlugin(
-    { client: host.client, directory: await makeDirectory("workspace") },
-    {
-      persistState: false,
-      registerTools: false,
-      registerAgents: false,
-      minDelayMs: 1,
-      noProgressTokenThreshold: 1,
-      noProgressTurnsBeforePause: 10,
-      noToolCallTurnsBeforePause: 2,
-      ...options,
-    },
-  )
-}
-
-async function goalCommand(hooks, sessionID, argumentsText) {
-  const output = { parts: [] }
-  await hooks["command.execute.before"](
-    { command: "goal", sessionID, arguments: argumentsText },
-    output,
-  )
-  return output.parts.map((part) => part.text || "").join("\n")
-}
-
-async function idle(hooks, sessionID, id) {
-  await hooks.event({
-    event: {
-      id,
-      type: "session.status",
-      properties: { sessionID, status: { type: "idle" } },
-    },
-  })
-}
-
-async function scenario(name, points, run) {
-  const scenarioStartedAt = performance.now()
-  try {
-    const telemetry = await run()
-    return {
-      name,
-      passed: true,
-      points,
-      durationMs: Number((performance.now() - scenarioStartedAt).toFixed(2)),
-      ...telemetry,
-    }
-  } catch (error) {
-    return {
-      name,
-      passed: false,
-      points: 0,
-      possiblePoints: points,
-      durationMs: Number((performance.now() - scenarioStartedAt).toFixed(2)),
-      error: error instanceof Error ? error.message : String(error),
-    }
-  }
-}
-
-const results = []
-
-results.push(await scenario("verified-success", 20, async () => {
-  const sessionID = "benchmark-success"
-  const host = createHost(() => "Tests pass.\n[goal:evidence] npm test: 210/210\n[goal:complete]")
-  const hooks = await createHooks(host, {
-    auditor: async () => ({ approved: true, reason: "evidence independently accepted" }),
-  })
-  await goalCommand(hooks, sessionID, "ship a verified release")
-  await idle(hooks, sessionID, "success-idle")
-  const status = await goalCommand(hooks, sessionID, "status")
-  assert.match(status, /State: achieved/)
-  await hooks.dispose()
-  return {
-    continuationPrompts: host.prompts.length,
-    continuationCharacters: promptCharacters(host.prompts),
-    status: "archived",
-  }
-}))
-
-results.push(await scenario("false-completion", 20, async () => {
-  const sessionID = "benchmark-false-completion"
-  const host = createHost(() => "Looks done.\n[goal:evidence] guessed from source\n[goal:complete]")
-  const hooks = await createHooks(host, {
-    auditor: async () => ({ approved: false, reason: "no executed verification" }),
-  })
-  await goalCommand(hooks, sessionID, "do not accept an unverified claim")
-  await idle(hooks, sessionID, "false-idle")
-  const status = await goalCommand(hooks, sessionID, "status")
-  assert.match(status, /audit rejected/i)
-  assert.doesNotMatch(status, /No active goal/)
-  await hooks.dispose()
-  return {
-    continuationPrompts: host.prompts.length,
-    continuationCharacters: promptCharacters(host.prompts),
-    status: "rejected",
-  }
-}))
-
-results.push(await scenario("loop-circuit-breaker", 15, async () => {
-  const sessionID = "benchmark-loop"
-  let turn = 0
-  const host = createHost(() => `Still discussing the work, turn ${turn++}.`)
-  const hooks = await createHooks(host)
-  await goalCommand(hooks, sessionID, "stop self-chat loops")
-  await idle(hooks, sessionID, "loop-1")
-  await idle(hooks, sessionID, "loop-2")
-  await idle(hooks, sessionID, "loop-3")
-  const status = await goalCommand(hooks, sessionID, "status")
-  assert.match(status, /no tool calls|self-chat loop/i)
-  assert.equal(host.prompts.length, 2)
-  await hooks.dispose()
-  return {
-    continuationPrompts: host.prompts.length,
-    continuationCharacters: promptCharacters(host.prompts),
-    status: "paused",
-  }
-}))
-
-results.push(await scenario("human-interruption", 15, async () => {
-  const sessionID = "benchmark-interruption"
-  const host = createHost()
-  const hooks = await createHooks(host)
-  await goalCommand(hooks, sessionID, "respect explicit interruption")
-  await hooks.event({
-    event: {
-      type: "session.error",
-      properties: {
-        sessionID,
-        error: { name: "MessageAbortedError", message: "aborted by user" },
-      },
-    },
-  })
-  await idle(hooks, sessionID, "interruption-idle")
-  assert.equal(host.prompts.length, 0)
-  assert.match(await goalCommand(hooks, sessionID, "status"), /abort|paused|stopped/i)
-  await hooks.dispose()
-  return { continuationPrompts: 0, status: "paused" }
-}))
-
-results.push(await scenario("compaction-continuity", 15, async () => {
-  const sessionID = "benchmark-compaction"
-  const host = createHost()
-  const hooks = await createHooks(host)
-  await goalCommand(hooks, sessionID, "preserve the objective across compaction")
-  const output = { context: [] }
-  await hooks["experimental.session.compacting"]({ sessionID }, output)
-  assert.equal(output.context.length, 1)
-  assert.match(output.context[0], /preserve the objective across compaction/)
-  assert.ok(output.context[0].length < 2_000, "compaction context exceeded token-efficient size cap")
-  await hooks.dispose()
-  return {
-    contextCharacters: output.context[0].length,
-    estimatedContextTokens: Math.ceil(output.context[0].length / 4),
-    status: "preserved",
-  }
-}))
-
-results.push(await scenario("restart-recovery", 15, async () => {
-  const sessionID = "benchmark-restart"
-  const directory = await makeDirectory("restart")
-  const stateFilePath = join(directory, "state.json")
-  const host = createHost()
-  const first = await GoalPlugin(
-    { client: host.client, directory },
-    { persistState: true, stateFilePath, registerTools: false, registerAgents: false, minDelayMs: 1 },
-  )
-  await goalCommand(first, sessionID, "recover safely after restart")
-  await first.dispose()
-  const second = await GoalPlugin(
-    { client: host.client, directory },
-    { persistState: true, stateFilePath, registerTools: false, registerAgents: false, minDelayMs: 1 },
-  )
-  const status = await goalCommand(second, sessionID, "status")
-  assert.match(status, /Recovered persisted goal state|recovered after restart/i)
-  await idle(second, sessionID, "restart-idle")
-  assert.equal(host.prompts.length, 0, "recovered goals must not resume without user consent")
-  const stateBytes = (await fs.stat(stateFilePath)).size
-  await second.dispose()
-  return { continuationPrompts: 0, persistedStateBytes: stateBytes, status: "recovered-paused" }
-}))
-
-const score = results.reduce((total, result) => total + result.points, 0)
-const possibleScore = 100
-const continuationCharacters = results.reduce(
-  (total, result) => total + (result.continuationCharacters || 0),
-  0,
-)
-const report = {
-  schemaVersion: 1,
-  benchmark: "opencode-goal-plugin-behavior",
-  score,
-  possibleScore,
-  passed: score === possibleScore,
-  durationMs: Number((performance.now() - startedAt).toFixed(2)),
-  efficiency: {
-    totalContinuationPrompts: results.reduce(
-      (total, result) => total + (result.continuationPrompts || 0),
-      0,
-    ),
-    continuationCharacters,
-    estimatedContinuationTokens: Math.ceil(continuationCharacters / 4),
-    modelCalls: 0,
-    externalRequests: 0,
-  },
-  scenarios: results,
-}
-
-for (const directory of temporaryDirectories) {
-  await fs.rm(directory, { recursive: true, force: true })
-}
-
-process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
-if (!report.passed) process.exitCode = 1

package/scripts/packed-host-contract.mjs

@@ -1,160 +0,0 @@
-import assert from "node:assert/strict"
-import { execFileSync } from "node:child_process"
-import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises"
-import { tmpdir } from "node:os"
-import { join } from "node:path"
-import { pathToFileURL } from "node:url"
-
-const repository = new URL("..", import.meta.url)
-const root = await mkdtemp(join(tmpdir(), "opencode-goal-plugin-packed-host-"))
-const packDirectory = join(root, "pack")
-const projectDirectory = join(root, "host-project")
-const cacheDirectory = join(root, "npm-cache")
-const npmEnvironment = { ...process.env, npm_config_cache: cacheDirectory }
-
-try {
-  await Promise.all([
-    mkdir(packDirectory, { recursive: true }),
-    mkdir(projectDirectory, { recursive: true }),
-    mkdir(cacheDirectory, { recursive: true }),
-  ])
-  await writeFile(
-    join(projectDirectory, "package.json"),
-    JSON.stringify({ private: true, type: "module" }),
-  )
-
-  const packResult = JSON.parse(
-    execFileSync(
-      "npm",
-      ["pack", "--json", "--pack-destination", packDirectory],
-      { cwd: repository, encoding: "utf8", env: npmEnvironment },
-    ),
-  )
-  assert.equal(packResult.length, 1)
-  const tarball = join(packDirectory, packResult[0].filename)
-
-  // Install only the artifact npm produced. The optional peer is omitted so this
-  // contract test is offline-safe and cannot mutate the user's OpenCode install.
-  execFileSync(
-    "npm",
-    [
-      "install",
-      "--ignore-scripts",
-      "--no-audit",
-      "--no-fund",
-      "--no-package-lock",
-      "--omit=peer",
-      "--offline",
-      "--cache",
-      cacheDirectory,
-      tarball,
-    ],
-    { cwd: projectDirectory, encoding: "utf8", env: npmEnvironment },
-  )
-
-  const installedManifestPath = join(
-    projectDirectory,
-    "node_modules",
-    "opencode-goal-plugin",
-    "package.json",
-  )
-  const installedManifest = JSON.parse(await readFile(installedManifestPath, "utf8"))
-  const installedEntry = join(
-    projectDirectory,
-    "node_modules",
-    "opencode-goal-plugin",
-    installedManifest.main,
-  )
-  const installed = await import(pathToFileURL(installedEntry).href)
-
-  assert.equal(installed.default.id, "opencode-goal-plugin")
-  assert.equal(installed.default.server, installed.GoalPlugin)
-
-  const sessionID = "packed-host-contract"
-  const promptCalls = []
-  const client = {
-    app: { log: async () => {} },
-    session: {
-      messages: async ({ path }) => ({
-        data: [
-          {
-            info: {
-              id: "assistant-packed-contract",
-              role: "assistant",
-              sessionID: path.id,
-              tokens: { input: 1, output: 1, reasoning: 0 },
-            },
-            parts: [{ type: "text", text: "Work remains." }],
-          },
-        ],
-      }),
-      promptAsync: async (input) => {
-        promptCalls.push(input)
-        return {}
-      },
-    },
-  }
-  const hooks = await installed.GoalPlugin(
-    { client, directory: projectDirectory },
-    {
-      persistState: false,
-      registerTools: false,
-      minDelayMs: 1,
-      noToolCallTurnsBeforePause: 10,
-    },
-  )
-
-  for (const hook of [
-    "config",
-    "command.execute.before",
-    "event",
-    "experimental.chat.system.transform",
-    "experimental.session.compacting",
-    "experimental.compaction.autocontinue",
-    "dispose",
-  ]) {
-    assert.equal(typeof hooks[hook], "function", `${hook} must be callable`)
-  }
-  const config = {}
-  await hooks.config(config)
-  assert.equal(config.agent.goal.mode, "primary")
-  assert.equal(config.agent["goal-verify"].tools.edit, false)
-
-  const output = { parts: [] }
-  await hooks["command.execute.before"](
-    { command: "goal", sessionID, arguments: "verify the installed artifact --max-turns 1" },
-    output,
-  )
-  assert.match(output.parts[0]?.text, /New active goal/)
-
-  // Let the configured throttle window elapse before idle. This avoids leaving
-  // the contract dependent on the host's event-loop/timer shutdown behavior.
-  await new Promise((resolve) => setTimeout(resolve, 5))
-
-  await hooks.event({
-    event: {
-      type: "session.status",
-      properties: { sessionID, status: { type: "idle" } },
-    },
-  })
-
-  assert.equal(promptCalls.length, 1)
-  // PluginInput currently supplies OpenCode's generated legacy client shape:
-  // session.promptAsync({ path, body }). The standalone adapter suite covers
-  // flattened v2 clients separately.
-  assert.deepEqual(promptCalls[0].path, { id: sessionID })
-  assert.equal(promptCalls[0].body.parts.length, 1)
-  assert.deepEqual(promptCalls[0].body.parts[0].metadata, {
-    "opencode-goal-plugin": { kind: "continuation" },
-  })
-  assert.equal(promptCalls[0].body.parts[0].synthetic, true)
-
-  await hooks.dispose()
-  await hooks.dispose()
-
-  console.log(
-    `packed host contract passed (${installedManifest.name}@${installedManifest.version}; ${packResult[0].size} byte tarball)`,
-  )
-} finally {
-  await rm(root, { recursive: true, force: true })
-}

package/scripts/smoke-command-hook.mjs

@@ -1,51 +0,0 @@
-import assert from "node:assert/strict"
-import pluginModule, { GoalPlugin } from "opencode-goal-plugin"
-
-const sessionID = `smoke-${Date.now()}`
-const promptCalls = []
-const logCalls = []
-
-const client = {
-  app: {
-    log: async (input) => {
-      logCalls.push(input)
-    },
-  },
-  session: {
-    messages: async () => ({ data: [] }),
-    promptAsync: async (input) => {
-      promptCalls.push(input)
-      return {}
-    },
-  },
-}
-
-assert.equal(pluginModule.id, "opencode-goal-plugin")
-assert.equal(pluginModule.server, GoalPlugin)
-
-// persistState:false keeps the smoke test from reading or overwriting the
-// user's real ~/.opencode-goal-plugin/state.json.
-const hooks = await GoalPlugin({ client }, { minDelayMs: 1, persistState: false })
-assert.equal(typeof hooks["command.execute.before"], "function")
-assert.equal(typeof hooks.event, "function")
-assert.equal(typeof hooks["experimental.chat.system.transform"], "function")
-
-const commandHook = hooks["command.execute.before"]
-
-async function runGoalCommand(args) {
-  const output = { parts: [] }
-  await commandHook({ command: "goal", sessionID, arguments: args }, output)
-  assert.equal(output.parts.length, 1)
-  assert.equal(output.parts[0].type, "text")
-  return output.parts[0].text
-}
-
-assert.match(await runGoalCommand("status"), /No active goal/)
-assert.match(await runGoalCommand("ship a smoke test --max-turns 1"), /New active goal/)
-assert.match(await runGoalCommand("status"), /Active goal: ship a smoke test/)
-assert.match(await runGoalCommand("clear"), /Goal cleared/)
-assert.match(await runGoalCommand("status"), /No active goal/)
-assert.equal(promptCalls.length, 0)
-assert.equal(logCalls.length, 0)
-
-console.log("opencode-goal-plugin command hook smoke passed")