openguardrails-instrumentation-opencode 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# openguardrails-instrumentation-opencode
+
+Guard an [opencode](https://github.com/anomalyco/opencode) agent's tool calls
+through the [OpenGuardrails (OGR)](https://www.npmjs.com/package/@openguardrails/core)
+protocol — the TS counterpart of `openguardrails-instrumentation-hermes`.
+
+The agent configures **its own guardrails**: plain **text + regex** rules (no
+model required), and optionally **its own model** as an LLM judge. Enforced as a
+pure opencode plugin — **no core changes, no fork**.
+
+```bash
+npm install openguardrails-instrumentation-opencode
+```
+
+## How it works
+
+opencode fires `tool.execute.before` for every tool, before it runs. This plugin
+turns the call into an OGR `GuardEvent`, runs it through a `Runtime` built from
+your policy, and enforces the `Verdict`:
+
+| OGR decision | opencode behavior |
+| --- | --- |
+| `allow` / `modify` / `redact` | proceed |
+| `block` | throw → the agent sees a tool error and must find a safer path |
+| `require_approval` | throw → asks you to re-run intentionally or relax the policy |
+
+It is a **restrict-only** guard: it can stop a would-run tool call, never loosen
+one. (opencode's own `permission` rules still apply first.)
+
+## Enable
+
+In your opencode config:
+
+```jsonc
+{
+  "plugin": ["openguardrails-instrumentation-opencode"]
+}
+```
+
+## Configure your guardrails
+
+Drop an OGR policy at **`.opencode/guardrails.json`** (the agent can write/edit
+this itself), or pass it inline as plugin options. A sensible default ships in
+the package (`curl|bash`, `rm -rf /`, credential-file access, `| sudo`).
+
+```json
+{
+  "composition": { "security.*": { "strategy": "deny-wins", "on_all_failed": "block" } },
+  "config_rules": {
+    "command_rules": [
+      { "id": "no-prod-deploy", "regex": "deploy\\s+--env\\s+prod",
+        "category": "security.malicious_command", "decision": "require_approval",
+        "score": 0.9, "why": "production deploys need explicit human approval" }
+    ]
+  }
+}
+```
+
+### Use your own model as the judge
+
+```json
+{
+  "config_rules": { "command_rules": [] },
+  "judge": { "baseURL": "https://api.openai.com/v1", "model": "gpt-4o-mini", "apiKey": "sk-..." }
+}
+```
+
+Any OpenAI-compatible chat endpoint works — point it at the same model your agent
+uses, or a dedicated guard model. The judge weighs provenance and returns an OGR
+verdict; the deterministic text/regex rules remain the baseline.
+
+## Status
+
+`v0.1`. Pure plugin via `tool.execute.before`. A first-class "ask the human"
+(`require_approval` as an interactive prompt) and transcript-based provenance
+tainting are tracked follow-ups; today `require_approval` is enforced as a
+deny-with-guidance.

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+import type { Policy } from "@openguardrails/core";
+/** "Use your own model as the guardrail" — any OpenAI-compatible chat endpoint. */
+export interface JudgeConfig {
+    baseURL: string;
+    model: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+}
+export interface GuardrailsOptions {
+    /** Inline OGR policy (overrides the file + default). */
+    policy?: Policy;
+    /** Path to a guardrails policy file (defaults to .opencode/guardrails.json). */
+    policyPath?: string;
+    /** Enable the LLM-judge detector backed by your own model. */
+    judge?: JudgeConfig;
+}
+/** Default text/regex guardrails — deterministic, no model required. */
+export declare const DEFAULT_POLICY: Policy;
+export interface ResolvedConfig {
+    policy: Policy;
+    judge?: JudgeConfig;
+}
+export declare function loadGuardrailsConfig(directory: string, options?: GuardrailsOptions): ResolvedConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAElD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,WAAW,CAAA;CACpB;AAED,wEAAwE;AACxE,eAAO,MAAM,cAAc,EAAE,MA0C5B,CAAA;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,WAAW,CAAA;CACpB;AAED,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,cAAc,CAenG"}

package/dist/config.js

@@ -0,0 +1,77 @@
+/**
+ * Guardrails configuration for the opencode integration.
+ *
+ * The agent configures its OWN guardrails — text + regex rules (no model
+ * needed), and optionally its own model as an LLM judge. Config resolution:
+ *
+ *   1. a sensible default policy (below)
+ *   2. `.opencode/guardrails.json` in the project (agent-editable — this is how
+ *      an agent gives itself guardrails)
+ *   3. plugin `options` passed in opencode config (highest precedence)
+ *
+ * The policy IS an OGR policy.json (composition + config_rules), so the same
+ * file format works across every OGR integration.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+/** Default text/regex guardrails — deterministic, no model required. */
+export const DEFAULT_POLICY = {
+    composition: {
+        "security.*": { strategy: "deny-wins", on_all_failed: "block" },
+        default: { strategy: "deny-wins" },
+    },
+    config_rules: {
+        secret_env_markers: ["SECRET", "TOKEN", "KEY", "PASSWORD", "AWS_", "PRIVATE", "CREDENTIAL"],
+        command_rules: [
+            {
+                id: "pipe-to-shell",
+                regex: "(curl|wget)\\b.*\\|\\s*(ba)?sh",
+                category: "security.malicious_command",
+                decision: "require_approval",
+                score: 0.85,
+                why: "remote script fetched and piped directly into a shell",
+            },
+            {
+                id: "rm-rf-root",
+                regex: "rm\\s+-rf\\s+/(\\s|$)",
+                category: "security.malicious_command",
+                decision: "block",
+                score: 1.0,
+                why: "destructive recursive delete of the filesystem root",
+            },
+            {
+                id: "secret-file-access",
+                regex: "(\\.env\\b|/\\.aws/credentials|/\\.ssh/id_|/\\.ssh/|auth\\.json|\\.netrc)",
+                category: "security.secret_leak",
+                decision: "block",
+                score: 0.9,
+                why: "command references a credential file — independent of the reader",
+            },
+            {
+                id: "pipe-to-sudo",
+                regex: "\\|\\s*sudo\\b",
+                category: "security.privilege_escalation",
+                decision: "require_approval",
+                score: 0.7,
+                why: "output piped into sudo",
+            },
+        ],
+    },
+};
+export function loadGuardrailsConfig(directory, options) {
+    let policy = DEFAULT_POLICY;
+    const path = options?.policyPath ?? join(directory, ".opencode", "guardrails.json");
+    if (existsSync(path)) {
+        try {
+            policy = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            // malformed file → keep the safe default rather than failing open silently
+        }
+    }
+    if (options?.policy)
+        policy = options.policy;
+    const judge = options?.judge ?? policy["judge"];
+    return { policy, judge };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAoBhC,wEAAwE;AACxE,MAAM,CAAC,MAAM,cAAc,GAAW;IACpC,WAAW,EAAE;QACX,YAAY,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE;QAC/D,OAAO,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE;KACnC;IACD,YAAY,EAAE;QACZ,kBAAkB,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,CAAC;QAC3F,aAAa,EAAE;YACb;gBACE,EAAE,EAAE,eAAe;gBACnB,KAAK,EAAE,gCAAgC;gBACvC,QAAQ,EAAE,4BAA4B;gBACtC,QAAQ,EAAE,kBAAkB;gBAC5B,KAAK,EAAE,IAAI;gBACX,GAAG,EAAE,uDAAuD;aAC7D;YACD;gBACE,EAAE,EAAE,YAAY;gBAChB,KAAK,EAAE,uBAAuB;gBAC9B,QAAQ,EAAE,4BAA4B;gBACtC,QAAQ,EAAE,OAAO;gBACjB,KAAK,EAAE,GAAG;gBACV,GAAG,EAAE,qDAAqD;aAC3D;YACD;gBACE,EAAE,EAAE,oBAAoB;gBACxB,KAAK,EAAE,2EAA2E;gBAClF,QAAQ,EAAE,sBAAsB;gBAChC,QAAQ,EAAE,OAAO;gBACjB,KAAK,EAAE,GAAG;gBACV,GAAG,EAAE,kEAAkE;aACxE;YACD;gBACE,EAAE,EAAE,cAAc;gBAClB,KAAK,EAAE,gBAAgB;gBACvB,QAAQ,EAAE,+BAA+B;gBACzC,QAAQ,EAAE,kBAAkB;gBAC5B,KAAK,EAAE,GAAG;gBACV,GAAG,EAAE,wBAAwB;aAC9B;SACF;KACF;CACF,CAAA;AAOD,MAAM,UAAU,oBAAoB,CAAC,SAAiB,EAAE,OAA2B;IACjF,IAAI,MAAM,GAAW,cAAc,CAAA;IAEnC,MAAM,IAAI,GAAG,OAAO,EAAE,UAAU,IAAI,IAAI,CAAC,SAAS,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAA;IACnF,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAW,CAAA;QAC3D,CAAC;QAAC,MAAM,CAAC;YACP,2EAA2E;QAC7E,CAAC;IACH,CAAC;IACD,IAAI,OAAO,EAAE,MAAM;QAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;IAE5C,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAK,MAAM,CAAC,OAAO,CAA6B,CAAA;IAC5E,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;AAC1B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * openguardrails-instrumentation-opencode
+ *
+ * An opencode plugin that guards an agent's tool calls through the OpenGuardrails
+ * (OGR) protocol — the TS counterpart of `openguardrails-instrumentation-hermes`.
+ *
+ * It hooks `tool.execute.before` (fired for every tool, before it runs), turns
+ * the call into an OGR `GuardEvent`, runs it through a `Runtime` built from the
+ * agent's own guardrails policy (text/regex rules, plus optionally its own model
+ * as an LLM judge), and enforces the `Verdict`:
+ *
+ *   allow | modify | redact → proceed
+ *   block | require_approval → throw (deny-and-continue: the agent sees a tool
+ *                              error and must find a safer path or get approval)
+ *
+ * No opencode core changes required. This is a "restrict-only" guard: it can stop
+ * a would-run tool call, never loosen one.
+ */
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const OpenGuardrailsPlugin: Plugin;
+export default OpenGuardrailsPlugin;
+export { DEFAULT_POLICY, type GuardrailsOptions, type JudgeConfig } from "./config.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAS,MAAM,qBAAqB,CAAA;AAyBxD,eAAO,MAAM,oBAAoB,EAAE,MAuClC,CAAA;AAED,eAAe,oBAAoB,CAAA;AACnC,OAAO,EAAE,cAAc,EAAE,KAAK,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,51 @@
+import { Runtime, ConfigRulesDetector, LLMJudgeDetector, } from "@openguardrails/core";
+import { loadGuardrailsConfig } from "./config.js";
+import { openAICompatibleBackend } from "./own-model.js";
+let seq = 0;
+function id(prefix) {
+    seq += 1;
+    const rand = globalThis.crypto?.randomUUID?.().slice(0, 8) ?? Math.random().toString(36).slice(2, 10);
+    return `${prefix}-${seq.toString(36)}-${rand}`;
+}
+function brief(v) {
+    const cats = v.categories.map((c) => `${c.id}(${c.score})`).join(", ");
+    const why = v.reasons.filter((r) => !r.startsWith("[")).join("; ");
+    return [cats, why].filter(Boolean).join(" — ") || v.decision;
+}
+export const OpenGuardrailsPlugin = async ({ directory }, options) => {
+    const { policy, judge } = loadGuardrailsConfig(directory, options);
+    const detectors = [new ConfigRulesDetector(policy.config_rules ?? {})];
+    if (judge)
+        detectors.push(new LLMJudgeDetector(openAICompatibleBackend(judge)));
+    const runtime = new Runtime(detectors, policy);
+    const hooks = {
+        "tool.execute.before": async (input, output) => {
+            const ev = {
+                kind: "tool_call",
+                observationPoint: "agent_hook",
+                subject: { agent_id: "opencode", agent_type: "opencode", session_id: input.sessionID },
+                payload: { name: input.tool, arguments: output.args },
+                eventId: id("evt"),
+                guardId: id("ga"),
+                timestamp: new Date().toISOString(),
+                sessionId: input.sessionID,
+                // v0.1: principal is trusted. Transcript-based tainting (web/mcp results
+                // → untrusted provenance) is a follow-up via the opencode session API.
+                provenance: [{ source: "user", trust: "trusted" }],
+            };
+            const verdict = await runtime.evaluate(ev);
+            if (verdict.decision === "block") {
+                throw new Error(`[OpenGuardrails] blocked this ${input.tool} call: ${brief(verdict)}`);
+            }
+            if (verdict.decision === "require_approval") {
+                throw new Error(`[OpenGuardrails] this ${input.tool} call needs your explicit approval: ${brief(verdict)}. ` +
+                    `Re-run only if you intend this, or relax .opencode/guardrails.json.`);
+            }
+            // allow | modify | redact → proceed
+        },
+    };
+    return hooks;
+};
+export default OpenGuardrailsPlugin;
+export { DEFAULT_POLICY } from "./config.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/own-model.d.ts

@@ -0,0 +1,9 @@
+/**
+ * "Use your own model as the guardrail" — an OGR LLMBackend that calls any
+ * OpenAI-compatible chat-completions endpoint. Point it at the same model the
+ * agent already uses, a cheaper sibling, or a dedicated guard model.
+ */
+import type { LLMBackend } from "@openguardrails/core";
+import type { JudgeConfig } from "./config.js";
+export declare function openAICompatibleBackend(cfg: JudgeConfig): LLMBackend;
+//# sourceMappingURL=own-model.d.ts.map

package/dist/own-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"own-model.d.ts","sourceRoot":"","sources":["../src/own-model.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,WAAW,GAAG,UAAU,CA4BpE"}

package/dist/own-model.js

@@ -0,0 +1,31 @@
+export function openAICompatibleBackend(cfg) {
+    const url = cfg.baseURL.replace(/\/+$/, "") + "/chat/completions";
+    return {
+        name: `own-model:${cfg.model}`,
+        async complete(system, user) {
+            const res = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    ...(cfg.apiKey ? { authorization: `Bearer ${cfg.apiKey}` } : {}),
+                    ...(cfg.headers ?? {}),
+                },
+                body: JSON.stringify({
+                    model: cfg.model,
+                    temperature: 0,
+                    messages: [
+                        { role: "system", content: system },
+                        { role: "user", content: user },
+                    ],
+                }),
+            });
+            if (!res.ok)
+                throw new Error(`guard model returned ${res.status}`);
+            const data = (await res.json());
+            const text = data.choices?.[0]?.message?.content ?? "";
+            // Strip a ```json fence if the model wrapped its reply.
+            return text.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "").trim();
+        },
+    };
+}
+//# sourceMappingURL=own-model.js.map

