oc-one-guard 0.1.2 → 0.2.0

package/README.md

@@ -18,7 +18,9 @@ The default `noul` question asks whether the call violates exfiltration policy.
 
 ## Quick Heads-Up
 
-- OpenCode v1 only. Version 1.19.4 is tested; v2 is not supported.
+- Branches: `main` targets the latest OpenCode (2.x) and also still loads on 1.19.4. The `opencode-1.x` branch delivers the 1.x-only line. Version numbers are plain semver and do not track OpenCode versions.
+- OpenCode 2.2.x (`setup` entry) was tested end to end on 2.2.5 with a scripted model and judge: allowed and blocked calls, judge outage, staged scripts and the load check. Subagent and MCP calls are not tested yet. OpenCode 1.19.4 (`server` entry) is the tested v1 host. Unsupported before 1.19.4.
+- OpenCode 2.x does not log decisions or show toasts. A load failure is logged as `failed to load plugin`, so [check it loaded](docs/installation.md#verify-it-loaded).
 - Setup is opt-in. Cloning this repo does not register the plugin or change OpenCode configuration.
 - The judge receives rendered tool arguments and, in some cases, staged file contents. Pick an endpoint you trust.
 
@@ -32,7 +34,7 @@ Published on npm as [`oc-one-guard`](https://www.npmjs.com/package/oc-one-guard)
 {
   "plugin": [
     [
-      "oc-one-guard@0.1.1",
+      "oc-one-guard@0.2.0",
       {
         "endpoint": "http://127.0.0.1:8081/v1/systemone",
         "model": "h2o-lightning-4b"
@@ -42,7 +44,7 @@ Published on npm as [`oc-one-guard`](https://www.npmjs.com/package/oc-one-guard)
 }
 ```
 
-Use the global config instead if you want it in every project. To uninstall, remove that entry and restart. Full details and the local-checkout option: [installation](https://github.com/HumanFace-Tech/oc-one-guard/blob/main/docs/installation.md).
+OpenCode 2.x uses the `plugins` key with an object entry instead; see [installation](https://github.com/HumanFace-Tech/oc-one-guard/blob/main/docs/installation.md). Use the global config instead if you want it in every project. To uninstall, remove that entry and restart. Full details and the local-checkout option: [installation](https://github.com/HumanFace-Tech/oc-one-guard/blob/main/docs/installation.md).
 
 ## How Does the Check Work?
 
@@ -80,7 +82,7 @@ The run was **incomplete**: 45 requests timed out across the direct and guard te
 
 ## What's Next?
 
-These are ideas, not current features: support for OpenCode v2, plus a simpler setup and calibration path that stays conservative by default. The current release supports v1 only.
+These are ideas, not current features: a simpler setup and calibration path that stays conservative by default, and end-to-end tool-call tests on OpenCode 2.x. Version 0.2.0 adds the OpenCode 2.x entry; see [ADR 0011](https://github.com/HumanFace-Tech/oc-one-guard/blob/main/docs/adr/0011-opencode-v2-adapter.md).
 
 ## License
 

package/bin/oc-one-guard-doctor

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// Checks that OpenCode 2.x loaded oc-one-guard. Exit codes: 0 loaded, 1 not loaded or failed, 2 check could not run.
+//
+// OpenCode 2.x keeps running when a plugin fails to load, and logs `failed to load plugin`.
+// Without this check, that failure leaves every tool call unreviewed. The `api provider.list`
+// operation waits for plugin activation before it answers, so the logs are complete when it exits.
+//
+// Usage: OPENCODE_BIN=opencode node bin/oc-one-guard-doctor
+// Run it against a private server (`--standalone`) so no background service is started.
+
+import { spawnSync } from "node:child_process"
+
+const bin = process.env.OPENCODE_BIN || "opencode"
+const args = ["--standalone", "--print-logs", "--log-level", "info", "api", "provider.list"]
+
+const run = spawnSync(bin, args, { encoding: "utf8", timeout: 120000, maxBuffer: 64 * 1024 * 1024 })
+if (run.error) {
+  console.error(`oc-one-guard doctor: could not run ${bin} (${run.error.code ?? "error"}).`)
+  process.exit(2)
+}
+if (run.status !== 0) {
+  console.error(`oc-one-guard doctor: OpenCode did not finish plugin activation (exit ${run.status}).`)
+  process.exit(2)
+}
+
+const lines = `${run.stdout ?? ""}\n${run.stderr ?? ""}`.split(/\r?\n/)
+const isGuard = line => /oc-one-guard/.test(line)
+
+if (lines.some(line => /failed to load plugin/.test(line) && isGuard(line))) {
+  console.error("oc-one-guard doctor: FAILED. OpenCode could not load oc-one-guard, so no tool call is reviewed.")
+  process.exit(1)
+}
+if (!lines.some(line => /loading plugin/.test(line) && isGuard(line))) {
+  console.error("oc-one-guard doctor: FAILED. OpenCode did not attempt to load oc-one-guard. Check the plugins entry.")
+  process.exit(1)
+}
+console.log("oc-one-guard doctor: OK. oc-one-guard was loaded and no load failure was logged.")

package/index.js

@@ -10,223 +10,16 @@
  * The guard runs in `tool.execute.before`. OpenCode awaits that hook before
  * executing the tool, so throwing from it aborts the call and surfaces the
  * reason to the agent as a failed tool result.
- */
-
-import { createAuditLogger } from "./src/audit.js"
-import { resolveConfig } from "./src/config.js"
-import { createGuard, VERDICT } from "./src/guard.js"
-import { scanBlockedHosts } from "./src/blocked-hosts.js"
-import { redactText } from "./src/redact.js"
-import { beginMutation, endMutation } from "./src/written.js"
-import { createStopController } from "./src/stop.js"
-import { createScope } from "./src/scope.js"
-
-export const id = "oc-one-guard"
-
-/**
- * Build the error the agent sees when a call is blocked.
  *
- * The message is written for the model: it states what was blocked and why,
- * so the agent can adjust instead of retrying blindly. Arguments are
- * redacted first — this text goes back to the model provider, so a secret
- * inside a blocked command would otherwise leave the machine here.
+ * The default export serves both hosts: `setup` for OpenCode 2.x and `server`
+ * for OpenCode 1.x. Both adapters call the same runtime.
  */
-function blockedMessage(decision, tool, args, redact) {
-  const preview =
-    typeof args?.command === "string" ? redactText(args.command).slice(0, 300) : undefined
-  const lines = [
-    `[oc-one-guard] Blocked tool call "${tool}".`,
-    `Reason: ${redactText(decision.reason)}`,
-  ]
-  if (decision.probability !== undefined) {
-    lines.push(`Exfiltration probability: ${decision.probability.toFixed(3)}`)
-  }
-  if (decision.hosts?.length) {
-    lines.push(`Destinations: ${decision.hosts.join(", ")}`)
-  }
-  if (preview) {
-    lines.push(`Command: ${preview}`)
-  }
-  if (decision.verdict === VERDICT.ESCALATE) {
-    lines.push("Manual review required. No native approval prompt is available from this hook.")
-  }
-  lines.push(
-    "This call was stopped before execution. If it is legitimate, rephrase it so the intent is explicit, or ask the user to run it manually.",
-  )
-  return lines.join("\n")
-}
 
-/**
- * The OpenCode plugin entry point.
- *
- * @param {{client: object, directory?: string, worktree?: string, project?: {id?: string, vcs?: string}}} input OpenCode v1 host context.
- * @param {Record<string, unknown>} [options]
- */
-export async function server(input, options) {
-  // A broken config must not remove the guard: OpenCode discards a plugin
-  // that throws while loading, which would leave every tool call
-  // unrestricted. `resolveConfig` falls back to the fail-closed defaults.
-  const config = resolveConfig(options)
-  const scope = createScope(input)
+import { server } from "./src/adapters/v1.js"
+import { setup } from "./src/adapters/v2.js"
 
-  const audit = createAuditLogger(config, input.client)
-  const guard = createGuard(config, { writeAudit: audit, directory: input.directory, scope })
-  const pending = new Map()
-  const finish = key => {
-    for (const token of pending.get(key) ?? []) endMutation(token, scope)
-    pending.delete(key)
-  }
-  const remove = (key, token) => {
-    if (!token) return
-    endMutation(token, scope)
-    const tokens = pending.get(key)
-    if (!tokens) return
-    const remaining = tokens.filter(item => item !== token)
-    if (remaining.length) pending.set(key, remaining)
-    else pending.delete(key)
-  }
-
-  const report = (level, message, extra) => {
-    try {
-      input.client.app?.log?.({
-        body: { service: "oc-one-guard", level, message, extra },
-      })?.catch?.(() => {})
-    } catch {
-      // Logging must never break the guard.
-    }
-  }
-  const stopNotice = (message, variant) => {
-    try {
-      input.client.tui?.showToast?.({ body: { title: "oc-one-guard", message, variant, duration: 8000 } })?.catch?.(() => {})
-    } catch {}
-  }
-  const stop = createStopController({
-    client: input.client,
-    directory: input.directory,
-    warn: message => { report("warn", message); if (config.notify) stopNotice(message, "warning") },
-    notify: message => { report("warn", message); if (config.notify) stopNotice(message, "warning") },
-  })
-
-  for (const problem of config.problems ?? []) {
-    report("error", `Configuration problem, using fail-closed defaults: ${problem}`)
-  }
-  if (config.degraded) {
-    report("error", "Guard is running with the bundled defaults because the configuration was invalid.")
-  }
-
-  if (config.enabled) {
-    report(
-      "info",
-      `Guard active: ${config.endpoint} (model ${config.model}), deny>=${config.denyThreshold}, escalate>=${config.escalateThreshold} (${config.escalateAction})`,
-    )
-  } else {
-    report("warn", "Guard is DISABLED by configuration. Tool calls are not being reviewed.")
-  }
-
-  return {
-    async "chat.message"(hookInput, output) {
-      stop.observe(hookInput, output)
-    },
-    async "tool.execute.before"(hookInput, output) {
-      const ticket = stop.capture(hookInput.sessionID)
-      const tool = hookInput.tool
-      const args = output.args
-      if (await stop.pending(hookInput.sessionID)) {
-        throw new Error("[oc-one-guard] Blocked tool call while conversation cancellation is pending.")
-      }
-
-      const scan = config.blockedHosts.length ? scanBlockedHosts(args, config.blockedHosts) : {}
-      if (scan.host || scan.limited) {
-        const decision = {
-          verdict: VERDICT.DENY,
-          reason: scan.host ? `Destination ${scan.host} is on the blocked-host list.` : "Blocked-host scan could not inspect all arguments (scan limit or inaccessible value).",
-          tool,
-          hosts: scan.host ? [scan.host] : [],
-          probability: undefined,
-          durationMs: 0,
-          mode: "host-block",
-          state: undefined,
-        }
-        audit(decision, {})
-        throw new Error(blockedMessage(decision, tool, args, config.redactArguments))
-      }
-
-      const mutation = config.enabled && ["write", "edit", "apply_patch"].includes(tool)
-      const key = typeof hookInput.sessionID === "string" && typeof hookInput.callID === "string" ? `${hookInput.sessionID}\0${hookInput.callID}` : undefined
-      const token = mutation ? beginMutation(scope) : undefined
-      if (token && key) {
-        const tokens = pending.get(key) ?? []
-        tokens.push(token)
-        pending.set(key, tokens)
-      }
-      let decision
-      try {
-        decision = await guard.evaluate({ tool, args })
-      } catch (error) {
-        remove(key, token)
-        throw error
-      }
-
-      if (decision.stop) {
-        remove(key, token)
-        await stop.request(ticket)
-        throw new Error(blockedMessage(decision, tool, args, config.redactArguments))
-      }
-      if (await stop.pending(hookInput.sessionID)) {
-        remove(key, token)
-        throw new Error("[oc-one-guard] Blocked tool call while conversation cancellation is pending.")
-      }
-      if (decision.verdict === VERDICT.ESCALATE && config.escalateAction === "allow") {
-        // Escalated but allowed: warn loudly so the attempt is visible.
-        audit(decision, { state: decision.state })
-        try {
-          input.client.tui?.showToast?.({
-            body: {
-              title: "oc-one-guard",
-              message: redactText(`Flagged ${tool}: ${decision.reason}`),
-              variant: "warning",
-              duration: 8000,
-            },
-          })?.catch?.(() => {})
-        } catch {
-          // A toast must never break the guard.
-        }
-        return
-      }
+export const id = "oc-one-guard"
 
-      if (decision.blocked) {
-        remove(key, token)
-        if (config.notify) {
-          try {
-            input.client.tui?.showToast?.({
-              body: {
-                title: "oc-one-guard",
-                message: redactText(`Blocked ${tool}: ${decision.reason}`),
-                variant: decision.verdict === VERDICT.ESCALATE ? "warning" : "error",
-                duration: 8000,
-              },
-            })?.catch?.(() => {})
-          } catch {
-            // A toast must never break the guard.
-          }
-        }
-        throw new Error(blockedMessage(decision, tool, args, config.redactArguments))
-      }
-    },
-    async "tool.execute.after"(hookInput) {
-      if (!["write", "edit", "apply_patch"].includes(hookInput.tool)) return
-      if (typeof hookInput.sessionID !== "string" || typeof hookInput.callID !== "string") return
-      const key = `${hookInput.sessionID}\0${hookInput.callID}`
-      finish(key)
-    },
-    async event({ event }) {
-      const part = event?.type === "message.part.updated" && event.properties?.part
-      // Interrupted parts can be marked as errors before their tool has stopped.
-      if (!part || part.type !== "tool" || !["write", "edit", "apply_patch"].includes(part.tool) || part.state?.status !== "error" || part.state?.metadata?.interrupted === true) return
-      if (typeof part.sessionID !== "string" || typeof part.callID !== "string") return
-      finish(`${part.sessionID}\0${part.callID}`)
-    },
-  }
-}
+export { server, setup }
 
-export default { id, server }
+export default { id, setup, server }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oc-one-guard",
-  "version": "0.1.2",
-  "description": "OpenCode v1-only plugin that checks proposed tool calls for outbound data exfiltration with a local decision-model judge",
+  "version": "0.2.0",
+  "description": "OpenCode plugin (v1 and v2) that checks proposed tool calls for outbound data exfiltration with a local decision-model judge",
   "type": "module",
   "main": "./index.js",
   "exports": {
@@ -11,6 +11,7 @@
   "files": [
     "index.js",
     "src/",
+    "bin/oc-one-guard-doctor",
     "eval/runner.js",
     "eval/cases.json",
     "config.example.json",
@@ -18,7 +19,7 @@
     "docs/assets/risk-policy.svg"
   ],
   "scripts": {
-    "test": "node --test test/config.test.js test/guard.test.js test/judge.test.js test/fallback.test.js test/plugin.test.js test/security.test.js test/stop.test.js test/eval.test.js",
+    "test": "node --test test/config.test.js test/guard.test.js test/judge.test.js test/fallback.test.js test/plugin.test.js test/v2-adapter.test.js test/security.test.js test/stop.test.js test/eval.test.js",
     "eval:live": "node eval/runner.js"
   },
   "engines": {

package/src/adapters/v1.js

@@ -0,0 +1,39 @@
+/**
+ * OpenCode 1.x entry point: `server(input, options)` with `client` hooks.
+ */
+
+import { resolveConfig } from "../config.js"
+import { createScope } from "../scope.js"
+import { createGuardRuntime } from "../runtime.js"
+import { isMutationTool } from "../tools.js"
+
+/**
+ * @param {{client: object, directory?: string, worktree?: string, project?: {id?: string, vcs?: string}}} input OpenCode v1 host context.
+ * @param {Record<string, unknown>} [options]
+ */
+export async function server(input, options) {
+  // A broken config must not remove the guard: OpenCode discards a plugin
+  // that throws while loading, which would leave every tool call
+  // unrestricted. `resolveConfig` falls back to the fail-closed defaults.
+  const config = resolveConfig(options)
+  const scope = createScope(input)
+  const runtime = createGuardRuntime(config, { client: input.client, directory: input.directory, scope })
+
+  return {
+    async "chat.message"(hookInput, output) {
+      runtime.observe(hookInput, output)
+    },
+    async "tool.execute.before"(hookInput, output) {
+      await runtime.before({ tool: hookInput.tool, sessionID: hookInput.sessionID, callID: hookInput.callID, args: output.args })
+    },
+    async "tool.execute.after"(hookInput) {
+      runtime.after({ tool: hookInput.tool, sessionID: hookInput.sessionID, callID: hookInput.callID })
+    },
+    async event({ event }) {
+      const part = event?.type === "message.part.updated" && event.properties?.part
+      // Interrupted parts can be marked as errors before their tool has stopped.
+      if (!part || part.type !== "tool" || !isMutationTool(part.tool) || part.state?.status !== "error" || part.state?.metadata?.interrupted === true) return
+      runtime.after({ tool: part.tool, sessionID: part.sessionID, callID: part.callID })
+    },
+  }
+}

package/src/adapters/v2.js

@@ -0,0 +1,67 @@
+/**
+ * OpenCode 2.x entry point: `setup(ctx)` with domain hooks.
+ */
+
+import { resolveConfig } from "../config.js"
+import { createScope } from "../scope.js"
+import { createGuardRuntime } from "../runtime.js"
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+// Never replace unusable input with `{}`: a shell call with no command would
+// skip the judge, and input repair may turn the same value into a real command.
+function inputOf(value) {
+  if (value === undefined || value === null) return {}
+  let parsed = value
+  if (typeof value === "string") {
+    try { parsed = JSON.parse(value) } catch { parsed = undefined }
+  }
+  if (!isPlainObject(parsed)) throw new Error("[oc-one-guard] Blocked tool call: its input is not a JSON object.")
+  return parsed
+}
+
+// The stop controller reads sessions through an SDK-shaped object. OpenCode 2.x
+// exposes the same two operations on `ctx.session`; nothing else is provided.
+function sessionClient(ctx) {
+  return {
+    session: {
+      get: async ({ path }) => ({ data: await ctx.session.get({ sessionID: path.id }) }),
+      abort: async ({ path }) => ({ data: (await ctx.session.interrupt({ sessionID: path.id })).interrupted === true }),
+    },
+  }
+}
+
+/**
+ * @param {object} ctx OpenCode 2.x plugin context: `options`, `location`, `session` and `tool` hooks.
+ */
+export async function setup(ctx) {
+  // Same fail-closed rule as the v1 entry: a bad configuration falls back to
+  // the bundled defaults rather than preventing the plugin from loading.
+  const config = resolveConfig(ctx.options)
+  const directory = ctx.location.directory
+  const scope = createScope({
+    directory,
+    worktree: ctx.location.project?.directory,
+    project: { id: ctx.location.project?.id },
+  })
+  const runtime = createGuardRuntime(config, { client: sessionClient(ctx), directory, scope })
+
+  await ctx.session.hook("prompt", event => {
+    runtime.observe({ sessionID: event.sessionID, messageID: event.messageID })
+  })
+  await ctx.tool.hook("execute.before", async event => {
+    await runtime.before({
+      tool: event.tool,
+      sessionID: event.sessionID,
+      callID: event.id,
+      args: inputOf(event.input),
+    })
+  })
+  await ctx.tool.hook("execute.after", event => {
+    runtime.after({ tool: event.tool, sessionID: event.sessionID, callID: event.id })
+  })
+
+  return () => runtime.dispose()
+}

package/src/guard.js

@@ -20,9 +20,11 @@ import { sharedCache } from "./shared.js"
 import { requireScope } from "./scope.js"
 import { extractHosts, fullText, hasOutboundSurface, hasTransferPrimitive, renderState, runsLocalScript } from "./state.js"
 import { getWrite, recordWrite, referencedWrites, writesRevision, markUncertainPatch, hasUncertainPatch, refreshWrite, hasWrites, ambiguousPath, hasPendingMutation } from "./written.js"
+import { canonicalTool, listsTool, pathsOf } from "./tools.js"
 
 // Patch headers are line-oriented. Never interpret content lines as paths.
-function trackMutation(tool, args, directory, scope) {
+function trackMutation(name, args, directory, scope) {
+  const tool = canonicalTool(name)
   const knownDirectory = typeof directory === "string" && posix.isAbsolute(directory)
   const lookup = path => getWrite(path, directory, scope)
   const uncertainPath = path => {
@@ -30,16 +32,18 @@ function trackMutation(tool, args, directory, scope) {
     if (ambiguousPath(path, directory)) markUncertainPatch(scope)
   }
   if (tool === "write" || tool === "edit") {
-    const path = args?.filePath
-    if (typeof path !== "string" || !path) return
-    uncertainPath(path)
+    const paths = pathsOf(args)
+    if (!paths.length) return
     const content = writeContent(tool, args)
-    if (!ambiguousPath(path, directory) && (lookup(path) || hasTransferPrimitive(content))) {
-      recordWrite(path, null, directory, scope)
+    for (const path of paths) {
+      uncertainPath(path)
+      if (!ambiguousPath(path, directory) && (lookup(path) || hasTransferPrimitive(content))) {
+        recordWrite(path, null, directory, scope)
+      }
     }
     return
   }
-  if (tool !== "apply_patch") return
+  if (tool !== "patch") return
   const patch = typeof args?.patchText === "string" ? args.patchText : args?.patch
   if (typeof patch !== "string") { markUncertainPatch(scope); return }
   const lines = patch.split(/\r?\n/)
@@ -79,9 +83,10 @@ function trackMutation(tool, args, directory, scope) {
  * The text a write-like tool puts on disk.
  *
  * `write` uses `content`, `edit` uses `newString` (and `oldString`), and
- * `apply_patch` uses a patch text. All of them can carry a payload.
+ * `patch` (2.x) or `apply_patch` (1.x) uses a patch text. All of them can carry a payload.
  */
-export function writeContent(tool, args) {
+export function writeContent(name, args) {
+  const tool = canonicalTool(name)
   if (!args || typeof args !== "object") return ""
   if (tool === "write") return typeof args.content === "string" ? args.content : ""
   if (tool === "edit") {
@@ -90,7 +95,7 @@ export function writeContent(tool, args) {
     if (typeof args.oldString === "string") parts.push(args.oldString)
     return parts.join("\n")
   }
-  if (tool === "apply_patch") {
+  if (tool === "patch") {
     const parts = []
     if (typeof args.patchText === "string") parts.push(args.patchText)
     if (typeof args.patch === "string") parts.push(args.patch)
@@ -244,7 +249,8 @@ export function createGuard(config, deps = {}) {
    */
   async function evaluate(input) {
     const started = now()
-    const { tool, args } = input
+    const tool = canonicalTool(input.tool)
+    const { args } = input
     const hosts = extractHosts(tool, args)
 
     if (!config.enabled) {
@@ -260,7 +266,7 @@ export function createGuard(config, deps = {}) {
 
     // Deny is a security control and is checked before the skip list, which
     // is only a performance optimisation.
-    if (config.deniedTools.includes(tool)) {
+    if (listsTool(config.deniedTools, tool)) {
       return new GuardDecision({
         verdict: VERDICT.DENY,
         reason: `Tool "${tool}" is on the deny list.`,
@@ -274,7 +280,7 @@ export function createGuard(config, deps = {}) {
     // Invalidate evidence even if policy later skips this tool or the tool fails.
     trackMutation(tool, args, deps.directory, scope)
 
-    if (config.skipTools.includes(tool)) {
+    if (listsTool(config.skipTools, tool)) {
       return new GuardDecision({
         verdict: VERDICT.ALLOW,
         reason: `Tool "${tool}" is on the skip list.`,
@@ -285,7 +291,7 @@ export function createGuard(config, deps = {}) {
       })
     }
 
-    if (config.allowedTools.includes(tool)) {
+    if (listsTool(config.allowedTools, tool)) {
       return new GuardDecision({
         verdict: VERDICT.ALLOW,
         reason: `Tool "${tool}" is on the allow list.`,
@@ -296,7 +302,7 @@ export function createGuard(config, deps = {}) {
       })
     }
 
-    const isShell = tool === "bash" || tool === "shell" || tool === "run"
+    const isShell = tool === "shell"
     const command = typeof args?.command === "string" ? args.command : ""
     const base = typeof deps.directory === "string" && posix.isAbsolute(deps.directory) ? deps.directory : undefined
     const workdir = typeof args?.workdir === "string" && args.workdir ? args.workdir : undefined
@@ -345,7 +351,8 @@ export function createGuard(config, deps = {}) {
     let state
     try {
       state = renderState({
-      tool,
+      // The host's own name, so the judge sees the same text as before canonical ids.
+      tool: input.tool,
       args,
       template: config.stateTemplate,
       maxStateChars: config.maxStateChars,

package/src/runtime.js

@@ -0,0 +1,254 @@
+/**
+ * Host-agnostic guard runtime shared by the OpenCode 1.x and 2.x adapters.
+ *
+ * The adapters translate host hook payloads into `before`, `after` and
+ * `observe` calls. Everything that decides or tracks state lives here.
+ */
+
+import { createAuditLogger } from "./audit.js"
+import { createGuard, VERDICT } from "./guard.js"
+import { scanBlockedHosts } from "./blocked-hosts.js"
+import { redactText } from "./redact.js"
+import { beginMutation, endMutation, markUncertainPatch } from "./written.js"
+import { createStopController } from "./stop.js"
+import { isMutationTool } from "./tools.js"
+
+const PENDING_TTL_MS = 10 * 60 * 1000
+
+/**
+ * Build the error the agent sees when a call is blocked.
+ *
+ * The message is written for the model: it states what was blocked and why,
+ * so the agent can adjust instead of retrying blindly. Arguments are
+ * redacted first — this text goes back to the model provider, so a secret
+ * inside a blocked command would otherwise leave the machine here.
+ */
+function blockedMessage(decision, tool, args) {
+  const preview =
+    typeof args?.command === "string" ? redactText(args.command).slice(0, 300) : undefined
+  const lines = [
+    `[oc-one-guard] Blocked tool call "${tool}".`,
+    `Reason: ${redactText(decision.reason)}`,
+  ]
+  if (decision.probability !== undefined) {
+    lines.push(`Exfiltration probability: ${decision.probability.toFixed(3)}`)
+  }
+  if (decision.hosts?.length) {
+    lines.push(`Destinations: ${decision.hosts.join(", ")}`)
+  }
+  if (preview) {
+    lines.push(`Command: ${preview}`)
+  }
+  if (decision.verdict === VERDICT.ESCALATE) {
+    lines.push("Manual review required. No native approval prompt is available from this hook.")
+  }
+  lines.push(
+    "This call was stopped before execution. If it is legitimate, rephrase it so the intent is explicit, or ask the user to run it manually.",
+  )
+  return lines.join("\n")
+}
+
+/**
+ * @param {object} config Normalized configuration.
+ * @param {object} host
+ * @param {string} [host.directory] Absolute project directory.
+ * @param {string} host.scope Explicit state scope from `createScope`.
+ * @param {object} [host.client] Optional SDK-shaped object. `app.log`, `tui.showToast` and `session.get/abort` are used when present.
+ */
+export function createGuardRuntime(config, { client, directory, scope }) {
+  const audit = createAuditLogger(config, client)
+  const guard = createGuard(config, { writeAudit: audit, directory, scope })
+  const pending = new Map()
+  const finish = key => {
+    for (const entry of pending.get(key) ?? []) endMutation(entry.token, scope)
+    pending.delete(key)
+  }
+  // Code Mode nested calls share the outer call id, so one `after` releases one token.
+  const releaseOne = key => {
+    const entries = pending.get(key)
+    if (!entries?.length) return
+    endMutation(entries.shift().token, scope)
+    if (!entries.length) pending.delete(key)
+  }
+  const remove = (key, token) => {
+    if (!token) return
+    endMutation(token, scope)
+    const entries = pending.get(key)
+    if (!entries) return
+    const remaining = entries.filter(item => item.token !== token)
+    if (remaining.length) pending.set(key, remaining)
+    else pending.delete(key)
+  }
+  // `after` never fires when a call is interrupted or a later plugin rejects it.
+  // Drop such tokens, but mark the scope uncertain: the write may still land.
+  const sweepStale = () => {
+    const cutoff = Date.now() - PENDING_TTL_MS
+    for (const [key, entries] of pending) {
+      const fresh = entries.filter(entry => entry.at >= cutoff)
+      if (fresh.length === entries.length) continue
+      for (const entry of entries) if (entry.at < cutoff) endMutation(entry.token, scope)
+      markUncertainPatch(scope)
+      if (fresh.length) pending.set(key, fresh)
+      else pending.delete(key)
+    }
+  }
+
+  const report = (level, message, extra) => {
+    try {
+      client?.app?.log?.({
+        body: { service: "oc-one-guard", level, message, extra },
+      })?.catch?.(() => {})
+    } catch {
+      // Logging must never break the guard.
+    }
+  }
+  const stopNotice = (message, variant) => {
+    try {
+      client?.tui?.showToast?.({ body: { title: "oc-one-guard", message, variant, duration: 8000 } })?.catch?.(() => {})
+    } catch {}
+  }
+  const stop = createStopController({
+    client,
+    directory,
+    warn: message => { report("warn", message); if (config.notify) stopNotice(message, "warning") },
+    notify: message => { report("warn", message); if (config.notify) stopNotice(message, "warning") },
+  })
+
+  for (const problem of config.problems ?? []) {
+    report("error", `Configuration problem, using fail-closed defaults: ${problem}`)
+  }
+  if (config.degraded) {
+    report("error", "Guard is running with the bundled defaults because the configuration was invalid.")
+  }
+
+  if (config.enabled) {
+    report(
+      "info",
+      `Guard active: ${config.endpoint} (model ${config.model}), deny>=${config.denyThreshold}, escalate>=${config.escalateThreshold} (${config.escalateAction})`,
+    )
+  } else {
+    report("warn", "Guard is DISABLED by configuration. Tool calls are not being reviewed.")
+  }
+
+  return {
+    observe(input, output) {
+      stop.observe(input, output)
+    },
+
+    async before({ tool, sessionID, callID, args }) {
+      sweepStale()
+      const ticket = stop.capture(sessionID)
+      if (await stop.pending(sessionID)) {
+        throw new Error("[oc-one-guard] Blocked tool call while conversation cancellation is pending.")
+      }
+
+      const scan = config.blockedHosts.length ? scanBlockedHosts(args, config.blockedHosts) : {}
+      if (scan.host || scan.limited) {
+        const decision = {
+          verdict: VERDICT.DENY,
+          reason: scan.host ? `Destination ${scan.host} is on the blocked-host list.` : "Blocked-host scan could not inspect all arguments (scan limit or inaccessible value).",
+          tool,
+          hosts: scan.host ? [scan.host] : [],
+          probability: undefined,
+          durationMs: 0,
+          mode: "host-block",
+          state: undefined,
+        }
+        audit(decision, {})
+        throw new Error(blockedMessage(decision, tool, args))
+      }
+
+      const mutation = config.enabled && isMutationTool(tool)
+      const key = typeof sessionID === "string" && typeof callID === "string" ? `${sessionID}\0${callID}` : undefined
+      // A token without a key can never be released, so it would deny later
+      // script runs until restart. Refuse the call instead.
+      if (mutation && !key) {
+        const decision = {
+          verdict: VERDICT.DENY,
+          reason: "The call has no session or call identifier, so its pending state cannot be tracked.",
+          tool,
+          hosts: [],
+          probability: undefined,
+          durationMs: 0,
+          mode: "uncorrelated-block",
+          state: undefined,
+        }
+        audit(decision, {})
+        throw new Error(blockedMessage(decision, tool, args))
+      }
+      const token = mutation ? beginMutation(scope) : undefined
+      if (token && key) {
+        const entries = pending.get(key) ?? []
+        entries.push({ token, at: Date.now() })
+        pending.set(key, entries)
+      }
+      let decision
+      try {
+        decision = await guard.evaluate({ tool, args })
+      } catch (error) {
+        remove(key, token)
+        throw error
+      }
+
+      if (decision.stop) {
+        remove(key, token)
+        await stop.request(ticket)
+        throw new Error(blockedMessage(decision, tool, args))
+      }
+      if (await stop.pending(sessionID)) {
+        remove(key, token)
+        throw new Error("[oc-one-guard] Blocked tool call while conversation cancellation is pending.")
+      }
+      if (decision.verdict === VERDICT.ESCALATE && config.escalateAction === "allow") {
+        // Escalated but allowed: warn loudly so the attempt is visible.
+        audit(decision, { state: decision.state })
+        try {
+          client?.tui?.showToast?.({
+            body: {
+              title: "oc-one-guard",
+              message: redactText(`Flagged ${tool}: ${decision.reason}`),
+              variant: "warning",
+              duration: 8000,
+            },
+          })?.catch?.(() => {})
+        } catch {
+          // A toast must never break the guard.
+        }
+        return
+      }
+
+      if (decision.blocked) {
+        remove(key, token)
+        if (config.notify) {
+          try {
+            client?.tui?.showToast?.({
+              body: {
+                title: "oc-one-guard",
+                message: redactText(`Blocked ${tool}: ${decision.reason}`),
+                variant: decision.verdict === VERDICT.ESCALATE ? "warning" : "error",
+                duration: 8000,
+              },
+            })?.catch?.(() => {})
+          } catch {
+            // A toast must never break the guard.
+          }
+        }
+        throw new Error(blockedMessage(decision, tool, args))
+      }
+    },
+
+    after({ tool, sessionID, callID }) {
+      if (!isMutationTool(tool)) return
+      if (typeof sessionID !== "string" || typeof callID !== "string") return
+      releaseOne(`${sessionID}\0${callID}`)
+    },
+
+    // Called when the plugin unloads. A mutation still in flight may land after
+    // its hook is gone, so the scope is marked uncertain rather than trusted.
+    dispose() {
+      const held = [...pending.values()].some(entries => entries.length > 0)
+      for (const key of [...pending.keys()]) finish(key)
+      if (held) markUncertainPatch(scope)
+    },
+  }
+}

package/src/state.js

@@ -18,6 +18,7 @@
 
 import { getWrite, referencedWrites } from "./written.js"
 import { requireScope } from "./scope.js"
+import { canonicalTool, pathsOf } from "./tools.js"
 
 const URL_PATTERN = /\b(?:https?|ftps?|sftp|scp|rsync|ssh|git):\/\/[^\s"'`<>|;&]+/gi
 
@@ -51,7 +52,7 @@ const LOCAL_ONLY_TOOLS = new Set([
  * file and execute it in a later call. Their content is judged when it
  * contains something that moves data.
  */
-const CONTENT_TOOLS = new Set(["write", "edit", "apply_patch"])
+const CONTENT_TOOLS = new Set(["write", "edit", "patch"])
 
 /**
  * Primitives that reach the network, matched against shell text.
@@ -138,13 +139,14 @@ export function runsLocalScript(text) {
  * @returns {string[]}
  */
 export function extractHosts(tool, args) {
+  const name = canonicalTool(tool)
   const chunks = []
-  if (tool === "bash" || tool === "shell" || tool === "run") {
+  if (name === "shell") {
     if (typeof args?.command === "string") chunks.push(args.command)
-  } else if (tool === "webfetch") {
+  } else if (name === "webfetch") {
     if (typeof args?.url === "string") chunks.push(args.url)
-  } else if (CONTENT_TOOLS.has(tool)) {
-    chunks.push(writtenContent(tool, args))
+  } else if (CONTENT_TOOLS.has(name)) {
+    chunks.push(writtenContent(name, args))
   }
 
   const hosts = new Set()
@@ -170,20 +172,14 @@ export function extractPaths(tool, args) {
   const push = (value) => {
     if (typeof value === "string" && value.trim()) paths.push(value.trim())
   }
-  switch (tool) {
+  switch (canonicalTool(tool)) {
     case "read":
-      push(args?.filePath)
-      break
     case "write":
-      push(args?.filePath)
-      break
     case "edit":
-      push(args?.filePath)
-      break
-    case "apply_patch":
-      push(args?.filePath)
+    case "patch":
+      pathsOf(args).forEach(push)
       break
-    case "bash":
+    case "shell":
       push(args?.workdir)
       break
     default:
@@ -287,15 +283,16 @@ export function fullText(tool, args) {
  * helper is used so the two agree.
  */
 export function writtenContent(tool, args) {
+  const name = canonicalTool(tool)
   if (!args || typeof args !== "object") return ""
-  if (tool === "write") return typeof args.content === "string" ? args.content : ""
-  if (tool === "edit") {
+  if (name === "write") return typeof args.content === "string" ? args.content : ""
+  if (name === "edit") {
     const parts = []
     if (typeof args.newString === "string") parts.push(args.newString)
     if (typeof args.oldString === "string") parts.push(args.oldString)
     return parts.join("\n")
   }
-  if (tool === "apply_patch") {
+  if (name === "patch") {
     const parts = []
     if (typeof args.patchText === "string") parts.push(args.patchText)
     if (typeof args.patch === "string") parts.push(args.patch)
@@ -316,17 +313,18 @@ export function writtenContent(tool, args) {
  */
 export function hasOutboundSurface(tool, args, directory, scope) {
   requireScope(scope)
-  if (LOCAL_ONLY_TOOLS.has(tool)) {
+  const name = canonicalTool(tool)
+  if (LOCAL_ONLY_TOOLS.has(name)) {
     // A file write can stage a payload that a later call executes, so the
     // content decides.
-    if (CONTENT_TOOLS.has(tool)) {
-      const content = writtenContent(tool, args)
+    if (CONTENT_TOOLS.has(name)) {
+      const content = writtenContent(name, args)
       return hasTransferPrimitive(content)
     }
     return false
   }
 
-  if (tool === "bash" || tool === "shell" || tool === "run") {
+  if (name === "shell") {
     const command = typeof args?.command === "string" ? args.command : ""
     if (hasTransferPrimitive(command)) return true
     if (runsLocalScript(command)) return true
@@ -336,7 +334,7 @@ export function hasOutboundSurface(tool, args, directory, scope) {
     return false
   }
 
-  if (tool === "webfetch") {
+  if (name === "webfetch") {
     if (args && Object.keys(args).some((key) => !["url", "format", "timeout"].includes(key))) return true
     // A GET can still carry data in the path or the query string.
     const url = typeof args?.url === "string" ? args.url : ""

package/src/tools.js

@@ -0,0 +1,37 @@
+/**
+ * Tool identifiers shared by OpenCode 1.x and 2.x.
+ *
+ * Canonical names are the OpenCode 2.x ids. Names from 1.x are mapped onto
+ * them, so policy lists and checks work for both hosts.
+ */
+
+const ALIASES = new Map([
+  ["bash", "shell"],
+  ["apply_patch", "patch"],
+  ["task", "subagent"],
+])
+
+export function canonicalTool(name) {
+  if (typeof name !== "string") return name
+  return ALIASES.get(name) ?? name
+}
+
+export function isMutationTool(tool) {
+  return ["write", "edit", "patch"].includes(canonicalTool(tool))
+}
+
+export function listsTool(list, tool) {
+  const wanted = canonicalTool(tool)
+  return list.some(entry => typeof entry === "string" && canonicalTool(entry) === wanted)
+}
+
+// 1.x write, edit and read take `filePath`; 2.x takes `path`. Every listed
+// path counts as evidence, so a call that carries both is judged on both.
+export function pathsOf(args) {
+  const paths = []
+  for (const key of ["filePath", "path"]) {
+    const value = args?.[key]
+    if (typeof value === "string" && value && !paths.includes(value)) paths.push(value)
+  }
+  return paths
+}