@openviking/opencode-plugin 2026.9.9 → 2026.9.21-1

package/lib/shared/plugin-config.mjs

@@ -0,0 +1,300 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+/**
+ * Per-harness plugin settings from ovcli.conf.
+ *
+ * ovcli.conf carried connection fields only, so every harness had to keep its
+ * tuning knobs in ov.conf's harness section — a server-side file that a
+ * client-side plugin has no business editing. The `plugin` section fixes that:
+ * shared keys apply to every harness that reads them, and a per-harness object
+ * overrides them.
+ *
+ *   {
+ *     "url": "...", "api_key": "...",
+ *     "plugin": {
+ *       "recallQueryExpansion": "off",
+ *       "recallCompress": "auto"
+ *     }
+ *   }
+ *
+ * Resolution stays env → ovcli.conf plugin.<harness> → ovcli.conf plugin →
+ * ov.conf harness section (legacy) → defaults.
+ *
+ * Every harness resolves through `resolveSettings()` below, and assembles its
+ * whole configuration through `buildPluginConfig()`, so one `plugin` section
+ * configures all of them and `ov config switch` moves behaviour along with
+ * credentials. The knobs themselves are declared once in `config-schema.mjs`;
+ * this module decides which files supply them and what is derived from them.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { HARNESS_KEYS, KNOBS, harnessKey, resolveKnobs } from "./config-schema.mjs";
+import {
+  buildUserAgent,
+  loadCredentialFiles,
+  readManifestVersion,
+  resolveConnection,
+} from "./credentials.mjs";
+import {
+  announcedOverrides,
+  loadWorkspaceLayers,
+  mergeConfigLayers,
+  normalizeWorkspaceConfig,
+  projectWorkspaceSettings,
+} from "./workspace-config.mjs";
+import { findWorkspaceRoot, resolveWorkspaceIdentity } from "./workspace-identity.mjs";
+import { resolveEffectivePeerId, resolvePluginPeerId } from "./workspace-peer.mjs";
+import { readEntry } from "./workspace-registry.mjs";
+
+const OVCLI_LAYER = "ovcli.conf";
+const OV_CONF_LAYER = "ov.conf";
+
+export { HARNESS_KEYS, harnessKey };
+
+/**
+ * Merge the shared plugin section with the harness-specific override.
+ * Returns a flat settings object; unknown keys pass through untouched so a
+ * harness can add its own knobs without touching this module.
+ *
+ * `cliFile` is ovcli.conf already parsed. Callers that have it hand it over so
+ * the file is read once per build and, more importantly, so the `plugin`
+ * section comes out of the same file the credential chain read — an
+ * `OPENVIKING_CONFIG_FILE` that is ovcli-shaped is ovcli.conf, and only
+ * `loadCredentialFiles` knows that.
+ */
+export function loadPluginSettings(harness, env = process.env, options = {}) {
+  const file = options.cliFile || loadCredentialFiles(env).cliFile;
+  const plugin = file && typeof file.plugin === "object" && file.plugin ? file.plugin : {};
+
+  const shared = {};
+  for (const [key, value] of Object.entries(plugin)) {
+    if (value && typeof value === "object" && !Array.isArray(value)) continue;
+    shared[key] = value;
+  }
+  // Both spellings of the harness name find the same override, so copying
+  // `claude-code` out of the installer is not a silent no-op.
+  const key = harnessKey(harness);
+  const scoped = {};
+  for (const candidate of [key, key.replace(/_/g, "-")]) {
+    const value = candidate && plugin[candidate];
+    if (value && typeof value === "object" && !Array.isArray(value)) Object.assign(scoped, value);
+  }
+
+  const settings = { ...shared, ...scoped };
+  const cwd = String(options.cwd || "").trim();
+  if (!cwd) return settings;
+  return { ...settings, ...resolveWorkspaceSettings(cwd, env, options).settings };
+}
+
+/**
+ * Every knob for one harness, resolved through the whole layer stack.
+ *
+ * `legacy` is that harness's section in ov.conf, which is where tuning used to
+ * live: it stays the lowest configured layer so an existing deployment keeps
+ * working, and everything above it comes from files a client may edit.
+ *
+ * Returns the settings, the names some layer actually supplied (what the
+ * `*Configured` flags report), and the raw ovcli.conf merge — a couple of
+ * callers still need to know a value came from ovcli.conf rather than ov.conf.
+ */
+export function resolveSettings(harness, options = {}) {
+  const { env = process.env, cwd = "", legacy = {}, clientVersion = "", cliFile = null } = options;
+  const key = harnessKey(harness);
+  const plugin = loadPluginSettings(key, env, { cwd, clientVersion, cliFile });
+  const { settings, configured, sources } = resolveKnobs({
+    harness: key,
+    layers: [
+      { name: OV_CONF_LAYER, data: legacy },
+      { name: OVCLI_LAYER, data: plugin },
+    ],
+    env,
+  });
+  return { settings, configured, sources, plugin };
+}
+
+/**
+ * The workspace layers for one cwd, flattened into harness knobs.
+ *
+ * Takes the cwd explicitly because a hook's `loadConfig()` runs at module top
+ * level, before the payload on stdin has said which directory the session is
+ * actually in — the caller resolves this again once it knows.
+ */
+export function resolveWorkspaceSettings(cwd, env = process.env, { clientVersion = "" } = {}) {
+  const empty = { settings: {}, root: "", provenance: {}, warnings: [], announced: [] };
+  try {
+    const { root } = findWorkspaceRoot(cwd, env);
+    if (!root) return empty;
+
+    const { layers, warnings } = loadWorkspaceLayers(root, { clientVersion });
+    // The identity is what makes the registry's negative evidence work: without
+    // it a directory reused by a different repository inherits the old peer.
+    const identity = resolveWorkspaceIdentity({ cwd, env });
+    const registry = readEntry(root, { identity, env });
+    warnings.push(...registry.warnings);
+    if (registry.entry?.settings) layers.push({ layer: "registry", data: registry.entry.settings });
+    if (registry.entry?.peer) layers.push({ layer: "registry", data: { peer: registry.entry.peer } });
+    if (!layers.length) return { ...empty, root, warnings };
+
+    const { value, provenance } = mergeConfigLayers(layers, warnings);
+    normalizeWorkspaceConfig(value, warnings);
+    return {
+      settings: projectWorkspaceSettings(value),
+      root,
+      provenance,
+      warnings,
+      announced: announcedOverrides(provenance),
+      value,
+    };
+  } catch {
+    // A hook must never die over a config file. An unreadable layer is no layer.
+    return empty;
+  }
+}
+
+const SEND_ONLY_WHEN_CONFIGURED = KNOBS.filter((knob) => knob.sendOnlyWhenConfigured);
+
+function str(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : "";
+}
+
+/** The ov.conf block named after this harness, the lowest layer of every chain. */
+function ovConfSection(ovFile, key) {
+  const section = key ? ovFile?.[key] : null;
+  return section && typeof section === "object" && !Array.isArray(section) ? section : {};
+}
+
+/**
+ * One harness's whole configuration: the files, the knobs, the peer, and the
+ * handful of fields derived from them.
+ *
+ * Every loader used to write this sequence out by hand and each wrote a
+ * slightly different subset, which is how ov.conf's `<harness>.authMode` came
+ * to apply on three harnesses only, and why two of the four knobs the server
+ * defaults for itself were reported as configured on two harnesses and nowhere
+ * else. What is left in a loader after this call is what only that harness
+ * knows.
+ *
+ * The connection — server, key, identity, auth mode — is not a knob: it comes
+ * from `resolveConnection`, the same call an MCP proxy's connection comes
+ * from, and the `plugin` keys and ov.conf block that name it are read there.
+ *
+ * `legacy` replaces the ov.conf block this harness would otherwise get for its
+ * knobs (dsh's host hands it one of its own); `hostInput` is what an embedding
+ * host named for this process, which is the more specific answer and outranks
+ * every file; `logFile` is the log basename this harness has always used, and
+ * a harness that never had a default log path does not get one invented for
+ * it; `rootKeyFallback` is for the harnesses whose chain predates the ovcli.conf
+ * pinning and has always ended at `server.root_api_key`.
+ */
+export function buildPluginConfig(harness, {
+  cwd = "",
+  env = process.env,
+  legacy = null,
+  manifestUrl = "",
+  version = "",
+  hostInput = {},
+  logFile = "",
+  rootKeyFallback = false,
+  deriveEffectivePeer = false,
+} = {}) {
+  const name = String(harness || "");
+  const key = harnessKey(name);
+  const workspaceCwd = str(cwd) || process.cwd();
+  const files = loadCredentialFiles(env);
+  // The version answers two questions: what the User-Agent reports, and whether
+  // a workspace file asking for a newer client gets to say so.
+  const clientVersion = str(version) || (manifestUrl ? readManifestVersion(manifestUrl) : "");
+  const { settings, configured, sources } = resolveSettings(key, {
+    env,
+    cwd: workspaceCwd,
+    legacy: legacy || ovConfSection(files.ovFile, key),
+    cliFile: files.cliFile,
+    clientVersion,
+  });
+  const connection = resolveConnection(key, { env, files, hostInput, rootKeyFallback });
+  const { baseUrl, account, user } = connection;
+  const timeoutMs = settings.timeoutMs;
+  const peerId = resolvePluginPeerId({
+    settings,
+    configured,
+    sources,
+    credentials: connection,
+    hostInput: hostInput?.peerId,
+    env,
+  });
+
+  const config = {
+    ...settings,
+    harness: name,
+    clientVersion,
+    userAgent: buildUserAgent(name, clientVersion),
+
+    baseUrl,
+    mcpUrl: connection.mcpUrl,
+    apiKey: connection.apiKey,
+    account,
+    user,
+    authMode: connection.authMode,
+    sendIdentityHeaders: connection.sendIdentityHeaders,
+
+    credentialSource: connection.credentialSource,
+    apiKeySource: connection.apiKeySource,
+    credentialPath: connection.credentialPath,
+    hasApiKey: connection.hasApiKey,
+    configPath: connection.cliPath || connection.ovPath || null,
+    cliConfigPath: connection.cliPath,
+    ovConfigPath: connection.ovPath,
+    cliPath: connection.cliPath,
+    ovPath: connection.ovPath,
+
+    peerId,
+    explicitPeerId: peerId,
+
+    // A write gets a longer budget than a read, and a digest has to finish
+    // inside the recall request it belongs to, so both fall back to a knob.
+    captureTimeoutMs: settings.captureTimeoutMs || Math.max(timeoutMs * 2, 30000),
+    recallCompressTimeoutMs: settings.recallCompressTimeoutMs
+      || Math.max(1000, settings.recallTimeoutMs - 10000),
+    debugLogPath: settings.debugLogPath
+      || (logFile ? join(homedir(), ".openviking", "logs", logFile) : ""),
+
+    // The spellings these fields carried before every harness shared a loader.
+    endpoint: baseUrl,
+    accountId: account,
+    userId: user,
+    requestTimeoutMs: timeoutMs,
+  };
+  for (const knob of SEND_ONLY_WHEN_CONFIGURED) {
+    config[`${knob.name}Configured`] = configured.has(knob.name);
+  }
+
+  // Only for the harnesses that resolve the peer once at load. The rest derive
+  // it per session, against the directory the payload names, and an MCP proxy
+  // must not derive one from wherever it happened to be launched.
+  if (deriveEffectivePeer) {
+    const effectivePeer = resolveEffectivePeerId({ cfg: config, cwd: workspaceCwd, env });
+    config.effectivePeer = effectivePeer;
+    config.legacyPeerId = effectivePeer.legacyPeerId;
+  }
+  return config;
+}
+
+const REWRITE_MODES = new Set(["off", "client", "server", "auto"]);
+
+/**
+ * Normalize the tri-state rewrite knob.
+ *
+ * off    — never compress
+ * client — always compress locally through the host CLI
+ * server — always ask the server for a digest
+ * auto   — prefer local (cost lands on the user's own subscription), fall back
+ *          to the server when no healthy host CLI is available
+ */
+export function normalizeRewriteMode(value, fallback = "off") {
+  const raw = String(value ?? "").trim().toLowerCase();
+  if (REWRITE_MODES.has(raw)) return raw;
+  if (raw === "1" || raw === "true" || raw === "yes") return "auto";
+  if (raw === "0" || raw === "false" || raw === "no") return "off";
+  return fallback;
+}

