opencode-goal-plugin 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## Unreleased
 
+## 0.6.1 — 2026-07-10
+
+- Default-deny verifier tools except read/glob/grep, and fail closed unless the owned verifier agent registers successfully.
+- Require exact final-line audit verdicts and adjacent bounded completion evidence to prevent quoted-marker false approvals.
+- 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.
+- 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.
+
+## 0.6.0 — 2026-07-10
+
+> Adds canonical structured goal tools, native goal and read-only verifier agents, fail-closed completion verification, safer OpenCode SDK compatibility, bounded persistence, and stronger lifecycle isolation. Existing command workflows and legacy tool aliases remain supported.
+
+- Add canonical typed goal tools alongside backward-compatible aliases and structured completion claims.
+- Register collision-safe goal and verifier agents; completion auditing now requires an owned, distinct verifier identity with edit and shell permissions denied.
+- Fail closed on verifier errors/timeouts and abort timed-out child sessions when the host supports cancellation.
+- Isolate runtime state per workspace, suppress stale asynchronous continuations, handle abort/dispose races, and coalesce duplicate idle events.
+- Add an exclusive persistence lease so two OpenCode processes cannot silently overwrite one workspace state file.
+- Bound goal-definition inputs and rotate the sensitive lifecycle ledger using configurable size/retention ceilings.
+- Add normalized usage diagnostics, compact continuation prompts, a 100-point behavior benchmark, and packed-tarball host-contract verification.
+- Include provider documentation and the reproducible demo in the npm package; declare all public hooks.
+
 ## 0.5.0 — 2026-07-08
 
 - Replace the single-line "Compatibility snapshot" in the README with an OpenCode version compatibility table, manually verified via `tmux` + the OpenCode TUI against the persisted state file for each provider/model combination.
@@ -102,7 +127,7 @@
 
 ## 0.3.0 — 2026-06-14
 
-> A large feature release. Stronger completion integrity (evidence gate, optional auditor, visible audit messages), durable lifecycle ledger with state reconstruction, multiple goals per session with focus and ordered sisyphus sequences, richer goal schema, more auto-continue guardrails, project-local state with migration, a deterministic compaction summary, and npm Trusted Publishing CI. All changes are additive and backward-compatible; older state files load unchanged.
+> A large feature release. Stronger completion integrity (evidence gate, optional auditor, visible audit messages), durable lifecycle ledger with state reconstruction, multiple goals per session with focus and ordered sisyphus sequences, richer goal schema, more auto-continue guardrails, project-local state with migration, a deterministic compaction summary, and release-workflow groundwork. All changes are additive and backward-compatible; older state files load unchanged.
 
 ### Completion integrity & audit
 
@@ -134,8 +159,8 @@
 ### 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 **Unreleased** section above. Megalist items 7.1 and 7.2._
