@fusengine/harness 0.1.89 → 0.1.91

package/src/adapters/cursor/events.ts

@@ -0,0 +1,38 @@
+import type { CursorEventContract } from "./interfaces/types";
+
+const EVENT_CONTRACTS = {
+  sessionStart: { phase: "pre", lifecycle: "SessionStart", response: "session-context", blockable: false, known: true },
+  sessionEnd: { phase: "post", lifecycle: "SessionEnd", response: "neutral", blockable: false, known: true },
+  beforeSubmitPrompt: { phase: "pre", lifecycle: "UserPromptSubmit", response: "submit-control", blockable: true, known: true },
+  preCompact: { phase: "pre", lifecycle: "PreCompact", response: "compact-notice", blockable: false, known: true },
+  subagentStart: { phase: "pre", lifecycle: "SubagentStart", response: "permission", blockable: true, known: true },
+  subagentStop: { phase: "post", lifecycle: "SubagentStop", response: "followup", blockable: false, known: true },
+  preToolUse: { phase: "pre", lifecycle: "PreToolUse", response: "permission", blockable: true, known: true },
+  postToolUse: { phase: "post", lifecycle: "PostToolUse", response: "post-context", blockable: false, known: true },
+  postToolUseFailure: { phase: "post", lifecycle: "PostToolUseFailure", response: "neutral", blockable: false, known: true },
+  beforeShellExecution: { phase: "pre", lifecycle: "BeforeShellExecution", response: "permission", blockable: true, known: true },
+  afterShellExecution: { phase: "post", lifecycle: "AfterShellExecution", response: "neutral", blockable: false, known: true },
+  beforeMCPExecution: { phase: "pre", lifecycle: "BeforeMCPExecution", response: "permission", blockable: true, known: true },
+  afterMCPExecution: { phase: "post", lifecycle: "AfterMCPExecution", response: "neutral", blockable: false, known: true },
+  beforeReadFile: { phase: "pre", lifecycle: "BeforeReadFile", response: "permission", blockable: true, known: true },
+  afterFileEdit: { phase: "post", lifecycle: "AfterFileEdit", response: "neutral", blockable: false, known: true },
+  beforeTabFileRead: { phase: "pre", lifecycle: "BeforeTabFileRead", response: "permission", blockable: true, known: true },
+  afterTabFileEdit: { phase: "post", lifecycle: "AfterTabFileEdit", response: "neutral", blockable: false, known: true },
+  afterAgentResponse: { phase: "post", lifecycle: "AfterAgentResponse", response: "neutral", blockable: false, known: true },
+  afterAgentThought: { phase: "post", lifecycle: "AfterAgentThought", response: "neutral", blockable: false, known: true },
+  stop: { phase: "post", lifecycle: "Stop", response: "followup", blockable: false, known: true },
+  workspaceOpen: { phase: "pre", lifecycle: "WorkspaceOpen", response: "plugin-paths", blockable: false, known: true },
+} as const satisfies Record<string, CursorEventContract>;
+
+const UNKNOWN_EVENT: CursorEventContract = {
+  phase: "post",
+  lifecycle: null,
+  response: "neutral",
+  blockable: false,
+  known: false,
+};
+
+/** Return explicit routing and response metadata for a Cursor event name. */
+export function cursorEventContract(eventName: string): CursorEventContract {
+  return EVENT_CONTRACTS[eventName as keyof typeof EVENT_CONTRACTS] ?? UNKNOWN_EVENT;
+}

package/src/adapters/cursor/index.ts

