@fusengine/harness 0.1.90 → 0.1.91

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

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

@@ -0,0 +1,26 @@
+/**
+ * Hermes Agent (NousResearch/hermes-agent) shell-hook wire types. Verified 2026
+ * against hermes-agent.nousresearch.com/docs/user-guide/features/hooks: hooks
+ * are configured in `~/.hermes/config.yaml` under `hooks:`, receive a JSON
+ * payload on stdin, and answer with JSON on stdout.
+ */
+
+/** `pre_tool_call` stdin payload (subset). Same wire shape as Claude Code. */
+export interface HermesHookInput {
+  hook_event_name?: string;
+  tool_name?: string;
+  tool_input?: { path?: string; file_path?: string; content?: string; command?: string | string[] };
+  session_id?: string;
+  cwd?: string;
+}
+
+/**
+ * Hook stdout response. `{}` allows; `{ decision: "block", reason }` cancels
+ * the tool call; `{ context }` injects LLM context (honored on `pre_llm_call`).
+ * Hermes has NO Claude-style `permissionDecision` and no interactive "ask".
+ */
+export interface HermesResponse {
+  decision?: "block";
+  reason?: string;
+  context?: string;
+}

package/src/adapters/kimi/index.ts

@@ -0,0 +1,96 @@
+/**
+ * Kimi Code CLI adapter (hook-mode). Moonshot AI's Kimi Code CLI (v0.27.0,
+ * 2026) configures hooks in `~/.kimi-code/config.toml` (`[[hooks]]`: event,
+ * matcher, command, timeout — exactly 4 fields, any extra breaks config
+ * loading) and pipes a JSON payload to `command` on stdin, reading JSON back
+ * on stdout. Verified against kimi.com/code/docs/en/kimi-code-cli/
+ * customization/hooks.html (2026): the INPUT base shape
+ * (`hook_event_name`/`session_id`/`cwd`, `PreToolUse`/`Bash` carrying
+ * `tool_name` + `tool_input.command`) matches Claude Code's snake_case wire
+ * shape, so the Claude reader is reused — verified live against kimi-code
+ * v0.27.0 for both `PreToolUse`/`Bash` and `PreToolUse`/`Write`. Tool fields
+ * verified: `Bash` takes `command`; `Write` takes `path` + `content`; `Edit`
+ * takes `path` + `old_string`/`new_string` (per `docs/en/reference/tools.md`,
+ * moonshotai/kimi-code). The path key is `path`, NOT Claude's `file_path`
+ * (see interfaces/types.ts).
+ *
+ * OUTPUT does not match Claude: only `UserPromptSubmit`, `PreToolUse`, `Stop`
+ * are blockable, and the only documented decision is
+ * `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason"}}`
+ * (camelCase, despite the snake_case input — a real Kimi inconsistency). No
+ * `"ask"`/`"allow"`/`additionalContext` is documented. Verified live against
+ * kimi-code v0.27.0: that deny envelope on stdout at exit 0 blocks the call
+ * (exit 2 is NOT required) and `permissionDecisionReason` is re-injected to
+ * the model; empty stdout at exit 0 lets the call run. Exit 2 = block, stderr
+ * = reason; any other exit/timeout/crash fails open (allow). Whether raw-text
+ * stdout at exit 0 (the `inform` case) reaches the context is documented only
+ * as "may be" — unverified, needs live test.
+ */
+import { evaluate } from "../../policy/evaluate";
+import { formatPrompt, type Prompt } from "../../prompt/types";
+import { readClaudeInput } from "../claude";
+import { commandToString } from "../../runtime/command-string";
+import type { KimiHookInput, KimiResponse } from "./interfaces/types";
+
+export type { KimiHookInput, KimiResponse } from "./interfaces/types";
+
+/**
+ * Downgrade prefix for `ask` — Kimi has no interactive approval channel
+ * reachable from a hook. Kimi DOES have an `ask` decision, but only via
+ * `[[permission.rules]] decision = "ask"` in config.toml, a separate system
+ * a hook's return value cannot invoke.
+ */
+const ASK_PREFIX = "[downgraded from ask — Kimi Code has no interactive approval]";
+
+/** Read & parse the Kimi hook stdin payload (same wire shape as Claude for the fields we consume). */
+export async function readKimiInput(): Promise<KimiHookInput> {
+  return await readClaudeInput();
+}
+
+/**
+ * Render a portable {@link Prompt} as a Kimi hook response string:
+ * `block`/`ask` -> `{hookSpecificOutput:{permissionDecision:"deny",...}}`
+ * (only `"deny"` is documented; `ask` is downgraded with {@link ASK_PREFIX});
+ * `inform` -> raw text (Kimi appends stdout to context on exit 0 — no
+ * documented JSON envelope for non-blocking context injection).
+ * @param prompt - The portable policy prompt.
+ * @returns The native Kimi response string.
+ */
+export function toKimiResponse(prompt: Prompt): string {
+  const msg = formatPrompt(prompt);
+  if (prompt.kind === "inform") return msg;
+  const reason = prompt.kind === "ask" ? `${ASK_PREFIX}\n${msg}` : msg;
+  const res: KimiResponse = { hookSpecificOutput: { permissionDecision: "deny", permissionDecisionReason: reason } };
+  return JSON.stringify(res);
+}
+
+/**
+ * Render a raw deny reason as a Kimi hook response — for callers that already
+ * hold a fully-formatted message (e.g. the MCP cache-hit notice) rather than a
+ * portable {@link Prompt}. Same envelope as {@link toKimiResponse}, minus the
+ * `[BLOCKED]` prompt framing and without `hookEventName` (undocumented upstream).
+ * @param reason - The fully-formatted deny message.
+ * @returns The native Kimi response string.
+ */
+export function kimiDenyResponse(reason: string): string {
+  const res: KimiResponse = { hookSpecificOutput: { permissionDecision: "deny", permissionDecisionReason: reason } };
+  return JSON.stringify(res);
+}
+
+/**
+ * Run the bundled policy over a Kimi hook payload and return the native
+ * response string, or null to allow (the hook then exits 0 with empty stdout).
+ * @param input - Parsed hook stdin payload.
+ * @returns Native response string, or null when the tool use is allowed.
+ */
+export function guard(input: KimiHookInput): string | null {
+  const t = input.tool_input;
+  const r = evaluate({
+    tool: input.tool_name ?? "Write",
+    filePath: t?.path ?? t?.file_path,
+    content: t?.content ?? t?.new_string,
+    command: commandToString(t?.command),
+  });
+  if (r.decision === "allow" || !r.prompt) return null;
+  return toKimiResponse(r.prompt);
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Kimi Code CLI shell-hook wire types. Verified 2026 against
+ * kimi.com/code/docs/en/kimi-code-cli/customization/hooks.html (v0.27.0):
+ * hooks are configured in `~/.kimi-code/config.toml` under `[[hooks]]`,
+ * receive a snake_case JSON payload on stdin, and answer with a camelCase
+ * JSON envelope on stdout (a real, documented casing inconsistency).
+ */
+
+/**
+ * `PreToolUse`/`UserPromptSubmit`/`Stop` stdin payload (subset). Same base
+ * wire shape as Claude Code (`hook_event_name`/`tool_name`/`tool_input`/
+ * `cwd`); `tool_input.command` is confirmed for `Bash` by the docs' example
+ * script (`payload.tool_input?.command`). Verified live against kimi-code
+ * v0.27.0 on `PreToolUse`/`Bash`: `tool_name` is present at top level (the
+ * docs never name it as a stdin key) and `tool_input.command` carries the
+ * shell string. The live payload also carries an UNDOCUMENTED `tool_call_id`
+ * (e.g. `"tool_LsTnl0gBxM62XuWvKw0GFGHs"`); the harness does not consume it,
+ * so it is deliberately absent from this interface. `cwd` is the
+ * symlink-resolved path (macOS: `/private/tmp/…` for a shell in `/tmp/…`).
+ */
+export interface KimiHookInput {
+  hook_event_name?: string;
+  tool_name?: string;
+  /**
+   * Verified against the official tool reference (`docs/en/reference/tools.md`,
+   * moonshotai/kimi-code) AND live against kimi-code v0.27.0: `Write` sends
+   * `{ path, content, mode? }`, `Edit` sends
+   * `{ path, old_string, new_string, replace_all? }` — the path key is `path`,
+   * NOT Claude's `file_path`. `file_path` is kept as a tolerated alias (read
+   * second) for Claude-shaped replay payloads, mirroring
+   * `runtime/normalize.ts` which resolves both on the CLI path.
+   */
+  tool_input?: {
+    path?: string;
+    file_path?: string;
+    content?: string;
+    new_string?: string;
+    command?: string | string[];
+  };
+  session_id?: string;
+  cwd?: string;
+}
+
+/**
+ * Hook stdout response. Only `"deny"` is documented for `permissionDecision`
+ * — no `"ask"`/`"allow"` value, and no `additionalContext` field exists on
+ * this envelope. Blocking events are `UserPromptSubmit`, `PreToolUse`, and
+ * `Stop` only; every other event's return value is ignored.
+ */
+export interface KimiResponse {
+  hookSpecificOutput?: {
+    permissionDecision?: "deny";
+    permissionDecisionReason?: string;
+  };
+}