@fusengine/harness 0.1.90 → 0.1.91

package/dist/runtime/index.mjs

@@ -1,6 +1,6 @@
 import { r as projectLayout } from "../layout-KWoE_Mqn.mjs";
 import { a as sanitizeSessionId, c as sessionsDir, i as loadSessionState, n as fuseHarnessHome, o as saveSessionState, r as fusengineCache, s as sessionStatePath, t as claudeHome } from "../home-state-oUGFB4ds.mjs";
-import { A as trackMcpResearch, At as defaultStateDir, B as generateProjectMap, C as seoPostToolUse, Ct as trimLogFile, D as securityAdvisoryForPatch, Dt as claudeMdKey, E as securityAdvisory, Et as projectContext, F as dispatchAipilot, Ft as loadSecurityState, G as countFiles, H as writeTree, I as dispatchLessons, It as saveSecurityState, J as lessonsArchiveFileFor, K as getFileDesc, L as cartoSessionStart, Lt as securityStateDir, M as trackEnrichment, Mt as trackFile, N as dispatchLifecycle, Nt as normalizeEvent, O as postTrackingSideEffects, Ot as promptSubmitContext, P as aipilotPostToolUse, Pt as isoUtc, R as generateEcosystemMap, Rt as securityStatePath, S as postEditContext, St as removeOldFiles, T as dispatchMemory, Tt as gitContext, U as loadEnriched, V as isProject, W as mergeLines, X as lessonsStateFileFor, Y as lessonsFileFor, _ as preCommitGate, _t as readRules, a as recordActivity, at as saveApexState, b as extractSymbols, bt as pruneEmptyDirs, c as MCP_TTL_MS, ct as trackAgentMemory, d as isMcpTool, dt as validateSolidGate, f as queryOf, ft as checkFileSize, g as gate, gt as injectRules, h as TRIVIAL_BUDGET, ht as solidDetectStart, i as respond, it as cleanupSession, j as trackSkillRead, jt as projectHash, k as trackWatchResearch, kt as taskContext, l as WEBFETCH_TTL_MS, lt as subagentCacheContext, m as REQUIRED_AGENTS, mt as detectSolidProfile, n as activityFor, nt as trackSessionChanges, o as mcpPostStore, ot as logToolFailure, p as DEFAULT_WINDOW_MS, pt as countLoc, q as listChildren, r as handlePre, rt as validateRulesLoaded, s as mcpPreIntercept, st as validateTeammateOutput, t as handleHook, tt as postEditTypescript, u as cacheQueryOf, ut as validateTailwind, v as detectDuplication, vt as runSessionStartCleanups, w as seoPostToolUseResponse, wt as devContext, x as lifecycleStdout, xt as purgeTtlTree, y as dryGate, yt as sessionStartCore, z as writePluginMap, zt as todayUtc } from "../handle-CBaOcFZq.mjs";
+import { A as trackWatchResearch, At as taskContext, B as writePluginMap, Bt as todayUtc, C as postEditContext, Ct as removeOldFiles, D as securityAdvisory, Dt as projectContext, E as dispatchMemory, Et as gitContext, F as aipilotPostToolUse, Ft as isoUtc, G as mergeLines, H as isProject, I as dispatchAipilot, It as loadSecurityState, J as listChildren, K as countFiles, L as dispatchLessons, Lt as saveSecurityState, M as trackSkillRead, Mt as projectHash, N as trackEnrichment, Nt as trackFile, O as securityAdvisoryForPatch, Ot as claudeMdKey, P as dispatchLifecycle, Pt as normalizeEvent, R as cartoSessionStart, Rt as securityStateDir, S as lifecycleStdout, St as purgeTtlTree, T as seoPostToolUseResponse, Tt as devContext, U as writeTree, V as generateProjectMap, W as loadEnriched, X as lessonsFileFor, Y as lessonsArchiveFileFor, Z as lessonsStateFileFor, _ as gateCommandCandidates, _t as injectRules, a as recordActivity, at as cleanupSession, b as dryGate, bt as sessionStartCore, c as MCP_TTL_MS, ct as validateTeammateOutput, d as isMcpTool, dt as validateTailwind, f as queryOf, ft as validateSolidGate, g as gate, gt as solidDetectStart, h as TRIVIAL_BUDGET, ht as detectSolidProfile, i as respond, it as validateRulesLoaded, j as trackMcpResearch, jt as defaultStateDir, k as postTrackingSideEffects, kt as promptSubmitContext, l as WEBFETCH_TTL_MS, lt as trackAgentMemory, m as REQUIRED_AGENTS, mt as countLoc, n as activityFor, nt as postEditTypescript, o as mcpPostStore, ot as saveApexState, p as DEFAULT_WINDOW_MS, pt as checkFileSize, q as getFileDesc, r as handlePre, rt as trackSessionChanges, s as mcpPreIntercept, st as logToolFailure, t as handleHook, u as cacheQueryOf, ut as subagentCacheContext, v as preCommitGate, vt as readRules, w as seoPostToolUse, wt as trimLogFile, x as extractSymbols, xt as pruneEmptyDirs, y as detectDuplication, yt as runSessionStartCleanups, z as generateEcosystemMap, zt as securityStatePath } from "../handle-C43gA-Pr.mjs";
 //#region src/runtime/storage.ts
 /**
 * The project's single state dir (`<root>/.harness`) — neutral + harness-agnostic,
@@ -10,4 +10,4 @@ function harnessStateDir(root) {
 	return projectLayout(root).stateDir;
 }
 //#endregion
-export { DEFAULT_WINDOW_MS, MCP_TTL_MS, REQUIRED_AGENTS, TRIVIAL_BUDGET, WEBFETCH_TTL_MS, activityFor, aipilotPostToolUse, cacheQueryOf, cartoSessionStart, checkFileSize, claudeHome, claudeMdKey, cleanupSession, countFiles, countLoc, defaultStateDir, detectDuplication, detectSolidProfile, devContext, dispatchAipilot, dispatchLessons, dispatchLifecycle, dispatchMemory, dryGate, extractSymbols, fuseHarnessHome, fusengineCache, gate, generateEcosystemMap, generateProjectMap, getFileDesc, gitContext, handleHook, handlePre, harnessStateDir, injectRules, isMcpTool, isProject, isoUtc, lessonsArchiveFileFor, lessonsFileFor, lessonsStateFileFor, lifecycleStdout, listChildren, loadEnriched, loadSecurityState, loadSessionState, logToolFailure, mcpPostStore, mcpPreIntercept, mergeLines, normalizeEvent, postEditContext, postEditTypescript, postTrackingSideEffects, preCommitGate, projectContext, projectHash, promptSubmitContext, pruneEmptyDirs, purgeTtlTree, queryOf, readRules, recordActivity, removeOldFiles, respond, runSessionStartCleanups, sanitizeSessionId, saveApexState, saveSecurityState, saveSessionState, securityAdvisory, securityAdvisoryForPatch, securityStateDir, securityStatePath, seoPostToolUse, seoPostToolUseResponse, sessionStartCore, sessionStatePath, sessionsDir, solidDetectStart, subagentCacheContext, taskContext, todayUtc, trackAgentMemory, trackEnrichment, trackFile, trackMcpResearch, trackSessionChanges, trackSkillRead, trackWatchResearch, trimLogFile, validateRulesLoaded, validateSolidGate, validateTailwind, validateTeammateOutput, writePluginMap, writeTree };
+export { DEFAULT_WINDOW_MS, MCP_TTL_MS, REQUIRED_AGENTS, TRIVIAL_BUDGET, WEBFETCH_TTL_MS, activityFor, aipilotPostToolUse, cacheQueryOf, cartoSessionStart, checkFileSize, claudeHome, claudeMdKey, cleanupSession, countFiles, countLoc, defaultStateDir, detectDuplication, detectSolidProfile, devContext, dispatchAipilot, dispatchLessons, dispatchLifecycle, dispatchMemory, dryGate, extractSymbols, fuseHarnessHome, fusengineCache, gate, gateCommandCandidates, generateEcosystemMap, generateProjectMap, getFileDesc, gitContext, handleHook, handlePre, harnessStateDir, injectRules, isMcpTool, isProject, isoUtc, lessonsArchiveFileFor, lessonsFileFor, lessonsStateFileFor, lifecycleStdout, listChildren, loadEnriched, loadSecurityState, loadSessionState, logToolFailure, mcpPostStore, mcpPreIntercept, mergeLines, normalizeEvent, postEditContext, postEditTypescript, postTrackingSideEffects, preCommitGate, projectContext, projectHash, promptSubmitContext, pruneEmptyDirs, purgeTtlTree, queryOf, readRules, recordActivity, removeOldFiles, respond, runSessionStartCleanups, sanitizeSessionId, saveApexState, saveSecurityState, saveSessionState, securityAdvisory, securityAdvisoryForPatch, securityStateDir, securityStatePath, seoPostToolUse, seoPostToolUseResponse, sessionStartCore, sessionStatePath, sessionsDir, solidDetectStart, subagentCacheContext, taskContext, todayUtc, trackAgentMemory, trackEnrichment, trackFile, trackMcpResearch, trackSessionChanges, trackSkillRead, trackWatchResearch, trimLogFile, validateRulesLoaded, validateSolidGate, validateTailwind, validateTeammateOutput, writePluginMap, writeTree };

package/dist/{types-C0-igRKr.d.mts → types-Bh0jEF3_.d.mts}

@@ -8,6 +8,8 @@ type PromptKind = "ask" | "block" | "inform";
  */
 interface Prompt {
   kind: PromptKind;
+  /** Stable policy identifier for confirmation diagnostics. */
+  ruleId?: string;
   /** Short title, e.g. "SOLID file-size limit". */
   title: string;
   /** Why this fired. */

package/dist/{validate-DZFtAbLP.mjs → validate-KjZ1X9tH.mjs}

@@ -1,6 +1,6 @@
 import { a as resolveMaxLines, c as storeBudget, i as hookBudget } from "./limits-DG5pl-5s.mjs";
 import { l as ttlLabel, t as HOME_DIR } from "./dotenv-BLBkBTww.mjs";
-import { A as moduleAwarePath, S as isHooksPath, T as isStoresPath, _ as rolloutVerdict, at as DEV_KEYWORDS, it as maskCommentsOnly, nt as projectCaps, rt as maskCommentsAndStrings, tt as nearestManifestDir, x as isComponentsPath, y as declaresInterface } from "./evaluate-C1VSI5pb.mjs";
+import { A as moduleAwarePath, S as isHooksPath, T as isStoresPath, _ as rolloutVerdict, at as maskCommentsOnly, it as maskCommentsAndStrings, nt as nearestManifestDir, ot as DEV_KEYWORDS, rt as projectCaps, x as isComponentsPath, y as declaresInterface } from "./evaluate-CMiIqHeH.mjs";
 import { d as countFrameworkCodeLines, l as PLUGINS_DIR, u as SOLID_REF } from "./home-state-oUGFB4ds.mjs";
 import { r as isDocConsulted, t as formatDocDeny } from "./doc-helpers-CWZegVdR.mjs";
 import { t as routeReferences } from "./router-PKVNBHge.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fusengine/harness",
-	"version": "0.1.90",
+	"version": "0.1.91",
 	"description": "Harness-agnostic toolkit for AI coding agents: runtime harness detection (Claude Code, Codex, Cursor, Cline, Gemini, Aider...), pure policy core (env config, project/framework detection, SOLID/file-size limits, APEX freshness, guard patterns, portable prompts), cache, project memory, ref routing, state/locks, statusline, per-harness adapters (Claude/Cursor/Cline/Gemini) and a cli-mode harness-check binary. Bun-native, with a built dist for Node + bundlers.",
 	"type": "module",
 	"module": "src/index.ts",
@@ -121,6 +121,7 @@
 		}
 	},
 	"files": [
+		"src/**/*.ts",
 		"dist",
 		"assets",
 		"README.md",
@@ -138,7 +139,7 @@
 		"test": "bun test",
 		"sim": "bun test test/sim/",
 		"typecheck": "tsc --noEmit",
-		"docs:api": "typedoc",
+		"docs:api": "bun install --cwd tools/api-docs --frozen-lockfile && bun run --cwd tools/api-docs generate",
 		"build": "tsdown src/index.ts src/config/index.ts src/util/index.ts src/detect/index.ts src/policy/index.ts src/prompt/index.ts src/memory/index.ts src/cache/index.ts src/freshness/index.ts src/refs/index.ts src/statusline/index.ts src/cli/index.ts src/cli/bin.ts src/init/index.ts src/tracking/index.ts src/runtime/index.ts src/adapters/claude/index.ts src/adapters/codex/index.ts src/adapters/cursor/index.ts src/adapters/cline/index.ts src/adapters/gemini/index.ts src/adapters/hermes/index.ts src/adapters/kimi/index.ts --dts --format esm --clean --out-dir dist",
 		"prepublishOnly": "bun test && tsc --noEmit && bun run build"
 	},