package/dist/own-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"own-model.js","sourceRoot":"","sources":["../src/own-model.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,uBAAuB,CAAC,GAAgB;IACtD,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,mBAAmB,CAAA;IACjE,OAAO;QACL,IAAI,EAAE,aAAa,GAAG,CAAC,KAAK,EAAE;QAC9B,KAAK,CAAC,QAAQ,CAAC,MAAc,EAAE,IAAY;YACzC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAC3B,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAChE,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;iBACvB;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,KAAK,EAAE,GAAG,CAAC,KAAK;oBAChB,WAAW,EAAE,CAAC;oBACd,QAAQ,EAAE;wBACR,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE;wBACnC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE;qBAChC;iBACF,CAAC;aACH,CAAC,CAAA;YACF,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAA;YAClE,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA4D,CAAA;YAC1F,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,CAAA;YACtD,wDAAwD;YACxD,OAAO,IAAI,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;QAC7E,CAAC;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "openguardrails-instrumentation-opencode",
+  "version": "0.1.0",
+  "description": "Guard an opencode agent's tool calls through the OpenGuardrails (OGR) protocol — agent-configurable text/regex guardrails, or use your own model as the judge. No core changes.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "OpenGuardrails",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean"
+  },
+  "keywords": ["opencode", "plugin", "ai", "agent", "security", "guardrails", "ogr", "openguardrails"],
+  "dependencies": {
+    "@openguardrails/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "latest",
+    "@types/node": "^22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openguardrails/openguardrails-js.git",
+    "directory": "packages/instrumentation-opencode"
+  },
+  "homepage": "https://openguardrails.com",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/config.ts

