opencode-reviewer 2.0.0 → 2.0.2

package/README.md

@@ -3,8 +3,8 @@
 Reviews pending permissions in the [OpenCode](https://github.com/anomalyco/opencode) sidebar using a separate LLM. Reviews
 native shell commands, file edits, and external-directory access. Skill, MCP and
 custom-tool requests currently remain manual.
-Supports streaming explanations, saved report history, auto-approval, and Linux
-desktop notifications with distinct sounds.
+Supports streaming explanations, saved report history and stats, auto-approval, and Linux
+desktop notifications (Gnome) with distinct sounds.
 
 This plugin is meant to enable you to run sessions with less frequent input in a safer way. Also giving the reviewer context of specific files the agent might want to run/see/... The review prompts are freely configurable, so you can determine the reviewers behavior very accurately.
 
@@ -14,9 +14,8 @@ This plugin is meant to enable you to run sessions with less frequent input in a
 
 ![](./assets/recording.gif)
 
-Targets OpenCode V2 on Linux. Host version numbers do not gate plugin activation;
-the companion protocol and actual scoped API contracts govern review and approval.
-Verified host checks are recorded in the maintainer migration plan.
+For OpenCode V2 on Linux. The plugin checks the server companion's protocol and
+each request's data and scope rather than allowing only specific host versions.
 
 ## Install and config
 
@@ -30,7 +29,7 @@ There is no project-local CLI configuration. OpenCode loads the
   "$schema": "https://opencode.ai/v2/cli.json",
   "plugins": [
     {
-      "package": "opencode-reviewer@2.0.0",
+      "package": "opencode-reviewer@latest",
       "options": {
         "baseURL": "https://openrouter.ai/api/v1",
         "model": "your-model",
@@ -80,28 +79,18 @@ launching OpenCode. The inline key takes precedence. Omit both for an unauthenti
 endpoint. Remove `instructions` to use the built-in prompts and
 `notificationSoundDirectory` to use the bundled sounds.
 
-The connection, credential and directory values above are examples, not defaults.
-All boolean, numeric and per-type notification values shown are the defaults.
-Restart OpenCode after changing reviewer configuration. Also load the server
-companion in `opencode.json`, globally or in the project. Keep permission rules
-only in this server configuration, not in `cli.json`:
+You also need to edit `opencode.json`, as the plugin needs to be informed of states
+that are not exposed by TUI APIs:
 
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugins": ["opencode-reviewer@2.0.0"],
-  "permissions": [
-    { "action": "shell", "resource": "*", "effect": "ask" },
-    { "action": "edit", "resource": "*", "effect": "ask" },
-    { "action": "skill", "resource": "*", "effect": "ask" },
-    { "action": "external_directory", "resource": "*", "effect": "ask" }
-  ]
+  "plugins": ["opencode-reviewer@latest"],
 }
 ```
 
-Merge these entries with your existing configuration. Rules are ordered; the last
-matching rule wins. Reviews run only when OpenCode asks for permission. Existing
-`allow` rules and native autoaccept skip review. See OpenCode's
+### Opencode docs
+
 [server config](https://opencode.ai/v2/docs/config),
 [CLI config](https://opencode.ai/v2/docs/cli/config) and
 [CLI plugins](https://opencode.ai/v2/docs/build/plugins/cli) guides.
@@ -109,7 +98,7 @@ matching rule wins. Reviews run only when OpenCode asks for permission. Existing
 ## Options reference
 
 These are options inside the plugin's `options` object in global `cli.json`.
-Defaults apply only to omitted options; `null` is invalid. Boolean and integer
+Defaults apply only to omitted options. `null` is invalid. Boolean and integer
 options require JSON booleans and numbers, not quoted strings. Integer ranges are
 inclusive, fractions are invalid, and the maximum safe integer is
 9,007,199,254,740,991. Unknown option names are rejected.
@@ -128,7 +117,7 @@ inclusive, fractions are invalid, and the maximum safe integer is
 | `reviewMcp` | boolean | `false` | MCP-review category switch. V2 MCP collection is currently unsupported; enabling this does not supply missing origin/catalog evidence or permit automatic approval. |
 | `reviewCustomTools` | boolean | `false` | Custom-tool review category switch. V2 custom-tool collection is currently unsupported; these requests remain manual. |
 | `reviewExternalDirectories` | boolean | `false` | Review directory access independently of operation-review switches. Directory approval can resume the operation without another prompt. |
-| `autoApprove` | boolean | `false` | Allow Safe reviews once automatically. Normally waits for completion, validation and the countdown. Requires the top-level conversation and physical presentation proof; subagent browsing never permits automatic approval. Normal-mode report-history cover has a separate physical-proof exception. |
+| `autoApprove` | boolean | `false` | Allow Safe reviews once automatically. Normally waits for completion, validation and the countdown. Works throughout the current conversation, including subagent browsing and hidden/covered reports. Home, dashboards, unrelated conversations and native permission decision editing wait without cancellation. |
 | `fastMode` | boolean | `false` | Requires `autoApprove: true`. Approve an eligible, front-of-queue request as soon as a Safe rating is parsed, bypassing the countdown. Respects `stream`; with `stream: false`, waits for the complete validated response. Finish the report and save it in the background after approval. |
 | `extraCareful` | boolean | `true` | Include extra-careful guidance when `autoApprove` is enabled. Setting `false` omits that guidance without disabling automatic approval. |
 | `autoApproveDelaySeconds` | integer | `15` | `0`–`3600` seconds. Positive values include an extra 200 ms initial grace; `0` skips the wait but keeps the other approval checks. Ignored in fast mode. |
@@ -143,10 +132,10 @@ inclusive, fractions are invalid, and the maximum safe integer is
 | `maxFiles` | integer | `6` | `1`–`1000` distinct file candidates per shell/edit review, including unavailable candidates. |
 | `maxEvidenceBytes` | integer | `131072` | `1`–`16777216` bytes for command/source content, edit diffs or category-specific JSON evidence. Optional items are omitted whole; oversized mandatory evidence fails analysis. This is not a cap on the full prompt or HTTP request. |
 
-Notification channels are independent: `banner: false, sound: true` is sound-only;
-`banner: true, sound: false` is banner-only; both `false` disable that type.
+Notification channels are independent: `banner: false, sound: true` is sound-only,
+`banner: true, sound: false` is banner-only, both `false` disable that type.
 `notify` and `notifySound` take precedence. Invalid notification settings disable
-notification work without invalidating otherwise valid review settings.
+notification.
 
 My LLMs insist on writing a bunch of useless text to my README, so I collapsed them here in case anyone wants to inflict themselves (or more likely their agent) the pain of reading it.
 
@@ -156,47 +145,49 @@ The sidebar shows Safe, Unsafe, or Analysis unavailable. Explanations support
 Markdown and scrolling. If the sidebar is hidden, use OpenCode's Show sidebar
 command.
 
-The reviewer side panel appears only in the top-level conversation. Browsing its
-subagents, including nested subagents, hides the panel and prevents both normal
-and fast automatic approvals. Reviews may finish while hidden. A Safe report that
-has never started a normal countdown may first become eligible after returning to
-the root and receiving real presentation proof, with a fresh countdown. Leaving
-the root after a countdown starts permanently makes that request manual for the
-running controller, even after returning or disabling/re-enabling review.
-
-Automatic approval requires mouse tracking for the host's painted-panel ownership
-checks. With mouse tracking disabled, reports remain available for manual review.
-The plugin never enables mouse tracking. It preserves sidebar visibility except
-after an explicit approval-notification click, when a root frame confirms the
-sidebar is absent before revealing it.
-
-The category switches are retained, but the current V2 collectors do not support
-skill, MCP or custom-tool reviews. Missing mandatory skill instructions and unproven
-MCP/custom origin or catalog evidence leave these requests manual, not Safe.
-
-Native Code Mode and its tool search remain enabled. Exactly linked native calls
-can be reviewed; ambiguously linked nested calls remain manual. The plugin assumes
-installed plugins preserve native tool meanings, do not replace or alias native
-executors, and do not rewrite commands after evidence capture.
-
-Subagent requests carry the genuine latest root-user prompt. Exact immediate
-delegation is currently unavailable through the supported V2 evidence path and is
-factually omitted, not guessed from older tasks, sibling requests or queued follow-ups.
-Optional context omissions do not alone prevent review when mandatory operation
-evidence is verified. Context cannot override the review contract.
+The reviewer panel appears only in the main conversation. Opening any subagent,
+including a nested one, hides the panel but does not stop normal or fast auto-approval
+within that conversation. A Safe report need not be displayed before approval.
+Command selectors, dialogs, report history, other session panels, sidebar hiding,
+terminal resizing and disabled mouse tracking do not cancel automation.
+
+Home, dashboard routes and unrelated conversations hold approval until you return
+to the request's conversation. A countdown already started keeps its original
+deadline; if it expires while waiting, approval can proceed immediately on return
+after fresh checks. A review that has never started a countdown starts its full
+delay when its conversation becomes eligible.
+
+The plugin doesn't enable mouse tracking or reveal a hidden sidebar unless you
+click an approval notification; it checks that the sidebar is absent from the main
+conversation before showing it. Hidden automatic reports are saved normally.
+
+The skill, MCP and custom-tool options are still present, but these reviews aren't
+supported in V2. The reviewer can't get the required skill instructions or verify
+the source and catalog information for MCP and custom tools. Those requests need
+manual approval; they aren't rated Safe.
+
+Code Mode and its tool search stay enabled. Native tool calls can be reviewed when
+the reviewer can match them exactly to their permission requests. Nested calls
+without an exact match need manual approval. This assumes other installed plugins don't change
+what native tools do, replace or alias their executors, or rewrite commands after
+the reviewer has captured them.
+
+Subagent reviews include the latest user prompt from the main conversation. The
+V2 evidence collector can't get the exact task passed to the requesting subagent,
+so it leaves that out rather than guessing from older tasks, sibling requests or
+queued follow-ups. Missing optional context doesn't prevent review if the required
+operation evidence is verified. Context can't override the review rules.
 
 With streaming enabled, Evaluating and its spinner disappear when a rating arrives.
-The rating remains provisional until the full response is validated. A retry
-clears the preview and restores the loading indicator. Normal auto-approval
-starts only after the full response is validated and rendered on the top-level
-conversation, with matching physical presentation proof.
-
-With `autoApprove: true` and `fastMode: true`, a parsed Safe rating approves the
-current eligible permission immediately, without a countdown or waiting for the
-rest of a streamed report. It still requires native front-of-queue ownership and
-physical presentation on the top-level conversation. Subagent browsing, explicit
-sidebar hiding, covering dialogs and report history prevent fast approval. Without
-streaming, fast mode waits for the full validated response and then skips the countdown.
+The rating is provisional until the full response passes validation. A retry
+clears the preview and brings back the loading indicator. Normal auto-approval
+waits for the full validated report, then the configured countdown.
+
+With `autoApprove: true` and `fastMode: true`, a parsed Safe rating can approve the
+request before the streamed report finishes, without a countdown. The request must
+be first in OpenCode's permission queue and belong to the currently viewed conversation
+or its descendants. The report may be hidden or covered. Without streaming, fast
+mode waits for the full validated response, then skips the countdown.
 
 After confirmed fast approval, the live panel shows **Auto-approved; finishing
 report…** and stays ahead of newer requests until its report finishes. Hiding the
@@ -219,13 +210,16 @@ limits and overall timeout still apply. Retried requests can incur additional
 provider charges, and unreported usage remains unknown.
 
 During an auto-approval countdown, click the countdown to allow once immediately,
-or Cancel to leave the request manual. Hiding or covering the panel also cancels
-that request's countdown, except for this plugin's physically proven report-history
-cover on the root route. Browsing any subagent or switching conversations cancels it.
-Returning, remounting or re-enabling cannot revive a canceled request. An uncertain
-approval write also remains manual and is never retried.
-Cancel before using native Allow always or rejection
-forms; those forms alone do not stop the countdown.
+or Cancel to leave the request manual. Only explicit stop actions, such as Cancel,
+disabling review, or native interruption/rejection, stop automation for that request.
+Returning, reopening the panel or re-enabling review won't restart a canceled countdown.
+Selecting native Allow always or Reject, or editing a rejection reason, holds
+approval without cancellation. Returning to Allow once resumes eligibility with
+the original countdown deadline. Ambiguous native choice state also waits.
+Temporary queue/cache/read failures wait and recover after fresh verification.
+Changed or unverifiable requests remain manual. If the plugin can't confirm the
+result of a sent approval attempt, it never retries that write.
+Cancel remains available during native preparation, until the approval is sent.
 Positive countdowns add a 200 ms initial grace and then update on remaining-time
 boundaries. A zero-second setting still approves without that grace.
 
@@ -234,9 +228,9 @@ descendants. The setting is saved for resume. Both commands are also in the comm
 palette. Disabling stops unapproved reviews and countdowns while native permission
 controls remain available. Already-approved fast-mode reports finish in the background.
 
-After a server reconnect or companion replacement, the old controller stops reviews
-and automatic replies until the plugin is reloaded or OpenCode is restarted. It does
-not mix old permission caches with a new connection.
+If the server reconnects or the companion is replaced, reviews and auto-approval
+stop. Reload the plugin or restart OpenCode to resume. This keeps cached permissions
+from the old connection separate from the new one.
 
 ### Report history
 
@@ -247,6 +241,7 @@ PageUp/PageDown scroll. Close or Escape closes history. Repeating the command
 returns to the newest report. History remains available with review disabled or
 invalid reviewer configuration. The history command preserves a hidden sidebar;
 clicking an approval notification reveals it and selects that permission's live or saved report.
+Keyboard browsing also works with mouse tracking off.
 
 Each entry shows the original report, available usage, model, provider and outcome:
 **Auto approved**, **Manually approved**, **Cancelled**, or **Rejected**. Cancelled
@@ -256,20 +251,25 @@ native Allow once replies whose submitting client cannot be identified. History
 keeps the latest completed report, which can differ from the report that caused
 approval in another window.
 
-Normal-mode history cover preserves an ongoing countdown only on
-the root route, with physical proof of the history heading/footer and rendered
-report. A newly completed Safe review may become eligible under that same proof.
-Native dialogs, including the command palette, still cancel an active countdown;
-opening history afterward cannot restart it. Fast mode has no history-cover
-exception. Browsing saved reports never approves a request or replays notifications.
-
-Reports are saved only after a qualifying permission resolution. Saved reports
-can contain private text and are retained in OpenCode's local state directory
-unless deletion ownership is proven. A conversation deletion does not authorize
-purging reports without proven server/scope ownership. Uncertain offline deletions
-retain history; a missing list entry or bare 404 is not enough. Windows using the
-same state directory share this history, partitioned by host directory and root
-conversation. Uncommitted reports can be lost on shutdown or prolonged storage failure.
+Opening report history does not hold normal or fast auto-approval for eligible live
+requests. Browsing saved reports doesn't itself approve requests or replay notifications.
+
+Reports are saved only after a permission resolution that qualifies for history.
+They can contain private text and are kept under OpenCode's local state base:
+`$XDG_STATE_HOME`, or `~/.local/state` when unset. Safely accessible history stays
+under `opencode/opencode-reviewer/`. If the host directory is unsuitable for private
+storage, the plugin uses its private, plugin-owned sibling
+`opencode-reviewer-state/opencode-reviewer/` without changing host-directory permissions.
+An existing safe sibling database remains in use across restarts. Conversation
+enable/disable settings stay in the original OpenCode state directory.
+Saved modes require private ownership and a nonreplaceable path; an untrusted or
+unreadable mode suspends review rather than silently enabling it.
+The plugin deletes them only when it can verify that a deleted conversation belongs
+to the matching server and scope. If that can't be verified after an offline
+deletion, it keeps the history; a missing list entry or bare 404 isn't enough.
+Windows using the same state directory share history, grouped by host directory
+and main conversation. Reports not yet saved can be lost on shutdown or during a
+prolonged storage failure.
 
 ### Usage totals
 
@@ -432,7 +432,8 @@ Use Node.js 24.15.0+ within 24.x, or 22.22.2+ within 22.x, and npm.
 Run `npm ci --ignore-scripts`, then `npm run check` for typechecking, source tests,
 pure-helper tests and the build. `npm run test:helpers` runs the helper checks
 without building or starting OpenCode. Pull-request CI checks both Node versions
-and runs a separate representative Linux OpenCode 2.0.26 fixture profile.
+and runs a separate representative Linux fixture profile on stock OpenCode
+2.0.26 and 2.0.27.
 After building, run `node scripts/test-runtime.mjs --profile ci` for that same
 profile. Use `node scripts/test-runtime.mjs --list` for the complete runtime
 inventory or `node scripts/test-runtime.mjs --plan --profile ci` for a

package/THIRD_PARTY_NOTICES.md

@@ -31,8 +31,10 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 https://github.com/anomalyco/opencode/tree/v2.0.26/packages/theme
 
-The pinned theme helper is bundled in the terminal payload. Solid and OpenTUI
-remain host-provided external dependencies.
+The pinned theme syntax helper is bundled unchanged in the terminal payload.
+A build-time adapter replaces its public barrel with a syntax-only re-export;
+unused theme parsers, schemas and their Effect dependency are not bundled.
+Solid and OpenTUI remain host-provided external dependencies.
 
 License source: https://github.com/anomalyco/opencode/blob/v2.0.26/LICENSE