@kealthas-dev/opencode-llm-review-gate 1.0.12 → 1.0.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/llm-review-gate.ts +36 -61
  2. package/package.json +1 -1
@@ -5,30 +5,23 @@ import { homedir } from "node:os";
5
5
  import { z } from "zod";
6
6
  import type { Plugin, ToolContext, ToolResult } from "@opencode-ai/plugin";
7
7
 
8
- // permission.ask exists in @opencode-ai/plugin's type definitions but is
9
- // never actually dispatched by opencode's runtime (verified against the
10
- // real dev-branch source, not just the docs/types) - so it cannot be used
11
- // to intercept allow/ask/deny decisions. tool.execute.before is the real,
12
- // working interception point: it fires unconditionally before the tool's
13
- // own permission check runs, and throwing inside it blocks the call
14
- // outright (same mechanism the official .env-protection example plugin
15
- // uses). That gives us the layering the user asked for:
16
- // - config says "allow" -> review still runs first; only a clean
17
- // "allow" verdict lets it fall through to the real auto-run.
18
- // - config says "ask" -> review runs before the human is ever
19
- // prompted; a "block" verdict short-circuits before that prompt.
20
- // - config says "deny" -> review still runs (and gets logged) even
21
- // though the config's own deny wins either way - we can only ever
22
- // ADD a block here, never remove one the config would apply later.
8
+ // permission.ask exists in the plugin types but is never dispatched by
9
+ // opencode's runtime (verified against dev-branch source) - so tool.execute.before
10
+ // is the real interception point instead: it fires before the tool's own
11
+ // permission check, and throwing blocks the call outright (same mechanism the
12
+ // official .env-protection example uses). This layers under the config:
13
+ // - allow -> review runs first; only a clean verdict lets it through.
14
+ // - ask -> review runs before the human is prompted; block short-circuits it.
15
+ // - deny -> review still runs and logs, but can only ADD a block, never
16
+ // remove the config's own deny.
23
17
 
24
18
  // Tool names that get an LLM safety review before they're allowed to run.
25
19
  // Extend this to gate more tools (e.g. "edit", "webfetch").
26
20
  const GATED_TOOLS = new Set(["bash"]);
27
21
 
28
- // If the review call itself fails (model server down, network error,
29
- // timeout) this decides what happens: true = let the command through
30
- // (an availability failure isn't a security verdict, and fail-closed
31
- // here would brick every bash call including the ones needed to debug
22
+ // If the review call fails (server down, network error, timeout): true lets
23
+ // the command through (an availability failure isn't a security verdict, and
24
+ // fail-closed would brick every bash call including the ones needed to debug
32
25
  // why review is down). Flip to false for stricter fail-closed behavior.
33
26
  const FAIL_OPEN_ON_ERROR = true;
34
27
 
@@ -52,22 +45,17 @@ async function logReview(entry: Record<string, unknown>) {
52
45
  }
53
46
 
54
47
  // Custom tool the review-gate agent uses to record its verdict as a real
55
- // function call, verified enabled on this deployment's model (see
56
- // deploy/opencode.json.example's "review_verdict" permission: denied
57
- // globally, allowed only for the "review-gate" agent - a plugin-registered
58
- // tool is otherwise available to every agent by name, same as a built-in
59
- // one, per docs/opencode-docs-reference/custom-tools.mdx). Keyed by review
60
- // session ID so concurrent reviews (multiple gated tool calls in flight at
61
- // once, each with its own one-shot session) never clobber each other.
48
+ // function call (confirmed enabled on this deployment's model - see
49
+ // deploy/opencode.json.example's "review_verdict" permission, denied globally
50
+ // and re-allowed only for "review-gate"). Keyed by session ID so concurrent
51
+ // reviews never clobber each other.
62
52
  //
63
- // Built as a plain object (the documented alternative to @opencode-ai/plugin's
64
- // `tool()` helper - see docs/opencode-docs-reference/custom-tools.mdx's
65
- // "Arguments" section) rather than calling `tool()` itself, because every
66
- // other plugin in this repo only ever imports @opencode-ai/plugin's *types*
67
- // (erased at build time, zero runtime footprint) - `tool()` is a real
68
- // runtime value, and pulling it in would make this the one plugin that
69
- // actually needs @opencode-ai/plugin installed to run. `zod` alone (already
70
- // a real dependency below, needed for the args schema regardless) avoids that.
53
+ // Built as a plain object rather than @opencode-ai/plugin's `tool()` helper
54
+ // (the documented alternative - see custom-tools.mdx's "Arguments" section):
55
+ // every other plugin here only imports @opencode-ai/plugin's types (erased at
56
+ // build time), and `tool()` is a real runtime value that would make this the
57
+ // one plugin actually needing the package installed. `zod` alone (already
58
+ // needed for the schema) avoids that.
71
59
  const VERDICT_TOOL_NAME = "review_verdict";
