oc-one-guard 0.1.2 → 0.3.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.3.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?
 
@@ -66,7 +68,6 @@ An earlier synthetic guard run requested **H2O Lightning 4B** (the served model
 |---|---|
 | Benign calls scored by H2O | 17 allowed, **9 blocked** |
 | Malicious calls scored by H2O | **24 blocked**, 0 allowed |
-| Malicious call skipped by the prefilter | **1 allowed** without model review |
 
 The run was **incomplete**: 45 requests timed out across the direct and guard tests. Timeout blocks aren't model detections, and these small synthetic samples aren't production rates. [See the cases and full breakdown](https://github.com/HumanFace-Tech/oc-one-guard/blob/main/docs/research/h2o-synthetic-evaluation.md).
 
@@ -80,7 +81,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/config.example.json

@@ -19,12 +19,6 @@
   "redactArguments": true,
   "cacheEnabled": true,
   "cacheTtlMs": 30000,
-  "prefilter": true,
-  "skipTools": [],
-  "deniedTools": [],
-  "allowedTools": [],
-  "allowedHosts": [],
-  "blockedHosts": [],
   "maxStateChars": 8000,
   "maxArgChars": 2000,
   "stateTemplate": "proposed agent tool call\ntool: {tool}\narguments: {arguments}",

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.3.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/config.js

@@ -202,13 +202,6 @@ export function normalizeConfig(raw) {
     }
   }
 
-  const denied = new Set(merged.deniedTools ?? [])
-  for (const tool of merged.skipTools ?? []) {
-    if (denied.has(tool)) {
-      errors.push(`tool "${tool}" is on both the deny list and the skip list`)
-    }
-  }
-
   if (errors.length) {
     throw new Error(`[oc-one-guard] Invalid configuration: ${errors.join("; ")}`)
   }
@@ -221,11 +214,6 @@ export function normalizeConfig(raw) {
   merged.cacheTtlMs = Math.max(0, Math.floor(Number(merged.cacheTtlMs) || 0))
   merged.auditGenerations = Math.max(1, Math.floor(Number(merged.auditGenerations) || DEFAULTS.auditGenerations))
 
-  if (!Array.isArray(merged.allowedTools)) merged.allowedTools = []
-  if (!Array.isArray(merged.deniedTools)) merged.deniedTools = []
-  if (!Array.isArray(merged.skipTools)) merged.skipTools = []
-  if (!Array.isArray(merged.allowedHosts)) merged.allowedHosts = []
-  if (!Array.isArray(merged.blockedHosts)) merged.blockedHosts = []
   if (!Array.isArray(merged.questions)) merged.questions = []
 
   return merged

package/src/defaults.js

@@ -47,12 +47,6 @@
  * @property {boolean} redactArguments    Strip secret-looking values before they leave the machine.
  * @property {boolean} cacheEnabled       Cache identical verdicts for a short window.
  * @property {number} cacheTtlMs
- * @property {boolean} prefilter          Skip the judge for calls with no outbound surface.
- * @property {string[]} skipTools         Tool names never inspected.
- * @property {string[]} deniedTools       Tool names always blocked.
- * @property {string[]} allowedTools      Tool names always allowed, judge not consulted.
- * @property {string[]} allowedHosts      Hosts treated as trusted destinations.
- * @property {string[]} blockedHosts      Hosts always treated as exfiltration destinations.
  * @property {number} maxStateChars      Cap on the rendered state sent to the judge.
  * @property {number} maxArgChars        Per-argument truncation before rendering.
  * @property {QuestionConfig[]} questions  Judge questions.
@@ -84,12 +78,6 @@ export const DEFAULTS = {
   redactArguments: true,
   cacheEnabled: true,
   cacheTtlMs: 30000,
-  prefilter: true,
-  skipTools: [],
-  deniedTools: [],
-  allowedTools: [],
-  allowedHosts: [],
-  blockedHosts: [],
   maxStateChars: 8000,
   maxArgChars: 2000,
   stateTemplate:

package/src/guard.js

@@ -2,10 +2,9 @@
  * The guard engine: decide, cache, audit.
  *
  * Decision order:
- *   1. Tool allow/deny lists and host lists decide without consulting the judge.
- *   2. The judge is asked for a verdict.
- *   3. The verdict is compared against `denyThreshold` and `escalateThreshold`.
- *   4. Failures fall back to `failMode`; unclassifiable verdicts to `unknownMode`.
+ *   1. The judge is asked about every call; no code rule decides for it.
+ *   2. The verdict is compared against `denyThreshold` and `escalateThreshold`.
+ *   3. Failures fall back to `failMode`; unclassifiable verdicts to `unknownMode`.
  *
  * The cache is keyed on the *full* call as well as the rendered state. The
  * rendered state is truncated, so two different commands could otherwise
@@ -18,11 +17,13 @@ import { posix } from "node:path"
 import { denyProbability, findDenyOption, JudgeError, requestDecision } from "./judge.js"
 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 { extractHosts, fullText, hasTransferPrimitive, renderState } from "./state.js"
+import { getWrite, recordWrite, referencedWrites, markUncertainPatch, refreshWrite, ambiguousPath } from "./written.js"
+import { canonicalTool, 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 +31,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 +82,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 +94,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 +248,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) {
@@ -258,94 +263,26 @@ 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)) {
-      return new GuardDecision({
-        verdict: VERDICT.DENY,
-        reason: `Tool "${tool}" is on the deny list.`,
-        tool,
-        hosts,
-        durationMs: 0,
-        mode: "tool-deny",
-      })
-    }
-
-    // Invalidate evidence even if policy later skips this tool or the tool fails.
+    // Writes are tracked only as context for the judge; nothing here decides.
     trackMutation(tool, args, deps.directory, scope)
 
-    if (config.skipTools.includes(tool)) {
-      return new GuardDecision({
-        verdict: VERDICT.ALLOW,
-        reason: `Tool "${tool}" is on the skip list.`,
-        tool,
-        hosts,
-        durationMs: 0,
-        mode: "skip",
-      })
-    }
-
-    if (config.allowedTools.includes(tool)) {
-      return new GuardDecision({
-        verdict: VERDICT.ALLOW,
-        reason: `Tool "${tool}" is on the allow list.`,
-        tool,
-        hosts,
-        durationMs: 0,
-        mode: "tool-allow",
-      })
-    }
-
-    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
     const directory = workdir ? (posix.isAbsolute(workdir) ? posix.normalize(workdir) : base ? posix.resolve(base, workdir) : undefined) : base
-    const words = command.match(/'[^']*'|"[^"]*"|[^\s;&|()<>]+/g) ?? []
-    const ambiguous = ambiguousPath(workdir, base) || ambiguousPath(base) || words.some(word => {
-      const value = word.replace(/^(['"])(.*)\1$/, "$2")
-      return value.includes("/") && ambiguousPath(value, directory)
-    })
-    if (isShell && ambiguous && (hasWrites(scope) || hasUncertainPatch(scope))) {
-      const decision = new GuardDecision({ verdict: VERDICT.DENY, reason: "Ambiguous filesystem path prevents reliable staged-file evidence.", tool, hosts, durationMs: now() - started, mode: "staged-unknown" })
-      writeAudit(decision, {})
-      return decision
-    }
     const hits = isShell ? referencedWrites(command, directory, scope) : []
     const snapshots = new Map(hits.map(hit => {
       const entry = getWrite(hit.path, undefined, scope)
       const content = entry.content === null ? refreshWrite(hit.path, scope) : entry.content
       return [hit.path, { ...entry, content: content ?? null }]
     }))
-    const unresolvedScript = runsLocalScript(command) && hasWrites(scope) &&
-      ((!directory && !command.match(/(?:^|\s)\//)) || /(?:^|[;&|]\s*)\s*cd(?:\s|$)|[$`*?\[\]{}\\]/.test(command))
-    const unknownStaged = isShell && (hits.some(hit => snapshots.get(hit.path)?.content === null) || (hasPendingMutation(scope) && (hits.length > 0 || runsLocalScript(command))) || (hasUncertainPatch(scope) && runsLocalScript(command)) || unresolvedScript)
-    if (unknownStaged) {
-      const decision = new GuardDecision({ verdict: VERDICT.DENY, reason: "Tracked file content is unknown after a modification.", tool, hosts, durationMs: now() - started, mode: "staged-unknown" })
-      writeAudit(decision, {})
-      return decision
-    }
-    const revision = writesRevision(scope)
-    const snapshotsValid = () => (!(hits.length || runsLocalScript(command)) || !hasPendingMutation(scope)) && [...snapshots].every(([path, snapshot]) => {
-      const entry = getWrite(path, undefined, scope)
-      return entry && !ambiguousPath(path) && (entry.content === null ? refreshWrite(path, scope) : entry.content) === snapshot.content
-    })
-
-    if (config.prefilter && !hasOutboundSurface(tool, args, directory, scope)) {
-      return new GuardDecision({
-        verdict: VERDICT.ALLOW,
-        reason: `Tool "${tool}" has no outbound surface.`,
-        tool,
-        hosts,
-        durationMs: 0,
-        mode: "prefilter",
-      })
-    }
 
     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,
@@ -355,7 +292,8 @@ export function createGuard(config, deps = {}) {
       scope,
       })
     } catch {
-      const decision = new GuardDecision({ verdict: VERDICT.DENY, reason: "Security facts exceed the state limit or could not be rendered.", tool, hosts, durationMs: now() - started, mode: "state-block" })
+      const blocked = config.failMode === "block"
+      const decision = new GuardDecision({ verdict: blocked ? VERDICT.DENY : VERDICT.ALLOW, reason: `Call state could not be rendered for the judge. failMode="${config.failMode}".`, tool, hosts, durationMs: now() - started, mode: blocked ? "fail-block" : "fail-allow" })
       writeAudit(decision, {})
       return decision
     }
@@ -365,7 +303,6 @@ export function createGuard(config, deps = {}) {
     const cached = cacheGet(key)
     if (cached?.pending) {
       const decision = await cached.pending
-      if (isShell && (revision !== writesRevision(scope) || !snapshotsValid())) return evaluate(input)
       return new GuardDecision({ ...decision, durationMs: now() - started, mode: `${decision.mode}:coalesced` })
     }
     if (cached?.value) {
@@ -392,10 +329,6 @@ export function createGuard(config, deps = {}) {
       }
       throw error
     }
-    if (isShell && (revision !== writesRevision(scope) || !snapshotsValid())) {
-      if (config.cacheEnabled && cache.get(key)?.pending === pending) cache.delete(key)
-      return evaluate(input)
-    }
     if (decision.mode === "judge" && decision.verdict !== VERDICT.ESCALATE && !decision.stop) cacheSet(key, { ...decision })
     else if (config.cacheEnabled && cache.get(key)?.pending === pending) cache.delete(key)
     return decision

package/src/runtime.js

@@ -0,0 +1,221 @@
+/**
+ * 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 { 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 mutation = config.enabled && isMutationTool(tool)
+      const key = typeof sessionID === "string" && typeof callID === "string" ? `${sessionID}\0${callID}` : undefined
+      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,32 +18,10 @@
 
 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
 
-/**
- * Tools that cannot, on their own, move data off the machine.
- *
- * These are the only tools that skip the judge without further checks.
- * Everything else — shell, webfetch, MCP tools, any tool added in a future
- * OpenCode release — is judged.
- */
-const LOCAL_ONLY_TOOLS = new Set([
-  "read",
-  "write",
-  "edit",
-  "apply_patch",
-  "glob",
-  "grep",
-  "list",
-  "todowrite",
-  "todoread",
-  "patch",
-  "question",
-  "plan_exit",
-  "invalid",
-])
-
 /**
  * Tools whose arguments can contain a payload bound for a remote host.
  *
@@ -51,7 +29,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 +116,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 +149,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)
+    case "patch":
+      pathsOf(args).forEach(push)
       break
-    case "apply_patch":
-      push(args?.filePath)
-      break
-    case "bash":
+    case "shell":
       push(args?.workdir)
       break
     default:
@@ -287,15 +260,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)
@@ -304,54 +278,6 @@ export function writtenContent(tool, args) {
   return ""
 }
 
-/**
- * Decide whether a tool call has an outbound surface worth judging.
- *
- * The rule is an allowlist of known-local tools. Anything else — including
- * MCP tools, `webfetch`, and any tool added in a future OpenCode release —
- * is judged.
- *
- * A shell command is judged when it uses a network primitive, runs a file
- * the agent has written, or mentions a written file at all.
- */
-export function hasOutboundSurface(tool, args, directory, scope) {
-  requireScope(scope)
-  if (LOCAL_ONLY_TOOLS.has(tool)) {
-    // 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)
-      return hasTransferPrimitive(content)
-    }
-    return false
-  }
-
-  if (tool === "bash" || tool === "shell" || tool === "run") {
-    const command = typeof args?.command === "string" ? args.command : ""
-    if (hasTransferPrimitive(command)) return true
-    if (runsLocalScript(command)) return true
-    // The command mentions a file the agent wrote earlier. It may now hold
-    // a payload, so it is judged.
-    if (referencedWrites(command, directory, scope).length) return true
-    return false
-  }
-
-  if (tool === "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 : ""
-    if (!url) return false
-    try {
-      const parsed = new URL(url)
-      return parsed.search.length > 1 || parsed.pathname.length > 1
-    } catch {
-      return true
-    }
-  }
-
-  return true
-}
-
 /**
  * The contents of files the agent wrote that a command references.
  *

package/src/tools.js

@@ -0,0 +1,32 @@
+/**
+ * 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))
+}
+
+// 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
+}

package/src/blocked-hosts.js

@@ -1,61 +0,0 @@
-import { hostMatches } from "./guard.js"
-
-// Bound both traversal and text scanning, including object keys. Exceeding a
-// limit is a denial: an unseen suffix could contain a blocked destination.
-const MAX_NODES = 10000
-const MAX_DEPTH = 100
-const MAX_CHARS = 1000000
-// Stop at the authority, leaving paths and queries available for independent
-// URL matches. Shell punctuation can also be valid URL credentials, so it
-// must not truncate the authority before the URL parser sees it.
-const URLS = /\b([a-z][a-z0-9+.-]*:\/\/)([^\s/?#]+)/gi
-const SHELL_PUNCTUATION = /["'`<>|;&()]/
-const TRAILING_SHELL_PUNCTUATION = /["'`<>|;&()]+$/
-
-export function scanBlockedHosts(args, patterns) {
-  const seen = new WeakSet()
-  const pending = [{ value: args, depth: 0 }]
-  let nodes = 0
-  let chars = 0
-  try {
-    while (pending.length) {
-      const { value, depth } = pending.pop()
-      if (++nodes > MAX_NODES || depth > MAX_DEPTH) return { limited: true }
-      if (typeof value === "string") {
-        chars += value.length
-        if (chars > MAX_CHARS) return { limited: true }
-        for (const match of value.matchAll(URLS)) {
-          // Check at most two interpretations: the complete authority (minus
-          // closing shell punctuation), and the prefix a shell could use.
-          // Never enumerate every punctuation prefix: work stays bounded.
-          const authority = match[2]
-          const candidates = [authority.replace(TRAILING_SHELL_PUNCTUATION, "")]
-          const delimiter = authority.search(SHELL_PUNCTUATION)
-          if (delimiter >= 0) candidates.push(authority.slice(0, delimiter))
-          for (const candidate of candidates) {
-            try {
-              const host = new URL(match[1] + candidate).hostname.toLowerCase().replace(/\.$/, "")
-              if (!host) return { limited: true }
-              if (hostMatches(host, patterns)) return { host }
-            } catch {
-              // An ambiguous/unparseable authority is not evidence of safety.
-              return { limited: true }
-            }
-          }
-        }
-      } else if (value && typeof value === "object" && !seen.has(value)) {
-        seen.add(value)
-        const keys = Object.keys(value)
-        if (nodes + pending.length + keys.length * 2 > MAX_NODES) return { limited: true }
-        for (const key of keys) {
-          const descriptor = Object.getOwnPropertyDescriptor(value, key)
-          if (!descriptor || !("value" in descriptor)) return { limited: true }
-          pending.push({ value: key, depth: depth + 1 }, { value: descriptor.value, depth: depth + 1 })
-        }
-      }
-    }
-    return {}
-  } catch {
-    return { limited: true }
-  }
-}