@@ -0,0 +1,101 @@
+/**
+ * Guardrails configuration for the opencode integration.
+ *
+ * The agent configures its OWN guardrails — text + regex rules (no model
+ * needed), and optionally its own model as an LLM judge. Config resolution:
+ *
+ *   1. a sensible default policy (below)
+ *   2. `.opencode/guardrails.json` in the project (agent-editable — this is how
+ *      an agent gives itself guardrails)
+ *   3. plugin `options` passed in opencode config (highest precedence)
+ *
+ * The policy IS an OGR policy.json (composition + config_rules), so the same
+ * file format works across every OGR integration.
+ */
+import { readFileSync, existsSync } from "node:fs"
+import { join } from "node:path"
+import type { Policy } from "@openguardrails/core"
+
+/** "Use your own model as the guardrail" — any OpenAI-compatible chat endpoint. */
+export interface JudgeConfig {
+  baseURL: string
+  model: string
+  apiKey?: string
+  headers?: Record<string, string>
+}
+
+export interface GuardrailsOptions {
+  /** Inline OGR policy (overrides the file + default). */
+  policy?: Policy
+  /** Path to a guardrails policy file (defaults to .opencode/guardrails.json). */
+  policyPath?: string
+  /** Enable the LLM-judge detector backed by your own model. */
+  judge?: JudgeConfig
+}
+
+/** Default text/regex guardrails — deterministic, no model required. */
+export const DEFAULT_POLICY: Policy = {
+  composition: {
+    "security.*": { strategy: "deny-wins", on_all_failed: "block" },
+    default: { strategy: "deny-wins" },
+  },
+  config_rules: {
+    secret_env_markers: ["SECRET", "TOKEN", "KEY", "PASSWORD", "AWS_", "PRIVATE", "CREDENTIAL"],
+    command_rules: [
+      {
+        id: "pipe-to-shell",
+        regex: "(curl|wget)\\b.*\\|\\s*(ba)?sh",
+        category: "security.malicious_command",
+        decision: "require_approval",
+        score: 0.85,
+        why: "remote script fetched and piped directly into a shell",
+      },
+      {
+        id: "rm-rf-root",
+        regex: "rm\\s+-rf\\s+/(\\s|$)",
+        category: "security.malicious_command",
+        decision: "block",
+        score: 1.0,
+        why: "destructive recursive delete of the filesystem root",
+      },
+      {
+        id: "secret-file-access",
+        regex: "(\\.env\\b|/\\.aws/credentials|/\\.ssh/id_|/\\.ssh/|auth\\.json|\\.netrc)",
+        category: "security.secret_leak",
+        decision: "block",
+        score: 0.9,
+        why: "command references a credential file — independent of the reader",
+      },
+      {
+        id: "pipe-to-sudo",
+        regex: "\\|\\s*sudo\\b",
+        category: "security.privilege_escalation",
+        decision: "require_approval",
+        score: 0.7,
+        why: "output piped into sudo",
+      },
+    ],
+  },
+}
+
+export interface ResolvedConfig {
+  policy: Policy
+  judge?: JudgeConfig
+}
+
+export function loadGuardrailsConfig(directory: string, options?: GuardrailsOptions): ResolvedConfig {
+  let policy: Policy = DEFAULT_POLICY
+
+  const path = options?.policyPath ?? join(directory, ".opencode", "guardrails.json")
+  if (existsSync(path)) {
+    try {
+      policy = JSON.parse(readFileSync(path, "utf8")) as Policy
+    } catch {
+      // malformed file → keep the safe default rather than failing open silently
+    }
+  }
+  if (options?.policy) policy = options.policy
+
+  const judge = options?.judge ?? (policy["judge"] as JudgeConfig | undefined)
+  return { policy, judge }
+}

