@kealthas-dev/opencode-llm-review-gate 1.0.8 → 1.0.10
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.
- package/llm-review-gate.ts +110 -31
- package/package.json +5 -2
package/llm-review-gate.ts
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
69
|
-
|
|
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
|
-
|
|
75
|
-
reviewSessionIDs.add(
|
|
76
|
-
|
|
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
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
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.
|
|
3
|
+
"version": "1.0.10",
|
|
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"
|