@kealthas-dev/opencode-llm-review-gate 1.0.0

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 +149 -0
  2. package/package.json +20 -0
@@ -0,0 +1,149 @@
1
+ import { appendFile, mkdir } from "node:fs/promises";
2
+ import { existsSync } from "node:fs";
3
+ import { join } from "node:path";
4
+ import { homedir } from "node:os";
5
+ import type { Plugin } from "@opencode-ai/plugin";
6
+
7
+ // permission.ask exists in @opencode-ai/plugin's type definitions but is
8
+ // never actually dispatched by opencode's runtime (verified against the
9
+ // real dev-branch source, not just the docs/types) - so it cannot be used
10
+ // to intercept allow/ask/deny decisions. tool.execute.before is the real,
11
+ // working interception point: it fires unconditionally before the tool's
12
+ // own permission check runs, and throwing inside it blocks the call
13
+ // outright (same mechanism the official .env-protection example plugin
14
+ // uses). That gives us the layering the user asked for:
15
+ // - config says "allow" -> review still runs first; only a clean
16
+ // "allow" verdict lets it fall through to the real auto-run.
17
+ // - config says "ask" -> review runs before the human is ever
18
+ // prompted; a "block" verdict short-circuits before that prompt.
19
+ // - config says "deny" -> review still runs (and gets logged) even
20
+ // though the config's own deny wins either way - we can only ever
21
+ // ADD a block here, never remove one the config would apply later.
22
+
23
+ // Tool names that get an LLM safety review before they're allowed to run.
24
+ // Extend this to gate more tools (e.g. "edit", "webfetch").
25
+ const GATED_TOOLS = new Set(["bash"]);
26
+
27
+ // If the review call itself fails (model server down, network error,
28
+ // timeout) this decides what happens: true = let the command through
29
+ // (an availability failure isn't a security verdict, and fail-closed
30
+ // here would brick every bash call including the ones needed to debug
31
+ // why review is down). Flip to false for stricter fail-closed behavior.
32
+ const FAIL_OPEN_ON_ERROR = true;
33
+
34
+ const REVIEW_TIMEOUT_MS = 30_000;
35
+
36
+ const outDir = join(homedir(), "opencode-hook-output");
37
+
38
+ function errorMessage(e: unknown): string {
39
+ return e instanceof Error ? e.message : String(e);
40
+ }
41
+
42
+ async function logReview(entry: Record<string, unknown>) {
43
+ const file = join(outDir, "llm-review.jsonl");
44
+ const line = JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n";
45
+ try {
46
+ if (!existsSync(outDir)) await mkdir(outDir, { recursive: true });
47
+ await appendFile(file, line);
48
+ } catch (e) {
49
+ // logging must never be the reason the gate itself breaks
50
+ }
51
+ }
52
+
53
+ 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
+
55
+ 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
+
57
+ 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
+
59
+ Do not call any tools. Reply with plain text only, in exactly this format and nothing else:
60
+ ALLOW
61
+ or
62
+ BLOCK: <one short sentence explaining why>`;
63
+
64
+ export const LlmReviewGate: Plugin = async ({ client }) => {
65
+ let reviewSessionID: string | undefined;
66
+ const reviewSessionIDs = new Set<string>();
67
+
68
+ async function ensureReviewSession() {
69
+ if (reviewSessionID) return reviewSessionID;
70
+ const res = await client.session.create({
71
+ body: { title: "llm-review-gate (internal, safe to delete)" },
72
+ throwOnError: true,
73
+ });
74
+ reviewSessionID = res.data.id;
75
+ reviewSessionIDs.add(reviewSessionID);
76
+ return reviewSessionID;
77
+ }
78
+
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 };
99
+ }
100
+ return { verdict: "unclear", raw: text };
101
+ }
102
+
103
+ return {
104
+ "tool.execute.before": async (input, output) => {
105
+ if (!GATED_TOOLS.has(input.tool)) return;
106
+ if (reviewSessionIDs.has(input.sessionID)) return; // never review the review session's own calls
107
+
108
+ const command = input.tool === "bash" ? output.args?.command : JSON.stringify(output.args);
109
+
110
+ let result;
111
+ try {
112
+ result = await Promise.race([
113
+ review(command),
114
+ new Promise<never>((_, reject) => setTimeout(() => reject(new Error("review timed out")), REVIEW_TIMEOUT_MS)),
115
+ ]);
116
+ } catch (e) {
117
+ const decision = FAIL_OPEN_ON_ERROR ? "allow (fail-open)" : "block (fail-closed)";
118
+ await logReview({
119
+ tool: input.tool,
120
+ sessionID: input.sessionID,
121
+ callID: input.callID,
122
+ command,
123
+ error: errorMessage(e),
124
+ decision,
125
+ });
126
+ if (FAIL_OPEN_ON_ERROR) return;
127
+ throw new Error(`llm-review-gate: review unavailable, blocking (fail-closed): ${errorMessage(e)}`);
128
+ }
129
+
130
+ await logReview({
131
+ tool: input.tool,
132
+ sessionID: input.sessionID,
133
+ callID: input.callID,
134
+ command,
135
+ verdict: result.verdict,
136
+ raw: result.raw,
137
+ });
138
+
139
+ if (result.verdict === "block") {
140
+ throw new Error(`Blocked by LLM review: ${result.reason}`);
141
+ }
142
+ if (result.verdict === "unclear" && !FAIL_OPEN_ON_ERROR) {
143
+ throw new Error(`llm-review-gate: could not parse review verdict, blocking (fail-closed). Raw: ${result.raw.slice(0, 200)}`);
144
+ }
145
+ // "allow", or "unclear" while fail-open: fall through to whatever
146
+ // the config's own allow/ask/deny tier would normally do.
147
+ },
148
+ };
149
+ };
package/package.json ADDED
@@ -0,0 +1,20 @@
1
+ {
2
+ "name": "@kealthas-dev/opencode-llm-review-gate",
3
+ "version": "1.0.0",
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.",
6
+ "main": "llm-review-gate.ts",
7
+ "files": ["llm-review-gate.ts"],
8
+ "publishConfig": {
9
+ "access": "public"
10
+ },
11
+ "repository": {
12
+ "type": "git",
13
+ "url": "https://github.com/Keal-thas/opencode-toolkit.git",
14
+ "directory": "plugins/llm-review-gate"
15
+ },
16
+ "devDependencies": {
17
+ "@opencode-ai/plugin": "^1.0.0",
18
+ "@types/node": "^22.0.0"
19
+ }
20
+ }