@kealthas-dev/opencode-llm-review-gate 1.0.8 → 1.0.9

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 +110 -31
  2. package/package.json +5 -2
@@ -2,7 +2,8 @@ import { appendFile, mkdir } from "node:fs/promises";
2
2
  import { existsSync } from "node:fs";
3
3
  import { join } from "node:path";
4
4
  import { homedir } from "node:os";
5
- import type { Plugin } from "@opencode-ai/plugin";
5
+ import { z } from "zod";
6
+ import type { Plugin, ToolContext, ToolResult } from "@opencode-ai/plugin";
6
7
 
7
8
  // permission.ask exists in @opencode-ai/plugin's type definitions but is
8
9
  // never actually dispatched by opencode's runtime (verified against the
@@ -50,57 +51,135 @@ async function logReview(entry: Record<string, unknown>) {
50
51
  }
51
52
  }
52
53
 
54
+ // 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.
62
+ //
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.
71
+ const VERDICT_TOOL_NAME = "review_verdict";
72
+ const pendingVerdicts = new Map<string, { allow: boolean; reason?: string }>();
73
+
74
+ const reviewVerdictArgs = {
75
+ allow: z.boolean().describe("true to allow the command to run, false to block it"),
76
+ reason: z.string().optional().describe("required when allow is false: one short sentence explaining why"),
77
+ };
78
+
79
+ const reviewVerdictTool = {
80
+ description: "Record the ALLOW/BLOCK verdict for the command under review. Call this exactly once - it is the only tool available here.",
81
+ args: reviewVerdictArgs,
82
+ async execute(args: z.infer<z.ZodObject<typeof reviewVerdictArgs>>, context: ToolContext): Promise<ToolResult> {
83
+ pendingVerdicts.set(context.sessionID, args);
84
+ return args.allow ? "ALLOW recorded" : `BLOCK recorded: ${args.reason ?? "no reason given"}`;
85
+ },
86
+ };
87
+
53
88
  const REVIEW_SYSTEM_PROMPT = `You are a security gate reviewing a single shell command before it is allowed to run on the user's machine. You are NOT the assistant helping the user - you only judge this one command in isolation, with no other context.
54
89
 
55
90
  Block a command only if it is clearly destructive, irreversible, or likely to cause real harm without the user's informed consent: e.g. deleting or overwriting files/data outside an obvious scratch/temp area, force-pushing or rewriting git history, modifying system or security settings, exfiltrating secrets or credentials, downloading and running untrusted code, or anything clearly malicious.
56
91
 
57
92
  Do not block ordinary development work: reading files, listing directories, running builds/tests, git commits, installing declared dependencies, editing project files, etc. When in doubt, ALLOW - you are a safety net for genuinely dangerous commands, not a style reviewer.
58
93
 
59
- Do not call any tools. Reply with plain text only, in exactly this format and nothing else:
94
+ You MUST record your verdict by calling the "${VERDICT_TOOL_NAME}" tool exactly once - it is the only tool you have. Only if that tool is somehow unavailable, reply with plain text instead, in exactly this format and nothing else:
60
95
  ALLOW
61
96
  or
62
97
  BLOCK: <one short sentence explaining why>`;
63
98
 