package/lib/shared/recall-core.mjs

@@ -31,6 +31,28 @@ const CODING_QUOTA_WEIGHTS = {
 
 let userSpaceCache = "";
 
+/**
+ * Is recall on for this config?
+ *
+ * The switch has four spellings in the wild: a boolean `autoRecall`, opencode's
+ * `{ enabled }` object, dsh and pi's `syncTurns`, and the global `enabled`
+ * that turns the whole plugin off. Reading it here rather than in each loader
+ * is what keeps it from drifting a fifth time — and any spelling that says off
+ * wins, so a config that disables recall under an older name still disables it.
+ */
+export function isRecallEnabled(cfg = {}) {
+  return isSwitchOn([cfg.enabled, cfg.autoRecall, cfg.recall, cfg.syncRecall]);
+}
+
+/** Any recognised spelling that says off wins; everything else means on. */
+function isSwitchOn(values) {
+  for (const value of values) {
+    if (value === false) return false;
+    if (value && typeof value === "object" && !Array.isArray(value) && value.enabled === false) return false;
+  }
+  return true;
+}
+
 export function estimateTokens(text) {
   return text ? Math.ceil(String(text).length / 4) : 0;
 }
@@ -338,9 +360,8 @@ async function resolveItemContent(fetchJSON, item, cfg, actorPeerId = "") {
 }
 
 async function buildFallbackInjectionBlock(fetchJSON, items, cfg, actorPeerId = "", log = () => {}) {
-  if (items.length === 0) return null;
-
-  let budgetRemaining = Math.max(200, Number(cfg.recallTokenBudget || 2000));
+  const budgetTotal = Math.max(200, Number(cfg.recallTokenBudget || 2000));
+  let budgetRemaining = budgetTotal;
   const lines = [
     "<openviking-context>",
     "Relevant context from OpenViking. Use the read MCP tool to expand URIs.",
@@ -373,15 +394,15 @@ async function buildFallbackInjectionBlock(fetchJSON, items, cfg, actorPeerId =
 
   lines.push("</openviking-context>");
 
-  const budgetUsed = Math.max(200, Number(cfg.recallTokenBudget || 2000)) - budgetRemaining;
+  const budgetUsed = budgetTotal - budgetRemaining;
   log("recall_injection_built", {
     contentItems: contentCount,
     hintItems: hintCount,
     budgetUsed,
-    budgetTotal: Math.max(200, Number(cfg.recallTokenBudget || 2000)),
+    budgetTotal,
   });
 
-  return lines.join("\n");
+  return { block: lines.join("\n"), contentCount, hintCount, budgetUsed, stage: "ranked" };
 }
 
 const LEGACY_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
@@ -626,8 +647,13 @@ export async function postRecall(fetchJSON, body, opts = {}) {
  * `"actor"` that sweep is off by definition, so the old peer is asked for
  * separately — as itself, which is both cheaper and wider than a bare
  * cross-peer read (that would need the user id, and reaches memories only).
+ *
+ * `stage` names the path the block came from, which is what a host needs to
+ * tell "the server had nothing" (`no_results`) from "the score threshold
+ * dropped everything" (`filtered_out`) when the block is empty, and a
+ * `server_assembled` block from a `ranked` one when it is not.
  */
-export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
+export async function buildRecallBlockDetailed(fetchJSON, cfg, query, options = {}) {
   const primary = await recallForPeer(fetchJSON, cfg, query, options);
 
   const legacyPeerId = String(options.legacyPeerId || "").trim();
@@ -636,16 +662,32 @@ export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
 
   const log = options.log || (() => {});
   const legacy = await recallForPeer(fetchJSON, cfg, query, { ...options, actorPeerId: legacyPeerId });
-  if (!legacy) return primary;
+  if (!legacy.block) return primary;
   log("recall_legacy_peer_hit", { legacyPeerId });
-  return primary ? `${primary}\n${legacy}` : legacy;
+  return {
+    block: primary.block ? `${primary.block}\n${legacy.block}` : legacy.block,
+    contentCount: primary.contentCount + legacy.contentCount,
+    hintCount: primary.hintCount + legacy.hintCount,
+    budgetUsed: primary.budgetUsed + legacy.budgetUsed,
+    stage: primary.block ? primary.stage : legacy.stage,
+  };
+}
+
+/** The block alone, or null when nothing was injectable. */
+export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
+  const { block } = await buildRecallBlockDetailed(fetchJSON, cfg, query, options);
+  return block || null;
+}
+
+function emptyRecall(stage) {
+  return { block: "", contentCount: 0, hintCount: 0, budgetUsed: 0, stage };
 }
 
 async function recallForPeer(fetchJSON, cfg, query, options = {}) {
   const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";
   const log = options.log || (() => {});
   const trimmed = String(query || "").trim();
-  if (!trimmed) return null;
+  if (!trimmed) return emptyRecall("no_results");
 
   // Assembly happens server-side when the deployment offers the context face;
   // older servers fall through to /recall, then to raw find.
@@ -654,12 +696,23 @@ async function recallForPeer(fetchJSON, cfg, query, options = {}) {
     actorPeerId,
     log,
   });
-  if (serverBlock !== null) return serverBlock || null;
+  if (serverBlock !== null) {
+    if (!serverBlock) return emptyRecall("no_results");
+    // The server rendered one budgeted unit, so nothing here degraded to a
+    // URI-only hint and the block's own estimate is what it cost.
+    return {
+      block: serverBlock,
+      contentCount: 1,
+      hintCount: 0,
+      budgetUsed: estimateTokens(serverBlock),
+      stage: "server_assembled",
+    };
+  }
 
   const recallLimit = Math.max(1, Number(cfg.recallLimit || DEFAULT_CONTEXT_LIMIT));
   const perSourceLimit = Math.max(recallLimit * 2, 8);
   const raw = await searchAllSources(fetchJSON, trimmed, perSourceLimit, actorPeerId, log);
-  if (raw.length === 0) return null;
+  if (raw.length === 0) return emptyRecall("no_results");
 
   const profile = buildQueryProfile(trimmed);
   const scoreThreshold = Number.isFinite(Number(cfg.scoreThreshold)) ? Number(cfg.scoreThreshold) : 0.35;
@@ -673,6 +726,6 @@ async function recallForPeer(fetchJSON, cfg, query, options = {}) {
     items: picked.map((it) => ({ type: it._sourceType, uri: it.uri, score: clampScore(it.score) })),
   });
 
-  if (picked.length === 0) return null;
+  if (picked.length === 0) return emptyRecall("filtered_out");
   return buildFallbackInjectionBlock(fetchJSON, picked, cfg, actorPeerId, log);
 }

package/lib/shared/uri-guard.mjs

@@ -1,4 +1,8 @@
 // GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+import { readFileSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
 const DEFAULT_URI_KEYS = [
   "filePath",
   "file_path",
@@ -7,7 +11,6 @@ const DEFAULT_URI_KEYS = [
   "uri",
   "target_uri",
   "targetUri",
-  "pattern",
 ];
 
 export function normalizeToolName(value) {
@@ -76,3 +79,172 @@ export function buildGuardMessage(uri, hint = {}) {
   if (example) lines.push(`Example: ${example}`);
   return lines.join("\n");
 }
+
+export function buildGuardNotice(uri, hint = {}) {
+  const lines = [
+    `[OpenViking memory plugin] URI guard: this shell command contains the viking:// URI ${uri}.`,
+    "viking:// URIs are OpenViking virtual paths, not local files, so cat, ls, grep and other file commands cannot open them.",
+    `If you meant to read or search OpenViking content, use ${hint.tool || "the OpenViking MCP tools"} instead.`,
+  ];
+  if (hint.example) lines.push(`Example: ${hint.example}`);
+  lines.push("If the URI is intentional data (an ov CLI argument, an HTTP payload, a search pattern), ignore this notice.");
+  return lines.join("\n");
+}
+
+/** The hints a host gets when it names no table of its own. */
+export const DEFAULT_TOOL_HINTS = {
+  read: {
+    tool: "OpenViking MCP read",
+    example: (uri) => `read(uris="${uri}")`,
+  },
+  glob: {
+    tool: "OpenViking MCP glob or list",
+    example: (uri, input = {}) => (
+      `glob(pattern="${String(input.pattern ?? "**/*").replaceAll('"', '\\"')}", uri="${uri}")`
+    ),
+  },
+  grep: {
+    tool: "OpenViking MCP grep or search",
+    example: (uri, input = {}) => (
+      `grep(uri="${uri}", pattern="${String(input.pattern ?? "").replaceAll('"', '\\"')}")`
+    ),
+  },
+  edit: {
+    tool: "OpenViking MCP edit",
+    example: (uri) => `edit(uri="${uri}", old_string="...", new_string="...")`,
+  },
+  write: {
+    tool: "OpenViking MCP write",
+    example: (uri) => `write(uri="${uri}", content="...")`,
+  },
+  bash: {
+    tool: "OpenViking MCP read or search",
+    example: (uri) => `read(uris="${uri}")`,
+  },
+  runcommand: {
+    tool: "OpenViking MCP read or search",
+    example: (uri) => `read(uris="${uri}")`,
+  },
+  shell: {
+    tool: "OpenViking MCP read or search",
+    example: (uri) => `read(uris="${uri}")`,
+  },
+};
+
+// Tools whose argument is a command line rather than a location. A viking:// URI
+// in one is data (an `ov` argument, an HTTP payload, a grep pattern) as often as
+// a path the model hoped to open, so the command runs and the model gets a notice.
+const SHELL_TOOL_NAMES = new Set(["bash", "shell", "runcommand"]);
+
+// `pattern` is where glob looks but what grep looks for: a grep for the text
+// "viking://" in a local tree is not a path. The generic sweep still reaches
+// glob's pattern.
+const TEXT_ARGS_BY_TOOL = { grep: ["pattern"] };
+
+function resolveGuardedUri(toolName, input, { hints = DEFAULT_TOOL_HINTS } = {}) {
+  const name = normalizeToolName(toolName);
+  const hint = hints[name];
+  if (!hint) return null;
+  const textArgs = TEXT_ARGS_BY_TOOL[name];
+  const uri = findVikingUri(input, DEFAULT_URI_KEYS, textArgs ? [...DEFAULT_CONTENT_KEYS, ...textArgs] : DEFAULT_CONTENT_KEYS);
+  if (!uri) return null;
+  return {
+    uri,
+    shell: SHELL_TOOL_NAMES.has(name),
+    hint: {
+      tool: hint.tool,
+      example: typeof hint.example === "function" ? hint.example(uri, input) : hint.example,
+    },
+  };
+}
+
+/**
+ * The deny decision for one tool call, or null when the call may proceed.
+ *
+ * A file tool whose path is a viking:// URI cannot succeed, and a write would
+ * leave a junk local file, so it is denied. A shell tool is never denied here;
+ * `evaluateUriNotice` covers it. `hints` carries the host's replacement tool
+ * names and example calls, and a tool without a hint is not guarded.
+ */
+export function evaluateUriGuard(toolName, input = {}, opts = {}) {
+  const match = resolveGuardedUri(toolName, input, opts);
+  if (!match || match.shell) return null;
+  return { uri: match.uri, reason: buildGuardMessage(match.uri, match.hint) };
+}
+
+/** The notice for a shell command that carries a viking:// URI, or null. The command still runs. */
+export function evaluateUriNotice(toolName, input = {}, opts = {}) {
+  const match = resolveGuardedUri(toolName, input, opts);
+  if (!match?.shell) return null;
+  return { uri: match.uri, reason: buildGuardNotice(match.uri, match.hint) };
+}
+
+/** The PreToolUse deny envelope claude-code, trae and zcode all read. */
+export function denyHookSpecificOutput(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+/** The PreToolUse notice envelope: no permissionDecision, so the host's own permission flow still runs. */
+export function noticeHookSpecificOutput(reason) {
+  return { hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: reason } };
+}
+
+/** A hook event's tool name and input, under any of the spellings the hosts use. */
+export function readToolEvent(event = {}) {
+  return {
+    toolName: event.tool_name ?? event.toolName ?? event.name ?? event.tool,
+    toolInput: event.tool_input ?? event.toolInput ?? event.input ?? {},
+  };
+}
+
+/** The whole PreToolUse guard: a deny envelope, a notice envelope, or {}. */
+export function preToolUseOutput(event = {}, opts = {}) {
+  const { toolName, toolInput } = readToolEvent(event);
+  const denied = evaluateUriGuard(toolName, toolInput, opts);
+  if (denied) return denyHookSpecificOutput(denied.reason);
+  const notice = evaluateUriNotice(toolName, toolInput, opts);
+  return notice ? noticeHookSpecificOutput(notice.reason) : {};
+}
+
+/** Cursor's beforeReadFile deny envelope. */
+export function denyCursorPermission(reason) {
+  return { permission: "deny", user_message: reason };
+}
+
+function readHookInput() {
+  try {
+    const raw = readFileSync(0, "utf8").trim();
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Run a guard as a hook process: read the event off stdin, print the envelope.
+ *
+ * A guard is also imported by its harness tests, so the body only runs when the
+ * module is the process entrypoint. An empty envelope prints nothing — every
+ * host treats unrecognized or empty output as "no opinion", and one of them
+ * rejects any key it does not know.
+ */
+function isEntrypoint(moduleUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return resolve(process.argv[1]) === fileURLToPath(moduleUrl);
+  }
+}
+
+export function runUriGuardHook(moduleUrl, evaluate) {
+  if (!isEntrypoint(moduleUrl)) return;
+  const output = evaluate(readHookInput());
+  if (Object.keys(output).length > 0) process.stdout.write(`${JSON.stringify(output)}\n`);
+}