72
60
  const pendingVerdicts = new Map<string, { allow: boolean; reason?: string }>();
73
61
 
@@ -97,19 +85,13 @@ or
97
85
  BLOCK: <one short sentence explaining why>`;
98
86
 
99
87
  export const LlmReviewGate: Plugin = async ({ client }) => {
100
- // A session is opencode's only unit of model invocation (there's no
101
- // stateless "just complete this text" endpoint) - but it's also a
102
- // stateful conversation: every session.prompt() call appends to that
103
- // session's own message history, which then gets replayed as context on
104
- // every later call to the same session. A single long-lived review
105
- // session (the previous design) would grow that history by one
106
- // command+verdict turn per gated tool call for as long as the plugin
107
- // instance lives, quietly inflating token cost per review and eventually
108
- // contradicting REVIEW_SYSTEM_PROMPT's own "judge this one command in
109
- // isolation, with no other context" framing. So instead: one throwaway
110
- // session per review, deleted right after - session.create/delete are
111
- // cheap metadata calls, not model calls, so this doesn't add a second
112
- // LLM round trip, only a bit of bookkeeping.
88
+ // A session is opencode's only unit of model invocation, and it's stateful:
89
+ // every prompt() call appends to that session's history, replayed as context
90
+ // on the next call. A single long-lived review session (the earlier design)
91
+ // would grow that history every gated call, inflating cost and contradicting
92
+ // REVIEW_SYSTEM_PROMPT's "judge this command in isolation" framing. So:
93
+ // one throwaway session per review, deleted right after - create/delete are
94
+ // cheap metadata calls, not model calls, so no second LLM round trip.
113
95
  const reviewSessionIDs = new Set<string>();
114
96
 
115
97
  async function review(command: string) {
@@ -123,20 +105,13 @@ export const LlmReviewGate: Plugin = async ({ client }) => {
123
105
  const res = await client.session.prompt({
124
106
  path: { id: sessionID },
125
107
  body: {
126
- // Verified against opencode dev-branch source
127
- // (packages/opencode/src/session/llm/request.ts): the request's
128
- // `system` field does NOT replace an agent's configured `prompt` -
129
- // it's appended after it. Without an explicit `agent` here this
130
- // session would inherit whichever primary agent (build/plan/general)
131
- // is default, and in this deployment that means the full
132
- // system-prompt.txt persona ("you are opencode, a CLI coding
133
- // agent...") would run *ahead of* REVIEW_SYSTEM_PROMPT, competing
134
- // with the review instructions. "review-gate" (see
135
- // deploy/opencode.json.example) has no `prompt` override - so it
136
- // falls back to opencode's generic per-model default instead - and
137
- // denies every tool permission except `review_verdict`, so the
138
- // model's only real option is to call that tool rather than reach
139
- // for bash/edit/etc.
108
+ // Verified against opencode dev-branch source (session/llm/request.ts):
109
+ // `system` is appended after an agent's configured `prompt`, not a
110
+ // replacement. Without an explicit `agent` here, this session would
111
+ // inherit the default primary agent and run system-prompt.txt's full
112
+ // persona ahead of REVIEW_SYSTEM_PROMPT, competing for attention.
113
+ // "review-gate" has no `prompt` override and denies every tool except
114
+ // `review_verdict`, so calling that tool is the model's only option.
140
115
  agent: "review-gate",
141
116
  system: REVIEW_SYSTEM_PROMPT,
142
117
  parts: [{ type: "text", text: `Command:\n${command}` }],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kealthas-dev/opencode-llm-review-gate",
3
- "version": "1.0.12",
3
+ "version": "1.0.14",
4
4
  "type": "module",
5
5
  "description": "llm-review-gate.ts opencode plugin (gates bash tool calls behind an LLM safety review before they run, via a real review_verdict function-call tool with a text-parsing fallback), published to npm so opencode's own npm-plugin loader can install it directly from a bare package name in opencode.json's plugin array - see CLAUDE.md. Written in TypeScript against @opencode-ai/plugin's Plugin type (type-only) plus a real `zod` runtime dependency for the tool's argument schema - the one plugin in this repo with an actual runtime dependency, unlike hook-logger.ts/system-prompt-tools.ts's zero-dependency design. Independently installable from hook-logger.ts - not bundled together.",
6
6
  "main": "llm-review-gate.ts",