opencode-bug-review-gate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coral Bricks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# opencode-bug-review-gate
+
+An [opencode](https://opencode.ai) plugin that automatically runs a bug review
+over every turn that edited files, drives fix rounds for blocking findings, and
+resumes turns that were interrupted midstream.
+
+## Why
+
+Two failure modes make coding sessions silently stall or ship unreviewed
+changes:
+
+1. **Unreviewed edits** — agents mark turns "done" without anyone checking the
+   diff. This gate runs a dedicated review subagent after every turn that
+   edited files, parses its verdict, and re-prompts the session to fix every
+   BUG-class finding (up to `maxFixRounds` rounds).
+2. **Interrupted turns** — a model stream can terminate prematurely (e.g. a
+   spurious EOS from the provider or the model itself) and report a clean
+   `stop` with zero output. opencode treats that as a normal end-of-turn, so
+   the session just goes idle. This gate detects the signature — a finished
+   turn with no error, no text, and no tool calls — and automatically sends a
+   continue prompt (up to `maxAutoContinues` times), resuming the task with
+   the same agent that was interrupted. It also retries a review that dies
+   the same way, and resumes a fix turn that dies the same way.
+
+## Install
+
+Add to `opencode.json` (or `~/.config/opencode/opencode.json`):
+
+```json
+{
+  "plugin": ["opencode-bug-review-gate"]
+}
+```
+
+With options:
+
+```json
+{
+  "plugin": [
+    ["opencode-bug-review-gate", { "maxAutoContinues": 3 }]
+  ]
+}
+```
+
+Restart opencode after changing config — plugins are loaded once at startup.
+
+## Options
+
+| Option                | Default        | Description                                                              |
+| --------------------- | -------------- | ------------------------------------------------------------------------ |
+| `reviewAgent`         | `"bug-review"` | Agent that performs the static review.                                  |
+| `maxFixRounds`        | `2`            | Fix-and-re-review rounds after an `ISSUES` verdict.                       |
+| `maxNoVerdictRetries` | `1`            | Retries when a review ends without a verdict line.                       |
+| `maxAutoContinues`    | `2`            | Resume attempts for turns that stop with no model output.                 |
+| `askResponse`         | `"once"`       | How gate-driven turns answer permission asks (`"once"` or `"reject"`).    |
+| `autoContinue`        | `true`         | Resume turns that stop with no model output.                             |
+| `defineAgent`         | `true`         | Register a default `bug-review` subagent when the config has none.       |
+
+## The default review agent
+
+If your config does not define an agent named `bug-review` (or your
+`reviewAgent` value), the plugin registers one via its `config` hook: a
+subagent that cannot edit files (`edit: deny`, the hard guarantee — read,
+glob, grep, and list default to allow), whose bash permission allows only
+git diff/log/status/show and asks for everything else, and whose prompt
+directs it to find real defects, classify findings (BUG / RISK / VERIFY),
+cite `file:line`, and end with a verdict line:
+
+```
+PASS — no blocking issues found
+ISSUES — n blocking, m advisory
+```
+
+Define your own agent with that name to override it entirely.
+
+## Security notes
+
+- The review agent cannot edit or write files, and the review prompt forbids
+  executing the code under review.
+- While the gate is driving a session (review / fix / resume turns), permission
+  asks are answered automatically (`askResponse`, default `"once"` = allow one
+  execution) so headless runs cannot hang on a dialog. Normal user turns are
+  never auto-answered. Set `askResponse` to `"reject"` to make gate turns fail
+  fast instead, or restrict the review agent's permissions further.
+- Auto-resume only fires for turns that edited files (the gate only runs for
+  those), only when the turn's stream ended with no error and no visible
+  output, and is capped by `maxAutoContinues`.
+
+## Verdicts
+
+- `PASS` — toast, session goes idle.
+- `ISSUES` — the gate prompts the session to fix every BUG-class finding and
+  re-reviews, up to `maxFixRounds` times; remaining issues produce a warning
+  toast.
+- No verdict after retries — warning toast, no auto-fixing.
+- Degenerate stops (main turn, review, or fix turn) — auto-continue, capped.
+
+## Compatibility
+
+Targets opencode ≥ 1.18 (plugin API with the `config` hook and
+`client.session.messages`). No runtime dependencies.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "opencode-bug-review-gate",
+  "version": "0.1.0",
+  "description": "opencode plugin: automated post-change bug review gate, with auto-resume for turns interrupted midstream",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.ts",
+  "author": "Coral Bricks",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Coral-Bricks-AI/opencode-bug-review-gate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Coral-Bricks-AI/opencode-bug-review-gate/issues"
+  },
+  "homepage": "https://github.com/Coral-Bricks-AI/opencode-bug-review-gate#readme",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "code-review",
+    "agent"
+  ],
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.18.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.18.4",
+    "typescript": "^5.9.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,372 @@
+import type { Plugin } from "@opencode-ai/plugin"
+
+// How the gate answers permission asks raised by its own review/fix/resume
+// turns. "once" keeps the turn alive (the agent may run the command one time);
+// "reject" would abort the turn entirely, losing the review.
+type AskResponse = "once" | "reject"
+
+export type Options = {
+  /** Agent that performs the static review. Defaults to "bug-review". */
+  reviewAgent?: string
+  /** Fix rounds after an ISSUES verdict. Defaults to 2. */
+  maxFixRounds?: number
+  /** Retries for a review that ends without a verdict line. Defaults to 1. */
+  maxNoVerdictRetries?: number
+  /** Auto-continues for turns that stop with no model output. Defaults to 2. */
+  maxAutoContinues?: number
+  /** How gate-driven turns answer permission asks. Defaults to "once". */
+  askResponse?: AskResponse
+  /** Resume turns that stop with no model output. Defaults to true. */
+  autoContinue?: boolean
+  /** Define the default review agent when the config does not provide one. Defaults to true. */
+  defineAgent?: boolean
+}
+
+const DEFAULT_REVIEW_AGENT_PROMPT = `You are a meticulous bug reviewer. Your job is to find real defects in
+code that was just written or modified, and to challenge the reasoning
+that produced it. You do NOT fix things — you report findings.
+
+Review the changes (ask for or locate the diff if not provided) and
+scrutinize:
+
+## Code correctness
+- Edge cases: empty inputs, zero/negative values, nil/null, off-by-one,
+  boundary conditions, unicode/encoding issues.
+- Error handling: unhandled exceptions, swallowed errors, missing
+  rollbacks/cleanup, resource leaks (files, connections, locks).
+- Concurrency: race conditions, deadlocks, non-thread-safe shared state.
+- Type/logic errors: wrong operators, inverted conditions, unreachable
+  branches, incorrect defaults, copy-paste mistakes (wrong variable
+  names, wrong constants).
+
+## Reasoning quality
+- Assumptions presented as facts: verify against the actual codebase,
+  not the claim.
+- Claims that code "works" or "handles X" without evidence — check the
+  code paths.
+- Mismatch between stated intent and what the code actually does.
+- Silent scope creep: changes to files/behavior beyond what was asked.
+
+## Security & robustness
+- Injection, path traversal, exposed secrets, unsafe deserialization,
+  missing auth checks on new endpoints.
+
+## Process
+- Run whatever read-only verification you can (grep for callers of
+  changed functions, check test coverage of modified paths, inspect
+  dependent code).
+- For each finding, cite file:line and explain the concrete failure
+  scenario (input → wrong behavior), not just a style complaint.
+- Classify each finding: BUG (will misbehave), RISK (could misbehave
+  under conditions), VERIFY (claim you could not confirm).
+- End with a verdict: "PASS — no blocking issues found" or "ISSUES —
+  n blocking, m advisory" plus a one-line summary.
+
+Be skeptical. A quiet, empty report is only acceptable if you actively
+looked and can say what you checked.`
+
+const DEFAULT_REVIEW_AGENT_DESCRIPTION =
+  "Reviews generated code and the reasoning behind it for bugs, edge cases, and incorrect assumptions. Use after any non-trivial code change, or whenever the main agent should verify its own work before finishing."
+
+const EDIT_TOOLS = new Set(["edit", "write", "patch", "apply"])
+
+type GateState = { edited: boolean; busy: boolean }
+
+type ReviewOutcome = "pass" | "no-verdict" | "issues-remain" | "no-fix-edits" | "fix-interrupted"
+
+function textOf(parts: unknown): string {
+  if (!Array.isArray(parts)) return ""
+  const out: string[] = []
+  for (const part of parts) {
+    if (part && typeof part === "object") {
+      const p = part as { type?: string; text?: unknown }
+      if (p.type === "text" && typeof p.text === "string") out.push(p.text)
+    }
+  }
+  return out.join("\n")
+}
+
+function lastVerdict(text: string): "PASS" | "ISSUES" | undefined {
+  let verdict: "PASS" | "ISSUES" | undefined
+  const re = /(?:^|\n)[ \t]*(PASS|ISSUES)\b/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(text))) verdict = m[1] as "PASS" | "ISSUES"
+  return verdict
+}
+
+export const BugReviewGate: Plugin = async ({ client, serverUrl }, rawOptions = {}) => {
+  const options = rawOptions as Options
+  const reviewAgent = options.reviewAgent ?? "bug-review"
+  const maxFixRounds = options.maxFixRounds ?? 2
+  const maxNoVerdictRetries = options.maxNoVerdictRetries ?? 1
+  const maxAutoContinues = options.maxAutoContinues ?? 2
+  const askResponse: AskResponse = options.askResponse ?? "once"
+  const autoContinue = options.autoContinue !== false
+  const defineAgent = options.defineAgent !== false
+  const marker = `[[gate:${reviewAgent}]]`
+
+  const state = new Map<string, GateState>()
+  const answered = new Set<string>()
+
+  const get = (sessionID: string): GateState => {
+    let s = state.get(sessionID)
+    if (!s) {
+      s = { edited: false, busy: false }
+      state.set(sessionID, s)
+    }
+    return s
+  }
+
+  const log = async (
+    level: "debug" | "info" | "warn" | "error",
+    message: string,
+    extra?: Record<string, unknown>,
+  ) => {
+    try {
+      await client.app.log({ body: { service: "bug-review-gate", level, message, extra } })
+    } catch {
+      // logging must never break the gate
+    }
+  }
+
+  const toast = async (message: string, variant: "success" | "warning" | "error") => {
+    try {
+      await client.tui.showToast({ body: { message, variant } })
+    } catch {
+      // no TUI attached (headless / serve mode)
+    }
+  }
+
+  const ask = async (sessionID: string, body: Record<string, unknown>): Promise<string> => {
+    const res = await client.session.prompt({ path: { id: sessionID }, body: body as never })
+    const data = ((res as { data?: unknown }).data ?? res) as { parts?: unknown }
+    return textOf(data.parts)
+  }
+
+  // Inspect the turn that just went idle. "interrupted" is true when its last
+  // assistant message has no error yet produced no visible output — the stream
+  // stopped cleanly without completing (a degenerate stop, e.g. a premature
+  // EOS). Errored or user-aborted turns are never "interrupted", so they are
+  // left stopped. "agent" is the agent that ran the turn, so a resume reuses
+  // it instead of falling back to the default agent.
+  const lastTurnState = async (sessionID: string): Promise<{ interrupted: boolean; agent?: string }> => {
+    try {
+      const res = await client.session.messages({ path: { id: sessionID } })
+      const list = ((res as { data?: unknown }).data ?? res) as Array<{
+        info?: { role?: string; agent?: string; error?: unknown }
+        parts?: unknown
+      }>
+      let agent: string | undefined
+      for (let i = list.length - 1; i >= 0; i--) {
+        const info = list[i]?.info
+        if (info?.role === "user") {
+          if (info.agent && info.agent !== reviewAgent) agent = info.agent
+          break
+        }
+      }
+      for (let i = list.length - 1; i >= 0; i--) {
+        const info = list[i]?.info
+        if (info?.role !== "assistant") continue
+        if (info.error) return { interrupted: false }
+        return { interrupted: textOf(list[i]?.parts).trim().length === 0, agent }
+      }
+      return { interrupted: false }
+    } catch (err) {
+      await log("warn", `failed to inspect last turn: ${err instanceof Error ? err.message : String(err)}`)
+      return { interrupted: false }
+    }
+  }
+
+  const runReviewCycle = async (sessionID: string, s: GateState): Promise<ReviewOutcome> => {
+    for (let round = 0; round <= maxFixRounds; round++) {
+      let verdict: "PASS" | "ISSUES" | undefined = undefined
+      for (let retry = 0; ; retry++) {
+        const review = await ask(sessionID, {
+          agent: reviewAgent,
+          parts: [
+            {
+              type: "text",
+              text: `${marker} Automated post-change review. Files were edited in this session earlier. Locate those changes (read the session transcript; run git diff / git status if this is a git repo; read the edited files) and review them per your protocol. End with your verdict line: "PASS — no blocking issues found" or "ISSUES — n blocking, m advisory". Note: keep this a static review — do NOT execute the code under review (no python/node/test runs); rely on git commands, reading files, and grep.`,
+            },
+          ],
+        })
+        verdict = lastVerdict(review)
+        if (verdict !== undefined || retry >= maxNoVerdictRetries) break
+        await log("warn", "review ended without a verdict line; retrying review", { sessionID })
+      }
+      await log("info", `review round ${round + 1} verdict: ${verdict ?? "NO_VERDICT"}`, { sessionID })
+      if (verdict === "PASS") return "pass"
+      if (verdict === undefined) return "no-verdict"
+      if (round === maxFixRounds) break
+      s.edited = false
+      await ask(sessionID, {
+        parts: [
+          {
+            type: "text",
+            text: `${marker} The automated review above found blocking issues. Fix every BUG-class finding now: edit the code, then run lint/tests where available. Do not launch another bug-review yourself — the gate will re-review your fixes automatically.`,
+          },
+        ],
+      })
+      if (!s.edited) {
+        // Distinguish a fix turn that died midstream (no output, no edits)
+        // from one that deliberately made no edits.
+        const turn = await lastTurnState(sessionID)
+        if (turn.interrupted) {
+          await log("warn", "fix turn ended with no model output; treating as interrupted", { sessionID })
+          return "fix-interrupted"
+        }
+        await log("info", "fix turn made no file edits; stopping gate", { sessionID })
+        return "no-fix-edits"
+      }
+    }
+    return "issues-remain"
+  }
+
+  const runGate = async (sessionID: string) => {
+    const s = get(sessionID)
+    s.busy = true
+    s.edited = false
+    try {
+      await log("info", "gate started", { sessionID })
+      for (let resume = 0; ; resume++) {
+        const { interrupted, agent } = autoContinue ? await lastTurnState(sessionID) : { interrupted: false, agent: undefined }
+        const outcome = await runReviewCycle(sessionID, s)
+        if (outcome === "issues-remain") {
+          await log("warn", `issues remain after ${maxFixRounds} fix rounds`, { sessionID })
+          await toast(`bug-review gate: ISSUES remain after ${maxFixRounds} fix rounds — needs attention`, "warning")
+          return
+        }
+        if (outcome === "no-fix-edits") return
+        const mustResume = autoContinue && (outcome === "fix-interrupted" || interrupted)
+        if (!mustResume || resume >= maxAutoContinues) {
+          if (outcome === "pass") {
+            await toast("bug-review gate: PASS", "success")
+          } else if (outcome === "no-verdict") {
+            await log("warn", "review ended without a verdict line; not auto-fixing", { sessionID })
+            await toast("bug-review gate: no verdict — see transcript", "warning")
+          } else {
+            await toast("bug-review gate: fix turn interrupted — needs attention", "warning")
+          }
+          if (mustResume) {
+            await log("warn", `turn ended with no model output; auto-continue cap (${maxAutoContinues}) reached`, { sessionID })
+          }
+          return
+        }
+        await log("info", `turn ended with no model output; auto-continuing (${resume + 1}/${maxAutoContinues})`, {
+          sessionID,
+        })
+        await toast("bug-review gate: resuming interrupted turn", "warning")
+        s.edited = false
+        const body: Record<string, unknown> = {
+          parts: [
+            {
+              type: "text",
+              text: `${marker} The previous turn ended abnormally — the model stream stopped before producing any output. Continue the task from where it stopped (re-read the transcript above to see what was in progress). Do not launch a bug-review yourself — the gate reviews changes automatically.`,
+            },
+          ],
+        }
+        // A fix-interrupted resume continues the fix turn, which ran under
+        // the default agent — not the main turn's agent.
+        if (agent && outcome !== "fix-interrupted") body.agent = agent
+        await ask(sessionID, body)
+      }
+    } catch (err) {
+      await log("error", `gate failed: ${err instanceof Error ? err.message : String(err)}`)
+    } finally {
+      s.busy = false
+      s.edited = false
+    }
+  }
+
+  const respondPermission = async (sessionID: string, permissionID: string) => {
+    try {
+      const res = await fetch(`${serverUrl}session/${sessionID}/permissions/${permissionID}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ response: askResponse }),
+      })
+      await log("info", `auto-answered permission ${permissionID} with ${askResponse} (status ${res.status})`, {
+        sessionID,
+      })
+    } catch (err) {
+      await log("warn", `failed to answer permission ${permissionID}: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
+  return {
+    config: async (input) => {
+      if (!defineAgent) return
+      if (input.agent?.[reviewAgent]) return
+      input.agent ??= {}
+      input.agent[reviewAgent] = {
+        description: DEFAULT_REVIEW_AGENT_DESCRIPTION,
+        mode: "subagent",
+        prompt: DEFAULT_REVIEW_AGENT_PROMPT,
+        permission: {
+          edit: "deny",
+          bash: {
+            "*": "ask",
+            "git diff*": "allow",
+            "git log*": "allow",
+            "git status*": "allow",
+            "git show*": "allow",
+          },
+        },
+      }
+    },
+
+    "permission.ask": async (input, output) => {
+      // While the gate is driving a session (review/fix/resume turns), answer
+      // permission asks automatically so headless runs can't hang on a
+      // dialog. The configured response keeps the turn alive. Normal user
+      // turns are unaffected.
+      const s = state.get(input.sessionID)
+      if (s?.busy) {
+        output.status = askResponse === "once" ? "allow" : "deny"
+        await log("info", `permission.ask hook answered ask with ${output.status}`, { sessionID: input.sessionID, id: input.id })
+      }
+    },
+
+    "tool.execute.after": async ({ tool, sessionID }) => {
+      if (EDIT_TOOLS.has(tool)) get(sessionID).edited = true
+    },
+
+    event: async ({ event }) => {
+      if (event.type === "session.deleted") {
+        const info = (event.properties as { info?: { id?: string } }).info
+        if (info?.id) state.delete(info.id)
+        return
+      }
+      if ((event.type as string) === "permission.asked" || event.type === "permission.updated") {
+        // Safety net for permission asks raised by gate-driven turns
+        // (review/fix/resume): watch the ask broadcast and answer it via the
+        // server API (the same channel a TUI client uses), so headless
+        // runs can't hang on a dialog. Normal user turns are unaffected
+        // (their sessions aren't gate-busy).
+        const p = event.properties as { id?: string; sessionID?: string }
+        const s = p.sessionID ? state.get(p.sessionID) : undefined
+        if (p.id && s?.busy && !answered.has(p.id)) {
+          answered.add(p.id)
+          await respondPermission(p.sessionID as string, p.id)
+        }
+        return
+      }
+      if (event.type !== "session.idle") return
+      const sessionID = (event.properties as { sessionID?: string }).sessionID
+      if (!sessionID) return
+      const s = get(sessionID)
+      if (!s.edited || s.busy) return
+      let session: { id?: string; parentID?: string }
+      try {
+        const res = await client.session.get({ path: { id: sessionID } })
+        session = ((res as { data?: unknown }).data ?? res) as { id?: string; parentID?: string }
+      } catch {
+        return
+      }
+      if (!session?.id || session.parentID) return
+      void runGate(sessionID)
+    },
+  }
+}
+
+export default BugReviewGate