package/src/adapters/claude/index.ts

@@ -0,0 +1,92 @@
+/** Claude Code adapter — the thin Claude-only shim over the portable policy core; reads the hook stdin payload and emits hookSpecificOutput responses. */
+import { evaluate } from "../../policy/evaluate";
+import { formatPrompt, type Prompt } from "../../prompt/types";
+import { readStdin } from "../../util/runtime-io";
+import { commandToString } from "../../runtime/command-string";
+
+/** Subset of the Claude Code hook stdin payload we consume. */
+export interface ClaudeHookInput {
+  hook_event_name?: string;
+  tool_name?: string;
+  tool_input?: { file_path?: string; content?: string; new_string?: string; command?: string | string[] };
+  cwd?: string;
+  /** Shared Claude/Codex hook field — Codex maps approval_policy=never to "bypassPermissions" (adapters/codex/permission-mode.ts). */ permission_mode?: string;
+}
+
+/** Read & parse the Claude hook payload from stdin (empty object on bad input). */
+export async function readClaudeInput(): Promise<ClaudeHookInput> {
+  const text = await readStdin();
+  if (!text.trim()) return {};
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return typeof parsed === "object" && parsed !== null ? (parsed as ClaudeHookInput) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** A `deny` hook response for a given event. PreToolUse-only field. */
+export function denyResponse(event: string, reason: string): string {
+  return JSON.stringify({
+    hookSpecificOutput: { hookEventName: event, permissionDecision: "deny", permissionDecisionReason: reason },
+  });
+}
+
+/**
+ * A PostToolUse (and Stop/UserPromptSubmit) `block` response: those events
+ * ignore `permissionDecision` (PreToolUse-only) and only honor the top-level
+ * `decision`/`reason` keys, which feed `reason` back to Claude.
+ */
+export function blockResponse(reason: string): string {
+  return JSON.stringify({ decision: "block", reason });
+}
+
+/** An `additionalContext` injection response. */
+export function contextResponse(event: string, text: string): string {
+  return JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: text } });
+}
+
+/** A raw `systemMessage` notice — shown to the user without blocking the tool. Mirrors the shared Python `hook_output.allow_pass`/`post_pass` convention. */
+export function systemMessage(text: string): string {
+  return JSON.stringify({ systemMessage: text });
+}
+
+/** An `inform` response with a user-visible notice (Python `allow_pass`/`post_pass` parity): a pure pass reuses {@link systemMessage} alone; with agent-facing `context` both channels merge in one JSON. */
+export function informResponse(event: string, notice: string, context: string): string {
+  if (!context) return systemMessage(notice);
+  return JSON.stringify({ systemMessage: notice, hookSpecificOutput: { hookEventName: event, additionalContext: context } });
+}
+
+/** Attach a `systemMessage`, MERGING it with any already present (`\n`-joined) instead of overwriting — several producers may each call this on the same stdout in one hook invocation. */
+export function attachSystemMessage(stdout: string, notice: string): string {
+  try {
+    const parsed = JSON.parse(stdout) as Record<string, unknown>, prev = typeof parsed.systemMessage === "string" ? parsed.systemMessage : "";
+    return JSON.stringify({ ...parsed, systemMessage: prev ? `${prev}\n${notice}` : notice });
+  } catch { return systemMessage(notice); }
+}
+
+/** Render a portable {@link Prompt} as a Claude Code hook response: `block` → deny, `ask` → interactive `permissionDecision`, `inform` → `additionalContext` (+ `systemMessage` when `userMessage` is set). */
+export function toClaudeResponse(event: string, prompt: Prompt): string {
+  const reason = formatPrompt(prompt);
+  if (prompt.kind === "block") return denyResponse(event, reason);
+  if (prompt.kind === "ask") {
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: event, permissionDecision: "ask", permissionDecisionReason: reason } });
+  }
+  if (prompt.userMessage) return informResponse(event, prompt.userMessage, prompt.reason ? reason : "");
+  return contextResponse(event, reason);
+}
+
+/** Run the bundled policy over a Claude payload and return the native response string (deny/ask/additionalContext), or null to allow. */
+export function guard(input: ClaudeHookInput): string | null {
+  const result = evaluate({
+    tool: input.tool_name ?? "Write",
+    filePath: input.tool_input?.file_path,
+    content: input.tool_input?.content ?? input.tool_input?.new_string,
+    command: commandToString(input.tool_input?.command),
+  });
+  if (result.decision === "allow" || !result.prompt) return null;
+  return toClaudeResponse(input.hook_event_name ?? "PreToolUse", result.prompt);
+}
+
+/** @deprecated use {@link guard}. Kept for back-compat. */
+export const fileSizeGuard: typeof guard = guard;