@@ -0,0 +1,43 @@
+/** Cursor hook adapter; post-edit handling remains observe-only. */
+import { evaluate } from "../../policy/evaluate";
+import { formatPrompt } from "../../prompt/types";
+import { extractCursorEvent } from "./normalize";
+import type { CursorShellPayload, CursorToolPayload, CursorEditPayload, CursorResponse, CursorEditResponse } from "./interfaces/types";
+
+export type { CursorShellPayload, CursorToolPayload, CursorEditPayload, CursorResponse, CursorEditResponse } from "./interfaces/types";
+
+function guardCursor(payload: object): CursorResponse {
+  const event = extractCursorEvent(payload);
+  const result = evaluate({ tool: event.tool, filePath: event.filePath, content: event.content, oldString: event.oldString, command: event.command });
+  if (result.decision === "allow" || !result.prompt) return { permission: "allow" };
+  const message = formatPrompt(result.prompt);
+  const userMessage = result.prompt.kind === "ask"
+    ? `[downgraded from ask — Cursor preToolUse does not reliably enforce ask]\n${message}`
+    : message;
+  return { permission: "deny", user_message: userMessage, agent_message: message };
+}
+
+function namedPayload(payload: object, eventName: string): object {
+  return Object.hasOwn(payload, "hook_event_name") ? payload : { ...payload, hook_event_name: eventName };
+}
+
+/** Guard a shell command (git/install policies). */
+export function beforeShellExecution(payload: CursorShellPayload): CursorResponse {
+  return guardCursor(namedPayload(payload, "beforeShellExecution"));
+}
+
+/** Guard a generic Cursor tool call using the same extraction as the runtime. */
+export function preToolUse(payload: CursorToolPayload): CursorResponse {
+  return guardCursor(namedPayload(payload, "preToolUse"));
+}
+
+/**
+ * Complete an observed file edit without emitting pre-execution permission
+ * fields. Cursor does not define a callback schema for this post hook.
+ * @param payload - The `afterFileEdit` stdin payload.
+ * @returns An empty successful response.
+ */
+export function afterFileEdit(payload: CursorEditPayload): CursorEditResponse {
+  void payload;
+  return {};
+}

package/src/adapters/cursor/interfaces/types.ts

@@ -0,0 +1,88 @@
+/** `beforeShellExecution` stdin payload (subset). */
+export interface CursorShellPayload {
+  command?: string;
+  cwd?: string;
+  sandbox?: boolean;
+  workspace_roots?: string[];
+  hook_event_name?: string;
+}
+
+/** `preToolUse` stdin payload subset consumed by the adapter. */
+export interface CursorToolPayload {
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+}
+
+/** `afterFileEdit` stdin payload (subset). */
+export interface CursorEditPayload {
+  file_path?: string;
+  edits?: { old_string: string; new_string: string }[];
+}
+
+/** One extracted Cursor file edit used by runtime post fan-out. */
+export interface CursorExtractedFile {
+  filePath: string;
+  oldString?: string;
+  content: string;
+  op: "update";
+}
+
+/** Shared Cursor extraction result consumed by runtime and public adapter. */
+export interface CursorExtractedEvent {
+  eventName: string;
+  lifecycleEvent: string | null;
+  responseKind: CursorResponseKind;
+  blockable: boolean;
+  cwd?: string;
+  workspaceRoots?: string[];
+  phase: "pre" | "post";
+  tool: string;
+  input: Record<string, unknown>;
+  filePath?: string;
+  content?: string;
+  oldString?: string;
+  command?: string;
+  /** Distinct beforeMCPExecution root and nested commands, in wire order. */
+  commandCandidates?: string[];
+  files?: CursorExtractedFile[];
+}
+
+/** Native Cursor stdout contract selected for one hook event. */
+export type CursorResponseKind =
+  | "permission"
+  | "post-context"
+  | "session-context"
+  | "submit-control"
+  | "followup"
+  | "compact-notice"
+  | "plugin-paths"
+  | "neutral";
+
+/** Routing metadata for a documented Cursor lifecycle event. */
+export interface CursorEventContract {
+  phase: "pre" | "post";
+  lifecycle: string | null;
+  response: CursorResponseKind;
+  blockable: boolean;
+  known: boolean;
+}
+
+/**
+ * Empty afterFileEdit callback. Cursor documents no output fields for this
+ * post hook, so pre-execution permission fields are intentionally impossible.
+ */
+export type CursorEditResponse = Record<string, never>;
+
+/**
+ * `beforeShellExecution` stdout response. Message keys are snake_case:
+ * Cursor silently ignores camelCase `userMessage`/`agentMessage` (#141516,
+ * regression persists through v2.0.77+ — forum #142589), matching the
+ * schema respond.ts emits for the cursor harness.
+ */
+export interface CursorResponse {
+  permission: "allow" | "deny" | "ask";
+  /** User-visible message — snake_case required (#141516, #142589). */
+  user_message?: string;
+  /** Agent-visible message — snake_case required (#141516, #142589). */
+  agent_message?: string;
+}

package/src/adapters/cursor/native-response.ts