64
99
  export const LlmReviewGate: Plugin = async ({ client }) => {
65
- let reviewSessionID: string | undefined;
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.
66
113
  const reviewSessionIDs = new Set<string>();
67
114
 
68
- async function ensureReviewSession() {
69
- if (reviewSessionID) return reviewSessionID;
70
- const res = await client.session.create({
115
+ async function review(command: string) {
116
+ const created = await client.session.create({
71
117
  body: { title: "llm-review-gate (internal, safe to delete)" },
72
118
  throwOnError: true,
73
119
  });
74
- reviewSessionID = res.data.id;
75
- reviewSessionIDs.add(reviewSessionID);
76
- return reviewSessionID;
77
- }
120
+ const sessionID = created.data.id;
121
+ reviewSessionIDs.add(sessionID); // never review this session's own tool calls (no self-recursion)
122
+ try {
123
+ const res = await client.session.prompt({
124
+ path: { id: sessionID },
125
+ 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.
140
+ agent: "review-gate",
141
+ system: REVIEW_SYSTEM_PROMPT,
142
+ parts: [{ type: "text", text: `Command:\n${command}` }],
143
+ },
144
+ throwOnError: true,
145
+ });
78
146
 
79
- async function review(command: string) {
80
- const sessionID = await ensureReviewSession();
81
- const res = await client.session.prompt({
82
- path: { id: sessionID },
83
- body: {
84
- system: REVIEW_SYSTEM_PROMPT,
85
- parts: [{ type: "text", text: `Command:\n${command}` }],
86
- },
87
- throwOnError: true,
88
- });
89
- const text = (res.data.parts ?? [])
90
- .filter((p) => p.type === "text")
91
- .map((p) => p.text)
92
- .join("\n")
93
- .trim();
94
- const firstLine = text.split("\n")[0]?.trim() ?? "";
95
- if (/^ALLOW/i.test(firstLine)) return { verdict: "allow", raw: text };
96
- if (/^BLOCK/i.test(firstLine)) {
97
- const reason = firstLine.replace(/^BLOCK:?\s*/i, "") || "blocked by LLM review";
98
- return { verdict: "block", reason, raw: text };
147
+ // Prefer the tool call - it's a real structured verdict instead of a
148
+ // regex guess against free text. Only fall back to text parsing if
149
+ // the model didn't call the tool (ignored the instruction, or this
150
+ // deployment's tool-call parser doesn't cooperate for some reason).
151
+ const verdictArgs = pendingVerdicts.get(sessionID);
152
+ if (verdictArgs) {
153
+ return verdictArgs.allow
154
+ ? { verdict: "allow" as const, raw: `[tool call] allow=true` }
155
+ : { verdict: "block" as const, reason: verdictArgs.reason || "blocked by LLM review", raw: `[tool call] allow=false reason=${verdictArgs.reason ?? ""}` };
156
+ }
157
+
158
+ const text = (res.data.parts ?? [])
159
+ .filter((p) => p.type === "text")
160
+ .map((p) => p.text)
161
+ .join("\n")
162
+ .trim();
163
+ const firstLine = text.split("\n")[0]?.trim() ?? "";
164
+ if (/^ALLOW/i.test(firstLine)) return { verdict: "allow" as const, raw: text };
165
+ if (/^BLOCK/i.test(firstLine)) {
166
+ const reason = firstLine.replace(/^BLOCK:?\s*/i, "") || "blocked by LLM review";
167
+ return { verdict: "block" as const, reason, raw: text };
168
+ }
169
+ return { verdict: "unclear" as const, raw: text };
170
+ } finally {
171
+ pendingVerdicts.delete(sessionID);
172
+ reviewSessionIDs.delete(sessionID);
173
+ await client.session.delete({ path: { id: sessionID } }).catch(() => {
174
+ // best-effort cleanup; a leaked internal session is harmless clutter, not a correctness problem
175
+ });
99
176
  }
100
- return { verdict: "unclear", raw: text };
101
177
  }
102
178
 
103
179
  return {
180
+ tool: {
181
+ [VERDICT_TOOL_NAME]: reviewVerdictTool,
182
+ },
104
183
  "tool.execute.before": async (input, output) => {
105
184
  if (!GATED_TOOLS.has(input.tool)) return;
106
185
  if (reviewSessionIDs.has(input.sessionID)) return; // never review the review session's own calls
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@kealthas-dev/opencode-llm-review-gate",
3
- "version": "1.0.8",
3
+ "version": "1.0.9",
4
4
  "type": "module",
5
- "description": "llm-review-gate.ts opencode plugin (gates bash tool calls behind an LLM safety review before they run), 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. Independently installable from hook-logger.ts - not bundled together.",
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",
7
7
  "files": [
8
8
  "llm-review-gate.ts"
@@ -15,6 +15,9 @@
15
15
  "url": "https://github.com/Keal-thas/opencode-toolkit.git",
16
16
  "directory": "plugins/llm-review-gate"
17
17
  },
18
+ "dependencies": {
19
+ "zod": "^4.1.8"
20
+ },
18
21
  "devDependencies": {
19
22
  "@opencode-ai/plugin": "^1.0.0",
20
23
  "@types/node": "^22.0.0"