package/src/adapters/cline/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Cline adapter (hook-mode). Schema per docs.cline.bot / .clinerules/hooks (2026):
+ * `PreToolUse` blocks via `{ cancel: true }`; it cannot modify tool parameters.
+ */
+import { evaluate } from "../../policy/evaluate";
+import { formatPrompt } from "../../prompt/types";
+
+/** `PreToolUse` stdin payload (subset). */
+export interface ClineHookInput {
+  hookName?: string;
+  preToolUse?: {
+    toolName?: string;
+    parameters?: { path?: string; content?: string; command?: string };
+  };
+}
+
+/** Hook stdout response. */
+export interface ClineResponse {
+  cancel?: boolean;
+  errorMessage?: string;
+  contextModification?: string;
+}
+
+/** Evaluate a tool use; cancel on a hard block, otherwise inject context. */
+export function preToolUse(input: ClineHookInput): ClineResponse {
+  const t = input.preToolUse;
+  const r = evaluate({
+    tool: t?.toolName ?? "write_to_file",
+    filePath: t?.parameters?.path,
+    content: t?.parameters?.content,
+    command: t?.parameters?.command,
+  });
+  if (r.decision === "allow" || !r.prompt) return {};
+  const msg = formatPrompt(r.prompt);
+  return r.prompt.kind === "block" ? { cancel: true, errorMessage: msg } : { contextModification: msg };
+}

