@fusengine/harness 0.1.90 → 0.1.92

package/dist/runtime/index.d.mts

@@ -1,4 +1,4 @@
-import { t as Prompt } from "../types-C0-igRKr.mjs";
+import { t as Prompt } from "../types-Bh0jEF3_.mjs";
 import { t as RefMeta } from "../types-CY5qT2X1.mjs";
 import { t as AgentQuality } from "../session-state-D5gLr66m.mjs";
 //#region src/runtime/paths.d.ts
@@ -124,6 +124,12 @@ declare const TRIVIAL_BUDGET = 4;
  * {@link withDenyLoop} rewrite an identical retried deny (decision unchanged).
  */
 declare function gate(input: GateInput): Promise<Prompt | null>;
+/**
+ * Gate independent Cursor command candidates without merging their shell syntax.
+ * Stateful outcome bookkeeping runs once, against the command that decided the
+ * aggregate result. A single distinct candidate follows {@link gate} verbatim.
+ */
+declare function gateCommandCandidates(input: GateInput, candidates: readonly string[]): Promise<Prompt | null>;
 //#endregion
 //#region src/runtime/dry.d.ts
 /** Extract long (>12 char) declared symbol names from new file content. */
@@ -153,14 +159,17 @@ declare function dryGate(tool: string, filePath: string, content: string | undef
 declare function preCommitGate(tool: string, command: string | undefined, cwd: string | undefined): Prompt | null;
 //#endregion
 //#region src/runtime/normalize.d.ts
-/** One file fanned out of a multi-file edit primitive (Codex `apply_patch`). */
+/** One file/edit fanned out from Codex `apply_patch` or Cursor `afterFileEdit`. */
 interface NormalizedFile {
   filePath: string;
   content: string;
+  oldString?: string;
   op: "add" | "update" | "delete";
 }
 /** A hook event normalized across harnesses. */
 interface NormalizedEvent {
+  /** Native event name when the adapter exposes one explicitly (Cursor). */
+  eventName?: string;
   phase: "pre" | "post";
   tool: string;
   input: Record<string, unknown>;
@@ -170,22 +179,26 @@ interface NormalizedEvent {
   /** Edit only: the tool_input.old_string being replaced — lets the file-size gate (policy/evaluate.ts + policy/edit-outcome.ts) compute the post-edit outcome instead of judging the stale on-disk count alone. Undefined for Write (no such field) and for cline/apply_patch (parsed separately, no equivalent field). */
   oldString?: string;
   command?: string;
+  /** Cursor-only independent command candidates from beforeMCPExecution. */
+  commandCandidates?: string[];
   /** Subagent type, if the tool-use came from one (Explore/Plan are file-size-exempt). */
   agentType?: string;
   /** Harness-resolved permission mode (Claude emits it natively; Codex maps `AskForApproval::Never` to the same "bypassPermissions" string — see adapters/codex/permission-mode.ts). Generic field, Codex-only consumer today. */
   permissionMode?: string;
+  /** Codex logical tool-use identity, shared by sibling hook callbacks. */
+  toolUseId?: string;
+  /** Harness-reported working directory used to scope Codex authorization. */
+  cwd?: string;
+  /** Validated Cursor multi-root workspace paths in wire order. */
+  workspaceRoots?: string[];
   /**
-   * Per-file changes when the tool is a multi-file edit primitive (Codex
-   * `apply_patch`). Present ONLY for `apply_patch`; the file gates OR each
-   * entry's verdict so one violating hunk blocks the whole envelope. Left
-   * undefined for every other tool/harness (single-file `filePath`/`content`).
+   * Per-file changes for Codex `apply_patch` and per-edit changes for Cursor
+   * `afterFileEdit`; undefined for single-file events.
    */
   files?: NormalizedFile[];
 }
 /**
- * Normalize a harness hook payload into a uniform event. Handles Cline's nested
- * `preToolUse`/`postToolUse` shape and the top-level `tool_name`/`tool_input`
- * shape used by Claude, Codex, Gemini, and Cursor.
+ * Normalize a hook payload, including Cline nesting and native Cursor events.
  */
 declare function normalizeEvent(id: string, payload: Record<string, unknown>): NormalizedEvent;
 //#endregion
@@ -201,8 +214,8 @@ declare function normalizeEvent(id: string, payload: Record<string, unknown>): N
  * - gemini-cli/cline: their real hook schemas have no interactive "ask"
  *   state (deny is the only blocking outcome), so `ask` and `inform` already
  *   both resolve to non-blocking context injection — unchanged.
- * - cursor: `ask` keeps its current best-effort `permission:"ask"` shape;
- *   only `inform` is fixed to a non-blocking `permission:"allow"` note.
+ * - cursor: `ask` degrades to a native `permission:"deny"` because Cursor does
+ *   not reliably apply `ask` on `preToolUse`; `inform` stays non-blocking.
  * - hermes: delegated to the adapter's `toHermesResponse` — `block` ->
  *   `{decision:"block",reason}`; `ask`/`inform` degrade to non-blocking
  *   `{context}` (Hermes has no interactive "ask" state).
@@ -891,10 +904,18 @@ interface HandleOutcome {
 //#endregion
 //#region src/runtime/handle.d.ts
 /**
- * The full hook handler: on a PRE event it gates the tool-use (stateless guards
- * then APEX gates from the session track) and returns the native response; on a
- * POST event it records the activity into the track. The loop that makes the
- * package behave like the Claude plugin, on any harness.
+ * Run one hook and adapt every Cursor scope outcome at the common runtime exit.
+ * Other harnesses retain the core handler's stdout and exit status unchanged.
+ * Cursor's shared `additional_context` budget context (see
+ * `../adapters/cursor/context-budget.ts`) is assembled here too — this is
+ * the single point every Cursor stdout passes through exactly once, so it's
+ * also the single point that reserves from and records into the registry.
+ * With no `session_id`/`conversation_id` at all, `sessionId` is `""` — the
+ * registry key would degenerate to one bucket shared by every session-less
+ * call on the same (cwd, event) pair, so `budget` stays `undefined` instead
+ * (falls back to the flat per-response cap in `toCursorLifecycleResponse`,
+ * with zero registry I/O). `stateDir` honors `opts.home` (test-only OS home
+ * override, see `HandleOptions`) so tests never need the real `os.homedir()`.
  */
 declare function handleHook(id: string, payload: Record<string, unknown>, opts: HandleOptions): Promise<HandleOutcome>;
 //#endregion
@@ -923,4 +944,4 @@ interface PreContext {
  */
 declare function handlePre(ctx: PreContext): Promise<HandleOutcome>;
 //#endregion
-export { Activity, DEFAULT_WINDOW_MS, DuplicationVerdict, type GateInput, type HandleOptions, type HandleOutcome, LifecycleInput, MCP_TTL_MS, McpIntercept, NormalizedEvent, NormalizedFile, PluginScope, PreContext, REQUIRED_AGENTS, SolidProfile, TRIVIAL_BUDGET, ToolEvent, 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 { Activity, DEFAULT_WINDOW_MS, DuplicationVerdict, type GateInput, type HandleOptions, type HandleOutcome, LifecycleInput, MCP_TTL_MS, McpIntercept, NormalizedEvent, NormalizedFile, PluginScope, PreContext, REQUIRED_AGENTS, SolidProfile, TRIVIAL_BUDGET, ToolEvent, 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/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-BF1dZFjY.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.92",
 	"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";
+}