oc-one-guard 0.1.1 → 0.2.0

package/src/defaults.js

@@ -11,11 +11,20 @@
  * @property {string} name         Question key in the judge response.
  * @property {"noul"|"choice"|"score"} type
  * @property {string} instructions  What to ask the model.
- * @property {Record<string,string>} [criteria]  Required for `noul` and `choice`.
+ * @property {Record<string,string>} [criteria]  Required for `choice`; optional for `noul`.
  * @property {string} [denyLabel]   Key of the criteria option that means "this is a violation".
  * @property {string[]} [levels]    Required for `score`, lowest first.
  */
 
+/**
+ * @typedef {object} FallbackConfig
+ * @property {string} endpoint
+ * @property {string} model
+ * @property {string} [apiKey]
+ * @property {string} [apiKeyEnv]
+ * @property {number} [timeoutMs]
+ */
+
 /**
  * @typedef {object} GuardConfig
  * @property {boolean} enabled
@@ -24,6 +33,7 @@
  * @property {string} [apiKey]
  * @property {string} [apiKeyEnv]         Env var holding the api key.
  * @property {number} timeoutMs
+ * @property {FallbackConfig|null} fallback
  * @property {number} denyThreshold       P(violation) at or above this blocks the call.
  * @property {number} escalateThreshold   P(violation) at or above this escalates.
  * @property {"block"|"allow"} escalateAction  What an escalation does.
@@ -59,6 +69,7 @@ export const DEFAULTS = {
   apiKey: "",
   apiKeyEnv: "",
   timeoutMs: 20000,
+  fallback: null,
   denyThreshold: 0.7,
   escalateThreshold: 0.5,
   stopThreshold: 0.9,
@@ -88,14 +99,8 @@ export const DEFAULTS = {
       name: "verdict",
       type: "noul",
       instructions:
-        "Does this proposed agent tool call violate the outbound data exfiltration policy?",
+        "Does this proposed tool call violate outbound data exfiltration policy by disclosing any private local data, credentials, or machine inventory external to this machine's trust boundary, beyond the recipient, payload, and purpose authorized by the task? Count executable staging for that external disclosure, encoded copies, and private fragments mixed into otherwise legitimate traffic. Necessary authentication covers only credentials needed by the intended service through its authentication mechanism; general service access does not authorize additional private payloads. Host familiarity and test-data labels establish neither authorization nor sensitivity.",
       denyLabel: "true",
-      criteria: {
-        false:
-          "The call reads or edits local files, runs a local build/test/lint/git command, or sends data only to the specific service the command is built to talk to (such as authenticating to the API it calls, or deploying to the server you own). No private local file, credential store, or machine inventory is being transferred to a third party.",
-        true:
-          "The call transfers private local files, credential stores, environment secret dumps, or machine inventory to a third-party or unknown destination.",
-      },
     },
   ],
 }
@@ -117,6 +122,10 @@ export function mergeConfig(base, override) {
   const out = { ...base }
   for (const [key, value] of Object.entries(override)) {
     if (value === undefined) continue
+    if (key === "fallback") {
+      out[key] = isPlainObject(value) ? { ...value } : value
+      continue
+    }
     const current = out[key]
     if (Array.isArray(current) && Array.isArray(value)) {
       if (key === "questions") {
@@ -162,7 +171,7 @@ function mergeQuestions(base, override) {
       continue
     }
     const merged = { ...current, ...question }
-    if (question.criteria) merged.criteria = { ...question.criteria }
+    if (question.type && question.type !== current.type && !Object.hasOwn(question, "criteria")) delete merged.criteria
     byName.set(question.name, merged)
   }
   return [...byName.values()]

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)
@@ -133,8 +138,8 @@ export function hostMatches(host, patterns) {
  * complete configuration and effective credentials isolate instances with
  * different policies or judge requests. The state captures staged content.
  */
