opencode-reviewer 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,10 @@
 # OpenCode Reviewer
 
-Reviews pending permissions in the OpenCode sidebar using a separate LLM. Covers
+> ⚠️ **NOT v2 COMPATIBLE YET**
+> 
+> I recommend not upgrading opencode to v2 yet as many things are still unstable
+
+Reviews pending permissions in the [OpenCode](https://github.com/anomalyco/opencode) sidebar using a separate LLM. Covers
 shell commands, file edits, skill loading, MCP calls, custom tools, and external-directory access.
 Supports streaming explanations, saved report history, auto-approval, and Linux
 desktop notifications with distinct sounds.
@@ -13,7 +17,8 @@ This plugin is meant to enable you to run sessions with less frequent input in a
 
 ![](./assets/recording.gif)
 
-Requires OpenCode 1.18.35 or newer on Linux.
+Verified with OpenCode 1.18.35 on Linux. Version **1.0.2** is the final release
+compatible with OpenCode V1.
 
 ## Install and config
 
@@ -25,7 +30,7 @@ OpenCode installs the [npm package](https://www.npmjs.com/package/opencode-revie
   "$schema": "https://opencode.ai/tui.json",
   "plugin": [
     [
-      "opencode-reviewer@latest",
+      "opencode-reviewer@1.0.2",
       {
         "baseURL": "https://openrouter.ai/api/v1",
         "model": "your-model",
@@ -50,7 +55,7 @@ OpenCode installs the [npm package](https://www.npmjs.com/package/opencode-revie
           "attention": { "banner": true, "sound": true },
           "unsafe": { "banner": true, "sound": true },
           "question": { "banner": true, "sound": true },
-          "approved": { "banner": true, "sound": true },
+          "approved": { "banner": true, "sound": false },
           "error": { "banner": true, "sound": true },
           "ended": { "banner": true, "sound": true }
         },
@@ -96,21 +101,21 @@ inclusive, fractions are invalid, and the maximum safe integer is
 | `apiKey` | string | Unset | Nonempty Bearer token. Takes precedence over `apiKeyEnv`. |
 | `apiKeyEnv` | string | Unset | Environment-variable name matching `[A-Za-z_][A-Za-z_0-9]*`. Without an inline key, its value must be set and nonblank when a review runs. Omit both key options for no Authorization header. |
 | `instructions` | string | Unset (built-ins) | Absolute, NUL-free directory path containing overrides for the [prompt templates](https://github.com/mightykatun/opencode-reviewer/tree/main/prompts), not inline instructions. Missing named files use built-ins; supplied files must be readable, regular, non-symlink, nonempty UTF-8 text up to 64 KiB. Fixed contracts cannot be overridden. |
-| `stream` | boolean | `false` | Request SSE and show provisional rating/text updates. Normal automatic approval waits for a completed, validated and rendered report; fast mode can approve on an early Safe rating. |
+| `stream` | boolean | `false` | Request SSE and show provisional rating/text updates. Normal automatic approval waits for a completed, validated report; fast mode can approve on an early Safe rating. Presentation rules are described below. |
 | `reviewBash` | boolean | `true` | Review native shell-command permissions. |
 | `reviewEdits` | boolean | `true` | Review native `edit`, `write` and `apply_patch` permissions. |
 | `reviewSkills` | boolean | `true` | Review native skill-load permissions for dangerous guidance and relevance to the current task. Supplies the host's skill instructions and bounded, directly referenced supporting files within the skill directory. |
 | `reviewMcp` | boolean | `false` | Review identifiable MCP tool and resource permissions. |
 | `reviewCustomTools` | boolean | `false` | Review permissions requested by registered custom tools. |
 | `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, rendering and the countdown, including behind this plugin's report history. |
-| `fastMode` | boolean | `false` | Requires `autoApprove: true`. Approve a visible, 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. |
+| `autoApprove` | boolean | `false` | Allow Safe reviews once automatically. Normally waits for completion, validation and the countdown. Root-view rendering is required, including behind report history; same-conversation subagent browsing permits hidden approval. |
+| `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 have an extra one-second initial hold; `0` skips the wait but retains rendering and eligibility checks. Ignored in fast mode. |
+| `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. |
 | `notify` | boolean | `true` | Master switch for desktop banners, sounds and reminders. `false` overrides all per-type controls. |
 | `notifySound` | boolean | `true` | Master switch for notification audio. `false` silences every type and reminder without disabling enabled banners. |
 | `staleReminderSeconds` | integer | `60` | `0` through the maximum safe integer, in seconds. `0` disables reminders; otherwise eligible pending human interactions repeat at this interval, limited to the native front-of-queue blocker per conversation. |
-| `notifications` | object | All types: `banner: true`, `sound: true` | Keys: `attention`, `unsafe`, `question`, `approved`, `error`, `ended`. Each entry is an object with optional `banner` and `sound` booleans. Omitted types/fields remain enabled; unknown types/fields are invalid. Controls also apply to reminders. |
+| `notifications` | object | All banners enabled; all sounds enabled except `approved` | Keys: `attention`, `unsafe`, `question`, `approved`, `error`, `ended`. Each entry is an object with optional `banner` and `sound` booleans. Omitted types/fields retain their defaults; unknown types/fields are invalid. Controls also apply to reminders. |
 | `notificationSoundDirectory` | string | Unset (bundled sounds) | Absolute, NUL-free path, at most 4096 string code units. Use the six notification type names as basenames: usable `.wav` first, then `.mp3`, then the corresponding bundled sound. |
 | `formatRetries` | integer | `1` | `0`–`100` additional assessment-format correction attempts. `0` disables format corrections, not independent transport recovery. |
 | `maxOutputTokens` | integer | `4096` | `1` through the maximum safe integer. Sent as `max_tokens` on every reviewer POST, including retries/corrections. Your provider/model enforces its supported output limit. |
@@ -131,6 +136,16 @@ 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 while reviews and both normal
+and fast automatic approvals continue. Countdown deadlines stay the same, and new
+Safe reviews can become eligible while hidden. Return to the top-level conversation
+to see the current report or browse saved history.
+
+On the top-level route, automatic approval requires mouse tracking for the host's
+painted-panel ownership checks. With mouse tracking disabled there, reports remain
+available for manual review.
+
 Skill-load review is enabled by default; set `skill` permissions to `ask` in
 `opencode.json` to receive reviews. Its prompt requires both bounded risk and clear
 relevance to the current work. A harmless but irrelevant skill is rated Unsafe.
@@ -151,13 +166,16 @@ that can override its review contract.
 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.
+starts only after the full response is validated and rendered, except that rendering
+is not required while the panel is intentionally hidden by same-conversation
+subagent browsing.
 
 With `autoApprove: true` and `fastMode: true`, a parsed Safe rating approves the
-current visible permission immediately, without a countdown or waiting for the
-rest of a streamed report. Hidden panels and covering dialogs or history prevent
-fast approval. Without streaming, fast mode waits for the full validated response
-and then skips the countdown.
+current eligible permission immediately, without a countdown or waiting for the
+rest of a streamed report. Same-conversation subagent browsing also permits fast
+approval while the panel is hidden. 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.
 
 After confirmed fast approval, the live panel shows **Auto-approved; finishing
 report…** and stays ahead of newer requests until its report finishes. Hiding the
@@ -181,11 +199,14 @@ 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 when covered by this plugin's report history.
+that request's countdown, except when covered by this plugin's report history or
+intentionally hidden while browsing the same conversation's subagents. Switching
+to an unrelated conversation still cancels it. Returning cannot revive a canceled
+request.
 Cancel before using native Allow always or rejection
 forms; those forms alone do not stop the countdown.
-Positive countdowns hold their configured starting number for one extra second
-before counting down. A zero-second setting still approves without that hold.
+Positive countdowns add a 200 ms initial grace and then update on remaining-time
+boundaries. A zero-second setting still approves without that grace.
 
 `/reviewer-disable` and `/reviewer-enable` control the current conversation and its
 descendants. The setting is saved for resume. Both commands are also in the command
@@ -291,11 +312,12 @@ terminal is focused:
   with its own sound. Provisional streamed ratings never notify.
 - **Agent has a question:** a pending agent question at the front of the native
   input queue, with its own sound.
-- **Reviewer approved a permission:** sent with the approval sound after confirmed
+- **Reviewer approved a permission:** a silent banner by default, sent after confirmed
   automatic approval, including fast mode while its report is still streaming.
   Positive and zero delays also notify on success; the countdown is silent.
-  Approval sounds are limited to
-  one every two seconds; every eligible banner is retained for delivery.
+  Opt in with `notifications.approved.sound: true`. Approval sounds are limited to
+  one every two seconds, including delayed playback. Sounds from the same session
+  wait for the previous player to finish, so successive alerts do not overlap.
 - **Session error:** an unrecovered session/provider failure, not a review failure.
 - **Session ended:** a completed root-agent response, not a question/permission
   pause or an explicit user interruption.
@@ -311,7 +333,7 @@ actionable position, restarting analysis or entering automatic approval cancels
 pending attention delivery and reminders.
 
 Each type's `banner` and `sound` can be controlled independently. For example,
-`notifications.approved.banner: false` keeps approval sounds without banners;
+`notifications.approved: { "banner": false, "sound": true }` enables approval sounds without banners;
 `notifications.question.sound: false` keeps question banners silent. Set both to
 `false` to disable that type. `notify: false` overrides all types and disables
 reminders too; `notifySound: false` silences all types and their reminders.
@@ -319,7 +341,8 @@ Sound-only delivery does not require a desktop banner or delivery acknowledgemen
 Invalid notification settings disable notification work without disabling reviews.
 
 Pending permissions and questions repeat after `staleReminderSeconds`, measured
-from initial dispatch, even if desktop delivery fails. Reminders replace their
+from actual initial dispatch, even if desktop delivery fails. Capacity waiting
+does not start the reminder clock or replace an undelivered initial alert. Reminders replace their
 previous banner and append **(Reminder)** to the event text, reusing the same
 sound, icon, session heading and click target. Only the native front-of-queue
 interaction per root conversation repeats: permissions precede questions, with
@@ -362,6 +385,18 @@ Audio is prepared before showing its banner and played from the normalized cache
 with a low-latency buffer; preparation never blocks permission approval.
 `stdbuf` makes delivery acknowledgements immediate instead of waiting for
 `notify-send` to flush its output when the banner closes.
+Delivery is bounded: up to 64 active tickets (48 routine), 256 waiting actionable
+episodes, and 128 waiting routine events. A full routine backlog drops new
+approval/error/completion events; already admitted events retain their exact
+targets. Actionable attention/Unsafe/question work has priority, rotating among
+roots; after eight actionable dispatches, waiting routine work gets a turn.
+Each root has only its current actionable episode, and waiting reminders coalesce.
+The process pool allows 24 children: 20 banners (16 routine), two players, one
+withdrawal and one activation. Audio preparation has two actual-operation slots;
+audio waiting is bounded to 64 requests. Cancellation and timeouts do not free
+physical slots until their operations settle. Queued actionable work is canceled
+when its request resolves or loses native queue ownership. Desktop/process
+failures remain best-effort and do not delay permission approval.
 Disable overlapping notification plugins to avoid duplicate alerts.
 </details>
 
@@ -370,6 +405,12 @@ Disable overlapping notification plugins to avoid duplicate alerts.
 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.
+without building or starting OpenCode. Pull-request CI checks both Node versions
+and runs a separate representative Linux OpenCode 1.18.35 fixture profile.
+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
+host-independent plan. Profiles select documented scenario/flag combinations;
+interactive desktop checks and historical replays have separate prerequisites.
 See [AGENTS.md](https://github.com/mightykatun/opencode-reviewer/blob/main/AGENTS.md)
 for runtime tests and the tag-driven release process.