@@ -0,0 +1,158 @@
+type FieldValidator = (value: unknown) => boolean;
+
+interface NativeSchema {
+  fields: Readonly<Record<string, FieldValidator>>;
+  required?: readonly string[];
+}
+
+const stringValue: FieldValidator = (value) => typeof value === "string";
+const booleanValue: FieldValidator = (value) => typeof value === "boolean";
+const plainRecord = (value: unknown): value is Record<string, unknown> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  try {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+  } catch {
+    return false;
+  }
+};
+
+type JsonFrame = { value: unknown; leave?: false } | { value: object; leave: true };
+
+function jsonChildren(value: object): unknown[] | null {
+  const keys = Reflect.ownKeys(value);
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (Array.isArray(value)) {
+    if (Object.getPrototypeOf(value) !== Array.prototype) return null;
+    const length = descriptors.length;
+    if (!length || !("value" in length) || !Number.isSafeInteger(length.value) || length.value < 0) return null;
+    if (keys.length !== length.value + 1 || keys.some((key) => typeof key === "symbol")) return null;
+    const children: unknown[] = [];
+    for (let index = 0; index < length.value; index += 1) {
+      const descriptor = descriptors[String(index)];
+      if (!descriptor?.enumerable || !("value" in descriptor)) return null;
+      children.push(descriptor.value);
+    }
+    return children;
+  }
+  if (!plainRecord(value) || keys.some((key) => typeof key === "symbol")) return null;
+  const children: unknown[] = [];
+  for (const key of keys) {
+    const descriptor = descriptors[key as string];
+    if (!descriptor?.enumerable || !("value" in descriptor)) return null;
+    children.push(descriptor.value);
+  }
+  return children;
+}
+
+function jsonValue(root: unknown): boolean {
+  const active = new WeakSet<object>();
+  const stack: JsonFrame[] = [{ value: root }];
+  while (stack.length > 0) {
+    const frame = stack.pop()!;
+    if (frame.leave) {
+      active.delete(frame.value);
+      continue;
+    }
+    const { value } = frame;
+    if (value === null || typeof value === "string" || typeof value === "boolean") continue;
+    if (typeof value === "number") {
+      if (!Number.isFinite(value)) return false;
+      continue;
+    }
+    if (typeof value !== "object" || active.has(value)) return false;
+    let children: unknown[] | null;
+    try {
+      children = jsonChildren(value);
+    } catch {
+      return false;
+    }
+    if (!children) return false;
+    active.add(value);
+    stack.push({ value, leave: true });
+    for (let index = children.length - 1; index >= 0; index -= 1) stack.push({ value: children[index] });
+  }
+  return true;
+}
+
+const recordValue: FieldValidator = (value) => plainRecord(value) && jsonValue(value);
+const stringRecord: FieldValidator = (value) => {
+  if (!recordValue(value)) return false;
+  try {
+    return Object.values(Object.getOwnPropertyDescriptors(value as object))
+      .every((descriptor) => "value" in descriptor && typeof descriptor.value === "string");
+  } catch {
+    return false;
+  }
+};
+const stringArray: FieldValidator = (value) => Array.isArray(value) && value.every(stringValue);
+const permission = (...values: string[]): FieldValidator => (value) => typeof value === "string" && values.includes(value);
+
+const EMPTY: NativeSchema = { fields: {} };
+const FOLLOWUP: NativeSchema = { fields: { followup_message: stringValue } };
+const PERMISSION_ASK: NativeSchema = {
+  fields: { permission: permission("allow", "deny", "ask"), user_message: stringValue, agent_message: stringValue },
+  required: ["permission"],
+};
+
+const NATIVE_SCHEMAS = {
+  sessionStart: {
+    fields: { env: stringRecord, additional_context: stringValue, continue: booleanValue, user_message: stringValue },
+  },
+  sessionEnd: EMPTY,
+  beforeSubmitPrompt: { fields: { continue: booleanValue, user_message: stringValue }, required: ["continue"] },
+  preCompact: { fields: { user_message: stringValue } },
+  subagentStart: {
+    fields: { permission: permission("allow", "deny"), user_message: stringValue }, required: ["permission"],
+  },
+  subagentStop: FOLLOWUP,
+  preToolUse: {
+    fields: { ...PERMISSION_ASK.fields, updated_input: recordValue }, required: ["permission"],
+  },
+  postToolUse: { fields: { updated_mcp_tool_output: recordValue, additional_context: stringValue } },
+  postToolUseFailure: EMPTY,
+  beforeShellExecution: PERMISSION_ASK,
+  afterShellExecution: EMPTY,
+  beforeMCPExecution: PERMISSION_ASK,
+  afterMCPExecution: EMPTY,
+  beforeReadFile: {
+    fields: { permission: permission("allow", "deny"), user_message: stringValue }, required: ["permission"],
+  },
+  afterFileEdit: EMPTY,
+  beforeTabFileRead: { fields: { permission: permission("allow", "deny") }, required: ["permission"] },
+  afterTabFileEdit: EMPTY,
+  afterAgentResponse: EMPTY,
+  afterAgentThought: EMPTY,
+  stop: FOLLOWUP,
+  workspaceOpen: { fields: { pluginPaths: stringArray } },
+} as const satisfies Record<string, NativeSchema>;
+
+function isNativeCursorResponse(value: unknown, eventName: string): boolean {
+  try {
+    if (!recordValue(value)) return false;
+    const schema = NATIVE_SCHEMAS[eventName as keyof typeof NATIVE_SCHEMAS] as NativeSchema | undefined;
+    if (!schema) return false;
+    const descriptors = Object.getOwnPropertyDescriptors(value as object);
+    if (schema.required?.some((field) => !Object.hasOwn(descriptors, field))) return false;
+    return Reflect.ownKeys(descriptors).every((field) => {
+      if (typeof field !== "string") return false;
+      const descriptor = descriptors[field];
+      if (!Object.hasOwn(schema.fields, field)) return false;
+      const validate = schema.fields[field];
+      return descriptor?.enumerable === true && "value" in descriptor
+        && validate !== undefined && validate(descriptor.value);
+    });
+  } catch {
+    return false;
+  }
+}
+
+/** Preserve raw stdout only when JSON.parse proves a documented native Cursor response. */
+export function parseNativeCursorStdout(stdout: string, eventName: string): string | null {
+  if (typeof stdout !== "string") return null;
+  try {
+    return isNativeCursorResponse(JSON.parse(stdout), eventName) ? stdout : null;
+  } catch {
+    return null;
+  }
+}