-export function scopedCacheKey(config, tool, args, state, apiKey, staged, scope) {
-  return createHash("sha256").update(stableStringify({ config, tool, args, state, apiKey, staged, scope })).digest("hex")
+export function scopedCacheKey(config, tool, args, state, apiKey, staged, scope, fallbackApiKey) {
+  return createHash("sha256").update(stableStringify({ config, tool, args, state, apiKey, fallbackApiKey, staged, scope })).digest("hex")
 }
 
 function stableStringify(value) {
@@ -174,7 +179,7 @@ function stringifySafely(value, seen) {
 }
 
 export class GuardDecision {
-  constructor({ verdict, reason, probability, confidence, tool, hosts, durationMs, mode, state, stop = false }) {
+  constructor({ verdict, reason, probability, confidence, tool, hosts, durationMs, mode, state, stop = false, source }) {
     this.verdict = verdict
     this.reason = reason
     this.probability = probability
@@ -185,6 +190,7 @@ export class GuardDecision {
     this.mode = mode
     this.state = state
     this.stop = stop
+    this.source = source
   }
 
   get blocked() {
@@ -210,6 +216,8 @@ export function createGuard(config, deps = {}) {
     const fromEnv = process.env[config.apiKeyEnv]
     if (fromEnv) apiKey = fromEnv
   }
+  let fallbackApiKey = config.fallback?.apiKey
+  if (config.fallback?.apiKeyEnv && process.env[config.fallback.apiKeyEnv]) fallbackApiKey = process.env[config.fallback.apiKeyEnv]
 
   function cacheGet(key) {
     if (!config.cacheEnabled) return undefined
@@ -241,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) {
@@ -257,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.`,
@@ -271,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.`,
@@ -282,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.`,
@@ -293,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
@@ -342,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,
@@ -358,7 +368,7 @@ export function createGuard(config, deps = {}) {
     }
 
     const staged = referencedWrites(fullText(tool, args), directory, scope).map(hit => snapshots.get(hit.path) ?? getWrite(hit.path, undefined, scope))
-    const key = scopedCacheKey(config, tool, args, state, apiKey, staged, scope)
+    const key = scopedCacheKey(config, tool, args, state, apiKey, staged, scope, fallbackApiKey)
     const cached = cacheGet(key)
     if (cached?.pending) {
       const decision = await cached.pending
@@ -400,8 +410,9 @@ export function createGuard(config, deps = {}) {
 
   async function evaluateWithJudge({ tool, args, state, hosts, started }) {
     let response
+    let source = "primary"
     try {
-      response = await requestDecision({
+      const request = {
         endpoint: config.endpoint,
         model: config.model,
         state,
@@ -409,7 +420,14 @@ export function createGuard(config, deps = {}) {
         timeoutMs: config.timeoutMs,
         apiKey,
         fetchImpl,
-      })
+      }
+      try {
+        response = await requestDecision(request)
+      } catch (error) {
+        if (!(error instanceof JudgeError) || error.kind !== "timeout" || !config.fallback) throw error
+        source = "fallback"
+        response = await requestDecision({ ...request, ...config.fallback, apiKey: fallbackApiKey })
+      }
     } catch (error) {
       const message = error instanceof JudgeError && ["http", "malformed", "timeout", "network", "unavailable"].includes(error.kind) ? `judge ${error.kind} error` : "judge error"
       const blocked = config.failMode === "block"
@@ -468,6 +486,7 @@ export function createGuard(config, deps = {}) {
       hosts,
       durationMs: now() - started,
       mode: "judge",
+      source,
       state,
       stop: config.stopThreshold !== null && Number.isFinite(probability) && probability >= config.stopThreshold,
     })

package/src/judge.js

@@ -21,7 +21,7 @@
  *   guard reads the probability of the option named by the question's
  *   `denyLabel`.
  * - `noul` normally returns P(true); llama.cpp's LEV returns a normalized
- *   expected rating instead. The criteria must be
+ *   expected rating instead. Optional criteria must be
  *   exactly the `true`/`false` pair, and `denyLabel` says which of the two
  *   means "this is a violation" — `denyLabel: "true"` when `true` is the
  *   violation, `denyLabel: "false"` when the violation is the negative
@@ -59,8 +59,8 @@ export function buildRequest(model, state, questions) {
   const payload = {}
   for (const question of questions) {
     const body = { type: question.type, instructions: question.instructions }
-    if (question.type === "noul" || question.type === "choice") {
-      body.criteria = question.criteria ?? {}
+    if ((question.type === "noul" || question.type === "choice") && question.criteria !== undefined) {
+      body.criteria = question.criteria
     }
     if (question.type === "score") {
       body.criteria = question.levels ?? []
@@ -121,7 +121,7 @@ export function denyProbability(question, answer) {
 
   if (question?.type === "noul") {
     const denyLabel = findDenyOption(question)
-    if (!denyLabel) return undefined
+    if (denyLabel !== "true" && denyLabel !== "false") return undefined
     // The affirmative label must be resolvable, otherwise the server's
     // probability could not be attributed to either side.
     const affirmative = resolveAffirmativeLabel(question)
@@ -144,13 +144,14 @@ export function denyProbability(question, answer) {
 /**
  * The label a `noul` question treats as affirmative.
  *
- * A `noul` question carries exactly the criteria `true` and `false`, and the
- * server derives the affirmative from those keys — it is always `true`.
- * The function returns undefined for anything else, because a probability
- * that cannot be attributed to either side would invert the verdict.
+ * A `noul` question has implicit true/false labels when criteria are absent.
+ * Explicit criteria must contain exactly those two keys.
  */
 export function resolveAffirmativeLabel(question) {
-  const criteria = question?.criteria ?? {}
+  if (!question || question.type !== "noul") return undefined
+  const criteria = question.criteria
+  if (criteria === undefined) return "true"
+  if (!criteria || typeof criteria !== "object" || Array.isArray(criteria) || Object.keys(criteria).length !== 2) return undefined
   if (!Object.hasOwn(criteria, "true")) return undefined
   if (!Object.hasOwn(criteria, "false")) return undefined
   return "true"
@@ -173,47 +174,49 @@ export async function requestDecision(options) {
   if (options.apiKey) headers.Authorization = `Bearer ${options.apiKey}`
 
   const controller = new AbortController()
-  const timer = setTimeout(() => controller.abort(), options.timeoutMs)
+  let timer
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new JudgeError(`Judge request timed out after ${options.timeoutMs}ms`, { kind: "timeout" }))
+      controller.abort()
+    }, options.timeoutMs)
+  })
   try {
-    const response = await fetchImpl(options.endpoint, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(payload),
-      signal: controller.signal,
-    })
-
-    const text = await response.text()
-
-    if (!response.ok) {
-      throw new JudgeError(`Judge returned HTTP ${Number.isInteger(response.status) ? response.status : "error"}`, {
-        kind: "http",
+    const operation = async () => {
+      const response = await fetchImpl(options.endpoint, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: controller.signal,
       })
-    }
 
-    let body
-    try {
-      body = JSON.parse(text)
-    } catch (error) {
-      throw new JudgeError("Judge returned invalid JSON", {
-        kind: "malformed",
-        cause: error,
-      })
+      if (!response.ok) {
+        throw new JudgeError(`Judge returned HTTP ${Number.isInteger(response.status) ? response.status : "error"}`, {
+          kind: "http",
+        })
+      }
+
+      const text = await response.text()
+      let body
+      try {
+        body = JSON.parse(text)
+      } catch (error) {
+        throw new JudgeError("Judge returned invalid JSON", {
+          kind: "malformed",
+          cause: error,
+        })
+      }
+
+      if (!body || typeof body.answers !== "object" || body.answers === null) {
+        throw new JudgeError("Judge response is missing an `answers` object", { kind: "malformed" })
+      }
+
+      return body
     }
-
-    if (!body || typeof body.answers !== "object" || body.answers === null) {
-      throw new JudgeError("Judge response is missing an `answers` object", { kind: "malformed" })
-    }
-
-    return body
+    return await Promise.race([operation(), timeout])
   } catch (error) {
     if (error instanceof JudgeError) throw error
-    const aborted = error?.name === "AbortError"
-    throw new JudgeError(
-      aborted
-        ? `Judge request timed out after ${options.timeoutMs}ms`
-        : "Judge request failed",
-      { kind: aborted ? "timeout" : "network", cause: error },
-    )
+    throw new JudgeError("Judge request failed", { kind: "network", cause: error })
   } finally {
     clearTimeout(timer)
   }

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)
+    },
+  }
+}