package/src/adapters/codex/apply-patch.ts

@@ -0,0 +1,94 @@
+/**
+ * Parser for Codex's freeform `apply_patch` tool payload — the platform's PRIMARY
+ * edit primitive. The PreToolUse hook delivers `tool_name: "apply_patch"` with
+ * `tool_input: { command: <raw patch text> }` (verified in the Codex source:
+ * `core/src/tools/handlers/apply_patch.rs::pre_tool_use_payload`, which emits
+ * `json!({ "command": <freeform patch> })`). The grammar is the official
+ * apply-patch Lark spec (`apply-patch/src/parser.rs`): a single patch envelope
+ * can carry MULTIPLE files.
+ *
+ * Content precision (for the file-size / DRY gates that key off `content`):
+ * - Add File: EXACT — every `+` line is the new file verbatim.
+ * - Update File: APPROXIMATE — only the hunk "new side" (context ` ` + added `+`
+ *   lines) is reconstructed, not the full post-edit file. It is a lower bound on
+ *   the file's size (callers pair it with the on-disk count for oversized-file
+ *   edits), never the exact result.
+ * - Delete File: no content (empty).
+ */
+
+/** One file touched by an apply_patch envelope. */
+export interface PatchedFile {
+  path: string;
+  content: string;
+  op: "add" | "update" | "delete";
+}
+
+const BEGIN = "*** Begin Patch";
+const END = "*** End Patch";
+const ADD = "*** Add File: ";
+const DEL = "*** Delete File: ";
+const UPD = "*** Update File: ";
+const MOVE = "*** Move to: ";
+const EOF = "*** End of File";
+const ENV = "*** Environment ID: ";
+
+/**
+ * Parse a Codex freeform patch into its per-file changes. Lenient on whitespace
+ * around structural markers (as Codex's own parser is); returns `[]` when no
+ * recognizable hunk is present (malformed input fails open, not closed).
+ * @param text - Raw patch body from `tool_input.command`.
+ * @returns One {@link PatchedFile} per Add/Update/Delete hunk, in order.
+ */
+export function parseApplyPatch(text: string): PatchedFile[] {
+  const files: PatchedFile[] = [];
+  let cur: PatchedFile | null = null;
+  let buf: string[] = [];
+  const flush = (): void => {
+    if (cur) {
+      cur.content = buf.join("\n");
+      files.push(cur);
+    }
+    cur = null;
+    buf = [];
+  };
+  for (const line of text.split("\n")) {
+    const marker = line.trimStart();
+    if (marker === BEGIN || marker.startsWith(ENV)) continue;
+    if (marker === END) {
+      flush();
+      continue;
+    }
+    if (marker.startsWith(ADD)) {
+      flush();
+      cur = { path: marker.slice(ADD.length).trim(), content: "", op: "add" };
+      continue;
+    }
+    if (marker.startsWith(DEL)) {
+      flush();
+      files.push({ path: marker.slice(DEL.length).trim(), content: "", op: "delete" });
+      continue;
+    }
+    if (marker.startsWith(UPD)) {
+      flush();
+      cur = { path: marker.slice(UPD.length).trim(), content: "", op: "update" };
+      continue;
+    }
+    if (marker.startsWith(MOVE)) {
+      if (cur) cur.path = marker.slice(MOVE.length).trim();
+      continue;
+    }
+    if (marker === EOF || !cur) continue;
+    if (cur.op === "add") {
+      if (line.startsWith("+")) buf.push(line.slice(1));
+      continue;
+    }
+    // Update hunk: keep the "new side" (added `+` + context ` `), drop removed `-`
+    // and `@@` chunk headers.
+    if (line.startsWith("@@")) continue;
+    if (line.startsWith("+")) buf.push(line.slice(1));
+    else if (line.startsWith("-")) continue;
+    else buf.push(line.startsWith(" ") ? line.slice(1) : line);
+  }
+  flush();
+  return files;
+}