-- **Add a `Publish` GitHub Actions workflow (`.github/workflows/publish.yml`) for npm Trusted Publishing (OIDC).** On a push to `main` it runs the full check matrix on Node 18/20/22, then publishes via OIDC with no stored `NPM_TOKEN`, using a publish-on-version-change model (only publishes when `package.json`'s version is new). The publish job requires `id-token: write` and is gated behind a `release` environment. First run still requires a human to publish an initial version and configure the npm Trusted Publisher. Implements megalist item 9.1.
+- _**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._
+- **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
 
@@ -250,4 +275,4 @@
 
 ## 0.1.0
 
-- Initial experimental marker-based `/goal` plugin.
+- Initial experimental marker-based `/goal` plugin.

package/CONTRIBUTING.md

@@ -16,8 +16,10 @@ Run the local checks before submitting changes:
 npm test
 npm run test:coverage
 npm run smoke
+npm run smoke:packed-host
+npm run benchmark:behavior
+npm run verify
 npm run check
-npm run smoke
 npm run pack:check
 ```
 
@@ -28,11 +30,11 @@ 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` to verify the packaged entrypoint and command hook surface.
+2. Run `npm run smoke` and `npm run smoke:packed-host` to verify the source and installed-tarball host 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. It does not replace a real OpenCode smoke test after hook or command behavior 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.
 
 ## Release checklist
 
@@ -42,15 +44,14 @@ Before publishing or tagging a release:
 - 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`
 - perform at least one manual OpenCode smoke test if hook behavior changed
 - refresh compatibility notes if the tested OpenCode surface changed
 
-`npm run smoke` verifies the published package entrypoint and `/goal` command hook without
-invoking a model. It does not replace a manual OpenCode smoke test after hook or command
-behavior changes.
-
 ## Pull Requests
 
 Keep pull requests focused. Include:

package/README.md

@@ -3,7 +3,7 @@
 [![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-185%20passing-brightgreen)](test/)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](test/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 An experimental session-scoped `/goal` command for [OpenCode](https://opencode.ai/).
@@ -12,23 +12,15 @@ Set a goal and the plugin keeps it in context, auto-continues the session whenev
 
 Compatibility: this plugin relies on experimental OpenCode hooks. Re-test against the exact OpenCode build and provider/backend stack you plan to use for unattended work.
 
-## Comparison
-
-| Feature | Claude Code | Codex | opencode-goal-plugin |
-|---|---|---|---|
-| `/goal` command | ✅ Native | ✅ Native | ✅ Plugin |
-| Auto-continue | ✅ | ✅ | ✅ |
-| Per-goal flag overrides | ❌ | ❌ | ✅ |
-| No-progress / no-tool-call detection | ❌ | ❌ | ✅ Both |
-| Configurable safety limits | Limited | Limited | ✅ All tunable |
-| Goal history | ✅ | ❌ | ✅ `/goal history` |
-| Goal persistence | ❌ | ❌ | ✅ Survives restart, ledger-backed |
-| Multiple concurrent goals | ❌ | ❌ | ✅ `/goal add` / `/goal focus` |
-| Ordered goal sequences | ❌ | ❌ | ✅ `/goal sisyphus` |
-| Evidence-gated completion | ❌ | ❌ | ✅ `[goal:evidence]` required |
-| Independent completion audit | ✅ | ❌ | ✅ Optional child-session auditor |
-| Budget wrap-up prompts | ❌ | ❌ | ✅ 80% threshold |
-| Open source | ❌ | ❌ | ✅ MIT |
+## What it provides
+
+- Session-scoped goals that remain visible across turns and compaction.
+- Guarded auto-continuation with turn, duration, token, no-progress, and no-tool-call limits.
+- Project-local restart recovery backed by persisted state and a bounded lifecycle ledger.
+- Evidence-gated completion with an optional independent, fail-closed verifier.
+- Canonical agent tools, collision-safe goal/verifier agents, multiple goals, and ordered goal sequences.
+
+This project is independently implemented for OpenCode. Product names used elsewhere identify their respective owners; no feature-parity or endorsement claim is implied.
 
 ## Compatibility snapshot
 
@@ -137,6 +129,18 @@ Clear the active goal:
 
 `/goal stop`, `/goal off`, `/goal reset`, `/goal none`, and `/goal cancel` are aliases for `/goal clear`.
 
+### Session forks and child sessions
+
+Goals are scoped to the session where they were created. A child session or a
+fork does not automatically inherit its parent's active goal; set a goal in the
+new session when you want it to continue independently.
+
+This isolation is intentional. OpenCode currently includes `parentID` for
+ordinary child sessions but does not expose the source session in the
+`session.created` event for forks. Inferring ancestry from a mutable title such
+as `(fork #1)` could attach a goal to the wrong session. Automatic inheritance
+can be added once the host exposes an explicit fork relationship.
+
 ### Multiple goals
 
 A session can hold more than one goal. `/goal <condition>` replaces the focused goal, while `/goal add <condition>` keeps the current goal (backgrounding it) and focuses a new one. Only the **focused** goal is auto-continued; backgrounded goals are paused until you focus them.
@@ -186,10 +190,8 @@ An ordered sequence, run as a strict pipeline:
 
 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.
-3. The plugin stops auto-continuing when the assistant ends a response with `[goal:complete]` or `[goal:blocked]`, or when a safety limit is reached.
-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.
 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 the goal objective, budget usage, and latest checkpoint into the compaction context so the goal survives the compaction and the assistant keeps the thread. 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.
+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 and pauses auto-continue so it does not talk over you. The plugin's own continuation prompts are ignored for this check (they are not "your" messages). Run `/goal resume` to hand control back to the goal loop.
 
 ## Completion markers
@@ -205,7 +207,7 @@ The deploy step needs a production API token I don't have.
 [goal:blocked]
 ```
 
-`[goal:complete]` — goal is satisfied. It is **only honored when the line immediately before it (or an earlier line) begins with `[goal:evidence]` and contains a non-empty summary** of what was verified (commands run and their results, files checked). A `[goal:complete]` with no `[goal:evidence]` line is rejected, not recorded, and the plugin re-prompts for evidence. The accepted evidence is shown in `/goal status` after completion.
+`[goal:complete]` — goal is satisfied. It is **only honored when the immediately adjacent evidence line begins with `[goal:evidence]` and contains a non-empty summary** of what was verified (commands run and their results, files checked). The historical two-line form (`[goal:evidence]`, then one evidence line) is also accepted. A stale or non-adjacent evidence marker is rejected. The accepted evidence is shown in `/goal status` after completion.
 `[goal:blocked]` — the assistant needs input from you. The line immediately before the marker must explain the specific blocker; `/goal status` shows it while the goal remains in memory. A `[goal:blocked]` with no concrete blocker is rejected and the plugin keeps working.
 
 Markers must appear on their own final line. The bracketed form is canonical, but the plugin also accepts bare `goal:complete`, `goal:blocked`, and `goal:evidence` lines because some models omit brackets. Natural-language phrases like "goal complete" are intentionally ignored.
@@ -222,7 +224,7 @@ Markers must appear on their own final line. The bracketed form is canonical, bu
 | Budget wrap-up threshold | 80% of context token budget |
 | Auto-continue failure pause | 3 consecutive prompt failures |
 
-**Effective turn count.** Each LLM turn on a real task typically takes 30–90 seconds. At that latency, raising `--max-minutes` is usually more useful than raising `--max-turns`. At 45 s/turn, the default 15-minute window gives roughly 15–20 turns of headroom before the turn limit becomes the binding brake.
+**Effective turn count.** Each LLM turn on a real task typically takes 30–90 seconds. The default 10 auto-continues is normally the binding brake before the 15-minute window; raise `--max-turns` and/or `--max-minutes` deliberately for longer work.
 
 **Token budget.** The plugin tracks the session's context window size (`input + output + reasoning` tokens on the latest message). This matches the token count that OpenCode displays, so the numbers should be consistent. When the context window reaches the `--max-tokens` limit, the plugin sends a wrap-up prompt and stops. In high-context sessions (large codebases, long conversation history), the context can grow quickly — treat the budget as a safety brake.
 
@@ -240,7 +242,7 @@ The state-file location is resolved with this precedence:
 2. the `OPENCODE_GOAL_STATE_PATH` environment variable, if set;
 3. the project-local default `<cwd>/.opencode/goals/state.json`.
 
-When the default path has no state yet, the plugin migrates forward from older locations on first load: the legacy `~/.opencode-goal-plugin/state.json` and the XDG path `${XDG_STATE_HOME:-~/.local/state}/opencode-goal-plugin/state.json`. An explicit `stateFilePath` or `OPENCODE_GOAL_STATE_PATH` is used literally with no migration fallback.
+When the default path has no state yet, the plugin migrates forward from older locations on first load: the legacy `~/.opencode-goal-plugin/state.json` and the XDG path `${XDG_STATE_HOME:-~/.local/state}/opencode-goal-plugin/state.json`. Migration is exclusively claimed; after the project-local write succeeds, the legacy file is retired to a timestamped `.migrated…` backup so another project cannot import the same private goal state. An explicit `stateFilePath` or `OPENCODE_GOAL_STATE_PATH` is used literally with no migration fallback.
 
 The state directory is created with owner-only permissions, and the JSON state file is written as `0600` because it may contain goal text, assistant checkpoints, and workflow history.
 
@@ -312,13 +314,17 @@ Additional plugin-level options:
 
 - `maxRecentMessages` — how many recent session messages to scan when looking for the latest assistant turn before auto-continuing. Higher values make long, tool-heavy sessions less likely to lose the most recent assistant response.
 - `noProgressTurnsBeforePause` — grace window for low-output stalls. The plugin pauses only after this many consecutive stalled low-output turns rather than on the first one.
-- `noToolCallTurnsBeforePause` — grace window for tool-free continuation turns. The plugin pauses after this many consecutive continuation turns that produced no tool calls (anti self-chat loop). Default `2`.
+- `noToolCallTurnsBeforePause` — grace window for tool-free continuation turns. The plugin pauses after this many consecutive continuation turns that produced no tool calls (anti self-chat loop). Default `2`; set the plugin option to `0` for legitimate tool-free writing/research workflows.
 - `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).
+- `registerAgents` — whether the config hook adds native `goal` and `goal-verify` agents (default `true`). Existing agents with those names are preserved unchanged; the plugin never changes your default agent.
+- `goalAgentName` / `verifierAgentName` — customize the registered native agent names (defaults `goal` and `goal-verify`). The verifier is a hidden subagent with a default-deny tool policy; only `read`, `glob`, and `grep` are allowed.
+- `sdkShape` — OpenCode session-client argument shape: `legacy` (the default generated `PluginInput` client using `{ path, body, query }`) or `flat` (clients using `{ sessionID, ... }`). Read-only `messages`/`get` calls may probe the alternate shape after an argument/schema `TypeError`; mutating calls are never replayed, so set this option correctly for embedded clients.
 - `persistState` — whether to persist active goals and recent goal results to disk.
 - `stateFilePath` — where the persisted state JSON is written. Overrides the default project-local path and the `OPENCODE_GOAL_STATE_PATH` env var. Useful if you want a fixed or ephemeral location. When unset, the default is `<cwd>/.opencode/goals/state.json` (see the persistence section above), and `OPENCODE_GOAL_STATE_PATH` can override it without editing config.
+- `ledgerMaxBytes` / `ledgerRetentionFiles` — bound the lifecycle ledger to 2 MiB per generation and three rotated generations by default. Set retention to `0` to discard the active ledger when it reaches the size ceiling.
 - `resultRetentionMs` — how long a completed goal summary remains available through `/goal status` after the goal leaves active memory.
 - `maxStoredResults` — maximum number of completed-goal summaries retained in process memory before the oldest ones are evicted.
 
@@ -328,11 +334,10 @@ In addition to the `/goal` command, the plugin can expose the same workflow to t
 
 Registered tools:
 
-- `get_goal` — current goal status (objective, budget usage, latest checkpoint).
-- `get_goal_history` — lifecycle history and latest checkpoint.
-- `set_goal` — set/replace the session goal. Its description constrains the agent to call it **only when the user explicitly asks** to set a goal. Accepts `objective` plus optional `maxTurns`, `maxTokens`, `maxDurationMs`, `successCriteria`, `constraints`, and `mode`.
-- `update_goal` — revise the `objective` and/or set `status` to `complete` / `blocked` / `paused` / `resumed` (with `evidence` for complete or `blocker` for blocked).
-- `clear_goal` — clear the current goal and discard its saved status.
+- `goal_status`, `goal_set`, `goal_pause`, `goal_resume`, `goal_block`, and `goal_complete` are the canonical narrow operations. They return compact versioned JSON envelopes so agents can branch reliably without parsing prose.
+- `get_goal`, `get_goal_history`, `set_goal`, `update_goal`, and `clear_goal` remain compatibility aliases with their existing text responses.
+
+`goal_set` and `set_goal` are explicitly constrained to user-requested goals. `goal_complete` accepts a structured claim: a required non-empty `summary`, plus optional criterion/evidence pairs, checks (`passed`, `failed`, or `not-run`), changed files, and known limitations. Failed checks and empty criterion evidence are rejected before archival; accepted claims are serialized deterministically for the configured completion auditor. The legacy `update_goal` tool retains its string `evidence` field for compatibility.
 
 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 (sisyphus) sequence auto-promotes the next.
 
@@ -340,7 +345,7 @@ These operate on the same per-session multi-goal state as the command path: a to
 
 ## Audit messages
 
-When the assistant marks a goal complete or blocked, the plugin announces the audit instead of doing it silently: an audit-start message ("Auditing goal completion…") and an audit-result message ("completion accepted — goal archived" / "paused as blocked — …"). By default these are delivered through OpenCode's structured log (`client.app.log`, visible to the user). Provide an `auditMessenger(sessionID, text)` plugin option to route them elsewhere (for example into the live conversation once a suitable message API is available), or set `auditMessages: false` to disable them.
+When the assistant marks a goal complete or blocked, the plugin announces the audit instead of doing it silently: an audit-start message ("Auditing goal completion…") and an audit-result message ("completion accepted — goal archived" / "paused as blocked — …"). By default these are written to OpenCode's structured log and shown as a TUI toast when that client capability is available. Provide an `auditMessenger(sessionID, text)` plugin option to route them elsewhere, or set `auditMessages: false` to disable them.
 ## Completion auditor (optional)
 
 By default a `[goal:complete]` is accepted on the assistant's word. You can require an independent audit before a goal is archived:
@@ -348,20 +353,24 @@ By default a `[goal:complete]` is accepted on the assistant's word. You can requ
 - `completionAudit: true` — the plugin spawns an independent OpenCode child session to verify the completion against the goal and workspace. The auditor replies with `[audit:approved]` or `[audit:rejected]` (with a reason).
 - `auditor: async ({ goal, sessionID, latestText }) => ({ approved, reason })` — supply your own auditor function (takes precedence over `completionAudit`).
 
-On **approval** the goal is archived as achieved. On **rejection** the goal is *not* archived — it is paused with stop reason `audit rejected` and the reason in its status, so you can address the gap and `/goal resume`. The built-in child-session auditor fails *open* (auto-approves) if the session API is unavailable, while a custom auditor that throws is treated as a rejection (fail closed). The audit is off unless one of these options is set.
+On **approval** the goal is archived as achieved. On **rejection** the goal is *not* archived — it is paused with stop reason `audit rejected` and the reason in its status, so you can address the gap and `/goal resume`. The built-in and custom auditors fail closed by default. The audit is off unless one of these options is set.
 
 Pass `auditorOptions` to tune the built-in auditor:
 
 ```js
-GoalPlugin({
-  completionAudit: true,
-  auditorOptions: {
-    timeoutMs: 60_000,  // default 120 000 ms; set lower for faster CI feedback
+await GoalPlugin(
+  { client },
+  {
+    completionAudit: true,
+    auditorOptions: {
+      timeoutMs: 60_000,  // default 120 000 ms; set lower for faster CI feedback
+      failurePolicy: "reject",
+    },
   },
-})
+)
 ```
 
-`timeoutMs` caps how long the built-in child-session auditor waits for a verdict. If the session doesn't reply within the timeout the auditor auto-approves (fail open) so the goal can still be archived. `auditorOptions` is ignored when a custom `auditor` function is supplied.
+`timeoutMs` caps how long the built-in child-session auditor waits for a verdict. `failurePolicy` defaults to `reject`: an unavailable API, missing child-session ID, provider error, or timeout rejects the audit and pauses the goal for review. Set it to `approve` only as an explicit compatibility escape hatch; an actual negative or malformed verifier verdict still rejects. `auditorOptions` is ignored when a custom `auditor` function is supplied.
 
 ## Prompt safety
 
@@ -369,12 +378,28 @@ The goal text is wrapped in `<goal_objective>` tags and labeled as user-provided
 
 ## Limitations
 
-This is a marker-based implementation. The assistant is responsible for outputting `[goal:complete]` or `[goal:blocked]` — there is no independent evaluator verifying completion against the original goal. Claude Code's native `/goal` uses a separate evaluator model; this plugin currently approximates the workflow using OpenCode hooks and explicit completion markers. A future version could add a separate evaluator once OpenCode exposes a clean plugin API for that flow.
+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 depends on `experimental.chat.system.transform` and other OpenCode plugin hooks that may change between OpenCode versions.
 
+Only one persistence-enabled OpenCode plugin instance may own a given `stateFilePath` at a time. A second process fails initialization with the owning PID/host instead of risking last-writer-wins state loss. Dispose the first host or configure a different path.
+
+## Diagnostics and recovery
+
+Start with `/goal status`, then `/goal history`. Together they show whether a goal is active, its stop reason and budget usage, and the recent lifecycle/checkpoint trail without exposing the entire on-disk ledger to the model.
+
+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. `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.
+
 ## Local development
 
 Point OpenCode at the source file directly for local testing:
@@ -403,6 +428,9 @@ Keep test files outside OpenCode's auto-loaded plugin directory — OpenCode wil
 npm test                # run the test suite
 npm run test:coverage   # run tests with coverage
 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 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
 ```

package/SECURITY.md

@@ -27,4 +27,32 @@ Relevant security-sensitive areas include:
 - leakage of goal text through logs or status output
 - malformed persisted state causing stale or unexpected goal recovery
 
-The goal text is wrapped in `<goal_objective>` tags and the closing tag is escaped before insertion. Other structural tags used in continuation prompts (`<goal_continuation>`, `<progress_budget>`, etc.) are not escaped. Crafted goal text containing those literal strings would close the tag early in the plaintext prompt; the model still receives plaintext rather than true privileged structure, but you should still treat goal text as trusted local input rather than pasting in arbitrary third-party content.
+## Threat Model and Trust Boundaries
+
+The plugin is an orchestration layer, not a sandbox. OpenCode, the selected model/provider, enabled tools, repository instructions, and the local operating-system account remain separate trust boundaries. The plugin does not grant a model new tool permissions, but auto-continuation gives already-authorized tools more opportunities to run. Use OpenCode's permission controls and avoid unattended goals in repositories or sessions you do not trust.
+
+The following inputs are untrusted:
+
+- goal objectives, criteria, constraints, blockers, and completion evidence
+- assistant/provider output and completion markers
+- session events and SDK responses
+- persisted state and lifecycle-ledger content
+- repository files and instructions encountered by the agent
+
+The plugin bounds and escapes prompt-control-like goal text, validates public tool inputs, limits completion-claim size, coalesces duplicate idle events, and pauses recovered goals. These controls reduce accidental loops and prompt confusion; they do not turn model output into trusted data or prove that cited evidence is true. Enable the independent completion auditor for higher-assurance work and keep its default fail-closed failure policy.
+
+## Data Stored and Exposed
+
+Persistence may contain objectives, criteria, constraints, assistant checkpoints, lifecycle events, blockers, completion evidence, changed-file names, and commands reported by the agent. Files are created with owner-only permissions where the platform supports POSIX modes, but filesystem permissions do not provide encryption at rest. State is project-local by default and is not intentionally uploaded by this plugin; the configured model/provider still receives prompt context through OpenCode. The lifecycle ledger rotates at a finite size and retention count, but retained generations still contain sensitive task text until they are rotated out or deleted.
+
+Status and history are session-scoped. The plugin intentionally avoids a process-wide diagnostic dump because a long-running OpenCode host may serve multiple projects or sessions. Before sharing logs or persistence files, remove secrets, proprietary text, usernames, absolute paths, and provider identifiers.
+
+## Security Assumptions and Residual Risk
+
+- A compromised OpenCode host, provider, dependency, or local account is outside the plugin's protection boundary.
+- Completion auditing improves confidence but is not a cryptographic attestation and may share the same provider failure modes as the working agent.
+- Disabling persistence avoids local state files but also removes restart recovery and ledger durability.
+- Setting the auditor's `failurePolicy` to `approve` weakens completion integrity and should be treated as a compatibility-only escape hatch.
+- Experimental OpenCode hook or SDK changes can alter interception, display, or continuation behavior; re-test the exact version/provider combination used for unattended work.
+
+Goal text is wrapped in `<goal_objective>` tags and labeled as user-provided task data. The plugin neutralizes opening and closing tags that match its prompt-control vocabulary, including role-like tags, before inserting user-controlled text. This is defense in depth for a plaintext model prompt, not a privilege boundary: treat goal text as untrusted content and do not assume tag escaping can make arbitrary third-party instructions safe.

package/demo/README.md

@@ -0,0 +1,86 @@
+# opencode-goal-plugin demo
+
+A minimal, reproducible demo: a failing test suite and a `/goal` that fixes
+it autonomously, with no supervision after you set the goal.
+
+`src/math.js` has a deliberate bug — `add(a, b)` returns `a - b` instead of
+`a + b`. `test/math.test.js` catches it. The goal below tells the agent to
+fix the failing tests; the plugin auto-continues the session until the
+agent verifies the suite passes and reports evidence-backed completion.
+
+## Prerequisites
+
+- Node.js >= 18
+- OpenCode installed (`opencode --version`)
+- At least one provider configured (`opencode auth login`)
+
+## Steps
+
+1. From the repo root, confirm the bug is real:
+
+   ```sh
+   cd demo
+   npm test
+   ```
+
+   You should see 2 failing tests — `add(2, 3)` returns `-1` instead of `5`.
+
+2. Launch OpenCode in this directory. `demo/opencode.json` already points
+   the plugin at the source file (`file:../src/goal-plugin.js`) and
+   registers the `goal` command, so no install step is needed:
+
+   ```sh
+   opencode
+   ```
+
+3. Set the goal. If this `demo/` directory sits inside a larger checkout
+   (e.g. you cloned the whole plugin repo), be specific about scope —
+   "this repo" can otherwise be read as the surrounding project rather
+   than the demo itself:
+
+   ```
+   /goal fix the failing tests in demo/test/math.test.js --max-turns 10
+   ```
+
+4. Walk away. The plugin keeps the goal in context, auto-continues after
+   each idle turn, and stops when the agent reports a substantiated
+   completion or a safety limit is reached (10 turns here).
+
+5. Check the result:
+
+   ```sh
+   npm test
+   ```
+
+   Both tests should now pass, and `src/math.js` should return `a + b`.
+
+## What to expect
+
+- The agent should read `test/math.test.js`, find the failing assertions,
+  locate the bug in `src/math.js`, fix `a - b` → `a + b`, rerun `npm test`
+  to confirm, and end its response with a `[goal:evidence]` line
+  summarizing what it verified, followed by `[goal:complete]`. A
+  `[goal:complete]` with no preceding `[goal:evidence]` is rejected by the
+  plugin and re-prompted — the agent can't just claim done, it has to show
+  its work.
+- Run `/goal status` at any point to see the current goal, elapsed
+  turns/time/tokens, and remaining budget (plus the accepted evidence once
+  complete). Run `/goal history` to see the lifecycle events and the
+  latest checkpoint. Run `/goal list` to see all live/backgrounded goals
+  in the session.
+- **Hook output display varies by OpenCode version and provider** — the
+  plugin's own status text may or may not render directly in the TUI (see
+  the [compatibility table](../README.md#compatibility-snapshot)). Either
+  way, the goal's state (limits, turn count, completion) is tracked
+  correctly; you can always verify it directly by inspecting the
+  persisted state at `.opencode/goals/state.json` in this directory.
+
+## Resetting the demo
+
+To run the demo again from a clean slate:
+
+```sh
+git checkout -- src/math.js
+/goal clear
+rm -rf .opencode/goals
+```

package/demo/opencode.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["file:../src/goal-plugin.js"],
+  "command": {
+    "goal": {
+      "description": "Set a session-scoped goal and auto-continue until complete.",
+      "template": "$ARGUMENTS",
+      "agent": "build"
+    }
+  }
+}

package/demo/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "opencode-goal-plugin-demo",
+  "private": true,
+  "version": "1.0.0",
+  "description": "Minimal reproducible demo: a failing test and a /goal that fixes it autonomously.",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/demo/src/math.js

@@ -0,0 +1,3 @@
+export function add(a, b) {
+  return a - b
+}

package/demo/test/math.test.js

@@ -0,0 +1,11 @@
+import test from "node:test"
+import assert from "node:assert/strict"
+import { add } from "../src/math.js"
+
+test("add returns the sum of two numbers", () => {
+  assert.equal(add(2, 3), 5)
+})
+
+test("add handles negative numbers", () => {
+  assert.equal(add(-1, -1), -2)
+})

package/docs/providers.md

@@ -0,0 +1,84 @@
+# Provider / model compatibility
+
+opencode-goal-plugin works with any model OpenCode can talk to, but two things
+vary by provider and model:
+
+1. **Marker compliance** — whether the model reliably ends its response with
+   `[goal:complete]` (or the bracket-less form) on its own final line, with a
+   preceding `[goal:evidence]` line summarizing what it actually verified.
+   Since the completion-evidence requirement was added, a bare
+   `[goal:complete]` with no evidence line is **rejected** and the plugin
+   re-prompts with an explicit `<evidence_required>` block — this is a
+   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.
+
+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
+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.
+
+## Tested models
+
+| Provider | Model | Marker compliance | Notes |
+|---|---|---|---|
+| `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. |
+
+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.
+
+## Strict-template backends
+
+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
+[`test/goal-plugin.test.js`](../test/goal-plugin.test.js) and does not
+require any provider-specific configuration.
+
+## Testing a new model
+
+No LLM call is required to verify the plugin loads correctly — run
+`npm run verify` first. To check marker compliance and hook behavior for a
+specific provider/model:
+
+1. Point an OpenCode config at the plugin (see
+   [Local development](../README.md#local-development) in the README) and
+   register the `goal` command.
+2. Launch OpenCode against the model you want to test:
+   ```sh
+   opencode -m <provider>/<model>
+   ```
+3. Run a short, deterministic goal that should complete in one or two turns:
+   ```
+   /goal say hi and end with [goal:complete] --max-turns 2
+   ```
+4. Check whether the first attempt includes a proper `[goal:evidence]` line
+   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.
+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`
+   reflect what actually happened — this is authoritative even when the TUI
+   display doesn't show the plugin's own output.
+7. Add a row to the table above with your findings, including the OpenCode
+   version you tested against.