package/src/adapters/cursor/normalize.ts

@@ -0,0 +1,123 @@
+import { commandToString } from "../../runtime/command-string";
+import { cursorEventContract } from "./events";
+import { cursorAbsolutePath, cursorPath, cursorWorkspaceRoots } from "./context";
+import type { CursorExtractedEvent } from "./interfaces/types";
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function inputRecord(value: unknown): Record<string, unknown> | undefined {
+  const direct = record(value);
+  if (direct || typeof value !== "string") return direct;
+  try {
+    return record(JSON.parse(value));
+  } catch {
+    return undefined;
+  }
+}
+
+const MCP_ROOT_FIELDS = ["mcp_server_name", "mcp_server_url", "url", "result_json", "duration"] as const;
+
+function cursorMcpInput(raw: Record<string, unknown>, input: Record<string, unknown>): Record<string, unknown> {
+  const merged = { ...input };
+  for (const field of MCP_ROOT_FIELDS) {
+    if (Object.hasOwn(raw, field)) merged[field] = raw[field];
+  }
+  return merged;
+}
+
+function sanitizedCursorInput(input: Record<string, unknown>): Record<string, unknown> {
+  const safe = { ...input };
+  if (typeof safe.file_path === "string" && cursorPath(safe.file_path) === undefined) delete safe.file_path;
+  if (typeof safe.path === "string" && cursorPath(safe.path) === undefined) delete safe.path;
+  if (Object.hasOwn(safe, "cwd")) {
+    const cwd = cursorAbsolutePath(safe.cwd);
+    if (cwd) safe.cwd = cwd;
+    else delete safe.cwd;
+  }
+  if (Object.hasOwn(safe, "workspace_roots")) {
+    if (Array.isArray(safe.workspace_roots)) safe.workspace_roots = cursorWorkspaceRoots(safe.workspace_roots);
+    else delete safe.workspace_roots;
+  }
+  return safe;
+}
+
+function cursorToolName(raw: Record<string, unknown>, event: string, tool: string | undefined, hasCommand: boolean): string {
+  if (hasCommand) return "Bash";
+  const server = str(raw.mcp_server_name)?.trim().replace(/[^A-Za-z0-9_-]+/g, "_");
+  if (/^(before|after)MCPExecution$/i.test(event) && server && tool && !tool.startsWith("mcp__")) {
+    return `mcp__${server}__${tool}`;
+  }
+  if (tool === "Write") return "Edit";
+  return tool ?? "";
+}
+
+function cursorCommands(raw: Record<string, unknown>, input: Record<string, unknown>): string[] {
+  const candidates = [commandToString(raw.command), commandToString(input.command)]
+    .filter((candidate): candidate is string => candidate !== undefined);
+  return [...new Set(candidates)];
+}
+
+/**
+ * Extract one Cursor hook payload into the shared runtime shape.
+ *
+ * @param payload - Cursor hook stdin payload.
+ * @returns Cursor-specific phase, tool, command, and edit fields.
+ */
+export function extractCursorEvent(payload: object): CursorExtractedEvent {
+  const raw = payload as Record<string, unknown>;
+  const hookEvent = str(raw.hook_event_name) ?? "";
+  const parsedInput = inputRecord(raw.tool_input);
+  const mcpInput = parsedInput && /^(before|after)MCPExecution$/i.test(hookEvent)
+    ? cursorMcpInput(raw, parsedInput)
+    : parsedInput;
+  const input = sanitizedCursorInput(mcpInput ?? raw);
+  const contract = cursorEventContract(hookEvent);
+  const metadata = {
+    eventName: hookEvent,
+    lifecycleEvent: contract.lifecycle,
+    responseKind: contract.response,
+    blockable: contract.blockable,
+    cwd: cursorAbsolutePath(raw.cwd),
+    workspaceRoots: cursorWorkspaceRoots(raw.workspace_roots),
+  };
+  if (!contract.known) {
+    return { ...metadata, phase: contract.phase, tool: "", input };
+  }
+  const afterFileEdit = /^afterFileEdit$/i.test(hookEvent);
+  const beforeReadFile = /^beforeReadFile$/i.test(hookEvent);
+  const beforeTabFileRead = /^beforeTabFileRead$/i.test(hookEvent);
+  const edits = Array.isArray(raw.edits)
+    ? raw.edits.map(record).filter((edit): edit is Record<string, unknown> => edit !== undefined)
+    : [];
+  const filePath = cursorPath(raw.file_path);
+  if (filePath && edits.length > 0) {
+    const files = edits.map((edit) => ({
+      filePath,
+      oldString: str(edit.old_string),
+      content: str(edit.new_string) ?? "",
+      op: "update" as const,
+    }));
+    return { ...metadata, phase: contract.phase, tool: "Edit", input, filePath, content: files.map((file) => file.content).join("\n"), files };
+  }
+  const commands = cursorCommands(raw, input);
+  const command = commands[0];
+  return {
+    ...metadata,
+    phase: contract.phase,
+    tool: afterFileEdit ? "Edit" : beforeReadFile || beforeTabFileRead ? "Read" : cursorToolName(raw, hookEvent, str(raw.tool_name), command !== undefined),
+    input,
+    filePath: cursorPath(input.file_path) ?? cursorPath(input.path),
+    content: str(input.content) ?? str(input.new_string),
+    oldString: str(input.old_string),
+    command,
+    commandCandidates: /^beforeMCPExecution$/i.test(hookEvent) && commands.length > 0 ? commands : undefined,
+  };
+}