package/src/adapters/codex/index.ts

@@ -0,0 +1,84 @@
+/**
+ * OpenAI Codex CLI adapter (hook-mode). Codex's `PreToolUse` hook (since 2026)
+ * uses the SAME envelope as Claude Code — `tool_name`/`tool_input` in,
+ * `hookSpecificOutput.permissionDecision` out — so it shares Claude's readers.
+ * Config lives at `.codex/hooks.json`.
+ *
+ * Two Codex-specific quirks this adapter closes (audit 2026-07-06):
+ * 1. `apply_patch` is Codex's PRIMARY edit primitive; its payload is a freeform
+ *    patch in `tool_input.command`, with NO `file_path`/`content`. Claude's guard
+ *    keyed off those fields, so the SOLID/DRY gates saw NOTHING (enforcement 0%).
+ *    Here the patch is parsed and each file is judged (one violating hunk denies).
+ * 2. Codex parses but NEVER honors `permissionDecision: "ask"` (deny-only) — an
+ *    `ask` silently fails open (verified: `pre_tool_use.rs` test
+ *    `unsupported_permission_decision_fails_open`). Every `ask` is downgraded to
+ *    an explicit deny.
+ */
+import { evaluate } from "../../policy/evaluate";
+import { countLines } from "../../policy/file-size";
+import { formatPrompt, type Prompt } from "../../prompt/types";
+import { parseApplyPatch } from "./apply-patch";
+import { commandToString } from "../../runtime/command-string";
+import { canonicalizeCodexShellTool } from "../../runtime/codex-shell-tool";
+import { canonicalizeMcpToolName } from "../../runtime/mcp-tool-name";
+import { contextResponse, denyResponse, informResponse, type ClaudeHookInput } from "../claude";
+import { isBypassPermissions } from "./permission-mode";
+
+export { readClaudeInput as readCodexInput, denyResponse, contextResponse, informResponse, type ClaudeHookInput as CodexHookInput } from "../claude";
+
+const ASK_PREFIX = "[downgraded from ask — Codex has no interactive approval]";
+
+/**
+ * Render a portable {@link Prompt} as a Codex hook response, `ask` → explicit deny.
+ * NOTE: the REAL wired route is `harness hook codex` → handleHook → respond.ts
+ * (source of truth for the ask→deny downgrade); this thin export exists for
+ * direct package consumers and is kept aligned so it never silently diverges.
+ */
+export function toCodexResponse(prompt: Prompt): string {
+  const message = formatPrompt(prompt);
+  if (prompt.kind === "inform") {
+    return prompt.userMessage ? informResponse("PreToolUse", prompt.userMessage, prompt.reason ? message : "") : contextResponse("PreToolUse", message);
+  }
+  if (prompt.kind === "ask") return denyResponse("PreToolUse", `${ASK_PREFIX}\n${message}`);
+  return denyResponse("PreToolUse", message);
+}
+
+/** OR the per-file SOLID verdict of an `apply_patch` payload — first block wins. */
+function applyPatchPrompt(command: string): Prompt | null {
+  for (const f of parseApplyPatch(command)) {
+    if (f.op === "delete") continue;
+    const tool = f.op === "add" ? "Write" : "Edit";
+    const r = evaluate({ tool, filePath: f.path, content: f.content, existingLines: countLines(f.content) });
+    if (r.decision !== "allow" && r.prompt) return r.prompt;
+  }
+  return null;
+}
+
+/** Portable single-tool verdict for non-`apply_patch` Codex tools. */
+function resolvePrompt(input: ClaudeHookInput): Prompt | null {
+  const i = input.tool_input;
+  const r = evaluate({
+    // Code Mode-wrapped exec_command surfaces its raw function-tool name here
+    // instead of "Bash" (see codex-shell-tool.ts) — canonicalize so the SOLID/
+    // protected-path/bash-write guards recognize it like a native Bash call.
+    tool: canonicalizeCodexShellTool("codex", canonicalizeMcpToolName("codex", input.tool_name ?? "Write")),
+    filePath: i?.file_path,
+    content: i?.content ?? i?.new_string,
+    command: commandToString(i?.command),
+    neverApproval: isBypassPermissions(input.permission_mode),
+  });
+  return r.decision === "allow" || !r.prompt ? null : r.prompt;
+}
+
+/**
+ * Run the bundled policy over a Codex payload and return the native response
+ * string (deny/additionalContext), or null to allow. `apply_patch` is fanned
+ * into per-file checks; every other tool routes through the portable policy.
+ */
+export function guard(input: ClaudeHookInput): string | null {
+  const prompt =
+    input.tool_name === "apply_patch"
+      ? applyPatchPrompt(commandToString(input.tool_input?.command) ?? "")
+      : resolvePrompt(input);
+  return prompt ? toCodexResponse(prompt) : null;
+}