package/src/index.ts

@@ -0,0 +1,86 @@
+/**
+ * openguardrails-instrumentation-opencode
+ *
+ * An opencode plugin that guards an agent's tool calls through the OpenGuardrails
+ * (OGR) protocol — the TS counterpart of `openguardrails-instrumentation-hermes`.
+ *
+ * It hooks `tool.execute.before` (fired for every tool, before it runs), turns
+ * the call into an OGR `GuardEvent`, runs it through a `Runtime` built from the
+ * agent's own guardrails policy (text/regex rules, plus optionally its own model
+ * as an LLM judge), and enforces the `Verdict`:
+ *
+ *   allow | modify | redact → proceed
+ *   block | require_approval → throw (deny-and-continue: the agent sees a tool
+ *                              error and must find a safer path or get approval)
+ *
+ * No opencode core changes required. This is a "restrict-only" guard: it can stop
+ * a would-run tool call, never loosen one.
+ */
+import type { Plugin, Hooks } from "@opencode-ai/plugin"
+import {
+  Runtime,
+  ConfigRulesDetector,
+  LLMJudgeDetector,
+  type Detector,
+  type GuardEvent,
+  type Verdict,
+} from "@openguardrails/core"
+import { loadGuardrailsConfig, type GuardrailsOptions } from "./config.js"
+import { openAICompatibleBackend } from "./own-model.js"
+
+let seq = 0
+function id(prefix: string): string {
+  seq += 1
+  const rand = globalThis.crypto?.randomUUID?.().slice(0, 8) ?? Math.random().toString(36).slice(2, 10)
+  return `${prefix}-${seq.toString(36)}-${rand}`
+}
+
+function brief(v: Verdict): string {
+  const cats = v.categories.map((c) => `${c.id}(${c.score})`).join(", ")
+  const why = v.reasons.filter((r) => !r.startsWith("[")).join("; ")
+  return [cats, why].filter(Boolean).join(" — ") || v.decision
+}
+
+export const OpenGuardrailsPlugin: Plugin = async ({ directory }, options) => {
+  const { policy, judge } = loadGuardrailsConfig(directory, options as GuardrailsOptions | undefined)
+
+  const detectors: Detector[] = [new ConfigRulesDetector(policy.config_rules ?? {})]
+  if (judge) detectors.push(new LLMJudgeDetector(openAICompatibleBackend(judge)))
+  const runtime = new Runtime(detectors, policy)
+
+  const hooks: Hooks = {
+    "tool.execute.before": async (input, output) => {
+      const ev: GuardEvent = {
+        kind: "tool_call",
+        observationPoint: "agent_hook",
+        subject: { agent_id: "opencode", agent_type: "opencode", session_id: input.sessionID },
+        payload: { name: input.tool, arguments: output.args },
+        eventId: id("evt"),
+        guardId: id("ga"),
+        timestamp: new Date().toISOString(),
+        sessionId: input.sessionID,
+        // v0.1: principal is trusted. Transcript-based tainting (web/mcp results
+        // → untrusted provenance) is a follow-up via the opencode session API.
+        provenance: [{ source: "user", trust: "trusted" }],
+      }
+
+      const verdict = await runtime.evaluate(ev)
+
+      if (verdict.decision === "block") {
+        throw new Error(`[OpenGuardrails] blocked this ${input.tool} call: ${brief(verdict)}`)
+      }
+      if (verdict.decision === "require_approval") {
+        throw new Error(
+          `[OpenGuardrails] this ${input.tool} call needs your explicit approval: ${brief(verdict)}. ` +
+            `Re-run only if you intend this, or relax .opencode/guardrails.json.`,
+        )
+      }
+      // allow | modify | redact → proceed
+    },
+  }
+
+  return hooks
+}
+
+export default OpenGuardrailsPlugin
+export { DEFAULT_POLICY, type GuardrailsOptions, type JudgeConfig } from "./config.js"