package/src/adapters/cursor/respond.ts

@@ -0,0 +1,123 @@
+import { formatPrompt, type Prompt } from "../../prompt/types";
+import { cursorEventContract } from "./events";
+import { parseNativeCursorStdout } from "./native-response";
+
+const AGENT_MESSAGE_EVENTS = new Set([
+  "preToolUse",
+  "beforeShellExecution",
+  "beforeMCPExecution",
+]);
+const USER_MESSAGE_EVENTS = new Set([
+  "preToolUse",
+  "beforeShellExecution",
+  "beforeMCPExecution",
+  "beforeReadFile",
+  "subagentStart",
+]);
+
+function permissionMessages(eventName: string, userMessage?: string, agentMessage?: string): Record<string, string> {
+  return {
+    ...(userMessage && USER_MESSAGE_EVENTS.has(eventName) ? { user_message: userMessage } : {}),
+    ...(agentMessage && AGENT_MESSAGE_EVENTS.has(eventName) ? { agent_message: agentMessage } : {}),
+  };
+}
+
+function joinMessages(...values: unknown[]): string {
+  return values.filter((value): value is string => typeof value === "string" && value.length > 0).join("\n");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Render a portable policy prompt using the native Cursor event contract. */
+export function toCursorResponse(prompt: Prompt, eventName: string): string {
+  const contract = cursorEventContract(eventName);
+  const message = formatPrompt(prompt);
+  if (!contract.known || contract.response === "neutral" || contract.response === "plugin-paths") return "{}";
+  if (contract.response === "post-context" || contract.response === "session-context") {
+    return JSON.stringify({ additional_context: message });
+  }
+  if (contract.response === "followup") return JSON.stringify({ followup_message: message });
+  if (contract.response === "compact-notice") return JSON.stringify({ user_message: prompt.userMessage ?? message });
+  if (contract.response === "submit-control") {
+    return JSON.stringify({ continue: prompt.kind !== "block", user_message: prompt.userMessage ?? message });
+  }
+  if (prompt.kind === "inform") {
+    return JSON.stringify({
+      permission: "allow",
+      ...permissionMessages(eventName, prompt.userMessage, prompt.reason ? message : undefined),
+    });
+  }
+  const userMessage = prompt.kind === "ask"
+    ? `[downgraded from ask — Cursor does not enforce approval for this event]\n${message}`
+    : message;
+  return JSON.stringify({
+    permission: "deny",
+    ...permissionMessages(eventName, userMessage, userMessage),
+  });
+}
+
+/** Convert a shared lifecycle handler's output to the native Cursor envelope. */
+export function toCursorLifecycleResponse(stdout: string, eventName: string): string {
+  const contract = cursorEventContract(eventName);
+  const native = parseNativeCursorStdout(stdout, eventName);
+  if (native !== null) return native;
+  let text = stdout;
+  let decision: "allow" | "deny" | "ask" | undefined;
+  let userMessage = "";
+  let agentMessage = "";
+  let decisionMessage = "";
+  let structured = false;
+  try {
+    const parsed: unknown = JSON.parse(stdout);
+    const subagentAsk = eventName === "subagentStart" && isRecord(parsed)
+      && Object.hasOwn(parsed, "permission") && parsed.permission === "ask";
+    const shared = (isRecord(parsed) ? parsed : {}) as {
+      hookSpecificOutput?: {
+        additionalContext?: string;
+        permissionDecision?: "allow" | "deny" | "ask";
+        permissionDecisionReason?: string;
+      };
+      systemMessage?: string;
+      user_message?: string;
+      reason?: string;
+      followup_message?: string;
+    };
+    structured = true;
+    decision = shared.hookSpecificOutput?.permissionDecision ?? (subagentAsk ? "ask" : undefined);
+    userMessage = shared.systemMessage
+      ?? (subagentAsk && Object.hasOwn(shared, "user_message") && typeof shared.user_message === "string"
+        ? shared.user_message : "");
+    decisionMessage = joinMessages(shared.hookSpecificOutput?.permissionDecisionReason, shared.reason);
+    agentMessage = joinMessages(shared.hookSpecificOutput?.additionalContext, decisionMessage);
+    text = joinMessages(agentMessage, userMessage, shared.followup_message);
+  } catch {
+    text = stdout;
+  }
+  if (contract.response === "neutral") return "{}";
+  if (!text) return contract.response === "permission" ? '{"permission":"allow"}' : "{}";
+  if (contract.response === "session-context" || contract.response === "post-context") {
+    return JSON.stringify({ additional_context: text });
+  }
+  if (contract.response === "permission") {
+    const permission = decision === "deny" || decision === "ask" ? "deny" : "allow";
+    const denied = permission === "deny";
+    // Cursor subagentStart can gate creation but has no model-context channel.
+    // Drop shared context and its "injected" notice on allow: preserving either
+    // would claim delivery the native event contract cannot perform.
+    if (eventName === "subagentStart" && !denied) return '{"permission":"allow"}';
+    return JSON.stringify({
+      permission,
+      ...permissionMessages(
+        eventName,
+        userMessage || (denied ? decisionMessage || agentMessage : ""),
+        agentMessage || (denied ? decisionMessage || userMessage : structured ? "" : text),
+      ),
+    });
+  }
+  if (contract.response === "followup") return JSON.stringify({ followup_message: text });
+  if (contract.response === "compact-notice") return JSON.stringify({ user_message: text });
+  if (contract.response === "submit-control") return JSON.stringify({ continue: true, user_message: text });
+  return "{}";
+}

package/src/adapters/gemini/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Gemini CLI adapter (hook-mode). Schema per google-gemini/gemini-cli docs/hooks (2026):
+ * `BeforeTool` blocks via `{ decision: "deny", reason }` (or exit 2).
+ */
+import { evaluate } from "../../policy/evaluate";
+import { formatPrompt } from "../../prompt/types";
+
+/** `BeforeTool` stdin payload (subset). */
+export interface GeminiHookInput {
+  tool_name?: string;
+  tool_input?: { command?: string; path?: string; content?: string };
+  hook_event_name?: string;
+}
+
+/** Hook stdout response. */
+export interface GeminiResponse {
+  decision?: "allow" | "deny";
+  reason?: string;
+  hookSpecificOutput?: { additionalContext?: string };
+}
+
+/** Evaluate a tool use; deny on a hard block, otherwise inject context. */
+export function beforeTool(input: GeminiHookInput): GeminiResponse {
+  const i = input.tool_input;
+  const r = evaluate({
+    tool: input.tool_name ?? "write_file",
+    filePath: i?.path,
+    content: i?.content,
+    command: i?.command,
+  });
+  if (r.decision === "allow" || !r.prompt) return {};
+  const msg = formatPrompt(r.prompt);
+  return r.prompt.kind === "block"
+    ? { decision: "deny", reason: msg }
+    : { hookSpecificOutput: { additionalContext: msg } };
+}

package/src/adapters/hermes/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Hermes Agent adapter (hook-mode). Nous Research's hermes-agent (2026) pipes a
+ * JSON payload to shell hooks on stdin and reads stdout back as JSON — config
+ * `~/.hermes/config.yaml` under `hooks:`, event `pre_tool_call`, scripts in
+ * `~/.hermes/agent-hooks/`. The INPUT shape matches Claude Code
+ * (`hook_event_name`/`tool_name`/`tool_input`/`cwd`), so the Claude reader is
+ * reused; the OUTPUT does not: a block is `{ decision: "block", reason }`
+ * (no `permissionDecision`, no interactive "ask"), `{}` allows, and
+ * `{ context }` injects LLM context. Tool fields verified: `terminal` takes
+ * `command`; `write_file` takes `path` + `content`.
+ */
+import { evaluate } from "../../policy/evaluate";
+import { formatPrompt, type Prompt } from "../../prompt/types";
+import { readClaudeInput } from "../claude";
+import { commandToString } from "../../runtime/command-string";
+import type { HermesHookInput, HermesResponse } from "./interfaces/types";
+
+export type { HermesHookInput, HermesResponse } from "./interfaces/types";
+
+/** Read & parse the Hermes hook stdin payload (same wire shape as Claude). */
+export async function readHermesInput(): Promise<HermesHookInput> {
+  return await readClaudeInput();
+}
+
+/**
+ * Render a portable {@link Prompt} as a Hermes hook response string:
+ * `block` -> `{decision:"block",reason}`; `ask`/`inform` -> non-blocking
+ * `{context}` — Hermes has no interactive "ask" state, so both degrade to
+ * context injection, mirroring the gemini-cli/cline routing in `respond()`.
+ * @param prompt - The portable policy prompt.
+ * @returns The native Hermes JSON response string.
+ */
+export function toHermesResponse(prompt: Prompt): string {
+  const msg = formatPrompt(prompt);
+  const res: HermesResponse = prompt.kind === "block" ? { decision: "block", reason: msg } : { context: msg };
+  return JSON.stringify(res);
+}
+
+/**
+ * Run the bundled policy over a Hermes `pre_tool_call` payload and return the
+ * native response string, or null to allow (the hook then prints `{}`).
+ * @param input - Parsed `pre_tool_call` stdin payload.
+ * @returns Native response JSON, or null when the tool use is allowed.
+ */
+export function guard(input: HermesHookInput): string | null {
+  const t = input.tool_input;
+  const r = evaluate({
+    tool: input.tool_name ?? "write_file",
+    filePath: t?.path ?? t?.file_path,
+    content: t?.content,
+    command: commandToString(t?.command),
+  });
+  if (r.decision === "allow" || !r.prompt) return null;
+  return toHermesResponse(r.prompt);
+}