package/src/adapters/codex/permission-mode.ts

@@ -0,0 +1,16 @@
+/**
+ * Codex maps `AskForApproval::Never` -> `permission_mode: "bypassPermissions"`
+ * in its hook payload (codex-rs/core/src/hook_runtime.rs::hook_permission_mode)
+ * — the only value that isolates `never`; the other three approval policies
+ * (`untrusted`, `on-failure`, `on-request`) all collapse to `"default"`.
+ * Verified at openai/codex@342e4d4b, hook_runtime.rs run_pre_tool_use_hooks +
+ * pre_tool_use.rs PreToolUseRequest. Undocumented implementation detail, not
+ * a public contract — see the mapping-regression test that pins this string.
+ * @param permissionMode - The payload's `permission_mode` field, if present.
+ * @returns True only on an EXACT match — fail-closed. A near-miss
+ * (`"BypassPermissions"`, `"bypassPermissions "`, or a substring match) must
+ * never accidentally grant the neverApproval exemption.
+ */
+export function isBypassPermissions(permissionMode: string | undefined): boolean {
+  return permissionMode === "bypassPermissions";
+}

package/src/adapters/cursor/context.ts

@@ -0,0 +1,46 @@
+import { isAbsolute, normalize, relative } from "node:path";
+import { realpathSync } from "node:fs";
+
+/** Preserve a Cursor path value only when it is non-empty and NUL-free. */
+export function cursorPath(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 && !value.includes("\0") ? value : undefined;
+}
+
+/** Validate and normalize an absolute path supplied by Cursor. */
+export function cursorAbsolutePath(value: unknown): string | undefined {
+  const candidate = cursorPath(value);
+  if (!candidate || !isAbsolute(candidate)) return undefined;
+  const path = normalize(candidate);
+  try {
+    return realpathSync.native(path);
+  } catch {
+    return path;
+  }
+}
+
+/** Preserve distinct, validated Cursor workspace roots in wire order. */
+export function cursorWorkspaceRoots(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const roots = value.map(cursorAbsolutePath).filter((root): root is string => root !== undefined);
+  return [...new Set(roots)];
+}
+
+function contains(root: string, filePath: string): boolean {
+  const rel = relative(root, filePath);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/** Select Cursor's project scope without replacing a valid payload cwd. */
+export function cursorProjectCwd(
+  cwd: string | undefined,
+  workspaceRoots: readonly string[],
+  filePath: string | undefined,
+  fallback: string,
+): string {
+  if (cwd) return cwd;
+  if (filePath) {
+    const matches = workspaceRoots.filter((root) => contains(root, filePath));
+    if (matches.length > 0) return matches.sort((a, b) => b.length - a.length)[0]!;
+  }
+  return workspaceRoots[0] ?? fallback;
+}

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