package/src/own-model.ts

@@ -0,0 +1,37 @@
+/**
+ * "Use your own model as the guardrail" — an OGR LLMBackend that calls any
+ * OpenAI-compatible chat-completions endpoint. Point it at the same model the
+ * agent already uses, a cheaper sibling, or a dedicated guard model.
+ */
+import type { LLMBackend } from "@openguardrails/core"
+import type { JudgeConfig } from "./config.js"
+
+export function openAICompatibleBackend(cfg: JudgeConfig): LLMBackend {
+  const url = cfg.baseURL.replace(/\/+$/, "") + "/chat/completions"
+  return {
+    name: `own-model:${cfg.model}`,
+    async complete(system: string, user: string): Promise<string> {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          ...(cfg.apiKey ? { authorization: `Bearer ${cfg.apiKey}` } : {}),
+          ...(cfg.headers ?? {}),
+        },
+        body: JSON.stringify({
+          model: cfg.model,
+          temperature: 0,
+          messages: [
+            { role: "system", content: system },
+            { role: "user", content: user },
+          ],
+        }),
+      })
+      if (!res.ok) throw new Error(`guard model returned ${res.status}`)
+      const data = (await res.json()) as { choices?: Array<{ message?: { content?: string } }> }
+      const text = data.choices?.[0]?.message?.content ?? ""
+      // Strip a ```json fence if the model wrapped its reply.
+      return text.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "").trim()
+    },
+  }
+}